@krizaka/ui 3.2.0 → 3.3.0

package/registry/combobox.json

@@ -6,7 +6,7 @@
   "description": "A text field that suggests and completes — one value or several as chips, from a static list or a server, with values created from what was typed.",
   "status": "beta",
   "category": "forms",
-  "platforms": "web",
+  "platforms": "both",
   "whenToUse": [
     "To choose among many values the person knows by name: a creator, a country, a model, a playlist.",
     "With `onSearch` when the values live on a server (debounced, the previous request aborted).",
@@ -269,7 +269,229 @@
       }
     ]
   },
-  "native": null,
+  "native": {
+    "entry": "@krizaka/ui/native",
+    "import": "import { Combobox } from \"@krizaka/ui/native\";",
+    "differences": [
+      "A field that opens a `Sheet` with a search box and the matching options: radios for one value, checkboxes and a Done button with `multiple`.",
+      "`onSearch(query, signal)` is debounced (250 ms) and aborted by a newer query, as on the web; no `creatable` yet."
+    ],
+    "props": [
+      {
+        "component": "Select",
+        "description": "One choice among many — the web `<select>`: a field that opens a sheet of options; picking one closes it.",
+        "props": [
+          {
+            "name": "label",
+            "type": "string",
+            "default": null,
+            "description": "The visible label, passed translated (the field's name).",
+            "required": true
+          },
+          {
+            "name": "options",
+            "type": "readonly SelectOption[]",
+            "default": null,
+            "description": "The choices.",
+            "required": true
+          },
+          {
+            "name": "defaultValue",
+            "type": "string | null",
+            "default": "null",
+            "description": "The chosen value at first, uncontrolled.",
+            "required": false
+          },
+          {
+            "name": "disabled",
+            "type": "boolean",
+            "default": null,
+            "description": "Not available.",
+            "required": false
+          },
+          {
+            "name": "error",
+            "type": "string",
+            "default": null,
+            "description": "An error under the field: a danger edge, read and announced. Replaces the hint.",
+            "required": false
+          },
+          {
+            "name": "hint",
+            "type": "string",
+            "default": null,
+            "description": "A help text under the field.",
+            "required": false
+          },
+          {
+            "name": "onBlur",
+            "type": "(() => void)",
+            "default": null,
+            "description": "Called when the sheet closes (the field is left).",
+            "required": false
+          },
+          {
+            "name": "onValueChange",
+            "type": "((value: string) => void)",
+            "default": null,
+            "description": "Called with the value picked.",
+            "required": false
+          },
+          {
+            "name": "placeholder",
+            "type": "string",
+            "default": null,
+            "description": "Shown while nothing is chosen (\"Choose a category\"), passed translated.",
+            "required": false
+          },
+          {
+            "name": "sheetTitle",
+            "type": "string",
+            "default": null,
+            "description": "The sheet's title. Default: the label.",
+            "required": false
+          },
+          {
+            "name": "style",
+            "type": "StyleProp<ViewStyle>",
+            "default": null,
+            "description": "Styles merged last, on the field.",
+            "required": false
+          },
+          {
+            "name": "value",
+            "type": "string | null",
+            "default": null,
+            "description": "The chosen value (controlled); `null` or `\"\"` for none.",
+            "required": false
+          }
+        ]
+      },
+      {
+        "component": "Combobox",
+        "description": "A choice among many, searched: a field that opens a sheet with a search box and the matching options.",
+        "props": [
+          {
+            "name": "label",
+            "type": "string",
+            "default": null,
+            "description": "The visible label, passed translated (the field's name).",
+            "required": true
+          },
+          {
+            "name": "disabled",
+            "type": "boolean",
+            "default": null,
+            "description": "Not available.",
+            "required": false
+          },
+          {
+            "name": "error",
+            "type": "string",
+            "default": null,
+            "description": "An error under the field: a danger edge, read and announced. Replaces the hint.",
+            "required": false
+          },
+          {
+            "name": "hint",
+            "type": "string",
+            "default": null,
+            "description": "A help text under the field.",
+            "required": false
+          },
+          {
+            "name": "labels",
+            "type": "Partial<ComboboxLabels>",
+            "default": null,
+            "description": "The words, passed translated; English by default.",
+            "required": false
+          },
+          {
+            "name": "multiple",
+            "type": "boolean",
+            "default": null,
+            "description": "Several values (`string[]`, checkboxes, a Done button); one by default.",
+            "required": false
+          },
+          {
+            "name": "onBlur",
+            "type": "(() => void)",
+            "default": null,
+            "description": "Called when the sheet closes (the field is left).",
+            "required": false
+          },
+          {
+            "name": "onSearch",
+            "type": "((query: string, signal: AbortSignal) => Promise<readonly SelectOption[]>)",
+            "default": null,
+            "description": "Fetches the options for a query (debounced 250 ms, aborted by a newer one).",
+            "required": false
+          },
+          {
+            "name": "onValueChange",
+            "type": "((value: string | string[]) => void)",
+            "default": null,
+            "description": "Called with the value — or the values — chosen.",
+            "required": false
+          },
+          {
+            "name": "options",
+            "type": "readonly SelectOption[]",
+            "default": "[]",
+            "description": "The options, filtered by what is typed.",
+            "required": false
+          },
+          {
+            "name": "placeholder",
+            "type": "string",
+            "default": null,
+            "description": "Shown while nothing is chosen (\"Choose a category\"), passed translated.",
+            "required": false
+          },
+          {
+            "name": "style",
+            "type": "StyleProp<ViewStyle>",
+            "default": null,
+            "description": "Styles merged last, on the field.",
+            "required": false
+          },
+          {
+            "name": "value",
+            "type": "string | readonly string[] | null",
+            "default": null,
+            "description": "The chosen value(s) (controlled): a string, or strings with `multiple`.",
+            "required": false
+          }
+        ]
+      }
+    ],
+    "examples": [
+      {
+        "name": "search",
+        "title": "Search",
+        "description": "Cities filtered as you type.",
+        "path": "examples/combobox/native/search.tsx",
+        "module": "@krizaka/ui/registry/examples/combobox/native/search",
+        "code": "import { Combobox } from \"@krizaka/ui/native\";\nimport * as React from \"react\";\nimport { View } from \"react-native\";\n\nconst CITIES = [\"Montréal\", \"Québec\", \"Laval\", \"Gatineau\", \"Sherbrooke\", \"Trois-Rivières\"].map((c) => ({ value: c.toLowerCase(), label: c }));\n\n// A choice among many, searched in a sheet: what is typed filters the options.\nexport default function NativeComboboxSearch() {\n  const [city, setCity] = React.useState<string>(\"montréal\");\n  return (\n    <View style={{ width: 300 }}>\n      <Combobox label=\"City\" placeholder=\"Choose a city\" options={CITIES} value={city} onValueChange={(v) => setCity(String(v))} />\n    </View>\n  );\n}\n",
+        "screenshots": {
+          "dark": "examples/combobox/native/search.dark.png",
+          "light": "examples/combobox/native/search.light.png"
+        }
+      },
+      {
+        "name": "multiple",
+        "title": "Several values",
+        "description": "Interests as checkboxes; the field lists them.",
+        "path": "examples/combobox/native/multiple.tsx",
+        "module": "@krizaka/ui/registry/examples/combobox/native/multiple",
+        "code": "import { Combobox } from \"@krizaka/ui/native\";\nimport * as React from \"react\";\nimport { View } from \"react-native\";\n\nconst TOPICS = [\"Music\", \"Sport\", \"Art\", \"Cooking\", \"Gaming\", \"Travel\"].map((t) => ({ value: t.toLowerCase(), label: t }));\n\n// Several values: checkboxes in the sheet, Done closes it; the field lists the choices.\nexport default function NativeComboboxMultiple() {\n  const [topics, setTopics] = React.useState<string[]>([\"music\", \"travel\"]);\n  return (\n    <View style={{ width: 300 }}>\n      <Combobox label=\"Interests\" multiple options={TOPICS} value={topics} onValueChange={(v) => setTopics(Array.isArray(v) ? v : [v])} />\n    </View>\n  );\n}\n",
+        "screenshots": {
+          "dark": "examples/combobox/native/multiple.dark.png",
+          "light": "examples/combobox/native/multiple.light.png"
+        }
+      }
+    ]
+  },
   "files": [
     {
       "path": "combobox/combobox.tsx",
@@ -281,7 +503,7 @@
     },
     {
       "path": "combobox/meta.ts",
-      "content": "import type { ComponentMeta } from \"../meta\";\n\nexport const meta = {\n  title: \"Combobox\",\n  summary: \"A text field that suggests and completes — one value or several as chips, from a static list or a server, with values created from what was typed.\",\n  status: \"beta\",\n  category: \"forms\",\n  platforms: \"web\",\n  whenToUse: [\n    \"To choose among many values the person knows by name: a creator, a country, a model, a playlist.\",\n    \"With `onSearch` when the values live on a server (debounced, the previous request aborted).\",\n    \"With `multiple` for several values (collaborators, categories), and `creatable` when a new one can be added.\",\n  ],\n  whenNotToUse: [\n    { when: \"For fewer than about seven options known in advance: radios or a select.\", use: \"radio-group\" },\n    { when: \"For free words without a closed list (tags, keywords): a tag input.\", use: \"tag-input\" },\n    { when: \"To run a search and show results: a search field.\", use: \"search-field\" },\n  ],\n  bestPractices: [\n    \"Write `label` as the question (“Collaborators”), the `placeholder` as an example (“Type a name”).\",\n    \"Return at most 20 options from `onSearch`; put the best match first.\",\n    \"Give options a `description` when names collide (two creators named Eric: their handles).\",\n    \"Set `maxSelected` when the product has a limit, and say it in `hint`.\",\n  ],\n  accessibility: {\n    keyboard: [\n      { keys: \"Arrow Down / Arrow Up\", action: \"Open the list and move the active option.\" },\n      { keys: \"Home / End\", action: \"First or last option, when the list is open.\" },\n      { keys: \"Enter\", action: \"Choose the active option (or create the typed value).\" },\n      { keys: \"Esc\", action: \"Close the list; for one value, restore its label.\" },\n      { keys: \"Backspace\", action: \"In an empty input, remove the last chip.\" },\n    ],\n    notes: [\n      \"The ARIA 1.2 combobox pattern: the focus stays in the input, `aria-activedescendant` points at the active option of the `listbox`.\",\n      \"The number of results is announced in a polite live region (`labels.results`).\",\n      \"Chosen options carry `aria-selected`; each chip's remove button is named (“Remove Eric”).\",\n      \"The label is a real `<label>`; `hint` and `error` are wired with `aria-describedby`, `error` sets `aria-invalid`.\",\n    ],\n  },\n  related: [\"tag-input\", \"search-field\", \"field\", \"chip\", \"command\"],\n  web: {\n    imports: [\"Combobox\"],\n    examples: [\n      { name: \"async\", title: \"From a server\", description: \"`onSearch`: creators fetched as you type, debounced, the stale request aborted.\" },\n      { name: \"multiple\", title: \"Several values\", description: \"Collaborators as chips; Backspace removes the last one, at most three.\" },\n      { name: \"creatable\", title: \"Create a value\", description: \"Pick a playlist or create one from what was typed.\" },\n      { name: \"invalid\", title: \"With an error\", description: \"A required choice left empty: the error is read with the field.\" },\n    ],\n  },\n} satisfies ComponentMeta;\n"
+      "content": "import type { ComponentMeta } from \"../meta\";\n\nexport const meta = {\n  title: \"Combobox\",\n  summary: \"A text field that suggests and completes — one value or several as chips, from a static list or a server, with values created from what was typed.\",\n  status: \"beta\",\n  category: \"forms\",\n  platforms: \"both\",\n  whenToUse: [\n    \"To choose among many values the person knows by name: a creator, a country, a model, a playlist.\",\n    \"With `onSearch` when the values live on a server (debounced, the previous request aborted).\",\n    \"With `multiple` for several values (collaborators, categories), and `creatable` when a new one can be added.\",\n  ],\n  whenNotToUse: [\n    { when: \"For fewer than about seven options known in advance: radios or a select.\", use: \"radio-group\" },\n    { when: \"For free words without a closed list (tags, keywords): a tag input.\", use: \"tag-input\" },\n    { when: \"To run a search and show results: a search field.\", use: \"search-field\" },\n  ],\n  bestPractices: [\n    \"Write `label` as the question (“Collaborators”), the `placeholder` as an example (“Type a name”).\",\n    \"Return at most 20 options from `onSearch`; put the best match first.\",\n    \"Give options a `description` when names collide (two creators named Eric: their handles).\",\n    \"Set `maxSelected` when the product has a limit, and say it in `hint`.\",\n  ],\n  accessibility: {\n    keyboard: [\n      { keys: \"Arrow Down / Arrow Up\", action: \"Open the list and move the active option.\" },\n      { keys: \"Home / End\", action: \"First or last option, when the list is open.\" },\n      { keys: \"Enter\", action: \"Choose the active option (or create the typed value).\" },\n      { keys: \"Esc\", action: \"Close the list; for one value, restore its label.\" },\n      { keys: \"Backspace\", action: \"In an empty input, remove the last chip.\" },\n    ],\n    notes: [\n      \"The ARIA 1.2 combobox pattern: the focus stays in the input, `aria-activedescendant` points at the active option of the `listbox`.\",\n      \"The number of results is announced in a polite live region (`labels.results`).\",\n      \"Chosen options carry `aria-selected`; each chip's remove button is named (“Remove Eric”).\",\n      \"The label is a real `<label>`; `hint` and `error` are wired with `aria-describedby`, `error` sets `aria-invalid`.\",\n    ],\n  },\n  related: [\"tag-input\", \"search-field\", \"field\", \"chip\", \"command\"],\n  web: {\n    imports: [\"Combobox\"],\n    examples: [\n      { name: \"async\", title: \"From a server\", description: \"`onSearch`: creators fetched as you type, debounced, the stale request aborted.\" },\n      { name: \"multiple\", title: \"Several values\", description: \"Collaborators as chips; Backspace removes the last one, at most three.\" },\n      { name: \"creatable\", title: \"Create a value\", description: \"Pick a playlist or create one from what was typed.\" },\n      { name: \"invalid\", title: \"With an error\", description: \"A required choice left empty: the error is read with the field.\" },\n    ],\n  },\n  native: {\n    imports: [\"Combobox\"],\n    differences: [\n      \"A field that opens a `Sheet` with a search box and the matching options: radios for one value, checkboxes and a Done button with `multiple`.\",\n      \"`onSearch(query, signal)` is debounced (250 ms) and aborted by a newer query, as on the web; no `creatable` yet.\",\n    ],\n    examples: [\n      { name: \"search\", title: \"Search\", description: \"Cities filtered as you type.\" },\n      { name: \"multiple\", title: \"Several values\", description: \"Interests as checkboxes; the field lists them.\" },\n    ],\n  },\n} satisfies ComponentMeta;\n"
     },
     {
       "path": "glyphs.tsx",

package/registry/date-picker.json

@@ -1115,6 +1115,13 @@
             "description": "Marks the group invalid (a danger edge): pair it with an error read through `aria-describedby`.",
             "required": false
           },
+          {
+            "name": "unset",
+            "type": "boolean",
+            "default": null,
+            "description": "Nothing is chosen yet: the values under the band stay quiet until a wheel is turned.",
+            "required": false
+          },
           {
             "name": "visible",
             "type": "3 | 5 | 7",
@@ -1440,7 +1447,7 @@
     },
     {
       "path": "date-picker/date-field.tsx",
-      "content": "// Client. Two ways to give a memorable date — a birth date, an expiry — that a calendar would make slow to reach:\n// `DateField` (day · month · year typed in the locale's order, the next box focused once one is full; the web form's\n// `entry=\"parts\"`) and `DateWheel` (three wheels: the touch idiom, bounded by `min` / `max` — an age gate is\n// `max={latestBirthDate(18)}`). The value is `YYYY-MM-DD` either way, like the native `DateField` and `DateWheel`.\nimport * as React from \"react\";\n\nimport { useControllable } from \"../media\";\nimport { tv } from \"../tv\";\nimport { composeDate, DATE_PART_LENGTH, type DatePart, datePartsOrder, daysInMonth, isoOf, isoParts, monthNames, splitDate, todayIso, yearRange } from \"./parts\";\nimport { Wheel, WheelPicker } from \"./wheel\";\n\nexport const dateField = tv({\n  slots: {\n    root: \"flex flex-col gap-1.5 border-0 p-0\",\n    legend: \"mb-1.5 p-0 text-xs font-semibold text-fg-secondary\",\n    row: \"flex gap-2\",\n    part: \"flex flex-col gap-1 text-xs text-fg-secondary\",\n    input:\n      \"h-11 rounded-lg border border-border-default bg-surface-2 px-2 text-center text-base tabular-nums text-fg inset-shadow-well transition-[border-color,box-shadow] \" +\n      \"placeholder:text-fg-muted focus-visible:border-accent focus-visible:outline-hidden focus-visible:focus-ring-inset aria-invalid:border-danger disabled:cursor-not-allowed disabled:opacity-50\",\n    hint: \"text-xs text-fg-secondary\",\n    error: \"flex items-center gap-1.5 text-xs font-medium text-fg-danger before:h-1.5 before:w-1.5 before:shrink-0 before:rounded-full before:bg-danger\",\n  },\n});\n\nexport type DateFieldLabels = {\n  /** The name of the day (\"Day\"). */\n  day: string;\n  /** The name of the month (\"Month\"). */\n  month: string;\n  /** The name of the year (\"Year\"). */\n  year: string;\n};\n\nexport const dateFieldLabels: DateFieldLabels = { day: \"Day\", month: \"Month\", year: \"Year\" };\n\ntype Common = {\n  /** The visible label, passed translated (the group's name). */\n  label: string;\n  /** The BCP 47 locale: the order of the parts, the names of the months. */\n  locale: string;\n  /** A help text under the field (\"For example, 27 3 1990\"). */\n  hint?: string;\n  /** An error under the field: marks it invalid and is read with it. Replaces the hint. */\n  error?: string;\n  /** Not available. */\n  disabled?: boolean;\n  /** The name of a hidden input holding the value, for a plain `<form>` post. */\n  name?: string;\n  /** The names of the parts, passed translated; English by default. */\n  labels?: Partial<DateFieldLabels>;\n  /** Classes merged on the root. */\n  className?: string;\n};\n\nexport type DateFieldProps = Common & {\n  /** The date, `YYYY-MM-DD` (controlled); `\"\"` for none. What is typed comes back as it is, real date or not: the schema decides. */\n  value?: string;\n  /** The date at first, uncontrolled. */\n  defaultValue?: string;\n  /** Called on every key with the date typed so far (`\"\"` when the boxes are empty). */\n  onValueChange?: (value: string) => void;\n  /** Called when the focus leaves the field. */\n  onBlur?: () => void;\n  /** `bday` for a date of birth: the browser offers to fill it. */\n  autoComplete?: \"bday\" | \"off\";\n};\n\nfunction Caption({ id, hint, error }: { id: string; hint?: string; error?: string }) {\n  const s = dateField();\n  if (error)\n    return (\n      <p id={`${id}-error`} className={s.error()}>\n        {error}\n      </p>\n    );\n  return hint ? (\n    <p id={`${id}-hint`} className={s.hint()}>\n      {hint}\n    </p>\n  ) : null;\n}\n\n/** Day · month · year typed in the locale's order: numeric keyboards, the next box focused when one is full. */\nexport function DateField({ label, locale, hint, error, disabled, name, labels: given, className, value: valueProp, defaultValue = \"\", onValueChange, onBlur, autoComplete }: DateFieldProps) {\n  const labels = { ...dateFieldLabels, ...given };\n  const s = dateField();\n  const id = React.useId();\n  const [value, setValue] = useControllable<string>(valueProp, defaultValue, onValueChange);\n  const order = React.useMemo(() => datePartsOrder(locale), [locale]);\n  const [parts, setParts] = React.useState(() => splitDate(value));\n  // A value set from outside (a reset, a suggestion) replaces what is in the boxes.\n  if ((value ?? \"\") !== composeDate(parts) && composeDate(splitDate(value)) === (value ?? \"\")) setParts(splitDate(value));\n  const refs = { day: React.useRef<HTMLInputElement>(null), month: React.useRef<HTMLInputElement>(null), year: React.useRef<HTMLInputElement>(null) };\n  const describedBy = error ? `${id}-error` : hint ? `${id}-hint` : undefined;\n  return (\n    <fieldset className={s.root({ className })} aria-describedby={describedBy} onBlur={(e) => !e.currentTarget.contains(e.relatedTarget as Node | null) && onBlur?.()}>\n      <legend className={s.legend()}>{label}</legend>\n      <div className={s.row()}>\n        {order.map((part: DatePart) => (\n          <label key={part} className={s.part()}>\n            {labels[part]}\n            <input\n              ref={refs[part]}\n              inputMode=\"numeric\"\n              autoComplete={autoComplete === \"bday\" ? `bday-${part}` : \"off\"}\n              maxLength={DATE_PART_LENGTH[part]}\n              value={parts[part]}\n              disabled={disabled}\n              aria-invalid={error ? true : undefined}\n              className={s.input({ className: part === \"year\" ? \"w-20\" : \"w-14\" })}\n              onChange={(e) => {\n                const digits = e.target.value.replace(/\\D/g, \"\").slice(0, DATE_PART_LENGTH[part]);\n                const next = { ...parts, [part]: digits };\n                setParts(next);\n                setValue(composeDate(next));\n                const following = order[order.indexOf(part) + 1];\n                if (digits.length === DATE_PART_LENGTH[part] && following) refs[following].current?.focus();\n              }}\n            />\n          </label>\n        ))}\n      </div>\n      {name ? <input type=\"hidden\" name={name} value={value ?? \"\"} /> : null}\n      <Caption id={id} hint={hint} error={error} />\n    </fieldset>\n  );\n}\n\nexport type DateWheelProps = Common & {\n  /** The date, `YYYY-MM-DD` (controlled); `\"\"` or `null` for none (the wheels then rest on `defaultView`). */\n  value?: string | null;\n  /** The date at first, uncontrolled. */\n  defaultValue?: string | null;\n  /** Called with the date under the band, always a real date within `min` / `max`. */\n  onValueChange?: (value: string) => void;\n  /** The earliest date (ISO): the years start there, the days before it are refused. Default: 120 years ago. */\n  min?: string;\n  /** The latest date (ISO): `latestBirthDate(18)` for an age gate. Default: today. */\n  max?: string;\n  /** Where the wheels rest while there is no value. Default: `max` (a birth date: the youngest allowed). */\n  defaultView?: string;\n};\n\n/** Day, month and year as three wheels in the locale's order, bounded by `min` and `max`: always a real date. */\nexport function DateWheel({ label, locale, hint, error, disabled, name, labels: given, className, value: valueProp, defaultValue = null, onValueChange, min, max, defaultView }: DateWheelProps) {\n  const labels = { ...dateFieldLabels, ...given };\n  const id = React.useId();\n  const [value, setValue] = useControllable<string | null>(valueProp, defaultValue, (v) => v && onValueChange?.(v));\n  const today = todayIso();\n  const hi = max ?? today;\n  const lo = min ?? isoOf(Number(today.slice(0, 4)) - 120, 1, 1);\n  const shown = value || defaultView || hi;\n  const { year, month, day } = isoParts(shown);\n  const order = React.useMemo(() => datePartsOrder(locale), [locale]);\n  const months = React.useMemo(() => monthNames(locale, \"long\"), [locale]);\n  const number = React.useMemo(() => new Intl.NumberFormat(locale, { useGrouping: false }), [locale]);\n  const inBounds = (iso: string) => iso >= lo && iso <= hi;\n  const set = (y: number, m: number, d: number) => {\n    let next = isoOf(y, m, d);\n    if (next > hi) next = hi;\n    if (next < lo) next = lo;\n    setValue(next);\n  };\n  const lastDay = daysInMonth(year, month);\n  const columns: Record<DatePart, React.ReactNode> = {\n    day: (\n      <Wheel\n        key=\"day\"\n        label={labels.day}\n        disabled={disabled}\n        options={Array.from({ length: lastDay }, (_, i) => ({ value: String(i + 1), label: number.format(i + 1), disabled: !inBounds(isoOf(year, month, i + 1)) }))}\n        value={String(Math.min(day, lastDay))}\n        onValueChange={(v) => set(year, month, Number(v))}\n        className=\"min-w-14\"\n      />\n    ),\n    month: (\n      <Wheel\n        key=\"month\"\n        label={labels.month}\n        disabled={disabled}\n        options={months.map((n, i) => ({ value: String(i + 1), label: n, disabled: isoOf(year, i + 1, daysInMonth(year, i + 1)) < lo || isoOf(year, i + 1, 1) > hi }))}\n        value={String(month)}\n        onValueChange={(v) => set(year, Number(v), day)}\n        className=\"min-w-32 capitalize\"\n      />\n    ),\n    year: (\n      <Wheel\n        key=\"year\"\n        label={labels.year}\n        disabled={disabled}\n        options={yearRange(Number(hi.slice(0, 4)), Number(lo.slice(0, 4))).map((y) => ({ value: String(y), label: number.format(y) }))}\n        value={String(year)}\n        onValueChange={(v) => set(Number(v), month, day)}\n        className=\"min-w-20\"\n      />\n    ),\n  };\n  return (\n    <div className={dateField().root({ className })}>\n      <span aria-hidden className={dateField().legend()}>\n        {label}\n      </span>\n      <WheelPicker label={label} aria-describedby={error ? `${id}-error` : hint ? `${id}-hint` : undefined} invalid={Boolean(error)}>{order.map((part) => columns[part])}</WheelPicker>\n      {name ? <input type=\"hidden\" name={name} value={value ?? \"\"} /> : null}\n      <Caption id={id} hint={hint} error={error} />\n    </div>\n  );\n}\n"
+      "content": "// Client. Two ways to give a memorable date — a birth date, an expiry — that a calendar would make slow to reach:\n// `DateField` (day · month · year typed in the locale's order, the next box focused once one is full; the web form's\n// `entry=\"parts\"`) and `DateWheel` (three wheels: the touch idiom, bounded by `min` / `max` — an age gate is\n// `max={latestBirthDate(18)}`). The value is `YYYY-MM-DD` either way, like the native `DateField` and `DateWheel`.\nimport * as React from \"react\";\n\nimport { useControllable } from \"../media\";\nimport { tv } from \"../tv\";\nimport { composeDate, DATE_PART_LENGTH, type DatePart, datePartsOrder, daysInMonth, isoOf, isoParts, monthNames, splitDate, todayIso, yearRange } from \"./parts\";\nimport { Wheel, WheelPicker } from \"./wheel\";\n\nexport const dateField = tv({\n  slots: {\n    root: \"flex flex-col gap-1.5 border-0 p-0\",\n    legend: \"mb-1.5 p-0 text-xs font-semibold text-fg-secondary\",\n    row: \"flex gap-2\",\n    part: \"flex flex-col gap-1 text-xs text-fg-secondary\",\n    input:\n      \"h-11 rounded-lg border border-border-default bg-surface-2 px-2 text-center text-base tabular-nums text-fg inset-shadow-well transition-[border-color,box-shadow] \" +\n      \"placeholder:text-fg-muted focus-visible:border-accent focus-visible:outline-hidden focus-visible:focus-ring-inset aria-invalid:border-danger disabled:cursor-not-allowed disabled:opacity-50\",\n    hint: \"text-xs text-fg-secondary\",\n    error: \"flex items-center gap-1.5 text-xs font-medium text-fg-danger before:h-1.5 before:w-1.5 before:shrink-0 before:rounded-full before:bg-danger\",\n  },\n});\n\nexport type DateFieldLabels = {\n  /** The name of the day (\"Day\"). */\n  day: string;\n  /** The name of the month (\"Month\"). */\n  month: string;\n  /** The name of the year (\"Year\"). */\n  year: string;\n};\n\nexport const dateFieldLabels: DateFieldLabels = { day: \"Day\", month: \"Month\", year: \"Year\" };\n\ntype Common = {\n  /** The visible label, passed translated (the group's name). */\n  label: string;\n  /** The BCP 47 locale: the order of the parts, the names of the months. */\n  locale: string;\n  /** A help text under the field (\"For example, 27 3 1990\"). */\n  hint?: string;\n  /** An error under the field: marks it invalid and is read with it. Replaces the hint. */\n  error?: string;\n  /** Not available. */\n  disabled?: boolean;\n  /** The name of a hidden input holding the value, for a plain `<form>` post. */\n  name?: string;\n  /** The names of the parts, passed translated; English by default. */\n  labels?: Partial<DateFieldLabels>;\n  /** Classes merged on the root. */\n  className?: string;\n};\n\nexport type DateFieldProps = Common & {\n  /** The date, `YYYY-MM-DD` (controlled); `\"\"` for none. What is typed comes back as it is, real date or not: the schema decides. */\n  value?: string;\n  /** The date at first, uncontrolled. */\n  defaultValue?: string;\n  /** Called on every key with the date typed so far (`\"\"` when the boxes are empty). */\n  onValueChange?: (value: string) => void;\n  /** Called when the focus leaves the field. */\n  onBlur?: () => void;\n  /** `bday` for a date of birth: the browser offers to fill it. */\n  autoComplete?: \"bday\" | \"off\";\n};\n\nfunction Caption({ id, hint, error }: { id: string; hint?: string; error?: string }) {\n  const s = dateField();\n  if (error)\n    return (\n      <p id={`${id}-error`} className={s.error()}>\n        {error}\n      </p>\n    );\n  return hint ? (\n    <p id={`${id}-hint`} className={s.hint()}>\n      {hint}\n    </p>\n  ) : null;\n}\n\n/** Day · month · year typed in the locale's order: numeric keyboards, the next box focused when one is full. */\nexport function DateField({ label, locale, hint, error, disabled, name, labels: given, className, value: valueProp, defaultValue = \"\", onValueChange, onBlur, autoComplete }: DateFieldProps) {\n  const labels = { ...dateFieldLabels, ...given };\n  const s = dateField();\n  const id = React.useId();\n  const [value, setValue] = useControllable<string>(valueProp, defaultValue, onValueChange);\n  const order = React.useMemo(() => datePartsOrder(locale), [locale]);\n  const [parts, setParts] = React.useState(() => splitDate(value));\n  // A value set from outside (a reset, a suggestion) replaces what is in the boxes.\n  if ((value ?? \"\") !== composeDate(parts) && composeDate(splitDate(value)) === (value ?? \"\")) setParts(splitDate(value));\n  const refs = { day: React.useRef<HTMLInputElement>(null), month: React.useRef<HTMLInputElement>(null), year: React.useRef<HTMLInputElement>(null) };\n  const describedBy = error ? `${id}-error` : hint ? `${id}-hint` : undefined;\n  return (\n    <fieldset className={s.root({ className })} aria-describedby={describedBy} onBlur={(e) => !e.currentTarget.contains(e.relatedTarget as Node | null) && onBlur?.()}>\n      <legend className={s.legend()}>{label}</legend>\n      <div className={s.row()}>\n        {order.map((part: DatePart) => (\n          <label key={part} className={s.part()}>\n            {labels[part]}\n            <input\n              ref={refs[part]}\n              inputMode=\"numeric\"\n              autoComplete={autoComplete === \"bday\" ? `bday-${part}` : \"off\"}\n              maxLength={DATE_PART_LENGTH[part]}\n              value={parts[part]}\n              disabled={disabled}\n              aria-invalid={error ? true : undefined}\n              className={s.input({ className: part === \"year\" ? \"w-20\" : \"w-14\" })}\n              onChange={(e) => {\n                const digits = e.target.value.replace(/\\D/g, \"\").slice(0, DATE_PART_LENGTH[part]);\n                const next = { ...parts, [part]: digits };\n                setParts(next);\n                setValue(composeDate(next));\n                const following = order[order.indexOf(part) + 1];\n                if (digits.length === DATE_PART_LENGTH[part] && following) refs[following].current?.focus();\n              }}\n            />\n          </label>\n        ))}\n      </div>\n      {name ? <input type=\"hidden\" name={name} value={value ?? \"\"} /> : null}\n      <Caption id={id} hint={hint} error={error} />\n    </fieldset>\n  );\n}\n\nexport type DateWheelProps = Common & {\n  /** The date, `YYYY-MM-DD` (controlled); `\"\"` or `null` for none (the wheels then rest on `defaultView`). */\n  value?: string | null;\n  /** The date at first, uncontrolled. */\n  defaultValue?: string | null;\n  /** Called with the date under the band, always a real date within `min` / `max`. */\n  onValueChange?: (value: string) => void;\n  /** The earliest date (ISO): the years start there, the days before it are refused. Default: 120 years ago. */\n  min?: string;\n  /** The latest date (ISO): `latestBirthDate(18)` for an age gate. Default: today. */\n  max?: string;\n  /** Where the wheels rest while there is no value. Default: `max` (a birth date: the youngest allowed). */\n  defaultView?: string;\n};\n\n/** Day, month and year as three wheels in the locale's order, bounded by `min` and `max`: always a real date. */\nexport function DateWheel({ label, locale, hint, error, disabled, name, labels: given, className, value: valueProp, defaultValue = null, onValueChange, min, max, defaultView }: DateWheelProps) {\n  const labels = { ...dateFieldLabels, ...given };\n  const id = React.useId();\n  const [value, setValue] = useControllable<string | null>(valueProp, defaultValue, (v) => v && onValueChange?.(v));\n  const today = todayIso();\n  const hi = max ?? today;\n  const lo = min ?? isoOf(Number(today.slice(0, 4)) - 120, 1, 1);\n  const shown = value || defaultView || hi;\n  const { year, month, day } = isoParts(shown);\n  const order = React.useMemo(() => datePartsOrder(locale), [locale]);\n  const months = React.useMemo(() => monthNames(locale, \"long\"), [locale]);\n  const number = React.useMemo(() => new Intl.NumberFormat(locale, { useGrouping: false }), [locale]);\n  const inBounds = (iso: string) => iso >= lo && iso <= hi;\n  const set = (y: number, m: number, d: number) => {\n    let next = isoOf(y, m, d);\n    if (next > hi) next = hi;\n    if (next < lo) next = lo;\n    setValue(next);\n  };\n  const lastDay = daysInMonth(year, month);\n  const columns: Record<DatePart, React.ReactNode> = {\n    day: (\n      <Wheel\n        key=\"day\"\n        label={labels.day}\n        disabled={disabled}\n        options={Array.from({ length: lastDay }, (_, i) => ({ value: String(i + 1), label: number.format(i + 1), disabled: !inBounds(isoOf(year, month, i + 1)) }))}\n        value={String(Math.min(day, lastDay))}\n        onValueChange={(v) => set(year, month, Number(v))}\n        className=\"min-w-14\"\n      />\n    ),\n    month: (\n      <Wheel\n        key=\"month\"\n        label={labels.month}\n        disabled={disabled}\n        options={months.map((n, i) => ({ value: String(i + 1), label: n, disabled: isoOf(year, i + 1, daysInMonth(year, i + 1)) < lo || isoOf(year, i + 1, 1) > hi }))}\n        value={String(month)}\n        onValueChange={(v) => set(year, Number(v), day)}\n        className=\"min-w-32 capitalize\"\n      />\n    ),\n    year: (\n      <Wheel\n        key=\"year\"\n        label={labels.year}\n        disabled={disabled}\n        options={yearRange(Number(hi.slice(0, 4)), Number(lo.slice(0, 4))).map((y) => ({ value: String(y), label: number.format(y) }))}\n        value={String(year)}\n        onValueChange={(v) => set(Number(v), month, day)}\n        className=\"min-w-20\"\n      />\n    ),\n  };\n  return (\n    <div className={dateField().root({ className })}>\n      <span aria-hidden className={dateField().legend()}>\n        {label}\n      </span>\n      <WheelPicker label={label} aria-describedby={error ? `${id}-error` : hint ? `${id}-hint` : undefined} invalid={Boolean(error)} unset={!value}>{order.map((part) => columns[part])}</WheelPicker>\n      {name ? <input type=\"hidden\" name={name} value={value ?? \"\"} /> : null}\n      <Caption id={id} hint={hint} error={error} />\n    </div>\n  );\n}\n"
     },
     {
       "path": "date-picker/date-picker.tsx",
@@ -1472,7 +1479,7 @@
     },
     {
       "path": "date-picker/wheel.tsx",
-      "content": "// Client. A wheel: a column of values that turns under a lit band — the touch idiom of a time, a date of birth, a\n// quantity. Each column is a `spinbutton` for assistive technologies and the keyboard (Up / Down, Page Up / Page Down by\n// five, Home / End), its value read as words (`aria-valuetext`); the hand scrolls it (scroll snap) or clicks a value.\n// The curve is a scroll-driven animation (CSS `animation-timeline: view()`): no script per frame, flat where unsupported.\nimport * as React from \"react\";\n\nimport { usePrefersReducedMotion } from \"../media\";\nimport { tv } from \"../tv\";\n\n/** A value of a wheel: what is stored, and its words (passed translated or formatted for the locale). */\nexport type WheelOption = { value: string; label: string; disabled?: boolean };\n\nexport const wheel = tv({\n  slots: {\n    root: \"relative inline-flex select-none items-stretch gap-1 rounded-2xl border border-border-default data-[invalid]:border-danger bg-surface-1 bg-sheen px-2 shadow-raised inset-shadow-edge\",\n    band: \"pointer-events-none absolute inset-x-1.5 top-1/2 -translate-y-1/2 rounded-xl border border-border-subtle bg-surface-3 inset-shadow-well\",\n    column:\n      \"relative z-[1] min-w-14 flex-1 rounded-xl outline-hidden focus-visible:focus-ring-inset data-[disabled]:pointer-events-none data-[disabled]:opacity-40\",\n    scroller:\n      \"kz-wheel h-full snap-y snap-mandatory overflow-y-auto overscroll-contain [scrollbar-width:none] [&::-webkit-scrollbar]:hidden \" +\n      \"[mask-image:linear-gradient(to_bottom,transparent,#000_30%,#000_70%,transparent)]\",\n    item:\n      \"kz-wheel-item flex snap-center items-center justify-center px-2 text-base tabular-nums text-fg-secondary transition-colors \" +\n      \"data-[selected]:font-semibold data-[selected]:text-fg data-[disabled]:text-fg-muted data-[disabled]:line-through\",\n    divider: \"z-[1] self-center text-base font-semibold text-fg-secondary\",\n  },\n});\n\nconst ITEM = 40;\n\nexport type WheelProps = {\n  /** The column's accessible name (\"Hour\", \"Month\"), passed translated. */\n  label: string;\n  /** The values, in order. */\n  options: readonly WheelOption[];\n  /** The chosen value (controlled). */\n  value?: string | null;\n  /** The chosen value at first, uncontrolled. Default: the first one. */\n  defaultValue?: string;\n  /** Called with the value that comes to rest under the band. */\n  onValueChange?: (value: string) => void;\n  /** Not available. */\n  disabled?: boolean;\n  /** Classes merged on the column (a width: `w-20`). */\n  className?: string;\n};\n\nexport type WheelPickerProps = {\n  /** The group's accessible name (\"Departure time\"), passed translated. */\n  label: string;\n  /** The wheels (`Wheel`), and dividers (`WheelDivider`) between them. */\n  children: React.ReactNode;\n  /** How many values are visible: 3, 5 (default) or 7. */\n  visible?: 3 | 5 | 7;\n  /** The help text or the error that describes the group (their ids). */\n  \"aria-describedby\"?: string;\n  /** Marks the group invalid (a danger edge): pair it with an error read through `aria-describedby`. */\n  invalid?: boolean;\n  /** Classes merged on the root. */\n  className?: string;\n};\n\nconst VisibleContext = React.createContext(5);\n\n/** The frame of one or several wheels: a raised surface, the lit band across them, a group named by `label`. */\nexport function WheelPicker({ label, children, visible = 5, \"aria-describedby\": describedBy, invalid, className }: WheelPickerProps) {\n  const s = wheel();\n  return (\n    <VisibleContext.Provider value={visible}>\n      <div role=\"group\" aria-label={label} aria-describedby={describedBy} data-invalid={invalid ? \"\" : undefined} className={s.root({ className })} style={{ height: ITEM * visible }}>\n        <span aria-hidden className={s.band()} style={{ height: ITEM }} />\n        {children}\n      </div>\n    </VisibleContext.Provider>\n  );\n}\n\n/** A divider between two wheels (`:` between the hours and the minutes). */\nexport function WheelDivider({ children }: { children: React.ReactNode }) {\n  return (\n    <span aria-hidden className={wheel().divider()}>\n      {children}\n    </span>\n  );\n}\n\nconst nearestEnabled = (options: readonly WheelOption[], index: number) => {\n  for (let d = 0; d < options.length; d++) {\n    if (options[index + d] && !options[index + d]!.disabled) return index + d;\n    if (options[index - d] && !options[index - d]!.disabled) return index - d;\n  }\n  return index;\n};\n\n/** One column of a `WheelPicker`: a spinbutton over a scroll-snapped list of values. */\nexport function Wheel({ label, options, value: valueProp, defaultValue, onValueChange, disabled, className }: WheelProps) {\n  const s = wheel();\n  const visible = React.useContext(VisibleContext);\n  const [own, setOwn] = React.useState(defaultValue ?? options[0]?.value ?? \"\");\n  const value = valueProp ?? own;\n  const index = Math.max(0, options.findIndex((o) => o.value === value));\n  const scroller = React.useRef<HTMLDivElement>(null);\n  const settle = React.useRef<ReturnType<typeof setTimeout> | null>(null);\n  const programmatic = React.useRef(false);\n  const reduce = usePrefersReducedMotion();\n  const mounted = React.useRef(false);\n\n  const commit = React.useCallback(\n    (i: number) => {\n      const target = nearestEnabled(options, Math.min(options.length - 1, Math.max(0, i)));\n      const option = options[target];\n      if (!option) return;\n      if (valueProp === undefined) setOwn(option.value);\n      if (option.value !== value) onValueChange?.(option.value);\n    },\n    [options, valueProp, value, onValueChange],\n  );\n\n  // The list follows the value (a key, a click, a change from outside): at once the first time, smoothly after.\n  React.useEffect(() => {\n    const el = scroller.current;\n    if (!el) return;\n    const top = index * ITEM;\n    if (Math.abs(el.scrollTop - top) < 1) return;\n    programmatic.current = true;\n    if (typeof el.scrollTo === \"function\") el.scrollTo({ top, behavior: mounted.current && !reduce ? \"smooth\" : \"auto\" });\n    else el.scrollTop = top;\n    mounted.current = true;\n    const t = setTimeout(() => (programmatic.current = false), 400);\n    return () => clearTimeout(t);\n  }, [index, reduce]);\n\n  const onScroll = () => {\n    if (programmatic.current) return;\n    if (settle.current) clearTimeout(settle.current);\n    settle.current = setTimeout(() => {\n      const el = scroller.current;\n      if (el) commit(Math.round(el.scrollTop / ITEM));\n    }, 90);\n  };\n  React.useEffect(() => () => void (settle.current && clearTimeout(settle.current)), []);\n\n  const onKeyDown = (event: React.KeyboardEvent) => {\n    const step = (by: number) => {\n      let i = index + by;\n      while (options[i]?.disabled) i += Math.sign(by);\n      return options[i] ? i : index;\n    };\n    const moves: Record<string, () => number> = {\n      ArrowUp: () => step(-1),\n      ArrowDown: () => step(1),\n      PageUp: () => Math.max(0, nearestEnabled(options, index - 5)),\n      PageDown: () => Math.min(options.length - 1, nearestEnabled(options, index + 5)),\n      Home: () => nearestEnabled(options, 0),\n      End: () => nearestEnabled(options, options.length - 1),\n    };\n    const move = moves[event.key];\n    if (!move) return;\n    event.preventDefault();\n    commit(move());\n  };\n\n  const pad = ((visible - 1) / 2) * ITEM;\n  const current = options[index];\n  return (\n    <div\n      role=\"spinbutton\"\n      tabIndex={disabled ? -1 : 0}\n      aria-label={label}\n      aria-valuenow={index}\n      aria-valuemin={0}\n      aria-valuemax={Math.max(0, options.length - 1)}\n      aria-valuetext={current?.label}\n      aria-disabled={disabled || undefined}\n      data-disabled={disabled ? \"\" : undefined}\n      className={s.column({ className })}\n      onKeyDown={onKeyDown}\n    >\n      <div ref={scroller} aria-hidden className={s.scroller()} style={{ paddingBlock: pad, scrollPaddingBlock: pad }} onScroll={onScroll}>\n        {options.map((o, i) => (\n          <div\n            key={o.value}\n            data-value={o.value}\n            data-selected={i === index ? \"\" : undefined}\n            data-disabled={o.disabled ? \"\" : undefined}\n            className={s.item()}\n            style={{ height: ITEM }}\n            onClick={() => !o.disabled && commit(i)}\n          >\n            {o.label}\n          </div>\n        ))}\n      </div>\n    </div>\n  );\n}\n"
+      "content": "// Client. A wheel: a column of values that turns under a lit band — the touch idiom of a time, a date of birth, a\n// quantity. Each column is a `spinbutton` for assistive technologies and the keyboard (Up / Down, Page Up / Page Down by\n// five, Home / End), its value read as words (`aria-valuetext`); the hand scrolls it (scroll snap) or clicks a value.\n// The curve is a scroll-driven animation (CSS `animation-timeline: view()`): no script per frame, flat where unsupported.\nimport * as React from \"react\";\n\nimport { usePrefersReducedMotion } from \"../media\";\nimport { tv } from \"../tv\";\n\n/** A value of a wheel: what is stored, and its words (passed translated or formatted for the locale). */\nexport type WheelOption = { value: string; label: string; disabled?: boolean };\n\nexport const wheel = tv({\n  slots: {\n    root: \"group/wheel relative inline-flex select-none items-stretch gap-1 rounded-2xl border border-border-default data-[invalid]:border-danger bg-surface-1 bg-sheen px-2 shadow-raised inset-shadow-edge\",\n    band: \"pointer-events-none absolute inset-x-1.5 top-1/2 -translate-y-1/2 rounded-xl border border-border-subtle bg-surface-3 inset-shadow-well\",\n    column:\n      \"relative z-[1] min-w-14 flex-1 rounded-xl outline-hidden focus-visible:focus-ring-inset data-[disabled]:pointer-events-none data-[disabled]:opacity-40\",\n    scroller:\n      \"kz-wheel h-full snap-y snap-mandatory overflow-y-auto overscroll-contain [scrollbar-width:none] [&::-webkit-scrollbar]:hidden \" +\n      \"[mask-image:linear-gradient(to_bottom,transparent,#000_30%,#000_70%,transparent)]\",\n    item:\n      \"kz-wheel-item flex snap-center items-center justify-center px-2 text-base tabular-nums text-fg-secondary transition-colors \" +\n      \"data-[selected]:font-semibold data-[selected]:text-fg data-[disabled]:text-fg-muted data-[disabled]:line-through \" +\n      \"group-data-[unset]/wheel:data-[selected]:font-normal group-data-[unset]/wheel:data-[selected]:text-fg-secondary\",\n    divider: \"z-[1] self-center text-base font-semibold text-fg-secondary\",\n  },\n});\n\nconst ITEM = 40;\n\nexport type WheelProps = {\n  /** The column's accessible name (\"Hour\", \"Month\"), passed translated. */\n  label: string;\n  /** The values, in order. */\n  options: readonly WheelOption[];\n  /** The chosen value (controlled). */\n  value?: string | null;\n  /** The chosen value at first, uncontrolled. Default: the first one. */\n  defaultValue?: string;\n  /** Called with the value that comes to rest under the band. */\n  onValueChange?: (value: string) => void;\n  /** Not available. */\n  disabled?: boolean;\n  /** Classes merged on the column (a width: `w-20`). */\n  className?: string;\n};\n\nexport type WheelPickerProps = {\n  /** The group's accessible name (\"Departure time\"), passed translated. */\n  label: string;\n  /** The wheels (`Wheel`), and dividers (`WheelDivider`) between them. */\n  children: React.ReactNode;\n  /** How many values are visible: 3, 5 (default) or 7. */\n  visible?: 3 | 5 | 7;\n  /** The help text or the error that describes the group (their ids). */\n  \"aria-describedby\"?: string;\n  /** Marks the group invalid (a danger edge): pair it with an error read through `aria-describedby`. */\n  invalid?: boolean;\n  /** Nothing is chosen yet: the values under the band stay quiet until a wheel is turned. */\n  unset?: boolean;\n  /** Classes merged on the root. */\n  className?: string;\n};\n\nconst VisibleContext = React.createContext(5);\n\n/** The frame of one or several wheels: a raised surface, the lit band across them, a group named by `label`. */\nexport function WheelPicker({ label, children, visible = 5, \"aria-describedby\": describedBy, invalid, unset, className }: WheelPickerProps) {\n  const s = wheel();\n  return (\n    <VisibleContext.Provider value={visible}>\n      <div role=\"group\" aria-label={label} aria-describedby={describedBy} data-invalid={invalid ? \"\" : undefined} data-unset={unset ? \"\" : undefined} className={s.root({ className })} style={{ height: ITEM * visible }}>\n        <span aria-hidden className={s.band()} style={{ height: ITEM }} />\n        {children}\n      </div>\n    </VisibleContext.Provider>\n  );\n}\n\n/** A divider between two wheels (`:` between the hours and the minutes). */\nexport function WheelDivider({ children }: { children: React.ReactNode }) {\n  return (\n    <span aria-hidden className={wheel().divider()}>\n      {children}\n    </span>\n  );\n}\n\nconst nearestEnabled = (options: readonly WheelOption[], index: number) => {\n  for (let d = 0; d < options.length; d++) {\n    if (options[index + d] && !options[index + d]!.disabled) return index + d;\n    if (options[index - d] && !options[index - d]!.disabled) return index - d;\n  }\n  return index;\n};\n\n/** One column of a `WheelPicker`: a spinbutton over a scroll-snapped list of values. */\nexport function Wheel({ label, options, value: valueProp, defaultValue, onValueChange, disabled, className }: WheelProps) {\n  const s = wheel();\n  const visible = React.useContext(VisibleContext);\n  const [own, setOwn] = React.useState(defaultValue ?? options[0]?.value ?? \"\");\n  const value = valueProp ?? own;\n  const index = Math.max(0, options.findIndex((o) => o.value === value));\n  const scroller = React.useRef<HTMLDivElement>(null);\n  const settle = React.useRef<ReturnType<typeof setTimeout> | null>(null);\n  const programmatic = React.useRef(false);\n  const reduce = usePrefersReducedMotion();\n  const mounted = React.useRef(false);\n\n  const commit = React.useCallback(\n    (i: number) => {\n      const target = nearestEnabled(options, Math.min(options.length - 1, Math.max(0, i)));\n      const option = options[target];\n      if (!option) return;\n      if (valueProp === undefined) setOwn(option.value);\n      if (option.value !== value) onValueChange?.(option.value);\n    },\n    [options, valueProp, value, onValueChange],\n  );\n\n  // The list follows the value (a key, a click, a change from outside): at once the first time, smoothly after.\n  React.useEffect(() => {\n    const el = scroller.current;\n    if (!el) return;\n    const top = index * ITEM;\n    if (Math.abs(el.scrollTop - top) < 1) return;\n    programmatic.current = true;\n    if (typeof el.scrollTo === \"function\") el.scrollTo({ top, behavior: mounted.current && !reduce ? \"smooth\" : \"auto\" });\n    else el.scrollTop = top;\n    mounted.current = true;\n    const t = setTimeout(() => (programmatic.current = false), 400);\n    return () => clearTimeout(t);\n  }, [index, reduce]);\n\n  const onScroll = () => {\n    if (programmatic.current) return;\n    if (settle.current) clearTimeout(settle.current);\n    settle.current = setTimeout(() => {\n      const el = scroller.current;\n      if (el) commit(Math.round(el.scrollTop / ITEM));\n    }, 90);\n  };\n  React.useEffect(() => () => void (settle.current && clearTimeout(settle.current)), []);\n\n  const onKeyDown = (event: React.KeyboardEvent) => {\n    const step = (by: number) => {\n      let i = index + by;\n      while (options[i]?.disabled) i += Math.sign(by);\n      return options[i] ? i : index;\n    };\n    const moves: Record<string, () => number> = {\n      ArrowUp: () => step(-1),\n      ArrowDown: () => step(1),\n      PageUp: () => Math.max(0, nearestEnabled(options, index - 5)),\n      PageDown: () => Math.min(options.length - 1, nearestEnabled(options, index + 5)),\n      Home: () => nearestEnabled(options, 0),\n      End: () => nearestEnabled(options, options.length - 1),\n    };\n    const move = moves[event.key];\n    if (!move) return;\n    event.preventDefault();\n    commit(move());\n  };\n\n  const pad = ((visible - 1) / 2) * ITEM;\n  const current = options[index];\n  return (\n    <div\n      role=\"spinbutton\"\n      tabIndex={disabled ? -1 : 0}\n      aria-label={label}\n      aria-valuenow={index}\n      aria-valuemin={0}\n      aria-valuemax={Math.max(0, options.length - 1)}\n      aria-valuetext={current?.label}\n      aria-disabled={disabled || undefined}\n      data-disabled={disabled ? \"\" : undefined}\n      className={s.column({ className })}\n      onKeyDown={onKeyDown}\n    >\n      <div ref={scroller} aria-hidden className={s.scroller()} style={{ paddingBlock: pad, scrollPaddingBlock: pad }} onScroll={onScroll}>\n        {options.map((o, i) => (\n          <div\n            key={o.value}\n            data-value={o.value}\n            data-selected={i === index ? \"\" : undefined}\n            data-disabled={o.disabled ? \"\" : undefined}\n            className={s.item()}\n            style={{ height: ITEM }}\n            onClick={() => !o.disabled && commit(i)}\n          >\n            {o.label}\n          </div>\n        ))}\n      </div>\n    </div>\n  );\n}\n"
     },
     {
       "path": "glyphs.tsx",
@@ -2540,6 +2547,13 @@
           "description": "Marks the group invalid (a danger edge): pair it with an error read through `aria-describedby`.",
           "required": false
         },
+        {
+          "name": "unset",
+          "type": "boolean",
+          "default": null,
+          "description": "Nothing is chosen yet: the values under the band stay quiet until a wheel is turned.",
+          "required": false
+        },
         {
           "name": "visible",
           "type": "3 | 5 | 7",

package/registry/dialog.json

@@ -6,7 +6,7 @@
   "description": "A window over the page — centred, a bottom sheet or a side panel — and `AlertDialog` for a confirmation.",
   "status": "stable",
   "category": "overlays",
-  "platforms": "web",
+  "platforms": "both",
   "whenToUse": [
     "For a short task that must be finished or cancelled before going back: invite someone, edit a title.",
     "`AlertDialog` to confirm a destructive or irreversible action, with an async `onConfirm`.",
@@ -308,7 +308,78 @@
       }
     ]
   },
