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

package/src/client/interactions.js

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

package/src/client/points.generated.js

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

package/src/forms/components.generated.js

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

package/src/forms/factory.js

@@ -1,23 +1,32 @@
+import { compileForm } from './schema.js';
+import { createWithState } from './state.js';
+import { useNormalizedRecordOptions, recordObjectsForField } from './record-options.js';
 import { boundComponents, formComponent } from './components.generated.js';
 import { useNormalizedOptions } from './normalize-options.js';
-export function createFormHook({ createElement, useId, useMemo, useRef }) {
+export function createFormHook(React, { useBindCallback = () => callback => callback } = {}) {
+const { createElement, useId, useMemo, useRef } = React;
 
 return function useForm(options) {
   const formId = useId();
+  const bindCallback = useBindCallback();
   const initial = useRef(options);
   return useMemo(() => {
-    const { schema, initialValues } = initial.current;
+    const { initialValues } = initial.current;
+    const { schema, ...validation } = compileForm(initial.current, formId, bindCallback);
     const field = type => function Field({ children, ...props }) {
-      if (type === 'Combobox') {
+      if (type === 'Combobox' || type === 'RecordCombobox') {
         const { options, ...rest } = props;
-        const normalized = useNormalizedOptions({ useRef, useMemo }, options);
+        const normalized = type === 'RecordCombobox'
+          ? useNormalizedRecordOptions({ useRef, useMemo }, options, recordObjectsForField(schema.fields[props.name]))
+          : useNormalizedOptions({ useRef, useMemo }, options);
         return createElement(type, { ...rest, ...normalized, formId });
       }
       return createElement(type, { ...props, formId }, children);
     };
     return Object.freeze({
+      WithState: createWithState(React, formId, schema, initialValues),
       Form: function Form({ children, onSubmit }) {
-        return createElement(formComponent, { formId, schema, initialValues, onSubmit }, children);
+        return createElement(formComponent, { formId, schema, initialValues, onSubmit, ...validation }, children);
       },
       ...Object.fromEntries(boundComponents.map(type => [type, field(type)])),
     });

package/src/forms/index.d.ts

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

package/src/forms/index.js

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

package/src/forms/options.d.ts

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

package/src/forms/options.js

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

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

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

package/src/forms/record-options.js

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

package/src/forms/schema.d.ts

@@ -1,10 +1,18 @@
-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>>; }
+  | { 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 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 : string;
+  [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 FieldName<S extends FormSchema, T extends FormField['type']> = {
   [K in keyof S['fields']]: S['fields'][K]['type'] extends T ? K : never;
@@ -16,3 +24,40 @@ export type FormSubmitResult<S extends FormSchema> = void | { ok: true } | {
   message: string;
   fieldErrors?: Partial<Record<Extract<keyof S['fields'], string>, string>>;
 };
+
+export type FormValidationResult<S extends FormSchema> = void | {
+  fieldErrors?: Partial<Record<Extract<keyof S['fields'], string>, string>>;
+  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, { type: FormField['type']; label: (text: string) => unknown }>>(fields: F): { readonly fields: 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,105 @@
+import { isPlainDate, isDateTime } from './values.js';
+import { recordObjectsForField } from './record-options.js';
+import { freezeFormState } from './state.js';
+import { createValidationCallback } from './validation.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 === '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 (['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 === '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 }),
+  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.keys(schema.fields).length > 30 || !['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();
+    const descriptor = descriptors.get(input);
+    const field = structuredClone(descriptor?.field ?? input);
+    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));
+  return { schema: wire, ...(configured ? { validation } : {}), ...(remote ? {
+    onValidate: createValidationCallback(formId, fields, validators, validate ? bindCallback(validate) : undefined),
+  } : {}) };
+}

package/src/forms/state.d.ts

@@ -0,0 +1,28 @@
+import type { ReactNode } from 'react';
+import type { FormSchema, FormValues } from './schema.js';
+export type FormStateSelection<S extends FormSchema> = {
+  values?: true | readonly (keyof S['fields'] & 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: Readonly<Partial<Record<Names<S, T>, string>>> } : {})
+  & (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>>> } : {});
+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 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;