@krizaka/ui 3.14.0 → 3.16.0

package/registry/document-viewer.json

@@ -0,0 +1,232 @@
+{
+  "name": "document-viewer",
+  "type": "primitive",
+  "title": "Document viewer",
+  "summary": "A PDF drawn page by page with pdf.js, and the passages of a report lit where they sit — found from the PDF's own text positions, one box per line; the page and the quote when the text layer cannot place them.",
+  "description": "A PDF drawn page by page with pdf.js, and the passages of a report lit where they sit — found from the PDF's own text positions, one box per line; the page and the quote when the text layer cannot place them.",
+  "status": "beta",
+  "deprecated": null,
+  "category": "media",
+  "platforms": "web",
+  "whenToUse": [
+    "To read a document beside what was said about it: findings, comments, extracted fields.",
+    "To make a quoted passage visible in the original file instead of in a copy of its text."
+  ],
+  "whenNotToUse": [
+    {
+      "when": "To play a video or a recording.",
+      "use": "video-player"
+    },
+    {
+      "when": "To show an image to crop.",
+      "use": "image-cropper"
+    },
+    {
+      "when": "To let the browser open the file as it is: a link to the file is enough.",
+      "use": "button"
+    }
+  ],
+  "bestPractices": [
+    "Keep the list of passages in the page, next to the viewer: the viewer is not a keyboard route to each box, your list is (`activeId` / `onActiveChange`).",
+    "Pass the quote as the text layer reads it and, when you know it, the page: a quote the layout cut is still placed by its opening words, and a page alone still scrolls.",
+    "Use `onLocate` to tell the person what was placed and what was not (« page 3 », « not found in the text layer ») — a passage is never drawn at a guessed place.",
+    "Load pdf.js with `() => import(\"pdfjs-dist\")` and give it a same-origin worker (`workerSrc`): the engine only reaches pages that show a document."
+  ],
+  "accessibility": {
+    "keyboard": [
+      {
+        "keys": "Tab, arrows, Page Up / Down",
+        "action": "The pages' region is focusable and scrolls like any scrollable area."
+      }
+    ],
+    "notes": [
+      "The region is named by `labels.region`; each page is announced by its caption (« Page 2 of 5 »).",
+      "The highlight boxes are decorative (`aria-hidden`): the passages are reached through your list, whose entries scroll to them.",
+      "A scanned PDF has no text layer: nothing is lit, and the pages stay readable as images — offer the text alternative yourself.",
+      "A passage that cannot be placed is announced in a bar with its quote."
+    ]
+  },
+  "related": [
+    "tabs",
+    "split-view",
+    "image-cropper",
+    "video-player"
+  ],
+  "web": {
+    "entry": "@krizaka/ui/document-viewer",
+    "import": "import { DocumentViewer, locateQuote } from \"@krizaka/ui/document-viewer\";",
+    "props": [
+      {
+        "component": "DocumentViewer",
+        "description": "A PDF with its passages lit — see the file's header. Client.",
+        "props": [
+          {
+            "name": "loadPdfjs",
+            "type": "() => Promise<PdfjsModule>",
+            "default": null,
+            "description": "Loads pdf.js: `() => import(\"pdfjs-dist\")`. An optional peer, never in a bundle without a document.",
+            "required": true
+          },
+          {
+            "name": "src",
+            "type": "string | Uint8Array<ArrayBufferLike>",
+            "default": null,
+            "description": "The PDF: an address (same origin or CORS) or its bytes.",
+            "required": true
+          },
+          {
+            "name": "workerSrc",
+            "type": "string",
+            "default": null,
+            "description": "The address of pdf.js's worker (`new URL(\"pdfjs-dist/build/pdf.worker.min.mjs\", import.meta.url).toString()`).",
+            "required": true
+          },
+          {
+            "name": "activeId",
+            "type": "string | null",
+            "default": "null",
+            "description": "The passage in focus: the viewer scrolls to it.",
+            "required": false
+          },
+          {
+            "name": "highlights",
+            "type": "readonly DocumentHighlight[]",
+            "default": "[]",
+            "description": "The passages to light.",
+            "required": false
+          },
+          {
+            "name": "labels",
+            "type": "Partial<DocumentViewerLabels>",
+            "default": null,
+            "description": "The words of the viewer, translated (English by default).",
+            "required": false
+          },
+          {
+            "name": "onActiveChange",
+            "type": "((id: string | null) => void)",
+            "default": null,
+            "description": "A box was clicked (the id) or the focus was released (`null`).",
+            "required": false
+          },
+          {
+            "name": "onLocate",
+            "type": "((found: Record<string, Located | null>) => void)",
+            "default": null,
+            "description": "Where each passage was found (`null`: nowhere) — once the text layer is read, and again if `highlights` change.",
+            "required": false
+          }
+        ]
+      }
+    ],
+    "examples": [
+      {
+        "name": "highlights",
+        "title": "Findings in the file",
+        "description": "A one-page lease and two passages; pick one and the page scrolls to it and lights it.",
+        "path": "examples/document-viewer/highlights.tsx",
+        "module": "@krizaka/ui/registry/examples/document-viewer/highlights",
+        "code": "\"use client\";\n\nimport { DocumentViewer } from \"@krizaka/ui/document-viewer\";\nimport * as React from \"react\";\n\nconst PDF = \"JVBERi0xLjQKMSAwIG9iago8PCAvVHlwZSAvQ2F0YWxvZyAvUGFnZXMgMiAwIFIgPj4KZW5kb2JqCjIgMCBvYmoKPDwgL1R5cGUgL1BhZ2VzIC9LaWRzIFszIDAgUl0gL0NvdW50IDEgPj4KZW5kb2JqCjMgMCBvYmoKPDwgL1R5cGUgL1BhZ2UgL1BhcmVudCAyIDAgUiAvTWVkaWFCb3ggWzAgMCA2MTIgNzkyXSAvQ29udGVudHMgNCAwIFIgL1Jlc291cmNlcyA8PCAvRm9udCA8PCAvRjEgNSAwIFIgPj4gPj4gPj4KZW5kb2JqCjQgMCBvYmoKPDwgL0xlbmd0aCAyMDkgPj4Kc3RyZWFtCkJUIC9GMSAxNCBUZiA3MiA3MDAgVGQgKEJBSUwgUkVTSURFTlRJRUwpIFRqIEVUCkJUIC9GMSAxMSBUZiA3MiA2NzAgVGQgKExlIGxvY2F0ZXVyIHBldXQgYXVnbWVudGVyIGxlIGxveWVyIGEgdG91dCBtb21lbnQuKSBUaiBFVApCVCAvRjEgMTEgVGYgNzIgNjUwIFRkIChMZSBkZXBvdCBkZSBnYXJhbnRpZSBlc3QgZGUgZGV1eCBtb2lzIGRlIGxveWVyLikgVGogRVQKZW5kc3RyZWFtCmVuZG9iago1IDAgb2JqCjw8IC9UeXBlIC9Gb250IC9TdWJ0eXBlIC9UeXBlMSAvQmFzZUZvbnQgL0hlbHZldGljYSA+PgplbmRvYmoKeHJlZgowIDYKMDAwMDAwMDAwMCA2NTUzNSBmIAowMDAwMDAwMDA5IDAwMDAwIG4gCjAwMDAwMDAwNTggMDAwMDAgbiAKMDAwMDAwMDExNSAwMDAwMCBuIAowMDAwMDAwMjQxIDAwMDAwIG4gCjAwMDAwMDA1MDAgMDAwMDAgbiAKdHJhaWxlcgo8PCAvU2l6ZSA2IC9Sb290IDEgMCBSID4+CnN0YXJ0eHJlZgo1NzAKJSVFT0YK\";\nconst quotes = [\n  { id: \"r1\", quote: \"Le locateur peut augmenter le loyer à tout moment.\", label: \"Rent increase\" },\n  { id: \"r2\", quote: \"Le dépôt de garantie est de deux mois de loyer.\", label: \"Deposit\" },\n];\n// pdf.js is the app's: `loadPdfjs={() => import(\"pdfjs-dist\")}` and a worker served from its own origin. Here, from a CDN.\nconst CDN = \"https://cdn.jsdelivr.net/npm/pdfjs-dist@5.4.149/build/\";\nconst loadPdfjs = () => import(/* webpackIgnore: true */ /* turbopackIgnore: true */ `${CDN}pdf.min.mjs`) as never;\n\n// Pick a passage in your own list: the viewer scrolls to it and lights it where it sits in the page.\nexport default function DocumentViewerHighlights() {\n  const [active, setActive] = React.useState<string | null>(\"r1\");\n  return (\n    <div className=\"flex flex-col gap-3\">\n      <div className=\"flex gap-2\">\n        {quotes.map((q) => (\n          <button key={q.id} type=\"button\" aria-pressed={active === q.id} className=\"rounded-md border border-border-default px-3 py-1 text-sm aria-pressed:bg-surface-3\" onClick={() => setActive(q.id)}>\n            {q.label}\n          </button>\n        ))}\n      </div>\n      <DocumentViewer src={Uint8Array.from(atob(PDF), (c) => c.charCodeAt(0))} loadPdfjs={loadPdfjs} workerSrc={`${CDN}pdf.worker.min.mjs`} highlights={quotes} activeId={active} onActiveChange={setActive} />\n    </div>\n  );\n}\n"
+      }
+    ]
+  },
+  "native": null,
+  "files": [
+    {
+      "path": "document-viewer/document-viewer.tsx",
+      "content": "// Client. A PDF drawn page by page (pdf.js), and passages of it lit where they sit. The app hands over the engine\n// (`loadPdfjs={() => import(\"pdfjs-dist\")}` — an optional peer, loaded only on a page that shows a document) and the\n// worker's address; it hands over the passages as quotes (`highlights`), and the viewer finds their place from the\n// PDF's own text positions (`locateQuote`): one box per line, in fractions of the page, so they follow any zoom.\n// `activeId` (controlled) scrolls to a passage and strengthens it; a click on a box calls `onActiveChange`. A passage\n// the text layer cannot place is never drawn at a guessed place: the viewer goes to its page when it is known and shows\n// the quote in a bar — and tells the app (`onLocate`) so its list can say \"page 3\" or \"not found\".\nimport * as React from \"react\";\nimport { tv } from \"tailwind-variants\";\n\nimport { useLatest, usePrefersReducedMotion } from \"../media\";\nimport { type Located, locateQuote, type PageText } from \"./locate\";\n\nexport const documentViewer = tv({\n  slots: {\n    root: \"relative flex min-w-0 flex-col gap-3\",\n    pages: \"flex max-h-(--kz-document-viewer-height,70vh) flex-col gap-3 overflow-auto rounded-lg border border-border-default bg-surface-2 p-3 focus-visible:outline-2 focus-visible:outline-offset-2 focus-visible:outline-accent\",\n    page: \"relative mx-auto w-full max-w-(--kz-document-viewer-page,56rem) shrink-0 overflow-hidden rounded-sm bg-white shadow-sm\",\n    canvas: \"block h-auto w-full\",\n    caption: \"absolute top-1 left-1 rounded-sm bg-surface-1/90 px-1.5 py-0.5 text-xs text-fg-secondary\",\n    box: \"absolute cursor-pointer rounded-xs border border-warning/70 bg-warning/25 mix-blend-multiply transition-colors data-[active=true]:border-2 data-[active=true]:border-danger data-[active=true]:bg-danger/25 motion-reduce:transition-none\",\n    bar: \"rounded-lg border border-border-default bg-surface-1 px-3 py-2 text-sm text-fg-secondary\",\n    status: \"p-6 text-center text-sm text-fg-secondary\",\n  },\n});\n\n/** The words of the viewer, passed translated. `{page}` and `{total}` are replaced. */\nexport type DocumentViewerLabels = {\n  /** The accessible name of the pages' region. */\n  region: string;\n  loading: string;\n  failed: string;\n  /** A page's caption and accessible name: \"Page {page} of {total}\". */\n  page: string;\n  /** The bar above the pages when the active passage could only be placed on a page: \"Passage on page {page}:\". */\n  onPage: string;\n  /** The bar when the active passage is not in the text layer. */\n  notFound: string;\n};\n\nexport const documentViewerLabels: DocumentViewerLabels = {\n  region: \"Document pages\",\n  loading: \"Loading the document…\",\n  failed: \"The document could not be displayed.\",\n  page: \"Page {page} of {total}\",\n  onPage: \"Passage on page {page}:\",\n  notFound: \"This passage is not in the document's text layer:\",\n};\n\n/** A passage to light: its quote (as the text layer reads it), the page if the app knows it, a name for screen readers. */\nexport type DocumentHighlight = { id: string; quote: string; page?: number; label?: string };\n\n/** What the viewer found for a passage. */\nexport type { Located };\n\n/** The members of pdf.js the viewer uses (`pdfjs-dist` ≥ 5), typed here so the package does not depend on it. */\nexport type PdfjsModule = {\n  GlobalWorkerOptions: { workerSrc: string };\n  getDocument(source: { url?: string; data?: Uint8Array }): { promise: Promise<PdfDocument>; destroy?: () => Promise<void> | void };\n};\nexport type PdfDocument = { numPages: number; getPage(n: number): Promise<PdfPage>; destroy?: () => Promise<void> | void };\nexport type PdfPage = {\n  rotate: number;\n  view: number[];\n  getViewport(options: { scale: number }): { width: number; height: number };\n  getTextContent(): Promise<{ items: readonly unknown[] }>;\n  render(options: { canvas: HTMLCanvasElement; canvasContext: CanvasRenderingContext2D; viewport: { width: number; height: number } }): { promise: Promise<void>; cancel?: () => void };\n  cleanup?: () => void;\n};\n\nexport type DocumentViewerProps = Omit<React.ComponentProps<\"div\">, \"children\" | \"onChange\"> & {\n  /** The PDF: an address (same origin or CORS) or its bytes. */\n  src: string | Uint8Array;\n  /** Loads pdf.js: `() => import(\"pdfjs-dist\")`. An optional peer, never in a bundle without a document. */\n  loadPdfjs: () => Promise<PdfjsModule>;\n  /** The address of pdf.js's worker (`new URL(\"pdfjs-dist/build/pdf.worker.min.mjs\", import.meta.url).toString()`). */\n  workerSrc: string;\n  /** The passages to light. */\n  highlights?: readonly DocumentHighlight[];\n  /** The passage in focus: the viewer scrolls to it. */\n  activeId?: string | null;\n  /** A box was clicked (the id) or the focus was released (`null`). */\n  onActiveChange?: (id: string | null) => void;\n  /** Where each passage was found (`null`: nowhere) — once the text layer is read, and again if `highlights` change. */\n  onLocate?: (found: Record<string, Located | null>) => void;\n  /** Called when the document is open, with its page count. */\n  onLoad?: (info: { pages: number }) => void;\n  /** The words of the viewer, translated (English by default). */\n  labels?: Partial<DocumentViewerLabels>;\n};\n\nconst fill = (template: string, vars: Record<string, string | number>) => template.replace(/\\{(\\w+)\\}/g, (m, k: string) => (k in vars ? String(vars[k]) : m));\n\ntype Loaded = { doc: PdfDocument; texts: PageText[]; sizes: { width: number; height: number }[] };\ntype Phase = { state: \"loading\" } | { state: \"error\"; key: string } | ({ state: \"ready\"; key: string } & Loaded);\n\nconst isItem = (x: unknown): x is PageText[\"items\"][number] => typeof x === \"object\" && x !== null && typeof (x as { str?: unknown }).str === \"string\" && Array.isArray((x as { transform?: unknown }).transform);\n\nfunction PageCanvas({ page, doc, caption, onReady, className }: { page: number; doc: PdfDocument; caption: string; onReady?: () => void; className: string }) {\n  const ref = React.useRef<HTMLCanvasElement>(null);\n  const wrapper = React.useRef<HTMLDivElement>(null);\n  const [visible, setVisible] = React.useState(() => typeof IntersectionObserver === \"undefined\");\n  const ready = useLatest(onReady);\n  React.useEffect(() => {\n    const node = wrapper.current?.parentElement;\n    if (!node) return;\n    if (typeof IntersectionObserver === \"undefined\") return;\n    const observer = new IntersectionObserver((entries) => entries.some((e) => e.isIntersecting) && setVisible(true), { rootMargin: \"600px 0px\" });\n    observer.observe(node);\n    return () => observer.disconnect();\n  }, []);\n  React.useEffect(() => {\n    if (!visible) return;\n    let task: { promise: Promise<void>; cancel?: () => void } | undefined;\n    let cancelled = false;\n    void (async () => {\n      const p = await doc.getPage(page);\n      const canvas = ref.current;\n      const ctx = canvas?.getContext(\"2d\");\n      if (cancelled || !canvas || !ctx) return;\n      const base = p.getViewport({ scale: 1 });\n      const dpr = typeof window === \"undefined\" ? 1 : Math.min(2, window.devicePixelRatio || 1);\n      const scale = Math.min(2.5, Math.max(1, (canvas.parentElement?.clientWidth || base.width) / base.width)) * dpr;\n      const viewport = p.getViewport({ scale });\n      canvas.width = Math.floor(viewport.width);\n      canvas.height = Math.floor(viewport.height);\n      task = p.render({ canvas, canvasContext: ctx, viewport });\n      await task.promise.catch(() => undefined);\n      if (!cancelled) ready.current?.();\n    })().catch(() => undefined);\n    return () => {\n      cancelled = true;\n      task?.cancel?.();\n    };\n  }, [visible, doc, page, ready]);\n  return (\n    <div ref={wrapper} className=\"contents\">\n      <canvas ref={ref} aria-hidden=\"true\" className={className} />\n      <span className=\"sr-only\">{caption}</span>\n    </div>\n  );\n}\n\n/** A PDF with its passages lit — see the file's header. Client. */\nexport function DocumentViewer({ src, loadPdfjs, workerSrc, highlights = [], activeId = null, onActiveChange, onLocate, onLoad, labels, className, ...props }: DocumentViewerProps) {\n  const words = { ...documentViewerLabels, ...labels };\n  const s = documentViewer();\n  const reduce = usePrefersReducedMotion();\n  const [loaded, setPhase] = React.useState<Phase>({ state: \"loading\" });\n  const callbacks = useLatest({ onLoad, onLocate });\n  const containerRef = React.useRef<HTMLDivElement>(null);\n  const bytes = typeof src === \"string\" ? src : src.byteLength + \":\" + src[0] + \":\" + src[src.length - 1];\n  // A result belongs to the document it was read from: another `src` is loading again, with no reset inside the effect.\n  const phase: Phase = loaded.state !== \"loading\" && loaded.key !== bytes ? { state: \"loading\" } : loaded;\n\n  // Open the document and read every page's text layer (positions only; nothing is sent anywhere).\n  React.useEffect(() => {\n    let cancelled = false;\n    let opened: { destroy?: () => Promise<void> | void } | undefined;\n    void (async () => {\n      const pdfjs = await loadPdfjs();\n      pdfjs.GlobalWorkerOptions.workerSrc = workerSrc;\n      const loading = pdfjs.getDocument(typeof src === \"string\" ? { url: src } : { data: src.slice() });\n      opened = loading;\n      const doc = await loading.promise;\n      const texts: PageText[] = [];\n      const sizes: Loaded[\"sizes\"] = [];\n      for (let n = 1; n <= doc.numPages; n++) {\n        const page = await doc.getPage(n);\n        const vp = page.getViewport({ scale: 1 });\n        sizes.push({ width: vp.width, height: vp.height });\n        const content = await page.getTextContent();\n        // A rotated page has no reliable boxes: it keeps its size and an empty text layer (the app's page hint still works).\n        texts.push({ page: n, width: vp.width, height: vp.height, items: page.rotate % 360 === 0 ? content.items.filter(isItem) : [] });\n        page.cleanup?.();\n      }\n      if (cancelled) return;\n      setPhase({ state: \"ready\", key: bytes, doc, texts, sizes });\n      callbacks.current.onLoad?.({ pages: doc.numPages });\n    })().catch(() => !cancelled && setPhase({ state: \"error\", key: bytes }));\n    return () => {\n      cancelled = true;\n      void opened?.destroy?.();\n    };\n    // `src` is compared by content (`bytes`) so a re-render with the same bytes does not reopen the file.\n    // eslint-disable-next-line react-hooks/exhaustive-deps\n  }, [bytes, loadPdfjs, workerSrc, callbacks]);\n\n  const key = highlights.map((h) => `${h.id}\\u0000${h.page ?? \"\"}\\u0000${h.quote}`).join(\"\\u0001\");\n  const found = React.useMemo(() => {\n    const out: Record<string, Located | null> = {};\n    if (phase.state === \"ready\") for (const h of highlights) out[h.id] = locateQuote(phase.texts, h.quote, h.page);\n    return out;\n    // eslint-disable-next-line react-hooks/exhaustive-deps\n  }, [phase, key]);\n  React.useEffect(() => {\n    if (phase.state === \"ready\") callbacks.current.onLocate?.(found);\n  }, [found, phase.state, callbacks]);\n\n  // Go to the active passage.\n  const active = activeId ? highlights.find((h) => h.id === activeId) : undefined;\n  const where = activeId ? found[activeId] : undefined;\n  React.useEffect(() => {\n    if (phase.state !== \"ready\" || !where) return;\n    const root = containerRef.current;\n    const target = root?.querySelector<HTMLElement>(where.boxes.length > 0 ? `[data-highlight=\"${CSS.escape(activeId!)}\"]` : `[data-page=\"${where.page}\"]`) ?? null;\n    target?.scrollIntoView?.({ block: where.boxes.length > 0 ? \"center\" : \"start\", behavior: reduce ? \"auto\" : \"smooth\" });\n    // eslint-disable-next-line react-hooks/exhaustive-deps\n  }, [activeId, where, phase.state]);\n\n  return (\n    <div className={s.root({ className })} {...props}>\n      {active && where !== undefined && where?.match !== \"exact\" && where?.match !== \"start\" ? (\n        <p className={s.bar()} data-testid=\"document-viewer-bar\">\n          {where?.match === \"page\" ? fill(words.onPage, { page: where.page }) : words.notFound} <q>{active.quote}</q>\n        </p>\n      ) : null}\n      <div ref={containerRef} className={s.pages()} role=\"region\" aria-label={words.region} tabIndex={0}>\n        {phase.state === \"loading\" ? <p className={s.status()}>{words.loading}</p> : null}\n        {phase.state === \"error\" ? <p role=\"alert\" className={s.status()}>{words.failed}</p> : null}\n        {phase.state === \"ready\"\n          ? phase.texts.map((t, i) => {\n              const size = phase.sizes[i]!;\n              const caption = fill(words.page, { page: t.page, total: phase.doc.numPages });\n              return (\n                <div key={t.page} className={s.page()} data-page={t.page} style={{ aspectRatio: `${size.width} / ${size.height}` }}>\n                  <PageCanvas page={t.page} doc={phase.doc} caption={caption} className={s.canvas()} />\n                  <span className={s.caption()} aria-hidden=\"true\">{caption}</span>\n                  {highlights.flatMap((h) => {\n                    const f = found[h.id];\n                    if (!f || f.page !== t.page) return [];\n                    return f.boxes.map((b, k) => (\n                      <div\n                        key={`${h.id}:${k}`}\n                        aria-hidden=\"true\"\n                        data-highlight={h.id}\n                        data-active={h.id === activeId}\n                        className={s.box()}\n                        style={{ left: `${b.x * 100}%`, top: `${b.y * 100}%`, width: `${b.width * 100}%`, height: `${b.height * 100}%` }}\n                        onClick={() => onActiveChange?.(h.id === activeId ? null : h.id)}\n                      />\n                    ));\n                  })}\n                </div>\n              );\n            })\n          : null}\n      </div>\n    </div>\n  );\n}\n"
+    },
+    {
+      "path": "document-viewer/index.ts",
+      "content": "/** @krizaka/ui/document-viewer — `DocumentViewer` (a PDF drawn by pdf.js, its passages lit where they sit), `locateQuote` (a quote → boxes, pure). Client (\"use client\"). */\nexport { type DocumentHighlight, DocumentViewer, documentViewer, type DocumentViewerLabels, documentViewerLabels, type DocumentViewerProps, type Located, type PdfDocument, type PdfjsModule, type PdfPage } from \"./document-viewer\";\nexport { type Box, fold, locateQuote, type PageText, type TextItem } from \"./locate\";\n"
+    },
+    {
+      "path": "document-viewer/locate.ts",
+      "content": "// Pure: where a quoted passage sits on the pages of a PDF, from pdf.js's text positions. No DOM, no pdf.js import —\n// the viewer feeds it what `page.getTextContent()` returned, a test feeds it a fixture.\n\n/** A text item as pdf.js returns it (`TextItem`): the string, its matrix (`[a, b, c, d, x, baseline]`) and its size. */\nexport type TextItem = { str: string; transform: number[]; width: number; height: number };\n\n/** A rectangle in fractions of the page (0–1), origin top-left — independent of the zoom the page is drawn at. */\nexport type Box = { x: number; y: number; width: number; height: number };\n\n/** The text layer of one page: its size in PDF units (rotation 0) and its items in reading order. */\nexport type PageText = { page: number; width: number; height: number; items: readonly TextItem[] };\n\nexport type Located = {\n  /** 1-based page where the passage starts. */\n  page: number;\n  /** One box per line of the passage (merged along a line); empty when only the page is known. */\n  boxes: Box[];\n  /** `exact`: the whole quote was found; `start`: only its opening words were (a quote cut by a different layout). */\n  match: \"exact\" | \"start\" | \"page\";\n};\n\nconst FOLD: Record<string, string> = { \"’\": \"'\", \"‘\": \"'\", \"“\": '\"', \"”\": '\"', \"«\": '\"', \"»\": '\"', \"–\": \"-\", \"—\": \"-\", \" \": \" \", \" \": \" \", \"fi\": \"fi\", \"fl\": \"fl\" };\n\n/** The comparable form of a text: no whitespace, no soft hyphen, straight quotes, case and accents folded. */\nexport function fold(text: string): string {\n  let out = \"\";\n  for (const ch of text.normalize(\"NFKD\")) {\n    if (/\\p{M}/u.test(ch) || /\\s/u.test(ch) || ch === \"­\" || ch === \"​\") continue;\n    out += (FOLD[ch] ?? ch).toLowerCase();\n  }\n  return out;\n}\n\ntype Index = { text: string; at: { item: number; char: number }[] };\n\nfunction indexPage(items: readonly TextItem[]): Index {\n  let text = \"\";\n  const at: Index[\"at\"] = [];\n  items.forEach((item, i) => {\n    for (let c = 0; c < item.str.length; c++) {\n      const piece = fold(item.str[c]!);\n      for (let k = 0; k < piece.length; k++) {\n        text += piece[k];\n        at.push({ item: i, char: c });\n      }\n    }\n  });\n  return { text, at };\n}\n\nfunction boxesOf(page: PageText, index: Index, from: number, to: number): Box[] {\n  const spans = new Map<number, [number, number]>();\n  for (let k = from; k < to; k++) {\n    const { item, char } = index.at[k]!;\n    const s = spans.get(item);\n    spans.set(item, s ? [Math.min(s[0], char), Math.max(s[1], char + 1)] : [char, char + 1]);\n  }\n  const raw: Box[] = [];\n  for (const [i, [c0, c1]] of [...spans].sort((a, b) => a[0] - b[0])) {\n    const item = page.items[i]!;\n    const len = Math.max(1, item.str.length);\n    const size = item.height || Math.abs(item.transform[3] ?? 0) || 10;\n    const x = (item.transform[4] ?? 0) + (item.width * c0) / len;\n    const w = (item.width * (c1 - c0)) / len;\n    const top = page.height - ((item.transform[5] ?? 0) + size * 0.9);\n    raw.push({ x: x / page.width, y: top / page.height, width: w / page.width, height: (size * 1.15) / page.height });\n  }\n  // Merge the pieces that sit on one line and touch (several items of one sentence) into one rectangle.\n  const merged: Box[] = [];\n  for (const b of raw) {\n    const last = merged[merged.length - 1];\n    const sameLine = last && Math.abs(last.y - b.y) < last.height * 0.5 && b.x - (last.x + last.width) < last.height * 1.5 && b.x >= last.x - 1e-9;\n    if (last && sameLine) {\n      const right = Math.max(last.x + last.width, b.x + b.width);\n      last.y = Math.min(last.y, b.y);\n      last.height = Math.max(last.height, b.height);\n      last.width = right - last.x;\n    } else merged.push({ ...b });\n  }\n  return merged.map((b) => ({ x: clamp01(b.x), y: clamp01(b.y), width: Math.min(b.width, 1 - clamp01(b.x)), height: Math.min(b.height, 1 - clamp01(b.y)) }));\n}\n\nconst clamp01 = (n: number) => Math.min(1, Math.max(0, n));\n\n/** The shortest opening worth highlighting alone: a few words, not a stray letter. */\nconst MIN_START = 24;\n\n/**\n * Where `quote` sits in the pages: the first page (starting with `hintPage`, if any) whose text contains it, and the\n * boxes of its lines. A quote that a different layout cut (a column break, a hyphen) is looked for by its opening\n * words (`match: \"start\"`); one that is nowhere gives `null`, or the hinted page alone (`match: \"page\"`). Never a guess:\n * a rotated page has no boxes, only its page.\n */\nexport function locateQuote(pages: readonly PageText[], quote: string, hintPage?: number): Located | null {\n  const needle = fold(quote);\n  const ordered = hintPage ? [...pages].sort((a, b) => Number(b.page === hintPage) - Number(a.page === hintPage)) : pages;\n  if (needle.length > 0) {\n    for (const mode of [\"exact\", \"start\"] as const) {\n      const wanted = mode === \"exact\" ? needle : needle.slice(0, Math.max(MIN_START, Math.min(40, Math.floor(needle.length * 0.6))));\n      if (mode === \"start\" && (needle.length <= wanted.length || wanted.length < MIN_START)) break;\n      for (const page of ordered) {\n        const index = indexPage(page.items);\n        const found = index.text.indexOf(wanted);\n        if (found < 0) continue;\n        return { page: page.page, boxes: boxesOf(page, index, found, found + wanted.length), match: mode };\n      }\n    }\n  }\n  return hintPage && pages.some((p) => p.page === hintPage) ? { page: hintPage, boxes: [], match: \"page\" } : null;\n}\n"
+    },
+    {
+      "path": "document-viewer/meta.ts",
+      "content": "import type { ComponentMeta } from \"../meta\";\n\nexport const meta = {\n  title: \"Document viewer\",\n  summary: \"A PDF drawn page by page with pdf.js, and the passages of a report lit where they sit — found from the PDF's own text positions, one box per line; the page and the quote when the text layer cannot place them.\",\n  status: \"beta\",\n  category: \"media\",\n  platforms: \"web\",\n  whenToUse: [\n    \"To read a document beside what was said about it: findings, comments, extracted fields.\",\n    \"To make a quoted passage visible in the original file instead of in a copy of its text.\",\n  ],\n  whenNotToUse: [\n    { when: \"To play a video or a recording.\", use: \"video-player\" },\n    { when: \"To show an image to crop.\", use: \"image-cropper\" },\n    { when: \"To let the browser open the file as it is: a link to the file is enough.\", use: \"button\" },\n  ],\n  bestPractices: [\n    \"Keep the list of passages in the page, next to the viewer: the viewer is not a keyboard route to each box, your list is (`activeId` / `onActiveChange`).\",\n    \"Pass the quote as the text layer reads it and, when you know it, the page: a quote the layout cut is still placed by its opening words, and a page alone still scrolls.\",\n    \"Use `onLocate` to tell the person what was placed and what was not (« page 3 », « not found in the text layer ») — a passage is never drawn at a guessed place.\",\n    \"Load pdf.js with `() => import(\\\"pdfjs-dist\\\")` and give it a same-origin worker (`workerSrc`): the engine only reaches pages that show a document.\",\n  ],\n  accessibility: {\n    keyboard: [{ keys: \"Tab, arrows, Page Up / Down\", action: \"The pages' region is focusable and scrolls like any scrollable area.\" }],\n    notes: [\n      \"The region is named by `labels.region`; each page is announced by its caption (« Page 2 of 5 »).\",\n      \"The highlight boxes are decorative (`aria-hidden`): the passages are reached through your list, whose entries scroll to them.\",\n      \"A scanned PDF has no text layer: nothing is lit, and the pages stay readable as images — offer the text alternative yourself.\",\n      \"A passage that cannot be placed is announced in a bar with its quote.\",\n    ],\n  },\n  related: [\"tabs\", \"split-view\", \"image-cropper\", \"video-player\"],\n  web: {\n    imports: [\"DocumentViewer\", \"locateQuote\"],\n    examples: [\n      { name: \"highlights\", title: \"Findings in the file\", description: \"A one-page lease and two passages; pick one and the page scrolls to it and lights it.\" },\n    ],\n  },\n} satisfies ComponentMeta;\n"
+    },
+    {
+      "path": "media.ts",
+      "content": "// Shared by the data and media primitives (client): the clock format, the reduced-motion preference, the\n// in-view observer, a debounced callback. Never an entry of its own.\nimport * as React from \"react\";\n\n/** Seconds as a clock: `75` → `1:15`, `3725` → `1:02:05`. Negative or unknown values read `0:00`. */\nexport function formatClock(seconds: number): string {\n  const s = Number.isFinite(seconds) && seconds > 0 ? Math.floor(seconds) : 0;\n  const h = Math.floor(s / 3600);\n  const m = Math.floor((s % 3600) / 60);\n  const rest = String(s % 60).padStart(2, \"0\");\n  return h > 0 ? `${h}:${String(m).padStart(2, \"0\")}:${rest}` : `${m}:${rest}`;\n}\n\n/** Clamps `value` between `min` and `max`. */\nexport const clamp = (value: number, min: number, max: number) => Math.min(max, Math.max(min, value));\n\nconst REDUCE = \"(prefers-reduced-motion: reduce)\";\nconst subscribeReduce = (notify: () => void) => {\n  if (typeof window === \"undefined\" || !window.matchMedia) return () => undefined;\n  const query = window.matchMedia(REDUCE);\n  query.addEventListener?.(\"change\", notify);\n  return () => query.removeEventListener?.(\"change\", notify);\n};\n\n/** `true` when the person asked for less motion (`prefers-reduced-motion: reduce`); follows a change of the setting. */\nexport function usePrefersReducedMotion(): boolean {\n  return React.useSyncExternalStore(\n    subscribeReduce,\n    () => (typeof window !== \"undefined\" && window.matchMedia ? window.matchMedia(REDUCE).matches : false),\n    () => false,\n  );\n}\n\n/** The latest value of a callback, for an effect or an event that must not re-subscribe when it changes. */\nexport function useLatest<T>(value: T) {\n  const ref = React.useRef(value);\n  React.useLayoutEffect(() => {\n    ref.current = value;\n  });\n  return ref;\n}\n\n/** Calls `onChange(visible)` when at least `threshold` of the element enters or leaves the viewport. */\nexport function useInView(ref: React.RefObject<Element | null>, onChange: (visible: boolean) => void, enabled = true, threshold = 0.25) {\n  const latest = useLatest(onChange);\n  React.useEffect(() => {\n    const element = ref.current;\n    if (!enabled || !element || typeof IntersectionObserver === \"undefined\") return;\n    const observer = new IntersectionObserver(([entry]) => entry && latest.current(entry.isIntersecting), { threshold });\n    observer.observe(element);\n    return () => observer.disconnect();\n  }, [ref, enabled, threshold, latest]);\n}\n\n/** A value controlled by a prop when it is given, held inside otherwise; `set` calls `onChange` either way. */\nexport function useControllable<T>(value: T | undefined, defaultValue: T, onChange?: (next: T) => void) {\n  const [inner, setInner] = React.useState(defaultValue);\n  const controlled = value !== undefined;\n  const current = controlled ? value : inner;\n  const set = React.useCallback(\n    (next: T) => {\n      if (!controlled) setInner(next);\n      onChange?.(next);\n    },\n    [controlled, onChange],\n  );\n  return [current, set] as const;\n}\n\n/** Starts a media element without an unhandled rejection (autoplay refused, the source replaced meanwhile). */\nexport function playSafely(media: HTMLMediaElement | null | undefined) {\n  try {\n    const started = media?.play() as Promise<void> | undefined;\n    started?.catch?.(() => undefined);\n  } catch {\n    // Not playable here (no media support): the controls stay as they are.\n  }\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 ui.krizaka.com (apps/site) renders as\n// ui.krizaka.com/components/<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  | \"activity-feed\"\n  | \"action-sheet\"\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  | \"chat\"\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  | \"description-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  | \"fab\"\n  | \"field\"\n  | \"file-upload\"\n  | \"filter-bar\"\n  | \"form\"\n  | \"gallery-page\"\n  | \"glow-card\"\n  | \"goal-gauge\"\n  | \"header\"\n  | \"how-it-works-page\"\n  | \"document-viewer\"\n  | \"image-cropper\"\n  | \"image-viewer\"\n  | \"iso\"\n  | \"kanban\"\n  | \"kbd\"\n  | \"landing-page\"\n  | \"landscape\"\n  | \"legal-page\"\n  | \"link-card\"\n  | \"list\"\n  | \"loader\"\n  | \"map\"\n  | \"markdown\"\n  | \"longform-page\"\n  | \"marketing-layout\"\n  | \"marquee\"\n  | \"mascot-quote\"\n  | \"mascot-state\"\n  | \"mascots\"\n  | \"match-dialog\"\n  | \"media-capture\"\n  | \"media-picker\"\n  | \"meter\"\n  | \"nav-bar\"\n  | \"number-ticker\"\n  | \"onboarding\"\n  | \"otp-input\"\n  | \"page\"\n  | \"page-header\"\n  | \"page-hero\"\n  | \"pagination\"\n  | \"permission-prompt\"\n  | \"photo-grid\"\n  | \"pointer-light\"\n  | \"popover\"\n  | \"pricing-page\"\n  | \"product-page\"\n  | \"profile-card\"\n  | \"progress\"\n  | \"promise-card\"\n  | \"pull-to-refresh\"\n  | \"radio-group\"\n  | \"recipes\"\n  | \"screen\"\n  | \"scroll-stage\"\n  | \"search-field\"\n  | \"section-backdrop\"\n  | \"segmented\"\n  | \"separator\"\n  | \"settings-layout\"\n  | \"showcase\"\n  | \"site-footer\"\n  | \"sites\"\n  | \"skeleton\"\n  | \"skip-link\"\n  | \"slider\"\n  | \"slot\"\n  | \"spinner\"\n  | \"split-view\"\n  | \"splash-handoff\"\n  | \"stage-banner\"\n  | \"stat\"\n  | \"status-page\"\n  | \"step-progress\"\n  | \"stepper\"\n  | \"swipe-deck\"\n  | \"swipeable-row\"\n  | \"switch\"\n  | \"tab-bar\"\n  | \"tabs\"\n  | \"tag-input\"\n  | \"tag-selector\"\n  | \"terminal-replay\"\n  | \"theme\"\n  | \"toast\"\n  | \"toc\"\n  | \"tooltip\"\n  | \"tree-view\"\n  | \"txt\"\n  | \"verified-badge\"\n  | \"vertical-video\"\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/**\n * `stable`: its API only changes in a major. `beta`: it may still change in a minor. `deprecated`: no product uses it and\n * no work plans to — it still works, says what replaces it, and goes in the major named by `deprecated.removedIn`.\n */\nexport type Status = \"stable\" | \"beta\" | \"deprecated\";\n\n/** What a deprecated component says (required when `status` is `deprecated`, absent otherwise). */\nexport interface Deprecation {\n  /** The version that deprecated it (`3.6.0`). */\n  readonly since: string;\n  /** The major that removes it (`4.0.0`). */\n  readonly removedIn: string;\n  /** What replaces it, when a component does. */\n  readonly use?: ComponentName;\n  /** Why it goes: no product uses it, no planned work needs it. */\n  readonly reason: string;\n}\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/** Why a reader needs a template: the seven intents the templates are grouped by (sidebar sub-headings, catalogue filter). */\nexport type TemplatePurpose = \"convince\" | \"explain\" | \"show\" | \"act\" | \"operate\" | \"converse\" | \"recover\";\n\n/** The groups of templates, in reading order: the title, and the one line that says when to come to that group. */\nexport const templatePurposes = {\n  convince: { title: \"Convince\", useWhen: \"You come here when a visitor must decide: a landing, a product, a price, a comparison, a proof.\" },\n  explain: { title: \"Explain\", useWhen: \"You come here when a reader must understand: how it works, a documentation hub or article, a changelog, a FAQ, a policy.\" },\n  show: { title: \"Show\", useWhen: \"You come here when the work itself is the argument: a gallery, a story, a case study, an object and its details.\" },\n  act: { title: \"Act\", useWhen: \"You come here when a person must do something once: reach the team, sign in or up, set up, pay.\" },\n  operate: { title: \"Operate\", useWhen: \"You come here when a person works every day: a dashboard, a console with a table, settings, an app shell.\" },\n  converse: { title: \"Converse\", useWhen: \"You come here when people talk: an inbox, a chat, comments, a notifications centre.\" },\n  recover: { title: \"Recover\", useWhen: \"You come here when the way is blocked: an empty list, an error, a missing page, maintenance, a product still being built.\" },\n} as const satisfies Record<TemplatePurpose, { readonly title: string; readonly useWhen: string }>;\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 */\ninterface ExampleBase {\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/** A plain example, or a template: a whole screen with its intent (`purpose`) and the user goal its layout serves (`why`). */\nexport type Example =\n  | (ExampleBase & { readonly template?: false; readonly purpose?: undefined; readonly why?: undefined })\n  | (ExampleBase & {\n      /**\n       * A template: a whole screen of a product composed from the platform (a layout and its blocks, real words, its\n       * phone version thought out), copied as a starting point — at most 160 lines, listed on ui.krizaka.com/templates.\n       */\n      readonly template: true;\n      /** The intent that groups it: why you need this block. */\n      readonly purpose: TemplatePurpose;\n      /** Why this layout: the user goal it serves, in one sentence. */\n      readonly why: 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  /** Required for, and only for, a `deprecated` component. */\n  readonly deprecated?: Deprecation;\n  readonly category: Category;\n  /** Must match the sides below: `both` ⇔ `web` and `native`. */\n  readonly platforms: Platform;\n  /** When to reach for it: concrete situations, one per item. */\n  readonly whenToUse: readonly string[];\n  /** When not to — and what to use instead (`use`), when another component is the answer. */\n  readonly whenNotToUse: readonly { readonly when: string; readonly use?: ComponentName }[];\n  /** How to use it well: wording, placement, composition. */\n  readonly bestPractices: readonly string[];\n  readonly accessibility: {\n    /** The keyboard, when it does more than Tab and Enter. */\n    readonly keyboard: readonly KeyboardInteraction[];\n    /** Roles, names and announcements: what the component does, what the app must provide. */\n    readonly notes: readonly string[];\n  };\n  /** The components a reader of this page should know about. */\n  readonly related: readonly ComponentName[];\n  readonly web?: PlatformDocs;\n  readonly native?: NativeDocs;\n}\n"
+    }
+  ],
+  "dependencies": [
+    "tailwind-variants@^3.3.1"
+  ],
+  "registryDependencies": [],
+  "demo": {
+    "path": "examples/document-viewer/highlights.tsx",
+    "content": "\"use client\";\n\nimport { DocumentViewer } from \"@krizaka/ui/document-viewer\";\nimport * as React from \"react\";\n\nconst PDF = \"JVBERi0xLjQKMSAwIG9iago8PCAvVHlwZSAvQ2F0YWxvZyAvUGFnZXMgMiAwIFIgPj4KZW5kb2JqCjIgMCBvYmoKPDwgL1R5cGUgL1BhZ2VzIC9LaWRzIFszIDAgUl0gL0NvdW50IDEgPj4KZW5kb2JqCjMgMCBvYmoKPDwgL1R5cGUgL1BhZ2UgL1BhcmVudCAyIDAgUiAvTWVkaWFCb3ggWzAgMCA2MTIgNzkyXSAvQ29udGVudHMgNCAwIFIgL1Jlc291cmNlcyA8PCAvRm9udCA8PCAvRjEgNSAwIFIgPj4gPj4gPj4KZW5kb2JqCjQgMCBvYmoKPDwgL0xlbmd0aCAyMDkgPj4Kc3RyZWFtCkJUIC9GMSAxNCBUZiA3MiA3MDAgVGQgKEJBSUwgUkVTSURFTlRJRUwpIFRqIEVUCkJUIC9GMSAxMSBUZiA3MiA2NzAgVGQgKExlIGxvY2F0ZXVyIHBldXQgYXVnbWVudGVyIGxlIGxveWVyIGEgdG91dCBtb21lbnQuKSBUaiBFVApCVCAvRjEgMTEgVGYgNzIgNjUwIFRkIChMZSBkZXBvdCBkZSBnYXJhbnRpZSBlc3QgZGUgZGV1eCBtb2lzIGRlIGxveWVyLikgVGogRVQKZW5kc3RyZWFtCmVuZG9iago1IDAgb2JqCjw8IC9UeXBlIC9Gb250IC9TdWJ0eXBlIC9UeXBlMSAvQmFzZUZvbnQgL0hlbHZldGljYSA+PgplbmRvYmoKeHJlZgowIDYKMDAwMDAwMDAwMCA2NTUzNSBmIAowMDAwMDAwMDA5IDAwMDAwIG4gCjAwMDAwMDAwNTggMDAwMDAgbiAKMDAwMDAwMDExNSAwMDAwMCBuIAowMDAwMDAwMjQxIDAwMDAwIG4gCjAwMDAwMDA1MDAgMDAwMDAgbiAKdHJhaWxlcgo8PCAvU2l6ZSA2IC9Sb290IDEgMCBSID4+CnN0YXJ0eHJlZgo1NzAKJSVFT0YK\";\nconst quotes = [\n  { id: \"r1\", quote: \"Le locateur peut augmenter le loyer à tout moment.\", label: \"Rent increase\" },\n  { id: \"r2\", quote: \"Le dépôt de garantie est de deux mois de loyer.\", label: \"Deposit\" },\n];\n// pdf.js is the app's: `loadPdfjs={() => import(\"pdfjs-dist\")}` and a worker served from its own origin. Here, from a CDN.\nconst CDN = \"https://cdn.jsdelivr.net/npm/pdfjs-dist@5.4.149/build/\";\nconst loadPdfjs = () => import(/* webpackIgnore: true */ /* turbopackIgnore: true */ `${CDN}pdf.min.mjs`) as never;\n\n// Pick a passage in your own list: the viewer scrolls to it and lights it where it sits in the page.\nexport default function DocumentViewerHighlights() {\n  const [active, setActive] = React.useState<string | null>(\"r1\");\n  return (\n    <div className=\"flex flex-col gap-3\">\n      <div className=\"flex gap-2\">\n        {quotes.map((q) => (\n          <button key={q.id} type=\"button\" aria-pressed={active === q.id} className=\"rounded-md border border-border-default px-3 py-1 text-sm aria-pressed:bg-surface-3\" onClick={() => setActive(q.id)}>\n            {q.label}\n          </button>\n        ))}\n      </div>\n      <DocumentViewer src={Uint8Array.from(atob(PDF), (c) => c.charCodeAt(0))} loadPdfjs={loadPdfjs} workerSrc={`${CDN}pdf.worker.min.mjs`} highlights={quotes} activeId={active} onActiveChange={setActive} />\n    </div>\n  );\n}\n"
+  },
+  "props": [
+    {
+      "component": "DocumentViewer",
+      "description": "A PDF with its passages lit — see the file's header. Client.",
+      "props": [
+        {
+          "name": "loadPdfjs",
+          "type": "() => Promise<PdfjsModule>",
+          "default": null,
+          "description": "Loads pdf.js: `() => import(\"pdfjs-dist\")`. An optional peer, never in a bundle without a document.",
+          "required": true
+        },
+        {
+          "name": "src",
+          "type": "string | Uint8Array<ArrayBufferLike>",
+          "default": null,
+          "description": "The PDF: an address (same origin or CORS) or its bytes.",
+          "required": true
+        },
+        {
+          "name": "workerSrc",
+          "type": "string",
+          "default": null,
+          "description": "The address of pdf.js's worker (`new URL(\"pdfjs-dist/build/pdf.worker.min.mjs\", import.meta.url).toString()`).",
+          "required": true
+        },
+        {
+          "name": "activeId",
+          "type": "string | null",
+          "default": "null",
+          "description": "The passage in focus: the viewer scrolls to it.",
+          "required": false
+        },
+        {
+          "name": "highlights",
+          "type": "readonly DocumentHighlight[]",
+          "default": "[]",
+          "description": "The passages to light.",
+          "required": false
+        },
+        {
+          "name": "labels",
+          "type": "Partial<DocumentViewerLabels>",
+          "default": null,
+          "description": "The words of the viewer, translated (English by default).",
+          "required": false
+        },
+        {
+          "name": "onActiveChange",
+          "type": "((id: string | null) => void)",
+          "default": null,
+          "description": "A box was clicked (the id) or the focus was released (`null`).",
+          "required": false
+        },
+        {
+          "name": "onLocate",
+          "type": "((found: Record<string, Located | null>) => void)",
+          "default": null,
+          "description": "Where each passage was found (`null`: nowhere) — once the text layer is read, and again if `highlights` change.",
+          "required": false
+        }
+      ]
+    }
+  ]
+}

