@kurajs/ctrlk 0.0.1

package/README.md

@@ -0,0 +1,80 @@
+# @kurajs/ctrlk
+
+A headless, **zero-dependency** ⌘K command palette with a built-in default renderer.
+Vanilla DOM — no React, no Preact, nothing. It mirrors [cmdk](https://cmdk.paco.me)'s
+model and accessibility (dialog + combobox/listbox/option, `aria-activedescendant`,
+full keyboard) so it drops into any stack — including server-rendered sites with no
+client framework — and ships zero runtime bytes beyond itself.
+
+## Batteries-included
+
+```ts
+import { createCtrlk, mountCtrlk } from "@kurajs/ctrlk";
+
+const ctrl = createCtrlk({
+  // Async source: called (debounced, abortable) on every keystroke.
+  search: async (query, signal) => {
+    const res = await fetch(`/search.json?q=${encodeURIComponent(query)}`, { signal });
+    const { hits } = await res.json();
+    return hits.map((h) => ({
+      id: h.slug + "#" + h.headingId,
+      title: h.heading ?? h.title,
+      description: `${h.section} › ${h.title}`, // breadcrumb path
+      excerpt: h.text,
+      group: h.section,
+      icon: h.headingId ? "hash" : "page",
+      href: `/docs/${h.slug}` + (h.headingId ? `#${h.headingId}` : ""),
+    }));
+  },
+});
+
+mountCtrlk(ctrl, {
+  trigger: ".search-box",            // clicking this opens the palette
+  tokensOf: (s) => s.query.split(/\s+/), // or the engine's matched terms, for exact highlight
+});
+// ⌘K / Ctrl+K and "/" now open it; ↑/↓ navigate, Enter opens, Esc closes.
+```
+
+## Static command list
+
+Omit `search` and pass `items` to get cmdk-style local fuzzy filtering:
+
+```ts
+const ctrl = createCtrlk({
+  items: [
+    { id: "new", title: "New file", group: "Actions", keywords: ["create"] },
+    { id: "theme", title: "Toggle theme", group: "Actions" },
+  ],
+  onSelect: (item) => run(item.id),
+});
+mountCtrlk(ctrl);
+```
+
+## Headless
+
+`createCtrlk` is the whole state machine (no DOM): `open/close/toggle`, `setQuery`,
+`move`/`setActive`, `select`, and `subscribe`. Drive your own renderer from `getState()`,
+or render with your framework of choice — `mountCtrlk` is just the default one.
+
+```ts
+const ctrl = createCtrlk({ items });
+const stop = ctrl.subscribe((state) => paint(state)); // { open, query, loading, items, groups, activeIndex, error }
+```
+
+## Theming
+
+The default renderer is styled entirely through `--ctrlk-*` CSS variables (light/dark
+out of the box). Theme it by setting them on `.ctrlk-overlay` — e.g. to inherit a host's
+tokens: `.ctrlk-overlay { --ctrlk-accent: var(--accent); --ctrlk-bg: var(--surface); }`.
+Pass `renderItem` to fully control row markup, or `injectStyles: false` to ship your own.
+
+## API
+
+- `createCtrlk(options) → Ctrlk` — headless controller. Options: `search` | `items` + `filter`,
+  `debounce`, `empty`, `onSelect`.
+- `mountCtrlk(ctrl, opts) → { destroy }` — default DOM. Opts: `trigger`, `hotkey`, `labels`,
+  `tokensOf`, `renderItem`, `injectStyles`, `platform`, `ariaLabel`, `target`.
+- `platformHotkeyLabel()` → `"⌘K"` on macOS, `"Ctrl K"` elsewhere (for a trigger hint).
+- `highlight(text, tokens)` → segments for custom renderers.
+
+Zero dependencies. Runs on Node, Bun, Deno, Cloudflare Workers (core), and every browser.

package/dist/core.d.ts

@@ -0,0 +1,12 @@
+import type { Ctrlk, CtrlkItem, CtrlkOptions } from "./types.ts";
+/**
+ * Default static-mode scorer: case-insensitive match over `title` + `keywords`. A contiguous
+ * substring beats a scattered subsequence, and among substring hits an earlier, shorter match
+ * ranks higher (more specific). Returns 0 for no match. Replace via {@link CtrlkOptions.filter}.
+ */
+export declare function defaultFilter(item: CtrlkItem, query: string): number;
+/**
+ * Create a headless ⌘K controller. Provide `search` for an async source (debounced, abortable)
+ * or `items` + `filter` for a static, locally-filtered command list. Subscribe to drive a UI.
+ */
+export declare function createCtrlk<D = unknown>(options?: CtrlkOptions<D>): Ctrlk<D>;

package/dist/core.js

@@ -0,0 +1,147 @@
+const DEFAULT_DEBOUNCE = 120;
+/**
+ * Default static-mode scorer: case-insensitive match over `title` + `keywords`. A contiguous
+ * substring beats a scattered subsequence, and among substring hits an earlier, shorter match
+ * ranks higher (more specific). Returns 0 for no match. Replace via {@link CtrlkOptions.filter}.
+ */
+export function defaultFilter(item, query) {
+    const q = query.trim().toLowerCase();
+    if (!q)
+        return 1;
+    const hay = (item.title + " " + (item.keywords?.join(" ") ?? "")).toLowerCase();
+    const idx = hay.indexOf(q);
+    if (idx >= 0)
+        return 1000 - idx - hay.length * 0.01; // contiguous substring: strongest signal
+    // Subsequence fallback: every query char appears in order somewhere in the haystack.
+    let at = 0;
+    for (const ch of q) {
+        at = hay.indexOf(ch, at);
+        if (at < 0)
+            return 0;
+        at++;
+    }
+    return 1 - hay.length * 0.001; // weak match, deprioritized vs any substring hit
+}
+/** Bucket items by `group`, preserving first-seen group order; ungrouped items fall under "". */
+function bucket(items) {
+    const order = [];
+    const map = new Map();
+    for (const it of items) {
+        const g = it.group ?? "";
+        let arr = map.get(g);
+        if (!arr) {
+            arr = [];
+            map.set(g, arr);
+            order.push(g);
+        }
+        arr.push(it);
+    }
+    return order.map((label) => ({ label, items: map.get(label) }));
+}
+/**
+ * Create a headless ⌘K controller. Provide `search` for an async source (debounced, abortable)
+ * or `items` + `filter` for a static, locally-filtered command list. Subscribe to drive a UI.
+ */
+export function createCtrlk(options = {}) {
+    const debounceMs = options.debounce ?? DEFAULT_DEBOUNCE;
+    const subs = new Set();
+    let state = { open: false, query: "", loading: false, items: [], groups: [], activeIndex: -1, error: null };
+    let timer = null;
+    let ac = null;
+    let runSeq = 0; // monotonic guard: only the most recent async run may apply its result
+    const emit = () => { const snap = state; for (const fn of [...subs])
+        fn(snap); };
+    const set = (patch) => { state = { ...state, ...patch }; emit(); };
+    const clearTimer = () => { if (timer) {
+        clearTimeout(timer);
+        timer = null;
+    } };
+    const applyItems = (items) => set({ items, groups: bucket(items), activeIndex: items.length ? 0 : -1, loading: false, error: null });
+    const runStatic = (q) => {
+        const src = options.items ?? [];
+        if (!q.trim()) {
+            applyItems((options.empty ?? src).slice());
+            return;
+        }
+        const filter = options.filter ?? defaultFilter;
+        applyItems(src.map((it) => ({ it, s: filter(it, q) }))
+            .filter((x) => x.s > 0)
+            .sort((a, b) => b.s - a.s)
+            .map((x) => x.it));
+    };
+    const runAsync = async (q) => {
+        // Empty query never hits the network — show the configured suggestions (or nothing).
+        if (!q.trim()) {
+            ac?.abort();
+            applyItems((options.empty ?? []).slice());
+            return;
+        }
+        const seq = ++runSeq;
+        ac?.abort();
+        const controller = new AbortController();
+        ac = controller;
+        set({ loading: true });
+        try {
+            const items = await options.search(q, controller.signal);
+            if (seq === runSeq)
+                applyItems(items); // ignore out-of-order/stale resolves
+        }
+        catch (err) {
+            if (seq === runSeq && !controller.signal.aborted)
+                set({ loading: false, error: err });
+        }
+    };
+    const schedule = (q) => {
+        clearTimer();
+        if (!options.search) {
+            runStatic(q);
+            return;
+        } // local filter is cheap — run synchronously
+        if (!q.trim()) {
+            runAsync(q);
+            return;
+        } // empty → suggestions, no need to debounce
+        timer = setTimeout(() => runAsync(q), debounceMs);
+    };
+    const open = () => { if (!state.open) {
+        set({ open: true });
+        schedule(state.query);
+    } };
+    // Closing invalidates any in-flight async run (bump the seq) so a late resolve/reject can't
+    // apply stale results — or set an error — onto a palette the user already dismissed.
+    const close = () => { if (state.open) {
+        clearTimer();
+        runSeq++;
+        ac?.abort();
+        set({ open: false, loading: false });
+    } };
+    return {
+        getState: () => state,
+        subscribe(fn) { subs.add(fn); fn(state); return () => { subs.delete(fn); }; },
+        open,
+        close,
+        toggle() { state.open ? close() : open(); },
+        setQuery(q) { if (q !== state.query) {
+            set({ query: q });
+            schedule(q);
+        } },
+        move(delta) {
+            const n = state.items.length;
+            if (!n)
+                return;
+            const i = state.activeIndex < 0 ? (delta > 0 ? 0 : n - 1) : (state.activeIndex + delta + n) % n;
+            set({ activeIndex: i });
+        },
+        setActive(index) {
+            const n = state.items.length;
+            if (n)
+                set({ activeIndex: Math.max(0, Math.min(n - 1, index)) });
+        },
+        select(item, ev) {
+            const it = item ?? state.items[state.activeIndex];
+            if (it)
+                options.onSelect?.(it, ev);
+        },
+        destroy() { clearTimer(); ac?.abort(); subs.clear(); },
+    };
+}

package/dist/dom.d.ts

@@ -0,0 +1,46 @@
+import type { Ctrlk, CtrlkItem, CtrlkState } from "./types.ts";
+export interface MountLabels {
+    placeholder?: string;
+    /** Shown when a non-empty query returns nothing. */
+    empty?: string;
+    loading?: string;
+    /** Shown when the query is empty and there are no suggestions. */
+    initial?: string;
+    selectHint?: string;
+    openHint?: string;
+    closeHint?: string;
+}
+export interface MountOptions<D = unknown> {
+    /** Where to append the dialog. Default `document.body`. */
+    target?: HTMLElement;
+    /** Open on ⌘K / Ctrl+K and `/`. Default true. A predicate fully customizes the chord. */
+    hotkey?: boolean | ((e: KeyboardEvent) => boolean);
+    /** Element(s) or a selector whose click opens the palette (e.g. the nav search box). */
+    trigger?: Element | Iterable<Element> | string | null;
+    labels?: MountLabels;
+    /** Highlight tokens for the current state (e.g. the search engine's matched terms).
+     *  Default: the query split on whitespace. */
+    tokensOf?: (state: CtrlkState<D>) => string[];
+    /** Override a row's markup. Required ARIA/handlers are still applied to the returned element. */
+    renderItem?: (item: CtrlkItem<D>, ctx: {
+        active: boolean;
+        tokens: string[];
+    }) => HTMLElement;
+    /** Inject the default stylesheet. Default true. */
+    injectStyles?: boolean;
+    /** Force the hotkey-hint platform; default auto-detect from the UA. */
+    platform?: "mac" | "other";
+    /** ARIA label for the dialog. Default "Search". */
+    ariaLabel?: string;
+}
+export interface MountHandle {
+    /** Remove listeners + DOM and tear down the controller subscription. */
+    destroy(): void;
+}
+/** The closed-state hotkey hint to render on a trigger ("⌘K" on macOS, "Ctrl K" elsewhere). */
+export declare function platformHotkeyLabel(platform?: "mac" | "other"): string;
+/**
+ * Mount the default ⌘K UI for a controller. Returns a handle to tear it down. No-op (returns
+ * an inert handle) when there is no document, so it's safe to import in SSR bundles.
+ */
+export declare function mountCtrlk<D = unknown>(ctrl: Ctrlk<D>, opts?: MountOptions<D>): MountHandle;

package/dist/dom.js

@@ -0,0 +1,325 @@
+import { highlight } from "./highlight.js";
+import { injectStyles } from "./styles.js";
+const DEFAULT_LABELS = {
+    placeholder: "Search…",
+    empty: "No results",
+    loading: "Searching…",
+    initial: "Type to search",
+    selectHint: "Select",
+    openHint: "Open",
+    closeHint: "Close",
+};
+const SEARCH_SVG = `<svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"><circle cx="11" cy="11" r="7"/><path d="m21 21-4.3-4.3"/></svg>`;
+const PAGE_SVG = `<svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"><path d="M14 3H7a2 2 0 0 0-2 2v14a2 2 0 0 0 2 2h10a2 2 0 0 0 2-2V8z"/><path d="M14 3v5h5"/></svg>`;
+function detectMac(force) {
+    if (force)
+        return force === "mac";
+    if (typeof navigator === "undefined")
+        return false;
+    const n = `${navigator.platform ?? ""} ${navigator.userAgent ?? ""}`;
+    return /mac|iphone|ipad|ipod/i.test(n);
+}
+/** The closed-state hotkey hint to render on a trigger ("⌘K" on macOS, "Ctrl K" elsewhere). */
+export function platformHotkeyLabel(platform) {
+    return detectMac(platform) ? "⌘K" : "Ctrl K";
+}
+const isTypingTarget = (el) => {
+    const n = el;
+    if (!n)
+        return false;
+    const tag = n.tagName;
+    return tag === "INPUT" || tag === "TEXTAREA" || tag === "SELECT" || n.isContentEditable;
+};
+/**
+ * Mount the default ⌘K UI for a controller. Returns a handle to tear it down. No-op (returns
+ * an inert handle) when there is no document, so it's safe to import in SSR bundles.
+ */
+export function mountCtrlk(ctrl, opts = {}) {
+    if (typeof document === "undefined")
+        return { destroy() { } };
+    const doc = document;
+    const labels = { ...DEFAULT_LABELS, ...opts.labels };
+    const tokensOf = opts.tokensOf ?? ((s) => s.query.toLowerCase().split(/\s+/).filter(Boolean));
+    if (opts.injectStyles !== false)
+        injectStyles(doc);
+    // --- build the static shell once ---
+    const overlay = doc.createElement("div");
+    overlay.className = "ctrlk-overlay";
+    overlay.hidden = true;
+    overlay.setAttribute("role", "presentation");
+    const dialog = doc.createElement("div");
+    dialog.className = "ctrlk-dialog";
+    dialog.setAttribute("role", "dialog");
+    dialog.setAttribute("aria-modal", "true");
+    dialog.setAttribute("aria-label", opts.ariaLabel ?? "Search");
+    const header = doc.createElement("div");
+    header.className = "ctrlk-header";
+    const searchIcon = doc.createElement("span");
+    searchIcon.innerHTML = SEARCH_SVG; // static, trusted markup
+    const input = doc.createElement("input");
+    input.className = "ctrlk-input";
+    input.type = "text";
+    input.placeholder = labels.placeholder;
+    input.setAttribute("role", "combobox");
+    input.setAttribute("aria-autocomplete", "list");
+    input.setAttribute("aria-expanded", "false");
+    input.setAttribute("autocomplete", "off");
+    input.setAttribute("autocapitalize", "off");
+    input.setAttribute("spellcheck", "false");
+    const listId = "ctrlk-list";
+    input.setAttribute("aria-controls", listId);
+    const escKbd = doc.createElement("kbd");
+    escKbd.className = "ctrlk-esc";
+    escKbd.textContent = "ESC";
+    header.append(searchIcon.firstChild, input, escKbd);
+    const list = doc.createElement("div");
+    list.className = "ctrlk-list";
+    list.id = listId;
+    list.setAttribute("role", "listbox");
+    const footer = doc.createElement("div");
+    footer.className = "ctrlk-footer";
+    footer.append(hint(["↑", "↓"], labels.selectHint), hint(["↵"], labels.openHint), spacer(hint(["esc"], labels.closeHint)));
+    dialog.append(header, list, footer);
+    overlay.append(dialog);
+    (opts.target ?? doc.body).append(overlay);
+    function hint(keys, text) {
+        const span = doc.createElement("span");
+        span.className = "ctrlk-hint";
+        for (const k of keys) {
+            const kbd = doc.createElement("kbd");
+            kbd.textContent = k;
+            span.append(kbd);
+        }
+        span.append(doc.createTextNode(text));
+        return span;
+    }
+    function spacer(el) { el.classList.add("ctrlk-spacer"); return el; }
+    // --- rendering ---
+    let optionEls = [];
+    let lastItems = null;
+    let wasOpen = false;
+    let returnFocus = null;
+    function fillHighlighted(el, text, tokens) {
+        el.textContent = "";
+        for (const seg of highlight(text, tokens)) {
+            if (seg.match) {
+                const m = doc.createElement("mark");
+                m.textContent = seg.text;
+                el.append(m);
+            }
+            else
+                el.append(doc.createTextNode(seg.text));
+        }
+    }
+    function defaultRow(item, tokens) {
+        const row = doc.createElement(item.href ? "a" : "div");
+        if (item.href)
+            row.href = item.href;
+        const icon = doc.createElement("span");
+        icon.className = "ctrlk-option-icon";
+        if (item.icon === "hash")
+            icon.textContent = "#";
+        else if (item.icon && item.icon !== "page")
+            icon.textContent = item.icon;
+        else
+            icon.innerHTML = PAGE_SVG; // static, trusted
+        const body = doc.createElement("div");
+        body.className = "ctrlk-option-body";
+        const title = doc.createElement("div");
+        title.className = "ctrlk-option-title";
+        fillHighlighted(title, item.title, tokens);
+        body.append(title);
+        if (item.description) {
+            const path = doc.createElement("div");
+            path.className = "ctrlk-option-path";
+            fillHighlighted(path, item.description, tokens);
+            body.append(path);
+        }
+        if (item.excerpt) {
+            const ex = doc.createElement("div");
+            ex.className = "ctrlk-option-excerpt";
+            fillHighlighted(ex, item.excerpt, tokens);
+            body.append(ex);
+        }
+        row.append(icon, body);
+        return row;
+    }
+    function activate(item, ev) {
+        ctrl.select(item, { metaKey: ev.metaKey, ctrlKey: ev.ctrlKey, shiftKey: ev.shiftKey, altKey: ev.altKey });
+        ctrl.close();
+        if (item.href)
+            location.assign(item.href);
+    }
+    function rebuildList(state) {
+        const tokens = tokensOf(state);
+        list.textContent = "";
+        optionEls = [];
+        if (!state.items.length) {
+            const div = doc.createElement("div");
+            div.className = "ctrlk-state";
+            div.textContent = state.loading ? labels.loading : state.query.trim() ? labels.empty : labels.initial;
+            list.append(div);
+            return;
+        }
+        let flat = 0;
+        for (const group of state.groups) {
+            if (group.label) {
+                const gl = doc.createElement("div");
+                gl.className = "ctrlk-group-label";
+                gl.setAttribute("role", "presentation");
+                gl.textContent = group.label;
+                list.append(gl);
+            }
+            for (const item of group.items) {
+                const index = flat++;
+                const base = opts.renderItem ? opts.renderItem(item, { active: false, tokens }) : defaultRow(item, tokens);
+                base.classList.add("ctrlk-option");
+                base.id = `ctrlk-opt-${index}`;
+                base.setAttribute("role", "option");
+                base.setAttribute("aria-selected", "false");
+                base.dataset.index = String(index);
+                base.addEventListener("click", (e) => {
+                    if (e.metaKey || e.ctrlKey || e.shiftKey || e.altKey)
+                        return; // let the browser open links natively
+                    e.preventDefault();
+                    activate(item, e);
+                });
+                base.addEventListener("mousemove", () => { if (state.activeIndex !== index)
+                    ctrl.setActive(index); });
+                list.append(base);
+                optionEls.push(base);
+            }
+        }
+    }
+    function syncActive(state) {
+        optionEls.forEach((el, i) => el.setAttribute("aria-selected", i === state.activeIndex ? "true" : "false"));
+        const active = optionEls[state.activeIndex];
+        if (active) {
+            input.setAttribute("aria-activedescendant", active.id);
+            active.scrollIntoView({ block: "nearest" });
+        }
+        else
+            input.removeAttribute("aria-activedescendant");
+    }
+    function render(state) {
+        overlay.hidden = !state.open;
+        input.setAttribute("aria-expanded", String(state.open && state.items.length > 0));
+        if (state.open && !wasOpen) {
+            returnFocus = doc.activeElement;
+            doc.documentElement.classList.add("ctrlk-open");
+            if (input.value !== state.query)
+                input.value = state.query;
+            input.focus();
+        }
+        else if (!state.open && wasOpen) {
+            doc.documentElement.classList.remove("ctrlk-open");
+            lastItems = null; // force a fresh list next open
+            if (returnFocus && doc.contains(returnFocus))
+                returnFocus.focus();
+        }
+        wasOpen = state.open;
+        if (!state.open)
+            return;
+        // Keep the input text in sync when the query changed programmatically (not from typing).
+        if (input.value !== state.query)
+            input.value = state.query;
+        if (state.items !== lastItems) {
+            rebuildList(state);
+            lastItems = state.items;
+        }
+        syncActive(state);
+    }
+    // --- wiring ---
+    const unsubscribe = ctrl.subscribe(render);
+    const onInput = () => ctrl.setQuery(input.value);
+    input.addEventListener("input", onInput);
+    const onDialogKeydown = (e) => {
+        switch (e.key) {
+            case "ArrowDown":
+                e.preventDefault();
+                ctrl.move(1);
+                break;
+            case "ArrowUp":
+                e.preventDefault();
+                ctrl.move(-1);
+                break;
+            case "Home":
+                e.preventDefault();
+                ctrl.setActive(0);
+                break;
+            case "End":
+                e.preventDefault();
+                ctrl.setActive(ctrl.getState().items.length - 1);
+                break;
+            case "Enter": {
+                const st = ctrl.getState();
+                const item = st.items[st.activeIndex];
+                if (item) {
+                    e.preventDefault();
+                    activate(item, e);
+                }
+                break;
+            }
+            case "Escape":
+                e.preventDefault();
+                ctrl.close();
+                break;
+            case "Tab":
+                e.preventDefault();
+                break; // trap focus on the input (combobox pattern)
+        }
+    };
+    dialog.addEventListener("keydown", onDialogKeydown);
+    // Close on a click in the backdrop (outside the dialog).
+    const onOverlayMousedown = (e) => { if (e.target === overlay)
+        ctrl.close(); };
+    overlay.addEventListener("mousedown", onOverlayMousedown);
+    // Global hotkey: ⌘K / Ctrl+K toggles; "/" opens when not already typing.
+    const hotkeyEnabled = opts.hotkey ?? true;
+    const onGlobalKeydown = (e) => {
+        if (typeof hotkeyEnabled === "function") {
+            if (hotkeyEnabled(e)) {
+                e.preventDefault();
+                ctrl.toggle();
+            }
+            return;
+        }
+        if (!hotkeyEnabled)
+            return;
+        if ((e.metaKey || e.ctrlKey) && e.key.toLowerCase() === "k") {
+            e.preventDefault();
+            ctrl.toggle();
+            return;
+        }
+        if (e.key === "/" && !ctrl.getState().open && !isTypingTarget(e.target)) {
+            e.preventDefault();
+            ctrl.open();
+        }
+    };
+    doc.addEventListener("keydown", onGlobalKeydown);
+    // Triggers: clicking opens the palette (and never submits a wrapping form).
+    const triggers = [];
+    if (opts.trigger) {
+        const els = typeof opts.trigger === "string"
+            ? Array.from(doc.querySelectorAll(opts.trigger))
+            : opts.trigger instanceof Element ? [opts.trigger] : Array.from(opts.trigger);
+        for (const el of els) {
+            triggers.push(el);
+            el.addEventListener("click", onTriggerClick);
+        }
+    }
+    function onTriggerClick(e) { e.preventDefault(); ctrl.open(); }
+    return {
+        destroy() {
+            unsubscribe();
+            input.removeEventListener("input", onInput);
+            dialog.removeEventListener("keydown", onDialogKeydown);
+            overlay.removeEventListener("mousedown", onOverlayMousedown);
+            doc.removeEventListener("keydown", onGlobalKeydown);
+            for (const el of triggers)
+                el.removeEventListener("click", onTriggerClick);
+            doc.documentElement.classList.remove("ctrlk-open");
+            overlay.remove();
+        },
+    };
+}

