# @whyhotel/ui-core-components — full reference

> Placemakr product design-system React component library — accessible, token-driven UI components that render against the Placemakr theme in @whyhotel/ui-core-theme.

Generated from component TS types and zod schemas (source: `src/components`). Code is the source of truth; this file is a build artifact — do not edit by hand.

## Accordion

Accordion — a set of stacked sections that each expand or collapse in place to reveal their content. Use it to condense long, scannable content (FAQs, policy details, optional settings) so people see the headings first and open only what they need. It stays in the page flow rather than floating over other content — reach for a Dialog when the content must interrupt the user. Set `allowMultiple` when several sections may be open at once. Triggers are real buttons with `aria-expanded`, and each content region is labelled by its trigger, so it is keyboard- and screen-reader-accessible by default.

### Variants

- **open**: boolean

### Slots

- `root`
- `item`
- `title`
- `content`

### Props

| Prop | Type | Required | Default | Source | Description |
| --- | --- | --- | --- | --- | --- |
| `open` | `boolean` | no | — | variant | — |
| `className` | `string` | no | — | interface | Extra classes merged onto the root container. |
| `items` | `readonly AccordionItem[]` | no | — | interface | Sections to render. |
| `defaultOpen` | `number` | no | — | interface | Index open on mount; `-1` for all closed. |
| `allowMultiple` | `boolean` | no | — | interface | Allow several sections open at once. |

### Usage

```tsx
<Accordion />
```

---

## Alert

Alert — a static, inline status message that stays on the page to explain a condition or outcome (a warning, a confirmation, an error to resolve). Use it for information tied to a region of the page that the user should notice but that does not demand an immediate modal decision; for transient confirmations that fade on their own, use a Toast instead. Pick the `tone` to match intent — `info`, `success`, `warning`, `danger`, or `brand` — and pass `onDismiss` when the alert should be dismissible. The `danger` tone announces assertively to assistive tech; the others announce politely.

### Variants

- **tone**: `info`, `success`, `warning`, `danger`, `brand` (default `info`)

### Props

| Prop | Type | Required | Default | Source | Description |
| --- | --- | --- | --- | --- | --- |
| `tone` | `'info' \| 'success' \| 'warning' \| 'danger' \| 'brand'` | no | `info` | variant | — |
| `className` | `string` | no | — | interface | Extra classes merged onto the root (tailwind-variants resolves conflicts). |
| `icon` | `React.ReactNode` | no | — | interface | Leading icon node the caller supplies. |
| `title` | `React.ReactNode` | no | — | interface | Emphasised first line. |
| `action` | `React.ReactNode` | no | — | interface | Trailing action node — usually a ghost or secondary Button. |
| `onDismiss` | `() => void` | no | — | interface | Renders a dismiss control that calls this handler. |
| `children` | `React.ReactNode` | no | — | interface | Body message. |

### Usage

```tsx
<Alert tone="info">label</Alert>
```

---

## Avatar

Avatar — a small square or circular chip that stands in for a person or entity with a photo or their initials (a guest, a teammate, a property). Use it in lists, headers, and comment rows to make ownership scannable at a glance. Pass `src` for a photo, or set `placeholder` with initials `children` when there is no image; pick a `shape` and `size` to match the surface, and add `status` to show online or offline presence. It is display only — wrap it in a Button or link when it needs to be actionable.

### Variants

- **status**: `online`, `offline`
- **shape**: `circle`, `square`, `rounded` (default `circle`)
- **size**: `xs`, `sm`, `md`, `lg` (default `md`)
- **placeholder**: boolean

### Slots

- `root`
- `figure`

### Props

| Prop | Type | Required | Default | Source | Description |
| --- | --- | --- | --- | --- | --- |
| `status` | `'online' \| 'offline'` | no | — | variant | — |
| `shape` | `'circle' \| 'square' \| 'rounded'` | no | `circle` | variant | — |
| `size` | `'xs' \| 'sm' \| 'md' \| 'lg'` | no | `md` | variant | — |
| `placeholder` | `boolean` | no | — | variant | — |
| `className` | `string` | no | — | interface | Extra classes merged onto the root (tailwind-variants resolves conflicts). |
| `src` | `string` | no | — | interface | Photo source; when set the avatar renders an `<img>`. |
| `alt` | `string` | no | — | interface | Alt text for the photo — describe the person, not "avatar". |
| `children` | `React.ReactNode` | no | — | interface | Stand-in content (usually initials) shown when there is no `src`. |

### Usage

```tsx
<Avatar shape="circle" size="md">label</Avatar>
```

```tsx
<Avatar src="/guests/jordan.jpg" alt="jordan diaz" />
```

```tsx
<Avatar placeholder size="lg">JD</Avatar>
```

### Do

- Give photos meaningful `alt` text so screen readers announce who it is.

### Don't

- Put long text in a placeholder — keep it to one or two initials.

---

## Badge

Badge — a small inline label that tags an element with a short status or count (e.g. "checked in", "3 new"). Use it beside a title, table cell, or list item to surface state at a glance; keep the text to a word or two. Choose a `tone` to signal meaning and a `size` to match the surrounding type, and add `dot` for a leading status dot. It is decorative labelling, not an interactive control — use a Button for actions.

### Variants

- **tone**: `neutral`, `brand`, `info`, `success`, `warning`, `danger` (default `neutral`)
- **size**: `sm`, `md`, `lg` (default `md`)
- **outline**: boolean

### Props

| Prop | Type | Required | Default | Source | Description |
| --- | --- | --- | --- | --- | --- |
| `tone` | `'neutral' \| 'brand' \| 'info' \| 'success' \| 'warning' \| 'danger'` | no | `neutral` | variant | — |
| `size` | `'sm' \| 'md' \| 'lg'` | no | `md` | variant | — |
| `outline` | `boolean` | no | — | variant | — |
| `className` | `string` | no | — | interface | Extra classes merged onto the root (tailwind-variants resolves conflicts). |
| `dot` | `boolean` | no | — | interface | Leading status dot instead of an icon. |
| `icon` | `React.ReactNode` | no | — | interface | Leading icon node the caller supplies (the shared Icon primitive is out of slice scope). |
| `children` | `React.ReactNode` | no | — | interface | Short status label. |

### Usage

```tsx
<Badge tone="neutral" size="md">label</Badge>
```

---

## Breadcrumbs

Breadcrumbs — a compact trail showing where a page sits in the hierarchy and a one-tap way back up it. Feed it `items` from root to current; each crumb with an `href` renders as a link, and the last crumb renders as plain text marked `aria-current="page"` so it reads as the place you are. Use it on deep pages (a reservation inside a stay inside a property) to keep orientation cheap; skip it on top-level screens where there is nowhere to go up. Pick a `size` to match the surrounding type, and pass an `icon` on a crumb for a leading glyph. The root is a labelled `<nav>` so assistive tech announces it as the breadcrumb.

### Variants

- **size**: `xs`, `sm`, `md` (default `sm`)

### Slots

- `root`
- `list`
- `item`

### Props

| Prop | Type | Required | Default | Source | Description |
| --- | --- | --- | --- | --- | --- |
| `size` | `'xs' \| 'sm' \| 'md'` | no | `sm` | variant | — |
| `className` | `string` | no | — | interface | Extra classes merged onto the root (tailwind-variants resolves conflicts). |
| `items` | `readonly BreadcrumbItem[]` | no | — | interface | Crumbs in order, root first; the last one is the current page. |

### Usage

```tsx
<Breadcrumbs size="sm" />
```

```tsx
<Breadcrumbs
  items={[
    {label: 'home', href: '/'},
    {label: 'stays', href: '/stays'},
    {label: 'folio'}
  ]}
/>
```

### Do

- Make the last crumb the current page and leave it without an `href`.

### Don't

- Use Breadcrumbs for primary navigation — reach for a menu or tabs instead.

---

## Button

Button — the primary way a person triggers an action: submit a form, confirm a choice, or move to the next step. Use `variant` to signal importance — `primary` for the main action on a view, `secondary` for supporting actions, `accent` for an alternative emphasis in the brand accent color, `ghost` for low-emphasis or tertiary actions, and `danger` for destructive ones. Size with `sm`/`md`/`lg`, and set `fullWidth` when the button should span its container (common on mobile and in narrow forms). Keep one primary button per view so the main action stays obvious.

### Variants

- **variant**: `primary`, `secondary`, `accent`, `ghost`, `danger` (default `primary`)
- **size**: `sm`, `md`, `lg` (default `md`)
- **fullWidth**: boolean

### Props

| Prop | Type | Required | Default | Source | Description |
| --- | --- | --- | --- | --- | --- |
| `variant` | `'primary' \| 'secondary' \| 'accent' \| 'ghost' \| 'danger'` | no | `primary` | variant | — |
| `size` | `'sm' \| 'md' \| 'lg'` | no | `md` | variant | — |
| `fullWidth` | `boolean` | no | — | variant | — |
| `className` | `string` | no | — | interface | Extra classes merged onto the root (tailwind-variants resolves conflicts). |
| `iconLeft` | `React.ReactNode` | no | — | interface | Node rendered before the label (replaced by a spinner while `loading`). |
| `iconRight` | `React.ReactNode` | no | — | interface | Node rendered after the label. |
| `loading` | `boolean` | no | — | interface | Shows a spinner and disables the button. |
| `children` | `React.ReactNode` | no | — | interface | Label — lowercase, verb-first ("send request"), per the brand voice. |

### Usage

```tsx
<Button variant="primary" size="md">label</Button>
```

```tsx
<Button variant="primary" size="md">continue to keys</Button>
```

### Do

- use lowercase, verb-first labels ("send request"), per the brand voice

### Don't

- hard-code colors — retint via the theme or the `style` override channel

---

## Card

Card — a container that groups related content and actions into a single surface, optionally with a header and footer. Use it to break a page into scannable units — a reservation, a room, a summary — where each unit has its own title, body, and actions. Choose `border` elevation for flat, dense layouts and `shadow` to lift a card off the page; set `interactive` when the whole card is clickable. Adjust `padding` and `tone` to fit the surrounding density and hierarchy.

### Variants

- **elevation**: `border`, `shadow` (default `border`)
- **padding**: `none`, `sm`, `md`, `lg` (default `md`)
- **tone**: `default`, `sunken`, `accent` (default `default`)
- **interactive**: boolean

### Slots

- `base`
- `header`
- `body`
- `footer`

### Props

| Prop | Type | Required | Default | Source | Description |
| --- | --- | --- | --- | --- | --- |
| `elevation` | `'border' \| 'shadow'` | no | `border` | variant | — |
| `padding` | `'none' \| 'sm' \| 'md' \| 'lg'` | no | `md` | variant | — |
| `tone` | `'default' \| 'sunken' \| 'accent'` | no | `default` | variant | — |
| `interactive` | `boolean` | no | — | variant | — |
| `className` | `string` | no | — | interface | Extra classes merged onto the root (tailwind-variants resolves conflicts). |
| `header` | `React.ReactNode` | no | — | interface | Header slot — title, status, actions. |
| `footer` | `React.ReactNode` | no | — | interface | Footer slot — separated by a hairline top border. |
| `children` | `React.ReactNode` | no | — | interface | Body content. |

### Usage

```tsx
<Card elevation="border" padding="md" tone="default">label</Card>
```

---

## Carousel

Carousel — a horizontally (or vertically) scrolling track of equal-status slides that snap into place as a person swipes or scrolls. Reach for it to browse a set where each item stands on its own — room photos, nearby attractions, amenity cards — rather than to walk someone through ordered steps. Pass the slides as `items`; each is wrapped in a `.carousel-item`, so give every node a width utility (e.g. `w-full`, `w-64`) in its own className to set how many show at once. Use `snap` to settle slides at the start, center, or end of the viewport, and `orientation="vertical"` for a scroll-down track. It scrolls with native CSS scroll-snap, so it is touch- and keyboard-scrollable with no JavaScript.

