@pithyjs/ui-kit 0.1.0-beta.0

package/dist/organisms/forms/Form.js

@@ -0,0 +1,131 @@
+/** @codex
+{
+  "id": "pithy.ui-kit.form",
+  "title": "<Form> Organism",
+  "category": "feature"
+}
+*/
+import { renderChildren } from '@pithyjs/core';
+import { captureSlot } from '../../shared/slots';
+import { createFormState } from './form-state';
+import { createFormElement, attachSubmittingEffect, handleValidationFailure, } from './form-helpers';
+// ---------------------------------------------------------------------------
+// Component
+// ---------------------------------------------------------------------------
+/**
+ * Semantic `<form>` organism with signal-based state engine.
+ *
+ * Creates a `<form novalidate>` element, manages submit lifecycle
+ * (validate → submit → complete), and exposes `state` on the return
+ * object for manual wiring to child form atoms.
+ *
+ * Children are appended by the caller — Form does not render fields
+ * itself. For config-driven field generation, use `<DynamicForm>`.
+ *
+ * @example
+ * ```typescript
+ * const form = Form({
+ *   initialValues: { email: "" },
+ *   validationRules: { email: [{ type: "required", message: "Required" }] },
+ *   onSubmit: (values) => console.log(values),
+ * });
+ * const input = Input({
+ *   label: "Email",
+ *   value: form.state.fieldValue("email"),
+ *   error: form.state.fieldHasError("email"),
+ *   errorMessage: form.state.fieldErrorMessage("email"),
+ *   onInput: (val) => form.state.setValue("email", val),
+ *   onBlur: () => form.state.setTouched("email"),
+ * });
+ * form.el.appendChild(input.el);
+ * ```
+ */
+/** @codexApi {"parent":"pithy.ui-kit.form","name":"Form","stability":"stable","signature":"(props: FormProps) => FormResult"} */
+export function Form({ onSubmit, initialValues = undefined, validateOn = undefined, validationRules = undefined, ariaLabel = undefined, ariaLabelledBy = undefined, }) {
+    const disposers = [];
+    // -- State engine ---------------------------------------------------------
+    const state = createFormState({
+        initialValues,
+        validateOn,
+        validationRules,
+    });
+    // -- DOM ------------------------------------------------------------------
+    const { form, statusEl } = createFormElement();
+    if (ariaLabel)
+        form.setAttribute('aria-label', ariaLabel);
+    if (ariaLabelledBy)
+        form.setAttribute('aria-labelledby', ariaLabelledBy);
+    // -- Reactive submitting state --------------------------------------------
+    disposers.push(attachSubmittingEffect(form, state));
+    // Fields the consumer has declared either via initialValues or validationRules.
+    const trackedFields = new Set([
+        ...Object.keys(initialValues ?? {}),
+        ...Object.keys(validationRules ?? {}),
+    ]);
+    // Autofill safety net — see DynamicForm.syncDomToState for the full rationale.
+    const syncDomToState = () => {
+        const captured = [];
+        const inputs = form.querySelectorAll('input[name], textarea[name], select[name]');
+        for (const el of inputs) {
+            if (el instanceof HTMLInputElement &&
+                (el.type === 'checkbox' || el.type === 'radio')) {
+                continue;
+            }
+            const name = el.name;
+            if (!trackedFields.has(name))
+                continue;
+            captured.push([name, el.value]);
+        }
+        for (const [name, value] of captured) {
+            if (value !== state.values()[name]) {
+                state.setValue(name, value);
+            }
+        }
+    };
+    // -- Submit handler -------------------------------------------------------
+    const handleSubmit = async (e) => {
+        e.preventDefault();
+        if (state.isSubmitting())
+            return;
+        syncDomToState();
+        const valid = state.validateAll();
+        if (!valid) {
+            handleValidationFailure(form, state, statusEl);
+            return;
+        }
+        statusEl.textContent = '';
+        state.isSubmitting.set(true);
+        try {
+            // Shallow (top-level) copy — new outer object, so consumers can't
+            // reassign properties on our internal values map. Nested references
+            // would still be shared, but every built-in FieldConfig type produces
+            // a primitive value (string/number/boolean), so there's nothing
+            // nested to share. Revisit if complex field types are introduced.
+            await onSubmit({ ...state.values() });
+        }
+        catch (err) {
+            if (import.meta.env?.DEV) {
+                console.error('[PithyJS] Form onSubmit threw:', err);
+            }
+        }
+        finally {
+            state.isSubmitting.set(false);
+        }
+    };
+    form.addEventListener('submit', handleSubmit);
+    disposers.push(() => form.removeEventListener('submit', handleSubmit));
+    // -- Content projection (template children) -------------------------------
+    const { el: childFragment, destroy: destroyChildren } = renderChildren();
+    captureSlot(form, 'default');
+    form.appendChild(childFragment);
+    disposers.push(destroyChildren);
+    // -- Destroy --------------------------------------------------------------
+    function destroy() {
+        for (const dispose of disposers)
+            dispose();
+        disposers.length = 0;
+        form.replaceChildren();
+    }
+    return { el: form, destroy, state };
+}
+//# sourceMappingURL=Form.js.map

