@optimum-intelligence/opti-ui 0.4.0 → 0.5.0

package/dist/llms-full.txt

@@ -107,1365 +107,1483 @@ import { themeToStyle } from '@optimum-intelligence/opti-ui';
 
 Signature: `themeToStyle(theme: Theme \| undefined)`
 
-# Layout
+# Forms
 
-## AppShell
+## Calendar
 
-component · Layout
+component · Forms
 
-Full-height layout with a fixed navbar and an internally scrolling main
-area. Below 900px the navbar moves into a slide-in drawer.
-Customize width with `--oui-navbar-width` and `--oui-navbar-collapsed-width`.
+Month grid for picking one day. Keyboard: arrows move by day / week,
+Home / End jump within the week, PageUp / PageDown change month (with Shift: year).
+The month and year in the title open a list to jump straight to another one.
+With `granularity="month"` or `"year"` it shows a month or year grid instead.
 
 ```tsx
-import { AppShell } from '@optimum-intelligence/opti-ui';
+import { Calendar } from '@optimum-intelligence/opti-ui';
+```
+
+```tsx
+<Calendar value={month} onValueChange={setMonth} granularity="month" />
 ```
 
 | Prop | Type | Default | Description |
 | --- | --- | --- | --- |
-| `ref?` | `React.Ref<HTMLDivElement>` |  | Ref to the shell's root element. |
-| `navbar` | `React.ReactNode` |  | Navbar content (usually a `<Navbar>`). Rendered in a drawer on small screens. |
-| `mobileBrand?` | `React.ReactNode` |  | Brand shown in the mobile top bar. |
-| `mobileActions?` | `React.ReactNode` |  | Extra content on the right of the mobile top bar. |
-| `menuLabel?` | `string` | `'Open navigation'` | Accessible name of the button that opens the navigation drawer on small screens. |
-| `mainProps?` | `React.HTMLAttributes<HTMLElement>` |  | Props for the scrolling `<main>` element. |
+| `value?` | `string \| null` |  | Selected day as an ISO date (`"2026-03-09"`). With a month or year `granularity`, the day it falls in is enough. |
+| `defaultValue?` | `string \| null` | `null` | Initially selected day (ISO date) when uncontrolled. |
+| `onValueChange?` | `(value: string) => void` |  | Called with the picked day as an ISO date: the 1st of the month, or 1 January, for a month or year `granularity`. |
 
-Also accepts all props of: `React.HTMLAttributes<HTMLDivElement>`.
+Also accepts all props of: `CalendarOptions`.
 
-## Card
+## Checkbox
 
-component · Layout
+component · Forms
 
-Surface that groups related content. Compose with `CardHeader` (`CardTitle`, `CardDescription`,
-`CardActions`), `CardContent` and `CardFooter`.
+Checkbox with optional `label` and `description`. Supports `indeterminate`.
 
 ```tsx
-import { Card } from '@optimum-intelligence/opti-ui';
+import { Checkbox } from '@optimum-intelligence/opti-ui';
 ```
 
+
+Also accepts all props of: `BaseCheckbox.Root.Props`, `ChoiceLabelProps`.
+
+## CheckboxGroup
+
+component · Forms
+
+Manages the checked values of several `Checkbox` children (`value` / `onValueChange`).
+
 ```tsx
-<Card variant="elevated">
-  <CardHeader>
-    <CardTitle>Monthly energy</CardTitle>
-    <CardDescription>Last 30 days</CardDescription>
-  </CardHeader>
-  <CardContent>…</CardContent>
-</Card>
+import { CheckboxGroup } from '@optimum-intelligence/opti-ui';
 ```
 
 | Prop | Type | Default | Description |
 | --- | --- | --- | --- |
-| `variant?` | `'outlined' \| 'elevated' \| 'filled' \| 'ghost'` | `'outlined'` | `outlined` (default) uses the card border, `elevated` a soft shadow. |
-| `padding?` | `'none' \| 'sm' \| 'md' \| 'lg'` | `'md'` | Inner spacing. Override with `--oui-card-padding`. |
-| `interactive?` | `boolean` | `false` | Adds hover and focus states — use with `render={<a href=… />}` or a click handler. |
+| `orientation?` | `'vertical' \| 'horizontal'` | `'vertical'` | Layout direction of the checkboxes. |
 
-Also accepts all props of: `useRender.ComponentProps<'div', CardState>`.
+Also accepts all props of: `BaseCheckboxGroup.Props`.
 
-## CardActions
+## Combobox
 
-compound · Layout
+compound · Forms
 
-Right-aligned slot inside CardHeader for icon buttons or menus.
+Searchable select. `<Combobox items={…} />` covers single and `multiple`
+(chips) selection; compose the parts for anything custom.
 
 ```tsx
-import { CardActions } from '@optimum-intelligence/opti-ui';
+import { Combobox } from '@optimum-intelligence/opti-ui';
 ```
 
-### CardActions.displayName
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| `items` | `ComboboxOption[]` |  | Options to choose from. |
+| `label?` | `React.ReactNode` |  | Visible field label. |
+| `description?` | `React.ReactNode` |  | Help text under the input. |
+| `error?` | `React.ReactNode` |  | Error message. When set, the field is marked invalid. |
+| `placeholder?` | `string` |  | Placeholder shown while nothing is typed or selected. |
+| `emptyText?` | `React.ReactNode` | `'No results found.'` | Shown when the filter matches nothing. |
+| `size?` | `'sm' \| 'md' \| 'lg'` | `'md'` | Control height. |
+| `hideClear?` | `boolean` |  | Hide the clear button. |
+| `inputProps?` | `BaseCombobox.Input.Props` |  | Props for the text input. |
 
-## CardContent
+Also accepts all props of: `RootProps`.
 
-compound · Layout
+### Combobox.Root
 
-Styled `<div>` (`.oui-card__content`). Accepts `className`, `style`, the `render` prop and all `<div>` attributes.
+Base UI `Combobox.Root` re-exported unchanged. See https://base-ui.com/react/components/combobox.
 
-```tsx
-import { CardContent } from '@optimum-intelligence/opti-ui';
-```
+### Combobox.InputGroup
 
-### CardContent.displayName
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| `size?` | `'sm' \| 'md' \| 'lg'` | `'md'` | Control height. |
 
-## CardDescription
+Also accepts all props of: `BaseCombobox.InputGroup.Props`.
 
-compound · Layout
+### Combobox.Input
 
-Styled `<p>` (`.oui-card__description`). Accepts `className`, `style`, the `render` prop and all `<p>` attributes.
+### Combobox.Trigger
 
-```tsx
-import { CardDescription } from '@optimum-intelligence/opti-ui';
-```
+### Combobox.Clear
 
-### CardDescription.displayName
+### Combobox.Value
 
-## CardFooter
+Base UI `Combobox.Value` re-exported unchanged. See https://base-ui.com/react/components/combobox.
 
-compound · Layout
+### Combobox.Chips
 
-Styled `<div>` (`.oui-card__footer`). Accepts `className`, `style`, the `render` prop and all `<div>` attributes.
+### Combobox.Chip
 
-```tsx
-import { CardFooter } from '@optimum-intelligence/opti-ui';
-```
+### Combobox.Content
 
-### CardFooter.displayName
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| `side?` | `BaseCombobox.Positioner.Props['side']` |  | Which side of the input the list opens on. |
+| `align?` | `BaseCombobox.Positioner.Props['align']` |  | Alignment along that side. |
+| `sideOffset?` | `BaseCombobox.Positioner.Props['sideOffset']` | `6` | Distance from the input in px. |
+| `positionerProps?` | `BaseCombobox.Positioner.Props` |  | Props for the positioner element that places the popup. |
 
-## CardHeader
+Also accepts all props of: `BaseCombobox.Popup.Props`.
 
-compound · Layout
+### Combobox.List
 
-Styled `<div>` (`.oui-card__header`). Accepts `className`, `style`, the `render` prop and all `<div>` attributes.
+### Combobox.Item
 
-```tsx
-import { CardHeader } from '@optimum-intelligence/opti-ui';
-```
+### Combobox.Empty
 
-### CardHeader.displayName
+### Combobox.Group
 
-## CardTitle
+Base UI `Combobox.Group` re-exported unchanged. See https://base-ui.com/react/components/combobox.
 
-compound · Layout
+### Combobox.GroupLabel
 
-Styled `<h3>` (`.oui-card__title`). Accepts `className`, `style`, the `render` prop and all `<h3>` attributes.
+### Combobox.Collection
 
-```tsx
-import { CardTitle } from '@optimum-intelligence/opti-ui';
-```
+Base UI `Combobox.Collection` re-exported unchanged. See https://base-ui.com/react/components/combobox.
 
-### CardTitle.displayName
+### Combobox.useFilter
 
-## Grid
+Base UI `Combobox.useFilter` re-exported unchanged. See https://base-ui.com/react/components/combobox.
 
-component · Layout
+## DateConfigProvider
 
-Responsive dashboard grid.
+component · Forms
+
+Sets default locale, time zone, week start and display formats for every
+date picker and calendar inside it. Props on a component still win.
+Nested providers override only the settings they pass.
 
 ```tsx
-import { Grid } from '@optimum-intelligence/opti-ui';
+import { DateConfigProvider } from '@optimum-intelligence/opti-ui';
+```
+
+```tsx
+<DateConfigProvider timeZone="Europe/Budapest" locale="hu-HU" formats={{ day: 'YYYY.MM.DD' }}>
+  <App />
+</DateConfigProvider>
 ```
 
 | Prop | Type | Default | Description |
 | --- | --- | --- | --- |
-| `ref?` | `React.Ref<HTMLDivElement>` |  | Ref to the grid element. |
-| `columns?` | `1 \| 2 \| 3 \| 4 \| 5 \| 6` | `3` | Columns on wide screens; collapses to 2 below 1200px (for 4+) and 1 below 900px. |
-| `gap?` | `'sm' \| 'md' \| 'lg'` | `'md'` | Space between grid cells. |
+| `locale?` | `string` |  | BCP 47 locale for month and weekday names. |
+| `timeZone?` | `string` |  | IANA zone (`"Europe/Budapest"`) that date-times are shown and edited in. Defaults to the browser's. |
+| `weekStartsOn?` | `0 \| 1 \| 2 \| 3 \| 4 \| 5 \| 6` |  | First calendar column: 0 = Sunday, 1 = Monday. |
+| `formats?` | `Partial<Record<DateGranularity, string>>` |  | Display patterns per granularity, e.g. `{ day: 'DD.MM.YYYY' }`. Tokens as in `formatDate`. |
+| `children?` | `React.ReactNode` |  | The subtree that uses these settings. |
 
-Also accepts all props of: `React.HTMLAttributes<HTMLDivElement>`.
+## DatePicker
 
-## Navbar
+component · Forms
 
-component · Layout
+Date field with a calendar popover. Day values are ISO dates (`"2026-03-09"`),
+the same format as `<input type="date">`. `granularity="month"` or `"year"` opens a
+month or year grid and stores the period's first day (`"2026-03-01"`); a time
+granularity behaves like `DateTimePicker`.
 
-Collapsible side navigation. Use inside `AppShell`. Compose with `NavbarHeader` (`NavbarBrand`),
-`NavbarSection` (`NavbarSectionLabel`, `NavbarItem`) and `NavbarFooter`.
+```tsx
+import { DatePicker } from '@optimum-intelligence/opti-ui';
+```
 
 ```tsx
-import { Navbar } from '@optimum-intelligence/opti-ui';
+<DatePicker label="Delivery date" value={date} onValueChange={setDate} />
+<DatePicker label="Billing month" granularity="month" format="MMMM YYYY" />
 ```
 
-| Prop | Type | Default | Description |
-| --- | --- | --- | --- |
-| `variant?` | `'inverse' \| 'surface'` | `'inverse'` | `inverse` (brand-colored, default) or `surface` (light panel). |
-| `collapsible?` | `boolean` | `true` | Shows a toggle in the top right that shrinks the navbar to an icon rail. Defaults to `true`. |
-| `collapsed?` | `boolean` |  | Controlled collapsed state. |
-| `defaultCollapsed?` | `boolean` | `false` | Initial collapsed state when uncontrolled. |
-| `onCollapsedChange?` | `(collapsed: boolean) => void` |  | Called when the user collapses or expands the navbar. |
-| `expandOnHover?` | `boolean` | `true` | Temporarily opens a collapsed navbar while the mouse is over it. Defaults to `true`. |
-| `collapseLabel?` | `string` | `'Collapse'` | Accessible names for the icon-only toggle. |
-| `expandLabel?` | `string` | `'Expand'` | Accessible name of the toggle while collapsed. |
 
-Also accepts all props of: `useRender.ComponentProps<'nav', NavbarState>`.
+Also accepts all props of: `PickerProps`.
 
-## NavbarBrand
+## DateRangePicker
 
-component · Layout
+component · Forms
 
-Logo, title and subtitle block for the top of a `Navbar`.
+Date range field with a calendar popover and optional presets. Values are
+`{ start, end }` ISO dates (`"2026-03-09"`), both inclusive. With
+`granularity="month"` or `"year"` it picks whole months or years, and each end
+is the first day of its period.
 
 ```tsx
-import { NavbarBrand } from '@optimum-intelligence/opti-ui';
+import { DateRangePicker } from '@optimum-intelligence/opti-ui';
+```
+
+```tsx
+<DateRangePicker label="Period" value={period} onValueChange={setPeriod} presets={presets} />
 ```
 
 | Prop | Type | Default | Description |
 | --- | --- | --- | --- |
