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

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 }>;
 };

package/src/forms/schema.js

@@ -0,0 +1,128 @@
+import { isPlainDate, isDateTime } from './values.js';
+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 => {
+  if (typeof value !== 'string' || !value.trim() || value.length > 300) fail();
+  return value;
+};
+function builder(field, validators = []) {
+  field = freezeFormState(field);
+  const next = (patch, checks = validators) => builder({ ...field, ...patch }, checks);
+  const rule = (key, value, options) => {
+    const messages = { ...field.messages };
+    if (options !== undefined) {
+      if (!options || Object.keys(options).some(key => key !== 'message')) fail();
+      messages[key] = message(options.message);
+    } else delete messages[key];
+    return next({ [field.type === 'array' ? `${key}Items` : field.type === 'string' ? `${key}Length` : key]: value, messages });
+  };
+  const methods = {
+    label(value) { return next({ label: value }); },
+    required(value) { return next({ required: true, messages: { ...field.messages, ...(value === undefined ? {} : { required: message(value) }) } }); },
+    optional() { return next({ required: false }); },
+    custom(validator) {
+      if (typeof validator !== 'function' || validators.length >= 4) fail();
+      return next({}, [...validators, validator]);
+    },
+  };
+  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;
+    else { if (!options || Object.keys(options).some(key => key !== 'message')) fail(); messages.format = message(options.message); }
+    return next({ format, messages });
+  };
+  const result = Object.freeze({ ...field, ...methods });
+  descriptors.set(result, { field, validators });
+  return result;
+}
+export const Forms = Object.freeze({
+  schema(fields) {
+    if (!fields || typeof fields !== 'object' || Array.isArray(fields)) fail();
+    if (Object.values(fields).some(field => !descriptors.has(field))) fail();
+    return Object.freeze({ fields: Object.freeze({ ...fields }) });
+  },
+  ...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 }),
+});
+
+/** 只编译描述与回调；输入规则由 Host 单一校验器执行。 */
+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.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 (!validFieldKey(name)) fail();
+    const descriptor = descriptors.get(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'] : [])];
+    if (Object.keys(field).some(key => !allowed.includes(key)) || (field.required !== undefined && typeof field.required !== 'boolean')) fail();
+    if (field.messages !== undefined) {
+      if (!field.messages || typeof field.messages !== 'object' || Array.isArray(field.messages)
+        || Object.keys(field.messages).some(key => !['required', 'min', 'max', 'format'].includes(key))) fail();
+      Object.values(field.messages).forEach(message);
+    }
+    if (field.type === 'record') recordObjectsForField(field);
+    if (field.type === 'enum') {
+      if (!Array.isArray(field.options) || !field.options.length || field.options.length > 100) fail();
+      const seen = new Set();
+      for (const choice of field.options) {
+        if (!choice || Object.keys(choice).some(key => !['value', 'label', 'description'].includes(key)) || typeof choice.value !== 'string' || !choice.value || choice.value.length > 200 || seen.has(choice.value) || typeof choice.label !== 'string' || choice.label.length > 200) fail();
+        if (choice.description !== undefined && (typeof choice.description !== 'string' || choice.description.length > 300)) fail();
+        seen.add(choice.value);
+      }
+    }
+    const low = field.type === 'string' ? 'minLength' : 'min', high = field.type === 'string' ? 'maxLength' : 'max';
+    const valid = value => field.type === 'string' ? Number.isSafeInteger(value) && value >= 0 && value <= 10000
+      : field.type === 'number' ? typeof value === 'number' && Number.isFinite(value)
+        : field.type === 'plainDate' ? isPlainDate(value) : isDateTime(value);
+    for (const key of [low, high]) if (field[key] !== undefined && (!valid(field[key]) || key === 'maxLength' && field[key] === 0)) fail();
+    const comparable = value => field.type === 'dateTime' ? Date.parse(value) : value;
+    if (field[low] !== undefined && field[high] !== undefined && comparable(field[low]) > comparable(field[high])) fail();
+    if (field.format !== undefined && !['email', 'url'].includes(field.format)) fail();
+    fields[name] = field;
+    if (descriptor?.validators.length) validators[name] = descriptor.validators.map(bindCallback);
+  }
+  const wire = freezeFormState({ fields });
+  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));
+  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