package/registry/dropdown-menu.json

@@ -127,7 +127,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 ui.krizaka.com (apps/site) renders as\n// ui.krizaka.com/components/<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  | \"activity-feed\"\n  | \"action-sheet\"\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  | \"chat\"\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  | \"description-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  | \"fab\"\n  | \"field\"\n  | \"file-upload\"\n  | \"filter-bar\"\n  | \"form\"\n  | \"gallery-page\"\n  | \"glow-card\"\n  | \"goal-gauge\"\n  | \"header\"\n  | \"how-it-works-page\"\n  | \"image-cropper\"\n  | \"image-viewer\"\n  | \"iso\"\n  | \"kanban\"\n  | \"kbd\"\n  | \"landing-page\"\n  | \"landscape\"\n  | \"legal-page\"\n  | \"link-card\"\n  | \"list\"\n  | \"loader\"\n  | \"map\"\n  | \"markdown\"\n  | \"longform-page\"\n  | \"marketing-layout\"\n  | \"marquee\"\n  | \"mascot-quote\"\n  | \"mascot-state\"\n  | \"mascots\"\n  | \"match-dialog\"\n  | \"media-capture\"\n  | \"media-picker\"\n  | \"meter\"\n  | \"nav-bar\"\n  | \"number-ticker\"\n  | \"onboarding\"\n  | \"otp-input\"\n  | \"page\"\n  | \"page-header\"\n  | \"page-hero\"\n  | \"pagination\"\n  | \"permission-prompt\"\n  | \"photo-grid\"\n  | \"pointer-light\"\n  | \"popover\"\n  | \"pricing-page\"\n  | \"product-page\"\n  | \"profile-card\"\n  | \"progress\"\n  | \"promise-card\"\n  | \"pull-to-refresh\"\n  | \"radio-group\"\n  | \"recipes\"\n  | \"screen\"\n  | \"scroll-stage\"\n  | \"search-field\"\n  | \"section-backdrop\"\n  | \"segmented\"\n  | \"separator\"\n  | \"settings-layout\"\n  | \"showcase\"\n  | \"site-footer\"\n  | \"sites\"\n  | \"skeleton\"\n  | \"skip-link\"\n  | \"slider\"\n  | \"slot\"\n  | \"spinner\"\n  | \"split-view\"\n  | \"splash-handoff\"\n  | \"stage-banner\"\n  | \"stat\"\n  | \"status-page\"\n  | \"step-progress\"\n  | \"stepper\"\n  | \"swipe-deck\"\n  | \"swipeable-row\"\n  | \"switch\"\n  | \"tab-bar\"\n  | \"tabs\"\n  | \"tag-input\"\n  | \"tag-selector\"\n  | \"terminal-replay\"\n  | \"theme\"\n  | \"toast\"\n  | \"toc\"\n  | \"tooltip\"\n  | \"tree-view\"\n  | \"txt\"\n  | \"verified-badge\"\n  | \"vertical-video\"\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/**\n * `stable`: its API only changes in a major. `beta`: it may still change in a minor. `deprecated`: no product uses it and\n * no work plans to — it still works, says what replaces it, and goes in the major named by `deprecated.removedIn`.\n */\nexport type Status = \"stable\" | \"beta\" | \"deprecated\";\n\n/** What a deprecated component says (required when `status` is `deprecated`, absent otherwise). */\nexport interface Deprecation {\n  /** The version that deprecated it (`3.6.0`). */\n  readonly since: string;\n  /** The major that removes it (`4.0.0`). */\n  readonly removedIn: string;\n  /** What replaces it, when a component does. */\n  readonly use?: ComponentName;\n  /** Why it goes: no product uses it, no planned work needs it. */\n  readonly reason: string;\n}\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/** Why a reader needs a template: the seven intents the templates are grouped by (sidebar sub-headings, catalogue filter). */\nexport type TemplatePurpose = \"convince\" | \"explain\" | \"show\" | \"act\" | \"operate\" | \"converse\" | \"recover\";\n\n/** The groups of templates, in reading order: the title, and the one line that says when to come to that group. */\nexport const templatePurposes = {\n  convince: { title: \"Convince\", useWhen: \"You come here when a visitor must decide: a landing, a product, a price, a comparison, a proof.\" },\n  explain: { title: \"Explain\", useWhen: \"You come here when a reader must understand: how it works, a documentation hub or article, a changelog, a FAQ, a policy.\" },\n  show: { title: \"Show\", useWhen: \"You come here when the work itself is the argument: a gallery, a story, a case study, an object and its details.\" },\n  act: { title: \"Act\", useWhen: \"You come here when a person must do something once: reach the team, sign in or up, set up, pay.\" },\n  operate: { title: \"Operate\", useWhen: \"You come here when a person works every day: a dashboard, a console with a table, settings, an app shell.\" },\n  converse: { title: \"Converse\", useWhen: \"You come here when people talk: an inbox, a chat, comments, a notifications centre.\" },\n  recover: { title: \"Recover\", useWhen: \"You come here when the way is blocked: an empty list, an error, a missing page, maintenance, a product still being built.\" },\n} as const satisfies Record<TemplatePurpose, { readonly title: string; readonly useWhen: string }>;\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 */\ninterface ExampleBase {\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/** A plain example, or a template: a whole screen with its intent (`purpose`) and the user goal its layout serves (`why`). */\nexport type Example =\n  | (ExampleBase & { readonly template?: false; readonly purpose?: undefined; readonly why?: undefined })\n  | (ExampleBase & {\n      /**\n       * A template: a whole screen of a product composed from the platform (a layout and its blocks, real words, its\n       * phone version thought out), copied as a starting point — at most 160 lines, listed on ui.krizaka.com/templates.\n       */\n      readonly template: true;\n      /** The intent that groups it: why you need this block. */\n      readonly purpose: TemplatePurpose;\n      /** Why this layout: the user goal it serves, in one sentence. */\n      readonly why: 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  /** Required for, and only for, a `deprecated` component. */\n  readonly deprecated?: Deprecation;\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 ui.krizaka.com (apps/site) renders as\n// ui.krizaka.com/components/<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  | \"activity-feed\"\n  | \"action-sheet\"\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  | \"chat\"\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  | \"description-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  | \"fab\"\n  | \"field\"\n  | \"file-upload\"\n  | \"filter-bar\"\n  | \"form\"\n  | \"gallery-page\"\n  | \"glow-card\"\n  | \"goal-gauge\"\n  | \"header\"\n  | \"how-it-works-page\"\n  | \"document-viewer\"\n  | \"image-cropper\"\n  | \"image-viewer\"\n  | \"iso\"\n  | \"kanban\"\n  | \"kbd\"\n  | \"landing-page\"\n  | \"landscape\"\n  | \"legal-page\"\n  | \"link-card\"\n  | \"list\"\n  | \"loader\"\n  | \"map\"\n  | \"markdown\"\n  | \"longform-page\"\n  | \"marketing-layout\"\n  | \"marquee\"\n  | \"mascot-quote\"\n  | \"mascot-state\"\n  | \"mascots\"\n  | \"match-dialog\"\n  | \"media-capture\"\n  | \"media-picker\"\n  | \"meter\"\n  | \"nav-bar\"\n  | \"number-ticker\"\n  | \"onboarding\"\n  | \"otp-input\"\n  | \"page\"\n  | \"page-header\"\n  | \"page-hero\"\n  | \"pagination\"\n  | \"permission-prompt\"\n  | \"photo-grid\"\n  | \"pointer-light\"\n  | \"popover\"\n  | \"pricing-page\"\n  | \"product-page\"\n  | \"profile-card\"\n  | \"progress\"\n  | \"promise-card\"\n  | \"pull-to-refresh\"\n  | \"radio-group\"\n  | \"recipes\"\n  | \"screen\"\n  | \"scroll-stage\"\n  | \"search-field\"\n  | \"section-backdrop\"\n  | \"segmented\"\n  | \"separator\"\n  | \"settings-layout\"\n  | \"showcase\"\n  | \"site-footer\"\n  | \"sites\"\n  | \"skeleton\"\n  | \"skip-link\"\n  | \"slider\"\n  | \"slot\"\n  | \"spinner\"\n  | \"split-view\"\n  | \"splash-handoff\"\n  | \"stage-banner\"\n  | \"stat\"\n  | \"status-page\"\n  | \"step-progress\"\n  | \"stepper\"\n  | \"swipe-deck\"\n  | \"swipeable-row\"\n  | \"switch\"\n  | \"tab-bar\"\n  | \"tabs\"\n  | \"tag-input\"\n  | \"tag-selector\"\n  | \"terminal-replay\"\n  | \"theme\"\n  | \"toast\"\n  | \"toc\"\n  | \"tooltip\"\n  | \"tree-view\"\n  | \"txt\"\n  | \"verified-badge\"\n  | \"vertical-video\"\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/**\n * `stable`: its API only changes in a major. `beta`: it may still change in a minor. `deprecated`: no product uses it and\n * no work plans to — it still works, says what replaces it, and goes in the major named by `deprecated.removedIn`.\n */\nexport type Status = \"stable\" | \"beta\" | \"deprecated\";\n\n/** What a deprecated component says (required when `status` is `deprecated`, absent otherwise). */\nexport interface Deprecation {\n  /** The version that deprecated it (`3.6.0`). */\n  readonly since: string;\n  /** The major that removes it (`4.0.0`). */\n  readonly removedIn: string;\n  /** What replaces it, when a component does. */\n  readonly use?: ComponentName;\n  /** Why it goes: no product uses it, no planned work needs it. */\n  readonly reason: string;\n}\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/** Why a reader needs a template: the seven intents the templates are grouped by (sidebar sub-headings, catalogue filter). */\nexport type TemplatePurpose = \"convince\" | \"explain\" | \"show\" | \"act\" | \"operate\" | \"converse\" | \"recover\";\n\n/** The groups of templates, in reading order: the title, and the one line that says when to come to that group. */\nexport const templatePurposes = {\n  convince: { title: \"Convince\", useWhen: \"You come here when a visitor must decide: a landing, a product, a price, a comparison, a proof.\" },\n  explain: { title: \"Explain\", useWhen: \"You come here when a reader must understand: how it works, a documentation hub or article, a changelog, a FAQ, a policy.\" },\n  show: { title: \"Show\", useWhen: \"You come here when the work itself is the argument: a gallery, a story, a case study, an object and its details.\" },\n  act: { title: \"Act\", useWhen: \"You come here when a person must do something once: reach the team, sign in or up, set up, pay.\" },\n  operate: { title: \"Operate\", useWhen: \"You come here when a person works every day: a dashboard, a console with a table, settings, an app shell.\" },\n  converse: { title: \"Converse\", useWhen: \"You come here when people talk: an inbox, a chat, comments, a notifications centre.\" },\n  recover: { title: \"Recover\", useWhen: \"You come here when the way is blocked: an empty list, an error, a missing page, maintenance, a product still being built.\" },\n} as const satisfies Record<TemplatePurpose, { readonly title: string; readonly useWhen: string }>;\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 */\ninterface ExampleBase {\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/** A plain example, or a template: a whole screen with its intent (`purpose`) and the user goal its layout serves (`why`). */\nexport type Example =\n  | (ExampleBase & { readonly template?: false; readonly purpose?: undefined; readonly why?: undefined })\n  | (ExampleBase & {\n      /**\n       * A template: a whole screen of a product composed from the platform (a layout and its blocks, real words, its\n       * phone version thought out), copied as a starting point — at most 160 lines, listed on ui.krizaka.com/templates.\n       */\n      readonly template: true;\n      /** The intent that groups it: why you need this block. */\n      readonly purpose: TemplatePurpose;\n      /** Why this layout: the user goal it serves, in one sentence. */\n      readonly why: 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  /** Required for, and only for, a `deprecated` component. */\n  readonly deprecated?: Deprecation;\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/empty-state.json

