@pienter/ui 0.2.0 → 0.5.0

package/utils/controllers/form.ts

@@ -1,524 +0,0 @@
-import { focusFirstInvalid } from '../a11y/focus.js';
-import { announce } from '../a11y/live-region.js';
-import { type Validator } from '../validation/rules.js';
-import {
-    type FormSubmitResponse,
-    validateFormData,
-    normalizeFieldErrors,
-} from '../validation/form.js';
-
-/**
- * Configuration for `mountForm`. The controller owns submit orchestration:
- * intercepts the submit event, runs validators, renders per-field +
- * top-level errors, sets `aria-busy` during async submit, focuses the
- * first invalid field on failure, and announces success.
- *
- * `onSubmit` is the consumer's handler — usually an async fetch / SDK
- * call. The controller awaits it, then maps the returned
- * `FormSubmitResponse` to UI updates. `onSubmit` is only called when
- * client-side validation passes; if it fails, the controller renders
- * field errors and never calls `onSubmit`.
- */
-export interface FormConfig {
-    /** Per-field validators keyed by field `name`. Run on submit. */
-    validators?: Record<string, Validator[]>;
-    /**
-     * Async submit handler. Called only when client validation passes.
-     * The returned response shape is the placeholder
-     * `FormSubmitResponse` (see `validation/form.ts`); both Vue and
-     * Astro Form orchestration consume the identical shape per design
-     * D13.
-     */
-    onSubmit?: (
-        data: FormData,
-    ) => Promise<FormSubmitResponse> | FormSubmitResponse;
-    /**
-     * Optional observer hook fired after `onSubmit` returns OR after
-     * client validation fails (in the validation-only path it is
-     * called with `{ ok: false, fieldErrors }`). Useful for telemetry.
-     */
-    onResult?: (result: FormSubmitResponse) => void;
-}
-
-/**
- * Mount the form controller on `el`, which MUST be a `<form>` element.
- * The controller intercepts the submit event and orchestrates the full
- * submit lifecycle:
- *
- * 1. `event.preventDefault()`. Read `FormData`.
- * 2. Run `validateFormData(data, validators)` for client-side errors.
- * 3. **If client validation fails**: render per-field errors inside the
- *    matching form-primitive's `v-field__hint role="alert"` element,
- *    set `aria-invalid="true"` on each invalid control, render the
- *    error summary in `v-form__error-summary` (when present), call
- *    `focusFirstInvalid(el)`, announce the error count assertively,
- *    then call `onResult` with `{ ok: false, fieldErrors }`. Does NOT
- *    call `onSubmit`. `onResult` is also called here with
- *    `{ ok: false, fieldErrors }` so telemetry sees both client and
- *    server failures.
- * 4. **If client validation passes**: clear all field errors, set
- *    `aria-busy="true"` on the form, disable the submit button, then
- *    call `await onSubmit(data)`.
- * 5. After `onSubmit` returns: clear `aria-busy`, re-enable submit, then
- *    map the response — render server-side `fieldErrors` and top-level
- *    `errors`, focus first invalid + announce on failure, render +
- *    announce `statusMessage` on success. Call `onResult(response)`
- *    last so consumers can act on `response.redirect`.
- *
- * Returns a teardown function that removes the submit listener and
- * clears any in-progress busy state. Called from Vue's
- * `onBeforeUnmount` or an Astro page-level cleanup. The non-stateful
- * controller signature is the canonical default per CONVENTIONS
- * (mount → teardown without runtime imperative methods).
- */
-export function mountForm(
-    el: HTMLFormElement,
-    config: FormConfig = {},
-): () => void {
-    const validators = config.validators;
-    const onSubmit = config.onSubmit;
-    const onResult = config.onResult;
-
-    let busy = false;
-    let tornDown = false;
-
-    async function handleSubmit(event: SubmitEvent): Promise<void> {
-        event.preventDefault();
-        if (busy) return; // re-entrancy guard
-
-        const formData = new FormData(el);
-
-        // 1. Client-side validation.
-        const clientErrors = validateFormData(formData, validators);
-        const clientErrorCount = Object.keys(clientErrors).length;
-
-        if (clientErrorCount > 0) {
-            applyValidationFailure(el, clientErrors, [], null);
-            const result: FormSubmitResponse = {
-                ok: false,
-                fieldErrors: clientErrors,
-            };
-            onResult?.(result);
-            return;
-        }
-
-        // 2. Client validation passed — clear errors, enter busy state, call onSubmit.
-        clearAllErrors(el);
-
-        if (!onSubmit) {
-            // No submit handler — nothing else to do. Do not call onResult here
-            // because there's no result to report.
-            return;
-        }
-
-        setBusy(el, true);
-        busy = true;
-
-        let response: FormSubmitResponse;
-        try {
-            response = await onSubmit(formData);
-        } catch (err) {
-            // Translate thrown errors into a generic top-level error response so
-            // the UI still surfaces something. Consumers wanting structured
-            // error handling should resolve their promise with `{ ok: false, ... }`
-            // rather than throwing.
-            response = {
-                ok: false,
-                errors: [err instanceof Error ? err.message : 'Submit failed'],
-            };
-        } finally {
-            setBusy(el, false);
-            busy = false;
-        }
-
-        // If teardown ran while `onSubmit` was in flight, abort: the consumer
-        // is unmounting / re-mounting and the DOM should not be mutated.
-        if (tornDown) return;
-
-        // 3. Map response to UI.
-        if (response.ok) {
-            clearAllErrors(el);
-            renderStatusMessage(el, response.statusMessage);
-            if (response.statusMessage) {
-                announce(response.statusMessage, 'polite');
-            }
-        } else {
-            const fieldErrors = normalizeFieldErrors(response.fieldErrors);
-            const topErrors = response.errors ?? [];
-            applyValidationFailure(
-                el,
-                fieldErrors,
-                topErrors,
-                response.statusMessage ?? null,
-            );
-        }
-
-        onResult?.(response);
-    }
-
-    el.addEventListener('submit', handleSubmit);
-
-    return function teardown(): void {
-        el.removeEventListener('submit', handleSubmit);
-        tornDown = true;
-        if (busy) {
-            setBusy(el, false);
-            busy = false;
-        }
-        // Clean up all controller-injected DOM so the form returns to its
-        // pre-mount shape. Important for HMR re-mount and test
-        // mount→teardown→remount cycles where stale nodes / managed-state
-        // markers would otherwise leak between mounts.
-        cleanupControllerDom(el);
-    };
-}
-
-/**
- * Remove every piece of DOM the controller may have injected or marked,
- * leaving consumer-supplied static markup untouched. Mirrors the
- * inverse of {@link applyFieldErrors}, {@link renderErrorSummary},
- * {@link renderStatusMessage}, and {@link setBusy}.
- *
- * The principle: after `teardown()` runs, the form should be
- * indistinguishable from its state before `mountForm` ran.
- */
-function cleanupControllerDom(el: HTMLFormElement): void {
-    // Remove controller-injected error lists, summary, and status nodes.
-    el.querySelectorAll<HTMLElement>(
-        '[data-v-form-errors], [data-v-form-summary], [data-v-form-status]',
-    ).forEach((node) => {
-        // Walk up to the field wrapper before removing so we can clear a
-        // wrapper-level `data-status="error"` that has no other error list
-        // backing it (mirrors the cleanup branch in applyFieldErrors).
-        const wrapper = node.closest<HTMLElement>('.v-field');
-        node.remove();
-        if (wrapper && wrapper.dataset.status === 'error') {
-            const stillHasErrors = wrapper.querySelector<HTMLElement>(
-                '.v-field__hint[role="alert"]',
-            );
-            if (!stillHasErrors) delete wrapper.dataset.status;
-        }
-    });
-
-    // Strip `data-v-form-managed-invalid` markers and the `aria-invalid`
-    // attribute they track.
-    el.querySelectorAll<HTMLElement>(
-        '[data-v-form-managed-invalid="true"]',
-    ).forEach((node) => {
-        node.removeAttribute('aria-invalid');
-        delete node.dataset.vFormManagedInvalid;
-    });
-
-    // Strip `data-v-form-managed-described-by` markers, removing the
-    // tracked id from `aria-describedby` (and the attribute itself when
-    // it ends up empty).
-    el.querySelectorAll<HTMLElement>(
-        '[data-v-form-managed-described-by]',
-    ).forEach((node) => {
-        const managedId = node.dataset.vFormManagedDescribedBy;
-        if (managedId) {
-            const existing = node.getAttribute('aria-describedby');
-            if (existing) {
-                const remaining = existing
-                    .split(/\s+/)
-                    .filter((id) => id && id !== managedId);
-                if (remaining.length > 0) {
-                    node.setAttribute('aria-describedby', remaining.join(' '));
-                } else {
-                    node.removeAttribute('aria-describedby');
-                }
-            }
-        }
-        delete node.dataset.vFormManagedDescribedBy;
-    });
-
-    // Re-enable any submit button we disabled via the busy lifecycle.
-    el.querySelectorAll<HTMLButtonElement>(
-        '[data-v-form-managed-disabled="true"]',
-    ).forEach((node) => {
-        node.disabled = false;
-        delete node.dataset.vFormManagedDisabled;
-    });
-
-    // Clear `aria-busy` if we're the ones that set it.
-    if (el.getAttribute('aria-busy') === 'true') {
-        el.removeAttribute('aria-busy');
-    }
-}
-
-/* ------------------------------------------------------------------ */
-/* Display helpers — private to the controller.                         */
-/* ------------------------------------------------------------------ */
-
-/**
- * Render per-field errors + top-level error summary, mark invalid
- * controls, focus first invalid, and announce the error count. Used by
- * both the client-validation-fails path and the server-error response
- * path.
- */
-function applyValidationFailure(
-    el: HTMLFormElement,
-    fieldErrors: Record<string, string[]>,
-    topErrors: string[],
-    serverStatusMessage: string | null,
-): void {
-    // Clear any prior status message — error response should not coexist
-    // with success chrome.
-    renderStatusMessage(el, undefined);
-
-    // Clear field errors that are no longer present, then apply the new set.
-    applyFieldErrors(el, fieldErrors);
-
-    // Render the top-level summary (combining top-level errors + per-field
-    // counts). The current Form template renders `.v-form__error-summary`
-    // when `errors.length > 0` is true; the controller populates it
-    // imperatively here, creating the summary node if needed.
-    renderErrorSummary(el, topErrors);
-
-    // Focus the first invalid field.
-    focusFirstInvalid(el);
-
-    // Announce a summary count assertively. Server message (if any) takes
-    // priority over a generic count.
-    const totalCount = Object.keys(fieldErrors).length + topErrors.length;
-    if (serverStatusMessage) {
-        announce(serverStatusMessage, 'assertive');
-    } else if (totalCount > 0) {
-        const message =
-            totalCount === 1
-                ? '1 error found. Please review the form.'
-                : `${totalCount} errors found. Please review the form.`;
-        announce(message, 'assertive');
-    }
-}
-
-/**
- * Apply per-field errors to the matching form-primitive's `v-field`
- * wrapper. Looks up the control by `name`, walks up to its `v-field`
- * ancestor, and rewrites the error list inside the wrapper following
- * the locked `<ul class="v-field__hint" role="alert">` pattern.
- *
- * Fields not present in the new map have their previous controller-
- * rendered errors cleared (via the `[data-v-form-errors]` marker on the
- * element the controller injected, so consumer-supplied static error
- * markup is left alone).
- */
-function applyFieldErrors(
-    el: HTMLFormElement,
-    fieldErrors: Record<string, string[]>,
-): void {
-    // Clear all previously controller-rendered field errors first.
-    const previouslyRendered = el.querySelectorAll<HTMLElement>(
-        '[data-v-form-errors]',
-    );
-    previouslyRendered.forEach((node) => {
-        const wrapper = node.closest<HTMLElement>('.v-field');
-        node.remove();
-        if (wrapper) {
-            // Only clear data-status="error" if it was set by us (not by static
-            // consumer-supplied error markup). The marker convention: if a
-            // wrapper has no other error list left after we remove ours,
-            // clear data-status="error".
-            const stillHasErrors = wrapper.querySelector<HTMLElement>(
-                '.v-field__hint[role="alert"]',
-            );
-            if (!stillHasErrors && wrapper.dataset.status === 'error') {
-                delete wrapper.dataset.status;
-            }
-        }
-    });
-
-    // Clear aria-invalid + controller-managed aria-describedby additions on
-    // all named controls (we re-apply below).
-    const namedControls = el.querySelectorAll<HTMLElement>(
-        'input[name], select[name], textarea[name]',
-    );
-    namedControls.forEach((control) => {
-        if (control.dataset.vFormManagedInvalid === 'true') {
-            control.removeAttribute('aria-invalid');
-            delete control.dataset.vFormManagedInvalid;
-        }
-        const managedId = control.dataset.vFormManagedDescribedBy;
-        if (managedId) {
-            const existing = control.getAttribute('aria-describedby');
-            if (existing) {
-                const remaining = existing
-                    .split(/\s+/)
-                    .filter((id) => id && id !== managedId);
-                if (remaining.length > 0) {
-                    control.setAttribute(
-                        'aria-describedby',
-                        remaining.join(' '),
-                    );
-                } else {
-                    control.removeAttribute('aria-describedby');
-                }
-            }
-            delete control.dataset.vFormManagedDescribedBy;
-        }
-    });
-
-    // Apply new field errors.
-    for (const [name, errors] of Object.entries(fieldErrors)) {
-        if (errors.length === 0) continue;
-        const control = el.querySelector<HTMLElement>(
-            `[name="${CSS.escape(name)}"]`,
-        );
-        if (!control) continue;
-
-        control.setAttribute('aria-invalid', 'true');
-        control.dataset.vFormManagedInvalid = 'true';
-
-        const wrapper = control.closest<HTMLElement>('.v-field');
-        if (wrapper) {
-            wrapper.dataset.status = 'error';
-
-            // Build the error list with the locked pattern.
-            const controlId = control.id || '';
-            const errorsId = controlId ? `${controlId}-errors` : '';
-            const ul = document.createElement('ul');
-            ul.className = 'v-field__hint';
-            ul.setAttribute('role', 'alert');
-            if (errorsId) ul.id = errorsId;
-            ul.dataset.vFormErrors = 'true';
-            for (const errMsg of errors) {
-                const li = document.createElement('li');
-                li.textContent = errMsg;
-                ul.appendChild(li);
-            }
-            wrapper.appendChild(ul);
-
-            // Update aria-describedby to include the errors ID.
-            if (errorsId) {
-                const existingDescribedBy =
-                    control.getAttribute('aria-describedby');
-                const ids = existingDescribedBy
-                    ? existingDescribedBy.split(/\s+/).filter(Boolean)
-                    : [];
-                if (!ids.includes(errorsId)) {
-                    ids.push(errorsId);
-                    control.setAttribute('aria-describedby', ids.join(' '));
-                    control.dataset.vFormManagedDescribedBy = errorsId;
-                }
-            }
-        }
-    }
-}
-
-/**
- * Render or remove the form-level error summary at the top of the
- * form. If `topErrors` is empty AND there are no field errors needing a
- * summary nudge, the summary is removed entirely.
- */
-function renderErrorSummary(el: HTMLFormElement, topErrors: string[]): void {
-    // Only manage controller-owned summaries (`data-v-form-summary="true"`).
-    // Static consumer-rendered summaries (the `.v-form__error-summary`
-    // template-time block from Form.astro's `errors` prop) are left alone —
-    // the consumer is responsible for clearing them on a re-render.
-    let summary = el.querySelector<HTMLElement>(
-        '.v-form__error-summary[data-v-form-summary="true"]',
-    );
-
-    if (topErrors.length === 0) {
-        if (summary) summary.remove();
-        return;
-    }
-
-    if (!summary) {
-        summary = document.createElement('div');
-        summary.className = 'v-form__error-summary';
-        summary.setAttribute('role', 'alert');
-        summary.setAttribute('aria-live', 'assertive');
-        summary.dataset.vFormSummary = 'true';
-        el.prepend(summary);
-    }
-
-    // Rebuild contents.
-    summary.innerHTML = '';
-    const title = document.createElement('p');
-    title.className = 'v-form__error-summary-title';
-    title.textContent = 'There was a problem';
-    summary.appendChild(title);
-
-    const list = document.createElement('ul');
-    list.className = 'v-form__error-summary-list';
-    for (const errMsg of topErrors) {
-        const li = document.createElement('li');
-        li.textContent = errMsg;
-        list.appendChild(li);
-    }
-    summary.appendChild(list);
-}
-
-/**
- * Render or remove the form-level success status region. Mirrors the
- * Form template's `.v-form__status` element with `aria-live="polite"`.
- */
-function renderStatusMessage(
-    el: HTMLFormElement,
-    message: string | undefined,
-): void {
-    // Only manage controller-owned status (`data-v-form-status="true"`).
-    // Static consumer-rendered status regions are left alone.
-    let status = el.querySelector<HTMLElement>(
-        '.v-form__status[data-v-form-status="true"]',
-    );
-
-    if (!message) {
-        if (status) status.remove();
-        return;
-    }
-
-    if (!status) {
-        status = document.createElement('div');
-        status.className = 'v-form__status';
-        status.setAttribute('aria-live', 'polite');
-        status.dataset.vFormStatus = 'true';
-
-        // Insert before `.v-form__actions` if present so the layout matches
-        // the template; otherwise append.
-        const actions = el.querySelector<HTMLElement>('.v-form__actions');
-        if (actions) {
-            el.insertBefore(status, actions);
-        } else {
-            el.appendChild(status);
-        }
-    }
-    status.textContent = message;
-}
-
-/**
- * Clear all controller-rendered errors (per-field + summary) and the
- * status region. Called when the form transitions into the busy state
- * (so prior errors don't linger while the consumer's onSubmit runs).
- */
-function clearAllErrors(el: HTMLFormElement): void {
-    applyFieldErrors(el, {});
-    renderErrorSummary(el, []);
-}
-
-/**
- * Set or clear the form's busy state. Sets `aria-busy="true"` (per the
- * boolean-attr-only-when-truthy rule) and disables the implicit submit
- * button so consumers can't double-submit. The submit button is
- * identified as `<button type="submit">` inside the form.
- */
-function setBusy(el: HTMLFormElement, busyState: boolean): void {
-    if (busyState) {
-        el.setAttribute('aria-busy', 'true');
-    } else {
-        el.removeAttribute('aria-busy');
-    }
-    const submitBtn = el.querySelector<HTMLButtonElement>(
-        'button[type="submit"]',
-    );
-    if (submitBtn) {
-        if (busyState) {
-            submitBtn.disabled = true;
-            submitBtn.dataset.vFormManagedDisabled = 'true';
-        } else if (submitBtn.dataset.vFormManagedDisabled === 'true') {
-            submitBtn.disabled = false;
-            delete submitBtn.dataset.vFormManagedDisabled;
-        }
-    }
-}

