@krizaka/ui 2.8.0 → 2.10.0

package/registry/split-view.json

@@ -0,0 +1,233 @@
+{
+  "name": "split-view",
+  "type": "primitive",
+  "title": "Split view",
+  "summary": "A list and its open item: two panes on a desktop; on a phone one at a time, the open item with the way back — chosen by showDetail, from the address.",
+  "description": "A list and its open item: two panes on a desktop; on a phone one at a time, the open item with the way back — chosen by showDetail, from the address.",
+  "status": "beta",
+  "category": "layouts",
+  "platforms": "web",
+  "whenToUse": [
+    "Messages, moderation queues, jobs, notifications.",
+    "Any list the user works through item by item."
+  ],
+  "whenNotToUse": [
+    {
+      "when": "For an object reached from elsewhere.",
+      "use": "detail-layout"
+    },
+    {
+      "when": "For rows to sort and select.",
+      "use": "data-table"
+    }
+  ],
+  "bestPractices": [
+    "Put the open item in the address (`?thread=lea`) and pass `showDetail` from it: back and forward work, a link can be shared.",
+    "Mark the open item in the list with `aria-current`.",
+    "Say what to do when nothing is open (`empty`)."
+  ],
+  "accessibility": {
+    "keyboard": [],
+    "notes": [
+      "Each pane is a `section`; the list's title is an `h2`.",
+      "On a phone the hidden pane is not rendered visibly (display none): it is not read either."
+    ]
+  },
+  "related": [
+    "detail-layout",
+    "data-table",
+    "app-shell"
+  ],
+  "web": {
+    "entry": "@krizaka/ui/split-view",
+    "import": "import { SplitView } from \"@krizaka/ui/split-view\";",
+    "props": [
+      {
+        "component": "SplitView",
+        "description": "A list and its open item: two panes on a desktop, one at a time on a phone.",
+        "props": [
+          {
+            "name": "list",
+            "type": "ReactNode",
+            "default": null,
+            "description": "The items (a list of links, a DataTable).",
+            "required": true
+          },
+          {
+            "name": "listTitle",
+            "type": "ReactNode",
+            "default": null,
+            "description": "The list pane's title (`Messages`): it names the region.",
+            "required": true
+          },
+          {
+            "name": "back",
+            "type": "ReactNode",
+            "default": null,
+            "description": "The way back to the list on a phone: your router's link (`<Link href=\"/inbox\">Messages</Link>`).",
+            "required": false
+          },
+          {
+            "name": "detail",
+            "type": "ReactNode",
+            "default": null,
+            "description": "The open item, or nothing.",
+            "required": false
+          },
+          {
+            "name": "detailHead",
+            "type": "ReactNode",
+            "default": null,
+            "description": "The open item's head: its name, its actions.",
+            "required": false
+          },
+          {
+            "name": "empty",
+            "type": "ReactNode",
+            "default": null,
+            "description": "What the detail pane says when nothing is open (desktop).",
+            "required": false
+          },
+          {
+            "name": "listActions",
+            "type": "ReactNode",
+            "default": null,
+            "description": "Actions in the list's head (a search, a filter, a new item).",
+            "required": false
+          },
+          {
+            "name": "listLabel",
+            "type": "string",
+            "default": null,
+            "description": "The list pane's accessible name when `listTitle` is not text.",
+            "required": false
+          },
+          {
+            "name": "showDetail",
+            "type": "boolean",
+            "default": "false",
+            "description": "On a phone, the open item replaces the list. Usually: an item is selected in the address.",
+            "required": false
+          }
+        ]
+      }
+    ],
+    "examples": [
+      {
+        "name": "messages",
+        "title": "Messages",
+        "description": "A creator's inbox: threads beside the open one, a reply box at its foot.",
+        "template": true,
+        "path": "examples/split-view/messages.tsx",
+        "module": "@krizaka/ui/registry/examples/split-view/messages",
+        "code": "import { Avatar } from \"@krizaka/ui/avatar\";\nimport { Button } from \"@krizaka/ui/button\";\nimport { Field, Textarea } from \"@krizaka/ui/field\";\nimport { SplitView } from \"@krizaka/ui/split-view\";\n\nconst THREADS = [\n  { id: \"lea\", name: \"Léa M.\", last: \"Will part 3 be out before Friday?\", time: \"09:12\", unread: true },\n  { id: \"samir\", name: \"Samir K.\", last: \"Thanks for the backstage cut!\", time: \"Yesterday\" },\n  { id: \"ines\", name: \"Inès B.\", last: \"I won the auction 🎉\", time: \"Mon\" },\n];\n\n// TEMPLATE — a creator's messages (Orochia): the threads beside the open one; on a phone the open thread replaces the\n// list (`showDetail`, from the address) with the way back above it. The reply box stays at the foot of the thread.\nexport default function SplitViewMessages() {\n  return (\n    <SplitView\n      className=\"w-full\"\n      listTitle=\"Messages\"\n      showDetail\n      back={<a href=\"#messages\" className=\"text-sm font-medium text-fg-secondary\">← Messages</a>}\n      list={\n        <ul>\n          {THREADS.map((t, i) => (\n            <li key={t.id}>\n              <a href={`#${t.id}`} aria-current={i === 0 ? \"page\" : undefined} className=\"flex items-center gap-3 border-b border-border-subtle px-4 py-3 text-sm no-underline hover:bg-surface-2 aria-[current=page]:bg-accent-soft\">\n                <Avatar fallback={t.name.slice(0, 2)} size=\"sm\" />\n                <span className=\"min-w-0 flex-1\">\n                  <span className=\"flex justify-between gap-2\"><span className=\"font-semibold text-fg\">{t.name}</span><span className=\"text-xs text-fg-secondary\">{t.time}</span></span>\n                  <span className={t.unread ? \"block truncate font-medium text-fg\" : \"block truncate text-fg-secondary\"}>{t.last}</span>\n                </span>\n              </a>\n            </li>\n          ))}\n        </ul>\n      }\n      detailHead={<span className=\"text-sm font-bold text-fg\">Léa M.</span>}\n      detail={\n        <div className=\"flex h-full flex-col gap-4\">\n          <p className=\"max-w-[80%] rounded-2xl rounded-bl-md bg-surface-2 px-3.5 py-2 text-sm text-fg\">Will part 3 be out before Friday?</p>\n          <p className=\"ml-auto max-w-[80%] rounded-2xl rounded-br-md bg-accent-soft px-3.5 py-2 text-sm text-fg\">Thursday evening — you'll be the first to know.</p>\n          <form className=\"mt-auto flex items-end gap-2\">\n            <Field.Root className=\"flex-1\">\n              <Field.Label htmlFor=\"reply\" className=\"sr-only\">Reply to Léa</Field.Label>\n              <Textarea id=\"reply\" rows={2} placeholder=\"Write a reply…\" />\n            </Field.Root>\n            <Button type=\"submit\" variant=\"primary\" shape=\"cut\">Send</Button>\n          </form>\n        </div>\n      }\n    />\n  );\n}\n"
+      },
+      {
+        "name": "empty",
+        "title": "Nothing open",
+        "description": "The list, and what to do while nothing is open.",
+        "path": "examples/split-view/empty.tsx",
+        "module": "@krizaka/ui/registry/examples/split-view/empty",
+        "code": "import { SplitView } from \"@krizaka/ui/split-view\";\n\n// Nothing open yet: the detail pane says what to do (desktop); on a phone only the list shows.\nexport default function SplitViewEmpty() {\n  return (\n    <SplitView\n      className=\"w-full\"\n      listTitle=\"Moderation\"\n      list={<p className=\"p-4 text-sm text-fg-secondary\">5 comments waiting.</p>}\n      empty=\"Choose a comment to review it.\"\n    />\n  );\n}\n"
+      }
+    ]
+  },
+  "native": null,
+  "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  | \"achievement\"\n  | \"action-bar\"\n  | \"alert\"\n  | \"app-shell\"\n  | \"argument-card\"\n  | \"audio-player\"\n  | \"auth-layout\"\n  | \"avatar\"\n  | \"badge\"\n  | \"button\"\n  | \"card\"\n  | \"card-grid\"\n  | \"catalogue-page\"\n  | \"changelog-page\"\n  | \"checkbox\"\n  | \"chip\"\n  | \"chip-link\"\n  | \"choice-grid\"\n  | \"cn\"\n  | \"code-block\"\n  | \"combobox\"\n  | \"command\"\n  | \"component-page\"\n  | \"confirm-button\"\n  | \"contact-page\"\n  | \"continue-prompt\"\n  | \"countdown\"\n  | \"cta-panel\"\n  | \"dashboard-layout\"\n  | \"data-table\"\n  | \"date-picker\"\n  | \"decision-list\"\n  | \"detail-layout\"\n  | \"dialog\"\n  | \"docs-article-page\"\n  | \"docs-hub-page\"\n  | \"docs-layout\"\n  | \"dropdown-menu\"\n  | \"empty-state\"\n  | \"error-page\"\n  | \"field\"\n  | \"file-upload\"\n  | \"filter-bar\"\n  | \"gallery-page\"\n  | \"glow-card\"\n  | \"goal-gauge\"\n  | \"how-it-works-page\"\n  | \"image-cropper\"\n  | \"iso\"\n  | \"kbd\"\n  | \"landing-page\"\n  | \"landscape\"\n  | \"legal-page\"\n  | \"link-card\"\n  | \"loader\"\n  | \"longform-page\"\n  | \"marketing-layout\"\n  | \"marquee\"\n  | \"mascot-quote\"\n  | \"mascot-state\"\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  | \"pricing-page\"\n  | \"product-page\"\n  | \"profile-card\"\n  | \"progress\"\n  | \"promise-card\"\n  | \"radio-group\"\n  | \"scroll-stage\"\n  | \"search-field\"\n  | \"section-backdrop\"\n  | \"segmented\"\n  | \"separator\"\n  | \"settings-layout\"\n  | \"skeleton\"\n  | \"slider\"\n  | \"slot\"\n  | \"spinner\"\n  | \"split-view\"\n  | \"stage-banner\"\n  | \"stat\"\n  | \"status-page\"\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 * `layouts`: the shells of whole screens — an application, a dashboard, settings, sign-in, an object, a list and its\n * item, a site's page, a documentation page — each with its screens. `templates`: the page templates — whole pages of a\n * site (a landing, a product, a docs hub, a long read, a changelog, pricing, status, an error…), each a distinct\n * composition of the blocks, words and content as props.\n */\nexport type Category = \"actions\" | \"forms\" | \"navigation\" | \"overlays\" | \"feedback\" | \"data-display\" | \"media\" | \"blocks\" | \"layouts\" | \"templates\" | \"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   * A template: a whole screen of a product composed from the platform (a layout and its blocks, real words, its phone\n   * version thought out), copied as a starting point — at most 160 lines, listed on krizaka.com/docs/ui/templates.\n   */\n  readonly template?: boolean;\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": "split-view/index.ts",
+      "content": "/** @krizaka/ui/split-view — `SplitView`: a list and its open item (one at a time on a phone). Server-safe. */\nexport { SplitView, splitView, type SplitViewProps } from \"./split-view\";\n"
+    },
+    {
+      "path": "split-view/meta.ts",
+      "content": "import type { ComponentMeta } from \"../meta\";\n\nexport const meta = {\n  title: \"Split view\",\n  summary: \"A list and its open item: two panes on a desktop; on a phone one at a time, the open item with the way back — chosen by showDetail, from the address.\",\n  status: \"beta\",\n  category: \"layouts\",\n  platforms: \"web\",\n  whenToUse: [\"Messages, moderation queues, jobs, notifications.\", \"Any list the user works through item by item.\"],\n  whenNotToUse: [\n    { when: \"For an object reached from elsewhere.\", use: \"detail-layout\" },\n    { when: \"For rows to sort and select.\", use: \"data-table\" },\n  ],\n  bestPractices: [\"Put the open item in the address (`?thread=lea`) and pass `showDetail` from it: back and forward work, a link can be shared.\", \"Mark the open item in the list with `aria-current`.\", \"Say what to do when nothing is open (`empty`).\"],\n  accessibility: {\n    keyboard: [],\n    notes: [\"Each pane is a `section`; the list's title is an `h2`.\", \"On a phone the hidden pane is not rendered visibly (display none): it is not read either.\"],\n  },\n  related: [\"detail-layout\", \"data-table\", \"app-shell\"],\n  web: {\n    imports: [\"SplitView\"],\n    examples: [\n      { name: \"messages\", title: \"Messages\", description: \"A creator's inbox: threads beside the open one, a reply box at its foot.\", template: true },\n      { name: \"empty\", title: \"Nothing open\", description: \"The list, and what to do while nothing is open.\" },\n    ],\n  },\n} satisfies ComponentMeta;\n"
+    },
+    {
+      "path": "split-view/split-view.tsx",
+      "content": "// Server-safe. A list and the item open beside it, read from the products' inboxes and queues (messages, moderation,\n// jobs): two panes on a desktop; on a phone one at a time — the list, or the open item with the way back — chosen by\n// `showDetail` (the address says which item is open: URL = state).\nimport type * as React from \"react\";\nimport { tv } from \"tailwind-variants\";\n\nexport const splitView = tv({\n  slots: {\n    root:\n      \"grid w-full min-h-[min(40rem,calc(100dvh-8rem))] overflow-hidden rounded-xl border border-border-default bg-surface-1 \" +\n      \"md:grid-cols-[minmax(16rem,22rem)_minmax(0,1fr)]\",\n    list: \"flex min-h-0 min-w-0 flex-col border-border-subtle md:border-r data-[hidden-on-phone]:hidden md:data-[hidden-on-phone]:flex\",\n    listHead: \"flex h-14 shrink-0 items-center gap-2 border-b border-border-subtle px-4\",\n    listTitle: \"text-sm font-bold text-fg\",\n    listBody: \"min-h-0 flex-1 overflow-y-auto\",\n    detail: \"flex min-h-0 min-w-0 flex-col bg-surface-0 data-[hidden-on-phone]:hidden md:data-[hidden-on-phone]:flex\",\n    detailHead: \"flex h-14 shrink-0 items-center gap-2 border-b border-border-subtle px-4\",\n    back: \"md:hidden\",\n    detailBody: \"min-h-0 flex-1 overflow-y-auto p-4 md:p-6\",\n    empty: \"flex flex-1 items-center justify-center p-8 text-center text-sm text-fg-secondary\",\n  },\n});\nconst s = splitView();\n\nexport type SplitViewProps = React.ComponentProps<\"div\"> & {\n  /** The list pane's title (`Messages`): it names the region. */\n  listTitle: React.ReactNode;\n  /** Actions in the list's head (a search, a filter, a new item). */\n  listActions?: React.ReactNode;\n  /** The items (a list of links, a DataTable). */\n  list: React.ReactNode;\n  /** The open item's head: its name, its actions. */\n  detailHead?: React.ReactNode;\n  /** The open item, or nothing. */\n  detail?: React.ReactNode;\n  /** What the detail pane says when nothing is open (desktop). */\n  empty?: React.ReactNode;\n  /** On a phone, the open item replaces the list. Usually: an item is selected in the address. */\n  showDetail?: boolean;\n  /** The way back to the list on a phone: your router's link (`<Link href=\"/inbox\">Messages</Link>`). */\n  back?: React.ReactNode;\n  /** The list pane's accessible name when `listTitle` is not text. */\n  listLabel?: string;\n};\n\n/** A list and its open item: two panes on a desktop, one at a time on a phone. */\nexport function SplitView({ listTitle, listActions, list, detailHead, detail, empty, showDetail = false, back, listLabel, className, ...props }: SplitViewProps) {\n  return (\n    <div className={s.root({ className })} {...props}>\n      <section className={s.list()} aria-label={listLabel} data-hidden-on-phone={showDetail ? \"\" : undefined}>\n        <div className={s.listHead()}>\n          <h2 className={s.listTitle()}>{listTitle}</h2>\n          <div className=\"ml-auto flex items-center gap-1.5\">{listActions}</div>\n        </div>\n        <div className={s.listBody()}>{list}</div>\n      </section>\n      <section className={s.detail()} data-hidden-on-phone={showDetail ? undefined : \"\"}>\n        {(back || detailHead) && (\n          <div className={s.detailHead()}>\n            {back && <div className={s.back()}>{back}</div>}\n            {detailHead}\n          </div>\n        )}\n        {detail ? <div className={s.detailBody()}>{detail}</div> : <div className={s.empty()}>{empty}</div>}\n      </section>\n    </div>\n  );\n}\n"
+    }
+  ],
+  "dependencies": [
+    "tailwind-variants@^3.3.1"
+  ],
+  "registryDependencies": [],
+  "demo": {
+    "path": "examples/split-view/messages.tsx",
+    "content": "import { Avatar } from \"@krizaka/ui/avatar\";\nimport { Button } from \"@krizaka/ui/button\";\nimport { Field, Textarea } from \"@krizaka/ui/field\";\nimport { SplitView } from \"@krizaka/ui/split-view\";\n\nconst THREADS = [\n  { id: \"lea\", name: \"Léa M.\", last: \"Will part 3 be out before Friday?\", time: \"09:12\", unread: true },\n  { id: \"samir\", name: \"Samir K.\", last: \"Thanks for the backstage cut!\", time: \"Yesterday\" },\n  { id: \"ines\", name: \"Inès B.\", last: \"I won the auction 🎉\", time: \"Mon\" },\n];\n\n// TEMPLATE — a creator's messages (Orochia): the threads beside the open one; on a phone the open thread replaces the\n// list (`showDetail`, from the address) with the way back above it. The reply box stays at the foot of the thread.\nexport default function SplitViewMessages() {\n  return (\n    <SplitView\n      className=\"w-full\"\n      listTitle=\"Messages\"\n      showDetail\n      back={<a href=\"#messages\" className=\"text-sm font-medium text-fg-secondary\">← Messages</a>}\n      list={\n        <ul>\n          {THREADS.map((t, i) => (\n            <li key={t.id}>\n              <a href={`#${t.id}`} aria-current={i === 0 ? \"page\" : undefined} className=\"flex items-center gap-3 border-b border-border-subtle px-4 py-3 text-sm no-underline hover:bg-surface-2 aria-[current=page]:bg-accent-soft\">\n                <Avatar fallback={t.name.slice(0, 2)} size=\"sm\" />\n                <span className=\"min-w-0 flex-1\">\n                  <span className=\"flex justify-between gap-2\"><span className=\"font-semibold text-fg\">{t.name}</span><span className=\"text-xs text-fg-secondary\">{t.time}</span></span>\n                  <span className={t.unread ? \"block truncate font-medium text-fg\" : \"block truncate text-fg-secondary\"}>{t.last}</span>\n                </span>\n              </a>\n            </li>\n          ))}\n        </ul>\n      }\n      detailHead={<span className=\"text-sm font-bold text-fg\">Léa M.</span>}\n      detail={\n        <div className=\"flex h-full flex-col gap-4\">\n          <p className=\"max-w-[80%] rounded-2xl rounded-bl-md bg-surface-2 px-3.5 py-2 text-sm text-fg\">Will part 3 be out before Friday?</p>\n          <p className=\"ml-auto max-w-[80%] rounded-2xl rounded-br-md bg-accent-soft px-3.5 py-2 text-sm text-fg\">Thursday evening — you'll be the first to know.</p>\n          <form className=\"mt-auto flex items-end gap-2\">\n            <Field.Root className=\"flex-1\">\n              <Field.Label htmlFor=\"reply\" className=\"sr-only\">Reply to Léa</Field.Label>\n              <Textarea id=\"reply\" rows={2} placeholder=\"Write a reply…\" />\n            </Field.Root>\n            <Button type=\"submit\" variant=\"primary\" shape=\"cut\">Send</Button>\n          </form>\n        </div>\n      }\n    />\n  );\n}\n"
+  },
+  "props": [
+    {
+      "component": "SplitView",
+      "description": "A list and its open item: two panes on a desktop, one at a time on a phone.",
+      "props": [
+        {
+          "name": "list",
+          "type": "ReactNode",
+          "default": null,
+          "description": "The items (a list of links, a DataTable).",
+          "required": true
+        },
+        {
+          "name": "listTitle",
+          "type": "ReactNode",
+          "default": null,
+          "description": "The list pane's title (`Messages`): it names the region.",
+          "required": true
+        },
+        {
+          "name": "back",
+          "type": "ReactNode",
+          "default": null,
+          "description": "The way back to the list on a phone: your router's link (`<Link href=\"/inbox\">Messages</Link>`).",
+          "required": false
+        },
+        {
+          "name": "detail",
+          "type": "ReactNode",
+          "default": null,
+          "description": "The open item, or nothing.",
+          "required": false
+        },
+        {
+          "name": "detailHead",
+          "type": "ReactNode",
+          "default": null,
+          "description": "The open item's head: its name, its actions.",
+          "required": false
+        },
+        {
+          "name": "empty",
+          "type": "ReactNode",
+          "default": null,
+          "description": "What the detail pane says when nothing is open (desktop).",
+          "required": false
+        },
+        {
+          "name": "listActions",
+          "type": "ReactNode",
+          "default": null,
+          "description": "Actions in the list's head (a search, a filter, a new item).",
+          "required": false
+        },
+        {
+          "name": "listLabel",
+          "type": "string",
+          "default": null,
+          "description": "The list pane's accessible name when `listTitle` is not text.",
+          "required": false
+        },
+        {
+          "name": "showDetail",
+          "type": "boolean",
+          "default": "false",
+          "description": "On a phone, the open item replaces the list. Usually: an item is selected in the address.",
+          "required": false
+        }
+      ]
+    }
+  ]
+}

