@vobs/forms 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 vobsjs
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/dist/index.d.ts

@@ -0,0 +1,296 @@
+/** @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>;

package/dist/index.js

@@ -0,0 +1,467 @@
+/** @license MIT
+ * Copyright (c) 2026 vobsjs
+ * @vobs/forms
+ */
+import { computed, effect, EffectScope, signal, } from '@vobs/reactivity';
+import { createRuntimeError, currentOwner, TranslationAdapterKey, } from '@vobs/runtime-core';
+/**
+ * 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 function resolveFormError(error, translate) {
+    if (typeof error === 'string')
+        return error;
+    if (error.message !== undefined)
+        return error.message;
+    if (translate !== undefined)
+        return translate(error.code, error.params);
+    return error.code;
+}
+/**
+ * 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 function defaultResolveFormError(error) {
+    return resolveFormError(error, (code, params) => code === 'forms.required' ? `${String(params?.label ?? 'Field')} is required` : code);
+}
+export function defineForm(schema) {
+    return schema;
+}
+export function createForm(schema, initialValues = {}, options = {}) {
+    const models = {};
+    const errors = {};
+    const touched = {};
+    const fields = {};
+    const names = Object.keys(schema.fields);
+    // When the user provides an explicit required message, required errors store a message snapshot
+    // (not re-translated on locale change); otherwise they store { code: 'forms.required', params: { label } },
+    // translated via the adapter at render time (locale-reactive, default English without an adapter).
+    const requiredMessage = options.messages?.required;
+    const resolveLabel = options.resolveLabel ?? resolveFormError;
+    const owner = options.owner ?? currentOwner();
+    // Form-specific EffectScope: internal computeds (values/required/disabled) belong to this scope,
+    // so dispose() stops the scope and releases all subscriptions; Owner disposal cascades automatically (registered via owner.own below).
+    const scope = new EffectScope({ label: 'vobs.form' });
+    // Server error table: written by applyServerErrors/setFieldErrors; validate does not silently overwrite
+    // until clearErrors()/reset(). Client validation errors take precedence; server errors surface when no client errors exist.
+    const serverErrors = new Map();
+    const writeFieldErrors = (name, messages) => {
+        const server = serverErrors.get(name);
+        if (messages.length > 0) {
+            errors[name].value = messages;
+        }
+        else if (server !== undefined && server.length > 0) {
+            errors[name].value = server;
+        }
+        else {
+            errors[name].value = [];
+        }
+        touched[name].value = true;
+    };
+    for (const name of names) {
+        const field = schema.fields[name];
+        const initialValue = readInitialValue(field.defaultValue, initialValues[name]);
+        const model = signal(initialValue);
+        const fieldErrors = signal([]);
+        const fieldTouched = signal(false);
+        models[name] = model;
+        errors[name] = fieldErrors;
+        touched[name] = fieldTouched;
+        fields[name] = createFieldController(name, field, model, fieldErrors, fieldTouched, () => readValuesFromModels(models, names), requiredMessage, resolveLabel, scope, (messages) => writeFieldErrors(name, messages));
+    }
+    const values = computed(() => readValuesFromModels(models, names), { scope });
+    const items = names.map((name) => fields[name]);
+    function validateField(name) {
+        assertActive();
+        return fields[name].validate().then((client) => {
+            const server = serverErrors.get(name);
+            if (server !== undefined && server.length > 0) {
+                return [...client, ...server];
+            }
+            return client;
+        });
+    }
+    let disposed = false;
+    const dispose = () => {
+        if (disposed)
+            return;
+        disposed = true;
+        scope.stop();
+    };
+    if (owner !== undefined) {
+        owner.own(dispose);
+    }
+    // Terminal semantics (aligned with kernel-runtime §1 Owner VOR502): operations after dispose must fail, not silently succeed.
+    const assertActive = () => {
+        if (disposed) {
+            throw createRuntimeError('VOR581', 'Form is disposed');
+        }
+    };
+    // validateOn='change': an effect watches each field model and only re-validates that field on change (microtask-debounced).
+    // Input is treated as touch (marks touched), matching the react-hook-form onChange pattern.
+    const validateOn = options.validateOn ?? 'submit';
+    if (validateOn === 'change') {
+        const pendingFields = new Set();
+        let scheduled = false;
+        const flushChangeValidate = () => {
+            scheduled = false;
+            if (disposed)
+                return;
+            const targets = [...pendingFields];
+            pendingFields.clear();
+            for (const name of targets) {
+                touched[name].value = true;
+                void validateField(name).catch(() => undefined);
+            }
+        };
+        for (const name of names) {
+            const model = models[name];
+            let skipFirst = true;
+            effect(() => {
+                void model.value;
+                if (skipFirst) {
+                    skipFirst = false; // first run during subscription is not a change
+                    return;
+                }
+                pendingFields.add(name);
+                if (!scheduled) {
+                    scheduled = true;
+                    queueMicrotask(flushChangeValidate);
+                }
+            }, { scope, flush: 'sync' });
+        }
+    }
+    const touchField = (name) => {
+        assertActive();
+        touched[name].value = true;
+        if (validateOn === 'blur') {
+            void validateField(name).catch(() => undefined);
+        }
+    };
+    return {
+        schema,
+        fields,
+        items,
+        models,
+        errors,
+        touched,
+        values,
+        readValues() {
+            assertActive();
+            return values.value;
+        },
+        setValues(values) {
+            assertActive();
+            for (const name of names) {
+                const value = values[name];
+                if (value !== undefined) {
+                    models[name].value = value;
+                    // User corrected the field value: its server error is now stale, clear it (does not block the next submit)
+                    if (serverErrors.has(name)) {
+                        serverErrors.delete(name);
+                        errors[name].value = [];
+                    }
+                }
+            }
+        },
+        reset(values = {}) {
+            assertActive();
+            serverErrors.clear();
+            for (const name of names) {
+                const field = schema.fields[name];
+                models[name].value = readInitialValue(field.defaultValue, values[name]);
+                errors[name].value = [];
+                touched[name].value = false;
+            }
+        },
+        async validate() {
+            assertActive();
+            // Batch validation: build one values snapshot for all fields, avoiding per-field O(n) rebuild → O(n²)
+            const snapshot = readValuesFromModels(models, names);
+            const results = await Promise.all(names.map((name) => {
+                const controller = fields[name];
+                return controller.validateWith !== undefined
+                    ? controller.validateWith(snapshot)
+                    : controller.validate();
+            }));
+            const hasClientErrors = results.flat().length > 0;
+            // Server errors survive client validation (not silently overwritten),
+            // but when the client has no errors, remaining server errors still make validate() fail.
+            const hasServerErrors = [...serverErrors.values()].some((list) => list.length > 0);
+            return !hasClientErrors && !hasServerErrors;
+        },
+        validateField,
+        setFieldErrors(name, messages) {
+            assertActive();
+            serverErrors.set(name, messages);
+            errors[name].value = messages;
+            touched[name].value = true;
+        },
+        applyServerErrors(errorMap) {
+            assertActive();
+            for (const name of names) {
+                const messages = errorMap[name];
+                if (messages === undefined)
+                    continue;
+                serverErrors.set(name, messages);
+                errors[name].value = messages;
+                touched[name].value = true;
+            }
+        },
+        clearErrors() {
+            assertActive();
+            serverErrors.clear();
+            for (const name of names) {
+                errors[name].value = [];
+            }
+        },
+        touchField,
+        dispose,
+    };
+}
+export function createFormRenderer(form, options = {}) {
+    const fields = {};
+    const items = form.items.map((field) => {
+        const item = createRenderItem(field, options.fields?.[field.name]);
+        fields[field.name] = item;
+        return item;
+    });
+    return {
+        form,
+        fields,
+        items,
+        errorSummary: computed(() => items.flatMap((item) => item.errors.value)),
+        async submit(callback) {
+            if (!(await form.validate()))
+                return false;
+            await callback(form.readValues());
+            return true;
+        },
+    };
+}
+export function createFormView(renderer, options) {
+    const resolveError = options.resolveError ?? defaultResolveFormError;
+    const resolveLabel = options.resolveLabel ?? resolveFormError;
+    const submitting = signal(false);
+    const fields = {};
+    const items = renderer.items.map((item) => {
+        const controlId = `${options.id}-${item.name}`;
+        const errorId = `${controlId}-error`;
+        const viewItem = {
+            ...item,
+            id: `${controlId}-field`,
+            labelId: `${controlId}-label`,
+            controlId,
+            errorId,
+            className: computed(() => fieldClassName(item)),
+            labelText: computed(() => resolveLabel(item.label)),
+            options: computed(() => item.options.map((option) => ({ ...option, label: resolveLabel(option.label) }))),
+            errorText: computed(() => item.errors.value.map((error) => resolveError(error)).join(' ')),
+            ariaDescribedBy: computed(() => (item.errors.value.length === 0 ? undefined : errorId)),
+            ariaInvalid: computed(() => (item.errors.value.length === 0 ? undefined : 'true')),
+            ariaRequired: computed(() => (item.required.value ? 'true' : undefined)),
+            ariaDisabled: computed(() => (item.disabled.value ? 'true' : undefined)),
+        };
+        fields[item.name] = viewItem;
+        return viewItem;
+    });
+    const errorSummaryId = `${options.id}-error-summary`;
+    return {
+        id: options.id,
+        renderer,
+        fields,
+        items,
+        className: computed(() => (submitting.value ? 'vobs-form vobs-form--submitting' : 'vobs-form')),
+        submitting,
+        errorSummaryId,
+        errorSummaryLabelId: `${errorSummaryId}-label`,
+        errorSummaryClass: 'vobs-form__error-summary',
+        errorSummary: computed(() => items.flatMap((item) => item.errors.value.map((error, index) => ({
+            id: `${errorSummaryId}-${item.name}-${index}`,
+            field: item.name,
+            controlId: item.controlId,
+            href: `#${item.controlId}`,
+            message: resolveError(error),
+        })))),
+        async submit(callback) {
+            if (submitting.value)
+                return false;
+            submitting.value = true;
+            try {
+                return await renderer.submit(callback);
+            }
+            finally {
+                submitting.value = false;
+            }
+        },
+    };
+}
+function createFieldController(name, field, model, errors, touched, readValues, requiredMessage, resolveLabel, scope, writeErrors) {
+    const context = () => ({ values: readValues() });
+    let validationVersion = 0;
+    return {
+        name,
+        label: field.label,
+        type: field.type ?? 'text',
+        model,
+        errors,
+        touched,
+        required: computed(() => readSwitch(field.required, context()), { scope }),
+        disabled: computed(() => readSwitch(field.disabled, context()), { scope }),
+        options: field.options ?? [],
+        async validate() {
+            const values = readValues();
+            if (this.validateWith !== undefined) {
+                return this.validateWith(values);
+            }
+            return validateFieldValue(field, model.value, { values }, requiredMessage, resolveLabel);
+        },
+        async validateWith(input) {
+            const version = ++validationVersion;
+            const messages = await validateFieldValue(field, model.value, { values: input }, requiredMessage, resolveLabel);
+            if (version !== validationVersion) {
+                return messages;
+            }
+            writeErrors(messages);
+            return messages;
+        },
+    };
+}
+async function validateFieldValue(field, value, context, requiredMessage, resolveLabel) {
+    const messages = [];
+    if (readSwitch(field.required, context) && isEmptyValue(value)) {
+        // Structured required error: translated via the adapter at render time (locale-reactive);
+        // stores a message snapshot when the user explicitly provides messages.required.
+        const label = resolveLabel(field.label);
+        messages.push(requiredMessage === undefined
+            ? { code: 'forms.required', params: { label } }
+            : { code: 'forms.required', message: requiredMessage(label), params: { label } });
+    }
+    const custom = await field.validate?.(value, context);
+    if (custom !== undefined) {
+        if (Array.isArray(custom)) {
+            messages.push(...custom);
+        }
+        else {
+            messages.push(custom);
+        }
+    }
+    return messages;
+}
+function readSwitch(value, context) {
+    return typeof value === 'function' ? value(context) : (value ?? false);
+}
+function readInitialValue(defaultValue, value) {
+    return value === undefined ? defaultValue : value;
+}
+function readValuesFromModels(models, names) {
+    const values = {};
+    for (const name of names) {
+        values[name] = models[name].value;
+    }
+    return values;
+}
+function isEmptyValue(value) {
+    if (value === null || value === undefined)
+        return true;
+    if (typeof value === 'string')
+        return value.trim() === '';
+    if (Array.isArray(value))
+        return value.length === 0;
+    return false;
+}
+function createRenderItem(field, options) {
+    const defaults = defaultRenderOptions(field.type);
+    return {
+        name: field.name,
+        label: field.label,
+        control: options?.control ?? defaults.control,
+        ...((options?.inputType ?? defaults.inputType === undefined)
+            ? {}
+            : { inputType: options?.inputType ?? defaults.inputType }),
+        slot: options?.slot ?? field.name,
+        field,
+        model: field.model,
+        errors: field.errors,
+        touched: field.touched,
+        required: field.required,
+        disabled: field.disabled,
+        options: field.options,
+    };
+}
+function defaultRenderOptions(type) {
+    switch (type) {
+        case 'checkbox':
+            return { control: 'checkbox' };
+        case 'custom':
+            return { control: 'custom' };
+        case 'date':
+            return { control: 'input', inputType: 'date' };
+        case 'number':
+            return { control: 'input', inputType: 'number' };
+        case 'select':
+            return { control: 'select' };
+        case 'textarea':
+            return { control: 'textarea' };
+        default:
+            return { control: 'input', inputType: 'text' };
+    }
+}
+function fieldClassName(item) {
+    const classes = ['vobs-field'];
+    if (item.required.value)
+        classes.push('vobs-field--required');
+    if (item.disabled.value)
+        classes.push('vobs-field--disabled');
+    if (item.errors.value.length > 0)
+        classes.push('vobs-field--invalid');
+    return classes.join(' ');
+}
+/**
+ * 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 function useForm(context, schema, options = {}) {
+    const adapter = context.maybeInject(TranslationAdapterKey);
+    // required errors are stored as { code: 'forms.required', params } and translated via the adapter at render time (locale-reactive);
+    // the adapter's required function is no longer injected at assembly (it would freeze into a message snapshot).
+    const messages = options.messages ?? {};
+    const resolveError = options.resolveError ??
+        (adapter !== undefined
+            ? (error) => resolveFormError(error, (code, params) => adapter.t(code, params))
+            : defaultResolveFormError);
+    const resolveLabel = options.resolveLabel ??
+        (adapter !== undefined
+            ? (label) => resolveFormError(label, (code, params) => adapter.t(code, params))
+            : resolveFormError);
+    const form = createForm(schema, options.initialValues, {
+        messages,
+        ...(options.owner === undefined ? {} : { owner: options.owner }),
+        ...(options.validateOn === undefined ? {} : { validateOn: options.validateOn }),
+        resolveLabel,
+    });
+    const renderer = createFormRenderer(form, options.renderer);
+    const view = createFormView(renderer, {
+        id: options.viewId ?? 'form',
+        resolveError,
+        resolveLabel,
+    });
+    return { form, renderer, view };
+}

package/package.json

@@ -0,0 +1,41 @@
+{
+  "name": "@vobs/forms",
+  "version": "0.1.0",
+  "description": "Schema-driven form state primitives for vobs.",
+  "type": "module",
+  "publishConfig": {
+    "access": "public"
+  },
+  "license": "MIT",
+  "author": "vobsjs",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/vobsjs/vobs.git",
+    "directory": "packages/features/forms"
+  },
+  "bugs": {
+    "url": "https://github.com/vobsjs/vobs/issues"
+  },
+  "homepage": "https://github.com/vobsjs/vobs#readme",
+  "dependencies": {
+    "@vobs/reactivity": "0.1.0",
+    "@vobs/runtime-core": "0.1.0"
+  },
+  "files": [
+    "dist"
+  ],
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "types": "./dist/index.d.ts",
+  "module": "./dist/index.js",
+  "main": "./dist/index.js",
+  "sideEffects": false,
+  "engines": {
+    "node": ">=20.19.0"
+  }
+}