components/shortcuts/shortcuts.react.tsx

Functions

Imports

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

Source

1import { Fragment, useCallback, useEffect, useId, useRef, useState } from "react";
2import { Dialog, DialogBody, DialogFooter, DialogHeader, DialogTitle } from "../dialog/dialog.react.tsx";
3import { SINGLE_KEYS_NOTE, grouped, keyCaps, modifiedShortcutFor, register, setSheetOpener, setSingleKeys, singleKeysOn, type Shortcut } from "./shortcuts.ts";
4
5// Registers a shortcut while the component is mounted. The latest `run` is always the one
6// called, so passing a new function each render does not re-register.
7export function useShortcut(key: string | string[], run: (e: KeyboardEvent) => void, opts: { label?: string; about?: string; group?: string; when?: () => boolean } = {}): void {
8  const latest = useRef(run);
9  latest.current = run;
10  const when = useRef(opts.when);
11  when.current = opts.when;
12  const keyId = Array.isArray(key) ? key.join("|") : key;
13  useEffect(() => {
14    const s: Shortcut = {
15      key,
16      label: opts.label ?? keyId,
17      about: opts.about,
18      group: opts.group ?? "Other",
19      run: (e) => latest.current(e),
20      when: () => (when.current ? when.current() : true),
21    };
22    return register(s);
23    // The key, label and group identify the registration; run and when are read live.
24  }, [keyId, opts.label, opts.about, opts.group]);
25}
26
27// A shortcut's key caps, "or" between alternatives (the command menu shows them too).
28export function Keys({ spec }: { spec: string | string[] }) {
29  const specs = Array.isArray(spec) ? spec : [spec];
30  return (
31    <>
32      {specs.map((s, i) => (
33        <Fragment key={s}>
34          {i > 0 ? " or " : null}
35          {keyCaps(s).map((cap, j) => (
36            <Fragment key={`${cap}-${j}`}>
37              {j > 0 ? " " : null}
38              <kbd>{cap}</kbd>
39            </Fragment>
40          ))}
41        </Fragment>
42      ))}
43    </>
44  );
45}
46
47export interface ShortcutSheetProps {
48  open: boolean;
49  onOpenChange: (open: boolean) => void;
50}
51
52// The "?" sheet: every registered shortcut by group, and the switch for single keys. While
53// mounted it is the sheet "?" opens.
54export function ShortcutSheet({ open, onOpenChange }: ShortcutSheetProps) {
55  const id = useId();
56  const dlg = useRef<HTMLDialogElement | null>(null);
57  const closeButton = useRef<HTMLElement | null>(null);
58  const [single, setSingle] = useState(true);
59  const [groups, setGroups] = useState<ReturnType<typeof grouped>>([]);
60
61  useEffect(() => {
62    setSheetOpener(() => onOpenChange(true));
63    return () => setSheetOpener(null);
64  }, [onOpenChange]);
65
66  useEffect(() => {
67    const sync = () => setSingle(singleKeysOn());
68    sync();
69    document.addEventListener("cap-single-keys", sync);
70    return () => document.removeEventListener("cap-single-keys", sync);
71  }, []);
72
73  useEffect(() => {
74    if (open) setGroups(grouped());
75  }, [open]);
76
77  // Focus starts on Close: the dialog's own Close button, found once the markup is there.
78  const setRef = useCallback((el: HTMLDialogElement | null) => {
79    dlg.current = el;
80    closeButton.current = el?.querySelector<HTMLElement>("[data-cap-part='close']") ?? null;
81  }, []);
82
83  return (
84    <Dialog
85      ref={setRef}
86      className="cap-keys"
87      open={open}
88      onOpenChange={onOpenChange}
89      placement="center"
90      size="md"
91      initialFocus={closeButton}
92      aria-labelledby={`${id}-title`}
93      // A shortcut with Ctrl or Cmd still works over the sheet: the sheet closes, then it runs.
94      onKeyDown={(e) => {
95        const hit = modifiedShortcutFor(e.nativeEvent);
96        if (!hit) return;
97        e.preventDefault();
98        dlg.current?.close();
99        hit.run(e.nativeEvent);
100      }}
101    >
102      <DialogHeader divider>
103        <DialogTitle id={`${id}-title`}>Keyboard shortcuts</DialogTitle>
104      </DialogHeader>
105      <DialogBody className="cap-keys-body" data-cap-part="keys-list">
106        {groups.map((g) => (
107          <div className="cap-keys-group" key={g.group}>
108            <h3 className="cap-keys-group-title">{g.group}</h3>
109            <dl className="cap-keys-list">
110              {g.items.map((s, i) => (
111                <div key={`${s.label}-${i}`}>
112                  <dt>
113                    <Keys spec={s.key} />
114                  </dt>
115                  <dd>
116                    {s.label}
117                    {s.about ? <span className="cap-keys-about">{s.about}</span> : null}
118                  </dd>
119                </div>
120              ))}
121            </dl>
122          </div>
123        ))}
124      </DialogBody>
125      <DialogFooter align="start">
126        <div className="cap-keys-foot">
127          <label className="cap-switch">
128            <input type="checkbox" role="switch" data-cap-part="single-keys" aria-describedby={`${id}-note`} checked={single} onChange={(e) => setSingleKeys(e.target.checked)} />
129            <span>Single-key shortcuts</span>
130            <span className="cap-switch-state" aria-hidden="true">
131              {single ? "On" : "Off"}
132            </span>
133          </label>
134          <p className="cap-keys-note" id={`${id}-note`}>
135            {SINGLE_KEYS_NOTE}
136          </p>
137        </div>
138      </DialogFooter>
139    </Dialog>
140  );
141}