-  "native": null,
+  "native": {
+    "entry": "@krizaka/ui/native",
+    "import": "import { Sheet } from \"@krizaka/ui/native\";",
+    "differences": [
+      "One component, `Sheet`: a bottom sheet on React Native's `Modal` (focus kept inside, the back button and the scrim close it), its grip on top, rising with the theme's ease.",
+      "It holds what a phone shows over a screen: a choice (`Select`, `Combobox` use it), the details of a pin on a map, a short form."
+    ],
+    "props": [
+      {
+        "component": "Sheet",
+        "description": "A bottom sheet: it rises over a dimmed screen, its grip on top, the scrim closes it. The web `Dialog` on a phone —\na choice (`Select`, `Combobox`), the details of a pin on a map, a short form. React Native's `Modal`: focus stays\ninside, the back button closes it. Rises with the theme's ease; still under reduced motion.",
+        "props": [
+          {
+            "name": "children",
+            "type": "ReactNode",
+            "default": null,
+            "description": "The content: a list, details, a form.",
+            "required": true
+          },
+          {
+            "name": "onOpenChange",
+            "type": "(open: boolean) => void",
+            "default": null,
+            "description": "Called to close it: the scrim pressed, the back button, a choice made.",
+            "required": true
+          },
+          {
+            "name": "open",
+            "type": "boolean",
+            "default": null,
+            "description": "Open (controlled).",
+            "required": true
+          },
+          {
+            "name": "closeLabel",
+            "type": "string",
+            "default": "Close",
+            "description": "The name of the close action read by screen readers (\"Close\"), passed translated.",
+            "required": false
+          },
+          {
+            "name": "style",
+            "type": "StyleProp<ViewStyle>",
+            "default": null,
+            "description": "Styles merged last, on the sheet.",
+            "required": false
+          },
+          {
+            "name": "title",
+            "type": "string",
+            "default": null,
+            "description": "The title at the top of the sheet (its accessible name), passed translated.",
+            "required": false
+          }
+        ]
+      }
+    ],
+    "examples": [
+      {
+        "name": "sheet",
+        "title": "Bottom sheet",
+        "description": "The details of a pick-up point over the dimmed screen.",
+        "path": "examples/dialog/native/sheet.tsx",
+        "module": "@krizaka/ui/registry/examples/dialog/native/sheet",
+        "code": "import { Button, Sheet, Txt } from \"@krizaka/ui/native\";\nimport * as React from \"react\";\nimport { View } from \"react-native\";\n\n// A bottom sheet: it rises over the dimmed screen, the scrim or the back button closes it.\nexport default function NativeDialogSheet({ defaultOpen }: { defaultOpen?: boolean }) {\n  const [open, setOpen] = React.useState(Boolean(defaultOpen));\n  return (\n    <View>\n      <Button label=\"Show the pick-up point\" onPress={() => setOpen(true)} />\n      <Sheet open={open} onOpenChange={setOpen} title=\"Café Olimpico\">\n        <Txt tone=\"secondary\">124 Rue Saint-Viateur O, Montréal · 350 m away</Txt>\n        <Txt>Open until 10 pm. Ask for the order under your name at the counter.</Txt>\n        <Button label=\"Get directions\" variant=\"primary\" onPress={() => setOpen(false)} />\n      </Sheet>\n    </View>\n  );\n}\n",
+        "screenshots": {
+          "dark": "examples/dialog/native/sheet.dark.png",
+          "light": "examples/dialog/native/sheet.light.png"
+        }
+      }
+    ]
+  },
   "files": [
     {
       "path": "dialog/alert-dialog.tsx",
@@ -324,7 +395,7 @@
     },
     {
       "path": "dialog/meta.ts",
-      "content": "import type { ComponentMeta } from \"../meta\";\n\nexport const meta = {\n  title: \"Dialog\",\n  summary: \"A window over the page — centred, a bottom sheet or a side panel — and `AlertDialog` for a confirmation.\",\n  status: \"stable\",\n  category: \"overlays\",\n  platforms: \"web\",\n  whenToUse: [\n    \"For a short task that must be finished or cancelled before going back: invite someone, edit a title.\",\n    \"`AlertDialog` to confirm a destructive or irreversible action, with an async `onConfirm`.\",\n    \"`Sheet` (bottom) on phones, `placement=\\\"right\\\"` for a side panel of details.\",\n    \"A gate the user must answer (age, terms): `hideClose` and `dismissible={false}`.\",\n  ],\n  whenNotToUse: [\n    { when: \"For information next to an element, without blocking the page.\", use: \"popover\" },\n    { when: \"For a message that needs no answer.\", use: \"toast\" },\n    { when: \"For a long form or a flow of several steps: give it its own page.\" },\n    { when: \"To confirm the deletion of one item in place.\", use: \"confirm-button\" },\n  ],\n  bestPractices: [\n    \"Always a `Dialog.Title`; a `Dialog.Description` when the title is not enough.\",\n    \"Name the buttons by what they do (“Send the invitation”), the cancel one by what it keeps (“Keep it”).\",\n    \"Pass `closeLabel` translated: it names the close button.\",\n  ],\n  accessibility: {\n    keyboard: [\n      { keys: \"Esc\", action: \"Closes the dialog (unless `dismissible={false}`).\" },\n      { keys: \"Tab / Shift+Tab\", action: \"Move within the dialog: the focus is trapped while it is open.\" },\n    ],\n    notes: [\n      \"Radix Dialog: `role=\\\"dialog\\\"` (or `alertdialog`), `aria-modal`, named by its title and described by its description.\",\n      \"The focus moves into the dialog when it opens and returns to the trigger when it closes; the page behind does not scroll.\",\n      \"`AlertDialog` keeps the focus on the cancel button first.\",\n    ],\n  },\n  related: [\"popover\", \"confirm-button\", \"command\", \"toast\"],\n  web: {\n    imports: [\"Dialog\", \"Sheet\", \"AlertDialog\"],\n    examples: [\n      { name: \"center\", title: \"Centred\", description: \"A short form, `size=\\\"md\\\"`.\" },\n      { name: \"bottom\", title: \"Bottom sheet\", description: \"`placement=\\\"bottom\\\"`: a sheet on a phone, centred from `sm` up.\" },\n      { name: \"right\", title: \"Side panel\", description: \"`placement=\\\"right\\\"`: full height, for details.\" },\n      { name: \"left\", title: \"Navigation drawer\", description: \"`placement=\\\"left\\\"`: full height from the left, for an app's navigation on a phone.\" },\n      { name: \"sheet-form\", title: \"Sheet with a form\", description: \"`Sheet`, `size=\\\"lg\\\"`.\" },\n      { name: \"alert-destructive\", title: \"Alert dialog\", description: \"`AlertDialog tone=\\\"danger\\\"` with an async `onConfirm`.\" },\n      { name: \"gate\", title: \"Gate\", description: \"No close button: it closes only through its actions.\" },\n    ],\n  },\n} satisfies ComponentMeta;\n"
+      "content": "import type { ComponentMeta } from \"../meta\";\n\nexport const meta = {\n  title: \"Dialog\",\n  summary: \"A window over the page — centred, a bottom sheet or a side panel — and `AlertDialog` for a confirmation.\",\n  status: \"stable\",\n  category: \"overlays\",\n  platforms: \"both\",\n  whenToUse: [\n    \"For a short task that must be finished or cancelled before going back: invite someone, edit a title.\",\n    \"`AlertDialog` to confirm a destructive or irreversible action, with an async `onConfirm`.\",\n    \"`Sheet` (bottom) on phones, `placement=\\\"right\\\"` for a side panel of details.\",\n    \"A gate the user must answer (age, terms): `hideClose` and `dismissible={false}`.\",\n  ],\n  whenNotToUse: [\n    { when: \"For information next to an element, without blocking the page.\", use: \"popover\" },\n    { when: \"For a message that needs no answer.\", use: \"toast\" },\n    { when: \"For a long form or a flow of several steps: give it its own page.\" },\n    { when: \"To confirm the deletion of one item in place.\", use: \"confirm-button\" },\n  ],\n  bestPractices: [\n    \"Always a `Dialog.Title`; a `Dialog.Description` when the title is not enough.\",\n    \"Name the buttons by what they do (“Send the invitation”), the cancel one by what it keeps (“Keep it”).\",\n    \"Pass `closeLabel` translated: it names the close button.\",\n  ],\n  accessibility: {\n    keyboard: [\n      { keys: \"Esc\", action: \"Closes the dialog (unless `dismissible={false}`).\" },\n      { keys: \"Tab / Shift+Tab\", action: \"Move within the dialog: the focus is trapped while it is open.\" },\n    ],\n    notes: [\n      \"Radix Dialog: `role=\\\"dialog\\\"` (or `alertdialog`), `aria-modal`, named by its title and described by its description.\",\n      \"The focus moves into the dialog when it opens and returns to the trigger when it closes; the page behind does not scroll.\",\n      \"`AlertDialog` keeps the focus on the cancel button first.\",\n    ],\n  },\n  related: [\"popover\", \"confirm-button\", \"command\", \"toast\"],\n  web: {\n    imports: [\"Dialog\", \"Sheet\", \"AlertDialog\"],\n    examples: [\n      { name: \"center\", title: \"Centred\", description: \"A short form, `size=\\\"md\\\"`.\" },\n      { name: \"bottom\", title: \"Bottom sheet\", description: \"`placement=\\\"bottom\\\"`: a sheet on a phone, centred from `sm` up.\" },\n      { name: \"right\", title: \"Side panel\", description: \"`placement=\\\"right\\\"`: full height, for details.\" },\n      { name: \"left\", title: \"Navigation drawer\", description: \"`placement=\\\"left\\\"`: full height from the left, for an app's navigation on a phone.\" },\n      { name: \"sheet-form\", title: \"Sheet with a form\", description: \"`Sheet`, `size=\\\"lg\\\"`.\" },\n      { name: \"alert-destructive\", title: \"Alert dialog\", description: \"`AlertDialog tone=\\\"danger\\\"` with an async `onConfirm`.\" },\n      { name: \"gate\", title: \"Gate\", description: \"No close button: it closes only through its actions.\" },\n    ],\n  },\n  native: {\n    imports: [\"Sheet\"],\n    differences: [\n      \"One component, `Sheet`: a bottom sheet on React Native's `Modal` (focus kept inside, the back button and the scrim close it), its grip on top, rising with the theme's ease.\",\n      \"It holds what a phone shows over a screen: a choice (`Select`, `Combobox` use it), the details of a pin on a map, a short form.\",\n    ],\n    examples: [{ name: \"sheet\", title: \"Bottom sheet\", description: \"The details of a pick-up point over the dimmed screen.\" }],\n  },\n} satisfies ComponentMeta;\n"
     },
     {
       "path": "meta.ts",

package/registry/examples/combobox/native/multiple.d.ts

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

package/registry/examples/combobox/native/multiple.js

@@ -0,0 +1,15 @@
+"use client";
+
+// registry/examples/combobox/native/multiple.tsx
+import { Combobox } from "@krizaka/ui/native";
+import * as React from "react";
+import { View } from "react-native";
+import { jsx } from "react/jsx-runtime";
+var TOPICS = ["Music", "Sport", "Art", "Cooking", "Gaming", "Travel"].map((t) => ({ value: t.toLowerCase(), label: t }));
+function NativeComboboxMultiple() {
+  const [topics, setTopics] = React.useState(["music", "travel"]);
+  return /* @__PURE__ */ jsx(View, { style: { width: 300 }, children: /* @__PURE__ */ jsx(Combobox, { label: "Interests", multiple: true, options: TOPICS, value: topics, onValueChange: (v) => setTopics(Array.isArray(v) ? v : [v]) }) });
+}
+export {
+  NativeComboboxMultiple as default
+};

package/registry/examples/combobox/native/multiple.tsx

@@ -0,0 +1,15 @@
+import { Combobox } from "@krizaka/ui/native";
+import * as React from "react";
+import { View } from "react-native";
+
+const TOPICS = ["Music", "Sport", "Art", "Cooking", "Gaming", "Travel"].map((t) => ({ value: t.toLowerCase(), label: t }));
+
+// Several values: checkboxes in the sheet, Done closes it; the field lists the choices.
+export default function NativeComboboxMultiple() {
+  const [topics, setTopics] = React.useState<string[]>(["music", "travel"]);
+  return (
+    <View style={{ width: 300 }}>
+      <Combobox label="Interests" multiple options={TOPICS} value={topics} onValueChange={(v) => setTopics(Array.isArray(v) ? v : [v])} />
+    </View>
+  );
+}

package/registry/examples/combobox/native/search.d.ts

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

package/registry/examples/combobox/native/search.js

@@ -0,0 +1,15 @@
+"use client";
+
+// registry/examples/combobox/native/search.tsx
+import { Combobox } from "@krizaka/ui/native";
+import * as React from "react";
+import { View } from "react-native";
+import { jsx } from "react/jsx-runtime";
+var CITIES = ["Montr\xE9al", "Qu\xE9bec", "Laval", "Gatineau", "Sherbrooke", "Trois-Rivi\xE8res"].map((c) => ({ value: c.toLowerCase(), label: c }));
+function NativeComboboxSearch() {
+  const [city, setCity] = React.useState("montr\xE9al");
+  return /* @__PURE__ */ jsx(View, { style: { width: 300 }, children: /* @__PURE__ */ jsx(Combobox, { label: "City", placeholder: "Choose a city", options: CITIES, value: city, onValueChange: (v) => setCity(String(v)) }) });
+}
+export {
+  NativeComboboxSearch as default
+};

package/registry/examples/combobox/native/search.tsx

@@ -0,0 +1,15 @@
+import { Combobox } from "@krizaka/ui/native";
+import * as React from "react";
+import { View } from "react-native";
+
+const CITIES = ["Montréal", "Québec", "Laval", "Gatineau", "Sherbrooke", "Trois-Rivières"].map((c) => ({ value: c.toLowerCase(), label: c }));
+
+// A choice among many, searched in a sheet: what is typed filters the options.
+export default function NativeComboboxSearch() {
+  const [city, setCity] = React.useState<string>("montréal");
+  return (
+    <View style={{ width: 300 }}>
+      <Combobox label="City" placeholder="Choose a city" options={CITIES} value={city} onValueChange={(v) => setCity(String(v))} />
+    </View>
+  );
+}

package/registry/examples/dialog/native/sheet.d.ts

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

package/registry/examples/dialog/native/sheet.js

@@ -0,0 +1,21 @@
+"use client";
+
+// registry/examples/dialog/native/sheet.tsx
+import { Button, Sheet, Txt } from "@krizaka/ui/native";
+import * as React from "react";
+import { View } from "react-native";
+import { jsx, jsxs } from "react/jsx-runtime";
+function NativeDialogSheet({ defaultOpen }) {
+  const [open, setOpen] = React.useState(Boolean(defaultOpen));
+  return /* @__PURE__ */ jsxs(View, { children: [
+    /* @__PURE__ */ jsx(Button, { label: "Show the pick-up point", onPress: () => setOpen(true) }),
+    /* @__PURE__ */ jsxs(Sheet, { open, onOpenChange: setOpen, title: "Caf\xE9 Olimpico", children: [
+      /* @__PURE__ */ jsx(Txt, { tone: "secondary", children: "124 Rue Saint-Viateur O, Montr\xE9al \xB7 350 m away" }),
+      /* @__PURE__ */ jsx(Txt, { children: "Open until 10 pm. Ask for the order under your name at the counter." }),
+      /* @__PURE__ */ jsx(Button, { label: "Get directions", variant: "primary", onPress: () => setOpen(false) })
+    ] })
+  ] });
+}
+export {
+  NativeDialogSheet as default
+};