package/dist/organisms/forms/Form.js.map

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

package/dist/organisms/forms/dynamic-form.scss

@@ -0,0 +1,91 @@
+@use 'sass:map';
+@use '@pithyjs/design-system/a11y/styles/mixins' as a11y;
+@use '@pithyjs/design-system/spacing/styles/tokens' as spacing;
+@use '../../shared/tokens' as shared;
+
+.ui-dynamic-form-grid {
+  display: grid;
+  gap: var(--space-md);
+  grid-template-columns: 1fr;
+  min-inline-size: 0;
+}
+
+.ui-dynamic-form {
+  container-type: inline-size;
+}
+
+// Max of the fluid --space-md range — the runtime gap can be larger than
+// the static default, so using `max` keeps the $min-column floor honored.
+$_max-gap: map.get(map.get(spacing.$spacing-fluid, md), max);
+
+// N columns activate when the container fits N × $min-column + (N−1) gaps.
+@for $n from 2 through 4 {
+  @container (min-inline-size: #{shared.$min-column * $n + $_max-gap * ($n - 1)}) {
+    .ui-dynamic-form-grid[data-columns='#{$n}'] {
+      grid-template-columns: repeat($n, 1fr);
+    }
+  }
+}
+
+.ui-dynamic-form-field {
+  min-inline-size: 0;
+
+  &[data-span='full'] {
+    grid-column: 1 / -1;
+  }
+}
+
+// Numeric spans activate only when multi-column layout is active.
+@container (min-inline-size: #{shared.$min-column * 2 + $_max-gap}) {
+  @for $n from 2 through 4 {
+    .ui-dynamic-form-field[data-span='#{$n}'] {
+      grid-column: span $n;
+    }
+  }
+}
+
+// -- Collapsible field (dependsOn) — 0fr→1fr height animation --------------
+.ui-dynamic-form-collapsible {
+  border: 0;
+  padding: 0;
+  margin: 0;
+  min-inline-size: 0;
+
+  display: grid;
+  grid-template-rows: 0fr;
+  opacity: 0;
+  overflow: hidden;
+
+  @include a11y.motion-safe {
+    transition:
+      grid-template-rows var(--motion-duration-normal)
+        var(--motion-easing-standard),
+      opacity var(--motion-duration-normal) var(--motion-easing-standard);
+  }
+
+  > * {
+    min-block-size: 0;
+  }
+
+  &-open {
+    grid-template-rows: 1fr;
+    opacity: 1;
+  }
+}
+
+.ui-dynamic-form-check {
+  display: inline-flex;
+  align-items: center;
+  inline-size: var(--icon-size-sm);
+  block-size: var(--icon-size-sm);
+  vertical-align: middle;
+  margin-inline-end: var(--space-xs);
+}
+
+.ui-dynamic-form-actions {
+  grid-column: 1 / -1;
+  display: flex;
+  justify-content: flex-end;
+  gap: var(--space-sm);
+  padding-block-start: var(--space-sm);
+}

package/dist/organisms/forms/form-helpers.d.ts

