@dsh-workbench/shared 0.3.4 → 0.3.6

package/dist/components/FormNodes.d.ts

@@ -0,0 +1,103 @@
+import type { ReactNode } from '../lib/react.js';
+import type { FormAction } from './FormActions.js';
+import type { FormField, FormValue } from './FormTypes.js';
+/**
+ * 只剩要显示的那些格子 —— `visible: false` 的当它不存在：不渲染、不校验、不进 `values`，也不参与找第一处错误。
+ * @param fields - 表单的字段清单。
+ * @returns 保序的新数组，`visible` 不给或为 `true` 的都在；全不可见时给空数组。
+ */
+export declare function visibleFieldsOf(fields: readonly FormField[]): readonly FormField[];
+/**
+ * 找出装配错的键：**假值**的键（空串 / `undefined` / `null`，运行期真漏给 `key` 就是这条）每次出现都算一处，
+ * 以及同一张表单里出现两次的键 —— 这两样都会让 `id` 撞车、`values` 少一格。
+ * @param fields - 表单的字段清单（通常是已经过滤过可见性的那份）。
+ * @returns 出问题的键的清单、按首次出现顺序去重；缺失的键一律记成空串（报的时候印成 `（空 key）`），空表给空数组。
+ */
+export declare function duplicateKeysOf(fields: readonly FormField[]): readonly string[];
+/**
+ * 装配错了要当场诊断：`key` 缺失或重复时给 `console.error` —— 但照渲不误，不 throw。
+ * 形式与理由同 `FormActions` 里那颗多出来的 `primary`：装配的小错不该让 `CardBoundary` 把用户的整张卡变空白。
+ * @param fields - 表单的字段清单（通常是已经过滤过可见性的那份）。
+ */
+export declare function reportDuplicateKeys(fields: readonly FormField[]): void;
+/**
+ * 把每格的 `value` 收成一张键值表交给 `onSubmit` —— `Form` 自己一个值都不存，这张表就是从 `fields` 现取的快照。
+ * @param fields - 表单的字段清单；取的就是它们的 `value`，`value` 是数组的那格（多选）原样带出、不复制。
+ * @returns 键为字段 `key`、值为该格 `value` 的表；`fields` 为空时给空表，不是 `undefined`。
+ */
+export declare function formValuesOf(fields: readonly FormField[]): Readonly<Record<string, FormValue>>;
+/**
+ * 算每格现在该不该报错：还没提交过（`show` 为 false）时一格都不报 —— 不边打字边骂人。
+ * `validate` 返回**真值**才算错，假值（`undefined` / `null` / `false` / 空串）一律当"这格没错" ——
+ * 所以 `v.trim() === '' && '必填'` 这种用 `&&` 算文案的写法是对的。
+ * @param fields - 表单的字段清单（通常是已经过滤过可见性的那份）。
+ * @param show - 提交过没有；false 时全给 `undefined`，true 时逐格调 `field.validate` 并按真值收。
+ * @returns 键为 `key`、值为那句文案或 `undefined` 的表；没给 `validate` 的格子也是 `undefined`。
+ */
+export declare function formProblemsOf(fields: readonly FormField[], show: boolean): Readonly<Record<string, ReactNode | undefined>>;
+/**
+ * 按字段顺序取第一处错误 —— 提交被挡住时要带进视口的就是这一格。
+ * 判的是**真值**（与 `formProblemsOf` 同一口径）：假值那种"错误文案"渲染出来本来就是空的，不算错。
+ * @param fields - 表单的字段清单，顺序就是「第一处」的判据。
+ * @param problems - `formProblemsOf` 那张表，也可以是调用点自己拼的（同样按真值判）。
+ * @returns 第一格有错的字段；一格都没错时给 `undefined`。
+ */
+export declare function formFirstProblemOf(fields: readonly FormField[], problems: Readonly<Record<string, ReactNode | undefined>>): FormField | undefined;
+/**
+ * 提交那一拍的结果：有错就挡住（并点出第一处错在哪一格），没错就把键值表交出去。
+ */
+export type FormSubmitOutcome = {
+    readonly blocked: true;
+    readonly first: FormField;
+} | {
+    readonly blocked: false;
+    readonly values: Readonly<Record<string, FormValue>>;
+};
+/**
+ * 算提交那一拍该干什么 —— `Form` 的提交钮点下去、以及 `<form>` 的 Enter 提交，走的都是它。
+ * 错的判据只有一份（`formProblemsOf` + `formFirstProblemOf`），这里不重算第二遍。
+ * @param fields - 要提交的那些格子（通常是调用点先 `visibleFieldsOf` 过滤过的，不可见那格不进 `values` 也不算错）。
+ * @returns `blocked: true` 时带上是按字段顺序数第一格有错的字段（拿它去 `revealFirstProblem`）；
+ * `blocked: false` 时带上从 `fields` 现取的键值表。空表一定给 `blocked: false` 与空 values。
+ */
+export declare function formSubmitOf(fields: readonly FormField[]): FormSubmitOutcome;
+/**
+ * 组表单的操作区：调用点给的其余动作在最左，取消在中间，提交永远是最右那颗 `primary`。
+ * @param args.extra - 其余动作（default / danger），保持调用点给的顺序；不给就是没有。
+ * @param args.cancel - 取消那格的 `label` 与 `onClick`；不给就少一颗钮。
+ * @param args.submit - 提交钮的 `label` 与 `busyLabel`。
+ * @param args.busy - 提交中：提交钮带转圈并换 `busyLabel`（不给就沿用 `label`），`extra` 与取消一起禁用。
+ * @param args.disabled - 只再禁提交钮（如没改动可存），其余动作不受影响。
+ * @param args.onSubmitClick - 提交钮点下去做什么，通常是把这一拍交给 `Form` 的提交处理。
+ * @returns 给 `FormActions` 的动作清单；没给 `extra` 也没给 `cancel` 时只剩提交那一颗。
+ */
+export declare function formActionsOf(args: {
+    readonly extra: readonly FormAction[] | undefined;
+    readonly cancel: {
+        readonly label: ReactNode;
+        readonly onClick: () => void;
+    } | undefined;
+    readonly submit: {
+        readonly label: ReactNode;
+        readonly busyLabel?: ReactNode | undefined;
+    };
+    readonly busy: boolean;
+    readonly disabled: boolean;
+    readonly onSubmitClick: () => void;
+}): readonly FormAction[];
+/**
+ * 把整张表单的行画出来 —— 每格一个 `FormRow`，且**直接**是 `FormRows` 的孩子。
+ * 中间不许再包一层：`FormRow` 一旦不是 `.wb-formRows` 的网格项，`FormRows.css` 里那条 `subgrid` 就不匹配，
+ * 每行各自算列宽，控件左沿就参差了。
+ * @param args.fields - 要画的格子（通常是已经过滤过可见性的那份），顺序就是行的顺序。
+ * @param args.problems - `formProblemsOf` 那张表，决定哪一格显示错误文案（按**真值**判，假值不当错）。
+ * @param args.showProblem - 这一拍该不该显示错误（还没提交过时为 false，一格都不显示）。
+ * @param args.busy - 提交中：每格的绑定 `disabled` 为真。
+ * @returns `FormRow` 组成的数组；没有可画的格子时给空数组。
+ */
+export declare function formRowsOf(args: {
+    readonly fields: readonly FormField[];
+    readonly problems: Readonly<Record<string, ReactNode | undefined>>;
+    readonly showProblem: boolean;
+    readonly busy: boolean;
+}): readonly ReactNode[];