@@ -0,0 +1,30 @@
+import type { ReactNode } from 'react';
+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;
+  validatingFields?: true | readonly (keyof S['fields'] & string)[];
+  formError?: boolean;
+};
+type Names<S extends FormSchema, T> = T extends true ? keyof FormValues<S> : T extends readonly (infer K)[] ? Extract<K, keyof FormValues<S>> : never;
+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: 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: 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 = { 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

@@ -0,0 +1,82 @@
+import { assertFieldValue, assertErrorTree, assertArrayErrors, normalizeFormValues, formBytes, ARRAY_LIMITS } from './array-contract.js';
+import { assertJsonValue } from '../ui/validation.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();
+};
+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', '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 > 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;
+}
+export function assertFormStateSnapshot(snapshot, formId, fields, selection) {
+  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.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) assertFieldValue(snapshot.values[name], fields[name]);
+  }
+  if (selection.errors !== undefined) {
+    only(snapshot.errors, selectedNames(selection.errors, fields));
+    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));
+    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) {
+  if (value && typeof value === 'object') { Object.values(value).forEach(freezeFormState); Object.freeze(value); }
+  return value;
+}
+export function initialFormState(formId, fields, initialValues, selection) {
+  const snapshot = { formId, revision: 1 };
+  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 = {};
+  assertFormStateSnapshot(snapshot, formId, fields, selection);
+  return snapshot;
+}
+export function createWithState({ createElement, Fragment, useMemo, useState, useRef }, formId, schema, initialValues) {
+  function Observer({ selection, children }) {
+    const revision = useRef(0);
+    const [snapshot, setSnapshot] = useState(() => initialFormState(formId, schema.fields, initialValues, selection));
+    const onState = useMemo(() => next => {
+      assertFormStateSnapshot(next, formId, schema.fields, selection);
+      if (next.revision <= revision.current) return;
+      revision.current = next.revision;
+      setSnapshot(freezeFormState(next));
+    }, []);
+    const { formId: _, revision: _revision, ...state } = snapshot;
+    return createElement(Fragment, null,
+      createElement('FormStateObserver', { formId, selection, onState }),
+      children(freezeFormState(state)));
+  }
+  return function WithState({ selection, children }) {
+    assertFormStateSelection(selection, schema.fields);
+    if (typeof children !== 'function') fail();
+    return createElement(Observer, { key: JSON.stringify(selection), selection, children });
+  };
+}

package/src/forms/validation.d.ts

@@ -0,0 +1,9 @@
+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, unknown>; fields: string[]; includeForm: boolean;
+}
+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'> & { values?: Record<string, unknown> }, fields: Record<string, unknown>): ValidationResponse;

package/src/forms/validation.js

@@ -0,0 +1,81 @@
+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';
+
+export const VALIDATION_TIMEOUT_MS = 10000;
+const fail = () => { throw new Error('runtime_form_validation_invalid'); };
+const only = (value, keys) => {
+  if (!value || typeof value !== 'object' || Array.isArray(value) || Object.keys(value).some(key => !keys.includes(key))) fail();
+};
+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 > 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', 'arrayErrors', 'formError']);
+  if (value.formId !== request.formId || value.runId !== request.runId) 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) {
+  only(request, ['formId', 'runId', 'reason', 'values', 'fields', 'includeForm']);
+  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.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)) 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;
+  return async input => {
+    assertRequest(input, formId, fields, validators, validate);
+    if (busy) fail();
+    busy = true;
+    const request = freezeFormState(structuredClone(input));
+    let active = true, timer, position = 0;
+    const fieldErrors = {}, arrayErrors = {};
+    const runField = async () => {
+      while (active && position < request.fields.length) {
+        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(); (field.type === 'array' ? arrayErrors : fieldErrors)[name] = error; break; }
+        }
+      }
+    };
+    try {
+      return await Promise.race([
+        (async () => {
+          await Promise.all([runField(), runField()]);
+          if (!active) return;
+          const result = request.includeForm ? await validate(request.values) : undefined;
+          if (!active) return;
+          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); }),
+      ]);
+    } finally { active = false; busy = false; clearTimeout(timer); }
+  };
+}

package/src/forms/values.d.ts

@@ -0,0 +1,5 @@
+export function isPlainDate(value: unknown): value is string;
+export function isDateTime(value: unknown): value is string;
+export function parseNumberDraft(value: unknown): { value: number | null; error?: string };
+export function instantToLocal(value: string | null): string;
+export function localToInstant(value: string): { value: string | null; error?: string };

package/src/forms/values.js

