@haruhimemoe/ui 0.7.0 → 0.8.0

package/dist/components/palette/CommandPalette.js

@@ -0,0 +1,315 @@
+/**
+ * @file src/components/palette/CommandPalette.tsx
+ * @desc The command palette: a native <dialog> opened by mod+k, `openCommandPalette()` or a
+ *       command shortcut, with a combobox over the rows the store and row builder produce.
+ *       Enter runs a command, pushes its page, or starts collecting its args; Escape and
+ *       Backspace on an empty input go back a level, then close. Providers search as you type.
+ *       Recents are read on open and written on every run. The calculator row copies its result.
+ *       Mount once, inside a client component, since commands carry functions.
+ * @author David @dvhsh (https://dvh.sh)
+ * @created Sat Oct 3, 2026
+ * @modified Sat Oct 3, 2026
+ */
+"use client";
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { usePathname, useRouter } from "next/navigation.js";
+import { useCallback, useEffect, useId, useMemo, useReducer, useRef, useState, } from "react";
+import { cx } from "../../utils/cx.js";
+import { useLatestStatus } from "../actions/useLatestStatus.js";
+import { isEditableTarget, matchesCombo, parseShortcut } from "./hotkeys.js";
+import { PaletteFooter } from "./PaletteFooter.js";
+import { PaletteInput } from "./PaletteInput.js";
+import { PaletteList } from "./PaletteList.js";
+import { PALETTE_EVENT } from "./paletteEvents.js";
+import { isMac } from "./platform.js";
+import { boostFrom, readRecents, recentIds, recordRecent } from "./recents.js";
+import { buildRows, CALC_ID, optionAt, optionCount } from "./rows.js";
+import { initialState, reduce, topFrame } from "./store.js";
+import { useProviderSearch } from "./useProviderSearch.js";
+const NONE = [];
+const CHORD_MS = 800;
+const DIALOG = "m-0 h-dvh max-h-none w-full max-w-none bg-transparent p-0 text-c1 backdrop:bg-b6/70 backdrop:backdrop-blur-sm sm:h-auto sm:pt-[12vh]";
+const PANEL = "mx-auto flex h-full max-h-dvh w-full flex-col overflow-hidden border-b3 bg-b6 shadow-2xl sm:h-auto sm:max-h-[70vh] sm:max-w-xl sm:rounded-xl sm:border";
+/**
+ * @function CommandPalette
+ * @param props {CommandPaletteProps} commands, root providers, storage key, hotkey, placeholder,
+ *        label, calculator and recents switches, panel classes
+ * @returns {JSX.Element} the dialog, empty until opened
+ */
+export function CommandPalette({ commands, providers = NONE, storageKey = "default", hotkey = "mod+k", placeholder = "Search commands…", label = "Command palette", calculator = true, recents: recentsOn = true, className, }) {
+    const router = useRouter();
+    const pathname = usePathname() ?? "";
+    const [state, dispatch] = useReducer(reduce, undefined, initialState);
+    const [recents, setRecents] = useState({});
+    const [mac, setMac] = useState(false);
+    const dialog = useRef(null);
+    const input = useRef(null);
+    const opener = useRef(null);
+    const chord = useRef(null);
+    // Where the pointer last was over a row. Chrome fires a pointermove at the same spot after the
+    // list scrolls under a still cursor; only a real move may take the active row from the keys.
+    const pointer = useRef(null);
+    const { status, start, settle } = useLatestStatus();
+    // The copy status reads until the query changes or the palette reopens, then the count again.
+    const [statusShown, setStatusShown] = useState(false);
+    const baseId = useId();
+    const listId = `${baseId}-list`;
+    const optionId = useCallback((index) => `${baseId}-option-${index}`, [baseId]);
+    useEffect(() => setMac(isMac()), []);
+    const root = useMemo(() => ({ title: label, placeholder, commands, providers }), [label, placeholder, commands, providers]);
+    const open = useCallback((page) => {
+        // Opening onto a page while already open keeps the original opener.
+        if (!state.open)
+            opener.current = document.activeElement;
+        if (recentsOn)
+            setRecents(readRecents(storageKey));
+        setStatusShown(false);
+        dispatch({ type: "open", root, page });
+    }, [root, recentsOn, storageKey, state.open]);
+    const close = useCallback(() => dispatch({ type: "close" }), []);
+    const ctx = useMemo(() => ({
+        navigate: (href) => router.push(href),
+        close,
+        push: (page) => (state.open ? dispatch({ type: "push", page }) : open(page)),
+        copy: async (text) => {
+            const run = start();
+            setStatusShown(true);
+            try {
+                await navigator.clipboard.writeText(text);
+                settle(run, "Copied");
+            }
+            catch {
+                settle(run, "Couldn't copy");
+            }
+        },
+        pathname,
+        commands,
+    }), [router, close, state.open, open, start, settle, pathname, commands]);
+    const frame = topFrame(state);
+    const depth = state.stack.length - 1;
+    const isRoot = depth === 0;
+    const query = state.arg ? state.arg.query : (frame?.query ?? "");
+    const rows = useMemo(() => frame
+        ? buildRows({
+            query: frame.query,
+            commands: frame.page.commands ?? [],
+            providers: frame.page.providers ?? NONE,
+            providerResults: frame.providers,
+            recentIds: isRoot && recentsOn ? recentIds(recents) : [],
+            boost: boostFrom(recents),
+            isRoot,
+            calculator,
+            arg: state.arg,
+            ctx,
+        })
+        : [], [frame, isRoot, recentsOn, recents, calculator, state.arg, ctx]);
+    const count = optionCount(rows);
+    const active = state.arg ? state.arg.active : (frame?.active ?? 0);
+    useProviderSearch({
+        providers: frame?.page.providers ?? NONE,
+        query: frame?.query ?? "",
+        depth,
+        dispatch,
+        enabled: state.open && state.arg === null && frame !== undefined,
+    });
+    // The dialog follows `open`: show it modally, focus the input, lock the page's scroll; on
+    // close, hand focus back to whatever had it.
+    useEffect(() => {
+        const element = dialog.current;
+        if (!element)
+            return;
+        if (state.open) {
+            if (!element.open)
+                element.showModal();
+            input.current?.focus();
+            document.documentElement.style.overflow = "hidden";
+            return;
+        }
+        if (element.open)
+            element.close();
+        document.documentElement.style.overflow = "";
+        if (opener.current instanceof HTMLElement)
+            opener.current.focus();
+        opener.current = null;
+    }, [state.open]);
+    useEffect(() => () => {
+        document.documentElement.style.overflow = "";
+    }, []);
+    const remember = (id) => {
+        if (recentsOn && id !== CALC_ID)
+            setRecents(recordRecent(storageKey, id));
+    };
+    const runCommand = (command, args = {}) => {
+        remember(command.id);
+        try {
+            const result = command.run?.(ctx, args);
+            if (result instanceof Promise)
+                result.catch((error) => console.error(`CommandPalette: "${command.id}" failed`, error));
+        }
+        catch (error) {
+            console.error(`CommandPalette: "${command.id}" failed`, error);
+        }
+        if (command.closeOnRun !== false)
+            close();
+    };
+    const acceptArg = (value) => {
+        const arg = state.arg;
+        const spec = arg?.command.args?.[arg.index];
+        if (!arg || !spec)
+            return;
+        const trimmed = value.trim();
+        if (spec.type !== "choice" && trimmed === "")
+            return dispatch({ type: "argError", message: "Required" });
+        if (spec.type === "number" && Number.isNaN(Number(trimmed)))
+            return dispatch({ type: "argError", message: "Enter a number" });
+        const message = spec.validate?.(trimmed);
+        if (message)
+            return dispatch({ type: "argError", message });
+        dispatch({ type: "argAccept", value: trimmed });
+        if (arg.index + 1 >= (arg.command.args?.length ?? 0))
+            runCommand(arg.command, { ...arg.values, [spec.name]: trimmed });
+    };
+    const select = (command) => {
+        if (state.arg)
+            return acceptArg(command.id);
+        if (command.page) {
+            remember(command.id);
+            return dispatch({ type: "push", page: command.page });
+        }
+        if (command.args && command.args.length > 0)
+            return dispatch({ type: "beginArgs", command });
+        runCommand(command);
+    };
+    const fire = (command) => {
+        try {
+            if (command.when && !command.when(ctx))
+                return;
+        }
+        catch {
+            return;
+        }
+        if (command.page)
+            return open(command.page);
+        if (command.args && command.args.length > 0) {
+            open();
+            return dispatch({ type: "beginArgs", command });
+        }
+        runCommand(command);
+    };
+    const back = () => {
+        if (state.arg || depth > 0)
+            dispatch({ type: "pop" });
+        else
+            close();
+    };
+    const onKeyDown = (event) => {
+        const spec = state.arg?.command.args?.[state.arg.index];
+        switch (event.key) {
+            case "ArrowDown":
+            case "ArrowUp":
+                event.preventDefault();
+                return dispatch({ type: "move", delta: event.key === "ArrowDown" ? 1 : -1, count });
+            case "Home":
+            case "End":
+                if (count === 0)
+                    return;
+                event.preventDefault();
+                return dispatch({ type: "move", delta: event.key === "Home" ? "home" : "end", count });
+            case "Enter": {
+                event.preventDefault();
+                if (state.arg && spec && spec.type !== "choice")
+                    return acceptArg(state.arg.query);
+                const option = optionAt(rows, active);
+                return option ? select(option.command) : undefined;
+            }
+            case "Escape":
+                event.preventDefault();
+                return back();
+            case "Backspace":
+                if (query !== "" || (!state.arg && depth === 0))
+                    return;
+                event.preventDefault();
+                return dispatch({ type: "pop" });
+            case "Tab":
+                return event.preventDefault();
+            default:
+                return;
+        }
+    };
+    // Global keys: the opening hotkey anywhere; command shortcuts (combos and chords) only while
+    // closed and outside editable targets.
+    useEffect(() => {
+        const toggle = parseShortcut(hotkey);
+        const shortcuts = commands.flatMap((command) => {
+            const shortcut = command.shortcut ? parseShortcut(command.shortcut) : null;
+            return shortcut ? [{ command, shortcut }] : [];
+        });
+        const onKey = (event) => {
+            if (toggle?.kind === "combo" && matchesCombo(event, toggle.combo, mac)) {
+                event.preventDefault();
+                return state.open ? close() : open();
+            }
+            if (state.open || isEditableTarget(event.target))
+                return;
+            const bare = !event.metaKey && !event.ctrlKey && !event.altKey && event.key.length === 1;
+            const key = event.key.toLowerCase();
+            const pending = chord.current;
+            chord.current = null;
+            for (const { command, shortcut } of shortcuts) {
+                if (shortcut.kind === "combo") {
+                    if (!matchesCombo(event, shortcut.combo, mac))
+                        continue;
+                    event.preventDefault();
+                    return fire(command);
+                }
+                if (!bare)
+                    continue;
+                if (pending &&
+                    pending.key === shortcut.keys[0] &&
+                    key === shortcut.keys[1] &&
+                    Date.now() - pending.at < CHORD_MS) {
+                    event.preventDefault();
+                    return fire(command);
+                }
+            }
+            if (bare &&
+                shortcuts.some((entry) => entry.shortcut.kind === "chord" && entry.shortcut.keys[0] === key)) {
+                chord.current = { key, at: Date.now() };
+            }
+        };
+        window.addEventListener("keydown", onKey);
+        return () => window.removeEventListener("keydown", onKey);
+    });
+    useEffect(() => {
+        const onOpen = (event) => open(event.detail?.page);
+        window.addEventListener(PALETTE_EVENT, onOpen);
+        return () => window.removeEventListener(PALETTE_EVENT, onOpen);
+    }, [open]);
+    const argSpec = state.arg?.command.args?.[state.arg.index];
+    const crumbs = state.arg
+        ? [
+            state.arg.command.title,
+            ...(state.arg.command.args ?? [])
+                .slice(0, state.arg.index)
+                .map((a) => state.arg?.values[a.name] ?? ""),
+        ]
+        : state.stack.slice(1).map((f) => f.page.title);
+    return (_jsx("dialog", { ref: dialog, "data-palette": "", "aria-label": label, className: DIALOG, onCancel: (event) => {
+            event.preventDefault();
+            back();
+        }, onKeyDown: onKeyDown, 
+        // The browser can close the dialog itself (a back gesture, a close watcher): follow it.
+        onClose: close, onClick: (event) => {
+            if (event.target === event.currentTarget)
+                close();
+        }, children: state.open && frame ? (_jsxs("div", { className: cx(PANEL, className), children: [_jsx(PaletteInput, { ref: input, value: query, placeholder: argSpec ? argSpec.label : (frame.page.placeholder ?? "Search…"), label: label, crumbs: crumbs, listId: listId, activeId: count > 0 ? optionId(active) : undefined, error: state.arg?.error, onChange: (value) => {
+                        setStatusShown(false);
+                        dispatch({ type: "query", value });
+                    } }), _jsx(PaletteList, { id: listId, rows: rows, active: active, mac: mac, optionId: optionId, busy: Object.values(frame.providers).some((result) => result.state === "loading"), onActivate: (index, x, y) => {
+                        const last = pointer.current;
+                        if (last && last.x === x && last.y === y)
+                            return;
+                        pointer.current = { x, y };
+                        dispatch({ type: "active", index, count });
+                    }, onSelect: select }), _jsx(PaletteFooter, { count: count, nested: depth > 0 || state.arg !== null, status: statusShown ? (status?.result ?? null) : null, statusRun: statusShown ? (status?.run ?? null) : null })] })) : null }));
+}

