@optimum-intelligence/opti-ui 0.3.0 → 0.5.0

package/dist/llms-full.txt

@@ -0,0 +1,2707 @@
+# Opti UI (`@optimum-intelligence/opti-ui`)
+
+> Optimum's customizable React component library, built on Base UI. React 19, styled with CSS custom properties (`--oui-*`) in cascade layers.
+
+## Setup
+
+React 19 is a peer dependency; the build is precompiled with React Compiler. `@base-ui/react` is installed with the package.
+
+```tsx
+import '@optimum-intelligence/opti-ui/styles.css';
+import '@optimum-intelligence/opti-ui/fonts.css'; // optional: loads Poppins + Montserrat from Google Fonts
+import { Button, Card, CardTitle, ToastProvider, Tooltip } from '@optimum-intelligence/opti-ui';
+
+export function App() {
+  return (
+    <Tooltip.Provider>
+      <ToastProvider>
+        <Card>
+          <CardTitle>Monthly energy</CardTitle>
+          <Button>Export report</Button>
+        </Card>
+      </ToastProvider>
+    </Tooltip.Provider>
+  );
+}
+```
+
+Add `class="oui-root"` to `<body>` for the library font, text color and background. Add `oui-isolate`
+to your app root so portalled popups stack above app content. Every module has a `'use client'` banner,
+so the components work in Next.js App Router.
+
+## Customization
+
+Start with the simplest option that does what you need:
+
+1. **Tokens.** Every color, radius, shadow, font, size and duration is a `--oui-*` custom property. Most
+   colors are derived from two inputs with `color-mix()`, so a product theme is often just two values:
+
+   ```css
+   :root {
+     --oui-color-brand: #0f2a44;  /* deep base: primary buttons, headings, navbar, muted text */
+     --oui-color-accent: #1f8fd6; /* focus rings, selection, borders, tints */
+   }
+   ```
+
+2. **Scoped themes.** `<ThemeProvider theme={{ 'color-accent': '#1f8fd6' }} mode="dark">` applies tokens to a
+   subtree. Popups opened inside are portalled into the provider, so they inherit the same theme. For
+   dark mode across the whole app, set `data-oui-theme="dark"` on `<html>`.
+3. **Component variables.** Use these per instance or globally, e.g. `--oui-button-radius`,
+   `--oui-button-height`, `--oui-input-height`, `--oui-card-padding`, `--oui-card-radius`,
+   `--oui-dialog-width`, `--oui-navbar-width`, `--oui-navbar-collapsed-width`, `--oui-switch-width`, `--oui-progress-height`.
+4. **Classes.** All library CSS is inside cascade layers (`oui.tokens < oui.base < oui.components`).
+   Any unlayered CSS in your app overrides it, whatever its specificity, so `!important` is never
+   needed. Every part has a stable class (`oui-select__trigger`, `oui-dialog__footer`, …).
+5. **State attributes.** Style states through Base UI's data attributes (`[data-checked]`,
+   `[data-popup-open]`, `[data-highlighted]`, …) and the library's own (`[data-variant]`, `[data-size]`,
+   `[data-tone]`). `className` also accepts a function of component state.
+6. **The render prop.** Swap the rendered element and keep the styles and behaviour:
+   `<NavbarItem render={<NavLink to="/fleet" />}>`,
+   `<Button render={<a href="…" />} nativeButton={false}>`.
+
+**Tailwind v4:** declare the layer order so utilities still win over library styles:
+`@layer theme, base, oui, components, utilities;`
+
+# Theme
+
+## createTheme
+
+function · Theme
+
+Builds a theme from a base, applying overrides on top.
+
+```tsx
+import { createTheme } from '@optimum-intelligence/opti-ui';
+```
+
+Signature: `createTheme(...themes: Theme[])`
+
+## ThemeProvider
+
+component · Theme
+
+Scopes a theme to its children. Popups opened inside are portalled into the
+provider so they pick up the same tokens.
+
+```tsx
+import { ThemeProvider } from '@optimum-intelligence/opti-ui';
+```
+
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| `ref?` | `React.Ref<HTMLDivElement>` |  | Ref to the provider's root element. |
+| `theme?` | `Theme` |  | Token overrides applied to this subtree. |
+| `mode?` | `'light' \| 'dark'` |  | Color mode for this subtree. |
+
+Also accepts all props of: `React.HTMLAttributes<HTMLDivElement>`.
+
+## themeToStyle
+
+function · Theme
+
+Converts a theme object into CSS custom properties for a `style` prop.
+
+```tsx
+import { themeToStyle } from '@optimum-intelligence/opti-ui';
+```
+
+Signature: `themeToStyle(theme: Theme \| undefined)`
+
+# Forms
+
+## Calendar
+
+component · Forms
+
+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 { Calendar } from '@optimum-intelligence/opti-ui';
+```
+
+```tsx
+<Calendar value={month} onValueChange={setMonth} granularity="month" />
+```
+
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| `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: `CalendarOptions`.
+
+## Checkbox
+
+component · Forms
+
+Checkbox with optional `label` and `description`. Supports `indeterminate`.
+
+```tsx
+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
+import { CheckboxGroup } 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`.
+
+## Combobox
+
+compound · Forms
+
+Searchable select. `<Combobox items={…} />` covers single and `multiple`
+(chips) selection; compose the parts for anything custom.
+
+```tsx
+import { Combobox } 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. |
+
+Also accepts all props of: `RootProps`.
+
+### Combobox.Root
+
+Base UI `Combobox.Root` re-exported unchanged. See https://base-ui.com/react/components/combobox.
+
+### Combobox.InputGroup
+
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| `size?` | `'sm' \| 'md' \| 'lg'` | `'md'` | Control height. |
+
+Also accepts all props of: `BaseCombobox.InputGroup.Props`.
+
+### Combobox.Input
+
+### Combobox.Trigger
+
+### Combobox.Clear
+
+### Combobox.Value
+
+Base UI `Combobox.Value` re-exported unchanged. See https://base-ui.com/react/components/combobox.
+
+### Combobox.Chips
+
+### Combobox.Chip
+
+### Combobox.Content
+
+| 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. |
+
+Also accepts all props of: `BaseCombobox.Popup.Props`.
+
+### Combobox.List
+
+### Combobox.Item
+
+### Combobox.Empty
+
+### Combobox.Group
+
+Base UI `Combobox.Group` re-exported unchanged. See https://base-ui.com/react/components/combobox.
+
+### Combobox.GroupLabel
+
+### Combobox.Collection
+
+Base UI `Combobox.Collection` re-exported unchanged. See https://base-ui.com/react/components/combobox.
+
+### Combobox.useFilter
+
+Base UI `Combobox.useFilter` re-exported unchanged. See https://base-ui.com/react/components/combobox.
+
+## DateConfigProvider
+
+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 { 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 |
+| --- | --- | --- | --- |
+| `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. |
+
+## DatePicker
+
+component · Forms
+
+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`.
+
+```tsx
+import { DatePicker } from '@optimum-intelligence/opti-ui';
+```
+
+```tsx
+<DatePicker label="Delivery date" value={date} onValueChange={setDate} />
+<DatePicker label="Billing month" granularity="month" format="MMMM YYYY" />
+```
+
+
+Also accepts all props of: `PickerProps`.
+
+## DateRangePicker
+
+component · Forms
+
+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 { DateRangePicker } from '@optimum-intelligence/opti-ui';
+```
+
+```tsx
+<DateRangePicker label="Period" value={period} onValueChange={setPeriod} presets={presets} />
+```
+
+| 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`. |
+| `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: `Pick<RangeCalendarProps, 'isDateDisabled' \| 'defaultMonth' \| 'locale' \| 'weekStartsOn' \| 'numberOfMonths' \| 'granularity'>`.
+
+## DateTimePicker
+
+component · Forms
+
+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 { DateTimePicker } from '@optimum-intelligence/opti-ui';
+```
+
+```tsx
+<DateTimePicker label="Departure" value={slot} onValueChange={setSlot} timeZone="Europe/Budapest" />
+```
+
+| 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`. |
+
+Also accepts all props of: `PickerProps`.
+
+## Dropzone
+
+component · Forms
+
+Drop target that also opens the file browser on click, Enter or Space.
+
+```tsx
+import { Dropzone } 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'>`.
+
+## Field
+
+compound · Forms
+
+Field parts wire up labels, descriptions and validation for any control
+inside (Input, Select, Checkbox, Switch, NumberField…).
+
+```tsx
+import { Field } from '@optimum-intelligence/opti-ui';
+```
+
+### Field.Root
+
+### Field.Label
+
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| `required?` | `boolean` |  | Appends a required marker. |
+
+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 { Fieldset } from '@optimum-intelligence/opti-ui';
+```
+
+### Fieldset.Root
+
+### Fieldset.Legend
+
+## FileItem
+
+component · Forms
+
+One file in a list: name, size, upload progress or error, and a remove button.
+
+```tsx
+import { FileItem } 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. |
+
+Also accepts all props of: `React.HTMLAttributes<HTMLDivElement>`.
+
+## FileUpload
+
+component · Forms
+
+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 { FileUpload } 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. |
+
+Also accepts all props of: `Pick<DropzoneProps, 'accept' \| 'multiple' \| 'maxSize' \| 'onReject' \| 'size' \| 'icon' \| 'title' \| 'hint'>`.
+
+## Form
+
+component · Forms
+
+Form with Base UI validation wiring and vertical field spacing.
+
+```tsx
+import { Form } from '@optimum-intelligence/opti-ui';
+```
+
+
+Also accepts all props of: `BaseForm.Props`.
+
+## formatDate
+
+function · Forms
+
+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 { formatDate } from '@optimum-intelligence/opti-ui';
+```
+
+Signature: `formatDate(value: string \| null \| undefined, options: FormatDateOptions = {})`
+
+```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"
+```
+
+## formatFileSize
+
+function · Forms
+
+`1536` → `"1.5 KB"`.
+
+```tsx
+import { formatFileSize } from '@optimum-intelligence/opti-ui';
+```
+
+Signature: `formatFileSize(bytes: number, locale?: string)`
+
+## Input
+
+component · Forms
+
+Text input, optionally with `startAdornment` / `endAdornment` inside the box. Use `TextField` for a labelled one.
+
+```tsx
+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: `Omit<BaseInput.Props, 'size'>`.
+
+## NumberField
+
+component · Forms
+
+Numeric input with stepper buttons, locale formatting and keyboard stepping.
+
+```tsx
+import { NumberField } 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. |
+
+Also accepts all props of: `BaseNumberField.Root.Props`.
+
+## PasswordField
+
+component · Forms
+
+Labelled password input with description and error message.
+
+```tsx
+import { PasswordField } 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. |
+
+Also accepts all props of: `Omit<BaseInput.Props, 'size'>`, `FieldShellProps`.
+
+## PasswordInput
+
+component · Forms
+
+Password input with a button that reveals the value.
+
+```tsx
+import { PasswordInput } 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` | `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. |
+
+Also accepts all props of: `Omit<BaseInput.Props, 'size'>`.
+
+## Radio
+
+component · Forms
+
+Radio button with optional `label` and `description`. Use inside `RadioGroup`; each needs a `value`.
+
+```tsx
+import { Radio } from '@optimum-intelligence/opti-ui';
+```
+
+
+Also accepts all props of: `BaseRadio.Root.Props`, `ChoiceLabelProps`.
+
+## RadioGroup
+
+component · Forms
+
+Single-choice group for `Radio` children (`value` / `onValueChange`).
+
+```tsx
+import { RadioGroup } from '@optimum-intelligence/opti-ui';
+```
+
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| `orientation?` | `'vertical' \| 'horizontal'` | `'vertical'` | Layout direction of the radios. |
+
+Also accepts all props of: `BaseRadioGroup.Props`.
+
+## RangeCalendar
+
+component · Forms
+
+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.
+
+```tsx
+import { RangeCalendar } from '@optimum-intelligence/opti-ui';
+```
+
+| 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`. |
+
+Also accepts all props of: `CalendarOptions`.
+
+## SearchInput
+
+component · Forms
+
+Text input with a search icon and a clear button that appears once there is a value.
+
+```tsx
+import { SearchInput } 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. |
+
+Also accepts all props of: `Omit<BaseInput.Props, 'size'>`.
+
+## Select
+
+compound · Forms
+
+`<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 { Select } from '@optimum-intelligence/opti-ui';
+```
+
+| 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…). |
+
+Also accepts all props of: `RootProps`.
+
+### Select.Root
+
+Base UI `Select.Root` re-exported unchanged. See https://base-ui.com/react/components/select.
+
+### Select.Label
+
+### Select.Trigger
+
+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: `BaseSelect.Trigger.Props`.
+
+### Select.Value
+
+### Select.Content
+
+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: `BaseSelect.Popup.Props`.
+
+### Select.Item
+
+### Select.Group
+
+### Select.GroupLabel
+
+### Select.Separator
+
+## Slider
+
+component · Forms
+
+Single value or range (pass an array) slider.
+
+```tsx
+import { Slider } from '@optimum-intelligence/opti-ui';
+```
+
+| 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). |
+
+Also accepts all props of: `BaseSlider.Root.Props`.
+
+## Switch
+
+component · Forms
+
+On/off switch with optional `label` and `description`.
+
+```tsx
+import { Switch } from '@optimum-intelligence/opti-ui';
+```
+
+```tsx
+<Switch label="Email alerts" checked={on} onCheckedChange={setOn} />
+```
+
+
+Also accepts all props of: `BaseSwitch.Root.Props`, `ChoiceLabelProps`.
+
+## Textarea
+
+component · Forms
+
+Multi-line text input. Use `TextareaField` for a labelled one.
+
+```tsx
+import { Textarea } 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). |
+
+Also accepts all props of: `React.TextareaHTMLAttributes<HTMLTextAreaElement>`.
+
+## TextareaField
+
+component · Forms
+
+Labelled textarea with description and error message.
+
+```tsx
+import { TextareaField } 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). |
+
+Also accepts all props of: `React.TextareaHTMLAttributes<HTMLTextAreaElement>`, `FieldShellProps`.
+
+## TextField
+
+component · Forms
+
+Labelled input with description and error message.
+
+```tsx
+import { TextField } 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. |
+
+Also accepts all props of: `Omit<BaseInput.Props, 'size'>`, `FieldShellProps`.
+
+## useDateConfig
+
+hook · Forms
+
+The date settings from the nearest `DateConfigProvider`. Spread it into
+`formatDate` options to format dates the same way the pickers do.
+
+```tsx
+import { useDateConfig } from '@optimum-intelligence/opti-ui';
+```
+
+Signature: `useDateConfig()`
+
+```tsx
+const config = useDateConfig();
+return <span>{formatDate(order.createdAt, { ...config, granularity: 'minute' })}</span>;
+```
+
+# Layout
+
+## AppShell
+
+component · Layout
+
+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`.
+
+```tsx
+import { AppShell } from '@optimum-intelligence/opti-ui';
+```
+
+```tsx
+<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 |
+| --- | --- | --- | --- |
+| `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: `React.HTMLAttributes<HTMLDivElement>`.
+
+## Card
+
+component · Layout
+
+Surface that groups related content. Compose with `CardHeader` (`CardTitle`, `CardDescription`,
+`CardActions`), `CardContent` and `CardFooter`.
+
+```tsx
+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>
+```
+
+| 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. |
+
+Also accepts all props of: `useRender.ComponentProps<'div', CardState>`.
+
+## CardActions
+
+compound · Layout
+
+Right-aligned slot inside CardHeader for icon buttons or menus.
+
+```tsx
+import { CardActions } from '@optimum-intelligence/opti-ui';
+```
+
+### CardActions.displayName
+
+## CardContent
+
+compound · Layout
+
+Styled `<div>` (`.oui-card__content`). Accepts `className`, `style`, the `render` prop and all `<div>` attributes.
+
+```tsx
+import { CardContent } from '@optimum-intelligence/opti-ui';
+```
+
+### CardContent.displayName
+
+## CardDescription
+
+compound · Layout
+
+Styled `<p>` (`.oui-card__description`). Accepts `className`, `style`, the `render` prop and all `<p>` attributes.
+
+```tsx
+import { CardDescription } from '@optimum-intelligence/opti-ui';
+```
+
+### CardDescription.displayName
+
+## CardFooter
+
+compound · Layout
+
+Styled `<div>` (`.oui-card__footer`). Accepts `className`, `style`, the `render` prop and all `<div>` attributes.
+
+```tsx
+import { CardFooter } from '@optimum-intelligence/opti-ui';
+```
+
+### CardFooter.displayName
+
+## CardHeader
+
+compound · Layout
+
+Styled `<div>` (`.oui-card__header`). Accepts `className`, `style`, the `render` prop and all `<div>` attributes.
+
+```tsx
+import { CardHeader } from '@optimum-intelligence/opti-ui';
+```
+
+### CardHeader.displayName
+
+## CardTitle
+
+compound · Layout
+
+Styled `<h3>` (`.oui-card__title`). Accepts `className`, `style`, the `render` prop and all `<h3>` attributes.
+
+```tsx
+import { CardTitle } from '@optimum-intelligence/opti-ui';
+```
+
+### CardTitle.displayName
+
+## Grid
+
+component · Layout
+
+Responsive dashboard grid.
+
+```tsx
+import { Grid } from '@optimum-intelligence/opti-ui';
+```
+
+| 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. |
+
+Also accepts all props of: `React.HTMLAttributes<HTMLDivElement>`.
+
+## Navbar
+
+component · Layout
+
+Collapsible side navigation. Use inside `AppShell`. Compose with `NavbarHeader` (`NavbarBrand`),
+`NavbarSection` (`NavbarSectionLabel`, `NavbarItem`) and `NavbarFooter`.
+
+```tsx
+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: `useRender.ComponentProps<'nav', NavbarState>`.
+
+## NavbarBrand
+
+component · Layout
+
+Logo, title and subtitle block for the top of a `Navbar`.
+
+```tsx
+import { NavbarBrand } from '@optimum-intelligence/opti-ui';
+```
+
+| 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. |
+
+Also accepts all props of: `Omit<useRender.ComponentProps<'div'>, 'title'>`.
+
+## NavbarFooter
+
+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';
+```
+
+### 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
+<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 |
+| --- | --- | --- | --- |
+| `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: `Omit<React.HTMLAttributes<HTMLDivElement>, 'title'>`.
+
+## 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';
+```
+
+### NavbarHeader.displayName
+
+## NavbarItem
+
+component · Layout
+
+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 { NavbarItem } 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. 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: `useRender.ComponentProps<'a', NavbarItemState>`.
+
+## NavbarSection
+
+compound · Layout
+
+Styled `<div>` (`.oui-navbar__section`). Accepts `className`, `style`, the `render` prop and all `<div>` attributes.
+
+```tsx
+import { NavbarSection } from '@optimum-intelligence/opti-ui';
+```
+
+### NavbarSection.displayName
+
+## NavbarSectionLabel
+
+compound · Layout
+
+Styled `<div>` (`.oui-navbar__section-label`). Accepts `className`, `style`, the `render` prop and all `<div>` attributes.
+
+```tsx
+import { NavbarSectionLabel } from '@optimum-intelligence/opti-ui';
+```
+
+### NavbarSectionLabel.displayName
+
+## PageHeader
+
+component · Layout
+
+Page title block with optional breadcrumbs, eyebrow, description and actions.
+
+```tsx
+import { PageHeader } 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. |
+
+Also accepts all props of: `Omit<React.HTMLAttributes<HTMLElement>, 'title'>`.
+
+## ScrollArea
+
+component · Layout
+
+Scroll container with slim, themed overlay scrollbars. Set a height or max-height.
+
+```tsx
+import { ScrollArea } 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. |
+
+Also accepts all props of: `BaseScrollArea.Root.Props`.
+
+## Separator
+
+component · Layout
+
+Thin divider line. Set `orientation="vertical"` for a vertical rule.
+
+```tsx
+import { Separator } from '@optimum-intelligence/opti-ui';
+```
+
+
+Also accepts all props of: `BaseSeparator.Props`.
+
+## Stack
+
+component · Layout
+
+Flex container that spaces its children evenly, in a column or a row.
+
+```tsx
+import { Stack } 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. |
+
+Also accepts all props of: `useRender.ComponentProps<'div', StackState>`.
+
+## StatCard
+
+component · Layout
+
+KPI tile: label, large value, optional unit and trend.
+
+```tsx
+import { StatCard } 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
+
+## Eyebrow
+
+component · Typography
+
+Small uppercase label used above titles, in filter bars and table headers.
+
+```tsx
+import { Eyebrow } from '@optimum-intelligence/opti-ui';
+```
+
+
+Also accepts all props of: `useRender.ComponentProps<'span'>`.
+
+## Heading
+
+component · Typography
+
+Heading element. `level` sets the tag (`h1`–`h6`) and the default size; `size` overrides only the look.
+
+```tsx
+import { Heading } 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. |
+
+Also accepts all props of: `useRender.ComponentProps<'h2', HeadingState>`.
+
+## Link
+
+component · Typography
+
+Text link. Pass a router link through `render`: `<Link render={<NavLink to="/fleet" />}>`.
+
+```tsx
+import { Link } 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. |
+
+Also accepts all props of: `useRender.ComponentProps<'a', LinkState>`.
+
+## Text
+
+component · Typography
+
+Body text paragraph. Use `render={<span />}` for inline text.
+
+```tsx
+import { Text } 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>`.
+
+# Actions
+
+## Button
+
+component · Actions
+
+Action button. Use `render={<a href="…" />}` with `nativeButton={false}` to style a link as a button.
+
+```tsx
+import { Button } 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`.
+
+## ContextMenu
+
+compound · Actions
+
+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 { ContextMenu } 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
+
+### ContextMenu.RadioGroup
+
+### ContextMenu.RadioItem
+
+### ContextMenu.Group
+
+### ContextMenu.GroupLabel
+
+### ContextMenu.Separator
+
+### ContextMenu.SubmenuRoot
+
+### ContextMenu.SubmenuTrigger
+
+## IconButton
+
+component · Actions
+
+Square button for a single icon. Defaults to the compact ghost style.
+
+```tsx
+import { IconButton } 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`. |
+
+Also accepts all props of: `BaseButton.Props`.
+
+## Menu
+
+compound · Actions
+
+Dropdown menu of actions. Compose `Menu.Root` › `Menu.Trigger` + `Menu.Content` › items.
+For nested menus use `Menu.SubmenuRoot` › `Menu.SubmenuTrigger` + `Menu.Content`.
+
+```tsx
+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 |
+| --- | --- | --- | --- |
+| `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`.
+
+### Menu.Item
+
+
+Also accepts all props of: `BaseMenu.Item.Props`, `ItemExtras`.
+
+### Menu.LinkItem
+
+
+Also accepts all props of: `BaseMenu.LinkItem.Props`, `Omit<ItemExtras, 'danger'>`.
+
+### Menu.CheckboxItem
+
+
+Also accepts all props of: `BaseMenu.CheckboxItem.Props`, `Omit<ItemExtras, 'icon' \| 'danger'>`.
+
+### Menu.RadioGroup
+
+Base UI `Menu.RadioGroup` re-exported unchanged. See https://base-ui.com/react/components/menu.
+
+### Menu.RadioItem
+
+
+Also accepts all props of: `BaseMenu.RadioItem.Props`, `Omit<ItemExtras, 'icon' \| 'danger'>`.
+
+### Menu.Group
+
+Base UI `Menu.Group` re-exported unchanged. See https://base-ui.com/react/components/menu.
+
+### Menu.GroupLabel
+
+### Menu.Separator
+
+### Menu.SubmenuRoot
+
+Base UI `Menu.SubmenuRoot` re-exported unchanged. See https://base-ui.com/react/components/menu.
+
+### Menu.SubmenuTrigger
+
+
+Also accepts all props of: `BaseMenu.SubmenuTrigger.Props`, `Omit<ItemExtras, 'shortcut' \| 'danger'>`.
+
+## SegmentedControl
+
+component · Actions
+
+Single-choice switcher (e.g. Day / Week / Month). Always keeps one value selected.
+
+```tsx
+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: `BaseToggleGroup.Props`.
+
+## Toggle
+
+component · Actions
+
+Two-state button (bold, pin, favourite…). Inside a ToggleGroup it acts as a segment.
+
+```tsx
+import { Toggle } from '@optimum-intelligence/opti-ui';
+```
+
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| `size?` | `'sm' \| 'md'` | `'md'` | Button height. |
+
+Also accepts all props of: `BaseToggle.Props`.
+
+## ToggleGroup
+
+component · Actions
+
+Group of `Toggle` buttons that share selection state (single or multiple).
+
+```tsx
+import { ToggleGroup } 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. |
+
+Also accepts all props of: `BaseToggleGroup.Props`.
+
+## Toolbar
+
+compound · Actions
+
+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 { Toolbar } from '@optimum-intelligence/opti-ui';
+```
+
+### Toolbar.Root
+
+### Toolbar.Button
+
+### Toolbar.Link
+
+### Toolbar.Group
+
+### Toolbar.Separator
+
+### Toolbar.Input
+
+# Overlays
+
+## AlertDialog
+
+compound · Overlays
+
+Confirmation dialog that requires an explicit choice (no outside-click dismissal).
+
+```tsx
+import { AlertDialog } from '@optimum-intelligence/opti-ui';
+```
+
+### AlertDialog.Root
+
+Base UI `AlertDialog.Root` re-exported unchanged. See https://base-ui.com/react/components/alert-dialog.
+
+### AlertDialog.Trigger
+
+Base UI `AlertDialog.Trigger` re-exported unchanged. See https://base-ui.com/react/components/alert-dialog.
+
+### AlertDialog.Content
+
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| `size?` | `Exclude<DialogSize, 'full'>` | `'sm'` | Dialog width. |
+
+Also accepts all props of: `BaseAlertDialog.Popup.Props`.
+
+### AlertDialog.Header
+
+Styled `<div>` (`.oui-dialog__header`). Accepts `className`, `style`, the `render` prop and all `<div>` attributes.
+
+### AlertDialog.Title
+
+### AlertDialog.Description
+
+### AlertDialog.Body
+
+Styled `<div>` (`.oui-dialog__body`). Accepts `className`, `style`, the `render` prop and all `<div>` attributes.
+
+### AlertDialog.Footer
+
+Styled `<div>` (`.oui-dialog__footer`). Accepts `className`, `style`, the `render` prop and all `<div>` attributes.
+
+### AlertDialog.Close
+
+Base UI `AlertDialog.Close` re-exported unchanged. See https://base-ui.com/react/components/alert-dialog.
+
+## CommandPalette
+
+component · Overlays
+
+Searchable command menu in a dialog (Ctrl / ⌘ + K) for navigation and quick
+actions. Keyboard: arrows move, Enter chooses, Esc closes.
+
+```tsx
+import { CommandPalette } from '@optimum-intelligence/opti-ui';
+```
+
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| `items` | `T[]` |  | Commands to list. |
+| `onSelect?` | `(item: T) => void` |  | Called for any chosen item, after the item's own `onSelect`. |
+| `open?` | `boolean` |  | Whether the palette is open (controlled). |
+| `defaultOpen?` | `boolean` | `false` | Initial state when uncontrolled. |
+| `onOpenChange?` | `(open: boolean) => void` |  | Called when the palette opens or closes. |
+| `search?` | `string` |  | Search text (controlled). |
+| `defaultSearch?` | `string` | `''` | Initial search text when uncontrolled. |
+| `onSearchChange?` | `(search: string) => void` |  | Called when the search text changes. |
+| `filter?` | `((item: T, search: string) => boolean) \| false` |  | Custom match function, or `false` when `items` are already filtered (server-side search). By default every term must occur in the label, keywords or group. |
+| `maxResults?` | `number` | `50` | Cap on rendered results. |
+| `hotkey?` | `string \| false` | `'k'` | Key that toggles the palette together with Ctrl / ⌘. `false` disables the shortcut. |
+| `keepOpenOnSelect?` | `boolean` |  | Keep the palette open after choosing an item. |
+| `title?` | `string` | `'Command palette'` | Accessible name of the dialog. |
+| `placeholder?` | `string` | `'Search…'` | Placeholder of the search input. |
+| `emptyText?` | `React.ReactNode` | `'No results found.'` | Shown when nothing matches. |
+| `loading?` | `boolean` |  | Show a spinner in the search row while results load. |
+| `footer?` | `React.ReactNode` |  | Content below the results (key hints, a retry button…). |
+| `className?` | `string` |  | Class name for the palette popup. |
+
+Also accepts all props of: `CommandItem = CommandItem>`.
+
+## createToastManager
+
+function · Overlays
+
+Base UI `Toast.createToastManager` re-exported unchanged. See https://base-ui.com/react/components/toast.
+
+```tsx
+import { createToastManager } from '@optimum-intelligence/opti-ui';
+```
+
+## Dialog
+
+compound · Overlays
+
+Modal dialog and side sheet. Compose:
+`Dialog.Root` › `Dialog.Trigger` + `Dialog.Content` › `Dialog.Header` (`Title`, `Description`), `Dialog.Body`, `Dialog.Footer`.
+Use `render={<Button />}` on `Dialog.Trigger` / `Dialog.Close` to style them as buttons.
+
+```tsx
+import { Dialog } from '@optimum-intelligence/opti-ui';
+```
+
+### Dialog.Root
+
+Base UI `Dialog.Root` re-exported unchanged. See https://base-ui.com/react/components/dialog.
+
+### Dialog.Trigger
+
+Base UI `Dialog.Trigger` re-exported unchanged. See https://base-ui.com/react/components/dialog.
+
+### Dialog.Content
+
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| `size?` | `'sm' \| 'md' \| 'lg' \| 'xl' \| 'full'` | `'md'` | Width of a centered dialog, or of a sheet. |
+| `placement?` | `'center' \| 'right' \| 'left' \| 'bottom'` | `'center'` | `center` modal, or a sheet docked to an edge. |
+| `showClose?` | `boolean` | `true` | Render the corner close button. |
+| `closeLabel?` | `string` | `'Close'` | Accessible name of the close button. |
+| `backdropProps?` | `BaseDialog.Backdrop.Props` |  | Props for the backdrop behind the dialog. |
+
+Also accepts all props of: `BaseDialog.Popup.Props`.
+
+### Dialog.Header
+
+Styled `<div>` (`.oui-dialog__header`). Accepts `className`, `style`, the `render` prop and all `<div>` attributes.
+
+### Dialog.Title
+
+### Dialog.Description
+
+### Dialog.Body
+
+Styled `<div>` (`.oui-dialog__body`). Accepts `className`, `style`, the `render` prop and all `<div>` attributes.
+
+### Dialog.Footer
+
+Styled `<div>` (`.oui-dialog__footer`). Accepts `className`, `style`, the `render` prop and all `<div>` attributes.
+
+### Dialog.Close
+
+Base UI `Dialog.Close` re-exported unchanged. See https://base-ui.com/react/components/dialog.
+
+### Dialog.createHandle
+
+Base UI `Dialog.createHandle` re-exported unchanged. See https://base-ui.com/react/components/dialog.
+
+## Drawer
+
+component · Overlays
+
+Side panel for inspecting or editing a record without leaving the page:
+pinned header, scrolling body, optional pinned footer. For a free-form
+sheet use `Dialog.Content` with `placement`.
+
+```tsx
+import { Drawer } from '@optimum-intelligence/opti-ui';
+```
+
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| `ref?` | `React.Ref<HTMLDivElement>` |  | Ref to the drawer panel. |
+| `open?` | `boolean` |  | Whether the drawer is open (controlled). |
+| `defaultOpen?` | `boolean` | `false` | Initial state when uncontrolled. |
+| `onOpenChange?` | `(open: boolean) => void` |  | Called when the drawer opens or closes. |
+| `trigger?` | `React.ReactElement` |  | Element that opens the drawer, e.g. `<Button>Details</Button>`. Omit when `open` is controlled. |
+| `title` | `React.ReactNode` |  | Header title; also the drawer's accessible name. |
+| `eyebrow?` | `React.ReactNode` |  | Small label above the title, e.g. the record type. |
+| `description?` | `React.ReactNode` |  | Supporting text under the title. |
+| `actions?` | `React.ReactNode` |  | Header content next to the close button (edit, delete, a menu…). |
+| `footer?` | `React.ReactNode` |  | Pinned to the bottom, for form buttons. |
+| `side?` | `'right' \| 'left'` | `'right'` | Edge the drawer slides in from. |
+| `size?` | `'sm' \| 'md' \| 'lg' \| 'xl'` | `'md'` | Width: sm 24rem, md 32rem (default), lg 48rem, xl 60rem. Override with `--oui-drawer-width`. |
+| `dismissible?` | `boolean` | `true` | Set to `false` to block Esc, outside clicks and the close button, e.g. while a form inside is saving. |
+| `modal?` | `boolean` | `true` | `false` leaves the page behind interactive and drops the backdrop. |
+| `closeLabel?` | `string` | `'Close'` | Accessible name of the close button. |
+| `className?` | `string` |  | Class name for the drawer panel. |
+| `bodyProps?` | `React.HTMLAttributes<HTMLDivElement>` |  | Props for the scrolling content area. |
+| `children?` | `React.ReactNode` |  | Drawer body content. |
+
+## Popover
+
+compound · Overlays
+
+Floating panel anchored to a trigger, for small forms, filters and details.
+
+```tsx
+import { Popover } from '@optimum-intelligence/opti-ui';
+```
+
+### Popover.Root
+
+Base UI `Popover.Root` re-exported unchanged. See https://base-ui.com/react/components/popover.
+
+### Popover.Trigger
+
+Base UI `Popover.Trigger` re-exported unchanged. See https://base-ui.com/react/components/popover.
+
+### Popover.Content
+
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| `side?` | `BasePopover.Positioner.Props['side']` | `'bottom'` | Which side of the trigger the popover opens on. |
+| `align?` | `BasePopover.Positioner.Props['align']` | `'center'` | Alignment along that side. |
+| `sideOffset?` | `BasePopover.Positioner.Props['sideOffset']` | `8` | Distance from the trigger in px. |
+| `arrow?` | `boolean` |  | Show a small arrow pointing at the trigger. |
+| `positionerProps?` | `BasePopover.Positioner.Props` |  | Props for the positioner element that places the popup. |
+
+Also accepts all props of: `BasePopover.Popup.Props`.
+
+### Popover.Title
+
+### Popover.Description
+
+### Popover.Close
+
+Base UI `Popover.Close` re-exported unchanged. See https://base-ui.com/react/components/popover.
+
+## PreviewCard
+
+compound · Overlays
+
+Card that appears when a link is hovered or focused, previewing what is behind it.
+`PreviewCard.Trigger` is the link itself. Keep the content supplementary: touch users never see it.
+
+```tsx
+import { PreviewCard } from '@optimum-intelligence/opti-ui';
+```
+
+### PreviewCard.Root
+
+Base UI `PreviewCard.Root` re-exported unchanged. See https://base-ui.com/react/components/preview-card.
+
+### PreviewCard.Trigger
+
+Base UI `PreviewCard.Trigger` re-exported unchanged. See https://base-ui.com/react/components/preview-card.
+
+### PreviewCard.Content
+
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| `side?` | `BasePreviewCard.Positioner.Props['side']` | `'bottom'` | Which side of the trigger the card opens on. |
+| `align?` | `BasePreviewCard.Positioner.Props['align']` | `'center'` | Alignment along that side. |
+| `sideOffset?` | `BasePreviewCard.Positioner.Props['sideOffset']` | `8` | Distance from the trigger in px. |
+| `arrow?` | `boolean` |  | Show a small arrow pointing at the trigger. |
+| `positionerProps?` | `BasePreviewCard.Positioner.Props` |  | Props for the positioner element that places the popup. |
+
+Also accepts all props of: `BasePreviewCard.Popup.Props`.
+
+## ToastProvider
+
+component · Overlays
+
+Mount once near the app root. Then call `useToast()` anywhere below, or pass
+a `toastManager` from `createToastManager()` to trigger toasts outside React.
+
+```tsx
+import { ToastProvider } from '@optimum-intelligence/opti-ui';
+```
+
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| `children?` | `React.ReactNode` |  | App content; toasts render over it. |
+| `placement?` | `'bottom-right' \| 'bottom-left' \| 'top-right' \| 'top-left' \| 'bottom-center' \| 'top-center'` | `'bottom-right'` | Screen corner or edge where toasts stack. |
+| `viewportClassName?` | `string` |  | Class for the viewport (positioning container). |
+
+Also accepts all props of: `Omit<BaseToast.Provider.Props, 'children'>`.
+
+## Tooltip
+
+compound · Overlays
+
+`<Tooltip content="Export"><IconButton … /></Tooltip>`.
+Wrap the app in `Tooltip.Provider` so adjacent tooltips open instantly.
+
+```tsx
+import { Tooltip } from '@optimum-intelligence/opti-ui';
+```
+
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| `content` | `React.ReactNode` |  | Tooltip text. |
+| `children` | `React.ReactElement` |  | The trigger. Must be a single element that accepts a ref (e.g. a Button). |
+| `side?` | `TooltipContentProps['side']` |  | Which side of the trigger the tooltip shows on. |
+| `align?` | `TooltipContentProps['align']` |  | Alignment along that side. |
+| `delay?` | `number` |  | Hover delay in ms. |
+| `contentProps?` | `Omit<TooltipContentProps, 'children'>` |  | Props for the tooltip popup (arrow, sideOffset, className…). |
+
+Also accepts all props of: `Omit<BaseTooltip.Root.Props, 'children'>`.
+
+### Tooltip.Provider
+
+Base UI `Tooltip.Provider` re-exported unchanged. See https://base-ui.com/react/components/tooltip.
+
+### Tooltip.Root
+
+Base UI `Tooltip.Root` re-exported unchanged. See https://base-ui.com/react/components/tooltip.
+
+### Tooltip.Trigger
+
+Base UI `Tooltip.Trigger` re-exported unchanged. See https://base-ui.com/react/components/tooltip.
+
+### Tooltip.Content
+
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| `side?` | `BaseTooltip.Positioner.Props['side']` | `'top'` | Which side of the trigger the tooltip shows on. |
+| `align?` | `BaseTooltip.Positioner.Props['align']` | `'center'` | Alignment along that side. |
+| `sideOffset?` | `BaseTooltip.Positioner.Props['sideOffset']` | `8` | Distance from the trigger in px. |
+| `arrow?` | `boolean` | `true` | Show a small arrow pointing at the trigger. |
+| `positionerProps?` | `BaseTooltip.Positioner.Props` |  | Props for the positioner element that places the popup. |
+
+Also accepts all props of: `BaseTooltip.Popup.Props`.
+
+## useToast
+
+hook · Overlays
+
+Toast API with tone shortcuts: `toast.success({ title })`.
+
+```tsx
+import { useToast } from '@optimum-intelligence/opti-ui';
+```
+
+Signature: `useToast()`
+
+# Disclosure & navigation
+
+## Accordion
+
+compound · Disclosure & navigation
+
+Expandable sections. Compose `Accordion.Root` › `Accordion.Item` (give each a `value`) ›
+`Accordion.Trigger` + `Accordion.Panel`. Pass `multiple` to `Root` to allow several open at once.
+
+```tsx
+import { Accordion } from '@optimum-intelligence/opti-ui';
+```
+
+```tsx
+<Accordion.Root defaultValue={['a']}>
+  <Accordion.Item value="a">
+    <Accordion.Trigger>Billing</Accordion.Trigger>
+    <Accordion.Panel>…</Accordion.Panel>
+  </Accordion.Item>
+</Accordion.Root>
+```
+
+### Accordion.Root
+
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| `variant?` | `'separated' \| 'plain'` | `'plain'` | `separated` renders each item as its own card; `plain` uses dividers. |
+
+Also accepts all props of: `BaseAccordion.Root.Props`.
+
+### Accordion.Item
+
+### Accordion.Trigger
+
+Header + trigger + chevron in one.
+
+### Accordion.Panel
+
+## Breadcrumb
+
+component · Disclosure & navigation
+
+One step of a breadcrumb trail. Pass a router link through `render`.
+
+```tsx
+import { Breadcrumb } from '@optimum-intelligence/opti-ui';
+```
+
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| `current?` | `boolean` | `false` | Marks the page the user is on; it renders as text instead of a link. |
+
+Also accepts all props of: `useRender.ComponentProps<'a', BreadcrumbState>`.
+
+## Breadcrumbs
+
+component · Disclosure & navigation
+
+Trail of links to the pages above the current one. Each child becomes one step.
+
+```tsx
+import { Breadcrumbs } from '@optimum-intelligence/opti-ui';
+```
+
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| `ref?` | `React.Ref<HTMLElement>` |  | Ref to the `<nav>` element. |
+| `separator?` | `React.ReactNode` |  | Shown between items. Defaults to a chevron. |
+
+Also accepts all props of: `React.HTMLAttributes<HTMLElement>`.
+
+## Collapsible
+
+compound · Disclosure & navigation
+
+A single section that shows and hides: advanced options, "show more", filter groups.
+
+```tsx
+import { Collapsible } from '@optimum-intelligence/opti-ui';
+```
+
+### Collapsible.Root
+
+### Collapsible.Trigger
+
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| `chevron?` | `boolean` | `true` | Show the chevron that turns when the panel opens. |
+
+Also accepts all props of: `BaseCollapsible.Trigger.Props`.
+
+### Collapsible.Panel
+
+## getPageItems
+
+function · Disclosure & navigation
+
+Page numbers to render, with `'gap'` where pages are skipped.
+
+```tsx
+import { getPageItems } from '@optimum-intelligence/opti-ui';
+```
+
+Signature: `getPageItems(page: number, pageCount: number, siblingCount = 1)`
+
+## Pagination
+
+component · Disclosure & navigation
+
+Controlled page navigation with an optional rows-per-page select.
+
+```tsx
+import { Pagination } from '@optimum-intelligence/opti-ui';
+```
+
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| `ref?` | `React.Ref<HTMLElement>` |  | Ref to the `<nav>` element. |
+| `page` | `number` |  | Current page, starting at 1. |
+| `pageSize` | `number` |  | Items per page. |
+| `total` | `number` |  | Total number of items across all pages. |
+| `onPageChange` | `(page: number) => void` |  | Called with the new page number. |
+| `onPageSizeChange?` | `(pageSize: number) => void` |  | Passing this adds the rows-per-page select. |
+| `pageSizeOptions?` | `number[]` | `[10, 25, 50]` | Choices in the rows-per-page select. |
+| `variant?` | `'pages' \| 'simple'` | `'pages'` | `pages` shows numbered buttons; `simple` only previous / next. |
+| `siblingCount?` | `number` | `1` | Numbered pages shown on each side of the current one. |
+| `hideRange?` | `boolean` |  | Hide the "11–20 of 87" summary. |
+| `labels?` | `Partial<PaginationLabels>` |  | Override texts for localisation. |
+
+Also accepts all props of: `Omit<React.HTMLAttributes<HTMLElement>, 'onChange'>`.
+
+## Stepper
+
+component · Disclosure & navigation
+
+Progress through an ordered sequence: a wizard, a checkout, a background job's phases.
+
+```tsx
+import { Stepper } from '@optimum-intelligence/opti-ui';
+```
+
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| `ref?` | `React.Ref<HTMLOListElement>` |  | Ref to the `<ol>` element. |
+| `steps` | `StepItem[]` |  | The steps in order. |
+| `current?` | `number` | `0` | Index of the active step. Earlier steps are complete; `steps.length` completes all of them. |
+| `orientation?` | `'horizontal' \| 'vertical'` | `'horizontal'` | Lay the steps out in a row or a column. |
+| `size?` | `'sm' \| 'md'` | `'md'` | Marker and text size. |
+| `labels?` | `Partial<StepperLabels>` |  | Screen-reader text for each status. |
+
+Also accepts all props of: `React.OlHTMLAttributes<HTMLOListElement>`.
+
+## Tabs
+
+compound · Disclosure & navigation
+
+`Tabs.Root` › `Tabs.List` › `Tabs.Tab`, then one `Tabs.Panel` per value.
+
+```tsx
+import { Tabs } from '@optimum-intelligence/opti-ui';
+```
+
+### Tabs.Root
+
+### Tabs.List
+
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| `variant?` | `'underline' \| 'segmented'` | `'underline'` | `underline` (default) for page sections, `segmented` for compact switchers. |
+| `size?` | `'sm' \| 'md'` | `'md'` | Tab height and text size. |
+
+Also accepts all props of: `BaseTabs.List.Props`.
+
+### Tabs.Tab
+
+### Tabs.Panel
+
+# Feedback & data display
+
+## Alert
+
+component · Feedback & data display
+
+Inline message for page- or section-level feedback.
+
+```tsx
+import { Alert } from '@optimum-intelligence/opti-ui';
+```
+
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| `ref?` | `React.Ref<HTMLDivElement>` |  | Ref to the alert element. |
+| `tone?` | `'info' \| 'success' \| 'warning' \| 'danger' \| 'neutral'` | `'info'` | Semantic color and default icon. `danger` and `warning` announce as an alert role. |
+| `variant?` | `'soft' \| 'outline'` | `'soft'` | `soft` (tinted, default) or `outline`. |
+| `title?` | `React.ReactNode` |  | Bold first line above the message. |
+| `icon?` | `React.ReactNode \| false` |  | Custom icon, or `false` to hide it. |
+| `actions?` | `React.ReactNode` |  | Buttons rendered after the message. |
+| `onDismiss?` | `() => void` |  | Shows a dismiss button. |
+| `dismissLabel?` | `string` | `'Dismiss'` | Accessible name of the dismiss button. |
+
+Also accepts all props of: `Omit<React.HTMLAttributes<HTMLDivElement>, 'title'>`.
+
+## Avatar
+
+component · Feedback & data display
+
+User or entity picture with initials fallback.
+
+```tsx
+import { Avatar } from '@optimum-intelligence/opti-ui';
+```
+
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| `src?` | `string` |  | Image URL. Falls back to initials or `fallback` while loading or on error. |
+| `alt?` | `string` |  | Image alt text. Defaults to `name`. |
+| `name?` | `string` |  | Name used for initials when the image is missing. |
+| `fallback?` | `React.ReactNode` |  | Explicit fallback content (overrides initials). |
+| `size?` | `'xs' \| 'sm' \| 'md' \| 'lg' \| 'xl'` | `'md'` | Diameter. |
+| `shape?` | `'circle' \| 'rounded'` | `'circle'` | Outline shape. |
+
+Also accepts all props of: `BaseAvatar.Root.Props`.
+
+## AvatarGroup
+
+component · Feedback & data display
+
+Overlapping row of `Avatar` children, with an optional "+N" overflow counter.
+
+```tsx
+import { AvatarGroup } from '@optimum-intelligence/opti-ui';
+```
+
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| `ref?` | `React.Ref<HTMLDivElement>` |  | Ref to the group element. |
+| `max?` | `number` |  | Show at most this many avatars, then a "+N" counter. |
+| `size?` | `'xs' \| 'sm' \| 'md' \| 'lg' \| 'xl'` | `'md'` | Size applied to every avatar in the group. |
+
+Also accepts all props of: `React.HTMLAttributes<HTMLDivElement>`.
+
+## Badge
+
+component · Feedback & data display
+
+Small status label.
+
+```tsx
+import { Badge } from '@optimum-intelligence/opti-ui';
+```
+
+```tsx
+<Badge tone="success">Online</Badge>
+```
+
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| `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. |
+
+Also accepts all props of: `useRender.ComponentProps<'span', BadgeState>`.
+
+## DataTable
+
+compound · Feedback & data display
+
+`<DataTable data={…} columns={…} />` renders a complete table with search,
+filters, sorting, pagination, row selection, row actions and inline editing;
+columns declare what they take part in. Every piece of state works
+uncontrolled or controlled (`search` / `filterValues` / `sort` / `page` /
+`selection`), and with `mode="server"` the same state drives an API.
+
+For another layout, create the table with `useDataTable` and compose the
+parts: `DataTable.Root`, `DataTable.Toolbar`, `DataTable.Search`,
+`DataTable.Filters`, `DataTable.Filter`, `DataTable.Actions`,
+`DataTable.Summary`, `DataTable.Content`, `DataTable.Pagination`.
+
+```tsx
+import { DataTable } from '@optimum-intelligence/opti-ui';
+```
+
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| `layout?` | `'stable' \| 'auto'` |  | `stable` (default) measures the columns once and holds their widths, keeps a short last page as tall as a full one, and keeps a row's height while it is edited: nothing moves while the table is used. `auto` leaves the layout to the browser, which fits the columns to the rows on screen. |
+| `maxHeight?` | `number \| string` |  | Scrolls the rows inside this height and keeps the header in view. |
+| `virtualized?` | `boolean \| DataTableVirtualOptions` |  | Renders only the rows in view, for thousands of rows without pagination. Rows are one line high: columns fit their longest value, so mark those with long text `truncate`. Scrolls inside `maxHeight` (default `32rem`). |
+| `onEndReached?` | `() => void` |  | Called when the rows are scrolled near their end, once per row count: load and append the next rows. Needs `maxHeight` or `virtualized`. |
+| `empty?` | `React.ReactNode` |  | Replaces the default empty state. |
+| `tableProps?` | `Omit<TableProps, 'children'>` |  | Props for the underlying `Table` (className, wrapperProps, aria-*). |
+| `pageSizeOptions?` | `number[]` |  | Choices in the rows-per-page select. |
+| `controlSize?` | `'sm' \| 'md'` |  | Size of the search box and the filters. |
+| `toolbar?` | `React.ReactNode \| ((context: DataTableToolbarContext<T>) => React.ReactNode)` |  | Extra toolbar content (export, add…). A function receives the processed rows. |
+| `className?` | `string` |  | Class name for the table's root element. |
+
+Also accepts all props of: `UseDataTableOptions<T>`, `Pick<TableProps, 'density' \| 'striped' \| 'stickyHeader'>`.
+
+### DataTable.Root
+
+Provides a table to the parts inside it.
+
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| `ref?` | `React.Ref<HTMLDivElement>` |  | Ref to the table's root element. |
+| `table` | `DataTableInstance<T>` |  | The table from `useDataTable`. |
+
+Also accepts all props of: `React.HTMLAttributes<HTMLDivElement>`.
+
+### DataTable.Toolbar
+
+Styled `<div>` (`.oui-data-table__toolbar`). Accepts `className`, `style`, the `render` prop and all `<div>` attributes.
+
+### DataTable.Search
+
+Search box of the table. Typing applies after the table's `searchDebounce`; clearing applies at once.
+
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| `size?` | `'sm' \| 'md' \| 'lg'` |  | Control height. |
+| `clearLabel?` | `string` |  | Accessible name of the clear button. |
+| `icon?` | `React.ReactNode` |  | Replaces the leading search icon. |
+| `className?` | `string` |  | Class name for the search box. |
+
+Also accepts all props of: `Omit<BaseInput.Props, 'size'>`.
+
+### DataTable.Filters
+
+Every filter of the table, with a clear button while any is active. Children are added after the filters.
+
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| `size?` | `'sm' \| 'md'` |  | Control height of every filter. |
+
+Also accepts all props of: `React.HTMLAttributes<HTMLDivElement>`.
+
+### DataTable.Filter
+
+The control of one filter: a dropdown, a toggle chip or a date range picker.
+
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| `id` | `string` |  | Id of the filter: the column id, or the `id` given in `filters`. |
+| `size?` | `'sm' \| 'md'` |  | Control height. |
+| `className?` | `string` |  | Class name for the filter control. |
+
+### DataTable.Actions
+
+Styled `<div>` (`.oui-data-table__actions`). Accepts `className`, `style`, the `render` prop and all `<div>` attributes.
+
+### DataTable.Summary
+
+Row count, or the number of selected rows, with a spinner while loading.
+
+### DataTable.Content
+
+The table itself, with its loading, empty and error states.
+
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| `layout?` | `'stable' \| 'auto'` |  | `stable` (default) measures the columns once and holds their widths, keeps a short last page as tall as a full one, and keeps a row's height while it is edited: nothing moves while the table is used. `auto` leaves the layout to the browser, which fits the columns to the rows on screen. |
+| `maxHeight?` | `number \| string` |  | Scrolls the rows inside this height and keeps the header in view. |
+| `virtualized?` | `boolean \| DataTableVirtualOptions` |  | Renders only the rows in view, for thousands of rows without pagination. Rows are one line high: columns fit their longest value, so mark those with long text `truncate`. Scrolls inside `maxHeight` (default `32rem`). |
+| `onEndReached?` | `() => void` |  | Called when the rows are scrolled near their end, once per row count: load and append the next rows. Needs `maxHeight` or `virtualized`. |
+| `empty?` | `React.ReactNode` |  | Replaces the default empty state. |
+| `tableProps?` | `Omit<TableProps, 'children'>` |  | Props for the underlying `Table` (className, wrapperProps, aria-*). |
+
+Also accepts all props of: `Pick<TableProps, 'density' \| 'striped' \| 'stickyHeader'>`.
+
+### DataTable.Pagination
+
+Page navigation of the table. Renders nothing when there are no rows, or the table is not paginated.
+
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| `ref?` | `React.Ref<HTMLElement>` |  | Ref to the `<nav>` element. |
+| `pageSizeOptions?` | `number[]` |  | Choices in the rows-per-page select. |
+| `variant?` | `'pages' \| 'simple'` |  | `pages` shows numbered buttons; `simple` only previous / next. |
+| `siblingCount?` | `number` |  | Numbered pages shown on each side of the current one. |
+| `hideRange?` | `boolean` |  | Hide the "11–20 of 87" summary. |
+| `labels?` | `Partial<PaginationLabels>` |  | Override texts for localisation. |
+
+Also accepts all props of: `Omit<React.HTMLAttributes<HTMLElement>, 'onChange'>`.
+
+## EmptyState
+
+component · Feedback & data display
+
+Placeholder for empty lists, searches without results and first-run screens.
+
+```tsx
+import { EmptyState } from '@optimum-intelligence/opti-ui';
+```
+
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| `ref?` | `React.Ref<HTMLDivElement>` |  | Ref to the root element. |
+| `icon?` | `React.ReactNode` |  | Illustration or icon above the title. |
+| `title` | `React.ReactNode` |  | What is missing, e.g. "No vehicles yet". |
+| `description?` | `React.ReactNode` |  | Explains why it is empty or what to do next. |
+| `actions?` | `React.ReactNode` |  | Buttons for the next step. |
+| `align?` | `'center' \| 'start'` | `'center'` | Center content (default) or align to start. |
+
+Also accepts all props of: `Omit<React.HTMLAttributes<HTMLDivElement>, 'title'>`.
+
+## Meter
+
+component · Feedback & data display
+
+A measurement within a known range (quota, capacity, score).
+
+```tsx
+import { Meter } from '@optimum-intelligence/opti-ui';
+```
+
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| `label?` | `React.ReactNode` |  | Label above the bar. |
+| `showValue?` | `boolean` | `true` | Show the formatted value next to the label. Defaults to `true`. |
+| `tone?` | `'accent' \| 'primary' \| 'success' \| 'warning' \| 'danger'` | `'accent'` | Bar color. |
+| `size?` | `'sm' \| 'md' \| 'lg'` | `'md'` | Bar thickness. |
+
+Also accepts all props of: `BaseMeter.Root.Props`.
+
+## Progress
+
+component · Feedback & data display
+
+Task completion. Pass `value={null}` for an indeterminate bar.
+
+```tsx
+import { Progress } from '@optimum-intelligence/opti-ui';
+```
+
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| `label?` | `React.ReactNode` |  | Label above the bar. |
+| `showValue?` | `boolean` |  | Show the formatted value next to the label. |
+| `tone?` | `'accent' \| 'primary' \| 'success' \| 'warning' \| 'danger'` | `'accent'` | Bar color. |
+| `size?` | `'sm' \| 'md' \| 'lg'` | `'md'` | Bar thickness. |
+
+Also accepts all props of: `BaseProgress.Root.Props`.
+
+## Skeleton
+
+component · Feedback & data display
+
+Pulsing placeholder for content that is still loading.
+
+```tsx
+import { Skeleton } from '@optimum-intelligence/opti-ui';
+```
+
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| `ref?` | `React.Ref<HTMLSpanElement>` |  | Ref to the placeholder element. |
+| `width?` | `number \| string` |  | Width in px (number) or any CSS length. |
+| `height?` | `number \| string` |  | Height in px (number) or any CSS length. |
+| `circle?` | `boolean` |  | Render as a circle (uses `width` for both dimensions). |
+| `radius?` | `number \| string` |  | Corner radius in px (number) or any CSS length. |
+
+Also accepts all props of: `React.HTMLAttributes<HTMLSpanElement>`.
+
+## SkeletonText
+
+component · Feedback & data display
+
+Skeleton placeholder shaped like a paragraph; the last line is shorter.
+
+```tsx
+import { SkeletonText } from '@optimum-intelligence/opti-ui';
+```
+
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| `ref?` | `React.Ref<HTMLDivElement>` |  | Ref to the wrapper element. |
+| `lines?` | `number` | `3` | Number of placeholder lines. |
+
+Also accepts all props of: `React.HTMLAttributes<HTMLDivElement>`.
+
+## Spinner
+
+component · Feedback & data display
+
+Indeterminate loading indicator that follows `currentColor`.
+
+```tsx
+import { Spinner } from '@optimum-intelligence/opti-ui';
+```
+
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| `ref?` | `React.Ref<HTMLSpanElement>` |  | Ref to the spinner element. |
+| `size?` | `number \| string` |  | Diameter, e.g. `1rem` or `24`. Defaults to `1.25em`. |
+| `label?` | `string \| null` | `'Loading'` | Accessible label. Set to `null` when a parent already announces loading. |
+
+Also accepts all props of: `React.HTMLAttributes<HTMLSpanElement>`.
+
+## Table
+
+component · Feedback & data display
+
+Styled HTML table inside a horizontally scrolling wrapper. Compose with `TableHeader`, `TableBody`,
+`TableFooter`, `TableRow`, `TableHead`, `TableCell` and `TableCaption`. For search, filters, sorting
+and pagination use `DataTable` instead.
+
+```tsx
+import { Table } from '@optimum-intelligence/opti-ui';
+```
+
+```tsx
+<Table striped>
+  <TableHeader>
+    <TableRow><TableHead>Site</TableHead><TableHead align="end">kWh</TableHead></TableRow>
+  </TableHeader>
+  <TableBody>
+    <TableRow><TableCell>Győr</TableCell><TableCell numeric>1,204</TableCell></TableRow>
+  </TableBody>
+</Table>
+```
+
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| `ref?` | `React.Ref<HTMLTableElement>` |  | Ref to the `<table>`. |
+| `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). |
+| `wrapperProps?` | `React.HTMLAttributes<HTMLDivElement>` |  | Props for the horizontally scrolling wrapper. |
+
+Also accepts all props of: `React.TableHTMLAttributes<HTMLTableElement>`.
+
+## TableBody
+
+compound · Feedback & data display
+
+Styled `<tbody>` (`.oui-table__body`). Accepts `className`, `style`, the `render` prop and all `<tbody>` attributes.
+
+```tsx
+import { TableBody } from '@optimum-intelligence/opti-ui';
+```
+
+### TableBody.displayName
+
+## TableCaption
+
+compound · Feedback & data display
+
+Styled `<caption>` (`.oui-table__caption`). Accepts `className`, `style`, the `render` prop and all `<caption>` attributes.
+
+```tsx
+import { TableCaption } from '@optimum-intelligence/opti-ui';
+```
+
+### TableCaption.displayName
+
+## TableCell
+
+component · Feedback & data display
+
+Body cell (`<td>`). `numeric` right-aligns and uses tabular figures.
+
+```tsx
+import { TableCell } from '@optimum-intelligence/opti-ui';
+```
+
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| `ref?` | `React.Ref<HTMLTableCellElement>` |  | Ref to the `<td>`. |
+| `align?` | `Align` |  | Horizontal alignment. Defaults to `end` when `numeric`, else `start`. |
+| `numeric?` | `boolean` |  | Tabular figures for numeric columns. |
+
+Also accepts all props of: `Omit<React.TdHTMLAttributes<HTMLTableCellElement>, 'align'>`.
+
+## TableFooter
+
+compound · Feedback & data display
+
+Styled `<tfoot>` (`.oui-table__footer`). Accepts `className`, `style`, the `render` prop and all `<tfoot>` attributes.
+
+```tsx
+import { TableFooter } from '@optimum-intelligence/opti-ui';
+```
+
+### TableFooter.displayName
+
+## TableHead
+
+component · Feedback & data display
+
+Column header cell (`<th>`), optionally a sort button.
+
+```tsx
+import { TableHead } from '@optimum-intelligence/opti-ui';
+```
+
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| `ref?` | `React.Ref<HTMLTableCellElement>` |  | Ref to the `<th>`. |
+| `align?` | `Align` | `'start'` | Horizontal alignment of the header content. |
+| `sort?` | `SortDirection` |  | Current sort of this column. Passing it (even `false`) makes the header sortable. |
+| `onSort?` | `() => void` |  | Called when the sortable header is clicked. |
+
+Also accepts all props of: `Omit<React.ThHTMLAttributes<HTMLTableCellElement>, 'align'>`.
+
+## TableHeader
+
+compound · Feedback & data display
+
+Styled `<thead>` (`.oui-table__header`). Accepts `className`, `style`, the `render` prop and all `<thead>` attributes.
+
+```tsx
+import { TableHeader } from '@optimum-intelligence/opti-ui';
+```
+
+### TableHeader.displayName
+
+## TableRow
+
+compound · Feedback & data display
+
+Styled `<tr>` (`.oui-table__row`). Accepts `className`, `style`, the `render` prop and all `<tr>` attributes.
+
+```tsx
+import { TableRow } from '@optimum-intelligence/opti-ui';
+```
+
+### TableRow.displayName
+
+## Tag
+
+component · Feedback & data display
+
+Label for a value the user can take away again: an active filter, a recipient, a keyword.
+
+```tsx
+import { Tag } from '@optimum-intelligence/opti-ui';
+```
+
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| `tone?` | `'neutral' \| 'accent' \| 'info' \| 'success' \| 'warning' \| 'danger'` | `'neutral'` | Semantic color. |
+| `size?` | `'sm' \| 'md'` | `'md'` | Tag height. |
+| `icon?` | `React.ReactNode` |  | Leading icon. |
+| `onRemove?` | `() => void` |  | Adds the remove button. |
+| `removeLabel?` | `string` |  | Accessible name of the remove button. Defaults to "Remove <text>". |
+| `disabled?` | `boolean` | `false` | Dims the tag and disables its remove button. |
+
+Also accepts all props of: `useRender.ComponentProps<'span', TagState>`.
+
+## useDataTable
+
+hook · Feedback & data display
+
+State and row processing of a `DataTable`, without any markup. Pass the
+result to `DataTable.Root` to lay the parts out yourself, or read `rows`,
+`filterValues` and the rest to drive something else (an export, a chart).
+
+```tsx
+import { useDataTable } from '@optimum-intelligence/opti-ui';
+```
+
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| `data` | `T[]` |  | All rows, or in server mode the rows of the current page. |
+| `columns` | `DataTableColumn<T>[]` |  | Column definitions: id, header, cell renderer, sorting, filter and layout options. |
+| `mode?` | `'client' \| 'server'` | `'client'` | `server` renders `data` as it is: search, filtering, sorting and pagination are left to the API, driven by the `search` / `filterValues` / `sort` / `page` callbacks. |
+| `total?` | `number` |  | Server mode: number of rows across all pages. |
+| `loading?` | `boolean` | `false` | Shows placeholder rows when there is no data yet, and dims the rows during a refetch. |
+| `error?` | `React.ReactNode` |  | Error message shown in place of the rows. |
+| `onRetry?` | `() => void` |  | Adds a retry button to the error message. |
+| `getRowId?` | `(row: T, index: number) => string` |  | Stable id per row, needed for selection and editing. Defaults to `row.id`, then the index. |
+| `locale?` | `string` |  | Language whose alphabet orders sorted text and filter options (`"hu"`). Defaults to the browser's. |
+| `searchable?` | `boolean` | `true` | Show the search box (default `true`). |
+| `search?` | `string` |  | Search text (controlled). |
+| `defaultSearch?` | `string` | `''` | Initial search text when uncontrolled. |
+| `onSearchChange?` | `(search: string) => void` |  | Called when the search text changes (after `searchDebounce`). |
+| `searchDebounce?` | `number` |  | Milliseconds of typing pause before the search applies. Defaults to 300 in server mode, 0 otherwise. |
+| `filter?` | `(row: T, search: string) => boolean` |  | Replaces the built-in search, which matches every term against the searchable columns. |
+| `filters?` | `DataTableFilter<T>[]` |  | Toolbar filters that are not tied to a column. Columns add theirs with `filter`. |
+| `filterValues?` | `DataTableFilterValues` |  | Filter values by filter id (controlled). |
+| `defaultFilterValues?` | `DataTableFilterValues` |  | Initial filter values when uncontrolled. |
+| `onFilterValuesChange?` | `(values: DataTableFilterValues) => void` |  | Called with all filter values when one changes or they are cleared. |
+| `sort?` | `DataTableSort \| null` |  | Column sort (controlled); `null` for none. |
+| `defaultSort?` | `DataTableSort \| null` | `null` | Initial sort when uncontrolled. |
+| `onSortChange?` | `(sort: DataTableSort \| null) => void` |  | Called when the user sorts a column. |
+| `paginated?` | `boolean` | `true` | Paginate rows (default `true`). |
+| `page?` | `number` |  | Current page, starting at 1 (controlled). |
+| `onPageChange?` | `(page: number) => void` |  | Called when the page changes. |
+| `pageSize?` | `number` |  | Rows per page (controlled). |
+| `defaultPageSize?` | `number` | `10` | Initial rows per page when uncontrolled. |
+| `onPageSizeChange?` | `(pageSize: number) => void` |  | Called when the rows per page change. |
+| `selection?` | `string[]` |  | Selected row ids. Passing `onSelectionChange` adds the checkbox column. Select-all covers every filtered row, or in server mode the current page. |
+| `onSelectionChange?` | `(selection: string[]) => void` |  | Called with the selected row ids. |
+| `onRowClick?` | `(row: T) => void` |  | Makes rows clickable and keyboard-activatable (Enter). |
+| `rowLabel?` | `(row: T) => string` |  | Accessible name of a row, used by row selection and clickable rows. |
+| `rowActions?` | `(row: T) => DataTableRowAction[] \| React.ReactNode` |  | Trailing cell of each row: icon buttons, or any content (a menu, a link). |
+| `rowTone?` | `(row: T) => DataTableRowTone \| null \| undefined` |  | Tints a row to flag its state. |
+| `rowProps?` | `(row: T) => React.HTMLAttributes<HTMLTableRowElement> & Record<`data-${string}`, unknown>` |  | Extra props for a row's `<tr>` (`className`, `style`, `data-*`). |
+| `onRowSave?` | `(row: T, original: T) => void \| Promise<void>` |  | Adds an edit action to each row; columns with `edit` turn into inputs. Called with the edited row. Return a promise to keep the row open while it saves; a rejected one leaves it open for another try. |
+| `onRowDelete?` | `(row: T) => void` |  | Adds a delete action, shown while a row is edited, or on every row without `onRowSave`. |
+| `labels?` | `Partial<DataTableLabels>` |  | Override texts for localisation. |
+
+## useDataTableContext
+
+hook · Feedback & data display
+
+The table of the surrounding `DataTable.Root`, for building custom parts.
+
+```tsx
+import { useDataTableContext } from '@optimum-intelligence/opti-ui';
+```
+
+Signature: `useDataTableContext()`
+
+# Icons & utilities
+
+## cx
+
+function · Icons & utilities
+
+Joins truthy class names.
+
+```tsx
+import { cx } from '@optimum-intelligence/opti-ui';
+```
+
+Signature: `cx(...classes: ClassValue[])`
+
+## Icons
+
+icons · Icons & utilities
+
+Small built-in stroke icon set. Every icon renders an `<svg>` that follows the font size and `currentColor`.
+
+```tsx
+import { ArrowDownIcon } from '@optimum-intelligence/opti-ui';
+```
+
+Icons: `ArrowDownIcon`, `ArrowUpIcon`, `CalendarIcon`, `CheckIcon`, `ChevronDownIcon`, `ChevronLeftIcon`, `ChevronRightIcon`, `ChevronUpIcon`, `ChevronsLeftIcon`, `ChevronsRightIcon`, `ChevronsUpDownIcon`, `CircleCheckIcon`, `CircleIcon`, `CircleXIcon`, `ClockIcon`, `ExternalLinkIcon`, `EyeIcon`, `EyeOffIcon`, `FileIcon`, `InfoIcon`, `MenuIcon`, `MinusIcon`, `MoreHorizontalIcon`, `PencilIcon`, `PlusIcon`, `SearchIcon`, `TrashIcon`, `TrendingDownIcon`, `TrendingUpIcon`, `TriangleAlertIcon`, `UploadIcon`, `XIcon`
+
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| `size?` | `number \| string` |  | Width and height. Defaults to `1em` so icons follow the font size. |
+
+## matchesQuery
+
+function · Icons & utilities
+
+True when every whitespace-separated term of `query` occurs in `text`. An empty query matches.
+
+```tsx
+import { matchesQuery } from '@optimum-intelligence/opti-ui';
+```
+
+Signature: `matchesQuery(text: unknown, query: string)`
+
+## normalizeText
+
+function · Icons & utilities
+
+Lower-cases and strips diacritics, so "gyor" matches "Győr".
+
+```tsx
+import { normalizeText } from '@optimum-intelligence/opti-ui';
+```
+
+Signature: `normalizeText(value: unknown)`
+
+## usePortalContainer
+
+hook · Icons & utilities
+
+Returns the element popups should portal into: the nearest `ThemeProvider`, or
+`undefined` for the document body. Pass it as `container` when building a custom portalled popup.
+
+```tsx
+import { usePortalContainer } from '@optimum-intelligence/opti-ui';
+```
+
+Signature: `usePortalContainer()`
+
+## withClass
+
+function · Icons & utilities
+
+Prepends a library class to a Base UI `className` prop, preserving the
+function form so consumers can still derive classes from component state.
+
+```tsx
+import { withClass } from '@optimum-intelligence/opti-ui';
+```
+
+Signature: `withClass(base: string, className: StateClassName<State>,)`