@stridge/noctis 1.0.0-beta.5 → 1.0.0-beta.6

package/dist/components/command/command-listbox.js

@@ -0,0 +1,174 @@
+"use client";
+import { createContext, use, useCallback, useEffect, useId, useMemo, useRef, useState } from "react";
+//#region src/components/command/command-listbox.tsx
+/**
+* The command palette's own combobox/listbox engine. Rather than delegate the keyboard model to a
+* generic autocomplete primitive (and then fight it for command-bar details), Noctis owns it directly:
+* the top result auto-highlights on every keystroke, arrow navigation has a smart key-repeat loop
+* (holding a key stops at the end; a fresh press wraps), and Enter activates the highlighted row. Focus
+* stays on the input throughout — a virtual cursor (`aria-activedescendant`) moves the active row, the
+* WAI-ARIA editable-combobox pattern.
+*/
+/** Enabled command rows, in DOM (render) order — the unit the navigation and auto-highlight act on. */
+const OPTION_SELECTOR = "[data-slot=\"noctis-command-item\"]:not([aria-disabled=\"true\"])";
+/**
+* Resolve a keydown to a navigation intent, matching the reference's bindings:
+* ↓/↑ step; ⌘/Alt+↓/↑ jump to the ends; Home/End to the ends; PageDown/PageUp by a page; Ctrl-N/J down and
+* Ctrl-P/K up (emacs/vim); Enter activates. Returns `null` for anything else so typing falls through.
+*/
+function navIntentFor(event) {
+	const jump = event.metaKey || event.altKey;
+	switch (event.key) {
+		case "Enter": return "activate";
+		case "ArrowDown": return jump ? "last" : "down";
+		case "ArrowUp": return jump ? "first" : "up";
+		case "Home": return "first";
+		case "End": return "last";
+		case "PageDown": return "pageDown";
+		case "PageUp": return "pageUp";
+		default: break;
+	}
+	if (event.ctrlKey && !event.metaKey && !event.altKey) {
+		const key = event.key.toLowerCase();
+		if (key === "n" || key === "j") return "down";
+		if (key === "p" || key === "k") return "up";
+	}
+	return null;
+}
+const CommandListboxContext = createContext(null);
+/** Read the listbox context, throwing a named error when a part renders outside the palette. */
+function useCommandListbox(part) {
+	const context = use(CommandListboxContext);
+	if (context === null) throw new Error(`Command.${part} must be rendered inside <Command.Root> or <Command.Dialog>.`);
+	return context;
+}
+const CommandListboxProvider = CommandListboxContext.Provider;
+/** A row's stable id plus whether it is the active (highlighted) row and a setter to claim the highlight. */
+function useCommandOption() {
+	const id = useId();
+	const { activeId, setActiveId } = useCommandListbox("Item");
+	const setActive = useCallback(() => setActiveId(id), [id, setActiveId]);
+	return {
+		id,
+		active: id === activeId,
+		setActive
+	};
+}
+/** Lets a `Command.GroupLabel` lend its id to its `Command.Group`'s `aria-labelledby` (only when present). */
+/** A `Command.GroupLabel` rendered outside any group registers into this no-op, so the call is always safe. */
+const noopRegisterGroupLabel = () => {};
+const CommandGroupContext = createContext(noopRegisterGroupLabel);
+const CommandGroupProvider = CommandGroupContext.Provider;
+/** Register a group label's id with its enclosing group, so the group is `aria-labelledby` it while mounted. */
+function useRegisterGroupLabel(id) {
+	const register = use(CommandGroupContext);
+	useEffect(() => {
+		register(id);
+		return () => register(void 0);
+	}, [id, register]);
+}
+/** The group's own state: the id of its label (if a `Command.GroupLabel` is rendered) for `aria-labelledby`. */
+function useCommandGroup() {
+	const [labelId, setLabelId] = useState(void 0);
+	return {
+		labelId,
+		setLabelId
+	};
+}
+/** Owns the active-row state, the auto-highlight, and the keyboard navigation that the input delegates to. */
+function useCommandListboxState({ query, setQuery, loop, viewKey }) {
+	const listId = useId();
+	const listRef = useRef(null);
+	const [activeId, setActiveIdState] = useState(void 0);
+	const activeIdRef = useRef(void 0);
+	const setActiveId = useCallback((id) => {
+		activeIdRef.current = id;
+		setActiveIdState(id);
+	}, []);
+	const options = useCallback(() => listRef.current ? Array.from(listRef.current.querySelectorAll(OPTION_SELECTOR)) : [], []);
+	const prevViewRef = useRef(null);
+	useEffect(() => {
+		const list = listRef.current;
+		if (!list) return;
+		const opts = Array.from(list.querySelectorAll(OPTION_SELECTOR));
+		const viewChanged = prevViewRef.current !== viewKey;
+		prevViewRef.current = viewKey;
+		if (opts.length === 0) {
+			if (activeId !== void 0) setActiveId(void 0);
+			return;
+		}
+		const stillValid = activeId !== void 0 && opts.some((option) => option.id === activeId);
+		if (viewChanged || !stillValid) {
+			setActiveId(opts[0].id);
+			if (viewChanged) list.scrollTop = 0;
+		}
+	});
+	const onInputKeyDown = useCallback((event) => {
+		const intent = navIntentFor(event);
+		if (intent === null) return;
+		const opts = options();
+		if (opts.length === 0) return;
+		const current = opts.findIndex((option) => option.id === activeIdRef.current);
+		const last = opts.length - 1;
+		if (intent === "activate") {
+			event.preventDefault();
+			/* v8 ignore next -- the guard's false branch (Enter with nothing highlighted) is unreachable */
+			if (current >= 0) opts[current].click();
+			return;
+		}
+		const list = listRef.current;
+		/* v8 ignore next -- jsdom reports offsetHeight 0, so only the `|| 1` guard runs (real rows measure > 0) */
+		const rowHeight = opts[0].offsetHeight || 1;
+		const page = Math.max(1, Math.floor(list.clientHeight / rowHeight) - 1);
+		const from = Math.max(current, 0);
+		let next;
+		switch (intent) {
+			case "down":
+				next = current >= last ? loop && !event.repeat ? 0 : last : from + 1;
+				break;
+			case "up":
+				next = current <= 0 ? loop && !event.repeat ? last : 0 : current - 1;
+				break;
+			case "first":
+				next = 0;
+				break;
+			case "last":
+				next = last;
+				break;
+			case "pageDown":
+				next = Math.min(from + page, last);
+				break;
+			default:
+				next = Math.max(from - page, 0);
+				break;
+		}
+		event.preventDefault();
+		const target = opts[next];
+		setActiveId(target.id);
+		if (next === 0) list.scrollTop = 0;
+		else if (next === last) list.scrollTop = list.scrollHeight;
+		else target.scrollIntoView({ block: "nearest" });
+	}, [
+		loop,
+		options,
+		setActiveId
+	]);
+	return useMemo(() => ({
+		query,
+		setQuery,
+		listId,
+		activeId,
+		listRef,
+		setActiveId,
+		onInputKeyDown
+	}), [
+		query,
+		setQuery,
+		listId,
+		activeId,
+		setActiveId,
+		onInputKeyDown
+	]);
+}
+//#endregion
+export { CommandGroupProvider, CommandListboxProvider, useCommandGroup, useCommandListbox, useCommandListboxState, useCommandOption, useRegisterGroupLabel };

