@dsh-workbench/shared 0.3.4 → 0.3.6

package/dist/components/Activity.d.ts

@@ -1,17 +1,40 @@
 import type { ReactNode } from '../lib/react.js';
 import './Activity.css';
+/**
+ * `ActivityBlock` 的契约：块头与块内容。
+ */
 export interface ActivityBlockProps {
     readonly head?: ReactNode | undefined;
     readonly children?: ReactNode | undefined;
 }
+/**
+ * "它做过什么"那一块：上面一行块头、下面一列活动行，卡里放时间线就用它。
+ * @param props.head - 块头（如"最近 10 次"）；不给不画那一行。
+ * @param props.children - 块内容，通常是一串 `ActivityLine`。
+ * @returns 一个 div。
+ */
 export declare function ActivityBlock({ head, children }: ActivityBlockProps): JSX.Element;
+/**
+ * `ActivityLine` 的契约：状态点、正文、时间与行尾动作。
+ */
 export interface ActivityLineProps {
     readonly dot?: ReactNode | undefined;
     readonly text: ReactNode;
     readonly at?: ReactNode | undefined;
     readonly actions?: ReactNode | undefined;
 }
+/**
+ * 一条活动：状态点 + 正文 + 时间，行尾可挂动作；时间一律用它，别自己拼。
+ * @param props.dot - 行首那枚状态点；不给就只留正文。
+ * @param props.text - 这一条干了什么。
+ * @param props.at - 时间那一格（相对时间文本）；不给不画。
+ * @param props.actions - 行尾动作，通常是一两颗 `ActivityAction`；不给不画。
+ * @returns 一行。
+ */
 export declare function ActivityLine({ dot, text, at, actions }: ActivityLineProps): JSX.Element;
