@77-zhike/app-sdk 0.2.0-d7b1.10

package/src/development-workspace.js

@@ -0,0 +1,154 @@
+import { randomUUID } from "node:crypto";
+import { mkdir, readFile, rename, writeFile } from "node:fs/promises";
+import { resolve } from "node:path";
+import { createInterface } from "node:readline/promises";
+
+import { ZhikeCliError } from "./errors.js";
+
+export const DEVELOPMENT_WORKSPACE_PATH = ".zhike/development.json";
+
+export function parseDevelopmentWorkspaceState(value) {
+  if (
+    !value ||
+    typeof value !== "object" ||
+    Array.isArray(value) ||
+    Object.keys(value).sort().join(",") !== "currentWorkspaceId,schemaVersion" ||
+    value.schemaVersion !== 1 ||
+    !isStableId(value.currentWorkspaceId)
+  ) {
+    throw new ZhikeCliError(
+      "zhike_development_workspace_invalid",
+      `${DEVELOPMENT_WORKSPACE_PATH} 不是受支持的Development Workspace状态`,
+    );
+  }
+  return Object.freeze({ ...value });
+}
+
+export async function readDevelopmentWorkspace(projectDirectory) {
+  let content;
+  try {
+    content = await readFile(resolve(projectDirectory, DEVELOPMENT_WORKSPACE_PATH), "utf8");
+  } catch (error) {
+    if (error?.code === "ENOENT") return null;
+    throw new ZhikeCliError(
+      "zhike_development_workspace_read_failed",
+      "无法读取当前Development Workspace",
+      { cause: error },
+    );
+  }
+  try {
+    return parseDevelopmentWorkspaceState(JSON.parse(content));
+  } catch (error) {
+    if (error instanceof ZhikeCliError) throw error;
+    throw new ZhikeCliError(
+      "zhike_development_workspace_invalid",
+      `${DEVELOPMENT_WORKSPACE_PATH} 不是受支持的Development Workspace状态`,
+      { cause: error },
+    );
+  }
+}
+
+export async function writeDevelopmentWorkspace(projectDirectory, workspaceId) {
+  const state = parseDevelopmentWorkspaceState({
+    schemaVersion: 1,
+    currentWorkspaceId: workspaceId,
+  });
+  const directory = resolve(projectDirectory, ".zhike");
+  const target = resolve(projectDirectory, DEVELOPMENT_WORKSPACE_PATH);
+  const temporary = `${target}.${randomUUID()}.tmp`;
+  try {
+    await mkdir(directory, { recursive: true });
+    await writeFile(temporary, `${JSON.stringify(state, null, 2)}\n`, { flag: "wx" });
+    await rename(temporary, target);
+  } catch (error) {
+    throw new ZhikeCliError(
+      "zhike_development_workspace_write_failed",
+      "无法保存当前Development Workspace",
+      { cause: error },
+    );
+  }
+  return state;
+}
+
+export async function resolveDevelopmentWorkspace({
+  workspaces,
+  currentWorkspaceId = null,
+  requestedWorkspaceId = null,
+  selectWorkspace = promptForWorkspace,
+}) {
+  const normalized = normalizeWorkspaces(workspaces);
+  if (normalized.length === 0) {
+    throw new ZhikeCliError(
+      "zhike_manageable_workspace_missing",
+      "当前账号没有可用于App开发的Workspace管理权限",
+    );
+  }
+  if (requestedWorkspaceId) {
+    const requested = normalized.find(({ id }) => id === requestedWorkspaceId);
+    if (!requested) throw workspaceNotManageable();
+    return requested;
+  }
+  const current = normalized.find(({ id }) => id === currentWorkspaceId);
+  const selectedId = await selectWorkspace(normalized, current?.id ?? null);
+  const selected = normalized.find(({ id }) => id === selectedId);
+  if (!selected) throw workspaceNotManageable();
+  return selected;
+}
+
+export async function promptForWorkspace(workspaces, defaultWorkspaceId = null) {
+  const prompt = createInterface({ input: process.stdin, output: process.stdout });
+  try {
+    const defaultIndex = workspaces.findIndex(({ id }) => id === defaultWorkspaceId);
+    process.stdout.write("请选择当前Development Workspace：\n");
+    workspaces.forEach((workspace, index) => {
+      process.stdout.write(
+        `  ${index + 1}. ${workspace.name} (${workspace.id})${index === defaultIndex ? " [上次选择，默认]" : ""}\n`,
+      );
+    });
+    const answer = (await prompt.question(defaultIndex >= 0
+      ? `输入序号（回车选择 ${defaultIndex + 1}）：`
+      : "输入序号：")).trim();
+    if (!answer) return workspaces[defaultIndex]?.id ?? "";
+    const index = /^\d+$/.test(answer) ? Number(answer) - 1 : -1;
+    return workspaces[index]?.id ?? "";
+  } finally {
+    prompt.close();
+  }
+}
+
+function normalizeWorkspaces(value) {
+  if (!Array.isArray(value)) throw workspaceResponseInvalid();
+  const ids = new Set();
+  return value.map((workspace) => {
+    if (
+      !workspace ||
+      typeof workspace !== "object" ||
+      !isStableId(workspace.id) ||
+      typeof workspace.name !== "string" ||
+      !workspace.name.trim() ||
+      ids.has(workspace.id)
+    ) {
+      throw workspaceResponseInvalid();
+    }
+    ids.add(workspace.id);
+    return Object.freeze({ id: workspace.id, name: workspace.name.trim() });
+  });
+}
+
+function isStableId(value) {
+  return typeof value === "string" && /^[0-9A-HJKMNP-TV-Z]{26}$/.test(value);
+}
+
+function workspaceNotManageable() {
+  return new ZhikeCliError(
+    "zhike_workspace_not_manageable",
+    "选择的Workspace不存在或当前账号已无管理权限",
+  );
+}
+
+function workspaceResponseInvalid() {
+  return new ZhikeCliError(
+    "zhike_manageable_workspaces_invalid",
+    "Developer Server返回了不受支持的Workspace列表",
+  );
+}

