@bquery/bquery 1.6.0 → 1.8.1

package/dist/forms/index.d.ts

@@ -0,0 +1,40 @@
+/**
+ * Form handling module for bQuery.js.
+ *
+ * Provides a reactive, TypeScript-first form API with field-level
+ * and cross-field validation, dirty/touched tracking, and submission
+ * handling — all backed by bQuery's signal-based reactivity system.
+ *
+ * @module bquery/forms
+ *
+ * @example
+ * ```ts
+ * import { createForm, required, email, min } from '@bquery/bquery/forms';
+ *
+ * const form = createForm({
+ *   fields: {
+ *     name:  { initialValue: '', validators: [required()] },
+ *     email: { initialValue: '', validators: [required(), email()] },
+ *     age:   { initialValue: 0,  validators: [min(18, 'Must be 18+')] },
+ *   },
+ *   onSubmit: async (values) => {
+ *     await fetch('/api/register', {
+ *       method: 'POST',
+ *       body: JSON.stringify(values),
+ *     });
+ *   },
+ * });
+ *
+ * // Reactive access
+ * console.log(form.isValid.value);          // boolean
+ * console.log(form.fields.name.error.value); // '' or error message
+ *
+ * // Submit
+ * await form.handleSubmit();
+ * ```
+ */
+export { createForm } from './create-form';
+export { useFormField } from './use-field';
+export { custom, customAsync, email, matchField, max, maxLength, min, minLength, pattern, required, url, } from './validators';
+export type { AsyncValidator, CrossFieldValidator, FieldConfig, Form, FormConfig, FormErrors, FormField, FormFieldValidationMode, FormFields, SubmitHandler, SyncValidator, UseFormFieldOptions, UseFormFieldReturn, ValidationResult, Validator, } from './types';
+//# sourceMappingURL=index.d.ts.map

package/dist/forms/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/forms/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAkCG;AAEH,OAAO,EAAE,UAAU,EAAE,MAAM,eAAe,CAAC;AAC3C,OAAO,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAE3C,OAAO,EACL,MAAM,EACN,WAAW,EACX,KAAK,EACL,UAAU,EACV,GAAG,EACH,SAAS,EACT,GAAG,EACH,SAAS,EACT,OAAO,EACP,QAAQ,EACR,GAAG,GACJ,MAAM,cAAc,CAAC;AAEtB,YAAY,EACV,cAAc,EACd,mBAAmB,EACnB,WAAW,EACX,IAAI,EACJ,UAAU,EACV,UAAU,EACV,SAAS,EACT,uBAAuB,EACvB,UAAU,EACV,aAAa,EACb,aAAa,EACb,mBAAmB,EACnB,kBAAkB,EAClB,gBAAgB,EAChB,SAAS,GACV,MAAM,SAAS,CAAC"}

package/dist/forms/types.d.ts