package/registry/stage-banner.json

@@ -0,0 +1,221 @@
+{
+  "name": "stage-banner",
+  "type": "primitive",
+  "title": "Stage banner",
+  "summary": "The announcement of a chapter: a stage and its name on one line, or, large, a stage above a title and a line — a sober eyebrow by default, a stage call that slams in for the arcade flavour.",
+  "description": "The announcement of a chapter: a stage and its name on one line, or, large, a stage above a title and a line — a sober eyebrow by default, a stage call that slams in for the arcade flavour.",
+  "status": "beta",
+  "category": "blocks",
+  "platforms": "web",
+  "whenToUse": [
+    "Before a chapter's heading on a told page or a tour (“Step 02 · Payments”).",
+    "To open a section that turns the story (`size=\"lg\"`): a final chapter, a reveal."
+  ],
+  "whenNotToUse": [
+    {
+      "when": "Progress through a form or a checkout.",
+      "use": "stepper"
+    },
+    {
+      "when": "A plain eyebrow above a section's heading.",
+      "use": "page"
+    }
+  ],
+  "bestPractices": [
+    "Few words: the stage (“Step 02”) and a name of one or two words.",
+    "With `size=\"lg\"` and no heading after it, pass `titleAs=\"h2\"` so the section keeps its heading."
+  ],
+  "accessibility": {
+    "keyboard": [],
+    "notes": [
+      "A paragraph by default; the large title can be a heading (`titleAs`).",
+      "Its entrance plays once in a stage and never under `prefers-reduced-motion`."
+    ]
+  },
+  "related": [
+    "scroll-stage",
+    "stepper",
+    "page-hero"
+  ],
+  "web": {
+    "entry": "@krizaka/ui/stage-banner",
+    "import": "import { StageBanner } from \"@krizaka/ui/stage-banner\";",
+    "props": [
+      {
+        "component": "StageBanner",
+        "description": "Announces a chapter: a stage and its name on one line, or (`size=\"lg\"`) a stage, a title and a line, centred.",
+        "props": [
+          {
+            "name": "stage",
+            "type": "ReactNode",
+            "default": null,
+            "description": "Where the reader is: “Step 02”, “Chapter 3”, “Final round”.",
+            "required": true
+          },
+          {
+            "name": "brand",
+            "type": "string",
+            "default": null,
+            "description": "A brand scope (`orochia` → `.brand-orochia`).",
+            "required": false
+          },
+          {
+            "name": "name",
+            "type": "ReactNode",
+            "default": null,
+            "description": "`sm`: the name of the chapter, beside the stage.",
+            "required": false
+          },
+          {
+            "name": "size",
+            "type": "\"sm\" | \"lg\"",
+            "default": "sm",
+            "description": "`sm`: one line, before a chapter's heading. `lg`: centred, the stage above a title and a line — a section's opening.",
+            "required": false
+          },
+          {
+            "name": "subtitle",
+            "type": "ReactNode",
+            "default": null,
+            "description": "`lg`: one line under the title.",
+            "required": false
+          },
+          {
+            "name": "title",
+            "type": "ReactNode",
+            "default": null,
+            "description": "`lg`: the title under the stage.",
+            "required": false
+          },
+          {
+            "name": "titleAs",
+            "type": "\"h2\" | \"h3\" | \"p\"",
+            "default": "p",
+            "description": "The element of the `lg` title: a heading when the banner opens a section that has none.",
+            "required": false
+          },
+          {
+            "name": "variant",
+            "type": "StoryVariant",
+            "default": "default",
+            "description": "`default`: a sober eyebrow. `arcade`: the stage call — a skewed plate that slams in, a light that sweeps it.",
+            "required": false
+          }
+        ]
+      }
+    ],
+    "examples": [
+      {
+        "name": "steps",
+        "title": "Before a chapter",
+        "description": "A stage and its name, sober then in the arcade flavour.",
+        "path": "examples/stage-banner/steps.tsx",
+        "module": "@krizaka/ui/registry/examples/stage-banner/steps",
+        "code": "import { StageBanner } from \"@krizaka/ui/stage-banner\";\n\n// Before a chapter's heading: where the reader is. Sober by default; `variant=\"arcade\"` for a told page.\nexport default function StageBannerSteps() {\n  return (\n    <div className=\"grid justify-items-start gap-4\">\n      <StageBanner stage=\"Step 02\" name=\"Payments\" />\n      <StageBanner variant=\"arcade\" stage=\"Stage 02\" name=\"Orazaka\" />\n    </div>\n  );\n}\n"
+      },
+      {
+        "name": "round",
+        "title": "A section's opening",
+        "description": "`size=\"lg\"`: the stage, a title and a line — sober, then a final round.",
+        "path": "examples/stage-banner/round.tsx",
+        "module": "@krizaka/ui/registry/examples/stage-banner/round",
+        "code": "import { StageBanner } from \"@krizaka/ui/stage-banner\";\n\n// `size=\"lg\"`: a section's opening — the stage, a title (a heading here) and a line.\nexport default function StageBannerRound() {\n  return (\n    <div className=\"grid gap-10\">\n      <StageBanner size=\"lg\" titleAs=\"h3\" stage=\"Chapter 3\" title=\"Get paid on your terms\" subtitle=\"Tips, challenges and auctions — 90 % to you.\" />\n      <StageBanner size=\"lg\" variant=\"arcade\" stage=\"Final round\" title=\"The last boss\" subtitle=\"Eight heads, one by one.\" />\n    </div>\n  );\n}\n"
+      }
+    ]
+  },
+  "native": null,
+  "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  | \"achievement\"\n  | \"action-bar\"\n  | \"alert\"\n  | \"app-shell\"\n  | \"argument-card\"\n  | \"audio-player\"\n  | \"auth-layout\"\n  | \"avatar\"\n  | \"badge\"\n  | \"button\"\n  | \"card\"\n  | \"card-grid\"\n  | \"catalogue-page\"\n  | \"changelog-page\"\n  | \"checkbox\"\n  | \"chip\"\n  | \"chip-link\"\n  | \"choice-grid\"\n  | \"cn\"\n  | \"code-block\"\n  | \"combobox\"\n  | \"command\"\n  | \"component-page\"\n  | \"confirm-button\"\n  | \"contact-page\"\n  | \"continue-prompt\"\n  | \"countdown\"\n  | \"cta-panel\"\n  | \"dashboard-layout\"\n  | \"data-table\"\n  | \"date-picker\"\n  | \"decision-list\"\n  | \"detail-layout\"\n  | \"dialog\"\n  | \"docs-article-page\"\n  | \"docs-hub-page\"\n  | \"docs-layout\"\n  | \"dropdown-menu\"\n  | \"empty-state\"\n  | \"error-page\"\n  | \"field\"\n  | \"file-upload\"\n  | \"filter-bar\"\n  | \"gallery-page\"\n  | \"glow-card\"\n  | \"goal-gauge\"\n  | \"how-it-works-page\"\n  | \"image-cropper\"\n  | \"iso\"\n  | \"kbd\"\n  | \"landing-page\"\n  | \"landscape\"\n  | \"legal-page\"\n  | \"link-card\"\n  | \"loader\"\n  | \"longform-page\"\n  | \"marketing-layout\"\n  | \"marquee\"\n  | \"mascot-quote\"\n  | \"mascot-state\"\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  | \"pricing-page\"\n  | \"product-page\"\n  | \"profile-card\"\n  | \"progress\"\n  | \"promise-card\"\n  | \"radio-group\"\n  | \"scroll-stage\"\n  | \"search-field\"\n  | \"section-backdrop\"\n  | \"segmented\"\n  | \"separator\"\n  | \"settings-layout\"\n  | \"skeleton\"\n  | \"slider\"\n  | \"slot\"\n  | \"spinner\"\n  | \"split-view\"\n  | \"stage-banner\"\n  | \"stat\"\n  | \"status-page\"\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 * `layouts`: the shells of whole screens — an application, a dashboard, settings, sign-in, an object, a list and its\n * item, a site's page, a documentation page — each with its screens. `templates`: the page templates — whole pages of a\n * site (a landing, a product, a docs hub, a long read, a changelog, pricing, status, an error…), each a distinct\n * composition of the blocks, words and content as props.\n */\nexport type Category = \"actions\" | \"forms\" | \"navigation\" | \"overlays\" | \"feedback\" | \"data-display\" | \"media\" | \"blocks\" | \"layouts\" | \"templates\" | \"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   * A template: a whole screen of a product composed from the platform (a layout and its blocks, real words, its phone\n   * version thought out), copied as a starting point — at most 160 lines, listed on krizaka.com/docs/ui/templates.\n   */\n  readonly template?: boolean;\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": "stage-banner/index.ts",
+      "content": "/** @krizaka/ui/stage-banner — `StageBanner`, the announcement of a chapter. Server-safe. Styles: story.css. */\nexport { StageBanner, type StageBannerProps } from \"./stage-banner\";\n"
+    },
+    {
+      "path": "stage-banner/meta.ts",
+      "content": "import type { ComponentMeta } from \"../meta\";\n\nexport const meta = {\n  title: \"Stage banner\",\n  summary: \"The announcement of a chapter: a stage and its name on one line, or, large, a stage above a title and a line — a sober eyebrow by default, a stage call that slams in for the arcade flavour.\",\n  status: \"beta\",\n  category: \"blocks\",\n  platforms: \"web\",\n  whenToUse: [\n    \"Before a chapter's heading on a told page or a tour (“Step 02 · Payments”).\",\n    \"To open a section that turns the story (`size=\\\"lg\\\"`): a final chapter, a reveal.\",\n  ],\n  whenNotToUse: [\n    { when: \"Progress through a form or a checkout.\", use: \"stepper\" },\n    { when: \"A plain eyebrow above a section's heading.\", use: \"page\" },\n  ],\n  bestPractices: [\n    \"Few words: the stage (“Step 02”) and a name of one or two words.\",\n    \"With `size=\\\"lg\\\"` and no heading after it, pass `titleAs=\\\"h2\\\"` so the section keeps its heading.\",\n  ],\n  accessibility: {\n    keyboard: [],\n    notes: [\n      \"A paragraph by default; the large title can be a heading (`titleAs`).\",\n      \"Its entrance plays once in a stage and never under `prefers-reduced-motion`.\",\n    ],\n  },\n  related: [\"scroll-stage\", \"stepper\", \"page-hero\"],\n  web: {\n    imports: [\"StageBanner\"],\n    examples: [\n      { name: \"steps\", title: \"Before a chapter\", description: \"A stage and its name, sober then in the arcade flavour.\" },\n      { name: \"round\", title: \"A section's opening\", description: \"`size=\\\"lg\\\"`: the stage, a title and a line — sober, then a final round.\" },\n    ],\n  },\n} satisfies ComponentMeta;\n"
+    },
+    {
+      "path": "stage-banner/stage-banner.tsx",
+      "content": "// Server-safe. The announcement of a chapter (story.css): “Step 02 · Payments”, or, large, a round with its title and a\n// line under it. In a `Scene` of a `ScrollStage` it arrives once, after the scene's visual.\nimport type * as React from \"react\";\n\nimport { cn } from \"../cn\";\nimport { brandClass, type StoryVariant, storyVariantClass } from \"../story-variant\";\n\nexport type StageBannerProps = Omit<React.HTMLAttributes<HTMLElement>, \"title\"> & {\n  /** Where the reader is: “Step 02”, “Chapter 3”, “Final round”. */\n  stage: React.ReactNode;\n  /** `sm`: the name of the chapter, beside the stage. */\n  name?: React.ReactNode;\n  /** `lg`: the title under the stage. */\n  title?: React.ReactNode;\n  /** `lg`: one line under the title. */\n  subtitle?: React.ReactNode;\n  /**\n   * `sm`: one line, before a chapter's heading. `lg`: centred, the stage above a title and a line — a section's opening.\n   * @default \"sm\"\n   */\n  size?: \"sm\" | \"lg\";\n  /**\n   * The element of the `lg` title: a heading when the banner opens a section that has none.\n   * @default \"p\"\n   */\n  titleAs?: \"p\" | \"h2\" | \"h3\";\n  /**\n   * `default`: a sober eyebrow. `arcade`: the stage call — a skewed plate that slams in, a light that sweeps it.\n   * @default \"default\"\n   */\n  variant?: StoryVariant;\n  /** A brand scope (`orochia` → `.brand-orochia`). */\n  brand?: string;\n};\n\n/** Announces a chapter: a stage and its name on one line, or (`size=\"lg\"`) a stage, a title and a line, centred. */\nexport function StageBanner({ stage, name, title, subtitle, size = \"sm\", titleAs: Title = \"p\", variant, brand, className, ...props }: StageBannerProps) {\n  const cls = cn(\"kzs-banner\", storyVariantClass(variant), brandClass(brand), className);\n  if (size === \"lg\")\n    return (\n      <div data-size=\"lg\" className={cls} {...props}>\n        <span className=\"kzs-banner-stage\">{stage}</span>\n        {title && <Title className=\"kzs-banner-title\">{title}</Title>}\n        {subtitle && <p className=\"kzs-banner-sub\">{subtitle}</p>}\n      </div>\n    );\n  return (\n    <p className={cls} {...props}>\n      <span className=\"kzs-banner-stage\">{stage}</span>\n      {name && <span className=\"kzs-banner-name\">{name}</span>}\n      <span className=\"kzs-banner-sweep\" aria-hidden />\n    </p>\n  );\n}\n"
+    },
+    {
+      "path": "story-variant.ts",
+      "content": "// The two looks of the storytelling kit (story.css), shared by its entries. Server-safe.\n\n/** The look of the storytelling kit: `default` (sober, for any app) or `arcade` (the opt-in cabinet flavour). */\nexport type StoryVariant = \"default\" | \"arcade\";\n\n/** The class a storytelling component adds for its look (`kzs-arcade` for the arcade flavour). */\nexport const storyVariantClass = (variant: StoryVariant | undefined) => (variant === \"arcade\" ? \"kzs-arcade\" : undefined);\n\n/** The class of a brand scope (`brand-orochia`): the accent and the gradient become that brand's. */\nexport const brandClass = (brand: string | undefined) => (brand ? `brand-${brand}` : undefined);\n"
+    }
+  ],
+  "dependencies": [],
+  "registryDependencies": [
+    "cn"
+  ],
+  "demo": {
+    "path": "examples/stage-banner/steps.tsx",
+    "content": "import { StageBanner } from \"@krizaka/ui/stage-banner\";\n\n// Before a chapter's heading: where the reader is. Sober by default; `variant=\"arcade\"` for a told page.\nexport default function StageBannerSteps() {\n  return (\n    <div className=\"grid justify-items-start gap-4\">\n      <StageBanner stage=\"Step 02\" name=\"Payments\" />\n      <StageBanner variant=\"arcade\" stage=\"Stage 02\" name=\"Orazaka\" />\n    </div>\n  );\n}\n"
+  },
+  "props": [
+    {
+      "component": "StageBanner",
+      "description": "Announces a chapter: a stage and its name on one line, or (`size=\"lg\"`) a stage, a title and a line, centred.",
+      "props": [
+        {
+          "name": "stage",
+          "type": "ReactNode",
+          "default": null,
+          "description": "Where the reader is: “Step 02”, “Chapter 3”, “Final round”.",
+          "required": true
+        },
+        {
+          "name": "brand",
+          "type": "string",
+          "default": null,
+          "description": "A brand scope (`orochia` → `.brand-orochia`).",
+          "required": false
+        },
+        {
+          "name": "name",
+          "type": "ReactNode",
+          "default": null,
+          "description": "`sm`: the name of the chapter, beside the stage.",
+          "required": false
+        },
+        {
+          "name": "size",
+          "type": "\"sm\" | \"lg\"",
+          "default": "sm",
+          "description": "`sm`: one line, before a chapter's heading. `lg`: centred, the stage above a title and a line — a section's opening.",
+          "required": false
+        },
+        {
+          "name": "subtitle",
+          "type": "ReactNode",
+          "default": null,
+          "description": "`lg`: one line under the title.",
+          "required": false
+        },
+        {
+          "name": "title",
+          "type": "ReactNode",
+          "default": null,
+          "description": "`lg`: the title under the stage.",
+          "required": false
+        },
+        {
+          "name": "titleAs",
+          "type": "\"h2\" | \"h3\" | \"p\"",
+          "default": "p",
+          "description": "The element of the `lg` title: a heading when the banner opens a section that has none.",
+          "required": false
+        },
+        {
+          "name": "variant",
+          "type": "StoryVariant",
+          "default": "default",
+          "description": "`default`: a sober eyebrow. `arcade`: the stage call — a skewed plate that slams in, a light that sweeps it.",
+          "required": false
+        }
+      ]
+    }
+  ]
+}