package/dist/components/palette/CommandPaletteButton.d.ts

@@ -0,0 +1,21 @@
+/**
+ * @file src/components/palette/CommandPaletteButton.tsx
+ * @desc A header button that opens the mounted CommandPalette: a magnifier, optional text, and
+ *       the hotkey hint ("Ctrl K", or "⌘K" once a Mac is detected after mount). Goes anywhere;
+ *       it only dispatches the palette event.
+ * @author David @dvhsh (https://dvh.sh)
+ * @created Sat Oct 3, 2026
+ * @modified Sat Oct 3, 2026
+ */
+import { type ButtonProps } from "../basics/Button.js";
+/** Every Button prop except onClick, plus the accessible name. */
+export type CommandPaletteButtonProps = Omit<ButtonProps, "onClick"> & {
+    /** The accessible name. Default "Open command palette". */
+    label?: string | undefined;
+};
+/**
+ * @function CommandPaletteButton
+ * @param props {CommandPaletteButtonProps} label, children (text beside the icon) and Button props
+ * @returns {JSX.Element} a ghost Button
+ */
+export declare function CommandPaletteButton({ label, children, variant, ...props }: CommandPaletteButtonProps): import("react").JSX.Element;

package/dist/components/palette/CommandPaletteButton.js

@@ -0,0 +1,26 @@
+/**
+ * @file src/components/palette/CommandPaletteButton.tsx
+ * @desc A header button that opens the mounted CommandPalette: a magnifier, optional text, and
+ *       the hotkey hint ("Ctrl K", or "⌘K" once a Mac is detected after mount). Goes anywhere;
+ *       it only dispatches the palette event.
+ * @author David @dvhsh (https://dvh.sh)
+ * @created Sat Oct 3, 2026
+ * @modified Sat Oct 3, 2026
+ */
+"use client";
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { useEffect, useState } from "react";
+import { Button } from "../basics/Button.js";
+import { openCommandPalette } from "./paletteEvents.js";
+import { isMac } from "./platform.js";
+const KBD = "rounded border border-b3 bg-b5 px-1.5 font-sans text-c3 text-xs";
+/**
+ * @function CommandPaletteButton
+ * @param props {CommandPaletteButtonProps} label, children (text beside the icon) and Button props
+ * @returns {JSX.Element} a ghost Button
+ */
+export function CommandPaletteButton({ label = "Open command palette", children, variant = "ghost", ...props }) {
+    const [mac, setMac] = useState(false);
+    useEffect(() => setMac(isMac()), []);
+    return (_jsxs(Button, { type: "button", variant: variant, "aria-label": children === undefined || children === null ? label : undefined, onClick: () => openCommandPalette(), ...props, children: [_jsxs("svg", { "aria-hidden": "true", viewBox: "0 0 20 20", fill: "none", stroke: "currentColor", strokeWidth: "2", className: "size-4", children: [_jsx("circle", { cx: "8.5", cy: "8.5", r: "5.5" }), _jsx("path", { d: "m13 13 4 4", strokeLinecap: "round" })] }), children, _jsx("kbd", { "aria-hidden": "true", className: KBD, children: mac ? "⌘K" : "Ctrl K" })] }));
+}

