@77-zhike/app-sdk 0.2.0-d7b1.6 → 0.2.0-d7b1.8

package/src/client/interactions.js

@@ -1,3 +1,6 @@
+import { assertExternalUrl } from './external-url.js';
+import { assertAppDestination } from './destinations.js';
+
 const fail = () => { throw new Error('runtime_interaction_invalid'); };
 const text = (value, max, required = false) => value === undefined ? !required : typeof value === 'string' && value.length <= max && (!required || value.length > 0);
 const externalUrl = value => {
@@ -9,13 +12,19 @@ const externalUrl = value => {
 };
 export function assertHostInteraction(operation, input) {
   if (!input || typeof input !== 'object' || Array.isArray(input)) fail();
-  const allowed = operation === 'showToast' ? ['message','tone'] : operation === 'confirm' ? ['title','description','confirmLabel','cancelLabel'] : operation === 'openExternalUrl' ? ['url'] : [];
+  const allowed = operation === 'showToast' ? ['message','tone'] : operation === 'confirm' ? ['title','description','confirmLabel','cancelLabel'] : operation === 'navigate' ? ['destination'] : operation === 'openExternal' ? ['href'] : operation === 'openExternalUrl' ? ['url'] : [];
   if (!allowed.length || Object.keys(input).some(key=>!allowed.includes(key))) fail();
   if (operation === 'showToast') {
     if (!text(input.message,500,true) || (input.tone !== undefined && !['info','success','error'].includes(input.tone))) fail();
   } else if (operation === 'confirm') {
     if (!text(input.title,200,true) || !text(input.description,2000) || !text(input.confirmLabel,60) || !text(input.cancelLabel,60)) fail();
-  } else if (!externalUrl(input.url)) fail();
+  } else if (operation === 'openExternalUrl') {
+    if (!externalUrl(input.url)) fail();
+  } else if (operation === 'openExternal') {
+    try { return Object.freeze({ href: assertExternalUrl(input.href) }); } catch { fail(); }
+  } else {
+    try { assertAppDestination(input.destination); } catch { fail(); }
+  }
   return Object.freeze(Object.fromEntries(Object.entries(input).filter(([,value])=>value!==undefined)));
 }
 export function createClientInteractions(invoke) {
@@ -32,5 +41,13 @@ export function createClientInteractions(invoke) {
       const request = assertHostInteraction('openExternalUrl',{url});
       return invoke('openExternalUrl',request).then(value=>{if(value!==null)fail();});
     },
+    openExternal(href) {
+      const request = assertHostInteraction('openExternal', {href});
+      return invoke('openExternal',request).then(value=>{if(typeof value!=='boolean')fail();return value;});
+    },
+    navigate(destination) {
+      const request = assertHostInteraction('navigate',{destination});
+      return invoke('navigate',request).then(value=>{if(value!==null)fail();});
+    },
   });
 }

package/src/client/points.generated.js

@@ -14,6 +14,54 @@ export const frontendPoints = Object.freeze([
     "definitionName": "RecordActionDefinition",
     "callbackName": "onTrigger",
     "maxPerApp": 100
+  },
+  {
+    "key": "app.object-actions",
+    "kind": "action",
+    "legacyType": "object-action",
+    "definitionName": "ObjectActionDefinition",
+    "callbackName": "onTrigger",
+    "maxPerApp": 100
+  },
+  {
+    "key": "app.bulk-record-actions",
+    "kind": "action",
+    "legacyType": "bulk-record-action",
+    "definitionName": "BulkRecordActionDefinition",
+    "callbackName": "onTrigger",
+    "maxPerApp": 100
+  },
+  {
+    "key": "app.record-page-widgets",
+    "kind": "view",
+    "legacyType": "record-widget",
+    "definitionName": "RecordWidgetDefinition",
+    "componentName": "Widget",
+    "maxPerApp": 100
+  },
+  {
+    "key": "app.record-sections",
+    "kind": "view",
+    "legacyType": "record-section",
+    "definitionName": "RecordSectionDefinition",
+    "componentName": "Section",
+    "maxPerApp": 100
+  },
+  {
+    "key": "app.record-page-tabs",
+    "kind": "view",
+    "legacyType": "record-tab",
+    "definitionName": "RecordTabDefinition",
+    "componentName": "Tab",
+    "maxPerApp": 100
+  },
+  {
+    "key": "app.workspace-pages",
+    "kind": "view",
+    "legacyType": "page",
+    "definitionName": "PageDefinition",
+    "componentName": "Page",
+    "maxPerApp": 100
   }
 ].map(Object.freeze));
 export const frontendPoint = type => frontendPoints.find(point => point.legacyType === type);

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

@@ -1,4 +1,4 @@
 // 此文件由 scripts/generate-components.mjs 生成，请修改产品能力声明。
-export const fieldComponents = Object.freeze(["TextInput","Checkbox","Select","Combobox","MemberCombobox","TeamCombobox"]);
-export const boundComponents = Object.freeze(["TextInput","Checkbox","Select","Combobox","MemberCombobox","TeamCombobox","SubmitButton"]);
+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

