@krizaka/ui 3.2.0 → 3.4.0

package/registry/tree-view.json

@@ -0,0 +1,291 @@
+{
+  "name": "tree-view",
+  "type": "primitive",
+  "title": "Tree view",
+  "summary": "A hierarchy the keyboard walks — the ARIA tree: one tab stop, the arrows move and open, a letter jumps, branches load on demand.",
+  "description": "A hierarchy the keyboard walks — the ARIA tree: one tab stop, the arrows move and open, a letter jumps, branches load on demand.",
+  "status": "beta",
+  "category": "navigation",
+  "platforms": "web",
+  "whenToUse": [
+    "The documentation's sections (krizaka.com/docs).",
+    "A studio's datasets, folders of files."
+  ],
+  "whenNotToUse": [
+    {
+      "when": "For two levels or fewer: a list with headings reads better.",
+      "use": "list"
+    },
+    {
+      "when": "On a phone: drill down screen by screen with a list.",
+      "use": "list"
+    }
+  ],
+  "bestPractices": [
+    "Open the branch of the selected node at first (`defaultExpanded`).",
+    "Load big branches on demand (`hasChildren` + `onLoadChildren`)."
+  ],
+  "accessibility": {
+    "keyboard": [
+      {
+        "keys": "Arrow Down / Arrow Up",
+        "action": "Move to the next or previous visible node."
+      },
+      {
+        "keys": "Arrow Right",
+        "action": "Opens a closed branch, or moves to its first child."
+      },
+      {
+        "keys": "Arrow Left",
+        "action": "Closes an open branch, or moves to its parent."
+      },
+      {
+        "keys": "Home / End",
+        "action": "Move to the first or last visible node."
+      },
+      {
+        "keys": "Enter / Space",
+        "action": "Select the node (`onSelect`)."
+      },
+      {
+        "keys": "A letter",
+        "action": "Moves to the next node whose name starts with it."
+      }
+    ],
+    "notes": [
+      "`tree`, `treeitem` and `group` with level, position and size; a loading branch is busy.",
+      "Web only: a phone drills down with lists."
+    ]
+  },
+  "related": [
+    "list",
+    "nav-bar"
+  ],
+  "web": {
+    "entry": "@krizaka/ui/tree-view",
+    "import": "import { TreeView } from \"@krizaka/ui/tree-view\";",
+    "props": [
+      {
+        "component": "TreeView",
+        "description": "A hierarchy to browse — documentation sections, a studio's datasets, folders: one tab stop, the arrows walk it (→\nopens, ← closes or goes up), Home/End, a letter jumps to the next name; branches can load their children on demand.",
+        "props": [
+          {
+            "name": "aria-label",
+            "type": "string",
+            "default": null,
+            "description": "The tree's accessible name (“Documentation”).",
+            "required": true
+          },
+          {
+            "name": "nodes",
+            "type": "readonly TreeNode[]",
+            "default": null,
+            "description": "The roots.",
+            "required": true
+          },
+          {
+            "name": "className",
+            "type": "string",
+            "default": null,
+            "description": "Classes merged on the tree.",
+            "required": false
+          },
+          {
+            "name": "defaultExpanded",
+            "type": "readonly string[]",
+            "default": "[]",
+            "description": "The ids open at first, uncontrolled.",
+            "required": false
+          },
+          {
+            "name": "defaultSelected",
+            "type": "string | null",
+            "default": "null",
+            "description": "The selected node at first, uncontrolled.",
+            "required": false
+          },
+          {
+            "name": "expanded",
+            "type": "readonly string[]",
+            "default": null,
+            "description": "The ids of the open branches (controlled).",
+            "required": false
+          },
+          {
+            "name": "loadingLabel",
+            "type": "string",
+            "default": "Loading",
+            "description": "The words of a branch that is loading (“Loading”).",
+            "required": false
+          },
+          {
+            "name": "onExpandedChange",
+            "type": "((expanded: string[]) => void)",
+            "default": null,
+            "description": "Called with the open branches.",
+            "required": false
+          },
+          {
+            "name": "onLoadChildren",
+            "type": "((node: TreeNode) => void)",
+            "default": null,
+            "description": "Called when a branch with `hasChildren` and no `children` opens: fetch them, then pass them in `nodes`.",
+            "required": false
+          },
+          {
+            "name": "onSelect",
+            "type": "((node: TreeNode) => void)",
+            "default": null,
+            "description": "Called when a node is chosen (click, Enter or Space): navigate, open the file.",
+            "required": false
+          },
+          {
+            "name": "selected",
+            "type": "string | null",
+            "default": null,
+            "description": "The selected node (controlled).",
+            "required": false
+          }
+        ]
+      }
+    ],
+    "examples": [
+      {
+        "name": "docs",
+        "title": "Documentation",
+        "description": "Products, sections and pages, the current page selected.",
+        "path": "examples/tree-view/docs.tsx",
+        "module": "@krizaka/ui/registry/examples/tree-view/docs",
+        "code": "\"use client\";\n\nimport { TreeView } from \"@krizaka/ui/tree-view\";\n\nconst nodes = [\n  {\n    id: \"orazaka\",\n    label: \"Orazaka\",\n    children: [\n      { id: \"getting-started\", label: \"Getting started\" },\n      { id: \"studios\", label: \"Studios\", meta: \"12\", children: [{ id: \"dubbing\", label: \"Dubbing\" }, { id: \"transcript\", label: \"Transcript\" }, { id: \"clips\", label: \"Clips\" }] },\n      { id: \"api\", label: \"API reference\" },\n    ],\n  },\n  { id: \"orochia\", label: \"Orochia\", children: [{ id: \"auctions\", label: \"Auctions\" }, { id: \"challenges\", label: \"Challenges\" }] },\n  { id: \"ui\", label: \"Krizaka UI\", children: [{ id: \"components\", label: \"Components\" }] },\n];\n\n// The documentation's sections: one tab stop, the arrows walk and open, a letter jumps.\nexport default function TreeViewDocs() {\n  return <TreeView aria-label=\"Documentation\" nodes={nodes} defaultExpanded={[\"orazaka\", \"studios\"]} defaultSelected=\"dubbing\" className=\"max-w-xs\" />;\n}\n"
+      },
+      {
+        "name": "lazy",
+        "title": "Loaded on demand",
+        "description": "A branch fetches its files when it opens.",
+        "path": "examples/tree-view/lazy.tsx",
+        "module": "@krizaka/ui/registry/examples/tree-view/lazy",
+        "code": "\"use client\";\n\nimport { type TreeNode, TreeView } from \"@krizaka/ui/tree-view\";\nimport { useState } from \"react\";\n\n// A studio's datasets: a branch loads its files when it opens (here after 600 ms).\nexport default function TreeViewLazy() {\n  const [nodes, setNodes] = useState<TreeNode[]>([\n    { id: \"voices\", label: \"Voices\", hasChildren: true, meta: \"3\" },\n    { id: \"glossaries\", label: \"Glossaries\", hasChildren: true, meta: \"2\" },\n    { id: \"readme\", label: \"README.md\" },\n  ]);\n  const load = (node: TreeNode) =>\n    setTimeout(() => {\n      const files = Array.from({ length: Number(node.meta) }, (_, i) => ({ id: `${node.id}-${i}`, label: `${node.label.toLowerCase()}-${i + 1}.json` }));\n      setNodes((all) => all.map((n) => (n.id === node.id ? { ...n, children: files } : n)));\n    }, 600);\n  return <TreeView aria-label=\"Datasets\" nodes={nodes} onLoadChildren={load} loadingLabel=\"Loading the files\" className=\"max-w-xs\" />;\n}\n"
+      }
+    ]
+  },
+  "native": null,
+  "files": [
+    {
+      "path": "glyphs.tsx",
+      "content": "// The small line glyphs the data and media primitives draw (play, volume, search, chevrons…): decorative, 24-unit\n// box, `currentColor`, sized by the caller's class. Shared by the entries that need them; never exported on its own —\n// a product draws its own icons with @krizaka/icons.\nimport type * as React from \"react\";\n\ntype GlyphProps = { className?: string };\n\nfunction Glyph({ className = \"h-4 w-4\", fill, children }: GlyphProps & { fill?: boolean; children: React.ReactNode }) {\n  return (\n    <svg\n      viewBox=\"0 0 24 24\"\n      className={className}\n      fill={fill ? \"currentColor\" : \"none\"}\n      stroke={fill ? \"none\" : \"currentColor\"}\n      strokeWidth=\"2\"\n      strokeLinecap=\"round\"\n      strokeLinejoin=\"round\"\n      aria-hidden\n      focusable=\"false\"\n    >\n      {children}\n    </svg>\n  );\n}\n\nexport const PlayGlyph = (p: GlyphProps) => (\n  <Glyph {...p} fill>\n    <path d=\"M8 5.5v13a1 1 0 0 0 1.5.86l10.4-6.5a1 1 0 0 0 0-1.72L9.5 4.64A1 1 0 0 0 8 5.5Z\" />\n  </Glyph>\n);\nexport const PauseGlyph = (p: GlyphProps) => (\n  <Glyph {...p} fill>\n    <rect x=\"6\" y=\"5\" width=\"4\" height=\"14\" rx=\"1\" />\n    <rect x=\"14\" y=\"5\" width=\"4\" height=\"14\" rx=\"1\" />\n  </Glyph>\n);\nexport const VolumeGlyph = ({ muted, ...p }: GlyphProps & { muted?: boolean }) => (\n  <Glyph {...p}>\n    <path d=\"M11 5 6 9H3v6h3l5 4V5Z\" />\n    {muted ? <path d=\"m22 9-6 6m0-6 6 6\" /> : <path d=\"M15.5 8.5a5 5 0 0 1 0 7M18.5 5.5a9 9 0 0 1 0 13\" />}\n  </Glyph>\n);\nexport const FullscreenGlyph = ({ exit, ...p }: GlyphProps & { exit?: boolean }) => (\n  <Glyph {...p}>\n    {exit ? <path d=\"M9 4v5H4m11-5v5h5M9 20v-5H4m11 5v-5h5\" /> : <path d=\"M4 9V4h5m6 0h5v5M4 15v5h5m11-5v5h-5\" />}\n  </Glyph>\n);\nexport const CaptionsGlyph = (p: GlyphProps) => (\n  <Glyph {...p}>\n    <rect x=\"3\" y=\"5\" width=\"18\" height=\"14\" rx=\"2\" />\n    <path d=\"M10 10.5a2 2 0 1 0 0 3M17 10.5a2 2 0 1 0 0 3\" />\n  </Glyph>\n);\nexport const PipGlyph = (p: GlyphProps) => (\n  <Glyph {...p}>\n    <rect x=\"3\" y=\"5\" width=\"18\" height=\"14\" rx=\"2\" />\n    <rect x=\"12\" y=\"12\" width=\"6\" height=\"4\" rx=\"1\" />\n  </Glyph>\n);\nexport const SearchGlyph = (p: GlyphProps) => (\n  <Glyph {...p}>\n    <circle cx=\"11\" cy=\"11\" r=\"7\" />\n    <path d=\"m20 20-3.5-3.5\" />\n  </Glyph>\n);\nexport const CloseGlyph = (p: GlyphProps) => (\n  <Glyph {...p}>\n    <path d=\"M18 6 6 18M6 6l12 12\" />\n  </Glyph>\n);\nexport const ChevronGlyph = ({ direction = \"down\", ...p }: GlyphProps & { direction?: \"left\" | \"right\" | \"up\" | \"down\" }) => (\n  <Glyph {...p}>\n    <path d={{ left: \"m15 6-6 6 6 6\", right: \"m9 6 6 6-6 6\", up: \"m6 15 6-6 6 6\", down: \"m6 9 6 6 6-6\" }[direction]} />\n  </Glyph>\n);\nexport const CheckGlyph = (p: GlyphProps) => (\n  <Glyph {...p}>\n    <path d=\"M20 6 9 17l-5-5\" />\n  </Glyph>\n);\nexport const PlusGlyph = (p: GlyphProps) => (\n  <Glyph {...p}>\n    <path d=\"M12 5v14M5 12h14\" />\n  </Glyph>\n);\nexport const CalendarGlyph = (p: GlyphProps) => (\n  <Glyph {...p}>\n    <rect x=\"3\" y=\"5\" width=\"18\" height=\"16\" rx=\"2\" />\n    <path d=\"M3 10h18M8 3v4M16 3v4\" />\n  </Glyph>\n);\nexport const UploadGlyph = (p: GlyphProps) => (\n  <Glyph {...p}>\n    <path d=\"M12 16V4m0 0L7 9m5-5 5 5\" />\n    <path d=\"M4 16v2a2 2 0 0 0 2 2h12a2 2 0 0 0 2-2v-2\" />\n  </Glyph>\n);\nexport const FileGlyph = (p: GlyphProps) => (\n  <Glyph {...p}>\n    <path d=\"M14 3H7a2 2 0 0 0-2 2v14a2 2 0 0 0 2 2h10a2 2 0 0 0 2-2V8l-5-5Z\" />\n    <path d=\"M14 3v5h5\" />\n  </Glyph>\n);\nexport const CameraGlyph = (p: GlyphProps) => (\n  <Glyph {...p}>\n    <path d=\"M4 8h3l2-3h6l2 3h3a1 1 0 0 1 1 1v10a1 1 0 0 1-1 1H4a1 1 0 0 1-1-1V9a1 1 0 0 1 1-1Z\" />\n    <circle cx=\"12\" cy=\"13.5\" r=\"3.5\" />\n  </Glyph>\n);\nexport const FlipGlyph = (p: GlyphProps) => (\n  <Glyph {...p}>\n    <path d=\"M4 12a8 8 0 0 1 14-5.3M20 12a8 8 0 0 1-14 5.3\" />\n    <path d=\"M18 3v4h-4M6 21v-4h4\" />\n  </Glyph>\n);\nexport const RetryGlyph = (p: GlyphProps) => (\n  <Glyph {...p}>\n    <path d=\"M4 12a8 8 0 1 0 2.3-5.7L4 8.5\" />\n    <path d=\"M4 4v4.5h4.5\" />\n  </Glyph>\n);\nexport const SortGlyph = ({ direction, ...p }: GlyphProps & { direction?: \"ascending\" | \"descending\" }) => (\n  <Glyph {...p}>\n    {direction === \"ascending\" ? <path d=\"m7 14 5-5 5 5\" /> : direction === \"descending\" ? <path d=\"m7 10 5 5 5-5\" /> : <path d=\"m8 9 4-4 4 4M8 15l4 4 4-4\" />}\n  </Glyph>\n);\nexport const ArrowGlyph = ({ direction = \"right\", ...p }: GlyphProps & { direction?: \"left\" | \"right\" }) => (\n  <Glyph {...p}>\n    <path d={direction === \"left\" ? \"M19 12H5m0 0 6-6m-6 6 6 6\" : \"M5 12h14m0 0-6-6m6 6-6 6\"} />\n  </Glyph>\n);\nexport const ExternalGlyph = (p: GlyphProps) => (\n  <Glyph {...p}>\n    <path d=\"M14 4h6v6M20 4l-9 9\" />\n    <path d=\"M18 14v4a2 2 0 0 1-2 2H6a2 2 0 0 1-2-2V8a2 2 0 0 1 2-2h4\" />\n  </Glyph>\n);\nexport const WarningGlyph = (p: GlyphProps) => (\n  <Glyph {...p}>\n    <path d=\"M12 4 2.5 20h19L12 4Z\" />\n    <path d=\"M12 10v4M12 17.2v.1\" />\n  </Glyph>\n);\nexport const CopyGlyph = (p: GlyphProps) => (\n  <Glyph {...p}>\n    <rect x=\"9\" y=\"9\" width=\"11\" height=\"11\" rx=\"2\" />\n    <path d=\"M15 9V6a2 2 0 0 0-2-2H6a2 2 0 0 0-2 2v7a2 2 0 0 0 2 2h3\" />\n  </Glyph>\n);\n"
+    },
+    {
+      "path": "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 stable function that runs `callback` once `delay` ms have passed without a new call; `cancel()` drops the pending one. */\nexport function useDebouncedCallback<A extends unknown[]>(callback: (...args: A) => void, delay: number) {\n  const latest = useLatest(callback);\n  const [debounced] = React.useState(() => {\n    let timer: ReturnType<typeof setTimeout> | undefined;\n    let wait = delay;\n    const run = (...args: A) => {\n      clearTimeout(timer);\n      if (wait <= 0) latest.current(...args);\n      else timer = setTimeout(() => latest.current(...args), wait);\n    };\n    return Object.assign(run, {\n      cancel: () => clearTimeout(timer),\n      setDelay: (next: number) => {\n        wait = next;\n      },\n    });\n  });\n  React.useEffect(() => debounced.setDelay(delay), [debounced, delay]);\n  React.useEffect(() => () => debounced.cancel(), [debounced]);\n  return debounced;\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 krizaka.com renders as\n// /docs/ui/<name>, and `scripts/registry.test.mjs` fails when one is missing or incomplete.\n//\n// Why a typed module and not JSDoc tags: the fields are lists and links (`related`, `whenNotToUse[].use`, examples),\n// which a type checks and a comment does not; the file is plain data (erasable TypeScript), so Node reads it without a\n// compiler, and an editor completes it.\n\n/** Every documented component: the web primitives (one entry of the package each) and the native-only ones. */\nexport type ComponentName =\n  | \"achievement\"\n  | \"action-bar\"\n  | \"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  | \"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  | \"longform-page\"\n  | \"marketing-layout\"\n  | \"marquee\"\n  | \"mascot-quote\"\n  | \"mascot-state\"\n  | \"mascots\"\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  | \"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  | \"scroll-stage\"\n  | \"search-field\"\n  | \"section-backdrop\"\n  | \"segmented\"\n  | \"separator\"\n  | \"settings-layout\"\n  | \"skeleton\"\n  | \"slider\"\n  | \"slot\"\n  | \"spinner\"\n  | \"split-view\"\n  | \"stage-banner\"\n  | \"stat\"\n  | \"status-page\"\n  | \"stepper\"\n  | \"swipeable-row\"\n  | \"switch\"\n  | \"tab-bar\"\n  | \"tabs\"\n  | \"tag-input\"\n  | \"terminal-replay\"\n  | \"theme\"\n  | \"toast\"\n  | \"toc\"\n  | \"tooltip\"\n  | \"tree-view\"\n  | \"txt\"\n  | \"video-player\"\n  | \"video-trimmer\"\n  | \"virtual\";\n\n/** Where a component exists: `@krizaka/ui/<name>` (web), `@krizaka/ui/native` (React Native), or both. */\nexport type Platform = \"web\" | \"native\" | \"both\";\n\n/** `stable`: its API only changes in a major. `beta`: it may still change in a minor. */\nexport type Status = \"stable\" | \"beta\";\n\n/**\n * The group of the catalogue. `media`: video, sound, camera, files, cropping. `blocks`: the page blocks — the frame,\n * the hero, sections, cards that lead or argue, decisions, code, calls to act — that every page of a site is made of.\n * `layouts`: the shells of whole screens — an application, a dashboard, settings, sign-in, an object, a list and its\n * item, a site's page, a documentation page — each with its screens. `templates`: the page templates — whole pages of a\n * site (a landing, a product, a docs hub, a long read, a changelog, pricing, status, an error…), each a distinct\n * composition of the blocks, words and content as props.\n */\nexport type Category = \"actions\" | \"forms\" | \"navigation\" | \"overlays\" | \"feedback\" | \"data-display\" | \"media\" | \"blocks\" | \"layouts\" | \"templates\" | \"layout\" | \"foundations\";\n\n/**\n * A named example: the file `registry/examples/<component>/<name>.tsx` (web) or\n * `registry/examples/<component>/native/<name>.tsx` (React Native) — at most 40 lines, imported by the stories and\n * shown (live, with its code) by the documentation.\n */\nexport interface Example {\n  /** The file name, kebab-case (`primary`, `icon-button`). */\n  readonly name: string;\n  /** A short title (`Primary`, `Icon button`). */\n  readonly title: string;\n  /** One or two sentences: when this variant is the right one. */\n  readonly description: string;\n  /**\n   * A template: a whole screen of a product composed from the platform (a layout and its blocks, real words, its phone\n   * version thought out), copied as a starting point — at most 160 lines, listed on krizaka.com/docs/ui/templates.\n   */\n  readonly template?: boolean;\n}\n\n/** One platform's side of a component. */\nexport interface PlatformDocs {\n  /** The names to import (`[\"Button\", \"IconButton\"]`): from `@krizaka/ui/<name>` on the web, `@krizaka/ui/native` in React Native. */\n  readonly imports: readonly string[];\n  /** The examples, in reading order; the first one is the component's preview. */\n  readonly examples: readonly Example[];\n}\n\n/** The React Native side: the same concept, and what differs from the web API. */\nexport interface NativeDocs extends PlatformDocs {\n  /**\n   * The entry to import from when it is not `@krizaka/ui/native`: a component that needs an Expo module (an optional\n   * peer) has its own, `@krizaka/ui/native/<name>`, so an app that does not use it never installs the module.\n   */\n  readonly entry?: string;\n  /** What differs from the web API (`label` instead of children…); empty for a native-only component. */\n  readonly differences: readonly string[];\n}\n\nexport interface KeyboardInteraction {\n  /** The keys, as written on a keyboard: `Space`, `Enter`, `Arrow keys`, `Esc`, `Tab`. */\n  readonly keys: string;\n  /** What they do. */\n  readonly action: string;\n}\n\nexport interface ComponentMeta {\n  /** The display name: `Button`, `Dropdown menu`. */\n  readonly title: string;\n  /** One sentence: what it is. */\n  readonly summary: string;\n  readonly status: Status;\n  readonly category: Category;\n  /** Must match the sides below: `both` ⇔ `web` and `native`. */\n  readonly platforms: Platform;\n  /** When to reach for it: concrete situations, one per item. */\n  readonly whenToUse: readonly string[];\n  /** When not to — and what to use instead (`use`), when another component is the answer. */\n  readonly whenNotToUse: readonly { readonly when: string; readonly use?: ComponentName }[];\n  /** How to use it well: wording, placement, composition. */\n  readonly bestPractices: readonly string[];\n  readonly accessibility: {\n    /** The keyboard, when it does more than Tab and Enter. */\n    readonly keyboard: readonly KeyboardInteraction[];\n    /** Roles, names and announcements: what the component does, what the app must provide. */\n    readonly notes: readonly string[];\n  };\n  /** The components a reader of this page should know about. */\n  readonly related: readonly ComponentName[];\n  readonly web?: PlatformDocs;\n  readonly native?: NativeDocs;\n}\n"
+    },
+    {
+      "path": "tree-view/index.ts",
+      "content": "/** @krizaka/ui/tree-view — `TreeView`: a hierarchy the keyboard walks (the ARIA tree), branches loaded on demand. */\nexport { type TreeNode, TreeView, treeView, type TreeViewProps } from \"./tree-view\";\n"
+    },
+    {
+      "path": "tree-view/meta.ts",
+      "content": "import type { ComponentMeta } from \"../meta\";\n\nexport const meta = {\n  title: \"Tree view\",\n  summary: \"A hierarchy the keyboard walks — the ARIA tree: one tab stop, the arrows move and open, a letter jumps, branches load on demand.\",\n  status: \"beta\",\n  category: \"navigation\",\n  platforms: \"web\",\n  whenToUse: [\"The documentation's sections (krizaka.com/docs).\", \"A studio's datasets, folders of files.\"],\n  whenNotToUse: [\n    { when: \"For two levels or fewer: a list with headings reads better.\", use: \"list\" },\n    { when: \"On a phone: drill down screen by screen with a list.\", use: \"list\" },\n  ],\n  bestPractices: [\"Open the branch of the selected node at first (`defaultExpanded`).\", \"Load big branches on demand (`hasChildren` + `onLoadChildren`).\"],\n  accessibility: {\n    keyboard: [\n      { keys: \"Arrow Down / Arrow Up\", action: \"Move to the next or previous visible node.\" },\n      { keys: \"Arrow Right\", action: \"Opens a closed branch, or moves to its first child.\" },\n      { keys: \"Arrow Left\", action: \"Closes an open branch, or moves to its parent.\" },\n      { keys: \"Home / End\", action: \"Move to the first or last visible node.\" },\n      { keys: \"Enter / Space\", action: \"Select the node (`onSelect`).\" },\n      { keys: \"A letter\", action: \"Moves to the next node whose name starts with it.\" },\n    ],\n    notes: [\"`tree`, `treeitem` and `group` with level, position and size; a loading branch is busy.\", \"Web only: a phone drills down with lists.\"],\n  },\n  related: [\"list\", \"nav-bar\"],\n  web: {\n    imports: [\"TreeView\"],\n    examples: [\n      { name: \"docs\", title: \"Documentation\", description: \"Products, sections and pages, the current page selected.\" },\n      { name: \"lazy\", title: \"Loaded on demand\", description: \"A branch fetches its files when it opens.\" },\n    ],\n  },\n} satisfies ComponentMeta;\n"
+    },
+    {
+      "path": "tree-view/tree-view.tsx",
+      "content": "// Client (expansion, selection, the roving focus). A hierarchy the keyboard walks — the ARIA tree pattern: one tab\n// stop, the arrows move and open, Home/End, typing a letter jumps; children loaded on demand when a branch opens.\nimport * as React from \"react\";\nimport { tv } from \"tailwind-variants\";\n\nimport { ChevronGlyph } from \"../glyphs\";\nimport { useControllable } from \"../media\";\n\nexport const treeView = tv({\n  slots: {\n    root: \"m-0 list-none p-0 text-sm\",\n    group: \"m-0 list-none p-0\",\n    row:\n      \"flex min-h-8 cursor-pointer select-none items-center gap-1.5 rounded-md pr-2 text-fg outline-hidden \" +\n      \"hover:bg-surface-2 data-[selected]:bg-accent-soft data-[selected]:font-semibold data-[disabled]:cursor-default data-[disabled]:opacity-50\",\n    toggle: \"flex h-5 w-5 shrink-0 items-center justify-center text-fg-secondary [&>svg]:h-3.5 [&>svg]:w-3.5 [&>svg]:transition-transform motion-reduce:[&>svg]:transition-none\",\n    icon: \"flex shrink-0 items-center text-fg-secondary [&>svg]:h-4 [&>svg]:w-4\",\n    label: \"min-w-0 flex-1 truncate\",\n    meta: \"shrink-0 text-xs tabular-nums text-fg-secondary\",\n  },\n});\n\nexport type TreeNode = {\n  /** A stable id. */\n  id: string;\n  /** Its name — passed translated. */\n  label: string;\n  /** A decorative icon before the name. */\n  icon?: React.ReactNode;\n  /** A detail after the name (a count, a size). */\n  meta?: React.ReactNode;\n  /** Its children; `undefined` for a leaf. With `hasChildren`, they load when it opens (`onLoadChildren`). */\n  children?: readonly TreeNode[];\n  /** A branch whose children are not loaded yet. */\n  hasChildren?: boolean;\n  /** Cannot be selected. */\n  disabled?: boolean;\n};\n\nexport type TreeViewProps = {\n  /** The roots. */\n  nodes: readonly TreeNode[];\n  /** The tree's accessible name (“Documentation”). */\n  \"aria-label\": string;\n  /** The ids of the open branches (controlled). */\n  expanded?: readonly string[];\n  /** The ids open at first, uncontrolled. */\n  defaultExpanded?: readonly string[];\n  /** Called with the open branches. */\n  onExpandedChange?: (expanded: string[]) => void;\n  /** The selected node (controlled). */\n  selected?: string | null;\n  /** The selected node at first, uncontrolled. */\n  defaultSelected?: string | null;\n  /** Called when a node is chosen (click, Enter or Space): navigate, open the file. */\n  onSelect?: (node: TreeNode) => void;\n  /** Called when a branch with `hasChildren` and no `children` opens: fetch them, then pass them in `nodes`. */\n  onLoadChildren?: (node: TreeNode) => void;\n  /** The words of a branch that is loading (“Loading”). */\n  loadingLabel?: string;\n  /** Classes merged on the tree. */\n  className?: string;\n};\n\ntype Flat = { node: TreeNode; level: number; parent: string | null; posinset: number; setsize: number };\n\nconst isBranch = (node: TreeNode) => Boolean(node.children?.length || node.hasChildren);\n\nfunction flatten(nodes: readonly TreeNode[], open: Set<string>, level = 1, parent: string | null = null, out: Flat[] = []): Flat[] {\n  nodes.forEach((node, i) => {\n    out.push({ node, level, parent, posinset: i + 1, setsize: nodes.length });\n    if (open.has(node.id) && node.children) flatten(node.children, open, level + 1, node.id, out);\n  });\n  return out;\n}\n\n/**\n * A hierarchy to browse — documentation sections, a studio's datasets, folders: one tab stop, the arrows walk it (→\n * opens, ← closes or goes up), Home/End, a letter jumps to the next name; branches can load their children on demand.\n */\nexport function TreeView({\n  nodes,\n  \"aria-label\": label,\n  expanded: expandedProp,\n  defaultExpanded = [],\n  onExpandedChange,\n  selected: selectedProp,\n  defaultSelected = null,\n  onSelect,\n  onLoadChildren,\n  loadingLabel = \"Loading\",\n  className,\n}: TreeViewProps) {\n  const s = treeView();\n  const uid = React.useId();\n  const [expanded, setExpanded] = useControllable<readonly string[]>(expandedProp, defaultExpanded, onExpandedChange as (next: readonly string[]) => void);\n  const [selected, setSelected] = useControllable<string | null>(selectedProp, defaultSelected);\n  const open = new Set(expanded);\n  const rows = flatten(nodes, open);\n  const [active, setActive] = React.useState<string | null>(null);\n  const focusId = active && rows.some((r) => r.node.id === active) ? active : (selected ?? rows[0]?.node.id ?? null);\n  const refs = React.useRef(new Map<string, HTMLDivElement>());\n  const move = (id: string | undefined) => {\n    if (!id) return;\n    setActive(id);\n    refs.current.get(id)?.focus();\n  };\n  const toggle = (node: TreeNode, to = !open.has(node.id)) => {\n    if (!isBranch(node)) return;\n    if (to && node.hasChildren && !node.children) onLoadChildren?.(node);\n    setExpanded(to ? [...expanded, node.id] : expanded.filter((id) => id !== node.id));\n  };\n  const choose = (node: TreeNode) => {\n    if (node.disabled) return;\n    setSelected(node.id);\n    onSelect?.(node);\n  };\n  const onKeyDown = (event: React.KeyboardEvent, i: number) => {\n    const row = rows[i]!;\n    const { node } = row;\n    const keys: Record<string, () => void> = {\n      ArrowDown: () => move(rows[i + 1]?.node.id),\n      ArrowUp: () => move(rows[i - 1]?.node.id),\n      Home: () => move(rows[0]?.node.id),\n      End: () => move(rows[rows.length - 1]?.node.id),\n      ArrowRight: () => (isBranch(node) && !open.has(node.id) ? toggle(node, true) : isBranch(node) ? move(rows[i + 1]?.node.id) : undefined),\n      ArrowLeft: () => (open.has(node.id) ? toggle(node, false) : move(row.parent ?? undefined)),\n      Enter: () => choose(node),\n      \" \": () => choose(node),\n    };\n    const run = keys[event.key];\n    if (run) {\n      event.preventDefault();\n      run();\n      return;\n    }\n    if (event.key.length === 1 && /\\S/.test(event.key)) {\n      const letter = event.key.toLowerCase();\n      const next = [...rows.slice(i + 1), ...rows.slice(0, i)].find((r) => r.node.label.toLowerCase().startsWith(letter));\n      move(next?.node.id);\n    }\n  };\n\n  const render = (list: readonly TreeNode[], level: number): React.ReactNode =>\n    list.map((node) => {\n      const i = rows.findIndex((r) => r.node.id === node.id);\n      const row = rows[i]!;\n      const branch = isBranch(node);\n      const isOpen = open.has(node.id);\n      const loading = isOpen && node.hasChildren && !node.children;\n      return (\n        // The row is the treeitem (its name is its own words, never its children's); the group of children hangs\n        // from it with aria-owns, in the `li` that holds both.\n        <li key={node.id} role=\"none\">\n          <div\n            ref={(el) => {\n              if (el) refs.current.set(node.id, el);\n              else refs.current.delete(node.id);\n            }}\n            role=\"treeitem\"\n            aria-level={level}\n            aria-posinset={row.posinset}\n            aria-setsize={row.setsize}\n            aria-expanded={branch ? isOpen : undefined}\n            aria-selected={selected === node.id}\n            aria-disabled={node.disabled || undefined}\n            aria-busy={loading || undefined}\n            aria-owns={branch && isOpen ? `${uid}-${node.id}-group` : undefined}\n            tabIndex={node.id === focusId ? 0 : -1}\n            onKeyDown={(e) => {\n              if (e.target === e.currentTarget) onKeyDown(e, i);\n            }}\n            onFocus={(e) => {\n              if (e.target === e.currentTarget) setActive(node.id);\n            }}\n            className={s.row({ className: \"outline-hidden focus-visible:ring-2 focus-visible:ring-ring\" })}\n            data-selected={selected === node.id || undefined}\n            data-disabled={node.disabled || undefined}\n            style={{ paddingLeft: `${(level - 1) * 1.25 + 0.25}rem` }}\n            onClick={() => {\n              if (branch) toggle(node);\n              choose(node);\n              move(node.id);\n            }}\n          >\n            <span className={s.toggle()} aria-hidden>\n              {branch ? <ChevronGlyph direction={isOpen ? \"down\" : \"right\"} /> : null}\n            </span>\n            {node.icon ? <span className={s.icon()} aria-hidden>{node.icon}</span> : null}\n            <span className={s.label()}>{node.label}</span>\n            {node.meta ? <span className={s.meta()}>{node.meta}</span> : null}\n          </div>\n          {branch && isOpen ? (\n            <ul role=\"group\" id={`${uid}-${node.id}-group`} className={s.group()}>\n              {loading ? (\n                <li role=\"none\" className=\"py-1 text-xs text-fg-secondary\" style={{ paddingLeft: `${level * 1.25 + 1.75}rem` }}>\n                  {loadingLabel}\n                </li>\n              ) : (\n                render(node.children ?? [], level + 1)\n              )}\n            </ul>\n          ) : null}\n        </li>\n      );\n    });\n\n  return (\n    <ul role=\"tree\" aria-label={label} className={s.root({ className })}>\n      {render(nodes, 1)}\n    </ul>\n  );\n}\n"
+    }
+  ],
+  "dependencies": [
+    "tailwind-variants@^3.3.1"
+  ],
+  "registryDependencies": [],
+  "demo": {
+    "path": "examples/tree-view/docs.tsx",
+    "content": "\"use client\";\n\nimport { TreeView } from \"@krizaka/ui/tree-view\";\n\nconst nodes = [\n  {\n    id: \"orazaka\",\n    label: \"Orazaka\",\n    children: [\n      { id: \"getting-started\", label: \"Getting started\" },\n      { id: \"studios\", label: \"Studios\", meta: \"12\", children: [{ id: \"dubbing\", label: \"Dubbing\" }, { id: \"transcript\", label: \"Transcript\" }, { id: \"clips\", label: \"Clips\" }] },\n      { id: \"api\", label: \"API reference\" },\n    ],\n  },\n  { id: \"orochia\", label: \"Orochia\", children: [{ id: \"auctions\", label: \"Auctions\" }, { id: \"challenges\", label: \"Challenges\" }] },\n  { id: \"ui\", label: \"Krizaka UI\", children: [{ id: \"components\", label: \"Components\" }] },\n];\n\n// The documentation's sections: one tab stop, the arrows walk and open, a letter jumps.\nexport default function TreeViewDocs() {\n  return <TreeView aria-label=\"Documentation\" nodes={nodes} defaultExpanded={[\"orazaka\", \"studios\"]} defaultSelected=\"dubbing\" className=\"max-w-xs\" />;\n}\n"
+  },
+  "props": [
+    {
+      "component": "TreeView",
+      "description": "A hierarchy to browse — documentation sections, a studio's datasets, folders: one tab stop, the arrows walk it (→\nopens, ← closes or goes up), Home/End, a letter jumps to the next name; branches can load their children on demand.",
+      "props": [
+        {
+          "name": "aria-label",
+          "type": "string",
+          "default": null,
+          "description": "The tree's accessible name (“Documentation”).",
+          "required": true
+        },
+        {
+          "name": "nodes",
+          "type": "readonly TreeNode[]",
+          "default": null,
+          "description": "The roots.",
+          "required": true
+        },
+        {
+          "name": "className",
+          "type": "string",
+          "default": null,
+          "description": "Classes merged on the tree.",
+          "required": false
+        },
+        {
+          "name": "defaultExpanded",
+          "type": "readonly string[]",
+          "default": "[]",
+          "description": "The ids open at first, uncontrolled.",
+          "required": false
+        },
+        {
+          "name": "defaultSelected",
+          "type": "string | null",
+          "default": "null",
+          "description": "The selected node at first, uncontrolled.",
+          "required": false
+        },
+        {
+          "name": "expanded",
+          "type": "readonly string[]",
+          "default": null,
+          "description": "The ids of the open branches (controlled).",
+          "required": false
+        },
+        {
+          "name": "loadingLabel",
+          "type": "string",
+          "default": "Loading",
+          "description": "The words of a branch that is loading (“Loading”).",
+          "required": false
+        },
+        {
+          "name": "onExpandedChange",
+          "type": "((expanded: string[]) => void)",
+          "default": null,
+          "description": "Called with the open branches.",
+          "required": false
+        },
+        {
+          "name": "onLoadChildren",
+          "type": "((node: TreeNode) => void)",
+          "default": null,
+          "description": "Called when a branch with `hasChildren` and no `children` opens: fetch them, then pass them in `nodes`.",
+          "required": false
+        },
+        {
+          "name": "onSelect",
+          "type": "((node: TreeNode) => void)",
+          "default": null,
+          "description": "Called when a node is chosen (click, Enter or Space): navigate, open the file.",
+          "required": false
+        },
+        {
+          "name": "selected",
+          "type": "string | null",
+          "default": null,
+          "description": "The selected node (controlled).",
+          "required": false
+        }
+      ]
+    }
+  ]
+}

