@dsh-workbench/shared 0.3.6 → 0.3.8

package/dist/api/context-ref.d.ts

@@ -15,12 +15,6 @@ export interface ContextRef {
  * @returns 形如 kind:part/part；分段里的 / 不转义，所以分段名本身不能含 /。
  */
 export declare function encodeRef(ref: ContextRef): string;
-/**
- * 把 kind:part/part 文本读回引用。
- * @param text 待解析文本。
- * @returns 没冒号、冒号在首尾、种类不是小写字母开头、或冒号后为空时给 undefined；不抛异常。
- */
-export declare function decodeRef(text: string): ContextRef | undefined;
 /**
  * 拼出 @ 后面那半截（标记名加已编码文本），比较与拼接都用它。
  * @param encoded encodeRef 的结果。
@@ -33,9 +27,3 @@ export declare function markerBody(encoded: string): string;
  * @returns 形如 @工作台:file:src/a.ts 的一段文本。
  */
 export declare function buildMarker(ref: ContextRef): string;
-/**
- * 从一段文本里按出现顺序捞出所有标记引用，同一个引用只留第一次。
- * @param text 任意文本；null / undefined 当空串。
- * @returns 解析不出来的标记会被丢掉，所以结果只含合法引用，可能为空数组。
- */
-export declare function parseMarkers(text: string): ContextRef[];

package/dist/api/context-ref.js

@@ -2,8 +2,6 @@
  * 引用标记的固定名字；完整标记是 @<这个名字>:<编码文本>，改它等于作废历史会话里已写下的引用。
  */
 export const CONTEXT_MARKER_NAME = '工作台';
-const MARKER = new RegExp(`@${CONTEXT_MARKER_NAME}:([a-z][a-z0-9-]*:[A-Za-z0-9._~%#/-]+)`, 'g');
-const TRAILING_PUNCTUATION = /[.,;:!?]+$/;
 /**
  * 把引用拼回标记体里的那一段文本（不含 @ 与标记名）。
  * @param ref 要拼的引用。
@@ -12,23 +10,6 @@ const TRAILING_PUNCTUATION = /[.,;:!?]+$/;
 export function encodeRef(ref) {
     return `${ref.kind}:${ref.parts.join('/')}`;
 }
-/**
- * 把 kind:part/part 文本读回引用。
- * @param text 待解析文本。
- * @returns 没冒号、冒号在首尾、种类不是小写字母开头、或冒号后为空时给 undefined；不抛异常。
- */
-export function decodeRef(text) {
-    const at = text.indexOf(':');
-    if (at <= 0 || at === text.length - 1)
-        return undefined;
-    const kind = text.slice(0, at);
-    if (!/^[a-z][a-z0-9-]*$/.test(kind))
-        return undefined;
-    const parts = text.slice(at + 1).split('/').filter((part) => part !== '');
-    if (parts.length === 0)
-        return undefined;
-    return { kind, parts };
-}
 /**
  * 拼出 @ 后面那半截（标记名加已编码文本），比较与拼接都用它。
  * @param encoded encodeRef 的结果。
@@ -45,24 +26,3 @@ export function markerBody(encoded) {
 export function buildMarker(ref) {
     return `@${markerBody(encodeRef(ref))}`;
 }
-/**
- * 从一段文本里按出现顺序捞出所有标记引用，同一个引用只留第一次。
- * @param text 任意文本；null / undefined 当空串。
- * @returns 解析不出来的标记会被丢掉，所以结果只含合法引用，可能为空数组。
- */
-export function parseMarkers(text) {
-    const seen = new Set();
-    const refs = [];
-    for (const match of String(text ?? '').matchAll(MARKER)) {
-        const raw = match[1].replace(TRAILING_PUNCTUATION, '');
-        const ref = decodeRef(raw);
-        if (ref === undefined)
-            continue;
-        const key = encodeRef(ref);
-        if (seen.has(key))
-            continue;
-        seen.add(key);
-        refs.push(ref);
-    }
-    return refs;
-}

package/dist/api/facts.d.ts

@@ -10,12 +10,6 @@ export interface FactFrame {
  * 范围查法的后缀：cmdb/* 这类名字表示「这个前缀下的一族」，不是一条事实。
  */
 export declare const FACT_SCOPE_SUFFIX = "*";
-/**
- * 由单元 id 拼出它那一族事实的范围名。
- * @param unit 单元 id，不带后缀。
- * @returns <unit>* —— 永远是范围名，不是某一条事实。
- */
-export declare function unitFactScope(unit: string): string;
 /**
  * 判一个名字是不是范围查法，不是问这条事实存不存在。
  * @param name 事实名或范围名。

package/dist/api/facts.js

@@ -2,14 +2,6 @@
  * 范围查法的后缀：cmdb/* 这类名字表示「这个前缀下的一族」，不是一条事实。
  */
 export const FACT_SCOPE_SUFFIX = '*';
-/**
- * 由单元 id 拼出它那一族事实的范围名。
- * @param unit 单元 id，不带后缀。
- * @returns <unit>* —— 永远是范围名，不是某一条事实。
- */
-export function unitFactScope(unit) {
-    return `${unit}${FACT_SCOPE_SUFFIX}`;
-}
 /**
  * 判一个名字是不是范围查法，不是问这条事实存不存在。
  * @param name 事实名或范围名。

package/dist/api/long-task.d.ts

@@ -58,6 +58,14 @@ export declare function longTaskRunsOf<T>(state: {
  * @returns ongoing / done / error / idle；needs-login 也算进行中；`stopped` 落进 idle —— 灰点：不是成功、不是出错，是用户自己按停的。
  */
 export declare function longTaskDot(status: LongTaskStatus): 'ongoing' | 'done' | 'error' | 'idle';
+/**
+ * 这一趟还在不在跑（`running` 与 `needs-login` 都算）。
+ * 卡片要判"这一行要不要摆停止钮""这套环境里有没有活着的跑"时用这个 —— **不是** `longTaskDot`：
+ * 那一件是状态点的**长相**（四档），归 `LongTaskRow` 自己用，不该被调用点拿去当判据。
+ * @param status 长任务的五种态。
+ * @returns 在跑 `true`；成功 / 失败 / 用户按停都是 `false`。
+ */
+export declare function longTaskIsLive(status: LongTaskStatus): boolean;
 /**
  * 停止钮的三档：没上膛 / 上了膛 / 请求在飞。
  */

package/dist/api/long-task.js

@@ -55,6 +55,16 @@ export function longTaskDot(status) {
         return 'ongoing';
     return 'idle';
 }
+/**
+ * 这一趟还在不在跑（`running` 与 `needs-login` 都算）。
+ * 卡片要判"这一行要不要摆停止钮""这套环境里有没有活着的跑"时用这个 —— **不是** `longTaskDot`：
+ * 那一件是状态点的**长相**（四档），归 `LongTaskRow` 自己用，不该被调用点拿去当判据。
+ * @param status 长任务的五种态。
+ * @returns 在跑 `true`；成功 / 失败 / 用户按停都是 `false`。
+ */
+export function longTaskIsLive(status) {
+    return status === 'running' || status === 'needs-login';
+}
 /**
  * 算停止钮现在在哪一档。
  * @param state armed = 已经按过第一下、在等第二下；busy = 停止请求已经在飞。

package/dist/components/ConfirmBar.css

@@ -0,0 +1,26 @@
+.wb-confirmBar {
+  display: flex;
+  flex-direction: column;
+  gap: var(--wb-len-8);
+  width: 100%;
+  box-sizing: border-box;
+  padding: var(--wb-len-10) var(--wb-len-12);
+  border: 0.5px solid var(--dsw-alias-border-l3);
+  border-radius: var(--dsw-radius-md);
+  background: var(--dsw-alias-bg-layer-1);
+}
+.wb-confirmBarTitle {
+  margin: 0;
+  font-size: var(--dsw-font-xxs-12-font-size);
+  font-weight: 600;
+  line-height: var(--wb-line-18);
+  color: var(--dsw-alias-label-primary);
+  overflow-wrap: anywhere;
+}
+.wb-confirmBarHint {
+  margin: 0;
+  font-size: var(--dsw-font-xxxs-11-font-size);
+  line-height: var(--wb-line-16);
+  color: var(--dsw-alias-label-secondary);
+  overflow-wrap: anywhere;
+}

package/dist/components/ConfirmBar.d.ts

@@ -0,0 +1,36 @@
+import type { ReactNode } from '../lib/react.js';
+import { type FormAction } from './FormActions.js';
+import './ConfirmBar.css';
+/**
+ * `ConfirmBar` 的一格键值：`label` 在左、`value` 在右（走 `Rows` 的标签列）。
+ */
+export interface ConfirmRow {
+    readonly key: string;
+    readonly label: ReactNode;
+    readonly value: ReactNode;
+}
+/**
+ * `ConfirmBar` 的契约：标题、说明、键值、失败那句与动作。
+ */
+export interface ConfirmBarProps {
+    readonly title: ReactNode;
+    readonly hint?: ReactNode | undefined;
+    readonly rows?: readonly ConfirmRow[] | undefined;
+    readonly actions: readonly FormAction[];
+    readonly problem?: ReactNode | undefined;
+    readonly busy?: boolean | undefined;
+    readonly label?: string | undefined;
+}
+/**
+ * 「先问一句再动手」那一条：标题 + 说明 + 键值 + 失败那句 + 动作区，形状一次收口。
+ * **要不要问**归调用点（ADR-0054 §2 规则三），这一件只回答"问的时候长什么样"。
+ * @param props.title - 那一句问话（"发布到 prod？"）。
+ * @param props.hint - 标题下面那句说明或正文；不给不占位。
+ * @param props.rows - 键值两格（键值列宽与分隔线归 `Rows` / `Row`）；不给或空数组不渲染。值那一格可以放控件。
+ * @param props.actions - 动作清单（归 `FormActions`：一个区一颗 `primary`、永远在右、窄了折行）。
+ * @param props.problem - 失败那句（走 `Note tone="problem"`，读屏是 `alert`）；不给不占位。
+ * @param props.busy - 整条在忙（只喂 `aria-busy`；按钮自己的转圈与禁用归 `actions` 里那一颗）。
+ * @param props.label - 读屏的组名；不给时 `title` 是字符串就拿它顶上，两者都没有就不设。
+ * @returns 一个 `role="group"` 的条；`actions` 空数组时最后那一块不渲染。
+ */
+export declare function ConfirmBar({ title, hint, rows, actions, problem, busy, label }: ConfirmBarProps): JSX.Element;

package/dist/components/ConfirmBar.js

@@ -0,0 +1,26 @@
+import { h } from '../lib/react.js';
+import { FormActions } from './FormActions.js';
+import { Note } from './Note.js';
+import { Row, Rows } from './Rows.js';
+import './ConfirmBar.css';
+/**
+ * 「先问一句再动手」那一条：标题 + 说明 + 键值 + 失败那句 + 动作区，形状一次收口。
+ * **要不要问**归调用点（ADR-0054 §2 规则三），这一件只回答"问的时候长什么样"。
+ * @param props.title - 那一句问话（"发布到 prod？"）。
+ * @param props.hint - 标题下面那句说明或正文；不给不占位。
+ * @param props.rows - 键值两格（键值列宽与分隔线归 `Rows` / `Row`）；不给或空数组不渲染。值那一格可以放控件。
+ * @param props.actions - 动作清单（归 `FormActions`：一个区一颗 `primary`、永远在右、窄了折行）。
+ * @param props.problem - 失败那句（走 `Note tone="problem"`，读屏是 `alert`）；不给不占位。
+ * @param props.busy - 整条在忙（只喂 `aria-busy`；按钮自己的转圈与禁用归 `actions` 里那一颗）。
+ * @param props.label - 读屏的组名；不给时 `title` 是字符串就拿它顶上，两者都没有就不设。
+ * @returns 一个 `role="group"` 的条；`actions` 空数组时最后那一块不渲染。
+ */
+export function ConfirmBar({ title, hint, rows, actions, problem, busy, label }) {
+    const name = label ?? (typeof title === 'string' ? title : undefined);
+    return (h("div", { className: "wb-confirmBar", role: "group", "aria-label": name, "aria-busy": busy },
+        h("p", { className: "wb-confirmBarTitle" }, title),
+        hint === undefined ? null : h("p", { className: "wb-confirmBarHint" }, hint),
+        rows === undefined || rows.length === 0 ? null : (h(Rows, null, rows.map((row) => (h(Row, { key: row.key, label: row.label, value: row.value }))))),
+        problem === undefined ? null : (h(Note, { tone: "problem", role: "alert" }, problem)),
+        h(FormActions, { actions: actions })));
+}

package/dist/components/Form.d.ts

@@ -1,14 +1,16 @@
-import type { FormProps } from './FormTypes.js';
+import type { FormProps, FormValues } from './FormTypes.js';
 import './Form.css';
 /**
  * 整张表单：`fields` 进，行、错误、操作区、（被挡住的）提交都由它安排 —— 它自己一个值都不存，
- * 值仍归调用点的 model（`value` 只读给校验看）。
+ * 值仍归调用点（`value` 与 `onChange` 写在字段配置的同一格里，`Form` 只是把两者原样递给那一格的 `control`）。
+ * 写了 `Form<Values>` 就按 `Values` 把每一格的键与值类型钉住（`Values` 里会 `visible: false` 的键写成可选键）；
+ * 不写就是默认档，键值都不钉。
  * 还没提交过时一格错都不显示；第一次提交之后每次渲染重算，改好了当场消。
  * 提交那一拍永远先算一遍：有错就不调 `onSubmit`，并把第一个有错的 `FormRow` 带进视口、聚焦它里面的控件。
  * 回车与点提交钮走的是同一条路：真 `<form>` 的隐式提交在**只有一个文本框**时也会 fire，所以 `busy` / `disabled` 时回车同样不提交。
  * 调用点只管数据与语义：行怎么排、错误摆哪、什么时候校验、按钮在哪，这里没有口子。
- * @param props.fields - 每格的键 / 标签 / 值 / 校验 / 控件；`visible: false` 的那格当它不存在（不渲染、不校验、不进 `values`）。
- * @param props.onSubmit - 校验全过的那一拍，回的是从 `fields` 现取的键值表；被挡住时不会被调。
+ * @param props.fields - 每格的键 / 标签 / 值 / 值怎么改（`onChange`）/ 校验 / 控件；`visible: false` 的那格当它不存在（不渲染、不校验、不进 `values`）。
+ * @param props.onSubmit - 校验全过的那一拍，回的是从 `fields` 现取的键值表（按 `visibleFieldsOf` 过滤过，不可见那格不在里面）；被挡住时不会被调。
  * @param props.submit - 提交钮文案；`busyLabel` 是提交中换的那句，不给就沿用 `label`。
  * @param props.cancel - 取消钮；给了就排在提交钮左边，`busy` 时一起禁用。
  * @param props.extra - 其余动作（default / danger），排在最左，`busy` 时一起禁用。
@@ -17,4 +19,4 @@ import './Form.css';
  * @param props.problem - 整表级那句错（提交失败），落在行与操作区之间；不给就不画。
  * @returns 一个 `<form>`（`noValidate`：报错形状归 `FormRow`，不走浏览器的气泡）。
  */
-export declare function Form(props: FormProps): JSX.Element;
+export declare function Form<Values extends object = FormValues>(props: FormProps<Values>): JSX.Element;

package/dist/components/Form.js

@@ -7,13 +7,15 @@ import { revealFirstProblem } from '../lib/form-problem.js';
 import './Form.css';
 /**
  * 整张表单：`fields` 进，行、错误、操作区、（被挡住的）提交都由它安排 —— 它自己一个值都不存，
- * 值仍归调用点的 model（`value` 只读给校验看）。
+ * 值仍归调用点（`value` 与 `onChange` 写在字段配置的同一格里，`Form` 只是把两者原样递给那一格的 `control`）。
+ * 写了 `Form<Values>` 就按 `Values` 把每一格的键与值类型钉住（`Values` 里会 `visible: false` 的键写成可选键）；
+ * 不写就是默认档，键值都不钉。
  * 还没提交过时一格错都不显示；第一次提交之后每次渲染重算，改好了当场消。
  * 提交那一拍永远先算一遍：有错就不调 `onSubmit`，并把第一个有错的 `FormRow` 带进视口、聚焦它里面的控件。
  * 回车与点提交钮走的是同一条路：真 `<form>` 的隐式提交在**只有一个文本框**时也会 fire，所以 `busy` / `disabled` 时回车同样不提交。
  * 调用点只管数据与语义：行怎么排、错误摆哪、什么时候校验、按钮在哪，这里没有口子。
- * @param props.fields - 每格的键 / 标签 / 值 / 校验 / 控件；`visible: false` 的那格当它不存在（不渲染、不校验、不进 `values`）。
- * @param props.onSubmit - 校验全过的那一拍，回的是从 `fields` 现取的键值表；被挡住时不会被调。
+ * @param props.fields - 每格的键 / 标签 / 值 / 值怎么改（`onChange`）/ 校验 / 控件；`visible: false` 的那格当它不存在（不渲染、不校验、不进 `values`）。
+ * @param props.onSubmit - 校验全过的那一拍，回的是从 `fields` 现取的键值表（按 `visibleFieldsOf` 过滤过，不可见那格不在里面）；被挡住时不会被调。
  * @param props.submit - 提交钮文案；`busyLabel` 是提交中换的那句，不给就沿用 `label`。
  * @param props.cancel - 取消钮；给了就排在提交钮左边，`busy` 时一起禁用。
  * @param props.extra - 其余动作（default / danger），排在最左，`busy` 时一起禁用。

package/dist/components/FormNodes.d.ts

@@ -1,31 +1,35 @@
 import type { ReactNode } from '../lib/react.js';
 import type { FormAction } from './FormActions.js';
-import type { FormField, FormValue } from './FormTypes.js';
+import type { FormFieldOf, FormValues } from './FormTypes.js';
 /**
  * 只剩要显示的那些格子 —— `visible: false` 的当它不存在：不渲染、不校验、不进 `values`，也不参与找第一处错误。
  * @param fields - 表单的字段清单。
  * @returns 保序的新数组，`visible` 不给或为 `true` 的都在；全不可见时给空数组。
  */
-export declare function visibleFieldsOf(fields: readonly FormField[]): readonly FormField[];
+export declare function visibleFieldsOf<Values extends object>(fields: readonly FormFieldOf<Values>[]): readonly FormFieldOf<Values>[];
 /**
  * 找出装配错的键：**假值**的键（空串 / `undefined` / `null`，运行期真漏给 `key` 就是这条）每次出现都算一处，
  * 以及同一张表单里出现两次的键 —— 这两样都会让 `id` 撞车、`values` 少一格。
  * @param fields - 表单的字段清单（通常是已经过滤过可见性的那份）。
  * @returns 出问题的键的清单、按首次出现顺序去重；缺失的键一律记成空串（报的时候印成 `（空 key）`），空表给空数组。
  */
-export declare function duplicateKeysOf(fields: readonly FormField[]): readonly string[];
+export declare function duplicateKeysOf(fields: readonly {
+    readonly key: string;
+}[]): readonly string[];
 /**
  * 装配错了要当场诊断：`key` 缺失或重复时给 `console.error` —— 但照渲不误，不 throw。
  * 形式与理由同 `FormActions` 里那颗多出来的 `primary`：装配的小错不该让 `CardBoundary` 把用户的整张卡变空白。
  * @param fields - 表单的字段清单（通常是已经过滤过可见性的那份）。
  */
-export declare function reportDuplicateKeys(fields: readonly FormField[]): void;
+export declare function reportDuplicateKeys(fields: readonly {
+    readonly key: string;
+}[]): 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>>;
+export declare function formValuesOf<Values extends object>(fields: readonly FormFieldOf<Values>[]): Readonly<Values>;
 /**
  * 算每格现在该不该报错：还没提交过（`show` 为 false）时一格都不报 —— 不边打字边骂人。
  * `validate` 返回**真值**才算错，假值（`undefined` / `null` / `false` / 空串）一律当"这格没错" ——
@@ -34,7 +38,7 @@ export declare function formValuesOf(fields: readonly FormField[]): Readonly<Rec
  * @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>>;
+export declare function formProblemsOf<Values extends object>(fields: readonly FormFieldOf<Values>[], show: boolean): Readonly<Record<string, ReactNode | undefined>>;
 /**
  * 按字段顺序取第一处错误 —— 提交被挡住时要带进视口的就是这一格。
  * 判的是**真值**（与 `formProblemsOf` 同一口径）：假值那种"错误文案"渲染出来本来就是空的，不算错。
@@ -42,16 +46,16 @@ export declare function formProblemsOf(fields: readonly FormField[], show: boole
  * @param problems - `formProblemsOf` 那张表，也可以是调用点自己拼的（同样按真值判）。
  * @returns 第一格有错的字段；一格都没错时给 `undefined`。
  */
-export declare function formFirstProblemOf(fields: readonly FormField[], problems: Readonly<Record<string, ReactNode | undefined>>): FormField | undefined;
+export declare function formFirstProblemOf<Values extends object>(fields: readonly FormFieldOf<Values>[], problems: Readonly<Record<string, ReactNode | undefined>>): FormFieldOf<Values> | undefined;
 /**
  * 提交那一拍的结果：有错就挡住（并点出第一处错在哪一格），没错就把键值表交出去。
  */
-export type FormSubmitOutcome = {
+export type FormSubmitOutcome<Values extends object = FormValues> = {
     readonly blocked: true;
-    readonly first: FormField;
+    readonly first: FormFieldOf<Values>;
 } | {
     readonly blocked: false;
-    readonly values: Readonly<Record<string, FormValue>>;
+    readonly values: Readonly<Values>;
 };
 /**
  * 算提交那一拍该干什么 —— `Form` 的提交钮点下去、以及 `<form>` 的 Enter 提交，走的都是它。
@@ -60,7 +64,7 @@ export type FormSubmitOutcome = {
  * @returns `blocked: true` 时带上是按字段顺序数第一格有错的字段（拿它去 `revealFirstProblem`）；
  * `blocked: false` 时带上从 `fields` 现取的键值表。空表一定给 `blocked: false` 与空 values。
  */
-export declare function formSubmitOf(fields: readonly FormField[]): FormSubmitOutcome;
+export declare function formSubmitOf<Values extends object>(fields: readonly FormFieldOf<Values>[]): FormSubmitOutcome<Values>;
 /**
  * 组表单的操作区：调用点给的其余动作在最左，取消在中间，提交永远是最右那颗 `primary`。
  * @param args.extra - 其余动作（default / danger），保持调用点给的顺序；不给就是没有。
@@ -95,8 +99,8 @@ export declare function formActionsOf(args: {
  * @param args.busy - 提交中：每格的绑定 `disabled` 为真。
  * @returns `FormRow` 组成的数组；没有可画的格子时给空数组。
  */
-export declare function formRowsOf(args: {
-    readonly fields: readonly FormField[];
+export declare function formRowsOf<Values extends object>(args: {
+    readonly fields: readonly FormFieldOf<Values>[];
     readonly problems: Readonly<Record<string, ReactNode | undefined>>;
     readonly showProblem: boolean;
     readonly busy: boolean;

package/dist/components/FormNodes.js

@@ -65,11 +65,14 @@ 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;
+        const found = show ? problemOf(field, values) : undefined;
         problems[field.key] = found ? found : undefined;
     }
     return problems;
 }
+function problemOf(field, values) {
+    return field.validate?.(field.value, values);
+}
 /**
  * 按字段顺序取第一处错误 —— 提交被挡住时要带进视口的就是这一格。
  * 判的是**真值**（与 `formProblemsOf` 同一口径）：假值那种"错误文案"渲染出来本来就是空的，不算错。
@@ -144,10 +147,15 @@ export function formRowsOf(args) {
         hint: field.hint,
         problem: args.showProblem ? args.problems[field.key] : undefined,
         layout: field.layout,
-    }, field.control({
+    }, controlOf(field, args.problems, args.showProblem, args.busy)));
+}
+function controlOf(field, problems, showProblem, busy) {
+    return field.control({
         id: `wb-form-${field.key}`,
         name: field.key,
-        invalid: args.showProblem && Boolean(args.problems[field.key]),
-        disabled: args.busy || field.disabled === true,
-    })));
+        invalid: showProblem && Boolean(problems[field.key]),
+        disabled: busy || field.disabled === true,
+        value: field.value,
+        onChange: field.onChange,
+    });
 }

package/dist/components/FormTypes.d.ts

@@ -1,35 +1,56 @@
 import type { ReactNode } from '../lib/react.js';
 import type { FormAction } from './FormActions.js';
 /**
- * 一格控件的值：单值（`TextField` / `SelectField` / `ChoiceGroup` 单选），或一组值（`ChoiceGroup` 多选）。
+ * 默认档一格控件的值：单值（`TextField` / `SelectField` / `ChoiceGroup` 单选），或一组值（`ChoiceGroup` 多选）。
+ * 写了 `Form<Values>` 的类型参数之后，每一格的值类型由 `Values[那一格的键]` 定 —— 这个联合只是**没写类型参数**时的默认档。
  */
 export type FormValue = string | readonly string[];
 /**
- * `Form` 递给控件那一格的绑定：`id` / `name` / `invalid` / `disabled` 由 `Form` 定，控件只负责接上。
+ * 默认档的 `Values`：键是任意 `string`、值是 `FormValue` —— 不写 `Form<Values>` 的类型参数时就是它，
+ * 于是 `fields` 的键与值都不钉（老写法照旧能编），代价是每格拿到的都是那个联合、要自己收窄。
  */
-export interface FormFieldBinding {
+export type FormValues = Readonly<Record<string, FormValue>>;
+/**
+ * `Form` 递给控件那一格的绑定：`id` / `name` / `invalid` / `disabled` 由 `Form` 定；
+ * `value` / `onChange` 就是这一格自己那份配置里的那两个**原样转手**（`Form` 不持有值）——
+ * 控件接上即可，别再自己接 model：值只写在字段配置里那一次。
+ */
+export interface FormFieldBinding<K extends string = string, V = FormValue> {
     readonly id: string;
-    readonly name: string;
+    readonly name: K;
     readonly invalid: boolean;
     readonly disabled: boolean;
+    readonly value: V;
+    readonly onChange: (next: V) => void;
 }
 /**
- * 一格字段的配置：键、标签、值、怎么算错（`validate`）、控件本身 —— 排布、时机、阻断都不写在这里，那些归 `Form`。
+ * 一格字段的配置：键、标签、值、值怎么改（`onChange`）、怎么算错（`validate`）、控件本身 ——
+ * 排布、时机、阻断都不写在这里，那些归 `Form`。`value` 与 `onChange` 就在同一格里，`control` 从绑定直接取
+ * （`(binding) => …（{ value: binding.value, onChange: binding.onChange }）`），值不再有第二处。
  * `validate` 是纯函数、同步、只读 `values`：返回**真值**才算这一格错，假值（`undefined` / `null` / `false` / 空串）
  * 一律当"没错"—— 所以 `(value) => value.trim() === '' && '必填'` 这种用 `&&` 算文案的写法是对的，
  * 它的返回值就是错误行那句话。
  */
-export interface FormField {
-    readonly key: string;
+export interface FormField<K extends string = string, V = FormValue, Vals extends object = FormValues> {
+    readonly key: K;
     readonly label: ReactNode;
     readonly hint?: ReactNode | undefined;
     readonly layout?: 'inline' | 'stacked' | undefined;
-    readonly value: FormValue;
+    readonly value: V;
+    readonly onChange: (next: V) => void;
     readonly visible?: boolean | undefined;
     readonly disabled?: boolean | undefined;
-    readonly validate?: (value: FormValue, values: Readonly<Record<string, FormValue>>) => ReactNode | undefined;
-    readonly control: (binding: FormFieldBinding) => ReactNode;
+    readonly validate?: (value: V, values: Readonly<Vals>) => ReactNode | undefined;
+    readonly control: (binding: FormFieldBinding<K, V>) => ReactNode;
 }
+/**
+ * 把 `Values` 的每一键映射成一格字段 —— 写 `Form<Values>` 时 `fields` 就是这个联合的数组：
+ * `{ key: 'env', … }` 那一格的 `value` / `onChange` / `validate` 只认 `Values['env']`，
+ * `control` 拿到的绑定也只带它。要"键值都不钉"的松档就干脆别写类型参数（默认档 `FormValues`），别手写这个类型。
+ */
+export type FormFieldOf<Values extends object> = {
+    [K in keyof Values & string]: FormField<K, Values[K], Values>;
+}[keyof Values & string];
 /**
  * 提交钮：文案归调用点，位置、禁用与忙态归 `Form`。
  */
@@ -45,11 +66,15 @@ export interface FormCancel {
     readonly onClick: () => void;
 }
 /**
- * `Form` 的契约：fields 配置进，排布、校验时机、提交阻断、操作区全归组件。
+ * `Form` 的契约：`fields` 配置进，排布、校验时机、提交阻断、操作区全归组件。
+ * `Values` 是**那张值表**的形状（不写就是默认档 `FormValues`）：`fields` 的键只能取它的键，
+ * 每格的 `value` / `onChange` / `validate` 只认它那一键的值类型，`onSubmit` 与 `validate` 第二参收到的也是它。
+ * **会 `visible: false` 的键写成可选键**（`branch?: string`）—— 那一格不渲染、不校验、不进 `values`（规则五），
+ * 可选键让"它可能不在表里"这件事在类型上也成立；永远可见的键照常必填。
  */
-export interface FormProps {
-    readonly fields: readonly FormField[];
-    readonly onSubmit: (values: Readonly<Record<string, FormValue>>) => void;
+export interface FormProps<Values extends object = FormValues> {
+    readonly fields: readonly FormFieldOf<Values>[];
+    readonly onSubmit: (values: Readonly<Values>) => void;
     readonly submit: FormSubmit;
     readonly cancel?: FormCancel | undefined;
     readonly extra?: readonly FormAction[] | undefined;

package/dist/components/MockStrip.css

@@ -36,4 +36,14 @@
   border-color: transparent;
   background: var(--dsw-alias-brand-primary);
   color: var(--dsw-alias-label-primary-foreground);
-}
+}
+
+.wb-mockChipOn:hover {
+  border-color: transparent;
+  background: var(--dsw-alias-brand-primary);
+  color: var(--dsw-alias-label-primary-foreground);
+}
+
+.wb-panelBody.wb-panelMany .wb-mockStrip {
+  display: none;
+}

package/dist/components/StateDot.d.ts

@@ -0,0 +1,5 @@
+export type DotState = 'ongoing' | 'warning' | 'done' | 'idle' | string;
+export declare function StateDot({ state, size }: {
+    state: DotState;
+    size: number;
+}): JSX.Element;

package/dist/components/StateDot.js

@@ -0,0 +1,10 @@
+import { h } from '../lib/react.js';
+export function StateDot({ state, size }) {
+    if (state === 'ongoing') {
+        return (h("svg", { className: "wb-loading", viewBox: "0 0 24 24", width: size, height: size, "aria-hidden": "true", style: { display: 'block' } },
+            h("g", { className: "wb-loadingMotion" },
+                h("circle", { className: "wb-loadingTrack", cx: 12, cy: 12, r: 9.5 }),
+                h("circle", { className: "wb-loadingArc", cx: 12, cy: 12, r: 9.5 }))));
+    }
+    return (h("span", { className: "wb-stateDot", "data-state": state, style: { width: size, height: size }, "aria-hidden": "true" }));
+}

package/dist/config/constants.d.ts

@@ -48,6 +48,8 @@ export declare const OPENCLI_TIMEOUT_MS = 120000;
 export declare const OPENCLI_MAX_CONCURRENT = 4;
 /** 启动预热站点那一跳的超时（毫秒）；超时按未热对待，不挡面板。 */
 export declare const WARM_TIMEOUT_MS = 20000;
+/** 体检结果算「还新鲜」的时长（毫秒）：期内再来的强制体检直接回上一次那份快照。 */
+export declare const PREFLIGHT_FRESH_MS = 30000;
 /** 装 / 卸模块包的超时（毫秒）：pnpm 与取包内容都按它算。 */
 export declare const INSTALL_TIMEOUT_MS = 300000;
 /** 查 registry 版本那一次请求的超时（毫秒）。 */

package/dist/config/constants.js

@@ -51,6 +51,8 @@ export const OPENCLI_TIMEOUT_MS = 120_000;
 export const OPENCLI_MAX_CONCURRENT = 4;
 /** 启动预热站点那一跳的超时（毫秒）；超时按未热对待，不挡面板。 */
 export const WARM_TIMEOUT_MS = 20_000;
+/** 体检结果算「还新鲜」的时长（毫秒）：期内再来的强制体检直接回上一次那份快照。 */
+export const PREFLIGHT_FRESH_MS = 30_000;
 /** 装 / 卸模块包的超时（毫秒）：pnpm 与取包内容都按它算。 */
 export const INSTALL_TIMEOUT_MS = 300_000;
 /** 查 registry 版本那一次请求的超时（毫秒）。 */

package/dist/host/__tests__/fakes.d.ts

@@ -0,0 +1,41 @@
+import type { DshShell } from '../../api/dsh.js';
+import type { Opencli } from '../../host/opencli.js';
+export interface ShellCall {
+    command: string;
+    workdir?: string;
+    timeoutMs?: number;
+    onExpiry?: string;
+    stdoutMaxBytes?: number;
+}
+export interface ShellReply {
+    stdout?: string;
+    stderr?: string;
+    exitCode?: number | null;
+    timedOut?: boolean;
+    aborted?: boolean;
+    failWith?: Error;
+}
+export declare function createFakeShell(replies?: ShellReply[] | ((call: ShellCall, index: number) => ShellReply)): {
+    shell: DshShell;
+    calls: ShellCall[];
+    peak: () => number;
+    commands: () => string[];
+};
+export interface OpencliCall {
+    args: readonly string[];
+    key?: string;
+    workdir?: string;
+    refresh?: boolean;
+}
+export declare function createFakeOpencli(replies?: Array<unknown | Error> | ((call: OpencliCall, index: number) => unknown | Error)): {
+    opencli: Opencli;
+    calls: OpencliCall[];
+    keys: () => (string | undefined)[];
+};
+export declare function createFakeLogger(): {
+    logger: {
+        info: () => void;
+        warn: (message: string) => void;
+    };
+    warnings: string[];
+};