@krizaka/ui 2.8.0 → 2.10.0

package/registry/docs-hub-page.json

@@ -0,0 +1,270 @@
+{
+  "name": "docs-hub-page",
+  "type": "primitive",
+  "title": "Docs hub page",
+  "summary": "The entry of a documentation: the search in the middle of the hero, the collections each in its product's brand with their quick links, quick starts beside the most read pages, what is new, the owl's promise.",
+  "description": "The entry of a documentation: the search in the middle of the hero, the collections each in its product's brand with their quick links, quick starts beside the most read pages, what is new, the owl's promise.",
+  "status": "beta",
+  "category": "templates",
+  "platforms": "web",
+  "whenToUse": [
+    "The home of a documentation with several collections.",
+    "A help centre's entry."
+  ],
+  "whenNotToUse": [
+    {
+      "when": "For one article of the documentation.",
+      "use": "docs-article-page"
+    },
+    {
+      "when": "For a plain list of entry points.",
+      "use": "link-card"
+    }
+  ],
+  "bestPractices": [
+    "The search first: most readers come to find one page.",
+    "Each collection in its product's brand, with three or four quick links.",
+    "What is new comes from the registries, never typed by hand.",
+    "Words and content arrive as props; the motion is the platform's (`[data-reveal]`, still under reduced motion)."
+  ],
+  "accessibility": {
+    "keyboard": [],
+    "notes": [
+      "One `h1`; each collection a list item with its main link and a named list of quick links.",
+      "The lists of pages are lists of links with their meta in words."
+    ]
+  },
+  "related": [
+    "docs-article-page",
+    "link-card",
+    "search-field"
+  ],
+  "web": {
+    "entry": "@krizaka/ui/docs-hub-page",
+    "import": "import { DocsHubPage } from \"@krizaka/ui/docs-hub-page\";",
+    "props": [
+      {
+        "component": "DocsHubPage",
+        "description": "A documentation hub: search first, the collections in their brand, quick starts, popular and new pages.",
+        "props": [
+          {
+            "name": "collections",
+            "type": "readonly DocsCollection[]",
+            "default": null,
+            "description": "The collections, each in its brand.",
+            "required": true
+          },
+          {
+            "name": "collectionsTitle",
+            "type": "ReactNode",
+            "default": null,
+            "description": "The collections' heading.",
+            "required": true
+          },
+          {
+            "name": "title",
+            "type": "ReactNode",
+            "default": null,
+            "description": "The page's `h1`.",
+            "required": true
+          },
+          {
+            "name": "eyebrow",
+            "type": "ReactNode",
+            "default": null,
+            "description": "A mono line above the title.",
+            "required": false
+          },
+          {
+            "name": "lead",
+            "type": "ReactNode",
+            "default": null,
+            "description": "One sentence under it.",
+            "required": false
+          },
+          {
+            "name": "linkAs",
+            "type": "LinkComponent",
+            "default": null,
+            "description": "The app's link component (Next's `Link`) for internal addresses.",
+            "required": false
+          },
+          {
+            "name": "popular",
+            "type": "{ title: ReactNode; items: readonly DocsHubLink[]; }",
+            "default": null,
+            "description": "The most read pages.",
+            "required": false
+          },
+          {
+            "name": "promise",
+            "type": "{ label: ReactNode; text: ReactNode; }",
+            "default": null,
+            "description": "The owl's promise at the foot: what this documentation guarantees.",
+            "required": false
+          },
+          {
+            "name": "quickstarts",
+            "type": "{ title: ReactNode; children: ReactNode; }",
+            "default": null,
+            "description": "The quick starts: a title and their samples (CodeBlocks, CodeTabs).",
+            "required": false
+          },
+          {
+            "name": "search",
+            "type": "ReactNode",
+            "default": null,
+            "description": "The search, front and centre (a SearchField, a button that opens the command palette).",
+            "required": false
+          },
+          {
+            "name": "searchHints",
+            "type": "ReactNode",
+            "default": null,
+            "description": "Under the search: what people look for (a few links or keys).",
+            "required": false
+          },
+          {
+            "name": "whatsNew",
+            "type": "{ title: ReactNode; items: readonly DocsHubLink[]; }",
+            "default": null,
+            "description": "What is new (releases from the registries, published pages).",
+            "required": false
+          }
+        ]
+      }
+    ],
+    "examples": [
+      {
+        "name": "krizaka",
+        "title": "krizaka.com/docs",
+        "description": "The five collections, a quick start, the most read pages, what is new.",
+        "template": true,
+        "path": "examples/docs-hub-page/krizaka.tsx",
+        "module": "@krizaka/ui/registry/examples/docs-hub-page/krizaka",
+        "code": "import { ProductLogo } from \"@krizaka/ui\";\nimport { Button } from \"@krizaka/ui/button\";\nimport { CodeBlock } from \"@krizaka/ui/code-block\";\nimport { DocsHubPage } from \"@krizaka/ui/docs-hub-page\";\nimport { Kbd } from \"@krizaka/ui/kbd\";\n\nconst COLLECTIONS = [\n  { id: \"ui\", title: \"Krizaka UI\", href: \"#ui\", mark: <ProductLogo id=\"krizaka\" size={26} animated={false} />, description: \"Tokens, a Tailwind preset, the components — live, generated from their code.\", links: [{ href: \"#blocks\", label: \"Blocks\" }, { href: \"#layouts\", label: \"Layouts\" }, { href: \"#templates\", label: \"Templates\" }] },\n  { id: \"java\", title: \"Krizaka Java\", href: \"#java\", mark: <ProductLogo id=\"krizaka\" size={26} animated={false} />, description: \"Parent, BOM, starters, messaging, Problem Details.\", links: [{ href: \"#bom\", label: \"BOM\" }, { href: \"#messaging\", label: \"Messaging\" }] },\n  { id: \"orazaka\", brand: \"orazaka\", title: \"Orazaka\", href: \"#orazaka\", mark: <ProductLogo id=\"orazaka\" size={26} animated={false} />, description: \"The sovereign AI engine: install, packs, administration.\", links: [{ href: \"#cli\", label: \"CLI\" }, { href: \"#packs\", label: \"Packs\" }, { href: \"#admin\", label: \"Admin\" }] },\n  { id: \"orochia\", brand: \"orochia\", title: \"Orochia\", href: \"#orochia\", mark: <ProductLogo id=\"orochia\" size={26} animated={false} />, description: \"The creator platform: payments, auctions, the admin console.\", links: [{ href: \"#payouts\", label: \"Payouts\" }, { href: \"#console\", label: \"Console\" }] },\n];\n\n// TEMPLATE — krizaka.com/docs: the search in the middle of the hero (⌘K), the collections each in its product's brand\n// with their quick links, a quick start beside the most read pages, what is new, the owl's promise. On a phone: search,\n// then one collection per row.\nexport default function DocsHubPageKrizaka() {\n  return (\n    <DocsHubPage\n      eyebrow=\"Documentation\"\n      title=\"Build with Krizaka\"\n      lead=\"Every building block the products are made of, documented from its source.\"\n      search={\n        <Button variant=\"secondary\" size=\"lg\" shape=\"cut\" className=\"w-full justify-between text-fg-secondary\">\n          Search the documentation <Kbd>⌘K</Kbd>\n        </Button>\n      }\n      searchHints={<>Try: <a href=\"#cli\">orazaka install</a> · <a href=\"#button\">Button</a> · <a href=\"#bom\">BOM</a></>}\n      collectionsTitle=\"Collections\"\n      collections={COLLECTIONS}\n      quickstarts={{ title: \"Start in one line\", children: <CodeBlock code=\"npx orazaka install\" language=\"bash\" file=\"Terminal\" copyLabel=\"Copy\" copiedLabel=\"Copied\" /> }}\n      popular={{ title: \"Most read\", items: [{ href: \"#cli\", title: \"The CLI\", meta: \"Orazaka\" }, { href: \"#button\", title: \"Button\", meta: \"Krizaka UI\" }, { href: \"#bom\", title: \"The BOM\", meta: \"Java\" }] }}\n      whatsNew={{ title: \"What's new\", items: [{ href: \"#ui-260\", title: \"Page blocks: frame, hero, cards, decisions\", meta: \"@krizaka/ui 2.6.0\" }, { href: \"#java-010\", title: \"The platform kit on Maven Central\", meta: \"0.1.0\" }] }}\n      promise={{ label: \"The owl's promise\", text: \"Every page here is generated from the code it documents — when the code changes, the page does.\" }}\n    />\n  );\n}\n"
+      }
+    ]
+  },
+  "native": null,
+  "files": [
+    {
+      "path": "docs-hub-page/docs-hub-page.tsx",
+      "content": "// Server-safe. The entry of a documentation (blocks.css `.kz-tpl-hub-*`, `.kz-tpl-collections`): the search in the\n// middle of the hero, the collections each in its product's brand with its quick links, the quick starts beside the\n// most read pages, what is new from the registries, and the owl's promise. One column on a phone, the search first.\nimport { MascotQuote } from \"@krizaka/ui/mascot-quote\";\nimport { Section } from \"@krizaka/ui/page\";\nimport type { LinkComponent } from \"@krizaka/ui/page-hero\";\nimport { PageHero } from \"@krizaka/ui/page-hero\";\nimport * as React from \"react\";\n\nexport interface DocsCollection {\n  /** A stable key. */\n  id: string;\n  /** The product's brand (`orazaka`…): the panel wears `.brand-<id>`. */\n  brand?: string;\n  /** The product's mark. */\n  mark?: React.ReactNode;\n  /** The collection's name: a link to its home. */\n  title: string;\n  /** Where it starts. */\n  href: string;\n  /** What it covers, in one sentence. */\n  description?: React.ReactNode;\n  /** Its most useful pages (three or four). */\n  links?: readonly { href: string; label: string }[];\n}\n\nexport interface DocsHubLink {\n  /** Where it leads. */\n  href: string;\n  /** The page's title. */\n  title: React.ReactNode;\n  /** On the right, in mono: a collection, a version, a date. */\n  meta?: React.ReactNode;\n}\n\nexport type DocsHubPageProps = Omit<React.HTMLAttributes<HTMLElement>, \"title\"> & {\n  /** A mono line above the title. */\n  eyebrow?: React.ReactNode;\n  /** The page's `h1`. */\n  title: React.ReactNode;\n  /** One sentence under it. */\n  lead?: React.ReactNode;\n  /** The search, front and centre (a SearchField, a button that opens the command palette). */\n  search?: React.ReactNode;\n  /** Under the search: what people look for (a few links or keys). */\n  searchHints?: React.ReactNode;\n  /** The collections' heading. */\n  collectionsTitle: React.ReactNode;\n  /** The collections, each in its brand. */\n  collections: readonly DocsCollection[];\n  /** The quick starts: a title and their samples (CodeBlocks, CodeTabs). */\n  quickstarts?: { title: React.ReactNode; children: React.ReactNode };\n  /** The most read pages. */\n  popular?: { title: React.ReactNode; items: readonly DocsHubLink[] };\n  /** What is new (releases from the registries, published pages). */\n  whatsNew?: { title: React.ReactNode; items: readonly DocsHubLink[] };\n  /** The owl's promise at the foot: what this documentation guarantees. */\n  promise?: { label: React.ReactNode; text: React.ReactNode };\n  /** The app's link component (Next's `Link`) for internal addresses. */\n  linkAs?: LinkComponent;\n};\n\nfunction List({ items, linkAs: Link = \"a\" }: { items: readonly DocsHubLink[]; linkAs?: LinkComponent }) {\n  const L = Link as React.ElementType;\n  return (\n    <ul className=\"kz-tpl-links\">\n      {items.map((item, i) => (\n        <li key={`${i}:${item.href}`}>\n          <L href={item.href}>\n            <strong>{item.title}</strong>\n            {item.meta && <small>{item.meta}</small>}\n          </L>\n        </li>\n      ))}\n    </ul>\n  );\n}\n\n/** A documentation hub: search first, the collections in their brand, quick starts, popular and new pages. */\nexport function DocsHubPage({ eyebrow, title, lead, search, searchHints, collectionsTitle, collections, quickstarts, popular, whatsNew, promise, linkAs, ...props }: DocsHubPageProps) {\n  const L = (linkAs ?? \"a\") as React.ElementType;\n  return (\n    <div {...props}>\n      <PageHero eyebrow={eyebrow} title={title} lead={lead} align=\"center\" backdrop=\"grid\">\n        {(search || searchHints) && (\n          <div className=\"kz-tpl-hub-search\">\n            {search}\n            {searchHints && <div className=\"kz-tpl-hub-hints\">{searchHints}</div>}\n          </div>\n        )}\n      </PageHero>\n      <Section id=\"collections\" title={collectionsTitle} headingSize=\"sm\" spacing=\"sm\">\n        <ul className=\"kz-tpl-collections\">\n          {collections.map((c) => (\n            <li key={c.id} className={c.brand ? \"brand-\" + c.brand : undefined}>\n              <div className=\"kz-tpl-collection\">\n                <div className=\"kz-tpl-collection-head\">\n                  {c.mark && <span aria-hidden>{c.mark}</span>}\n                  <L href={c.href}>{c.title}</L>\n                </div>\n                {c.description && <p>{c.description}</p>}\n                {c.links && c.links.length > 0 && (\n                  <ul aria-label={c.title}>\n                    {c.links.map((l) => (\n                      <li key={l.href}>\n                        <L href={l.href}>{l.label}</L>\n                      </li>\n                    ))}\n                  </ul>\n                )}\n              </div>\n            </li>\n          ))}\n        </ul>\n      </Section>\n      {(quickstarts || popular) && (\n        <Section spacing=\"sm\" divider aria-label={typeof quickstarts?.title === \"string\" ? quickstarts.title : undefined}>\n          <div className=\"kz-tpl-two\">\n            {quickstarts && (\n              <div className=\"kz-tpl-stack\">\n                <h2 className=\"kz-heading-title kz-tpl-h2\">{quickstarts.title}</h2>\n                {quickstarts.children}\n              </div>\n            )}\n            {popular && (\n              <div className=\"kz-tpl-stack\">\n                <h2 className=\"kz-heading-title kz-tpl-h2\">{popular.title}</h2>\n                <List items={popular.items} linkAs={linkAs} />\n              </div>\n            )}\n          </div>\n        </Section>\n      )}\n      {whatsNew && (\n        <Section id=\"whats-new\" title={whatsNew.title} headingSize=\"sm\" spacing=\"sm\" divider>\n          <List items={whatsNew.items} linkAs={linkAs} />\n        </Section>\n      )}\n      {promise && (\n        <Section spacing=\"sm\" aria-label={typeof promise.label === \"string\" ? promise.label : undefined}>\n          <MascotQuote variant=\"callout\" bird=\"owl\" mood=\"welcome\" label={promise.label}>\n            {promise.text}\n          </MascotQuote>\n        </Section>\n      )}\n    </div>\n  );\n}\n"
+    },
+    {
+      "path": "docs-hub-page/index.ts",
+      "content": "/** @krizaka/ui/docs-hub-page — `DocsHubPage`: A documentation hub: search first, the collections in their brand, quick starts, popular and new pages. Server-safe; a page template. */\nexport { type DocsCollection, type DocsHubLink,DocsHubPage, type DocsHubPageProps } from \"./docs-hub-page\";\n"
+    },
+    {
+      "path": "docs-hub-page/meta.ts",
+      "content": "import type { ComponentMeta } from \"../meta\";\n\nexport const meta = {\n  title: \"Docs hub page\",\n  summary: \"The entry of a documentation: the search in the middle of the hero, the collections each in its product's brand with their quick links, quick starts beside the most read pages, what is new, the owl's promise.\",\n  status: \"beta\",\n  category: \"templates\",\n  platforms: \"web\",\n  whenToUse: [\"The home of a documentation with several collections.\", \"A help centre's entry.\"],\n  whenNotToUse: [\n    { when: \"For one article of the documentation.\", use: \"docs-article-page\" },\n    { when: \"For a plain list of entry points.\", use: \"link-card\" },\n  ],\n  bestPractices: [\"The search first: most readers come to find one page.\", \"Each collection in its product's brand, with three or four quick links.\", \"What is new comes from the registries, never typed by hand.\", \"Words and content arrive as props; the motion is the platform's (`[data-reveal]`, still under reduced motion).\"],\n  accessibility: {\n    keyboard: [],\n    notes: [\"One `h1`; each collection a list item with its main link and a named list of quick links.\", \"The lists of pages are lists of links with their meta in words.\"],\n  },\n  related: [\"docs-article-page\", \"link-card\", \"search-field\"],\n  web: {\n    imports: [\"DocsHubPage\"],\n    examples: [\n      { name: \"krizaka\", title: \"krizaka.com/docs\", description: \"The five collections, a quick start, the most read pages, what is new.\", template: true },\n    ],\n  },\n} satisfies ComponentMeta;\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  | \"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"
+    }
+  ],
+  "dependencies": [],
+  "registryDependencies": [
+    "mascot-quote",
+    "page",
+    "page-hero"
+  ],
+  "demo": {
+    "path": "examples/docs-hub-page/krizaka.tsx",
+    "content": "import { ProductLogo } from \"@krizaka/ui\";\nimport { Button } from \"@krizaka/ui/button\";\nimport { CodeBlock } from \"@krizaka/ui/code-block\";\nimport { DocsHubPage } from \"@krizaka/ui/docs-hub-page\";\nimport { Kbd } from \"@krizaka/ui/kbd\";\n\nconst COLLECTIONS = [\n  { id: \"ui\", title: \"Krizaka UI\", href: \"#ui\", mark: <ProductLogo id=\"krizaka\" size={26} animated={false} />, description: \"Tokens, a Tailwind preset, the components — live, generated from their code.\", links: [{ href: \"#blocks\", label: \"Blocks\" }, { href: \"#layouts\", label: \"Layouts\" }, { href: \"#templates\", label: \"Templates\" }] },\n  { id: \"java\", title: \"Krizaka Java\", href: \"#java\", mark: <ProductLogo id=\"krizaka\" size={26} animated={false} />, description: \"Parent, BOM, starters, messaging, Problem Details.\", links: [{ href: \"#bom\", label: \"BOM\" }, { href: \"#messaging\", label: \"Messaging\" }] },\n  { id: \"orazaka\", brand: \"orazaka\", title: \"Orazaka\", href: \"#orazaka\", mark: <ProductLogo id=\"orazaka\" size={26} animated={false} />, description: \"The sovereign AI engine: install, packs, administration.\", links: [{ href: \"#cli\", label: \"CLI\" }, { href: \"#packs\", label: \"Packs\" }, { href: \"#admin\", label: \"Admin\" }] },\n  { id: \"orochia\", brand: \"orochia\", title: \"Orochia\", href: \"#orochia\", mark: <ProductLogo id=\"orochia\" size={26} animated={false} />, description: \"The creator platform: payments, auctions, the admin console.\", links: [{ href: \"#payouts\", label: \"Payouts\" }, { href: \"#console\", label: \"Console\" }] },\n];\n\n// TEMPLATE — krizaka.com/docs: the search in the middle of the hero (⌘K), the collections each in its product's brand\n// with their quick links, a quick start beside the most read pages, what is new, the owl's promise. On a phone: search,\n// then one collection per row.\nexport default function DocsHubPageKrizaka() {\n  return (\n    <DocsHubPage\n      eyebrow=\"Documentation\"\n      title=\"Build with Krizaka\"\n      lead=\"Every building block the products are made of, documented from its source.\"\n      search={\n        <Button variant=\"secondary\" size=\"lg\" shape=\"cut\" className=\"w-full justify-between text-fg-secondary\">\n          Search the documentation <Kbd>⌘K</Kbd>\n        </Button>\n      }\n      searchHints={<>Try: <a href=\"#cli\">orazaka install</a> · <a href=\"#button\">Button</a> · <a href=\"#bom\">BOM</a></>}\n      collectionsTitle=\"Collections\"\n      collections={COLLECTIONS}\n      quickstarts={{ title: \"Start in one line\", children: <CodeBlock code=\"npx orazaka install\" language=\"bash\" file=\"Terminal\" copyLabel=\"Copy\" copiedLabel=\"Copied\" /> }}\n      popular={{ title: \"Most read\", items: [{ href: \"#cli\", title: \"The CLI\", meta: \"Orazaka\" }, { href: \"#button\", title: \"Button\", meta: \"Krizaka UI\" }, { href: \"#bom\", title: \"The BOM\", meta: \"Java\" }] }}\n      whatsNew={{ title: \"What's new\", items: [{ href: \"#ui-260\", title: \"Page blocks: frame, hero, cards, decisions\", meta: \"@krizaka/ui 2.6.0\" }, { href: \"#java-010\", title: \"The platform kit on Maven Central\", meta: \"0.1.0\" }] }}\n      promise={{ label: \"The owl's promise\", text: \"Every page here is generated from the code it documents — when the code changes, the page does.\" }}\n    />\n  );\n}\n"
+  },
+  "props": [
+    {
+      "component": "DocsHubPage",
+      "description": "A documentation hub: search first, the collections in their brand, quick starts, popular and new pages.",
+      "props": [
+        {
+          "name": "collections",
+          "type": "readonly DocsCollection[]",
+          "default": null,
+          "description": "The collections, each in its brand.",
+          "required": true
+        },
+        {
+          "name": "collectionsTitle",
+          "type": "ReactNode",
+          "default": null,
+          "description": "The collections' heading.",
+          "required": true
+        },
+        {
+          "name": "title",
+          "type": "ReactNode",
+          "default": null,
+          "description": "The page's `h1`.",
+          "required": true
+        },
+        {
+          "name": "eyebrow",
+          "type": "ReactNode",
+          "default": null,
+          "description": "A mono line above the title.",
+          "required": false
+        },
+        {
+          "name": "lead",
+          "type": "ReactNode",
+          "default": null,
+          "description": "One sentence under it.",
+          "required": false
+        },
+        {
+          "name": "linkAs",
+          "type": "LinkComponent",
+          "default": null,
+          "description": "The app's link component (Next's `Link`) for internal addresses.",
+          "required": false
+        },
+        {
+          "name": "popular",
+          "type": "{ title: ReactNode; items: readonly DocsHubLink[]; }",
+          "default": null,
+          "description": "The most read pages.",
+          "required": false
+        },
+        {
+          "name": "promise",
+          "type": "{ label: ReactNode; text: ReactNode; }",
+          "default": null,
+          "description": "The owl's promise at the foot: what this documentation guarantees.",
+          "required": false
+        },
+        {
+          "name": "quickstarts",
+          "type": "{ title: ReactNode; children: ReactNode; }",
+          "default": null,
+          "description": "The quick starts: a title and their samples (CodeBlocks, CodeTabs).",
+          "required": false
+        },
+        {
+          "name": "search",
+          "type": "ReactNode",
+          "default": null,
+          "description": "The search, front and centre (a SearchField, a button that opens the command palette).",
+          "required": false
+        },
+        {
+          "name": "searchHints",
+          "type": "ReactNode",
+          "default": null,
+          "description": "Under the search: what people look for (a few links or keys).",
+          "required": false
+        },
+        {
+          "name": "whatsNew",
+          "type": "{ title: ReactNode; items: readonly DocsHubLink[]; }",
+          "default": null,
+          "description": "What is new (releases from the registries, published pages).",
+          "required": false
+        }
+      ]
+    }
+  ]
+}

