@enigmax/primitives 0.8.0 → 0.10.0

package/dist/chunk-L4KA342C.js

@@ -0,0 +1,466 @@
+import { generatePassword, estimatePasswordStrength, INPUT_ICON_PATHS, createButton, createMarquee, createInput } from './chunk-42Y7OOJM.js';
+import { createSearch } from './chunk-UZFEEFMF.js';
+import { forwardRef, createElement, useRef, useState, useId, useCallback, useEffect, useMemo, useLayoutEffect } from 'react';
+import { jsx, jsxs } from 'react/jsx-runtime';
+
+var useIsomorphicLayoutEffect = typeof window === "undefined" ? useEffect : useLayoutEffect;
+function useMarquee(options = {}) {
+  const laneRef = useRef(null);
+  const trackRef = useRef(null);
+  const instanceRef = useRef(null);
+  const optionsRef = useRef(options);
+  optionsRef.current = options;
+  const [copies, setCopies] = useState(2);
+  const [dragging, setDragging] = useState(false);
+  const [period, setPeriod] = useState(0);
+  useIsomorphicLayoutEffect(() => {
+    const lane = laneRef.current;
+    const track = trackRef.current;
+    if (!lane || !track) return;
+    const instance = createMarquee(lane, track, {
+      ...optionsRef.current,
+      // React owns the DOM; cloning behind its back would be undone on render.
+      copies: "external",
+      onCopyCountChange: setCopies,
+      onMeasure: (measured) => setPeriod(measured),
+      onItemClick: (event) => optionsRef.current.onItemClick?.(event)
+    });
+    instanceRef.current = instance;
+    const syncDragging = () => setDragging(instance.dragging);
+    lane.addEventListener("pointerdown", syncDragging);
+    window.addEventListener("pointerup", syncDragging);
+    window.addEventListener("pointercancel", syncDragging);
+    return () => {
+      lane.removeEventListener("pointerdown", syncDragging);
+      window.removeEventListener("pointerup", syncDragging);
+      window.removeEventListener("pointercancel", syncDragging);
+      instance.destroy();
+      instanceRef.current = null;
+    };
+  }, []);
+  useIsomorphicLayoutEffect(() => {
+    instanceRef.current?.update(options);
+  }, [options.speed, options.reverse, options.vertical, options.draggable, options.hover, options.decay]);
+  useIsomorphicLayoutEffect(() => {
+    instanceRef.current?.measure();
+  }, [copies]);
+  return {
+    laneRef,
+    trackRef,
+    copies,
+    dragging,
+    period,
+    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("");
+    }
+  };
+}
+function useButton(options = {}) {
+  const optionsRef = useRef(options);
+  optionsRef.current = options;
+  const instance = useMemo(() => createButton({
+    ...optionsRef.current,
+    onPress: (event) => optionsRef.current.onPress?.(event),
+    onChange: (next) => optionsRef.current.onChange?.(next)
+    // Built once: recreating it would drop a running cooldown on every render.
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }), []);
+  const [state, setState] = useState(() => instance.state);
+  useEffect(() => {
+    const unsubscribe = instance.subscribe(setState);
+    setState(instance.state);
+    return () => {
+      unsubscribe();
+      instance.destroy();
+    };
+  }, [instance]);
+  useEffect(() => {
+    instance.update({
+      href: options.href,
+      disabled: options.disabled,
+      loading: options.loading,
+      cooldown: options.cooldown,
+      shortcut: options.shortcut
+    });
+  }, [instance, options.href, options.disabled, options.loading, options.cooldown, options.shortcut]);
+  const press = useCallback(() => {
+    void instance.press();
+  }, [instance]);
+  return {
+    ...state,
+    press,
+    reset: () => instance.reset(),
+    props: {
+      onClick: (event) => {
+        if (!state.available) {
+          event.preventDefault();
+          return;
+        }
+        void instance.press();
+      },
+      "aria-disabled": !state.available,
+      "aria-busy": state.loading,
+      ...state.loading ? { "data-loading": "" } : {},
+      ...state.cooldown > 0 ? { "data-cooldown": "" } : {},
+      ...state.element === "button" ? { disabled: state.disabled } : { href: options.href },
+      ...state.shortcut ? { title: `Shortcut: ${state.shortcut.toUpperCase()}` } : {}
+    }
+  };
+}
+
+// src/react/link.ts
+var linkComponent = null;
+function setLinkComponent(component) {
+  linkComponent = component;
+}
+function getLinkComponent() {
+  return linkComponent ?? "a";
+}
+var Button = forwardRef(function Button2({
+  as,
+  children,
+  pending,
+  href,
+  disabled,
+  loading,
+  cooldown,
+  shortcut,
+  onPress,
+  onChange,
+  type = "button",
+  ...rest
+}, ref) {
+  const button = useButton({ href, disabled, loading, cooldown, shortcut, onPress, onChange });
+  const state = button;
+  const Tag = as ?? (state.element === "a" ? getLinkComponent() : "button");
+  const native = Tag === "button" ? { type } : {};
+  const label = typeof children === "function" ? children(state) : children;
+  return createElement(
+    Tag,
+    { ref, ...button.props, ...native, ...rest },
+    state.loading && pending !== void 0 ? pending : label
+  );
+});
+var ICON_PROPS = {
+  viewBox: "0 0 24 24",
+  width: "1em",
+  height: "1em",
+  fill: "none",
+  stroke: "currentColor",
+  strokeWidth: 2,
+  strokeLinecap: "round",
+  strokeLinejoin: "round",
+  "aria-hidden": true
+};
+function Icon({ paths }) {
+  return /* @__PURE__ */ jsx("svg", { ...ICON_PROPS, children: paths.map((path) => /* @__PURE__ */ jsx("path", { d: path }, path)) });
+}
+function writeValue(input, next) {
+  const setter = Object.getOwnPropertyDescriptor(HTMLInputElement.prototype, "value")?.set;
+  if (setter) setter.call(input, next);
+  else input.value = next;
+  input.dispatchEvent(new Event("input", { bubbles: true }));
+}
+var Input = forwardRef(function Input2({
+  reveal,
+  revealLabels,
+  generate = false,
+  generateLabel = "Generate a password",
+  revealOnGenerate = true,
+  copyOnGenerate = false,
+  onGenerate,
+  actions = [],
+  position = "end",
+  strength = false,
+  onStrengthChange,
+  breach,
+  breachDelay = 500,
+  onBreachChange,
+  wrapperProps,
+  fieldProps,
+  classNames,
+  children,
+  type = "text",
+  onChange,
+  ...props
+}, forwardedRef) {
+  const innerRef = useRef(null);
+  const [revealed, setRevealed] = useState(false);
+  const describedBy = useId();
+  const isPassword = type === "password";
+  const showReveal = reveal ?? isPassword;
+  const showGenerate = generate !== false && isPassword;
+  const controlled = props.value !== void 0;
+  const [ownValue, setOwnValue] = useState(String(props.defaultValue ?? ""));
+  const value = controlled ? String(props.value ?? "") : ownValue;
+  const handleChange = useCallback((event) => {
+    if (!controlled) setOwnValue(event.target.value);
+    onChange?.(event);
+  }, [controlled, onChange]);
+  const caret = useRef(null);
+  const toggleReveal = useCallback(() => {
+    const input = innerRef.current;
+    if (input && typeof document !== "undefined" && document.activeElement === input) {
+      try {
+        const { selectionStart, selectionEnd } = input;
+        caret.current = selectionStart === null || selectionEnd === null ? null : [selectionStart, selectionEnd];
+      } catch {
+        caret.current = null;
+      }
+    }
+    setRevealed((current) => !current);
+  }, []);
+  useEffect(() => {
+    const selection = caret.current;
+    if (!selection) return;
+    caret.current = null;
+    const restore = () => {
+      const input = innerRef.current;
+      if (!input || document.activeElement !== input) return;
+      try {
+        input.setSelectionRange(selection[0], selection[1]);
+      } catch {
+      }
+    };
+    restore();
+    const timer = setTimeout(restore, 0);
+    return () => clearTimeout(timer);
+  }, [revealed]);
+  const handleGenerate = useCallback(() => {
+    const input = innerRef.current;
+    if (!input) return;
+    const password = generatePassword(typeof generate === "object" ? generate : {});
+    writeValue(input, password);
+    if (revealOnGenerate) setRevealed(true);
+    if (copyOnGenerate) void navigator.clipboard?.writeText(password).catch(() => {
+    });
+    input.focus();
+    onGenerate?.(password);
+  }, [generate, revealOnGenerate, copyOnGenerate, onGenerate]);
+  const estimateOptions = typeof strength === "object" ? strength : void 0;
+  const userInputs = estimateOptions?.userInputs;
+  const report = useMemo(
+    () => strength === false ? null : estimatePasswordStrength(value, { userInputs }),
+    // The array is compared by identity, so a literal would re-estimate every render.
+    [strength, value, userInputs]
+  );
+  const strengthListener = useRef(onStrengthChange);
+  strengthListener.current = onStrengthChange;
+  useEffect(() => {
+    if (report) strengthListener.current?.(report);
+  }, [report]);
+  const [breachState, setBreachState] = useState({ status: "idle", count: 0, error: null });
+  const breachListener = useRef(onBreachChange);
+  breachListener.current = onBreachChange;
+  useEffect(() => {
+    if (!breach || !value) {
+      setBreachState({ status: "idle", count: 0, error: null });
+      return;
+    }
+    const controller = new AbortController();
+    const timer = setTimeout(() => {
+      setBreachState({ status: "checking", count: 0, error: null });
+      breach(value, { signal: controller.signal }).then((result) => {
+        if (controller.signal.aborted) return;
+        setBreachState({ status: result.breached ? "breached" : "safe", count: result.count, error: null });
+      }).catch((error) => {
+        if (controller.signal.aborted) return;
+        setBreachState({ status: "error", count: 0, error });
+      });
+    }, breachDelay);
+    return () => {
+      clearTimeout(timer);
+      controller.abort();
+    };
+  }, [breach, value, breachDelay]);
+  useEffect(() => {
+    breachListener.current?.(breachState);
+  }, [breachState]);
+  const builtIn = [];
+  if (showGenerate) {
+    builtIn.push({
+      name: "generate",
+      label: generateLabel,
+      icon: /* @__PURE__ */ jsx(Icon, { paths: INPUT_ICON_PATHS.generate }),
+      onSelect: handleGenerate
+    });
+  }
+  if (showReveal) {
+    builtIn.push({
+      name: "reveal",
+      label: revealed ? revealLabels?.hide ?? "Hide password" : revealLabels?.show ?? "Show password",
+      icon: /* @__PURE__ */ jsx(Icon, { paths: revealed ? INPUT_ICON_PATHS.eyeOff : INPUT_ICON_PATHS.eye }),
+      pressed: revealed,
+      onSelect: toggleReveal
+    });
+  }
+  const overridden = new Set(actions.map((action) => action.name));
+  const rendered = [...builtIn.filter((action) => !overridden.has(action.name)), ...actions].filter((action) => action.visible !== false);
+  const locked = props.disabled === true || props.readOnly === true;
+  const buttons = rendered.length === 0 ? null : /* @__PURE__ */ jsx("span", { "data-enigma-input-actions": "", "data-position": position, className: classNames?.actions, children: rendered.map((action) => /* @__PURE__ */ jsx(
+    "button",
+    {
+      type: "button",
+      "data-enigma-input-action": action.name,
+      className: classNames?.action,
+      "aria-label": action.label,
+      title: action.label,
+      "aria-pressed": action.pressed,
+      disabled: locked,
+      onMouseDown: (event) => event.preventDefault(),
+      onClick: action.onSelect,
+      children: action.icon
+    },
+    action.name
+  )) });
+  return /* @__PURE__ */ jsxs(
+    "div",
+    {
+      ...wrapperProps,
+      "data-enigma-input-root": "",
+      "data-revealed": revealed ? "" : void 0,
+      "data-breached": breachState.status === "breached" ? "" : void 0,
+      "data-score": report && !report.empty ? report.score : void 0,
+      children: [
+        /* @__PURE__ */ jsxs("div", { ...fieldProps, "data-enigma-input-field": "", children: [
+          position === "start" && buttons,
+          /* @__PURE__ */ jsx(
+            "input",
+            {
+              ...props,
+              ref: (node) => {
+                innerRef.current = node;
+                if (typeof forwardedRef === "function") forwardedRef(node);
+                else if (forwardedRef) forwardedRef.current = node;
+              },
+              type: revealed && isPassword ? "text" : type,
+              onChange: handleChange,
+              "data-enigma-input": "",
+              "aria-describedby": report ? describedBy : props["aria-describedby"]
+            }
+          ),
+          position === "end" && buttons
+        ] }),
+        report && /* @__PURE__ */ jsx(PasswordStrength, { id: describedBy, report, classNames: classNames?.strength }),
+        children
+      ]
+    }
+  );
+});
+var SCORE_LABELS = ["Very weak", "Weak", "Fair", "Strong", "Very strong"];
+function PasswordStrength({
+  value = "",
+  report,
+  userInputs,
+  segments = 5,
+  labels = SCORE_LABELS,
+  showWarning = true,
+  classNames,
+  ...props
+}) {
+  const computed = useMemo(
+    () => report ?? estimatePasswordStrength(value, { userInputs }),
+    [report, value, userInputs]
+  );
+  const score = computed.score;
+  return /* @__PURE__ */ jsxs(
+    "div",
+    {
+      ...props,
+      "data-enigma-password-strength": "",
+      "data-score": computed.empty ? void 0 : score,
+      "data-empty": computed.empty ? "" : void 0,
+      children: [
+        /* @__PURE__ */ jsx("div", { "data-enigma-password-strength-track": "", "aria-hidden": "true", className: classNames?.track, children: Array.from({ length: segments }, (unused, index) => /* @__PURE__ */ jsx(
+          "span",
+          {
+            "data-enigma-password-strength-segment": "",
+            className: classNames?.segment,
+            "data-filled": !computed.empty && index <= score ? "" : void 0
+          },
+          index
+        )) }),
+        /* @__PURE__ */ jsx("p", { "data-enigma-password-strength-label": "", role: "status", "aria-live": "polite", className: classNames?.label, children: computed.empty ? "" : labels[score] ?? "" }),
+        showWarning && !computed.empty && computed.warnings.length > 0 && /* @__PURE__ */ jsx("p", { "data-enigma-password-strength-warning": "", className: classNames?.warning, children: computed.warnings[0] })
+      ]
+    }
+  );
+}
+
+export { Button, Input, PasswordStrength, getLinkComponent, setLinkComponent, useButton, useInput, useMarquee, useSearch };

