@morlay/dsh-client-ui-primitives 0.0.2-alpha.8 → 0.0.2-alpha.9

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

@@ -0,0 +1,334 @@
+/**
+ * 行模型：把字段树（`walkFields` 的结果）排成**编辑器的行**——结构行（`{` / `[` / `}` / `]`）、字段行、注释行、
+ * 以及容器尾部的添加行。
+ *
+ * 渲染层因此只按行画，不必自己递归：行序 = 视觉顺序，行号连续。折叠在这里生效（折叠的容器只留开启行）。
+ */
+
+import { fieldKey, type AddableProperty, type SchemaFormState } from "./controller.ts";
+import type { DraftFieldState } from "./draft.ts";
+import type { ResolveText } from "./labels.ts";
+import { fieldHint } from "./labels.ts";
+import type { SchemaFormTranslate } from "./slot-contract.ts";
+import {
+  unionOf,
+  unwrapLazy,
+  variantChoices,
+  variantOf,
+  type FieldNode,
+  type VariantChoice,
+  type WalkedField,
+} from "./schema-node.ts";
+
+/** 一个容器的闭合行后面能加什么。 */
+export type AddLineSpec =
+  /** 数组：追加一个空项。 */
+  | { kind: "item" }
+  /** 字典：敲键名，或从候选键里选（业务注册的读数）。 */
+  | { kind: "key"; options: readonly AddableProperty[] }
+  /** 对象：从「schema 声明了、值里还没有」的字段里选（没有候选项时不给输入框）。 */
+  | { kind: "prop"; options: readonly AddableProperty[] };
+
+/** 一行上的变体切换控件。 */
+export interface VariantControl {
+  /** 可以切到哪几支；顺序即声明顺序。 */
+  choices: readonly VariantChoice[];
+  /** 当前落在第几支。 */
+  selected: number;
+}
+
+/** 容器类型：结构行用 `{` 还是 `[`。 */
+export type ContainerShape = "object" | "array";
+
+/** 一行。 */
+export type EditorLine =
+  /** 容器的开启行：`key: {` 或 `[`。 */
+  | {
+      kind: "open";
+      path: readonly string[];
+      node: FieldNode;
+      shape: ContainerShape;
+      depth: number;
+      collapsed: boolean;
+      member: WalkedField["member"];
+      /** 这一层是 union 时，可以在哪几支之间切（写哪个值）。 */
+      variants: VariantControl | undefined;
+    }
+  /** 容器的关闭行：`}` / `]`（添加行挂在它后面同一行）。 */
+  | {
+      kind: "close";
+      path: readonly string[];
+      node: FieldNode;
+      shape: ContainerShape;
+      depth: number;
+      /** 这一层能加什么；`undefined` 表示加不了（对象的声明字段都配齐了）。 */
+      add: AddLineSpec | undefined;
+      member: WalkedField["member"];
+    }
+  /** 字段行：`key: value`。 */
+  | {
+      kind: "field";
+      path: readonly string[];
+      node: FieldNode;
+      depth: number;
+      field: DraftFieldState;
+      member: WalkedField["member"];
+      /** 这个字段是 union 时，可以在哪几支之间切。 */
+      variants: VariantControl | undefined;
+      /**
+       * 变体触发**代替这一行的值**：判别式 union 的标签行就是这样——`type: "sqlite" ▾` 里的值就是那个触发，
+       * 不再另画一份值。
+       */
+      variantsStandIn: boolean;
+    }
+  /** 注释行：schema 的说明与业务给的文案，画在字段行上方；这一行有问题时它装的是那条消息。 */
+  | {
+      kind: "comment";
+      path: readonly string[];
+      depth: number;
+      text: string;
+      /** 这一行有校验消息（草稿解析失败或整段校验落下来）：画成错误，而不是普通说明。 */
+      invalid: boolean;
+    };
+
+/**
+ * 容器的形状：对象类用 `{}`，序列类用 `[]`。
+ *
+ * union 没有自己的形状——它跟着**当前选中那一支**走（`access` 是数组就在页面上画 `[`），这也是
+ * `access: string | string[]` 这类字段以前被画成对象容器的原因。
+ * @param node - 字段节点。
+ * @param value - 这一层的值（选支判据）。
+ * @returns 形状；叶子节点是 `undefined`。
+ */
+export function containerShape(node: FieldNode, value?: unknown): ContainerShape | undefined {
+  switch (variantOf(node, value).type) {
+    case "object":
+    case "dict":
+    case "intersect":
+      return "object";
+    case "array":
+    case "tuple":
+      return "array";
+    default:
+      return undefined;
+  }
+}
+
+/** 折叠状态与可见性：记「用户切换过的路径」，开合 = 切换过就反转 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
+      .filter((item) => containerShape(item.node, valueAt(state, item.path)) !== undefined)
+      .map((item) => fieldKey(item.path)),
+  );
+  return state.walked.filter((item) => {
+    for (let depth = 1; depth < item.path.length; depth++) {
+      const ancestor = item.path.slice(0, depth);
+      if (containers.has(fieldKey(ancestor)) && fold.collapsed(ancestor)) return false;
+    }
+    return true;
+  });
+}
+
+/** 这一层的当前值：与字段行显示的是同一份读数（草稿优先）。 */
+function valueAt(state: SchemaFormState, path: readonly string[]): unknown {
+  return state.fields.get(fieldKey(path))?.value;
+}
+
+/** 这一层能加什么：数组追加空项，字典敲键名（可来自候选），对象从还没配的声明字段里选。 */
+function addOf(
+  node: FieldNode,
+  shape: ContainerShape,
+  options: readonly AddableProperty[],
+): AddLineSpec | undefined {
+  if (shape === "array") return { kind: "item" };
+  if (unwrapLazy(node)?.type === "dict") return { kind: "key", options };
+  return options.length === 0 ? undefined : { kind: "prop", options };
+}
+
+/** 一个节点上的变体切换控件：不是 union、或只有一支、或成员全是常量（字面量集合是选择器）时没有。 */
+function variantsOf(node: FieldNode, value: unknown): VariantControl | undefined {
+  const union = unionOf(node);
+  if (union === undefined || union.choices !== undefined || union.variants.length < 2)
+    return undefined;
+  return {
+    choices: variantChoices(union),
+    selected: union.variants.indexOf(variantOf(union, value)),
+  };
+}
+
+/**
+ * 排成行序列。
+ * @param state - 页面读数。
+ * @param fold - 折叠状态。
+ * @param resolveText - `description` 的本地化。
+ * @param t - 本包字典。
+ * @returns 行序列（行号即下标）。
+ */
+export function editorLines(
+  state: SchemaFormState,
+  fold: FoldState,
+  resolveText: ResolveText,
+  t: SchemaFormTranslate,
+): EditorLine[] {
+  const lines: EditorLine[] = [];
+  const open: {
+    path: readonly string[];
+    node: FieldNode;
+    shape: ContainerShape;
+    depth: number;
+    add: AddLineSpec | undefined;
+    member: WalkedField["member"];
+  }[] = [];
+  const closeOpenUntil = (path: readonly string[]): void => {
+    while (open.length > 0) {
+      const top = open[open.length - 1]!;
+      if (isPrefix(top.path, path)) return;
+      open.pop();
+      lines.push({
+        kind: "close",
+        path: top.path,
+        node: top.node,
+        shape: top.shape,
+        depth: top.depth,
+        add: top.add,
+        member: top.member,
+      });
+    }
+  };
+  for (const item of visibleFields(state, fold)) {
+    closeOpenUntil(item.path);
+    const node = unwrapLazy(item.node) ?? item.node;
+    const value = valueAt(state, item.path);
+    // 层级从根算起：根的 `{` 是 0，第一层字段就是 1——第一层也缩进一格。
+    const depth = item.path.length;
+    const comment = commentFor(state, item, resolveText, t);
+    if (comment !== undefined) {
+      lines.push({
+        kind: "comment",
+        path: item.path,
+        depth,
+        text: comment.text,
+        invalid: comment.invalid,
+      });
+    }
+    const variants = variantsOf(node, value);
+    const shape = containerShape(node, value);
+    if (shape !== undefined) {
+      const collapsed = fold.collapsed(item.path);
+      const add = addOf(node, shape, state.addable.get(fieldKey(item.path)) ?? []);
+      lines.push({
+        kind: "open",
+        path: item.path,
+        node,
+        shape,
+        depth,
+        collapsed,
+        member: item.member,
+        variants,
+      });
+      // 折叠的容器用 `{…}` 收在一行里：它不再有子行，也没有自己的关闭行。
+      if (!collapsed) {
+        open.push({ path: item.path, node, shape, depth, add, member: item.member });
+      }
+      continue;
+    }
+    lines.push({
+      kind: "field",
+      path: item.path,
+      node,
+      depth,
+      field: state.fields.get(fieldKey(item.path)) ?? {
+        value: undefined,
+        text: undefined,
+        invalid: undefined,
+        overridden: false,
+        staged: false,
+      },
+      member: item.member,
+      variants,
+      variantsStandIn: false,
+    });
+  }
+  while (open.length > 0) {
+    const top = open.pop()!;
+    lines.push({
+      kind: "close",
+      path: top.path,
+      node: top.node,
+      shape: top.shape,
+      depth: top.depth,
+      add: top.add,
+      member: top.member,
+    });
+  }
+  return moveVariantControlToTag(lines);
+}
+
+/**
+ * 判别式 union 的切换控件挪到**标签字段那一行**上：`session-rdb` 的页面上用户改的就是 `type`，把它放在容器
+ * 行上等于让人在两处看同一件事。没有标签字段（`access` 这种按值形状选的）就留在 union 自己那一行。
+ */
+function moveVariantControlToTag(lines: EditorLine[]): EditorLine[] {
+  for (const line of lines) {
+    if (line.kind === "comment" || line.kind === "close") continue;
+    if (line.variants === undefined) continue;
+    const tagKey = unionOf(line.node)?.tagKey;
+    if (tagKey === undefined) continue;
+    const tagPath = [...line.path, tagKey];
+    const tagLine = lines.find(
+      (candidate) =>
+        candidate.kind === "field" &&
+        candidate.path.length === tagPath.length &&
+        candidate.path.every((segment, index) => segment === tagPath[index]),
+    );
+    if (tagLine === undefined || tagLine.kind !== "field") continue;
+    // 标签行：值位置直接画那个切换控件（值是 const，本来就改不了）。
+    tagLine.variants = line.variants;
+    tagLine.variantsStandIn = true;
+    line.variants = undefined;
+  }
+  return lines;
+}
+
+/**
+ * 一行的注释：业务给的文案（字段槽的 label/hint）优先，其次 schema 的说明。
+ *
+ * 这一行有问题时**注释位让给那条消息**（参考实现也是把错误画在行尾那一段的位置上）——说明换成"哪里不对"，
+ * 错误因此不必挤在值后面。
+ */
+function commentFor(
+  state: SchemaFormState,
+  item: WalkedField,
+  resolveText: ResolveText,
+  t: SchemaFormTranslate,
+): { text: string; invalid: boolean } | undefined {
+  const key = fieldKey(item.path);
+  const failure = state.fields.get(key)?.invalid ?? state.invalidAt.get(key);
+  if (failure !== undefined) return { text: failure, invalid: true };
+  const node = unwrapLazy(item.node) ?? item.node;
+  const parts: string[] = [];
+  // 注释放"这是什么"（说明）与只读、徽标这类一眼看不出的状态，不放"必填"这类结构信息——那是 schema 的常规。
+  // 业务经提示面给的文案优先，schema 的 `description` / `comment` 兜底。
+  const text = state.texts.get(fieldKey(item.path));
+  const hint =
+    [text?.label, text?.hint].filter((part) => part !== undefined && part !== "").join("：") ||
+    fieldHint(node, resolveText);
+  if (hint !== undefined && hint !== "") parts.push(hint);
+  // 只读的字段（装配事实这类）要说清楚为什么改不了，否则看起来只是"点不开"。
+  if (node.meta.disabled) parts.push(t("readOnlyField"));
+  if (node.meta.badges.length > 0) parts.push(node.meta.badges.join(" / "));
+  return parts.length === 0 ? undefined : { text: parts.join(" · "), invalid: false };
+}
+
+/** `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

@@ -0,0 +1,128 @@
+/**
+ * 本包字典（命名空间 `settings.schema-form`）：表单壳、字段控件与只读呈现的文案。
+ *
+ * 字段自身的人话标签不在这里（那是业务方经字段槽或 schema `description` 给的），这里只放**机制**文案。
+ */
+
+/** 中文文案（部署语言偏好是 zh）。 */
+export const zh = {
+  unavailable: "该插件当前未加载，暂时无法配置。",
+  readOnly: "本部署的设置为只读。",
+  save: "保存",
+  confirmEdit: "确认",
+  cancelEdit: "取消",
+  saving: "保存中…",
+  saveFailed: "本部署没有接受这些值，已保留供你修改。",
+  notSaved: "没有保存：{message}",
+  noSchema: "这一行没有可自动生成的配置项。",
+
+  reset: "恢复默认",
+  revert: "撤回",
+  invalid: "这个值不被接受。",
+  invalidNumber: "需要一个数字。",
+  invalidInteger: "需要一个整数。",
+  invalidJson: "需要一段合法的 JSON。",
+  invalidBoolean: "需要 true 或 false。",
+  invalidConst: "这个字段只接受固定值。",
+  invalidPattern: "要匹配 {pattern}。",
+  invalidRange: "要在 {min} 与 {max} 之间。",
+  invalidMin: "不能小于 {min}。",
+  invalidMax: "不能大于 {max}。",
+  invalidChoice: "只能是 {choices} 之一。",
+  unknownProperty: "这一层没有这个字段：从上面的候选里选，或换个键名。",
+  empty: "（空）",
+
+  toggleGroup: "展开 / 收起这一层",
+  switchVariant: "切换这一层的形状或分支",
+  copyValue: "复制值",
+  copied: "已复制",
+  addProperty: "添加属性",
+  addItemPaste: "添加数组项（可粘贴 JSON 字符串）",
+  addItem: "添加一项",
+  removeItem: "移除",
+  addKey: "添加键（可粘贴 JSON 字符串）",
+  keyName: "键名",
+  noKeys: "还没有键。",
+  noItems: "还没有项。",
+
+  deprecated: "已废弃",
+  experimental: "试验中",
+  secretSet: "已配置",
+  secretUnset: "未配置",
+  secretHint: "留空即保留已存的值。",
+
+  constValue: "固定值",
+  notEditable: "这一项由插件在运行时提供，不能在页面上编辑。",
+  recursive: "递归结构：展开到这一层为止。",
+  fixedLength: "固定长度",
+  bitsetHint: "可多选。",
+  unconfigured: "未配置",
+  readOnlyField: "只读",
+  noDescription: "（无说明）",
+  required: "必填",
+  duplicateItem: "重复的 {key}：{value}",
+  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.",
+  save: "Save",
+  confirmEdit: "Confirm",
+  cancelEdit: "Cancel",
+  saving: "Saving…",
+  saveFailed: "This deployment did not accept these values; they are kept for you to fix.",
+  notSaved: "Not saved: {message}",
+  noSchema: "This row has no configuration to generate.",
+
+  reset: "Reset",
+  revert: "Revert",
+  invalid: "This value is not accepted.",
+  invalidNumber: "Enter a number.",
+  invalidInteger: "Enter a whole number.",
+  invalidJson: "Enter valid JSON.",
+  invalidBoolean: "Enter true or false.",
+  invalidConst: "This field only accepts its fixed value.",
+  invalidPattern: "Must match {pattern}.",
+  invalidRange: "Must be between {min} and {max}.",
+  invalidMin: "Must not be less than {min}.",
+  invalidMax: "Must not be greater than {max}.",
+  invalidChoice: "Must be one of {choices}.",
+  unknownProperty: "No such field at this level: pick one of the candidates above.",
+  empty: "(empty)",
+
+  toggleGroup: "Expand or collapse this level",
+  switchVariant: "Switch this level's shape or branch",
+  copyValue: "Copy value",
+  copied: "Copied",
+  addProperty: "Add property",
+  addItemPaste: "Add item (a JSON string can be pasted)",
+  addItem: "Add item",
+  removeItem: "Remove",
+  addKey: "Add key (a JSON string can be pasted)",
+  keyName: "Key",
+  noKeys: "No keys yet.",
+  noItems: "No items yet.",
+
+  deprecated: "deprecated",
+  experimental: "experimental",
+  secretSet: "configured",
+  secretUnset: "not set",
+  secretHint: "Leave blank to keep the stored value.",
+
+  constValue: "fixed",
+  notEditable: "This entry is provided by the plugin at runtime and cannot be edited here.",
+  recursive: "Recursive structure: expanded down to this level.",
+  fixedLength: "fixed length",
+  bitsetHint: "Multiple choices.",
+  unconfigured: "not configured",
+  readOnlyField: "read-only",
+  noDescription: "(no description)",
+  required: "required",
+  duplicateItem: "Duplicate {key}: {value}",
+  missingItem: "Every item needs a {key}",
+} as const;
+
+/** 本命名空间的字典键。 */
+export type SchemaFormLocaleKey = keyof typeof zh;

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