package/registry/stat.json

@@ -134,7 +134,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  | \"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  | \"mascot-state\"\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"
+      "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  | \"achievement\"\n  | \"action-bar\"\n  | \"alert\"\n  | \"app-shell\"\n  | \"argument-card\"\n  | \"audio-player\"\n  | \"auth-layout\"\n  | \"avatar\"\n  | \"badge\"\n  | \"button\"\n  | \"card\"\n  | \"card-grid\"\n  | \"catalogue-page\"\n  | \"changelog-page\"\n  | \"checkbox\"\n  | \"chip\"\n  | \"chip-link\"\n  | \"choice-grid\"\n  | \"cn\"\n  | \"code-block\"\n  | \"combobox\"\n  | \"command\"\n  | \"component-page\"\n  | \"confirm-button\"\n  | \"contact-page\"\n  | \"continue-prompt\"\n  | \"countdown\"\n  | \"cta-panel\"\n  | \"dashboard-layout\"\n  | \"data-table\"\n  | \"date-picker\"\n  | \"decision-list\"\n  | \"detail-layout\"\n  | \"dialog\"\n  | \"docs-article-page\"\n  | \"docs-hub-page\"\n  | \"docs-layout\"\n  | \"dropdown-menu\"\n  | \"empty-state\"\n  | \"error-page\"\n  | \"field\"\n  | \"file-upload\"\n  | \"filter-bar\"\n  | \"gallery-page\"\n  | \"glow-card\"\n  | \"goal-gauge\"\n  | \"how-it-works-page\"\n  | \"image-cropper\"\n  | \"iso\"\n  | \"kbd\"\n  | \"landing-page\"\n  | \"landscape\"\n  | \"legal-page\"\n  | \"link-card\"\n  | \"loader\"\n  | \"longform-page\"\n  | \"marketing-layout\"\n  | \"marquee\"\n  | \"mascot-quote\"\n  | \"mascot-state\"\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  | \"pricing-page\"\n  | \"product-page\"\n  | \"profile-card\"\n  | \"progress\"\n  | \"promise-card\"\n  | \"radio-group\"\n  | \"scroll-stage\"\n  | \"search-field\"\n  | \"section-backdrop\"\n  | \"segmented\"\n  | \"separator\"\n  | \"settings-layout\"\n  | \"skeleton\"\n  | \"slider\"\n  | \"slot\"\n  | \"spinner\"\n  | \"split-view\"\n  | \"stage-banner\"\n  | \"stat\"\n  | \"status-page\"\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 * `layouts`: the shells of whole screens — an application, a dashboard, settings, sign-in, an object, a list and its\n * item, a site's page, a documentation page — each with its screens. `templates`: the page templates — whole pages of a\n * site (a landing, a product, a docs hub, a long read, a changelog, pricing, status, an error…), each a distinct\n * composition of the blocks, words and content as props.\n */\nexport type Category = \"actions\" | \"forms\" | \"navigation\" | \"overlays\" | \"feedback\" | \"data-display\" | \"media\" | \"blocks\" | \"layouts\" | \"templates\" | \"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   * A template: a whole screen of a product composed from the platform (a layout and its blocks, real words, its phone\n   * version thought out), copied as a starting point — at most 160 lines, listed on krizaka.com/docs/ui/templates.\n   */\n  readonly template?: boolean;\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": "stat/index.ts",