@ratio-ui/core 0.2.0 → 0.3.0

package/dist/catalogue.json

@@ -1,6 +1,146 @@
 {
-  "version": "0.2.0",
+  "version": "0.3.0",
   "components": [
+    {
+      "name": "Alert",
+      "import": "import { Alert } from '@ratio-ui/core'",
+      "description": "A message that stays in the page: a tone glyph, an optional title and description, and an optional action.",
+      "props": [
+        {
+          "name": "tone",
+          "type": "\"critical\" | \"info\" | \"success\" | \"warning\"",
+          "required": false,
+          "default": "info",
+          "description": "The tone. Defaults to info."
+        },
+        {
+          "name": "title",
+          "type": "ReactNode",
+          "required": false,
+          "description": "An optional bold first line."
+        },
+        {
+          "name": "description",
+          "type": "ReactNode",
+          "required": false,
+          "description": "An optional second line."
+        },
+        {
+          "name": "action",
+          "type": "ReactNode",
+          "required": false,
+          "description": "An optional action on the right, usually one Button."
+        },
+        {
+          "name": "ref",
+          "type": "Ref<HTMLDivElement>",
+          "required": false,
+          "description": "Receives the rendered div."
+        }
+      ],
+      "usage": {
+        "whenToUse": "- A message that sits in the page and stays until the cause is gone: a banner above a form, a notice in a card\n- Four tones: info, success, warning, critical (question 1 tokens: no fill, strong border, warning glyph)",
+        "whenNotToUse": "- A message that disappears by itself: use Toaster\n- A confirmation before a destructive step: use AlertDialog\n- A field error: say it in one clause under the field",
+        "example": "```tsx\n<Alert\n  tone=\"critical\"\n  title=\"Payment failed\"\n  description=\"Try another method.\"\n  action={<Button>Retry</Button>}\n/>\n```\n\nInfo and success have role status (polite); warning and critical have role alert (assertive)."
+      }
+    },
+    {
+      "name": "AlertDialog",
+      "import": "import { AlertDialog } from '@ratio-ui/core'",
+      "description": "The root of a confirmation. It holds the open state and renders nothing itself. Pass `open` and `onOpenChange` to control it, or `defaultOpen` to leave it uncontrolled. Escape closes it; a click outside does not.",
+      "props": [],
+      "usage": {
+        "whenToUse": "- A confirm step before deleting something, or before a money action such as a refund\n- An answer that must be given: Escape closes it, a click outside does not\n- A short question that fits in 480px: the panel is fixed at that width, with a ring outline and no scrim",
+        "whenNotToUse": "- A form or any input: use Dialog\n- A message after an action: use toast()\n- A reversible action: do it and offer undo instead",
+        "example": "```tsx\n<AlertDialog>\n  <AlertDialogTrigger>Delete product</AlertDialogTrigger>\n  <AlertDialogContent>\n    <AlertDialogHeader>\n      <AlertDialogTitle>Delete this product?</AlertDialogTitle>\n      <AlertDialogDescription>It leaves the storefront at once.</AlertDialogDescription>\n    </AlertDialogHeader>\n    <AlertDialogFooter>\n      <AlertDialogCancel>Cancel</AlertDialogCancel>\n      <AlertDialogAction>Delete</AlertDialogAction>\n    </AlertDialogFooter>\n  </AlertDialogContent>\n</AlertDialog>\n```\n\n- `AlertDialogAction` is the Button's destructive variant and closes the dialog after `onClick` runs. Pass `variant=\"main\"` for a non-destructive confirmation such as a refund. For an async action that must stay open until it finishes, control the dialog with `open` and `onOpenChange`.\n- `AlertDialogCancel` is the secondary Button and closes the dialog.\n- Name the action with the verb (\"Delete\", \"Refund\"), never \"OK\". Put the amount in the title for money actions, formatted with the format helpers."
+      },
+      "parts": [
+        {
+          "name": "AlertDialogAction",
+          "import": "import { AlertDialogAction } from '@ratio-ui/core'",
+          "description": "The confirming button. It is the Button's destructive variant and closes the dialog after its onClick runs.",
+          "props": [
+            {
+              "name": "variant",
+              "type": "\"destructive\" | \"main\"",
+              "required": false,
+              "default": "destructive",
+              "description": "The Button look. Defaults to destructive; use main for a confirmation that deletes nothing."
+            }
+          ]
+        },
+        {
+          "name": "AlertDialogCancel",
+          "import": "import { AlertDialogCancel } from '@ratio-ui/core'",
+          "description": "The secondary button that closes the dialog without doing anything.",
+          "props": []
+        },
+        {
+          "name": "AlertDialogContent",
+          "import": "import { AlertDialogContent } from '@ratio-ui/core'",
+          "description": "The panel: 480px wide, white, drawn with the ring outline and no shadow, with no scrim behind it. Put AlertDialogHeader and AlertDialogFooter inside.",
+          "props": [
+            {
+              "name": "render",
+              "type": "ReactElement<unknown, string | JSXElementConstructor<any>> | ComponentRenderFn<HTMLProps, DialogPopupState>",
+              "required": false,
+              "description": "Allows you to replace the component's HTML element with a different tag, or compose it with another component.\n\nAccepts a `ReactElement` or a function that returns the element to render."
+            }
+          ]
+        },
+        {
+          "name": "AlertDialogDescription",
+          "import": "import { AlertDialogDescription } from '@ratio-ui/core'",
+          "description": "What will happen, in subdued body text.",
+          "props": [
+            {
+              "name": "render",
+              "type": "ReactElement<unknown, string | JSXElementConstructor<any>> | ComponentRenderFn<HTMLProps, DialogDescriptionState>",
+              "required": false,
+              "description": "Allows you to replace the component's HTML element with a different tag, or compose it with another component.\n\nAccepts a `ReactElement` or a function that returns the element to render."
+            }
+          ]
+        },
+        {
+          "name": "AlertDialogFooter",
+          "import": "import { AlertDialogFooter } from '@ratio-ui/core'",
+          "description": "The row of actions at the bottom, aligned to the end.",
+          "props": []
+        },
+        {
+          "name": "AlertDialogHeader",
+          "import": "import { AlertDialogHeader } from '@ratio-ui/core'",
+          "description": "The title and description, stacked.",
+          "props": []
+        },
+        {
+          "name": "AlertDialogTitle",
+          "import": "import { AlertDialogTitle } from '@ratio-ui/core'",
+          "description": "The question, in the b4 style. It names the dialog for assistive technology.",
+          "props": [
+            {
+              "name": "render",
+              "type": "ReactElement<unknown, string | JSXElementConstructor<any>> | ComponentRenderFn<HTMLProps, DialogTitleState>",
+              "required": false,
+              "description": "Allows you to replace the component's HTML element with a different tag, or compose it with another component.\n\nAccepts a `ReactElement` or a function that returns the element to render."
+            }
+          ]
+        },
+        {
+          "name": "AlertDialogTrigger",
+          "import": "import { AlertDialogTrigger } from '@ratio-ui/core'",
+          "description": "The button that opens the confirmation.",
+          "props": [
+            {
+              "name": "render",
+              "type": "ReactElement<unknown, string | JSXElementConstructor<any>> | ComponentRenderFn<HTMLProps, DialogTriggerState>",
+              "required": false,
+              "description": "Allows you to replace the component's HTML element with a different tag, or compose it with another component.\n\nAccepts a `ReactElement` or a function that returns the element to render."
+            }
+          ]
+        }
+      ]
+    },
     {
       "name": "AppShell",
       "import": "import { AppShell } from '@ratio-ui/core'",
@@ -138,6 +278,17 @@
         "example": "<Stack gap={8}>\n  <Button><Icon name=\"plus\" />Add customer</Button>\n  <Button variant=\"secondary\">Export</Button>\n  <Button iconOnly variant=\"ghost\" aria-label=\"Add\"><Icon name=\"plus\" /></Button>\n</Stack>"
       }
     },
+    {
+      "name": "Calendar",
+      "import": "import { Calendar } from '@ratio-ui/core'",
+      "description": "A month grid to pick a day or a range of days, drawn by the design system: 28px days with a 6px radius, today in the accent ink, the selected day filled with the accent, a range as accent ends on a tinted band, disabled days at 50% and the days of the months around it in the muted ink. Every day is named in the format module's date order (28/10/2026). Arrow keys move between days and the previous and next buttons between months. It has no fill of its own, so it sits in a popover or a container as drawn.",
+      "props": [],
+      "usage": {
+        "whenToUse": "- Picking one day, such as a \"Best before\" date, inside a popover or a form: `mode=\"single\"`\n- Picking a range of days, such as an analytics period: `mode=\"range\"`, with `numberOfMonths={2}` for a wide range\n- Limiting the days that can be picked: `disabled` (for example `{ before: today }`), `startMonth` and `endMonth`",
+        "whenNotToUse": "- A date field people type into: use DatePicker or DateRangePicker, which open this calendar in a popover\n- Showing a date as text: write it with the format module, never with a calendar\n- Styling: Calendar takes no `className`, `classNames`, `style`, `components` or `formatters`; dates are written in the format module's order (28/10/2026)",
+        "example": "const [day, setDay] = useState<Date | undefined>()\n\n<Calendar mode=\"single\" selected={day} onSelect={setDay} disabled={{ before: new Date() }} />"
+      }
+    },
     {
       "name": "Card",
       "import": "import { Card } from '@ratio-ui/core'",
@@ -200,6 +351,129 @@
         "example": "<Checkbox aria-label=\"Select row\" checked={selected} onCheckedChange={setSelected} />"
       }
     },
