@dsh-workbench/shared 0.3.4 → 0.3.5

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

@@ -18,6 +18,9 @@ interface ChatSnapshot {
 
 type UseChat = <T>(selector: (snapshot: ChatSnapshot) => T) => T | undefined;
 
+/**
+ * `ApprovalDetail` 的契约：调用 id、读会话快照的钩子、已装模块与兜底渲染。
+ */
 export interface ApprovalDetailProps {
   readonly callId?: string;
   readonly useChat?: UseChat;
@@ -45,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));

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%;
+}