components/command-menu/command-menu.react.tsx

Functions

Imports

It imports components/command-menu/command-menu.ts, components/dialog/dialog.react.tsx, components/listbox/listbox.react.tsx, components/shortcuts/shortcuts.react.tsx, components/shortcuts/shortcuts.ts. Imported by components/command-menu/examples.tsx.

Source

1import { useCallback, useEffect, useId, useMemo, useRef, useState } from "react";
2import { Dialog } from "../dialog/dialog.react.tsx";
3import { Listbox, ListboxEmpty, Option, OptionGroup } from "../listbox/listbox.react.tsx";
4import { register } from "../shortcuts/shortcuts.ts";
5import { Keys } from "../shortcuts/shortcuts.react.tsx";
6import { emptyText, filterCommands, groupCommands, SEARCHING, step, type Command } from "./command-menu.ts";
7
8export type { Command } from "./command-menu.ts";
9export { SEARCHING, STOP_GROUP, STOP_HINTS, stopCommand } from "./command-menu.ts";
10
11export interface CommandMenuProps {
12  open: boolean;
13  onOpenChange: (open: boolean) => void;
14  commands: Command[];
15  // The input's accessible name (a visually hidden label).
16  label?: string;
17  placeholder?: string;
18  // Binds Ctrl K, Cmd K and "/" to open it. On by default.
19  bindKeys?: boolean;
20  // Results from an async source as the person types (books, people, records). Called with the
21  // trimmed query and an AbortSignal, `searchDelay` ms (180) after the last key, never for an
22  // empty query; the signal aborts when the query changes or the menu closes. Its commands come
23  // after the matching `commands`, in their own groups and order, unfiltered; their ids must not
24  // repeat a command's. The last results stay until new ones arrive; a failed search keeps them.
25  search?: (query: string, signal: AbortSignal) => Promise<Command[]>;
26  searchDelay?: number;
27}
28
29// The shortcut caps of a command, after the words that say it is a shortcut.
30function Caps({ spec }: { spec: string | string[] }) {
31  return (
32    <>
33      <span className="cap-sr-only">, shortcut </span>
34      <Keys spec={spec} />
35    </>
36  );
37}
38
39const SEARCH_ICON = <path fill="currentColor" fillRule="evenodd" d="M7 2.5a4.5 4.5 0 1 0 2.7 8.1l3 3 1.1-1.1-3-3A4.5 4.5 0 0 0 7 2.5zm0 1.5a3 3 0 1 1 0 6 3 3 0 0 1 0-6z" />;
40
41export function CommandMenu({ open, onOpenChange, commands, label = "Search commands", placeholder = "Search commands", bindKeys = true, search, searchDelay = 180 }: CommandMenuProps) {
42  const id = useId();
43  const dlg = useRef<HTMLDialogElement | null>(null);
44  const input = useRef<HTMLInputElement | null>(null);
45  const [query, setQuery] = useState("");
46  const [active, setActive] = useState(0);
47  const [found, setFound] = useState<Command[]>([]);
48  const [busy, setBusy] = useState(false);
49  const shown = useMemo(() => [...filterCommands(commands, query), ...found], [commands, query, found]);
50  const groups = useMemo(() => groupCommands(shown), [shown]);
51  const cur = shown.length ? Math.min(active, shown.length - 1) : -1;
52  const optionId = (c: Command) => `${id}-o-${c.id}`;
53  const activeCommand = cur >= 0 ? shown[cur] : undefined;
54
55  useEffect(() => {
56    if (!bindKeys) return;
57    return register({ key: ["Mod+k", "/"], label: "Open the command menu", group: "General", run: () => onOpenChange(true) });
58  }, [bindKeys, onOpenChange]);
59
60  // A fresh menu each time it opens: nothing typed, the first command active.
61  useEffect(() => {
62    if (!open) return;
63    setQuery("");
64    setActive(0);
65  }, [open]);
66
67  // The live search: debounced, the one before aborted, nothing for an empty query. Read through
68  // a ref, so an inline function does not start a search on every render.
69  const q = query.trim();
70  const searchRef = useRef(search);
71  searchRef.current = search;
72  const live = search != null;
73  useEffect(() => {
74    const run = searchRef.current;
75    if (!run || !open || !q) {
76      setFound([]);
77      setBusy(false);
78      return;
79    }
80    const ctrl = new AbortController();
81    setBusy(true);
82    const timer = setTimeout(() => {
83      run(q, ctrl.signal).then(
84        (results) => {
85          if (ctrl.signal.aborted) return;
86          setFound(results);
87          setBusy(false);
88        },
89        () => {
90          if (!ctrl.signal.aborted) setBusy(false);
91        },
92      );
93    }, searchDelay);
94    return () => {
95      clearTimeout(timer);
96      ctrl.abort();
97    };
98  }, [live, searchDelay, open, q]);
99
100  useEffect(() => {
101    if (activeCommand) document.getElementById(optionId(activeCommand))?.scrollIntoView({ block: "nearest" });
102  }, [activeCommand]);
103
104  const setRef = useCallback((el: HTMLDialogElement | null) => {
105    dlg.current = el;
106  }, []);
107
108  const choose = (c: Command | undefined) => {
109    if (!c) return;
110    dlg.current?.close();
111    c.run();
112  };
113
114  return (
115    <Dialog ref={setRef} className="cap-cmd" open={open} onOpenChange={onOpenChange} placement="top" size="lg" closeButton={false} initialFocus={input} aria-label="Command menu">
116      <div className="cap-cmd-search">
117        <svg viewBox="0 0 16 16" width="16" height="16" aria-hidden="true" focusable="false">
118          {SEARCH_ICON}
119        </svg>
120        <label className="cap-sr-only" htmlFor={`${id}-input`}>
121          {label}
122        </label>
123        <input
124          ref={input}
125          className="cap-cmd-input"
126          id={`${id}-input`}
127          type="text"
128          autoComplete="off"
129          spellCheck={false}
130          role="combobox"
131          aria-expanded={shown.length > 0}
132          aria-controls={`${id}-list`}
133          aria-autocomplete="list"
134          aria-activedescendant={activeCommand ? optionId(activeCommand) : undefined}
135          placeholder={placeholder}
136          value={query}
137          onChange={(e) => {
138            setQuery(e.target.value);
139            setActive(0);
140          }}
141          onKeyDown={(e) => {
142            if (e.key === "ArrowDown" || e.key === "ArrowUp") {
143              e.preventDefault();
144              setActive(step(cur, e.key === "ArrowDown" ? 1 : -1, shown.length));
145            } else if (e.key === "Home" || e.key === "End") {
146              e.preventDefault();
147              setActive(e.key === "Home" ? 0 : Math.max(0, shown.length - 1));
148            } else if (e.key === "Enter") {
149              e.preventDefault();
150              choose(activeCommand);
151            } else if ((e.ctrlKey || e.metaKey) && e.key.toLowerCase() === "k") {
152              e.preventDefault();
153              dlg.current?.close();
154            }
155          }}
156        />
157      </div>
158      <Listbox id={`${id}-list`} className="cap-cmd-list" mode="input" controlled aria-label="Commands" aria-busy={busy || undefined} hidden={shown.length === 0}>
159        {groups.map((g) => (
160          <OptionGroup label={g.group} key={g.group}>
161            {g.items.map((c) => (
162              <Option
163                key={c.id}
164                id={optionId(c)}
165                active={c === activeCommand}
166                hint={c.hint}
167                keys={c.shortcut ? <Caps spec={c.shortcut} /> : undefined}
168                onPointerMove={() => {
169                  const i = shown.indexOf(c);
170                  if (i !== cur) setActive(i);
171                }}
172                // The input keeps focus: a press on an option must not take it.
173                onPointerDown={(e) => e.preventDefault()}
174                onClick={() => choose(c)}
175              >
176                {c.label}
177              </Option>
178            ))}
179          </OptionGroup>
180        ))}
181      </Listbox>
182      <ListboxEmpty>{shown.length === 0 ? (busy ? SEARCHING : emptyText(query)) : ""}</ListboxEmpty>
183      <div className="cap-cmd-foot" aria-hidden="true">
184        <span>
185          <kbd>↑</kbd> <kbd>↓</kbd> move
186        </span>
187        <span>
188          <kbd>Enter</kbd> run
189        </span>
190        <span>
191          <kbd>Esc</kbd> close
192        </span>
193      </div>
194    </Dialog>
195  );
196}