package/src/errors.js

@@ -0,0 +1,20 @@
+export class ZhikeCliError extends Error {
+  constructor(code, message, options = {}) {
+    super(message, options);
+    this.name = "ZhikeCliError";
+    this.code = code;
+    this.exitCode = options.exitCode ?? 1;
+    this.retryable = options.retryable ?? false;
+  }
+}
+
+export function asSafeCliError(error) {
+  if (error instanceof ZhikeCliError) {
+    return error;
+  }
+  return new ZhikeCliError(
+    "zhike_unexpected_error",
+    "操作失败，请检查 Developer Server 状态后重试",
+    { cause: error, retryable: true },
+  );
+}

package/src/forms/array-contract.d.ts

@@ -0,0 +1,32 @@
+export const ARRAY_LIMITS: Readonly<{ arrays: number; rowFields: number; rows: number; instances: number; valueBytes: number; messageBytes: number }>;
+export function validFieldKey(key: unknown): boolean;
+export function formBytes(value: unknown): number;
+export function formObject(value: unknown, keys: string[]): void;
+export interface FieldAddress { field: string; array?: string; index?: number }
+export interface ArrayBinding { name: string; rowKey: string; formInstanceId: string; structureRevision: number }
+export type ArrayAction = { kind: 'append'; value: Record<string, unknown> } | { kind: 'insertBefore'; beforeKey: string; value: Record<string, unknown> } | { kind: 'remove'; rowKey: string } | { kind: 'move'; rowKey: string; before: string | null };
+export interface ArrayOperation { formId: string; formInstanceId: string; arrayName: string; baseStructureRevision: number; action: ArrayAction }
+export interface ArraySnapshot {
+  formId: string; name: string; formInstanceId: string; revision: number; structureRevision: number;
+  rows: { key: string; index: number; value: Record<string, unknown>; errors: Record<string, string>; validatingFields: Record<string, boolean> }[];
+  submitting: boolean; canAppend: boolean; error: string | null;
+}
+export type ErrorTree<T = string> = Record<string, T | (Record<string, T> | null)[]>;
+export function parseFieldPath(path: string): FieldAddress;
+export function fieldAtPath<F>(fields: Record<string, F>, path: string): F;
+export function valueAtPath(values: Record<string, unknown>, path: string): unknown;
+export function setPathValue(values: Record<string, unknown>, path: string, value: unknown): void;
+export function rulePath(path: string): string;
+export function leafPaths(fields: Record<string, unknown>, values: Record<string, unknown>): string[];
+export function rhfPath(path: string): string;
+export function publicPath(path: string): string;
+export function assertFieldValue(value: unknown, field: unknown, draft?: boolean): void;
+export function assertArrayCapacity(fields: Record<string, unknown>, values: Record<string, unknown>, draft?: boolean): void;
+export function normalizeFormValues<T extends Record<string, unknown>>(fields: Record<string, unknown>, raw: T): T;
+export function assertErrorTree(tree: unknown, fields: Record<string, unknown>, values?: Record<string, unknown>, boolean?: boolean, maxText?: number): void;
+export function assertArrayErrors(errors: unknown, fields: Record<string, unknown>, maxText?: number): void;
+export function flattenErrors<T = string>(tree?: ErrorTree<T>): Record<string, T>;
+export function nestErrors<T = string>(flat: Record<string, T>): ErrorTree<T>;
+export function assertArrayBinding(binding: unknown): ArrayBinding;
+export function assertArrayOperation(input: unknown): ArrayOperation;
+export function assertArraySnapshot(snapshot: unknown, formId: string, name: string, fields: Record<string, unknown>): ArraySnapshot;

