@boxcustodia/library 2.0.0-alpha.2 → 2.0.0-alpha.20

package/src/hooks/use-hotkey/use-hotkey.stories.tsx

@@ -0,0 +1,321 @@
+import type { Meta, StoryObj } from "@storybook/react-vite";
+import { type ReactNode, useState } from "react";
+import { Kbd, KbdGroup } from "../../components";
+import { cn } from "../../lib";
+import { getHotkeyHandler, useHotkey } from "../use-hotkey";
+
+/**
+ * Bind keyboard shortcuts to handlers. `useHotkey` registers on `document`, so
+ * shortcuts fire regardless of which element has focus; `getHotkeyHandler`
+ * builds an element-scoped `onKeyDown` handler instead.
+ *
+ * **Two forms of `useHotkey`:**
+ * - Single binding — `useHotkey(keys, handler, options?)`. `keys` is a string
+ *   or string array sharing one handler (the handler fires if any matches).
+ * - Multiple bindings — `useHotkey(bindings)` where `bindings` is a list of
+ *   `[key, handler, options?]` tuples, each dispatched independently with its
+ *   own options.
+ *
+ * ```tsx
+ * useHotkey("mod+k", openPalette);
+ * useHotkey(["w", "ArrowUp"], moveUp);
+ * useHotkey([
+ *   ["mod+k", openPalette],
+ *   ["mod+s", save, { preventDefault: false }],
+ * ]);
+ * ```
+ *
+ * **Key syntax** — zero or more modifiers followed by the main key, joined with
+ * `+` (e.g. `"ctrl+shift+k"`). Literal modifiers are `shift`, `ctrl`, `alt`,
+ * `meta`. `mod` is platform-aware: it resolves to `meta` (⌘) on Apple devices
+ * and `ctrl` everywhere else — write the shortcut once and it adapts.
+ *
+ * **Matching is strict and exact.** A binding fires only when every required
+ * modifier is held and no other modifier is. `"a"` will not fire for `Ctrl+A`;
+ * `"ctrl+k"` will not fire for `Ctrl+Shift+K`. Strict `mod` also rejects the
+ * opposite platform's modifier (on Apple, `mod+k` matches ⌘+K but not Ctrl+K).
+ *
+ * **`getHotkeyHandler(bindings)`** returns an `onKeyDown` handler for a single
+ * element. It shares the same strict-modifier and `mod` behavior but applies no
+ * tag suppression — it has no `tagsToIgnore` and matches regardless of the
+ * target tag, including the `<input>` it is attached to. Use it for shortcuts
+ * that must work while a specific field is focused (e.g. ⌘/Ctrl+Enter to
+ * submit).
+ *
+ * ```tsx
+ * <input onKeyDown={getHotkeyHandler("mod+enter", submit)} />
+ * ```
+ *
+ * Handlers are read through a ref, so passing an inline function never
+ * re-attaches the listener. SSR-safe: no DOM access on the server.
+ */
+const meta: Meta = {
+  title: "hooks/useHotkey",
+};
+
+export default meta;
+type Story = StoryObj<typeof meta>;
+
+const isApple =
+  typeof navigator !== "undefined" &&
+  /Mac|iP(hone|ad|od)/.test(navigator.platform);
+const modLabel = isApple ? "⌘" : "Ctrl";
+
+const Stage = ({ children }: { children: ReactNode }) => (
+  <div className="flex h-52 w-80 items-center justify-center overflow-hidden rounded-md border border-input">
+    {children}
+  </div>
+);
+
+const generateRandomColor = () => {
+  const letters = "0123456789ABCDEF";
+  let color = "#";
+  for (let i = 0; i < 6; i++) {
+    color += letters[Math.floor(Math.random() * 16)];
+  }
+  return color;
+};
+
+/**
+ * Interactive demo combining several bindings:
+ * - `Ctrl+B` randomizes the color.
+ * - `Space` pulses a ring.
+ * - `WASD` or the arrow keys move the dot, using an array of keys on a single
+ *   handler that branches on `event.key`.
+ */
+export const Playground: Story = {
+  render: () => {
+    const [posX, setPosX] = useState(0);
+    const [posY, setPosY] = useState(0);
+    const [color, setColor] = useState("#333333");
+    const [pulse, setPulse] = useState(false);
+
+    useHotkey("ctrl+b", () => setColor(generateRandomColor()));
+
+    useHotkey(" ", () => {
+      setPulse(true);
+      setTimeout(() => setPulse(false), 300);
+    });
+
+    useHotkey(
+      ["w", "s", "a", "d", "ArrowUp", "ArrowDown", "ArrowLeft", "ArrowRight"],
+      (event) => {
+        const { key } = event;
+        if (["w", "ArrowUp"].includes(key)) return setPosY((y) => y - 20);
+        if (["s", "ArrowDown"].includes(key)) return setPosY((y) => y + 20);
+        if (["a", "ArrowLeft"].includes(key)) return setPosX((x) => x - 20);
+        if (["d", "ArrowRight"].includes(key)) return setPosX((x) => x + 20);
+      },
+    );
+
+    return (
+      <div className="space-y-4">
+        <div className="flex flex-wrap items-center gap-2 text-sm">
+          <KbdGroup>
+            <Kbd>Ctrl</Kbd>
+            <Kbd>B</Kbd>
+          </KbdGroup>
+          color · <Kbd>Space</Kbd> pulse ·{" "}
+          <KbdGroup>
+            <Kbd>W</Kbd>
+            <Kbd>A</Kbd>
+            <Kbd>S</Kbd>
+            <Kbd>D</Kbd>
+          </KbdGroup>
+          move
+        </div>
+        <Stage>
+          <div
+            className={cn(
+              "h-10 w-10 rounded-full transition-transform",
+              pulse && "ring ring-offset-2",
+            )}
+            style={{
+              backgroundColor: color,
+              transform: `translate(${posX}px, ${posY}px)`,
+            }}
+          />
+        </Stage>
+      </div>
+    );
+  },
+};
+
+/**
+ * Modifier matching is exact: `"ctrl+m"` fires only when Ctrl is held and
+ * Shift/Alt/Meta are not. Try pressing `M` alone or `Ctrl+Shift+M` — neither
+ * matches.
+ */
+export const KeyCombo: Story = {
+  render: () => {
+    const [count, setCount] = useState(0);
+    useHotkey("ctrl+m", () => setCount((c) => c + 1));
+    return (
+      <p className="text-sm">
+        Press <Kbd>Ctrl</Kbd> + <Kbd>M</Kbd> — matched {count} time(s)
+      </p>
+    );
+  },
+};
+
+/**
+ * `mod` is platform-aware: it resolves to `meta` (⌘) on Apple devices and
+ * `ctrl` everywhere else, so one binding works cross-platform. Matching stays
+ * strict — on a Mac, `mod+m` matches ⌘+M but not Ctrl+M.
+ */
+export const Mod: Story = {
+  render: () => {
+    const [count, setCount] = useState(0);
+    useHotkey("mod+m", () => setCount((c) => c + 1));
+    return (
+      <p className="text-sm">
+        Press <Kbd>{modLabel}</Kbd> + <Kbd>M</Kbd> — matched {count} time(s)
+      </p>
+    );
+  },
+};
+
+/**
+ * The array-of-tuples form binds several independent shortcuts in one call.
+ * Each `[key, handler, options?]` tuple dispatches on its own and can override
+ * options per binding (here `mod+s` opts out of `preventDefault`).
+ */
+export const MultipleBindings: Story = {
+  render: () => {
+    const [log, setLog] = useState<string[]>([]);
+    const push = (entry: string) => setLog((l) => [entry, ...l].slice(0, 5));
+
+    useHotkey([
+      ["mod+m", () => push("palette")],
+      ["mod+s", () => push("save"), { preventDefault: false }],
+    ]);
+
+    return (
+      <div className="space-y-3 text-sm">
+        <div className="flex flex-wrap items-center gap-2">
+          <KbdGroup>
+            <Kbd>{modLabel}</Kbd>
+            <Kbd>M</Kbd>
+          </KbdGroup>
+          palette ·
+          <KbdGroup>
+            <Kbd>{modLabel}</Kbd>
+            <Kbd>S</Kbd>
+          </KbdGroup>
+          save
+        </div>
+        <ul className="font-mono text-muted-foreground">
+          {log.map((entry, i) => (
+            <li key={`${entry}-${i}`}>{entry}</li>
+          ))}
+        </ul>
+      </div>
+    );
+  },
+};
+
+/**
+ * By default `useHotkey` skips events while a control in `tagsToIgnore`
+ * (`INPUT`, `TEXTAREA`, `SELECT`) is focused. Focus the input and press `S` —
+ * the counter stays put. Pass `tagsToIgnore: []` to let shortcuts fire during
+ * text entry, or `triggerOnContentEditable: true` for contentEditable regions.
+ */
+export const TagsToIgnore: Story = {
+  render: () => {
+    const [ignored, setIgnored] = useState(0);
+    const [always, setAlways] = useState(0);
+    useHotkey("s", () => setIgnored((c) => c + 1));
+    useHotkey("d", () => setAlways((c) => c + 1), { tagsToIgnore: [] });
+    return (
+      <div className="space-y-3 text-sm">
+        <p>
+          <Kbd>S</Kbd> (default) — matched {ignored} · <Kbd>D</Kbd>{" "}
+          (tagsToIgnore: []) — matched {always}
+        </p>
+        <input
+          placeholder="type here — S won't fire, D will"
+          className="w-full rounded-md border border-input px-3 py-1"
+        />
+      </div>
+    );
+  },
+};
+
+/**
+ * `getHotkeyHandler` builds an element-scoped `onKeyDown` handler. Unlike
+ * `useHotkey`, it applies no tag suppression, so it fires even on the `<input>`
+ * it is attached to — the canonical case for a submit shortcut while a field is
+ * focused. Press ⌘/Ctrl+Enter inside the input to submit.
+ */
+export const ElementScoped: Story = {
+  render: () => {
+    const [value, setValue] = useState("");
+    const [submitted, setSubmitted] = useState<string | null>(null);
+    return (
+      <div className="space-y-3 text-sm">
+        <input
+          value={value}
+          onChange={(e) => setValue(e.target.value)}
+          onKeyDown={getHotkeyHandler("mod+enter", () => {
+            setSubmitted(value);
+            setValue("");
+          })}
+          placeholder="type, then press mod+Enter"
+          className="w-full rounded-md border border-input px-3 py-1"
+        />
+        <p className="flex flex-wrap items-center gap-2">
+          <KbdGroup>
+            <Kbd>{modLabel}</Kbd>
+            <Kbd>Enter</Kbd>
+          </KbdGroup>
+          to submit — last: {submitted ?? "—"}
+        </p>
+      </div>
+    );
+  },
+};
+
+/**
+ * `watch: false` disables the binding without unmounting. Toggle it to start
+ * and stop listening at runtime.
+ */
+export const Disabled: Story = {
+  render: () => {
+    const [enabled, setEnabled] = useState(false);
+    const [count, setCount] = useState(0);
+    useHotkey("e", () => setCount((c) => c + 1), {
+      watch: enabled,
+    });
+    return (
+      <div className="space-y-3 text-sm">
+        <label className="flex items-center gap-2">
+          <input
+            type="checkbox"
+            checked={enabled}
+            onChange={(e) => setEnabled(e.target.checked)}
+          />
+          binding enabled
+        </label>
+        <p>
+          Press <Kbd>e</Kbd> — matched {count} time(s)
+        </p>
+      </div>
+    );
+  },
+};
+
+/**
+ * Bind to `keyup` instead of the default `keydown` via the `eventName` option
+ * — the handler fires when the key is released.
+ */
+export const OnKeyUp: Story = {
+  render: () => {
+    const [count, setCount] = useState(0);
+    useHotkey("u", () => setCount((c) => c + 1), { eventName: "keyup" });
+    return (
+      <p className="text-sm">
+        Release <Kbd>U</Kbd> — matched {count} time(s)
+      </p>
+    );
+  },
+};