### Variants

- **snap**: `start`, `center`, `end` (default `start`)
- **orientation**: `horizontal`, `vertical` (default `horizontal`)

### Slots

- `root`
- `item`

### Props

| Prop | Type | Required | Default | Source | Description |
| --- | --- | --- | --- | --- | --- |
| `snap` | `'start' \| 'center' \| 'end'` | no | `start` | variant | — |
| `orientation` | `'horizontal' \| 'vertical'` | no | `horizontal` | variant | — |
| `className` | `string` | no | — | interface | Extra classes merged onto the root track (tailwind-variants resolves conflicts). |
| `items` | `readonly React.ReactNode[]` | no | — | interface | Slides to render — each is wrapped in a `.carousel-item`. |

### Usage

```tsx
<Carousel snap="start" orientation="horizontal" />
```

```tsx
<Carousel
  snap="center"
  items={[
    <img key="1" className="w-full rounded-box" src={pool} alt="rooftop pool" />,
    <img key="2" className="w-full rounded-box" src={lobby} alt="lobby lounge" />
  ]}
/>
```

### Do

- give each slide a width utility (`w-full`, `w-64`) so items size predictably.

### Don't

- use a Carousel for sequential steps or a primary navigation path — that is
a Steps or Tabs job; a Carousel is for browsing peers.

---

## Chat

Chat — a single message in a conversation: an optional avatar, a header line, the message bubble, and a footer line. Use it to build message threads (guest messaging, support chat, front-desk handoffs) one entry at a time. Set `side` to place the message — `start` for the other person on the left, `end` for the current user on the right — and add a `tone` to tint the bubble when a message needs emphasis (a confirmation in `success`, an alert in `error`). Pass `header` for the sender and time, `footer` for a receipt, and `avatar` for the speaker's image; keep the bubble content to the message itself.

### Variants

- **side**: `start`, `end` (default `start`)
- **tone**: `primary`, `secondary`, `accent`, `neutral`, `info`, `success`, `warning`, `error`

### Slots

- `root`
- `image`
- `header`
- `bubble`
- `footer`

### Props

| Prop | Type | Required | Default | Source | Description |
| --- | --- | --- | --- | --- | --- |
| `side` | `'start' \| 'end'` | no | `start` | variant | — |
| `tone` | `'primary' \| 'secondary' \| 'accent' \| 'neutral' \| 'info' \| 'success' \| 'warning' \| 'error'` | no | — | variant | — |
| `className` | `string` | no | — | interface | Extra classes merged onto the root container. |
| `avatar` | `React.ReactNode` | no | — | interface | Avatar or image node shown beside the bubble. |
| `header` | `React.ReactNode` | no | — | interface | Line above the bubble — usually the sender's name and a timestamp. |
| `footer` | `React.ReactNode` | no | — | interface | Line below the bubble — usually a delivery or read receipt. |
| `children` | `React.ReactNode` | no | — | interface | The message content inside the bubble. |

### Usage

```tsx
<Chat side="start">label</Chat>
```

```tsx
<Chat side="start" avatar={<Avatar />} header="front desk" footer="seen">
  your room is ready
</Chat>
```

```tsx
<Chat side="end" tone="primary">
  thanks, on my way up
</Chat>
```

### Do

- Use `side="end"` for the current user's own messages so the thread reads
left-to-right like a familiar chat.

### Don't

- Reach for `tone` on every bubble — reserve the color roles for messages
that carry status; a plain bubble is the default for ordinary chat.

---

## Checkbox

Checkbox — a single on/off control for an independent boolean choice, such as opting into an email or accepting a policy. Use it when each option stands alone; for one-of-many choices use radio controls, and for a compact on/off setting consider a switch. Supports an `indeterminate` (mixed) state for a "select all" row whose children are partly selected, and a required-true mode for must-check confirmations. Pair it with a `label`, and a `description` when the choice needs a line of explanation.

### Variants

- **size**: `sm`, `md`, `lg` (default `md`)
- **invalid**: boolean
- **disabled**: boolean

### Slots

- `root`
- `control`
- `label`
- `labelText`
- `description`

### Props

| Prop | Type | Required | Default | Source | Description |
| --- | --- | --- | --- | --- | --- |
| `size` | `'sm' \| 'md' \| 'lg'` | no | `md` | variant | Control size. Defaults to md. |
| `invalid` | `boolean` | no | — | variant | Marks the control invalid and applies the error style. |
| `disabled` | `boolean` | no | — | variant | Disables the control. |
| `checked` | `boolean` | no | — | schema | Controlled checked state. |
| `indeterminate` | `boolean` | no | — | schema | Mixed state for "select all" rows. |
| `required` | `boolean` | no | — | schema | Requires the box to be checked (required-true). |
| `className` | `string` | no | — | interface | Extra classes merged onto the root label. |
| `style` | `React.CSSProperties` | no | — | interface | Inline style — the CSS-variable override channel. |
| `label` | `React.ReactNode` | no | — | interface | Label beside the box. |
| `description` | `React.ReactNode` | no | — | interface | Secondary line under the label. |
| `onChange` | `(checked: boolean) => void` | no | — | interface | Reports the new checked state. |

### Usage

```tsx
<Checkbox size="md" />
```

---

## Countdown

Countdown — an animated number whose digits slide when the value changes, for live counters like the seconds left on a hold, minutes until check-in, or a rooms-remaining tally. Pass a `value` from 0 to 99 and update it over time (usually on an interval) to animate; the digits inherit their scale from the surrounding font size, so wrap it in a text-size utility for a larger display. It is a display element, not a timer — drive the value yourself and keep an accessible label nearby so the count reads clearly to assistive tech.

### Props

| Prop | Type | Required | Default | Source | Description |
| --- | --- | --- | --- | --- | --- |
| `className` | `string` | no | — | interface | Extra classes merged onto the root (tailwind-variants resolves conflicts). |
| `value` | `number` | yes | — | interface | The number to display, 0–99. Changing it slides the digits to the new value. |

### Usage

```tsx
<Countdown />
```

```tsx
<Countdown value={59} />
```

```tsx
<span className="font-mono text-2xl"><Countdown value={minutes} /></span>
```

### Do

- drive `value` from your own state or interval so the digits animate as it changes.

### Don't

- pass values outside 0–99 — DaisyUI clamps the display and the animation breaks.

---

## DataTable

DataTable — a typed, configuration-driven table for presenting rows of structured data (reservations, folios, arrivals) in aligned columns. Define columns once — header, alignment, width, and an optional custom cell renderer — and pass row data; the table handles layout, horizontal scrolling, and the empty state. Use `density="compact"` for dense operational views, and provide `onRowClick` when a row should open its detail. Reach for it whenever data is naturally tabular; for a handful of key/value pairs a simple list is lighter.

### Variants

- **density**: `default`, `compact` (default `default`)
- **interactive**: boolean

### Slots

- `wrapper`
- `table`
- `row`

### Props

| Prop | Type | Required | Default | Source | Description |
| --- | --- | --- | --- | --- | --- |
| `density` | `'default' \| 'compact'` | no | `default` | variant | Row height. Compact tightens vertical padding. |
| `interactive` | `boolean` | no | — | variant | — |
| `className` | `string` | no | — | interface | Extra classes merged onto the table (tailwind-variants resolves conflicts). |
| `style` | `React.CSSProperties` | no | — | interface | Inline style — the CSS-variable override channel. |
| `columns` | `readonly DataTableColumn<Row>[]` | no | — | interface | Column definitions. |
| `rows` | `readonly Row[]` | no | — | interface | Row data. |
| `onRowClick` | `(row: Row) => void` | no | — | interface | Makes rows clickable and applies the hover affordance. |
| `empty` | `React.ReactNode` | no | — | interface | Rendered instead of the table when there are no rows. |
| `rowKey` | `(row: Row, index: number) => React.Key` | no | — | interface | Stable row key extractor. Falls back to the row index. |

### Usage

```tsx
<DataTable density="default" />
```

---

## Dialog

Dialog — a modal panel that overlays the page to focus the user on a single task or decision (confirm a checkout, complete a short form) and blocks the rest of the UI until it is resolved. Use it when the interaction must interrupt the current flow; for non-blocking status, prefer an inline Alert or a Toast. It traps focus inside the panel, restores focus to the trigger on close, and dismisses on escape or a backdrop click, so keyboard and screen-reader users are handled correctly. Keep dialogs short — a title, one line of context, and a clear primary action.

### Slots

- `overlay`
- `box`

### Props

| Prop | Type | Required | Default | Source | Description |
| --- | --- | --- | --- | --- | --- |
| `open` | `boolean` | no | — | interface | Controlled open state. When false, nothing is mounted. |
| `className` | `string` | no | — | interface | Extra classes merged onto the panel (tailwind-variants resolves conflicts). |
| `title` | `React.ReactNode` | no | — | interface | Panel heading. |
| `description` | `React.ReactNode` | no | — | interface | One line of context or consequence, under the title. |
| `footer` | `React.ReactNode` | no | — | interface | Action row — primary Button last. |
| `onClose` | `() => void` | no | — | interface | Called on escape, backdrop click, or the close control. |
| `width` | `number` | no | — | interface | Max panel width in px (480 default; 640 suits forms). |
| `children` | `React.ReactNode` | no | — | interface | Panel body. |

### Usage

```tsx
<Dialog>label</Dialog>
```

---

## Diff

Diff — a side-by-side comparison slider that stacks two panes and reveals one over the other as a person drags the handle between them. Use it to hold two versions of the same frame in place — a room before and after a refresh, a photo with and without an edit, two copy treatments — so the difference reads at a glance instead of side by side. Pass any node to `item1` and `item2`: images, text blocks, or whole layouts, as long as both fill the same box. The figure is focusable and the handle is keyboard-resizable, so the comparison works without a mouse. It is a display surface, not a control — reach for a Toggle or Tabs when you need to switch state.

### Slots

- `root`
- `item1`
- `item2`
- `resizer`

### Props

| Prop | Type | Required | Default | Source | Description |
| --- | --- | --- | --- | --- | --- |
| `className` | `string` | no | — | interface | Extra classes merged onto the root figure (tailwind-variants resolves conflicts). |
| `item1` | `React.ReactNode` | yes | — | interface | The first pane — the layer clipped by the slider (typically the "before"). |
| `item2` | `React.ReactNode` | yes | — | interface | The second pane — the layer revealed as the slider moves (typically the "after"). |

### Usage

```tsx
<Diff />
```

```tsx
<Diff
  item1={<img src="/room-before.jpg" alt="before refresh" />}
  item2={<img src="/room-after.jpg" alt="after refresh" />}
/>
```

### Do

- give both panes the same dimensions so the two layers line up as the slider moves.

### Don't

- use it to switch app state — it compares content, it doesn't toggle settings.

---

## Divider

Divider — a thin rule that separates two blocks of content, optionally with a short label sitting in the gap. Use the default horizontal rule between stacked sections (a folio total above a payment form, "or" between sign-in options), or set `orientation="vertical"` to split two side-by-side items in a flex row. Add a `tone` to tint the rule when the separation carries meaning, and use `placement` to push the label to the start or end. Keep labels lowercase and short; it is a separator, not a heading.

### Variants

- **orientation**: `horizontal`, `vertical` (default `horizontal`)
- **placement**: `start`, `end`
- **tone**: `brand`, `secondary`, `accent`, `neutral`, `info`, `success`, `warning`, `danger`

### Props