package/src/forms/array-contract.js

@@ -0,0 +1,138 @@
+import { assertJsonValue } from '../ui/validation.js';
+import { isDateTime, isPlainDate, parseNumberDraft } from './values.js';
+import { assertRecordRef, recordObjectsForField } from './record-options.js';
+
+export const ARRAY_LIMITS = Object.freeze({ arrays: 3, rowFields: 12, rows: 50, instances: 300, valueBytes: 65536, messageBytes: 196608 });
+const fail = () => { throw new Error('runtime_form_array_invalid'); };
+export const validFieldKey = key => typeof key === 'string' && /^[a-zA-Z][a-zA-Z0-9_]{0,63}$/.test(key) && !['constructor', 'prototype'].includes(key);
+export const formBytes = value => new TextEncoder().encode(JSON.stringify(value)).length;
+export function formObject(value, keys) {
+  if (!value || typeof value !== 'object' || Array.isArray(value) || Object.keys(value).some(key => !keys.includes(key))) fail();
+}
+export function parseFieldPath(path) {
+  if (validFieldKey(path)) return { field: path };
+  const match = typeof path === 'string' && /^([a-zA-Z][a-zA-Z0-9_]{0,63})\[(0|[1-9][0-9]*)\]\.([a-zA-Z][a-zA-Z0-9_]{0,63})$/.exec(path);
+  if (!match || !validFieldKey(match[1]) || !validFieldKey(match[3]) || !Number.isSafeInteger(Number(match[2])) || Number(match[2]) >= ARRAY_LIMITS.rows) fail();
+  return { array: match[1], index: Number(match[2]), field: match[3] };
+}
+export function fieldAtPath(fields, path) {
+  const address = parseFieldPath(path);
+  const field = address.array ? fields[address.array]?.item?.fields[address.field] : fields[address.field];
+  if (!field || address.array && fields[address.array].type !== 'array') fail();
+  return field;
+}
+export function valueAtPath(values, path) {
+  const address = parseFieldPath(path);
+  return address.array ? values[address.array]?.[address.index]?.[address.field] : values[address.field];
+}
+export function setPathValue(values, path, value) {
+  const address = parseFieldPath(path);
+  if (address.array) values[address.array][address.index][address.field] = value;
+  else values[address.field] = value;
+}
+export function rulePath(path) {
+  const address = parseFieldPath(path);
+  return address.array ? `${address.array}[*].${address.field}` : address.field;
+}
+export function leafPaths(fields, values) {
+  return Object.entries(fields).flatMap(([name, field]) => field.type === 'array'
+    ? (values[name] ?? []).flatMap((_row, index) => Object.keys(field.item.fields).map(key => `${name}[${index}].${key}`)) : [name]);
+}
+export const rhfPath = path => path.replace(/\[(\d+)\]/g, '.$1');
+export const publicPath = path => path.replace(/\.(\d+)\./g, '[$1].');
+export function assertFieldValue(value, field, draft = false) {
+  if (field.type === 'array') {
+    if (!Array.isArray(value) || value.length > field.maxItems || Object.keys(value).length !== value.length) fail();
+    for (const row of value) {
+      formObject(row, Object.keys(field.item.fields));
+      if (Object.keys(row).length !== Object.keys(field.item.fields).length) fail();
+      for (const [key, leaf] of Object.entries(field.item.fields)) assertFieldValue(row[key], leaf, draft);
+    }
+  } else if (field.type === 'boolean') { if (typeof value !== 'boolean') fail(); }
+  else if (field.type === 'number') { if (value !== null && !(draft && typeof value === 'string') && (typeof value !== 'number' || !Number.isFinite(value))) fail(); }
+  else if (field.type === 'record') { if (value !== null) assertRecordRef(value, recordObjectsForField(field)); }
+  else if (field.type === 'plainDate' || field.type === 'dateTime') { if (value !== null && !(draft && typeof value === 'string') && !(field.type === 'plainDate' ? isPlainDate(value) : isDateTime(value))) fail(); }
+  else if (typeof value !== 'string' || value.length > 10000) fail();
+}
+export function assertArrayCapacity(fields, values, draft = false) {
+  if (!Object.values(fields).some(field => field.type === 'array')) return;
+  formObject(values, Object.keys(fields));
+  if (Object.keys(fields).length !== Object.keys(values).length) fail();
+  for (const [name, field] of Object.entries(fields)) assertFieldValue(values[name], field, draft);
+  if (leafPaths(fields, values).length > ARRAY_LIMITS.instances || formBytes(values) > ARRAY_LIMITS.valueBytes) throw new Error('runtime_form_limit_exceeded');
+}
+export function normalizeFormValues(fields, raw) {
+  return Object.fromEntries(Object.entries(fields).map(([name, field]) => {
+    const value = raw[name];
+    return [name, field.type === 'array' ? value.map(row => normalizeFormValues(field.item.fields, row))
+      : field.type === 'number' ? parseNumberDraft(value).value
+      : field.type === 'dateTime' ? isDateTime(value) ? new Date(value).toISOString() : null
+      : field.type === 'plainDate' ? isPlainDate(value) ? value : null : structuredClone(value)];
+  }));
+}
+/** errors / validatingFields 的索引只对应这次快照；无错误行必须是显式 null。 */
+export function assertErrorTree(tree, fields, values, boolean = false, maxText = 4096) {
+  formObject(tree, Object.keys(fields));
+  for (const [name, error] of Object.entries(tree)) {
+    const field = fields[name];
+    if (field.type === 'array') {
+      if (!Array.isArray(error) || error.length > (values?.[name]?.length ?? field.maxItems) || Object.keys(error).length !== error.length) fail();
+      for (const row of error) if (row !== null) assertErrorTree(row, field.item.fields, undefined, boolean, maxText);
+    } else if (boolean ? typeof error !== 'boolean' : typeof error !== 'string' || !error.trim() || error.length > maxText) fail();
+  }
+}
+export function assertArrayErrors(errors, fields, maxText = 4096) {
+  formObject(errors, Object.keys(fields).filter(name => fields[name].type === 'array'));
+  if (Object.values(errors).some(value => typeof value !== 'string' || !value.trim() || value.length > maxText)) fail();
+}
+export function flattenErrors(tree = {}) {
+  return Object.fromEntries(Object.entries(tree).flatMap(([name, value]) => Array.isArray(value)
+    ? value.flatMap((row, index) => Object.entries(row ?? {}).map(([key, error]) => [`${name}[${index}].${key}`, error])) : [[name, value]]));
+}
+export function nestErrors(flat) {
+  const tree = {};
+  for (const [path, error] of Object.entries(flat)) {
+    const address = parseFieldPath(path);
+    if (!address.array) tree[path] = error;
+    else {
+      const rows = tree[address.array] ??= [];
+      while (rows.length <= address.index) rows.push(null);
+      (rows[address.index] ??= {})[address.field] = error;
+    }
+  }
+  return tree;
+}
+export function assertArrayBinding(binding) {
+  formObject(binding, ['name', 'rowKey', 'formInstanceId', 'structureRevision']);
+  if (!validFieldKey(binding.name) || !opaque(binding.rowKey) || !opaque(binding.formInstanceId) || !revision(binding.structureRevision)) fail();
+  return binding;
+}
+const opaque = value => typeof value === 'string' && value.length > 0 && value.length <= 200;
+const revision = value => Number.isSafeInteger(value) && value >= 0;
+export function assertArrayOperation(input) {
+  formObject(input, ['formId', 'formInstanceId', 'arrayName', 'baseStructureRevision', 'action']);
+  if (!opaque(input.formId) || !opaque(input.formInstanceId) || !validFieldKey(input.arrayName) || !revision(input.baseStructureRevision)) fail();
+  const action = input.action;
+  const keys = { append: ['kind', 'value'], insertBefore: ['kind', 'beforeKey', 'value'], remove: ['kind', 'rowKey'], move: ['kind', 'rowKey', 'before'] }[action?.kind];
+  if (!keys) fail();
+  formObject(action, keys);
+  if (Object.keys(action).length !== keys.length || keys.includes('rowKey') && !opaque(action.rowKey) || keys.includes('beforeKey') && !opaque(action.beforeKey) || keys.includes('before') && action.before !== null && !opaque(action.before)) fail();
+  return input;
+}
+export function assertArraySnapshot(snapshot, formId, name, fields) {
+  assertJsonValue(snapshot, { maxBytes: ARRAY_LIMITS.messageBytes, maxEntries: 4096 });
+  formObject(snapshot, ['formId', 'name', 'formInstanceId', 'revision', 'structureRevision', 'rows', 'submitting', 'canAppend', 'error']);
+  const field = fields[name];
+  if (snapshot.formId !== formId || snapshot.name !== name || !opaque(snapshot.formInstanceId) || !revision(snapshot.revision) || !revision(snapshot.structureRevision) || field?.type !== 'array' || !Array.isArray(snapshot.rows) || snapshot.rows.length > field.maxItems || typeof snapshot.submitting !== 'boolean' || typeof snapshot.canAppend !== 'boolean') fail();
+  const keys = new Set();
+  for (const [index, row] of snapshot.rows.entries()) {
+    formObject(row, ['key', 'index', 'value', 'errors', 'validatingFields']);
+    if (!opaque(row.key) || keys.has(row.key) || row.index !== index) fail();
+    keys.add(row.key);
+    assertFieldValue([row.value], { ...field, maxItems: 1 });
+    assertErrorTree(row.errors, field.item.fields);
+    assertErrorTree(row.validatingFields, field.item.fields, undefined, true);
+  }
+  if (snapshot.error !== null && (typeof snapshot.error !== 'string' || !snapshot.error || snapshot.error.length > 4096) || formBytes(snapshot) > ARRAY_LIMITS.messageBytes) fail();
+  return snapshot;
+}

