@krizaka/ui 2.0.0-beta.5 → 2.0.0

package/registry/progress.json

@@ -1,12 +1,274 @@
 {
   "name": "progress",
   "type": "primitive",
-  "description": "`Progress` (bar · ring, indeterminate), `progress` (the slots). Server-safe.",
+  "title": "Progress",
+  "summary": "How far a task or a goal has come: a bar or a ring, determinate or indeterminate.",
+  "description": "How far a task or a goal has come: a bar or a ring, determinate or indeterminate.",
+  "status": "beta",
+  "category": "feedback",
+  "platforms": "both",
+  "whenToUse": [
+    "For a task with a known end: an upload, a processing step, a profile to complete.",
+    "A ring with its amount in the centre for a goal: money raised, steps done.",
+    "Indeterminate (no `value`) for a wait of unknown length inside a layout."
+  ],
+  "whenNotToUse": [
+    {
+      "when": "For a short, unknown wait with nothing to show.",
+      "use": "spinner"
+    },
+    {
+      "when": "While the content of a page loads.",
+      "use": "skeleton"
+    },
+    {
+      "when": "For the time left until a moment.",
+      "use": "countdown"
+    }
+  ],
+  "bestPractices": [
+    "Always a `label` (“Upload”), translated: it names the bar.",
+    "Give `valueText` when the percentage is not what matters (“$420 of $1,000”).",
+    "Do not move the bar backwards: if a task restarts, say so."
+  ],
+  "accessibility": {
+    "keyboard": [],
+    "notes": [
+      "`role=\"progressbar\"` named by `label`, with `aria-valuenow`, `aria-valuemax` and `aria-valuetext`.",
+      "Indeterminate: no value attributes; the motion stops under `prefers-reduced-motion`."
+    ]
+  },
+  "related": [
+    "spinner",
+    "skeleton",
+    "countdown"
+  ],
+  "web": {
+    "entry": "@krizaka/ui/progress",
+    "import": "import { Progress } from \"@krizaka/ui/progress\";",
+    "props": [
+      {
+        "component": "Progress",
+        "description": "A progress bar or ring: `value` / `max`, indeterminate without a value. State: `data-state` (loading · complete · indeterminate).",
+        "props": [
+          {
+            "name": "label",
+            "type": "string",
+            "default": null,
+            "description": "The accessible name — passed translated (\"Upload\", \"Raised towards the goal\").",
+            "required": true
+          },
+          {
+            "name": "children",
+            "type": "ReactNode",
+            "default": null,
+            "description": "A ring's centre: an amount, a percentage, an icon.",
+            "required": false
+          },
+          {
+            "name": "max",
+            "type": "number",
+            "default": "100",
+            "description": "The value that means complete.",
+            "required": false
+          },
+          {
+            "name": "size",
+            "type": "\"sm\" | \"md\" | \"lg\"",
+            "default": "md",
+            "description": "sm · md · lg: the bar's thickness, the ring's diameter.",
+            "required": false
+          },
+          {
+            "name": "value",
+            "type": "number | null",
+            "default": null,
+            "description": "How far, between 0 and `max`. `null` or absent: indeterminate (a wait of unknown length).",
+            "required": false
+          },
+          {
+            "name": "valueText",
+            "type": "string",
+            "default": null,
+            "description": "The value in words for assistive technology (\"$420 of $1,000\") — default: the percentage.",
+            "required": false
+          },
+          {
+            "name": "variant",
+            "type": "\"bar\" | \"ring\"",
+            "default": "bar",
+            "description": "bar · ring (a ring holds its `children` in the centre).",
+            "required": false
+          }
+        ]
+      }
+    ],
+    "examples": [
+      {
+        "name": "bar",
+        "title": "Bar",
+        "description": "A task with a known end.",
+        "path": "examples/progress/bar.tsx",
+        "module": "@krizaka/ui/registry/examples/progress/bar",
+        "code": "import { Progress } from \"@krizaka/ui/progress\";\n\nexport default function ProgressBar() {\n  return <Progress label=\"Upload\" value={64} />;\n}\n"
+      },
+      {
+        "name": "bar-sizes",
+        "title": "Bar sizes",
+        "description": "`sm`, `md`, `lg`.",
+        "path": "examples/progress/bar-sizes.tsx",
+        "module": "@krizaka/ui/registry/examples/progress/bar-sizes",
+        "code": "import { Progress } from \"@krizaka/ui/progress\";\n\nexport default function ProgressBarSizes() {\n  return (\n    <div className=\"flex flex-col gap-4\">\n      <Progress label=\"Small\" size=\"sm\" value={30} />\n      <Progress label=\"Medium\" size=\"md\" value={55} />\n      <Progress label=\"Large\" size=\"lg\" value={80} />\n    </div>\n  );\n}\n"
+      },
+      {
+        "name": "bar-indeterminate",
+        "title": "Indeterminate bar",
+        "description": "A wait of unknown length.",
+        "path": "examples/progress/bar-indeterminate.tsx",
+        "module": "@krizaka/ui/registry/examples/progress/bar-indeterminate",
+        "code": "import { Progress } from \"@krizaka/ui/progress\";\n\n// No `value`: a wait of unknown length (still under reduced motion).\nexport default function ProgressBarIndeterminate() {\n  return <Progress label=\"Processing\" />;\n}\n"
+      },
+      {
+        "name": "ring",
+        "title": "Ring",
+        "description": "A goal with its amount in the centre.",
+        "path": "examples/progress/ring.tsx",
+        "module": "@krizaka/ui/registry/examples/progress/ring",
+        "code": "import { Progress } from \"@krizaka/ui/progress\";\n\n// A ring holds its amount in the centre; `valueText` gives the words a screen reader reads.\nexport default function ProgressRing() {\n  return (\n    <div className=\"flex items-end gap-6\">\n      <Progress variant=\"ring\" size=\"sm\" label=\"Profile completed\" value={40} />\n      <Progress variant=\"ring\" size=\"md\" label=\"Raised\" value={420} max={1000} valueText=\"$420 of $1,000\">\n        <span className=\"text-sm font-bold text-fg\">42%</span>\n      </Progress>\n      <Progress variant=\"ring\" size=\"lg\" label=\"Raised towards the goal\" value={750} max={1000} valueText=\"$750 of $1,000\">\n        <span className=\"font-display text-2xl font-black text-fg\">$750</span>\n        <span className=\"text-xs text-fg-secondary\">of $1,000</span>\n      </Progress>\n    </div>\n  );\n}\n"
+      },
+      {
+        "name": "ring-indeterminate",
+        "title": "Indeterminate ring",
+        "description": "A ring without a value.",
+        "path": "examples/progress/ring-indeterminate.tsx",
+        "module": "@krizaka/ui/registry/examples/progress/ring-indeterminate",
+        "code": "import { Progress } from \"@krizaka/ui/progress\";\n\nexport default function ProgressRingIndeterminate() {\n  return <Progress variant=\"ring\" size=\"md\" label=\"Loading\" />;\n}\n"
+      }
+    ]
+  },
+  "native": {
+    "entry": "@krizaka/ui/native",
+    "import": "import { Progress } from \"@krizaka/ui/native\";",
+    "differences": [
+      "The ring's centre is native text (`Txt`).",
+      "Style with `style`, not `className`."
+    ],
+    "props": [
+      {
+        "component": "Progress",
+        "description": "A progress bar or ring in the accent gradient (`accent` → `accent2`): it moves to `value` / `max` when it changes,\nindeterminate without a value. Still under reduced motion. A `progressbar` with its value for screen readers.",
+        "props": [
+          {
+            "name": "label",
+            "type": "string",
+            "default": null,
+            "description": "The accessible name — passed translated (\"Upload\", \"Raised towards the goal\").",
+            "required": true
+          },
+          {
+            "name": "children",
+            "type": "ReactNode",
+            "default": null,
+            "description": "A ring's centre: an amount, a percentage, an icon.",
+            "required": false
+          },
+          {
+            "name": "max",
+            "type": "number",
+            "default": "100",
+            "description": "The value of a full bar. Default 100.",
+            "required": false
+          },
+          {
+            "name": "size",
+            "type": "\"sm\" | \"md\" | \"lg\"",
+            "default": "md",
+            "description": "sm · md (default) · lg: the bar's thickness or the ring's diameter.",
+            "required": false
+          },
+          {
+            "name": "style",
+            "type": "StyleProp<ViewStyle>",
+            "default": null,
+            "description": "Styles merged last.",
+            "required": false
+          },
+          {
+            "name": "value",
+            "type": "number | null",
+            "default": null,
+            "description": "How far, between 0 and `max`. `null` or absent: indeterminate (a wait of unknown length).",
+            "required": false
+          },
+          {
+            "name": "valueText",
+            "type": "string",
+            "default": null,
+            "description": "The value in words for screen readers (\"$420 of $1,000\") — default: the percentage.",
+            "required": false
+          },
+          {
+            "name": "variant",
+            "type": "\"bar\" | \"ring\"",
+            "default": "bar",
+            "description": "`bar` (default) or `ring`.",
+            "required": false
+          }
+        ]
+      }
+    ],
+    "examples": [
+      {
+        "name": "bar",
+        "title": "Bar",
+        "description": "`sm`, `md`, `lg`.",
+        "path": "examples/progress/native/bar.tsx",
+        "module": "@krizaka/ui/registry/examples/progress/native/bar",
+        "code": "import { Progress } from \"@krizaka/ui/native\";\nimport { View } from \"react-native\";\n\nexport default function NativeProgressBar() {\n  return (\n    <View style={{ width: 320, gap: 16 }}>\n      <Progress label=\"Upload\" value={64} size=\"sm\" />\n      <Progress label=\"Upload\" value={64} size=\"md\" />\n      <Progress label=\"Upload\" value={64} size=\"lg\" />\n    </View>\n  );\n}\n",
+        "screenshots": {
+          "dark": "examples/progress/native/bar.dark.png",
+          "light": "examples/progress/native/bar.light.png"
+        }
+      },
+      {
+        "name": "ring",
+        "title": "Ring",
+        "description": "A ring with its centre: an amount, a percentage.",
+        "path": "examples/progress/native/ring.tsx",
+        "module": "@krizaka/ui/registry/examples/progress/native/ring",
+        "code": "import { Progress, Txt } from \"@krizaka/ui/native\";\nimport { View } from \"react-native\";\n\nexport default function NativeProgressRing() {\n  return (\n    <View style={{ flexDirection: \"row\", gap: 16, alignItems: \"center\" }}>\n      <Progress variant=\"ring\" size=\"sm\" value={30} label=\"Goal\" />\n      <Progress variant=\"ring\" size=\"md\" value={64} label=\"Goal\">\n        <Txt variant=\"label\">64%</Txt>\n      </Progress>\n      <Progress variant=\"ring\" size=\"lg\" value={420} max={1000} label=\"Raised towards the goal\" valueText=\"$420 of $1,000\">\n        <Txt variant=\"title\">$420</Txt>\n        <Txt variant=\"caption\" tone=\"secondary\">\n          of $1,000\n        </Txt>\n      </Progress>\n    </View>\n  );\n}\n",
+        "screenshots": {
+          "dark": "examples/progress/native/ring.dark.png",
+          "light": "examples/progress/native/ring.light.png"
+        }
+      },
+      {
+        "name": "indeterminate",
+        "title": "Indeterminate",
+        "description": "No value: a wait of unknown length.",
+        "path": "examples/progress/native/indeterminate.tsx",
+        "module": "@krizaka/ui/registry/examples/progress/native/indeterminate",
+        "code": "import { Progress } from \"@krizaka/ui/native\";\nimport { View } from \"react-native\";\n\n// No value: a wait of unknown length (still under reduced motion).\nexport default function NativeProgressIndeterminate() {\n  return (\n    <View style={{ width: 320, gap: 16 }}>\n      <Progress label=\"Processing\" />\n      <Progress variant=\"ring\" label=\"Processing\" />\n    </View>\n  );\n}\n",
+        "screenshots": {
+          "dark": "examples/progress/native/indeterminate.dark.png",
+          "light": "examples/progress/native/indeterminate.light.png"
+        }
+      }
+    ]
+  },
   "files": [
+    {
+      "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  | \"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"
+    },
     {
       "path": "progress/index.ts",
       "content": "/** @krizaka/ui/progress — `Progress` (bar · ring, indeterminate), `progress` (the slots). Server-safe. */\nexport { Progress, progress, type ProgressProps, type ProgressVariants } from \"./progress\";\n"
     },
+    {
+      "path": "progress/meta.ts",
+      "content": "import type { ComponentMeta } from \"../meta\";\n\nexport const meta = {\n  title: \"Progress\",\n  summary: \"How far a task or a goal has come: a bar or a ring, determinate or indeterminate.\",\n  status: \"beta\",\n  category: \"feedback\",\n  platforms: \"both\",\n  whenToUse: [\n    \"For a task with a known end: an upload, a processing step, a profile to complete.\",\n    \"A ring with its amount in the centre for a goal: money raised, steps done.\",\n    \"Indeterminate (no `value`) for a wait of unknown length inside a layout.\",\n  ],\n  whenNotToUse: [\n    { when: \"For a short, unknown wait with nothing to show.\", use: \"spinner\" },\n    { when: \"While the content of a page loads.\", use: \"skeleton\" },\n    { when: \"For the time left until a moment.\", use: \"countdown\" },\n  ],\n  bestPractices: [\n    \"Always a `label` (“Upload”), translated: it names the bar.\",\n    \"Give `valueText` when the percentage is not what matters (“$420 of $1,000”).\",\n    \"Do not move the bar backwards: if a task restarts, say so.\",\n  ],\n  accessibility: {\n    keyboard: [],\n    notes: [\n      \"`role=\\\"progressbar\\\"` named by `label`, with `aria-valuenow`, `aria-valuemax` and `aria-valuetext`.\",\n      \"Indeterminate: no value attributes; the motion stops under `prefers-reduced-motion`.\",\n    ],\n  },\n  related: [\"spinner\", \"skeleton\", \"countdown\"],\n  web: {\n    imports: [\"Progress\"],\n    examples: [\n      { name: \"bar\", title: \"Bar\", description: \"A task with a known end.\" },\n      { name: \"bar-sizes\", title: \"Bar sizes\", description: \"`sm`, `md`, `lg`.\" },\n      { name: \"bar-indeterminate\", title: \"Indeterminate bar\", description: \"A wait of unknown length.\" },\n      { name: \"ring\", title: \"Ring\", description: \"A goal with its amount in the centre.\" },\n      { name: \"ring-indeterminate\", title: \"Indeterminate ring\", description: \"A ring without a value.\" },\n    ],\n  },\n  native: {\n    imports: [\"Progress\"],\n    differences: [\"The ring's centre is native text (`Txt`).\", \"Style with `style`, not `className`.\"],\n    examples: [\n      { name: \"bar\", title: \"Bar\", description: \"`sm`, `md`, `lg`.\" },\n      { name: \"ring\", title: \"Ring\", description: \"A ring with its centre: an amount, a percentage.\" },\n      { name: \"indeterminate\", title: \"Indeterminate\", description: \"No value: a wait of unknown length.\" },\n    ],\n  },\n} satisfies ComponentMeta;\n"
+    },
     {
       "path": "progress/progress.tsx",
       "content": "// Server-safe: no hook, no context. role=\"progressbar\" with aria-valuenow / aria-valuemax (none when indeterminate),\n// named by `label`. A bar or a ring; the ring can hold content in its centre (an amount, a percentage).\nimport type * as React from \"react\";\nimport { tv, type VariantProps } from \"tailwind-variants\";\n\nexport const progress = tv({\n  slots: {\n    root: \"relative\",\n    track: \"\",\n    indicator: \"\",\n    center: \"absolute inset-0 flex flex-col items-center justify-center text-center\",\n  },\n  variants: {\n    variant: {\n      bar: {\n        root: \"w-full overflow-hidden rounded-full bg-surface-3\",\n        indicator:\n          \"kz-progress h-full rounded-full bg-linear-to-r from-accent to-accent-2 transition-[width] duration-500 motion-reduce:transition-none \" +\n          \"data-[state=indeterminate]:w-2/5\",\n      },\n      ring: {\n        root: \"inline-flex shrink-0 items-center justify-center\",\n        track: \"stroke-border-default\",\n        indicator:\n          \"stroke-accent transition-[stroke-dashoffset] duration-1000 motion-reduce:transition-none \" +\n          \"data-[state=indeterminate]:origin-center data-[state=indeterminate]:animate-spin motion-reduce:data-[state=indeterminate]:animate-none\",\n      },\n    },\n    size: { sm: {}, md: {}, lg: {} },\n  },\n  compoundVariants: [\n    { variant: \"bar\", size: \"sm\", class: { root: \"h-1\" } },\n    { variant: \"bar\", size: \"md\", class: { root: \"h-2\" } },\n    { variant: \"bar\", size: \"lg\", class: { root: \"h-3\" } },\n    { variant: \"ring\", size: \"sm\", class: { root: \"h-10 w-10\" } },\n    { variant: \"ring\", size: \"md\", class: { root: \"h-20 w-20\" } },\n    { variant: \"ring\", size: \"lg\", class: { root: \"h-36 w-36\" } },\n  ],\n  defaultVariants: { variant: \"bar\", size: \"md\" },\n});\n\nexport type ProgressVariants = VariantProps<typeof progress>;\n\nexport type ProgressProps = Omit<React.ComponentProps<\"div\">, \"children\"> &\n  ProgressVariants & {\n    /** bar · ring (a ring holds its `children` in the centre). */\n    variant?: ProgressVariants[\"variant\"];\n    /** sm · md · lg: the bar's thickness, the ring's diameter. */\n    size?: ProgressVariants[\"size\"];\n    /** How far, between 0 and `max`. `null` or absent: indeterminate (a wait of unknown length). */\n    value?: number | null;\n    /** The value that means complete. */\n    max?: number;\n    /** The accessible name — passed translated (\"Upload\", \"Raised towards the goal\"). */\n    label: string;\n    /** The value in words for assistive technology (\"$420 of $1,000\") — default: the percentage. */\n    valueText?: string;\n    /** A ring's centre: an amount, a percentage, an icon. */\n    children?: React.ReactNode;\n  };\n\nconst STROKE = { sm: 12, md: 9, lg: 7 } as const;\n\n/** A progress bar or ring: `value` / `max`, indeterminate without a value. State: `data-state` (loading · complete · indeterminate). */\nexport function Progress({ variant = \"bar\", size = \"md\", value, max = 100, label, valueText, className, children, ...props }: ProgressProps) {\n  const s = progress({ variant, size });\n  const known = typeof value === \"number\" && Number.isFinite(value);\n  const ratio = known ? Math.min(1, Math.max(0, value / (max || 1))) : 0;\n  const percent = Math.round(ratio * 100);\n  const state = !known ? \"indeterminate\" : ratio >= 1 ? \"complete\" : \"loading\";\n  const aria = {\n    role: \"progressbar\" as const,\n    \"aria-label\": label,\n    \"aria-valuemin\": known ? 0 : undefined,\n    \"aria-valuemax\": known ? max : undefined,\n    \"aria-valuenow\": known ? Math.min(max, Math.max(0, value)) : undefined,\n    \"aria-valuetext\": known ? (valueText ?? `${percent}%`) : valueText,\n    \"data-state\": state,\n    \"data-value\": known ? value : undefined,\n    \"data-variant\": variant,\n  };\n  if (variant === \"ring\") {\n    const stroke = STROKE[size];\n    const r = 50 - stroke / 2;\n    return (\n      <div {...aria} className={s.root({ className })} {...props}>\n        <svg viewBox=\"0 0 100 100\" className=\"h-full w-full -rotate-90\" aria-hidden>\n          <circle cx=\"50\" cy=\"50\" r={r} fill=\"none\" strokeWidth={stroke} className={s.track()} />\n          <circle\n            cx=\"50\"\n            cy=\"50\"\n            r={r}\n            fill=\"none\"\n            strokeWidth={stroke}\n            strokeLinecap=\"round\"\n            pathLength={100}\n            strokeDasharray={100}\n            strokeDashoffset={known ? 100 - percent : 75}\n            data-state={state}\n            className={s.indicator()}\n          />\n        </svg>\n        {children !== undefined && <div className={s.center()}>{children}</div>}\n      </div>\n    );\n  }\n  return (\n    <div {...aria} className={s.root({ className })} {...props}>\n      <div data-state={state} className={s.indicator()} style={known ? { width: `${ratio * 100}%` } : undefined} />\n    </div>\n  );\n}\n"
@@ -17,8 +279,8 @@
   ],
   "registryDependencies": [],
   "demo": {
-    "path": "demos/progress.tsx",
-    "content": "import { Progress } from \"@krizaka/ui/progress\";\n\nexport default function ProgressDemo() {\n  return <Progress label=\"Upload\" value={64} />;\n}\n"
+    "path": "examples/progress/bar.tsx",
+    "content": "import { Progress } from \"@krizaka/ui/progress\";\n\nexport default function ProgressBar() {\n  return <Progress label=\"Upload\" value={64} />;\n}\n"
   },
   "props": [
     {

package/registry/radio-group.json

@@ -1,12 +1,145 @@
 {
   "name": "radio-group",
   "type": "primitive",
-  "description": "`RadioGroup.Root/Item/Card`, `radioGroup` (the slots). Client (\"use client\").",
+  "title": "Radio group",
+  "summary": "One choice among a few options, all visible: dots with their words, or whole cards.",
+  "description": "One choice among a few options, all visible: dots with their words, or whole cards.",
+  "status": "beta",
+  "category": "forms",
+  "platforms": "web",
+  "whenToUse": [
+    "In a form, to choose exactly one of two to five options that should all be seen: a frequency, a quality.",
+    "`RadioGroup.Card` when each option needs more than a line: an amount, a plan, a payment method."
+  ],
+  "whenNotToUse": [
+    {
+      "when": "For many options (a country).",
+      "use": "field"
+    },
+    {
+      "when": "For independent options that can all be chosen.",
+      "use": "checkbox"
+    },
+    {
+      "when": "To filter a list at once, without a form.",
+      "use": "chip"
+    },
+    {
+      "when": "To switch between views.",
+      "use": "tabs"
+    }
+  ],
+  "bestPractices": [
+    "Give the group a `label`: the question being answered.",
+    "Pre-select the safest or most common option with `defaultValue` when there is one.",
+    "Keep the labels parallel and short."
+  ],
+  "accessibility": {
+    "keyboard": [
+      {
+        "keys": "Tab",
+        "action": "Moves into the group (one tab stop, on the chosen option) and out of it."
+      },
+      {
+        "keys": "Arrow keys",
+        "action": "Move to the next or previous option and choose it."
+      }
+    ],
+    "notes": [
+      "Radix RadioGroup: `role=\"radiogroup\"` named by `label`, `role=\"radio\"` with `aria-checked` on each option.",
+      "Disabled options are skipped by the arrows."
+    ]
+  },
+  "related": [
+    "checkbox",
+    "chip",
+    "field",
+    "switch"
+  ],
+  "web": {
+    "entry": "@krizaka/ui/radio-group",
+    "import": "import { RadioGroup } from \"@krizaka/ui/radio-group\";",
+    "props": [
+      {
+        "component": "RadioGroupRoot",
+        "description": "`value`/`defaultValue` + `onValueChange`, `orientation`, `required`, `name` for a form.",
+        "props": [
+          {
+            "name": "invalid",
+            "type": "boolean",
+            "default": null,
+            "description": "Marks every radio invalid: aria-invalid (pair it with a `Field.Error`).",
+            "required": false
+          },
+          {
+            "name": "label",
+            "type": "string",
+            "default": null,
+            "description": "The group's accessible name — passed translated (or `aria-labelledby` a visible heading).",
+            "required": false
+          }
+        ]
+      },
+      {
+        "component": "RadioGroupItem",
+        "description": "A radio: a dot, and its words when given.",
+        "props": [
+          {
+            "name": "children",
+            "type": "ReactNode",
+            "default": null,
+            "description": "The words next to the dot, clickable. Otherwise name it with `Field.Label htmlFor` or `aria-label`.",
+            "required": false
+          }
+        ]
+      },
+      {
+        "component": "RadioGroupCard",
+        "description": "A whole card as the radio: its content is the radio's name. `data-state=\"checked\"` styles the chosen one.",
+        "props": []
+      }
+    ],
+    "examples": [
+      {
+        "name": "items",
+        "title": "Items",
+        "description": "Dots and their words, one disabled.",
+        "path": "examples/radio-group/items.tsx",
+        "module": "@krizaka/ui/registry/examples/radio-group/items",
+        "code": "import { RadioGroup } from \"@krizaka/ui/radio-group\";\n\nexport default function RadioGroupItems() {\n  return (\n    <RadioGroup.Root label=\"Notification frequency\" defaultValue=\"daily\">\n      <RadioGroup.Item value=\"instant\">Instantly</RadioGroup.Item>\n      <RadioGroup.Item value=\"daily\">Once a day</RadioGroup.Item>\n      <RadioGroup.Item value=\"weekly\">Once a week</RadioGroup.Item>\n      <RadioGroup.Item value=\"never\" disabled>\n        Never\n      </RadioGroup.Item>\n    </RadioGroup.Root>\n  );\n}\n"
+      },
+      {
+        "name": "cards",
+        "title": "Cards",
+        "description": "Whole cards: the chosen one carries the accent.",
+        "path": "examples/radio-group/cards.tsx",
+        "module": "@krizaka/ui/registry/examples/radio-group/cards",
+        "code": "import { RadioGroup } from \"@krizaka/ui/radio-group\";\n\nconst AMOUNTS = [\n  [\"5\", \"$5\", \"A coffee\"],\n  [\"20\", \"$20\", \"A dinner\"],\n  [\"50\", \"$50\", \"A night out\"],\n];\n\n// Whole cards: the chosen one carries the accent border and tint.\nexport default function RadioGroupCards() {\n  return (\n    <RadioGroup.Root label=\"Amount\" defaultValue=\"20\" className=\"grid w-[30rem] max-w-full grid-cols-3 gap-3\">\n      {AMOUNTS.map(([value, amount, hint]) => (\n        <RadioGroup.Card key={value} value={value}>\n          <span className=\"font-display text-lg font-bold\">{amount}</span>\n          <span className=\"text-xs text-fg-secondary\">{hint}</span>\n        </RadioGroup.Card>\n      ))}\n    </RadioGroup.Root>\n  );\n}\n"
+      },
+      {
+        "name": "horizontal",
+        "title": "Horizontal",
+        "description": "`orientation=\"horizontal\"`: the items in a row.",
+        "path": "examples/radio-group/horizontal.tsx",
+        "module": "@krizaka/ui/registry/examples/radio-group/horizontal",
+        "code": "import { RadioGroup } from \"@krizaka/ui/radio-group\";\n\n// `orientation=\"horizontal\"`: left and right arrows, the items in a row.\nexport default function RadioGroupHorizontal() {\n  return (\n    <RadioGroup.Root label=\"Quality\" defaultValue=\"1080\" orientation=\"horizontal\" className=\"gap-5\">\n      <RadioGroup.Item value=\"720\">720p</RadioGroup.Item>\n      <RadioGroup.Item value=\"1080\">1080p</RadioGroup.Item>\n      <RadioGroup.Item value=\"2160\">4K</RadioGroup.Item>\n    </RadioGroup.Root>\n  );\n}\n"
+      }
+    ]
+  },
+  "native": null,
   "files": [
+    {
+      "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  | \"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"
+    },
     {
       "path": "radio-group/index.ts",
       "content": "/** @krizaka/ui/radio-group — `RadioGroup.Root/Item/Card`, `radioGroup` (the slots). Client (\"use client\"). */\nexport {\n  RadioGroup,\n  radioGroup,\n  RadioGroupCard,\n  RadioGroupItem,\n  type RadioGroupItemProps,\n  RadioGroupRoot,\n  type RadioGroupRootProps,\n} from \"./radio-group\";\n"
     },
+    {
+      "path": "radio-group/meta.ts",
+      "content": "import type { ComponentMeta } from \"../meta\";\n\nexport const meta = {\n  title: \"Radio group\",\n  summary: \"One choice among a few options, all visible: dots with their words, or whole cards.\",\n  status: \"beta\",\n  category: \"forms\",\n  platforms: \"web\",\n  whenToUse: [\n    \"In a form, to choose exactly one of two to five options that should all be seen: a frequency, a quality.\",\n    \"`RadioGroup.Card` when each option needs more than a line: an amount, a plan, a payment method.\",\n  ],\n  whenNotToUse: [\n    { when: \"For many options (a country).\", use: \"field\" },\n    { when: \"For independent options that can all be chosen.\", use: \"checkbox\" },\n    { when: \"To filter a list at once, without a form.\", use: \"chip\" },\n    { when: \"To switch between views.\", use: \"tabs\" },\n  ],\n  bestPractices: [\n    \"Give the group a `label`: the question being answered.\",\n    \"Pre-select the safest or most common option with `defaultValue` when there is one.\",\n    \"Keep the labels parallel and short.\",\n  ],\n  accessibility: {\n    keyboard: [\n      { keys: \"Tab\", action: \"Moves into the group (one tab stop, on the chosen option) and out of it.\" },\n      { keys: \"Arrow keys\", action: \"Move to the next or previous option and choose it.\" },\n    ],\n    notes: [\"Radix RadioGroup: `role=\\\"radiogroup\\\"` named by `label`, `role=\\\"radio\\\"` with `aria-checked` on each option.\", \"Disabled options are skipped by the arrows.\"],\n  },\n  related: [\"checkbox\", \"chip\", \"field\", \"switch\"],\n  web: {\n    imports: [\"RadioGroup\"],\n    examples: [\n      { name: \"items\", title: \"Items\", description: \"Dots and their words, one disabled.\" },\n      { name: \"cards\", title: \"Cards\", description: \"Whole cards: the chosen one carries the accent.\" },\n      { name: \"horizontal\", title: \"Horizontal\", description: \"`orientation=\\\"horizontal\\\"`: the items in a row.\" },\n    ],\n  },\n} satisfies ComponentMeta;\n"
+    },
     {
       "path": "radio-group/radio-group.tsx",
       "content": "// Client (a context). Radix RadioGroup: role=\"radiogroup\" / \"radio\", one tab stop, the arrows move and select, a\n// hidden input inside a form. Two looks: `RadioGroup.Item` (a dot and its words) and `RadioGroup.Card` (a whole card\n// is the radio: an amount, a pack, a payment method, a plan).\nimport { RadioGroup as RadioGroupPrimitive } from \"radix-ui\";\nimport type * as React from \"react\";\nimport { tv } from \"tailwind-variants\";\n\nexport const radioGroup = tv({\n  slots: {\n    root: \"grid gap-2 data-[orientation=horizontal]:flex data-[orientation=horizontal]:flex-wrap\",\n    item:\n      \"peer inline-flex h-5 w-5 shrink-0 items-center justify-center rounded-full border border-border-strong bg-surface-1 transition-colors \" +\n      \"focus-visible:outline-hidden focus-visible:ring-2 focus-visible:ring-ring focus-visible:ring-offset-2 focus-visible:ring-offset-surface-0 \" +\n      \"hover:border-accent disabled:cursor-not-allowed disabled:opacity-40 data-[state=checked]:border-accent aria-invalid:border-danger\",\n    dot: \"h-2.5 w-2.5 rounded-full bg-accent\",\n    label: \"flex cursor-pointer items-start gap-3 text-sm text-fg has-disabled:cursor-not-allowed has-disabled:opacity-60\",\n    card:\n      \"relative flex min-w-0 flex-col items-start gap-1 rounded-xl border border-border-default bg-surface-1 p-3 text-left text-sm text-fg transition-colors \" +\n      \"hover:border-border-strong focus-visible:outline-hidden focus-visible:ring-2 focus-visible:ring-ring \" +\n      \"disabled:cursor-not-allowed disabled:opacity-40 data-[state=checked]:border-accent data-[state=checked]:bg-accent-soft \" +\n      \"data-[state=checked]:shadow-sm\",\n  },\n});\nconst s = radioGroup();\n\nexport type RadioGroupRootProps = React.ComponentProps<typeof RadioGroupPrimitive.Root> & {\n  /** The group's accessible name — passed translated (or `aria-labelledby` a visible heading). */\n  label?: string;\n  /** Marks every radio invalid: aria-invalid (pair it with a `Field.Error`). */\n  invalid?: boolean;\n};\n\n/** `value`/`defaultValue` + `onValueChange`, `orientation`, `required`, `name` for a form. */\nexport function RadioGroupRoot({ label, invalid, className, ...props }: RadioGroupRootProps) {\n  return (\n    <RadioGroupPrimitive.Root\n      aria-label={label}\n      aria-invalid={invalid || undefined}\n      data-invalid={invalid ? \"\" : undefined}\n      className={s.root({ className })}\n      {...props}\n    />\n  );\n}\n\nexport type RadioGroupItemProps = Omit<React.ComponentProps<typeof RadioGroupPrimitive.Item>, \"children\"> & {\n  /** The words next to the dot, clickable. Otherwise name it with `Field.Label htmlFor` or `aria-label`. */\n  children?: React.ReactNode;\n};\n\n/** A radio: a dot, and its words when given. */\nexport function RadioGroupItem({ className, children, ...props }: RadioGroupItemProps) {\n  const item = (\n    <RadioGroupPrimitive.Item className={s.item({ className: children ? \"mt-0.5\" : className })} {...props}>\n      <RadioGroupPrimitive.Indicator className={s.dot()} />\n    </RadioGroupPrimitive.Item>\n  );\n  if (!children) return item;\n  return (\n    <label className={s.label({ className })}>\n      {item}\n      <span className=\"min-w-0\">{children}</span>\n    </label>\n  );\n}\n\n/** A whole card as the radio: its content is the radio's name. `data-state=\"checked\"` styles the chosen one. */\nexport function RadioGroupCard({ className, ...props }: React.ComponentProps<typeof RadioGroupPrimitive.Item>) {\n  return <RadioGroupPrimitive.Item className={s.card({ className })} {...props} />;\n}\n\n/** `RadioGroup.Root/Item/Card`. */\nexport const RadioGroup = { Root: RadioGroupRoot, Item: RadioGroupItem, Card: RadioGroupCard };\n"
@@ -18,8 +151,8 @@
   ],
   "registryDependencies": [],
   "demo": {
-    "path": "demos/radio-group.tsx",
-    "content": "import { RadioGroup } from \"@krizaka/ui/radio-group\";\n\nexport default function RadioGroupDemo() {\n  return (\n    <RadioGroup.Root label=\"Notification frequency\" defaultValue=\"daily\">\n      <RadioGroup.Item value=\"instant\">Instantly</RadioGroup.Item>\n      <RadioGroup.Item value=\"daily\">Once a day</RadioGroup.Item>\n      <RadioGroup.Item value=\"weekly\">Once a week</RadioGroup.Item>\n      <RadioGroup.Item value=\"never\" disabled>\n        Never\n      </RadioGroup.Item>\n    </RadioGroup.Root>\n  );\n}\n"
+    "path": "examples/radio-group/items.tsx",
+    "content": "import { RadioGroup } from \"@krizaka/ui/radio-group\";\n\nexport default function RadioGroupItems() {\n  return (\n    <RadioGroup.Root label=\"Notification frequency\" defaultValue=\"daily\">\n      <RadioGroup.Item value=\"instant\">Instantly</RadioGroup.Item>\n      <RadioGroup.Item value=\"daily\">Once a day</RadioGroup.Item>\n      <RadioGroup.Item value=\"weekly\">Once a week</RadioGroup.Item>\n      <RadioGroup.Item value=\"never\" disabled>\n        Never\n      </RadioGroup.Item>\n    </RadioGroup.Root>\n  );\n}\n"
   },
   "props": [
     {