package/dist/highlight.d.ts

@@ -0,0 +1,15 @@
+export interface HighlightSegment {
+    text: string;
+    /** True when this segment matched one of the query tokens. */
+    match: boolean;
+}
+/**
+ * Split `text` into consecutive segments, marking the spans that match any `token`
+ * (case-insensitive). Overlapping/adjacent matches are merged. Tokens should be the terms the
+ * search engine actually matched on (e.g. BM25's per-locale tokens) so CJK/accented matches
+ * line up with scoring rather than a naive whitespace re-split.
+ *
+ * Returns a single unmatched segment when there are no tokens or no hits — so a renderer can
+ * always map over the result uniformly.
+ */
+export declare function highlight(text: string, tokens: readonly string[]): HighlightSegment[];

package/dist/highlight.js

@@ -0,0 +1,54 @@
+// Query-term highlighting, as a pure function so it's testable without a DOM and reusable
+// by any renderer. The default DOM renderer turns matched segments into <mark> elements
+// (built via textContent, never innerHTML — so user/content text is never parsed as markup).
+/**
+ * Split `text` into consecutive segments, marking the spans that match any `token`
+ * (case-insensitive). Overlapping/adjacent matches are merged. Tokens should be the terms the
+ * search engine actually matched on (e.g. BM25's per-locale tokens) so CJK/accented matches
+ * line up with scoring rather than a naive whitespace re-split.
+ *
+ * Returns a single unmatched segment when there are no tokens or no hits — so a renderer can
+ * always map over the result uniformly.
+ */
+export function highlight(text, tokens) {
+    const terms = tokens.map((t) => t.toLowerCase()).filter(Boolean);
+    if (!text || terms.length === 0)
+        return [{ text, match: false }];
+    const hay = text.toLowerCase();
+    // Collect every [start, end) match range across all tokens.
+    const ranges = [];
+    for (const term of terms) {
+        let from = 0;
+        for (;;) {
+            const at = hay.indexOf(term, from);
+            if (at < 0)
+                break;
+            ranges.push([at, at + term.length]);
+            from = at + term.length;
+        }
+    }
+    if (ranges.length === 0)
+        return [{ text, match: false }];
+    // Merge overlapping/touching ranges so we never emit empty or nested marks.
+    ranges.sort((a, b) => a[0] - b[0] || a[1] - b[1]);
+    const merged = [];
+    for (const [s, e] of ranges) {
+        const last = merged[merged.length - 1];
+        if (last && s <= last[1])
+            last[1] = Math.max(last[1], e);
+        else
+            merged.push([s, e]);
+    }
+    // Walk the merged ranges, interleaving the unmatched gaps. Slice the ORIGINAL text to keep case.
+    const out = [];
+    let cursor = 0;
+    for (const [s, e] of merged) {
+        if (s > cursor)
+            out.push({ text: text.slice(cursor, s), match: false });
+        out.push({ text: text.slice(s, e), match: true });
+        cursor = e;
+    }
+    if (cursor < text.length)
+        out.push({ text: text.slice(cursor), match: false });
+    return out;
+}