package/dist/next/index.d.ts

@@ -0,0 +1,26 @@
+import * as react from 'react';
+import { ButtonProps } from '../react/index.js';
+export { BreachChecker, BreachState, BreachStatus, FieldAction, Input, InputProps, PasswordStrength, PasswordStrengthProps, UseButtonResult, UseInputResult, UseMarqueeResult, UseSearchResult, getLinkComponent, setLinkComponent, useButton, useInput, useMarquee, useSearch } from '../react/index.js';
+export { ButtonOptions, ButtonState, EstimateOptions, GeneratePasswordOptions, InputAction, InputIcon, InputOptions, MarqueeHover, MarqueeInstance, MarqueeOptions, PasswordScore, PasswordStrengthReport, estimatePasswordStrength, generatePassword } from '../index.js';
+export { F as FuseConstructor, b as SearchMatch, c as SearchOptions } from '../search-CsO3L1Lw.js';
+
+/**
+ * The Next.js entry. Same components, wired to `next/link`.
+ *
+ * ```tsx
+ * import { Button } from "@enigmax/primitives/next";
+ *
+ * <Button href="/settings">Settings</Button>   // renders next/link
+ * ```
+ *
+ * The import path is the configuration. There is nothing to register and nothing to pass at
+ * the call site, and a project that is not on Next never resolves this file - which is the
+ * whole reason the main entry cannot simply `import Link from "next/link"` itself: that
+ * import is a build error for every consumer on Vite, Astro, Remix or plain React.
+ *
+ * Everything else is re-exported unchanged, so this can be the only import path in a Next
+ * app rather than a second one to remember.
+ */
+declare const Button: react.ForwardRefExoticComponent<ButtonProps & react.RefAttributes<HTMLElement>>;
+
+export { Button, ButtonProps };

