@enigmax/primitives 0.1.2 → 0.3.0

package/registry.json

@@ -7,28 +7,72 @@
       "name": "marquee",
       "title": "Draggable infinite marquee",
       "description": "Looping row that takes a speed in px/s, measures its own lap, and can be grabbed and thrown without swallowing the clicks on its items.",
-      "targets": ["vanilla", "astro", "react"],
+      "targets": [
+        "vanilla",
+        "astro",
+        "react"
+      ],
       "entry": {
         "vanilla": "@enigmax/primitives",
         "astro": "@enigmax/primitives",
         "react": "@enigmax/primitives/react"
       },
       "exports": {
-        "vanilla": ["createMarquee"],
-        "astro": ["createMarquee"],
-        "react": ["useMarquee"]
+        "vanilla": [
+          "createMarquee"
+        ],
+        "astro": [
+          "createMarquee"
+        ],
+        "react": [
+          "useMarquee"
+        ]
       },
       "files": [
         {
           "path": "src/core/marquee.ts",
           "dest": "marquee.ts",
-          "targets": ["vanilla", "astro", "react"]
+          "targets": [
+            "vanilla",
+            "astro",
+            "react"
+          ]
         },
         {
           "path": "src/react/use-marquee.ts",
           "dest": "use-marquee.ts",
-          "targets": ["react"],
-          "rewrite": { "@/core/marquee": "./marquee" }
+          "targets": [
+            "react"
+          ],
+          "rewrite": {
+            "@/core/marquee": "./marquee"
+          }
+        },
+        {
+          "path": "recipes/marquee.tailwind.tsx",
+          "dest": "Marquee.tsx",
+          "targets": [
+            "react"
+          ],
+          "style": "tailwind"
+        },
+        {
+          "path": "recipes/marquee.css.tsx",
+          "dest": "Marquee.tsx",
+          "targets": [
+            "react"
+          ],
+          "style": "css"
+        },
+        {
+          "path": "recipes/marquee.css",
+          "dest": "marquee.css",
+          "targets": [
+            "react",
+            "vanilla",
+            "astro"
+          ],
+          "style": "css"
         }
       ],
       "styles": false,
@@ -40,7 +84,164 @@
         "[data-enigma-marquee-track]",
         "[data-enigma-marquee-copy]"
       ],
-      "docs": "docs/notes/primitives.md#marquee"
+      "docs": "docs/notes/primitives.md#marquee",
+      "recipes": [
+        "tailwind",
+        "css"
+      ]
+    },
+    {
+      "name": "input",
+      "title": "Input affordances",
+      "description": "In-field buttons with no styles of their own. A password field gets its reveal toggle automatically; the icon, label, side and container are all replaceable, and any other action plugs into the same mechanism.",
+      "targets": [
+        "vanilla",
+        "astro",
+        "react"
+      ],
+      "entry": {
+        "vanilla": "@enigmax/primitives",
+        "astro": "@enigmax/primitives",
+        "react": "@enigmax/primitives/react"
+      },
+      "exports": {
+        "vanilla": [
+          "createInput"
+        ],
+        "astro": [
+          "createInput"
+        ],
+        "react": [
+          "useInput"
+        ]
+      },
+      "files": [
+        {
+          "path": "src/core/input.ts",
+          "dest": "input.ts",
+          "targets": [
+            "vanilla",
+            "astro",
+            "react"
+          ]
+        },
+        {
+          "path": "src/react/use-input.ts",
+          "dest": "use-input.ts",
+          "targets": [
+            "react"
+          ],
+          "rewrite": {
+            "@/core/input": "./input"
+          }
+        },
+        {
+          "path": "recipes/input.tailwind.tsx",
+          "dest": "Field.tsx",
+          "targets": [
+            "react"
+          ],
+          "style": "tailwind"
+        },
+        {
+          "path": "recipes/input.css.tsx",
+          "dest": "Field.tsx",
+          "targets": [
+            "react"
+          ],
+          "style": "css"
+        },
+        {
+          "path": "recipes/input.css",
+          "dest": "input.css",
+          "targets": [
+            "react",
+            "vanilla",
+            "astro"
+          ],
+          "style": "css"
+        }
+      ],
+      "styles": false,
+      "themeHooks": [
+        "[data-enigma-input]",
+        "[data-enigma-input][data-enigma-input-reveal=on]",
+        "[data-enigma-input-actions]",
+        "[data-enigma-input-actions][data-position=start]",
+        "[data-enigma-input-action]",
+        "[data-enigma-input-action=reveal]"
+      ],
+      "docs": "docs/notes/primitives.md#input",
+      "recipes": [
+        "tailwind",
+        "css"
+      ]
+    },
+    {
+      "name": "search",
+      "title": "Search as you type",
+      "description": "Debouncing, ranking, cancellation and the field wiring, with the matching pluggable. Pass Fuse.js for fuzzy search, your own function to replace the engine, or neither for the built-in accent-insensitive substring matcher.",
+      "targets": [
+        "vanilla",
+        "astro",
+        "react"
+      ],
+      "entry": {
+        "vanilla": "@enigmax/primitives",
+        "astro": "@enigmax/primitives",
+        "react": "@enigmax/primitives/react"
+      },
+      "exports": {
+        "vanilla": [
+          "createSearch"
+        ],
+        "astro": [
+          "createSearch"
+        ],
+        "react": [
+          "useSearch"
+        ]
+      },
+      "files": [
+        {
+          "path": "src/core/search.ts",
+          "dest": "search.ts",
+          "targets": [
+            "vanilla",
+            "astro",
+            "react"
+          ]
+        },
+        {
+          "path": "src/react/use-search.ts",
+          "dest": "use-search.ts",
+          "targets": [
+            "react"
+          ],
+          "rewrite": {
+            "@/core/search": "./search"
+          }
+        },
+        {
+          "path": "recipes/search.tailwind.tsx",
+          "dest": "Search.tsx",
+          "targets": [
+            "react"
+          ],
+          "style": "tailwind"
+        }
+      ],
+      "styles": false,
+      "themeHooks": [
+        "[data-enigma-search]"
+      ],
+      "optionalDependencies": {
+        "fuse.js": "Fuzzy matching. Omit it and a built-in substring matcher is used."
+      },
+      "docs": "docs/notes/primitives.md#search",
+      "recipes": [
+        "tailwind"
+      ]
     }
   ]
 }

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";
+        }
+    };
+}