@enigmax/primitives 0.18.0 → 0.19.0

package/recipes/palette/styles.css

@@ -0,0 +1,243 @@
+/*
+ * The palette's look.
+ *
+ * `SearchPalette` renders the structure, the state and every key it answers to; every
+ * colour, distance and curve is in this file. Nothing below is something the package decided
+ * for you, so editing it is the supported way to make it yours.
+ *
+ * The custom properties at the top are the whole API. Override them on `:root` and you have
+ * a different palette without touching a selector.
+ */
+
+:root {
+    --enigma-palette-width: 34rem;
+    --enigma-palette-radius: 0.85rem;
+    --enigma-palette-top: 12vh;
+
+    --enigma-palette-bg: #101010;
+    --enigma-palette-border: #2a2a2a;
+    --enigma-palette-text: #f5f5f5;
+    --enigma-palette-muted: #a3a3a3;
+    --enigma-palette-active: #1c1c1c;
+    --enigma-palette-accent: #e0a458;
+    --enigma-palette-shadow: 0 20px 60px rgb(0 0 0 / 55%);
+    --enigma-palette-scrim: rgb(0 0 0 / 55%);
+    --enigma-palette-enter: 160ms;
+    --enigma-palette-exit: 140ms;
+}
+
+@media (prefers-color-scheme: light) {
+    :root {
+        --enigma-palette-bg: #ffffff;
+        --enigma-palette-border: #e5e5e5;
+        --enigma-palette-text: #171717;
+        --enigma-palette-muted: #737373;
+        --enigma-palette-active: #f5f5f5;
+        --enigma-palette-shadow: 0 20px 60px rgb(0 0 0 / 18%);
+        --enigma-palette-scrim: rgb(0 0 0 / 25%);
+    }
+}
+
+/* -------- the trigger -------- */
+
+[data-enigma-palette-trigger] {
+    display: inline-flex;
+    align-items: center;
+    gap: 0.5rem;
+    min-width: 12rem;
+    padding: 0.45rem 0.6rem;
+    font: inherit;
+    font-size: 0.8125rem;
+    /* Set explicitly: this may be rendered as a button or, through asChild, as something
+       else entirely, and only a button gets `line-height: normal` from the user agent. */
+    line-height: 1.25;
+    color: var(--enigma-palette-muted);
+    background: transparent;
+    border: 1px solid var(--enigma-palette-border);
+    border-radius: 0.6rem;
+    cursor: pointer;
+}
+
+[data-enigma-palette-trigger]:hover { color: var(--enigma-palette-text); }
+[data-enigma-palette-trigger-label] { flex: 1; text-align: left; }
+
+[data-enigma-palette-trigger-key] {
+    font-family: ui-monospace, SFMono-Regular, Menlo, monospace;
+    font-size: 0.6875rem;
+    padding: 0.15rem 0.35rem;
+    border: 1px solid var(--enigma-palette-border);
+    border-radius: 0.3rem;
+}
+
+/* -------- the panel -------- */
+
+[data-enigma-palette-overlay] {
+    position: fixed;
+    inset: 0;
+    z-index: 9998;
+    background: var(--enigma-palette-scrim);
+    /* Behind the panel, and the only thing a click outside can land on. */
+    backdrop-filter: blur(2px);
+    animation: enigma-palette-fade var(--enigma-palette-enter) ease-out;
+}
+
+/* The panel stays in the DOM through its exit (`closeDuration`), which is the only way a
+   component that unmounts on close can animate out at all. */
+[data-enigma-palette-overlay][data-state="closed"] {
+    animation: enigma-palette-fade var(--enigma-palette-exit) ease-in reverse forwards;
+}
+
+[data-enigma-palette-content] {
+    position: fixed;
+    z-index: 9999;
+    top: var(--enigma-palette-top);
+    left: 50%;
+    transform: translateX(-50%);
+    display: flex;
+    flex-direction: column;
+    width: min(var(--enigma-palette-width), calc(100vw - 2rem));
+    /* Never taller than the room it has: the list scrolls, the field and the footer stay. */
+    max-height: min(70vh, 32rem);
+    overflow: hidden;
+    color: var(--enigma-palette-text);
+    background: var(--enigma-palette-bg);
+    border: 1px solid var(--enigma-palette-border);
+    border-radius: var(--enigma-palette-radius);
+    box-shadow: var(--enigma-palette-shadow);
+    animation: enigma-palette-in var(--enigma-palette-enter) cubic-bezier(0.16, 1, 0.3, 1);
+}
+
+[data-enigma-palette-content][data-state="closed"] {
+    animation: enigma-palette-in var(--enigma-palette-exit) ease-in reverse forwards;
+}
+
+@keyframes enigma-palette-fade {
+    from { opacity: 0; }
+    to { opacity: 1; }
+}
+
+/* Down and in: the panel arrives rather than appearing whole. */
+@keyframes enigma-palette-in {
+    from { opacity: 0; transform: translateX(-50%) translateY(-8px) scale(0.98); }
+    to { opacity: 1; transform: translateX(-50%) translateY(0) scale(1); }
+}
+
+/* Reduced motion keeps the fade and drops the movement: the panel still has to announce
+   itself as new, and a hard cut in the middle of the screen is its own kind of jolt. */
+@media (prefers-reduced-motion: reduce) {
+    [data-enigma-palette-content],
+    [data-enigma-palette-content][data-state="closed"] {
+        animation-name: enigma-palette-fade;
+        animation-duration: 90ms;
+    }
+}
+
+/* The dialog needs a name; nobody needs to see it. */
+[data-enigma-palette-title] {
+    position: absolute;
+    width: 1px;
+    height: 1px;
+    margin: -1px;
+    padding: 0;
+    overflow: hidden;
+    clip-path: inset(50%);
+    white-space: nowrap;
+}
+
+[data-enigma-palette-field] {
+    display: block;
+    width: 100%;
+    padding: 0.95rem 1.1rem;
+    font: inherit;
+    font-size: 0.95rem;
+    /* Both set explicitly. A field inherits nothing useful from a dialog - a page that
+       styles `input` at all (a reset, a framework, the site's own form CSS) otherwise
+       reaches in and leaves the palette with a field that does not match its own panel. */
+    color: var(--enigma-palette-text);
+    background: var(--enigma-palette-bg);
+    border: 0;
+    border-bottom: 1px solid var(--enigma-palette-border);
+    border-radius: 0;
+    outline: none;
+    box-shadow: none;
+}
+
+[data-enigma-palette-field]::placeholder { color: var(--enigma-palette-muted); }
+/* The platform's own clear button would sit next to a list that already answers to Escape. */
+[data-enigma-palette-field]::-webkit-search-cancel-button { display: none; }
+
+[data-enigma-palette-list] {
+    flex: 1;
+    overflow-y: auto;
+    /* A scroll that reaches the end stays in the panel instead of moving the page under it. */
+    overscroll-behavior: contain;
+    padding: 0.4rem;
+}
+
+[data-enigma-palette-group-label] {
+    margin: 0.4rem 0.6rem 0.25rem;
+    font-size: 0.6875rem;
+    font-weight: 600;
+    letter-spacing: 0.04em;
+    text-transform: uppercase;
+    color: var(--enigma-palette-muted);
+}
+
+[data-enigma-palette-item] {
+    display: flex;
+    align-items: center;
+    gap: 0.6rem;
+    padding: 0.55rem 0.6rem;
+    border-radius: 0.5rem;
+    cursor: pointer;
+}
+
+/* One highlight, whether it was the keyboard or the pointer that moved it. */
+[data-enigma-palette-item][data-active="true"] { background: var(--enigma-palette-active); }
+[data-enigma-palette-item][data-kind="recent"] [data-enigma-palette-item-label]::before {
+    content: "";
+    display: inline-block;
+    width: 0.35rem;
+    height: 0.35rem;
+    margin-right: 0.5rem;
+    vertical-align: 0.1rem;
+    border-radius: 999px;
+    background: var(--enigma-palette-accent);
+}
+
+[data-enigma-palette-item-label] { flex: 1; min-width: 0; }
+[data-enigma-palette-item-description] { color: var(--enigma-palette-muted); font-size: 0.8125rem; }
+
+[data-enigma-palette-empty] {
+    margin: 0;
+    padding: 2.5rem 1rem;
+    text-align: center;
+    color: var(--enigma-palette-muted);
+    font-size: 0.875rem;
+}
+
+[data-enigma-palette-footer] {
+    display: flex;
+    gap: 1rem;
+    padding: 0.55rem 0.9rem;
+    font-size: 0.75rem;
+    color: var(--enigma-palette-muted);
+    border-top: 1px solid var(--enigma-palette-border);
+}
+
+[data-enigma-palette-hint] kbd {
+    font-family: ui-monospace, SFMono-Regular, Menlo, monospace;
+    font-size: 0.6875rem;
+    padding: 0.1rem 0.3rem;
+    margin-right: 0.2rem;
+    border: 1px solid var(--enigma-palette-border);
+    border-radius: 0.25rem;
+}
+
+/* A phone has no Escape key and less room: the panel takes the top of the screen. */
+@media (max-width: 640px) {
+    [data-enigma-palette-content] {
+        top: 0.75rem;
+        max-height: calc(100vh - 1.5rem);
+    }
+}