package/dist/components/palette/PaletteFooter.d.ts

@@ -0,0 +1,21 @@
+/**
+ * @file src/components/palette/PaletteFooter.tsx
+ * @desc The palette's bottom line (internal): the live region that announces the result count
+ *       or the latest copy status, and the key hints (hidden on phones). No hooks, no cx.
+ * @author David @dvhsh (https://dvh.sh)
+ * @created Sat Oct 3, 2026
+ * @modified Sat Oct 3, 2026
+ */
+/** The option count, whether Backspace goes back, and the latest status (keyed by its run). */
+export type PaletteFooterProps = {
+    count: number;
+    nested: boolean;
+    status: string | null;
+    statusRun: number | null;
+};
+/**
+ * @function PaletteFooter
+ * @param props {PaletteFooterProps} count, nested, status and its run
+ * @returns {JSX.Element} the footer with its `<output>` live region
+ */
+export declare function PaletteFooter({ count, nested, status, statusRun }: PaletteFooterProps): import("react").JSX.Element;

package/dist/components/palette/PaletteFooter.js

@@ -0,0 +1,10 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+const KBD = "rounded border border-b3 bg-b5 px-1 font-sans text-c3";
+/**
+ * @function PaletteFooter
+ * @param props {PaletteFooterProps} count, nested, status and its run
+ * @returns {JSX.Element} the footer with its `<output>` live region
+ */
+export function PaletteFooter({ count, nested, status, statusRun }) {
+    return (_jsxs("div", { className: "flex items-center justify-between gap-4 border-b4 border-t px-4 py-2 text-c4 text-xs", children: [_jsx("output", { "aria-live": "polite", className: "truncate", children: statusRun === null ? (`${count} ${count === 1 ? "result" : "results"}`) : (_jsx("span", { children: status }, statusRun)) }), _jsxs("span", { className: "hidden shrink-0 gap-3 sm:flex", children: [_jsxs("span", { children: [_jsx("kbd", { className: KBD, children: "\u2191" }), " ", _jsx("kbd", { className: KBD, children: "\u2193" }), " navigate"] }), _jsxs("span", { children: [_jsx("kbd", { className: KBD, children: "\u21B5" }), " select"] }), nested ? (_jsxs("span", { children: [_jsx("kbd", { className: KBD, children: "\u232B" }), " back"] })) : null, _jsxs("span", { children: [_jsx("kbd", { className: KBD, children: "esc" }), " ", nested ? "back" : "close"] })] })] }));
+}

