@krizaka/ui 2.2.0 → 2.4.0

package/registry/pagination.json

@@ -0,0 +1,475 @@
+{
+  "name": "pagination",
+  "type": "primitive",
+  "title": "Pagination",
+  "summary": "Moves through a long list page by page: numbers with ellipses that fold into “Page 3 of 12” on a phone, or previous / next on a cursor.",
+  "description": "Moves through a long list page by page: numbers with ellipses that fold into “Page 3 of 12” on a phone, or previous / next on a cursor.",
+  "status": "beta",
+  "category": "navigation",
+  "platforms": "both",
+  "whenToUse": [
+    "Under a table or a grid of results the person reads page by page: an admin list, search results, invoices.",
+    "With `getHref` when the page belongs in the address — a search engine and a shared link reach page 4.",
+    "In cursor mode (`hasPrevious` / `hasNext`) when the API only knows the next page (a cursor, a `nextToken`)."
+  ],
+  "whenNotToUse": [
+    {
+      "when": "For a feed people scroll without a goal: load more at the end of the list instead (an infinite list)."
+    },
+    {
+      "when": "To switch between views of the same page: tabs.",
+      "use": "tabs"
+    }
+  ],
+  "bestPractices": [
+    "Say where the list stands with `status` (“61–80 of 392 videos”): it is read next to the controls.",
+    "Prefer links (`getHref`) for public lists; buttons (`onPageChange`) for a list inside an app screen.",
+    "Keep `siblings` at 1 on a list people browse; the container folds the numbers by itself under 28rem.",
+    "Disable the controls (`disabled`) while the next page loads, and move the focus to the top of the list after."
+  ],
+  "accessibility": {
+    "keyboard": [
+      {
+        "keys": "Tab",
+        "action": "Reaches the previous control, each page, then the next control."
+      }
+    ],
+    "notes": [
+      "A `nav` named by `labels.nav`; the current page carries `aria-current=\"page\"`.",
+      "Each number is named “Page 4” (`labels.page`); the ellipses are hidden from assistive technology.",
+      "A disabled link is `aria-disabled` with no `href`: it is skipped by the Tab key and read as unavailable."
+    ]
+  },
+  "related": [
+    "data-table",
+    "filter-bar",
+    "search-field"
+  ],
+  "web": {
+    "entry": "@krizaka/ui/pagination",
+    "import": "import { Pagination, pageRange } from \"@krizaka/ui/pagination\";",
+    "props": [
+      {
+        "component": "Pagination",
+        "description": "Moves through a long list: page numbers (folded on a narrow screen) or previous / next on a cursor.",
+        "props": [
+          {
+            "name": "boundaries",
+            "type": "number",
+            "default": "1",
+            "description": "Pages always shown at each end. Default 1.",
+            "required": false
+          },
+          {
+            "name": "disabled",
+            "type": "boolean",
+            "default": null,
+            "description": "Disables every control (a page is loading).",
+            "required": false
+          },
+          {
+            "name": "getHref",
+            "type": "((page: number) => string)",
+            "default": null,
+            "description": "The address of a page: the pages become links (crawlable, shareable, the state in the URL).",
+            "required": false
+          },
+          {
+            "name": "hasNext",
+            "type": "boolean",
+            "default": null,
+            "description": "Cursor mode: whether there is a next page.",
+            "required": false
+          },
+          {
+            "name": "hasPrevious",
+            "type": "boolean",
+            "default": null,
+            "description": "Cursor mode: whether there is a previous page.",
+            "required": false
+          },
+          {
+            "name": "labels",
+            "type": "Partial<PaginationLabels>",
+            "default": null,
+            "description": "The words, passed translated; English by default.",
+            "required": false
+          },
+          {
+            "name": "onNext",
+            "type": "(() => void)",
+            "default": null,
+            "description": "Cursor mode: called by the next control.",
+            "required": false
+          },
+          {
+            "name": "onPageChange",
+            "type": "((page: number) => void)",
+            "default": null,
+            "description": "Called with the page asked for (buttons). Ignored for the pages `getHref` turns into links.",
+            "required": false
+          },
+          {
+            "name": "onPageSizeChange",
+            "type": "((size: number) => void)",
+            "default": null,
+            "description": "Called with the size chosen.",
+            "required": false
+          },
+          {
+            "name": "onPrevious",
+            "type": "(() => void)",
+            "default": null,
+            "description": "Cursor mode: called by the previous control.",
+            "required": false
+          },
+          {
+            "name": "page",
+            "type": "number",
+            "default": "1",
+            "description": "Pages mode: the current page, from 1.",
+            "required": false
+          },
+          {
+            "name": "pageCount",
+            "type": "number",
+            "default": null,
+            "description": "Pages mode: how many pages there are. Without it, the pagination is in cursor mode.",
+            "required": false
+          },
+          {
+            "name": "pageSize",
+            "type": "number",
+            "default": null,
+            "description": "The page size, with `pageSizeOptions` and `onPageSizeChange`: a select of rows per page.",
+            "required": false
+          },
+          {
+            "name": "pageSizeOptions",
+            "type": "readonly number[]",
+            "default": null,
+            "description": "The sizes offered (`[10, 20, 50]`).",
+            "required": false
+          },
+          {
+            "name": "siblings",
+            "type": "number",
+            "default": "1",
+            "description": "Pages shown on each side of the current one. Default 1.",
+            "required": false
+          },
+          {
+            "name": "status",
+            "type": "ReactNode",
+            "default": null,
+            "description": "A text beside the controls, read as is: \"41–60 of 1,284\", \"12 results\".",
+            "required": false
+          }
+        ]
+      }
+    ],
+    "examples": [
+      {
+        "name": "results",
+        "title": "Search results",
+        "description": "Page numbers with ellipses and a status: the explore page of a video platform.",
+        "path": "examples/pagination/results.tsx",
+        "module": "@krizaka/ui/registry/examples/pagination/results",
+        "code": "\"use client\";\n\nimport { Pagination } from \"@krizaka/ui/pagination\";\nimport * as React from \"react\";\n\n// The explore page of a video platform: 392 results, 20 per page.\nexport default function PaginationResults() {\n  const [page, setPage] = React.useState(4);\n  const first = (page - 1) * 20 + 1;\n  return (\n    <Pagination\n      page={page}\n      pageCount={20}\n      onPageChange={setPage}\n      status={`${first}–${Math.min(first + 19, 392)} of 392 videos`}\n      labels={{ nav: \"Pages of results\" }}\n    />\n  );\n}\n"
+      },
+      {
+        "name": "table-footer",
+        "title": "Table footer",
+        "description": "Under an admin table: the rows per page, the range shown, and the pages.",
+        "path": "examples/pagination/table-footer.tsx",
+        "module": "@krizaka/ui/registry/examples/pagination/table-footer",
+        "code": "\"use client\";\n\nimport { Pagination } from \"@krizaka/ui/pagination\";\nimport * as React from \"react\";\n\n// Under an admin table: rows per page, the range shown, the pages.\nexport default function PaginationTableFooter() {\n  const [page, setPage] = React.useState(1);\n  const [size, setSize] = React.useState(20);\n  const total = 1284;\n  const count = Math.ceil(total / size);\n  const first = (page - 1) * size + 1;\n  return (\n    <Pagination\n      page={page}\n      pageCount={count}\n      onPageChange={setPage}\n      pageSize={size}\n      pageSizeOptions={[10, 20, 50]}\n      onPageSizeChange={(next) => {\n        setSize(next);\n        setPage(1);\n      }}\n      status={`${first.toLocaleString(\"en\")}–${Math.min(first + size - 1, total).toLocaleString(\"en\")} of ${total.toLocaleString(\"en\")}`}\n    />\n  );\n}\n"
+      },
+      {
+        "name": "cursor",
+        "title": "Cursor",
+        "description": "An API that only knows the next and previous pages: two buttons and the range.",
+        "path": "examples/pagination/cursor.tsx",
+        "module": "@krizaka/ui/registry/examples/pagination/cursor",
+        "code": "\"use client\";\n\nimport { Pagination } from \"@krizaka/ui/pagination\";\nimport * as React from \"react\";\n\n// An API that answers with a `nextCursor`: no total, previous and next only.\nexport default function PaginationCursor() {\n  const [pages, setPages] = React.useState([\"start\"]);\n  const index = pages.length - 1;\n  return (\n    <Pagination\n      hasPrevious={index > 0}\n      hasNext\n      onPrevious={() => setPages((p) => p.slice(0, -1))}\n      onNext={() => setPages((p) => [...p, `cursor-${p.length}`])}\n      status={`Jobs ${index * 25 + 1}–${index * 25 + 25}`}\n      labels={{ previous: \"Newer jobs\", next: \"Older jobs\" }}\n    />\n  );\n}\n"
+      },
+      {
+        "name": "links",
+        "title": "Links in the address",
+        "description": "`getHref`: every page is a link — crawlable, shareable, the state in the URL.",
+        "path": "examples/pagination/links.tsx",
+        "module": "@krizaka/ui/registry/examples/pagination/links",
+        "code": "import { Pagination } from \"@krizaka/ui/pagination\";\n\n// Server-rendered: every page is a link, the page lives in the address (`?q=sunset&page=7`).\nexport default function PaginationLinks() {\n  return <Pagination page={7} pageCount={42} getHref={(page) => `/explore?q=sunset&page=${page}`} siblings={2} />;\n}\n"
+      }
+    ]
+  },
+  "native": {
+    "entry": "@krizaka/ui/native",
+    "import": "import { Pagination } from \"@krizaka/ui/native\";",
+    "differences": [
+      "Folded only: previous / next and “Page 3 of 12”, the form a thumb reaches; no numbers, no links, no page size.",
+      "`labels` is required (`previous`, `next`, `compact`)."
+    ],
+    "props": [
+      {
+        "component": "Pagination",
+        "description": "Previous / next with where the list stands (\"Page 3 of 12\"), or the two buttons of a cursor — the web\n`Pagination` folded, the form a phone's thumb reaches. On a feed, prefer loading more at the end of the list.",
+        "props": [
+          {
+            "name": "labels",
+            "type": "PaginationLabels",
+            "default": null,
+            "description": "The words, passed translated.",
+            "required": true
+          },
+          {
+            "name": "disabled",
+            "type": "boolean",
+            "default": null,
+            "description": "Disables both buttons (a page is loading).",
+            "required": false
+          },
+          {
+            "name": "hasNext",
+            "type": "boolean",
+            "default": null,
+            "description": "Cursor mode: whether there is a next page.",
+            "required": false
+          },
+          {
+            "name": "hasPrevious",
+            "type": "boolean",
+            "default": null,
+            "description": "Cursor mode: whether there is a previous page.",
+            "required": false
+          },
+          {
+            "name": "onNext",
+            "type": "(() => void)",
+            "default": null,
+            "description": "Cursor mode: called by the next button.",
+            "required": false
+          },
+          {
+            "name": "onPageChange",
+            "type": "((page: number) => void)",
+            "default": null,
+            "description": "Pages mode: called with the page asked for.",
+            "required": false
+          },
+          {
+            "name": "onPrevious",
+            "type": "(() => void)",
+            "default": null,
+            "description": "Cursor mode: called by the previous button.",
+            "required": false
+          },
+          {
+            "name": "page",
+            "type": "number",
+            "default": "1",
+            "description": "Pages mode: the current page, from 1.",
+            "required": false
+          },
+          {
+            "name": "pageCount",
+            "type": "number",
+            "default": null,
+            "description": "Pages mode: how many pages. Without it, the pagination is in cursor mode.",
+            "required": false
+          },
+          {
+            "name": "status",
+            "type": "string",
+            "default": null,
+            "description": "A text between the buttons in cursor mode (\"41–60\"), or instead of \"Page 3 of 12\".",
+            "required": false
+          },
+          {
+            "name": "style",
+            "type": "StyleProp<ViewStyle>",
+            "default": null,
+            "description": "Styles merged last.",
+            "required": false
+          }
+        ]
+      }
+    ],
+    "examples": [
+      {
+        "name": "pages",
+        "title": "Pages",
+        "description": "Previous / next around “Page 3 of 12”.",
+        "path": "examples/pagination/native/pages.tsx",
+        "module": "@krizaka/ui/registry/examples/pagination/native/pages",
+        "code": "import { Pagination } from \"@krizaka/ui/native\";\nimport * as React from \"react\";\n\nexport default function NativePaginationPages() {\n  const [page, setPage] = React.useState(3);\n  return (\n    <Pagination\n      page={page}\n      pageCount={12}\n      onPageChange={setPage}\n      labels={{ previous: \"Previous page\", next: \"Next page\", compact: (p, count) => `Page ${p} of ${count}` }}\n    />\n  );\n}\n",
+        "screenshots": {
+          "dark": "examples/pagination/native/pages.dark.png",
+          "light": "examples/pagination/native/pages.light.png"
+        }
+      },
+      {
+        "name": "cursor",
+        "title": "Cursor",
+        "description": "Previous / next on a cursor, with the range in between.",
+        "path": "examples/pagination/native/cursor.tsx",
+        "module": "@krizaka/ui/registry/examples/pagination/native/cursor",
+        "code": "import { Pagination } from \"@krizaka/ui/native\";\n\n// A cursor: the range in between, no total.\nexport default function NativePaginationCursor() {\n  return (\n    <Pagination\n      hasPrevious\n      hasNext\n      status=\"Payouts 21–40\"\n      labels={{ previous: \"Newer payouts\", next: \"Older payouts\", compact: (p, count) => `${p} / ${count}` }}\n    />\n  );\n}\n",
+        "screenshots": {
+          "dark": "examples/pagination/native/cursor.dark.png",
+          "light": "examples/pagination/native/cursor.light.png"
+        }
+      }
+    ]
+  },
+  "files": [
+    {
+      "path": "glyphs.tsx",
+      "content": "// The small line glyphs the data and media primitives draw (play, volume, search, chevrons…): decorative, 24-unit\n// box, `currentColor`, sized by the caller's class. Shared by the entries that need them; never exported on its own —\n// a product draws its own icons with @krizaka/icons.\nimport type * as React from \"react\";\n\ntype GlyphProps = { className?: string };\n\nfunction Glyph({ className = \"h-4 w-4\", fill, children }: GlyphProps & { fill?: boolean; children: React.ReactNode }) {\n  return (\n    <svg\n      viewBox=\"0 0 24 24\"\n      className={className}\n      fill={fill ? \"currentColor\" : \"none\"}\n      stroke={fill ? \"none\" : \"currentColor\"}\n      strokeWidth=\"2\"\n      strokeLinecap=\"round\"\n      strokeLinejoin=\"round\"\n      aria-hidden\n      focusable=\"false\"\n    >\n      {children}\n    </svg>\n  );\n}\n\nexport const PlayGlyph = (p: GlyphProps) => (\n  <Glyph {...p} fill>\n    <path d=\"M8 5.5v13a1 1 0 0 0 1.5.86l10.4-6.5a1 1 0 0 0 0-1.72L9.5 4.64A1 1 0 0 0 8 5.5Z\" />\n  </Glyph>\n);\nexport const PauseGlyph = (p: GlyphProps) => (\n  <Glyph {...p} fill>\n    <rect x=\"6\" y=\"5\" width=\"4\" height=\"14\" rx=\"1\" />\n    <rect x=\"14\" y=\"5\" width=\"4\" height=\"14\" rx=\"1\" />\n  </Glyph>\n);\nexport const VolumeGlyph = ({ muted, ...p }: GlyphProps & { muted?: boolean }) => (\n  <Glyph {...p}>\n    <path d=\"M11 5 6 9H3v6h3l5 4V5Z\" />\n    {muted ? <path d=\"m22 9-6 6m0-6 6 6\" /> : <path d=\"M15.5 8.5a5 5 0 0 1 0 7M18.5 5.5a9 9 0 0 1 0 13\" />}\n  </Glyph>\n);\nexport const FullscreenGlyph = ({ exit, ...p }: GlyphProps & { exit?: boolean }) => (\n  <Glyph {...p}>\n    {exit ? <path d=\"M9 4v5H4m11-5v5h5M9 20v-5H4m11 5v-5h5\" /> : <path d=\"M4 9V4h5m6 0h5v5M4 15v5h5m11-5v5h-5\" />}\n  </Glyph>\n);\nexport const CaptionsGlyph = (p: GlyphProps) => (\n  <Glyph {...p}>\n    <rect x=\"3\" y=\"5\" width=\"18\" height=\"14\" rx=\"2\" />\n    <path d=\"M10 10.5a2 2 0 1 0 0 3M17 10.5a2 2 0 1 0 0 3\" />\n  </Glyph>\n);\nexport const PipGlyph = (p: GlyphProps) => (\n  <Glyph {...p}>\n    <rect x=\"3\" y=\"5\" width=\"18\" height=\"14\" rx=\"2\" />\n    <rect x=\"12\" y=\"12\" width=\"6\" height=\"4\" rx=\"1\" />\n  </Glyph>\n);\nexport const SearchGlyph = (p: GlyphProps) => (\n  <Glyph {...p}>\n    <circle cx=\"11\" cy=\"11\" r=\"7\" />\n    <path d=\"m20 20-3.5-3.5\" />\n  </Glyph>\n);\nexport const CloseGlyph = (p: GlyphProps) => (\n  <Glyph {...p}>\n    <path d=\"M18 6 6 18M6 6l12 12\" />\n  </Glyph>\n);\nexport const ChevronGlyph = ({ direction = \"down\", ...p }: GlyphProps & { direction?: \"left\" | \"right\" | \"up\" | \"down\" }) => (\n  <Glyph {...p}>\n    <path d={{ left: \"m15 6-6 6 6 6\", right: \"m9 6 6 6-6 6\", up: \"m6 15 6-6 6 6\", down: \"m6 9 6 6 6-6\" }[direction]} />\n  </Glyph>\n);\nexport const CheckGlyph = (p: GlyphProps) => (\n  <Glyph {...p}>\n    <path d=\"M20 6 9 17l-5-5\" />\n  </Glyph>\n);\nexport const PlusGlyph = (p: GlyphProps) => (\n  <Glyph {...p}>\n    <path d=\"M12 5v14M5 12h14\" />\n  </Glyph>\n);\nexport const CalendarGlyph = (p: GlyphProps) => (\n  <Glyph {...p}>\n    <rect x=\"3\" y=\"5\" width=\"18\" height=\"16\" rx=\"2\" />\n    <path d=\"M3 10h18M8 3v4M16 3v4\" />\n  </Glyph>\n);\nexport const UploadGlyph = (p: GlyphProps) => (\n  <Glyph {...p}>\n    <path d=\"M12 16V4m0 0L7 9m5-5 5 5\" />\n    <path d=\"M4 16v2a2 2 0 0 0 2 2h12a2 2 0 0 0 2-2v-2\" />\n  </Glyph>\n);\nexport const FileGlyph = (p: GlyphProps) => (\n  <Glyph {...p}>\n    <path d=\"M14 3H7a2 2 0 0 0-2 2v14a2 2 0 0 0 2 2h10a2 2 0 0 0 2-2V8l-5-5Z\" />\n    <path d=\"M14 3v5h5\" />\n  </Glyph>\n);\nexport const CameraGlyph = (p: GlyphProps) => (\n  <Glyph {...p}>\n    <path d=\"M4 8h3l2-3h6l2 3h3a1 1 0 0 1 1 1v10a1 1 0 0 1-1 1H4a1 1 0 0 1-1-1V9a1 1 0 0 1 1-1Z\" />\n    <circle cx=\"12\" cy=\"13.5\" r=\"3.5\" />\n  </Glyph>\n);\nexport const FlipGlyph = (p: GlyphProps) => (\n  <Glyph {...p}>\n    <path d=\"M4 12a8 8 0 0 1 14-5.3M20 12a8 8 0 0 1-14 5.3\" />\n    <path d=\"M18 3v4h-4M6 21v-4h4\" />\n  </Glyph>\n);\nexport const RetryGlyph = (p: GlyphProps) => (\n  <Glyph {...p}>\n    <path d=\"M4 12a8 8 0 1 0 2.3-5.7L4 8.5\" />\n    <path d=\"M4 4v4.5h4.5\" />\n  </Glyph>\n);\nexport const SortGlyph = ({ direction, ...p }: GlyphProps & { direction?: \"ascending\" | \"descending\" }) => (\n  <Glyph {...p}>\n    {direction === \"ascending\" ? <path d=\"m7 14 5-5 5 5\" /> : direction === \"descending\" ? <path d=\"m7 10 5 5 5-5\" /> : <path d=\"m8 9 4-4 4 4M8 15l4 4 4-4\" />}\n  </Glyph>\n);\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  | \"alert\"\n  | \"audio-player\"\n  | \"avatar\"\n  | \"badge\"\n  | \"button\"\n  | \"card\"\n  | \"checkbox\"\n  | \"chip\"\n  | \"chip-link\"\n  | \"cn\"\n  | \"combobox\"\n  | \"command\"\n  | \"confirm-button\"\n  | \"countdown\"\n  | \"data-table\"\n  | \"date-picker\"\n  | \"dialog\"\n  | \"dropdown-menu\"\n  | \"empty-state\"\n  | \"field\"\n  | \"file-upload\"\n  | \"filter-bar\"\n  | \"glow-card\"\n  | \"image-cropper\"\n  | \"iso\"\n  | \"kbd\"\n  | \"loader\"\n  | \"marquee\"\n  | \"mascots\"\n  | \"media-capture\"\n  | \"meter\"\n  | \"nav-bar\"\n  | \"number-ticker\"\n  | \"page-header\"\n  | \"pagination\"\n  | \"popover\"\n  | \"progress\"\n  | \"radio-group\"\n  | \"search-field\"\n  | \"section-backdrop\"\n  | \"segmented\"\n  | \"separator\"\n  | \"skeleton\"\n  | \"slider\"\n  | \"slot\"\n  | \"spinner\"\n  | \"stat\"\n  | \"stepper\"\n  | \"switch\"\n  | \"tabs\"\n  | \"tag-input\"\n  | \"theme\"\n  | \"toast\"\n  | \"tooltip\"\n  | \"txt\"\n  | \"video-player\"\n  | \"video-trimmer\";\n\n/** Where a component exists: `@krizaka/ui/<name>` (web), `@krizaka/ui/native` (React Native), or both. */\nexport type Platform = \"web\" | \"native\" | \"both\";\n\n/** `stable`: its API only changes in a major. `beta`: it may still change in a minor. */\nexport type Status = \"stable\" | \"beta\";\n\n/** The group of the catalogue. `media`: video, sound, camera, files, cropping. */\nexport type Category = \"actions\" | \"forms\" | \"navigation\" | \"overlays\" | \"feedback\" | \"data-display\" | \"media\" | \"layout\" | \"foundations\";\n\n/**\n * A named example: the file `registry/examples/<component>/<name>.tsx` (web) or\n * `registry/examples/<component>/native/<name>.tsx` (React Native) — at most 40 lines, imported by the stories and\n * shown (live, with its code) by the documentation.\n */\nexport interface Example {\n  /** The file name, kebab-case (`primary`, `icon-button`). */\n  readonly name: string;\n  /** A short title (`Primary`, `Icon button`). */\n  readonly title: string;\n  /** One or two sentences: when this variant is the right one. */\n  readonly description: string;\n}\n\n/** One platform's side of a component. */\nexport interface PlatformDocs {\n  /** The names to import (`[\"Button\", \"IconButton\"]`): from `@krizaka/ui/<name>` on the web, `@krizaka/ui/native` in React Native. */\n  readonly imports: readonly string[];\n  /** The examples, in reading order; the first one is the component's preview. */\n  readonly examples: readonly Example[];\n}\n\n/** The React Native side: the same concept, and what differs from the web API. */\nexport interface NativeDocs extends PlatformDocs {\n  /**\n   * The entry to import from when it is not `@krizaka/ui/native`: a component that needs an Expo module (an optional\n   * peer) has its own, `@krizaka/ui/native/<name>`, so an app that does not use it never installs the module.\n   */\n  readonly entry?: string;\n  /** What differs from the web API (`label` instead of children…); empty for a native-only component. */\n  readonly differences: readonly string[];\n}\n\nexport interface KeyboardInteraction {\n  /** The keys, as written on a keyboard: `Space`, `Enter`, `Arrow keys`, `Esc`, `Tab`. */\n  readonly keys: string;\n  /** What they do. */\n  readonly action: string;\n}\n\nexport interface ComponentMeta {\n  /** The display name: `Button`, `Dropdown menu`. */\n  readonly title: string;\n  /** One sentence: what it is. */\n  readonly summary: string;\n  readonly status: Status;\n  readonly category: Category;\n  /** Must match the sides below: `both` ⇔ `web` and `native`. */\n  readonly platforms: Platform;\n  /** When to reach for it: concrete situations, one per item. */\n  readonly whenToUse: readonly string[];\n  /** When not to — and what to use instead (`use`), when another component is the answer. */\n  readonly whenNotToUse: readonly { readonly when: string; readonly use?: ComponentName }[];\n  /** How to use it well: wording, placement, composition. */\n  readonly bestPractices: readonly string[];\n  readonly accessibility: {\n    /** The keyboard, when it does more than Tab and Enter. */\n    readonly keyboard: readonly KeyboardInteraction[];\n    /** Roles, names and announcements: what the component does, what the app must provide. */\n    readonly notes: readonly string[];\n  };\n  /** The components a reader of this page should know about. */\n  readonly related: readonly ComponentName[];\n  readonly web?: PlatformDocs;\n  readonly native?: NativeDocs;\n}\n"
+    },
+    {
+      "path": "pagination/index.ts",
+      "content": "/** @krizaka/ui/pagination — `Pagination` (pages or cursor, folded on a narrow screen), `pageRange`, `pagination` (the slots). Server-safe. */\nexport { pageRange,Pagination, pagination, type PaginationLabels, paginationLabels, type PaginationProps } from \"./pagination\";\n"
+    },
+    {
+      "path": "pagination/meta.ts",
+      "content": "import type { ComponentMeta } from \"../meta\";\n\nexport const meta = {\n  title: \"Pagination\",\n  summary: \"Moves through a long list page by page: numbers with ellipses that fold into “Page 3 of 12” on a phone, or previous / next on a cursor.\",\n  status: \"beta\",\n  category: \"navigation\",\n  platforms: \"both\",\n  whenToUse: [\n    \"Under a table or a grid of results the person reads page by page: an admin list, search results, invoices.\",\n    \"With `getHref` when the page belongs in the address — a search engine and a shared link reach page 4.\",\n    \"In cursor mode (`hasPrevious` / `hasNext`) when the API only knows the next page (a cursor, a `nextToken`).\",\n  ],\n  whenNotToUse: [\n    { when: \"For a feed people scroll without a goal: load more at the end of the list instead (an infinite list).\" },\n    { when: \"To switch between views of the same page: tabs.\", use: \"tabs\" },\n  ],\n  bestPractices: [\n    \"Say where the list stands with `status` (“61–80 of 392 videos”): it is read next to the controls.\",\n    \"Prefer links (`getHref`) for public lists; buttons (`onPageChange`) for a list inside an app screen.\",\n    \"Keep `siblings` at 1 on a list people browse; the container folds the numbers by itself under 28rem.\",\n    \"Disable the controls (`disabled`) while the next page loads, and move the focus to the top of the list after.\",\n  ],\n  accessibility: {\n    keyboard: [{ keys: \"Tab\", action: \"Reaches the previous control, each page, then the next control.\" }],\n    notes: [\n      \"A `nav` named by `labels.nav`; the current page carries `aria-current=\\\"page\\\"`.\",\n      \"Each number is named “Page 4” (`labels.page`); the ellipses are hidden from assistive technology.\",\n      \"A disabled link is `aria-disabled` with no `href`: it is skipped by the Tab key and read as unavailable.\",\n    ],\n  },\n  related: [\"data-table\", \"filter-bar\", \"search-field\"],\n  web: {\n    imports: [\"Pagination\", \"pageRange\"],\n    examples: [\n      { name: \"results\", title: \"Search results\", description: \"Page numbers with ellipses and a status: the explore page of a video platform.\" },\n      { name: \"table-footer\", title: \"Table footer\", description: \"Under an admin table: the rows per page, the range shown, and the pages.\" },\n      { name: \"cursor\", title: \"Cursor\", description: \"An API that only knows the next and previous pages: two buttons and the range.\" },\n      { name: \"links\", title: \"Links in the address\", description: \"`getHref`: every page is a link — crawlable, shareable, the state in the URL.\" },\n    ],\n  },\n  native: {\n    imports: [\"Pagination\"],\n    differences: [\n      \"Folded only: previous / next and “Page 3 of 12”, the form a thumb reaches; no numbers, no links, no page size.\",\n      \"`labels` is required (`previous`, `next`, `compact`).\",\n    ],\n    examples: [\n      { name: \"pages\", title: \"Pages\", description: \"Previous / next around “Page 3 of 12”.\" },\n      { name: \"cursor\", title: \"Cursor\", description: \"Previous / next on a cursor, with the range in between.\" },\n    ],\n  },\n} satisfies ComponentMeta;\n"
+    },
+    {
+      "path": "pagination/pagination.tsx",
+      "content": "// Server-safe: no hook, no context. A `<nav>` named by `labels.nav`; the current page is `aria-current=\"page\"`.\n// Two modes: pages (`page` + `pageCount`: numbers with ellipses, which fold into \"Page 3 of 12\" in a narrow container)\n// and cursor (`hasPrevious` / `hasNext`: an API that only knows the next and previous pages). Links (`getHref`) when\n// the page lives in the address — the right default for a list a search engine or a shared link should reach — or\n// buttons (`onPageChange`).\nimport type * as React from \"react\";\nimport { tv } from \"tailwind-variants\";\n\nimport { ChevronGlyph } from \"../glyphs\";\n\nexport const pagination = tv({\n  slots: {\n    root: \"@container flex w-full flex-wrap items-center justify-between gap-3 text-sm\",\n    list: \"flex items-center gap-1\",\n    pages: \"hidden items-center gap-1 @md:flex\",\n    compact: \"px-2 text-xs font-semibold tabular-nums text-fg-secondary @md:hidden\",\n    item:\n      \"inline-flex h-9 min-w-9 select-none items-center justify-center gap-1.5 rounded-lg px-2.5 text-sm font-semibold tabular-nums text-fg-secondary \" +\n      \"transition-colors hover:bg-surface-2 hover:text-fg focus-visible:outline-hidden focus-visible:ring-2 focus-visible:ring-ring \" +\n      \"aria-[current=page]:bg-accent aria-[current=page]:text-on-accent aria-[current=page]:hover:bg-accent \" +\n      \"aria-disabled:pointer-events-none aria-disabled:opacity-40 disabled:pointer-events-none disabled:opacity-40\",\n    edge: \"border border-border-default bg-surface-1 px-3\",\n    ellipsis: \"inline-flex h-9 min-w-6 items-end justify-center pb-2 text-fg-muted\",\n    status: \"text-xs text-fg-secondary tabular-nums\",\n    size: \"flex items-center gap-2 text-xs text-fg-secondary\",\n    select:\n      \"h-9 rounded-lg border border-border-default bg-surface-2 px-2 text-sm text-fg focus-visible:outline-hidden focus-visible:ring-2 focus-visible:ring-ring\",\n  },\n});\n\nexport type PaginationLabels = {\n  /** The accessible name of the navigation (\"Pagination\", \"Pages of results\"). */\n  nav: string;\n  /** The previous-page control. */\n  previous: string;\n  /** The next-page control. */\n  next: string;\n  /** The accessible name of a page number: `(3) => \"Page 3\"`. */\n  page: (page: number) => string;\n  /** The folded form, in a narrow container: `(3, 12) => \"Page 3 of 12\"`. */\n  compact: (page: number, pageCount: number) => string;\n  /** The label of the page-size select (\"Rows per page\"). */\n  pageSize: string;\n};\n\n/** The English words, for a quick start — pass your translations through `labels`. */\nexport const paginationLabels: PaginationLabels = {\n  nav: \"Pagination\",\n  previous: \"Previous\",\n  next: \"Next\",\n  page: (page) => `Page ${page}`,\n  compact: (page, count) => `Page ${page} of ${count}`,\n  pageSize: \"Rows per page\",\n};\n\n/**\n * The pages to show: the first and last `boundaries`, the current page and its `siblings`, and `\"…\"` where pages are\n * skipped. A gap of a single page shows that page instead of an ellipsis; few pages are all shown.\n */\nexport function pageRange(page: number, pageCount: number, siblings = 1, boundaries = 1): (number | \"…\")[] {\n  // Few enough pages to show them all in the room the folded form takes: no ellipsis.\n  if (pageCount <= 2 * boundaries + 2 * siblings + 3) return Array.from({ length: Math.max(0, pageCount) }, (_, i) => i + 1);\n  const pages = new Set<number>();\n  for (let i = 1; i <= Math.min(boundaries, pageCount); i += 1) pages.add(i);\n  for (let i = Math.max(1, pageCount - boundaries + 1); i <= pageCount; i += 1) pages.add(i);\n  for (let i = Math.max(1, page - siblings); i <= Math.min(pageCount, page + siblings); i += 1) pages.add(i);\n  const sorted = [...pages].sort((a, b) => a - b);\n  const out: (number | \"…\")[] = [];\n  sorted.forEach((n, i) => {\n    const prev = sorted[i - 1];\n    if (prev !== undefined && n - prev === 2) out.push(prev + 1);\n    else if (prev !== undefined && n - prev > 2) out.push(\"…\");\n    out.push(n);\n  });\n  return out;\n}\n\nexport type PaginationProps = Omit<React.ComponentProps<\"nav\">, \"children\"> & {\n  /** Pages mode: the current page, from 1. */\n  page?: number;\n  /** Pages mode: how many pages there are. Without it, the pagination is in cursor mode. */\n  pageCount?: number;\n  /** Called with the page asked for (buttons). Ignored for the pages `getHref` turns into links. */\n  onPageChange?: (page: number) => void;\n  /** The address of a page: the pages become links (crawlable, shareable, the state in the URL). */\n  getHref?: (page: number) => string;\n  /** Cursor mode: whether there is a previous page. */\n  hasPrevious?: boolean;\n  /** Cursor mode: whether there is a next page. */\n  hasNext?: boolean;\n  /** Cursor mode: called by the previous control. */\n  onPrevious?: () => void;\n  /** Cursor mode: called by the next control. */\n  onNext?: () => void;\n  /** Pages shown on each side of the current one. Default 1. */\n  siblings?: number;\n  /** Pages always shown at each end. Default 1. */\n  boundaries?: number;\n  /** A text beside the controls, read as is: \"41–60 of 1,284\", \"12 results\". */\n  status?: React.ReactNode;\n  /** The page size, with `pageSizeOptions` and `onPageSizeChange`: a select of rows per page. */\n  pageSize?: number;\n  /** The sizes offered (`[10, 20, 50]`). */\n  pageSizeOptions?: readonly number[];\n  /** Called with the size chosen. */\n  onPageSizeChange?: (size: number) => void;\n  /** Disables every control (a page is loading). */\n  disabled?: boolean;\n  /** The words, passed translated; English by default. */\n  labels?: Partial<PaginationLabels>;\n};\n\ntype ItemProps = {\n  href?: string;\n  onClick?: () => void;\n  disabled?: boolean;\n  current?: boolean;\n  label: string;\n  className: string;\n  children: React.ReactNode;\n};\n\nfunction Item({ href, onClick, disabled, current, label, className, children }: ItemProps) {\n  const common = { \"aria-label\": label, \"aria-current\": current ? (\"page\" as const) : undefined, className };\n  if (href && !disabled) {\n    return (\n      <a href={href} onClick={onClick} {...common}>\n        {children}\n      </a>\n    );\n  }\n  if (href) {\n    return (\n      <a role=\"link\" aria-disabled {...common}>\n        {children}\n      </a>\n    );\n  }\n  return (\n    <button type=\"button\" onClick={onClick} disabled={disabled} {...common}>\n      {children}\n    </button>\n  );\n}\n\n/** Moves through a long list: page numbers (folded on a narrow screen) or previous / next on a cursor. */\nexport function Pagination({\n  page = 1,\n  pageCount,\n  onPageChange,\n  getHref,\n  hasPrevious,\n  hasNext,\n  onPrevious,\n  onNext,\n  siblings = 1,\n  boundaries = 1,\n  status,\n  pageSize,\n  pageSizeOptions,\n  onPageSizeChange,\n  disabled,\n  labels: given,\n  className,\n  ...props\n}: PaginationProps) {\n  const s = pagination();\n  const labels = { ...paginationLabels, ...given };\n  const paged = pageCount !== undefined;\n  const count = Math.max(1, pageCount ?? 1);\n  const current = Math.min(Math.max(1, page), count);\n  const canPrevious = paged ? current > 1 : Boolean(hasPrevious);\n  const canNext = paged ? current < count : Boolean(hasNext);\n  const go = (target: number) => () => onPageChange?.(target);\n  const href = (target: number) => (paged && getHref ? getHref(target) : undefined);\n\n  return (\n    <nav aria-label={labels.nav} className={s.root({ className })} {...props}>\n      {status !== undefined || pageSizeOptions ? (\n        <div className=\"flex flex-wrap items-center gap-4\">\n          {status !== undefined && <p className={s.status()}>{status}</p>}\n          {pageSizeOptions && pageSize !== undefined && (\n            <label className={s.size()}>\n              {labels.pageSize}\n              <select\n                className={s.select()}\n                value={pageSize}\n                disabled={disabled}\n                onChange={(event) => onPageSizeChange?.(Number(event.target.value))}\n              >\n                {pageSizeOptions.map((size) => (\n                  <option key={size} value={size}>\n                    {size}\n                  </option>\n                ))}\n              </select>\n            </label>\n          )}\n        </div>\n      ) : null}\n      <ul className={s.list()}>\n        <li>\n          <Item\n            href={href(current - 1)}\n            onClick={paged ? go(current - 1) : onPrevious}\n            disabled={disabled || !canPrevious}\n            label={labels.previous}\n            className={s.item({ className: s.edge() })}\n          >\n            <ChevronGlyph direction=\"left\" />\n            <span className=\"hidden @lg:inline\">{labels.previous}</span>\n          </Item>\n        </li>\n        {paged && (\n          <>\n            <li className={s.pages()}>\n              <ul className=\"contents\">\n                {pageRange(current, count, siblings, boundaries).map((n, i) =>\n                  n === \"…\" ? (\n                    <li key={`gap-${i}`} aria-hidden className={s.ellipsis()}>\n                      …\n                    </li>\n                  ) : (\n                    <li key={n}>\n                      <Item href={href(n)} onClick={go(n)} disabled={disabled} current={n === current} label={labels.page(n)} className={s.item()}>\n                        {n}\n                      </Item>\n                    </li>\n                  ),\n                )}\n              </ul>\n            </li>\n            <li className={s.compact()}>\n              {labels.compact(current, count)}\n            </li>\n          </>\n        )}\n        <li>\n          <Item\n            href={href(current + 1)}\n            onClick={paged ? go(current + 1) : onNext}\n            disabled={disabled || !canNext}\n            label={labels.next}\n            className={s.item({ className: s.edge() })}\n          >\n            <span className=\"hidden @lg:inline\">{labels.next}</span>\n            <ChevronGlyph direction=\"right\" />\n          </Item>\n        </li>\n      </ul>\n    </nav>\n  );\n}\n"
+    }
+  ],
+  "dependencies": [
+    "tailwind-variants@^3.3.1"
+  ],
+  "registryDependencies": [],
+  "demo": {
+    "path": "examples/pagination/results.tsx",
+    "content": "\"use client\";\n\nimport { Pagination } from \"@krizaka/ui/pagination\";\nimport * as React from \"react\";\n\n// The explore page of a video platform: 392 results, 20 per page.\nexport default function PaginationResults() {\n  const [page, setPage] = React.useState(4);\n  const first = (page - 1) * 20 + 1;\n  return (\n    <Pagination\n      page={page}\n      pageCount={20}\n      onPageChange={setPage}\n      status={`${first}–${Math.min(first + 19, 392)} of 392 videos`}\n      labels={{ nav: \"Pages of results\" }}\n    />\n  );\n}\n"
+  },
+  "props": [
+    {
+      "component": "Pagination",
+      "description": "Moves through a long list: page numbers (folded on a narrow screen) or previous / next on a cursor.",
+      "props": [
+        {
+          "name": "boundaries",
+          "type": "number",
+          "default": "1",
+          "description": "Pages always shown at each end. Default 1.",
+          "required": false
+        },
+        {
+          "name": "disabled",
+          "type": "boolean",
+          "default": null,
+          "description": "Disables every control (a page is loading).",
+          "required": false
+        },
+        {
+          "name": "getHref",
+          "type": "((page: number) => string)",
+          "default": null,
+          "description": "The address of a page: the pages become links (crawlable, shareable, the state in the URL).",
+          "required": false
+        },
+        {
+          "name": "hasNext",
+          "type": "boolean",
+          "default": null,
+          "description": "Cursor mode: whether there is a next page.",
+          "required": false
+        },
+        {
+          "name": "hasPrevious",
+          "type": "boolean",
+          "default": null,
+          "description": "Cursor mode: whether there is a previous page.",
+          "required": false
+        },
+        {
+          "name": "labels",
+          "type": "Partial<PaginationLabels>",
+          "default": null,
+          "description": "The words, passed translated; English by default.",
+          "required": false
+        },
+        {
+          "name": "onNext",
+          "type": "(() => void)",
+          "default": null,
+          "description": "Cursor mode: called by the next control.",
+          "required": false
+        },
+        {
+          "name": "onPageChange",
+          "type": "((page: number) => void)",
+          "default": null,
+          "description": "Called with the page asked for (buttons). Ignored for the pages `getHref` turns into links.",
+          "required": false
+        },
+        {
+          "name": "onPageSizeChange",
+          "type": "((size: number) => void)",
+          "default": null,
+          "description": "Called with the size chosen.",
+          "required": false
+        },
+        {
+          "name": "onPrevious",
+          "type": "(() => void)",
+          "default": null,
+          "description": "Cursor mode: called by the previous control.",
+          "required": false
+        },
+        {
+          "name": "page",
+          "type": "number",
+          "default": "1",
+          "description": "Pages mode: the current page, from 1.",
+          "required": false
+        },
+        {
+          "name": "pageCount",
+          "type": "number",
+          "default": null,
+          "description": "Pages mode: how many pages there are. Without it, the pagination is in cursor mode.",
+          "required": false
+        },
+        {
+          "name": "pageSize",
+          "type": "number",
+          "default": null,
+          "description": "The page size, with `pageSizeOptions` and `onPageSizeChange`: a select of rows per page.",
+          "required": false
+        },
+        {
+          "name": "pageSizeOptions",
+          "type": "readonly number[]",
+          "default": null,
+          "description": "The sizes offered (`[10, 20, 50]`).",
+          "required": false
+        },
+        {
+          "name": "siblings",
+          "type": "number",
+          "default": "1",
+          "description": "Pages shown on each side of the current one. Default 1.",
+          "required": false
+        },
+        {
+          "name": "status",
+          "type": "ReactNode",
+          "default": null,
+          "description": "A text beside the controls, read as is: \"41–60 of 1,284\", \"12 results\".",
+          "required": false
+        }
+      ]
+    }
+  ]
+}