@@ -0,0 +1,38 @@
+/** 平台值格式，不包含业务字段规则或缺省时区。 */
+export function isPlainDate(value) {
+  if (typeof value !== 'string' || !/^\d{4}-\d{2}-\d{2}$/.test(value)) return false;
+  const [year, month, day] = value.split('-').map(Number);
+  const date = new Date(0);
+  date.setUTCFullYear(year, month - 1, day);
+  return year > 0 && date.getUTCFullYear() === year && date.getUTCMonth() === month - 1 && date.getUTCDate() === day;
+}
+export function isDateTime(value) {
+  if (typeof value !== 'string') return false;
+  const match = /^(\d{4}-\d{2}-\d{2})T(\d{2}):(\d{2})(?::(\d{2})(?:\.(\d{1,3}))?)?(Z|[+-]\d{2}:\d{2})$/.exec(value);
+  return Boolean(match && isPlainDate(match[1]) && +match[2] < 24 && +match[3] < 60 && +(match[4] ?? 0) < 60 && Number.isFinite(Date.parse(value)));
+}
+export function parseNumberDraft(value) {
+  if (value === null || value === '') return { value: null };
+  if (typeof value === 'number') return Number.isFinite(value) ? { value } : { value: null, error: '请输入有效数字' };
+  if (typeof value !== 'string' || value.length > 512 || !/^[+-]?(?:\d+(?:\.\d*)?|\.\d+)(?:[eE][+-]?\d+)?$/.test(value)) return { value: null, error: '请输入有效数字' };
+  const number = Number(value);
+  return Number.isFinite(number) ? { value: number } : { value: null, error: '请输入有效数字' };
+}
+const pad = value => String(value).padStart(2, '0');
+export function instantToLocal(value) {
+  if (!value) return '';
+  if (!isDateTime(value)) return value;
+  const date = new Date(value);
+  return `${String(date.getFullYear()).padStart(4, '0')}-${pad(date.getMonth() + 1)}-${pad(date.getDate())}T${pad(date.getHours())}:${pad(date.getMinutes())}`;
+}
+export function localToInstant(value) {
+  if (!value) return { value: null };
+  const match = /^(\d{4}-\d{2}-\d{2})T(\d{2}):(\d{2})$/.exec(value);
+  if (!match || !isPlainDate(match[1]) || +match[2] > 23 || +match[3] > 59) return { value: null, error: '请输入有效日期时间' };
+  const wall = new Date(value);
+  const utc = new Date(value + ':00.000Z').getTime();
+  const offsets = new Set([-36, 0, 36].map(hours => new Date(wall.getTime() + hours * 3600000).getTimezoneOffset()));
+  const candidates = [...offsets].map(offset => new Date(utc + offset * 60000).toISOString()).filter(instant => instantToLocal(instant) === value);
+  if (candidates.length !== 1) return { value: null, error: '该本地时间不存在或有歧义，请选择其他时间' };
+  return { value: candidates[0] };
+}

package/src/server/index.d.ts

@@ -221,6 +221,21 @@ export interface WorkspaceConnection {
 /** 同步读取当前执行的连接快照；未连接或暂不可用时抛出安全错误，不在 getter 内刷新。 */
 export function getWorkspaceConnection(): Readonly<WorkspaceConnection>;
 
+/** 当前 Server Function 调用者在当前 Workspace 内的成员快照。 */
+export interface CurrentUser {
+  /** Workspace 成员 ID；不是平台全局 User ID。 */
+  workspaceMemberId: string;
+  /** 当前 Workspace 中的显示名称。 */
+  displayName: string;
+  /** 当前 Workspace 中的主邮箱。 */
+  primaryEmailAddress: string | null;
+  /** 当前平台用户头像；未绑定平台用户时为空。 */
+  avatarUrl: string | null;
+}
+
+/** 同步读取当前调用者；Lifecycle、Webhook 等无人触发入口会抛出 current_user_unavailable。 */
+export function getCurrentUser(): Readonly<CurrentUser>;
+
 /** Server Function 的一期函数合同。 */
 export type ServerFunction<TArgs extends JsonValue[] = JsonValue[], TResult extends JsonValue = JsonValue> =
   (...args: TArgs) => Promise<TResult>;

package/src/server/index.js

@@ -153,6 +153,26 @@ export function getWorkspaceConnection() {
   });
 }
 
+export function getCurrentUser() {
+  const current = globalThis.ZHIKE_CURRENT_USER;
+  if (
+    !current ||
+    typeof current !== "object" ||
+    typeof current.workspaceMemberId !== "string" ||
+    typeof current.displayName !== "string"
+  ) {
+    const error = new Error("current_user_unavailable");
+    error.code = "current_user_unavailable";
+    throw error;
+  }
+  return Object.freeze({
+    workspaceMemberId: current.workspaceMemberId,
+    displayName: current.displayName,
+    primaryEmailAddress: typeof current.primaryEmailAddress === "string" ? current.primaryEmailAddress : null,
+    avatarUrl: typeof current.avatarUrl === "string" ? current.avatarUrl : null,
+  });
+}
+
 // 仅兼容已构建的旧 Bundle；新源码入口由 .server.ts 的默认 async 函数确定。
 export function defineServerFunction(handler) {
   if (typeof handler !== "function") {