| Prop | Type | Required | Default | Source | Description |
| --- | --- | --- | --- | --- | --- |
| `orientation` | `'horizontal' \| 'vertical'` | no | `horizontal` | variant | — |
| `placement` | `'start' \| 'end'` | no | — | variant | — |
| `tone` | `'brand' \| 'secondary' \| 'accent' \| 'neutral' \| 'info' \| 'success' \| 'warning' \| 'danger'` | no | — | variant | — |
| `className` | `string` | no | — | interface | Extra classes merged onto the root (tailwind-variants resolves conflicts). |
| `children` | `React.ReactNode` | no | — | interface | Optional label shown in the gap — keep it to a word or two ("or", "today"). |

### Usage

```tsx
<Divider orientation="horizontal">label</Divider>
```

```tsx
<Divider>or</Divider>
```

```tsx
<div className="flex">
  <span>details</span>
  <Divider orientation="vertical" />
  <span>payment</span>
</div>
```

### Do

- <Divider placement="start">today</Divider>

### Don't

- <Divider><h2>Payment</h2></Divider>  // a divider label is not a heading

---

## Dock

Dock — a fixed bar of destinations pinned to the bottom of the viewport, the primary way to move between the top-level areas of a mobile-first app (stays, calendar, keys, account). Feed it an `items` array of a label and optional icon, mark the current area with `active`, and handle taps with `onSelect`. Keep it to three to five destinations so each stays a comfortable tap target, and match `size` to the surrounding density. Each destination is a real `<button>` and the active one carries `aria-current`, so it is keyboard- and screen-reader-navigable by default.

### Variants

- **size**: `xs`, `sm`, `md`, `lg`, `xl` (default `md`)
- **active**: boolean

### Slots

- `root`
- `item`
- `label`

### Props

| Prop | Type | Required | Default | Source | Description |
| --- | --- | --- | --- | --- | --- |
| `size` | `'xs' \| 'sm' \| 'md' \| 'lg' \| 'xl'` | no | `md` | variant | — |
| `active` | `boolean` | no | — | variant | Index of the current destination — gets `dock-active` and `aria-current`. |
| `className` | `string` | no | — | interface | Extra classes merged onto the root bar (tailwind-variants resolves conflicts). |
| `items` | `readonly DockItem[]` | no | — | interface | Destinations to render, left to right. |
| `onSelect` | `(index: number) => void` | no | — | interface | Called with the index when a destination is pressed. |

### Usage

```tsx
<Dock size="md" />
```

```tsx
<Dock
  active={tab}
  onSelect={setTab}
  items={[
    {label: 'stays', icon: <HomeIcon />},
    {label: 'calendar', icon: <CalendarIcon />},
    {label: 'keys', icon: <KeyIcon />}
  ]}
/>
```

### Do

- Keep to three to five destinations and give every one an icon and a short label.

### Don't

- Reach for a Dock as a secondary toolbar — it owns the bottom of the viewport, so use Tabs for in-page section switching.

---

## Drawer

Drawer — a panel that slides in from the edge of the screen over the current view, dimming the main content behind an overlay. Use it for secondary navigation, filters, or a folio summary that should appear on demand without a full page change — reach for a Dialog when the task must be completed before anything else. It is uncontrolled by default: set `defaultOpen` and listen with `onOpenChange`, or pass `open` to drive it yourself. Clicking the overlay closes the panel, and the overlay carries a `close sidebar` label so it stays reachable by assistive tech. Set `placement="end"` to slide it from the trailing edge.

### Variants

- **placement**: `start`, `end` (default `start`)

### Slots

- `root`
- `toggle`
- `content`
- `side`
- `overlay`

### Props

| Prop | Type | Required | Default | Source | Description |
| --- | --- | --- | --- | --- | --- |
| `placement` | `'start' \| 'end'` | no | `start` | variant | Which edge the panel slides from — `end` maps to `drawer-end`. |
| `className` | `string` | no | — | interface | Extra classes merged onto the root container. |
| `side` | `React.ReactNode` | yes | — | interface | Panel content — rendered inside the sliding side region. |
| `children` | `React.ReactNode` | yes | — | interface | Main content — stays visible beneath the overlay. |
| `open` | `boolean` | no | — | interface | Controlled open state. Omit to let Drawer own it. |
| `defaultOpen` | `boolean` | no | — | interface | Open state on mount when uncontrolled. |
| `onOpenChange` | `(open: boolean) => void` | no | — | interface | Called with the next open state whenever it changes. |

### Usage

```tsx
<Drawer placement="start">label</Drawer>
```

---

## Dropdown

Dropdown — a button that reveals a small floating panel of actions or links beneath (or beside) it. Use it to tuck away secondary actions — a row's overflow menu, an account switcher, a "more" list — so the surface stays calm until someone asks for the options. It is built on the native `<details>`/`<summary>` disclosure, so it opens on click or Enter/Space, closes on Escape or an outside click, and needs no extra ARIA. Set `placement` to anchor the panel (bottom by default), `hover` to open it on pointer hover, and pass `open` only when you need to drive visibility from your own state. Fill the panel with a `menu` list of links or Buttons — keep it short and scannable.

### Variants

- **placement**: `bottom`, `top`, `left`, `right`, `end` (default `bottom`)
- **hover**: boolean
- **open**: boolean

### Slots

- `root`
- `trigger`
- `content`

### Props

| Prop | Type | Required | Default | Source | Description |
| --- | --- | --- | --- | --- | --- |
| `placement` | `'bottom' \| 'top' \| 'left' \| 'right' \| 'end'` | no | `bottom` | variant | — |
| `hover` | `boolean` | no | — | variant | — |
| `open` | `boolean` | no | — | variant | — |
| `className` | `string` | no | — | interface | Extra classes merged onto the root `<details>`. |
| `label` | `React.ReactNode` | yes | — | interface | Trigger content rendered inside the `<summary>` button. |
| `children` | `React.ReactNode` | yes | — | interface | Panel content — usually a menu or list of `<li>` items. |

### Usage

```tsx
<Dropdown placement="bottom">label</Dropdown>
```

```tsx
<Dropdown label="reservation actions">
  <li><a>edit dates</a></li>
  <li><a>cancel booking</a></li>
</Dropdown>
```

### Do

- keep the panel to a short, scannable list of related actions

### Don't

- reach for a Dropdown when the choice belongs inline — use a Select for form values

---

## Fab

Fab — a floating action button that pins the single most important action to the bottom-right of a view, then fans out into a speed-dial of related actions on focus or hover. Reach for it on task-focused screens (a reservation, a folio, a housekeeping board) where one action dominates — compose, add, check in — and a few supporting ones should stay one tap away without crowding the layout. Pass `icon` for the trigger glyph and `triggerLabel` for its accessible name; feed `actions` to reveal labelled buttons, and set `mainAction` when a primary affordance should slide into the trigger's place as the dial opens. The reveal is CSS-driven via `:focus-within`, so it is keyboard-reachable by default. Keep one Fab per view so the main action stays unmistakable.

### Slots

- `root`
- `trigger`
- `action`

### Props

| Prop | Type | Required | Default | Source | Description |
| --- | --- | --- | --- | --- | --- |
| `className` | `string` | no | — | interface | Extra classes merged onto the root container. |
| `icon` | `React.ReactNode` | yes | — | interface | Content of the main trigger — usually a single icon. |
| `triggerLabel` | `string` | no | — | interface | Accessible name for the icon-only trigger (e.g. "quick actions"). |
| `actions` | `readonly FabAction[]` | no | — | interface | Actions revealed on focus/hover, stacked above the trigger. |
| `mainAction` | `React.ReactNode` | no | — | interface | A primary action shown in the trigger's place while the Fab is open. |

### Usage

```tsx
<Fab />
```

```tsx
<Fab
  icon={<PlusIcon />}
  triggerLabel="quick actions"
  actions={[
    {label: 'message guest', icon: <ChatIcon />, onClick: openChat},
    {label: 'extend stay', icon: <CalendarIcon />, onClick: extendStay}
  ]}
/>
```

### Do

- give the trigger an accessible name via `triggerLabel` when `icon` is a glyph

### Don't

- stack more than five or six actions — a speed-dial is for a short shortlist

---

## Fieldset

Fieldset — a labelled wrapper that groups related fields into one section of a form, such as guest details or payment. Give it a `legend` for the section heading and an optional `label` caption to explain what the group is for, then pass the fields as children; it lays them out in a tidy vertical stack. Reach for it whenever a form has more than a handful of inputs and benefits from being read in chunks — it is structure, not a control, so it holds inputs but never carries a value of its own. Keep the legend to a short noun phrase and the caption to a single helpful line.

### Slots

- `root`
- `legend`
- `label`

### Props

| Prop | Type | Required | Default | Source | Description |
| --- | --- | --- | --- | --- | --- |
| `className` | `string` | no | — | interface | Extra classes merged onto the root fieldset (tailwind-variants resolves conflicts). |
| `legend` | `React.ReactNode` | no | — | interface | Heading for the group, rendered as the `<legend>`. |
| `label` | `React.ReactNode` | no | — | interface | Muted caption line under the legend that describes the group. |
| `children` | `React.ReactNode` | no | — | interface | The fields this fieldset groups. |

### Usage

```tsx
<Fieldset>label</Fieldset>
```

```tsx
<Fieldset legend="guest details" label="how we reach you about your stay">
  <Input label="full name" />
  <Input label="email" type="email" />
</Fieldset>
```

### Do

- Group fields that belong together and give each Fieldset a clear legend.

### Don't

- Nest a Fieldset inside another just to indent fields — use spacing instead.

---

## FileInput

FileInput — a field for picking one or more files from the device, such as a folio PDF, an ID scan, or a room photo. It reports the raw `FileList` through `onChange`, so the caller owns reading, previewing, and uploading. Set `accept` to constrain the file types and `multiple` to allow more than one, and mark `invalid` to show the error state when validation fails. Size with `sm`/`md`/`lg` to match the surrounding form, or use `ghost` for a borderless field on a tinted panel. Pair it with a form field for the label, help text, and error message.

### Variants

- **size**: `sm`, `md`, `lg` (default `md`)
- **invalid**: boolean
- **ghost**: boolean

### Props

| Prop | Type | Required | Default | Source | Description |
| --- | --- | --- | --- | --- | --- |
| `size` | `'sm' \| 'md' \| 'lg'` | no | `md` | variant | Control height. Defaults to md. |
| `invalid` | `boolean` | no | — | variant | Marks the field invalid and applies the error style. |
| `ghost` | `boolean` | no | — | variant | Strips the border and background for a seamless, borderless field. |
| `className` | `string` | no | — | interface | Extra classes merged onto the field. |
| `style` | `React.CSSProperties` | no | — | interface | Inline style — the CSS-variable override channel. |
| `onChange` | `(files: FileList \| null) => void` | no | — | interface | Reports the picked files, or `null` when the selection is cleared. |

### Usage

```tsx
<FileInput size="md" />
```

```tsx
<FileInput accept="application/pdf" onChange={files => setFolio(files?.[0])} />
```

### Do

- <FileInput accept="image/*" multiple onChange={handleUpload} />

### Don't

- <FileInput onChange={e => read(e.target.files)} /> // onChange gives the FileList, not an event

---

## Filter

Filter — a compact row of buttons for narrowing a list to one facet at a time: a room type, a rate plan, a reservation status. It renders as a radio group, so only one option is ever active, and a reset control appears once a choice is made to clear back to "all". Use it above a results list where the choices are few and worth showing at a glance; reach for a Select when the options are many or space is tight. Leave it uncontrolled to let it track its own selection, or pass `value` and `onChange` to drive it from state. Every option is a real labelled radio, so it is keyboard- and screen-reader-friendly.

### Variants

- **size**: `sm`, `md`, `lg` (default `md`)

### Slots

- `root`
- `reset`
- `option`

### Props

