@elurjs/core 3.5.0

package/dist/lib/elur/form.d.cts

@@ -0,0 +1,283 @@
+import type { Signal } from "./reactivity.js";
+/**
+ * A validator function. Return an error string when invalid, or `null` /
+ * `undefined` when valid.
+ *
+ * `allValues` is provided when the validator runs inside `createForm`, enabling
+ * cross-field validation (e.g., "confirm password matches password").
+ *
+ * **Validators must be pure.** They are invoked reactively whenever the field
+ * value changes — potentially many times per keystroke in forms with
+ * cross-field rules — and may run inside computed signals that assume
+ * deterministic output. Do not perform I/O, mutate external state, or rely on
+ * `Date.now()` / `Math.random()` inside a validator. For asynchronous checks
+ * (uniqueness, server-side rules), submit the form and inject the result via
+ * {@link FormState.setErrors}.
+ */
+export type Validator<T, AllValues = unknown> = (value: T, allValues?: AllValues) => string | null | undefined;
+export declare function required(message?: string): Validator<unknown>;
+export declare function minLength(n: number, message?: string): Validator<string>;
+export declare function maxLength(n: number, message?: string): Validator<string>;
+export declare function pattern(regex: RegExp, message?: string): Validator<string>;
+export declare function email(message?: string): Validator<string>;
+export declare function min(n: number, message?: string): Validator<number>;
+export declare function max(n: number, message?: string): Validator<number>;
+/** Creates a typed custom validator compatible with `elurField` and `createForm`. */
+export declare function createValidator<T, AllValues = unknown>(fn: (value: T, allValues?: AllValues) => string | null | undefined): Validator<T, AllValues>;
+/** All built-in validators grouped as a namespace. Extensible via `extendValidators`. */
+export declare const validators: {
+    readonly required: typeof required;
+    readonly minLength: typeof minLength;
+    readonly maxLength: typeof maxLength;
+    readonly email: typeof email;
+    readonly pattern: typeof pattern;
+    readonly min: typeof min;
+    readonly max: typeof max;
+};
+/** Shape of the built-in `validators` namespace. Used as the base type for `extendValidators`. */
+export type ValidatorsBase = typeof validators;
+/**
+ * Merges custom validator factories into the built-in namespace.
+ * Returns a new object — the original is never mutated.
+ */
+export declare function extendValidators<E extends Record<string, (...args: any[]) => Validator<any>>>(base: ValidatorsBase, extensions: E): ValidatorsBase & E;
+/**
+ * Controls when validation errors become visible.
+ * - `"blur"` — after the field loses focus (default)
+ * - `"input"` — as soon as the user types
+ * - `"submit"` — only after the first submit attempt
+ */
+export type ValidateOn = "blur" | "input" | "submit";
+/** Public state of a single form field. */
+export interface FieldState<T> {
+    /** Current value — read/write signal. */
+    value: Signal<T>;
+    /** Error visible según validateOn. Para UI. */
+    readonly error: Signal<string | null>;
+    /**
+     * Error real, ignorando validateOn/touched/dirty.
+     * Para lógica de habilitación de botones, validez global, etc.
+     */
+    readonly rawError: Signal<string | null>;
+    /** True after the input has lost focus at least once. */
+    touched: Signal<boolean>;
+    /** True after the user has typed at least once. */
+    dirty: Signal<boolean>;
+    /** Attach to `@input` on any `<input>`, `<select>`, `<textarea>`. */
+    readonly onInput: (e: Event) => void;
+    /** Attach to `@blur`. */
+    readonly onBlur: () => void;
+    /** Reset to initial value and clear touched/dirty/error state. */
+    reset(): void;
+    /**
+     * Set the field value programmatically.
+     *
+     * @param value — new value for the field.
+     * @param options — control whether to touch/dirty the field and whether to force
+     *   validation visibility.
+     */
+    setValue(value: T, options?: {
+        shouldTouch?: boolean;
+        shouldDirty?: boolean;
+        shouldValidate?: boolean;
+    }): void;
+    /**
+     * @internal — inject an external error message (server / schema validator).
+     * The error clears automatically when the user next edits the field.
+     */
+    _setExternalError(msg: string | null): void;
+    /** @internal — force error visibility (e.g., on submit). */
+    _forceVisible(): void;
+    /** @internal — update the stored initial value so a later reset() returns here. */
+    _setInitialValue(value: T): void;
+    /** @internal — dispose computed signals. */
+    _dispose(): void;
+}
+/** Creates a standalone reactive form field with optional validators. */
+export declare function elurField<T, AllValues = unknown>(initialValue: T, fieldValidators?: Validator<T, AllValues>[], validateOn?: ValidateOn, getAllValues?: () => AllValues): FieldState<T>;
+/** Public state of a field array (dynamic list of field groups). */
+export interface FieldArrayState<T extends Record<string, unknown>> {
+    /** Reactive list of field group states. */
+    readonly fields: Signal<Array<{
+        [K in keyof T]: FieldState<T[K]>;
+    }>>;
+    /** Appends a new item to the end of the array. */
+    append(value: T): void;
+    /** Removes the item at the given index. */
+    remove(index: number): void;
+    /**
+     * Moves an item from `from` to `to` index.
+     * Items between the two positions shift to fill the gap.
+     */
+    move(from: number, to: number): void;
+    /** Replaces the item at the given index with new values. */
+    replace(index: number, value: T): void;
+    /** Number of items in the array. Reactive. */
+    readonly length: Signal<number>;
+    /** Replaces the whole array with a new list of items. */
+    setValues(items: T[]): void;
+    /** Patches existing items and appends any extras without touching untouched items. */
+    patchValues(items: Partial<T>[]): void;
+    /** Resets the array to its initial value, optionally updating that initial value. */
+    reset(items?: T[]): void;
+    /** @internal */
+    _dispose(): void;
+}
+/**
+ * Creates a reactive array of field groups for dynamic list forms.
+ *
+ * @example
+ * const items = elurFieldArray([{ name: "" }], {
+ *     name: [required()],
+ * });
+ * items.append({ name: "nuevo" });
+ * items.remove(0);
+ */
+export declare function elurFieldArray<T extends Record<string, unknown>>(initialItems: T[], fieldValidators?: {
+    [K in keyof T]?: Validator<T[K], unknown>[];
+}, validateOn?: ValidateOn): FieldArrayState<T>;
+/** Field-name map that supports top-level keys and dot-path nested keys. */
+export type FormFields<T extends Record<string, unknown>> = {
+    [K in keyof T]: FieldState<T[K]>;
+} & Record<string, FieldState<unknown>>;
+/** Map of field-name → error message for external validation results. */
+export type FieldErrors<T extends Record<string, unknown>> = {
+    [K in keyof T]?: string | null;
+} & Record<string, string | null | undefined>;
+/** Validators map supporting both top-level and dot-path keys. */
+export type FormValidators<T extends Record<string, unknown>> = {
+    [K in keyof T]?: Validator<T[K], T>[];
+} & Record<string, Validator<any, any>[] | undefined>;
+export type DeepPartial<T> = T extends object ? {
+    [P in keyof T]?: DeepPartial<T[P]>;
+} : T;
+export interface FormState<T extends Record<string, unknown>> {
+    /** Individual field states — access value, error, event handlers. */
+    fields: FormFields<T>;
+    /** Computed snapshot of all current field values. */
+    readonly values: Signal<T>;
+    /** Computed map of all currently visible field errors. */
+    readonly errors: Signal<FieldErrors<T>>;
+    /**
+     * True when no field has a *visible* error.
+     *
+     * Visibility follows `validateOn`, so this signal reflects what the user
+     * currently sees in the UI — not the underlying validity of the data.
+     * Use it to drive error summaries, banners, or any UI that should only
+     * react to errors the user has been shown.
+     *
+     * For enabling or disabling submit buttons, use {@link canSubmit} instead.
+     */
+    readonly valid: Signal<boolean>;
+    /**
+     * True when every per-field validator passes against the current values,
+     * regardless of `touched`, `dirty`, or `validateOn`.
+     *
+     * This is the signal to bind to submit buttons:
+     *
+     * ```ts
+     * <button disabled=${() => !form.canSubmit.value || form.isSubmitting.value}>
+     *   Save
+     * </button>
+     * ```
+     *
+     * Unlike {@link valid}, `canSubmit` does not depend on whether errors are
+     * currently visible — a pristine form with empty required fields starts
+     * as `false` and flips to `true` the moment all validators pass.
+     *
+     * External errors injected via {@link setErrors} also flip `canSubmit` to
+     * `false` until the user edits the affected field.
+     *
+     * **Note:** `canSubmit` does not execute `options.validate` (schema-level
+     * validators such as Zod). Schema validation runs only on submit, by design,
+     * to keep per-keystroke cost predictable. If you need a schema rule to
+     * affect `canSubmit` reactively, express it as a per-field validator in
+     * `options.validators` instead.
+     */
+    readonly canSubmit: Signal<boolean>;
+    /** True when at least one field has been modified. */
+    readonly dirty: Signal<boolean>;
+    /** True when at least one field has been touched (lost focus). */
+    readonly touched: Signal<boolean>;
+    /** True while the submit callback is executing (async-safe). */
+    readonly isSubmitting: Signal<boolean>;
+    /** Number of times the form has been submitted (including failed validations). */
+    readonly submitCount: Signal<number>;
+    /**
+     * Wraps a submit callback. Returned handler:
+     * 1. Calls `e.preventDefault()`
+     * 2. Increments `submitCount` and marks all fields as visible
+     * 3. Runs `options.validate` if provided (Zod, etc.)
+     * 4. Only calls `fn(values)` if all validations pass
+     * 5. Manages `isSubmitting` across async callbacks
+     */
+    handleSubmit(fn: (values: T) => void | Promise<void>): (e: Event) => void;
+    /**
+     * Reset all fields to their initial values. If `newInitialValues` is provided,
+     * it becomes the new baseline and subsequent reset() calls will use it.
+     */
+    reset(newInitialValues?: T): void;
+    /**
+     * Set a single field value by its path (top-level or nested dot-path).
+     */
+    setValue(path: string, value: unknown, options?: {
+        shouldTouch?: boolean;
+        shouldDirty?: boolean;
+        shouldValidate?: boolean;
+    }): void;
+    /**
+     * Set multiple field values at once.
+     *
+     * @param values — partial object with top-level and/or nested values.
+     * @param options — control whether to preserve existing touched/dirty/error state.
+     */
+    setValues(values: DeepPartial<T>, options?: {
+        keepDirty?: boolean;
+        keepTouched?: boolean;
+        keepErrors?: boolean;
+    }): void;
+    /**
+     * Inject external errors (e.g., from a server response) into specific fields.
+     * Each field's error clears automatically the next time the user edits it.
+     */
+    setErrors(errors: FieldErrors<T>): void;
+    /**
+     * Disposes all internal computed signals.
+     * Call in `onUnmount` when the form lives inside a component.
+     */
+    dispose(): void;
+}
+export interface FormOptions<T extends Record<string, unknown>> {
+    /** Per-field validators. Each validator receives `(value, allValues?)`. */
+    validators?: FormValidators<T>;
+    /**
+     * Controls when validation errors become visible.
+     * - `"blur"` — after the field loses focus (default)
+     * - `"input"` — as soon as the user types
+     * - `"submit"` — only after the first submit attempt
+     */
+    validateOn?: ValidateOn;
+    /**
+     * Optional schema-level validator — runs on submit after built-in validators pass.
+     * Return `null` / `undefined` if valid, or a field→error map if not.
+     * String arrays are accepted (first element shown per field).
+     *
+     * @example Zod interop
+     * ```typescript
+     * validate(values) {
+     *   const r = schema.safeParse(values);
+     *   if (r.success) return null;
+     *   return Object.fromEntries(
+     *     Object.entries(r.error.flatten().fieldErrors)
+     *           .map(([k, v]) => [k, v?.[0]])
+     *   );
+     * }
+     * ```
+     */
+    validate?: (values: T) => Record<string, string | string[] | null | undefined> | null | undefined;
+}
+/**
+ * Creates a managed form with reactive fields, built-in validation,
+ * schema-level validation (Zod/Valibot/Yup/custom), and submit handling.
+ */
+export declare function createForm<T extends Record<string, unknown>>(initialValues: T, options?: FormOptions<T>): FormState<T>;

