@enigmax/primitives 0.1.2 → 0.2.0

package/dist/index.d.ts

@@ -70,4 +70,146 @@ interface MarqueeInstance {
  */
 declare function createMarquee(lane: HTMLElement, track: HTMLElement, options?: MarqueeOptions): MarqueeInstance;
 
-export { type MarqueeInstance, type MarqueeOptions, createMarquee };
+/**
+ * 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. */
+type InputIcon = string | Node;
+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;
+}
+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;
+}
+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;
+}
+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;
+}
+/**
+ * Wire a field's in-field actions.
+ *
+ * @param input The field itself. A `type="password"` field gets the reveal for free.
+ */
+declare function createInput(input: HTMLInputElement, options?: InputOptions): InputInstance;
+
+/**
+ * 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.
+ */
+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. */
+interface FuseLike<T> {
+    search(query: string): {
+        item: T;
+        score?: number;
+        matches?: {
+            key?: string;
+        }[];
+    }[];
+}
+type FuseConstructor = new <T>(items: readonly T[], options?: Record<string, unknown>) => FuseLike<T>;
+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;
+}
+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;
+}
+declare function createSearch<T>(options?: SearchOptions<T>): SearchInstance<T>;
+
+export { type FuseConstructor, type FuseLike, type InputAction, type InputActionState, type InputIcon, type InputInstance, type InputOptions, type MarqueeInstance, type MarqueeOptions, type SearchInstance, type SearchMatch, type SearchOptions, createInput, createMarquee, createSearch };

package/dist/index.js

@@ -1 +1 @@
-export { createMarquee } from './chunk-55J5JEWX.js';
+export { createInput, createMarquee, createSearch } from './chunk-OKNWKBQI.js';

package/dist/react/index.d.ts

@@ -1,6 +1,6 @@
 import { RefObject } from 'react';