| Prop | Type | Required | Default | Source | Description |
| --- | --- | --- | --- | --- | --- |
| `size` | `'sm' \| 'md' \| 'lg'` | no | `md` | variant | — |
| `className` | `string` | no | — | interface | Extra classes merged onto the root `.filter`. |
| `style` | `React.CSSProperties` | no | — | interface | Inline style — the CSS-variable override channel. |
| `options` | `readonly FilterOption[]` | yes | — | interface | Choices to render, one radio button each. |
| `value` | `string` | no | — | interface | Active value when controlled — Filter no longer keeps its own state. |
| `defaultValue` | `string` | no | — | interface | Active value on mount when uncontrolled. |
| `name` | `string` | no | — | interface | Shared radio-group name; defaults to a generated id. |
| `onChange` | `(value: string \| null) => void` | no | — | interface | Reports the picked value, or `null` when reset clears the selection. |

### Usage

```tsx
<Filter size="md" />
```

```tsx
<Filter options={[{value: 'suite', label: 'suite'}, {value: 'studio', label: 'studio'}]} defaultValue="suite" />
```

### Do

- keep labels short and lowercase ("sold out", "available"), per the brand voice

### Don't

- use it for multi-select — reach for a checkbox group when several facets stack

---

## Footer

Footer — the page's closing landmark, holding link columns, contact details, or a copyright line at the bottom of a view. Supply the columns as children (each a `<nav>` with a `footer-title` heading and `link link-hover` links); the Footer owns the grid so the columns align and space evenly. Use `orientation="horizontal"` to lay the columns in a row on wide surfaces, and `center` for a single-column, centered footer such as a copyright strip. It is a `<footer>` landmark, not a navigation bar — reach for it at the end of the page, not the top.

### Variants

- **orientation**: `vertical`, `horizontal` (default `vertical`)
- **center**: boolean

### Props

| Prop | Type | Required | Default | Source | Description |
| --- | --- | --- | --- | --- | --- |
| `orientation` | `'vertical' \| 'horizontal'` | no | `vertical` | variant | — |
| `center` | `boolean` | no | — | variant | — |
| `className` | `string` | no | — | interface | Extra classes merged onto the root (tailwind-variants resolves conflicts). |
| `children` | `React.ReactNode` | no | — | interface | The footer columns — usually `<nav>` groups of a title and links. |

### Usage

```tsx
<Footer orientation="vertical">label</Footer>
```

---

## Header

Header — a section or page heading rendered in the theme's display type roles. Use `variant` to set the visual level: `display` for a hero or page title, `headline` for a major section, `title` for a card or subsection (the default), and `subtitle` for a secondary line paired with a title. The variant also picks a sensible heading element (h1–h4); override it with `as` (h1–h6) to keep the document outline correct when the visual size and the semantic level differ.

### Variants

- **variant**: `display`, `headline`, `title`, `subtitle` (default `title`)

### Props

| Prop | Type | Required | Default | Source | Description |
| --- | --- | --- | --- | --- | --- |
| `variant` | `'display' \| 'headline' \| 'title' \| 'subtitle'` | no | `title` | variant | — |
| `className` | `string` | no | — | interface | Extra classes merged onto the root (tailwind-variants resolves conflicts). |
| `as` | `HeadingLevel` | no | — | interface | Heading element to render (`h1`–`h6`). Defaults to the variant's semantic level; set it explicitly to keep the document outline correct when the visual size and the heading level differ. |
| `children` | `React.ReactNode` | no | — | interface | Heading text. |

### Usage

```tsx
<Header variant="title">label</Header>
```

```tsx
<Header variant="title">Front desk overview</Header>
```

---

## Hero

Hero — a full-width banner that opens a page with a headline, a line of copy, and a call to action, centered over a background. Use it once at the top of a landing or confirmation view to set the scene (a property photo behind a "your stay is booked" message); reach for a Card for anything smaller or repeated. Set `overlay` when a background image sits behind the content so the text stays legible, and set the image itself via `className` or `style` on the root. Keep the content to one idea — a heading, a sentence, one primary action.

### Slots

- `root`
- `overlay`
- `content`

### Props

| Prop | Type | Required | Default | Source | Description |
| --- | --- | --- | --- | --- | --- |
| `className` | `string` | no | — | interface | Extra classes merged onto the root — set the background image here. |
| `style` | `React.CSSProperties` | no | — | interface | Inline style — the background-image and CSS-variable override channel. |
| `overlay` | `boolean` | no | — | interface | Render a dimming overlay behind the content — for background images. |
| `children` | `React.ReactNode` | no | — | interface | The centered banner content (headline, copy, actions). |

### Usage

```tsx
<Hero>label</Hero>
```

```tsx
<Hero
  overlay
  className="min-h-96"
  style={{backgroundImage: 'url(/lobby.jpg)'}}
>
  <div className="max-w-md text-center text-neutral-content">
    <h1 className="text-5xl font-bold">welcome home</h1>
    <p className="py-6">your keys are ready at the front desk.</p>
    <Button>check in</Button>
  </div>
</Hero>
```

### Do

- pair `overlay` with a background image so the copy keeps its contrast.

### Don't

- stack multiple Heroes on one view — one scene-setter per page.

---

## Indicator

Indicator — a wrapper that pins a small badge or dot to a corner of whatever it wraps, so a count or status floats over an avatar, button, or card without shifting the layout. Use it to surface an unread count, a "new" flag, or a live status next to the thing it describes; pass the pinned node as `indicator` (usually a Badge) and the anchored content as `children`. Place it with the `vAlign` (top/middle/bottom) and `hAlign` (start/center/end) axes — top-end by default, the conventional notification corner. It only positions; the meaning lives in the node you pin, so keep that label short.

### Variants

- **vAlign**: `top`, `middle`, `bottom` (default `top`)
- **hAlign**: `start`, `center`, `end` (default `end`)

### Slots

- `root`
- `item`

### Props

| Prop | Type | Required | Default | Source | Description |
| --- | --- | --- | --- | --- | --- |
| `vAlign` | `'top' \| 'middle' \| 'bottom'` | no | `top` | variant | — |
| `hAlign` | `'start' \| 'center' \| 'end'` | no | `end` | variant | — |
| `className` | `string` | no | — | interface | Extra classes merged onto the root container. |
| `indicator` | `React.ReactNode` | no | — | interface | The node pinned to a corner — usually a Badge with a count or status dot. |
| `children` | `React.ReactNode` | no | — | interface | The content the indicator is anchored to. |

### Usage

```tsx
<Indicator vAlign="top" hAlign="end">label</Indicator>
```

```tsx
<Indicator indicator={<Badge tone="danger">9+</Badge>}>
  <Button variant="secondary">inbox</Button>
</Indicator>
```

### Do

- Pin one short indicator — a count, a dot, or a word like "new".

### Don't

- Anchor a full sentence or an interactive control in the indicator slot; it
floats over content and should stay a glanceable label.

---

## Input

Input — a single-line text field bound to `value`/`onChange` for capturing short free-form entries such as a name, email, or phone number. Choose the `type` (email, password, number, tel, …) to get the right keyboard and native validation, and set `invalid` to show the error state when validation fails. Size with `sm`/`md`/`lg` to match the surrounding form. Pair it with a form field for the label, help text, and error message; use a Select instead when the value must come from a fixed set of options.

### Variants

- **size**: `sm`, `md`, `lg` (default `md`)
- **invalid**: boolean

### Props

| Prop | Type | Required | Default | Source | Description |
| --- | --- | --- | --- | --- | --- |
| `size` | `'sm' \| 'md' \| 'lg'` | no | `md` | variant | Control height. Defaults to md. |
| `invalid` | `boolean` | no | — | variant | Marks the field invalid and applies the error style. |
| `type` | `'text' \| 'email' \| 'password' \| 'number' \| 'tel' \| 'url' \| 'search' \| 'date'` | no | — | schema | Native input type, narrowed to the supported set. |
| `className` | `string` | no | — | interface | Extra classes merged onto the field wrapper. |
| `style` | `React.CSSProperties` | no | — | interface | Inline style — the CSS-variable override channel. |
| `icon` | `React.ReactNode` | no | — | interface | Leading icon node the caller supplies. |
| `suffix` | `React.ReactNode` | no | — | interface | Static trailing text, e.g. a unit or "of 8". |

### Usage

```tsx
<Input size="md" />
```

---

## Join

Join — groups a set of controls into a single segmented unit, squaring the inner corners and collapsing the shared borders so a button cluster or an input + button reads as one control (think a search field with a "go" button, or a paginator). Set `orientation` to `vertical` to stack the segments into a column instead of the default row. Join only groups and sets direction: every child supplies its own `join-item` class, either on the raw element or through a library component's `className` passthrough. Reach for it when adjacent controls act as one; use plain spacing when they are independent.

### Variants

- **orientation**: `horizontal`, `vertical` (default `horizontal`)

### Props

| Prop | Type | Required | Default | Source | Description |
| --- | --- | --- | --- | --- | --- |
| `orientation` | `'horizontal' \| 'vertical'` | no | `horizontal` | variant | — |
| `className` | `string` | no | — | interface | Extra classes merged onto the root (tailwind-variants resolves conflicts). |
| `children` | `React.ReactNode` | no | — | interface | The grouped items — each must carry its own `join-item` class. |

### Usage

```tsx
<Join orientation="horizontal">label</Join>
```

```tsx
<Join>
<button class="btn join-item">prev</button>
<button class="btn join-item">next</button>
</Join>
```

### Do

- give every child a `join-item` class so its corners and borders collapse in

### Don't

- use Join to space unrelated controls — it is for items that act as one

---

## Kbd

Kbd — an inline key cap that shows a single keyboard input inside body copy (e.g. "press ⌘ K to search"). Use it in help text, tooltips, and command hints to name a key or a step in a shortcut; chain several with a "+" between them for a combination. Pick a `size` to match the surrounding type — xs and sm sit inside dense captions, md (the default) rides normal text, lg suits a standalone hint. It is a label, not a control — use a Button for something a person can click.

### Variants

- **size**: `xs`, `sm`, `md`, `lg` (default `md`)

### Props

| Prop | Type | Required | Default | Source | Description |
| --- | --- | --- | --- | --- | --- |
| `size` | `'xs' \| 'sm' \| 'md' \| 'lg'` | no | `md` | variant | — |
| `className` | `string` | no | — | interface | Extra classes merged onto the root (tailwind-variants resolves conflicts). |
| `children` | `React.ReactNode` | no | — | interface | The key label — a glyph, letter, or short word (e.g. "⌘", "Ctrl", "K"). |

### Usage

```tsx
<Kbd size="md">label</Kbd>
```

```tsx
<Kbd>K</Kbd>
```

```tsx
<span>press <Kbd>⌘</Kbd> + <Kbd>K</Kbd> to open search</span>
```

### Do

- use one Kbd per key and a plain "+" between them to spell out a combination.

### Don't

- pack a whole shortcut into one Kbd ("Ctrl+Shift+P") — cap one key each.

---

## Label

Label — a short inline text accent rendered in the theme's small type roles. Use `label` (the default) for form-field and control labels, `caption` for secondary helper text beside a value, and `eyebrow` for the uppercase kicker that sits above a heading. It renders a `<span>`, so it stays inline; for a form control's actual `<label>` element, pass it as that field's label.

### Variants

- **variant**: `label`, `caption`, `eyebrow` (default `label`)

### Props

| Prop | Type | Required | Default | Source | Description |
| --- | --- | --- | --- | --- | --- |
| `variant` | `'label' \| 'caption' \| 'eyebrow'` | no | `label` | variant | — |
| `className` | `string` | no | — | interface | Extra classes merged onto the root (tailwind-variants resolves conflicts). |
| `children` | `React.ReactNode` | no | — | interface | Label text. |

### Usage