+    {
+      "name": "CheckboxList",
+      "import": "import { CheckboxList } from '@ratio-ui/core'",
+      "description": "A titled list of checkboxes with the count of chosen items in the heading (\"4 of 6\"), an optional description under each label and an optional select-all.",
+      "props": [
+        {
+          "name": "title",
+          "type": "string",
+          "required": true,
+          "description": "The heading. The count of chosen items sits beside it."
+        },
+        {
+          "name": "items",
+          "type": "CheckboxListItem[]",
+          "required": true,
+          "description": "The options."
+        },
+        {
+          "name": "value",
+          "type": "string[]",
+          "required": false,
+          "description": "The chosen values, when controlled."
+        },
+        {
+          "name": "defaultValue",
+          "type": "string[]",
+          "required": false,
+          "description": "The chosen values to start with, when not controlled."
+        },
+        {
+          "name": "onValueChange",
+          "type": "((value: string[]) => void)",
+          "required": false,
+          "description": "Called with the new list of chosen values."
+        },
+        {
+          "name": "selectAll",
+          "type": "boolean",
+          "required": false,
+          "description": "Adds a \"Select all\" box that is mixed while only some are chosen."
+        },
+        {
+          "name": "selectAllLabel",
+          "type": "string",
+          "required": false,
+          "default": "Select all",
+          "description": "The label of the select-all box. Defaults to \"Select all\"."
+        },
+        {
+          "name": "countLabel",
+          "type": "((chosen: string, total: string) => string)",
+          "required": false,
+          "default": "(c, t) => `${c} of ${t}`",
+          "description": "Writes the count in the heading from the chosen and total counts, already formatted. Defaults to \"4 of 6\"."
+        }
+      ],
+      "usage": {
+        "whenToUse": "- A titled list where several options can be on and the heading should say how many (\"Sales channels  4 of 6\")\n- Add `selectAll` for a long list; it shows a mixed box while only some are on",
+        "whenNotToUse": "- One choice among several: use radio buttons or FilterTabs\n- A single yes or no: use Checkbox\n- Styling: CheckboxList takes no `className` and no `style`",
+        "example": "<CheckboxList title=\"Sales channels\" items={channels} value={on} onValueChange={setOn} selectAll />"
+      }
+    },
+    {
+      "name": "Collapsible",
+      "import": "import { Collapsible } from '@ratio-ui/core'",
+      "description": "A section that opens and closes on its heading and, while closed, still shows its values as chips. The panel appears and disappears with no height animation.",
+      "props": [
+        {
+          "name": "title",
+          "type": "string",
+          "required": true,
+          "description": "The section heading, shown on the trigger."
+        },
+        {
+          "name": "summary",
+          "type": "readonly SummaryChip[]",
+          "required": false,
+          "description": "The values to show as chips while the section is closed."
+        },
+        {
+          "name": "open",
+          "type": "boolean",
+          "required": false,
+          "description": "Whether the section is open, when controlled."
+        },
+        {
+          "name": "defaultOpen",
+          "type": "boolean",
+          "required": false,
+          "default": "false",
+          "description": "Whether the section starts open, when uncontrolled. Defaults to closed."
+        },
+        {
+          "name": "onOpenChange",
+          "type": "((open: boolean) => void)",
+          "required": false,
+          "description": "Called when the section opens or closes."
+        },
+        {
+          "name": "disabled",
+          "type": "boolean",
+          "required": false,
+          "description": "Stops the section from opening or closing."
+        },
+        {
+          "name": "children",
+          "type": "ReactNode",
+          "required": true,
+          "description": "The section's content, shown when open."
+        },
+        {
+          "name": "ref",
+          "type": "Ref<HTMLDivElement>",
+          "required": false,
+          "description": "Receives the rendered root."
+        }
+      ],
+      "usage": {
+        "whenToUse": "- A form section that is rarely edited and can stay closed, such as the pricing details under the price\n- A closed section that must still show its values: pass `summary` and the chips show while it is closed",
+        "whenNotToUse": "- Content the person must see to finish the task: leave it open\n- Switching between peer views: use Tabs",
+        "example": "```tsx\n<Collapsible title=\"More pricing\" summary={[{ label: 'Cost price', value: '₹450.00' }, { label: 'HSN code', value: '6109' }]}>\n  ...fields...\n</Collapsible>\n```\n\nThe panel appears and disappears at once; the library has no height animation."
+      }
+    },
     {
       "name": "DataTable",
       "import": "import { DataTable } from '@ratio-ui/core'",
@@ -303,6 +577,130 @@
         "example": "<DataTable\n  aria-label=\"Products\"\n  columns={[\n    { id: 'name', header: 'Product', cell: (p) => p.name, essential: true, sortable: true, truncate: true },\n    { id: 'stock', header: 'Stock', cell: (p) => p.stock, numeric: true },\n  ]}\n  data={products}\n  getRowId={(p) => p.id}\n  rowHref={(p) => `/products/${p.id}`}\n  sort={sort}\n  onSortChange={setSort}\n  page={page}\n  pageSize={20}\n  total={84}\n  onPageChange={setPage}\n  empty=\"No products match this filter\"\n/>"
       }
     },