package/dist/index.d.ts

@@ -0,0 +1,7 @@
+export { createCtrlk, defaultFilter } from "./core.ts";
+export { mountCtrlk, platformHotkeyLabel } from "./dom.ts";
+export type { MountHandle, MountLabels, MountOptions } from "./dom.ts";
+export { highlight } from "./highlight.ts";
+export type { HighlightSegment } from "./highlight.ts";
+export { CSS as ctrlkCss, STYLE_ID, injectStyles } from "./styles.ts";
+export type { Ctrlk, CtrlkGroup, CtrlkItem, CtrlkOptions, CtrlkSelectEvent, CtrlkState, } from "./types.ts";

package/dist/index.js

@@ -0,0 +1,7 @@
+// @kurajs/ctrlk — a headless, zero-dependency ⌘K command palette with a built-in default
+// renderer. Use `createCtrlk` for the headless state machine and `mountCtrlk` for the
+// batteries-included DOM, or drive the controller from your own renderer.
+export { createCtrlk, defaultFilter } from "./core.js";
+export { mountCtrlk, platformHotkeyLabel } from "./dom.js";
+export { highlight } from "./highlight.js";
+export { CSS as ctrlkCss, STYLE_ID, injectStyles } from "./styles.js";

package/dist/styles.d.ts