```tsx
<Label variant="label">label</Label>
```

```tsx
<Label variant="eyebrow">Reservation</Label>
```

---

## Link

Link — an inline text anchor for navigating somewhere else, whether that's another view, an external page, or an anchor further down the page. Reach for it inside running copy where a Button would feel heavy — "read the house rules", "manage your reservation". By default it inherits the theme's Cabana color that darkens toward Midnight on hover; set a `tone` to match a feedback context (say `danger` for a cancel-and-lose-your-hold path), and set `hover` to hold the underline until someone hovers, keeping dense copy calm. It's for navigation, not actions — use a Button to submit, save, or trigger something.

### Variants

- **tone**: `brand`, `secondary`, `accent`, `neutral`, `success`, `info`, `warning`, `danger`
- **hover**: boolean

### Props

| Prop | Type | Required | Default | Source | Description |
| --- | --- | --- | --- | --- | --- |
| `tone` | `'brand' \| 'secondary' \| 'accent' \| 'neutral' \| 'success' \| 'info' \| 'warning' \| 'danger'` | no | — | variant | — |
| `hover` | `boolean` | no | — | variant | — |
| `className` | `string` | no | — | interface | Extra classes merged onto the root (tailwind-variants resolves conflicts). |
| `href` | `string` | no | — | interface | Destination the link points to — the anchor's `href`. |
| `children` | `React.ReactNode` | no | — | interface | The link text (or nodes) a person clicks. |

### Usage

```tsx
<Link>label</Link>
```

```tsx
<Link href="/reservations">manage your reservation</Link>
```

```tsx
<Link href="/help" tone="accent" hover>
  read the house rules
</Link>
```

### Do

- Write the link text to describe its destination, so it makes sense on its own.

### Don't

- Use a Link to trigger an action like submit or delete — reach for a Button.

---

## List

List — a vertical stack of rows that each pair optional media with a title, an optional subtitle, and optional trailing actions. Reach for it to lay out scannable records — reservations, room assignments, folio line items, teammates — where every row shares the same shape. Feed it a `items` array and it renders a divided `<ul>`; the title column grows to fill the width while media and actions hug their content. It is display, not navigation — wrap a row's title or an action in a link or Button when a row should be interactive.

### Slots

- `root`
- `row`
- `media`
- `content`
- `title`
- `subtitle`
- `actions`

### Props

| Prop | Type | Required | Default | Source | Description |
| --- | --- | --- | --- | --- | --- |
| `className` | `string` | no | — | interface | Extra classes merged onto the root `<ul>` (tailwind-variants resolves conflicts). |
| `items` | `readonly ListItem[]` | no | — | interface | Rows to render, in order. |

### Usage

```tsx
<List />
```

```tsx
<List
  items={[
    {media: <Avatar />, title: 'ada lovelace', subtitle: 'room 214'},
    {media: <Avatar />, title: 'alan turing', subtitle: 'room 215'}
  ]}
/>
```

### Do

- give every row the same cells so the columns line up down the list.

### Don't

- use List for a menu of links — reach for a nav list or Menu instead.

---

## Loading

Loading — an inline, self-animating indicator that signals a short, indefinite wait (fetching a folio, confirming a reservation). Drop it wherever content is pending; pick a `variant` for the shape, a `size` to match the surrounding type, and an optional `tone` to color it — otherwise it inherits the current text color. It carries `role="status"` and an `aria-label` so screen readers announce the wait; keep that label short and specific. For a wait tied to a button press, prefer the Button `loading` prop; reach for Loading when the spinner stands on its own.

### Variants

- **variant**: `spinner`, `dots`, `ring`, `ball`, `bars`, `infinity` (default `spinner`)
- **size**: `xs`, `sm`, `md`, `lg` (default `md`)
- **tone**: `neutral`, `brand`, `info`, `success`, `warning`, `danger`

### Props

| Prop | Type | Required | Default | Source | Description |
| --- | --- | --- | --- | --- | --- |
| `variant` | `'spinner' \| 'dots' \| 'ring' \| 'ball' \| 'bars' \| 'infinity'` | no | `spinner` | variant | — |
| `size` | `'xs' \| 'sm' \| 'md' \| 'lg'` | no | `md` | variant | — |
| `tone` | `'neutral' \| 'brand' \| 'info' \| 'success' \| 'warning' \| 'danger'` | no | — | variant | — |
| `className` | `string` | no | — | interface | Extra classes merged onto the root (tailwind-variants resolves conflicts). |

### Usage

```tsx
<Loading variant="spinner" size="md" />
```

```tsx
<Loading />
```

```tsx
<Loading variant="dots" size="lg" tone="brand" aria-label="checking availability" />
```

### Do

- use a specific aria-label so the wait is announced meaningfully.

### Don't

- leave a Loading mounted after the content arrives — unmount it so the
status stops being announced.

---

## Mask

Mask — clips its content to a decorative shape (squircle, circle, hexagon, star, heart, and more). Wrap a photo, avatar, or colored block to soften a grid of thumbnails or dress up a single hero image; the `shape` prop picks the silhouette and the caller sizes the mask through `className` (the clip scales to fit). Reach for `squircle` or `circle` for avatars and headshots, and the playful shapes sparingly for accents. It is pure decoration — never rely on the shape alone to convey meaning.

### Variants

- **shape**: `squircle`, `heart`, `hexagon`, `hexagon2`, `decagon`, `pentagon`, `diamond`, `circle`, `star`, `star2`, `triangle`, `triangle2`, `triangle3`, `triangle4`, `half1`, `half2` (default `squircle`)

### Props

| Prop | Type | Required | Default | Source | Description |
| --- | --- | --- | --- | --- | --- |
| `shape` | `'squircle' \| 'heart' \| 'hexagon' \| 'hexagon2' \| 'decagon' \| 'pentagon' \| 'diamond' \| 'circle' \| 'star' \| 'star2' \| 'triangle' \| 'triangle2' \| 'triangle3' \| 'triangle4' \| 'half1' \| 'half2'` | no | `squircle` | variant | — |
| `className` | `string` | no | — | interface | Extra classes merged onto the root — size the mask here (e.g. `size-16`). |
| `children` | `React.ReactNode` | no | — | interface | The content to clip: an `<img>`, an avatar, or a colored block. |

### Usage

```tsx
<Mask shape="squircle">label</Mask>
```

```tsx
<Mask shape="squircle" className="size-16">
  <img src="/guest.jpg" alt="guest avatar" />
</Mask>
```

### Do

- wrap an `<img>` or a sized block and let `className` set the dimensions.

### Don't

- use a mask to hint at status or state — pair it with a label instead.

---

## Menu

Menu — a vertical (or horizontal) list of navigation rows: links, section titles, and parents that reveal a nested submenu. Feed it an `items` tree and it renders the DaisyUI markup for you, marking the current row with `active`, dimming unavailable rows with `disabled`, and grouping rows under a `title` heading. Use it for sidebars, account navs, and folio sections; pick an `orientation` and `size` to fit the surface. Submenus are native `<details>` disclosures, so they expand and collapse by keyboard and pointer without extra wiring. Keep labels short and verb- or noun-first (check in, room keys, folio).

### Variants

- **orientation**: `vertical`, `horizontal` (default `vertical`)
- **size**: `xs`, `sm`, `md`, `lg` (default `md`)

### Slots

- `root`
- `title`

### Props

| Prop | Type | Required | Default | Source | Description |
| --- | --- | --- | --- | --- | --- |
| `orientation` | `'vertical' \| 'horizontal'` | no | `vertical` | variant | — |
| `size` | `'xs' \| 'sm' \| 'md' \| 'lg'` | no | `md` | variant | — |
| `className` | `string` | no | — | interface | Extra classes merged onto the root list (tailwind-variants resolves conflicts). |
| `items` | `readonly MenuItem[]` | no | — | interface | The rows to render, nested via each row's own `items`. |

### Usage

```tsx
<Menu orientation="vertical" size="md" />
```

```tsx
<Menu
  items={[
    {title: true, label: 'stay'},
    {label: 'reservation', href: '#', active: true},
    {
      label: 'folio',
      items: [
        {label: 'charges', href: '#'},
        {label: 'payments', href: '#'}
      ]
    },
    {label: 'archived', href: '#', disabled: true}
  ]}
/>
```

### Do

- keep one row `active` so people always know where they are.

### Don't

- use Menu for a set of actions — reach for Button or Dropdown instead.

---

## MockupBrowser

MockupBrowser — a decorative browser frame that wraps a screenshot or live preview in familiar window chrome, complete with a toolbar and address field. Use it in docs, marketing, and onboarding to show what a page looks like in a real browser without a real browser. Pass a `url` to label the address bar (e.g. a booking or check-in link) and put the page itself in `children`. It is a frame, not a viewport — it renders whatever you give it and adds no behavior.

### Slots

- `root`
- `toolbar`
- `address`

### Props

| Prop | Type | Required | Default | Source | Description |
| --- | --- | --- | --- | --- | --- |
| `className` | `string` | no | — | interface | Extra classes merged onto the root frame (tailwind-variants resolves conflicts). |
| `url` | `string` | no | — | interface | Address shown in the toolbar field. Omit to render a chrome-only frame. |
| `children` | `React.ReactNode` | no | — | interface | The page content displayed inside the frame. |

### Usage

```tsx
<MockupBrowser>label</MockupBrowser>
```

```tsx
<MockupBrowser url="https://placemakr.com">
  <div className="flex justify-center p-8">welcome to your stay</div>
</MockupBrowser>
```

### Do

- wrap a screenshot or a small live preview to show it in context.

### Don't

- use it as an actual browser or iframe — it renders content, nothing more.

---

## MockupCode

MockupCode — a terminal-style frame that shows a short block of commands or code, complete with the window chrome and a gutter for per-line prefixes. Use it in docs and onboarding to demonstrate a command someone runs (`$ yarn install`) or the output they should expect; pass a `prefix` per line for the `$`/`>` markers and a `className` like `text-warning` to tint a status line. It is illustrative, not interactive — reach for a real code editor or copyable snippet when people need to run the commands themselves.

### Slots

- `root`
- `line`
- `code`

### Props

| Prop | Type | Required | Default | Source | Description |
| --- | --- | --- | --- | --- | --- |
| `className` | `string` | no | — | interface | Extra classes merged onto the root frame. |
| `lines` | `readonly CodeLine[]` | no | — | interface | Lines to render, top to bottom. |

### Usage

```tsx
<MockupCode />
```

```tsx
<MockupCode
  lines={[
    {prefix: '$', content: 'yarn add daisyui'},
    {prefix: '>', content: 'installing…', className: 'text-warning'},
    {prefix: '>', content: 'done', className: 'text-success'}
  ]}
/>
```

### Do

- Keep each line short and give status lines a semantic text class so the
outcome reads at a glance.

### Don't

- Use it as an editable input — it only displays; wire a real control when
people must type or copy.

---

## MockupPhone

MockupPhone — a phone-shaped device frame that wraps a preview so a screen looks like it is running on a handset. Use it in marketing pages, onboarding tours, or a styleguide to show a mobile flow in context — a booking confirmation, the room keys screen, a folio — without hand-drawing a bezel. Drop any content in as `children`: a screenshot `<img>`, an embedded page, or live components; the frame clips it to the rounded display and adds the camera notch. It is pure chrome, not an interactive control, so it carries no color axis — the screen supplies all the color.

### Slots

- `root`
- `camera`
- `display`

### Props

| Prop | Type | Required | Default | Source | Description |
| --- | --- | --- | --- | --- | --- |
| `className` | `string` | no | — | interface | Extra classes merged onto the phone frame (tailwind-variants resolves conflicts). |
| `children` | `React.ReactNode` | no | — | interface | Screen content rendered inside the phone display (a screenshot, an image, or live UI). |