package/dist/components/palette/PaletteInput.d.ts

@@ -0,0 +1,30 @@
+/**
+ * @file src/components/palette/PaletteInput.tsx
+ * @desc The palette's top line (internal): breadcrumb chips for nested pages or the argument
+ *       being collected, the combobox input, and the validation message under it. The input is
+ *       the dialog's one focusable thing, so its row shows focus: the bottom border turns h1 on
+ *       focus-visible, the cue 0.7.0's fields use. The error line is a status region that is
+ *       always mounted, so a message that appears is announced.
+ * @author David @dvhsh (https://dvh.sh)
+ * @created Sat Oct 3, 2026
+ * @modified Sat Oct 3, 2026
+ */
+import { type Ref } from "react";
+/** The input's state and ids. */
+export type PaletteInputProps = {
+    ref: Ref<HTMLInputElement>;
+    value: string;
+    placeholder: string;
+    label: string;
+    crumbs: readonly string[];
+    listId: string;
+    activeId: string | undefined;
+    error: string | undefined;
+    onChange: (value: string) => void;
+};
+/**
+ * @function PaletteInput
+ * @param props {PaletteInputProps} value, placeholder, name, crumbs, list and active ids, error
+ * @returns {JSX.Element} the crumbs, the combobox and its error line
+ */
+export declare function PaletteInput({ ref, value, placeholder, label, crumbs, listId, activeId, error, onChange, }: PaletteInputProps): import("react").JSX.Element;

