@multicomma/arkcn 0.1.2 → 0.1.3

package/registry/items/hooks/use-mobile.json

@@ -5,6 +5,7 @@
   "exports": [
     "useIsMobile"
   ],
+  "parts": [],
   "dependencies": {},
   "registryDependencies": [],
   "files": [

package/registry/items/hotkeys.json

@@ -12,6 +12,104 @@
     "useHotkeys",
     "useHotkeysDialog"
   ],
+  "parts": [
+    {
+      "name": "HotkeyKbd",
+      "props": [
+        {
+          "name": "hotkey",
+          "type": "string",
+          "required": true,
+          "description": "Key combination such as `mod+k`, or a sequence such as `g d`.",
+          "from": "arkcn"
+        },
+        {
+          "name": "children",
+          "type": "ReactNode",
+          "required": false,
+          "description": "Content rendered inside the part.",
+          "from": "@types/react"
+        },
+        {
+          "name": "className",
+          "type": "string",
+          "required": false,
+          "description": "Extra classes merged into the part's own classes with `cn`.",
+          "from": "@types/react"
+        },
+        {
+          "name": "style",
+          "type": "CSSProperties",
+          "required": false,
+          "description": "Inline styles applied to the rendered element.",
+          "from": "@types/react"
+        }
+      ]
+    },
+    {
+      "name": "HotkeysDialog",
+      "props": [
+        {
+          "name": "children",
+          "type": "ReactNode",
+          "required": false,
+          "description": "Content rendered inside the part.",
+          "from": "arkcn"
+        },
+        {
+          "name": "className",
+          "type": "string",
+          "required": false,
+          "description": "Extra classes merged into the part's own classes with `cn`.",
+          "from": "arkcn"
+        },
+        {
+          "name": "description",
+          "type": "ReactNode",
+          "required": false,
+          "default": "\"Shortcuts work anywhere on the page except while typing.\"",
+          "description": "Description text.",
+          "from": "arkcn"
+        },
+        {
+          "name": "title",
+          "type": "ReactNode",
+          "required": false,
+          "default": "\"Keyboard shortcuts\"",
+          "description": "Title text.",
+          "from": "arkcn"
+        }
+      ]
+    },
+    {
+      "name": "HotkeysProvider",
+      "props": [
+        {
+          "name": "children",
+          "type": "ReactNode",
+          "required": true,
+          "description": "Content rendered inside the part.",
+          "from": "arkcn"
+        },
+        {
+          "name": "dialogHotkey",
+          "type": "string | null",
+          "required": false,
+          "default": "\"?\"",
+          "description": "Opens the shortcuts dialog; `null` disables it.",
+          "from": "arkcn"
+        },
+        {
+          "name": "sequenceTimeout",
+          "type": "number",
+          "required": false,
+          "default": "1000",
+          "description": "Milliseconds allowed between keys of a sequence.",
+          "from": "arkcn"
+        }
+      ]
+    }
+  ],
   "dependencies": {},
   "registryDependencies": [
     "dialog",
@@ -21,7 +119,7 @@
   "files": [
     {
       "path": "components/ui/hotkeys.tsx",
-      "content": "\"use client\"\n\nimport * as React from \"react\"\nimport { cn } from \"@/lib/utils\"\nimport { Dialog, DialogContent, DialogDescription, DialogHeader, DialogTitle } from \"@/components/ui/dialog\"\nimport { Kbd, KbdGroup } from \"@/components/ui/kbd\"\n\n/* -------------------------------- parsing -------------------------------- */\n\nconst isMac = () => typeof navigator !== \"undefined\" && /mac|iphone|ipad|ipod/i.test(navigator.platform)\n\ntype Chord = { key: string; mod: boolean; ctrl: boolean; meta: boolean; alt: boolean; shift: boolean }\n\nconst keyAliases: Record<string, string> = {\n  esc: \"escape\",\n  return: \"enter\",\n  space: \" \",\n  up: \"arrowup\",\n  down: \"arrowdown\",\n  left: \"arrowleft\",\n  right: \"arrowright\",\n  plus: \"+\",\n  del: \"delete\",\n}\n\n/** \"mod+shift+k\" → chord; \"g d\" → sequence of chords. */\nfunction parseHotkey(hotkey: string): Chord[] {\n  return hotkey\n    .trim()\n    .split(/\\s+/)\n    .map((part) => {\n      const tokens = part.split(\"+\").map((t) => t.toLowerCase())\n      // \"+\" itself is written as \"plus\"\n      const key = tokens.pop() ?? \"\"\n      const chord: Chord = {\n        key: keyAliases[key] ?? key,\n        mod: false,\n        ctrl: false,\n        meta: false,\n        alt: false,\n        shift: false,\n      }\n      for (const t of tokens) {\n        if (t === \"mod\" || t === \"cmd\" || t === \"command\") chord.mod = true\n        else if (t === \"ctrl\" || t === \"control\") chord.ctrl = true\n        else if (t === \"meta\" || t === \"win\" || t === \"super\") chord.meta = true\n        else if (t === \"alt\" || t === \"option\") chord.alt = true\n        else if (t === \"shift\") chord.shift = true\n      }\n      return chord\n    })\n}\n\nfunction matchesChord(event: KeyboardEvent, chord: Chord, mac: boolean) {\n  const key = event.key.length === 1 ? event.key.toLowerCase() : event.key.toLowerCase()\n  if (key !== chord.key) return false\n  const wantMeta = chord.meta || (chord.mod && mac)\n  const wantCtrl = chord.ctrl || (chord.mod && !mac)\n  if (event.metaKey !== wantMeta || event.ctrlKey !== wantCtrl || event.altKey !== chord.alt) return false\n  // Punctuation like \"?\" already implies Shift on most layouts, so only enforce Shift for letters.\n  const letter = /^[a-z0-9]$/.test(chord.key) || chord.key.length > 1\n  if (letter && event.shiftKey !== chord.shift) return false\n  return true\n}\n\nconst symbol: Record<string, string> = {\n  mod: \"⌘\",\n  meta: \"⌘\",\n  ctrl: \"⌃\",\n  alt: \"⌥\",\n  shift: \"⇧\",\n  enter: \"↵\",\n  escape: \"Esc\",\n  backspace: \"⌫\",\n  delete: \"⌦\",\n  arrowup: \"↑\",\n  arrowdown: \"↓\",\n  arrowleft: \"←\",\n  arrowright: \"→\",\n  \" \": \"Space\",\n  tab: \"Tab\",\n}\nconst winSymbol: Record<string, string> = {\n  ...symbol,\n  mod: \"Ctrl\",\n  meta: \"Win\",\n  ctrl: \"Ctrl\",\n  alt: \"Alt\",\n  shift: \"Shift\",\n}\n\n/** Platform-aware key labels: \"mod+k\" → [\"⌘\", \"K\"] on Mac, [\"Ctrl\", \"K\"] elsewhere. Sequences give one array per chord. */\nfunction formatHotkey(hotkey: string, mac = isMac()): string[][] {\n  const table = mac ? symbol : winSymbol\n  return parseHotkey(hotkey).map((chord) => {\n    const parts: string[] = []\n    if (chord.ctrl) parts.push(table.ctrl)\n    if (chord.alt) parts.push(table.alt)\n    if (chord.shift) parts.push(table.shift)\n    if (chord.mod) parts.push(table.mod)\n    if (chord.meta && !chord.mod) parts.push(table.meta)\n    parts.push(table[chord.key] ?? (chord.key.length === 1 ? chord.key.toUpperCase() : chord.key))\n    return parts\n  })\n}\n\n/* -------------------------------- registry ------------------------------- */\n\ntype HotkeyEntry = {\n  id: string\n  hotkey: string\n  label: string\n  group: string\n  enabled: boolean\n  /** Fire even while typing in an input, textarea, or contenteditable. */\n  allowInInput: boolean\n  handler: (event: KeyboardEvent) => void\n}\n\ntype HotkeysContextValue = {\n  entries: HotkeyEntry[]\n  register: (entry: HotkeyEntry) => () => void\n  dialogOpen: boolean\n  setDialogOpen: (open: boolean) => void\n}\n\nconst HotkeysContext = React.createContext<HotkeysContextValue | null>(null)\n\nfunction useHotkeysContext() {\n  const ctx = React.useContext(HotkeysContext)\n  if (!ctx) throw new Error(\"Hotkeys parts must be used inside <HotkeysProvider>\")\n  return ctx\n}\n\nconst isEditable = (target: EventTarget | null) => {\n  const el = target as HTMLElement | null\n  if (!el || !(\"tagName\" in el)) return false\n  const tag = el.tagName\n  return tag === \"INPUT\" || tag === \"TEXTAREA\" || tag === \"SELECT\" || el.isContentEditable\n}\n\n/**\n * One document-level keydown listener for every registered hotkey. Supports chords\n * (\"mod+k\"), sequences (\"g d\", one second between keys), and a built-in \"?\" that opens\n * `HotkeysDialog` when one is rendered.\n */\nfunction HotkeysProvider({\n  children,\n  dialogHotkey = \"?\",\n  sequenceTimeout = 1000,\n}: {\n  children: React.ReactNode\n  /** Opens the shortcuts dialog; `null` disables it. */\n  dialogHotkey?: string | null\n  sequenceTimeout?: number\n}) {\n  const [entries, setEntries] = React.useState<HotkeyEntry[]>([])\n  const [dialogOpen, setDialogOpen] = React.useState(false)\n  const entriesRef = React.useRef(entries)\n  entriesRef.current = entries\n  const buffer = React.useRef<{ keys: KeyboardEvent[]; at: number }>({ keys: [], at: 0 })\n\n  const register = React.useCallback((entry: HotkeyEntry) => {\n    setEntries((prev) => [...prev.filter((e) => e.id !== entry.id), entry])\n    return () => setEntries((prev) => prev.filter((e) => e.id !== entry.id))\n  }, [])\n\n  const mac = React.useMemo(isMac, [])\n  React.useEffect(() => {\n    const down = (event: KeyboardEvent) => {\n      if (event.defaultPrevented || event.isComposing) return\n      if ([\"Shift\", \"Control\", \"Alt\", \"Meta\"].includes(event.key)) return\n      const editing = isEditable(event.target)\n      const now = Date.now()\n      const buf = buffer.current\n      if (now - buf.at > sequenceTimeout) buf.keys = []\n      buf.keys.push(event)\n      buf.at = now\n      if (buf.keys.length > 4) buf.keys.shift()\n\n      const candidates = [...entriesRef.current]\n      if (dialogHotkey) {\n        candidates.push({\n          id: \"hotkeys:dialog\",\n          hotkey: dialogHotkey,\n          label: \"Keyboard shortcuts\",\n          group: \"General\",\n          enabled: true,\n          allowInInput: false,\n          handler: () => setDialogOpen((open) => !open),\n        })\n      }\n      let partial = false\n      for (const entry of candidates) {\n        if (!entry.enabled || (editing && !entry.allowInInput)) continue\n        const chords = parseHotkey(entry.hotkey)\n        const tail = buf.keys.slice(-chords.length)\n        if (tail.length === chords.length && chords.every((c, i) => matchesChord(tail[i], c, mac))) {\n          event.preventDefault()\n          buf.keys = []\n          entry.handler(event)\n          return\n        }\n        // Is the buffer a prefix of a longer sequence? Then keep it.\n        if (chords.length > 1 && buf.keys.length < chords.length) {\n          const head = chords.slice(0, buf.keys.length)\n          if (head.every((c, i) => matchesChord(buf.keys[i], c, mac))) partial = true\n        }\n      }\n      if (!partial) buf.keys = []\n    }\n    document.addEventListener(\"keydown\", down)\n    return () => document.removeEventListener(\"keydown\", down)\n  }, [dialogHotkey, sequenceTimeout, mac])\n\n  const ctx = React.useMemo<HotkeysContextValue>(\n    () => ({ entries, register, dialogOpen, setDialogOpen }),\n    [entries, register, dialogOpen]\n  )\n  return <HotkeysContext.Provider value={ctx}>{children}</HotkeysContext.Provider>\n}\n\n/** Register a hotkey for the lifetime of the component. Listed in `HotkeysDialog` when it has a label. */\nfunction useHotkey(\n  hotkey: string,\n  handler: (event: KeyboardEvent) => void,\n  options: { label?: string; group?: string; enabled?: boolean; allowInInput?: boolean } = {}\n) {\n  const { register } = useHotkeysContext()\n  const { label = \"\", group = \"General\", enabled = true, allowInInput = false } = options\n  const id = React.useId()\n  const handlerRef = React.useRef(handler)\n  handlerRef.current = handler\n  React.useEffect(\n    () =>\n      register({\n        id,\n        hotkey,\n        label,\n        group,\n        enabled,\n        allowInInput,\n        handler: (event) => handlerRef.current(event),\n      }),\n    [register, id, hotkey, label, group, enabled, allowInInput]\n  )\n}\n\n/** Every registered hotkey with a label, grouped, for rendering a cheat sheet. */\nfunction useHotkeys() {\n  const { entries } = useHotkeysContext()\n  return React.useMemo(() => {\n    const groups = new Map<string, HotkeyEntry[]>()\n    for (const e of entries) {\n      if (!e.label) continue\n      const list = groups.get(e.group) ?? []\n      list.push(e)\n      groups.set(e.group, list)\n    }\n    return Array.from(groups, ([group, hotkeys]) => ({ group, hotkeys }))\n  }, [entries])\n}\n\n/* ---------------------------------- parts -------------------------------- */\n\n/** Renders a hotkey as Kbd caps (\"mod+k\" → ⌘ K; \"g d\" → G then D). */\nfunction HotkeyKbd({ hotkey, className, ...props }: React.ComponentProps<\"span\"> & { hotkey: string }) {\n  const chords = formatHotkey(hotkey)\n  return (\n    <span data-slot=\"hotkey-kbd\" className={cn(\"inline-flex items-center gap-1\", className)} {...props}>\n      {chords.map((keys, i) => (\n        <React.Fragment key={i}>\n          {i > 0 && <span className=\"text-xs text-muted-foreground\">then</span>}\n          <KbdGroup>\n            {keys.map((k, j) => (\n              <Kbd key={j}>{k}</Kbd>\n            ))}\n          </KbdGroup>\n        </React.Fragment>\n      ))}\n    </span>\n  )\n}\n\n/** The shortcuts cheat sheet. Opens from the provider's `dialogHotkey` (\"?\" by default) or `useHotkeysDialog()`. */\nfunction HotkeysDialog({\n  title = \"Keyboard shortcuts\",\n  description = \"Shortcuts work anywhere on the page except while typing.\",\n  children,\n  className,\n}: {\n  title?: React.ReactNode\n  description?: React.ReactNode\n  children?: React.ReactNode\n  className?: string\n}) {\n  const { dialogOpen, setDialogOpen } = useHotkeysContext()\n  const registered = useHotkeys()\n  const groups = React.useMemo(() => {\n    const self = { id: \"hotkeys:dialog\", hotkey: \"?\", label: \"Show this dialog\" }\n    const general = registered.find((g) => g.group === \"General\")\n    if (general) return registered.map((g) => (g === general ? { ...g, hotkeys: [...g.hotkeys, self] } : g))\n    return [...registered, { group: \"General\", hotkeys: [self] }]\n  }, [registered])\n  return (\n    <Dialog open={dialogOpen} onOpenChange={({ open }) => setDialogOpen(open)}>\n      <DialogContent data-slot=\"hotkeys-dialog\" className={cn(\"sm:max-w-lg\", className)}>\n        <DialogHeader>\n          <DialogTitle>{title}</DialogTitle>\n          <DialogDescription>{description}</DialogDescription>\n        </DialogHeader>\n        <div className=\"grid gap-5 sm:grid-cols-2\">\n          {groups.map(({ group, hotkeys }) => (\n            <div key={group} data-slot=\"hotkeys-dialog-group\" className=\"flex flex-col gap-1.5\">\n              <h4 className=\"text-xs font-medium text-muted-foreground uppercase\">{group}</h4>\n              {hotkeys.map((h) => (\n                <div\n                  key={h.id}\n                  data-slot=\"hotkeys-dialog-item\"\n                  className=\"flex items-center justify-between gap-3 text-sm\"\n                >\n                  <span className=\"truncate\">{h.label}</span>\n                  <HotkeyKbd hotkey={h.hotkey} />\n                </div>\n              ))}\n            </div>\n          ))}\n        </div>\n        {children}\n      </DialogContent>\n    </Dialog>\n  )\n}\n\nfunction useHotkeysDialog() {\n  const { dialogOpen, setDialogOpen } = useHotkeysContext()\n  return { open: dialogOpen, setOpen: setDialogOpen }\n}\n\nexport { HotkeyKbd, HotkeysDialog, HotkeysProvider, formatHotkey, parseHotkey, useHotkey, useHotkeys, useHotkeysDialog }\n"
+      "content": "\"use client\"\n\nimport * as React from \"react\"\nimport { cn } from \"@/lib/utils\"\nimport { Dialog, DialogContent, DialogDescription, DialogHeader, DialogTitle } from \"@/components/ui/dialog\"\nimport { Kbd, KbdGroup } from \"@/components/ui/kbd\"\n\n/* -------------------------------- parsing -------------------------------- */\n\nconst isMac = () => typeof navigator !== \"undefined\" && /mac|iphone|ipad|ipod/i.test(navigator.platform)\n\ntype Chord = { key: string; mod: boolean; ctrl: boolean; meta: boolean; alt: boolean; shift: boolean }\n\nconst keyAliases: Record<string, string> = {\n  esc: \"escape\",\n  return: \"enter\",\n  space: \" \",\n  up: \"arrowup\",\n  down: \"arrowdown\",\n  left: \"arrowleft\",\n  right: \"arrowright\",\n  plus: \"+\",\n  del: \"delete\",\n}\n\n/** \"mod+shift+k\" → chord; \"g d\" → sequence of chords. */\nfunction parseHotkey(hotkey: string): Chord[] {\n  return hotkey\n    .trim()\n    .split(/\\s+/)\n    .map((part) => {\n      const tokens = part.split(\"+\").map((t) => t.toLowerCase())\n      // \"+\" itself is written as \"plus\"\n      const key = tokens.pop() ?? \"\"\n      const chord: Chord = {\n        key: keyAliases[key] ?? key,\n        mod: false,\n        ctrl: false,\n        meta: false,\n        alt: false,\n        shift: false,\n      }\n      for (const t of tokens) {\n        if (t === \"mod\" || t === \"cmd\" || t === \"command\") chord.mod = true\n        else if (t === \"ctrl\" || t === \"control\") chord.ctrl = true\n        else if (t === \"meta\" || t === \"win\" || t === \"super\") chord.meta = true\n        else if (t === \"alt\" || t === \"option\") chord.alt = true\n        else if (t === \"shift\") chord.shift = true\n      }\n      return chord\n    })\n}\n\nfunction matchesChord(event: KeyboardEvent, chord: Chord, mac: boolean) {\n  const key = event.key.length === 1 ? event.key.toLowerCase() : event.key.toLowerCase()\n  if (key !== chord.key) return false\n  const wantMeta = chord.meta || (chord.mod && mac)\n  const wantCtrl = chord.ctrl || (chord.mod && !mac)\n  if (event.metaKey !== wantMeta || event.ctrlKey !== wantCtrl || event.altKey !== chord.alt) return false\n  // Punctuation like \"?\" already implies Shift on most layouts, so only enforce Shift for letters.\n  const letter = /^[a-z0-9]$/.test(chord.key) || chord.key.length > 1\n  if (letter && event.shiftKey !== chord.shift) return false\n  return true\n}\n\nconst symbol: Record<string, string> = {\n  mod: \"⌘\",\n  meta: \"⌘\",\n  ctrl: \"⌃\",\n  alt: \"⌥\",\n  shift: \"⇧\",\n  enter: \"↵\",\n  escape: \"Esc\",\n  backspace: \"⌫\",\n  delete: \"⌦\",\n  arrowup: \"↑\",\n  arrowdown: \"↓\",\n  arrowleft: \"←\",\n  arrowright: \"→\",\n  \" \": \"Space\",\n  tab: \"Tab\",\n}\nconst winSymbol: Record<string, string> = {\n  ...symbol,\n  mod: \"Ctrl\",\n  meta: \"Win\",\n  ctrl: \"Ctrl\",\n  alt: \"Alt\",\n  shift: \"Shift\",\n}\n\n/** Platform-aware key labels: \"mod+k\" → [\"⌘\", \"K\"] on Mac, [\"Ctrl\", \"K\"] elsewhere. Sequences give one array per chord. */\nfunction formatHotkey(hotkey: string, mac = isMac()): string[][] {\n  const table = mac ? symbol : winSymbol\n  return parseHotkey(hotkey).map((chord) => {\n    const parts: string[] = []\n    if (chord.ctrl) parts.push(table.ctrl)\n    if (chord.alt) parts.push(table.alt)\n    if (chord.shift) parts.push(table.shift)\n    if (chord.mod) parts.push(table.mod)\n    if (chord.meta && !chord.mod) parts.push(table.meta)\n    parts.push(table[chord.key] ?? (chord.key.length === 1 ? chord.key.toUpperCase() : chord.key))\n    return parts\n  })\n}\n\n/* -------------------------------- registry ------------------------------- */\n\ntype HotkeyEntry = {\n  id: string\n  /** Key combination such as `mod+k`, or a sequence such as `g d`. */\n  hotkey: string\n  label: string\n  group: string\n  enabled: boolean\n  /** Fire even while typing in an input, textarea, or contenteditable. */\n  allowInInput: boolean\n  handler: (event: KeyboardEvent) => void\n}\n\ntype HotkeysContextValue = {\n  entries: HotkeyEntry[]\n  register: (entry: HotkeyEntry) => () => void\n  dialogOpen: boolean\n  setDialogOpen: (open: boolean) => void\n}\n\nconst HotkeysContext = React.createContext<HotkeysContextValue | null>(null)\n\nfunction useHotkeysContext() {\n  const ctx = React.useContext(HotkeysContext)\n  if (!ctx) throw new Error(\"Hotkeys parts must be used inside <HotkeysProvider>\")\n  return ctx\n}\n\nconst isEditable = (target: EventTarget | null) => {\n  const el = target as HTMLElement | null\n  if (!el || !(\"tagName\" in el)) return false\n  const tag = el.tagName\n  return tag === \"INPUT\" || tag === \"TEXTAREA\" || tag === \"SELECT\" || el.isContentEditable\n}\n\n/**\n * One document-level keydown listener for every registered hotkey. Supports chords\n * (\"mod+k\"), sequences (\"g d\", one second between keys), and a built-in \"?\" that opens\n * `HotkeysDialog` when one is rendered.\n */\nfunction HotkeysProvider({\n  children,\n  dialogHotkey = \"?\",\n  sequenceTimeout = 1000,\n}: {\n  children: React.ReactNode\n  /** Opens the shortcuts dialog; `null` disables it. */\n  dialogHotkey?: string | null\n  /** Milliseconds allowed between keys of a sequence. */\n  sequenceTimeout?: number\n}) {\n  const [entries, setEntries] = React.useState<HotkeyEntry[]>([])\n  const [dialogOpen, setDialogOpen] = React.useState(false)\n  const entriesRef = React.useRef(entries)\n  entriesRef.current = entries\n  const buffer = React.useRef<{ keys: KeyboardEvent[]; at: number }>({ keys: [], at: 0 })\n\n  const register = React.useCallback((entry: HotkeyEntry) => {\n    setEntries((prev) => [...prev.filter((e) => e.id !== entry.id), entry])\n    return () => setEntries((prev) => prev.filter((e) => e.id !== entry.id))\n  }, [])\n\n  const mac = React.useMemo(isMac, [])\n  React.useEffect(() => {\n    const down = (event: KeyboardEvent) => {\n      if (event.defaultPrevented || event.isComposing) return\n      if ([\"Shift\", \"Control\", \"Alt\", \"Meta\"].includes(event.key)) return\n      const editing = isEditable(event.target)\n      const now = Date.now()\n      const buf = buffer.current\n      if (now - buf.at > sequenceTimeout) buf.keys = []\n      buf.keys.push(event)\n      buf.at = now\n      if (buf.keys.length > 4) buf.keys.shift()\n\n      const candidates = [...entriesRef.current]\n      if (dialogHotkey) {\n        candidates.push({\n          id: \"hotkeys:dialog\",\n          hotkey: dialogHotkey,\n          label: \"Keyboard shortcuts\",\n          group: \"General\",\n          enabled: true,\n          allowInInput: false,\n          handler: () => setDialogOpen((open) => !open),\n        })\n      }\n      let partial = false\n      for (const entry of candidates) {\n        if (!entry.enabled || (editing && !entry.allowInInput)) continue\n        const chords = parseHotkey(entry.hotkey)\n        const tail = buf.keys.slice(-chords.length)\n        if (tail.length === chords.length && chords.every((c, i) => matchesChord(tail[i], c, mac))) {\n          event.preventDefault()\n          buf.keys = []\n          entry.handler(event)\n          return\n        }\n        // Is the buffer a prefix of a longer sequence? Then keep it.\n        if (chords.length > 1 && buf.keys.length < chords.length) {\n          const head = chords.slice(0, buf.keys.length)\n          if (head.every((c, i) => matchesChord(buf.keys[i], c, mac))) partial = true\n        }\n      }\n      if (!partial) buf.keys = []\n    }\n    document.addEventListener(\"keydown\", down)\n    return () => document.removeEventListener(\"keydown\", down)\n  }, [dialogHotkey, sequenceTimeout, mac])\n\n  const ctx = React.useMemo<HotkeysContextValue>(\n    () => ({ entries, register, dialogOpen, setDialogOpen }),\n    [entries, register, dialogOpen]\n  )\n  return <HotkeysContext.Provider value={ctx}>{children}</HotkeysContext.Provider>\n}\n\n/** Register a hotkey for the lifetime of the component. Listed in `HotkeysDialog` when it has a label. */\nfunction useHotkey(\n  /** Key combination such as `mod+k`, or a sequence such as `g d`. */\n  hotkey: string,\n  handler: (event: KeyboardEvent) => void,\n  options: { label?: string; group?: string; enabled?: boolean; allowInInput?: boolean } = {}\n) {\n  const { register } = useHotkeysContext()\n  const { label = \"\", group = \"General\", enabled = true, allowInInput = false } = options\n  const id = React.useId()\n  const handlerRef = React.useRef(handler)\n  handlerRef.current = handler\n  React.useEffect(\n    () =>\n      register({\n        id,\n        hotkey,\n        label,\n        group,\n        enabled,\n        allowInInput,\n        handler: (event) => handlerRef.current(event),\n      }),\n    [register, id, hotkey, label, group, enabled, allowInInput]\n  )\n}\n\n/** Every registered hotkey with a label, grouped, for rendering a cheat sheet. */\nfunction useHotkeys() {\n  const { entries } = useHotkeysContext()\n  return React.useMemo(() => {\n    const groups = new Map<string, HotkeyEntry[]>()\n    for (const e of entries) {\n      if (!e.label) continue\n      const list = groups.get(e.group) ?? []\n      list.push(e)\n      groups.set(e.group, list)\n    }\n    return Array.from(groups, ([group, hotkeys]) => ({ group, hotkeys }))\n  }, [entries])\n}\n\n/* ---------------------------------- parts -------------------------------- */\n\n/** Renders a hotkey as Kbd caps (\"mod+k\" → ⌘ K; \"g d\" → G then D). */\nfunction HotkeyKbd({ hotkey, className, ...props }: React.ComponentProps<\"span\"> & { hotkey: string }) {\n  const chords = formatHotkey(hotkey)\n  return (\n    <span data-slot=\"hotkey-kbd\" className={cn(\"inline-flex items-center gap-1\", className)} {...props}>\n      {chords.map((keys, i) => (\n        <React.Fragment key={i}>\n          {i > 0 && <span className=\"text-xs text-muted-foreground\">then</span>}\n          <KbdGroup>\n            {keys.map((k, j) => (\n              <Kbd key={j}>{k}</Kbd>\n            ))}\n          </KbdGroup>\n        </React.Fragment>\n      ))}\n    </span>\n  )\n}\n\n/** The shortcuts cheat sheet. Opens from the provider's `dialogHotkey` (\"?\" by default) or `useHotkeysDialog()`. */\nfunction HotkeysDialog({\n  title = \"Keyboard shortcuts\",\n  description = \"Shortcuts work anywhere on the page except while typing.\",\n  children,\n  className,\n}: {\n  title?: React.ReactNode\n  description?: React.ReactNode\n  children?: React.ReactNode\n  className?: string\n}) {\n  const { dialogOpen, setDialogOpen } = useHotkeysContext()\n  const registered = useHotkeys()\n  const groups = React.useMemo(() => {\n    const self = { id: \"hotkeys:dialog\", hotkey: \"?\", label: \"Show this dialog\" }\n    const general = registered.find((g) => g.group === \"General\")\n    if (general) return registered.map((g) => (g === general ? { ...g, hotkeys: [...g.hotkeys, self] } : g))\n    return [...registered, { group: \"General\", hotkeys: [self] }]\n  }, [registered])\n  return (\n    <Dialog open={dialogOpen} onOpenChange={({ open }) => setDialogOpen(open)}>\n      <DialogContent data-slot=\"hotkeys-dialog\" className={cn(\"sm:max-w-lg\", className)}>\n        <DialogHeader>\n          <DialogTitle>{title}</DialogTitle>\n          <DialogDescription>{description}</DialogDescription>\n        </DialogHeader>\n        <div className=\"grid gap-5 sm:grid-cols-2\">\n          {groups.map(({ group, hotkeys }) => (\n            <div key={group} data-slot=\"hotkeys-dialog-group\" className=\"flex flex-col gap-1.5\">\n              <h4 className=\"text-xs font-medium text-muted-foreground uppercase\">{group}</h4>\n              {hotkeys.map((h) => (\n                <div\n                  key={h.id}\n                  data-slot=\"hotkeys-dialog-item\"\n                  className=\"flex items-center justify-between gap-3 text-sm\"\n                >\n                  <span className=\"truncate\">{h.label}</span>\n                  <HotkeyKbd hotkey={h.hotkey} />\n                </div>\n              ))}\n            </div>\n          ))}\n        </div>\n        {children}\n      </DialogContent>\n    </Dialog>\n  )\n}\n\nfunction useHotkeysDialog() {\n  const { dialogOpen, setDialogOpen } = useHotkeysContext()\n  return { open: dialogOpen, setOpen: setDialogOpen }\n}\n\nexport { HotkeyKbd, HotkeysDialog, HotkeysProvider, formatHotkey, parseHotkey, useHotkey, useHotkeys, useHotkeysDialog }\n"
     }
   ],
   "docs": "## Shared infrastructure\n- `src/lib/controllable.ts` `useControllable(controlled, default, onChange)` is the one\n  controllable-state hook (updater functions accepted; `onChange` fires in both modes, not on\n  no-op sets). Every primitive and demo composition uses it (chat, menubar, comment thread, gantt,\n  scheduler, data grid, query builder, tree select, cascader, transfer list, the table engine,\n  apps view, settings layout). Never hand-roll `valueProp ?? internal` again.\n- `src/components/ui/live-region.tsx`: `useLiveRegion({ clearAfter })` → `{ message, announce }`\n  (re-fires identical text) and `<LiveRegion message= assertive? />` (sr-only `role=\"status\"`).\n  Kanban, canvas, gantt, scheduler, node graph, data grid, data table bulk actions, and transfer\n  list all announce through it; a primitive renders its own `LiveRegion` (with its `data-slot`)\n  so it works without any provider.\n- `src/components/ui/hotkeys.tsx`: `HotkeysProvider` (one document keydown listener; chords like\n  `mod+k` where `mod` is ⌘ on Mac and Ctrl elsewhere, sequences like `g d` with a 1s window,\n  ignores typing in inputs unless `allowInInput`, built-in `?` toggles the dialog;\n  `dialogHotkey={null}` disables), `useHotkey(hotkey, handler, { label, group, enabled,\n  allowInInput })` registers for the component's lifetime (labelled ones appear in the dialog),\n  `useHotkeys()` (grouped list), `HotkeysDialog` (the cheat sheet on `Dialog`; `useHotkeysDialog()`\n  opens it), `HotkeyKbd hotkey=` (platform-aware `Kbd` caps, \"then\" between sequence steps),\n  `formatHotkey`/`parseHotkey`. The shell demo wraps everything in the provider with\n  `AppShell searchShortcut={false}` and registers ⌘K, ⌘J (theme), and `g` + letter navigation in\n  `ShellHotkeys`; the user menu has a \"Keyboard shortcuts\" item. Pages register their own with\n  `useHotkey` and a `group`."

package/registry/items/hover-card.json

@@ -12,6 +12,363 @@
     "HoverCardPositioner",
     "HoverCardTrigger"
   ],