package/registry/docs-layout.json

@@ -0,0 +1,148 @@
+{
+  "name": "docs-layout",
+  "type": "primitive",
+  "title": "Docs layout",
+  "summary": "A documentation page in the site's frame: the pages, the article and its contents on a wide screen; on a phone the pages fold into a disclosure above the article.",
+  "description": "A documentation page in the site's frame: the pages, the article and its contents on a wide screen; on a phone the pages fold into a disclosure above the article.",
+  "status": "beta",
+  "category": "layouts",
+  "platforms": "web",
+  "whenToUse": [
+    "A documentation without a docs engine, or around one.",
+    "Guides and references of a product."
+  ],
+  "whenNotToUse": [
+    {
+      "when": "For a reading page of a site without a list of pages.",
+      "use": "toc"
+    },
+    {
+      "when": "For a hub of entry points.",
+      "use": "link-card"
+    }
+  ],
+  "bestPractices": [
+    "The frame of the docs is wider (`--kz-page-max-docs`): give the bar the same width on these pages.",
+    "Keep the article under 48rem; the contents list three to eight headings."
+  ],
+  "accessibility": {
+    "keyboard": [
+      {
+        "keys": "Enter / Space",
+        "action": "On a phone, opens or closes the list of pages."
+      }
+    ],
+    "notes": [
+      "The pages are your `nav`; on a phone the same nav sits in a native `details`.",
+      "The article is an `article`; the contents a `Toc`."
+    ]
+  },
+  "related": [
+    "toc",
+    "page",
+    "marketing-layout"
+  ],
+  "web": {
+    "entry": "@krizaka/ui/docs-layout",
+    "import": "import { DocsLayout } from \"@krizaka/ui/docs-layout\";",
+    "props": [
+      {
+        "component": "DocsLayout",
+        "description": "A documentation page: pages · article · contents, in the site's frame.",
+        "props": [
+          {
+            "name": "sidebar",
+            "type": "ReactNode",
+            "default": null,
+            "description": "The pages of the documentation (a nav of links, grouped).",
+            "required": true
+          },
+          {
+            "name": "sidebarLabel",
+            "type": "string",
+            "default": null,
+            "description": "On a phone the sidebar is folded: the words that open it (`Pages of the documentation`).",
+            "required": true
+          },
+          {
+            "name": "toc",
+            "type": "ReactNode",
+            "default": null,
+            "description": "The page's table of contents (a `Toc` of\n@krizaka /ui/toc): beside the article from `xl`.",
+            "required": false
+          }
+        ]
+      }
+    ],
+    "examples": [
+      {
+        "name": "page",
+        "title": "A documentation page",
+        "description": "Pages, an article with two headings, its contents.",
+        "path": "examples/docs-layout/page.tsx",
+        "module": "@krizaka/ui/registry/examples/docs-layout/page",
+        "code": "import { DocsLayout } from \"@krizaka/ui/docs-layout\";\nimport { Toc } from \"@krizaka/ui/toc\";\n\nconst PAGES = [\"Getting started\", \"Architecture\", \"API reference\"];\n\n// A documentation page in the site's frame: pages · article · contents; on a phone the pages fold above the article.\nexport default function DocsLayoutPage() {\n  return (\n    <DocsLayout\n      className=\"pt-6\"\n      sidebarLabel=\"Pages of the documentation\"\n      sidebar={\n        <nav aria-label=\"Documentation\">\n          <ul className=\"flex flex-col gap-1 text-sm\">\n            {PAGES.map((p, i) => (\n              <li key={p}>\n                <a href={`#${i}`} aria-current={i === 0 ? \"page\" : undefined} className=\"block rounded-md px-3 py-2 text-fg-secondary no-underline hover:bg-surface-2 aria-[current=page]:bg-accent-soft aria-[current=page]:text-fg\">{p}</a>\n              </li>\n            ))}\n          </ul>\n        </nav>\n      }\n      toc={<Toc label=\"On this page\" items={[{ id: \"install\", label: \"Install\" }, { id: \"run\", label: \"Run\" }]} />}\n    >\n      <h1 className=\"font-display text-3xl font-extrabold text-fg\">Getting started</h1>\n      <h2 id=\"install\" className=\"mt-6 text-xl font-bold text-fg\">Install</h2>\n      <p className=\"mt-2 text-sm text-fg-secondary\">npx orazaka install</p>\n    </DocsLayout>\n  );\n}\n"
+      }
+    ]
+  },
+  "native": null,
+  "files": [
+    {
+      "path": "docs-layout/docs-layout.tsx",
+      "content": "// Server-safe. A documentation page in the site's frame (--kz-page-max-docs): the sidebar of pages, the article, the\n// table of contents — the three columns of the frame on a wide screen, the sidebar folded into a disclosure above the\n// article on a phone, the contents under the title as chips (a `Toc`). Its edges are the bar's: no column runs to the\n// window's edge.\nimport type * as React from \"react\";\nimport { tv } from \"tailwind-variants\";\n\nimport { ChevronGlyph } from \"../glyphs\";\n\nexport const docsLayout = tv({\n  slots: {\n    root:\n      \"mx-auto grid w-full max-w-[calc(var(--kz-page-max-docs,88rem)+2*var(--kz-page-gutter,24px))] grid-cols-1 gap-8 px-(--kz-page-gutter,16px) \" +\n      \"pt-(--kz-hero-top,6rem) pb-16 lg:grid-cols-[15rem_minmax(0,1fr)] xl:grid-cols-[15rem_minmax(0,1fr)_13rem]\",\n    sidebar: \"hidden lg:block lg:sticky lg:top-24 lg:max-h-[calc(100dvh-7rem)] lg:self-start lg:overflow-y-auto\",\n    mobileNav: \"rounded-xl border border-border-default bg-surface-1 lg:hidden\",\n    mobileSummary:\n      \"flex min-h-11 cursor-pointer list-none items-center justify-between gap-2 px-4 text-sm font-semibold text-fg [&::-webkit-details-marker]:hidden \" +\n      \"rounded-xl focus-visible:outline-hidden focus-visible:ring-2 focus-visible:ring-ring [[open]>&>svg]:rotate-180\",\n    mobileBody: \"border-t border-border-subtle px-2 py-2\",\n    article: \"min-w-0 max-w-3xl\",\n    toc: \"hidden xl:block xl:sticky xl:top-24 xl:self-start\",\n  },\n});\nconst s = docsLayout();\n\nexport type DocsLayoutProps = React.ComponentProps<\"div\"> & {\n  /** The pages of the documentation (a nav of links, grouped). */\n  sidebar: React.ReactNode;\n  /** On a phone the sidebar is folded: the words that open it (`Pages of the documentation`). */\n  sidebarLabel: string;\n  /** The page's table of contents (a `Toc` of @krizaka/ui/toc): beside the article from `xl`. */\n  toc?: React.ReactNode;\n  /** The article: its title, its body. */\n  children: React.ReactNode;\n};\n\n/** A documentation page: pages · article · contents, in the site's frame. */\nexport function DocsLayout({ sidebar, sidebarLabel, toc, className, children, ...props }: DocsLayoutProps) {\n  return (\n    <div className={s.root({ className })} {...props}>\n      <div className={s.sidebar()}>{sidebar}</div>\n      <div className=\"flex min-w-0 flex-col gap-6\">\n        <details className={s.mobileNav()}>\n          <summary className={s.mobileSummary()}>\n            {sidebarLabel} <ChevronGlyph className=\"h-4 w-4 transition-transform motion-reduce:transition-none\" />\n          </summary>\n          <div className={s.mobileBody()}>{sidebar}</div>\n        </details>\n        <article className={s.article()}>{children}</article>\n      </div>\n      {toc && <div className={s.toc()}>{toc}</div>}\n    </div>\n  );\n}\n"
+    },
+    {
+      "path": "docs-layout/index.ts",
+      "content": "/** @krizaka/ui/docs-layout — `DocsLayout`: pages · article · contents in the site's frame. Server-safe. */\nexport { DocsLayout, docsLayout, type DocsLayoutProps } from \"./docs-layout\";\n"
+    },
+    {
+      "path": "docs-layout/meta.ts",
+      "content": "import type { ComponentMeta } from \"../meta\";\n\nexport const meta = {\n  title: \"Docs layout\",\n  summary: \"A documentation page in the site's frame: the pages, the article and its contents on a wide screen; on a phone the pages fold into a disclosure above the article.\",\n  status: \"beta\",\n  category: \"layouts\",\n  platforms: \"web\",\n  whenToUse: [\"A documentation without a docs engine, or around one.\", \"Guides and references of a product.\"],\n  whenNotToUse: [\n    { when: \"For a reading page of a site without a list of pages.\", use: \"toc\" },\n    { when: \"For a hub of entry points.\", use: \"link-card\" },\n  ],\n  bestPractices: [\"The frame of the docs is wider (`--kz-page-max-docs`): give the bar the same width on these pages.\", \"Keep the article under 48rem; the contents list three to eight headings.\"],\n  accessibility: {\n    keyboard: [\n      { keys: \"Enter / Space\", action: \"On a phone, opens or closes the list of pages.\" }\n    ],\n    notes: [\"The pages are your `nav`; on a phone the same nav sits in a native `details`.\", \"The article is an `article`; the contents a `Toc`.\"],\n  },\n  related: [\"toc\", \"page\", \"marketing-layout\"],\n  web: {\n    imports: [\"DocsLayout\"],\n    examples: [\n      { name: \"page\", title: \"A documentation page\", description: \"Pages, an article with two headings, its contents.\" },\n    ],\n  },\n} satisfies ComponentMeta;\n"
+    },
+    {
+      "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  | \"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"
+    }
+  ],
+  "dependencies": [
+    "tailwind-variants@^3.3.1"
+  ],
+  "registryDependencies": [],
+  "demo": {
+    "path": "examples/docs-layout/page.tsx",
+    "content": "import { DocsLayout } from \"@krizaka/ui/docs-layout\";\nimport { Toc } from \"@krizaka/ui/toc\";\n\nconst PAGES = [\"Getting started\", \"Architecture\", \"API reference\"];\n\n// A documentation page in the site's frame: pages · article · contents; on a phone the pages fold above the article.\nexport default function DocsLayoutPage() {\n  return (\n    <DocsLayout\n      className=\"pt-6\"\n      sidebarLabel=\"Pages of the documentation\"\n      sidebar={\n        <nav aria-label=\"Documentation\">\n          <ul className=\"flex flex-col gap-1 text-sm\">\n            {PAGES.map((p, i) => (\n              <li key={p}>\n                <a href={`#${i}`} aria-current={i === 0 ? \"page\" : undefined} className=\"block rounded-md px-3 py-2 text-fg-secondary no-underline hover:bg-surface-2 aria-[current=page]:bg-accent-soft aria-[current=page]:text-fg\">{p}</a>\n              </li>\n            ))}\n          </ul>\n        </nav>\n      }\n      toc={<Toc label=\"On this page\" items={[{ id: \"install\", label: \"Install\" }, { id: \"run\", label: \"Run\" }]} />}\n    >\n      <h1 className=\"font-display text-3xl font-extrabold text-fg\">Getting started</h1>\n      <h2 id=\"install\" className=\"mt-6 text-xl font-bold text-fg\">Install</h2>\n      <p className=\"mt-2 text-sm text-fg-secondary\">npx orazaka install</p>\n    </DocsLayout>\n  );\n}\n"
+  },
+  "props": [
+    {
+      "component": "DocsLayout",
+      "description": "A documentation page: pages · article · contents, in the site's frame.",
+      "props": [
+        {
+          "name": "sidebar",
+          "type": "ReactNode",
+          "default": null,
+          "description": "The pages of the documentation (a nav of links, grouped).",
+          "required": true
+        },
+        {
+          "name": "sidebarLabel",
+          "type": "string",
+          "default": null,
+          "description": "On a phone the sidebar is folded: the words that open it (`Pages of the documentation`).",
+          "required": true
+        },
+        {
+          "name": "toc",
+          "type": "ReactNode",
+          "default": null,
+          "description": "The page's table of contents (a `Toc` of\n@krizaka /ui/toc): beside the article from `xl`.",
+          "required": false
+        }
+      ]
+    }
+  ]
+}

package/registry/dropdown-menu.json

@@ -82,7 +82,7 @@
         "props": [
           {
             "name": "tone",
-            "type": "\"danger\" | \"default\"",
+            "type": "\"default\" | \"danger\"",
             "default": null,
             "description": "`danger` for a destructive action: the icon and the highlight carry the danger, the label stays legible.",
             "required": false
@@ -126,7 +126,7 @@
     },
     {
       "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"
     }
   ],
   "dependencies": [
@@ -160,7 +160,7 @@
       "props": [
         {
           "name": "tone",
-          "type": "\"danger\" | \"default\"",
+          "type": "\"default\" | \"danger\"",
           "default": null,
           "description": "`danger` for a destructive action: the icon and the highlight carry the danger, the label stays legible.",
           "required": false

package/registry/empty-state.json

@@ -176,7 +176,7 @@
     },
     {
       "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"
     }
   ],
   "dependencies": [