@@ -0,0 +1,21 @@
+/** @codex { "id": "pithy.ui-kit.form-helpers", "title": "Form DOM Helpers", "category": "feature" } */
+import type { FormState } from './form-state';
+/**
+ * Create a `<form novalidate>` element with an aria-live status region.
+ * Returns both the form and status elements for further configuration.
+ */
+export declare function createFormElement(...classes: string[]): {
+    form: HTMLFormElement;
+    statusEl: HTMLDivElement;
+};
+/**
+ * Sync `data-submitting` and `aria-busy` attributes on the form element
+ * reactively from `state.isSubmitting`. Returns an effect disposer.
+ */
+export declare function attachSubmittingEffect(form: HTMLFormElement, state: FormState): () => void;
+/**
+ * Handle validation failure: announce error count via status region
+ * and focus the first invalid field. Returns false (for use as early return).
+ */
+export declare function handleValidationFailure(form: HTMLFormElement, state: FormState, statusEl: HTMLElement): false;
+//# sourceMappingURL=form-helpers.d.ts.map

package/dist/organisms/forms/form-helpers.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"form-helpers.d.ts","sourceRoot":"","sources":["../../../src/organisms/forms/form-helpers.ts"],"names":[],"mappings":"AAAA,uGAAuG;AAWvG,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,cAAc,CAAC;AAE9C;;;GAGG;AACH,wBAAgB,iBAAiB,CAAC,GAAG,OAAO,EAAE,MAAM,EAAE,GAAG;IACvD,IAAI,EAAE,eAAe,CAAC;IACtB,QAAQ,EAAE,cAAc,CAAC;CAC1B,CAYA;AAED;;;GAGG;AACH,wBAAgB,sBAAsB,CACpC,IAAI,EAAE,eAAe,EACrB,KAAK,EAAE,SAAS,GACf,MAAM,IAAI,CAWZ;AAED;;;GAGG;AACH,wBAAgB,uBAAuB,CACrC,IAAI,EAAE,eAAe,EACrB,KAAK,EAAE,SAAS,EAChB,QAAQ,EAAE,WAAW,GACpB,KAAK,CAgBP"}

package/dist/organisms/forms/form-helpers.js

@@ -0,0 +1,57 @@
+/** @codex { "id": "pithy.ui-kit.form-helpers", "title": "Form DOM Helpers", "category": "feature" } */
+/**
+ * Shared DOM helpers for Form and DynamicForm organisms.
+ * Extracts common setup patterns to avoid duplication.
+ *
+ * @internal — not part of public API. Exports are consumed only by
+ * Form.ts and DynamicForm.ts within this package.
+ */
+import { effect } from '@pithyjs/signals';
+/**
+ * Create a `<form novalidate>` element with an aria-live status region.
+ * Returns both the form and status elements for further configuration.
+ */
+export function createFormElement(...classes) {
+    const form = document.createElement('form');
+    form.noValidate = true;
+    form.classList.add('ui-form', ...classes);
+    const statusEl = document.createElement('div');
+    statusEl.setAttribute('role', 'status');
+    statusEl.setAttribute('aria-live', 'polite');
+    statusEl.classList.add('u-sr-only');
+    form.appendChild(statusEl);
+    return { form, statusEl };
+}
+/**
+ * Sync `data-submitting` and `aria-busy` attributes on the form element
+ * reactively from `state.isSubmitting`. Returns an effect disposer.
+ */
+export function attachSubmittingEffect(form, state) {
+    return effect(() => {
+        const submitting = state.isSubmitting();
+        if (submitting) {
+            form.setAttribute('data-submitting', '');
+            form.setAttribute('aria-busy', 'true');
+        }
+        else {
+            form.removeAttribute('data-submitting');
+            form.removeAttribute('aria-busy');
+        }
+    });
+}
+/**
+ * Handle validation failure: announce error count via status region
+ * and focus the first invalid field. Returns false (for use as early return).
+ */
+export function handleValidationFailure(form, state, statusEl) {
+    const errorCount = Object.values(state.errors()).reduce((sum, msgs) => sum + msgs.length, 0);
+    statusEl.textContent = `Form has ${errorCount} ${errorCount === 1 ? 'error' : 'errors'}. Please correct and try again.`;
+    const FOCUSABLE = "input, select, textarea, button, [tabindex]:not([tabindex='-1'])";
+    const firstInvalid = form.querySelector("[aria-invalid='true']");
+    const target = firstInvalid?.matches(FOCUSABLE)
+        ? firstInvalid
+        : firstInvalid?.querySelector(FOCUSABLE);
+    target?.focus();
+    return false;
+}
+//# sourceMappingURL=form-helpers.js.map

