@dsh-workbench/shared 0.3.4 → 0.3.5

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 }));
 }

package/dist/components/board-module.d.ts

@@ -3,9 +3,15 @@ import type { SessionsSnapshot, Translate, WorkspaceSnapshot, WorkspaceView } fr
 import type { UnitManifest } from '../api/unit.js';
 import type { CapabilityPayload } from '../api/workbench-contract.js';
 import type { Dictionaries } from '../i18n/index.js';
+/**
+ * 面板要跳去的一格：只用 `kind` 说去哪，具体负载由各 unit 自己约定。
+ */
 export interface PanelStep {
     readonly kind: string;
 }
+/**
+ * 交给面板渲染的宿主世界：工作区与会话快照、装着的 unit、面板开关、能力表与当前选中。
+ */
 export interface SuiteWorld {
     readonly workspaces: WorkspaceSnapshot;
     readonly sessions: SessionsSnapshot;
@@ -19,6 +25,9 @@ export interface SuiteWorld {
         readonly workspace: WorkspaceView | null;
     };
 }
+/**
+ * 面板视图的统一 prop：一份世界快照 + 刷新令牌 + 四个通知回调 + 翻译函数。
+ */
 export interface BoardModuleProps {
     readonly world: SuiteWorld;
     readonly refreshToken: number;
@@ -28,14 +37,23 @@ export interface BoardModuleProps {
     readonly onSummary: (summary: ModuleSummary) => void;
     readonly t: Translate;
 }
+/**
+ * 一张卡报给宿主的摘要：此刻在不在刷新、上次读到是哪个时刻。
+ */
 export interface ModuleSummary {
     readonly refreshing: boolean;
     readonly at: number | null;
 }
+/**
+ * unit 的一个子步骤：标题文案键 + 渲染这件视图的组件。
+ */
 export interface UnitStep {
     readonly titleKey: string;
     readonly View: (props: BoardModuleProps) => ReactNode;
 }
+/**
+ * 一个面板单元的注册面：id、标题键、排序、视图，可带一组子步骤。
+ */
 export interface BoardModule {
     readonly id: string;
     readonly titleKey: string;
@@ -43,6 +61,9 @@ export interface BoardModule {
     readonly View: (props: BoardModuleProps) => ReactNode;
     readonly steps?: Readonly<Record<string, UnitStep>>;
 }
+/**
+ * 模块在浏览器侧交出来的那份面：卡片、子步骤、自己的字典，以及审批渲染。
+ */
 export interface UnitClientFace {
     readonly unit: string;
     readonly card?: (props: BoardModuleProps) => ReactNode;
@@ -56,13 +77,22 @@ export interface UnitClientFace {
         }) => ReactNode;
     } | undefined;
 }
+/**
+ * 带着自己 manifest 的模块面（外壳按 unit 认领时用）。
+ */
 export interface UnitOwnedClientFace extends UnitClientFace {
     readonly manifest: UnitManifest;
 }
+/**
+ * 一次审批要看的输入：工具名，与它这次收到的参数。
+ */
 export interface ApprovalInput {
     readonly tool: string;
     readonly args: Readonly<Record<string, unknown>>;
 }