+    {
+      "name": "DatePicker",
+      "import": "import { DatePicker } from '@ratio-ui/core'",
+      "description": "A field that shows a day as DD/MM/YYYY, reads a typed date through the format module and opens a calendar in a popover from the button at its end. Text that is not a date is marked invalid when the field loses focus, and reports nothing. Under a name, a form submits the day as YYYY-MM-DD (empty when there is none), never the text on screen.",
+      "props": [
+        {
+          "name": "value",
+          "type": "Date | null",
+          "required": false,
+          "description": "The day, or null for an empty field. Pass it to control the field."
+        },
+        {
+          "name": "defaultValue",
+          "type": "Date | null",
+          "required": false,
+          "default": "null",
+          "description": "The starting day when the field is not controlled. Defaults to empty."
+        },
+        {
+          "name": "onValueChange",
+          "type": "((value: Date | null) => void)",
+          "required": false,
+          "description": "Called with the day when a typed date is complete or a day is picked, and with null when the text is cleared."
+        },
+        {
+          "name": "disabledDays",
+          "type": "Matcher | Matcher[]",
+          "required": false,
+          "description": "The days that cannot be picked in the calendar, for example { before: new Date() }."
+        },
+        {
+          "name": "startMonth",
+          "type": "Date",
+          "required": false,
+          "description": "The first month the calendar can show."
+        },
+        {
+          "name": "endMonth",
+          "type": "Date",
+          "required": false,
+          "description": "The last month the calendar can show."
+        },
+        {
+          "name": "size",
+          "type": "32 | 36",
+          "required": false,
+          "default": "36",
+          "description": "The height in px: 36 for forms, 32 for fields inside a table. Defaults to 36."
+        },
+        {
+          "name": "ref",
+          "type": "Ref<HTMLInputElement>",
+          "required": false,
+          "description": "Receives the input element."
+        }
+      ],
+      "usage": {
+        "whenToUse": "- One day a person types or picks, such as a \"Best before\" custom field: `value` and `onValueChange` take a `Date` (or null when empty)\n- A date inside a table: `size` 32\n- Limiting the days: `disabledDays` (for example `{ before: new Date() }`), `startMonth` and `endMonth`, which limit the calendar (a typed date is not checked against them)",
+        "whenNotToUse": "- A period of days, such as an analytics range: use DateRangePicker\n- A calendar shown on the page, not behind a field: use Calendar\n- Showing a date as text: write it with the format module (`formatDate`)\n- Custom classes or inline styles: DatePicker takes neither `className` nor `style`",
+        "example": "```tsx\nconst [bestBefore, setBestBefore] = useState<Date | null>(null)\n\n<DatePicker aria-label=\"Best before\" value={bestBefore} onValueChange={setBestBefore} />\n<DatePicker aria-label=\"Expiry\" size={32} aria-invalid aria-describedby=\"expiry-error\" />\n```\n\nThe field shows DD/MM/YYYY and reads typed dates through the format module (\"3/1/2026\" is 3 January). Text that is not a date turns the field invalid when it loses focus and is never reported.\n\nUnder a `name`, a form submits the committed day as `YYYY-MM-DD` (an empty string when the field is empty), not the text on screen: `<DatePicker name=\"bestBefore\" />` posts `bestBefore=2026-10-28`. A disabled field posts nothing."
+      }
+    },
+    {
+      "name": "DateRangePicker",
+      "import": "import { DateRangePicker } from '@ratio-ui/core'",
+      "description": "A field that shows a range as two DD/MM/YYYY days, reads a typed range through the format module and opens a calendar in a popover from the button at its end, for analytics periods. Pick the first day, then the last. Text that is not a range in order is marked invalid when the field loses focus, and reports nothing. Under a name, a form submits two fields, `name.from` and `name.to`, each as YYYY-MM-DD (empty when there is no range), never the text on screen.",
+      "props": [
+        {
+          "name": "value",
+          "type": "DateRangeValue | null",
+          "required": false,
+          "description": "The range, or null for an empty field. Pass it to control the field."
+        },
+        {
+          "name": "defaultValue",
+          "type": "DateRangeValue | null",
+          "required": false,
+          "default": "null",
+          "description": "The starting range when the field is not controlled. Defaults to empty."
+        },
+        {
+          "name": "onValueChange",
+          "type": "((value: DateRangeValue | null) => void)",
+          "required": false,
+          "description": "Called with the range when a typed range is complete or two days are picked, and with null when the text is cleared."
+        },
+        {
+          "name": "disabledDays",
+          "type": "Matcher | Matcher[]",
+          "required": false,
+          "description": "The days that cannot be picked in the calendar, for example { after: new Date() } for an analytics period."
+        },
+        {
+          "name": "startMonth",
+          "type": "Date",
+          "required": false,
+          "description": "The first month the calendar can show."
+        },
+        {
+          "name": "endMonth",
+          "type": "Date",
+          "required": false,
+          "description": "The last month the calendar can show."
+        },
+        {
+          "name": "size",
+          "type": "32 | 36",
+          "required": false,
+          "default": "36",
+          "description": "The height in px: 36 for forms, 32 for fields inside a table. Defaults to 36."
+        },
+        {
+          "name": "ref",
+          "type": "Ref<HTMLInputElement>",
+          "required": false,
+          "description": "Receives the input element."
+        }
+      ],
+      "usage": {
+        "whenToUse": "- A period of days a person types or picks, such as an analytics range: `value` and `onValueChange` take `{ from, to }` (or null when empty)\n- Limiting the days: `disabledDays` (for example `{ after: new Date() }` for reports), `startMonth` and `endMonth`, which limit the calendar (a typed range is not checked against them)\n- A range inside a table: `size` 32",
+        "whenNotToUse": "- One day: use DatePicker\n- A calendar shown on the page, not behind a field: use Calendar\n- Showing a range as text: write both days with the format module (`formatDate`)\n- Custom classes or inline styles: DateRangePicker takes neither `className` nor `style`",
+        "example": "```tsx\nconst [period, setPeriod] = useState<DateRangeValue | null>(null)\n\n<DateRangePicker aria-label=\"Period\" value={period} onValueChange={setPeriod} disabledDays={{ after: new Date() }} />\n```\n\nThe field shows `28/10/2026 – 03/11/2026`. Pick the first day, then the last (an earlier second day swaps them). A typed range with the end before the start, or one day only, turns the field invalid when it loses focus and is never reported.\n\nUnder a `name`, a form submits two fields, `name.from` and `name.to`, each the committed day as `YYYY-MM-DD` (empty strings when the field is empty), not the text on screen: `<DateRangePicker name=\"period\" />` posts `period.from=2026-10-28` and `period.to=2026-11-03`. A disabled field posts nothing."
+      }
+    },
     {
       "name": "Definition",
       "import": "import { Definition } from '@ratio-ui/core'",
@@ -698,6 +1096,75 @@
         "example": "<EmptyState title=\"No products match this filter\" action={<Button>Clear filter</Button>} />"
       }
     },