@@ -0,0 +1,4 @@
+export declare const STYLE_ID = "ctrlk-styles";
+export declare const CSS = "\n.ctrlk-overlay {\n  --ctrlk-bg: #fff;\n  --ctrlk-fg: #1a1a1a;\n  --ctrlk-muted: #6b7280;\n  --ctrlk-border: #e5e7eb;\n  --ctrlk-active: #f3f4f6;\n  --ctrlk-accent: #2563eb;\n  --ctrlk-mark: #facc15;\n  --ctrlk-mark-fg: #1a1a1a;\n  --ctrlk-shadow: 0 16px 48px rgba(0,0,0,.18);\n  --ctrlk-radius: 14px;\n  position: fixed; inset: 0; z-index: 9999;\n  display: flex; align-items: flex-start; justify-content: center;\n  padding: 12vh 16px 16px;\n  background: rgba(15,17,21,.45);\n  backdrop-filter: blur(2px);\n}\n.ctrlk-overlay[hidden] { display: none; }\n@media (prefers-color-scheme: dark) {\n  .ctrlk-overlay {\n    --ctrlk-bg: #1c1f26; --ctrlk-fg: #f3f4f6; --ctrlk-muted: #9aa1ad;\n    --ctrlk-border: #2d323c; --ctrlk-active: #272b34; --ctrlk-accent: #6ea8fe;\n    --ctrlk-mark-fg: #1a1a1a; --ctrlk-shadow: 0 16px 48px rgba(0,0,0,.5);\n  }\n}\n.ctrlk-dialog {\n  width: 100%; max-width: 640px; max-height: 76vh;\n  display: flex; flex-direction: column; overflow: hidden;\n  background: var(--ctrlk-bg); color: var(--ctrlk-fg);\n  border: 1px solid var(--ctrlk-border); border-radius: var(--ctrlk-radius);\n  box-shadow: var(--ctrlk-shadow);\n  animation: ctrlk-in .12s ease-out;\n}\n@keyframes ctrlk-in { from { opacity: 0; transform: translateY(-6px) scale(.99); } to { opacity: 1; transform: none; } }\n@media (prefers-reduced-motion: reduce) { .ctrlk-dialog { animation: none; } }\n\n.ctrlk-header { display: flex; align-items: center; gap: 10px; padding: 14px 16px; border-bottom: 1px solid var(--ctrlk-border); }\n.ctrlk-header svg { width: 18px; height: 18px; flex: none; color: var(--ctrlk-muted); }\n.ctrlk-input {\n  flex: 1; min-width: 0; border: 0; outline: 0; background: transparent;\n  font: inherit; font-size: 1rem; color: var(--ctrlk-fg);\n}\n.ctrlk-input::placeholder { color: var(--ctrlk-muted); }\n.ctrlk-esc {\n  flex: none; font-size: .7rem; line-height: 1; padding: 4px 7px; color: var(--ctrlk-muted);\n  border: 1px solid var(--ctrlk-border); border-radius: 6px; background: var(--ctrlk-active);\n}\n\n.ctrlk-list { overflow-y: auto; overscroll-behavior: contain; padding: 6px; flex: 1; }\n.ctrlk-group-label {\n  padding: 12px 10px 6px; font-size: .72rem; font-weight: 600; letter-spacing: .04em;\n  text-transform: uppercase; color: var(--ctrlk-muted);\n}\n.ctrlk-option {\n  display: flex; gap: 11px; align-items: flex-start; padding: 9px 10px; border-radius: 9px;\n  cursor: pointer; color: inherit; text-decoration: none; scroll-margin: 8px;\n}\n.ctrlk-option[aria-selected=\"true\"] { background: var(--ctrlk-active); }\n.ctrlk-option-icon { flex: none; width: 18px; height: 18px; margin-top: 2px; color: var(--ctrlk-muted); display: flex; align-items: center; justify-content: center; font-size: .95rem; }\n.ctrlk-option-body { min-width: 0; flex: 1; }\n.ctrlk-option-title { font-size: .92rem; font-weight: 500; color: var(--ctrlk-fg); overflow: hidden; text-overflow: ellipsis; white-space: nowrap; }\n.ctrlk-option-path { font-size: .76rem; color: var(--ctrlk-muted); overflow: hidden; text-overflow: ellipsis; white-space: nowrap; }\n.ctrlk-option-excerpt { font-size: .8rem; color: var(--ctrlk-muted); margin-top: 2px; display: -webkit-box; -webkit-line-clamp: 2; -webkit-box-orient: vertical; overflow: hidden; }\n.ctrlk-option mark { background: var(--ctrlk-mark); color: var(--ctrlk-mark-fg); border-radius: 2px; padding: 0 1px; }\n\n.ctrlk-state { padding: 36px 16px; text-align: center; color: var(--ctrlk-muted); font-size: .9rem; }\n\n.ctrlk-footer {\n  display: flex; gap: 16px; align-items: center; padding: 9px 14px;\n  border-top: 1px solid var(--ctrlk-border); color: var(--ctrlk-muted); font-size: .76rem;\n}\n.ctrlk-footer .ctrlk-hint { display: inline-flex; gap: 5px; align-items: center; }\n.ctrlk-footer kbd {\n  font: inherit; font-size: .72rem; min-width: 18px; height: 18px; padding: 0 4px;\n  display: inline-flex; align-items: center; justify-content: center;\n  border: 1px solid var(--ctrlk-border); border-radius: 5px; background: var(--ctrlk-active);\n}\n.ctrlk-footer .ctrlk-spacer { margin-left: auto; }\n\nhtml.ctrlk-open, body.ctrlk-open { overflow: hidden !important; }\n";
+/** Inject the default stylesheet once (no-op on the server or if already present). */
+export declare function injectStyles(doc?: Document): void;