package/dist/components/palette/PaletteInput.js

@@ -0,0 +1,23 @@
+/**
+ * @file src/components/palette/PaletteInput.tsx
+ * @desc The palette's top line (internal): breadcrumb chips for nested pages or the argument
+ *       being collected, the combobox input, and the validation message under it. The input is
+ *       the dialog's one focusable thing, so its row shows focus: the bottom border turns h1 on
+ *       focus-visible, the cue 0.7.0's fields use. The error line is a status region that is
+ *       always mounted, so a message that appears is announced.
+ * @author David @dvhsh (https://dvh.sh)
+ * @created Sat Oct 3, 2026
+ * @modified Sat Oct 3, 2026
+ */
+"use client";
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { useId } from "react";
+/**
+ * @function PaletteInput
+ * @param props {PaletteInputProps} value, placeholder, name, crumbs, list and active ids, error
+ * @returns {JSX.Element} the crumbs, the combobox and its error line
+ */
+export function PaletteInput({ ref, value, placeholder, label, crumbs, listId, activeId, error, onChange, }) {
+    const errorId = `${useId()}-error`;
+    return (_jsxs("div", { className: "border-b4 border-b has-[input:focus-visible]:border-h1", children: [_jsxs("div", { className: "flex items-center gap-2 px-4 py-3", children: [crumbs.map((crumb, index) => (_jsx("span", { className: "shrink-0 rounded bg-b4 px-2 py-0.5 text-c3 text-xs", children: crumb }, index))), _jsx("input", { ref: ref, type: "text", role: "combobox", "aria-expanded": "true", "aria-controls": listId, "aria-activedescendant": activeId, "aria-autocomplete": "list", "aria-label": label, "aria-invalid": error ? true : undefined, "aria-describedby": errorId, autoComplete: "off", spellCheck: false, value: value, placeholder: placeholder, onChange: (event) => onChange(event.target.value), className: "min-w-0 flex-1 bg-transparent text-base text-c1 outline-hidden placeholder:text-c4 sm:text-lg" })] }), _jsx("p", { id: errorId, role: "status", className: error ? "px-4 pb-2 text-rose-300 text-xs" : "sr-only", children: error })] }));
+}

