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

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

@@ -1,8 +1,54 @@
-import { Meta, StoryObj } from "@storybook/react-vite";
-import { HTMLProps, ReactNode, useState } from "react";
+import type { Meta, StoryObj } from "@storybook/react-vite";
+import { type ReactNode, useState } from "react";
+import { Kbd, KbdGroup } from "../../components";
 import { cn } from "../../lib";
-import { useHotkey } from "../use-hotkey";
+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",
 };
@@ -10,6 +56,17 @@ const meta: Meta = {
 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 = "#";
@@ -19,78 +76,31 @@ const generateRandomColor = () => {
   return color;
 };
 
-const Kbd = (props: HTMLProps<HTMLDivElement>) => (
-  <kbd
-    {...props}
-    className="inline-block px-3 py-1 text-sm font-semibold text-gray-800 bg-gray-200 border rounded-md shadow-inner border-input"
-  />
-);
-
-const Wrapper = ({ children }: { children: ReactNode }) => (
-  <div>
-    <div className="space-y-2">
-      <div className="flex gap-2">
-        <span>Usa</span>
-        <Kbd>C</Kbd>
-        <span>+</span>
-        <Kbd>R</Kbd>
-        <span>para cambiar el color</span>
-      </div>
-      <div className="flex gap-2">
-        <span>Usa</span>
-        <Kbd>w</Kbd>
-        <Kbd>a</Kbd>
-        <Kbd>s</Kbd>
-        <Kbd>d</Kbd>
-        <span>o</span>
-        <Kbd>&#8593;</Kbd>
-        <Kbd>&#8592;</Kbd>
-        <Kbd>&#8595;</Kbd>
-        <Kbd>&#8594;</Kbd>
-        <span>Para moverte</span>
-      </div>
-    </div>
-    <div className="flex items-center justify-center w-80 h-52">{children}</div>
-  </div>
-);
-
 /**
- * Opciones
- *
- * ```tsx
- * type HotkeyOptions = {
- * // Es el evento que se va a utilizar; Keydown, Keyup, Keypress
- * eventName?: HotkeyEventName;
- * @default "keydown"
- * // si se debe prevenir los comandos por defecto del navegador
- * preventDefault?: boolean;
- * @default true
- * // si los comandos se deberían ejecutar mientras el usuario está escribiendo en un input o textarea
- * ignoreInputFields?: boolean;
- * @default false
- * };
- * ```
- **/
-export const Default: Story = {
+ * 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 [spacePressed, setSpacePressed] = useState(false);
+    const [pulse, setPulse] = useState(false);
 
-    useHotkey(["ctrl+r"], () => setColor(generateRandomColor()));
+    useHotkey("ctrl+b", () => setColor(generateRandomColor()));
 
     useHotkey(" ", () => {
-      setSpacePressed(true);
-      setTimeout(() => {
-        setSpacePressed(false);
-      }, 300);
+      setPulse(true);
+      setTimeout(() => setPulse(false), 300);
     });
 
     useHotkey(
       ["w", "s", "a", "d", "ArrowUp", "ArrowDown", "ArrowLeft", "ArrowRight"],
-      (e) => {
-        const { key } = e;
+      (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);
@@ -99,18 +109,213 @@ export const Default: Story = {
     );
 
     return (
-      <Wrapper>
-        <div
-          className={cn(
-            "w-10 h-10 rounded-full",
-            spacePressed && "ring ring-offset-2",
-          )}
-          style={{
-            backgroundColor: color,
-            transform: `translate(${posX}px, ${posY}px)`,
-          }}
+      <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"
         />
-      </Wrapper>
+        <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>
     );
   },
 };