@krizaka/ui 2.9.0 → 3.0.0

package/registry/list.json

@@ -0,0 +1,249 @@
+{
+  "name": "list",
+  "type": "native",
+  "title": "List",
+  "summary": "A long list for React Native on FlashList v2 — separators, skeleton rows, empty and error states, pull to refresh, the next page loaded near the end through useInfiniteQuery of @krizaka/query.",
+  "description": "A long list for React Native on FlashList v2 — separators, skeleton rows, empty and error states, pull to refresh, the next page loaded near the end through useInfiniteQuery of @krizaka/query.",
+  "status": "beta",
+  "category": "data-display",
+  "platforms": "native",
+  "whenToUse": [
+    "Any scrolling list of an app screen: notifications, messages, a feed, search results, payouts.",
+    "A paginated API (`useInfiniteList`): one hook, one component — pages, refresh and errors handled."
+  ],
+  "whenNotToUse": [
+    {
+      "when": "On the web: the virtual list, or the data table for columns.",
+      "use": "virtual"
+    },
+    {
+      "when": "For a few items that never scroll: lay them out in a View.",
+      "use": "card"
+    }
+  ],
+  "bestPractices": [
+    "Give `keyExtractor` an id: FlashList recycles the views by it.",
+    "Fetch with `useInfiniteList` (a `defineKeys` key, `krizakaFetch` in `queryFn`) and spread its `listProps` on `List`.",
+    "Render `error` with an `ErrorState` and a retry; give `empty` its words (`{ title, description, action }`).",
+    "Keep `renderItem` light (no state per item): views are recycled while the person scrolls."
+  ],
+  "accessibility": {
+    "keyboard": [],
+    "notes": [
+      "The list is named by `label`; while the first page loads it is `aria-busy` and its skeleton rows are hidden from assistive technology.",
+      "An error is announced (`role=\"alert\"`); the spinner of the next page is named by `loadingMoreLabel`.",
+      "Pull to refresh is the system's control (tinted with the theme); `onRefresh` should also be reachable from a button for switch and voice access."
+    ]
+  },
+  "related": [
+    "virtual",
+    "empty-state",
+    "skeleton",
+    "spinner",
+    "pagination"
+  ],
+  "web": null,
+  "native": {
+    "entry": "@krizaka/ui/native/list",
+    "import": "import { List, useInfiniteList } from \"@krizaka/ui/native/list\";",
+    "differences": [],
+    "props": [
+      {
+        "component": "List",
+        "description": "A long list on FlashList v2 (recycled views, 60 fps): separators, skeleton rows while the first page loads, an empty\nor error state in place of the items, pull to refresh tinted with the theme, the next page asked for near the end and\na spinner under the last item. With `useInfiniteList`, a paginated API is one hook and one component.",
+        "props": [
+          {
+            "name": "data",
+            "type": "readonly T[]",
+            "default": null,
+            "description": "The items (stable: a query's data, state).",
+            "required": true
+          },
+          {
+            "name": "keyExtractor",
+            "type": "(item: T, index: number) => string",
+            "default": null,
+            "description": "A stable key per item (an id): FlashList recycles the views by it.",
+            "required": true
+          },
+          {
+            "name": "label",
+            "type": "string",
+            "default": null,
+            "description": "The accessible name of the list (\"Notifications\"), passed translated.",
+            "required": true
+          },
+          {
+            "name": "renderItem",
+            "type": "(item: T, index: number) => ReactElement<unknown, string | JSXElementConstructor<any>> | null",
+            "default": null,
+            "description": "Draws one item.",
+            "required": true
+          },
+          {
+            "name": "contentContainerStyle",
+            "type": "StyleProp<ViewStyle>",
+            "default": null,
+            "description": "Styles of the list's content (padding).",
+            "required": false
+          },
+          {
+            "name": "empty",
+            "type": "ReactNode | { title: string; description?: string; action?: ReactNode; }",
+            "default": null,
+            "description": "Shown when there is no item (an `EmptyState`, or its words: `{ title, description, action }`).",
+            "required": false
+          },
+          {
+            "name": "endReachedThreshold",
+            "type": "number",
+            "default": "0.5",
+            "description": "How far from the end `onEndReached` fires, in screens. Default 0.5.",
+            "required": false
+          },
+          {
+            "name": "error",
+            "type": "ReactNode",
+            "default": null,
+            "description": "A failure, shown in place of the items (an `ErrorState` with a retry).",
+            "required": false
+          },
+          {
+            "name": "extraData",
+            "type": "unknown",
+            "default": null,
+            "description": "Extra data the items depend on (a selection): a change re-renders the visible items.",
+            "required": false
+          },
+          {
+            "name": "footer",
+            "type": "ReactElement<unknown, string | JSXElementConstructor<any>>",
+            "default": null,
+            "description": "Under the last item.",
+            "required": false
+          },
+          {
+            "name": "header",
+            "type": "ReactElement<unknown, string | JSXElementConstructor<any>>",
+            "default": null,
+            "description": "Above the first item (a title, filters): scrolls with the list.",
+            "required": false
+          },
+          {
+            "name": "loading",
+            "type": "boolean",
+            "default": null,
+            "description": "The first page is loading: skeleton rows (`loadingRows` of them) in place of the items.",
+            "required": false
+          },
+          {
+            "name": "loadingMore",
+            "type": "boolean",
+            "default": null,
+            "description": "The next page is loading: a spinner under the last item, named by `loadingMoreLabel`.",
+            "required": false
+          },
+          {
+            "name": "loadingMoreLabel",
+            "type": "string",
+            "default": "Loading more",
+            "description": "The name of that spinner (\"Loading more\"), passed translated.",
+            "required": false
+          },
+          {
+            "name": "loadingRows",
+            "type": "number",
+            "default": "6",
+            "description": "How many skeleton rows while loading. Default 6.",
+            "required": false
+          },
+          {
+            "name": "onEndReached",
+            "type": "(() => void)",
+            "default": null,
+            "description": "Called when the end comes near: load the next page.",
+            "required": false
+          },
+          {
+            "name": "onRefresh",
+            "type": "(() => void)",
+            "default": null,
+            "description": "Pull to refresh: called when the person pulls the list down.",
+            "required": false
+          },
+          {
+            "name": "ref",
+            "type": "Ref<FlashListRef<T>>",
+            "default": null,
+            "description": "The FlashList, for `scrollToIndex` / `scrollToOffset`.",
+            "required": false
+          },
+          {
+            "name": "refreshing",
+            "type": "boolean",
+            "default": "false",
+            "description": "The list is reloading after a pull: the system's spinner at the top.",
+            "required": false
+          },
+          {
+            "name": "separator",
+            "type": "\"none\" | \"full\" | \"inset\"",
+            "default": "full",
+            "description": "A hairline between items: `full` (default), `inset` (aligned with the text after an avatar), `none`.",
+            "required": false
+          },
+          {
+            "name": "style",
+            "type": "StyleProp<ViewStyle>",
+            "default": null,
+            "description": "Styles merged last, on the list.",
+            "required": false
+          }
+        ]
+      }
+    ],
+    "examples": [
+      {
+        "name": "default",
+        "title": "Default",
+        "description": "Notifications with avatars, separators inset after the avatar.",
+        "path": "examples/list/native/default.tsx",
+        "module": "@krizaka/ui/registry/examples/list/native/default",
+        "code": "import { Avatar, Txt } from \"@krizaka/ui/native\";\nimport { List } from \"@krizaka/ui/native/list\";\nimport { View } from \"react-native\";\n\ntype Notification = { id: string; who: string; what: string; when: string };\nconst notifications: Notification[] = [\n  { id: \"n1\", who: \"Elena Varga\", what: \"tipped your video “Sunset over Montréal”\", when: \"2 min\" },\n  { id: \"n2\", who: \"Noah Petit\", what: \"started following you\", when: \"1 h\" },\n  { id: \"n3\", who: \"Maya Chen\", what: \"commented: “The drone shot!”\", when: \"3 h\" },\n];\n\n// A FlashList v2 with the theme's separators, inset after the avatar.\nexport default function NativeListDefault() {\n  return (\n    <List\n      label=\"Notifications\"\n      data={notifications}\n      keyExtractor={(n) => n.id}\n      separator=\"inset\"\n      renderItem={(n) => (\n        <View style={{ flexDirection: \"row\", alignItems: \"center\", gap: 12, paddingHorizontal: 16, paddingVertical: 12 }}>\n          <Avatar alt={n.who} size=\"md\" />\n          <View style={{ flex: 1 }}>\n            <Txt>{`${n.who} ${n.what}`}</Txt>\n            <Txt variant=\"caption\" tone=\"secondary\">{n.when}</Txt>\n          </View>\n        </View>\n      )}\n    />\n  );\n}\n",
+        "screenshots": {
+          "dark": "examples/list/native/default.dark.png",
+          "light": "examples/list/native/default.light.png"
+        }
+      },
+      {
+        "name": "infinite",
+        "title": "Infinite",
+        "description": "`useInfiniteList` on a paginated API (faked here with `configureKrizakaFetch`): the next page near the end, pull to refresh.",
+        "path": "examples/list/native/infinite.tsx",
+        "module": "@krizaka/ui/registry/examples/list/native/infinite",
+        "code": "import { configureKrizakaFetch, krizakaFetch, KrizakaQueryProvider } from \"@krizaka/query\";\nimport { Txt } from \"@krizaka/ui/native\";\nimport { List, useInfiniteList } from \"@krizaka/ui/native/list\";\nimport { useState } from \"react\";\n\ntype Page = { items: { id: string; title: string }[]; next: number | null };\n// The API, faked in the screen: 20 videos per page, 5 pages.\nasync function fakeApi(input: RequestInfo | URL) {\n  const cursor = Number(new URL(String(input), \"https://api.example\").searchParams.get(\"cursor\"));\n  const items = Array.from({ length: 20 }, (_, i) => ({ id: `v${cursor + i}`, title: `Video ${cursor + i + 1}` }));\n  return Response.json({ items, next: cursor + 20 < 100 ? cursor + 20 : null } satisfies Page);\n}\n\nfunction Videos() {\n  const { listProps, error } = useInfiniteList({\n    queryKey: [\"videos\", \"feed\"],\n    queryFn: ({ pageParam, signal }) => krizakaFetch(\"/api/videos\", { query: { cursor: pageParam }, signal }) as Promise<Page>,\n    initialPageParam: 0,\n    getNextPageParam: (last) => last.next,\n    getItems: (page) => page.items,\n  });\n  return (\n    <List label=\"Videos\" {...listProps} error={error ? <Txt>Could not load the videos.</Txt> : undefined} keyExtractor={(v) => v.id} renderItem={(v) => <Txt style={{ padding: 16 }}>{v.title}</Txt>} />\n  );\n}\n\n// A paginated API as a list: the next page near the end, pull to refresh, the query of @krizaka/query.\nexport default function NativeListInfinite() {\n  useState(() => configureKrizakaFetch({ fetch: fakeApi as typeof fetch }));\n  return (\n    <KrizakaQueryProvider>\n      <Videos />\n    </KrizakaQueryProvider>\n  );\n}\n",
+        "screenshots": {
+          "dark": "examples/list/native/infinite.dark.png",
+          "light": "examples/list/native/infinite.light.png"
+        }
+      },
+      {
+        "name": "states",
+        "title": "Loading and empty",
+        "description": "Skeleton rows while the first page loads; the empty state with what to do next.",
+        "path": "examples/list/native/states.tsx",
+        "module": "@krizaka/ui/registry/examples/list/native/states",
+        "code": "import { Button } from \"@krizaka/ui/native\";\nimport { List } from \"@krizaka/ui/native/list\";\nimport { View } from \"react-native\";\n\nconst NONE: { id: string }[] = [];\n\n// While the first page loads: skeleton rows. Nothing yet: the empty state and what to do next.\nexport default function NativeListStates() {\n  return (\n    <View style={{ gap: 24, width: \"100%\" }}>\n      <List label=\"Messages\" data={NONE} keyExtractor={(m) => m.id} renderItem={() => null} loading loadingRows={3} />\n      <List\n        label=\"Messages\"\n        data={NONE}\n        keyExtractor={(m) => m.id}\n        renderItem={() => null}\n        empty={{ title: \"No message yet\", description: \"Say hello to a creator you follow.\", action: <Button label=\"Find creators\" size=\"sm\" /> }}\n      />\n    </View>\n  );\n}\n",
+        "screenshots": {
+          "dark": "examples/list/native/states.dark.png",
+          "light": "examples/list/native/states.light.png"
+        }
+      }
+    ]
+  },
+  "files": [],
+  "dependencies": [],
+  "registryDependencies": [],
+  "demo": null,
+  "props": []
+}

