command-filter.ts

command-filter.tspackages/ui/src/command-filter.tsraw ← src5,309 B← Back to the app
1/**
2 * @factory/ui — command palette: PURE filtering + keyboard navigation.
3 *
4 * Two pieces, both fully testable without React/DOM:
5 *  - {@link scoreCommand}/{@link filterCommands}: fuzzy SUBSEQUENCE scoring —
6 *    every query character must appear in order inside the target; consecutive
7 *    matches and word-boundary matches score higher. Ties break by ORIGINAL
8 *    INDEX (stable, deterministic).
9 *  - {@link commandNav}: a reducer over the selection state — ArrowUp/Down
10 *    (wrapping), Home/End, Enter (select), Escape (close).
11 *
12 * The .tsx `CommandPalette` wires query input + nav state to this module.
13 */
14 
15export interface CommandItem {
16  id: string;
17  /** Primary label shown in the palette (match target). */
18  title: string;
19  /** Optional secondary text (shortcut, hint) — not a match target. */
20  hint?: string;
21}
22 
23export interface ScoredCommand {
24  item: CommandItem;
25  score: number;
26}
27 
28const BONUS_CONTIGUOUS = 4;
29const BONUS_WORD_START = 2;
30 
31/**
32 * Fuzzy subsequence score of `query` against `target`. Returns -1 when the
33 * query is NOT a subsequence (case-insensitive). Scoring:
34 *  - +1 per matched character
35 *  - +4 when a match continues the previous match position (contiguous run)
36 *  - +2 when a match starts a word (boundary: start of string or after space)
37 *  - -0.1 per gap character between matches (prefers tighter matches)
38 * Empty query matches everything with score 0.
39 */
40export function scoreCommand(query: string, target: string): number {
41  const q = query.trim().toLowerCase();
42  const t = target.toLowerCase();
43  if (q.length === 0) return 0;
44  let score = 0;
45  let ti = 0;
46  let prevMatch = -2;
47  for (let qi = 0; qi < q.length; qi += 1) {
48    const ch = q[qi];
49    let found = -1;
50    while (ti < t.length) {
51      if (t[ti] === ch) {
52        found = ti;
53        break;
54      }
55      ti += 1;
56    }
57    if (found < 0) return -1; // query char missing → not a subsequence
58    score += 1;
59    if (found === prevMatch + 1) score += BONUS_CONTIGUOUS;
60    if (found === 0 || t[found - 1] === " ") score += BONUS_WORD_START;
61    if (found > prevMatch + 1) score -= (found - prevMatch - 1) * 0.1;
62    prevMatch = found;
63    ti = found + 1;
64  }
65  return score;
66}
67 
68/**
69 * Filter + rank items against a query. Deterministic: sorted by score
70 * descending, ties by original index ascending. Items scoring < 0 are dropped.
71 */
72export function filterCommands(items: readonly CommandItem[], query: string): ScoredCommand[] {
73  const scored: Array<ScoredCommand & { index: number }> = [];
74  for (let i = 0; i < items.length; i += 1) {
75    const item = items[i];
76    if (item === undefined) continue;
77    const score = scoreCommand(query, item.title);
78    if (score >= 0) scored.push({ item, score, index: i });
79  }
80  // Deterministic: score descending, ties by ORIGINAL INDEX ascending.
81  scored.sort((a, b) => b.score - a.score || a.index - b.index);
82  return scored.map(({ index: _index, ...rest }) => rest);
83}
84 
85export interface CommandNavState {
86  /** Currently highlighted index; -1 = nothing highlighted. */
87  active: number;
88  /** Number of visible results (clamped by the caller). */
89  count: number;
90  open: boolean;
91}
92 
93export type CommandNavKey = "ArrowUp" | "ArrowDown" | "Enter" | "Escape" | "Home" | "End";
94 
95export type CommandNavAction =
96  | { type: "key"; key: CommandNavKey }
97  | { type: "open" }
98  | { type: "close" }
99  | { type: "results"; count: number };
100 
101/**
102 * Pure navigation reducer for the command palette.
103 *  - ArrowDown/ArrowUp move the highlight with wrap-around (Home/End jump);
104 *    with `count === 0` the highlight stays -1.
105 *  - Enter is a NO-OP on state: selecting `state.active` is a side effect the
106 *    wiring performs (dispatch "close" afterwards when appropriate).
107 *  - Escape closes (resets highlight to -1).
108 *  - "results" re-bounds `active` into [0, count) when the list shrinks.
109 *  - Keys are ignored while closed or when `count === 0`.
110 */
111export function commandNav(state: CommandNavState, action: CommandNavAction): CommandNavState {
112  switch (action.type) {
113    case "open":
114      return { ...state, open: true, active: state.active >= 0 ? state.active : 0 };
115    case "close":
116      return { ...state, open: false, active: -1 };
117    case "results": {
118      const count = Math.max(0, action.count);
119      const active = state.active >= 0 ? Math.min(state.active, Math.max(0, count - 1)) : -1;
120      return { ...state, count, active };
121    }
122    case "key": {
123      if (!state.open) return state;
124      if (state.count === 0) return state;
125      const n = state.count;
126      switch (action.key) {
127        case "ArrowDown": {
128          const next = state.active < 0 ? 0 : (state.active + 1) % n;
129          return { ...state, active: next };
130        }
131        case "ArrowUp": {
132          const next = state.active < 0 ? n - 1 : (state.active - 1 + n) % n;
133          return { ...state, active: next };
134        }
135        case "Home":
136          return { ...state, active: 0 };
137        case "End":
138          return { ...state, active: n - 1 };
139        case "Enter":
140          return state; // selection is a side effect handled by the wiring
141        case "Escape":
142          return { ...state, open: false, active: -1 };
143        default:
144          return state;
145      }
146    }
147    default:
148      return state;
149  }
150}
151