-| `logo?` | `React.ReactNode` |  | Logo or icon shown before the title; stays visible when the navbar is collapsed. |
-| `title` | `React.ReactNode` |  | Product or organization name. |
-| `subtitle?` | `React.ReactNode` |  | Smaller line under the title. |
+| `ref?` | `React.Ref<HTMLButtonElement>` |  | Ref to the trigger button. |
+| `label?` | `React.ReactNode` |  | Visible field label. |
+| `description?` | `React.ReactNode` |  | Help text under the field. |
+| `error?` | `React.ReactNode` |  | Error message. When set, the field is marked invalid. |
+| `required?` | `boolean` |  | Marks the field required and adds the required indicator to the label. |
+| `disabled?` | `boolean` |  | Disables the field. |
+| `placeholder?` | `React.ReactNode` | `'Select dates'` | Text shown while no date is selected. |
+| `size?` | `'sm' \| 'md' \| 'lg'` |  | Control height. |
+| `open?` | `boolean` |  | Whether the calendar popover is open (controlled). |
+| `defaultOpen?` | `boolean` |  | Initial popover state when uncontrolled. |
+| `onOpenChange?` | `(open: boolean) => void` |  | Called when the popover opens or closes. |
+| `id?` | `string` |  | Id of the trigger button. Generated when omitted. |
+| `className?` | `string` |  | Class name for the trigger button. |
+| `triggerProps?` | `Omit<React.ComponentProps<typeof BasePopover.Trigger>, 'children' \| 'disabled' \| 'id'>` |  | Props for the trigger button (aria-*, data-*, onBlur…). |
+| `contentProps?` | `Omit<PopoverContentProps, 'children'>` |  | Props for the popover content. |
+| `value?` | `DateRange \| null` |  | Selected days as ISO dates; both ends are inclusive. |
+| `defaultValue?` | `DateRange \| null` | `null` | Initially selected range when uncontrolled. |
+| `onValueChange?` | `(value: DateRange \| null) => void` |  | Called with the new range, or `null` when cleared. |
+| `min?` | `string` |  | Earliest allowed day. |
+| `max?` | `string` |  | Latest allowed day. |
+| `presets?` | `DateRangePreset[]` |  | Shortcuts listed beside the calendar ("Last 7 days", "This month"…). |
+| `startName?` | `string` |  | Submits the first day with a form under this name. |
+| `endName?` | `string` |  | Submits the last day with a form under this name. |
+| `clearable?` | `boolean` |  | Show the Clear action. Defaults to `true` unless `required`. |
+| `format?` | `string` |  | Display pattern for each end, e.g. `"DD.MM.YYYY"` (tokens as in `formatDate`). Defaults to `DateConfigProvider` formats, then an ISO-style pattern for the granularity. |
+| `formatValue?` | `(value: DateRange) => React.ReactNode` |  | Custom display text for the selected range. Wins over `format`. |
+| `labels?` | `Partial<DateRangePickerLabels>` |  | Override texts for localisation. |
 
-Also accepts all props of: `Omit<useRender.ComponentProps<'div'>, 'title'>`.
+Also accepts all props of: `Pick<RangeCalendarProps, 'isDateDisabled' \| 'defaultMonth' \| 'locale' \| 'weekStartsOn' \| 'numberOfMonths' \| 'granularity'>`.
 
-## NavbarFooter
+## DateTimePicker
 
-compound · Layout
+component · Forms
 
