feat(ui): Surface 加受控槽与只出边框档

Author: Aparencia

app/src/ui/primitives/Surface.css

@@ -38,6 +38,14 @@
 .ed-surface--surface { background: var(--ed-bg-surface); } /* 卡片 / 列 / 阅读面（= 基类，显式写出让四档对称） */
 .ed-surface--raised { background: var(--ed-bg-raised); box-shadow: var(--ed-shadow-1); } /* 弹层 / 菜单 / 浮窗 */
 
+/* 第五档底 `none`（批 7 T7 的「只出边框」档）：**明确声明不出底** —— `transparent` 就是
+   `background` 的初始值，与迁移前「style 里根本不写 background」逐字同义。
+   Why 需要它：基类必出 `--ed-bg-surface`，而仓里有一批「整圈边框 + 无底色」的透明容器
+   （批 4 B11 的 `no-background` 残留，批 7 T7 实测 21 处）—— 没有本档就只能留在行内 style 里。
+   ⚠️ 本档**不是**第五种底色，也不能反过来当「继承父层底」用：它就是不出底。
+   规则写在四档之后 ⇒ 同特异性下后者胜，基类的 `background` 被本档覆盖。 */
+.ed-surface--none { background: transparent; }
+
 /* 五档圆角：前四档的 token 真源是 `SCALE_TOKENS.radiusScale`（3/5/8/10），类名带 `r-` 前缀以免与
    同名的 level 档（如 `--surface`）撞在一起。
 

app/src/ui/primitives/Surface.test.tsx

@@ -23,7 +23,7 @@ import { Surface } from "./index";
 import type { SurfaceLevel, SurfaceRadius, SurfaceTag } from "./index";
 
 /** 契约名单：与 `Surface.css` 的规则一一对应（改名单必须同时改 CSS 与测试） */