package/dist/components/FormNodes.js

@@ -0,0 +1,153 @@
+import { h } from '../lib/react.js';
+import { FormRow } from './FormRows.js';
+/**
+ * 只剩要显示的那些格子 —— `visible: false` 的当它不存在：不渲染、不校验、不进 `values`，也不参与找第一处错误。
+ * @param fields - 表单的字段清单。
+ * @returns 保序的新数组，`visible` 不给或为 `true` 的都在；全不可见时给空数组。
+ */
+export function visibleFieldsOf(fields) {
+    return fields.filter((field) => field.visible !== false);
+}
+/**
+ * 找出装配错的键：**假值**的键（空串 / `undefined` / `null`，运行期真漏给 `key` 就是这条）每次出现都算一处，
+ * 以及同一张表单里出现两次的键 —— 这两样都会让 `id` 撞车、`values` 少一格。
+ * @param fields - 表单的字段清单（通常是已经过滤过可见性的那份）。
+ * @returns 出问题的键的清单、按首次出现顺序去重；缺失的键一律记成空串（报的时候印成 `（空 key）`），空表给空数组。
+ */
+export function duplicateKeysOf(fields) {
+    const seen = new Set();
+    const duplicated = new Set();
+    for (const field of fields) {
+        const key = field.key;
+        if (!key) {
+            duplicated.add('');
+            continue;
+        }
+        if (seen.has(key))
+            duplicated.add(key);
+        seen.add(key);
+    }
+    return [...duplicated];
+}
+/**
+ * 装配错了要当场诊断：`key` 缺失或重复时给 `console.error` —— 但照渲不误，不 throw。
+ * 形式与理由同 `FormActions` 里那颗多出来的 `primary`：装配的小错不该让 `CardBoundary` 把用户的整张卡变空白。
+ * @param fields - 表单的字段清单（通常是已经过滤过可见性的那份）。
+ */
+export function reportDuplicateKeys(fields) {
+    const duplicated = duplicateKeysOf(fields);
+    if (duplicated.length === 0)
+        return;
+    const named = duplicated.map((key) => (key === '' ? '（空 key）' : key));
+    console.error(`[dsh-workbench] Form 里有重复或缺失的字段 key：${named.join('、')} —— ` +
+        '同一张表单里 key 必须唯一且非空（它决定 id 与 values 的键），否则 id 会撞车、values 会少一格');
+}
+/**
+ * 把每格的 `value` 收成一张键值表交给 `onSubmit` —— `Form` 自己一个值都不存，这张表就是从 `fields` 现取的快照。
+ * @param fields - 表单的字段清单；取的就是它们的 `value`，`value` 是数组的那格（多选）原样带出、不复制。
+ * @returns 键为字段 `key`、值为该格 `value` 的表；`fields` 为空时给空表，不是 `undefined`。
+ */
+export function formValuesOf(fields) {
+    const values = {};
+    for (const field of fields)
+        values[field.key] = field.value;
+    return values;
+}
+/**
+ * 算每格现在该不该报错：还没提交过（`show` 为 false）时一格都不报 —— 不边打字边骂人。
+ * `validate` 返回**真值**才算错，假值（`undefined` / `null` / `false` / 空串）一律当"这格没错" ——
+ * 所以 `v.trim() === '' && '必填'` 这种用 `&&` 算文案的写法是对的。
+ * @param fields - 表单的字段清单（通常是已经过滤过可见性的那份）。
+ * @param show - 提交过没有；false 时全给 `undefined`，true 时逐格调 `field.validate` 并按真值收。
+ * @returns 键为 `key`、值为那句文案或 `undefined` 的表；没给 `validate` 的格子也是 `undefined`。
+ */
+export function formProblemsOf(fields, show) {
+    const values = formValuesOf(fields);
+    const problems = {};
+    for (const field of fields) {
+        const found = show ? field.validate?.(field.value, values) : undefined;
+        problems[field.key] = found ? found : undefined;
+    }
+    return problems;
+}
+/**
+ * 按字段顺序取第一处错误 —— 提交被挡住时要带进视口的就是这一格。
+ * 判的是**真值**（与 `formProblemsOf` 同一口径）：假值那种"错误文案"渲染出来本来就是空的，不算错。
+ * @param fields - 表单的字段清单，顺序就是「第一处」的判据。
+ * @param problems - `formProblemsOf` 那张表，也可以是调用点自己拼的（同样按真值判）。
+ * @returns 第一格有错的字段；一格都没错时给 `undefined`。
+ */
+export function formFirstProblemOf(fields, problems) {
+    return fields.find((field) => Boolean(problems[field.key]));
+}
+/**
+ * 算提交那一拍该干什么 —— `Form` 的提交钮点下去、以及 `<form>` 的 Enter 提交，走的都是它。
+ * 错的判据只有一份（`formProblemsOf` + `formFirstProblemOf`），这里不重算第二遍。
+ * @param fields - 要提交的那些格子（通常是调用点先 `visibleFieldsOf` 过滤过的，不可见那格不进 `values` 也不算错）。
+ * @returns `blocked: true` 时带上是按字段顺序数第一格有错的字段（拿它去 `revealFirstProblem`）；
+ * `blocked: false` 时带上从 `fields` 现取的键值表。空表一定给 `blocked: false` 与空 values。
+ */
+export function formSubmitOf(fields) {
+    const problems = formProblemsOf(fields, true);
+    const first = formFirstProblemOf(fields, problems);
+    if (first !== undefined)
+        return { blocked: true, first };
+    return { blocked: false, values: formValuesOf(fields) };
+}
+/**
+ * 组表单的操作区：调用点给的其余动作在最左，取消在中间，提交永远是最右那颗 `primary`。
+ * @param args.extra - 其余动作（default / danger），保持调用点给的顺序；不给就是没有。
+ * @param args.cancel - 取消那格的 `label` 与 `onClick`；不给就少一颗钮。
+ * @param args.submit - 提交钮的 `label` 与 `busyLabel`。
+ * @param args.busy - 提交中：提交钮带转圈并换 `busyLabel`（不给就沿用 `label`），`extra` 与取消一起禁用。
+ * @param args.disabled - 只再禁提交钮（如没改动可存），其余动作不受影响。
+ * @param args.onSubmitClick - 提交钮点下去做什么，通常是把这一拍交给 `Form` 的提交处理。
+ * @returns 给 `FormActions` 的动作清单；没给 `extra` 也没给 `cancel` 时只剩提交那一颗。
+ */
+export function formActionsOf(args) {
+    const submit = {
+        key: 'submit',
+        label: args.busy ? (args.submit.busyLabel ?? args.submit.label) : args.submit.label,
+        kind: 'primary',
+        busy: args.busy,
+        disabled: args.busy || args.disabled,
+        onClick: args.onSubmitClick,
+    };
+    const cancel = args.cancel === undefined
+        ? []
+        : [
+            {
+                key: 'cancel',
+                label: args.cancel.label,
+                kind: 'default',
+                disabled: args.busy,
+                onClick: args.cancel.onClick,
+            },
+        ];
+    const extra = (args.extra ?? []).map((action) => (args.busy ? { ...action, disabled: true } : action));
+    return [...extra, ...cancel, submit];
+}
+/**
+ * 把整张表单的行画出来 —— 每格一个 `FormRow`，且**直接**是 `FormRows` 的孩子。
+ * 中间不许再包一层：`FormRow` 一旦不是 `.wb-formRows` 的网格项，`FormRows.css` 里那条 `subgrid` 就不匹配，
+ * 每行各自算列宽，控件左沿就参差了。
+ * @param args.fields - 要画的格子（通常是已经过滤过可见性的那份），顺序就是行的顺序。
+ * @param args.problems - `formProblemsOf` 那张表，决定哪一格显示错误文案（按**真值**判，假值不当错）。
+ * @param args.showProblem - 这一拍该不该显示错误（还没提交过时为 false，一格都不显示）。
+ * @param args.busy - 提交中：每格的绑定 `disabled` 为真。
+ * @returns `FormRow` 组成的数组；没有可画的格子时给空数组。
+ */
+export function formRowsOf(args) {
+    return args.fields.map((field) => h(FormRow, {
+        key: field.key,
+        label: field.label,
+        hint: field.hint,
+        problem: args.showProblem ? args.problems[field.key] : undefined,
+        layout: field.layout,
+    }, field.control({
+        id: `wb-form-${field.key}`,
+        name: field.key,
+        invalid: args.showProblem && Boolean(args.problems[field.key]),
+        disabled: args.busy || field.disabled === true,
+    })));
+}