package/dist/lib/elur/form.d.ts

@@ -0,0 +1,283 @@
+import type { Signal } from "./reactivity.js";
+/**
+ * A validator function. Return an error string when invalid, or `null` /
+ * `undefined` when valid.
+ *
+ * `allValues` is provided when the validator runs inside `createForm`, enabling
+ * cross-field validation (e.g., "confirm password matches password").
+ *
+ * **Validators must be pure.** They are invoked reactively whenever the field
+ * value changes — potentially many times per keystroke in forms with
+ * cross-field rules — and may run inside computed signals that assume
+ * deterministic output. Do not perform I/O, mutate external state, or rely on
+ * `Date.now()` / `Math.random()` inside a validator. For asynchronous checks
+ * (uniqueness, server-side rules), submit the form and inject the result via
+ * {@link FormState.setErrors}.
+ */
+export type Validator<T, AllValues = unknown> = (value: T, allValues?: AllValues) => string | null | undefined;
+export declare function required(message?: string): Validator<unknown>;
+export declare function minLength(n: number, message?: string): Validator<string>;
+export declare function maxLength(n: number, message?: string): Validator<string>;
+export declare function pattern(regex: RegExp, message?: string): Validator<string>;
+export declare function email(message?: string): Validator<string>;
+export declare function min(n: number, message?: string): Validator<number>;
+export declare function max(n: number, message?: string): Validator<number>;
+/** Creates a typed custom validator compatible with `elurField` and `createForm`. */
+export declare function createValidator<T, AllValues = unknown>(fn: (value: T, allValues?: AllValues) => string | null | undefined): Validator<T, AllValues>;
+/** All built-in validators grouped as a namespace. Extensible via `extendValidators`. */
+export declare const validators: {
+    readonly required: typeof required;
+    readonly minLength: typeof minLength;
+    readonly maxLength: typeof maxLength;
+    readonly email: typeof email;
+    readonly pattern: typeof pattern;
+    readonly min: typeof min;
+    readonly max: typeof max;
+};
+/** Shape of the built-in `validators` namespace. Used as the base type for `extendValidators`. */
+export type ValidatorsBase = typeof validators;
+/**
+ * Merges custom validator factories into the built-in namespace.
+ * Returns a new object — the original is never mutated.
+ */
+export declare function extendValidators<E extends Record<string, (...args: any[]) => Validator<any>>>(base: ValidatorsBase, extensions: E): ValidatorsBase & E;
+/**
+ * Controls when validation errors become visible.
+ * - `"blur"` — after the field loses focus (default)
+ * - `"input"` — as soon as the user types
+ * - `"submit"` — only after the first submit attempt
+ */
+export type ValidateOn = "blur" | "input" | "submit";
+/** Public state of a single form field. */
+export interface FieldState<T> {
+    /** Current value — read/write signal. */
+    value: Signal<T>;
+    /** Error visible según validateOn. Para UI. */
+    readonly error: Signal<string | null>;
+    /**
+     * Error real, ignorando validateOn/touched/dirty.
+     * Para lógica de habilitación de botones, validez global, etc.
+     */
+    readonly rawError: Signal<string | null>;
+    /** True after the input has lost focus at least once. */
+    touched: Signal<boolean>;
+    /** True after the user has typed at least once. */
+    dirty: Signal<boolean>;
+    /** Attach to `@input` on any `<input>`, `<select>`, `<textarea>`. */
+    readonly onInput: (e: Event) => void;
+    /** Attach to `@blur`. */
+    readonly onBlur: () => void;
+    /** Reset to initial value and clear touched/dirty/error state. */
+    reset(): void;
+    /**
+     * Set the field value programmatically.
+     *
+     * @param value — new value for the field.
+     * @param options — control whether to touch/dirty the field and whether to force
+     *   validation visibility.
+     */
+    setValue(value: T, options?: {
+        shouldTouch?: boolean;
+        shouldDirty?: boolean;
+        shouldValidate?: boolean;
+    }): void;
+    /**
+     * @internal — inject an external error message (server / schema validator).
+     * The error clears automatically when the user next edits the field.
+     */
+    _setExternalError(msg: string | null): void;
+    /** @internal — force error visibility (e.g., on submit). */
+    _forceVisible(): void;
+    /** @internal — update the stored initial value so a later reset() returns here. */
+    _setInitialValue(value: T): void;
+    /** @internal — dispose computed signals. */
+    _dispose(): void;
+}
+/** Creates a standalone reactive form field with optional validators. */
+export declare function elurField<T, AllValues = unknown>(initialValue: T, fieldValidators?: Validator<T, AllValues>[], validateOn?: ValidateOn, getAllValues?: () => AllValues): FieldState<T>;
+/** Public state of a field array (dynamic list of field groups). */
+export interface FieldArrayState<T extends Record<string, unknown>> {
+    /** Reactive list of field group states. */
+    readonly fields: Signal<Array<{
+        [K in keyof T]: FieldState<T[K]>;
+    }>>;
+    /** Appends a new item to the end of the array. */
+    append(value: T): void;
+    /** Removes the item at the given index. */
+    remove(index: number): void;
+    /**
+     * Moves an item from `from` to `to` index.
+     * Items between the two positions shift to fill the gap.
+     */
+    move(from: number, to: number): void;
+    /** Replaces the item at the given index with new values. */
+    replace(index: number, value: T): void;
+    /** Number of items in the array. Reactive. */
+    readonly length: Signal<number>;
+    /** Replaces the whole array with a new list of items. */
+    setValues(items: T[]): void;
+    /** Patches existing items and appends any extras without touching untouched items. */
+    patchValues(items: Partial<T>[]): void;
+    /** Resets the array to its initial value, optionally updating that initial value. */
+    reset(items?: T[]): void;
+    /** @internal */
+    _dispose(): void;
+}
+/**
+ * Creates a reactive array of field groups for dynamic list forms.
+ *
+ * @example
+ * const items = elurFieldArray([{ name: "" }], {
+ *     name: [required()],
+ * });
+ * items.append({ name: "nuevo" });
+ * items.remove(0);
+ */
+export declare function elurFieldArray<T extends Record<string, unknown>>(initialItems: T[], fieldValidators?: {
+    [K in keyof T]?: Validator<T[K], unknown>[];
+}, validateOn?: ValidateOn): FieldArrayState<T>;
+/** Field-name map that supports top-level keys and dot-path nested keys. */
+export type FormFields<T extends Record<string, unknown>> = {
+    [K in keyof T]: FieldState<T[K]>;
+} & Record<string, FieldState<unknown>>;
+/** Map of field-name → error message for external validation results. */
+export type FieldErrors<T extends Record<string, unknown>> = {
+    [K in keyof T]?: string | null;
+} & Record<string, string | null | undefined>;
+/** Validators map supporting both top-level and dot-path keys. */
+export type FormValidators<T extends Record<string, unknown>> = {
+    [K in keyof T]?: Validator<T[K], T>[];
+} & Record<string, Validator<any, any>[] | undefined>;
+export type DeepPartial<T> = T extends object ? {
+    [P in keyof T]?: DeepPartial<T[P]>;
+} : T;
+export interface FormState<T extends Record<string, unknown>> {
+    /** Individual field states — access value, error, event handlers. */
+    fields: FormFields<T>;
+    /** Computed snapshot of all current field values. */
+    readonly values: Signal<T>;
+    /** Computed map of all currently visible field errors. */
+    readonly errors: Signal<FieldErrors<T>>;
+    /**
+     * True when no field has a *visible* error.
+     *
+     * Visibility follows `validateOn`, so this signal reflects what the user
+     * currently sees in the UI — not the underlying validity of the data.
+     * Use it to drive error summaries, banners, or any UI that should only
+     * react to errors the user has been shown.
+     *
+     * For enabling or disabling submit buttons, use {@link canSubmit} instead.
+     */
+    readonly valid: Signal<boolean>;
+    /**
+     * True when every per-field validator passes against the current values,
+     * regardless of `touched`, `dirty`, or `validateOn`.
+     *
+     * This is the signal to bind to submit buttons:
+     *
+     * ```ts
+     * <button disabled=${() => !form.canSubmit.value || form.isSubmitting.value}>
+     *   Save
+     * </button>
+     * ```
+     *
+     * Unlike {@link valid}, `canSubmit` does not depend on whether errors are
+     * currently visible — a pristine form with empty required fields starts
+     * as `false` and flips to `true` the moment all validators pass.
+     *
+     * External errors injected via {@link setErrors} also flip `canSubmit` to
+     * `false` until the user edits the affected field.
+     *
+     * **Note:** `canSubmit` does not execute `options.validate` (schema-level
+     * validators such as Zod). Schema validation runs only on submit, by design,
+     * to keep per-keystroke cost predictable. If you need a schema rule to
+     * affect `canSubmit` reactively, express it as a per-field validator in
+     * `options.validators` instead.
+     */
+    readonly canSubmit: Signal<boolean>;
+    /** True when at least one field has been modified. */
+    readonly dirty: Signal<boolean>;
+    /** True when at least one field has been touched (lost focus). */
+    readonly touched: Signal<boolean>;
+    /** True while the submit callback is executing (async-safe). */
+    readonly isSubmitting: Signal<boolean>;
+    /** Number of times the form has been submitted (including failed validations). */
+    readonly submitCount: Signal<number>;
+    /**
+     * Wraps a submit callback. Returned handler:
+     * 1. Calls `e.preventDefault()`
+     * 2. Increments `submitCount` and marks all fields as visible
+     * 3. Runs `options.validate` if provided (Zod, etc.)
+     * 4. Only calls `fn(values)` if all validations pass
+     * 5. Manages `isSubmitting` across async callbacks
+     */
+    handleSubmit(fn: (values: T) => void | Promise<void>): (e: Event) => void;
+    /**
+     * Reset all fields to their initial values. If `newInitialValues` is provided,
+     * it becomes the new baseline and subsequent reset() calls will use it.
+     */
+    reset(newInitialValues?: T): void;
+    /**
+     * Set a single field value by its path (top-level or nested dot-path).
+     */
+    setValue(path: string, value: unknown, options?: {
+        shouldTouch?: boolean;
+        shouldDirty?: boolean;
+        shouldValidate?: boolean;
+    }): void;
+    /**
+     * Set multiple field values at once.
+     *
+     * @param values — partial object with top-level and/or nested values.
+     * @param options — control whether to preserve existing touched/dirty/error state.
+     */
+    setValues(values: DeepPartial<T>, options?: {
+        keepDirty?: boolean;
+        keepTouched?: boolean;
+        keepErrors?: boolean;
+    }): void;
+    /**
+     * Inject external errors (e.g., from a server response) into specific fields.
+     * Each field's error clears automatically the next time the user edits it.
+     */
+    setErrors(errors: FieldErrors<T>): void;
+    /**
+     * Disposes all internal computed signals.
+     * Call in `onUnmount` when the form lives inside a component.
+     */
+    dispose(): void;
+}
+export interface FormOptions<T extends Record<string, unknown>> {
+    /** Per-field validators. Each validator receives `(value, allValues?)`. */
+    validators?: FormValidators<T>;
+    /**
+     * Controls when validation errors become visible.
+     * - `"blur"` — after the field loses focus (default)
+     * - `"input"` — as soon as the user types
+     * - `"submit"` — only after the first submit attempt
+     */
+    validateOn?: ValidateOn;
+    /**
+     * Optional schema-level validator — runs on submit after built-in validators pass.
+     * Return `null` / `undefined` if valid, or a field→error map if not.
+     * String arrays are accepted (first element shown per field).
+     *
+     * @example Zod interop
+     * ```typescript
+     * validate(values) {
+     *   const r = schema.safeParse(values);
+     *   if (r.success) return null;
+     *   return Object.fromEntries(
+     *     Object.entries(r.error.flatten().fieldErrors)
+     *           .map(([k, v]) => [k, v?.[0]])
+     *   );
+     * }
+     * ```
+     */
+    validate?: (values: T) => Record<string, string | string[] | null | undefined> | null | undefined;
+}
+/**
+ * Creates a managed form with reactive fields, built-in validation,
+ * schema-level validation (Zod/Valibot/Yup/custom), and submit handling.
+ */
+export declare function createForm<T extends Record<string, unknown>>(initialValues: T, options?: FormOptions<T>): FormState<T>;