package/src/forms/components.generated.js

@@ -0,0 +1,4 @@
+// 此文件由 scripts/generate-components.mjs 生成，请修改产品能力声明。
+export const fieldComponents = Object.freeze(["TextInput","Checkbox","Select","Combobox","MemberCombobox","TeamCombobox","TextArea","NumberInput","PlainDateInput","DateTimeInput","Toggle","RadioGroup","RecordCombobox"]);
+export const boundComponents = Object.freeze(["TextInput","Checkbox","Select","Combobox","MemberCombobox","TeamCombobox","SubmitButton","TextArea","NumberInput","PlainDateInput","DateTimeInput","Toggle","RadioGroup","RecordCombobox","InputGroup","Fieldset"]);
+export const formComponent = "Form";

package/src/forms/factory.js

@@ -0,0 +1,41 @@
+import { createFieldArrays } from './field-array.js';
+import { compileForm } from './schema.js';
+import { createWithState } from './state.js';
+import { useNormalizedRecordOptions, recordObjectsForField } from './record-options.js';
+import { boundComponents, formComponent } from './components.generated.js';
+import { useNormalizedOptions } from './normalize-options.js';
+export function createFormHook(React, { useBindCallback = () => callback => callback, useInvoke = () => () => Promise.reject(new Error('runtime_host_interaction_unavailable')) } = {}) {
+const { createElement, useId, useMemo, useRef } = React;
+
+return function useForm(options) {
+  const formId = useId();
+  const bindCallback = useBindCallback();
+  const invoke = useInvoke();
+  const initial = useRef(options);
+  return useMemo(() => {
+    const { initialValues } = initial.current;
+    const { schema, ...validation } = compileForm(initial.current, formId, bindCallback);
+    const arrays = createFieldArrays(React, formId, schema, invoke);
+    const field = type => function Field({ children, ...props }) {
+      const binding = arrays.useBinding(props.name);
+      if (type === 'Combobox' || type === 'RecordCombobox') {
+        const { options, ...rest } = props;
+        const normalized = type === 'RecordCombobox'
+          ? useNormalizedRecordOptions({ useRef, useMemo }, options, recordObjectsForField(binding.arrayBinding ? schema.fields[binding.arrayBinding.name].item.fields[binding.name] : schema.fields[props.name]))
+          : useNormalizedOptions({ useRef, useMemo }, options);
+        return createElement(type, { ...rest, ...normalized, ...binding, formId });
+      }
+      return createElement(type, { ...props, ...binding, formId }, children);
+    };
+    return Object.freeze({
+      FieldArray: arrays.FieldArray,
+      WithState: createWithState(React, formId, schema, initialValues),
+      Form: function Form({ children, onSubmit }) {
+        return createElement(formComponent, { formId, schema, initialValues, onSubmit, ...validation }, children);
+      },
+      ...Object.fromEntries(boundComponents.map(type => [type, field(type)])),
+    });
+  }, [formId]);
+}
+
+}

