@dsh-workbench/shared 0.3.4 → 0.3.6

package/src/components/Form.tsx

@@ -0,0 +1,78 @@
+import { h, useEffect, useRef, useState } from '../lib/react.js';
+import type { FormProps } from './FormTypes.js';
+import { FormActions } from './FormActions.js';
+import { FormRows } from './FormRows.js';
+import { Note } from './Note.js';
+import {
+  formActionsOf,
+  formProblemsOf,
+  formRowsOf,
+  formSubmitOf,
+  reportDuplicateKeys,
+  visibleFieldsOf,
+} from './FormNodes.js';
+import { revealFirstProblem } from '../lib/form-problem.js';
+import './Form.css';
+
+/**
+ * 整张表单：`fields` 进，行、错误、操作区、（被挡住的）提交都由它安排 —— 它自己一个值都不存，
+ * 值仍归调用点的 model（`value` 只读给校验看）。
+ * 还没提交过时一格错都不显示；第一次提交之后每次渲染重算，改好了当场消。
+ * 提交那一拍永远先算一遍：有错就不调 `onSubmit`，并把第一个有错的 `FormRow` 带进视口、聚焦它里面的控件。
+ * 回车与点提交钮走的是同一条路：真 `<form>` 的隐式提交在**只有一个文本框**时也会 fire，所以 `busy` / `disabled` 时回车同样不提交。
+ * 调用点只管数据与语义：行怎么排、错误摆哪、什么时候校验、按钮在哪，这里没有口子。
+ * @param props.fields - 每格的键 / 标签 / 值 / 校验 / 控件；`visible: false` 的那格当它不存在（不渲染、不校验、不进 `values`）。
+ * @param props.onSubmit - 校验全过的那一拍，回的是从 `fields` 现取的键值表；被挡住时不会被调。
+ * @param props.submit - 提交钮文案；`busyLabel` 是提交中换的那句，不给就沿用 `label`。
+ * @param props.cancel - 取消钮；给了就排在提交钮左边，`busy` 时一起禁用。
+ * @param props.extra - 其余动作（default / danger），排在最左，`busy` 时一起禁用。
+ * @param props.busy - 提交中（默认 false）：整表控件的绑定 `disabled` 为真，所有动作一起禁用，回车也不提交。
+ * @param props.disabled - 只再禁提交钮（如没改动可存），各格控件与其余动作不受影响，回车也不提交。
+ * @param props.problem - 整表级那句错（提交失败），落在行与操作区之间；不给就不画。
+ * @returns 一个 `<form>`（`noValidate`：报错形状归 `FormRow`，不走浏览器的气泡）。
+ */
+export function Form(props: FormProps) {
+  const { fields, onSubmit, submit, cancel, extra, busy = false, disabled = false, problem } = props;
+  const [done, setDone] = useState(false);
+  const [reveal, setReveal] = useState(0);
+  const rootRef = useRef<HTMLFormElement | null>(null);
+  const shown = visibleFieldsOf(fields);
+  const problems = formProblemsOf(shown, done);
+
+  reportDuplicateKeys(shown);
+
+  useEffect(() => {
+    if (reveal === 0) return;
+    const root = rootRef.current;
+    if (root !== null) revealFirstProblem(root);
+  }, [reveal]);
+
+  const submitForm = (): void => {
+    if (busy || disabled) return;
+    const outcome = formSubmitOf(visibleFieldsOf(fields));
+    setDone(true);
+    if (outcome.blocked) {
+      setReveal((count) => count + 1);
+      return;
+    }
+    onSubmit(outcome.values);
+  };
+
+  return (
+    <form
+      className="wb-form"
+      ref={rootRef}
+      noValidate
+      onSubmit={(event) => {
+        event.preventDefault();
+        submitForm();
+      }}
+    >
+      <FormRows>{formRowsOf({ fields: shown, problems, showProblem: done, busy })}</FormRows>
+      {problem === undefined ? null : h(Note, { tone: 'problem', role: 'alert' }, problem)}
+      <FormActions
+        actions={formActionsOf({ extra, cancel, submit, busy, disabled, onSubmitClick: submitForm })}
+      />
+    </form>
+  );
+}

