# omaris — everything

The complete API followed by every guide from the documentation site.
For an index that links to one page per component, read llms.txt instead;
the pages it links to also ship in the package, under docs/.

---

# omaris

A Material 3 Expressive component library for SvelteKit. This is the
complete public API in one place, generated from the source — every prop,
its type, and whatever the source says about it. For an index that links to
one page per component instead, read llms.txt.

## Conventions that apply everywhere

- Import from `omaris`. Charts are `omaris/chart` and maps are `omaris/map`,
  separate so their heavy dependencies stay opt-in.
- `class` styles the root element and is merged last, so it always wins.
- Multi-part components also take `classes`, one Tailwind string per part:
  `<Input class="w-96" classes={{ control: 'font-mono' }} />`. The parts each
  component has are listed under it below.
- Classes merge through tailwind-merge, which only resolves conflicts within
  a group. `aspect-video` does not cancel a height; where a component ships
  one it gives you a prop instead (see `Carousel.height`).
- Every component spreads the rest of its props onto its root element, so
  native attributes and `data-*` work as usual.
- Variants are exported as `<name>Variants` for reuse on your own elements.
- Icons: hand a component an `<svg>`; it sets the size and the colour.
  omaris bundles no icon set. Lucide matches its built-in glyphs.
- Each component below opens with "Use it for" and "Not for". A "Not for"
  line names the component to use instead; follow it.

## Components

### Accordion

`import { Accordion } from 'omaris'`

MD3 expansion panels.

#### Use it for

- Stacked sections people scan by heading and open one at a time: an FAQ, a
  settings page's groups, the stages of a build. `type="single"` opens one
  and closes the rest.
- Sections read together, like a filter panel or a checklist, where several
  stay open. Use `type="multiple"`, usually with `variant="separated"` so each
  panel is its own card.
- Open state that lives elsewhere. `value` is the whole open set and is
  bindable, so it can come from the URL or storage.
- A header that carries status. `supportingText` for "Passed in 42s", `end`
  for a badge or a count, `disabled` for a stage that cannot open yet.

#### Not for

- Peers of equal weight where exactly one is visible → [Tabs](/docs/components/tabs).
- One block behind a "Show more" → [Collapsible](/docs/components/collapsible).
- Sections of a site's navigation → [Navigation Drawer](/docs/components/navigation-drawer).
- Rows the person picks from → [List](/docs/components/list).

#### Do

- Match the variant to the surface: `plain` flush on a page, `outlined` among
  other things, `separated` when each panel is its own item, like a pipeline
  stage or an order.
- Keep the trigger to one line and a `supportingText`. Put content in the
  body.
- Use `disabled` with a reason in `supportingText` ("Blocked by the failing
  tests") instead of hiding the panel.
- Leave `collapsible` on. Turn it off only when an empty accordion makes no
  sense, like a wizard that must always show the current step.

#### Don't

- Put a form's required fields in a closed panel. A hidden validation error
  blocks the submit.
- Open every panel of a `multiple` accordion by default. That is a page with
  headings; use [Text](/docs/components/text) headings.
- Put a button or a link in `heading`. The trigger is already a button.
- Nest one accordion inside another.

#### Pairs with

- [Badge](/docs/components/badge), [Card](/docs/components/card),
  [List](/docs/components/list), [Divider](/docs/components/divider),
  [Tabs](/docs/components/tabs)

| Prop | Type | Notes |
| --- | --- | --- |
| `value?` | `string[]` | Open item values. Bindable. Default `[]`. |
| `type?` | `'single' \| 'multiple'` | `single` closes the others on open; `multiple` doesn't. Default `'single'`. |
| `variant?` | `AccordionVariant` | One of `plain`, `separated`, `outlined`. Default `'plain'`. |
| `collapsible?` | `boolean` | Stop the last open item from being closed. Default `true`. |
| `class?` | `string` |  |
| `children?` | `Snippet` |  |

### AccordionItem

`import { AccordionItem } from 'omaris'`

One panel of an `Accordion`: a header you press and the content it reveals.

Parts (`classes`): `root` `trigger` `headline` `supporting` `wrapper` `content` `inner` `chevron`

| Prop | Type | Notes |
| --- | --- | --- |
| `value` | `string` | Identifies the panel in the accordion's `value`. |
| `title?` | `string` | Trigger text. |
| `supportingText?` | `string` | Second line in the trigger. |
| `disabled?` | `boolean` | Default `false`. |
| `class?` | `string` |  |
| `classes?` | `AccordionItemClasses` | Per-part Tailwind overrides. `class` still covers the root. |
| `icon?` | `Snippet` | Leading icon in the trigger. |
| `heading?` | `Snippet` | Rich trigger content, in place of `title`. |
| `end?` | `Snippet` | Trailing content before the chevron — a badge, a count. |
| `children?` | `Snippet` | The panel body. |

### AiChat

`import { AiChat } from 'omaris'`

A conversation with a model — the thread, the streaming reply, the composer, the stop button — wired to whichever model you have.

#### Use it for

- A conversation with a model, anywhere one belongs: a help desk in a
  drawer, an assistant in a dashboard's sidebar, a whole chat page. One
  `send` prop and it streams, renders markdown, scrolls, stops and retries.
- An assistant with a job. `system` says what it is for, `title` and
  `hint` greet the person, `suggestions` are the three things people ask it.
- A conversation that comes back. `bind:messages` is the whole state; save
  it in `onchange`, load it on the way in.
- A reply that shows its work. Reasoning a model streams is folded above
  its answer, with nothing to turn on.
- A composer of your own. An empty `composer` snippet takes the bar away,
  and `send()`, `stop()`, `regenerate()` and `clear()` come through
  `bind:this`.

#### Not for

- Chat between people → [List](/docs/components/list) with your own
  transport. This one has a person and a model, and the tools on a message
  (regenerate, edit) assume it.
- One question with one answer, with no thread → a
  [Text Field](/docs/components/input) and a [Card](/docs/components/card)
  for the reply.
- Making a picture → [AI Image](/docs/components/ai-image). A model that
  replies with one can still be shown here through the `message` snippet.
- Long-form output to be edited → [Rich Text Editor](/docs/components/rich-text-editor),
  with the model writing into it.

#### Do

- Keep the key on the server. `chatEndpoint('/api/chat')` here and
  `chatRoute()` from `omaris/ai` in the route, or any route that streams.
  The component reads the AI SDK's stream, plain streamed text, or a JSON
  `{ text }`.
- Return the `fetch` `Response` as is from a `send` of your own. There is
  nothing to parse on your side.
- Give it a height it can scroll in. `height` or `class="h-full"` inside a
  flex column; a chat that grows with its thread pushes the composer off
  the screen.
- Put a `disclaimer` under it when the answers matter.
- Leave the reading column alone in a wide frame. It stops at 48rem and
  centres, which is what keeps a reply readable on a full page; set
  `--chat-measure` on the root only for a different measure.
- Use `mockChat()` while the route is not there yet. It streams markdown a
  word at a time after a pause, and can fail on demand.

#### Don't

- Fight the scroll from outside. The thread follows the reply until the
  person scrolls up, and the jump button brings them back; a `scrollTo` of
  your own on every change drags them down mid-read.
- Put the model's reply in a bubble through `classes.bubble`. That slot is
  the person's message; the reply is plain text on purpose, so long answers
  and code blocks read like a document.
- Store secrets in `body` of `chatEndpoint()`. It is the request body, in
  the network tab.
- Drop `status: 'error'` messages from `messages` before resending them.
  `chatEndpoint()` already leaves them out.

#### Pairs with

- [AI Image](/docs/components/ai-image), [Sheet](/docs/components/sheet),
  [Drawer](/docs/components/navigation-drawer), [Card](/docs/components/card),
  [Chip](/docs/components/chip), [Code Block](/docs/components/code-block)

Parts (`classes`): `root` `header` `thread` `content` `user` `bubble` `assistant` `avatar` `reply` `prose` `cursor` `typing` `tools` `reasoning` `alert` `empty` `mark` `title` `description` `suggestions` `footer` `jump` `composer` `input` `disclaimer`

| Prop | Type | Notes |
| --- | --- | --- |
| `send?` | `SendFn` | Answers the conversation. `chatEndpoint('/api/chat')`, `mockChat()`, or any `(messages, ctx) => reply` of your own — a `fetch` whose `Response` you return as is will do. |
| `messages?` | `AiChatMessage[]` | The conversation. Bindable; give it a history to resume one. Default `[]`. Bindable. |
| `prompt?` | `string` | The text in the composer. Bindable. Default `''`. |
| `system?` | `string` | A system prompt, carried in the request by `chatEndpoint()`. |
| `status?` | `AiChatStatus` | Where it is. Bindable, read-only in practice. Default `'idle'`. Bindable. |
| `tone?` | `AiChatTone` | Colours the send button, the focus ring, links and the assistant's mark. One of `primary`, `secondary`, `tertiary`, `destructive`, `success`, `warning`, `info`. Default `'primary'`. |
| `height?` | `number \| string` | Height of the whole thing, in px or any CSS length. `class="h-full"` also works. Default `'32rem'`. |
| `avatar?` | `boolean` | A small mark beside each reply. The `icon` snippet replaces what is in it. Default `false`. |
| `suggestions?` | `string[]` | Prompts offered as chips before the first message. Default `[]`. |
| `assistantName?` | `string` | The name the assistant goes by, for screen readers. Default `'Assistant'`. |
| `title?` | `string` | The headline before the first message. Default `'How can I help?'`. |
| `hint?` | `string` | The line under it. |
| `placeholder?` | `string` | Default `'Message…'`. |
| `disclaimer?` | `string` | The line under the composer. |
| `disabled?` | `boolean` | Default `false`. |
| `onsend?` | `(message: AiChatMessage) => void` | Called with the message the person sent. |
| `onfinish?` | `(message: AiChatMessage) => void` | Called with the finished reply. |
| `onerror?` | `(error: Error) => void` |  |
| `onchange?` | `(messages: AiChatMessage[]) => void` | Called after any change to the conversation. |
| `class?` | `string` |  |
| `classes?` | `AiChatClasses` | Per-part Tailwind overrides. `class` still covers the root. |
| `header?` | `Snippet` | Above the thread. |
| `icon?` | `Snippet` | The assistant's mark, in the empty state and the `avatar`. Defaults to sparkles. |
| `empty?` | `Snippet<[AiChatEmptyContext]>` | Replaces the empty thread. |
| `message?` | `Snippet<[AiChatMessageContext]>` | Replaces what a message shows — the bubble's text, or the reply's. |
| `actions?` | `Snippet<[AiChatMessageContext]>` | Extra buttons under a message, after copy, regenerate and edit. |
| `composer?` | `Snippet<[AiChatComposerContext]>` | Replaces the composer. An empty snippet takes it away. |

### AiImage

`import { AiImage } from 'omaris'`

A picture made from a sentence — the frame, the prompt bar, the wait and the picture, wired to whichever model you have.

#### Use it for

- Any place a picture is made from words: a cover for a playlist, a hero
  for a landing page, a product placeholder, a logo sketch, an avatar. One
  `generate` prop and it has the bar, the spinner, the fade-in and the tools.
- Editing a picture rather than starting over. `attach` takes one from the
  person; the edit tool feeds a result back in. Either way the generator is
  handed `reference`, and `gemini()` and `openaiImages()` both use it.
- A picture with nothing to press. `prompt` and `auto` make it on mount and
  again when the prompt changes; `composer="none"` and `tools={[]}` leave
  only the frame.
- Several at once. `count` tiles them in the frame; tap one to keep it.
  `history` keeps every result on a strip under it.
- Your own controls around the frame. `composer="none"`, then `generate()`,
  `cancel()`, `clear()` and `download()` through `bind:this`.

#### Not for

- Choosing a picture that already exists → [File Upload](/docs/components/file-upload)
  or [Image Viewer](/docs/components/image-viewer).
- Cropping or rotating a picture → [Image Cropper](/docs/components/image-cropper).
- A conversation about the picture → [AI Chat](/docs/components/ai-chat),
  with this in a message snippet if the reply is a picture.
- Loading a picture you already have the URL for. A plain `<img>` with a
  [Skeleton](/docs/components/skeleton) is enough; the wait here is for a
  picture that does not exist yet.

#### Do

- Keep the key on the server. `endpoint('/api/image')` here, and `gemini()`,
  `openaiImages()` or `imageRoute()` from `omaris/ai` in the route.
- Set `aspect`. It is both the shape of the frame and what the model is asked
  for, so the picture lands in a frame that already fits it.
- Give `suggestions`. An empty frame with three good prompts on it is used;
  an empty frame with a blank field is stared at.
- Bind `images` if the session matters — it is every result, newest first,
  and the strip and the viewer both read from it.
- Return `text` from your generator when the model says something about the
  picture, and set `caption` to show it.
- Use `mockGenerate()` while the backend is not there yet. It makes an
  abstract picture from the prompt after a believable wait, so the screen
  is designed against the real states.
- Reach for the `loading` snippet when the wait should say more than a
  spinner — it is handed the provider's `progress`, `message` and `partial`.

#### Don't

- Put an API key in `gemini({ apiKey })` in a browser. It ships to everyone
  who opens the page.
- Set `auto` without a `prompt` you control. Every keystroke into a bound
  prompt is a request.
- Hand it a `src` you have not waited on and expect the fade. A picture it
  makes itself is decoded behind the spinner before it fades in; one passed
  in from outside just shows, so preload it or wrap it in a
  [Skeleton](/docs/components/skeleton).
- Raise `count` past what the model makes in one call. Gemini makes one per
  call, so `count={4}` is four calls, billed as four.
- Leave out a stop with `composer="none"`. The frame shows only a spinner,
  so your own controls call `cancel()`, or a slow model has no way out.

#### Pairs with

- [AI Chat](/docs/components/ai-chat), [Drawing Board](/docs/components/drawing-board)
  (its `ai` prop takes the same `generate`), [File Upload](/docs/components/file-upload),
  [Image Viewer](/docs/components/image-viewer), [Chip](/docs/components/chip),
  [Card](/docs/components/card), [Dialog](/docs/components/dialog)

Parts (`classes`): `root` `frame` `canvas` `grid` `cell` `image` `loader` `spinner` `empty` `emptyIcon` `title` `description` `suggestions` `alert` `tools` `caption` `composer` `attachment` `input` `controls` `history` `thumb`

| Prop | Type | Notes |
| --- | --- | --- |
| `generate?` | `GenerateFn` | Makes the pictures. `gemini({ apiKey })`, `openaiImages({ apiKey })`, `endpoint('/api/image')`, `mockGenerate()`, or any `(request, ctx) => results` of your own. |
| `prompt?` | `string` | The prompt in the bar. Bindable. Default `''`. |
| `auto?` | `boolean` | Generate as soon as there is a prompt — on mount, and again when it changes. Default `false`. |
| `aspect?` | `AiImageAspect` | The shape of the picture. Also the shape of the frame. Default `'1:1'`. |
| `height?` | `number \| string` | Frame height, in px or any CSS length. Replaces the aspect. |
| `count?` | `number` | How many pictures per prompt. Above one they tile in the frame. Default `1`. |
| `reference?` | `string \| Blob` | A picture to edit or draw from — a URL, data URL or `Blob`. Bindable: the attach button and the edit tool set it. Default `undefined`. Bindable. |
| `params?` | `Record<string` | Model-specific knobs, passed through untouched in the request. |
| `src?` | `string` | The picture on show. Bindable; set it to start with one. Default `undefined`. Bindable. |
| `images?` | `AiImageItem[]` | Every picture made so far, newest first. Bindable. Default `[]`. |
| `keep?` | `number` | How many past pictures to keep in `images`. Default `24`. |
| `status?` | `AiImageStatus` | Where it is. Bindable, read-only in practice. Default `'idle'`. Bindable. |
| `alt?` | `string` | Alt text for the results. Defaults to the prompt. |
| `tone?` | `AiImageTone` | One of `primary`, `secondary`, `tertiary`, `destructive`, `success`, `warning`, `info`. Default `'primary'`. |
| `variant?` | `AiImageVariant` | One of `filled`, `outlined`, `ghost`. Default `'filled'`. |
| `size?` | `AiImageSize` | One of `sm`, `md`, `lg`. Default `'md'`. |
| `composer?` | `AiImageComposer` | `below` the frame, `overlay` on it, or `none` for a prompt UI of your own. One of `below`, `overlay`, `none`. Default `'below'`. |
| `tools?` | `AiImageTool[]` | The buttons over a finished picture. `[]` for none. Default `DEFAULT_TOOLS`. |
| `history?` | `boolean` | Keep a strip of past results under the frame. Default `false`. |
| `viewer?` | `boolean` | Tap a finished picture to open it full-screen. Default `false`. |
| `caption?` | `boolean` | Show the model's words about the picture, under it, when there are any. Default `false`. |
| `attach?` | `boolean` | Offer an attach button in the bar, so a person can drop a picture in to edit. Default `false`. |
| `suggestions?` | `string[]` | Prompts offered as chips before anything is made. Default `[]`. |
| `title?` | `string` | The headline of the empty frame. |
| `hint?` | `string` | The line under it. |
| `placeholder?` | `string` | Default `'Describe the picture you want…'`. |
| `generateLabel?` | `string` | Accessible name of the send button. Default `'Generate'`. |
| `submitOnEnter?` | `boolean` | A submit with nothing typed. Defaults to Enter; `false` needs the button. Default `true`. |
| `disabled?` | `boolean` | Default `false`. |
| `onstart?` | `(request: AiImageRequest) => void` |  |
| `onresult?` | `(images: AiImageItem[]) => void` |  |
| `onerror?` | `(error: Error) => void` |  |
| `oncancel?` | `() => void` |  |
| `onchange?` | `(image: AiImageItem \| undefined) => void` | Called when the picture on show changes — a new result, a history pick, a clear. |
| `ondownload?` | `(image: AiImageItem) => void` |  |
| `class?` | `string` |  |
| `classes?` | `AiImageClasses` | Per-part Tailwind overrides. `class` still covers the root. |
| `empty?` | `Snippet<[AiImageEmptyContext]>` | Replaces the empty frame. |
| `loading?` | `Snippet<[AiImageLoadingContext]>` | Replaces the spinner. Drawn on the loader's surface. |
| `image?` | `Snippet<[AiImageResultContext]>` | Replaces one finished picture. |
| `error?` | `Snippet<[AiImageErrorContext]>` | Replaces the error. |
| `bar?` | `Snippet<[AiImageComposerContext]>` | Replaces the prompt bar. |
| `actions?` | `Snippet<[AiImageResultContext]>` | Extra buttons in the corner toolbar. |
| `children?` | `Snippet` | Content under the frame, before the bar — a caption, a legend. |

### Alert

`import { Alert } from 'omaris'`

Alert — MD3's banner, for a message that belongs to the page rather than floating over it.

#### Use it for

- A message that belongs to the page and stays until the problem clears: a
  failed payment method, a maintenance window, an unverified email. `tonal`
  (the default) at the top of the content, under the
  [Top App Bar](/docs/components/top-app-bar).
- A form-level error listing what to fix. `tone="destructive"` announces
  itself at once; `variant="plain"` is an inline one with no container.
- A quieter note inside a form, like "Applies to every member". Use
  `outlined` or `bar`.
- A message with a way out. `actions` holds one or two buttons ("Fix", "Learn
  more"); `dismissible` lets the person close it.

#### Not for

- Confirming something just happened, like "Saved" or "Sent" →
  [Toast](/docs/components/toast).
- A decision that must be made before continuing →
  [Dialog](/docs/components/dialog). An alert never blocks.
- A one-word status on an item, like "Overdue" → [Badge](/docs/components/badge).
- A hint about one field → that field's `supportingText` on the
  [Text Field](/docs/components/input).
- A list with nothing in it → [Empty](/docs/components/empty).

#### Do

- Keep one alert at the top of a page. Two stacked banners cancel each other
  out.
- Lead with a `title` that says what is wrong and a `description` that says
  what to do. Drop the title for a one-line note.
- Match `tone` to the meaning: `destructive` for broken, `warning` for about
  to break, `info` (the default) for worth knowing, `success` for a state.
  A success event is a toast.
- Keep `dismissible` off while the problem is still there.

#### Don't

- Fire one from an event handler. A message that answers a press is a
  [Toast](/docs/components/toast).
- Put a third button in `actions`. It belongs on the page the first two point
  to.
- Use `size="lg"` in a dashboard column. It is for a landing page or a
  full-width notice.
- Swap the icon to decorate. The tone's own icon makes it readable without
  colour.

#### Pairs with

- [Toast](/docs/components/toast), [Dialog](/docs/components/dialog),
  [Button](/docs/components/button), [Empty](/docs/components/empty),
  [Text Field](/docs/components/input)

Parts (`classes`): `root` `icon` `body` `title` `description` `actions` `close`

| Prop | Type | Notes |
| --- | --- | --- |
| `tone?` | `AlertTone` | One of `primary`, `secondary`, `tertiary`, `destructive`, `success`, `warning`, `info`. Default `'info'`. |
| `variant?` | `AlertVariant` | One of `tonal`, `outlined`, `bar`, `plain`. Default `'tonal'`. |
| `size?` | `AlertSize` | One of `sm`, `md`, `lg`. Default `'md'`. |
| `title?` | `string` | Heading line. |
| `description?` | `string` | Body text. Use children for rich content. |
| `showIcon?` | `boolean` | Draw the tone's default icon. Default `true`. |
| `dismissible?` | `boolean` | Adds the trailing ×. Default `false`. |
| `ondismiss?` | `() => void` |  |
| `class?` | `string` |  |
| `classes?` | `AlertClasses` | Per-part Tailwind overrides. `class` still covers the root. |
| `icon?` | `Snippet` | Replaces the tone's default icon. |
| `children?` | `Snippet` | Body content, in place of `description`. |
| `actions?` | `Snippet` | Buttons under the body. |

### AppShell

`import { AppShell } from 'omaris'`

The frame a dashboard is built in.

#### Use it for

- The frame of a dashboard. `AppShellSidebar` holds a `NavigationDrawer`,
  `AppShellMain` holds a `TopAppBar` and `AppShellContent`. Only the content
  column scrolls; the sidebar and bar stay put with no `sticky` anywhere.
- An inspector on the trailing edge, like the selected row's details. Add a
  second `AppShellSidebar side="end"`.
- A bar a selection needs, or a form's unsaved-changes strip.
  `AppShellFooter sticky` holds the bottom of the column.
- A page's reading measure. `AppShellContent width` defaults to `full`, which
  a table wants; `md` for prose, `sm` for a lone form.

#### Not for

- A marketing or landing page → a plain layout. The document should scroll.
- A sign-in screen → a centred [Card](/docs/components/card) on the page.
- Panes the person drags → [Resizable](/docs/components/resizable) inside
  `AppShellMain`. The shell's sidebar is a fixed column.
- Long articles where the address bar should collapse on a phone →
  `scroll="page"`, which scrolls the document and sticks the sidebar instead.

#### Do

- Put it in `+layout.svelte` once. Pages render inside `AppShellContent`.
- Plan the phone. The sidebar column is gone below `breakpoint` (`md` by
  default), so a phone needs a modal
  [Navigation Drawer](/docs/components/navigation-drawer) rendered outside
  the sidebar, or a [Navigation Bar](/docs/components/navigation-bar) in the
  main column.
- Use `padded={false}` when a page brings its own edges, like a full-bleed
  map or a kanban board.
- Use `AppShellHeader` for a bar plus a filter row that must stay up together.
  A `TopAppBar` on its own sticks by itself and finds the scroller from the
  shell.

#### Don't

- Put `h-screen` or `overflow-auto` on your own wrappers inside it. The shell
  already picked the scrolling element; a second one brings back the double
  scrollbar.
- Pass `scrollContainer` to a `TopAppBar` inside the shell. It already knows.
- Nest an `AppShell` per route.
- Leave `width="full"` on a page of prose. Lines a screen wide do not read.

#### Pairs with

- [Navigation Drawer](/docs/components/navigation-drawer), [Top App Bar](/docs/components/top-app-bar),
  [Navigation Bar](/docs/components/navigation-bar), [Resizable](/docs/components/resizable),
  [Breadcrumb](/docs/components/breadcrumb)

| Prop | Type | Notes |
| --- | --- | --- |
| `scroll?` | `NonNullable<Variants['scroll']>` | Which element scrolls: the content column, or the document. Default `'main'`. |
| `class?` | `string` |  |
| `children?` | `Snippet` |  |

### AppShellContent

`import { AppShellContent } from 'omaris'`

The padded well a page's content sits in.

| Prop | Type | Notes |
| --- | --- | --- |
| `width?` | `NonNullable<Variants['width']>` | One of `sm`, `md`, `lg`, `xl`, `full`. Default `'full'`. |
| `padded?` | `boolean` | Gutter and the rhythm between sections. Off when the page brings its own. Default `true`. |
| `class?` | `string` |  |
| `children?` | `Snippet` |  |

### AppShellFooter

`import { AppShellFooter } from 'omaris'`

The bottom band of the content column.

| Prop | Type | Notes |
| --- | --- | --- |
| `sticky?` | `boolean` | Hold it at the bottom of the column rather than after the content. Default `false`. |
| `class?` | `string` |  |
| `children?` | `Snippet` |  |

### AppShellHeader

`import { AppShellHeader } from 'omaris'`

A band that stays at the top of the content column while it scrolls.

| Prop | Type | Notes |
| --- | --- | --- |
| `sticky?` | `boolean` | Ride up with the content instead of staying put. Default `true`. |
| `class?` | `string` |  |
| `children?` | `Snippet` |  |

### AppShellMain

`import { AppShellMain } from 'omaris'`

The content column of an `AppShell` — and, in the default scroll mode, the element that scrolls.

| Prop | Type | Notes |
| --- | --- | --- |
| `class?` | `string` |  |
| `children?` | `Snippet` |  |

### AppShellSidebar

`import { AppShellSidebar } from 'omaris'`

The column an `AppShell` puts beside its main area — a navigation drawer, usually.

| Prop | Type | Notes |
| --- | --- | --- |
| `side?` | `'start' \| 'end'` | Which edge it sits on. `end` gives you an inspector panel instead. Default `'start'`. |
| `breakpoint?` | `AppShellSidebarBreakpoint` | Viewport width at which the column appears. `false` keeps it at every size — what you want when the thing inside is already responsive. Default `'md'`. |
| `label?` | `string` | Accessible name, when the column isn't a single labelled drawer. |
| `class?` | `string` |  |
| `children?` | `Snippet` |  |

### AreaChart

`import { AreaChart } from 'omaris/chart'`

Area chart.

#### Use it for

- A value over time → `LineChart`. The same with the space under it filled,
  which reads as "amount" → `AreaChart`, `stacked` when the series add up to
  a total.
- Categories → `BarChart`, `horizontal` when the names are long, `grouped` or
  `stacked` when several series share a band.
- Parts of a small whole → `PieChart`, `donut` with the total in `centre`,
  for up to about five slices. Too many parts, or one that dwarfs the rest →
  `TreemapChart`, with `group` for one level of nesting.
- Stages → `FunnelChart`, `drop` for stage over stage. Correlation →
  `ScatterChart`, `size` for a bubble. Open, high, low, close →
  `CandlestickChart`. A magnitude and a rate on two scales → `ComboChart`
  with `axis: 'right'`. Several measures on one shape → `RadarChart`.
- A few progress-shaped values → `RadialBarChart`. One number against a
  range → `Gauge`. A trend inside a stat tile or a table cell → `Sparkline`.

#### Not for

- More than about six rings → a `BarChart`. Inner rings of a
  `RadialBarChart` get shorter for the same value, so the comparison is off.
- A pie of twelve slices, or one slice at 90% → `TreemapChart`, or a sorted
  `horizontal` `BarChart`.
- One number with no range → a `display-sm` [Text](/docs/components/text) in
  a [Card](/docs/components/card). With a range → [Gauge](/docs/components/gauge)
  from the core entry, which needs no peer dependency.
- Exact values people read off and compare → [Table](/docs/components/table).
- Places → [Map](/docs/components/map).

#### Do

- Import from `omaris/chart` and add `layerchart` and `d3-shape` as peers.
  It is opt-in so a page with only a Button pays nothing for it; see
  [Charts and maps](/docs/charts-and-maps).
- Give every chart a `label`. The SVG is `role="img"` and that is its name.
- Pass `error` (and `onRetry`) when the request failed. A failed fetch must
  not draw a clean empty pair of axes; `emptyText` is for a real nothing.
- Keep the `series` shape. Swapping a line for an area or a bar is a one-word
  change, and `references` (a target, an SLO), `annotations`, `brush`, `zoom`
  and `csv` work the same on all of them.
- Switch to `legend="isolate"` once there are more than two series.

#### Don't

- Set the height from a class. `height` is a prop, and the frame is what
  layerchart measures.
- Put anything hover-dependent in a `Sparkline`. It is inert on purpose so it
  cannot swallow a tap inside a row.
- Ask a `ComboChart` for grouped bars beside a line. Bars stack there; use a
  `BarChart` and a second chart.
- Hand-pick a `color` per series unless it means something, like a team's
  colour or a status. The palette already follows the theme.

#### Pairs with

- [Card](/docs/components/card), [Gauge](/docs/components/gauge),
  [Table](/docs/components/table), [Text](/docs/components/text),
  [Charts and maps](/docs/charts-and-maps)

| Prop | Type | Notes |
| --- | --- | --- |
| `stacked?` | `boolean` | Pile the series on top of each other rather than overlapping them. Default `false`. |
| `curve?` | `ChartCurve` | Default `'smooth'`. |
| `fillOpacity?` | `number` | Opacity of the fill under each line. Default `0.18`. |
| `points?` | `boolean` | Mark each data point. Default `false`. |
| `data` | `T[]` |  |
| `x?` | `Field<T>` | The category or time field. |
| `y?` | `Field<T>` | The value field. Ignored once `series` names its own. |
| `series?` | `ChartSeries<T>[]` | Several values per row. Each gets a colour and a legend entry. |
| `height?` | `number \| string` | Plot height. A number is px; a string is any CSS length. Default `260`. |
| `axis?` | `boolean \| 'x' \| 'y'` | `true` for both, or just the one you want. Default `true`. |
| `grid?` | `boolean` | Default `true`. |
| `legend?` | `ChartLegend` | `true` shows the legend and lets a click toggle a series off. `'isolate'` makes a click show that series alone, and a second one bring the rest back — which is the move you actually want on a chart with six lines on it. Default `false`. |
| `tooltip?` | `boolean` | Default `true`. |
| `formatX?` | `(value: never) => string` | Tick labels along the x axis. |
| `formatY?` | `(value: never) => string` | Tick labels along the y axis, and the tooltip's values. |
| `colors?` | `readonly string[]` | Palette override, cycled across the series. Default `CHART_COLORS`. |
| `padding?` | `number \| { top?: number; right?: number; bottom?: number; left?: number }` | Space around the plot, in px — room for long axis labels. |
| `label?` | `string` | Accessible description of what the chart shows. |
| `class?` | `string` |  |
| `empty?` | `Snippet` | Shown in place of the plot when `data` is empty. |
| `emptyText?` | `string` |  |
| `error?` | `boolean \| string \| Error` | Something went wrong. Truthy puts the chart into its error state; a string or an `Error` supplies the message. |
| `errorText?` | `string` | The message, when `error` is just `true`. |
| `errorState?` | `Snippet<[{ message: string }]>` | Replaces the whole error state. |
| `onRetry?` | `() => void` | Offers a "Try again" button in the error state. |
| `csv?` | `boolean \| string` | Offer the plotted rows as a CSV download, from a button in the corner. A string names the file. Default `false`. |
| `csvColumns?` | `(string \| { key: string; label?: string; value?: (row: T) => unknown })[]` | Which fields the download writes, in order. Defaults to every field. |
| `references?` | `ChartReference[]` | Lines and bands at fixed values — targets, thresholds, windows. |
| `annotations?` | `ChartAnnotation[]` | Notes pinned to a point. |
| `brush?` | `ChartBrush` | Drag across the plot to select a range, and zoom the chart to it. |
| `zoom?` | `ChartZoom` | Wheel or pinch to zoom, drag to pan. |

### Avatar

`import { Avatar } from 'omaris'`

Avatar — image, initials, or icon, in that order of preference.

#### Use it for

- A person in a table row, a comment, an assignee on a card. `src` when there
  is a photo, `name` for initials when there is not, an icon in `children`
  when there is neither. The initials show until the image has decoded.
- A team, an organisation, a product. `shape="square"` is the rounded square
  for things that are not people.
- Presence. `status="online"`, `away`, `busy` or `offline` puts a dot on the
  edge of the shape, at every size, without clipping it.
- The people on a thread or a project, stacked. `AvatarGroup` with `overflow`
  for the trailing "+n".

#### Not for

- A picture that is content, not identity, like a product photo → an `<img>`,
  or [Image Viewer](/docs/components/image-viewer) when it opens full screen.
- A count or a status word beside a name → [Badge](/docs/components/badge).
  The presence dot is the only state an avatar carries.
- Choosing a person from a list → [Combobox](/docs/components/combobox) with
  an Avatar in each row and the picked one as a [Chip](/docs/components/chip).
- A decorative icon in a tinted circle on an empty screen →
  [Empty](/docs/components/empty), which draws that circle itself.

#### Do

- Pass `name` even when `src` is set. It shows while the photo loads and
  stays if the URL 404s, so a broken image never leaves a hole.
- Turn on `colorize` everywhere or nowhere. The hue comes from the name, so
  the same person is the same colour on every screen only if every avatar
  opts in.
- Give `AvatarGroup` the same `size` as the avatars inside it. The overlap is
  per size and a mismatch shows at once.
- Use `xs` and `sm` in a table cell or a chip, `md` in a list row, `lg` and
  `xl` in a profile header.

#### Don't

- Add `overflow-hidden` on the root to round a photo. The `media` slot
  already clips, and the presence dot sits outside the root.
- Write `initials` by hand unless the derived pair is wrong, like a mononym
  or a company name. "Ada L." already becomes "AL".
- Stack more than about five in a group. That is what `overflow` is for.

#### Pairs with

- [Badge](/docs/components/badge), [List](/docs/components/list),
  [Table](/docs/components/table), [Chip](/docs/components/chip),
  [Tooltip](/docs/components/tooltip)

Parts (`classes`): `root` `media` `image` `status`

| Prop | Type | Notes |
| --- | --- | --- |
| `size?` | `AvatarSize` | One of `sm`, `md`, `lg`, `xl`. Default `'md'`. |
| `shape?` | `AvatarShape` | One of `circle`, `square`. Default `'circle'`. |
| `status?` | `AvatarStatus` | Presence dot in the bottom corner. One of `none`, `online`, `away`, `busy`, `offline`. Default `'none'`. |
| `src?` | `string` |  |
| `alt?` | `string` |  |
| `name?` | `string` | Full name. Initials and the fallback tint are derived from it. |
| `initials?` | `string` | Override the derived initials. |
| `colorize?` | `boolean` | Paint the initials fallback with the name-derived tint. Default `false`. |
| `class?` | `string` |  |
| `classes?` | `AvatarClasses` | Per-part Tailwind overrides. `class` still covers the root. |
| `children?` | `Snippet` | Shown when there's no image and no name — an icon, usually. |

### AvatarGroup

`import { AvatarGroup } from 'omaris'`

A stack of overlapping avatars — the people on a thread, the members of a team.

| Prop | Type | Notes |
| --- | --- | --- |
| `size?` | `AvatarSize` | Overlap amount. Must match the avatars' own `size` to look right. One of `xs`, `sm`, `md`, `lg`, `xl`. Default `'md'`. |
| `overflow?` | `number` | Renders a "+n" chip after the children. |
| `class?` | `string` |  |
| `classes?` | `ClassesOf<typeof avatarGroupVariants>` | Tailwind per part. |
| `children?` | `Snippet` |  |

### Badge

`import { Badge } from 'omaris'`

Badge — a status pill, or the count that rides on an icon.

#### Use it for

- A count on an icon: unread on a bell, items in a cart. `value` with
  `anchor="top-end"` on a `relative` parent, and `max` so 100 reads "99+".
- "Something new" with no number. `dot` on a
  [Navigation Bar](/docs/components/navigation-bar) item or an
  [Icon Button](/docs/components/icon-button).
- A read-only status on a row or a card: "Paid", "Draft", "Beta". A labelled
  pill, `tonal` or `outlined`, with `tone` carrying the meaning.
- A coloured word in a table cell. `variant="text"` when a pill in every row
  is too loud.

#### Not for

- Anything pressable, like a filter or a removable tag → [Chip](/docs/components/chip).
  A badge has no state layer and no focus ring.
- A sentence → [Alert](/docs/components/alert).
- A number people compare across rows → [Text](/docs/components/text) with
  `tabular-nums`, or a [Gauge](/docs/components/gauge).
- A message that should be noticed now → [Toast](/docs/components/toast). A
  badge waits to be seen.

#### Do

- Give a count or a dot a `label`: "3 unread", not "3", so a screen reader
  says what the number is.
- Put `relative` on the parent before you `anchor`. The badge is positioned
  absolutely and needs a box to pin to.
- Keep one tone per meaning across the app: `success` paid, `warning`
  pending, `destructive` failed.
- Clear the dot as soon as the thing has been seen. A dot that never goes
  away means nothing.

#### Don't

- Use `filled` for status pills in a table. A column of solid capsules fights
  the data; use `tonal` or `outlined`.
- Show a zero. No `value`, no badge.
- Anchor a count to something nobody will act on. "99+" on a log tab is
  noise.

#### Pairs with

- [Icon Button](/docs/components/icon-button),
  [Navigation Bar](/docs/components/navigation-bar), [Avatar](/docs/components/avatar),
  [Table](/docs/components/table), [Chip](/docs/components/chip)

| Prop | Type | Notes |
| --- | --- | --- |
| `variant?` | `BadgeVariant` | One of `filled`, `tonal`, `outlined`, `text`. Default `'filled'`. |
| `tone?` | `BadgeTone` | One of `primary`, `secondary`, `tertiary`, `destructive`, `success`, `warning`, `info`. Default `'primary'`. |
| `size?` | `BadgeSize` | One of `sm`, `md`, `lg`. Default `'md'`. |
| `dot?` | `boolean` | Renders the 6dp dot instead of a label. Default `false`. |
| `value?` | `number` | A number badge. Values above `max` render as "99+", and the pill stays a circle until two digits force it wider. |
| `max?` | `number` | Cap for `value`. Default `99`. |
| `anchor?` | `BadgeAnchor` | Corner of the `relative` parent to pin to. One of `none`, `top-end`, `top-start`. Default `'none'`. |
| `label?` | `string` | Screen-reader text — "3 unread", not "3". |
| `class?` | `string` |  |
| `children?` | `Snippet` |  |

### BarChart

`import { BarChart } from 'omaris/chart'`

Bar chart.

| Prop | Type | Notes |
| --- | --- | --- |
| `horizontal?` | `boolean` | Bars run along the x axis, categories down the y one. Default `false`. |
| `stacked?` | `boolean` | Pile several series into one bar. Default `false`. |
| `grouped?` | `boolean` | Sit several series side by side within the band. Default `false`. |
| `radius?` | `number` | Corner radius on the bars, in px. Default `4`. |
| `labels?` | `boolean` | Print the value on each bar. Default `false`. |
| `data` | `T[]` |  |
| `x?` | `Field<T>` | The category or time field. |
| `y?` | `Field<T>` | The value field. Ignored once `series` names its own. |
| `series?` | `ChartSeries<T>[]` | Several values per row. Each gets a colour and a legend entry. |
| `height?` | `number \| string` | Plot height. A number is px; a string is any CSS length. Default `260`. |
| `axis?` | `boolean \| 'x' \| 'y'` | `true` for both, or just the one you want. Default `true`. |
| `grid?` | `boolean` | Default `true`. |
| `legend?` | `ChartLegend` | `true` shows the legend and lets a click toggle a series off. `'isolate'` makes a click show that series alone, and a second one bring the rest back — which is the move you actually want on a chart with six lines on it. Default `false`. |
| `tooltip?` | `boolean` | Default `true`. |
| `formatX?` | `(value: never) => string` | Tick labels along the x axis. |
| `formatY?` | `(value: never) => string` | Tick labels along the y axis, and the tooltip's values. |
| `colors?` | `readonly string[]` | Palette override, cycled across the series. Default `CHART_COLORS`. |
| `padding?` | `number \| { top?: number; right?: number; bottom?: number; left?: number }` | Space around the plot, in px — room for long axis labels. |
| `label?` | `string` | Accessible description of what the chart shows. |
| `class?` | `string` |  |
| `empty?` | `Snippet` | Shown in place of the plot when `data` is empty. |
| `emptyText?` | `string` |  |
| `error?` | `boolean \| string \| Error` | Something went wrong. Truthy puts the chart into its error state; a string or an `Error` supplies the message. |
| `errorText?` | `string` | The message, when `error` is just `true`. |
| `errorState?` | `Snippet<[{ message: string }]>` | Replaces the whole error state. |
| `onRetry?` | `() => void` | Offers a "Try again" button in the error state. |
| `csv?` | `boolean \| string` | Offer the plotted rows as a CSV download, from a button in the corner. A string names the file. Default `false`. |
| `csvColumns?` | `(string \| { key: string; label?: string; value?: (row: T) => unknown })[]` | Which fields the download writes, in order. Defaults to every field. |
| `references?` | `ChartReference[]` | Lines and bands at fixed values — targets, thresholds, windows. |
| `annotations?` | `ChartAnnotation[]` | Notes pinned to a point. |
| `brush?` | `ChartBrush` | Drag across the plot to select a range, and zoom the chart to it. |
| `zoom?` | `ChartZoom` | Wheel or pinch to zoom, drag to pan. |

### Breadcrumb

`import { Breadcrumb } from 'omaris'`

Breadcrumbs.

#### Use it for

- Where a page sits in a hierarchy three or more levels deep: region,
  customer, order. Give every crumb but the last an `href`.
- Client-side routing with no URL to give. A crumb with `onclick` and no
  `href` renders as a button.
- A trail that gets long. Past `maxItems` it collapses in the middle, and the
  "…" expands in place instead of navigating.

#### Not for

- The app's top-level sections → [Navigation Drawer](/docs/components/navigation-drawer)
  or [Navigation Bar](/docs/components/navigation-bar).
- Views within one page → [Tabs](/docs/components/tabs).
- A page one level deep → a back arrow in the `leading` slot of the
  [Top App Bar](/docs/components/top-app-bar).
- Steps in a flow that happen in order → [Progress](/docs/components/progress)
  for how far, a [Button](/docs/components/button) for next. Crumbs are
  places, not stages.

#### Do

- Mirror the URL: one crumb per segment a person could land on, in the order
  they nest.
- Use the entity's name as the label: "Acme Ltd", not "Customer: Acme Ltd".
  The position implies the level.
- Put it above the page title in the content column, not in the app bar.
- Raise `itemsAfterCollapse` when the deep levels matter most, which in a
  dashboard they usually do.

#### Don't

- Link the last crumb to itself. It is marked current and rendered as text.
- Make it the only way off a phone screen. It is small and wraps badly, so
  give the phone a back arrow too.
- Truncate labels with a class. Let the trail collapse in the middle; the
  ends carry the meaning.

#### Pairs with

- [Top App Bar](/docs/components/top-app-bar), [Navigation Drawer](/docs/components/navigation-drawer),
  [App Shell](/docs/components/app-shell), [Text](/docs/components/text)

Parts (`classes`): `root` `list` `item` `link` `current` `separator` `expand`

| Prop | Type | Notes |
| --- | --- | --- |
| `items` | `BreadcrumbItem[]` |  |
| `size?` | `BreadcrumbSize` | One of `sm`, `md`. Default `'md'`. |
| `maxItems?` | `number` | Collapse the middle once the trail is longer than this. `0` never collapses. Default `5`. |
| `itemsBeforeCollapse?` | `number` | Crumbs kept at the start of a collapsed trail. Default `1`. |
| `itemsAfterCollapse?` | `number` | Crumbs kept at the end of a collapsed trail. Default `2`. |
| `label?` | `string` | Accessible name. Default `'Breadcrumb'`. |
| `class?` | `string` |  |
| `classes?` | `BreadcrumbClasses` | Per-part Tailwind overrides. `class` still covers the root. |
| `separator?` | `Snippet` | Custom separator, in place of the chevron. |

### Button

`import { Button } from 'omaris'`

MD3 buttons, the Expressive way.

#### Use it for

- The main action on a screen or dialog. Use `filled`, once per view.
- The actions next to it. `tonal` for the second most important, `outlined`
  or `text` for the rest.
- An action that takes a moment. Pass `loading`; the label stays and a
  spinner appears.

#### Not for

- A link that only changes the URL → give it `href` and it renders an `<a>`.
  `variant="link"` is for a link inside a sentence.
- An icon with no label → [Icon Button](/docs/components/icon-button).
- The floating main action on a phone → [FAB](/docs/components/fab).
- One action plus a menu of alternatives → [Split Button](/docs/components/split-button).
- Picking between options → [Segmented Button](/docs/components/segmented-button)
  or filter [Chips](/docs/components/chip).

#### Do

- Keep one `filled` button per view. Everything else is `tonal`, `outlined`
  or `text`.
- Write labels in sentence case, verb first: "Save changes", not "SAVE" or
  "OK".
- Give destructive actions `tone="destructive"` and confirm them in a
  [Dialog](/docs/components/dialog).

#### Don't

- Wrap a label onto two lines, or put two icons in one button.
- Disable a button to explain why it cannot be pressed. Keep it enabled and
  say why in the supporting text or a toast.
- Use `size="lg"` or `xl` in a dashboard. They are for landing screens.

#### Pairs with

- [Icon Button](/docs/components/icon-button), [Button Group](/docs/components/button-group),
  [Split Button](/docs/components/split-button), [Dialog](/docs/components/dialog),
  [Toast](/docs/components/toast)

| Prop | Type | Notes |
| --- | --- | --- |
| `variant?` | `ButtonVariant` | Fill style. MD3's five, plus `link` for inline navigation. One of `filled`, `tonal`, `elevated`, `outlined`, `text`, `link`. Default `'filled'`. |
| `tone?` | `ButtonTone` | Color role the fill style paints with. One of `primary`, `secondary`, `tertiary`, `destructive`, `success`, `warning`, `info`. Default `'primary'`. |
| `size?` | `ButtonSize` | MD3 Expressive heights: 32 / 40 / 56 / 96 / 136dp. One of `xs`, `sm`, `md`, `lg`, `xl`. Default `'sm'`. |
| `shape?` | `ButtonShape` | Pill (`round`) or MD3 rounded rectangle (`square`). One of `round`, `square`. Default `'round'`. |
| `icon?` | `boolean` | Square, label-less button. Requires an `aria-label`. Default `false`. |
| `ripple?` | `boolean` | Material ripple on press. Set false for a flat, instant button. Default `true`. |
| `confetti?` | `boolean \| ConfettiOptions` | Confetti on press. `true` for the default burst, or any `ConfettiOptions` — `confetti={{ preset: 'fireworks' }}`. Default `false`. |
| `loading?` | `boolean` | Grows a spinner in at the start of the button and blocks interaction. The label stays put; only an `icon` button swaps its icon out. Default `false`. |
| `toggle?` | `boolean` | Turns the button into a two-state toggle driven by `pressed`. Ignored when `href` is set — a link has no pressed state. Default `false`. |
| `pressed?` | `boolean` | Selected state of a toggle button. Bindable. Default `false`. |
| `class?` | `string` |  |
| `children?` | `Snippet` |  |

### ButtonGroup

`import { ButtonGroup } from 'omaris'`

MD3 button group — a row of buttons that reads as one control.

#### Use it for

- A row of actions that reads as one control: Undo/Redo,
  Bold/Italic/Underline, Zoom in/out. `connected` is the default: pill ends
  outside, squared joins inside, a hairline gap between.
- A segmented control built from full `Button`s. `toggle` buttons with
  `pressed` inside a `connected` group, when a segment needs an `href`, a
  `loading` state or its own tone.
- `spaced` when the buttons stay separate but should sit on the 8dp rhythm: a
  card's action row, a dialog footer.
- `orientation="vertical"` for a stacked control in a narrow side panel;
  `full` for a group that fills a phone width or a sheet edge to edge.

#### Not for

- One choice out of two to five that you bind a value to →
  [Segmented Button](/docs/components/segmented-button). It owns the
  selection and draws the tick; a group only lays buttons out.
- One default action plus a menu of the rest →
  [Split Button](/docs/components/split-button).
- Filters that can wrap or scroll and can all be off →
  [Chips](/docs/components/chip) in a `ChipGroup`.
- Page numbers → [Pagination](/docs/components/pagination).
- Two unrelated buttons that happen to be neighbours → a flex container with
  `gap-2`.

#### Do

- Give every child the same `variant` and `size`. The group reshapes the
  corners; it does not unify the fills.
- Pass `label`. It becomes the `aria-label` of the `role="group"`, so a
  screen reader can say what the row is for.
- Use [Icon Buttons](/docs/components/icon-button) as the children of a
  toolbar group, each with its own `aria-label`.

#### Don't

- Mix `filled` and `outlined` children in a `connected` group. The joins only
  read as one control when the fills match.
- Go past five in a row. Beyond that it is a toolbar: `spaced` clusters with
  a [Divider](/docs/components/divider) between them.
- Use `full` at desktop width. The buttons stretch into bars; it is for a
  phone or a sheet.

#### Pairs with

- [Button](/docs/components/button), [Icon Button](/docs/components/icon-button),
  [Segmented Button](/docs/components/segmented-button),
  [Split Button](/docs/components/split-button), [Divider](/docs/components/divider)

| Prop | Type | Notes |
| --- | --- | --- |
| `variant?` | `ButtonGroupVariant` | One of `connected`, `spaced`. Default `'connected'`. |
| `orientation?` | `ButtonGroupOrientation` | One of `horizontal`, `vertical`. Default `'horizontal'`. |
| `full?` | `boolean` | Default `false`. |
| `label?` | `string` | Accessible name for the group. |
| `class?` | `string` |  |
| `children?` | `Snippet` |  |

### Calendar

`import { Calendar } from 'omaris'`

Month grid — one date, a range, or a handful of dates.

#### Use it for

- A date picked by looking at the month it falls in — a delivery day, a
  booking, a shift — where seeing the weekday and the week around it is the
  point.
- A span of days with `mode="range"`: a stay, a leave request, a report
  period. `months={2}` shows a range that crosses a month end without paging.
- Several separate days with `mode="multiple"` — rota shifts, class dates,
  blackout days.
- A calendar that stays on the page: a booking sidebar, a scheduling panel,
  the body of a card. For one that opens from a field, reach for the field.

#### Not for

- A date inside a form, shown as text until it is edited →
  [Date Field](/docs/components/date-field). It wraps this calendar in a
  popover on a desktop and a sheet on a phone.
- A period filter on a dashboard, with shortcuts like "Last 30 days" →
  [Date Range Field](/docs/components/date-range-field).
- A date far from today — a birthday, an expiry year → the `DatePicker`
  wheels in [Picker](/docs/components/picker). Paging back forty years a
  month at a time is the wrong tool, even with the year grid.
- A time of day → `TimePicker` in [Picker](/docs/components/picker).
- Showing events across a month or a week. This picks dates; it does not lay
  out a schedule.

#### Do

- Keep values at local midnight — `new Date(2026, 2, 3)`, or `startOfDay` on
  anything else. The calendar hands back midnights, and compares by day.
- Set `min` and `max` whenever the valid window is known. The arrows stop at
  its months and the out-of-range days grey out, which is kinder than an
  error after the fact.
- Use `isDateDisabled` for the rules a window cannot express — weekends,
  holidays, sold-out nights.
- Leave `locale` and `weekStartsOn` alone unless the page's language is wrong
  for the calendar. Both follow `<html lang>`, and a week that starts on the
  wrong day is the first thing people notice.

#### Don't

- Build dates from ISO strings — `new Date('2026-03-03')` is UTC midnight,
  which is the 2nd of March west of Greenwich.
- Expect a range's `value` to change on the first press. It is set once the
  range is whole; the half-drawn state is the calendar's own.
- Set `showOutsideDays` with two months — the neighbouring month is already
  on screen, so it is ignored.
- Squeeze it much under 280px. The cells shrink to fit, but below about 36px
  a day is hard to hit with a finger.

#### Pairs with

- [Date Field](/docs/components/date-field), [Date Range Field](/docs/components/date-range-field),
  [Popover](/docs/components/popover), [Sheet](/docs/components/sheet),
  [Card](/docs/components/card), [Picker](/docs/components/picker)

Parts (`classes`): `root` `months` `month` `header` `caption` `nav` `grid` `weeks` `row` `weekday` `weekNumber` `cell` `day` `track` `band` `face` `picker` `pickerHeader` `pickerGrid` `pickerItem`

| Prop | Type | Notes |
| --- | --- | --- |
| `mode?` | `M` | `'single'` (the default), `'range'` or `'multiple'`. Decides what `value` holds. |
| `value?` | `CalendarValue<M>` | The selection, at local midnight. A `Date` or `null` in `single`, `{ start, end }` or `null` in `range` — set on the second press, never half-filled — and a sorted `Date[]` in `multiple`. Bindable. |
| `month?` | `Date` | The first month on screen. Defaults to the selection's month, or today's. Bindable. |
| `min?` | `Date` | Earliest selectable day. The previous button stops at its month. |
| `max?` | `Date` | Latest selectable day. The next button stops at its month. |
| `isDateDisabled?` | `(date: Date) => boolean` | Days that cannot be picked — weekends, holidays, sold-out dates. |
| `locale?` | `string` | BCP-47 tag for names and the first weekday. Defaults to `<html lang>`, then the browser. |
| `weekStartsOn?` | `Weekday` | 0 is Sunday. Defaults to the locale's own first day. |
| `months?` | `1 \| 2` | Months side by side. They stack below the `sm` breakpoint. Default `1`. |
| `showOutsideDays?` | `boolean` | Fill the first and last rows with the neighbouring months' days. Ignored with two months, where the neighbour is already on screen. Default `true`. |
| `showWeekNumbers?` | `boolean` | ISO week numbers at the start of each row. Default `false`. |
| `weekdayFormat?` | `'narrow' \| 'short'` | Weekday headings: `narrow` ("M") or `short` ("Mon"). Default `'narrow'`. |
| `autofocus?` | `boolean` | Focus the active day as soon as the calendar mounts — for one that opens in a popup. Default `false`. |
| `swipe?` | `boolean` | Swipe sideways on a touch screen to change month. Default `true`. |
| `haptics?` | `boolean` | Vibrate on a pick, where the haptics store is on. Default `true`. |
| `labels?` | `CalendarLabels` | Accessible names for the arrows, the caption and the week column — for translation. |
| `onchange?` | `(value: CalendarValue<M>) => void` | Fires with the new value after every pick — for `range`, once the range is whole. |
| `class?` | `string` | Merged onto the root, so `class="p-0"` removes the padding. |
| `classes?` | `CalendarClasses` | Per-part Tailwind overrides. `class` still covers the root. |

### CandlestickChart

`import { CandlestickChart } from 'omaris/chart'`

Candlestick chart — open, high, low and close in one mark per period.

| Prop | Type | Notes |
| --- | --- | --- |
| `data` | `T[]` |  |
| `x?` | `Field<T>` | The period field. Defaults to `row.date`. Default `'date'`. |
| `open?` | `Field<T>` | Defaults to `row.open`. Default `'open'`. |
| `high?` | `Field<T>` | Defaults to `row.high`. Default `'high'`. |
| `low?` | `Field<T>` | Defaults to `row.low`. Default `'low'`. |
| `close?` | `Field<T>` | Defaults to `row.close`. Default `'close'`. |
| `height?` | `number \| string` | Plot height. A number is px; a string is any CSS length. Default `300`. |
| `axis?` | `boolean \| 'x' \| 'y'` | `true` for both, or just the one you want. Default `true`. |
| `grid?` | `boolean` | Default `true`. |
| `tooltip?` | `boolean` | Default `true`. |
| `up?` | `string` | Any CSS colour for a period that closed up. Default `'var(--success)'`. |
| `down?` | `string` | Any CSS colour for a period that closed down. Default `'var(--destructive)'`. |
| `hollow?` | `boolean` | Draw rising candles as outlines rather than fills. Default `false`. |
| `width?` | `number` | Share of the band each candle body takes. Default `0.62`. |
| `formatX?` | `(value: never) => string` | Tick labels along the x axis. |
| `formatY?` | `(value: never) => string` | Tick labels along the y axis, and the tooltip's values. |
| `padding?` | `number \| { top?: number; right?: number; bottom?: number; left?: number }` | Space around the plot, in px. |
| `label?` | `string` | Accessible description of what the chart shows. |
| `class?` | `string` |  |
| `empty?` | `Snippet` |  |
| `emptyText?` | `string` |  |
| `error?` | `boolean \| string \| Error` | Something went wrong. Truthy puts the chart into its error state; a string or an `Error` supplies the message. |
| `errorText?` | `string` | The message, when `error` is just `true`. |
| `errorState?` | `Snippet<[{ message: string }]>` | Replaces the whole error state. |
| `onRetry?` | `() => void` | Offers a "Try again" button in the error state. |
| `csv?` | `boolean \| string` | Offer the plotted rows as a CSV download, from a button in the corner. A string names the file. Default `false`. |
| `csvColumns?` | `(string \| { key: string; label?: string; value?: (row: T) => unknown })[]` | Which fields the download writes, in order. Defaults to every field. |
| `references?` | `ChartReference[]` | Lines and bands at fixed values — targets, thresholds, windows. |
| `annotations?` | `ChartAnnotation[]` | Notes pinned to a point. |
| `brush?` | `ChartBrush` | Drag across the plot to select a range, and zoom the chart to it. |
| `zoom?` | `ChartZoom` | Wheel or pinch to zoom, drag to pan. |

### Card

`import { Card } from 'omaris'`

MD3 card — elevated, filled, or outlined.

#### Use it for

- One thing with a heading, a body and its actions: an invoice, an order, a
  project. `CardHeader`, `CardContent`, `CardFooter`. The body grows, so a
  row of cards with different amounts of content still lines its footers up.
- A grid of pressable tiles. Give the card `href` or `onclick` and it becomes
  a real target with a ripple and a focus ring, with no wrapper `<a>`.
- A picker, like plans or delivery options. `interactive` and `selected`,
  with `aria-pressed` on each so the choice is read out.
- An image-led card. `CardMedia` with a `ratio`; `bleed` is on by default so
  the picture reaches the edges and rounds only the corners it touches.

#### Not for

- Rows of the same shape you read down → [List](/docs/components/list).
  Several columns you compare or sort → [Table](/docs/components/table).
- Grouping a form's fields → whitespace and a [Text](/docs/components/text)
  heading. A card around every fieldset is a page of boxes.
- Pictures of unequal height in a wall → [Masonry](/docs/components/masonry)
  around the cards, not a grid of cards with cropped images.

#### Do

- Pick the variant by what is underneath. `outlined` (the default) reads
  well on a plain page. A dashboard grid usually wants `elevated`, so cards
  read as separate objects without a hairline each. `filled` is for a card
  inside another surface, like a sheet or a dialog.
- Set `level` on `CardHeader` to fit the page outline. The default `3`
  assumes the page has an `h2` above it.
- Leave `CardFooter` actions at the end. `align="between"` is only for
  keeping a destructive action apart from the safe one.
- Put a menu or a badge in the header's `end` slot, an avatar or icon in
  `start`.

#### Don't

- Nest a card in a card. Use `CardContent` with a `Divider` or a `List`
  inside it.
- Put a button, a link or a menu inside an `interactive` card. Make the
  whole card the target, or none of it.
- Give a card more than one `filled` button. One action commits; the rest
  are `text`.
- Add a `border` class to make an `elevated` card visible on a busy surface.
  Switch to `outlined` instead.

#### Pairs with

- [Button](/docs/components/button), [Icon Button](/docs/components/icon-button),
  [Avatar](/docs/components/avatar), [Badge](/docs/components/badge),
  [Masonry](/docs/components/masonry), [Skeleton](/docs/components/skeleton)

| Prop | Type | Notes |
| --- | --- | --- |
| `variant?` | `CardVariant` | One of `elevated`, `filled`, `outlined`. Default `'outlined'`. |
| `size?` | `CardSize` | One of `md`, `lg`. Default `'md'`. |
| `interactive?` | `boolean` | Force the interactive treatment on a card that handles its own press. |
| `selected?` | `boolean` | Chosen state — border and ring in the primary color. Default `false`. |
| `ripple?` | `boolean` | Ripple on press. Interactive cards only. Default `true`. |
| `class?` | `string` |  |
| `children?` | `Snippet` |  |
| `tone?` | `ButtonTone` | Color role the fill style paints with. |
| `shape?` | `ButtonShape` | Pill (`round`) or MD3 rounded rectangle (`square`). |
| `icon?` | `boolean` | Square, label-less button. Requires an `aria-label`. |
| `confetti?` | `boolean \| ConfettiOptions` | Confetti on press. `true` for the default burst, or any `ConfettiOptions` — `confetti={{ preset: 'fireworks' }}`. |
| `loading?` | `boolean` | Grows a spinner in at the start of the button and blocks interaction. The label stays put; only an `icon` button swaps its icon out. |
| `toggle?` | `boolean` | Turns the button into a two-state toggle driven by `pressed`. Ignored when `href` is set — a link has no pressed state. |
| `pressed?` | `boolean` | Selected state of a toggle button. Bindable. |

### CardContent

`import { CardContent } from 'omaris'`

A card's body — the text and controls between its header and its footer.

| Prop | Type | Notes |
| --- | --- | --- |
| `class?` | `string` |  |
| `children?` | `Snippet` |  |

### CardFooter

`import { CardFooter } from 'omaris'`

A card's actions, laid out in a row that wraps.

| Prop | Type | Notes |
| --- | --- | --- |
| `align?` | `'start' \| 'end' \| 'between'` | Where the actions sit. MD3 puts card actions at the end. Default `'end'`. |
| `class?` | `string` |  |
| `children?` | `Snippet` |  |

### CardHeader

`import { CardHeader } from 'omaris'`

The heading row of a card: a leading slot, a title block, a trailing slot.

Parts (`classes`): `root` `start` `body` `title` `description` `end`

| Prop | Type | Notes |
| --- | --- | --- |
| `heading?` | `string` | Heading text. Use the `title` snippet instead for rich markup. |
| `description?` | `string` | Supporting line under the heading. |
| `level?` | `2 \| 3 \| 4 \| 5 \| 6` | Heading level, so cards nest correctly in a page outline. Default `3`. |
| `class?` | `string` |  |
| `classes?` | `CardHeaderClasses` | Per-part Tailwind overrides. `class` still covers the root. |
| `start?` | `Snippet` | Leading slot — an avatar or icon. |
| `end?` | `Snippet` | Trailing slot — an overflow menu, a badge. |
| `title?` | `Snippet` | Rich heading, in place of `heading`. |
| `supporting?` | `Snippet` | Rich supporting line, in place of `description`. |

### CardMedia

`import { CardMedia } from 'omaris'`

The image at the top of a card.

| Prop | Type | Notes |
| --- | --- | --- |
| `src?` | `string` |  |
| `alt?` | `string` | Default `''`. |
| `ratio?` | `'16/9' \| '4/3' \| '1/1' \| '3/2' \| 'auto'` | Common MD3 media ratios. Default `'16/9'`. |
| `bleed?` | `boolean` | Cancels the card's padding so the media reaches the edges, and keeps only the corners it actually touches rounded. Default `true`. |
| `class?` | `string` |  |
| `children?` | `Snippet` | Overlaid content — a play button, a gradient caption. |

### Carousel

`import { Carousel } from 'omaris'`

MD3 carousel.

#### Use it for

- A shelf of visual things where one is in front and the rest peek: product
  photos, places, featured content. The default `hero` layout, or `centered`
  when the front item should sit in the middle.
- A browsing row of many equal cards: "more like this", a team, a set of
  templates. `variant="uncontained"` with an `itemWidth`.
- A highlights banner that runs itself. `variant="full"`, `autoplay` and
  `loop`. It pauses under the pointer, on focus, and off screen.
- A story: full-bleed slides on a timer, tapped through. `variant="story"`
  with `autoplay`, `indicators` for the segmented bar, and `header`/`footer`
  for the name and the actions over it. Onboarding, a release tour, a daily
  recap.
- A front item that something else follows, like a caption, a thumbnail
  strip or a map pin. `bind:index`.

#### Not for

- Pictures the person wants to see all at once → [Masonry](/docs/components/masonry)
  or a plain grid. A carousel hides everything but the front.
- Looking closely at one picture → [Image Viewer](/docs/components/image-viewer).
  Wrap each item in an `ImageViewerItem` and the carousel becomes the gallery.
- Steps that are not visual, like a wizard → a morphing [Dialog](/docs/components/dialog)
  or [Tabs](/docs/components/tabs).
- Rows of text → [List](/docs/components/list).

#### Do

- Give it a `label` ("Product photos"), and an `itemLabel` when "3 of 6" is
  not a useful name for an item.
- Pin a caption with `w-(--carousel-card)` and fade it with
  `opacity-(--carousel-reveal)`, so it is clipped instead of re-wrapped as
  the card folds into a strip.
- Fill the card: images `object-cover` at `size-full`. Size the viewport with
  the `height` prop, or use `height="auto"` plus an `aspect-*` on
  `classes.viewport` to size by ratio.
- Add `controls` where a mouse is likely, like a dashboard or a desktop
  shelf. A finger swipes without them.
- Hold a story open with `bind:paused` while something else has the screen:
  a menu, a dialog, a buffering video. Use `oncomplete` to move to the next
  story or close the screen.
- Put only controls in a story's `header` and `footer`. Links, buttons and
  fields there stay clickable; everything else taps through, so a wide label
  between two buttons does not eat the tap that advances the story.

#### Don't

- `autoplay` content people need to read or act on. It is for ambient
  highlights, not a form or a list of offers.
- Put twenty items in a `hero` carousel. Nobody pages that far; use
  `uncontained` or a wall.
- Put text that has to wrap, or a form, inside an item. Strips fold and clip
  whatever is in them.
- Give a story slides that have to be read. A person gets one hold and one
  tap-back, not a second reading.
- Write `h-56` in `class` to size it. The base sets its own height; the
  `height` prop replaces it.

#### Pairs with

- [Image Viewer](/docs/components/image-viewer), [Card](/docs/components/card),
  [Masonry](/docs/components/masonry), [Icon Button](/docs/components/icon-button),
  [Segmented Button](/docs/components/segmented-button)

Parts (`classes`): `root` `frame` `viewport` `track` `item` `strip` `control` `indicators` `dot` `segments` `segment` `segmentFill` `header` `footer`

| Prop | Type | Notes |
| --- | --- | --- |
| `items` | `T[]` |  |
| `item` | `Snippet<[T, CarouselItemContext]>` | How to draw one item. It fills the card; images should `object-cover`. |
| `variant?` | `CarouselVariant` | One of `hero`, `centered`, `multi-browse`, `full`, `story`, `uncontained`. Default `'hero'`. |
| `index?` | `number` | The item in front. Bindable. Default `0`. |
| `gap?` | `number` | Gap between items, in px. Defaults to 8, and to 0 for a story. |
| `stripWidth?` | `number` | Width of a peeking strip, in px. Default `56`. |
| `itemWidth?` | `number` | Item width for `uncontained`, in px. Default `240`. |
| `loop?` | `boolean` | Wrap around at the ends. With enough items to fill the row it is a true loop — the last folds into the first in either direction; with fewer, the ends still join but by a cut. Default `false`. |
| `autoplay?` | `number` | Advance every this many ms. Pauses under the pointer, on focus, and offscreen — a story instead pauses while held, while a key has focused it, and whenever `paused` is set. Default `0`. |
| `controls?` | `boolean` | Draw prev/next buttons. Default `false`. |
| `indicators?` | `boolean` | Draw the dots. Default `false`. |
| `label?` | `string` | Accessible name — "Product photos". |
| `itemLabel?` | `(item: T, index: number) => string` | Names each item for assistive tech. Defaults to "n of total". |
| `onchange?` | `(index: number) => void` |  |
| `oncomplete?` | `() => void` | The last slide's timer ran out with `loop` off — the story is over. |
| `header?` | `Snippet<[T, CarouselItemContext]>` | Drawn across the top of the frame, over the slide: a name, a time, a close button. Direct children of it are clickable; everything around them still taps through to the story. |
| `footer?` | `Snippet<[T, CarouselItemContext]>` | The same, across the bottom: actions, a reply box. |
| `paused?` | `boolean` | Held open by the caller — a menu is up, a video is buffering. Bindable. A press-and-hold is not written back here — it is its own state, read from the root's `data-held` attribute. Default `false`. Bindable. |
| `height?` | `number \| string` | How tall the viewport is. A number is px, a string is any CSS length. Defaults to `14rem`, and to `30rem` for a story — `100dvh` for one that fills the screen. |
| `morph?` | `boolean \| CarouselMorph` | Dissolve between slides with a warp instead of sliding them, for `full` and `story`. `true` is `melt`; see `CarouselMorph` for the others. Ignored by the morphing layouts, which have their own motion. Default `false`. |
| `morphStrength?` | `number` | How far the warp displaces at its peak, in px. Default `48`. |
| `class?` | `string` |  |
| `classes?` | `CarouselClasses` |  |

### ChartFrame

`import { ChartFrame } from 'omaris/chart'`

The box every chart draws into.

| Prop | Type | Notes |
| --- | --- | --- |
| `height` | `number \| string` |  |
| `label?` | `string` | Accessible description of what the chart shows. |
| `role?` | `'img' \| 'group'` | `'group'` — the default — for a plot with anything in it a person can reach: a legend that filters, a tooltip, the CSV button, the "Try again" of the error state. `'img'` for a plot that really is just a picture, which hides the SVG's innards from a screen reader — and which promises there is nothing inside to tab to, so it is wrong the moment there is. Default `'group'`. |
| `blank?` | `boolean` | True when there's nothing to draw. Default `false`. |
| `emptyText?` | `string` | Default `'No data'`. |
| `empty?` | `Snippet` |  |
| `error?` | `boolean \| string \| Error` | Something went wrong. Truthy replaces the plot with the error state; a string or an `Error` supplies the message. |
| `errorText?` | `string` | The message, when `error` is just `true`. Default `'Could not load this chart'`. |
| `errorState?` | `Snippet<[{ message: string }]>` | Replaces the whole error state. |
| `onRetry?` | `() => void` | Offers a "Try again" button in the error state. |
| `csv?` | `boolean \| string` | Offer `rows` as a CSV download. A string names the file. Default `false`. |
| `rows?` | `readonly T[]` | The rows the download writes. |
| `csvColumns?` | `(string \| CsvColumn<T>)[]` | Which fields the download writes, in order. Defaults to every field. |
| `class?` | `string` |  |
| `children?` | `Snippet` |  |

### Checkbox

`import { Checkbox } from 'omaris'`

MD3 checkbox.

#### Use it for

- Any number of items from a set: permissions, columns to show, rows to act
  on.
- A yes/no submitted with the form rather than applied at once: "Accept the
  terms", "Send me the digest". Bind `checked` and give it a `name`.
- The parent row over a set. `indeterminate` while some but not all children
  are checked. The parent computes it; it is not a third value.
- An option that needs explaining. `description` is the second line that
  says what the first commits you to.
- A run of rows ticked in one go. Dragging across a column of checkboxes
  paints them all to the state the first one was heading to, the way a
  phone's photo grid selects. It is on by default and needs no wiring.

#### Not for

- A setting that takes effect the moment it flips → [Switch](/docs/components/switch).
- Exactly one of several → [Radio](/docs/components/radio).
- A filter above a list that shows its result as you tick → filter
  [Chips](/docs/components/chip).
- A single boolean in a toolbar → a `toggle`
  [Icon Button](/docs/components/icon-button).
- More than about seven options → a searchable
  [Combobox](/docs/components/combobox).

#### Do

- Use `label` (or `children` for rich text) rather than a separate `<label>`.
  The text is wired to the input, so clicking it toggles the box.
- Keep `size="md"`, the 40dp target, anywhere a thumb will land. `sm` is for
  a dense table cell.
- Mark a required-but-empty box `invalid` and say why in text beside it. The
  red border is not an error message.
- Compute the parent's `indeterminate` from the children and let a click on
  the dash check everything.
- Keep a list of checkboxes in one container — a `ul`, a `form`, a `table` —
  so a paint stroke knows where it ends. Across containers you don't control,
  give every box in the run the same `paint="name"`.

#### Don't

- Phrase the label as a negative. "Don't email me" makes a tick mean no.
- Use a column of checkboxes as a settings list. That list is
  [Switch](/docs/components/switch) rows.
- Restyle the box through `classes` until the empty state has no border. An
  unchecked box must still be visible.
- Turn `paint` off because a row does something on change. If ticking a box
  fires a request, the fix is batching the result, not making people press
  twelve times.

#### Pairs with

- [Switch](/docs/components/switch), [Radio](/docs/components/radio),
  [Label](/docs/components/label), [Table](/docs/components/table),
  [List](/docs/components/list)

Parts (`classes`): `root` `control` `box` `fill` `input` `mark` `label` `description`

| Prop | Type | Notes |
| --- | --- | --- |
| `tone?` | `CheckboxTone` | One of `primary`, `secondary`, `tertiary`, `destructive`, `success`, `warning`, `info`. Default `'primary'`. |
| `size?` | `CheckboxSize` | One of `md`, `lg`. Default `'md'`. |
| `checked?` | `boolean` | Bindable. Default `false`. |
| `indeterminate?` | `boolean` | The dash state — some but not all children are checked. Default `false`. |
| `label?` | `string` | Text beside the box. |
| `description?` | `string` | Second line under the label. |
| `invalid?` | `boolean` | Inside a `Field`, defaults to the field's. |
| `haptics?` | `boolean` | A haptic tap when it's ticked or cleared. Follows the shared `haptics` store; `false` opts this checkbox out. Default `true`. |
| `sound?` | `boolean` | A sound cue when it's ticked. Follows the shared `sound` store; `false` opts this checkbox out. Default `true`. |
| `paint?` | `boolean \| string` | Drag across a run of checkboxes to set them all, the way a phone's photo grid selects. The box you press decides the direction — start on an empty one and the stroke ticks, start on a ticked one and it clears. On by default. Default `true`. |
| `class?` | `string` |  |
| `classes?` | `CheckboxClasses` | Per-part Tailwind overrides. `class` still covers the root. |
| `children?` | `Snippet` | Rich label, in place of `label`. |
| `ref?` | `HTMLInputElement \| null` | Default `null`. Bindable. |

### Chip

`import { Chip } from 'omaris'`

MD3 chip — assist, filter, input and suggestion, in one component.

#### Use it for

- A filter bar above a list or a [Table](/docs/components/table). `selectable`
  chips in a `ChipGroup` with `multiple`, and `overflow="scroll"` so it stays
  one line on a phone.
- Things the person entered, like tags, recipients or attached files. Input
  chips with `onremove` and a `removeLabel` ("Remove React").
- A contextual assist beside content: "Add to calendar", "Open in Maps". A
  plain chip with an icon in `start` and an `onclick` or `href`.
- Suggestions and quick replies under a composer. `variant="elevated"` when
  they float over content.
- A person. Put an [Avatar](/docs/components/avatar) in `start`.

#### Not for

- The primary or a secondary action of a screen → [Button](/docs/components/button).
  A chip is small, optional and about the content next to it.
- One choice from a fixed two to five →
  [Segmented Button](/docs/components/segmented-button). Chips are for sets
  that vary, wrap and can all be off.
- A read-only status nobody presses, like "Paid" or "Overdue" →
  [Badge](/docs/components/badge). A chip looks pressable.
- A boolean submitted with a form → [Checkbox](/docs/components/checkbox).
- One on/off → [Switch](/docs/components/switch).

#### Do

- Put chips that belong together in a `ChipGroup` with a `label`. It gives
  the set an accessible name.
- Pick `overflow` on purpose: `scroll` for a filter bar above a list, `wrap`
  inside a form.
- Keep the label to a couple of words. `label` truncates, and a chip that
  wraps is a button.
- Leave `check` on for filter chips. The tick tells a selected chip from a
  `tonal` one. Use `check={false}` only when the leading icon is the meaning,
  like a colour swatch.

#### Don't

- Use `variant="tonal"` for unselected filter chips. Selected and unselected
  then look the same.
- Let the × do anything but remove.
- Grow a chip with `size="lg"` to make it act as a button. If it needs to be
  big, it is a [Button](/docs/components/button).

#### Pairs with

- [Search Bar](/docs/components/search-bar),
  [Segmented Button](/docs/components/segmented-button),
  [Badge](/docs/components/badge), [Avatar](/docs/components/avatar),
  [Text Field](/docs/components/input)

Parts (`classes`): `root` `label` `check` `remove`

| Prop | Type | Notes |
| --- | --- | --- |
| `variant?` | `ChipVariant` | One of `outlined`, `tonal`, `elevated`. Default `'outlined'`. |
| `tone?` | `ChipTone` | One of `primary`, `secondary`, `tertiary`, `destructive`, `success`, `warning`, `info`. Default `'primary'`. |
| `size?` | `ChipSize` | One of `sm`, `md`, `lg`. Default `'md'`. |
| `shape?` | `ChipShape` | One of `round`, `square`. Default `'round'`. |
| `selectable?` | `boolean` | Turns the chip into a filter chip: clicking toggles `selected`. Default `false`. |
| `selected?` | `boolean` | Selected state of a filter chip. Bindable. Default `false`. |
| `check?` | `boolean` | Hide the leading tick on a selected filter chip. Default `true`. |
| `onremove?` | `() => void` | Adds the trailing ×. Called when it's pressed. |
| `removeLabel?` | `string` | Accessible name for the × — "Remove React". |
| `ripple?` | `boolean` | Default `true`. |
| `class?` | `string` |  |
| `classes?` | `ChipClasses` | Per-part Tailwind overrides. `class` still covers the root. |
| `start?` | `Snippet` | Leading icon or avatar. |
| `end?` | `Snippet` | Trailing icon, before the × if there is one. |
| `children?` | `Snippet` |  |
| `icon?` | `boolean` | Square, label-less button. Requires an `aria-label`. |
| `confetti?` | `boolean \| ConfettiOptions` | Confetti on press. `true` for the default burst, or any `ConfettiOptions` — `confetti={{ preset: 'fireworks' }}`. |
| `loading?` | `boolean` | Grows a spinner in at the start of the button and blocks interaction. The label stays put; only an `icon` button swaps its icon out. |
| `toggle?` | `boolean` | Turns the button into a two-state toggle driven by `pressed`. Ignored when `href` is set — a link has no pressed state. |
| `pressed?` | `boolean` | Selected state of a toggle button. Bindable. |

### ChipGroup

`import { ChipGroup } from 'omaris'`

A set of chips that belong together, with the accessible name that implies.

| Prop | Type | Notes |
| --- | --- | --- |
| `overflow?` | `'wrap' \| 'scroll'` | `wrap` lets the set flow onto more lines — the right choice in a form. `scroll` keeps it to one line that swipes sideways, which is what MD3 does for a filter bar above a list. Default `'wrap'`. |
| `label?` | `string` | Accessible name for the set. |
| `multiple?` | `boolean` | A set where chips are chosen, rather than one where they act. Default `false`. |
| `class?` | `string` |  |
| `children?` | `Snippet` |  |

### CircularProgress

`import { CircularProgress } from 'omaris'`

MD3 circular progress — the spinner, and the ring that counts up.

#### Use it for

- A process with a known length: an upload, an export, an import. `Progress`
  with `value` and `max`, the `stop` dot on, and a `label` like "Uploading
  photos".
- A wait of unknown length. `Progress` with no `value` along the top of a
  section that is refreshing, or `CircularProgress` with no `value` where
  only a small square is free.
- A ring that counts. `CircularProgress` with `value` and a percentage or an
  icon in `children`: storage used, step 3 of 6, a timer.
- `size="sm"` linear across the top of a [Card](/docs/components/card) or
  [Table](/docs/components/table) that is reloading in place.

#### Not for

- A page or list that has not loaded yet → [Skeleton](/docs/components/skeleton)
  in the shape of what is coming.
- The button just pressed → its own `loading` on
  [Button](/docs/components/button).
- Following a promise from an action → [Toast](/docs/components/toast) with
  `toast.promise`, which shows loading and the result in one card.
- A measurement against a scale, like CPU at 72% or a score →
  [Gauge](/docs/components/gauge). Progress means it will reach the end.
- A value the person drags → [Slider](/docs/components/slider).

#### Do

- Pass `label`: "Uploading", "Syncing". It is the accessible name, what a
  screen reader says instead of "progress bar".
- Prefer determinate. Give `value` as soon as you know the total; fall back
  to indeterminate only when you lose it.
- Run a linear bar the full width of what it belongs to: the card, the row,
  the top of the page. Never floating on its own.
- Keep `CircularProgress` at `xs` or `sm` beside text. `lg` and `xl` are for
  when the ring is the content.

#### Don't

- Show a spinner for a wait under about 300 ms. A flash of progress feels
  slower than nothing.
- Hide the bar the instant `value` hits 100. The indicator eases over 300 ms;
  let it arrive.
- Use `tone="destructive"` for "failed". Stop the bar and say so in an
  [Alert](/docs/components/alert).

#### Pairs with

- [Skeleton](/docs/components/skeleton), [Button](/docs/components/button),
  [Toast](/docs/components/toast), [Gauge](/docs/components/gauge),
  [Card](/docs/components/card)

Parts (`classes`): `root` `svg` `track` `indicator` `content`

| Prop | Type | Notes |
| --- | --- | --- |
| `value?` | `number` | 0…`max`. Leave undefined to spin. |
| `max?` | `number` | Default `100`. |
| `tone?` | `CircularProgressTone` | One of `primary`, `secondary`, `tertiary`, `destructive`, `success`, `warning`, `info`. Default `'primary'`. |
| `size?` | `CircularProgressSize` | One of `xs`, `sm`, `md`, `lg`, `xl`. Default `'md'`. |
| `thickness?` | `number` | Stroke width, as a fraction of the radius. Default `4`. |
| `track?` | `boolean` | Draw the unfilled remainder of the ring. Default `true`. |
| `label?` | `string` |  |
| `class?` | `string` |  |
| `classes?` | `CircularProgressClasses` | Per-part Tailwind overrides. `class` still covers the root. |
| `children?` | `Snippet` | Centered content — omit for a bare ring. |

### CodeBlock

`import { CodeBlock } from 'omaris'`

A code block: highlighted, copyable, and themed like everything else.

#### Use it for

- Read-only source: an install line, a config snippet, a response body, the
  "copy this" in a docs page. Highlighted with the theme's `--code-*` tokens,
  with `copy` on.
- A file worth pointing at. `title="button.svelte"`, `lineNumbers`,
  `highlight="2-4"`, and `focus` to dim the rest until the block is hovered.
- A short before and after. `diff` reads leading `+` and `-` as signs and
  tints the lines.
- Long output. `collapse={12}` shows the top and a control for the rest;
  `wrap` for a shell command that must not scroll sideways.

#### Not for

- Text someone edits → [Code Editor](/docs/components/code-editor).
- Two versions of a file → [Diff Viewer](/docs/components/diff-viewer). It
  diffs inside changed lines and collapses unchanged runs. `diff` here is for
  a hand-written five-line change.
- A payload someone explores → [JSON Viewer](/docs/components/json-viewer).
  `lang="json"` is right for a short, fixed example.
- A stream of lines that keeps arriving →
  [Log Viewer](/docs/components/log-viewer).
- One identifier in a sentence → [Text](/docs/components/text) `as="code"`.

#### Do

- Set `lang`: `ts`, `svelte`, `css`, `json`, `bash`, `python`, `sql`, `yaml`,
  `md`. Every token is a real element, so the code follows the theme.
- Use `variant="ghost"` inside a card or a sheet that already has a border,
  `filled` on a plain page section. The default `outlined` stands alone.
- Keep `lineNumbers` on when you `highlight`, and set `startLine` when the
  snippet is cut from a file, so the prose can say "line 14" and mean it.
- Let the block be as tall as its content. `collapse` is the height control,
  and it opens with the height animating.

#### Don't

- Paste minified or generated code and `collapse` it. That hides the length,
  not the noise.
- Leave `copy` on a fragment with `…` or placeholder values in it. People
  paste what the button gives them.
- Give it a `max-h-*` and let it scroll both ways. A block that scrolls
  inside a page that scrolls is a trap.

#### Pairs with

- [Code Editor](/docs/components/code-editor),
  [Diff Viewer](/docs/components/diff-viewer),
  [JSON Viewer](/docs/components/json-viewer), [Tabs](/docs/components/tabs),
  [Card](/docs/components/card)

Parts (`classes`): `root` `header` `title` `badge` `viewport` `code` `line` `gutter` `sign` `content` `float` `expand` `fade`

| Prop | Type | Notes |
| --- | --- | --- |
| `code` | `string` | The source. Leading and trailing blank lines are trimmed. |
| `lang?` | `string` | `ts`, `svelte`, `css`, `json`, `bash`, `python`, `sql`, `yaml`, `md`, … Default `'plain'`. |
| `title?` | `string` | Filename, shown in the header bar. |
| `variant?` | `CodeBlockVariant` | One of `outlined`, `filled`, `ghost`. Default `'outlined'`. |
| `size?` | `CodeBlockSize` | One of `sm`, `md`. Default `'md'`. |
| `badge?` | `boolean` | Show the language chip. Defaults to on whenever there's a header. |
| `lineNumbers?` | `boolean` | Default `false`. |
| `startLine?` | `number` | Number the first line is given. Default `1`. |
| `highlight?` | `string \| number[]` | Lines to call out — `[2, 5]` or `'2,5-8'`. |
| `focus?` | `boolean` | Dim every line that isn't called out until the block is hovered. Default `false`. |
| `diff?` | `boolean` | Read `+`/`-` prefixes as a diff and tint the lines. Default `false`. |
| `copy?` | `boolean` | Offer the copy button. Default `true`. |
| `wrap?` | `boolean` | Wrap long lines instead of scrolling sideways. Default `false`. |
| `collapse?` | `number` | Collapse to this many lines, with a control to open it up. |
| `actions?` | `Snippet` | Extra header controls, before the copy button. |
| `oncopy?` | `(code: string) => void` | Fires after the source lands on the clipboard. |
| `class?` | `string` |  |
| `classes?` | `CodeBlockClasses` | Per-part Tailwind overrides. `class` still covers the root. |

### CodeEditor

`import { CodeEditor } from 'omaris'`

A code editor with no editor in it.

#### Use it for

- Source someone edits inside an app: a webhook payload, a SQL query, a JSON
  config, a template. `lang` takes the same names as Code Block.
- An editor that ships small. It is a `<textarea>` with a highlighted copy
  behind it, so IME, autocorrect, undo and screen readers are the browser's.
- Feedback from your own validator. `markers` draw a rule under the span and
  put the message in the status bar; `completions` feed `⌃Space`.
- A tool for people who live in a terminal. `vim` is one prop.

#### Not for

- Code that is shown, not edited → [Code Block](/docs/components/code-block).
  `readOnly` here still costs a gutter and a textarea.
- Two versions of a file → [Diff Viewer](/docs/components/diff-viewer).
- Prose with bold and a list → [Rich Text Editor](/docs/components/rich-text-editor).
- A log that keeps growing → [Log Viewer](/docs/components/log-viewer). A
  JSON document to browse and fold → [JSON Viewer](/docs/components/json-viewer).
- A multi-file IDE with a language server → Monaco or CodeMirror.

#### Do

- Always set `lang`. `plain` has no colour, no bracket pairs and no comment
  token for `⌘/`.
- Size it with `height`, not a class. `height="auto"` plus a `min-h-*` on
  `classes.frame` for content-sized; a fixed number inside a dialog.
- Wire `onsave`. `⌘S` and vim's `:w` are caught either way and do nothing
  without it.
- Turn `copy` on for anything someone is more likely to take away than edit:
  a generated snippet, a payload, a token. It copies the selection or the
  whole file, keeps the caret, and sits in the header when there is one.
- Turn on `wrap` for markdown, SQL and anything prose-shaped. Leave it off
  for code, where a long line is a signal.

#### Don't

- Switch `vim` on by default in a form. It is a preference someone opts into;
  normal mode swallows the first keystrokes of anyone who did not.
- Hand it a file of tens of thousands of lines. The painted copy is the whole
  text; a log belongs in [Log Viewer](/docs/components/log-viewer).
- Use `readOnly` to display a short snippet → [Code Block](/docs/components/code-block).
- Leave `title` off when the person has more than one file open in their
  head. The header bar with a filename tells them which this is.
- Build your own copy button out of `actions`. `copy` already handles the
  selection, the flash and the insecure-origin fallback. `actions` is for the
  controls beside it: a language switch, a format button, a reset.

#### Pairs with

- [Code Block](/docs/components/code-block), [Diff Viewer](/docs/components/diff-viewer),
  [JSON Viewer](/docs/components/json-viewer), [Dialog](/docs/components/dialog),
  [Button](/docs/components/button)

Parts (`classes`): `root` `header` `title` `badge` `tools` `float` `frame` `gutter` `gutterInner` `gutterLine` `gutterMarked` `editor` `paint` `code` `line` `active` `overlay` `overlayInner` `match` `matchCurrent` `bracket` `caret` `marker` `guide` `input` `placeholder` `find` `findRow` `findField` `findButton` `findCount` `menu` `option` `optionActive` `status` `mode` `command` `pending`

| Prop | Type | Notes |
| --- | --- | --- |
| `value?` | `string` | The source. Bindable. Default `''`. |
| `lang?` | `string` | `ts`, `svelte`, `css`, `json`, `bash`, … — the names `CodeBlock` takes. Default `'plain'`. |
| `size?` | `CodeEditorSize` | One of `sm`, `md`. Default `'md'`. |
| `title?` | `string` | Filename, shown in the header bar. |
| `badge?` | `boolean` | Show the language chip. Defaults to on whenever there is a header. |
| `copy?` | `boolean` | Offer a copy button. It goes in the header when there is one, and floats over the top corner when there is not — where it fades in on hover, and stays put on a touch screen. Default `false`. |
| `actions?` | `Snippet` | Extra header controls, before the copy button. |
| `oncopy?` | `(text: string) => void` | Fires after the source lands on the clipboard, with what was copied. |
| `lineNumbers?` | `boolean` | Default `true`. |
| `relativeLineNumbers?` | `boolean` | Number every line by its distance from the caret, as `:set rnu` does. Default `false`. |
| `startLine?` | `number` | Number the first line is given. Default `1`. |
| `wrap?` | `boolean` | Wrap long lines instead of scrolling sideways. Default `false`. |
| `highlightActiveLine?` | `boolean` | Tint the line the caret is on. Default `true`. |
| `readOnly?` | `boolean` | Default `false`. |
| `tabSize?` | `number` | Indent width, in spaces. Default `2`. |
| `insertSpaces?` | `boolean` | Indent with spaces rather than a tab character. Default `true`. |
| `autoClose?` | `boolean` | Close brackets and quotes as you type, and wrap a selection in them. Default `true`. |
| `status?` | `boolean` | Line, column and character count along the bottom. On by default with `vim`. Default `false`. |
| `vim?` | `boolean` | Modal editing: normal, insert, visual and visual-line, operators and motions (`d2w`, `ci"`, `>ip`, `gUiw`), registers, marks, `/` search, `.`, `<C-a>`, and `:w :q :s/// :set`. `u` and `<C-r>` undo a whole command — `ciwfoo<Esc>` included — and still leave `⌘Z` working. Default `false`. |
| `vimMode?` | `VimMode` | The mode vim is in. Bindable, for a status bar of your own. Default `'normal'`. Bindable. |
| `find?` | `boolean` | `⌘F` / `⌘H`. Default `true`. |
| `bracketMatch?` | `boolean` | Ring the bracket under the caret and its partner. Default `true`. |
| `indentGuides?` | `boolean` | A rule down each level of indentation. Default `false`. |
| `markers?` | `CodeEditorMarker[]` | Errors and warnings to draw under the text. Default `[]`. |
| `completions?` | `string[] \| ((context: CodeEditorCompletionContext) => string[])` | What `⌃Space` offers. A list, or a function called with the word being typed. Given a list, the menu also opens as you type. Left out, `⌃Space` still completes from the words already in the document. |
| `comment?` | `string \| [string, string]` | What `⌘/` and vim's `gc` comment with. A line token like `'#'`, or an open/close pair. Defaults to the one `lang` uses. |
| `onsave?` | `(value: string) => void` | `⌘S`, and vim's `:w`. |
| `onquit?` | `() => void` | Vim's `:q`. Nothing happens without it. |
| `onchange?` | `(value: string) => void` |  |
| `height?` | `number \| string` | Height of the editing area. A number is px, a string any CSS length. It lives in a property rather than a class, so a height in `classes.frame` genuinely replaces it — `height="auto"` with a `min-h-*` class lets it grow with the content instead. Default `'18rem'`. |
| `class?` | `string` |  |
| `classes?` | `CodeEditorClasses` |  |
| `ref?` | `HTMLTextAreaElement \| null` | Default `null`. Bindable. |

### Collapsible

`import { Collapsible } from 'omaris'`

A single disclosure: a header you press and the block it shows or hides.

#### Use it for

- One block of detail behind a header — the delivery details on an order,
  the raw payload under a log line, the refund history on a receipt.
- "More options" under a form's required fields: the fields most people never
  touch, one press away. `trigger` takes your own `Button` for it.
- A filter panel that folds away on a phone, with a count in `end` that says
  how much is applied while it is closed.
- Open state that lives somewhere else: `open` is bindable, so it can come
  from the URL, from storage, or from a toggle elsewhere on the page.

#### Not for

- A set of sections read one after another → [Accordion](/docs/components/accordion),
  which keeps the headers in one list, moves between them with the arrows,
  and can close the others when one opens.
- Peers where exactly one is visible → [Tabs](/docs/components/tabs).
- Content that should float over the page instead of pushing it down →
  [Popover](/docs/components/popover), or [Sheet](/docs/components/sheet) on
  a phone.
- Sections of navigation → [Navigation Drawer](/docs/components/navigation-drawer).

#### Do

- Say what is inside in the header: "Delivery details", not "More". Use
  `supportingText` for the one fact worth reading without opening it.
- Pick the surface to match what is around it: `plain` inside a card,
  `outlined` among other blocks, `filled` when it is a thing of its own.
- Use `disabled` with the reason in `supportingText` rather than hiding a
  section that cannot open yet.
- Set `headingLevel` when the disclosure titles a section of the page, so it
  shows up in a screen reader's list of headings.

#### Don't

- Put a required field, or an error, in a closed body. A validation message
  nobody can see is a form nobody can submit.
- Stack three collapsibles in a column; that is an
  [Accordion](/docs/components/accordion).
- Put a button or a link in `title` or `end` — the header is already a button.
- Nest one inside another more than once. Two levels of folding is where
  people stop finding things.

#### Pairs with

- [Accordion](/docs/components/accordion), [Card](/docs/components/card),
  [Badge](/docs/components/badge), [Button](/docs/components/button),
  [Text](/docs/components/text)

Parts (`classes`): `root` `trigger` `icon` `headline` `title` `supporting` `chevron` `wrapper` `content` `inner`

| Prop | Type | Notes |
| --- | --- | --- |
| `open?` | `boolean` | Whether the body is showing. Bindable. Default `false`. |
| `onOpenChange?` | `(open: boolean) => void` | Called whenever it opens or closes from the trigger. |
| `title?` | `string` | Header text for the built-in trigger. |
| `supportingText?` | `string` | A second line under `title` — "3 filters applied". |
| `variant?` | `CollapsibleVariant` | `plain` flush on the page, `outlined` a hairline card, `filled` a tonal one. One of `plain`, `outlined`, `filled`. Default `'plain'`. |
| `disabled?` | `boolean` | The trigger does nothing and reads as unavailable. The body keeps its state. Default `false`. |
| `headingLevel?` | `2 \| 3 \| 4 \| 5 \| 6` | Wraps the built-in trigger in a heading of this level, for a disclosure that titles a section of the page. Leave unset for one that doesn't. |
| `class?` | `string` |  |
| `classes?` | `CollapsibleClasses` | Per-part Tailwind overrides. `class` still covers the root. |
| `icon?` | `Snippet` | Leading icon in the built-in trigger. |
| `end?` | `Snippet` | Trailing content before the chevron — a count, a badge. |
| `trigger?` | `Snippet<[CollapsibleTriggerProps]>` | Your own trigger in place of the built-in one. Spread the props onto a button — they carry `aria-expanded`, `aria-controls` and the toggle. |
| `children?` | `Snippet` | The body. |
| `id` | `string` |  |
| `aria-expanded` | `boolean` |  |
| `aria-controls` | `string` |  |
| `onclick` | `(event: MouseEvent) => void` |  |

### ColorPicker

`import { ColorPicker } from 'omaris'`

A colour picker that thinks in OKLCH, because this library does.

#### Use it for

- A colour that becomes a token: a brand accent, a project colour, a chart
  series. `format="oklch"` writes what `app.css` reads.
- A tint with opacity, like an overlay or a highlight. Pass `alpha`; the
  colour is drawn over a checkerboard.
- A picker inside a settings panel. `compact` keeps the plane, the sliders
  and the swatches and drops the text and number fields.
- A legacy field that needs `#rrggbb`. Use `format="hex"`. Parsing accepts
  hex, `rgb()`, `oklch()` and `oklab()` whatever the format.
- Matching a colour on screen but outside the app, like a logo or a
  screenshot. The eyedropper samples any pixel the browser can see;
  `sampleScreenColor()` puts that on a button of your own.

#### Not for

- A choice between a few named colours, like six tag colours → a row of
  [Chips](/docs/components/chip) or a [Radio](/docs/components/radio) group
  drawn as swatches. `swatches` here still opens the whole plane.
- Switching the app's palette, contrast and radius → [Theme Settings](/docs/components/theme-settings).
- An emoji or icon for a channel → [Emoji Picker](/docs/components/emoji-picker).
- A gradient or a palette of several stops. It picks one colour.

#### Do

- Leave `plane="relative"`. `absolute` draws the gamut's true shape, most of
  which cannot be picked. It is for teaching, not choosing.
- Pass `swatches` with the brand's colours, so the common pick is one tap.
- Let an out-of-gamut value stay as it is. A saved `oklch()` past sRGB shows
  a hint and pins the puck to the edge instead of clipping silently.
- Set `channels={false}` where the text field is enough. The L / C / H boxes
  are for someone typing a colour.
- Use `size="md"` or larger where a finger does the picking. Everything grows
  on a coarse pointer; `size="sm"` is a mouse size.

#### Don't

- Store `hex` when the source of truth is an `oklch` token. The round trip
  to sRGB lowers chroma.
- Put it in a popover with no width. The plane takes the container's width.
- Hide `eyedropper` because some browsers lack it. It hides itself where
  there is nothing to sample with.
- Call `sampleScreenColor()` from anything but a click. Browsers only open
  the sampler inside a user gesture; a call from an effect resolves `null`.

#### Pairs with

- [Theme Settings](/docs/components/theme-settings), [Text Field](/docs/components/input),
  [Sheet](/docs/components/sheet), [Chip](/docs/components/chip),
  [Tooltip](/docs/components/tooltip)

Parts (`classes`): `root` `area` `canvas` `areaThumb` `controls` `preview` `previewFill` `sliders` `slider` `alphaTrack` `track` `thumb` `fields` `field` `label` `input` `eyedropper` `swatches` `swatch` `hint`

| Prop | Type | Notes |
| --- | --- | --- |
| `value?` | `string` | The colour, as CSS text in `format`. Bindable. Default `'oklch(0.6 0.18 260)'`. |
| `format?` | `ColorFormat` | How `value` is written. Parsing accepts hex, `rgb()`, `oklch()` and `oklab()` whatever this says. Default `'oklch'`. |
| `size?` | `ColorPickerSize` | One of `sm`, `md`, `lg`. Default `'md'`. |
| `alpha?` | `boolean` | Show the alpha slider and carry alpha in `value`. Default `false`. |
| `swatches?` | `string[]` | Preset colours under the picker. Any CSS colour string. |
| `plane?` | `PlaneScale` | How the plane's x-axis is scaled — `relative` fills it with the colour this lightness can hold, `absolute` draws the gamut's own silhouette against transparency. Default `'relative'`. |
| `channels?` | `boolean` | Show the L / C / H number boxes beside the text field. Default `true`. |
| `eyedropper?` | `boolean` | Offer the browser's screen sampler, where there is one. Default `true`. |
| `compact?` | `boolean` | Default `false`. |
| `disabled?` | `boolean` | Default `false`. |
| `label?` | `string` | Accessible name for the plane. Default `'Colour'`. |
| `onchange?` | `(value: string, color: Oklch) => void` |  |
| `class?` | `string` |  |
| `classes?` | `ColorPickerClasses` |  |

### Combobox

`import { Combobox } from 'omaris'`

Combobox — type to search, arrow to the one you want, Enter to take it.

#### Use it for

- One value from a list too long to scroll: a country, a person, a product,
  a city. A few typed letters cut the list to three rows.
- Search against a server. Pass `load`; it is debounced and gets an
  `AbortSignal`, so a slow reply for "ir" never lands over "iraq".
- Free text with suggestions, like tags or labels. Set `allowCustom`.
- Matching on text that is not in the label. `keywords` lets "uae" find the
  Emirates and an ISO code find its country.

#### Not for

- A short, fixed list nobody would search → [Select](/docs/components/select).
- Finding a page, an order or a record anywhere in the app → [Search Bar](/docs/components/search-bar).
  It opens a results view instead of filling a field.
- Several values at once. Pick them one at a time and show each as an input
  [Chip](/docs/components/chip) with `onremove`. The box holds one value.
- Actions matched by name → [Menu](/docs/components/menu). Typing a letter
  already jumps to the row there.

#### Do

- Use `bind:selected` when you render more than the value next: the label,
  the description, the avatar.
- Set `minChars={2}` with `load` against a large index, and
  `openOnFocus={false}` so an empty query does not open an empty list.
- Write an `emptyText` that says what to do next: "No one by that name —
  invite them", not "No results".
- Leave `highlight` on. The bold run shows why a row matched.

#### Don't

- Set `allowCustom` where the value must exist, like an assignee or a
  customer id. A typo becomes a record.
- Filter thousands of `options` locally. `maxResults` caps what is drawn,
  not what is matched. Past a few hundred rows use `load`.
- Turn off `clearable` on an optional field. The × is how the person says
  "none" without emptying the text by hand.

#### Pairs with

- [Select](/docs/components/select), [Text Field](/docs/components/input),
  [Chip](/docs/components/chip), [Search Bar](/docs/components/search-bar),
  [Avatar](/docs/components/avatar)

Parts (`classes`): `root` `field` `control` `label` `adornment` `affix` `action` `support` `counter` `surface` `option` `group` `body` `description` `check` `empty` `highlight`

| Prop | Type | Notes |
| --- | --- | --- |
| `variant?` | `InputVariant` | Default `'outline'`. |
| `size?` | `InputSize` | Default `'default'`. |
| `value?` | `string` | The chosen option's value. Bindable. Default `''`. |
| `selected?` | `ComboboxOption \| null` | The chosen option itself. Bindable, for when `value` alone isn't enough. Default `null`. Bindable. |
| `query?` | `string` | What's in the box. Bindable. Default `''`. |
| `options?` | `ComboboxOption[]` | A fixed list, filtered locally. |
| `load?` | `ComboboxLoad` | Fetch results for a query instead. |
| `debounce?` | `number` | ms to wait after the last keystroke before calling `load`. Default `200`. |
| `minChars?` | `number` | Don't call `load` until this many characters are typed. Default `0`. |
| `maxResults?` | `number` | Cap on rows shown from a local filter. Default `50`. |
| `filter?` | `(option: ComboboxOption, query: string) => boolean` | Your own local matcher. |
| `allowCustom?` | `boolean` | Take whatever's typed as the value when nothing matches. Default `false`. |
| `openOnFocus?` | `boolean` | Open the list as soon as the field is focused. Default `true`. |
| `clearable?` | `boolean` | Show an × that empties the field. Default `true`. |
| `highlight?` | `boolean` | Bolden the matched part of each label. Default `true`. |
| `emptyText?` | `string` | Default `'No results'`. |
| `loadingText?` | `string` | Default `'Searching…'`. |
| `label?` | `string` |  |
| `supportingText?` | `string` |  |
| `invalid?` | `boolean` | Inside a `Field`, defaults to the field's. |
| `required?` | `boolean` | Inside a `Field`, defaults to the field's. |
| `start?` | `Snippet` | Leading icon inside the frame. |
| `option?` | `Snippet<[ComboboxOption, { selected: boolean; active: boolean; query: string }]>` | Custom row rendering. |
| `onchange?` | `(value: string, option: ComboboxOption \| null) => void` |  |
| `class?` | `string` |  |
| `classes?` | `ComboboxClasses` | Per-part Tailwind overrides. `class` still covers the root. |
| `ref?` | `HTMLInputElement \| null` | Default `null`. Bindable. |

### ComboChart

`import { ComboChart } from 'omaris/chart'`

Combo chart — bars and lines on one plot.

| Prop | Type | Notes |
| --- | --- | --- |
| `data` | `T[]` |  |
| `x?` | `Field<T>` | The category or time field. |
| `series?` | `ComboSeries<T>[]` | What to draw, in the order it draws. Default `[]`. |
| `height?` | `number \| string` | Plot height. A number is px; a string is any CSS length. Default `280`. |
| `axis?` | `boolean \| 'x' \| 'y'` | `true` for both, or just the one you want. Default `true`. |
| `grid?` | `boolean` | Default `true`. |
| `legend?` | `ChartLegend` | `true` toggles a series off on click; `'isolate'` shows it alone. Default `false`. |
| `tooltip?` | `boolean` | Default `true`. |
| `stacked?` | `boolean` | Pile the bar series rather than overlapping them. Default `true`. |
| `radius?` | `number` | Corner radius on the bars, in px. Default `4`. |
| `formatX?` | `(value: never) => string` | Tick labels along the x axis. |
| `formatY?` | `(value: never) => string` | Tick labels down the left axis. |
| `formatY2?` | `(value: never) => string` | Tick labels down the right axis. |
| `colors?` | `readonly string[]` | Palette override, cycled across the series. Default `CHART_COLORS`. |
| `padding?` | `number \| { top?: number; right?: number; bottom?: number; left?: number }` | Space around the plot, in px. |
| `label?` | `string` | Accessible description of what the chart shows. |
| `class?` | `string` |  |
| `empty?` | `Snippet` |  |
| `emptyText?` | `string` |  |
| `error?` | `boolean \| string \| Error` | Something went wrong. Truthy puts the chart into its error state; a string or an `Error` supplies the message. |
| `errorText?` | `string` | The message, when `error` is just `true`. |
| `errorState?` | `Snippet<[{ message: string }]>` | Replaces the whole error state. |
| `onRetry?` | `() => void` | Offers a "Try again" button in the error state. |
| `csv?` | `boolean \| string` | Offer the plotted rows as a CSV download, from a button in the corner. A string names the file. Default `false`. |
| `csvColumns?` | `(string \| { key: string; label?: string; value?: (row: T) => unknown })[]` | Which fields the download writes, in order. Defaults to every field. |
| `references?` | `ChartReference[]` | Lines and bands at fixed values — targets, thresholds, windows. |
| `annotations?` | `ChartAnnotation[]` | Notes pinned to a point. |
| `brush?` | `ChartBrush` | Drag across the plot to select a range, and zoom the chart to it. |
| `zoom?` | `ChartZoom` | Wheel or pinch to zoom, drag to pan. |

### CommandPalette

`import { CommandPalette } from 'omaris'`

⌘K — a search field over every action in the app, opened from anywhere.

#### Use it for

- One place to reach everything in an app from the keyboard — pages, actions,
  records — opened with ⌘K (`hotkey`, `mod+k` by default) from anywhere.
- Actions that take a second choice: "Assign to…", "Move to…", "Theme…" as a
  row with `children`, which opens as its own page.
- Searching records on a server: `bind:query` to send what is typed,
  `filter={false}` to show the answer as it came back, `loading` meanwhile.
- The rows people use most, first: `recentKey` remembers the last `recent`
  choices across visits.

#### Not for

- Filtering a list that is already on the screen →
  [Search Bar](/docs/components/search-bar). The palette covers the page; a
  filter should leave the results in view.
- Picking a value for a form field → [Combobox](/docs/components/combobox).
- The actions of one row or one button → [Menu](/docs/components/menu).
- The app's primary navigation → [Navigation Drawer](/docs/components/navigation-drawer)
  or [Navigation Bar](/docs/components/navigation-bar). A palette is a
  shortcut to places, not the only way there — nothing on a phone has ⌘K.

#### Do

- Give every row a stable, unique `id`; it keys the list and it is what
  `recent` stores.
- Add `keywords` for the words people will actually type — "preferences" and
  "account" for Settings.
- Start a label with the verb or the place: "New issue", "Go to billing".
  The first letters rank highest.
- Keep a visible way to open it — a button with a `Kbd` in it, or a search
  field in the top bar — for touch screens and for people who do not know
  the shortcut.
- Put the `shortcut` on a row only when that shortcut really works outside
  the palette; the cap is a promise.

#### Don't

- Register ⌘K twice. If the app already binds it (a docs search, a browser
  extension you ship), pass another `hotkey` or `false`.
- Put a form in a page. A page is a list to choose from; a form belongs in a
  [Dialog](/docs/components/dialog) the chosen row opens.
- Announce what a row did with a toast when its result is on screen — the
  page navigated, the theme changed.
- Nest pages more than two deep. Past that, people lose the thread even with
  the chips.

#### Pairs with

- [Kbd](/docs/components/kbd), [Dialog](/docs/components/dialog),
  [Top App Bar](/docs/components/top-app-bar), [Search Bar](/docs/components/search-bar),
  [Button](/docs/components/button)

Parts (`classes`): `root` `body` `header` `searchIcon` `back` `crumbs` `crumb` `input` `clear` `progress` `list` `page` `group` `heading` `option` `icon` `text` `label` `path` `description` `highlight` `shortcut` `chevron` `empty` `footer` `hint`

| Prop | Type | Notes |
| --- | --- | --- |
| `open?` | `boolean` | Bindable. Default `false`. |
| `items` | `CommandGroup[]` | The rows, in groups. |
| `query?` | `string` | What is typed in the field. Bindable, for searching a server as it changes. Default `''`. Bindable. |
| `placeholder?` | `string` | Default `'Type a command or search…'`. |
| `hotkey?` | `string \| string[] \| false` | The shortcut that toggles it from anywhere on the page — `'mod+k'` is ⌘K on a Mac and Ctrl+K elsewhere. `false` for none. Listened for only while the palette is mounted. Default `'mod+k'`. |
| `recent?` | `number` | How many recently chosen rows to remember and show first. Needs `recentKey`. Default `5`. |
| `recentKey?` | `string` | localStorage key the recent rows are kept under. Without one, nothing is remembered. |
| `recentHeading?` | `string` | Heading over the recent rows. Default `'Recent'`. |
| `loading?` | `boolean` | Draw a progress line under the field — for results that are on their way. Default `false`. |
| `empty?` | `Snippet<[string]>` | Drawn when nothing matches. Handed the query. |
| `filter?` | `CommandFilter \| false` | Replace the fuzzy ranking. `false` shows `items` exactly as given, for a list a server has already filtered. |
| `limit?` | `number` | Most results shown for a query. The best ones, by score. Default `100`. |
| `onselect?` | `(item: CommandItem) => void` | Called with every row chosen, after the row's own `onselect`. |
| `closeOnSelect?` | `boolean` | Close once a row has been chosen. On by default. Default `true`. |
| `label?` | `string` | Accessible name of the dialog. Default `'Command palette'`. |
| `backLabel?` | `string` | Accessible name of the back button on a nested page. Default `'Back'`. |
| `clearLabel?` | `string` | Accessible name of the button that empties the field. Default `'Clear'`. |
| `hints?` | `boolean` | The key hints along the bottom. Hidden on touch either way. Default `true`. |
| `footer?` | `Snippet` | Replaces the key hints — in another language, say. Hidden on touch too. |
| `mobileQuery?` | `string` | What counts as a phone — below it the palette is a full-height sheet. Default `'(max-width: 639px)'`. |
| `onclose?` | `() => void` | Called after it has finished closing. |
| `class?` | `string` |  |
| `classes?` | `CommandPaletteClasses` | Per-part Tailwind overrides. `class` still covers the dialog. |

### ContextMenu

`import { ContextMenu } from 'omaris'`

The right-click menu.

#### Use it for

- The actions that belong to one thing: a file, a row, a card, a node in a
  [Tree View](/docs/components/tree-view). A visible button per row would
  clutter the list.
- A long list of actions people run quickly: open, rename, duplicate, share,
  delete.
- A power-user path in a dense surface like a board, a canvas or a table,
  next to the ordinary buttons, not instead of them.

#### Not for

- The only way to reach an action. A context menu is invisible until guessed
  at, so every row must also be reachable somewhere obvious: a
  [Menu](/docs/components/menu) off a ⋯ button, a toolbar, a shortcut.
- A menu opened by a button → [Menu](/docs/components/menu).
- Choosing a value → [Select](/docs/components/select) or
  [Combobox](/docs/components/combobox). This menu is for actions.
- The whole page. A menu on `<body>` replaces the browser's own, which people
  use to open a link in a new tab.

#### Do

- Repeat the important rows somewhere visible. If the only way to delete is
  a right-click, the feature does not exist on a phone.
- Keep it to about seven rows, grouped with `Divider` and named with
  `MenuLabel` when the target is not obvious. Put the destructive row last,
  with `tone="destructive"`, behind a divider.
- Wrap the smallest region that owns the actions: one row, not the list.
- Leave `longPress` on. It is the same gesture on a touch screen; off makes
  the menu desktop-only.
- Set `closeOnSelect={false}` when the rows are toggles.

#### Don't

- Nest submenus. A shortcut with a second level is not a shortcut.
- Use it on a link or a text selection. People want the browser's own menu
  there.
- Open it on left click. That is a [Menu](/docs/components/menu).
- Add a row that needs a second click somewhere else to make sense.

#### Pairs with

- [Menu](/docs/components/menu), [Tree View](/docs/components/tree-view),
  [List](/docs/components/list), [Table](/docs/components/table),
  [Kanban](/docs/components/kanban)

Parts (`classes`): `surface` `trigger`

| Prop | Type | Notes |
| --- | --- | --- |
| `open?` | `boolean` | Bindable. Default `false`. |
| `size?` | `MenuSize` | Default `'md'`. |
| `disabled?` | `boolean` | Never opens, and the browser's own menu comes back. Default `false`. |
| `longPress?` | `number` | How long a touch has to be held before the menu opens, in ms. `0` turns the gesture off and leaves right-click as the only way in. Default `500`. |
| `closeOnSelect?` | `boolean` | Leave the menu open after a row is chosen — for a set of toggles. Default `true`. |
| `label?` | `string` | Accessible name for the menu. |
| `mobileSheet?` | `boolean` | On a phone, rise from the bottom edge as a sheet — dragged down to dismiss, rows a thumb can hit — rather than opening under a finger that is covering it. `false` keeps it at the press point. Default `true`. |
| `trigger?` | `Snippet` | The region that answers the right-click. |
| `children?` | `Snippet` | The rows — `MenuItem`, `MenuLabel`, `Divider`. |
| `onopen?` | `(position: { x: number; y: number }) => void` | Fires with the coordinates the menu opened at. |
| `class?` | `string` |  |
| `classes?` | `MenuClasses` | Per-part Tailwind overrides. `class` covers the wrapper. |

### ContributionGraph

`import { ContributionGraph } from 'omaris'`

The activity calendar: one square per day, a year across.

#### Use it for

- Something that happens some days and not others, over months: commits,
  workouts, shifts, orders shipped, doses taken. It answers "how consistent
  has this been" faster than a line chart.
- The header of a profile, a project page or a habit tracker, where a year
  has to fit above the fold.
- Spotting gaps. Two empty weeks are visible at a glance and invisible in a
  table.
- A quarter or a month, with `weeks={13}`. Same picture, shorter range,
  easier to read on a phone.

#### Not for

- A value you need to read rather than compare, like revenue or temperature
  → a [Chart](/docs/components/chart). This has five levels.
- Fewer than about eight weeks. A handful of squares is a table.
- Picking a date → [Picker](/docs/components/picker) or a calendar. The
  squares are a report, even when `onselect` makes them clickable.
- Comparing two series. One graph shows one thing.

#### Do

- Set `unit` to the thing counted: "commit", "workout", "shift". It appears
  in the title and every tooltip.
- Choose `fit` for the space: `trim` for a narrow card that should show
  fewer weeks, `scroll` when the whole year matters.
- Leave `thresholds` alone unless the scale is known and fixed. The defaults
  are the data's own quartiles, so a quiet year reads as well as a busy one.
- Use `tone` to match what it tracks: `success` for a habit, `info` for
  deliveries, `destructive` for incidents.
- Turn `stats` on only where streaks are the point; a streak counter changes
  how people feel about a gap. Keep the `legend` on the first graph on a
  page and drop it on repeats.

#### Don't

- Show more than about 53 weeks. Past a year the squares stop being
  countable.
- Put a year of `size="lg"` squares in a phone-width card and let it scroll
  sideways. Trim it instead.
- Use it for something that happens every day. A graph with no empty squares
  says nothing.
- Rely on colour alone. Every square carries its date and count as its
  accessible name and tooltip; leave those in place.

#### Pairs with

- [Card](/docs/components/card), [Chart](/docs/components/chart),
  [Gauge](/docs/components/gauge), [Tooltip](/docs/components/tooltip),
  [Empty](/docs/components/empty)

Parts (`classes`): `root` `header` `title` `stats` `board` `scroller` `frame` `weekdays` `months` `grid` `cell` `legend` `tooltip`

| Prop | Type | Notes |
| --- | --- | --- |
| `data?` | `ActivityDay[]` | One entry per day that has anything. Missing days are empty ones. Default `[]`. |
| `to?` | `Date` | Last day on the grid. Defaults to today. |
| `from?` | `Date` | First day. Defaults to `weeks` back from `to`. |
| `weeks?` | `number` | How far back to go when there is no `from`. Default `53`. |
| `fit?` | `ContributionFit` | What happens when the grid is wider than its container. Default `'scroll'`. |
| `size?` | `ContributionGraphSize` | One of `sm`, `md`, `lg`. Default `'md'`. |
| `tone?` | `Tone` | The colour the levels are mixed from. Default `'primary'`. |
| `weekStart?` | `0 \| 1 \| 2 \| 3 \| 4 \| 5 \| 6` | Day the week starts on — 0 Sunday, 1 Monday. Default `0`. |
| `thresholds?` | `[number, number, number, number]` | Counts at which each level starts, ascending, four of them. Left out, they are the quartiles of the data — so a graph of a busy year and one of a quiet year are both readable. |
| `months?` | `boolean` | Draw the month names above the grid. Default `true`. |
| `weekdays?` | `boolean` | Draw the weekday names beside it. Default `true`. |
| `legend?` | `boolean` | Draw the Less–More key under it. Default `true`. |
| `stats?` | `boolean` | Show the total, the longest run and the current one. Default `false`. |
| `title?` | `string` | Replaces the built-in "N contributions in …" title. |
| `unit?` | `string` | The noun in the title and every tooltip — "commit", "workout". Default `'contribution'`. |
| `locale?` | `string` | BCP-47 tag for the month, weekday and date names. |
| `onselect?` | `(day: ActivityCell) => void` | Fires when a day is clicked or activated from the keyboard. |
| `day?` | `Snippet<[ActivityCell]>` | Replaces a square. Gets the day and its level. |
| `header?` | `Snippet<[{ total: number; days: number }]>` | Replaces the header row. |
| `class?` | `string` |  |
| `classes?` | `ContributionGraphClasses` | Per-part Tailwind overrides. `class` still covers the root. |

### DataList

`import { DataList } from 'omaris'`

Key/value details — an order's number, status and total; a profile's email, role and join date — as a real `<dl>`, so a screen reader reads each label with its value rather than as two unrelated runs of text.

#### Use it for

- The details of one thing — an order's number, status, customer and date; a
  user's email, role and join date — as label/value pairs in a real `<dl>`.
- A detail panel that has to read right in a wide page, a side sheet and a
  phone: `horizontal` puts labels beside values and stacks them on its own
  once the list is narrower than 24rem.
- A profile or settings summary with each label over its value:
  `orientation="vertical"`.
- Values people paste elsewhere — an order number, an API key, an IBAN —
  with `copyable`, whose own tick is the confirmation.
- A receipt's totals, lined up at the far edge: `align="end"`.

#### Not for

- Many records of the same shape, compared or sorted →
  [Table](/docs/components/table).
- Rows you press to open something → [List](/docs/components/list).
- Values the person edits in place → [Input](/docs/components/input) in a form,
  or [Inline Edit](/docs/components/inline-edit) for one field at a time.
- One headline figure and its trend → [Stat Card](/docs/components/stat-card).
- Nested or arbitrary data — an API response →
  [JSON Viewer](/docs/components/json-viewer).

#### Do

- Keep labels short and the same kind of word — nouns, "Email", "Role" — so
  the column scans.
- Put rich values in the children — a [Badge](/docs/components/badge) for a
  status, an [Avatar](/docs/components/avatar) and a name, a link.
- Leave an unknown value empty rather than writing "N/A"; the row shows a dash
  and tells a screen reader the value is not set.
- Set `labelWidth` when labels are long, so the value column does not start
  halfway across a narrow panel.

#### Don't

- Wrap it in a `Card` per row; one `dividers` list is one object.
- Use `copyable` on values nobody pastes — a status, a date.
- Fire a toast from a copy; the button already turned into a tick.
- Put a paragraph in a value. A long note belongs under the list as body text.

#### Pairs with

- [Card](/docs/components/card), [Sheet](/docs/components/sheet),
  [Badge](/docs/components/badge), [Avatar](/docs/components/avatar),
  [Divider](/docs/components/divider), [Timeline](/docs/components/timeline)
  for the order's history under its details

| Prop | Type | Notes |
| --- | --- | --- |
| `orientation?` | `DataListOrientation` | `horizontal` puts each label in a column beside its value, and stacks them once the list is narrower than 24rem. `vertical` always stacks. Default `'horizontal'`. |
| `size?` | `DataListSize` | Text size and row padding together. Default `'md'`. |
| `dividers?` | `boolean` | A hairline between rows. Default `false`. |
| `align?` | `DataListAlign` | Where values sit in a horizontal list. `end` is the receipt layout — a total at the far edge, lined up with the numbers above it. Default `'start'`. |
| `labelWidth?` | `number \| string` | Width of the label column in a horizontal list: pixels, or any CSS length. Defaults to 40% of the list, up to 12rem. |
| `class?` | `string` |  |
| `children?` | `Snippet` |  |

### DataListItem

`import { DataListItem } from 'omaris'`

One row of a `DataList`: a `<dt>` and its `<dd>`, grouped in a `<div>` the way the HTML spec allows, so each row can be styled as one.

Parts (`classes`): `root` `label` `value` `content` `copy`

| Prop | Type | Notes |
| --- | --- | --- |
| `label` | `string` | The term — "Order", "Email", "Joined". |
| `value?` | `string \| number \| null` | The value, as text. Use children for anything richer — a badge, a link, an avatar. With neither, the row shows a dash and tells a screen reader the value is not set. |
| `copyable?` | `boolean \| string` | Add a copy button after the value. `true` copies what is shown — the `value`, or the text of the children; a string copies that instead, for a value displayed differently from how it is pasted (a masked key, a formatted IBAN). Default `false`. |
| `copyLabel?` | `string` | Accessible name of the copy button. Defaults to "Copy {label}". |
| `class?` | `string` |  |
| `classes?` | `DataListItemClasses` | Per-part Tailwind overrides. `class` still covers the root. |
| `icon?` | `Snippet` | An icon before the label. |
| `children?` | `Snippet` | Rich value, in place of `value`. |

### DateField

`import { DateField } from 'omaris'`

A date input: a field that shows the date in the page's language and opens a `Calendar` to change it — anchored under the field on a desktop, in a bottom sheet on a phone, where a popover would be a thumb's width from the edge.

#### Use it for

- A date in a form: a due date, a start date, a delivery day. It reads as
  text until pressed, then opens a calendar under the field — or, on a
  phone, in a bottom sheet where a thumb can reach it.
- A date that should read in the page's language, with Western digits,
  without anyone writing a formatter: `format` takes `Intl` options.
- A form posted the plain way: with `name`, the date goes as `YYYY-MM-DD`.

#### Not for

- A span of dates → [Date Range Field](/docs/components/date-range-field).
- A calendar that stays open on the page → [Calendar](/docs/components/calendar).
- A birthday or any date years away → `DatePicker` in
  [Picker](/docs/components/picker); three wheels beat forty pages of months.
- A time, or a date with a time → `TimePicker` or `DateTimePicker` in
  [Picker](/docs/components/picker).
- A date people know by heart and type faster than they pick — an ID's
  expiry on a data-entry screen → an [Input](/docs/components/input) with
  `type="date"`.

#### Do

- Give it a `label`, and a `placeholder` that says what is missing when it
  is empty — "Pick a delivery day" rather than a format mask.
- Put the valid window in `min`, `max` and `isDateDisabled`, so the calendar
  greys out what cannot be picked instead of the form rejecting it.
- Use the same `variant` and `size` as the text fields around it; they are
  the same frame.
- Turn `clearable` off when the date is required — an × that empties a field
  that cannot be empty is a trap.

#### Don't

- Pass it a string. The value is a `Date` at local midnight, or `null`.
- Use it as a filter chip in a toolbar. A range filter is
  [Date Range Field](/docs/components/date-range-field); a single-day filter
  still wants a label someone can read.
- Set `mobileQuery` wider than a phone. The sheet is for a thumb; a tablet
  is better served by the popover.

#### Pairs with

- [Input](/docs/components/input), [Select](/docs/components/select),
  [Date Range Field](/docs/components/date-range-field),
  [Calendar](/docs/components/calendar), [Picker](/docs/components/picker)

Parts (`classes`): `root` `field` `control` `value` `placeholder` `icon` `action` `label` `support` `panel` `sheet`

| Prop | Type | Notes |
| --- | --- | --- |
| `value?` | `Date \| null` | The date, at local midnight, or `null`. Bindable. Default `null`. |
| `variant?` | `DateFieldVariant` | `outline`, `filled` or `ghost` — the same frames as `Input`. One of `outline`, `filled`, `ghost`. Default `'outline'`. |
| `size?` | `DateFieldSize` | `sm`, `default` or `lg` — the same heights as `Input`. One of `sm`, `default`, `lg`. Default `'default'`. |
| `label?` | `string` | Label above the field. |
| `required?` | `boolean` | Marks the label required. Default `false`. |
| `supportingText?` | `string` | Helper line under the field. Turns into the error text when invalid. |
| `invalid?` | `boolean` | Marks the field invalid and wires up aria-invalid. Default `false`. |
| `placeholder?` | `string` | Shown, greyed, while there is no date. Default `'Select a date'`. |
| `format?` | `Intl.DateTimeFormatOptions` | How the date reads in the field. `Intl.DateTimeFormat` options, with Western digits added — `{ dateStyle: 'long' }`, or `{ weekday: 'short', day: 'numeric', month: 'short' }`. Default `{ dateStyle: 'medium' }`. |
| `min?` | `Date` | Earliest selectable day. |
| `max?` | `Date` | Latest selectable day. |
| `isDateDisabled?` | `(date: Date) => boolean` | Days that cannot be picked. |
| `locale?` | `string` | BCP-47 tag for the field and the calendar. Defaults to `<html lang>`. |
| `weekStartsOn?` | `Weekday` | 0 is Sunday. Defaults to the locale's first day. |
| `clearable?` | `boolean` | Show an × that empties the field once it has a date. Default `true`. |
| `open?` | `boolean` | Whether the calendar is open. Bindable. Default `false`. |
| `mobileQuery?` | `string` | What counts as a phone, where the calendar opens in a bottom sheet. Default `'(max-width: 639px)'`. |
| `onchange?` | `(value: Date \| null) => void` | Fires after a pick or a clear. |
| `class?` | `string` | Merged onto the root wrapper. |
| `classes?` | `DateFieldClasses` | Per-part Tailwind overrides. `class` still covers the root. |
| `calendarClasses?` | `CalendarClasses` | Per-part overrides for the calendar inside the popup. |
| `ref?` | `HTMLButtonElement \| null` | The trigger button. Default `null`. Bindable. |

### DatePicker

`import { DatePicker } from 'omaris'`

Three wheels — day, month, year — in the order this locale writes them.

#### Use it for

- Touch first. A wheel covers a hundred values in one flick. Use it on a
  phone, a tablet or a kiosk; on a desktop a typed field or a
  [Select](/docs/components/select) is faster.
- A date far from today, like a birthday or an expiry, with `DatePicker`.
  Three wheels beat thirteen taps through a calendar.
- A time, with `TimePicker`. The wheels are always 1–12 and AM/PM — omaris
  never shows a 24-hour clock, and there is no prop to make it. The value
  stays `"14:30"` underneath, so it sorts and stores as is.
- A moment, with `DateTimePicker`: one wheel of whole days ("Today",
  "Wed 17 Sep") beside the hour and minute.
- A number out of a long run, like a weight or an age, with `NumberPicker`.
  Anything else with your own wheels: `Picker` is the frame (band, fade,
  confirm row) and `PickerColumn` is one wheel in it.

#### Not for

- A date near today, or one picked by looking at the week → a
  [Date Field](/docs/components/date-field) or
  [Calendar](/docs/components/calendar). A wheel hides the shape of the month.
- A number typed more often than spun, like a quantity or a price →
  [Number Input](/docs/components/number-input) or
  [Price Input](/docs/components/price-input).
- Fewer than about eight choices → [Select](/docs/components/select),
  [Radio](/docs/components/radio) or
  [Segmented Button](/docs/components/segmented-button).
- A value that needs searching → [Combobox](/docs/components/combobox).
- A desktop-only form where every field is typed. One wheel in a column of
  text fields costs more than it saves.

#### Do

- Put it in a [Sheet](/docs/components/sheet) on a phone and a
  [Dialog](/docs/components/dialog) on a desktop. Pass `onconfirm` and
  `oncancel` so the picker draws its own confirm row.
- Edit a copy of the value and commit it on confirm, so Cancel has something
  to undo.
- Give every wheel a `label`. It is the accessible name.
- Use `loop` for a cycle (hours, minutes, months), never for a bounded run
  like a year. Keep looping wheels short; the list is repeated to fake the
  ends.
- Set `minuteStep` to what the value really has: 15 for opening hours, 5 for
  a booking, 1 only for an alarm. Use `monthFormat="short"` (or `"numeric"`)
  when three wheels share a phone's width.

#### Don't

- Show the stored `"14:30"` to a person. It is data; read it back through
  `Intl.DateTimeFormat` with `latn()`, which pins the 12-hour clock.
- Stack more than four wheels. Each one gets too narrow to read or hit.
- Use it for a value with no natural order, like a country or a category.
- Put one inside a scrolling column without room around it. A wheel takes
  the vertical drag that would otherwise scroll the page.
- Reimplement the momentum. The scrolling is the browser's own.

#### Pairs with

- [Sheet](/docs/components/sheet), [Dialog](/docs/components/dialog),
  [Number Input](/docs/components/number-input),
  [Select](/docs/components/select), [Button](/docs/components/button)

Parts (`classes`): `root` `header` `stage` `band` `wheels` `actions` `action`

| Prop | Type | Notes |
| --- | --- | --- |
| `value?` | `Date \| null` | The date. Bindable. `null` until a wheel is touched. Default `null`. Bindable. |
| `min?` | `Date` | Earliest selectable date. Also the first year on the wheel. |
| `max?` | `Date` | Latest selectable date. Also the last year on the wheel. |
| `locale?` | `string` | BCP-47 tag for the month names and the column order. |
| `monthFormat?` | `'long' \| 'short' \| 'numeric'` | How the months read. `numeric` for a wheel with no room for names. Default `'long'`. |
| `weekday?` | `boolean` | Prefix the day with its weekday — "Wed 17". Default `false`. |
| `labels?` | `{ day?: string; month?: string; year?: string }` | Accessible names for the three wheels. |
| `onchange?` | `(value: Date) => void` | Fires once a wheel settles. |
| `columnClasses?` | `PickerColumnClasses` | Per-part overrides for the wheels themselves. |
| `classes?` | `PickerClasses` |  |
| `size?` | `PickerSize` | Row height and type scale. |
| `surface?` | `PickerSurface` | How the frame is drawn. |
| `visible?` | `number` | Rows on screen at once. Rounded up to the next odd number. |
| `title?` | `string` | A title above the wheels. |
| `disabled?` | `boolean` | Disables every wheel inside. |
| `haptics?` | `boolean` | Play a tick as each row passes the centre, once haptics are on. |
| `onconfirm?` | `() => void` | Renders the action row. Called with the value already committed. |
| `oncancel?` | `() => void` | Renders a cancel button beside it. |
| `confirmLabel?` | `string` |  |
| `cancelLabel?` | `string` |  |
| `footer?` | `Snippet` | Replaces the built-in action row. |
| `class?` | `string` |  |

### DateRangeField

`import { DateRangeField } from 'omaris'`

A date-range input for a dashboard's filter bar: a field that reads "Mar 3 – 9, 2026" and opens two months side by side with a rail of shortcuts — Today, Last 7 days, This month — beside them.

#### Use it for

- The period filter at the top of a dashboard or a report: "Mar 3 – 9,
  2026", with Today, Last 7 days, Last 30 days, This month, Last month and
  This year one press away.
- A span in a form — a leave request, a campaign's run, a rental — where the
  two ends belong to one question.
- Commit-on-Apply on a phone: the sheet keeps a draft, so a thumb that lands
  on the wrong day changes nothing until Apply.

#### Not for

- One date → [Date Field](/docs/components/date-field).
- A range picked on the page itself, with no field → [Calendar](/docs/components/calendar)
  with `mode="range"`.
- A handful of fixed periods and nothing else — "7d / 30d / 90d" →
  [Segmented Button](/docs/components/segmented-button). A calendar behind a
  field is overhead when nobody picks a custom range.
- A range of times within a day → two `TimePicker`s in
  [Picker](/docs/components/picker).

#### Do

- Set `max={today}` on a filter over data that ends today. The presets clamp
  to it, so "This month" becomes month-to-date.
- Replace the presets with the periods your users actually compare —
  `presets` takes `{ label, range }`, and the date helpers build the ranges.
- Translate `labels` and the preset labels together when the page is not in
  English; the calendar translates itself.
- Show the chosen period somewhere in the view it filters, not only in the
  field — the chart's subtitle, the export's filename.

#### Don't

- Keep the default presets when `min` rules most of them out. A rail of
  greyed shortcuts reads as broken.
- Expect `value` to change on the first calendar press. It changes when the
  range is whole — the second press on a desktop, Apply on a phone.
- Put two of these side by side for "compare to". Say what is being compared
  and give the second one its own label.

#### Pairs with

- [Date Field](/docs/components/date-field), [Calendar](/docs/components/calendar),
  [Segmented Button](/docs/components/segmented-button),
  [Select](/docs/components/select), [Chart](/docs/components/chart),
  [Table](/docs/components/table)

Parts (`classes`): `body` `presets` `preset` `footer` `root` `field` `control` `value` `placeholder` `icon` `action` `label` `support` `panel` `sheet`

| Prop | Type | Notes |
| --- | --- | --- |
| `value?` | `DateRange \| null` | The range, or `null`. Bindable. Default `null`. |
| `variant?` | `DateFieldVariant` | `outline`, `filled` or `ghost` — the same frames as `Input`. Default `'outline'`. |
| `size?` | `DateFieldSize` | `sm`, `default` or `lg` — the same heights as `Input`. Default `'default'`. |
| `label?` | `string` | Label above the field. |
| `required?` | `boolean` | Marks the label required. Default `false`. |
| `supportingText?` | `string` | Helper line under the field. Turns into the error text when invalid. |
| `invalid?` | `boolean` | Marks the field invalid and wires up aria-invalid. Default `false`. |
| `placeholder?` | `string` | Shown, greyed, while there is no range. Default `'Select a range'`. |
| `format?` | `Intl.DateTimeFormatOptions` | `Intl.DateTimeFormat` options for the two ends, joined by `formatRange`. Default `{ dateStyle: 'medium' }`. |
| `presets?` | `DatePreset[]` | Shortcuts beside the calendar — Today through This year unless you pass your own, or `[]` for none. Each is clamped to `min` and `max` when chosen, and one that falls wholly outside them is disabled. Default `defaultDatePresets`. |
| `months?` | `1 \| 2` | Months side by side on a desktop. A phone always gets one. Default `2`. |
| `min?` | `Date` | Earliest selectable day. |
| `max?` | `Date` | Latest selectable day — `today` for a filter over data that ends now. |
| `isDateDisabled?` | `(date: Date) => boolean` | Days that cannot be picked. |
| `locale?` | `string` | BCP-47 tag for the field and the calendar. Defaults to `<html lang>`. |
| `weekStartsOn?` | `Weekday` | 0 is Sunday. Defaults to the locale's first day. |
| `clearable?` | `boolean` | Show an × that empties the field once it has a range. Default `true`. |
| `open?` | `boolean` | Whether the calendar is open. Bindable. Default `false`. |
| `mobileQuery?` | `string` | What counts as a phone, where the calendar opens in a bottom sheet. Default `'(max-width: 639px)'`. |
| `labels?` | `DateRangeFieldLabels` | The words the field says itself — the presets group's name, Apply, Cancel. |
| `onchange?` | `(value: DateRange \| null) => void` | Fires when a range is committed or cleared. |
| `class?` | `string` | Merged onto the root wrapper. |
| `classes?` | `DateRangeFieldClasses` | Per-part Tailwind overrides — the frame's parts and the presets'. |
| `calendarClasses?` | `CalendarClasses` | Per-part overrides for the calendar inside the popup. |
| `ref?` | `HTMLButtonElement \| null` | The trigger button. Default `null`. Bindable. |

### DateTimePicker

`import { DateTimePicker } from 'omaris'`

A day, an hour and a minute in one row of wheels.

Parts (`classes`): `root` `header` `stage` `band` `wheels` `actions` `action`

| Prop | Type | Notes |
| --- | --- | --- |
| `value?` | `Date \| null` | The moment. Bindable. Default `null`. |
| `min?` | `Date` | First selectable day. Defaults to today. |
| `max?` | `Date` | Last selectable day. Defaults to a year from today. |
| `minuteStep?` | `number` | Minutes between rows. Default `5`. |
| `locale?` | `string` | BCP-47 tag for the day labels. |
| `relative?` | `boolean` | Say "Today" and "Tomorrow" instead of their dates. Default `true`. |
| `labels?` | `{ day?: string; hour?: string; minute?: string; meridiem?: string; am?: string; pm?: string; }` |  |
| `onchange?` | `(value: Date) => void` |  |
| `columnClasses?` | `PickerColumnClasses` | Per-part overrides for the wheels themselves. |
| `classes?` | `PickerClasses` |  |
| `size?` | `PickerSize` | Row height and type scale. |
| `surface?` | `PickerSurface` | How the frame is drawn. |
| `visible?` | `number` | Rows on screen at once. Rounded up to the next odd number. |
| `title?` | `string` | A title above the wheels. |
| `disabled?` | `boolean` | Disables every wheel inside. |
| `haptics?` | `boolean` | Play a tick as each row passes the centre, once haptics are on. |
| `onconfirm?` | `() => void` | Renders the action row. Called with the value already committed. |
| `oncancel?` | `() => void` | Renders a cancel button beside it. |
| `confirmLabel?` | `string` |  |
| `cancelLabel?` | `string` |  |
| `footer?` | `Snippet` | Replaces the built-in action row. |
| `class?` | `string` |  |

### DeviceMockup

`import { DeviceMockup } from 'omaris'`

A device drawn around whatever you put on its screen.

#### Use it for

- Showing a screen in the device it runs on: a phone on a marketing page, a
  tablet in a case study, a laptop above the fold. Pick a `device` and a
  `finish`, and put your own components inside it.
- Previewing your own UI at a real device width. The screen is laid out at
  the device's viewport (390 CSS px for `phone`, 834 for `tablet`, 1440 for
  `laptop`), however small the mockup is drawn.
- A responsive preview. Drive `device` and `orientation` from a
  [Segmented Button](/docs/components/segmented-button); the snippet is told
  the `width` it is laid out at.
- A live site. `src` loads it in an iframe at the device's viewport, so it
  lays out, scrolls and navigates like it would on the hardware.
- A screenshot. `image` fills the glass edge to edge.

#### Not for

- One screenshot with nothing to say about the hardware → a plain `<img>`,
  or [Image Viewer](/docs/components/image-viewer) when it should open.
- A phone-shaped panel in your app's own layout, like a preview column →
  [Card](/docs/components/card) or [Resizable](/docs/components/resizable).
  A drawn frame around real application UI reads as a mistake.
- A gallery of screenshots → [Carousel](/docs/components/carousel) or
  [Masonry](/docs/components/masonry), with one mockup as the hero above it.
- Testing a real viewport while you build. Use the browser's device toolbar.

#### Do

- Let it size itself. Each device has a width it looks right at and it never
  grows past its container. Set `width` (or a `w-*` / `max-w-*` class) when
  the layout needs a particular size.
- Give the glass the background: `classes={{ screen: 'bg-surface-container-low' }}`.
  It runs edge to edge behind the status bar and the island, while your
  content sits between them and scrolls when it is taller than the screen.
- Put a light `text-*` on the glass over a dark wallpaper. The clock and the
  battery follow the screen's text colour.
- Use `safeArea={false}` for a wallpaper or hero picture that should run
  under the hardware. The insets are on the glass as `--device-safe-top`
  (and `-right`, `-bottom`, `-left`) and in the snippet as `safe`.
- Give a site or a screenshot a name with `label`: it becomes the iframe's
  title and the image's alt text. Sandbox a site you do not control with
  `sandbox="allow-scripts allow-same-origin"`.
- Add `inert` when the mockup is decoration, so it takes no clicks, focus or
  scrolls.

#### Don't

- Set a height on it. The height follows from the width and the device;
  size it by width only.
- Turn a laptop, a browser window or a watch sideways. `orientation` only
  applies to `phone`, `android` and `tablet`.
- Point `src` at the page the mockup is on. The iframe loads that page,
  mockup and all.
- Load several live sites on one page. Each `src` is a full browsing
  context. Use `image` for the ones that are only looked at.

#### Pairs with

- [Segmented Button](/docs/components/segmented-button),
  [Carousel](/docs/components/carousel), [Card](/docs/components/card),
  [Tabs](/docs/components/tabs), [App Shell](/docs/components/app-shell)

Parts (`classes`): `root` `frame` `screen` `content` `status` `cutout` `button` `stand` `chrome`

| Prop | Type | Notes |
| --- | --- | --- |
| `device?` | `DeviceId` | Which frame to draw. Default `'phone'`. |
| `orientation?` | `DeviceOrientation` | Turned sideways. The laptop, the browser and the watch ignore it. Default `'portrait'`. |
| `finish?` | `DeviceFinish` | The body's colour. The browser window follows the theme instead. One of `graphite`, `silver`, `gold`, `sky`, `porcelain`. Default `'graphite'`. |
| `width?` | `number \| string` | How wide to draw it — px, or any CSS length. It still never grows past its container. Defaults to a width that suits the device. |
| `image?` | `string` | A screenshot to fill the screen with, edge to edge. |
| `src?` | `string` | A site to load on the screen, at the device's own viewport. |
| `label?` | `string` | Accessible name: the iframe's title, the image's alt text. |
| `sandbox?` | `string` | `sandbox` for the iframe. Set it for a site you do not control. |
| `allow?` | `string` | `allow` for the iframe — clipboard, camera, fullscreen. |
| `url?` | `string` | What the browser window's address bar reads. Defaults to `src`'s host. |
| `statusBar?` | `boolean` | The clock and battery across the top of a phone, tablet or watch. Default `true`. |
| `safeArea?` | `boolean` | Keep content clear of the status bar, the island and the home indicator. Off, it runs under them — for a wallpaper or a full-bleed picture. An `image` is always full bleed. Default `true`. |
| `class?` | `string` |  |
| `classes?` | `DeviceMockupClasses` |  |
| `children?` | `Snippet<[DeviceScreenContext]>` | What goes on the screen. Takes the screen's size, if it wants it. |

### Dialog

`import { Dialog } from 'omaris'`

MD3 dialog, on the native `<dialog>` element.

#### Use it for

- An interruption that needs an answer first: delete, discard, sign out.
  `dialog.confirm()` from the provider is one line and returns a promise;
  `destructive: true` paints the confirming button.
- A short form finished or abandoned in one go, like an invite or a rename.
  `dialog.prompt()` gives a single field.
- Something the person must read before going on, like an expired session
  or a failed payment. `dialog.alert()`.
- A bigger task that still ends in finish or cancel, like an editor or a
  crop. `size="full"`. Steps inside it morph the one panel instead of
  opening a second dialog.

#### Not for

- A task that keeps the page in view: filters, editing a record beside its
  table, an inspector → [Sheet](/docs/components/sheet).
- Feedback that needs no answer, like "Saved" or "Sent" → [Toast](/docs/components/toast).
  A toast never blocks; a dialog always does.
- A few actions off a button → [Menu](/docs/components/menu).
- Explaining the screen → [Tour](/docs/components/tour).
- A picture full-screen → [Image Viewer](/docs/components/image-viewer).

#### Do

- Phrase `title` as the question ("Delete this project?") and `description`
  as the consequence. Actions answer it: "Delete" and "Cancel", never "Yes",
  "No" or "OK".
- Keep `actions` to two: the safe one `variant="text"` first, the committing
  one `filled` last.
- Leave `responsive` on. Below 640px the dialog becomes a bottom sheet with
  a drag handle.
- Use `dialog.confirm()` before writing a `Dialog` with `bind:open`. The
  component is for a body of your own.

#### Don't

- Open a dialog from a dialog. Change the content and let `morph` grow the
  panel.
- Set `dismissible={false}` unless leaving would lose work, and then still
  offer a way out among the actions.
- Put a long document in a `md` dialog. Use `size="lg"`, `full`, or a page.
- Show one on page load, or for anything that is not the person's decision.

#### Pairs with

- [Button](/docs/components/button), [Sheet](/docs/components/sheet),
  [Toast](/docs/components/toast), [Text Field](/docs/components/input),
  [Text](/docs/components/text)

Parts (`classes`): `root` `panel` `body` `close` `handle` `grip` `icon` `header` `title` `description` `content` `actions`

| Prop | Type | Notes |
| --- | --- | --- |
| `open?` | `boolean` | Bindable. Default `false`. |
| `size?` | `DialogSize` | One of `sm`, `md`, `lg`, `xl`, `full`. Default `'md'`. |
| `title?` | `string` | Headline. |
| `description?` | `string` | Supporting text under the headline. |
| `centered?` | `boolean` | Center the icon, headline and supporting text. Default `false`. |
| `dismissible?` | `boolean` | Allow Escape and a backdrop press to close it. Default `true`. |
| `closable?` | `boolean` | Close button at the top end corner. Defaults to `dismissible`. |
| `closeLabel?` | `string` | Accessible name for that button. Default `'Close'`. |
| `responsive?` | `boolean` | Become a bottom sheet on a phone. On by default. Default `true`. |
| `mobileQuery?` | `string` | What counts as a phone. Default `'(max-width: 639px)'`. |
| `morph?` | `boolean` | Animate height and width changes. On by default. Default `true`. |
| `drag?` | `boolean` | Drag the bottom sheet away with a finger. On by default. Default `true`. |
| `onclose?` | `() => void` | Called after the dialog has finished closing. |
| `class?` | `string` |  |
| `classes?` | `DialogClasses` | Per-part Tailwind overrides. `class` still covers the root. |
| `icon?` | `Snippet` | Icon above the headline. |
| `children?` | `Snippet` | The body. |
| `actions?` | `Snippet` | Buttons along the bottom. |

### DiffViewer

`import { DiffViewer } from 'omaris'`

A diff, unified or side by side, with the syntax colouring the rest of the library uses.

#### Use it for

- Two versions of a file or setting: a review, an audit trail, what changed
  since the last publish. Pass `before` and `after`. A renamed variable
  shows as one word moving, not two lines replaced.
- A patch from a server or `git diff`. `patch` renders it as is, with no
  `before`/`after` to reconstruct.
- A long file with one change. `context={3}` keeps three lines either side
  and folds the rest into a strip that opens on click.
- Side by side on a wide screen. `view="split"`, plus `switchable` to let
  the reader choose. `view` is bindable, so the choice can be kept.

#### Not for

- A hand-written five-line change in a docs page → [Code Block](/docs/components/code-block)
  with `diff`.
- Reviewing and fixing the change → [Code Editor](/docs/components/code-editor)
  beside it. The viewer is read-only.
- Two JSON documents → [JSON Viewer](/docs/components/json-viewer) to explore
  one. For the difference, pretty-print both with the same key order and
  pass them here as `lang="json"`.
- Prose that changed. A line diff of a paragraph is one changed line. Diff
  at the word level in the editor that owns the prose.

#### Do

- Set `lang`. Both sides are highlighted whole, so a block comment or a
  multi-line string stays coloured across a change.
- Name the file with `title`, or `titles={['old.ts', 'new.ts']}` for a
  rename. Keep `stats` so `+12 −4` says how big the change is.
- Cap it with `height` in a sheet or card. Use `wrap` in a narrow column
  instead of sideways scrolling.
- Set `emptyText` for "nothing changed". A blank frame reads as broken.

#### Don't

- Pass `context={Infinity}` for a long file. 400 unchanged lines are not the
  change.
- Force `split` on a phone. Unified is the one that fits.
- Re-tint the rows by hand. The three change colours are slots shared by
  both views.

#### Pairs with

- [Code Block](/docs/components/code-block),
  [Code Editor](/docs/components/code-editor), [Sheet](/docs/components/sheet),
  [Dialog](/docs/components/dialog), [Tabs](/docs/components/tabs)

Parts (`classes`): `root` `header` `title` `stats` `added` `removed` `action` `viewport` `table` `row` `side` `gutter` `sign` `code` `word` `gap` `empty`

| Prop | Type | Notes |
| --- | --- | --- |
| `before?` | `string` | The old text. Ignored when `patch` is given. Default `''`. |
| `after?` | `string` | The new text. Default `''`. |
| `patch?` | `string` | A unified patch, as `git diff` prints it. Wins over `before`/`after`. |
| `lang?` | `string` | `ts`, `svelte`, `css`, … — the same names `CodeBlock` takes. Default `'plain'`. |
| `view?` | `DiffView` | Default `'unified'`. Bindable. |
| `size?` | `DiffViewerSize` | One of `sm`, `md`. Default `'md'`. |
| `context?` | `number` | Unchanged lines kept either side of a change. `Infinity` keeps them all. Default `3`. |
| `lineNumbers?` | `boolean` | Default `true`. |
| `wrap?` | `boolean` | Default `false`. |
| `title?` | `string` | Filename in the header. |
| `titles?` | `[string, string]` | Per-side filenames, for a rename. Falls back to `title`. |
| `stats?` | `boolean` | Show the `+n −n` counts. Default `true`. |
| `switchable?` | `boolean` | Offer the unified / split switch. Default `false`. |
| `emptyText?` | `string` | Shown when nothing changed. Default `'No changes.'`. |
| `height?` | `number \| string` | Tallest the scroller gets. A number is px, a string any CSS length. Default `'32rem'`. |
| `class?` | `string` |  |
| `classes?` | `DiffViewerClasses` |  |

### Divider

`import { Divider } from 'omaris'`

MD3 divider — a hairline that separates content without dividing the layout. `inset` indents it past a leading icon or avatar so the rule lines up with the text column of a list.

#### Use it for

- Rows dense enough to run together, like a message list or a menu with two
  groups. `inset="start"` past an avatar or icon lines the rule up with the
  text column.
- A rule with a word on it between two ways of doing the same thing:
  `<Divider>or</Divider>` between "Continue with Google" and the email form.
- A vertical rule between inline metadata or toolbar groups.
  `orientation="vertical"` between "Draft" and "Edited 3m ago".
- A full-width rule between unrelated regions of a screen, in
  `emphasis="strong"`.

#### Not for

- Between every row of a `List` by hand → `dividers` on
  [List](/docs/components/list). It insets past the leading slot and skips
  the last row.
- Between cards or sections that already have their own surface → a
  `gap-6`. A hairline under a [Card](/docs/components/card) is noise.
- Under a heading, as decoration → a [Text](/docs/components/text) heading
  with space below it.
- A section title inside a rule → a heading. A labelled divider is for "or"
  and "then", not "Details".

#### Do

- Try whitespace first. Add a divider only when the grouping is still
  unclear.
- Use `inset="both"` for a rule inside a padded card, so it stops where the
  content stops.
- Give a vertical divider a `flex` row with a height (`h-10 items-center`)
  to stretch in. It is `self-stretch`, not a fixed height.
- Keep `emphasis="subtle"` inside lists and menus. `strong` is for the one
  rule between the app bar's region and the page.

#### Don't

- Draw one after the last row.
- Stack a divider on a spacing utility or a `border-b`. Pick one.
- Put a rule under a [Top App Bar](/docs/components/top-app-bar). It already
  lifts onto a raised surface as the page scrolls.
- Use it as a spacer. It has no height.

#### Pairs with

- [List](/docs/components/list), [Menu](/docs/components/menu),
  [Card](/docs/components/card), [Top App Bar](/docs/components/top-app-bar),
  [Text](/docs/components/text)

| Prop | Type | Notes |
| --- | --- | --- |
| `orientation?` | `DividerOrientation` | One of `horizontal`, `vertical`. Default `'horizontal'`. |
| `inset?` | `DividerInset` | Indent so the rule aligns with a list's text column. One of `none`, `start`, `both`. Default `'none'`. |
| `emphasis?` | `DividerEmphasis` | One of `subtle`, `strong`. Default `'subtle'`. |
| `class?` | `string` |  |
| `children?` | `Snippet` | A label sat in the middle of the rule. Horizontal only. |

### Dock

`import { Dock } from 'omaris'`

The macOS dock, in Material.

#### Use it for

- A launcher: a handful of apps, tools or workspaces a person switches
  between all day. `active` marks the one that is running or current.
- A floating toolbar over a canvas, a map or a board: `orientation="vertical"`
  down one side, `variant="glass"` when it sits over the picture.
- Quick actions in a desktop dashboard's corner, where a pointer will find
  them and a swelling tile makes six icons easy to tell apart.
- A shortcut strip with counts: `badge` for what is waiting behind a tile.

#### Not for

- The main navigation of a phone app → [Navigation Bar](/docs/components/navigation-bar).
  A finger gets no magnification, and a bar that names its destinations is
  what a phone needs.
- More than about eight items → [Navigation Drawer](/docs/components/navigation-drawer)
  or a [Menu](/docs/components/menu). A dock that scrolls is a list.
- Actions that belong to one screen's content → [Button](/docs/components/button)
  in the content, or a [FAB](/docs/components/fab) for the one that matters.
- A row of options where one is chosen → [Segmented Button](/docs/components/segmented-button).

#### Do

- Give it a `label` ("Apps"), and every `DockItem` a `label` — it is the
  tooltip and the accessible name, and an icon alone names nothing.
- Keep the icons one family and one weight. The tiles are identical boxes;
  a mismatched icon is the only thing on the bar that will look wrong.
- Leave `size` at 48 on anything a finger might use. A dock does not swell
  for a touch, so the base size is the whole target.
- Use `variant="glass"` only over something worth blurring — a photo, a
  gradient, a map. Over a flat surface it is `elevated` for more work.
- Put a `DockDivider` between the things that launch and the things that
  collect — apps, then the trash.

#### Don't

- Set a width, height or transform on a `DockItem` from outside. The dock
  owns a tile's size and place; style the tile through `classes.control`,
  and the bar's look through `classes.surface` — `bar` is only the row.
- Raise `magnification` past about 2. Tiles that double push their
  neighbours out of reach and the pointer chases a moving target.
- Use `labels="never"` on a dock of abstract icons. It is for a dock whose
  icons are the brand marks everyone knows.
- Put a dock inside a scrolling container that clips it. The tiles grow out
  of the bar, and a clipped tile reads as a bug.

#### Pairs with

- [Tooltip](/docs/components/tooltip),
  [Badge](/docs/components/badge), [Icon Button](/docs/components/icon-button),
  [Navigation Bar](/docs/components/navigation-bar)

Parts (`classes`): `bar` `surface`

| Prop | Type | Notes |
| --- | --- | --- |
| `orientation?` | `DockOrientation` | One of `horizontal`, `vertical`. Default `'horizontal'`. |
| `variant?` | `DockVariant` | One of `elevated`, `filled`, `glass`, `plain`. Default `'elevated'`. |
| `size?` | `number` | Base tile size, in px. Default `48`. |
| `magnification?` | `number` | How big the tile under the pointer gets, as a multiple of `size`. `1` turns the effect off. Default `1.7`. |
| `distance?` | `number` | How far from the pointer a tile is still affected, in px. Default `130`. |
| `labels?` | `DockLabels` | When labels show. `hover` (the default) is the tooltip above the tile under the pointer or with focus; `always` prints them under every tile; `never` keeps them for assistive tech only. Default `'hover'`. |
| `label?` | `string` | Accessible name — "Apps". |
| `class?` | `string` |  |
| `classes?` | `DockClasses` | Per-part Tailwind overrides. `class` still covers the root. |
| `children?` | `Snippet` |  |

### DockDivider

`import { DockDivider } from 'omaris'`

A hairline between two groups of tiles — apps on one side, the trash on the other.

| Prop | Type | Notes |
| --- | --- | --- |
| `class?` | `string` |  |

### DockItem

`import { DockItem } from 'omaris'`

One tile in a `Dock`: an icon, a name, and the press.

Parts (`classes`): `root` `tile` `control` `label` `dot` `badge`

| Prop | Type | Notes |
| --- | --- | --- |
| `label` | `string` | The tile's name. Drawn as the tooltip, and read to assistive tech always. |
| `href?` | `string` | Makes it a link. |
| `target?` | `string` |  |
| `active?` | `boolean` | The running dot under the tile — or "you are here". Default `false`. |
| `badge?` | `string \| number \| boolean` | A count in the corner. `true` for a plain dot. |
| `disabled?` | `boolean` | Default `false`. |
| `onclick?` | `(event: MouseEvent) => void` |  |
| `class?` | `string` |  |
| `classes?` | `DockItemClasses` | Per-part Tailwind overrides. `class` still covers the root. |
| `children?` | `Snippet` | The icon. An `<svg>` is sized to half the tile, an `<img>` fills it. |

### DrawingBoard

`import { DrawingBoard } from 'omaris'`

An infinite canvas you can actually draw on: pen, shapes, arrows, text and sticky notes, with pan, zoom, selection, undo and export.

#### Use it for

- A whiteboard: freehand, shapes, arrows, text and sticky notes on an
  infinite canvas. Pan, zoom, selection, undo and export are built in.
- Marking up a picture. Put an image element on the board or drop one on
  it, then annotate. `tools` cuts the strip down to the four you want.
- A diagram built from data. Elements are plain objects, so a flow chart can
  be generated from a record and edited by hand.
- A signature or sketch field: `tools={['pen', 'eraser']}` with the panels
  off, then `toBlob()` on save.
- Showing a saved drawing. `readonly` keeps pan and zoom and removes the
  rest.
- Sketch to picture. `ai={{ generate }}` — the same function
  [AI Image](/docs/components/ai-image) takes — adds a sparkle to the strip
  that sends the selection or the drawing to the model and puts the result
  back on the board. Optional; without it nothing changes.

#### Not for

- Rich text with a caret, headings and lists → [Rich Text Editor](/docs/components/rich-text-editor).
- Cards in columns that people drag between → [Kanban](/docs/components/kanban).
- Cropping, straightening or framing one photo → [Image Cropper](/docs/components/image-cropper).
- Looking at a picture with zoom, swipe and next → [Image Viewer](/docs/components/image-viewer).
- Charts. Data drawn from numbers is a [chart](/docs/components/chart).
- Multiplayer. There is no transport; `elements` is the state, and sending
  it is yours to do.

#### Do

- Use `bind:elements` and save what you get. It is JSON, and `load()` puts
  it back exactly, including the camera if you saved `toJSON()`.
- Use data URLs for images. An object URL dies with the page and cannot be
  rasterised, so `toBlob()` comes back with a hole.
- Use `bind:this` for the methods: `undo`, `zoomToFit`, `insertImage`,
  `toSVG`, `toBlob`, `load`, `clear`.
- Give it a height. `height` is a property, not a class, so `classes.canvas`
  can still restyle the stage.
- Pick a tool from your own chrome with `bind:tool` when the strip is off;
  the shortcuts keep working. Turn `keepTool` on only where people draw the
  same shape many times, since a shape normally lands selected.
- Paint with the ink tokens, `var(--ink-blue)`, `var(--ink-red)`, not hex,
  when you build elements yourself. They stay legible in both themes.
- Put it on a phone. Below about 30rem the chrome folds into one scrolling
  bar and the paint panel becomes a sheet; two fingers pan and zoom, and a
  double-tap opens text. A narrow desktop column folds the same way.

#### Don't

- Put a thousand elements on it and expect smooth scrolling. It draws SVG,
  which is right for a board people draw on and wrong for a generated map.
- Turn `toolbar` off with `stylePanel` on unless you also give people a way
  to pick a tool. The panel paints what the tool is about to draw.
- Style the root's height with a class. `h-96` on `class` fights the
  `--board-h` the property sets.
- Give a phone a `height` taller than the screen. The canvas takes the whole
  gesture, so the page cannot scroll past it. `height="min(32rem, 60svh)"`
  leaves a way out.
- Expect `toBlob()` to include a cross-origin image. The canvas is tainted
  and the export throws, as it does for [Image Cropper](/docs/components/image-cropper).

#### Pairs with

- [AI Image](/docs/components/ai-image),
  [Image Cropper](/docs/components/image-cropper), [Image Viewer](/docs/components/image-viewer),
  [Rich Text Editor](/docs/components/rich-text-editor), [Dialog](/docs/components/dialog),
  [Sheet](/docs/components/sheet), [Button](/docs/components/button),
  [Color Picker](/docs/components/color-picker), [Tabs](/docs/components/tabs)

Parts (`classes`): `root` `canvas` `surface` `overlay` `panel` `toolbar` `style` `section` `caption` `row` `button` `swatch` `choice` `slider` `zoom` `history` `status` `separator` `editor`

| Prop | Type | Notes |
| --- | --- | --- |
| `elements?` | `DrawingElement[]` | The document. Bindable, and the whole state of the drawing. Default `[]`. Bindable. |
| `tool?` | `DrawingTool` | The tool in hand. Bindable, so a toolbar of your own can set it. Default `'pen'`. Bindable. |
| `selection?` | `string[]` | Ids of the selected elements. Bindable. Default `[]`. |
| `camera?` | `Camera` | Where the camera is and how far in. Bindable. Default `{ x: 0, y: 0, zoom: 1 }`. |
| `ink?` | `DrawingStyle` | The paint new elements are made with — and what a selection is repainted to. Bindable. Default `{ ...defaultDrawingStyle }`. |
| `tools?` | `DrawingTool[]` | Which tools the strip offers, in order. Default `drawingBoardTools.map((spec) => spec.tool)`. |
| `palette?` | `DrawingSwatch[]` | The colours in the stroke row. Default `drawingInk`. |
| `fills?` | `DrawingSwatch[]` | The colours in the fill row. Default `drawingFills`. |
| `toolbar?` | `boolean` | Default `true`. |
| `toolbarPosition?` | `DrawingBoardToolbarPosition` | One of `top`, `bottom`. Default `'top'`. |
| `stylePanel?` | `boolean` | Default `true`. |
| `panelSide?` | `DrawingBoardPanelSide` | One of `start`, `end`. Default `'start'`. |
| `zoomControls?` | `boolean` | Default `true`. |
| `historyControls?` | `boolean` | Default `true`. |
| `grid?` | `DrawingGrid` | The backdrop: `'dots'`, `'lines'`, or `'none'` for a blank page. Default `'dots'`. |
| `gridSize?` | `number` | Grid spacing in scene units — and the step everything snaps to. Default `20`. |
| `snap?` | `boolean` | Snap new and moved elements to the grid. Bindable. Default `false`. |
| `keepTool?` | `boolean` | Keep the tool in hand after a shape is drawn, instead of dropping back to select. For drawing ten of something in a row. Default `false`. |
| `readonly?` | `boolean` | Look, don't touch. Pan and zoom still work. Default `false`. |
| `minZoom?` | `number` | How far out and in the camera may go. Default `0.1`. |
| `maxZoom?` | `number` | Default `8`. |
| `maxHistory?` | `number` | How many steps of undo to keep. Default `100`. |
| `height?` | `number \| string` | Height of the board. A number is px, a string any CSS length. Default `'32rem'`. |
| `onchange?` | `(elements: DrawingElement[]) => void` | Fires after any change to the document, with the new elements. |
| `onselect?` | `(selected: DrawingElement[]) => void` | Fires when the selection changes, with the selected elements. |
| `ontool?` | `(tool: DrawingTool) => void` | Fires when the tool changes — including from a keyboard shortcut. |
| `oncamera?` | `(camera: Camera) => void` | Fires while panning and zooming. |
| `ai?` | `DrawingBoardAi` | The optional AI: a sparkle in the strip that draws from the sketch. |
| `toolbarExtra?` | `Snippet` | Extra buttons at the end of the tool strip. |
| `panelExtra?` | `Snippet` | Extra controls at the foot of the style panel. |
| `children?` | `Snippet` | Your own chrome, over the canvas. |
| `class?` | `string` |  |
| `classes?` | `DrawingBoardClasses` |  |

### Emoji

`import { Emoji } from 'omaris'`

One emoji, drawn by the emoji font at a size you can name.

#### Use it for

- A message composer, a comment box, a reaction bar: anywhere people add an
  emoji to text. `EmojiButton` is that shape ready-made.
- A "pick an icon" field for a status, a channel or a project. Pass `groups`
  with your own set and it picks from exactly those.
- One emoji inline in copy, at a named size, with a screen-reader label only
  when it means something. That is `Emoji`.

#### Not for

- A picker that must cover every Unicode emoji. The built-in set is a few
  hundred; pass `groups` for the long tail.
- A list of named options where the emoji is decoration → a [Select](/docs/components/select)
  or [Combobox](/docs/components/combobox) with an emoji in each row.
- A colour, a date, or an icon from your icon set. It is an emoji keyboard.
- Six fixed reactions like "react with 👍" → six plain buttons, with
  `EmojiButton` only for "more".

#### Do

- Drop `EmojiPicker` into a container and let it size itself. The column
  count comes from the width.
- Use `EmojiButton` over a hand-rolled popover. It is already a bottom sheet
  on a phone and anchored on a pointer.
- Bind `skinTone` when the rest of the app shows people's emoji.
- Give `Emoji` a `label` when the emoji is the whole message ("🟢" for
  "online"). Leave it off when text beside it already says so.

#### Don't

- Set `autofocus` on a picker visible on page load. It steals the cursor.
- Share a `storageKey` between unrelated pickers, or recents leak between
  them. `null` keeps recents for the life of the component only.
- Put a bare emoji in a `<span>` with a size class. It hangs below the
  baseline and is read out by its Unicode name.

#### Pairs with

- [Text Field](/docs/components/input), [Textarea](/docs/components/textarea),
  [Icon Button](/docs/components/icon-button), [Sheet](/docs/components/sheet),
  [Avatar](/docs/components/avatar)

| Prop | Type | Notes |
| --- | --- | --- |
| `emoji` | `string` | The character. |
| `label?` | `string` | What it means, for a screen reader — "Celebrating", not "party popper". Leave it out and the emoji is hidden from assistive tech, which is right whenever the text beside it already says the same thing. |
| `tone?` | `EmojiSkinTone` | Tint it. `0` is the default yellow. Default `0`. |
| `size?` | `EmojiSize` | One of `xs`, `sm`, `md`, `lg`, `xl`, `2xl`, `inherit`. Default `'md'`. |
| `class?` | `string` |  |

### EmojiButton

`import { EmojiButton } from 'omaris'`

The emoji keyboard behind a button — the shape it takes in a composer, a reaction bar or a form field.

Parts (`classes`): `trigger` `popover` `surface` `sheetPicker`

| Prop | Type | Notes |
| --- | --- | --- |
| `value?` | `string` | The emoji last chosen, tone applied. Bindable. Default `''`. |
| `open?` | `boolean` | Whether the panel is showing. Bindable. Default `false`. |
| `onselect?` | `(emoji: string, entry: EmojiEntry) => void` |  |
| `size?` | `EmojiButtonSize` | One of `sm`, `md`, `lg`. Default `'md'`. |
| `placeholder?` | `string` | Shown on the default trigger before anything is chosen. Default `'\u{1F642}'`. |
| `reflect?` | `boolean` | Put the chosen emoji on the trigger. On by default. Default `true`. |
| `closeOnSelect?` | `boolean` | Close as soon as one is picked. On by default. Default `true`. |
| `label?` | `string` | Accessible name for the default trigger. Default `'Pick an emoji'`. |
| `side?` | `AnchorSide` | Preferred side of the trigger. Flips when there isn't room. Default `'bottom'`. |
| `align?` | `AnchorAlign` | Default `'start'`. |
| `offset?` | `number` | Gap between trigger and panel, in px. Default `8`. |
| `responsive?` | `boolean` | Become a bottom sheet on a narrow screen. On by default. Default `true`. |
| `mobileQuery?` | `string` | Default `'(max-width: 639px)'`. |
| `skinTone?` | `EmojiSkinTone` | The chosen skin tone. Bindable, and remembered with the recents. Default `0`. Bindable. |
| `recent?` | `string[]` | Recently used emoji, most recent first. Bindable. Default `[]`. |
| `storageKey?` | `string \| null` | localStorage key for the recents and the tone. `null` to not persist. Default `'omaris:emoji'`. |
| `picker?` | `EmojiPickerOptions` | Everything else the panel takes. |
| `trigger?` | `Snippet<[{ open: boolean; emoji: string }]>` | Your own trigger, in place of the round button. Draw the shape only — it is rendered inside the button that opens the panel, so it must not contain an interactive element of its own. |
| `class?` | `string` |  |
| `classes?` | `EmojiButtonClasses` | Per-part Tailwind overrides. `class` still covers the trigger. |

### EmojiPicker

`import { EmojiPicker } from 'omaris'`

The emoji keyboard: search, categories, skin tone and a memory of what you picked last.

Parts (`classes`): `root` `header` `search` `searchIcon` `input` `clear` `tabs` `indicator` `tab` `scroller` `section` `heading` `grid` `cell` `empty` `emptyIcon` `emptyText` `footer` `previewEmoji` `previewName` `tones` `toneToggle` `toneList` `tone`

| Prop | Type | Notes |
| --- | --- | --- |
| `value?` | `string` | The emoji last chosen, tone applied. Bindable. Default `''`. |
| `onselect?` | `(emoji: string, entry: EmojiEntry) => void` | Called with the chosen emoji and the entry behind it. |
| `onclose?` | `() => void` | Escape on an empty search field. |
| `size?` | `EmojiPickerSize` | One of `sm`, `md`, `lg`. Default `'md'`. |
| `groups?` | `EmojiGroup[]` | Your own set, in place of the built-in one. |
| `search?` | `boolean` | Show the search field. Default `true`. |
| `query?` | `string` | What the search field is bound to. Bindable. Default `''`. |
| `searchPlaceholder?` | `string` | Default `'Search emoji'`. |
| `categories?` | `boolean` | Show the category rail. Default `true`. |
| `preview?` | `boolean` | Show the preview row along the bottom. Default `true`. |
| `tones?` | `boolean` | Offer the skin tone control. Needs `preview`. Default `true`. |
| `skinTone?` | `EmojiSkinTone` | The chosen skin tone. Bindable. Default `0`. |
| `recent?` | `string[]` | Recently used emoji, most recent first. Bindable. Default `[]`. |
| `storageKey?` | `string \| null` | localStorage key the recents and the tone are remembered under. `null` keeps them for the life of the component only. Default `'omaris:emoji'`. |
| `maxRecent?` | `number` | How many recents to keep. Default `24`. |
| `columns?` | `number` | Force a column count instead of fitting as many as the width allows. |
| `height?` | `number \| string` | Height of the scrolling area — a number of px or any CSS length. Default `260`. |
| `autofocus?` | `boolean` | Put the cursor in the search field on mount. Default `false`. |
| `bare?` | `boolean` | Drop the panel's own border, radius and background. Default `false`. |
| `emptyText?` | `string` | Default `'No emoji found'`. |
| `footer?` | `Snippet<[{ emoji: string; name: string }]>` | Replaces the preview row's contents, keeping the row. |
| `class?` | `string` |  |
| `classes?` | `EmojiPickerClasses` | Per-part Tailwind overrides. `class` still covers the root. |

### Empty

`import { Empty } from 'omaris'`

Empty state.

#### Use it for

- Nothing created yet. `title` says what goes here and `actions` holds the
  one button that makes the first one.
- No results from a search or filter. "Clear filters" is the action.
  `size="sm"` inside a card or panel.
- A failed load. `tone="destructive"` tints the icon; "Retry" is the action.
- An unfilled slot or a drop zone. `bordered` draws the dashed frame.

#### Not for

- Data still loading → [Skeleton](/docs/components/skeleton) in the shape of
  what is coming, or [Progress](/docs/components/progress) when a fraction
  is known.
- A problem with the whole page, like an outage or a permission → [Alert](/docs/components/alert)
  above content that is still there.
- A confirmation or a passing notice → [Toast](/docs/components/toast).
- A table with no rows → the `empty` snippet on [Table](/docs/components/table).
  It draws an Empty inside the frame; do not add a second one under it.

#### Do

- Say what would be here and how to get one: "No orders yet — share your
  menu to take the first", not "No data".
- Keep to one `filled` action. A second is `text` at most.
- Pass your own `icon` when the default inbox is wrong for the noun: a pin
  for places, a receipt for orders.
- Match `size` to the container: `lg` fills a route, `md` a card body, `sm`
  a sidebar panel.

#### Don't

- Use `destructive` for an absence. An empty inbox is not an error; a search
  that threw is.
- Pad it from outside. The vertical space is in `size`; `mt-40` on a `lg`
  Empty puts the button below the fold.
- Show it while filters are still applied without saying so. Table's
  `noResultsText` exists for that.

#### Pairs with

- [Button](/docs/components/button), [Skeleton](/docs/components/skeleton),
  [Table](/docs/components/table), [Card](/docs/components/card),
  [Alert](/docs/components/alert)

Parts (`classes`): `root` `icon` `title` `description` `actions`

| Prop | Type | Notes |
| --- | --- | --- |
| `title?` | `string` |  |
| `description?` | `string` |  |
| `size?` | `EmptySize` | One of `sm`, `md`, `lg`. Default `'md'`. |
| `tone?` | `EmptyTone` | One of `neutral`, `destructive`. Default `'neutral'`. |
| `bordered?` | `boolean` | Default `false`. |
| `class?` | `string` |  |
| `classes?` | `EmptyClasses` | Per-part Tailwind overrides. `class` still covers the root. |
| `icon?` | `Snippet` | Icon or illustration. A default inbox icon is used without one. |
| `children?` | `Snippet` | Extra content between the text and the actions. |
| `actions?` | `Snippet` | Buttons under the text. |

### Fab

`import { Fab } from 'omaris'`

MD3 floating action button. Three sizes (40 / 56 / 96dp), plus `extended` for the pill that carries a label next to the icon.

#### Use it for

- The single most common action on a screen: Compose, New order, Add. One
  per screen, and only when the screen has an action like that.
- A phone layout, pinned bottom-end above scrolling content, where a
  [Button](/docs/components/button) would scroll away with the list.
- `extended` when the icon alone is ambiguous. "New invoice" reads; a plus
  does not. Drop back to the icon on scroll when space is tight.
- `size="lg"` (96dp) for a screen that is nothing but that one action: a
  camera shutter, "Start scan".

#### Not for

- The primary action of a form or dialog → a `filled` [Button](/docs/components/button)
  in its footer.
- The second and third action on the same screen → [Icon Buttons](/docs/components/icon-button)
  in the [Top App Bar](/docs/components/top-app-bar), or a [Menu](/docs/components/menu).
- An icon-only action in a toolbar → [Icon Button](/docs/components/icon-button).
  A FAB has elevation and a 56dp target; a row of them would fight.
- Deleting. A FAB creates. Put removal in a `tone="destructive"` button and
  confirm it in a [Dialog](/docs/components/dialog).
- A desktop dashboard whose action lives in the header. A FAB over a table
  is a phone pattern out of place. Use it where content scrolls under it.

#### Do

- Keep the default `tonal`. Use `filled` only when nothing else on the
  screen is primary and the FAB must dominate.
- Give an icon-only FAB an `aria-label`.
- Position it yourself, `fixed bottom-4 end-4`, clear of a
  [Navigation Bar](/docs/components/navigation-bar). The component draws the
  button, not the placement.

#### Don't

- Put two FABs on one screen. The second demotes both.
- Use `size="sm"` (40dp) as the screen's action. It is for a FAB inside a
  dense surface like a card or a split-screen panel.
- Flatten the elevation with a class. A flat FAB is an [Icon Button](/docs/components/icon-button).
- Attach `confetti` to a routine action. It is for a moment worth marking:
  the first order, a milestone.

#### Pairs with

- [Button](/docs/components/button), [Icon Button](/docs/components/icon-button),
  [Navigation Bar](/docs/components/navigation-bar),
  [Top App Bar](/docs/components/top-app-bar), [Sheet](/docs/components/sheet)

| Prop | Type | Notes |
| --- | --- | --- |
| `variant?` | `FabVariant` | One of `tonal`, `filled`, `surface`. Default `'tonal'`. |
| `tone?` | `FabTone` | One of `primary`, `secondary`, `tertiary`, `destructive`, `success`, `warning`, `info`. Default `'primary'`. |
| `size?` | `FabSize` | 40 / 56 / 96dp. One of `sm`, `md`, `lg`. Default `'md'`. |
| `extended?` | `boolean` | Show the label beside the icon instead of an icon-only circle. Default `false`. |
| `ripple?` | `boolean` | Default `true`. |
| `confetti?` | `boolean \| ConfettiOptions` | Confetti on press. `true` for the default burst, or any `ConfettiOptions` — `confetti={{ preset: 'fireworks' }}`. Default `false`. |
| `class?` | `string` |  |
| `children?` | `Snippet` | The icon. Always rendered. |
| `label?` | `Snippet` | The label, shown only when `extended`. |
| `shape?` | `ButtonShape` | Pill (`round`) or MD3 rounded rectangle (`square`). |
| `icon?` | `boolean` | Square, label-less button. Requires an `aria-label`. |
| `loading?` | `boolean` | Grows a spinner in at the start of the button and blocks interaction. The label stays put; only an `icon` button swaps its icon out. |
| `toggle?` | `boolean` | Turns the button into a two-state toggle driven by `pressed`. Ignored when `href` is set — a link has no pressed state. |
| `pressed?` | `boolean` | Selected state of a toggle button. Bindable. |

### Field

`import { Field } from 'omaris'`

Field — the label, the help line and the error, around any control.

#### Use it for

- One label, one line of help and one error around a control that has none of
  its own — a bare [Input](/docs/components/input), a
  [Select](/docs/components/select), a [Slider](/docs/components/slider), a
  [Radio](/docs/components/radio) group. The control gets the right `id`,
  `aria-describedby`, `aria-invalid`, `required` and `disabled` from the field.
- A form whose errors come from one place — a validator, a server response:
  set `error` per field and each one opens its own row, announced politely.
- Settings rows: `orientation="horizontal"` puts the label and description at
  the start and a [Switch](/docs/components/switch) or a
  [Checkbox](/docs/components/checkbox) at the end.
- A control of your own: read `getFieldContext()` and it gets the same wiring.

#### Not for

- A single text field with its own label and help →
  [Input](/docs/components/input)'s `label` and `supportingText`; it already
  draws both, and a Field around it adds nothing.
- A checkbox or switch whose words sit beside it and toggle it →
  [Checkbox](/docs/components/checkbox)'s or [Switch](/docs/components/switch)'s
  own `label` and `description`.
- An error about the whole form, not one field →
  [Alert](/docs/components/alert) above the submit button.
- Several controls under one heading → a `fieldset`, or a
  [Radio](/docs/components/radio) group's own `label`. A Field describes one
  control.

#### Do

- Leave the control bare. Its own props win over the field's, so a stray
  `invalid={false}` on the control hides the field's error state.
- Set the id on the field with `controlId`, not on the control — otherwise the
  label's `for` points at an id nobody has.
- Keep `error` specific and short — "Lowercase letters and dashes only", not
  "Invalid input". Clear it the moment the value is fixed.
- Validate on blur or submit, not on every keystroke from the first one; an
  error that opens while the person is still typing is noise.

#### Don't

- Put two controls in one Field; both take the same id, and the label names
  only the first.
- Give the control a `label` as well; it will be announced twice.
- Use `description` for the error. It is always shown; `error` is what marks
  the control invalid and what a screen reader announces.

#### Pairs with

- [Input](/docs/components/input), [Textarea](/docs/components/textarea),
  [Select](/docs/components/select), [Switch](/docs/components/switch),
  [Checkbox](/docs/components/checkbox), [Tags Input](/docs/components/tags-input),
  [Label](/docs/components/label)

Parts (`classes`): `root` `label` `control` `description` `error` `collapse` `message`

| Prop | Type | Notes |
| --- | --- | --- |
| `label?` | `string` | The label. Its `for` points at the control, so pressing it focuses it. |
| `description?` | `string` | Help under the control — what the value is for, or what shape it takes. |
| `error?` | `string` | The error text. Setting it marks the field invalid; clearing it closes the error again. Announced politely, never read out over what the person is typing. |
| `invalid?` | `boolean` | Invalid with no message — for when the reason is shown somewhere else. Set automatically by `error`. Default `false`. |
| `required?` | `boolean` | Stars the label and marks the control required. Default `false`. |
| `disabled?` | `boolean` | Dims the label and description and disables the control. Default `false`. |
| `orientation?` | `FieldOrientation` | `vertical` stacks the parts. `horizontal` puts the label at the start and the control at the end — a switch, a checkbox, a compact number. One of `vertical`, `horizontal`. Default `'vertical'`. |
| `controlId?` | `string` | The control's id. Set it here rather than on the control, so the label's `for` and the control agree. Generated when omitted. |
| `children?` | `Snippet` | One control. A group — radios, a slider — is labelled by the field too. |
| `class?` | `string` |  |
| `classes?` | `FieldClasses` | Per-part Tailwind overrides. `class` still covers the root. |

### FileUpload

`import { FileUpload } from 'omaris'`

A dropzone that takes files from all three places people have them: dropped, browsed, and — the one usually missing — pasted.

#### Use it for

- Any place a person hands the app a file: attachments on a form, an import
  screen, a document drop, an avatar or cover image. `preview="grid"` shows
  images as a gallery before they are saved.
- Screenshots. `paste` is on by default, so ⌘V drops the clipboard image
  into the list. This is the main reason to use a dropzone over a bare
  `<input type="file">`.
- Uploads with feedback. Pass `upload` and each file gets a progress bar, a
  cancel while in flight and a retry after it fails.
- A whole folder. The picker takes one with `directory`; a dropped folder is
  always walked.
- A drop target that is the page rather than a box on it: `dropAnywhere`.

#### Not for

- A stored file someone is editing → pick it here, then crop it in
  [Image Cropper](/docs/components/image-cropper).
- Files already on the server, like a list of attachments with download
  links → [List](/docs/components/list) or [Table](/docs/components/table).
  This component owns files on their way in.
- One short string of text → [Text Field](/docs/components/input).
- Reordering or triaging files across columns → [Kanban](/docs/components/kanban).
- A gallery to browse rather than edit → [Image Viewer](/docs/components/image-viewer)
  or [Masonry](/docs/components/masonry).

#### Do

- Bind `files` and treat it as the state. `accept`, `max`, `maxSize` and
  `minSize` are rules about what may enter it; drop, browse and paste all
  go through them.
- Set `accept` even when the server also checks. It filters the picker as
  well as the drop.
- Give `name` when the dropzone sits in a real form. The input underneath is
  the control, so it submits and honours `required`.
- Handle `onreject` if a refusal needs logging or showing elsewhere. The
  zone already names the first one under itself for a few seconds.
- Return something from `upload`: an id, a URL, the server's row. It is kept
  on the item as `result`, which is what the form submits.
- Use `bind:this` for `open()`, `start()` when `autoUpload` is off, and
  `clear()`.
- Use `preview="none"` and the `file` snippet when the list belongs
  somewhere else on the page.

#### Don't

- Use `dropAnywhere` twice on one page, or leave `paste` on for two
  dropzones. Two veils fight over one drop, and one ⌘V lands in both; give
  all but one `paste="focus"`.
- Set `max` without `multiple`. A single-file dropzone replaces rather than
  refuses, which is what a new avatar should do.
- Hold object URLs from `preview` after removing a file. The component
  revokes them when a file goes and on unmount; copy the blob if you need it
  longer.
- Rely on `paste` alone on a phone. Keep the browse button; `browseLabel`
  set to `null` removes it, and touch has no ⌘V.
- Put a `maxSize` here and a different one on the server.

#### Pairs with

- [Button](/docs/components/button), [Progress](/docs/components/progress),
  [Image Cropper](/docs/components/image-cropper),
  [Dialog](/docs/components/dialog), [Toast](/docs/components/toast),
  [Text Field](/docs/components/input)

Parts (`classes`): `root` `zone` `spotlight` `trigger` `media` `sheet` `face` `glyph` `copy` `title` `description` `controls` `alert` `summary` `list` `item` `thumb` `info` `name` `meta` `bar` `actions` `overlay` `overlayCard`

| Prop | Type | Notes |
| --- | --- | --- |
| `files?` | `UploadFile[]` | The accepted files. Bindable, and the only state you need — every other prop is a rule about what may enter it. Default `[]`. Bindable. |
| `accept?` | `string` | `<input accept>` grammar: `image/*`, `.csv`, `application/pdf`. |
| `multiple?` | `boolean` | Default `true`. |
| `max?` | `number` | Cap on how many files may be held at once. |
| `maxSize?` | `number` | Largest file, in bytes. `5 * 1000 * 1000` is 5 MB. |
| `minSize?` | `number` | Smallest file, in bytes — catches empty and truncated files. |
| `directory?` | `boolean` | Let the picker take a whole folder. Dropped folders always walk. Default `false`. |
| `paste?` | `boolean \| 'focus'` | Take files from a paste. `true` listens on the window and skips pastes aimed at a text field elsewhere; `'focus'` only listens while the dropzone itself has focus. `false` turns it off. Default `true`. |
| `dropAnywhere?` | `boolean` | Accept a drop anywhere on the page, with a full-window veil. Default `false`. |
| `capture?` | `'user' \| 'environment'` | On a phone, open the camera instead of the file browser. |
| `name?` | `string` | Submitted with the surrounding form, like any `<input name>`. |
| `required?` | `boolean` | Default `false`. |
| `disabled?` | `boolean` | Default `false`. |
| `upload?` | `UploadFn` | Sends a file. Give it one and the component becomes an uploader. |
| `autoUpload?` | `boolean` | Start uploading the moment a file is accepted. Default `true`. |
| `concurrency?` | `number` | How many uploads run at once. Default `3`. |
| `variant?` | `FileUploadVariant` | One of `dashed`, `outlined`, `tonal`, `ghost`. Default `'dashed'`. |
| `tone?` | `FileUploadTone` | One of `primary`, `secondary`, `tertiary`, `destructive`, `success`, `warning`, `info`. Default `'primary'`. |
| `size?` | `FileUploadSize` | One of `sm`, `md`, `lg`. Default `'md'`. |
| `preview?` | `FileUploadPreview` | `list` rows, `grid` tiles, or `none` to render the files yourself. One of `list`, `grid`, `none`. Default `'list'`. |
| `label?` | `string` | The headline in the zone. |
| `hint?` | `string` | The line under it. Defaults to a sentence built from the rules. |
| `browseLabel?` | `string \| null` | Text of the browse button. `null` removes it. Default `'Browse files'`. |
| `onadd?` | `(files: UploadFile[]) => void` | Called with the files that were just accepted. |
| `onreject?` | `(rejections: UploadRejection[]) => void` | Called with the files that were turned away, and why. |
| `onchange?` | `(files: UploadFile[]) => void` | Called with the whole list after any change to it. |
| `oncomplete?` | `(files: UploadFile[]) => void` | Called once nothing is left to upload. |
| `class?` | `string` |  |
| `classes?` | `FileUploadClasses` | Per-part Tailwind overrides. `class` still covers the root. |
| `icon?` | `Snippet` | Replaces the fanning sheets. |
| `title?` | `Snippet` | Replaces the headline. |
| `description?` | `Snippet` | Replaces the line under it. |
| `actions?` | `Snippet` | Extra controls beside the browse button. |
| `file?` | `Snippet<[FileUploadRowContext]>` | Replaces the whole row or tile for one file. |

### FunnelChart

`import { FunnelChart } from 'omaris/chart'`

Funnel chart — how many made it through each stage.

| Prop | Type | Notes |
| --- | --- | --- |
| `data` | `T[]` |  |
| `label?` | `Field<T>` | Field naming each stage. Defaults to `row.label`. Default `'label'`. |
| `value?` | `Field<T>` | Field holding each stage's count. Defaults to `row.value`. Default `'value'`. |
| `height?` | `number \| string` | Plot height. A number is px; a string is any CSS length. Default `300`. |
| `gap?` | `number` | Gap between stages, in px. Default `4`. |
| `share?` | `boolean` | Show each stage's share — of the first stage, or of the previous. Default `true`. |
| `drop?` | `boolean` | Measure the share against the previous stage rather than the first. Default `false`. |
| `format?` | `(value: number) => string` | How each count reads. |
| `colors?` | `readonly string[]` | Palette override, cycled across the stages. Default `CHART_COLORS`. |
| `title?` | `string` | Accessible description of what the chart shows. |
| `class?` | `string` |  |
| `empty?` | `Snippet` |  |
| `emptyText?` | `string` |  |
| `error?` | `boolean \| string \| Error` | Something went wrong. Truthy puts the chart into its error state; a string or an `Error` supplies the message. |
| `errorText?` | `string` | The message, when `error` is just `true`. |
| `errorState?` | `Snippet<[{ message: string }]>` | Replaces the whole error state. |
| `onRetry?` | `() => void` | Offers a "Try again" button in the error state. |
| `csv?` | `boolean \| string` | Offer the plotted rows as a CSV download, from a button in the corner. A string names the file. Default `false`. |
| `csvColumns?` | `(string \| { key: string; label?: string; value?: (row: T) => unknown })[]` | Which fields the download writes, in order. Defaults to every field. |

### Gauge

`import { Gauge } from 'omaris/chart'`

Gauge — one number against the range it lives in.

| Prop | Type | Notes |
| --- | --- | --- |
| `value` | `number` |  |
| `min?` | `number` | Bottom of the range. Default `0`. |
| `max?` | `number` | Top of the range. Default `100`. |
| `sweep?` | `number` | Degrees the dial sweeps, centred on the top. Default `270`. |
| `height?` | `number \| string` | Plot height. A number is px; a string is any CSS length. Default `200`. |
| `thickness?` | `number` | Thickness of the dial, in px. Default `14`. |
| `color?` | `string` | Any CSS colour. Ignored where a `thresholds` entry matches. Default `'var(--primary)'`. |
| `thresholds?` | `{ at: number; color: string }[]` | Colour by value: the first entry whose `at` the value is at or under wins, and anything above them all falls back to `color`. |
| `format?` | `(value: number) => string` | How the printed value reads. Defaults to the number itself. |
| `caption?` | `string` | A word under the number — "of quota", "requests/s". |
| `centre?` | `Snippet<[{ value: number }]>` | Replaces the number and caption in the middle. |
| `title?` | `string` | Accessible description of what the gauge shows. |
| `class?` | `string` |  |
| `error?` | `boolean \| string \| Error` | Something went wrong. Truthy puts the chart into its error state; a string or an `Error` supplies the message. |
| `errorText?` | `string` | The message, when `error` is just `true`. |
| `errorState?` | `Snippet<[{ message: string }]>` | Replaces the whole error state. |
| `onRetry?` | `() => void` | Offers a "Try again" button in the error state. |
| `csv?` | `boolean \| string` | Offer the plotted rows as a CSV download, from a button in the corner. A string names the file. Default `false`. |
| `csvColumns?` | `(string \| { key: string; label?: string; value?: (row: T) => unknown })[]` | Which fields the download writes, in order. Defaults to every field. |

### Gauge

`import { Gauge } from 'omaris'`

A radial gauge — one number against the range it lives in.

#### Use it for

- One number against its range: CPU at 72%, quota used, a score out of 100.
  The value is printed in the middle, so nobody has to read an arc.
- A status light with a number in it. Set `tone="warning"` past 60 and
  `destructive` past 80 from the value in the page.
- A scale with zones. `segments` paint a red band from 80 on the track
  without touching the indicator, so reading and scale stay separate.
- A live reading. The arc and the number tween together, so a new value
  glides and counts up. `animate={false}` lands a value at once.

#### Not for

- Progress toward finishing a task, like an upload or a wizard → [Progress](/docs/components/progress).
  A gauge is a reading, not a wait.
- Several progress-shaped values side by side → `RadialBarChart` in
  [Chart](/docs/components/chart), and past about six a `BarChart`.
- A trend over time → `Sparkline` inside the stat, or a `LineChart`, both in
  [Chart](/docs/components/chart).
- A number with no meaningful ceiling, like revenue or a count → a
  `display-sm` [Text](/docs/components/text) in a card. A dial with an
  invented `max` reads as a share that is not there.

#### Do

- Say what the number is under it: `label="CPU"`, or `label="of 2,000"`
  when `format` writes the unit into the readout.
- Pick `sweep` for the space: 270 is the classic dial, 180 fits a
  half-height card, 360 closes it into a ring.
- In a dense table cell, use `size="sm"` with `showValue={false}` and put
  the figure in the next column.
- Prefer this one, from `omaris`, unless the page already imports
  `omaris/chart`. That entry has a `Gauge` too, drawn by layerchart with
  `thresholds` and `caption`, for dials that share the chart palette.

#### Don't

- Colour the indicator from a `segments` band and from `tone` with two
  different meanings. The band is the scale; the tone is the reading.
- Set `ticks` on a `sm` gauge. At that size they are noise.
- Tween a value that updates several times a second. Pass a short `animate`
  or `false`, or the dial never catches up.

#### Pairs with

- [Card](/docs/components/card), [Text](/docs/components/text),
  [Chart](/docs/components/chart), [Progress](/docs/components/progress),
  [Badge](/docs/components/badge)

Parts (`classes`): `root` `svg` `track` `segment` `indicator` `content` `value` `label` `tick`

| Prop | Type | Notes |
| --- | --- | --- |
| `value` | `number` |  |
| `min?` | `number` | Default `0`. |
| `max?` | `number` | Default `100`. |
| `tone?` | `GaugeTone` | One of `primary`, `secondary`, `tertiary`, `destructive`, `success`, `warning`, `info`. Default `'primary'`. |
| `size?` | `GaugeSize` | One of `sm`, `md`, `lg`. Default `'md'`. |
| `sweep?` | `number` | Degrees of arc. 270 is the classic dial; 360 closes it into a ring. Default `270`. |
| `thickness?` | `number` | Stroke width as a share of the radius. Default `0.22`. |
| `rounded?` | `boolean` | Round the ends of both arcs. Default `true`. |
| `segments?` | `GaugeSegment[]` | Zones on the track — thresholds, safe ranges, a red line. |
| `ticks?` | `number` | Evenly spaced ticks around the scale. `0` draws none. Default `0`. |
| `label?` | `string` | Under the number — "CPU", "of 2,000". |
| `format?` | `(value: number) => string` | Formats the number in the middle. Defaults to a rounded integer. |
| `showValue?` | `boolean` | Hide the centred readout — for a gauge in a dense table cell. Default `true`. |
| `animate?` | `boolean \| number` | Glide to a new value rather than jump. `true` takes 700 ms on the emphasized curve, a number sets the duration in ms, `false` is instant. Reduced motion is always instant. Default `true`. |
| `children?` | `Snippet` | Replaces the whole centre stack. |
| `name?` | `string` | Accessible name. Falls back to `label`, and one of the two is required: a meter with a value and no name reaches a screen reader as "64 percent" of nothing. Give it one whenever the centre stack is replaced by `children`, which is the case where `label` is gone. |
| `class?` | `string` |  |
| `classes?` | `GaugeClasses` |  |
| `height?` | `number \| string` | Plot height. A number is px; a string is any CSS length. |
| `color?` | `string` | Any CSS colour. Ignored where a `thresholds` entry matches. |
| `thresholds?` | `{ at: number; color: string }[]` | Colour by value: the first entry whose `at` the value is at or under wins, and anything above them all falls back to `color`. |
| `caption?` | `string` | A word under the number — "of quota", "requests/s". |
| `centre?` | `Snippet<[{ value: number }]>` | Replaces the number and caption in the middle. |
| `title?` | `string` | Accessible description of what the gauge shows. |
| `error?` | `boolean \| string \| Error` | Something went wrong. Truthy puts the chart into its error state; a string or an `Error` supplies the message. |
| `errorText?` | `string` | The message, when `error` is just `true`. |
| `errorState?` | `Snippet<[{ message: string }]>` | Replaces the whole error state. |
| `onRetry?` | `() => void` | Offers a "Try again" button in the error state. |
| `csv?` | `boolean \| string` | Offer the plotted rows as a CSV download, from a button in the corner. A string names the file. |
| `csvColumns?` | `(string \| { key: string; label?: string; value?: (row: T) => unknown })[]` | Which fields the download writes, in order. Defaults to every field. |

### IconButton

`import { IconButton } from 'omaris'`

MD3 icon button. Same tone system as `Button`, but its own geometry: height comes from `size`, width from `width` as a ratio of that height (MD3's narrow / default / wide, which are ~0.8× / 1× / 1.3×).

#### Use it for

- An action whose icon everyone reads: close, search, more, edit, delete. In
  a [Top App Bar](/docs/components/top-app-bar), a toolbar, a table row or a
  card corner.
- An on/off that is an action, not a setting: favourite, bookmark, mute,
  play/pause. Use `toggle` with `bind:pressed`, and `selectedIcon` so the
  outline fills in when on.
- A row of them in a `connected` [Button Group](/docs/components/button-group),
  like a text-editor toolbar.
- MD3 Expressive rhythm: one `width="wide"` `shape="square"` `filled` button
  anchoring a row of `standard` ones.

#### Not for

- Anything without a universal icon → a [Button](/docs/components/button)
  with a label. A [Tooltip](/docs/components/tooltip) names an icon; it does
  not make it obvious.
- The screen's one floating action → [FAB](/docs/components/fab).
- An on/off that saves a preference → [Switch](/docs/components/switch). A
  pressed icon button means "doing this now", not "this is how it is set".
- One of two to five options → [Segmented Button](/docs/components/segmented-button).
- A set of destinations → [Navigation Bar](/docs/components/navigation-bar).
  `href` on a single icon button, like a back arrow, is fine.

#### Do

- Pass `aria-label` with the verb in it: "Delete row", not "Trash". The prop
  is required; the type refuses without it.
- Wrap it in a [Tooltip](/docs/components/tooltip) with the same words, so
  pointer users get the name too.
- Keep `standard` (no fill until touched) as the default. Use `filled` or
  `tonal` for the one action in a row that matters, `outlined` when it needs
  a boundary on a busy surface.
- Stay at `size="sm"` (40dp) where a thumb lands. `xs` (32dp) only in a dense
  table row; `md` and up for a hero control.

#### Don't

- Put text inside. An icon button is a square; if it needs a label it is a
  [Button](/docs/components/button).
- Set `toggle` on something that opens a [Menu](/docs/components/menu) or
  navigates. A toggle reports `aria-pressed`; a trigger does not stay pressed.
- Make every button in a row `filled`. The emphasis is lost.

#### Pairs with

- [Tooltip](/docs/components/tooltip), [Button Group](/docs/components/button-group),
  [Top App Bar](/docs/components/top-app-bar), [Badge](/docs/components/badge),
  [Menu](/docs/components/menu)

| Prop | Type | Notes |
| --- | --- | --- |
| `variant?` | `IconButtonVariant` | One of `filled`, `tonal`, `elevated`, `outlined`, `standard`. Default `'standard'`. |
| `tone?` | `IconButtonTone` | One of `primary`, `secondary`, `tertiary`, `destructive`, `success`, `warning`, `info`. Default `'primary'`. |
| `size?` | `IconButtonSize` | One of `xs`, `sm`, `md`, `lg`, `xl`. Default `'sm'`. |
| `width?` | `IconButtonWidth` | Horizontal weight relative to the height — MD3's three densities. One of `narrow`, `default`, `wide`. Default `'default'`. |
| `shape?` | `IconButtonShape` | One of `round`, `square`. Default `'round'`. |
| `ripple?` | `boolean` | Default `true`. |
| `confetti?` | `boolean \| ConfettiOptions` | Confetti on press. `true` for the default burst, or any `ConfettiOptions` — `confetti={{ preset: 'fireworks' }}`. Default `false`. |
| `toggle?` | `boolean` | Turns the button into a two-state toggle driven by `pressed`. Ignored when `href` is set — a link has no pressed state. Default `false`. |
| `pressed?` | `boolean` | Selected state of a toggle button. Bindable. Default `false`. |
| `selectedIcon?` | `Snippet` | Icon shown while `pressed`. Lets a toggle swap outline for solid, the way Material's own icons do. |
| `aria-label` | `string` | Required — an icon alone carries no accessible name. |
| `class?` | `string` |  |
| `children?` | `Snippet` |  |
| `icon?` | `boolean` | Square, label-less button. Requires an `aria-label`. |
| `loading?` | `boolean` | Grows a spinner in at the start of the button and blocks interaction. The label stays put; only an `icon` button swaps its icon out. |

### ImageCropper

`import { ImageCropper } from 'omaris'`

Crop an image by moving the image, not the box.

#### Use it for

- An avatar: `aspect={1}`, `shape="circle"`, and `toBlob()` on save. The
  output is square; the circle is only the preview.
- A cover or banner at a fixed ratio, or `ratios` when one picture has to fit
  several places.
- Straightening a photo: `controls={['zoom', 'straighten', 'reset']}` adds a
  fine-angle slider. The picture still cannot show a gap.
- A crop the person shapes by hand: `aspect="free"` with `resizable`.

#### Not for

- Looking at a picture, zooming in, swiping to the next → [Image Viewer](/docs/components/image-viewer).
- Choosing the file. It takes a `src`; your own file input or drop zone hands
  it `URL.createObjectURL(file)`.
- Filters, drawing, annotations → nothing here. It only crops.
- The thumbnail once the crop is done → [Avatar](/docs/components/avatar).

#### Do

- `bind:this` and call `toBlob` or `toFile` when the person confirms. The
  export replays the on-screen transform at the size you name.
- Name the output size the server wants: `toBlob({ width: 512 })`. Do not
  take the crop at the source's own pixel size.
- Set `crossorigin="anonymous"` on a remote image, or the canvas is tainted
  and the export throws.
- Give it `alt`, and put "Choose a different photo" in `children`, over the
  stage.

#### Don't

- Turn `controls` off without binding `zoom` to a control of your own. Pinch
  and wheel still work, but the slider is the keyboard's way in.
- Use it when the crop must show blank space around a small image. It keeps
  the window full by design.
- Size the stage with a class on the root. `height` is a property;
  `classes.stage` replaces it.

#### Pairs with

- [Image Viewer](/docs/components/image-viewer), [Avatar](/docs/components/avatar),
  [Dialog](/docs/components/dialog), [Sheet](/docs/components/sheet),
  [Slider](/docs/components/slider), [Button](/docs/components/button)

Parts (`classes`): `root` `stage` `image` `window` `grid` `gridLine` `handle` `ratios` `ratio` `controls` `slider` `angle` `angleValue` `button` `loading`

| Prop | Type | Notes |
| --- | --- | --- |
| `src` | `string` | Image URL, object URL or data URL. |
| `alt?` | `string` | Describes the picture, for anyone who cannot see it. Default `''`. |
| `aspect?` | `ImageCropperAspect` | Width ÷ height of the crop window. `1` is a square, `'free'` is any. Bindable. Default `1`. |
| `shape?` | `ImageCropperShape` | One of `rect`, `circle`. Default `'rect'`. |
| `zoom?` | `number` | Zoom, where `1` is "just covers the window". Bindable. Default `1`. |
| `rotation?` | `number` | Rotation in degrees — any angle, not only quarter turns. Bindable. Default `0`. |
| `flipX?` | `boolean` | Mirror the picture left to right. Bindable. Default `false`. |
| `flipY?` | `boolean` | Mirror the picture top to bottom. Bindable. Default `false`. |
| `maxZoom?` | `number` | Default `5`. |
| `grid?` | `boolean` | Draw the rule-of-thirds grid while the crop is being changed. Default `true`. |
| `controls?` | `boolean \| ImageCropperControl[]` | The controls under the stage: `true` for the usual set, `false` for none, or the list you want — `['zoom', 'straighten', 'reset']`. Default `true`. |
| `ratios?` | `boolean \| ImageCropperRatio[]` | A row of aspect presets over the controls. `true` for the built-in set, or your own — `[{ label: 'Cover', value: 3 }]`. Default `false`. |
| `resizable?` | `boolean` | Put handles on the window so its size can be dragged. Default `false`. |
| `inset?` | `number` | Widest the crop window may be drawn, as a share of the stage. Leaves room around it so there is somewhere to drag from, and caps how far the handles can be pulled. Default `0.86`. |
| `crossorigin?` | `'anonymous' \| 'use-credentials'` | Set for a cross-origin image that has to be exported. Without it the canvas is tainted and `toBlob` throws. |
| `height?` | `number \| string` | Height of the stage. A number is px, a string any CSS length — a property rather than a class, so `classes.stage` can replace it. Default `'20rem'`. |
| `onchange?` | `(crop: CropRect) => void` | Fires whenever the crop settles, with the rectangle in source pixels. |
| `children?` | `Snippet` | Extra content over the stage — a "choose a different photo" button. |
| `class?` | `string` |  |
| `classes?` | `ImageCropperClasses` |  |

### ImageViewer

`import { ImageViewer } from 'omaris'`

Image viewer — tap a picture and it lifts off the page into a full-screen, zoomable, swipeable lightbox, then settles back where it came from. The feel of react-photo-view, for Svelte.

#### Use it for

- A gallery where a thumbnail opens full-screen. Wrap the grid in
  `ImageViewer` and mark each picture with `ImageViewerItem`. It lifts off
  that spot and settles back on close.
- One picture in a card, a chat bubble or a ticket. A single
  `ImageViewerItem` is enough.
- Opening from something that is not a thumbnail: a "View all 12 photos"
  button, a keyboard shortcut, a route. Pass `images` and drive `open` and
  `index` yourself.
- Actions on the picture (download, delete, set as cover) in the `actions`
  snippet, before the close button.

#### Not for

- Flicking through pictures on the page → [Carousel](/docs/components/carousel).
  Wrap the carousel's items in `ImageViewerItem` and you have both.
- A wall of thumbnails → [Masonry](/docs/components/masonry), with an
  `ImageViewer` around it.
- Cropping or rotating for keeps → [Image Cropper](/docs/components/image-cropper).
  `R` rotates the view here; nothing is saved.
- Video → [Video Player](/docs/components/video-player).
- Any modal that is not a picture → [Dialog](/docs/components/dialog).

#### Do

- Give `ImageViewerItem` the full-size `src` and put the thumbnail `<img>`
  inside it. The page loads small; the viewer loads big.
- Use the same `alt` on both. The viewer announces it as the picture opens.
- Set `loop` for a small set you step through with the arrow keys or
  buttons. Swiping never wraps either way: it stops at the first and last
  picture with a rubber band, as a phone's gallery does. Leave `loop` off
  when the order means something, like before and after.
- Give `width` and `height` when you know them. The picture then opens at
  its real shape before the full image has loaded.
- Keep `dismissible` on. A pull down, a pinch in and a tap on the black are
  how a phone closes it.

#### Don't

- Put a link or a button inside `ImageViewerItem`. It is already a button.
- Hang anything of your own on a tap on the picture. On a phone a tap shows
  and hides the controls and a double-tap zooms; a mouse click zooms at the
  pointer.
- Turn `toolbar` and `arrows` off together on a desktop. A mouse then has no
  way to move on or out.
- Raise `maxScale` for small originals. Five times a 400px thumbnail is
  pixels.
- Give a decorative thumbnail an `ImageViewerItem`. A full-screen 40px icon
  is a bad surprise.

#### Pairs with

- [Masonry](/docs/components/masonry), [Carousel](/docs/components/carousel),
  [Card](/docs/components/card), [Avatar](/docs/components/avatar),
  [Icon Button](/docs/components/icon-button)

| Prop | Type | Notes |
| --- | --- | --- |
| `images?` | `ImageViewerImage[]` | Images to show, when not using `ImageViewerItem`s. |
| `open?` | `boolean` | Bindable. Default `false`. |
| `index?` | `number` | Which image is showing. Bindable. Default `0`. |
| `loop?` | `boolean` | The arrow keys and buttons wrap from the last picture to the first. Swiping never does — it stops at either end with a rubber band, the way a phone's gallery does. Default `false`. |
| `maxScale?` | `number` | Furthest you can zoom in. Default `5`. |
| `toolbar?` | `boolean` | Show the top bar: counter, zoom, rotate, close. Default `true`. |
| `arrows?` | `boolean` | Show the prev/next arrows on wide screens. Default `true`. |
| `dismissible?` | `boolean` | Allow the pull-down and the scrim tap to close it. Default `true`. |
| `actions?` | `Snippet<[{ image: ImageViewerImage; index: number }]>` | Extra toolbar actions, rendered before the close button. |
| `onchange?` | `(index: number) => void` |  |
| `onclose?` | `() => void` |  |
| `children?` | `Snippet` |  |

### ImageViewerItem

`import { ImageViewerItem } from 'omaris'`

Marks a thumbnail as openable in the surrounding `ImageViewer`.

| Prop | Type | Notes |
| --- | --- | --- |
| `class?` | `string` |  |
| `children?` | `Snippet` |  |

### IndexScrubber

`import { IndexScrubber } from 'omaris'`

The A-Z rail down the side of a long list — the one every phone's contacts app has, and almost nothing on the web does.

#### Use it for

- A long alphabetical list on a touch screen: contacts, cities, products,
  tags, members. The rail turns a thousand rows into one thumb movement.
- Any list already split into sections with short headings: a letter, a
  date, a country code, a rating.
- A list people aim at rather than scroll through. A drag aims; a tap is a
  destination. The component treats them differently.
- A directory in a panel or a sheet as well as a full page. It finds the
  scroller it is inside instead of assuming the window.
- A steady rail across refreshes. `groupByInitial(…, { fill: true })` keeps
  every letter, greyed where empty, so the letters never move under the
  thumb.

#### Not for

- A list that is not sorted, or sorted by relevance or a manual order →
  nothing, or [Pagination](/docs/components/pagination).
- Finding one known item → [Search Bar](/docs/components/search-bar) or
  [Combobox](/docs/components/combobox). Typing three letters beats aiming.
- Fewer than about fifty rows → plain scrolling, or
  [Tabs](/docs/components/tabs) if there really are sections.
- Moving between sections of one page → [Table of Contents](/docs/components/toc).
  That rail is for reading position; this one is for a data set.
- A desktop-only screen → a sticky header per section, or
  [Table](/docs/components/table) with a sort.

#### Do

- Build the sections with `groupByInitial` and render the headings with the
  `id`s it produced. The scrubber finds them by id.
- Give the rail height with room either side of the list:
  `class="absolute inset-y-1 end-0.5"` over a `relative` container.
- Set `offset` to the height of a sticky header, or every jump lands with the
  first row hidden behind it.
- Keep labels to one character; three turn the rail into a column of tiny
  words. Use `magnify={0}` for a quiet rail; drag, callout and condensing
  still work.
- Leave `observe` on so the rail follows an ordinary scroll too and the
  active letter is always right.

#### Don't

- Put it over content it hides. Give the list `pe-6` so nothing sits under
  the rail.
- Expect thirty-odd sections all to be drawn. It condenses on purpose; every
  letter stays reachable by dragging.
- Wire `onselect` to your own scrolling and leave `scroll` on. Pick one, or
  the list scrolls twice.
- Use it with section ids that are not on the page. It reports and does not
  scroll, which looks broken.
- Turn haptics on globally just for this. The shared store is off by default
  and this component follows it.

#### Pairs with

- [List](/docs/components/list), [Avatar](/docs/components/avatar),
  [Search Bar](/docs/components/search-bar), [Sheet](/docs/components/sheet),
  [Shape](/docs/components/shape),
  [Pull to Refresh](/docs/components/pull-to-refresh)

Parts (`classes`): `root` `rail` `track` `row` `dot` `bubble`

| Prop | Type | Notes |
| --- | --- | --- |
| `sections` | `IndexSection[]` | The stops, in the order the list has them. `groupByInitial` builds these. |
| `active?` | `string` | The section currently in view. Bindable. |
| `onselect?` | `(key: string, section: IndexSection) => void` | Called on every change, dragging included. |
| `container?` | `HTMLElement \| string \| null` | The scroller. A selector, an element, or left out — in which case the nearest scrollable ancestor of the target section is used, falling back to the page. Default `null`. |
| `offset?` | `number` | Distance from the top of the scroller that counts as "at" a section, in px. Default `0`. |
| `scroll?` | `boolean` | Scroll to the section. Off leaves the scrolling entirely to `onselect`. Default `true`. |
| `observe?` | `boolean` | Follow the scroller and keep `active` current as the user scrolls normally. Default `true`. |
| `side?` | `'end' \| 'start'` | Which edge the rail is pinned to. It only decides which way the letters bulge. One of `end`, `start`. Default `'end'`. |
| `magnify?` | `number` | The magnification under the finger. `0` turns it off and leaves a plain rail. Default `0.85`. |
| `spread?` | `number` | How far the magnification reaches, in px. Wider is softer. Default `46`. |
| `bulge?` | `number` | How far the swollen letters lean toward the content, in px. Default `14`. |
| `bubble?` | `boolean` | The callout beside the finger. Default `true`. |
| `bubbleShape?` | `ShapeName` | Its outline. Any of the 36 in the shape library. Default `'cookie-9'`. |
| `bubbleSize?` | `number` | Its size, in px. Default `60`. |
| `haptics?` | `boolean` | A tick as each new letter comes under the finger. Follows the shared store. Default `true`. |
| `rowHeight?` | `number` | Height one letter needs, in px — what decides when the rail condenses. Default `13`. |
| `label?` | `string` | Accessible name for the rail. Default `'Section index'`. |
| `callout?` | `Snippet<[IndexSection]>` | Replace the callout. It is handed the section under the finger. |
| `class?` | `string` |  |
| `classes?` | `IndexScrubberClasses` | Per-part Tailwind overrides. `class` still covers the root. |

### InlineEdit

`import { InlineEdit } from 'omaris'`

Click the text, it becomes a field. Nothing on the page moves.

#### Use it for

- Renaming the thing on screen: a board, a document, a column, a file.
  Opening a dialog to change six characters is too much.
- A field in a detail panel or card that is read far more often than it is
  changed: a title, an owner, a note, a due-date label.
- A cell in a light table of editable values. Use `align="end"` and
  `pencil={false}`.
- A description. `multiline` grows the box by the line as it is typed.

#### Not for

- A form → [Text Field](/docs/components/input) and a submit button.
  Click-to-edit fields hide that there is anything to fill in.
- Something required before anything else works. An empty inline edit reads
  as "nothing here", not "required".
- A value with a picker behind it, like a date, a currency or a country →
  [Picker](/docs/components/picker), [Select](/docs/components/select) or
  [Price Input](/docs/components/price-input) in a small form.
- Text longer than a couple of lines → [Textarea](/docs/components/textarea)
  or [Rich Text Editor](/docs/components/rich-text-editor).

#### Do

- Give it a `label`. It is the accessible name in both states, read as
  "Board name: Untitled board", and there is no visible label to fall back
  on.
- Return a promise from `onsave`. The field shows a spinner, writes `value`
  once it resolves, and stays open with the message if it rejects.
- Use `validate` for the rules. The message floats under the box and never
  pushes the page around.
- Set `placeholder` to what should be there: "Add a description". An empty
  box does not look editable. Turn `actions` on for touch, where there is no
  obvious way to leave the field; leave them off on desktop.
- Put the type on the component (`class="text-xl font-semibold"`), not on the
  parts. Everything inside inherits it, so both states stay the same size.

#### Don't

- Swap a `<span>` for an `<input>` yourself. The border, padding and line
  height all change, and the rows below jump twice per edit.
- Put one inside a row that also handles clicks. The edit and the row's
  action fight over the same press.
- Save on every keystroke. `onsave` fires once, on Enter or on leaving.
- Use `trigger="manual"` without giving people something to press.

#### Pairs with

- [Text Field](/docs/components/input), [Textarea](/docs/components/textarea),
  [Table](/docs/components/table), [Card](/docs/components/card),
  [Kanban](/docs/components/kanban)

Parts (`classes`): `root` `sizer` `view` `control` `pencil` `placeholder` `error` `actions` `action` `busy`

| Prop | Type | Notes |
| --- | --- | --- |
| `value?` | `string` | The text. Bindable, and only written once a save succeeds. Default `''`. Bindable. |
| `editing?` | `boolean` | Whether the field is open. Bindable — the way to open it from a button. Default `false`. Bindable. |
| `size?` | `InlineEditSize` | One of `sm`, `md`, `lg`. Default `'md'`. |
| `align?` | `InlineEditAlign` | One of `start`, `center`, `end`. Default `'start'`. |
| `multiline?` | `boolean` | A `textarea` that grows by the line instead of an input. Default `false`. |
| `block?` | `boolean` | Fill the container rather than hugging the text. Default `false`. |
| `trigger?` | `InlineEditTrigger` | What opens the field. `manual` leaves it to `bind:editing`. Default `'click'`. |
| `submitOn?` | `InlineEditSubmit` | When the change is kept. Escape always cancels. Default `'both'`. |
| `pencil?` | `boolean` | Show the pencil on hover. Its space is reserved either way. Default `true`. |
| `actions?` | `boolean` | Float a confirm/cancel pair under the field — worth it on touch. Default `false`. |
| `selectOnEdit?` | `boolean` | Select the whole value when the field opens. Default `true`. |
| `placeholder?` | `string` | Shown, greyed, when the value is empty. Default `'Empty'`. |
| `label?` | `string` | Accessible name — what this text *is*. Required in practice. |
| `disabled?` | `boolean` | Default `false`. |
| `readonly?` | `boolean` | Reads, never edits. The hover hint and the pencil go away. Default `false`. |
| `maxlength?` | `number` |  |
| `validate?` | `(value: string) => string \| null` | Checked before saving. Return a message to refuse the change and keep the field open; return `null` to let it through. |
| `onsave?` | `(value: string) => void \| Promise<unknown>` | Called with the new text. Return a promise and the field waits on it, showing a spinner — a rejection keeps the field open with the message. |
| `oncancel?` | `() => void` | Called when the edit is abandoned. |
| `view?` | `Snippet<[string]>` | Replaces the reading view — a badge, an avatar beside the name. |
| `class?` | `string` |  |
| `classes?` | `InlineEditClasses` | Per-part Tailwind overrides. `class` still covers the root. |
| `ref?` | `HTMLInputElement \| HTMLTextAreaElement \| null` | Default `null`. Bindable. |

### Input

`import { Input } from 'omaris'`

Text field.

#### Use it for

- One line of text a form collects: a name, an email, a URL, a filter box.
  `type` and `format` decide what the keyboard shows and what the field
  accepts.
- A number typed by hand: `format="decimal"` or `integer` with `suffix="kg"`,
  not `type="number"` and its spinner. Eastern-Arabic digits type as digits.
- A password. The eye toggle is on by default. `clearable` adds the × a
  search or filter field wants.
- A value with a fixed part: `prefix="https://"` or `suffix=".com"` is drawn
  beside the value and never ends up inside it.

#### Not for

- More than a line → [Textarea](/docs/components/textarea).
- Bold, a list, a link → [Rich Text Editor](/docs/components/rich-text-editor).
  Source with syntax → [Code Editor](/docs/components/code-editor).
- A value chosen from a list → [Select](/docs/components/select). A list you
  search → [Combobox](/docs/components/combobox).
- Money → [Price Input](/docs/components/price-input). A phone number with a
  country → [Phone Input](/docs/components/phone-input). `format="phone"` is
  an Iraqi mobile number only.
- A label for something that is not an Input → [Label](/docs/components/label).

#### Do

- Say what is wrong in `supportingText` and set `invalid`. The helper line
  becomes the error line, where the person is already looking.
- Pick the variant by the surface: `outline` on the page background, `filled`
  inside a card, `ghost` inside another control such as a table cell or a
  toolbar.
- Set `format` and the keyboard follows. `inputmode`, `autocapitalize` and
  `spellcheck` come with it, so a slug field never autocorrects.
- Use `counter` only with a `maxlength`, and only where the limit is real,
  like a headline shown elsewhere at a fixed width.

#### Don't

- Use the placeholder as the label. The label stays above the field; the
  placeholder vanishes on the first keystroke.
- Type the unit into the value. `suffix="kg"` keeps the number a number.
- Use `size="lg"` in a dashboard form. It is for a sign-in screen. `sm` is
  for a dense filter row.
- Disable a field to show a value that cannot change. `readonly` keeps it
  selectable and copyable; `disabled` greys it out and skips it in Tab order.

#### Pairs with

- [Label](/docs/components/label), [Textarea](/docs/components/textarea),
  [Select](/docs/components/select), [Combobox](/docs/components/combobox),
  [Button](/docs/components/button)

Parts (`classes`): `root` `field` `control` `label` `adornment` `affix` `action` `support` `counter`

| Prop | Type | Notes |
| --- | --- | --- |
| `variant?` | `InputVariant` | One of `outline`, `filled`, `ghost`. Default `'outline'`. |
| `size?` | `InputSize` | One of `sm`, `default`, `lg`. Default `'default'`. |
| `type?` | `HTMLInputTypeAttribute` | Default `'text'`. |
| `format?` | `InputFormatName \| InputFormat` | What the field accepts. A built-in name (`decimal`, `slug`, `phone`, …) or your own `InputFormat`. Rejected characters never make it in, and the format's keyboard hints come along with it. |
| `label?` | `string` | Label above the field. Wired to the control, so clicking focuses it. |
| `required?` | `boolean` | Marks the label required and sets `required` on the control. Inside a `Field`, defaults to the field's. |
| `supportingText?` | `string` | Helper line under the field. Turns into the error text when invalid. |
| `invalid?` | `boolean` | Marks the field invalid and wires up aria-invalid. Inside a `Field`, defaults to the field's. |
| `value?` | `string \| number \| null` | Bindable. |
| `revealable?` | `boolean` | Show the eye toggle on a password field. On by default — that's the behaviour every password field wants and nobody wants to rebuild. Default `true`. |
| `revealed?` | `boolean` | Starts a password field revealed. Bindable. Default `false`. |
| `clearable?` | `boolean` | Adds a clear (×) button once the field has a value. Default `false`. |
| `loading?` | `boolean` | Swaps the trailing controls for a spinner and blocks interaction. Default `false`. |
| `counter?` | `boolean` | Live `n/maxlength` count beside the supporting text. Default `false`. |
| `prefix?` | `string` | Flat text glued to the start of the value — "https://", "@". |
| `suffix?` | `string` | Flat text glued to the end of the value — "kg", ".com". |
| `start?` | `Snippet` | Leading icon. |
| `end?` | `Snippet` | Trailing icon or control, after the built-in actions. |
| `supporting?` | `Snippet` | Richer supporting text — a link, a strength meter. |
| `onclear?` | `() => void` | Fires after the clear button empties the field. |
| `class?` | `string` |  |
| `classes?` | `InputClasses` | Per-part Tailwind overrides. `class` still covers the root. |
| `ref?` | `HTMLInputElement \| null` | Default `null`. Bindable. |

### JsonViewer

`import { JsonViewer } from 'omaris'`

A JSON tree you can actually read: collapsible, searchable, and coloured with the same `--code-*` tokens as `CodeBlock`, so a payload in a docs page and a payload in a debug panel look like the same language.

#### Use it for

- A payload someone will explore: an API response in a debug panel, a
  webhook's details, a row's raw record. `depth={2}` opens the top, and a
  collapsed node still says what is inside: `{ id, name, +3 }`, `[ 12 items ]`.
- Finding one field in a large document. `search` keeps the matches and the
  path down to them, so a hit five levels deep arrives with its ancestors.
- Grabbing a piece. `copy` puts a copy button on every node and a copy-all in
  the header.
- A string that might be JSON. It is parsed when it is, and shown as a string
  when it is not.

#### Not for

- A short, fixed example nobody expands → [Code Block](/docs/components/code-block)
  with `lang="json"`. It copies and highlights with the same tokens.
- Editing the document → [Code Editor](/docs/components/code-editor) with
  `lang="json"`.
- Structured log lines → [Log Viewer](/docs/components/log-viewer). A row's
  `details` object already opens as this tree.
- Data with a fixed shape people compare across rows →
  [Table](/docs/components/table).

#### Do

- Name the root with `name`, like `response` or `payload`, so the first row
  is not a bare brace.
- Start shallow: `depth={1}` for a document you do not know, `Infinity` only
  for something small. The previews make skipping a node possible.
- Give it a `height` when it sits in a panel and let the tree scroll inside.
  Use `height="auto"` when the card around it scrolls.
- Use `variant="ghost"` inside a bordered surface. The three variants match
  [Code Block](/docs/components/code-block).

#### Don't

- Stringify first. Pass the object; a pre-stringified value loses the types,
  and the colours are the types.
- Turn `search` on for a ten-key object. The field is taller than the tree.
- Set the height from a class alone. `height` is a property, so a `max-h-*`
  on `classes.viewport` only works once `height="auto"` has cleared it.

#### Pairs with

- [Code Block](/docs/components/code-block),
  [Log Viewer](/docs/components/log-viewer), [Sheet](/docs/components/sheet),
  [Accordion](/docs/components/accordion), [Card](/docs/components/card)

Parts (`classes`): `root` `header` `search` `action` `viewport` `row` `toggle` `spacer` `key` `punctuation` `value` `preview` `count` `copy` `empty`

| Prop | Type | Notes |
| --- | --- | --- |
| `value` | `unknown` | Any value. A string that parses as JSON is parsed; one that doesn't is shown as a string. |
| `name?` | `string` | Name for the root node. Default `'$'`. |
| `variant?` | `JsonViewerVariant` | One of `outlined`, `filled`, `ghost`. Default `'outlined'`. |
| `size?` | `JsonViewerSize` | One of `sm`, `md`. Default `'md'`. |
| `depth?` | `number` | How many levels start open. `Infinity` opens everything. Default `1`. |
| `search?` | `boolean` | Show the filter box. Default `false`. |
| `copy?` | `boolean` | Per-node copy buttons, and a copy-all in the header. Default `true`. |
| `maxStringLength?` | `number` | Longest string shown before it is elided. Default `120`. |
| `height?` | `number \| string` | Height of the scroll area. A number is px, a string any CSS length — a property rather than a class, so `classes.viewport` can replace it. Default `'20rem'`. |
| `indent?` | `number` | Indent per level, in px. Default `14`. |
| `class?` | `string` |  |
| `classes?` | `JsonViewerClasses` |  |

### Kanban

`import { Kanban } from 'omaris'`

A board of columns you drag cards between.

#### Use it for

- Work that moves through stages by hand: tickets, leads, applications. One
  column per stage, `bind:columns`, and `onmove` to save where a card went.
- Stages with rules. `limit` turns a column's count amber past its cap and
  refuses cards from elsewhere while over it. `locked` refuses every drop and
  shows a padlock, for a "Done" that is closed.
- Cards built from the library's own pieces: a `Badge` per label, an `Avatar`
  for the assignee, a due-date `Chip`, a `tone` per column, and a `Menu` at
  the end of each header through `columnActions`.
- A board used from a phone and a keyboard. A finger holds, then drags.
  `Space` picks a card up, arrows move it, `Escape` puts it back, and a live
  region reads every step out.

#### Not for

- Rows people sort, filter and page → [Table](/docs/components/table). A board
  moves a few dozen things; it does not read a thousand.
- Items with a status word and no stages to move between →
  [List](/docs/components/list) with a [Badge](/docs/components/badge).
- A grid where the columns mean nothing → a [Card](/docs/components/card)
  grid or [Masonry](/docs/components/masonry).

#### Do

- Give `key` when items have no `id`. Identity keeps a card the same element
  while it slides and is what the keyboard drag holds on to.
- Save in `onmove`, not in an effect on `columns`. The array is rewritten
  once, on release, so a cancelled drag never reaches the server.
- Pass `label` so a keyboard drag announces "Fix login bug" rather than
  "card".
- Set `height` from the prop. It is a property, so `height="auto"` plus an
  `h-*` on `classes.root` replaces it. Use `density="compact"` when the
  columns are long.
- Handle `onadd` when `addable` is on. The row only asks; it does not create.

#### Don't

- Use native drag and drop or a `draggable` attribute inside a card. The
  board tracks the pointer itself, and a native drag fights it.
- Mutate `columns` from a card's own button while a drag is in flight. Wait
  for `onmove`.
- Put more than about six columns on a phone. The board scrolls sideways, but
  dragging toward an off-screen column is dragging toward an edge.

#### Pairs with

- [Card](/docs/components/card), [Badge](/docs/components/badge),
  [Avatar](/docs/components/avatar), [Chip](/docs/components/chip),
  [Menu](/docs/components/menu)

Parts (`classes`): `root` `column` `header` `dot` `title` `count` `over` `lock` `list` `cell` `card` `placeholder` `ghost` `empty` `add` `status`

| Prop | Type | Notes |
| --- | --- | --- |
| `columns` | `KanbanColumn<T>[]` | The board. Bindable — a drop rewrites it. Bindable. |
| `card` | `Snippet<[T, KanbanCardContext<T>]>` | How to draw one card. |
| `header?` | `Snippet<[KanbanColumn<T>]>` | Replaces a column's whole header row — dot, title, count and `columnActions`. |
| `columnActions?` | `Snippet<[KanbanColumn<T>]>` | Rendered at the end of the default header — a menu, usually. |
| `key?` | `(item: T, index: number) => string \| number` | Identity, which is what keeps a card the same element while it slides. Defaults to the item's `id`, then its index. |
| `label?` | `(item: T) => string` | Names a card for assistive tech during a keyboard drag. |
| `density?` | `KanbanDensity` | One of `comfortable`, `compact`. Default `'comfortable'`. |
| `columnWidth?` | `number \| string` | Column width. A number is px, a string any CSS length. Default `272`. |
| `height?` | `number \| string` | Board height. A number is px, a string any CSS length — a property rather than a class, so `classes.root` can replace it. Default `'28rem'`. |
| `emptyText?` | `string` | Shown in an empty column. Default `'Nothing here'`. |
| `addable?` | `boolean` | Show the "add a card" row under each column. Default `false`. |
| `addLabel?` | `string` | Default `'Add a card'`. |
| `disabled?` | `boolean` | Default `false`. |
| `onmove?` | `(move: KanbanMove<T>) => void` |  |
| `onadd?` | `(columnId: string) => void` |  |
| `class?` | `string` |  |
| `classes?` | `KanbanClasses` |  |

### Kbd

`import { Kbd } from 'omaris'`

A key cap — the `<kbd>` a shortcut is drawn with.

#### Use it for

- A shortcut beside the thing it triggers — a menu row, a
  [Command Palette](/docs/components/command-palette) result, a button's
  tooltip: `<Kbd keys="mod+k" size="sm" />`.
- A shortcut sheet or a help page, one row per action, with `keys` so every
  reader sees their own keyboard.
- A key named in running text — "press <kbd>Esc</kbd> to close" — as a single
  cap with children.
- The string form, `formatShortcut('mod+k')`, where a cap cannot go: a
  `title`, a tooltip, an `aria-keyshortcuts` attribute (`{ aria: true }`).

#### Not for

- A status or a count → [Badge](/docs/components/badge). A cap reads as a key,
  and a key reads as something to press.
- A code identifier or a value to copy → [Code Block](/docs/components/code-block),
  or `<Text font="mono">` inline.
- A button that performs the shortcut → [Button](/docs/components/button) with
  the `Kbd` inside it; a cap is not pressable.

#### Do

- Write `mod` rather than `cmd` or `ctrl` for the primary modifier. It is ⌘ on
  Apple devices and Ctrl everywhere else, and it is what `matchShortcut` binds.
- Use `size="sm"` inside a menu row, a list item or a chip, and `variant="flat"`
  where the row already has its own surface.
- Match the listener to the label: bind with `matchShortcut(event, 'mod+k')` so
  the key that is drawn is the key that works, on every keyboard layout.
- Pin `platform` only when comparing keyboards side by side; left on `auto`,
  the reader's own keyboard is the one drawn.

#### Don't

- Hand-write `⌘K` in a label. A Windows reader sees a key they do not have,
  and a screen reader skips the symbol entirely.
- Put a shortcut on a phone-only screen. There is no keyboard; the cap is
  noise.
- Style the caps with `class` when you mean `classes.key` — on a combo, `class`
  is the row the caps sit in.

#### Pairs with

- [Command Palette](/docs/components/command-palette), [Menu](/docs/components/menu),
  [Tooltip](/docs/components/tooltip), [Text](/docs/components/text),
  [Button](/docs/components/button)

Parts (`classes`): `root` `key` `separator`

| Prop | Type | Notes |
| --- | --- | --- |
| `keys?` | `string \| readonly string[]` | The combo to draw: `'mod+k'`, `'shift+enter'`, or the same as an array. `mod` is ⌘ on Apple devices and Ctrl elsewhere. Without it, the children are drawn as one cap. |
| `variant?` | `KbdVariant` | One of `raised`, `flat`. Default `'raised'`. |
| `size?` | `KbdSize` | One of `sm`, `md`, `lg`. Default `'md'`. |
| `platform?` | `ShortcutPlatform` | Which keyboard to draw for. `auto` asks the browser once it has hydrated, and draws Ctrl until then. Default `'auto'`. |
| `separator?` | `string \| false` | Drawn between caps. Defaults to nothing on a Mac, where combos are written ⌘K, and `+` elsewhere, where they are written Ctrl+K. `false` for none anywhere. |
| `class?` | `string` |  |
| `classes?` | `KbdClasses` | Per-part Tailwind overrides. `class` still covers the root. |
| `children?` | `Snippet` | One cap's content, when `keys` is not set. |

### Label

`import { Label } from 'omaris'`

A form label. `for` wires it to its control, so clicking it focuses.

#### Use it for

- A control that does not draw its own label: a raw `<input>`, an element of
  your own, a third-party widget. `for` wires it so a click focuses.
- A row where the words are the click target. Wrap a Checkbox or a Switch in
  it and the whole line toggles.
- A heading over a group of controls that share one question, when the group
  is not a RadioGroup.

#### Not for

- A field with a `label` prop → [Text Field](/docs/components/input),
  [Textarea](/docs/components/textarea), [Select](/docs/components/select),
  [Combobox](/docs/components/combobox). The prop renders and wires this.
- A section heading in a form → [Text](/docs/components/text) with
  `variant="title-sm"` and `as="h3"`.
- Help text under a field → the field's `supportingText`.
- A tag on an item → [Badge](/docs/components/badge) or [Chip](/docs/components/chip).

#### Do

- Always give it a `for`, or put the control inside it. A label that focuses
  nothing is just a span.
- Set `required` on the label and on the control. The asterisk is for the
  eye; the attribute is for the screen reader and the browser.
- Set `disabled` to match the control, so the row dims as one thing.

#### Don't

- Point two controls at one `for`. A label names one thing.
- Use a placeholder instead. It is gone on the first keystroke.
- Grow it into a heading with `class`. It merges last and wins, but the size
  is a field label's for a reason.

#### Pairs with

- [Text Field](/docs/components/input), [Checkbox](/docs/components/checkbox),
  [Switch](/docs/components/switch), [Radio](/docs/components/radio),
  [Text](/docs/components/text)

| Prop | Type | Notes |
| --- | --- | --- |
| `required?` | `boolean` | Appends a `*`, announced as "required" by screen readers. Default `false`. |
| `disabled?` | `boolean` | Default `false`. |
| `class?` | `string` |  |
| `children?` | `Snippet` |  |

### LineChart

`import { LineChart } from 'omaris/chart'`

Line chart.

| Prop | Type | Notes |
| --- | --- | --- |
| `curve?` | `ChartCurve` | Default `'smooth'`. |
| `points?` | `boolean` | Mark each data point. Default `false`. |
| `dashed?` | `boolean` | Dash the line — for a forecast or a target. Default `false`. |
| `data` | `T[]` |  |
| `x?` | `Field<T>` | The category or time field. |
| `y?` | `Field<T>` | The value field. Ignored once `series` names its own. |
| `series?` | `ChartSeries<T>[]` | Several values per row. Each gets a colour and a legend entry. |
| `height?` | `number \| string` | Plot height. A number is px; a string is any CSS length. Default `260`. |
| `axis?` | `boolean \| 'x' \| 'y'` | `true` for both, or just the one you want. Default `true`. |
| `grid?` | `boolean` | Default `true`. |
| `legend?` | `ChartLegend` | `true` shows the legend and lets a click toggle a series off. `'isolate'` makes a click show that series alone, and a second one bring the rest back — which is the move you actually want on a chart with six lines on it. Default `false`. |
| `tooltip?` | `boolean` | Default `true`. |
| `formatX?` | `(value: never) => string` | Tick labels along the x axis. |
| `formatY?` | `(value: never) => string` | Tick labels along the y axis, and the tooltip's values. |
| `colors?` | `readonly string[]` | Palette override, cycled across the series. Default `CHART_COLORS`. |
| `padding?` | `number \| { top?: number; right?: number; bottom?: number; left?: number }` | Space around the plot, in px — room for long axis labels. |
| `label?` | `string` | Accessible description of what the chart shows. |
| `class?` | `string` |  |
| `empty?` | `Snippet` | Shown in place of the plot when `data` is empty. |
| `emptyText?` | `string` |  |
| `error?` | `boolean \| string \| Error` | Something went wrong. Truthy puts the chart into its error state; a string or an `Error` supplies the message. |
| `errorText?` | `string` | The message, when `error` is just `true`. |
| `errorState?` | `Snippet<[{ message: string }]>` | Replaces the whole error state. |
| `onRetry?` | `() => void` | Offers a "Try again" button in the error state. |
| `csv?` | `boolean \| string` | Offer the plotted rows as a CSV download, from a button in the corner. A string names the file. Default `false`. |
| `csvColumns?` | `(string \| { key: string; label?: string; value?: (row: T) => unknown })[]` | Which fields the download writes, in order. Defaults to every field. |
| `references?` | `ChartReference[]` | Lines and bands at fixed values — targets, thresholds, windows. |
| `annotations?` | `ChartAnnotation[]` | Notes pinned to a point. |
| `brush?` | `ChartBrush` | Drag across the plot to select a range, and zoom the chart to it. |
| `zoom?` | `ChartZoom` | Wheel or pinch to zoom, drag to pan. |

### List

`import { List } from 'omaris'`

MD3 list.

#### Use it for

- Rows of the same shape you read down: messages, contacts, warehouses.
  `headline` alone is one line; `supportingText` makes it two; `lines={3}`
  lets the note wrap once more.
- Rows the person picks from, like the current warehouse or the selected
  conversation. `interactive` with `selected`; `href` or `onclick` makes the
  row a real `<a>` or `<button>` with no wrapper.
- A settings list: an icon in `leading`, a `Switch` or a time in `trailing`.
- Rows with actions behind them (pin, archive, delete). `SwipeItem` around a
  `ListItem`, `fullSwipe` to fire the first action on a long drag, `dismiss`
  to collapse the row on the way out.
- Rows whose order is the data: a playlist, a checklist, dashboard panels.
  `Reorder` instead of `List`, `bind:items`, and a `ReorderHandle` in
  `leading`. It drags with a pointer and moves with the arrow keys.

#### Not for

- Several columns you compare or sort → [Table](/docs/components/table).
- The app's main navigation → [Navigation Drawer](/docs/components/navigation-drawer)
  or [Navigation Bar](/docs/components/navigation-bar). `as="nav"` is for a
  secondary list of links, in a sheet or a footer.
- Picking one of a few options in a form → [Radio](/docs/components/radio) or
  [Select](/docs/components/select). Actions off a button →
  [Menu](/docs/components/menu).
- Moving rows between several lists or columns → [Kanban](/docs/components/kanban).
  `Reorder` moves rows within one list.
- Rows with a heading, a body and their own actions → [Card](/docs/components/card).

#### Do

- Put `dividers` on the `List`, not a `Divider` after each row. There is none
  after the last row, and a swipe row keeps its line.
- Give the `List` a `label` ("Messages"). It is the accessible name of the
  `role="list"`.
- Use `variant="surface"` or `outlined` when the list sits on the page among
  other things; `plain` inside a card, a sheet or a menu.
- Use `density="compact"` in a dashboard panel. Leave it comfortable on a
  phone, where a row is a finger's target.
- Give `Reorder` a `key` when the rows have ids, so a row keeps its element
  and its focus across a move. Show a `ReorderHandle` even when the whole
  row drags, or nobody knows the list can be reordered.

#### Don't

- Put a `Switch` or a `Checkbox` in `trailing` of an `interactive` row. That
  is a control inside a button. Either the row press toggles it, or the row
  is not interactive.
- Use `spaced` on a long inbox. It is for a handful of rows that are
  different things.
- Rely on the swipe alone for an action a mouse user needs. Offer it in an
  overflow menu too.
- Wrap rows in `<ul>` and `<li>`, or leave the default `role` on a `ListItem`
  inside a `Reorder`. The default `div` with `role="list"` lets a row be a
  button; in `Reorder` the wrapper is the item, so pass `role="presentation"`.
- Make the whole row draggable when it is a link or holds a control. Use
  `handle`.

#### Pairs with

- [Avatar](/docs/components/avatar), [Divider](/docs/components/divider),
  [Switch](/docs/components/switch), [Checkbox](/docs/components/checkbox),
  [Menu](/docs/components/menu), [Sheet](/docs/components/sheet)

| Prop | Type | Notes |
| --- | --- | --- |
| `variant?` | `ListVariant` | One of `plain`, `surface`, `outlined`. Default `'plain'`. |
| `dividers?` | `boolean` | Hairline between rows. Default `false`. |
| `spaced?` | `boolean` | Round each row and space them apart. Default `false`. |
| `padding?` | `'none' \| 'sm' \| 'md'` | One of `none`, `sm`, `md`. Default `'none'`. |
| `label?` | `string` | Accessible name for the list. |
| `as?` | `'div' \| 'nav'` | The element to render. The default `div` carries `role="list"`, which lets a row be a `<button>` or `<a>` directly — a `<ul>` would need every row wrapped in an `<li>`, and a wrapper can't take the divider. Use `nav` for a navigation list. Default `'div'`. |
| `class?` | `string` |  |
| `children?` | `Snippet` |  |

### ListItem

`import { ListItem } from 'omaris'`

MD3 list item — one, two or three lines.

Parts (`classes`): `root` `leading` `body` `headline` `supporting` `trailing`

| Prop | Type | Notes |
| --- | --- | --- |
| `headline?` | `string` | Main line. |
| `supportingText?` | `string` | Second line. Its presence makes the row two lines tall. |
| `lines?` | `ListItemLines` | Force the line count rather than inferring it. One of `1`, `2`, `3`. |
| `density?` | `ListItemDensity` | One of `comfortable`, `compact`. Default `'comfortable'`. |
| `interactive?` | `boolean` | Force the interactive treatment. |
| `selected?` | `boolean` | Chosen state — the current page in a nav list, say. Default `false`. |
| `inset?` | `boolean` | Indent to line up with rows that have a leading slot. Default `false`. |
| `ripple?` | `boolean` | Default `true`. |
| `class?` | `string` |  |
| `classes?` | `ListItemClasses` | Per-part Tailwind overrides. `class` still covers the root. |
| `leading?` | `Snippet` | Leading slot — icon, avatar, checkbox. |
| `trailing?` | `Snippet` | Trailing slot — meta text, a switch, an overflow menu. |
| `children?` | `Snippet` | Rich body, in place of `headline` / `supportingText`. |
| `variant?` | `ButtonVariant` | Fill style. MD3's five, plus `link` for inline navigation. |
| `tone?` | `ButtonTone` | Color role the fill style paints with. |
| `size?` | `ButtonSize` | MD3 Expressive heights: 32 / 40 / 56 / 96 / 136dp. |
| `shape?` | `ButtonShape` | Pill (`round`) or MD3 rounded rectangle (`square`). |
| `icon?` | `boolean` | Square, label-less button. Requires an `aria-label`. |
| `confetti?` | `boolean \| ConfettiOptions` | Confetti on press. `true` for the default burst, or any `ConfettiOptions` — `confetti={{ preset: 'fireworks' }}`. |
| `loading?` | `boolean` | Grows a spinner in at the start of the button and blocks interaction. The label stays put; only an `icon` button swaps its icon out. |
| `toggle?` | `boolean` | Turns the button into a two-state toggle driven by `pressed`. Ignored when `href` is set — a link has no pressed state. |
| `pressed?` | `boolean` | Selected state of a toggle button. Bindable. |

### LogViewer

`import { LogViewer } from 'omaris'`

A log console: levels, filtering, search, ANSI colour, expandable rows and a tail that follows.

#### Use it for

- Output that keeps arriving from a build, a deploy or a worker. `follow`
  sticks to the newest line and lets go the moment the reader scrolls up.
- Plain strings from a process. The level is read off each line, ANSI colour
  resolves to theme tokens, and an existing log needs no preparation.
- Structured entries with `level`, `time`, `source` and `details`. A row
  with details opens on click: an object as a JSON tree, a string as a block.
- A hundred thousand lines. Rows are virtualised, so it scrolls as smoothly
  as ten and the scrollbar stays honest.
- Finding one line. `search` narrows and marks, Enter steps through the
  hits. `levels` is bindable, so the chips are state the page can read.

#### Not for

- A finished file nobody filters → [Code Block](/docs/components/code-block)
  with `lang="bash"` and `collapse`.
- Events with a time and a title, one per row → [List](/docs/components/list).
- One payload someone explores → [JSON Viewer](/docs/components/json-viewer).
- Metrics over time → [Chart](/docs/components/chart).

#### Do

- Append to `lines` rather than replacing it. A new line parses one line.
- Pass entries, not strings, when you have the parts. A `source` tag and a
  real `time` make the `error` chips and the timestamp column useful.
- Give it a `height` and let it scroll inside. A console the page scrolls
  around loses the tail.
- Set `filename` when `tools` is on, so the download is `deploy-42.log` and
  not `log.txt`.

#### Don't

- Default `wrap` on for a long log. Wrapping turns virtualisation off,
  because a wrapped row has no height until it is laid out.
- Strip the header and keep `follow` on. The "jump to newest" button is how a
  reader who scrolled up gets back.
- Colour lines by hand from `classes.row`. The level already uses the theme's
  `--warning` and `--destructive`, in both modes.

#### Pairs with

- [JSON Viewer](/docs/components/json-viewer),
  [Code Block](/docs/components/code-block), [Chip](/docs/components/chip),
  [Sheet](/docs/components/sheet), [Tabs](/docs/components/tabs)

Parts (`classes`): `root` `header` `search` `searchNav` `matchCount` `filters` `filter` `action` `tools` `tool` `viewport` `canvas` `window` `row` `toggle` `gutter` `time` `level` `source` `message` `mark` `markActive` `rowAction` `details` `detailsCard` `detailsText` `jump` `empty` `count` `live`

| Prop | Type | Notes |
| --- | --- | --- |
| `lines` | `(string \| LogEntry)[]` | Raw lines, one string each, or entries with their parts already split out. |
| `size?` | `LogViewerSize` | One of `md`. Default `'md'`. |
| `levels?` | `LogLevel[]` | Which levels to show. Left off, all of them. Lines with no level are always shown, unless this is an empty array. Bindable. |
| `filters?` | `boolean` | Show the level filter chips. Default `true`. |
| `search?` | `boolean` | Show the search box. Default `true`. |
| `follow?` | `boolean` | Stick to the newest line as output arrives. Bindable. Default `false`. |
| `wrappable?` | `boolean` | Offer the wrap toggle in the header. Default `true`. |
| `wrap?` | `boolean` | Wrap long lines instead of scrolling sideways. Bindable. Default `false`. |
| `lineNumbers?` | `boolean` | Line numbers down the left. Default `true`. |
| `timestamps?` | `boolean` | Draw the timestamp column. Default `true`. |
| `tools?` | `boolean` | Copy-all and download buttons in the header. Default `true`. |
| `filename?` | `string` | Name of the file the download button saves. Default `'output.log'`. |
| `expandable?` | `boolean` | Rows with `details` open on click, `Enter` or `Space`. Default `true`. |
| `expanded?` | `number[]` | Indices (into `lines`) of the rows whose details are open. Bindable. Default `[]`. |
| `onrowclick?` | `(row: LogRow, index: number) => void` | Called when a row is clicked or activated from the keyboard. |
| `formatTime?` | `(time: Date) => string` | How a timestamp is written. Defaults to a 12-hour clock with seconds, `02:05:09 PM`, in the page's language and Western digits. A bare `14:05:09` at the start of a raw line is read as today at that time. |
| `emptyText?` | `string` | Shown when nothing is left after filtering. Default `'Nothing to show.'`. |
| `height?` | `number \| string` | Height of the console. A number is px, a string any CSS length — a property rather than a class, so `classes.viewport` can replace it. Default `'24rem'`. |
| `class?` | `string` |  |
| `classes?` | `LogViewerClasses` |  |

### Magnifier

`import { Magnifier } from 'omaris'`

A loupe that really magnifies — text included.

#### Use it for

- Fine print people must be able to read: terms, a receipt, a footnote, a
  table at 11px. The lens holds live text scaled by the browser, so it is
  legible rather than blurry.
- A picture with detail that matters: a site plan, a scan, a product
  close-up, a map tile. `src` takes the picture directly.
- A dense diagram or chart where the labels are smaller than the shapes.
- A sprite sheet, a QR code or anything whose pixels are the subject.
  `pixelated` enlarges them instead of smoothing them.
- The system loupe, for a phone user picking a point precisely:
  `trigger="press"` with a wide `shape="rounded"` glass above the finger.

#### Not for

- Looking at a photograph properly, with panning, pinching and full-screen →
  [Image Viewer](/docs/components/image-viewer).
- Cropping or choosing a region of an image →
  [Image Cropper](/docs/components/image-cropper).
- More detail about a thing rather than a bigger copy of it →
  [Tooltip](/docs/components/tooltip) or [Popover](/docs/components/popover).
- Reading a whole document larger → let the browser zoom, or offer a
  type-size control. A loupe is for a spot, not a page.
- Live content: a video, a canvas, an animating chart. The copy is taken when
  the lens opens; `live` re-takes it on DOM changes, but a `<canvas>` or a
  playing `<video>` does not come with it.

#### Do

- Keep `zoom` between 2 and 3 for text. Past about 4 the lens shows three
  words and the reader loses their place.
- Use `lift` (or leave it `'auto'`) on touch, so the glass is not under the
  finger.
- Give the content a real width. The copy is laid out at the source's own
  width, so a `w-full` source in a narrow column magnifies what is on screen.
- Leave `keyboard` on. The control is invisible until focused, and it is the
  only way a keyboard user gets the same help.
- Use `shape="rounded"` with a wide `width` for text and a circle for
  pictures.

#### Don't

- Wrap an interactive region and expect the copy to be interactive. It is
  inert: nothing inside the lens is focusable and no handler fires twice.
- Turn `live` on for a page that mutates constantly. It re-copies the subtree
  on every change.
- Put one inside a scrolling column without `trigger="press"`. A hover lens
  on a touch screen fires on the first tap of a scroll.
- Magnify something that could simply be bigger. The lens is for content
  that has to stay small.

#### Pairs with

- [Image Viewer](/docs/components/image-viewer),
  [Image Cropper](/docs/components/image-cropper),
  [Card](/docs/components/card), [Text](/docs/components/text),
  [Table](/docs/components/table), [Maps](/docs/components/map)

Parts (`classes`): `root` `source` `image` `lens` `glass` `stage` `sheen` `rim` `control`

| Prop | Type | Notes |
| --- | --- | --- |
| `zoom?` | `number` | How much bigger. `2` is a reading aid, `4` inspects a detail. Default `2`. |
| `shape?` | `MagnifierShape` | The glass's outline. One of `circle`, `rounded`, `square`. Default `'circle'`. |
| `width?` | `number \| string` | Lens width — a number is px, a string is any CSS length. Default `132`. |
| `height?` | `number \| string` | Lens height. Defaults to `width`, which is what makes a circle round. |
| `trigger?` | `MagnifierTrigger` | What summons it. `auto` — the default — reads the pointer: a mouse opens it on hover, a finger on a press and hold. Default `'auto'`. |
| `hold?` | `number` | How long a touch has to hold still before the lens appears, in ms. Default `320`. |
| `lift?` | `number \| 'auto'` | How far above the pointer the lens both sits *and looks*, in px, so a finger never covers what it is magnifying. `'auto'` lifts it for touch only, by enough to clear the glass. Default `'auto'`. |
| `hideCursor?` | `boolean` | Hide the system cursor while the lens is up, so nothing is drawn over the magnified content. `false` keeps the arrow. Default `true`. |
| `open?` | `boolean` | Whether the lens is up. Bindable, so it can be driven from outside. Default `false`. Bindable. |
| `disabled?` | `boolean` | Turn it off without unwrapping the content. Default `false`. |
| `live?` | `boolean` | Re-copy the content as it changes, for something that moves under the glass. Default `false`. |
| `pixelated?` | `boolean` | Enlarge the pixels rather than smoothing them. Default `false`. |
| `fluid?` | `boolean` | A drop of glass rather than a disc: the lens eases after the pointer, stretches along its motion, and refracts at the rim. Default `false`. |
| `refraction?` | `number` | How hard the rim bends the picture with `fluid`, in px. Default `26`. |
| `keyboard?` | `boolean` | Offer the lens to the keyboard as well. Default `true`. |
| `label?` | `string` | The name of the keyboard control, and the lens's accessible label. Default `'Magnify'`. |
| `src?` | `string` | A picture to magnify, for the common case. Children work too. |
| `alt?` | `string` |  |
| `class?` | `string` |  |
| `classes?` | `MagnifierClasses` | Per-part Tailwind overrides. `class` still covers the root. |
| `children?` | `Snippet` |  |

### Map

`import { Map } from 'omaris/map'`

Interactive map.

#### Use it for

- A place. `Map` with `center` and `zoom`; the base style is keyless and
  follows the app's light and dark theme. `MapControls` for zoom, compass,
  locate and fullscreen buttons; `MapSource` and `MapLayer` for any other layer.
- Things at places. `Marker` is a real element with a `tone`, a `size` and a
  snippet (a photo, a price, an avatar); `draggable` lets it move.
  `MapPopup` is the card that opens on one.
- Many things. `MapCluster` groups thousands of points until you zoom;
  `MapHeatmap` shows where they concentrate, with `weight` for the ones that
  count more.
- Lines, areas and zones. `MapRoute` for a path; `arc` separates its legs,
  `animate` shows direction. `MapGeoJson` for any geometry, coloured by
  `colorBy`. `MapDraw` draws a zone; `MapGeofence` fires on every crossing.
- Things that move. `MapVehicle` drives to each new `lngLat` and faces the way
  it goes; `path` and `progress` follow a route, `follow` keeps the map on
  it. `MapVehicleIcon` is the same glyph for a list beside the map.
- Input. `MapPicker` for "put the pin on your door": the map moves under a
  fixed pin on touch, the pin drags with a mouse. `bind:lngLat`, `onsettle`
  for the geocoder, `describe` for the caption.

#### Not for

- A picture of a place → still `Map`, with `interactive={false}`.
- A distribution with no geography → [Chart](/docs/components/chart).
- Choosing a country or a city → [Combobox](/docs/components/combobox).
- A list of addresses → [List](/docs/components/list) or
  [Table](/docs/components/table), with the map beside it and `center` bound
  to the selected row.
- Ten thousand `Marker`s → `MapCluster`. Markers are DOM nodes, and ten
  thousand of them stutter.

#### Do

- Import from `omaris/map`, add `maplibre-gl` as a peer, and exclude it from
  `optimizeDeps` in dev. See [Charts and maps](/docs/charts-and-maps).
- Give it a `height`; MapLibre measures the box. Leave `attribution` on; the
  base maps require it.
- Frame a set of pins with `bounds` and `fitPadding` rather than guessing
  `center` and `zoom`. `fitPadding={{ bottom: 320 }}` keeps the frame out
  from under a sheet.
- Set `MapVehicle`'s `duration` to the interval positions arrive at, so it
  never stops between pings. Use `MapPicker` where the pin is the input; a
  `draggable` `Marker` is for a pin that happens to be movable.
- Draw a zone with `MapDraw` and hand the polygon to `MapGeofence`. Both
  take plain GeoJSON.

#### Don't

- Turn `scrollZoom` off by habit. Do it only when the map really must not
  eat the page's scroll.
- Use `MapHeatmap` to count. It says where, not how many; that is
  `MapCluster`.
- Build a fill, an outline and a dot layer by hand for one collection.
  `MapGeoJson` already filters each to its geometry.
- Add layers in `onload` with `map.addLayer`. A restyle wipes them;
  `MapSource` and `MapLayer` put themselves back.
- Move a car with a `Marker` whose `lngLat` you update. It teleports; use
  `MapVehicle`.

#### Pairs with

- [Card](/docs/components/card), [Sheet](/docs/components/sheet),
  [List](/docs/components/list), [Search Bar](/docs/components/search-bar),
  [Charts and maps](/docs/charts-and-maps)

| Prop | Type | Notes |
| --- | --- | --- |
| `center?` | `LngLat` | `[longitude, latitude]`. Bindable. Default `[0, 0]`. |
| `zoom?` | `number` | Bindable. Default `2`. |
| `bearing?` | `number` | Rotation in degrees. Bindable. Default `0`. |
| `pitch?` | `number` | Tilt in degrees. Bindable. Default `0`. |
| `bounds?` | `MapBounds` | Frame these bounds instead of using `center`/`zoom`. |
| `fitPadding?` | `number \| Partial<MapPadding>` | Padding, in px, kept around `bounds` — one number for all four sides, or a side or two of their own: `{ bottom: 320 }` frames the trip in the strip of map a sheet leaves visible. A side not named keeps the default 40. Default `40`. |
| `style?` | `MapStyleName \| 'blank' \| string \| StyleSpecification` | A name from `MAP_STYLES`, `'blank'`, a URL, or a full style object. |
| `theme?` | `'light' \| 'dark' \| 'auto'` | `auto` follows the app's light/dark setting. Default `'auto'`. |
| `minZoom?` | `number` |  |
| `maxZoom?` | `number` |  |
| `maxBounds?` | `MapBounds` | Keep the viewport inside these bounds. |
| `interactive?` | `boolean` | Turn off every interaction — a static picture of a place. Default `true`. |
| `rotatable?` | `boolean` | Let a drag rotate and tilt the map. Default `true`. |
| `scrollZoom?` | `boolean` | The wheel zooms. Default `true`. |
| `height?` | `number \| string` | Height of the map. A number is px; a string is any CSS length. Default `400`. |
| `attribution?` | `boolean` | Show the attribution the base maps require. Leave it on. Default `true`. |
| `cursor?` | `string` | Cursor over the map. |
| `onload?` | `(map: MapLibreMap) => void` |  |
| `onmove?` | `(viewport: MapViewport) => void` |  |
| `onmoveend?` | `(viewport: MapViewport) => void` |  |
| `onclick?` | `(lngLat: LngLat, event: MapMouseEvent) => void` |  |
| `oncontextmenu?` | `(lngLat: LngLat, event: MapMouseEvent) => void` |  |
| `class?` | `string` |  |
| `children?` | `Snippet` | Markers, layers, controls — anything that needs the map. |
| `overlay?` | `Snippet` | Drawn over the map, outside its own event handling. |

### MapCluster

`import { MapCluster } from 'omaris/map'`

Thousands of points, grouped.

| Prop | Type | Notes |
| --- | --- | --- |
| `id` | `string` |  |
| `data` | `GeoJsonInput` |  |
| `radius?` | `number` | How near two points have to be to group, in px. Default `50`. |
| `maxZoom?` | `number` | Above this zoom every point stands alone. Default `14`. |
| `color?` | `string` | Any CSS colour, for the clusters and the lone points. Default `'var(--chart-1)'`. |
| `steps?` | `[number, number]` | Counts at which a cluster steps up a size. Default `[10, 50]`. |
| `pointRadius?` | `number` | Radius of a point that isn't in a cluster, in px. Default `6`. |
| `onclick?` | `(event: MapLayerMouseEvent) => void` |  |
| `onpointclick?` | `(lngLat: LngLat, event: MapLayerMouseEvent) => void` | A press on a single point, with its coordinates. |

### MapControls

`import { MapControls } from 'omaris/map'`

Zoom, compass, locate and fullscreen — as omaris buttons rather than MapLibre's, so they carry the app's radii, shadows and focus rings and sit at a real touch target size.

| Prop | Type | Notes |
| --- | --- | --- |
| `position?` | `'top-start' \| 'top-end' \| 'bottom-start' \| 'bottom-end'` | Corner it sits in. Default `'top-end'`. |
| `zoom?` | `boolean` | Default `true`. |
| `compass?` | `boolean` | Reset north. Hidden while the map is already facing north. Default `true`. |
| `locate?` | `boolean` | Jump to the visitor's position. Default `false`. |
| `fullscreen?` | `boolean` | Default `false`. |
| `scale?` | `boolean` | A bar showing what the current scale means on the ground. Default `false`. |
| `onlocate?` | `(lngLat: LngLat) => void` | Called with the located position, so a caller can drop a marker. |
| `onlocateerror?` | `(error: GeolocationPositionError) => void` |  |
| `class?` | `string` |  |
| `children?` | `Snippet` | Extra buttons, below the built-in ones. |

### MapDraw

`import { MapDraw } from 'omaris/map'`

Draw a territory on the map.

| Prop | Type | Notes |
| --- | --- | --- |
| `polygon?` | `Feature<Polygon>` | The shape. Bindable — `undefined` until it's closed. Default `undefined`. Bindable. |
| `drawing?` | `boolean` | Start in drawing mode. Bindable. Default `false`. |
| `editable?` | `boolean` | Let existing corners be moved, added and removed. Default `true`. |
| `color?` | `string` | Any CSS colour. Default `'var(--chart-1)'`. |
| `id?` | `string` | Prefix for the layers this adds. Default `'omaris-draw'`. |
| `onfinish?` | `(polygon: Feature<Polygon>) => void` | Fires when the shape closes. |
| `onchange?` | `(points: LngLat[]) => void` | Fires on every change, including while drawing. |
| `onclear?` | `() => void` | Fires when the shape is cleared. |
| `class?` | `string` |  |

### MapGeofence

`import { MapGeofence } from 'omaris/map'`

Watch points against zones and say when one crosses.

| Prop | Type | Notes |
| --- | --- | --- |
| `zones` | `Zone[]` |  |
| `points?` | `TrackedPoint[]` | The points being watched. Update it and the crossings are reported. Default `[]`. |
| `id?` | `string` | Prefix for the layers this adds. Default `'omaris-geofence'`. |
| `show?` | `boolean` | Draw the zones. Off when something else already draws them. Default `true`. |
| `showPoints?` | `boolean` | Draw the points too. Default `true`. |
| `fillOpacity?` | `number` | Fill opacity of each zone. Default `0.14`. |
| `onenter?` | `(event: GeofenceEvent) => void` | A point crossed into a zone. |
| `onleave?` | `(event: GeofenceEvent) => void` | A point crossed out of one. |
| `onchange?` | `(inside: Map<string, string[]>) => void` | Which zones hold each point, on every change. |
| `marker?` | `Snippet<[TrackedPoint, string[]]>` | Rendered for each point, in place of the default dot. |

### MapGeoJson

`import { MapGeoJson } from 'omaris/map'`

Draw GeoJSON, whatever's in it.

| Prop | Type | Notes |
| --- | --- | --- |
| `id` | `string` |  |
| `data` | `GeoJsonInput` |  |
| `color?` | `string \| unknown[]` | Any CSS colour, or a MapLibre expression. Default `'var(--chart-1)'`. |
| `colorBy?` | `string` | Colour each feature by this property, which must hold a colour. |
| `fillOpacity?` | `number` | Fill opacity for polygons. Default `0.18`. |
| `lineWidth?` | `number` | Stroke width for lines and polygon outlines. Default `2`. |
| `pointRadius?` | `number` | Radius of point features, in px. Default `5`. |
| `dash?` | `number[]` | Dash the lines — `[2, 2]` and so on. |
| `interactive?` | `boolean` | Show a pointer and respond to presses. Default `false`. |
| `before?` | `string` | Insert below this layer id, to sit under the base map's labels. |
| `visible?` | `boolean` | Default `true`. |
| `onclick?` | `(event: MapLayerMouseEvent) => void` |  |
| `onhover?` | `(event: MapLayerMouseEvent \| null) => void` |  |

### MapHeatmap

`import { MapHeatmap } from 'omaris/map'`

Density, as heat.

| Prop | Type | Notes |
| --- | --- | --- |
| `id` | `string` |  |
| `data` | `GeoJsonInput` |  |
| `weight?` | `string` | Property whose value weights each point. Defaults to one each. |
| `maxWeight?` | `number` | Largest expected value of `weight`, for scaling. Default `1`. |
| `radius?` | `number` | Blur radius, in px. Default `24`. |
| `intensity?` | `number` | Default `1`. |
| `opacity?` | `number` | Default `0.8`. |
| `maxZoom?` | `number` | Stop drawing above this zoom, where points are better. Default `16`. |
| `before?` | `string` |  |
| `visible?` | `boolean` | Default `true`. |

### MapLayer

`import { MapLayer } from 'omaris/map'`

A style layer over a source.

| Prop | Type | Notes |
| --- | --- | --- |
| `id` | `string` |  |
| `type` | `LayerSpecification['type']` |  |
| `source?` | `string` | Defaults to the enclosing `<MapSource>`. |
| `sourceLayer?` | `string` | Layer within a vector source. |
| `paint?` | `Record<string` |  |
| `layout?` | `Record<string` |  |
| `filter?` | `FilterSpecification` |  |
| `minZoom?` | `number` |  |
| `maxZoom?` | `number` |  |
| `before?` | `string` | Insert below this layer, to sit under the labels. |
| `visible?` | `boolean` | Hide without removing. Default `true`. |
| `interactive?` | `boolean` | Show a pointer over the layer's features. Default `false`. |
| `onclick?` | `(event: MapLayerMouseEvent) => void` |  |
| `onhover?` | `(event: MapLayerMouseEvent \| null) => void` |  |

### MapPicker

`import { MapPicker } from 'omaris/map'`

"Put the pin where you are."

Parts (`classes`): `root` `pin` `caption` `control`

| Prop | Type | Notes |
| --- | --- | --- |
| `lngLat?` | `LngLat` | The chosen point. Bindable; starts at the map's centre when omitted. Bindable. |
| `mode?` | `MapPickerMode` | `center` fixes the pin in the middle and moves the map; `drag` moves the pin. `auto` is `center` on a coarse pointer and `drag` on a fine one. Default `'auto'`. |
| `tone?` | `MapPickerTone` | One of `primary`, `secondary`, `tertiary`, `destructive`, `success`, `warning`, `info`. Default `'primary'`. |
| `size?` | `MapPickerSize` | One of `sm`, `md`, `lg`. Default `'md'`. |
| `describe?` | `string \| ((lngLat: LngLat) => string \| Promise<string>)` | Text for the caption — a string, or a function of the point that may return a promise. Called once the pin settles. |
| `clickToMove?` | `boolean` | In `drag` mode, a click on the map moves the pin there. On by default. Default `true`. |
| `nudge?` | `number` | Pixels an arrow key moves the pin. Default `8`. |
| `disabled?` | `boolean` | Show the pin but take no input. Default `false`. |
| `title?` | `string` | Accessible name of the pin. Default `'Location'`. |
| `onchange?` | `(lngLat: LngLat) => void` | Fires with every movement, mid-gesture included. |
| `onsettle?` | `(lngLat: LngLat) => void` | Fires once the pin has come to rest. |
| `z?` | `number` | Stacking order against markers, in `drag` mode. |
| `class?` | `string` |  |
| `classes?` | `MapPickerClasses` | Per-part Tailwind overrides. `class` still covers the root. |
| `children?` | `Snippet` | Replaces the pin. Its bottom edge is the point. |

### MapPopup

`import { MapPopup } from 'omaris/map'`

A card anchored to a place on the map.

| Prop | Type | Notes |
| --- | --- | --- |
| `lngLat` | `LngLat` | `[longitude, latitude]` it points at. |
| `open?` | `boolean` | Bindable. Default `true`. |
| `anchor?` | `\| 'center'` | Which side of the coordinate it sits on. Auto-placed when unset. |
| `offset?` | `number` | Distance from the coordinate, in px. The default clears a dot; a `pin` marker stands about 44px above its point, so a popup on one wants `offset={44}` or it sits on the pin's head. Default `14`. |
| `closeButton?` | `boolean` | Show the ×. Default `true`. |
| `closeOnClick?` | `boolean` | A press on the map closes it. Default `true`. |
| `focus?` | `boolean` | Pan the map so the popup fits. Default `true`. |
| `maxWidth?` | `string` | Default `'18rem'`. |
| `onclose?` | `() => void` |  |
| `class?` | `string` |  |
| `children?` | `Snippet` |  |

### MapRoute

`import { MapRoute } from 'omaris/map'`

A path between places.

| Prop | Type | Notes |
| --- | --- | --- |
| `id` | `string` |  |
| `coordinates` | `LngLat[]` | The path, in order. |
| `color?` | `string` | Any CSS colour. Default `'var(--chart-1)'`. |
| `width?` | `number` | Default `3`. |
| `arc?` | `boolean` | Bend each leg instead of drawing it straight. Default `false`. |
| `bend?` | `number` | How far each arc bows out, as a fraction of the leg's length. Default `0.2`. |
| `dash?` | `number[]` | Dash pattern, e.g. `[2, 2]`. |
| `animate?` | `boolean` | March the dashes along the line. Implies `dash`. Default `false`. |
| `halo?` | `boolean` | A soft wider line under the main one, so it reads over any base map. Default `true`. |
| `opacity?` | `number` | Default `1`. |
| `before?` | `string` |  |
| `visible?` | `boolean` | Default `true`. |

### MapSource

`import { MapSource } from 'omaris/map'`

A GeoJSON source, declared rather than added.

| Prop | Type | Notes |
| --- | --- | --- |
| `id` | `string` | Unique within the map. Layers refer to it by this. |
| `data` | `GeoJsonInput` |  |
| `cluster?` | `boolean` | Group nearby points. See `<MapCluster>` for the ready-made version. Default `false`. |
| `clusterRadius?` | `number` | Default `50`. |
| `clusterMaxZoom?` | `number` | Default `14`. |
| `clusterProperties?` | `Record<string` | Sums and counts to compute per cluster. |
| `tolerance?` | `number` | Simplification tolerance. Lower is more faithful and heavier. |
| `children?` | `Snippet` | Layers reading from this source. |

### MapVehicle

`import { MapVehicle } from 'omaris/map'`

Something that moves: a car, a courier, a bus, a boat.

Parts (`classes`): `root` `body` `glyph` `pulse` `label`

| Prop | Type | Notes |
| --- | --- | --- |
| `model?` | `VehicleModel` | Default `'car'`. |
| `lngLat?` | `LngLat` | Where it is. Each change is driven to, not jumped to. |
| `path?` | `LngLat[]` | Follow this path instead of `lngLat`; `progress` says how far. |
| `progress?` | `number` | 0 → 1 along `path`, by distance. Default `0`. |
| `heading?` | `number` | Degrees clockwise from north. Worked out from the movement when omitted. |
| `duration?` | `number` | How long a move takes, in ms — the interval positions arrive at. Default `600`. |
| `variant?` | `MapVehicleVariant` | One of `plain`, `badge`. Default `'plain'`. |
| `tone?` | `MapVehicleTone` | One of `primary`, `secondary`, `tertiary`, `destructive`, `success`, `warning`, `info`, `foreground`. Default `'foreground'`. |
| `size?` | `MapVehicleSize` | One of `sm`, `md`, `lg`. Default `'md'`. |
| `active?` | `boolean` | Highlight it — the one that is yours. Default `false`. |
| `pulse?` | `boolean` | A ring breathing under it: live, and being tracked. Default `false`. |
| `follow?` | `boolean` | Keep the map centred on it. Bindable: a drag on the map turns it off, so a "recentre" button is `onclick={() => (follow = true)}`. Default `false`. Bindable. |
| `label?` | `string` | Short text under it. |
| `z?` | `number` | Stacking order against the other markers. |
| `title?` | `string` | Accessible name. Falls back to `label`, then to the model. |
| `onclick?` | `(lngLat: LngLat) => void` |  |
| `onarrive?` | `(lngLat: LngLat, heading: number) => void` | Fires when a move finishes — with where it is and which way it faces. |
| `class?` | `string` |  |
| `classes?` | `MapVehicleClasses` | Per-part Tailwind overrides. `class` still covers the root. |
| `children?` | `Snippet` | Replaces the glyph. Still rotated to the heading. |

### MapVehicleIcon

`import { MapVehicleIcon } from 'omaris/map'`

One of the vehicles on its own — for a list of ride tiers, a legend, a chip — drawn exactly as `<MapVehicle>` draws it on the map.

| Prop | Type | Notes |
| --- | --- | --- |
| `model?` | `VehicleModel` | Default `'car'`. |
| `heading?` | `number` | Degrees clockwise from north. Default `0`. |
| `shadow?` | `boolean` | Draw the soft shadow on the ground. Off for an icon in a list. Default `true`. |
| `class?` | `string` |  |

### Marker

`import { Marker } from 'omaris/map'`

A point on the map.

Parts (`classes`): `root` `label`

| Prop | Type | Notes |
| --- | --- | --- |
| `lngLat` | `LngLat` | `[longitude, latitude]`. Bindable when `draggable`. Bindable. |
| `tone?` | `MarkerTone` | One of `primary`, `secondary`, `tertiary`, `destructive`, `success`, `warning`, `info`. Default `'primary'`. |
| `size?` | `MarkerSize` | One of `sm`, `md`, `lg`. Default `'md'`. |
| `pin?` | `boolean` | Draw a teardrop pin instead of a dot. Default `false`. |
| `active?` | `boolean` | Highlight it — the selected one in a list, say. Default `false`. |
| `label?` | `string` | Short text under the pin. |
| `anchor?` | `\| 'center'` | Which part of the element sits on the coordinate. Default `pin ? 'bottom' : 'center'`. |
| `draggable?` | `boolean` | Let it be dragged. `lngLat` follows. Default `false`. |
| `z?` | `number` | Stacking order against the other markers. |
| `title?` | `string` | Accessible name. Falls back to `label`. |
| `onclick?` | `(lngLat: LngLat) => void` |  |
| `ondragend?` | `(lngLat: LngLat) => void` |  |
| `class?` | `string` |  |
| `classes?` | `MarkerClasses` | Per-part Tailwind overrides. `class` still covers the root. |
| `children?` | `Snippet` | Replaces the pin entirely. |

### Masonry

`import { Masonry } from 'omaris'`

A masonry grid — the photo wall. Cards of unequal height, packed so the bottom edge comes out level, in reading order.

#### Use it for

- A wall of pictures or cards of unequal height: a photo board, a moodboard,
  a wall of notes. Cards pack in reading order and the bottom edge comes out
  level.
- Infinite scroll. `onend` fires as the bottom nears the viewport and re-arms
  when the next page lands.
- A board with filters. A `key` per pin means switching boards slides the
  survivors into place instead of re-mounting them.
- The same wall in a rail and in the main column. The column count follows
  the container and `minColumnWidth`, not the viewport.

#### Not for

- Cards of the same height → a plain grid,
  `grid-cols-[repeat(auto-fill,minmax(16rem,1fr))]`. Nothing to level.
- A row paged through, one in front → [Carousel](/docs/components/carousel).
- Rows of data → [List](/docs/components/list) or [Table](/docs/components/table).
- Columns of cards you drag between → [Kanban](/docs/components/kanban).
- Opening a picture → [Image Viewer](/docs/components/image-viewer) around
  the wall, with each pin an `ImageViewerItem`.

#### Do

- Give every `<img>` `width`, `height` and an `aspect-ratio`, so the first
  pack is right before the picture loads and nothing jumps after.
- Pass `key` from your data, not the index, so a filter or a new page keeps
  each pin's identity.
- Leave `balance="height"` for pictures. Use `order` when the sequence must
  read strictly left to right: numbered steps, a timeline of notes.
- Show a [Skeleton](/docs/components/skeleton) row under the wall while
  `onend` loads, and set `aria-busy` on the container.

#### Don't

- Use CSS `columns`. It lays out down-then-across and slices a card at the
  column break.
- Fix `columns` for a wall that fills the page. Let `minColumnWidth` derive
  it; a fixed count is for a small known set, like a three-column pricing wall.
- Set the gap or the count with classes per breakpoint. `gap` and
  `minColumnWidth` are props, and padding in `class` is already respected.
- Animate a board of thousands. Set `animate={false}` when a re-pack moves
  more than a screenful.

#### Pairs with

- [Image Viewer](/docs/components/image-viewer), [Card](/docs/components/card),
  [Chip](/docs/components/chip), [Skeleton](/docs/components/skeleton),
  [Empty](/docs/components/empty)

Parts (`classes`): `item` `sentinel`

| Prop | Type | Notes |
| --- | --- | --- |
| `items` | `T[]` |  |
| `item` | `Snippet<[T, MasonryItemContext]>` | How to draw one entry. It is given the full width of its column. |
| `columns?` | `number` | Fix the column count. Left off, it is derived from the container's width and `minColumnWidth`. |
| `minColumnWidth?` | `number` | Narrowest a column may get before one is dropped. Default `240`. |
| `maxColumns?` | `number` | Ceiling for the derived count. Default `8`. |
| `gap?` | `number \| string` | Gap between columns and between cards. Default `16`. |
| `balance?` | `MasonryBalance` | `height` packs each card into the shortest column — a level bottom edge. `order` deals them out in turn, which keeps a strict left-to-right rhythm at the cost of a ragged bottom. Default `'height'`. |
| `animate?` | `boolean` | Slide cards on a re-pack and fade new ones in. Reduced motion turns it off. Default `true`. |
| `key?` | `(item: T, index: number) => string \| number` | Stable key per entry. Defaults to the index. |
| `onend?` | `() => void` | Called once when the bottom of the wall scrolls within `endOffset` of the viewport — the hook for infinite scroll. It re-arms when `items` change, so appending a page makes it fire again for the next one. |
| `endOffset?` | `number` | How far above the bottom `onend` fires, in px. Default `400`. |
| `class?` | `string` |  |
| `classes?` | `MasonryClasses` | Per-part Tailwind overrides. `class` still covers the root. |

### Menu

`import { Menu } from 'omaris'`

MD3 menu — a list of actions hanging off a trigger.

#### Use it for

- Actions off a trigger: the overflow on a row or card behind an
  [Icon Button](/docs/components/icon-button), the account menu, "more" at
  the end of a toolbar.
- A single choice the trigger names, like "Density: comfortable". `selected`
  draws the tick on the current row, and `radio` makes the rows one set.
- A second level that would crowd the first: "Move to ▸", "Sort by ▸" as a
  `MenuSub`. On a phone it expands in place inside the sheet.
- A set of toggles changed in one visit. `closeOnSelect={false}` keeps it
  open; `selected={false}` reserves the tick's space so rows do not shift.
- Links, when a row has `href`.

#### Not for

- A value in a form → [Select](/docs/components/select); one you search for →
  [Combobox](/docs/components/combobox). A Menu does something; a Select
  holds something.
- The main action and its alternatives → [Split Button](/docs/components/split-button).
- Moving between the app's sections → [Navigation Drawer](/docs/components/navigation-drawer).
- Anything with a field in it, or a decision to confirm → [Dialog](/docs/components/dialog)
  or [Sheet](/docs/components/sheet).
- Explaining what a control does → [Tooltip](/docs/components/tooltip).

#### Do

- Spread the trigger snippet's props onto the real button, so the ARIA and
  the click land on the element that has focus.
- Put the destructive row last, after a [Divider](/docs/components/divider),
  with `tone="destructive"`.
- Give every row an `icon` or none. `inset` lines up the odd one out.
- Use `shortcut` only for a shortcut that works on the page.

#### Don't

- Nest one menu in another; there is no submenu. Group with `MenuLabel` and
  a Divider, or move the set into a [Sheet](/docs/components/sheet).
- Set `selected` on a row that is an action. A tick means a state, and
  "Delete ✓" makes no sense.
- Build a row without `data-menu-item`. The arrow keys find rows by it;
  `MenuItem` sets it, your own `<button>` does not.
- Let it grow past a dozen rows. Past that it scrolls, and a scrolled menu
  should be a page.

#### Pairs with

- [Icon Button](/docs/components/icon-button), [Button](/docs/components/button),
  [Split Button](/docs/components/split-button), [Divider](/docs/components/divider),
  [Dialog](/docs/components/dialog)

Parts (`classes`): `surface` `trigger`

| Prop | Type | Notes |
| --- | --- | --- |
| `open?` | `boolean` | Bindable. Default `false`. |
| `side?` | `AnchorSide` | Default `'bottom'`. |
| `align?` | `AnchorAlign` | Default `'start'`. |
| `offset?` | `number` | Default `6`. |
| `size?` | `MenuSize` | One of `sm`, `md`, `lg`. Default `'md'`. |
| `matchWidth?` | `boolean` | Make the menu at least as wide as its trigger. Default `false`. |
| `closeOnSelect?` | `boolean` | Leave the menu open after an item is chosen — for a set of toggles. Default `true`. |
| `label?` | `string` | Accessible name for the menu. |
| `mobileSheet?` | `boolean` | On a phone, rise from the bottom edge as a sheet — full width, a scrim behind, dragged down to dismiss, rows a thumb can hit — instead of hanging off the trigger. `false` keeps it anchored. Default `true`. |
| `class?` | `string` |  |
| `classes?` | `MenuClasses` | Per-part Tailwind overrides. `class` still covers the root. |
| `trigger?` | `Snippet<[MenuTriggerProps]>` | Receives the props to spread onto the opening control. |
| `children?` | `Snippet` | The items — `MenuItem`, `MenuLabel`, `Divider`. Arrow-key navigation finds rows by their `data-menu-item` attribute, which `MenuItem` sets for you; an item you build yourself needs that attribute or the keyboard will skip it. |
| `aria-haspopup` | `'menu'` |  |
| `aria-expanded` | `boolean` |  |
| `aria-controls` | `string \| undefined` |  |
| `onclick` | `(event: MouseEvent) => void` |  |
| `onkeydown` | `(event: KeyboardEvent) => void` |  |

### MenuItem

`import { MenuItem } from 'omaris'`

A row in a `Menu`.

Parts (`classes`): `root` `label` `shortcut` `check`

| Prop | Type | Notes |
| --- | --- | --- |
| `tone?` | `MenuItemTone` | One of `default`, `destructive`. Default `'default'`. |
| `selected?` | `boolean` | Checkable row: shows a trailing tick when true. Leaving it undefined keeps the row a plain `menuitem` rather than a checkbox. |
| `radio?` | `boolean` | One of a set, rather than a toggle of its own: the checkable row becomes a `menuitemradio`, which is what a screen reader needs to say "Sort by: Name, selected, 1 of 3". Default `false`. |
| `inset?` | `boolean` | Indent to line up with rows that have a leading icon. Default `false`. |
| `shortcut?` | `string` | Right-aligned hint — a keyboard shortcut, a count. |
| `ripple?` | `boolean` | Default `true`. |
| `class?` | `string` |  |
| `classes?` | `MenuItemClasses` | Per-part Tailwind overrides. `class` still covers the root. |
| `icon?` | `Snippet` | Leading icon. |
| `end?` | `Snippet` | Trailing content, before the tick. |
| `children?` | `Snippet` |  |
| `variant?` | `ButtonVariant` | Fill style. MD3's five, plus `link` for inline navigation. |
| `size?` | `ButtonSize` | MD3 Expressive heights: 32 / 40 / 56 / 96 / 136dp. |
| `shape?` | `ButtonShape` | Pill (`round`) or MD3 rounded rectangle (`square`). |
| `confetti?` | `boolean \| ConfettiOptions` | Confetti on press. `true` for the default burst, or any `ConfettiOptions` — `confetti={{ preset: 'fireworks' }}`. |
| `loading?` | `boolean` | Grows a spinner in at the start of the button and blocks interaction. The label stays put; only an `icon` button swaps its icon out. |
| `toggle?` | `boolean` | Turns the button into a two-state toggle driven by `pressed`. Ignored when `href` is set — a link has no pressed state. |
| `pressed?` | `boolean` | Selected state of a toggle button. Bindable. |

### MenuLabel

`import { MenuLabel } from 'omaris'`

A heading over a run of menu items.

| Prop | Type | Notes |
| --- | --- | --- |
| `class?` | `string` |  |
| `children?` | `Snippet` |  |

### MenuSub

`import { MenuSub } from 'omaris'`

A row that opens a menu of its own — "Move to ▸", "Sort by ▸".

Parts (`classes`): `trigger` `chevron` `surface` `inline`

| Prop | Type | Notes |
| --- | --- | --- |
| `label` | `string` | The row's text. |
| `open?` | `boolean` | Bindable. Default `false`. |
| `delay?` | `number` | Delay before a hover opens it, in ms — long enough to cross it on the way down. Default `120`. |
| `class?` | `string` |  |
| `classes?` | `MenuSubClasses` |  |
| `icon?` | `Snippet` | Leading icon on the row. |
| `children?` | `Snippet` | The submenu's rows — `MenuItem`, `MenuLabel`, `Divider`, another `MenuSub`. |

### MultiSelect

`import { MultiSelect } from 'omaris'`

Several values from a list, in one field.

#### Use it for

- Several values from a known list in one field: labels on an issue,
  reviewers on a pull request, categories on a product, permissions on a role.
- A filter that means "any of these": statuses, owners, tags.
- Free-form tags. Use `creatable` when the list is a head start and new
  values are expected.
- A capped set. `max={3}` disables the remaining rows and shows the count
  under the field, so the limit is visible before it is hit.

#### Not for

- One value → [Select](/docs/components/select), or
  [Combobox](/docs/components/combobox) when the list needs searching.
- Two to five options with room to show them all →
  [Checkbox](/docs/components/checkbox) in a group. Hiding four options
  behind a click is worse than showing them.
- A filter bar above a list where the choices should stay on screen →
  [Chip](/docs/components/chip) with `selectable`.
- Picking from a very long remote list, one at a time →
  [Combobox](/docs/components/combobox) with `load`.

#### Do

- Give the options `keywords` for the words people type: an ISO code, a
  nickname, an old name. Use `group` when the list has natural sections.
- Pick the `display` to fit the field: `chips` when it is wide, `collapse={2}`
  when it is not, `count` in a narrow filter bar.
- Add `selectAll` when picking most of the list is common, and `max` when the
  form has a real limit.
- Keep `closeOnSelect` off. Closing after each pick turns three choices into
  three round-trips.
- Set `name` to post the values. One hidden input per value, so the form
  sends an array.

#### Don't

- Use it with two options. That is two checkboxes.
- Rely on chips alone in a narrow field. Five chips in a 16rem input wrap
  into a wall; use `collapse` or `display="count"`.
- Turn `searchable` off on a list longer than about a dozen.
- Let `creatable` write to the database on every keystroke. Handle
  `oncreate` and decide there what a new value means.

#### Pairs with

- [Select](/docs/components/select), [Combobox](/docs/components/combobox),
  [Chip](/docs/components/chip), [Checkbox](/docs/components/checkbox),
  [Text Field](/docs/components/input)

Parts (`classes`): `root` `field` `control` `label` `adornment` `affix` `action` `support` `counter` `surface` `option` `group` `body` `description` `check` `empty` `highlight` `chips` `chip` `row` `box` `all` `divider` `count` `search` `chevron`

| Prop | Type | Notes |
| --- | --- | --- |
| `values?` | `string[]` | The chosen values, in the order they were picked. Bindable. Default `[]`. |
| `options?` | `MultiSelectOption[]` | The options. Rows with a `group` are filed under that heading. Default `[]`. |
| `query?` | `string` | What's in the search box. Bindable. Default `''`. |
| `variant?` | `InputVariant` | Default `'outline'`. |
| `size?` | `InputSize` | One of `sm`, `default`, `lg`. Default `'default'`. |
| `display?` | `MultiSelectDisplay` | How the chosen options read in the closed field. Default `'chips'`. |
| `collapse?` | `number` | Show only this many chips, and a "+n" for the rest. |
| `max?` | `number` | Most that can be chosen. The remaining rows go disabled at the cap. |
| `searchable?` | `boolean` | Let the field filter as you type. On by default. Default `true`. |
| `mobileSheet?` | `boolean` | On a phone, the list rises from the bottom edge as a sheet — full width, a scrim behind, dragged down to dismiss, rows a thumb can hit — instead of hanging under the field. `false` keeps it anchored. |
| `creatable?` | `boolean` | Offer the typed text as a new value when nothing matches it. Default `false`. |
| `filter?` | `(option: MultiSelectOption, query: string) => boolean` | Your own matcher, when label and `keywords` aren't enough. |
| `highlight?` | `boolean` | Bolden the matched part of each label. Default `true`. |
| `clearable?` | `boolean` | Show an × that empties the field. Default `true`. |
| `closeOnSelect?` | `boolean` | Close the list after each pick. Off by default — this is a multi-select. Default `false`. |
| `selectAll?` | `boolean` | A "Select all" / "Clear" row above the options. Default `false`. |
| `emptyText?` | `string` | Default `'No results'`. |
| `label?` | `string` |  |
| `supportingText?` | `string` | Helper line under the field. Becomes the error text when `invalid`. |
| `invalid?` | `boolean` | Inside a `Field`, defaults to the field's. |
| `required?` | `boolean` | Inside a `Field`, defaults to the field's. |
| `onchange?` | `(values: string[], options: MultiSelectOption[]) => void` | Fires with the new list on every change. |
| `oncreate?` | `(label: string) => MultiSelectOption \| void` | Called when a `creatable` field takes text that matched nothing. |
| `start?` | `Snippet` | Leading icon inside the frame. |
| `option?` | `Snippet<[MultiSelectOption, { selected: boolean; active: boolean; query: string }]>` | Replaces a row of the list. |
| `chip?` | `Snippet<[MultiSelectOption, { remove: () => void }]>` | Replaces a chip in the field. |
| `class?` | `string` |  |
| `classes?` | `MultiSelectClasses` | Per-part Tailwind overrides. `class` still covers the root. |
| `ref?` | `HTMLInputElement \| null` | Default `null`. Bindable. |

### Navigation

`import { Navigation } from 'omaris'`

A bottom bar and the screens it moves between, holding the one piece of state they share.

#### Use it for

- Primary navigation on a phone: three to five top-level destinations along
  the bottom, `fixed`, on every screen.
- The layout below `md`, where `AppShellSidebar` has dropped out and the
  drawer is off screen.
- A count on a destination, like unread messages or open orders. `badge`
  sits on the icon without touching the pill.
- Screens a thumb can swipe between. Wrap the bar and its content in
  `Navigation` with `swipeable`, give each destination a `value` and each
  screen a `NavigationView`.

#### Not for

- More than five destinations → [Navigation Drawer](/docs/components/navigation-drawer),
  modal on a phone or `responsive`.
- A laptop or desktop → [Navigation Drawer](/docs/components/navigation-drawer).
  There is no rail component; `collapsed` on the drawer is the rail.
- Views within one screen → [Tabs](/docs/components/tabs), which swipe the
  same way.
- An action like compose, search or add → [FAB](/docs/components/fab) or the
  `actions` of a [Top App Bar](/docs/components/top-app-bar).
- Two destinations → [Tabs](/docs/components/tabs) or a
  [Segmented Button](/docs/components/segmented-button). A bar of two is
  mostly empty.

#### Do

- Show the same destinations, in the same order, on every top-level screen,
  and mark the current one `selected`.
- Give `selectedIcon` the filled twin of `icon`, and set `elevated` when
  content scrolls underneath it.
- Keep `labels="always"`. Drop to `selected` only when five labels squeeze
  and the icons are unmistakable.
- Use `Navigation` instead of `selected={x === 'home'}` and an `onclick` on
  every item. One bindable `value` owns the destination and enables the swipe
  and the sliding indicator.
- Keep the `NavigationView` order the same as the items' order. A drag follows
  the writing direction; under `dir="rtl"` the bar mirrors. Pair `swipeable`
  with `lazy` when a screen is expensive, or every view is mounted.

#### Don't

- Change which destinations appear depending on the screen, or put a
  transient or destructive action in it.
- Use `labels="never"`. An icon alone is a guess for a first-time visitor.
- Show it alongside the drawer on a wide screen. One primary navigation at a
  time.
- Mark a plain sideways scroller `data-swipe-ignore`. It hands over the swipe
  once it runs out of room. Save the attribute for something with its own
  pointer handling: a carousel, a slider, a canvas.
- Turn `mouse` on for a production app. A drag is a touch gesture; on a
  desktop it fights text selection.

#### Pairs with

- [Navigation Drawer](/docs/components/navigation-drawer), [Top App Bar](/docs/components/top-app-bar),
  [App Shell](/docs/components/app-shell), [Badge](/docs/components/badge),
  [FAB](/docs/components/fab)

| Prop | Type | Notes |
| --- | --- | --- |
| `value?` | `string` | The current destination. Bindable. Default `undefined`. |
| `swipeable?` | `boolean` | Let the views be dragged sideways. Needs them wrapped in `NavigationViews`, and mounts them all at once so there is something to drag to — pair it with `lazy` when a screen is expensive. Default `false`. |
| `class?` | `string` |  |
| `children?` | `Snippet` |  |

### NavigationBar

`import { NavigationBar } from 'omaris'`

MD3 navigation bar — the bottom bar on a phone, 3–5 destinations.

| Prop | Type | Notes |
| --- | --- | --- |
| `size?` | `NavigationBarSize` | Default `'md'`. |
| `elevated?` | `boolean` | Default `false`. |
| `fixed?` | `boolean` | Default `false`. |
| `labels?` | `NavigationLabelMode` | Applies to every item that doesn't override it. Default `'always'`. |
| `label?` | `string` | Accessible name — "Main". |
| `class?` | `string` |  |
| `children?` | `Snippet` |  |

### NavigationBarItem

`import { NavigationBarItem } from 'omaris'`

A destination in a `NavigationBar`.

Parts (`classes`): `root` `indicator` `label`

| Prop | Type | Notes |
| --- | --- | --- |
| `label?` | `string` | Label under the icon. |
| `value?` | `string` | Names the destination, and the `NavigationView` it opens. Inside a `Navigation` this replaces `selected` and the `onclick` that went with it — the container owns which one is current. |
| `selected?` | `boolean` | Default `false`. |
| `labels?` | `NavigationLabelMode` | Override the container's label policy for this destination. |
| `badge?` | `number \| boolean` | A count on the icon — rendered as an anchored badge. |
| `badgeMax?` | `number` | Cap for a numeric badge. Default `99`. |
| `ripple?` | `boolean` | Default `true`. |
| `class?` | `string` |  |
| `classes?` | `NavigationBarItemClasses` | Per-part Tailwind overrides. `class` still covers the root. |
| `icon?` | `Snippet` | The icon. Swap it for a filled version when selected if you like. |
| `selectedIcon?` | `Snippet` | Icon shown only while selected — MD3's filled/outlined pair. |
| `children?` | `Snippet` |  |
| `variant?` | `ButtonVariant` | Fill style. MD3's five, plus `link` for inline navigation. |
| `tone?` | `ButtonTone` | Color role the fill style paints with. |
| `size?` | `ButtonSize` | MD3 Expressive heights: 32 / 40 / 56 / 96 / 136dp. |
| `shape?` | `ButtonShape` | Pill (`round`) or MD3 rounded rectangle (`square`). |
| `confetti?` | `boolean \| ConfettiOptions` | Confetti on press. `true` for the default burst, or any `ConfettiOptions` — `confetti={{ preset: 'fireworks' }}`. |
| `loading?` | `boolean` | Grows a spinner in at the start of the button and blocks interaction. The label stays put; only an `icon` button swaps its icon out. |
| `toggle?` | `boolean` | Turns the button into a two-state toggle driven by `pressed`. Ignored when `href` is set — a link has no pressed state. |
| `pressed?` | `boolean` | Selected state of a toggle button. Bindable. |

### NavigationDrawer

`import { NavigationDrawer } from 'omaris'`

MD3 navigation drawer — the sidebar of a dashboard, in all three of the shapes a dashboard needs it in.

#### Use it for

- The sidebar of a dashboard, inside an `AppShellSidebar`: sections, nested
  groups via `submenu`, a logo in `header`, the account row in `footer`.
- The rail. `collapsed` narrows it to icons with labels as tooltips. There is
  no NavigationRail component; this is it. It is bindable, so a button in the
  app bar can toggle it.
- A phone or tablet. `mode="modal"` slides it over the page on a scrim;
  `responsive` picks between the two at `breakpoint`, so one drawer serves
  every screen.
- More destinations than a bar can hold, or destinations that nest.

#### Not for

- Three to five destinations on a phone → [Navigation Bar](/docs/components/navigation-bar).
- Views within one page → [Tabs](/docs/components/tabs). The drawer maps the
  app, not a page.
- A filter panel, an inspector or a form sliding in from an edge →
  [Sheet](/docs/components/sheet).
- A list of actions off a button → [Menu](/docs/components/menu).
- Where the current page sits in a hierarchy → [Breadcrumb](/docs/components/breadcrumb).

#### Do

- Pair `responsive` with `breakpoint={false}` on the `AppShellSidebar`, or
  the shell drops the column before the drawer can go modal.
- Add `bordered` when the drawer sits on the same colour as the page. It
  draws no border on its own.
- Give every item an `icon`. Collapsed, a row without one is an empty pill.
- When modal, bind `open` to a menu button in the `leading` slot of the
  [Top App Bar](/docs/components/top-app-bar) and leave `closeOnNavigate` on.
- Put "Sign out" and the account in `footer`, not among the destinations.

#### Don't

- Leave a phone with nothing. `AppShellSidebar` hides below `md`; without
  `responsive` here or a [Navigation Bar](/docs/components/navigation-bar),
  the phone has no navigation.
- Nest deeper than one `submenu`. A second level means the section wants a
  page of its own with [Tabs](/docs/components/tabs).
- Turn on `resizable` for the look. It is for labels that do not fit at
  `280`. Set `minWidth` so the rail cannot be dragged into.
- Rebuild the modal drawer from a Sheet. `mode="modal"` already has the
  scrim, the drag and close-on-navigate.

#### Pairs with

- [App Shell](/docs/components/app-shell), [Top App Bar](/docs/components/top-app-bar),
  [Navigation Bar](/docs/components/navigation-bar), [Badge](/docs/components/badge),
  [Tooltip](/docs/components/tooltip)

Parts (`classes`): `root` `body` `header` `footer` `dialog` `grip`

| Prop | Type | Notes |
| --- | --- | --- |
| `collapsed?` | `boolean` | Narrow the drawer to its icons. Bindable. Default `false`. |
| `bordered?` | `boolean` | Default `false`. |
| `label?` | `string` | Accessible name. |
| `mode?` | `NavigationDrawerMode` | Beside the content, or over it. `responsive` overrides this. Default `'standard'`. |
| `open?` | `boolean` | Whether a modal drawer is showing. Bindable. Default `false`. |
| `responsive?` | `boolean` | Be a modal drawer on a narrow viewport and a standard one on a wide one. `true` switches at `breakpoint`. Default `false`. |
| `breakpoint?` | `number` | Viewport width, in px, at or above which the drawer stays standard. Default `900`. |
| `closeOnNavigate?` | `boolean` | Close a modal drawer when a destination inside it is chosen. Default `true`. |
| `resizable?` | `boolean` | Let the trailing edge be dragged to set the width. Default `false`. |
| `width?` | `number` | Width in px while expanded. Bindable; only used when `resizable`. Default `280`. Bindable. |
| `minWidth?` | `number` | Default `220`. |
| `maxWidth?` | `number` | Default `420`. |
| `onclose?` | `() => void` |  |
| `class?` | `string` |  |
| `classes?` | `NavigationDrawerClasses` | Per-part Tailwind overrides. `class` still covers the root. |
| `header?` | `Snippet` | Pinned to the top — a logo, a compose button. |
| `footer?` | `Snippet` | Pinned to the bottom — the account row, usually. |
| `children?` | `Snippet` |  |

### NavigationDrawerItem

`import { NavigationDrawerItem } from 'omaris'`

A destination in a `NavigationDrawer`.

Parts (`classes`): `root` `tail` `label` `trailing` `chevron` `submenu` `nest`

| Prop | Type | Notes |
| --- | --- | --- |
| `label?` | `string` | Row text — and the accessible name once the drawer collapses. |
| `selected?` | `boolean` | Default `false`. |
| `badge?` | `number \| string` | Trailing count. |
| `ripple?` | `boolean` | Default `true`. |
| `expanded?` | `boolean` | Whether the nested rows are showing. Bindable. Default `false`. |
| `class?` | `string` |  |
| `classes?` | `NavigationDrawerItemClasses` | Per-part Tailwind overrides. `class` still covers the root. |
| `icon?` | `Snippet` |  |
| `selectedIcon?` | `Snippet` | Icon shown only while selected. |
| `trailing?` | `Snippet` | Trailing slot, in place of `badge`. |
| `submenu?` | `Snippet` | Nested destinations. Their presence turns the row into a group. |
| `children?` | `Snippet` |  |
| `variant?` | `ButtonVariant` | Fill style. MD3's five, plus `link` for inline navigation. |
| `tone?` | `ButtonTone` | Color role the fill style paints with. |
| `size?` | `ButtonSize` | MD3 Expressive heights: 32 / 40 / 56 / 96 / 136dp. |
| `shape?` | `ButtonShape` | Pill (`round`) or MD3 rounded rectangle (`square`). |
| `confetti?` | `boolean \| ConfettiOptions` | Confetti on press. `true` for the default burst, or any `ConfettiOptions` — `confetti={{ preset: 'fireworks' }}`. |
| `loading?` | `boolean` | Grows a spinner in at the start of the button and blocks interaction. The label stays put; only an `icon` button swaps its icon out. |
| `toggle?` | `boolean` | Turns the button into a two-state toggle driven by `pressed`. Ignored when `href` is set — a link has no pressed state. |
| `pressed?` | `boolean` | Selected state of a toggle button. Bindable. |

### NavigationDrawerSection

`import { NavigationDrawerSection } from 'omaris'`

A labelled group of items inside a `NavigationDrawer`.

| Prop | Type | Notes |
| --- | --- | --- |
| `label?` | `string` | Group heading. Hidden (but still announced) when collapsed. |
| `divider?` | `boolean` | Hairline above the group. Default `false`. |
| `class?` | `string` |  |
| `children?` | `Snippet` |  |

### NavigationView

`import { NavigationView } from 'omaris'`

One screen behind one destination. Its `value` must match the item's.

| Prop | Type | Notes |
| --- | --- | --- |
| `value` | `string` | Must match the `value` of the destination that opens it. |
| `keepMounted?` | `boolean` | Keep the view mounted while hidden, in a set that isn't swipeable. Costs memory but preserves scroll position, form state and any in-flight work. Default `false`. |
| `class?` | `string` |  |
| `children?` | `Snippet` |  |

### NavigationViews

`import { NavigationViews } from 'omaris'`

The viewport the screens live in, and the thing a swipe moves.

| Prop | Type | Notes |
| --- | --- | --- |
| `threshold?` | `number` | Fraction of the width a drag has to cover before it counts as a move. A fast flick moves regardless. Default `0.25`. |
| `disabled?` | `boolean` | Turns the gesture off for this viewport, leaving the layout alone. Default `false`. |
| `mouse?` | `boolean` | Drag with a mouse too. Off by default — a swipe is a touch gesture. Default `false`. |
| `lazy?` | `boolean` | Build a screen the first time it is reached, then keep it mounted. Default `false`. |
| `fill?` | `boolean` | Grow to fill the `Navigation` column. Off sizes it by its content. Default `true`. |
| `class?` | `string` |  |
| `children?` | `Snippet` |  |

### NotificationCenter

`import { NotificationCenter } from 'omaris'`

The bell in the top bar, and everything behind it.

#### Use it for

- The bell in an app's top bar: a count of what is unread, and a panel of the
  latest activity behind it — mentions, assignments, approvals, finished jobs.
- An inbox people triage in place: open one to mark it read, "Mark all read"
  for the rest, swipe or × to dismiss.
- A long backlog. Past `virtualize` rows the list is windowed, so a thousand
  notifications open as fast as ten.
- The same feature on a phone and a desktop: a popover under the bell above
  `mobileQuery`, a full-screen view with a back arrow below it.

#### Not for

- Telling someone that what they just did finished → [Toast](/docs/components/toast).
  The center is the history; a toast is the moment.
- A problem with the page they are on → [Alert](/docs/components/alert),
  inline where it applies.
- A full-page inbox with filters, search and bulk selection →
  [List](/docs/components/list) or [Table](/docs/components/table) on a route
  of its own; link to it from `footer`.
- A count on a navigation destination → [Badge](/docs/components/badge) on
  that destination.

#### Do

- Own the list. `onread`, `onreadall` and `ondismiss` are requests: update
  `notifications` in them (and on the server), and the panel follows.
- Give system notifications an `icon` and people's an `avatar`, so the two
  read apart at a glance.
- Write the `title` as the whole sentence — "Amina mentioned you in Checkout"
  — and keep `body` for the quote or the detail.
- Pass `href` for anything with a page behind it; opening it marks it read and
  closes the panel.
- Set `locale` (or `<html lang>`) so the times are in the app's language —
  `ar`, `ckb` and `tr` ship with it, and the digits stay Western in all of
  them.

#### Don't

- Toast a notification and also put it in the center. Pick one: the moment,
  or the history.
- Leave out `ondismiss` and then expect a swipe to do anything — without it
  rows cannot be dismissed, by design.
- Put actions inside a row (Approve, Reply). A row is one press; the action
  belongs on the page `href` opens.
- Mark everything read when the panel opens. People open it to see what is
  new; reading is their call.

#### Pairs with

- [Top App Bar](/docs/components/top-app-bar), [Badge](/docs/components/badge),
  [Avatar](/docs/components/avatar), [Virtual List](/docs/components/virtual-list),
  [Empty](/docs/components/empty)

Parts (`classes`): `root` `bell` `badge` `panel` `screen` `header` `back` `heading` `markAll` `tabs` `tabPanel` `list` `item` `row` `dot` `media` `icon` `text` `title` `body` `time` `dismiss` `empty` `footer`

| Prop | Type | Notes |
| --- | --- | --- |
| `notifications` | `NotificationItem[]` |  |
| `open?` | `boolean` | Whether the panel is open. Bindable. Default `false`. |
| `tab?` | `NotificationTab` | The tab showing. Bindable. Default `'all'`. |
| `title?` | `string` | The panel's heading, and its accessible name. Default `'Notifications'`. |
| `label?` | `string` | The bell's accessible name. The unread count is added to it. Default `'Notifications'`. |
| `onread?` | `(id: string) => void` | A notification was opened, or swiped the other way: mark it read. |
| `onreadall?` | `() => void` | "Mark all read" was pressed. Without it the button is not drawn. |
| `ondismiss?` | `(id: string) => void` | A notification was dismissed — swiped away, or its × pressed. Called once the row has folded shut. Without it rows cannot be dismissed. |
| `onselect?` | `(notification: NotificationItem) => void` | A notification was pressed, after `onread`. |
| `empty?` | `Snippet<[NotificationTab]>` | Drawn when the tab has nothing in it. Handed the tab. |
| `footer?` | `Snippet<[{ close: () => void }]>` | Along the bottom of the panel — a "See all" link, say. |
| `icon?` | `Snippet` | Replaces the bell glyph. |
| `locale?` | `string` | Language for the relative times. Defaults to `<html lang>`. |
| `max?` | `number` | The count stops at this and adds a `+`. Default `99`. |
| `virtualize?` | `number` | Past this many rows the list is windowed. Default `50`. |
| `align?` | `AnchorAlign` | Which edge of the bell the popover lines up with. Default `'end'`. |
| `mobileQuery?` | `string` | What counts as a phone — there the panel is a full-screen view. Default `'(max-width: 639px)'`. |
| `markAllLabel?` | `string` | Labels, for another language. Default `'Mark all read'`. |
| `allLabel?` | `string` | Default `'All'`. |
| `unreadLabel?` | `string` | Default `'Unread'`. |
| `dismissLabel?` | `string` | Default `'Dismiss'`. |
| `readLabel?` | `string` | Default `'Read'`. |
| `closeLabel?` | `string` | The back arrow that closes the full-screen view on a phone. Default `'Back'`. |
| `class?` | `string` |  |
| `classes?` | `NotificationCenterClasses` | Per-part Tailwind overrides. `class` still covers the root. |

### NumberInput

`import { NumberInput } from 'omaris'`

A number field that is a text field underneath.

#### Use it for

- A quantity, a count, a seat or guest number: anything adjusted by one more
  often than retyped. `layout="split"` puts a stepper either side of the
  value, the easiest shape to hit with a thumb.
- A bounded setting like a page size, a retry count or an hour. Use `min`,
  `max`, and `wrap` when the range is a cycle.
- An optional number. Clearing the field gives `null`, not `0`, so "no limit"
  and "a limit of zero" stay different.
- A measurement, with `precision` and a `suffix`: `2.5 kg`, `30 %`.
- The same bounded number on a phone. `picker` leaves the desktop field alone
  and turns the touch one into a tap that opens a wheel, instead of a keypad
  covering half the screen.

#### Not for

- Money → [Price Input](/docs/components/price-input), which knows the
  currency's decimals, symbol side and step.
- A number chosen by feel, like a volume or a threshold →
  [Slider](/docs/components/slider).
- A number from a short fixed set → [Select](/docs/components/select) or
  [Segmented Button](/docs/components/segmented-button).
- Spinning through a long range on a touch screen with no field to fall back
  to → [Picker](/docs/components/picker) on its own. `picker` here is the same
  wheel behind a field a mouse can still type into.
- Free text with digits, like an order number or a postcode →
  [Text Field](/docs/components/input) with `format="numeric"`.

#### Do

- Give it a `min` when the number cannot go below one. The − stepper then
  stops, and the first + on an empty field starts at the minimum.
- Set `precision` to the decimals the value really has. The field rounds to
  it on blur and `step` moves in it.
- Use `layout="stacked"` in a dense table row and `layout="none"` when the
  number is always typed, like an amount or a year. Holding a stepper
  accelerates and multiplies the step after twenty repeats.
- Leave `group` on for anything over a thousand. It formats only while the
  field is idle, so the caret never moves.
- Give `picker` both a `min` and a `max`. Without ends the field stays a
  field.

#### Don't

- Turn `wheel` on inside a scrolling page. A wheel over a focused field would
  change the value instead of scrolling past, the bug `<input type="number">`
  is most disliked for.
- Use it as a slider with a hundred steps of one.
- Put `picker` on a range thousands of steps wide. Every row is a real
  element; past a thousand the field stays a field.
- Set `clamp={false}` and then show the number as valid. To report an
  out-of-range value instead of correcting it, pair it with `invalid` and a
  `supportingText`.
- Hide the label. `aria-label` is the fallback, not the plan.

#### Pairs with

- [Text Field](/docs/components/input), [Price Input](/docs/components/price-input),
  [Picker](/docs/components/picker), [Slider](/docs/components/slider),
  [Button Group](/docs/components/button-group)

Parts (`classes`): `root` `field` `control` `label` `adornment` `affix` `action` `support` `counter` `step` `steppers`

| Prop | Type | Notes |
| --- | --- | --- |
| `value?` | `number \| null` | The number. `null` when the field is empty — not `0`. Bindable. Default `null`. |
| `layout?` | `NumberInputLayout` | Where the steppers sit, or `none` for a bare field. Default `'trailing'`. |
| `emphasis?` | `NumberInputEmphasis` | How loud the steppers are. One of `plain`, `tonal`. Default `'plain'`. |
| `variant?` | `InputVariant` | Default `'outline'`. |
| `size?` | `InputSize` | Default `'default'`. |
| `min?` | `number` | Lower bound. The − stepper stops here, and `clamp` snaps to it. |
| `max?` | `number` | Upper bound. |
| `step?` | `number` | One press of a stepper, or one arrow key. Shift multiplies it by 10. Default `1`. |
| `precision?` | `number` | Decimal places. `0` — the default — makes it an integer field. Default `0`. |
| `group?` | `boolean` | Group the thousands while the field is idle — `12,500`. Default `true`. |
| `clamp?` | `boolean` | Snap into `[min, max]` when the field is left. Default `true`. |
| `wrap?` | `boolean` | Wrap past the bounds instead of stopping — 12 → 1 on an hour field. Needs both `min` and `max`. Default `false`. |
| `wheel?` | `boolean` | Change the value on a wheel over the focused field. Off by default: a page that scrolls under the pointer must not edit the form. Default `false`. |
| `picker?` | `boolean \| 'always'` | Collect the number on a wheel instead of a keyboard when the pointer is a finger. Default `false`. |
| `pickerTitle?` | `string` | Title on the picker sheet. Defaults to the field's own label. |
| `pickerConfirmLabel?` | `string` | Confirm button on the picker sheet. Default `'Done'`. |
| `pickerCancelLabel?` | `string` | Cancel button on the picker sheet. Default `'Cancel'`. |
| `formatValue?` | `(value: number) => string` | Renders the settled value. Replaces the built-in grouping. |
| `label?` | `string` |  |
| `supportingText?` | `string` | Helper line under the field. Becomes the error text when `invalid`. |
| `invalid?` | `boolean` | Inside a `Field`, defaults to the field's. |
| `disabled?` | `boolean` | Inside a `Field`, defaults to the field's. |
| `readonly?` | `boolean` | Default `false`. |
| `required?` | `boolean` | Inside a `Field`, defaults to the field's. |
| `placeholder?` | `string` |  |
| `prefix?` | `string` | Flat text glued to the start of the value — "$", "#". |
| `suffix?` | `string` | Flat text glued to the end — "kg", "%". |
| `name?` | `string` | Posts the raw number, not the formatted text, under this name. |
| `id?` | `string` |  |
| `aria-label?` | `string` |  |
| `aria-describedby?` | `string` |  |
| `decrementLabel?` | `string` | Accessible label for the − stepper. Default `'Decrease'`. |
| `incrementLabel?` | `string` | Accessible label for the + stepper. Default `'Increase'`. |
| `haptics?` | `boolean` | Play a tick on each step once `haptics.enabled` is on. Default `true`. |
| `supporting?` | `Snippet` | Richer supporting text — a link, a hint. |
| `onchange?` | `(value: number \| null) => void` | Fires once per settled value, after clamping. |
| `class?` | `string` |  |
| `classes?` | `NumberInputClasses` | Per-part Tailwind overrides. `class` still covers the root. |
| `ref?` | `HTMLInputElement \| null` | Default `null`. Bindable. |

### NumberPicker

`import { NumberPicker } from 'omaris'`

One wheel over a run of numbers.

Parts (`classes`): `root` `header` `stage` `band` `wheels` `actions` `action`

| Prop | Type | Notes |
| --- | --- | --- |
| `value?` | `number` | The number. Bindable. Default `0`. |
| `min?` | `number` | Default `0`. |
| `max?` | `number` | Default `100`. |
| `step?` | `number` | The gap between rows. Default `1`. |
| `precision?` | `number` | Decimal places on each row's label. Default `0`. |
| `unit?` | `string` | Drawn small beside every row — "kg", "%". |
| `loop?` | `boolean` | Spin past the ends and come back round. Default `false`. |
| `label?` | `string` | Accessible name for the wheel. Default `'Value'`. |
| `format?` | `(value: number) => string` | Replaces the row's text. |
| `onchange?` | `(value: number) => void` |  |
| `columnClasses?` | `PickerColumnClasses` | Per-part overrides for the wheel itself. |
| `classes?` | `PickerClasses` |  |
| `size?` | `PickerSize` | Row height and type scale. |
| `surface?` | `PickerSurface` | How the frame is drawn. |
| `visible?` | `number` | Rows on screen at once. Rounded up to the next odd number. |
| `title?` | `string` | A title above the wheels. |
| `disabled?` | `boolean` | Disables every wheel inside. |
| `haptics?` | `boolean` | Play a tick as each row passes the centre, once haptics are on. |
| `onconfirm?` | `() => void` | Renders the action row. Called with the value already committed. |
| `oncancel?` | `() => void` | Renders a cancel button beside it. |
| `confirmLabel?` | `string` |  |
| `cancelLabel?` | `string` |  |
| `footer?` | `Snippet` | Replaces the built-in action row. |
| `class?` | `string` |  |

### OtpInput

`import { OtpInput } from 'omaris'`

The one-time code field.

#### Use it for

- The six digits from an SMS, an email or an authenticator app, on the screen
  whose whole job is that code. `autofocus` belongs here and almost nowhere
  else.
- A short recovery or invite code. Use `pattern="alphanumeric"` with
  `uppercase`, and `groups` where the code is printed with a break.
- A numeric PIN, with `mask` so it cannot be read over a shoulder.
- Any field where the length is fixed and known, and seeing how much is left
  to type helps.

#### Not for

- A code of unknown or variable length → [Text Field](/docs/components/input)
  with `format="numeric"`. Boxes promise a length.
- A password → a `Text Field` with `type="password"`, which gets the reveal
  toggle and the password manager.
- Anything longer than about eight characters. The row stops fitting a phone.
- A quantity → [Number Input](/docs/components/number-input).

#### Do

- Handle `oncomplete` and submit from it. A filled code should not need a
  button press.
- Set `pattern` to what the code really is. Everything else is dropped on the
  way in, typed or pasted, so a code copied with spaces or dashes still lands.
- Match `groups` to how the code is written elsewhere: `[3, 3]` for `483-920`.
  It has to add up to `length`.
- Show the failure on the field. `invalid` turns it destructive and shakes it
  once. Say what to do next in text beneath it.
- Leave `autocomplete="one-time-code"` alone. It is what makes iOS offer the
  code above the keyboard.

#### Don't

- Build the row out of one input per box. Paste, autofill, select-all and
  backspace across a boundary all break. This component is one input under
  the boxes for that reason.
- Clear the field on a wrong code. Tapping a box puts the caret in it and the
  next keystroke replaces that character, so one wrong digit costs one key.
- Disable paste. Every code arrives by being copied from somewhere.
- Put two on one screen. Only one code is entered at a time.
- Wrap it in something that flips direction. The row pins itself to `ltr`
  whatever the page does; a code reads left to right in every language.

#### Pairs with

- [Text Field](/docs/components/input), [Button](/docs/components/button),
  [Alert](/docs/components/alert), [Dialog](/docs/components/dialog)

Parts (`classes`): `slot` `char` `caret` `separator` `control`

| Prop | Type | Notes |
| --- | --- | --- |
| `value?` | `string` | The code so far. Bindable, and never longer than `length`. Default `''`. Bindable. |
| `length?` | `number` | How many characters the code has. Default `6`. |
| `variant?` | `OtpInputVariant` | One of `outline`, `filled`, `underline`. Default `'outline'`. |
| `size?` | `OtpInputSize` | One of `sm`, `md`, `lg`. Default `'md'`. |
| `pattern?` | `OtpPattern` | What the field accepts. Anything else is dropped, typed or pasted. Default `'digits'`. |
| `uppercase?` | `boolean` | Upper-case every letter as it lands — codes are usually read aloud. Default `false`. |
| `groups?` | `number[]` | Split the row — `[3, 3]` for `123-456`. Must add up to `length`. |
| `separator?` | `string` | What sits between two groups. Default `'–'`. |
| `mask?` | `boolean` | Show dots instead of the characters. Default `false`. |
| `invalid?` | `boolean` | Marks the row invalid and shakes it once. Inside a `Field`, defaults to the field's. |
| `disabled?` | `boolean` | Inside a `Field`, defaults to the field's. |
| `readonly?` | `boolean` | Default `false`. |
| `autofocus?` | `boolean` | Take focus on mount — right on a screen whose only job is the code. Default `false`. |
| `label?` | `string` | Accessible name for the whole row. "Verification code" when omitted — or, inside a `Field`, the field's own label. |
| `oncomplete?` | `(value: string) => void` | Fires the moment the last character lands, typed or pasted. |
| `onchange?` | `(value: string) => void` | Fires on every change, complete or not. |
| `slot?` | `Snippet<[{ char: string; index: number; active: boolean; filled: boolean }]>` | Replaces a box's contents. Gets the character and the box's state. |
| `class?` | `string` |  |
| `classes?` | `OtpInputClasses` | Per-part Tailwind overrides. `class` still covers the root. |
| `ref?` | `HTMLInputElement \| null` | Default `null`. Bindable. |

### PageTransition

`import { PageTransition } from 'omaris'`

Page transitions — off unless you ask for one.

#### Use it for

- Route changes that should feel like an app. In `+layout.svelte`, set
  `key={page.url.pathname}` and `transition="shared-x"`. A wizard or a
  settings screen keys on the step instead of the URL.
- A stack like a phone's. `transition="push"` with `direction="auto"` slides
  a deeper page in over the old one and plays the reverse on the way back.
- Going back that reads as going back. `direction="auto"` keeps the keys it
  has seen as a stack, so a Back button, a breadcrumb and a swipe back all
  play backward with no wiring.
- Pages of different heights. The leaving page is taken out of flow and the
  container clips, so the document never grows a scrollbar.
- A keyboard that should follow. `focus` moves focus to the arriving page;
  `scroll="top"` resets the scroll like a native screen.

#### Not for

- An app that did not ask for it → leave `transition={false}`, the default,
  which renders the children with no wrapper and no cost.
- A section that opens and closes → [Accordion](/docs/components/accordion),
  or a Svelte `transition:` on the block.
- Covering a slow load → [Skeleton](/docs/components/skeleton) or
  [Progress](/docs/components/progress). A transition does not hide waiting.

#### Do

- Pick one preset and keep it. `shared-x` for siblings, `push` for a stack,
  `shared-y`, `zoom` or `scale` for parent to child, `fade-through` for
  unrelated destinations, `fade` or `dissolve` for the least motion.
- Leave `duration` alone unless you disagree with the preset. `push` is
  longer than `fade` because it travels further.
- Prefer `direction="auto"`. Set it by hand only where the keys are not a
  stack, like a tab strip.
- Key on the pathname, not the whole URL, so a query-string change does not
  replay the page.
- Trust the presets under RTL. `shared-x`, `slide`, `push` and `swap` read
  the writing direction, so forward is leftward in Arabic.

#### Don't

- Put one in every layout. Use one, at the outermost layout that changes.
- Wrap a `TopAppBar` or a `NavigationDrawer` in it. Only the page moves.
- Key on an object. A new object every render is a transition every render.
- Use it for a change inside a page, like a filter or a sort.
- Use `flip` twice. It draws attention to itself.

#### Pairs with

- [App Shell](/docs/components/app-shell), [Top App Bar](/docs/components/top-app-bar),
  [Navigation Bar](/docs/components/navigation-bar), [Tabs](/docs/components/tabs)

| Prop | Type | Notes |
| --- | --- | --- |
| `key?` | `unknown` | Change this to run a transition — `page.url.pathname`, usually. |
| `transition?` | `PageTransitionName \| false` | The pattern, or `false` (the default) for none at all. Default `false`. |
| `direction?` | `PageTransitionDirection \| 'auto'` | Which way the axis patterns travel. `auto` reads it off the keys it has seen: a new one is forward, one it has been to before is a Back. Default `'forward'`. |
| `duration?` | `number` | Total time for the pair, in ms. Defaults to what the pattern wants. |
| `clip?` | `boolean` | Clip the travel while a transition runs. On unless a page has something that has to escape the container mid-flight. Default `true`. |
| `scroll?` | `'keep' \| 'top'` | Put the scroll back to the top as the new page arrives. `'top'` scrolls the nearest scrollable ancestor, which is the app frame in a dashboard and the window on an ordinary page. Default `'keep'`. |
| `focus?` | `boolean` | Move focus to the arriving page, the way a native screen change does, so a keyboard lands on the new page rather than back at the top of the document. Default `false`. |
| `onstart?` | `(direction: PageTransitionDirection) => void` | Called as a pair starts, with the direction it is playing. |
| `onend?` | `() => void` | Called once the pair has landed. |
| `children` | `Snippet` | The page. |
| `class?` | `string` |  |

### Pagination

`import { Pagination } from 'omaris'`

Pagination.

#### Use it for

- The footer of a list whose rows come from a server a page at a time.
  `page`, `count`, and `total` with `perPage` for the "1–10 of 240" line.
- Pages people jump between rather than walk through: months of a report,
  chapters.
- A narrow footer or a phone. `compact` keeps previous, next and the count.

#### Not for

- A [Table](/docs/components/table)'s own rows → its `pagination` prop draws
  this footer, and `manual` hands the paging to your server.
- A feed that keeps going → a "Load more" [Button](/docs/components/button)
  under the list, or scrolling.
- Slides, photos or cards to swipe → [Carousel](/docs/components/carousel).
- Switching between views of one thing → [Tabs](/docs/components/tabs).

#### Do

- Reset `page` to `1` when a filter, a sort or the query changes.
- Pass `total` and `perPage`. The summary says whether the search worked.
- Keep the page in the URL, so back and refresh land where the person was.
- Leave `siblings` and `boundaries` at `1`. The row keeps a fixed width
  either way; more numbers is more to read.

#### Don't

- Use `compact` on a desktop footer where the numbers fit.
- Change `perPage` without recomputing `count`, or the last pages point at
  nothing.
- Render it for a single page. Hide it once `count` is `1`.

#### Pairs with

- [Table](/docs/components/table), [List](/docs/components/list),
  [Empty](/docs/components/empty), [Skeleton](/docs/components/skeleton),
  [Select](/docs/components/select)

Parts (`classes`): `root` `indicator` `page` `current` `ellipsis` `summary` `meta` `perPage`

| Prop | Type | Notes |
| --- | --- | --- |
| `page?` | `number` | Current page, 1-based. Bindable. Default `1`. |
| `count` | `number` | Total number of pages. |
| `size?` | `PaginationSize` | One of `sm`, `md`. Default `'md'`. |
| `siblings?` | `number` | How many numbers to show around the current page. Default `1`. |
| `boundaries?` | `number` | How many to always show at each end. Default `1`. |
| `compact?` | `boolean` | Hide the number list, leaving just previous/next. Default `false`. |
| `total?` | `number` | Total rows, for the "1–10 of 240" summary. |
| `perPage?` | `number` | Rows per page, for the summary. Bindable, when `perPageOptions` lets it change. Bindable. |
| `perPageOptions?` | `number[]` | Offer these as a "Rows per page" choice beside the summary — `[10, 25, 50, 100]`. Changing it keeps the first visible row on screen by moving `page` to wherever that row now lands. |
| `perPageLabel?` | `string` | Label for the rows-per-page choice. Default `'Rows per page'`. |
| `onpagechange?` | `(page: number) => void` |  |
| `onperpagechange?` | `(perPage: number) => void` | Called when the rows-per-page choice changes. |
| `label?` | `string` | Accessible name. Default `'Pagination'`. |
| `class?` | `string` |  |
| `classes?` | `PaginationClasses` | Per-part Tailwind overrides. `class` still covers the root. |

### PhoneInput

`import { PhoneInput } from 'omaris'`

A phone field that stores E.164 and lets people type a national number.

#### Use it for

- A phone number with a country: sign-up, a customer record, a delivery
  contact. `value` is E.164, like `+9647701234567`, ready for an SMS or
  WhatsApp API without parsing.
- A form where most numbers are from one place. `country` defaults to `IQ`
  and the picker covers the rest.
- Pasted numbers in any shape. `+90 …`, `0090 …` and `00964 …` all switch
  the country and keep the digits.

#### Not for

- An Iraqi mobile number that never leaves the country → [Text Field](/docs/components/input)
  with `format="phone"`, which groups it as `0770 123 4567` and stores the
  local form.
- A verification code → [Text Field](/docs/components/input) with
  `format="code"` or `numeric`.
- An extension, a short code or a PIN → [Text Field](/docs/components/input)
  with `format="integer"`.
- A number that is shown, not edited → [Text](/docs/components/text).

#### Do

- Leave `validate` on. The incomplete message appears on blur, once, not on
  every keystroke.
- Pass `countries` limited to the ones you serve. The picker gets shorter and
  a pasted number is matched against fewer dial codes.
- Give it a `name` in a plain `<form>`. The E.164 value is what is posted.
- `bind:country` when the rest of the form follows it: the address country,
  the currency of a [Price Input](/docs/components/price-input).

#### Don't

- Set your own `placeholder` unless you must. The country's example number is
  the placeholder, and it changes with the country.
- Store the formatted text. `value` is the canonical string; the national
  formatting is for the eye.
- Add your own regex with `invalid`. The field knows each country's length;
  a second rule usually rejects a real number.

#### Pairs with

- [Text Field](/docs/components/input), [Select](/docs/components/select),
  [Price Input](/docs/components/price-input), [Button](/docs/components/button)

Parts (`classes`): `root` `field` `control` `label` `adornment` `affix` `action` `support` `counter`

| Prop | Type | Notes |
| --- | --- | --- |
| `value?` | `string` | The number in E.164 — `+9647701234567`. Bindable, `''` when empty. Default `''`. Bindable. |
| `country?` | `string` | Selected country, as an ISO code. Bindable. Default `'IQ'`. |
| `countries?` | `Country[]` | Countries offered in the picker. Default `COUNTRIES`. |
| `variant?` | `InputVariant` | Default `'outline'`. |
| `size?` | `InputSize` | Default `'default'`. |
| `label?` | `string` |  |
| `supportingText?` | `string` |  |
| `invalid?` | `boolean` | Forces the error state. Otherwise the field checks itself on blur — and, inside a `Field`, is invalid while the field is. |
| `incompleteMessage?` | `string` | Shown when a half-typed number is left behind. Default `'That number looks incomplete.'`. |
| `validate?` | `boolean` | Turn off the on-blur completeness check. Default `true`. |
| `disabled?` | `boolean` | Inside a `Field`, defaults to the field's. |
| `readonly?` | `boolean` | Default `false`. |
| `required?` | `boolean` | Inside a `Field`, defaults to the field's. |
| `placeholder?` | `string` | Overrides the country's own example number. |
| `id?` | `string` |  |
| `name?` | `string` | Posts the E.164 value under this name. |
| `class?` | `string` |  |
| `classes?` | `InputClasses` | Per-part Tailwind overrides, forwarded to the `Input` underneath. |
| `ref?` | `HTMLInputElement \| null` | Default `null`. Bindable. |

### Picker

`import { Picker } from 'omaris'`

The frame a set of wheels sits in: the selection band across the middle, the fade at the top and bottom edges, and — when you give it `onconfirm` — the cancel/confirm row under them.

Parts (`classes`): `root` `header` `stage` `band` `wheels` `actions` `action`

| Prop | Type | Notes |
| --- | --- | --- |
| `size?` | `PickerSize` | Row height and type scale. One of `sm`, `md`, `lg`. Default `'md'`. |
| `surface?` | `PickerSurface` | How the frame is drawn. One of `plain`, `card`, `filled`. Default `'plain'`. |
| `visible?` | `number` | Rows on screen at once. Rounded up to the next odd number. |
| `title?` | `string` | A title above the wheels. |
| `disabled?` | `boolean` | Disables every wheel inside. Default `false`. |
| `haptics?` | `boolean` | Play a tick as each row passes the centre, once haptics are on. Default `true`. |
| `onconfirm?` | `() => void` | Renders the action row. Called with the value already committed. |
| `oncancel?` | `() => void` | Renders a cancel button beside it. |
| `confirmLabel?` | `string` | Default `'OK'`. |
| `cancelLabel?` | `string` | Default `'Cancel'`. |
| `footer?` | `Snippet` | Replaces the built-in action row. |
| `children?` | `Snippet` | The wheels — one `PickerColumn` each. |
| `class?` | `string` |  |
| `classes?` | `PickerClasses` | Per-part Tailwind overrides. `class` still covers the root. |

### PickerColumn

`import { PickerColumn } from 'omaris'`

One wheel.

Parts (`classes`): `root` `item` `face` `unit`

| Prop | Type | Notes |
| --- | --- | --- |
| `options` | `readonly (PickerOption<T> \| string)[]` | The rows. Strings are shorthand for `{ value: s, label: s }`. |
| `value?` | `T` | The selected row's value. Bindable. Default `undefined as T`. |
| `label?` | `string` | Accessible name for the wheel — "Hour", "Month". Required in practice. |
| `caption?` | `string` | A caption above the wheel. Rarely needed; the value usually says it. |
| `loop?` | `boolean` | Spin past the ends and come back round. For a cycle — hours, minutes, months — and wrong for a bounded range like a year. Default `false`. |
| `unit?` | `string` | A unit drawn small beside every row — "kg", "min". |
| `size?` | `PickerSize` | Overrides the size inherited from the `Picker`. One of `sm`, `md`, `lg`. |
| `visible?` | `number` | Overrides the visible row count inherited from the `Picker`. |
| `disabled?` | `boolean` | Default `false`. |
| `hug?` | `boolean` | Let the wheel size itself to its widest row instead of sharing the width. Default `false`. |
| `onchange?` | `(value: T) => void` | Fires once the wheel settles, not on every row it passes. |
| `row?` | `Snippet<[PickerOption<T>, boolean]>` | Replaces the row's text. Gets the option and whether it is centred. |
| `class?` | `string` |  |
| `classes?` | `PickerColumnClasses` | Per-part Tailwind overrides. `class` still covers the root. |

### PieChart

`import { PieChart } from 'omaris/chart'`

Pie and donut chart.

| Prop | Type | Notes |
| --- | --- | --- |
| `data` | `T[]` |  |
| `label?` | `Field<T>` | Field naming each slice. Defaults to `row.label`. Default `'label'`. |
| `value?` | `Field<T>` | Field holding each slice's size. Defaults to `row.value`. Default `'value'`. |
| `donut?` | `boolean \| number` | Cut the middle out. A number is the hole's radius in px. Default `false`. |
| `height?` | `number \| string` | Plot height. A number is px; a string is any CSS length. Default `260`. |
| `legend?` | `ChartLegend` | `true` toggles a slice off on click; `'isolate'` shows it alone. Default `false`. |
| `tooltip?` | `boolean` | Default `true`. |
| `labels?` | `boolean` | Print each slice's value on it. Default `false`. |
| `colors?` | `readonly string[]` | Palette override, cycled across the slices. Default `CHART_COLORS`. |
| `title?` | `string` | Accessible description of what the chart shows. |
| `class?` | `string` |  |
| `centre?` | `Snippet` | Content for the middle of a donut — a total, usually. |
| `empty?` | `Snippet` |  |
| `emptyText?` | `string` |  |
| `error?` | `boolean \| string \| Error` | Something went wrong. Truthy puts the chart into its error state; a string or an `Error` supplies the message. |
| `errorText?` | `string` | The message, when `error` is just `true`. |
| `errorState?` | `Snippet<[{ message: string }]>` | Replaces the whole error state. |
| `onRetry?` | `() => void` | Offers a "Try again" button in the error state. |
| `csv?` | `boolean \| string` | Offer the plotted rows as a CSV download, from a button in the corner. A string names the file. Default `false`. |
| `csvColumns?` | `(string \| { key: string; label?: string; value?: (row: T) => unknown })[]` | Which fields the download writes, in order. Defaults to every field. |

### Popover

`import { Popover } from 'omaris'`

A panel that hangs off a trigger and holds whatever you put in it — a filter form, a colour picker, a profile card, a confirmation.

#### Use it for

- A small form off a button: filters, a date range, "add member", a rename
  field. `title` names it, `footer` holds Apply and Cancel, and both snippets
  are handed `close`.
- A detail card that would clutter the page: a user preview on `@name`, a
  commit summary, what a metric counts. `openOn="hover"` waits before opening
  and survives the move from the trigger into the panel.
- A confirmation that should not take over the screen: one line and a
  destructive button, anchored to the row it is about.
- A colour, icon or emoji picker off the control it fills. `size="auto"`
  gives a panel with no width and no padding of its own.
- Anything anchored that must escape a scroll container or a table cell. It
  is portalled, flips when out of room, and shrinks and scrolls instead of
  hanging off the bottom of the screen.

#### Not for

- A list of actions → [Menu](/docs/components/menu). One value from a list →
  [Select](/docs/components/select), or [Combobox](/docs/components/combobox)
  when it is long enough to search.
- A sentence describing a control → [Tooltip](/docs/components/tooltip). A
  popover is focusable and dismissible, too much for four words.
- A decision the page must wait for → [Dialog](/docs/components/dialog). A
  popover is non-modal and light-dismisses, so unsaved input can vanish on an
  outside click.
- A form long enough to scroll, or one that needs the whole width →
  [Sheet](/docs/components/sheet).
- Something that just happened → [Toast](/docs/components/toast).

#### Do

- Spread the `trigger` props onto the real control: a `Button`, an
  `IconButton`, a table cell button. They carry `aria-expanded` and
  `aria-controls`.
- Give it a `title` when it holds more than a sentence. It becomes the
  panel's accessible name.
- Close it from inside with the `close` you are handed, so Apply and Cancel
  both return focus to the trigger.
- Turn `arrow` on when several triggers sit close together.
- Use `size="auto"` plus `class` when the panel has its own layout, like a
  coloured header. Use `matchWidth` under a full-width trigger, and give the
  wrapper the width with `classes={{ trigger: 'w-full' }}`.

#### Don't

- Nest one inside a [Dialog](/docs/components/dialog) that also traps focus.
  Pick one owner of focus, or set `trapFocus={false}` on the popover.
- Put a long form in it. It caps at 28rem and scrolls, which means the
  content wants a [Sheet](/docs/components/sheet).
- Rely on `openOn="hover"` for anything essential. A touch screen has no
  hover.
- Open one on scroll or on load. Without a gesture, people cannot tell where
  it came from.
- Set `autofocus={false}` on a click popover with fields in it. The panel
  opens and the keyboard stays behind it.

#### Pairs with

- [Button](/docs/components/button), [Icon Button](/docs/components/icon-button),
  [Menu](/docs/components/menu), [Tooltip](/docs/components/tooltip),
  [Input](/docs/components/input), [Checkbox](/docs/components/checkbox),
  [Text](/docs/components/text)

Parts (`classes`): `trigger` `surface` `content` `header` `title` `description` `footer` `arrow`

| Prop | Type | Notes |
| --- | --- | --- |
| `open?` | `boolean` | Bindable. Default `false`. |
| `onOpenChange?` | `(open: boolean) => void` | Called whenever it opens or closes, however that happened. |
| `openOn?` | `PopoverTrigger` | The gesture that opens it. Default `'click'`. |
| `side?` | `AnchorSide` | Which side to prefer. Flips when there isn't room. Default `'bottom'`. |
| `align?` | `AnchorAlign` | Default `'center'`. |
| `offset?` | `number` | Gap between the trigger and the panel, in px. Default `8`. |
| `size?` | `PopoverSize` | One of `sm`, `md`, `lg`, `auto`. Default `'md'`. |
| `matchWidth?` | `boolean` | Make the panel at least as wide as its trigger. Default `false`. |
| `arrow?` | `boolean` | Show the pointer. It tracks the trigger, not the panel's middle. Default `false`. |
| `title?` | `string` | Heading, and the panel's accessible name. |
| `description?` | `string` | A line under the title. |
| `disabled?` | `boolean` | Opening is a no-op, and an open one closes. Default `false`. |
| `delay?` | `number` | Delay before a hover opens it, in ms. Default `120`. |
| `closeDelay?` | `number` | Grace period before a hover closes it — the trip to the panel. Default `140`. |
| `closeOnEscape?` | `boolean` | Escape closes it. Default `true`. |
| `closeOnOutsideClick?` | `boolean` | A press outside closes it. Default `true`. |
| `trapFocus?` | `boolean` | Keep Tab inside the panel while it is open. Defaults to on for `click` and `manual`, off for the pointer-driven modes. |
| `autofocus?` | `boolean \| string` | What to focus on open: the first focusable thing (`true`), the panel itself (`false`), or a CSS selector for one element inside it. Defaults to `true` for `click` and `manual`, `false` otherwise. |
| `portalTo?` | `PortalTarget` | Where the panel is portalled. The body, by default. |
| `mobileSheet?` | `boolean` | On a phone, rise from the bottom edge as a sheet — full width, a scrim behind, dragged down to dismiss — instead of hanging off the trigger. On by default for a popover opened by a press; `false` keeps it anchored on every screen. |
| `class?` | `string` | Merged onto the panel, so `class="w-80"` resizes it. |
| `classes?` | `PopoverClasses` | Per-part Tailwind overrides. `class` still covers the panel. |
| `trigger?` | `Snippet<[PopoverTriggerProps]>` | Receives the props to spread onto the opening control. |
| `children?` | `Snippet<[PopoverBody]>` | The panel's contents. |
| `footer?` | `Snippet<[PopoverBody]>` | Buttons along the bottom, separated from the content. |
| `aria-haspopup` | `'dialog'` |  |
| `aria-expanded` | `boolean` |  |
| `aria-controls` | `string \| undefined` |  |
| `onclick` | `(event: MouseEvent) => void` |  |
| `onkeydown` | `(event: KeyboardEvent) => void` |  |

### PriceInput

`import { PriceInput } from 'omaris'`

A money field: the currency decides the symbol, which side it sits on, how many decimals are allowed and how much one step is worth.

#### Use it for

- An amount of money: a menu price, a tip, a budget, a payout. `value` is a
  number, `null` when empty, so nothing downstream parses a string.
- More than one currency. Pass `currencies` and the picker appears; `rates`
  and `secondary` draw the "≈ $12.50" line under an IQD amount.
- One-tap amounts. `presets` for a tip, a top-up, a donation.
- A bounded amount. `min`, `max` and `clamp` pull a wild value back on blur
  instead of refusing the keystroke.

#### Not for

- A quantity, a percentage or a weight → [Text Field](/docs/components/input)
  with `format="integer"`, `percent` or `decimal` and a `suffix`.
- An amount chosen from a range by feel → [Slider](/docs/components/slider).
- A price on a card or a total in a table → [Text](/docs/components/text).
  Format it with `Intl.NumberFormat` and the same currency code.
- A number with no currency → [Text Field](/docs/components/input) with
  `format="decimal"`.

#### Do

- Let the currency set the decimals and the step. IQD takes none and steps
  in thousands; USD takes two. Set `step` only when the business rule is
  stricter.
- Keep `presets` in the current currency, in round amounts people pay.
- Give it a `name` in a plain `<form>`. The raw number is posted, not the
  formatted text.
- Replace the approximation line with `hint` when there is something more
  useful to say: the fee, the balance after.

#### Don't

- Show the currency picker for one currency. Pass a single entry in
  `currencies` and it becomes a label.
- Mix currencies in one form without `rates`. Two amounts in different units
  cannot be compared.
- Round `value` for display and store the rounded one. `value` is what was
  typed; formatting belongs to the field.

#### Pairs with

- [Text Field](/docs/components/input), [Select](/docs/components/select),
  [Phone Input](/docs/components/phone-input), [Slider](/docs/components/slider),
  [Table](/docs/components/table)

Parts (`classes`): `root` `field` `control` `label` `adornment` `affix` `action` `support` `counter`

| Prop | Type | Notes |
| --- | --- | --- |
| `value?` | `number \| null` | The amount, as a number. Bindable, and null when the field is empty. Default `null`. Bindable. |
| `currency?` | `string` | Selected currency code. Bindable. Default `'IQD'`. |
| `currencies?` | `Currency[]` | Currencies offered. More than one renders the picker. Default `DEFAULT_CURRENCIES`. |
| `variant?` | `InputVariant` | Default `'outline'`. |
| `size?` | `InputSize` | Default `'default'`. |
| `label?` | `string` | Label above the field. |
| `supportingText?` | `string` | Helper line. Replaced by the error text when `invalid`. |
| `min?` | `number` |  |
| `max?` | `number` |  |
| `step?` | `number` | Arrow-key increment. Defaults to the currency's own step. |
| `clamp?` | `boolean` | Snap the value into [min, max] when the field is left. Default `true`. |
| `presets?` | `number[]` | One-tap amounts under the field, in the current currency. |
| `rates?` | `Record<string` | Value of one unit of each currency in a shared base, keyed by code — `{ IQD: 1, USD: 1310 }`. Drives the approximate second amount. |
| `secondary?` | `string` | Code the approximation is shown in. Hidden when it's the active one. |
| `invalid?` | `boolean` | Inside a `Field`, defaults to the field's. |
| `disabled?` | `boolean` | Inside a `Field`, defaults to the field's. |
| `readonly?` | `boolean` | Default `false`. |
| `required?` | `boolean` | Inside a `Field`, defaults to the field's. |
| `placeholder?` | `string` | Default `'0'`. |
| `id?` | `string` |  |
| `name?` | `string` | Posts the raw number (not the formatted text) under this name. |
| `aria-describedby?` | `string` |  |
| `hint?` | `Snippet` | Replaces the built-in approximation line. |
| `class?` | `string` |  |
| `classes?` | `InputClasses` | Per-part Tailwind overrides, forwarded to the `Input` underneath. |
| `ref?` | `HTMLInputElement \| null` | Default `null`. Bindable. |

### Progress

`import { Progress } from 'omaris'`

MD3 linear progress indicator.

Parts (`classes`): `root` `track` `indicator` `buffer` `stop`

| Prop | Type | Notes |
| --- | --- | --- |
| `value?` | `number` | 0…`max`. Leave undefined for the indeterminate animation. |
| `max?` | `number` | Default `100`. |
| `tone?` | `ProgressTone` | One of `primary`, `secondary`, `tertiary`, `destructive`, `success`, `warning`, `info`. Default `'primary'`. |
| `size?` | `ProgressSize` | One of `sm`, `md`, `lg`. Default `'md'`. |
| `label?` | `string` | Accessible name — "Uploading", not "progress bar". |
| `stop?` | `boolean` | Draw MD3's stop dot at the end of the track. Determinate only. Default `true`. |
| `buffer?` | `number` | How far ahead is ready, on the same 0…`max` scale — a video's buffered range, a stream that downloads faster than it plays. Drawn as a paler run from the fill to this point. Determinate only. |
| `class?` | `string` |  |
| `classes?` | `ProgressClasses` | Per-part Tailwind overrides. `class` still covers the root. |

### PullToRefresh

`import { PullToRefresh } from 'omaris'`

Pull down to refetch — the gesture every phone app has, on the web.

#### Use it for

- A list on a phone that people expect to refetch by pulling down. With it,
  the list needs no refresh button.
- A feed whose freshness matters: orders, messages, a courier's jobs, a
  dashboard someone is watching.
- A list inside its own scroller, like a sheet or a panel. `height` sets the
  viewport; `scroller={false}` hands scrolling back to the page.
- A refetch that already lives elsewhere. With no `onrefresh` the component is
  controlled, so `bind:refreshing` wires it to a store or query client.
- A branded indicator. The indicator is a snippet and gets the live gesture,
  so a logo or a line of text can move with the finger.

#### Not for

- A desktop screen → a refresh [Button](/docs/components/button) or
  [Icon Button](/docs/components/icon-button).
- Showing a fetch the person did not ask for → [Progress](/docs/components/progress),
  or [Skeleton](/docs/components/skeleton) for a first load.
- Loading the next page → infinite scroll or a "Load more"
  [Button](/docs/components/button). This gesture means "start again".
- A horizontal strip → [Carousel](/docs/components/carousel). The two gestures
  fight.
- A page that is one form or a map. Pulling a form down is how typed input
  gets lost.

#### Do

- Return a promise from `onrefresh`. It tells the indicator when to stop.
  `minimum` keeps a fast refetch from flashing.
- Keep `threshold` near the default. Too short refreshes by accident; too long
  feels broken.
- Wrap the scrolling element, not the page frame.
- Use `overlay` when the first row is a header or search field you do not
  want pushed down.
- Disable it while a dialog or sheet is open over the list, and while the
  list is empty.

#### Don't

- Refetch without changing anything visible. Show a timestamp, a count or a
  new row.
- Leave `refreshing` true with no `onrefresh`. Controlled means nothing else
  will close it.
- Nest one inside another, or inside a [Sheet](/docs/components/sheet) that
  drags on the same axis. The inner one takes the gesture.
- Make the indicator taller than `max`.
- Make it the only way to refresh. Keep a menu item or keyboard path too.

#### Pairs with

- [List](/docs/components/list), [Sheet](/docs/components/sheet),
  [Shape](/docs/components/shape), [Progress](/docs/components/progress),
  [Empty](/docs/components/empty), [App Shell](/docs/components/app-shell)

Parts (`classes`): `root` `indicator` `disc` `arc` `glyph` `viewport`

| Prop | Type | Notes |
| --- | --- | --- |
| `onrefresh?` | `() => unknown` | Run the refetch. Return a promise and the indicator is held until it settles; return nothing and it is held for `minimum`. Leave it out to drive the component yourself with `bind:refreshing`. |
| `refreshing?` | `boolean` | Whether the refresh is running. Bindable, and the whole API without `onrefresh`. Default `false`. Bindable. |
| `disabled?` | `boolean` | Turn the gesture off — while a dialog is up, or the list is empty. Default `false`. |
| `threshold?` | `number` | Travel at which a release refreshes, in px. Default `72`. |
| `max?` | `number` | Furthest the content can be pulled, in px. The rubber band's asymptote. Default `140`. |
| `minimum?` | `number` | Shortest time the indicator stays up, in ms, so a fast refetch doesn't flash. Default `450`. |
| `overlay?` | `boolean` | Let the indicator float over the content rather than pushing it down. Default `false`. |
| `scroller?` | `boolean` | Whether this component owns the scrolling. The default gives the viewport its own `overflow-y-auto` and `height`; `false` leaves the scrolling to the page (or to an ancestor) and only reads the gesture. Default `true`. |
| `height?` | `number \| string` | How tall the scrolling viewport is — a number is px, a string is any CSS length. Ignored when `scroller` is `false`. Default `'24rem'`. |
| `shapes?` | `ShapeName[]` | The outlines the indicator travels through as you pull, and spins through. Default `['circle', 'cookie-4', 'cookie-9', 'clover-4', 'burst']`. |
| `label?` | `string` | What a screen reader is told while the refresh runs. Default `'Refreshing'`. |
| `armedLabel?` | `string` | What it is told once the pull would refresh on release. Default `'Release to refresh'`. |
| `indicator?` | `Snippet<[PullState]>` | Replace the indicator entirely. It is handed the live state. |
| `class?` | `string` |  |
| `classes?` | `PullToRefreshClasses` | Per-part Tailwind overrides. `class` still covers the root. |
| `children` | `Snippet` |  |

### QrCode

`import { QrCode } from 'omaris'`

A QR code, drawn as vector, encoded here.

#### Use it for

- A link people reach with a camera: a menu, a form, a ticket, a device's
  setup page. `value` is the whole API.
- Something a phone should act on: join this network, save this contact,
  call this number, add this event. Build the payload with `qrWifi`,
  `qrVcard`, `qrTel`, `qrEmail`, `qrSms`, `qrGeo` or `qrCalendar`, not by hand.
- A code that will be printed. It is SVG, so it prints at the printer's
  resolution. `download('name', 'image/svg+xml')` gives a designer a file.
- A code that matches the product: `shape`, `eyes`, `gradient` and `logo`.
  The correction level rises to `H` on its own when a logo covers the middle.

#### Not for

- A barcode a scanner gun reads (Code 128, EAN, UPC) → nothing here. That is
  a different symbology.
- Showing a code someone else generated → an `<img>`, or
  [Image Viewer](/docs/components/image-viewer) if it needs to zoom.
- Reading a code from a camera → nothing here. This encodes only.
- More than about 2,900 bytes. No QR code exists past that, and the component
  says so. Put the payload behind a URL.

#### Do

- Leave `margin` at `4`. It is the standard's quiet zone. Trimming it is the
  most common reason a code will not scan.
- Keep `logoSize` under `0.3`, and leave `level` alone when there is a logo.
  The bump to `H` pays for the modules the logo covers.
- Print at least 2cm across for a code held in the hand, more for one read
  from further away.
- Test a styled code with a real phone before it ships. `dot` and low
  contrast are the two things that stop a code scanning.
- Give it a `label` or `caption` when the value is not readable. The
  accessible name falls back to the raw payload.

#### Don't

- Put a light code on a dark background because the theme is dark. Not every
  scanner reads inverted codes. Keep `color` dark and `background` light in
  both themes.
- Raise `level` to `H` for its own sake. More correction means a denser code
  that must print bigger to scan.
- Encode a long URL when a short one exists. Every character is modules.
- Use `mask` or `minVersion` for looks. They keep a code's module count the
  same across a reprint.

#### Pairs with

- [Card](/docs/components/card), [Dialog](/docs/components/dialog),
  [Sheet](/docs/components/sheet), [Button](/docs/components/button),
  [Magnifier](/docs/components/magnifier)

Parts (`classes`): `root` `frame` `svg` `logo` `caption` `error`

| Prop | Type | Notes |
| --- | --- | --- |
| `value` | `string` | What the code says. A URL, a phone number, a Wi-Fi payload, anything. |
| `level?` | `QrLevel` | How much damage the code survives: `L` ~7%, `M` ~15%, `Q` ~25%, `H` ~30%. Defaults to `M`, or `H` when there is a `logo` — more correction means a denser code, so it is not free. |
| `size?` | `number \| string` | Rendered size. A number is px, a string any CSS length. Default `176`. |
| `margin?` | `number` | The quiet zone, in modules. Four is the standard's minimum and what scanners are built for; less than that and some will not see the code at all. Default `4`. |
| `shape?` | `QrShape` | How each module is drawn. Default `'square'`. |
| `radius?` | `number` | Corner radius for `shape="rounded"`, in modules — `0` to `0.5`. Default `0.35`. |
| `eyes?` | `QrEyes` | How the three corner markers are drawn. Default `'square'`. |
| `color?` | `string` | The code's colour. Defaults to the theme's foreground. Default `'var(--color-foreground)'`. |
| `background?` | `string` | Behind it. `transparent` leaves whatever is underneath. Default `'var(--color-background)'`. |
| `eyeColor?` | `string` | The corner frames, if they should differ from the modules. |
| `pupilColor?` | `string` | The pupils, if they should differ from the frames. |
| `gradient?` | `QrGradient` | A gradient over the modules, in place of `color`. |
| `logo?` | `string` | A mark in the middle. Any image URL, a data URI included. |
| `logoSize?` | `number` | How much of the code's width the logo covers. Keep it under `0.3`. Default `0.22`. |
| `logoMargin?` | `number` | Clear space punched around the logo, in modules. Default `1`. |
| `logoRadius?` | `number \| string` | Rounding on the logo's backing plate — a number is px. Default `6`. |
| `caption?` | `string` | Below the code. |
| `variant?` | `QrCodeVariant` | One of `plain`, `card`, `padded`. Default `'plain'`. |
| `label?` | `string` | The code's accessible name. Falls back to `caption`, then `value`. |
| `minVersion?` | `number` | Force a version, 1–40, when a code has to keep its module count — printed on a template, say. Too small for the data is still refused. |
| `mask?` | `number` | Force one of the eight mask patterns. By default the best is chosen. |
| `children?` | `Snippet` | Replaces the caption line. |
| `onerror?` | `(error: Error) => void` | Told when the value cannot be encoded — too long for a version 40 code. |
| `class?` | `string` |  |
| `classes?` | `QrCodeClasses` | Per-part Tailwind overrides. `class` still covers the root. |

### RadarChart

`import { RadarChart } from 'omaris/chart'`

Radar chart — several measures on one shape, so two things can be compared across all of them at once.

| Prop | Type | Notes |
| --- | --- | --- |
| `data` | `T[]` |  |
| `x?` | `Field<T>` | The field naming each spoke. |
| `y?` | `Field<T>` | The value field. Ignored once `series` names its own. |
| `series?` | `ChartSeries<T>[]` | Several values per row. Each gets a colour and a legend entry. |
| `max?` | `number` | Top of the shared scale. Defaults to the largest value in the data. |
| `height?` | `number \| string` | Plot height. A number is px; a string is any CSS length. Default `300`. |
| `grid?` | `boolean` | Rings and spokes behind the shapes. Default `true`. |
| `axis?` | `boolean \| 'x' \| 'y'` | `'x'` — the default — names the spokes. `true` also labels the rings, which is worth having when the scale isn't obvious and a collision with whichever spoke points down when it is. Default `'x'`. |
| `ticks?` | `number` | How many rings. Default `4`. |
| `legend?` | `ChartLegend` | `true` toggles a series off on click; `'isolate'` shows it alone. Default `false`. |
| `tooltip?` | `boolean` | Default `true`. |
| `points?` | `boolean` | Mark each spoke's value. Default `false`. |
| `fillOpacity?` | `number` | Opacity of the fill inside each shape. Default `0.16`. |
| `formatY?` | `(value: never) => string` | Tick labels on the rings. |
| `colors?` | `readonly string[]` | Palette override, cycled across the series. Default `CHART_COLORS`. |
| `label?` | `string` | Accessible description of what the chart shows. |
| `class?` | `string` |  |
| `empty?` | `Snippet` |  |
| `emptyText?` | `string` |  |
| `error?` | `boolean \| string \| Error` | Something went wrong. Truthy puts the chart into its error state; a string or an `Error` supplies the message. |
| `errorText?` | `string` | The message, when `error` is just `true`. |
| `errorState?` | `Snippet<[{ message: string }]>` | Replaces the whole error state. |
| `onRetry?` | `() => void` | Offers a "Try again" button in the error state. |
| `csv?` | `boolean \| string` | Offer the plotted rows as a CSV download, from a button in the corner. A string names the file. Default `false`. |
| `csvColumns?` | `(string \| { key: string; label?: string; value?: (row: T) => unknown })[]` | Which fields the download writes, in order. Defaults to every field. |

### RadialBarChart

`import { RadialBarChart } from 'omaris/chart'`

Radial bar chart — one ring per row, each filled to its share of the whole.

| Prop | Type | Notes |
| --- | --- | --- |
| `data` | `T[]` |  |
| `label?` | `Field<T>` | Field naming each ring. Defaults to `row.label`. Default `'label'`. |
| `value?` | `Field<T>` | Field holding each ring's value. Defaults to `row.value`. Default `'value'`. |
| `max?` | `number` | The value a complete ring means. Defaults to the largest one. |
| `height?` | `number \| string` | Plot height. A number is px; a string is any CSS length. Default `260`. |
| `thickness?` | `number` | Thickness of each ring, in px. Default `14`. |
| `gap?` | `number` | Gap between rings, in px. Default `6`. |
| `sweep?` | `number` | Degrees each ring sweeps when full. 360 is a closed circle. Default `360`. |
| `legend?` | `ChartLegend` | `true` toggles a ring off on click; `'isolate'` shows it alone. Default `false`. |
| `tooltip?` | `boolean` | Default `true`. |
| `colors?` | `readonly string[]` | Palette override, cycled across the rings. Default `CHART_COLORS`. |
| `title?` | `string` | Accessible description of what the chart shows. |
| `class?` | `string` |  |
| `centre?` | `Snippet` | Content for the middle — a total, usually. |
| `empty?` | `Snippet` |  |
| `emptyText?` | `string` |  |
| `error?` | `boolean \| string \| Error` | Something went wrong. Truthy puts the chart into its error state; a string or an `Error` supplies the message. |
| `errorText?` | `string` | The message, when `error` is just `true`. |
| `errorState?` | `Snippet<[{ message: string }]>` | Replaces the whole error state. |
| `onRetry?` | `() => void` | Offers a "Try again" button in the error state. |
| `csv?` | `boolean \| string` | Offer the plotted rows as a CSV download, from a button in the corner. A string names the file. Default `false`. |
| `csvColumns?` | `(string \| { key: string; label?: string; value?: (row: T) => unknown })[]` | Which fields the download writes, in order. Defaults to every field. |

### Radio

`import { Radio } from 'omaris'`

MD3 radio button.

#### Use it for

- One of two to seven options, all visible: a plan, a shipping method, a
  delivery day. `RadioGroup` carries the legend, `name`, `value` and
  `supportingText`. Each `Radio` needs only a `value` and a `label`.
- Options that need a line of explanation. Put it in `description` on each
  radio.
- A required question. Set `required` and `invalid` on the group and put the
  reason in `supportingText`; it turns red and is announced.
- A short set of short labels, like Yes/No or S/M/L. Use
  `orientation="horizontal"`, and nothing longer.

#### Not for

- More than seven options, or options with nothing to explain →
  [Select](/docs/components/select); searchable →
  [Combobox](/docs/components/combobox).
- A choice that takes effect at once, in a toolbar or over a table →
  [Segmented Button](/docs/components/segmented-button).
- Any number of options → [Checkbox](/docs/components/checkbox); one on/off →
  [Switch](/docs/components/switch).
- Switching between sections of a page → [Tabs](/docs/components/tabs).

#### Do

- Give every group a `label`. It is the fieldset's legend, read before each
  option.
- Bind `value` on the group, not `group` on each radio. Inside a `RadioGroup`
  a radio takes its name, tone and size from it. `bind:group` is for a radio
  on its own.
- Preselect the default when the form has one. Leave it empty only when the
  person must choose, and mark the group `required`.
- Put the most common option first, not the cheapest or the alphabetical one.

#### Don't

- Use bare `Radio`s without a `RadioGroup` unless you build your own
  fieldset. You lose the legend, the helper line and the shared `name` that
  lets arrow keys move between them.
- Disable an option to say it is unavailable. Explain in `description`, or
  drop it.
- Write labels as sentences. Keep them short and put detail in `description`.

#### Pairs with

- [Checkbox](/docs/components/checkbox), [Switch](/docs/components/switch),
  [Segmented Button](/docs/components/segmented-button),
  [Select](/docs/components/select), [Label](/docs/components/label)

Parts (`classes`): `root` `control` `circle` `dot` `input` `label` `description`

| Prop | Type | Notes |
| --- | --- | --- |
| `value` | `string` | This radio's value. Required — it's what the group selects. |
| `group?` | `string \| undefined` | The selected value, when the radio is used outside a group. Bindable. Default `undefined`. |
| `tone?` | `RadioTone` | One of `primary`, `secondary`, `tertiary`, `destructive`, `success`, `warning`, `info`. |
| `size?` | `RadioSizeToken` | One of `sm`, `md`, `lg`. |
| `label?` | `string` |  |
| `description?` | `string` |  |
| `invalid?` | `boolean` |  |
| `haptics?` | `boolean` | A haptic tap when it's picked. Follows the shared `haptics` store; `false` opts this radio out. Default `true`. |
| `sound?` | `boolean` | A sound cue when it's picked. Follows the shared `sound` store; `false` opts this radio out. Default `true`. |
| `class?` | `string` |  |
| `classes?` | `RadioClasses` | Per-part Tailwind overrides. `class` still covers the root. |
| `children?` | `Snippet` |  |
| `ref?` | `HTMLInputElement \| null` | Default `null`. Bindable. |

### RadioGroup

`import { RadioGroup } from 'omaris'`

The fieldset around a run of radios: legend, the options, a helper line.

Parts (`classes`): `root` `label` `options` `support`

| Prop | Type | Notes |
| --- | --- | --- |
| `value?` | `string` | Selected value. Bindable. Default `undefined`. |
| `name?` | `string` | Shared `name` for the radios. Generated when omitted. |
| `orientation?` | `'vertical' \| 'horizontal'` | One of `vertical`, `horizontal`. Default `'vertical'`. |
| `tone?` | `Tone` | Default `'primary'`. |
| `size?` | `RadioSize` | Default `'md'`. |
| `disabled?` | `boolean` | Inside a `Field`, defaults to the field's. |
| `required?` | `boolean` | Inside a `Field`, defaults to the field's. |
| `invalid?` | `boolean` | Inside a `Field`, defaults to the field's. |
| `label?` | `string` | Group heading, rendered as the fieldset's legend. |
| `supportingText?` | `string` | Helper line under the group. Turns red when `invalid`. |
| `class?` | `string` |  |
| `classes?` | `RadioGroupClasses` | Per-part Tailwind overrides. `class` still covers the root. |
| `children?` | `Snippet` |  |

### RangeSlider

`import { RangeSlider } from 'omaris'`

Two handles, one track — a price range, a time window.

#### Use it for

- A value set by feel, like volume, brightness, opacity or zoom, where the
  effect shows as you drag. `showValue` or `bubble` for the readout.
- Coarse choices along a scale: `step` with `ticks`, and `format` to name the
  stops ("Low / Medium / High", "1x … 4x").
- A window between two ends, like a price bracket or working hours:
  `RangeSlider`, with `minDistance` so the handles cannot meet.
- A media track: `wave` ripples while dragging, `wave="always"` while it
  plays, `size="sm"`. `size="lg"` with `orientation="vertical"` for a dimmer
  or a fader.

#### Not for

- A number that must be exact, like a quantity, a port or a price →
  [Text Field](/docs/components/input) `type="number"` or
  [Price Input](/docs/components/price-input).
- A handful of named options → [Segmented Button](/docs/components/segmented-button)
  or [Radio](/docs/components/radio). A slider with three stops is a radio.
- A value that cannot be changed → [Progress](/docs/components/progress) or
  [Gauge](/docs/components/gauge).
- A colour → [Color Picker](/docs/components/color-picker), which is these
  sliders already wired.

#### Do

- Give it a `label`, or `ariaLabel` when the label is elsewhere. A range takes
  two, one per handle.
- Do the expensive work (the save, the fetch) in `onchange`. Keep `oninput`
  for what must track the drag, like a preview.
- Pass `format` whenever the raw number means nothing alone: "40%", "$120",
  "3:45".
- Set `name` when the value should submit with the form. One hidden input per
  handle.

#### Don't

- Use a step so fine the handle lands anywhere. On a phone a thumb cannot hit
  37 of 100. Show the value and let the arrow keys finish.
- Ask for `ticks` on hundreds of steps. They switch off above 30.
- Put `wave="always"` on anything that is not playing.
- Hide both the label and the value. A bare track is decoration.

#### Pairs with

- [Text Field](/docs/components/input), [Progress](/docs/components/progress),
  [Gauge](/docs/components/gauge), [Video Player](/docs/components/video-player),
  [Color Picker](/docs/components/color-picker)

| Prop | Type | Notes |
| --- | --- | --- |
| `value?` | `[number, number]` | `[low, high]`. Bindable. Default `[0, 100]`. |
| `oninput?` | `(value: [number, number]) => void` |  |
| `onchange?` | `(value: [number, number]) => void` |  |
| `min?` | `number` |  |
| `max?` | `number` |  |
| `step?` | `number` |  |
| `minDistance?` | `number` | Smallest allowed gap between the two handles of a range. |
| `tone?` | `SliderTone` |  |
| `size?` | `SliderSize` |  |
| `orientation?` | `SliderOrientation` |  |
| `wave?` | `boolean \| 'always'` | Ripple a wave through the filled part while it's being dragged. `'always'` keeps it moving — for a media player that's playing. |
| `label?` | `string` | Label above the track. |
| `supportingText?` | `string` | Helper line below the track. |
| `showValue?` | `boolean` | Show the current value beside the label. |
| `bubble?` | `boolean \| 'always'` | Float the value over the handle while dragging; `'always'` keeps it up. |
| `ticks?` | `boolean` | Draw a stop dot at every step. Ignored above 30 steps. |
| `format?` | `(value: number) => string` | Turns a number into display text — "40%", "$12". |
| `name?` | `string` | Submit the value(s) with the surrounding form. |
| `elastic?` | `boolean` | Let the track stretch when dragged past either end, and spring back on release. |
| `haptics?` | `boolean` | A haptic tick on every step, and a firmer bump at either end. Follows the shared `haptics` store; `false` opts this slider out. |
| `sound?` | `boolean` | A sound cue as the handle passes each step, and a duller one at the ends. Follows the shared `sound` store; `false` opts this slider out. |
| `disabled?` | `boolean` | Inside a `Field`, defaults to the field's. |
| `ariaLabel?` | `string \| string[]` | Accessible name for each handle, when there's no visible label. |
| `class?` | `string` |  |
| `classes?` | `SliderClasses` | Per-part Tailwind overrides. `class` still covers the root. |
| `ref?` | `HTMLDivElement \| null` | Default `null`. Bindable. |

### Rating

`import { Rating } from 'omaris'`

Rating — a row of stars, or of any icon you give it.

#### Use it for

- Asking for a score out of a few — an order, a driver, a dish — bound with
  `bind:value`; 0 means "not rated yet".
- Half-point precision with `allowHalf`, where the difference between 3 and
  3.5 matters to the person giving it.
- Showing an average next to a review count: `readonly` fills fractionally,
  so 4.3 shows a third of the fifth star, and is announced as one value.
- A scale that is not stars — hearts, flames, thumbs — through the `icon`
  snippet, painted with `currentColor`.

#### Not for

- A precise number on a wide range — 0 to 100, a price →
  [Slider](/docs/components/slider) or [Number Input](/docs/components/number-input).
- A choice between labelled options — Poor / Fair / Good →
  [Segmented Button](/docs/components/segmented-button) or
  [Radio](/docs/components/radio). The words carry the meaning; stars do not.
- A like, a favourite, a bookmark — one on/off → a `toggle`
  [Icon Button](/docs/components/icon-button).
- Progress towards a goal → [Progress](/docs/components/progress) or
  [Gauge](/docs/components/gauge).

#### Do

- Give it a `label` that says what is rated — "Rate the driver" — or put it
  in a [Field](/docs/components/field); "Rating" is only the fallback.
- Keep `max` at 5 for a score people give, and show the number beside a
  `readonly` average; the stars alone read as roughly.
- Localise `valueText` with the page — it is what a screen reader speaks.
- Turn on `haptics` in settings once for the whole app; a chosen star buzzes
  on a phone.

#### Don't

- Use `readonly` stars as a button to open the reviews; they are an image. Put
  them inside a link or a [Button](/docs/components/button).
- Put ten stars on a phone at the default size; at a finger's 44px each, the
  row is wider than the screen. Trim `classes.item` or keep to five.
- Colour a low score red with `tone`; the fill is the scale, not a verdict.

#### Pairs with

- [Field](/docs/components/field), [Card](/docs/components/card),
  [Text](/docs/components/text), [List](/docs/components/list),
  [Textarea](/docs/components/textarea)

Parts (`classes`): `root` `item` `icon` `fill`

| Prop | Type | Notes |
| --- | --- | --- |
| `value?` | `number` | The rating, from 0 to `max`. 0 is "not rated". Bindable. Default `0`. |
| `max?` | `number` | How many stars. Default `5`. |
| `allowHalf?` | `boolean` | Half-star steps — the starting half of a star gives the half-point. Default `false`. |
| `readonly?` | `boolean` | A display, not a control: no focus, no pointer, fractional fill. Default `false`. |
| `disabled?` | `boolean` | Inside a `Field`, defaults to the field's. |
| `clearable?` | `boolean` | Pressing the current value again clears it back to 0. Default `true`. |
| `size?` | `RatingSize` | One of `sm`, `md`, `lg`. Default `'md'`. |
| `tone?` | `RatingTone` | Colour of a filled star. Amber by default — the colour a rating is read in. One of `primary`, `secondary`, `tertiary`, `destructive`, `success`, `warning`, `info`. Default `'warning'`. |
| `label?` | `string` | Accessible name. "Rating" when omitted — or, inside a `Field`, the field's own label. |
| `valueText?` | `(value: number, max: number) => string` | The spoken value. Defaults to "3.5 of 5". Default `(v: number, m: number) => `${Math.round(v * 10) / 10} of ${m}``. |
| `name?` | `string` | Posts the value in a form under this name. |
| `icon?` | `Snippet` | The icon, drawn twice — once unfilled, once filled and clipped. Paint it with `currentColor` and it takes both colours. |
| `haptics?` | `boolean` | A buzz when a value is chosen, once `haptics.enabled` is on. Default `true`. |
| `onchange?` | `(value: number) => void` | Fires when a value is committed — a press, a lifted finger, a key. |
| `class?` | `string` |  |
| `classes?` | `RatingClasses` | Per-part Tailwind overrides. `class` still covers the root. |
| `ref?` | `HTMLDivElement \| null` | Default `null`. Bindable. |

### Reorder

`import { Reorder } from 'omaris'`

A list whose rows you can drag into a different order.

Parts (`classes`): `root` `row` `handle` `status`

| Prop | Type | Notes |
| --- | --- | --- |
| `items` | `T[]` | The rows, in order. Bindable — a drop rewrites it. Bindable. |
| `children` | `Snippet<[T, ReorderContext]>` | How to draw one row. |
| `key?` | `(item: T, index: number) => string \| number` | Identity, which is what keeps a row the same element across a reorder. Defaults to the item's `id`, then its index. |
| `label?` | `(item: T) => string` | Names a row for assistive tech during a keyboard drag. |
| `handle?` | `boolean` | Only `<ReorderHandle />` may start a drag. Leave it off and the whole row is the grip — anything but a control inside it. Default `false`. |
| `listLabel?` | `string` | Accessible name for the list. |
| `variant?` | `ListVariant` | Container look — the same three `List` has. Default `'plain'`. |
| `dividers?` | `boolean` | Default `false`. |
| `spaced?` | `boolean` | Default `false`. |
| `padding?` | `'none' \| 'sm' \| 'md'` | Default `'none'`. |
| `disabled?` | `boolean` | Default `false`. |
| `onreorder?` | `(move: ReorderMove<T>) => void` |  |
| `class?` | `string` |  |
| `classes?` | `ReorderClasses` | Per-part Tailwind overrides. `class` still covers the root. |

### ReorderHandle

`import { ReorderHandle } from 'omaris'`

The grip on a reorderable row.

| Prop | Type | Notes |
| --- | --- | --- |
| `class?` | `string` |  |
| `children?` | `Snippet` | Replaces the six-dot glyph. |

### ResizableHandle

`import { ResizableHandle } from 'omaris'`

The divider between two panels — and the thing you drag.

#### Use it for

- A dashboard split: a sidebar and its content, or a three-pane inbox
  (folders, messages, preview) as two nested groups.
- An editor over a terminal, or a chart over its data: `direction="vertical"`.
- A sidebar the person closes and reopens from a toolbar button: `collapsible`
  with `bind:collapsed`, and `reset()` on the group behind "Reset layout".
- A layout that survives a reload: `autoSaveId` stores the sizes in
  `localStorage`.

#### Not for

- The frame of the app, what scrolls and where the app bar sits →
  [App Shell](/docs/components/app-shell). Put a `ResizablePanelGroup` inside
  `AppShellMain` when a pane in the content needs dragging.
- Two columns nobody will resize → a plain `grid-cols-[16rem_1fr]`.
- A panel that comes and goes → [Sheet](/docs/components/sheet).
- Content split by topic rather than by space → [Tabs](/docs/components/tabs).
- A phone. Stack the panes below `md`, or put the second one in a
  [Sheet](/docs/components/sheet).

#### Do

- Give the group a height. It fills its parent, which needs `h-…` or a flex
  column.
- Set `withHandle` and a `label` ("Resize sidebar") on every handle people
  are meant to find. The line alone is 1px.
- Use `min="240px"` for a panel with fixed-width content, like a nav rail or
  a form. Use a percentage for one that scales with the window.
- Put `min-w-0` and `overflow-auto` inside a panel, so long content scrolls
  in the pane instead of forcing it wider.

#### Don't

- Write `w-…` on a `ResizablePanel`. Sizes are shares the group owns.
- Reuse an `autoSaveId` for two different groups. They trade layouts.
- Make a panel `collapsible` with the drag as the only way back. Pair it with
  a button through `bind:collapsed`.
- Shrink `hitArea` to make the divider thinner. The line is 1px already; the
  hit area is what makes it grabbable.

#### Pairs with

- [App Shell](/docs/components/app-shell), [Navigation Drawer](/docs/components/navigation-drawer),
  [Icon Button](/docs/components/icon-button), [Table](/docs/components/table),
  [Code Editor](/docs/components/code-editor)

Parts (`classes`): `root` `grip`

| Prop | Type | Notes |
| --- | --- | --- |
| `withHandle?` | `boolean` | Draw the grip, so the divider is obviously draggable. Default `false`. |
| `keyboardStep?` | `number` | Percentage points one arrow press moves it. Falls back to the group's `step`. |
| `hitArea?` | `number` | Width of the pointer target in px. The line it draws stays 1px, and a coarse pointer gets at least 24px however small this is. Default `8`. |
| `disabled?` | `boolean` | Default `false`. |
| `label?` | `string` | Accessible name — "Resize sidebar". Default `'Resize'`. |
| `class?` | `string` |  |
| `classes?` | `ResizableHandleClasses` | Per-part Tailwind overrides. `class` still covers the root. |

### ResizablePanel

`import { ResizablePanel } from 'omaris'`

One pane of a `ResizablePanelGroup`.

| Prop | Type | Notes |
| --- | --- | --- |
| `defaultSize?` | `ResizableSize` | Share of the group to open at — a percentage, or pixels as `'320px'`. |
| `min?` | `ResizableSize` | Smallest share it may take — a percentage, or pixels as `'240px'`. Default `10`. |
| `max?` | `ResizableSize` | Largest share it may take — a percentage, or pixels as `'600px'`. Default `100`. |
| `collapsible?` | `boolean` | Let it be squashed shut past `min`, snapping to `collapsedSize`. Default `false`. |
| `collapsedSize?` | `number` | Size a collapsed panel rests at, as a percentage. Default `0`. |
| `collapsed?` | `boolean` | Whether it is shut. Bindable — set it to collapse or expand from outside. Default `false`. Bindable. |
| `snapPoints?` | `number[]` | Percentages a drag pulls onto as the handle comes near. |
| `snapThreshold?` | `number` | How close, in percentage points, before a snap point pulls. Default `3`. |
| `onResize?` | `(size: number) => void` | Fires with the new size whenever this panel is resized. |
| `onCollapse?` | `(collapsed: boolean) => void` | Fires when it collapses or opens back up. |
| `class?` | `string` |  |
| `children?` | `Snippet` |  |

### ResizablePanelGroup

`import { ResizablePanelGroup } from 'omaris'`

Resizable panels — the dashboard split view.

| Prop | Type | Notes |
| --- | --- | --- |
| `direction?` | `ResizableDirection` | Axis the panels are laid out along. One of `horizontal`, `vertical`. Default `'horizontal'`. |
| `sizes?` | `number[]` | Panel sizes as percentages, in order. Bindable. Default `[]`. |
| `autoSaveId?` | `string` | Persist the layout under this key in `localStorage`. |
| `disabled?` | `boolean` | Freeze the layout: no handle can be dragged, keyed or double-clicked. Default `false`. |
| `step?` | `number` | Percentage points one arrow press moves a handle. A handle's own `keyboardStep` wins. Default `5`. |
| `onLayout?` | `(sizes: number[]) => void` | Fires whenever the layout settles on new sizes. |
| `onDragStart?` | `() => void` | A handle has been grabbed. |
| `onDragEnd?` | `(sizes: number[]) => void` | The handle has been let go, with the sizes it left behind. |
| `class?` | `string` |  |
| `children?` | `Snippet` |  |

### RichTextEditor

`import { RichTextEditor } from 'omaris'`

A rich text editor that is a `contenteditable` and a toolbar, and nothing else.

#### Use it for

- A description, a note or a comment with bold, a list and a link in it.
  `value` is HTML, sanitised on the way in and out.
- A comment box: `size="sm"`, `tools` cut to bold, italic and link, a short
  `height`.
- Content written elsewhere and shown here: `readOnly`. Same typography, same
  tokens, no toolbar.
- Paste from a word processor. It arrives as paragraphs, not as spans
  carrying someone else's font.

#### Not for

- Plain text → [Textarea](/docs/components/textarea).
- Code, JSON, a query → [Code Editor](/docs/components/code-editor).
- One line → [Text Field](/docs/components/input).
- Collaborative editing, custom block types or an enforced schema → not in
  this library. That is ProseMirror or TipTap.
- Markdown source edited as markdown → [Code Editor](/docs/components/code-editor)
  with `lang="md"` and `wrap`.

#### Do

- Keep `sanitize` on. When you need one more tag, like `<table>` or `<mark>`,
  add it with `allowedTags` instead of turning the allowlist off.
- Trim `tools` to what the field needs. Three buttons for a comment, the
  full set for a product description.
- Set `status` on a field with a limit, so the count is visible.
- Size it with `height`. It is a minimum and a property, so `classes.content`
  can replace it.

#### Don't

- Trust the HTML on the server because the client cleaned it. Run an
  allowlist on the way into the database too.
- Set `sanitize={false}` for content that is "already clean". It is only
  clean until the first paste.
- Use it for a title or a name. One line, no formatting →
  [Text Field](/docs/components/input).

#### Pairs with

- [Textarea](/docs/components/textarea), [Text Field](/docs/components/input),
  [Code Editor](/docs/components/code-editor), [Emoji Picker](/docs/components/emoji-picker),
  [Button](/docs/components/button)

Parts (`classes`): `root` `toolbar` `separator` `tool` `select` `linkBar` `linkInput` `content` `placeholder` `status`

| Prop | Type | Notes |
| --- | --- | --- |
| `value?` | `string` | The document, as HTML. Bindable. Default `''`. |
| `size?` | `RichTextEditorSize` | One of `sm`, `md`. Default `'md'`. |
| `tools?` | `RichTextTool[]` | Which buttons, and in what order. `'separator'` draws a divider. Default `DEFAULT_TOOLS`. |
| `placeholder?` | `string` | Default `'Write something…'`. |
| `readOnly?` | `boolean` | Default `false`. |
| `status?` | `boolean` | Word and character counts along the bottom. Default `false`. |
| `sanitize?` | `boolean` | Run pasted and incoming HTML through the tag allowlist. Leave it on unless the content is already trusted *and* already clean. Default `true`. |
| `allowedTags?` | `string[]` | Tags kept by the sanitiser, on top of the defaults. Default `[]`. |
| `height?` | `number \| string` | Minimum height of the editing area. A number is px, a string any CSS length — a property rather than a class, so `classes.content` can replace it. Default `'9rem'`. |
| `toolbar?` | `Snippet` | Extra buttons, rendered at the end of the toolbar. |
| `onchange?` | `(value: string) => void` |  |
| `class?` | `string` |  |
| `classes?` | `RichTextEditorClasses` |  |

### SafeArea

`import { SafeArea } from 'omaris'`

The padding that keeps an interface out from under the hardware.

#### Use it for

- The outermost wrapper of an app that gets the whole screen: Capacitor, a
  PWA opened from the home screen. One `<SafeArea class="min-h-dvh">` keeps
  everything clear of the notch and the home indicator.
- The contents of a bar that reaches the screen edge: a header, a bottom
  action row, a floating toolbar. The surface runs edge to edge and
  `edges={['bottom']}` keeps only what is inside it clear.
- A screen in landscape, where the cutout moves to the side.
  `edges={['start', 'end']}` adds the padding portrait did not need.
- A bottom bar that must stay above the on-screen keyboard. `keyboard` adds
  what the keyboard covers to the bottom edge.

#### Not for

- A page in an ordinary browser tab → nothing. The insets are zero there.
- Padding unrelated to the hardware → a `p-*` class. `min` is the floor under
  an inset, not a way to add padding.
- The insets as numbers, for a canvas or a measured animation → the
  `safeArea` rune.
- One edge on one element, with no minimum → `pt-safe-top`, `pb-safe-bottom`,
  `ps-safe-start`, `pe-safe-end`.
- Components that already inset themselves →
  [Top App Bar](/docs/components/top-app-bar),
  [Navigation Bar](/docs/components/navigation-bar), [Sheet](/docs/components/sheet),
  [Dialog](/docs/components/dialog), [Toast](/docs/components/toast). Wrapping
  one pads it twice.

#### Do

- Set `viewport-fit=cover` in the viewport meta tag, or every inset is zero.
  `bunx omaris native` writes it into `src/app.html`; an older project adds
  it by hand.
- Give `min` the padding the design wanted anyway. Many phones report `0` for
  the bottom inset.
- Name the edges as soon as something else handles one. Two nested
  `SafeArea`s on the same edge pad it twice.
- Put the background on the bar and the `SafeArea` inside it, so the colour
  runs under the status bar.
- Test with a notched device in the simulator, or fake it on desktop by
  redefining `--safe-top` and `--safe-bottom` on an ancestor.

#### Don't

- Wrap every screen and the layout. Insets stack.
- Use it to lift something off the bottom of a browser window. There is no
  inset there; use padding.
- Hard-code `env(safe-area-inset-top)` in a component. The `--safe-*`
  variables let a preview fake them and let `start`/`end` follow the writing
  direction; `env()` only knows left and right.
- Use `mode="margin"` by default. Padding keeps the element's surface against
  the screen edge, which is what a bar wants. Margin is for something with
  its own shape, like a floating button.

#### Pairs with

- [App Shell](/docs/components/app-shell), [Top App
  Bar](/docs/components/top-app-bar), [Navigation
  Bar](/docs/components/navigation-bar), [Sheet](/docs/components/sheet),
  [Device Mockup](/docs/components/device-mockup)

| Prop | Type | Notes |
| --- | --- | --- |
| `edges?` | `SafeAreaEdge[]` | Which edges to hold clear. Defaults to all four — name the ones you mean as soon as a parent is already handling another. Default `[...SAFE_AREA_EDGES]`. |
| `min?` | `number \| string` | The padding you wanted anyway, as a floor under every inset. A number is px, a string any CSS length. Without it an edge with no hardware in the way gets no padding at all. Default `0`. |
| `keyboard?` | `boolean` | Add the on-screen keyboard's height to the bottom edge. Default `false`. |
| `mode?` | `SafeAreaMode` | Move it off the edge with margin rather than padding into it. One of `padding`, `margin`. Default `'padding'`. |
| `as?` | `keyof HTMLElementTagNameMap` | The element to render. `div` unless the region has a better name. Default `'div'`. |
| `children?` | `Snippet` |  |
| `class?` | `string` |  |
| `ref?` | `HTMLElement \| null` | Default `null`. Bindable. |

### ScatterChart

`import { ScatterChart } from 'omaris/chart'`

Scatter chart.

| Prop | Type | Notes |
| --- | --- | --- |
| `radius?` | `number` | Radius of each point, in px. Default `4`. |
| `size?` | `BaseChartProps<T>['x']` | Field driving the point size, for a bubble chart. |
| `sizeRange?` | `[number, number]` | Smallest and largest radius when `size` is set. Default `[3, 18]`. |
| `data` | `T[]` |  |
| `x?` | `Field<T>` | The category or time field. |
| `y?` | `Field<T>` | The value field. Ignored once `series` names its own. |
| `series?` | `ChartSeries<T>[]` | Several values per row. Each gets a colour and a legend entry. |
| `height?` | `number \| string` | Plot height. A number is px; a string is any CSS length. Default `260`. |
| `axis?` | `boolean \| 'x' \| 'y'` | `true` for both, or just the one you want. Default `true`. |
| `grid?` | `boolean` | Default `true`. |
| `legend?` | `ChartLegend` | `true` shows the legend and lets a click toggle a series off. `'isolate'` makes a click show that series alone, and a second one bring the rest back — which is the move you actually want on a chart with six lines on it. Default `false`. |
| `tooltip?` | `boolean` | Default `true`. |
| `formatX?` | `(value: never) => string` | Tick labels along the x axis. |
| `formatY?` | `(value: never) => string` | Tick labels along the y axis, and the tooltip's values. |
| `colors?` | `readonly string[]` | Palette override, cycled across the series. Default `CHART_COLORS`. |
| `padding?` | `number \| { top?: number; right?: number; bottom?: number; left?: number }` | Space around the plot, in px — room for long axis labels. |
| `label?` | `string` | Accessible description of what the chart shows. |
| `class?` | `string` |  |
| `empty?` | `Snippet` | Shown in place of the plot when `data` is empty. |
| `emptyText?` | `string` |  |
| `error?` | `boolean \| string \| Error` | Something went wrong. Truthy puts the chart into its error state; a string or an `Error` supplies the message. |
| `errorText?` | `string` | The message, when `error` is just `true`. |
| `errorState?` | `Snippet<[{ message: string }]>` | Replaces the whole error state. |
| `onRetry?` | `() => void` | Offers a "Try again" button in the error state. |
| `csv?` | `boolean \| string` | Offer the plotted rows as a CSV download, from a button in the corner. A string names the file. Default `false`. |
| `csvColumns?` | `(string \| { key: string; label?: string; value?: (row: T) => unknown })[]` | Which fields the download writes, in order. Defaults to every field. |
| `references?` | `ChartReference[]` | Lines and bands at fixed values — targets, thresholds, windows. |
| `annotations?` | `ChartAnnotation[]` | Notes pinned to a point. |
| `brush?` | `ChartBrush` | Drag across the plot to select a range, and zoom the chart to it. |
| `zoom?` | `ChartZoom` | Wheel or pinch to zoom, drag to pan. |

### ScrollArea

`import { ScrollArea } from 'omaris'`

A scroll container that looks like it belongs: thin, token-coloured bars that thicken under the pointer, and optional edge fades that say there is more beyond an edge — and only when there is.

#### Use it for

- A panel inside the page that scrolls on its own — a member list in a card,
  an activity feed beside a chart, the body of a settings dialog.
- A row that runs off the side on a phone: category chips, a strip of cards,
  a week of days. `orientation="horizontal"` keeps the page itself from
  scrolling sideways.
- A table or grid wider and taller than its frame: `orientation="both"`, with
  sticky headers inside — the viewport is the scroller, so `sticky` works.
- A list where "there is more" should be visible: `fade` masks each edge the
  content has left, and only while it has left it.

#### Not for

- The page's own scroll → nothing. The window already scrolls natively; an
  [App Shell](/docs/components/app-shell) gives the main column its own.
- A long list of thousands of rows → a virtualised list, such as
  [Log Viewer](/docs/components/log-viewer) for logs. A scroll area renders
  every row it holds.
- Content that pages rather than scrolls → [Carousel](/docs/components/carousel)
  for slides, [Pagination](/docs/components/pagination) for results.
- A data table → [Table](/docs/components/table), which already scrolls
  sideways on its own and pins its header with `sticky`.

#### Do

- Size it from outside: `maxHeight` to grow up to a limit, or `class="h-64"`
  (or `flex-1 min-h-0` in a flex column) to fill a fixed space. It ships no
  height of its own, so either replaces nothing.
- Give it a `label` — "Team", "Order items". A scroll area that overflows
  takes focus so the keyboard can scroll it, and the label is what a screen
  reader calls that stop.
- Use `fade` on a surface with no border to carry the edge, and a border or a
  `data-overflow-top:` shadow when the edge needs to be drawn.
- Let the content wrap on the axis that does not scroll —
  `orientation="vertical"` clips anything wider than the frame.

#### Don't

- Nest one scroll area in another on the same axis. A finger cannot tell
  which one it is moving.
- Put the only copy of a primary action at the bottom of a scrolled list;
  pin it outside the area instead.
- Use it to hide the scrollbar. Pass `classes={{ viewport: 'scrollbar-none' }}`
  only where something else says the content moves — a fade, or a peek of
  the next card.
- Wrap a whole screen in one — a phone's toolbar collapses and its
  pull-to-refresh works only on the page's own scroll.

#### Pairs with

- [Card](/docs/components/card), [List](/docs/components/list),
  [Chip](/docs/components/chip), [Dialog](/docs/components/dialog),
  [App Shell](/docs/components/app-shell), [Text](/docs/components/text)

Parts (`classes`): `root` `viewport` `content`

| Prop | Type | Notes |
| --- | --- | --- |
| `orientation?` | `ScrollAreaOrientation` | Which way it scrolls. The other axis is clipped. One of `vertical`, `horizontal`, `both`. Default `'vertical'`. |
| `maxHeight?` | `number \| string` | The tallest it grows before it scrolls. A number is px, a string any CSS length — `320`, `"20rem"`, `"50dvh"`. Unset, it grows with its content unless something outside gives it a height. |
| `fade?` | `boolean \| number \| string` | Fade the content out at each edge it has been scrolled away from. `true` is a 1.5rem fade; a number (px) or a CSS length sets the depth. Default `false`. |
| `label?` | `string` | Names the area for a screen reader — "Activity", "Order items". When the content overflows the area takes focus, and with a label it is a `region` too. `aria-label` works the same. |
| `ref?` | `HTMLDivElement \| null` | The scrolling element, for `scrollTo` and friends. Bindable. Default `null`. |
| `class?` | `string` |  |
| `classes?` | `ScrollAreaClasses` | Per-part Tailwind overrides. `class` still covers the root. |
| `children?` | `Snippet` |  |

### SearchBar

`import { SearchBar } from 'omaris'`

MD3 search — the bar and the view it opens into.

#### Use it for

- Search across the app (an order, a customer, a page) from the `search` slot
  of a [Top App Bar](/docs/components/top-app-bar). On a wide screen a panel
  docks under it; on a phone a tap opens a full search screen.
- Results from a server. Set `filter={false}` so nothing is re-filtered
  locally, `loading` while the request is out, or use the `results` snippet
  for rows of your own.
- A bar over a map or a canvas: `variant="elevated"`.
- Suggestions that open the best match on Enter. The first row is highlighted
  as soon as there is a query.

#### Not for

- Filtering a table or list in place → a [Text Field](/docs/components/input)
  with a magnifier in `start` and `clearable`.
- Choosing a value for a form field → [Combobox](/docs/components/combobox).
- Narrowing by category → filter [Chips](/docs/components/chip).
- A settings page with sections → [Toc](/docs/components/toc).

#### Do

- Handle both `onsearch` for Enter and `onselect` for a row. Both expect to
  go somewhere.
- Show recent searches as `suggestions` while the query is empty, so the view
  is not blank on open.
- Set `autoHighlight={false}` on a full-text search, where Enter means
  "search for this" rather than "open the best guess".
- Put a menu button in `leading` when it sits in the app bar of a layout
  whose drawer is modal.

#### Don't

- Put two on one screen. The global one is the pill; a page's filter is a
  [Text Field](/docs/components/input).
- Leave `filter` on for server results. Ranked rows get filtered again and
  the ranking is lost.
- Send thousands of `suggestions`. Cap them at the source; the view is a
  short list.

#### Pairs with

- [Top App Bar](/docs/components/top-app-bar), [Text Field](/docs/components/input),
  [Combobox](/docs/components/combobox), [List](/docs/components/list),
  [Avatar](/docs/components/avatar), [Empty](/docs/components/empty)

Parts (`classes`): `root` `input` `icon` `action` `view` `viewHeader` `results` `docked` `body` `surface` `option` `group` `description` `check` `empty` `highlight`

| Prop | Type | Notes |
| --- | --- | --- |
| `value?` | `string` | The query. Bindable. Default `''`. |
| `open?` | `boolean` | Whether the search view is showing. Bindable. Default `false`. |
| `placeholder?` | `string` | Default `'Search'`. |
| `variant?` | `SearchBarVariant` | One of `filled`, `outlined`, `elevated`. Default `'filled'`. |
| `size?` | `SearchBarSize` | One of `sm`, `md`, `lg`. Default `'md'`. |
| `view?` | `SearchBarView` | Which view focusing the bar opens. Default `'auto'`. |
| `breakpoint?` | `number` | Viewport width, in px, under which `auto` goes full screen. Default `768`. |
| `suggestions?` | `SearchSuggestion[]` | Rows to show under the field. Default `[]`. |
| `filter?` | `boolean` | Filter `suggestions` against the query here. Off when they arrive already filtered. Default `true`. |
| `autoHighlight?` | `boolean` | Highlight the first result as soon as there is a query, so Enter takes it without a trip through the arrow keys. Turn it off where Enter should search for what was typed rather than open the best guess. Default `true`. |
| `loading?` | `boolean` | Spinner in the field. Default `false`. |
| `disabled?` | `boolean` | Default `false`. |
| `emptyText?` | `string` | Text when a query matches nothing. Default `'No results'`. |
| `onsearch?` | `(value: string) => void` | Fires on Enter, with the query. |
| `onselect?` | `(suggestion: SearchSuggestion) => void` | Fires when a suggestion is taken. |
| `onclear?` | `() => void` |  |
| `onopen?` | `(open: boolean) => void` | Fires as the view opens and closes. |
| `class?` | `string` |  |
| `classes?` | `SearchBarClasses` | Per-part Tailwind overrides. `class` still covers the root. |
| `leading?` | `Snippet` | Leading slot. Defaults to a magnifier — pass a menu button instead. |
| `trailing?` | `Snippet` | Trailing slot — an avatar, a mic, a filter button. |
| `results?` | `Snippet` | The whole result area, in place of `suggestions`. |
| `footer?` | `Snippet` | Pinned under the results — "see all", a keyboard hint. |

### SegmentedButton

`import { SegmentedButton } from 'omaris'`

MD3 segmented button.

#### Use it for

- One choice out of two to five, all visible at once: Day/Week/Month, List/Grid,
  Sort by. Bind `value`; `items` are data, not children.
- A few that can all apply — Bold, Italic; Show done, Show blocked: `multiple`
  binds `values` and lets the set be empty.
- The view switcher above a [Table](/docs/components/table) or a
  [Chart](/docs/components/chart), where the choice changes what is shown now.
- Icon-only segments — alignment, density — with `keepIcon` so the tick does
  not replace the meaning, and `ariaLabel` on each item.

#### Not for

- More than five options → [Select](/docs/components/select); options that are
  whole sections of the page → [Tabs](/docs/components/tabs).
- Filters that grow with the data, wrap, or can all be off → filter
  [Chips](/docs/components/chip).
- A choice submitted with a form → [Radio](/docs/components/radio). A segment
  changes something now, not on Save.
- One on/off → [Switch](/docs/components/switch), or a `toggle`
  [Icon Button](/docs/components/icon-button).
- Commands that happen to sit together — Undo, Redo →
  [Button Group](/docs/components/button-group). Segments are choices.

#### Do

- Keep labels to a word or two of similar length; `label` truncates rather than
  wraps, and a long segment makes the row lopsided.
- Pass `label` on the set — it names the `radiogroup` — and `ariaLabel` on any
  icon-only item.
- Leave `mandatory` on for a view switcher. Turn it off only when "none" is a
  real state, such as an optional filter.
- Use `full` on a phone so the segments share the width; `size="sm"` in a
  dense toolbar.

#### Don't

- Mix labelled and icon-only segments in one set; the tick swaps the icon out
  and the widths jump.
- Use a single-segment set as an on/off; that is a [Switch](/docs/components/switch).
- Expect `tone="destructive"` to mean danger; tone here colours the selected
  fill, nothing more.

#### Pairs with

- [Button Group](/docs/components/button-group), [Chip](/docs/components/chip),
  [Tabs](/docs/components/tabs), [Radio](/docs/components/radio),
  [Table](/docs/components/table)

Parts (`classes`): `root` `segment` `check` `label`

| Prop | Type | Notes |
| --- | --- | --- |
| `items` | `SegmentedItem[]` |  |
| `value?` | `string` | Selected value, in single mode. Bindable. Default `undefined`. |
| `values?` | `string[]` | Selected values, in multiple mode. Bindable. Default `[]`. |
| `multiple?` | `boolean` | Allow more than one segment at a time. Default `false`. |
| `tone?` | `SegmentedTone` | One of `primary`, `secondary`, `tertiary`, `destructive`, `success`, `warning`, `info`. Default `'primary'`. |
| `size?` | `SegmentedSize` | One of `sm`, `md`, `lg`. Default `'md'`. |
| `shape?` | `SegmentedShape` | One of `round`, `square`. Default `'round'`. |
| `full?` | `boolean` | Default `false`. |
| `check?` | `boolean` | Draw the leading tick on selected segments. Default `true`. |
| `keepIcon?` | `boolean` | Keep a segment's own icon instead of swapping it for the tick. Default `false`. |
| `mandatory?` | `boolean` | Refuse to clear the last selection. Default `true`. |
| `ripple?` | `boolean` | Default `true`. |
| `label?` | `string` | Accessible name for the set. |
| `onchange?` | `(value: string \| string[]) => void` |  |
| `class?` | `string` |  |
| `classes?` | `SegmentedButtonClasses` | Per-part Tailwind overrides. `class` still covers the root. |

### Select

`import { Select } from 'omaris'`

Select — the Input's frame around a styled list of values.

#### Use it for

- One value from a short, fixed list people already know: a currency, a plan,
  a region, a status.
- Rows that need more than a word: `description` for a second line, `icon`
  for a mark that carries into the field, `group` for headings.
- A form on a phone, or a long native form. `native` swaps the styled list
  for the platform's own picker.

#### Not for

- A list you would search rather than scroll (people, products, countries) →
  [Combobox](/docs/components/combobox).
- Two to five choices that can stay visible → [Segmented Button](/docs/components/segmented-button);
  a few choices that each need a line of explanation → [Radio](/docs/components/radio).
- Actions like rename, duplicate, delete → [Menu](/docs/components/menu). A
  Select holds a value; a Menu does something.
- Several values at once → filter [Chips](/docs/components/chip) or a column
  of [Checkboxes](/docs/components/checkbox).
- On or off → [Switch](/docs/components/switch).

#### Do

- Give it a `placeholder` while nothing is chosen, or a `value` when one is
  obviously right, like the account's own currency.
- Add `clearable` only when "none" is a valid answer, and say so in
  `supportingText`.
- Split a list past a dozen rows with `group`, so a currency list reads as
  regions.
- Use `native` on a phone form. The styled list is the desktop version.

#### Don't

- Use it for yes or no. That is a [Switch](/docs/components/switch) or two
  [Radios](/docs/components/radio).
- Hide three options behind a closed field when they fit on the line. A
  [Segmented Button](/docs/components/segmented-button) shows them all.
- Rely on `description` or `icon` with `native`. The OS picker drops both, so
  the label must stand alone.
- Pass `<option>` children and `options` at once. Children are for the native
  path only.

#### Pairs with

- [Combobox](/docs/components/combobox), [Text Field](/docs/components/input),
  [Segmented Button](/docs/components/segmented-button), [Radio](/docs/components/radio),
  [Menu](/docs/components/menu)

Parts (`classes`): `root` `field` `control` `value` `chevron` `adornment` `action` `label` `support` `placeholder` `surface` `option` `group` `body` `description` `check` `empty` `highlight`

| Prop | Type | Notes |
| --- | --- | --- |
| `variant?` | `SelectVariant` | One of `outline`, `filled`, `ghost`. Default `'outline'`. |
| `size?` | `SelectSize` | One of `sm`, `default`, `lg`. Default `'default'`. |
| `value?` | `string` | Selected value. Bindable. Default `''`. |
| `options?` | `SelectOption[]` | Options to render. Omit and pass `<option>` children for a native select. |
| `placeholder?` | `string` | Shown, greyed, while nothing is chosen. |
| `label?` | `string` |  |
| `required?` | `boolean` | Inside a `Field`, defaults to the field's. |
| `supportingText?` | `string` |  |
| `invalid?` | `boolean` | Inside a `Field`, defaults to the field's. |
| `native?` | `boolean` | Use the OS picker instead of the styled list. Default `false`. |
| `mobileSheet?` | `boolean` | On a phone, the list rises from the bottom edge as a sheet — full width, a scrim behind, dragged down to dismiss, rows a thumb can hit — instead of hanging under the field. `false` keeps it anchored. |
| `clearable?` | `boolean` | Show an × that empties the field. Default `false`. |
| `emptyText?` | `string` | Text for an empty `options` array. Default `'No options'`. |
| `start?` | `Snippet` | Leading icon inside the frame. |
| `option?` | `Snippet<[SelectOption, { selected: boolean; active: boolean }]>` | Custom row rendering for the styled list. |
| `onchange?` | `(value: string, option: SelectOption \| undefined) => void` |  |
| `class?` | `string` |  |
| `classes?` | `SelectClasses` | Per-part Tailwind overrides. `class` still covers the root. |
| `children?` | `Snippet` |  |
| `ref?` | `HTMLSelectElement \| HTMLButtonElement \| null` | Default `null`. Bindable. |

### Shape

`import { Shape } from 'omaris'`

The Material 3 shape library, as a box you can put things in.

#### Use it for

- A picture that should not be a rounded rectangle: a profile, a place, a
  category tile, a cover. `src` clips the image itself.
- Decorative marks with a brand's personality: an empty state, an onboarding
  step, a badge behind an icon. `<Shape>` with a background class and no
  children is a filled shape.
- A loading indicator that is not a spinner: `cycle` with `spin`. The
  contents counter-rotate, so an icon inside stays upright.
- Feedback on a tile people can point at. `hover` and `press` are shapes, and
  the outline morphs to them.
- The outline on its own, for a mask or a CSS `clip-path` elsewhere.
  `shapePaths` and `shapeNames` are exported, each a closed path in a 100×100
  box.

#### Not for

- The corner rounding of ordinary UI, like cards, buttons and sheets → the
  shape scale (`rounded-shape-md`, `rounded-shape-xl`).
- A person's picture with a presence dot, initials fallback and a group stack
  → [Avatar](/docs/components/avatar). Use `Shape` only when the frame itself
  must be unusual.
- Progress with a number → [Progress](/docs/components/progress) or
  [Gauge](/docs/components/gauge). A cycling shape says "working", not "62%".
- Cropping or zooming a photo a person picked →
  [Image Cropper](/docs/components/image-cropper).
- Text. Clipping a paragraph cuts lines mid-word.

#### Do

- Keep the box square unless the stretch is the point. A wide box gives a
  wide shape.
- Size it with the `size` prop, or a `size-*` class when the layout owns the
  size. The class wins.
- Use `hover` on something already interactive (a link, a button, a card), so
  the movement is a response.
- Pair a strong shape with a plain one. `cookie-12` next to `arch` reads as a
  set; twelve different shapes read as noise.
- Give an image an `alt`, or leave it empty when the picture is decoration.
- Let a `cycle` run at 700–1200ms per shape. Faster and the morph never
  lands; slower and it looks stalled.

#### Don't

- Morph on every state change in a list. One shape moving is fine; twenty is
  a screen that will not sit still.
- Put a control at the edge of a concave shape. A burst's points leave the
  middle of each edge cut away.
- Use `spin` on something people read, like a photo of a person. It is for a
  loader or a mark.
- Use `pixel-circle` or `heart` in a dashboard because they exist. `circle`,
  `square`, `arch` and `pill` survive a redesign.
- Set a `clip-path` in `class`. The component already owns that property on
  the root.

#### Pairs with

- [Avatar](/docs/components/avatar), [Card](/docs/components/card),
  [Masonry](/docs/components/masonry), [Empty](/docs/components/empty),
  [Carousel](/docs/components/carousel), [Chip](/docs/components/chip)

Parts (`classes`): `root` `content` `image`

| Prop | Type | Notes |
| --- | --- | --- |
| `shape?` | `ShapeName` | The outline. Changing it morphs, rather than cutting. Default `'circle'`. |
| `hover?` | `ShapeName` | Morph to this while the pointer is over it, or focus is inside. |
| `press?` | `ShapeName` | Morph to this while it is being pressed. |
| `cycle?` | `ShapeName[]` | Morph through these forever — a loader, or an idle flourish. |
| `interval?` | `number` | How long each shape in `cycle` is held, in ms. Default `1400`. |
| `duration?` | `number` | How long one morph takes, in ms. `0` cuts instead. Default `500`. |
| `spin?` | `boolean \| number` | Turn the outline while the contents stay upright. Seconds per turn, or `true` for 12. Default `false`. |
| `size?` | `string \| number` | Width and height, as a CSS length. Numbers are pixels. Default `'6rem'`. |
| `src?` | `string` | A picture to clip, for the common case. Children work too. |
| `alt?` | `string` |  |
| `class?` | `string` |  |
| `classes?` | `ShapeClasses` | Per-part Tailwind overrides. `class` still covers the root. |
| `children?` | `Snippet` |  |

### Share

`import { Share } from 'omaris'`

The share sheet — a bottom sheet on a phone, a centred dialog on a desktop, built on `Dialog` so the focus trap, the drag-to-dismiss and the morphing height all come for free.

#### Use it for

- Handing a link to another person or app. One tag is the whole setup:
  `<Share bind:open url={link} title={name} text={summary} />`. The preview,
  the copyable link, the QR code, seven destinations and the platform sheet
  come from those three fields.
- Sending a record out of a dashboard, like an invoice or a report. Put the
  exports in `actions` (`Download PDF`, `Print`) and the destinations in
  `targets`. Both sit in the same sheet.
- A recents row. `people` puts faces above the apps, each badged with the
  channel the message goes over. An unreachable recipient stays on the rail
  as `disabled`.
- Getting a URL onto a phone in the room. The QR row is on whenever there is
  a `url`, and the sheet morphs to the code in place.
- Your own destination beside the built-ins:
  `targets={['whatsapp', 'email', intranet]}`. Names and objects share the
  array. `{ ...shareTargets.email, label: 'Send by post' }` keeps a built-in's
  glyph and changes its wording.

#### Not for

- Feedback about something that already happened → [Toast](/docs/components/toast).
  Share reports its own copy on the row that was pressed.
- A form, a filter panel or anything you work in → [Sheet](/docs/components/sheet).
- A question that must be answered before anything continues →
  [Dialog](/docs/components/dialog).
- A few commands off a button → [Menu](/docs/components/menu).
- Showing a link to be read rather than sent →
  [Code Block](/docs/components/code-block), or a `readonly`
  [Input](/docs/components/input).
- A QR code as the point of the screen, like a table booking or a Wi-Fi
  handover → [QR Code](/docs/components/qr-code) on the page itself.

#### Do

- Fill `title` and `text`. They are the preview's two lines and the payload
  every destination gets.
- Give `image` when there is a thumbnail: a product shot, an og:image, an
  avatar.
- Keep the default `targets` for a public link. Narrow them only when a
  destination is wrong for the content, like an internal invoice on Facebook.
- Give every `ShareTarget` and `ShareAction` a stable `id`. `onshare` reports
  it and the `{#each}` keys on it.
- Set `done` on an action whose result leaves nothing on screen, like
  revoking a link. The row says it where it was pressed; no toast.
- Keep `native` on. On a phone the platform sheet reaches apps the web cannot,
  and it only appears where the browser has one.

#### Don't

- Pass `files` and expect a web intent to carry them. Only the platform sheet
  takes attachments; every other destination gets the link.
- Raise a toast from an `onselect` that opens an app. The app opening is the
  report.
- Use it as a menu. Two rows and no link is a [Menu](/docs/components/menu).
- Put a destructive action anywhere but last, or without `destructive: true`.
- Set `closeOnShare={false}` unless the sheet stays useful after a send. It
  fits a recents row people send to twice, and nothing else.

#### Pairs with

- [Dialog](/docs/components/dialog), [Sheet](/docs/components/sheet),
  [QR Code](/docs/components/qr-code), [Avatar](/docs/components/avatar),
  [Button](/docs/components/button), [Icon Button](/docs/components/icon-button)

Parts (`classes`): `root` `surface` `header` `thumb` `heading` `subheading` `close` `link` `linkText` `copy` `section` `label` `rail` `target` `tile` `targetLabel` `targetDetail` `person` `badge` `actions` `action` `actionLabel` `actionDetail` `actionIcon` `qr` `qrPlate` `footer`

| Prop | Type | Notes |
| --- | --- | --- |
| `open?` | `boolean` | Bindable. Default `false`. |
| `url?` | `string` | The link being shared. Everything else has a sensible default from it. |
| `title?` | `string` | Headline — the page, product or file. Also the preview's first line. |
| `text?` | `string` | The sentence that goes with it, and the preview's second line. |
| `files?` | `File[]` | Attachments for the platform sheet. Web intents get the link instead. |
| `image?` | `string` | A thumbnail of what is being shared. |
| `heading?` | `string` | The sheet's own headline, above the preview. Defaults to "Share". Default `'Share'`. |
| `targets?` | `readonly (ShareTargetId \| ShareTarget)[] \| false` | Destinations, by name or as objects, in one array. Defaults to the seven built-ins; `false` drops the rail entirely. Default `DEFAULT_TARGETS`. |
| `people?` | `readonly ShareTarget[]` | Faces above the apps — recent recipients, teammates, devices. |
| `actions?` | `readonly ShareAction[]` | Rows under the rails. The QR row is added to them, not instead of them. |
| `peopleLabel?` | `string` | Caption over the people rail, and its accessible name. Default `'Send to'`. |
| `targetsLabel?` | `string` | Caption over the apps rail, and its accessible name. Default `'Share via'`. |
| `link?` | `boolean` | Show the copyable link bar. On whenever there is a `url`. |
| `qr?` | `boolean` | Offer the QR code row. On whenever there is a `url`. |
| `native?` | `boolean` | Offer the platform's own sheet where the browser has one. On by default. Default `true`. |
| `nativeLabel?` | `string` | What that tile is called. Default `'More'`. |
| `closeOnShare?` | `boolean` | Close the sheet once a destination has been handed the payload. On by default. Default `true`. |
| `size?` | `ShareSize` | Default `'md'`. |
| `density?` | `ShareDensity` | One of `comfortable`, `compact`. Default `'comfortable'`. |
| `responsive?` | `boolean` | Become a bottom sheet on a phone. On by default. Default `true`. |
| `mobileQuery?` | `string` | What counts as a phone. |
| `dismissible?` | `boolean` | Escape, a press outside and a downward drag close it. Default `true`. |
| `closeLabel?` | `string` | Accessible name for the close button. Default `'Close'`. |
| `onshare?` | `(id: string, data: ShareData) => void` | Fires with the id of whatever was pressed, once it has been acted on. |
| `onclose?` | `() => void` | Fires after the sheet has finished closing. |
| `class?` | `string` |  |
| `classes?` | `ShareClasses` | Per-part Tailwind overrides. `class` still covers the root. |
| `thumb?` | `Snippet` | Replaces the preview square — a file icon, a colour swatch, a chart. |
| `children?` | `Snippet` | Extra content between the link bar and the rails. |
| `footer?` | `Snippet` | Pinned under everything — a visibility switch, an expiry note. |

### Sheet

`import { Sheet } from 'omaris'`

MD3 side and bottom sheets.

#### Use it for

- A task that keeps the page in view: filters, editing a customer beside the
  table, an inspector for the selected row. `side="end"`, with actions in
  `footer` so they stay while the body scrolls.
- On a phone, anything that would be a side panel on desktop.
  `side="bottom"`, with the drag handle on by default.
- A sheet that rests at more than one height, like a map's "Nearby drivers"
  peek: `snapPoints={[0.25, 0.6, 1]}` with `size="full"`.
- The modal navigation drawer on a phone: a `side="start"` sheet with
  `ListItem` rows. There is no separate component for it.
- A panel kept over a live map. `modal={false}` (no backdrop, page stays
  tappable), `inline` so it sits inside the map's box, `dismissible={false}`
  and `snapPoints`. Bind `snap` so the page can move it. Make the lowest snap
  a strip showing the one line that matters, like the ETA.

#### Not for

- A decision that interrupts, like delete or discard → [Dialog](/docs/components/dialog)
  or `dialog.confirm()`.
- Feedback → [Toast](/docs/components/toast).
- A few actions off a button → [Menu](/docs/components/menu).
- A sidebar that is always there → [App Shell](/docs/components/app-shell)
  with a [Navigation Drawer](/docs/components/navigation-drawer).
- A picture full-screen → [Image Viewer](/docs/components/image-viewer).

#### Do

- Choose the edge per viewport: `side={narrow ? 'bottom' : 'end'}`. Unlike a
  [Dialog](/docs/components/dialog), a sheet does not switch edges on its own.
- Put actions in `footer`, not at the bottom of the body. A long form scrolls
  them away.
- Bind `snap` when the page behind reacts, like a map moving its controls
  above the sheet. Write it when the page knows better: a focused search box
  lifts the sheet to full, a trip starting drops it to a peek.
- Give an `inline` sheet's container `relative overflow-clip`, or the part
  below the snap point hangs past the edge.
- Keep `handle` and `drag` on for a bottom sheet. The handle is also a real
  close button, so the keyboard gets the same exit.

#### Don't

- Open a sheet from a sheet. Change what is inside instead.
- Set `dismissible={false}` on a modal sheet. A persistent `modal={false}`
  sheet is the one place it is right; there is nothing to dismiss to.
- Use a bottom sheet on desktop. Pick `side={wide ? 'end' : 'bottom'}`.
- Use `side="top"` for more than a short filter bar or a notice. The reach on
  a phone is wrong and the drag is upward.
- Put the app's main navigation in an `end` sheet. A drawer opens from the
  start edge.

#### Pairs with

- [Dialog](/docs/components/dialog), [Button](/docs/components/button),
  [Text Field](/docs/components/input), [List](/docs/components/list),
  [Navigation Drawer](/docs/components/navigation-drawer), [Map](/docs/components/map)

Parts (`classes`): `root` `header` `title` `description` `footer` `handle` `grip`

| Prop | Type | Notes |
| --- | --- | --- |
| `open?` | `boolean` | Bindable. Default `false`. |
| `side?` | `SheetSide` | Edge it hangs off. `start`/`end` follow the writing direction. One of `start`, `end`, `top`, `bottom`. Default `'end'`. |
| `size?` | `SheetSize` | One of `sm`, `md`, `lg`, `full`. Default `'md'`. |
| `title?` | `string` |  |
| `description?` | `string` |  |
| `dismissible?` | `boolean` | Escape, a backdrop press and a full drag close it. Default `true`. |
| `modal?` | `boolean` | A modal sheet dims and blocks the page. `false` leaves the page live behind a panel with no backdrop — for a sheet that rests over a map, not one that asks a question. Default `true`. |
| `inline?` | `boolean` | Keep it inside the nearest positioned ancestor instead of the viewport. Sizes and snap points then read against that box. Default `false`. |
| `handle?` | `boolean` | Show MD3's drag handle. On by default for a bottom sheet. |
| `drag?` | `boolean` | Follow the pointer. On by default. Default `true`. |
| `dragThreshold?` | `number` | Fraction of the sheet that has to be dragged away before a release dismisses it. A flick dismisses from anywhere regardless. Default `0.5`. |
| `snapPoints?` | `number[]` | Resting fractions of the sheet, ascending — `[0.4, 1]` gives a peek and a full height. Dragging below the smallest one dismisses. |
| `snap?` | `number` | Fraction currently rested at. Bindable. Default `1`. |
| `onclose?` | `() => void` |  |
| `onsnap?` | `(snap: number) => void` | Fires each time the sheet settles on a different snap point. |
| `class?` | `string` |  |
| `classes?` | `SheetClasses` | Per-part Tailwind overrides. `class` still covers the root. |
| `headerEnd?` | `Snippet` | Trailing slot in the header — a close button, usually. |
| `children?` | `Snippet` |  |
| `footer?` | `Snippet` | Pinned action row along the bottom. |

### Skeleton

`import { Skeleton } from 'omaris'`

Skeleton placeholder.

#### Use it for

- The shape of what is coming: `shape="circle"` for an avatar, `text` lines
  for copy, `block` for a chart or an image. Lay them out in the real
  component's slots so nothing jumps when the data lands.
- A paragraph: `lines={3}` repeats the row with a short last line.
- A whole list or card grid while its first page loads. The shimmer uses
  `translate` only, so a screenful stays at 60fps.

#### Not for

- A load with a known fraction, like an upload or export →
  [Progress](/docs/components/progress) with `value`.
- A wait inside a control, like a pressed button or a refreshing table → the
  `loading` prop on [Button](/docs/components/button) and
  [Table](/docs/components/table). The table draws its own skeleton rows.
- Nothing to show once loading ends → [Empty](/docs/components/empty), with
  the one action that fills it.
- A brief wait on content already on screen → the indeterminate
  [Progress](/docs/components/progress) bar at the top of the region.

#### Do

- Match the real size: the same `size-10` as the avatar, the same line count
  as the copy, the same footer. Keep the real layout around it.
- Mark the region `aria-busy`, or give one `label` to one skeleton that
  stands for the whole region. Skeletons are `aria-hidden` by default.
- Use `animation="pulse"` or `none` on a page with many of them. Both stop
  under reduced motion.

#### Don't

- Give every block a `label`. "Loading" twelve times is noise.
- Leave a skeleton up after an error. A failed load is `tone="destructive"`
  on [Empty](/docs/components/empty).
- Show one for data that arrives in under a couple of hundred milliseconds.
  The flash of grey is worse than the blank.

#### Pairs with

- [Empty](/docs/components/empty), [Progress](/docs/components/progress),
  [Card](/docs/components/card), [List](/docs/components/list),
  [Table](/docs/components/table)

| Prop | Type | Notes |
| --- | --- | --- |
| `animation?` | `SkeletonAnimation` | One of `shimmer`, `pulse`, `none`. Default `'shimmer'`. |
| `shape?` | `SkeletonShape` | One of `text`, `block`, `circle`. Default `'block'`. |
| `lines?` | `number` | Number of lines. Above one, the block repeats with a short last line so it reads as a paragraph. Default `1`. |
| `label?` | `string` | Announce this skeleton as a live loading region under this name. Use it once per region — not once per block. |
| `class?` | `string` |  |

### Slider

`import { Slider } from 'omaris'`

MD3 Expressive slider.

| Prop | Type | Notes |
| --- | --- | --- |
| `value?` | `number` | Bindable. Default `0`. |
| `oninput?` | `(value: number) => void` | Fires on every change. |
| `onchange?` | `(value: number) => void` | Fires when a drag ends or a key is pressed — the commit moment. |
| `min?` | `number` |  |
| `max?` | `number` |  |
| `step?` | `number` |  |
| `minDistance?` | `number` | Smallest allowed gap between the two handles of a range. |
| `tone?` | `SliderTone` |  |
| `size?` | `SliderSize` |  |
| `orientation?` | `SliderOrientation` |  |
| `wave?` | `boolean \| 'always'` | Ripple a wave through the filled part while it's being dragged. `'always'` keeps it moving — for a media player that's playing. |
| `label?` | `string` | Label above the track. |
| `supportingText?` | `string` | Helper line below the track. |
| `showValue?` | `boolean` | Show the current value beside the label. |
| `bubble?` | `boolean \| 'always'` | Float the value over the handle while dragging; `'always'` keeps it up. |
| `ticks?` | `boolean` | Draw a stop dot at every step. Ignored above 30 steps. |
| `format?` | `(value: number) => string` | Turns a number into display text — "40%", "$12". |
| `name?` | `string` | Submit the value(s) with the surrounding form. |
| `elastic?` | `boolean` | Let the track stretch when dragged past either end, and spring back on release. |
| `haptics?` | `boolean` | A haptic tick on every step, and a firmer bump at either end. Follows the shared `haptics` store; `false` opts this slider out. |
| `sound?` | `boolean` | A sound cue as the handle passes each step, and a duller one at the ends. Follows the shared `sound` store; `false` opts this slider out. |
| `disabled?` | `boolean` | Inside a `Field`, defaults to the field's. |
| `ariaLabel?` | `string \| string[]` | Accessible name for each handle, when there's no visible label. |
| `class?` | `string` |  |
| `classes?` | `SliderClasses` | Per-part Tailwind overrides. `class` still covers the root. |
| `ref?` | `HTMLDivElement \| null` | Default `null`. Bindable. |

### Sparkline

`import { Sparkline } from 'omaris/chart'`

Sparkline — a trend with no axes, sized to sit inline in a table cell or a stat tile.

| Prop | Type | Notes |
| --- | --- | --- |
| `data` | `T[] \| number[]` |  |
| `y?` | `Field<T>` | Field holding the value. Ignored when `data` is numbers. |
| `width?` | `number \| string` | Any CSS length, or a number of px. Default `'100%'`. |
| `height?` | `number \| string` | Default `32`. |
| `color?` | `string` | Any CSS colour. Defaults to the first chart role. Default `CHART_COLORS[0]`. |
| `area?` | `boolean` | Fill under the line. Default `true`. |
| `curve?` | `ChartCurve` | Default `'smooth'`. |
| `marker?` | `boolean` | Dot on the last point, so "where it ended" reads at a glance. Default `false`. |
| `class?` | `string` |  |

### Spinner

`import { Spinner } from 'omaris'`

A small busy indicator for inline use — at the end of a row, on a chip, beside a line of text, in the corner of a card that is refetching.

#### Use it for

- A small wait inside something that is already on screen — the end of a row
  that is syncing, a chip that is fetching, a line that says "Checking the
  name is free…".
- A card that is refetching while its old figure stays visible: a `sm`
  spinner in the header, and the number left where it is.
- An icon-sized "busy" anywhere a `CircularProgress` would be too heavy —
  `xs` on a chip, `sm` beside body text, `md` in a row, `lg` in an empty card.
- A named wait for a screen reader: `label="Saving the menu"` is what gets
  announced, politely, through `role="status"`.

#### Not for

- A button that is working → `loading` on [Button](/docs/components/button),
  which grows its own spinner in and blocks the press.
- A wait with a known amount → [Progress](/docs/components/progress), linear
  or circular, with a `value`.
- A wait that owns the screen or a large panel →
  [Progress](/docs/components/progress)'s `CircularProgress`, or
  [Splash Screen](/docs/components/splash-screen) before the app has anything.
- Content whose shape is known before it arrives → [Skeleton](/docs/components/skeleton),
  which holds the layout so nothing jumps when the data lands.
- A text field that is validating → `loading` on [Input](/docs/components/input).

#### Do

- Name the wait: `label="Syncing orders"` rather than the default "Loading"
  when there are several on a screen.
- Use `tone="current"` on a chip, on a filled surface or in coloured text, so
  the spinner is the colour of what it sits in.
- Keep the old content on screen while it refreshes and put the spinner
  beside it. A blank card with a spinner in it throws away what the person
  was reading.
- Match the size to the text next to it: `xs` with `label-sm`, `sm` with
  `body-md`.

#### Don't

- Put one in a `Button` by hand; `loading` does it with the right size, the
  right colour and the press blocked.
- Show a spinner for less than a few hundred milliseconds. A flash of one is
  noise — delay it, or skip it.
- Stack several on one screen for one piece of work. One spinner per thing
  that is actually waiting.
- Hide it from screen readers with `aria-hidden` unless something else on the
  page already announces the same wait.

#### Pairs with

- [Button](/docs/components/button), [Chip](/docs/components/chip),
  [List](/docs/components/list), [Card](/docs/components/card),
  [Text](/docs/components/text), [Skeleton](/docs/components/skeleton)

Parts (`classes`): `root` `svg` `track` `indicator` `label`

| Prop | Type | Notes |
| --- | --- | --- |
| `tone?` | `SpinnerTone` | `current` inherits the surrounding text colour — the choice on a coloured surface. One of `current`, `primary`, `secondary`, `tertiary`, `destructive`, `success`, `warning`, `info`. Default `'primary'`. |
| `size?` | `SpinnerSize` | `xs` 12px, `sm` 16px, `md` 20px, `lg` 32px. One of `xs`, `sm`, `md`, `lg`. Default `'md'`. |
| `label?` | `string` | What a screen reader hears — "Saving", "Loading orders". Defaults to "Loading". It is `sr-only`; nothing is drawn. Default `'Loading'`. |
| `class?` | `string` |  |
| `classes?` | `SpinnerClasses` | Per-part Tailwind overrides. `class` still covers the root. |

### SplashScreen

`import { SplashScreen } from 'omaris'`

The screen an app shows before it has anything else to show.

#### Use it for

- The first screen of an app with work to do before it can draw: a session to
  restore, a config to fetch. Drop `<SplashScreen title="Acme" />` in
  `+layout.svelte`; it renders on the server, waits for load and removes
  itself.
- A boot sequence with steps. `createSplash()` plus
  `splash.run([{ label: 'Signing you in', run: … }, …])` shows each step and
  moves the bar as they finish.
- A first-run screen. `createSplash({ id: 'boot', once: true })` shows it
  once per tab, so a reload goes straight to the app.
- A brand moment on a phone-sized web app: `variant="primary"`, a logo,
  `exit="iris"`.
- A pane that covers its own content while it reloads. `inline` keeps the
  screen inside the container instead of over the viewport.

#### Not for

- A section of a page still filling in → [Skeleton](/docs/components/skeleton)
  in the shape of what is coming.
- A known fraction of a job, like an upload or export →
  [Progress](/docs/components/progress), next to the thing.
- A route change inside a running app → [PageTransition](/docs/components/page-transition).
  A splash between screens looks like a restart.
- A short wait after pressing something → the `loading` state on
  [Button](/docs/components/button), or [Empty](/docs/components/empty) for a
  panel that came back with nothing.
- An app that failed to boot. The splash comes down either way; say what went
  wrong with [Alert](/docs/components/alert) or an
  [Empty](/docs/components/empty) with a Retry.

#### Do

- Leave `open` alone unless you know better than the page-load event. Bind it
  when you do; auto-hide switches off once the splash is controlled.
- Set `appearAfter` on a fast app. A boot that finishes inside the delay never
  shows a splash at all.
- Keep `minDuration` as it is. It stops a 40ms boot from flashing.
- Say what is happening in `message`: "Loading your workspace". It changes
  with a fade.
- Use `simulate` for an indeterminate wait, and a real `progress` the moment
  you have one. Never both.
- Match `exit` to the app: `iris` and `rise` for a phone-shaped app, `fade`
  for a dashboard.
- Reach the parts through `classes`, like `classes={{ title: '…' }}`, rather
  than wrapping the component.

#### Don't

- Hold it up for work the person did not ask for, like analytics or a
  prefetch.
- Show one on every navigation. It belongs to the boot, not the router.
- Expect contrast from `variant="primary"` with `pattern="gradient"`. Branded
  variants tint their patterns with the text colour; neutral ones tint with
  `primary`.
- Leave a `simulate`d bar running forever. It stops at 90 on purpose; only
  the splash coming down puts it on 100.
- Put a button on it that is not a way out of a failed boot.
- Give it a `z-index`. The fixed splash is above the app already; an `inline`
  one only needs its container to be `relative`.

#### Pairs with

- [Progress](/docs/components/progress), [Skeleton](/docs/components/skeleton),
  [PageTransition](/docs/components/page-transition),
  [AppShell](/docs/components/app-shell), [Text](/docs/components/text),
  [Button](/docs/components/button)

Parts (`classes`): `root` `scrim` `backdrop` `content` `logo` `halo` `title` `description` `indicator` `track` `fill` `message` `percent` `actions` `footer`

| Prop | Type | Notes |
| --- | --- | --- |
| `open?` | `boolean` | Whether the splash is up. Bindable. |
| `splash?` | `SplashController` | A {@link SplashController}, for a boot sequence. It supplies `open`, `progress` and `message`; any of the three passed as a prop wins. |
| `variant?` | `SplashScreenVariant` | The colour scheme. One of `background`, `surface`, `primary`, `inverse`, `glass`, `image`. Default `'background'`. |
| `pattern?` | `SplashScreenPattern` | The decorative layer over it. One of `none`, `gradient`, `aurora`, `mesh`, `spotlight`, `grid`, `dots`. Default `'none'`. |
| `size?` | `SplashScreenSize` | Mark and type size. One of `sm`, `md`, `lg`. Default `'md'`. |
| `align?` | `SplashScreenAlign` | Where the block sits. One of `center`, `top`, `bottom`. Default `'center'`. |
| `indicator?` | `SplashScreenIndicator` | What loops while it is up. Default `'spinner'`. |
| `exit?` | `SplashScreenExit` | How it leaves. Default `'fade'`. |
| `enter?` | `SplashScreenEnter` | How the content arrives. Default `'rise'`. |
| `title?` | `string` | The app's name, under the mark. |
| `description?` | `string` | One line under the title. Say what is happening, not "Loading…". |
| `message?` | `string` | The line under the indicator. Changing it fades the new one in. |
| `progress?` | `number` | How far along, 0–100. Left out, the indicator is indeterminate — which is the honest answer unless you really are counting something. |
| `percent?` | `boolean` | Show the percentage beside the bar. Only with a real `progress`. Default `false`. |
| `simulate?` | `boolean` | Move an indeterminate bar along on its own, up to about 90%. Default `false`. |
| `halo?` | `boolean` | A ring that pulses out of the logo. Costs nothing, reads as alive. Default `false`. |
| `image?` | `string` | Background photograph, for `variant="image"`. |
| `minDuration?` | `number` | The shortest time it may be on screen once shown, in ms. What stops a 40ms boot from flashing a splash at somebody. Default `600`. |
| `appearAfter?` | `number` | Wait this long before showing it at all, in ms. An app that becomes ready inside the delay never shows a splash — the best splash screen is the one nobody had to see. Default `0`. |
| `duration?` | `number` | How long the exit takes, in ms. Default `520`. |
| `autoHide?` | `boolean \| number` | When an uncontrolled splash takes itself off: `true` waits for the page to finish loading, a number is a plain timeout in ms, `false` leaves it up until something sets `open`. Default `true`. |
| `lockScroll?` | `boolean` | Stop the page behind it scrolling while it is up. Default `true`. |
| `portalTo?` | `PortalTarget` | Where the overlay is moved to. `null` keeps it where it is. |
| `inline?` | `boolean` | Inside its container instead of over the viewport. Default `false`. |
| `label?` | `string` | What a screen reader calls it. |
| `onhide?` | `() => void` | The exit has started. |
| `onhidden?` | `() => void` | The splash is off screen and out of the DOM. |
| `logo?` | `Snippet` | The mark. An `<img>`, an inline `<svg>`, anything. |
| `children?` | `Snippet` | Extra content between the words and the indicator. |
| `actions?` | `Snippet` | Buttons — a "Retry" for a boot that failed, usually. |
| `footer?` | `Snippet` | Pinned to the bottom edge: version, byline, legal line. |
| `class?` | `string` |  |
| `classes?` | `SplashScreenClasses` | Per-part Tailwind overrides. `class` still covers the root. |

### SplitButton

`import { SplitButton } from 'omaris'`

MD3 Expressive split button.

#### Use it for

- One obvious default with variants behind it: Save / Save as, Save and close;
  Export CSV / PDF, XLSX; Merge / Squash, Rebase.
- A set of related commands that would otherwise be three buttons — the default
  stays one press away, the rest one more.
- The primary action of a dashboard header: `variant="filled"`, `size="sm"`
  (the defaults), `loading` while it runs.

#### Not for

- A menu with no default — "Actions", "More" → a [Button](/docs/components/button)
  or [Icon Button](/docs/components/icon-button) as the trigger of a
  [Menu](/docs/components/menu).
- A choice that stays chosen → [Segmented Button](/docs/components/segmented-button)
  or [Select](/docs/components/select). The menu here holds commands, not state.
- Two actions of equal weight → two buttons in a
  [Button Group](/docs/components/button-group).
- A card's whole action set → a [Menu](/docs/components/menu) behind a "more"
  icon button. A split button with six items is a menu with a hat on.

#### Do

- Make the wide half the thing pressed nine times in ten, and repeat it in the
  menu so the list is complete on its own.
- Fill `menu` with `MenuItem`s and give `menuLabel` a real name — "More save
  options" — since that half is an icon-only button.
- Match `variant`, `tone` and `size` to the [Button](/docs/components/button)s
  beside it; both halves share them, so it never looks like a guest.
- Use `loading` for the whole control; it disables the menu half too, so the
  list cannot open mid-save.

#### Don't

- Bury Delete in the menu under a `filled` primary. Give it its own
  `tone="destructive"` button and a [Dialog](/docs/components/dialog).
- Rename the wide half to whatever was picked last; the default should stay
  predictable.
- Use `variant="text"`; without a fill or a border the seam between the halves
  disappears. `filled`, `tonal` and `outlined` show it.

#### Pairs with

- [Button](/docs/components/button), [Menu](/docs/components/menu),
  [Button Group](/docs/components/button-group), [Dialog](/docs/components/dialog),
  [Toast](/docs/components/toast)

Parts (`classes`): `action` `trigger` `chevron`

| Prop | Type | Notes |
| --- | --- | --- |
| `label?` | `string` | Label of the main action. |
| `variant?` | `ButtonVariant` | Default `'filled'`. |
| `tone?` | `ButtonTone` | Default `'primary'`. |
| `size?` | `ButtonSize` | Default `'sm'`. |
| `disabled?` | `boolean` | Default `false`. |
| `loading?` | `boolean` | Default `false`. |
| `open?` | `boolean` | Menu open state. Bindable. Default `false`. |
| `side?` | `AnchorSide` | Default `'bottom'`. |
| `align?` | `AnchorAlign` | Default `'end'`. |
| `menuLabel?` | `string` | Accessible name for the half that opens the menu. Default `'More actions'`. |
| `onclick?` | `(event: MouseEvent) => void` | The default action. |
| `class?` | `string` |  |
| `classes?` | `SplitButtonClasses` | Per-part Tailwind overrides. `class` still covers the root. |
| `icon?` | `Snippet` | Leading icon on the main half. |
| `children?` | `Snippet` | Rich label, in place of `label`. |
| `menu?` | `Snippet` | The menu's items. |

### StatCard

`import { StatCard } from 'omaris'`

The KPI tile every dashboard opens with: a label, one number, and how that number moved.

#### Use it for

- The KPI row at the top of a dashboard — revenue, orders, active users — in a
  grid that goes one, two, then four columns wide.
- One number and how it moved: `delta` as a fraction (`0.124` is +12.4%) with a
  `deltaLabel` that says against what — "vs last week".
- A metric where down is the good news — churn, refunds, response time — with
  `invert`, so a fall is green and a rise is red.
- A trend under the figure: a `Sparkline` from `omaris/chart` in the `chart`
  snippet.
- A tile that opens the report behind it: `href` or `onclick` makes the whole
  tile one target.

#### Not for

- A chart that is the point of the card → [Charts](/docs/components/chart) in a
  [Card](/docs/components/card); a stat card's chart is a sparkline under a
  number.
- Several figures about one thing — an order's total, tax and delivery →
  [Data List](/docs/components/data-list).
- A count on an icon or a tab → [Badge](/docs/components/badge).
- Progress towards a target — storage used, a quota →
  [Progress](/docs/components/progress) or [Gauge](/docs/components/gauge).

#### Do

- Pass numbers, not strings, and describe them with `format` — currency,
  `notation: 'compact'`, fraction digits. Digits stay Western in every locale.
- Keep the label to a couple of words; it truncates rather than wrapping.
- Use `loading` while the figure is on its way. The label stays and the tile
  keeps its height, so the row does not jump when the numbers land.
- Pick one `variant` for the whole row — `elevated` on a plain page, `filled`
  inside another surface.

#### Don't

- Pass a delta already multiplied by 100 — `12.4` reads as +1,240%. Use
  `0.124`, or `deltaFormat={{ style: 'decimal' }}` for a delta that is a count.
- Put a button or a link inside a tile that has `href` or `onclick`; the tile
  is already the target.
- Turn on `animate` for a whole grid of tiles that refresh every few seconds;
  count up the one figure that matters.
- Colour a tile's value by hand to say good or bad — that is what the delta
  chip and `invert` are for.

#### Pairs with

- [Charts](/docs/components/chart) (the `Sparkline`),
  [Card](/docs/components/card), [Skeleton](/docs/components/skeleton),
  [Table](/docs/components/table), [Segmented Button](/docs/components/segmented-button)
  for the date range above the row

Parts (`classes`): `root` `header` `body` `label` `icon` `value` `trend` `delta` `deltaLabel` `chart` `footer`

| Prop | Type | Notes |
| --- | --- | --- |
| `label?` | `string` | What is being measured — "Revenue", "Active users". |
| `value?` | `string \| number` | The figure. A number is formatted with `format` and `locale`, in Western digits whatever the locale; a string is shown as given, for a value you have already formatted ("4m 12s", "—"). |
| `format?` | `Intl.NumberFormatOptions` | `Intl.NumberFormat` options for a numeric `value` — currency, `notation: 'compact'`, fraction digits. The numbering system is pinned to Western digits on top of whatever you pass. |
| `locale?` | `string` | BCP-47 tag for the value and the delta. Defaults to the runtime's. |
| `delta?` | `number` | The change, as a fraction: `0.124` is +12.4%, `-0.03` is −3%. The arrow and the colour come from its sign; the chip shows its size. |
| `deltaFormat?` | `Intl.NumberFormatOptions` | How `delta` is written. Defaults to a percentage with at most one fraction digit. Pass `{ style: 'decimal' }` for a delta that is a count rather than a ratio ("+3 orders"). |
| `deltaLabel?` | `string` | What the delta is measured against — "vs last week". |
| `trend?` | `StatCardTrend` | Which way it moved. Derived from the sign of `delta`; set it for a trend you know without a delta to show. |
| `invert?` | `boolean` | Down is the good direction — churn, refunds, latency. Swaps which trend is coloured as success and which as destructive; the arrow still points the way the number went. Default `false`. |
| `variant?` | `CardVariant` | Card surface, as on `Card`. Default `'outlined'`. |
| `size?` | `CardSize` | Padding, gap and radius, as on `Card`; the value's type role steps with it. Default `'md'`. |
| `tone?` | `Tone` | The icon container's colour role. One of `primary`, `secondary`, `tertiary`, `destructive`, `success`, `warning`, `info`. Default `'primary'`. |
| `loading?` | `boolean` | Swap the value, the delta and the chart for skeletons. The label stays, since you know it already, and the tile keeps its height. Default `false`. |
| `animate?` | `boolean` | Count up to a numeric `value` on mount, and tween between values as it changes. Off by default, and skipped entirely under reduced motion. Default `false`. |
| `ripple?` | `boolean` | Ripple on press. Pressable tiles only. Default `true`. |
| `class?` | `string` |  |
| `classes?` | `StatCardClasses` | Per-part Tailwind overrides. `class` still covers the root. |
| `icon?` | `Snippet` | An icon, drawn in a tonal square at the top end of the tile. |
| `chart?` | `Snippet` | A chart along the bottom — a `Sparkline` from `omaris/chart`. |
| `footer?` | `Snippet` | A last line — a link to the report, when the figure was updated. |
| `shape?` | `ButtonShape` | Pill (`round`) or MD3 rounded rectangle (`square`). |
| `confetti?` | `boolean \| ConfettiOptions` | Confetti on press. `true` for the default burst, or any `ConfettiOptions` — `confetti={{ preset: 'fireworks' }}`. |
| `toggle?` | `boolean` | Turns the button into a two-state toggle driven by `pressed`. Ignored when `href` is set — a link has no pressed state. |
| `pressed?` | `boolean` | Selected state of a toggle button. Bindable. |
| `children?` | `Snippet` |  |

### StatusIncident

`import { StatusIncident } from 'omaris'`

One incident, and the thread of updates under it.

#### Use it for

- The page people open when something looks broken: one sentence at the top,
  the services under it, and what happened recently.
- A per-service uptime history, the ninety-day bar. It answers "is it usually
  working".
- An incident and its thread. `StatusIncident` keeps every update in order
  and badges the incident with the latest one.
- A status strip inside an app that is not about status: `emphasis="quiet"`,
  or `StatusIndicator` on its own beside a region, a queue or a host.
- A wallboard: `emphasis="solid"` is the accent at full strength, readable
  across a room.

#### Not for

- A metric over time, like latency or error rate → [Chart](/docs/components/chart).
  The bar here is categorical: each day is a state, not a number.
- One thing's state inline in a table or list → a [Badge](/docs/components/badge)
  or a [Chip](/docs/components/chip). `StatusIndicator` is for a row where
  the state is the point.
- Progress through a task you started → [Progress](/docs/components/progress).
- Telling someone their own action failed → [Toast](/docs/components/toast) or
  [Alert](/docs/components/alert). This page is about the system.

#### Do

- Compute the banner with `worstStatus()`. The overall state of a system is
  its worst part.
- Always pass `updatedAt` (or `updatedLabel`). A status page with no
  timestamp looks broken.
- Give `history` oldest first. Days that do not fit are dropped from the
  front, so the most recent ones stay on screen.
- Use the levels as meant: `degraded` is slow, `partial` is some of it down,
  `major` is all of it.
- Write `note` on the bad days. It is what the hover readout shows.
- Keep resolved incidents on the page, `muted`. The history is the
  credibility.

#### Don't

- Rely on the dot alone. `StatusIndicator` ships its label because green and
  amber are the same dot to many readers.
- Mark planned work as an outage. `maintenance` is left out of the uptime sum
  on purpose.
- Show ninety focusable bars. The track is one `role="img"` with the row
  summarised.
- Round uptime up to 100%. `formatUptime` refuses to, and so should whatever
  feeds it.

#### Pairs with

- [Chart](/docs/components/chart), [Card](/docs/components/card),
  [Badge](/docs/components/badge), [Alert](/docs/components/alert),
  [Empty](/docs/components/empty), [Button](/docs/components/button)

Parts (`classes`): `root` `header` `title` `stage` `when` `scope` `chip` `updates` `update` `updateHead` `updateStage` `updateWhen` `body`

| Prop | Type | Notes |
| --- | --- | --- |
| `title` | `string` | What happened, in a line. |
| `level?` | `StatusLevel` | How bad it was. Colours the title's marker. Default `'major'`. |
| `startedAt?` | `Date \| string` | When it started. |
| `services?` | `string[]` | What it affected. Default `[]`. |
| `updates?` | `IncidentUpdate[]` | The thread. Given oldest first or newest first; it is sorted. Default `[]`. |
| `muted?` | `boolean` | Dim it — for a resolved incident in a history list. Default `false`. |
| `locale?` | `string` |  |
| `children?` | `Snippet` | Replaces the update thread. |
| `class?` | `string` |  |
| `classes?` | `StatusIncidentClasses` | Per-part Tailwind overrides. `class` still covers the root. |

### StatusIndicator

`import { StatusIndicator } from 'omaris'`

A dot, and what it means.

Parts (`classes`): `root` `dot` `label`

| Prop | Type | Notes |
| --- | --- | --- |
| `level` | `StatusLevel` |  |
| `label?` | `string \| false` | The words beside the dot. `false` hides them, a string replaces them. |
| `size?` | `StatusIndicatorSize` | One of `sm`, `md`, `lg`. Default `'md'`. |
| `pulse?` | `boolean` | Beat the halo — for a page that is watching a live feed. Default `false`. |
| `class?` | `string` |  |
| `classes?` | `StatusIndicatorClasses` |  |

### StatusPage

`import { StatusPage } from 'omaris'`

The page itself: one sentence at the top, and everything else under it.

Parts (`classes`): `root` `banner` `mark` `headline` `title` `updated` `actions` `section` `sectionHeader` `sectionTitle` `group` `timeline` `empty`

| Prop | Type | Notes |
| --- | --- | --- |
| `level` | `StatusLevel` | The one thing the page says. `worstStatus()` computes it from the parts. |
| `title?` | `string` | Replaces the sentence the level would otherwise write. |
| `updatedAt?` | `Date \| string` | When the numbers were last true. |
| `updatedLabel?` | `string` | Replaces "Checked <time>". |
| `emphasis?` | `StatusPageEmphasis` | One of `tonal`, `solid`, `quiet`. Default `'tonal'`. |
| `locale?` | `string` |  |
| `actions?` | `Snippet` | Buttons on the right of the banner — subscribe, refresh, history. |
| `banner?` | `Snippet` | Replaces the whole banner. |
| `children?` | `Snippet` | Everything under it: services, incidents, whatever else. |
| `class?` | `string` |  |
| `classes?` | `StatusPageClasses` | Per-part Tailwind overrides. `class` still covers the root. |

### StatusService

`import { StatusService } from 'omaris'`

One service, and the last however many days of it.

Parts (`classes`): `root` `header` `name` `description` `state` `track` `bar` `readout` `legend` `legendRule` `uptime`

| Prop | Type | Notes |
| --- | --- | --- |
| `name` | `string` | What the service is called. |
| `description?` | `string` | A line under it — what it covers, or which region. |
| `level?` | `StatusLevel` | How it is right now. Defaults to the most recent point's level. |
| `history?` | `StatusPoint[]` | Oldest first. Anything that does not fit is dropped from the front. Default `[]`. |
| `uptime?` | `number` | Uptime to print, `0`–`100`. Computed from `history` when left out — pass it when the real number comes from somewhere with more data than the bars are showing. |
| `legend?` | `string \| false` | The words under the bar. `false` drops the whole legend row. |
| `labels?` | `{ state?: string \| false; uptime?: string; today?: string }` | The words the row writes for itself, for a page that is not in English: the state beside the dot, and the two fixed words in the legend. One prop rather than three, because they are always replaced together — a row that says "جاهزية" and "Today" is worse than either. `state: false` leaves the dot alone, with the state still read out to a screen reader. |
| `minBarWidth?` | `number` | How thin the bars may get before older days are dropped, in px. Default `4`. |
| `density?` | `StatusServiceDensity` | One of `comfortable`, `compact`. Default `'comfortable'`. |
| `locale?` | `string` | Locale for the dates and the percentage. |
| `children?` | `Snippet` | Extra content under the legend — a link to the region's own page. |
| `class?` | `string` |  |
| `classes?` | `StatusServiceClasses` | Per-part Tailwind overrides. `class` still covers the root. |

### Stepper

`import { Stepper } from 'omaris'`

Wizard progress — where you are in a checkout, an onboarding, a form too long for one screen.

#### Use it for

- A task split over a few screens — checkout, onboarding, a long form —
  where knowing how many steps are left is what keeps people going.
- A wizard that must be done in order: `linear` (the default) lets people go
  back to a finished step but not skip ahead.
- Sections that can be filled in any order: `linear={false}`, with `complete`
  on the ones that are done.
- A setup flow in a narrow column: `orientation="vertical"`, each step's
  content opening under it.

#### Not for

- Switching between views of the same thing → [Tabs](/docs/components/tabs).
- The history of what already happened → [Timeline](/docs/components/timeline).
- A single wait with a known length → [Progress](/docs/components/progress).
- Paging through results → [Pagination](/docs/components/pagination).

#### Do

- Keep it to three to five steps with one- or two-word titles; the collapsed
  view on a phone shows the title of the current one.
- Drive it with `bind:step` and switch the content on the same value, with
  Back and Next [Buttons](/docs/components/button) under it.
- Validate before moving on, and mark the step with `error` — a string is
  shown in place of its description.
- Set `step` to the number of steps when the task is finished, so every step
  reads as complete.

#### Don't

- Hide a required step behind `disabled` to force an order; that is what
  `linear` does.
- Use it for a single form that fits on one screen — the steps are overhead.
- Rely on the step circles alone for navigation on a phone; below 36rem they
  collapse to a summary, so Back and Next have to be there.

#### Pairs with

- [Button](/docs/components/button), [Input](/docs/components/input),
  [Radio](/docs/components/radio), [Data List](/docs/components/data-list)
  for the review step, [Dialog](/docs/components/dialog) or
  [Sheet](/docs/components/sheet) for a wizard that opens over a page

Parts (`classes`): `root` `list` `compact` `summary` `next` `progress`

| Prop | Type | Notes |
| --- | --- | --- |
| `step?` | `number` | The current step's index, from 0. Bindable. Set it to the number of steps to mark every one complete — the wizard is finished. Default `0`. Bindable. |
| `orientation?` | `'horizontal' \| 'vertical'` | A row across the top, or a column with each step's content under it. One of `horizontal`, `vertical`. Default `'horizontal'`. |
| `linear?` | `boolean` | Steps behind the current one can be revisited; steps ahead cannot be skipped to. Off, any step can be picked at any time. Default `true`. |
| `label?` | `string` | Accessible name for the list of steps — "Checkout". Default `'Progress'`. |
| `collapse?` | `boolean` | Let a horizontal stepper narrower than 36rem collapse to "Step 2 of 4 · Title" over a progress bar. Off, it stays a row and its titles truncate. Default `true`. |
| `counter?` | `(step: number, total: number) => string` | How the collapsed view counts: `(2, 4) => 'Step 2 of 4'`. Default `(current, total) => `Step ${current} of ${total}``. |
| `upNext?` | `(title: string) => string` | How the collapsed view names what comes next: `'Review' => 'Next: Review'`. Default `(title) => `Next: ${title}``. |
| `class?` | `string` |  |
| `classes?` | `StepperClasses` | Per-part Tailwind overrides. `class` still covers the root. |
| `children?` | `Snippet` | The `StepperItem`s. |

### StepperItem

`import { StepperItem } from 'omaris'`

One step of a `Stepper`: a numbered indicator, a title, and the line to the next step, which fills in as the step is completed.

Parts (`classes`): `root` `step` `indicator` `body` `title` `description` `connector` `fill` `content`

| Prop | Type | Notes |
| --- | --- | --- |
| `title` | `string` | The step's name — "Shipping". Also what the collapsed view shows. |
| `description?` | `string` | A line under the title — "Where it's going". |
| `error?` | `boolean \| string` | Something is wrong with this step: the indicator turns destructive and says so. A string is shown in place of the description. Default `false`. |
| `complete?` | `boolean` | Mark the step done regardless of where the stepper is — a section of a non-linear form filled in out of order. Leave it unset and the position decides. |
| `disabled?` | `boolean` | The step cannot be picked, even when the stepper would allow it. Default `false`. |
| `completeLabel?` | `string` | Spoken after a completed step's title. Default `'completed'`. |
| `class?` | `string` |  |
| `classes?` | `StepperItemClasses` | Per-part Tailwind overrides. `class` still covers the root. |
| `icon?` | `Snippet` | An icon in place of the step's number. A completed step still shows its tick. |
| `children?` | `Snippet` | Vertical only: the step's content, opened while it is the current step. |

### SwipeItem

`import { SwipeItem } from 'omaris'`

A row you can swipe aside to get at its actions.

Parts (`classes`): `clip` `actions` `action` `row`

| Prop | Type | Notes |
| --- | --- | --- |
| `startActions?` | `SwipeAction[]` | Actions behind the leading edge — swiping toward the end reveals them. Default `[]`. |
| `endActions?` | `SwipeAction[]` | Actions behind the trailing edge. Default `[]`. |
| `fullSwipe?` | `boolean \| SwipeSide` | Let a swipe clear across the row fire that side's first action with no second press. `true` arms both edges. Default `false`. |
| `fullSwipeThreshold?` | `number` | Fraction of the row a full swipe has to cross. Default `0.55`. |
| `labels?` | `boolean` | Draw the labels under the icons. Default `true`. |
| `open?` | `SwipeSide \| null` | Which side is showing. Bindable — set it to open or close the row. Default `null`. Bindable. |
| `disabled?` | `boolean` | Default `false`. |
| `onopen?` | `(side: SwipeSide \| null) => void` | Fires when the row settles open or closed. |
| `ondismiss?` | `() => void` | Fires once a dismissing action has played out and the row has collapsed. |
| `class?` | `string` |  |
| `classes?` | `SwipeItemClasses` | Per-part Tailwind overrides. `class` still covers the root. |
| `start?` | `Snippet` | Custom leading pane, in place of `startActions`. |
| `end?` | `Snippet` | Custom trailing pane, in place of `endActions`. |
| `children?` | `Snippet` |  |

### Switch

`import { Switch } from 'omaris'`

MD3 switch.

#### Use it for

- One setting that takes effect the moment it flips: notifications, dark mode,
  Wi-Fi. No Save button after it.
- A settings screen. `labelPosition="start"` puts the label first and the
  switch at the trailing edge, like a row in a [List](/docs/components/list).
- A row that needs a second line. `description` says what "on" does.
- A state that must be clear at a glance, like a safety toggle or a row seen
  in monochrome. Pass `icons`.

#### Not for

- A choice submitted with a form → [Checkbox](/docs/components/checkbox). If a
  Save button follows it, it is a checkbox.
- Several items from a set → [Checkbox](/docs/components/checkbox). One switch
  per table row is too many toggles.
- One of several → [Radio](/docs/components/radio) or
  [Segmented Button](/docs/components/segmented-button).
- A momentary on/off in a toolbar, like mute or bookmark → a `toggle`
  [Icon Button](/docs/components/icon-button).
- Revealing a section of a form → [Accordion](/docs/components/accordion).

#### Do

- Label it with the thing, not the state: "Email notifications", not
  "Enable" or "On".
- Apply the change on `onchange` at once. If it can fail, flip the switch back
  and say why in a [Toast](/docs/components/toast).
- Keep `size="md"` in a settings list. `sm` fits a table cell or a dense card
  header.
- Put a destructive setting like "Delete after 30 days" behind a
  [Dialog](/docs/components/dialog) before it applies.

#### Don't

- Disable a switch without saying why. Explain in `description`.
- Rely on `tone` to carry meaning. It only colours the on state; `icons` makes
  on and off legible without colour.
- Add a Save button under a page of switches. Either they apply as they flip,
  or they are checkboxes.

#### Pairs with

- [Checkbox](/docs/components/checkbox), [List](/docs/components/list),
  [Label](/docs/components/label), [Card](/docs/components/card),
  [Toast](/docs/components/toast)

Parts (`classes`): `root` `track` `handle` `state` `knob` `input` `icon` `label` `description`

| Prop | Type | Notes |
| --- | --- | --- |
| `tone?` | `SwitchTone` | One of `primary`, `secondary`, `tertiary`, `destructive`, `success`, `warning`, `info`. Default `'primary'`. |
| `size?` | `SwitchSize` | One of `md`, `lg`. Default `'md'`. |
| `checked?` | `boolean` | Bindable. Default `false`. |
| `icons?` | `boolean` | Draw a tick (on) and a cross (off) inside the handle. Default `false`. |
| `label?` | `string` |  |
| `description?` | `string` |  |
| `labelPosition?` | `'start' \| 'end'` | Put the label before the switch — the settings-row layout. Default `'end'`. |
| `haptics?` | `boolean` | A haptic tap when it flips. Follows the shared `haptics` store; `false` opts this switch out. Default `true`. |
| `sound?` | `boolean` | A sound cue when it flips. Follows the shared `sound` store; `false` opts this switch out. Default `true`. |
| `class?` | `string` |  |
| `classes?` | `SwitchClasses` | Per-part Tailwind overrides. `class` still covers the root. |
| `children?` | `Snippet` |  |
| `ref?` | `HTMLInputElement \| null` | Default `null`. Bindable. |

### Tab

`import { Tab } from 'omaris'`

One tab in a `TabList`. Its `value` names the `TabPanel` it opens.

#### Use it for

- Views of one thing within a page, like a customer's orders, invoices and
  notes, where the URL stays the same. `Tabs` holds the value, `TabList` the
  row, one `TabPanel` per `Tab`.
- A second level inside a primary tab's content: `variant="secondary"`. Its
  indicator runs the width of the tab.
- More tabs than the width: `scrollable`. A few equal ones on a phone:
  `fitted`.
- Forms across tabs. `keepMounted` on the panel keeps typed values, scroll and
  in-flight work alive while it is hidden.
- A phone. `swipeable` on `Tabs`, with the panels wrapped in `TabPanels`, adds
  the sideways drag a touch screen expects. The indicator follows the finger.

#### Not for

- Moving between the app's screens → [Navigation Drawer](/docs/components/navigation-drawer)
  or [Navigation Bar](/docs/components/navigation-bar).
- Two or three filters on the same list → [Segmented Button](/docs/components/segmented-button)
  or filter [Chips](/docs/components/chip).
- Steps that must happen in order → a [Button](/docs/components/button) for
  next and [Progress](/docs/components/progress) for how far.
- Sections people read top to bottom → headings and a [Toc](/docs/components/toc).

#### Do

- Keep labels to a word or two, sentence case, about the same length. The
  indicator hugs the label on a primary tab, so a long one stands out.
- Use `stacked` icons on primary tabs only. Secondary tabs are text.
- Put a live count in `badge`, like open tickets. Nothing that never changes.
- Sync `value` with the URL (`?tab=`) when a person might share or refresh
  the page.
- Turn `swipeable` on where the tabs are a phone's main surface, pair it with
  `fitted` so the whole row is visible, and mark a panel's own horizontal
  scroller with `data-swipe-ignore` so its gesture wins over the tab swipe.

#### Don't

- Nest primary inside primary. The second level is `secondary`; there is no
  third.
- Mix icon tabs and text-only tabs in one list.
- Put an action like "+ New" in the row. A tab opens a panel; an action is a
  [Button](/docs/components/button) beside it.
- Squeeze six tabs into a phone width. `scrollable` swipes on one line;
  `fitted` at six truncates every label.
- Turn `swipeable` on for heavy panels; every panel is mounted at once. Never
  rely on the swipe alone either. A mouse and a keyboard never see it.

#### Pairs with

- [Top App Bar](/docs/components/top-app-bar), [Segmented Button](/docs/components/segmented-button),
  [Badge](/docs/components/badge), [Card](/docs/components/card),
  [Toc](/docs/components/toc)

| Prop | Type | Notes |
| --- | --- | --- |
| `value` | `string` | Identifies the tab, and the panel it controls. |
| `label?` | `string` | Label text. Use children for rich content. |
| `stacked?` | `boolean` | Stack the icon above the label — MD3's two-line primary tab. Default `false`. |
| `badge?` | `Snippet` | A count or dot rendered after the label. |
| `icon?` | `Snippet` | Leading icon. |
| `class?` | `string` |  |
| `children?` | `Snippet` |  |

### Table

`import { Table } from 'omaris'`

Data table.

#### Use it for

- Figures people scan like a spreadsheet. The default `variant="grid"` rules
  every cell on a white page, framed by a tinted header and footer; `group`
  spans a header over sibling columns (USD over Debit and Credit), `summary`
  adds a totals row, `rowNumbers` the `#` column, `fullscreen` a button that
  gives the sheet the whole screen.
- A quick look at any array. `<Table {rows} />` reads the columns off the
  first row; `format: 'number' | 'decimal' | 'percent' | 'date'` or any `Intl`
  options formats a column in Western digits.
- Rows people read across and compare. Pass `columns` and `rows`; each feature
  is one prop: `search`, `selection`, `pagination={20}`, `sortable` on a
  column, `filtering` as chips on one line.
- Rows that live on a server. `manual` on `sorting`, `filtering` or
  `pagination` hands that stage back: the table reports through that feature's
  `onchange`, renders what it is given, and `pagination.total` is the count.
- A dashboard's main list: an Avatar for the customer, a Badge for status,
  aligned money, a Sparkline per row, a row menu, a bulk bar through
  `selectionActions` once rows are picked, and `sticky` with `maxHeight`.
- Loading and empty states. `loading` draws skeleton rows at the real row
  height; the `empty` snippet puts an Empty inside the frame.

#### Not for

- Rows of one to three lines with a leading avatar or icon, especially on a
  phone → [List](/docs/components/list). It has swipe actions and no header
  row.
- Items whose picture is the point → a [Card](/docs/components/card) grid or
  [Masonry](/docs/components/masonry).
- Things that move between stages → [Kanban](/docs/components/kanban).
- A few key–value pairs, like a settings summary →
  [Text](/docs/components/text) as `dt` and `dd`.
- Cells people edit in place → nothing here. Cells are read-only; `cell` only
  changes how a column renders.

#### Do

- Keep the `grid` default for money, ledgers and anything read cell by cell.
  `outlined` for a list of people or things with avatars and badges, where
  rules between columns are noise.
- Put totals in `summary` rather than a row in `rows`: it follows the search
  and filters and never sorts into the middle. Extra footer rows go in the
  `foot` snippet, with the `cell` class it hands you.
- Keep `density="compact"`, the default, in a dashboard. `comfortable` for
  rows people tap on a tablet; `spacious` for a few rows of prose.
- Give a column `value` so it sorts and searches on the number behind the
  display, and `cell` to take over the markup without losing that.
- Set `hideBelow` on columns a phone does not need. The toolbar already
  reflows into search, then filters, then the pager.
- Set `rowKey` to a stable id so a selection survives a re-sort, and `label`
  so the table has an accessible name.
- Mark at most one filter `inline`: the one worth a single press.

#### Don't

- Hold search, sort and page in `$state` unless the page needs to know. Every
  feature is uncontrolled by default and bindable when needed.
- Make every column `sortable`. It hides which ones matter.
- Add a second empty state under the table. The `empty` snippet is already
  inside the frame.
- Let the page scroll sideways. The viewport scrolls, and `hideBelow` drops
  what will not fit.

#### Pairs with

- [Badge](/docs/components/badge), [Avatar](/docs/components/avatar),
  [Chart](/docs/components/chart), [Pagination](/docs/components/pagination),
  [Sheet](/docs/components/sheet), [Empty](/docs/components/empty)

Parts (`classes`): `root` `toolbar` `search` `filterBar` `toolbarActions` `scroller` `table` `head` `headRow` `headCell` `groupCell` `sorter` `body` `row` `cell` `pick` `rowNumber` `empty` `foot` `footCell` `footer` `caption`

| Prop | Type | Notes |
| --- | --- | --- |
| `columns?` | `TableColumn<T>[]` | What to show and how. Leave it out and the columns are read off the first row — every field, a readable header, all sortable. |
| `rows` | `T[]` |  |
| `variant?` | `TableVariant` | One of `plain`, `surface`, `outlined`, `grid`. Default `'grid'`. |
| `density?` | `TableDensity` | One of `compact`, `comfortable`, `spacious`. Default `'compact'`. |
| `striped?` | `boolean` | Default `false`. |
| `hoverable?` | `boolean` | Default `true`. |
| `sticky?` | `boolean` | Pin the header. Pair with `maxHeight`. Default `false`. |
| `maxHeight?` | `string` | Height of the scroll area when `sticky`. Any CSS length. Default `'32rem'`. |
| `rowKey?` | `(row: T, index: number) => Key` | Stable key per row. Falls back to the index. |
| `sorting?` | `TableSorting` | Current sort. Columns opt in with `sortable`, so this is state rather than a switch — leave it off and sortable columns still sort, the table just keeps the sort itself. Default `undefined`. Bindable. |
| `search?` | `boolean \| TableSearch` | The search box. Passing it at all is what puts it in the toolbar. Default `undefined`. Bindable. |
| `filtering?` | `TableFilter<T>[] \| TableFiltering<T>` | The filter bar. An array is the filters; the object form adds the picked state and an `onchange`. Options are derived from the rows when a filter doesn't list its own. Default `undefined`. Bindable. |
| `pagination?` | `boolean \| number \| TablePagination` | Pagination. `true` takes the default page size, a number *is* the page size, and the object form carries the page, the rows-per-page choices and the server-side `total`. Default `undefined`. Bindable. |
| `selection?` | `boolean \| TableSelection<Key>` | Row selection. Passing it at all is what adds the checkbox column. Default `undefined`. Bindable. |
| `columnVisibility?` | `boolean \| TableColumnVisibility` | The column-visibility menu. Passing it at all is what adds it. Default `undefined`. Bindable. |
| `fullscreen?` | `boolean \| TableFullscreen` | A button that lets the table fill the screen, header pinned, for the moment a wide sheet needs every pixel. Escape comes back. Default `undefined`. Bindable. |
| `rowNumbers?` | `boolean` | A leading `#` column numbering the rows, the way a sheet does. Default `false`. |
| `summaryLabel?` | `string` | Label of the summary row the columns' `summary` builds. Default `'Total'`. |
| `foot?` | `Snippet<[{ rows: T[]; cell: string; span: number }]>` | Extra rows under the summary — a net figure spanning two columns, say. Write `<tr>`s; `cell` is the class a footer cell takes, `rows` what the search and filters left, `span` the column count. |
| `onrowclick?` | `(row: T, index: number) => void` | Called when a row is pressed. Makes rows interactive. |
| `loading?` | `boolean` | Draw skeletons while the data is on its way. Default `false`. |
| `loadingRows?` | `number` | Default `5`. |
| `emptyText?` | `string` | Message when there are no rows at all. Default `'Nothing here yet'`. |
| `noResultsText?` | `string` | Message when the filters or the search excluded everything. Default `'No rows match your filters'`. |
| `label?` | `string` | Accessible name for the table. |
| `caption?` | `string` | Visible caption under the table. |
| `class?` | `string` |  |
| `classes?` | `TableClasses` | Per-part Tailwind overrides. `class` still covers the root. |
| `actions?` | `Snippet` | Extra controls on the trailing edge of the toolbar. |
| `selectionActions?` | `Snippet<[Key[]]>` | Replaces the toolbar's trailing edge while rows are selected. |
| `empty?` | `Snippet` | Rich empty state, in place of `emptyText`. |

### TableFilterControl

`import { TableFilterControl } from 'omaris'`

One filter in a table's toolbar.

| Prop | Type | Notes |
| --- | --- | --- |
| `label` | `string` |  |
| `options` | `TableFilterOption[]` |  |
| `selected` | `string[]` | Bindable. Default `[]`. |
| `single?` | `boolean` | Default `false`. |
| `inline?` | `boolean` | Lay the options out as toggle chips rather than behind a menu. |
| `format?` | `(value: string) => string` |  |
| `onchange?` | `(selected: string[]) => void` |  |

### TabList

`import { TabList } from 'omaris'`

The row of tabs, and the indicator that slides between them.

| Prop | Type | Notes |
| --- | --- | --- |
| `label?` | `string` | Accessible name for the tab set. |
| `divider?` | `boolean` | Draw the hairline the indicator rides on. Default `true`. |
| `scrollable?` | `boolean` | One line that scrolls sideways, for a set too wide to fit. Default `false`. |
| `class?` | `string` |  |
| `children?` | `Snippet` |  |

### TabPanel

`import { TabPanel } from 'omaris'`

The content behind one tab. Its `value` must match that tab's.

| Prop | Type | Notes |
| --- | --- | --- |
| `value` | `string` | Must match the `value` of the tab that opens it. |
| `keepMounted?` | `boolean` | Keep the panel mounted while hidden. Costs memory but preserves scroll position, form state and any in-flight work in the panel. Default `false`. |
| `class?` | `string` |  |
| `children?` | `Snippet` |  |

### TabPanels

`import { TabPanels } from 'omaris'`

The viewport the panels live in, and the thing a swipe moves.

| Prop | Type | Notes |
| --- | --- | --- |
| `threshold?` | `number` | Fraction of the width a drag has to cover before it counts as a move. A fast flick moves regardless. Default `0.25`. |
| `disabled?` | `boolean` | Turns the gesture off for this viewport, leaving the layout alone. Default `false`. |
| `class?` | `string` |  |
| `children?` | `Snippet` |  |

### Tabs

`import { Tabs } from 'omaris'`

MD3 tabs — a `TabList` of `Tab`s over one `TabPanel` per tab.

| Prop | Type | Notes |
| --- | --- | --- |
| `value?` | `string` | The selected tab's value. Bindable. Default `undefined`. |
| `variant?` | `TabsVariant` | MD3's two kinds. `primary` is the top-level one — bigger, with the indicator hugging the label. `secondary` sits inside a primary tab's content and runs its indicator the full width of the tab. Default `'primary'`. |
| `size?` | `TabsSize` | Default `'md'`. |
| `fitted?` | `boolean` | Share the width evenly rather than hugging the labels. Default `false`. |
| `swipeable?` | `boolean` | Let the panels be dragged sideways. Needs the panels wrapped in `TabPanels`, and mounts them all at once so there is something to drag to — so leave it off for a set whose panels are expensive. Default `false`. |
| `orientation?` | `TabsOrientation` | `vertical` stacks the tabs down the start edge beside the panels — a settings screen's sections. ↑ and ↓ move between them. Default `'horizontal'`. |
| `activation?` | `TabsActivation` | `automatic` shows a tab's panel as soon as the arrow keys reach it. `manual` only moves focus, and Enter or Space opens it — for panels that are expensive to show, or that fetch when they open. Default `'automatic'`. |
| `class?` | `string` |  |
| `children?` | `Snippet` |  |

### TagsInput

`import { TagsInput } from 'omaris'`

Free-form tags, typed into one field.

#### Use it for

- Free-form values the person types — keywords, labels, email recipients, allowed
  domains — bound as a `string[]` with `bind:value`.
- A list that is vetted as it grows: `validate` returns the reason a tag was
  refused and leaves the text in the box to fix; `unique` (on by default)
  refuses a repeat; `max` caps it and shows a count.
- Pasting a list from somewhere else — a comma- or newline-separated paste
  becomes one tag per piece, each vetted on its own.
- A form field like any other: inside a [Field](/docs/components/field), or
  with its own `label` and `supportingText`, in `Input`'s variants and sizes.

#### Not for

- Picking several from a known list → [Multi Select](/docs/components/multi-select);
  its `creatable` covers the occasional value that is not on the list.
- One free-text value → [Input](/docs/components/input); one choice from a
  list → [Combobox](/docs/components/combobox).
- Filters the person switches on and off → filter
  [Chips](/docs/components/chip) in a `ChipGroup`.
- Showing tags nobody edits → [Chips](/docs/components/chip) or
  [Badges](/docs/components/badge).

#### Do

- Say what separates tags in the `placeholder` or `supportingText` — "Separate
  with commas" — the first time it matters.
- Return a specific reason from `validate` — "Not an email address", not
  "Invalid" — and keep it short; it shares a line with the count.
- Pass `name` in a plain form: every tag posts as its own value under it.
- Localise `removeLabel`, `duplicateMessage` and `maxMessage` with the rest of
  the page's strings.

#### Don't

- Use it for values that must come from a fixed set; a typed tag that the
  server then rejects is worse than a list that never offered it.
- Put more than a line or two of tags in it — past about fifteen, the
  field is a list and wants to be a [List](/docs/components/list) with an
  add row.
- Set `required` expecting the browser to enforce it; the box is empty
  whenever a tag has been added. Check `value.length` yourself.

#### Pairs with

- [Field](/docs/components/field), [Chip](/docs/components/chip),
  [Multi Select](/docs/components/multi-select), [Input](/docs/components/input)

Parts (`classes`): `root` `field` `control` `label` `adornment` `affix` `action` `support` `counter` `list` `chip` `input`

| Prop | Type | Notes |
| --- | --- | --- |
| `value?` | `string[]` | The tags, in the order they were added. Bindable. Default `[]`. |
| `query?` | `string` | What is typed but not yet a tag. Bindable — handy for suggestions. Default `''`. Bindable. |
| `variant?` | `InputVariant` | Default `'outline'`. |
| `size?` | `InputSize` | One of `sm`, `default`, `lg`. Default `'default'`. |
| `label?` | `string` | Label above the field. Wired to the text box, so clicking it focuses. |
| `supportingText?` | `string` | Helper line under the field. A rejected tag's reason replaces it. |
| `invalid?` | `boolean` | Marks the field invalid. Inside a `Field`, defaults to the field's. |
| `required?` | `boolean` | Stars the label. Inside a `Field`, defaults to the field's. |
| `max?` | `number` | Most tags it takes. Adds an `n/max` count under the field. |
| `unique?` | `boolean` | Refuse a tag that is already there, ignoring case. Default `true`. |
| `validate?` | `(tag: string, value: string[]) => string \| true` | Vets a tag before it goes in. Return `true` to accept it, or the reason it was refused — that text shows under the field and the typed text stays put for fixing. |
| `duplicateMessage?` | `string` | Shown when `unique` refuses a tag. Default `'Already added.'`. |
| `maxMessage?` | `string` | Shown when a tag would go past `max`. Defaults to "Up to {max}." |
| `removeLabel?` | `(tag: string) => string` | Accessible name of a tag's ×. Default `(tag: string) => `Remove ${tag}``. |
| `onchange?` | `(value: string[]) => void` | Fires with the new list after every add and remove. |
| `class?` | `string` |  |
| `classes?` | `TagsInputClasses` | Per-part Tailwind overrides. `class` still covers the root. |
| `ref?` | `HTMLInputElement \| null` | Default `null`. Bindable. |

### Text

`import { Text } from 'omaris'`

Text — the one component every string in the app goes through, instead of a `<p>`, a `<span>` or a `<div>` with a size class on it.

#### Use it for

- Every string in the app: a heading, a paragraph, a cell, a caption.
  `variant` is how it looks, `as` is what it means.
  `<Text variant="title-md" as="h3">` is a card title that is also a heading.
- Five roles, three sizes each. `display-*` for a stat card's hero number,
  `headline-*` for page and section titles, `title-*` for cards and dialogs,
  `body-*` for prose and cells, `label-*` for chips, headers and timestamps.
- Text with its own meaning: `tone="muted"` for secondary text,
  `tone="destructive"` for an error. Everything else inherits, so text on a
  coloured surface stays legible.
- Figures. `tabular` lines up a column and stops a live counter twitching;
  `font="mono"` for ids, hashes and anything compared character by character.
- Clipping. `lines={1}` for a filename in a row, `lines={2}` for a card
  description.

#### Not for

- A label inside a component that already sets its type, like a
  [Button](/docs/components/button), [Chip](/docs/components/chip),
  [Badge](/docs/components/badge) or [Label](/docs/components/label) → pass the
  string. The component owns the `label-*` role.
- A block of code → [Code Block](/docs/components/code-block). `as="code"` is
  for one identifier inside a sentence.
- Long prose with its own headings, lists and links → the
  [Typography](/docs/typography) guide covers that scale.
- A `sr-only` span, a single glyph or a layout-only wrapper → a raw utility
  class. An emoji → `Emoji` from [Emoji Picker](/docs/components/emoji-picker).

#### Do

- Let `as` carry the semantics and `variant` the look. Set both when they
  differ; leave one out and it is inferred. `as="h2"` is `headline-md`; a
  variant alone is a `<p>` (a `<span>` for `label-*`).
- Pick the variant by the job of the text, not the size you want. Each variant
  sets size, line height, letter spacing and weight together. Needing
  `font-semibold` after `variant="title-md"` means the wrong variant.
- Leave `wrap` alone. Headings balance and body avoids orphans already. Set
  `wrap="nowrap"` with `lines={1}` only for a cell that must stay one line.
- On a dashboard card: `display-sm` is the metric, `title-md` the card's
  name, `body-sm` with `tone="muted"` the comparison under it.

#### Don't

- Write `<p class="text-sm text-muted-foreground">`. That is
  `<Text variant="body-sm" tone="muted">`, and it moves with the theme.
- Use `weight` to make a label bold. `label-lg` is already the weight buttons
  and tabs use.
- Put `tone="default"` on text inside a tinted card or a filled button. It
  goes illegible in dark mode. Let it inherit.
- Use `display-lg` twice on a screen. It is the one number the screen is
  about.

#### Pairs with

- [Card](/docs/components/card), [Table](/docs/components/table),
  [Label](/docs/components/label), [Badge](/docs/components/badge),
  [Typography](/docs/typography)

| Prop | Type | Notes |
| --- | --- | --- |
| `variant?` | `TextVariant` | How it looks — the type token minus `text-`. Pick by the job the text does: `display` is the one hero number on a screen, `headline` titles a page or section, `title` titles a card or dialog, `body` is prose and cell contents, `label` is buttons, chips, tabs and column headers. Each one carries size, line height, letter spacing and weight together. Defaults to `body-md`, or to the role that matches `as` when that is a heading. One of `display-lg`, `display-md`, `display-sm`, `headline-lg`, `headline-md`, `headline-sm`, `title-lg`, `title-md`, `title-sm`, `body-lg`, `body-md`, `body-sm`, `label-lg`, `label-md`, `label-sm`. |
| `as?` | `TextElement` | What it means. Defaults to `span` for `label-*` and `p` for everything else. Use a heading tag for anything that is one — the look does not make it a heading, this does. |
| `tone?` | `TextTone` | Colour role. Inherits from the surface by default, so a Text inside a coloured container stays legible; set it when the colour itself means something — `muted` for secondary copy, `destructive` for an error. One of `inherit`, `default`, `muted`, `primary`, `secondary`, `tertiary`, `destructive`, `success`, `warning`, `info`, `inverse`. Default `'inherit'`. |
| `weight?` | `TextWeight` | Overrides the weight the variant carries. If you want it, the role is probably wrong. One of `normal`, `medium`, `semibold`, `bold`. |
| `align?` | `TextAlign` | Logical, so it follows the writing direction. One of `start`, `center`, `end`, `justify`. |
| `wrap?` | `TextWrap` | Overrides the wrapping the variant sets — headings balance, body avoids orphans. One of `normal`, `balance`, `pretty`, `nowrap`. |
| `lines?` | `TextLines` | Clamps to N lines with an ellipsis. `lines={1}` is a single line. One of `1`, `2`, `3`, `4`, `5`, `6`. |
| `font?` | `TextFont` | Family. Inherits unless set; `mono` for ids, hashes and code. One of `sans`, `mono`. |
| `tabular?` | `boolean` | Fixed-width digits, for numbers that sit in a column. Default `false`. |
| `for?` | `string` | Only with `as="label"`: the id of the control it labels. |
| `datetime?` | `string` | Only with `as="time"`: the machine-readable date. |
| `class?` | `string` |  |
| `children?` | `Snippet` |  |

### Textarea

`import { Textarea } from 'omaris'`

Multi-line text field.

#### Use it for

- Text that runs past a line: delivery notes, a description, a reply, an
  address.
- A composer. `autosize` with `rows={1}` and a `maxRows` grows one line at a
  time. `bind:lines` swaps in a send button or shows a "shift+enter for a new
  line" hint.
- A hard limit the person should see coming. Pass `counter` with `maxlength`.

#### Not for

- One line, like a title, a name or a URL → [Text Field](/docs/components/input).
- Bold, a list, a link → [Rich Text Editor](/docs/components/rich-text-editor).
- Code, JSON, a query → [Code Editor](/docs/components/code-editor) with
  `lang`. It indents, closes brackets and colours.
- Chat text with emoji → still this, with an [Emoji Button](/docs/components/emoji-picker)
  beside it.

#### Do

- Match the Input next to it: same `variant`, same `size`. They share a frame
  and line up without adjustment.
- Set `rows` to the length you expect: `2` for a note, `6` for a description.
  The default `3` is a guess.
- Give `autosize` a `maxRows`, or a pasted essay pushes the submit button off
  the screen.
- Put the reason in `supportingText` and set `invalid`. The helper line
  becomes the error line.

#### Don't

- Autosize inside a grid of cards. The row below moves every time a line is
  added. Fix `rows` there and let it scroll.
- Expect the resize grip with `autosize`. The box sizes itself, so the grip
  is removed. Without `autosize` the grip is on, vertical only.
- Use the placeholder for instructions needed after typing starts. That is
  `supportingText`.

#### Pairs with

- [Text Field](/docs/components/input), [Label](/docs/components/label),
  [Emoji Picker](/docs/components/emoji-picker), [Button](/docs/components/button),
  [Chip](/docs/components/chip)

Parts (`classes`): `root` `field` `well` `control` `mirror` `label` `support` `counter`

| Prop | Type | Notes |
| --- | --- | --- |
| `variant?` | `TextareaVariant` | One of `outline`, `filled`, `ghost`. Default `'outline'`. |
| `size?` | `TextareaSize` | One of `sm`, `default`, `lg`. Default `'default'`. |
| `label?` | `string` |  |
| `required?` | `boolean` | Inside a `Field`, defaults to the field's. |
| `supportingText?` | `string` |  |
| `invalid?` | `boolean` | Inside a `Field`, defaults to the field's. |
| `value?` | `string` | Default `''`. Bindable. |
| `counter?` | `boolean` | Live `n/maxlength` count beside the supporting text. Default `false`. |
| `autosize?` | `boolean` | Grow with the text. The box starts at `rows`, gains a line as the text takes one, and scrolls once it reaches `maxRows`. Default `false`. |
| `rows?` | `number` | Starting height, in lines — and the floor when `autosize`. Default `3`. |
| `maxRows?` | `number` | Ceiling for `autosize`, in lines. Past this it scrolls. |
| `lines?` | `number` | Lines the text currently occupies. Bindable, and read-only in practice — useful for a "shift+enter for a new line" hint or for swapping a send button in once the composer has something in it. Default `1`. Bindable. |
| `class?` | `string` |  |
| `classes?` | `TextareaClasses` | Per-part Tailwind overrides. `class` still covers the root. |
| `supporting?` | `Snippet` | Richer supporting text — a link, a hint. |
| `ref?` | `HTMLTextAreaElement \| null` | Default `null`. Bindable. |

### ThemeSettings

`import { ThemeSettings } from 'omaris'`

A ready-made appearance screen for the theme store.

#### Use it for

- The appearance screen of a product built on omaris. Put `<ThemeSettings />`
  behind a "Customise" button, in a [Dialog](/docs/components/dialog) or a
  [Sheet](/docs/components/sheet).
- Every knob of the theme store: colour, shape, density, type, motion. Each
  changes the whole product live. The store and its tokens are explained in
  [Theming](/docs/theming).
- A settings page that already has tabs. `layout="stack"` drops the tabs and
  gives each section a heading.
- Only what the product honours: `sections={['color']}`, with
  `customHue={false}` to keep people on the presets.
- A product in English, Arabic, Turkish or Sorani Kurdish. It follows the
  page's `lang`, or `locale="ar" | "tr" | "ckb" | "en"` picks one; Arabic and
  Kurdish mirror the screen. `labels` swaps any word.

#### Not for

- A dark-mode toggle in the app bar → a [Switch](/docs/components/switch) or
  an [Icon Button](/docs/components/icon-button) bound to the theme store
  (see [Theming](/docs/theming)). This is the whole screen, not one row.
- Setting the brand for everyone → tokens in `app.css` and the provider's
  defaults ([Tokens](/docs/tokens)). This screen is one person's preference.
- A colour for a record, like a tag or a label → [Color Picker](/docs/components/color-picker).
- An app without `OmarisProvider` → nothing works. The provider applies the
  theme and remembers it.

#### Do

- Wrap the app in `OmarisProvider` so the choice applies live and survives a
  reload.
- Put it where people look for it, under Settings or Appearance, and give it
  a measure like `max-w-2xl`.
- Trim `sections` to what the product honours. If the typeface is pinned,
  drop `text`; if the density is fixed, drop `layout`.
- Keep `resettable` on. Someone who picked the wrong hue needs a way back.
- Set `lang` on `<html>` and let the screen follow it, rather than passing
  `locale` in one place and forgetting it in another.

#### Don't

- Ship all five sections in a one-screen tool. Two sections in `stack` is
  enough.
- Restyle the swatches through `classes` to match the brand. The swatches are
  the presets; their colours are the point.
- Put it in onboarding. People choose a theme after they have seen the
  product.
- Mount two on one page. Both write the same store.
- Translate it by wrapping it in your own strings. Pass `labels` for the
  words you want to change; the rest stay in the chosen language.

#### Pairs with

- [Dialog](/docs/components/dialog), [Sheet](/docs/components/sheet),
  [Switch](/docs/components/switch), [Tabs](/docs/components/tabs),
  [Color Picker](/docs/components/color-picker)

Parts (`classes`): `root` `section` `heading` `row` `label` `hint` `choices` `choice` `choiceArt` `choiceLabel` `swatch` `swatchDot` `swatchLabel` `footer`

| Prop | Type | Notes |
| --- | --- | --- |
| `layout?` | `ThemeSettingsLayout` | One of `tabs`, `stack`. Default `'tabs'`. |
| `sections?` | `ThemeSettingsSection[]` | Which groups to show, in order. Default `ALL`. |
| `resettable?` | `boolean` | Show the "Reset" row at the bottom. Default `true`. |
| `customHue?` | `boolean` | Offer the custom hue slider alongside the presets. Default `true`. |
| `locale?` | `ThemeSettingsLocale` | The language — `en`, `ar`, `tr` or `ckb` (Sorani Kurdish). Arabic and Kurdish lay the screen out right to left. Leave it out to follow the nearest `lang` attribute on the page, falling back to English. |
| `labels?` | `Partial<ThemeSettingsLabels>` | Replace any of the words, over whichever language is showing. |
| `class?` | `string` |  |
| `classes?` | `ThemeSettingsClasses` | Per-part Tailwind overrides. `class` still covers the root. |

### Timeline

`import { Timeline } from 'omaris'`

An activity feed or an order's history: events in order, each on a rail with a dot or an icon, joined by the line that makes them read as one sequence rather than a list of unrelated rows.

#### Use it for

- An order's or a ticket's history — placed, paid, shipped, delivered — with
  the step still to come marked `pending`.
- An activity feed: who did what and when, `variant="compact"`, one
  `Timeline` per day with a `heading` ("Today", "Yesterday").
- An audit log with exact dates: `relative={false}` and a `dateFormat`.
- Events that carry more than a line — a comment, a set of labels, a diff —
  as the item's children.

#### Not for

- Steps the person is moving through right now — a checkout, an onboarding →
  [Stepper](/docs/components/stepper).
- Records to sort, filter or compare → [Table](/docs/components/table).
- Live, high-volume output — a build log, a server stream →
  [Log Viewer](/docs/components/log-viewer).
- A list of things that are not in time order → [List](/docs/components/list).

#### Do

- Pass `time` as a `Date`, a timestamp or an ISO string. It is written relative
  to now in the page's language, marked up as `<time datetime>`, and kept
  current from one shared clock.
- Use `tone="neutral"` for routine events and save the colours for the ones
  that need attention — a failure, a refund, a delivery.
- Set `maxAge` on a long feed so old events read as dates rather than "47
  weeks ago".
- Give the list a name: a `heading`, or a `label` when there is none.

#### Don't

- Mark more than one item `pending`; it is the step that has not happened
  yet, and there is one.
- Put the time in the title as text; `time` is what gives it the tooltip and
  the machine-readable date.
- Give every item an icon. Icons pick out the events worth finding at a
  glance; a column of them is as flat as a column of dots.

#### Pairs with

- [Data List](/docs/components/data-list) for the details above the history,
  [Avatar](/docs/components/avatar) as an item's icon,
  [Chip](/docs/components/chip), [Card](/docs/components/card),
  [Sheet](/docs/components/sheet)

Parts (`classes`): `root` `heading` `list`

| Prop | Type | Notes |
| --- | --- | --- |
| `variant?` | `TimelineVariant` | `default` gives each event room and icon-sized markers; `compact` is a dense feed. Default `'default'`. |
| `heading?` | `string` | A heading over the list, which also names it for a screen reader — "Today", "Yesterday". Use one `Timeline` per group. |
| `level?` | `2 \| 3 \| 4 \| 5 \| 6` | Heading level, so the group fits the page outline. Default `3`. |
| `label?` | `string` | Accessible name for the list when there is no `heading`. |
| `relative?` | `boolean` | Write times relative to now — "3 minutes ago". Off, they are written as dates with `dateFormat`. Either way the exact moment is in the `<time datetime>` and the tooltip. Default `true`. |
| `maxAge?` | `number` | Past this age, in ms, a relative time switches to the date: a week is `7 * 24 * 3600_000`. "47 weeks ago" is not information. |
| `dateFormat?` | `Intl.DateTimeFormatOptions` | How absolute dates are written. Defaults to a long date and a short time. |
| `locale?` | `string` | Language of the times. English, Arabic, Turkish and Sorani Kurdish are built in; defaults to `<html lang>`. Digits stay Western. |
| `class?` | `string` |  |
| `classes?` | `TimelineClasses` | Per-part Tailwind overrides. `class` still covers the root. |
| `header?` | `Snippet` | Rich heading, in place of `heading`. |
| `children?` | `Snippet` |  |

### TimelineItem

`import { TimelineItem } from 'omaris'`

One event on a `Timeline`: a marker on the rail, a title, when it happened, and whatever else it needs underneath.

Parts (`classes`): `root` `rail` `marker` `dot` `icon` `line` `content` `header` `title` `time` `description` `body`

| Prop | Type | Notes |
| --- | --- | --- |
| `title?` | `string` | What happened — "Order shipped". |
| `description?` | `string` | A supporting line under the title. |
| `time?` | `Date \| string \| number` | When it happened. A `Date`, a timestamp or an ISO string is written relative to now and marked up as `<time datetime>`; a string that is not a date ("Tomorrow, 9–12") is shown as given. |
| `tone?` | `TimelineItemTone` | The marker's colour role. `neutral` is a quiet grey dot for events that need no attention; save the tones for the ones that do. One of `neutral`, `primary`, `secondary`, `tertiary`, `destructive`, `success`, `warning`, `info`. Default `'primary'`. |
| `pending?` | `boolean` | The event that has not happened yet — the courier on the way, the review awaiting. Its marker pulses (and holds still under reduced motion), and the line into it is dashed. Usually the last item. Default `false`. |
| `pendingLabel?` | `string` | Spoken after the title of a pending item. Default `'In progress'`. |
| `class?` | `string` |  |
| `classes?` | `TimelineItemClasses` | Per-part Tailwind overrides. `class` still covers the root. |
| `icon?` | `Snippet` | An icon in a tonal circle, in place of the dot. |
| `children?` | `Snippet` | Rich content under the description. |

### TimePicker

`import { TimePicker } from 'omaris'`

Hour, minute and AM/PM.

Parts (`classes`): `root` `header` `stage` `band` `wheels` `actions` `action`

| Prop | Type | Notes |
| --- | --- | --- |
| `value?` | `string` | `"HH:mm"`, stored 24-hour; the wheels always show 1–12 and AM/PM. Bindable. Default `'09:00'`. |
| `minuteStep?` | `number` | Minutes between rows — 5 or 15 for an opening time, 1 for an alarm. Default `1`. |
| `loop?` | `boolean` | Spin past midnight and noon instead of stopping. On by default. Default `true`. |
| `labels?` | `{ hour?: string; minute?: string; meridiem?: string; am?: string; pm?: string }` | Accessible names for the wheels, and the AM/PM row text. |
| `onchange?` | `(value: string) => void` | Fires once a wheel settles, with the 24-hour string. |
| `columnClasses?` | `PickerColumnClasses` | Per-part overrides for the wheels themselves. |
| `classes?` | `PickerClasses` |  |
| `size?` | `PickerSize` | Row height and type scale. |
| `surface?` | `PickerSurface` | How the frame is drawn. |
| `visible?` | `number` | Rows on screen at once. Rounded up to the next odd number. |
| `title?` | `string` | A title above the wheels. |
| `disabled?` | `boolean` | Disables every wheel inside. |
| `haptics?` | `boolean` | Play a tick as each row passes the centre, once haptics are on. |
| `onconfirm?` | `() => void` | Renders the action row. Called with the value already committed. |
| `oncancel?` | `() => void` | Renders a cancel button beside it. |
| `confirmLabel?` | `string` |  |
| `cancelLabel?` | `string` |  |
| `footer?` | `Snippet` | Replaces the built-in action row. |
| `class?` | `string` |  |

### Toast

`import { Toast } from 'omaris'`

One toast card.

#### Use it for

- Confirming something just happened: "Saved", "Invitation sent", "Copied".
  Call `toast('Saved')` from anywhere. `OmarisProvider` already renders the
  `<Toaster />`.
- Undo. Put `action: { label: 'Undo', onclick }` on the toast that reports a
  delete or archive, instead of a confirm dialog before it.
- A job the person can walk away from. `toast.promise()` with `loading`,
  `success` and `error` turns one card from spinner to result.
- A failure that needs no decision: "Could not sync, retrying". `toast.error`
  stays six seconds instead of four.
- A message that must stand out while the page is in use: `variant="rich"`
  tints the whole card.

#### Not for

- A message that stays until the problem clears → [Alert](/docs/components/alert).
- A decision, like "Delete 12 files?" → [Dialog](/docs/components/dialog). A
  toast never blocks and leaves on its own.
- Progress of the button just pressed → the [Button](/docs/components/button)'s
  `loading`.
- A count or a "new" mark → [Badge](/docs/components/badge).
- Field validation → the field's `supportingText`. A toast is gone before it
  is read.

#### Do

- Write one line with a verb: "Invoice sent", not "Success!". Put detail in
  `description`.
- Keep to one `action`. Add `cancel` only for a destructive pair. Three
  buttons means you want a dialog.
- Reuse an `id` to update a toast in place, for a changing count or a retry.
- Let it close on its own. Use `duration: 0` with `closeButton` only for a
  message that needs acknowledging, like a lost connection.
- Set `keepOpen` on an action whose press does not finish the job.

#### Don't

- Toast a result that is already on screen: the row is gone, the panel
  closed, the page moved. Most actions get no toast.
- Toast every row in a bulk edit. Batch it: "12 rows updated".
- Put the only way to reach something in a toast. A swipe throws it away.
- Fire one on page load.
- Mount a second `<Toaster />`. There is one stack; a message that belongs to
  a region is an [Alert](/docs/components/alert).

#### Pairs with

- [Alert](/docs/components/alert), [Dialog](/docs/components/dialog),
  [Button](/docs/components/button), [Progress](/docs/components/progress),
  [Badge](/docs/components/badge)

Parts (`classes`): `root` `icon` `body` `title` `description` `actions` `action` `cancel` `close`

| Prop | Type | Notes |
| --- | --- | --- |
| `toast` | `ToastItem` |  |
| `variant?` | `ToastVariant` | One of `plain`, `rich`. Default `'plain'`. |
| `swipe?` | `ToastSwipe` | Default `{ x: 0, y: 1 }`. |
| `closeButton?` | `boolean` | Stack-wide default; the toast's own `closeButton` wins. Default `false`. |
| `ondismiss?` | `() => void` |  |
| `onhold?` | `(held: boolean) => void` | Held while a finger is on the card, so the timer can pause. |
| `ontap?` | `() => void` | A press that turned out to be a press: it ended without becoming a swipe and did not land on a button. The stack uses it as "expand" on a touchscreen, where there is no hover to fan the deck with. |
| `class?` | `string` |  |
| `classes?` | `ToastClasses` | Per-part Tailwind overrides. `class` still covers the root. |

### Toaster

`import { Toaster } from 'omaris'`

Where toasts appear. `OmarisProvider` renders one, so you only need this if you want them somewhere else or stacked differently.

| Prop | Type | Notes |
| --- | --- | --- |
| `position?` | `ToastPosition` | Default `'bottom-end'`. |
| `visible?` | `number` | How many are on screen at once. The rest wait in the deck. Default `3`. |
| `variant?` | `ToastVariant` | Fill style for every toast the stack renders. Default `'plain'`. |
| `closeButton?` | `boolean` | Show the × on every toast. Default `false`. |
| `expand?` | `boolean` | Keep the deck fanned out instead of expanding on hover. Default `false`. |
| `gap?` | `number` | Gap between toasts once expanded, in px. Default `14`. |
| `class?` | `string` |  |

### Toc

`import { Toc } from 'omaris'`

Toc — the "on this page" rail.

#### Use it for

- The "on this page" rail beside a long document, a report, or a settings
  page with a dozen sections.
- Content that scrolls inside an [App Shell](/docs/components/app-shell)
  column, a panel or a dialog. It follows whatever scrolls, not only the
  window.
- A page that knows its own position. `spy={false}` and `bind:active` move
  the marker from your own stepper or form.

#### Not for

- Moving between pages → [Navigation Drawer](/docs/components/navigation-drawer).
- Sections that swap rather than scroll → [Tabs](/docs/components/tabs).
- Where this page sits among others → [Breadcrumb](/docs/components/breadcrumb).
- A page with two headings → drop the rail. The marker needs enough sections
  to move between.

#### Do

- Set `offset` to the height of whatever sticks to the top, like a `sticky`
  [Top App Bar](/docs/components/top-app-bar), plus a little. Otherwise the
  marker changes section early.
- Give every heading a stable `id`, and pass `level` so nesting indents.
  Indentation is relative to the shallowest level in the list.
- Hide it below a wide breakpoint (`hidden xl:block`). It needs a column of
  its own, and a phone has none.
- Use `size="sm"` when it shares a narrow column with something else.

#### Don't

- List every `h4`. Two levels is enough; deeper is noise.
- Drop `label` when hiding the heading with `showLabel={false}`. The
  accessible name comes from it.
- Leave headings without ids. The links are anchors, and nothing scrolls to a
  heading it cannot find.

#### Pairs with

- [App Shell](/docs/components/app-shell), [Top App Bar](/docs/components/top-app-bar),
  [Text](/docs/components/text), [Accordion](/docs/components/accordion),
  [Breadcrumb](/docs/components/breadcrumb)

Parts (`classes`): `root` `title` `rail` `marker` `list` `item` `link`

| Prop | Type | Notes |
| --- | --- | --- |
| `items?` | `TocItem[]` | The headings, in the order they appear on the page. Default `[]`. |
| `label?` | `string` | Heading above the list, and the nav's accessible name. Default `'On this page'`. |
| `showLabel?` | `boolean` | Draw the heading. The accessible name survives either way. Default `true`. |
| `active?` | `string` | The id of the highlighted heading. Bindable. Default `undefined`. |
| `spy?` | `boolean` | Follow the scroll position. Off leaves `active` to the consumer. Default `true`. |
| `offset?` | `number` | How far below the top of whatever scrolls — the viewport, or the panel the headings are in — a heading counts as read, in pixels: the height of whatever sticks to the top, plus a little. Default `96`. |
| `size?` | `TocSize` | One of `sm`, `md`. Default `'md'`. |
| `marker?` | `boolean` | Draw the sliding marker. Off leaves the hairline and the colour. Default `true`. |
| `onnavigate?` | `(id: string) => void` | Runs when a link is clicked, after `active` has moved. |
| `class?` | `string` |  |
| `classes?` | `TocClasses` | Per-part Tailwind overrides. `class` still covers the root. |

### Tooltip

`import { Tooltip } from 'omaris'`

MD3 tooltip — plain and rich.

#### Use it for

- Naming an [Icon Button](/docs/components/icon-button). Wrap it and pass
  `text` with the same words as its `aria-label`. On a toolbar the first
  waits; the rest open as fast as the pointer moves.
- A line about a truncated cell, a chart point or an abbreviation. Plain
  `text`, a phrase long.
- Context worth a paragraph and a link, like what a retention window means.
  `title` turns on rich mode, `content` is the body, `actions` the buttons.
  It stays open while the pointer is inside.
- `open` to pin one for a screenshot or a story.

#### Not for

- Anything needed to finish the task → put it on the page, as `supportingText`
  or an [Alert](/docs/components/alert). On a phone a tooltip only appears on
  long press.
- The only name a control has → a visible label or an `aria-label`. A tooltip
  describes; it does not name.
- Content people interact with, like a form or a list → [Menu](/docs/components/menu),
  [Sheet](/docs/components/sheet) or [Dialog](/docs/components/dialog). Only a
  rich tooltip's `actions` are reachable.
- A sequence of hints → [Tour](/docs/components/tour).
- Something that just happened → [Toast](/docs/components/toast).

#### Do

- Wrap the thing it describes. The wrapper is the anchor; hover, focus and
  long press all open it, so keyboard users get it too.
- Keep a plain tooltip to a phrase. It caps at 16rem and wraps into a block
  after that.
- Set `side` to where there is usually room. It flips when there is none, but
  one that always flips looks wrong.
- Leave `delay` alone across an app. `0` makes every hover flash.

#### Don't

- Put one on a disabled button. It gets no hover and no focus, so it never
  opens. Say why in text beside it.
- Attach one to plain text. A `<span>` never takes focus, so it becomes
  pointer-only. Give the trigger `tabindex="0"` or make it a button.
- Repeat the visible label. "Save" under a button that says Save is noise.
- Use rich when plain would do. A rich tooltip needs a title and a reason to
  exist.

#### Pairs with

- [Icon Button](/docs/components/icon-button), [Button](/docs/components/button),
  [Tour](/docs/components/tour), [Menu](/docs/components/menu),
  [Text](/docs/components/text)

Parts (`classes`): `root` `surface` `title` `body` `actions`

| Prop | Type | Notes |
| --- | --- | --- |
| `text?` | `string` | Plain-tooltip text. |
| `title?` | `string` | Heading of a rich tooltip. Its presence turns rich mode on. |
| `side?` | `AnchorSide` | Which side to prefer. Flips when there isn't room. Default `'top'`. |
| `align?` | `AnchorAlign` | Default `'center'`. |
| `offset?` | `number` | Gap between the trigger and the tooltip, in px. Default `8`. |
| `delay?` | `number` | Delay before opening, in ms. Suppressed once one is already open. Default `500`. |
| `open?` | `boolean` | Keep it open. Useful for a story or a walkthrough. Default `false`. Bindable. |
| `disabled?` | `boolean` | Default `false`. |
| `class?` | `string` |  |
| `classes?` | `TooltipClasses` | Per-part Tailwind overrides. `class` still covers the root. |
| `children?` | `Snippet` | The trigger. |
| `content?` | `Snippet` | Rich body, in place of `text`. |
| `actions?` | `Snippet` | Buttons along the bottom of a rich tooltip. |

### TopAppBar

`import { TopAppBar } from 'omaris'`

MD3 top app bar — small, medium, large and center-aligned.

#### Use it for

- The top of every screen in an [App Shell](/docs/components/app-shell): the
  screen's `title`, a `leading` back arrow or menu button, and up to three
  `actions`.
- A long read, like a report or a document. `size="large"` with `flexible`
  collapses the headline into a small bar as the page scrolls.
- The dashboard's top bar: a [Search Bar](/docs/components/search-bar) in the
  `search` slot, navigation on the left, the account on the right.
- A map or a canvas. `floating` detaches it into a rounded, blurred capsule
  over the content.
- A tab row under the bar, passed as `children`. It moves with the bar.

#### Not for

- The app's navigation → [Navigation Drawer](/docs/components/navigation-drawer)
  or [Navigation Bar](/docs/components/navigation-bar). The bar carries one
  screen's title and actions.
- A bar plus a filter row that stick together → wrap both in an
  `AppShellHeader` from [App Shell](/docs/components/app-shell).
- A headline with no actions, halfway down a page → [Text](/docs/components/text)
  with `variant="headline-md"`.
- A selection bar like "3 selected, delete" → a sticky `AppShellFooter` from
  [App Shell](/docs/components/app-shell), at the bottom.

#### Do

- Set `sticky`. It does not stick on its own. Inside a shell it knows which
  column scrolls; `scrollContainer` is only for other layouts.
- Use one `leading` control: back on a detail screen, the menu button when the
  drawer is modal, nothing on a top-level screen.
- Keep to three icon `actions`. The rest go in a [Menu](/docs/components/menu)
  behind the last one.
- Pick `size` by the screen: `small` for a dense dashboard page, `medium` or
  `large` where the headline is the point, `center` on a top-level screen
  with one action.

#### Don't

- Stack two bars. The tab row is `children`; the search is `search`.
- Set `hideOnScroll` on a screen whose actions people use while they work. It
  is for reading.
- Use `variant="surface"` on a flat page. `flat` is flat at rest and lifts
  once content scrolls under it.
- Expect `title` and `search` together on a small bar. `search` replaces the
  middle; only `medium` and `large` keep the headline on the row below.

#### Pairs with

- [App Shell](/docs/components/app-shell), [Navigation Drawer](/docs/components/navigation-drawer),
  [Search Bar](/docs/components/search-bar), [Tabs](/docs/components/tabs),
  [Icon Button](/docs/components/icon-button), [Menu](/docs/components/menu)

Parts (`classes`): `root` `bar` `leading` `title` `actions` `headlineRow` `headline` `search`

| Prop | Type | Notes |
| --- | --- | --- |
| `size?` | `TopAppBarSize` | One of `small`, `center`, `medium`, `large`. Default `'small'`. |
| `variant?` | `TopAppBarVariant` | One of `flat`, `surface`, `transparent`. Default `'flat'`. |
| `title?` | `string` | Headline text. |
| `sticky?` | `boolean` | Stick to the top of the scroll container. Default `false`. |
| `floating?` | `boolean` | Rounded, blurred and inset from the edges. Default `false`. |
| `elevateOnScroll?` | `boolean` | Lift onto a raised surface once the page is scrolled. Give it a scroll container element to watch something other than the window. Default `true`. |
| `flexible?` | `boolean` | Collapse a medium or large bar into a small one as the page scrolls — MD3's flexible bar. Default `false`. |
| `collapseDistance?` | `number` | Scroll distance the collapse runs over, in px. Defaults to the headline's own height, which is the distance it has to travel. |
| `hideOnScroll?` | `boolean` | Slide the bar away while scrolling down; bring it back on the way up. Default `false`. |
| `scrollContainer?` | `HTMLElement \| null` | What to watch for scrolling. Inside an `AppShell` this is already known — the shell hands over its scrolling column — so it's only needed for a layout that scrolls something else. `null` is the window, explicitly. |
| `threshold?` | `number` | Scroll distance, in px, before the bar lifts. Default `4`. |
| `progress?` | `number` | How far the collapse has run, 0…1. Bindable, read-only in practice. Default `0`. Bindable. |
| `class?` | `string` |  |
| `classes?` | `TopAppBarClasses` | Per-part Tailwind overrides. `class` still covers the root. |
| `leading?` | `Snippet` | Leading control — a back arrow or menu button. |
| `headline?` | `Snippet` | Rich headline, in place of `title`. |
| `actions?` | `Snippet` | Trailing controls. |
| `search?` | `Snippet` | Takes over the middle of the action row, full width — a `SearchBar`, usually. It *replaces* what sits there rather than joining it, so on a small or centred bar `title` is not drawn at all while this is set. A medium or large bar still draws its headline on the row below, so those keep both. |
| `children?` | `Snippet` | Anything below the bar — a tab row. |

### Tour

`import { Tour } from 'omaris'`

A guided tour: a spotlight on one thing at a time, with a card explaining it.

#### Use it for

- A first run through a dashboard: three to six steps pointing at real things
  like the new-order button, the filter bar, the settings menu.
  `createTour(steps, { id, once: true })` runs it once per browser and
  resumes after a reload.
- A "what's new" walk started from a button or `?tour=1` in the URL. Call
  `tour.start()` from anywhere, `restart()` to run it again.
- A flow across pages. Put a `path` on the steps that live elsewhere, pass
  `navigate: goto`, and mount `<Tour {tour} />` in `+layout.svelte` so
  navigation does not unmount it.
- Steps whose target is not on screen yet. Open a menu, switch a tab or await
  a fetch in the step's `before`.

#### Not for

- Explaining one control on hover → [Tooltip](/docs/components/tooltip). A
  tour is a sequence.
- Documentation, more than two sentences a step → a docs page, linked from a
  rich [Tooltip](/docs/components/tooltip) or an [Alert](/docs/components/alert)
  with an action.
- An announcement with nothing to point at, like "Welcome to v2" →
  [Dialog](/docs/components/dialog). One centred, targetless step can open a
  tour but should not be the whole tour.
- Walking someone through a form → the form itself, with `required` fields
  and `supportingText`.
- A screen with nothing on it → [Empty](/docs/components/empty). With no
  targets every step is skipped and the tour finishes at once.

#### Do

- Select targets by an id or a `data-tour` attribute you own. A step that
  names a design-system class breaks on the next refactor.
- Keep a step to a title and a sentence or two. The card fits the room beside
  the target and scrolls; on a phone that room is small.
- Let a step ask for a real click when it helps. The page stays live inside
  the spotlight; use the next step's `before` to put things back.
- Set `round` on a step pointing at an avatar or icon button, and `padding`
  where the target's own padding is thin.
- Leave `dismissible` on, and watch `onskip` to learn where people leave.

#### Don't

- Run it on every visit. Give it an `id` and `once`, and a "Take the tour"
  button for the rest.
- Put more than about eight steps in one tour. Split it by page and start the
  second from the first's `onfinish`.
- Mount `<Tour />` inside the page a step navigates away from. It goes with
  the page.
- Point at a target inside an `overflow: hidden` box that clips it. The hole
  is clipped to what is visible.

#### Pairs with

- [Tooltip](/docs/components/tooltip), [Dialog](/docs/components/dialog),
  [Empty](/docs/components/empty), [App Shell](/docs/components/app-shell),
  [Button](/docs/components/button)

Parts (`classes`): `scrim` `spotlight` `card` `scroller` `body` `header` `title` `counter` `progress` `progressBar` `content` `footer` `dots` `dot` `actions` `ghost` `next`

| Prop | Type | Notes |
| --- | --- | --- |
| `steps?` | `TourStep[]` | The steps. Omit it when `tour` is given — the controller holds them. |
| `tour?` | `TourController` | A controller from `createTour`, holding `steps`, `open` and `index` outside the component. Use one when the tour crosses pages: the state lives in the controller (and, with an `id`, in storage), so a real navigation resumes the tour where it was instead of ending it. |
| `open?` | `boolean` | Whether the tour is running. Bindable. Ignored when `tour` is given. Default `false`. Bindable. |
| `index?` | `number` | Which step, from 0. Bindable. Setting it to a step whose target is missing lands on the next one that resolves. Ignored when `tour` is given. Default `0`. Bindable. |
| `scrim?` | `TourScrim` | One of `soft`, `strong`. Default `'soft'`. |
| `padding?` | `number` | Default breathing room around a target, in px. Default `8`. |
| `width?` | `number \| string` | Card width. A number is px, a string any CSS length. Default `320`. |
| `dismissible?` | `boolean` | Let `Escape` and a click on the scrim end the tour. Default `true`. |
| `dots?` | `boolean` | Show the progress dots. Default `true`. |
| `progress?` | `boolean` | Show the slim progress bar under the header. Default `true`. |
| `labels?` | `{ next?: string; back?: string; done?: string; skip?: string }` | Button text. |
| `scrollIntoView?` | `boolean` | Bring each target into view before pointing at it. Default `true`. |
| `wait?` | `number` | How long to wait, in ms, for a step's target to appear before the step is treated as missing and skipped. `0` looks once. Raise it for targets that arrive with a fetch; a step with a `path` waits anyway. Default `0`. |
| `navigate?` | `(path: string) => void \| Promise<void>` | How a step's `path` is followed. `goto` from `$app/navigation` in a SvelteKit app; a full page load otherwise, which a tour with an `id` survives. |
| `onfinish?` | `() => void` |  |
| `onskip?` | `(index: number) => void` |  |
| `onstep?` | `(index: number, step: TourStep) => void` | Fires once per step shown, after its target has been found. |
| `class?` | `string` |  |
| `classes?` | `TourClasses` |  |

### TreemapChart

`import { TreemapChart } from 'omaris/chart'`

Treemap — a part-of-a-whole where the parts are too many, or too lopsided, for a pie.

| Prop | Type | Notes |
| --- | --- | --- |
| `data` | `T[]` |  |
| `label?` | `Field<T>` | Field naming each tile. Defaults to `row.label`. Default `'label'`. |
| `value?` | `Field<T>` | Field holding each tile's size. Defaults to `row.value`. Default `'value'`. |
| `group?` | `Field<T>` | Field gathering rows into blocks. |
| `height?` | `number \| string` | Plot height. A number is px; a string is any CSS length. Default `300`. |
| `gap?` | `number` | Gap between tiles, in px. Default `2`. |
| `radius?` | `number` | Corner radius on the tiles, in px. Default `4`. |
| `values?` | `boolean` | Print each tile's value under its name. Default `false`. |
| `tooltip?` | `boolean` | Default `true`. |
| `format?` | `(value: number) => string` | How each value reads. |
| `colors?` | `readonly string[]` | Palette override, cycled across the tiles or the groups. Default `CHART_COLORS`. |
| `title?` | `string` | Accessible description of what the chart shows. |
| `class?` | `string` |  |
| `empty?` | `Snippet` |  |
| `emptyText?` | `string` |  |
| `error?` | `boolean \| string \| Error` | Something went wrong. Truthy puts the chart into its error state; a string or an `Error` supplies the message. |
| `errorText?` | `string` | The message, when `error` is just `true`. |
| `errorState?` | `Snippet<[{ message: string }]>` | Replaces the whole error state. |
| `onRetry?` | `() => void` | Offers a "Try again" button in the error state. |
| `csv?` | `boolean \| string` | Offer the plotted rows as a CSV download, from a button in the corner. A string names the file. Default `false`. |
| `csvColumns?` | `(string \| { key: string; label?: string; value?: (row: T) => unknown })[]` | Which fields the download writes, in order. Defaults to every field. |

### TreeView

`import { TreeView } from 'omaris'`

A tree of rows you can open, close and walk with the keyboard.

#### Use it for

- Files and folders: a repository browser, an attachment picker, a media
  library.
- Any nesting a person navigates rather than reads: a category tree, an org
  chart, nested filters, a JSON path, a chart of accounts.
- A sidebar of sections whose depth varies from page to page, where a flat
  list would lose the relationships.
- Picking a set out of a hierarchy, with `checkable`. Ticking a branch ticks
  everything under it; a partly ticked branch shows a dash.

#### Not for

- One level of rows → [List](/docs/components/list).
- Sections of content on one page → [Accordion](/docs/components/accordion).
  An accordion opens content; a tree opens more rows.
- The app's own navigation → [Navigation Drawer](/docs/components/navigation-drawer),
  which knows the current route.
- Rows with several columns of data → [Table](/docs/components/table).
- A data structure for reading rather than walking → [JSON Viewer](/docs/components/json-viewer).

#### Do

- Keep `expanded` yourself when open branches should survive a navigation or
  come from a URL. `bind:expanded` is a plain array of ids.
- Use `expandable: true` on a branch whose children are fetched, load them in
  `onexpand`, and set `loading` while they are on the way. The chevron
  becomes a spinner.
- Put a size, a count or a status in `meta`, not in the label. It is
  right-aligned and stays out of the truncation.
- Give the tree a `label`. It is the accessible name.
- Turn `guides` off for a shallow tree and keep them past about three levels.
  Use `size="sm"` in a sidebar, where the tree is not the subject.

#### Don't

- Render thousands of rows at once. A tree is for a hierarchy someone walks.
  Page or search instead.
- Use `checkable` and `onselect` for two jobs at once. With checkboxes,
  clicking a row ticks it; a row that also navigates is ambiguous.
- Nest more than about five levels. The indent runs out of screen first.
- Reuse an `id` anywhere in the tree. `expanded`, `selected` and `checked`
  all key off it.

#### Pairs with

- [List](/docs/components/list), [Resizable](/docs/components/resizable),
  [Code Block](/docs/components/code-block),
  [Context Menu](/docs/components/context-menu),
  [Empty](/docs/components/empty)

Parts (`classes`): `root` `item` `toggle` `icon` `label` `meta` `check` `group` `guide`

| Prop | Type | Notes |
| --- | --- | --- |
| `items?` | `TreeNode[]` | The tree. Default `[]`. |
| `expanded?` | `string[]` | Ids of the open branches. Bindable. Default `[]`. |
| `selected?` | `string \| null` | Id of the selected row, or `null`. Bindable. Default `null`. |
| `checked?` | `string[]` | Ids of the ticked **leaves** — rows with no children. A branch's own state is worked out from them, so a half-ticked folder is a state you never have to store. Bindable. Default `[]`. |
| `checkable?` | `boolean` | Give every row a checkbox and tick branches through their leaves. Default `false`. |
| `size?` | `TreeViewSize` | One of `sm`, `md`. Default `'md'`. |
| `guides?` | `boolean` | Draw the vertical rules down each open branch. Default `true`. |
| `icons?` | `boolean` | Use the built-in folder and file icons for rows with no `icon`. Default `true`. |
| `defaultExpanded?` | `boolean` | Open every branch on first render. Default `false`. |
| `label?` | `string` | Accessible name for the tree. |
| `onselect?` | `(node: TreeNode) => void` | Fires when a row is picked — clicked, or Enter on the keyboard. |
| `onexpand?` | `(node: TreeNode) => void` | Fires when a branch opens. The place to fetch its children. |
| `oncollapse?` | `(node: TreeNode) => void` | Fires when a branch closes. |
| `row?` | `Snippet<[TreeNode, { depth: number; expanded: boolean; selected: boolean }]>` | Replaces a row's contents, after the chevron and the checkbox. |
| `empty?` | `Snippet` | Shown when `items` is empty. |
| `class?` | `string` |  |
| `classes?` | `TreeViewClasses` | Per-part Tailwind overrides. `class` still covers the root. |

### VideoPlayer

`import { VideoPlayer } from 'omaris'`

A video player with its own chrome.

#### Use it for

- A clip that belongs to the app, like an onboarding video, a lesson or a
  recording, with chrome that matches the UI. Pass `src`, `poster`, `title`.
- Long content. `chapters` mark the scrubber and name the hover bubble;
  `tracks` add captions, and with one track the CC button is a switch.
- Handing the file over: `download`, and `pip` where the browser has it.
- A hero: `aspect="21/9"`, `fit="cover"`, `rounded="xl"`. `rounded="none"` for
  a player that fills the page.
- A page that follows along. `paused`, `currentTime`, `volume` and `muted`
  are bindable, and `ref` is the `<video>` itself.

#### Not for

- Pictures → [Image Viewer](/docs/components/image-viewer).
- A muted background loop with no controls → a plain
  `<video autoplay muted loop playsinline>`.
- A YouTube or Vimeo embed → their `<iframe>`. This needs a media URL it can
  play itself.
- Several clips to flick through → [Carousel](/docs/components/carousel) with
  a player per slide, one playing at a time.

#### Do

- Give it a `title`. It is the accessible name and the top scrim.
- Pass a `poster`, or a `cover` snippet for a custom one. Otherwise the frame
  before the first play is black.
- Pass `src` as an array to offer several encodings and let the browser
  choose.
- Deep-link a moment with `start`.
- Leave `idleAfter` alone. `0` keeps the chrome up, for a kiosk only.

#### Don't

- Autoplay with sound. Browsers block it and the player sits paused.
- Let two players play at once. Pause the other through its `paused` binding.
- Set `download` on content you do not want saved. It is a real link to
  `src`.

#### Pairs with

- [Card](/docs/components/card), [Carousel](/docs/components/carousel),
  [Image Viewer](/docs/components/image-viewer),
  [Dialog](/docs/components/dialog), [Tabs](/docs/components/tabs)

Parts (`classes`): `root` `video` `surface` `chrome` `top` `title` `bottom` `seek` `track` `range` `handle` `bubble` `controls` `button` `menu` `menuItem` `center` `pill`

| Prop | Type | Notes |
| --- | --- | --- |
| `src` | `string \| VideoSource[]` | One URL, or several encodings for the browser to choose from. |
| `poster?` | `string` |  |
| `title?` | `string` | Shown in the top scrim, and used as the accessible name. |
| `aspect?` | `string \| number` | `16/9` by default. Any CSS aspect ratio, or a number. Default `'16/9'`. |
| `rounded?` | `VideoPlayerRounded` | One of `none`, `md`, `lg`, `xl`. Default `'lg'`. |
| `fit?` | `VideoPlayerFit` | One of `contain`, `cover`. Default `'contain'`. |
| `start?` | `number` | Second to open at. Default `0`. |
| `chapters?` | `VideoChapter[]` | Default `[]`. |
| `tracks?` | `VideoTrack[]` | Default `[]`. |
| `speeds?` | `number[]` | Rates the speed menu offers. Default `[0.5, 0.75, 1, 1.25, 1.5, 2]`. |
| `pip?` | `boolean` | Offer picture-in-picture, where the browser has it. Default `true`. |
| `fullscreen?` | `boolean` | Offer the fullscreen button. Default `true`. |
| `download?` | `boolean \| string` | Offer a download link — `true` uses `src`, a string names the file. Default `false`. |
| `idleAfter?` | `number` | Hide the chrome after this many ms of stillness. `0` keeps it up. Default `2600`. |
| `paused?` | `boolean` | Bindable. Default `true`. |
| `currentTime?` | `number` | Bindable, in seconds. Default `0`. Bindable. |
| `volume?` | `number` | Bindable, 0–1. Default `1`. Bindable. |
| `muted?` | `boolean` | Bindable. Default `false`. |
| `ref?` | `HTMLVideoElement \| null` | Bindable — the underlying `<video>`. Default `null`. Bindable. |
| `actions?` | `Snippet` | Extra controls, at the end of the control row. |
| `cover?` | `Snippet` | Covers the frame before the first play — a custom poster. |
| `class?` | `string` |  |
| `classes?` | `VideoPlayerClasses` | Per-part Tailwind overrides. `class` still covers the root. |

### VirtualList

`import { VirtualList } from 'omaris'`

A windowed list: ten thousand rows, and only the thirty on screen exist.

#### Use it for

- A list long enough that rendering all of it is the slow part — a thousand
  rows and up: an activity feed, a message history, search results, a picker
  over every customer.
- Rows of uneven height. Each is measured as it renders and cached by
  `getKey`, so wrapped text and late-loading images are fine.
- Infinite scroll: `onend` to fetch the next page, `loading` drawn after the
  last row while there is more.
- Jumping to a row from outside — a search hit, "back to where I was" — with
  `bind:this` and `scrollToIndex(i, { align: 'center' })`.
- A long horizontal strip of cards with `horizontal`.

#### Not for

- A list of a few dozen → [List](/docs/components/list). Windowing costs
  find-in-page, anchor links and focus that survives scrolling, and buys
  nothing under a few hundred rows.
- Rows and columns that sort, filter and select → [Table](/docs/components/table).
- Log output with levels, search and a tail that follows →
  [Log Viewer](/docs/components/log-viewer), which is already virtualised.
- A photo wall of unequal cards in columns → [Masonry](/docs/components/masonry).
- Paging through results a person should be able to link to →
  [Pagination](/docs/components/pagination).

#### Do

- Give it a height: a parent with one (it fills it), or `height`. Without
  either it stops at the height of the screen.
- Pass `getKey` whenever items can be inserted, removed or re-sorted, so the
  measured sizes follow the rows rather than the positions.
- Set `estimateSize` to a typical row. It only has to be close; a function of
  the index is there for lists whose rows come in known kinds.
- Give it an `aria-label` — it is a `list` with a name, and every row carries
  `aria-setsize` and `aria-posinset`, so a screen reader still hears "row 512
  of 10,000".
- Put the row's padding and border inside the snippet; the wrapper is what gets
  measured.

#### Don't

- Rely on focus staying in a row that is scrolled far away — rows off screen
  do not exist. Keep the thing being edited in a panel or a
  [Dialog](/docs/components/dialog), not in the row.
- Set a margin on the row's outer element; margins are outside the measured
  box. Use `gap`.
- Nest it inside another scroll container of the same axis. It is the scroller.
- Fire a fetch from `onend` without guarding against one already in flight —
  it re-arms when `items` grows, not when your request finishes.

#### Pairs with

- [List](/docs/components/list), [Empty](/docs/components/empty),
  [Progress](/docs/components/progress), [Search Bar](/docs/components/search-bar),
  [Notification Center](/docs/components/notification-center)

Parts (`classes`): `root` `canvas` `window` `item` `loading` `empty`

| Prop | Type | Notes |
| --- | --- | --- |
| `items` | `T[]` | Everything in the list. Only the rows in view are rendered. |
| `children` | `Snippet<[T, number]>` | One row. Handed the item and its index in `items`. |
| `estimateSize?` | `number \| ((index: number) => number)` | The size of a row not yet measured, in px — height, or width when `horizontal`. A function gets the index, for lists whose rows come in known kinds. Rows are measured as they render; this only has to be close. Default `48`. |
| `overscan?` | `number` | Rows rendered beyond each edge of the viewport, so a fast flick never shows a gap. Default `6`. |
| `getKey?` | `(item: T, index: number) => string \| number` | A stable key per item. Measurements are cached under it, so a list that is prepended to or re-sorted keeps its measured sizes. Defaults to the index. |
| `gap?` | `number` | Space between rows, in px. Default `0`. |
| `horizontal?` | `boolean` | Lay the rows out side by side and scroll sideways. Default `false`. |
| `height?` | `number \| string` | Height of the scroller. A number is px, a string any CSS length. Defaults to `100%` — fill a parent that has a height — and to `auto` when `horizontal`. A property rather than a class, so `classes.root` can still replace it. |
| `onend?` | `() => void` | Called when the end comes within `endThreshold` px — the hook for infinite scroll. Fires once per length of `items`, so appending a page re-arms it. |
| `endThreshold?` | `number` | How far before the end `onend` fires, in px. Default `400`. |
| `loading?` | `Snippet` | Drawn after the last row — pass it while there is more to load. With no items yet it is drawn instead of `empty`: the first page on its way is not an empty list. |
| `empty?` | `Snippet` | Drawn in place of the list when `items` is empty. |
| `itemRole?` | `string` | Role of each row's wrapper. Defaults to `listitem` under the default `role="list"`, and to none under any other role — a `listbox` brings its own `option`s. |
| `onscroll?` | `(event: Event) => void` | Called on every scroll, after the window has been updated. |
| `class?` | `string` |  |
| `classes?` | `VirtualListClasses` | Per-part Tailwind overrides. `class` still covers the root. |

### Workspace

`import { Workspace } from 'omaris'`

A dockable workspace: panels in tabbed groups, split any way, dragged anywhere, floated into windows, maximized, and remembered.

#### Use it for

- A screen people arrange for themselves: an editor with its files,
  terminal and preview; an admin console of logs, charts and a runbook; a
  dashboard whose cards someone drags into the order they read them.
- Tools with many views and not enough room for all of them at once — tabs
  stack what does not fit, splits show what must be side by side, and a
  floating window holds what is needed for a minute.
- Content that must survive being moved. A panel's content is mounted once
  and never re-parented, so an iframe, a video, a form or a scrolled list
  keeps its state through every drag.
- An arrangement that should come back tomorrow: `storageKey` saves it, or
  `bind:layout` hands you the JSON to keep on a server.
- Panels that come from data: a `WorkspacePanel` in an `{#each}` with `open`
  appears next to the others the moment it exists.

#### Not for

- One sidebar beside one content area with a draggable divider →
  [Resizable](/docs/components/resizable).
- Views of one thing, switched one at a time, that nobody rearranges →
  [Tabs](/docs/components/tabs).
- The frame of an app — its navigation and the column that scrolls →
  [App Shell](/docs/components/app-shell). Put the workspace inside it.
- Cards in a grid that people only reorder → [Kanban](/docs/components/kanban),
  or a plain CSS grid.
- A panel that slides in over the page and leaves again →
  [Sheet](/docs/components/sheet).

#### Do

- Give it a height. It fills its parent, which needs `h-…` or a flex column
  with `min-h-0`.
- Write `defaultLayout` with `row`, `column` and `tabs` — a string is a panel
  in a group of its own, an array is a group of tabs, and a trailing
  `{ sizes: [30, 70] }` sets the shares. It is also what the server renders.
- Give every panel an `id` that means something (`'terminal'`, not `'p3'`) and
  keep it stable: saved layouts refer to panels by id.
- Put `class="p-4"` on a `WorkspacePanel` for padding. Its content box
  scrolls on its own.
- Use `bind:open` for a toolbar toggle or a menu of checkboxes. A panel
  switched off remembers its place.
- Pause expensive work in a hidden tab with `getWorkspacePanel().shown`.

#### Don't

- Reorder an `{#each}` of panels to change the layout. The layout says where
  panels are; the markup only declares them. Move them with `move()` or let
  people drag them.
- Use the same `storageKey` for two workspaces. They overwrite each other.
- Make every panel `closable={false}` and `movable={false}` — that is a
  static grid, and a grid is simpler.
- Rely on the tab strip alone on a phone. Below `compactBelow` the workspace
  becomes one stack of tabs; keep the most-used panel first in the layout.

#### Pairs with

- [App Shell](/docs/components/app-shell), [Menu](/docs/components/menu),
  [Stat Card](/docs/components/stat-card), [Code Editor](/docs/components/code-editor),
  [Log Viewer](/docs/components/log-viewer), [Table](/docs/components/table),
  [Kbd](/docs/components/kbd)

Parts (`classes`): `root` `stage` `group` `header` `tabs` `tab` `tabButton` `close` `badge` `tools` `sash` `preview` `caret` `ghost` `handle` `empty`

| Prop | Type | Notes |
| --- | --- | --- |
| `layout?` | `WorkspaceLayout` | The layout, bindable. Leave it out and the workspace keeps its own, starting from `defaultLayout`; bind it to save it yourself, or to switch between presets by assigning one. Bindable. |
| `defaultLayout?` | `WorkspaceLayoutInput` | Where the panels start, and what `reset()` goes back to. Write it with `row`, `column` and `tabs`: `row('files', column('editor', 'terminal'), { sizes: [20, 80] })`. Left out, every panel sits side by side in the order declared. |
| `storageKey?` | `string` | Saves the layout in `localStorage` under this key and restores it on load. |
| `variant?` | `WorkspaceVariant` | One of `cards`, `flush`. Default `'cards'`. |
| `compactBelow?` | `number` | Below this width, in px, every panel becomes a tab in one full-size stack — the workspace on a phone. `0` never stacks. Default `600`. |
| `locked?` | `boolean` | Nothing moves: no dragging, resizing, closing or floating. Tabs still switch. Default `false`. |
| `floating?` | `boolean` | Panels may leave the tree for floating windows. Default `true`. |
| `maximizable?` | `boolean` | Groups may be maximized to fill the workspace. Default `true`. |
| `labels?` | `Partial<WorkspaceLabels>` |  |
| `class?` | `string` |  |
| `classes?` | `WorkspaceClasses` | Per-part Tailwind overrides. `class` still covers the root. |
| `empty?` | `Snippet<[{ closed: string[]; show: (id: string) => void }]>` | What shows when every panel is closed. It gets the closed panels' ids and a way to open one. |
| `onlayoutchange?` | `(layout: WorkspaceLayout) => void` | Fires after every change the person makes — a move, a resize, a close. |
| `onactivate?` | `(id: string) => void` | A panel was brought to the front. |
| `children?` | `Snippet` | The `WorkspacePanel`s. |

### WorkspacePanel

`import { WorkspacePanel } from 'omaris'`

One panel of a `Workspace`: a title for its tab, and the content.

| Prop | Type | Notes |
| --- | --- | --- |
| `id` | `string` | Names the panel in the layout. Unique within the workspace. |
| `title` | `string` | What its tab says. |
| `icon?` | `Snippet` | Leading icon for the tab. |
| `badge?` | `number \| string \| boolean` | A count or short word after the title, or `true` for a dot. |
| `modified?` | `boolean` | Unsaved changes: a dot where the close button sits until it is hovered. Default `false`. |
| `closable?` | `boolean` | Has a close button, and Delete closes it. Default `true`. |
| `movable?` | `boolean` | May be dragged, split off and moved with the keyboard. Default `true`. |
| `floatable?` | `boolean` | May go into a floating window. Default `true`. |
| `minWidth?` | `number` | Smallest width its group may be dragged to, in px. Default `160`. |
| `minHeight?` | `number` | Smallest height of its content, in px — the tab strip comes on top. Default `80`. |
| `keepAlive?` | `boolean` | Stay mounted, hidden, while closed — for a panel that is slow to build. Default `false`. |
| `open?` | `boolean` | Bindable: whether the panel is in the layout. Set it to open or close the panel from outside — a toolbar toggle, a menu of checkboxes. Bindable. |
| `placement?` | `WorkspacePlacement` | Where it goes when `open` is set and it has no remembered place. |
| `actions?` | `Snippet` | Buttons for the group's header while this panel is on show — a refresh, a filter. |
| `onclose?` | `() => boolean \| void \| Promise<boolean \| void>` | Asked before closing: return `false`, or a promise of it, to keep the panel. |
| `class?` | `string` | Covers the content box: padding, a background, a layout. |
| `children?` | `Snippet` |  |

---

# Guides

<!-- /docs/introduction -->

omaris is a component library for SvelteKit — Svelte 5, Tailwind v4, and a
Material 3 accent: the colour roles, state layers, ripples, elevation and
easing that make an interface feel good, without the spec. It was built for
dashboards, and it shows: an app shell that scrolls correctly, a data table,
resizable panels, a drawer that is a rail on a laptop and a modal on a phone,
and charts and maps behind their own entry points.

```demo
button/variants
```

## What it assumes

- **SvelteKit and Svelte 5.** Runes, not stores. There is no Svelte 4 build.
- **Tailwind v4.** Styling is utilities and design tokens. There is no
  `styled` API and no CSS-in-JS.
- **You bring the icons.** Hand any component an `<svg>` and it sets the size
  and the colour. Bundling an icon set would be a taste decision and a bundle
  decision, and both are yours.

## What makes it different

**One knob re-skins everything.** Colours are OKLCH expressed in terms of a
hue, a chroma multiplier and a tint. Change the hue and the whole app moves
with it, syntax highlighting included, in both light and dark.

**Every part is reachable.** `class` styles a component's root and is merged
last, so your utility always wins. Anything deeper is a named key on `classes`.
You never have to fork a component to move one element.

**Every page says when.** A component page opens with "Use it for" and "Not
for" — and every "Not for" names the component to use instead. The API under
it is generated from the source, indexed by [llms.txt](/llms.txt), and shipped
in the package, so an agent reads the same page you do and neither of you
guesses.

## When not to use it

If you want a headless library you style from scratch, this is the wrong shape
— omaris has opinions about how things look and moves them out of your way
rather than having none. If you are not on Tailwind, none of the override story
works. And if you need Svelte 4, it will not install.

## Where to go next

- [Start a project](/docs/start-a-project) — three commands and a first screen.
- [Choosing a component](/docs/choosing-a-component) — the look-alikes, told apart.
- [Building a screen](/docs/building-a-screen) — shell, rhythm, surfaces, states, phone.
- [Styling](/docs/styling) — `class`, `classes`, and the one merge rule that
  surprises people. Read this before you fight a component.

---

<!-- /docs/installation -->

## The short way

```bash
bunx omaris init
```

That installs the package, wires the stylesheet and the provider into your app,
and writes an `AGENTS.md` so an AI agent working in the project reads the
conventions before it writes anything. Run it in an existing SvelteKit app; it
will tell you what it is about to change and skip anything already done.

## By hand

**1. Install it.**

```bash
bun add omaris
```

**2. Import the stylesheet** — this is the only stylesheet omaris has, and it
carries the tokens, the type scale and the Tailwind theme.

```css title=src/app.css
@import 'omaris/app.css';
```

Add the fonts too if you want Geist, which is what the type scale is drawn for:

```css title=src/app.css
@import 'omaris/fonts.css';
@import 'omaris/app.css';
```

**3. Wrap the app once** in `OmarisProvider`. It mounts the hosts that toasts
and dialogs render into, and starts the theme.

```svelte title=src/routes/+layout.svelte
<script>
	import '../app.css';
	import { OmarisProvider } from 'omaris';

	let { children } = $props();
</script>

<OmarisProvider>
	{@render children()}
</OmarisProvider>
```

**4. Use it.**

```svelte
<script>
	import { Button, Card, CardContent } from 'omaris';
</script>

<Card>
	<CardContent>
		<Button>Ship it</Button>
	</CardContent>
</Card>
```

## Make it installable

```bash
bunx omaris pwa
```

One command turns the app into a PWA — manifest, icons, offline service worker.
`bunx omaris native` takes the same app to the Play Store and the App Store.
See [On a phone](/docs/mobile).

## Charts and maps

Both live behind their own entry points, because `layerchart` and `maplibre-gl`
together are tens of megabytes and nobody importing a `Button` should pay for
them. They are optional peer dependencies, so they install only if you ask.

```bash
bun add layerchart d3-shape   # for omaris/chart
bun add maplibre-gl           # for omaris/map
```

> **Note** In `vite dev`, exclude `maplibre-gl` from `optimizeDeps` so the dev
> server serves its tile worker. A production build needs nothing — see
> [Charts and maps](/docs/charts-and-maps).

## Requirements

|              |              |
| ------------ | ------------ |
| Svelte       | 5.0 or later |
| SvelteKit    | 2.0 or later |
| Tailwind CSS | 4.0 or later |

---

<!-- /docs/provider -->

`OmarisProvider` wraps your app once, at the root layout. It mounts the hosts
that floating UI renders into and it starts the theme before the first paint.

```svelte title=src/routes/+layout.svelte
<script>
	import '../app.css';
	import { OmarisProvider } from 'omaris';

	let { children } = $props();
</script>

<OmarisProvider>
	{@render children()}
</OmarisProvider>
```

## What it turns on

|                    |                                                                   |
| ------------------ | ----------------------------------------------------------------- |
| `toast()`          | Toast stack, plus `toast.success/error/warning/info`.             |
| `dialog.confirm()` | Promise-returning dialogs — also `alert`, `prompt`, `custom`.     |
| `theme`            | The theme store, applied to `<html>` and read by every component. |
| Light and dark     | Resolved before first paint, so nothing flashes.                  |

Without it, those imperative APIs have nowhere to render and silently do
nothing. Everything else — every component you import directly — works fine
without it.

## Setting your product's defaults

The `theme` prop is your product's starting point, and what `theme.reset()`
returns to. It is not a lock: a user can still change anything, and with
`persist` their choices survive a reload.

```svelte
<OmarisProvider
	theme={{ preset: 'ocean', radius: 'sm', density: 'comfortable' }}
	defaultMode="system"
	persist
>
	{@render children()}
</OmarisProvider>
```

## Turning pieces off

Each host can be configured or removed. Pass `false` to leave one out entirely —
useful when you are rendering it yourself somewhere specific.

```svelte
<OmarisProvider toaster={{ position: 'bottom-end' }} dialogs>
	{@render children()}
</OmarisProvider>
```

## Imperative APIs

These are plain function calls from anywhere — no component, no context hook.

```ts
import { toast, dialog } from 'omaris';

toast.success('Saved');

const ok = await dialog.confirm({ title: 'Delete this?', destructive: true });
const name = await dialog.prompt({ title: 'Rename', value: current });
```

## Haptics

Off unless you ask, because vibration you did not opt into feels like a bug.

```svelte
<OmarisProvider haptics>{@render children()}</OmarisProvider>
```

---

<!-- /docs/start-a-project -->

Three commands, then a decision about how to organise the code. The commands
are fixed; the shape is a suggestion, and the last section says why.

## The first ten minutes

```bash
bunx sv create my-app      # SvelteKit, TypeScript, Tailwind — say yes to Tailwind
cd my-app
bunx omaris init           # installs omaris, wires the stylesheet and the provider
bunx omaris pwa            # optional: manifest, icons, offline service worker
bunx omaris native         # optional: an Android and an iOS project
```

`init` also writes an `AGENTS.md` next to your code: the conventions on this
site, in the flat imperative form a coding agent reads before it writes
anything. Keep it; it is how a model working in your project stops guessing
prop names. See [Feeding this to a model](/docs/ai).

Then set the product's look once, at the root:

```svelte title=src/routes/+layout.svelte
<script>
	import '../app.css';
	import { OmarisProvider } from 'omaris';

	let { children } = $props();
</script>

<OmarisProvider theme={{ preset: 'ocean' }} defaultMode="system" persist>
	{@render children()}
</OmarisProvider>
```

Ten presets, or a hue of your own — [Theming](/docs/theming). Everything you
build after this follows that one line.

## The first screen

Most omaris apps are a shell with one scrolling column. Get it in place before
the first page, because the scrolling is hard to retrofit.

```demo
app-shell/dashboard-frame
```

```svelte title=src/routes/+layout.svelte (inside the provider)
<AppShell>
	<AppShellSidebar>
		<NavigationDrawer responsive bordered>
			<NavigationDrawerItem href="/" label="Overview" selected />
			<NavigationDrawerItem href="/orders" label="Orders" badge={12} />
		</NavigationDrawer>
	</AppShellSidebar>

	<AppShellMain>
		<TopAppBar title="Overview" sticky />
		<AppShellContent width="xl">
			{@render children()}
		</AppShellContent>
	</AppShellMain>
</AppShell>
```

Only the content column scrolls; the sidebar stays put and the app bar finds
its own scroller, so `sticky` works and there is never a second scrollbar.
`responsive` makes the drawer a sidebar on a laptop and a modal on a phone,
so you write one drawer. `width="xl"` sets the reading measure — leave it off
and a dashboard goes full-bleed on a wide monitor.

From here, [Building a screen](/docs/building-a-screen) is the next page.

## Two ways to shape the code

omaris does not care how your project is organised. These are two shapes
that have worked, offered so you do not have to invent one on day one. Use
your own if you have one.

### Routes only

For a small app — a handful of pages, no shared state to speak of.

```
src/routes/
  +layout.svelte          provider, shell, navigation
  +page.svelte            the overview
  orders/+page.svelte
  orders/[id]/+page.svelte
src/lib/
  components/             the pieces two pages share
  api.ts                  the calls to your backend
```

The page file holds its own state. When a page grows past a screen of code,
pull a section out into `src/lib/components/` and keep going. This is fine for
longer than people expect.

### Features, with the logic beside the markup

For a dashboard that will be worked on for a year. This is the shape `omaris
init` writes into `AGENTS.md`, because it gives an agent one place to put each
thing.

```
src/lib/
  features/
    orders/
      table/
        index.svelte        markup only — calls the logic once and renders
        logic.svelte.ts     $state, $derived, handlers
        row.svelte          a markup-only fragment
      add/
        index.svelte
        logic.svelte.ts
  shared/                   used by two or more features; same shape
  api/orders/index.ts       the only thing UI calls for data
  server/orders/logic.ts    the work, framework-free
src/routes/
  (app)/orders/+page.svelte imports the feature and lays it out; no state
```

The rules that make it hold: a folder means it has logic; `index.svelte` has
no `$state` of its own; a route's name is its feature's name; `shared/` at
the second user, not the first. The full list is in the `AGENTS.md` that
`init` writes.

### What both have in common

- **One `OmarisProvider`, at the root.** It hosts toasts and dialogs and
  starts the theme before first paint. A second one is a bug.
- **Import from `omaris`;** charts from `omaris/chart`, maps from
  `omaris/map`. Nothing else is a public path.
- **Read the component's page before using it.** The top of each page says
  when it is the right choice and, more usefully, when it is not.

## What to read next

- [Principles](/docs/principles) — five rules that make screens look like one product.
- [Choosing a component](/docs/choosing-a-component) — the look-alikes, told apart.
- [Building a screen](/docs/building-a-screen) — shell, rhythm, surfaces, states.
- [Making it look designed](/docs/look) — personality, one hero, space, two greys.
- [Footguns](/docs/footguns) — the mistakes that compile.

---

<!-- /docs/mobile -->

Three ways to get this app onto a phone. Start at the top.

| Want                     | Command              | Needs                     |
| ------------------------ | -------------------- | ------------------------- |
| Install from the browser | `bunx omaris pwa`    | nothing                   |
| One file you can send    | `bunx omaris apk`    | a JDK and the Android SDK |
| Play Store, App Store    | `bunx omaris native` | Android Studio, Xcode     |

The components need no changes for any of it — they render in a WebView.

## Installable

```bash
bunx omaris pwa
```

Writes `static/manifest.webmanifest`, the icons each browser asks for, the head
tags that link them, and the `src/service-worker.ts` SvelteKit registers on its
own: build assets from cache, pages network-first so they open offline.

```bash
bunx omaris pwa --name "Ledger" --theme '#0b0b0c'   # name and colour
bunx omaris pwa --no-icons                          # keep the artwork you have
bunx omaris pwa --dry-run                           # show it, write nothing
```

The icons are a monogram in your theme colour, so there is nothing to design
first. Overwrite `static/icons/` when you have real artwork.

> **Note** A service worker only runs in a real build. Check it with
> `bun run build && bun run preview`, not `bun dev`.

Nothing is ever overwritten, so a second run only adds what is missing — which
means `--theme` changes nothing once the icons exist. Delete `static/icons/` and
`static/manifest.webmanifest` to redraw them.

## Android and iOS

```bash
bunx omaris native
```

Installs [Capacitor](https://capacitorjs.com), switches the build to a static
SPA, writes `capacitor.config.json`, generates `android/` and `ios/`, draws the
launcher icons, and adds the scripts you use from then on:

| Script                | Does                                     |
| --------------------- | ---------------------------------------- |
| `bun run android:run` | run on a device, reloading as you edit   |
| `bun run android:apk` | build one installable `.apk` — see below |
| `bun run android`     | build, sync, open Android Studio         |
| `bun run ios:run`     | run on a device, reloading as you edit   |
| `bun run ios`         | build, sync, open Xcode                  |

```bash
bunx omaris native --app-id com.acme.ledger   # the id the stores key your listing on
bunx omaris native --theme '#0b6bcb'          # the icon colour
bunx omaris native --no-ios                   # Android only
bunx omaris native --dry-run                  # show it, write nothing
```

> **Warning** Set `--app-id` before you publish. It is how Play and the App
> Store identify your app and it cannot be changed afterwards. The default is
> `com.example.<your-app>` — the one prefix that can't be published by accident.

Run `omaris pwa` first and the launcher icons pick up the colour already in the
manifest, so the home-screen icon and the one in the app drawer match.

Android needs Android Studio; iOS needs a Mac with Xcode. Neither is something a
CLI can install for you.

### What it changed

| File                    | Why                                                  |
| ----------------------- | ---------------------------------------------------- |
| `vite.config.ts`        | `adapter-static`, falling back to one `index.html`   |
| `vite.config.ts`        | Vite's watcher kept out of `android/` and `ios/`     |
| `src/routes/+layout.ts` | `ssr = false` — there is no server inside an app     |
| `capacitor.config.json` | the app's id, its name, and where the build lands    |
| `src/app.html`          | `viewport-fit=cover`, so the safe-area insets report |

The adapter is the one worth knowing about: SvelteKit moved it into
`vite.config.ts`, and every Capacitor guide written before that tells you to
edit a `svelte.config.js` your project does not have. The watcher is the one
nobody mentions: after one Gradle build `android/` is thousands of files, which
is enough to hit Linux's inotify limit and stop the dev server noticing edits.

## Reloading as you edit

```bash
bun run android:run     # or bun run ios:run
```

You don't rebuild for every change. That script starts the dev server, works out
the address your phone can reach it on, builds and installs the app once, and
launches it pointed at the server — so from then on a save reloads the app the
same way it reloads the browser. Ctrl-C stops the server and puts the native
project back the way it was.

Nothing is written to your `capacitor.config.json`. The address goes to
`cap run` as a flag, which sets it in the native project's copy for the run and
reverts it after — so there is no `server.url` block to remember to delete
before you build something real, the mistake that ships an app pointing at a
laptop.

Phone and laptop have to be on the same network. A blank screen on the phone
means it cannot reach the address the command printed — a firewall on the
laptop, nearly always; allow the port, or use `--forward-ports` over USB.

The flags belong to `omaris run`, and `bun run android:run --packaged` passes
them through (`npm run android:run -- --packaged`).

| Flag                        | For                                            |
| --------------------------- | ---------------------------------------------- |
| `--packaged`                | the built app instead: no server, no reloading |
| `--port 3000`               | a dev server that isn't on 5173                |
| `--host 192.168.1.20`       | choosing the address yourself                  |
| `--target emulator-5554`    | one device out of several                      |
| `--forward-ports 5173:5173` | a device on USB with no route to your machine  |

Only web code reloads. Adding a Capacitor plugin, editing anything inside
`android/` or `ios/`, or changing the app id or icons still means a rebuild.

## An APK you can send

```bash
bun run android:apk     # or, from anywhere: bunx omaris apk
```

Builds the web app, syncs it into `android/`, runs Gradle, and copies the result
next to `package.json` as `<your-app>-debug.apk`. No IDE is opened at any point.

```bash
adb install -r ledger-debug.apk   # over USB
```

Or send the file. Android installs it from the Files app, once that app is
allowed to install unknown apps.

A debug APK installs anywhere and is what you want for testers. Play does not
accept one — a store upload is a signed `.aab`, which is Android Studio's
**Build → Generate Signed App Bundle**. `bunx omaris apk --release` runs
`assembleRelease` instead, and that APK is unsigned, so no phone will install it
until you add a `signingConfig`.

The two ways it fails are both the machine, not the project:

| Gradle says              | Do                                                             |
| ------------------------ | -------------------------------------------------------------- |
| `SDK location not found` | set `ANDROID_HOME`, or open the project once in Android Studio |
| `JAVA_HOME is not set`   | install a JDK 21 and point `JAVA_HOME` at it                   |

> **Note** Ran `omaris native` before this script existed? Run it again — it
> only adds what is missing, and `android:apk` is one of them.

## Three things to get right

**Fonts work offline.** `omaris/fonts.css` ships its woff2 files inside the
package, so a packaged app draws Geist with no network. Replacing them with
your own is a matter of `@font-face` rules; the token names don't change. See
[Typography](/docs/typography).

**Give controls a thumb.** The default control height is 40px, drawn for a
mouse; Apple and Google both ask for 44. Set `size="lg"` on anything a finger
has to hit. A number that has bounds can skip the keypad entirely —
`<NumberInput picker min={30} max={200} />` is a field on a desktop and a wheel
in a bottom sheet under a thumb.

**Respect the safe areas.** `native` sets `viewport-fit=cover`, which is what
makes the insets report at all — the padding is still yours to add, or anything
pinned to an edge sits under the status bar. Wrap the app once:

```svelte
<SafeArea class="min-h-dvh">
	{@render children()}
</SafeArea>
```

…and one edge at a time where a bar is supposed to reach the glass:

```svelte
<footer class="bg-surface-container">
	<SafeArea edges={['bottom']} min={12}>…</SafeArea>
</footer>
```

`min` is the part people forget: half the phones in the world report `0` for
the bottom inset, so padding that is only the inset is no padding at all on
them. The same insets are spacing utilities (`pt-safe-top`, `pb-safe-bottom`,
`ps-safe-start`, `pe-safe-end`) when a wrapper is one element too many, and
numbers on the `safeArea` rune when a canvas has to be drawn around them.
`<SafeArea keyboard>` grows the bottom edge by however much the on-screen
keyboard is covering, which is the other thing that eats a bottom action row.

See [Safe Area](/docs/components/safe-area).

## Not this

Reach for React Native, Flutter or Kotlin and none of omaris comes with you. The
trade is worth it only when the app is mostly native — heavy gestures,
background work, real-time graphics. A dashboard is not that.

---

<!-- /docs/upgrading -->

An upgrade never breaks your code. No export, prop, slot or token is renamed or removed. A new prop always defaults to what the component already did.

Some upgrades do change how an app _feels_ with no code change: a press, a phone layout. Each of those changes has an off switch, listed here. An agent working in your app reads this page from `node_modules/omaris/docs`.

```sh
bun add omaris@latest
bunx omaris init   # adds what's new, never overwrites what you edited
```

## Changed defaults

### Presses give under the finger

`Button`, `IconButton`, `Fab` and clickable `Chip` shrink slightly while pressed, then ease back. A native button does the same. The effect respects reduced motion.

| Keep the old behaviour | How                              |
| ---------------------- | -------------------------------- |
| Everywhere             | `<html data-press="none">`       |
| One control            | `class="active:scale-100"`       |
| A different depth      | `:root { --press-scale: 0.95; }` |

### Phone-sized targets on a touch screen

Under a coarse pointer (a phone or a tablet), the default `sm` `Button` and `IconButton` are at least 44px tall, up from 40px. This is the size Apple and Material give for a first-time thumb hit. On a mouse, nothing changes. The dense `xs` size is left alone.

| Keep the old behaviour | How                                 |
| ---------------------- | ----------------------------------- |
| Everywhere             | `<html data-touch="compact">`       |
| One control            | set its height, e.g. `class="h-10"` |

### Menus, selects and popovers are sheets on a phone

Below 640px wide, these open from the bottom edge as a sheet instead of hanging off their trigger: `Menu`, `ContextMenu`, `Select`, a non-searchable `MultiSelect`, and a click-opened `Popover`.

A sheet is full width, with a grip and a dimmed backdrop. It follows the safe area. Dragging it down or tapping outside dismisses it, and the page behind stays still. Keyboard handling and ARIA are unchanged. `Combobox` and a searchable `MultiSelect` stay anchored, because the on-screen keyboard needs the field.

| Keep the old behaviour | How                   |
| ---------------------- | --------------------- |
| One overlay            | `mobileSheet={false}` |

These overlays also animate on the way out now, back toward their trigger, instead of vanishing.

## Fixed

- **Stacked overlays no longer free the page early.** Open a `Sheet` over a `Dialog`, close one, and the page used to start scrolling behind the one still open. Every overlay now shares one page lock, so the page scrolls again only after the last one closes.

---

<!-- /docs/principles -->

The components agree with each other because they all follow the same five
rules. Follow them in the code between the components — the layouts, the
one-off elements, the overrides — and the whole screen agrees too. None of
this is a style guide to memorise; each rule is one sentence and one habit.

## 1. Emphasis is hierarchy

One thing on a screen is the thing. It gets the `filled` treatment; everything
else steps down — `tonal`, then `outlined`, then `text`. The same ladder runs
through buttons, chips, cards, badges and alerts, which is why a screen with
one filled button reads as calm and a screen with five reads as shouting.

```demo
button/variants
```

**The habit:** before adding a filled anything, find the one that is already
there. If there is one, yours is tonal.

## 2. Depth comes from surfaces, not lines

A card is not a box with a border. It is a tier of surface — `lowest` to
`highest` — that reads as closer to the reader without a shadow. Nest tiers
to group things; reach for a border or a divider only when the grouping is
still unclear.

```demo
tokens/surface-tiers
```

**The habit:** page `bg-background` → a panel `bg-surface-container-low` → a
raised card `bg-surface-container` → a well inside it
`bg-surface-container-high`. Up one tier per level of nesting, and stop at
three.

## 3. Tokens, never values

`bg-primary`, not a hex. `rounded-shape-lg`, not `rounded-[16px]`.
`shadow-2`, not `shadow-md`. A token follows the theme — the hue, the
roundness, dark mode, high contrast, the density slider — and a raw value
follows nothing, so it is the one thing on the screen that will look wrong
the moment someone changes a setting.

```demo
tokens/colour-roles
```

**The habit:** every colour is a role and comes as a pair. `bg-primary` with
`text-primary-foreground`; `bg-primary-container` with
`text-primary-container-foreground`. Use the pair and the contrast is
handled in both themes. The roles are on the [Design tokens](/docs/tokens)
page.

## 4. Motion is feedback

Things move because something happened: a button pressed, a panel opened, a
card grew to fit new content. Motion that runs on its own is decoration, and
decoration is opt-in — the library ships no idle animation, and everything
that moves says what `motion-reduce` does to it.

```demo
island/growing
```

**The habit:** transition the property that changed, on an MD3 curve —
`ease-emphasized` for things arriving, `ease-standard` for state — with
`motion-reduce:transition-none` beside it. If you cannot say what user action
the animation answers, delete it.

## 5. Every part is reachable, so never fork

`class` styles a component's root and always wins. `classes={{ part: '…' }}`
reaches every inner element by name. Between the two there is no element you
cannot restyle, which means there is never a reason to copy a component into
your project to change one thing about it.

```demo
styling/classes-parts
```

**The habit:** when an override does not take, it is not the component
ignoring you; it is [the merge rule](/docs/styling) — `aspect-video` does not
cancel a height, because they are different groups. Look for the prop the
component gives you instead.

## What this adds up to

A screen where the primary action is obvious, the grouping is felt rather
than drawn, everything follows the theme, nothing moves without a reason,
and nothing was forked. That is the whole design system. The component pages
say which part to use where; [Building a screen](/docs/building-a-screen)
says how to put them together.

---

<!-- /docs/choosing-a-component -->

Most wrong choices are between two components that look the same and mean
different things. Each table below is one of those families. Find the row
that sounds like your situation; the component in it is the answer, and its
page opens with the same "Use it for / Not for" so you can check.

## Something to press

| The situation                                               | Use                                                             | Because                                               |
| ----------------------------------------------------------- | --------------------------------------------------------------- | ----------------------------------------------------- |
| The one action the screen is about                          | [Button](/docs/components/button) `filled`                      | Once per view. Everything else steps down.            |
| The other actions beside it                                 | [Button](/docs/components/button) `tonal` / `outlined` / `text` | The emphasis ladder, in that order.                   |
| The action is only an icon                                  | [Icon Button](/docs/components/icon-button)                     | Same tones, its own geometry, `aria-label` required.  |
| The screen's main action, floating, on a phone              | [FAB](/docs/components/fab)                                     | One per screen. Sits above the content.               |
| One action plus a menu of alternatives                      | [Split Button](/docs/components/split-button)                   | The wide half acts, the narrow half opens the rest.   |
| A few related actions that read as one control              | [Button Group](/docs/components/button-group)                   | Layout only; the buttons stay plain.                  |
| A list of actions hanging off a trigger                     | [Menu](/docs/components/menu)                                   | Actions, not values.                                  |
| A small action inline with content — "add filter", "assist" | [Chip](/docs/components/chip)                                   | The assist chip.                                      |
| Navigation to another page                                  | `Button href`, or a plain link                                  | A link is a link; `variant="link"` inside a sentence. |

## Something to choose

| The situation                                         | Use                                                                                                                                                                                    | Because                                                       |
| ----------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------- |
| One of a few options, all visible, mutually exclusive | [Segmented Button](/docs/components/segmented-button)                                                                                                                                  | Two to five options, short labels.                            |
| One of a few options, in a form                       | [Radio](/docs/components/radio)                                                                                                                                                        | The choice is submitted, not applied.                         |
| One of many options                                   | [Select](/docs/components/select)                                                                                                                                                      | A styled list of values.                                      |
| One of many, and you have to search for it            | [Combobox](/docs/components/combobox)                                                                                                                                                  | Type to filter; `load` for the server.                        |
| An on/off that takes effect immediately               | [Switch](/docs/components/switch)                                                                                                                                                      | A setting. Nothing to submit.                                 |
| A yes/no that is submitted with the form              | [Checkbox](/docs/components/checkbox)                                                                                                                                                  | Also "select this row".                                       |
| Several of many, above a list                         | filter [Chips](/docs/components/chip)                                                                                                                                                  | The filter bar.                                               |
| A number in a range                                   | [Slider](/docs/components/slider)                                                                                                                                                      | Precision does not matter; the feel does.                     |
| A colour, a phone number, a price, an emoji           | [Color Picker](/docs/components/color-picker), [Phone Input](/docs/components/phone-input), [Price Input](/docs/components/price-input), [Emoji Picker](/docs/components/emoji-picker) | Each one stores the right value and shows the right keyboard. |

## Something to type

| The situation                                            | Use                                                   | Because                                                          |
| -------------------------------------------------------- | ----------------------------------------------------- | ---------------------------------------------------------------- |
| One line                                                 | [Text Field](/docs/components/input)                  | Label, supporting text, affixes, clear, password eye — built in. |
| One line with a shape — a slug, a decimal, a card number | [Text Field](/docs/components/input) with `format`    | Rejects what does not fit as it is typed.                        |
| A few lines                                              | [Textarea](/docs/components/textarea)                 | `autosize` for a composer.                                       |
| Formatted prose                                          | [Rich Text Editor](/docs/components/rich-text-editor) | A `contenteditable` and a toolbar; nothing heavier.              |
| Code                                                     | [Code Editor](/docs/components/code-editor)           | A real textarea with a painted highlight layer, vim optional.    |

## Something on top of the page

| The situation                                              | Use                                           | Because                                                    |
| ---------------------------------------------------------- | --------------------------------------------- | ---------------------------------------------------------- |
| A decision the person must make before continuing          | [Dialog](/docs/components/dialog)             | Interrupts. `await dialog.confirm(…)` for the common case. |
| A task that keeps the page in view — edit, filter, details | [Sheet](/docs/components/sheet)               | A side panel on a laptop, a bottom sheet on a phone.       |
| A list of actions                                          | [Menu](/docs/components/menu)                 | Anchored, dismisses on choice.                             |
| A word or two about a control, on hover                    | [Tooltip](/docs/components/tooltip)           | Never for anything the person must read.                   |
| A picture, full screen                                     | [Image Viewer](/docs/components/image-viewer) | Tap to lift it off the page.                               |
| A first-run walkthrough                                    | [Tour](/docs/components/tour)                 | A spotlight, one thing at a time.                          |

## Telling the person something

| What happened                          | Show                                                                           | Because                                                                     |
| -------------------------------------- | ------------------------------------------------------------------------------ | --------------------------------------------------------------------------- |
| Something succeeded or failed, briefly | [Toast](/docs/components/toast)                                                | Never blocks; `toast.promise` follows the request.                          |
| Something about this page, that stays  | [Alert](/docs/components/alert)                                                | A banner in the content, with a tone.                                       |
| Something is on its way                | [Progress](/docs/components/progress) or [Skeleton](/docs/components/skeleton) | A bar when there is a known amount; a skeleton the shape of what is coming. |
| There is nothing to show               | [Empty](/docs/components/empty)                                                | With the one action that changes that.                                      |
| A count, or a status, on something     | [Badge](/docs/components/badge)                                                | A pill on its own, or a dot on an icon.                                     |
| Something that needs a decision        | [Dialog](/docs/components/dialog)                                              | See above.                                                                  |

More on this in [Feedback](/docs/feedback).

## Something to hold content

| The situation                             | Use                                     | Because                                                          |
| ----------------------------------------- | --------------------------------------- | ---------------------------------------------------------------- |
| A unit of content — one order, one metric | [Card](/docs/components/card)           | Defaults to `outlined`; a grid of them usually wants `elevated`. |
| Rows of one to three lines each           | [List](/docs/components/list)           | Swipe actions on a phone.                                        |
| Rows with columns, sorting, selection     | [Table](/docs/components/table)         | Server-side paging when it is big.                               |
| Sections that expand one at a time        | [Accordion](/docs/components/accordion) | Content in the page, not off it.                                 |
| Sections that swap                        | [Tabs](/docs/components/tabs)           | Within a page — not app navigation.                              |
| Panels the person can drag                | [Resizable](/docs/components/resizable) | Remembers the layout.                                            |
| Media, side by side, swiped               | [Carousel](/docs/components/carousel)   | Five layouts.                                                    |
| Photos of different heights               | [Masonry](/docs/components/masonry)     | The photo wall.                                                  |
| Cards you drag between columns            | [Kanban](/docs/components/kanban)       | A board, not a table.                                            |

## Getting around

| The situation                            | Use                                                     | Because                                                          |
| ---------------------------------------- | ------------------------------------------------------- | ---------------------------------------------------------------- |
| Top-level destinations, on a laptop      | [Navigation Drawer](/docs/components/navigation-drawer) | `collapsed` is the rail; `responsive` makes it modal on a phone. |
| Top-level destinations, on a phone       | [Navigation Bar](/docs/components/navigation-bar)       | Three to five, at the bottom.                                    |
| The title of this screen and its actions | [Top App Bar](/docs/components/top-app-bar)             | Pass `sticky`.                                                   |
| Where you are, in a hierarchy            | [Breadcrumb](/docs/components/breadcrumb)               | Collapses in the middle.                                         |
| Views within a page                      | [Tabs](/docs/components/tabs)                           | Primary on top, secondary nested.                                |
| Pages of a long list                     | [Pagination](/docs/components/pagination)               | Or the Table's own.                                              |
| Sections of a long page                  | [Table of Contents](/docs/components/toc)               | The rail on the right of this page.                              |
| Searching the whole app                  | [Search Bar](/docs/components/search-bar)               | The bar and the view it opens into.                              |

## Showing data

| The situation                 | Use                                              | Because                                 |
| ----------------------------- | ------------------------------------------------ | --------------------------------------- |
| A number over time            | Line or Area [Chart](/docs/components/chart)     | Time goes on the x axis.                |
| Numbers by category           | Bar [Chart](/docs/components/chart)              | Categories are bars.                    |
| One number against its range  | [Gauge](/docs/components/gauge)                  | The dial.                               |
| A trend inside a stat         | Sparkline, from [Charts](/docs/components/chart) | No axes; the shape is the point.        |
| Places                        | [Map](/docs/components/map)                      | `omaris/map`, opt-in.                   |
| Code, read-only               | [Code Block](/docs/components/code-block)        | Highlighted, copyable.                  |
| A change between two versions | [Diff Viewer](/docs/components/diff-viewer)      | Unified or split.                       |
| A JSON payload                | [JSON Viewer](/docs/components/json-viewer)      | Collapsible and searchable.             |
| A stream of log lines         | [Log Viewer](/docs/components/log-viewer)        | Levels, ANSI colour, follow.            |
| Any string on the screen      | [Text](/docs/components/text)                    | The variant is the whole type decision. |

> **Note** Every component page opens with "Use it for" and "Not for", and every
> "Not for" line names the component to use instead. When a table above does
> not settle it, that section will.

---

<!-- /docs/building-a-screen -->

A screen is built from the outside in: the frame, then the rhythm of the
content, then the surfaces things sit on, then the states the data can be in,
then the phone. Do it in that order and each step has something to hang on.

## 1. The frame

```demo
app-shell/dashboard-frame
```

`AppShell` gives you the layout most dashboards end up with, and the one thing
that is hard to add later: only the content column scrolls. The sidebar stays
put, the app bar sticks to its own scroller, and there is never a second
scrollbar. `AppShellContent` supplies the page gutter and the vertical rhythm
between its children — sections are direct children of it and own no padding
of their own.

`width` is the reading measure. `full` is the default and right for a wide
table; `xl` or `lg` for a page of cards and prose.

```demo
app-shell/content-width
```

## 2. The rhythm

Spacing is Tailwind's numeric scale, which the theme rescales with the density
setting — so `gap-4` is already right, and `p-[16px]` is a bug. These are the
layouts a dashboard is made of. Use them rather than inventing a grid per page,
and the pages agree with each other for free.

| Layout                     | Classes                                                          |
| -------------------------- | ---------------------------------------------------------------- |
| Stat row                   | `grid gap-4 sm:grid-cols-2 xl:grid-cols-4`                       |
| Chart row, one wide        | `grid gap-4 lg:grid-cols-3` and `lg:col-span-2` on the wide card |
| Two up                     | `grid gap-4 lg:grid-cols-2`                                      |
| Card list                  | `grid gap-4 sm:grid-cols-2 xl:grid-cols-3`                       |
| Inside a card              | `flex flex-col gap-3`                                            |
| Page heading with controls | `flex flex-wrap items-end justify-between gap-4`                 |
| A cluster of buttons       | `flex items-center gap-2`                                        |

Type has a rhythm too, and it is the `Text` variant: `headline-md` for the page
title, `title-lg` for a section, `title-md` for a card, `body-md` for
everything you read, `label-md` for a column header. A metric is
`display-sm` with `tabular`. The variant carries size, weight, leading and
tracking together, so there is nothing to add after it.

```demo
text/scale
```

## 3. The surfaces

Depth is tiers, not borders. The page is `bg-background`; a panel is
`surface-container-low`; a card is `surface-container`; something raised
inside it, or a hover, is `surface-container-high`. Up one tier per level of
nesting, and stop at three. A `Card` does this for you — `outlined` when it
sits on a plain page, `elevated` in a grid of cards, `filled` for a well.

```demo
card/variants
```

A [Divider](/docs/components/divider) is for when the grouping is still not
clear after the surfaces and the spacing. It is not the default way to
separate two things.

## 4. The four states

Every list, every table, every chart has four states, and the design is only
finished when all four are on screen. The empty one is the one people forget,
and it is the first thing a new user sees.

| State   | Show                                                  | Component                                                           |
| ------- | ----------------------------------------------------- | ------------------------------------------------------------------- |
| Loading | The shape of what is coming                           | [Skeleton](/docs/components/skeleton), or `loading` on the Table    |
| Empty   | Why it is empty, and the one action that changes that | [Empty](/docs/components/empty)                                     |
| Error   | What went wrong and how to try again                  | [Alert](/docs/components/alert) `tone="destructive"` with an action |
| Ready   | The data                                              | The component                                                       |

```demo
table/states
```

A skeleton is the same shape as the content it stands in for — a table's
rows, a card's title and two lines — so nothing jumps when the data lands.
Progress bars are for a known amount; a skeleton is for "soon".

## 5. The phone

The same screen, not a second one. Three things carry a dashboard onto a
phone:

- **The drawer becomes modal.** `NavigationDrawer responsive` is a sidebar
  above 900px and a modal below it, from one drawer.
- **The bottom gets a bar.** `AppShellSidebar` hides below `md`, so give phones
  a [Navigation Bar](/docs/components/navigation-bar) in `AppShellFooter` —
  three to five destinations, the ones that matter.
- **Sheets, not dialogs, for tasks.** A [Sheet](/docs/components/sheet) is a
  bottom sheet on a phone with a handle to throw it away by; a Dialog is for a
  decision.

```demo
navigation-bar/basic
```

Every component is built on logical properties (`ms-`, `pe-`, `start-`), so
a right-to-left language mirrors the whole screen without anything in your
code changing. Write your own layout the same way and it stays true.

## Whole screens to copy

Twelve complete apps live at [/patterns](/patterns), each on its own URL and
built only from what this library exports — a dashboard, an inbox, a till, a
board, a shop, sign-in, a wizard, settings, a fleet map, a phone app, a clinic
schedule and an AI assistant. Open the one closest to what you are building
and take the layout. Anything in them is something you can have.

The frame, the rhythm and the states make a screen that works.
[Making it look designed](/docs/look) is what makes it one you would sign.

---

<!-- /docs/forms -->

A form is a column of fields, one primary action, and a way to say what went
wrong. The fields do most of the work: every omaris field takes a `label`, a
`supportingText` and an `invalid`, so a form is one line per field rather
than a nest of wrappers.

```demo
input/states
```

## The field

- **Always a label.** `label="Email"` — above the field, wired to the control,
  so clicking it focuses. A placeholder is not a label; it disappears when
  someone starts typing.
- **Help before, error after.** `supportingText` is the hint under the field.
  When `invalid` is set, the same line becomes the error, in the destructive
  colour, and the control is marked `aria-invalid` for you.
- **`required` on the field, not in the label.** It marks the label and sets
  `required` on the control.
- **Let the field do the shape.** `format="decimal"`, `format="slug"`, a
  [Price Input](/docs/components/price-input) for money, a
  [Phone Input](/docs/components/phone-input) for a phone number. Rejected
  characters never make it in, and the right keyboard comes up on a phone.

## Choosing the control

| You are asking for                 | Use                                                                                          |
| ---------------------------------- | -------------------------------------------------------------------------------------------- |
| A line of text                     | [Text Field](/docs/components/input)                                                         |
| A few lines                        | [Textarea](/docs/components/textarea)                                                        |
| One of a few, all visible          | [Radio](/docs/components/radio)                                                              |
| One of many                        | [Select](/docs/components/select); [Combobox](/docs/components/combobox) if they must search |
| Yes or no, submitted with the form | [Checkbox](/docs/components/checkbox)                                                        |
| On or off, applied immediately     | [Switch](/docs/components/switch) — and then it is a setting, not a form                     |
| A number in a range                | [Slider](/docs/components/slider)                                                            |

The full set is in [Choosing a component](/docs/choosing-a-component).

## The layout

- **One column.** Fields stack, in the order someone would answer them. Two
  columns only for a pair that belongs together — first and last name, city
  and postcode — with `grid gap-4 sm:grid-cols-2`.
- **`gap-4` between fields, `gap-6` between groups.** A group is a heading
  (`Text variant="title-md"`) and the fields under it. Past three groups,
  consider a step per group.
- **The width is the answer's width.** A postcode field does not need to be
  as wide as an address. Set it with `class="w-32"` on the field.

## The actions

- **One primary.** `filled`, at the end, named for what it does: "Create
  invoice", not "Submit". Cancel is `text`, before it.
- **Disable nothing to explain a rule.** A disabled submit button tells the
  person nothing about what is missing. Leave it enabled; validate on submit;
  put the error on the field.
- **Show that it is working.** `loading` on the submit button while the
  request is out. The label stays put and nothing jumps.
- **Destructive means confirm.** Deleting is `tone="destructive"` and goes
  through `await dialog.confirm({ title: 'Delete?', destructive: true })`.

## When to validate

Validate on submit, then on change for any field that already has an error —
so nobody is told they are wrong while they are still typing, and once they
have been told, they see it fixed as they fix it. Put the message on the field
that has the problem; put a [Toast](/docs/components/toast) up only for a
failure that is not any field's fault, such as the network.

## A whole one

```svelte
<script lang="ts">
	import { Button, Input, Select, Checkbox, Text, toast } from 'omaris';

	const PLANS = [
		{ value: 'free', label: 'Free' },
		{ value: 'team', label: 'Team' }
	];

	let email = $state('');
	let plan = $state('');
	let agree = $state(false);
	let errors = $state<Record<string, string>>({});
	let busy = $state(false);

	async function submit(event: SubmitEvent) {
		event.preventDefault();
		errors = {};
		if (!email.includes('@')) errors.email = 'Enter an email address.';
		if (!plan) errors.plan = 'Choose a plan.';
		if (Object.keys(errors).length) return;
		busy = true;
		try {
			await createAccount({ email, plan, agree }); // your API call
			toast.success('Account created');
		} catch {
			toast.error('Could not create the account', {
				action: { label: 'Retry', onclick: () => submit(event) }
			});
		} finally {
			busy = false;
		}
	}
</script>

<form onsubmit={submit} class="flex max-w-md flex-col gap-4">
	<Text as="h2" variant="title-lg">Create an account</Text>
	<Input
		label="Email"
		type="email"
		required
		bind:value={email}
		invalid={!!errors.email}
		supportingText={errors.email ?? 'We only use it to sign you in.'}
	/>
	<Select
		label="Plan"
		required
		bind:value={plan}
		options={PLANS}
		invalid={!!errors.plan}
		supportingText={errors.plan}
	/>
	<Checkbox bind:checked={agree} label="Email me the release notes" />
	<div class="flex items-center justify-end gap-2 pt-2">
		<Button variant="text" href="/">Cancel</Button>
		<Button type="submit" loading={busy}>Create account</Button>
	</div>
</form>
```

The [sign-in block](/blocks) is this, complete; the [ride-hailing
pattern](/patterns/ride) carries the one-time code step that follows it.

---

<!-- /docs/look -->

Everything else on this site makes a screen that works. This page is about
the difference between a screen that works and one a designer would sign —
and it is a short list, because most of that difference is restraint. Each
rule is one decision and the habit that keeps it. The same rules go into the
`AGENTS.md` that `omaris init` writes, so a model building in your project
reads them before its first screen.

## 1. Decide the personality before the first screen

A journal is not a dashboard, and both on the default theme look like the
same template. The product's character is one line in the provider, set
before any page is written, and derived from what the app _is_ rather than
from what the defaults happen to be.

| The app is…                                 | Provider `theme`                                                         | Frame                                                               |
| ------------------------------------------- | ------------------------------------------------------------------------ | ------------------------------------------------------------------- |
| Personal — a journal, notes, reading        | `{ preset: 'coffee', radius: 'md', font: 'serif', density: 'spacious' }` | No sidebar. `AppShellContent width="sm"`, one column, a `TopAppBar` |
| A dashboard, admin, ops                     | `{ preset: 'graphite', radius: 'sm', density: 'compact' }`               | `AppShell` + `NavigationDrawer responsive`, `width="xl"`            |
| Consumer, phone-first                       | `{ preset: 'sunset', radius: 'md', font: 'rounded' }`                    | `NavigationBar` in the footer, sheets not dialogs, `width="md"`     |
| A developer tool                            | `{ preset: 'indigo', radius: 'none' }`                                   | Drawer `collapsed`, `width="full"`, tables and code blocks          |
| Money, health, anything that must feel safe | `{ preset: 'forest', radius: 'sm', density: 'comfortable' }`             | `width="lg"`, fewer cards, more whitespace                          |

Corners stay at `sm` (the default) or `md`. `lg`, `xl` and `full` exist for
a user who picks them in settings, not as a product default — every card,
field and button balloons, and the screen reads as a toy. A softer
personality comes from the font and the hue, not from rounder corners.

Or a hue of your own:

```svelte
<OmarisProvider theme={{ preset: 'custom', hue: 25, chroma: 0.9, tint: 1.4 }}>
```

A `tint` above `1` is the cheapest signature there is. The greys lean toward
the accent, so even an empty surface belongs to this product and no other —
which is what "our own look" means in practice. Pick once, write it at the top
of the root layout, and never override it per page.

## 2. One hero per screen

Every screen has one thing the person came for. It gets the size —
`headline-lg`, or `display-sm` for a number — the top-start position, and
air around it. Everything else is a step down from it.

```demo
text/scale
```

A row of four equal stat cards has no hero. Make one number big and set the
other three under it as `title-md`, or drop the row. The question to ask
before laying anything out is "what is the one thing here?" — and if the
answer is "the four cards", it is the wrong answer.

## 3. Space does the work

Whitespace before a line, a line before a shadow, and never a border and a
shadow on the same box. Between sections `gap-8` or `gap-10`; inside a card
`gap-3`. Depth, where it is needed, is a surface tier — up one per level of
nesting, and stop at three.

```demo
tokens/surface-tiers
```

**Not everything is a card.** A card is for a unit that stands alone — a
stat, a product, a plan. A list of entries is rows, `flex flex-col gap-1`
with `rounded-shape-md px-3 py-2 hover:bg-surface-container-high` on each,
not a card per row. A form is fields on the page, not a card around a card.
And one level of nesting: a card inside a card inside a panel is three
borders around one number.

Align everything to a single left edge and let the right rag. Centre only a
marketing hero or an empty state.

## 4. Type is the design

Big and quiet. One large title, `body-md` for everything that is read, and
above the title an eyebrow — `label-md`, uppercase, `tracking-wide`,
`tone="muted"`. That three-line stack, eyebrow → title → one muted sentence,
is how nearly every good screen opens.

```svelte
<div class="flex flex-col gap-1 pb-8">
	<Text variant="label-md" tone="muted" class="tracking-wide uppercase">This week</Text>
	<Text as="h1" variant="headline-lg">Seven entries</Text>
	<Text tone="muted">Two more than last week. The longest was Tuesday.</Text>
</div>
```

Two greys of text, not five: `text-foreground` and `tone="muted"`. A third
tone means the hierarchy has a hole in it. Numbers are always `tabular`, and
a big number carries its unit small beside it. Prose has a measure —
`max-w-prose` on a paragraph, `width="sm"` on a page that is mostly reading.

## 5. Colour is a role, and it is rare

The canvas is neutral. The accent goes on the primary action, the selected
item, a link, and one detail per screen — a dot, an eyebrow, a ring. If
`bg-primary` appears in more than two places, the screen is loud.

```demo
button/variants
```

- A tinted area is a `-container` pair — `bg-primary-container
text-primary-container-foreground` — never the role at `/10`.
- `success`, `warning`, `destructive` and `info` mean status and nothing
  else. A green card that is not "healthy" is a lie.
- One filled button per screen; the rest step down the ladder.
- No gradients, no glow, no glass. They are what a template does when it has
  no idea. `bg-surface-container-low` behind a section does the same job and
  reads as intentional.

## 6. The details that read as designed

Each of these is one line, and each is the difference between a mock-up and a
product.

```demo
chip/icons-and-tones
```

- An eyebrow above the title.
- The date, large, where a journal or a feed starts the day.
- A tonal `Chip` for a status, not a coloured `Badge` on every row.
- An `AvatarGroup` with its `+3`; a `Sparkline` inside a stat; a `Progress`
  under a quota.
- Hover that tints (`hover:bg-surface-container-high`), not hover that adds a
  border. An interactive `Card` lifts on its own.
- Icons from one set — Lucide matches the built-in glyphs — at `size-4`
  beside text and `size-5` in an `IconButton`. Never an emoji as an icon.
- Rounded avatars, square-cornered thumbnails (`rounded-shape-md`): one rule
  for pictures, kept everywhere.
- The empty state exists on day one, because it is the first screen a new
  user sees.

```demo
empty/basic
```

- Transitions on every state change — `duration-200 ease-standard`, with
  `motion-reduce:transition-none` beside them — and nothing that moves on
  its own.

## 7. Copy

Real names and real numbers; never "Lorem ipsum", never "John Doe", never
"Sample item 1". Sentence case everywhere and no exclamation marks — no
"Welcome to your dashboard!" and no "Manage your things with ease". Headings
are nouns (`Entries`, `This week`); buttons are verbs (`Write`, `Save`,
`Invite`); an empty state is one sentence and one verb ("Nothing written
yet." → "Write the first entry"). A title is the word a person would say —
"Journal", not "Journal Entry Management".

## 8. The AI look

If a screen has any of these, it was assembled rather than designed. Take it
out:

- Four stat cards, then a chart, then a table — on every page, whatever the
  app.
- A centred hero with gradient text and three feature cards with an emoji
  each.
- A `Badge` on every row, a border on every box, a shadow on every card.
- Every card with a header, a description, content _and_ a footer.
- `rounded-2xl` and `shadow-lg` sprinkled on things — both ignore the theme.
- A toast on every button.
- Purple, on a product that has nothing to do with purple.
- Five shades of grey text and three sizes of heading in one card.
- A sidebar on an app with four pages.

## Before you call it done

Open it at 390px and at 1440px, in light and in dark, and answer each of
these with a yes:

1. Can you name the one thing on the screen in three words?
2. Is there exactly one filled button?
3. Is there nothing with both a border and a shadow?
4. Are there at most two greys of text?
5. Does the empty state exist, and does it say what to do?
6. Does every number line up, in Western digits, and every time read 12-hour with AM/PM?
7. Does nothing move unless something happened?
8. Would you show it as your own work?

A "no" on any of them is the next edit, not a note. [Principles](/docs/principles)
is why these rules hold; [Building a screen](/docs/building-a-screen) is the
order to build in.

---

<!-- /docs/feedback -->

Something happened. The person needs to know. There are five ways to tell
them, and the wrong one is either not noticed or in the way. Pick by what
happened, not by what looks nice.

| What happened                                                                 | Show                                                                           | Why                                                               |
| ----------------------------------------------------------------------------- | ------------------------------------------------------------------------------ | ----------------------------------------------------------------- |
| Something succeeded, and there is nothing to do about it                      | [Toast](/docs/components/toast)                                                | Brief, out of the way, gone on its own.                           |
| Something failed, and there is a retry                                        | Toast with an `action`                                                         | The retry is one tap away and the page is still usable.           |
| Something about this page that stays true — a plan is expiring, a sync is off | [Alert](/docs/components/alert)                                                | Part of the page, in a tone. It does not disappear.               |
| Something must be decided before going on                                     | [Dialog](/docs/components/dialog)                                              | It interrupts, on purpose.                                        |
| Something is on its way                                                       | [Progress](/docs/components/progress) or [Skeleton](/docs/components/skeleton) | A bar for a known amount; a skeleton the shape of what is coming. |
| A count, or a state, on a thing — 4 unread, online                            | [Badge](/docs/components/badge)                                                | It rides on the thing.                                            |
| A word about a control, on hover                                              | [Tooltip](/docs/components/tooltip)                                            | Never for anything that must be read.                             |

## Toast: brief, never blocking

```demo
toast/kinds
```

Most actions get no toast. One reports work that finished and left nothing on
screen to see — "Copied", "Invite resent", "12 rows archived". A press whose
result is visible reports itself, and a control that would only announce its
own name needs no feedback at all. Toasts stack, and on a phone a handful of
them are the whole viewport.

Creating something is the case people toast by reflex and should not: add a
product and the product is in the list, so the list already said it. The same
goes for a rename, a delete, a toggle, a filter, an opened panel and a sent
message — the screen changed, which is a better confirmation than a strip of
text over it. What is left, and what a toast is genuinely for:

| Toast                                                         | No toast                                      |
| ------------------------------------------------------------- | --------------------------------------------- |
| Copied to the clipboard — nothing on screen moved             | Added a row to a list you can see             |
| A request that failed, when the form cannot show it           | A field that failed validation                |
| Work that finished off screen — "Export ready", "42 archived" | An item deleted from the list in front of you |
| A background job that outlived the screen that started it     | A dialog that closed, a page that navigated   |

A toast is for a result the person did not need to wait for. It never asks a
question — there is no "Are you sure?" toast — and it never carries the only
copy of something important, because it will be gone in four seconds.

- `toast.success('Saved')` for the common case; `toast.error(…)` for a failure.
- `toast.promise(save(), { loading: 'Saving…', success: 'Saved', error: 'Could not save' })`
  follows a request from start to end, in one toast.
- One `action` at most — "Undo", "Retry", "View". An undo toast is the right
  way to make a delete safe without a dialog.

```demo
toast/following-a-promise
```

## Alert: stays until it is not true

```demo
alert/tones
```

An alert belongs to the page. It is the right answer for a condition rather
than an event: the account is over its limit, the connection is offline, this
record is read-only. It has a tone, an optional action, and it can be
dismissed if the condition can be ignored. A destructive alert announces
itself to a screen reader immediately; the rest wait their turn.

## Dialog: a decision

```demo
dialog/promise-dialogs
```

A dialog stops everything, so it earns that by asking something. The
provider gives you the three shapes as promises, which is how most of them
should be written:

```ts
if (await dialog.confirm({ title: 'Delete this order?', destructive: true })) remove();
const name = await dialog.prompt({ title: 'Rename', value: current });
await dialog.alert({ title: 'Saved', description: 'Your changes are live.' });
```

A dialog for a _task_ — editing, filtering, a long form — is a
[Sheet](/docs/components/sheet): it keeps the page in view and becomes a bottom
sheet on a phone.

## Progress: something is coming

```demo
progress/linear
```

A bar when you know how far along it is; the indeterminate bar when you only
know it is working; a skeleton when what is coming has a shape. A spinner on
a button (`loading`) is the same idea at the scale of one action. Never show
two of these for one thing.

## When to confirm

Confirm when the action is destructive and cannot be undone: deleting,
signing out of every device, sending to a thousand people. Everywhere else,
do the thing and offer an undo in the toast — a confirmation dialog on every
action trains people to click through it, and then it stops protecting the
one that mattered.

- Name the action in the button: "Delete order", not "OK".
- Say what will happen, once, in the description.
- `destructive: true` paints the confirm button red. The safe choice is the
  quiet one.

## The whole thing on one screen

The admin pattern at [/patterns/dashboard](/patterns/dashboard) has all of it:
toasts on save, an alert for a failed sync, a confirm on delete, skeletons
while the table loads, and an empty state when a filter matches nothing.

---

<!-- /docs/footguns -->

<!-- Generated by `bun run reference` from cli/footguns.js. Edit that file. -->

Every one of these compiles, renders, and is wrong. They are the things a
reviewer would catch and a linter cannot, collected so that neither you nor
an agent has to learn them by shipping them. The same list goes into the
`AGENTS.md` that `bunx omaris init` writes.

## `on-*` colour classes do not exist

MD3 muscle memory writes `text-on-primary` or `text-on-surface`. The names here are `text-primary-foreground`, `text-surface-foreground`, `text-primary-container-foreground`.

## Surface tiers always say `container`

`bg-surface-high` is not a class; `bg-surface-container-high` is. Only `surface` and `surface-variant` are tier-less.

## `accent` is a near-grey, not an accent colour

The second accent is `tertiary`. `bg-accent` on a call-to-action looks broken. There is no `accent-container` or `muted-container`.

## Two radius scales

`rounded-lg` (0.625rem) ≠ `rounded-shape-lg` (16px). Components use `rounded-shape-*`; match them. `rounded-3xl` and larger are Tailwind's stock fixed values and ignore the theme's roundness setting.

## Tailwind's stock shadows are wrong here

`shadow-md`, `shadow-lg` compile but ignore the theme's shadow colour and look wrong in dark mode. Only `shadow-0`…`shadow-5` are theme-aware.

## No duration tokens

Write `duration-200`, `duration-300`.

## `TopAppBar` does not stick by default

— pass `sticky`. It elevates on scroll regardless, which reads as a bug if it isn't stuck. `flexible` only does something with `size="medium"` or `"large"`.

## `AppShellContent` defaults to `width="full"`

— a dashboard goes full-bleed on a wide monitor unless you pass `width="lg"` or `"xl"`.

## `AppShellSidebar` hides below `md`

(`breakpoint="md"`). Give phones a `NavigationBar` in the footer or a modal drawer, or there is no navigation.

## `NavigationDrawer` has no border unless you pass `bordered`

That is the whole rule.

## There is no `NavigationRail`

Use a `collapsed` `NavigationDrawer`.

## `Card` defaults to `variant="outlined"`

A grid of flat "cards" is usually this — pass `variant="elevated"`. A `Card` with `href` or `onclick` becomes interactive on its own; never wrap one in your own `<a>`.

## tailwind-merge only resolves within a group

`aspect-video` does not cancel a component's built-in height. Where a component ships one it gives you a prop instead (`Carousel.height`).

## One `Text` variant is the whole type decision

`text-title-md` carries size, line height, tracking and weight. Adding `font-semibold` after it means the wrong variant was picked, not the wrong weight.

## Icons are yours

omaris bundles none; hand any component an `<svg>` and it sizes and colours it. Lucide matches the built-in glyphs.

## Not every action gets a toast

A toast is for work that finished and left nothing on screen to see — "Copied", "Invite resent", "12 rows archived". If the result is visible there is no toast, and a button that would only announce its own name gets no handler at all. The case that gets this wrong most often is the one that feels most deserving: **creating something**. Add a product and the product is in the list — the list is the confirmation, and "Product added" on top of it is a second, worse copy of news the screen already broke. Same for a rename (the name changed), a delete (the row went), a toggle (the switch moved), a filter (the results changed), an opened panel, and a sent message. Progress of the press itself is the `Button`'s `loading`; a field error is the field's `supportingText`; a message that stays until something changes is an `Alert` in the page. Batch bulk work into one toast rather than one per row. Count the toasts a screen can raise: one or two is a designed interface; more than four means placeholders are wearing a toast as a costume, and the fix is to implement the action or drop the handler — never to shorten the message. Toasts stack, and eight of them over a phone are the interface.

## Numbers are Western digits — always, in every language

`ar`, `ckb` and `fa` default to Eastern-Arabic digits under CLDR, so `total.toLocaleString()` renders `١٬٢٣٤` the moment the interface is in Arabic, and `Intl.DateTimeFormat('ar-IQ')` dates read `٤ أيلول`. Nobody wants that in a product: prices, counts, IDs, phone numbers and dates are read and typed in `0-9`. Pin every formatter with `latn()` from `omaris` — `n.toLocaleString(undefined, latn())`, `new Intl.DateTimeFormat(locale, latn({ month: 'short' }))`. Every formatter inside omaris already does; yours has to. Translate the words, never the digits.

---

<!-- /docs/styling -->

Two props cover every override. `class` styles the root. `classes` reaches
every other element by name. Nothing else is needed, and nothing is out of
reach.

## class wins

`class` is merged last, through `cn()`, so your utility always beats the
component's own.

```demo
styling/class-wins
```

That is the whole rule for single-element components — `Button`, `Chip`,
`Badge`, `Switch` and the rest render one element, so `class` is the entire
story there.

## classes reaches the parts

A component that renders more than one element declares each as a named part.
Pass Tailwind for one of them and nothing else moves.

```demo
styling/classes-parts
```

Every page in this reference lists the parts its component has, under **Parts**.
The keys are typed and exported too — `InputClasses`, `TableClasses` — so your
editor lists them.

```svelte
<Table
	classes={{
		headCell: 'uppercase tracking-wide',
		row: 'even:bg-surface-container-low'
	}}
/>
```

`class` is sugar for the root part, and still beats `classes.root`.

## The merge rule that catches people

Classes merge through [tailwind-merge](https://github.com/dcastil/tailwind-merge),
which only resolves conflicts **within a group**. `h-64` replaces a built-in
`h-56`, because both are heights. But `aspect-video` does not cancel a height at
all — different group, so both survive and the height wins.

> **Warning** This is the single most common override bug. If your class seems
> to be ignored, check whether it is actually in the same group as the one you
> are trying to beat.

Where a component ships a value that would be caught by this, it gives you a
prop and a custom property instead of a class, so a class genuinely can replace
it.

```demo
styling/the-merge-trap
```

## Borrowing the variants

Every component exports its `tv()` object — `buttonVariants`, `cardVariants`,
`inputVariants`. Call it to put a component's look on your own element.

```demo
styling/borrowing-variants
```

## What not to do

- **Don't invent a one-off prop.** If a part is hard to reach, it is a missing
  slot, not a missing `fooClass` prop.
- **Don't use raw values.** `bg-primary`, not `bg-[#6750A4]`; `rounded-shape-lg`,
  not `rounded-[16px]`. Raw values do not follow the theme, so they break the
  moment someone changes the hue or turns on high contrast.
- **Don't reach past the API with a descendant selector.** `[&_.some-class]:…`
  binds you to markup that is free to change. Every part has a name; use it.

---

<!-- /docs/theming -->

Every colour in omaris is OKLCH, expressed in terms of three knobs: an accent
**hue**, a **chroma** multiplier and a **tint**. Both themes are derived from
them, so changing one value re-skins the whole app — components, charts and
syntax highlighting together.

## Presets

Ten of them: `indigo`, `ocean`, `teal`, `forest`, `amber`, `sunset`, `rose`,
`violet`, `coffee`, `graphite`. Out of the box you get `ocean` with `sm`
corners — set your product's own in `OmarisProvider`.

```ts
import { theme } from 'omaris';

theme.preset = 'ocean';
```

## Or your own

Setting a hue switches to the `custom` preset automatically.

```ts
theme.hue = 210; // degrees
theme.chroma = 0.7; // 0 is monochrome, 1 as designed, up to 1.6
theme.tint = 1.4; // how far the greys lean toward the accent
```

## Everything the store holds

| Setting       | Values                                                                  |
| ------------- | ----------------------------------------------------------------------- |
| `mode`        | `light` · `dark` · `system`                                             |
| `preset`      | a preset name, or `custom`                                              |
| `hue`         | degrees, when `preset` is `custom`                                      |
| `chroma`      | `0`–`1.6`                                                               |
| `tint`        | `0` is pure grey                                                        |
| `contrast`    | `normal` · `high`                                                       |
| `radius`      | `none` · `sm` · `md` · `lg` · `xl` · `full`                             |
| `density`     | `compact` · `comfortable` · `spacious`                                  |
| `scale`       | `0.8`–`1.25`, whole-UI zoom                                             |
| `fontSize`    | `sm` · `md` · `lg` · `xl`, independent of `scale`                       |
| `font`        | `system` · `sans` · `rounded` · `serif` · `mono`, or any stack          |
| `motion`      | `full` · `reduced` · `none`                                             |
| `translucent` | `false` (default) · `true` — frosted popovers, menus, dropdowns, toasts |

Every one is a property, so `bind:` works:

```svelte
<Slider bind:value={theme.scale} min={0.8} max={1.25} step={0.05} />
```

Or set several at once, and go back:

```ts
theme.set({ preset: 'forest', radius: 'md', density: 'compact' });
theme.reset();
```

## Translucency

Off by default. Turn it on and every floating surface — popover, menu,
select and combobox dropdowns, toasts — becomes frosted glass: a see-through
fill with the page blurred behind it. High contrast switches it back off.

```ts
theme.translucent = true;
```

Your own floating surface opts in with the `translucent:` variant and the
`frosted` utility, which apply only while the setting is on:

```svelte
<div class="border bg-popover shadow-3 translucent:frosted">…</div>
```

## Light and dark

`mode` is what the user asked for; `resolvedMode` is what is actually on screen
once `system` has been worked out.

```ts
theme.toggleMode();
theme.isDark; // boolean
```

The provider resolves this before first paint, so there is no flash of the
wrong theme.

## A ready-made settings screen

`ThemeSettings` is the whole appearance panel, already bound to the store. Drop
it in a dialog and you have a themable app.

```svelte
<Dialog bind:open title="Appearance">
	<ThemeSettings />
</Dialog>
```

## Adding a preset

```svelte
<OmarisProvider
	presets={{
		brand: { label: 'Brand', primary: 268, tertiary: 320, neutral: 280, chroma: 1.1, tint: 1 }
	}}
	theme={{ preset: 'brand' }}
>
	{@render children()}
</OmarisProvider>
```

---

<!-- /docs/tokens -->

Every value a component uses is a token. Tokens follow the theme; raw values do
not, which is why `bg-[#6750A4]` looks fine until someone changes the hue or
turns on high contrast.

## Colour roles

Each accent role comes as a set of four: the role, its foreground, its
container, and the container's foreground. Use the pair — `bg-primary` with
`text-primary-foreground` — and contrast takes care of itself in both themes.

```demo
tokens/colour-roles
```

The seven accent roles are `primary`, `secondary`, `tertiary`, `destructive`,
`success`, `warning` and `info`. Components that take a `tone` prop accept
exactly these.

## Surface tiers

Material's elevation ladder, as backgrounds. A higher tier reads as closer to
the reader without a shadow.

```demo
tokens/surface-tiers
```

## Elevation

```demo
tokens/elevation
```

One utility works in both themes: the shadow reads its colour at the point of
use rather than baking it in.

## Shape

Two scales. `rounded-*` follows the theme's `radius` setting and is what most
components use. `rounded-shape-*` is Material's own fixed ladder — `none`, `xs`,
`sm`, `md`, `lg`, `xl`, `2xl` at 0, 4, 8, 12, 16, 28 and 48px — for the places
the spec is specific.

Both follow the same roundness knob, so turning corners up or down moves
everything together.

## Motion

| Token                        | Use                            |
| ---------------------------- | ------------------------------ |
| `ease-standard`              | Anything that stays on screen. |
| `ease-standard-decelerate`   | Something entering.            |
| `ease-standard-accelerate`   | Something leaving.             |
| `ease-emphasized`            | The one the eye should follow. |
| `ease-emphasized-decelerate` | A large entrance.              |
| `ease-emphasized-accelerate` | A large exit.                  |

Always pair a transition with `motion-reduce:transition-none`. The variant
honours the OS setting _and_ the theme store's `motion`, so a user who turns
motion off in your app's own settings gets what they asked for.

## State layers

Material's interaction tint, as opacities rather than colours: `--state-hover`,
`--state-focus`, `--state-pressed`, `--state-dragged`,
`--state-disabled-content`, `--state-disabled-surface`. High contrast raises
them. If you are building a pressable element of your own, `stateLayer` from
`omaris` is the class string omaris's own controls use.

## Adding a role

A new colour role has to exist in three places or it will be wrong in one of
them: `:root`, `.dark`, and the `@theme inline` block that turns it into a
utility. There is no fourth place, and skipping the dark one is how a token
ends up invisible at night.

---

<!-- /docs/typography -->

Material's type scale, as five roles in three sizes each. The class carries the
size, the line height, the letter spacing **and** the weight — so `text-title-md`
is the whole decision. Adding `font-semibold` after it is a sign you picked the
wrong role.

```demo
typography/scale
```

## Use the component

Reach for [Text](/docs/components/text) rather than a `<p>` with a class on it.
It names the same roles, picks the tag for you, and gives you the things you
would otherwise hand-write every time — tone, clamping, tabular figures:

```svelte
<Text as="h2">Deployments</Text>
<Text tone="muted">Every push to main builds and ships.</Text>
<Text variant="display-sm" tabular>48,210</Text>
```

The utilities below still work, and are what `Text` is built on. Use them
directly when you are styling something that is not a Text — a slot in a
third-party component, or your own element.

## Which role

| Role              | For                                                      |
| ----------------- | -------------------------------------------------------- |
| `text-display-*`  | The one number on a landing screen. Rare in a dashboard. |
| `text-headline-*` | Page and section titles.                                 |
| `text-title-*`    | Card and dialog titles, table captions.                  |
| `text-body-*`     | Prose, cell contents, descriptions.                      |
| `text-label-*`    | Buttons, chips, tabs, column headers, form labels.       |

Tailwind's own `text-sm` … `text-5xl` still work and are rewritten through the
same knobs, so they gain the tracking. Reach for a role when the text has a job;
reach for a size when it does not.

## The knobs

Three custom properties tune the whole scale: `--type-scale`, `--type-leading`
and `--type-tracking`. The theme store's `fontSize` setting moves the first, and
because `@theme inline` keeps the tokens unresolved, every text utility on the
page follows — including Tailwind's own.

## Arabic

Arabic is not Latin at a different size. It has no capitals, so it reads smaller
at the same nominal size; its ascenders and descenders need more room; and
letter-spacing actively damages it because the letters join.

So `:lang(ar)` retunes the three knobs — slightly larger, more leading, zero
tracking — and swaps in an Arabic-first stack. Nothing else changes: the same
`text-title-lg` sets both scripts correctly.

```demo
typography/arabic
```

It keys off language rather than direction, so an Arabic quote inside an
English page is set properly, and an English string inside an RTL layout is not
over-corrected.

## Fonts

Geist and Geist Mono, imported separately so you can skip them:

```css
@import 'omaris/fonts.css';
```

The files ship with the package — no font CDN, and nothing to change for an
app that runs offline. Each face is `font-display: block`, so text is drawn
once, in the right face, rather than in a fallback that swaps a moment later.
The theme's typefaces are declared there too and download only when chosen,
and `theme.font` keeps the current face on screen until the new one has
arrived — switching never flashes a fallback.

Preload the Latin files so the first paint doesn't wait on them either:

```ts title=src/hooks.server.ts
export const handle = ({ event, resolve }) =>
	resolve(event, {
		preload: ({ type, path }) =>
			type === 'js' ||
			type === 'css' ||
			(type === 'font' && /\/(geist|geist-mono)-latin\.[\w-]+\.woff2$/.test(path))
	});
```

Or change the stack entirely — `theme.font` takes `system`, `sans`, `rounded`,
`serif`, `mono`, or any `font-family` value of your own.

## Numbers

Body text uses proportional figures, which read better in a sentence. Anything
tabular should opt in with `tabular-nums` so columns of digits line up.

---

<!-- /docs/icons -->

An icon set is a taste decision and a bundle decision, and both are yours. So
omaris bundles none. Every component sizes and colours whatever `<svg>` you hand
it — `[&_svg]:size-*` at its own density, `currentColor` for its tone — which
means any set works and none is required.

```demo
icons/any-svg
```

## The recommendation

[Lucide](https://lucide.dev): 24×24, stroked, `currentColor`. It is what
omaris's own built-in glyphs are drawn to match, so a mixed page looks
deliberate.

```bash
bun add @lucide/svelte
```

```svelte
<script>
	import { Search, Trash2 } from '@lucide/svelte';
	import { Button, IconButton } from 'omaris';
</script>

<Button><Search />Search</Button>
<IconButton aria-label="Delete"><Trash2 /></IconButton>
```

For a closer match to Material, use `@iconify/svelte` with the
`material-symbols:*` set.

## Where icons go

Most components take an icon as a snippet in a named slot rather than as
children, because the position matters:

```svelte
<Input label="Search">
	{#snippet start()}<Search />{/snippet}
</Input>

<Chip>
	{#snippet start()}<Filter />{/snippet}
	Filtered
</Chip>
```

Each component page lists its snippet props under **Props** — `start`, `end`,
`icon`, `badge` and so on.

## Sizing

Don't set a size on the icon. The component does it, at its own density, and a
size of your own will fight the component at every breakpoint. If you need a
different size, that is usually the component's `size` prop.

> **Warning** An icon that carries meaning on its own needs an accessible name.
> `IconButton` requires `aria-label`; anywhere else, add `sr-only` text.

---

<!-- /docs/charts-and-maps -->

Charts and maps ship in the same package but behind their own entry points,
because `layerchart` and `maplibre-gl` together are tens of megabytes and nobody
importing a `Button` should pay for them.

```ts
import { Button, Card } from 'omaris'; // no heavy dependencies
import { LineChart } from 'omaris/chart'; // needs layerchart + d3-shape
import { Map, Marker } from 'omaris/map'; // needs maplibre-gl
```

All three are optional peer dependencies, so a package manager installs them
only if you ask:

```bash
bun add layerchart d3-shape   # for omaris/chart
bun add maplibre-gl           # for omaris/map
```

`TreemapChart` also reads `d3-hierarchy` and `ComboChart` `d3-scale`; both
arrive with `layerchart`, so add them explicitly only if your package manager
refuses to hoist (pnpm's default).

## Charts

Twelve types and a sparkline:

|                                                   |                                             |
| ------------------------------------------------- | ------------------------------------------- |
| `AreaChart` `LineChart` `BarChart` `ScatterChart` | the cartesian four                          |
| `ComboChart`                                      | bars and lines together, with a second axis |
| `PieChart` `TreemapChart` `FunnelChart`           | part of a whole                             |
| `RadarChart` `RadialBarChart` `Gauge`             | radial                                      |
| `CandlestickChart`                                | open, high, low, close                      |
| `Sparkline`                                       | a trend with no axes, for a table cell      |

They read the theme's chart colours, so they re-skin with everything else, and
`ChartFrame` is the shared shell if you are dropping down to layerchart
directly.

### What every chart takes

Beyond the data, the props that matter across the set:

- `references` — lines and bands at fixed values: a target, a threshold, the
  window something was broken.
- `annotations` — a note pinned to one point, with an optional leader line.
- `brush` — drag across the plot to select a range, and zoom to it.
- `zoom` — wheel or pinch to zoom, drag to pan. Both rescale the axes rather
  than the pixels, so the tick labels stay true.
- `legend="isolate"` — a click shows that series alone, a second brings the
  rest back.
- `csv` — a download in the corner that hands the plotted rows back as a file.
  `toCsv` and `downloadCsv` are exported for doing it yourself.
- `error` — a request that failed is not the same as no data, and shouldn't
  look like it. Pass a string, an `Error`, or `true`; add `onRetry` for a
  button.

```svelte
<LineChart
	data={rows}
	x="date"
	y="latency"
	legend="isolate"
	brush
	csv="latency"
	error={loadError}
	onRetry={reload}
	references={[{ y: 400, label: 'SLO', color: 'var(--warning)' }]}
	annotations={[{ x: shipped, y: 820, label: 'v2 rollout', leader: true }]}
/>
```

See [Charts](/docs/components/chart) for the API.

## Maps and the tile worker

MapLibre parses tiles in a web worker it finds by URL, and the URL is built at
runtime — no bundler can follow it, so a production build used to ship the
library and 404 the worker: an attribution line over an empty box. `Map` now
asks Vite for the worker as an asset of its own and points MapLibre at it, so a
built app draws tiles with no configuration.

In `vite dev`, one line still helps: pre-bundling rewrites MapLibre's imports
in a way its worker chunk doesn't survive, and excluding it keeps the dev
server serving the real module.

```ts title=vite.config.ts
export default defineConfig({
	plugins: [tailwindcss(), sveltekit()],
	optimizeDeps: {
		exclude: ['maplibre-gl']
	}
});
```

The map family is declarative — sources, layers, clustering, routes, heatmaps,
drawing and geofences are components rather than imperative calls. See
[Maps](/docs/components/map).

---

<!-- /docs/accessibility -->

Accessibility is part of "done" here, not a later pass. Every component ships
with a focus-visible outline, the right ARIA state for what it is doing, and
`sr-only` text wherever an icon carries meaning on its own.

## What you get

- **Focus is always visible.** A ring that follows the accent, on every
  interactive element, in both themes.
- **State is announced.** `aria-pressed` on toggles, `aria-expanded` on
  disclosures, `aria-invalid` and `aria-describedby` wired between a field and
  its supporting text, `aria-current` on the selected navigation item.
- **Keyboard support is real.** Menus, tabs, listboxes, comboboxes and sliders
  implement their full keyboard model — arrows, Home/End, type-ahead where the
  pattern calls for it.
- **Focus is trapped where it should be.** Dialogs and modal drawers hold focus
  and give it back to whatever opened them.
- **Motion is optional.** Every transition pairs with `motion-reduce`, which
  honours the OS setting and the theme store's own `motion` setting.
- **High contrast is a supported mode**, not an accident — `contrast: 'high'`
  raises foreground contrast, border strength and the state layers together.

## What it cannot do for you

**Name your icon-only controls.** `IconButton` requires `aria-label` and the
type will tell you so, but the same applies anywhere an icon stands alone.

```svelte
<IconButton aria-label="Delete message"><Trash2 /></IconButton>
```

**Label your fields.** Most inputs take a `label` prop and render a real
`<label>` wired to the control. If you leave it off because the design has no
visible label, supply `aria-label` instead — a placeholder is not a label.

**Order your headings.** Components render the element you ask for; nothing
stops you from putting an `h4` above an `h2`.

## Checking your work

Storybook runs the a11y addon on every story, so the fastest way to check a
composition is to build it as one. `bun run storybook`, then the Accessibility
panel.

---

<!-- /docs/ai -->

Two components talk to models: [AI Chat](/docs/components/ai-chat) and
[AI Image](/docs/components/ai-image). Neither knows which model. Each takes
one function — `send` for the chat, `generate` for the image — and reads
back whatever it returns. Everything else, from the streaming caret to the
picture fading in, is already there.

## The shape of it

The key never leaves the server. The component posts to a route of yours;
the route calls the model. `omaris/ai` makes that route two lines on top of
the [Vercel AI SDK](https://ai-sdk.dev), so switching models is switching
an import:

```ts
// src/routes/api/chat/+server.ts
import { chatRoute } from 'omaris/ai';
import { anthropic } from '@ai-sdk/anthropic';

export const POST = chatRoute({
	model: anthropic('claude-sonnet-5'),
	system: 'You are the help desk for a bakery. Be brief.'
});
```

```ts
// src/routes/api/image/+server.ts
import { imageRoute } from 'omaris/ai';
import { google } from '@ai-sdk/google';

export const POST = imageRoute({ model: google.image('imagen-4.0-generate-001') });
```

```svelte
<script>
	import { AiChat, AiImage, chatEndpoint, endpoint } from 'omaris';
</script>

<AiChat send={chatEndpoint('/api/chat')} />
<AiImage generate={endpoint('/api/image')} />
```

Install `ai` and the provider you picked — `@ai-sdk/anthropic`,
`@ai-sdk/openai`, `@ai-sdk/google` — alongside `omaris`. Nothing in the
components depends on either; they ship in the main entry and weigh what a
card does.

The same `generate` fits the [Drawing Board](/docs/components/drawing-board):
`ai={{ generate }}` adds a sparkle to its strip that turns a sketch, or the
selection, into a picture and puts it back on the board.

## Without the SDK

`gemini()` and `openaiImages()` talk to those two image APIs with `fetch`,
and both take a reference picture to edit — which the SDK's image call does
not. Put one in the route instead:

```ts
import { gemini } from 'omaris';
import { GEMINI_API_KEY } from '$env/static/private';

const generate = gemini({ apiKey: GEMINI_API_KEY });

export async function POST({ request }) {
	const images = await generate(await request.json(), {
		signal: request.signal,
		progress() {},
		partial() {},
		status() {}
	});
	return Response.json(images);
}
```

For the chat, any route that streams will do. The component reads the AI
SDK's UI message stream, an SSE with `delta` or `content` in each event,
plain text as it arrives, or a JSON `{ text }` — by content type, with
nothing to configure.

## Your own function

Both props take a plain function, so a transport that is not HTTP is a few
lines: a WebSocket, a worker, a model in the browser.

```ts
const send: SendFn = async function* (messages, { signal }) {
	for await (const token of localModel.stream(messages, { signal })) yield token;
};

const generate: GenerateFn = async ({ prompt, aspect }, { signal, progress }) => {
	const blob = await diffusion.run(prompt, { aspect, signal, onStep: progress });
	return { src: blob };
};
```

A `send` can return a string, a promise of one, an async iterable of chunks,
a `ReadableStream`, or a `Response`. A `generate` returns one result or a
list, and a result's `src` can be a URL, a data URL or a `Blob`.

## Before the backend exists

`mockChat()` streams markdown a word at a time after a pause, and can fail
on demand. `mockGenerate()` makes an abstract picture from the prompt after a
believable wait, with progress and a partial. Design the screen against the
real states — the dots, the caret, the stop, the error, the spinner —
and swap the mock for the route when it lands. Every demo on both pages runs
on them.

---

<!-- /docs/sound -->

A control can answer in three ways: something moves, something buzzes, something
sounds. omaris has had the first two for a while — `use:ripple` and the
[`haptics`](/docs/provider) store — and sound is the one that was missing.

It is **off by default and stays off** until a person turns it on. Audio is the
only feedback that reaches the room and not just the user, so it is never a
default, never a surprise, and always one switch away from silent.

```demo
sound/soundboard
```

Every cue is synthesized live by [cuelume](https://cuelume.dev) — no audio files
in your bundle, one lazily created `AudioContext`, and nothing at all before the
browser has seen a real interaction.

## Turning it on

```svelte
<!-- +layout.svelte -->
<OmarisProvider sound={{ persist: true }}>
	{@render children()}
</OmarisProvider>
```

That configures the store without switching it on. `sound={true}` starts it on
for everyone; `{ persist: true }` remembers whatever the person chooses between
visits. [`ThemeSettings`](/docs/components/theme-settings) already renders the
switch, next to Haptics, on browsers that can play audio at all.

```ts
import { sound } from 'omaris';

sound.enabled = true; // usually from that switch
sound.volume = 0.4; // 0–1, scaling every cue
sound.supported; // false where there is no Web Audio
```

## Playing one

```ts
sound.play('chime');
sound.play('error', { force: true, volume: 0.8 });
```

`play` returns whether anything was heard, so a caller can fall back to
something visible. Two cues closer together than 60 ms collapse into a smear
rather than reading as two events, so the second is dropped — `force` is for the
ones that matter more than the rhythm.

The named methods say what happened instead of what it sounds like, which is
what components should reach for:

| Method            | Cue       | For                                   |
| ----------------- | --------- | ------------------------------------- |
| `sound.tick()`    | `tick`    | One step of a slider or picker        |
| `sound.select()`  | `droplet` | Something became selected             |
| `sound.press()`   | `press`   | A control went down                   |
| `sound.release()` | `release` | …and came back up                     |
| `sound.toggled()` | `toggle`  | A switch flipped                      |
| `sound.open()`    | `bloom`   | A sheet, dialog or menu opened        |
| `sound.close()`   | `whisper` | …and closed                           |
| `sound.page()`    | `page`    | One of a series went past             |
| `sound.loading()` | `loading` | Work the person asked for has started |
| `sound.ready()`   | `ready`   | The screen it arrived at is usable    |
| `sound.success()` | `success` | It worked                             |
| `sound.error()`   | `error`   | It did not                            |

The other cues — `sparkle`, `pulse`, `scan`, `arrival` — are there for the
moments a product invents for itself. `sound.cues` is the whole list.

## What already sounds

The four controls with a natural detent play their own cue once the store is
on, the same way they already play their own haptic:
[Switch](/docs/components/switch) when it flips,
[Checkbox](/docs/components/checkbox) and [Radio](/docs/components/radio) when
they are picked, and [Slider](/docs/components/slider) once per step — with a
duller knock at either end of the range, so a wall doesn't read as one more
step. Each takes `sound={false}` to stay silent on its own:

```svelte
<Switch label="Notifications" sound={false} />
```

Everything else is up to you, which is what the action below is for.

## The `cue` action

```demo
sound/the-cue-action
```

For a control that has no sound of its own, `use:cue` is to audio what
`use:ripple` is to the ripple and `use:haptic` is to the buzz — silent until the
store is on, so it is safe to sprinkle anywhere.

```svelte
<button use:cue>Send</button>
<button use:cue={{ cue: 'success', on: 'release' }}>Confirm</button>
<a use:cue={{ cue: 'whisper', on: 'hover' }}>Preview</a>
```

`on` picks the moment: `'press'` (the default) fires as the finger lands, which
is what makes a control feel physical; `'release'` waits for the click, which
suits anything that can be dragged away from and cancelled; `'hover'` fires as
the pointer arrives, for a real mouse only and throttled to 150 ms. Keyboard
activation gets the same cue as a tap.

## Restraint

- **One cue per event.** A button that plays on press _and_ release sounds
  broken, not detailed. Pick the half that matters.
- **Nothing repeating.** A cue under a dragging finger or a live-updating number
  is a drone. Slider detents are the exception, and only because they are
  throttled.
- **Silence is the failure mode.** Autoplay policy, a muted tab, no Web Audio at
  all — a cue that never plays must cost nothing. Never let a sound be the only
  signal that something happened; it is always the third channel, never the
  first.
- **Volume lives with the user.** Ship a sensible default (0.6) and a slider,
  not a louder default.

## Where it is silent

Beyond the switch itself, cues do not play when `theme.motion` is `'none'` — a
person who has turned off every animation is not asking for the noisy version —
and, with `sound.configure({ respectReducedMotion: true })`, when the OS asks
for reduced motion. Cross-check `sound.active` for whether a call right now
would actually reach the speakers.

---

<!-- /docs/patterns -->

Single components tell you what a thing does. They do not tell you what a screen
made of them feels like — whether the density is right, whether the app bar and
the table agree about their edges, whether a filter bar reads as part of the
list below it.

So there are **twenty-five complete apps** at **[/patterns](/patterns)**. Not
embedded demos: each one has its own URL and fills the window, because a layout
you are judging cannot share the viewport with a documentation sidebar. Open one
on a phone and it is the same app, laid out for a phone — no second set of
styles.

Most of them are an app you already know rebuilt from this catalogue — a feed, a
swipe deck, a player, a code host, a till. That is deliberate: you already know
what those are supposed to feel like, which makes them a much harder test than a
screen invented to flatter the components on it.

### The ones you already know

| Pattern                            | What it exercises                                   |
| ---------------------------------- | --------------------------------------------------- |
| [Social Feed](/patterns/feed)      | Feed, composer, tabs, pull-to-refresh, menus        |
| [Messenger](/patterns/chat)        | Conversation, composer, emoji, swipe actions        |
| [Dating Swipes](/patterns/swipe)   | A pointer-driven swipe deck, dialogs, range sliders |
| [Music Player](/patterns/music)    | Now playing, queue, slider, island                  |
| [Video Streaming](/patterns/watch) | Video player, poster rows, tabs, episode list       |
| [Photo Library](/patterns/photos)  | Masonry, image viewer, selection, albums            |
| [Notes and Docs](/patterns/notes)  | Tree view, rich text, table of contents             |
| [Stay Booking](/patterns/stays)    | Search, facets, map, carousel, booking              |
| [Food Delivery](/patterns/food)    | Menu, basket, order tracking, sheets                |
| [Banking App](/patterns/bank)      | Cards, transactions, charts, transfer form          |
| [Trading Desk](/patterns/trade)    | Candlesticks, order book, live data, order form     |
| [Code Hosting](/patterns/repo)     | Tree view, diff viewer, code block, activity graph  |
| [Issue Tracker](/patterns/issues)  | List and board, command palette, filters            |

### The rest of the shelf

| Pattern                                  | What it exercises                                         |
| ---------------------------------------- | --------------------------------------------------------- |
| [Admin Console](/patterns/dashboard)     | App shell, table, charts, command palette, sheets         |
| [Support Inbox](/patterns/inbox)         | Resizable panes, page transitions, emoji, composer        |
| [Restaurant Till](/patterns/pos)         | Dense touch targets, receipt, held tickets, right-to-left |
| [Project Board](/patterns/board)         | Drag and drop, chips, checklists, sheets                  |
| [Online Shop](/patterns/storefront)      | Carousel, image viewer, facets, cart, empty states        |
| [Account Settings](/patterns/settings)   | Ten sections, switches, live theme settings, devices      |
| [Delivery Dispatch](/patterns/fleet)     | Map, markers, geofences, live data                        |
| [Ride Hailing](/patterns/ride)           | Map, a trip that runs, bottom sheet, fare, rating         |
| [Fitness Tracker](/patterns/mobile)      | Navigation bar, rings, a route on a real map              |
| [AI Assistant](/patterns/studio)         | Streaming answers, code blocks, tool calls, composer      |
| [Product Analytics](/patterns/analytics) | Funnel, retention grid, a live event stream               |
| [Status Page](/patterns/status)          | Uptime bars, incident timeline, gauges                    |

## The dock

Every pattern carries a small tab against the right edge. Open it and you get
the three switches that make the point:

- **Light and dark**, on the same screen, with no reload.
- **Language** — English, Arabic, Kurdish. Arabic and Kurdish write `dir="rtl"`
  onto `<html>`, and the entire screen mirrors. Nothing in the pattern does
  that; every component in the library is built on logical properties
  (`ms-`, `pe-`, `start-`), so the mirroring is a property of the catalogue.
- **Personalise**, which is `ThemeSettings` — hue, chroma, corner radius,
  density, type scale and motion, applied live to everything on screen.

## They are also the regression surface

If a change makes one of these screens worse, that is the change being wrong
rather than the screen. They are the only place in the repository where a
hundred components are on screen at once, under real data, at real size.

---

<!-- /docs/runes -->

A component library eventually runs out of components. What is left is the
state every dashboard writes for itself and gets subtly wrong: the debounce that
drops the last keystroke, the breakpoint check that flashes the wrong layout on
the first paint, the undo stack that records one step per keystroke, the filter
that lives in a variable instead of the URL and so cannot be shared.

Those are the runes. One import, one line, and they behave.

```svelte
<script>
	import { screen, queryState, debounced, relativeTime } from 'omaris';

	const query = queryState('q', '');
	const search = debounced(() => query.current, 300);
</script>

{#if screen.phone}<NavigationBar />{/if}
```

## What there is

| Rune                                         | For                                                    |
| -------------------------------------------- | ------------------------------------------------------ |
| [`queryState`](/docs/query-state)            | Filters, search terms and page numbers, in the URL     |
| [`screen`](/docs/screen)                     | Phone, tablet or desktop — the layout decision         |
| [`debounced` / `throttled`](/docs/debounced) | A value that lags on purpose                           |
| [`elementSize`](/docs/element-size)          | How wide _this_ is, not the window                     |
| [`inView`](/docs/in-view)                    | On screen, for reveals and lazy loading                |
| [`scroll`](/docs/scroll)                     | Position, direction, progress, and scrolling to things |
| [`clipboard`](/docs/clipboard)               | Copy, and the “Copied!” that follows it                |
| [`undoable`](/docs/undoable)                 | Undo and redo, for any state at all                    |
| [`network`](/docs/network)                   | Online, offline, and whether anything is reachable     |
| [`relativeTime`](/docs/relative-time)        | “3 minutes ago”, in four languages, kept true          |

## What they have in common

**They are safe on the server.** Every one can be created during SSR and
reports a documented value until the browser has measured something — `ready`
is `false` until then, so a layout that cannot survive being wrong for one frame
can wait.

**They clean themselves up.** Created inside a component, a rune stops with that
component. Created anywhere else — module scope, a class, a `.svelte.ts` helper
— it keeps going until you call `destroy()`. There is no third case to remember.

**They share their listeners.** `screen` is one `resize` handler for the whole
app. `elementSize` is one `ResizeObserver` however many elements you measure.
`inView` is one `IntersectionObserver` per distinct set of options.
`relativeTime` is one timer per cadence, so a feed of two hundred timestamps
costs one interval and they all tick in the same frame.

**They read like the state they replace.** `search.current`, `box.width`,
`doc.canUndo`, `screen.phone` — properties, not subscriptions, so they work in
markup, in `$derived`, and in a plain function without ceremony.

> note
> Two of them are shared stores rather than per-call runes — `screen` and
> `network` — for the same reason `theme` and `toast` are. There is only one
> window and one connection, so there should only be one of each watching them.

## Where they go

Import from `omaris`, alongside everything else:

```ts
import { screen, elementSize, undoable } from 'omaris';
```

`queryState` is the one that needs SvelteKit's router — it reads `$app/state`
and writes through `$app/navigation`, so it works in a SvelteKit app and
nowhere else. Everything else is plain Svelte.

---

<!-- /docs/query-state -->

The address bar is the only piece of state a user can bookmark, share, reload
and press Back through. Filters, search terms, the open tab, the page number and
the sort order all belong there — and they usually are not, because wiring one
value to a query parameter takes twenty lines.

It takes one.

```demo
runes/query-state
```

## The shape of it

```svelte
<script>
	import { queryState } from 'omaris';

	const query = queryState('q', '');
	const page = queryState('page', 1);
</script>

<SearchBar bind:value={query.current} />
<Pagination bind:page={page.current} total={120} />
```

`/products` becomes `/products?q=chair&page=2` as you type and click, Back walks
it backwards, and a reload lands on the same screen. `current` is a normal
read/write property, so `bind:` works on it like any other.

## The type comes from the default

A `string` default reads and writes strings, `1` reads integers, `false` reads
booleans, a `Date` reads ISO, an array reads a comma-separated list. Say it
explicitly when the default cannot imply it:

```ts
import { queryState, parsers } from 'omaris';

const sort = queryState('sort', 'newest', { parser: parsers.literal(['newest', 'price']) });
const tags = queryState('tags', [] as string[], { parser: parsers.array() });
const from = queryState('from', new Date(), { parser: parsers.day });
```

With no default at all it is `string | null`, and `null` removes the parameter.

| Parser                 | URL                            | Type      |
| ---------------------- | ------------------------------ | --------- |
| `parsers.string`       | `?q=chair`                     | `string`  |
| `parsers.integer`      | `?page=2`                      | `number`  |
| `parsers.float`        | `?zoom=1.5`                    | `number`  |
| `parsers.boolean`      | `?open=true`                   | `boolean` |
| `parsers.date`         | `?at=2026-09-06T12:00:00.000Z` | `Date`    |
| `parsers.day`          | `?from=2026-09-06`             | `Date`    |
| `parsers.literal([…])` | `?sort=name`                   | the union |
| `parsers.array(item?)` | `?tags=a,b`                    | `T[]`     |
| `parsers.set(item?)`   | `?ids=1,2`                     | `Set<T>`  |
| `parsers.json()`       | `?state=%7B…%7D`               | anything  |

Anything a parser cannot read falls back to the default, so a hand-edited
`?page=banana` renders page 1 rather than throwing mid-render.

## The defaults are the ones you want

It **replaces** the history entry rather than pushing one, so Back leaves the
page instead of undoing a keystroke. It routes **shallowly**, so `load` does not
re-run for a client-side filter. It does **not scroll**. And it **drops a
parameter once it equals its default**, which is what keeps `/products` from
becoming `/products?page=1&sort=newest&view=grid&q=`.

Each of those is an option:

```ts
queryState('tab', 'overview', { history: 'push' }); // Back returns to the last tab
queryState('q', '', { debounce: 300 }); // one entry per pause, not per key
queryState('page', 1, { shallow: false }); // let `load` re-fetch
queryState('view', 'grid', { clearOnDefault: false }); // always in the URL
```

`debounce` delays only the URL. The value you read updates immediately, so the
input never lags behind the typing.

## Several at once

```svelte
<script>
	import { queryParams, parsers } from 'omaris';

	const filters = queryParams(
		{ q: '', page: 1, tags: [] as string[], sort: 'newest' },
		{ q: { debounce: 300 }, sort: { parser: parsers.literal(['newest', 'price']) } }
	);

	const results = $derived(search(filters.values));
</script>

<SearchBar bind:value={filters.q.current} />
<Button onclick={() => filters.reset()}>Clear</Button>
```

Each key is a `queryState`, so `filters.page.current` behaves exactly as it
would alone. What this adds is `values` — every value in one object, which is
what a fetch or a `$derived` actually wants — and a `reset()` that clears the
lot in one history entry.

> warning
> `values`, `set`, `reset` and `isDefault` are the object's own members, so a
> parameter of one of those names is not reachable as `filters.set.current`.
> Give it a different key, or use `queryState` for that one on its own.

> note
> **Writes are batched.** Setting three parameters in the same tick produces one
> navigation and one history entry, so a “clear filters” button does not leave
> three steps behind it.

## Reading it on the server

The URL is the state, so `load` already has it:

```ts
export const load = ({ url }) => ({
	q: url.searchParams.get('q') ?? '',
	page: Number(url.searchParams.get('page') ?? 1)
});
```

Use `shallow: false` when the server is what filters the data — then changing
the URL is meant to fetch.

## On a prerendered page

SvelteKit will not expose `url.searchParams` while prerendering — a prerendered
page is one file serving every query string, so HTML that depended on one would
be wrong for all the others. So during the build every value reads as its
default, and the browser corrects it on hydration. Nothing to configure; it is
worth knowing only because the first paint of a prerendered page shows the
unfiltered view for a moment.

## When not to

`queryState` needs SvelteKit's router: it reads `$app/state` and writes through
`$app/navigation`. In a plain Svelte app it will not work.

Nor should everything go in a URL. A value that is long, secret, or of no
interest to whoever receives the link belongs in component state — an open
dropdown, a hovered row, a half-typed comment.

---

<!-- /docs/screen -->

CSS can change how something looks at a width. It cannot decide _which
component to mount_, and that is the decision a responsive app actually makes: a
phone gets a bottom bar, a tablet gets a rail, a desktop gets a drawer — three
different components, not one component with three sets of classes.

```demo
runes/screen
```

## Three sizes, named after the decision

```svelte
<script>
	import { screen } from 'omaris';
</script>

{#if screen.phone}
	<NavigationBar {items} />
{:else}
	<NavigationDrawer mode={screen.tablet ? 'rail' : 'standard'} {items} />
{/if}
```

| Size      | Width         | Usually                        |
| --------- | ------------- | ------------------------------ |
| `phone`   | under 768px   | one column, bottom bar, sheets |
| `tablet`  | 768–1023px    | two columns, a rail            |
| `desktop` | 1024px and up | sidebar, three or four columns |

Those are Tailwind's `md` and `lg`, so a class and a branch never disagree. Move
them once, at the top of the app:

```svelte
<OmarisProvider screen={{ tablet: 720, desktop: 1200 }}>
```

or `screen.configure({ tablet: 720, desktop: 1200 })` if you have no provider.

They are named after the device rather than the breakpoint on purpose. `md` and
`lg` describe the CSS and say nothing about the design; `phone` says what you
are drawing for.

## Everything else is sugar on those three

```ts
screen.size; // 'phone' | 'tablet' | 'desktop'
screen.atLeast('tablet'); // tablet or desktop
screen.below('desktop'); // phone or tablet
screen.is('tablet'); // exactly
screen.width; // live px
screen.height;
screen.portrait; // taller than wide
screen.touch; // the pointer is a finger
screen.ready; // the browser has measured
```

`pick` is the one that removes the most code — a value per size, falling back to
the next narrower one:

```ts
const columns = $derived(screen.pick({ phone: 1, tablet: 2, desktop: 4 }, 1));
const mode = $derived(screen.pick({ phone: 'modal', tablet: 'rail', desktop: 'standard' }));
```

Leaving a size out means “same as the one below”: `{ phone: 1, desktop: 3 }`
gives a tablet `1`, because a tablet is a wide phone more often than it is a
narrow desktop.

## The first frame

Nothing has been measured on the server, so `screen.size` is `desktop` until the
browser says otherwise, and `screen.ready` is `false` until it does. Change the
assumption if most of your traffic is not on a desktop:

```svelte
<OmarisProvider screen={{ ssr: 'phone' }}>
```

> warning
> Prefer a CSS breakpoint for anything that must be right on the very first
> paint. `screen` is for the decisions CSS cannot make — which component to
> mount, how many items to fetch, whether to open a sheet or a dialog. Using it
> for something a `md:` class could do costs you a frame of the wrong layout.

Wait for it when the wrong answer would be visible:

```svelte
{#if screen.ready}
	{#if screen.phone}<Sheet />{:else}<Dialog />{/if}
{/if}
```

## `touch` is not `phone`

They are different questions. A 27-inch touchscreen is `desktop` and `touch`; a
tablet with a trackpad is `tablet` and not. Use `touch` for hit targets and
hover affordances, and `size` for layout.

## Anything else

`mediaQuery` is the escape hatch for the questions three sizes cannot answer:

```svelte
<script>
	import { mediaQuery } from 'omaris';
	const short = mediaQuery('(max-height: 640px)');
</script>

{#if short.matches}<CompactHeader />{/if}
```

And when the question is about a _container_ rather than the window — a card in
a resizable panel, a widget in a dashboard column — the answer is
[`elementSize`](/docs/element-size), not this.

---

<!-- /docs/debounced -->

Debounce waits for quiet. Throttle refuses to wait. Almost every interface needs
one of them, and almost every codebase writes both again from scratch, usually
without the two things that make them work: a way to _read_ the delayed value,
and a way to know that a change is still on its way.

```demo
runes/debounced
```

## Values

```svelte
<script>
	import { debounced } from 'omaris';

	let query = $state('');
	const search = debounced(() => query, 300);
	const results = $derived(filter(items, search.current));
</script>

<SearchBar bind:value={query} loading={search.pending} />
```

`search.current` is `''` on the first render rather than after 300ms — the
initial value is never delayed, because there is nothing to debounce yet.

`pending` is what makes this feel right: it is `true` from the keystroke until
the value lands, which is exactly the window a spinner belongs in.

|            |                                    |
| ---------- | ---------------------------------- |
| `current`  | the value, late — read this        |
| `source`   | the value right now, with no delay |
| `pending`  | `current` is behind `source`       |
| `flush()`  | catch up immediately               |
| `cancel()` | abandon the pending update         |

`throttled` has the same shape and updates at a fixed rate instead of waiting
for a pause — for values that change continuously and are read continuously, a
scroll position driving a progress bar, a pointer driving a spotlight.

```ts
const y = throttled(() => scroll.y, 100);
```

## Functions

When there is nothing to read and something to _do_, wrap the function instead:

```ts
import { debounce } from 'omaris';

const save = debounce((draft) => api.save(draft), 800);

$effect(() => save(draft)); // called on every keystroke
onNavigate(() => save.flush()); // …but never lose the last one
```

`flush()` is the one that matters. A debounced save that is not flushed before a
navigation or a submit silently loses the last edit, and it is the bug nobody
finds until a user does.

```ts
save.pending; // reactive — for a "saving…" hint
save.cancel(); // drop it
```

`throttle(fn, ms)` is the same, for streams you must keep up with:

```ts
const move = throttle((e) => broadcast(e.x, e.y), 50);
```

## Which one, and how long

|                           | Debounce                | Throttle                                 |
| ------------------------- | ----------------------- | ---------------------------------------- |
| Search as you type        | ✓ 300ms                 |                                          |
| Autosave a draft          | ✓ 800ms, with `maxWait` |                                          |
| Validating a field        | ✓ 400ms                 |                                          |
| Resize handler            | ✓ 150ms                 |                                          |
| Pointer move, live cursor |                         | ✓ 50ms                                   |
| Scroll-driven animation   |                         | ✓ 16ms — or use [`scroll`](/docs/scroll) |
| Rate-limited API          |                         | ✓ the limit                              |

> note
> `maxWait` is the option a save needs. Someone who types continuously would
> otherwise never trigger a debounced save at all. `{ maxWait: 5000 }` means “at
> least once every five seconds, no matter what”.

`leading: true` fires at the _start_ of a burst as well — right for a button
that must respond instantly but should not be spammable.

## Where the delay goes

Both take a getter for the delay too, so it can react:

```ts
const search = debounced(
	() => query,
	() => (network.slow ? 800 : 300)
);
```

---

<!-- /docs/element-size -->

[`screen`](/docs/screen) answers “how wide is the window”. That is the wrong
question for a component in a resizable panel, a drawer, a grid cell or a
dashboard column — a card 640px wide looks the same in a phone's whole viewport
and in one column of a desktop, and it should decide the same thing in both.

```demo
runes/element-size
```

## Attach it, read it

```svelte
<script>
	import { elementSize } from 'omaris';
	const box = elementSize();

	const columns = $derived(box.pick({ xs: 1, md: 2, xl: 3 }, 1));
</script>

<div use:box.ref class="grid gap-4" style="grid-template-columns: repeat({columns}, 1fr)">
	{#if box.up('md')}<Details />{/if}
</div>
```

Three spellings, one state — use whichever fits:

```svelte
<div use:box.ref></div> <!-- action --><div {@attach box.attach}></div> <!-- attachment -->
```

```ts
const stop = box.observe(node); // imperative
const box = elementSize(() => el); // or hand it an element to follow
```

## Container breakpoints

| Name | From   |
| ---- | ------ |
| `xs` | 0      |
| `sm` | 360px  |
| `md` | 640px  |
| `lg` | 900px  |
| `xl` | 1200px |

These are deliberately not the screen's breakpoints. Replace them entirely when
your component thinks in different steps:

```ts
const box = elementSize({ breakpoints: { one: 0, two: 480, three: 900 } });
box.up('two');
```

```ts
box.name; // the widest breakpoint it clears
box.up('md'); // this one or wider
box.down('md'); // narrower
box.between('sm', 'lg');
box.pick({ xs: 1, md: 2 }, 1);
box.width / box.height; // border box, in px
box.contentWidth / contentHeight;
box.aspect; // width ÷ height
box.portrait / box.landscape;
box.ready; // false until the first measurement
```

## Why not a CSS container query

Use one, when the answer is a class. `@container` is cheaper and needs no
JavaScript. Reach for this when the answer is not a class — mounting a different
component, fetching a different number of rows, switching a chart from twelve
labels to three, deciding whether a table shows its filter row.

## What it costs

One `ResizeObserver` for the whole application, however many elements are
measured. It never reads layout outside the observer's own callback, so a
hundred of these cost what one does.

`epsilon` is there for the rare case where a measurement oscillates — a
scrollbar appearing and disappearing at exactly the wrong width:

```ts
elementSize({ epsilon: 2 });
```

---

<!-- /docs/in-view -->

Reveal-on-scroll, lazy loading, “load more” sentinels and scroll-spy are the
same question asked with different margins: is this element on screen yet?

```demo
runes/in-view
```

## Reveal

```svelte
<script>
  import { inView } from 'omaris';
  const card = inView({ amount: 0.3, once: true });
</script>

<article
  use:card.ref
  class="transition-all duration-500 ease-emphasized motion-reduce:transition-none
         {card.visible ? 'translate-y-0 opacity-100' : 'translate-y-4 opacity-0'}"
>
```

`once: true` is the setting you almost always want for a reveal. Without it the
card fades out again when you scroll back past it, which reads as a bug.

## Load more

```svelte
<script>
	const end = inView({ margin: '400px' });
	$effect(() => {
		if (end.visible) loadMore();
	});
</script>

<div use:end.ref class="h-px"></div>
```

The margin is the whole trick: the sentinel counts as visible 400px before it
actually is, so the next page is already loading by the time the reader gets
there.

## Lazy load

```svelte
<img use:inview={{ margin: '300px', once: true, onenter: () => (src = full) }} {src} alt="" />
```

`inview` is the action form, for when the element does not need state — only to
be told.

## What it knows

```ts
card.visible; // in view right now
card.seen; // has been, at least once — survives `once`
card.ratio; // 0…1, how much is showing
card.from; // 'above' | 'below' | 'left' | 'right' — the edge it came in from
card.count; // how many times it has entered
card.entry; // the raw IntersectionObserverEntry
```

`from` is what makes a direction-aware animation possible: something that
entered from below should rise, and something that entered from above should
fall.

## Options

|                                    |                                                              |
| ---------------------------------- | ------------------------------------------------------------ |
| `amount`                           | `'any'` (default), `'all'`, a fraction, or a list of them    |
| `margin`                           | grow or shrink the box that counts — `'400px'`, `'-25% 0px'` |
| `root`                             | measure against an element instead of the viewport           |
| `once`                             | stop watching after the first time                           |
| `onenter` / `onleave` / `onchange` | callbacks, with the raw entry                                |

A negative margin is how scroll-spy works: `'-40% 0px -40% 0px'` marks a section
active only while it is in the middle of the screen.

> note
> One `IntersectionObserver` is shared by every `inView` with the same options,
> so fifty cards revealing on scroll are one observer's worth of work.

---

<!-- /docs/scroll -->

```demo
runes/scroll
```

## The window, by default

```svelte
<script>
  import { scroll } from 'omaris';
  const page = scroll();
</script>

<header
  class="sticky top-0 transition-transform duration-300 ease-emphasized motion-reduce:transition-none
         {page.direction === 'down' && page.past(120) ? '-translate-y-full' : ''}"
>
```

That is the whole hide-on-scroll header. `past(120)` keeps the bar visible near
the top, where hiding it just looks like a flicker.

## Or an element

```svelte
<div use:list.ref class="overflow-y-auto">…</div>
{#if !list.atBottom}<Fade />{/if}
```

or `scroll(() => node)` when you already have one.

## What it knows

```ts
page.x / page.y; // position in px
page.direction; // 'up' | 'down' | 'left' | 'right' | null
page.scrolling; // moving right now; false again shortly after it stops
page.progress; // 0…1 down the scrollable distance
page.maxY; // how much further it can go
page.atTop / page.atBottom / page.atStart / page.atEnd;
page.past(200); // scrolled further than this
```

and it can move things:

```ts
page.to({ y: 0 });
page.toTop();
page.toBottom();
page.toElement(node, { offset: 72 }); // stop short of a sticky header
```

`toElement`'s `offset` is the one people forget — without it the heading you
scrolled to sits underneath the bar.

## Direction has hysteresis

`direction` only flips after 8px of movement the other way, because a trackpad
emits a few pixels of the opposite direction at the end of every gesture and
each of them would otherwise count as a change of mind. Set your own with
`{ threshold: 16 }`.

## Reaching the end

```ts
const list = scroll(() => node, { onbottom: () => loadMore() });
```

Fires once each time the bottom is reached, rather than on every frame at the
bottom. [`inView`](/docs/in-view) with a sentinel is the better tool when you
want to load _before_ the reader arrives.

## What it costs

The position is read once per animation frame however fast the events arrive,
and never written back, so it cannot cause layout thrash. `to()` and friends
fall back to an instant jump when the reader has asked for reduced motion.

---

<!-- /docs/clipboard -->

The flash is the whole reason this is a rune rather than a function. A copy
button with no feedback leaves you pressing it twice, and every codebase ends up
writing its own `setTimeout` to say so.

```demo
runes/clipboard
```

## Copy

```svelte
<script>
	import { clipboard } from 'omaris';
	const clip = clipboard();
</script>

<Button onclick={() => clip.copy(token)}>
	{clip.copied ? 'Copied' : 'Copy token'}
</Button>
```

Or skip the handler — `trigger` is an action that copies on click and sets the
same state:

```svelte
<button use:clip.trigger={token}>{clip.copied ? '✓' : 'Copy'}</button>
<button use:clip.trigger={{ value: token, event: 'dblclick' }}>Copy</button>
```

## More than text

```ts
clip.copy('plain');
clip.copy({ text: '# Title', html: '<h1>Title</h1>' }); // rich where it's understood
clip.copy(await canvas.convertToBlob()); // an image
clip.copy({ 'text/csv': rows, 'text/plain': preview }); // one entry per type
```

A `{ text, html }` pair pastes as formatted text in an editor and as plain text
in a terminal, which is what a “copy this table” button should do.

## Reading back

Reading needs the user's permission and is refused outright by some browsers, so
it is a call rather than a property:

```ts
const pasted = await clip.read(); // string | null
const image = await clip.readBlob('image/png'); // Blob | null
```

## State

```ts
clip.copied; // the flash — true for `timeout` ms, 2000 by default
clip.value; // the text of the last successful copy
clip.text; // what read() last returned
clip.error; // what went wrong, if anything
clip.busy; // a call is in flight
clip.supported; // the async Clipboard API exists
clip.canRead; // reading back is possible at all
clip.reset(); // clear the flash now
```

`clipboard({ timeout: 0 })` keeps `copied` true until you call `reset()` — for a
confirmation that should stay until dismissed.

> note
> On an insecure origin — plain `http://`, some in-app browsers — the async
> Clipboard API does not exist. It falls back to a hidden textarea and
> `execCommand`, so the button still works. Pass `fallback: false` to fail
> loudly instead.

## One-off

No state, no flash, no ceremony:

```ts
import { copy } from 'omaris';
await copy(url);
```

---

<!-- /docs/undoable -->

Undo is the feature that separates a form from an editor, and it is almost never
built, because doing it by hand means a “record this” call at every mutation and
one forgotten call to break the whole thing.

Here there is nothing to call.

```demo
runes/undoable
```

## Hand it a value

```svelte
<script>
	import { undoable } from 'omaris';
	const doc = undoable({ title: '', tags: [] as string[] });
</script>

<Input bind:value={doc.current.title} />
<Button disabled={!doc.canUndo} onclick={() => doc.undo()}>Undo</Button>
<Button disabled={!doc.canRedo} onclick={() => doc.redo()}>Redo</Button>
```

`doc.current` is a deeply reactive `$state`, so you mutate it the way you mutate
anything else — push to an array, set a nested field, replace the whole object —
and every change is recorded on its own.

## Or wrap state you already have

```ts
let value = $state('');
const history = undoable(
	() => value,
	(v) => (value = v)
);
```

Which is how you put undo on something a parent owns, or on a value that is
already bound to half a screen.

## Steps a person would recognise

Changes within `coalesce` ms of each other become one step, so a typed sentence
is one press of ⌘Z rather than forty. That default — 400ms — is the difference
between undo that works and undo that is unusable.

```ts
doc.commit('Rename'); // close the current step, named
doc.batch(() => {
	// one step, whatever it touches
	doc.current.items.push(item);
	doc.current.total += item.price;
}, 'Add item');
doc.silent(() => (doc.current.seen = true)); // not a step at all
doc.label('Reorder'); // name the step being collected
```

`batch` is the one to reach for on a drag, a paste, or anything where a single
gesture changes several things.

## The timeline is readable

Which is how you build the panel rather than just the two buttons:

```svelte
{#each doc.entries as step (step.index)}
	<button onclick={() => doc.jump(step.index)} aria-current={step.current}>
		{step.label}
	</button>
{/each}
```

```ts
doc.index; // where you are
doc.past; // how many undos are available
doc.future; // how many redos
doc.size; // steps in total
doc.dirty; // changed since markSaved()
doc.go(-2); // move by a signed number of steps
doc.clear(); // forget the timeline, keep the value
doc.reset(); // back to the start, timeline emptied
```

`dirty` and `markSaved()` are the pair a “you have unsaved changes” guard needs:

```ts
async function save() {
	await api.save($state.snapshot(doc.current));
	doc.markSaved();
}
```

## Keyboard

```svelte
<div use:doc.shortcuts tabindex="-1">…</div>
```

or `undoable(value, { shortcuts: true })` for the whole window. Both bind ⌘Z and
⌃Z to undo, and ⇧⌘Z and ⌃Y to redo.

Inside a text field it takes over from the browser's own undo by default, which
is right when the field is bound to this state — the two would otherwise fight.
`{ inputs: 'native' }` steps aside instead.

## What it cannot track

A value that cannot be cloned: a DOM node, a class instance with methods, a
function. Keep those out of the state you hand it.

> note
> Steps are snapshots, not diffs. `limit` is 100 by default and the oldest fall
> off the end; lower it for state that is large, raise it for state that is
> small and edited constantly.

---

<!-- /docs/network -->

```demo
runes/network
```

## The banner

```svelte
<script>
	import { network } from 'omaris';
</script>

{#if network.offline}
	<Alert tone="warning">You are offline — changes are saved locally.</Alert>
{/if}
```

## `navigator.onLine` lies

This is the one thing worth knowing about networks in a browser: it reports
whether there is _a_ network, not whether anything is reachable. A captive
portal, a VPN that dropped, a server that is down — all of them are
`online: true`.

So `offline` is trustworthy in one direction only: when it is `true`, you really
are offline. For the other direction, ask:

```ts
if (!(await network.check())) showOfflineBanner();
```

`check()` fetches a small URL and reports whether it arrived. Point it somewhere
meaningful once, at the top of the app:

```svelte
<OmarisProvider network={{ probe: '/api/health', timeout: 5000 }}>
```

`interval` probes on a timer, which is worth it only for something
long-running and unattended — a dashboard on a wall. Everything else is better
served by probing when a request fails.

## Connection quality

From the Network Information API, which Chromium has and Safari and Firefox do
not. `network.supported` says whether the numbers mean anything.

```ts
network.slow; // 2g, or the user has Data Saver on
network.effectiveType; // 'slow-2g' | '2g' | '3g' | '4g'
network.downlink; // Mbps, rounded by the browser for privacy
network.rtt; // ms, rounded
network.saveData; // the user asked for less
network.type; // 'wifi' | 'cellular' | 'ethernet' | …
```

`slow` is the one to branch on — it covers both a bad connection and a user who
has asked for less data, and it is `false` where the API is missing, so it never
degrades an experience on a browser that simply will not say.

```svelte
{#if network.slow}
	<img {src} alt="" />
{:else}
	<VideoPlayer {src} autoplay />
{/if}
```

## Reacting

For the things that are not rendering — a retry queue to drain, a socket to
reconnect:

```ts
$effect(() => network.onChange((online) => online && flushQueue()));
```

```ts
network.since; // when the state last changed
network.reachable; // what the last check() found — true, false, or null
network.checking; // a probe is in flight
network.checkedAt; // when it finished
```

---

<!-- /docs/editor-keys -->

`CodeEditor` is a real `<textarea>`, so everything your operating system does
in a text field it still does here. What follows is what the component adds on
top — first the shortcuts everyone gets, then vim, which is one prop away.

`⌘` is `Ctrl` outside macOS. Where the two differ, both are listed.

## Always on

| Key                         | What it does                                                                             |
| --------------------------- | ---------------------------------------------------------------------------------------- |
| `Tab` / `⇧Tab`              | Indent, or dedent. With a selection, every line it touches moves together.               |
| `Enter`                     | Keeps the indentation you were on, and adds a level after an opening brace.              |
| `(` `[` `{` `'` `"` `` ` `` | Closes itself. With a selection, wraps it instead of replacing it.                       |
| `⌘/`                        | Comment or uncomment the lines the selection touches, in whatever `lang` uses.           |
| `⌥↑` / `⌥↓`                 | Move the line, or the selected lines, up or down.                                        |
| `⌥⇧↑` / `⌥⇧↓`               | Duplicate them above or below.                                                           |
| `⌘F`                        | Find. `Enter` steps forward, `⇧Enter` back, `Esc` closes.                                |
| `⌘H`                        | Find and replace.                                                                        |
| `⌘D`                        | Select the word under the caret, then each next copy of it.                              |
| `⌃Space`                    | Complete — from `completions`, or from the words already in the file.                    |
| `⌘S`                        | `onsave`. Nothing happens without that prop.                                             |
| `⌘Z` / `⌘⇧Z`                | Undo and redo, native, because every edit goes through the browser's own insert command. |

## Vim

```svelte
<CodeEditor bind:value lang="ts" vim />
```

That is the whole integration. The editor opens in normal mode, the status bar
names the mode and echoes the half-typed command, and `⌘`-shortcuts above keep
working in every mode — the `⌃` ones step aside in normal mode, because `⌃d`
and `⌃f` are vim's there.

`u` and `⌃r` undo and redo a whole **command**: `ciwfoo<Esc>` comes back in one
press, not four. `⌘Z` still works alongside it.

### Modes

| Key                     | Mode                                                                                      |
| ----------------------- | ----------------------------------------------------------------------------------------- |
| `i` `I` `a` `A` `o` `O` | Insert, at the caret / first non-blank / after / end of line / a new line below or above. |
| `v` `V`                 | Visual, and visual by line. `o` swaps which end you are moving.                           |
| `R`                     | Replace.                                                                                  |
| `Esc` / `⌃c`            | Back to normal.                                                                           |
| `gv`                    | Reselect what you last had selected.                                                      |

### Moving

`h j k l` · `w W b B e E ge` · `0 ^ $ g_` · `gg G` · `{ }` · `%` ·
`f F t T` and `; ,` · `+ -` · `⌃d ⌃u ⌃f ⌃b` · `n N` · `* #` · a mark, by
backtick or `'a`.

Every one takes a count: `5j`, `3w`, `2f,`.

### Operators

`d` delete · `c` change · `y` yank · `>` `<` indent · `gu` `gU` `g~` case ·
`gc` comment.

An operator takes a motion (`d2w`, `y}`, `c$`), a text object (`ci"`, `da(`,
`>ip`, `gUiw`), or doubles for the whole line (`dd`, `yy`, `cc`, `>>`, `gcc`).
Counts multiply: `2d3w` deletes six words.

Text objects: `iw aw iW aW` · quotes, `i"` and `a'` · brackets, `i( a( i[ a[
i{ a{ i< a<` (and `ib ab iB aB`) · paragraphs, `ip ap`.

### Acting

| Key            | What it does                                                     |
| -------------- | ---------------------------------------------------------------- |
| `x` `X`        | Delete the character under or before the caret.                  |
| `s` `S`        | Change the character, or the whole line.                         |
| `D` `C` `Y`    | To the end of the line: delete, change, yank.                    |
| `p` `P`        | Put after or before. Linewise registers land on their own lines. |
| `r{char}`      | Replace one character.                                           |
| `J` `gJ`       | Join lines, with or without a space.                             |
| `~`            | Toggle case.                                                     |
| `⌃a` `⌃x`      | Add to or subtract from the number at the caret. Takes a count.  |
| `.`            | Do the last change again, typed text included.                   |
| `m{a-z}`       | Set a mark.                                                      |
| `"{a-z}`       | Choose a register — `"ayy` then `"ap`. `"_d` throws it away.     |
| `zz` `zt` `zb` | Put the caret's line in the middle, at the top, at the bottom.   |
| `ZZ` `ZQ`      | `onsave`, and `onquit`.                                          |

### Searching

`/pattern` and `?pattern` search — JavaScript regular expressions, smartcase,
so a lowercase pattern ignores case. `n` and `N` repeat it, `*` and `#` take
the word under the caret, and `:noh` clears the highlight.

### The ex line

| Command                                                    | What it does                                                                                   |
| ---------------------------------------------------------- | ---------------------------------------------------------------------------------------------- |
| `:42`                                                      | Go to line 42.                                                                                 |
| `:s/a/b/`, `:%s/a/b/g`, `:'<,'>s/a/b/gi`                   | Substitute over a line, the file, or the last selection. `&` and `\1` work in the replacement. |
| `:d` `:y`                                                  | Delete or yank the range.                                                                      |
| `:w` `:wq` `:x`                                            | `onsave`.                                                                                      |
| `:q` `:q!`                                                 | `onquit`.                                                                                      |
| `:noh`                                                     | Clear the search highlight.                                                                    |
| `:set nu` `:set rnu` `:set nowrap` `:set ts=4` `:set noet` | Change the editor's own props for this session. `no…` turns one off.                           |

### Its own status bar

`bind:vimMode` gives you the mode if you would rather draw it yourself, and
`status={false}` takes the built-in bar away.

```svelte
<script lang="ts">
	import { CodeEditor, type VimMode } from 'omaris';

	let mode = $state<VimMode>('normal');
</script>

<CodeEditor bind:value bind:vimMode={mode} vim status={false} /><p>{mode}</p>
```

### The engine on its own

The vim implementation is a pure function over `(state, key, document)` — no
DOM, no editor of its own — and it is exported, so it can drive a textarea you
wrote yourself:

```ts
import { createVimState, vimKey, vimKeyName, VIM_DEFAULTS } from 'omaris';

const state = createVimState();

textarea.addEventListener('keydown', (event) => {
	const doc = {
		text: textarea.value,
		start: textarea.selectionStart,
		end: textarea.selectionEnd
	};
	const result = vimKey(state, vimKeyName(event), doc, VIM_DEFAULTS);
	if (!result.handled) return;
	event.preventDefault();
	// result.edit is one contiguous replacement; result.selection is where the caret ends up.
});
```

---

<!-- /docs/relative-time -->

A timestamp rendered once is wrong a minute later. A timestamp rendered by a
timer per row is a page that shimmers. This is one shared timer per cadence, and
four languages written out properly.

```demo
runes/relative-time
```

## Use it

```svelte
<script>
	import { relativeTime } from 'omaris';
	let { post } = $props();

	const posted = relativeTime(() => post.createdAt);
</script>

<time datetime={posted.iso} title={posted.absolute}>{posted.text}</time>
```

It re-renders itself as the clock moves — every second under a minute, every
half minute under an hour, and progressively less often after that.

## Four languages

`en`, `ar`, `tr` and `ckb`, taken from `<html lang>` unless you say otherwise:

```ts
relativeTime(() => date, { locale: 'ckb' });
relativeTime(() => date, { locale: () => user.locale, style: 'short' });
```

|         | long             | short        |
| ------- | ---------------- | ------------ |
| English | 3 minutes ago    | 3m ago       |
| العربية | قبل 3 دقائق      | قبل 3 د      |
| Türkçe  | 3 dakika önce    | 3 dk önce    |
| کوردی   | 3 خولەک لەمەوپێش | 3 خ لەمەوپێش |

They are written out rather than delegated to `Intl.RelativeTimeFormat`, for two
reasons. Sorani Kurdish is not in most ICU builds at all, and a set of four
languages where one is formatted by a different mechanism than the other three
is a set that drifts. Writing them out also means Arabic gets its counting
right — the bare noun for one, the dual for two, the plural for three to ten,
and back to the singular from eleven:

|     |              |
| --- | ------------ |
| 1   | قبل دقيقة    |
| 2   | قبل دقيقتين  |
| 3   | قبل 3 دقائق  |
| 11  | قبل 11 دقيقة |

`dir` is `'rtl'` for Arabic and Kurdish, for your own layout decisions.

Numerals stay Western in every language, for [the same reason every other
formatter in this library pins them](/docs/typography) — a table that switches
digit systems with the language is unreadable to the people who asked for the
language. Pass `digits: 'auto'` for `٣ دقائق`. The clock in `absolute` is
12-hour with AM/PM either way — `digits` frees the numerals, never the clock.

Add a language, or replace one of the four:

```ts
import { registerRelativeLocale } from 'omaris';

registerRelativeLocale('fa', { dir: 'rtl', now: { … }, unit: (…) => …, past: …, future: … });
```

## Old timestamps

Past a certain age a count stops being information — “47 weeks ago” tells you
nothing. `maxAge` switches to a real date:

```ts
relativeTime(() => date, { maxAge: 7 * 24 * 3600_000 }); // relative for a week, then a date
```

## What it exposes

```ts
posted.text; // '3 minutes ago'
posted.value; // 3
posted.unit; // 'minute'
posted.past; // true
posted.isNow; // within the "just now" window
posted.expired; // maxAge has switched it to a date
posted.absolute; // 'September 6, 2026 at 2:03 PM'
posted.iso; // for <time datetime>
posted.dir; // 'rtl' for ar and ckb
```

## One-off

For a tooltip, a log line, a table cell that never updates — the same
formatting, without the timer:

```ts
import { formatRelative } from 'omaris';

formatRelative(comment.at); // '3 minutes ago'
formatRelative(comment.at, { locale: 'ar' }); // 'قبل 3 دقائق'
formatRelative(due, { locale: 'tr', style: 'short' }); // '2 g sonra'
```

> note
> Timestamps of the same age share one timer and therefore tick in the same
> frame. A feed of two hundred of these costs one interval, and updates as one
> rather than as two hundred separate flickers.

---