@@ -0,0 +1,185 @@
+/**
+ * Form module types and interfaces.
+ *
+ * @module bquery/forms
+ */
+import type { Computed, Signal } from '../reactive/index';
+/**
+ * Result of a single validation rule.
+ * A string indicates an error message; `true` or `undefined` means valid.
+ */
+export type ValidationResult = string | true | undefined;
+/**
+ * Synchronous validator function.
+ *
+ * @param value - The current field value
+ * @returns A validation result — `true` / `undefined` for valid, or an error string
+ */
+export type SyncValidator<T = unknown> = (value: T) => ValidationResult;
+/**
+ * Asynchronous validator function.
+ *
+ * @param value - The current field value
+ * @returns A promise resolving to a validation result
+ */
+export type AsyncValidator<T = unknown> = (value: T) => Promise<ValidationResult>;
+/**
+ * Either a sync or async validator.
+ */
+export type Validator<T = unknown> = SyncValidator<T> | AsyncValidator<T>;
+/**
+ * Configuration for a single form field.
+ *
+ * @template T - The type of the field value
+ */
+export type FieldConfig<T = unknown> = {
+    /** Initial value for this field */
+    initialValue: T;
+    /** Validation rules applied in order; stops at first failure */
+    validators?: Validator<T>[];
+};
+/**
+ * Reactive state for a single form field.
+ *
+ * @template T - The type of the field value
+ */
+export type FormField<T = unknown> = {
+    /** Reactive signal holding the current value */
+    value: Signal<T>;
+    /** Reactive signal for the first validation error (empty string when valid) */
+    error: Signal<string>;
+    /** Whether the field value differs from its initial value */
+    isDirty: Computed<boolean>;
+    /** Whether the field has been interacted with (blur / explicit touch) */
+    isTouched: Signal<boolean>;
+    /** Whether the field has never been modified */
+    isPristine: Computed<boolean>;
+    /** Mark the field as touched */
+    touch: () => void;
+    /** Reset the field to its initial value and clear errors */
+    reset: () => void;
+};
+/**
+ * Controls when {@link useFormField} runs validation automatically.
+ */
+export type FormFieldValidationMode = 'manual' | 'change' | 'blur' | 'both';
+/**
+ * Configuration for {@link useFormField}.
+ *
+ * @template T - The type of the field value
+ */
+export type UseFormFieldOptions<T = unknown> = {
+    /** Validation rules applied in order; stops at first failure */
+    validators?: Validator<T>[];
+    /** When validation should run automatically. Defaults to `'manual'`. */
+    validateOn?: FormFieldValidationMode;
+    /** Delay automatic validation by the given milliseconds. Defaults to `0`. */
+    debounceMs?: number;
+    /** Initial error message for the field. Defaults to an empty string. */
+    initialError?: string;
+};
+/**
+ * Return value of {@link useFormField}.
+ *
+ * Extends the standard field state with validation helpers for standalone field usage.
+ *
+ * @template T - The type of the field value
+ */
+export type UseFormFieldReturn<T = unknown> = FormField<T> & {
+    /** Whether the current field has no validation error */
+    isValid: Computed<boolean>;
+    /** Reactive signal: `true` while async validation is still running */
+    isValidating: Signal<boolean>;
+    /** Validate the current field value immediately */
+    validate: () => Promise<boolean>;
+    /** Cancel pending timers and automatic validation subscriptions */
+    destroy: () => void;
+};
+/**
+ * Map of field names to their reactive field state.
+ */
+export type FormFields<T extends Record<string, unknown>> = {
+    [K in keyof T]: FormField<T[K]>;
+};
+/**
+ * Map of field names to their error strings (reactive signals).
+ */
+export type FormErrors<T extends Record<string, unknown>> = {
+    [K in keyof T]: Signal<string>;
+};
+/**
+ * Cross-field validation function.
+ * Receives all current field values and returns a map of field name → error message,
+ * or an empty object / undefined if all fields are valid.
+ */
+export type CrossFieldValidator<T extends Record<string, unknown>> = (values: T) => Partial<Record<keyof T, string>> | undefined | Promise<Partial<Record<keyof T, string>> | undefined>;
+/**
+ * Submit handler function.
+ *
+ * @template T - Shape of the form values
+ */
+export type SubmitHandler<T extends Record<string, unknown>> = (values: T) => void | Promise<void>;
+/**
+ * Configuration for `createForm()`.
+ *
+ * @template T - Shape of the form values
+ *
+ * @example
+ * ```ts
+ * const config: FormConfig<{ name: string; age: number }> = {
+ *   fields: {
+ *     name: { initialValue: '', validators: [required('Name is required')] },
+ *     age: { initialValue: 0, validators: [min(1, 'Must be positive')] },
+ *   },
+ *   onSubmit: (values) => console.log(values),
+ * };
+ * ```
+ */
+export type FormConfig<T extends Record<string, unknown>> = {
+    /** Per-field configuration with initial values and validators */
+    fields: {
+        [K in keyof T]: FieldConfig<T[K]>;
+    };
+    /** Optional cross-field validators run after per-field validation */
+    crossValidators?: CrossFieldValidator<T>[];
+    /** Callback invoked on successful form submission */
+    onSubmit?: SubmitHandler<T>;
+};
+/**
+ * Return value of `createForm()`.
+ *
+ * @template T - Shape of the form values
+ */
+export type Form<T extends Record<string, unknown>> = {
+    /** Reactive field objects keyed by field name */
+    fields: FormFields<T>;
+    /** Shorthand error signals keyed by field name */
+    errors: FormErrors<T>;
+    /** Computed signal: `true` when all fields pass validation */
+    isValid: Computed<boolean>;
+    /** Computed signal: `true` when any field value differs from initial */
+    isDirty: Computed<boolean>;
+    /** Reactive signal: `true` while the submit handler is executing */
+    isSubmitting: Signal<boolean>;
+    /** Validate all fields and, if valid, call the `onSubmit` handler */
+    handleSubmit: () => Promise<void>;
+    /** Validate a single field by name */
+    validateField: (name: keyof T & string) => Promise<void>;
+    /** Validate all fields without submitting */
+    validate: () => Promise<boolean>;
+    /** Reset the entire form to initial values */
+    reset: () => void;
+    /** Get a snapshot of all current field values */
+    getValues: () => T;
+    /**
+     * Bulk-set field values from a partial object.
+     * Only fields present in the object are updated; missing keys are left unchanged.
+     */
+    setValues: (values: Partial<T>) => void;
+    /**
+     * Bulk-set field error messages from a partial object.
+     * Useful for applying server-side validation errors.
+     */
+    setErrors: (errors: Partial<Record<keyof T & string, string>>) => void;
+};
+//# sourceMappingURL=types.d.ts.map