package/dist/components/palette/PaletteList.d.ts

@@ -0,0 +1,29 @@
+/**
+ * @file src/components/palette/PaletteList.tsx
+ * @desc The palette's listbox (internal): option rows under group headings, hint rows as plain
+ *       text, the active row scrolled into view. Hover makes a row active; click selects it.
+ * @author David @dvhsh (https://dvh.sh)
+ * @created Sat Oct 3, 2026
+ * @modified Sat Oct 3, 2026
+ */
+import type { Row } from "./rows.js";
+import type { Command } from "./types.js";
+/** The rows, which option is active, how to id an option, and the handlers. */
+export type PaletteListProps = {
+    id: string;
+    rows: readonly Row[];
+    active: number;
+    mac: boolean;
+    optionId: (index: number) => string;
+    /** A provider is searching: the listbox is aria-busy. */
+    busy?: boolean | undefined;
+    /** The pointer is over a row, at this position. */
+    onActivate: (index: number, x: number, y: number) => void;
+    onSelect: (command: Command) => void;
+};
+/**
+ * @function PaletteList
+ * @param props {PaletteListProps} rows, the active index, option ids and handlers
+ * @returns {JSX.Element} the `role="listbox"`
+ */
+export declare function PaletteList({ id, rows, active, mac, optionId, busy, onActivate, onSelect, }: PaletteListProps): import("react").JSX.Element;

package/dist/components/palette/PaletteList.js

