@morlay/dsh-client-ui-primitives 0.0.3 → 0.0.5

package/src/client/schema-form/hints.ts

@@ -1,127 +1,69 @@
-/**
- * 通用表单的提示面：业务知道、而 schema 表达不了的结构信息。
- *
- * 两件事：**dict 字段的候选键**（例如「会话模式」那一行，键是运行期清单里的模式 id，schema 里写不出来），以及
- * **字段的候选值**（选服务商、选模型这类——候选来自部署里的另一份配置，还经常互相依赖）。业务在客户端注册一个
- * 同步读数，表单一侧在投影时用它补出「未配置」行或把字段画成选择器。
- *
- * 读数必须是**同步**的：投影发生在渲染帧里。异步来源（HTTP / remote）由业务自己取好再注册；注册本身就当作一次
- * 变更通知（所以"取到清单后再注册"是推荐用法）。
- */
+// 通用表单的提示面：注册同步读数，投影时补出 dict 的候选键、字段的候选值与文案。
+//
+// 读数必须同步（投影发生在渲染帧里）：异步来源由业务取好再注册，注册本身即一次变更通知。
 
 import { Service } from "@deepseek-ai/cordis";
 import type { Context } from "@deepseek-ai/cordis";
 import { DYNAMIC_SEGMENT } from "./schema-node.ts";
 
-/** 一个 dict 字段的候选键读数。 */
+// 一个 dict 字段的候选键读数。
 export type SuggestedKeysReader = () => readonly string[];
 
-/** 一个字段的文案（业务知道的说法；schema 上没有 title 这种位）。 */
+// 一个字段的文案（业务知道的说法；schema 上没有 title 这种位）。
 export interface FieldText {
-  /** 短名字（行式视图里当注释的抬头）。 */
+  // 短名字（行式视图里当注释的抬头）。
   label?: string | undefined;
-  /** 一句话说明。 */
+  // 一句话说明。
   hint?: string | undefined;
 }
 
-/** 一个字段的文案读数。 */
+// 一个字段的文案读数。
 export type FieldTextReader = () => FieldText;
 
-/** 一个可选项：要写进去的值，以及页面上显示的名字。 */
+// 一个可选项：要写进去的值，以及页面上显示的名字。
 export interface SelectOption {
-  /** 选中时写进配置的值。 */
+  // 选中时写进配置的值。
   value: unknown;
-  /** 显示名；省略就用值本身。 */
+  // 显示名；省略就用值本身。
   label?: string | undefined;
 }
 
-/** 一个字段的候选值读数。 */
+// 一个字段的候选值读数。
 export interface SelectSpec {
-  /**
-   * 候选依赖哪些**兄弟字段**（相对该字段所在对象的路径）。
-   *
-   * 依赖只声明"什么时候要重算"：读侧在投影时按当前读数（草稿优先）求一次候选，所以声明了依赖的字段会随着
-   * 兄弟字段的编辑立刻换候选——「选完服务商才列它有哪些模型」就是这么来的。
-   */
+  // 候选依赖哪些兄弟字段（相对该字段所在对象的路径）：声明只表示"何时重算"，编辑兄弟字段即换候选。
   dependsOn?: readonly (readonly string[])[] | undefined;
-  /**
-   * 求候选。
-   * @param read - 按依赖路径（相对该字段所在对象）读当前值：草稿优先。
-   * @returns 可选项，顺序即页面上的顺序。
-   */
+  // 按依赖路径读当前值（草稿优先），返回可选项（顺序即页面顺序）。
   options: (read: (path: readonly string[]) => unknown) => readonly SelectOption[];
 }
 