### Usage

```tsx
<MockupPhone>label</MockupPhone>
```

```tsx
<MockupPhone><img src="/booking.png" alt="booking confirmation" /></MockupPhone>
```

### Do

- fill the display edge to edge so the content reaches the rounded corners

### Don't

- hard-code the frame color — the device chrome is themed; retint via the theme

---

## MockupWindow

MockupWindow — a browser/app window frame for showing a screenshot or a live UI preview in context, complete with the title-bar dots. Use it in docs, onboarding, or marketing surfaces to present a screen as if captured in its own window — for example framing the guest check-in flow or a folio summary. Drop the content in as `children` and shape the inner panel (centering, height, padding) with `contentClassName`. It is a static frame, not an interactive window — the dots are decorative, so use real controls for anything a person needs to act on.

### Slots

- `root`
- `content`

### Props

| Prop | Type | Required | Default | Source | Description |
| --- | --- | --- | --- | --- | --- |
| `className` | `string` | no | — | interface | Extra classes merged onto the window frame (tailwind-variants resolves conflicts). |
| `contentClassName` | `string` | no | — | interface | Extra classes merged onto the inner content panel — set layout, height, or padding here. |
| `children` | `React.ReactNode` | no | — | interface | What the window frames — a screenshot, UI preview, or any node. |

### Usage

```tsx
<MockupWindow>label</MockupWindow>
```

```tsx
<MockupWindow contentClassName="grid place-content-center h-40">
  welcome to your stay
</MockupWindow>
```

### Do

- frame a screenshot or live UI preview to show a screen in context.

### Don't

- rely on the title dots as controls — they are decorative, not buttons.

---

## Navbar

Navbar — the horizontal bar across the top of a view that holds the brand, the primary navigation, and account or page actions. Fill any of three regions — `start`, `center`, `end` — and the bar spaces them apart; a region stays out of the DOM until you give it content, so a brand-plus-actions bar needs only `start` and `end`. It renders as a labelled navigation landmark, so drop links, a Button, or a Dropdown straight in. Keep it to one per view and reserve the `center` slot for a title or the main links, not a second row of actions.

### Slots

- `root`
- `start`
- `center`
- `end`

### Props

| Prop | Type | Required | Default | Source | Description |
| --- | --- | --- | --- | --- | --- |
| `className` | `string` | no | — | interface | Extra classes merged onto the root (tailwind-variants resolves conflicts). |
| `style` | `React.CSSProperties` | no | — | interface | Inline style — the CSS-variable override channel. |
| `start` | `React.ReactNode` | no | — | interface | Leading region — brand, logo, or a menu toggle. Aligned to the start edge. |
| `center` | `React.ReactNode` | no | — | interface | Middle region — a title or primary links. Sized to its content. |
| `end` | `React.ReactNode` | no | — | interface | Trailing region — actions, search, or the account menu. Aligned to the end edge. |

### Usage

```tsx
<Navbar />
```

```tsx
<Navbar
  start={<span className="text-lg font-semibold">Placemakr</span>}
  end={<Button size="sm">check in</Button>}
/>
```

### Do

- Reserve a single Navbar for the top of a view and let empty regions stay unset.

### Don't

- Stack two Navbars or cram actions into `center` — use `start`/`end` for those.

---

## Pagination

Pagination — lets a person move through a long, paged list (search results, a reservations table, an activity log) one page at a time. It renders a joined row of page buttons: the first and last page always show, a window sits around the current page, and `…` fills any gap so the control stays compact at scale. It is controlled — pass the current `page` and update it from `onPageChange` — and `siblingCount` widens the window around the current page. Size with `sm`/`md`/`lg` to match the surrounding density. The active page is marked with `aria-current="page"` and the whole row is a labelled navigation landmark, so it is screen-reader-accessible by default.

### Variants

- **size**: `sm`, `md`, `lg` (default `md`)

### Slots

- `root`
- `item`

### Props

| Prop | Type | Required | Default | Source | Description |
| --- | --- | --- | --- | --- | --- |
| `size` | `'sm' \| 'md' \| 'lg'` | no | `md` | variant | — |
| `className` | `string` | no | — | interface | Extra classes merged onto the root join container. |
| `count` | `number` | yes | — | interface | Total number of pages. |
| `page` | `number` | yes | — | interface | The current page, 1-based. |
| `onPageChange` | `(page: number) => void` | no | — | interface | Called with the requested page when a page button is pressed. |
| `siblingCount` | `number` | no | — | interface | Pages to show on each side of the current page before an ellipsis. |

### Usage

```tsx
<Pagination size="md" />
```

```tsx
<Pagination count={12} page={page} onPageChange={setPage} />
```

### Do

- keep Pagination controlled — drive `page` from state and update it in `onPageChange`

### Don't

- hard-code colors — retint the active page via the theme or the `style` override channel

---

## Progress

Progress — a slim horizontal bar that shows how far along a task is, from an upload to a multi-step check-in flow. Give it a `value` from 0 to `max` (100 by default) to fill the track; omit `value` for an indeterminate bar that animates while the amount of work is still unknown. Choose a `tone` to match the context — primary for a neutral task, success when it is nearly done, warning or danger to flag trouble. It is a status display, not a control — pair it with nearby text for the exact numbers.

### Variants

- **tone**: `primary`, `secondary`, `accent`, `info`, `success`, `warning`, `danger` (default `primary`)

### Props

| Prop | Type | Required | Default | Source | Description |
| --- | --- | --- | --- | --- | --- |
| `tone` | `'primary' \| 'secondary' \| 'accent' \| 'info' \| 'success' \| 'warning' \| 'danger'` | no | `primary` | variant | — |
| `className` | `string` | no | — | interface | Extra classes merged onto the root (tailwind-variants resolves conflicts). |
| `value` | `number` | no | — | interface | How far along the task is, from 0 to `max`. Omit it for an indeterminate bar that animates while the amount of work is still unknown. |
| `max` | `number` | no | — | interface | The value that represents a full bar. Defaults to 100. |

### Usage

```tsx
<Progress tone="primary" />
```

```tsx
<Progress value={70} />
```

```tsx
<Progress tone="success" value={100} />
```

```tsx
<Progress aria-label="loading availability" />
```

### Do

- give an indeterminate bar an `aria-label` so its purpose is announced.

### Don't

- use Progress for a value a person can drag — reach for Range instead.

---

## RadialProgress

RadialProgress — a circular gauge that shows how far along a value is, from 0 to 100 (e.g. profile completeness, an upload, nights checked in). Pass `value` and it fills the ring and prints the percentage in the center; supply `children` to label it with something else, and `size`/`thickness` to fit the surface. Choose a `tone` to signal meaning — the ring paints with the theme color, so no colors are hard-coded. It reports progress as an ARIA `progressbar`; it is a display, not a control — use a slider for input.

### Variants

- **tone**: `brand`, `info`, `success`, `warning`, `danger` (default `brand`)

### Props

| Prop | Type | Required | Default | Source | Description |
| --- | --- | --- | --- | --- | --- |
| `tone` | `'brand' \| 'info' \| 'success' \| 'warning' \| 'danger'` | no | `brand` | variant | — |
| `value` | `number` | yes | — | interface | Completion from 0 to 100 — drives the `--value` custom property and the ring fill. |
| `size` | `string` | no | — | interface | Overall diameter as a CSS length (e.g. `'6rem'`) → the `--size` custom property. |
| `thickness` | `string` | no | — | interface | Ring thickness as a CSS length (e.g. `'4px'`) → the `--thickness` custom property. |
| `className` | `string` | no | — | interface | Extra classes merged onto the root (tailwind-variants resolves conflicts). |
| `children` | `React.ReactNode` | no | — | interface | Center label; defaults to `${value}%` when omitted. |

### Usage

```tsx
<RadialProgress tone="brand">label</RadialProgress>
```

```tsx
<RadialProgress value={70} />
```

```tsx
<RadialProgress value={40} tone="success" size="6rem" thickness="4px">
  40%
</RadialProgress>
```

### Do

- Keep `value` between 0 and 100 and let the center label read as a percentage.

### Don't

- Use it for indeterminate work with no known percentage — use a spinner instead.

---

## Radio

Radio — a single control for a one-of-many choice, such as picking a rate plan or a room type. Use it when exactly one option in a set may be selected; for an independent on/off choice use a checkbox, and for a compact setting consider a switch. Radios are grouped by sharing the native `name` prop across the set, so selecting one clears the rest. Pair each with a `label`, and a `description` when the option needs a line of explanation.

### Variants

- **size**: `sm`, `md`, `lg` (default `md`)
- **tone**: `primary`, `secondary`, `accent`, `neutral`, `info`, `success`, `warning`, `error` (default `primary`)
- **invalid**: boolean
- **disabled**: boolean

### Slots

- `root`
- `control`
- `label`
- `labelText`
- `description`

### Props

| Prop | Type | Required | Default | Source | Description |
| --- | --- | --- | --- | --- | --- |
| `size` | `'sm' \| 'md' \| 'lg'` | no | `md` | variant | Control size. Defaults to md. |
| `tone` | `'primary' \| 'secondary' \| 'accent' \| 'neutral' \| 'info' \| 'success' \| 'warning' \| 'error'` | no | `primary` | variant | Color role for the control. Defaults to primary. |
| `invalid` | `boolean` | no | — | variant | Marks the control invalid and applies the error style. |
| `disabled` | `boolean` | no | — | variant | Disables the control. |
| `checked` | `boolean` | no | — | schema | Controlled checked state. |
| `className` | `string` | no | — | interface | Extra classes merged onto the root label. |
| `style` | `React.CSSProperties` | no | — | interface | Inline style — the CSS-variable override channel. |
| `label` | `React.ReactNode` | no | — | interface | Label beside the control. |
| `description` | `React.ReactNode` | no | — | interface | Secondary line under the label. |
| `onChange` | `(checked: boolean) => void` | no | — | interface | Reports the new checked state. |

### Usage

```tsx
<Radio size="md" tone="primary" />
```

```tsx
<Radio name="bed" value="king" label="king" defaultChecked />
<Radio name="bed" value="queen" label="queen" />
```

### Do

- Give every radio in a group the same `name` so they behave as one set.

### Don't

- Use a radio for a standalone yes/no — reach for a checkbox or toggle.

---

## Range

Range — a slider for picking a single number from a continuous span, such as a price ceiling, a party size, or a number of nights. Set `min`/`max`/`step` to bound and quantize the values, and read the choice through `onChange`, which hands back a plain number. Size with `xs`/`sm`/`md`/`lg` to match the surrounding form, and give it a `tone` to tint the filled track and thumb with a color role. Reach for a Range when the exact figure matters less than the sense of more-or-less; use an Input of type number when a person needs to type a precise value. Pair it with a form field for the label and a live read-out of the current value.

### Variants

- **size**: `xs`, `sm`, `md`, `lg` (default `md`)
- **tone**: `primary`, `secondary`, `accent`, `success`, `warning`, `info`, `error`

### Props

| Prop | Type | Required | Default | Source | Description |
| --- | --- | --- | --- | --- | --- |
| `size` | `'xs' \| 'sm' \| 'md' \| 'lg'` | no | `md` | variant | Track and thumb size. Defaults to md. |
| `tone` | `'primary' \| 'secondary' \| 'accent' \| 'success' \| 'warning' \| 'info' \| 'error'` | no | — | variant | Color role for the filled track and thumb. |
| `disabled` | `boolean` | no | — | schema | Disables the slider. |
| `className` | `string` | no | — | interface | Extra classes merged onto the slider. |
| `style` | `React.CSSProperties` | no | — | interface | Inline style — the CSS-variable override channel. |
| `onChange` | `(value: number) => void` | no | — | interface | Reports the new value as a number (`event.target.valueAsNumber`). |