package/dist/forms/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/forms/types.ts"],"names":[],"mappings":"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"}

package/dist/forms/use-field.d.ts

@@ -0,0 +1,34 @@
+/**
+ * Standalone reactive field composable.
+ *
+ * @module bquery/forms
+ */
+import type { MaybeSignal } from '../reactive/index';
+import type { UseFormFieldOptions, UseFormFieldReturn } from './types';
+/**
+ * Creates a standalone reactive form field with optional automatic validation.
+ *
+ * This helper is useful when you want field-level state without creating a full form,
+ * or when you want to bind an existing signal to the forms validation model.
+ *
+ * @template T - The type of the field value
+ * @param initialValue - Plain initial value, an existing writable signal to reuse, or a
+ * computed / readonly reactive source to snapshot
+ * @param options - Validation mode, validators, debounce, and initial error configuration
+ * @returns A reactive field handle with validation helpers
+ *
+ * @example
+ * ```ts
+ * import { useFormField, required } from '@bquery/bquery/forms';
+ *
+ * const email = useFormField('', {
+ *   validators: [required()],
+ *   validateOn: 'blur',
+ * });
+ *
+ * email.value.value = 'ada@example.com';
+ * email.touch();
+ * ```
+ */
+export declare const useFormField: <T>(initialValue: MaybeSignal<T>, options?: UseFormFieldOptions<T>) => UseFormFieldReturn<T>;
+//# sourceMappingURL=use-field.d.ts.map

package/dist/forms/use-field.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"use-field.d.ts","sourceRoot":"","sources":["../../src/forms/use-field.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAOH,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAC;AAErD,OAAO,KAAK,EAAE,mBAAmB,EAAE,kBAAkB,EAA+B,MAAM,SAAS,CAAC;AAmBpG;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,eAAO,MAAM,YAAY,GAAI,CAAC,EAC5B,cAAc,WAAW,CAAC,CAAC,CAAC,EAC5B,UAAS,mBAAmB,CAAC,CAAC,CAAM,KACnC,kBAAkB,CAAC,CAAC,CA0JtB,CAAC"}

package/dist/forms/validators.d.ts