-Styled `<div>` (`.oui-navbar__footer`). Accepts `className`, `style`, the `render` prop and all `<div>` attributes.
+Date and time field. Values are UTC instants (`"2026-03-09T13:30:00Z"`) shown and
+edited in `timeZone` (the browser's by default) on a 24-hour clock, as
+`2026-03-09 14:30`. Values without an offset (`"2026-03-09T14:30"`) are read as
+wall-clock time in `timeZone`.
 
 ```tsx
-import { NavbarFooter } from '@optimum-intelligence/opti-ui';
+import { DateTimePicker } from '@optimum-intelligence/opti-ui';
 ```
 
-### NavbarFooter.displayName
-
-## NavbarHeader
-
-compound · Layout
-
-Styled `<div>` (`.oui-navbar__header`). Accepts `className`, `style`, the `render` prop and all `<div>` attributes.
-
 ```tsx
-import { NavbarHeader } from '@optimum-intelligence/opti-ui';
+<DateTimePicker label="Departure" value={slot} onValueChange={setSlot} timeZone="Europe/Budapest" />
 ```
 
-### NavbarHeader.displayName
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| `step?` | `number` |  | Spacing of the time options in seconds (60 = every minute, 900 = quarter hours, 1 = every second). |
+| `defaultTime?` | `string` |  | Time (`"09:00"`) used when a day is picked before any time is set. |
+| `granularity?` | `'hour' \| 'minute' \| 'second'` | `'minute'` | Smallest unit shown and stored: `hour`, `minute` or `second`. When omitted, `second` if `step` is not a whole number of minutes, otherwise `minute`. |
 
-## NavbarItem
+Also accepts all props of: `PickerProps`.
 
-component · Layout
+## Dropzone
 
-Navigation link. Renders an `<a>`; use `render={<Link to="…" />}` for a
-router link or `render={<button />}` for an action.
+component · Forms
+
+Drop target that also opens the file browser on click, Enter or Space.
 
 ```tsx
-import { NavbarItem } from '@optimum-intelligence/opti-ui';
+import { Dropzone } from '@optimum-intelligence/opti-ui';
 ```
 
 | Prop | Type | Default | Description |
 | --- | --- | --- | --- |
-| `icon?` | `React.ReactNode` |  | Icon shown before the label; it stays visible when the navbar is collapsed to a rail. |
-| `active?` | `boolean` | `false` | Marks the current page (sets aria-current). |
-| `badge?` | `React.ReactNode` |  | Trailing content such as a count badge. |
-
-Also accepts all props of: `useRender.ComponentProps<'a', NavbarItemState>`.
-
-## NavbarSection
-
-compound · Layout
+| `ref?` | `React.Ref<HTMLLabelElement>` |  | Ref to the dropzone element. |
+| `onFiles?` | `(files: File[]) => void` |  | Called with the picked or dropped files that pass `accept` and `maxSize`. |
+| `onReject?` | `(rejections: FileRejection[]) => void` |  | Called with the files that were turned away, and why. |
+| `accept?` | `string` |  | Allowed types, as for `<input accept>`: `".pdf,image/*"`. |
+| `multiple?` | `boolean` |  | Allow choosing several files. |
+| `maxSize?` | `number` |  | Largest allowed file, in bytes. |
+| `files?` | `File[]` |  | The current selection. It is kept in the native input, so the files submit with a form and `required` validates. Without it the input is emptied after each pick. |
+| `disabled?` | `boolean` |  | Disables picking and dropping. |
+| `invalid?` | `boolean` |  | Shows the error styling. |
+| `size?` | `'sm' \| 'md'` | `'md'` | `sm` is a single compact row. |
+| `icon?` | `React.ReactNode` |  | Icon shown before the title. Defaults to an upload icon. |
+| `title?` | `React.ReactNode` |  | Main line. Defaults to "Drop files here or click to browse". |
+| `hint?` | `React.ReactNode` |  | Secondary line, e.g. the allowed types and size. |
+| `inputProps?` | `Omit<React.ComponentProps<'input'>, 'ref' \| 'type'>` |  | Props for the file input (name, id, required, aria-*…). |
 
-Styled `<div>` (`.oui-navbar__section`). Accepts `className`, `style`, the `render` prop and all `<div>` attributes.
+Also accepts all props of: `Omit<React.LabelHTMLAttributes<HTMLLabelElement>, 'title'>`.
+
+## Field
+
+compound · Forms
+
+Field parts wire up labels, descriptions and validation for any control
+inside (Input, Select, Checkbox, Switch, NumberField…).
 
 ```tsx
-import { NavbarSection } from '@optimum-intelligence/opti-ui';
+import { Field } from '@optimum-intelligence/opti-ui';
 ```
 
-### NavbarSection.displayName
+### Field.Root
 
-## NavbarSectionLabel
+### Field.Label
 
-compound · Layout
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| `required?` | `boolean` |  | Appends a required marker. |
 
-Styled `<div>` (`.oui-navbar__section-label`). Accepts `className`, `style`, the `render` prop and all `<div>` attributes.
+Also accepts all props of: `BaseField.Label.Props`.
+
+### Field.Description
+
+### Field.Error
+
+### Field.Item
+
+### Field.Validity
+
+Base UI `Field.Validity` re-exported unchanged. See https://base-ui.com/react/components/field.
+
+## Fieldset
+
+compound · Forms
+
+Groups related fields under a legend.
 
 ```tsx
-import { NavbarSectionLabel } from '@optimum-intelligence/opti-ui';
+import { Fieldset } from '@optimum-intelligence/opti-ui';
 ```
 
-### NavbarSectionLabel.displayName
+### Fieldset.Root
 
-## PageHeader
+### Fieldset.Legend
 
-component · Layout
+## FileItem
 
-Page title block with optional breadcrumbs, eyebrow, description and actions.
+component · Forms
+
+One file in a list: name, size, upload progress or error, and a remove button.
 
 ```tsx
-import { PageHeader } from '@optimum-intelligence/opti-ui';
+import { FileItem } from '@optimum-intelligence/opti-ui';
 ```
 
 | Prop | Type | Default | Description |
 | --- | --- | --- | --- |
-| `ref?` | `React.Ref<HTMLElement>` |  | Ref to the `<header>` element. |
-| `breadcrumbs?` | `React.ReactNode` |  | Trail shown above the title, usually `<Breadcrumbs>`. |
-| `eyebrow?` | `React.ReactNode` |  | Small label above the title. |
-| `title` | `React.ReactNode` |  | Page title, rendered as the page `<h1>`. |
-| `description?` | `React.ReactNode` |  | Supporting text under the title. |
-| `actions?` | `React.ReactNode` |  | Buttons or controls aligned to the right of the title. |
+| `ref?` | `React.Ref<HTMLDivElement>` |  | Ref to the item element. |
+| `name` | `string` |  | File name. |
+| `size?` | `number` |  | Size in bytes. |
+| `icon?` | `React.ReactNode` |  | Icon before the name. Defaults to a file icon. |
+| `status?` | `'idle' \| 'uploading' \| 'success' \| 'error'` | `'idle'` | Upload state; sets the progress bar and error styling. |
+| `progress?` | `number \| null` | `null` | Upload progress from 0 to 100, shown while `uploading`. `null` is indeterminate. |
+| `error?` | `React.ReactNode` |  | Message shown in place of the size when `status` is `error`. |
+| `onRemove?` | `() => void` |  | Adds the remove button. |
+| `removeLabel?` | `string` |  | Accessible name of the remove button. Defaults to "Remove {name}". |
+| `actions?` | `React.ReactNode` |  | Extra controls before the remove button (download, preview…). |
+| `locale?` | `string` |  | BCP 47 locale for the size. |
 
-Also accepts all props of: `Omit<React.HTMLAttributes<HTMLElement>, 'title'>`.
+Also accepts all props of: `React.HTMLAttributes<HTMLDivElement>`.
 
-## ScrollArea
+## FileUpload
 
-component · Layout
+component · Forms
 
-Scroll container with slim, themed overlay scrollbars. Set a height or max-height.
+File field: a dropzone plus the list of chosen files. It only collects
+`File` objects; upload them yourself and report progress through `fileState`.
 
 ```tsx
-import { ScrollArea } from '@optimum-intelligence/opti-ui';
+import { FileUpload } from '@optimum-intelligence/opti-ui';
 ```
 
 | Prop | Type | Default | Description |
 | --- | --- | --- | --- |
-| `scrollbars?` | `'vertical' \| 'horizontal' \| 'both'` | `'vertical'` | Which scrollbars to render. |
-| `viewportProps?` | `BaseScrollArea.Viewport.Props` |  | Props for the inner scrolling viewport, e.g. a `ref` to read the scroll position. |
+| `ref?` | `React.Ref<HTMLLabelElement>` |  | Ref to the dropzone element. |
+| `value?` | `File[]` |  | Chosen files (controlled). |
+| `defaultValue?` | `File[]` |  | Initially chosen files when uncontrolled. |
+| `onValueChange?` | `(files: File[]) => void` |  | Called with the full list of files after a file is added or removed. |
+| `maxFiles?` | `number` |  | Most files allowed when `multiple`. |
+| `fileState?` | `(file: File) => Pick<FileItemProps, 'status' \| 'progress' \| 'error'> \| undefined` |  | Upload state of a file, for showing progress and errors in the list. |
+| `label?` | `React.ReactNode` |  | Visible field label. |
+| `description?` | `React.ReactNode` |  | Help text under the dropzone. |
+| `error?` | `React.ReactNode` |  | Error message. When set, the field is marked invalid. |
+| `required?` | `boolean` |  | Requires at least one file before the form submits. |
+| `disabled?` | `boolean` |  | Disables picking, dropping and removing files. |
+| `name?` | `string` |  | Submits the files with a form under this name. |
+| `id?` | `string` |  | Id of the file input. Generated when omitted. |
+| `className?` | `string` |  | Class name for the root element. |
+| `locale?` | `string` |  | BCP 47 locale for file sizes. |
+| `labels?` | `Partial<FileUploadLabels>` |  | Override texts for localisation. |
 
-Also accepts all props of: `BaseScrollArea.Root.Props`.
+Also accepts all props of: `Pick<DropzoneProps, 'accept' \| 'multiple' \| 'maxSize' \| 'onReject' \| 'size' \| 'icon' \| 'title' \| 'hint'>`.
 
-## Separator
+## Form
 
-component · Layout
+component · Forms
 
-Thin divider line. Set `orientation="vertical"` for a vertical rule.
+Form with Base UI validation wiring and vertical field spacing.
 
 ```tsx
-import { Separator } from '@optimum-intelligence/opti-ui';
+import { Form } from '@optimum-intelligence/opti-ui';
 ```
 
 
-Also accepts all props of: `BaseSeparator.Props`.
+Also accepts all props of: `BaseForm.Props`.
 
-## Stack
+## formatDate
 
-component · Layout
+function · Forms
 
-Flex container that spaces its children evenly, in a column or a row.
+Formats a date or date-time the way the date pickers show it: ISO-style
+(`2026-03-09 14:30`) on a 24-hour clock by default, or with a custom `format`.
+Instants (`"2026-03-09T13:30:00Z"`) are shown in `timeZone`. Returns `""` for an invalid value.
 
 ```tsx
-import { Stack } from '@optimum-intelligence/opti-ui';
+import { formatDate } from '@optimum-intelligence/opti-ui';
 ```
 
-| Prop | Type | Default | Description |
-| --- | --- | --- | --- |
-| `direction?` | `'column' \| 'row'` | `'column'` | `column` (default) stacks children, `row` puts them on a line. |
-| `gap?` | `'none' \| 'xs' \| 'sm' \| 'md' \| 'lg' \| 'xl'` | `'md'` | Space between children. Override with `--oui-stack-gap`. |
-| `align?` | `'start' \| 'center' \| 'end' \| 'stretch' \| 'baseline'` |  | Cross-axis alignment. Defaults to `stretch` in a column and `center` in a row. |
-| `justify?` | `'start' \| 'center' \| 'end' \| 'between'` |  | Main-axis distribution. |
-| `wrap?` | `boolean` | `false` | Let a row's children wrap onto more lines. |
+Signature: `formatDate(value: string \| null \| undefined, options: FormatDateOptions = {})`
 
-Also accepts all props of: `useRender.ComponentProps<'div', StackState>`.
+```tsx
+formatDate('2026-03-09T13:30:00Z', { timeZone: 'Europe/Budapest' }); // "2026-03-09 14:30"
+formatDate('2026-03-01', { granularity: 'month', format: 'MMMM YYYY', locale: 'en' }); // "March 2026"
+```
 
-## StatCard
+## formatFileSize
 
-component · Layout
+function · Forms
 
-KPI tile: label, large value, optional unit and trend.
+`1536` → `"1.5 KB"`.
 
 ```tsx
-import { StatCard } from '@optimum-intelligence/opti-ui';
+import { formatFileSize } from '@optimum-intelligence/opti-ui';
 ```
 
-| Prop | Type | Default | Description |
-| --- | --- | --- | --- |
-| `variant?` | `'outlined' \| 'elevated' \| 'filled' \| 'ghost'` |  | `outlined` (default) uses the card border, `elevated` a soft shadow. |
-| `padding?` | `'none' \| 'sm' \| 'md' \| 'lg'` |  | Inner spacing. Override with `--oui-card-padding`. |
-| `interactive?` | `boolean` |  | Adds hover and focus states — use with `render={<a href=… />}` or a click handler. |
-| `label` | `React.ReactNode` |  | What the number measures. |
-| `value` | `React.ReactNode` |  | The headline figure. |
-| `unit?` | `React.ReactNode` |  | Unit beside the value, e.g. "kWh" or "orders". |
-| `delta?` | `React.ReactNode` |  | Change indicator, e.g. "+12.4%". |
-| `trend?` | `'up' \| 'down' \| 'flat'` |  | Arrow direction shown next to `delta`. |
-| `tone?` | `'positive' \| 'negative' \| 'neutral'` |  | Color of the delta. Defaults to positive for `up`, negative for `down`. |
-| `hint?` | `React.ReactNode` |  | Supporting text under the value. |
-| `icon?` | `React.ReactNode` |  | Icon tile shown in the top-right corner. |
-| `loading?` | `boolean` |  | Replaces the value with a skeleton while data loads. |
-
-Also accepts all props of: `useRender.ComponentProps<'div', CardState>`.
-
-# Typography
+Signature: `formatFileSize(bytes: number, locale?: string)`
 
-## Eyebrow
+## Input
 
-component · Typography
+component · Forms
 
-Small uppercase label used above titles, in filter bars and table headers.
+Text input, optionally with `startAdornment` / `endAdornment` inside the box. Use `TextField` for a labelled one.
 
 ```tsx
-import { Eyebrow } from '@optimum-intelligence/opti-ui';
+import { Input } from '@optimum-intelligence/opti-ui';
 ```
 
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| `size?` | `'sm' \| 'md' \| 'lg'` | `'md'` | Control height. |
+| `startAdornment?` | `React.ReactNode` |  | Icon or text rendered inside the box, before the value. |
+| `endAdornment?` | `React.ReactNode` |  | Icon, text or button rendered inside the box, after the value. |
 
-Also accepts all props of: `useRender.ComponentProps<'span'>`.
+Also accepts all props of: `Omit<BaseInput.Props, 'size'>`.
 
-## Heading
+## NumberField
 
-component · Typography
+component · Forms
 
-Heading element. `level` sets the tag (`h1`–`h6`) and the default size; `size` overrides only the look.
+Numeric input with stepper buttons, locale formatting and keyboard stepping.
 
 ```tsx
-import { Heading } from '@optimum-intelligence/opti-ui';
+import { NumberField } from '@optimum-intelligence/opti-ui';
 ```
 
 | Prop | Type | Default | Description |
 | --- | --- | --- | --- |
-| `level?` | `HeadingLevel` | `2` | Semantic level; picks the element. |
-| `size?` | `'xs' \| 'sm' \| 'md' \| 'lg' \| 'xl' \| '2xl'` |  | Visual size, independent of the level. |
+| `label?` | `React.ReactNode` |  | Visible field label. |
+| `description?` | `React.ReactNode` |  | Help text under the input. |
+| `error?` | `React.ReactNode` |  | Error message. When set, the field is marked invalid. |
+| `size?` | `'sm' \| 'md' \| 'lg'` | `'md'` | Control height. |
+| `placeholder?` | `string` |  | Placeholder shown while empty. |
+| `hideStepper?` | `boolean` |  | Hide the − / + stepper buttons. |
+| `decrementLabel?` | `string` | `'Decrease'` | Accessible name of the − button. |
+| `incrementLabel?` | `string` | `'Increase'` | Accessible name of the + button. |
 
-Also accepts all props of: `useRender.ComponentProps<'h2', HeadingState>`.
+Also accepts all props of: `BaseNumberField.Root.Props`.
 
-## Link
+## PasswordField
 
-component · Typography
+component · Forms
 
-Text link. Pass a router link through `render`: `<Link render={<NavLink to="/fleet" />}>`.
+Labelled password input with description and error message.
 
 ```tsx
-import { Link } from '@optimum-intelligence/opti-ui';
+import { PasswordField } from '@optimum-intelligence/opti-ui';
 ```
 
 | Prop | Type | Default | Description |
 | --- | --- | --- | --- |
-| `tone?` | `'accent' \| 'muted' \| 'inherit'` | `'accent'` | `inherit` takes the color of the surrounding text. |
-| `underline?` | `'always' \| 'hover' \| 'none'` | `'always'` | When the underline shows. |
-| `external?` | `boolean` | `false` | Opens in a new tab, with a trailing icon. |
+| `size?` | `'sm' \| 'md' \| 'lg'` |  | Control height. |
+| `startAdornment?` | `React.ReactNode` |  | Icon or text rendered inside the box, before the value. |
+| `visible?` | `boolean` |  | Whether the value is shown as plain text. |
+| `defaultVisible?` | `boolean` |  | Initial visibility when uncontrolled. |
+| `onVisibleChange?` | `(visible: boolean) => void` |  | Called when the user toggles visibility. |
+| `toggleLabel?` | `string` |  | Accessible name of the show/hide button. |
 
-Also accepts all props of: `useRender.ComponentProps<'a', LinkState>`.
+Also accepts all props of: `Omit<BaseInput.Props, 'size'>`, `FieldShellProps`.
 
-## Text
+## PasswordInput
 
-component · Typography
+component · Forms
 
-Body text paragraph. Use `render={<span />}` for inline text.
+Password input with a button that reveals the value.
 
 ```tsx
-import { Text } from '@optimum-intelligence/opti-ui';
+import { PasswordInput } from '@optimum-intelligence/opti-ui';
 ```
 
 | Prop | Type | Default | Description |
 | --- | --- | --- | --- |
-| `size?` | `'xs' \| 'sm' \| 'md' \| 'lg'` | `'md'` | Font size. |
-| `tone?` | `'default' \| 'strong' \| 'muted' \| 'subtle' \| 'accent' \| 'success' \| 'warning' \| 'danger'` | `'default'` | Color role: from `strong` to `subtle`, or a status color. |
-| `weight?` | `'regular' \| 'medium' \| 'semibold' \| 'bold'` |  | Font weight. Inherits when omitted. |
-
-Also accepts all props of: `useRender.ComponentProps<'p', TextState>`.
+| `size?` | `'sm' \| 'md' \| 'lg'` |  | Control height. |
+| `startAdornment?` | `React.ReactNode` |  | Icon or text rendered inside the box, before the value. |
+| `visible?` | `boolean` |  | Whether the value is shown as plain text. |
+| `defaultVisible?` | `boolean` | `false` | Initial visibility when uncontrolled. |
+| `onVisibleChange?` | `(visible: boolean) => void` |  | Called when the user toggles visibility. |
+| `toggleLabel?` | `string` | `'Show password'` | Accessible name of the show/hide button. |
 
-# Actions
+Also accepts all props of: `Omit<BaseInput.Props, 'size'>`.
 
-## Button
+## Radio
 
-component · Actions
+component · Forms
 
-Action button. Use `render={<a href="…" />}` with `nativeButton={false}` to style a link as a button.
+Radio button with optional `label` and `description`. Use inside `RadioGroup`; each needs a `value`.
 
 ```tsx
-import { Button } from '@optimum-intelligence/opti-ui';
+import { Radio } from '@optimum-intelligence/opti-ui';
 ```
 
-```tsx
-<Button variant="secondary" loading={saving} onClick={save}>Save</Button>
-```
 
-| Prop | Type | Default | Description |
-| --- | --- | --- | --- |
-| `variant?` | `'primary' \| 'accent' \| 'secondary' \| 'soft' \| 'ghost' \| 'danger'` | `'primary'` | Visual emphasis. |
-| `size?` | `'sm' \| 'md' \| 'lg'` | `'md'` | Height and padding. |
-| `shape?` | `'pill' \| 'rounded'` | `'pill'` | `pill` (default) or `rounded` corners. Override with `--oui-button-radius`. |
-| `fullWidth?` | `boolean` |  | Stretch to the container width. |
-| `loading?` | `boolean` |  | Shows a spinner and blocks interaction while keeping focus. |
-
-Also accepts all props of: `BaseButton.Props`.
+Also accepts all props of: `BaseRadio.Root.Props`, `ChoiceLabelProps`.
 
-## ContextMenu
+## RadioGroup
 
-compound · Actions
+component · Forms
 
-Menu opened by right click or long press on `ContextMenu.Trigger`, which wraps
-the target area. The item parts are the same as `Menu`'s.
+Single-choice group for `Radio` children (`value` / `onValueChange`).
 
 ```tsx
-import { ContextMenu } from '@optimum-intelligence/opti-ui';
+import { RadioGroup } from '@optimum-intelligence/opti-ui';
 ```
 
-### ContextMenu.Root
-
-Base UI `ContextMenu.Root` re-exported unchanged. See https://base-ui.com/react/components/context-menu.
-
-### ContextMenu.Trigger
-
-Base UI `ContextMenu.Trigger` re-exported unchanged. See https://base-ui.com/react/components/context-menu.
-
-### ContextMenu.Content
-
 | Prop | Type | Default | Description |
 | --- | --- | --- | --- |
-| `positionerProps?` | `BaseContextMenu.Positioner.Props` |  | Props for the positioner element that places the popup. |
-
-Also accepts all props of: `BaseContextMenu.Popup.Props`.
-
-### ContextMenu.Item
-
-### ContextMenu.LinkItem
-
-### ContextMenu.CheckboxItem
+| `orientation?` | `'vertical' \| 'horizontal'` | `'vertical'` | Layout direction of the radios. |
 
-### ContextMenu.RadioGroup
+Also accepts all props of: `BaseRadioGroup.Props`.
 
-### ContextMenu.RadioItem
+## RangeCalendar
 
-### ContextMenu.Group
+component · Forms
 
-### ContextMenu.GroupLabel
+Month grid for picking a range of days: the first pick sets one end, the
+second completes the range (in either order). Same keyboard as Calendar.
+Disabled days cannot be picked as an end but may fall inside a range.
 
-### ContextMenu.Separator
+```tsx
+import { RangeCalendar } from '@optimum-intelligence/opti-ui';
+```
 
-### ContextMenu.SubmenuRoot
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| `value?` | `DateRange \| null` |  | Selected days as ISO dates; both ends are inclusive. With a month or year `granularity`, each end is the 1st day of its month or year. |
+| `defaultValue?` | `DateRange \| null` | `null` | Initially selected range when uncontrolled. |
+| `onValueChange?` | `(value: DateRange) => void` |  | Called once both ends are picked, with `start` on or before `end`. |
 
-### ContextMenu.SubmenuTrigger
+Also accepts all props of: `CalendarOptions`.
 
-## IconButton
+## SearchInput
 
-component · Actions
+component · Forms
 
-Square button for a single icon. Defaults to the compact ghost style.
+Text input with a search icon and a clear button that appears once there is a value.
 
 ```tsx
-import { IconButton } from '@optimum-intelligence/opti-ui';
+import { SearchInput } from '@optimum-intelligence/opti-ui';
 ```
 
 | Prop | Type | Default | Description |
 | --- | --- | --- | --- |
-| `variant?` | `'primary' \| 'accent' \| 'secondary' \| 'soft' \| 'ghost' \| 'danger'` | `'ghost'` | Visual emphasis. |
-| `size?` | `'sm' \| 'md' \| 'lg'` | `'md'` | Height and padding. |
-| `loading?` | `boolean` |  | Shows a spinner and blocks interaction while keeping focus. |
-| `aria-label` | `string` |  | Required: icon-only buttons need an accessible name. |
-| `shape?` | `'rounded' \| 'circle'` | `'rounded'` | `rounded` square (default) or `circle`. |
+| `size?` | `'sm' \| 'md' \| 'lg'` |  | Control height. |
+| `value?` | `string` |  | Current text (controlled). |
+| `defaultValue?` | `string` | `''` | Initial text when uncontrolled. |
+| `onValueChange?` | `(value: string) => void` |  | Called with the new text on typing and with `''` on clear. |
+| `clearLabel?` | `string` | `'Clear search'` | Accessible name of the clear button. |
+| `icon?` | `React.ReactNode` |  | Replaces the leading search icon. |
 
-Also accepts all props of: `BaseButton.Props`.
+Also accepts all props of: `Omit<BaseInput.Props, 'size'>`.
 
-## Menu
+## Select
 
-compound · Actions
+compound · Forms
 
-Dropdown menu of actions. Compose `Menu.Root` › `Menu.Trigger` + `Menu.Content` › items.
-For nested menus use `Menu.SubmenuRoot` › `Menu.SubmenuTrigger` + `Menu.Content`.
+`<Select items={…} />` renders a complete labelled select. For full control
+compose the parts: `Select.Root`, `Select.Trigger`, `Select.Content`,
+`Select.Item`, `Select.Group`, `Select.GroupLabel`, `Select.Separator`.
 
 ```tsx
-import { Menu } from '@optimum-intelligence/opti-ui';
+import { Select } from '@optimum-intelligence/opti-ui';
 ```
 
-### Menu.Root
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| `items` | `Array<SelectOption \| SelectOptionGroup>` |  | Options, or groups of options. |
+| `label?` | `React.ReactNode` |  | Visible field label. |
+| `description?` | `React.ReactNode` |  | Help text under the trigger. |
+| `error?` | `React.ReactNode` |  | Error message. When set, the field is marked invalid. |
+| `placeholder?` | `React.ReactNode` | `'Select…'` | Text shown while nothing is selected. |
+| `size?` | `'sm' \| 'md' \| 'lg'` | `'md'` | Control height. |
+| `triggerProps?` | `Omit<SelectTriggerProps, 'size' \| 'placeholder'>` |  | Props passed to the trigger button (className, style, aria-*). |
+| `contentProps?` | `Omit<SelectContentProps, 'children'>` |  | Props for the popup (side, align, className…). |
 
-Base UI `Menu.Root` re-exported unchanged. See https://base-ui.com/react/components/menu.
+Also accepts all props of: `RootProps`.
 
-### Menu.Trigger
+### Select.Root
 
-Base UI `Menu.Trigger` re-exported unchanged. See https://base-ui.com/react/components/menu.
+Base UI `Select.Root` re-exported unchanged. See https://base-ui.com/react/components/select.
 
-### Menu.Content
+### Select.Label
+
+### Select.Trigger
+
+The select button. Renders the value and chevron unless children are given.
 
 | Prop | Type | Default | Description |
 | --- | --- | --- | --- |
-| `side?` | `BaseMenu.Positioner.Props['side']` |  | Which side of the trigger the menu opens on. |
-| `align?` | `BaseMenu.Positioner.Props['align']` | `'start'` | Alignment along that side. |
-| `sideOffset?` | `BaseMenu.Positioner.Props['sideOffset']` | `6` | Distance from the trigger in px. |
-| `alignOffset?` | `BaseMenu.Positioner.Props['alignOffset']` |  | Shift along the alignment axis in px. |
-| `positionerProps?` | `BaseMenu.Positioner.Props` |  | Props for the positioner element that places the popup. |
-
-Also accepts all props of: `BaseMenu.Popup.Props`.
+| `size?` | `'sm' \| 'md' \| 'lg'` | `'md'` | Control height. |
+| `placeholder?` | `React.ReactNode` |  | Placeholder shown by the default value slot. |
 
-### Menu.Item
+Also accepts all props of: `BaseSelect.Trigger.Props`.
 
+### Select.Value
 
-Also accepts all props of: `BaseMenu.Item.Props`, `ItemExtras`.
+### Select.Content
 
-### Menu.LinkItem
+Portal + positioner + popup + list in one.
 
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| `side?` | `BaseSelect.Positioner.Props['side']` |  | Which side of the trigger the list opens on. |
+| `align?` | `BaseSelect.Positioner.Props['align']` |  | Alignment along that side. |
+| `sideOffset?` | `BaseSelect.Positioner.Props['sideOffset']` | `6` | Distance from the trigger in px. |
+| `alignItemWithTrigger?` | `boolean` | `false` | Overlap the trigger so the selected item lines up with it (macOS style). |
+| `positionerProps?` | `BaseSelect.Positioner.Props` |  | Props for the positioner element that places the popup. |
 
-Also accepts all props of: `BaseMenu.LinkItem.Props`, `Omit<ItemExtras, 'danger'>`.
+Also accepts all props of: `BaseSelect.Popup.Props`.
 
-### Menu.CheckboxItem
+### Select.Item
 
+### Select.Group
 
-Also accepts all props of: `BaseMenu.CheckboxItem.Props`, `Omit<ItemExtras, 'icon' \| 'danger'>`.
+### Select.GroupLabel
 
-### Menu.RadioGroup
+### Select.Separator
 
-Base UI `Menu.RadioGroup` re-exported unchanged. See https://base-ui.com/react/components/menu.
+## Slider
 
-### Menu.RadioItem
+component · Forms
 
+Single value or range (pass an array) slider.
 
-Also accepts all props of: `BaseMenu.RadioItem.Props`, `Omit<ItemExtras, 'icon' \| 'danger'>`.
+```tsx
+import { Slider } from '@optimum-intelligence/opti-ui';
+```
 
-### Menu.Group
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| `label?` | `React.ReactNode` |  | Visible label above the track. |
+| `showValue?` | `boolean` |  | Show the formatted value next to the label. |
+| `thumbLabels?` | `string[]` |  | Accessible labels for each thumb (needed for range sliders). |
 
-Base UI `Menu.Group` re-exported unchanged. See https://base-ui.com/react/components/menu.
+Also accepts all props of: `BaseSlider.Root.Props`.
 
-### Menu.GroupLabel
+## Switch
 
-### Menu.Separator
+component · Forms
 
-### Menu.SubmenuRoot
+On/off switch with optional `label` and `description`.
 
-Base UI `Menu.SubmenuRoot` re-exported unchanged. See https://base-ui.com/react/components/menu.
+```tsx
+import { Switch } from '@optimum-intelligence/opti-ui';
+```
 
-### Menu.SubmenuTrigger
+```tsx
+<Switch label="Email alerts" checked={on} onCheckedChange={setOn} />
+```
 
 
-Also accepts all props of: `BaseMenu.SubmenuTrigger.Props`, `Omit<ItemExtras, 'shortcut' \| 'danger'>`.
+Also accepts all props of: `BaseSwitch.Root.Props`, `ChoiceLabelProps`.
 
-## SegmentedControl
+## Textarea
 
-component · Actions
+component · Forms
 
-Single-choice switcher (e.g. Day / Week / Month). Always keeps one value selected.
+Multi-line text input. Use `TextareaField` for a labelled one.
 
 ```tsx
-import { SegmentedControl } from '@optimum-intelligence/opti-ui';
+import { Textarea } from '@optimum-intelligence/opti-ui';
 ```
 
 | Prop | Type | Default | Description |
 | --- | --- | --- | --- |
-| `size?` | `'sm' \| 'md'` | `'md'` | Segment height. |
-| `variant?` | `'segmented' \| 'outline'` |  | `segmented` renders a pill track like a tab switcher; `outline` separate buttons. |
-| `fullWidth?` | `boolean` |  | Stretch segments to fill the width. |
-| `options` | `SegmentedControlOption[]` |  | Segments to show. |
-| `value?` | `string` |  | Selected option `value` (controlled). |
-| `defaultValue?` | `string` |  | Initially selected option `value` when uncontrolled. |
-| `onValueChange?` | `(value: string) => void` |  | Called with the new `value` when the selection changes. |
+| `ref?` | `React.Ref<HTMLTextAreaElement>` |  | Ref to the `<textarea>`. |
+| `autoResize?` | `boolean` |  | Grow with content up to `maxRows` (uses CSS field-sizing where supported). |
 
-Also accepts all props of: `BaseToggleGroup.Props`.
+Also accepts all props of: `React.TextareaHTMLAttributes<HTMLTextAreaElement>`.
 
-## Toggle
+## TextareaField
 
-component · Actions
+component · Forms
 
-Two-state button (bold, pin, favourite…). Inside a ToggleGroup it acts as a segment.
+Labelled textarea with description and error message.
 
 ```tsx
-import { Toggle } from '@optimum-intelligence/opti-ui';
+import { TextareaField } from '@optimum-intelligence/opti-ui';
 ```
 
 | Prop | Type | Default | Description |
 | --- | --- | --- | --- |
-| `size?` | `'sm' \| 'md'` | `'md'` | Button height. |
+| `ref?` | `React.Ref<HTMLTextAreaElement>` |  | Ref to the `<textarea>`. |
+| `autoResize?` | `boolean` |  | Grow with content up to `maxRows` (uses CSS field-sizing where supported). |
 
-Also accepts all props of: `BaseToggle.Props`.
+Also accepts all props of: `React.TextareaHTMLAttributes<HTMLTextAreaElement>`, `FieldShellProps`.
 
-## ToggleGroup
+## TextField
 
-component · Actions
+component · Forms
 
-Group of `Toggle` buttons that share selection state (single or multiple).
+Labelled input with description and error message.
 
 ```tsx
-import { ToggleGroup } from '@optimum-intelligence/opti-ui';
+import { TextField } from '@optimum-intelligence/opti-ui';
 ```
 
 | Prop | Type | Default | Description |
 | --- | --- | --- | --- |
-| `size?` | `'sm' \| 'md'` | `'md'` | Segment height. |
-| `variant?` | `'segmented' \| 'outline'` | `'segmented'` | `segmented` renders a pill track like a tab switcher; `outline` separate buttons. |
-| `fullWidth?` | `boolean` |  | Stretch segments to fill the width. |
+| `size?` | `'sm' \| 'md' \| 'lg'` |  | Control height. |
+| `startAdornment?` | `React.ReactNode` |  | Icon or text rendered inside the box, before the value. |
+| `endAdornment?` | `React.ReactNode` |  | Icon, text or button rendered inside the box, after the value. |
 
-Also accepts all props of: `BaseToggleGroup.Props`.
+Also accepts all props of: `Omit<BaseInput.Props, 'size'>`, `FieldShellProps`.
 
-## Toolbar
+## useDateConfig
 
-compound · Actions
+hook · Forms
 
-Row of controls that is a single tab stop; arrow keys move between them.
-Other controls join through `render`: `<Toolbar.Button render={<Toggle />} />`,
-`<Toolbar.Button render={<Menu.Trigger />} />`.
+The date settings from the nearest `DateConfigProvider`. Spread it into
+`formatDate` options to format dates the same way the pickers do.
 
 ```tsx
-import { Toolbar } from '@optimum-intelligence/opti-ui';
+import { useDateConfig } from '@optimum-intelligence/opti-ui';
 ```
 
-### Toolbar.Root
-
-### Toolbar.Button
+Signature: `useDateConfig()`
 
-### Toolbar.Link
-
-### Toolbar.Group
-
-### Toolbar.Separator
+```tsx
+const config = useDateConfig();
+return <span>{formatDate(order.createdAt, { ...config, granularity: 'minute' })}</span>;
+```
 
-### Toolbar.Input
+# Layout
 
-# Forms
+## AppShell
 
-## Calendar
+component · Layout
 
-component · Forms
+Full-height layout with a fixed navbar and an internally scrolling main
+area. Below 900px the navbar moves into a slide-in drawer, and `NavbarItem`s marked `pinned` show in a
+tab bar (see `mobileNavPosition`).
+Customize width with `--oui-navbar-width` and `--oui-navbar-collapsed-width`.
 
-Month grid for picking one day. Keyboard: arrows move by day / week,
-Home / End jump within the week, PageUp / PageDown change month (with Shift: year).
-The month and year in the title open a list to jump straight to another one.
+```tsx
+import { AppShell } from '@optimum-intelligence/opti-ui';
+```
 
 ```tsx
-import { Calendar } from '@optimum-intelligence/opti-ui';
+<AppShell
+  mobileBrand="OptiControl"
+  navbar={
+    <Navbar>
+      <NavbarSection>
+        <NavbarItem href="/" icon={<Home />} active pinned>Overview</NavbarItem>
+        <NavbarItem href="/fleet" icon={<Truck />} pinned>Fleet</NavbarItem>
+      </NavbarSection>
+    </Navbar>
+  }
+>
+  <PageHeader title="Overview" />
+</AppShell>
 ```
 
 | Prop | Type | Default | Description |
 | --- | --- | --- | --- |
-| `value?` | `string \| null` |  | Selected day as an ISO date (`"2026-03-09"`). |
-| `defaultValue?` | `string \| null` | `null` | Initially selected day (ISO date) when uncontrolled. |
-| `onValueChange?` | `(value: string) => void` |  | Called with the picked day as an ISO date. |
+| `ref?` | `React.Ref<HTMLDivElement>` |  | Ref to the shell's root element. |
+| `navbar` | `React.ReactNode` |  | Navbar content (usually a `<Navbar>`). Rendered in a drawer on small screens. |
+| `mobileBrand?` | `React.ReactNode` |  | Brand shown in the mobile top bar. |
+| `mobileActions?` | `React.ReactNode` |  | Extra content on the right of the mobile top bar. |
+| `mobileNavPosition?` | `'bottom' \| 'top'` | `'bottom'` | Where small screens show the tab bar of pinned `NavbarItem`s: below or above the main area. Both look the same; the "More" slot (see `moreTabPosition`) opens the navbar drawer. The top bar with `mobileBrand` and `mobileActions` only appears when one of them is set. Without pinned items, a top bar with a menu button is shown instead. |
+| `menuLabel?` | `string` | `'Open navigation'` | Accessible name of the button that opens the navigation drawer on small screens. |
+| `moreLabel?` | `string` | `'More'` | Label of the tab-bar slot that opens the navigation drawer. |
+| `moreTabPosition?` | `'start' \| 'end'` | `'start'` | Whether the "More" slot comes before or after the pinned items in the tab bar. |
+| `mainProps?` | `React.HTMLAttributes<HTMLElement>` |  | Props for the scrolling `<main>` element. |
 
-Also accepts all props of: `CalendarOptions`.
+Also accepts all props of: `React.HTMLAttributes<HTMLDivElement>`.
 
-## Checkbox
+## Card
 
-component · Forms
+component · Layout
 
-Checkbox with optional `label` and `description`. Supports `indeterminate`.
+Surface that groups related content. Compose with `CardHeader` (`CardTitle`, `CardDescription`,
+`CardActions`), `CardContent` and `CardFooter`.
 
 ```tsx
-import { Checkbox } from '@optimum-intelligence/opti-ui';
+import { Card } from '@optimum-intelligence/opti-ui';
 ```
 
+```tsx
+<Card variant="elevated">
+  <CardHeader>
+    <CardTitle>Monthly energy</CardTitle>
+    <CardDescription>Last 30 days</CardDescription>
+  </CardHeader>
+  <CardContent>…</CardContent>
+</Card>
+```
 
-Also accepts all props of: `BaseCheckbox.Root.Props`, `ChoiceLabelProps`.
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| `variant?` | `'outlined' \| 'elevated' \| 'filled' \| 'ghost'` | `'outlined'` | `outlined` (default) uses the card border, `elevated` a soft shadow. |
+| `padding?` | `'none' \| 'sm' \| 'md' \| 'lg'` | `'md'` | Inner spacing. Override with `--oui-card-padding`. |
+| `interactive?` | `boolean` | `false` | Adds hover and focus states — use with `render={<a href=… />}` or a click handler. |
 
-## CheckboxGroup
+Also accepts all props of: `useRender.ComponentProps<'div', CardState>`.
 
-component · Forms
+## CardActions
 
-Manages the checked values of several `Checkbox` children (`value` / `onValueChange`).
+compound · Layout
+
+Right-aligned slot inside CardHeader for icon buttons or menus.
 
 ```tsx
-import { CheckboxGroup } from '@optimum-intelligence/opti-ui';
+import { CardActions } from '@optimum-intelligence/opti-ui';
 ```
 
-| Prop | Type | Default | Description |
-| --- | --- | --- | --- |
-| `orientation?` | `'vertical' \| 'horizontal'` | `'vertical'` | Layout direction of the checkboxes. |
-
-Also accepts all props of: `BaseCheckboxGroup.Props`.
+### CardActions.displayName
 
-## Combobox
+## CardContent
 
-compound · Forms
+compound · Layout
 
-Searchable select. `<Combobox items={…} />` covers single and `multiple`
-(chips) selection; compose the parts for anything custom.
+Styled `<div>` (`.oui-card__content`). Accepts `className`, `style`, the `render` prop and all `<div>` attributes.
 
 ```tsx
-import { Combobox } from '@optimum-intelligence/opti-ui';
+import { CardContent } from '@optimum-intelligence/opti-ui';
 ```
 
-| Prop | Type | Default | Description |
-| --- | --- | --- | --- |
-| `items` | `ComboboxOption[]` |  | Options to choose from. |
-| `label?` | `React.ReactNode` |  | Visible field label. |
-| `description?` | `React.ReactNode` |  | Help text under the input. |
-| `error?` | `React.ReactNode` |  | Error message. When set, the field is marked invalid. |
-| `placeholder?` | `string` |  | Placeholder shown while nothing is typed or selected. |
-| `emptyText?` | `React.ReactNode` | `'No results found.'` | Shown when the filter matches nothing. |
-| `size?` | `'sm' \| 'md' \| 'lg'` | `'md'` | Control height. |
-| `hideClear?` | `boolean` |  | Hide the clear button. |
-| `inputProps?` | `BaseCombobox.Input.Props` |  | Props for the text input. |
+### CardContent.displayName
 
-Also accepts all props of: `RootProps`.
+## CardDescription
 
-### Combobox.Root
+compound · Layout
 
-Base UI `Combobox.Root` re-exported unchanged. See https://base-ui.com/react/components/combobox.
+Styled `<p>` (`.oui-card__description`). Accepts `className`, `style`, the `render` prop and all `<p>` attributes.
 
-### Combobox.InputGroup
+```tsx
+import { CardDescription } from '@optimum-intelligence/opti-ui';
+```
 
-| Prop | Type | Default | Description |
-| --- | --- | --- | --- |
-| `size?` | `'sm' \| 'md' \| 'lg'` | `'md'` | Control height. |
+### CardDescription.displayName
 
-Also accepts all props of: `BaseCombobox.InputGroup.Props`.
+## CardFooter
 
-### Combobox.Input
+compound · Layout
 
-### Combobox.Trigger
+Styled `<div>` (`.oui-card__footer`). Accepts `className`, `style`, the `render` prop and all `<div>` attributes.
 
-### Combobox.Clear
+```tsx
+import { CardFooter } from '@optimum-intelligence/opti-ui';
+```
 
-### Combobox.Value
+### CardFooter.displayName
 
-Base UI `Combobox.Value` re-exported unchanged. See https://base-ui.com/react/components/combobox.
+## CardHeader
 
-### Combobox.Chips
+compound · Layout
 
-### Combobox.Chip
+Styled `<div>` (`.oui-card__header`). Accepts `className`, `style`, the `render` prop and all `<div>` attributes.
 
-### Combobox.Content
+```tsx
+import { CardHeader } from '@optimum-intelligence/opti-ui';
+```
 
-| Prop | Type | Default | Description |
-| --- | --- | --- | --- |
-| `side?` | `BaseCombobox.Positioner.Props['side']` |  | Which side of the input the list opens on. |
-| `align?` | `BaseCombobox.Positioner.Props['align']` |  | Alignment along that side. |
-| `sideOffset?` | `BaseCombobox.Positioner.Props['sideOffset']` | `6` | Distance from the input in px. |
-| `positionerProps?` | `BaseCombobox.Positioner.Props` |  | Props for the positioner element that places the popup. |
+### CardHeader.displayName
 
-Also accepts all props of: `BaseCombobox.Popup.Props`.
+## CardTitle
 
-### Combobox.List
+compound · Layout
 
-### Combobox.Item
+Styled `<h3>` (`.oui-card__title`). Accepts `className`, `style`, the `render` prop and all `<h3>` attributes.
 
-### Combobox.Empty
+```tsx
+import { CardTitle } from '@optimum-intelligence/opti-ui';
+```
 
-### Combobox.Group
+### CardTitle.displayName
 
-Base UI `Combobox.Group` re-exported unchanged. See https://base-ui.com/react/components/combobox.
+## Grid
 
-### Combobox.GroupLabel
+component · Layout
 
-### Combobox.Collection
+Responsive dashboard grid.
 
-Base UI `Combobox.Collection` re-exported unchanged. See https://base-ui.com/react/components/combobox.
+```tsx
+import { Grid } from '@optimum-intelligence/opti-ui';
+```
 
-### Combobox.useFilter
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| `ref?` | `React.Ref<HTMLDivElement>` |  | Ref to the grid element. |
+| `columns?` | `1 \| 2 \| 3 \| 4 \| 5 \| 6` | `3` | Columns on wide screens; collapses to 2 below 1200px (for 4+) and 1 below 900px. |
+| `gap?` | `'sm' \| 'md' \| 'lg'` | `'md'` | Space between grid cells. |
 
-Base UI `Combobox.useFilter` re-exported unchanged. See https://base-ui.com/react/components/combobox.
+Also accepts all props of: `React.HTMLAttributes<HTMLDivElement>`.
 
-## DatePicker
+## Navbar
 
-component · Forms
+component · Layout
 
-Date field with a calendar popover. Values are ISO dates (`"2026-03-09"`),
-the same format as `<input type="date">`, and are shown the same way.
+Collapsible side navigation. Use inside `AppShell`. Compose with `NavbarHeader` (`NavbarBrand`),
+`NavbarSection` (`NavbarSectionLabel`, `NavbarItem`) and `NavbarFooter`.
 
 ```tsx
-import { DatePicker } from '@optimum-intelligence/opti-ui';
+import { Navbar } from '@optimum-intelligence/opti-ui';
 ```
 
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| `variant?` | `'inverse' \| 'surface'` | `'inverse'` | `inverse` (brand-colored, default) or `surface` (light panel). |
+| `collapsible?` | `boolean` | `true` | Shows a toggle in the top right that shrinks the navbar to an icon rail. Defaults to `true`. |
+| `collapsed?` | `boolean` |  | Controlled collapsed state. |
+| `defaultCollapsed?` | `boolean` | `false` | Initial collapsed state when uncontrolled. |
+| `onCollapsedChange?` | `(collapsed: boolean) => void` |  | Called when the user collapses or expands the navbar. |
+| `expandOnHover?` | `boolean` | `true` | Temporarily opens a collapsed navbar while the mouse is over it. Defaults to `true`. |
+| `collapseLabel?` | `string` | `'Collapse'` | Accessible names for the icon-only toggle. |
+| `expandLabel?` | `string` | `'Expand'` | Accessible name of the toggle while collapsed. |
 
-Also accepts all props of: `PickerProps`.
+Also accepts all props of: `useRender.ComponentProps<'nav', NavbarState>`.
 
-## DateRangePicker
+## NavbarBrand
 
-component · Forms
+component · Layout
 
-Date range field with a calendar popover and optional presets. Values are
-`{ start, end }` ISO dates (`"2026-03-09"`), both inclusive.
+Logo, title and subtitle block for the top of a `Navbar`.
 
 ```tsx
-import { DateRangePicker } from '@optimum-intelligence/opti-ui';
+import { NavbarBrand } from '@optimum-intelligence/opti-ui';
 ```
 
 | Prop | Type | Default | Description |
 | --- | --- | --- | --- |
-| `ref?` | `React.Ref<HTMLButtonElement>` |  | Ref to the trigger button. |
-| `label?` | `React.ReactNode` |  | Visible field label. |
-| `description?` | `React.ReactNode` |  | Help text under the field. |
-| `error?` | `React.ReactNode` |  | Error message. When set, the field is marked invalid. |
-| `required?` | `boolean` |  | Marks the field required and adds the required indicator to the label. |
-| `disabled?` | `boolean` |  | Disables the field. |
-| `placeholder?` | `React.ReactNode` | `'Select dates'` | Text shown while no date is selected. |
-| `size?` | `'sm' \| 'md' \| 'lg'` |  | Control height. |
-| `open?` | `boolean` |  | Whether the calendar popover is open (controlled). |
-| `defaultOpen?` | `boolean` |  | Initial popover state when uncontrolled. |
-| `onOpenChange?` | `(open: boolean) => void` |  | Called when the popover opens or closes. |
-| `id?` | `string` |  | Id of the trigger button. Generated when omitted. |
-| `className?` | `string` |  | Class name for the trigger button. |
-| `triggerProps?` | `Omit<React.ComponentProps<typeof BasePopover.Trigger>, 'children' \| 'disabled' \| 'id'>` |  | Props for the trigger button (aria-*, data-*, onBlur…). |
-| `contentProps?` | `Omit<PopoverContentProps, 'children'>` |  | Props for the popover content. |
-| `value?` | `DateRange \| null` |  | Selected days as ISO dates; both ends are inclusive. |
-| `defaultValue?` | `DateRange \| null` | `null` | Initially selected range when uncontrolled. |
-| `onValueChange?` | `(value: DateRange \| null) => void` |  | Called with the new range, or `null` when cleared. |
-| `min?` | `string` |  | Earliest allowed day. |
-| `max?` | `string` |  | Latest allowed day. |
-| `presets?` | `DateRangePreset[]` |  | Shortcuts listed beside the calendar ("Last 7 days", "This month"…). |
-| `startName?` | `string` |  | Submits the first day with a form under this name. |
-| `endName?` | `string` |  | Submits the last day with a form under this name. |
-| `clearable?` | `boolean` |  | Show the Clear action. Defaults to `true` unless `required`. |
-| `formatValue?` | `(value: DateRange) => React.ReactNode` |  | Custom display text for the selected range. |
-| `labels?` | `Partial<DateRangePickerLabels>` |  | Override texts for localisation. |
+| `logo?` | `React.ReactNode` |  | Logo or icon shown before the title; stays visible when the navbar is collapsed. |
+| `title` | `React.ReactNode` |  | Product or organization name. |
+| `subtitle?` | `React.ReactNode` |  | Smaller line under the title. |
 
-Also accepts all props of: `Pick<RangeCalendarProps, 'isDateDisabled' \| 'defaultMonth' \| 'locale' \| 'weekStartsOn' \| 'numberOfMonths'>`.
+Also accepts all props of: `Omit<useRender.ComponentProps<'div'>, 'title'>`.
 
-## DateTimePicker
+## NavbarFooter
 
-component · Forms
+compound · Layout
+
+Styled `<div>` (`.oui-navbar__footer`). Accepts `className`, `style`, the `render` prop and all `<div>` attributes.
+
+```tsx
+import { NavbarFooter } from '@optimum-intelligence/opti-ui';
+```
 
-Date and time field. Values are local ISO date-times (`"2026-03-09T14:30"`),
-the same format as `<input type="datetime-local">`, shown as `2026-03-09 14:30:00`
-on a 24-hour clock whatever the locale.
+### NavbarFooter.displayName
+
+## NavbarGroup
+
+component · Layout
+
+Expandable parent row in a `Navbar` with nested `NavbarItem` sub-links. Place it in a `NavbarSection`
+next to other items. On a collapsed rail the sub-links are hidden and the parent shows as active when
+one of them is; the hover peek shows the full tree.
+
+```tsx
+import { NavbarGroup } from '@optimum-intelligence/opti-ui';
+```
 
 ```tsx
-import { DateTimePicker } from '@optimum-intelligence/opti-ui';
+<NavbarSection>
+  <NavbarGroup icon={<Truck />} label="Fleet">
+    <NavbarItem href="/fleet/vehicles" active>Vehicles</NavbarItem>
+    <NavbarItem href="/fleet/drivers">Drivers</NavbarItem>
+  </NavbarGroup>
+</NavbarSection>
 ```
 
 | Prop | Type | Default | Description |
 | --- | --- | --- | --- |
-| `step?` | `number` |  | Granularity of the time input in seconds (60 = minutes, 1 = seconds). |
-| `defaultTime?` | `string` |  | Time used when a day is picked before any time is set. |
+| `ref?` | `React.Ref<HTMLDivElement>` |  | Ref to the group's root element. |
+| `label` | `React.ReactNode` |  | Text of the parent row. A string also becomes its tooltip on the collapsed rail. |
+| `icon?` | `React.ReactNode` |  | Icon of the parent row; it stays visible when the navbar is collapsed to a rail. |
+| `badge?` | `React.ReactNode` |  | Trailing content of the parent row, such as a count badge. |
+| `open?` | `boolean` |  | Controlled open state. Takes over from the automatic opening on an active child. |
+| `defaultOpen?` | `boolean` | `true when a child item is active` | Initial open state when uncontrolled. Whenever a child item becomes `active`, the group opens. |
+| `onOpenChange?` | `(open: boolean) => void` |  | Called when the user opens or closes the group. |
+| `children?` | `React.ReactNode` |  | Sub-links: `NavbarItem` elements (directly or in fragments), shown indented and without icons. |
 
-Also accepts all props of: `PickerProps`.
+Also accepts all props of: `Omit<React.HTMLAttributes<HTMLDivElement>, 'title'>`.
 
-## Dropzone
+## NavbarHeader
 
-component · Forms
+compound · Layout
 
-Drop target that also opens the file browser on click, Enter or Space.
+Styled `<div>` (`.oui-navbar__header`). Accepts `className`, `style`, the `render` prop and all `<div>` attributes.
 
 ```tsx
-import { Dropzone } from '@optimum-intelligence/opti-ui';
+import { NavbarHeader } from '@optimum-intelligence/opti-ui';
 ```
 
-| Prop | Type | Default | Description |
-| --- | --- | --- | --- |
-| `ref?` | `React.Ref<HTMLLabelElement>` |  | Ref to the dropzone element. |
-| `onFiles?` | `(files: File[]) => void` |  | Called with the picked or dropped files that pass `accept` and `maxSize`. |
-| `onReject?` | `(rejections: FileRejection[]) => void` |  | Called with the files that were turned away, and why. |
-| `accept?` | `string` |  | Allowed types, as for `<input accept>`: `".pdf,image/*"`. |
-| `multiple?` | `boolean` |  | Allow choosing several files. |
-| `maxSize?` | `number` |  | Largest allowed file, in bytes. |
-| `files?` | `File[]` |  | The current selection. It is kept in the native input, so the files submit with a form and `required` validates. Without it the input is emptied after each pick. |
-| `disabled?` | `boolean` |  | Disables picking and dropping. |
-| `invalid?` | `boolean` |  | Shows the error styling. |
-| `size?` | `'sm' \| 'md'` | `'md'` | `sm` is a single compact row. |
-| `icon?` | `React.ReactNode` |  | Icon shown before the title. Defaults to an upload icon. |
-| `title?` | `React.ReactNode` |  | Main line. Defaults to "Drop files here or click to browse". |
-| `hint?` | `React.ReactNode` |  | Secondary line, e.g. the allowed types and size. |
-| `inputProps?` | `Omit<React.ComponentProps<'input'>, 'ref' \| 'type'>` |  | Props for the file input (name, id, required, aria-*…). |
-
-Also accepts all props of: `Omit<React.LabelHTMLAttributes<HTMLLabelElement>, 'title'>`.
+### NavbarHeader.displayName
 
-## Field
+## NavbarItem
 
-compound · Forms
+component · Layout
 
-Field parts wire up labels, descriptions and validation for any control
-inside (Input, Select, Checkbox, Switch, NumberField…).
+Navigation link. Renders an `<a>`; use `render={<Link to="…" />}` for a
+router link or `render={<button />}` for an action. Inside a `NavbarGroup` it becomes an indented sub-link.
 
 ```tsx
-import { Field } from '@optimum-intelligence/opti-ui';
+import { NavbarItem } from '@optimum-intelligence/opti-ui';
 ```
 
-### Field.Root
-
-### Field.Label
-
 | Prop | Type | Default | Description |
 | --- | --- | --- | --- |
-| `required?` | `boolean` |  | Appends a required marker. |
+| `icon?` | `React.ReactNode` |  | Icon shown before the label; it stays visible when the navbar is collapsed to a rail. Not shown inside a `NavbarGroup`. |
+| `active?` | `boolean` | `false` | Marks the current page (sets aria-current). Also opens the surrounding `NavbarGroup`. |
+| `badge?` | `React.ReactNode` |  | Trailing content such as a count badge. |
+| `pinned?` | `boolean` | `false` | Also shows the item in the `AppShell` mobile tab bar (icon and label). Pin up to four items; the first four in navbar order are used. Has no effect outside an `AppShell`. |
 
-Also accepts all props of: `BaseField.Label.Props`.
+Also accepts all props of: `useRender.ComponentProps<'a', NavbarItemState>`.
 
-### Field.Description
+## NavbarSection
 
-### Field.Error
+compound · Layout
 
-### Field.Item
+Styled `<div>` (`.oui-navbar__section`). Accepts `className`, `style`, the `render` prop and all `<div>` attributes.
 
-### Field.Validity
+```tsx
+import { NavbarSection } from '@optimum-intelligence/opti-ui';
+```
 
-Base UI `Field.Validity` re-exported unchanged. See https://base-ui.com/react/components/field.
+### NavbarSection.displayName
 
-## Fieldset
+## NavbarSectionLabel
 
-compound · Forms
+compound · Layout
 
-Groups related fields under a legend.
+Styled `<div>` (`.oui-navbar__section-label`). Accepts `className`, `style`, the `render` prop and all `<div>` attributes.
 
 ```tsx
-import { Fieldset } from '@optimum-intelligence/opti-ui';
+import { NavbarSectionLabel } from '@optimum-intelligence/opti-ui';
 ```
 
-### Fieldset.Root
-
-### Fieldset.Legend
+### NavbarSectionLabel.displayName
 
-## FileItem
+## PageHeader
 
-component · Forms
+component · Layout
 
-One file in a list: name, size, upload progress or error, and a remove button.
+Page title block with optional breadcrumbs, eyebrow, description and actions.
 
 ```tsx
-import { FileItem } from '@optimum-intelligence/opti-ui';
+import { PageHeader } from '@optimum-intelligence/opti-ui';
 ```
 
 | Prop | Type | Default | Description |
 | --- | --- | --- | --- |
-| `ref?` | `React.Ref<HTMLDivElement>` |  | Ref to the item element. |
-| `name` | `string` |  | File name. |
-| `size?` | `number` |  | Size in bytes. |
-| `icon?` | `React.ReactNode` |  | Icon before the name. Defaults to a file icon. |
-| `status?` | `'idle' \| 'uploading' \| 'success' \| 'error'` | `'idle'` | Upload state; sets the progress bar and error styling. |
-| `progress?` | `number \| null` | `null` | Upload progress from 0 to 100, shown while `uploading`. `null` is indeterminate. |
-| `error?` | `React.ReactNode` |  | Message shown in place of the size when `status` is `error`. |
-| `onRemove?` | `() => void` |  | Adds the remove button. |
-| `removeLabel?` | `string` |  | Accessible name of the remove button. Defaults to "Remove {name}". |
-| `actions?` | `React.ReactNode` |  | Extra controls before the remove button (download, preview…). |
-| `locale?` | `string` |  | BCP 47 locale for the size. |
+| `ref?` | `React.Ref<HTMLElement>` |  | Ref to the `<header>` element. |
+| `breadcrumbs?` | `React.ReactNode` |  | Trail shown above the title, usually `<Breadcrumbs>`. |
+| `eyebrow?` | `React.ReactNode` |  | Small label above the title. |
+| `title` | `React.ReactNode` |  | Page title, rendered as the page `<h1>`. |
+| `description?` | `React.ReactNode` |  | Supporting text under the title. |
+| `actions?` | `React.ReactNode` |  | Buttons or controls aligned to the right of the title. |
 
-Also accepts all props of: `React.HTMLAttributes<HTMLDivElement>`.
+Also accepts all props of: `Omit<React.HTMLAttributes<HTMLElement>, 'title'>`.
 
-## FileUpload
+## ScrollArea
 
-component · Forms
+component · Layout
 
-File field: a dropzone plus the list of chosen files. It only collects
-`File` objects; upload them yourself and report progress through `fileState`.
+Scroll container with slim, themed overlay scrollbars. Set a height or max-height.
 
 ```tsx
-import { FileUpload } from '@optimum-intelligence/opti-ui';
+import { ScrollArea } from '@optimum-intelligence/opti-ui';
 ```
 
 | Prop | Type | Default | Description |
 | --- | --- | --- | --- |
-| `ref?` | `React.Ref<HTMLLabelElement>` |  | Ref to the dropzone element. |
-| `value?` | `File[]` |  | Chosen files (controlled). |
-| `defaultValue?` | `File[]` |  | Initially chosen files when uncontrolled. |
-| `onValueChange?` | `(files: File[]) => void` |  | Called with the full list of files after a file is added or removed. |
-| `maxFiles?` | `number` |  | Most files allowed when `multiple`. |
-| `fileState?` | `(file: File) => Pick<FileItemProps, 'status' \| 'progress' \| 'error'> \| undefined` |  | Upload state of a file, for showing progress and errors in the list. |
-| `label?` | `React.ReactNode` |  | Visible field label. |
-| `description?` | `React.ReactNode` |  | Help text under the dropzone. |
-| `error?` | `React.ReactNode` |  | Error message. When set, the field is marked invalid. |
-| `required?` | `boolean` |  | Requires at least one file before the form submits. |
-| `disabled?` | `boolean` |  | Disables picking, dropping and removing files. |
-| `name?` | `string` |  | Submits the files with a form under this name. |
-| `id?` | `string` |  | Id of the file input. Generated when omitted. |
-| `className?` | `string` |  | Class name for the root element. |
-| `locale?` | `string` |  | BCP 47 locale for file sizes. |
-| `labels?` | `Partial<FileUploadLabels>` |  | Override texts for localisation. |
+| `scrollbars?` | `'vertical' \| 'horizontal' \| 'both'` | `'vertical'` | Which scrollbars to render. |
+| `viewportProps?` | `BaseScrollArea.Viewport.Props` |  | Props for the inner scrolling viewport, e.g. a `ref` to read the scroll position. |
 
-Also accepts all props of: `Pick<DropzoneProps, 'accept' \| 'multiple' \| 'maxSize' \| 'onReject' \| 'size' \| 'icon' \| 'title' \| 'hint'>`.
+Also accepts all props of: `BaseScrollArea.Root.Props`.
 
-## Form
+## Separator
 
-component · Forms
+component · Layout
 
-Form with Base UI validation wiring and vertical field spacing.
+Thin divider line. Set `orientation="vertical"` for a vertical rule.
 
 ```tsx
-import { Form } from '@optimum-intelligence/opti-ui';
+import { Separator } from '@optimum-intelligence/opti-ui';
 ```
 
 
-Also accepts all props of: `BaseForm.Props`.
+Also accepts all props of: `BaseSeparator.Props`.
 
-## formatDate
+## Stack
 
-function · Forms
+component · Layout
 
-`"2026-03-09"`, or `"2026-03-09 14:30:00"` for a date-time: the same everywhere, on a 24-hour clock.
+Flex container that spaces its children evenly, in a column or a row.
 
 ```tsx
-import { formatDate } from '@optimum-intelligence/opti-ui';
+import { Stack } from '@optimum-intelligence/opti-ui';
 ```
 
-Signature: `formatDate(value: string \| null \| undefined)`
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| `direction?` | `'column' \| 'row'` | `'column'` | `column` (default) stacks children, `row` puts them on a line. |
+| `gap?` | `'none' \| 'xs' \| 'sm' \| 'md' \| 'lg' \| 'xl'` | `'md'` | Space between children. Override with `--oui-stack-gap`. |
+| `align?` | `'start' \| 'center' \| 'end' \| 'stretch' \| 'baseline'` |  | Cross-axis alignment. Defaults to `stretch` in a column and `center` in a row. |
+| `justify?` | `'start' \| 'center' \| 'end' \| 'between'` |  | Main-axis distribution. |
+| `wrap?` | `boolean` | `false` | Let a row's children wrap onto more lines. |
+
+Also accepts all props of: `useRender.ComponentProps<'div', StackState>`.
 
-## formatDateLong
+## StatCard
 
-function · Forms
+component · Layout
 
-The written form, `"2026. March 9."`, or `"2026. March 9. 14:30"` for a date-time.
-The order and the 24-hour clock are fixed; `locale` only translates the month name.
+KPI tile: label, large value, optional unit and trend.
 
 ```tsx
-import { formatDateLong } from '@optimum-intelligence/opti-ui';
+import { StatCard } from '@optimum-intelligence/opti-ui';
 ```
 
-Signature: `formatDateLong(value: string \| null \| undefined, locale?: string)`
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| `variant?` | `'outlined' \| 'elevated' \| 'filled' \| 'ghost'` |  | `outlined` (default) uses the card border, `elevated` a soft shadow. |
+| `padding?` | `'none' \| 'sm' \| 'md' \| 'lg'` |  | Inner spacing. Override with `--oui-card-padding`. |
+| `interactive?` | `boolean` |  | Adds hover and focus states — use with `render={<a href=… />}` or a click handler. |
+| `label` | `React.ReactNode` |  | What the number measures. |
+| `value` | `React.ReactNode` |  | The headline figure. |
+| `unit?` | `React.ReactNode` |  | Unit beside the value, e.g. "kWh" or "orders". |
+| `delta?` | `React.ReactNode` |  | Change indicator, e.g. "+12.4%". |
+| `trend?` | `'up' \| 'down' \| 'flat'` |  | Arrow direction shown next to `delta`. |
+| `tone?` | `'positive' \| 'negative' \| 'neutral'` |  | Color of the delta. Defaults to positive for `up`, negative for `down`. |
+| `hint?` | `React.ReactNode` |  | Supporting text under the value. |
+| `icon?` | `React.ReactNode` |  | Icon tile shown in the top-right corner. |
+| `loading?` | `boolean` |  | Replaces the value with a skeleton while data loads. |
+
+Also accepts all props of: `useRender.ComponentProps<'div', CardState>`.
 
-## formatFileSize
+# Typography
 
-function · Forms
+## Eyebrow
 
-`1536` → `"1.5 KB"`.
+component · Typography
+
+Small uppercase label used above titles, in filter bars and table headers.
 
 ```tsx
-import { formatFileSize } from '@optimum-intelligence/opti-ui';
+import { Eyebrow } from '@optimum-intelligence/opti-ui';
 ```
 
-Signature: `formatFileSize(bytes: number, locale?: string)`
 
-## Input
+Also accepts all props of: `useRender.ComponentProps<'span'>`.
 
-component · Forms
+## Heading
 
-Text input, optionally with `startAdornment` / `endAdornment` inside the box. Use `TextField` for a labelled one.
+component · Typography
+
+Heading element. `level` sets the tag (`h1`–`h6`) and the default size; `size` overrides only the look.
 
 ```tsx
-import { Input } from '@optimum-intelligence/opti-ui';
+import { Heading } from '@optimum-intelligence/opti-ui';
 ```
 
 | Prop | Type | Default | Description |
 | --- | --- | --- | --- |
-| `size?` | `'sm' \| 'md' \| 'lg'` | `'md'` | Control height. |
-| `startAdornment?` | `React.ReactNode` |  | Icon or text rendered inside the box, before the value. |
-| `endAdornment?` | `React.ReactNode` |  | Icon, text or button rendered inside the box, after the value. |
+| `level?` | `HeadingLevel` | `2` | Semantic level; picks the element. |
+| `size?` | `'xs' \| 'sm' \| 'md' \| 'lg' \| 'xl' \| '2xl'` |  | Visual size, independent of the level. |
 
-Also accepts all props of: `Omit<BaseInput.Props, 'size'>`.
+Also accepts all props of: `useRender.ComponentProps<'h2', HeadingState>`.
 
-## NumberField
+## Link
 
-component · Forms
+component · Typography
 
-Numeric input with stepper buttons, locale formatting and keyboard stepping.
+Text link. Pass a router link through `render`: `<Link render={<NavLink to="/fleet" />}>`.
 
 ```tsx
-import { NumberField } from '@optimum-intelligence/opti-ui';
+import { Link } from '@optimum-intelligence/opti-ui';
 ```
 
 | Prop | Type | Default | Description |
 | --- | --- | --- | --- |
-| `label?` | `React.ReactNode` |  | Visible field label. |
-| `description?` | `React.ReactNode` |  | Help text under the input. |
-| `error?` | `React.ReactNode` |  | Error message. When set, the field is marked invalid. |
-| `size?` | `'sm' \| 'md' \| 'lg'` | `'md'` | Control height. |
-| `placeholder?` | `string` |  | Placeholder shown while empty. |
-| `hideStepper?` | `boolean` |  | Hide the − / + stepper buttons. |
-| `decrementLabel?` | `string` | `'Decrease'` | Accessible name of the − button. |
-| `incrementLabel?` | `string` | `'Increase'` | Accessible name of the + button. |
+| `tone?` | `'accent' \| 'muted' \| 'inherit'` | `'accent'` | `inherit` takes the color of the surrounding text. |
+| `underline?` | `'always' \| 'hover' \| 'none'` | `'always'` | When the underline shows. |
+| `external?` | `boolean` | `false` | Opens in a new tab, with a trailing icon. |
 
-Also accepts all props of: `BaseNumberField.Root.Props`.
+Also accepts all props of: `useRender.ComponentProps<'a', LinkState>`.
 
-## PasswordField
+## Text
 
-component · Forms
+component · Typography
 
-Labelled password input with description and error message.
+Body text paragraph. Use `render={<span />}` for inline text.
 
 ```tsx
-import { PasswordField } from '@optimum-intelligence/opti-ui';
+import { Text } from '@optimum-intelligence/opti-ui';
 ```
 
 | Prop | Type | Default | Description |
 | --- | --- | --- | --- |
-| `size?` | `'sm' \| 'md' \| 'lg'` |  | Control height. |
-| `startAdornment?` | `React.ReactNode` |  | Icon or text rendered inside the box, before the value. |
-| `visible?` | `boolean` |  | Whether the value is shown as plain text. |
-| `defaultVisible?` | `boolean` |  | Initial visibility when uncontrolled. |
-| `onVisibleChange?` | `(visible: boolean) => void` |  | Called when the user toggles visibility. |
-| `toggleLabel?` | `string` |  | Accessible name of the show/hide button. |
+| `size?` | `'xs' \| 'sm' \| 'md' \| 'lg'` | `'md'` | Font size. |
+| `tone?` | `'default' \| 'strong' \| 'muted' \| 'subtle' \| 'accent' \| 'success' \| 'warning' \| 'danger'` | `'default'` | Color role: from `strong` to `subtle`, or a status color. |
+| `weight?` | `'regular' \| 'medium' \| 'semibold' \| 'bold'` |  | Font weight. Inherits when omitted. |
 
-Also accepts all props of: `Omit<BaseInput.Props, 'size'>`, `FieldShellProps`.
+Also accepts all props of: `useRender.ComponentProps<'p', TextState>`.
 
-## PasswordInput
+# Actions
 
-component · Forms
+## Button
 
-Password input with a button that reveals the value.
+component · Actions
+
+Action button. Use `render={<a href="…" />}` with `nativeButton={false}` to style a link as a button.
 
 ```tsx
-import { PasswordInput } from '@optimum-intelligence/opti-ui';
+import { Button } from '@optimum-intelligence/opti-ui';
+```
+
+```tsx
+<Button variant="secondary" loading={saving} onClick={save}>Save</Button>
 ```
 
 | Prop | Type | Default | Description |
 | --- | --- | --- | --- |
-| `size?` | `'sm' \| 'md' \| 'lg'` |  | Control height. |
-| `startAdornment?` | `React.ReactNode` |  | Icon or text rendered inside the box, before the value. |
-| `visible?` | `boolean` |  | Whether the value is shown as plain text. |
-| `defaultVisible?` | `boolean` | `false` | Initial visibility when uncontrolled. |
-| `onVisibleChange?` | `(visible: boolean) => void` |  | Called when the user toggles visibility. |
-| `toggleLabel?` | `string` | `'Show password'` | Accessible name of the show/hide button. |
+| `variant?` | `'primary' \| 'accent' \| 'secondary' \| 'soft' \| 'ghost' \| 'danger'` | `'primary'` | Visual emphasis. |
+| `size?` | `'sm' \| 'md' \| 'lg'` | `'md'` | Height and padding. |
+| `shape?` | `'pill' \| 'rounded'` | `'pill'` | `pill` (default) or `rounded` corners. Override with `--oui-button-radius`. |
+| `fullWidth?` | `boolean` |  | Stretch to the container width. |
+| `loading?` | `boolean` |  | Shows a spinner and blocks interaction while keeping focus. |
 
-Also accepts all props of: `Omit<BaseInput.Props, 'size'>`.
+Also accepts all props of: `BaseButton.Props`.
 
-## Radio
+## ContextMenu
 
-component · Forms
+compound · Actions
 
-Radio button with optional `label` and `description`. Use inside `RadioGroup`; each needs a `value`.
+Menu opened by right click or long press on `ContextMenu.Trigger`, which wraps
+the target area. The item parts are the same as `Menu`'s.
 
 ```tsx
-import { Radio } from '@optimum-intelligence/opti-ui';
+import { ContextMenu } from '@optimum-intelligence/opti-ui';
 ```
 
+### ContextMenu.Root
 
-Also accepts all props of: `BaseRadio.Root.Props`, `ChoiceLabelProps`.
-
-## RadioGroup
+Base UI `ContextMenu.Root` re-exported unchanged. See https://base-ui.com/react/components/context-menu.
 
-component · Forms
+### ContextMenu.Trigger
 
-Single-choice group for `Radio` children (`value` / `onValueChange`).
+Base UI `ContextMenu.Trigger` re-exported unchanged. See https://base-ui.com/react/components/context-menu.
 
-```tsx
-import { RadioGroup } from '@optimum-intelligence/opti-ui';
-```
+### ContextMenu.Content
 
 | Prop | Type | Default | Description |
 | --- | --- | --- | --- |
-| `orientation?` | `'vertical' \| 'horizontal'` | `'vertical'` | Layout direction of the radios. |
+| `positionerProps?` | `BaseContextMenu.Positioner.Props` |  | Props for the positioner element that places the popup. |
 
-Also accepts all props of: `BaseRadioGroup.Props`.
+Also accepts all props of: `BaseContextMenu.Popup.Props`.
 
-## RangeCalendar
+### ContextMenu.Item
 
-component · Forms
+### ContextMenu.LinkItem
 
-Month grid for picking a range of days: the first pick sets one end, the
-second completes the range (in either order). Same keyboard as Calendar.
-Disabled days cannot be picked as an end but may fall inside a range.
+### ContextMenu.CheckboxItem
 
-```tsx
-import { RangeCalendar } from '@optimum-intelligence/opti-ui';
-```
+### ContextMenu.RadioGroup
 
-| Prop | Type | Default | Description |
-| --- | --- | --- | --- |
-| `value?` | `DateRange \| null` |  | Selected days as ISO dates; both ends are inclusive. |
-| `defaultValue?` | `DateRange \| null` | `null` | Initially selected range when uncontrolled. |
-| `onValueChange?` | `(value: DateRange) => void` |  | Called once both ends are picked, with `start` on or before `end`. |
+### ContextMenu.RadioItem
 
-Also accepts all props of: `CalendarOptions`.
+### ContextMenu.Group
 
-## SearchInput
+### ContextMenu.GroupLabel
 
-component · Forms
+### ContextMenu.Separator
 
-Text input with a search icon and a clear button that appears once there is a value.
+### ContextMenu.SubmenuRoot
+
+### ContextMenu.SubmenuTrigger
+
+## IconButton
+
+component · Actions
+
+Square button for a single icon. Defaults to the compact ghost style.
 
 ```tsx
-import { SearchInput } from '@optimum-intelligence/opti-ui';
+import { IconButton } from '@optimum-intelligence/opti-ui';
 ```
 
 | Prop | Type | Default | Description |
 | --- | --- | --- | --- |
-| `size?` | `'sm' \| 'md' \| 'lg'` |  | Control height. |
-| `value?` | `string` |  | Current text (controlled). |
-| `defaultValue?` | `string` | `''` | Initial text when uncontrolled. |
-| `onValueChange?` | `(value: string) => void` |  | Called with the new text on typing and with `''` on clear. |
-| `clearLabel?` | `string` | `'Clear search'` | Accessible name of the clear button. |
-| `icon?` | `React.ReactNode` |  | Replaces the leading search icon. |
+| `variant?` | `'primary' \| 'accent' \| 'secondary' \| 'soft' \| 'ghost' \| 'danger'` | `'ghost'` | Visual emphasis. |
+| `size?` | `'sm' \| 'md' \| 'lg'` | `'md'` | Height and padding. |
+| `loading?` | `boolean` |  | Shows a spinner and blocks interaction while keeping focus. |
+| `aria-label` | `string` |  | Required: icon-only buttons need an accessible name. |
+| `shape?` | `'rounded' \| 'circle'` | `'rounded'` | `rounded` square (default) or `circle`. |
 
-Also accepts all props of: `Omit<BaseInput.Props, 'size'>`.
+Also accepts all props of: `BaseButton.Props`.
 
-## Select
+## Menu
 
-compound · Forms
+compound · Actions
 
-`<Select items={…} />` renders a complete labelled select. For full control
-compose the parts: `Select.Root`, `Select.Trigger`, `Select.Content`,
-`Select.Item`, `Select.Group`, `Select.GroupLabel`, `Select.Separator`.
+Dropdown menu of actions. Compose `Menu.Root` › `Menu.Trigger` + `Menu.Content` › items.
+For nested menus use `Menu.SubmenuRoot` › `Menu.SubmenuTrigger` + `Menu.Content`.
 
 ```tsx
-import { Select } from '@optimum-intelligence/opti-ui';
+import { Menu } from '@optimum-intelligence/opti-ui';
 ```
 
+### Menu.Root
+
+Base UI `Menu.Root` re-exported unchanged. See https://base-ui.com/react/components/menu.
+
+### Menu.Trigger
+
+Base UI `Menu.Trigger` re-exported unchanged. See https://base-ui.com/react/components/menu.
+
+### Menu.Content
+
 | Prop | Type | Default | Description |
 | --- | --- | --- | --- |
-| `items` | `Array<SelectOption \| SelectOptionGroup>` |  | Options, or groups of options. |
-| `label?` | `React.ReactNode` |  | Visible field label. |
-| `description?` | `React.ReactNode` |  | Help text under the trigger. |
-| `error?` | `React.ReactNode` |  | Error message. When set, the field is marked invalid. |
-| `placeholder?` | `React.ReactNode` | `'Select…'` | Text shown while nothing is selected. |
-| `size?` | `'sm' \| 'md' \| 'lg'` | `'md'` | Control height. |
-| `triggerProps?` | `Omit<SelectTriggerProps, 'size' \| 'placeholder'>` |  | Props passed to the trigger button (className, style, aria-*). |
-| `contentProps?` | `Omit<SelectContentProps, 'children'>` |  | Props for the popup (side, align, className…). |
+| `side?` | `BaseMenu.Positioner.Props['side']` |  | Which side of the trigger the menu opens on. |
+| `align?` | `BaseMenu.Positioner.Props['align']` | `'start'` | Alignment along that side. |
+| `sideOffset?` | `BaseMenu.Positioner.Props['sideOffset']` | `6` | Distance from the trigger in px. |
+| `alignOffset?` | `BaseMenu.Positioner.Props['alignOffset']` |  | Shift along the alignment axis in px. |
+| `positionerProps?` | `BaseMenu.Positioner.Props` |  | Props for the positioner element that places the popup. |
 
-Also accepts all props of: `RootProps`.
+Also accepts all props of: `BaseMenu.Popup.Props`.
 
-### Select.Root
+### Menu.Item
 
-Base UI `Select.Root` re-exported unchanged. See https://base-ui.com/react/components/select.
 
-### Select.Label
+Also accepts all props of: `BaseMenu.Item.Props`, `ItemExtras`.
 
-### Select.Trigger
+### Menu.LinkItem
 
-The select button. Renders the value and chevron unless children are given.
 
-| Prop | Type | Default | Description |
-| --- | --- | --- | --- |
-| `size?` | `'sm' \| 'md' \| 'lg'` | `'md'` | Control height. |
-| `placeholder?` | `React.ReactNode` |  | Placeholder shown by the default value slot. |
+Also accepts all props of: `BaseMenu.LinkItem.Props`, `Omit<ItemExtras, 'danger'>`.
 
-Also accepts all props of: `BaseSelect.Trigger.Props`.
+### Menu.CheckboxItem
 
-### Select.Value
 
-### Select.Content
+Also accepts all props of: `BaseMenu.CheckboxItem.Props`, `Omit<ItemExtras, 'icon' \| 'danger'>`.
 
-Portal + positioner + popup + list in one.
+### Menu.RadioGroup
 
-| Prop | Type | Default | Description |
-| --- | --- | --- | --- |
-| `side?` | `BaseSelect.Positioner.Props['side']` |  | Which side of the trigger the list opens on. |
-| `align?` | `BaseSelect.Positioner.Props['align']` |  | Alignment along that side. |
-| `sideOffset?` | `BaseSelect.Positioner.Props['sideOffset']` | `6` | Distance from the trigger in px. |
-| `alignItemWithTrigger?` | `boolean` | `false` | Overlap the trigger so the selected item lines up with it (macOS style). |
-| `positionerProps?` | `BaseSelect.Positioner.Props` |  | Props for the positioner element that places the popup. |
+Base UI `Menu.RadioGroup` re-exported unchanged. See https://base-ui.com/react/components/menu.
 
-Also accepts all props of: `BaseSelect.Popup.Props`.
+### Menu.RadioItem
 
-### Select.Item
 
-### Select.Group
+Also accepts all props of: `BaseMenu.RadioItem.Props`, `Omit<ItemExtras, 'icon' \| 'danger'>`.
 
-### Select.GroupLabel
+### Menu.Group
 
-### Select.Separator
+Base UI `Menu.Group` re-exported unchanged. See https://base-ui.com/react/components/menu.
 
-## Slider
+### Menu.GroupLabel
 
-component · Forms
+### Menu.Separator
 
-Single value or range (pass an array) slider.
+### Menu.SubmenuRoot
 
-```tsx
-import { Slider } from '@optimum-intelligence/opti-ui';
-```
+Base UI `Menu.SubmenuRoot` re-exported unchanged. See https://base-ui.com/react/components/menu.
 
-| Prop | Type | Default | Description |
-| --- | --- | --- | --- |
-| `label?` | `React.ReactNode` |  | Visible label above the track. |
-| `showValue?` | `boolean` |  | Show the formatted value next to the label. |
-| `thumbLabels?` | `string[]` |  | Accessible labels for each thumb (needed for range sliders). |
+### Menu.SubmenuTrigger
 
-Also accepts all props of: `BaseSlider.Root.Props`.
 
-## Switch
+Also accepts all props of: `BaseMenu.SubmenuTrigger.Props`, `Omit<ItemExtras, 'shortcut' \| 'danger'>`.
 
-component · Forms
+## SegmentedControl
 
-On/off switch with optional `label` and `description`.
+component · Actions
 
-```tsx
-import { Switch } from '@optimum-intelligence/opti-ui';
-```
+Single-choice switcher (e.g. Day / Week / Month). Always keeps one value selected.
 
 ```tsx
-<Switch label="Email alerts" checked={on} onCheckedChange={setOn} />
+import { SegmentedControl } from '@optimum-intelligence/opti-ui';
 ```
 
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| `size?` | `'sm' \| 'md'` | `'md'` | Segment height. |
+| `variant?` | `'segmented' \| 'outline'` |  | `segmented` renders a pill track like a tab switcher; `outline` separate buttons. |
+| `fullWidth?` | `boolean` |  | Stretch segments to fill the width. |
+| `options` | `SegmentedControlOption[]` |  | Segments to show. |
+| `value?` | `string` |  | Selected option `value` (controlled). |
+| `defaultValue?` | `string` |  | Initially selected option `value` when uncontrolled. |
+| `onValueChange?` | `(value: string) => void` |  | Called with the new `value` when the selection changes. |
 
-Also accepts all props of: `BaseSwitch.Root.Props`, `ChoiceLabelProps`.
+Also accepts all props of: `BaseToggleGroup.Props`.
 
-## Textarea
+## Toggle
 
-component · Forms
+component · Actions
 
-Multi-line text input. Use `TextareaField` for a labelled one.
+Two-state button (bold, pin, favourite…). Inside a ToggleGroup it acts as a segment.
 
 ```tsx
-import { Textarea } from '@optimum-intelligence/opti-ui';
+import { Toggle } from '@optimum-intelligence/opti-ui';
 ```
 
 | Prop | Type | Default | Description |
 | --- | --- | --- | --- |
-| `ref?` | `React.Ref<HTMLTextAreaElement>` |  | Ref to the `<textarea>`. |
-| `autoResize?` | `boolean` |  | Grow with content up to `maxRows` (uses CSS field-sizing where supported). |
+| `size?` | `'sm' \| 'md'` | `'md'` | Button height. |
 
-Also accepts all props of: `React.TextareaHTMLAttributes<HTMLTextAreaElement>`.
+Also accepts all props of: `BaseToggle.Props`.
 
-## TextareaField
+## ToggleGroup
 
-component · Forms
+component · Actions
 
-Labelled textarea with description and error message.
+Group of `Toggle` buttons that share selection state (single or multiple).
 
 ```tsx
-import { TextareaField } from '@optimum-intelligence/opti-ui';
+import { ToggleGroup } from '@optimum-intelligence/opti-ui';
 ```
 
 | Prop | Type | Default | Description |
 | --- | --- | --- | --- |
-| `ref?` | `React.Ref<HTMLTextAreaElement>` |  | Ref to the `<textarea>`. |
-| `autoResize?` | `boolean` |  | Grow with content up to `maxRows` (uses CSS field-sizing where supported). |
+| `size?` | `'sm' \| 'md'` | `'md'` | Segment height. |
+| `variant?` | `'segmented' \| 'outline'` | `'segmented'` | `segmented` renders a pill track like a tab switcher; `outline` separate buttons. |
+| `fullWidth?` | `boolean` |  | Stretch segments to fill the width. |
 
-Also accepts all props of: `React.TextareaHTMLAttributes<HTMLTextAreaElement>`, `FieldShellProps`.
+Also accepts all props of: `BaseToggleGroup.Props`.
 
-## TextField
+## Toolbar
 
-component · Forms
+compound · Actions
 
-Labelled input with description and error message.
+Row of controls that is a single tab stop; arrow keys move between them.
+Other controls join through `render`: `<Toolbar.Button render={<Toggle />} />`,
+`<Toolbar.Button render={<Menu.Trigger />} />`.
 
 ```tsx
-import { TextField } from '@optimum-intelligence/opti-ui';
+import { Toolbar } from '@optimum-intelligence/opti-ui';
 ```
 
-| Prop | Type | Default | Description |
-| --- | --- | --- | --- |
-| `size?` | `'sm' \| 'md' \| 'lg'` |  | Control height. |
-| `startAdornment?` | `React.ReactNode` |  | Icon or text rendered inside the box, before the value. |
-| `endAdornment?` | `React.ReactNode` |  | Icon, text or button rendered inside the box, after the value. |
+### Toolbar.Root
 
-Also accepts all props of: `Omit<BaseInput.Props, 'size'>`, `FieldShellProps`.
+### Toolbar.Button
+
+### Toolbar.Link
+
+### Toolbar.Group
+
+### Toolbar.Separator
+
+### Toolbar.Input
 
 # Overlays
 
@@ -2046,7 +2164,7 @@ import { Badge } from '@optimum-intelligence/opti-ui';
 ```
 
 ```tsx
-<Badge tone="success" dot>Online</Badge>
+<Badge tone="success">Online</Badge>
 ```
 
 | Prop | Type | Default | Description |
@@ -2054,7 +2172,6 @@ import { Badge } from '@optimum-intelligence/opti-ui';
 | `tone?` | `'neutral' \| 'accent' \| 'info' \| 'success' \| 'warning' \| 'danger'` | `'neutral'` | Semantic color. |
 | `variant?` | `'soft' \| 'solid' \| 'outline'` | `'soft'` | `soft` tinted, `solid` filled, `outline` bordered. |
 | `size?` | `'sm' \| 'md'` | `'md'` | Badge height and text size. |
-| `dot?` | `boolean` |  | Leading status dot. |
 
 Also accepts all props of: `useRender.ComponentProps<'span', BadgeState>`.
 
@@ -2318,7 +2435,7 @@ import { Table } from '@optimum-intelligence/opti-ui';
 | Prop | Type | Default | Description |
 | --- | --- | --- | --- |
 | `ref?` | `React.Ref<HTMLTableElement>` |  | Ref to the `<table>`. |
-| `density?` | `'compact' \| 'normal' \| 'comfortable'` | `'normal'` | Row height. |
+| `density?` | `'compact' \| 'normal' \| 'comfortable'` | `'normal'` | Row height and cell padding. `normal` suits data-heavy screens; `comfortable` adds air for short tables. |
 | `striped?` | `boolean` |  | Alternating row background. |
 | `hoverable?` | `boolean` | `true` | Highlight rows on hover. |
 | `stickyHeader?` | `boolean` |  | Keep the header visible while the wrapper scrolls (set a max height on it). |