@@ -188,7 +188,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 ui.krizaka.com (apps/site) renders as\n// ui.krizaka.com/components/<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  | \"activity-feed\"\n  | \"action-sheet\"\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  | \"chat\"\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  | \"description-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  | \"fab\"\n  | \"field\"\n  | \"file-upload\"\n  | \"filter-bar\"\n  | \"form\"\n  | \"gallery-page\"\n  | \"glow-card\"\n  | \"goal-gauge\"\n  | \"header\"\n  | \"how-it-works-page\"\n  | \"image-cropper\"\n  | \"image-viewer\"\n  | \"iso\"\n  | \"kanban\"\n  | \"kbd\"\n  | \"landing-page\"\n  | \"landscape\"\n  | \"legal-page\"\n  | \"link-card\"\n  | \"list\"\n  | \"loader\"\n  | \"map\"\n  | \"markdown\"\n  | \"longform-page\"\n  | \"marketing-layout\"\n  | \"marquee\"\n  | \"mascot-quote\"\n  | \"mascot-state\"\n  | \"mascots\"\n  | \"match-dialog\"\n  | \"media-capture\"\n  | \"media-picker\"\n  | \"meter\"\n  | \"nav-bar\"\n  | \"number-ticker\"\n  | \"onboarding\"\n  | \"otp-input\"\n  | \"page\"\n  | \"page-header\"\n  | \"page-hero\"\n  | \"pagination\"\n  | \"permission-prompt\"\n  | \"photo-grid\"\n  | \"pointer-light\"\n  | \"popover\"\n  | \"pricing-page\"\n  | \"product-page\"\n  | \"profile-card\"\n  | \"progress\"\n  | \"promise-card\"\n  | \"pull-to-refresh\"\n  | \"radio-group\"\n  | \"recipes\"\n  | \"screen\"\n  | \"scroll-stage\"\n  | \"search-field\"\n  | \"section-backdrop\"\n  | \"segmented\"\n  | \"separator\"\n  | \"settings-layout\"\n  | \"showcase\"\n  | \"site-footer\"\n  | \"sites\"\n  | \"skeleton\"\n  | \"skip-link\"\n  | \"slider\"\n  | \"slot\"\n  | \"spinner\"\n  | \"split-view\"\n  | \"splash-handoff\"\n  | \"stage-banner\"\n  | \"stat\"\n  | \"status-page\"\n  | \"step-progress\"\n  | \"stepper\"\n  | \"swipe-deck\"\n  | \"swipeable-row\"\n  | \"switch\"\n  | \"tab-bar\"\n  | \"tabs\"\n  | \"tag-input\"\n  | \"tag-selector\"\n  | \"terminal-replay\"\n  | \"theme\"\n  | \"toast\"\n  | \"toc\"\n  | \"tooltip\"\n  | \"tree-view\"\n  | \"txt\"\n  | \"verified-badge\"\n  | \"vertical-video\"\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/**\n * `stable`: its API only changes in a major. `beta`: it may still change in a minor. `deprecated`: no product uses it and\n * no work plans to — it still works, says what replaces it, and goes in the major named by `deprecated.removedIn`.\n */\nexport type Status = \"stable\" | \"beta\" | \"deprecated\";\n\n/** What a deprecated component says (required when `status` is `deprecated`, absent otherwise). */\nexport interface Deprecation {\n  /** The version that deprecated it (`3.6.0`). */\n  readonly since: string;\n  /** The major that removes it (`4.0.0`). */\n  readonly removedIn: string;\n  /** What replaces it, when a component does. */\n  readonly use?: ComponentName;\n  /** Why it goes: no product uses it, no planned work needs it. */\n  readonly reason: string;\n}\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/** Why a reader needs a template: the seven intents the templates are grouped by (sidebar sub-headings, catalogue filter). */\nexport type TemplatePurpose = \"convince\" | \"explain\" | \"show\" | \"act\" | \"operate\" | \"converse\" | \"recover\";\n\n/** The groups of templates, in reading order: the title, and the one line that says when to come to that group. */\nexport const templatePurposes = {\n  convince: { title: \"Convince\", useWhen: \"You come here when a visitor must decide: a landing, a product, a price, a comparison, a proof.\" },\n  explain: { title: \"Explain\", useWhen: \"You come here when a reader must understand: how it works, a documentation hub or article, a changelog, a FAQ, a policy.\" },\n  show: { title: \"Show\", useWhen: \"You come here when the work itself is the argument: a gallery, a story, a case study, an object and its details.\" },\n  act: { title: \"Act\", useWhen: \"You come here when a person must do something once: reach the team, sign in or up, set up, pay.\" },\n  operate: { title: \"Operate\", useWhen: \"You come here when a person works every day: a dashboard, a console with a table, settings, an app shell.\" },\n  converse: { title: \"Converse\", useWhen: \"You come here when people talk: an inbox, a chat, comments, a notifications centre.\" },\n  recover: { title: \"Recover\", useWhen: \"You come here when the way is blocked: an empty list, an error, a missing page, maintenance, a product still being built.\" },\n} as const satisfies Record<TemplatePurpose, { readonly title: string; readonly useWhen: string }>;\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 */\ninterface ExampleBase {\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/** A plain example, or a template: a whole screen with its intent (`purpose`) and the user goal its layout serves (`why`). */\nexport type Example =\n  | (ExampleBase & { readonly template?: false; readonly purpose?: undefined; readonly why?: undefined })\n  | (ExampleBase & {\n      /**\n       * A template: a whole screen of a product composed from the platform (a layout and its blocks, real words, its\n       * phone version thought out), copied as a starting point — at most 160 lines, listed on ui.krizaka.com/templates.\n       */\n      readonly template: true;\n      /** The intent that groups it: why you need this block. */\n      readonly purpose: TemplatePurpose;\n      /** Why this layout: the user goal it serves, in one sentence. */\n      readonly why: 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  /** Required for, and only for, a `deprecated` component. */\n  readonly deprecated?: Deprecation;\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 ui.krizaka.com (apps/site) renders as\n// ui.krizaka.com/components/<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  | \"activity-feed\"\n  | \"action-sheet\"\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  | \"chat\"\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  | \"description-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  | \"fab\"\n  | \"field\"\n  | \"file-upload\"\n  | \"filter-bar\"\n  | \"form\"\n  | \"gallery-page\"\n  | \"glow-card\"\n  | \"goal-gauge\"\n  | \"header\"\n  | \"how-it-works-page\"\n  | \"document-viewer\"\n  | \"image-cropper\"\n  | \"image-viewer\"\n  | \"iso\"\n  | \"kanban\"\n  | \"kbd\"\n  | \"landing-page\"\n  | \"landscape\"\n  | \"legal-page\"\n  | \"link-card\"\n  | \"list\"\n  | \"loader\"\n  | \"map\"\n  | \"markdown\"\n  | \"longform-page\"\n  | \"marketing-layout\"\n  | \"marquee\"\n  | \"mascot-quote\"\n  | \"mascot-state\"\n  | \"mascots\"\n  | \"match-dialog\"\n  | \"media-capture\"\n  | \"media-picker\"\n  | \"meter\"\n  | \"nav-bar\"\n  | \"number-ticker\"\n  | \"onboarding\"\n  | \"otp-input\"\n  | \"page\"\n  | \"page-header\"\n  | \"page-hero\"\n  | \"pagination\"\n  | \"permission-prompt\"\n  | \"photo-grid\"\n  | \"pointer-light\"\n  | \"popover\"\n  | \"pricing-page\"\n  | \"product-page\"\n  | \"profile-card\"\n  | \"progress\"\n  | \"promise-card\"\n  | \"pull-to-refresh\"\n  | \"radio-group\"\n  | \"recipes\"\n  | \"screen\"\n  | \"scroll-stage\"\n  | \"search-field\"\n  | \"section-backdrop\"\n  | \"segmented\"\n  | \"separator\"\n  | \"settings-layout\"\n  | \"showcase\"\n  | \"site-footer\"\n  | \"sites\"\n  | \"skeleton\"\n  | \"skip-link\"\n  | \"slider\"\n  | \"slot\"\n  | \"spinner\"\n  | \"split-view\"\n  | \"splash-handoff\"\n  | \"stage-banner\"\n  | \"stat\"\n  | \"status-page\"\n  | \"step-progress\"\n  | \"stepper\"\n  | \"swipe-deck\"\n  | \"swipeable-row\"\n  | \"switch\"\n  | \"tab-bar\"\n  | \"tabs\"\n  | \"tag-input\"\n  | \"tag-selector\"\n  | \"terminal-replay\"\n  | \"theme\"\n  | \"toast\"\n  | \"toc\"\n  | \"tooltip\"\n  | \"tree-view\"\n  | \"txt\"\n  | \"verified-badge\"\n  | \"vertical-video\"\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/**\n * `stable`: its API only changes in a major. `beta`: it may still change in a minor. `deprecated`: no product uses it and\n * no work plans to — it still works, says what replaces it, and goes in the major named by `deprecated.removedIn`.\n */\nexport type Status = \"stable\" | \"beta\" | \"deprecated\";\n\n/** What a deprecated component says (required when `status` is `deprecated`, absent otherwise). */\nexport interface Deprecation {\n  /** The version that deprecated it (`3.6.0`). */\n  readonly since: string;\n  /** The major that removes it (`4.0.0`). */\n  readonly removedIn: string;\n  /** What replaces it, when a component does. */\n  readonly use?: ComponentName;\n  /** Why it goes: no product uses it, no planned work needs it. */\n  readonly reason: string;\n}\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/** Why a reader needs a template: the seven intents the templates are grouped by (sidebar sub-headings, catalogue filter). */\nexport type TemplatePurpose = \"convince\" | \"explain\" | \"show\" | \"act\" | \"operate\" | \"converse\" | \"recover\";\n\n/** The groups of templates, in reading order: the title, and the one line that says when to come to that group. */\nexport const templatePurposes = {\n  convince: { title: \"Convince\", useWhen: \"You come here when a visitor must decide: a landing, a product, a price, a comparison, a proof.\" },\n  explain: { title: \"Explain\", useWhen: \"You come here when a reader must understand: how it works, a documentation hub or article, a changelog, a FAQ, a policy.\" },\n  show: { title: \"Show\", useWhen: \"You come here when the work itself is the argument: a gallery, a story, a case study, an object and its details.\" },\n  act: { title: \"Act\", useWhen: \"You come here when a person must do something once: reach the team, sign in or up, set up, pay.\" },\n  operate: { title: \"Operate\", useWhen: \"You come here when a person works every day: a dashboard, a console with a table, settings, an app shell.\" },\n  converse: { title: \"Converse\", useWhen: \"You come here when people talk: an inbox, a chat, comments, a notifications centre.\" },\n  recover: { title: \"Recover\", useWhen: \"You come here when the way is blocked: an empty list, an error, a missing page, maintenance, a product still being built.\" },\n} as const satisfies Record<TemplatePurpose, { readonly title: string; readonly useWhen: string }>;\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 */\ninterface ExampleBase {\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/** A plain example, or a template: a whole screen with its intent (`purpose`) and the user goal its layout serves (`why`). */\nexport type Example =\n  | (ExampleBase & { readonly template?: false; readonly purpose?: undefined; readonly why?: undefined })\n  | (ExampleBase & {\n      /**\n       * A template: a whole screen of a product composed from the platform (a layout and its blocks, real words, its\n       * phone version thought out), copied as a starting point — at most 160 lines, listed on ui.krizaka.com/templates.\n       */\n      readonly template: true;\n      /** The intent that groups it: why you need this block. */\n      readonly purpose: TemplatePurpose;\n      /** Why this layout: the user goal it serves, in one sentence. */\n      readonly why: 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  /** Required for, and only for, a `deprecated` component. */\n  readonly deprecated?: Deprecation;\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/error-page.json