package/registry/loader.json

@@ -250,7 +250,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  | \"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  | \"checkbox\"\n  | \"chip\"\n  | \"chip-link\"\n  | \"choice-grid\"\n  | \"cn\"\n  | \"code-block\"\n  | \"combobox\"\n  | \"command\"\n  | \"confirm-button\"\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-layout\"\n  | \"dropdown-menu\"\n  | \"empty-state\"\n  | \"field\"\n  | \"file-upload\"\n  | \"filter-bar\"\n  | \"glow-card\"\n  | \"goal-gauge\"\n  | \"image-cropper\"\n  | \"iso\"\n  | \"kbd\"\n  | \"landscape\"\n  | \"link-card\"\n  | \"loader\"\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  | \"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  | \"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 templates.\n */\nexport type Category = \"actions\" | \"forms\" | \"navigation\" | \"overlays\" | \"feedback\" | \"data-display\" | \"media\" | \"blocks\" | \"layouts\" | \"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"
+      "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  | \"list\"\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  | \"virtual\";\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": [

package/registry/longform-page.json

@@ -0,0 +1,213 @@
+{
+  "name": "longform-page",
+  "type": "primitive",
+  "title": "Longform page",
+  "summary": "A long read — a story, an essay, a case: numbered chapters in a reading column, pull quotes in the margin, figures that break out.",
+  "description": "A long read — a story, an essay, a case: numbered chapters in a reading column, pull quotes in the margin, figures that break out.",
+  "status": "beta",
+  "category": "templates",
+  "platforms": "web",
+  "whenToUse": [
+    "A company's story, a case study, an essay.",
+    "Any text read from the top, chapter by chapter."
+  ],
+  "whenNotToUse": [
+    {
+      "when": "For a documentation article.",
+      "use": "docs-article-page"
+    },
+    {
+      "when": "For a policy.",
+      "use": "legal-page"
+    }
+  ],
+  "bestPractices": [
+    "Chapters of three to six paragraphs; one pull quote at most each.",
+    "Figures carry a promise (a bird's quote, a schema), never decoration.",
+    "Words and content arrive as props; the motion is the platform's (`[data-reveal]`, still under reduced motion)."
+  ],
+  "accessibility": {
+    "keyboard": [],
+    "notes": [
+      "Each chapter is a `section` named by its `h2`; the numbers are decorative.",
+      "The pull quote repeats the text: it adds nothing a reader would miss."
+    ]
+  },
+  "related": [
+    "mascot-quote",
+    "page-hero",
+    "legal-page"
+  ],
+  "web": {
+    "entry": "@krizaka/ui/longform-page",
+    "import": "import { LongformPage } from \"@krizaka/ui/longform-page\";",
+    "props": [
+      {
+        "component": "LongformPage",
+        "description": "A long read: hero, then numbered chapters with pull quotes in the margin and figures that break out.",
+        "props": [
+          {
+            "name": "chapters",
+            "type": "readonly LongformChapter[]",
+            "default": null,
+            "description": "The chapters, in order.",
+            "required": true
+          },
+          {
+            "name": "title",
+            "type": "ReactNode",
+            "default": null,
+            "description": "The page's `h1`.",
+            "required": true
+          },
+          {
+            "name": "aside",
+            "type": "ReactNode",
+            "default": null,
+            "description": "Beside the hero: the page's bird, an illustration.",
+            "required": false
+          },
+          {
+            "name": "back",
+            "type": "{ href: string; label: string; }",
+            "default": null,
+            "description": "The way back.",
+            "required": false
+          },
+          {
+            "name": "brand",
+            "type": "string",
+            "default": null,
+            "description": "The brand the page wears (`.brand-<id>`).",
+            "required": false
+          },
+          {
+            "name": "eyebrow",
+            "type": "ReactNode",
+            "default": null,
+            "description": "A mono line above the title.",
+            "required": false
+          },
+          {
+            "name": "lead",
+            "type": "ReactNode",
+            "default": null,
+            "description": "The standfirst.",
+            "required": false
+          },
+          {
+            "name": "linkAs",
+            "type": "LinkComponent",
+            "default": null,
+            "description": "The app's link component (Next's `Link`).",
+            "required": false
+          }
+        ]
+      }
+    ],
+    "examples": [
+      {
+        "name": "story",
+        "title": "Our story",
+        "description": "Krizaka's story in chapters, a pull quote and the flamingo's rule.",
+        "template": true,
+        "path": "examples/longform-page/story.tsx",
+        "module": "@krizaka/ui/registry/examples/longform-page/story",
+        "code": "import { LongformPage } from \"@krizaka/ui/longform-page\";\nimport { MascotQuote } from \"@krizaka/ui/mascot-quote\";\nimport { Mascot } from \"@krizaka/ui/mascots\";\n\n// TEMPLATE — a long read (Krizaka's story): numbered chapters in a reading column, a sentence pulled into the margin,\n// a bird's quote breaking out under the text. Editorial, not cards; one column on a phone.\nexport default function LongformPageStory() {\n  return (\n    <LongformPage\n      eyebrow=\"Our story\"\n      title=\"Why a studio in Montréal builds its own AI\"\n      lead=\"Three products, one rule: what is yours stays yours.\"\n      aside={<Mascot bird=\"owl\" mood=\"welcome\" size={112} />}\n      chapters={[\n        {\n          id: \"start\",\n          title: \"It started with a lease\",\n          pull: \"The prompt crossed the ocean before the answer came back.\",\n          children: (\n            <>\n              <p>A notary asked a chatbot to summarise a lease. The answer was good; the lease was now on someone else's server.</p>\n              <p>We built Orazaka so that question never has to leave the office.</p>\n            </>\n          ),\n        },\n        {\n          id: \"creators\",\n          title: \"Then came the creators\",\n          children: <p>Orochia pays creators 90 % of what their fans spend, every Monday — no algorithm in between.</p>,\n          figure: <MascotQuote bird=\"flamingo\" label=\"The flamingo's rule\">Whoever does the work gets paid first.</MascotQuote>,\n        },\n      ]}\n    />\n  );\n}\n"
+      }
+    ]
+  },
+  "native": null,
+  "files": [
+    {
+      "path": "longform-page/index.ts",
+      "content": "/** @krizaka/ui/longform-page — `LongformPage`: A long read: numbered chapters, pull quotes in the margin, figures that break out. Server-safe; a page template. */\nexport { type LongformChapter,LongformPage, type LongformPageProps } from \"./longform-page\";\n"
+    },
+    {
+      "path": "longform-page/longform-page.tsx",
+      "content": "// Server-safe. A long read — a story, an essay, a case (blocks.css `.kz-tpl-chapters`): the hero, then chapters, each\n// with its big outlined number, its title, its text in a reading column, a pull quote in the margin and a figure that\n// breaks out to the margin's width; the contents as chips on a phone. Editorial, not cards.\nimport { Page } from \"@krizaka/ui/page\";\nimport type { LinkComponent } from \"@krizaka/ui/page-hero\";\nimport { PageHero } from \"@krizaka/ui/page-hero\";\nimport type * as React from \"react\";\n\nimport { cn } from \"../cn\";\n\nexport interface LongformChapter {\n  /** The chapter's anchor. */\n  id: string;\n  /** Its title. */\n  title: React.ReactNode;\n  /** Its text (paragraphs). */\n  children: React.ReactNode;\n  /** A sentence pulled into the margin. */\n  pull?: React.ReactNode;\n  /** A figure under the text (an image, a schema, a quote by a bird). */\n  figure?: React.ReactNode;\n}\n\nexport type LongformPageProps = Omit<React.HTMLAttributes<HTMLElement>, \"title\"> & {\n  /** The brand the page wears (`.brand-<id>`). */\n  brand?: string;\n  /** The way back. */\n  back?: { href: string; label: string };\n  /** A mono line above the title. */\n  eyebrow?: React.ReactNode;\n  /** The page's `h1`. */\n  title: React.ReactNode;\n  /** The standfirst. */\n  lead?: React.ReactNode;\n  /** Beside the hero: the page's bird, an illustration. */\n  aside?: React.ReactNode;\n  /** The chapters, in order. */\n  chapters: readonly LongformChapter[];\n  /** After the chapters: the end note, a call. */\n  children?: React.ReactNode;\n  /** The app's link component (Next's `Link`). */\n  linkAs?: LinkComponent;\n};\n\n/** A long read: hero, then numbered chapters with pull quotes in the margin and figures that break out. */\nexport function LongformPage({ brand, back, eyebrow, title, lead, aside, chapters, linkAs, className, children, ...props }: LongformPageProps) {\n  return (\n    <div className={cn(brand && \"brand-\" + brand, className)} {...props}>\n      <PageHero back={back} linkAs={linkAs} eyebrow={eyebrow} title={title} lead={lead} aside={aside} />\n      <Page className=\"kz-tpl-longform\">\n        <div className=\"kz-tpl-chapters\">\n          {chapters.map((c, i) => (\n            <section key={c.id} className=\"kz-tpl-chapter\" aria-labelledby={c.id} data-reveal=\"\">\n              <span className=\"kz-tpl-chapter-n\" aria-hidden>\n                {String(i + 1).padStart(2, \"0\")}\n              </span>\n              <div className=\"kz-tpl-chapter-body\">\n                <h2 id={c.id}>{c.title}</h2>\n                {c.children}\n              </div>\n              {c.pull && (\n                <aside className=\"kz-tpl-chapter-aside\">\n                  <p className=\"kz-tpl-pull\">{c.pull}</p>\n                </aside>\n              )}\n              {c.figure && <figure className=\"kz-tpl-chapter-figure\">{c.figure}</figure>}\n            </section>\n          ))}\n        </div>\n        {children}\n      </Page>\n    </div>\n  );\n}\n"
+    },
+    {
+      "path": "longform-page/meta.ts",
+      "content": "import type { ComponentMeta } from \"../meta\";\n\nexport const meta = {\n  title: \"Longform page\",\n  summary: \"A long read — a story, an essay, a case: numbered chapters in a reading column, pull quotes in the margin, figures that break out.\",\n  status: \"beta\",\n  category: \"templates\",\n  platforms: \"web\",\n  whenToUse: [\"A company's story, a case study, an essay.\", \"Any text read from the top, chapter by chapter.\"],\n  whenNotToUse: [\n    { when: \"For a documentation article.\", use: \"docs-article-page\" },\n    { when: \"For a policy.\", use: \"legal-page\" },\n  ],\n  bestPractices: [\"Chapters of three to six paragraphs; one pull quote at most each.\", \"Figures carry a promise (a bird's quote, a schema), never decoration.\", \"Words and content arrive as props; the motion is the platform's (`[data-reveal]`, still under reduced motion).\"],\n  accessibility: {\n    keyboard: [],\n    notes: [\"Each chapter is a `section` named by its `h2`; the numbers are decorative.\", \"The pull quote repeats the text: it adds nothing a reader would miss.\"],\n  },\n  related: [\"mascot-quote\", \"page-hero\", \"legal-page\"],\n  web: {\n    imports: [\"LongformPage\"],\n    examples: [\n      { name: \"story\", title: \"Our story\", description: \"Krizaka's story in chapters, a pull quote and the flamingo's rule.\", 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  | \"list\"\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  | \"virtual\";\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": [
+    "cn",
+    "page",
+    "page-hero"
+  ],
+  "demo": {
+    "path": "examples/longform-page/story.tsx",
+    "content": "import { LongformPage } from \"@krizaka/ui/longform-page\";\nimport { MascotQuote } from \"@krizaka/ui/mascot-quote\";\nimport { Mascot } from \"@krizaka/ui/mascots\";\n\n// TEMPLATE — a long read (Krizaka's story): numbered chapters in a reading column, a sentence pulled into the margin,\n// a bird's quote breaking out under the text. Editorial, not cards; one column on a phone.\nexport default function LongformPageStory() {\n  return (\n    <LongformPage\n      eyebrow=\"Our story\"\n      title=\"Why a studio in Montréal builds its own AI\"\n      lead=\"Three products, one rule: what is yours stays yours.\"\n      aside={<Mascot bird=\"owl\" mood=\"welcome\" size={112} />}\n      chapters={[\n        {\n          id: \"start\",\n          title: \"It started with a lease\",\n          pull: \"The prompt crossed the ocean before the answer came back.\",\n          children: (\n            <>\n              <p>A notary asked a chatbot to summarise a lease. The answer was good; the lease was now on someone else's server.</p>\n              <p>We built Orazaka so that question never has to leave the office.</p>\n            </>\n          ),\n        },\n        {\n          id: \"creators\",\n          title: \"Then came the creators\",\n          children: <p>Orochia pays creators 90 % of what their fans spend, every Monday — no algorithm in between.</p>,\n          figure: <MascotQuote bird=\"flamingo\" label=\"The flamingo's rule\">Whoever does the work gets paid first.</MascotQuote>,\n        },\n      ]}\n    />\n  );\n}\n"
+  },
+  "props": [
+    {
+      "component": "LongformPage",
+      "description": "A long read: hero, then numbered chapters with pull quotes in the margin and figures that break out.",
+      "props": [
+        {
+          "name": "chapters",
+          "type": "readonly LongformChapter[]",
+          "default": null,
+          "description": "The chapters, in order.",
+          "required": true
+        },
+        {
+          "name": "title",
+          "type": "ReactNode",
+          "default": null,
+          "description": "The page's `h1`.",
+          "required": true
+        },
+        {
+          "name": "aside",
+          "type": "ReactNode",
+          "default": null,
+          "description": "Beside the hero: the page's bird, an illustration.",
+          "required": false
+        },
+        {
+          "name": "back",
+          "type": "{ href: string; label: string; }",
+          "default": null,
+          "description": "The way back.",
+          "required": false
+        },
+        {
+          "name": "brand",
+          "type": "string",
+          "default": null,
+          "description": "The brand the page wears (`.brand-<id>`).",
+          "required": false
+        },
+        {
+          "name": "eyebrow",
+          "type": "ReactNode",
+          "default": null,
+          "description": "A mono line above the title.",
+          "required": false
+        },
+        {
+          "name": "lead",
+          "type": "ReactNode",
+          "default": null,
+          "description": "The standfirst.",
+          "required": false
+        },
+        {
+          "name": "linkAs",
+          "type": "LinkComponent",
+          "default": null,
+          "description": "The app's link component (Next's `Link`).",
+          "required": false
+        }
+      ]
+    }
+  ]
+}

package/registry/marketing-layout.json

@@ -129,7 +129,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  | \"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  | \"checkbox\"\n  | \"chip\"\n  | \"chip-link\"\n  | \"choice-grid\"\n  | \"cn\"\n  | \"code-block\"\n  | \"combobox\"\n  | \"command\"\n  | \"confirm-button\"\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-layout\"\n  | \"dropdown-menu\"\n  | \"empty-state\"\n  | \"field\"\n  | \"file-upload\"\n  | \"filter-bar\"\n  | \"glow-card\"\n  | \"goal-gauge\"\n  | \"image-cropper\"\n  | \"iso\"\n  | \"kbd\"\n  | \"landscape\"\n  | \"link-card\"\n  | \"loader\"\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  | \"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  | \"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 templates.\n */\nexport type Category = \"actions\" | \"forms\" | \"navigation\" | \"overlays\" | \"feedback\" | \"data-display\" | \"media\" | \"blocks\" | \"layouts\" | \"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"
+      "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  | \"list\"\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  | \"virtual\";\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": [