@@ -0,0 +1,44 @@
+/**
+ * @file src/components/palette/PaletteList.tsx
+ * @desc The palette's listbox (internal): option rows under group headings, hint rows as plain
+ *       text, the active row scrolled into view. Hover makes a row active; click selects it.
+ * @author David @dvhsh (https://dvh.sh)
+ * @created Sat Oct 3, 2026
+ * @modified Sat Oct 3, 2026
+ */
+"use client";
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { useEffect } from "react";
+import { PaletteRow } from "./PaletteRow.js";
+const segments = (rows) => {
+    const out = [];
+    let index = 0;
+    for (const row of rows) {
+        if (row.kind === "hint") {
+            out.push({ kind: "hint", row });
+            continue;
+        }
+        const last = out[out.length - 1];
+        const item = { row, index: index++ };
+        if (last?.kind === "group" && last.group === row.group)
+            last.items.push(item);
+        else
+            out.push({ kind: "group", group: row.group, items: [item] });
+    }
+    return out;
+};
+/**
+ * @function PaletteList
+ * @param props {PaletteListProps} rows, the active index, option ids and handlers
+ * @returns {JSX.Element} the `role="listbox"`
+ */
+export function PaletteList({ id, rows, active, mac, optionId, busy, onActivate, onSelect, }) {
+    // Runs for a new list too (its first row changes), so it scrolls back up when active stays 0.
+    const first = rows[0]?.id;
+    useEffect(() => {
+        if (first === undefined)
+            return;
+        document.getElementById(optionId(active))?.scrollIntoView?.({ block: "nearest" });
+    }, [active, optionId, first]);
+    return (_jsx("div", { id: id, role: "listbox", "aria-label": "Results", "aria-busy": busy ? true : undefined, className: "min-h-0 flex-1 overflow-y-auto p-2", children: segments(rows).map((segment) => segment.kind === "hint" ? (_jsx("div", { role: "option", "aria-disabled": "true", "aria-selected": "false", className: "px-3 py-2 text-c4 text-sm", children: segment.row.text }, segment.row.id)) : (_jsxs("div", { role: "group", "aria-labelledby": `${id}-${segment.items[0]?.index}-h`, children: [_jsx("div", { id: `${id}-${segment.items[0]?.index}-h`, className: "px-3 pt-3 pb-1 font-bold text-c3 text-xs", children: segment.group }), segment.items.map(({ row, index }) => (_jsx(PaletteRow, { id: optionId(index), command: row.command, ranges: row.ranges, active: index === active, mac: mac, onHover: (x, y) => onActivate(index, x, y), onSelect: () => onSelect(row.command) }, row.id)))] }, `${segment.group}:${segment.items[0]?.row.id}`))) }));
+}

package/dist/components/palette/PaletteRow.d.ts

@@ -0,0 +1,30 @@
+/**
+ * @file src/components/palette/PaletteRow.tsx
+ * @desc One option in the palette's list (internal): icon slot, the title with its matched
+ *       characters marked, the subtitle, and the shortcut as kbd parts. Finished class strings,
+ *       no hooks: the list sets aria-selected and the pointer handlers. Keyboard handling lives
+ *       on the dialog, so this isn't focusable (aria-activedescendant names it).
+ * @author David @dvhsh (https://dvh.sh)
+ * @created Sat Oct 3, 2026
+ * @modified Sat Oct 3, 2026
+ */
+import type { FuzzyMatch } from "./fuzzy.js";
+import type { Command } from "./types.js";
+/** The row's id (for aria-activedescendant), its command and spans, whether it's active. */
+export type PaletteRowProps = {
+    id: string;
+    command: Command;
+    ranges: FuzzyMatch["ranges"];
+    active: boolean;
+    mac: boolean;
+    /** The pointer moved over the row; gets the pointer's position, so a stale move can be told. */
+    onHover: (x: number, y: number) => void;
+    onSelect: () => void;
+};
+/**
+ * @function PaletteRow
+ * @param props {PaletteRowProps} the option's id, command, matched spans, active state, platform
+ *        and pointer handlers
+ * @returns {JSX.Element} a `role="option"` row
+ */
+export declare function PaletteRow({ id, command, ranges, active, mac, onHover, onSelect, }: PaletteRowProps): import("react").JSX.Element;