+    {
+      "name": "Field",
+      "import": "import { Field } from '@ratio-ui/core'",
+      "description": "A form row: label, control, hint and error. It wires the label to the control by id, links the hint and error with aria-describedby, and sets aria-invalid when there is an error. The control keeps an id it already has.",
+      "props": [
+        {
+          "name": "label",
+          "type": "ReactNode",
+          "required": true,
+          "description": "The label text."
+        },
+        {
+          "name": "hint",
+          "type": "ReactNode",
+          "required": false,
+          "description": "Help text under the control. An error replaces it."
+        },
+        {
+          "name": "error",
+          "type": "ReactNode",
+          "required": false,
+          "description": "The error message. It shows under the control beside the alert glyph and marks the control invalid."
+        },
+        {
+          "name": "info",
+          "type": "ReactNode",
+          "required": false,
+          "description": "An explanation of the field, opened from a small info icon beside the label by keyboard, touch or hover."
+        },
+        {
+          "name": "required",
+          "type": "boolean",
+          "required": false,
+          "description": "Shows a star after the label and marks the control aria-required."
+        },
+        {
+          "name": "disabled",
+          "type": "boolean",
+          "required": false,
+          "description": "Dims the label and disables the control."
+        },
+        {
+          "name": "children",
+          "type": "ReactElement<Record<string, unknown>, string | JSXElementConstructor<any>> | ((props: FieldControlProps) => ReactNode)",
+          "required": true,
+          "description": "The control: one element, such as Input, which gets an id, aria-describedby, aria-invalid, aria-required and disabled. When the control sits inside a wrapper such as InputGroup, pass a function instead and spread the props it receives onto the input itself."
+        }
+      ],
+      "usage": {
+        "whenToUse": "- Every form row: a label, one control, and optional hint, error, info tooltip and required mark\n- Wiring: Field sets the control's id, aria-describedby, aria-invalid, aria-required and disabled, so you do not",
+        "whenNotToUse": "- A heading for a group of controls: use a fieldset with a legend\n- A label with no control beside it: use Label alone, with `htmlFor`\n- Long help that must be read to finish the task: put it on the screen as the hint",
+        "example": "```tsx\n<Field label=\"Title\" hint=\"Shown in search results\" error={errors.title} required>\n  <Input />\n</Field>\n<Field label=\"MRP\" info=\"Maximum retail price, with tax\">\n  <Input inputMode=\"decimal\" />\n</Field>\n```\n\nFor an input inside an InputGroup, pass a function child and spread its props onto the input: `<Field label=\"MRP\">{(props) => <InputGroup>…<InputGroupInput {...props} /></InputGroup>}</Field>`.\n\nFor a Select, which renders no element of its own, spread the props onto its trigger: `<Field label=\"GST rate\">{(props) => <Select items={rates}><SelectTrigger {...props}><SelectValue /></SelectTrigger><SelectContent>…</SelectContent></Select>}</Field>`.\n\nThe error shows beside the alert glyph in the error ink (question 1) and replaces the hint. Label is the same label as a separate part."
+      },
+      "parts": [
+        {
+          "name": "Label",
+          "import": "import { Label } from '@ratio-ui/core'",
+          "description": "The text that names a control, in the 12px medium label type. Point htmlFor at the control's id; Field does this for you.",
+          "props": [
+            {
+              "name": "ref",
+              "type": "Ref<HTMLLabelElement>",
+              "required": false,
+              "description": "Receives the label element."
+            }
+          ]
+        }
+      ]
+    },
     {
       "name": "FilterTabs",
       "import": "import { FilterTabs } from '@ratio-ui/core'",
@@ -816,7 +1283,7 @@
       "props": [
         {
           "name": "name",
-          "type": "\"alert-triangle\" | \"check\" | \"chevron-left\" | \"chevron-right\" | \"export\" | \"import\" | \"info-circle\" | \"menu\" | \"more\" | \"nav-analytics\" | \"nav-apps\" | \"nav-caret-down\" | \"nav-chevron\" | \"nav-content\" | \"nav-customers\" | \"nav-discounts\" | \"nav-growth\" | \"nav-home\" | \"nav-markets\" | \"nav-orders\" | \"nav-product\" | \"nav-product-2\" | \"nav-sales-channels\" | \"nav-settings\" | \"nav-shortcut\" | \"plus\" | \"search\" | \"x\"",
+          "type": "\"alert-triangle\" | \"calendar\" | \"check\" | \"chevron-left\" | \"chevron-right\" | \"export\" | \"import\" | \"info-circle\" | \"menu\" | \"more\" | \"nav-analytics\" | \"nav-apps\" | \"nav-caret-down\" | \"nav-chevron\" | \"nav-content\" | \"nav-customers\" | \"nav-discounts\" | \"nav-growth\" | \"nav-home\" | \"nav-markets\" | \"nav-orders\" | \"nav-product\" | \"nav-product-2\" | \"nav-sales-channels\" | \"nav-settings\" | \"nav-shortcut\" | \"plus\" | \"search\" | \"x\"",
           "required": true,
           "description": "Which icon to draw, by name."
         },
@@ -842,7 +1309,7 @@
         }
       ],
       "usage": {
-        "whenToUse": "- A glyph beside a label inside a control: the plus on a main button, the magnifier in a search field, the export tray on a secondary button. Use size 12\n- The side navigation: the nav glyphs at size 16 (nav-home and nav-product are the design system's own; nav-orders, nav-customers, nav-growth, nav-discounts, nav-content, nav-markets, nav-analytics, nav-sales-channels, nav-apps and nav-settings are Tabler stand-ins for the dashboard's sections, question 7), and the disclosure caret (nav-chevron or nav-caret-down, one glyph under two names) at size 8\n- Pagination: chevron-left and chevron-right at size 8\n- A mark that Tabler supplies: check, x, alert-triangle, info-circle, import, more (three dots) and menu (the phone menu button). They are drawn with a 1.5px line at every size, so they sit beside the design system's own glyphs without looking heavier\n- Meaning that lives only in the icon: pass label. The icon is then an image that assistive technology announces under that name. Without a label it is decoration and is hidden from assistive technology\n- Colour: tone current, the default, takes the colour of the text around the icon. icon is the design system's icon ink, subdued is its subdued text ink and primary is the accent\n- Chevron geometry (design question 9): the design system has no vector for its pagination chevrons, only a 1.5px CSS caret in an 8px box, so chevron-left and chevron-right stand in. Each is the outline of a line 1.5 units wide with round ends, two legs at 45 degrees, each 2.5 units across and 2.5 down, through (2.75, 1.5), (5.25, 4) and (2.75, 6.5) in an 8 unit box. They scale like every filled glyph, so draw them at size 8, and expect them to be replaced when the designer sends real vectors",
+        "whenToUse": "- A glyph beside a label inside a control: the plus on a main button, the magnifier in a search field, the export tray on a secondary button. Use size 12\n- The side navigation: the nav glyphs at size 16 (nav-home and nav-product are the design system's own; nav-orders, nav-customers, nav-growth, nav-discounts, nav-content, nav-markets, nav-analytics, nav-sales-channels, nav-apps and nav-settings are Tabler stand-ins for the dashboard's sections, question 7), and the disclosure caret (nav-chevron or nav-caret-down, one glyph under two names) at size 8\n- The date pickers' open button: calendar (Tabler) at size 12\n- Pagination: chevron-left and chevron-right at size 8\n- A mark that Tabler supplies: check, x, alert-triangle, info-circle, import, more (three dots) and menu (the phone menu button). They are drawn with a 1.5px line at every size, so they sit beside the design system's own glyphs without looking heavier\n- Meaning that lives only in the icon: pass label. The icon is then an image that assistive technology announces under that name. Without a label it is decoration and is hidden from assistive technology\n- Colour: tone current, the default, takes the colour of the text around the icon. icon is the design system's icon ink, subdued is its subdued text ink and primary is the accent\n- Chevron geometry (design question 9): the design system has no vector for its pagination chevrons, only a 1.5px CSS caret in an 8px box, so chevron-left and chevron-right stand in. Each is the outline of a line 1.5 units wide with round ends, two legs at 45 degrees, each 2.5 units across and 2.5 down, through (2.75, 1.5), (5.25, 4) and (2.75, 6.5) in an 8 unit box. They scale like every filled glyph, so draw them at size 8, and expect them to be replaced when the designer sends real vectors",
         "whenNotToUse": "- Decoration that adds no meaning. An icon next to text that already says the same thing is hidden from assistive technology, so leave the label off, and leave the icon out when it adds nothing\n- An icon the registry does not have. Components accept no className or style, and icons come from the registry only, so a new one is a registry entry: the design system's glyph first, Tabler for the rest\n- An icon-only control without a name. Pass label, or give the control its own accessible name\n- A size other than 8, 12 or 16, or a colour other than the four tones. There is no red, no destructive colour and no third accent: an error is marked with the alert-triangle glyph beside its message, not with a colour\n- Emoji, or unicode arrows and symbols, as icons. Inter's web subsets do not hold them and the design system bans them",
         "example": "import { Icon } from '@ratio-ui/core'\n\n// Beside text that names it: decoration, hidden from assistive technology\n<button type=\"button\">\n  <Icon name=\"plus\" />\n  Add product\n</button>\n\n// Alone: the label is the accessible name\n<Icon name=\"search\" tone=\"icon\" label=\"Search\" />\n\n// Pagination chevrons are drawn for an 8px box\n<Icon name=\"chevron-right\" size={8} />"
       }