-const LEVELS: readonly SurfaceLevel[] = ["sunken", "canvas", "surface", "raised"];
+const LEVELS: readonly SurfaceLevel[] = ["sunken", "canvas", "surface", "raised", "none"];
 const RADIUS: readonly SurfaceRadius[] = ["stamp", "control", "panel", "overlay", "pill"];
 const TAGS: ReadonlyArray<readonly [SurfaceTag, string]> = [
   ["div", "DIV"], ["section", "SECTION"], ["article", "ARTICLE"], ["aside", "ASIDE"], ["li", "LI"],
@@ -61,7 +61,7 @@ describe("Surface 默认契约", () => {
 });
 
 describe("Surface 四档底 / 五档圆角映射到类", () => {
-  it("4 档 level 各有对应类（sunken 输入槽 · canvas 纸 · surface 卡面 · raised 弹层）", () => {
+  it("5 档 level 各有对应类（sunken 输入槽 · canvas 纸 · surface 卡面 · raised 弹层 · none 只出边框）", () => {
     for (const level of LEVELS) {
       const cls = classesOf(render(<Surface level={level}>x</Surface>).container);
       expect(cls, `档位 ${level}`).toContain(`ed-surface--${level}`);
@@ -154,6 +154,35 @@ describe("Surface 语义与透传", () => {
   });
 });
 
+describe("Surface 受控槽（批 7 T7：`html` / `domId` —— 只开属性级的两个口，**不开 `...rest`**）", () => {
+  it("`html` 走 `dangerouslySetInnerHTML`：宿主的 innerHTML 含该串，且**不**渲染 children", () => {
+    const { container } = render(<Surface html={'<p class="x">已渲染串</p>'} />);
+    expect(root(container).innerHTML).toBe('<p class="x">已渲染串</p>');
+    expect(root(container).querySelector("p")?.className).toBe("x");
+  });
+
+  it("`html` 与面本身的正交性：类名/圆角档照旧，`html` 不吞掉面的契约", () => {
+    const cls = classesOf(render(<Surface level="none" radius="panel" html="<b>k</b>" />).container);
+    expect(cls).toContain("ed-surface--none");
+    expect(cls).toContain("ed-surface--r-panel");
+  });
+
+  it("`domId` 落到宿主的 `id` ⇒ `document.getElementById` 找得到（锚点跳转的落点）", () => {
+    render(<Surface domId="anchor-x">x</Surface>);
+    expect(document.getElementById("anchor-x")?.textContent).toBe("x");
+  });
+
+  it("`domId` 不给时不产生 `id` 属性（不留 `id=\"undefined\"`）", () => {
+    expect(root(render(<Surface>x</Surface>).container).hasAttribute("id")).toBe(false);
+  });
+
+  it("反例守门：`...rest` 没开 —— 未知属性既不被解构也不被渲染（编译期那一半由 tsc 探针 V2 守）", () => {
+    const stray = { "data-foo": "1" };
+    const { container } = render(<Surface {...stray}>x</Surface>);
+    expect(root(container).hasAttribute("data-foo")).toBe(false);
+  });
+});
+
 describe("Surface 反例守门（批 6 要一处改对所有地方）", () => {
   it("底 / 边框 / 圆角 / 阴影 / 内边距 / 位移**只走类**，绝不落内联 style", () => {
     const el = root(

app/src/ui/primitives/Surface.tsx

@@ -27,8 +27,11 @@
 import type { CSSProperties, ReactElement, ReactNode } from "react";
 import "./Surface.css";
 
-/** 四档底，与 `COLOR_TOKENS` 的 `bg-*` 四个颜色 token 一一对应（值只在 `ui/tokens.css`） */
-export type SurfaceLevel = "sunken" | "canvas" | "surface" | "raised";
+/** 底档：四档与 `COLOR_TOKENS` 的 `bg-*` 四个颜色 token 一一对应（值只在 `ui/tokens.css`）；
+ *  第五档 `none` 是**批 7 T7 的「只出边框」档** —— 它不是第五种底色，而是**明确声明不出底**
+ *  （`background: transparent` = 迁移前「不写 background」的逐字同义），供「整圈边框 + 无底色」的
+ *  透明容器落进原语（批 4 B11 的 `no-background` 残留：`Surface` 基类必出底色）。 */
+export type SurfaceLevel = "sunken" | "canvas" | "surface" | "raised" | "none";
 
 /** 五档圆角：四档与 `SCALE_TOKENS.radiusScale` 同序（3 / 5 / 8 / 10px），第五档 `pill` 是批 4 T17 加的**药丸**形态
  *  （`radiusScale` 里还没有它 ⇒ `Surface.css` 的该档走 `var(--ed-radius-pill, 999px)` 兜底；补 token 见彼处注释） */
@@ -37,8 +40,9 @@ export type SurfaceRadius = "stamp" | "control" | "panel" | "overlay" | "pill";
 /** 可渲染的语义标签（不含 `button` / `a` —— 可交互元素属 `Button` 与调用点） */
 export type SurfaceTag = "div" | "section" | "article" | "aside" | "li";
 
-export interface SurfaceProps {
-  /** 底色档位，默认 `surface`（卡片 / 列 / 阅读面） */
+/** 面的**自有属性**（不含内容面 —— 内容的二选一由 `SurfaceProps` 的联合表达） */
+interface SurfaceOwnProps {
+  /** 底色档位，默认 `surface`（卡片 / 列 / 阅读面）；`none` = **只出边框、不出底色**（批 7 T7） */
   level?: SurfaceLevel;
   /** 圆角档位，默认 `panel`（8px） */
   radius?: SurfaceRadius;
@@ -56,9 +60,30 @@ export interface SurfaceProps {
   style?: CSSProperties;
   /** 落到 `data-testid`；不传时不产生该属性 */
   testId?: string;
-  children: ReactNode;
+  /**
+   * **受控槽**：宿主元素的 `id`（供锚点跳转，如 `SessionScreenCards` 的 `ocr-<会话>-<ms>`）。
+   * Why 用受控槽而不是 `...rest`：`Surface` 是「面」的唯一出口，DOM 属性面一旦放开就再也收不回
+   * （ADR-033 §4 + 批 7 §C9.4 的裁决）—— 只把**已点名的**两个属性开口。
+   */
+  domId?: string;
 }
 
+/**
+ * `Surface` 的属性。**内容面是联合类型**：`children`（常规）与 `html`（受控槽，走
+ * `dangerouslySetInnerHTML`）**互斥** —— 两者都给 = TS2353/TS2322，不是运行期才炸。
+ */
+export type SurfaceProps =
+  | (SurfaceOwnProps & {
+      readonly children: ReactNode;
+      /** 受控槽：把**已渲染的 HTML 串**交给 `dangerouslySetInnerHTML`（与 `children` 互斥） */
+      readonly html?: never;
+    })
+  | (SurfaceOwnProps & {
+      readonly children?: never;
+      /** 受控槽：把**已渲染的 HTML 串**交给 `dangerouslySetInnerHTML`（与 `children` 互斥） */
+      readonly html: string;
+    });
+
 /**
  * 渲染一个「面」。
  *
@@ -75,6 +100,8 @@ export function Surface({
   className,
   style,
   testId,
+  domId,
+  html,
   children,
 }: SurfaceProps): ReactElement {
   const cls = [
@@ -90,8 +117,16 @@ export function Surface({
     .join(" ");
 
   const Tag = as;
+  // 两个内容分支**分开写**：`children` 与 `dangerouslySetInnerHTML` 同时出现会被 React 抛错，
+  // 而联合类型已在编译期禁止「两者都给」；分开写让「运行期只可能走一支」一眼可见。
+  if (html !== undefined) {
+    return (
+      <Tag className={cls} style={style} data-testid={testId} id={domId}
+        dangerouslySetInnerHTML={{ __html: html }} />
+    );
+  }
   return (
-    <Tag className={cls} style={style} data-testid={testId}>
+    <Tag className={cls} style={style} data-testid={testId} id={domId}>
       {children}
     </Tag>
   );

app/src/ui/primitives/style-contract.test.ts

@@ -104,6 +104,8 @@ const LEVEL_CLASS: Record<SurfaceLevel, string> = {
   canvas: "ed-surface--canvas",
   surface: "ed-surface--surface",
   raised: "ed-surface--raised",
+  // 批 7 T7：「只出边框」档（透明边框容器的落点）⇒ 底档 4 → 5
+  none: "ed-surface--none",
 };
 const RADIUS_CLASS: Record<SurfaceRadius, string> = {
   stamp: "ed-surface--r-stamp",
@@ -163,7 +165,7 @@ const CONTRACTS: readonly UnionContract[] = [
   { union: "TextTone", css: "Text.css", members: TONE_CLASS, expected: 9 },
   { union: "TextSize", css: "Text.css", members: SIZE_CLASS, expected: 6 },
   { union: "TextFont", css: "Text.css", members: FONT_CLASS, expected: 3 },
-  { union: "SurfaceLevel", css: "Surface.css", members: LEVEL_CLASS, expected: 4 },
+  { union: "SurfaceLevel", css: "Surface.css", members: LEVEL_CLASS, expected: 5 },
   { union: "SurfaceRadius", css: "Surface.css", members: RADIUS_CLASS, expected: 5 },
   { union: "ButtonVariant", css: "Button.css", members: VARIANT_CLASS, expected: 3 },
   { union: "ButtonSize", css: "Button.css", members: BTN_SIZE_CLASS, expected: 3 },

app/src/ui/primitives/style-seams.test.ts

@@ -88,11 +88,11 @@ describe("Text 类名 ↔ CSS 规则一致（类名拼错 = 静默无样式）",
   });
 });
 
-/** `Surface.tsx` 产出的 13 个类名（与 `Surface.test.tsx` 的名单同源） */
+/** `Surface.tsx` 产出的 14 个类名（与 `Surface.test.tsx` 的名单同源） */
 const SURFACE_CLASSES: readonly string[] = [
   "ed-surface",
-  ...["sunken", "canvas", "surface", "raised"].map((l) => `ed-surface--${l}`),
-  // 批 4 T17：`pill` 是 B17 第 2 条加的药丸档（切片内 `borderRadius: 999` 实测 3 处 ⇒ ≥3）⇒ 12 → 13
+  // 批 7 T7：底档第五档 `none`（只出边框）⇒ 13 → 14；批 4 T17：`pill` 药丸档（切片内 `borderRadius: 999` 实测 3 处 ⇒ ≥3）⇒ 12 → 13
+  ...["sunken", "canvas", "surface", "raised", "none"].map((l) => `ed-surface--${l}`),
   ...["stamp", "control", "panel", "overlay", "pill"].map((r) => `ed-surface--r-${r}`),
   "ed-surface--bordered",
   "ed-surface--interactive",
@@ -118,7 +118,7 @@ describe("Surface 盒子契约（控制方 2026-09-11 裁决 · 类名 ↔ CSS 
 
   it("Surface.tsx 产出的每个类在 Surface.css 里都有规则；且零颜色字面量、无 z-index", () => {
     const clean = stripComments(SURFACE_CSS);
-    expect(SURFACE_CLASSES).toHaveLength(13);
+    expect(SURFACE_CLASSES).toHaveLength(14);
     for (const cls of SURFACE_CLASSES) {
       expect(clean, `Surface.css 缺少 .${cls} 的规则`).toContain(`.${cls} {`);
     }