@enigmax/primitives 0.7.0 → 0.9.0

package/dist/react/index.d.ts

@@ -1,5 +1,5 @@
 import * as react from 'react';
-import { RefObject, ReactNode, ComponentPropsWithoutRef } from 'react';
+import { RefObject, ComponentPropsWithoutRef, ElementType, ReactNode } from 'react';
 import { MarqueeOptions, InputOptions, ButtonState, ButtonOptions, 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';
@@ -129,6 +129,46 @@ 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"> {
+    /**
+     * 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>>;
+
+/** 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 {
     /** Stable id. Lands on `data-enigma-input-action`, and replaces a built-in of the same name. */
@@ -239,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, ButtonOptions, 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,8 +1,8 @@
 "use client";
-import { generatePassword, estimatePasswordStrength, INPUT_ICON_PATHS, createMarquee, createInput, createButton } from '../chunk-42Y7OOJM.js';
+import { generatePassword, estimatePasswordStrength, INPUT_ICON_PATHS, createButton, createMarquee, createInput } from '../chunk-42Y7OOJM.js';
 export { estimatePasswordStrength, generatePassword } from '../chunk-42Y7OOJM.js';
 import { createSearch } from '../chunk-UZFEEFMF.js';
-import { forwardRef, useRef, useState, useId, useCallback, useEffect, useMemo, useLayoutEffect } from 'react';
+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;
@@ -185,6 +185,40 @@ function useButton(options = {}) {
     }
   };
 }
+
+// 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",
@@ -431,4 +465,4 @@ function PasswordStrength({
   );
 }
 
-export { Input, PasswordStrength, useButton, useInput, useMarquee, useSearch };
+export { Button, Input, PasswordStrength, getLinkComponent, setLinkComponent, useButton, useInput, useMarquee, useSearch };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@enigmax/primitives",
-  "version": "0.7.0",
+  "version": "0.9.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",

package/recipes/{marquee.css.tsx → marquee/css.tsx}

@@ -1,4 +1,4 @@
-import "./marquee.css";
+import "./styles.css";
 import type { ReactNode, Ref } from "react";
 import { useMarquee, type MarqueeHover } from "@enigmax/primitives/react";
 

package/registry.json

@@ -31,7 +31,7 @@
       "files": [
         {
           "path": "src/core/marquee.ts",
-          "dest": "marquee.ts",
+          "dest": "marquee/marquee.ts",
           "targets": [
             "vanilla",
             "astro",
@@ -40,33 +40,34 @@
         },
         {
           "path": "src/react/use-marquee.ts",
-          "dest": "use-marquee.ts",
+          "dest": "marquee/use-marquee.ts",
           "targets": [
             "react"
           ],
           "rewrite": {
             "@/core/marquee": "./marquee"
-          }
+          },
+          "main": true
         },
         {
-          "path": "recipes/marquee.tailwind.tsx",
-          "dest": "Marquee.tsx",
+          "path": "recipes/marquee/tailwind.tsx",
+          "dest": "marquee/Marquee.tsx",
           "targets": [
             "react"
           ],
           "style": "tailwind"
         },
         {
-          "path": "recipes/marquee.css.tsx",
-          "dest": "Marquee.tsx",
+          "path": "recipes/marquee/css.tsx",
+          "dest": "marquee/Marquee.tsx",
           "targets": [
             "react"
           ],
           "style": "css"
         },
         {
-          "path": "recipes/marquee.css",
-          "dest": "marquee.css",
+          "path": "recipes/marquee/styles.css",
+          "dest": "marquee/styles.css",
           "targets": [
             "react",
             "vanilla",
@@ -235,7 +236,7 @@
       "files": [
         {
           "path": "src/core/search.ts",
-          "dest": "search.ts",
+          "dest": "search/search.ts",
           "targets": [
             "vanilla",
             "astro",
@@ -244,17 +245,18 @@
         },
         {
           "path": "src/react/use-search.ts",
-          "dest": "use-search.ts",
+          "dest": "search/use-search.ts",
           "targets": [
             "react"
           ],
           "rewrite": {
             "@/core/search": "./search"
-          }
+          },
+          "main": true
         },
         {
-          "path": "recipes/search.tailwind.tsx",
-          "dest": "Search.tsx",
+          "path": "recipes/search/tailwind.tsx",
+          "dest": "search/Search.tsx",
           "targets": [
             "react"
           ],
@@ -278,8 +280,8 @@
     },
     {
       "name": "button",
-      "title": "Button behaviour",
-      "description": "Disabled, loading, a keyboard shortcut and a cooldown that can outlive a reload, collapsed into one `available` the renderer reads. An href reports an anchor rather than a button, so the framework's own Link stays your choice.",
+      "title": "Button",
+      "description": "A button you pass props to. Disabled, loading, a keyboard shortcut and a cooldown that can outlive a reload collapse into one `available`; an href reports an anchor, so the framework's own Link stays your choice.",
       "targets": [
         "vanilla",
         "astro",
@@ -298,13 +300,15 @@
           "createButton"
         ],
         "react": [
+          "Button",
+          "setLinkComponent",
           "useButton"
         ]
       },
       "files": [
         {
           "path": "src/core/button.ts",
-          "dest": "button.ts",
+          "dest": "button/button.ts",
           "targets": [
             "vanilla",
             "astro",
@@ -313,13 +317,33 @@
         },
         {
           "path": "src/react/use-button.ts",
-          "dest": "use-button.ts",
+          "dest": "button/use-button.ts",
           "targets": [
             "react"
           ],
           "rewrite": {
             "@/core/button": "./button"
           }
+        },
+        {
+          "path": "src/react/link.ts",
+          "dest": "button/link.ts",
+          "targets": [
+            "react"
+          ]
+        },
+        {
+          "path": "src/react/button.tsx",
+          "dest": "button/index.tsx",
+          "main": true,
+          "targets": [
+            "react"
+          ],
+          "rewrite": {
+            "@/core/button": "./button",
+            "@/react/use-button": "./use-button",
+            "@/react/link": "./link"
+          }
         }
       ],
       "styles": false,

package/src/react/button.tsx

@@ -0,0 +1,79 @@
+"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";
+
+/**
+ * `<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.
+ */
+
+// `onChange` is omitted from the DOM side because the primitive's own onChange - which
+// 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"> {
+    /**
+     * 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";
+}
+
+export const Button = forwardRef<HTMLElement, ButtonProps>(function Button({
+    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: ButtonState = button;
+
+    // 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.
+    const native = Tag === "button" ? { type } : {};
+
+    const label = typeof children === "function" ? children(state) : children;
+
+    return createElement(
+        Tag,
+        { ref, ...button.props, ...native, ...rest },
+        state.loading && pending !== undefined ? pending : label
+    );
+});

package/src/react/index.ts

@@ -7,6 +7,8 @@ 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";
 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";
+}