package/registry/popover.json

@@ -88,7 +88,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  | \"alert\"\n  | \"avatar\"\n  | \"badge\"\n  | \"button\"\n  | \"card\"\n  | \"checkbox\"\n  | \"chip\"\n  | \"cn\"\n  | \"command\"\n  | \"confirm-button\"\n  | \"countdown\"\n  | \"dialog\"\n  | \"dropdown-menu\"\n  | \"empty-state\"\n  | \"field\"\n  | \"kbd\"\n  | \"mascots\"\n  | \"page-header\"\n  | \"popover\"\n  | \"progress\"\n  | \"radio-group\"\n  | \"section-backdrop\"\n  | \"segmented\"\n  | \"separator\"\n  | \"skeleton\"\n  | \"slider\"\n  | \"slot\"\n  | \"spinner\"\n  | \"stat\"\n  | \"switch\"\n  | \"tabs\"\n  | \"theme\"\n  | \"toast\"\n  | \"tooltip\"\n  | \"txt\";\n\n/** Where a component exists: `@krizaka/ui/<name>` (web), `@krizaka/ui/native` (React Native), or both. */\nexport type Platform = \"web\" | \"native\" | \"both\";\n\n/** `stable`: its API only changes in a major. `beta`: it may still change in a minor. */\nexport type Status = \"stable\" | \"beta\";\n\n/** The group of the catalogue. */\nexport type Category = \"actions\" | \"forms\" | \"navigation\" | \"overlays\" | \"feedback\" | \"data-display\" | \"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  /** 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  | \"alert\"\n  | \"audio-player\"\n  | \"avatar\"\n  | \"badge\"\n  | \"button\"\n  | \"card\"\n  | \"checkbox\"\n  | \"chip\"\n  | \"chip-link\"\n  | \"cn\"\n  | \"combobox\"\n  | \"command\"\n  | \"confirm-button\"\n  | \"countdown\"\n  | \"data-table\"\n  | \"date-picker\"\n  | \"dialog\"\n  | \"dropdown-menu\"\n  | \"empty-state\"\n  | \"field\"\n  | \"file-upload\"\n  | \"filter-bar\"\n  | \"glow-card\"\n  | \"image-cropper\"\n  | \"iso\"\n  | \"kbd\"\n  | \"loader\"\n  | \"marquee\"\n  | \"mascots\"\n  | \"media-capture\"\n  | \"meter\"\n  | \"nav-bar\"\n  | \"number-ticker\"\n  | \"page-header\"\n  | \"pagination\"\n  | \"popover\"\n  | \"progress\"\n  | \"radio-group\"\n  | \"search-field\"\n  | \"section-backdrop\"\n  | \"segmented\"\n  | \"separator\"\n  | \"skeleton\"\n  | \"slider\"\n  | \"slot\"\n  | \"spinner\"\n  | \"stat\"\n  | \"stepper\"\n  | \"switch\"\n  | \"tabs\"\n  | \"tag-input\"\n  | \"theme\"\n  | \"toast\"\n  | \"tooltip\"\n  | \"txt\"\n  | \"video-player\"\n  | \"video-trimmer\";\n\n/** Where a component exists: `@krizaka/ui/<name>` (web), `@krizaka/ui/native` (React Native), or both. */\nexport type Platform = \"web\" | \"native\" | \"both\";\n\n/** `stable`: its API only changes in a major. `beta`: it may still change in a minor. */\nexport type Status = \"stable\" | \"beta\";\n\n/** The group of the catalogue. `media`: video, sound, camera, files, cropping. */\nexport type Category = \"actions\" | \"forms\" | \"navigation\" | \"overlays\" | \"feedback\" | \"data-display\" | \"media\" | \"layout\" | \"foundations\";\n\n/**\n * A named example: the file `registry/examples/<component>/<name>.tsx` (web) or\n * `registry/examples/<component>/native/<name>.tsx` (React Native) — at most 40 lines, imported by the stories and\n * shown (live, with its code) by the documentation.\n */\nexport interface Example {\n  /** The file name, kebab-case (`primary`, `icon-button`). */\n  readonly name: string;\n  /** A short title (`Primary`, `Icon button`). */\n  readonly title: string;\n  /** One or two sentences: when this variant is the right one. */\n  readonly description: string;\n}\n\n/** One platform's side of a component. */\nexport interface PlatformDocs {\n  /** The names to import (`[\"Button\", \"IconButton\"]`): from `@krizaka/ui/<name>` on the web, `@krizaka/ui/native` in React Native. */\n  readonly imports: readonly string[];\n  /** The examples, in reading order; the first one is the component's preview. */\n  readonly examples: readonly Example[];\n}\n\n/** The React Native side: the same concept, and what differs from the web API. */\nexport interface NativeDocs extends PlatformDocs {\n  /**\n   * The entry to import from when it is not `@krizaka/ui/native`: a component that needs an Expo module (an optional\n   * peer) has its own, `@krizaka/ui/native/<name>`, so an app that does not use it never installs the module.\n   */\n  readonly entry?: string;\n  /** What differs from the web API (`label` instead of children…); empty for a native-only component. */\n  readonly differences: readonly string[];\n}\n\nexport interface KeyboardInteraction {\n  /** The keys, as written on a keyboard: `Space`, `Enter`, `Arrow keys`, `Esc`, `Tab`. */\n  readonly keys: string;\n  /** What they do. */\n  readonly action: string;\n}\n\nexport interface ComponentMeta {\n  /** The display name: `Button`, `Dropdown menu`. */\n  readonly title: string;\n  /** One sentence: what it is. */\n  readonly summary: string;\n  readonly status: Status;\n  readonly category: Category;\n  /** Must match the sides below: `both` ⇔ `web` and `native`. */\n  readonly platforms: Platform;\n  /** When to reach for it: concrete situations, one per item. */\n  readonly whenToUse: readonly string[];\n  /** When not to — and what to use instead (`use`), when another component is the answer. */\n  readonly whenNotToUse: readonly { readonly when: string; readonly use?: ComponentName }[];\n  /** How to use it well: wording, placement, composition. */\n  readonly bestPractices: readonly string[];\n  readonly accessibility: {\n    /** The keyboard, when it does more than Tab and Enter. */\n    readonly keyboard: readonly KeyboardInteraction[];\n    /** Roles, names and announcements: what the component does, what the app must provide. */\n    readonly notes: readonly string[];\n  };\n  /** The components a reader of this page should know about. */\n  readonly related: readonly ComponentName[];\n  readonly web?: PlatformDocs;\n  readonly native?: NativeDocs;\n}\n"
     },
     {
       "path": "popover/index.ts",