package/dist/next/index.js

@@ -0,0 +1,13 @@
+"use client";
+import { Button } from '../chunk-L4KA342C.js';
+export { Input, PasswordStrength, getLinkComponent, setLinkComponent, useButton, useInput, useMarquee, useSearch } from '../chunk-L4KA342C.js';
+export { estimatePasswordStrength, generatePassword } from '../chunk-42Y7OOJM.js';
+import '../chunk-UZFEEFMF.js';
+import Link from 'next/link';
+import { forwardRef, createElement } from 'react';
+
+var Button2 = forwardRef(function Button3(props, ref) {
+  return createElement(Button, { ...props, as: props.as ?? (props.href ? Link : void 0), ref });
+});
+
+export { Button2 as Button };

package/dist/react/index.d.ts

@@ -1,10 +1,45 @@
 import * as react from 'react';
-import { RefObject, ComponentPropsWithoutRef, ElementType, ReactNode } from 'react';
-import { MarqueeOptions, InputOptions, ButtonState, ButtonOptions, GeneratePasswordOptions, EstimateOptions, PasswordStrengthReport } from '../index.js';
+import { ComponentPropsWithoutRef, ElementType, ReactNode, RefObject } from 'react';
+import { ButtonOptions, ButtonState, MarqueeOptions, InputOptions, GeneratePasswordOptions, EstimateOptions, PasswordStrengthReport } from '../index.js';
 export { InputAction, InputIcon, MarqueeHover, MarqueeInstance, PasswordScore, estimatePasswordStrength, generatePassword } from '../index.js';
 import { b as SearchMatch, c as SearchOptions } from '../search-CsO3L1Lw.js';
 export { F as FuseConstructor } from '../search-CsO3L1Lw.js';
 