+  "parts": [
+    {
+      "name": "HoverCard",
+      "props": [
+        {
+          "name": "children",
+          "type": "ReactNode",
+          "required": false,
+          "description": "Content rendered inside the part.",
+          "from": "@ark-ui/react"
+        },
+        {
+          "name": "closeDelay",
+          "type": "number",
+          "required": false,
+          "default": "300",
+          "description": "The duration from when the mouse leaves the trigger or content until the hover card closes.",
+          "from": "@zag-js/hover-card"
+        },
+        {
+          "name": "defaultOpen",
+          "type": "boolean",
+          "required": false,
+          "description": "The initial open state of the hover card when rendered.\nUse when you don't need to control the open state of the hover card.",
+          "from": "@zag-js/hover-card"
+        },
+        {
+          "name": "defaultTriggerValue",
+          "type": "string | null",
+          "required": false,
+          "description": "The initial trigger value when rendered.\nUse when you don't need to control the trigger value.",
+          "from": "@zag-js/hover-card"
+        },
+        {
+          "name": "disabled",
+          "type": "boolean",
+          "required": false,
+          "description": "Whether the hover card is disabled",
+          "from": "@zag-js/hover-card"
+        },
+        {
+          "name": "hideMode",
+          "type": "HideMode",
+          "required": false,
+          "default": "'display-none'",
+          "description": "How to hide content when mounted but not present.\n- `'display-none'`: HTML `hidden` attribute. Effects stay alive.\n- `'activity'`: React 19 `<Activity mode=\"hidden\">`. Effects pause. Requires React 19+.",
+          "from": "@ark-ui/react"
+        },
+        {
+          "name": "id",
+          "type": "string",
+          "required": false,
+          "description": "The unique identifier of the machine.",
+          "from": "@zag-js/types"
+        },
+        {
+          "name": "ids",
+          "type": "ElementIds",
+          "required": false,
+          "description": "The ids of the elements in the popover. Useful for composition.",
+          "from": "@zag-js/hover-card"
+        },
+        {
+          "name": "immediate",
+          "type": "boolean",
+          "required": false,
+          "description": "Whether to synchronize the present change immediately or defer it to the next frame",
+          "from": "@zag-js/presence"
+        },
+        {
+          "name": "lazyMount",
+          "type": "boolean",
+          "required": false,
+          "default": "true",
+          "description": "Whether to enable lazy mounting",
+          "from": "@ark-ui/react"
+        },
+        {
+          "name": "onEnterComplete",
+          "type": "VoidFunction",
+          "required": false,
+          "description": "Function called when the animation ends in the open state",
+          "from": "@zag-js/presence"
+        },
+        {
+          "name": "onExitComplete",
+          "type": "VoidFunction",
+          "required": false,
+          "description": "Function called when the animation ends in the closed state",
+          "from": "@zag-js/presence"
+        },
+        {
+          "name": "onFocusOutside",
+          "type": "((event: FocusOutsideEvent) => void)",
+          "required": false,
+          "description": "Function called when the focus is moved outside the component",
+          "from": "@zag-js/interact-outside"
+        },
+        {
+          "name": "onInteractOutside",
+          "type": "((event: InteractOutsideEvent) => void)",
+          "required": false,
+          "description": "Function called when an interaction happens outside the component",
+          "from": "@zag-js/interact-outside"
+        },
+        {
+          "name": "onOpenChange",
+          "type": "((details: OpenChangeDetails) => void)",
+          "required": false,
+          "description": "Function called when the hover card opens or closes.",
+          "from": "@zag-js/hover-card"
+        },
+        {
+          "name": "onPointerDownOutside",
+          "type": "((event: PointerDownOutsideEvent) => void)",
+          "required": false,
+          "description": "Function called when the pointer is pressed down outside the component",
+          "from": "@zag-js/interact-outside"
+        },
+        {
+          "name": "onTriggerValueChange",
+          "type": "((details: TriggerValueChangeDetails) => void)",
+          "required": false,
+          "description": "Function called when the trigger value changes.",
+          "from": "@zag-js/hover-card"
+        },
+        {
+          "name": "open",
+          "type": "boolean",
+          "required": false,
+          "description": "The controlled open state of the hover card",
+          "from": "@zag-js/hover-card"
+        },
+        {
+          "name": "openDelay",
+          "type": "number",
+          "required": false,
+          "default": "600",
+          "description": "The duration from when the mouse enters the trigger until the hover card opens.",
+          "from": "@zag-js/hover-card"
+        },
+        {
+          "name": "positioning",
+          "type": "PositioningOptions",
+          "required": false,
+          "description": "The user provided options used to position the popover content",
+          "from": "@zag-js/hover-card"
+        },
+        {
+          "name": "present",
+          "type": "boolean",
+          "required": false,
+          "description": "Whether the node is present (controlled by the user)",
+          "from": "@zag-js/presence"
+        },
+        {
+          "name": "skipAnimationOnMount",
+          "type": "boolean",
+          "required": false,
+          "default": "false",
+          "description": "Whether to allow the initial presence animation.",
+          "from": "@ark-ui/react"
+        },
+        {
+          "name": "triggerValue",
+          "type": "string | null",
+          "required": false,
+          "description": "The controlled trigger value",
+          "from": "@zag-js/hover-card"
+        },
+        {
+          "name": "unmountOnExit",
+          "type": "boolean",
+          "required": false,
+          "default": "true",
+          "description": "Whether to unmount on exit.",
+          "from": "@ark-ui/react"
+        }
+      ]
+    },
+    {
+      "name": "HoverCardArrow",
+      "props": [
+        {
+          "name": "asChild",
+          "type": "boolean",
+          "required": false,
+          "description": "Use the provided child element as the default rendered element, combining their props and behavior.",
+          "from": "@ark-ui/react"
+        },
+        {
+          "name": "children",
+          "type": "ReactNode",
+          "required": false,
+          "description": "Content rendered inside the part.",
+          "from": "@types/react"
+        },
+        {
+          "name": "className",
+          "type": "string",
+          "required": false,
+          "description": "Extra classes merged into the part's own classes with `cn`.",
+          "from": "@types/react"
+        },
+        {
+          "name": "style",
+          "type": "CSSProperties",
+          "required": false,
+          "description": "Inline styles applied to the rendered element.",
+          "from": "@types/react"
+        }
+      ]
+    },
+    {
+      "name": "HoverCardContent",
+      "props": [
+        {
+          "name": "asChild",
+          "type": "boolean",
+          "required": false,
+          "description": "Use the provided child element as the default rendered element, combining their props and behavior.",
+          "from": "@ark-ui/react"
+        },
+        {
+          "name": "children",
+          "type": "ReactNode",
+          "required": false,
+          "description": "Content rendered inside the part.",
+          "from": "@types/react"
+        },
+        {
+          "name": "className",
+          "type": "string",
+          "required": false,
+          "description": "Extra classes merged into the part's own classes with `cn`.",
+          "from": "@types/react"
+        },
+        {
+          "name": "style",
+          "type": "CSSProperties",
+          "required": false,
+          "description": "Inline styles applied to the rendered element.",
+          "from": "@types/react"
+        }
+      ]
+    },
+    {
+      "name": "HoverCardContext",
+      "props": [
+        {
+          "name": "children",
+          "type": "(context: UseHoverCardContext) => ReactNode",
+          "required": true,
+          "description": "Content rendered inside the part.",
+          "from": "@ark-ui/react"
+        }
+      ]
+    },
+    {
+      "name": "HoverCardPortal",
+      "props": [
+        {
+          "name": "children",
+          "type": "ReactNode",
+          "required": false,
+          "description": "Content rendered inside the part.",
+          "from": "@types/react"
+        },
+        {
+          "name": "container",
+          "type": "RefObject<HTMLElement | null>",
+          "required": false,
+          "from": "@ark-ui/react"
+        },
+        {
+          "name": "disabled",
+          "type": "boolean",
+          "required": false,
+          "description": "Disables the part and everything inside it.",
+          "from": "@ark-ui/react"
+        }
+      ]
+    },
+    {
+      "name": "HoverCardPositioner",
+      "props": [
+        {
+          "name": "asChild",
+          "type": "boolean",
+          "required": false,
+          "description": "Use the provided child element as the default rendered element, combining their props and behavior.",
+          "from": "@ark-ui/react"
+        },
+        {
+          "name": "children",
+          "type": "ReactNode",
+          "required": false,
+          "description": "Content rendered inside the part.",
+          "from": "@types/react"
+        },
+        {
+          "name": "className",
+          "type": "string",
+          "required": false,
+          "description": "Extra classes merged into the part's own classes with `cn`.",
+          "from": "@types/react"
+        },
+        {
+          "name": "style",
+          "type": "CSSProperties",
+          "required": false,
+          "description": "Inline styles applied to the rendered element.",
+          "from": "@types/react"
+        }
+      ]
+    },
+    {
+      "name": "HoverCardTrigger",
+      "props": [
+        {
+          "name": "asChild",
+          "type": "boolean",
+          "required": false,
+          "description": "Use the provided child element as the default rendered element, combining their props and behavior.",
+          "from": "@ark-ui/react"
+        },
+        {
+          "name": "children",
+          "type": "ReactNode",
+          "required": false,
+          "description": "Content rendered inside the part.",
+          "from": "@types/react"
+        },
+        {
+          "name": "className",
+          "type": "string",
+          "required": false,
+          "description": "Extra classes merged into the part's own classes with `cn`.",
+          "from": "@types/react"
+        },
+        {
+          "name": "style",
+          "type": "CSSProperties",
+          "required": false,
+          "description": "Inline styles applied to the rendered element.",
+          "from": "@types/react"
+        },
+        {
+          "name": "value",
+          "type": "string",
+          "required": false,
+          "description": "The value that identifies this specific trigger",
+          "from": "@zag-js/hover-card"
+        }
+      ]
+    }
+  ],
   "dependencies": {
     "@ark-ui/react": "^5.39.1"
   },