### Usage

```tsx
<Range size="md" />
```

```tsx
<Range min={1} max={7} defaultValue={3} onChange={setNights} />
```

```tsx
<Range tone="primary" min={0} max={500} step={25} defaultValue={250} />
```

### Do

- Show the current value next to the slider so the choice is legible.

### Don't

- Use a Range for a value that must be exact — offer a number Input instead.

---

## Rating

Rating — a row of stars for capturing or showing a score, such as how a guest rated their stay. Use it for a small, bounded scale (typically five) where the shape carries the meaning at a glance; for longer or non-symbolic scales reach for a slider or a select. It is a controlled input: pass `value` and handle `onChange`, which fires the chosen number. A leading clear input lets someone reset to no rating (`0`), `half` enables half-star precision, and `shape` swaps stars for hearts when you want a favorite rather than a score. Each star is a real radio sharing one group name, so it is keyboard- and screen-reader-friendly.

### Variants

- **size**: `xs`, `sm`, `md`, `lg` (default `md`)
- **shape**: `star`, `heart` (default `star`)
- **half**: boolean
- **disabled**: boolean

### Slots

- `root`
- `item`

### Props

| Prop | Type | Required | Default | Source | Description |
| --- | --- | --- | --- | --- | --- |
| `size` | `'xs' \| 'sm' \| 'md' \| 'lg'` | no | `md` | variant | Star size. Defaults to md. |
| `shape` | `'star' \| 'heart'` | no | `star` | variant | Item mask shape. Defaults to star. |
| `half` | `boolean` | no | — | variant | Allows half-star selection in 0.5 steps. |
| `disabled` | `boolean` | no | — | variant | Disables the control and dims it. |
| `value` | `number` | no | — | schema | Controlled rating value; 0 clears the selection. |
| `max` | `number` | no | — | schema | Number of stars to render. Defaults to 5. |
| `className` | `string` | no | — | interface | Extra classes merged onto the root container. |
| `style` | `React.CSSProperties` | no | — | interface | Inline style — the CSS-variable override channel. |
| `clearable` | `boolean` | no | — | interface | Renders a leading input that resets the value to 0. Defaults to true. |
| `onChange` | `(value: number) => void` | no | — | interface | Reports the newly selected value. |

### Usage

```tsx
<Rating size="md" shape="star" />
```

---

## Select

Select — a dropdown for choosing one value from a fixed set of options (an arrival window, a room type, a status). Use it when the options are known and mutually exclusive and there are more than a couple of them; for two or three choices consider radios, and for many searchable options a typeahead. Pass `options` as strings or `{value, label}` pairs and a `placeholder` for the empty prompt, and set `invalid` to show the error state. Pair it with a form field for the label and error surface.

### Variants

- **size**: `sm`, `md`, `lg` (default `md`)
- **invalid**: boolean

### Props

| Prop | Type | Required | Default | Source | Description |
| --- | --- | --- | --- | --- | --- |
| `size` | `'sm' \| 'md' \| 'lg'` | no | `md` | variant | Control height. Defaults to md. |
| `invalid` | `boolean` | no | — | variant | Marks the field invalid and applies the error style. |
| `placeholder` | `string` | no | — | schema | Empty-value first option, e.g. "choose a time". |
| `className` | `string` | no | — | interface | Extra classes merged onto the root (tailwind-variants resolves conflicts). |
| `style` | `React.CSSProperties` | no | — | interface | Inline style — the CSS-variable override channel. |
| `options` | `readonly (string \| SelectOption)[]` | no | — | interface | Options as bare strings or `{value, label}` pairs. |
| `children` | `React.ReactNode` | no | — | interface | Custom `<option>` children instead of (or after) `options`. |

### Usage

```tsx
<Select size="md">label</Select>
```

---

## Skeleton

Skeleton — a shimmering placeholder that stands in for content while it loads, so the layout holds its shape instead of jumping when data arrives. Size it with `className` (Tailwind width/height/rounded utilities) to mirror the real element it replaces — a line of text, an avatar, a card — and set `shape="circle"` for round placeholders. Render one per incoming element and swap it for the real content once loaded; it is purely decorative, marked `aria-busy` so assistive tech announces the pending state rather than reading an empty box.

### Variants

- **shape**: `rect`, `circle` (default `rect`)

### Props

| Prop | Type | Required | Default | Source | Description |
| --- | --- | --- | --- | --- | --- |
| `shape` | `'rect' \| 'circle'` | no | `rect` | variant | — |
| `className` | `string` | no | — | interface | Extra classes merged onto the root — size the placeholder here (`h-32 w-full`, `size-12`, `rounded-lg`). |
| `children` | `React.ReactNode` | no | — | interface | Optional content to reserve space around; a Skeleton is usually empty. |

### Usage

```tsx
<Skeleton shape="rect">label</Skeleton>
```

```tsx
<Skeleton className="h-32 w-full" />
```

```tsx
<Skeleton shape="circle" className="size-16" />
```

### Do

- Match the Skeleton's size to the content it replaces so nothing shifts on load.

### Don't

- Leave a Skeleton on screen after the data resolves — always swap it for the real element.

---

## Stack

Stack — a layout container that lays its children in one cell so they overlap, front to back, with the ones behind peeking out. Use it to imply a pile or a count without a real list: a shuffle of key cards, a run of notification toasts, a couple of stacked receipts on a folio. The first child sits on top; give `placement` an edge (top, bottom, start, end) to choose which way the layers behind fan out. It is decorative arrangement, not a carousel — reach for a proper list or Carousel when the layers need to be read or navigated.

### Variants

- **placement**: `top`, `bottom`, `start`, `end`

### Props

| Prop | Type | Required | Default | Source | Description |
| --- | --- | --- | --- | --- | --- |
| `placement` | `'top' \| 'bottom' \| 'start' \| 'end'` | no | — | variant | — |
| `className` | `string` | no | — | interface | Extra classes merged onto the root (tailwind-variants resolves conflicts). |
| `children` | `React.ReactNode` | no | — | interface | The overlapping layers, front-most first. |

### Usage

```tsx
<Stack>label</Stack>
```

```tsx
<Stack>
  <div className="card bg-primary text-primary-content p-4">room 412</div>
  <div className="card bg-secondary text-secondary-content p-4">room 413</div>
  <div className="card bg-accent text-accent-content p-4">room 414</div>
</Stack>
```

### Do

- use it for a small pile of like items where the depth is the message.

### Don't

- use it to overlap unrelated content — that is a job for absolute layout.

---

## Stat

Stat — a compact group of headline metrics, each a title, a big value, and an optional supporting line. Use it to surface the numbers that matter at a glance — occupancy, revenue, nights booked — across the top of a dashboard or summary. Pass `orientation="vertical"` to stack the blocks in a narrow column instead of flowing them across. Hang an icon or badge off `figure` to give a metric a visual anchor. Keep titles short and lowercase, and let the value do the talking.

### Variants

- **orientation**: `horizontal`, `vertical` (default `horizontal`)

### Slots

- `root`
- `item`
- `figure`
- `title`
- `value`
- `desc`

### Props

| Prop | Type | Required | Default | Source | Description |
| --- | --- | --- | --- | --- | --- |
| `orientation` | `'horizontal' \| 'vertical'` | no | `horizontal` | variant | — |
| `className` | `string` | no | — | interface | Extra classes merged onto the root container. |
| `items` | `readonly StatItem[]` | no | — | interface | Metric blocks to render. |

### Usage

```tsx
<Stat orientation="horizontal" />
```

```tsx
<Stat
  items={[
    {title: 'occupancy', value: '92%', desc: '4% more than last week'},
    {title: 'nights booked', value: '1,204', desc: 'since check-in opened'}
  ]}
/>
```

### Do

- keep titles to a couple of words so the value stays the focal point.

### Don't

- crowd a single group with more than four or five metrics — split them.

---

## Status

Status — a tiny inline dot that signals the live state of a nearby thing (e.g. a room is available, a guest is checked in, a sync is running). Use it beside a label, avatar, or list row to surface state at a glance without taking up space. Choose a `tone` to carry the meaning and a `size` to match the type around it. It is a decorative indicator with no text of its own, so always give it an `aria-label`; for an action use a Button, and for a labelled tag use a Badge.

### Variants

- **tone**: `neutral`, `brand`, `secondary`, `accent`, `info`, `success`, `warning`, `danger` (default `neutral`)
- **size**: `xs`, `sm`, `md`, `lg` (default `md`)

### Props

| Prop | Type | Required | Default | Source | Description |
| --- | --- | --- | --- | --- | --- |
| `tone` | `'neutral' \| 'brand' \| 'secondary' \| 'accent' \| 'info' \| 'success' \| 'warning' \| 'danger'` | no | `neutral` | variant | — |
| `size` | `'xs' \| 'sm' \| 'md' \| 'lg'` | no | `md` | variant | — |
| `className` | `string` | no | — | interface | Extra classes merged onto the root (tailwind-variants resolves conflicts). |

### Usage

```tsx
<Status tone="neutral" size="md" />
```

```tsx
<Status tone="success" aria-label="room is available" />
```

```tsx
<Status tone="warning" size="lg" aria-label="cleaning in progress" />
```

### Do

- pair every Status with an aria-label so its meaning reaches assistive tech.

### Don't

- stretch a Status to convey a count or a word — reach for a Badge instead.

---

## Steps

Steps — an ordered tracker that shows where someone is in a multi-part flow and how much is left, laid out as numbered nodes joined by connectors. Reach for it on a checkout, onboarding, or check-in wizard so people can see the whole path at a glance. Pass `items` for the sequence and `current` to mark the active step — every step up to and including it takes the `tone` color, the rest stay muted. Set `orientation` to `vertical` for a stacked layout in narrow columns, and give an item an `icon` to replace its auto number with a glyph. It is a status display, not a set of controls — use Tabs or a Button when a person needs to move between steps directly.

### Variants

- **orientation**: `horizontal`, `vertical` (default `horizontal`)
- **tone**: `primary`, `secondary`, `accent`, `info`, `success`, `warning`, `error`

### Slots

- `root`
- `item`

### Props

| Prop | Type | Required | Default | Source | Description |
| --- | --- | --- | --- | --- | --- |
| `orientation` | `'horizontal' \| 'vertical'` | no | `horizontal` | variant | — |
| `tone` | `'primary' \| 'secondary' \| 'accent' \| 'info' \| 'success' \| 'warning' \| 'error'` | no | — | variant | — |
| `className` | `string` | no | — | interface | Extra classes merged onto the root (tailwind-variants resolves conflicts). |
| `items` | `readonly StepItem[]` | no | — | interface | Ordered steps to render. |
| `current` | `number` | no | — | interface | 0-based index of the active step; steps with index ≤ current get the tone color. |

### Usage

```tsx
<Steps orientation="horizontal" />
```

```tsx
<Steps
  current={1}
  items={[
    {label: 'reserve'},
    {label: 'check in'},
    {label: 'room keys'}
  ]}
/>
```

### Do

- Keep labels to a word or two so the horizontal track stays readable.

### Don't

- Use Steps to navigate between screens — it reports progress, it does not control it.

---

## Swap

Swap — a single control that flips between two faces in place, such as play/pause, menu/close, or a lights-on/lights-off setting. Use it when one tap moves between two mirrored states and you want the transition to read as motion rather than a jump; for a labelled on/off form setting reach for a toggle instead. Choose the `effect` axis to spin the faces (`rotate`, the default) or turn them over (`flip`). It drives a real hidden checkbox, so it toggles on click and by keyboard and reports back through `onChange`. Keep the two faces the same size so nothing shifts as they trade places.

### Variants

- **effect**: `rotate`, `flip` (default `rotate`)

### Slots