@@ -1016,6 +1483,50 @@
         }
       ]
     },
+    {
+      "name": "Link",
+      "import": "import { Link } from '@ratio-ui/core'",
+      "description": "A text link to another page, such as \"← Products\" or \"View all variants →\". It is drawn by the app's LinkProvider, so a router navigates without a reload; without one it is a plain <a href>. The arrows are decoration and are hidden from screen readers.",
+      "props": [
+        {
+          "name": "href",
+          "type": "string",
+          "required": true,
+          "description": "Where the link goes."
+        },
+        {
+          "name": "children",
+          "type": "ReactNode",
+          "required": true,
+          "description": "The link text."
+        },
+        {
+          "name": "back",
+          "type": "boolean",
+          "required": false,
+          "default": "false",
+          "description": "Shows a back arrow before the text, as in \"← Products\". Screen readers skip it."
+        },
+        {
+          "name": "forward",
+          "type": "boolean",
+          "required": false,
+          "default": "false",
+          "description": "Shows a forward arrow after the text, as in \"View all variants →\". Screen readers skip it."
+        },
+        {
+          "name": "ref",
+          "type": "Ref<HTMLAnchorElement>",
+          "required": false,
+          "description": "Receives the anchor element."
+        }
+      ],
+      "usage": {
+        "whenToUse": "- A text link to another page: \"← Products\", \"View all variants →\"\n- A back link in a detail page's body (the page header has its own back link)",
+        "whenNotToUse": "- An action that changes something: use Button\n- A whole table row: use DataTable's `rowHref`\n- A navigation row in the side navigation: use SideNav",
+        "example": "<Link href=\"/products\" back>Products</Link>\n<Link href=\"/products/blue-shirt/variants\" forward>View all variants</Link>"
+      }
+    },
     {
       "name": "LinkProvider",
       "import": "import { LinkProvider } from '@ratio-ui/core'",
@@ -1040,6 +1551,93 @@
         "example": "import { Link as RouterLink } from 'react-router-dom'\n\n<LinkProvider render={({ href, ...props }) => <RouterLink to={href} {...props} />}>\n  <App />\n</LinkProvider>"
       }
     },
+    {
+      "name": "MediaGrid",
+      "import": "import { MediaGrid } from '@ratio-ui/core'",
+      "description": "The media of a product: a row of square thumbs with an add tile that opens the file picker and takes dropped files. Thumbs reorder by drag (pointer, touch or keyboard) and by the Move left, Move right and Make cover buttons, so no drag is needed. The first image is the cover and carries a badge. Uploads show a thin progress bar and failures an error under the thumb. Every move, cover change and removal is announced to screen readers.",
+      "props": [
+        {
+          "name": "items",
+          "type": "MediaGridItem[]",
+          "required": true,
+          "description": "The images in order. The first one is the cover."
+        },
+        {
+          "name": "onAdd",
+          "type": "(files: File[]) => void",
+          "required": true,
+          "description": "Called with the files chosen in the add tile or dropped on the grid."
+        },
+        {
+          "name": "onReorder",
+          "type": "(ids: string[]) => void",
+          "required": true,
+          "description": "Called with every id in the new order after a drag, Move left, Move right or Make cover."
+        },
+        {
+          "name": "onRemove",
+          "type": "(id: string) => void",
+          "required": true,
+          "description": "Called with the id of the item to take off the grid."
+        },
+        {
+          "name": "onMakeCover",
+          "type": "((id: string) => void)",
+          "required": false,
+          "description": "Called with the id after Make cover has moved it first through onReorder, for an app that saves the cover on its own."
+        },
+        {
+          "name": "accept",
+          "type": "Accept",
+          "required": false,
+          "default": "{ 'image/*': [] }",
+          "description": "The file types the add tile takes, as react-dropzone's accept map. Defaults to every image type."
+        },
+        {
+          "name": "disabled",
+          "type": "boolean",
+          "required": false,
+          "default": "false",
+          "description": "Stops adding, dragging and every button."
+        },
+        {
+          "name": "addLabel",
+          "type": "string",
+          "required": false,
+          "default": "Add media",
+          "description": "The accessible name of the add tile. Defaults to \"Add media\"."
+        },
+        {
+          "name": "id",
+          "type": "string",
+          "required": false,
+          "description": "The id of the grid."
+        },
+        {
+          "name": "aria-label",
+          "type": "string",
+          "required": false,
+          "description": "The accessible name of the grid. Defaults to \"Media\" when there is no aria-labelledby."
+        },
+        {
+          "name": "aria-labelledby",
+          "type": "string",
+          "required": false,
+          "description": "The id of the visible label that names the grid, such as a Field label."
+        },
+        {
+          "name": "aria-describedby",
+          "type": "string",
+          "required": false,
+          "description": "The id of help text for the grid."
+        }
+      ],
+      "usage": {
+        "whenToUse": "- The images of a product or any ordered set of images, with an add tile that opens the file picker and takes dropped files\n- The app uploads: MediaGrid reports `onAdd(files)`, `onReorder(ids)`, `onRemove(id)` and `onMakeCover(id)`, and shows each item's `progress` (0 to 100) and `error`\n- The first image is the cover; Make cover moves an image first through `onReorder`, then calls `onMakeCover`\n- Images reorder by drag (pointer, touch or keyboard) and by the Move left and Move right buttons, so no drag is needed",
+        "whenNotToUse": "- A single image such as a logo or an avatar: use Avatar or a single file input\n- Files that are not images in a visual order (documents, CSV imports): use a list\n- Remove has no confirm step, because the save bar's Discard brings an image back; confirm in `onRemove` with AlertDialog when the removal is final\n- Styling: MediaGrid takes no `className` and no `style`",
+        "example": "<MediaGrid\n  items={media}\n  onAdd={(files) => upload(files)}\n  onReorder={(ids) => setMedia(ids.map((id) => media.find((m) => m.id === id)!))}\n  onRemove={(id) => setMedia(media.filter((m) => m.id !== id))}\n/>"
+      }
+    },
     {
       "name": "MetricStrip",
       "import": "import { MetricStrip } from '@ratio-ui/core'",
@@ -1064,6 +1662,62 @@
         "example": "<MetricStrip\n  label=\"Product metrics\"\n  segments={[\n    {\n      id: 'rate',\n      title: 'Average sell-through rate',\n      definition: 'Share of stock sold',\n      value: '9.95%',\n    },\n    { id: 'days', title: 'Days of inventory remaining', value: null },\n    { id: 'abc', title: 'ABC product analysis', value: 0, format: 'money' },\n  ]}\n/>"
       }
     },