package/dist/components/command/command-rank.d.ts

@@ -0,0 +1,40 @@
+//#region src/components/command/command-rank.d.ts
+/** A candidate the ranker can score. Carry whatever else you need on the same object; only these are read. */
+interface RankableItem {
+  /** A stable, unique value/id for the item (used as the React key and the selection value). */
+  value: string;
+  /** The text the query is scored against (the row's label). */
+  label: string;
+  /** Hidden aliases the row should also answer to (e.g. `["new", "add"]`), folded into the score. */
+  keywords?: readonly string[];
+  /**
+   * A `[0, 1]` usage/recency boost blended into the textual score (frecency). The consumer owns and
+   * persists this; the ranker only reads it. A boost only re-orders items that already match — it
+   * never resurrects a non-matching row.
+   */
+  boost?: number;
+}
+/** Options for {@link rankItems}. */
+interface RankOptions<T extends RankableItem> {
+  /**
+   * Items whose textual score is at or below this are dropped. `0` keeps any subsequence match.
+   * @default 0
+   */
+  threshold?: number;
+  /**
+   * Override the textual scorer. Receives the item and the query, returns `[0, 1]`. Defaults to
+   * {@link commandScore} over the label + keywords.
+   */
+  score?: (item: T, query: string) => number;
+}
+/**
+ * Rank `items` against `query`: score each (blending its `boost`), drop everything at or below
+ * `threshold`, and return the survivors sorted strongest-first. An empty/whitespace query returns the
+ * items unchanged (the caller's own order), so the palette shows its full list at rest.
+ *
+ * The sort is stable, so equally-scored items keep their input order — let the caller pre-order by
+ * section/priority and ties resolve predictably.
+ */
+declare function rankItems<T extends RankableItem>(items: readonly T[], query: string, options?: RankOptions<T>): T[];
+//#endregion
+export { RankOptions, RankableItem, rankItems };