@@ -0,0 +1,153 @@
+/**
+ * 自动注册面：把 describe 出来的命名空间与 bundle 的行清单配对，为每个能渲染的行注册本行的配置入口。
+ *
+ * 注册用 `<bundle 包名>#<行 id>`（页面按同一个 key 打开这一行的配置页）与兜底 priority：手写卡片用默认
+ * priority 0 注册，按 slots 的 cell winner 规则自然遮住这里的自动项，与加载顺序无关。
+ */
+
+import type { BundleInfo, SettingsNamespaceView } from "@deepseek-ai/dsh-api-remotes/client";
+import type { SettingsDescribeFace } from "@deepseek-ai/dsh-client-ui-settings/client";
+
+/** 一个该自动长出配置页的行。 */
+export interface RowRegistrationPlan {
+  /** `plugins.row.config` 的 key：`<bundle 包名>#<行 id>`。 */
+  key: string;
+  /** settings 命名空间（行 id）。 */
+  ns: string;
+}
+
+/**
+ * 配对命名空间与 bundle 行清单。
+ * @param namespaces - host 发来的命名空间视图。
+ * @param bundles - host 的 bundle 清单（含各 bundle 声明的行 id）。
+ * @returns 该自动注册的行，按命名空间视图的顺序。
+ */
+export function rowRegistrations(
+  namespaces: readonly SettingsNamespaceView[],
+  bundles: readonly BundleInfo[],
+): RowRegistrationPlan[] {
+  const owners = new Map<string, string>();
+  for (const bundle of bundles) {
+    for (const row of bundle.rows) owners.set(row.rowId, bundle.name);
+  }
+  const plans: RowRegistrationPlan[] = [];
+  for (const view of namespaces) {
+    if (view.autoGenerate !== true) continue;
+    const owner = owners.get(view.ns);
+    if (owner === undefined) continue;
+    plans.push({ key: `${owner}#${view.ns}`, ns: view.ns });
+  }
+  return plans;
+}
+
+/** 注册器要的外部面。 */
+export interface RowRegistrationDeps {
+  /** 槽位注册：返回注销函数。 */
+  slots: {
+    register(
+      options: {
+        name: "plugins.row.config";
+        key: string;
+        priority: number;
+        locale: string;
+      },
+      component: unknown,
+    ): () => void;
+  };
+  /** describe 读面：命名空间清单与变更通知。 */
+  describe: SettingsDescribeFace;
+  /** 读 bundle 清单。 */
+  bundles(): Promise<readonly BundleInfo[]>;
+  /** 订阅 bundle 清单变化。 */
+  subscribeBundles(listener: () => void): () => void;
+  /**
+   * 一行的注册项组件；`undefined` 表示这一行渲染不了（schema rehydrate 不了或段根不是对象）。
+   * 每次调用返回同一个实例（控制器按命名空间缓存）。
+   */
+  entryFor(ns: string): { component: unknown } | undefined;
+  /** 槽项文案的命名空间。 */
+  locale: string;
+  /** 一行注销时释放它的控制器。 */
+  release(ns: string): void;
+}
+
+/** 自动项的兜底优先级：手写卡片（默认 0）遮住它。 */
+const FALLBACK_PRIORITY = 100;
+
+/**
+ * 自动注册的差分器：按 describe 与 bundle 清单把「该有的行」与「已在的行」对齐。
+ */
+export class RowRegistration {
+  readonly #deps: RowRegistrationDeps;
+  readonly #live = new Map<string, () => void>();
+  #pending: Promise<void> | undefined;
+  #disposed = false;
+
+  /**
+   * @param deps - 槽位、清单读面与每行的槽项工厂。
+   */
+  constructor(deps: RowRegistrationDeps) {
+    this.#deps = deps;
+  }
+
+  /**
+   * 对齐一次：新增该有的行，注销不该有的行。
+   *
+   * 并发调用折叠成一次（bundle 清单只读一趟），后到的调用等同一趟结束。
+   * @returns 对齐完成。
+   */
+  sync(): Promise<void> {
+    if (this.#disposed) return Promise.resolve();
+    this.#pending ??= this.#run().finally(() => {
+      this.#pending = undefined;
+    });
+    return this.#pending;
+  }
+
+  /** 收掉自己：注销还活着的全部注册并释放它们的控制器。 */
+  dispose(): void {
+    this.#disposed = true;
+    this.#release();
+  }
+
+  async #run(): Promise<void> {
+    const bundles = await this.#deps.bundles();
+    if (this.#disposed) return;
+    const namespaces = this.#deps.describe.getSnapshot().view?.namespaces ?? [];
+    const wanted = new Map<string, RowRegistrationPlan>();
+    for (const plan of rowRegistrations(namespaces, bundles)) {
+      if (this.#deps.entryFor(plan.ns) === undefined) continue;
+      wanted.set(plan.ns, plan);
+    }
+    for (const [ns, dispose] of this.#live) {
+      if (wanted.has(ns)) continue;
+      dispose();
+      this.#live.delete(ns);
+      this.#deps.release(ns);
+    }
+    for (const [ns, plan] of wanted) {
+      if (this.#live.has(ns)) continue;
+      const entry = this.#deps.entryFor(ns);
+      if (entry === undefined) continue;
+      const dispose = this.#deps.slots.register(
+        {
+          name: "plugins.row.config",
+          key: plan.key,
+          priority: FALLBACK_PRIORITY,
+          locale: this.#deps.locale,
+        },
+        entry.component,
+      );
+      this.#live.set(ns, dispose);
+    }
+  }
+
+  /** 注销全部并释放控制器。 */
+  #release(): void {
+    for (const [ns, dispose] of this.#live) {
+      dispose();
+      this.#live.delete(ns);
+      this.#deps.release(ns);
+    }
+  }
+}