+    {
+      "name": "MoneyInput",
+      "import": "import { MoneyInput } from '@ratio-ui/core'",
+      "description": "A money field: the currency symbol before the amount, inside one ring. It takes and gives integer paise, shows the amount grouped as India groups it with two decimals (1,23,456.50) once the field loses focus, and reads a pasted amount written with the currency symbol or with either grouping. Under a name, a form submits paise.",
+      "props": [
+        {
+          "name": "value",
+          "type": "number | null",
+          "required": false,
+          "description": "The amount in integer paise (12345650 is 1,23,456 rupees and 50 paise), or null for an empty field. Pass it to control the field."
+        },
+        {
+          "name": "defaultValue",
+          "type": "number | null",
+          "required": false,
+          "default": "null",
+          "description": "The starting amount in integer paise when the field is not controlled. Defaults to empty."
+        },
+        {
+          "name": "onValueChange",
+          "type": "((paise: number | null) => void)",
+          "required": false,
+          "description": "Called with the amount in integer paise as it is typed, pasted or cleared (null when empty)."
+        },
+        {
+          "name": "min",
+          "type": "number",
+          "required": false,
+          "description": "The smallest amount in integer paise; the field moves a smaller one up to it on blur. Leave it out to allow negatives."
+        },
+        {
+          "name": "max",
+          "type": "number",
+          "required": false,
+          "description": "The largest amount in integer paise; the field moves a larger one down to it on blur."
+        },
+        {
+          "name": "size",
+          "type": "32 | 36",
+          "required": false,
+          "default": "36",
+          "description": "The height in px: 36 for forms, 32 for prices inside a table. Defaults to 36."
+        },
+        {
+          "name": "ref",
+          "type": "Ref<HTMLInputElement>",
+          "required": false,
+          "description": "Receives the input element."
+        }
+      ],
+      "usage": {
+        "whenToUse": "- Any amount of money a person types: MRP, selling price, cost price, variant prices\n- Values stored as integer paise: `value` and `onValueChange` take and give paise, and under a `name` a form submits paise\n- A price inside a table: `size` 32\n- Amounts people paste from a spreadsheet or another page: a pasted amount with the rupee sign or either grouping is read as paise",
+        "whenNotToUse": "- Showing an amount that is not edited: write it with the format module (`formatPaise`) in text\n- A number that is not money, such as a weight or a length: use UnitInput\n- A count of items: use Input with `inputMode=\"numeric\"`\n- Custom classes or inline styles: MoneyInput takes neither `className` nor `style`",
+        "example": "const [mrp, setMrp] = useState<number | null>(129900)\n\n<MoneyInput aria-label=\"MRP\" value={mrp} onValueChange={setMrp} min={0} />\n<MoneyInput aria-label=\"Price of L\" size={32} defaultValue={44900} name=\"price\" />\n<MoneyInput aria-label=\"Selling price\" aria-invalid aria-describedby=\"price-error\" />"
+      }
+    },
     {
       "name": "PageHeader",
       "import": "import { PageHeader } from '@ratio-ui/core'",
@@ -1216,12 +1870,6 @@
           "import": "import { PopoverTrigger } from '@ratio-ui/core'",
           "description": "The element that opens the popover on click or Enter. It renders a button unless render says otherwise.",
           "props": [
-            {
-              "name": "render",
-              "type": "ReactElement<unknown, string | JSXElementConstructor<any>> | ComponentRenderFn<HTMLProps, PopoverTriggerState>",
-              "required": false,
-              "description": "Allows you to replace the component's HTML element with a different tag, or compose it with another component.\n\nAccepts a `ReactElement` or a function that returns the element to render."
-            },
             {
               "name": "handle",
               "type": "PopoverHandle<unknown>",
@@ -1234,6 +1882,12 @@
               "required": false,
               "description": "A payload to pass to the popover when it is opened."
             },
+            {
+              "name": "render",
+              "type": "ReactElement<unknown, string | JSXElementConstructor<any>> | ComponentRenderFn<HTMLProps, PopoverTriggerState>",
+              "required": false,
+              "description": "Allows you to replace the component's HTML element with a different tag, or compose it with another component.\n\nAccepts a `ReactElement` or a function that returns the element to render."
+            },
             {
               "name": "delay",
               "type": "number",
@@ -1257,7 +1911,78 @@
             }
           ]
         }
-      ]
+      ]
+    },
+    {
+      "name": "SaveBar",
+      "import": "import { SaveBar } from '@ratio-ui/core'",
+      "description": "The bar that appears under the top bar when a form is dirty: a message, Discard and Save. It renders in flow, so the page (AppShell) decides where it sits. While saving, Save is disabled; Discard only calls onDiscard.",
+      "props": [
+        {
+          "name": "dirty",
+          "type": "boolean",
+          "required": true,
+          "description": "Whether the form has unsaved changes. The bar renders nothing when false."
+        },
+        {
+          "name": "saving",
+          "type": "boolean",
+          "required": false,
+          "default": "false",
+          "description": "True while the save is running: Save is disabled and reads the saving label."
+        },
+        {
+          "name": "onSave",
+          "type": "() => void",
+          "required": true,
+          "description": "Called by Save."
+        },
+        {
+          "name": "onDiscard",
+          "type": "() => void",
+          "required": true,
+          "description": "Called by Discard. The bar asks nothing itself: confirm in the caller if you need to."
+        },
+        {
+          "name": "message",
+          "type": "ReactNode",
+          "required": false,
+          "default": "Unsaved changes",
+          "description": "The message. Defaults to \"Unsaved changes\"."
+        },
+        {
+          "name": "saveLabel",
+          "type": "ReactNode",
+          "required": false,
+          "default": "Save",
+          "description": "The Save label. Defaults to \"Save\"."
+        },
+        {
+          "name": "savingLabel",
+          "type": "ReactNode",
+          "required": false,
+          "default": "Saving…",
+          "description": "The Save label while saving. Defaults to \"Saving…\"."
+        },
+        {
+          "name": "discardLabel",
+          "type": "ReactNode",
+          "required": false,
+          "default": "Discard",
+          "description": "The Discard label. Defaults to \"Discard\"."
+        },
+        {
+          "name": "ref",
+          "type": "Ref<HTMLDivElement>",
+          "required": false,
+          "description": "Receives the rendered div."
+        }
+      ],
+      "usage": {
+        "whenToUse": "- Under the top bar of a form page, when the form has unsaved changes: \"Unsaved changes\", Discard, Save\n- Drive `dirty` from the form's dirty state and `saving` from the pending save",
+        "whenNotToUse": "- A confirmation: Discard only calls `onDiscard`; open an AlertDialog yourself if the loss needs confirming\n- Per-field saving: save on change or use the field's own action",
+        "example": "```tsx\n<SaveBar dirty={form.isDirty} saving={form.isSaving} onSave={form.save} onDiscard={form.reset} />\n```\n\nIt renders in flow and nothing when not dirty; the app shell decides where it sits. While saving, Save is disabled."
+      }
     },
     {
       "name": "SearchField",
@@ -1309,6 +2034,117 @@
         "example": "<SearchField label=\"Search products\" placeholder=\"Search by name, SKU\" value={query} onValueChange={setQuery} />"
       }
     },