package/dist/components/command/command-rank.js

@@ -0,0 +1,61 @@
+import { commandScore } from "./command-score.js";
+//#region src/components/command/command-rank.ts
+/**
+* Ranking layer over {@link commandScore}: turn a flat list of candidates and a query into the ordered,
+* filtered list a palette renders. This is the seam where the consumer's frecency (a per-item usage
+* `boost`) is blended into the textual score, and where a custom scorer can be dropped in. Pure and
+* synchronous — the default path used everywhere; the Worker offload (`useCommandRanking`) wraps this
+* same function for large sets.
+*/
+const defaultScore = (item, query) => commandScore(item.label, query, item.keywords);
+/**
+* Rank `items` against `query`: score each (blending its `boost`), drop everything at or below
+* `threshold`, and return the survivors sorted strongest-first. An empty/whitespace query returns the
+* items unchanged (the caller's own order), so the palette shows its full list at rest.
+*
+* The sort is stable, so equally-scored items keep their input order — let the caller pre-order by
+* section/priority and ties resolve predictably.
+*/
+function rankItems(items, query, options = {}) {
+	const trimmed = query.trim();
+	if (trimmed === "") return items.slice();
+	const { threshold = 0, score = defaultScore } = options;
+	const scored = [];
+	items.forEach((item, order) => {
+		const base = score(item, trimmed);
+		if (base <= threshold) return;
+		const sortScore = base * (1 + (item.boost ?? 0));
+		scored.push({
+			item,
+			sortScore,
+			order
+		});
+	});
+	scored.sort((a, b) => b.sortScore - a.sortScore || a.order - b.order);
+	return scored.map((entry) => entry.item);
+}
+/**
+* The default ranking reduced to just the surviving `value`s, strongest-first — the unit of work the
+* Web Worker performs (it can't pass rich objects or a custom scorer across the boundary). Mirrors
+* {@link rankItems} with the default scorer, and is **self-contained** (it references only
+* {@link commandScore}) so it can be serialised into the Worker via `toString()`. The hook maps the
+* returned values back to its full items.
+*/
+function rankValues(items, query, threshold = 0) {
+	const trimmed = query.trim();
+	if (trimmed === "") return items.map((item) => item.value);
+	const scored = [];
+	items.forEach((item, order) => {
+		const base = commandScore(item.label, trimmed, item.keywords);
+		if (base <= threshold) return;
+		scored.push({
+			value: item.value,
+			sortScore: base * (1 + (item.boost ?? 0)),
+			order
+		});
+	});
+	scored.sort((a, b) => b.sortScore - a.sortScore || a.order - b.order);
+	return scored.map((entry) => entry.value);
+}
+//#endregion
+export { rankItems, rankValues };

package/dist/components/command/command-score.d.ts

