@enigmax/primitives 0.1.2 → 0.2.0

package/src/core/input.ts

@@ -0,0 +1,315 @@
+/**
+ * Input affordances: the buttons that live inside a field, with no styling of their own.
+ *
+ * A password field gets its reveal toggle automatically, because a field the visitor
+ * cannot read back is the single most common cause of a failed sign-in. Everything about
+ * it is replaceable - the icon, the label, the position, the container, whether it exists
+ * at all - and the same mechanism takes any other action you want in there.
+ *
+ * The details below are the ones the hand-rolled version gets wrong; each is commented
+ * with the failure it prevents.
+ */
+
+/** What an action renders. A string is parsed as HTML, so an inline SVG works. */
+export type InputIcon = string | Node;
+
+export interface InputActionState {
+    /** The field the action belongs to. */
+    input: HTMLInputElement;
+    /** True while the password is readable. Always false for a non-password field. */
+    revealed: boolean;
+    /** The field cannot be acted on: disabled or read-only. */
+    locked: boolean;
+}
+
+export interface InputAction {
+    /** Stable id. Used for `data-action` and to replace a built-in (e.g. "reveal"). */
+    name: string;
+    /** Accessible name. Becomes both `aria-label` and `title`. */
+    label: string | ((state: InputActionState) => string);
+    icon: InputIcon | ((state: InputActionState) => InputIcon);
+    /** Runs on click and on Enter/Space, because it is a real button. */
+    onSelect: (state: InputActionState) => void;
+    /** Renders `aria-pressed`. Omit for actions that are not a toggle. */
+    pressed?: (state: InputActionState) => boolean;
+    /** Hide the action without removing it, e.g. a clear button on an empty field. */
+    visible?: (state: InputActionState) => boolean;
+}
+
+export interface InputOptions {
+    /**
+     * The password reveal. `false` removes it. An object overrides parts of it - the
+     * icons, the labels - without giving up the caret and focus handling.
+     */
+    reveal?: boolean | {
+        /** Shown while the password is hidden; selecting it reveals. */
+        showIcon?: InputIcon;
+        /** Shown while the password is readable. */
+        hideIcon?: InputIcon;
+        showLabel?: string;
+        hideLabel?: string;
+    };
+    /** Extra actions, or a replacement for a built-in when `name` matches. */
+    actions?: InputAction[];
+    /** Which side the actions mount on. Position them yourself with CSS. */
+    position?: "start" | "end";
+    /**
+     * Mount the actions here instead of in a container created next to the input.
+     * Use it when your markup already has a slot for them.
+     */
+    container?: HTMLElement;
+    /** Called whenever the password's visibility changes. */
+    onRevealChange?: (revealed: boolean) => void;
+}
+
+export interface InputInstance {
+    readonly revealed: boolean;
+    /** Show or hide the password. Toggles when the argument is omitted. */
+    reveal(next?: boolean): void;
+    /** Re-read the field and re-render the actions. Call after changing it yourself. */
+    refresh(): void;
+    update(options: Partial<InputOptions>): void;
+    destroy(): void;
+}
+
+/** Neutral 1em glyphs that inherit `color`. Replace them with anything. */
+const EYE = '<svg viewBox="0 0 24 24" width="1em" height="1em" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true"><path d="M2 12s3.5-7 10-7 10 7 10 7-3.5 7-10 7-10-7-10-7Z"/><circle cx="12" cy="12" r="3"/></svg>';
+const EYE_OFF = '<svg viewBox="0 0 24 24" width="1em" height="1em" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true"><path d="M10.6 5.2A9.8 9.8 0 0 1 12 5c6.5 0 10 7 10 7a17.6 17.6 0 0 1-3.2 4.2M6.2 6.2A17.7 17.7 0 0 0 2 12s3.5 7 10 7a9.6 9.6 0 0 0 4.2-.9"/><path d="m2 2 20 20"/><path d="M9.9 9.9a3 3 0 0 0 4.2 4.2"/></svg>';
+
+function resolve<T>(value: T | ((state: InputActionState) => T), state: InputActionState): T {
+    return typeof value === "function" ? (value as (state: InputActionState) => T)(state) : value;
+}
+
+function paint(target: HTMLElement, icon: InputIcon): void {
+    if (typeof icon === "string") target.innerHTML = icon;
+    else {
+        target.replaceChildren(icon);
+    }
+}
+
+/**
+ * Wire a field's in-field actions.
+ *
+ * @param input The field itself. A `type="password"` field gets the reveal for free.
+ */
+export function createInput(input: HTMLInputElement, options: InputOptions = {}): InputInstance {
+    let opts: InputOptions = { ...options };
+    let revealed = false;
+    let destroyed = false;
+    let restoreTimer: ReturnType<typeof setTimeout> | null = null;
+
+    const owned = !opts.container;
+    const container = opts.container ?? document.createElement("span");
+    const buttons = new Map<string, HTMLButtonElement>();
+
+    function state(): InputActionState {
+        return { input, revealed, locked: input.disabled || input.readOnly };
+    }
+
+    function revealConfig() {
+        return typeof opts.reveal === "object" ? opts.reveal : {};
+    }
+
+    /** The built-in, presented as an ordinary action so it can be replaced by name. */
+    function revealAction(): InputAction {
+        const config = revealConfig();
+        return {
+            name: "reveal",
+            label: (current) => (current.revealed ? config.hideLabel ?? "Hide password" : config.showLabel ?? "Show password"),
+            icon: (current) => (current.revealed ? config.hideIcon ?? EYE_OFF : config.showIcon ?? EYE),
+            pressed: (current) => current.revealed,
+            onSelect: () => setRevealed(!revealed)
+        };
+    }
+
+    /** A password field is one whose type is password OR one already revealed by us. */
+    function isPasswordField(): boolean {
+        return input.type === "password" || (revealed && input.dataset.enigmaInputReveal === "on");
+    }
+
+    function activeActions(): InputAction[] {
+        const custom = opts.actions ?? [];
+        const wantsReveal = opts.reveal !== false && isPasswordField();
+        const builtIn = wantsReveal && !custom.some((action) => action.name === "reveal") ? [revealAction()] : [];
+        return [...builtIn, ...custom];
+    }
+
+    function setRevealed(next: boolean): void {
+        if (!isPasswordField() && next) return;
+        // Captured BEFORE the switch. Assigning `type` inside a click handler resets the
+        // caret to 0 in Chromium - reproduced in twenty lines with no library, and it does
+        // NOT happen when the same assignment runs outside an event - so anything read
+        // afterwards is already the clobbered value.
+        const selection = readSelection();
+
+        revealed = next;
+        input.type = next ? "text" : "password";
+        input.dataset.enigmaInputReveal = next ? "on" : "off";
+
+        render();
+
+        // After the render, because rewriting the buttons moves it again.
+        if (selection) {
+            applySelection(selection);
+            // And once more on the next MACROTASK. Chromium clobbers the caret exactly
+            // there - not synchronously and not in a microtask, both of which still read
+            // the right value - so a restore that only runs inline silently loses. The
+            // field is re-checked for focus first, so a visitor who clicked elsewhere in
+            // the meantime is not dragged back.
+            if (restoreTimer !== null) clearTimeout(restoreTimer);
+            restoreTimer = setTimeout(() => {
+                restoreTimer = null;
+                if (!destroyed && document.activeElement === input) applySelection(selection);
+            }, 0);
+        }
+        opts.onRevealChange?.(next);
+    }
+
+    /** Read the field's caret, if it has one and owns the focus. */
+    function readSelection(): [number, number] | null {
+        if (document.activeElement !== input) return null;
+        try {
+            const { selectionStart, selectionEnd } = input;
+            return selectionStart === null || selectionEnd === null ? null : [selectionStart, selectionEnd];
+        } catch {
+            return null;   // selection is not supported on this input type
+        }
+    }
+
+    function applySelection(selection: [number, number]): void {
+        try { input.setSelectionRange(selection[0], selection[1]); } catch { /* unsupported */ }
+    }
+
+    function render(): void {
+        if (destroyed) return;
+        // Rewriting the buttons resets the caret of a focused field - measured, and it
+        // happens asynchronously too, because the MutationObserver below re-renders after
+        // the type switch. Preserving it HERE covers every trigger: the observer, an
+        // update(), a caller's refresh(). Doing it only in setRevealed left the reveal
+        // sending the cursor to position 0 one task later.
+        const selection = readSelection();
+        const current = state();
+        const actions = activeActions();
+        const seen = new Set<string>();
+
+        for (const action of actions) {
+            seen.add(action.name);
+            const visible = action.visible ? action.visible(current) : true;
+            let button = buttons.get(action.name);
+
+            if (!button) {
+                button = document.createElement("button");
+                // Without this a button inside a form SUBMITS it, so revealing a password
+                // posts the half-filled form. It is the single most common bug here.
+                button.type = "button";
+                button.dataset.enigmaInputAction = action.name;
+                buttons.set(action.name, button);
+                container.append(button);
+            }
+
+            if (!visible) {
+                // Removed rather than `hidden`: the hidden attribute works through a UA
+                // `display: none`, and ANY author rule that sets `display` on the button
+                // beats it - which a theme styling these buttons always does.
+                button.remove();
+                buttons.delete(action.name);
+                continue;
+            }
+            if (!button.isConnected) container.append(button);
+
+            const label = resolve(action.label, current);
+            button.setAttribute("aria-label", label);
+            button.title = label;
+            button.disabled = current.locked;
+            if (action.pressed) button.setAttribute("aria-pressed", String(action.pressed(current)));
+            else button.removeAttribute("aria-pressed");
+            paint(button, resolve(action.icon, current));
+        }
+
+        for (const [name, button] of [...buttons]) {
+            if (seen.has(name)) continue;
+            button.remove();
+            buttons.delete(name);
+        }
+
+        container.hidden = buttons.size === 0;
+
+        if (selection) {
+            try { input.setSelectionRange(selection[0], selection[1]); } catch { /* unsupported */ }
+        }
+    }
+
+    /**
+     * A press on an action must not pull focus out of the field: the visitor is mid-word
+     * and expects to keep typing. Preventing the default on mousedown keeps focus where
+     * it is, which also means the caret survives on its own. Keyboard users still reach
+     * the button with Tab and activate it with Space, and focus correctly stays there.
+     */
+    function onMouseDown(event: MouseEvent): void {
+        if (!(event.target as HTMLElement | null)?.closest("[data-enigma-input-action]")) return;
+        event.preventDefault();
+    }
+
+    function onClick(event: MouseEvent): void {
+        const target = (event.target as HTMLElement | null)?.closest<HTMLElement>("[data-enigma-input-action]");
+        if (!target) return;
+        const action = activeActions().find((candidate) => candidate.name === target.dataset.enigmaInputAction);
+        if (!action) return;
+        event.preventDefault();
+        action.onSelect(state());
+    }
+
+    /** The field's own type can change from outside; the reveal has to follow. */
+    const observer = typeof MutationObserver === "function"
+        ? new MutationObserver(() => {
+            if (!isPasswordField() && revealed) revealed = false;
+            render();
+        })
+        : null;
+
+    function mount(): void {
+        input.dataset.enigmaInput = "";
+        container.dataset.enigmaInputActions = "";
+        container.dataset.position = opts.position ?? "end";
+        if (owned && !container.isConnected) {
+            if ((opts.position ?? "end") === "start") input.before(container);
+            else input.after(container);
+        }
+        container.addEventListener("mousedown", onMouseDown);
+        container.addEventListener("click", onClick);
+        observer?.observe(input, { attributes: true, attributeFilter: ["type", "disabled", "readonly"] });
+        render();
+    }
+
+    mount();
+
+    return {
+        get revealed() { return revealed; },
+        reveal(next?: boolean) { setRevealed(next ?? !revealed); },
+        refresh: render,
+        update(next: Partial<InputOptions>) {
+            const moved = next.position !== undefined && next.position !== opts.position;
+            opts = { ...opts, ...next };
+            if (moved && owned) {
+                container.dataset.position = opts.position ?? "end";
+                if (opts.position === "start") input.before(container);
+                else input.after(container);
+            }
+            render();
+        },
+        destroy() {
+            destroyed = true;
+            if (restoreTimer !== null) clearTimeout(restoreTimer);
+            observer?.disconnect();
+            container.removeEventListener("mousedown", onMouseDown);
+            container.removeEventListener("click", onClick);
+            for (const button of buttons.values()) button.remove();
+            buttons.clear();
+            if (owned) container.remove();
+            delete input.dataset.enigmaInput;
+            delete input.dataset.enigmaInputReveal;
+            // A field left as text would leak the password on the next render.
+            if (revealed) input.type = "password";
+        }
+    };
+}

