{
  "schemaVersion": 1,
  "target": "react",
  "name": "kbd",
  "version": "0.1.0",
  "category": "data",
  "title": "Kbd",
  "description": "Keyboard keys and key combinations as quiet keycaps, with a platform-aware Mod key that shows ⌘ on Apple devices and Ctrl elsewhere.",
  "tags": [
    "keyboard",
    "shortcut",
    "hotkey",
    "kbd"
  ],
  "requires": {
    "projectTypes": [
      "next",
      "vite-react"
    ],
    "styling": "tailwind-v4"
  },
  "npmDependencies": {},
  "registryDependencies": [],
  "docsPath": "/components/kbd",
  "props": [
    {
      "name": "Kbd size",
      "type": "\"sm\" | \"md\"",
      "default": "\"sm\"",
      "description": "20 or 24 pixels tall."
    },
    {
      "name": "KbdGroup keys",
      "type": "string | string[]",
      "description": "Keys pressed together: [\"Mod\", \"K\"] or \"Mod+Shift+P\". Mod, Shift, Alt, Ctrl, Enter, Escape, Backspace, Tab, and arrows map to symbols on Apple platforms."
    },
    {
      "name": "KbdGroup separator",
      "type": "ReactNode",
      "description": "Between keys. None on Apple platforms, + elsewhere."
    },
    {
      "name": "KbdGroup platform",
      "type": "\"mac\" | \"other\"",
      "description": "Forces a platform; detected from the browser by default."
    },
    {
      "name": "useKbdPlatform / formatKey",
      "type": "hook / (key, platform) => { label, name }",
      "description": "The detection and key mapping, for building your own shortcut hints."
    }
  ],
  "accessibility": [
    "Renders kbd elements, with a combination as a kbd that contains one kbd per key, as HTML specifies.",
    "Symbols carry their spoken names in visually hidden text (\"Command\", \"Shift\"), and a title tooltip for sighted users.",
    "Platform detection renders the non-Apple labels on the server and during hydration, then settles, so there is no hydration mismatch.",
    "Separators are decorative and hidden from assistive technology."
  ],
  "states": [],
  "files": [
    {
      "path": "ui/kbd.tsx",
      "content": "\"use client\";\n\nimport { type ComponentProps, Fragment, type ReactNode, useSyncExternalStore } from \"react\";\n\nfunction cx(...classes: (string | false | null | undefined)[]) {\n  return classes.filter(Boolean).join(\" \");\n}\n\nexport type KbdPlatform = \"mac\" | \"other\";\n\nfunction detectPlatform(): KbdPlatform {\n  if (typeof navigator === \"undefined\") return \"other\";\n  const nav = navigator as Navigator & { userAgentData?: { platform?: string } };\n  const name = nav.userAgentData?.platform || nav.platform || nav.userAgent;\n  return /mac|iphone|ipad|ipod/i.test(name) ? \"mac\" : \"other\";\n}\n\nconst subscribe = () => () => {};\n\n/**\n * The visitor's platform: `\"mac\"` on macOS and iOS, `\"other\"` elsewhere. Renders `\"other\"` on the\n * server and during hydration, then settles on the real value, so there is no hydration mismatch.\n */\nexport function useKbdPlatform(): KbdPlatform {\n  return useSyncExternalStore(subscribe, detectPlatform, () => \"other\");\n}\n\ntype KeyLabel = { mac: string; other: string; name: string };\n\n// Symbols on Apple platforms, words elsewhere. `name` is what a screen reader hears.\nconst keys: Record<string, KeyLabel> = {\n  mod: { mac: \"⌘\", other: \"Ctrl\", name: \"Command\" },\n  cmd: { mac: \"⌘\", other: \"Win\", name: \"Command\" },\n  command: { mac: \"⌘\", other: \"Win\", name: \"Command\" },\n  meta: { mac: \"⌘\", other: \"Win\", name: \"Command\" },\n  ctrl: { mac: \"⌃\", other: \"Ctrl\", name: \"Control\" },\n  control: { mac: \"⌃\", other: \"Ctrl\", name: \"Control\" },\n  shift: { mac: \"⇧\", other: \"Shift\", name: \"Shift\" },\n  alt: { mac: \"⌥\", other: \"Alt\", name: \"Option\" },\n  option: { mac: \"⌥\", other: \"Alt\", name: \"Option\" },\n  enter: { mac: \"↵\", other: \"Enter\", name: \"Enter\" },\n  return: { mac: \"↵\", other: \"Enter\", name: \"Return\" },\n  escape: { mac: \"Esc\", other: \"Esc\", name: \"Escape\" },\n  esc: { mac: \"Esc\", other: \"Esc\", name: \"Escape\" },\n  backspace: { mac: \"⌫\", other: \"Backspace\", name: \"Backspace\" },\n  delete: { mac: \"⌦\", other: \"Del\", name: \"Delete\" },\n  tab: { mac: \"⇥\", other: \"Tab\", name: \"Tab\" },\n  space: { mac: \"Space\", other: \"Space\", name: \"Space\" },\n  up: { mac: \"↑\", other: \"↑\", name: \"Up arrow\" },\n  arrowup: { mac: \"↑\", other: \"↑\", name: \"Up arrow\" },\n  down: { mac: \"↓\", other: \"↓\", name: \"Down arrow\" },\n  arrowdown: { mac: \"↓\", other: \"↓\", name: \"Down arrow\" },\n  left: { mac: \"←\", other: \"←\", name: \"Left arrow\" },\n  arrowleft: { mac: \"←\", other: \"←\", name: \"Left arrow\" },\n  right: { mac: \"→\", other: \"→\", name: \"Right arrow\" },\n  arrowright: { mac: \"→\", other: \"→\", name: \"Right arrow\" },\n};\n\n/** Resolves a key name such as `\"Mod\"` or `\"shift\"` to its label for a platform, with a spoken name. */\nexport function formatKey(key: string, platform: KbdPlatform) {\n  const known = keys[key.toLowerCase()];\n  if (known) {\n    // The modifier's spoken name follows the platform: \"Command\" on a Mac, \"Control\" elsewhere.\n    const lower = key.toLowerCase();\n    const name =\n      platform === \"other\" && lower === \"mod\"\n        ? \"Control\"\n        : platform === \"other\" && (lower === \"cmd\" || lower === \"command\" || lower === \"meta\")\n          ? \"Windows\"\n          : platform === \"other\" && (lower === \"alt\" || lower === \"option\")\n            ? \"Alt\"\n            : known.name;\n    return { label: known[platform], name };\n  }\n  return { label: key.length === 1 ? key.toUpperCase() : key, name: key.length === 1 ? key.toUpperCase() : key };\n}\n\nconst sizes = {\n  sm: \"h-5 min-w-5 px-1 text-[11px]\",\n  md: \"h-6 min-w-6 px-1.5 text-xs\",\n} as const;\n\nexport interface KbdProps extends ComponentProps<\"kbd\"> {\n  size?: keyof typeof sizes;\n}\n\n/**\n * One key, drawn as a quiet keycap: hairline border with a slightly heavier bottom edge.\n * Renders a `<kbd>`, so assistive technology knows it is keyboard input.\n */\nexport function Kbd({ size = \"sm\", className, ...props }: KbdProps) {\n  return (\n    <kbd\n      data-slot=\"kbd\"\n      className={cx(\n        \"inline-flex shrink-0 items-center justify-center rounded-md font-sans leading-none font-medium whitespace-nowrap select-none\",\n        \"border border-b-[1.5px] border-zinc-950/12 bg-white text-zinc-600 shadow-[0_1px_0_rgb(0_0_0/0.04)]\",\n        \"dark:border-white/15 dark:bg-white/[0.04] dark:text-zinc-300 dark:shadow-none\",\n        \"[&_svg]:size-3 [&_svg]:shrink-0\",\n        sizes[size],\n        className,\n      )}\n      {...props}\n    />\n  );\n}\n\nexport interface KbdGroupProps extends Omit<ComponentProps<\"kbd\">, \"children\"> {\n  /**\n   * The keys to press together, as an array (`[\"Mod\", \"K\"]`) or a string joined by `+`\n   * (`\"Mod+Shift+P\"`). `Mod` becomes ⌘ on Apple platforms and Ctrl elsewhere.\n   */\n  keys: string | string[];\n  size?: KbdProps[\"size\"];\n  /**\n   * Text between keys. Defaults to nothing on Apple platforms (⌘K reads as one chord there)\n   * and `+` elsewhere.\n   */\n  separator?: ReactNode;\n  /** Forces a platform, for example to document both. Detected from the browser by default. */\n  platform?: KbdPlatform;\n}\n\n/**\n * A key combination: a `<kbd>` holding one `<kbd>` per key, as HTML specifies for chords.\n * Each symbol carries its spoken name for screen readers (\"Command K\", not \"K\").\n */\nexport function KbdGroup({ keys: input, size = \"sm\", separator, platform: forced, className, ...props }: KbdGroupProps) {\n  const detected = useKbdPlatform();\n  const platform = forced ?? detected;\n  const list = Array.isArray(input) ? input : input.split(\"+\").map((key) => key.trim()).filter(Boolean);\n  const between = separator !== undefined ? separator : platform === \"mac\" ? null : \"+\";\n\n  return (\n    <kbd data-slot=\"kbd-group\" className={cx(\"inline-flex items-center gap-1 font-sans\", className)} {...props}>\n      {list.map((key, index) => {\n        const { label, name } = formatKey(key, platform);\n        const spoken = name !== label;\n        return (\n          <Fragment key={`${key}-${index}`}>\n            {index > 0 && between != null ? (\n              <span aria-hidden=\"true\" className=\"text-[11px] text-zinc-400 dark:text-zinc-500\">\n                {between}\n              </span>\n            ) : null}\n            <Kbd size={size} title={spoken ? name : undefined}>\n              {spoken ? (\n                <>\n                  <span aria-hidden=\"true\">{label}</span>\n                  <span className=\"sr-only\">{name}</span>\n                </>\n              ) : (\n                label\n              )}\n            </Kbd>\n          </Fragment>\n        );\n      })}\n    </kbd>\n  );\n}\n"
    }
  ],
  "example": {
    "content": "import { Kbd, KbdGroup } from \"@/components/shaken/ui/kbd\";\n\nconst shortcuts = [\n  { action: \"Open the command menu\", keys: \"Mod+K\" },\n  { action: \"Send the prompt\", keys: \"Mod+Enter\" },\n  { action: \"Stop the running agent\", keys: \"Escape\" },\n  { action: \"Toggle the trace panel\", keys: \"Mod+Shift+T\" },\n];\n\nexport default function KbdExample() {\n  return (\n    <div className=\"grid w-full max-w-sm gap-5\">\n      <ul className=\"grid divide-y divide-zinc-950/[0.07] rounded-xl border border-zinc-950/10 dark:divide-white/[0.08] dark:border-white/10\">\n        {shortcuts.map((shortcut) => (\n          <li key={shortcut.action} className=\"flex items-center justify-between gap-4 px-4 py-2.5 text-sm\">\n            <span className=\"text-zinc-700 dark:text-zinc-300\">{shortcut.action}</span>\n            <KbdGroup keys={shortcut.keys} />\n          </li>\n        ))}\n      </ul>\n      <p className=\"text-sm text-zinc-600 dark:text-zinc-400\">\n        Press <Kbd>/</Kbd> to search the docs, or <KbdGroup keys={[\"Shift\", \"?\"]} /> for every shortcut.\n      </p>\n    </div>\n  );\n}\n"
  }
}