@@ -122,7 +122,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 ui.krizaka.com (apps/site) renders as\n// ui.krizaka.com/components/<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  | \"activity-feed\"\n  | \"action-sheet\"\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  | \"chat\"\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  | \"description-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  | \"fab\"\n  | \"field\"\n  | \"file-upload\"\n  | \"filter-bar\"\n  | \"form\"\n  | \"gallery-page\"\n  | \"glow-card\"\n  | \"goal-gauge\"\n  | \"header\"\n  | \"how-it-works-page\"\n  | \"image-cropper\"\n  | \"image-viewer\"\n  | \"iso\"\n  | \"kanban\"\n  | \"kbd\"\n  | \"landing-page\"\n  | \"landscape\"\n  | \"legal-page\"\n  | \"link-card\"\n  | \"list\"\n  | \"loader\"\n  | \"map\"\n  | \"markdown\"\n  | \"longform-page\"\n  | \"marketing-layout\"\n  | \"marquee\"\n  | \"mascot-quote\"\n  | \"mascot-state\"\n  | \"mascots\"\n  | \"match-dialog\"\n  | \"media-capture\"\n  | \"media-picker\"\n  | \"meter\"\n  | \"nav-bar\"\n  | \"number-ticker\"\n  | \"onboarding\"\n  | \"otp-input\"\n  | \"page\"\n  | \"page-header\"\n  | \"page-hero\"\n  | \"pagination\"\n  | \"permission-prompt\"\n  | \"photo-grid\"\n  | \"pointer-light\"\n  | \"popover\"\n  | \"pricing-page\"\n  | \"product-page\"\n  | \"profile-card\"\n  | \"progress\"\n  | \"promise-card\"\n  | \"pull-to-refresh\"\n  | \"radio-group\"\n  | \"recipes\"\n  | \"screen\"\n  | \"scroll-stage\"\n  | \"search-field\"\n  | \"section-backdrop\"\n  | \"segmented\"\n  | \"separator\"\n  | \"settings-layout\"\n  | \"showcase\"\n  | \"site-footer\"\n  | \"sites\"\n  | \"skeleton\"\n  | \"skip-link\"\n  | \"slider\"\n  | \"slot\"\n  | \"spinner\"\n  | \"split-view\"\n  | \"splash-handoff\"\n  | \"stage-banner\"\n  | \"stat\"\n  | \"status-page\"\n  | \"step-progress\"\n  | \"stepper\"\n  | \"swipe-deck\"\n  | \"swipeable-row\"\n  | \"switch\"\n  | \"tab-bar\"\n  | \"tabs\"\n  | \"tag-input\"\n  | \"tag-selector\"\n  | \"terminal-replay\"\n  | \"theme\"\n  | \"toast\"\n  | \"toc\"\n  | \"tooltip\"\n  | \"tree-view\"\n  | \"txt\"\n  | \"verified-badge\"\n  | \"vertical-video\"\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/**\n * `stable`: its API only changes in a major. `beta`: it may still change in a minor. `deprecated`: no product uses it and\n * no work plans to — it still works, says what replaces it, and goes in the major named by `deprecated.removedIn`.\n */\nexport type Status = \"stable\" | \"beta\" | \"deprecated\";\n\n/** What a deprecated component says (required when `status` is `deprecated`, absent otherwise). */\nexport interface Deprecation {\n  /** The version that deprecated it (`3.6.0`). */\n  readonly since: string;\n  /** The major that removes it (`4.0.0`). */\n  readonly removedIn: string;\n  /** What replaces it, when a component does. */\n  readonly use?: ComponentName;\n  /** Why it goes: no product uses it, no planned work needs it. */\n  readonly reason: string;\n}\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/** Why a reader needs a template: the seven intents the templates are grouped by (sidebar sub-headings, catalogue filter). */\nexport type TemplatePurpose = \"convince\" | \"explain\" | \"show\" | \"act\" | \"operate\" | \"converse\" | \"recover\";\n\n/** The groups of templates, in reading order: the title, and the one line that says when to come to that group. */\nexport const templatePurposes = {\n  convince: { title: \"Convince\", useWhen: \"You come here when a visitor must decide: a landing, a product, a price, a comparison, a proof.\" },\n  explain: { title: \"Explain\", useWhen: \"You come here when a reader must understand: how it works, a documentation hub or article, a changelog, a FAQ, a policy.\" },\n  show: { title: \"Show\", useWhen: \"You come here when the work itself is the argument: a gallery, a story, a case study, an object and its details.\" },\n  act: { title: \"Act\", useWhen: \"You come here when a person must do something once: reach the team, sign in or up, set up, pay.\" },\n  operate: { title: \"Operate\", useWhen: \"You come here when a person works every day: a dashboard, a console with a table, settings, an app shell.\" },\n  converse: { title: \"Converse\", useWhen: \"You come here when people talk: an inbox, a chat, comments, a notifications centre.\" },\n  recover: { title: \"Recover\", useWhen: \"You come here when the way is blocked: an empty list, an error, a missing page, maintenance, a product still being built.\" },\n} as const satisfies Record<TemplatePurpose, { readonly title: string; readonly useWhen: string }>;\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 */\ninterface ExampleBase {\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/** A plain example, or a template: a whole screen with its intent (`purpose`) and the user goal its layout serves (`why`). */\nexport type Example =\n  | (ExampleBase & { readonly template?: false; readonly purpose?: undefined; readonly why?: undefined })\n  | (ExampleBase & {\n      /**\n       * A template: a whole screen of a product composed from the platform (a layout and its blocks, real words, its\n       * phone version thought out), copied as a starting point — at most 160 lines, listed on ui.krizaka.com/templates.\n       */\n      readonly template: true;\n      /** The intent that groups it: why you need this block. */\n      readonly purpose: TemplatePurpose;\n      /** Why this layout: the user goal it serves, in one sentence. */\n      readonly why: 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  /** Required for, and only for, a `deprecated` component. */\n  readonly deprecated?: Deprecation;\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 ui.krizaka.com (apps/site) renders as\n// ui.krizaka.com/components/<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  | \"activity-feed\"\n  | \"action-sheet\"\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  | \"chat\"\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  | \"description-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  | \"fab\"\n  | \"field\"\n  | \"file-upload\"\n  | \"filter-bar\"\n  | \"form\"\n  | \"gallery-page\"\n  | \"glow-card\"\n  | \"goal-gauge\"\n  | \"header\"\n  | \"how-it-works-page\"\n  | \"document-viewer\"\n  | \"image-cropper\"\n  | \"image-viewer\"\n  | \"iso\"\n  | \"kanban\"\n  | \"kbd\"\n  | \"landing-page\"\n  | \"landscape\"\n  | \"legal-page\"\n  | \"link-card\"\n  | \"list\"\n  | \"loader\"\n  | \"map\"\n  | \"markdown\"\n  | \"longform-page\"\n  | \"marketing-layout\"\n  | \"marquee\"\n  | \"mascot-quote\"\n  | \"mascot-state\"\n  | \"mascots\"\n  | \"match-dialog\"\n  | \"media-capture\"\n  | \"media-picker\"\n  | \"meter\"\n  | \"nav-bar\"\n  | \"number-ticker\"\n  | \"onboarding\"\n  | \"otp-input\"\n  | \"page\"\n  | \"page-header\"\n  | \"page-hero\"\n  | \"pagination\"\n  | \"permission-prompt\"\n  | \"photo-grid\"\n  | \"pointer-light\"\n  | \"popover\"\n  | \"pricing-page\"\n  | \"product-page\"\n  | \"profile-card\"\n  | \"progress\"\n  | \"promise-card\"\n  | \"pull-to-refresh\"\n  | \"radio-group\"\n  | \"recipes\"\n  | \"screen\"\n  | \"scroll-stage\"\n  | \"search-field\"\n  | \"section-backdrop\"\n  | \"segmented\"\n  | \"separator\"\n  | \"settings-layout\"\n  | \"showcase\"\n  | \"site-footer\"\n  | \"sites\"\n  | \"skeleton\"\n  | \"skip-link\"\n  | \"slider\"\n  | \"slot\"\n  | \"spinner\"\n  | \"split-view\"\n  | \"splash-handoff\"\n  | \"stage-banner\"\n  | \"stat\"\n  | \"status-page\"\n  | \"step-progress\"\n  | \"stepper\"\n  | \"swipe-deck\"\n  | \"swipeable-row\"\n  | \"switch\"\n  | \"tab-bar\"\n  | \"tabs\"\n  | \"tag-input\"\n  | \"tag-selector\"\n  | \"terminal-replay\"\n  | \"theme\"\n  | \"toast\"\n  | \"toc\"\n  | \"tooltip\"\n  | \"tree-view\"\n  | \"txt\"\n  | \"verified-badge\"\n  | \"vertical-video\"\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/**\n * `stable`: its API only changes in a major. `beta`: it may still change in a minor. `deprecated`: no product uses it and\n * no work plans to — it still works, says what replaces it, and goes in the major named by `deprecated.removedIn`.\n */\nexport type Status = \"stable\" | \"beta\" | \"deprecated\";\n\n/** What a deprecated component says (required when `status` is `deprecated`, absent otherwise). */\nexport interface Deprecation {\n  /** The version that deprecated it (`3.6.0`). */\n  readonly since: string;\n  /** The major that removes it (`4.0.0`). */\n  readonly removedIn: string;\n  /** What replaces it, when a component does. */\n  readonly use?: ComponentName;\n  /** Why it goes: no product uses it, no planned work needs it. */\n  readonly reason: string;\n}\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/** Why a reader needs a template: the seven intents the templates are grouped by (sidebar sub-headings, catalogue filter). */\nexport type TemplatePurpose = \"convince\" | \"explain\" | \"show\" | \"act\" | \"operate\" | \"converse\" | \"recover\";\n\n/** The groups of templates, in reading order: the title, and the one line that says when to come to that group. */\nexport const templatePurposes = {\n  convince: { title: \"Convince\", useWhen: \"You come here when a visitor must decide: a landing, a product, a price, a comparison, a proof.\" },\n  explain: { title: \"Explain\", useWhen: \"You come here when a reader must understand: how it works, a documentation hub or article, a changelog, a FAQ, a policy.\" },\n  show: { title: \"Show\", useWhen: \"You come here when the work itself is the argument: a gallery, a story, a case study, an object and its details.\" },\n  act: { title: \"Act\", useWhen: \"You come here when a person must do something once: reach the team, sign in or up, set up, pay.\" },\n  operate: { title: \"Operate\", useWhen: \"You come here when a person works every day: a dashboard, a console with a table, settings, an app shell.\" },\n  converse: { title: \"Converse\", useWhen: \"You come here when people talk: an inbox, a chat, comments, a notifications centre.\" },\n  recover: { title: \"Recover\", useWhen: \"You come here when the way is blocked: an empty list, an error, a missing page, maintenance, a product still being built.\" },\n} as const satisfies Record<TemplatePurpose, { readonly title: string; readonly useWhen: string }>;\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 */\ninterface ExampleBase {\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/** A plain example, or a template: a whole screen with its intent (`purpose`) and the user goal its layout serves (`why`). */\nexport type Example =\n  | (ExampleBase & { readonly template?: false; readonly purpose?: undefined; readonly why?: undefined })\n  | (ExampleBase & {\n      /**\n       * A template: a whole screen of a product composed from the platform (a layout and its blocks, real words, its\n       * phone version thought out), copied as a starting point — at most 160 lines, listed on ui.krizaka.com/templates.\n       */\n      readonly template: true;\n      /** The intent that groups it: why you need this block. */\n      readonly purpose: TemplatePurpose;\n      /** Why this layout: the user goal it serves, in one sentence. */\n      readonly why: 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  /** Required for, and only for, a `deprecated` component. */\n  readonly deprecated?: Deprecation;\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/examples/document-viewer/highlights.d.ts