+    {
+      "name": "Select",
+      "import": "import { Select } from '@ratio-ui/core'",
+      "description": "A choice from a fixed list. Pass items ({ label, value }[]) so the trigger shows the label of the chosen value. Put a SelectTrigger and a SelectContent inside it.",
+      "props": [],
+      "usage": {
+        "whenToUse": "- A choice from a short, fixed list in a form, such as a GST rate (0, 5, 12, 18, 28%), a return window or a status\n- A field in a table cell: `size={32}` on the trigger\n- A form row with a label, hint, error or required mark: put the Select inside a Field with a function child (see below)",
+        "whenNotToUse": "- A long list, or one the user searches: use a combobox\n- Free text or several values (tags): use Input or TagInput\n- A menu of actions: use DropdownMenu\n- Custom classes or inline styles: no part takes `className` or `style`",
+        "example": "```tsx\nconst rates = [\n  { label: '0%', value: '0' },\n  { label: '18%', value: '18' },\n]\n\n<Select items={rates} defaultValue=\"18\">\n  <SelectTrigger aria-label=\"GST rate\">\n    <SelectValue placeholder=\"Choose a rate\" />\n  </SelectTrigger>\n  <SelectContent>\n    <SelectGroup>\n      <SelectLabel>Rates</SelectLabel>\n      <SelectItem value=\"0\">0%</SelectItem>\n      <SelectItem value=\"18\">18%</SelectItem>\n    </SelectGroup>\n  </SelectContent>\n</Select>\n```\n\nPass `items` to `Select` so the trigger shows the label, not the raw value."
+      },
+      "parts": [
+        {
+          "name": "SelectContent",
+          "import": "import { SelectContent } from '@ratio-ui/core'",
+          "description": "The list: the popover look (8px radius, outline, no shadow, 6px 0 padding), as wide as the trigger. It opens below the trigger.",
+          "props": [
+            {
+              "name": "render",
+              "type": "ReactElement<unknown, string | JSXElementConstructor<any>> | ComponentRenderFn<HTMLProps, SelectPopupState>",
+              "required": false,
+              "description": "Allows you to replace the component's HTML element with a different tag, or compose it with another component.\n\nAccepts a `ReactElement` or a function that returns the element to render."
+            }
+          ]
+        },
+        {
+          "name": "SelectGroup",
+          "import": "import { SelectGroup } from '@ratio-ui/core'",
+          "description": "Groups related options under a SelectLabel.",
+          "props": [
+            {
+              "name": "render",
+              "type": "ReactElement<unknown, string | JSXElementConstructor<any>> | ComponentRenderFn<HTMLProps, SelectGroupState>",
+              "required": false,
+              "description": "Allows you to replace the component's HTML element with a different tag, or compose it with another component.\n\nAccepts a `ReactElement` or a function that returns the element to render."
+            }
+          ]
+        },
+        {
+          "name": "SelectItem",
+          "import": "import { SelectItem } from '@ratio-ui/core'",
+          "description": "One option. The highlighted one has the accent background, the chosen one a check at its end, a disabled one is dimmed and cannot be chosen.",
+          "props": [
+            {
+              "name": "render",
+              "type": "ReactElement<unknown, string | JSXElementConstructor<any>> | ComponentRenderFn<HTMLProps, SelectItemState>",
+              "required": false,
+              "description": "Allows you to replace the component's HTML element with a different tag, or compose it with another component.\n\nAccepts a `ReactElement` or a function that returns the element to render."
+            }
+          ]
+        },
+        {
+          "name": "SelectLabel",
+          "import": "import { SelectLabel } from '@ratio-ui/core'",
+          "description": "The heading of a group, in the muted colour.",
+          "props": [
+            {
+              "name": "render",
+              "type": "ReactElement<unknown, string | JSXElementConstructor<any>> | ComponentRenderFn<HTMLProps, SelectGroupLabelState>",
+              "required": false,
+              "description": "Allows you to replace the component's HTML element with a different tag, or compose it with another component.\n\nAccepts a `ReactElement` or a function that returns the element to render."
+            }
+          ]
+        },
+        {
+          "name": "SelectSeparator",
+          "import": "import { SelectSeparator } from '@ratio-ui/core'",
+          "description": "A hairline between groups.",
+          "props": [
+            {
+              "name": "render",
+              "type": "ReactElement<unknown, string | JSXElementConstructor<any>> | ComponentRenderFn<HTMLProps, SelectSeparatorState>",
+              "required": false,
+              "description": "Allows you to replace the component's HTML element with a different tag, or compose it with another component.\n\nAccepts a `ReactElement` or a function that returns the element to render."
+            }
+          ]
+        },
+        {
+          "name": "SelectTrigger",
+          "import": "import { SelectTrigger } from '@ratio-ui/core'",
+          "description": "The closed field: the chosen value (or the placeholder) and a chevron at the right. Put a SelectValue inside it.",
+          "props": [
+            {
+              "name": "render",
+              "type": "ReactElement<unknown, string | JSXElementConstructor<any>> | ComponentRenderFn<HTMLProps, SelectTriggerState>",
+              "required": false,
+              "description": "Allows you to replace the component's HTML element with a different tag, or compose it with another component.\n\nAccepts a `ReactElement` or a function that returns the element to render."
+            },
+            {
+              "name": "size",
+              "type": "32 | 36",
+              "required": false,
+              "default": "36",
+              "description": "The height in px: 36 for forms, 32 inside a table. Defaults to 36."
+            }
+          ]
+        },
+        {
+          "name": "SelectValue",
+          "import": "import { SelectValue } from '@ratio-ui/core'",
+          "description": "Shows the label of the chosen option inside the trigger, or the placeholder while nothing is chosen.",
+          "props": [
+            {
+              "name": "render",
+              "type": "ReactElement<unknown, string | JSXElementConstructor<any>> | ComponentRenderFn<HTMLProps, SelectValueState>",
+              "required": false,
+              "description": "Allows you to replace the component's HTML element with a different tag, or compose it with another component.\n\nAccepts a `ReactElement` or a function that returns the element to render."
+            }
+          ]
+        }
+      ]
+    },
     {
       "name": "SideNav",
       "import": "import { SideNav } from '@ratio-ui/core'",
@@ -1470,6 +2306,41 @@
         "example": "<StatusPill tone=\"success\">Active</StatusPill>"
       }
     },
+    {
+      "name": "SummaryChips",
+      "import": "import { SummaryChips } from '@ratio-ui/core'",
+      "description": "A row of 20px chips that summarise values, such as the ones a collapsed section still shows.",
+      "props": [
+        {
+          "name": "items",
+          "type": "readonly SummaryChip[]",
+          "required": true,
+          "description": "The chips, in order. Nothing is rendered when empty."
+        },
+        {
+          "name": "ref",
+          "type": "Ref<HTMLUListElement>",
+          "required": false,
+          "description": "Receives the rendered list."
+        }
+      ],
+      "usage": {
+        "whenToUse": "- A collapsed section that still shows its values: \"Cost price · HSN code · Includes GST Yes\"\n- A short read-only summary of a record's settings",
+        "whenNotToUse": "- Values the person can edit or remove: use a tag input\n- A status of a row: use StatusPill",
+        "example": "<SummaryChips items={[{ label: 'Cost price', value: '₹450.00' }, { label: 'Includes GST', value: 'Yes' }]} />"
+      }
+    },
+    {
+      "name": "Switch",
+      "import": "import { Switch } from '@ratio-ui/core'",
+      "description": "An on/off switch, 32px by 18px. Off it is drawn with the control hairline; on it is filled in the primary colour. In forced-colours mode the thumb keeps a system-colour outline, and its side shows the state. The thumb jumps to the other end with no slide, and colours fade over 120ms.",
+      "props": [],
+      "usage": {
+        "whenToUse": "- An on/off setting that takes effect as soon as it changes, such as \"Inventory tracked\" or \"Cash on delivery\"\n- Give it an `aria-label`, or a label that points to it",
+        "whenNotToUse": "- A choice that is sent with a form and several others: use Checkbox\n- Custom classes or inline styles: Switch takes no `className` and no `style`",
+        "example": "<Switch aria-label=\"Inventory tracked\" defaultChecked />"
+      }
+    },
     {
       "name": "Table",
       "import": "import { Table } from '@ratio-ui/core'",
@@ -1651,6 +2522,123 @@
         }
       ]
     },
