@pienter/ui 0.2.0

package/utils/controllers/slider.ts

@@ -0,0 +1,336 @@
+/**
+ * Configuration for `mountSlider`. The controller wires the
+ * `<button role="slider">` thumb(s) inside a Slider track to the
+ * canonical WAI-ARIA Slider keyboard + pointer pattern:
+ *  - ArrowRight / ArrowUp: increment by `step`.
+ *  - ArrowLeft / ArrowDown: decrement by `step`.
+ *  - PageUp / PageDown: increment / decrement by 10× `step`.
+ *  - Home / End: jump to `min` / `max`.
+ *  - Mouse / touch drag: pointer-position-derived value, clamped to
+ *    `[min, max]` and snapped to `step`.
+ *  - Track click: jumps the closest thumb to the click position.
+ *
+ * `onChange` is fired after every successful change with the current
+ * value (single-thumb) or values tuple (range mode). Range mode is
+ * detected from `initialValue` shape: `number` → single, `[number,
+ * number]` → range. Range mode preserves ordering — if the lower
+ * thumb is dragged past the upper, both end at the same value (no
+ * crossing); the same applies in reverse for the upper thumb.
+ */
+export interface SliderConfig {
+    /** Minimum value (default 0). */
+    min?: number;
+    /** Maximum value (default 100). */
+    max?: number;
+    /** Step granularity (default 1). */
+    step?: number;
+    /**
+     * Initial value. Provide a number for single-thumb mode, a
+     * `[lower, upper]` tuple for range mode. The tuple shape locks the
+     * controller into range mode for its lifetime.
+     */
+    initialValue?: number | [number, number];
+    /** Disabled controls reject all keyboard / pointer interactions. */
+    disabled?: boolean;
+    /** Callback fired after every successful value change. */
+    onChange?: (value: number | [number, number]) => void;
+}
+
+/**
+ * Mount the Slider controller on `trackEl`, which MUST be the
+ * `<div class="v-slider">` track element containing one or two
+ * `<button class="v-slider__thumb" role="slider">` children. The
+ * track owns the clickable / draggable surface; the thumbs own
+ * keyboard focus and the per-thumb ARIA attributes.
+ *
+ * Lifecycle (non-stateful per CONVENTIONS — teardown-only signature):
+ * 1. On mount: locate thumbs, read `min` / `max` / `step` from
+ *    `data-min` / `data-max` / `data-step` (set via dataset by the
+ *    framework component), seed values from `initialValue` or from
+ *    the thumbs' `aria-valuenow` attributes (Astro SSR path).
+ * 2. Wire `keydown` on each thumb (WAI-ARIA Slider pattern), and
+ *    `pointerdown` on the track + thumbs for drag.
+ * 3. Every value change updates the thumb's
+ *    `aria-valuenow` / `aria-valuetext` + the track's `data-value`
+ *    + a CSS variable `--v-slider-fill-start` /
+ *    `--v-slider-fill-end` (range mode) on the track for the filled
+ *    progress bar visual. Dispatches `input` and `change` events on
+ *    the track and (if present) on the hidden form input(s).
+ * 4. `teardown()`: removes all listeners. Track / thumb DOM is left
+ *    in place; the framework owns markup cleanup.
+ *
+ * Mounting on a track without thumb children is a graceful no-op.
+ */
+export function mountSlider(
+    trackEl: HTMLElement,
+    config: SliderConfig = {},
+): () => void {
+    const thumbs = Array.from(
+        trackEl.querySelectorAll<HTMLButtonElement>('button.v-slider__thumb'),
+    );
+    if (thumbs.length === 0) {
+        return () => {};
+    }
+
+    const min = config.min ?? readNumber(trackEl.dataset.min, 0);
+    const max = config.max ?? readNumber(trackEl.dataset.max, 100);
+    const step = config.step ?? readNumber(trackEl.dataset.step, 1);
+    const disabled = config.disabled ?? trackEl.dataset.disabled === 'true';
+
+    // Determine mode: range if there are 2 thumbs OR if config.initialValue is a tuple.
+    const isRange =
+        thumbs.length === 2 ||
+        (Array.isArray(config.initialValue) &&
+            config.initialValue.length === 2);
+
+    // Seed values. Priority: config.initialValue, then thumbs' aria-valuenow.
+    const values: number[] = seedValues();
+
+    function seedValues(): number[] {
+        if (config.initialValue !== undefined) {
+            return Array.isArray(config.initialValue)
+                ? [config.initialValue[0], config.initialValue[1]]
+                : [config.initialValue];
+        }
+        return thumbs.map((thumb) => {
+            const raw = thumb.getAttribute('aria-valuenow');
+            const parsed = raw === null ? min : Number.parseFloat(raw);
+            return Number.isFinite(parsed) ? parsed : min;
+        });
+    }
+
+    function readNumber(raw: string | undefined, fallback: number): number {
+        if (raw === undefined) return fallback;
+        const parsed = Number.parseFloat(raw);
+        return Number.isFinite(parsed) ? parsed : fallback;
+    }
+
+    function clamp(value: number, lo: number, hi: number): number {
+        if (value < lo) return lo;
+        if (value > hi) return hi;
+        return value;
+    }
+
+    function snapToStep(value: number): number {
+        if (step <= 0) return value;
+        const stepped = Math.round((value - min) / step) * step + min;
+        // Round-trip floats so 0.1 + 0.2 doesn't surface as 0.30000000000004.
+        const decimals = (step.toString().split('.')[1] ?? '').length;
+        return decimals > 0
+            ? Number.parseFloat(stepped.toFixed(decimals))
+            : stepped;
+    }
+
+    function setValue(thumbIndex: number, raw: number): void {
+        const snapped = snapToStep(clamp(raw, min, max));
+        if (isRange && thumbs.length === 2) {
+            // Enforce no-crossing ordering. Lower thumb (index 0) can't go
+            // above the upper; upper thumb (index 1) can't go below the lower.
+            if (thumbIndex === 0) {
+                const otherValue = values[1] ?? max;
+                values[0] = Math.min(snapped, otherValue);
+            } else {
+                const otherValue = values[0] ?? min;
+                values[1] = Math.max(snapped, otherValue);
+            }
+        } else {
+            values[thumbIndex] = snapped;
+        }
+        render();
+        notifyChange();
+    }
+
+    function render(): void {
+        thumbs.forEach((thumb, idx) => {
+            const value = values[idx] ?? min;
+            thumb.setAttribute('aria-valuenow', String(value));
+            thumb.setAttribute('aria-valuemin', String(min));
+            thumb.setAttribute('aria-valuemax', String(max));
+            if (isRange) {
+                const role = idx === 0 ? 'Lower bound' : 'Upper bound';
+                thumb.setAttribute('aria-valuetext', `${role}: ${value}`);
+            } else {
+                thumb.setAttribute('aria-valuetext', String(value));
+            }
+            const pct = ((value - min) / (max - min)) * 100;
+            thumb.style.insetInlineStart = `${pct}%`;
+        });
+
+        // Track-level CSS vars for the filled progress segment.
+        if (isRange && values.length === 2) {
+            const [v0, v1] = values as [number, number];
+            const startPct = ((v0 - min) / (max - min)) * 100;
+            const endPct = ((v1 - min) / (max - min)) * 100;
+            trackEl.style.setProperty('--v-slider-fill-start', `${startPct}%`);
+            trackEl.style.setProperty('--v-slider-fill-end', `${endPct}%`);
+        } else {
+            const v = values[0] ?? min;
+            const pct = ((v - min) / (max - min)) * 100;
+            trackEl.style.setProperty('--v-slider-fill-start', '0%');
+            trackEl.style.setProperty('--v-slider-fill-end', `${pct}%`);
+        }
+    }
+
+    function notifyChange(): void {
+        const payload: number | [number, number] =
+            isRange && values.length === 2
+                ? [values[0] as number, values[1] as number]
+                : (values[0] as number);
+        config.onChange?.(payload);
+
+        // Sync any hidden form inputs (the Astro / Vue component renders
+        // `<input type="hidden" name="<name>">` (single) or two such with
+        // `[data-bound="lower"|"upper"]` for range — controller writes
+        // their `value` attribute and dispatches input/change so
+        // `mountForm` sees the change).
+        const hiddenSingle =
+            trackEl.parentElement?.querySelector<HTMLInputElement>(
+                'input.v-slider__hidden:not([data-bound])',
+            );
+        const hiddenLower =
+            trackEl.parentElement?.querySelector<HTMLInputElement>(
+                'input.v-slider__hidden[data-bound="lower"]',
+            );
+        const hiddenUpper =
+            trackEl.parentElement?.querySelector<HTMLInputElement>(
+                'input.v-slider__hidden[data-bound="upper"]',
+            );
+        if (isRange && hiddenLower && hiddenUpper && values.length === 2) {
+            hiddenLower.value = String(values[0]);
+            hiddenUpper.value = String(values[1]);
+            hiddenLower.dispatchEvent(new Event('input', { bubbles: true }));
+            hiddenLower.dispatchEvent(new Event('change', { bubbles: true }));
+            hiddenUpper.dispatchEvent(new Event('input', { bubbles: true }));
+            hiddenUpper.dispatchEvent(new Event('change', { bubbles: true }));
+        } else if (!isRange && hiddenSingle && values[0] !== undefined) {
+            hiddenSingle.value = String(values[0]);
+            hiddenSingle.dispatchEvent(new Event('input', { bubbles: true }));
+            hiddenSingle.dispatchEvent(new Event('change', { bubbles: true }));
+        }
+
+        // Bubble track-level events for general consumer listeners.
+        trackEl.dispatchEvent(new Event('input', { bubbles: true }));
+        trackEl.dispatchEvent(new Event('change', { bubbles: true }));
+    }
+
+    function thumbIndexOf(target: EventTarget | null): number {
+        if (!(target instanceof HTMLButtonElement)) return -1;
+        return thumbs.indexOf(target);
+    }
+
+    function handleKeydown(event: KeyboardEvent): void {
+        if (disabled) return;
+        const idx = thumbIndexOf(event.target);
+        if (idx === -1) return;
+        const current = values[idx] ?? min;
+
+        let next: number;
+        switch (event.key) {
+            case 'ArrowRight':
+            case 'ArrowUp':
+                next = current + step;
+                break;
+            case 'ArrowLeft':
+            case 'ArrowDown':
+                next = current - step;
+                break;
+            case 'PageUp':
+                next = current + step * 10;
+                break;
+            case 'PageDown':
+                next = current - step * 10;
+                break;
+            case 'Home':
+                next = min;
+                break;
+            case 'End':
+                next = max;
+                break;
+            default:
+                return;
+        }
+        event.preventDefault();
+        setValue(idx, next);
+    }
+
+    function valueFromPointer(event: PointerEvent): number {
+        const rect = trackEl.getBoundingClientRect();
+        const x = event.clientX - rect.left;
+        const ratio = clamp(x / rect.width, 0, 1);
+        return min + ratio * (max - min);
+    }
+
+    function nearestThumbIndex(target: number): number {
+        if (!isRange || thumbs.length < 2) return 0;
+        const v0 = values[0] ?? min;
+        const v1 = values[1] ?? max;
+        return Math.abs(target - v0) <= Math.abs(target - v1) ? 0 : 1;
+    }
+
+    let activeDragIndex = -1;
+    let dragPointerId: number | null = null;
+
+    function handlePointerDown(event: PointerEvent): void {
+        if (disabled) return;
+        if (event.button !== undefined && event.button !== 0) return;
+
+        const target = event.target;
+        let idx: number;
+        if (target instanceof HTMLButtonElement && thumbs.includes(target)) {
+            idx = thumbs.indexOf(target);
+        } else {
+            // Click on track (not on a thumb) — jump nearest thumb.
+            const value = valueFromPointer(event);
+            idx = nearestThumbIndex(value);
+            setValue(idx, value);
+        }
+        if (idx === -1) return;
+
+        activeDragIndex = idx;
+        dragPointerId = event.pointerId;
+        // Capture so subsequent pointermove / pointerup events fire even if
+        // the cursor leaves the track box.
+        trackEl.setPointerCapture(event.pointerId);
+        // Move focus to the thumb being dragged so subsequent keyboard
+        // input acts on it.
+        thumbs[idx]?.focus();
+        event.preventDefault();
+    }
+
+    function handlePointerMove(event: PointerEvent): void {
+        if (activeDragIndex === -1) return;
+        if (dragPointerId !== null && event.pointerId !== dragPointerId) return;
+        const value = valueFromPointer(event);
+        setValue(activeDragIndex, value);
+    }
+
+    function handlePointerUp(event: PointerEvent): void {
+        if (dragPointerId !== null && event.pointerId !== dragPointerId) return;
+        if (trackEl.hasPointerCapture(event.pointerId)) {
+            trackEl.releasePointerCapture(event.pointerId);
+        }
+        activeDragIndex = -1;
+        dragPointerId = null;
+    }
+
+    thumbs.forEach((thumb) => {
+        thumb.addEventListener('keydown', handleKeydown);
+    });
+    trackEl.addEventListener('pointerdown', handlePointerDown);
+    trackEl.addEventListener('pointermove', handlePointerMove);
+    trackEl.addEventListener('pointerup', handlePointerUp);
+    trackEl.addEventListener('pointercancel', handlePointerUp);
+
+    // Initial render to seed positions / ARIA from the seeded values.
+    render();
+
+    return function teardown(): void {
+        thumbs.forEach((thumb) => {
+            thumb.removeEventListener('keydown', handleKeydown);
+        });
+        trackEl.removeEventListener('pointerdown', handlePointerDown);
+        trackEl.removeEventListener('pointermove', handlePointerMove);
+        trackEl.removeEventListener('pointerup', handlePointerUp);
+        trackEl.removeEventListener('pointercancel', handlePointerUp);
+    };
+}