@@ -0,0 +1,204 @@
+/**
+ * Built-in validation functions for form fields.
+ *
+ * Each factory returns a {@link SyncValidator} that can be passed
+ * to a field's `validators` array in {@link FormConfig}.
+ *
+ * @module bquery/forms
+ */
+import type { AsyncValidator, SyncValidator } from './types';
+/**
+ * Requires a non-empty value.
+ *
+ * Fails for `undefined`, `null`, empty strings (after trim), and empty arrays.
+ *
+ * @param message - Custom error message (default: `'This field is required'`)
+ * @returns A sync validator function
+ *
+ * @example
+ * ```ts
+ * import { required } from '@bquery/bquery/forms';
+ * const validate = required('Name is required');
+ * validate('');    // 'Name is required'
+ * validate('Ada'); // true
+ * ```
+ */
+export declare const required: (message?: string) => SyncValidator;
+/**
+ * Requires a string to have at least `len` characters.
+ *
+ * Non-string values are coerced via `String()` before checking length.
+ *
+ * @param len - Minimum length
+ * @param message - Custom error message
+ * @returns A sync validator function
+ *
+ * @example
+ * ```ts
+ * import { minLength } from '@bquery/bquery/forms';
+ * const validate = minLength(3);
+ * validate('ab');  // 'Must be at least 3 characters'
+ * validate('abc'); // true
+ * ```
+ */
+export declare const minLength: (len: number, message?: string) => SyncValidator<unknown>;
+/**
+ * Requires a string to have at most `len` characters.
+ *
+ * Non-string values are coerced via `String()` before checking length.
+ *
+ * @param len - Maximum length
+ * @param message - Custom error message
+ * @returns A sync validator function
+ *
+ * @example
+ * ```ts
+ * import { maxLength } from '@bquery/bquery/forms';
+ * const validate = maxLength(10);
+ * validate('hello world!!'); // 'Must be at most 10 characters'
+ * validate('hello');         // true
+ * ```
+ */
+export declare const maxLength: (len: number, message?: string) => SyncValidator<unknown>;
+/**
+ * Requires a string to match a regular expression pattern.
+ *
+ * Non-string values are coerced via `String()` before testing.
+ *
+ * @param regex - Pattern to test against
+ * @param message - Custom error message (default: `'Invalid format'`)
+ * @returns A sync validator function
+ *
+ * @example
+ * ```ts
+ * import { pattern } from '@bquery/bquery/forms';
+ * const validate = pattern(/^\d+$/, 'Numbers only');
+ * validate('abc'); // 'Numbers only'
+ * validate('123'); // true
+ * ```
+ */
+export declare const pattern: (regex: RegExp, message?: string) => SyncValidator<unknown>;
+/**
+ * RFC 5322–simplified email validation.
+ *
+ * @param message - Custom error message (default: `'Invalid email address'`)
+ * @returns A sync validator function
+ *
+ * @example
+ * ```ts
+ * import { email } from '@bquery/bquery/forms';
+ * const validate = email();
+ * validate('nope');          // 'Invalid email address'
+ * validate('ada@lovelace'); // 'Invalid email address'
+ * validate('ada@love.co');  // true
+ * ```
+ */
+export declare const email: (message?: string) => SyncValidator<unknown>;
+/**
+ * Requires a string to be a valid URL.
+ *
+ * Uses the native `URL` constructor for validation.
+ *
+ * @param message - Custom error message (default: `'Invalid URL'`)
+ * @returns A sync validator function
+ *
+ * @example
+ * ```ts
+ * import { url } from '@bquery/bquery/forms';
+ * const validate = url();
+ * validate('not-a-url');                // 'Invalid URL'
+ * validate('https://example.com');      // true
+ * ```
+ */
+export declare const url: (message?: string) => SyncValidator<unknown>;
+/**
+ * Requires a numeric value to be at least `limit`.
+ *
+ * @param limit - Minimum allowed value (inclusive)
+ * @param message - Custom error message
+ * @returns A sync validator function
+ *
+ * @example
+ * ```ts
+ * import { min } from '@bquery/bquery/forms';
+ * const validate = min(1, 'Must be positive');
+ * validate(0); // 'Must be positive'
+ * validate(1); // true
+ * ```
+ */
+export declare const min: (limit: number, message?: string) => SyncValidator<unknown>;
+/**
+ * Requires a numeric value to be at most `limit`.
+ *
+ * @param limit - Maximum allowed value (inclusive)
+ * @param message - Custom error message
+ * @returns A sync validator function
+ *
+ * @example
+ * ```ts
+ * import { max } from '@bquery/bquery/forms';
+ * const validate = max(100, 'Too high');
+ * validate(101); // 'Too high'
+ * validate(100); // true
+ * ```
+ */
+export declare const max: (limit: number, message?: string) => SyncValidator<unknown>;
+/**
+ * Creates a custom synchronous validator from any predicate function.
+ *
+ * @param fn - Predicate that returns `true` when the value is valid
+ * @param message - Error message when the predicate returns `false`
+ * @returns A sync validator function
+ *
+ * @example
+ * ```ts
+ * import { custom } from '@bquery/bquery/forms';
+ * const isEven = custom((v: number) => v % 2 === 0, 'Must be even');
+ * isEven(3); // 'Must be even'
+ * isEven(4); // true
+ * ```
+ */
+export declare const custom: <T = unknown>(fn: (value: T) => boolean, message: string) => SyncValidator<T>;
+/**
+ * Creates a custom asynchronous validator.
+ *
+ * @param fn - Async predicate that resolves to `true` when valid
+ * @param message - Error message when the predicate resolves to `false`
+ * @returns An async validator function
+ *
+ * @example
+ * ```ts
+ * import { customAsync } from '@bquery/bquery/forms';
+ * const isUnique = customAsync(
+ *   async (name: string) => !(await checkExists(name)),
+ *   'Already taken',
+ * );
+ * ```
+ */
+export declare const customAsync: <T = unknown>(fn: (value: T) => Promise<boolean>, message: string) => AsyncValidator<T>;
+/**
+ * Requires a field's value to match the current value of a reference signal.
+ *
+ * Typically used for "confirm password" or "confirm email" patterns where
+ * one field must have the same value as another.
+ *
+ * @param ref - A reactive signal whose current value is the comparison target
+ * @param message - Custom error message (default: `'Fields do not match'`)
+ * @returns A sync validator function
+ *
+ * @example
+ * ```ts
+ * import { signal } from '@bquery/bquery/reactive';
+ * import { matchField } from '@bquery/bquery/forms';
+ *
+ * const password = signal('secret');
+ * const confirmPassword = signal('');
+ * const validateConfirmPassword = matchField(password, 'Passwords must match');
+ *
+ * validateConfirmPassword(confirmPassword.value);
+ * ```
+ */
+export declare const matchField: <T>(ref: {
+    readonly value: T;
+}, message?: string) => SyncValidator<T>;
+//# sourceMappingURL=validators.d.ts.map