package/src/components/FormActions.tsx

@@ -4,8 +4,14 @@ import { Button } from '@deepseek-ai/dsh-client-ui-primitives';
 import { Spinner } from './Spinner.js';
 import './FormActions.css';
 
+/**
+ * 一颗动作按钮的语气：`default`、`danger`（破坏性，描边危险色，永远不当填充主操作）、`primary`（填充，一个区只许一颗）。
+ */
 export type FormActionKind = 'default' | 'danger' | 'primary';
 
+/**
+ * 操作区里的一颗动作：键、文案、语气与回调；`busy` 时自带转圈并禁用。
+ */
 export interface FormAction {
   readonly key: string;
   readonly label: ReactNode;
@@ -15,6 +21,9 @@ export interface FormAction {
   readonly busy?: boolean | undefined;
 }
 
+/**
+ * `FormActions` 的契约：一组动作。
+ */
 export interface FormActionsProps {
   readonly actions: readonly FormAction[];
 }
@@ -47,6 +56,11 @@ function variantOf(kind: FormActionKind): 'ghost' | 'outline' | 'primary' {
   return 'ghost';
 }
 
+/**
+ * 操作区：把一组动作按"primary 永远在右、danger 紧挨它左侧"排好，窄了自动折行。
+ * @param props.actions - 动作清单；调用点给的顺序只在同语气内部生效，空数组时整块不渲染。
+ * @returns 一排按钮，或 `null`（没有动作时）。
+ */
 export function FormActions({ actions }: FormActionsProps) {
   if (actions.length === 0) return null;
   reportExtraPrimaries(actions);

package/src/components/FormNodes.tsx

@@ -0,0 +1,193 @@
+import type { ReactNode } from '../lib/react.js';
+import { h } from '../lib/react.js';
+import type { FormAction } from './FormActions.js';
+import type { FormField, FormValue } from './FormTypes.js';
+import { FormRow } from './FormRows.js';
+
+/**
+ * 只剩要显示的那些格子 —— `visible: false` 的当它不存在：不渲染、不校验、不进 `values`，也不参与找第一处错误。
+ * @param fields - 表单的字段清单。
+ * @returns 保序的新数组，`visible` 不给或为 `true` 的都在；全不可见时给空数组。
+ */
+export function visibleFieldsOf(fields: readonly FormField[]): readonly FormField[] {
+  return fields.filter((field) => field.visible !== false);
+}
+
+/**
+ * 找出装配错的键：**假值**的键（空串 / `undefined` / `null`，运行期真漏给 `key` 就是这条）每次出现都算一处，
+ * 以及同一张表单里出现两次的键 —— 这两样都会让 `id` 撞车、`values` 少一格。
+ * @param fields - 表单的字段清单（通常是已经过滤过可见性的那份）。
+ * @returns 出问题的键的清单、按首次出现顺序去重；缺失的键一律记成空串（报的时候印成 `（空 key）`），空表给空数组。
+ */
+export function duplicateKeysOf(fields: readonly FormField[]): readonly string[] {
+  const seen = new Set<string>();
+  const duplicated = new Set<string>();
+  for (const field of fields) {
+    const key = field.key;
+    if (!key) {
+      duplicated.add('');
+      continue;
+    }
+    if (seen.has(key)) duplicated.add(key);
+    seen.add(key);
+  }
+  return [...duplicated];
+}
+
+/**
+ * 装配错了要当场诊断：`key` 缺失或重复时给 `console.error` —— 但照渲不误，不 throw。
+ * 形式与理由同 `FormActions` 里那颗多出来的 `primary`：装配的小错不该让 `CardBoundary` 把用户的整张卡变空白。
+ * @param fields - 表单的字段清单（通常是已经过滤过可见性的那份）。
+ */
+export function reportDuplicateKeys(fields: readonly FormField[]): void {
+  const duplicated = duplicateKeysOf(fields);
+  if (duplicated.length === 0) return;
+  const named = duplicated.map((key) => (key === '' ? '（空 key）' : key));
+  console.error(
+    `[dsh-workbench] Form 里有重复或缺失的字段 key：${named.join('、')} —— ` +
+      '同一张表单里 key 必须唯一且非空（它决定 id 与 values 的键），否则 id 会撞车、values 会少一格',
+  );
+}
+
+/**
+ * 把每格的 `value` 收成一张键值表交给 `onSubmit` —— `Form` 自己一个值都不存，这张表就是从 `fields` 现取的快照。
+ * @param fields - 表单的字段清单；取的就是它们的 `value`，`value` 是数组的那格（多选）原样带出、不复制。
+ * @returns 键为字段 `key`、值为该格 `value` 的表；`fields` 为空时给空表，不是 `undefined`。
+ */
+export function formValuesOf(fields: readonly FormField[]): Readonly<Record<string, FormValue>> {
+  const values: Record<string, FormValue> = {};
+  for (const field of fields) values[field.key] = field.value;
+  return values;
+}
+
+/**
+ * 算每格现在该不该报错：还没提交过（`show` 为 false）时一格都不报 —— 不边打字边骂人。
+ * `validate` 返回**真值**才算错，假值（`undefined` / `null` / `false` / 空串）一律当"这格没错" ——
+ * 所以 `v.trim() === '' && '必填'` 这种用 `&&` 算文案的写法是对的。
+ * @param fields - 表单的字段清单（通常是已经过滤过可见性的那份）。
+ * @param show - 提交过没有；false 时全给 `undefined`，true 时逐格调 `field.validate` 并按真值收。
+ * @returns 键为 `key`、值为那句文案或 `undefined` 的表；没给 `validate` 的格子也是 `undefined`。
+ */
+export function formProblemsOf(
+  fields: readonly FormField[],
+  show: boolean,
+): Readonly<Record<string, ReactNode | undefined>> {
+  const values = formValuesOf(fields);
+  const problems: Record<string, ReactNode | undefined> = {};
+  for (const field of fields) {
+    const found = show ? field.validate?.(field.value, values) : undefined;
+    problems[field.key] = found ? found : undefined;
+  }
+  return problems;
+}
+
+/**
+ * 按字段顺序取第一处错误 —— 提交被挡住时要带进视口的就是这一格。
+ * 判的是**真值**（与 `formProblemsOf` 同一口径）：假值那种"错误文案"渲染出来本来就是空的，不算错。
+ * @param fields - 表单的字段清单，顺序就是「第一处」的判据。
+ * @param problems - `formProblemsOf` 那张表，也可以是调用点自己拼的（同样按真值判）。
+ * @returns 第一格有错的字段；一格都没错时给 `undefined`。
+ */
+export function formFirstProblemOf(
+  fields: readonly FormField[],
+  problems: Readonly<Record<string, ReactNode | undefined>>,
+): FormField | undefined {
+  return fields.find((field) => Boolean(problems[field.key]));
+}
+
+/**
+ * 提交那一拍的结果：有错就挡住（并点出第一处错在哪一格），没错就把键值表交出去。
+ */
+export type FormSubmitOutcome =
+  | { readonly blocked: true; readonly first: FormField }
+  | { readonly blocked: false; readonly values: Readonly<Record<string, FormValue>> };
+
+/**
+ * 算提交那一拍该干什么 —— `Form` 的提交钮点下去、以及 `<form>` 的 Enter 提交，走的都是它。
+ * 错的判据只有一份（`formProblemsOf` + `formFirstProblemOf`），这里不重算第二遍。
+ * @param fields - 要提交的那些格子（通常是调用点先 `visibleFieldsOf` 过滤过的，不可见那格不进 `values` 也不算错）。
+ * @returns `blocked: true` 时带上是按字段顺序数第一格有错的字段（拿它去 `revealFirstProblem`）；
+ * `blocked: false` 时带上从 `fields` 现取的键值表。空表一定给 `blocked: false` 与空 values。
+ */
+export function formSubmitOf(fields: readonly FormField[]): FormSubmitOutcome {
+  const problems = formProblemsOf(fields, true);
+  const first = formFirstProblemOf(fields, problems);
+  if (first !== undefined) return { blocked: true, first };
+  return { blocked: false, values: formValuesOf(fields) };
+}
+
+/**
+ * 组表单的操作区：调用点给的其余动作在最左，取消在中间，提交永远是最右那颗 `primary`。
+ * @param args.extra - 其余动作（default / danger），保持调用点给的顺序；不给就是没有。
+ * @param args.cancel - 取消那格的 `label` 与 `onClick`；不给就少一颗钮。
+ * @param args.submit - 提交钮的 `label` 与 `busyLabel`。
+ * @param args.busy - 提交中：提交钮带转圈并换 `busyLabel`（不给就沿用 `label`），`extra` 与取消一起禁用。
+ * @param args.disabled - 只再禁提交钮（如没改动可存），其余动作不受影响。
+ * @param args.onSubmitClick - 提交钮点下去做什么，通常是把这一拍交给 `Form` 的提交处理。
+ * @returns 给 `FormActions` 的动作清单；没给 `extra` 也没给 `cancel` 时只剩提交那一颗。
+ */
+export function formActionsOf(args: {
+  readonly extra: readonly FormAction[] | undefined;
+  readonly cancel: { readonly label: ReactNode; readonly onClick: () => void } | undefined;
+  readonly submit: { readonly label: ReactNode; readonly busyLabel?: ReactNode | undefined };
+  readonly busy: boolean;
+  readonly disabled: boolean;
+  readonly onSubmitClick: () => void;
+}): readonly FormAction[] {
+  const submit: FormAction = {
+    key: 'submit',
+    label: args.busy ? (args.submit.busyLabel ?? args.submit.label) : args.submit.label,
+    kind: 'primary',
+    busy: args.busy,
+    disabled: args.busy || args.disabled,
+    onClick: args.onSubmitClick,
+  };
+  const cancel: readonly FormAction[] =
+    args.cancel === undefined
+      ? []
+      : [
+          {
+            key: 'cancel',
+            label: args.cancel.label,
+            kind: 'default',
+            disabled: args.busy,
+            onClick: args.cancel.onClick,
+          },
+        ];
+  const extra = (args.extra ?? []).map(
+    (action): FormAction => (args.busy ? { ...action, disabled: true } : action),
+  );
+  return [...extra, ...cancel, submit];
+}
+
+/**
+ * 把整张表单的行画出来 —— 每格一个 `FormRow`，且**直接**是 `FormRows` 的孩子。
+ * 中间不许再包一层：`FormRow` 一旦不是 `.wb-formRows` 的网格项，`FormRows.css` 里那条 `subgrid` 就不匹配，
+ * 每行各自算列宽，控件左沿就参差了。
+ * @param args.fields - 要画的格子（通常是已经过滤过可见性的那份），顺序就是行的顺序。
+ * @param args.problems - `formProblemsOf` 那张表，决定哪一格显示错误文案（按**真值**判，假值不当错）。
+ * @param args.showProblem - 这一拍该不该显示错误（还没提交过时为 false，一格都不显示）。
+ * @param args.busy - 提交中：每格的绑定 `disabled` 为真。
+ * @returns `FormRow` 组成的数组；没有可画的格子时给空数组。
+ */
+export function formRowsOf(args: {
+  readonly fields: readonly FormField[];
+  readonly problems: Readonly<Record<string, ReactNode | undefined>>;
+  readonly showProblem: boolean;
+  readonly busy: boolean;
+}): readonly ReactNode[] {
+  return args.fields.map((field) =>
+    h(FormRow, {
+      key: field.key,
+      label: field.label,
+      hint: field.hint,
+      problem: args.showProblem ? args.problems[field.key] : undefined,
+      layout: field.layout,
+    }, field.control({
+      id: `wb-form-${field.key}`,
+      name: field.key,
+      invalid: args.showProblem && Boolean(args.problems[field.key]),
+      disabled: args.busy || field.disabled === true,
+    })),
+  );
+}

package/src/components/FormRows.css

@@ -24,6 +24,10 @@
   gap: var(--wb-len-6);
 }
 
+.wb-formRows > .wb-formRow[data-layout='stacked'] {
+  grid-template-columns: minmax(0, 1fr);
+}
+
 .wb-formLabel {
   min-width: 0;
   font-size: var(--dsw-font-xs-13-font-size);
@@ -36,12 +40,39 @@
   white-space: normal;
 }
 
+.wb-formRow[data-layout='stacked'] .wb-formHint,
+.wb-formRow[data-layout='stacked'] .wb-formProblem {
+  grid-column: 1 / -1;
+}
+
 .wb-formControl {
   display: flex;
   align-items: center;
   min-width: 0;
 }
 
+.wb-formControl
+  > :where(
+    .wb-selectAnchor,
+    .wb-choiceMenu,
+    input:not(
+      [type='checkbox'],
+      [type='radio'],
+      [type='button'],
+      [type='submit'],
+      [type='reset'],
+      [type='image'],
+      [type='color'],
+      [type='range']
+    ),
+    select,
+    textarea
+  ) {
+  box-sizing: border-box;
+  width: 100%;
+  min-width: 0;
+}
+
 .wb-formHint {
   grid-column: 2;
   font-size: var(--dsw-font-xxs-12-font-size);

package/src/components/FormRows.test.tsx

@@ -84,11 +84,37 @@ describe('FormRow', () => {
 
 const FORM_CSS = readFileSync(new URL('./FormRows.css', import.meta.url), 'utf8');
 
+function normalize(selector: string): string {
+  return selector
+    .replace(/\s+/g, ' ')
+    .replace(/\(\s+/g, '(')
+    .replace(/\s+\)/g, ')')
+    .trim();
+}
+
+function selectorParts(head: string): string[] {
+  const parts: string[] = [];
+  let depth = 0;
+  let current = '';
+  for (const char of head) {
+    if (char === '(') depth += 1;
+    if (char === ')') depth -= 1;
+    if (char === ',' && depth === 0) {
+      parts.push(normalize(current));
+      current = '';
+      continue;
+    }
+    current += char;
+  }
+  parts.push(normalize(current));
+  return parts;
+}
+
 function declarations(selector: string): string[] {
   for (const block of FORM_CSS.split('}')) {
     const [head, ...rest] = block.split('{');
     if (rest.length === 0 || head === undefined) continue;
-    if (head.trim() !== selector) continue;
+    if (!selectorParts(head).includes(normalize(selector))) continue;
     return rest
       .join('{')
       .split(';')
@@ -132,7 +158,51 @@ describe('标签列：同一个 FormRows 共用一列（ADR-0052 §11）', () =>
     );
   });
 
+  it('★ stacked 行在 FormRows 里也压得过 subgrid 与那条回退（同权重、靠后那条赢过的老坑）', () => {
+    expect(declarations(".wb-formRows > .wb-formRow[data-layout='stacked']")).toContain(
+      'grid-template-columns: minmax(0, 1fr)',
+    );
+  });
+
+  it('★ stacked 行里 hint / problem 通栏（它们的 grid-column: 2 会造出隐式第二列）', () => {
+    expect(declarations(".wb-formRow[data-layout='stacked'] .wb-formHint")).toContain(
+      'grid-column: 1 / -1',
+    );
+    expect(declarations(".wb-formRow[data-layout='stacked'] .wb-formProblem")).toContain(
+      'grid-column: 1 / -1',
+    );
+  });
+
   it('★ 不是 FormRow 的子项（分组标题那种）通栏，别被塞进标签那一列', () => {
     expect(declarations('.wb-formRows > :not(.wb-formRow)')).toContain('grid-column: 1 / -1');
   });
 });
+
+const EXCLUDED_INPUT_TYPES = [
+  'checkbox',
+  'radio',
+  'button',
+  'submit',
+  'reset',
+  'image',
+  'color',
+  'range',
+];
+const CONTROL_FILL_SELECTOR = `.wb-formControl > :where(.wb-selectAnchor, .wb-choiceMenu, input:not(${EXCLUDED_INPUT_TYPES.map((one) => `[type='${one}']`).join(', ')}), select, textarea)`;
+
+describe('控件槽那一格：字段控件铺满，宽度不归调用点写（ADR-0052 §13）', () => {
+  it('★ 那一格里的字段控件吃满控件槽：border-box + width 100% + min-width 0', () => {
+    const fill = declarations(CONTROL_FILL_SELECTOR);
+
+    expect(fill).toContain('box-sizing: border-box');
+    expect(fill).toContain('width: 100%');
+    expect(fill).toContain('min-width: 0');
+  });
+
+  it('★ 开关与按钮那一族不在名单里（拉宽一颗 switch、一颗 <input type=submit> 就是另一回事）', () => {
+    for (const type of EXCLUDED_INPUT_TYPES) {
+      expect(CONTROL_FILL_SELECTOR).toContain(`[type='${type}']`);
+    }
+    expect(FORM_CSS).not.toMatch(/\.wb-formControl\s*>\s*\*/);
+  });
+});

package/src/components/FormRows.tsx

@@ -2,14 +2,25 @@ import type { ReactNode } from '../lib/react.js';
 import { h } from '../lib/react.js';
 import './FormRows.css';
 
+/**
+ * `FormRows` 的契约：一列 `FormRow` 的容器。
+ */
 export interface FormRowsProps {
   readonly children?: ReactNode | undefined;
 }
 
+/**
+ * 表单行的容器：同一份 `FormRows` 共用一个标签列（列宽由最长的标签定），行距也归它。
+ * @param props.children - 一串 `FormRow`；非行的孩子（如分组标题）自动通栏。
+ * @returns 竖排的 div。
+ */
 export function FormRows({ children }: FormRowsProps) {
   return <div className="wb-formRows">{children}</div>;
 }
 
+/**
+ * `FormRow` 的契约：标签、提示、错误与控件的排布。
+ */
 export interface FormRowProps {
   readonly label: ReactNode;
   readonly hint?: ReactNode | undefined;
@@ -18,6 +29,15 @@ export interface FormRowProps {
   readonly children?: ReactNode | undefined;
 }
 
+/**
+ * 表单一行：左边标签、右边控件，提示与错误占控件下面那一格。
+ * @param props.label - 这一行的标签；进了这一行，控件自己就别再给 `label`，否则会多一个标签。
+ * @param props.hint - 控件下的说明；给了 `problem` 就不画它 —— 同一格不叠两段话。
+ * @param props.problem - 校验失败那句话；给了就顶掉 `hint` 并给整行加上出错标记。
+ * @param props.layout - `stacked` 才是标签在上、控件在下（默认 `inline`：标签在左）。
+ * @param props.children - 控件本体。
+ * @returns 一个 `<label>`。
+ */
 export function FormRow({ label, hint, problem, layout = 'inline', children }: FormRowProps) {
   return (
     <label

package/src/components/FormTypes.ts

@@ -0,0 +1,65 @@
+import type { ReactNode } from '../lib/react.js';
+import type { FormAction } from './FormActions.js';
+
+/**
+ * 一格控件的值：单值（`TextField` / `SelectField` / `ChoiceGroup` 单选），或一组值（`ChoiceGroup` 多选）。
+ */
+export type FormValue = string | readonly string[];
+
+/**
+ * `Form` 递给控件那一格的绑定：`id` / `name` / `invalid` / `disabled` 由 `Form` 定，控件只负责接上。
+ */
+export interface FormFieldBinding {
+  readonly id: string;
+  readonly name: string;
+  readonly invalid: boolean;
+  readonly disabled: boolean;
+}
+
+/**
+ * 一格字段的配置：键、标签、值、怎么算错（`validate`）、控件本身 —— 排布、时机、阻断都不写在这里，那些归 `Form`。
+ * `validate` 是纯函数、同步、只读 `values`：返回**真值**才算这一格错，假值（`undefined` / `null` / `false` / 空串）
+ * 一律当"没错"—— 所以 `(value) => value.trim() === '' && '必填'` 这种用 `&&` 算文案的写法是对的，
+ * 它的返回值就是错误行那句话。
+ */
+export interface FormField {
+  readonly key: string;
+  readonly label: ReactNode;
+  readonly hint?: ReactNode | undefined;
+  readonly layout?: 'inline' | 'stacked' | undefined;
+  readonly value: FormValue;
+  readonly visible?: boolean | undefined;
+  readonly disabled?: boolean | undefined;
+  readonly validate?: (value: FormValue, values: Readonly<Record<string, FormValue>>) => ReactNode | undefined;
+  readonly control: (binding: FormFieldBinding) => ReactNode;
+}
+
+/**
+ * 提交钮：文案归调用点，位置、禁用与忙态归 `Form`。
+ */
+export interface FormSubmit {
+  readonly label: ReactNode;
+  readonly busyLabel?: ReactNode | undefined;
+}
+
+/**
+ * 取消钮：文案与点下去做什么，`Form` 把它排在提交钮左边。
+ */
+export interface FormCancel {
+  readonly label: ReactNode;
+  readonly onClick: () => void;
+}
+
+/**
+ * `Form` 的契约：fields 配置进，排布、校验时机、提交阻断、操作区全归组件。
+ */
+export interface FormProps {
+  readonly fields: readonly FormField[];
+  readonly onSubmit: (values: Readonly<Record<string, FormValue>>) => void;
+  readonly submit: FormSubmit;
+  readonly cancel?: FormCancel | undefined;
+  readonly extra?: readonly FormAction[] | undefined;
+  readonly busy?: boolean | undefined;
+  readonly disabled?: boolean | undefined;
+  readonly problem?: ReactNode | undefined;
+}

package/src/components/FormWiring.test.tsx

@@ -0,0 +1,88 @@
+import { describe, expect, it, vi } from 'vitest';
+import type { FormField, FormProps, FormValue } from './FormTypes.js';
+import { Form } from './Form.js';
+
+function field(key: string, value: FormValue, validate?: FormField['validate']): FormField {
+  return {
+    key,
+    label: key,
+    value,
+    control: (binding) => `${key}:${binding.id}:${String(binding.invalid)}:${String(binding.disabled)}`,
+    ...(validate === undefined ? {} : { validate }),
+  };
+}
+
+vi.mock('../lib/react.js', async () => {
+  const actual = await vi.importActual<Record<string, unknown>>('../lib/react.js');
+  return {
+    ...actual,
+    useState: (initial: unknown) => [typeof initial === 'function' ? (initial as () => unknown)() : initial, () => {}],
+    useRef: (initial: unknown) => ({ current: initial ?? null }),
+    useEffect: () => {},
+  };
+});
+
+describe('Form 的接线（hooks 换成假的，在 node 里当函数调）', () => {
+  function formEvent(): { preventDefault: () => void; prevented: () => boolean } {
+    let prevented = false;
+    return {
+      preventDefault: () => {
+        prevented = true;
+      },
+      prevented: () => prevented,
+    };
+  }
+
+  function submitHandlerOf(props: FormProps): (event: { preventDefault: () => void }) => void {
+    const node = Form(props) as unknown as { props: { onSubmit: (event: { preventDefault: () => void }) => void } };
+    return node.props.onSubmit;
+  }
+
+  function propsOfForm(onSubmit: (values: Readonly<Record<string, FormValue>>) => void, over: Partial<FormProps> = {}): FormProps {
+    return { fields: [field('env', 'prod')], onSubmit, submit: { label: '保存' }, ...over };
+  }
+
+  it('★ 没错那一拍：preventDefault（不用浏览器默认提交）并调 onSubmit(values) 一次', () => {
+    const seen: (Readonly<Record<string, FormValue>>)[] = [];
+    const event = formEvent();
+
+    submitHandlerOf(propsOfForm((values) => void seen.push(values)))(event);
+
+    expect(event.prevented()).toBe(true);
+    expect(seen).toEqual([{ env: 'prod' }]);
+  });
+
+  it('★ 有错那一拍：不调 onSubmit', () => {
+    const onSubmit = vi.fn();
+    const fields = [field('project', '', () => '这个项目不存在')];
+
+    submitHandlerOf(propsOfForm(onSubmit, { fields }))({ preventDefault: () => {} });
+
+    expect(onSubmit).not.toHaveBeenCalled();
+  });
+
+  it('★ busy 时 Enter / 点提交都不提交（隐式提交也走这道闸）', () => {
+    const onSubmit = vi.fn();
+
+    submitHandlerOf(propsOfForm(onSubmit, { busy: true }))({ preventDefault: () => {} });
+
+    expect(onSubmit).not.toHaveBeenCalled();
+  });
+
+  it('★ disabled 时也不提交（没改动可存那颗钮禁着，回车同样进不来）', () => {
+    const onSubmit = vi.fn();
+
+    submitHandlerOf(propsOfForm(onSubmit, { disabled: true }))({ preventDefault: () => {} });
+
+    expect(onSubmit).not.toHaveBeenCalled();
+  });
+
+  it('★ 不可见那格不进 values（过滤发生在提交那一拍）', () => {
+    const seen: (Readonly<Record<string, FormValue>>)[] = [];
+    const fields = [field('env', 'prod'), { ...field('secret', 'shh'), visible: false }];
+
+    submitHandlerOf(propsOfForm((values) => void seen.push(values), { fields }))({ preventDefault: () => {} });
+
+    expect(seen).toEqual([{ env: 'prod' }]);
+  });
+});

package/src/components/Link.tsx

@@ -3,6 +3,9 @@ import { h } from '../lib/react.js';
 import { IconRightUpOutlineRegular } from '@deepseek-ai/dsh-client-ui-primitives';
 import './Link.css';
 
+/**
+ * `Link` 的契约：目标地址、文案与外链开关。
+ */
 export interface LinkProps {
   readonly href: string;
   readonly children?: ReactNode | undefined;
@@ -11,6 +14,15 @@ export interface LinkProps {
   readonly className?: string | undefined;
 }
 
+/**
+ * 唯一的外链写法：自带新窗口、`rel="noopener noreferrer"`、正文色与行尾那颗小箭头。
+ * @param props.href - 目标地址，必给。
+ * @param props.children - 链接文字（别自己再带 `→`）。
+ * @param props.title - 原生 title 提示；不给就不写这个属性。
+ * @param props.external - 默认 true：新窗口打开并画那颗 ↗；站内跳转给 false，箭头也一起不画。
+ * @param props.className - 追加在基础类名之后，不是替换。
+ * @returns 一个 `<a>`。
+ */
 export function Link({ href, children, title, external = true, className }: LinkProps) {
   return (
     <a