package/src/core/search.ts

@@ -0,0 +1,225 @@
+/**
+ * Search-as-you-type: debouncing, ordering, cancellation and the field wiring, with the
+ * matching left pluggable.
+ *
+ * Fuse.js is NOT a dependency of this package. Hand it the constructor and you get fuzzy
+ * matching configured exactly as if you had called it yourself - `fuseOptions` is passed
+ * through untouched. Hand it nothing and a built-in accent-insensitive substring matcher
+ * runs instead, so the primitive works with zero dependencies. Hand it a `matcher` and
+ * every part of this is replaced by your own.
+ */
+
+export interface SearchMatch<T> {
+    item: T;
+    /** Lower is better, matching Fuse's convention. 0 is an exact hit. */
+    score: number;
+    /** Which key matched, when the matcher reports it. */
+    key?: string;
+}
+
+/** The shape of Fuse's constructor, declared here so the package need not depend on it. */
+export interface FuseLike<T> {
+    search(query: string): { item: T; score?: number; matches?: { key?: string; }[]; }[];
+}
+export type FuseConstructor = new <T>(items: readonly T[], options?: Record<string, unknown>) => FuseLike<T>;
+
+export interface SearchOptions<T> {
+    items?: readonly T[];
+    /** Fields to search. Dotted paths work with the built-in matcher and with Fuse. */
+    keys?: string[];
+    /**
+     * Pass Fuse.js's constructor to get fuzzy matching. Omit it for the built-in
+     * substring matcher. Ignored when `matcher` is set.
+     */
+    fuse?: FuseConstructor;
+    /** Handed to Fuse verbatim, so any Fuse option behaves exactly as documented there. */
+    fuseOptions?: Record<string, unknown>;
+    /** Replaces the engine entirely. Return the results in the order you want them. */
+    matcher?: (query: string, items: readonly T[]) => SearchMatch<T>[];
+    /** ms to wait after the last keystroke. 0 searches on every one. */
+    debounce?: number;
+    /** Queries shorter than this return nothing rather than everything. */
+    minLength?: number;
+    /** Cap the result list. */
+    limit?: number;
+    /** What an empty query returns. "none" (default) or "all". */
+    empty?: "none" | "all";
+    onResults?: (results: SearchMatch<T>[], query: string) => void;
+}
+
+export interface SearchInstance<T> {
+    readonly query: string;
+    readonly results: SearchMatch<T>[];
+    /** Debounced. */
+    search(query: string): void;
+    /** Skips the debounce, e.g. on Enter. */
+    searchNow(query: string): SearchMatch<T>[];
+    setItems(items: readonly T[]): void;
+    update(options: Partial<SearchOptions<T>>): void;
+    /** Bind to a field: input events search, Escape clears. Returns an unbind. */
+    attach(input: HTMLInputElement): () => void;
+    subscribe(listener: (results: SearchMatch<T>[], query: string) => void): () => void;
+    destroy(): void;
+}
+
+const DEFAULT_DEBOUNCE = 120;
+
+/** "Café" must match "cafe" - a search that fails on an accent reads as broken. */
+function fold(value: string): string {
+    return value.normalize("NFD").replace(/\p{Diacritic}/gu, "").toLowerCase();
+}
+
+function readPath(item: unknown, path: string): string {
+    let cursor: unknown = item;
+    for (const step of path.split(".")) {
+        if (cursor == null || typeof cursor !== "object") return "";
+        cursor = (cursor as Record<string, unknown>)[step];
+    }
+    return cursor == null ? "" : String(cursor);
+}
+
+/**
+ * The zero-dependency fallback: accent-insensitive substring, ranked by where the match
+ * lands and which key it landed in, so a title hit outranks a body hit.
+ */
+function substringMatcher<T>(query: string, items: readonly T[], keys: string[]): SearchMatch<T>[] {
+    const needle = fold(query);
+    const results: SearchMatch<T>[] = [];
+
+    for (const item of items) {
+        const fields = keys.length ? keys : [""];
+        let best: SearchMatch<T> | null = null;
+
+        for (let index = 0; index < fields.length; index++) {
+            const key = fields[index];
+            const haystack = fold(key ? readPath(item, key) : String(item));
+            const at = haystack.indexOf(needle);
+            if (at < 0) continue;
+            // Earlier in the string and earlier in the key list is a better hit; a whole
+            // field that IS the query scores 0.
+            const score = haystack === needle ? 0 : (at + 1) / (haystack.length + 1) + index * 0.01;
+            if (!best || score < best.score) best = { item, score, key: key || undefined };
+        }
+        if (best) results.push(best);
+    }
+
+    return results.sort((left, right) => left.score - right.score);
+}
+
+export function createSearch<T>(options: SearchOptions<T> = {}): SearchInstance<T> {
+    let opts: SearchOptions<T> = { ...options };
+    let items: readonly T[] = opts.items ?? [];
+    let query = "";
+    let results: SearchMatch<T>[] = [];
+    let timer: ReturnType<typeof setTimeout> | null = null;
+    let engine: FuseLike<T> | null = null;
+    let destroyed = false;
+    const listeners = new Set<(results: SearchMatch<T>[], query: string) => void>();
+
+    function buildEngine(): void {
+        engine = null;
+        if (opts.matcher || !opts.fuse) return;
+        // Fuse indexes on construction, so it is rebuilt when the items or keys change
+        // and never per keystroke.
+        engine = new opts.fuse(items, { keys: opts.keys ?? [], includeScore: true, includeMatches: true, threshold: 0.4, ...opts.fuseOptions });
+    }
+
+    function run(next: string): SearchMatch<T>[] {
+        const trimmed = next.trim();
+        const minLength = opts.minLength ?? 1;
+
+        let found: SearchMatch<T>[];
+        // The limit applies to this branch too: a caller asking for 10 rows means 10 rows,
+        // including the "show everything" state, which is the longest list of them all.
+        if (trimmed.length < minLength) {
+            found = (opts.empty ?? "none") === "all" ? items.map((item) => ({ item, score: 0 })) : [];
+        } else if (opts.matcher) {
+            found = opts.matcher(trimmed, items);
+        } else if (engine) {
+            found = engine.search(trimmed).map((hit) => ({
+                item: hit.item,
+                score: hit.score ?? 0,
+                key: hit.matches?.[0]?.key
+            }));
+        } else {
+            found = substringMatcher(trimmed, items, opts.keys ?? []);
+        }
+
+        return opts.limit != null ? found.slice(0, opts.limit) : found;
+    }
+
+    function publish(next: string): SearchMatch<T>[] {
+        query = next;
+        results = run(next);
+        opts.onResults?.(results, query);
+        for (const listener of listeners) listener(results, query);
+        return results;
+    }
+
+    function clearTimer(): void {
+        if (timer === null) return;
+        clearTimeout(timer);
+        timer = null;
+    }
+
+    buildEngine();
+
+    return {
+        get query() { return query; },
+        get results() { return results; },
+        search(next: string) {
+            if (destroyed) return;
+            clearTimer();
+            const wait = opts.debounce ?? DEFAULT_DEBOUNCE;
+            // A pending search is dropped rather than queued, so a fast typist gets one
+            // pass over the data instead of one per keystroke.
+            if (wait <= 0) { publish(next); return; }
+            timer = setTimeout(() => { timer = null; publish(next); }, wait);
+        },
+        searchNow(next: string) {
+            clearTimer();
+            return publish(next);
+        },
+        setItems(next: readonly T[]) {
+            items = next;
+            buildEngine();
+            // The visible results are stale the moment the data changes under them.
+            if (query) publish(query);
+        },
+        update(next: Partial<SearchOptions<T>>) {
+            opts = { ...opts, ...next };
+            if (next.items) items = next.items;
+            buildEngine();
+            if (query) publish(query);
+        },
+        attach(input: HTMLInputElement) {
+            const onInput = () => this.search(input.value);
+            const onKeyDown = (event: KeyboardEvent) => {
+                if (event.key !== "Escape" || !input.value) return;
+                // Escape clears the field first and only then reaches the dialog around
+                // it, which is what a visitor expects from a search box.
+                event.stopPropagation();
+                input.value = "";
+                this.searchNow("");
+            };
+            input.addEventListener("input", onInput);
+            input.addEventListener("keydown", onKeyDown);
+            input.dataset.enigmaSearch = "";
+            return () => {
+                input.removeEventListener("input", onInput);
+                input.removeEventListener("keydown", onKeyDown);
+                delete input.dataset.enigmaSearch;
+            };
+        },
+        subscribe(listener) {
+            listeners.add(listener);
+            return () => { listeners.delete(listener); };
+        },
+        destroy() {
+            destroyed = true;
+            clearTimer();
+            listeners.clear();
+            engine = null;
+        }
+    };
+}

