@vobs/forms 0.3.0 → 1.1.0

package/src/plugin.ts

@@ -0,0 +1,22 @@
+import { createInjectionKey, type VobsPlugin } from '@vobs/vobs'
+import { createForm, type Form, type FormOptions } from './form'
+
+export interface FormsClient {
+  createForm<T extends object>(initialValues: T, options?: FormOptions<T>): Form<T>
+}
+
+export const FORMS_KEY = createInjectionKey<FormsClient>('vobs.forms')
+
+export interface FormsPluginOptions {
+  client?: FormsClient
+}
+
+export function formsPlugin(options: FormsPluginOptions = {}): VobsPlugin {
+  return {
+    name: '@vobs/forms',
+    version: '0.1.0',
+    install(context) {
+      context.provide(FORMS_KEY, options.client ?? { createForm })
+    }
+  }
+}

package/src/rules.ts

@@ -0,0 +1,62 @@
+import type { Validator } from './form'
+
+export const rules = {
+  required(value: unknown): string | null {
+    if (value === undefined || value === null || value === '') return '必填'
+    return null
+  },
+
+  email(value: unknown): string | null {
+    if (value === undefined || value === null || value === '') return null
+    return /^[^\s@]+@[^\s@]+\.[^\s@]+$/.test(String(value)) ? null : '邮箱格式错误'
+  },
+
+  phone(value: unknown): string | null {
+    if (value === undefined || value === null || value === '') return null
+    return /^1[3-9]\d{9}$/.test(String(value)) ? null : '手机号格式错误'
+  },
+
+  minLength(min: number): Validator<string | null | undefined, object> {
+    assertNonNegativeInteger(min, 'minLength')
+    return value => value === undefined || value === null || value.length >= min
+      ? null
+      : `至少 ${min} 个字符`
+  },
+
+  maxLength(max: number): Validator<string | null | undefined, object> {
+    assertNonNegativeInteger(max, 'maxLength')
+    return value => value === undefined || value === null || value.length <= max
+      ? null
+      : `最多 ${max} 个字符`
+  },
+
+  min(minimum: number): Validator<number | null | undefined, object> {
+    assertFiniteNumber(minimum, 'min')
+    return value => value === undefined || value === null || value >= minimum
+      ? null
+      : `不能小于 ${minimum}`
+  },
+
+  max(maximum: number): Validator<number | null | undefined, object> {
+    assertFiniteNumber(maximum, 'max')
+    return value => value === undefined || value === null || value <= maximum
+      ? null
+      : `不能大于 ${maximum}`
+  },
+
+  pattern(pattern: RegExp, message: string): Validator<string | null | undefined, object> {
+    return value => {
+      if (value === undefined || value === null || value === '') return null
+      pattern.lastIndex = 0
+      return pattern.test(value) ? null : message
+    }
+  }
+}
+
+function assertNonNegativeInteger(value: number, name: string): void {
+  if (!Number.isInteger(value) || value < 0) throw new Error(`Vobs forms: ${name} 必须是大于等于 0 的整数`)
+}
+
+function assertFiniteNumber(value: number, name: string): void {
+  if (!Number.isFinite(value)) throw new Error(`Vobs forms: ${name} 必须是有限数字`)
+}

package/dist/index.d.ts