@@ -0,0 +1,4 @@
+import type { ComponentType } from "react";
+/** A named example of the @krizaka/ui registry; `defaultOpen` opens what it opens (a dialog, a menu, toasts) at load. */
+declare const Example: ComponentType<{ defaultOpen?: boolean }>;
+export default Example;

package/registry/examples/document-viewer/highlights.js

@@ -0,0 +1,27 @@
+"use client";
+
+// registry/examples/document-viewer/highlights.tsx
+import { DocumentViewer } from "@krizaka/ui/document-viewer";
+import * as React from "react";
+import { jsx, jsxs } from "react/jsx-runtime";
+var PDF = "JVBERi0xLjQKMSAwIG9iago8PCAvVHlwZSAvQ2F0YWxvZyAvUGFnZXMgMiAwIFIgPj4KZW5kb2JqCjIgMCBvYmoKPDwgL1R5cGUgL1BhZ2VzIC9LaWRzIFszIDAgUl0gL0NvdW50IDEgPj4KZW5kb2JqCjMgMCBvYmoKPDwgL1R5cGUgL1BhZ2UgL1BhcmVudCAyIDAgUiAvTWVkaWFCb3ggWzAgMCA2MTIgNzkyXSAvQ29udGVudHMgNCAwIFIgL1Jlc291cmNlcyA8PCAvRm9udCA8PCAvRjEgNSAwIFIgPj4gPj4gPj4KZW5kb2JqCjQgMCBvYmoKPDwgL0xlbmd0aCAyMDkgPj4Kc3RyZWFtCkJUIC9GMSAxNCBUZiA3MiA3MDAgVGQgKEJBSUwgUkVTSURFTlRJRUwpIFRqIEVUCkJUIC9GMSAxMSBUZiA3MiA2NzAgVGQgKExlIGxvY2F0ZXVyIHBldXQgYXVnbWVudGVyIGxlIGxveWVyIGEgdG91dCBtb21lbnQuKSBUaiBFVApCVCAvRjEgMTEgVGYgNzIgNjUwIFRkIChMZSBkZXBvdCBkZSBnYXJhbnRpZSBlc3QgZGUgZGV1eCBtb2lzIGRlIGxveWVyLikgVGogRVQKZW5kc3RyZWFtCmVuZG9iago1IDAgb2JqCjw8IC9UeXBlIC9Gb250IC9TdWJ0eXBlIC9UeXBlMSAvQmFzZUZvbnQgL0hlbHZldGljYSA+PgplbmRvYmoKeHJlZgowIDYKMDAwMDAwMDAwMCA2NTUzNSBmIAowMDAwMDAwMDA5IDAwMDAwIG4gCjAwMDAwMDAwNTggMDAwMDAgbiAKMDAwMDAwMDExNSAwMDAwMCBuIAowMDAwMDAwMjQxIDAwMDAwIG4gCjAwMDAwMDA1MDAgMDAwMDAgbiAKdHJhaWxlcgo8PCAvU2l6ZSA2IC9Sb290IDEgMCBSID4+CnN0YXJ0eHJlZgo1NzAKJSVFT0YK";
+var quotes = [
+  { id: "r1", quote: "Le locateur peut augmenter le loyer \xE0 tout moment.", label: "Rent increase" },
+  { id: "r2", quote: "Le d\xE9p\xF4t de garantie est de deux mois de loyer.", label: "Deposit" }
+];
+var CDN = "https://cdn.jsdelivr.net/npm/pdfjs-dist@5.4.149/build/";
+var loadPdfjs = () => import(
+  /* webpackIgnore: true */
+  /* turbopackIgnore: true */
+  `${CDN}pdf.min.mjs`
+);
+function DocumentViewerHighlights() {
+  const [active, setActive] = React.useState("r1");
+  return /* @__PURE__ */ jsxs("div", { className: "flex flex-col gap-3", children: [
+    /* @__PURE__ */ jsx("div", { className: "flex gap-2", children: quotes.map((q) => /* @__PURE__ */ jsx("button", { type: "button", "aria-pressed": active === q.id, className: "rounded-md border border-border-default px-3 py-1 text-sm aria-pressed:bg-surface-3", onClick: () => setActive(q.id), children: q.label }, q.id)) }),
+    /* @__PURE__ */ jsx(DocumentViewer, { src: Uint8Array.from(atob(PDF), (c) => c.charCodeAt(0)), loadPdfjs, workerSrc: `${CDN}pdf.worker.min.mjs`, highlights: quotes, activeId: active, onActiveChange: setActive })
+  ] });
+}
+export {
+  DocumentViewerHighlights as default
+};

