@dsh-workbench/shared 0.3.5 → 0.3.7

package/dist/lib/text.js

@@ -1,23 +1,3 @@
-/**
- * 把一个值裹成 shell 里的单引号字面量（值里的单引号一并转义），保证元字符按字面量传递。
- * @param value - 任意值；不是字符串的先 `String()`。
- * @returns 可安全拼进 `/bin/sh -c` 的一段文本 —— 含空格 / `$()` / `;` / 通配符的值都不会被当成语法。
- */
-export function quoteShellArg(value) {
-    return `'${String(value).replace(/'/g, `'\\''`)}'`;
-}
-/**
- * 取一段文本的末尾若干行（如命令输出），顺带去掉首尾空白。
- * @param text - 原文；`null` / `undefined` 当空串。
- * @param lines - 最多留几行，默认 6；0 给全篇、负数从开头砍掉那么多行（都是 `slice` 语义），调用方传正数。
- * @returns 末尾若干行、去首尾空行后的文本；原文行数不够就全给，空输入给空串。
- */
-export function tailLines(text, lines = 6) {
-    const all = String(text ?? '')
-        .trim()
-        .split('\n');
-    return all.slice(-lines).join('\n');
-}
 function candidateStarts(raw) {
     const starts = [];
     for (let index = 0; index < raw.length; index += 1) {

package/dist/testing/declaration.js

@@ -1,6 +1,6 @@
 import fs from 'node:fs';
 import { fileURLToPath } from 'node:url';
-import { readDeclaration } from '../api/unit-declaration.js';
+import { readDeclaration } from '../host/unit-declaration.js';
 export function declarationOfPackage(pkg, packageJson) {
     const at = typeof packageJson === 'string' ? packageJson : fileURLToPath(packageJson);
     let parsed;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dsh-workbench/shared",
-  "version": "0.3.5",
+  "version": "0.3.7",
   "description": "工作台与模块共享的纯代码与契约类型：类型、纯逻辑、哑组件、平台解析。宿主侧的东西从 /host 进（不影响浏览器产物）。",
   "license": "MIT",
   "type": "module",

package/src/api/__tests__/facts.test.ts

@@ -2,10 +2,7 @@ import { describe, expect, it, vi } from 'vitest';
 import {
   createFactChannel,
   factOfRoute,
-  isFactScope,
   parseFactFrame,
-  scopePrefixOf,
-  unitFactScope,
   type FactFrame,
   type FactTransport,
 } from '../facts.js';
@@ -262,13 +259,3 @@ describe('factOfRoute', () => {
     expect(factOfRoute('capability')).toBe('capability');
   });
 });
-
-describe('unitFactScope', () => {
-  it('命名空间 = 模块 id + `*`（"这个模块的数据全作废"只写一个字符串）', () => {
-    expect(unitFactScope('cmdb')).toBe('cmdb*');
-    expect(isFactScope('cmdb*')).toBe(true);
-    expect(isFactScope('*')).toBe(false);
-    expect(isFactScope('cmdb/summary')).toBe(false);
-    expect(scopePrefixOf('cmdb*')).toBe('cmdb');
-  });
-});

package/src/api/__tests__/long-task.test.ts

@@ -1,5 +1,14 @@
 import { describe, expect, it } from 'vitest';
-import { longTaskDot, longTaskPollMs, longTaskRunsOf, runsRouteOf } from '../long-task.js';
+import {
+  longTaskDot,
+  longTaskPollMs,
+  longTaskRunsOf,
+  longTaskStopPress,
+  longTaskStopStage,
+  LONG_TASK_STOP_ARM_MS,
+  runsRouteOf,
+  stopRouteOf,
+} from '../long-task.js';
 
 describe('runsRouteOf', () => {
   it('★ 事实名 = 路由名（三处同一个来源，改一处不可能漏另一处）', () => {
@@ -8,6 +17,14 @@ describe('runsRouteOf', () => {
   });
 });
 
+describe('stopRouteOf（停止那条写路由）', () => {
+  it('★ 就是读路由 + `/stop`（读口与写口同一个单元名，不另造一套命名）', () => {
+    expect(stopRouteOf('cmdb')).toBe('cmdb/runs/stop');
+    expect(stopRouteOf('issues')).toBe('issues/runs/stop');
+    expect(stopRouteOf('cmdb')).toBe(`${runsRouteOf('cmdb')}/stop`);
+  });
+});
+
 describe('longTaskDot', () => {
   it('★ 两个"还在等"的状态都转圈：等编排与等你登录是同一个信号', () => {
     expect(longTaskDot('running')).toBe('ongoing');
@@ -15,6 +32,29 @@ describe('longTaskDot', () => {
     expect(longTaskDot('ok')).toBe('done');
     expect(longTaskDot('failed')).toBe('error');
   });
+
+  it('★ 用户按停的那一趟是灰点：不是成功、不是出错，落进 idle', () => {
+    expect(longTaskDot('stopped')).toBe('idle');
+  });
+});
+
+describe('longTaskStopStage / longTaskStopPress（两按：第一次上膛，第二次才真发）', () => {
+  it('★ 三档：没上膛 / 上了膛 / 请求在飞；在飞压过一切', () => {
+    expect(longTaskStopStage({ armed: false, busy: false })).toBe('idle');
+    expect(longTaskStopStage({ armed: true, busy: false })).toBe('armed');
+    expect(longTaskStopStage({ armed: false, busy: true })).toBe('busy');
+    expect(longTaskStopStage({ armed: true, busy: true })).toBe('busy');
+  });
+
+  it('★ 按一下该干什么：idle → arm、armed → fire、busy → ignore（在飞时按不动）', () => {
+    expect(longTaskStopPress('idle')).toBe('arm');
+    expect(longTaskStopPress('armed')).toBe('fire');
+    expect(longTaskStopPress('busy')).toBe('ignore');
+  });
+
+  it('★ 上膛时限照 dsh：3 秒自己落膛', () => {
+    expect(LONG_TASK_STOP_ARM_MS).toBe(3000);
+  });
 });
 
 describe('longTaskRunsOf（这一读交回的"当前那些趟"）', () => {

package/src/api/context-ref.ts

@@ -11,10 +11,6 @@ export interface ContextRef {
   readonly parts: readonly string[];
 }
 
-const MARKER = new RegExp(`@${CONTEXT_MARKER_NAME}:([a-z][a-z0-9-]*:[A-Za-z0-9._~%#/-]+)`, 'g');
-
-const TRAILING_PUNCTUATION = /[.,;:!?]+$/;
-
 /**
  * 把引用拼回标记体里的那一段文本（不含 @ 与标记名）。
  * @param ref 要拼的引用。
@@ -24,21 +20,6 @@ export function encodeRef(ref: ContextRef): string {
   return `${ref.kind}:${ref.parts.join('/')}`;
 }
 
-/**
- * 把 kind:part/part 文本读回引用。
- * @param text 待解析文本。
- * @returns 没冒号、冒号在首尾、种类不是小写字母开头、或冒号后为空时给 undefined；不抛异常。
- */
-export function decodeRef(text: string): ContextRef | undefined {
-  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 的结果。
@@ -56,23 +37,3 @@ export function markerBody(encoded: string): string {
 export function buildMarker(ref: ContextRef): string {
   return `@${markerBody(encodeRef(ref))}`;
 }
-
-/**
- * 从一段文本里按出现顺序捞出所有标记引用，同一个引用只留第一次。
- * @param text 任意文本；null / undefined 当空串。
- * @returns 解析不出来的标记会被丢掉，所以结果只含合法引用，可能为空数组。
- */
-export function parseMarkers(text: string): ContextRef[] {
-  const seen = new Set<string>();
-  const refs: ContextRef[] = [];
-  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/src/api/facts.ts

@@ -12,15 +12,6 @@ export interface FactFrame {
  */
 export const FACT_SCOPE_SUFFIX = '*';
 
-/**
- * 由单元 id 拼出它那一族事实的范围名。
- * @param unit 单元 id，不带后缀。
- * @returns <unit>* —— 永远是范围名，不是某一条事实。
- */
-export function unitFactScope(unit: string): string {
-  return `${unit}${FACT_SCOPE_SUFFIX}`;
-}
-
 /**
  * 判一个名字是不是范围查法，不是问这条事实存不存在。
  * @param name 事实名或范围名。

package/src/api/long-task.ts

@@ -1,7 +1,7 @@
 /**
- * 一条长任务的四种态；needs-login 与 running 一样算还没结束。
+ * 一条长任务的五种态；needs-login 与 running 一样算还没结束，stopped 是用户自己按停的。
  */
-export type LongTaskStatus = 'running' | 'needs-login' | 'ok' | 'failed';
+export type LongTaskStatus = 'running' | 'needs-login' | 'stopped' | 'ok' | 'failed';
 
 /**
  * 长任务步骤流里的一行：kind 定样式，登录那一步带 loginUrl 给用户去点。
@@ -21,6 +21,15 @@ export function runsRouteOf(unit: string): string {
   return `${unit}/runs`;
 }
 
+/**
+ * 停止那条写路由（走 actions 通道的资源名）：`<单元>/runs/stop`。
+ * @param unit 单元 id。
+ * @returns <unit>/runs/stop。
+ */
+export function stopRouteOf(unit: string): string {
+  return `${unit}/runs/stop`;
+}
+
 /**
  * 长任务读口回的载荷：一串 run，形状由模块自己定，外壳只透传。
  */
@@ -63,8 +72,8 @@ export function longTaskRunsOf<T>(state: {
 
 /**
  * 把长任务态折成状态点的那一档。
- * @param status 长任务的四种态。
- * @returns ongoing / done / error / idle；needs-login 也算进行中。
+ * @param status 长任务的五种态。
+ * @returns ongoing / done / error / idle；needs-login 也算进行中；`stopped` 落进 idle —— 灰点：不是成功、不是出错，是用户自己按停的。
  */
 export function longTaskDot(status: LongTaskStatus): 'ongoing' | 'done' | 'error' | 'idle' {
   if (status === 'ok') return 'done';
@@ -72,3 +81,36 @@ export function longTaskDot(status: LongTaskStatus): 'ongoing' | 'done' | 'error
   if (status === 'running' || status === 'needs-login') return 'ongoing';
   return 'idle';
 }
+
+/**
+ * 停止钮的三档：没上膛 / 上了膛 / 请求在飞。
+ */
+export type LongTaskStopStage = 'idle' | 'armed' | 'busy';
+
+/**
+ * 算停止钮现在在哪一档。
+ * @param state armed = 已经按过第一下、在等第二下；busy = 停止请求已经在飞。
+ * @returns busy 优先（在飞时按不动），其次 armed，否则 idle。
+ */
+export function longTaskStopStage(state: {
+  readonly armed: boolean;
+  readonly busy: boolean;
+}): LongTaskStopStage {
+  if (state.busy) return 'busy';
+  return state.armed ? 'armed' : 'idle';
+}
+
+/**
+ * 按一下该干什么：第一次只上膛（'arm'），上了膛再按才真发（'fire'），在飞时按不动（'ignore'）。
+ * @param stage 现在这一档（先过 `longTaskStopStage`）。
+ * @returns 'arm' / 'fire' / 'ignore'，调用点照它上膛、落膛加发请求、或什么都不做。
+ */
+export function longTaskStopPress(stage: LongTaskStopStage): 'arm' | 'fire' | 'ignore' {
+  if (stage === 'busy') return 'ignore';
+  return stage === 'armed' ? 'fire' : 'arm';
+}
+
+/**
+ * 上膛后多久自己落膛（毫秒）。3 秒 = dsh 那行现在的取值。
+ */
+export const LONG_TASK_STOP_ARM_MS = 3000;

package/src/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/src/components/ConfirmBar.test.tsx

@@ -0,0 +1,130 @@
+import { readFileSync } from 'node:fs';
+import { describe, expect, it } from 'vitest';
+import { ConfirmBar, type ConfirmRow } from './ConfirmBar.js';
+import { FormActions, type FormAction } from './FormActions.js';
+import { Note } from './Note.js';
+import { Rows } from './Rows.js';
+
+interface AnyElement {
+  readonly type: unknown;
+  readonly props: Record<string, unknown>;
+  readonly key?: unknown;
+}
+
+function action(key: string, kind?: FormAction['kind']): FormAction {
+  return { key, label: key, kind, onClick: () => {} };
+}
+
+function row(key: string): ConfirmRow {
+  return { key, label: `名字-${key}`, value: `值-${key}` };
+}
+
+function bar(extra: Record<string, unknown> = {}): AnyElement {
+  return ConfirmBar({
+    title: '发布到 prod？',
+    actions: [action('publish', 'primary')],
+    ...extra,
+  }) as unknown as AnyElement;
+}
+
+function childrenOf(node: AnyElement): AnyElement[] {
+  return ((node.props['children'] as unknown[]) ?? []).filter(
+    (one): one is AnyElement => typeof one === 'object' && one !== null,
+  );
+}
+
+describe('确认条（契约类 wb-confirmBar）', () => {
+  it('★ 是一个 role="group" 的条，读屏名默认取字符串标题', () => {
+    const root = bar();
+
+    expect(root.props['role']).toBe('group');
+    expect(root.props['aria-label']).toBe('发布到 prod？');
+    expect(childrenOf(root)[0]?.props['className']).toBe('wb-confirmBarTitle');
+  });
+
+  it('显式给了 label 就用它；标题不是字符串又没给 label 就不设读屏名', () => {
+    expect(bar({ label: '发布确认' }).props['aria-label']).toBe('发布确认');
+    expect(bar({ title: 42 }).props['aria-label']).toBeUndefined();
+  });
+
+  it('busy 只喂 aria-busy，不改动作那一块', () => {
+    const root = bar({ busy: true, actions: [action('publish', 'primary'), action('cancel')] });
+
+    expect(root.props['aria-busy']).toBe(true);
+    expect(childrenOf(root)[1]?.props['actions']).toHaveLength(2);
+  });
+
+  it('★ 三件都借现成的：键值走 Rows、失败那句走 Note(tone=problem, role=alert)、动作走 FormActions', () => {
+    const actions = [action('publish', 'primary'), action('cancel')];
+    const root = bar({ rows: [row('env')], problem: '源上没有这个包', actions });
+    const children = childrenOf(root);
+
+    expect(children[0]?.props['className']).toBe('wb-confirmBarTitle');
+    expect(children[1]?.type).toBe(Rows);
+    expect(children[2]?.type).toBe(Note);
+    expect(children[2]?.props['tone']).toBe('problem');
+    expect(children[2]?.props['role']).toBe('alert');
+    expect(children[3]?.type).toBe(FormActions);
+    expect(children[3]?.props['actions']).toBe(actions);
+  });
+
+  it('★ 没给的那几块不占位：只要标题与动作区', () => {
+    expect(childrenOf(bar())).toHaveLength(2);
+    expect(childrenOf(bar({ rows: [] }))).toHaveLength(2);
+    expect(childrenOf(bar({ hint: '这一趟会重启一次' }))).toHaveLength(3);
+  });
+
+  it('★ 键值那几格走 Row 的 label / value 两格（key 交给 React 认列表），不是自己画两栏', () => {
+    const root = bar({ rows: [row('env'), row('branch')] });
+    const rowNodes = childrenOf(childrenOf(root)[1] as AnyElement);
+
+    expect(rowNodes.map((one) => one.props['label'])).toEqual(['名字-env', '名字-branch']);
+    expect(rowNodes.map((one) => one.props['value'])).toEqual(['值-env', '值-branch']);
+    expect(rowNodes.map((one) => one.key)).toEqual(['env', 'branch']);
+  });
+});
+
+const CSS = readFileSync(new URL('./ConfirmBar.css', import.meta.url), 'utf8');
+
+function declarations(selector: string): string[] {
+  for (const block of CSS.split('}')) {
+    const [head, ...rest] = block.split('{');
+    if (rest.length === 0 || head === undefined) continue;
+    if (head.trim() !== selector) continue;
+    return rest
+      .join('{')
+      .split(';')
+      .map((one) => one.replace(/\s+/g, ' ').trim())
+      .filter((one) => one !== '');
+  }
+  throw new Error(`ConfirmBar.css 里没有这条规则：${selector}`);
+}
+
+describe('确认条的版式（ADR-0073 §2.2）', () => {
+  it('★ 占满自己那一格（有内边距与描边 ⇒ 配 border-box），别在横向父容器里退回内容宽', () => {
+    const rule = declarations('.wb-confirmBar');
+
+    expect(rule).toContain('width: 100%');
+    expect(rule).toContain('box-sizing: border-box');
+  });
+
+  it('★ 一档间距、描边与圆角都走令牌', () => {
+    const rule = declarations('.wb-confirmBar');
+
+    expect(rule).toContain('gap: var(--wb-len-8)');
+    expect(rule).toContain('padding: var(--wb-len-10) var(--wb-len-12)');
+    expect(rule).toContain('border: 0.5px solid var(--dsw-alias-border-l3)');
+    expect(rule).toContain('border-radius: var(--dsw-radius-md)');
+  });
+
+  it('★ 标题与说明的大小走令牌，标题比说明重一档', () => {
+    const title = declarations('.wb-confirmBarTitle');
+    const hint = declarations('.wb-confirmBarHint');
+
+    expect(title).toContain('font-size: var(--dsw-font-xxs-12-font-size)');
+    expect(title).toContain('line-height: var(--wb-line-18)');
+    expect(title).toContain('font-weight: 600');
+    expect(hint).toContain('font-size: var(--dsw-font-xxxs-11-font-size)');
+    expect(hint).toContain('line-height: var(--wb-line-16)');
+  });
+});

package/src/components/ConfirmBar.tsx

@@ -0,0 +1,63 @@
+import type { ReactNode } from '../lib/react.js';
+import { h } from '../lib/react.js';
+import { FormActions, type FormAction } from './FormActions.js';
+import { Note } from './Note.js';
+import { Row, Rows } from './Rows.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 function ConfirmBar({ title, hint, rows, actions, problem, busy, label }: ConfirmBarProps) {
+  const name = label ?? (typeof title === 'string' ? title : undefined);
+  return (
+    <div className="wb-confirmBar" role="group" aria-label={name} aria-busy={busy}>
+      <p className="wb-confirmBarTitle">{title}</p>
+      {hint === undefined ? null : <p className="wb-confirmBarHint">{hint}</p>}
+      {rows === undefined || rows.length === 0 ? null : (
+        <Rows>
+          {rows.map((row) => (
+            <Row key={row.key} label={row.label} value={row.value} />
+          ))}
+        </Rows>
+      )}
+      {problem === undefined ? null : (
+        <Note tone="problem" role="alert">
+          {problem}
+        </Note>
+      )}
+      <FormActions actions={actions} />
+    </div>
+  );
+}

package/src/components/Form.test.tsx

@@ -20,6 +20,7 @@ function field(key: string, value: FormValue, validate?: FormField['validate']):
     key,
     label: key,
     value,
+    onChange: () => {},
     control: (binding) => `${key}:${binding.id}:${String(binding.invalid)}:${String(binding.disabled)}`,
     ...(validate === undefined ? {} : { validate }),
   };
@@ -402,6 +403,20 @@ describe('formRowsOf', () => {
     expect(propsOf(rows[0])['children']).toBe('env:wb-form-env:true:false');
   });
 
+  it('★ 这一格的 value / onChange 从字段配置原样进绑定（值只写一处）', () => {
+    const onChange = (): void => {};
+    const probe: FormField = {
+      key: 'env',
+      label: 'env',
+      value: 'prod',
+      onChange,
+      control: (binding) => `${String(binding.value)}:${String(binding.onChange === onChange)}`,
+    };
+    const rows = formRowsOf({ fields: [probe], problems: {}, showProblem: false, busy: false });
+
+    expect(propsOf(rows[0])['children']).toBe('prod:true');
+  });
+
   it('★ 还没提交过（showProblem: false）：文案不画、invalid 也不给（done 之前一律 false）', () => {
     const rows = formRowsOf({ fields: [field('env', 'prod')], problems, showProblem: false, busy: false });
 

package/src/components/Form.tsx

@@ -1,5 +1,5 @@
 import { h, useEffect, useRef, useState } from '../lib/react.js';
-import type { FormProps } from './FormTypes.js';
+import type { FormProps, FormValues } from './FormTypes.js';
 import { FormActions } from './FormActions.js';
 import { FormRows } from './FormRows.js';
 import { Note } from './Note.js';
@@ -16,13 +16,15 @@ 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` 时一起禁用。
@@ -31,7 +33,7 @@ import './Form.css';
  * @param props.problem - 整表级那句错（提交失败），落在行与操作区之间；不给就不画。
  * @returns 一个 `<form>`（`noValidate`：报错形状归 `FormRow`，不走浏览器的气泡）。
  */
-export function Form(props: FormProps) {
+export function Form<Values extends object = FormValues>(props: FormProps<Values>) {
   const { fields, onSubmit, submit, cancel, extra, busy = false, disabled = false, problem } = props;
   const [done, setDone] = useState(false);
   const [reveal, setReveal] = useState(0);