package/src/forms/field-array.d.ts

@@ -0,0 +1,16 @@
+import type { ReactNode } from 'react';
+import type { ArrayName, FormSchema, FormValues } from './schema.js';
+type ReadonlyValue<T> = T extends object ? { readonly [K in keyof T]: ReadonlyValue<T[K]> } : T;
+export type ArrayOperationResult = { ok: true; rowKey?: string } | { ok: false; code: string; message: string };
+type Row<S extends FormSchema, N extends ArrayName<S>> = FormValues<S>[N] extends (infer R)[] ? R : never;
+export interface FieldArrayHandle<R> {
+  readonly ready: boolean;
+  readonly rows: readonly { readonly key: string; readonly index: number; readonly value: ReadonlyValue<R>; readonly errors: Readonly<Partial<Record<keyof R, string>>>; readonly validatingFields: Readonly<Partial<Record<keyof R, boolean>>> }[];
+  readonly pending: boolean; readonly submitting: boolean; readonly canAppend: boolean;
+  readonly error: string | null; readonly operationError: string | null;
+  append(value: R): Promise<ArrayOperationResult>;
+  insertBefore(beforeKey: string, value: R): Promise<ArrayOperationResult>;
+  remove(rowKey: string): Promise<ArrayOperationResult>;
+  move(rowKey: string, position: { before: string | null }): Promise<ArrayOperationResult>;
+}
+export type FieldArrayComponent<S extends FormSchema> = <N extends ArrayName<S>>(props: { name: N; children: (array: FieldArrayHandle<Row<S, N>>) => ReactNode }) => ReactNode;

