@pienter/ui 0.2.0 → 0.5.0

package/utils/controllers/slider.ts

@@ -1,336 +0,0 @@
-/**
- * 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

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