package/dist/forms/validators.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"validators.d.ts","sourceRoot":"","sources":["../../src/forms/validators.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,KAAK,EAAE,cAAc,EAAE,aAAa,EAAE,MAAM,SAAS,CAAC;AAE7D;;;;;;;;;;;;;;;GAeG;AACH,eAAO,MAAM,QAAQ,GAAI,gBAAkC,KAAG,aAO7D,CAAC;AAEF;;;;;;;;;;;;;;;;GAgBG;AACH,eAAO,MAAM,SAAS,GAAI,KAAK,MAAM,EAAE,UAAU,MAAM,KAAG,aAAa,CAAC,OAAO,CAM9E,CAAC;AAEF;;;;;;;;;;;;;;;;GAgBG;AACH,eAAO,MAAM,SAAS,GAAI,KAAK,MAAM,EAAE,UAAU,MAAM,KAAG,aAAa,CAAC,OAAO,CAM9E,CAAC;AAEF;;;;;;;;;;;;;;;;GAgBG;AACH,eAAO,MAAM,OAAO,GAAI,OAAO,MAAM,EAAE,gBAA0B,KAAG,aAAa,CAAC,OAAO,CAWxF,CAAC;AAEF;;;;;;;;;;;;;;GAcG;AACH,eAAO,MAAM,KAAK,GAAI,gBAAiC,KAAG,aAAa,CAAC,OAAO,CAS9E,CAAC;AAEF;;;;;;;;;;;;;;;GAeG;AACH,eAAO,MAAM,GAAG,GAAI,gBAAuB,KAAG,aAAa,CAAC,OAAO,CAWlE,CAAC;AAEF;;;;;;;;;;;;;;GAcG;AACH,eAAO,MAAM,GAAG,GAAI,OAAO,MAAM,EAAE,UAAU,MAAM,KAAG,aAAa,CAAC,OAAO,CAQ1E,CAAC;AAEF;;;;;;;;;;;;;;GAcG;AACH,eAAO,MAAM,GAAG,GAAI,OAAO,MAAM,EAAE,UAAU,MAAM,KAAG,aAAa,CAAC,OAAO,CAQ1E,CAAC;AAEF;;;;;;;;;;;;;;GAcG;AACH,eAAO,MAAM,MAAM,GAAI,CAAC,GAAG,OAAO,EAChC,IAAI,CAAC,KAAK,EAAE,CAAC,KAAK,OAAO,EACzB,SAAS,MAAM,KACd,aAAa,CAAC,CAAC,CAEjB,CAAC;AAEF;;;;;;;;;;;;;;;GAeG;AACH,eAAO,MAAM,WAAW,GAAI,CAAC,GAAG,OAAO,EACrC,IAAI,CAAC,KAAK,EAAE,CAAC,KAAK,OAAO,CAAC,OAAO,CAAC,EAClC,SAAS,MAAM,KACd,cAAc,CAAC,CAAC,CAElB,CAAC;AAEF;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,eAAO,MAAM,UAAU,GAAI,CAAC,EAC1B,KAAK;IAAE,QAAQ,CAAC,KAAK,EAAE,CAAC,CAAA;CAAE,EAC1B,gBAA+B,KAC9B,aAAa,CAAC,CAAC,CAEjB,CAAC"}