package/src/forms/field-array.js

@@ -0,0 +1,52 @@
+import { assertArraySnapshot, parseFieldPath } from './array-contract.js';
+import { freezeFormState } from './state.js';
+
+export function createFieldArrays(React, formId, schema, invoke) {
+  const { createContext, createElement, Fragment, useContext, useEffect, useRef, useState, useMemo } = React;
+  const Context = createContext(null);
+  // 只串行化结构操作；行值仍由 Host 持有，不能乐观修改第二份草稿。
+  const gate = { pending: false };
+  function Observer({ name, children }) {
+    if (schema.fields[name]?.type !== 'array' || typeof children !== 'function') throw new Error('runtime_form_array_invalid');
+    const latest = useRef(null), alive = useRef(true);
+    const [snapshot, setSnapshot] = useState(null), [pending, setPending] = useState(false), [operationError, setError] = useState(null);
+    useEffect(() => { alive.current = true; return () => { alive.current = false; }; }, []);
+    const onState = useMemo(() => next => {
+      assertArraySnapshot(next, formId, name, schema.fields);
+      if (!alive.current || latest.current && latest.current.formInstanceId === next.formInstanceId && latest.current.revision >= next.revision) return;
+      latest.current = freezeFormState(next); setSnapshot(latest.current);
+    }, [name]);
+    async function operate(action) {
+      const state = latest.current;
+      const reject = (code, message) => { if (alive.current) setError(message); return { ok: false, code, message }; };
+      if (!alive.current || !state) return reject('owner_closed', '表单尚未就绪');
+      if (gate.pending || state.submitting) return reject('busy', '请等待当前操作完成');
+      gate.pending = true; setPending(true); setError(null);
+      try {
+        const result = await invoke('formArray', { formId, formInstanceId: state.formInstanceId, arrayName: name, baseStructureRevision: state.structureRevision, action });
+        if (result?.snapshot) onState(result.snapshot);
+        if (!result || typeof result.ok !== 'boolean') throw new Error('runtime_form_array_invalid');
+        if (!result.ok) return reject(result.code, result.message);
+        return { ok: true, ...(result.rowKey ? { rowKey: result.rowKey } : {}) };
+      } catch { return reject('owner_closed', '操作未确认，请检查当前明细后再操作'); }
+      finally { gate.pending = false; if (alive.current) setPending(false); }
+    }
+    const handle = Object.freeze({ ready: Boolean(snapshot), rows: snapshot?.rows ?? [], pending, submitting: snapshot?.submitting ?? false,
+      canAppend: Boolean(snapshot?.canAppend && !pending), error: snapshot?.error ?? null, operationError,
+      append: value => operate({ kind: 'append', value }), insertBefore: (beforeKey, value) => operate({ kind: 'insertBefore', beforeKey, value }),
+      remove: rowKey => operate({ kind: 'remove', rowKey }), move: (rowKey, { before }) => operate({ kind: 'move', rowKey, before }),
+    });
+    return createElement(Fragment, null, createElement('FormArrayObserver', { formId, name, onState }),
+      createElement(Context.Provider, { value: snapshot }, children(handle)));
+  }
+  function useBinding(name) {
+    const snapshot = useContext(Context);
+    if (name === undefined) return {};
+    const path = parseFieldPath(name);
+    if (!path.array) return { name };
+    if (!snapshot || snapshot.name !== path.array || !snapshot.rows[path.index] || !schema.fields[path.array].item.fields[path.field]) throw new Error('runtime_form_array_binding_missing');
+    return { name: path.field, arrayBinding: { name: path.array, rowKey: snapshot.rows[path.index].key, formInstanceId: snapshot.formInstanceId, structureRevision: snapshot.structureRevision } };
+  }
+  function FieldArray(props) { return createElement(Observer, { ...props, key: props.name }); }
+  return { FieldArray, useBinding };
+}