@@ -0,0 +1,25 @@
+//#region src/components/command/command-score.d.ts
+/**
+ * A fuzzy subsequence scorer for command palettes — the ranking brain `Command` ships by default. It
+ * rewards the matches a person reading a palette expects to float to the top: a contiguous prefix beats
+ * a gapped one, a match at a word boundary (after a space, `-`, `_`, `/`, `.`, …) beats one mid-word,
+ * an exact-case hit edges out a case-fold, and a single transposed pair still scores. The result is a
+ * number in `[0, 1]` — `0` means "no subsequence match", `1` means "the query is the whole string".
+ *
+ * The algorithm is the well-known open command-palette scorer (the same family editor and command-bar
+ * UIs use): a memoized recursive search over every way the query can thread through the candidate,
+ * keeping the best-scoring threading. Authored clean-room from the documented algorithm; the constants
+ * are the canonical weights.
+ *
+ * The whole function is intentionally **self-contained** (every constant and the recursion live in its
+ * own scope, no outer-scope references) so it can be serialised verbatim into the ranking Web Worker via
+ * `Function.prototype.toString()` — the worker reuses this exact, tested implementation rather than a
+ * copy. Keep it free of module-level references for that reason.
+ *
+ * @param candidate The text shown on the row (its label).
+ * @param query The current input value.
+ * @param keywords Hidden aliases appended to the candidate before scoring (e.g. `["new", "add"]`).
+ */
+declare function commandScore(candidate: string, query: string, keywords?: readonly string[]): number;
+//#endregion
+export { commandScore };

package/dist/components/command/command-score.js