@@ -1,296 +0,0 @@
-/** @license MIT
- * Copyright (c) 2026 vobsjs
- * @vobs/forms
- */
-import { type ReadonlySignal, type WritableSignal } from '@vobs/reactivity';
-import { type InjectionKey, type Owner } from '@vobs/runtime-core';
-export type FormFieldType = 'checkbox' | 'custom' | 'date' | 'number' | 'select' | 'text' | 'textarea';
-export type FormFieldRenderControl = 'checkbox' | 'custom' | 'input' | 'select' | 'textarea';
-export interface FormOption<Value> {
-    readonly label: FormLabel;
-    readonly value: Value;
-    readonly disabled?: boolean;
-}
-/** Render options (after view-layer translation): label is display text (re-translated reactively). */
-export interface FormRenderOption<Value> {
-    readonly label: string;
-    readonly value: Value;
-    readonly disabled?: boolean;
-}
-export interface FormFieldContext<Values extends FormValues> {
-    readonly values: Values;
-}
-/** Structured validation error params (aligned with TranslationAdapter.t params). */
-export type FormErrorParams = Readonly<Record<string, string | number | boolean | null | undefined>>;
-/**
- * Structured validation error: `{ code, message?, params? }`.
- * - `code`: stable identifier for i18n keys / automated assertions (independent of display text).
- * - `message`: already-translated display text (optional; preferred over adapter translation when present).
- * - `params`: interpolation params for `code` (`{name}` placeholders).
- * A plain string is equivalent to `{ code: string, message: string }` for backward compatibility.
- */
-export interface FormErrorCode {
-    readonly code: string;
-    readonly message?: string;
-    readonly params?: FormErrorParams;
-}
-/** Field validation error: a string (translated text) or a structured error. */
-export type FormError = string | FormErrorCode;
-/**
- * Field label: a static string or a structured translation descriptor (`{ code, message?, params? }`).
- * `{ code }` is translated via TranslationAdapter (view-layer labelText re-translates reactively),
- * isomorphic to FormError (reuses the FormErrorCode shape).
- */
-export type FormLabel = string | FormErrorCode;
-/**
- * Resolves a structured error into display text:
- * - strings are returned as-is;
- * - `{ code, message }` prefers `message`;
- * - when `message` is absent and `translate` is provided, `code` is translated (params passed through);
- * - when neither is available, falls back to the raw `code` (never throws or breaks rendering).
- */
-export declare function resolveFormError(error: FormError, translate?: (code: string, params?: FormErrorParams) => string): string;
-/**
- * Default error resolver (used when no TranslationAdapter is injected):
- * - `{ code: 'forms.required', params: { label } }` degrades to default English `"{label} is required"`;
- * - other `{code}` errors show the raw code (same semantics as resolveFormError).
- * When an adapter is present, useForm's injected resolver takes precedence (`forms.required` is translated via the i18n catalog).
- */
-export declare function defaultResolveFormError(error: FormError): string;
-export type FormRule<Value, Values extends FormValues> = (value: Value, context: FormFieldContext<Values>) => FormError | readonly FormError[] | undefined | Promise<FormError | readonly FormError[] | undefined>;
-export type FormSwitch<Values extends FormValues> = boolean | ((context: FormFieldContext<Values>) => boolean);
-export interface FormFieldSchema<Value, Values extends FormValues = FormValues> {
-    readonly label: FormLabel;
-    readonly defaultValue: Value;
-    readonly type?: FormFieldType;
-    readonly required?: FormSwitch<Values>;
-    readonly disabled?: FormSwitch<Values>;
-    readonly options?: readonly FormOption<Value>[];
-    readonly validate?: FormRule<Value, Values>;
-}
-export type FormFieldSchemaRecord = Readonly<Record<string, FormFieldSchema<unknown>>>;
-export type FormFieldValue<T> = T extends string ? string : T extends number ? number : T extends boolean ? boolean : T;
-export type FormValues<Fields extends FormFieldSchemaRecord = FormFieldSchemaRecord> = {
-    readonly [Name in keyof Fields]: FormFieldValue<Fields[Name]['defaultValue']>;
-};
-export type FormModels<Fields extends FormFieldSchemaRecord> = {
-    readonly [Name in keyof Fields]: WritableSignal<FormValues<Fields>[Name]>;
-};
-export type FormErrors<Fields extends FormFieldSchemaRecord> = {
-    readonly [Name in keyof Fields]: WritableSignal<readonly FormError[]>;
-};
-export type FormTouched<Fields extends FormFieldSchemaRecord> = {
-    readonly [Name in keyof Fields]: WritableSignal<boolean>;
-};
-export interface FormFieldController<Name extends string = string, Value = unknown> {
-    readonly name: Name;
-    readonly label: FormLabel;
-    readonly type: FormFieldType;
-    readonly model: WritableSignal<Value>;
-    readonly errors: WritableSignal<readonly FormError[]>;
-    readonly touched: WritableSignal<boolean>;
-    readonly required: ReadonlySignal<boolean>;
-    readonly disabled: ReadonlySignal<boolean>;
-    readonly options: readonly FormOption<Value>[];
-    validate(): Promise<readonly FormError[]>;
-    /** @internal Batch validation entry: receives a values snapshot to avoid per-field O(n) rebuild (used internally by validate()). */
-    validateWith?(values: FormValues): Promise<readonly FormError[]>;
-}
-export type FormFieldControllers<Fields extends FormFieldSchemaRecord> = {
-    readonly [Name in keyof Fields & string]: FormFieldController<Name, FormValues<Fields>[Name]>;
-};
-export interface FormSchema<Fields extends FormFieldSchemaRecord> {
-    readonly fields: Fields;
-}
-export interface FormMessages {
-    readonly required?: (label: string) => string;
-}
-/** Auto re-validation mode: submit (default, validates only on submit) / change (validates on field change, microtask-debounced) / blur (validates after view-layer touchField bridge). */
-export type FormValidateOn = 'submit' | 'change' | 'blur';
-export interface FormOptions {
-    readonly messages?: FormMessages;
-    /** Owner the form belongs to (default currentOwner, i.e. the page Owner inside page setup); form state is released when the Owner is disposed. */
-    readonly owner?: Owner;
-    /** Auto re-validation mode (default 'submit'). 'change' is driven by an internal effect watching field changes; 'blur' requires the view layer to call touchField. */
-    readonly validateOn?: FormValidateOn;
-    /**
-     * Field label resolver (default: strings pass through; `{code, message}` prefers message, falls back to code).
-     * useForm automatically supplies a resolver that translates code via TranslationAdapter; overridable.
-     * Used for the `{label}` interpolation param in required messages.
-     */
-    readonly resolveLabel?: (label: FormLabel) => string;
-}
-export interface FormInstance<Fields extends FormFieldSchemaRecord> {
-    readonly schema: FormSchema<Fields>;
-    readonly fields: FormFieldControllers<Fields>;
-    readonly items: readonly FormFieldControllers<Fields>[keyof FormFieldControllers<Fields>][];
-    readonly models: FormModels<Fields>;
-    readonly errors: FormErrors<Fields>;
-    readonly touched: FormTouched<Fields>;
-    readonly values: ReadonlySignal<FormValues<Fields>>;
-    readValues(): FormValues<Fields>;
-    setValues(values: Partial<FormValues<Fields>>): void;
-    reset(values?: Partial<FormValues<Fields>>): void;
-    validate(): Promise<boolean>;
-    validateField<Name extends keyof Fields & string>(name: Name): Promise<readonly FormError[]>;
-    /** Sets errors for a single field (e.g. server error write-back); marks it touched. Accepts strings or `{code, message?}` structured errors. */
-    setFieldErrors<Name extends keyof Fields & string>(name: Name, errors: readonly FormError[]): void;
-    /** Batch-writes server validation errors: field name → error array (strings or `{code}`). Server errors are not silently overwritten by later client validation until clearErrors()/reset(). */
-    applyServerErrors(errors: Partial<Record<keyof Fields & string, readonly FormError[]>>): void;
-    /** Clears all field errors (including server errors). Call after a successful submit. */
-    clearErrors(): void;
-    /** Marks a field as touched (bridged from view-layer blur events; validates afterwards when validateOn='blur'). */
-    touchField<Name extends keyof Fields & string>(name: Name): void;
-    /** Releases form state and subscriptions (idempotent). Called automatically on Owner disposal. */
-    dispose(): void;
-}
-export interface FormFieldRenderOptions {
-    readonly control?: FormFieldRenderControl;
-    readonly inputType?: string;
-    readonly slot?: string;
-}
-export interface FormRendererOptions<Fields extends FormFieldSchemaRecord> {
-    readonly fields?: Partial<Record<keyof Fields & string, FormFieldRenderOptions>>;
-}
-export type FormFieldRenderControlFor<Field extends FormFieldSchema<unknown>> = Field extends {
-    readonly type: 'checkbox';
-} ? 'checkbox' : Field extends {
-    readonly type: 'custom';
-} ? 'custom' : Field extends {
-    readonly type: 'select';
-} ? 'select' : Field extends {
-    readonly type: 'textarea';
-} ? 'textarea' : 'input';
-export interface FormFieldRenderItem<Name extends string = string, Value = unknown, Control extends FormFieldRenderControl = FormFieldRenderControl> {
-    readonly name: Name;
-    readonly label: FormLabel;
-    readonly control: Control;
-    readonly inputType?: string;
-    readonly slot: string;
-    readonly field: FormFieldController<Name, Value>;
-    readonly model: WritableSignal<Value>;
-    readonly errors: WritableSignal<readonly FormError[]>;
-    readonly touched: WritableSignal<boolean>;
-    readonly required: ReadonlySignal<boolean>;
-    readonly disabled: ReadonlySignal<boolean>;
-    readonly options: readonly FormOption<Value>[];
-}
-export type FormFieldRenderItems<Fields extends FormFieldSchemaRecord> = {
-    readonly [Name in keyof Fields & string]: FormFieldRenderItem<Name, FormValues<Fields>[Name], FormFieldRenderControlFor<Fields[Name]>>;
-};
-export interface FormRenderer<Fields extends FormFieldSchemaRecord> {
-    readonly form: FormInstance<Fields>;
-    readonly fields: FormFieldRenderItems<Fields>;
-    readonly items: readonly FormFieldRenderItems<Fields>[keyof FormFieldRenderItems<Fields>][];
-    readonly errorSummary: ReadonlySignal<readonly FormError[]>;
-    submit(callback: (values: FormValues<Fields>) => void | Promise<void>): Promise<boolean>;
-}
-export interface FormViewOptions {
-    readonly id: string;
-    /**
-     * Resolves structured errors (`{code, message}`) into display text.
-     * Default: strings pass through; `{code, message}` prefers message, falls back to code.
-     * useForm automatically supplies a resolver that translates code via TranslationAdapter; overridable.
-     */
-    readonly resolveError?: (error: FormError) => string;
-    /**
-     * Field label resolver (default: same semantics as resolveError).
-     * useForm automatically supplies a resolver that translates code via TranslationAdapter; drives the labelText signal.
-     */
-    readonly resolveLabel?: (label: FormLabel) => string;
-}
-export interface FormErrorSummaryItem<Name extends string = string> {
-    readonly id: string;
-    readonly field: Name;
-    readonly controlId: string;
-    readonly href: string;
-    readonly message: string;
-}
-export interface FormFieldViewItem<Name extends string = string, Value = unknown, Control extends FormFieldRenderControl = FormFieldRenderControl> extends Omit<FormFieldRenderItem<Name, Value, Control>, 'options'> {
-    readonly id: string;
-    readonly labelId: string;
-    readonly controlId: string;
-    readonly errorId: string;
-    readonly className: ReadonlySignal<string>;
-    /** Display text for the field label (`{code}` labels re-translate reactively via TranslationAdapter). */
-    readonly labelText: ReadonlySignal<string>;
-    /** Display options list (`{code}` option labels re-translate reactively via TranslationAdapter; `#for` template iteration auto-unwraps). */
-    readonly options: ReadonlySignal<readonly FormRenderOption<Value>[]>;
-    readonly errorText: ReadonlySignal<string>;
-    readonly ariaDescribedBy: ReadonlySignal<string | undefined>;
-    readonly ariaInvalid: ReadonlySignal<'true' | undefined>;
-    readonly ariaRequired: ReadonlySignal<'true' | undefined>;
-    readonly ariaDisabled: ReadonlySignal<'true' | undefined>;
-}
-export type FormFieldViewItems<Fields extends FormFieldSchemaRecord> = {
-    readonly [Name in keyof Fields & string]: FormFieldViewItem<Name, FormValues<Fields>[Name], FormFieldRenderControlFor<Fields[Name]>>;
-};
-export interface FormView<Fields extends FormFieldSchemaRecord> {
-    readonly id: string;
-    readonly renderer: FormRenderer<Fields>;
-    readonly fields: FormFieldViewItems<Fields>;
-    readonly items: readonly FormFieldViewItems<Fields>[keyof FormFieldViewItems<Fields>][];
-    readonly className: ReadonlySignal<string>;
-    readonly submitting: ReadonlySignal<boolean>;
-    readonly errorSummaryId: string;
-    readonly errorSummaryLabelId: string;
-    readonly errorSummaryClass: string;
-    readonly errorSummary: ReadonlySignal<readonly FormErrorSummaryItem<keyof Fields & string>[]>;
-    submit(callback: (values: FormValues<Fields>) => void | Promise<void>): Promise<boolean>;
-}
-export declare function defineForm<const Fields extends FormFieldSchemaRecord>(schema: FormSchema<Fields>): FormSchema<Fields>;
-export declare function createForm<const Fields extends FormFieldSchemaRecord>(schema: FormSchema<Fields>, initialValues?: Partial<FormValues<Fields>>, options?: FormOptions): FormInstance<Fields>;
-export declare function createFormRenderer<const Fields extends FormFieldSchemaRecord>(form: FormInstance<Fields>, options?: FormRendererOptions<Fields>): FormRenderer<Fields>;
-export declare function createFormView<const Fields extends FormFieldSchemaRecord>(renderer: FormRenderer<Fields>, options: FormViewOptions): FormView<Fields>;
-/**
- * The injection capability subset useForm needs (structurally compatible with ComponentSetupContext/PageSetupContext maybeInject).
- * forms does not depend on the di package: it only consumes runtime-core's public port (TranslationAdapterKey).
- */
-export interface FormInjectionHost {
-    maybeInject<T>(key: InjectionKey<T>): T | undefined;
-}
-export interface FormSetupOptions<Fields extends FormFieldSchemaRecord> {
-    readonly initialValues?: Partial<FormValues<Fields>>;
-    /** Validation message localization. When required is not provided, the injected TranslationAdapter wires i18n (key: forms.required, param {label}); without an injection, default English is used. */
-    readonly messages?: FormMessages;
-    /** Owner the form belongs to (default currentOwner, i.e. the page Owner inside page setup). */
-    readonly owner?: Owner;
-    /** Auto re-validation mode (default 'submit'). */
-    readonly validateOn?: FormValidateOn;
-    /** Renderer configuration (field control/slot overrides). */
-    readonly renderer?: FormRendererOptions<Fields>;
-    /** View id (DOM id prefix, default 'form'). */
-    readonly viewId?: string;
-    /**
-     * Structured error resolver (default: `{code}` translated via the injected TranslationAdapter,
-     * `message` preferred, raw code shown without an adapter). Overridable.
-     */
-    readonly resolveError?: (error: FormError) => string;
-    /**
-     * Field label resolver (default: `{code}` labels translated via the injected TranslationAdapter,
-     * driving view.labelText and the `{label}` interpolation in required messages). Overridable.
-     */
-    readonly resolveLabel?: (label: FormLabel) => string;
-}
-export interface FormSetup<Fields extends FormFieldSchemaRecord> {
-    readonly form: FormInstance<Fields>;
-    readonly renderer: FormRenderer<Fields>;
-    readonly view: FormView<Fields>;
-}
-/**
- * Composition API: single entry to create the form trio (form + renderer + view), replacing three manual calls.
- *
- * Called in page/component setup:
- * ```ts
- * const { form, view } = useForm(context, schema);
- * await view.submit(async (values) => { ... });
- * form.applyServerErrors(serverErrors);   // server error write-back
- * ```
- *
- * Automatic behavior:
- * - Owner ownership: calls inside setup join the page Owner tree; page disposal cascades release (no manual dispose)
- * - i18n integration: the injected TranslationAdapter (active after provideI18n assembly) localizes required messages
- *   and translates `{code}` structured errors into display text (reactively re-translated on locale change);
- *   explicit messages.required / resolveError win; without injection, default English / raw code is shown
- */
-export declare function useForm<const Fields extends FormFieldSchemaRecord>(context: FormInjectionHost, schema: FormSchema<Fields>, options?: FormSetupOptions<Fields>): FormSetup<Fields>;