package/src/forms/index.d.ts

@@ -0,0 +1,118 @@
+// 此文件由 scripts/generate-components.mjs 生成，请修改产品能力声明。
+import type { ComponentType, ReactNode } from "react";
+import type { FormSchema, FormValues, FieldName, FormSubmitResult, FormOptions } from "./schema.js";
+import type { Option, OptionsPage, OptionsProvider } from "./options.js";
+import type { RecordOptionsProvider } from "./record-options.js";
+import type { FieldArrayComponent } from "./field-array.js";
+export type { FieldArrayHandle, ArrayOperationResult } from "./field-array.js";
+import type { WithStateComponent } from "./state.js";
+export type { FormStateSelection, SelectedFormState } from "./state.js";
+export type { RecordRef, RecordObjectOption, RecordOption, RecordOptionsPage, RecordOptionsProvider } from "./record-options.js";
+export type { Option, OptionsPage, OptionsProvider } from "./options.js";
+export { Forms } from "./schema.js";
+export type { FormField, FormSchema, FormValues, FieldName, FormSubmitResult, FormOptions, FormValidationResult, FormFieldErrors, FormArrayErrors, ArrayName } from "./schema.js";
+export interface FormHandle<S extends FormSchema> {
+  WithState: WithStateComponent<S>;
+  FieldArray: FieldArrayComponent<S>;
+  Form: ComponentType<{
+  children?: ReactNode;
+  onSubmit: (values: FormValues<S>) => FormSubmitResult<S> | Promise<FormSubmitResult<S>>;
+  }>;
+  TextInput: ComponentType<{
+  name: FieldName<S, "string">;
+  description?: string;
+  placeholder?: string;
+  disabled?: boolean;
+  type?: "text" | "email" | "password" | "tel" | "url";
+  }>;
+  Checkbox: ComponentType<{
+  name: FieldName<S, "boolean">;
+  description?: string;
+  disabled?: boolean;
+  labelHidden?: boolean;
+  }>;
+  Select: ComponentType<{
+  name: FieldName<S, "enum">;
+  description?: string;
+  placeholder?: string;
+  disabled?: boolean;
+  }>;
+  Combobox: ComponentType<{
+  name: FieldName<S, "string">;
+  description?: string;
+  placeholder?: string;
+  disabled?: boolean;
+  options: readonly Option[] | OptionsProvider;
+  }>;
+  MemberCombobox: ComponentType<{
+  name: FieldName<S, "string">;
+  description?: string;
+  placeholder?: string;
+  disabled?: boolean;
+  }>;
+  TeamCombobox: ComponentType<{
+  name: FieldName<S, "string">;
+  description?: string;
+  placeholder?: string;
+  disabled?: boolean;
+  }>;
+  SubmitButton: ComponentType<{
+  children?: string;
+  disabled?: boolean;
+  }>;
+  TextArea: ComponentType<{
+  name: FieldName<S, "string">;
+  description?: string;
+  placeholder?: string;
+  disabled?: boolean;
+  resizable?: boolean;
+  }>;
+  NumberInput: ComponentType<{
+  name: FieldName<S, "number">;
+  description?: string;
+  placeholder?: string;
+  disabled?: boolean;
+  step?: number;
+  }>;
+  PlainDateInput: ComponentType<{
+  name: FieldName<S, "plainDate">;
+  description?: string;
+  placeholder?: string;
+  disabled?: boolean;
+  }>;
+  DateTimeInput: ComponentType<{
+  name: FieldName<S, "dateTime">;
+  description?: string;
+  placeholder?: string;
+  disabled?: boolean;
+  }>;
+  Toggle: ComponentType<{
+  name: FieldName<S, "boolean">;
+  description?: string;
+  placeholder?: string;
+  disabled?: boolean;
+  }>;
+  RadioGroup: ComponentType<{
+  name: FieldName<S, "enum">;
+  description?: string;
+  placeholder?: string;
+  disabled?: boolean;
+  variant?: "default" | "cards";
+  }>;
+  RecordCombobox: ComponentType<{
+  name: FieldName<S, "record">;
+  description?: string;
+  placeholder?: string;
+  disabled?: boolean;
+  options?: RecordOptionsProvider;
+  }>;
+  InputGroup: ComponentType<{
+  children?: ReactNode;
+  }>;
+  Fieldset: ComponentType<{
+  legend: string;
+  children?: ReactNode;
+  }>;
+}
+/** schema 和 initialValues 仅在首次挂载使用；重新渲染不会重置输入。 */
+export function useForm<const S extends FormSchema>(options: FormOptions<S>): FormHandle<S>;

