@pienter/ui 0.3.0 → 0.5.0

package/utils/controllers/toast.ts

@@ -1,426 +0,0 @@
-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;
-    };
-}