package/dist/styles.js

@@ -0,0 +1,98 @@
+// Default renderer styles, as a string injected once into a <style id="ctrlk-styles">.
+// Self-contained: everything is driven by `--ctrlk-*` custom properties with sensible
+// light/dark defaults, so a host (e.g. Kura docs) can theme it by setting those vars —
+// `.ctrlk-overlay { --ctrlk-accent: var(--accent); }` — without touching this sheet.
+export const STYLE_ID = "ctrlk-styles";
+export const CSS = `
+.ctrlk-overlay {
+  --ctrlk-bg: #fff;
+  --ctrlk-fg: #1a1a1a;
+  --ctrlk-muted: #6b7280;
+  --ctrlk-border: #e5e7eb;
+  --ctrlk-active: #f3f4f6;
+  --ctrlk-accent: #2563eb;
+  --ctrlk-mark: #facc15;
+  --ctrlk-mark-fg: #1a1a1a;
+  --ctrlk-shadow: 0 16px 48px rgba(0,0,0,.18);
+  --ctrlk-radius: 14px;
+  position: fixed; inset: 0; z-index: 9999;
+  display: flex; align-items: flex-start; justify-content: center;
+  padding: 12vh 16px 16px;
+  background: rgba(15,17,21,.45);
+  backdrop-filter: blur(2px);
+}
+.ctrlk-overlay[hidden] { display: none; }
+@media (prefers-color-scheme: dark) {
+  .ctrlk-overlay {
+    --ctrlk-bg: #1c1f26; --ctrlk-fg: #f3f4f6; --ctrlk-muted: #9aa1ad;
+    --ctrlk-border: #2d323c; --ctrlk-active: #272b34; --ctrlk-accent: #6ea8fe;
+    --ctrlk-mark-fg: #1a1a1a; --ctrlk-shadow: 0 16px 48px rgba(0,0,0,.5);
+  }
+}
+.ctrlk-dialog {
+  width: 100%; max-width: 640px; max-height: 76vh;
+  display: flex; flex-direction: column; overflow: hidden;
+  background: var(--ctrlk-bg); color: var(--ctrlk-fg);
+  border: 1px solid var(--ctrlk-border); border-radius: var(--ctrlk-radius);
+  box-shadow: var(--ctrlk-shadow);
+  animation: ctrlk-in .12s ease-out;
+}
+@keyframes ctrlk-in { from { opacity: 0; transform: translateY(-6px) scale(.99); } to { opacity: 1; transform: none; } }
+@media (prefers-reduced-motion: reduce) { .ctrlk-dialog { animation: none; } }
+
+.ctrlk-header { display: flex; align-items: center; gap: 10px; padding: 14px 16px; border-bottom: 1px solid var(--ctrlk-border); }
+.ctrlk-header svg { width: 18px; height: 18px; flex: none; color: var(--ctrlk-muted); }
+.ctrlk-input {
+  flex: 1; min-width: 0; border: 0; outline: 0; background: transparent;
+  font: inherit; font-size: 1rem; color: var(--ctrlk-fg);
+}
+.ctrlk-input::placeholder { color: var(--ctrlk-muted); }
+.ctrlk-esc {
+  flex: none; font-size: .7rem; line-height: 1; padding: 4px 7px; color: var(--ctrlk-muted);
+  border: 1px solid var(--ctrlk-border); border-radius: 6px; background: var(--ctrlk-active);
+}
+
+.ctrlk-list { overflow-y: auto; overscroll-behavior: contain; padding: 6px; flex: 1; }
+.ctrlk-group-label {
+  padding: 12px 10px 6px; font-size: .72rem; font-weight: 600; letter-spacing: .04em;
+  text-transform: uppercase; color: var(--ctrlk-muted);
+}
+.ctrlk-option {
+  display: flex; gap: 11px; align-items: flex-start; padding: 9px 10px; border-radius: 9px;
+  cursor: pointer; color: inherit; text-decoration: none; scroll-margin: 8px;
+}
+.ctrlk-option[aria-selected="true"] { background: var(--ctrlk-active); }
+.ctrlk-option-icon { flex: none; width: 18px; height: 18px; margin-top: 2px; color: var(--ctrlk-muted); display: flex; align-items: center; justify-content: center; font-size: .95rem; }
+.ctrlk-option-body { min-width: 0; flex: 1; }
+.ctrlk-option-title { font-size: .92rem; font-weight: 500; color: var(--ctrlk-fg); overflow: hidden; text-overflow: ellipsis; white-space: nowrap; }
+.ctrlk-option-path { font-size: .76rem; color: var(--ctrlk-muted); overflow: hidden; text-overflow: ellipsis; white-space: nowrap; }
+.ctrlk-option-excerpt { font-size: .8rem; color: var(--ctrlk-muted); margin-top: 2px; display: -webkit-box; -webkit-line-clamp: 2; -webkit-box-orient: vertical; overflow: hidden; }
+.ctrlk-option mark { background: var(--ctrlk-mark); color: var(--ctrlk-mark-fg); border-radius: 2px; padding: 0 1px; }
+
+.ctrlk-state { padding: 36px 16px; text-align: center; color: var(--ctrlk-muted); font-size: .9rem; }
+
+.ctrlk-footer {
+  display: flex; gap: 16px; align-items: center; padding: 9px 14px;
+  border-top: 1px solid var(--ctrlk-border); color: var(--ctrlk-muted); font-size: .76rem;
+}
+.ctrlk-footer .ctrlk-hint { display: inline-flex; gap: 5px; align-items: center; }
+.ctrlk-footer kbd {
+  font: inherit; font-size: .72rem; min-width: 18px; height: 18px; padding: 0 4px;
+  display: inline-flex; align-items: center; justify-content: center;
+  border: 1px solid var(--ctrlk-border); border-radius: 5px; background: var(--ctrlk-active);
+}
+.ctrlk-footer .ctrlk-spacer { margin-left: auto; }
+
+html.ctrlk-open, body.ctrlk-open { overflow: hidden !important; }
+`;
+/** Inject the default stylesheet once (no-op on the server or if already present). */
+export function injectStyles(doc = document) {
+    if (typeof document === "undefined" && !doc)
+        return;
+    if (doc.getElementById(STYLE_ID))
+        return;
+    const el = doc.createElement("style");
+    el.id = STYLE_ID;
+    el.textContent = CSS;
+    doc.head.appendChild(el);
+}