package/dist/organisms/forms/form-helpers.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"form-helpers.js","sourceRoot":"","sources":["../../../src/organisms/forms/form-helpers.ts"],"names":[],"mappings":"AAAA,uGAAuG;AAEvG;;;;;;GAMG;AAEH,OAAO,EAAE,MAAM,EAAE,MAAM,kBAAkB,CAAC;AAG1C;;;GAGG;AACH,MAAM,UAAU,iBAAiB,CAAC,GAAG,OAAiB;IAIpD,MAAM,IAAI,GAAG,QAAQ,CAAC,aAAa,CAAC,MAAM,CAAC,CAAC;IAC5C,IAAI,CAAC,UAAU,GAAG,IAAI,CAAC;IACvB,IAAI,CAAC,SAAS,CAAC,GAAG,CAAC,SAAS,EAAE,GAAG,OAAO,CAAC,CAAC;IAE1C,MAAM,QAAQ,GAAG,QAAQ,CAAC,aAAa,CAAC,KAAK,CAAC,CAAC;IAC/C,QAAQ,CAAC,YAAY,CAAC,MAAM,EAAE,QAAQ,CAAC,CAAC;IACxC,QAAQ,CAAC,YAAY,CAAC,WAAW,EAAE,QAAQ,CAAC,CAAC;IAC7C,QAAQ,CAAC,SAAS,CAAC,GAAG,CAAC,WAAW,CAAC,CAAC;IACpC,IAAI,CAAC,WAAW,CAAC,QAAQ,CAAC,CAAC;IAE3B,OAAO,EAAE,IAAI,EAAE,QAAQ,EAAE,CAAC;AAC5B,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,sBAAsB,CACpC,IAAqB,EACrB,KAAgB;IAEhB,OAAO,MAAM,CAAC,GAAG,EAAE;QACjB,MAAM,UAAU,GAAG,KAAK,CAAC,YAAY,EAAE,CAAC;QACxC,IAAI,UAAU,EAAE,CAAC;YACf,IAAI,CAAC,YAAY,CAAC,iBAAiB,EAAE,EAAE,CAAC,CAAC;YACzC,IAAI,CAAC,YAAY,CAAC,WAAW,EAAE,MAAM,CAAC,CAAC;QACzC,CAAC;aAAM,CAAC;YACN,IAAI,CAAC,eAAe,CAAC,iBAAiB,CAAC,CAAC;YACxC,IAAI,CAAC,eAAe,CAAC,WAAW,CAAC,CAAC;QACpC,CAAC;IACH,CAAC,CAAC,CAAC;AACL,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,uBAAuB,CACrC,IAAqB,EACrB,KAAgB,EAChB,QAAqB;IAErB,MAAM,UAAU,GAAG,MAAM,CAAC,MAAM,CAAC,KAAK,CAAC,MAAM,EAAE,CAAC,CAAC,MAAM,CACrD,CAAC,GAAG,EAAE,IAAI,EAAE,EAAE,CAAC,GAAG,GAAG,IAAI,CAAC,MAAM,EAChC,CAAC,CACF,CAAC;IACF,QAAQ,CAAC,WAAW,GAAG,YAAY,UAAU,IAAI,UAAU,KAAK,CAAC,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,QAAQ,iCAAiC,CAAC;IAExH,MAAM,SAAS,GACb,kEAAkE,CAAC;IACrE,MAAM,YAAY,GAAG,IAAI,CAAC,aAAa,CAAc,uBAAuB,CAAC,CAAC;IAC9E,MAAM,MAAM,GAAG,YAAY,EAAE,OAAO,CAAC,SAAS,CAAC;QAC7C,CAAC,CAAC,YAAY;QACd,CAAC,CAAC,YAAY,EAAE,aAAa,CAAc,SAAS,CAAC,CAAC;IACxD,MAAM,EAAE,KAAK,EAAE,CAAC;IAEhB,OAAO,KAAK,CAAC;AACf,CAAC"}

package/dist/organisms/forms/form-state.d.ts

