@krizaka/ui 2.5.0 → 2.6.0

package/registry/terminal-replay.json

@@ -0,0 +1,317 @@
+{
+  "name": "terminal-replay",
+  "type": "primitive",
+  "title": "Terminal replay",
+  "summary": "A terminal session played back: each command typed at the prompt, its output line by line, the screen following the last line — or the whole session at rest, as the server renders it.",
+  "description": "A terminal session played back: each command typed at the prompt, its output line by line, the screen following the last line — or the whole session at rest, as the server renders it.",
+  "status": "beta",
+  "category": "media",
+  "platforms": "web",
+  "whenToUse": [
+    "Show how a command-line tool works from a recording of a real session: install, start, run.",
+    "A getting-started page where the reader should see the order of the commands and what each one answers."
+  ],
+  "whenNotToUse": [
+    {
+      "when": "For commands the reader copies and runs, with nothing to watch.",
+      "use": "kbd"
+    },
+    {
+      "when": "For a video of an application's screens: record the screens, not a terminal.",
+      "use": "video-player"
+    },
+    {
+      "when": "For output you wrote by hand: replay what the tool really printed, or show none."
+    }
+  ],
+  "bestPractices": [
+    "Replay a real session, captured from the tool itself — never an invented output.",
+    "Keep each step short: a long output is trimmed where it repeats, and says it was trimmed.",
+    "Name the screen (`label`) by what it shows; the words of the controls arrive as props, translated.",
+    "Give the copy button (`copyLabel`) when the commands are meant to be run."
+  ],
+  "accessibility": {
+    "keyboard": [
+      {
+        "keys": "Tab",
+        "action": "Focuses the play, pause or replay control, the copy button, then the screen, which scrolls with the arrow keys."
+      }
+    ],
+    "notes": [
+      "The screen is a named region holding the whole transcript for assistive technology; the characters being typed are hidden from it — never read letter by letter.",
+      "It starts when it scrolls into view and waits while it is off screen; a control pauses it, plays it or replays it (WCAG 2.2.2).",
+      "Under `prefers-reduced-motion`, without JavaScript and before it plays, the whole session is shown at rest; the caret does not blink.",
+      "The copy button says it copied in a polite live region."
+    ]
+  },
+  "related": [
+    "kbd",
+    "video-player",
+    "stepper"
+  ],
+  "web": {
+    "entry": "@krizaka/ui/terminal-replay",
+    "import": "import { TerminalReplay } from \"@krizaka/ui/terminal-replay\";",
+    "props": [
+      {
+        "component": "TerminalReplay",
+        "description": "A terminal session played back: commands typed at the prompt, their output line by line — or the whole session at rest.",
+        "props": [
+          {
+            "name": "label",
+            "type": "string",
+            "default": null,
+            "description": "The accessible name of the screen (“Terminal session: install, start, dev”) — passed translated.",
+            "required": true
+          },
+          {
+            "name": "pauseLabel",
+            "type": "string",
+            "default": null,
+            "description": "The pause button's words (the replay is running).",
+            "required": true
+          },
+          {
+            "name": "playLabel",
+            "type": "string",
+            "default": null,
+            "description": "The play button's words (the replay is waiting or paused).",
+            "required": true
+          },
+          {
+            "name": "replayLabel",
+            "type": "string",
+            "default": null,
+            "description": "The replay button's words (the session is shown whole).",
+            "required": true
+          },
+          {
+            "name": "steps",
+            "type": "readonly TerminalStep[]",
+            "default": null,
+            "description": "The session, in order.",
+            "required": true
+          },
+          {
+            "name": "autoPlay",
+            "type": "boolean",
+            "default": "true",
+            "description": "Plays the first time it scrolls into view. `false`: the session rests whole until the reader presses play.",
+            "required": false
+          },
+          {
+            "name": "copiedLabel",
+            "type": "string",
+            "default": null,
+            "description": "What the copy button says once the commands are copied (announced politely).",
+            "required": false
+          },
+          {
+            "name": "copyLabel",
+            "type": "string",
+            "default": null,
+            "description": "The copy button's words: it copies the commands, one per line. Without it, no copy button.",
+            "required": false
+          },
+          {
+            "name": "lineDelay",
+            "type": "number",
+            "default": "70",
+            "description": "Milliseconds between two output lines.",
+            "required": false
+          },
+          {
+            "name": "prompt",
+            "type": "string",
+            "default": "$",
+            "description": "What the prompt shows before each command.",
+            "required": false
+          },
+          {
+            "name": "rows",
+            "type": "number",
+            "default": "18",
+            "description": "The screen's height, in lines; longer sessions scroll.",
+            "required": false
+          },
+          {
+            "name": "stepDelay",
+            "type": "number",
+            "default": "900",
+            "description": "Milliseconds between a command's last line and the next command.",
+            "required": false
+          },
+          {
+            "name": "title",
+            "type": "ReactNode",
+            "default": null,
+            "description": "The window's title, shown in its bar (`~/projects — zsh`).",
+            "required": false
+          },
+          {
+            "name": "typingSpeed",
+            "type": "number",
+            "default": "34",
+            "description": "Milliseconds per typed character.",
+            "required": false
+          }
+        ]
+      }
+    ],
+    "examples": [
+      {
+        "name": "session",
+        "title": "A session",
+        "description": "Three commands typed one after the other, their output line by line; it starts when it scrolls into view.",
+        "path": "examples/terminal-replay/session.tsx",
+        "module": "@krizaka/ui/registry/examples/terminal-replay/session",
+        "code": "import { TerminalReplay } from \"@krizaka/ui/terminal-replay\";\n\n// A real session played back: each command typed at the prompt, then its output, line by line.\nexport default function TerminalReplaySession() {\n  return (\n    <TerminalReplay\n      label=\"Terminal session: create, install, start\"\n      title=\"~/projects — zsh\"\n      playLabel=\"Play\"\n      pauseLabel=\"Pause\"\n      replayLabel=\"Replay\"\n      copyLabel=\"Copy commands\"\n      copiedLabel=\"Copied\"\n      rows={12}\n      steps={[\n        { command: \"mkdir shop && cd shop\", output: [] },\n        {\n          command: \"npm install @krizaka/ui\",\n          output: [{ text: \"added 12 packages in 2s\", tone: \"success\" }, { text: \"found 0 vulnerabilities\", tone: \"muted\" }],\n        },\n        {\n          command: \"npm run dev\",\n          output: [{ text: \"▲ Next.js 16\", tone: \"accent\" }, \"- Local: http://localhost:3000\", { text: \"✓ Ready in 1.4s\", tone: \"success\" }],\n        },\n      ]}\n    />\n  );\n}\n"
+      },
+      {
+        "name": "at-rest",
+        "title": "At rest",
+        "description": "`autoPlay={false}`: the whole session is shown until the reader presses play — a page that should stay still.",
+        "path": "examples/terminal-replay/at-rest.tsx",
+        "module": "@krizaka/ui/registry/examples/terminal-replay/at-rest",
+        "code": "import { TerminalReplay } from \"@krizaka/ui/terminal-replay\";\n\n// At rest: the whole session is there to read; it plays only when the reader presses play.\nexport default function TerminalReplayAtRest() {\n  return (\n    <TerminalReplay\n      autoPlay={false}\n      label=\"Terminal session: check the tools\"\n      title=\"~/projects — zsh\"\n      playLabel=\"Play\"\n      pauseLabel=\"Pause\"\n      replayLabel=\"Replay\"\n      rows={7}\n      steps={[\n        {\n          command: \"node --version && git --version\",\n          output: [\"v22.12.0\", \"git version 2.47.1\"],\n        },\n        {\n          command: \"docker compose version\",\n          output: [{ text: \"Docker Compose version v2.31.0\", tone: \"success\" }],\n        },\n      ]}\n    />\n  );\n}\n"
+      }
+    ]
+  },
+  "native": null,
+  "files": [
+    {
+      "path": "glyphs.tsx",
+      "content": "// The small line glyphs the data and media primitives draw (play, volume, search, chevrons…): decorative, 24-unit\n// box, `currentColor`, sized by the caller's class. Shared by the entries that need them; never exported on its own —\n// a product draws its own icons with @krizaka/icons.\nimport type * as React from \"react\";\n\ntype GlyphProps = { className?: string };\n\nfunction Glyph({ className = \"h-4 w-4\", fill, children }: GlyphProps & { fill?: boolean; children: React.ReactNode }) {\n  return (\n    <svg\n      viewBox=\"0 0 24 24\"\n      className={className}\n      fill={fill ? \"currentColor\" : \"none\"}\n      stroke={fill ? \"none\" : \"currentColor\"}\n      strokeWidth=\"2\"\n      strokeLinecap=\"round\"\n      strokeLinejoin=\"round\"\n      aria-hidden\n      focusable=\"false\"\n    >\n      {children}\n    </svg>\n  );\n}\n\nexport const PlayGlyph = (p: GlyphProps) => (\n  <Glyph {...p} fill>\n    <path d=\"M8 5.5v13a1 1 0 0 0 1.5.86l10.4-6.5a1 1 0 0 0 0-1.72L9.5 4.64A1 1 0 0 0 8 5.5Z\" />\n  </Glyph>\n);\nexport const PauseGlyph = (p: GlyphProps) => (\n  <Glyph {...p} fill>\n    <rect x=\"6\" y=\"5\" width=\"4\" height=\"14\" rx=\"1\" />\n    <rect x=\"14\" y=\"5\" width=\"4\" height=\"14\" rx=\"1\" />\n  </Glyph>\n);\nexport const VolumeGlyph = ({ muted, ...p }: GlyphProps & { muted?: boolean }) => (\n  <Glyph {...p}>\n    <path d=\"M11 5 6 9H3v6h3l5 4V5Z\" />\n    {muted ? <path d=\"m22 9-6 6m0-6 6 6\" /> : <path d=\"M15.5 8.5a5 5 0 0 1 0 7M18.5 5.5a9 9 0 0 1 0 13\" />}\n  </Glyph>\n);\nexport const FullscreenGlyph = ({ exit, ...p }: GlyphProps & { exit?: boolean }) => (\n  <Glyph {...p}>\n    {exit ? <path d=\"M9 4v5H4m11-5v5h5M9 20v-5H4m11 5v-5h5\" /> : <path d=\"M4 9V4h5m6 0h5v5M4 15v5h5m11-5v5h-5\" />}\n  </Glyph>\n);\nexport const CaptionsGlyph = (p: GlyphProps) => (\n  <Glyph {...p}>\n    <rect x=\"3\" y=\"5\" width=\"18\" height=\"14\" rx=\"2\" />\n    <path d=\"M10 10.5a2 2 0 1 0 0 3M17 10.5a2 2 0 1 0 0 3\" />\n  </Glyph>\n);\nexport const PipGlyph = (p: GlyphProps) => (\n  <Glyph {...p}>\n    <rect x=\"3\" y=\"5\" width=\"18\" height=\"14\" rx=\"2\" />\n    <rect x=\"12\" y=\"12\" width=\"6\" height=\"4\" rx=\"1\" />\n  </Glyph>\n);\nexport const SearchGlyph = (p: GlyphProps) => (\n  <Glyph {...p}>\n    <circle cx=\"11\" cy=\"11\" r=\"7\" />\n    <path d=\"m20 20-3.5-3.5\" />\n  </Glyph>\n);\nexport const CloseGlyph = (p: GlyphProps) => (\n  <Glyph {...p}>\n    <path d=\"M18 6 6 18M6 6l12 12\" />\n  </Glyph>\n);\nexport const ChevronGlyph = ({ direction = \"down\", ...p }: GlyphProps & { direction?: \"left\" | \"right\" | \"up\" | \"down\" }) => (\n  <Glyph {...p}>\n    <path d={{ left: \"m15 6-6 6 6 6\", right: \"m9 6 6 6-6 6\", up: \"m6 15 6-6 6 6\", down: \"m6 9 6 6 6-6\" }[direction]} />\n  </Glyph>\n);\nexport const CheckGlyph = (p: GlyphProps) => (\n  <Glyph {...p}>\n    <path d=\"M20 6 9 17l-5-5\" />\n  </Glyph>\n);\nexport const PlusGlyph = (p: GlyphProps) => (\n  <Glyph {...p}>\n    <path d=\"M12 5v14M5 12h14\" />\n  </Glyph>\n);\nexport const CalendarGlyph = (p: GlyphProps) => (\n  <Glyph {...p}>\n    <rect x=\"3\" y=\"5\" width=\"18\" height=\"16\" rx=\"2\" />\n    <path d=\"M3 10h18M8 3v4M16 3v4\" />\n  </Glyph>\n);\nexport const UploadGlyph = (p: GlyphProps) => (\n  <Glyph {...p}>\n    <path d=\"M12 16V4m0 0L7 9m5-5 5 5\" />\n    <path d=\"M4 16v2a2 2 0 0 0 2 2h12a2 2 0 0 0 2-2v-2\" />\n  </Glyph>\n);\nexport const FileGlyph = (p: GlyphProps) => (\n  <Glyph {...p}>\n    <path d=\"M14 3H7a2 2 0 0 0-2 2v14a2 2 0 0 0 2 2h10a2 2 0 0 0 2-2V8l-5-5Z\" />\n    <path d=\"M14 3v5h5\" />\n  </Glyph>\n);\nexport const CameraGlyph = (p: GlyphProps) => (\n  <Glyph {...p}>\n    <path d=\"M4 8h3l2-3h6l2 3h3a1 1 0 0 1 1 1v10a1 1 0 0 1-1 1H4a1 1 0 0 1-1-1V9a1 1 0 0 1 1-1Z\" />\n    <circle cx=\"12\" cy=\"13.5\" r=\"3.5\" />\n  </Glyph>\n);\nexport const FlipGlyph = (p: GlyphProps) => (\n  <Glyph {...p}>\n    <path d=\"M4 12a8 8 0 0 1 14-5.3M20 12a8 8 0 0 1-14 5.3\" />\n    <path d=\"M18 3v4h-4M6 21v-4h4\" />\n  </Glyph>\n);\nexport const RetryGlyph = (p: GlyphProps) => (\n  <Glyph {...p}>\n    <path d=\"M4 12a8 8 0 1 0 2.3-5.7L4 8.5\" />\n    <path d=\"M4 4v4.5h4.5\" />\n  </Glyph>\n);\nexport const SortGlyph = ({ direction, ...p }: GlyphProps & { direction?: \"ascending\" | \"descending\" }) => (\n  <Glyph {...p}>\n    {direction === \"ascending\" ? <path d=\"m7 14 5-5 5 5\" /> : direction === \"descending\" ? <path d=\"m7 10 5 5 5-5\" /> : <path d=\"m8 9 4-4 4 4M8 15l4 4 4-4\" />}\n  </Glyph>\n);\nexport const ArrowGlyph = ({ direction = \"right\", ...p }: GlyphProps & { direction?: \"left\" | \"right\" }) => (\n  <Glyph {...p}>\n    <path d={direction === \"left\" ? \"M19 12H5m0 0 6-6m-6 6 6 6\" : \"M5 12h14m0 0-6-6m6 6-6 6\"} />\n  </Glyph>\n);\nexport const ExternalGlyph = (p: GlyphProps) => (\n  <Glyph {...p}>\n    <path d=\"M14 4h6v6M20 4l-9 9\" />\n    <path d=\"M18 14v4a2 2 0 0 1-2 2H6a2 2 0 0 1-2-2V8a2 2 0 0 1 2-2h4\" />\n  </Glyph>\n);\nexport const WarningGlyph = (p: GlyphProps) => (\n  <Glyph {...p}>\n    <path d=\"M12 4 2.5 20h19L12 4Z\" />\n    <path d=\"M12 10v4M12 17.2v.1\" />\n  </Glyph>\n);\nexport const CopyGlyph = (p: GlyphProps) => (\n  <Glyph {...p}>\n    <rect x=\"9\" y=\"9\" width=\"11\" height=\"11\" rx=\"2\" />\n    <path d=\"M15 9V6a2 2 0 0 0-2-2H6a2 2 0 0 0-2 2v7a2 2 0 0 0 2 2h3\" />\n  </Glyph>\n);\n"
+    },
+    {
+      "path": "meta.ts",
+      "content": "// The documentation of a component, carried by its code: each primitive has a `meta.ts` beside its source\n// (`src/<name>/meta.ts`; a component that exists only in React Native: `src/native/meta/<name>.ts`). Never built into\n// the package: `scripts/build-registry.mjs` reads them into `registry/<name>.json`, which krizaka.com renders as\n// /docs/ui/<name>, and `scripts/registry.test.mjs` fails when one is missing or incomplete.\n//\n// Why a typed module and not JSDoc tags: the fields are lists and links (`related`, `whenNotToUse[].use`, examples),\n// which a type checks and a comment does not; the file is plain data (erasable TypeScript), so Node reads it without a\n// compiler, and an editor completes it.\n\n/** Every documented component: the web primitives (one entry of the package each) and the native-only ones. */\nexport type ComponentName =\n  | \"action-bar\"\n  | \"alert\"\n  | \"argument-card\"\n  | \"audio-player\"\n  | \"avatar\"\n  | \"badge\"\n  | \"button\"\n  | \"card\"\n  | \"card-grid\"\n  | \"checkbox\"\n  | \"chip\"\n  | \"chip-link\"\n  | \"cn\"\n  | \"code-block\"\n  | \"combobox\"\n  | \"command\"\n  | \"confirm-button\"\n  | \"countdown\"\n  | \"cta-panel\"\n  | \"data-table\"\n  | \"date-picker\"\n  | \"decision-list\"\n  | \"dialog\"\n  | \"dropdown-menu\"\n  | \"empty-state\"\n  | \"field\"\n  | \"file-upload\"\n  | \"filter-bar\"\n  | \"glow-card\"\n  | \"image-cropper\"\n  | \"iso\"\n  | \"kbd\"\n  | \"link-card\"\n  | \"loader\"\n  | \"marquee\"\n  | \"mascot-quote\"\n  | \"mascots\"\n  | \"media-capture\"\n  | \"meter\"\n  | \"nav-bar\"\n  | \"number-ticker\"\n  | \"page\"\n  | \"page-header\"\n  | \"page-hero\"\n  | \"pagination\"\n  | \"pointer-light\"\n  | \"popover\"\n  | \"progress\"\n  | \"radio-group\"\n  | \"search-field\"\n  | \"section-backdrop\"\n  | \"segmented\"\n  | \"separator\"\n  | \"skeleton\"\n  | \"slider\"\n  | \"slot\"\n  | \"spinner\"\n  | \"stat\"\n  | \"stepper\"\n  | \"switch\"\n  | \"tabs\"\n  | \"tag-input\"\n  | \"terminal-replay\"\n  | \"theme\"\n  | \"toast\"\n  | \"toc\"\n  | \"tooltip\"\n  | \"txt\"\n  | \"video-player\"\n  | \"video-trimmer\";\n\n/** Where a component exists: `@krizaka/ui/<name>` (web), `@krizaka/ui/native` (React Native), or both. */\nexport type Platform = \"web\" | \"native\" | \"both\";\n\n/** `stable`: its API only changes in a major. `beta`: it may still change in a minor. */\nexport type Status = \"stable\" | \"beta\";\n\n/**\n * The group of the catalogue. `media`: video, sound, camera, files, cropping. `blocks`: the page blocks — the frame,\n * the hero, sections, cards that lead or argue, decisions, code, calls to act — that every page of a site is made of.\n */\nexport type Category = \"actions\" | \"forms\" | \"navigation\" | \"overlays\" | \"feedback\" | \"data-display\" | \"media\" | \"blocks\" | \"layout\" | \"foundations\";\n\n/**\n * A named example: the file `registry/examples/<component>/<name>.tsx` (web) or\n * `registry/examples/<component>/native/<name>.tsx` (React Native) — at most 40 lines, imported by the stories and\n * shown (live, with its code) by the documentation.\n */\nexport interface Example {\n  /** The file name, kebab-case (`primary`, `icon-button`). */\n  readonly name: string;\n  /** A short title (`Primary`, `Icon button`). */\n  readonly title: string;\n  /** One or two sentences: when this variant is the right one. */\n  readonly description: string;\n}\n\n/** One platform's side of a component. */\nexport interface PlatformDocs {\n  /** The names to import (`[\"Button\", \"IconButton\"]`): from `@krizaka/ui/<name>` on the web, `@krizaka/ui/native` in React Native. */\n  readonly imports: readonly string[];\n  /** The examples, in reading order; the first one is the component's preview. */\n  readonly examples: readonly Example[];\n}\n\n/** The React Native side: the same concept, and what differs from the web API. */\nexport interface NativeDocs extends PlatformDocs {\n  /**\n   * The entry to import from when it is not `@krizaka/ui/native`: a component that needs an Expo module (an optional\n   * peer) has its own, `@krizaka/ui/native/<name>`, so an app that does not use it never installs the module.\n   */\n  readonly entry?: string;\n  /** What differs from the web API (`label` instead of children…); empty for a native-only component. */\n  readonly differences: readonly string[];\n}\n\nexport interface KeyboardInteraction {\n  /** The keys, as written on a keyboard: `Space`, `Enter`, `Arrow keys`, `Esc`, `Tab`. */\n  readonly keys: string;\n  /** What they do. */\n  readonly action: string;\n}\n\nexport interface ComponentMeta {\n  /** The display name: `Button`, `Dropdown menu`. */\n  readonly title: string;\n  /** One sentence: what it is. */\n  readonly summary: string;\n  readonly status: Status;\n  readonly category: Category;\n  /** Must match the sides below: `both` ⇔ `web` and `native`. */\n  readonly platforms: Platform;\n  /** When to reach for it: concrete situations, one per item. */\n  readonly whenToUse: readonly string[];\n  /** When not to — and what to use instead (`use`), when another component is the answer. */\n  readonly whenNotToUse: readonly { readonly when: string; readonly use?: ComponentName }[];\n  /** How to use it well: wording, placement, composition. */\n  readonly bestPractices: readonly string[];\n  readonly accessibility: {\n    /** The keyboard, when it does more than Tab and Enter. */\n    readonly keyboard: readonly KeyboardInteraction[];\n    /** Roles, names and announcements: what the component does, what the app must provide. */\n    readonly notes: readonly string[];\n  };\n  /** The components a reader of this page should know about. */\n  readonly related: readonly ComponentName[];\n  readonly web?: PlatformDocs;\n  readonly native?: NativeDocs;\n}\n"
+    },
+    {
+      "path": "terminal-replay/index.ts",
+      "content": "/** @krizaka/ui/terminal-replay — `TerminalReplay`: a terminal session played back, command by command, or shown whole at rest. Client. */\nexport { type TerminalLine, TerminalReplay, type TerminalReplayProps, type TerminalStep, type TerminalTone } from \"./terminal-replay\";\n"
+    },
+    {
+      "path": "terminal-replay/meta.ts",
+      "content": "import type { ComponentMeta } from \"../meta\";\n\nexport const meta = {\n  title: \"Terminal replay\",\n  summary:\n    \"A terminal session played back: each command typed at the prompt, its output line by line, the screen following the last line — or the whole session at rest, as the server renders it.\",\n  status: \"beta\",\n  category: \"media\",\n  platforms: \"web\",\n  whenToUse: [\n    \"Show how a command-line tool works from a recording of a real session: install, start, run.\",\n    \"A getting-started page where the reader should see the order of the commands and what each one answers.\",\n  ],\n  whenNotToUse: [\n    { when: \"For commands the reader copies and runs, with nothing to watch.\", use: \"kbd\" },\n    { when: \"For a video of an application's screens: record the screens, not a terminal.\", use: \"video-player\" },\n    { when: \"For output you wrote by hand: replay what the tool really printed, or show none.\" },\n  ],\n  bestPractices: [\n    \"Replay a real session, captured from the tool itself — never an invented output.\",\n    \"Keep each step short: a long output is trimmed where it repeats, and says it was trimmed.\",\n    \"Name the screen (`label`) by what it shows; the words of the controls arrive as props, translated.\",\n    \"Give the copy button (`copyLabel`) when the commands are meant to be run.\",\n  ],\n  accessibility: {\n    keyboard: [\n      { keys: \"Tab\", action: \"Focuses the play, pause or replay control, the copy button, then the screen, which scrolls with the arrow keys.\" },\n    ],\n    notes: [\n      \"The screen is a named region holding the whole transcript for assistive technology; the characters being typed are hidden from it — never read letter by letter.\",\n      \"It starts when it scrolls into view and waits while it is off screen; a control pauses it, plays it or replays it (WCAG 2.2.2).\",\n      \"Under `prefers-reduced-motion`, without JavaScript and before it plays, the whole session is shown at rest; the caret does not blink.\",\n      \"The copy button says it copied in a polite live region.\",\n    ],\n  },\n  related: [\"kbd\", \"video-player\", \"stepper\"],\n  web: {\n    imports: [\"TerminalReplay\"],\n    examples: [\n      { name: \"session\", title: \"A session\", description: \"Three commands typed one after the other, their output line by line; it starts when it scrolls into view.\" },\n      { name: \"at-rest\", title: \"At rest\", description: \"`autoPlay={false}`: the whole session is shown until the reader presses play — a page that should stay still.\" },\n    ],\n  },\n} satisfies ComponentMeta;\n"
+    },
+    {
+      "path": "terminal-replay/terminal-replay.tsx",
+      "content": "// Client (a timer, an observer). A terminal session played back: each command is typed at the prompt, its output\n// arrives line by line, the screen follows the last line like a real terminal. What a reader sees without the motion\n// is the session itself: the server renders it whole (no JavaScript, reduced motion and assistive technology all get\n// the full transcript), the screen has a fixed height (no layout shift while it plays), the replay starts when it\n// scrolls into view, waits while it is off screen, and pauses or replays on demand (WCAG 2.2.2). A bounded chain of\n// timeouts, never a permanent animation frame.\nimport * as React from \"react\";\n\nimport { cn } from \"../cn\";\nimport { CheckGlyph, PauseGlyph, PlayGlyph, RetryGlyph } from \"../glyphs\";\n\n/** The colour of an output line — the tokens' text roles, all AA on the screen: secondary, accent, success, warning, danger. */\nexport type TerminalTone = \"muted\" | \"accent\" | \"success\" | \"warning\" | \"danger\";\n\nexport interface TerminalLine {\n  /** The line as the program printed it (no colour codes). */\n  text: string;\n  /** Its colour, when the program coloured it. */\n  tone?: TerminalTone;\n}\n\nexport interface TerminalStep {\n  /** What is typed at the prompt (`npx orazaka install`). */\n  command: string;\n  /** What it printed, line by line. */\n  output?: readonly (string | TerminalLine)[];\n}\n\nexport type TerminalReplayProps = Omit<React.ComponentProps<\"figure\">, \"children\" | \"title\"> & {\n  /** The session, in order. */\n  steps: readonly TerminalStep[];\n  /** The accessible name of the screen (“Terminal session: install, start, dev”) — passed translated. */\n  label: string;\n  /** The window's title, shown in its bar (`~/projects — zsh`). */\n  title?: React.ReactNode;\n  /**\n   * What the prompt shows before each command.\n   * @default \"$\"\n   */\n  prompt?: string;\n  /** The play button's words (the replay is waiting or paused). */\n  playLabel: string;\n  /** The pause button's words (the replay is running). */\n  pauseLabel: string;\n  /** The replay button's words (the session is shown whole). */\n  replayLabel: string;\n  /** The copy button's words: it copies the commands, one per line. Without it, no copy button. */\n  copyLabel?: string;\n  /** What the copy button says once the commands are copied (announced politely). */\n  copiedLabel?: string;\n  /**\n   * Milliseconds per typed character.\n   * @default 34\n   */\n  typingSpeed?: number;\n  /**\n   * Milliseconds between two output lines.\n   * @default 70\n   */\n  lineDelay?: number;\n  /**\n   * Milliseconds between a command's last line and the next command.\n   * @default 900\n   */\n  stepDelay?: number;\n  /**\n   * The screen's height, in lines; longer sessions scroll.\n   * @default 18\n   */\n  rows?: number;\n  /**\n   * Plays the first time it scrolls into view. `false`: the session rests whole until the reader presses play.\n   * @default true\n   */\n  autoPlay?: boolean;\n};\n\ntype Phase = \"final\" | \"idle\" | \"playing\" | \"paused\" | \"done\";\ninterface Position {\n  step: number;\n  chars: number;\n  lines: number;\n}\n\nconst TONE: Record<TerminalTone, string> = {\n  muted: \"text-fg-secondary\",\n  accent: \"text-fg-accent\",\n  success: \"text-fg-success\",\n  warning: \"text-fg-warning\",\n  danger: \"text-fg-danger\",\n};\n\nconst line = (entry: string | TerminalLine): TerminalLine => (typeof entry === \"string\" ? { text: entry } : entry);\n\n/** The next position of the replay and how long to wait for it; null at the end of the session. */\nfunction advance(steps: readonly TerminalStep[], pos: Position, timing: { typing: number; line: number; step: number }): [Position, number] | null {\n  const current = steps[pos.step];\n  if (!current) return null;\n  const output = current.output ?? [];\n  if (pos.chars < current.command.length) {\n    // A space is a beat longer: the rhythm of someone typing, not of a printer.\n    const pause = current.command[pos.chars] === \" \" ? timing.typing * 2 : timing.typing;\n    return [{ ...pos, chars: pos.chars + 1 }, pause];\n  }\n  if (pos.lines < output.length) return [{ ...pos, lines: pos.lines + 1 }, pos.lines === 0 ? timing.line * 4 : timing.line];\n  if (pos.step < steps.length - 1) return [{ step: pos.step + 1, chars: 0, lines: 0 }, timing.step];\n  return null;\n}\n\n/** A terminal session played back: commands typed at the prompt, their output line by line — or the whole session at rest. */\nexport function TerminalReplay({\n  steps,\n  label,\n  title,\n  prompt = \"$\",\n  playLabel,\n  pauseLabel,\n  replayLabel,\n  copyLabel,\n  copiedLabel,\n  typingSpeed = 34,\n  lineDelay = 70,\n  stepDelay = 900,\n  rows = 18,\n  autoPlay = true,\n  className,\n  style,\n  ...props\n}: TerminalReplayProps) {\n  const root = React.useRef<HTMLElement>(null);\n  const screenRef = React.useRef<HTMLDivElement>(null);\n  // The server renders the session whole; the client takes it over unless the reader asked for less motion.\n  const [phase, setPhase] = React.useState<Phase>(\"final\");\n  const [pos, setPos] = React.useState<Position>({ step: 0, chars: 0, lines: 0 });\n  const [visible, setVisible] = React.useState(false);\n  const [copied, setCopied] = React.useState(false);\n\n  React.useEffect(() => {\n    const el = root.current;\n    if (!el || !autoPlay || window.matchMedia(\"(prefers-reduced-motion: reduce)\").matches) return;\n    setPhase(\"idle\");\n    // Starts the first time it is seen; off screen, it waits where it is.\n    const io = new IntersectionObserver(\n      ([entry]) => {\n        const seen = Boolean(entry?.isIntersecting);\n        setVisible(seen);\n        if (seen) setPhase((current) => (current === \"idle\" ? \"playing\" : current));\n      },\n      { threshold: 0.35 },\n    );\n    io.observe(el);\n    return () => io.disconnect();\n  }, [autoPlay]);\n\n  const ended = phase === \"playing\" && !advance(steps, pos, { typing: typingSpeed, line: lineDelay, step: stepDelay });\n  // The end of the session is where the replay stands, not an event: derived, never set from an effect.\n  const state: Phase = ended ? \"done\" : phase;\n\n  React.useEffect(() => {\n    if (phase !== \"playing\" || !visible) return;\n    const next = advance(steps, pos, { typing: typingSpeed, line: lineDelay, step: stepDelay });\n    if (!next) return;\n    const timer = setTimeout(() => setPos(next[0]), next[1]);\n    return () => clearTimeout(timer);\n  }, [phase, visible, pos, steps, typingSpeed, lineDelay, stepDelay]);\n\n  // The screen follows the last line while it plays, like a terminal.\n  React.useEffect(() => {\n    const el = screenRef.current;\n    if (el && state === \"playing\") el.scrollTop = el.scrollHeight;\n  }, [pos, state]);\n\n  React.useEffect(() => {\n    if (!copied) return;\n    const timer = setTimeout(() => setCopied(false), 1800);\n    return () => clearTimeout(timer);\n  }, [copied]);\n\n  const whole = state === \"final\" || state === \"done\";\n  const shown = whole ? steps.length - 1 : pos.step;\n  const toggle = () => {\n    if (state === \"playing\") setPhase(\"paused\");\n    else if (state === \"paused\" || state === \"idle\") setPhase(\"playing\");\n    else {\n      // Played on demand — also under reduced motion: the reader asked for it. Off screen it would wait: it is on screen.\n      setVisible(true);\n      setPos({ step: 0, chars: 0, lines: 0 });\n      setPhase(\"playing\");\n    }\n  };\n  const control =\n    state === \"playing\"\n      ? { text: pauseLabel, Glyph: PauseGlyph }\n      : state === \"done\"\n        ? { text: replayLabel, Glyph: RetryGlyph }\n        : { text: playLabel, Glyph: PlayGlyph };\n  const commands = steps.map((s) => s.command).join(\"\\n\");\n  const transcript = steps.map((s) => [`${prompt} ${s.command}`, ...(s.output ?? []).map((o) => line(o).text)].join(\"\\n\")).join(\"\\n\\n\");\n\n  return (\n    <figure\n      ref={root}\n      data-state={state}\n      data-autoplay={autoPlay ? \"\" : undefined}\n      className={cn(\"kz-replay overflow-hidden rounded-xl border border-border-default bg-surface-1 shadow-md\", className)}\n      style={{ \"--kz-replay-rows\": rows, ...style } as React.CSSProperties}\n      {...props}\n    >\n      <figcaption className=\"flex items-center gap-3 border-b border-border-subtle bg-surface-2 px-3 py-2 text-xs text-fg-secondary\">\n        <span aria-hidden className=\"flex shrink-0 gap-1.5\">\n          <span className=\"h-2.5 w-2.5 rounded-full bg-border-strong\" />\n          <span className=\"h-2.5 w-2.5 rounded-full bg-border-strong\" />\n          <span className=\"h-2.5 w-2.5 rounded-full bg-border-strong\" />\n        </span>\n        <span className=\"min-w-0 flex-1 truncate font-mono\">{title}</span>\n        <button\n          type=\"button\"\n          onClick={toggle}\n          className=\"inline-flex shrink-0 items-center gap-1.5 rounded-md px-2 py-1 font-medium text-fg-secondary transition-colors hover:bg-surface-3 hover:text-fg focus-visible:outline-2 focus-visible:outline-ring\"\n        >\n          <control.Glyph className=\"h-3.5 w-3.5\" />\n          {control.text}\n        </button>\n        {copyLabel && (\n          <button\n            type=\"button\"\n            onClick={() => navigator.clipboard?.writeText(commands).then(() => setCopied(true))}\n            data-copied={copied ? \"\" : undefined}\n            className=\"inline-flex shrink-0 items-center gap-1.5 rounded-md px-2 py-1 font-medium text-fg-secondary transition-colors hover:bg-surface-3 hover:text-fg focus-visible:outline-2 focus-visible:outline-ring\"\n          >\n            {copied ? <CheckGlyph className=\"h-3.5 w-3.5\" /> : <CopyGlyph />}\n            <span aria-live=\"polite\">{copied ? (copiedLabel ?? copyLabel) : copyLabel}</span>\n          </button>\n        )}\n      </figcaption>\n      <div\n        ref={screenRef}\n        role=\"region\"\n        aria-label={label}\n        tabIndex={0}\n        className=\"kz-replay-screen relative overflow-auto bg-surface-0 px-4 py-3 font-mono text-[0.8125rem] leading-relaxed text-fg focus-visible:outline-2 focus-visible:-outline-offset-2 focus-visible:outline-ring\"\n      >\n        <div aria-hidden className=\"kz-replay-live\">\n          {steps.slice(0, state === \"idle\" ? 0 : shown + 1).map((step, i) => {\n            const current = !whole && i === shown;\n            const typed = current ? step.command.slice(0, pos.chars) : step.command;\n            const output = (step.output ?? []).slice(0, current ? pos.lines : undefined);\n            const typing = current && pos.chars < step.command.length;\n            return (\n              <div key={i} className={i > 0 ? \"mt-3\" : undefined}>\n                <div className=\"whitespace-pre\">\n                  <span className=\"text-fg-accent select-none\">{prompt} </span>\n                  <span className=\"font-medium\">{typed}</span>\n                  {typing && <span className=\"kz-replay-caret\" />}\n                </div>\n                {output.map((entry, j) => {\n                  const { text, tone } = line(entry);\n                  return (\n                    <div key={j} className={cn(\"min-h-[1lh] whitespace-pre\", tone ? TONE[tone] : \"text-fg\")}>\n                      {text}\n                    </div>\n                  );\n                })}\n              </div>\n            );\n          })}\n          {(state === \"idle\" || whole) && (\n            <div className={cn(\"whitespace-pre\", state !== \"idle\" && \"mt-3\")}>\n              <span className=\"text-fg-accent select-none\">{prompt} </span>\n              <span className=\"kz-replay-caret\" />\n            </div>\n          )}\n        </div>\n        <pre className=\"sr-only\">{transcript}</pre>\n      </div>\n    </figure>\n  );\n}\n\n/** Two sheets, one over the other: copy. Drawn here, like the other glyphs of the primitives (decorative). */\nfunction CopyGlyph() {\n  return (\n    <svg viewBox=\"0 0 24 24\" className=\"h-3.5 w-3.5\" fill=\"none\" stroke=\"currentColor\" strokeWidth=\"2\" strokeLinecap=\"round\" strokeLinejoin=\"round\" aria-hidden focusable=\"false\">\n      <rect x=\"9\" y=\"9\" width=\"11\" height=\"11\" rx=\"2\" />\n      <path d=\"M5 15V6a2 2 0 0 1 2-2h8\" />\n    </svg>\n  );\n}\n"
+    }
+  ],
+  "dependencies": [],
+  "registryDependencies": [
+    "cn"
+  ],
+  "demo": {
+    "path": "examples/terminal-replay/session.tsx",
+    "content": "import { TerminalReplay } from \"@krizaka/ui/terminal-replay\";\n\n// A real session played back: each command typed at the prompt, then its output, line by line.\nexport default function TerminalReplaySession() {\n  return (\n    <TerminalReplay\n      label=\"Terminal session: create, install, start\"\n      title=\"~/projects — zsh\"\n      playLabel=\"Play\"\n      pauseLabel=\"Pause\"\n      replayLabel=\"Replay\"\n      copyLabel=\"Copy commands\"\n      copiedLabel=\"Copied\"\n      rows={12}\n      steps={[\n        { command: \"mkdir shop && cd shop\", output: [] },\n        {\n          command: \"npm install @krizaka/ui\",\n          output: [{ text: \"added 12 packages in 2s\", tone: \"success\" }, { text: \"found 0 vulnerabilities\", tone: \"muted\" }],\n        },\n        {\n          command: \"npm run dev\",\n          output: [{ text: \"▲ Next.js 16\", tone: \"accent\" }, \"- Local: http://localhost:3000\", { text: \"✓ Ready in 1.4s\", tone: \"success\" }],\n        },\n      ]}\n    />\n  );\n}\n"
+  },
+  "props": [
+    {
+      "component": "TerminalReplay",
+      "description": "A terminal session played back: commands typed at the prompt, their output line by line — or the whole session at rest.",
+      "props": [
+        {
+          "name": "label",
+          "type": "string",
+          "default": null,
+          "description": "The accessible name of the screen (“Terminal session: install, start, dev”) — passed translated.",
+          "required": true
+        },
+        {
+          "name": "pauseLabel",
+          "type": "string",
+          "default": null,
+          "description": "The pause button's words (the replay is running).",
+          "required": true
+        },
+        {
+          "name": "playLabel",
+          "type": "string",
+          "default": null,
+          "description": "The play button's words (the replay is waiting or paused).",
+          "required": true
+        },
+        {
+          "name": "replayLabel",
+          "type": "string",
+          "default": null,
+          "description": "The replay button's words (the session is shown whole).",
+          "required": true
+        },
+        {
+          "name": "steps",
+          "type": "readonly TerminalStep[]",
+          "default": null,
+          "description": "The session, in order.",
+          "required": true
+        },
+        {
+          "name": "autoPlay",
+          "type": "boolean",
+          "default": "true",
+          "description": "Plays the first time it scrolls into view. `false`: the session rests whole until the reader presses play.",
+          "required": false
+        },
+        {
+          "name": "copiedLabel",
+          "type": "string",
+          "default": null,
+          "description": "What the copy button says once the commands are copied (announced politely).",
+          "required": false
+        },
+        {
+          "name": "copyLabel",
+          "type": "string",
+          "default": null,
+          "description": "The copy button's words: it copies the commands, one per line. Without it, no copy button.",
+          "required": false
+        },
+        {
+          "name": "lineDelay",
+          "type": "number",
+          "default": "70",
+          "description": "Milliseconds between two output lines.",
+          "required": false
+        },
+        {
+          "name": "prompt",
+          "type": "string",
+          "default": "$",
+          "description": "What the prompt shows before each command.",
+          "required": false
+        },
+        {
+          "name": "rows",
+          "type": "number",
+          "default": "18",
+          "description": "The screen's height, in lines; longer sessions scroll.",
+          "required": false
+        },
+        {
+          "name": "stepDelay",
+          "type": "number",
+          "default": "900",
+          "description": "Milliseconds between a command's last line and the next command.",
+          "required": false
+        },
+        {
+          "name": "title",
+          "type": "ReactNode",
+          "default": null,
+          "description": "The window's title, shown in its bar (`~/projects — zsh`).",
+          "required": false
+        },
+        {
+          "name": "typingSpeed",
+          "type": "number",
+          "default": "34",
+          "description": "Milliseconds per typed character.",
+          "required": false
+        }
+      ]
+    }
+  ]
+}