+/**
+ * `ActivityAction` 的契约：一颗图标钮、一个外链，或一个失败态。
+ */
 export interface ActivityActionProps {
     readonly label: string;
     readonly hint?: string | undefined;
@@ -20,4 +43,14 @@ export interface ActivityActionProps {
     readonly onClick?: (() => void) | undefined;
     readonly failed?: boolean | undefined;
 }
+/**
+ * 活动行尾那颗动作：给 `href` 就是外链，否则是图标钮并带上 tooltip。
+ * @param props.label - 读屏名，也是 `hint` 不给时的 tooltip 文案。
+ * @param props.hint - tooltip 上那句更细的说明；不给退化成 `label`。
+ * @param props.icon - 那颗图标。
+ * @param props.href - 给了就渲染成新窗口外链；与 `onClick` 同时给时以它为准。
+ * @param props.onClick - 图标钮的点击回调。
+ * @param props.failed - 上一次动作失败了：钮换成危险色（默认 false）。
+ * @returns 一个 `<a>` 或一颗 `Button`。
+ */
 export declare function ActivityAction({ label, hint, icon, href, onClick, failed }: ActivityActionProps): JSX.Element;

package/dist/components/Activity.js

@@ -1,11 +1,25 @@
 import { Button, Tooltip } from '@deepseek-ai/dsh-client-ui-primitives';
 import { h } from '../lib/react.js';
 import './Activity.css';
+/**
+ * "它做过什么"那一块：上面一行块头、下面一列活动行，卡里放时间线就用它。
+ * @param props.head - 块头（如"最近 10 次"）；不给不画那一行。
+ * @param props.children - 块内容，通常是一串 `ActivityLine`。
+ * @returns 一个 div。
+ */
 export function ActivityBlock({ head, children }) {
     return (h("div", { className: "wb-activityBlock" },
         head === undefined ? null : h("div", { className: "wb-activityBlockHead" }, head),
         children));
 }
+/**
+ * 一条活动：状态点 + 正文 + 时间，行尾可挂动作；时间一律用它，别自己拼。
+ * @param props.dot - 行首那枚状态点；不给就只留正文。
+ * @param props.text - 这一条干了什么。
+ * @param props.at - 时间那一格（相对时间文本）；不给不画。
+ * @param props.actions - 行尾动作，通常是一两颗 `ActivityAction`；不给不画。
+ * @returns 一行。
+ */
 export function ActivityLine({ dot, text, at, actions }) {
     return (h("div", { className: "wb-activityLine" },
         dot,
@@ -13,6 +27,16 @@ export function ActivityLine({ dot, text, at, actions }) {
         at === undefined ? null : h("span", { className: "wb-activityLineAt" }, at),
         actions === undefined ? null : h("span", { className: "wb-activityLineActions" }, actions)));
 }
+/**
+ * 活动行尾那颗动作：给 `href` 就是外链，否则是图标钮并带上 tooltip。
+ * @param props.label - 读屏名，也是 `hint` 不给时的 tooltip 文案。
+ * @param props.hint - tooltip 上那句更细的说明；不给退化成 `label`。
+ * @param props.icon - 那颗图标。
+ * @param props.href - 给了就渲染成新窗口外链；与 `onClick` 同时给时以它为准。
+ * @param props.onClick - 图标钮的点击回调。
+ * @param props.failed - 上一次动作失败了：钮换成危险色（默认 false）。
+ * @returns 一个 `<a>` 或一颗 `Button`。
+ */
 export function ActivityAction({ label, hint, icon, href, onClick, failed }) {
     const tip = hint ?? label;
     if (href !== undefined) {

package/dist/components/ApprovalDetail.d.ts

@@ -19,6 +19,9 @@ interface ChatSnapshot {
     };
 }
 type UseChat = <T>(selector: (snapshot: ChatSnapshot) => T) => T | undefined;
+/**
+ * `ApprovalDetail` 的契约：调用 id、读会话快照的钩子、已装模块与兜底渲染。
+ */
 export interface ApprovalDetailProps {
     readonly callId?: string;
     readonly useChat?: UseChat;
@@ -26,5 +29,14 @@ export interface ApprovalDetailProps {
     readonly t?: Translate;
     readonly renderShell?: ((input: ApprovalInput, t: Translate) => ReactNode) | undefined;
 }
+/**
+ * 审批屏的详情格：按工具名找到认领它的模块交给它渲染，没有模块认领就退回外壳那张表或一段原始命令。
+ * @param props.callId - 这次工具调用的 id；不给就直接走兜底（连调用都找不到）。
+ * @param props.useChat - 读会话快照的钩子（dsh 注入）；不给就当作读不到调用。
+ * @param props.units - 已装模块的面，按各自的 `approval.tools` 认领这次调用。
+ * @param props.t - 翻译函数；不给就用返回 key 的直通实现。
+ * @param props.renderShell - 没有模块认领时外壳自己的渲染（那张表）；不给且这次调用没带 `command` 时整格返回 `null`。
+ * @returns 认领方的渲染、外壳那张表，或一段可复制的命令。
+ */
 export declare function ApprovalDetail(props: ApprovalDetailProps): JSX.Element | null;
 export {};

package/dist/components/ApprovalDetail.js

@@ -22,6 +22,15 @@ function parseArgs(raw) {
         return {};
     }
 }
+/**
+ * 审批屏的详情格：按工具名找到认领它的模块交给它渲染，没有模块认领就退回外壳那张表或一段原始命令。
+ * @param props.callId - 这次工具调用的 id；不给就直接走兜底（连调用都找不到）。
+ * @param props.useChat - 读会话快照的钩子（dsh 注入）；不给就当作读不到调用。
+ * @param props.units - 已装模块的面，按各自的 `approval.tools` 认领这次调用。
+ * @param props.t - 翻译函数；不给就用返回 key 的直通实现。
+ * @param props.renderShell - 没有模块认领时外壳自己的渲染（那张表）；不给且这次调用没带 `command` 时整格返回 `null`。
+ * @returns 认领方的渲染、外壳那张表，或一段可复制的命令。
+ */
 export function ApprovalDetail(props) {
     const useChat = props.useChat ?? (() => undefined);
     const call = useChat((snapshot) => callOf(snapshot, props.callId));

package/dist/components/ApprovalPlan.d.ts

@@ -1,13 +1,27 @@
 import type { ReactNode } from '../lib/react.js';
 import './ApprovalPlan.css';
+/**
+ * 审批详情里的一行：左边标签、右边值。
+ */
 export interface ApprovalPlanRow {
     readonly label: ReactNode;
     readonly value: ReactNode;
 }
+/**
+ * `ApprovalPlan` 的契约：详情行，外加附注与警告两格。
+ */
 export interface ApprovalPlanProps {
     readonly rows: readonly ApprovalPlanRow[];
     readonly hint?: ReactNode | undefined;
     readonly warn?: ReactNode | undefined;
     readonly children?: ReactNode | undefined;
 }
+/**
+ * 审批屏那张"这次要做什么"的表：一行一项，上面可给一句附注、下面可给一句警告。
+ * @param props.rows - 详情行，按给的顺序渲染；空数组时只剩附注与警告。
+ * @param props.hint - 表上面那句说明；不给不画。
+ * @param props.warn - 表下面那句警告；不给不画。
+ * @param props.children - 插在表与 `warn` 之间的补充内容。
+ * @returns 一个 div。
+ */
 export declare function ApprovalPlan({ rows, hint, warn, children }: ApprovalPlanProps): JSX.Element;

package/dist/components/ApprovalPlan.js

@@ -1,5 +1,13 @@
 import { h } from '../lib/react.js';
 import './ApprovalPlan.css';
+/**
+ * 审批屏那张"这次要做什么"的表：一行一项，上面可给一句附注、下面可给一句警告。
+ * @param props.rows - 详情行，按给的顺序渲染；空数组时只剩附注与警告。
+ * @param props.hint - 表上面那句说明；不给不画。
+ * @param props.warn - 表下面那句警告；不给不画。
+ * @param props.children - 插在表与 `warn` 之间的补充内容。
+ * @returns 一个 div。
+ */
 export function ApprovalPlan({ rows, hint, warn, children }) {
     return (h("div", { className: "wb-approvalPlan" },
         hint === undefined ? null : h("p", { className: "wb-approvalHint" }, hint),

package/dist/components/Card.d.ts

@@ -1,6 +1,9 @@
 import type { ReactNode } from '../lib/react.js';
 import type { Translate } from '../api/dsh-client.js';
 import './Card.css';
+/**
+ * `Card` 的契约：标题、刷新、卡片体，以及可整块替换的卡头。
+ */
 export interface CardProps {
     readonly t: Translate;
     readonly title: string;
@@ -10,4 +13,14 @@ export interface CardProps {
     readonly head?: ReactNode | undefined;
     readonly children?: ReactNode | undefined;
 }
+/**
+ * 一张卡的壳：卡头（标题 + 刷新钮）+ 卡片体，面板上每一格都是它。
+ * @param props.t - 卡头那两句文案（刷新 / 刷新中）的翻译函数。
+ * @param props.refreshing - 正在刷新：刷新钮随之禁用并转圈；接 `resource.phase === 'loading'`。
+ * @param props.onRefresh - 点刷新钮做什么，异步由调用点自己管。
+ * @param props.meta - 标题右侧那一小段补充（条数、时间）；不给不占位。
+ * @param props.head - 整块替换卡头时给（如自带齿轮的 `CardHead`）；不给用默认卡头。
+ * @param props.children - 卡片体。
+ * @returns 一个 `<section>`。
+ */
 export declare function Card({ t, title, refreshing, onRefresh, meta, head, children }: CardProps): JSX.Element;

package/dist/components/Card.js

@@ -1,6 +1,16 @@
 import { h } from '../lib/react.js';
 import { CardHead } from './CardHead.js';
 import './Card.css';
+/**
+ * 一张卡的壳：卡头（标题 + 刷新钮）+ 卡片体，面板上每一格都是它。
+ * @param props.t - 卡头那两句文案（刷新 / 刷新中）的翻译函数。
+ * @param props.refreshing - 正在刷新：刷新钮随之禁用并转圈；接 `resource.phase === 'loading'`。
+ * @param props.onRefresh - 点刷新钮做什么，异步由调用点自己管。
+ * @param props.meta - 标题右侧那一小段补充（条数、时间）；不给不占位。
+ * @param props.head - 整块替换卡头时给（如自带齿轮的 `CardHead`）；不给用默认卡头。
+ * @param props.children - 卡片体。
+ * @returns 一个 `<section>`。
+ */
 export function Card({ t, title, refreshing, onRefresh, meta, head, children }) {
     return (h("section", { className: "wb-card" },
         head === undefined ? (h(CardHead, { t: t, title: title, refreshing: refreshing, onRefresh: onRefresh, meta: meta })) : (head),

package/dist/components/CardAnchor.d.ts

@@ -1,7 +1,21 @@
 import type { ReactNode } from '../lib/react.js';
+/**
+ * 由 unit id 拼出卡片锚点 id，外壳的截图、滚动与页面探针都按它找卡。
+ * @param unit - unit id；`null` 或空串（没有 unit 的卡）时返回 undefined，不生成锚点。
+ * @returns `wb-card-<unit>`，或 undefined。
+ */
 export declare function cardIdOf(unit: string | null): string | undefined;
+/**
+ * `CardAnchor` 的契约：unit id 与它锚住的内容。
+ */
 export interface CardAnchorProps {
     readonly unit: string;
     readonly children?: ReactNode | undefined;
 }
+/**
+ * 外壳自己盖的卡片锚点：套在卡外面给出 `id="wb-card-<unit>"`；模块别自己写，也别删。
+ * @param props.unit - 卡的 unit id，用来算锚点 id。
+ * @param props.children - 被锚住的卡片本体；锚点自己 `display: contents`，不占布局。
+ * @returns 带 id 的占位 div。
+ */
 export declare function CardAnchor({ unit, children }: CardAnchorProps): JSX.Element;

package/dist/components/CardAnchor.js

@@ -1,8 +1,19 @@
 import { h } from '../lib/react.js';
 import styles from './CardAnchor.module.css';
+/**
+ * 由 unit id 拼出卡片锚点 id，外壳的截图、滚动与页面探针都按它找卡。
+ * @param unit - unit id；`null` 或空串（没有 unit 的卡）时返回 undefined，不生成锚点。
+ * @returns `wb-card-<unit>`，或 undefined。
+ */
 export function cardIdOf(unit) {
     return unit === null || unit === '' ? undefined : `wb-card-${unit}`;
 }
+/**
+ * 外壳自己盖的卡片锚点：套在卡外面给出 `id="wb-card-<unit>"`；模块别自己写，也别删。
+ * @param props.unit - 卡的 unit id，用来算锚点 id。
+ * @param props.children - 被锚住的卡片本体；锚点自己 `display: contents`，不占布局。
+ * @returns 带 id 的占位 div。
+ */
 export function CardAnchor({ unit, children }) {
     return (h("div", { id: cardIdOf(unit), className: styles.anchor }, children));
 }

package/dist/components/CardBoundary.d.ts

@@ -1,6 +1,9 @@
 import type { Translate } from '../api/dsh-client.js';
 import type { ReactNode } from '../lib/react.js';
 import { Component } from '../lib/react.js';
+/**
+ * `CardBoundary` 的契约：被守的 unit、重来键与失败回调。
+ */
 export interface CardBoundaryProps {
     readonly unit: string;
     readonly resetKey: string;
@@ -8,10 +11,27 @@ export interface CardBoundaryProps {
     readonly onFailure?: ((reason: string) => void) | undefined;
     readonly children?: ReactNode | undefined;
 }
+/**
+ * `CardBoundary` 的状态：这次渲染炸出来的那句话，没炸是 `null`。
+ */
 export interface CardBoundaryState {
     readonly reason: string | null;
 }
+/**
+ * 把抛出来的任何东西收成一句人能看的失败原因，上报与展示都用它。
+ * @param error - 抛出来的值：`Error` 取 `message`，字符串原样，其余走 JSON。
+ * @returns 一句原因文本；`Error('')` 这种没带 message 的会回空串（调用点别把它当"一定有话"）。
+ */
 export declare function errorReasonOf(error: unknown): string;
+/**
+ * 卡片级错误边界：一张卡渲染炸了只画一条报错 + 重试，不让整块面板跟着塌。
+ * @param props.unit - 出事的 unit id，写进报错文案并作为上报标识。
+ * @param props.resetKey - 重来键：它一变（如切了工作区）就自动清掉报错，把卡片重新渲染一遍。
+ * @param props.t - 报错那句与重试钮文案的翻译函数。
+ * @param props.onFailure - 失败时把原因报给宿主（面板状态要用）；不给就只打一条 console。
+ * @param props.children - 正常时要渲染的卡片内容。
+ * @returns 正常时是 `children`，炸过且还没重来之前是一条报错。
+ */
 export declare class CardBoundary extends Component<CardBoundaryProps, CardBoundaryState> {
     state: CardBoundaryState;
     static getDerivedStateFromError(error: unknown): CardBoundaryState;

package/dist/components/CardBoundary.js

@@ -1,11 +1,25 @@
 import { Button } from '@deepseek-ai/dsh-client-ui-primitives';
 import { Component, h } from '../lib/react.js';
 import { Note } from './Note.js';
+/**
+ * 把抛出来的任何东西收成一句人能看的失败原因，上报与展示都用它。
+ * @param error - 抛出来的值：`Error` 取 `message`，字符串原样，其余走 JSON。
+ * @returns 一句原因文本；`Error('')` 这种没带 message 的会回空串（调用点别把它当"一定有话"）。
+ */
 export function errorReasonOf(error) {
     if (error instanceof Error)
         return error.message;
     return typeof error === 'string' ? error : JSON.stringify(error) ?? String(error);
 }
+/**
+ * 卡片级错误边界：一张卡渲染炸了只画一条报错 + 重试，不让整块面板跟着塌。
+ * @param props.unit - 出事的 unit id，写进报错文案并作为上报标识。
+ * @param props.resetKey - 重来键：它一变（如切了工作区）就自动清掉报错，把卡片重新渲染一遍。
+ * @param props.t - 报错那句与重试钮文案的翻译函数。
+ * @param props.onFailure - 失败时把原因报给宿主（面板状态要用）；不给就只打一条 console。
+ * @param props.children - 正常时要渲染的卡片内容。
+ * @returns 正常时是 `children`，炸过且还没重来之前是一条报错。
+ */
 export class CardBoundary extends Component {
     state = { reason: null };
     static getDerivedStateFromError(error) {

package/dist/components/CardHead.d.ts

@@ -1,6 +1,9 @@
 import type { ReactNode } from '../lib/react.js';
 import type { Translate } from '../api/dsh-client.js';
 import './CardHead.css';
+/**
+ * `CardHead` 的契约：标题、补充、刷新，外加齿轮与平台跳转两格。
+ */
 export interface CardHeadProps {
     readonly t: Translate;
     readonly title: string;
@@ -14,4 +17,14 @@ export interface CardHeadProps {
     readonly platform?: string | undefined;
     readonly platformTitle?: string | undefined;
 }
+/**
+ * 卡头：标题 + 补充 + 刷新钮（`Card` 内部就是它），要自己拼卡头或加齿轮 / 平台跳转时直接用。
+ * @param props.t - 刷新那两句文案（刷新 / 刷新中）的翻译函数。
+ * @param props.title - 卡标题；`props.meta` 是它右侧那一小段补充，不给不占位。
+ * @param props.refreshing - 正在刷新：刷新钮禁用并转圈。
+ * @param props.onRefresh - 点刷新钮做什么。
+ * @param props.gear - 齿轮钮的读屏名；`gearOpen` 控制它高亮、`onToggleGear` 是点击回调，三者一起给才画。
+ * @param props.platformHref - 整张卡对应系统的地址：给了就画那颗 ↗（新窗口），tooltip 用 `platformTitle`，缺了退化用 `platform`。
+ * @returns 一个 `<header>`。
+ */
 export declare function CardHead({ t, title, meta, refreshing, onRefresh, gear, gearOpen, onToggleGear, platformHref, platform, platformTitle, }: CardHeadProps): JSX.Element;

package/dist/components/CardHead.js

@@ -1,6 +1,16 @@
 import { Button, IconRefreshOutlineRegular, IconRightUpOutlineRegular, IconSettingsOutlineRegular, Tooltip, } from '@deepseek-ai/dsh-client-ui-primitives';
 import { h } from '../lib/react.js';
 import './CardHead.css';
+/**
+ * 卡头：标题 + 补充 + 刷新钮（`Card` 内部就是它），要自己拼卡头或加齿轮 / 平台跳转时直接用。
+ * @param props.t - 刷新那两句文案（刷新 / 刷新中）的翻译函数。
+ * @param props.title - 卡标题；`props.meta` 是它右侧那一小段补充，不给不占位。
+ * @param props.refreshing - 正在刷新：刷新钮禁用并转圈。
+ * @param props.onRefresh - 点刷新钮做什么。
+ * @param props.gear - 齿轮钮的读屏名；`gearOpen` 控制它高亮、`onToggleGear` 是点击回调，三者一起给才画。
+ * @param props.platformHref - 整张卡对应系统的地址：给了就画那颗 ↗（新窗口），tooltip 用 `platformTitle`，缺了退化用 `platform`。
+ * @returns 一个 `<header>`。
+ */
 export function CardHead({ t, title, meta, refreshing, onRefresh, gear, gearOpen, onToggleGear, platformHref, platform, platformTitle, }) {
     const refreshLabel = refreshing ? t('rightbar.refreshing') : t('rightbar.refresh');
     const platformLabel = platformTitle ?? platform ?? t('rightbar.openPlatform');

package/dist/components/ChoiceGroup.d.ts

@@ -1,5 +1,8 @@
 import type { ReactNode } from '../lib/react.js';
 import './ChoiceGroup.css';
+/**
+ * 一个候选项：值、人看的标签，可带一行说明。
+ */
 export interface ChoiceGroupOption {
     readonly value: string;
     readonly label: ReactNode;
@@ -15,16 +18,37 @@ interface ChoiceGroupCommon {
     readonly loadingText?: ReactNode | undefined;
     readonly emptyText?: ReactNode | undefined;
 }
+/**
+ * 单选那一支的契约：`value` + `onChange(next)`；`multi` 不给或给 false。
+ */
 export interface ChoiceGroupSingleProps extends ChoiceGroupCommon {
     readonly multi?: false | undefined;
     readonly value: string;
     readonly onChange: (next: string) => void;
 }
+/**
+ * 多选那一支的契约：`multi: true` + `values` + `onChange(next[])`。
+ */
 export interface ChoiceGroupMultiProps extends ChoiceGroupCommon {
     readonly multi: true;
     readonly values: readonly string[];
     readonly onChange: (next: readonly string[]) => void;
 }
+/**
+ * `ChoiceGroup` 的契约：单选与多选两支的联合。
+ */
 export type ChoiceGroupProps = ChoiceGroupSingleProps | ChoiceGroupMultiProps;
+/**
+ * 一组单选或多选：候选少、要一眼看全时用它；候选多或要搜索就用 `SelectField`。
+ * @param props.multi - true 走多选那支（`values` / `onChange(string[])`）；默认单选（`value` / `onChange(string)`）。
+ * @param props.label - 只给读屏的组名（`aria-label`）。
+ * @param props.name - 这一组 `input` 的共用 name。
+ * @param props.options - 候选项，按给的顺序排；空数组时画 `emptyText`（没给就什么都不画）。
+ * @param props.disabled - 禁掉整组（默认 false），不是单颗。
+ * @param props.variant - `boxed`（默认，带边框的选项格）或 `ghost`（无边框，跟着父容器走）。
+ * @param props.loading - 正在读候选：整组换成转圈，文案取 `loadingText`（不给是 `…`）；默认 false。
+ * @param props.emptyText - 读到了但一个候选都没有时那句话；不给不画。
+ * @returns 一组 `radio` / `checkbox` 选项。
+ */
 export declare function ChoiceGroup(props: ChoiceGroupProps): JSX.Element;
 export {};

package/dist/components/ChoiceGroup.js

@@ -17,6 +17,18 @@ function ChoiceMenu(input) {
     }));
     return (h("div", { className: "wb-choiceMenu", "data-variant": input.variant, role: input.multi ? 'group' : 'radiogroup', "aria-label": input.label, "aria-busy": input.loading ? true : undefined }, body));
 }
+/**
+ * 一组单选或多选：候选少、要一眼看全时用它；候选多或要搜索就用 `SelectField`。
+ * @param props.multi - true 走多选那支（`values` / `onChange(string[])`）；默认单选（`value` / `onChange(string)`）。
+ * @param props.label - 只给读屏的组名（`aria-label`）。
+ * @param props.name - 这一组 `input` 的共用 name。
+ * @param props.options - 候选项，按给的顺序排；空数组时画 `emptyText`（没给就什么都不画）。
+ * @param props.disabled - 禁掉整组（默认 false），不是单颗。
+ * @param props.variant - `boxed`（默认，带边框的选项格）或 `ghost`（无边框，跟着父容器走）。
+ * @param props.loading - 正在读候选：整组换成转圈，文案取 `loadingText`（不给是 `…`）；默认 false。
+ * @param props.emptyText - 读到了但一个候选都没有时那句话；不给不画。
+ * @returns 一组 `radio` / `checkbox` 选项。
+ */
 export function ChoiceGroup(props) {
     const common = {
         label: props.label,

package/dist/components/Field.d.ts

@@ -1,8 +1,18 @@
 import type { ReactNode } from '../lib/react.js';
 import './Field.css';
+/**
+ * `Field` 的契约：一行"标签 + 控件 + 说明"的排布。
+ */
 export interface FieldProps {
     readonly label: ReactNode;
     readonly hint?: ReactNode | undefined;
     readonly children?: ReactNode | undefined;
 }
+/**
+ * 标签 + 控件的排布：没进 `FormRow` 时用它兜住一个字段的标签与说明。
+ * @param props.label - 左侧标签，必给。
+ * @param props.hint - 控件下面那行说明；不给不画。
+ * @param props.children - 控件本体，落在标签与说明之间。
+ * @returns 一个 `<label>`，点标签会聚焦里面的控件。
+ */
 export declare function Field({ label, hint, children }: FieldProps): JSX.Element;

package/dist/components/Field.js

@@ -1,5 +1,12 @@
 import { h } from '../lib/react.js';
 import './Field.css';
+/**
+ * 标签 + 控件的排布：没进 `FormRow` 时用它兜住一个字段的标签与说明。
+ * @param props.label - 左侧标签，必给。
+ * @param props.hint - 控件下面那行说明；不给不画。
+ * @param props.children - 控件本体，落在标签与说明之间。
+ * @returns 一个 `<label>`，点标签会聚焦里面的控件。
+ */
 export function Field({ label, hint, children }) {
     return (h("label", { className: "wb-field" },
         h("span", { className: "wb-fieldLabel" }, label),

package/dist/components/Form.css

@@ -0,0 +1,6 @@
+.wb-form {
+  display: flex;
+  flex-direction: column;
+  gap: var(--wb-len-12);
+  width: 100%;
+}

package/dist/components/Form.d.ts

@@ -0,0 +1,20 @@
+import type { FormProps } from './FormTypes.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 declare function Form(props: FormProps): JSX.Element;

package/dist/components/Form.js

@@ -0,0 +1,58 @@
+import { h, useEffect, useRef, useState } from '../lib/react.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) {
+    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(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 = () => {
+        if (busy || disabled)
+            return;
+        const outcome = formSubmitOf(visibleFieldsOf(fields));
+        setDone(true);
+        if (outcome.blocked) {
+            setReveal((count) => count + 1);
+            return;
+        }
+        onSubmit(outcome.values);
+    };
+    return (h("form", { className: "wb-form", ref: rootRef, noValidate: true, onSubmit: (event) => {
+            event.preventDefault();
+            submitForm();
+        } },
+        h(FormRows, null, formRowsOf({ fields: shown, problems, showProblem: done, busy })),
+        problem === undefined ? null : h(Note, { tone: 'problem', role: 'alert' }, problem),
+        h(FormActions, { actions: formActionsOf({ extra, cancel, submit, busy, disabled, onSubmitClick: submitForm }) })));
+}

package/dist/components/FormActions.d.ts

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

package/dist/components/FormActions.js

@@ -26,6 +26,11 @@ function variantOf(kind) {
         return 'outline';
     return 'ghost';
 }
+/**
+ * 操作区：把一组动作按"primary 永远在右、danger 紧挨它左侧"排好，窄了自动折行。
+ * @param props.actions - 动作清单；调用点给的顺序只在同语气内部生效，空数组时整块不渲染。
+ * @returns 一排按钮，或 `null`（没有动作时）。
+ */
 export function FormActions({ actions }) {
     if (actions.length === 0)
         return null;