@enigmax/primitives 0.2.0 → 0.3.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@enigmax/primitives",
-  "version": "0.2.0",
+  "version": "0.3.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",
@@ -26,6 +26,7 @@
   "files": [
     "dist",
     "src",
+    "recipes",
     "registry.json",
     "README.md",
     "LICENSE"

package/recipes/input.css

@@ -0,0 +1,32 @@
+/* A starting point for the field, yours to edit. The primitive creates the action
+   buttons and publishes their state; it decides nothing about how they look. */
+
+.enigma-field { display: grid; gap: 0.375rem; }
+.enigma-field__label { font-size: 0.75rem; color: #a3a3a3; }
+
+.enigma-field__box {
+    display: flex; align-items: center; gap: 0.375rem;
+    padding: 0 0.75rem;
+    background: #171717; border: 1px solid #404040; border-radius: 0.5rem;
+}
+.enigma-field__box:focus-within { border-color: #a3a3a3; }
+
+.enigma-field__input {
+    flex: 1; min-width: 0; padding: 0.625rem 0;
+    font-size: 0.875rem; color: #f5f5f5;
+    background: transparent; border: 0; outline: none;
+}
+
+/* The engine's buttons. Styled through its hooks, never through a className. */
+[data-enigma-input-actions] { display: inline-flex; gap: 0.125rem; }
+[data-enigma-input-actions][data-position="start"] { order: -1; }
+
+[data-enigma-input-action] {
+    display: grid; place-items: center;
+    width: 1.75rem; height: 1.75rem;
+    color: #a3a3a3; background: none; border: 0; border-radius: 0.375rem;
+    cursor: pointer; font-size: 0.9375rem;
+}
+[data-enigma-input-action]:hover { color: #f5f5f5; background: #262626; }
+[data-enigma-input-action][aria-pressed="true"] { color: #fbbf24; }
+[data-enigma-input-action]:disabled { opacity: 0.5; cursor: default; }

package/recipes/input.css.tsx

@@ -0,0 +1,28 @@
+import "./input.css";
+import type { InputHTMLAttributes } from "react";
+import { useInput } from "@enigmax/primitives/react";
+
+/**
+ * A styled field, yours to edit.
+ *
+ * The reveal toggle, its accessible name, its pressed state and the caret handling all
+ * come from the primitive. input.css beside this file is a starting point.
+ */
+export interface FieldProps extends InputHTMLAttributes<HTMLInputElement> {
+    label?: string;
+    /** Remove the automatic password reveal. */
+    reveal?: boolean;
+}
+
+export function Field({ label, reveal = true, className = "", ...props }: FieldProps) {
+    const { inputRef } = useInput({ reveal });
+
+    return (
+        <label className="enigma-field">
+            {label && <span className="enigma-field__label">{label}</span>}
+            <span className="enigma-field__box">
+                <input ref={inputRef} className={`enigma-field__input ${className}`.trim()} {...props} />
+            </span>
+        </label>
+    );
+}

package/recipes/input.tailwind.tsx

@@ -0,0 +1,44 @@
+import type { InputHTMLAttributes } from "react";
+import { useInput } from "@enigmax/primitives/react";
+
+/**
+ * A styled field, yours to edit.
+ *
+ * The reveal toggle, its accessible name, its pressed state and the caret handling all
+ * come from the primitive. Every class below is a suggestion.
+ *
+ * The action buttons are created by the engine, so they are styled through the
+ * data-* hooks rather than a className prop - hence the arbitrary-variant selectors.
+ */
+export interface FieldProps extends InputHTMLAttributes<HTMLInputElement> {
+    label?: string;
+    /** Remove the automatic password reveal. */
+    reveal?: boolean;
+}
+
+export function Field({ label, reveal = true, className = "", ...props }: FieldProps) {
+    const { inputRef } = useInput({ reveal });
+
+    return (
+        <label className="grid gap-1.5">
+            {label && <span className="text-xs text-neutral-400">{label}</span>}
+            <span
+                className="
+                    flex items-center gap-1.5 rounded-lg border border-neutral-700 bg-neutral-900 px-3
+                    focus-within:border-neutral-400
+                    [&_[data-enigma-input-actions]]:inline-flex
+                    [&_[data-enigma-input-action]]:grid [&_[data-enigma-input-action]]:size-7 [&_[data-enigma-input-action]]:place-items-center
+                    [&_[data-enigma-input-action]]:rounded-md [&_[data-enigma-input-action]]:text-neutral-400
+                    [&_[data-enigma-input-action]:hover]:bg-neutral-800 [&_[data-enigma-input-action]:hover]:text-neutral-100
+                    [&_[data-enigma-input-action][aria-pressed=true]]:text-amber-400
+                "
+            >
+                <input
+                    ref={inputRef}
+                    className={`min-w-0 flex-1 bg-transparent py-2.5 text-sm text-neutral-100 outline-none placeholder:text-neutral-500 ${className}`}
+                    {...props}
+                />
+            </span>
+        </label>
+    );
+}

package/recipes/marquee.css

@@ -0,0 +1,22 @@
+/* A starting point for the marquee, yours to edit. The primitive ships no styles;
+   it sets only what the behaviour needs (overflow, touch-action, user-select,
+   will-change, transform) and publishes its state as data-* attributes. */
+
+.enigma-marquee { position: relative; width: 100%; cursor: grab; }
+.enigma-marquee[data-grabbing] { cursor: grabbing; }
+
+/* Fade both ends so items enter and leave instead of being cut. */
+.enigma-marquee.is-faded {
+    -webkit-mask-image: linear-gradient(90deg, transparent, #000 6%, #000 94%, transparent);
+    mask-image: linear-gradient(90deg, transparent, #000 6%, #000 94%, transparent);
+}
+
+/* Never set `transform` or `translate` on the track: the engine owns it, and in
+   Tailwind v4 a translate-* utility composes with it rather than replacing it. */
+.enigma-marquee__track { display: flex; }
+.enigma-marquee__copy { display: flex; flex-shrink: 0; align-items: center; gap: 2.5rem; padding-right: 2.5rem; }
+.enigma-marquee__item { flex-shrink: 0; }
+
+/* State the engine publishes, for you to style. */
+.enigma-marquee[data-hovering] .enigma-marquee__item { opacity: 1; }
+.enigma-marquee[data-reduced-motion="true"] { /* autoplay is off; the drag still works */ }

package/recipes/marquee.css.tsx

@@ -0,0 +1,52 @@
+import "./marquee.css";
+import type { ReactNode, Ref } from "react";
+import { useMarquee } from "@enigmax/primitives/react";
+
+/**
+ * A styled marquee, yours to edit.
+ *
+ * The behaviour comes from the primitive, which ships no styles at all; marquee.css
+ * beside this file is a starting point you are meant to change.
+ */
+export interface MarqueeProps<T> {
+    items: T[];
+    /** Pixels per second. Never a duration - the row would speed up as items are added. */
+    speed?: number;
+    /** Speed multiplier while a mouse rests on the row. 0 pauses it. */
+    hoverScale?: number;
+    reverse?: boolean;
+    /** Fade both ends so items enter and leave instead of being cut. */
+    fade?: boolean;
+    className?: string;
+    children: (item: T, index: number) => ReactNode;
+}
+
+export function Marquee<T>({
+    items,
+    speed = 70,
+    hoverScale = 1,
+    reverse = false,
+    fade = true,
+    className = "",
+    children
+}: MarqueeProps<T>) {
+    const { laneRef, trackRef, copies, dragging } = useMarquee({ speed, hoverScale, reverse });
+
+    return (
+        <div
+            ref={laneRef as Ref<HTMLDivElement>}
+            className={["enigma-marquee", fade ? "is-faded" : "", className].filter(Boolean).join(" ")}
+            data-grabbing={dragging ? "" : undefined}
+        >
+            <div ref={trackRef as Ref<HTMLDivElement>} className="enigma-marquee__track">
+                {Array.from({ length: copies }, (_, copy) => (
+                    <div key={copy} aria-hidden={copy > 0} className="enigma-marquee__copy">
+                        {items.map((item, index) => (
+                            <div key={index} className="enigma-marquee__item">{children(item, index)}</div>
+                        ))}
+                    </div>
+                ))}
+            </div>
+        </div>
+    );
+}

package/recipes/marquee.tailwind.tsx

@@ -0,0 +1,61 @@
+import type { ReactNode, Ref } from "react";
+import { useMarquee } from "@enigmax/primitives/react";
+
+/**
+ * A styled marquee, yours to edit.
+ *
+ * The behaviour comes from the primitive, which ships no styles at all; every class
+ * below is a suggestion you are meant to change.
+ *
+ * TAILWIND v4 WARNING: never put a `translate-*` utility on the track. v4 writes those
+ * to the CSS `translate` property, which COMPOSES with `transform` rather than replacing
+ * it, so the class and the engine's transform add up and the row drifts. Anything you
+ * need to offset goes on the lane or on an inner element, never on the moved one.
+ */
+export interface MarqueeProps<T> {
+    items: T[];
+    /** Pixels per second. Never a duration - the row would speed up as items are added. */
+    speed?: number;
+    /** Speed multiplier while a mouse rests on the row. 0 pauses it. */
+    hoverScale?: number;
+    reverse?: boolean;
+    /** Fade both ends so items enter and leave instead of being cut. */
+    fade?: boolean;
+    className?: string;
+    children: (item: T, index: number) => ReactNode;
+}
+
+export function Marquee<T>({
+    items,
+    speed = 70,
+    hoverScale = 1,
+    reverse = false,
+    fade = true,
+    className = "",
+    children
+}: MarqueeProps<T>) {
+    const { laneRef, trackRef, copies, dragging } = useMarquee({ speed, hoverScale, reverse });
+
+    return (
+        <div
+            ref={laneRef as Ref<HTMLDivElement>}
+            className={[
+                "relative w-full",
+                dragging ? "cursor-grabbing" : "cursor-grab",
+                fade ? "[mask-image:linear-gradient(90deg,transparent,#000_6%,#000_94%,transparent)]" : "",
+                className
+            ].filter(Boolean).join(" ")}
+        >
+            {/* No translate-* utility here. See the note at the top of this file. */}
+            <div ref={trackRef as Ref<HTMLDivElement>} className="flex">
+                {Array.from({ length: copies }, (_, copy) => (
+                    <div key={copy} aria-hidden={copy > 0} className="flex shrink-0 items-center gap-10 pr-10">
+                        {items.map((item, index) => (
+                            <div key={index} className="shrink-0">{children(item, index)}</div>
+                        ))}
+                    </div>
+                ))}
+            </div>
+        </div>
+    );
+}

package/recipes/search.tailwind.tsx

@@ -0,0 +1,73 @@
+import Fuse from "fuse.js";
+import type { ReactNode } from "react";
+import { useSearch } from "@enigmax/primitives/react";
+
+/**
+ * A styled search field with its result list, yours to edit.
+ *
+ * Debouncing, ranking, cancellation and the Escape-to-clear all come from the primitive.
+ * Drop the Fuse import and the `fuse` prop to fall back to the built-in
+ * accent-insensitive substring matcher and no dependency at all.
+ */
+export interface SearchProps<T> {
+    items: T[];
+    /** Fields to search. Dotted paths work: "author.name". */
+    keys: string[];
+    placeholder?: string;
+    /** Fuzzy matching. Omit for the zero-dependency substring matcher. */
+    fuzzy?: boolean;
+    emptyMessage?: string;
+    children: (item: T, score: number) => ReactNode;
+}
+
+export function Search<T>({
+    items,
+    keys,
+    placeholder = "Search",
+    fuzzy = true,
+    emptyMessage = "No matches",
+    children
+}: SearchProps<T>) {
+    const { inputRef, results, query } = useSearch<T>({
+        items,
+        keys,
+        fuse: fuzzy ? (Fuse as never) : undefined,
+        debounce: 120
+    });
+
+    return (
+        <div className="grid gap-2.5">
+            <input
+                ref={inputRef}
+                type="search"
+                aria-label={placeholder}
+                placeholder={placeholder}
+                className="
+                    rounded-lg border border-neutral-700 bg-neutral-900 px-3 py-2.5
+                    text-sm text-neutral-100 outline-none
+                    placeholder:text-neutral-500 focus:border-neutral-400
+                "
+            />
+
+            {query && (
+                <p className="font-mono text-[11px] text-neutral-500">
+                    {results.length} result{results.length === 1 ? "" : "s"} for &quot;{query}&quot;
+                </p>
+            )}
+
+            <ul className="grid list-none gap-1.5 p-0">
+                {results.map((result, index) => (
+                    <li
+                        key={index}
+                        className="rounded-lg border border-neutral-800 bg-neutral-900 px-3 py-2 text-sm text-neutral-100"
+                    >
+                        {children(result.item, result.score)}
+                    </li>
+                ))}
+                {query && results.length === 0 && (
+                    <li className="text-sm text-neutral-500">{emptyMessage}</li>
+                )}
+            </ul>
+        </div>
+    );
+}

package/registry.json

@@ -47,6 +47,32 @@
           "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,
@@ -58,7 +84,11 @@
         "[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",
@@ -104,6 +134,32 @@
           "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,
@@ -115,7 +171,11 @@
         "[data-enigma-input-action]",
         "[data-enigma-input-action=reveal]"
       ],
-      "docs": "docs/notes/primitives.md#input"
+      "docs": "docs/notes/primitives.md#input",
+      "recipes": [
+        "tailwind",
+        "css"
+      ]
     },
     {
       "name": "search",
@@ -161,6 +221,14 @@
           "rewrite": {
             "@/core/search": "./search"
           }
+        },
+        {
+          "path": "recipes/search.tailwind.tsx",
+          "dest": "Search.tsx",
+          "targets": [
+            "react"
+          ],
+          "style": "tailwind"
         }
       ],
       "styles": false,
@@ -170,7 +238,10 @@
       "optionalDependencies": {
         "fuse.js": "Fuzzy matching. Omit it and a built-in substring matcher is used."
       },
-      "docs": "docs/notes/primitives.md#search"
+      "docs": "docs/notes/primitives.md#search",
+      "recipes": [
+        "tailwind"
+      ]
     }
   ]
 }