package/src/hooks/use-hotkey/use-hotkey.test.tsx

@@ -0,0 +1,388 @@
+import { fireEvent, render, screen, waitFor } from "@testing-library/react";
+import { afterEach, describe, expect, it, vi } from "vitest";
+import { keyboard } from "../../utils/tests/keyboard";
+import { getHotkeyHandler, type HotkeyOptions, useHotkey } from "../use-hotkey";
+
+afterEach(() => {
+  vi.unstubAllGlobals();
+});
+
+describe("useHotkey hook", () => {
+  it("should be defined", () => {
+    expect(useHotkey).toBeDefined();
+  });
+
+  it("calls handler on a matching keydown event", async () => {
+    const handler = vi.fn();
+    const TestComponent = () => {
+      useHotkey("a", handler);
+      return null;
+    };
+
+    render(<TestComponent />);
+    keyboard(document, { key: "a" });
+
+    await waitFor(() => {
+      expect(handler).toHaveBeenCalledTimes(1);
+    });
+  });
+
+  it("matches an exact key combination", async () => {
+    const handler = vi.fn();
+    const TestComponent = () => {
+      useHotkey("ctrl+a", handler);
+      return null;
+    };
+
+    render(<TestComponent />);
+    keyboard(document, { key: "a", ctrlKey: true });
+
+    await waitFor(() => {
+      expect(handler).toHaveBeenCalledTimes(1);
+    });
+  });
+
+  it("rejects when an extra modifier is pressed", async () => {
+    const handler = vi.fn();
+    const TestComponent = () => {
+      useHotkey("ctrl+a", handler);
+      return null;
+    };
+
+    render(<TestComponent />);
+    keyboard(document, { key: "a", ctrlKey: true, shiftKey: true });
+
+    await waitFor(() => {
+      expect(handler).not.toHaveBeenCalled();
+    });
+  });
+
+  it("calls preventDefault by default", async () => {
+    const handler = vi.fn();
+    const TestComponent = () => {
+      useHotkey("b", handler);
+      return null;
+    };
+
+    render(<TestComponent />);
+    const event = new KeyboardEvent("keydown", { key: "b" });
+    Object.defineProperty(event, "preventDefault", { value: vi.fn() });
+    document.dispatchEvent(event);
+
+    await waitFor(() => {
+      expect(event.preventDefault).toHaveBeenCalled();
+    });
+  });
+
+  it("does not call preventDefault when preventDefault is false", async () => {
+    const handler = vi.fn();
+    const options: HotkeyOptions = { preventDefault: false };
+    const TestComponent = () => {
+      useHotkey("c", handler, options);
+      return null;
+    };
+
+    render(<TestComponent />);
+    const event = new KeyboardEvent("keydown", { key: "c" });
+    Object.defineProperty(event, "preventDefault", { value: vi.fn() });
+    document.dispatchEvent(event);
+
+    await waitFor(() => {
+      expect(event.preventDefault).not.toHaveBeenCalled();
+    });
+  });
+
+  it("shares one handler across an array of keys", async () => {
+    const handler = vi.fn();
+    const TestComponent = () => {
+      useHotkey(["d", "e"], handler);
+      return null;
+    };
+
+    render(<TestComponent />);
+    keyboard(document, { key: "d" });
+    keyboard(document, { key: "e" });
+
+    await waitFor(() => {
+      expect(handler).toHaveBeenCalledTimes(2);
+    });
+  });
+
+  it("does not call handler when watch is false", async () => {
+    const handler = vi.fn();
+    const TestComponent = () => {
+      useHotkey("f", handler, { watch: false });
+      return null;
+    };
+
+    render(<TestComponent />);
+    keyboard(document, { key: "f" });
+
+    await waitFor(() => {
+      expect(handler).not.toHaveBeenCalled();
+    });
+  });
+
+  it("listens on keyup when eventName is 'keyup'", async () => {
+    const handler = vi.fn();
+    const TestComponent = () => {
+      useHotkey("g", handler, { eventName: "keyup" });
+      return null;
+    };
+
+    render(<TestComponent />);
+
+    keyboard(document, { key: "g" }, "keydown");
+    await waitFor(() => {
+      expect(handler).not.toHaveBeenCalled();
+    });
+
+    keyboard(document, { key: "g" }, "keyup");
+    await waitFor(() => {
+      expect(handler).toHaveBeenCalledTimes(1);
+    });
+  });
+
+  describe("array-of-tuples form", () => {
+    it("dispatches each binding independently", async () => {
+      const handlerA = vi.fn();
+      const handlerB = vi.fn();
+      const TestComponent = () => {
+        useHotkey([
+          ["a", handlerA],
+          ["b", handlerB],
+        ]);
+        return null;
+      };
+
+      render(<TestComponent />);
+      keyboard(document, { key: "b" });
+
+      await waitFor(() => {
+        expect(handlerB).toHaveBeenCalledTimes(1);
+        expect(handlerA).not.toHaveBeenCalled();
+      });
+    });
+
+    it("honors per-binding preventDefault override", async () => {
+      const handler = vi.fn();
+      const TestComponent = () => {
+        useHotkey([["a", handler, { preventDefault: false }]]);
+        return null;
+      };
+
+      render(<TestComponent />);
+      const event = new KeyboardEvent("keydown", { key: "a" });
+      Object.defineProperty(event, "preventDefault", { value: vi.fn() });
+      document.dispatchEvent(event);
+
+      await waitFor(() => {
+        expect(handler).toHaveBeenCalledTimes(1);
+        expect(event.preventDefault).not.toHaveBeenCalled();
+      });
+    });
+  });
+
+  describe("platform-aware mod", () => {
+    it("matches meta (⌘) and rejects ctrl on Apple", async () => {
+      vi.stubGlobal("navigator", { platform: "MacIntel" });
+      const handler = vi.fn();
+      const TestComponent = () => {
+        useHotkey("mod+k", handler);
+        return null;
+      };
+
+      render(<TestComponent />);
+
+      keyboard(document, { key: "k", ctrlKey: true });
+      await waitFor(() => {
+        expect(handler).not.toHaveBeenCalled();
+      });
+
+      keyboard(document, { key: "k", metaKey: true });
+      await waitFor(() => {
+        expect(handler).toHaveBeenCalledTimes(1);
+      });
+    });
+
+    it("matches ctrl and rejects meta on non-Apple", async () => {
+      vi.stubGlobal("navigator", { platform: "Win32" });
+      const handler = vi.fn();
+      const TestComponent = () => {
+        useHotkey("mod+k", handler);
+        return null;
+      };
+
+      render(<TestComponent />);
+
+      keyboard(document, { key: "k", metaKey: true });
+      await waitFor(() => {
+        expect(handler).not.toHaveBeenCalled();
+      });
+
+      keyboard(document, { key: "k", ctrlKey: true });
+      await waitFor(() => {
+        expect(handler).toHaveBeenCalledTimes(1);
+      });
+    });
+  });
+
+  describe("tag and contentEditable suppression", () => {
+    it("does not fire when the event originates from an input field", async () => {
+      const handler = vi.fn();
+      const TestComponent = () => {
+        useHotkey("z", handler);
+        return <input data-testid="input" />;
+      };
+
+      render(<TestComponent />);
+      const input = screen.getByTestId("input");
+      input.dispatchEvent(
+        new KeyboardEvent("keydown", { key: "z", bubbles: true }),
+      );
+
+      await waitFor(() => {
+        expect(handler).not.toHaveBeenCalled();
+      });
+    });
+
+    it("fires from an input when tagsToIgnore is empty", async () => {
+      const handler = vi.fn();
+      const TestComponent = () => {
+        useHotkey("z", handler, { tagsToIgnore: [] });
+        return <input data-testid="input" />;
+      };
+
+      render(<TestComponent />);
+      const input = screen.getByTestId("input");
+      input.dispatchEvent(
+        new KeyboardEvent("keydown", { key: "z", bubbles: true }),
+      );
+
+      await waitFor(() => {
+        expect(handler).toHaveBeenCalledTimes(1);
+      });
+    });
+
+    it("fires from a contentEditable target when triggerOnContentEditable is true", async () => {
+      const handler = vi.fn();
+      const TestComponent = () => {
+        useHotkey("z", handler, { triggerOnContentEditable: true });
+        return (
+          <div
+            contentEditable
+            data-testid="editable"
+            suppressContentEditableWarning
+          />
+        );
+      };
+
+      render(<TestComponent />);
+      const editable = screen.getByTestId("editable");
+      editable.dispatchEvent(
+        new KeyboardEvent("keydown", { key: "z", bubbles: true }),
+      );
+
+      await waitFor(() => {
+        expect(handler).toHaveBeenCalledTimes(1);
+      });
+    });
+  });
+
+  describe("lifecycle", () => {
+    it("removes the document listener on unmount", async () => {
+      const handler = vi.fn();
+      const TestComponent = () => {
+        useHotkey("u", handler);
+        return null;
+      };
+
+      const { unmount } = render(<TestComponent />);
+      unmount();
+      keyboard(document, { key: "u" });
+
+      await waitFor(() => {
+        expect(handler).not.toHaveBeenCalled();
+      });
+    });
+
+    it("invokes the latest handler after a re-render without re-binding", async () => {
+      const first = vi.fn();
+      const second = vi.fn();
+      const TestComponent = ({ handler }: { handler: () => void }) => {
+        useHotkey("r", handler);
+        return null;
+      };
+
+      const { rerender } = render(<TestComponent handler={first} />);
+      rerender(<TestComponent handler={second} />);
+
+      keyboard(document, { key: "r" });
+
+      await waitFor(() => {
+        expect(second).toHaveBeenCalledTimes(1);
+        expect(first).not.toHaveBeenCalled();
+      });
+    });
+  });
+});
+
+describe("getHotkeyHandler", () => {
+  it("returns a handler that fires on a matching key", async () => {
+    const handler = vi.fn();
+    const TestComponent = () => (
+      <input
+        data-testid="scoped"
+        onKeyDown={getHotkeyHandler([["a", handler]])}
+      />
+    );
+
+    render(<TestComponent />);
+    fireEvent.keyDown(screen.getByTestId("scoped"), { key: "a" });
+
+    await waitFor(() => {
+      expect(handler).toHaveBeenCalledTimes(1);
+    });
+  });
+
+  it("shares mod behavior (Ctrl+K on non-Apple)", async () => {
+    vi.stubGlobal("navigator", { platform: "Win32" });
+    const handler = vi.fn();
+    const TestComponent = () => (
+      <input
+        data-testid="scoped"
+        onKeyDown={getHotkeyHandler([["mod+k", handler]])}
+      />
+    );
+
+    render(<TestComponent />);
+    fireEvent.keyDown(screen.getByTestId("scoped"), {
+      key: "k",
+      ctrlKey: true,
+    });
+
+    await waitFor(() => {
+      expect(handler).toHaveBeenCalledTimes(1);
+    });
+  });
+
+  it("does NOT suppress the input tag it is attached to", async () => {
+    const handler = vi.fn();
+    const TestComponent = () => (
+      <input
+        data-testid="scoped"
+        onKeyDown={getHotkeyHandler([["mod+enter", handler]])}
+      />
+    );
+
+    render(<TestComponent />);
+    fireEvent.keyDown(screen.getByTestId("scoped"), {
+      key: "Enter",
+      ctrlKey: true,
+    });
+
+    await waitFor(() => {
+      expect(handler).toHaveBeenCalledTimes(1);
+    });
+  });
+});