dalila 1.5.13 → 1.6.0

package/README.md

@@ -77,6 +77,10 @@ bind(document.getElementById('app')!, ctx);
 - [Query](./docs/core/query.md) — Cached queries
 - [Mutations](./docs/core/mutation.md) — Write operations
 
+### Forms
+
+- [Forms](./docs/forms.md) — DOM-first form management with validation, field arrays, and accessibility
+
 ### Utilities
 
 - [Scheduler](./docs/core/scheduler.md) — Batching and coordination
@@ -189,6 +193,49 @@ const router = createRouter({
 router.start();
 ```
 
+### Forms
+
+```ts
+import { createForm } from 'dalila';
+
+const userForm = createForm({
+  defaultValues: { name: '', email: '' },
+  validate: (data) => {
+    const errors: Record<string, string> = {};
+    if (!data.name) errors.name = 'Name is required';
+    if (!data.email?.includes('@')) errors.email = 'Invalid email';
+    return errors;
+  }
+});
+
+async function handleSubmit(data, { signal }) {
+  await fetch('/api/users', {
+    method: 'POST',
+    body: JSON.stringify(data),
+    signal
+  });
+}
+```
+
+```html
+<form d-form="userForm" d-on-submit="handleSubmit">
+  <label>
+    Name
+    <input d-field="name" />
+  </label>
+  <span d-error="name"></span>
+
+  <label>
+    Email
+    <input d-field="email" type="email" />
+  </label>
+  <span d-error="email"></span>
+
+  <button type="submit">Save</button>
+  <span d-form-error="userForm"></span>
+</form>
+```
+
 ## Development
 
 ```bash

package/dist/form/form-types.d.ts

@@ -0,0 +1,181 @@
+/**
+ * Type utilities for path-based access
+ */
+export type FieldErrors = Record<string, string>;
+export interface FormSubmitContext {
+    signal: AbortSignal;
+}
+export interface FormOptions<T> {
+    /**
+     * Default values for the form.
+     * Can be a static object, a function returning values, or a promise.
+     */
+    defaultValues?: Partial<T> | (() => Partial<T>) | (() => Promise<Partial<T>>);
+    /**
+     * Custom parser for FormData → T.
+     * If not provided, uses the built-in parser with dot/bracket notation.
+     */
+    parse?: (formEl: HTMLFormElement, fd: FormData) => T;
+    /**
+     * Client-side validation function.
+     * Returns { fieldErrors?, formError? } or just fieldErrors.
+     */
+    validate?: (data: T) => FieldErrors | {
+        fieldErrors?: FieldErrors;
+        formError?: string;
+    } | void;
+    /**
+     * When to run validation:
+     * - "submit" (default): only on submit
+     * - "blur": on field blur after first submit
+     * - "change": on every change after first submit
+     */
+    validateOn?: 'submit' | 'blur' | 'change';
+    /**
+     * Transform server errors into form errors.
+     * Useful for mapping backend error formats to field paths.
+     */
+    transformServerErrors?: (error: unknown) => {
+        fieldErrors?: FieldErrors;
+        formError?: string;
+    } | void;
+}
+export interface Form<T> {
+    /**
+     * Creates a submit handler that:
+     * - prevents default
+     * - collects FormData
+     * - parses to T
+     * - validates (if configured)
+     * - calls handler with data and AbortSignal
+     * - cancels previous submit if re-submitted
+     */
+    handleSubmit(handler: (data: T, ctx: FormSubmitContext) => Promise<unknown> | unknown): (ev: SubmitEvent) => void;
+    /**
+     * Reset form to initial/new defaults
+     */
+    reset(nextDefaults?: Partial<T>): void;
+    /**
+     * Set error for a specific field
+     */
+    setError(path: string, message: string): void;
+    /**
+     * Set form-level error
+     */
+    setFormError(message: string): void;
+    /**
+     * Clear errors (all or by prefix)
+     */
+    clearErrors(prefix?: string): void;
+    /**
+     * Get error message for a field
+     */
+    error(path: string): string | null;
+    /**
+     * Get form-level error
+     */
+    formError(): string | null;
+    /**
+     * Check if field has been touched
+     */
+    touched(path: string): boolean;
+    /**
+     * Check if field is dirty (value differs from default)
+     */
+    dirty(path: string): boolean;
+    /**
+     * Check if form is currently submitting
+     */
+    submitting(): boolean;
+    /**
+     * Get submit count
+     */
+    submitCount(): number;
+    /**
+     * Focus first error field (or specific field)
+     */
+    focus(path?: string): void;
+    /**
+     * Internal: register a field element
+     * @internal
+     */
+    _registerField(path: string, element: HTMLElement): () => void;
+    /**
+     * Internal: get form element
+     * @internal
+     */
+    _getFormElement(): HTMLFormElement | null;
+    /**
+     * Internal: set form element
+     * @internal
+     */
+    _setFormElement(form: HTMLFormElement): void;
+    /**
+     * Create or get a field array
+     */
+    fieldArray<TItem = unknown>(path: string): FieldArray<TItem>;
+}
+export interface FieldArrayItem<T = unknown> {
+    key: string;
+    value?: T;
+}
+export interface FieldArray<TItem = unknown> {
+    /**
+     * Get array of items with stable keys
+     */
+    fields(): FieldArrayItem<TItem>[];
+    /**
+     * Append item(s) to the end
+     */
+    append(value: TItem | TItem[]): void;
+    /**
+     * Remove item by key
+     */
+    remove(key: string): void;
+    /**
+     * Remove item by index
+     */
+    removeAt(index: number): void;
+    /**
+     * Insert item at index
+     */
+    insert(index: number, value: TItem): void;
+    /**
+     * Move item from one index to another
+     */
+    move(fromIndex: number, toIndex: number): void;
+    /**
+     * Swap two items by index
+     */
+    swap(indexA: number, indexB: number): void;
+    /**
+     * Replace entire array
+     */
+    replace(values: TItem[]): void;
+    /**
+     * Update a specific item by key
+     */
+    update(key: string, value: TItem): void;
+    /**
+     * Update a specific item by index
+     */
+    updateAt(index: number, value: TItem): void;
+    /**
+     * Clear all items
+     */
+    clear(): void;
+    /**
+     * Get current length
+     */
+    length(): number;
+    /**
+     * Internal: translate index-based path to key-based path
+     * @internal
+     */
+    _translatePath(path: string): string | null;
+    /**
+     * Internal: get current index for a key
+     * @internal
+     */
+    _getIndex(key: string): number;
+}

package/dist/form/form-types.js

@@ -0,0 +1,4 @@
+/**
+ * Type utilities for path-based access
+ */
+export {};

package/dist/form/form.d.ts

@@ -0,0 +1,71 @@
+/**
+ * Dalila Forms - DOM-first reactive form management
+ *
+ * Design principles:
+ * - Values live in the DOM (uncontrolled by default)
+ * - Meta-state in memory (errors, touched, dirty, submitting)
+ * - Declarative HTML via directives
+ * - Scope-safe with automatic cleanup
+ * - Race-safe submits with AbortController
+ * - Field arrays with stable keys
+ */
+import type { Form, FormOptions } from './form-types.js';
+/**
+ * Symbol to mark handlers that have been wrapped by handleSubmit().
+ * Used by bindForm to avoid double-wrapping.
+ */
+export declare const WRAPPED_HANDLER: unique symbol;
+/**
+ * Parse FormData into a nested object structure.
+ *
+ * Supports:
+ * - Simple fields: "email" → { email: "..." }
+ * - Nested objects: "user.name" → { user: { name: "..." } }
+ * - Arrays: "phones[0].number" → { phones: [{ number: "..." }] }
+ * - Checkboxes: single = boolean, multiple = array of values
+ * - Select multiple: array of selected values
+ * - Radio: single value
+ * - Files: File object
+ *
+ * ## Checkbox Parsing Contract
+ *
+ * HTML FormData omits unchecked checkboxes entirely. To resolve this ambiguity,
+ * parseFormData() inspects the DOM to distinguish between "field missing" vs "checkbox unchecked".
+ *
+ * ### Single Checkbox (one input with unique name)
+ * When there is exactly ONE checkbox with a given name:
+ * - Checked (with or without value) → `true`
+ * - Unchecked → `false`
+ * - Value attribute is ignored (always returns boolean)
+ *
+ * Example:
+ * ```html
+ * <input type="checkbox" name="agree" />
+ * ```
+ * Result: `{ agree: false }` (unchecked) or `{ agree: true }` (checked)
+ *
+ * ### Multiple Checkboxes (same name, multiple inputs)
+ * When there are MULTIPLE checkboxes with the same name:
+ * - Result is ALWAYS an array
+ * - Some checked → `["value1", "value2"]`
+ * - None checked → `[]`
+ * - One checked → `["value1"]` (still an array!)
+ *
+ * Example:
+ * ```html
+ * <input type="checkbox" name="colors" value="red" checked />
+ * <input type="checkbox" name="colors" value="blue" />
+ * <input type="checkbox" name="colors" value="green" checked />
+ * ```
+ * Result: `{ colors: ["red", "green"] }`
+ *
+ * ### Edge Cases
+ * - Radio buttons: Unchecked radio → field absent (standard HTML behavior)
+ * - Select multiple: Always returns array (like multiple checkboxes)
+ *
+ * @param form - The form element to parse (used for DOM inspection)
+ * @param fd - FormData instance from the form
+ * @returns Parsed form data with nested structure
+ */
+export declare function parseFormData<T = unknown>(form: HTMLFormElement, fd: FormData): T;
+export declare function createForm<T = unknown>(options?: FormOptions<T>): Form<T>;