- `root`
- `on`
- `off`
- `indeterminate`

### Props

| Prop | Type | Required | Default | Source | Description |
| --- | --- | --- | --- | --- | --- |
| `effect` | `'rotate' \| 'flip'` | no | `rotate` | variant | — |
| `className` | `string` | no | — | interface | Extra classes merged onto the root label. |
| `style` | `React.CSSProperties` | no | — | interface | Inline style — the CSS-variable override channel. |
| `on` | `React.ReactNode` | yes | — | interface | Face shown when active. |
| `off` | `React.ReactNode` | yes | — | interface | Face shown when inactive. |
| `active` | `boolean` | no | — | interface | Controlled active state; pair with `onChange`. |
| `defaultActive` | `boolean` | no | — | interface | Uncontrolled initial active state. |
| `onChange` | `(active: boolean) => void` | no | — | interface | Reports the new active state on toggle. |
| `indeterminate` | `React.ReactNode` | no | — | interface | Optional third face shown while the checkbox is indeterminate. |

### Usage

```tsx
<Swap effect="rotate" />
```

```tsx
<Swap on="ON" off="OFF" defaultActive />
```

```tsx
<Swap
  effect="flip"
  active={open}
  onChange={setOpen}
  on={<CloseIcon />}
  off={<MenuIcon />}
/>
```

### Do

- Keep both faces the same footprint so the toggle stays put as it swaps.

### Don't

- Reach for Swap to collect a form value — use a toggle or checkbox.

---

## Tabs

Tabs — a horizontal set of views that share a region, where selecting a tab swaps the panel below it. Use tabs to divide related content into a few peer sections the user moves between (arrivals / departures / in-house) without leaving the page; don't use them for sequential steps — use a stepper — or for primary navigation. Choose the `underline` variant for in-page section switching and `pill` for a more contained, toolbar-like grouping. Left/Right and Home/End move focus and selection between enabled tabs, following the ARIA tablist pattern.

### Variants

- **variant**: `underline`, `pill` (default `underline`)

### Slots

- `list`
- `tab`
- `panel`

### Props

| Prop | Type | Required | Default | Source | Description |
| --- | --- | --- | --- | --- | --- |
| `variant` | `'underline' \| 'pill'` | no | `underline` | variant | — |
| `className` | `string` | no | — | interface | Extra classes merged onto the tablist container. |
| `tabs` | `readonly TabItem[]` | no | — | interface | The tabs to render. |
| `selected` | `string` | no | — | interface | Controlled active tab id. |
| `defaultSelected` | `string` | no | — | interface | Initial active tab id when uncontrolled. |
| `onSelect` | `(id: string) => void` | no | — | interface | Called with the newly selected tab id. |

### Usage

```tsx
<Tabs variant="underline" />
```

---

## Textarea

Textarea — a multi-line text field bound to `value`/`onChange` for capturing longer free-form entries such as a guest note, special request, or feedback. Set `rows` to size the visible height, and set `invalid` to show the error state when validation fails. Size with `sm`/`md`/`lg` to match the surrounding form. Pair it with a form field for the label, help text, and error message; use an Input instead when a single line is enough.

### Variants

- **size**: `sm`, `md`, `lg` (default `md`)
- **invalid**: boolean

### Props

| Prop | Type | Required | Default | Source | Description |
| --- | --- | --- | --- | --- | --- |
| `size` | `'sm' \| 'md' \| 'lg'` | no | `md` | variant | Control height. Defaults to md. |
| `invalid` | `boolean` | no | — | variant | Marks the field invalid and applies the error style. |
| `className` | `string` | no | — | interface | Extra classes merged onto the field. |
| `style` | `React.CSSProperties` | no | — | interface | Inline style — the CSS-variable override channel. |

### Usage

```tsx
<Textarea size="md" />
```

---

## TextBlock

TextBlock — a paragraph of body copy rendered in the theme's body type roles. Use it for readable running text — descriptions, help text, empty-state explanations. `regular` is the default; `small` steps the size down for dense or secondary passages. It renders a `<p>`, so use one TextBlock per paragraph rather than stacking line breaks.

### Variants

- **variant**: `regular`, `small` (default `regular`)

### Props

| Prop | Type | Required | Default | Source | Description |
| --- | --- | --- | --- | --- | --- |
| `variant` | `'regular' \| 'small'` | no | `regular` | variant | — |
| `className` | `string` | no | — | interface | Extra classes merged onto the root (tailwind-variants resolves conflicts). |
| `children` | `React.ReactNode` | no | — | interface | Paragraph content. |

### Usage

```tsx
<TextBlock variant="regular">label</TextBlock>
```

```tsx
<TextBlock variant="regular">Guest arriving at 3:00pm.</TextBlock>
```

---

## Timeline

Timeline — an ordered track of events connected by a running line, each with an icon on the line and detail to one or both sides. Use it to show a sequence in time (a reservation's lifecycle, a stay's check-in to check-out, a delivery's status) so people can follow what happened and what comes next. Feed it an `items` array: each event supplies a `start` label, a `middle` marker, and an `end` detail, and the connectors between events are drawn for you. Set `orientation` to run it horizontally, `compact` to keep every event on one side, and clear an item's `boxed` flag when its detail should sit inline instead of in a card. It is read-only structure, not a control — reach for Steps when a person is moving through a process.

### Variants

- **orientation**: `vertical`, `horizontal` (default `vertical`)
- **compact**: boolean
- **boxed**: boolean (default `true`)

### Slots

- `root`
- `item`
- `start`
- `middle`
- `end`

### Props

| Prop | Type | Required | Default | Source | Description |
| --- | --- | --- | --- | --- | --- |
| `orientation` | `'vertical' \| 'horizontal'` | no | `vertical` | variant | Run the track down the page or across it; defaults to `vertical`. |
| `compact` | `boolean` | no | — | variant | Collapse each event to one side of the connector. |
| `boxed` | `boolean` | no | `true` | variant | — |
| `className` | `string` | no | — | interface | Extra classes merged onto the root (tailwind-variants resolves conflicts). |
| `items` | `readonly TimelineItem[]` | no | — | interface | Ordered events to render along the track. |

### Usage

```tsx
<Timeline orientation="vertical" boxed />
```

---

## Toast

Toast — a brief, self-dismissing notification that confirms the result of an action ("request sent", "changes saved") without interrupting what the user is doing. Use it for transient, low-stakes feedback that does not need acknowledgement; for information that must persist on the page use an Alert, and for a decision that must block the flow use a Dialog. Set the `tone` to match the outcome and keep the message to one short line, optionally with a single inline action such as undo.

### Variants

- **tone**: `info`, `success`, `warning`, `danger`, `brand` (default `success`)

### Props

| Prop | Type | Required | Default | Source | Description |
| --- | --- | --- | --- | --- | --- |
| `tone` | `'info' \| 'success' \| 'warning' \| 'danger' \| 'brand'` | no | `success` | variant | — |
| `className` | `string` | no | — | interface | Extra classes merged onto the root (tailwind-variants resolves conflicts). |
| `message` | `React.ReactNode` | no | — | interface | One short past-tense line: "request sent to the front desk". |
| `action` | `React.ReactNode` | no | — | interface | Optional inline action — usually a ghost Button (e.g. undo). |
| `onDismiss` | `() => void` | no | — | interface | Renders a dismiss control that calls this handler. |
| `children` | `React.ReactNode` | no | — | interface | Body, when richer than `message`. |

### Usage

```tsx
<Toast tone="success">label</Toast>
```

---

## Toggle

Toggle — a switch for a setting that takes effect immediately, such as turning on housekeeping alerts or opting into text updates. Reach for it when the choice is a self-contained on/off with an obvious default; for choosing among options use radio controls, and for a boolean that only applies once a form is submitted prefer a checkbox. Tint the checked track with `tone` to match the surrounding context, and pair it with a `label`, adding a `description` when the setting needs a line of explanation.

### Variants

- **size**: `sm`, `md`, `lg` (default `md`)
- **tone**: `primary`, `secondary`, `accent`, `success`, `warning`, `info`, `error` (default `primary`)
- **disabled**: boolean

### Slots

- `root`
- `control`
- `label`
- `labelText`
- `description`

### Props

| Prop | Type | Required | Default | Source | Description |
| --- | --- | --- | --- | --- | --- |
| `size` | `'sm' \| 'md' \| 'lg'` | no | `md` | variant | Control size. Defaults to md. |
| `tone` | `'primary' \| 'secondary' \| 'accent' \| 'success' \| 'warning' \| 'info' \| 'error'` | no | `primary` | variant | Color role for the checked track. Defaults to primary. |
| `disabled` | `boolean` | no | — | variant | Disables the control. |
| `checked` | `boolean` | no | — | schema | Controlled on/off state. |
| `className` | `string` | no | — | interface | Extra classes merged onto the root label. |
| `style` | `React.CSSProperties` | no | — | interface | Inline style — the CSS-variable override channel. |
| `label` | `React.ReactNode` | no | — | interface | Label beside the switch. |
| `description` | `React.ReactNode` | no | — | interface | Secondary line under the label. |
| `onChange` | `(checked: boolean) => void` | no | — | interface | Reports the new on/off state. |

### Usage

```tsx
<Toggle size="md" tone="primary" />
```

```tsx
<Toggle label="Housekeeping alerts" defaultChecked />
```

```tsx
<Toggle
  tone="success"
  label="Text me room updates"
  description="We'll text when your room is ready."
  onChange={on => setSmsOptIn(on)}
/>
```

### Do

- Use a Toggle for settings that apply the moment they change.

### Don't

- Use a Toggle inside a form where the value only matters on submit — use a Checkbox.

---

## Tooltip

Tooltip — a small hover/focus hint that explains the trigger it wraps (e.g. a terse icon button, a truncated folio line, a status badge). Wrap the trigger as `children` and pass the hint as `tip`; a string tip rides the `data-tip` attribute, while a richer node renders in a `.tooltip-content` bubble. Move it with `placement`, colour it with `tone` to echo the surface it annotates, and set `open` to pin it visible for a walkthrough or a screenshot. Keep tips to a phrase — they supplement the UI, they are not where the real content lives.

### Variants

- **placement**: `top`, `bottom`, `left`, `right` (default `top`)
- **tone**: `brand`, `secondary`, `accent`, `info`, `success`, `warning`, `danger`
- **open**: boolean

### Props

| Prop | Type | Required | Default | Source | Description |
| --- | --- | --- | --- | --- | --- |
| `placement` | `'top' \| 'bottom' \| 'left' \| 'right'` | no | `top` | variant | — |
| `tone` | `'brand' \| 'secondary' \| 'accent' \| 'info' \| 'success' \| 'warning' \| 'danger'` | no | — | variant | — |
| `open` | `boolean` | no | — | variant | — |
| `className` | `string` | no | — | interface | Extra classes merged onto the root (tailwind-variants resolves conflicts). |
| `tip` | `React.ReactNode` | yes | — | interface | The hint shown on hover or focus. A plain string renders through the CSS `data-tip` attribute; any richer node (formatted text, key/value rows) is rendered into a `.tooltip-content` bubble instead. |
| `children` | `React.ReactNode` | no | — | interface | The trigger the tip describes — typically a button, link, or icon. |

### Usage

```tsx
<Tooltip placement="top">label</Tooltip>
```

```tsx
<Tooltip tip="checked in 3:00 PM">
  <button className="btn">details</button>
</Tooltip>
```

```tsx
<Tooltip placement="right" tone="brand" tip="room keys are ready">
  <button className="btn btn-primary">continue</button>
</Tooltip>
```

### Do

- Keep the tip to a short phrase that adds context the trigger cannot show
on its own.

### Don't

- Put essential content or actions inside a tip — it is hidden until hover
and never reachable on touch.