package/registry/theme.json

@@ -191,7 +191,7 @@
   "files": [
     {
       "path": "meta.ts",
-      "content": "// The documentation of a component, carried by its code: each primitive has a `meta.ts` beside its source\n// (`src/<name>/meta.ts`; a component that exists only in React Native: `src/native/meta/<name>.ts`). Never built into\n// the package: `scripts/build-registry.mjs` reads them into `registry/<name>.json`, which krizaka.com renders as\n// /docs/ui/<name>, and `scripts/registry.test.mjs` fails when one is missing or incomplete.\n//\n// Why a typed module and not JSDoc tags: the fields are lists and links (`related`, `whenNotToUse[].use`, examples),\n// which a type checks and a comment does not; the file is plain data (erasable TypeScript), so Node reads it without a\n// compiler, and an editor completes it.\n\n/** Every documented component: the web primitives (one entry of the package each) and the native-only ones. */\nexport type ComponentName =\n  | \"alert\"\n  | \"audio-player\"\n  | \"avatar\"\n  | \"badge\"\n  | \"button\"\n  | \"card\"\n  | \"checkbox\"\n  | \"chip\"\n  | \"chip-link\"\n  | \"cn\"\n  | \"combobox\"\n  | \"command\"\n  | \"confirm-button\"\n  | \"countdown\"\n  | \"data-table\"\n  | \"date-picker\"\n  | \"dialog\"\n  | \"dropdown-menu\"\n  | \"empty-state\"\n  | \"field\"\n  | \"file-upload\"\n  | \"filter-bar\"\n  | \"glow-card\"\n  | \"image-cropper\"\n  | \"iso\"\n  | \"kbd\"\n  | \"loader\"\n  | \"marquee\"\n  | \"mascots\"\n  | \"media-capture\"\n  | \"meter\"\n  | \"nav-bar\"\n  | \"number-ticker\"\n  | \"page-header\"\n  | \"pagination\"\n  | \"popover\"\n  | \"progress\"\n  | \"radio-group\"\n  | \"search-field\"\n  | \"section-backdrop\"\n  | \"segmented\"\n  | \"separator\"\n  | \"skeleton\"\n  | \"slider\"\n  | \"slot\"\n  | \"spinner\"\n  | \"stat\"\n  | \"stepper\"\n  | \"switch\"\n  | \"tabs\"\n  | \"tag-input\"\n  | \"theme\"\n  | \"toast\"\n  | \"tooltip\"\n  | \"txt\"\n  | \"video-player\"\n  | \"video-trimmer\";\n\n/** Where a component exists: `@krizaka/ui/<name>` (web), `@krizaka/ui/native` (React Native), or both. */\nexport type Platform = \"web\" | \"native\" | \"both\";\n\n/** `stable`: its API only changes in a major. `beta`: it may still change in a minor. */\nexport type Status = \"stable\" | \"beta\";\n\n/** The group of the catalogue. `media`: video, sound, camera, files, cropping. */\nexport type Category = \"actions\" | \"forms\" | \"navigation\" | \"overlays\" | \"feedback\" | \"data-display\" | \"media\" | \"layout\" | \"foundations\";\n\n/**\n * A named example: the file `registry/examples/<component>/<name>.tsx` (web) or\n * `registry/examples/<component>/native/<name>.tsx` (React Native) — at most 40 lines, imported by the stories and\n * shown (live, with its code) by the documentation.\n */\nexport interface Example {\n  /** The file name, kebab-case (`primary`, `icon-button`). */\n  readonly name: string;\n  /** A short title (`Primary`, `Icon button`). */\n  readonly title: string;\n  /** One or two sentences: when this variant is the right one. */\n  readonly description: string;\n}\n\n/** One platform's side of a component. */\nexport interface PlatformDocs {\n  /** The names to import (`[\"Button\", \"IconButton\"]`): from `@krizaka/ui/<name>` on the web, `@krizaka/ui/native` in React Native. */\n  readonly imports: readonly string[];\n  /** The examples, in reading order; the first one is the component's preview. */\n  readonly examples: readonly Example[];\n}\n\n/** The React Native side: the same concept, and what differs from the web API. */\nexport interface NativeDocs extends PlatformDocs {\n  /**\n   * The entry to import from when it is not `@krizaka/ui/native`: a component that needs an Expo module (an optional\n   * peer) has its own, `@krizaka/ui/native/<name>`, so an app that does not use it never installs the module.\n   */\n  readonly entry?: string;\n  /** What differs from the web API (`label` instead of children…); empty for a native-only component. */\n  readonly differences: readonly string[];\n}\n\nexport interface KeyboardInteraction {\n  /** The keys, as written on a keyboard: `Space`, `Enter`, `Arrow keys`, `Esc`, `Tab`. */\n  readonly keys: string;\n  /** What they do. */\n  readonly action: string;\n}\n\nexport interface ComponentMeta {\n  /** The display name: `Button`, `Dropdown menu`. */\n  readonly title: string;\n  /** One sentence: what it is. */\n  readonly summary: string;\n  readonly status: Status;\n  readonly category: Category;\n  /** Must match the sides below: `both` ⇔ `web` and `native`. */\n  readonly platforms: Platform;\n  /** When to reach for it: concrete situations, one per item. */\n  readonly whenToUse: readonly string[];\n  /** When not to — and what to use instead (`use`), when another component is the answer. */\n  readonly whenNotToUse: readonly { readonly when: string; readonly use?: ComponentName }[];\n  /** How to use it well: wording, placement, composition. */\n  readonly bestPractices: readonly string[];\n  readonly accessibility: {\n    /** The keyboard, when it does more than Tab and Enter. */\n    readonly keyboard: readonly KeyboardInteraction[];\n    /** Roles, names and announcements: what the component does, what the app must provide. */\n    readonly notes: readonly string[];\n  };\n  /** The components a reader of this page should know about. */\n  readonly related: readonly ComponentName[];\n  readonly web?: PlatformDocs;\n  readonly native?: NativeDocs;\n}\n"
+      "content": "// The documentation of a component, carried by its code: each primitive has a `meta.ts` beside its source\n// (`src/<name>/meta.ts`; a component that exists only in React Native: `src/native/meta/<name>.ts`). Never built into\n// the package: `scripts/build-registry.mjs` reads them into `registry/<name>.json`, which krizaka.com renders as\n// /docs/ui/<name>, and `scripts/registry.test.mjs` fails when one is missing or incomplete.\n//\n// Why a typed module and not JSDoc tags: the fields are lists and links (`related`, `whenNotToUse[].use`, examples),\n// which a type checks and a comment does not; the file is plain data (erasable TypeScript), so Node reads it without a\n// compiler, and an editor completes it.\n\n/** Every documented component: the web primitives (one entry of the package each) and the native-only ones. */\nexport type ComponentName =\n  | \"action-bar\"\n  | \"alert\"\n  | \"argument-card\"\n  | \"audio-player\"\n  | \"avatar\"\n  | \"badge\"\n  | \"button\"\n  | \"card\"\n  | \"card-grid\"\n  | \"checkbox\"\n  | \"chip\"\n  | \"chip-link\"\n  | \"cn\"\n  | \"code-block\"\n  | \"combobox\"\n  | \"command\"\n  | \"confirm-button\"\n  | \"countdown\"\n  | \"cta-panel\"\n  | \"data-table\"\n  | \"date-picker\"\n  | \"decision-list\"\n  | \"dialog\"\n  | \"dropdown-menu\"\n  | \"empty-state\"\n  | \"field\"\n  | \"file-upload\"\n  | \"filter-bar\"\n  | \"glow-card\"\n  | \"image-cropper\"\n  | \"iso\"\n  | \"kbd\"\n  | \"link-card\"\n  | \"loader\"\n  | \"marquee\"\n  | \"mascot-quote\"\n  | \"mascots\"\n  | \"media-capture\"\n  | \"meter\"\n  | \"nav-bar\"\n  | \"number-ticker\"\n  | \"page\"\n  | \"page-header\"\n  | \"page-hero\"\n  | \"pagination\"\n  | \"pointer-light\"\n  | \"popover\"\n  | \"progress\"\n  | \"radio-group\"\n  | \"search-field\"\n  | \"section-backdrop\"\n  | \"segmented\"\n  | \"separator\"\n  | \"skeleton\"\n  | \"slider\"\n  | \"slot\"\n  | \"spinner\"\n  | \"stat\"\n  | \"stepper\"\n  | \"switch\"\n  | \"tabs\"\n  | \"tag-input\"\n  | \"terminal-replay\"\n  | \"theme\"\n  | \"toast\"\n  | \"toc\"\n  | \"tooltip\"\n  | \"txt\"\n  | \"video-player\"\n  | \"video-trimmer\";\n\n/** Where a component exists: `@krizaka/ui/<name>` (web), `@krizaka/ui/native` (React Native), or both. */\nexport type Platform = \"web\" | \"native\" | \"both\";\n\n/** `stable`: its API only changes in a major. `beta`: it may still change in a minor. */\nexport type Status = \"stable\" | \"beta\";\n\n/**\n * The group of the catalogue. `media`: video, sound, camera, files, cropping. `blocks`: the page blocks — the frame,\n * the hero, sections, cards that lead or argue, decisions, code, calls to act — that every page of a site is made of.\n */\nexport type Category = \"actions\" | \"forms\" | \"navigation\" | \"overlays\" | \"feedback\" | \"data-display\" | \"media\" | \"blocks\" | \"layout\" | \"foundations\";\n\n/**\n * A named example: the file `registry/examples/<component>/<name>.tsx` (web) or\n * `registry/examples/<component>/native/<name>.tsx` (React Native) — at most 40 lines, imported by the stories and\n * shown (live, with its code) by the documentation.\n */\nexport interface Example {\n  /** The file name, kebab-case (`primary`, `icon-button`). */\n  readonly name: string;\n  /** A short title (`Primary`, `Icon button`). */\n  readonly title: string;\n  /** One or two sentences: when this variant is the right one. */\n  readonly description: string;\n}\n\n/** One platform's side of a component. */\nexport interface PlatformDocs {\n  /** The names to import (`[\"Button\", \"IconButton\"]`): from `@krizaka/ui/<name>` on the web, `@krizaka/ui/native` in React Native. */\n  readonly imports: readonly string[];\n  /** The examples, in reading order; the first one is the component's preview. */\n  readonly examples: readonly Example[];\n}\n\n/** The React Native side: the same concept, and what differs from the web API. */\nexport interface NativeDocs extends PlatformDocs {\n  /**\n   * The entry to import from when it is not `@krizaka/ui/native`: a component that needs an Expo module (an optional\n   * peer) has its own, `@krizaka/ui/native/<name>`, so an app that does not use it never installs the module.\n   */\n  readonly entry?: string;\n  /** What differs from the web API (`label` instead of children…); empty for a native-only component. */\n  readonly differences: readonly string[];\n}\n\nexport interface KeyboardInteraction {\n  /** The keys, as written on a keyboard: `Space`, `Enter`, `Arrow keys`, `Esc`, `Tab`. */\n  readonly keys: string;\n  /** What they do. */\n  readonly action: string;\n}\n\nexport interface ComponentMeta {\n  /** The display name: `Button`, `Dropdown menu`. */\n  readonly title: string;\n  /** One sentence: what it is. */\n  readonly summary: string;\n  readonly status: Status;\n  readonly category: Category;\n  /** Must match the sides below: `both` ⇔ `web` and `native`. */\n  readonly platforms: Platform;\n  /** When to reach for it: concrete situations, one per item. */\n  readonly whenToUse: readonly string[];\n  /** When not to — and what to use instead (`use`), when another component is the answer. */\n  readonly whenNotToUse: readonly { readonly when: string; readonly use?: ComponentName }[];\n  /** How to use it well: wording, placement, composition. */\n  readonly bestPractices: readonly string[];\n  readonly accessibility: {\n    /** The keyboard, when it does more than Tab and Enter. */\n    readonly keyboard: readonly KeyboardInteraction[];\n    /** Roles, names and announcements: what the component does, what the app must provide. */\n    readonly notes: readonly string[];\n  };\n  /** The components a reader of this page should know about. */\n  readonly related: readonly ComponentName[];\n  readonly web?: PlatformDocs;\n  readonly native?: NativeDocs;\n}\n"
     },
     {
       "path": "theme/index.ts",

package/registry/toast.json

@@ -211,7 +211,7 @@
   "files": [
     {
       "path": "meta.ts",
-      "content": "// The documentation of a component, carried by its code: each primitive has a `meta.ts` beside its source\n// (`src/<name>/meta.ts`; a component that exists only in React Native: `src/native/meta/<name>.ts`). Never built into\n// the package: `scripts/build-registry.mjs` reads them into `registry/<name>.json`, which krizaka.com renders as\n// /docs/ui/<name>, and `scripts/registry.test.mjs` fails when one is missing or incomplete.\n//\n// Why a typed module and not JSDoc tags: the fields are lists and links (`related`, `whenNotToUse[].use`, examples),\n// which a type checks and a comment does not; the file is plain data (erasable TypeScript), so Node reads it without a\n// compiler, and an editor completes it.\n\n/** Every documented component: the web primitives (one entry of the package each) and the native-only ones. */\nexport type ComponentName =\n  | \"alert\"\n  | \"audio-player\"\n  | \"avatar\"\n  | \"badge\"\n  | \"button\"\n  | \"card\"\n  | \"checkbox\"\n  | \"chip\"\n  | \"chip-link\"\n  | \"cn\"\n  | \"combobox\"\n  | \"command\"\n  | \"confirm-button\"\n  | \"countdown\"\n  | \"data-table\"\n  | \"date-picker\"\n  | \"dialog\"\n  | \"dropdown-menu\"\n  | \"empty-state\"\n  | \"field\"\n  | \"file-upload\"\n  | \"filter-bar\"\n  | \"glow-card\"\n  | \"image-cropper\"\n  | \"iso\"\n  | \"kbd\"\n  | \"loader\"\n  | \"marquee\"\n  | \"mascots\"\n  | \"media-capture\"\n  | \"meter\"\n  | \"nav-bar\"\n  | \"number-ticker\"\n  | \"page-header\"\n  | \"pagination\"\n  | \"popover\"\n  | \"progress\"\n  | \"radio-group\"\n  | \"search-field\"\n  | \"section-backdrop\"\n  | \"segmented\"\n  | \"separator\"\n  | \"skeleton\"\n  | \"slider\"\n  | \"slot\"\n  | \"spinner\"\n  | \"stat\"\n  | \"stepper\"\n  | \"switch\"\n  | \"tabs\"\n  | \"tag-input\"\n  | \"theme\"\n  | \"toast\"\n  | \"tooltip\"\n  | \"txt\"\n  | \"video-player\"\n  | \"video-trimmer\";\n\n/** Where a component exists: `@krizaka/ui/<name>` (web), `@krizaka/ui/native` (React Native), or both. */\nexport type Platform = \"web\" | \"native\" | \"both\";\n\n/** `stable`: its API only changes in a major. `beta`: it may still change in a minor. */\nexport type Status = \"stable\" | \"beta\";\n\n/** The group of the catalogue. `media`: video, sound, camera, files, cropping. */\nexport type Category = \"actions\" | \"forms\" | \"navigation\" | \"overlays\" | \"feedback\" | \"data-display\" | \"media\" | \"layout\" | \"foundations\";\n\n/**\n * A named example: the file `registry/examples/<component>/<name>.tsx` (web) or\n * `registry/examples/<component>/native/<name>.tsx` (React Native) — at most 40 lines, imported by the stories and\n * shown (live, with its code) by the documentation.\n */\nexport interface Example {\n  /** The file name, kebab-case (`primary`, `icon-button`). */\n  readonly name: string;\n  /** A short title (`Primary`, `Icon button`). */\n  readonly title: string;\n  /** One or two sentences: when this variant is the right one. */\n  readonly description: string;\n}\n\n/** One platform's side of a component. */\nexport interface PlatformDocs {\n  /** The names to import (`[\"Button\", \"IconButton\"]`): from `@krizaka/ui/<name>` on the web, `@krizaka/ui/native` in React Native. */\n  readonly imports: readonly string[];\n  /** The examples, in reading order; the first one is the component's preview. */\n  readonly examples: readonly Example[];\n}\n\n/** The React Native side: the same concept, and what differs from the web API. */\nexport interface NativeDocs extends PlatformDocs {\n  /**\n   * The entry to import from when it is not `@krizaka/ui/native`: a component that needs an Expo module (an optional\n   * peer) has its own, `@krizaka/ui/native/<name>`, so an app that does not use it never installs the module.\n   */\n  readonly entry?: string;\n  /** What differs from the web API (`label` instead of children…); empty for a native-only component. */\n  readonly differences: readonly string[];\n}\n\nexport interface KeyboardInteraction {\n  /** The keys, as written on a keyboard: `Space`, `Enter`, `Arrow keys`, `Esc`, `Tab`. */\n  readonly keys: string;\n  /** What they do. */\n  readonly action: string;\n}\n\nexport interface ComponentMeta {\n  /** The display name: `Button`, `Dropdown menu`. */\n  readonly title: string;\n  /** One sentence: what it is. */\n  readonly summary: string;\n  readonly status: Status;\n  readonly category: Category;\n  /** Must match the sides below: `both` ⇔ `web` and `native`. */\n  readonly platforms: Platform;\n  /** When to reach for it: concrete situations, one per item. */\n  readonly whenToUse: readonly string[];\n  /** When not to — and what to use instead (`use`), when another component is the answer. */\n  readonly whenNotToUse: readonly { readonly when: string; readonly use?: ComponentName }[];\n  /** How to use it well: wording, placement, composition. */\n  readonly bestPractices: readonly string[];\n  readonly accessibility: {\n    /** The keyboard, when it does more than Tab and Enter. */\n    readonly keyboard: readonly KeyboardInteraction[];\n    /** Roles, names and announcements: what the component does, what the app must provide. */\n    readonly notes: readonly string[];\n  };\n  /** The components a reader of this page should know about. */\n  readonly related: readonly ComponentName[];\n  readonly web?: PlatformDocs;\n  readonly native?: NativeDocs;\n}\n"
+      "content": "// The documentation of a component, carried by its code: each primitive has a `meta.ts` beside its source\n// (`src/<name>/meta.ts`; a component that exists only in React Native: `src/native/meta/<name>.ts`). Never built into\n// the package: `scripts/build-registry.mjs` reads them into `registry/<name>.json`, which krizaka.com renders as\n// /docs/ui/<name>, and `scripts/registry.test.mjs` fails when one is missing or incomplete.\n//\n// Why a typed module and not JSDoc tags: the fields are lists and links (`related`, `whenNotToUse[].use`, examples),\n// which a type checks and a comment does not; the file is plain data (erasable TypeScript), so Node reads it without a\n// compiler, and an editor completes it.\n\n/** Every documented component: the web primitives (one entry of the package each) and the native-only ones. */\nexport type ComponentName =\n  | \"action-bar\"\n  | \"alert\"\n  | \"argument-card\"\n  | \"audio-player\"\n  | \"avatar\"\n  | \"badge\"\n  | \"button\"\n  | \"card\"\n  | \"card-grid\"\n  | \"checkbox\"\n  | \"chip\"\n  | \"chip-link\"\n  | \"cn\"\n  | \"code-block\"\n  | \"combobox\"\n  | \"command\"\n  | \"confirm-button\"\n  | \"countdown\"\n  | \"cta-panel\"\n  | \"data-table\"\n  | \"date-picker\"\n  | \"decision-list\"\n  | \"dialog\"\n  | \"dropdown-menu\"\n  | \"empty-state\"\n  | \"field\"\n  | \"file-upload\"\n  | \"filter-bar\"\n  | \"glow-card\"\n  | \"image-cropper\"\n  | \"iso\"\n  | \"kbd\"\n  | \"link-card\"\n  | \"loader\"\n  | \"marquee\"\n  | \"mascot-quote\"\n  | \"mascots\"\n  | \"media-capture\"\n  | \"meter\"\n  | \"nav-bar\"\n  | \"number-ticker\"\n  | \"page\"\n  | \"page-header\"\n  | \"page-hero\"\n  | \"pagination\"\n  | \"pointer-light\"\n  | \"popover\"\n  | \"progress\"\n  | \"radio-group\"\n  | \"search-field\"\n  | \"section-backdrop\"\n  | \"segmented\"\n  | \"separator\"\n  | \"skeleton\"\n  | \"slider\"\n  | \"slot\"\n  | \"spinner\"\n  | \"stat\"\n  | \"stepper\"\n  | \"switch\"\n  | \"tabs\"\n  | \"tag-input\"\n  | \"terminal-replay\"\n  | \"theme\"\n  | \"toast\"\n  | \"toc\"\n  | \"tooltip\"\n  | \"txt\"\n  | \"video-player\"\n  | \"video-trimmer\";\n\n/** Where a component exists: `@krizaka/ui/<name>` (web), `@krizaka/ui/native` (React Native), or both. */\nexport type Platform = \"web\" | \"native\" | \"both\";\n\n/** `stable`: its API only changes in a major. `beta`: it may still change in a minor. */\nexport type Status = \"stable\" | \"beta\";\n\n/**\n * The group of the catalogue. `media`: video, sound, camera, files, cropping. `blocks`: the page blocks — the frame,\n * the hero, sections, cards that lead or argue, decisions, code, calls to act — that every page of a site is made of.\n */\nexport type Category = \"actions\" | \"forms\" | \"navigation\" | \"overlays\" | \"feedback\" | \"data-display\" | \"media\" | \"blocks\" | \"layout\" | \"foundations\";\n\n/**\n * A named example: the file `registry/examples/<component>/<name>.tsx` (web) or\n * `registry/examples/<component>/native/<name>.tsx` (React Native) — at most 40 lines, imported by the stories and\n * shown (live, with its code) by the documentation.\n */\nexport interface Example {\n  /** The file name, kebab-case (`primary`, `icon-button`). */\n  readonly name: string;\n  /** A short title (`Primary`, `Icon button`). */\n  readonly title: string;\n  /** One or two sentences: when this variant is the right one. */\n  readonly description: string;\n}\n\n/** One platform's side of a component. */\nexport interface PlatformDocs {\n  /** The names to import (`[\"Button\", \"IconButton\"]`): from `@krizaka/ui/<name>` on the web, `@krizaka/ui/native` in React Native. */\n  readonly imports: readonly string[];\n  /** The examples, in reading order; the first one is the component's preview. */\n  readonly examples: readonly Example[];\n}\n\n/** The React Native side: the same concept, and what differs from the web API. */\nexport interface NativeDocs extends PlatformDocs {\n  /**\n   * The entry to import from when it is not `@krizaka/ui/native`: a component that needs an Expo module (an optional\n   * peer) has its own, `@krizaka/ui/native/<name>`, so an app that does not use it never installs the module.\n   */\n  readonly entry?: string;\n  /** What differs from the web API (`label` instead of children…); empty for a native-only component. */\n  readonly differences: readonly string[];\n}\n\nexport interface KeyboardInteraction {\n  /** The keys, as written on a keyboard: `Space`, `Enter`, `Arrow keys`, `Esc`, `Tab`. */\n  readonly keys: string;\n  /** What they do. */\n  readonly action: string;\n}\n\nexport interface ComponentMeta {\n  /** The display name: `Button`, `Dropdown menu`. */\n  readonly title: string;\n  /** One sentence: what it is. */\n  readonly summary: string;\n  readonly status: Status;\n  readonly category: Category;\n  /** Must match the sides below: `both` ⇔ `web` and `native`. */\n  readonly platforms: Platform;\n  /** When to reach for it: concrete situations, one per item. */\n  readonly whenToUse: readonly string[];\n  /** When not to — and what to use instead (`use`), when another component is the answer. */\n  readonly whenNotToUse: readonly { readonly when: string; readonly use?: ComponentName }[];\n  /** How to use it well: wording, placement, composition. */\n  readonly bestPractices: readonly string[];\n  readonly accessibility: {\n    /** The keyboard, when it does more than Tab and Enter. */\n    readonly keyboard: readonly KeyboardInteraction[];\n    /** Roles, names and announcements: what the component does, what the app must provide. */\n    readonly notes: readonly string[];\n  };\n  /** The components a reader of this page should know about. */\n  readonly related: readonly ComponentName[];\n  readonly web?: PlatformDocs;\n  readonly native?: NativeDocs;\n}\n"
     },
     {
       "path": "toast/index.ts",