package/registry/examples/document-viewer/highlights.tsx

@@ -0,0 +1,30 @@
+"use client";
+
+import { DocumentViewer } from "@krizaka/ui/document-viewer";
+import * as React from "react";
+
+const PDF = "JVBERi0xLjQKMSAwIG9iago8PCAvVHlwZSAvQ2F0YWxvZyAvUGFnZXMgMiAwIFIgPj4KZW5kb2JqCjIgMCBvYmoKPDwgL1R5cGUgL1BhZ2VzIC9LaWRzIFszIDAgUl0gL0NvdW50IDEgPj4KZW5kb2JqCjMgMCBvYmoKPDwgL1R5cGUgL1BhZ2UgL1BhcmVudCAyIDAgUiAvTWVkaWFCb3ggWzAgMCA2MTIgNzkyXSAvQ29udGVudHMgNCAwIFIgL1Jlc291cmNlcyA8PCAvRm9udCA8PCAvRjEgNSAwIFIgPj4gPj4gPj4KZW5kb2JqCjQgMCBvYmoKPDwgL0xlbmd0aCAyMDkgPj4Kc3RyZWFtCkJUIC9GMSAxNCBUZiA3MiA3MDAgVGQgKEJBSUwgUkVTSURFTlRJRUwpIFRqIEVUCkJUIC9GMSAxMSBUZiA3MiA2NzAgVGQgKExlIGxvY2F0ZXVyIHBldXQgYXVnbWVudGVyIGxlIGxveWVyIGEgdG91dCBtb21lbnQuKSBUaiBFVApCVCAvRjEgMTEgVGYgNzIgNjUwIFRkIChMZSBkZXBvdCBkZSBnYXJhbnRpZSBlc3QgZGUgZGV1eCBtb2lzIGRlIGxveWVyLikgVGogRVQKZW5kc3RyZWFtCmVuZG9iago1IDAgb2JqCjw8IC9UeXBlIC9Gb250IC9TdWJ0eXBlIC9UeXBlMSAvQmFzZUZvbnQgL0hlbHZldGljYSA+PgplbmRvYmoKeHJlZgowIDYKMDAwMDAwMDAwMCA2NTUzNSBmIAowMDAwMDAwMDA5IDAwMDAwIG4gCjAwMDAwMDAwNTggMDAwMDAgbiAKMDAwMDAwMDExNSAwMDAwMCBuIAowMDAwMDAwMjQxIDAwMDAwIG4gCjAwMDAwMDA1MDAgMDAwMDAgbiAKdHJhaWxlcgo8PCAvU2l6ZSA2IC9Sb290IDEgMCBSID4+CnN0YXJ0eHJlZgo1NzAKJSVFT0YK";
+const quotes = [
+  { id: "r1", quote: "Le locateur peut augmenter le loyer à tout moment.", label: "Rent increase" },
+  { id: "r2", quote: "Le dépôt de garantie est de deux mois de loyer.", label: "Deposit" },
+];
+// pdf.js is the app's: `loadPdfjs={() => import("pdfjs-dist")}` and a worker served from its own origin. Here, from a CDN.
+const CDN = "https://cdn.jsdelivr.net/npm/pdfjs-dist@5.4.149/build/";
+const loadPdfjs = () => import(/* webpackIgnore: true */ /* turbopackIgnore: true */ `${CDN}pdf.min.mjs`) as never;
+
+// Pick a passage in your own list: the viewer scrolls to it and lights it where it sits in the page.
+export default function DocumentViewerHighlights() {
+  const [active, setActive] = React.useState<string | null>("r1");
+  return (
+    <div className="flex flex-col gap-3">
+      <div className="flex gap-2">
+        {quotes.map((q) => (
+          <button key={q.id} type="button" aria-pressed={active === q.id} className="rounded-md border border-border-default px-3 py-1 text-sm aria-pressed:bg-surface-3" onClick={() => setActive(q.id)}>
+            {q.label}
+          </button>
+        ))}
+      </div>
+      <DocumentViewer src={Uint8Array.from(atob(PDF), (c) => c.charCodeAt(0))} loadPdfjs={loadPdfjs} workerSrc={`${CDN}pdf.worker.min.mjs`} highlights={quotes} activeId={active} onActiveChange={setActive} />
+    </div>
+  );
+}

package/registry/examples/mascots/beaver.d.ts

@@ -0,0 +1,4 @@
+import type { ComponentType } from "react";
+/** A named example of the @krizaka/ui registry; `defaultOpen` opens what it opens (a dialog, a menu, toasts) at load. */
+declare const Example: ComponentType<{ defaultOpen?: boolean }>;
+export default Example;