package/registry/video-player.json

@@ -408,7 +408,7 @@
     },
     {
       "path": "meta.ts",
-      "content": "// The documentation of a component, carried by its code: each primitive has a `meta.ts` beside its source\n// (`src/<name>/meta.ts`; a component that exists only in React Native: `src/native/meta/<name>.ts`). Never built into\n// the package: `scripts/build-registry.mjs` reads them into `registry/<name>.json`, which krizaka.com renders as\n// /docs/ui/<name>, and `scripts/registry.test.mjs` fails when one is missing or incomplete.\n//\n// Why a typed module and not JSDoc tags: the fields are lists and links (`related`, `whenNotToUse[].use`, examples),\n// which a type checks and a comment does not; the file is plain data (erasable TypeScript), so Node reads it without a\n// compiler, and an editor completes it.\n\n/** Every documented component: the web primitives (one entry of the package each) and the native-only ones. */\nexport type ComponentName =\n  | \"achievement\"\n  | \"action-bar\"\n  | \"alert\"\n  | \"app-shell\"\n  | \"argument-card\"\n  | \"audio-player\"\n  | \"auth-layout\"\n  | \"avatar\"\n  | \"badge\"\n  | \"button\"\n  | \"card\"\n  | \"card-grid\"\n  | \"catalogue-page\"\n  | \"changelog-page\"\n  | \"checkbox\"\n  | \"chip\"\n  | \"chip-link\"\n  | \"choice-grid\"\n  | \"cn\"\n  | \"code-block\"\n  | \"combobox\"\n  | \"command\"\n  | \"component-page\"\n  | \"confirm-button\"\n  | \"contact-page\"\n  | \"continue-prompt\"\n  | \"countdown\"\n  | \"cta-panel\"\n  | \"dashboard-layout\"\n  | \"data-table\"\n  | \"date-picker\"\n  | \"decision-list\"\n  | \"detail-layout\"\n  | \"dialog\"\n  | \"docs-article-page\"\n  | \"docs-hub-page\"\n  | \"docs-layout\"\n  | \"dropdown-menu\"\n  | \"empty-state\"\n  | \"error-page\"\n  | \"field\"\n  | \"file-upload\"\n  | \"filter-bar\"\n  | \"form\"\n  | \"gallery-page\"\n  | \"glow-card\"\n  | \"goal-gauge\"\n  | \"how-it-works-page\"\n  | \"image-cropper\"\n  | \"iso\"\n  | \"kbd\"\n  | \"landing-page\"\n  | \"landscape\"\n  | \"legal-page\"\n  | \"link-card\"\n  | \"list\"\n  | \"loader\"\n  | \"longform-page\"\n  | \"marketing-layout\"\n  | \"marquee\"\n  | \"mascot-quote\"\n  | \"mascot-state\"\n  | \"mascots\"\n  | \"media-capture\"\n  | \"meter\"\n  | \"nav-bar\"\n  | \"number-ticker\"\n  | \"page\"\n  | \"page-header\"\n  | \"page-hero\"\n  | \"pagination\"\n  | \"pointer-light\"\n  | \"popover\"\n  | \"pricing-page\"\n  | \"product-page\"\n  | \"profile-card\"\n  | \"progress\"\n  | \"promise-card\"\n  | \"radio-group\"\n  | \"scroll-stage\"\n  | \"search-field\"\n  | \"section-backdrop\"\n  | \"segmented\"\n  | \"separator\"\n  | \"settings-layout\"\n  | \"skeleton\"\n  | \"slider\"\n  | \"slot\"\n  | \"spinner\"\n  | \"split-view\"\n  | \"stage-banner\"\n  | \"stat\"\n  | \"status-page\"\n  | \"stepper\"\n  | \"switch\"\n  | \"tabs\"\n  | \"tag-input\"\n  | \"terminal-replay\"\n  | \"theme\"\n  | \"toast\"\n  | \"toc\"\n  | \"tooltip\"\n  | \"txt\"\n  | \"video-player\"\n  | \"video-trimmer\"\n  | \"virtual\";\n\n/** Where a component exists: `@krizaka/ui/<name>` (web), `@krizaka/ui/native` (React Native), or both. */\nexport type Platform = \"web\" | \"native\" | \"both\";\n\n/** `stable`: its API only changes in a major. `beta`: it may still change in a minor. */\nexport type Status = \"stable\" | \"beta\";\n\n/**\n * The group of the catalogue. `media`: video, sound, camera, files, cropping. `blocks`: the page blocks — the frame,\n * the hero, sections, cards that lead or argue, decisions, code, calls to act — that every page of a site is made of.\n * `layouts`: the shells of whole screens — an application, a dashboard, settings, sign-in, an object, a list and its\n * item, a site's page, a documentation page — each with its screens. `templates`: the page templates — whole pages of a\n * site (a landing, a product, a docs hub, a long read, a changelog, pricing, status, an error…), each a distinct\n * composition of the blocks, words and content as props.\n */\nexport type Category = \"actions\" | \"forms\" | \"navigation\" | \"overlays\" | \"feedback\" | \"data-display\" | \"media\" | \"blocks\" | \"layouts\" | \"templates\" | \"layout\" | \"foundations\";\n\n/**\n * A named example: the file `registry/examples/<component>/<name>.tsx` (web) or\n * `registry/examples/<component>/native/<name>.tsx` (React Native) — at most 40 lines, imported by the stories and\n * shown (live, with its code) by the documentation.\n */\nexport interface Example {\n  /** The file name, kebab-case (`primary`, `icon-button`). */\n  readonly name: string;\n  /** A short title (`Primary`, `Icon button`). */\n  readonly title: string;\n  /** One or two sentences: when this variant is the right one. */\n  readonly description: string;\n  /**\n   * A template: a whole screen of a product composed from the platform (a layout and its blocks, real words, its phone\n   * version thought out), copied as a starting point — at most 160 lines, listed on krizaka.com/docs/ui/templates.\n   */\n  readonly template?: boolean;\n}\n\n/** One platform's side of a component. */\nexport interface PlatformDocs {\n  /** The names to import (`[\"Button\", \"IconButton\"]`): from `@krizaka/ui/<name>` on the web, `@krizaka/ui/native` in React Native. */\n  readonly imports: readonly string[];\n  /** The examples, in reading order; the first one is the component's preview. */\n  readonly examples: readonly Example[];\n}\n\n/** The React Native side: the same concept, and what differs from the web API. */\nexport interface NativeDocs extends PlatformDocs {\n  /**\n   * The entry to import from when it is not `@krizaka/ui/native`: a component that needs an Expo module (an optional\n   * peer) has its own, `@krizaka/ui/native/<name>`, so an app that does not use it never installs the module.\n   */\n  readonly entry?: string;\n  /** What differs from the web API (`label` instead of children…); empty for a native-only component. */\n  readonly differences: readonly string[];\n}\n\nexport interface KeyboardInteraction {\n  /** The keys, as written on a keyboard: `Space`, `Enter`, `Arrow keys`, `Esc`, `Tab`. */\n  readonly keys: string;\n  /** What they do. */\n  readonly action: string;\n}\n\nexport interface ComponentMeta {\n  /** The display name: `Button`, `Dropdown menu`. */\n  readonly title: string;\n  /** One sentence: what it is. */\n  readonly summary: string;\n  readonly status: Status;\n  readonly category: Category;\n  /** Must match the sides below: `both` ⇔ `web` and `native`. */\n  readonly platforms: Platform;\n  /** When to reach for it: concrete situations, one per item. */\n  readonly whenToUse: readonly string[];\n  /** When not to — and what to use instead (`use`), when another component is the answer. */\n  readonly whenNotToUse: readonly { readonly when: string; readonly use?: ComponentName }[];\n  /** How to use it well: wording, placement, composition. */\n  readonly bestPractices: readonly string[];\n  readonly accessibility: {\n    /** The keyboard, when it does more than Tab and Enter. */\n    readonly keyboard: readonly KeyboardInteraction[];\n    /** Roles, names and announcements: what the component does, what the app must provide. */\n    readonly notes: readonly string[];\n  };\n  /** The components a reader of this page should know about. */\n  readonly related: readonly ComponentName[];\n  readonly web?: PlatformDocs;\n  readonly native?: NativeDocs;\n}\n"
+      "content": "// The documentation of a component, carried by its code: each primitive has a `meta.ts` beside its source\n// (`src/<name>/meta.ts`; a component that exists only in React Native: `src/native/meta/<name>.ts`). Never built into\n// the package: `scripts/build-registry.mjs` reads them into `registry/<name>.json`, which krizaka.com renders as\n// /docs/ui/<name>, and `scripts/registry.test.mjs` fails when one is missing or incomplete.\n//\n// Why a typed module and not JSDoc tags: the fields are lists and links (`related`, `whenNotToUse[].use`, examples),\n// which a type checks and a comment does not; the file is plain data (erasable TypeScript), so Node reads it without a\n// compiler, and an editor completes it.\n\n/** Every documented component: the web primitives (one entry of the package each) and the native-only ones. */\nexport type ComponentName =\n  | \"achievement\"\n  | \"action-bar\"\n  | \"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  | \"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  | \"longform-page\"\n  | \"marketing-layout\"\n  | \"marquee\"\n  | \"mascot-quote\"\n  | \"mascot-state\"\n  | \"mascots\"\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  | \"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  | \"scroll-stage\"\n  | \"search-field\"\n  | \"section-backdrop\"\n  | \"segmented\"\n  | \"separator\"\n  | \"settings-layout\"\n  | \"skeleton\"\n  | \"slider\"\n  | \"slot\"\n  | \"spinner\"\n  | \"split-view\"\n  | \"stage-banner\"\n  | \"stat\"\n  | \"status-page\"\n  | \"stepper\"\n  | \"swipeable-row\"\n  | \"switch\"\n  | \"tab-bar\"\n  | \"tabs\"\n  | \"tag-input\"\n  | \"terminal-replay\"\n  | \"theme\"\n  | \"toast\"\n  | \"toc\"\n  | \"tooltip\"\n  | \"tree-view\"\n  | \"txt\"\n  | \"video-player\"\n  | \"video-trimmer\"\n  | \"virtual\";\n\n/** Where a component exists: `@krizaka/ui/<name>` (web), `@krizaka/ui/native` (React Native), or both. */\nexport type Platform = \"web\" | \"native\" | \"both\";\n\n/** `stable`: its API only changes in a major. `beta`: it may still change in a minor. */\nexport type Status = \"stable\" | \"beta\";\n\n/**\n * The group of the catalogue. `media`: video, sound, camera, files, cropping. `blocks`: the page blocks — the frame,\n * the hero, sections, cards that lead or argue, decisions, code, calls to act — that every page of a site is made of.\n * `layouts`: the shells of whole screens — an application, a dashboard, settings, sign-in, an object, a list and its\n * item, a site's page, a documentation page — each with its screens. `templates`: the page templates — whole pages of a\n * site (a landing, a product, a docs hub, a long read, a changelog, pricing, status, an error…), each a distinct\n * composition of the blocks, words and content as props.\n */\nexport type Category = \"actions\" | \"forms\" | \"navigation\" | \"overlays\" | \"feedback\" | \"data-display\" | \"media\" | \"blocks\" | \"layouts\" | \"templates\" | \"layout\" | \"foundations\";\n\n/**\n * A named example: the file `registry/examples/<component>/<name>.tsx` (web) or\n * `registry/examples/<component>/native/<name>.tsx` (React Native) — at most 40 lines, imported by the stories and\n * shown (live, with its code) by the documentation.\n */\nexport interface Example {\n  /** The file name, kebab-case (`primary`, `icon-button`). */\n  readonly name: string;\n  /** A short title (`Primary`, `Icon button`). */\n  readonly title: string;\n  /** One or two sentences: when this variant is the right one. */\n  readonly description: string;\n  /**\n   * A template: a whole screen of a product composed from the platform (a layout and its blocks, real words, its phone\n   * version thought out), copied as a starting point — at most 160 lines, listed on krizaka.com/docs/ui/templates.\n   */\n  readonly template?: boolean;\n}\n\n/** One platform's side of a component. */\nexport interface PlatformDocs {\n  /** The names to import (`[\"Button\", \"IconButton\"]`): from `@krizaka/ui/<name>` on the web, `@krizaka/ui/native` in React Native. */\n  readonly imports: readonly string[];\n  /** The examples, in reading order; the first one is the component's preview. */\n  readonly examples: readonly Example[];\n}\n\n/** The React Native side: the same concept, and what differs from the web API. */\nexport interface NativeDocs extends PlatformDocs {\n  /**\n   * The entry to import from when it is not `@krizaka/ui/native`: a component that needs an Expo module (an optional\n   * peer) has its own, `@krizaka/ui/native/<name>`, so an app that does not use it never installs the module.\n   */\n  readonly entry?: string;\n  /** What differs from the web API (`label` instead of children…); empty for a native-only component. */\n  readonly differences: readonly string[];\n}\n\nexport interface KeyboardInteraction {\n  /** The keys, as written on a keyboard: `Space`, `Enter`, `Arrow keys`, `Esc`, `Tab`. */\n  readonly keys: string;\n  /** What they do. */\n  readonly action: string;\n}\n\nexport interface ComponentMeta {\n  /** The display name: `Button`, `Dropdown menu`. */\n  readonly title: string;\n  /** One sentence: what it is. */\n  readonly summary: string;\n  readonly status: Status;\n  readonly category: Category;\n  /** Must match the sides below: `both` ⇔ `web` and `native`. */\n  readonly platforms: Platform;\n  /** When to reach for it: concrete situations, one per item. */\n  readonly whenToUse: readonly string[];\n  /** When not to — and what to use instead (`use`), when another component is the answer. */\n  readonly whenNotToUse: readonly { readonly when: string; readonly use?: ComponentName }[];\n  /** How to use it well: wording, placement, composition. */\n  readonly bestPractices: readonly string[];\n  readonly accessibility: {\n    /** The keyboard, when it does more than Tab and Enter. */\n    readonly keyboard: readonly KeyboardInteraction[];\n    /** Roles, names and announcements: what the component does, what the app must provide. */\n    readonly notes: readonly string[];\n  };\n  /** The components a reader of this page should know about. */\n  readonly related: readonly ComponentName[];\n  readonly web?: PlatformDocs;\n  readonly native?: NativeDocs;\n}\n"
     },
     {
       "path": "video-player/index.ts",

package/registry/video-trimmer.json

@@ -225,7 +225,7 @@
     },
     {
       "path": "meta.ts",
-      "content": "// The documentation of a component, carried by its code: each primitive has a `meta.ts` beside its source\n// (`src/<name>/meta.ts`; a component that exists only in React Native: `src/native/meta/<name>.ts`). Never built into\n// the package: `scripts/build-registry.mjs` reads them into `registry/<name>.json`, which krizaka.com renders as\n// /docs/ui/<name>, and `scripts/registry.test.mjs` fails when one is missing or incomplete.\n//\n// Why a typed module and not JSDoc tags: the fields are lists and links (`related`, `whenNotToUse[].use`, examples),\n// which a type checks and a comment does not; the file is plain data (erasable TypeScript), so Node reads it without a\n// compiler, and an editor completes it.\n\n/** Every documented component: the web primitives (one entry of the package each) and the native-only ones. */\nexport type ComponentName =\n  | \"achievement\"\n  | \"action-bar\"\n  | \"alert\"\n  | \"app-shell\"\n  | \"argument-card\"\n  | \"audio-player\"\n  | \"auth-layout\"\n  | \"avatar\"\n  | \"badge\"\n  | \"button\"\n  | \"card\"\n  | \"card-grid\"\n  | \"catalogue-page\"\n  | \"changelog-page\"\n  | \"checkbox\"\n  | \"chip\"\n  | \"chip-link\"\n  | \"choice-grid\"\n  | \"cn\"\n  | \"code-block\"\n  | \"combobox\"\n  | \"command\"\n  | \"component-page\"\n  | \"confirm-button\"\n  | \"contact-page\"\n  | \"continue-prompt\"\n  | \"countdown\"\n  | \"cta-panel\"\n  | \"dashboard-layout\"\n  | \"data-table\"\n  | \"date-picker\"\n  | \"decision-list\"\n  | \"detail-layout\"\n  | \"dialog\"\n  | \"docs-article-page\"\n  | \"docs-hub-page\"\n  | \"docs-layout\"\n  | \"dropdown-menu\"\n  | \"empty-state\"\n  | \"error-page\"\n  | \"field\"\n  | \"file-upload\"\n  | \"filter-bar\"\n  | \"form\"\n  | \"gallery-page\"\n  | \"glow-card\"\n  | \"goal-gauge\"\n  | \"how-it-works-page\"\n  | \"image-cropper\"\n  | \"iso\"\n  | \"kbd\"\n  | \"landing-page\"\n  | \"landscape\"\n  | \"legal-page\"\n  | \"link-card\"\n  | \"list\"\n  | \"loader\"\n  | \"longform-page\"\n  | \"marketing-layout\"\n  | \"marquee\"\n  | \"mascot-quote\"\n  | \"mascot-state\"\n  | \"mascots\"\n  | \"media-capture\"\n  | \"meter\"\n  | \"nav-bar\"\n  | \"number-ticker\"\n  | \"page\"\n  | \"page-header\"\n  | \"page-hero\"\n  | \"pagination\"\n  | \"pointer-light\"\n  | \"popover\"\n  | \"pricing-page\"\n  | \"product-page\"\n  | \"profile-card\"\n  | \"progress\"\n  | \"promise-card\"\n  | \"radio-group\"\n  | \"scroll-stage\"\n  | \"search-field\"\n  | \"section-backdrop\"\n  | \"segmented\"\n  | \"separator\"\n  | \"settings-layout\"\n  | \"skeleton\"\n  | \"slider\"\n  | \"slot\"\n  | \"spinner\"\n  | \"split-view\"\n  | \"stage-banner\"\n  | \"stat\"\n  | \"status-page\"\n  | \"stepper\"\n  | \"switch\"\n  | \"tabs\"\n  | \"tag-input\"\n  | \"terminal-replay\"\n  | \"theme\"\n  | \"toast\"\n  | \"toc\"\n  | \"tooltip\"\n  | \"txt\"\n  | \"video-player\"\n  | \"video-trimmer\"\n  | \"virtual\";\n\n/** Where a component exists: `@krizaka/ui/<name>` (web), `@krizaka/ui/native` (React Native), or both. */\nexport type Platform = \"web\" | \"native\" | \"both\";\n\n/** `stable`: its API only changes in a major. `beta`: it may still change in a minor. */\nexport type Status = \"stable\" | \"beta\";\n\n/**\n * The group of the catalogue. `media`: video, sound, camera, files, cropping. `blocks`: the page blocks — the frame,\n * the hero, sections, cards that lead or argue, decisions, code, calls to act — that every page of a site is made of.\n * `layouts`: the shells of whole screens — an application, a dashboard, settings, sign-in, an object, a list and its\n * item, a site's page, a documentation page — each with its screens. `templates`: the page templates — whole pages of a\n * site (a landing, a product, a docs hub, a long read, a changelog, pricing, status, an error…), each a distinct\n * composition of the blocks, words and content as props.\n */\nexport type Category = \"actions\" | \"forms\" | \"navigation\" | \"overlays\" | \"feedback\" | \"data-display\" | \"media\" | \"blocks\" | \"layouts\" | \"templates\" | \"layout\" | \"foundations\";\n\n/**\n * A named example: the file `registry/examples/<component>/<name>.tsx` (web) or\n * `registry/examples/<component>/native/<name>.tsx` (React Native) — at most 40 lines, imported by the stories and\n * shown (live, with its code) by the documentation.\n */\nexport interface Example {\n  /** The file name, kebab-case (`primary`, `icon-button`). */\n  readonly name: string;\n  /** A short title (`Primary`, `Icon button`). */\n  readonly title: string;\n  /** One or two sentences: when this variant is the right one. */\n  readonly description: string;\n  /**\n   * A template: a whole screen of a product composed from the platform (a layout and its blocks, real words, its phone\n   * version thought out), copied as a starting point — at most 160 lines, listed on krizaka.com/docs/ui/templates.\n   */\n  readonly template?: boolean;\n}\n\n/** One platform's side of a component. */\nexport interface PlatformDocs {\n  /** The names to import (`[\"Button\", \"IconButton\"]`): from `@krizaka/ui/<name>` on the web, `@krizaka/ui/native` in React Native. */\n  readonly imports: readonly string[];\n  /** The examples, in reading order; the first one is the component's preview. */\n  readonly examples: readonly Example[];\n}\n\n/** The React Native side: the same concept, and what differs from the web API. */\nexport interface NativeDocs extends PlatformDocs {\n  /**\n   * The entry to import from when it is not `@krizaka/ui/native`: a component that needs an Expo module (an optional\n   * peer) has its own, `@krizaka/ui/native/<name>`, so an app that does not use it never installs the module.\n   */\n  readonly entry?: string;\n  /** What differs from the web API (`label` instead of children…); empty for a native-only component. */\n  readonly differences: readonly string[];\n}\n\nexport interface KeyboardInteraction {\n  /** The keys, as written on a keyboard: `Space`, `Enter`, `Arrow keys`, `Esc`, `Tab`. */\n  readonly keys: string;\n  /** What they do. */\n  readonly action: string;\n}\n\nexport interface ComponentMeta {\n  /** The display name: `Button`, `Dropdown menu`. */\n  readonly title: string;\n  /** One sentence: what it is. */\n  readonly summary: string;\n  readonly status: Status;\n  readonly category: Category;\n  /** Must match the sides below: `both` ⇔ `web` and `native`. */\n  readonly platforms: Platform;\n  /** When to reach for it: concrete situations, one per item. */\n  readonly whenToUse: readonly string[];\n  /** When not to — and what to use instead (`use`), when another component is the answer. */\n  readonly whenNotToUse: readonly { readonly when: string; readonly use?: ComponentName }[];\n  /** How to use it well: wording, placement, composition. */\n  readonly bestPractices: readonly string[];\n  readonly accessibility: {\n    /** The keyboard, when it does more than Tab and Enter. */\n    readonly keyboard: readonly KeyboardInteraction[];\n    /** Roles, names and announcements: what the component does, what the app must provide. */\n    readonly notes: readonly string[];\n  };\n  /** The components a reader of this page should know about. */\n  readonly related: readonly ComponentName[];\n  readonly web?: PlatformDocs;\n  readonly native?: NativeDocs;\n}\n"
+      "content": "// The documentation of a component, carried by its code: each primitive has a `meta.ts` beside its source\n// (`src/<name>/meta.ts`; a component that exists only in React Native: `src/native/meta/<name>.ts`). Never built into\n// the package: `scripts/build-registry.mjs` reads them into `registry/<name>.json`, which krizaka.com renders as\n// /docs/ui/<name>, and `scripts/registry.test.mjs` fails when one is missing or incomplete.\n//\n// Why a typed module and not JSDoc tags: the fields are lists and links (`related`, `whenNotToUse[].use`, examples),\n// which a type checks and a comment does not; the file is plain data (erasable TypeScript), so Node reads it without a\n// compiler, and an editor completes it.\n\n/** Every documented component: the web primitives (one entry of the package each) and the native-only ones. */\nexport type ComponentName =\n  | \"achievement\"\n  | \"action-bar\"\n  | \"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  | \"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  | \"longform-page\"\n  | \"marketing-layout\"\n  | \"marquee\"\n  | \"mascot-quote\"\n  | \"mascot-state\"\n  | \"mascots\"\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  | \"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  | \"scroll-stage\"\n  | \"search-field\"\n  | \"section-backdrop\"\n  | \"segmented\"\n  | \"separator\"\n  | \"settings-layout\"\n  | \"skeleton\"\n  | \"slider\"\n  | \"slot\"\n  | \"spinner\"\n  | \"split-view\"\n  | \"stage-banner\"\n  | \"stat\"\n  | \"status-page\"\n  | \"stepper\"\n  | \"swipeable-row\"\n  | \"switch\"\n  | \"tab-bar\"\n  | \"tabs\"\n  | \"tag-input\"\n  | \"terminal-replay\"\n  | \"theme\"\n  | \"toast\"\n  | \"toc\"\n  | \"tooltip\"\n  | \"tree-view\"\n  | \"txt\"\n  | \"video-player\"\n  | \"video-trimmer\"\n  | \"virtual\";\n\n/** Where a component exists: `@krizaka/ui/<name>` (web), `@krizaka/ui/native` (React Native), or both. */\nexport type Platform = \"web\" | \"native\" | \"both\";\n\n/** `stable`: its API only changes in a major. `beta`: it may still change in a minor. */\nexport type Status = \"stable\" | \"beta\";\n\n/**\n * The group of the catalogue. `media`: video, sound, camera, files, cropping. `blocks`: the page blocks — the frame,\n * the hero, sections, cards that lead or argue, decisions, code, calls to act — that every page of a site is made of.\n * `layouts`: the shells of whole screens — an application, a dashboard, settings, sign-in, an object, a list and its\n * item, a site's page, a documentation page — each with its screens. `templates`: the page templates — whole pages of a\n * site (a landing, a product, a docs hub, a long read, a changelog, pricing, status, an error…), each a distinct\n * composition of the blocks, words and content as props.\n */\nexport type Category = \"actions\" | \"forms\" | \"navigation\" | \"overlays\" | \"feedback\" | \"data-display\" | \"media\" | \"blocks\" | \"layouts\" | \"templates\" | \"layout\" | \"foundations\";\n\n/**\n * A named example: the file `registry/examples/<component>/<name>.tsx` (web) or\n * `registry/examples/<component>/native/<name>.tsx` (React Native) — at most 40 lines, imported by the stories and\n * shown (live, with its code) by the documentation.\n */\nexport interface Example {\n  /** The file name, kebab-case (`primary`, `icon-button`). */\n  readonly name: string;\n  /** A short title (`Primary`, `Icon button`). */\n  readonly title: string;\n  /** One or two sentences: when this variant is the right one. */\n  readonly description: string;\n  /**\n   * A template: a whole screen of a product composed from the platform (a layout and its blocks, real words, its phone\n   * version thought out), copied as a starting point — at most 160 lines, listed on krizaka.com/docs/ui/templates.\n   */\n  readonly template?: boolean;\n}\n\n/** One platform's side of a component. */\nexport interface PlatformDocs {\n  /** The names to import (`[\"Button\", \"IconButton\"]`): from `@krizaka/ui/<name>` on the web, `@krizaka/ui/native` in React Native. */\n  readonly imports: readonly string[];\n  /** The examples, in reading order; the first one is the component's preview. */\n  readonly examples: readonly Example[];\n}\n\n/** The React Native side: the same concept, and what differs from the web API. */\nexport interface NativeDocs extends PlatformDocs {\n  /**\n   * The entry to import from when it is not `@krizaka/ui/native`: a component that needs an Expo module (an optional\n   * peer) has its own, `@krizaka/ui/native/<name>`, so an app that does not use it never installs the module.\n   */\n  readonly entry?: string;\n  /** What differs from the web API (`label` instead of children…); empty for a native-only component. */\n  readonly differences: readonly string[];\n}\n\nexport interface KeyboardInteraction {\n  /** The keys, as written on a keyboard: `Space`, `Enter`, `Arrow keys`, `Esc`, `Tab`. */\n  readonly keys: string;\n  /** What they do. */\n  readonly action: string;\n}\n\nexport interface ComponentMeta {\n  /** The display name: `Button`, `Dropdown menu`. */\n  readonly title: string;\n  /** One sentence: what it is. */\n  readonly summary: string;\n  readonly status: Status;\n  readonly category: Category;\n  /** Must match the sides below: `both` ⇔ `web` and `native`. */\n  readonly platforms: Platform;\n  /** When to reach for it: concrete situations, one per item. */\n  readonly whenToUse: readonly string[];\n  /** When not to — and what to use instead (`use`), when another component is the answer. */\n  readonly whenNotToUse: readonly { readonly when: string; readonly use?: ComponentName }[];\n  /** How to use it well: wording, placement, composition. */\n  readonly bestPractices: readonly string[];\n  readonly accessibility: {\n    /** The keyboard, when it does more than Tab and Enter. */\n    readonly keyboard: readonly KeyboardInteraction[];\n    /** Roles, names and announcements: what the component does, what the app must provide. */\n    readonly notes: readonly string[];\n  };\n  /** The components a reader of this page should know about. */\n  readonly related: readonly ComponentName[];\n  readonly web?: PlatformDocs;\n  readonly native?: NativeDocs;\n}\n"
     },
     {
       "path": "video-trimmer/index.ts",

package/registry/virtual.json

@@ -318,7 +318,7 @@
     },
     {
       "path": "meta.ts",
-      "content": "// The documentation of a component, carried by its code: each primitive has a `meta.ts` beside its source\n// (`src/<name>/meta.ts`; a component that exists only in React Native: `src/native/meta/<name>.ts`). Never built into\n// the package: `scripts/build-registry.mjs` reads them into `registry/<name>.json`, which krizaka.com renders as\n// /docs/ui/<name>, and `scripts/registry.test.mjs` fails when one is missing or incomplete.\n//\n// Why a typed module and not JSDoc tags: the fields are lists and links (`related`, `whenNotToUse[].use`, examples),\n// which a type checks and a comment does not; the file is plain data (erasable TypeScript), so Node reads it without a\n// compiler, and an editor completes it.\n\n/** Every documented component: the web primitives (one entry of the package each) and the native-only ones. */\nexport type ComponentName =\n  | \"achievement\"\n  | \"action-bar\"\n  | \"alert\"\n  | \"app-shell\"\n  | \"argument-card\"\n  | \"audio-player\"\n  | \"auth-layout\"\n  | \"avatar\"\n  | \"badge\"\n  | \"button\"\n  | \"card\"\n  | \"card-grid\"\n  | \"catalogue-page\"\n  | \"changelog-page\"\n  | \"checkbox\"\n  | \"chip\"\n  | \"chip-link\"\n  | \"choice-grid\"\n  | \"cn\"\n  | \"code-block\"\n  | \"combobox\"\n  | \"command\"\n  | \"component-page\"\n  | \"confirm-button\"\n  | \"contact-page\"\n  | \"continue-prompt\"\n  | \"countdown\"\n  | \"cta-panel\"\n  | \"dashboard-layout\"\n  | \"data-table\"\n  | \"date-picker\"\n  | \"decision-list\"\n  | \"detail-layout\"\n  | \"dialog\"\n  | \"docs-article-page\"\n  | \"docs-hub-page\"\n  | \"docs-layout\"\n  | \"dropdown-menu\"\n  | \"empty-state\"\n  | \"error-page\"\n  | \"field\"\n  | \"file-upload\"\n  | \"filter-bar\"\n  | \"form\"\n  | \"gallery-page\"\n  | \"glow-card\"\n  | \"goal-gauge\"\n  | \"how-it-works-page\"\n  | \"image-cropper\"\n  | \"iso\"\n  | \"kbd\"\n  | \"landing-page\"\n  | \"landscape\"\n  | \"legal-page\"\n  | \"link-card\"\n  | \"list\"\n  | \"loader\"\n  | \"longform-page\"\n  | \"marketing-layout\"\n  | \"marquee\"\n  | \"mascot-quote\"\n  | \"mascot-state\"\n  | \"mascots\"\n  | \"media-capture\"\n  | \"meter\"\n  | \"nav-bar\"\n  | \"number-ticker\"\n  | \"page\"\n  | \"page-header\"\n  | \"page-hero\"\n  | \"pagination\"\n  | \"pointer-light\"\n  | \"popover\"\n  | \"pricing-page\"\n  | \"product-page\"\n  | \"profile-card\"\n  | \"progress\"\n  | \"promise-card\"\n  | \"radio-group\"\n  | \"scroll-stage\"\n  | \"search-field\"\n  | \"section-backdrop\"\n  | \"segmented\"\n  | \"separator\"\n  | \"settings-layout\"\n  | \"skeleton\"\n  | \"slider\"\n  | \"slot\"\n  | \"spinner\"\n  | \"split-view\"\n  | \"stage-banner\"\n  | \"stat\"\n  | \"status-page\"\n  | \"stepper\"\n  | \"switch\"\n  | \"tabs\"\n  | \"tag-input\"\n  | \"terminal-replay\"\n  | \"theme\"\n  | \"toast\"\n  | \"toc\"\n  | \"tooltip\"\n  | \"txt\"\n  | \"video-player\"\n  | \"video-trimmer\"\n  | \"virtual\";\n\n/** Where a component exists: `@krizaka/ui/<name>` (web), `@krizaka/ui/native` (React Native), or both. */\nexport type Platform = \"web\" | \"native\" | \"both\";\n\n/** `stable`: its API only changes in a major. `beta`: it may still change in a minor. */\nexport type Status = \"stable\" | \"beta\";\n\n/**\n * The group of the catalogue. `media`: video, sound, camera, files, cropping. `blocks`: the page blocks — the frame,\n * the hero, sections, cards that lead or argue, decisions, code, calls to act — that every page of a site is made of.\n * `layouts`: the shells of whole screens — an application, a dashboard, settings, sign-in, an object, a list and its\n * item, a site's page, a documentation page — each with its screens. `templates`: the page templates — whole pages of a\n * site (a landing, a product, a docs hub, a long read, a changelog, pricing, status, an error…), each a distinct\n * composition of the blocks, words and content as props.\n */\nexport type Category = \"actions\" | \"forms\" | \"navigation\" | \"overlays\" | \"feedback\" | \"data-display\" | \"media\" | \"blocks\" | \"layouts\" | \"templates\" | \"layout\" | \"foundations\";\n\n/**\n * A named example: the file `registry/examples/<component>/<name>.tsx` (web) or\n * `registry/examples/<component>/native/<name>.tsx` (React Native) — at most 40 lines, imported by the stories and\n * shown (live, with its code) by the documentation.\n */\nexport interface Example {\n  /** The file name, kebab-case (`primary`, `icon-button`). */\n  readonly name: string;\n  /** A short title (`Primary`, `Icon button`). */\n  readonly title: string;\n  /** One or two sentences: when this variant is the right one. */\n  readonly description: string;\n  /**\n   * A template: a whole screen of a product composed from the platform (a layout and its blocks, real words, its phone\n   * version thought out), copied as a starting point — at most 160 lines, listed on krizaka.com/docs/ui/templates.\n   */\n  readonly template?: boolean;\n}\n\n/** One platform's side of a component. */\nexport interface PlatformDocs {\n  /** The names to import (`[\"Button\", \"IconButton\"]`): from `@krizaka/ui/<name>` on the web, `@krizaka/ui/native` in React Native. */\n  readonly imports: readonly string[];\n  /** The examples, in reading order; the first one is the component's preview. */\n  readonly examples: readonly Example[];\n}\n\n/** The React Native side: the same concept, and what differs from the web API. */\nexport interface NativeDocs extends PlatformDocs {\n  /**\n   * The entry to import from when it is not `@krizaka/ui/native`: a component that needs an Expo module (an optional\n   * peer) has its own, `@krizaka/ui/native/<name>`, so an app that does not use it never installs the module.\n   */\n  readonly entry?: string;\n  /** What differs from the web API (`label` instead of children…); empty for a native-only component. */\n  readonly differences: readonly string[];\n}\n\nexport interface KeyboardInteraction {\n  /** The keys, as written on a keyboard: `Space`, `Enter`, `Arrow keys`, `Esc`, `Tab`. */\n  readonly keys: string;\n  /** What they do. */\n  readonly action: string;\n}\n\nexport interface ComponentMeta {\n  /** The display name: `Button`, `Dropdown menu`. */\n  readonly title: string;\n  /** One sentence: what it is. */\n  readonly summary: string;\n  readonly status: Status;\n  readonly category: Category;\n  /** Must match the sides below: `both` ⇔ `web` and `native`. */\n  readonly platforms: Platform;\n  /** When to reach for it: concrete situations, one per item. */\n  readonly whenToUse: readonly string[];\n  /** When not to — and what to use instead (`use`), when another component is the answer. */\n  readonly whenNotToUse: readonly { readonly when: string; readonly use?: ComponentName }[];\n  /** How to use it well: wording, placement, composition. */\n  readonly bestPractices: readonly string[];\n  readonly accessibility: {\n    /** The keyboard, when it does more than Tab and Enter. */\n    readonly keyboard: readonly KeyboardInteraction[];\n    /** Roles, names and announcements: what the component does, what the app must provide. */\n    readonly notes: readonly string[];\n  };\n  /** The components a reader of this page should know about. */\n  readonly related: readonly ComponentName[];\n  readonly web?: PlatformDocs;\n  readonly native?: NativeDocs;\n}\n"
+      "content": "// The documentation of a component, carried by its code: each primitive has a `meta.ts` beside its source\n// (`src/<name>/meta.ts`; a component that exists only in React Native: `src/native/meta/<name>.ts`). Never built into\n// the package: `scripts/build-registry.mjs` reads them into `registry/<name>.json`, which krizaka.com renders as\n// /docs/ui/<name>, and `scripts/registry.test.mjs` fails when one is missing or incomplete.\n//\n// Why a typed module and not JSDoc tags: the fields are lists and links (`related`, `whenNotToUse[].use`, examples),\n// which a type checks and a comment does not; the file is plain data (erasable TypeScript), so Node reads it without a\n// compiler, and an editor completes it.\n\n/** Every documented component: the web primitives (one entry of the package each) and the native-only ones. */\nexport type ComponentName =\n  | \"achievement\"\n  | \"action-bar\"\n  | \"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  | \"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  | \"longform-page\"\n  | \"marketing-layout\"\n  | \"marquee\"\n  | \"mascot-quote\"\n  | \"mascot-state\"\n  | \"mascots\"\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  | \"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  | \"scroll-stage\"\n  | \"search-field\"\n  | \"section-backdrop\"\n  | \"segmented\"\n  | \"separator\"\n  | \"settings-layout\"\n  | \"skeleton\"\n  | \"slider\"\n  | \"slot\"\n  | \"spinner\"\n  | \"split-view\"\n  | \"stage-banner\"\n  | \"stat\"\n  | \"status-page\"\n  | \"stepper\"\n  | \"swipeable-row\"\n  | \"switch\"\n  | \"tab-bar\"\n  | \"tabs\"\n  | \"tag-input\"\n  | \"terminal-replay\"\n  | \"theme\"\n  | \"toast\"\n  | \"toc\"\n  | \"tooltip\"\n  | \"tree-view\"\n  | \"txt\"\n  | \"video-player\"\n  | \"video-trimmer\"\n  | \"virtual\";\n\n/** Where a component exists: `@krizaka/ui/<name>` (web), `@krizaka/ui/native` (React Native), or both. */\nexport type Platform = \"web\" | \"native\" | \"both\";\n\n/** `stable`: its API only changes in a major. `beta`: it may still change in a minor. */\nexport type Status = \"stable\" | \"beta\";\n\n/**\n * The group of the catalogue. `media`: video, sound, camera, files, cropping. `blocks`: the page blocks — the frame,\n * the hero, sections, cards that lead or argue, decisions, code, calls to act — that every page of a site is made of.\n * `layouts`: the shells of whole screens — an application, a dashboard, settings, sign-in, an object, a list and its\n * item, a site's page, a documentation page — each with its screens. `templates`: the page templates — whole pages of a\n * site (a landing, a product, a docs hub, a long read, a changelog, pricing, status, an error…), each a distinct\n * composition of the blocks, words and content as props.\n */\nexport type Category = \"actions\" | \"forms\" | \"navigation\" | \"overlays\" | \"feedback\" | \"data-display\" | \"media\" | \"blocks\" | \"layouts\" | \"templates\" | \"layout\" | \"foundations\";\n\n/**\n * A named example: the file `registry/examples/<component>/<name>.tsx` (web) or\n * `registry/examples/<component>/native/<name>.tsx` (React Native) — at most 40 lines, imported by the stories and\n * shown (live, with its code) by the documentation.\n */\nexport interface Example {\n  /** The file name, kebab-case (`primary`, `icon-button`). */\n  readonly name: string;\n  /** A short title (`Primary`, `Icon button`). */\n  readonly title: string;\n  /** One or two sentences: when this variant is the right one. */\n  readonly description: string;\n  /**\n   * A template: a whole screen of a product composed from the platform (a layout and its blocks, real words, its phone\n   * version thought out), copied as a starting point — at most 160 lines, listed on krizaka.com/docs/ui/templates.\n   */\n  readonly template?: boolean;\n}\n\n/** One platform's side of a component. */\nexport interface PlatformDocs {\n  /** The names to import (`[\"Button\", \"IconButton\"]`): from `@krizaka/ui/<name>` on the web, `@krizaka/ui/native` in React Native. */\n  readonly imports: readonly string[];\n  /** The examples, in reading order; the first one is the component's preview. */\n  readonly examples: readonly Example[];\n}\n\n/** The React Native side: the same concept, and what differs from the web API. */\nexport interface NativeDocs extends PlatformDocs {\n  /**\n   * The entry to import from when it is not `@krizaka/ui/native`: a component that needs an Expo module (an optional\n   * peer) has its own, `@krizaka/ui/native/<name>`, so an app that does not use it never installs the module.\n   */\n  readonly entry?: string;\n  /** What differs from the web API (`label` instead of children…); empty for a native-only component. */\n  readonly differences: readonly string[];\n}\n\nexport interface KeyboardInteraction {\n  /** The keys, as written on a keyboard: `Space`, `Enter`, `Arrow keys`, `Esc`, `Tab`. */\n  readonly keys: string;\n  /** What they do. */\n  readonly action: string;\n}\n\nexport interface ComponentMeta {\n  /** The display name: `Button`, `Dropdown menu`. */\n  readonly title: string;\n  /** One sentence: what it is. */\n  readonly summary: string;\n  readonly status: Status;\n  readonly category: Category;\n  /** Must match the sides below: `both` ⇔ `web` and `native`. */\n  readonly platforms: Platform;\n  /** When to reach for it: concrete situations, one per item. */\n  readonly whenToUse: readonly string[];\n  /** When not to — and what to use instead (`use`), when another component is the answer. */\n  readonly whenNotToUse: readonly { readonly when: string; readonly use?: ComponentName }[];\n  /** How to use it well: wording, placement, composition. */\n  readonly bestPractices: readonly string[];\n  readonly accessibility: {\n    /** The keyboard, when it does more than Tab and Enter. */\n    readonly keyboard: readonly KeyboardInteraction[];\n    /** Roles, names and announcements: what the component does, what the app must provide. */\n    readonly notes: readonly string[];\n  };\n  /** The components a reader of this page should know about. */\n  readonly related: readonly ComponentName[];\n  readonly web?: PlatformDocs;\n  readonly native?: NativeDocs;\n}\n"
     },
     {
       "path": "virtual/index.ts",

package/skills/choice-controls/SKILL.md

@@ -0,0 +1,39 @@
+---
+name: krizaka-choice-controls
+description: Choices and settings in a Krizaka app (Next.js or Expo) with @krizaka/ui — RadioGroup (dots, cards, tactile keys that press in, segmented), Slider (range, steps and marks, floating value, brand gradient, vertical), Switch, and on React Native Select / Combobox in a Sheet, with haptics through the ThemeProvider. Use it instead of React Native's Switch, a picker module, a hand-made segmented control or a slider library.
+---
+
+# RadioGroup · Slider · Switch · Select · Combobox · Sheet
+
+## Rules
+
+1. Pick by the choice:
+   - two to five options seen at once → `RadioGroup` — `list` (settings), `cards` (an amount, a plan: a line under
+     each), `buttons` (a size, a tip, a level: tactile keys), `segmented` (two to four short words on one line);
+   - many options → web `Select` of `@krizaka/ui/field` (the platform's menu) or `Combobox` (searched); native `Select`
+     / `Combobox` (a field that opens a `Sheet`);
+   - a value by feel within bounds → `Slider` (`ticks` when the steps are few, `marks` to name the ends,
+     `floatingValue` while touched, `orientation="vertical"` for faders); an exact number → a text field;
+   - on / off, applied at once → `Switch` (native: `showLabel` + `description` makes the settings row).
+2. Never React Native's `Switch`, `@react-native-community/slider` or a picker module: the platform's controls are
+   drawn by the theme, the same on iOS and Android, and wear the product's accent.
+3. A segmented control that **switches views** is `Tabs variant="segmented"` (web) / `Segmented` (native); one that is a
+   **form's value** is `RadioGroup variant="segmented"`.
+4. Haptics: `<ThemeProvider haptics={(k) => k === "selection" ? Haptics.selectionAsync() : Haptics.impactAsync(Haptics.ImpactFeedbackStyle.Light)}>`
+   once at the root (expo-haptics). Wheels, slider steps, radios and switches play `selection`; a tactile key `impact`.
+5. Words are props (`label`, `thumbLabels`, `formatValue`, `hint`, `labels`), passed translated. In a form, use the
+   form's fields (`form.RadioGroup variant=…`, `form.Slider`, `form.Switch`, `form.Select`, `form.Combobox`).
+
+## Recipes
+
+```tsx
+<RadioGroup.Root label={t("tip")} variant="buttons" value={tip} onValueChange={setTip}>
+  {TIPS.map((p) => <RadioGroup.Button key={p} value={p} hint={formatMoney(total * p / 100)}>{`${p} %`}</RadioGroup.Button>)}
+</RadioGroup.Root>
+<Slider<[number, number]> label={t("price")} thumbLabels={[t("min"), t("max")]} value={range} onValueChange={setRange}
+  max={250} step={10} floatingValue marks={[{ value: 0, label: "$0" }, { value: 250, label: "$250+" }]} />
+// React Native
+<Switch label={t("push")} description={t("push.hint")} showLabel checked={push} onCheckedChange={setPush} />
+<Select label={t("language")} options={LANGUAGES} value={lang} onValueChange={setLang} />
+<Combobox label={t("city")} onSearch={(q, signal) => searchCities(q, signal)} value={city} onValueChange={setCity} />
+```

package/skills/form/SKILL.md

@@ -40,5 +40,8 @@ const form = signUp.useForm({ i18n: { t }, codeFields: { USERNAME_RESERVED: "use
 - Amounts: `form.Money name="amount" currency="EUR"` stores integer cents (`z.number().int()`).
 - Lists: `<form.FieldArray name="links">{(a) => a.items.map((_, i) => <form.TextField name={`links[${i}].url`} … />)}</form.FieldArray>`.
 - Conditional parts: `<form.Watch name="audience">{(v) => v === "subscribers" ? <form.Money name="price" … /> : null}</form.Watch>`.
+- Controls (DS5): `form.RadioGroup variant="buttons" | "segmented" | "cards"`, `form.DateField entry="wheel" max={latestBirthDate(18)}`,
+  `form.Slider ticks marks={…}` (the value floats while touched). Native: `DateField` is wheels by default, `Select` /
+  `Combobox` open a sheet, `Switch` is a settings row; pass `haptics` to the native `ThemeProvider` for the haptics.
 - Native: `<form.Form scroll>` makes the form the screen's scrolling content above the keyboard; the return key walks the
   text fields and the last one sends; `<form.Submit label=… brand="orochia" />` turns the product's mark while sending.

package/skills/map/SKILL.md

@@ -0,0 +1,35 @@
+---
+name: krizaka-map
+description: Maps in a Krizaka app (Next.js or Expo) with @krizaka/ui/map and @krizaka/ui/native/map — MapLibre (open source) over Protomaps PMTiles on the Krizaka CDN, no API key and no metered service, the style generated from the tokens (dark/light, the product's accent): Map, Marker, Cluster, UserPosition, RadiusCircle, LocationPicker (distance chip, Near me), StaticMap (fallback), mapStyle, distanceMeters. Use it instead of Mapbox, Google Maps, Leaflet with raster tiles or react-native-maps.
+---
+
+# @krizaka/ui/map · @krizaka/ui/native/map
+
+## Rules
+
+1. Never Mapbox or Google Maps (keys, per-view bills): MapLibre + our PMTiles. Install the engine only in the app that
+   shows a map: web `maplibre-gl` (≥ 6), Expo `@maplibre/maplibre-react-native` (≥ 11, with its config plugin and the
+   location usage strings). `pmtiles` and `@protomaps/basemaps` come with `@krizaka/ui`.
+2. Every `Map` has a `label`, every `Marker` / `Cluster` point a `label`: they are the text alternative (a list of places
+   on the web, the map's name on native). Give the web `Map` a `fallback` — a `StaticMap` with the same centre and places.
+3. Pass the product: `brand="orochia"` paints the accent (markers, the water's tint); the scheme follows the page
+   (`html.light`) or the native theme.
+4. Ask for the position only when the person presses Near me (`LocationPicker`); never on load. Every answer has its words
+   (`labels.denied`, `labels.unavailable`), passed translated.
+5. Details of a place: a panel on the web, a `Sheet` (`@krizaka/ui/native`) on a phone, opened from `Marker onPress`.
+6. Tiles: the defaults are the world (zoom 0–6) and Montréal–Québec (to 14). Another region is an extract published by
+   `tools/map-assets.mjs` (krizaka-ui) and passed as `region={{ url, maxzoom }}`. The attribution (OpenStreetMap, ODbL;
+   Protomaps) is drawn by the components — never hide it.
+
+## Recipes
+
+```tsx
+import { Map, Marker, StaticMap, LocationPicker } from "@krizaka/ui/map";
+
+<Map label={t("pickup.title")} center={[-73.59, 45.52]} zoom={13} brand="orochia" className="h-80"
+  fallback={<StaticMap label={t("pickup.title")} center={[-73.59, 45.52]} zoom={13} places={spots} />}>
+  {spots.map((s) => <Marker key={s.id} position={s.position} label={s.label} selected={s.id === chosen} onPress={() => setChosen(s.id)} />)}
+</Map>
+<LocationPicker label={t("meet.point")} locale={locale} value={point} onValueChange={setPoint} radius={1000}
+  labels={{ nearMe: t("meet.nearMe"), denied: t("meet.denied"), distance: (d) => t("meet.distance", { d }) }} />
+```

package/dist/chunk-I5RVM5CW.js.map

@@ -1 +0,0 @@
-{"version":3,"sources":["../src/cn.ts","../src/floating.ts"],"sourcesContent":["import { type ClassValue, clsx } from \"clsx\";\nimport { cnMerge, type TWMergeConfig } from \"tailwind-variants\";\n\nexport type { ClassValue };\n\n/**\n * The preset's own utilities, told to the merge engine: the material (BRAND.md §6: `bg-sheen`, `bg-fill-shade`,\n * `bg-halo` are background images; `shadow-raised` · `-floating` · `-overlay` · `-glow` are shadows; `inset-shadow-edge`\n * · `-edge-fill` · `-well` are inset shadows). Unknown, tailwind-merge would take `bg-sheen` for a colour and drop the\n * `bg-surface-2` it lies on.\n */\nexport const twMergeConfig: TWMergeConfig = {\n  extend: {\n    classGroups: {\n      \"bg-image\": [\"bg-sheen\", \"bg-fill-shade\", \"bg-halo\"],\n      shadow: [\"shadow-raised\", \"shadow-floating\", \"shadow-overlay\", \"shadow-glow\", \"shadow-glow-lg\"],\n      \"inset-shadow\": [\"inset-shadow-edge\", \"inset-shadow-edge-fill\", \"inset-shadow-well\"],\n    },\n  },\n};\n\n/**\n * Merges Tailwind classes: the last one wins — a product's `className` overrides the primitive's. The merge engine is\n * tailwind-merge as tailwind-variants ships it (the one `tv` uses), so the platform carries a single copy of it.\n * tailwind-variants bundles that engine since 3.3 (it never imports the `tailwind-merge` package, an optional peer):\n * hence `tailwind-variants ^3.3.1` and no `tailwind-merge` dependency — `scripts/consumer.mjs` checks it on a clean\n * install of the packed package.\n */\nexport function cn(...inputs: ClassValue[]): string {\n  return cnMerge(clsx(inputs))({ twMergeConfig }) ?? \"\";\n}\n","// The one surface of everything that floats next to its trigger (popover, menu, tooltip): a raised surface, a border,\n// the large shadow and the `kz-pop` entrance from the side Radix measured (`--radix-*-transform-origin`).\nexport const floating =\n  \"kz-pop z-50 rounded-lg border border-border-default bg-surface-2 text-fg shadow-lg outline-hidden\";\n"],"mappings":";;;AAAA,SAA0B,YAAY;AACtC,SAAS,eAAmC;AAUrC,IAAM,gBAA+B;AAAA,EAC1C,QAAQ;AAAA,IACN,aAAa;AAAA,MACX,YAAY,CAAC,YAAY,iBAAiB,SAAS;AAAA,MACnD,QAAQ,CAAC,iBAAiB,mBAAmB,kBAAkB,eAAe,gBAAgB;AAAA,MAC9F,gBAAgB,CAAC,qBAAqB,0BAA0B,mBAAmB;AAAA,IACrF;AAAA,EACF;AACF;AASO,SAAS,MAAM,QAA8B;AAClD,SAAO,QAAQ,KAAK,MAAM,CAAC,EAAE,EAAE,cAAc,CAAC,KAAK;AACrD;;;AC5BO,IAAM,WACX;","names":[]}