package/registry.json

@@ -515,6 +515,14 @@
             "react"
           ]
         },
+        {
+          "path": "recipes/palette/styles.css",
+          "dest": "palette/styles.css",
+          "targets": [
+            "react"
+          ],
+          "style": "css"
+        },
         {
           "path": "src/react/palette/context.ts",
           "dest": "palette/context.ts",
@@ -572,7 +580,10 @@
         "[data-enigma-palette-footer]",
         "[data-enigma-palette-hint]"
       ],
-      "docs": "docs/notes/primitives.md#palette"
+      "docs": "docs/notes/primitives.md#palette",
+      "recipes": [
+        "css"
+      ]
     },
     {
       "name": "flags",

package/src/core/search.ts

@@ -106,6 +106,61 @@ function substringMatcher<T>(query: string, items: readonly T[], keys: string[])
     return results.sort((left, right) => left.score - right.score);
 }
 
+/**
+ * Subsequence ranking: every letter of the query, in order, anywhere in the text.
+ *
+ * This is what a COMMAND palette wants and a substring filter cannot do: "qgate" finds
+ * "Quality gate" and "plyg" finds "Playground", because the letters only have to appear in
+ * order. The score rewards consecutive runs and word starts and penalises gaps, so the
+ * closest thing to what was typed comes first rather than the first thing that happened to
+ * contain the letters.
+ *
+ * Pass it as `matcher`, or take it as the default from the palette. The substring matcher
+ * stays the default for a plain search FIELD, where a typo should fail rather than quietly
+ * match something four words away.
+ */
+export function subsequenceMatcher<T>(keys: string[] = []): NonNullable<SearchOptions<T>["matcher"]> {
+    return (query, items) => {
+        const needle = fold(query);
+        const results: SearchMatch<T>[] = [];
+
+        for (const item of items) {
+            const fields = keys.length ? keys : [""];
+            let best: SearchMatch<T> | null = null;
+
+            for (const key of fields) {
+                const haystack = fold(key ? readPath(item, key) : String(item));
+                const score = subsequenceScore(needle, haystack);
+                if (score < 0) continue;
+                // The engine orders by ASCENDING score (Fuse's convention, 0 is exact), and
+                // this one counts upwards, so it is negated rather than compared backwards -
+                // getting that wrong ranks the worst match first and looks like a broken
+                // search rather than a sign error.
+                const ranked = -score;
+                if (!best || ranked < best.score) best = { item, score: ranked, key: key || undefined };
+            }
+            if (best) results.push(best);
+        }
+
+        return results.sort((left, right) => left.score - right.score);
+    };
+}
+
+/** -1 when the query is not a subsequence of the text; otherwise higher is better. */
+function subsequenceScore(query: string, text: string): number {
+    if (!query) return 0;
+    let from = 0, score = 0, run = 0;
+    for (let i = 0; i < query.length; i++) {
+        const at = text.indexOf(query[i], from);
+        if (at === -1) return -1;
+        run = i > 0 && at === from ? run + 1 : 0;
+        const wordStart = at === 0 || /[^a-z0-9]/.test(text[at - 1]);
+        score += 10 + run * 6 + (wordStart ? 8 : 0) - Math.min(at - from, 6);
+        from = at + 1;
+    }
+    return score;
+}
+
 export function createSearch<T>(options: SearchOptions<T> = {}): SearchInstance<T> {
     let opts: SearchOptions<T> = { ...options };
     let items: readonly T[] = opts.items ?? [];
@@ -205,6 +260,11 @@ export function createSearch<T>(options: SearchOptions<T> = {}): SearchInstance<
             input.addEventListener("input", onInput);
             input.addEventListener("keydown", onKeyDown);
             input.dataset.enigmaSearch = "";
+            // A field can already hold a value when the engine reaches it: a query restored
+            // from the URL, a browser refill, or simply someone typing before the module
+            // that searches finished loading. Binding without reading it leaves the field
+            // full and the list empty until the NEXT keystroke, which reads as broken.
+            if (input.value) this.searchNow(input.value);
             return () => {
                 input.removeEventListener("input", onInput);
                 input.removeEventListener("keydown", onKeyDown);

package/src/index.ts

@@ -1,6 +1,6 @@
 export { createMarquee, type MarqueeOptions, type MarqueeInstance, type MarqueeHover } from "@/core/marquee";
 export { createInput, type InputOptions, type InputInstance, type InputAction, type InputIcon, type InputActionState } from "@/core/input";
-export { createSearch, type SearchOptions, type SearchInstance, type SearchMatch, type FuseConstructor, type FuseLike } from "@/core/search";
+export { createSearch, subsequenceMatcher, type SearchOptions, type SearchInstance, type SearchMatch, type FuseConstructor, type FuseLike } from "@/core/search";
 export { createButton, type ButtonOptions, type ButtonInstance, type ButtonState, type ButtonElement, type ButtonCooldown } from "@/core/button";
 export { INPUT_ICON_PATHS, iconMarkup } from "@/core/input";
 export {
@@ -45,3 +45,19 @@ export {
     type FlagFormat,
     type FlagSource
 } from "@/core/flags";
+// The palette's non-rendering half: no framework anywhere near it, so a vanilla or Astro
+// page can run the same keyboard arithmetic, grouping and history the React palette does.
+export {
+    createRecentStore,
+    recentKey,
+    groupRows,
+    moveActive,
+    shortcutLabel,
+    isPaletteShortcut,
+    type RecentEntry,
+    type RecentStore,
+    type RecentStoreOptions,
+    type RowGroup,
+    type PositionedRow,
+    type PaletteKey
+} from "@/core/palette";

package/src/react/index.ts

@@ -40,6 +40,16 @@ export { Toaster, type ToasterProps, type ToastPosition, type ToastControls } fr
 export { useNetworkState } from "@/react/use-network-state";
 export { type NetworkState } from "@/core/network";
 export { RelativeTime, type RelativeTimeProps } from "@/react/relative-time";
+// The option types too: a wrapper around any of these has to be able to name its own props.
+export type {
+    RelativeTimeOptions,
+    RelativeTimeFormat,
+    RelativeTimeTense,
+    RelativeTimePrecision,
+    RelativeTimeStyle
+} from "@/core/relative-time";
+export type { NotificationTone, NotificationAction, NotificationInput, Notification, NotificationsOptions } from "@/core/notifications";
+export type { SearchInstance, FuseLike } from "@/core/search";
 export { Flag, type FlagProps } from "@/react/flag";
 export {
     flagSrc,

package/src/react/palette/root.tsx

@@ -3,7 +3,7 @@
 import { Slot } from "@/react/slot";
 import { createPortal } from "react-dom";
 import { PaletteContext, usePaletteContext, type PaletteRow } from "@/react/palette/context";
-import { createSearch, type SearchInstance, type SearchMatch, type SearchOptions } from "@/core/search";
+import { createSearch, subsequenceMatcher, type SearchInstance, type SearchMatch, type SearchOptions } from "@/core/search";
 import { createRecentStore, groupRows, moveActive, shortcutLabel, isPaletteShortcut, type RecentEntry, type PaletteKey } from "@/core/palette";
 import {
     useCallback, useEffect, useId, useMemo, useRef, useState,
@@ -146,12 +146,28 @@ export function PaletteRoot<Item>({
 
     /* -------- the engine -------- */
 
+    /**
+     * A palette ranks by SUBSEQUENCE unless told otherwise: "qgate" has to find "Quality
+     * gate" and "plyg" has to find "Playground", which a substring filter cannot do. A plain
+     * search field keeps the substring matcher, where a typo should fail rather than quietly
+     * match something four words away.
+     *
+     * Computed ONCE and used by both the constructor and the update below. Passing the raw
+     * prop to `update` instead is how the first version lost it: the effect overwrote the
+     * default with `undefined` on the very next render, and the palette silently went back
+     * to substring matching.
+     */
+    const ranking = useMemo(
+        () => matcher ?? (fuse ? undefined : subsequenceMatcher<Item>(keys ?? [])),
+        [matcher, fuse, keys]
+    );
+
     const engine = useMemo<SearchInstance<Item>>(() => createSearch<Item>({
         items,
         keys,
         fuse,
         fuseOptions,
-        matcher,
+        matcher: ranking,
         debounce: delay,
         limit,
         onResults: (next) => {
@@ -165,7 +181,7 @@ export function PaletteRoot<Item>({
 
     useEffect(() => () => engine.destroy(), [engine]);
     useEffect(() => { engine.setItems(items ?? []); }, [engine, items]);
-    useEffect(() => { engine.update({ keys, fuse, fuseOptions, matcher, debounce: delay, limit }); }, [engine, keys, fuse, fuseOptions, matcher, delay, limit]);
+    useEffect(() => { engine.update({ keys, fuse, fuseOptions, matcher: ranking, debounce: delay, limit }); }, [engine, keys, fuse, fuseOptions, ranking, delay, limit]);
 
     /* -------- opening and closing -------- */
 
@@ -349,6 +365,15 @@ export interface PaletteContentProps extends ComponentPropsWithoutRef<"div"> {
     portal?: boolean;
     /** Rendered behind the panel. Pass null for no overlay of ours. */
     overlayProps?: ComponentPropsWithoutRef<"div"> | null;
+    /**
+     * How long the closing animation is given before the panel leaves the DOM, in ms.
+     *
+     * It exists because a component that unmounts on close can only ever animate IN: the
+     * element is gone before a leaving animation has a frame to run. `data-state="closed"`
+     * is set first, the stylesheet animates it, and only then does it unmount. 0 removes it
+     * immediately, which is also what a reader with reduced motion gets.
+     */
+    closeDuration?: number;
 }
 
 /**
@@ -357,15 +382,28 @@ export interface PaletteContentProps extends ComponentPropsWithoutRef<"div"> {
  * Mounted only while open, so nothing of the palette is in the document (or in the tab
  * order) the rest of the time.
  */
-export function PaletteContent({ title = "Search", portal = true, overlayProps, children, ...props }: PaletteContentProps): ReactNode {
+export function PaletteContent({ title = "Search", portal = true, overlayProps, closeDuration = 160, children, ...props }: PaletteContentProps): ReactNode {
     const palette = usePaletteContext("SearchPalette.Content");
     const panelRef = useRef<HTMLDivElement | null>(null);
     const [mounted, setMounted] = useState(false);
+    /** Stays true through the closing animation, so the panel has frames to leave in. */
+    const [present, setPresent] = useState(palette.open);
 
     // A portal has no server render: `document` does not exist there, and rendering the
     // panel into the tree instead would put it in the wrong place for one frame.
     useEffect(() => setMounted(true), []);
 
+    useEffect(() => {
+        if (palette.open) {
+            setPresent(true);
+            return;
+        }
+        if (!present) return;
+        const reduced = typeof window !== "undefined" && window.matchMedia?.("(prefers-reduced-motion: reduce)").matches;
+        const timer = setTimeout(() => setPresent(false), reduced ? 0 : closeDuration);
+        return () => clearTimeout(timer);
+    }, [palette.open, present, closeDuration]);
+
     useEffect(() => {
         if (!palette.open || typeof document === "undefined") return;
 
@@ -414,14 +452,15 @@ export function PaletteContent({ title = "Search", portal = true, overlayProps,
         };
     }, [palette.open, palette.setOpen, palette.triggerRef]);
 
-    if (!palette.open) return null;
+    if (!present) return null;
 
     const panel = (
-        <div data-enigma-palette-portal="">
+        <div data-enigma-palette-portal="" data-state={palette.open ? "open" : "closed"}>
             {overlayProps !== null && (
                 <div
                     {...overlayProps}
                     data-enigma-palette-overlay=""
+                    data-state={palette.open ? "open" : "closed"}
                     // A click outside is a dismiss, and it is not a keyboard event, so it
                     // never reaches the Escape handler.
                     onClick={(event) => {
@@ -437,6 +476,7 @@ export function PaletteContent({ title = "Search", portal = true, overlayProps,
                 aria-modal="true"
                 aria-labelledby={palette.ids.title}
                 data-enigma-palette-content=""
+                data-state={palette.open ? "open" : "closed"}
             >
                 <h2 id={palette.ids.title} data-enigma-palette-title="">{title}</h2>
                 {children}