+/**
+ * `<Button>` - the component, for the ninety percent.
+ *
+ * ```tsx
+ * <Button onPress={save}>Save</Button>
+ * ```
+ *
+ * That is the whole thing: disabled while the work runs, `aria-busy`, `data-loading`, and a
+ * cooldown afterwards if you asked for one. `useButton` is still there for a button whose
+ * markup is nothing like a button - a card, a table row - but reaching for it to render an
+ * ordinary one means writing the same six lines at every call site, which is how they drift.
+ */
+interface ButtonProps extends ButtonOptions, Omit<ComponentPropsWithoutRef<"button">, "onClick" | "onChange" | "children" | "type"> {
+    /**
+     * Override what to render. You rarely need it: an href already renders whatever
+     * `setLinkComponent` registered - your router's Link - and a button otherwise.
+     */
+    as?: ElementType;
+    /**
+     * The label, or a function of the state for one that changes with it.
+     *
+     * ```tsx
+     * <Button onPress={send} cooldown={30_000}>
+     *     {({ loading, cooldown }) => loading ? "Sending" : cooldown ? `Wait ${Math.ceil(cooldown / 1000)}s` : "Resend"}
+     * </Button>
+     * ```
+     */
+    children?: ReactNode | ((state: ButtonState) => ReactNode);
+    /** Replaces the label while async work runs - a spinner, or just different words. */
+    pending?: ReactNode;
+    /** `type` on a real button. Ignored on a link, which has none. */
+    type?: "button" | "submit" | "reset";
+}
+declare const Button: react.ForwardRefExoticComponent<ButtonProps & react.RefAttributes<HTMLElement>>;
+
 interface UseMarqueeResult {
     /** Attach to the clipping viewport. */
     laneRef: RefObject<HTMLElement | null>;
@@ -129,44 +164,10 @@ interface UseButtonResult extends ButtonState {
  */
 declare function useButton(options?: ButtonOptions): UseButtonResult;
 
-/**
- * `<Button>` - the component, for the ninety percent.
- *
- * ```tsx
- * <Button onPress={save}>Save</Button>
- * ```
- *
- * That is the whole thing: disabled while the work runs, `aria-busy`, `data-loading`, and a
- * cooldown afterwards if you asked for one. `useButton` is still there for a button whose
- * markup is nothing like a button - a card, a table row - but reaching for it to render an
- * ordinary one means writing the same six lines at every call site, which is how they drift.
- */
-interface ButtonProps extends ButtonOptions, Omit<ComponentPropsWithoutRef<"button">, "onClick" | "onChange" | "children" | "type"> {
-    /**
-     * What to render. Defaults to `a` when there is an href and `button` otherwise, which
-     * is what you want until a router is involved - then pass its Link and keep the rest.
-     *
-     * ```tsx
-     * <Button as={Link} href="/settings">Settings</Button>
-     * ```
-     */
-    as?: ElementType;
-    /**
-     * The label, or a function of the state for one that changes with it.
-     *
-     * ```tsx
-     * <Button onPress={send} cooldown={30_000}>
-     *     {({ loading, cooldown }) => loading ? "Sending" : cooldown ? `Wait ${Math.ceil(cooldown / 1000)}s` : "Resend"}
-     * </Button>
-     * ```
-     */
-    children?: ReactNode | ((state: ButtonState) => ReactNode);
-    /** Replaces the label while async work runs - a spinner, or just different words. */
-    pending?: ReactNode;
-    /** `type` on a real button. Ignored on a link, which has none. */
-    type?: "button" | "submit" | "reset";
-}
-declare const Button: react.ForwardRefExoticComponent<ButtonProps & react.RefAttributes<HTMLElement>>;
+/** Register the router's link. Pass null to go back to a plain anchor. */
+declare function setLinkComponent(component: ElementType | null): void;
+/** What an href should render as right now. */
+declare function getLinkComponent(): ElementType;
 
 /** An extra button inside the field. The built-ins are the same shape. */
 interface FieldAction {
@@ -278,4 +279,4 @@ interface PasswordStrengthProps extends Omit<ComponentPropsWithoutRef<"div">, "c
  */
 declare function PasswordStrength({ value, report, userInputs, segments, labels, showWarning, classNames, ...props }: PasswordStrengthProps): ReactNode;
 
-export { type BreachChecker, type BreachState, type BreachStatus, Button, ButtonOptions, type ButtonProps, ButtonState, EstimateOptions, type FieldAction, GeneratePasswordOptions, Input, InputOptions, type InputProps, MarqueeOptions, PasswordStrength, type PasswordStrengthProps, PasswordStrengthReport, SearchMatch, SearchOptions, type UseButtonResult, type UseInputResult, type UseMarqueeResult, type UseSearchResult, useButton, useInput, useMarquee, useSearch };
+export { type BreachChecker, type BreachState, type BreachStatus, Button, ButtonOptions, type ButtonProps, ButtonState, EstimateOptions, type FieldAction, GeneratePasswordOptions, Input, InputOptions, type InputProps, MarqueeOptions, PasswordStrength, type PasswordStrengthProps, PasswordStrengthReport, SearchMatch, SearchOptions, type UseButtonResult, type UseInputResult, type UseMarqueeResult, type UseSearchResult, getLinkComponent, setLinkComponent, useButton, useInput, useMarquee, useSearch };

package/dist/react/index.js

@@ -1,459 +1,4 @@
 "use client";
-import { generatePassword, estimatePasswordStrength, INPUT_ICON_PATHS, createButton, createMarquee, createInput } from '../chunk-42Y7OOJM.js';
+export { Button, Input, PasswordStrength, getLinkComponent, setLinkComponent, useButton, useInput, useMarquee, useSearch } from '../chunk-L4KA342C.js';
 export { estimatePasswordStrength, generatePassword } from '../chunk-42Y7OOJM.js';
-import { createSearch } from '../chunk-UZFEEFMF.js';
-import { forwardRef, createElement, useRef, useState, useId, useCallback, useEffect, useMemo, useLayoutEffect } from 'react';
-import { jsx, jsxs } from 'react/jsx-runtime';
-
-var useIsomorphicLayoutEffect = typeof window === "undefined" ? useEffect : useLayoutEffect;
-function useMarquee(options = {}) {
-  const laneRef = useRef(null);
-  const trackRef = useRef(null);
-  const instanceRef = useRef(null);
-  const optionsRef = useRef(options);
-  optionsRef.current = options;
-  const [copies, setCopies] = useState(2);
-  const [dragging, setDragging] = useState(false);
-  const [period, setPeriod] = useState(0);
-  useIsomorphicLayoutEffect(() => {
-    const lane = laneRef.current;
-    const track = trackRef.current;
-    if (!lane || !track) return;
-    const instance = createMarquee(lane, track, {
-      ...optionsRef.current,
-      // React owns the DOM; cloning behind its back would be undone on render.
-      copies: "external",
-      onCopyCountChange: setCopies,
-      onMeasure: (measured) => setPeriod(measured),
-      onItemClick: (event) => optionsRef.current.onItemClick?.(event)
-    });
-    instanceRef.current = instance;
-    const syncDragging = () => setDragging(instance.dragging);
-    lane.addEventListener("pointerdown", syncDragging);
-    window.addEventListener("pointerup", syncDragging);
-    window.addEventListener("pointercancel", syncDragging);
-    return () => {
-      lane.removeEventListener("pointerdown", syncDragging);
-      window.removeEventListener("pointerup", syncDragging);
-      window.removeEventListener("pointercancel", syncDragging);
-      instance.destroy();
-      instanceRef.current = null;
-    };
-  }, []);
-  useIsomorphicLayoutEffect(() => {
-    instanceRef.current?.update(options);
-  }, [options.speed, options.reverse, options.vertical, options.draggable, options.hover, options.decay]);
-  useIsomorphicLayoutEffect(() => {
-    instanceRef.current?.measure();
-  }, [copies]);
-  return {
-    laneRef,
-    trackRef,
-    copies,
-    dragging,
-    period,
-    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("");
-    }
-  };
-}
-function useButton(options = {}) {
-  const optionsRef = useRef(options);
-  optionsRef.current = options;
-  const instance = useMemo(() => createButton({
-    ...optionsRef.current,
-    onPress: (event) => optionsRef.current.onPress?.(event),
-    onChange: (next) => optionsRef.current.onChange?.(next)
-    // Built once: recreating it would drop a running cooldown on every render.
-    // eslint-disable-next-line react-hooks/exhaustive-deps
-  }), []);
-  const [state, setState] = useState(() => instance.state);
-  useEffect(() => {
-    const unsubscribe = instance.subscribe(setState);
-    setState(instance.state);
-    return () => {
-      unsubscribe();
-      instance.destroy();
-    };
-  }, [instance]);
-  useEffect(() => {
-    instance.update({
-      href: options.href,
-      disabled: options.disabled,
-      loading: options.loading,
-      cooldown: options.cooldown,
-      shortcut: options.shortcut
-    });
-  }, [instance, options.href, options.disabled, options.loading, options.cooldown, options.shortcut]);
-  const press = useCallback(() => {
-    void instance.press();
-  }, [instance]);
-  return {
-    ...state,
-    press,
-    reset: () => instance.reset(),
-    props: {
-      onClick: (event) => {
-        if (!state.available) {
-          event.preventDefault();
-          return;
-        }
-        void instance.press();
-      },
-      "aria-disabled": !state.available,
-      "aria-busy": state.loading,
-      ...state.loading ? { "data-loading": "" } : {},
-      ...state.cooldown > 0 ? { "data-cooldown": "" } : {},
-      ...state.element === "button" ? { disabled: state.disabled } : { href: options.href },
-      ...state.shortcut ? { title: `Shortcut: ${state.shortcut.toUpperCase()}` } : {}
-    }
-  };
-}
-var Button = forwardRef(function Button2({
-  as,
-  children,
-  pending,
-  href,
-  disabled,
-  loading,
-  cooldown,
-  shortcut,
-  onPress,
-  onChange,
-  type = "button",
-  ...rest
-}, ref) {
-  const button = useButton({ href, disabled, loading, cooldown, shortcut, onPress, onChange });
-  const state = button;
-  const Tag = as ?? state.element;
-  const native = Tag === "button" ? { type } : {};
-  const label = typeof children === "function" ? children(state) : children;
-  return createElement(
-    Tag,
-    { ref, ...button.props, ...native, ...rest },
-    state.loading && pending !== void 0 ? pending : label
-  );
-});
-var ICON_PROPS = {
-  viewBox: "0 0 24 24",
-  width: "1em",
-  height: "1em",
-  fill: "none",
-  stroke: "currentColor",
-  strokeWidth: 2,
-  strokeLinecap: "round",
-  strokeLinejoin: "round",
-  "aria-hidden": true
-};
-function Icon({ paths }) {
-  return /* @__PURE__ */ jsx("svg", { ...ICON_PROPS, children: paths.map((path) => /* @__PURE__ */ jsx("path", { d: path }, path)) });
-}
-function writeValue(input, next) {
-  const setter = Object.getOwnPropertyDescriptor(HTMLInputElement.prototype, "value")?.set;
-  if (setter) setter.call(input, next);
-  else input.value = next;
-  input.dispatchEvent(new Event("input", { bubbles: true }));
-}
-var Input = forwardRef(function Input2({
-  reveal,
-  revealLabels,
-  generate = false,
-  generateLabel = "Generate a password",
-  revealOnGenerate = true,
-  copyOnGenerate = false,
-  onGenerate,
-  actions = [],
-  position = "end",
-  strength = false,
-  onStrengthChange,
-  breach,
-  breachDelay = 500,
-  onBreachChange,
-  wrapperProps,
-  fieldProps,
-  classNames,
-  children,
-  type = "text",
-  onChange,
-  ...props
-}, forwardedRef) {
-  const innerRef = useRef(null);
-  const [revealed, setRevealed] = useState(false);
-  const describedBy = useId();
-  const isPassword = type === "password";
-  const showReveal = reveal ?? isPassword;
-  const showGenerate = generate !== false && isPassword;
-  const controlled = props.value !== void 0;
-  const [ownValue, setOwnValue] = useState(String(props.defaultValue ?? ""));
-  const value = controlled ? String(props.value ?? "") : ownValue;
-  const handleChange = useCallback((event) => {
-    if (!controlled) setOwnValue(event.target.value);
-    onChange?.(event);
-  }, [controlled, onChange]);
-  const caret = useRef(null);
-  const toggleReveal = useCallback(() => {
-    const input = innerRef.current;
-    if (input && typeof document !== "undefined" && document.activeElement === input) {
-      try {
-        const { selectionStart, selectionEnd } = input;
-        caret.current = selectionStart === null || selectionEnd === null ? null : [selectionStart, selectionEnd];
-      } catch {
-        caret.current = null;
-      }
-    }
-    setRevealed((current) => !current);
-  }, []);
-  useEffect(() => {
-    const selection = caret.current;
-    if (!selection) return;
-    caret.current = null;
-    const restore = () => {
-      const input = innerRef.current;
-      if (!input || document.activeElement !== input) return;
-      try {
-        input.setSelectionRange(selection[0], selection[1]);
-      } catch {
-      }
-    };
-    restore();
-    const timer = setTimeout(restore, 0);
-    return () => clearTimeout(timer);
-  }, [revealed]);
-  const handleGenerate = useCallback(() => {
-    const input = innerRef.current;
-    if (!input) return;
-    const password = generatePassword(typeof generate === "object" ? generate : {});
-    writeValue(input, password);
-    if (revealOnGenerate) setRevealed(true);
-    if (copyOnGenerate) void navigator.clipboard?.writeText(password).catch(() => {
-    });
-    input.focus();
-    onGenerate?.(password);
-  }, [generate, revealOnGenerate, copyOnGenerate, onGenerate]);
-  const estimateOptions = typeof strength === "object" ? strength : void 0;
-  const userInputs = estimateOptions?.userInputs;
-  const report = useMemo(
-    () => strength === false ? null : estimatePasswordStrength(value, { userInputs }),
-    // The array is compared by identity, so a literal would re-estimate every render.
-    [strength, value, userInputs]
-  );
-  const strengthListener = useRef(onStrengthChange);
-  strengthListener.current = onStrengthChange;
-  useEffect(() => {
-    if (report) strengthListener.current?.(report);
-  }, [report]);
-  const [breachState, setBreachState] = useState({ status: "idle", count: 0, error: null });
-  const breachListener = useRef(onBreachChange);
-  breachListener.current = onBreachChange;
-  useEffect(() => {
-    if (!breach || !value) {
-      setBreachState({ status: "idle", count: 0, error: null });
-      return;
-    }
-    const controller = new AbortController();
-    const timer = setTimeout(() => {
-      setBreachState({ status: "checking", count: 0, error: null });
-      breach(value, { signal: controller.signal }).then((result) => {
-        if (controller.signal.aborted) return;
-        setBreachState({ status: result.breached ? "breached" : "safe", count: result.count, error: null });
-      }).catch((error) => {
-        if (controller.signal.aborted) return;
-        setBreachState({ status: "error", count: 0, error });
-      });
-    }, breachDelay);
-    return () => {
-      clearTimeout(timer);
-      controller.abort();
-    };
-  }, [breach, value, breachDelay]);
-  useEffect(() => {
-    breachListener.current?.(breachState);
-  }, [breachState]);
-  const builtIn = [];
-  if (showGenerate) {
-    builtIn.push({
-      name: "generate",
-      label: generateLabel,
-      icon: /* @__PURE__ */ jsx(Icon, { paths: INPUT_ICON_PATHS.generate }),
-      onSelect: handleGenerate
-    });
-  }
-  if (showReveal) {
-    builtIn.push({
-      name: "reveal",
-      label: revealed ? revealLabels?.hide ?? "Hide password" : revealLabels?.show ?? "Show password",
-      icon: /* @__PURE__ */ jsx(Icon, { paths: revealed ? INPUT_ICON_PATHS.eyeOff : INPUT_ICON_PATHS.eye }),
-      pressed: revealed,
-      onSelect: toggleReveal
-    });
-  }
-  const overridden = new Set(actions.map((action) => action.name));
-  const rendered = [...builtIn.filter((action) => !overridden.has(action.name)), ...actions].filter((action) => action.visible !== false);
-  const locked = props.disabled === true || props.readOnly === true;
-  const buttons = rendered.length === 0 ? null : /* @__PURE__ */ jsx("span", { "data-enigma-input-actions": "", "data-position": position, className: classNames?.actions, children: rendered.map((action) => /* @__PURE__ */ jsx(
-    "button",
-    {
-      type: "button",
-      "data-enigma-input-action": action.name,
-      className: classNames?.action,
-      "aria-label": action.label,
-      title: action.label,
-      "aria-pressed": action.pressed,
-      disabled: locked,
-      onMouseDown: (event) => event.preventDefault(),
-      onClick: action.onSelect,
-      children: action.icon
-    },
-    action.name
-  )) });
-  return /* @__PURE__ */ jsxs(
-    "div",
-    {
-      ...wrapperProps,
-      "data-enigma-input-root": "",
-      "data-revealed": revealed ? "" : void 0,
-      "data-breached": breachState.status === "breached" ? "" : void 0,
-      "data-score": report && !report.empty ? report.score : void 0,
-      children: [
-        /* @__PURE__ */ jsxs("div", { ...fieldProps, "data-enigma-input-field": "", children: [
-          position === "start" && buttons,
-          /* @__PURE__ */ jsx(
-            "input",
-            {
-              ...props,
-              ref: (node) => {
-                innerRef.current = node;
-                if (typeof forwardedRef === "function") forwardedRef(node);
-                else if (forwardedRef) forwardedRef.current = node;
-              },
-              type: revealed && isPassword ? "text" : type,
-              onChange: handleChange,
-              "data-enigma-input": "",
-              "aria-describedby": report ? describedBy : props["aria-describedby"]
-            }
-          ),
-          position === "end" && buttons
-        ] }),
-        report && /* @__PURE__ */ jsx(PasswordStrength, { id: describedBy, report, classNames: classNames?.strength }),
-        children
-      ]
-    }
-  );
-});
-var SCORE_LABELS = ["Very weak", "Weak", "Fair", "Strong", "Very strong"];
-function PasswordStrength({
-  value = "",
-  report,
-  userInputs,
-  segments = 5,
-  labels = SCORE_LABELS,
-  showWarning = true,
-  classNames,
-  ...props
-}) {
-  const computed = useMemo(
-    () => report ?? estimatePasswordStrength(value, { userInputs }),
-    [report, value, userInputs]
-  );
-  const score = computed.score;
-  return /* @__PURE__ */ jsxs(
-    "div",
-    {
-      ...props,
-      "data-enigma-password-strength": "",
-      "data-score": computed.empty ? void 0 : score,
-      "data-empty": computed.empty ? "" : void 0,
-      children: [
-        /* @__PURE__ */ jsx("div", { "data-enigma-password-strength-track": "", "aria-hidden": "true", className: classNames?.track, children: Array.from({ length: segments }, (unused, index) => /* @__PURE__ */ jsx(
-          "span",
-          {
-            "data-enigma-password-strength-segment": "",
-            className: classNames?.segment,
-            "data-filled": !computed.empty && index <= score ? "" : void 0
-          },
-          index
-        )) }),
-        /* @__PURE__ */ jsx("p", { "data-enigma-password-strength-label": "", role: "status", "aria-live": "polite", className: classNames?.label, children: computed.empty ? "" : labels[score] ?? "" }),
-        showWarning && !computed.empty && computed.warnings.length > 0 && /* @__PURE__ */ jsx("p", { "data-enigma-password-strength-warning": "", className: classNames?.warning, children: computed.warnings[0] })
-      ]
-    }
-  );
-}
-
-export { Button, Input, PasswordStrength, useButton, useInput, useMarquee, useSearch };
+import '../chunk-UZFEEFMF.js';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@enigmax/primitives",
-  "version": "0.8.0",
+  "version": "0.10.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",
@@ -18,13 +18,17 @@
     "./search": {
       "types": "./dist/search/index.d.ts",
       "import": "./dist/search/index.js"
+    },
+    "./next": {
+      "types": "./dist/next/index.d.ts",
+      "import": "./dist/next/index.js"
     }
   },
   "scripts": {
     "build": "tsup",
     "typecheck": "tsc --noEmit",
     "test": "npm run test:fixtures && playwright test",
-    "test:fixtures": "esbuild test/fixture/react.tsx --bundle --format=esm --jsx=automatic --outfile=test/fixture/build/react.js --tsconfig=tsconfig.json",
+    "test:fixtures": "esbuild test/fixture/react.tsx --bundle --format=esm --jsx=automatic --outfile=test/fixture/build/react.js --tsconfig=tsconfig.json --alias:next/link=./test/fixture/next-link-stub.tsx",
     "test:install": "playwright install chromium",
     "prepublishOnly": "npm run typecheck && npm run build"
   },
@@ -38,7 +42,8 @@
   ],
   "peerDependencies": {
     "fuse.js": ">=6",
-    "react": ">=18"
+    "react": ">=18",
+    "next": ">=13"
   },
   "peerDependenciesMeta": {
     "react": {
@@ -46,6 +51,9 @@
     },
     "fuse.js": {
       "optional": true
+    },
+    "next": {
+      "optional": true
     }
   },
   "devDependencies": {
@@ -53,6 +61,7 @@
     "@types/react": "^19.2.0",
     "@types/react-dom": "^19.2.4",
     "fuse.js": "^7.0.0",
+    "next": "^15.5.23",
     "react": "^19.2.0",
     "react-dom": "^19.2.8",
     "tsup": "^8.0.0",

package/registry.json

@@ -301,6 +301,7 @@
         ],
         "react": [
           "Button",
+          "setLinkComponent",
           "useButton"
         ]
       },
