@pienter/ui 0.2.0

package/utils/controllers/menu.ts

@@ -0,0 +1,255 @@
+/**
+ * Menu controller — keyboard navigation for `role="menu"` surfaces.
+ * Pairs with `mountPopover` (which owns open/close/positioning) to
+ * provide the menu-specific affordances per the WAI-ARIA Menu
+ * pattern: ArrowDown/Up cycle through items with wrap, Home/End
+ * jump to the ends, Escape closes via the consumer-supplied
+ * callback, and a click on a menu item triggers the
+ * activate-and-close consumer callback (`onItemActivate`).
+ *
+ * The controller treats the items as a roving-tabindex group: only
+ * the focused item carries `tabindex="0"`; the rest carry
+ * `tabindex="-1"`. This is the canonical menu pattern — Tab moves
+ * focus past the menu rather than walking through every item.
+ *
+ * Mount on:
+ * - The menu container element (the element that carries
+ *   `role="menu"`). Items are queried inside the container via
+ *   `itemSelector` (default covers `menuitem`,
+ *   `menuitemcheckbox`, and `menuitemradio` roles).
+ *
+ * Item discovery is lazy — the keydown handler re-queries on every
+ * navigation event so consumers may add/remove menu items at
+ * runtime (for e.g., async-loaded items or filter views) without
+ * remounting the controller.
+ *
+ * The controller does NOT decide when to close; consumers wire
+ * `onEscape` and `onItemActivate` to their popover control's
+ * `hide()` (the standard dropdown menu UX is auto-close on activate).
+ */
+
+export interface MenuConfig {
+    /**
+     * The menu container element with `role="menu"`. Items are
+     * resolved by querying this element with `itemSelector`.
+     */
+    menuEl: HTMLElement;
+    /**
+     * Selector matching the menu items. Defaults to all three
+     * canonical menuitem roles so the same controller serves
+     * vanilla menus, checkbox-style menus, and radio-style menus.
+     * Override when the consumer needs to filter (e.g. exclude a
+     * group label) — but the role-based default is correct for the
+     * v1 DropdownMenu component.
+     */
+    itemSelector?: string;
+    /**
+     * Called when Escape is pressed inside the menu. The consumer
+     * typically forwards to `popoverControl.hide()` so the menu
+     * closes and focus returns to the trigger.
+     */
+    onEscape?: () => void;
+    /**
+     * Called when a menu item is activated by pointer click or by
+     * Enter / Space on the focused item. The consumer typically
+     * forwards to `popoverControl.hide()` so the menu auto-closes
+     * after a selection — the standard menu UX. Item-specific
+     * actions (the consumer's `@click` handler on each
+     * `<button role="menuitem">`) run independently from this
+     * callback; the consumer's handler runs first, then this
+     * callback closes the menu.
+     */
+    onItemActivate?: (item: HTMLElement) => void;
+}
+
+const DEFAULT_ITEM_SELECTOR =
+    '[role="menuitem"], [role="menuitemcheckbox"], [role="menuitemradio"]';
+
+/**
+ * Wire menu-style keyboard navigation onto a `role="menu"`
+ * container. Returns a teardown function that removes the
+ * listeners and restores any tabindex attributes the controller
+ * managed.
+ *
+ * Lifecycle:
+ * 1. On mount: set `tabindex="-1"` on every item (only the
+ *    currently-focused item gets `tabindex="0"` after the menu
+ *    opens and the consumer focuses the first item). The first
+ *    focus event inside the menu promotes that item.
+ * 2. On `keydown` inside the menu:
+ *    - ArrowDown moves to the next item; wraps to first.
+ *    - ArrowUp moves to the previous item; wraps to last.
+ *    - Home jumps to the first item.
+ *    - End jumps to the last item.
+ *    - Escape calls `onEscape`.
+ *    - Enter / Space on an item calls `onItemActivate(item)` and
+ *      lets the native click behavior of `<button>` items run on
+ *      the same key. (Native `<button>` already triggers click on
+ *      Enter/Space, so we only call `onItemActivate` to close;
+ *      the consumer's click handler runs from the synthetic
+ *      click.)
+ * 3. On click of an item: call `onItemActivate(item)`. The
+ *    consumer's own click handler runs first (DOM event bubbles
+ *    bottom-up; we listen on the menu container).
+ * 4. On `focus` inside the menu (capture): re-rove the tabindex
+ *    so only the focused item has `tabindex="0"`.
+ *
+ * Cross-cutting:
+ * - Disabled items (`[disabled]` or `aria-disabled="true"`) are
+ *   skipped during arrow / Home / End navigation. They remain in
+ *   the DOM and can still receive direct clicks (native
+ *   `disabled` already blocks that), but the keyboard path
+ *   skips them so users do not get "stuck" on a non-actionable
+ *   item.
+ */
+export function mountMenu(config: MenuConfig): () => void {
+    const menuEl = config.menuEl;
+    const itemSelector = config.itemSelector ?? DEFAULT_ITEM_SELECTOR;
+
+    function getItems(): HTMLElement[] {
+        return Array.from(menuEl.querySelectorAll<HTMLElement>(itemSelector));
+    }
+
+    function isDisabled(item: HTMLElement): boolean {
+        return (
+            item.hasAttribute('disabled') ||
+            item.getAttribute('aria-disabled') === 'true'
+        );
+    }
+
+    function getEnabledItems(): HTMLElement[] {
+        return getItems().filter((it) => !isDisabled(it));
+    }
+
+    // Initial roving tabindex — every item starts at `-1`. The
+    // first item is promoted to `0` so a Tab into the menu (rare —
+    // the trigger usually opens with explicit focus) lands somewhere.
+    function initRovingTabindex(): void {
+        const items = getItems();
+        items.forEach((item, idx) => {
+            // Don't override an explicit author tabindex on disabled items;
+            // for active items, the first enabled item gets `0` and the
+            // rest get `-1`.
+            if (isDisabled(item)) {
+                item.setAttribute('tabindex', '-1');
+                return;
+            }
+            const firstEnabledIdx = items.findIndex((i) => !isDisabled(i));
+            item.setAttribute('tabindex', idx === firstEnabledIdx ? '0' : '-1');
+        });
+    }
+
+    initRovingTabindex();
+
+    function focusItem(item: HTMLElement): void {
+        // Promote the focus target to `tabindex="0"` and demote the
+        // rest to `-1` BEFORE focusing — focus on a `tabindex="-1"`
+        // element works fine, but the rove must reflect the new state
+        // so a subsequent Tab leaves the menu cleanly.
+        const items = getItems();
+        items.forEach((it) => {
+            it.setAttribute('tabindex', it === item ? '0' : '-1');
+        });
+        item.focus();
+    }
+
+    function moveFocus(direction: 1 | -1): void {
+        const enabled = getEnabledItems();
+        if (enabled.length === 0) return;
+
+        const active = document.activeElement as HTMLElement | null;
+        const currentIdx = active ? enabled.indexOf(active) : -1;
+
+        let nextIdx: number;
+        if (currentIdx === -1) {
+            // Focus is not on any enabled item (could be on the menu
+            // container itself, or a disabled item). Land on the first
+            // for ArrowDown, last for ArrowUp.
+            nextIdx = direction === 1 ? 0 : enabled.length - 1;
+        } else {
+            nextIdx =
+                (currentIdx + direction + enabled.length) % enabled.length;
+        }
+
+        focusItem(enabled[nextIdx]!);
+    }
+
+    function focusFirst(): void {
+        const enabled = getEnabledItems();
+        if (enabled.length > 0) focusItem(enabled[0]!);
+    }
+
+    function focusLast(): void {
+        const enabled = getEnabledItems();
+        if (enabled.length > 0) focusItem(enabled[enabled.length - 1]!);
+    }
+
+    function onKeydown(event: KeyboardEvent): void {
+        switch (event.key) {
+            case 'ArrowDown':
+                event.preventDefault();
+                moveFocus(1);
+                break;
+            case 'ArrowUp':
+                event.preventDefault();
+                moveFocus(-1);
+                break;
+            case 'Home':
+                event.preventDefault();
+                focusFirst();
+                break;
+            case 'End':
+                event.preventDefault();
+                focusLast();
+                break;
+            case 'Escape':
+                // The native Popover API also closes on Escape via
+                // `popover="auto"` light-dismiss; calling `onEscape`
+                // here lets consumers using `popover="manual"` (or
+                // future variants) hook the same key. We do NOT
+                // preventDefault — the browser's light-dismiss should
+                // still run for `auto` popovers.
+                config.onEscape?.();
+                break;
+            default:
+                break;
+        }
+    }
+
+    function onClick(event: MouseEvent): void {
+        const target = event.target as HTMLElement | null;
+        if (!target) return;
+        const item = target.closest<HTMLElement>(itemSelector);
+        if (!item || !menuEl.contains(item)) return;
+        if (isDisabled(item)) return;
+        config.onItemActivate?.(item);
+    }
+
+    function onFocusIn(event: FocusEvent): void {
+        const target = event.target as HTMLElement | null;
+        if (!target) return;
+        const item = target.closest<HTMLElement>(itemSelector);
+        if (!item || !menuEl.contains(item) || isDisabled(item)) return;
+        // Re-rove so only the freshly-focused item carries
+        // `tabindex="0"`. This catches focus that didn't go through
+        // `focusItem` (e.g., a click that focused an item directly).
+        const items = getItems();
+        items.forEach((it) => {
+            it.setAttribute('tabindex', it === item ? '0' : '-1');
+        });
+    }
+
+    menuEl.addEventListener('keydown', onKeydown);
+    menuEl.addEventListener('click', onClick);
+    menuEl.addEventListener('focusin', onFocusIn);
+
+    return function teardown(): void {
+        menuEl.removeEventListener('keydown', onKeydown);
+        menuEl.removeEventListener('click', onClick);
+        menuEl.removeEventListener('focusin', onFocusIn);
+        // Leave items' tabindex attributes as-is — if the menu
+        // remounts, `initRovingTabindex` will re-apply correct values.
+        // Removing them risks stomping author-supplied tabindex
+        // attributes the controller didn't set originally.
+    };
+}