+    {
+      "name": "TagInput",
+      "import": "import { TagInput } from '@ratio-ui/core'",
+      "description": "Several values as chips in one field in the input's look. The picker offers the existing values (typing filters them), a small field below adds a new one on Enter, and a chip goes with its remove button or with Backspace in the empty picker. Base UI's combobox cannot accept a value it does not list, which is why new values have their own field.",
+      "props": [
+        {
+          "name": "options",
+          "type": "readonly string[]",
+          "required": true,
+          "description": "The existing values the picker offers, such as S, M, L, XL and XXL."
+        },
+        {
+          "name": "value",
+          "type": "readonly string[]",
+          "required": false,
+          "description": "The chosen values, in order, when the owner holds the state."
+        },
+        {
+          "name": "defaultValue",
+          "type": "readonly string[]",
+          "required": false,
+          "description": "The values chosen at first, when the component holds the state."
+        },
+        {
+          "name": "onValueChange",
+          "type": "((value: string[]) => void)",
+          "required": false,
+          "description": "Called with every new list of values: after a pick, an added value or a removal."
+        },
+        {
+          "name": "creatable",
+          "type": "boolean",
+          "required": false,
+          "default": "true",
+          "description": "Shows a small field that adds a typed value on Enter. Defaults to true."
+        },
+        {
+          "name": "addLabel",
+          "type": "string",
+          "required": false,
+          "default": "Add value",
+          "description": "The placeholder and accessible name of the small field. Defaults to \"Add value\"."
+        },
+        {
+          "name": "placeholder",
+          "type": "string",
+          "required": false,
+          "description": "The placeholder of the picker, shown while nothing is chosen."
+        },
+        {
+          "name": "emptyText",
+          "type": "string",
+          "required": false,
+          "default": "No matching values",
+          "description": "The line the list shows when no value matches the typed text. Defaults to \"No matching values\"."
+        },
+        {
+          "name": "name",
+          "type": "string",
+          "required": false,
+          "description": "The form field name: one hidden input per chosen value is submitted under it."
+        },
+        {
+          "name": "disabled",
+          "type": "boolean",
+          "required": false,
+          "description": "Dims the component and stops every change."
+        },
+        {
+          "name": "id",
+          "type": "string",
+          "required": false,
+          "description": "The id of the picker's input, which a label points to."
+        },
+        {
+          "name": "aria-label",
+          "type": "string",
+          "required": false,
+          "description": "The accessible name of the picker, when no label points to it."
+        },
+        {
+          "name": "aria-labelledby",
+          "type": "string",
+          "required": false,
+          "description": "The id of the element that names the picker."
+        },
+        {
+          "name": "aria-describedby",
+          "type": "string",
+          "required": false,
+          "description": "The ids of the hint or error that describe the component."
+        },
+        {
+          "name": "aria-invalid",
+          "type": "boolean | \"true\" | \"false\"",
+          "required": false,
+          "description": "Marks the values as invalid, which draws the error ring."
+        },
+        {
+          "name": "aria-required",
+          "type": "boolean | \"true\" | \"false\"",
+          "required": false,
+          "description": "Marks the values as required."
+        },
+        {
+          "name": "ref",
+          "type": "Ref<HTMLInputElement>",
+          "required": false,
+          "description": "Receives the picker's input element."
+        }
+      ],
+      "usage": {
+        "whenToUse": "- Several values in one field, such as a product's tags or a variant option's values (S, M, L, XL, XXL)\n- Picking from existing values, with typing to filter them, and adding a new one in the small field below (Enter adds it)\n- Inside a Field: the label, hint, error and required mark land on the picker",
+        "whenNotToUse": "- One value from a fixed list: use Select\n- A read-only summary of values: use SummaryChips\n- Only existing values and no new ones: keep TagInput and set `creatable={false}`\n- Custom classes or inline styles: TagInput takes no `className` and no `style`",
+        "example": "```tsx\nconst [sizes, setSizes] = useState(['S', 'M'])\n\n<Field label=\"Size\" error={errors.size}>\n  <TagInput options={['S', 'M', 'L', 'XL', 'XXL']} value={sizes} onValueChange={setSizes} placeholder=\"Choose sizes\" />\n</Field>\n```\n\nA chip goes with its remove button, or with Backspace in the empty picker. A new value is trimmed, takes the spelling of an existing value that differs only in letter case, and is not added twice. Base UI's combobox cannot accept a value it does not list, so new values have their own field."
+      }
+    },
     {
       "name": "Text",
       "import": "import { Text } from '@ratio-ui/core'",
@@ -1697,6 +2685,31 @@
         "example": "<Text as=\"h1\" variant=\"h1\">Settlements</Text>\n<Text tone=\"subdued\">Paid out every weekday</Text>"
       }
     },
+    {
+      "name": "Textarea",
+      "import": "import { Textarea } from '@ratio-ui/core'",
+      "description": "A multi-line text field in the input's look: 8px radius, 1px ring that turns blue on focus, 10px 12px padding, 88px tall (64px compact).",
+      "props": [
+        {
+          "name": "size",
+          "type": "64 | 88",
+          "required": false,
+          "default": "88",
+          "description": "The height in px: 88 by default, 64 compact. The field can still be dragged taller."
+        },
+        {
+          "name": "ref",
+          "type": "Ref<HTMLTextAreaElement>",
+          "required": false,
+          "description": "Receives the textarea element."
+        }
+      ],
+      "usage": {
+        "whenToUse": "- A multi-line text field such as a product description: 88px tall by default, `size={64}` for a compact one\n- A field with an error: set `aria-invalid` and the ring changes, and put the error message beside it in text",
+        "whenNotToUse": "- A single line of text: use Input\n- Custom classes or inline styles: Textarea takes no `className` and no `style`",
+        "example": "<Textarea aria-label=\"Description\" placeholder=\"Describe the product\" />\n<Textarea aria-label=\"Note\" size={64} />"
+      }
+    },
     {
       "name": "Toaster",
       "import": "import { Toaster } from '@ratio-ui/core'",
@@ -1850,6 +2863,74 @@
           ]
         }
       ]
+    },
+    {
+      "name": "UnitInput",
+      "import": "import { UnitInput } from '@ratio-ui/core'",
+      "description": "A number field with its unit after it, inside one ring: a weight in kg, a length in cm. It takes and gives a number, written without thousands separators as counts are, and keeps at most `decimals` decimals.",
+      "props": [
+        {
+          "name": "unit",
+          "type": "string",
+          "required": true,
+          "description": "The unit after the number, such as kg or cm. Screen readers read it as the field's description."
+        },
+        {
+          "name": "value",
+          "type": "number | null",
+          "required": false,
+          "description": "The number, or null for an empty field. Pass it to control the field."
+        },
+        {
+          "name": "defaultValue",
+          "type": "number | null",
+          "required": false,
+          "description": "The starting number when the field is not controlled. Defaults to empty."
+        },
+        {
+          "name": "onValueChange",
+          "type": "((value: number | null) => void)",
+          "required": false,
+          "description": "Called with the number as it is typed or cleared (null when empty), and with the rounded number on blur."
+        },
+        {
+          "name": "decimals",
+          "type": "number",
+          "required": false,
+          "default": "3",
+          "description": "The most decimals the number keeps; the field rounds to them on blur. Defaults to 3 (grams in kg)."
+        },
+        {
+          "name": "min",
+          "type": "number",
+          "required": false,
+          "description": "The smallest number; the field moves a smaller one up to it on blur."
+        },
+        {
+          "name": "max",
+          "type": "number",
+          "required": false,
+          "description": "The largest number; the field moves a larger one down to it on blur."
+        },
+        {
+          "name": "size",
+          "type": "32 | 36",
+          "required": false,
+          "default": "36",
+          "description": "The height in px: 36 for forms, 32 for fields inside a table. Defaults to 36."
+        },
+        {
+          "name": "ref",
+          "type": "Ref<HTMLInputElement>",
+          "required": false,
+          "description": "Receives the input element."
+        }
+      ],
+      "usage": {
+        "whenToUse": "- A number with a unit after it: weight in kg, length in cm, a lead time in days\n- Values stored as numbers: `value` and `onValueChange` take and give a number, null when empty\n- A field inside a table: `size` 32",
+        "whenNotToUse": "- Money: use MoneyInput, which takes and gives paise\n- A unit before the number, or an icon: use InputGroup with an addon\n- Text that is not a number: use Input\n- Custom classes or inline styles: UnitInput takes neither `className` nor `style`",
+        "example": "const [weight, setWeight] = useState<number | null>(0.24)\n\n<UnitInput aria-label=\"Weight\" unit=\"kg\" value={weight} onValueChange={setWeight} min={0} />\n<UnitInput aria-label=\"Length\" unit=\"cm\" decimals={0} defaultValue={30} name=\"length\" />"
+      }
     }
   ]
 }