@@ -324,6 +325,13 @@
             "@/core/button": "./button"
           }
         },
+        {
+          "path": "src/react/link.ts",
+          "dest": "button/link.ts",
+          "targets": [
+            "react"
+          ]
+        },
         {
           "path": "src/react/button.tsx",
           "dest": "button/index.tsx",
@@ -333,7 +341,8 @@
           ],
           "rewrite": {
             "@/core/button": "./button",
-            "@/react/use-button": "./use-button"
+            "@/react/use-button": "./use-button",
+            "@/react/link": "./link"
           }
         }
       ],

package/src/next/index.tsx

@@ -0,0 +1,32 @@
+"use client";
+
+import Link from "next/link";
+import { forwardRef, createElement } from "react";
+import { Button as BaseButton, type ButtonProps } from "@/react/button";
+
+/**
+ * The Next.js entry. Same components, wired to `next/link`.
+ *
+ * ```tsx
+ * import { Button } from "@enigmax/primitives/next";
+ *
+ * <Button href="/settings">Settings</Button>   // renders next/link
+ * ```
+ *
+ * The import path is the configuration. There is nothing to register and nothing to pass at
+ * the call site, and a project that is not on Next never resolves this file - which is the
+ * whole reason the main entry cannot simply `import Link from "next/link"` itself: that
+ * import is a build error for every consumer on Vite, Astro, Remix or plain React.
+ *
+ * Everything else is re-exported unchanged, so this can be the only import path in a Next
+ * app rather than a second one to remember.
+ */
+
+export const Button = forwardRef<HTMLElement, ButtonProps>(function Button(props, ref) {
+    // Only an href makes it a link; a plain button must not be handed a router component.
+    return createElement(BaseButton, { ...props, as: props.as ?? (props.href ? Link : undefined), ref });
+});
+
+// `export *` skips names this module exports itself, so the Button above is the one a
+// consumer gets and everything else comes straight from the React entry.
+export * from "@/react/index";