package/utils/controllers/index.ts

@@ -1,39 +0,0 @@
-// Controllers are added as components are built (Phase 1+).
-// See packages/ui/CONVENTIONS.md § Controller mount-on-element pattern.
-export { mountDialog } from './dialog.js';
-export type { DialogControl, DialogConfig } from './dialog.js';
-
-export { mountSidebar, isHrefActive, deriveGroupKey } from './sidebar.js';
-export type { SidebarControl, SidebarConfig } from './sidebar.js';
-
-export { mountForm } from './form.js';
-export type { FormConfig } from './form.js';
-
-export { mountNumberField } from './number-field.js';
-export type { NumberFieldConfig } from './number-field.js';
-
-export { mountToast, toast } from './toast.js';
-export type {
-    ToastTone,
-    ToastOptions,
-    ToastConfig,
-    ToastPosition,
-} from './toast.js';
-
-export { mountDisclosure } from './disclosure.js';
-export type { DisclosureConfig } from './disclosure.js';
-
-export { mountPopover } from './popover.js';
-export type { PopoverControl, PopoverConfig, Placement } from './popover.js';
-
-export { mountMenu } from './menu.js';
-export type { MenuConfig } from './menu.js';
-
-export { mountTagsInput } from './tags-input.js';
-export type { TagsInputConfig } from './tags-input.js';
-
-export { mountInputOTP } from './otp.js';
-export type { InputOTPConfig } from './otp.js';
-
-export { mountSlider } from './slider.js';
-export type { SliderConfig } from './slider.js';

