@vobs/forms 0.3.0 → 1.1.0

package/dist/index.js

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