@krizaka/ui 2.2.0 → 2.4.0

package/registry/kbd.json

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

package/registry/loader.json

@@ -0,0 +1,399 @@
+{
+  "name": "loader",
+  "type": "primitive",
+  "title": "Loader",
+  "summary": "A wait from start to end: nothing for the first instants, then the Krizaka glyph with its words, a percentage and an ETA, held long enough to read, ending on a check or a cross that is drawn and announced — and `LoadingRegion`, which hands a region over to a skeleton of its shape.",
+  "description": "A wait from start to end: nothing for the first instants, then the Krizaka glyph with its words, a percentage and an ETA, held long enough to read, ending on a check or a cross that is drawn and announced — and `LoadingRegion`, which hands a region over to a skeleton of its shape.",
+  "status": "beta",
+  "category": "feedback",
+  "platforms": "web",
+  "whenToUse": [
+    "Any wait whose length you do not control (a fetch, a refresh): the delay keeps fast answers from flashing a spinner.",
+    "A wait that ends in a result worth saying — “12 invoices loaded”, “Could not publish”.",
+    "Over a region that stays readable while it refreshes (`variant=\"overlay\"`), or over the whole screen at start-up (`page`).",
+    "`LoadingRegion` for a card, a list or a panel: a skeleton of its shape while it loads, words when it lasts."
+  ],
+  "whenNotToUse": [
+    {
+      "when": "Inside the button that started the action: the button draws the same glyph.",
+      "use": "button"
+    },
+    {
+      "when": "For a long task with steps or a known size the user follows.",
+      "use": "progress"
+    },
+    {
+      "when": "A tiny wait glyph with nothing else.",
+      "use": "spinner"
+    }
+  ],
+  "bestPractices": [
+    "Say what is loading (“Loading your invoices”), not “Loading…”; say how it ended with `successLabel` / `errorLabel`.",
+    "Keep the defaults: 250 ms of delay, 600 ms at least once shown — the two numbers that stop flicker.",
+    "Give an `eta` when you can estimate it (format durations with `@krizaka/intl`): a known wait feels shorter.",
+    "With `LoadingRegion`, draw the skeleton the shape of the content: nothing moves when it arrives."
+  ],
+  "accessibility": {
+    "keyboard": [],
+    "notes": [
+      "`role=\"status\"` (polite) is present from the first render, so its words are announced when the wait shows and again when it ends.",
+      "`LoadingRegion` sets `aria-busy` on the region while it waits; the skeleton is hidden from assistive technology and the wait is announced once.",
+      "Under `prefers-reduced-motion` the glyph rests on a still frame and endings do not animate; the delay, the words and the announcements stay."
+    ]
+  },
+  "related": [
+    "spinner",
+    "skeleton",
+    "progress",
+    "button"
+  ],
+  "web": {
+    "entry": "@krizaka/ui/loader",
+    "import": "import { Loader, LoadingRegion, useDelayedWait } from \"@krizaka/ui/loader\";",
+    "props": [
+      {
+        "component": "Loader",
+        "description": "A wait, from start to end. `role=\"status\"` (polite): its words are announced when it shows and when it ends. Under\nprefers-reduced-motion the glyph rests on a still frame; the delay and the ending stay.",
+        "props": [
+          {
+            "name": "label",
+            "type": "string",
+            "default": null,
+            "description": "What is loading, in words (“Loading your invoices”) — passed translated; shown and announced.",
+            "required": true
+          },
+          {
+            "name": "delay",
+            "type": "number",
+            "default": "250",
+            "description": "Milliseconds before anything shows: a wait shorter than this never flashes.",
+            "required": false
+          },
+          {
+            "name": "endDuration",
+            "type": "number",
+            "default": "1600",
+            "description": "Milliseconds the ending (check or cross) stays before the loader disappears; `0` never shows it, `Infinity` keeps it.",
+            "required": false
+          },
+          {
+            "name": "errorLabel",
+            "type": "string",
+            "default": null,
+            "description": "The words of a failure (“Could not load the invoices”) — passed translated.",
+            "required": false
+          },
+          {
+            "name": "eta",
+            "type": "string",
+            "default": null,
+            "description": "The time left, in words (“About 20 s left”) — passed translated (`@krizaka/intl` formats durations).",
+            "required": false
+          },
+          {
+            "name": "minDuration",
+            "type": "number",
+            "default": "600",
+            "description": "Once shown, the least milliseconds it stays: it never blinks.",
+            "required": false
+          },
+          {
+            "name": "status",
+            "type": "\"success\" | \"loading\" | \"error\"",
+            "default": "loading",
+            "description": "loading · success · error. When the wait ends, the loader shows how it ended for `endDuration` ms, then disappears.",
+            "required": false
+          },
+          {
+            "name": "successLabel",
+            "type": "string",
+            "default": null,
+            "description": "The words of a success (“Invoices loaded”) — passed translated. Default: nothing more than the check.",
+            "required": false
+          },
+          {
+            "name": "value",
+            "type": "number | null",
+            "default": null,
+            "description": "Between 0 and 1: a determinate wait — the trace grows to it and the percentage shows.",
+            "required": false
+          },
+          {
+            "name": "variant",
+            "type": "\"inline\" | \"page\" | \"overlay\" | \"block\"",
+            "default": "inline",
+            "description": "inline (beside the content) · block (a region's centre) · overlay (over a `relative` parent, frosted) · page (the\nwhole screen).",
+            "required": false
+          }
+        ]
+      },
+      {
+        "component": "LoadingRegion",
+        "description": "A region that hands over: its content → (after `delay`) a skeleton of the same shape → (after `slowAfter`) words over\nthe skeleton → its content again, fading in. `aria-busy` while it waits; the wait is announced once.",
+        "props": [
+          {
+            "name": "label",
+            "type": "string",
+            "default": null,
+            "description": "What is loading, in words — passed translated; announced when the wait shows.",
+            "required": true
+          },
+          {
+            "name": "loading",
+            "type": "boolean",
+            "default": null,
+            "description": "Whether the content is on its way.",
+            "required": true
+          },
+          {
+            "name": "skeleton",
+            "type": "ReactNode",
+            "default": null,
+            "description": "What stands in while it loads: skeletons the shape of the content (no layout shift when it arrives).",
+            "required": true
+          },
+          {
+            "name": "delay",
+            "type": "number",
+            "default": "200",
+            "description": "Milliseconds before the skeleton shows: a fast answer goes straight to the content.",
+            "required": false
+          },
+          {
+            "name": "minDuration",
+            "type": "number",
+            "default": "500",
+            "description": "Once shown, the least milliseconds the skeleton stays.",
+            "required": false
+          },
+          {
+            "name": "slowAfter",
+            "type": "number",
+            "default": "4000",
+            "description": "Milliseconds of skeleton before the words of a long wait appear over it.",
+            "required": false
+          },
+          {
+            "name": "slowLabel",
+            "type": "string",
+            "default": null,
+            "description": "The words when the wait grows long (“Still loading — the server is busy”) — passed translated.",
+            "required": false
+          }
+        ]
+      }
+    ],
+    "examples": [
+      {
+        "name": "fetch-flow",
+        "title": "No flash, then a result",
+        "description": "A fast answer shows nothing; a slow one shows the wait, then “12 invoices loaded” with a check, then nothing.",
+        "path": "examples/loader/fetch-flow.tsx",
+        "module": "@krizaka/ui/registry/examples/loader/fetch-flow",
+        "code": "\"use client\";\nimport { Button } from \"@krizaka/ui/button\";\nimport { Loader } from \"@krizaka/ui/loader\";\nimport { useState } from \"react\";\n\n// Try both: a fast answer (150 ms) shows nothing at all; a slow one shows the wait, then a check, then nothing.\nexport default function LoaderFetchFlow() {\n  const [status, setStatus] = useState<\"idle\" | \"loading\" | \"success\">(\"idle\");\n  const run = (ms: number) => {\n    setStatus(\"loading\");\n    setTimeout(() => setStatus(\"success\"), ms);\n  };\n  return (\n    <div className=\"flex flex-col gap-4\">\n      <div className=\"flex gap-2\">\n        <Button size=\"sm\" onClick={() => run(150)}>Fast answer</Button>\n        <Button size=\"sm\" onClick={() => run(2500)}>Slow answer</Button>\n      </div>\n      <div className=\"h-10\">\n        {status !== \"idle\" && <Loader status={status} label=\"Loading your invoices\" successLabel=\"12 invoices loaded\" />}\n      </div>\n    </div>\n  );\n}\n"
+      },
+      {
+        "name": "region-handover",
+        "title": "Hand-over to a skeleton",
+        "description": "`LoadingRegion`: a skeleton of the card's shape, words when it lasts, the card fading in.",
+        "path": "examples/loader/region-handover.tsx",
+        "module": "@krizaka/ui/registry/examples/loader/region-handover",
+        "code": "\"use client\";\nimport { Button } from \"@krizaka/ui/button\";\nimport { LoadingRegion } from \"@krizaka/ui/loader\";\nimport { Skeleton } from \"@krizaka/ui/skeleton\";\nimport { useState } from \"react\";\n\n// Press “Load again”: the region hands over — a skeleton of its shape → words when it lasts → the content, fading in.\nexport default function LoaderRegionHandover() {\n  const [loading, setLoading] = useState(false);\n  const card = \"flex items-center gap-3 rounded-xl border border-border-default bg-surface-1 p-4\";\n  return (\n    <div className=\"flex w-full max-w-sm flex-col gap-3\">\n      <LoadingRegion\n        loading={loading}\n        label=\"Loading the creator\"\n        slowLabel=\"Still loading — the server is busy\"\n        slowAfter={2500}\n        delay={0}\n        skeleton={<div className={card}><Skeleton shape=\"circle\" /><div className=\"flex flex-1 flex-col gap-2\"><Skeleton className=\"w-1/2\" /><Skeleton className=\"w-3/4\" /></div></div>}\n      >\n        <div className={card}>\n          <span aria-hidden className=\"h-10 w-10 rounded-full bg-accent-soft\" />\n          <div><p className=\"font-semibold text-fg\">Eric Moreau</p><p className=\"text-sm text-fg-secondary\">1,204 supporters</p></div>\n        </div>\n      </LoadingRegion>\n      <Button size=\"sm\" onClick={() => setLoading((l) => !l)}>{loading ? \"Finish loading\" : \"Load again\"}</Button>\n    </div>\n  );\n}\n"
+      },
+      {
+        "name": "upload-eta",
+        "title": "Progress and ETA",
+        "description": "`value` and `eta`: the trace grows, the percentage and the time left read in tabular figures.",
+        "path": "examples/loader/upload-eta.tsx",
+        "module": "@krizaka/ui/registry/examples/loader/upload-eta",
+        "code": "import { Loader } from \"@krizaka/ui/loader\";\n\n// A determinate wait with its time left: the trace grows, the percentage and the ETA read in tabular figures.\nexport default function LoaderUploadEta() {\n  return (\n    <div className=\"w-full max-w-sm rounded-xl border border-border-default bg-surface-1 p-4\">\n      <Loader label=\"Uploading “Night walk.mp4”\" value={0.62} eta=\"About 40 s left\" delay={0} />\n    </div>\n  );\n}\n"
+      },
+      {
+        "name": "overlay",
+        "title": "Over a region",
+        "description": "`variant=\"overlay\"`: the report stays readable behind frosted glass while it refreshes.",
+        "path": "examples/loader/overlay.tsx",
+        "module": "@krizaka/ui/registry/examples/loader/overlay",
+        "code": "import { Loader } from \"@krizaka/ui/loader\";\n\n// Over a region that stays readable behind frosted glass: `variant=\"overlay\"` in a `relative` parent.\nexport default function LoaderOverlay() {\n  return (\n    <div className=\"relative w-full max-w-sm rounded-xl border border-border-default bg-surface-1 p-5\">\n      <p className=\"font-semibold text-fg\">Monthly report</p>\n      <p className=\"mt-1 text-sm text-fg-secondary\">Revenue, supporters and payouts for October.</p>\n      <div className=\"mt-4 h-24 rounded-lg bg-surface-2\" />\n      <Loader variant=\"overlay\" label=\"Refreshing the report\" eta=\"A few seconds\" delay={0} />\n    </div>\n  );\n}\n"
+      },
+      {
+        "name": "endings",
+        "title": "Endings",
+        "description": "`status`: a success and a failure, drawn in their colour and said in words.",
+        "path": "examples/loader/endings.tsx",
+        "module": "@krizaka/ui/registry/examples/loader/endings",
+        "code": "import { Loader } from \"@krizaka/ui/loader\";\n\n// How a wait ends: drawn (a check or a cross in the status colour) and announced in words.\nexport default function LoaderEndings() {\n  return (\n    <div className=\"flex flex-col gap-3\">\n      <Loader status=\"success\" label=\"Publishing\" successLabel=\"Published\" endDuration={Infinity} delay={0} minDuration={0} />\n      <Loader status=\"error\" label=\"Publishing\" errorLabel=\"Could not publish — check your connection\" endDuration={Infinity} delay={0} minDuration={0} />\n    </div>\n  );\n}\n"
+      },
+      {
+        "name": "minimal",
+        "title": "Minimal",
+        "description": "A label, nothing else: the defaults do the rest.",
+        "path": "examples/loader/minimal.tsx",
+        "module": "@krizaka/ui/registry/examples/loader/minimal",
+        "code": "import { Loader } from \"@krizaka/ui/loader\";\n\n// The minimal API: a label. It appears after 250 ms and stays at least 600 ms once shown.\nexport default function LoaderMinimal() {\n  return <Loader label=\"Loading\" delay={0} />;\n}\n"
+      }
+    ]
+  },
+  "native": null,
+  "files": [
+    {
+      "path": "loader/index.ts",
+      "content": "/** @krizaka/ui/loader — `Loader` (a wait from start to end: delay, glyph, ETA, ending), `LoadingRegion` (content ⇄ skeleton hand-over), `useDelayedWait`. Client. */\nexport { Loader, loader, type LoaderProps, type LoaderVariants, LoadingRegion, type LoadingRegionProps, useDelayedWait } from \"./loader\";\n"
+    },
+    {
+      "path": "loader/loader.tsx",
+      "content": "// Client (timers). The whole life of a wait, done right once: nothing for the first instants (a fast answer never\n// flashes a spinner), then the Krizaka glyph with its words and an ETA, held long enough to be read, ending on a\n// check or a cross that is drawn and announced. `LoadingRegion` hands a region over from its content to a skeleton of\n// the same shape, then to words when the wait grows long, then back to the content.\nimport * as React from \"react\";\nimport { tv, type VariantProps } from \"tailwind-variants\";\n\nimport { LoaderGlyph } from \"../spinner/glyph\";\n\nexport const loader = tv({\n  slots: {\n    root: \"text-fg-secondary\",\n    box: \"kz-fade flex items-center gap-3\",\n    glyph: \"shrink-0 text-accent\",\n    text: \"flex min-w-0 flex-col\",\n    label: \"font-medium text-fg\",\n    detail: \"text-xs text-fg-secondary tabular-nums\",\n  },\n  variants: {\n    variant: {\n      inline: { box: \"text-sm\", glyph: \"h-5 w-5\" },\n      block: { box: \"flex-col justify-center py-10 text-center text-sm\", glyph: \"h-9 w-9\", text: \"items-center\" },\n      overlay: {\n        root: \"absolute inset-0 z-10 flex items-center justify-center rounded-[inherit] empty:hidden\",\n        box: \"flex-col rounded-xl border border-border-default bg-surface-1/90 px-6 py-5 text-center text-sm shadow-lg backdrop-blur-sm\",\n        glyph: \"h-9 w-9\",\n        text: \"items-center\",\n      },\n      page: {\n        root: \"fixed inset-0 z-50 flex items-center justify-center bg-surface-0/80 backdrop-blur-sm empty:hidden\",\n        box: \"flex-col text-center\",\n        glyph: \"h-14 w-14\",\n        text: \"items-center\",\n        label: \"font-display text-lg\",\n      },\n    },\n    ended: {\n      success: { glyph: \"text-fg-success\" },\n      error: { glyph: \"text-fg-danger\" },\n    },\n  },\n  defaultVariants: { variant: \"inline\" },\n});\n\nexport type LoaderVariants = VariantProps<typeof loader>;\n\n/**\n * `true` once `active` has lasted `delay` ms; then stays `true` at least `minDuration` ms — a wait that ends early never\n * shows, one that shows never blinks.\n */\nexport function useDelayedWait(active: boolean, delay = 250, minDuration = 600): boolean {\n  const [shown, setShown] = React.useState(false);\n  const since = React.useRef(0);\n  React.useEffect(() => {\n    if (active === shown) return;\n    const wait = active ? delay : Math.max(0, minDuration - (Date.now() - since.current));\n    const timer = setTimeout(() => {\n      since.current = Date.now();\n      setShown(active);\n    }, wait);\n    return () => clearTimeout(timer);\n  }, [active, shown, delay, minDuration]);\n  return shown;\n}\n\nexport interface LoaderProps extends Omit<React.ComponentProps<\"div\">, \"children\"> {\n  /** What is loading, in words (“Loading your invoices”) — passed translated; shown and announced. */\n  label: string;\n  /**\n   * loading · success · error. When the wait ends, the loader shows how it ended for `endDuration` ms, then disappears.\n   * @default \"loading\"\n   */\n  status?: \"loading\" | \"success\" | \"error\";\n  /** The words of a success (“Invoices loaded”) — passed translated. Default: nothing more than the check. */\n  successLabel?: string;\n  /** The words of a failure (“Could not load the invoices”) — passed translated. */\n  errorLabel?: string;\n  /** Between 0 and 1: a determinate wait — the trace grows to it and the percentage shows. */\n  value?: number | null;\n  /** The time left, in words (“About 20 s left”) — passed translated (`@krizaka/intl` formats durations). */\n  eta?: string;\n  /**\n   * Milliseconds before anything shows: a wait shorter than this never flashes.\n   * @default 250\n   */\n  delay?: number;\n  /**\n   * Once shown, the least milliseconds it stays: it never blinks.\n   * @default 600\n   */\n  minDuration?: number;\n  /**\n   * Milliseconds the ending (check or cross) stays before the loader disappears; `0` never shows it, `Infinity` keeps it.\n   * @default 1600\n   */\n  endDuration?: number;\n  /**\n   * inline (beside the content) · block (a region's centre) · overlay (over a `relative` parent, frosted) · page (the\n   * whole screen).\n   * @default \"inline\"\n   */\n  variant?: LoaderVariants[\"variant\"];\n}\n\n/**\n * A wait, from start to end. `role=\"status\"` (polite): its words are announced when it shows and when it ends. Under\n * prefers-reduced-motion the glyph rests on a still frame; the delay and the ending stay.\n */\nexport function Loader({\n  label,\n  status = \"loading\",\n  successLabel,\n  errorLabel,\n  value,\n  eta,\n  delay = 250,\n  minDuration = 600,\n  endDuration = 1600,\n  variant,\n  className,\n  ...props\n}: LoaderProps) {\n  const waiting = useDelayedWait(status === \"loading\", delay, minDuration);\n  // Rendered already ended (a result to show), it shows its ending; otherwise only a wait that was seen ends visibly.\n  const [ending, setEnding] = React.useState<\"success\" | \"error\" | null>(() => (status !== \"loading\" && endDuration > 0 ? status : null));\n  const wasWaiting = React.useRef(false);\n  React.useEffect(() => {\n    if (!Number.isFinite(endDuration)) return;\n    const hide = setTimeout(() => setEnding((e) => (wasWaiting.current ? e : null)), endDuration);\n    return () => clearTimeout(hide);\n    // Only the ending a loader was mounted with: later endings have their own timer below.\n    // eslint-disable-next-line react-hooks/exhaustive-deps\n  }, []);\n  React.useEffect(() => {\n    if (waiting) {\n      wasWaiting.current = true;\n      return;\n    }\n    if (!wasWaiting.current || status === \"loading\") return;\n    wasWaiting.current = false;\n    const end = status;\n    const show = setTimeout(() => setEnding(endDuration > 0 ? end : null), 0);\n    const hide = Number.isFinite(endDuration) ? setTimeout(() => setEnding(null), endDuration) : undefined;\n    return () => {\n      clearTimeout(show);\n      clearTimeout(hide);\n    };\n  }, [waiting, status, endDuration]);\n\n  const phase = waiting ? \"loading\" : ending;\n  const s = loader({ variant, ended: phase === \"success\" || phase === \"error\" ? phase : undefined });\n  const known = phase === \"loading\" && typeof value === \"number\" && Number.isFinite(value);\n  const words = phase === \"success\" ? (successLabel ?? label) : phase === \"error\" ? (errorLabel ?? label) : label;\n  const detail = phase === \"loading\" ? [known ? `${Math.round(Math.min(1, Math.max(0, value)) * 100)} %` : null, eta].filter(Boolean).join(\" · \") : \"\";\n  return (\n    <div role=\"status\" aria-live=\"polite\" data-phase={phase ?? \"idle\"} className={s.root({ className })} {...props}>\n      {phase && (\n        <div className={s.box()}>\n          <LoaderGlyph state={phase} value={known ? value : null} className={s.glyph()} />\n          <span className={s.text()}>\n            <span className={s.label()}>{words}</span>\n            {detail && <span className={s.detail()}>{detail}</span>}\n          </span>\n        </div>\n      )}\n    </div>\n  );\n}\n\nexport interface LoadingRegionProps extends React.ComponentProps<\"div\"> {\n  /** Whether the content is on its way. */\n  loading: boolean;\n  /** What stands in while it loads: skeletons the shape of the content (no layout shift when it arrives). */\n  skeleton: React.ReactNode;\n  /** What is loading, in words — passed translated; announced when the wait shows. */\n  label: string;\n  /** The words when the wait grows long (“Still loading — the server is busy”) — passed translated. */\n  slowLabel?: string;\n  /**\n   * Milliseconds of skeleton before the words of a long wait appear over it.\n   * @default 4000\n   */\n  slowAfter?: number;\n  /**\n   * Milliseconds before the skeleton shows: a fast answer goes straight to the content.\n   * @default 200\n   */\n  delay?: number;\n  /**\n   * Once shown, the least milliseconds the skeleton stays.\n   * @default 500\n   */\n  minDuration?: number;\n}\n\n/**\n * A region that hands over: its content → (after `delay`) a skeleton of the same shape → (after `slowAfter`) words over\n * the skeleton → its content again, fading in. `aria-busy` while it waits; the wait is announced once.\n */\nexport function LoadingRegion({\n  loading,\n  skeleton,\n  label,\n  slowLabel,\n  slowAfter = 4000,\n  delay = 200,\n  minDuration = 500,\n  className,\n  children,\n  ...props\n}: LoadingRegionProps) {\n  const waiting = useDelayedWait(loading, delay, minDuration);\n  const slow = useDelayedWait(waiting && loading, slowAfter, 0);\n  const busy = loading || waiting;\n  return (\n    <div aria-busy={busy} data-phase={waiting ? (slow ? \"slow\" : \"skeleton\") : busy ? \"pending\" : \"ready\"} className={[\"relative\", className].filter(Boolean).join(\" \")} {...props}>\n      <span role=\"status\" className=\"sr-only\">\n        {waiting ? (slow ? (slowLabel ?? label) : label) : \"\"}\n      </span>\n      {waiting ? (\n        <div aria-hidden className=\"kz-fade\">\n          {skeleton}\n        </div>\n      ) : busy ? (\n        // Within the delay: the skeleton holds the place, invisible — nothing flashes, nothing jumps.\n        <div aria-hidden className=\"invisible\">\n          {skeleton}\n        </div>\n      ) : (\n        <div className=\"kz-fade\">{children}</div>\n      )}\n      {waiting && slow && <Loader label={slowLabel ?? label} variant=\"overlay\" delay={0} minDuration={0} endDuration={0} aria-live=\"off\" role=\"presentation\" />}\n    </div>\n  );\n}\n"
+    },
+    {
+      "path": "loader/meta.ts",
+      "content": "import type { ComponentMeta } from \"../meta\";\n\nexport const meta = {\n  title: \"Loader\",\n  summary:\n    \"A wait from start to end: nothing for the first instants, then the Krizaka glyph with its words, a percentage and an ETA, held long enough to read, ending on a check or a cross that is drawn and announced — and `LoadingRegion`, which hands a region over to a skeleton of its shape.\",\n  status: \"beta\",\n  category: \"feedback\",\n  platforms: \"web\",\n  whenToUse: [\n    \"Any wait whose length you do not control (a fetch, a refresh): the delay keeps fast answers from flashing a spinner.\",\n    \"A wait that ends in a result worth saying — “12 invoices loaded”, “Could not publish”.\",\n    \"Over a region that stays readable while it refreshes (`variant=\\\"overlay\\\"`), or over the whole screen at start-up (`page`).\",\n    \"`LoadingRegion` for a card, a list or a panel: a skeleton of its shape while it loads, words when it lasts.\",\n  ],\n  whenNotToUse: [\n    { when: \"Inside the button that started the action: the button draws the same glyph.\", use: \"button\" },\n    { when: \"For a long task with steps or a known size the user follows.\", use: \"progress\" },\n    { when: \"A tiny wait glyph with nothing else.\", use: \"spinner\" },\n  ],\n  bestPractices: [\n    \"Say what is loading (“Loading your invoices”), not “Loading…”; say how it ended with `successLabel` / `errorLabel`.\",\n    \"Keep the defaults: 250 ms of delay, 600 ms at least once shown — the two numbers that stop flicker.\",\n    \"Give an `eta` when you can estimate it (format durations with `@krizaka/intl`): a known wait feels shorter.\",\n    \"With `LoadingRegion`, draw the skeleton the shape of the content: nothing moves when it arrives.\",\n  ],\n  accessibility: {\n    keyboard: [],\n    notes: [\n      \"`role=\\\"status\\\"` (polite) is present from the first render, so its words are announced when the wait shows and again when it ends.\",\n      \"`LoadingRegion` sets `aria-busy` on the region while it waits; the skeleton is hidden from assistive technology and the wait is announced once.\",\n      \"Under `prefers-reduced-motion` the glyph rests on a still frame and endings do not animate; the delay, the words and the announcements stay.\",\n    ],\n  },\n  related: [\"spinner\", \"skeleton\", \"progress\", \"button\"],\n  web: {\n    imports: [\"Loader\", \"LoadingRegion\", \"useDelayedWait\"],\n    examples: [\n      { name: \"fetch-flow\", title: \"No flash, then a result\", description: \"A fast answer shows nothing; a slow one shows the wait, then “12 invoices loaded” with a check, then nothing.\" },\n      { name: \"region-handover\", title: \"Hand-over to a skeleton\", description: \"`LoadingRegion`: a skeleton of the card's shape, words when it lasts, the card fading in.\" },\n      { name: \"upload-eta\", title: \"Progress and ETA\", description: \"`value` and `eta`: the trace grows, the percentage and the time left read in tabular figures.\" },\n      { name: \"overlay\", title: \"Over a region\", description: \"`variant=\\\"overlay\\\"`: the report stays readable behind frosted glass while it refreshes.\" },\n      { name: \"endings\", title: \"Endings\", description: \"`status`: a success and a failure, drawn in their colour and said in words.\" },\n      { name: \"minimal\", title: \"Minimal\", description: \"A label, nothing else: the defaults do the rest.\" },\n    ],\n  },\n} satisfies ComponentMeta;\n"
+    },
+    {
+      "path": "meta.ts",
+      "content": "// The documentation of a component, carried by its code: each primitive has a `meta.ts` beside its source\n// (`src/<name>/meta.ts`; a component that exists only in React Native: `src/native/meta/<name>.ts`). Never built into\n// the package: `scripts/build-registry.mjs` reads them into `registry/<name>.json`, which krizaka.com renders as\n// /docs/ui/<name>, and `scripts/registry.test.mjs` fails when one is missing or incomplete.\n//\n// Why a typed module and not JSDoc tags: the fields are lists and links (`related`, `whenNotToUse[].use`, examples),\n// which a type checks and a comment does not; the file is plain data (erasable TypeScript), so Node reads it without a\n// compiler, and an editor completes it.\n\n/** Every documented component: the web primitives (one entry of the package each) and the native-only ones. */\nexport type ComponentName =\n  | \"alert\"\n  | \"audio-player\"\n  | \"avatar\"\n  | \"badge\"\n  | \"button\"\n  | \"card\"\n  | \"checkbox\"\n  | \"chip\"\n  | \"chip-link\"\n  | \"cn\"\n  | \"combobox\"\n  | \"command\"\n  | \"confirm-button\"\n  | \"countdown\"\n  | \"data-table\"\n  | \"date-picker\"\n  | \"dialog\"\n  | \"dropdown-menu\"\n  | \"empty-state\"\n  | \"field\"\n  | \"file-upload\"\n  | \"filter-bar\"\n  | \"glow-card\"\n  | \"image-cropper\"\n  | \"iso\"\n  | \"kbd\"\n  | \"loader\"\n  | \"marquee\"\n  | \"mascots\"\n  | \"media-capture\"\n  | \"meter\"\n  | \"nav-bar\"\n  | \"number-ticker\"\n  | \"page-header\"\n  | \"pagination\"\n  | \"popover\"\n  | \"progress\"\n  | \"radio-group\"\n  | \"search-field\"\n  | \"section-backdrop\"\n  | \"segmented\"\n  | \"separator\"\n  | \"skeleton\"\n  | \"slider\"\n  | \"slot\"\n  | \"spinner\"\n  | \"stat\"\n  | \"stepper\"\n  | \"switch\"\n  | \"tabs\"\n  | \"tag-input\"\n  | \"theme\"\n  | \"toast\"\n  | \"tooltip\"\n  | \"txt\"\n  | \"video-player\"\n  | \"video-trimmer\";\n\n/** Where a component exists: `@krizaka/ui/<name>` (web), `@krizaka/ui/native` (React Native), or both. */\nexport type Platform = \"web\" | \"native\" | \"both\";\n\n/** `stable`: its API only changes in a major. `beta`: it may still change in a minor. */\nexport type Status = \"stable\" | \"beta\";\n\n/** The group of the catalogue. `media`: video, sound, camera, files, cropping. */\nexport type Category = \"actions\" | \"forms\" | \"navigation\" | \"overlays\" | \"feedback\" | \"data-display\" | \"media\" | \"layout\" | \"foundations\";\n\n/**\n * A named example: the file `registry/examples/<component>/<name>.tsx` (web) or\n * `registry/examples/<component>/native/<name>.tsx` (React Native) — at most 40 lines, imported by the stories and\n * shown (live, with its code) by the documentation.\n */\nexport interface Example {\n  /** The file name, kebab-case (`primary`, `icon-button`). */\n  readonly name: string;\n  /** A short title (`Primary`, `Icon button`). */\n  readonly title: string;\n  /** One or two sentences: when this variant is the right one. */\n  readonly description: string;\n}\n\n/** One platform's side of a component. */\nexport interface PlatformDocs {\n  /** The names to import (`[\"Button\", \"IconButton\"]`): from `@krizaka/ui/<name>` on the web, `@krizaka/ui/native` in React Native. */\n  readonly imports: readonly string[];\n  /** The examples, in reading order; the first one is the component's preview. */\n  readonly examples: readonly Example[];\n}\n\n/** The React Native side: the same concept, and what differs from the web API. */\nexport interface NativeDocs extends PlatformDocs {\n  /**\n   * The entry to import from when it is not `@krizaka/ui/native`: a component that needs an Expo module (an optional\n   * peer) has its own, `@krizaka/ui/native/<name>`, so an app that does not use it never installs the module.\n   */\n  readonly entry?: string;\n  /** What differs from the web API (`label` instead of children…); empty for a native-only component. */\n  readonly differences: readonly string[];\n}\n\nexport interface KeyboardInteraction {\n  /** The keys, as written on a keyboard: `Space`, `Enter`, `Arrow keys`, `Esc`, `Tab`. */\n  readonly keys: string;\n  /** What they do. */\n  readonly action: string;\n}\n\nexport interface ComponentMeta {\n  /** The display name: `Button`, `Dropdown menu`. */\n  readonly title: string;\n  /** One sentence: what it is. */\n  readonly summary: string;\n  readonly status: Status;\n  readonly category: Category;\n  /** Must match the sides below: `both` ⇔ `web` and `native`. */\n  readonly platforms: Platform;\n  /** When to reach for it: concrete situations, one per item. */\n  readonly whenToUse: readonly string[];\n  /** When not to — and what to use instead (`use`), when another component is the answer. */\n  readonly whenNotToUse: readonly { readonly when: string; readonly use?: ComponentName }[];\n  /** How to use it well: wording, placement, composition. */\n  readonly bestPractices: readonly string[];\n  readonly accessibility: {\n    /** The keyboard, when it does more than Tab and Enter. */\n    readonly keyboard: readonly KeyboardInteraction[];\n    /** Roles, names and announcements: what the component does, what the app must provide. */\n    readonly notes: readonly string[];\n  };\n  /** The components a reader of this page should know about. */\n  readonly related: readonly ComponentName[];\n  readonly web?: PlatformDocs;\n  readonly native?: NativeDocs;\n}\n"
+    }
+  ],
+  "dependencies": [
+    "tailwind-variants@^3.3.1"
+  ],
+  "registryDependencies": [
+    "spinner"
+  ],
+  "demo": {
+    "path": "examples/loader/fetch-flow.tsx",
+    "content": "\"use client\";\nimport { Button } from \"@krizaka/ui/button\";\nimport { Loader } from \"@krizaka/ui/loader\";\nimport { useState } from \"react\";\n\n// Try both: a fast answer (150 ms) shows nothing at all; a slow one shows the wait, then a check, then nothing.\nexport default function LoaderFetchFlow() {\n  const [status, setStatus] = useState<\"idle\" | \"loading\" | \"success\">(\"idle\");\n  const run = (ms: number) => {\n    setStatus(\"loading\");\n    setTimeout(() => setStatus(\"success\"), ms);\n  };\n  return (\n    <div className=\"flex flex-col gap-4\">\n      <div className=\"flex gap-2\">\n        <Button size=\"sm\" onClick={() => run(150)}>Fast answer</Button>\n        <Button size=\"sm\" onClick={() => run(2500)}>Slow answer</Button>\n      </div>\n      <div className=\"h-10\">\n        {status !== \"idle\" && <Loader status={status} label=\"Loading your invoices\" successLabel=\"12 invoices loaded\" />}\n      </div>\n    </div>\n  );\n}\n"
+  },
+  "props": [
+    {
+      "component": "Loader",
+      "description": "A wait, from start to end. `role=\"status\"` (polite): its words are announced when it shows and when it ends. Under\nprefers-reduced-motion the glyph rests on a still frame; the delay and the ending stay.",
+      "props": [
+        {
+          "name": "label",
+          "type": "string",
+          "default": null,
+          "description": "What is loading, in words (“Loading your invoices”) — passed translated; shown and announced.",
+          "required": true
+        },
+        {
+          "name": "delay",
+          "type": "number",
+          "default": "250",
+          "description": "Milliseconds before anything shows: a wait shorter than this never flashes.",
+          "required": false
+        },
+        {
+          "name": "endDuration",
+          "type": "number",
+          "default": "1600",
+          "description": "Milliseconds the ending (check or cross) stays before the loader disappears; `0` never shows it, `Infinity` keeps it.",
+          "required": false
+        },
+        {
+          "name": "errorLabel",
+          "type": "string",
+          "default": null,
+          "description": "The words of a failure (“Could not load the invoices”) — passed translated.",
+          "required": false
+        },
+        {
+          "name": "eta",
+          "type": "string",
+          "default": null,
+          "description": "The time left, in words (“About 20 s left”) — passed translated (`@krizaka/intl` formats durations).",
+          "required": false
+        },
+        {
+          "name": "minDuration",
+          "type": "number",
+          "default": "600",
+          "description": "Once shown, the least milliseconds it stays: it never blinks.",
+          "required": false
+        },
+        {
+          "name": "status",
+          "type": "\"success\" | \"loading\" | \"error\"",
+          "default": "loading",
+          "description": "loading · success · error. When the wait ends, the loader shows how it ended for `endDuration` ms, then disappears.",
+          "required": false
+        },
+        {
+          "name": "successLabel",
+          "type": "string",
+          "default": null,
+          "description": "The words of a success (“Invoices loaded”) — passed translated. Default: nothing more than the check.",
+          "required": false
+        },
+        {
+          "name": "value",
+          "type": "number | null",
+          "default": null,
+          "description": "Between 0 and 1: a determinate wait — the trace grows to it and the percentage shows.",
+          "required": false
+        },
+        {
+          "name": "variant",
+          "type": "\"inline\" | \"page\" | \"overlay\" | \"block\"",
+          "default": "inline",
+          "description": "inline (beside the content) · block (a region's centre) · overlay (over a `relative` parent, frosted) · page (the\nwhole screen).",
+          "required": false
+        }
+      ]
+    },
+    {
+      "component": "LoadingRegion",
+      "description": "A region that hands over: its content → (after `delay`) a skeleton of the same shape → (after `slowAfter`) words over\nthe skeleton → its content again, fading in. `aria-busy` while it waits; the wait is announced once.",
+      "props": [
+        {
+          "name": "label",
+          "type": "string",
+          "default": null,
+          "description": "What is loading, in words — passed translated; announced when the wait shows.",
+          "required": true
+        },
+        {
+          "name": "loading",
+          "type": "boolean",
+          "default": null,
+          "description": "Whether the content is on its way.",
+          "required": true
+        },
+        {
+          "name": "skeleton",
+          "type": "ReactNode",
+          "default": null,
+          "description": "What stands in while it loads: skeletons the shape of the content (no layout shift when it arrives).",
+          "required": true
+        },
+        {
+          "name": "delay",
+          "type": "number",
+          "default": "200",
+          "description": "Milliseconds before the skeleton shows: a fast answer goes straight to the content.",
+          "required": false
+        },
+        {
+          "name": "minDuration",
+          "type": "number",
+          "default": "500",
+          "description": "Once shown, the least milliseconds the skeleton stays.",
+          "required": false
+        },
+        {
+          "name": "slowAfter",
+          "type": "number",
+          "default": "4000",
+          "description": "Milliseconds of skeleton before the words of a long wait appear over it.",
+          "required": false
+        },
+        {
+          "name": "slowLabel",
+          "type": "string",
+          "default": null,
+          "description": "The words when the wait grows long (“Still loading — the server is busy”) — passed translated.",
+          "required": false
+        }
+      ]
+    }
+  ]
+}