@@ -0,0 +1,66 @@
+/** @codex { "id": "pithy.ui-kit.form-state-engine", "title": "Form State Engine", "category": "feature" } */
+/**
+ * Signal-based form state engine.
+ * Pure logic — no DOM dependencies. Used by both <Form> and <DynamicForm>.
+ */
+import { type Signal } from '@pithyjs/signals';
+import { type ValidationRule } from './validation';
+/** When to run field validation. */
+export type ValidateOn = 'change' | 'blur' | 'submit';
+/** @codexApi {"parent":"pithy.ui-kit.form-state-engine","name":"FormState","stability":"stable","signature":"interface FormState"} */
+export interface FormState {
+    /** Current field values */
+    values: Signal<Record<string, unknown>>;
+    /** Per-field error message arrays. Empty object = no errors. */
+    errors: Signal<Record<string, string[]>>;
+    /** Which fields the user has interacted with */
+    touched: Signal<Record<string, boolean>>;
+    /**
+     * Which fields have been edited at least once (matches React Hook Form's
+     * `dirtyFields` semantics — sticky after first edit, only cleared by `reset()`).
+     * Powers the "type-then-clear-then-blur shows required error" UX.
+     */
+    dirty: Signal<Record<string, boolean>>;
+    /** Derived: true when any field has been edited at least once */
+    isDirty: () => boolean;
+    /** Derived: true when errors object has no keys with non-empty arrays */
+    isValid: () => boolean;
+    /** True while the onSubmit async handler is executing */
+    isSubmitting: Signal<boolean>;
+    /** Set a single field value. Triggers validation if validateOn is "change". */
+    setValue(field: string, value: unknown): void;
+    /** Manually set errors for a field. Pass empty array to clear. */
+    setError(field: string, messages: string[]): void;
+    /** Mark a field as touched. Triggers validation if validateOn is "blur". */
+    setTouched(field: string): void;
+    /** Reset all state to initialValues, clear errors and touched. */
+    reset(): void;
+    /** Signal accessor for a single field's value — plugs into atom value prop */
+    fieldValue(field: string): () => unknown;
+    /** Signal accessor: is this field in error state? — plugs into atom error prop */
+    fieldHasError(field: string): () => boolean;
+    /** Signal accessor: first error message — plugs into atom errorMessage prop */
+    fieldErrorMessage(field: string): () => string;
+    /** Validate a single field against its rules. Returns error messages. */
+    validateField(field: string): string[];
+    /** Validate all registered fields. Sets errors signal. Returns true if all valid. */
+    validateAll(): boolean;
+}
+/** @codexApi {"parent":"pithy.ui-kit.form-state-engine","name":"FormStateOptions","stability":"stable","signature":"interface FormStateOptions"} */
+export interface FormStateOptions {
+    /** Initial field values (default: {}) */
+    initialValues?: Record<string, unknown>;
+    /** When to run validation (default: "submit") */
+    validateOn?: ValidateOn;
+    /** Validation rules keyed by field name */
+    validationRules?: Record<string, ValidationRule[]>;
+}
+/**
+ * Create a reactive form state engine.
+ *
+ * Returns a FormState object with signal-based values, errors, touched,
+ * and field accessors that are directly compatible with form atom props.
+ */
+/** @codexApi {"parent":"pithy.ui-kit.form-state-engine","name":"createFormState","stability":"stable","signature":"(options?: FormStateOptions) => FormState"} */
+export declare function createFormState(options?: FormStateOptions): FormState;
+//# sourceMappingURL=form-state.d.ts.map