+/**
+ * 模块注册进外壳的那个口：注册一份面（拿回注销函数）、列出已装 unit。
+ */
 export interface UnitClientApi {
     registerUnit(face: UnitClientFace): () => void;
     manifests(): readonly UnitManifest[];

package/dist/components/icons.d.ts

@@ -1,10 +1,48 @@
+/**
+ * 自绘图标的契约：只给边长像素。
+ */
 export interface IconProps {
     size?: number;
 }
+/**
+ * 会话图标：一枚对话气泡，dsh 的图标表里没有，留给我们自己用；默认 16px。
+ * @param props.size - 边长像素，同时给 `width` 与 `height`。
+ * @returns 一枚 `aria-hidden` 的 svg。
+ */
 export declare function IconConversation({ size }: IconProps): JSX.Element;
+/**
+ * 品牌标：侧栏顶上那枚工作台方块标；默认 24px（它是品牌物，别拿它当通用图标）。
+ * @param props.size - 边长像素，同时给 `width` 与 `height`。
+ * @returns 一枚 `aria-hidden` 的 svg。
+ */
 export declare function IconBrandMark({ size }: IconProps): JSX.Element;
+/**
+ * opencli 的标：包类型那一格用它；颜色写死的品牌物，不跟主题走。默认 16px。
+ * @param props.size - 边长像素，同时给 `width` 与 `height`。
+ * @returns 一枚 `aria-hidden` 的 svg。
+ */
 export declare function IconOpencli({ size }: IconProps): JSX.Element;
+/**
+ * npm 的标：包类型那一格用它；保留品牌红，不跟主题走。默认 16px。
+ * @param props.size - 边长像素，同时给 `width` 与 `height`。
+ * @returns 一枚 `aria-hidden` 的 svg。
+ */
 export declare function IconNpm({ size }: IconProps): JSX.Element;
+/**
+ * 四宫格："模块"这个概念的通用单色图标（侧栏、面板那颗钮、市场节的标题）；默认 16px。
+ * @param props.size - 边长像素，同时给 `width` 与 `height`。
+ * @returns 一枚 `aria-hidden` 的 svg。
+ */
 export declare function IconModules({ size }: IconProps): JSX.Element;
+/**
+ * 模块类型标：渐变方块 + 白四宫格，用在"这是个模块"的行首；品牌物，颜色不跟主题走。默认 16px。
+ * @param props.size - 边长像素，同时给 `width` 与 `height`。
+ * @returns 一枚 `aria-hidden` 的 svg。
+ */
 export declare function IconModuleMark({ size }: IconProps): JSX.Element;
+/**
+ * 面板 / 卡片那类的图标：整屏与柱状那种形状，给"面板"这一档用；默认 16px。
+ * @param props.size - 边长像素，同时给 `width` 与 `height`。
+ * @returns 一枚 `aria-hidden` 的 svg。
+ */
 export declare function IconPanelScreen({ size }: IconProps): JSX.Element;

package/dist/components/icons.js

@@ -2,15 +2,30 @@ import { h } from '../lib/react.js';
 function Shell({ size, strokeWidth = 1, viewBox = '0 0 16 16', children, }) {
     return (h("svg", { width: size, height: size, viewBox: viewBox, fill: "none", xmlns: "http://www.w3.org/2000/svg", "aria-hidden": "true", strokeWidth: strokeWidth, style: { display: 'block' } }, children));
 }
+/**
+ * 会话图标：一枚对话气泡，dsh 的图标表里没有，留给我们自己用；默认 16px。
+ * @param props.size - 边长像素，同时给 `width` 与 `height`。
+ * @returns 一枚 `aria-hidden` 的 svg。
+ */
 export function IconConversation({ size = 16 }) {
     return (h(Shell, { size: size, strokeWidth: 1.3 },
         h("path", { d: "M2.5 7.2c0-2.3 2.1-4.2 4.8-4.2h1.4c2.7 0 4.8 1.9 4.8 4.2s-2.1 4.2-4.8 4.2H7.5l-3.2 2v-2.3c-1.1-.8-1.8-2-1.8-3.9Z", stroke: "currentColor", strokeLinejoin: "round" })));
 }
+/**
+ * 品牌标：侧栏顶上那枚工作台方块标；默认 24px（它是品牌物，别拿它当通用图标）。
+ * @param props.size - 边长像素，同时给 `width` 与 `height`。
+ * @returns 一枚 `aria-hidden` 的 svg。
+ */
 export function IconBrandMark({ size = 24 }) {
     return (h(Shell, { size: size, strokeWidth: 1.6, viewBox: "0 0 24 24" },
         h("rect", { x: 3, y: 3, width: 18, height: 18, rx: 5, stroke: "currentColor" }),
         h("path", { d: "M8 9.5h8M8 12.5h8M8 15.5h5", stroke: "currentColor", strokeLinecap: "round" })));
 }
+/**
+ * opencli 的标：包类型那一格用它；颜色写死的品牌物，不跟主题走。默认 16px。
+ * @param props.size - 边长像素，同时给 `width` 与 `height`。
+ * @returns 一枚 `aria-hidden` 的 svg。
+ */
 export function IconOpencli({ size = 16 }) {
     return (h(Shell, { size: size, viewBox: "0 0 64 64" },
         h("defs", null,
@@ -21,10 +36,20 @@ export function IconOpencli({ size = 16 }) {
         h("rect", { width: 64, height: 64, rx: 14, fill: "#0a0a0f" }),
         h("text", { x: "50%", y: "54%", dominantBaseline: "middle", textAnchor: "middle", fontFamily: "monospace", fontWeight: 700, fontSize: 28, fill: "url(#opencli-mark)" }, ">_")));
 }
+/**
+ * npm 的标：包类型那一格用它；保留品牌红，不跟主题走。默认 16px。
+ * @param props.size - 边长像素，同时给 `width` 与 `height`。
+ * @returns 一枚 `aria-hidden` 的 svg。
+ */
 export function IconNpm({ size = 16 }) {
     return (h(Shell, { size: size, viewBox: "0 0 1024 1024" },
         h("path", { d: "M64 337.76h896v298.72H512v49.792H312.896v-49.824H64z m49.792 248.928h99.552v-149.376h49.76v149.344h49.792v-199.104H113.792z m248.896-199.136v248.928h99.552v-49.792h99.552v-199.136z m99.552 49.792H512v99.584h-49.792z m149.344-49.792v199.136h99.552v-149.376h49.792v149.344h49.792v-149.344h49.792v149.344h49.792v-199.104z", fill: "#CB3837" })));
 }
+/**
+ * 四宫格："模块"这个概念的通用单色图标（侧栏、面板那颗钮、市场节的标题）；默认 16px。
+ * @param props.size - 边长像素，同时给 `width` 与 `height`。
+ * @returns 一枚 `aria-hidden` 的 svg。
+ */
 export function IconModules({ size = 16 }) {
     return (h("svg", { width: size, height: size, viewBox: "0 0 16 16", fill: "none", "aria-hidden": "true" },
         h("rect", { x: "2.5", y: "2.5", width: "4.6", height: "4.6", rx: "1.2", stroke: "currentColor", strokeWidth: "1.2" }),
@@ -32,6 +57,11 @@ export function IconModules({ size = 16 }) {
         h("rect", { x: "2.5", y: "8.9", width: "4.6", height: "4.6", rx: "1.2", stroke: "currentColor", strokeWidth: "1.2" }),
         h("rect", { x: "8.9", y: "8.9", width: "4.6", height: "4.6", rx: "1.2", stroke: "currentColor", strokeWidth: "1.2" })));
 }
+/**
+ * 模块类型标：渐变方块 + 白四宫格，用在"这是个模块"的行首；品牌物，颜色不跟主题走。默认 16px。
+ * @param props.size - 边长像素，同时给 `width` 与 `height`。
+ * @returns 一枚 `aria-hidden` 的 svg。
+ */
 export function IconModuleMark({ size = 16 }) {
     return (h(Shell, { size: size, viewBox: "0 0 24 24" },
         h("defs", null,
@@ -45,6 +75,11 @@ export function IconModuleMark({ size = 16 }) {
         h("rect", { x: "4.6", y: "13.2", width: "6.2", height: "6.2", rx: "1.9", fill: "#ffffff", fillOpacity: 0.78 }),
         h("rect", { x: "13.2", y: "13.2", width: "6.2", height: "6.2", rx: "1.9", fill: "#ffffff" })));
 }
+/**
+ * 面板 / 卡片那类的图标：整屏与柱状那种形状，给"面板"这一档用；默认 16px。
+ * @param props.size - 边长像素，同时给 `width` 与 `height`。
+ * @returns 一枚 `aria-hidden` 的 svg。
+ */
 export function IconPanelScreen({ size = 16 }) {
     return (h("svg", { width: size, height: size, viewBox: "0 0 1024 1024", fill: "currentColor", xmlns: "http://www.w3.org/2000/svg", "aria-hidden": "true", style: { display: 'block', overflow: 'hidden' } },
         h("path", { d: "M939 112c17.673 0 32 14.327 32 32v554.667c0 17.673-14.327 32-32 32l-394.5-0.001v96c0 3.74-0.642 7.331-1.82 10.668H768.4c17.673 0 32 14.326 32 32 0 17.496-14.042 31.712-31.47 31.995l-0.53 0.004H256.6c-17.673 0-32-14.327-32-32 0-17.496 14.042-31.713 31.47-31.995l0.53-0.005h225.721a31.923 31.923 0 0 1-1.817-10.137l-0.004-0.53v-96H86c-17.496 0-31.713-14.041-31.996-31.47l-0.004-0.53V144c0-17.673 14.327-32 32-32z m-32 64H118v490.666h789V176zM341.9 432c17.496 0 31.713 14.042 31.996 31.47l0.004 0.53v85.333c0 17.673-14.327 32-32 32-17.496 0-31.713-14.041-31.996-31.47l-0.004-0.53V464c0-17.673 14.327-32 32-32z m170.6-85.333c17.496 0 31.713 14.041 31.996 31.47l0.004 0.53v170.666c0 17.673-14.327 32-32 32-17.496 0-31.713-14.041-31.996-31.47l-0.004-0.53V378.667c0-17.673 14.327-32 32-32z m170.6-85.334c17.496 0 31.713 14.042 31.996 31.471l0.004 0.53v256c0 17.672-14.327 32-32 32-17.496 0-31.713-14.042-31.996-31.471l-0.004-0.53v-256c0-17.673 14.327-32 32-32z" })));