package/dist/types.d.ts

@@ -0,0 +1,87 @@
+/** A selectable row. The shape is intentionally open — `data` carries whatever the
+ *  consumer needs back in `onSelect`. `id` must be stable and unique (ARIA ids,
+ *  selection, dedup all key on it). */
+export interface CtrlkItem<D = unknown> {
+    /** Stable unique id. */
+    id: string;
+    /** Primary label. In static-filter mode this (plus `keywords`) is what the query matches. */
+    title: string;
+    /** Secondary line — e.g. a breadcrumb path ("Guides › Install"). */
+    description?: string;
+    /** Snippet / matched body text shown under the title. */
+    excerpt?: string;
+    /** Group label. Items sharing a group render under one heading, in first-seen order. */
+    group?: string;
+    /** Leading glyph/icon hint for the default renderer ("page" | "hash" | custom string). */
+    icon?: string;
+    /** Extra terms matched in static-filter mode (never shown). */
+    keywords?: string[];
+    /** Optional destination. The default renderer makes the row a link and Enter navigates here. */
+    href?: string;
+    /** Arbitrary payload handed back to `onSelect`. */
+    data?: D;
+}
+/** A click/keypress context passed to `onSelect`, so a consumer can honor modifier-clicks
+ *  (open in new tab, etc.) without the renderer owning that policy. */
+export interface CtrlkSelectEvent {
+    metaKey?: boolean;
+    ctrlKey?: boolean;
+    shiftKey?: boolean;
+    altKey?: boolean;
+}
+export interface CtrlkOptions<D = unknown> {
+    /** Async data source, called (debounced) on every query change; return ranked items.
+     *  Receives an AbortSignal so stale in-flight requests can be dropped. When set, it takes
+     *  precedence over `items`/`filter`. */
+    search?: (query: string, signal: AbortSignal) => CtrlkItem<D>[] | Promise<CtrlkItem<D>[]>;
+    /** Static item pool, filtered locally by `filter` (cmdk-style). Used when `search` is absent. */
+    items?: CtrlkItem<D>[];
+    /** Static-mode scorer: returns >0 to keep an item (higher = ranked earlier), 0 to drop it.
+     *  Defaults to a case-insensitive substring/subsequence match over title + keywords. */
+    filter?: (item: CtrlkItem<D>, query: string) => number;
+    /** Milliseconds to wait after the last keystroke before calling `search`. Default 120. */
+    debounce?: number;
+    /** Rows to show when the query is empty (recent searches, suggestions). Default: none in
+     *  async mode, the full pool in static mode. */
+    empty?: CtrlkItem<D>[];
+    /** Invoked when a row is chosen (Enter or click). The default renderer additionally
+     *  navigates `item.href` when present and the event has no opening modifier. */
+    onSelect?: (item: CtrlkItem<D>, ev?: CtrlkSelectEvent) => void;
+}
+/** A group of rows under one heading. The ungrouped bucket has `label === ""`. */
+export interface CtrlkGroup<D = unknown> {
+    label: string;
+    items: CtrlkItem<D>[];
+}
+/** The full observable state. The renderer is a pure function of this. */
+export interface CtrlkState<D = unknown> {
+    open: boolean;
+    query: string;
+    loading: boolean;
+    /** Resolved, ordered rows for the current query (post-filter in static mode). */
+    items: CtrlkItem<D>[];
+    /** `items` bucketed by group, in first-seen order. */
+    groups: CtrlkGroup<D>[];
+    /** Index into `items` of the highlighted row, or -1 when there are none. */
+    activeIndex: number;
+    /** The last async-source error, if any (cleared on the next successful resolve). */
+    error: Error | null;
+}
+/** The headless controller. Drive it from any renderer (or none). */
+export interface Ctrlk<D = unknown> {
+    getState(): Readonly<CtrlkState<D>>;
+    /** Subscribe to state changes. Fires once immediately with the current state. Returns an unsubscribe. */
+    subscribe(fn: (state: Readonly<CtrlkState<D>>) => void): () => void;
+    open(): void;
+    close(): void;
+    toggle(): void;
+    setQuery(query: string): void;
+    /** Move the active row by `delta`, wrapping around the ends. */
+    move(delta: number): void;
+    /** Set the active row to an absolute index (clamped to range). */
+    setActive(index: number): void;
+    /** Choose a row — the given `item`, or the active one — firing `onSelect`. */
+    select(item?: CtrlkItem<D>, ev?: CtrlkSelectEvent): void;
+    /** Cancel timers/in-flight requests and drop all subscribers. */
+    destroy(): void;
+}

package/dist/types.js

@@ -0,0 +1,3 @@
+// Public types for @kurajs/ctrlk. The core (state machine) and the default DOM renderer
+// both speak these; a consumer can drive the core directly or mount the renderer.
+export {};

package/package.json

@@ -0,0 +1,44 @@
+{
+  "name": "@kurajs/ctrlk",
+  "version": "0.0.1",
+  "type": "module",
+  "description": "Kura — ⌘K command palette: a headless, zero-dependency command/search menu with a built-in default renderer. Framework-agnostic (vanilla DOM); mirrors cmdk's model & accessibility without React.",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "test": "node --experimental-strip-types --test test/*.test.ts"
+  },
+  "keywords": [
+    "kura",
+    "june",
+    "command-palette",
+    "cmdk",
+    "ctrl-k",
+    "command-menu",
+    "search",
+    "headless",
+    "a11y"
+  ],
+  "homepage": "https://kura.build",
+  "license": "MIT",
+  "devDependencies": {
+    "typescript": "^5.7.0"
+  },
+  "author": "Lawrence Lin",
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/kurajs/kura.git",
+    "directory": "packages/ctrlk"
+  }
+}