package/dist/organisms/forms/form-state.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"form-state.d.ts","sourceRoot":"","sources":["../../../src/organisms/forms/form-state.ts"],"names":[],"mappings":"AAAA,6GAA6G;AAE7G;;;GAGG;AAEH,OAAO,EAAiB,KAAK,MAAM,EAAE,MAAM,kBAAkB,CAAC;AAC9D,OAAO,EAEL,KAAK,cAAc,EACpB,MAAM,cAAc,CAAC;AAMtB,oCAAoC;AACpC,MAAM,MAAM,UAAU,GAAG,QAAQ,GAAG,MAAM,GAAG,QAAQ,CAAC;AAEtD,sIAAsI;AACtI,MAAM,WAAW,SAAS;IACxB,2BAA2B;IAC3B,MAAM,EAAE,MAAM,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAAC;IACxC,gEAAgE;IAChE,MAAM,EAAE,MAAM,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,EAAE,CAAC,CAAC,CAAC;IACzC,gDAAgD;IAChD,OAAO,EAAE,MAAM,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAAC;IACzC;;;;OAIG;IACH,KAAK,EAAE,MAAM,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAAC;IACvC,iEAAiE;IACjE,OAAO,EAAE,MAAM,OAAO,CAAC;IACvB,yEAAyE;IACzE,OAAO,EAAE,MAAM,OAAO,CAAC;IACvB,yDAAyD;IACzD,YAAY,EAAE,MAAM,CAAC,OAAO,CAAC,CAAC;IAE9B,+EAA+E;IAC/E,QAAQ,CAAC,KAAK,EAAE,MAAM,EAAE,KAAK,EAAE,OAAO,GAAG,IAAI,CAAC;IAC9C,kEAAkE;IAClE,QAAQ,CAAC,KAAK,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,EAAE,GAAG,IAAI,CAAC;IAClD,4EAA4E;IAC5E,UAAU,CAAC,KAAK,EAAE,MAAM,GAAG,IAAI,CAAC;IAChC,kEAAkE;IAClE,KAAK,IAAI,IAAI,CAAC;IAEd,8EAA8E;IAC9E,UAAU,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,OAAO,CAAC;IACzC,kFAAkF;IAClF,aAAa,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,OAAO,CAAC;IAC5C,+EAA+E;IAC/E,iBAAiB,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,MAAM,CAAC;IAE/C,yEAAyE;IACzE,aAAa,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,EAAE,CAAC;IACvC,qFAAqF;IACrF,WAAW,IAAI,OAAO,CAAC;CACxB;AAED,oJAAoJ;AACpJ,MAAM,WAAW,gBAAgB;IAC/B,yCAAyC;IACzC,aAAa,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACxC,iDAAiD;IACjD,UAAU,CAAC,EAAE,UAAU,CAAC;IACxB,2CAA2C;IAC3C,eAAe,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,cAAc,EAAE,CAAC,CAAC;CACpD;AAMD;;;;;GAKG;AACH,kKAAkK;AAClK,wBAAgB,eAAe,CAAC,OAAO,GAAE,gBAAqB,GAAG,SAAS,CA6JzE"}

package/dist/organisms/forms/form-state.js