package/src/react/button.tsx

@@ -1,6 +1,7 @@
 "use client";
 
 import { useButton } from "@/react/use-button";
+import { getLinkComponent } from "@/react/link";
 import type { ButtonOptions, ButtonState } from "@/core/button";
 import { createElement, forwardRef, type ComponentPropsWithoutRef, type ElementType, type ReactNode } from "react";
 
@@ -21,12 +22,8 @@ import { createElement, forwardRef, type ComponentPropsWithoutRef, type ElementT
 // reports the button's state - would otherwise clash with the form event of the same name.
 export interface ButtonProps extends ButtonOptions, Omit<ComponentPropsWithoutRef<"button">, "onClick" | "onChange" | "children" | "type"> {
     /**
-     * What to render. Defaults to `a` when there is an href and `button` otherwise, which
-     * is what you want until a router is involved - then pass its Link and keep the rest.
-     *
-     * ```tsx
-     * <Button as={Link} href="/settings">Settings</Button>
-     * ```
+     * Override what to render. You rarely need it: an href already renders whatever
+     * `setLinkComponent` registered - your router's Link - and a button otherwise.
      */
     as?: ElementType;
     /**
@@ -62,9 +59,11 @@ export const Button = forwardRef<HTMLElement, ButtonProps>(function Button({
     const button = useButton({ href, disabled, loading, cooldown, shortcut, onPress, onChange });
     const state: ButtonState = button;
 
-    // Reported, not chosen: an href makes it an anchor, and a package that cannot import
-    // next/link must not be the thing deciding. `as` overrides both.
-    const Tag: ElementType = as ?? state.element;
+    // An href renders the registered link - next/link, react-router's, whatever was passed
+    // to setLinkComponent - and a plain <a> when nothing was. The package cannot import a
+    // router itself, so registering one is what turns every href into a client navigation
+    // without a word at the call site.
+    const Tag: ElementType = as ?? (state.element === "a" ? getLinkComponent() : "button");
 
     // `type="button"` is the default on purpose. A bare <button> inside a form submits it,
     // so an action button that forgot it posts the form instead of doing its job.

package/src/react/index.ts

@@ -8,6 +8,7 @@ export { type InputOptions, type InputAction, type InputIcon } from "@/core/inpu
 export { type SearchOptions, type SearchMatch, type FuseConstructor } from "@/core/search";
 export { useButton, type UseButtonResult } from "@/react/use-button";
 export { Button, type ButtonProps } from "@/react/button";
+export { setLinkComponent, getLinkComponent } from "@/react/link";
 export { type ButtonOptions, type ButtonState } from "@/core/button";
 export {
     Input,

package/src/react/link.ts

@@ -0,0 +1,45 @@
+"use client";
+
+import type { ElementType } from "react";
+
+/**
+ * The component every `href` in this package renders through.
+ *
+ * The package cannot `import Link from "next/link"`. It is framework-agnostic and Next is
+ * not a dependency, so that import would fail to resolve for every consumer who is not on
+ * Next - a hard build error in Vite, Astro, Remix and plain React.
+ *
+ * So it is registered instead, ONCE, and after that an href is a router link everywhere:
+ *
+ * ```tsx
+ * // app/providers.tsx, or wherever your app starts
+ * import Link from "next/link";
+ * import { setLinkComponent } from "@enigmax/primitives/react";
+ *
+ * setLinkComponent(Link);
+ * ```
+ *
+ * ```tsx
+ * // and from then on, every call site
+ * <Button href="/settings">Settings</Button>
+ * ```
+ *
+ * Without it an href renders a plain `<a>`, which is correct everywhere and merely means a
+ * full page load under a router. Any router works the same way - react-router's `Link`,
+ * TanStack Router's, Astro has none to register.
+ *
+ * A module-level value rather than a context: it is one component reference for the whole
+ * app, identical on every request, so threading a provider through the tree would buy
+ * nothing and cost every consumer a wrapper.
+ */
+let linkComponent: ElementType | null = null;
+
+/** Register the router's link. Pass null to go back to a plain anchor. */
+export function setLinkComponent(component: ElementType | null): void {
+    linkComponent = component;
+}
+
+/** What an href should render as right now. */
+export function getLinkComponent(): ElementType {
+    return linkComponent ?? "a";
+}