@@ -0,0 +1,85 @@
+//#region src/components/command/command-score.ts
+/**
+* A fuzzy subsequence scorer for command palettes — the ranking brain `Command` ships by default. It
+* rewards the matches a person reading a palette expects to float to the top: a contiguous prefix beats
+* a gapped one, a match at a word boundary (after a space, `-`, `_`, `/`, `.`, …) beats one mid-word,
+* an exact-case hit edges out a case-fold, and a single transposed pair still scores. The result is a
+* number in `[0, 1]` — `0` means "no subsequence match", `1` means "the query is the whole string".
+*
+* The algorithm is the well-known open command-palette scorer (the same family editor and command-bar
+* UIs use): a memoized recursive search over every way the query can thread through the candidate,
+* keeping the best-scoring threading. Authored clean-room from the documented algorithm; the constants
+* are the canonical weights.
+*
+* The whole function is intentionally **self-contained** (every constant and the recursion live in its
+* own scope, no outer-scope references) so it can be serialised verbatim into the ranking Web Worker via
+* `Function.prototype.toString()` — the worker reuses this exact, tested implementation rather than a
+* copy. Keep it free of module-level references for that reason.
+*
+* @param candidate The text shown on the row (its label).
+* @param query The current input value.
+* @param keywords Hidden aliases appended to the candidate before scoring (e.g. `["new", "add"]`).
+*/
+function commandScore(candidate, query, keywords) {
+	/** A contiguous continuation of the match — the strongest signal. */
+	const SCORE_CONTINUE_MATCH = 1;
+	/** Jumping to the start of a new space-delimited word. */
+	const SCORE_SPACE_WORD_JUMP = .9;
+	/** Jumping to the start of a new word delimited by a non-space separator (`-`, `_`, `/`, …). */
+	const SCORE_NON_SPACE_WORD_JUMP = .8;
+	/** Jumping to a character mid-word (the weakest jump). */
+	const SCORE_CHARACTER_JUMP = .17;
+	/** A transposed pair (e.g. "recieve" matching "receive"). */
+	const SCORE_TRANSPOSITION = .1;
+	/** Multiplicative penalty per skipped character, so tighter matches win. */
+	const PENALTY_SKIPPED = .999;
+	/** Penalty when the matched character's case differs from the query's. */
+	const PENALTY_CASE_MISMATCH = .9999;
+	/** Penalty when the query is exhausted but the candidate still has trailing characters. */
+	const PENALTY_NOT_COMPLETE = .99;
+	const IS_GAP = /[\\/_+.#"@[({&]/;
+	const COUNT_GAP = /[\\/_+.#"@[({&]/g;
+	const IS_SPACE = /[\s-]/;
+	const COUNT_SPACE = /[\s-]/g;
+	const fold = (value) => value.toLowerCase().replace(COUNT_SPACE, " ");
+	const scoreInner = (cand, q, lc, lq, ci, qi, memo) => {
+		if (qi === q.length) return ci === cand.length ? SCORE_CONTINUE_MATCH : PENALTY_NOT_COMPLETE;
+		const key = `${ci},${qi}`;
+		const cached = memo[key];
+		if (cached !== void 0) return cached;
+		const queryChar = lq.charAt(qi);
+		let index = lc.indexOf(queryChar, ci);
+		let high = 0;
+		while (index >= 0) {
+			let score = scoreInner(cand, q, lc, lq, index + 1, qi + 1, memo);
+			if (score > high) {
+				if (index === ci) score *= SCORE_CONTINUE_MATCH;
+				else if (IS_GAP.test(cand.charAt(index - 1))) {
+					score *= SCORE_NON_SPACE_WORD_JUMP;
+					const gaps = cand.slice(ci, index - 1).match(COUNT_GAP);
+					if (gaps && ci > 0) score *= PENALTY_SKIPPED ** gaps.length;
+				} else if (IS_SPACE.test(cand.charAt(index - 1))) {
+					score *= SCORE_SPACE_WORD_JUMP;
+					const spaces = cand.slice(ci, index - 1).match(COUNT_SPACE);
+					if (spaces && ci > 0) score *= PENALTY_SKIPPED ** spaces.length;
+				} else {
+					score *= SCORE_CHARACTER_JUMP;
+					if (ci > 0) score *= PENALTY_SKIPPED ** (index - ci);
+				}
+				if (cand.charAt(index) !== q.charAt(qi)) score *= PENALTY_CASE_MISMATCH;
+			}
+			if (score < SCORE_TRANSPOSITION && lc.charAt(index - 1) === lq.charAt(qi + 1) || lq.charAt(qi + 1) === lq.charAt(qi) && lc.charAt(index - 1) !== lq.charAt(qi)) {
+				const transposed = scoreInner(cand, q, lc, lq, index + 1, qi + 2, memo);
+				score = Math.max(score, transposed * SCORE_TRANSPOSITION);
+			}
+			if (score > high) high = score;
+			index = lc.indexOf(queryChar, index + 1);
+		}
+		memo[key] = high;
+		return high;
+	};
+	const haystack = keywords && keywords.length > 0 ? `${candidate} ${keywords.join(" ")}` : candidate;
+	return scoreInner(haystack, query, fold(haystack), fold(query), 0, 0, {});
+}
+//#endregion
+export { commandScore };

package/dist/components/command/command.context.d.ts

@@ -0,0 +1,17 @@
+import { ReactNode } from "react";
+
+//#region src/components/command/command.context.d.ts
+/**
+ * One entry in the drill-in stack. Selecting a parent command pushes a page (the list swaps to its
+ * children, the query clears, a breadcrumb segment appears); Backspace on the empty query — or clicking
+ * an earlier segment — pops back. The consumer owns the stack (`pages` + `onPagesChange` on
+ * `Command.Root`) so it can load children lazily.
+ */
+interface CommandPage {
+  /** A stable id for the page (used as the React key and for navigation). */
+  id: string;
+  /** The breadcrumb label rendered for this page. */
+  label: ReactNode;
+}
+//#endregion
+export { CommandPage };

package/dist/components/command/command.context.js

@@ -0,0 +1,13 @@
+"use client";
+import { createContext, use } from "react";
+//#region src/components/command/command.context.ts
+const CommandContext = createContext(null);
+const CommandProvider = CommandContext.Provider;
+/** Read the palette context, throwing a named error when a part renders outside `Command.Root`. */
+function useCommandContext(part) {
+	const context = use(CommandContext);
+	if (context === null) throw new Error(`Command.${part} must be rendered inside <Command.Root> or <Command.Dialog>.`);
+	return context;
+}
+//#endregion
+export { CommandProvider, useCommandContext };