@bquery/bquery 1.7.0 → 1.8.2

package/src/forms/index.ts

@@ -1,65 +1,70 @@
-/**
- * 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 {
-  custom,
-  customAsync,
-  email,
-  max,
-  maxLength,
-  min,
-  minLength,
-  pattern,
-  required,
-  url,
-} from './validators';
-
-export type {
-  AsyncValidator,
-  CrossFieldValidator,
-  FieldConfig,
-  Form,
-  FormConfig,
-  FormErrors,
-  FormField,
-  FormFields,
-  SubmitHandler,
-  SyncValidator,
-  ValidationResult,
-  Validator,
-} from './types';
+/**
+ * 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';

package/src/forms/types.ts

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