@@ -1,23 +1,37 @@
+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({ createElement, useId, useMemo, useRef }) {
+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 { schema, initialValues } = initial.current;
+    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 }) {
-      if (type === 'Combobox') {
+      const binding = arrays.useBinding(props.name);
+      if (type === 'Combobox' || type === 'RecordCombobox') {
         const { options, ...rest } = props;
-        const normalized = useNormalizedOptions({ useRef, useMemo }, options);
-        return createElement(type, { ...rest, ...normalized, formId });
+        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, formId }, children);
+      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 }, children);
+        return createElement(formComponent, { formId, schema, initialValues, onSubmit, ...validation }, children);
       },
       ...Object.fromEntries(boundComponents.map(type => [type, field(type)])),
     });

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

@@ -1,10 +1,19 @@
 // 此文件由 scripts/generate-components.mjs 生成，请修改产品能力声明。
 import type { ComponentType, ReactNode } from "react";
-import type { FormSchema, FormValues, FieldName, FormSubmitResult } from "./schema.js";
+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 type { FormField, FormSchema, FormValues, FieldName, FormSubmitResult } from "./schema.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>>;
@@ -14,11 +23,13 @@ export interface FormHandle<S extends FormSchema> {
   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">;
@@ -49,6 +60,59 @@ export interface FormHandle<S extends FormSchema> {
   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: { schema: S; initialValues: FormValues<S> }): FormHandle<S>;
+export function useForm<const S extends FormSchema>(options: FormOptions<S>): FormHandle<S>;

package/src/forms/index.js

@@ -1,3 +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/options.d.ts

@@ -1,12 +1,17 @@
+import type { AppIconName, BadgeProps } from '../ui/index.js';
 /** value 是持久化标识，label 只负责显示。无法回显不能清除原 value。 */
-export interface Option {
+export type Option = {
   value: string;
   label: string;
   description?: string;
   disabled?: boolean;
   disabledReason?: string;
+  categoryLabel?: string;
+  avatarUrl?: string;
+  icon?: AppIconName;
+  color?: NonNullable<BadgeProps['color']>;
 }
-export interface OptionsPage {
+export type OptionsPage = {
   items: Option[];
   /** null 表示末页；游标只能在当前搜索下使用。 */
   nextCursor: string | null;

package/src/forms/options.js

@@ -1,16 +1,23 @@
+import { sdkIconNames } from '../ui/icons.generated.js';
+import { badgeColors } from '../ui/components.generated.js';
+import { assertExternalUrl } from '../client/external-url.js';
 // SDK 回调与 Host 共用有界 DTO 验证；函数留在 Guest，不传递 Provider 对象。
 const fail = () => { throw new Error('runtime_options_invalid'); };
 const object = value => value !== null && typeof value === 'object' && !Array.isArray(value);
 const only = (value, keys) => { if (!object(value) || Object.keys(value).some(key => !keys.includes(key))) fail(); };
 export const OPTIONS_PAGE_LIMIT = 100;
 export function assertOption(option) {
-  only(option, ['value', 'label', 'description', 'disabled', 'disabledReason']);
+  only(option, ['value', 'label', 'description', 'disabled', 'disabledReason', 'categoryLabel', 'avatarUrl', 'icon', 'color']);
   assertOptionValue(option.value);
   if (typeof option.label !== 'string' || !option.label || option.label.length > 200) fail();
   for (const key of ['description', 'disabledReason']) {
     if (option[key] !== undefined && (typeof option[key] !== 'string' || option[key].length > 4096)) fail();
   }
   if (option.disabled !== undefined && typeof option.disabled !== 'boolean') fail();
+  if (option.categoryLabel !== undefined && (typeof option.categoryLabel !== 'string' || !option.categoryLabel.trim() || option.categoryLabel.length > 200)) fail();
+  if (option.avatarUrl !== undefined) { try { assertExternalUrl(option.avatarUrl); } catch { fail(); } }
+  if (option.icon !== undefined && !sdkIconNames.includes(option.icon)) fail();
+  if (option.color !== undefined && !badgeColors.includes(option.color)) fail();
   return option;
 }
 export function assertOptionValue(value) {

package/src/forms/record-options.d.ts

@@ -0,0 +1,28 @@
+export type RecordRef = {
+  /** 数据源范围内稳定的公开对象键，不是内部模型名或授权证明。 */
+  objectSlug: string;
+  recordId: string;
+};
+export type RecordObjectOption = { objectSlug: string; label: string; }
+export type RecordOption = {
+  value: RecordRef;
+  label: string;
+  description?: string;
+  disabled?: boolean;
+  disabledReason?: string;
+}
+export type RecordOptionsPage = { items: RecordOption[]; nextCursor: string | null; }
+export interface RecordOptionsProvider {
+  search(input: { objectSlug: string; query: string; cursor?: string }): Promise<RecordOptionsPage>;
+  /** null 表示未解析；查询错误必须拒绝 Promise，不能静默清空引用。 */
+  getOption(value: RecordRef): Promise<RecordOption | null>;
+}
+export function recordKey(value: RecordRef): string;
+export function assertRecordRef(value: unknown, objects?: readonly RecordObjectOption[]): RecordRef;
+export function assertRecordObjects(value: unknown): RecordObjectOption[];
+export function assertRecordSearch(value: unknown, objects?: readonly RecordObjectOption[]): { objectSlug: string; query: string; cursor?: string };
+export function assertRecordOption(value: unknown): RecordOption;
+export function assertRecordPage(value: unknown, objectSlug: string): RecordOptionsPage;
+export function assertSelectedRecordOption(value: unknown, ref: RecordRef): RecordOption | null;
+
+export function recordObjectsForField(field: { objectSlug?: string; objects?: readonly RecordObjectOption[]; label: string }): readonly RecordObjectOption[];