@@ -0,0 +1,156 @@
+/** @codex { "id": "pithy.ui-kit.form-state-engine", "title": "Form State Engine", "category": "feature" } */
+/**
+ * Signal-based form state engine.
+ * Pure logic — no DOM dependencies. Used by both <Form> and <DynamicForm>.
+ */
+import { signal, batch } from '@pithyjs/signals';
+import { validateField as runValidation, } from './validation';
+// ---------------------------------------------------------------------------
+// Factory
+// ---------------------------------------------------------------------------
+/**
+ * Create a reactive form state engine.
+ *
+ * Returns a FormState object with signal-based values, errors, touched,
+ * and field accessors that are directly compatible with form atom props.
+ */
+/** @codexApi {"parent":"pithy.ui-kit.form-state-engine","name":"createFormState","stability":"stable","signature":"(options?: FormStateOptions) => FormState"} */
+export function createFormState(options = {}) {
+    const { initialValues: rawInitialValues = {}, validateOn = 'submit', validationRules = {}, } = options;
+    // Snapshot initialValues so caller mutations after createFormState() don't
+    // change reset() / dirty comparison behavior.
+    const initialValues = { ...rawInitialValues };
+    // -- Core signals ---------------------------------------------------------
+    const values = signal({ ...initialValues });
+    const errors = signal({});
+    const touched = signal({});
+    const dirty = signal({});
+    const isSubmitting = signal(false);
+    // Derived as plain functions (not computed()) — @pithyjs/signals' computed
+    // doesn't return a disposer, so using it would leak an internal effect
+    // for every createFormState() call. As plain functions these are still
+    // reactive when called inside an effect (they read errors()/dirty() which
+    // tracks the dependency normally).
+    const isValid = () => {
+        const errs = errors();
+        return Object.keys(errs).every(key => errs[key].length === 0);
+    };
+    const isDirty = () => {
+        const d = dirty();
+        return Object.keys(d).some(key => d[key]);
+    };
+    // -- Internal validation --------------------------------------------------
+    function runFieldValidation(field) {
+        const rules = validationRules[field];
+        if (!rules || rules.length === 0)
+            return [];
+        return runValidation(values()[field], rules, values());
+    }
+    function applyFieldErrors(field, msgs) {
+        errors.set(prev => {
+            const next = { ...prev };
+            if (msgs.length === 0) {
+                delete next[field];
+            }
+            else {
+                next[field] = msgs;
+            }
+            return next;
+        });
+    }
+    // -- Mutations ------------------------------------------------------------
+    function setValue(field, value) {
+        values.set(prev => ({ ...prev, [field]: value }));
+        // `dirty` tracks "has been edited at least once" (not "currently differs
+        // from initial"). This matches React Hook Form's `dirtyFields` semantics
+        // and powers the "type-then-clear-then-blur shows required error" UX:
+        // a user who edits a field and reverts it should still see validation
+        // on blur, otherwise required-but-cleared fields look fine.
+        // The flag is set on first edit and only reset by `reset()`.
+        if (value !== initialValues[field]) {
+            dirty.set(prev => ({ ...prev, [field]: true }));
+        }
+        // Always re-validate on change if the field already has errors (eager clear)
+        // Otherwise only validate on change if that's the configured mode
+        const hasExistingError = errors()[field]?.length > 0;
+        if (validateOn === 'change' || hasExistingError) {
+            applyFieldErrors(field, runFieldValidation(field));
+        }
+    }
+    function setError(field, messages) {
+        applyFieldErrors(field, messages);
+    }
+    function setTouched(field) {
+        touched.set(prev => ({ ...prev, [field]: true }));
+        if (validateOn === 'blur' && dirty()[field]) {
+            applyFieldErrors(field, runFieldValidation(field));
+        }
+    }
+    function reset() {
+        batch(() => {
+            values.set({ ...initialValues });
+            errors.set({});
+            touched.set({});
+            dirty.set({});
+            isSubmitting.set(false);
+        });
+    }
+    // -- Field accessors (signal-compatible for atom props) -------------------
+    function fieldValue(field) {
+        return () => values()[field];
+    }
+    function fieldHasError(field) {
+        return () => {
+            const fieldErrors = errors()[field];
+            return !!fieldErrors && fieldErrors.length > 0;
+        };
+    }
+    function fieldErrorMessage(field) {
+        return () => {
+            const fieldErrors = errors()[field];
+            return fieldErrors && fieldErrors.length > 0 ? fieldErrors[0] : '';
+        };
+    }
+    // -- Validation -----------------------------------------------------------
+    function validateFieldMethod(field) {
+        const msgs = runFieldValidation(field);
+        applyFieldErrors(field, msgs);
+        return msgs;
+    }
+    function validateAll() {
+        const allErrors = {};
+        const currentValues = values();
+        for (const field of Object.keys(validationRules)) {
+            const rules = validationRules[field];
+            if (!rules || rules.length === 0)
+                continue;
+            const msgs = runValidation(currentValues[field], rules, currentValues);
+            if (msgs.length > 0) {
+                allErrors[field] = msgs;
+            }
+        }
+        // Replace all errors with freshly computed validation results.
+        // Manual errors set via setError() are cleared — validateAll() is a full reset.
+        errors.set(allErrors);
+        return Object.keys(allErrors).length === 0;
+    }
+    return {
+        values,
+        errors,
+        touched,
+        dirty,
+        isDirty,
+        isValid,
+        isSubmitting,
+        setValue,
+        setError,
+        setTouched,
+        reset,
+        fieldValue,
+        fieldHasError,
+        fieldErrorMessage,
+        validateField: validateFieldMethod,
+        validateAll,
+    };
+}
+//# sourceMappingURL=form-state.js.map

package/dist/organisms/forms/form-state.js.map

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

package/dist/organisms/forms/form.scss

