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

package/package.json

@@ -1,7 +1,12 @@
 {
   "name": "@77-zhike/app-sdk",
-  "version": "0.2.0-d7b1.7",
-  "description": "\u667a\u5ba2 Integration App \u4e00\u671f SDK \u4e0e\u672c\u5730 Toolchain",
+  "version": "0.2.0-d7b1.8",
+  "description": "智客 Integration App 一期 SDK 与本地 Toolchain",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/tonyjiang88215/TruthLoop.git",
+    "directory": "developer-tools/packages/app-sdk"
+  },
   "type": "module",
   "engines": {
     "node": ">=20"
@@ -53,5 +58,6 @@
     "react": {
       "optional": true
     }
-  }
+  },
+  "gitHead": "5ebb33176120cba2e1c70440cc56dc041e1cf924"
 }

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/factory.js

@@ -1,29 +1,34 @@
+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 } = {}) {
+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(schema.fields[props.name]))
+          ? 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, formId });
+        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, ...validation }, children);

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

@@ -3,14 +3,17 @@ 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 } 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>>;
@@ -69,6 +72,7 @@ export interface FormHandle<S extends FormSchema> {
   description?: string;
   placeholder?: string;
   disabled?: boolean;
+  step?: number;
   }>;
   PlainDateInput: ComponentType<{
   name: FieldName<S, "plainDate">;

package/src/forms/schema.d.ts

@@ -7,26 +7,44 @@ export type FormField = (
   | { 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 interface FormSchema { fields: Readonly<Record<string, FormField | { type: FormField['type']; label: (text: string) => unknown }>>; }
-export type FormValues<S extends FormSchema> = {
-  [K in keyof S["fields"]]: S["fields"][K] extends { type: "boolean" } ? boolean
-    : S["fields"][K] extends { type: "record" } ? (S["fields"][K] extends { objectSlug: infer O extends string } ? RecordRef & { objectSlug: O } : RecordRef) | null
-    : S["fields"][K] extends { type: "number" } ? number | null
-    : S["fields"][K] extends { type: "plainDate" | "dateTime" } ? string | null : string;
+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?: Partial<Record<Extract<keyof S['fields'], string>, string>>;
+  fieldErrors?: FormFieldErrors<S>;
+  arrayErrors?: FormArrayErrors<S>;
   formError?: string;
 };
 type FieldValue<F extends FormField> = FormValues<{ fields: { value: F } }>['value'];
@@ -52,7 +70,8 @@ export type FieldBuilder<F extends FormField> = Omit<F, 'label'> & {
 } : {});
 // builder 的 label 是方法，wire 的 label 是字符串；只有编译后才跨 Worker 边界。
 export const Forms: {
-  schema<const F extends Record<string, { type: FormField['type']; label: (text: string) => unknown }>>(fields: F): { readonly fields: F };
+  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' }>>;

package/src/forms/schema.js

@@ -3,6 +3,8 @@ import { recordObjectsForField } from './record-options.js';
 import { freezeFormState } from './state.js';
 import { createValidationCallback } from './validation.js';
 
+import { validFieldKey, assertArrayCapacity } from './array-contract.js';
+
 const descriptors = new WeakMap();
 const fail = () => { throw new Error('runtime_form_schema_invalid'); };
 const message = value => {
@@ -18,7 +20,7 @@ function builder(field, validators = []) {
       if (!options || Object.keys(options).some(key => key !== 'message')) fail();
       messages[key] = message(options.message);
     } else delete messages[key];
-    return next({ [field.type === 'string' ? `${key}Length` : key]: value, messages });
+    return next({ [field.type === 'array' ? `${key}Items` : field.type === 'string' ? `${key}Length` : key]: value, messages });
   };
   const methods = {
     label(value) { return next({ label: value }); },
@@ -29,10 +31,11 @@ function builder(field, validators = []) {
       return next({}, [...validators, validator]);
     },
   };
-  if (['string', 'number', 'plainDate', 'dateTime'].includes(field.type)) {
+  if (['array', 'string', 'number', 'plainDate', 'dateTime'].includes(field.type)) {
     methods.min = (value, options) => rule('min', value, options);
     methods.max = (value, options) => rule('max', value, options);
   }
+  if (field.type === 'array') { delete methods.required; delete methods.optional; }
   if (field.type === 'string') for (const format of ['email', 'url']) methods[format] = options => {
     const messages = { ...field.messages };
     if (options === undefined) delete messages.format;
@@ -51,6 +54,10 @@ export const Forms = Object.freeze({
   },
   ...Object.fromEntries(['string', 'number', 'boolean', 'plainDate', 'dateTime'].map(type => [type, () => builder({ type })])),
   enum: options => builder({ type: 'enum', options: Array.isArray(options) ? options.map(option => Object.freeze({ ...option })) : options }),
+  array(fields) {
+    if (!fields || typeof fields !== 'object' || Array.isArray(fields) || !Object.keys(fields).length || Object.keys(fields).length > 12 || Object.values(fields).some(field => !descriptors.has(field) || field.type === 'array')) fail();
+    return builder({ type: 'array', minItems: 0, maxItems: 50, item: { type: 'object', fields: { ...fields } } });
+  },
   record: objectSlug => builder({ type: 'record', objectSlug }),
 });
 
@@ -58,13 +65,26 @@ export const Forms = Object.freeze({
 export function compileForm(options, formId, bindCallback = callback => callback) {
   const { schema, validate, validationMode = 'onBlur' } = options;
   if (!schema || !schema.fields || typeof schema.fields !== 'object' || Array.isArray(schema.fields) || Object.keys(schema).some(key => key !== 'fields')
-    || Object.keys(schema.fields).length > 30 || !['onBlur', 'onChange', 'onSubmit'].includes(validationMode)
+    || Object.values(schema.fields).filter(field => field.type !== 'array').length > 30 || Object.values(schema.fields).filter(field => field.type === 'array').length > 3 || !['onBlur', 'onChange', 'onSubmit'].includes(validationMode)
     || (validate !== undefined && typeof validate !== 'function')) fail();
   const fields = {}, validators = {};
   for (const [name, input] of Object.entries(schema.fields)) {
-    if (!/^[a-zA-Z][a-zA-Z0-9_]{0,63}$/.test(name) || ['constructor', 'prototype'].includes(name)) fail();
+    if (!validFieldKey(name)) fail();
     const descriptor = descriptors.get(input);
-    const field = structuredClone(descriptor?.field ?? input);
+    const source = descriptor?.field ?? input;
+    if (source?.type === 'array') {
+      if (Object.keys(source).some(key => !['type', 'label', 'minItems', 'maxItems', 'item', 'messages'].includes(key)) || typeof source.label !== 'string' || !source.label.trim() || source.label.length > 200
+        || !Number.isSafeInteger(source.minItems) || source.minItems < 0 || !Number.isSafeInteger(source.maxItems) || source.maxItems < 1 || source.maxItems > 50 || source.minItems > source.maxItems
+        || source.item?.type !== 'object' || Object.keys(source.item).some(key => !['type', 'fields'].includes(key)) || !source.item.fields || Object.values(source.item.fields).some(field => field.type === 'array')
+        || !Object.keys(source.item.fields).length || Object.keys(source.item.fields).length > 12) fail();
+      const child = compileForm({ schema: { fields: source.item.fields } }, formId, bindCallback);
+      fields[name] = { ...source, item: { type: 'object', fields: child.schema.fields } };
+      if (source.messages) { if (Object.keys(source.messages).some(key => !['min', 'max'].includes(key))) fail(); Object.values(source.messages).forEach(message); }
+      for (const [key, checks] of Object.entries(child.validators)) validators[`${name}[*].${key}`] = checks;
+      if (descriptor?.validators.length) validators[name] = descriptor.validators.map(bindCallback);
+      continue;
+    }
+    const field = structuredClone(source);
     if (!field || !['string', 'boolean', 'enum', 'number', 'plainDate', 'dateTime', 'record'].includes(field.type)
       || typeof field.label !== 'string' || descriptor && !field.label.trim() || field.label.length > 200) fail();
     const allowed = ['type', 'label', 'required', 'messages', ...(field.type === 'string' ? ['minLength', 'maxLength', 'format'] : field.type === 'enum' ? ['options'] : field.type === 'record' ? ['objectSlug', 'objects'] : ['number', 'plainDate', 'dateTime'].includes(field.type) ? ['min', 'max'] : [])];
@@ -99,7 +119,10 @@ export function compileForm(options, formId, bindCallback = callback => callback
   const validation = { fields: Object.keys(validators), form: Boolean(validate), mode: validationMode };
   const remote = Boolean(validation.fields.length || validate);
   const configured = remote || options.validationMode !== undefined || Object.values(schema.fields).some(field => descriptors.has(field));
-  return { schema: wire, ...(configured ? { validation } : {}), ...(remote ? {
+  if (options.initialValues !== undefined) assertArrayCapacity(fields, options.initialValues);
+  const result = { schema: wire, ...(configured ? { validation } : {}), ...(remote ? {
     onValidate: createValidationCallback(formId, fields, validators, validate ? bindCallback(validate) : undefined),
   } : {}) };
+  Object.defineProperty(result, 'validators', { value: validators });
+  return result;
 }

package/src/forms/state.d.ts

@@ -1,7 +1,8 @@
 import type { ReactNode } from 'react';
-import type { FormSchema, FormValues } from './schema.js';
+import type { FormSchema, FormValues, FormFieldErrors, FormArrayErrors } from './schema.js';
 export type FormStateSelection<S extends FormSchema> = {
   values?: true | readonly (keyof S['fields'] & string)[];
+  arrayErrors?: true | readonly (keyof FormArrayErrors<S> & string)[];
   errors?: true | readonly (keyof S['fields'] & string)[];
   submitting?: boolean;
   validating?: boolean;
@@ -12,17 +13,18 @@ type Names<S extends FormSchema, T> = T extends true ? keyof FormValues<S> : T e
 type ReadonlyValue<T> = T extends object ? { readonly [K in keyof T]: ReadonlyValue<T[K]> } : T;
 export type SelectedFormState<S extends FormSchema, Selection extends FormStateSelection<S>> =
   (Selection extends { values: infer T } ? { readonly values: ReadonlyValue<Pick<FormValues<S>, Names<S, T>>> } : {})
-  & (Selection extends { errors: infer T } ? { readonly errors: Readonly<Partial<Record<Names<S, T>, string>>> } : {})
+  & (Selection extends { errors: infer T } ? { readonly errors: ReadonlyValue<Pick<FormFieldErrors<S>, Names<S, T>>> } : {})
+  & (Selection extends { arrayErrors: infer T } ? { readonly arrayErrors: Readonly<Pick<FormArrayErrors<S>, Extract<Names<S, T>, keyof FormArrayErrors<S>>>> } : {})
   & (Selection extends { submitting: true } ? { readonly submitting: boolean } : {})
   & (Selection extends { validating: true } ? { readonly validating: boolean } : {})
   & (Selection extends { formError: true } ? { readonly formError: string | null } : {})
-  & (Selection extends { validatingFields: infer T } ? { readonly validatingFields: Readonly<Partial<Record<Names<S, T>, boolean>>> } : {});
+  & (Selection extends { validatingFields: infer T } ? { readonly validatingFields: ReadonlyValue<Pick<FormFieldErrors<S, boolean>, Names<S, T>>> } : {});
 export type WithStateComponent<S extends FormSchema> = <const Selection extends FormStateSelection<S>>(props: {
   selection: Selection;
   children: (state: SelectedFormState<S, Selection>) => ReactNode;
 }) => ReactNode;
 
-export type StateSelection = { values?: true | readonly string[]; errors?: true | readonly string[]; submitting?: boolean; validating?: boolean; validatingFields?: true | readonly string[]; formError?: boolean };
+export type StateSelection = { arrayErrors?: true | readonly string[]; values?: true | readonly string[]; errors?: true | readonly string[]; submitting?: boolean; validating?: boolean; validatingFields?: true | readonly string[]; formError?: boolean };
 export function selectedNames(selection: true | readonly string[] | undefined, fields: Record<string, unknown>): string[];
 export function assertFormStateSelection(selection: unknown, fields: Record<string, unknown>): StateSelection;
 export function assertFormStateSnapshot(snapshot: unknown, formId: string, fields: Record<string, unknown>, selection: StateSelection): unknown;

package/src/forms/state.js

@@ -1,6 +1,5 @@
+import { assertFieldValue, assertErrorTree, assertArrayErrors, normalizeFormValues, formBytes, ARRAY_LIMITS } from './array-contract.js';
 import { assertJsonValue } from '../ui/validation.js';
-import { isDateTime, isPlainDate } from './values.js';
-import { assertRecordRef, recordObjectsForField } from './record-options.js';
 const fail = () => { throw new Error('runtime_form_state_invalid'); };
 const only = (value, keys) => {
   if (!value || typeof value !== 'object' || Array.isArray(value) || Object.keys(value).some(key => !keys.includes(key))) fail();
@@ -9,47 +8,40 @@ export function selectedNames(selection, fields) {
   return selection === true ? Object.keys(fields) : Array.isArray(selection) ? selection : [];
 }
 export function assertFormStateSelection(selection, fields) {
-  only(selection, ['values', 'errors', 'submitting', 'validating', 'validatingFields', 'formError']);
-  for (const kind of ['values', 'errors', 'validatingFields']) {
+  only(selection, ['values', 'errors', 'submitting', 'validating', 'validatingFields', 'arrayErrors', 'formError']);
+  for (const kind of ['values', 'errors', 'validatingFields', 'arrayErrors']) {
     const names = selection[kind];
     if (names === undefined || names === true) continue;
-    if (!Array.isArray(names) || names.length > 30 || new Set(names).size !== names.length || names.some(name => typeof name !== 'string' || !Object.hasOwn(fields, name))) fail();
+    if (!Array.isArray(names) || names.length > 33 || new Set(names).size !== names.length || names.some(name => typeof name !== 'string' || !Object.hasOwn(fields, name))) fail();
+    if (kind === 'arrayErrors' && names.some(name => fields[name].type !== 'array')) fail();
   }
   for (const key of ['submitting', 'validating', 'formError']) if (selection[key] !== undefined && typeof selection[key] !== 'boolean') fail();
   return selection;
 }
-function assertValue(value, field) {
-  switch (field.type) {
-    case 'boolean': if (typeof value !== 'boolean') fail(); break;
-    case 'number': if (value !== null && (typeof value !== 'number' || !Number.isFinite(value))) fail(); break;
-    case 'plainDate': if (value !== null && !isPlainDate(value)) fail(); break;
-    case 'dateTime': if (value !== null && !isDateTime(value)) fail(); break;
-    case 'record': if (value !== null) assertRecordRef(value, recordObjectsForField(field)); break;
-    default: if (typeof value !== 'string' || value.length > 10000) fail();
-  }
-}
 export function assertFormStateSnapshot(snapshot, formId, fields, selection) {
-  assertJsonValue(snapshot);
+  assertJsonValue(snapshot, Object.values(fields).some(field => field.type === 'array') ? { maxBytes: ARRAY_LIMITS.messageBytes, maxEntries: 4096 } : undefined);
   assertFormStateSelection(selection, fields);
-  const keys = ['formId', 'revision', ...(selection.values !== undefined ? ['values'] : []), ...(selection.errors !== undefined ? ['errors'] : []), ...['submitting', 'validating', 'formError'].filter(key => selection[key]), ...(selection.validatingFields !== undefined ? ['validatingFields'] : [])];
+  const keys = ['formId', 'revision', ...(selection.values !== undefined ? ['values'] : []), ...(selection.errors !== undefined ? ['errors'] : []), ...['submitting', 'validating', 'formError'].filter(key => selection[key]), ...(selection.arrayErrors !== undefined ? ['arrayErrors'] : []), ...(selection.validatingFields !== undefined ? ['validatingFields'] : [])];
   only(snapshot, keys);
   if (Object.keys(snapshot).length !== keys.length || snapshot.formId !== formId || !Number.isSafeInteger(snapshot.revision) || snapshot.revision < 1) fail();
   if (selection.values !== undefined) {
     const names = selectedNames(selection.values, fields);
     only(snapshot.values, names);
     if (Object.keys(snapshot.values).length !== names.length) fail();
-    for (const name of names) assertValue(snapshot.values[name], fields[name]);
+    for (const name of names) assertFieldValue(snapshot.values[name], fields[name]);
   }
   if (selection.errors !== undefined) {
     only(snapshot.errors, selectedNames(selection.errors, fields));
-    for (const value of Object.values(snapshot.errors)) if (typeof value !== 'string' || !value || value.length > 4096) fail();
+    assertErrorTree(snapshot.errors, fields, snapshot.values);
   }
   for (const key of ['submitting', 'validating']) if (selection[key] && typeof snapshot[key] !== 'boolean') fail();
   if (selection.formError && snapshot.formError !== null && (typeof snapshot.formError !== 'string' || !snapshot.formError || snapshot.formError.length > 4096)) fail();
   if (selection.validatingFields !== undefined) {
     only(snapshot.validatingFields, selectedNames(selection.validatingFields, fields));
-    if (Object.values(snapshot.validatingFields).some(value => typeof value !== 'boolean')) fail();
+    assertErrorTree(snapshot.validatingFields, fields, snapshot.values, true);
   }
+  if (selection.arrayErrors !== undefined) { only(snapshot.arrayErrors, selectedNames(selection.arrayErrors, fields)); assertArrayErrors(snapshot.arrayErrors, fields); }
+  if (Object.values(fields).some(field => field.type === 'array') && formBytes(snapshot) > ARRAY_LIMITS.messageBytes) fail();
   return snapshot;
 }
 export function freezeFormState(value) {
@@ -58,11 +50,9 @@ export function freezeFormState(value) {
 }
 export function initialFormState(formId, fields, initialValues, selection) {
   const snapshot = { formId, revision: 1 };
-  if (selection.values !== undefined) snapshot.values = Object.fromEntries(selectedNames(selection.values, fields).map(name => {
-    const value = initialValues[name];
-    return [name, fields[name].type === 'dateTime' && value ? new Date(value).toISOString() : value && typeof value === 'object' ? { ...value } : value];
-  }));
+  if (selection.values !== undefined) { const values = normalizeFormValues(fields, initialValues); snapshot.values = Object.fromEntries(selectedNames(selection.values, fields).map(name => [name, values[name]])); }
   if (selection.errors !== undefined) snapshot.errors = {};
+  if (selection.arrayErrors !== undefined) snapshot.arrayErrors = {};
   for (const key of ['submitting', 'validating']) if (selection[key]) snapshot[key] = false;
   if (selection.formError) snapshot.formError = null;
   if (selection.validatingFields !== undefined) snapshot.validatingFields = {};

package/src/forms/validation.d.ts

@@ -2,8 +2,8 @@ export const VALIDATION_TIMEOUT_MS: 10000;
 export interface ValidationMetadata { fields: string[]; form: boolean; mode: 'onBlur' | 'onChange' | 'onSubmit'; }
 export interface ValidationRequest {
   formId: string; runId: number; reason: 'blur' | 'change' | 'submit';
-  values: Record<string, string | boolean | number | import("./record-options.js").RecordRef | null>; fields: string[]; includeForm: boolean;
+  values: Record<string, unknown>; fields: string[]; includeForm: boolean;
 }
-export interface ValidationResponse { formId: string; runId: number; fieldErrors: Record<string, string>; formError?: string; }
+export interface ValidationResponse { formId: string; runId: number; fieldErrors: Record<string, string | (Record<string, string> | null)[]>; arrayErrors?: Record<string, string>; formError?: string; }
 export function assertValidationMetadata(value: unknown, fields: Record<string, unknown>): ValidationMetadata;
-export function assertValidationResponse(value: unknown, request: Pick<ValidationRequest, 'formId' | 'runId'>, fields: Record<string, unknown>): ValidationResponse;
+export function assertValidationResponse(value: unknown, request: Pick<ValidationRequest, 'formId' | 'runId'> & { values?: Record<string, unknown> }, fields: Record<string, unknown>): ValidationResponse;

package/src/forms/validation.js

@@ -1,3 +1,4 @@
+import { assertFieldValue, assertArrayCapacity, assertErrorTree, assertArrayErrors, fieldAtPath, valueAtPath, rulePath, flattenErrors, nestErrors, formBytes, ARRAY_LIMITS } from './array-contract.js';
 import { freezeFormState } from './state.js';
 import { isDateTime, isPlainDate } from './values.js';
 import { assertRecordRef, recordObjectsForField } from './record-options.js';
@@ -10,16 +11,18 @@ const only = (value, keys) => {
 const validMessage = value => typeof value === 'string' && value.trim() && value.length <= 300;
 export function assertValidationMetadata(value, fields) {
   only(value, ['fields', 'form', 'mode']);
-  if (!Array.isArray(value.fields) || value.fields.length > 30 || new Set(value.fields).size !== value.fields.length
-    || value.fields.some(name => typeof name !== 'string' || !Object.hasOwn(fields, name))
+  if (!Array.isArray(value.fields) || value.fields.length > 69 || new Set(value.fields).size !== value.fields.length
+    || value.fields.some(name => { try { fieldAtPath(fields, typeof name === 'string' ? name.replace('[*]', '[0]') : name); return false; } catch { return true; } })
     || typeof value.form !== 'boolean' || !['onBlur', 'onChange', 'onSubmit'].includes(value.mode)) fail();
   return value;
 }
 export function assertValidationResponse(value, request, fields) {
-  only(value, ['formId', 'runId', 'fieldErrors', 'formError']);
+  only(value, ['formId', 'runId', 'fieldErrors', 'arrayErrors', 'formError']);
   if (value.formId !== request.formId || value.runId !== request.runId) fail();
-  only(value.fieldErrors, Object.keys(fields));
-  if (Object.values(value.fieldErrors).some(error => !validMessage(error)) || value.formError !== undefined && !validMessage(value.formError)) fail();
+  assertErrorTree(value.fieldErrors, fields, request.values, false, 300);
+  if (value.arrayErrors !== undefined) assertArrayErrors(value.arrayErrors, fields, 300);
+  if (value.formError !== undefined && !validMessage(value.formError)) fail();
+  if (Object.values(fields).some(field => field.type === 'array') && formBytes({ ...value, values: request.values }) > ARRAY_LIMITS.messageBytes - 32768) fail();
   return value;
 }
 function assertRequest(request, formId, fields, validators, validate) {
@@ -27,17 +30,12 @@ function assertRequest(request, formId, fields, validators, validate) {
   if (request.formId !== formId || !Number.isSafeInteger(request.runId) || request.runId < 1
     || !['blur', 'change', 'submit'].includes(request.reason) || typeof request.includeForm !== 'boolean'
     || request.includeForm && !validate || !Array.isArray(request.fields) || new Set(request.fields).size !== request.fields.length
-    || request.fields.some(name => !Object.hasOwn(validators, name))) fail();
+    || request.fields.length > 303 || request.fields.some(name => !Object.hasOwn(validators, rulePath(name)))) fail();
   only(request.values, Object.keys(fields));
   if (Object.keys(request.values).length !== Object.keys(fields).length) fail();
-  for (const [name, field] of Object.entries(fields)) {
-    const value = request.values[name];
-    if (field.type === 'boolean') { if (typeof value !== 'boolean') fail(); }
-    else if (field.type === 'record') { if (value !== null) assertRecordRef(value, recordObjectsForField(field)); }
-    else if (field.type === 'number') { if (value !== null && (typeof value !== 'number' || !Number.isFinite(value))) fail(); }
-    else if (['plainDate', 'dateTime'].includes(field.type)) { if (value !== null && !(field.type === 'plainDate' ? isPlainDate(value) : isDateTime(value))) fail(); }
-    else if (typeof value !== 'string' || value.length > 10000) fail();
-  }
+  for (const [name, field] of Object.entries(fields)) assertFieldValue(request.values[name], field);
+  assertArrayCapacity(fields, request.values);
+  for (const path of request.fields) if (valueAtPath(request.values, path) === undefined) fail();
 }
 export function createValidationCallback(formId, fields, validators, validate) {
   let busy = false;
@@ -47,16 +45,16 @@ export function createValidationCallback(formId, fields, validators, validate) {
     busy = true;
     const request = freezeFormState(structuredClone(input));
     let active = true, timer, position = 0;
-    const fieldErrors = {};
+    const fieldErrors = {}, arrayErrors = {};
     const runField = async () => {
       while (active && position < request.fields.length) {
-        const name = request.fields[position++], value = request.values[name];
-        if (!fields[name].required && (value === '' || value === null)) continue;
-        for (const validator of validators[name]) {
+        const name = request.fields[position++], value = valueAtPath(request.values, name), field = fieldAtPath(fields, name);
+        if (!field.required && (value === '' || value === null)) continue;
+        for (const validator of validators[rulePath(name)]) {
           if (!active) return;
           const error = await validator(value);
           if (!active) return;
-          if (error !== undefined) { if (!validMessage(error)) fail(); fieldErrors[name] = error; break; }
+          if (error !== undefined) { if (!validMessage(error)) fail(); (field.type === 'array' ? arrayErrors : fieldErrors)[name] = error; break; }
         }
       }
     };
@@ -67,13 +65,13 @@ export function createValidationCallback(formId, fields, validators, validate) {
           if (!active) return;
           const result = request.includeForm ? await validate(request.values) : undefined;
           if (!active) return;
-          if (result !== undefined) { only(result, ['fieldErrors', 'formError']); }
-          // 字段 custom 错误优先于跨字段错误。
-          const response = { formId, runId: request.runId, fieldErrors: { ...result?.fieldErrors, ...fieldErrors }, ...(result?.formError === undefined ? {} : { formError: result.formError }) };
-          if (result?.fieldErrors !== undefined) {
-            only(result.fieldErrors, Object.keys(fields));
-            if (Object.values(result.fieldErrors).some(error => !validMessage(error))) fail();
-          }
+          if (result !== undefined) { only(result, ['fieldErrors', 'arrayErrors', 'formError']); }
+          if (result?.fieldErrors !== undefined) assertErrorTree(result.fieldErrors, fields, request.values, false, 300);
+          if (result?.arrayErrors !== undefined) assertArrayErrors(result.arrayErrors, fields, 300);
+          // 每个叶子合并，不能用整行覆盖同一行其他字段的跨字段错误。
+          const arrays = { ...result?.arrayErrors, ...arrayErrors };
+          const response = { formId, runId: request.runId, fieldErrors: nestErrors({ ...flattenErrors(result?.fieldErrors), ...fieldErrors }),
+            ...(Object.keys(arrays).length ? { arrayErrors: arrays } : {}), ...(result?.formError === undefined ? {} : { formError: result.formError }) };
           return assertValidationResponse(response, request, fields);
         })(),
         new Promise((_, reject) => { timer = setTimeout(() => { active = false; reject(new Error('runtime_form_validation_timeout')); }, VALIDATION_TIMEOUT_MS); }),

package/src/ui/validation.js

@@ -1,7 +1,7 @@
 const fail = () => { throw new Error('runtime_ui_contract_invalid'); };
 
 /** 在序列化之前校验，避免 Date、非有限数字或 undefined 被 JSON 静默改写。 */
-export function assertJsonValue(value) {
+export function assertJsonValue(value, { maxBytes = 32 * 1024, maxEntries = 1000 } = {}) {
   const ancestors = new Set();
   let entries = 0;
   function visit(item, depth) {
@@ -14,7 +14,7 @@ export function assertJsonValue(value) {
     const keys = Reflect.ownKeys(item).filter(key => !array || key !== 'length');
     if (keys.some(key => typeof key !== 'string') || (array && keys.length !== item.length)) fail();
     entries += keys.length;
-    if (entries > 1000) fail();
+    if (entries > maxEntries) fail();
     ancestors.add(item);
     for (const key of keys) {
       const descriptor = Object.getOwnPropertyDescriptor(item, key);
@@ -24,7 +24,7 @@ export function assertJsonValue(value) {
     ancestors.delete(item);
   }
   visit(value, 0);
-  if (new TextEncoder().encode(JSON.stringify(value)).byteLength > 32 * 1024) fail();
+  if (new TextEncoder().encode(JSON.stringify(value)).byteLength > maxBytes) fail();
   return value;
 }