-/** 一个命名空间里各字段的候选键、文案与候选值。 */
+// 一个命名空间里各字段的候选键、文案与候选值。
 export interface SchemaFormHintsFace {
-  /**
-   * 注册一个 dict 字段的候选键读数（重复注册同一处会覆盖，并通知一次）。
-   * @param ns - settings 命名空间（行 id）。
-   * @param path - 该 dict 字段的具体路径（顶层字段就是 `['models']`）。
-   * @param read - 同步读数：当前候选键（顺序即页面上的顺序）。
-   * @returns 注销函数。
-   */
+  // 注册一个 dict 字段的候选键读数（同处重复注册会覆盖并通知一次）；返回注销函数。
   suggestKeys(ns: string, path: readonly string[], read: SuggestedKeysReader): () => void;
-  /**
-   * 读某处当前声明的候选键。
-   * @param ns - settings 命名空间。
-   * @param path - 该字段的路径。
-   * @returns 候选键；没注册过就是空数组。
-   */
+  // 读某处当前声明的候选键；没注册过就是空数组。
   keysFor(ns: string, path: readonly string[]): readonly string[];
 
-  /**
-   * 注册一个字段的文案（短名 + 一句话说明）。行式视图把它画成注释行；schema 的 `description` 是兜底。
-   * @param ns - settings 命名空间。
-   * @param path - 该字段的路径。
-   * @param read - 同步读数。
-   * @returns 注销函数。
-   */
+  // 注册一个字段的文案（短名 + 一句话说明）：行式视图画成注释行，schema 的 `description` 是兜底；返回注销函数。
   describe(ns: string, path: readonly string[], read: FieldTextReader): () => void;
 
-  /**
-   * 读某处当前注册的文案。
-   * @param ns - settings 命名空间。
-   * @param path - 该字段的路径。
-   * @returns 文案；没注册过就是空对象。
-   */
+  // 读某处当前注册的文案；没注册过就是空对象。
   textFor(ns: string, path: readonly string[]): FieldText;
 
-  /**
-   * 注册一个字段的候选值读数（页面据此把字段画成选择器，并随依赖字段变化重算）。
-   * @param ns - settings 命名空间。
-   * @param path - 该字段的路径。
-   * @param spec - 候选取法与它依赖的兄弟字段。
-   * @returns 注销函数。
-   */
+  // 注册一个字段的候选值读数（页面据此画成选择器，随依赖字段变化重算）；返回注销函数。
   select(ns: string, path: readonly string[], spec: SelectSpec): () => void;
 
-  /**
-   * 注册一个**具名候选源**：schema 上用 `role('select', { source })` 认领它，字段因此不必在客户端按 ns/path
-   * 登记——同一个源可以被多行、多个字段复用（「服务商」「模型」就是这种）。
-   * @param name - 源的名字（schema 的 `role` extra 里写的那一个）。
-   * @param spec - 候选取法与它依赖的兄弟字段。
-   * @returns 注销函数。
-   */
+  // 注册一个具名候选源：schema 上用 `role('select', { source })` 认领，字段不必按 ns/path 登记，一个源可被多行复用。
+  // 返回注销函数。
   source(name: string, spec: SelectSpec): () => void;
 
-  /**
-   * 读一个具名候选源。
-   * @param name - 源的名字。
-   * @returns 该源的读数；没注册过就是 `undefined`。
-   */
+  // 读一个具名候选源；没注册过就是 `undefined`。
   sourceFor(name: string): SelectSpec | undefined;
 
-  /**
-   * 读某处当前声明的候选值读数。
-   * @param ns - settings 命名空间。
-   * @param path - 该字段的路径。
-   * @returns 候选读数；没注册过就是 `undefined`。
-   */
+  // 读某处当前声明的候选值读数；没注册过就是 `undefined`。
   selectFor(ns: string, path: readonly string[]): SelectSpec | undefined;
 }
 
