@dsh-workbench/shared 0.3.3 → 0.3.5

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.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

package/src/components/LongTaskRow.tsx

@@ -10,11 +10,17 @@ import {
 } from '@deepseek-ai/dsh-client-ui-primitives';
 import './LongTaskRow.css';
 
+/**
+ * 长任务行尾的一个链接：地址与文字。
+ */
 export interface LongTaskRowLink {
   readonly href: string;
   readonly text: string;
 }
 
+/**
+ * `LongTaskRow` 的契约：状态、标题、问题、链接，与两处可展开的原始输出。
+ */
 export interface LongTaskRowProps {
   readonly status: LongTaskStatus;
   readonly headline: string;
@@ -36,6 +42,19 @@ function RowLink({ href, text }: LongTaskRowLink) {
   );
 }
 
+/**
+ * 长任务那一行：状态点 + 标题 + 链接，跑失败时把步骤与原始输出收在两处可展开里。
+ * 发布、扫描、迁移这类跑得久的事都用它，别自己画进度。
+ * @param props.status - `longTaskDot` 认的四态之一，决定状态点颜色与要不要画"失败"那两块。
+ * @param props.headline - 这一行在干什么（一句话）。
+ * @param props.problem - 失败原因；不给不画。
+ * @param props.links - 行尾的链接，通常指向产物或日志。
+ * @param props.steps - 步骤文本；只在失败时画，且要同时给 `stepsTitle` 才成一块可展开。
+ * @param props.raw - 原始输出；只在失败时画，且要同时给 `rawTitle` 才成一块可展开。
+ * @param props.stepsTitle - 步骤那块展开行的标题；`rawTitle` 同理是原始输出那块。
+ * @param props.copyLabel - 复制钮文案：给了才画复制钮；`copiedLabel` 是复制成功后那句。
+ * @returns 一行长任务。
+ */
 export function LongTaskRow(props: LongTaskRowProps) {
   const [stepsOpen, setStepsOpen] = useState(false);
   const [rawOpen, setRawOpen] = useState(false);

package/src/components/Note.tsx

@@ -2,6 +2,9 @@ import type { ReactNode } from '../lib/react.js';
 import { h } from '../lib/react.js';
 import './Note.css';
 
+/**
+ * `Note` 的契约：语气、标签名与读屏角色。
+ */
 export interface NoteProps {
   readonly tone?: 'muted' | 'problem';
   readonly as?: 'p' | 'span';
@@ -9,6 +12,14 @@ export interface NoteProps {
   readonly children?: ReactNode | undefined;
 }
 
+/**
+ * 一句话说明或一句报错：卡片里的提示条用它，不承载交互。
+ * @param props.tone - `problem` 是报错色；默认 `muted`，普通说明色。
+ * @param props.as - `span` 是跟在别的行里，`p`（默认）独占一段。
+ * @param props.role - 读屏角色：变化中的提示给 `status`、报错给 `alert`；不给不设。
+ * @param props.children - 那句话本身。
+ * @returns 一个 `span` 或 `p`。
+ */
 export function Note({ tone = 'muted', as, role, children }: NoteProps) {
   const className = tone === 'problem' ? 'wb-problem' : 'wb-note';
   return as === 'span' ? (

package/src/components/ResourceStates.tsx

@@ -2,6 +2,11 @@ import type { ReactNode } from 'react';
 import { h } from '../lib/react.js';
 import './ResourceStates.css';
 
+/**
+ * 骨架屏：读数期间已经知道大概形状时用它（连形状都不知道就用 `CenteredState` 那句"正在读"）。
+ * @param props.rows - 画几行骨架（默认 4）；整块 `aria-hidden`，不读给读屏。
+ * @returns 一叠占位条。
+ */
 export function SkeletonRows({ rows = 4 }: { rows?: number }) {
   return (
     <div className="wb-skeleton" aria-hidden="true">
@@ -15,6 +20,9 @@ export function SkeletonRows({ rows = 4 }: { rows?: number }) {
   );
 }
 
+/**
+ * `CenteredState` 的契约：图标、标题、说明、明细与动作。
+ */
 export interface CenteredStateProps {
   icon: ReactNode;
   title: ReactNode;
@@ -24,6 +32,16 @@ export interface CenteredStateProps {
   compact?: boolean;
 }
 
+/**
+ * 居中一屏：要他先选一个 / 正在读 / 读不到时用它占住卡片版面。
+ * @param props.icon - 标题上方那枚图标；给 `null` 就只留标题（加载与报错常见）。
+ * @param props.title - 正中那行大字。
+ * @param props.hint - 标题下的一行说明。
+ * @param props.detail - 更细的一行（如原始错误码与那句话）；"读不到"时把错误放这里，绝不显示 0。
+ * @param props.action - 底部动作（如"重试"）；不给不画。
+ * @param props.compact - 紧凑档（默认 false），卡里空间小的时候给 true。
+ * @returns 一个 `role="status"` 的居中块。
+ */
 export function CenteredState({ icon, title, hint, detail, action, compact = false }: CenteredStateProps) {
   return (
     <div className={compact ? 'wb-centered wb-centeredCompact' : 'wb-centered'} role="status">
@@ -40,6 +58,13 @@ export function CenteredState({ icon, title, hint, detail, action, compact = fal
   );
 }
 
+/**
+ * 就绪但空：它只是 `CenteredState` 的简写，标题就是那句空态文案。
+ * @param props.text - 空态那句话。
+ * @param props.icon - 标题上方的图标；默认 `null`，不画图标。
+ * @param props.compact - 紧凑档，默认 false。
+ * @returns 一个居中块。
+ */
 export function EmptyState({ text, icon = null, compact = false }: { text: string; icon?: ReactNode; compact?: boolean }) {
   return <CenteredState icon={icon} title={text} compact={compact} />;
 }

package/src/components/Rows.tsx

@@ -2,19 +2,36 @@ import type { ReactNode } from '../lib/react.js';
 import { h } from '../lib/react.js';
 import './Rows.css';
 
+/**
+ * `Rows` 的契约：一组键值行的容器。
+ */
 export interface RowsProps {
   readonly children?: ReactNode | undefined;
 }
 
+/**
+ * 键值行的容器：分隔线、行距与两端对齐在它和 `Row` 里，别自己写 `ul` / `li` 拼。
+ * @param props.children - 一串 `Row`。
+ * @returns 竖排的 div。
+ */
 export function Rows({ children }: RowsProps) {
   return <div className="wb-rows">{children}</div>;
 }
 
+/**
+ * `Row` 的契约：左边名字 + 右边值。
+ */
 export interface RowProps {
   readonly label: ReactNode;
   readonly value: ReactNode;
 }
 
+/**
+ * 一行键值：左边名字、右边值；要成对说明一项数据就用它，别自己写两栏。
+ * @param props.label - 左边那格（键）。
+ * @param props.value - 右边那格（值），可以是数字、时间或一小段节点。
+ * @returns 一行两格。
+ */
 export function Row({ label, value }: RowProps) {
   return (
     <div className="wb-row">

package/src/components/SaveBar.tsx

@@ -2,6 +2,9 @@ import { h } from '../lib/react.js';
 import type { FormAction } from './FormActions.js';
 import { FormActions } from './FormActions.js';
 
+/**
+ * `SaveBar` 的契约：忙碌态、三句文案与两个回调。
+ */
 export interface SaveBarProps {
   readonly busy: boolean;
   readonly disabled?: boolean | undefined;
@@ -14,6 +17,15 @@ export interface SaveBarProps {
   readonly onSave: () => void;
 }
 
+/**
+ * 设置面底下那条"取消 / 保存"：就是 `FormActions` 的两颗固定动作，顺序与间距不归调用点。
+ * @param props.busy - 保存中：两颗钮一起禁用，保存那颗换成 `saving` 文案并带转圈。
+ * @param props.disabled - 再额外禁掉保存钮（如没改动可存）；默认不禁，取消钮不受它管。
+ * @param props.labels - 三句文案：`cancel` / `save` / `saving`。
+ * @param props.onCancel - 点取消。
+ * @param props.onSave - 点保存。
+ * @returns 一组按钮。
+ */
 export function SaveBar({ busy, disabled, labels, onCancel, onSave }: SaveBarProps) {
   const actions: readonly FormAction[] = [
     { key: 'cancel', label: labels.cancel, kind: 'default', onClick: onCancel, disabled: busy },