@77-zhike/app-sdk 0.2.0-d7b1.2 → 0.2.0-d7b1.20

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,15 @@ export interface FormHandle<S extends FormSchema> {
   description?: string;
   placeholder?: string;
   disabled?: boolean;
+  labelHidden?: boolean;
+  inputMode?: "numeric" | "decimal";
+  type?: "text" | "email" | "password" | "tel" | "url";
   }>;
   Checkbox: ComponentType<{
   name: FieldName<S, "boolean">;
   description?: string;
   disabled?: boolean;
+  labelHidden?: boolean;
   }>;
   Select: ComponentType<{
   name: FieldName<S, "enum">;
@@ -48,7 +61,65 @@ export interface FormHandle<S extends FormSchema> {
   SubmitButton: ComponentType<{
   children?: string;
   disabled?: boolean;
+  icon?: import("../ui/index.js").AppIconName;
+  iconOnly?: boolean;
+  label?: string;
+  }>;
+  TextArea: ComponentType<{
+  name: FieldName<S, "string">;
+  description?: string;
+  placeholder?: string;
+  disabled?: boolean;
+  resizable?: boolean;
+  labelHidden?: boolean;
+  appearance?: "default" | "revision";
+  }>;
+  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[];

package/src/forms/record-options.js

@@ -0,0 +1,92 @@
+import { assertOptionValue, assertOptionsSearch } from './options.js';
+const fail = () => { throw new Error('runtime_record_options_invalid'); };
+const only = (value, keys) => {
+  if (!value || typeof value !== 'object' || Array.isArray(value) || Object.keys(value).some(key => !keys.includes(key))) fail();
+};
+/** 仅用于 Host 选择器 identity，不作为公开保存值或传输编码。 */
+export const recordKey = value => JSON.stringify([value.objectSlug, value.recordId]);
+export function assertRecordRef(value, objects) {
+  only(value, ['objectSlug', 'recordId']);
+  assertOptionValue(value.objectSlug); assertOptionValue(value.recordId);
+  if (objects && !objects.some(object => object.objectSlug === value.objectSlug)) fail();
+  return value;
+}
+export function assertRecordObjects(objects) {
+  if (!Array.isArray(objects) || objects.length !== 1) fail();
+  const seen = new Set();
+  for (const object of objects) {
+    only(object, ['objectSlug', 'label']);
+    assertOptionValue(object.objectSlug);
+    if (seen.has(object.objectSlug) || typeof object.label !== 'string' || !object.label.trim() || object.label.length > 200) fail();
+    seen.add(object.objectSlug);
+  }
+  return objects;
+}
+/** 新配置绑定唯一对象；旧数组仅允许恰好一项。 */
+export function recordObjectsForField(field) {
+  if (field.objectSlug !== undefined) {
+    if (field.objects !== undefined) fail();
+    assertOptionValue(field.objectSlug);
+    return [{ objectSlug: field.objectSlug, label: field.label }];
+  }
+  return assertRecordObjects(field.objects);
+}
+export function assertRecordSearch(input, objects) {
+  only(input, ['objectSlug', 'query', 'cursor']);
+  assertOptionValue(input.objectSlug);
+  if (objects && !objects.some(object => object.objectSlug === input.objectSlug)) fail();
+  assertOptionsSearch({ query: input.query, ...(input.cursor === undefined ? {} : { cursor: input.cursor }) });
+  return input;
+}
+export function assertRecordOption(option) {
+  only(option, ['value', 'label', 'description', 'disabled', 'disabledReason']);
+  assertRecordRef(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();
+  return option;
+}
+export function assertRecordPage(page, objectSlug) {
+  only(page, ['items', 'nextCursor']);
+  if (!Array.isArray(page.items) || page.items.length > 100) fail();
+  if (page.nextCursor !== null && (typeof page.nextCursor !== 'string' || !page.nextCursor || page.nextCursor.length > 4096)) fail();
+  const seen = new Set();
+  for (const item of page.items) {
+    assertRecordOption(item);
+    const key = recordKey(item.value);
+    if (item.value.objectSlug !== objectSlug || seen.has(key)) fail();
+    seen.add(key);
+  }
+  return page;
+}
+export function assertSelectedRecordOption(option, ref) {
+  assertRecordRef(ref);
+  if (option === null) return null;
+  assertRecordOption(option);
+  if (recordKey(option.value) !== recordKey(ref)) fail();
+  return option;
+}
+export function useNormalizedRecordOptions({ useRef, useMemo }, options, objects) {
+  assertRecordObjects(objects);
+  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;
+  return useMemo(() => {
+    if (options === undefined) return {};
+    if (!options || typeof search !== 'function' || typeof getOption !== 'function') fail();
+    return {
+      sourceRevision: String(revision),
+      onSearch: input => {
+        assertRecordSearch(input, objects);
+        return Promise.resolve(search.call(options, input)).then(page => assertRecordPage(page, input.objectSlug));
+      },
+      onGetOption: value => {
+        assertRecordRef(value, objects);
+        return Promise.resolve(getOption.call(options, value)).then(option => assertSelectedRecordOption(option, value));
+      },
+    };
+  }, [revision]);
+}

package/src/forms/schema.d.ts

@@ -1,18 +1,82 @@
-export type FormField =
-  | { type: "string"; label: string; required?: boolean; maxLength?: number }
+import type { RecordRef, RecordObjectOption } from "./record-options.js";
+export interface RuleMessages { required?: string; min?: string; max?: string; format?: string; }
+export type FormField = (
+  | { type: "string"; label: string; required?: boolean; minLength?: number; maxLength?: number; format?: "email" | "url" }
   | { type: "boolean"; label: string; required?: boolean }
-  | { type: "enum"; label: string; required?: boolean; options: readonly { value: string; label: string }[] };
-export interface FormSchema { fields: Readonly<Record<string, FormField>>; }
-export type FormValues<S extends FormSchema> = {
-  [K in keyof S["fields"]]: S["fields"][K] extends { type: "boolean" } ? boolean : string;
+  | { type: "enum"; label: string; required?: boolean; options: readonly { value: string; label: string; description?: string }[] }
+  | { type: "number"; label: string; required?: boolean; min?: number; max?: number }
+  | { type: "plainDate" | "dateTime"; label: string; required?: boolean; min?: string; max?: string }
+  | ({ type: "record"; label: string; required?: boolean } & ({ objectSlug: string; objects?: never } | { objectSlug?: never; objects: readonly [RecordObjectOption] }))) & { messages?: RuleMessages };
+export type LeafDefinition = FormField | { type: FormField['type']; label: (text: string) => unknown };
+export interface ArrayField<F extends Record<string, LeafDefinition> = Record<string, LeafDefinition>> {
+  type: 'array'; label: string; minItems: number; maxItems: number; item: { type: 'object'; fields: F };
+  messages?: { min?: string; max?: string };
+}
+export type ArrayBuilder<F extends Record<string, LeafDefinition>> = Omit<ArrayField<F>, 'label'> & {
+  label(text: string): ArrayBuilder<F>;
+  min(count: number, options?: MessageOption): ArrayBuilder<F>;
+  max(count: number, options?: MessageOption): ArrayBuilder<F>;
+  custom(validator: (rows: ReadonlyValue<RowValues<F>[]>) => void | string | Promise<void | string>): ArrayBuilder<F>;
 };
+export interface FormSchema { fields: Readonly<Record<string, LeafDefinition | ArrayField | ArrayBuilder<Record<string, LeafDefinition>>>>; }
+export type ValueOf<F> = F extends { type: 'array'; item: { fields: infer R extends Record<string, LeafDefinition> } } ? RowValues<R>[]
+  : F extends { type: 'boolean' } ? boolean : F extends { type: 'record' } ? (F extends { objectSlug: infer O extends string } ? RecordRef & { objectSlug: O } : RecordRef) | null
+  : F extends { type: 'number' } ? number | null : F extends { type: 'plainDate' | 'dateTime' } ? string | null : string;
+export type RowValues<F extends Record<string, LeafDefinition>> = { [K in keyof F]: ValueOf<F[K]> };
+export type FormValues<S extends FormSchema> = { [K in keyof S['fields']]: ValueOf<S['fields'][K]> };
+export type ArrayName<S extends FormSchema> = { [K in keyof S['fields']]: S['fields'][K]['type'] extends 'array' ? K : never }[keyof S['fields']] & string;
 export type FieldName<S extends FormSchema, T extends FormField['type']> = {
-  [K in keyof S['fields']]: S['fields'][K]['type'] extends T ? K : never;
-}[keyof S['fields']] & string;
+  [K in keyof S['fields'] & string]: S['fields'][K] extends { type: 'array'; item: { fields: infer F extends Record<string, LeafDefinition> } }
+    ? `${K}[${number}].${{ [P in keyof F & string]: F[P]['type'] extends T ? P : never }[keyof F & string]}`
+    : S['fields'][K]['type'] extends T ? K : never;
+}[keyof S['fields'] & string];
+export type FormFieldErrors<S extends FormSchema, E = string> = { [K in keyof S['fields']]?: S['fields'][K] extends { type: 'array'; item: { fields: infer F } }
+  ? (Partial<Record<keyof F, E>> | null)[] : E };
+export type FormArrayErrors<S extends FormSchema> = Partial<Record<ArrayName<S>, string>>;
 /** void 兼容既有提交；失败保留输入，字段名必须属于当前表单。 */
 export type FormSubmitResult<S extends FormSchema> = void | { ok: true } | {
   ok: false;
   code: string;
   message: string;
-  fieldErrors?: Partial<Record<Extract<keyof S['fields'], string>, string>>;
+  fieldErrors?: FormFieldErrors<S>;
+  arrayErrors?: FormArrayErrors<S>;
+};
+
+export type FormValidationResult<S extends FormSchema> = void | {
+  fieldErrors?: FormFieldErrors<S>;
+  arrayErrors?: FormArrayErrors<S>;
+  formError?: string;
+};
+type FieldValue<F extends FormField> = FormValues<{ fields: { value: F } }>['value'];
+type ReadonlyValue<T> = T extends object ? { readonly [K in keyof T]: ReadonlyValue<T[K]> } : T;
+export type FormOptions<S extends FormSchema> = {
+  schema: S;
+  initialValues: FormValues<S>;
+  validationMode?: 'onBlur' | 'onChange' | 'onSubmit';
+  validate?: (values: ReadonlyValue<FormValues<S>>) => FormValidationResult<S> | Promise<FormValidationResult<S>>;
+};
+type MessageOption = { message: string };
+export type FieldBuilder<F extends FormField> = Omit<F, 'label'> & {
+  label(text: string): FieldBuilder<F>;
+  required(message?: string): FieldBuilder<F>;
+  optional(): FieldBuilder<F>;
+  custom(validator: (value: ReadonlyValue<FieldValue<F>>) => void | string | Promise<void | string>): FieldBuilder<F>;
+} & (F['type'] extends 'string' | 'number' | 'plainDate' | 'dateTime' ? {
+  min(value: F['type'] extends 'string' | 'number' ? number : string, options?: MessageOption): FieldBuilder<F>;
+  max(value: F['type'] extends 'string' | 'number' ? number : string, options?: MessageOption): FieldBuilder<F>;
+} : {}) & (F['type'] extends 'string' ? {
+  email(options?: MessageOption): FieldBuilder<F>;
+  url(options?: MessageOption): FieldBuilder<F>;
+} : {});
+// builder 的 label 是方法，wire 的 label 是字符串；只有编译后才跨 Worker 边界。
+export const Forms: {
+  schema<const F extends Record<string, LeafDefinition | ArrayBuilder<Record<string, LeafDefinition>>>>(fields: F): { readonly fields: F };
+  array<const F extends Record<string, LeafDefinition>>(fields: F): ArrayBuilder<F>;
+  string(): FieldBuilder<Extract<FormField, { type: 'string' }>>;
+  number(): FieldBuilder<Extract<FormField, { type: 'number' }>>;
+  boolean(): FieldBuilder<Extract<FormField, { type: 'boolean' }>>;
+  enum(options: readonly { value: string; label: string; description?: string }[]): FieldBuilder<Extract<FormField, { type: 'enum' }>>;
+  plainDate(): FieldBuilder<{ type: 'plainDate'; label: string }>;
+  dateTime(): FieldBuilder<{ type: 'dateTime'; label: string }>;
+  record<const O extends string>(objectSlug: O): FieldBuilder<{ type: 'record'; label: string; objectSlug: O }>;
 };