package/src/index.ts

@@ -1 +1,3 @@
 export { createMarquee, type MarqueeOptions, type MarqueeInstance } from "@/core/marquee";
+export { createInput, type InputOptions, type InputInstance, type InputAction, type InputIcon, type InputActionState } from "@/core/input";
+export { createSearch, type SearchOptions, type SearchInstance, type SearchMatch, type FuseConstructor, type FuseLike } from "@/core/search";

package/src/react/index.ts

@@ -1,2 +1,6 @@
 export { useMarquee, type UseMarqueeResult } from "@/react/use-marquee";
 export { type MarqueeOptions, type MarqueeInstance } from "@/core/marquee";
+export { useInput, type UseInputResult } from "@/react/use-input";
+export { useSearch, type UseSearchResult } from "@/react/use-search";
+export { type InputOptions, type InputAction, type InputIcon } from "@/core/input";
+export { type SearchOptions, type SearchMatch, type FuseConstructor } from "@/core/search";

package/src/react/use-input.ts

@@ -0,0 +1,70 @@
+import { createInput, type InputOptions, type InputInstance } from "@/core/input";
+import { useRef, useState, useEffect, useLayoutEffect, type RefObject } from "react";
+
+const useIsomorphicLayoutEffect = typeof window === "undefined" ? useEffect : useLayoutEffect;
+
+export interface UseInputResult {
+    /** Attach to the `<input>`. */
+    inputRef: RefObject<HTMLInputElement | null>;
+    /** Attach to your own actions container, or leave it and one is created for you. */
+    actionsRef: RefObject<HTMLElement | null>;
+    /** True while a password is readable. */
+    revealed: boolean;
+    reveal: (next?: boolean) => void;
+    /** Re-render the actions after you change the field yourself. */
+    refresh: () => void;
+}
+
+/**
+ * In-field actions for an input, with the password reveal wired for free.
+ *
+ * ```tsx
+ * const { inputRef, revealed } = useInput();
+ * return <input ref={inputRef} type="password" autoComplete="current-password" />;
+ * ```
+ *
+ * The toggle is a real `<button type="button">`, so it never submits the form, and the
+ * caret survives the type switch.
+ */
+export function useInput(options: InputOptions = {}): UseInputResult {
+    const inputRef = useRef<HTMLInputElement | null>(null);
+    const actionsRef = useRef<HTMLElement | null>(null);
+    const instanceRef = useRef<InputInstance | null>(null);
+    const optionsRef = useRef(options);
+    optionsRef.current = options;
+
+    const [revealed, setRevealed] = useState(false);
+
+    useIsomorphicLayoutEffect(() => {
+        const input = inputRef.current;
+        if (!input) return;
+
+        const instance = createInput(input, {
+            ...optionsRef.current,
+            container: actionsRef.current ?? optionsRef.current.container,
+            onRevealChange: (next) => {
+                setRevealed(next);
+                optionsRef.current.onRevealChange?.(next);
+            }
+        });
+        instanceRef.current = instance;
+        return () => {
+            instance.destroy();
+            instanceRef.current = null;
+        };
+        // Created once; option changes go through update() so the field is not rebuilt
+        // on every render, which would drop the caret mid-typing.
+    }, []);
+
+    useIsomorphicLayoutEffect(() => {
+        instanceRef.current?.update(options);
+    }, [options.reveal, options.actions, options.position]);
+
+    return {
+        inputRef,
+        actionsRef,
+        revealed,
+        reveal: (next?: boolean) => instanceRef.current?.reveal(next),
+        refresh: () => instanceRef.current?.refresh()
+    };
+}