package/utils/controllers/number-field.ts

@@ -0,0 +1,103 @@
+/**
+ * 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);
+    };
+}

package/utils/controllers/otp.ts

@@ -0,0 +1,252 @@
+/**
+ * Configuration for `mountInputOTP`. The controller wires N
+ * `<input class="v-input-otp__slot">` single-character inputs inside
+ * an InputOTP wrapper for the canonical one-time-code UX:
+ *  - Type a character matching `pattern` → fill, advance focus.
+ *  - Backspace on a filled slot → clear it (focus stays).
+ *  - Backspace on an empty slot → focus + clear the previous slot.
+ *  - Arrow Left / Right → move focus between slots.
+ *  - Paste a multi-character string → distribute across slots starting
+ *    from the focused position; characters that fail the pattern are
+ *    silently skipped.
+ *
+ * `onChange` receives the concatenated OTP string after every change.
+ * Empty slots are represented as the empty string in the concatenation
+ * (so a partial code like `"12  "` reflects two filled slots and two
+ * empty), keeping the contract simple for consumers building reactive
+ * UIs that need to know when the code is complete (`value.length ===
+ * length` AND `!value.includes(' ')` — the controller emits a
+ * literal-empty for unfilled slots, NOT a space; see implementation).
+ */
+export interface InputOTPConfig {
+    /**
+     * Optional regex used to validate each typed / pasted character.
+     * Defaults to digits-only (`/^[0-9]$/`). Pass an alphanumeric or
+     * uppercase-letter pattern when the OTP code is not a PIN.
+     */
+    pattern?: RegExp;
+    /**
+     * Callback fired on every value change with the concatenated OTP
+     * string. Length always equals the slot count; unfilled slots are
+     * the empty character so consumers can distinguish "fully entered"
+     * from "partial".
+     */
+    onChange?: (value: string) => void;
+}
+
+/**
+ * Mount the InputOTP controller on `wrapperEl`, which MUST be the
+ * `<div class="v-input-otp">` wrapper containing N
+ * `<input class="v-input-otp__slot">` children. The wrapper is the
+ * only DOM the controller modifies (slot focus / value); the surrounding
+ * `.v-field` scaffold (label, hint, errors) is owned by the framework
+ * component.
+ *
+ * Lifecycle (non-stateful per CONVENTIONS — teardown-only signature):
+ * 1. On mount: locate all slot inputs via `.v-input-otp__slot`.
+ * 2. Wire `input`, `keydown`, `paste`, and `focus` listeners on each
+ *    slot. Behaviours:
+ *    - **input**: validate against `pattern`. Reject (clear the slot)
+ *      if invalid; advance focus to the next empty slot if valid and
+ *      not the last.
+ *    - **keydown** Backspace: if the current slot is empty, focus +
+ *      clear the previous; if filled, clear it (stay).
+ *    - **keydown** ArrowLeft / ArrowRight: navigate between slots.
+ *    - **paste**: distribute pasted characters across slots starting
+ *      from the focused index. Pattern-failing characters are skipped
+ *      so a paste of "123-456" with a digit pattern yields "123456".
+ *      Focus lands on the slot after the last filled one (or the last
+ *      slot if all were filled).
+ * 3. Every value change dispatches `input` and `change` events
+ *    (bubbling) on the wrapper element, plus calls `onChange` with
+ *    the joined OTP string. The hidden `<input name>` paired by the
+ *    framework component receives the same value via `dispatchEvent`
+ *    on its element when the wrapper emits.
+ * 4. `teardown()`: removes all listeners. The slot DOM is left in
+ *    place; the framework owns markup cleanup.
+ *
+ * Mounting on a wrapper without slot inputs is a graceful no-op.
+ *
+ * Per CONVENTIONS, the InputOTP wrapper does NOT use `aria-hidden`
+ * or `role="group"` on the slot row — each slot is a native input
+ * with its own `aria-label="Digit N of M"`. The form-primitive
+ * `.v-field` label still applies to the group as a whole; per-slot
+ * labels are screen-reader specific.
+ */
+export function mountInputOTP(
+    wrapperEl: HTMLElement,
+    config: InputOTPConfig = {},
+): () => void {
+    const slots = Array.from(
+        wrapperEl.querySelectorAll<HTMLInputElement>('input.v-input-otp__slot'),
+    );
+    if (slots.length === 0) {
+        // Graceful no-op: wrapper is missing slot inputs.
+        return () => {};
+    }
+
+    const pattern = config.pattern ?? /^[0-9]$/;
+    const onChange = config.onChange;
+
+    // The hidden input the framework component renders for FormData
+    // serialization (named via `:name`). Optional — if absent, the
+    // controller still works for client-only state.
+    const hiddenInput = wrapperEl.querySelector<HTMLInputElement>(
+        'input.v-input-otp__hidden',
+    );
+
+    function readValue(): string {
+        return slots
+            .map((s) => (s.value.length > 0 ? s.value[0] : ''))
+            .join('');
+    }
+
+    function notifyChange(): void {
+        const value = readValue();
+        if (hiddenInput) {
+            hiddenInput.value = value;
+            hiddenInput.dispatchEvent(new Event('input', { bubbles: true }));
+            hiddenInput.dispatchEvent(new Event('change', { bubbles: true }));
+        }
+        onChange?.(value);
+    }
+
+    function focusSlot(index: number): void {
+        const target = slots[index];
+        if (target) {
+            target.focus();
+            // Select the slot's content so a typed digit overwrites cleanly.
+            target.select();
+        }
+    }
+
+    function findThisIndex(target: EventTarget | null): number {
+        if (!(target instanceof HTMLInputElement)) return -1;
+        return slots.indexOf(target);
+    }
+
+    function handleInput(event: Event): void {
+        const idx = findThisIndex(event.target);
+        if (idx === -1) return;
+        const slot = slots[idx];
+        if (!slot) return;
+        const value = slot.value;
+
+        // Native paste / IME may deliver multi-character input — defer to
+        // the paste handler for that case; here, normalize single-char.
+        if (value.length === 0) {
+            notifyChange();
+            return;
+        }
+
+        if (value.length > 1) {
+            // Multi-char input (paste fallback path on browsers that fire
+            // `input` instead of `paste`): keep only the last character if
+            // it matches the pattern; the explicit `paste` handler covers
+            // the typical Cmd+V flow.
+            const last = value[value.length - 1] ?? '';
+            slot.value = pattern.test(last) ? last : '';
+        } else if (!pattern.test(value)) {
+            // Reject invalid character.
+            slot.value = '';
+            notifyChange();
+            return;
+        }
+
+        notifyChange();
+
+        // Advance focus to the next empty slot (or the next slot if all
+        // remaining are filled — matches the Reka UI / shadcn UX).
+        if (slot.value.length === 1 && idx < slots.length - 1) {
+            focusSlot(idx + 1);
+        }
+    }
+
+    function handleKeydown(event: KeyboardEvent): void {
+        const idx = findThisIndex(event.target);
+        if (idx === -1) return;
+        const slot = slots[idx];
+        if (!slot) return;
+
+        if (event.key === 'Backspace') {
+            if (slot.value.length === 0 && idx > 0) {
+                event.preventDefault();
+                const prev = slots[idx - 1];
+                if (prev) {
+                    prev.value = '';
+                    notifyChange();
+                    focusSlot(idx - 1);
+                }
+            } else if (slot.value.length > 0) {
+                // Clear current slot but stay on it — the next Backspace then
+                // moves to the previous (canonical OTP UX).
+                event.preventDefault();
+                slot.value = '';
+                notifyChange();
+            }
+            return;
+        }
+
+        if (event.key === 'ArrowLeft' && idx > 0) {
+            event.preventDefault();
+            focusSlot(idx - 1);
+            return;
+        }
+
+        if (event.key === 'ArrowRight' && idx < slots.length - 1) {
+            event.preventDefault();
+            focusSlot(idx + 1);
+            return;
+        }
+    }
+
+    function handlePaste(event: ClipboardEvent): void {
+        const idx = findThisIndex(event.target);
+        if (idx === -1) return;
+        const data = event.clipboardData?.getData('text') ?? '';
+        if (!data) return;
+        event.preventDefault();
+
+        // Filter to pattern-matching characters; distribute starting at
+        // the focused slot.
+        const valid = Array.from(data).filter((ch) => pattern.test(ch));
+        if (valid.length === 0) return;
+
+        let cursor = idx;
+        for (const ch of valid) {
+            if (cursor >= slots.length) break;
+            const slot = slots[cursor];
+            if (slot) slot.value = ch;
+            cursor += 1;
+        }
+        notifyChange();
+
+        // Land focus on the slot after the last filled one (or the last
+        // slot if the paste filled to the end).
+        const landingIdx = Math.min(cursor, slots.length - 1);
+        focusSlot(landingIdx);
+    }
+
+    function handleFocus(event: FocusEvent): void {
+        if (!(event.target instanceof HTMLInputElement)) return;
+        // Select existing content so a typed digit overwrites it cleanly,
+        // matching Reka UI's "click any slot to retype" UX.
+        event.target.select();
+    }
+
+    slots.forEach((slot) => {
+        slot.addEventListener('input', handleInput);
+        slot.addEventListener('keydown', handleKeydown);
+        slot.addEventListener('paste', handlePaste);
+        slot.addEventListener('focus', handleFocus);
+    });
+
+    return function teardown(): void {
+        slots.forEach((slot) => {
+            slot.removeEventListener('input', handleInput);
+            slot.removeEventListener('keydown', handleKeydown);
+            slot.removeEventListener('paste', handlePaste);
+            slot.removeEventListener('focus', handleFocus);
+        });
+    };
+}