package/utils/controllers/tags-input.ts

@@ -0,0 +1,255 @@
+/**
+ * Configuration for `mountTagsInput`. The controller wires the inner
+ * entry input + per-tag remove buttons inside a TagsInput wrapper to
+ * the canonical add / remove behaviour:
+ *  - Typing + a configured separator (default `,` or Enter) adds a tag.
+ *  - Backspace on the empty entry input removes the last tag.
+ *  - Click on a tag's remove button removes that tag.
+ *
+ * `onChange` is invoked after every successful add / remove with the
+ * resulting tags array (a fresh `string[]` — the controller does not
+ * leak its internal mutable buffer). Consumers that need to mirror the
+ * tags list into reactive state read from this hook; the controller
+ * is non-stateful and does not surface a control object per the
+ * teardown-only signature locked in CONVENTIONS.
+ */
+export interface TagsInputConfig {
+    /** Initial tags array (defaults to empty). Re-rendered on mount. */
+    initialTags?: string[];
+    /**
+     * Callback fired after every add / remove. Receives a fresh array
+     * (controllers MUST NOT leak internal mutable state).
+     */
+    onChange?: (tags: string[]) => void;
+    /**
+     * Maximum number of tags. Beyond this, add operations are no-ops
+     * (the entry input keeps its typed value). `undefined` disables the
+     * cap (default).
+     */
+    maxTags?: number;
+    /**
+     * Characters or key names that finalize a tag. Single-character
+     * strings are matched against the typed character; multi-character
+     * strings are matched against `event.key` (e.g. `'Enter'`). Default
+     * `[',', 'Enter']`.
+     */
+    separators?: string[];
+}
+
+/**
+ * Mount the TagsInput controller on `wrapperEl`, which MUST be the
+ * `<div class="v-tags-input">` wrapper element containing both the
+ * `<input class="v-tags-input__entry">` and (optionally) any
+ * pre-rendered `<span class="v-tags-input__tag">` children.
+ *
+ * Lifecycle (non-stateful per CONVENTIONS — teardown-only signature,
+ * matching `mountForm` / `mountNumberField`):
+ * 1. On mount: locate the inner entry input. If `initialTags` is
+ *    provided, the controller renders the tag pills DOM-side (this
+ *    keeps Astro's SSR markup free of duplicated state — the wrapper
+ *    only needs to render the entry input, the controller fills in
+ *    the rest from `data-initial-tags`).
+ * 2. Wire `keydown` on the entry input for separator handling and
+ *    Backspace-on-empty-removes-last; wire `click` delegation on the
+ *    wrapper for per-tag remove buttons (so dynamically-added tags
+ *    don't need re-listening).
+ * 3. Every add / remove dispatches `input` and `change` events
+ *    (bubbling) on the entry input so Form's `mountForm` controller
+ *    and consumer-attached listeners observe the change. `onChange`
+ *    fires with the fresh tags array.
+ * 4. `teardown()`: removes the keydown + click listeners; the
+ *    rendered DOM is left in place (the framework owns markup
+ *    cleanup on unmount).
+ *
+ * Mounting on a wrapper without an inner entry input is a graceful
+ * no-op — the controller returns a teardown function that does
+ * nothing, mirroring `mountNumberField`'s defensive pattern.
+ *
+ * Per CONVENTIONS § "Use native APIs where applicable", we deliberately
+ * do NOT add a `role="combobox"` ARIA layer in v1 — the wrapper is a
+ * native input + list-of-tags; the WAI-ARIA "tags input" pattern is
+ * still actively evolving (APG calls it "List input"); the v1 default
+ * uses native input semantics and the per-tag buttons carry their own
+ * `aria-label="Remove tag <label>"` so the surface is fully reachable
+ * with simpler markup.
+ */
+export function mountTagsInput(
+    wrapperEl: HTMLElement,
+    config: TagsInputConfig = {},
+): () => void {
+    const entry = wrapperEl.querySelector<HTMLInputElement>(
+        'input.v-tags-input__entry',
+    );
+    if (!entry) {
+        // Graceful no-op: wrapper is missing the inner entry input.
+        return () => {};
+    }
+
+    const onChange = config.onChange;
+    const maxTags = config.maxTags;
+    const separators = config.separators ?? [',', 'Enter'];
+
+    // Internal tag buffer — the source of truth while the controller is
+    // mounted. Initialised from `config.initialTags` (Vue path) or from
+    // `data-initial-tags` JSON on the wrapper (Astro SSR path).
+    let tags: string[] = readInitialTags(wrapperEl, config.initialTags);
+
+    // Render initial pills if any tags were carried in. Astro renders
+    // its initial SSR pass with the full pill DOM already in place; the
+    // Vue path renders pills reactively. To keep the controller usable
+    // from both, we only render when the wrapper has no existing tag
+    // children (avoids duplication).
+    const hasExistingPills =
+        wrapperEl.querySelector('.v-tags-input__tag') !== null;
+    if (!hasExistingPills && tags.length > 0) {
+        renderTags();
+    } else if (hasExistingPills) {
+        // Sync internal buffer from existing DOM (Astro SSR path).
+        tags = Array.from(
+            wrapperEl.querySelectorAll<HTMLElement>(
+                '.v-tags-input__tag[data-tag-value]',
+            ),
+        ).map((el) => el.dataset.tagValue ?? '');
+    }
+
+    function readInitialTags(
+        el: HTMLElement,
+        fromConfig: string[] | undefined,
+    ): string[] {
+        if (fromConfig) return [...fromConfig];
+        const raw = el.dataset.initialTags;
+        if (!raw) return [];
+        try {
+            const parsed: unknown = JSON.parse(raw);
+            if (Array.isArray(parsed)) {
+                return parsed.filter((v): v is string => typeof v === 'string');
+            }
+        } catch {
+            // Malformed — graceful empty start.
+        }
+        return [];
+    }
+
+    function notifyChange(): void {
+        // Fresh copy so consumers can't mutate the internal buffer.
+        onChange?.([...tags]);
+        // Keep Form's mountForm / consumer listeners in the loop. The
+        // entry input is the FormData carrier — its current value is the
+        // empty entry, but its dataset reflects the tag list so server
+        // payload shaping is the consumer's call (see components/form/tags-input/AUDIT.md).
+        entry?.dispatchEvent(new Event('input', { bubbles: true }));
+        entry?.dispatchEvent(new Event('change', { bubbles: true }));
+    }
+
+    function addTag(raw: string): boolean {
+        const value = raw.trim();
+        if (!value) return false;
+        if (maxTags !== undefined && tags.length >= maxTags) return false;
+        // Reject duplicates — the canonical TagsInput UX is set semantics.
+        if (tags.includes(value)) return false;
+        tags = [...tags, value];
+        renderTags();
+        notifyChange();
+        return true;
+    }
+
+    function removeTag(index: number): void {
+        if (index < 0 || index >= tags.length) return;
+        tags = tags.filter((_, i) => i !== index);
+        renderTags();
+        notifyChange();
+    }
+
+    function renderTags(): void {
+        if (!entry) return;
+        // Remove existing pills (everything before the entry input).
+        const existing =
+            wrapperEl.querySelectorAll<HTMLElement>('.v-tags-input__tag');
+        existing.forEach((el) => el.remove());
+        // Render in reverse insertion order so each new pill lands directly
+        // before the entry input.
+        tags.forEach((tag) => {
+            const pill = document.createElement('span');
+            pill.className = 'v-tags-input__tag';
+            pill.dataset.tagValue = tag;
+
+            const label = document.createElement('span');
+            label.className = 'v-tags-input__tag-label';
+            label.textContent = tag;
+            pill.appendChild(label);
+
+            const removeBtn = document.createElement('button');
+            removeBtn.type = 'button';
+            removeBtn.className = 'v-tags-input__tag-remove';
+            removeBtn.setAttribute('aria-label', `Remove tag ${tag}`);
+            removeBtn.dataset.tagsRemove = '';
+            removeBtn.textContent = '×'; // ×
+            pill.appendChild(removeBtn);
+
+            wrapperEl.insertBefore(pill, entry);
+        });
+    }
+
+    function isSeparator(event: KeyboardEvent): boolean {
+        for (const sep of separators) {
+            if (sep.length === 1 && event.key === sep) return true;
+            if (sep.length > 1 && event.key === sep) return true;
+        }
+        return false;
+    }
+
+    function handleKeydown(event: KeyboardEvent): void {
+        if (!entry) return;
+
+        if (isSeparator(event)) {
+            const value = entry.value;
+            if (value.trim().length > 0) {
+                event.preventDefault();
+                if (addTag(value)) {
+                    entry.value = '';
+                }
+            } else if (event.key === 'Enter') {
+                // Empty + Enter — let the surrounding form submit naturally;
+                // do NOT preventDefault.
+            }
+            return;
+        }
+
+        if (
+            event.key === 'Backspace' &&
+            entry.value === '' &&
+            tags.length > 0
+        ) {
+            event.preventDefault();
+            removeTag(tags.length - 1);
+            return;
+        }
+    }
+
+    function handleClick(event: MouseEvent): void {
+        const target = event.target;
+        if (!(target instanceof Element)) return;
+        const removeBtn =
+            target.closest<HTMLButtonElement>('[data-tags-remove]');
+        if (!removeBtn) return;
+        event.preventDefault();
+        const pill = removeBtn.closest<HTMLElement>('.v-tags-input__tag');
+        if (!pill) return;
+        const idx = Array.from(
+            wrapperEl.querySelectorAll<HTMLElement>('.v-tags-input__tag'),
+        ).indexOf(pill);
+        if (idx === -1) return;
+        removeTag(idx);
+        // Return focus to the entry input so the keyboard user keeps
+        // typing without a manual click — matches Reka UI's TagsInput UX.
+        entry?.focus();
+    }
+
+    entry.addEventListener('keydown', handleKeydown);
+    wrapperEl.addEventListener('click', handleClick);
+
+    return function teardown(): void {
+        entry.removeEventListener('keydown', handleKeydown);
+        wrapperEl.removeEventListener('click', handleClick);
+    };
+}