package/src/forms/index.js

@@ -0,0 +1,5 @@
+import * as React from "react";
+import { createFormHook } from "./factory.js";
+export const useForm = createFormHook(React);
+
+export { Forms } from './schema.js';

package/src/forms/normalize-options.js

@@ -0,0 +1,19 @@
+import { assertOptions, assertOptionsSearch, assertOptionsPage, assertOptionValue, assertSelectedOption } from './options.js';
+export function useNormalizedOptions({ useRef, useMemo }, options) {
+  const source = useRef({ options: null, search: null, getOption: null, revision: 0 });
+  const search = options?.search, getOption = options?.getOption;
+  if (source.current.options !== options || source.current.search !== search || source.current.getOption !== getOption) {
+    source.current = { options, search, getOption, revision: source.current.revision + 1 };
+  }
+  const revision = source.current.revision;
+  const normalized = useMemo(() => {
+    if (Array.isArray(options)) return { options: assertOptions(options) };
+    if (!options || typeof search !== 'function' || typeof getOption !== 'function') throw new Error('runtime_options_invalid');
+    return {
+      sourceRevision: String(revision),
+      onSearch: input => Promise.resolve(search.call(options, assertOptionsSearch(input))).then(assertOptionsPage),
+      onGetOption: value => Promise.resolve(getOption.call(options, assertOptionValue(value))).then(option => assertSelectedOption(option, value)),
+    };
+  }, [revision]);
+  return normalized;
+}

package/src/forms/options.d.ts

@@ -0,0 +1,30 @@
+import type { AppIconName, BadgeProps } from '../ui/index.js';
+/** value 是持久化标识，label 只负责显示。无法回显不能清除原 value。 */
+export type Option = {
+  value: string;
+  label: string;
+  description?: string;
+  disabled?: boolean;
+  disabledReason?: string;
+  categoryLabel?: string;
+  avatarUrl?: string;
+  icon?: AppIconName;
+  color?: NonNullable<BadgeProps['color']>;
+}
+export type OptionsPage = {
+  items: Option[];
+  /** null 表示末页；游标只能在当前搜索下使用。 */
+  nextCursor: string | null;
+}
+export interface OptionsProvider {
+  search(input: { query: string; cursor?: string }): Promise<OptionsPage>;
+  /** null 表示成功查询但无法解析；读取失败应拒绝 Promise。 */
+  getOption(value: string): Promise<Option | null>;
+}
+export const OPTIONS_PAGE_LIMIT: number;
+export function assertOption(value: unknown): Option;
+export function assertOptionValue(value: unknown): string;
+export function assertOptions(value: unknown): Option[];
+export function assertOptionsSearch(value: unknown): { query: string; cursor?: string };
+export function assertOptionsPage(value: unknown): OptionsPage;
+export function assertSelectedOption(option: unknown, value: string): Option | null;