-import { MarqueeOptions } from '../index.js';
-export { MarqueeInstance } from '../index.js';
+import { MarqueeOptions, InputOptions, SearchMatch, SearchOptions } from '../index.js';
+export { FuseConstructor, InputAction, InputIcon, MarqueeInstance } from '../index.js';
 
 interface UseMarqueeResult {
     /** Attach to the clipping viewport. */
@@ -42,4 +42,54 @@ interface UseMarqueeResult {
  */
 declare function useMarquee(options?: MarqueeOptions): UseMarqueeResult;
 
-export { MarqueeOptions, type UseMarqueeResult, useMarquee };
+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.
+ */
+declare function useInput(options?: InputOptions): UseInputResult;
+
+interface UseSearchResult<T> {
+    /** Attach to the search field, or drive it yourself with `search`. */
+    inputRef: RefObject<HTMLInputElement | null>;
+    query: string;
+    results: SearchMatch<T>[];
+    /** Debounced. */
+    search: (query: string) => void;
+    /** Skips the debounce. */
+    searchNow: (query: string) => void;
+    clear: () => void;
+}
+/**
+ * Search-as-you-type over a list.
+ *
+ * Pass `fuse` (Fuse.js's constructor) for fuzzy matching, `matcher` to replace the
+ * engine, or neither for the built-in accent-insensitive substring search.
+ *
+ * ```tsx
+ * import Fuse from "fuse.js";
+ *
+ * const { inputRef, results } = useSearch({ items: docs, keys: ["title", "body"], fuse: Fuse });
+ * return <input ref={inputRef} type="search" placeholder="Search" />;
+ * ```
+ */
+declare function useSearch<T>(options?: SearchOptions<T>): UseSearchResult<T>;
+
+export { InputOptions, MarqueeOptions, SearchMatch, SearchOptions, type UseInputResult, type UseMarqueeResult, type UseSearchResult, useInput, useMarquee, useSearch };

package/dist/react/index.js

@@ -1,5 +1,5 @@
-import { createMarquee } from '../chunk-55J5JEWX.js';
-import { useRef, useState, useEffect, useLayoutEffect } from 'react';
+import { createMarquee, createInput, createSearch } from '../chunk-OKNWKBQI.js';
+import { useRef, useState, useMemo, useEffect, useLayoutEffect } from 'react';
 
 var useIsomorphicLayoutEffect = typeof window === "undefined" ? useEffect : useLayoutEffect;
 function useMarquee(options = {}) {
@@ -51,5 +51,83 @@ function useMarquee(options = {}) {
     measure: () => instanceRef.current?.measure()
   };
 }
+var useIsomorphicLayoutEffect2 = typeof window === "undefined" ? useEffect : useLayoutEffect;
+function useInput(options = {}) {
+  const inputRef = useRef(null);
+  const actionsRef = useRef(null);
+  const instanceRef = useRef(null);
+  const optionsRef = useRef(options);
+  optionsRef.current = options;
+  const [revealed, setRevealed] = useState(false);
+  useIsomorphicLayoutEffect2(() => {
+    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;
+    };
+  }, []);
+  useIsomorphicLayoutEffect2(() => {
+    instanceRef.current?.update(options);
+  }, [options.reveal, options.actions, options.position]);
+  return {
+    inputRef,
+    actionsRef,
+    revealed,
+    reveal: (next) => instanceRef.current?.reveal(next),
+    refresh: () => instanceRef.current?.refresh()
+  };
+}
+function useSearch(options = {}) {
+  const inputRef = useRef(null);
+  const instanceRef = useRef(null);
+  const optionsRef = useRef(options);
+  optionsRef.current = options;
+  const [query, setQuery] = useState("");
+  const [results, setResults] = useState([]);
+  const instance = useMemo(() => {
+    const created = createSearch({
+      ...optionsRef.current,
+      onResults: (next, nextQuery) => {
+        setResults(next);
+        setQuery(nextQuery);
+        optionsRef.current.onResults?.(next, nextQuery);
+      }
+    });
+    instanceRef.current = created;
+    return created;
+  }, []);
+  useEffect(() => () => instance.destroy(), [instance]);
+  useEffect(() => {
+    instance.setItems(options.items ?? []);
+  }, [instance, options.items]);
+  useEffect(() => {
+    const input = inputRef.current;
+    if (!input) return;
+    return instance.attach(input);
+  }, [instance]);
+  return {
+    inputRef,
+    query,
+    results,
+    search: (next) => instance.search(next),
+    searchNow: (next) => {
+      instance.searchNow(next);
+    },
+    clear: () => {
+      if (inputRef.current) inputRef.current.value = "";
+      instance.searchNow("");
+    }
+  };
+}
 
-export { useMarquee };
+export { useInput, useMarquee, useSearch };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@enigmax/primitives",
-  "version": "0.1.2",
+  "version": "0.2.0",
   "description": "Headless interaction primitives: the behaviour, the timing and the accessibility of components like a draggable infinite marquee, with no styles of their own. Framework-agnostic core plus thin adapters.",
   "type": "module",
   "main": "./dist/index.js",
@@ -31,11 +31,15 @@
     "LICENSE"
   ],
   "peerDependencies": {
-    "react": ">=18"
+    "react": ">=18",
+    "fuse.js": ">=6"
   },
   "peerDependenciesMeta": {
     "react": {
       "optional": true
+    },
+    "fuse.js": {
+      "optional": true
     }
   },
   "devDependencies": {
@@ -43,7 +47,8 @@
     "@types/react": "^19.2.0",
     "react": "^19.2.0",
     "tsup": "^8.0.0",
-    "typescript": "^5.0.0"
+    "typescript": "^5.0.0",
+    "fuse.js": "^7.0.0"
   },
   "engines": {
     "node": ">=18"
@@ -56,7 +61,11 @@
     "unstyled",
     "react",
     "vanilla",
-    "enigma"
+    "enigma",
+    "input",
+    "password",
+    "search",
+    "fuse"
   ],
   "license": "Apache-2.0",
   "author": "FJRG2007 <fjrg2007@tpeoficial.com>",

package/registry.json

@@ -7,28 +7,46 @@
       "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"
+          }
         }
       ],
       "styles": false,
@@ -41,6 +59,118 @@
         "[data-enigma-marquee-copy]"
       ],
       "docs": "docs/notes/primitives.md#marquee"
+    },
+    {
+      "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"
+          }
+        }
+      ],
+      "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"
+    },
+    {
+      "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"
+          }
+        }
+      ],
+      "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"
     }
   ]
 }