@@ -0,0 +1,23 @@
+@use '@pithyjs/design-system/a11y/styles/mixins' as a11y;
+
+.ui-form {
+  // Minimal base — child atoms handle their own styling.
+  // Form only manages the submitting overlay state.
+
+  &[data-submitting] {
+    opacity: var(--state-disabled-opacity);
+    pointer-events: none;
+
+    @include a11y.motion-safe {
+      transition: opacity var(--motion-duration-normal)
+        var(--motion-easing-standard);
+    }
+  }
+
+  // Forced-colors: make submitting state visible via system color
+  @include a11y.forced-colors {
+    &[data-submitting] {
+      color: GrayText;
+    }
+  }
+}

package/dist/organisms/forms/validation.d.ts

@@ -0,0 +1,32 @@
+/** @codex { "id": "pithy.ui-kit.validation", "title": "Form Validation Engine", "category": "feature" } */
+/**
+ * Pure validation functions for the form system.
+ * No DOM dependencies — can be tested and used in isolation.
+ */
+/** @codexApi {"parent":"pithy.ui-kit.validation","name":"ValidationRule","stability":"stable","signature":"interface ValidationRule"} */
+export interface ValidationRule {
+    /** Built-in rule type or "custom" for user-defined validators */
+    type: 'required' | 'minLength' | 'maxLength' | 'min' | 'max' | 'pattern' | 'email' | 'url' | 'custom';
+    /** Rule parameter: number for length/min/max, string or RegExp source for pattern */
+    value?: unknown;
+    /** Error message shown when the rule fails */
+    message: string;
+    /** Custom validator function (only used when type is "custom") */
+    validator?: (value: unknown, allValues: Record<string, unknown>) => string | null;
+}
+/**
+ * Validate a single value against one rule.
+ * Returns the error message string if the rule fails, or `null` if it passes.
+ *
+ * Non-required rules are skipped for empty values (standard HTML5 behavior):
+ * an empty optional field is valid; the "required" rule handles emptiness.
+ */
+/** @codexApi {"parent":"pithy.ui-kit.validation","name":"checkRule","stability":"stable","signature":"(rule: ValidationRule, value: unknown, allValues: Record<string, unknown>) => string | null"} */
+export declare function checkRule(rule: ValidationRule, value: unknown, allValues: Record<string, unknown>): string | null;
+/**
+ * Validate a single value against all its rules.
+ * Returns an array of error messages (empty array = valid).
+ */
+/** @codexApi {"parent":"pithy.ui-kit.validation","name":"validateField","stability":"stable","signature":"(value: unknown, rules: ValidationRule[], allValues: Record<string, unknown>) => string[]"} */
+export declare function validateField(value: unknown, rules: ValidationRule[], allValues: Record<string, unknown>): string[];
+//# sourceMappingURL=validation.d.ts.map

package/dist/organisms/forms/validation.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"validation.d.ts","sourceRoot":"","sources":["../../../src/organisms/forms/validation.ts"],"names":[],"mappings":"AAAA,2GAA2G;AAE3G;;;GAGG;AAMH,yIAAyI;AACzI,MAAM,WAAW,cAAc;IAC7B,iEAAiE;IACjE,IAAI,EACA,UAAU,GACV,WAAW,GACX,WAAW,GACX,KAAK,GACL,KAAK,GACL,SAAS,GACT,OAAO,GACP,KAAK,GACL,QAAQ,CAAC;IACb,qFAAqF;IACrF,KAAK,CAAC,EAAE,OAAO,CAAC;IAChB,8CAA8C;IAC9C,OAAO,EAAE,MAAM,CAAC;IAChB,kEAAkE;IAClE,SAAS,CAAC,EAAE,CACV,KAAK,EAAE,OAAO,EACd,SAAS,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,KAC/B,MAAM,GAAG,IAAI,CAAC;CACpB;AAiBD;;;;;;GAMG;AACH,uMAAuM;AACvM,wBAAgB,SAAS,CACvB,IAAI,EAAE,cAAc,EACpB,KAAK,EAAE,OAAO,EACd,SAAS,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GACjC,MAAM,GAAG,IAAI,CAkFf;AAED;;;GAGG;AACH,yMAAyM;AACzM,wBAAgB,aAAa,CAC3B,KAAK,EAAE,OAAO,EACd,KAAK,EAAE,cAAc,EAAE,EACvB,SAAS,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GACjC,MAAM,EAAE,CAOV"}