@optimum-intelligence/opti-ui 0.3.0 → 0.5.0

package/dist/llms.txt

@@ -0,0 +1,177 @@
+# 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.
+
+## Read this first
+
+- Full API reference (every component, part, prop, type, default): `node_modules/@optimum-intelligence/opti-ui/llms-full.txt`
+- Same data as JSON: `node_modules/@optimum-intelligence/opti-ui/components.json` (also `import manifest from '@optimum-intelligence/opti-ui/components.json'`)
+- Prop types and JSDoc ship in `node_modules/@optimum-intelligence/opti-ui/dist/**/*.d.ts`
+
+## 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.
+
+## Theme
+
+- `createTheme` — Builds a theme from a base, applying overrides on top.
+- `ThemeProvider` — Scopes a theme to its children. Popups opened inside are portalled into the provider so they pick up the same tokens.
+- `themeToStyle` — Converts a theme object into CSS custom properties for a `style` prop.
+
+## Forms
+
+- `Calendar` — 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.
+- `Checkbox` — Checkbox with optional `label` and `description`. Supports `indeterminate`.
+- `CheckboxGroup` — Manages the checked values of several `Checkbox` children (`value` / `onValueChange`).
+- `Combobox` — Searchable select. `<Combobox items={…} />` covers single and `multiple` (chips) selection; compose the parts for anything custom. (parts: Root, InputGroup, Input, Trigger, Clear, Value, Chips, Chip, Content, List, Item, Empty, Group, GroupLabel, Collection, useFilter)
+- `DateConfigProvider` — 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.
+- `DatePicker` — 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`.
+- `DateRangePicker` — 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.
+- `DateTimePicker` — 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`.
+- `Dropzone` — Drop target that also opens the file browser on click, Enter or Space.
+- `Field` — Field parts wire up labels, descriptions and validation for any control inside (Input, Select, Checkbox, Switch, NumberField…). (parts: Root, Label, Description, Error, Item, Validity)
+- `Fieldset` — Groups related fields under a legend. (parts: Root, Legend)
+- `FileItem` — One file in a list: name, size, upload progress or error, and a remove button.
+- `FileUpload` — File field: a dropzone plus the list of chosen files. It only collects `File` objects; upload them yourself and report progress through `fileState`.
+- `Form` — Form with Base UI validation wiring and vertical field spacing.
+- `formatDate` — 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.
+- `formatFileSize` — `1536` → `"1.5 KB"`.
+- `Input` — Text input, optionally with `startAdornment` / `endAdornment` inside the box. Use `TextField` for a labelled one.
+- `NumberField` — Numeric input with stepper buttons, locale formatting and keyboard stepping.
+- `PasswordField` — Labelled password input with description and error message.
+- `PasswordInput` — Password input with a button that reveals the value.
+- `Radio` — Radio button with optional `label` and `description`. Use inside `RadioGroup`; each needs a `value`.
+- `RadioGroup` — Single-choice group for `Radio` children (`value` / `onValueChange`).
+- `RangeCalendar` — 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.
+- `SearchInput` — Text input with a search icon and a clear button that appears once there is a value.
+- `Select` — `<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`. (parts: Root, Label, Trigger, Value, Content, Item, Group, GroupLabel, Separator)
+- `Slider` — Single value or range (pass an array) slider.
+- `Switch` — On/off switch with optional `label` and `description`.
+- `Textarea` — Multi-line text input. Use `TextareaField` for a labelled one.
+- `TextareaField` — Labelled textarea with description and error message.
+- `TextField` — Labelled input with description and error message.
+- `useDateConfig` — The date settings from the nearest `DateConfigProvider`. Spread it into `formatDate` options to format dates the same way the pickers do.
+
+## Layout
+
+- `AppShell` — 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`.
+- `Card` — Surface that groups related content. Compose with `CardHeader` (`CardTitle`, `CardDescription`, `CardActions`), `CardContent` and `CardFooter`.
+- `CardActions` — Right-aligned slot inside CardHeader for icon buttons or menus. (parts: displayName)
+- `CardContent` — Styled `<div>` (`.oui-card__content`). Accepts `className`, `style`, the `render` prop and all `<div>` attributes. (parts: displayName)
+- `CardDescription` — Styled `<p>` (`.oui-card__description`). Accepts `className`, `style`, the `render` prop and all `<p>` attributes. (parts: displayName)
+- `CardFooter` — Styled `<div>` (`.oui-card__footer`). Accepts `className`, `style`, the `render` prop and all `<div>` attributes. (parts: displayName)
+- `CardHeader` — Styled `<div>` (`.oui-card__header`). Accepts `className`, `style`, the `render` prop and all `<div>` attributes. (parts: displayName)
+- `CardTitle` — Styled `<h3>` (`.oui-card__title`). Accepts `className`, `style`, the `render` prop and all `<h3>` attributes. (parts: displayName)
+- `Grid` — Responsive dashboard grid.
+- `Navbar` — Collapsible side navigation. Use inside `AppShell`. Compose with `NavbarHeader` (`NavbarBrand`), `NavbarSection` (`NavbarSectionLabel`, `NavbarItem`) and `NavbarFooter`.
+- `NavbarBrand` — Logo, title and subtitle block for the top of a `Navbar`.
+- `NavbarFooter` — Styled `<div>` (`.oui-navbar__footer`). Accepts `className`, `style`, the `render` prop and all `<div>` attributes. (parts: displayName)
+- `NavbarGroup` — 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.
+- `NavbarHeader` — Styled `<div>` (`.oui-navbar__header`). Accepts `className`, `style`, the `render` prop and all `<div>` attributes. (parts: displayName)
+- `NavbarItem` — 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.
+- `NavbarSection` — Styled `<div>` (`.oui-navbar__section`). Accepts `className`, `style`, the `render` prop and all `<div>` attributes. (parts: displayName)
+- `NavbarSectionLabel` — Styled `<div>` (`.oui-navbar__section-label`). Accepts `className`, `style`, the `render` prop and all `<div>` attributes. (parts: displayName)
+- `PageHeader` — Page title block with optional breadcrumbs, eyebrow, description and actions.
+- `ScrollArea` — Scroll container with slim, themed overlay scrollbars. Set a height or max-height.
+- `Separator` — Thin divider line. Set `orientation="vertical"` for a vertical rule.
+- `Stack` — Flex container that spaces its children evenly, in a column or a row.
+- `StatCard` — KPI tile: label, large value, optional unit and trend.
+
+## Typography
+
+- `Eyebrow` — Small uppercase label used above titles, in filter bars and table headers.
+- `Heading` — Heading element. `level` sets the tag (`h1`–`h6`) and the default size; `size` overrides only the look.
+- `Link` — Text link. Pass a router link through `render`: `<Link render={<NavLink to="/fleet" />}>`.
+- `Text` — Body text paragraph. Use `render={<span />}` for inline text.
+
+## Actions
+
+- `Button` — Action button. Use `render={<a href="…" />}` with `nativeButton={false}` to style a link as a button.
+- `ContextMenu` — 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. (parts: Root, Trigger, Content, Item, LinkItem, CheckboxItem, RadioGroup, RadioItem, Group, GroupLabel, Separator, SubmenuRoot, SubmenuTrigger)
+- `IconButton` — Square button for a single icon. Defaults to the compact ghost style.
+- `Menu` — Dropdown menu of actions. Compose `Menu.Root` › `Menu.Trigger` + `Menu.Content` › items. For nested menus use `Menu.SubmenuRoot` › `Menu.SubmenuTrigger` + `Menu.Content`. (parts: Root, Trigger, Content, Item, LinkItem, CheckboxItem, RadioGroup, RadioItem, Group, GroupLabel, Separator, SubmenuRoot, SubmenuTrigger)
+- `SegmentedControl` — Single-choice switcher (e.g. Day / Week / Month). Always keeps one value selected.
+- `Toggle` — Two-state button (bold, pin, favourite…). Inside a ToggleGroup it acts as a segment.
+- `ToggleGroup` — Group of `Toggle` buttons that share selection state (single or multiple).
+- `Toolbar` — 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 />} />`. (parts: Root, Button, Link, Group, Separator, Input)
+
+## Overlays
+
+- `AlertDialog` — Confirmation dialog that requires an explicit choice (no outside-click dismissal). (parts: Root, Trigger, Content, Header, Title, Description, Body, Footer, Close)
+- `CommandPalette` — Searchable command menu in a dialog (Ctrl / ⌘ + K) for navigation and quick actions. Keyboard: arrows move, Enter chooses, Esc closes.
+- `createToastManager` — Base UI `Toast.createToastManager` re-exported unchanged. See https://base-ui.com/react/components/toast.
+- `Dialog` — 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. (parts: Root, Trigger, Content, Header, Title, Description, Body, Footer, Close, createHandle)
+- `Drawer` — 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`.
+- `Popover` — Floating panel anchored to a trigger, for small forms, filters and details. (parts: Root, Trigger, Content, Title, Description, Close)
+- `PreviewCard` — 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. (parts: Root, Trigger, Content)
+- `ToastProvider` — Mount once near the app root. Then call `useToast()` anywhere below, or pass a `toastManager` from `createToastManager()` to trigger toasts outside React.
+- `Tooltip` — `<Tooltip content="Export"><IconButton … /></Tooltip>`. Wrap the app in `Tooltip.Provider` so adjacent tooltips open instantly. (parts: Provider, Root, Trigger, Content)
+- `useToast` — Toast API with tone shortcuts: `toast.success({ title })`.
+
+## Disclosure & navigation
+
+- `Accordion` — 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. (parts: Root, Item, Trigger, Panel)
+- `Breadcrumb` — One step of a breadcrumb trail. Pass a router link through `render`.
+- `Breadcrumbs` — Trail of links to the pages above the current one. Each child becomes one step.
+- `Collapsible` — A single section that shows and hides: advanced options, "show more", filter groups. (parts: Root, Trigger, Panel)
+- `getPageItems` — Page numbers to render, with `'gap'` where pages are skipped.
+- `Pagination` — Controlled page navigation with an optional rows-per-page select.
+- `Stepper` — Progress through an ordered sequence: a wizard, a checkout, a background job's phases.
+- `Tabs` — `Tabs.Root` › `Tabs.List` › `Tabs.Tab`, then one `Tabs.Panel` per value. (parts: Root, List, Tab, Panel)
+
+## Feedback & data display
+
+- `Alert` — Inline message for page- or section-level feedback.
+- `Avatar` — User or entity picture with initials fallback.
+- `AvatarGroup` — Overlapping row of `Avatar` children, with an optional "+N" overflow counter.
+- `Badge` — Small status label.
+- `DataTable` — `<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. (parts: Root, Toolbar, Search, Filters, Filter, Actions, Summary, Content, Pagination)
+- `EmptyState` — Placeholder for empty lists, searches without results and first-run screens.
+- `Meter` — A measurement within a known range (quota, capacity, score).
+- `Progress` — Task completion. Pass `value={null}` for an indeterminate bar.
+- `Skeleton` — Pulsing placeholder for content that is still loading.
+- `SkeletonText` — Skeleton placeholder shaped like a paragraph; the last line is shorter.
+- `Spinner` — Indeterminate loading indicator that follows `currentColor`.
+- `Table` — 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.
+- `TableBody` — Styled `<tbody>` (`.oui-table__body`). Accepts `className`, `style`, the `render` prop and all `<tbody>` attributes. (parts: displayName)
+- `TableCaption` — Styled `<caption>` (`.oui-table__caption`). Accepts `className`, `style`, the `render` prop and all `<caption>` attributes. (parts: displayName)
+- `TableCell` — Body cell (`<td>`). `numeric` right-aligns and uses tabular figures.
+- `TableFooter` — Styled `<tfoot>` (`.oui-table__footer`). Accepts `className`, `style`, the `render` prop and all `<tfoot>` attributes. (parts: displayName)
+- `TableHead` — Column header cell (`<th>`), optionally a sort button.
+- `TableHeader` — Styled `<thead>` (`.oui-table__header`). Accepts `className`, `style`, the `render` prop and all `<thead>` attributes. (parts: displayName)
+- `TableRow` — Styled `<tr>` (`.oui-table__row`). Accepts `className`, `style`, the `render` prop and all `<tr>` attributes. (parts: displayName)
+- `Tag` — Label for a value the user can take away again: an active filter, a recipient, a keyword.
+- `useDataTable` — 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).
+- `useDataTableContext` — The table of the surrounding `DataTable.Root`, for building custom parts.
+
+## Icons & utilities
+
+- `cx` — Joins truthy class names.
+- `Icons` — Small built-in stroke icon set. Every icon renders an `<svg>` that follows the font size and `currentColor`.
+- `matchesQuery` — True when every whitespace-separated term of `query` occurs in `text`. An empty query matches.
+- `normalizeText` — Lower-cases and strips diacritics, so "gyor" matches "Győr".
+- `usePortalContainer` — 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.
+- `withClass` — Prepends a library class to a Base UI `className` prop, preserving the function form so consumers can still derive classes from component state.