package/dist/components/FormRows.css

@@ -24,6 +24,10 @@
   gap: var(--wb-len-6);
 }
 
+.wb-formRows > .wb-formRow[data-layout='stacked'] {
+  grid-template-columns: minmax(0, 1fr);
+}
+
 .wb-formLabel {
   min-width: 0;
   font-size: var(--dsw-font-xs-13-font-size);
@@ -36,12 +40,39 @@
   white-space: normal;
 }
 
+.wb-formRow[data-layout='stacked'] .wb-formHint,
+.wb-formRow[data-layout='stacked'] .wb-formProblem {
+  grid-column: 1 / -1;
+}
+
 .wb-formControl {
   display: flex;
   align-items: center;
   min-width: 0;
 }
 
+.wb-formControl
+  > :where(
+    .wb-selectAnchor,
+    .wb-choiceMenu,
+    input:not(
+      [type='checkbox'],
+      [type='radio'],
+      [type='button'],
+      [type='submit'],
+      [type='reset'],
+      [type='image'],
+      [type='color'],
+      [type='range']
+    ),
+    select,
+    textarea
+  ) {
+  box-sizing: border-box;
+  width: 100%;
+  min-width: 0;
+}
+
 .wb-formHint {
   grid-column: 2;
   font-size: var(--dsw-font-xxs-12-font-size);

package/dist/components/FormRows.d.ts

@@ -1,9 +1,20 @@
 import type { ReactNode } from '../lib/react.js';
 import './FormRows.css';
+/**
+ * `FormRows` 的契约：一列 `FormRow` 的容器。
+ */
 export interface FormRowsProps {
     readonly children?: ReactNode | undefined;
 }
+/**
+ * 表单行的容器：同一份 `FormRows` 共用一个标签列（列宽由最长的标签定），行距也归它。
+ * @param props.children - 一串 `FormRow`；非行的孩子（如分组标题）自动通栏。
+ * @returns 竖排的 div。
+ */
 export declare function FormRows({ children }: FormRowsProps): JSX.Element;
+/**
+ * `FormRow` 的契约：标签、提示、错误与控件的排布。
+ */
 export interface FormRowProps {
     readonly label: ReactNode;
     readonly hint?: ReactNode | undefined;
@@ -11,4 +22,13 @@ export interface FormRowProps {
     readonly layout?: 'inline' | 'stacked' | undefined;
     readonly children?: ReactNode | undefined;
 }
+/**
+ * 表单一行：左边标签、右边控件，提示与错误占控件下面那一格。
+ * @param props.label - 这一行的标签；进了这一行，控件自己就别再给 `label`，否则会多一个标签。
+ * @param props.hint - 控件下的说明；给了 `problem` 就不画它 —— 同一格不叠两段话。
+ * @param props.problem - 校验失败那句话；给了就顶掉 `hint` 并给整行加上出错标记。
+ * @param props.layout - `stacked` 才是标签在上、控件在下（默认 `inline`：标签在左）。
+ * @param props.children - 控件本体。
+ * @returns 一个 `<label>`。
+ */
 export declare function FormRow({ label, hint, problem, layout, children }: FormRowProps): JSX.Element;

package/dist/components/FormRows.js

@@ -1,8 +1,22 @@
 import { h } from '../lib/react.js';
 import './FormRows.css';
+/**
+ * 表单行的容器：同一份 `FormRows` 共用一个标签列（列宽由最长的标签定），行距也归它。
+ * @param props.children - 一串 `FormRow`；非行的孩子（如分组标题）自动通栏。
+ * @returns 竖排的 div。
+ */
 export function FormRows({ children }) {
     return h("div", { className: "wb-formRows" }, children);
 }
+/**
+ * 表单一行：左边标签、右边控件，提示与错误占控件下面那一格。
+ * @param props.label - 这一行的标签；进了这一行，控件自己就别再给 `label`，否则会多一个标签。
+ * @param props.hint - 控件下的说明；给了 `problem` 就不画它 —— 同一格不叠两段话。
+ * @param props.problem - 校验失败那句话；给了就顶掉 `hint` 并给整行加上出错标记。
+ * @param props.layout - `stacked` 才是标签在上、控件在下（默认 `inline`：标签在左）。
+ * @param props.children - 控件本体。
+ * @returns 一个 `<label>`。
+ */
 export function FormRow({ label, hint, problem, layout = 'inline', children }) {
     return (h("label", { className: "wb-formRow", "data-layout": layout, "data-wb-problem": problem === undefined ? undefined : '' },
         h("span", { className: "wb-formLabel" }, label),

package/dist/components/FormTypes.d.ts

@@ -0,0 +1,59 @@
+import type { ReactNode } from '../lib/react.js';
+import type { FormAction } from './FormActions.js';
+/**
+ * 一格控件的值：单值（`TextField` / `SelectField` / `ChoiceGroup` 单选），或一组值（`ChoiceGroup` 多选）。
+ */
+export type FormValue = string | readonly string[];
+/**
+ * `Form` 递给控件那一格的绑定：`id` / `name` / `invalid` / `disabled` 由 `Form` 定，控件只负责接上。
+ */
+export interface FormFieldBinding {
+    readonly id: string;
+    readonly name: string;
+    readonly invalid: boolean;
+    readonly disabled: boolean;
+}
+/**
+ * 一格字段的配置：键、标签、值、怎么算错（`validate`）、控件本身 —— 排布、时机、阻断都不写在这里，那些归 `Form`。
+ * `validate` 是纯函数、同步、只读 `values`：返回**真值**才算这一格错，假值（`undefined` / `null` / `false` / 空串）
+ * 一律当"没错"—— 所以 `(value) => value.trim() === '' && '必填'` 这种用 `&&` 算文案的写法是对的，
+ * 它的返回值就是错误行那句话。
+ */
+export interface FormField {
+    readonly key: string;
+    readonly label: ReactNode;
+    readonly hint?: ReactNode | undefined;
+    readonly layout?: 'inline' | 'stacked' | undefined;
+    readonly value: FormValue;
+    readonly visible?: boolean | undefined;
+    readonly disabled?: boolean | undefined;
+    readonly validate?: (value: FormValue, values: Readonly<Record<string, FormValue>>) => ReactNode | undefined;
+    readonly control: (binding: FormFieldBinding) => ReactNode;
+}
+/**
+ * 提交钮：文案归调用点，位置、禁用与忙态归 `Form`。
+ */
+export interface FormSubmit {
+    readonly label: ReactNode;
+    readonly busyLabel?: ReactNode | undefined;
+}
+/**
+ * 取消钮：文案与点下去做什么，`Form` 把它排在提交钮左边。
+ */
+export interface FormCancel {
+    readonly label: ReactNode;
+    readonly onClick: () => void;
+}
+/**
+ * `Form` 的契约：fields 配置进，排布、校验时机、提交阻断、操作区全归组件。
+ */
+export interface FormProps {
+    readonly fields: readonly FormField[];
+    readonly onSubmit: (values: Readonly<Record<string, FormValue>>) => void;
+    readonly submit: FormSubmit;
+    readonly cancel?: FormCancel | undefined;
+    readonly extra?: readonly FormAction[] | undefined;
+    readonly busy?: boolean | undefined;
+    readonly disabled?: boolean | undefined;
+    readonly problem?: ReactNode | undefined;
+}

package/dist/components/FormTypes.js

@@ -0,0 +1 @@
+export {};

package/dist/components/Link.d.ts

@@ -1,5 +1,8 @@
 import type { ReactNode } from '../lib/react.js';
 import './Link.css';
+/**
+ * `Link` 的契约：目标地址、文案与外链开关。
+ */
 export interface LinkProps {
     readonly href: string;
     readonly children?: ReactNode | undefined;
@@ -7,4 +10,13 @@ export interface LinkProps {
     readonly external?: boolean | undefined;
     readonly className?: string | undefined;
 }
+/**
+ * 唯一的外链写法：自带新窗口、`rel="noopener noreferrer"`、正文色与行尾那颗小箭头。
+ * @param props.href - 目标地址，必给。
+ * @param props.children - 链接文字（别自己再带 `→`）。
+ * @param props.title - 原生 title 提示；不给就不写这个属性。
+ * @param props.external - 默认 true：新窗口打开并画那颗 ↗；站内跳转给 false，箭头也一起不画。
+ * @param props.className - 追加在基础类名之后，不是替换。
+ * @returns 一个 `<a>`。
+ */
 export declare function Link({ href, children, title, external, className }: LinkProps): JSX.Element;

package/dist/components/Link.js

@@ -1,6 +1,15 @@
 import { h } from '../lib/react.js';
 import { IconRightUpOutlineRegular } from '@deepseek-ai/dsh-client-ui-primitives';
 import './Link.css';
+/**
+ * 唯一的外链写法：自带新窗口、`rel="noopener noreferrer"`、正文色与行尾那颗小箭头。
+ * @param props.href - 目标地址，必给。
+ * @param props.children - 链接文字（别自己再带 `→`）。
+ * @param props.title - 原生 title 提示；不给就不写这个属性。
+ * @param props.external - 默认 true：新窗口打开并画那颗 ↗；站内跳转给 false，箭头也一起不画。
+ * @param props.className - 追加在基础类名之后，不是替换。
+ * @returns 一个 `<a>`。
+ */
 export function Link({ href, children, title, external = true, className }) {
     return (h("a", { className: className === undefined ? 'wb-link' : `wb-link ${className}`, href: href, ...(title === undefined ? {} : { title }), ...(external ? { target: '_blank', rel: 'noopener noreferrer' } : {}) },
         children,

package/dist/components/LongTaskRow.css

@@ -45,4 +45,56 @@
   margin: var(--wb-len-4) 0 0;
   max-height: var(--wb-len-220);
   overflow: auto;
+}
+
+.wb-longTaskStop {
+  display: inline-flex;
+  flex: none;
+  align-items: center;
+  align-self: center;
+  justify-content: center;
+  width: var(--wb-len-20);
+  height: var(--wb-len-20);
+  padding: 0;
+  margin-left: auto;
+  border: 0.5px solid var(--dsw-alias-border-l2);
+  border-radius: var(--dsw-radius-sm);
+  background: var(--dsw-specific-menu);
+  color: var(--dsw-alias-label-secondary);
+  cursor: pointer;
+}
+
+.wb-longTaskStop:hover:not(:disabled),
+.wb-longTaskStop:focus-visible {
+  border-color: color-mix(in srgb, var(--dsw-alias-state-error-primary) 45%, transparent);
+  color: var(--dsw-alias-state-error-primary);
+}
+
+.wb-longTaskStop:disabled {
+  cursor: default;
+}
+
+.wb-longTaskStopArmed,
+.wb-longTaskStopArmed:hover:not(:disabled),
+.wb-longTaskStopArmed:focus-visible {
+  gap: var(--wb-len-4);
+  width: auto;
+  padding: 0 var(--wb-len-7);
+  border-color: color-mix(in srgb, var(--dsw-alias-state-error-primary) 45%, transparent);
+  background: color-mix(in srgb, var(--dsw-alias-state-error-primary) 12%, transparent);
+  color: var(--dsw-alias-state-error-primary);
+}
+
+.wb-longTaskStopLabel {
+  white-space: nowrap;
+  font-size: var(--dsw-font-xxxs-11-font-size);
+  line-height: var(--wb-line-18);
+}
+
+.wb-longTaskStopWhy {
+  margin: 0;
+  font-size: var(--dsw-font-xxxs-11-font-size);
+  line-height: var(--wb-line-16);
+  color: var(--dsw-alias-state-error-primary);
+  overflow-wrap: anywhere;
 }

package/dist/components/LongTaskRow.d.ts

@@ -1,9 +1,29 @@
 import { type LongTaskStatus } from '../api/long-task.js';
 import './LongTaskRow.css';
+/**
+ * 长任务行尾的一个链接：地址与文字。
+ */
 export interface LongTaskRowLink {
     readonly href: string;
     readonly text: string;
 }
+/**
+ * `LongTaskRow` 那颗两按停止钮的契约：确认之后真发的那一下、三句词、在飞与失败两态。
+ * `label` 是没上膛时那颗钮的 aria-label（dsh 的词：`停止任务 {label}`）；`askLabel` 是上膛时那颗钮上显示的字（`确认停止`）；
+ * `armedLabel` 是上膛时的 aria-label，不给就用 `askLabel`（`再次点击确认停止`）；`busy` = 这一趟正在被停、钮禁用；
+ * `failed` 给了才在问题那行后面再画一行。
+ */
+export interface LongTaskRowStop {
+    readonly onStop: () => void;
+    readonly label: string;
+    readonly askLabel: string;
+    readonly armedLabel?: string | undefined;
+    readonly busy?: boolean | undefined;
+    readonly failed?: string | null | undefined;
+}
+/**
+ * `LongTaskRow` 的契约：状态、标题、问题、链接，两处可展开的原始输出，与最右边那颗可选的停止钮。
+ */
 export interface LongTaskRowProps {
     readonly status: LongTaskStatus;
     readonly headline: string;
@@ -15,5 +35,20 @@ export interface LongTaskRowProps {
     readonly rawTitle?: string | undefined;
     readonly copyLabel?: string | undefined;
     readonly copiedLabel?: string | undefined;
+    readonly stop?: LongTaskRowStop | undefined;
 }
+/**
+ * 长任务那一行：状态点 + 标题 + 链接，跑失败时把步骤与原始输出收在两处可展开里。
+ * 发布、扫描、迁移这类跑得久的事都用它，别自己画进度。
+ * @param props.status - `longTaskDot` 认的五态之一，决定状态点颜色与要不要画"失败"那两块。
+ * @param props.headline - 这一行在干什么（一句话）。
+ * @param props.problem - 失败原因；不给不画。
+ * @param props.links - 行尾的链接，通常指向产物或日志。
+ * @param props.steps - 步骤文本；只在失败时画，且要同时给 `stepsTitle` 才成一块可展开。
+ * @param props.raw - 原始输出；只在失败时画，且要同时给 `rawTitle` 才成一块可展开。
+ * @param props.stepsTitle - 步骤那块展开行的标题；`rawTitle` 同理是原始输出那块。
+ * @param props.copyLabel - 复制钮文案：给了才画复制钮；`copiedLabel` 是复制成功后那句。
+ * @param props.stop - 给了才在最右边画那颗两按停止钮；**不给就一个像素都不变**。只在生产方认 `signal` 时给。
+ * @returns 一行长任务。
+ */
 export declare function LongTaskRow(props: LongTaskRowProps): JSX.Element;

package/dist/components/LongTaskRow.js

@@ -1,24 +1,65 @@
-import { longTaskDot } from '../api/long-task.js';
+import { longTaskDot, longTaskStopPress, longTaskStopStage, LONG_TASK_STOP_ARM_MS } from '../api/long-task.js';
 import { Link } from './Link.js';
-import { Fragment, h, useState } from '../lib/react.js';
-import { CodeBlock, DisclosureRow, IconCodeOutlineRegular, IconFlatListOutlineRegular, StateDot, } from '@deepseek-ai/dsh-client-ui-primitives';
+import { Fragment, h, useEffect, useState } from '../lib/react.js';
+import { CodeBlock, DisclosureRow, IconCodeOutlineRegular, IconFlatListOutlineRegular, IconStopFillRegular, StateDot, } from '@deepseek-ai/dsh-client-ui-primitives';
 import './LongTaskRow.css';
 function RowLink({ href, text }) {
     return (h(Link, { href: href, className: "wb-longTaskLink" }, text));
 }
+/**
+ * 长任务那一行：状态点 + 标题 + 链接，跑失败时把步骤与原始输出收在两处可展开里。
+ * 发布、扫描、迁移这类跑得久的事都用它，别自己画进度。
+ * @param props.status - `longTaskDot` 认的五态之一，决定状态点颜色与要不要画"失败"那两块。
+ * @param props.headline - 这一行在干什么（一句话）。
+ * @param props.problem - 失败原因；不给不画。
+ * @param props.links - 行尾的链接，通常指向产物或日志。
+ * @param props.steps - 步骤文本；只在失败时画，且要同时给 `stepsTitle` 才成一块可展开。
+ * @param props.raw - 原始输出；只在失败时画，且要同时给 `rawTitle` 才成一块可展开。
+ * @param props.stepsTitle - 步骤那块展开行的标题；`rawTitle` 同理是原始输出那块。
+ * @param props.copyLabel - 复制钮文案：给了才画复制钮；`copiedLabel` 是复制成功后那句。
+ * @param props.stop - 给了才在最右边画那颗两按停止钮；**不给就一个像素都不变**。只在生产方认 `signal` 时给。
+ * @returns 一行长任务。
+ */
 export function LongTaskRow(props) {
     const [stepsOpen, setStepsOpen] = useState(false);
     const [rawOpen, setRawOpen] = useState(false);
+    const [armed, setArmed] = useState(false);
     const failed = props.status === 'failed';
     const problem = props.problem ?? '';
     const raw = (props.raw ?? '').trim();
     const steps = props.steps ?? [];
+    const stop = props.stop;
+    const busy = stop?.busy === true;
+    const stopWhy = stop?.failed ?? '';
+    useEffect(() => {
+        if (!armed)
+            return undefined;
+        const timer = setTimeout(() => setArmed(false), LONG_TASK_STOP_ARM_MS);
+        return () => clearTimeout(timer);
+    }, [armed]);
+    const onStopPress = () => {
+        if (stop === undefined)
+            return;
+        const press = longTaskStopPress(longTaskStopStage({ armed, busy }));
+        if (press === 'ignore')
+            return;
+        if (press === 'arm') {
+            setArmed(true);
+            return;
+        }
+        setArmed(false);
+        stop.onStop();
+    };
     return (h("div", { className: "wb-longTask" },
         h("p", { className: "wb-longTaskHead" },
             h(StateDot, { state: longTaskDot(props.status), size: 10 }),
             h("span", { className: "wb-longTaskHeadline" }, props.headline),
-            (props.links ?? []).map((link) => (h(RowLink, { href: link.href, key: `${link.text}@${link.href}`, text: link.text })))),
+            (props.links ?? []).map((link) => (h(RowLink, { href: link.href, key: `${link.text}@${link.href}`, text: link.text }))),
+            stop === undefined ? null : (h("button", { type: "button", className: `wb-longTaskStop${armed ? ' wb-longTaskStopArmed' : ''}`, "data-stop-state": longTaskStopStage({ armed, busy }), "aria-label": armed ? stop.armedLabel ?? stop.askLabel : stop.label, disabled: busy, onClick: onStopPress, onBlur: () => setArmed(false) },
+                h(IconStopFillRegular, { size: 12 }),
+                armed ? h("span", { className: "wb-longTaskStopLabel" }, stop.askLabel) : null))),
         problem === '' ? null : h("p", { className: "wb-longTaskProblem" }, problem),
+        stopWhy === '' ? null : h("p", { className: "wb-longTaskStopWhy" }, stopWhy),
         !failed ? null : (h(Fragment, null,
             steps.length === 0 || props.stepsTitle === undefined ? null : (h(DisclosureRow, { className: "wb-longTaskDump", icon: h(IconFlatListOutlineRegular, { size: 14 }), title: props.stepsTitle, open: stepsOpen, expandable: true, expandOnRowClick: true, previewChevron: true, onToggle: () => setStepsOpen(!stepsOpen) },
                 h(CodeBlock, { code: steps.join('\n'), className: "wb-longTaskDump", showHeader: props.copyLabel !== undefined, copyLabel: props.copyLabel ?? '', copiedLabel: props.copiedLabel ?? '' }))),