@kurajs/ctrlk 0.0.1 → 0.0.2

package/README.md

@@ -71,7 +71,11 @@ Pass `renderItem` to fully control row markup, or `injectStyles: false` to ship
 ## API
 
 - `createCtrlk(options) → Ctrlk` — headless controller. Options: `search` | `items` + `filter`,
-  `debounce`, `empty`, `onSelect`.
+  `debounce`, `empty`, `loop` (wrap arrow nav, default true), `shouldFilter` (static mode, default
+  true), `value` (initial highlight), `onSelect`, `onValueChange`, `onOpenChange`.
+  Controller methods: `open`/`close`/`toggle`, `setQuery`, `move`/`setActive`, `setValue` (by id),
+  `setItems` (swap the static pool), `select`, `subscribe`, `getState`, `destroy`. State exposes a
+  cmdk-style `value` (the active item id) alongside `activeIndex`.
 - `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).

package/dist/core.js

@@ -44,11 +44,14 @@ function bucket(items) {
  */
 export function createCtrlk(options = {}) {
     const debounceMs = options.debounce ?? DEFAULT_DEBOUNCE;
+    const loop = options.loop ?? true; // wrap arrow nav around the ends (false → clamp)
     const subs = new Set();
-    let state = { open: false, query: "", loading: false, items: [], groups: [], activeIndex: -1, error: null };
+    let staticItems = options.items ?? []; // the static-mode pool (swappable via setItems)
+    let state = { open: false, query: "", loading: false, items: [], groups: [], activeIndex: -1, value: null, error: null };
     let timer = null;
     let ac = null;
     let runSeq = 0; // monotonic guard: only the most recent async run may apply its result
+    let pendingValue = options.value ?? null; // initial highlight, honored on first results
     const emit = () => { const snap = state; for (const fn of [...subs])
         fn(snap); };
     const set = (patch) => { state = { ...state, ...patch }; emit(); };
@@ -56,24 +59,50 @@ export function createCtrlk(options = {}) {
         clearTimeout(timer);
         timer = null;
     } };
-    const applyItems = (items) => set({ items, groups: bucket(items), activeIndex: items.length ? 0 : -1, loading: false, error: null });
+    // Set the highlighted row by index, deriving `value` (its id) and firing onValueChange on change.
+    const commitActive = (index) => {
+        const value = index >= 0 ? state.items[index]?.id ?? null : null;
+        const changed = value !== state.value;
+        set({ activeIndex: index, value });
+        if (changed)
+            options.onValueChange?.(value);
+    };
+    // Replace the result set. `resetActive` (query-driven runs) highlights the first row — except an
+    // initial `value` is honored once; otherwise the current highlight is kept if it survived (so a
+    // host-driven setItems doesn't yank the user's selection).
+    const applyItems = (items, resetActive) => {
+        const want = resetActive ? pendingValue : state.value ?? pendingValue;
+        pendingValue = null;
+        let index = want != null ? items.findIndex((it) => it.id === want) : -1;
+        if (index < 0)
+            index = items.length ? 0 : -1;
+        const value = index >= 0 ? items[index].id : null;
+        const changed = value !== state.value;
+        state = { ...state, items, groups: bucket(items), activeIndex: index, value, loading: false, error: null };
+        emit();
+        if (changed)
+            options.onValueChange?.(value);
+    };
     const runStatic = (q) => {
-        const src = options.items ?? [];
+        if (options.shouldFilter === false) {
+            applyItems(staticItems.slice(), true);
+            return;
+        } // already ranked
         if (!q.trim()) {
-            applyItems((options.empty ?? src).slice());
+            applyItems((options.empty ?? staticItems).slice(), true);
             return;
         }
         const filter = options.filter ?? defaultFilter;
-        applyItems(src.map((it) => ({ it, s: filter(it, q) }))
+        applyItems(staticItems.map((it) => ({ it, s: filter(it, q) }))
             .filter((x) => x.s > 0)
             .sort((a, b) => b.s - a.s)
-            .map((x) => x.it));
+            .map((x) => x.it), true);
     };
     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());
+            applyItems((options.empty ?? []).slice(), true);
             return;
         }
         const seq = ++runSeq;
@@ -84,7 +113,7 @@ export function createCtrlk(options = {}) {
         try {
             const items = await options.search(q, controller.signal);
             if (seq === runSeq)
-                applyItems(items); // ignore out-of-order/stale resolves
+                applyItems(items, true); // ignore out-of-order/stale resolves
         }
         catch (err) {
             if (seq === runSeq && !controller.signal.aborted)
@@ -105,6 +134,7 @@ export function createCtrlk(options = {}) {
     };
     const open = () => { if (!state.open) {
         set({ open: true });
+        options.onOpenChange?.(true);
         schedule(state.query);
     } };
     // Closing invalidates any in-flight async run (bump the seq) so a late resolve/reject can't
@@ -114,6 +144,7 @@ export function createCtrlk(options = {}) {
         runSeq++;
         ac?.abort();
         set({ open: false, loading: false });
+        options.onOpenChange?.(false);
     } };
     return {
         getState: () => state,
@@ -129,13 +160,32 @@ export function createCtrlk(options = {}) {
             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 });
+            let i;
+            if (state.activeIndex < 0)
+                i = delta > 0 ? 0 : n - 1;
+            else if (loop)
+                i = (state.activeIndex + delta + n) % n;
+            else
+                i = Math.max(0, Math.min(n - 1, state.activeIndex + delta));
+            commitActive(i);
         },
         setActive(index) {
             const n = state.items.length;
             if (n)
-                set({ activeIndex: Math.max(0, Math.min(n - 1, index)) });
+                commitActive(Math.max(0, Math.min(n - 1, index)));
+        },
+        setValue(id) {
+            if (id == null) {
+                commitActive(-1);
+                return;
+            }
+            const i = state.items.findIndex((it) => it.id === id);
+            if (i >= 0)
+                commitActive(i);
+        },
+        setItems(items) {
+            staticItems = items;
+            applyItems(items, false); // host-supplied (e.g. externally filtered) → keep the active row if present
         },
         select(item, ev) {
             const it = item ?? state.items[state.activeIndex];

package/dist/types.d.ts

@@ -44,9 +44,20 @@ export interface CtrlkOptions<D = unknown> {
     /** 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>[];
+    /** Wrap arrow navigation around the list ends. Default true; set false to clamp at the ends. */
+    loop?: boolean;
+    /** Static mode: run the built-in filter/sort. Set false when `items` are already filtered and
+     *  ranked (e.g. you filter externally and feed results via {@link Ctrlk.setItems}). Default true. */
+    shouldFilter?: boolean;
+    /** Initial highlighted item id. Observe changes via {@link onValueChange}. */
+    value?: string;
     /** 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;
+    /** Fires when the highlighted item changes — its id, or null when the list is empty. */
+    onValueChange?: (value: string | null) => void;
+    /** Fires when the palette opens or closes (for URL/analytics sync). */
+    onOpenChange?: (open: boolean) => void;
 }
 /** A group of rows under one heading. The ungrouped bucket has `label === ""`. */
 export interface CtrlkGroup<D = unknown> {
@@ -64,6 +75,9 @@ export interface CtrlkState<D = unknown> {
     groups: CtrlkGroup<D>[];
     /** Index into `items` of the highlighted row, or -1 when there are none. */
     activeIndex: number;
+    /** Id of the highlighted row (its `item.id`), or null when there are none. Mirrors `activeIndex`
+     *  but is stable across reorders — the cmdk-style controlled selection value. */
+    value: string | null;
     /** The last async-source error, if any (cleared on the next successful resolve). */
     error: Error | null;
 }
@@ -80,6 +94,10 @@ export interface Ctrlk<D = unknown> {
     move(delta: number): void;
     /** Set the active row to an absolute index (clamped to range). */
     setActive(index: number): void;
+    /** Highlight the row with this id (no-op if absent); null clears the highlight. */
+    setValue(id: string | null): void;
+    /** Replace the item pool (static mode), keeping the current highlight if it survives. */
+    setItems(items: CtrlkItem<D>[]): 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. */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kurajs/ctrlk",
-  "version": "0.0.1",
+  "version": "0.0.2",
   "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": {