package/dist/components/palette/PaletteRow.js

@@ -0,0 +1,33 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { displayShortcut, parseShortcut } from "./hotkeys.js";
+// The active row shows its state with an h1 edge, not background alone: bg-b4 on b6 is only
+// 1.5:1. min-h-9 keeps every row a 36px target.
+const ROW = "flex min-h-9 cursor-default items-center gap-3 rounded-lg border-l-2 border-transparent px-3 py-2";
+const ACTIVE = `${ROW} border-h1 bg-b4 forced-colors:border-[Highlight] forced-colors:bg-[Highlight] forced-colors:text-[HighlightText]`;
+const KBD = "rounded border border-b3 bg-b5 px-1.5 font-sans text-c3 text-xs";
+const highlighted = (title, ranges) => {
+    const parts = [];
+    let at = 0;
+    for (const [start, end] of ranges) {
+        if (start > at)
+            parts.push(title.slice(at, start));
+        parts.push(_jsx("mark", { className: "bg-transparent text-h1", children: title.slice(start, end) }, start));
+        at = end;
+    }
+    if (at < title.length)
+        parts.push(title.slice(at));
+    return parts;
+};
+/**
+ * @function PaletteRow
+ * @param props {PaletteRowProps} the option's id, command, matched spans, active state, platform
+ *        and pointer handlers
+ * @returns {JSX.Element} a `role="option"` row
+ */
+export function PaletteRow({ id, command, ranges, active, mac, onHover, onSelect, }) {
+    const shortcut = command.shortcut ? parseShortcut(command.shortcut) : null;
+    return (_jsxs("div", { id: id, role: "option", "aria-selected": active, className: active ? ACTIVE : ROW, onPointerMove: (event) => onHover(event.clientX, event.clientY), 
+        // Keep focus in the input: a click on a row must not blur it, so the next prompt
+        // (an argument, a nested page) can be typed straight away.
+        onPointerDown: (event) => event.preventDefault(), onClick: onSelect, children: [command.icon ? (_jsx("span", { className: "flex size-5 shrink-0 items-center justify-center text-c3", children: command.icon })) : null, _jsxs("span", { className: "flex min-w-0 flex-1 flex-col", children: [_jsx("span", { className: "truncate font-bold text-c1 text-sm", children: highlighted(command.title, ranges) }), command.subtitle ? (_jsx("span", { className: "truncate text-c4 text-xs", children: command.subtitle })) : null] }), shortcut ? (_jsx("span", { className: "flex shrink-0 gap-1", children: displayShortcut(shortcut, mac).map((part, index) => (_jsx("kbd", { className: KBD, children: part }, index))) })) : null] }));
+}

package/dist/components/palette/calc.d.ts

@@ -0,0 +1,28 @@
+/**
+ * @file src/components/palette/calc.ts
+ * @desc The palette's calculator, pure and without eval: a tokenizer and the shunting-yard
+ *       algorithm over + - * / % ^, unary minus, parentheses, k and m number suffixes, pi and e,
+ *       and sqrt, abs, round, floor, ceil, min and max. Anything it can't parse, and any result
+ *       that isn't finite (division by zero), is null.
+ * @author David @dvhsh (https://dvh.sh)
+ * @created Sat Oct 3, 2026
+ * @modified Sat Oct 3, 2026
+ */
+/**
+ * @function evaluate
+ * @param expression {string} what was typed, e.g. "1.5k * (2 + sqrt(9))"
+ * @returns {number | null} the value, or null when it doesn't parse or isn't finite
+ */
+export declare function evaluate(expression: string): number | null;
+/**
+ * @function formatResult
+ * @param value {number} a result
+ * @returns {string} up to 10 significant digits, trailing zeros dropped, "-0" as "0"
+ */
+export declare function formatResult(value: number): string;
+/**
+ * @function isBareNumber
+ * @param expression {string} what was typed
+ * @returns {boolean} true for just a number ("2", " -2.5 "), when the palette shows no "= 2" row
+ */
+export declare const isBareNumber: (expression: string) => boolean;