@dsh-workbench/shared 0.3.3 → 0.3.5

package/src/api/unit-declaration.ts

@@ -1,20 +1,35 @@
 import type { UnitEnvNeeds, UnitHostNeeds, UnitManifest } from './unit.js';
 
+/**
+ * 声明协议当前版本；模块清单的 dsh.workbench.apiVersion 要写这个整数。
+ */
 export const WORKBENCH_API_VERSION = 1;
 
+/**
+ * 外壳愿意认的协议版本；不在表里的模块当场被拒，不猜语义。
+ */
 export const SUPPORTED_API_VERSIONS: readonly number[] = [WORKBENCH_API_VERSION];
 
+/**
+ * 清单里那半张卡片声明：文案键加排序位；卡片默认显不显示不在这里（那是运行期面板配置的事）。
+ */
 export interface UnitCardDeclaration {
   readonly titleKey: string;
   readonly order: number;
 }
 
+/**
+ * 清单里的一条工具声明：进 dsh 工具表的全名、会不会写，以及生成物里的键名。
+ */
 export interface UnitToolDeclaration {
   readonly name: string;
   readonly writes: boolean;
   readonly key?: string;
 }
 
+/**
+ * 模块清单里 dsh.workbench 那一段的完整形状（协议版本、单元 id、卡片、工具、宿主与环境需要）。
+ */
 export interface UnitDeclaration {
   readonly apiVersion: number;
   readonly unit: string;
@@ -24,6 +39,9 @@ export interface UnitDeclaration {
   readonly env?: UnitEnvNeeds;
 }
 
+/**
+ * 协议认得的全部键；写了别的键不会被采纳（外壳静默忽略），所以字段名拼错不会有提示。
+ */
 export const DECLARATION_KEYS: readonly string[] = [
   'apiVersion',
   'unit',
@@ -33,6 +51,9 @@ export const DECLARATION_KEYS: readonly string[] = [
   'env',
 ];
 
+/**
+ * 协议要求必写的键；env 不在其中（没有环境需要就不写）。
+ */
 export const DECLARATION_REQUIRED_KEYS: readonly string[] = [
   'apiVersion',
   'unit',
@@ -70,6 +91,12 @@ function stringArrayProblems(at: string, value: unknown): string[] {
   );
 }
 
+/**
+ * 查清单里 dsh.workbench 那一段的形状，回一串给人看的问题（中文，带字段路径）。
+ * @param subject 报错时用的主语，一般是包名。
+ * @param raw 清单里那段原始值，可能什么都不是。
+ * @returns 空数组表示形状过得去；版本不对就当场返回（后面的字段无从判起）。
+ */
 export function declarationProblemsOf(subject: string, raw: unknown): readonly string[] {
   if (!isRecord(raw)) return [`${subject}: dsh.workbench 不是一个对象 —— ${JSON.stringify(raw)}`];
 
@@ -207,12 +234,21 @@ export function declarationProblemsOf(subject: string, raw: unknown): readonly s
   return problems;
 }
 
+/**
+ * 读一份清单的结果：要么带着规整过的声明与 manifest，要么只带一串问题。
+ */
 export interface DeclarationRead {
   readonly declaration?: UnitDeclaration;
   readonly manifest?: UnitManifest;
   readonly problems: readonly string[];
 }
 
+/**
+ * 读一份清单：先查形状，过了再把声明规整成 manifest。
+ * @param subject 报错时用的主语。
+ * @param raw 清单里 dsh.workbench 那段原始值。
+ * @returns 有问题时只有 problems；没问题时 declaration 与 manifest 都给，manifest 里的字符串已 trim。
+ */
 export function readDeclaration(subject: string, raw: unknown): DeclarationRead {
   const problems = declarationProblemsOf(subject, raw);
   if (problems.length > 0) return { problems };

package/src/api/unit.ts

@@ -1,18 +1,30 @@
+/**
+ * 一张卡片在清单里的静态声明（文案键加排序位）；默认显不显示由运行期面板配置定。
+ */
 export interface UnitCard {
   readonly titleKey: string;
   readonly order: number;
 }
 
+/**
+ * 一条工具在清单里的样子：全名加会不会写；审批按 writes 认领。
+ */
 export interface UnitTool {
   readonly name: string;
   readonly writes: boolean;
 }
 
+/**
+ * 模块要外壳的哪些服务：inject 缺一个就挂不上，optional 缺了照挂。
+ */
 export interface UnitHostNeeds {
   readonly inject: readonly string[];
   readonly optional?: readonly string[];
 }
 
+/**
+ * 一个 opencli 插件的来源三选一（git / 本地 / npm）；npm 那支的安装源先看 registryEnv 那个环境变量，没设才用 registryDefault。
+ */
 export type PluginSource =
   | { readonly kind: 'git'; readonly url: string }
   | { readonly kind: 'local'; readonly env: string }
@@ -23,12 +35,18 @@ export type PluginSource =
       readonly registryDefault?: string;
     };
 
+/**
+ * 模块要的一个 opencli 插件：名字、它得提供的命令，以及装它的来源（没写就是不代装）。
+ */
 export interface UnitPluginNeed {
   readonly name: string;
   readonly commands?: readonly string[];
   readonly installSource?: PluginSource;
 }
 
+/**
+ * 模块要的一个共用库：名字、期望范围与它为什么要这个版本（purpose 会进申报文案）。
+ */
 export interface UnitLibNeed {
   readonly name: string;
   readonly version?: string | undefined;
@@ -37,17 +55,26 @@ export interface UnitLibNeed {
   readonly purpose: string;
 }
 
+/**
+ * 模块的整份环境需要：一条自检命令，加上插件与共用库两张表。
+ */
 export interface UnitEnvNeeds {
   readonly command?: string;
   readonly plugins?: readonly UnitPluginNeed[];
   readonly libs?: readonly UnitLibNeed[];
 }
 
+/**
+ * 已装插件与源上最新版那一对，用来判该不该提示升级；latest 缺省表示还没查到。
+ */
 export interface PluginRelease {
   readonly installed: string;
   readonly latest?: string;
 }
 
+/**
+ * 装配期用的模块清单：单元 id、卡片、工具与宿主 / 环境需要，比声明少一层协议包装。
+ */
 export interface UnitManifest {
   readonly id: string;
   readonly card: UnitCard | null;
@@ -56,6 +83,11 @@ export interface UnitManifest {
   readonly env?: UnitEnvNeeds;
 }
 
+/**
+ * 判这个模块要不要往外装东西。
+ * @param manifest 模块清单。
+ * @returns 插件与共用库两张表都空时给 false。
+ */
 export function hasEnvSupply(manifest: UnitManifest): boolean {
   return (manifest.env?.plugins ?? []).length > 0 || (manifest.env?.libs ?? []).length > 0;
 }

package/src/api/workbench-client.ts

@@ -1,5 +1,8 @@
 import { API_PREFIX } from '../config/constants.js';
 
+/**
+ * 宿主读口 / 写口回的错误：code 给判据分档，message 给人看，helpUrl 有就去点。
+ */
 export interface ApiError {
   readonly code: string;
   readonly message: string;
@@ -8,14 +11,30 @@ export interface ApiError {
   readonly helpUrl?: string;
 }
 
+/**
+ * 读口的统一响应：成了把载荷摊平在顶层，没成只有一条 ApiError。
+ */
 export type ApiResponse<T> = ({ readonly ok: true } & T) | { readonly ok: false; readonly error: ApiError };
 
+/**
+ * GET 的查询参数：值为 undefined 的键直接丢掉，不进 URL。
+ */
 export type Query = Record<string, string | number | boolean | undefined>;
 
+/**
+ * GET 的可选项；目前只有中止信号。
+ */
 export interface ApiGetOptions {
   readonly signal?: AbortSignal | undefined;
 }
 
+/**
+ * 打一条宿主读口。
+ * @param route 路由，相对 API_PREFIX，不带前导斜杠。
+ * @param query 查询参数，undefined 的值不序列化。
+ * @param options 中止信号等。
+ * @returns HTTP 不是 2xx 时给 ok: false（code 为 http）；响应体不是 JSON 会当场抛，调用点要接住。
+ */
 export async function apiGet<T>(
   route: string,
   query: Query = {},
@@ -44,6 +63,12 @@ export async function apiGet<T>(
   return (await response.json()) as ApiResponse<T>;
 }
 
+/**
+ * 打一条宿主写口。
+ * @param route 路由，相对 API_PREFIX，不带前导斜杠。
+ * @param body 请求体，按 JSON 序列化。
+ * @returns HTTP 不是 2xx 时给 ok: false（code 为 http）；响应体不是 JSON 会当场抛。
+ */
 export async function apiPost<T>(route: string, body: Record<string, unknown>): Promise<ApiResponse<T>> {
   const response = await fetch(`${API_PREFIX}/${route}`, {
     method: 'POST',

package/src/api/workbench-contract.ts

@@ -1,5 +1,8 @@
 import type { PluginRelease } from '../api/unit.js';
 
+/**
+ * 供给动作的那几档（装 / 升 / 卸，模块、共用依赖与插件各一套）；写口按它分派。
+ */
 export type ProvisionAction =
   | 'install'
   | 'update'
@@ -13,6 +16,9 @@ export type ProvisionAction =
   | 'uninstall-plugin'
   | 'update-workbench';
 
+/**
+ * 宿主报的一个 opencli 插件此刻的状态：装没装、缺哪些命令、该不该升，以及怎么升。
+ */
 export interface PluginStatePayload {
   readonly name: string;
   readonly status: 'ok' | 'outdated' | 'missing';
@@ -22,6 +28,9 @@ export interface PluginStatePayload {
   readonly release?: PluginRelease;
 }
 
+/**
+ * 宿主对「这个单元现在能不能用」的那份读数：状态、缺的命令与插件、修复动作和供给细节。
+ */
 export interface CapabilityPayload {
   readonly unit: string;
   readonly status: 'ok' | 'failed' | 'missing-commands' | 'missing-plugin' | 'unchecked';
@@ -37,6 +46,9 @@ export interface CapabilityPayload {
   readonly libs?: readonly LibStatePayload[];
 }
 
+/**
+ * 宿主报的一个共用库此刻的状态（装没装、版本对不对）与它为什么要这个版本。
+ */
 export interface LibStatePayload {
   readonly name: string;
   readonly purpose: string;

package/src/components/Activity.tsx

@@ -3,11 +3,20 @@ import { Button, Tooltip } from '@deepseek-ai/dsh-client-ui-primitives';
 import { h } 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 function ActivityBlock({ head, children }: ActivityBlockProps) {
   return (
     <div className="wb-activityBlock">
@@ -17,6 +26,9 @@ export function ActivityBlock({ head, children }: ActivityBlockProps) {
   );
 }
 
+/**
+ * `ActivityLine` 的契约：状态点、正文、时间与行尾动作。
+ */
 export interface ActivityLineProps {
   readonly dot?: ReactNode | undefined;
   readonly text: ReactNode;
@@ -24,6 +36,14 @@ export interface ActivityLineProps {
   readonly actions?: ReactNode | undefined;
 }
 
+/**
+ * 一条活动：状态点 + 正文 + 时间，行尾可挂动作；时间一律用它，别自己拼。
+ * @param props.dot - 行首那枚状态点；不给就只留正文。
+ * @param props.text - 这一条干了什么。
+ * @param props.at - 时间那一格（相对时间文本）；不给不画。
+ * @param props.actions - 行尾动作，通常是一两颗 `ActivityAction`；不给不画。
+ * @returns 一行。
+ */
 export function ActivityLine({ dot, text, at, actions }: ActivityLineProps) {
   return (
     <div className="wb-activityLine">
@@ -35,6 +55,9 @@ export function ActivityLine({ dot, text, at, actions }: ActivityLineProps) {
   );
 }
 
+/**
+ * `ActivityAction` 的契约：一颗图标钮、一个外链，或一个失败态。
+ */
 export interface ActivityActionProps {
   readonly label: string;
   readonly hint?: string | undefined;
@@ -44,6 +67,16 @@ export interface ActivityActionProps {
   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 function ActivityAction({ label, hint, icon, href, onClick, failed }: ActivityActionProps) {
   const tip = hint ?? label;
   if (href !== undefined) {

package/src/components/ApprovalDetail.tsx

@@ -1,6 +1,6 @@
 import type { Translate } from '../api/dsh-client.js';
 import type { ApprovalInput, UnitClientFace } from '../components/board-module.js';
-import { h } from '../lib/react.js';
+import { Fragment, h, type ReactNode } from '../lib/react.js';
 import { CodeBlock } from '@deepseek-ai/dsh-client-ui-primitives';
 import { CardBoundary } from './CardBoundary.js';
 import './ApprovalDetail.css';
@@ -18,11 +18,15 @@ interface ChatSnapshot {
 
 type UseChat = <T>(selector: (snapshot: ChatSnapshot) => T) => T | undefined;
 
+/**
+ * `ApprovalDetail` 的契约：调用 id、读会话快照的钩子、已装模块与兜底渲染。
+ */
 export interface ApprovalDetailProps {
   readonly callId?: string;
   readonly useChat?: UseChat;
   readonly units?: readonly UnitClientFace[];
   readonly t?: Translate;
+  readonly renderShell?: ((input: ApprovalInput, t: Translate) => ReactNode) | undefined;
 }
 
 function callOf(snapshot: ChatSnapshot, callId: string | undefined): { name?: string; argsRaw: string } | undefined {
@@ -44,6 +48,15 @@ function parseArgs(raw: string): Readonly<Record<string, unknown>> {
   }
 }
 
+/**
+ * 审批屏的详情格：按工具名找到认领它的模块交给它渲染，没有模块认领就退回外壳那张表或一段原始命令。
+ * @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: ApprovalDetailProps) {
   const useChat = props.useChat ?? ((): undefined => undefined);
   const call = useChat((snapshot) => callOf(snapshot, props.callId));
@@ -63,6 +76,9 @@ export function ApprovalDetail(props: ApprovalDetailProps) {
     );
   }
 
+  const shell = props.renderShell?.(input, t);
+  if (shell !== undefined && shell !== null) return <Fragment>{shell}</Fragment>;
+
   if (command === '') return null;
   return (
     <CodeBlock

package/src/components/ApprovalPlan.tsx

@@ -2,11 +2,17 @@ import type { ReactNode } from '../lib/react.js';
 import { h } 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;
@@ -14,6 +20,14 @@ export interface ApprovalPlanProps {
   readonly children?: ReactNode | undefined;
 }
 
+/**
+ * 审批屏那张"这次要做什么"的表：一行一项，上面可给一句附注、下面可给一句警告。
+ * @param props.rows - 详情行，按给的顺序渲染；空数组时只剩附注与警告。
+ * @param props.hint - 表上面那句说明；不给不画。
+ * @param props.warn - 表下面那句警告；不给不画。
+ * @param props.children - 插在表与 `warn` 之间的补充内容。
+ * @returns 一个 div。
+ */
 export function ApprovalPlan({ rows, hint, warn, children }: ApprovalPlanProps) {
   return (
     <div className="wb-approvalPlan">

package/src/components/Card.tsx

@@ -4,6 +4,9 @@ import { h } from '../lib/react.js';
 import { CardHead } from './CardHead.js';
 import './Card.css';
 
+/**
+ * `Card` 的契约：标题、刷新、卡片体，以及可整块替换的卡头。
+ */
 export interface CardProps {
   readonly t: Translate;
   readonly title: string;
@@ -14,6 +17,16 @@ export interface CardProps {
   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 function Card({ t, title, refreshing, onRefresh, meta, head, children }: CardProps) {
   return (
     <section className="wb-card">

package/src/components/CardAnchor.tsx

@@ -2,15 +2,29 @@ import type { ReactNode } from '../lib/react.js';
 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: string | null): string | undefined {
   return unit === null || unit === '' ? undefined : `wb-card-${unit}`;
 }
 
+/**
+ * `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 function CardAnchor({ unit, children }: CardAnchorProps) {
   return (
     <div id={cardIdOf(unit)} className={styles.anchor}>

package/src/components/CardBoundary.tsx

@@ -4,6 +4,9 @@ import type { ReactNode } from '../lib/react.js';
 import { Component, h } from '../lib/react.js';
 import { Note } from './Note.js';
 
+/**
+ * `CardBoundary` 的契约：被守的 unit、重来键与失败回调。
+ */
 export interface CardBoundaryProps {
   readonly unit: string;
   readonly resetKey: string;
@@ -12,15 +15,32 @@ export interface CardBoundaryProps {
   readonly children?: ReactNode | undefined;
 }
 
+/**
+ * `CardBoundary` 的状态：这次渲染炸出来的那句话，没炸是 `null`。
+ */
 export interface CardBoundaryState {
   readonly reason: string | null;
 }
 
+/**
+ * 把抛出来的任何东西收成一句人能看的失败原因，上报与展示都用它。
+ * @param error - 抛出来的值：`Error` 取 `message`，字符串原样，其余走 JSON。
+ * @returns 一句原因文本；`Error('')` 这种没带 message 的会回空串（调用点别把它当"一定有话"）。
+ */
 export function errorReasonOf(error: unknown): string {
   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<CardBoundaryProps, CardBoundaryState> {
   override state: CardBoundaryState = { reason: null };
 

package/src/components/CardHead.tsx

@@ -10,6 +10,9 @@ import {
 import { h } from '../lib/react.js';
 import './CardHead.css';
 
+/**
+ * `CardHead` 的契约：标题、补充、刷新，外加齿轮与平台跳转两格。
+ */
 export interface CardHeadProps {
   readonly t: Translate;
   readonly title: string;
@@ -24,6 +27,16 @@ export interface CardHeadProps {
   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 function CardHead({
   t,
   title,

package/src/components/ChoiceGroup.tsx

@@ -4,6 +4,9 @@ import { IconCheckOutlineRegular } from '@deepseek-ai/dsh-client-ui-primitives';
 import { Spinner } from './Spinner.js';
 import './ChoiceGroup.css';
 
+/**
+ * 一个候选项：值、人看的标签，可带一行说明。
+ */
 export interface ChoiceGroupOption {
   readonly value: string;
   readonly label: ReactNode;
@@ -21,18 +24,27 @@ interface ChoiceGroupCommon {
   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;
 
 interface ChoiceRowState {
@@ -110,6 +122,18 @@ function ChoiceMenu(input: {
   );
 }
 
+/**
+ * 一组单选或多选：候选少、要一眼看全时用它；候选多或要搜索就用 `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: ChoiceGroupProps) {
   const common = {
     label: props.label,

package/src/components/Field.tsx

@@ -2,12 +2,22 @@ import type { ReactNode } from '../lib/react.js';
 import { h } 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 function Field({ label, hint, children }: FieldProps) {
   return (
     <label className="wb-field">

package/src/components/Form.css

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