@pienter/ui 0.2.0

package/utils/controllers/toast.ts

@@ -0,0 +1,426 @@
+import { announce } from '../a11y/live-region.js';
+import { icons, type IconName } from '../../icons/index.js';
+
+/**
+ * Toast tones (parity with Toast.vue / Toast.astro). Drives the
+ * `data-tone` attribute on the rendered toast and the default icon
+ * selection inside `renderToastEl`.
+ */
+export type ToastTone = 'brand' | 'success' | 'warning' | 'danger';
+
+export type ToastPosition =
+    | 'bottom-right'
+    | 'bottom-center'
+    | 'bottom-left'
+    | 'top-right'
+    | 'top-center'
+    | 'top-left';
+
+/**
+ * Options accepted by `toast.show(opts)` and `toast.queue` items.
+ *
+ * `duration` is in milliseconds; `0` disables auto-dismiss (the
+ * toast stays until dismissed manually or via `toast.dismiss(id)`).
+ * `action` adds a single action button alongside the close button;
+ * clicking it invokes `onClick` and then dismisses the toast.
+ */
+export interface ToastOptions {
+    title: string;
+    message?: string;
+    tone?: ToastTone;
+    /** Milliseconds. `0` disables auto-dismiss. Default `defaultDuration`. */
+    duration?: number;
+    action?: { label: string; onClick: () => void };
+    /** Optional icon name override; defaults to the tone-mapped icon. */
+    icon?: IconName;
+    /** Optional ID for manual dismiss; auto-generated if omitted. */
+    id?: string;
+}
+
+export interface ToastConfig {
+    /** Maximum visible toasts; queued toasts wait until a slot opens. Default `3`. */
+    maxVisible?: number;
+    /** Default auto-dismiss duration in ms. Default `5000`. */
+    defaultDuration?: number;
+    /** Container position. v1 ships `bottom-right` only; others reserved. */
+    position?: ToastPosition;
+}
+
+interface ActiveToast {
+    id: string;
+    el: HTMLElement;
+    duration: number;
+    timerId: number | null;
+    remaining: number;
+    startedAt: number;
+}
+
+const toneIconMap: Record<ToastTone, IconName> = {
+    brand: 'info',
+    success: 'circle-check',
+    warning: 'alert-triangle',
+    danger: 'circle-alert',
+};
+
+const config: Required<ToastConfig> = {
+    maxVisible: 3,
+    defaultDuration: 5000,
+    position: 'bottom-right',
+};
+
+const queued: ToastOptions[] = [];
+const active: ActiveToast[] = [];
+let regionEl: HTMLElement | null = null;
+let nextIdCounter = 0;
+
+function generateToastId(): string {
+    nextIdCounter += 1;
+    return `v-toast-${Date.now().toString(36)}-${nextIdCounter}`;
+}
+
+function escapeHtml(value: string): string {
+    return value
+        .replace(/&/g, '&amp;')
+        .replace(/</g, '&lt;')
+        .replace(/>/g, '&gt;')
+        .replace(/"/g, '&quot;')
+        .replace(/'/g, '&#39;');
+}
+
+/**
+ * Lazily create the global region container on first `show()`. The
+ * region is `role="region" aria-label="Notifications"` per the
+ * locked CONVENTIONS rule — distinct from the global ARIA live
+ * region (which is a separate visually-hidden node managed by
+ * `utils/a11y/live-region.ts:announce()`). The two responsibilities
+ * are intentionally separate: the region is the visual container,
+ * the live region is the SR announcement channel.
+ */
+function ensureRegion(): HTMLElement {
+    if (regionEl && document.body.contains(regionEl)) return regionEl;
+    const el = document.createElement('div');
+    el.id = 'v-toast-region';
+    el.className = 'v-toast-region';
+    el.setAttribute('role', 'region');
+    el.setAttribute('aria-label', 'Notifications');
+    el.setAttribute('data-position', config.position);
+    document.body.appendChild(el);
+    regionEl = el;
+    return el;
+}
+
+function buildToastInnerHTML(opts: ToastOptions): string {
+    const iconName: IconName =
+        opts.icon ?? (opts.tone ? toneIconMap[opts.tone] : 'info');
+    const iconSvg = icons[iconName];
+    const xSvg = icons['x'];
+    return [
+        `<span class="v-toast__icon" aria-hidden="true">${iconSvg}</span>`,
+        '<div class="v-toast__body">',
+        `<p class="v-toast__title">${escapeHtml(opts.title)}</p>`,
+        opts.message
+            ? `<p class="v-toast__msg">${escapeHtml(opts.message)}</p>`
+            : '',
+        '</div>',
+        opts.action
+            ? `<button class="v-toast__action" type="button">${escapeHtml(opts.action.label)}</button>`
+            : '',
+        `<button class="v-toast__close" type="button" aria-label="Close">${xSvg}</button>`,
+    ].join('');
+}
+
+/**
+ * Render the toast wrapper element matching Toast.vue / Toast.astro
+ * markup so the same `toast.css` styles apply. Wires close + action
+ * + hover/focus pause/resume listeners. The element is returned
+ * un-mounted; callers append into the region.
+ */
+function renderToastEl(opts: ToastOptions, id: string): HTMLElement {
+    const el = document.createElement('div');
+    el.className = 'v-toast';
+    if (opts.tone) el.setAttribute('data-tone', opts.tone);
+    el.setAttribute('data-toast-id', id);
+    // No `role` here — `announce()` already covers SR announcement, and
+    // double-announcing (visual `role="status"` + live region) is the
+    // common Toast a11y bug. See components/feedback/toast/AUDIT.md.
+    el.innerHTML = buildToastInnerHTML(opts);
+
+    el.querySelector<HTMLButtonElement>('.v-toast__close')?.addEventListener(
+        'click',
+        () => {
+            dismissByEl(el);
+        },
+    );
+    if (opts.action) {
+        el.querySelector<HTMLButtonElement>(
+            '.v-toast__action',
+        )?.addEventListener('click', () => {
+            opts.action!.onClick();
+            dismissByEl(el);
+        });
+    }
+    el.addEventListener('mouseenter', () => pauseEl(el));
+    el.addEventListener('mouseleave', () => resumeEl(el));
+    el.addEventListener('focusin', () => pauseEl(el));
+    el.addEventListener('focusout', () => resumeEl(el));
+    el.addEventListener('keydown', (event) => {
+        if (event.key === 'Escape') {
+            event.preventDefault();
+            dismissByEl(el);
+        }
+    });
+
+    return el;
+}
+
+function findActiveByEl(el: HTMLElement): ActiveToast | undefined {
+    return active.find((a) => a.el === el);
+}
+
+function findActiveById(id: string): ActiveToast | undefined {
+    return active.find((a) => a.id === id);
+}
+
+function startTimer(entry: ActiveToast): void {
+    if (entry.duration <= 0) return; // persistent
+    if (entry.timerId !== null) return; // already running
+    entry.startedAt = Date.now();
+    entry.timerId = window.setTimeout(() => {
+        entry.timerId = null;
+        dismissEntry(entry);
+    }, entry.remaining);
+}
+
+function pauseTimer(entry: ActiveToast): void {
+    if (entry.timerId === null) return;
+    window.clearTimeout(entry.timerId);
+    entry.timerId = null;
+    const elapsed = Date.now() - entry.startedAt;
+    entry.remaining = Math.max(0, entry.remaining - elapsed);
+}
+
+function pauseEl(el: HTMLElement): void {
+    const entry = findActiveByEl(el);
+    if (entry) pauseTimer(entry);
+}
+
+function resumeEl(el: HTMLElement): void {
+    const entry = findActiveByEl(el);
+    if (entry) startTimer(entry);
+}
+
+function dismissEntry(entry: ActiveToast): void {
+    if (entry.timerId !== null) {
+        window.clearTimeout(entry.timerId);
+        entry.timerId = null;
+    }
+    if (entry.el.parentNode) {
+        entry.el.parentNode.removeChild(entry.el);
+    }
+    const idx = active.indexOf(entry);
+    if (idx !== -1) active.splice(idx, 1);
+    drainQueue();
+}
+
+function dismissByEl(el: HTMLElement): void {
+    const entry = findActiveByEl(el);
+    if (entry) dismissEntry(entry);
+}
+
+function drainQueue(): void {
+    while (active.length < config.maxVisible && queued.length > 0) {
+        const next = queued.shift()!;
+        showNow(next);
+    }
+}
+
+function showNow(opts: ToastOptions): string {
+    const region = ensureRegion();
+    const id = opts.id ?? generateToastId();
+    const duration = opts.duration ?? config.defaultDuration;
+    const el = renderToastEl(opts, id);
+    region.appendChild(el);
+
+    const entry: ActiveToast = {
+        id,
+        el,
+        duration,
+        timerId: null,
+        remaining: duration,
+        startedAt: Date.now(),
+    };
+    active.push(entry);
+
+    // Announce via the global SR live region. Danger tone is assertive;
+    // everything else polite. The announcement uses title (+ message).
+    const announceText = opts.message
+        ? `${opts.title}. ${opts.message}`
+        : opts.title;
+    announce(announceText, opts.tone === 'danger' ? 'assertive' : 'polite');
+
+    startTimer(entry);
+    return id;
+}
+
+/**
+ * Module-level singleton API per the singleton-controller exception
+ * documented in CONVENTIONS § Controller mount-on-element pattern.
+ *
+ * Toast manages a single global queue + region; consumers call
+ * `toast.show({ tone, title, message })` rather than rendering the
+ * `<Toast>` component themselves. Returns the assigned id so callers
+ * can dismiss programmatically via `toast.dismiss(id)`.
+ *
+ * `toast.configure({ maxVisible, defaultDuration, position })` mutates
+ * the module-level config; call once on app init if the defaults
+ * (`maxVisible: 3`, `defaultDuration: 5000`, `position: 'bottom-right'`)
+ * need overriding. v1 only ships `bottom-right`; other positions are
+ * accepted by the type but not yet styled.
+ */
+export const toast = {
+    show(opts: ToastOptions): string {
+        if (active.length >= config.maxVisible) {
+            const queuedOpts = { ...opts, id: opts.id ?? generateToastId() };
+            queued.push(queuedOpts);
+            return queuedOpts.id;
+        }
+        return showNow(opts);
+    },
+
+    dismiss(id: string): void {
+        const entry = findActiveById(id);
+        if (entry) {
+            dismissEntry(entry);
+            return;
+        }
+        const queueIdx = queued.findIndex((q) => q.id === id);
+        if (queueIdx !== -1) queued.splice(queueIdx, 1);
+    },
+
+    dismissAll(): void {
+        queued.length = 0;
+        // Snapshot active because dismissEntry mutates the array.
+        const snapshot = [...active];
+        for (const entry of snapshot) dismissEntry(entry);
+    },
+
+    configure(c: ToastConfig): void {
+        if (typeof c.maxVisible === 'number' && c.maxVisible > 0) {
+            config.maxVisible = Math.floor(c.maxVisible);
+        }
+        if (typeof c.defaultDuration === 'number' && c.defaultDuration >= 0) {
+            config.defaultDuration = c.defaultDuration;
+        }
+        if (c.position) {
+            config.position = c.position;
+            if (regionEl) regionEl.setAttribute('data-position', c.position);
+        }
+        drainQueue();
+    },
+};
+
+/**
+ * Per-instance escape hatch for consumers who render a `<Toast>`
+ * declaratively (Astro `<Toast>` or `<Toast>` Vue component) and
+ * want the controller to manage close-button wiring, action wiring,
+ * hover/focus pause-resume, and auto-dismiss timing. Returns a
+ * teardown function per the canonical mount signature.
+ *
+ * Most consumers should use the module-level `toast.show()` API
+ * instead. This is a fallback for cases where the toast DOM is
+ * authored declaratively and the controller layers behavior on top.
+ *
+ * Note: `mountToast(el)` does NOT add `el` to the global `active`
+ * queue, because the consumer owns the DOM placement (it isn't in
+ * the controller's region container). The lifecycle is local to
+ * `el` only — close button, action button, hover/focus pause-resume,
+ * auto-dismiss timer (if duration provided), Escape-to-dismiss on
+ * the rendered element. Calling `dismiss()` removes `el` from its
+ * parent.
+ */
+export function mountToast(
+    el: HTMLElement,
+    opts: { duration?: number; onDismiss?: () => void } = {},
+): () => void {
+    const duration = opts.duration ?? 0; // default to no auto-dismiss for declarative usage
+    let timerId: number | null = null;
+    let remaining = duration;
+    let startedAt = Date.now();
+    let dismissed = false;
+
+    function dismiss(): void {
+        if (dismissed) return;
+        dismissed = true;
+        if (timerId !== null) {
+            window.clearTimeout(timerId);
+            timerId = null;
+        }
+        el.removeEventListener('mouseenter', pause);
+        el.removeEventListener('mouseleave', resume);
+        el.removeEventListener('focusin', pause);
+        el.removeEventListener('focusout', resume);
+        closeBtn?.removeEventListener('click', onClose);
+        actionBtn?.removeEventListener('click', onAction);
+        el.removeEventListener('keydown', onKeydown);
+        if (el.parentNode) el.parentNode.removeChild(el);
+        opts.onDismiss?.();
+    }
+
+    function start(): void {
+        if (duration <= 0 || timerId !== null) return;
+        startedAt = Date.now();
+        timerId = window.setTimeout(() => {
+            timerId = null;
+            dismiss();
+        }, remaining);
+    }
+    function pause(): void {
+        if (timerId === null) return;
+        window.clearTimeout(timerId);
+        timerId = null;
+        remaining = Math.max(0, remaining - (Date.now() - startedAt));
+    }
+    function resume(): void {
+        start();
+    }
+    function onClose(): void {
+        dismiss();
+    }
+    function onAction(): void {
+        dismiss();
+    }
+    function onKeydown(event: KeyboardEvent): void {
+        if (event.key === 'Escape') {
+            event.preventDefault();
+            dismiss();
+        }
+    }
+
+    const closeBtn = el.querySelector<HTMLButtonElement>('.v-toast__close');
+    const actionBtn = el.querySelector<HTMLButtonElement>('.v-toast__action');
+    closeBtn?.addEventListener('click', onClose);
+    actionBtn?.addEventListener('click', onAction);
+    el.addEventListener('mouseenter', pause);
+    el.addEventListener('mouseleave', resume);
+    el.addEventListener('focusin', pause);
+    el.addEventListener('focusout', resume);
+    el.addEventListener('keydown', onKeydown);
+
+    start();
+
+    return () => {
+        if (dismissed) return;
+        if (timerId !== null) {
+            window.clearTimeout(timerId);
+            timerId = null;
+        }
+        el.removeEventListener('mouseenter', pause);
+        el.removeEventListener('mouseleave', resume);
+        el.removeEventListener('focusin', pause);
+        el.removeEventListener('focusout', resume);
+        closeBtn?.removeEventListener('click', onClose);
+        actionBtn?.removeEventListener('click', onAction);
+        el.removeEventListener('keydown', onKeydown);
+        dismissed = true;
+    };
+}

package/utils/dom/index.ts

@@ -0,0 +1 @@
+export { lockScroll } from './scroll-lock.js';

package/utils/dom/scroll-lock.ts

@@ -0,0 +1,48 @@
+/**
+ * Reference-counted body scroll lock with scrollbar-width compensation.
+ *
+ * The lock is applied on the first call and released only when the matching
+ * unlock fn is the last outstanding caller. This handles nested overlays
+ * (e.g., a Modal opening an AlertDialog) without one releasing the other's
+ * lock prematurely.
+ *
+ * Scrollbar compensation: when locking, we add the scrollbar's width as
+ * extra `padding-right` on `<body>` so layout doesn't shift when the
+ * scrollbar disappears.
+ */
+
+let lockCount = 0;
+let originalOverflow: string | null = null;
+let originalPaddingRight: string | null = null;
+
+export function lockScroll(): () => void {
+    if (lockCount === 0) {
+        const scrollbarWidth =
+            window.innerWidth - document.documentElement.clientWidth;
+        originalOverflow = document.body.style.overflow;
+        originalPaddingRight = document.body.style.paddingRight;
+        document.body.style.overflow = 'hidden';
+        if (scrollbarWidth > 0) {
+            const computedPaddingRight = parseFloat(
+                getComputedStyle(document.body).paddingRight,
+            );
+            document.body.style.paddingRight = `${
+                computedPaddingRight + scrollbarWidth
+            }px`;
+        }
+    }
+    lockCount += 1;
+
+    let released = false;
+    return function unlock(): void {
+        if (released) return;
+        released = true;
+        lockCount = Math.max(0, lockCount - 1);
+        if (lockCount === 0) {
+            document.body.style.overflow = originalOverflow ?? '';
+            document.body.style.paddingRight = originalPaddingRight ?? '';
+            originalOverflow = null;
+            originalPaddingRight = null;
+        }
+    };
+}

package/utils/index.ts

@@ -0,0 +1,3 @@
+export * from './a11y/index.js';
+export * from './sort/index.js';
+export * from './validation/index.js';

package/utils/sort/index.ts

@@ -0,0 +1,3 @@
+export { toggleSort } from './state.js';
+export { parseSort, formatSort } from './serialize.js';
+export type { Sort, SortDirection, SortState } from './types.js';

package/utils/sort/serialize.ts

@@ -0,0 +1,19 @@
+// Wire form of a sort state: the column key, `-`-prefixed for descending, absent when unsorted.
+// A column key must not itself start with `-`, since that prefix is how direction is encoded.
+import type { SortState } from './types.js';
+
+/** Read the wire form. Anything unparseable is treated as unsorted. */
+export function parseSort(raw: string | null | undefined): SortState {
+    if (!raw) return null;
+    const descending = raw.startsWith('-');
+    const key = descending ? raw.slice(1) : raw;
+    // a bare '-' carries no column, so it is unsorted rather than a key of ''
+    if (!key) return null;
+    return { key, direction: descending ? 'desc' : 'asc' };
+}
+
+/** Write the wire form. `null` when unsorted — the cue to drop the parameter entirely. */
+export function formatSort(state: SortState): string | null {
+    if (!state) return null;
+    return (state.direction === 'desc' ? '-' : '') + state.key;
+}

package/utils/sort/state.ts

@@ -0,0 +1,11 @@
+import type { SortState } from './types.js';
+
+/**
+ * The sort state activating `key` should produce: ascending → descending → unsorted,
+ * restarting ascending on a different column. Pure; swap it out for another cycle.
+ */
+export function toggleSort(state: SortState, key: string): SortState {
+    if (state?.key !== key) return { key, direction: 'asc' };
+    if (state.direction === 'asc') return { key, direction: 'desc' };
+    return null;
+}

package/utils/sort/types.ts

@@ -0,0 +1,15 @@
+/** Direction of the sorted column. */
+export type SortDirection = 'asc' | 'desc';
+
+/** One column, sorted one way. */
+export interface Sort {
+    /** The sorted column — matches a `Column.key` on a table. */
+    key: string;
+    direction: SortDirection;
+}
+
+/**
+ * Sort state of a list. `null` is unsorted — a real state meaning "original order",
+ * reached on a column's third activation. One column at a time (ADR 0005).
+ */
+export type SortState = Sort | null;

package/utils/validation/form.ts

@@ -0,0 +1,93 @@
+import { type Validator, validate } from './rules.js';
+
+/**
+ * Placeholder shape for form-submit responses, consumed identically by both
+ * `Form.vue` (reactive orchestration) and `controllers/form.ts:mountForm`
+ * (Astro imperative orchestration). The symmetry requirement is locked in
+ * design D13 / spec "Unified Form Submit Response Handling"; the exact
+ * shape is **subject to change when ts-sdk publishes the canonical
+ * response shape**, at which point both implementations are updated
+ * together.
+ */
+export interface FormSubmitResponse {
+    /** Whether the submit succeeded. */
+    ok: boolean;
+    /** Per-field errors keyed by field `name`. Single string or array of strings. */
+    fieldErrors?: Record<string, string | string[]>;
+    /** Top-level errors not tied to a specific field (e.g., "Something went wrong"). */
+    errors?: string[];
+    /** Success/status message to announce via aria-live. */
+    statusMessage?: string;
+    /**
+     * Optional post-submit redirect URL — orchestration does NOT auto-navigate
+     * (consumer's call); the value is just stored on the response for the
+     * consumer to act on.
+     */
+    redirect?: string;
+}
+
+/**
+ * Run a per-field validator map against a `FormData` instance and return
+ * a `Record<string, string[]>` of field errors. Pure function; framework
+ * agnostic. Used by both Vue and Astro Form orchestration.
+ *
+ * Field values are read via `formData.get(name)` and coerced to strings.
+ * Fields without an entry in `validators` are not checked. Fields whose
+ * validators all return `null` are omitted from the result entirely
+ * (rather than mapped to an empty array) so consumers can tell errors
+ * apart from "validated, passed".
+ *
+ * Note: validators receive `formData.get(name)` (single value). For
+ * multi-value fields (`<select multiple>`, repeated `<input name="x">`
+ * checkboxes, future TagsInput), the controller will need a multi-value
+ * path — out of scope for v1; revisit when the first multi-value
+ * primitive ships.
+ */
+export function validateFormData(
+    formData: FormData,
+    validators?: Record<string, Validator[]>,
+): Record<string, string[]> {
+    const result: Record<string, string[]> = {};
+    if (!validators) return result;
+
+    for (const [name, fieldValidators] of Object.entries(validators)) {
+        const raw = formData.get(name);
+        let value: string;
+        if (typeof raw === 'string') {
+            value = raw;
+        } else if (raw == null) {
+            value = '';
+        } else {
+            // v1 validators are string-only; a `File` entry (multi-value support
+            // is out of scope, see the function doc) has no meaningful string
+            // form here — coerce and let the string validators run.
+            value = String(raw);
+        }
+        const fieldErrors = validate(value, fieldValidators);
+        if (fieldErrors.length > 0) {
+            result[name] = fieldErrors;
+        }
+    }
+
+    return result;
+}
+
+/**
+ * Normalize the per-field error map carried on a `FormSubmitResponse`
+ * (where each entry can be a string or array of strings) into the
+ * `Record<string, string[]>` shape used internally by orchestration.
+ */
+export function normalizeFieldErrors(
+    fieldErrors: Record<string, string | string[]> | undefined,
+): Record<string, string[]> {
+    if (!fieldErrors) return {};
+    const result: Record<string, string[]> = {};
+    for (const [name, value] of Object.entries(fieldErrors)) {
+        if (Array.isArray(value)) {
+            if (value.length > 0) result[name] = value;
+        } else if (value) {
+            result[name] = [value];
+        }
+    }
+    return result;
+}

package/utils/validation/index.ts

@@ -0,0 +1,13 @@
+export {
+    type ValidationResult,
+    type Validator,
+    isRequired,
+    isEmail,
+    minLength,
+    validate,
+} from './rules.js';
+export {
+    type FormSubmitResponse,
+    validateFormData,
+    normalizeFieldErrors,
+} from './form.js';

package/utils/validation/rules.ts

@@ -0,0 +1,31 @@
+export type ValidationResult = string | null;
+export type Validator = (value: string) => ValidationResult;
+
+export function isRequired(message = 'This field is required'): Validator {
+    return (value: string) => (value.trim() === '' ? message : null);
+}
+
+export function isEmail(
+    message = 'Please enter a valid email address',
+): Validator {
+    return (value: string) =>
+        /^[^\s@]+@[^\s@]+\.[^\s@]+$/.test(value) ? null : message;
+}
+
+export function minLength(min: number, message?: string): Validator {
+    return (value: string) =>
+        value.length >= min
+            ? null
+            : (message ?? `Must be at least ${min} characters`);
+}
+
+export function validate(value: string, validators: Validator[]): string[] {
+    const errors: string[] = [];
+    for (const validator of validators) {
+        const result = validator(value);
+        if (result !== null) {
+            errors.push(result);
+        }
+    }
+    return errors;
+}