-/** 提示面的完整服务（业务用注册侧，表单一侧用读侧）。 */
+// 提示面的完整服务（业务用注册侧，表单一侧用读侧）。
 export class SchemaFormHints extends Service implements SchemaFormHintsFace {
   readonly #readers = new Map<string, SuggestedKeysReader>();
   readonly #texts = new Map<string, FieldTextReader>();
@@ -129,27 +71,18 @@ export class SchemaFormHints extends Service implements SchemaFormHintsFace {
   readonly #sources = new Map<string, SelectSpec>();
   readonly #listeners = new Set<() => void>();
 
-  /** @param ctx - 提供本服务的插件上下文。 */
   constructor(ctx: Context) {
     super(ctx, "schemaFormHints");
   }
 
-  /** @param ns - settings 命名空间。 @param path - 字段路径。 @returns 该处的键。 */
   keysFor(ns: string, path: readonly string[]): readonly string[] {
     return lookup(this.#readers, ns, path)?.() ?? [];
   }
 
-  /** @param ns - settings 命名空间。 @param path - 字段路径。 @returns 该处注册的文案。 */
   textFor(ns: string, path: readonly string[]): FieldText {
     return lookup(this.#texts, ns, path)?.() ?? {};
   }
 
-  /**
-   * @param ns - settings 命名空间。
-   * @param path - 字段路径。
-   * @param spec - 候选取法与依赖。
-   * @returns 注销函数。
-   */
   select(ns: string, path: readonly string[], spec: SelectSpec): () => void {
     const key = locationKey(ns, path);
     this.#selects.set(key, spec);
@@ -161,16 +94,10 @@ export class SchemaFormHints extends Service implements SchemaFormHintsFace {
     };
   }
 
-  /** @param ns - settings 命名空间。 @param path - 字段路径。 @returns 该处注册的候选读数。 */
   selectFor(ns: string, path: readonly string[]): SelectSpec | undefined {
     return lookup(this.#selects, ns, path);
   }
 
-  /**
-   * @param name - 源的名字。
-   * @param spec - 候选取法与依赖。
-   * @returns 注销函数。
-   */
   source(name: string, spec: SelectSpec): () => void {
     this.#sources.set(name, spec);
     this.#publish();
@@ -181,17 +108,10 @@ export class SchemaFormHints extends Service implements SchemaFormHintsFace {
     };
   }
 
-  /** @param name - 源的名字。 @returns 该源注册的候选读数。 */
   sourceFor(name: string): SelectSpec | undefined {
     return this.#sources.get(name);
   }
 
-  /**
-   * @param ns - settings 命名空间。
-   * @param path - 字段路径。
-   * @param read - 同步读数。
-   * @returns 注销函数。
-   */
   describe(ns: string, path: readonly string[], read: FieldTextReader): () => void {
     const key = locationKey(ns, path);
     this.#texts.set(key, read);
@@ -203,12 +123,6 @@ export class SchemaFormHints extends Service implements SchemaFormHintsFace {
     };
   }
 
-  /**
-   * @param ns - settings 命名空间。
-   * @param path - 字段路径。
-   * @param read - 同步读数。
-   * @returns 注销函数。
-   */
   suggestKeys(ns: string, path: readonly string[], read: SuggestedKeysReader): () => void {
     const key = locationKey(ns, path);
     this.#readers.set(key, read);
@@ -220,11 +134,7 @@ export class SchemaFormHints extends Service implements SchemaFormHintsFace {
     };
   }
 
-  /**
-   * 观察候选键的变化（注册与注销）。
-   * @param listener - 变更回调。
-   * @returns 取消订阅。
-   */
+  // 观察候选键的变化（注册与注销）；返回取消订阅。
   subscribe(listener: () => void): () => void {
     this.#listeners.add(listener);
     return () => {
@@ -232,9 +142,7 @@ export class SchemaFormHints extends Service implements SchemaFormHintsFace {
     };
   }
 
-  /**
-   * 重新通知一次：读数背后的数据变了（业务自己知道），页面据此重算候选行。
-   */
+  // 重新通知一次：读数背后的数据变了（业务自己知道），页面据此重算候选行。
   refresh(): void {
     this.#publish();
   }
@@ -244,20 +152,12 @@ export class SchemaFormHints extends Service implements SchemaFormHintsFace {
   }
 }
 
-/** 一处字段的定位键（命名空间 + 路径）。 */
+// 一处字段的定位键（命名空间 + 路径）。
 function locationKey(ns: string, path: readonly string[]): string {
   return `${ns}\u0000${path.join("\u0000")}`;
 }
 
-/**
- * 按具体路径找一处注册：先精确匹配，再试**模板变体**（动态键 / 数组下标的段写成 `*`）。
- *
- * 业务因此可以注册一次 `models.*.provider` 就覆盖每个模式，不必知道运行期有哪些键。
- * @param map - 某类注册表。
- * @param ns - settings 命名空间。
- * @param path - 具体路径。
- * @returns 命中的注册，或 `undefined`。
- */
+// 按具体路径找一处注册：先精确匹配，再试模板变体（动态键 / 数组下标的段写成 `*`，一条 `models.*.provider` 覆盖整个模式）。
 function lookup<T>(map: Map<string, T>, ns: string, path: readonly string[]): T | undefined {
   const exact = map.get(locationKey(ns, path));
   if (exact !== undefined) return exact;
@@ -268,7 +168,7 @@ function lookup<T>(map: Map<string, T>, ns: string, path: readonly string[]): T
   return undefined;
 }
 
-/** 具体路径的模板变体（首段是顶层字段名，保持原样）：通配得多的先试。 */
+// 具体路径的模板变体（首段是顶层字段名，保持原样）：通配得多的先试。
 function* templates(path: readonly string[]): Generator<readonly string[]> {
   const wildcardable = Math.max(0, path.length - 1);
   for (let bits = (1 << wildcardable) - 1; bits > 0; bits--) {
@@ -280,7 +180,7 @@ function* templates(path: readonly string[]): Generator<readonly string[]> {
 
 declare module "@deepseek-ai/cordis" {
   interface Context {
-    /** 通用表单的提示面（dict 的候选键）。 */
+    // 通用表单的提示面（dict 的候选键）。
     schemaFormHints: SchemaFormHints;
   }
 }

package/src/client/schema-form/index.ts

@@ -1,16 +1,14 @@
-/**
- * client 半：为每个可由 schema 生成配置页的行注册本行的配置入口，并给出字段级自定义输入的槽契约。
- *
- * | 面                                   | 呈现                                                             |
- * | ------------------------------------ | ---------------------------------------------------------------- |
- * | `plugins.row.config`（key 见 `rows.ts`） | `view: 'page'` 渲染该行 schema 生成的表单；`summary` 不画东西     |
- * | Factory `settings.schema-form.form`  | 行注册项经它渲染同一份表单体，字段槽因此只声明一次               |
- * | `settings.schema-form.field`         | chain 槽：业务方按 `role` 或 `ns + path` 认领字段的控件与文案    |
- *
- * 数据面是 host 的 settings 投影与共享配置表单（`ctx.configForms` / `ctx.settingsSchema`）；bundle 与行的对应关系
- * 来自 `remote.pluginManager.listBundles()`。手写卡片用默认 priority 0 注册，按 slots 的 cell winner 规则自然遮住
- * 这里的自动项，因此两种页面可以并存、迁移不必一次做完。
- */
+// client 半：为每个可由 schema 生成配置页的行注册本行的配置入口，并给出字段级自定义输入的槽契约。
+//
+// | 面                                   | 呈现                                                             |
+// | ------------------------------------ | ---------------------------------------------------------------- |
+// | `plugins.row.config`（key 见 `rows.ts`） | `view: 'page'` 渲染该行 schema 生成的表单；`summary` 不画东西     |
+// | Factory `settings.schema-form.form`  | 行注册项经它渲染同一份表单体，字段槽因此只声明一次               |
+// | `settings.schema-form.field`         | chain 槽：业务方按 `role` 或 `ns + path` 认领字段的控件与文案    |
+//
+// 数据面是 host 的 settings 投影与共享配置表单（`ctx.configForms` / `ctx.settingsSchema`）；bundle 与行的对应关系
+// 来自 `remote.pluginManager.listBundles()`。手写卡片用默认 priority 0 注册，按 slots 的 cell winner 规则自然遮住
+// 这里的自动项，因此两种页面可以并存。
 
 import type { Context } from "@deepseek-ai/cordis";
 import type {} from "@deepseek-ai/dsh-api-remotes/client";
@@ -29,10 +27,10 @@ import { RowRegistration } from "./rows.ts";
 import { SchemaForm } from "./SchemaForm.tsx";
 import type { SchemaFormProps } from "./slot-contract.ts";
 
-/** 本包字典与槽位文案的命名空间。 */
+// 本包字典与槽位文案的命名空间。
 export const NS = "settings.schema-form";
 
-/** 需要的服务：槽位、字典、共享配置表单、schema 服务与插件管理（bundle 行清单）。 */
+// 需要的服务：槽位、字典、共享配置表单、schema 服务与插件管理（bundle 行清单）。
 export const inject = [
   "slots",
   "locale",
@@ -72,13 +70,10 @@ export type {
 } from "./hints.ts";
 export type { SuggestedKeys } from "./schema-node.ts";
 
-/** 行配置入口的注册项：`page` 画表单，`summary` 不画（行的描述来自包自己的 locale）。 */
+// 行配置入口的注册项：`page` 画表单，`summary` 不画（行的描述来自包自己的 locale）。
 type RowConfigEntryProps = PropsRuntime<"plugins.row.config"> & PropsRenderFactories;
 
-/**
- * 装上本包：字典、Factory（字段槽的声明者）与按行自动注册。
- * @param ctx - 浏览器插件上下文。
- */
+// 装上本包：字典、Factory（字段槽的声明者）与按行自动注册。
 export function apply(ctx: Context): void {
   ctx.effect(() => ctx.locale.register(NS, { zh, en }), "ui-schema-form: dictionaries");
   // 提示面（dict 的候选键）：同一次 apply 里提供，业务插件注册读数，本包的行投影读它。

package/src/client/schema-form/labels.ts

@@ -1,16 +1,14 @@
-/**
- * 字段文案：标签兜底与说明解析。
- *
- * 标签没有 schema 声明可用（schemastery 的 meta 没有 title/label），所以先是字段名兜底（驼峰/下划线拆词），
- * 业务方经字段槽给 label/hint 时以槽为准；说明取 `description`（可本地化）与 `comment`。
- */
+// 字段文案：标签兜底与说明解析。
+//
+// 标签没有 schema 声明可用（schemastery 的 meta 没有 title/label），所以先是字段名兜底（驼峰/下划线拆词），
+// 业务方经字段槽给 label/hint 时以槽为准；说明取 `description`（可本地化）与 `comment`。
 
 import type { FieldNode } from "./schema-node.ts";
 
-/** 把 schema 里的本地化文本解析成当前语言；由 locale 服务提供。 */
+// 把 schema 里的本地化文本解析成当前语言；由 locale 服务提供。
 export type ResolveText = (text: string | Readonly<Record<string, string>>) => string;
 
-/** 字段名兜底的可读标签：拆词并首字母大写，`0`/`1` 这类索引保持原样。 */
+// 字段名兜底的可读标签：拆词并首字母大写，`0`/`1` 这类索引保持原样。
 export function humanizeKey(key: string): string {
   if (key.length === 0) return "";
   if (/^\d+$/.test(key)) return key;
@@ -21,7 +19,7 @@ export function humanizeKey(key: string): string {
   return words.charAt(0).toUpperCase() + words.slice(1);
 }
 
-/** 字段的说明（`description` 本地化后 + `comment`），没有就是 undefined。 */
+// 字段的说明（`description` 本地化后 + `comment`），没有就是 undefined。
 export function fieldHint(node: FieldNode, resolveText: ResolveText): string | undefined {
   const parts: string[] = [];
   if (node.meta.description !== undefined) parts.push(resolveText(node.meta.description));

package/src/client/schema-form/lines.ts

@@ -1,9 +1,7 @@
-/**
- * 行模型：把字段树（`walkFields` 的结果）排成**编辑器的行**——结构行（`{` / `[` / `}` / `]`）、字段行、注释行、
- * 以及容器尾部的添加行。
- *
- * 渲染层因此只按行画，不必自己递归：行序 = 视觉顺序，行号连续。折叠在这里生效（折叠的容器只留开启行）。
- */
+// 行模型：把字段树（`walkFields` 的结果）排成**编辑器的行**——结构行（`{` / `[` / `}` / `]`）、字段行、注释行、
+// 以及容器尾部的添加行。
+//
+// 渲染层因此只按行画，不必自己递归：行序 = 视觉顺序，行号连续。折叠在这里生效（折叠的容器只留开启行）。
 
 import { fieldKey, type AddableProperty, type SchemaFormState } from "./controller.ts";
 import type { DraftFieldState } from "./draft.ts";
@@ -20,29 +18,29 @@ import {
   type WalkedField,
 } from "./schema-node.ts";
 
-/** 一个容器的闭合行后面能加什么。 */
+// 一个容器的闭合行后面能加什么。
 export type AddLineSpec =
-  /** 数组：追加一个空项。 */
+  // 数组：追加一个空项。
   | { kind: "item" }
-  /** 字典：敲键名，或从候选键里选（业务注册的读数）。 */
+  // 字典：敲键名，或从候选键里选（业务注册的读数）。
   | { kind: "key"; options: readonly AddableProperty[] }
-  /** 对象：从「schema 声明了、值里还没有」的字段里选（没有候选项时不给输入框）。 */
+  // 对象：从「schema 声明了、值里还没有」的字段里选（没有候选项时不给输入框）。
   | { kind: "prop"; options: readonly AddableProperty[] };
 
-/** 一行上的变体切换控件。 */
+// 一行上的变体切换控件。
 export interface VariantControl {
-  /** 可以切到哪几支；顺序即声明顺序。 */
+  // 可以切到哪几支；顺序即声明顺序。
   choices: readonly VariantChoice[];
-  /** 当前落在第几支。 */
+  // 当前落在第几支。
   selected: number;
 }
 
-/** 容器类型：结构行用 `{` 还是 `[`。 */
+// 容器类型：结构行用 `{` 还是 `[`。
 export type ContainerShape = "object" | "array";
 
-/** 一行。 */
+// 一行。
 export type EditorLine =
-  /** 容器的开启行：`key: {` 或 `[`。 */
+  // 容器的开启行：`key: {` 或 `[`。
   | {
       kind: "open";
       path: readonly string[];
@@ -51,21 +49,21 @@ export type EditorLine =
       depth: number;
       collapsed: boolean;
       member: WalkedField["member"];
-      /** 这一层是 union 时，可以在哪几支之间切（写哪个值）。 */
+      // 这一层是 union 时，可以在哪几支之间切（写哪个值）。
       variants: VariantControl | undefined;
     }
-  /** 容器的关闭行：`}` / `]`（添加行挂在它后面同一行）。 */
+  // 容器的关闭行：`}` / `]`（添加行挂在它后面同一行）。
   | {
       kind: "close";
       path: readonly string[];
       node: FieldNode;
       shape: ContainerShape;
       depth: number;
-      /** 这一层能加什么；`undefined` 表示加不了（对象的声明字段都配齐了）。 */
+      // 这一层能加什么；`undefined` 表示加不了（对象的声明字段都配齐了）。
       add: AddLineSpec | undefined;
       member: WalkedField["member"];
     }
-  /** 字段行：`key: value`。 */
+  // 字段行：`key: value`。
   | {
       kind: "field";
       path: readonly string[];
@@ -73,33 +71,24 @@ export type EditorLine =
       depth: number;
       field: DraftFieldState;
       member: WalkedField["member"];
-      /** 这个字段是 union 时，可以在哪几支之间切。 */
+      // 这个字段是 union 时，可以在哪几支之间切。
       variants: VariantControl | undefined;
-      /**
-       * 变体触发**代替这一行的值**：判别式 union 的标签行就是这样——`type: "sqlite" ▾` 里的值就是那个触发，
-       * 不再另画一份值。
-       */
+      // 变体触发**代替这一行的值**：判别式 union 的标签行就是这样——`type: "sqlite" ▾` 里的值就是那个触发，
+      // 不再另画一份值。
       variantsStandIn: boolean;
     }
-  /** 注释行：schema 的说明与业务给的文案，画在字段行上方；这一行有问题时它装的是那条消息。 */
+  // 注释行：schema 的说明与业务给的文案，画在字段行上方；这一行有问题时它装的是那条消息。
   | {
       kind: "comment";
       path: readonly string[];
       depth: number;
       text: string;
-      /** 这一行有校验消息（草稿解析失败或整段校验落下来）：画成错误，而不是普通说明。 */
+      // 这一行有校验消息（草稿解析失败或整段校验落下来）：画成错误，而不是普通说明。
       invalid: boolean;
     };
 
-/**
- * 容器的形状：对象类用 `{}`，序列类用 `[]`。
- *
- * union 没有自己的形状——它跟着**当前选中那一支**走（`access` 是数组就在页面上画 `[`），这也是
- * `access: string | string[]` 这类字段以前被画成对象容器的原因。
- * @param node - 字段节点。
- * @param value - 这一层的值（选支判据）。
- * @returns 形状；叶子节点是 `undefined`。
- */
+// 容器的形状：对象类用 `{}`，序列类用 `[]`；union 没有自己的形状——它跟着**当前选中那一支**走
+// （`access: string | string[]` 选到数组就画 `[`）。
 export function containerShape(node: FieldNode, value?: unknown): ContainerShape | undefined {
   switch (variantOf(node, value).type) {
     case "object":
@@ -114,13 +103,13 @@ export function containerShape(node: FieldNode, value?: unknown): ContainerShape
   }
 }
 
-/** 折叠状态与可见性：记「用户切换过的路径」，开合 = 切换过就反转 schema 的默认值。 */
+// 折叠状态与可见性：记「用户切换过的路径」，开合 = 切换过就反转 schema 的默认值。
 export interface FoldState {
   collapsed(path: readonly string[]): boolean;
   toggle(path: readonly string[]): void;
 }
 
-/** 渲染顺序里可见的字段：折叠的容器把整棵子树滤掉，只留它自己的开启行。 */
+// 渲染顺序里可见的字段：折叠的容器把整棵子树滤掉，只留它自己的开启行。
 export function visibleFields(state: SchemaFormState, fold: FoldState): readonly WalkedField[] {
   const containers = new Set(
     state.walked
@@ -136,12 +125,12 @@ export function visibleFields(state: SchemaFormState, fold: FoldState): readonly
   });
 }
 
-/** 这一层的当前值：与字段行显示的是同一份读数（草稿优先）。 */
+// 这一层的当前值：与字段行显示的是同一份读数（草稿优先）。
 function valueAt(state: SchemaFormState, path: readonly string[]): unknown {
   return state.fields.get(fieldKey(path))?.value;
 }
 
-/** 这一层能加什么：数组追加空项，字典敲键名（可来自候选），对象从还没配的声明字段里选。 */
+// 这一层能加什么：数组追加空项，字典敲键名（可来自候选），对象从还没配的声明字段里选。
 function addOf(
   node: FieldNode,
   shape: ContainerShape,
@@ -152,7 +141,7 @@ function addOf(
   return options.length === 0 ? undefined : { kind: "prop", options };
 }
 
-/** 一个节点上的变体切换控件：不是 union、或只有一支、或成员全是常量（字面量集合是选择器）时没有。 */
+// 一个节点上的变体切换控件：不是 union、或只有一支、或成员全是常量（字面量集合是选择器）时没有。
 function variantsOf(node: FieldNode, value: unknown): VariantControl | undefined {
   const union = unionOf(node);
   if (union === undefined || union.choices !== undefined || union.variants.length < 2)
@@ -163,14 +152,7 @@ function variantsOf(node: FieldNode, value: unknown): VariantControl | undefined
   };
 }
 
-/**
- * 排成行序列。
- * @param state - 页面读数。
- * @param fold - 折叠状态。
- * @param resolveText - `description` 的本地化。
- * @param t - 本包字典。
- * @returns 行序列（行号即下标）。
- */
+// 排成行序列（行号即下标）。
 export function editorLines(
   state: SchemaFormState,
   fold: FoldState,
@@ -271,10 +253,8 @@ export function editorLines(
   return moveVariantControlToTag(lines);
 }
 
-/**
- * 判别式 union 的切换控件挪到**标签字段那一行**上：`session-rdb` 的页面上用户改的就是 `type`，把它放在容器
- * 行上等于让人在两处看同一件事。没有标签字段（`access` 这种按值形状选的）就留在 union 自己那一行。
- */
+// 判别式 union 的切换控件挪到**标签字段那一行**上：`session-rdb` 的页面上用户改的就是 `type`，把它放在容器
+// 行上等于让人在两处看同一件事。没有标签字段（`access` 这种按值形状选的）就留在 union 自己那一行。
 function moveVariantControlToTag(lines: EditorLine[]): EditorLine[] {
   for (const line of lines) {
     if (line.kind === "comment" || line.kind === "close") continue;
@@ -297,12 +277,8 @@ function moveVariantControlToTag(lines: EditorLine[]): EditorLine[] {
   return lines;
 }
 
-/**
- * 一行的注释：业务给的文案（字段槽的 label/hint）优先，其次 schema 的说明。
- *
- * 这一行有问题时**注释位让给那条消息**（参考实现也是把错误画在行尾那一段的位置上）——说明换成"哪里不对"，
- * 错误因此不必挤在值后面。
- */
+// 一行的注释：业务经提示面给的文案优先，schema 的 `description` / `comment` 兜底；这一行有问题时
+// **注释位让给那条消息**（错误因此不必挤在值后面）。
 function commentFor(
   state: SchemaFormState,
   item: WalkedField,
@@ -327,7 +303,7 @@ function commentFor(
   return parts.length === 0 ? undefined : { text: parts.join(" · "), invalid: false };
 }
 
-/** `path` 是不是 `prefix` 的后代（含自身）。 */
+// `path` 是不是 `prefix` 的后代（含自身）。
 function isPrefix(prefix: readonly string[], path: readonly string[]): boolean {
   if (prefix.length > path.length) return false;
   return prefix.every((segment, index) => path[index] === segment);

package/src/client/schema-form/locales.ts

@@ -1,10 +1,8 @@
-/**
- * 本包字典（命名空间 `settings.schema-form`）：表单壳、字段控件与只读呈现的文案。
- *
- * 字段自身的人话标签不在这里（那是业务方经字段槽或 schema `description` 给的），这里只放**机制**文案。
- */
+// 本包字典（命名空间 `settings.schema-form`）：表单壳、字段控件与只读呈现的文案。
+//
+// 字段自身的人话标签不在这里（那是业务方经字段槽或 schema `description` 给的），这里只放**机制**文案。
 
-/** 中文文案（部署语言偏好是 zh）。 */
+// 中文文案（部署语言偏好是 zh）。
 export const zh = {
   unavailable: "该插件当前未加载，暂时无法配置。",
   readOnly: "本部署的设置为只读。",
@@ -64,7 +62,7 @@ export const zh = {
   missingItem: "每一项都需要一个 {key}",
 } as const;
 
-/** 英文文案。 */
+// 英文文案。
 export const en = {
   unavailable: "This plugin is not loaded, so it cannot be configured right now.",
   readOnly: "This deployment stores settings read-only.",
@@ -124,5 +122,5 @@ export const en = {
   missingItem: "Every item needs a {key}",
 } as const;
 
-/** 本命名空间的字典键。 */
+// 本命名空间的字典键。
 export type SchemaFormLocaleKey = keyof typeof zh;