package/utils/controllers/number-field.ts

@@ -1,103 +0,0 @@
-/**
- * Configuration for `mountNumberField`. The controller wires the
- * decrement / increment step buttons inside a NumberField wrapper to
- * the inner `<input type="number">`. Native arrow-up / arrow-down
- * keypresses on the input are already handled by the browser; this
- * controller only adds button click handling.
- *
- * `onChange` is an optional observer hook fired after each successful
- * step, receiving the resulting `valueAsNumber`. NaN is passed when
- * the input is empty after the step (rare — `stepUp` / `stepDown`
- * seed an empty input from `min` / 0 per the HTML spec).
- */
-export interface NumberFieldConfig {
-    /** Optional callback fired after a step button changes the value. */
-    onChange?: (value: number) => void;
-}
-
-/**
- * Mount the NumberField controller on `wrapperEl`, which MUST be the
- * `<div class="v-number-field">` wrapper element containing both the
- * `<input class="v-number-field__input">` and the
- * `[data-direction="decrement"|"increment"]` step buttons.
- *
- * Lifecycle (non-stateful per CONVENTIONS — teardown-only signature,
- * matching `mountForm`):
- * 1. On mount: locate the inner input + step buttons, wire `click`
- *    listeners on both buttons.
- * 2. Click on a step button calls native `input.stepDown()` /
- *    `stepUp()`, which respects the `min`, `max`, and `step` HTML
- *    attributes on the `<input type="number">`. The controller does
- *    NOT do its own clamping — the browser owns the math.
- * 3. After mutating the input value, dispatch `input` and `change`
- *    events (both bubbling) so Form's `mountForm` controller — and
- *    Vue's `v-model` indirectly when the framework wraps the same
- *    DOM — observe the change.
- * 4. `teardown()`: removes the click listeners. Returns the same
- *    teardown contract as `mountForm`.
- *
- * Mounting on a wrapper without an inner input or step buttons is a
- * graceful no-op: the controller returns a teardown function that
- * does nothing. This mirrors `mountForm`'s defensive behavior and
- * makes hoisted `querySelectorAll` mounting safe to call on pages
- * that include a NumberField partial only sometimes.
- *
- * Native keyboard interactions on the `<input type="number">` are
- * NOT handled by this controller — the browser already provides:
- *   - ArrowUp / ArrowDown to step
- *   - mouse wheel to step (in some browsers)
- * Page Up / Page Down (large step) and Home / End (jump to min/max)
- * are documented as out-of-scope for v1; see the NumberField audit
- * entry in CONVENTIONS for rationale.
- */
-export function mountNumberField(
-    wrapperEl: HTMLElement,
-    config: NumberFieldConfig = {},
-): () => void {
-    const input = wrapperEl.querySelector<HTMLInputElement>(
-        'input.v-number-field__input',
-    );
-    if (!input) {
-        // Graceful no-op: wrapper is missing the inner input.
-        return () => {};
-    }
-
-    const decrementBtn = wrapperEl.querySelector<HTMLButtonElement>(
-        '[data-direction="decrement"]',
-    );
-    const incrementBtn = wrapperEl.querySelector<HTMLButtonElement>(
-        '[data-direction="increment"]',
-    );
-
-    const onChange = config.onChange;
-
-    function step(direction: 'decrement' | 'increment'): void {
-        if (!input || input.disabled) return;
-        if (direction === 'decrement') {
-            input.stepDown();
-        } else {
-            input.stepUp();
-        }
-        // Dispatch native events so Form's controller, Vue's v-model,
-        // and any consumer-attached listeners see the change.
-        input.dispatchEvent(new Event('input', { bubbles: true }));
-        input.dispatchEvent(new Event('change', { bubbles: true }));
-        onChange?.(input.valueAsNumber);
-    }
-
-    function handleDecrement(): void {
-        step('decrement');
-    }
-
-    function handleIncrement(): void {
-        step('increment');
-    }
-
-    decrementBtn?.addEventListener('click', handleDecrement);
-    incrementBtn?.addEventListener('click', handleIncrement);
-
-    return function teardown(): void {
-        decrementBtn?.removeEventListener('click', handleDecrement);
-        incrementBtn?.removeEventListener('click', handleIncrement);
-    };
-}