@dsh-workbench/shared 0.3.4 → 0.3.6

package/dist/components/Note.d.ts

@@ -1,9 +1,20 @@
 import type { ReactNode } from '../lib/react.js';
 import './Note.css';
+/**
+ * `Note` 的契约：语气、标签名与读屏角色。
+ */
 export interface NoteProps {
     readonly tone?: 'muted' | 'problem';
     readonly as?: 'p' | 'span';
     readonly role?: 'alert' | 'status';
     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 declare function Note({ tone, as, role, children }: NoteProps): JSX.Element;

package/dist/components/Note.js

@@ -1,5 +1,13 @@
 import { h } from '../lib/react.js';
 import './Note.css';
+/**
+ * 一句话说明或一句报错：卡片里的提示条用它，不承载交互。
+ * @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 }) {
     const className = tone === 'problem' ? 'wb-problem' : 'wb-note';
     return as === 'span' ? (h("span", { className: className, role: role }, children)) : (h("p", { className: className, role: role }, children));

package/dist/components/ResourceStates.d.ts

@@ -1,8 +1,16 @@
 import type { ReactNode } from 'react';
 import './ResourceStates.css';
+/**
+ * 骨架屏：读数期间已经知道大概形状时用它（连形状都不知道就用 `CenteredState` 那句"正在读"）。
+ * @param props.rows - 画几行骨架（默认 4）；整块 `aria-hidden`，不读给读屏。
+ * @returns 一叠占位条。
+ */
 export declare function SkeletonRows({ rows }: {
     rows?: number;
 }): JSX.Element;
+/**
+ * `CenteredState` 的契约：图标、标题、说明、明细与动作。
+ */
 export interface CenteredStateProps {
     icon: ReactNode;
     title: ReactNode;
@@ -11,7 +19,24 @@ export interface CenteredStateProps {
     action?: ReactNode;
     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 declare function CenteredState({ icon, title, hint, detail, action, compact }: CenteredStateProps): JSX.Element;
+/**
+ * 就绪但空：它只是 `CenteredState` 的简写，标题就是那句空态文案。
+ * @param props.text - 空态那句话。
+ * @param props.icon - 标题上方的图标；默认 `null`，不画图标。
+ * @param props.compact - 紧凑档，默认 false。
+ * @returns 一个居中块。
+ */
 export declare function EmptyState({ text, icon, compact }: {
     text: string;
     icon?: ReactNode;

package/dist/components/ResourceStates.js

@@ -1,10 +1,25 @@
 import { h } from '../lib/react.js';
 import './ResourceStates.css';
+/**
+ * 骨架屏：读数期间已经知道大概形状时用它（连形状都不知道就用 `CenteredState` 那句"正在读"）。
+ * @param props.rows - 画几行骨架（默认 4）；整块 `aria-hidden`，不读给读屏。
+ * @returns 一叠占位条。
+ */
 export function SkeletonRows({ rows = 4 }) {
     return (h("div", { className: "wb-skeleton", "aria-hidden": "true" }, Array.from({ length: rows }, (_, index) => (h("span", { key: index, className: "wb-skeletonRow" },
         h("span", { className: "wb-skeletonBar wb-skeletonBarTitle" }),
         h("span", { className: "wb-skeletonBar wb-skeletonBarMeta" }))))));
 }
+/**
+ * 居中一屏：要他先选一个 / 正在读 / 读不到时用它占住卡片版面。
+ * @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 }) {
     return (h("div", { className: compact ? 'wb-centered wb-centeredCompact' : 'wb-centered', role: "status" },
         icon === null ? null : (h("span", { className: "wb-centeredHero", "aria-hidden": "true" }, icon)),
@@ -13,6 +28,13 @@ export function CenteredState({ icon, title, hint, detail, action, compact = fal
         detail === undefined ? null : h("div", { className: "wb-centeredDetail" }, detail),
         action === undefined ? null : h("div", { className: "wb-centeredAction" }, action)));
 }
+/**
+ * 就绪但空：它只是 `CenteredState` 的简写，标题就是那句空态文案。
+ * @param props.text - 空态那句话。
+ * @param props.icon - 标题上方的图标；默认 `null`，不画图标。
+ * @param props.compact - 紧凑档，默认 false。
+ * @returns 一个居中块。
+ */
 export function EmptyState({ text, icon = null, compact = false }) {
     return h(CenteredState, { icon: icon, title: text, compact: compact });
 }

package/dist/components/Rows.d.ts

@@ -1,11 +1,28 @@
 import type { ReactNode } 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 declare function Rows({ children }: RowsProps): JSX.Element;
+/**
+ * `Row` 的契约：左边名字 + 右边值。
+ */
 export interface RowProps {
     readonly label: ReactNode;
     readonly value: ReactNode;
 }
+/**
+ * 一行键值：左边名字、右边值；要成对说明一项数据就用它，别自己写两栏。
+ * @param props.label - 左边那格（键）。
+ * @param props.value - 右边那格（值），可以是数字、时间或一小段节点。
+ * @returns 一行两格。
+ */
 export declare function Row({ label, value }: RowProps): JSX.Element;

package/dist/components/Rows.js

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

package/dist/components/SaveBar.d.ts

@@ -1,3 +1,6 @@
+/**
+ * `SaveBar` 的契约：忙碌态、三句文案与两个回调。
+ */
 export interface SaveBarProps {
     readonly busy: boolean;
     readonly disabled?: boolean | undefined;
@@ -9,4 +12,13 @@ export interface SaveBarProps {
     readonly onCancel: () => void;
     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 declare function SaveBar({ busy, disabled, labels, onCancel, onSave }: SaveBarProps): JSX.Element;

package/dist/components/SaveBar.js

@@ -1,5 +1,14 @@
 import { h } from '../lib/react.js';
 import { FormActions } from './FormActions.js';
+/**
+ * 设置面底下那条"取消 / 保存"：就是 `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 }) {
     const actions = [
         { key: 'cancel', label: labels.cancel, kind: 'default', onClick: onCancel, disabled: busy },

package/dist/components/SelectField.d.ts

@@ -1,6 +1,7 @@
 import type { ReactNode } from 'react';
 import type { MenuEntry } from '@deepseek-ai/dsh-client-ui-primitives';
 import './SelectField.css';
+/** 一个候选项：值、人看的标签，可带搜索词、图标、分组与禁用标记。 */
 export interface SelectFieldOption {
     readonly value: string;
     readonly label: ReactNode;
@@ -9,14 +10,17 @@ export interface SelectFieldOption {
     readonly group?: string | undefined;
     readonly disabled?: boolean | undefined;
 }
+/** 名单读不到时的退路：值 + 变更回调，`SelectField` 会由下拉改成手填输入框。 */
 export interface SelectFieldFallback {
     readonly value: string;
     readonly onChange: (next: string) => void;
 }
+/** 列表底部固定那一条（如"添加工作区"）：文案 + 可选图标。 */
 export interface SelectFieldFooter {
     readonly label: ReactNode;
     readonly icon?: ReactNode | undefined;
 }
+/** `SelectField` 的契约：值、候选、变更回调，外加搜索 / 分组 / 加载 / 空态 / 页脚那一整套开关。 */
 export interface SelectFieldProps {
     readonly value: string;
     readonly options: readonly SelectFieldOption[];
@@ -51,10 +55,32 @@ export interface SelectFieldProps {
     readonly className?: string | undefined;
     readonly menuClassName?: string | undefined;
 }
+/** 算候选项用来匹配搜索的文本：有 `searchText` 就用它，否则取字符串标签；标签不是字符串又没给它是空串（这项搜不到）。 */
 export declare function searchTextOf(option: SelectFieldOption): string;
+/** 默认匹配：查询去空白折成小写后看它是不是 `searchTextOf` 的子串；查询为空或纯空白时一律命中（留在列表里）。 */
 export declare function defaultSelectFilter(option: SelectFieldOption, query: string): boolean;
+/** 按查询过滤候选 —— 组件与模块自己算列表都用它，好让同一份口径管两处：`filter` 不给就用 `defaultSelectFilter`，顺序不变。 */
 export declare function filterSelectOptions(options: readonly SelectFieldOption[], query: string, filter?: (option: SelectFieldOption, query: string) => boolean): readonly SelectFieldOption[];
+/** 把键盘游标换算成当前该高亮那项的 value：游标 `null`（还没动过键盘）或列表为空时没有高亮；太大的游标收到最后一项，负游标取不到项也回 `null`。 */
 export declare function selectCursorValue(shown: readonly SelectFieldOption[], cursor: number | null): string | null;
+/** 按上下键移动游标（两头环绕）：还没选过时向下取第一项、向上取最后一项；列表为空回 `null`（一步都动不了）。`step` 1 向下、-1 向上。 */
 export declare function stepSelectCursor(shown: readonly SelectFieldOption[], cursor: number | null, step: 1 | -1): number | null;
+/** 把候选排成 `Menu` 要的条目表：按 `group` 插分组标题；一项都没有时退回 `emptyText` 那一行（不给就是空表）。`revealId` 是开列表时要滚进可视区的那个 value。 */
 export declare function selectEntries(shown: readonly SelectFieldOption[], emptyText: string | undefined, revealId?: string | undefined): readonly MenuEntry[];
+/**
+ * 下拉选择：默认是跟 `TextField` 一套的常规下拉框（不是原生 `<select>`），无边框那种给 `variant: 'ghost'`。
+ * `open` 不给就内部自己管（两种接法下 `onOpenChange` 都会通知），`loading` 把触发器换成转圈 + `loadingText`（默认 `…`），
+ * `selection` 选选中行标记（`fill` 整行底色 / `check` 行尾勾），`footer` 是列表底部那一条（点它走 `onFooter`，不改当前值）。
+ * @param props.value - 当前值；在 `options` 里找不到就按"没选"画 `placeholder`。
+ * @param props.options - 全量候选；空数组且给了 `fallback` 时改画手填输入框。
+ * @param props.onChange - 选中一项后的回调，回的是那一项的 `value`。
+ * @param props.label - 没进 `FormRow` 时的标签兜底；进了那一行就别再给它和 `hint`，否则会多一个标签。
+ * @param props.renderValue - 自己渲染触发器上那份当前值；不给就用候选项的 `label`。
+ * @param props.placeholder - 没选中时那句话；不给是 `—`。
+ * @param props.search - 是否可搜（默认 true）；`false` 时不画搜索框、也不自动聚焦。
+ * @param props.filter - 自定义匹配；不给用 `defaultSelectFilter`（空白查询一律命中）。
+ * @param props.emptyText - 无匹配时的文案，或按查询生成文案的函数（能说"没有匹配 X 的项"）。
+ * @param props.fallback - 退路：`options` 为空时改成手填（`value` + `onChange`）。
+ * @returns 触发器，以及打开时的搜索框与列表。
+ */
 export declare function SelectField(props: SelectFieldProps): ReactNode;

package/dist/components/SelectField.js

@@ -70,25 +70,30 @@ function framed(label, hint, className, control) {
         : (h(Field, { label: label, hint: hint }, control));
     return className === undefined ? inner : h("div", { className: className }, inner);
 }
+/** 算候选项用来匹配搜索的文本：有 `searchText` 就用它，否则取字符串标签；标签不是字符串又没给它是空串（这项搜不到）。 */
 export function searchTextOf(option) {
     if (option.searchText !== undefined)
         return option.searchText;
     return typeof option.label === 'string' ? option.label : '';
 }
+/** 默认匹配：查询去空白折成小写后看它是不是 `searchTextOf` 的子串；查询为空或纯空白时一律命中（留在列表里）。 */
 export function defaultSelectFilter(option, query) {
     const needle = query.trim().toLowerCase();
     if (needle === '')
         return true;
     return searchTextOf(option).toLowerCase().includes(needle);
 }
+/** 按查询过滤候选 —— 组件与模块自己算列表都用它，好让同一份口径管两处：`filter` 不给就用 `defaultSelectFilter`，顺序不变。 */
 export function filterSelectOptions(options, query, filter = defaultSelectFilter) {
     return options.filter((option) => filter(option, query));
 }
+/** 把键盘游标换算成当前该高亮那项的 value：游标 `null`（还没动过键盘）或列表为空时没有高亮；太大的游标收到最后一项，负游标取不到项也回 `null`。 */
 export function selectCursorValue(shown, cursor) {
     if (cursor === null || shown.length === 0)
         return null;
     return shown[Math.min(cursor, shown.length - 1)]?.value ?? null;
 }
+/** 按上下键移动游标（两头环绕）：还没选过时向下取第一项、向上取最后一项；列表为空回 `null`（一步都动不了）。`step` 1 向下、-1 向上。 */
 export function stepSelectCursor(shown, cursor, step) {
     if (shown.length === 0)
         return null;
@@ -96,6 +101,7 @@ export function stepSelectCursor(shown, cursor, step) {
         return step === 1 ? 0 : shown.length - 1;
     return (cursor + step + shown.length) % shown.length;
 }
+/** 把候选排成 `Menu` 要的条目表：按 `group` 插分组标题；一项都没有时退回 `emptyText` 那一行（不给就是空表）。`revealId` 是开列表时要滚进可视区的那个 value。 */
 export function selectEntries(shown, emptyText, revealId) {
     if (shown.length === 0) {
         return emptyText === undefined ? [] : [{ type: 'label', id: EMPTY_ID, text: emptyText }];
@@ -170,6 +176,22 @@ function useSelectState(props) {
         empty: typeof emptyText === 'function' ? emptyText(query) : emptyText,
     };
 }
+/**
+ * 下拉选择：默认是跟 `TextField` 一套的常规下拉框（不是原生 `<select>`），无边框那种给 `variant: 'ghost'`。
+ * `open` 不给就内部自己管（两种接法下 `onOpenChange` 都会通知），`loading` 把触发器换成转圈 + `loadingText`（默认 `…`），
+ * `selection` 选选中行标记（`fill` 整行底色 / `check` 行尾勾），`footer` 是列表底部那一条（点它走 `onFooter`，不改当前值）。
+ * @param props.value - 当前值；在 `options` 里找不到就按"没选"画 `placeholder`。
+ * @param props.options - 全量候选；空数组且给了 `fallback` 时改画手填输入框。
+ * @param props.onChange - 选中一项后的回调，回的是那一项的 `value`。
+ * @param props.label - 没进 `FormRow` 时的标签兜底；进了那一行就别再给它和 `hint`，否则会多一个标签。
+ * @param props.renderValue - 自己渲染触发器上那份当前值；不给就用候选项的 `label`。
+ * @param props.placeholder - 没选中时那句话；不给是 `—`。
+ * @param props.search - 是否可搜（默认 true）；`false` 时不画搜索框、也不自动聚焦。
+ * @param props.filter - 自定义匹配；不给用 `defaultSelectFilter`（空白查询一律命中）。
+ * @param props.emptyText - 无匹配时的文案，或按查询生成文案的函数（能说"没有匹配 X 的项"）。
+ * @param props.fallback - 退路：`options` 为空时改成手填（`value` + `onChange`）。
+ * @returns 触发器，以及打开时的搜索框与列表。
+ */
 export function SelectField(props) {
     const { value, options, onChange, label, hint, icon, renderValue, placeholder, search = true, searchLabel, searchPlaceholder, footer, onFooter, disabled = false, invalid = false, loading = false, loadingText, fallback, selection = 'fill', variant = 'boxed', iconOnly = false, revealId, ariaLabel, title, id, name, className, menuClassName, } = props;
     const state = useSelectState(props);

package/dist/components/SelectFieldNodes.d.ts

@@ -1,4 +1,19 @@
 import type { ReactNode } from 'react';
+/**
+ * 下拉触发器那颗按钮：图标 + 当前值 + 箭头，交给 `Menu` 当 anchor；宽窄两档共用一个形状。
+ * @param args.id - 触发器 id。
+ * @param args.className - 触发器类名（已含 variant 与 iconOnly 的档）。
+ * @param args.disabled - 是否禁用。
+ * @param args.invalid - 置真写 `aria-invalid`。
+ * @param args.open - 列表是否开着，写进 `aria-expanded`。
+ * @param args.ariaLabel - 读屏名。
+ * @param args.title - 原生提示。
+ * @param args.icon - 值左边那枚图标；不给不占位。
+ * @param args.value - 已渲染好的当前值节点（文本或占位）。
+ * @param args.iconOnly - 只画图标（窄栏那颗切换钮），值与箭头都不画。
+ * @param args.onOpen - 点它做什么，通常是把列表打开。
+ * @returns 一颗 `<button>`。
+ */
 export declare function selectTriggerNode(args: {
     readonly id: string | undefined;
     readonly className: string;
@@ -12,6 +27,15 @@ export declare function selectTriggerNode(args: {
     readonly iconOnly: boolean;
     readonly onOpen: () => void;
 }): ReactNode;
+/**
+ * 名单还没读到时的触发器：禁用 + `aria-busy` 的按钮，`SelectField` 在 `loading` 那档画它。
+ * @param args.id - 触发器 id。
+ * @param args.className - 触发器类名；它后面会接上 loading 那档的类。
+ * @param args.invalid - 置真写 `aria-invalid`。
+ * @param args.ariaLabel - 读屏名。
+ * @param args.loadingText - 占位文案；不给就是 `…`。
+ * @returns 一颗禁用且 `aria-busy` 的按钮。
+ */
 export declare function selectLoadingNode(args: {
     readonly id: string | undefined;
     readonly className: string;

package/dist/components/SelectFieldNodes.js

@@ -1,6 +1,21 @@
 import { Fragment, h } from '../lib/react.js';
 import { IconChevronDownOutlineRegular, TextShimmer, } from '@deepseek-ai/dsh-client-ui-primitives';
 import { Spinner } from './Spinner.js';
+/**
+ * 下拉触发器那颗按钮：图标 + 当前值 + 箭头，交给 `Menu` 当 anchor；宽窄两档共用一个形状。
+ * @param args.id - 触发器 id。
+ * @param args.className - 触发器类名（已含 variant 与 iconOnly 的档）。
+ * @param args.disabled - 是否禁用。
+ * @param args.invalid - 置真写 `aria-invalid`。
+ * @param args.open - 列表是否开着，写进 `aria-expanded`。
+ * @param args.ariaLabel - 读屏名。
+ * @param args.title - 原生提示。
+ * @param args.icon - 值左边那枚图标；不给不占位。
+ * @param args.value - 已渲染好的当前值节点（文本或占位）。
+ * @param args.iconOnly - 只画图标（窄栏那颗切换钮），值与箭头都不画。
+ * @param args.onOpen - 点它做什么，通常是把列表打开。
+ * @returns 一颗 `<button>`。
+ */
 export function selectTriggerNode(args) {
     return (h("button", { type: "button", id: args.id, className: args.className, disabled: args.disabled, "aria-haspopup": "listbox", "aria-expanded": args.open, "aria-invalid": args.invalid || undefined, "aria-label": args.ariaLabel, title: args.title, onClick: args.onOpen }, args.iconOnly ? (h("span", { className: "wb-selectIcon" }, args.icon)) : (h(Fragment, null,
         args.icon === undefined ? null : h("span", { className: "wb-selectIcon" }, args.icon),
@@ -8,6 +23,15 @@ export function selectTriggerNode(args) {
         h("span", { className: "wb-selectChevron" },
             h(IconChevronDownOutlineRegular, { size: 14 }))))));
 }
+/**
+ * 名单还没读到时的触发器：禁用 + `aria-busy` 的按钮，`SelectField` 在 `loading` 那档画它。
+ * @param args.id - 触发器 id。
+ * @param args.className - 触发器类名；它后面会接上 loading 那档的类。
+ * @param args.invalid - 置真写 `aria-invalid`。
+ * @param args.ariaLabel - 读屏名。
+ * @param args.loadingText - 占位文案；不给就是 `…`。
+ * @returns 一颗禁用且 `aria-busy` 的按钮。
+ */
 export function selectLoadingNode(args) {
     return (h("button", { type: "button", id: args.id, className: `${args.className} wb-selectLoading`, disabled: true, "aria-busy": "true", "aria-invalid": args.invalid || undefined, "aria-label": args.ariaLabel, title: args.loadingText },
         h("span", { className: "wb-selectValue" },

package/dist/components/SettingsSection.d.ts

@@ -1,9 +1,20 @@
 import type { ReactNode } from '../lib/react.js';
 import './SettingsSection.css';
+/**
+ * `SettingsSection` 的契约：一节的读屏名、标题、右上动作与内容。
+ */
 export interface SettingsSectionProps {
     readonly label: string;
     readonly title: ReactNode;
     readonly action?: ReactNode | undefined;
     readonly children?: ReactNode | undefined;
 }
+/**
+ * 设置面里的一节：标题 + 右上那颗动作 + 一节内容，把一屏设置分组。
+ * @param props.label - 只给读屏的组名（`aria-label`），不是标题。
+ * @param props.title - 人看的标题。
+ * @param props.action - 标题右侧的动作（如"添加"）；不给不占位。
+ * @param props.children - 这一节的内容。
+ * @returns 一个 `role="group"` 的 section。
+ */
 export declare function SettingsSection({ label, title, action, children }: SettingsSectionProps): JSX.Element;

package/dist/components/SettingsSection.js

@@ -1,5 +1,13 @@
 import { h } from '../lib/react.js';
 import './SettingsSection.css';
+/**
+ * 设置面里的一节：标题 + 右上那颗动作 + 一节内容，把一屏设置分组。
+ * @param props.label - 只给读屏的组名（`aria-label`），不是标题。
+ * @param props.title - 人看的标题。
+ * @param props.action - 标题右侧的动作（如"添加"）；不给不占位。
+ * @param props.children - 这一节的内容。
+ * @returns 一个 `role="group"` 的 section。
+ */
 export function SettingsSection({ label, title, action, children }) {
     return (h("section", { className: "wb-settings", role: "group", "aria-label": label },
         h("header", { className: "wb-settingsHead" },

package/dist/components/Spinner.d.ts

@@ -1,6 +1,15 @@
 import './Spinner.css';
+/**
+ * `Spinner` 的契约：直径像素与可选的读屏标签。
+ */
 export interface SpinnerProps {
     readonly size?: number;
     readonly label?: string | undefined;
 }
+/**
+ * 转圈：加载态一律用它（`FormActions` 与 `ChoiceGroup` 内部也是它），别自己写动画。
+ * @param props.size - 直径像素（默认 14，与 dsh 紧凑控件同高）。
+ * @param props.label - 给了才读屏可见（`role="status"`）；不给整颗 `aria-hidden`，此时旁边必须有文字。
+ * @returns 一枚 `StateDot state="ongoing"`，自身不带文字。
+ */
 export declare function Spinner({ size, label }: SpinnerProps): JSX.Element;

package/dist/components/Spinner.js

@@ -1,6 +1,12 @@
 import { StateDot } from '@deepseek-ai/dsh-client-ui-primitives';
 import { h } from '../lib/react.js';
 import './Spinner.css';
+/**
+ * 转圈：加载态一律用它（`FormActions` 与 `ChoiceGroup` 内部也是它），别自己写动画。
+ * @param props.size - 直径像素（默认 14，与 dsh 紧凑控件同高）。
+ * @param props.label - 给了才读屏可见（`role="status"`）；不给整颗 `aria-hidden`，此时旁边必须有文字。
+ * @returns 一枚 `StateDot state="ongoing"`，自身不带文字。
+ */
 export function Spinner({ size = 14, label }) {
     return (h("span", { className: "wb-spinner", ...(label === undefined ? { 'aria-hidden': true } : { role: 'status', 'aria-label': label }) },
         h(StateDot, { state: "ongoing", size: size })));

package/dist/components/Stack.d.ts

@@ -1,6 +1,14 @@
 import type { ReactNode } from '../lib/react.js';
 import './Stack.css';
+/**
+ * `Stack` 的契约：只带一个竖排内容槽。
+ */
 export interface StackProps {
     readonly children?: ReactNode | undefined;
 }
+/**
+ * 竖排容器：把相邻内容按统一间距摞起来，懒得自己分组时的默认外包装。
+ * @param props.children - 要竖排的内容；不给就渲染一个空容器。
+ * @returns 竖排的 div。
+ */
 export declare function Stack({ children }: StackProps): JSX.Element;

package/dist/components/Stack.js

@@ -1,5 +1,10 @@
 import { h } from '../lib/react.js';
 import './Stack.css';
+/**
+ * 竖排容器：把相邻内容按统一间距摞起来，懒得自己分组时的默认外包装。
+ * @param props.children - 要竖排的内容；不给就渲染一个空容器。
+ * @returns 竖排的 div。
+ */
 export function Stack({ children }) {
     return h("div", { className: "wb-stack" }, children);
 }

package/dist/components/StateBlock.d.ts

@@ -1,5 +1,8 @@
 import type { ReactNode } from '../lib/react.js';
 import './StateBlock.css';
+/**
+ * `StateBlock` 的契约：标题、状态点、提示、正文与行尾动作。
+ */
 export interface StateBlockProps {
     readonly title?: ReactNode | undefined;
     readonly dot?: ReactNode | undefined;
@@ -8,4 +11,14 @@ export interface StateBlockProps {
     readonly resolving?: ReactNode | undefined;
     readonly children?: ReactNode | undefined;
 }
+/**
+ * 有内容那一段：一个标题 + 一行提示 + 正文，卡里已经读到东西时用它开头。
+ * @param props.title - 标题那行；它与 `dot` 都不给时整行不画。
+ * @param props.dot - 标题前那枚状态点。
+ * @param props.hint - 标题下那行小字（如"3 条 · 刚刚"）；不给不画。
+ * @param props.resolving - "正在读"那行，读数期间挂上去；不给不画。
+ * @param props.actions - 底部动作区；给了才画那一条。
+ * @param props.children - 正文。
+ * @returns 一个 div。
+ */
 export declare function StateBlock({ title, dot, hint, actions, resolving, children }: StateBlockProps): JSX.Element;

package/dist/components/StateBlock.js

@@ -1,5 +1,15 @@
 import { h } from '../lib/react.js';
 import './StateBlock.css';
+/**
+ * 有内容那一段：一个标题 + 一行提示 + 正文，卡里已经读到东西时用它开头。
+ * @param props.title - 标题那行；它与 `dot` 都不给时整行不画。
+ * @param props.dot - 标题前那枚状态点。
+ * @param props.hint - 标题下那行小字（如"3 条 · 刚刚"）；不给不画。
+ * @param props.resolving - "正在读"那行，读数期间挂上去；不给不画。
+ * @param props.actions - 底部动作区；给了才画那一条。
+ * @param props.children - 正文。
+ * @returns 一个 div。
+ */
 export function StateBlock({ title, dot, hint, actions, resolving, children }) {
     return (h("div", { className: "wb-stateBlock" },
         title === undefined && dot === undefined ? null : (h("p", { className: "wb-stateBlockTitle" },

package/dist/components/TextField.d.ts

@@ -1,6 +1,14 @@
 import type { InputHTMLAttributes } from 'react';
 import './TextField.css';
+/**
+ * `TextField` 的契约：原生 input 属性，外加一个标红开关。
+ */
 export interface TextFieldProps extends InputHTMLAttributes<HTMLInputElement> {
     readonly invalid?: boolean;
 }
+/**
+ * 单行文本输入：设置面与筛选框都用它，`invalid` 之外的属性全部透传给原生 `<input>`。
+ * @param props.invalid - 置真标红并写 `aria-invalid`（默认 false）；错在哪一句归 `FormRow.problem`。
+ * @returns 输入框元素；`className` 是追加在基础类名之后，而不是替换它。
+ */
 export declare function TextField({ invalid, className, ...rest }: TextFieldProps): JSX.Element;

package/dist/components/TextField.js

@@ -1,5 +1,10 @@
 import './TextField.css';
 import { h } from '../lib/react.js';
+/**
+ * 单行文本输入：设置面与筛选框都用它，`invalid` 之外的属性全部透传给原生 `<input>`。
+ * @param props.invalid - 置真标红并写 `aria-invalid`（默认 false）；错在哪一句归 `FormRow.problem`。
+ * @returns 输入框元素；`className` 是追加在基础类名之后，而不是替换它。
+ */
 export function TextField({ invalid = false, className, ...rest }) {
     return (h("input", { ...rest, className: className === undefined ? 'wb-textField' : `wb-textField ${className}`, "aria-invalid": invalid || undefined }));
 }