# All Components

Source: /docs/components/overview.md

# Components

Every component Frontile ships today, grouped by category. Pick one below to jump straight
into its docs and live demos.

<ComponentsOverviewGrid />

---

# ButtonGroup

Source: /docs/components/buttons/button-group.md

# ButtonGroup

A button group is used to group buttons whose actions are related.

## Import

```js
import { ButtonGroup } from 'frontile';
```

## Usage

```gts preview
import { ButtonGroup } from 'frontile';

<template>
  <ButtonGroup aria-label='Example actions' as |g|>
    <g.Button>First</g.Button>
    <g.Button>Second</g.Button>
    <g.Button>Third</g.Button>
  </ButtonGroup>
</template>
```

## Using with ToggleButton

```gts preview collapsible
import Component from '@glimmer/component';
import { tracked } from '@glimmer/tracking';
import { fn } from '@ember/helper';
import { ButtonGroup } from 'frontile';

export default class Example extends Component {
  @tracked
  isSelected = {
    first: false,
    second: false,
    third: false
  };

  onChange = (ty: keyof typeof this.isSelected, value: boolean): void => {
    this.isSelected[ty] = value;
    this.isSelected = { ...this.isSelected };
  };

  <template>
    <ButtonGroup
      @size='sm'
      @color='primary'
      aria-label='Example toggles'
      as |g|
    >
      {{#each-in this.isSelected as |key val|}}
        <g.ToggleButton
          @isSelected={{val}}
          @onChange={{(fn this.onChange key)}}
        >
          {{key}}
        </g.ToggleButton>
      {{/each-in}}
    </ButtonGroup>
  </template>
}
```

## ButtonGroup use case

A common use case for `ButtonGroup` is to create a split button.

```gts preview
import { ButtonGroup } from 'frontile';
import { ChevronDownIcon } from 'site/components/icons';

<template>
  <ButtonGroup @size='sm' @color='primary' aria-label='Merge options' as |g|>
    <g.Button>Create a merge commit</g.Button>
    <g.Button
      @class='border-l-primary-mild'
      aria-label='More merge options'
    ><ChevronDownIcon /></g.Button>
  </ButtonGroup>
</template>
```

## Arguments

Arguments passed to `ButtonGroup` are forwarded to every yielded component. Any
of them can be overridden on an individual button.

```gts preview
import { ButtonGroup } from 'frontile';

<template>
  <ButtonGroup @size='sm' @color='primary' aria-label='Example actions' as |g|>
    <g.Button>First</g.Button>
    <g.Button>Second</g.Button>
    <g.Button @color='danger'>Third</g.Button>
  </ButtonGroup>
</template>
```

## Accessibility

`ButtonGroup` renders `role="group"`, which tells assistive technology that the
buttons belong together — but a group with no name is announced as an unlabelled
container, so the relationship is stated without being explained. Name it with
`aria-label` (or `aria-labelledby` pointing at a visible heading); both pass
through to the element via `...attributes`.

```gts preview
import { ButtonGroup } from 'frontile';

<template>
  <div class='flex flex-col gap-6'>
    <ButtonGroup aria-label='Text alignment' as |g|>
      <g.Button>Left</g.Button>
      <g.Button>Center</g.Button>
      <g.Button>Right</g.Button>
    </ButtonGroup>

    <div>
      <h4 id='zoom-label' class='text-neutral-strong mb-2'>Zoom</h4>
      <ButtonGroup aria-labelledby='zoom-label' as |g|>
        <g.Button>Out</g.Button>
        <g.Button>Reset</g.Button>
        <g.Button>In</g.Button>
      </ButtonGroup>
    </div>
  </div>
</template>
```

Grouping does not change how the buttons themselves behave: each stays in the
tab order and is reached with `Tab`, not with arrow keys. If you want one
selection out of several with arrow-key navigation, that is a radio group rather
than a button group — see [RadioGroup](/docs/components/forms/radio-group).

Yielded `g.ToggleButton`s each carry their own `aria-pressed`, so a group of them
is announced as several independent toggles. That is right for a formatting
toolbar where bold and italic can both be on; it is misleading for a set where
only one value can be active at a time.

## API

### ButtonGroup

**Element:** `HTMLDivElement`

**Arguments**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `appearance` | `'soft' \| 'custom' \| 'default' \| 'outlined' \| 'minimal' \| 'tonal'` | - | **Deprecated.** Use `variant`. `default` is now `solid`, `outlined` is `outline`, and `minimal` is `plain`. |
| `class` | `string` | - | Custom class name, it will override the default ones using Tailwind Merge library. |
| `color` | `'neutral' \| 'primary' \| 'secondary' \| 'tertiary' \| 'success' \| 'warning' \| 'danger'` | - | The color of the button |
| `intent` | `'default' \| 'primary' \| 'secondary' \| 'tertiary' \| 'success' \| 'warning' \| 'danger'` | - | **Deprecated.** Use `color`. `default` is now `neutral`. |
| `size` | `'sm' \| 'md' \| 'lg' \| 'xs' \| 'xl' \| '2xl'` | - | The size of the button |
| `variant` | `'solid' \| 'soft' \| 'subtle' \| 'outline' \| 'ghost' \| 'plain' \| 'custom'` | `'solid'` | The button variant. |

**Blocks**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `default *` | `[{ Button: Button (isInGroup bound); ToggleButton: ToggleButton (isInGroup bound); }]` | - |  |

---

# Button

Source: /docs/components/buttons/button.md

# Button

The Button component can be used to trigger an action, such as submitting a form, opening a modal, and more.

## Import

```js
import { Button } from 'frontile';
```

## Usage

```gts preview
import { Button } from 'frontile';

<template>
  <Button>Button</Button>
</template>
```

## Button Variants

```gts preview
import { Button } from 'frontile';

<template>
  <div class='flex flex-wrap items-center gap-3'>
    <Button>Default</Button>
    <Button @variant='subtle'>Subtle</Button>
    <Button @variant='outline'>Outline</Button>
    <Button @variant='soft'>Soft</Button>
    <Button @variant='plain'>Plain</Button>
    <Button @variant='custom'>Custom</Button>
  </div>
</template>
```

The `custom` variant is available for the cases where you might want to fully customize the appearance of the button.
The default styles are mainly structural. Colors are applied as `color`.

## Button Colors

Every color is available in every variant. The label on each row is the
`@variant` value; the button labels are the `@color` values.

```gts preview collapsible
import { Button } from 'frontile';
import { array } from '@ember/helper';

const colors = [
  'neutral',
  'primary',
  'secondary',
  'tertiary',
  'success',
  'warning',
  'danger'
];

<template>
  <div class='flex flex-col gap-6'>
    {{#each (array 'solid' 'subtle' 'outline' 'soft' 'plain') as |variant|}}
      <div>
        <p class='font-code text-code-sm text-neutral-strong mb-2'>
          @variant='{{variant}}'
        </p>
        <div class='flex flex-wrap items-center gap-3'>
          {{#each colors as |color|}}
            <Button @variant={{variant}} @color={{color}}>
              {{color}}
            </Button>
          {{/each}}
        </div>
      </div>
    {{/each}}
  </div>
</template>
```

## Button Sizes

```gts preview
import { Button } from 'frontile';

<template>
  <div class='flex flex-wrap items-center gap-3'>
    <Button @size='xs'>Button xs</Button>
    <Button @size='sm'>Button sm</Button>
    <Button>Button md</Button>
    <Button @size='lg'>Button lg</Button>
    <Button @size='xl'>Button xl</Button>
    <Button @size='2xl'>Button 2xl</Button>
  </div>
</template>
```

## With Icons

```gts preview
import { Button } from 'frontile';
import { DownloadIcon, ShareIcon, CheckIcon } from 'site/components/icons';

<template>
  <div class='flex flex-wrap items-center gap-3'>
    <Button @size='xs' @color='primary'><DownloadIcon /> Download</Button>
    <Button @size='sm' @color='primary'><DownloadIcon /> Download</Button>
    <Button @color='primary'><DownloadIcon /> Download</Button>
    <Button @size='lg' @color='primary'><DownloadIcon /> Download</Button>
    <Button @size='xl' @color='primary'><DownloadIcon /> Download</Button>
  </div>
</template>
```

Icons can be placed before or after text. They inherit the button's text color via `currentColor`.

```gts preview
import { Button } from 'frontile';
import { DownloadIcon, ShareIcon, CheckIcon } from 'site/components/icons';

<template>
  <div class='flex gap-4'>
    <Button @color='primary'><DownloadIcon /> Download</Button>
    <Button @variant='outline' @color='neutral'>Share
      <ShareIcon /></Button>
    <Button @variant='soft' @color='success'><CheckIcon /> Confirm</Button>
  </div>
</template>
```

Icons passed as plain content keep working exactly as above. The `icon` named
block is opt-in sugar: it buys you `@iconPlacement` and, when the button is
loading, it is the slot the spinner takes over.

```gts preview
import { Button } from 'frontile';
import { ShareIcon } from 'site/components/icons';

<template>
  <Button>
    <:icon><ShareIcon /></:icon>
    <:default>Share</:default>
  </Button>
</template>
```

## Label with a Unit

A label can carry a smaller trailing unit — a price suffix like `/mo`, a count,
or an abbreviation. The label keeps the bold `strong` text role that the size
variant already applies; the unit uses the regular-weight `body` role, two steps
down the scale.

Wrap the pair so the unit sits tight against the label: the button's own `gap`
spaces the icon slots, while the wrapper's narrower gap spaces label from unit.

```gts preview
import { Button } from 'frontile';
import { StarIcon } from 'site/components/icons';

<template>
  <div class='flex flex-wrap items-center gap-3'>
    <Button @color='primary'>
      <span class='inline-flex items-center gap-1'>
        Upgrade
        <span class='font-body text-body-xs'>/mo</span>
      </span>
    </Button>

    <Button @variant='outline' @color='neutral'>
      <StarIcon />
      <span class='inline-flex items-center gap-1'>
        Button
        <span class='font-body text-body-xs'>/mo</span>
      </span>
      <StarIcon />
    </Button>
  </div>
</template>
```

The unit token pairs with the label token the size variant sets, so it needs to
change with `@size`:

| `@size` | label (automatic) | unit            | wrapper gap |
| ------- | ----------------- | --------------- | ----------- |
| `xs`    | `text-strong-sm`  | `text-body-3xs` | `gap-0.5`   |
| `sm`    | `text-strong-md`  | `text-body-2xs` | `gap-0.5`   |
| `md`    | `text-strong-lg`  | `text-body-xs`  | `gap-1`     |
| `lg`    | `text-strong-xl`  | `text-body-sm`  | `gap-1`     |
| `xl`    | `text-strong-2xl` | `text-body-md`  | `gap-1`     |
| `2xl`   | `text-strong-3xl` | `text-body-lg`  | `gap-1.5`   |

```gts preview
import { Button } from 'frontile';

<template>
  <div class='flex flex-wrap items-center gap-3'>
    <Button @size='sm' @color='primary'>
      <span class='inline-flex items-center gap-0.5'>
        $9
        <span class='font-body text-body-2xs'>/mo</span>
      </span>
    </Button>
    <Button @color='primary'>
      <span class='inline-flex items-center gap-1'>
        $19
        <span class='font-body text-body-xs'>/mo</span>
      </span>
    </Button>
    <Button @size='lg' @color='primary'>
      <span class='inline-flex items-center gap-1'>
        $29
        <span class='font-body text-body-sm'>/mo</span>
      </span>
    </Button>
    <Button @size='2xl' @color='primary'>
      <span class='inline-flex items-center gap-1.5'>
        $99
        <span class='font-body text-body-lg'>/mo</span>
      </span>
    </Button>
  </div>
</template>
```

## Disabled

```gts preview
import { Button } from 'frontile';

<template>
  <div class='flex flex-wrap items-center gap-3'>
    <Button @color='neutral' disabled>Default</Button>
    <Button @color='primary' disabled>Primary</Button>
    <Button @color='secondary' disabled>Secondary</Button>
    <Button @color='tertiary' disabled>Tertiary</Button>
    <Button @color='success' disabled>Success</Button>
    <Button @color='warning' disabled>Warning</Button>
    <Button @color='danger' disabled>Danger</Button>
  </div>
</template>
```

## Loading

`@isLoading` renders a spinner and disables the button.

```gts preview
import { Button } from 'frontile';

<template>
  <div class='flex flex-wrap items-center gap-3'>
    <Button @isLoading={{true}}>Save</Button>
    <Button @variant='outline' @isLoading={{true}}>Save</Button>
    <Button @color='danger' @isLoading={{true}}>Delete</Button>
  </div>
</template>
```

Use the `loading` block to swap the label while the action is in flight.

```gts preview
import { Button } from 'frontile';

<template>
  <Button @isLoading={{true}}>
    <:default>Save</:default>
    <:loading>Saving…</:loading>
  </Button>
</template>
```

The spinner takes the place of the `icon` block, so a button with an icon keeps
its width while loading.

```gts preview
import { Button } from 'frontile';
import { ShareIcon } from 'site/components/icons';

<template>
  <div class='flex flex-wrap items-center gap-3'>
    <Button>
      <:icon><ShareIcon /></:icon>
      <:default>Share</:default>
    </Button>
    <Button @isLoading={{true}}>
      <:icon><ShareIcon /></:icon>
      <:default>Share</:default>
    </Button>
  </div>
</template>
```

`@iconPlacement='end'` moves both the icon and the spinner after the label.

```gts preview
import { Button } from 'frontile';
import { ShareIcon } from 'site/components/icons';

<template>
  <div class='flex flex-wrap items-center gap-3'>
    <Button @iconPlacement='end'>
      <:icon><ShareIcon /></:icon>
      <:default>Share</:default>
    </Button>
    <Button @iconPlacement='end' @isLoading={{true}}>
      <:icon><ShareIcon /></:icon>
      <:default>Share</:default>
    </Button>
  </div>
</template>
```

## Renderless Button

Sometimes a button element is not ideal for a given case, but the same styles are still desired.
Frontile provides the option to disable rendering the `button` element, but instead it yields back an object with
the class names it would use.

```gts preview
import { Button } from 'frontile';

<template>
  <Button @isRenderless={{true}} as |btn|>
    <a href='#composition' class={{btn.classNames}}>Jump to composition</a>
  </Button>
</template>
```

## Composition

You can compose variant with colors and more to create the button that best fits your needs.

```gts preview
import { Button } from 'frontile';

<template>
  <Button @variant='outline' @color='primary'>Button</Button>
  <Button @variant='plain' @color='warning'>Button</Button>
  <Button @size='xs' @color='danger'>Button</Button>
</template>
```

## Customization

You can use TailwindCSS classes to customize even further.

```gts preview
import { Button } from 'frontile';

<template>
  <Button @variant='outline' @color='primary' @class='px-20 py-2 italic'>
    Button
  </Button>
</template>
```

Here is another example using TailwindCSS classes with the `custom` variant.

```gts preview
import { Button } from 'frontile';

<template>
  <Button
    @variant='custom'
    class='rounded-none border-teal-600 bg-teal-100 text-teal-900 hover:bg-teal-200 hover:text-teal-700 dark:border-teal-300 dark:bg-teal-950 dark:text-teal-100 dark:hover:bg-teal-900 dark:hover:text-teal-50 border-dashed'
  >
    Button
  </Button>
</template>
```

Note that here we used the HTML attribute `class`, instead of the argument `@class`.
Using the class attribute will just append the class names passed in, while the
argument `@class` will override and merge TailwindCSS class names.

## Press Interactions

The Button component supports press interactions through the `@onPress` callback, which provides cross-platform support for mouse, touch, and keyboard events.

```gts preview
import { Button } from 'frontile';
import Component from '@glimmer/component';
import { tracked } from '@glimmer/tracking';

export default class ButtonPressExample extends Component {
  @tracked pressCount = 0;

  handlePress = () => {
    this.pressCount++;
  };

  <template>
    <div class='flex items-center space-x-4'>
      <Button @onPress={{this.handlePress}}>
        Press me! ({{this.pressCount}})
      </Button>
      <p>Button has been pressed {{this.pressCount}} times</p>
    </div>
  </template>
}
```

### Press State

Buttons automatically track their pressed state and add a `data-pressed` attribute when being pressed, which can be used for styling:

```css
button[data-pressed='true'] {
  transform: scale(0.95);
  transition: transform 0.1s ease;
}
```

## Accessibility

`Button` renders a native `<button type="button">`, so focus order, the disabled
state, and Enter/Space activation come from the platform. What follows is what
you still have to get right.

| Key     | Behaviour                                                |
| ------- | -------------------------------------------------------- |
| `Tab`   | Moves focus to the button. Disabled buttons are skipped. |
| `Enter` | Activates the button, firing `@onPress`.                 |
| `Space` | Activates the button, firing `@onPress`.                 |

### Use `@onPress`, not a `click` listener

The `press` modifier calls `preventDefault()` on Enter and Space so the two keys
behave identically across elements. A side effect is that the browser never
synthesises the `click` event it would normally follow with — so a
`{{on "click"}}` handler on a default `@type='button'` fires for the mouse but
**not** for the keyboard:

```gts preview collapsible
import { Button } from 'frontile';
import Component from '@glimmer/component';
import { tracked } from '@glimmer/tracking';
import { on } from '@ember/modifier';

export default class KeyboardParityExample extends Component {
  @tracked pressCount = 0;
  @tracked clickCount = 0;

  handlePress = () => {
    this.pressCount++;
  };

  handleClick = () => {
    this.clickCount++;
  };

  <template>
    <div class='flex flex-wrap items-center gap-4'>
      <Button @color='primary' @onPress={{this.handlePress}}>
        @onPress ({{this.pressCount}})
      </Button>
      <Button @variant='outline' {{on 'click' this.handleClick}}>
        click listener ({{this.clickCount}})
      </Button>
      <p class='text-neutral'>
        Activate each with the mouse, then again with
        <kbd>Tab</kbd>
        +
        <kbd>Enter</kbd>. Only the first counter moves the second time.
      </p>
    </div>
  </template>
}
```

`@type='submit'` and `@type='reset'` are exempt — the default is preserved
there, so a button inside a form still submits or resets it from the keyboard.

### Buttons with no text

An icon on its own leaves the button unnamed. Give it an `aria-label` — it
passes through to the element via `...attributes`:

```gts preview
import { Button } from 'frontile';
import { ShareIcon } from 'site/components/icons';

<template>
  <Button @color='primary' aria-label='Share this page'>
    <ShareIcon />
  </Button>
</template>
```

### Disabling

There is no `@isDisabled` argument. Pass the plain HTML `disabled` attribute, as
the [Disabled](#disabled) demo above does; it removes the button from the tab
order and is what assistive technology reports.

### Loading

`@isLoading` sets the plain HTML `disabled` attribute, which has two
consequences worth designing around.

**Focus is lost.** A button that disables itself mid-press drops focus to
`<body>`, so keyboard and screen reader users lose their place and hear
nothing. Put the outcome of the action in a live region, or leave the button
enabled and guard against re-entry inside your handler.

**The button widens** by the spinner plus the gap, unless it has an `icon`
block for the spinner to take over. Either use the `icon` block, or set a
`min-w-*` class on buttons that toggle between states.

**A plain-content icon is not replaced.** The spinner only swaps in for an
`icon` block (see [With Icons](#with-icons)); an icon passed as ordinary
content — `<Button @isLoading={{true}}><DownloadIcon /> Download</Button>` —
stays on screen alongside the spinner, rendering both. If you want the
loading-swap behavior, move the icon into `<:icon>`.

### Renderless buttons

`@isRenderless` hands back only class names, so every semantic the `<button>`
provided becomes yours. An `<a href>` is already focusable and activates on
Enter; anything else — a `<div>`, a `<span>` — needs `role='button'`,
`tabindex='0'`, and its own key handling. Prefer a real `<button>` or `<a>` over
recreating that.

`@isRenderless` yields only to the default block — `<:icon>` and `<:loading>`
are ignored, because there is no element for the component to compose. The
yielded hash still carries `isLoading`, so you can branch on it yourself.

## API

### Button

**Element:** `HTMLButtonElement`

**Arguments**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `appearance` | `'soft' \| 'custom' \| 'default' \| 'outlined' \| 'minimal' \| 'tonal'` | - | **Deprecated.** Use `variant`. `default` is now `solid`, `outlined` is `outline`, and `minimal` is `plain`. |
| `class` | `string` | - | Custom class name, it will override the default ones using Tailwind Merge library. |
| `color` | `'neutral' \| 'primary' \| 'secondary' \| 'tertiary' \| 'success' \| 'warning' \| 'danger'` | - | The color of the button |
| `iconPlacement` | `'start' \| 'end'` | `'start'` | Which side the icon block — and the loading spinner that replaces it — sits on. |
| `intent` | `'default' \| 'primary' \| 'secondary' \| 'tertiary' \| 'success' \| 'warning' \| 'danger'` | - | **Deprecated.** Use `color`. `default` is now `neutral`. |
| `isInGroup` | `boolean` | - | If button is part of a group. Most of the time, this is automatically set when using the ButtonGroup component. |
| `isLoading` | `boolean` | `false` | Renders a spinner in place of the icon and disables the button. |
| `isRenderless` | `boolean` | - | Disable rendering the button element. It yields an object with classNames instead. |
| `onPress` | `(event: PressEvent) => void` | - | Callback for when the button is pressed. |
| `size` | `'sm' \| 'md' \| 'lg' \| 'xs' \| 'xl' \| '2xl'` | - | The size of the button |
| `type` | `'button' \| 'submit' \| 'reset'` | `'button'` | The HTML type of the button |
| `variant` | `'solid' \| 'soft' \| 'subtle' \| 'outline' \| 'ghost' \| 'plain' \| 'custom'` | `'solid'` | The button variant. |

**Blocks**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `default *` | `[{ classNames: string; isLoading: boolean; }]` | - |  |
| `icon` | `[]` | - |  |
| `loading` | `[]` | - |  |

---

# Chip

Source: /docs/components/buttons/chip.md

# Chip

Chips are compact elements that represent an input, attribute, or action — a
filter that has been applied, a tag on a record, a value selected in a
multi-select field.

## Import

```js
import { Chip } from 'frontile';
```

## Usage

```gts preview
import { Chip } from 'frontile';

<template>
  <Chip>Chip</Chip>
</template>
```

## Chip Variants

`solid` is a filled chip, `outline` draws the color as a border on the
page background, and `soft` is a tinted surface with color-tinted text.

```gts preview
import { Chip } from 'frontile';

<template>
  <div class='flex flex-wrap items-center gap-3'>
    <Chip @variant='solid'>Solid</Chip>
    <Chip @variant='outline'>Outline</Chip>
    <Chip @variant='soft'>Soft</Chip>
  </div>
</template>
```

## Chip Colors

Every color is available in every variant. The label on each row is the
`@variant` value; the chip labels are the `@color` values.

```gts preview collapsible
import { Chip } from 'frontile';
import { array } from '@ember/helper';

const colors = [
  'neutral',
  'primary',
  'secondary',
  'tertiary',
  'success',
  'warning',
  'danger'
];

<template>
  <div class='flex flex-col gap-6'>
    {{#each (array 'solid' 'outline' 'soft') as |variant|}}
      <div>
        <p class='font-code text-code-sm text-neutral-strong mb-2'>
          @variant='{{variant}}'
        </p>
        <div class='flex flex-wrap items-center gap-3'>
          {{#each colors as |color|}}
            <Chip @variant={{variant}} @color={{color}}>
              {{color}}
            </Chip>
          {{/each}}
        </div>
      </div>
    {{/each}}
  </div>
</template>
```

## Chip Sizes

```gts preview
import { Chip } from 'frontile';

<template>
  <div class='flex flex-wrap items-center gap-3'>
    <Chip @size='xs'>Chip xs</Chip>
    <Chip @size='sm'>Chip sm</Chip>
    <Chip @size='md'>Chip md</Chip>
    <Chip @size='lg'>Chip lg</Chip>
  </div>
</template>
```

`xs` is for dense layouts such as table cells, list rows, and chips inside a form
field. It uses the same text size as `sm` and gets smaller by dropping height and
padding, because 12px is about the smallest a label stays readable. Its close
button is small. If removing the chip is the main action, use `sm` or larger.

The dot and the close button scale with the chip, so a size change does not need
any other adjustment.

```gts preview
import { Chip } from 'frontile';
import { array } from '@ember/helper';

const noop = (): void => {};

<template>
  <div class='flex flex-col gap-6'>
    {{#each (array 'solid' 'outline' 'soft') as |variant|}}
      <div>
        <p class='font-code text-code-sm text-neutral-strong mb-2'>
          @variant='{{variant}}'
        </p>
        <div class='flex flex-wrap items-center gap-3'>
          {{#each (array 'xs' 'sm' 'md' 'lg') as |size|}}
            <Chip
              @variant={{variant}}
              @color='primary'
              @size={{size}}
              @withDot={{true}}
              @onClose={{noop}}
              @closeButtonTitle='Remove {{size}} chip'
            >
              {{size}}
            </Chip>
          {{/each}}
        </div>
      </div>
    {{/each}}
  </div>
</template>
```

## Chip Radius

`full` is the default. Use a smaller radius when chips sit alongside other
squared-off controls.

```gts preview
import { Chip } from 'frontile';
import { array } from '@ember/helper';

<template>
  <div class='flex flex-wrap items-center gap-3'>
    {{#each (array 'none' 'sm' 'lg' 'full') as |radius|}}
      <Chip @variant='outline' @color='primary' @radius={{radius}}>
        {{radius}}
      </Chip>
    {{/each}}
  </div>
</template>
```

## Chip with Dots

`@withDot` adds a small color-tinted dot before the content — useful when the
chip stands for a status and the color needs to read at a glance.

```gts preview collapsible
import { Chip } from 'frontile';
import { array } from '@ember/helper';

const colors = [
  'neutral',
  'primary',
  'secondary',
  'tertiary',
  'success',
  'warning',
  'danger'
];

<template>
  <div class='flex flex-col gap-6'>
    {{#each (array 'solid' 'outline' 'soft') as |variant|}}
      <div>
        <p class='font-code text-code-sm text-neutral-strong mb-2'>
          @variant='{{variant}}'
        </p>
        <div class='flex flex-wrap items-center gap-3'>
          {{#each colors as |color|}}
            <Chip @variant={{variant}} @color={{color}} @withDot={{true}}>
              {{color}}
            </Chip>
          {{/each}}
        </div>
      </div>
    {{/each}}
  </div>
</template>
```

## Close Button

Passing `@onClose` makes the close button visible.

```gts preview collapsible
import { Chip } from 'frontile';
import { array, concat } from '@ember/helper';

const colors = [
  'neutral',
  'primary',
  'secondary',
  'tertiary',
  'success',
  'warning',
  'danger'
];

const noop = (): void => {};

<template>
  <div class='flex flex-col gap-6'>
    {{#each (array 'solid' 'outline' 'soft') as |variant|}}
      <div>
        <p class='font-code text-code-sm text-neutral-strong mb-2'>
          @variant='{{variant}}'
        </p>
        <div class='flex flex-wrap items-center gap-3'>
          {{#each colors as |color|}}
            <Chip
              @variant={{variant}}
              @color={{color}}
              @onClose={{noop}}
              @closeButtonTitle={{concat 'Remove ' color}}
            >
              {{color}}
            </Chip>
          {{/each}}
        </div>
      </div>
    {{/each}}
  </div>
</template>
```

### Dot and Close Button Together

```gts preview collapsible
import { Chip } from 'frontile';
import { array, concat } from '@ember/helper';

const colors = [
  'neutral',
  'primary',
  'secondary',
  'tertiary',
  'success',
  'warning',
  'danger'
];

const noop = (): void => {};

<template>
  <div class='flex flex-col gap-6'>
    {{#each (array 'solid' 'outline' 'soft') as |variant|}}
      <div>
        <p class='font-code text-code-sm text-neutral-strong mb-2'>
          @variant='{{variant}}'
        </p>
        <div class='flex flex-wrap items-center gap-3'>
          {{#each colors as |color|}}
            <Chip
              @variant={{variant}}
              @color={{color}}
              @withDot={{true}}
              @onClose={{noop}}
              @closeButtonTitle={{concat 'Remove ' color}}
            >
              {{color}}
            </Chip>
          {{/each}}
        </div>
      </div>
    {{/each}}
  </div>
</template>
```

### Naming the close button

Every close button is announced as "Close" unless you say otherwise, which does
not tell anyone _what_ is being removed. When several closable chips sit together
— the usual case, since chips represent a set — give each one a
`@closeButtonTitle` naming its own value:

```gts preview
import Component from '@glimmer/component';
import { tracked } from '@glimmer/tracking';
import { concat, fn } from '@ember/helper';
import { Chip } from 'frontile';

export default class Example extends Component {
  @tracked filters = ['Fiber', 'Metro', 'Wholesale'];

  remove = (name: string): void => {
    this.filters = this.filters.filter((filter) => filter !== name);
  };

  <template>
    <div class='flex flex-wrap items-center gap-2'>
      {{#each this.filters as |filter|}}
        <Chip
          @variant='soft'
          @color='primary'
          @onClose={{fn this.remove filter}}
          @closeButtonTitle={{concat 'Remove ' filter}}
        >
          {{filter}}
        </Chip>
      {{else}}
        <p class='text-neutral'>All filters removed.</p>
      {{/each}}
    </div>
  </template>
}
```

### Keeping the close button out of the tab order

`@closeButtonTabIndex="-1"` makes a chip's close button a pointer-only affordance.
Reach for it when chips sit _inside_ another control — a multi-select field, say —
where each chip would otherwise cost a Tab stop before the control itself is
reachable. `Select` does exactly this in chips mode. If you do it, you owe keyboard
users another way to remove a chip (`Select` uses `Backspace` on the field); leaving
them with no route at all is worse than the extra tab stops.

## Disabled

`@isDisabled` dims the chip and disables its close button, so the value can no
longer be removed.

```gts preview collapsible
import { Chip } from 'frontile';
import { array } from '@ember/helper';

const colors = [
  'neutral',
  'primary',
  'secondary',
  'tertiary',
  'success',
  'warning',
  'danger'
];

const noop = (): void => {};

<template>
  <div class='flex flex-col gap-6'>
    {{#each (array 'solid' 'outline' 'soft') as |variant|}}
      <div>
        <p class='font-code text-code-sm text-neutral-strong mb-2'>
          @variant='{{variant}}'
        </p>
        <div class='flex flex-wrap items-center gap-3'>
          {{#each colors as |color|}}
            <Chip
              @variant={{variant}}
              @color={{color}}
              @withDot={{true}}
              @onClose={{noop}}
              @isDisabled={{true}}
            >
              {{color}}
            </Chip>
          {{/each}}
        </div>
      </div>
    {{/each}}
  </div>
</template>
```

## Customizing

You can also use TailwindCSS classes to customize even further.

```gts preview
import { Chip } from 'frontile';

<template>
  <Chip @variant='outline' @color='primary' @class='px-20 py-2 italic'>
    Chip
  </Chip>
</template>
```

The argument `@class` overrides and merges TailwindCSS class names, while the HTML
attribute `class` just appends the class names passed in.

## Accessibility

A `Chip` is a `<div>` holding text — it has no role of its own, because a chip is
not one thing. What it means depends on what you are using it for, and that
determines what you owe it:

- **As a label or attribute** (a status, a tag, a count) it is ordinary text.
  Nothing extra is needed. Do not rely on `@color` or `@withDot` alone to carry
  the meaning: `@color='danger'` reads as "failed" to a sighted user and as
  nothing at all to a screen reader, so keep the word in the content.
- **As a removable value** — with `@onClose` — the close button is the only
  interactive part. It is a real `<button>`, reached with `Tab` and activated
  with `Enter` or `Space`, and it needs a name that identifies the chip; see
  [above](#naming-the-close-button).
- **As something clickable in its own right**, a chip is the wrong element. Put a
  `Button` or a link inside it, or use a `Button` instead — attaching a click
  handler to the `<div>` leaves it unfocusable and unannounced.

When chips represent a set that changes, the container should say so, or removals
happen silently for anyone not watching the screen. A `role='list'` wrapper gives
the set a size and position; an `aria-live` region announces the change:

```gts preview collapsible
import Component from '@glimmer/component';
import { tracked } from '@glimmer/tracking';
import { concat, fn } from '@ember/helper';
import { Chip } from 'frontile';

export default class Example extends Component {
  @tracked tags = ['Design', 'Docs', 'Testing'];
  @tracked announcement = '';

  remove = (name: string): void => {
    this.tags = this.tags.filter((tag) => tag !== name);
    this.announcement = `${name} removed. ${this.tags.length} remaining.`;
  };

  <template>
    <ul role='list' aria-label='Tags' class='flex flex-wrap items-center gap-2'>
      {{#each this.tags as |tag|}}
        <li>
          <Chip
            @variant='outline'
            @onClose={{fn this.remove tag}}
            @closeButtonTitle={{concat 'Remove ' tag}}
          >
            {{tag}}
          </Chip>
        </li>
      {{/each}}
    </ul>

    <p aria-live='polite' class='text-neutral mt-3'>{{this.announcement}}</p>
  </template>
}
```

`@isDisabled` does not hide the chip from assistive technology — the text is
still read, which is usually what you want for a value that is present but
locked.

## API

### Chip

**Element:** `HTMLDivElement`

**Arguments**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `appearance` | `'default' \| 'outlined' \| 'faded'` | - | **Deprecated.** Use `variant`. `default` is now `solid`, `outlined` is `outline`, and `faded` is `soft`. |
| `class` | `string` | - | Custom class name, it will override the default ones using Tailwind Merge library. |
| `closeButtonTabIndex` | `string \| number` | `undefined (the close button is a normal tab stop)` | tabindex for the close button. Set to -1 when chips sit inside another control (a multi-select field, say) and the close button should stay a pointer affordance: every chip would otherwise cost a Tab stop before the control itself is reached. Whoever does this owes keyboard users another way to remove a chip. |
| `closeButtonTitle` | `string` | `'Close'` | The accessible name of the close button. Every close button would otherwise be announced as just "Close", which does not say what is being removed — worth setting when several chips sit together. |
| `color` | `'neutral' \| 'primary' \| 'secondary' \| 'tertiary' \| 'success' \| 'warning' \| 'danger'` | - | The color of the chip. |
| `intent` | `'default' \| 'primary' \| 'secondary' \| 'tertiary' \| 'success' \| 'warning' \| 'danger'` | - | **Deprecated.** Use `color`. `default` is now `neutral`. |
| `isDisabled` | `boolean` | `false` | Dims the chip and disables its close button, if any. |
| `onClose` | `() => void` | - | Function to be called when clicking on the close button. If you pass this argument, the close button will be visible. |
| `radius` | `'sm' \| 'lg' \| 'none' \| 'full'` | `'full'` | The border radius of the chip |
| `size` | `'sm' \| 'md' \| 'lg'` | `'md'` | The size of the chip |
| `variant` | `'solid' \| 'soft' \| 'outline'` | `'solid'` | The chip variant. |
| `withDot` | `boolean` | `false` | Adds a dot before the content, colored by @color. On the solid variant the dot takes the chip's text color, since the chip's background is already the chip's color. |

**Blocks**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `default *` | `[]` | - |  |

---

# CloseButton

Source: /docs/components/buttons/close-button.md

# CloseButton

This component provides the commonly used Close Button with an icon.

It is also used under other components in Frontile, for example `Modal` and `Drawer`

## Import

```js
import { CloseButton } from 'frontile';
```

## Usage

```gts preview
import { CloseButton } from 'frontile';

<template><CloseButton /></template>
```

## Sizes

```gts preview
import { CloseButton } from 'frontile';

<template>
  <div class='flex items-center space-x-2'>
    <CloseButton @size='xs' />
    <CloseButton @size='sm' />
    <CloseButton @size='md' />
    <CloseButton @size='lg' />
    <CloseButton @size='xl' />
  </div>
</template>
```

## Press Interactions

The CloseButton component supports press interactions through the `@onPress` callback, providing cross-platform support for mouse, touch, and keyboard events.

```gts preview
import { CloseButton } from 'frontile';
import Component from '@glimmer/component';
import { tracked } from '@glimmer/tracking';

export default class CloseButtonExample extends Component {
  @tracked isVisible = true;

  handleClose = () => {
    this.isVisible = false;
    // Reset after a delay for demo purposes
    setTimeout(() => {
      this.isVisible = true;
    }, 2000);
  };

  <template>
    <div class='flex items-center space-x-4'>
      {{#if this.isVisible}}
        <div
          class='bg-primary-soft border border-primary rounded p-4 flex items-center justify-between'
        >
          <span>This is a dismissible message</span>
          <CloseButton @onPress={{this.handleClose}} />
        </div>
      {{else}}
        <p class='text-neutral'>Message dismissed (will reappear in 2 seconds)</p>
      {{/if}}
    </div>
  </template>
}
```

### Press State

CloseButtons automatically track their pressed state and add a `data-pressed` attribute when being pressed, which can be used for styling:

```css
button[data-pressed='true'] {
  transform: scale(0.95);
  transition: transform 0.1s ease;
}
```

## Accessibility

The icon is `aria-hidden`, and the accessible name comes from `@title` rendered
inside a [`VisuallyHidden`](/docs/components/utilities/visually-hidden) — so the
button always has a name, defaulting to "Close", without any visible text.

| Key     | Behaviour                                                            |
| ------- | -------------------------------------------------------------------- |
| `Tab`   | Moves focus to the button. `disabled` removes it from the tab order. |
| `Enter` | Activates it, firing `@onPress`.                                     |
| `Space` | Activates it, firing `@onPress`.                                     |

Because the `press` modifier calls `preventDefault()` on Enter and Space, the
browser never synthesises a `click` — so use `@onPress` rather than a
`{{on "click"}}` handler, or keyboard users get nothing. This is the same reason
`@onClick` is deprecated.

### Set `@title` when there is more than one

"Close" is a fine name for the single dismiss button on a modal. It is a poor one
in a list, where every button is announced identically and none of them says what
it closes. Name the thing:

```gts preview
import Component from '@glimmer/component';
import { tracked } from '@glimmer/tracking';
import { concat, fn } from '@ember/helper';
import { CloseButton } from 'frontile';

export default class Example extends Component {
  @tracked messages = ['Deploy finished', 'Backup complete', 'Invite sent'];

  dismiss = (message: string): void => {
    this.messages = this.messages.filter((item) => item !== message);
  };

  <template>
    <ul role='list' aria-label='Notifications' class='flex flex-col gap-2'>
      {{#each this.messages as |message|}}
        <li
          class='bg-surface-card border border-neutral-soft rounded flex items-center justify-between gap-4 p-3'
        >
          <span>{{message}}</span>
          <CloseButton
            @title={{concat 'Dismiss: ' message}}
            @onPress={{fn this.dismiss message}}
          />
        </li>
      {{else}}
        <li class='text-neutral'>Nothing left to dismiss.</li>
      {{/each}}
    </ul>
  </template>
}
```

Passing a block replaces the default icon, and with it the `aria-hidden` that
kept the icon out of the accessible name. Mark your own icon `aria-hidden='true'`
so the name stays whatever `@title` says:

```gts preview
import { CloseButton } from 'frontile';
import { DeleteIcon } from 'site/components/icons';

<template>
  <CloseButton @title='Delete draft' as |iconClass|>
    <DeleteIcon class={{iconClass}} aria-hidden='true' />
  </CloseButton>
</template>
```

Removing something on press leaves focus on a button that no longer exists, which
drops it back to the top of the document. Move focus to the next item or to the
container that held the removed one.

## Migration from onClick

If you're currently using `@onClick`, you should migrate to `@onPress` for better cross-platform support:

```js
// ❌ Deprecated - will show a deprecation warning
<CloseButton @onClick={{this.handleClick}} />

// ✅ Recommended - better cross-platform support
<CloseButton @onPress={{this.handlePress}} />
```

The `@onClick` argument is still supported, but has been deprecated since v0.17
and will be removed in a future release. `@onPress` covers the same cases and
more:

- Better touch device support
- Automatic keyboard accessibility
- Consistent behavior across all input methods
- Enhanced pointer event handling

## API

### CloseButton

**Element:** `HTMLButtonElement`

**Arguments**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `class` | `string` | - | Additional class for close button element |
| `onClick` | `(event: Event) => void` | - | **Deprecated.** Use onPress instead for better cross-platform support Deprecated: The function to call when button is clicked |
| `onPress` | `(event: PressEvent) => void` | - | The function to call when button is pressed |
| `size` | `'sm' \| 'md' \| 'lg' \| 'xs' \| 'xl'` | `'lg'` | The icon size |
| `title` | `string` | `'Close'` | The title of the close button |
| `variant` | `'soft' \| 'subtle' \| 'ghost' \| 'transparent'` | `'ghost' `transparent` and `subtle` are` | **Deprecated.** — use `ghost` and `soft` instead. |

**Blocks**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `default *` | `[string]` | - |  |

---

# SegmentedControl

Source: /docs/components/buttons/segmented-control.md

# SegmentedControl

A row (or column) of mutually exclusive options with a single indicator that
slides between them. Use it in place of a small `RadioGroup` or a set of
`ToggleButton`s whenever the choice is small, fixed, and always visible — a
view switcher, a billing period, a density setting.

## Import

```js
import { SegmentedControl } from 'frontile';
```

## Usage

`@defaultValue` picks the item that starts selected and the control tracks the
rest itself, so the shortest working control needs no state and no handler.
Click between the items below: the indicator slides.

```gts preview
import { SegmentedControl } from 'frontile';

<template>
  <SegmentedControl @defaultValue='week' aria-label='Date range' as |Ctl|>
    <Ctl.Item @value='day'>Day</Ctl.Item>
    <Ctl.Item @value='week'>Week</Ctl.Item>
    <Ctl.Item @value='month'>Month</Ctl.Item>
  </SegmentedControl>
</template>
```

## Controlled and uncontrolled

The mode is decided by whether `@value` is _passed_, not by what it holds.
Omit the argument entirely and the control is uncontrolled; write it at all —
including `@value={{undefined}}`, or `@value={{this.selection}}` where
`selection` happens to be `undefined` — and it is controlled. That is what lets
a controlled control start with nothing selected and, later, be cleared back to
nothing by assigning `undefined`.

Without `@value` the control is uncontrolled. `@defaultValue` seeds the initial
selection, the control keeps the current one internally, and `@onChange` still
fires on every pick — so you can observe the value without having to own it.
That is the right default for a control whose selection nothing else drives.

Passing `@value` makes it controlled: the selection then only ever reflects what
you pass, so pair it with `@onChange` and assign the new value back to your own
state. Reach for it when something outside the control also sets the selection —
a query parameter, a saved preference, a value you validate before accepting.
`@defaultValue` is ignored in that mode.

```gts preview
import Component from '@glimmer/component';
import { tracked } from '@glimmer/tracking';
import { SegmentedControl } from 'frontile';

export default class Example extends Component {
  @tracked range = 'week';

  onChange = (value: string): void => {
    this.range = value;
  };

  <template>
    <div class='flex flex-col items-start gap-3'>
      <SegmentedControl
        @value={{this.range}}
        @onChange={{this.onChange}}
        aria-label='Date range'
        as |Ctl|
      >
        <Ctl.Item @value='day'>Day</Ctl.Item>
        <Ctl.Item @value='week'>Week</Ctl.Item>
        <Ctl.Item @value='month'>Month</Ctl.Item>
      </SegmentedControl>

      <p class='text-body-sm text-neutral-strong'>Selected: {{this.range}}</p>
    </div>
  </template>
}
```

`@value` is compared against each item's `@value` with `===`. Object values
must be referentially stable, or every item will read as unselected; two items
that share a value both render as selected, which is useful when the same
choice has more than one entry point but otherwise worth avoiding.

## Colors

`@color` colors the selection indicator, so the selected option carries the
meaning rather than the control as a whole. `default` keeps the neutral raised
pill; the rest tint it and switch the selected label to the matching contrast
ink.

```gts preview collapsible
import { SegmentedControl } from 'frontile';

<template>
  <div class='flex flex-col items-start gap-3'>
    <SegmentedControl
      @defaultValue='week'
      @color='neutral'
      aria-label='Neutral color'
      as |Ctl|
    >
      <Ctl.Item @value='day'>Day</Ctl.Item>
      <Ctl.Item @value='week'>Week</Ctl.Item>
      <Ctl.Item @value='month'>Month</Ctl.Item>
    </SegmentedControl>
    <SegmentedControl
      @defaultValue='week'
      @color='primary'
      aria-label='Primary color'
      as |Ctl|
    >
      <Ctl.Item @value='day'>Day</Ctl.Item>
      <Ctl.Item @value='week'>Week</Ctl.Item>
      <Ctl.Item @value='month'>Month</Ctl.Item>
    </SegmentedControl>
    <SegmentedControl
      @defaultValue='week'
      @color='secondary'
      aria-label='Secondary color'
      as |Ctl|
    >
      <Ctl.Item @value='day'>Day</Ctl.Item>
      <Ctl.Item @value='week'>Week</Ctl.Item>
      <Ctl.Item @value='month'>Month</Ctl.Item>
    </SegmentedControl>
    <SegmentedControl
      @defaultValue='week'
      @color='tertiary'
      aria-label='Tertiary color'
      as |Ctl|
    >
      <Ctl.Item @value='day'>Day</Ctl.Item>
      <Ctl.Item @value='week'>Week</Ctl.Item>
      <Ctl.Item @value='month'>Month</Ctl.Item>
    </SegmentedControl>
    <SegmentedControl
      @defaultValue='week'
      @color='success'
      aria-label='Success color'
      as |Ctl|
    >
      <Ctl.Item @value='day'>Day</Ctl.Item>
      <Ctl.Item @value='week'>Week</Ctl.Item>
      <Ctl.Item @value='month'>Month</Ctl.Item>
    </SegmentedControl>
    <SegmentedControl
      @defaultValue='week'
      @color='warning'
      aria-label='Warning color'
      as |Ctl|
    >
      <Ctl.Item @value='day'>Day</Ctl.Item>
      <Ctl.Item @value='week'>Week</Ctl.Item>
      <Ctl.Item @value='month'>Month</Ctl.Item>
    </SegmentedControl>
    <SegmentedControl
      @defaultValue='week'
      @color='danger'
      aria-label='Danger color'
      as |Ctl|
    >
      <Ctl.Item @value='day'>Day</Ctl.Item>
      <Ctl.Item @value='week'>Week</Ctl.Item>
      <Ctl.Item @value='month'>Month</Ctl.Item>
    </SegmentedControl>
  </div>
</template>
```

## Sizes

```gts preview collapsible
import { SegmentedControl } from 'frontile';

<template>
  <div class='flex flex-col items-start gap-3'>
    <SegmentedControl
      @defaultValue='week'
      @size='sm'
      aria-label='Small'
      as |Ctl|
    >
      <Ctl.Item @value='day'>Day</Ctl.Item>
      <Ctl.Item @value='week'>Week</Ctl.Item>
      <Ctl.Item @value='month'>Month</Ctl.Item>
    </SegmentedControl>
    <SegmentedControl
      @defaultValue='week'
      @size='md'
      aria-label='Medium'
      as |Ctl|
    >
      <Ctl.Item @value='day'>Day</Ctl.Item>
      <Ctl.Item @value='week'>Week</Ctl.Item>
      <Ctl.Item @value='month'>Month</Ctl.Item>
    </SegmentedControl>
    <SegmentedControl
      @defaultValue='week'
      @size='lg'
      aria-label='Large'
      as |Ctl|
    >
      <Ctl.Item @value='day'>Day</Ctl.Item>
      <Ctl.Item @value='week'>Week</Ctl.Item>
      <Ctl.Item @value='month'>Month</Ctl.Item>
    </SegmentedControl>
  </div>
</template>
```

## Ghost

`@variant='ghost'` removes the recessed track, leaving only the indicator
pill. Reach for it inline — next to a heading, inside a toolbar — where a
solid track would compete with the surrounding content.

```gts preview
import { SegmentedControl } from 'frontile';

<template>
  <SegmentedControl
    @defaultValue='month'
    @variant='ghost'
    aria-label='Date range'
    as |Ctl|
  >
    <Ctl.Item @value='day'>Day</Ctl.Item>
    <Ctl.Item @value='week'>Week</Ctl.Item>
    <Ctl.Item @value='month'>Month</Ctl.Item>
  </SegmentedControl>
</template>
```

## Separators

`@hasSeparators={{true}}` draws a hairline between neighbouring items. The
line on either side of the selected item is hidden, so the indicator never
appears to slide across a visible rule.

Four items with the first selected leaves two hairlines showing at rest. Click
along the row and watch them wink out as the indicator arrives and return
behind it.

```gts preview
import { SegmentedControl } from 'frontile';

<template>
  <SegmentedControl
    @defaultValue='day'
    @hasSeparators={{true}}
    aria-label='Date range'
    as |Ctl|
  >
    <Ctl.Item @value='day'>Day</Ctl.Item>
    <Ctl.Item @value='week'>Week</Ctl.Item>
    <Ctl.Item @value='month'>Month</Ctl.Item>
    <Ctl.Item @value='year'>Year</Ctl.Item>
  </SegmentedControl>
</template>
```

## Full width

`@isFullWidth={{true}}` stretches the control to its container and gives
every item equal width. Both controls below sit in the same 24rem panel: the
first shrinks to its labels, the second fills the line.

```gts preview
import { SegmentedControl } from 'frontile';

<template>
  <div
    class='flex w-96 max-w-full flex-col items-start gap-3 rounded-lg border border-neutral-soft p-4'
  >
    <SegmentedControl @defaultValue='week' aria-label='Default width' as |Ctl|>
      <Ctl.Item @value='day'>Day</Ctl.Item>
      <Ctl.Item @value='week'>Week</Ctl.Item>
      <Ctl.Item @value='month'>Month</Ctl.Item>
    </SegmentedControl>

    <SegmentedControl
      @defaultValue='week'
      @isFullWidth={{true}}
      aria-label='Full width'
      as |Ctl|
    >
      <Ctl.Item @value='day'>Day</Ctl.Item>
      <Ctl.Item @value='week'>Week</Ctl.Item>
      <Ctl.Item @value='month'>Month</Ctl.Item>
    </SegmentedControl>
  </div>
</template>
```

## Vertical

`@orientation='vertical'` stacks the items in a column and switches the arrow
keys that move between them to up/down. The track and the indicator swap their
pill radius for a rounded rectangle, and every item takes the column's full
width, so the indicator slides straight down instead of resizing at each stop —
clearest when the labels differ in length.

```gts preview
import { SegmentedControl } from 'frontile';

<template>
  <SegmentedControl
    @defaultValue='week'
    @orientation='vertical'
    aria-label='Date range'
    as |Ctl|
  >
    <Ctl.Item @value='day'>Day</Ctl.Item>
    <Ctl.Item @value='week'>This week</Ctl.Item>
    <Ctl.Item @value='month'>Month to date</Ctl.Item>
    <Ctl.Item @value='year'>Year</Ctl.Item>
  </SegmentedControl>
</template>
```

## Disabled

An individual item can be disabled with its own `@isDisabled`; keyboard
navigation skips it and it cannot be clicked. `@isDisabled` on the control
disables every item, which is why the second control below does not respond.

```gts preview
import { SegmentedControl } from 'frontile';

<template>
  <div class='flex flex-col items-start gap-3'>
    <SegmentedControl
      @defaultValue='day'
      aria-label='One item disabled'
      as |Ctl|
    >
      <Ctl.Item @value='day'>Day</Ctl.Item>
      <Ctl.Item @value='week' @isDisabled={{true}}>Week</Ctl.Item>
      <Ctl.Item @value='month'>Month</Ctl.Item>
    </SegmentedControl>

    <SegmentedControl
      @defaultValue='day'
      @isDisabled={{true}}
      aria-label='Whole control disabled'
      as |Ctl|
    >
      <Ctl.Item @value='day'>Day</Ctl.Item>
      <Ctl.Item @value='week'>Week</Ctl.Item>
    </SegmentedControl>
  </div>
</template>
```

## Icon and label

Each item yields `isSelected`, so a demo can show only an icon when unselected
and add the label once selected — a compact idle state that expands to
explain itself. Clicking between them is also the clearest look at the
indicator resizing as it moves, not just translating.

```gts preview
import { SegmentedControl } from 'frontile';
import { ViewIcon, ComponentIcon, TargetIcon } from 'site/components/icons';

<template>
  <SegmentedControl @defaultValue='list' aria-label='Layout' as |Ctl|>
    <Ctl.Item @value='list' as |item|>
      <ViewIcon />
      {{if item.isSelected 'List'}}
    </Ctl.Item>
    <Ctl.Item @value='grid' as |item|>
      <ComponentIcon />
      {{if item.isSelected 'Grid'}}
    </Ctl.Item>
    <Ctl.Item @value='target' as |item|>
      <TargetIcon />
      {{if item.isSelected 'Focus'}}
    </Ctl.Item>
  </SegmentedControl>
</template>
```

## Form mode

Passing `@name` switches items from `<button role="radio">` to `<label>`
wrapping a native, visually-hidden radio input under that name, so the
control's value submits with an ordinary form post — no `@onChange` required,
though one still fires. Keyboard behaviour also changes: a same-named native
radio group already handles arrow keys and focus on its own, so the component
steps aside rather than layering its own handling on top.

Form mode also constrains what an item's `@value` can usefully be. A form post
carries strings, so the input's `value` attribute is `String(value)` — an
object value submits as the literal `[object Object]`, and a `null` as
`"null"`. `@onChange` still receives the original typed value, so use `@name`
with string (or otherwise string-round-trippable) item values, and reach for
button mode when the values are objects.

```gts preview collapsible
import Component from '@glimmer/component';
import { tracked } from '@glimmer/tracking';
import { on } from '@ember/modifier';
import { SegmentedControl, Button } from 'frontile';

export default class Example extends Component {
  @tracked submitted = '';

  onSubmit = (event: SubmitEvent): void => {
    event.preventDefault();
    const data = new FormData(event.target as HTMLFormElement);
    this.submitted = String(data.get('range'));
  };

  <template>
    <form {{on 'submit' this.onSubmit}}>
      <SegmentedControl
        @defaultValue='week'
        @name='range'
        aria-label='Range'
        as |Ctl|
      >
        <Ctl.Item @value='day'>Day</Ctl.Item>
        <Ctl.Item @value='week'>Week</Ctl.Item>
        <Ctl.Item @value='month'>Month</Ctl.Item>
      </SegmentedControl>

      <div class='mt-3'>
        <Button @type='submit'>Submit</Button>
      </div>
    </form>

    {{#if this.submitted}}
      <p data-test-submitted>Submitted: {{this.submitted}}</p>
    {{/if}}
  </template>
}
```

> A consumer that flips `@value` asynchronously — after a network round trip,
> say — will briefly see form mode's selected-label colour flip, revert, and
> flip again while the indicator itself only moves once, at the end. This is
> a side effect of re-asserting native `checked` state a frame after the
> click so it cannot disagree with a declined or absent `@onChange`; it is
> bounded to a single frame and only visible on an async `@value`.

> Any interactive content yielded into an item ends up nested inside that
> item's `<label>` in form mode. A nested link or button becomes a
> click/activation hazard — clicking it also toggles the radio — so keep
> yielded content to text, icons, and other non-interactive markup in form
> mode.

## Custom styling

Every slot is overridable through `@classes`, so a control can be restyled well
past the built-in variants without dropping to a fork. The example below is a
brand-styled toggle: an adaptive card-coloured track with a hairline border, a
filled `primary` pill, and the brand color carried by the unselected labels
instead of neutral ink.

Three of the four pieces come from arguments rather than overrides —
`@color='primary'` fills the indicator and picks the contrast ink for the
selected label, `@isFullWidth={{true}}` stretches the control and divides it
evenly, and `@size='lg'` sets the padding. Only the track's surface and the
label treatment need `@classes`.

`text-neutral-bolder` is the strongest neutral ink, which adapts with the
theme, so the unselected labels stay legible on the card surface without
hard-coding a colour per mode. `font-label text-header-md` overrides the size variant's own
type step; because both live in Tailwind's font-size group, the `@classes`
value is the one that wins.

```gts preview
import { SegmentedControl } from 'frontile';
import { hash } from '@ember/helper';

<template>
  {{! The demo preview container is shrink-to-fit, so a width has to be
      given explicitly for `@isFullWidth` to have anything to stretch into. }}
  <div class='w-[34rem] max-w-full'>
    <SegmentedControl
      @defaultValue='resident'
      @color='primary'
      @size='lg'
      @isFullWidth={{true}}
      @classes={{hash
        base='bg-surface-card border border-neutral-soft'
        item='text-neutral-bolder font-label text-header-md'
      }}
      aria-label='Account type'
      as |Ctl|
    >
      <Ctl.Item @value='resident'>Resident</Ctl.Item>
      <Ctl.Item @value='business'>Business</Ctl.Item>
    </SegmentedControl>
  </div>
</template>
```

### Styling the selected and disabled items

`@classes.item` applies to every item, so an override that should only affect the
selected one needs a modifier. Each item publishes two data attributes for this,
in **both** rendering modes:

| Attribute       | Values               |
| --------------- | -------------------- |
| `data-selected` | `"true"` / `"false"` |
| `data-disabled` | `"true"` / `"false"` |

So `data-[selected=true]:` is the hook, and it is the same in button mode and
form mode:

```gts
@classes={{hash item='text-primary data-[selected=true]:text-on-primary'}}
```

Reach for these rather than the underlying ARIA or DOM state. Button mode's item
carries `aria-checked` and takes a native `disabled`, while form mode's item is a
`<label>` whose `sr-only` input holds both — so `aria-checked:` and `disabled:`
silently do nothing in form mode, and `has-[:checked]:` does nothing in button
mode. The data attributes are the one hook that spans both. The theme itself is
written against them for exactly this reason.

This also matches how the rest of Frontile exposes selection: `Switch`,
`Listbox`, `NativeSelect` and `Table` all publish `data-selected` the same way.

Overriding `@classes.indicator` is how a different indicator shape is built —
an underline rather than a pill, say. `SelectionIndicator`'s
[own documentation](/docs/components/utilities/selection-indicator) covers the
custom properties to position it with, and the one trap to avoid.

## Accessibility

The control renders `role="radiogroup"` with `aria-orientation`, and each
item is a radio (`role="radio"` in button mode, a native `<input
type="radio">` in form mode) — not a tab. Use `SegmentedControl` for a choice
that only changes a value; once tabs exist, prefer them for options that each
reveal their own panel.

The group needs an accessible name from the consumer: pass `aria-label` (as
every demo above does) or `aria-labelledby`.

| Key                        | Behaviour                                                            |
| -------------------------- | -------------------------------------------------------------------- |
| `Tab`                      | Moves focus to the group. Only the selected item is a tab stop.      |
| `ArrowRight` / `ArrowDown` | Moves selection to the next enabled item, wrapping at the end.       |
| `ArrowLeft` / `ArrowUp`    | Moves selection to the previous enabled item, wrapping at the start. |
| `Home` / `End`             | Moves selection to the first / last enabled item.                    |

Horizontal orientation uses left/right, vertical orientation uses up/down.
Disabled items are skipped entirely. In button mode, arrow navigation both
moves focus and selects immediately (automatic activation), matching the
native `<input type="radio">` behaviour form mode gets for free — form mode
does not implement this table itself; it defers to the browser's own
same-named-radio-group keyboard handling instead of duplicating it, since
fighting native radio semantics would only reintroduce the bugs the browser
already solved.

## API

### SegmentedControl

**Element:** `HTMLDivElement`

**Arguments**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `classes` | `SlotsToClasses<'base' \| 'item' \| 'indicator'>` | - | Class names for each slot of the component, merged with the theme's. |
| `color` | `'neutral' \| 'primary' \| 'secondary' \| 'tertiary' \| 'success' \| 'warning' \| 'danger'` | `'neutral'` | The colour applied to the selected item's indicator and label. |
| `defaultValue` | `T` | `undefined` | Sets the initially selected value when the control is used uncontrolled (that is, when @value is not provided). Ignored in controlled mode. |
| `hasSeparators` | `boolean` | `false` | Draws a hairline between neighbouring items, hidden around the selected one so the indicator never crosses a visible line. |
| `isDisabled` | `boolean` | `false` | Disables every item. Individual items can be disabled with the item's own @isDisabled. |
| `isFullWidth` | `boolean` | `false` | Stretches the control to its container and gives every item equal width. |
| `name` | `string` | - | When set, items render as <label> wrapping a native radio input under this name, so the control submits with its form. Without it the control renders buttons and reports only through onChange. |
| `onChange` | `(value: T) => void` | - | Called with the newly selected value when an item is chosen. |
| `orientation` | `'horizontal' \| 'vertical'` | `'horizontal'` | Lays the items out in a row or a column, and switches the arrow keys that move between them to match. |
| `size` | `'sm' \| 'md' \| 'lg'` | `'md'` | The size of the control, driving item padding and text size. |
| `value` | `T` | - | The currently selected value. Compared against each item's @value with ===, so object values must be referentially stable. Passing this argument at all puts the component in controlled mode -- passing it as undefined included, which is how a controlled control says "nothing is selected". The selection then only ever reflects what you pass, so pair it with @onChange and update your own state; setting it back to undefined clears the selection. Omit the argument entirely to let the control track the selection itself, seeded by @defaultValue. |
| `variant` | `'solid' \| 'ghost'` | `'solid'` | The visual style of the control's track and indicator. |

**Blocks**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `default *` | `[{ Item: SegmentedControlItem<T> (context bound); }]` | - |  |
### SegmentedControlItem

**Element:** `enum`

**Arguments**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `context *` | `Object` | - | Supplied by SegmentedControl. Not part of the public API. _(internal)_ |
| `value *` | `T` | - | The value this item represents. Selecting it calls the control's @onChange with exactly this value. |
| `class` | `string` | - | Class names appended to this item's theme classes. |
| `isDisabled` | `boolean` | `false` | Disables this item alone: it cannot be clicked and keyboard navigation skips over it. The whole control can be disabled with the control's own @isDisabled. |

**Blocks**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `default *` | `[{ isSelected: boolean; }]` | - |  |

---

# ToggleButton

Source: /docs/components/buttons/toggle-button.md

# ToggleButton

A toggle button allows to toggle a selection on or off, for example switching
between two states or modes.

Unselected, it reads as an outlined button — ink and border only. Selected, it
fills with its color and switches to the matching contrast ink; hovering
and pressing deepen that fill one step at a time, the same ramp a filled
`Button` uses, so the label stays readable in every state.

## Import

```js
import { ToggleButton } from 'frontile';
```

## Usage

```gts preview
import Component from '@glimmer/component';
import { tracked } from '@glimmer/tracking';
import { ToggleButton } from 'frontile';
import { StarIcon } from 'site/components/icons';

export default class Example extends Component {
  @tracked
  isSelected = false;

  onChange = (value: boolean): void => {
    this.isSelected = value;
  };

  <template>
    <ToggleButton
      @isSelected={{this.isSelected}}
      @onChange={{this.onChange}}
      aria-label='Favourite'
    >
      <StarIcon />
    </ToggleButton>
  </template>
}
```

## Colors

```gts preview collapsible
import Component from '@glimmer/component';
import { tracked } from '@glimmer/tracking';
import { fn } from '@ember/helper';
import { ToggleButton } from 'frontile';

export default class Example extends Component {
  @tracked
  isSelected = {
    default: false,
    primary: false,
    secondary: false,
    tertiary: false,
    success: false,
    warning: false,
    danger: false
  };

  onChange = (ty: keyof typeof this.isSelected, value: boolean): void => {
    this.isSelected[ty] = value;
    this.isSelected = { ...this.isSelected };
  };

  <template>
    {{#each-in this.isSelected as |key val|}}
      <ToggleButton
        @isSelected={{val}}
        @onChange={{(fn this.onChange key)}}
        @color={{key}}
      >
        Toggle
      </ToggleButton>
    {{/each-in}}
  </template>
}
```

## ToggleButton Sizes

```gts preview
import { ToggleButton } from 'frontile';

<template>
  <ToggleButton @size='xs'>ToggleButton</ToggleButton>
  <ToggleButton @size='sm'>ToggleButton</ToggleButton>
  <ToggleButton @size='md'>ToggleButton</ToggleButton>
  <ToggleButton @size='lg'>ToggleButton</ToggleButton>
  <ToggleButton @size='xl'>ToggleButton</ToggleButton>
</template>
```

## Disabled

You can pass the attribute `disabled` to disable a toggle button.

```gts preview
import { ToggleButton } from 'frontile';

<template>
  <div>
    <ToggleButton @color='neutral' disabled>ToggleButton</ToggleButton>
    <ToggleButton @color='primary' disabled>Primary</ToggleButton>
    <ToggleButton @color='secondary' disabled>Secondary</ToggleButton>
    <ToggleButton @color='tertiary' disabled>Tertiary</ToggleButton>
    <ToggleButton @color='success' disabled>Success</ToggleButton>
    <ToggleButton @color='warning' disabled>Warning</ToggleButton>
    <ToggleButton @color='danger' disabled>Danger</ToggleButton>
  </div>
</template>
```

## Accessibility

`ToggleButton` renders a native `<button>` carrying `aria-pressed`, which is what
turns it from a button into a toggle: assistive technology announces the label
followed by its state, and announces the change when it flips.

| Key     | Behaviour                                                |
| ------- | -------------------------------------------------------- |
| `Tab`   | Moves focus to the toggle. Disabled toggles are skipped. |
| `Enter` | Toggles it, firing `@onChange` with the new value.       |
| `Space` | Toggles it, firing `@onChange` with the new value.       |

`aria-pressed` tracks `@isSelected`, which the component does not own. Always
pair it with an `@onChange` that writes the new value back: without one the
toggle looks pressed to the eye for as long as the pointer is down, but never
reports a state change.

An icon with no text leaves the toggle unnamed, so the state is announced with
nothing to attach it to. Pass `aria-label`, as the [Usage](#usage) demo does.

The label should name the control, not the action — "Bold", not "Make bold" —
because `aria-pressed` already conveys whether it is on. A label that changes
with the state ("Mute" / "Unmute") duplicates that and contradicts it half the
time; if you want changing labels, use a plain `Button` and no `aria-pressed`.

```gts preview
import Component from '@glimmer/component';
import { tracked } from '@glimmer/tracking';
import { fn } from '@ember/helper';
import { ToggleButton } from 'frontile';

export default class Example extends Component {
  @tracked format: Record<string, boolean> = {
    Bold: false,
    Italic: false,
    Underline: false
  };

  onChange = (key: string, value: boolean): void => {
    this.format = { ...this.format, [key]: value };
  };

  <template>
    <div class='flex items-center gap-2'>
      {{#each-in this.format as |key selected|}}
        <ToggleButton
          @isSelected={{selected}}
          @onChange={{fn this.onChange key}}
          @color='primary'
        >
          {{key}}
        </ToggleButton>
      {{/each-in}}
    </div>
  </template>
}
```

Use the plain HTML `disabled` attribute to disable a toggle; there is no
`@isDisabled` argument.

## API

### ToggleButton

**Element:** `HTMLButtonElement`

**Arguments**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `appearance` | `'soft' \| 'custom' \| 'default' \| 'outlined' \| 'minimal' \| 'tonal'` | - | **Deprecated.** Use `variant`. `default` is now `solid`, `outlined` is `outline`, and `minimal` is `plain`. |
| `class` | `string` | - | Custom class name, it will override the default ones using Tailwind Merge library. |
| `color` | `'neutral' \| 'primary' \| 'secondary' \| 'tertiary' \| 'success' \| 'warning' \| 'danger'` | - | The color of the button |
| `intent` | `'default' \| 'primary' \| 'secondary' \| 'tertiary' \| 'success' \| 'warning' \| 'danger'` | - | **Deprecated.** Use `color`. `default` is now `neutral`. |
| `isInGroup` | `boolean` | - | If button is part of a group. Most of the time, this is automatically set when using the ButtonGroup component. |
| `isSelected` | `boolean` | `false` | If the button is currently selected |
| `onChange` | `(isSelected: boolean) => void` | - | Callback when the buttle is toggled |
| `size` | `'sm' \| 'md' \| 'lg' \| 'xs' \| 'xl' \| '2xl'` | - | The size of the button |
| `variant` | `'solid' \| 'soft' \| 'subtle' \| 'outline' \| 'ghost' \| 'plain' \| 'custom'` | `'solid'` | The button variant. |

**Blocks**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `default *` | `[]` | - |  |

---

# Avatar

Source: /docs/components/utilities/avatar.md

# Avatar

Represents a user by displaying their initials or an image. Supports customizable size and shape.

## Import

```js
import { Avatar } from 'frontile';
```

## Usage

### Basic

By default, Avatar displays initials derived from the `@name`, `@firstName`, and `@lastName` arguments.

```gts preview
import { Avatar } from 'frontile';

<template>
  <div class='flex items-center space-x-4 py-2'>
    <Avatar @name='Jon Snow' />
    <Avatar @firstName='Arya' @lastName='Stark' />
  </div>
</template>
```

### With an Image

If `@src` is provided, the avatar displays the image instead of initials.

```gts preview
import { Avatar } from 'frontile';

<template>
  <Avatar @src='https://i.pravatar.cc/150?img=5' @alt='Jon Snow' />
</template>
```

If the image fails to load, the avatar shows the initials instead, or an empty
plate when there is no name. A new `@src` is tried again.

```gts preview
import { Avatar } from 'frontile';

<template>
  <div class='flex items-center space-x-4 py-2'>
    <Avatar @src='https://example.invalid/missing.jpg' @name='Jon Snow' />
    <Avatar @src='https://example.invalid/missing.jpg' />
  </div>
</template>
```

### Photos

By default the image covers the avatar: it fills the whole shape and is
cropped to fit, so a photo that is not square keeps its proportions.

```gts preview
import { Avatar } from 'frontile';

<template>
  <div class='flex items-center space-x-4 py-2'>
    <Avatar @src='https://picsum.photos/id/64/300/200' @size='lg' />
    <Avatar @src='https://picsum.photos/id/64/300/200' @size='xl' />
  </div>
</template>
```

### Logos

`@fit='contain'` shows the whole image, with a small inset from the edge that
scales with `@size`. Use it for logos and wordmarks, which must not be cropped.
A square logo that brings its own background can keep the default `cover`.

```gts preview
import { Avatar } from 'frontile';

<template>
  <div class='flex items-center space-x-4 py-2'>
    <Avatar @src='/images/avatar/logo-mark.svg' @size='xl' @alt='Teal Peak' />
    <Avatar
      @src='/images/avatar/logo-wordmark.svg'
      @size='xl'
      @fit='contain'
      @alt='Northwind'
    />
  </div>
</template>
```

The avatar does not choose a background for the image. A dark logo on a
transparent background disappears against the dark-mode plate, so give it a
light background through `@classes.base`:

```gts preview
import { Avatar } from 'frontile';
import { hash } from '@ember/helper';

<template>
  <Avatar
    @src='/images/avatar/logo-wordmark.svg'
    @size='xl'
    @fit='contain'
    @alt='Northwind'
    @classes={{hash base='bg-white'}}
  />
</template>
```

### Border

Every avatar has a faint hairline just inside its edge, so its shape still
shows against a page or a photo of the same colour. Pass `@isBordered={{false}}`
to remove it.

```gts preview
import { Avatar } from 'frontile';

<template>
  <div class='flex items-center space-x-4 py-2'>
    <Avatar @name='Jon Snow' />
    <Avatar @src='https://i.pravatar.cc/150?img=5' />
    <Avatar @name='Jon Snow' @isBordered={{false}} />
    <Avatar @src='https://i.pravatar.cc/150?img=5' @isBordered={{false}} />
  </div>
</template>
```

### Different Sizes

`@size` sets the avatar's size.

```gts preview
import { Avatar } from 'frontile';

<template>
  <div class='flex items-center space-x-4 py-2'>
    <Avatar @name='Jon Snow' @size='xs' />
    <Avatar @name='Jon Snow' @size='sm' />
    <Avatar @name='Jon Snow' @size='md' />
    <Avatar @name='Jon Snow' @size='lg' />
    <Avatar @name='Jon Snow' @size='xl' />
  </div>

  <div class='flex items-center space-x-4 py-2'>
    <Avatar @size='xs' @src='https://i.pravatar.cc/150?img=1' />
    <Avatar @size='sm' @src='https://i.pravatar.cc/150?img=2' />
    <Avatar @size='md' @src='https://i.pravatar.cc/150?img=3' />
    <Avatar @size='lg' @src='https://i.pravatar.cc/150?img=4' />
    <Avatar @size='xl' @src='https://i.pravatar.cc/150?img=5' />
  </div>
</template>
```

### Shapes

`@shape` changes the avatar's shape.

```gts preview
import { Avatar } from 'frontile';

<template>
  <div class='flex items-center space-x-4 py-2'>
    <Avatar @name='Jon Snow' @shape='circle' />
    <Avatar @name='Jon Snow' @shape='square' />
  </div>
</template>
```

### Custom Styling

You can pass custom `@classes` to override styling:

```gts preview
import { Avatar } from 'frontile';
import { hash } from '@ember/helper';

<template>
  <Avatar
    @name='Jon Snow'
    @classes={{hash
      base='bg-gradient-to-r from-indigo-500 via-purple-500 to-pink-500 text-white'
    }}
  />
</template>
```

## Accessibility

An avatar is a picture of an identity, and almost always sits beside that
identity written out — a name in a row, a byline, a comment header. That makes
`@alt` a question about duplication rather than about labelling.

**Leave `@alt` off when the name is already visible.** The image then renders
with `alt=""`, marking it decorative so it is skipped rather than announced
twice, and the initials render as plain text. Both are read correctly by the
surrounding content.

```gts preview
import { Avatar } from 'frontile';

<template>
  <ul role='list' class='not-prose flex flex-col gap-3'>
    <li class='flex items-center gap-3'>
      <Avatar @src='https://i.pravatar.cc/150?img=5' />
      <span class='text-neutral-strong'>Jon Snow</span>
    </li>
    <li class='flex items-center gap-3'>
      <Avatar @name='Arya Stark' />
      <span class='text-neutral-strong'>Arya Stark</span>
    </li>
  </ul>
</template>
```

**Pass `@alt` when the avatar stands alone**, as it does in a header or a
compact list where the name is not written out. With `@alt` the initials gain
`role="img"` and are announced as that one name rather than spelled out letter
by letter.

```gts preview
import { Avatar } from 'frontile';

<template>
  <div class='flex items-center gap-4'>
    <Avatar @src='https://i.pravatar.cc/150?img=5' @alt='Jon Snow' />
    <Avatar @name='Arya Stark' @alt='Arya Stark' />
  </div>
</template>
```

The `@alt` should name the person, not the picture. "Jon Snow" is useful;
"User profile picture" and "Avatar" describe the widget, which the reader already
knows and cannot act on.

Two limits:

- **An avatar is never focusable or interactive.** It renders a `<span>` and
  takes no key handling. If the avatar should open a menu or a profile, wrap it
  in a `Button` or a link and put the accessible name there — an avatar with a
  click handler on the `<span>` cannot be reached by keyboard at all.
- **A broken `@src` falls back to the initials only when there is a name.**
  Pass `@name` (and `@alt` when the avatar stands alone) alongside `@src`, so a
  failed image still leaves something to read.

Colour alone should not carry status. An avatar tinted to mean "online" is
invisible to anyone who cannot see it, so pair the treatment with text — a
`VisuallyHidden` note or a visible label.

## API

### Avatar

**Element:** `HTMLSpanElement`

**Arguments**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `alt` | `string` | - | Alternative text for accessibility. If @src is provided, this text will be used as the alt attribute for the image. If only initials are displayed, this text will be read by screen readers. |
| `classes` | `SlotsToClasses<'name' \| 'base' \| 'img'>` | - | Custom CSS classes for styling different slots within the avatar component. |
| `firstName` | `string` | - | First name of the user, used to generate initials. If @name is not provided, initials will be generated from @firstName and @lastName. |
| `fit` | `'cover' \| 'contain'` | `'cover'` | How the image fills the avatar. cover crops the image to fill the avatar, which suits photos. contain shows the whole image, inset from the edge, which suits logos and wordmarks. |
| `isBordered` | `boolean` | `true` | Draws a faint hairline just inside the avatar's edge. Pass false to remove it. |
| `lastName` | `string` | - | Last name of the user, used to generate initials. If @name is not provided, initials will be generated from @firstName and @lastName. |
| `name` | `string` | - | Full name of the user, used to generate initials. If @firstName and @lastName are not provided, initials will be derived from this property. |
| `shape` | `'square' \| 'circle'` | `'circle'` | Defines the shape of the avatar. |
| `size` | `'sm' \| 'md' \| 'lg' \| 'xs' \| 'xl'` | `'md'` | Controls the size of the avatar. |
| `src` | `string` | - | URL of the image to be displayed in the avatar. If provided, the image will be used instead of initials. If the image fails to load, the avatar falls back to the initials, or to an empty plate when there is no name. |

---

# Collapsible

Source: /docs/components/utilities/collapsible.md

# Collapsible

An unstyled wrapper that animates its content's height and opacity as it opens
and closes. It is the primitive behind [Accordion](../disclosure/accordion) —
reach for this when you need a single expandable region and want to own the
trigger, the state and the markup yourself.

Building a set of coordinated sections? Use
[Accordion](../disclosure/accordion) instead. It handles the open-item state,
the WAI-ARIA wiring, the keyboard pattern and focus containment, all of which
are easy to get wrong by hand.

## Import

```js
import { Collapsible } from 'frontile';
```

## Usage

`@isOpen` is required and the component is fully controlled: keep the state in the parent and render your own trigger. Expanding animates height and opacity over `0.4s`, collapsing over `0.2s`; once expanded the height is set back to `auto` so content can keep growing.

```gts preview collapsible
import Component from '@glimmer/component';
import { tracked } from '@glimmer/tracking';
import { Collapsible, Button } from 'frontile';

export default class BasicCollapsible extends Component {
  @tracked isOpen = false;

  toggle = () => {
    this.isOpen = !this.isOpen;
  };

  <template>
    <div class='max-w-md'>
      <Button @color='primary' @onPress={{this.toggle}}>
        {{if this.isOpen 'Hide' 'Show'}}
        Content
      </Button>

      <Collapsible @isOpen={{this.isOpen}}>
        <div
          class='p-8 mt-4 bg-primary-subtle rounded-lg border border-primary-soft'
        >
          <p class='text-neutral-strong'>
            Lorem ipsum dolor sit amet, consectetur adipiscing elit. Suspendisse
            malesuada lacus ex, sit amet blandit leo lobortis eget.
          </p>
        </div>
      </Collapsible>
    </div>
  </template>
}
```

## Initial Height

`@initialHeight` keeps part of the content visible while collapsed — the "Read more" pattern. Opacity stays at `1` instead of fading out, and only the height animates. Include the unit in the value (`80px`, `5rem`) — a bare number isn't a valid CSS height and is ignored.

```gts preview collapsible
import Component from '@glimmer/component';
import { tracked } from '@glimmer/tracking';
import { Collapsible, Button } from 'frontile';

export default class PreviewCollapsible extends Component {
  @tracked isOpen = false;

  toggle = () => {
    this.isOpen = !this.isOpen;
  };

  <template>
    <div
      class='max-w-md border border-neutral-subtle rounded-lg overflow-hidden'
    >
      <Collapsible @isOpen={{this.isOpen}} @initialHeight='80px'>
        <div class='p-6 bg-neutral-subtle'>
          <h3 class='text-lg font-semibold mb-2'>Article Title</h3>
          <p class='text-neutral'>
            Lorem ipsum dolor sit amet, consectetur adipiscing elit. Suspendisse
            malesuada lacus ex, sit amet blandit leo lobortis eget. Lorem ipsum
            dolor sit amet, consectetur adipiscing elit. Suspendisse malesuada
            lacus ex, sit amet blandit leo lobortis eget. Sed hendrerit turpis
            nec dolor maximus, vitae facilisis lectus scelerisque.
          </p>
        </div>
      </Collapsible>

      <div class='px-6 py-3 bg-neutral-subtle border-t border-neutral-subtle'>
        <Button @size='sm' @variant='plain' @onPress={{this.toggle}}>
          {{if this.isOpen 'Read Less' 'Read More'}}
        </Button>
      </div>
    </div>
  </template>
}
```

## Initially Open

Passing `@isOpen={{true}}` on the first render shows the content immediately, with no opening animation. Closing it afterwards animates as usual.

```gts preview collapsible
import Component from '@glimmer/component';
import { tracked } from '@glimmer/tracking';
import { Collapsible, Button } from 'frontile';

export default class InitiallyOpen extends Component {
  @tracked isOpen = true;

  toggle = () => {
    this.isOpen = !this.isOpen;
  };

  <template>
    <div class='max-w-md border border-primary-soft rounded-lg overflow-hidden'>
      <h3
        class='p-4 font-semibold bg-primary-subtle border-b border-primary-soft'
      >
        Welcome Message
      </h3>

      <Collapsible @isOpen={{this.isOpen}}>
        <div class='p-4'>
          <p class='text-neutral mb-4'>
            Thank you for signing up! Here are some quick tips to get started.
          </p>
          <ul class='space-y-2 text-neutral'>
            <li>→ Complete your profile</li>
            <li>→ Connect your accounts</li>
            <li>→ Explore the dashboard</li>
          </ul>
        </div>
      </Collapsible>

      <div class='px-4 py-3 bg-neutral-subtle border-t border-neutral-subtle'>
        <Button @size='sm' @variant='plain' @onPress={{this.toggle}}>
          {{if this.isOpen 'Dismiss' 'Show Again'}}
        </Button>
      </div>
    </div>
  </template>
}
```

## Nested Collapsibles

A Collapsible can contain others. The outer one measures its content when it opens, so a nested panel that expands later grows the outer panel with it.

```gts preview collapsible
import Component from '@glimmer/component';
import { tracked } from '@glimmer/tracking';
import { fn } from '@ember/helper';
import { Collapsible, Button } from 'frontile';

export default class NestedCollapsibles extends Component {
  @tracked isParentOpen = false;
  @tracked openChildren: Record<string, boolean> = {};

  subcategories = [
    { id: 'one', title: 'Subcategory 1', body: 'Details for subcategory 1' },
    { id: 'two', title: 'Subcategory 2', body: 'Details for subcategory 2' }
  ];

  toggleParent = () => {
    this.isParentOpen = !this.isParentOpen;
  };

  toggleChild = (id: string) => {
    this.openChildren = { ...this.openChildren, [id]: !this.openChildren[id] };
  };

  isChildOpen = (id: string) => {
    return !!this.openChildren[id];
  };

  <template>
    <div
      class='max-w-md border border-neutral-subtle rounded-lg overflow-hidden'
    >
      <div class='p-4 bg-neutral-subtle'>
        <Button
          @variant='plain'
          @class='w-full text-left font-semibold'
          @onPress={{this.toggleParent}}
          aria-expanded='{{this.isParentOpen}}'
        >
          Category
          <span class='float-right'>{{if this.isParentOpen '▲' '▼'}}</span>
        </Button>
      </div>

      <Collapsible @isOpen={{this.isParentOpen}}>
        <div class='p-4 space-y-2'>
          {{#each this.subcategories as |sub|}}
            <div class='border border-neutral-subtle rounded overflow-hidden'>
              <div class='p-3 bg-neutral-subtle'>
                <Button
                  @variant='plain'
                  @size='sm'
                  @class='w-full text-left'
                  @onPress={{fn this.toggleChild sub.id}}
                  aria-expanded='{{this.isChildOpen sub.id}}'
                >
                  {{sub.title}}
                  <span class='float-right'>
                    {{if (this.isChildOpen sub.id) '−' '+'}}
                  </span>
                </Button>
              </div>

              <Collapsible @isOpen={{this.isChildOpen sub.id}}>
                <p class='p-3 text-sm text-neutral'>{{sub.body}}</p>
              </Collapsible>
            </div>
          {{/each}}
        </div>
      </Collapsible>
    </div>
  </template>
}
```

## Accessibility

Collapsible renders a plain `<div>` with no roles or ARIA of its own, and it has no trigger — the disclosure semantics are yours to supply. It forwards `...attributes`, so `id`, `role`, and `aria-*` can be set on it directly.

- Use a real `<button>` (or Frontile's `Button`) as the trigger, so Enter, Space, and focus work without extra code.
- Put `aria-expanded` on the trigger, mirroring the same state you pass to `@isOpen`.
- Point `aria-controls` at the Collapsible's `id`, and give the Collapsible `role="region"` when it holds a self-contained chunk of content.
- `Collapsible` animates a box; it does not manage focus. While collapsed its
  content is `height: 0` but still in the tab order, so add `inert` yourself
  when the content holds anything focusable — or use
  [Accordion](../disclosure/accordion), which does it for you.
- Building an accordion by hand also means owning the heading structure, the
  `aria-expanded`/`aria-controls` round trip and the arrow-key pattern.
  [Accordion](../disclosure/accordion) implements all of it.

```gts
<button
  type="button"
  aria-expanded={{this.isOpen}}
  aria-controls="content-1"
  {{on "click" this.toggle}}
>
  Toggle Content
</button>

<Collapsible @isOpen={{this.isOpen}} id="content-1" role="region">
  Content here
</Collapsible>
```

> **Note:** Transitions are registered with an Ember test waiter, so `await settled()` in tests resolves only after the open or close animation has finished.

## API

### Collapsible

**Element:** `HTMLDivElement`

**Arguments**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `isOpen *` | `boolean` | - | If true, the content will be visible |
| `initialHeight` | `string` | `0` | The height for the content in it's collapsed state. The unit of the value should be included, eg. '10px'. Any CSS height is accepted (2rem, 50%, calc(1rem + 2px), …); a value the CSS parser rejects is ignored and the content collapses to 0. |

**Blocks**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `default *` | `[]` | - |  |

---

# Divider

Source: /docs/components/utilities/divider.md

# Divider

A Divider is designed to delineate and separate content.

## Import

```js
import { Divider } from 'frontile';
```

## Usage

A horizontal divider renders an `<hr>`.

```gts preview
import { Divider } from 'frontile';

<template>
  <div class='demo-stack text-neutral-strong'>
    <p>
      Quisque nibh est, posuere non purus eu, auctor molestie quam. Mauris ante
      sapien, accumsan et nibh eget, ultricies aliquam orci.
    </p>
    <Divider />
    <p>
      Vestibulum non justo enim. Etiam sed neque lobortis, suscipit elit id,
      dapibus erat. Nulla cursus scelerisque elit, id dictum urna iaculis a.
    </p>
  </div>
</template>
```

## Variants

`@variant='sketch'` swaps the flat rule for a hand-drawn one. It stretches to
any width without distorting: the artwork is a near-horizontal filled shape, so
scaling it horizontally changes only how often it wobbles, never its thickness.

```gts preview
import { Divider } from 'frontile';

<template>
  <div class='demo-stack items-center'>
    <div class='bg-surface-card w-full max-w-sm rounded-2xl p-6'>
    <ul class='text-neutral-strong space-y-2'>
      <li>Parental controls</li>
      <li>Guest network</li>
      <li>Security &amp; malware blocking</li>
    </ul>
    <Divider @variant='sketch' @class='my-5' />
      <div class='text-neutral-strong flex items-baseline justify-between'>
        <span>Starting at</span>
        <span><strong>$10.00</strong> /mo</span>
      </div>
    </div>
  </div>
</template>
```

The line takes its colour from the element's background. By default that is the
`divider` token, which is translucent — 15% ink over whatever sits behind it — so
one divider reads correctly on a page, a card or a tinted panel without being
retuned for each. A utility class recolours it:

```gts preview
import { Divider } from 'frontile';

<template>
  <div class='demo-stack'>
    <Divider @variant='sketch' />
    <Divider @variant='sketch' @class='bg-primary' />
    <Divider @variant='sketch' @class='bg-danger' />
  </div>
</template>
```

`sketch` is horizontal only. The artwork cannot be squashed into a vertical
rule, so `@orientation='vertical'` ignores it and renders the plain line.

## Orientation

`@orientation='vertical'` renders a `<div>` instead, because `<hr>` cannot
express a vertical rule.

`@variant='sketch'` has no effect on a vertical divider — see Variants.

The vertical divider is styled `h-full`, which resolves against its parent — so
the parent needs a **definite** height. `items-stretch` alone is not enough:
`height: 100%` of an auto-height container computes to zero, and the divider
disappears.

```gts preview
import { Divider } from 'frontile';

<template>
  <div class='demo-stack items-center'>
    <div class='text-neutral-strong flex h-8 items-stretch gap-4'>
      <span>Overview</span>
      <Divider @orientation='vertical' />
      <span>Pricing</span>
      <Divider @orientation='vertical' />
      <span>Support</span>
    </div>
  </div>
</template>
```

If the row's height has to stay content-driven, override the height on the
divider itself instead:

```gts preview
import { Divider } from 'frontile';

<template>
  <div class='demo-stack items-center'>
    <div class='text-neutral-strong flex items-center gap-4'>
      <span>Overview</span>
      <Divider @orientation='vertical' @class='h-4' />
      <span>Pricing</span>
      <Divider @orientation='vertical' @class='h-4' />
      <span>Support</span>
    </div>
  </div>
</template>
```

## Changing the element

`@as` renders a different tag from the one the orientation would pick. This
matters when the surrounding markup constrains what is valid — an `<hr>` is not
allowed as a direct child of `<ul>`, so a divider between list items has to be
an `<li>`.

```gts preview
import { Divider } from 'frontile';

<template>
  <div class='demo-stack items-center'>
    <ul class='text-neutral-strong w-48'>
      <li>Recently opened</li>
      <li>Shared with me</li>
      <Divider @as='li' @class='my-2' />
      <li>Trash</li>
    </ul>
  </div>
</template>
```

## Accessibility

The divider carries `role="separator"`, so assistive technology reports a
boundary between groups rather than skipping over it silently. A separator with
no `tabindex` is not focusable and takes no keyboard interaction.

A vertical divider also gets `aria-orientation="vertical"`, because the
`separator` role is horizontal by default — without it a vertical rule is
reported the wrong way round. Horizontal dividers need no such attribute, and
`<hr>` carries its orientation implicitly.

A divider is a visual and structural boundary, not a label. If the two sides of
it are meaningfully different regions, say so with headings or a landmark —
`<section aria-labelledby>`, `<nav>` — rather than relying on the line to carry
that meaning. Screen reader users navigating by heading or landmark never
encounter the separator at all.

## API

### Divider

**Element:** `Element`

**Arguments**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `as` | `string` | - | The tag to render instead of the one the orientation would choose — for example li when the divider sits between list items. |
| `class` | `string` | - | Custom class name, it will override the default ones using Tailwind Merge library. |
| `orientation` | `'horizontal' \| 'vertical'` | `'horizontal'` | Which way the divider runs. A horizontal divider renders an <hr>; a vertical one renders a <div>, since <hr> cannot express that. |
| `variant` | `'solid' \| 'sketch'` | `'solid'` | The divider's visual treatment. sketch renders the hand-drawn rule in place of the flat line. Horizontal only — the artwork is a near-horizontal ribbon and cannot be squashed into a vertical rule, so a vertical divider ignores this and renders a plain line. |

---

# Kbd

Source: /docs/components/utilities/kbd.md

# Kbd

Renders keyboard keys and shortcuts.

`Kbd` knows the common keys by name, so `"mod+k"` becomes `⌘K` on Apple
platforms and `Ctrl+K` everywhere else — one string, correct on every machine.

## Import

```js
import { Kbd } from 'frontile';
```

## Usage

Pass a shortcut to `@keys` as `+`-separated keys.

```gts preview
import { Kbd } from 'frontile';

<template>
  <div class='flex items-center gap-4 not-prose p-2'>
    <Kbd @keys='mod+k' />
    <Kbd @keys='mod+shift+p' />
    <Kbd @keys='enter' />
    <Kbd @keys='esc' />
    <Kbd @keys='up' />
  </div>
</template>
```

Anything that is not a known key renders as given, and a single letter is
capitalised. Pass a block for arbitrary content.

```gts preview
import { Kbd } from 'frontile';

<template>
  <div class='flex items-center gap-4 not-prose p-2'>
    <Kbd @keys='F5' />
    <Kbd @keys='mod+/' />
    <Kbd>Fn</Kbd>
  </div>
</template>
```

## Keys

Named keys are case-insensitive.

| Group      | Names                                                                                                   |
| ---------- | ------------------------------------------------------------------------------------------------------- |
| Modifiers  | `mod`, `meta` / `cmd` / `command`, `ctrl` / `control`, `alt` / `option`, `shift`, `win`, `fn`           |
| Special    | `enter` / `return`, `esc` / `escape`, `tab`, `space`, `backspace`, `del` / `delete`, `capslock`, `plus` |
| Navigation | `up`, `down`, `left`, `right`, `pageup`, `pagedown`, `home`, `end`                                      |

Use `plus` when you need a literal `+`, since `+` is the separator.

Only three keys differ by platform:

| Name   | Apple | Elsewhere |
| ------ | ----- | --------- |
| `mod`  | `⌘`   | `Ctrl`    |
| `ctrl` | `⌃`   | `Ctrl`    |
| `alt`  | `⌥`   | `Alt`     |

Prefer `mod` for application shortcuts — it names the role, so it follows the
platform. Use `meta` only when you mean the Command key specifically.

## Display

`@display='merged'` puts every glyph in a single cap, and `@separator` places a
character between caps.

```gts preview
import { Kbd } from 'frontile';

<template>
  <div class='flex items-center gap-4 not-prose p-2'>
    <Kbd @keys='mod+k' />
    <Kbd @keys='mod+k' @display='merged' />
    <Kbd @keys='ctrl+b' @separator='+' />
  </div>
</template>
```

## Sizes

```gts preview
import { Kbd } from 'frontile';

<template>
  <div class='flex items-center gap-4 not-prose p-2'>
    <Kbd @keys='mod+k' @size='sm' />
    <Kbd @keys='mod+k' @size='md' />
    <Kbd @keys='mod+k' @size='lg' />
  </div>
</template>
```

## Variant and color

```gts preview
import { Kbd } from 'frontile';

const variants = ['solid', 'outline', 'subtle'];
const intents = [
  'default',
  'primary',
  'secondary',
  'success',
  'warning',
  'danger'
];

<template>
  <div class='flex flex-col gap-3 not-prose p-2'>
    {{#each variants as |variant|}}
      <div class='flex items-center gap-3'>
        {{#each intents as |intent|}}
          <Kbd @keys='mod+k' @variant={{variant}} @color={{intent}} />
        {{/each}}
      </div>
    {{/each}}
  </div>
</template>
```

Two variants take their colour from their surroundings rather than from
`@color`. `inherit` keeps a hairline box drawn in the current colour, which is
what lets a keycap sit on a filled, active row without the row's theme having to
repaint it. `plain` drops the box entirely, for a quiet trailing shortcut.

```gts preview
import { Kbd } from 'frontile';

<template>
  <div class='flex flex-col gap-2 not-prose p-2'>
    <div
      class='flex items-center justify-between gap-3 rounded-lg bg-primary-soft text-on-primary-soft px-3 py-2'
    >
      <span>Open command palette</span>
      <Kbd @keys='mod+k' @variant='inherit' @size='sm' />
    </div>
    <div class='flex items-center justify-between gap-3 rounded-lg px-3 py-2'>
      <span>Open command palette</span>
      <Kbd @keys='mod+k' @variant='plain' @size='sm' />
    </div>
  </div>
</template>
```

`Listbox`, `Dropdown` and `Command` render their items' `@shortcut` through
`Kbd`. Their keycaps default to `inherit`, so a shortcut stays legible on an
active or filled row; pass `@shortcutVariant` on the `Listbox` or `Dropdown`
to change every item at once.

## Platform

By default the platform is detected from the browser. Set it explicitly when
detection cannot work or would be wrong — during server rendering, where every
visitor looks non-Apple, or in tests, which would otherwise depend on the
machine running them.

```js
import { setKbdPlatform } from 'frontile';

setKbdPlatform('apple'); // or 'other', or 'auto' to detect
```

`@platform` overrides it for a single keycap.

## Accessibility

Rendered as nested `<kbd>` elements, which is how HTML expresses a key
combination.

Symbol glyphs are hidden from assistive technology and their names announced
instead, since "⌘" read aloud is meaningless. Glyphs that already read correctly
— `Esc`, `Ctrl`, a letter — are left alone, because labelling them would
announce the name twice. Named keys also carry a `title`, which helps sighted
users who do not recognise a glyph.

## API

### Kbd

Renders keyboard keys and shortcuts.

A wrapper <kbd> holds one child <kbd> per key, which is the HTML
specification's own idiom for a key combination.

**Element:** `HTMLElement`

**Arguments**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `class` | `string` | - | Custom class name, it will override the default ones using Tailwind Merge library. |
| `classes` | `SlotsToClasses<'base' \| 'key' \| 'separator'>` | - | Custom CSS classes for styling the individual slots: base for the wrapper, key for each cap, separator for the character between caps. |
| `color` | `'neutral' \| 'primary' \| 'secondary' \| 'tertiary' \| 'success' \| 'warning' \| 'danger'` | `'neutral'` |  |
| `display` | `'split' \| 'merged'` | `'split'` | split gives each key its own cap; merged puts every glyph in one. |
| `keys` | `string` | - | The shortcut to render, as +-separated keys: "mod+shift+p". Named keys resolve to glyphs (mod, shift, enter, esc, up, …); anything else renders verbatim, with a single letter capitalised. Use plus for a literal +. A string with no + is one key, rendered as given. Ignored when a block is passed. |
| `platform` | `KbdPlatform` | - | Overrides the platform for this keycap only. Prefer setKbdPlatform to set it once for the whole app. |
| `separator` | `string` | - | Rendered between caps, e.g. "+". Only applies when @display is split. |
| `size` | `'sm' \| 'md' \| 'lg'` | `'md'` |  |
| `variant` | `'solid' \| 'subtle' \| 'outline' \| 'plain' \| 'inherit'` | `'solid'` | inherit follows the colour it sits on, for keycaps on a filled row. plain drops the box entirely, for quiet trailing shortcuts. |

**Blocks**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `default *` | `[]` | - | Replaces @keys with arbitrary content, rendered as a single cap. |

---

# Skeleton

Source: /docs/components/utilities/skeleton.md

# Skeleton

A Skeleton is a placeholder that stands in for content while it loads. It gives
the eye the shape of what is coming, which an empty region cannot.

## Import

```js
import { Skeleton } from 'frontile';
```

## Usage

A Skeleton is a self-contained element. Reach for `@shape` and `@size` first,
and use `@class` for anything they don't cover.

```gts preview
import { Skeleton } from 'frontile';

<template>
  <div class='demo-stack items-center'>
    <div class='not-prose w-80 space-y-3'>
      <Skeleton @shape='rounded' @class='h-32' />
      <Skeleton @size='sm' />
      <Skeleton @size='sm' @class='w-2/3' />
    </div>
  </div>
</template>
```

`text`, `rounded`, and `rect` fill their container's width. Give the container a
width — or set one with `@class` — since a `width: 100%` element inside a
content-sized parent collapses to nothing.

## Shapes

`@shape` sets the radius and proportions so you don't hand-assemble them.
`text` is the default.

```gts preview
import { Skeleton } from 'frontile';

<template>
  <div class='demo-stack items-center'>
    <div class='not-prose flex w-96 items-end gap-4'>
      <div class='flex-1 space-y-2'>
        <Skeleton @shape='text' />
        <Skeleton @shape='text' @class='w-2/3' />
      </div>
      <Skeleton @shape='circle' @size='xl' />
      <Skeleton @shape='square' @size='xl' />
    </div>
  </div>
</template>
```

| Shape     | Use for                    | Sizing                           |
| --------- | -------------------------- | -------------------------------- |
| `text`    | Lines of copy, table cells | Fills width, `@size` sets height |
| `circle`  | Avatars, icon buttons      | Equal-sided from `@size`         |
| `square`  | Square avatars, thumbnails | Equal-sided from `@size`         |
| `rounded` | Images, cards, media       | Fills width, give it a height    |
| `rect`    | Flush-edged blocks         | Fills width, give it a height    |

`circle` and `square` reuse Avatar's radii and size scale, so a placeholder
lines up with the real thing it stands in for:

```gts preview
import { Skeleton, Avatar } from 'frontile';

<template>
  <div class='demo-stack items-center'>
    <div class='not-prose flex items-center gap-4'>
      <Skeleton @shape='circle' @size='lg' />
      <Avatar @name='Ada Lovelace' @size='lg' />
      <Skeleton @shape='square' @size='lg' />
      <Avatar @name='Ada Lovelace' @shape='square' @size='lg' />
    </div>
  </div>
</template>
```

## Sizes

`@size` accepts `xs`, `sm`, `md` (default), `lg`, and `xl`. For `circle` and
`square` it sets both dimensions; for the other shapes it sets the height.
Every shape has an intrinsic height at every size — a zero-height skeleton is
invisible, which makes a loading state look like an empty one.

```gts preview
import { Skeleton } from 'frontile';

<template>
  <div class='demo-stack items-center'>
    <div class='not-prose flex w-96 items-center gap-4'>
      <Skeleton @shape='circle' @size='xs' />
      <Skeleton @shape='circle' @size='sm' />
      <Skeleton @shape='circle' @size='md' />
      <Skeleton @shape='circle' @size='lg' />
      <Skeleton @shape='circle' @size='xl' />
    </div>
  </div>
</template>
```

## Images and cards

`rounded` and `rect` fill their container; give them a height with `@class`.

```gts preview
import { Skeleton } from 'frontile';

<template>
  <div class='demo-stack items-center'>
    <div class='not-prose w-72 space-y-3'>
      <Skeleton @shape='rounded' @class='h-40' />
      <Skeleton @shape='text' @size='lg' @class='w-3/4' />
      <Skeleton @shape='text' @size='sm' />
      <Skeleton @shape='text' @size='sm' @class='w-1/2' />
    </div>
  </div>
</template>
```

## Composing a layout

Compose several to sketch the shape of the real content.

```gts preview
import { Skeleton } from 'frontile';

<template>
  <div class='demo-stack items-center'>
    <div class='not-prose flex w-80 items-center gap-3'>
      <Skeleton @shape='circle' @size='lg' @class='shrink-0' />
      <div class='flex-1 space-y-2'>
        <Skeleton @size='sm' />
        <Skeleton @size='sm' @class='w-2/3' />
      </div>
    </div>
  </div>
</template>
```

## Animation

`shimmer` is the default. It uses a Frontile-defined keyframe, so it is
unaffected by an app that redefines Tailwind's `pulse`.

```gts preview
import { Skeleton } from 'frontile';

<template>
  <div class='demo-stack items-center'>
    <div class='not-prose w-80 space-y-4'>
      <div>
        <p class='mb-1 text-body-2xs text-neutral-soft'>shimmer (default)</p>
        <Skeleton @class='h-4' @animation='shimmer' />
      </div>
      <div>
        <p class='mb-1 text-body-2xs text-neutral-soft'>pulse</p>
        <Skeleton @class='h-4' @animation='pulse' />
      </div>
      <div>
        <p class='mb-1 text-body-2xs text-neutral-soft'>none</p>
        <Skeleton @class='h-4' @animation='none' />
      </div>
    </div>
  </div>
</template>
```

## Accessibility

Skeleton renders `aria-hidden="true"`. It is decorative — announce the loading
state on the container that owns it, not on each placeholder.

## In Table

[`Table`](/docs/components/collections/table#built-in-skeleton-rows) renders
`Skeleton` for you when you set `@isLoading` and `@skeletonRows` — you rarely
need to compose it by hand for that case.

## API

### Skeleton

**Element:** `HTMLDivElement`

**Arguments**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `animation` | `'none' \| 'shimmer' \| 'pulse'` | `'shimmer'` | Animation style for the placeholder. |
| `class` | `string` | - |  |
| `shape` | `'square' \| 'circle' \| 'text' \| 'rounded' \| 'rect'` | `'text'` | Shape preset. text fills its container at text height; circle and square are equal-sided and match Avatar's radii; rounded and rect fill their container for image and card placeholders. |
| `size` | `'sm' \| 'md' \| 'lg' \| 'xs' \| 'xl'` | `'md'` | Size preset. For circle and square this sets both dimensions from Avatar's scale; for the other shapes it sets the height. |

---

# Spinner

Source: /docs/components/utilities/spinner.md

# Spinner

Indicates a loading state with an animated visual cue.

## Import

```js
import { Spinner } from 'frontile';
```

## Usage

```gts preview
import { Spinner } from 'frontile';

<template><Spinner /></template>
```

## Sizes

`@size` controls the Spinner's size: `xs`, `sm`, `md`, `lg`, or `xl`.

```gts preview
import { Spinner } from 'frontile';

<template>
  <div class='flex items-center space-x-2'>
    <Spinner @size='xs' />
    <Spinner @size='sm' />
    <Spinner @size='md' />
    <Spinner @size='lg' />
    <Spinner @size='xl' />
  </div>
</template>
```

## Colors

`@color` changes the Spinner's color to match common UI patterns, such
as `primary` actions, `success` states, `warnings`, and `danger` actions.

```gts preview
import { Spinner } from 'frontile';

<template>
  <div class='flex items-center space-x-2'>
    <Spinner @color='neutral' />
    <Spinner @color='primary' />
    <Spinner @color='secondary' />
    <Spinner @color='tertiary' />
    <Spinner @color='success' />
    <Spinner @color='warning' />
    <Spinner @color='danger' />
  </div>
</template>
```

## Style Customization

Add custom CSS classes with the `class` argument for anything the built-in
options don't cover. Override colors with `fill-{*}` classes for the
highlighted color and `text-{*}` classes for the background. Semantic color
utilities adapt automatically across themes.

```gts preview
import { Spinner } from 'frontile';

<template>
  <div class='flex items-center justify-center'>
    <Spinner @class='h-24 w-24 fill-secondary text-primary-muted' />
  </div>
</template>
```

## Accessibility

The spinner is `aria-hidden` by default: it is a picture of a state, not the
state itself. An unhidden, unnamed `<svg>` is announced as an
image with no name, which tells a screen reader user nothing — and naming the
graphic ("Loading spinner") describes the decoration rather than saying that the
content they asked for is on its way.

Put the state on the thing that is loading. `aria-busy` marks the region, and a
polite live region announces the transition once:

```gts preview collapsible
import Component from '@glimmer/component';
import { tracked } from '@glimmer/tracking';
import { Button, Spinner } from 'frontile';

export default class Example extends Component {
  @tracked isLoading = false;
  @tracked rows: string[] = [];

  load = async () => {
    this.isLoading = true;
    this.rows = [];
    await new Promise((resolve) => setTimeout(resolve, 1500));
    this.rows = ['Fiber route A', 'Fiber route B', 'Fiber route C'];
    this.isLoading = false;
  };

  <template>
    <div class='flex flex-col gap-3'>
      <Button @color='primary' @onPress={{this.load}}>Load routes</Button>

      <div
        aria-busy={{if this.isLoading 'true' 'false'}}
        aria-live='polite'
        class='border-neutral-soft rounded border p-4'
      >
        {{#if this.isLoading}}
          <span class='flex items-center gap-2'>
            <Spinner @size='sm' @color='primary' />
            Loading routes…
          </span>
        {{else if this.rows}}
          <ul class='not-prose'>
            {{#each this.rows as |row|}}
              <li>{{row}}</li>
            {{/each}}
          </ul>
        {{else}}
          <p class='text-neutral'>No routes loaded yet.</p>
        {{/if}}
      </div>
    </div>
  </template>
}
```

The visible "Loading routes…" text is what carries the meaning here — the spinner
beside it is redundant by design, which is exactly what makes hiding it correct.

A spinner with no adjacent text needs the text supplied some other way, or the
wait is silent. `VisuallyHidden` is the usual answer for a button that swaps its
label for a spinner:

```gts preview
import Component from '@glimmer/component';
import { tracked } from '@glimmer/tracking';
import { Button, Spinner, VisuallyHidden } from 'frontile';

export default class Example extends Component {
  @tracked isSaving = false;

  save = async () => {
    this.isSaving = true;
    await new Promise((resolve) => setTimeout(resolve, 1500));
    this.isSaving = false;
  };

  <template>
    <Button @color='primary' @onPress={{this.save}} disabled={{this.isSaving}}>
      {{#if this.isSaving}}
        <Spinner @size='sm' />
        <VisuallyHidden>Saving, please wait</VisuallyHidden>
      {{else}}
        Save
      {{/if}}
    </Button>
  </template>
}
```

If you need the graphic itself announced — a full-page loader with
nothing else on screen — pass your own attributes, which are applied after the
default and so win:

```gts preview
import { Spinner } from 'frontile';

<template>
  <Spinner @size='xl' aria-hidden='false' role='status' aria-label='Loading' />
</template>
```

Motion is the other consideration: the theme applies `animate-spin` with **no**
`motion-reduce` variant, so the spinner keeps turning for users who have asked
for reduced motion. If your product treats that preference as absolute, suppress
it yourself:

```gts preview
import { Spinner } from 'frontile';

<template>
  <Spinner @color='primary' @class='motion-reduce:animate-none' />
</template>
```

Which is another reason not to let a spinner be the only sign that something is
happening: the text beside it keeps working when the animation does not.

## API

### Spinner

**Element:** `SVGElement`

**Arguments**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `class` | `string` | - | Custom class name, it will override the default ones using Tailwind Merge library. Use fill-* for the highlighted arc and text-* for the track. |
| `color` | `'neutral' \| 'primary' \| 'secondary' \| 'tertiary' \| 'success' \| 'warning' \| 'danger'` | `'neutral'` | The color of the spinner. |
| `intent` | `'default' \| 'primary' \| 'secondary' \| 'tertiary' \| 'success' \| 'warning' \| 'danger'` | - | **Deprecated.** Use `color`. `default` is now `neutral`. |
| `size` | `'sm' \| 'md' \| 'lg' \| 'xs' \| 'xl'` | `'md'` | The size of the spinner. |

---

# VisuallyHidden

Source: /docs/components/utilities/visually-hidden.md

# VisuallyHidden

Hides content visually while keeping it available to screen readers, for context
that assistive technology needs and the visual design does not.

## Import

```js
import { VisuallyHidden } from 'frontile';
```

## Usage

The common case is naming a control whose meaning is carried by an icon.

```gts preview
import { Button, VisuallyHidden } from 'frontile';
import { ViewIcon, EditIcon, DeleteIcon } from 'site/components/icons';

<template>
  <div class='flex gap-2'>
    <Button @variant='outline' @size='sm'>
      <VisuallyHidden>View details</VisuallyHidden>
      <ViewIcon />
    </Button>

    <Button @variant='outline' @size='sm'>
      <VisuallyHidden>Edit item</VisuallyHidden>
      <EditIcon />
    </Button>

    <Button @variant='outline' @size='sm' @color='danger'>
      <VisuallyHidden>Delete item</VisuallyHidden>
      <DeleteIcon />
    </Button>
  </div>
</template>
```

## Adding context to a visual signal

Where meaning is carried by colour, shape, or position, the sighted reader gets
it for free and everyone else gets nothing. A hidden word restores it without
changing the layout.

```gts preview
import { Chip, VisuallyHidden } from 'frontile';

<template>
  <ul role='list' class='not-prose flex flex-col gap-2'>
    <li>
      <Chip @color='success' @withDot={{true}}>
        <VisuallyHidden>Status: </VisuallyHidden>
        Operational
      </Chip>
    </li>
    <li>
      <Chip @color='danger' @withDot={{true}}>
        <VisuallyHidden>Status: </VisuallyHidden>
        Degraded
      </Chip>
    </li>
  </ul>
</template>
```

## Announcing a change

Combined with `aria-live`, a hidden region announces something that the visual
design already shows some other way — a count that updated, a save that
finished — without printing it twice on screen.

```gts preview
import Component from '@glimmer/component';
import { tracked } from '@glimmer/tracking';
import { Button, VisuallyHidden } from 'frontile';

export default class Example extends Component {
  @tracked count = 0;

  add = () => {
    this.count++;
  };

  // The announcement is a sentence, so build it in JS rather than stitching it
  // together in the template — the plural has to agree.
  get announcement(): string {
    const noun = this.count === 1 ? 'item' : 'items';
    return `${this.count} ${noun} in cart`;
  }

  <template>
    <div class='flex items-center gap-4'>
      <Button @color='primary' @onPress={{this.add}}>Add to cart</Button>
      <span class='text-neutral-strong'>{{this.count}}</span>

      <VisuallyHidden aria-live='polite'>{{this.announcement}}</VisuallyHidden>
    </div>
  </template>
}
```

## Accessibility

The component renders a `<div class="sr-only">`, the Tailwind utility that takes
content out of the visual flow while leaving it in the accessibility tree:

```css
position: absolute;
width: 1px;
height: 1px;
padding: 0;
margin: -1px;
overflow: hidden;
clip: rect(0, 0, 0, 0);
white-space: nowrap;
border-width: 0;
```

That is a different thing from `display: none`, `visibility: hidden`, or
`hidden`, all of which remove content from the accessibility tree too. Use
those when you want content gone for everyone.

### VisuallyHidden or `aria-label`

Both name a control, and for a plain string `aria-label` is shorter:

```gts
{{! equivalent }}
<Button aria-label='Close dialog'><CloseIcon /></Button>

<Button>
  <VisuallyHidden>Close dialog</VisuallyHidden>
  <CloseIcon />
</Button>
```

Reach for `VisuallyHidden` when `aria-label` cannot do the job:

- The content is **markup**, not a string — `aria-label` takes text only.
- The content must be **translated by the same machinery as visible text**;
  attribute values are easy for translation tooling to miss.
- The content is a **live region**, as above. `aria-label` cannot announce.

Note that `aria-label` on a container **replaces** everything inside it for
screen readers, so an element with both an `aria-label` and visible text hides
that text. `VisuallyHidden` adds instead of replacing.

### Keep it out of the visible text

Hidden text is concatenated with visible text into one accessible name, so
repeating the visible label produces "Save changes Save changes":

```gts
{{! ✗ the name is read twice }}
<Button>
  <VisuallyHidden>Save changes</VisuallyHidden>
  Save changes
</Button>

{{! ✓ the hidden text supplies what the icon cannot }}
<Button>
  <VisuallyHidden>Save changes</VisuallyHidden>
  <SaveIcon />
</Button>
```

### Say which one

In a list, a generic label is announced identically on every row, so it names
the action without identifying its target:

```gts
{{! ✗ every row announces "Delete" }}
<Button><VisuallyHidden>Delete</VisuallyHidden><DeleteIcon /></Button>

{{! ✓ }}
<Button>
  <VisuallyHidden>Delete contact {{contact.name}}</VisuallyHidden>
  <DeleteIcon />
</Button>
```

### Focusable content

Anything focusable inside a `VisuallyHidden` becomes a keyboard trap in
appearance: a sighted keyboard user tabs to something they cannot see. Keep
links and controls out of it, or use a skip-link pattern that reveals itself on
focus instead.

`sr-only` comes from Tailwind, so it has to be in your generated CSS. Frontile's
own components use it, which means your Tailwind setup needs to scan the
`frontile` package — see [Installation](/docs/get-started/installation).

## API

### VisuallyHidden

**Element:** `HTMLDivElement`

**Arguments**

_No arguments._

**Blocks**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `default *` | `[]` | - |  |

---

# ref

Source: /docs/components/utilities/ref.md

---
---

# ref

The `ref` utility offers a straightforward method to create a reference to a DOM element in your components. This is useful when you need direct access to an element for tasks like measuring dimensions, setting focus, or integrating with external libraries.

- **Element Reference:**
  Returns an object with a `setup` modifier that attaches the element to a tracked property in your component.

- **Reactive Tracking:**
  Changes to the element (e.g., mounting or unmounting) automatically trigger updates in your component.

- **Cleanup:**
  Automatically resets the element reference when the element is removed from the DOM.

- **Callback Notification:**
  If a callback function is provided, it is invoked every time the element changes, allowing you to perform additional operations (e.g., measuring the element's dimensions).

## Import

```js
import { ref } from 'frontile';
```

## Usage

### Basic

```gts preview
import Component from '@glimmer/component';
import { ref, toggleState } from 'frontile';
import { Button } from 'frontile';

export default class MyTestComponent extends Component {
  toggle = toggleState(true);

  // Create a ref to capture a reference to the DIV element.
  myRef = ref<HTMLDivElement>();

  <template>
    <Button @onPress={{this.toggle.toggle}}>
      Toggle
    </Button>

    {{#if this.toggle.current}}
      <div {{this.myRef.setup}}>
        Hello World
      </div>
    {{/if}}

    <div>
      Element TagName:
      {{this.myRef.current.tagName}}
    </div>
  </template>
}
```

### Using onChange to Measure Element Dimensions

In this example, a callback is provided to `ref` so that whenever the element is attached or removed, its width is measured and stored in a tracked property.

```gts preview
import Component from '@glimmer/component';
import { tracked } from '@glimmer/tracking';
import { ref } from 'frontile';

export default class ElementMeasureComponent extends Component {
  @tracked elementWidth = 0;

  // Create a ref with an onChange callback that updates the element's width.
  myRef = ref<HTMLDivElement>((el) => {
    if (el) {
      this.elementWidth = el.getBoundingClientRect().width;
    } else {
      this.elementWidth = 0;
    }
  });

  <template>
    <div {{this.myRef.setup}} class='bg-primary text-on-primary w-48'>
      Measured Element
    </div>
    <p>
      Element Width:
      {{this.elementWidth}}px
    </p>
  </template>
}
```

### Using as a Template Helper

You can also use `ref` directly within your templates:

```gts preview
import { ref, toggleState } from 'frontile';
import { Button } from 'frontile';

<template>
  {{#let (ref) as |myRef|}}
    {{#let (toggleState true) as |toggle|}}
      <Button @onPress={{toggle.toggle}}>
        Toggle Visibility
      </Button>

      {{#if toggle.current}}
        <div {{myRef.setup}}>
          Content is visible
        </div>
      {{/if}}

      <div>
        Element TagName:
        {{myRef.current.tagName}}
      </div>
    {{/let}}
  {{/let}}
</template>
```

---

# rovingFocus

Source: /docs/components/utilities/roving-focus.md

# rovingFocus

`rovingFocus` gives a group of related controls the keyboard behaviour the
ARIA authoring practices ask for: the group is a **single tab stop**, and once
focus is inside it the arrow keys move between the items. It owns the keyboard
and the `tabindex` bookkeeping only — it renders nothing, decides nothing about
selection, and applies no styling — which is what lets one primitive serve
`SegmentedControl`'s radiogroup and `Table`'s selectable rows today, and a
future `Tabs` unchanged.

## Import

```js
import { rovingFocus } from 'frontile';
```

## The contract

Construct one instance per group, then place its single modifier on every item.

```gts
<div role="radiogroup">
  <button aria-checked="true" {{roving.setupItem}}>...</button>
</div>
```

**`setupItem` takes no arguments.** Both facts it needs are read from the
element itself, live, at the moment a decision is made:

| State | How the element declares it |
| ----- | --------------------------- |
| selected | `data-selected="true"`, `aria-checked="true"`, or `aria-selected="true"` |
| disabled | `:disabled`, or `aria-disabled="true"` |

An element already has to declare both for the browser and for assistive
technology, so asking a consumer to declare them a second time only creates a
way for the two to disagree.

Covering several spellings of each is deliberate rather than defensive. A
radiogroup marks selection with `aria-checked`, a tab list with
`aria-selected`, and Frontile's own components publish `data-selected`.
Likewise `:disabled` is the form-control path, while `aria-disabled` is the
only option for an element that cannot be natively disabled at all — an `<a>`
or a `LinkTo`, which is exactly what a navigation tab list is built from.

Items register themselves as their modifiers run and are kept sorted by
document position, not by setup order — modifier setup order is not guaranteed
to match DOM order once items are added or reordered, and navigation has to
follow what the user actually sees.

## Options are a thunk

The constructor takes a *function* returning the options, not the options
themselves:

```ts
roving = rovingFocus(() => ({
  orientation: this.args.orientation ?? 'horizontal',
  activationMode: 'automatic',
  onActivate: this.activate
}));
```

The thunk is called at the moment a key is handled, never cached. That is the
whole point: a consumer whose orientation or activation mode is a component
argument stays reactive without having to push updates into the instance, and
without the instance having to be rebuilt when an argument changes. A snapshot
taken in the constructor would freeze `@orientation` at its first value, and a
control switched from horizontal to vertical would keep answering to the wrong
arrow keys.

| Option           | Type                                | Default        |
| ---------------- | ----------------------------------- | -------------- |
| `orientation`    | `'horizontal' \| 'vertical'`        | `'horizontal'` |
| `activationMode` | `'automatic' \| 'manual'`           | `'automatic'`  |
| `onActivate`     | `(element: HTMLElement) => void`    | —              |

`onActivate` receives the **element**, not a value. Keeping the primitive
ignorant of the consumer's value type is what lets a consumer hold non-string
values against their elements and get them back unserialised; `SegmentedControl`
keeps a `Map<HTMLElement, T>` for exactly that.

## The keyboard contract

| Key                        | Behaviour                                                            |
| -------------------------- | -------------------------------------------------------------------- |
| `Tab`                      | Enters or leaves the group. Only one item inside it is tabbable.     |
| `ArrowRight` / `ArrowDown` | Moves to the next enabled item, wrapping past the last to the first. |
| `ArrowLeft` / `ArrowUp`    | Moves to the previous enabled item, wrapping past the first to the last. |
| `Home` / `End`             | Moves to the first / last enabled item.                              |

Which arrow pair is live depends on `orientation`: horizontal listens to
left/right, vertical to up/down. The other pair is left alone, so a vertical
group inside a horizontally scrolling region does not swallow left/right.

Disabled items are skipped entirely rather than focused and stepped over — the
navigation order is computed from the enabled items alone, so wrapping and
`Home`/`End` land on real targets. Any handled key calls `preventDefault()`;
anything else is left to the browser.

Keys are only handled when they are pressed on the item **itself**. An item is
not always a leaf — a grid row holds real controls — and a key pressed on a
button, link or input inside one belongs to that control. Without this, typing
in a cell would move the row focus and `Enter` on a nested button would activate
the row instead.

## Activation modes

`automatic` — the default, and what the radiogroup pattern requires — moves
selection *with* focus: every arrow, `Home`, or `End` focuses the new item and
immediately calls `onActivate` with it. Arrowing through a `SegmentedControl`
selects as it goes, exactly as a native radio group does.

`manual` moves focus only. `onActivate` is not called on arrow keys; it fires
when the user presses `Enter` or `Space` on the focused item. This is the mode
tabs want when switching panels is expensive — a user arrowing across six tabs
should not trigger six panel loads — and it is why the option exists ahead of a
`Tabs` component to use it.

In both modes the consumer decides what "activate" means. `rovingFocus` never
changes `aria-checked`, `aria-selected`, or anything else about the item.

## The roving tabindex

Exactly one item in the group carries `tabindex="0"`; every other item gets
`tabindex="-1"`, and the set is recomputed whenever an item is added, removed,
or changes state. Because both facts are read from the element rather than
passed in, nothing re-runs the modifier when they change — so each item is
watched for changes to those attributes, and the tab stop hands off on its own.

The tab stop is where focus last was, else the selected item, else the **first
enabled item**. That last fallback is not incidental: a radiogroup with no
selection still has to be reachable by `Tab`, and without it a fresh group with
nothing chosen would have no tab stop at all and would be skipped over entirely
by keyboard users.

Focus comes ahead of selection because the two only disagree when activation
does not follow focus — a `manual` group, or one where several items are
selected at once. There the selected item is not where the user is, and sending
`Tab` back to it would undo their navigation. Focus is tracked with `focusin`
rather than `focus`, so focus landing on a control *inside* an item still puts
that item in play.

A group in which every item is disabled has no tab stop, which is the correct
outcome — there is nothing there to operate.

## Right-to-left

In an RTL container the right arrow moves towards the *start* of the group, so
`ArrowRight` and `ArrowLeft` swap roles. `rovingFocus` reads the focused item's
computed `direction` at the moment the key is handled, so a group inside a
`dir="rtl"` subtree behaves correctly without the consumer passing anything —
and a page that flips direction at runtime is picked up on the next keypress
rather than being frozen at construction time.

Only horizontal navigation is affected. Vertical order is the same in both
directions, so `ArrowUp`/`ArrowDown` are never swapped.

## Usage

Arrow between the options below — focus and selection move together, `Home`
and `End` jump to the ends, the disabled option is skipped, and `Tab` leaves
the group in one press rather than stepping through all four.

```gts preview collapsible
import Component from '@glimmer/component';
import { tracked } from '@glimmer/tracking';
import { rovingFocus } from 'frontile';

const options = [
  { value: 'day', label: 'Day', isDisabled: false },
  { value: 'week', label: 'Week', isDisabled: false },
  { value: 'month', label: 'Month', isDisabled: true },
  { value: 'year', label: 'Year', isDisabled: false }
];

export default class Example extends Component {
  @tracked selected = 'day';

  roving = rovingFocus(() => ({
    orientation: 'horizontal',
    activationMode: 'automatic',
    onActivate: this.activate
  }));

  activate = (element: HTMLElement): void => {
    this.selected = element.getAttribute('data-value') ?? this.selected;
  };

  isSelected = (value: string): boolean => {
    return this.selected === value;
  };

  <template>
    <div class='flex flex-col items-start gap-3'>
      <div role='radiogroup' aria-label='Date range' class='flex gap-2'>
        {{#each options as |option|}}
          <button
            type='button'
            role='radio'
            data-value={{option.value}}
            aria-checked='{{this.isSelected option.value}}'
            disabled={{option.isDisabled}}
            class='rounded-md border border-neutral-soft px-3 py-1 text-label-md
              aria-checked:border-primary aria-checked:text-primary
              disabled:cursor-not-allowed disabled:opacity-disabled'
            {{this.roving.setupItem}}
          >{{option.label}}</button>
        {{/each}}
      </div>

      <p class='text-body-sm text-neutral-strong'>Selected: {{this.selected}}</p>
    </div>
  </template>
}
```

> `rovingFocus` handles `keydown` on the items themselves, so it only reacts
> once focus is already inside the group. Selecting with the pointer stays the
> consumer's job — wire your own `click` handler alongside `setupItem`, as
> `SegmentedControl` does.

---

# selectionIndicator

Source: /docs/components/utilities/selection-indicator.md

# selectionIndicator

`selectionIndicator` creates a helper that measures whichever element is currently selected inside
a container and publishes its geometry as CSS custom properties on that
container. It paints nothing itself — a theme decides what that geometry
becomes, which is what lets one primitive back both `SegmentedControl`'s
pill and, in the future, an underline-style `Tabs`, with no JS change
between them.

## Import

```js
import { selectionIndicator } from 'frontile';
```

## The contract

Call it to create an instance; the instance exposes two modifiers and, for
callers that cannot use a modifier, the two methods those modifiers wrap.

```js
indicator = selectionIndicator();
```

`setupContainer` goes on the element the custom properties are written to. It
observes that element's size and re-measures whenever it changes.

`setupTarget` goes on each candidate element, with whether it is currently
selected as its sole positional argument:

```gts
<div {{indicator.setupContainer}}>
  <button {{indicator.setupTarget isSelected}}>...</button>
</div>
```

Only the element passed `true` is measured; its geometry is written to the
container as four custom properties:

| Property         | Value                                 |
| ---------------- | ------------------------------------- |
| `--fr-si-x`      | The selected element's `offsetLeft`   |
| `--fr-si-y`      | The selected element's `offsetTop`    |
| `--fr-si-width`  | The selected element's `offsetWidth`  |
| `--fr-si-height` | The selected element's `offsetHeight` |

### Driving it without `setupTarget`

`setupTarget` is a thin wrapper over two public methods, and a consumer that
needs to write its own modifier can call them directly:

| Method             | Effect                                               |
| ------------------ | ---------------------------------------------------- |
| `claim(element)`   | Makes `element` the measured target and measures it. |
| `release(element)` | Gives up the target, if `element` still holds it.    |

Reach for these only when one modifier has to do more than track geometry.
`TabNav` is the case that motivated them: its item modifier also writes
`aria-current` and `data-selected`, so it cannot simply apply `setupTarget`
alongside, and re-implementing the handover rules would mean two copies of
them.

```js
setupItem = modifier((element, [isActive]) => {
  if (isActive) {
    this.indicator.claim(element);
  }

  return () => {
    this.indicator.release(element);
  };
});
```

`release` is deliberately safe to call for an element that is not the target —
it returns without doing anything — so teardown never needs to check first.
Order matters more than it looks: when the selection moves backwards the
incoming element's setup runs _before_ the outgoing element's teardown, and the
guard inside `release` is what stops that teardown from wiping the new target.

These are physical offsets (`offsetLeft` / `offsetTop`), not logical ones,
and that is deliberate: the browser has already laid the items out for the
container's writing direction, so a physical offset fed to `translate` is
correct in both LTR and RTL with no extra handling. Reaching for a logical
property like `inset-inline-start` here would flip an already-flipped value.

Once the first real measurement lands, the container gains a
`data-fr-si-ready` attribute one frame later. A CSS transition on the
indicator must be gated on this attribute, not applied unconditionally —
otherwise the very first paint has nothing to transition _from_, and the
indicator visibly flies in from the container's origin `(0, 0)` before
settling into place. The same attribute should gate opacity, so the indicator
stays invisible until it has something correct to show.

The attribute lands on the **container**, and the indicator is a descendant of
it, so the gate is a descendant selector — `[data-fr-si-ready] .my-indicator
{ … }`, never `.my-indicator[data-fr-si-ready]`, which can never match. In
Tailwind the same relationship is spelled `group-data-[fr-si-ready]/name:`
against a `group/name` on the container, which is exactly how
`SegmentedControl`'s theme keys both opacity and the transition off of it.

If the selected target measures zero — inside a closed drawer, an inactive
tab panel — the container loses `data-fr-si-ready` instead of publishing a
collapsed box, so the indicator does not falsely mark itself ready with
nothing to show. It picks back up on its own once the target is actually
visible and a resize is observed.

## A working example

Everything above in one runnable piece: three buttons and a bar that slides
between them. The primitive supplies no styling at all — the bar's entire
appearance and geometry come from the CSS below, reading the published custom
properties.

Note the two rules the rest of this page argues for. The gate is
`.si-demo[data-fr-si-ready] .si-demo-bar` — container attribute, descendant
indicator — and the bar is positioned with `left` / `width` from
`--fr-si-x` / `--fr-si-width`, never with `transform`.

```gts preview collapsible
import Component from '@glimmer/component';
import { tracked } from '@glimmer/tracking';
import { on } from '@ember/modifier';
import { fn } from '@ember/helper';
import { selectionIndicator } from 'frontile';

export default class SelectionIndicatorDemo extends Component {
  indicator = selectionIndicator();

  tabs = ['Overview', 'Activity', 'Settings'];

  @tracked current = 'Overview';

  select = (tab: string): void => {
    this.current = tab;
  };

  isSelected = (tab: string): boolean => {
    return this.current === tab;
  };

  <template>
    {{! template-lint-disable no-forbidden-elements }}
    <style>
      .si-demo {
        position: relative;
        display: inline-flex;
      }

      .si-demo-bar {
        position: absolute;
        bottom: 0;
        height: 2px;
        left: var(--fr-si-x);
        width: var(--fr-si-width);
        background: currentColor;
        opacity: 0;
      }

      .si-demo[data-fr-si-ready] .si-demo-bar {
        opacity: 1;
        transition:
          left 200ms ease-out,
          width 200ms ease-out;
      }
    </style>

    <div
      class='si-demo border-b border-neutral-soft text-primary'
      {{this.indicator.setupContainer}}
    >
      <span class='si-demo-bar'></span>

      {{#each this.tabs as |tab|}}
        <button
          type='button'
          class='px-4 py-2 text-label-md
            {{if (this.isSelected tab) "text-primary" "text-neutral-strong"}}'
          {{this.indicator.setupTarget (this.isSelected tab)}}
          {{on 'click' (fn this.select tab)}}
        >
          {{tab}}
        </button>
      {{/each}}
    </div>
  </template>
}
```

The same markup with a different stylesheet is a pill, a highlight, or a
growing outline. That is the point of publishing geometry instead of painting
it.

## The transform / translate trap

Overriding the indicator's positioning with the seemingly obvious

```css
.my-indicator {
  transform: translateX(var(--fr-si-x));
}
```

silently applies the offset **twice**. Per CSS Transforms Level 2, the
standalone `translate` property (which is what Tailwind's `translate-x-*`
utilities emit, not `transform`) is applied _before_ `transform` in the same
box's transform stack — so a theme that already positions with
`translate-x-[var(--fr-si-x)]` and an override that adds
`transform: translateX(var(--fr-si-x))` on top compose, rather than one
replacing the other, and the element ends up offset by twice `--fr-si-x`.

An override has to neutralise the shipped geometry first —
`translate: none` — and then re-derive its own box purely from the published
custom properties, as the worked underline example below does.

## Worked example: a pill indicator

This is what `SegmentedControl`'s own theme does: an absolutely positioned
box sized and moved entirely by the four custom properties.

`.my-control` is the element carrying `setupContainer`, so it is the one that
gains `data-fr-si-ready`; the gated rules therefore read _container attribute,
then descendant indicator_.

```css
.my-control {
  position: relative;
}

.my-control .pill-indicator {
  position: absolute;
  left: 0;
  top: 0;
  width: var(--fr-si-width);
  height: var(--fr-si-height);
  translate: var(--fr-si-x) var(--fr-si-y);
  border-radius: 9999px;
  opacity: 0;
}

.my-control[data-fr-si-ready] .pill-indicator {
  opacity: 1;
  transition:
    translate 200ms ease-out,
    width 200ms ease-out,
    height 200ms ease-out;
}
```

## Worked example: an underline indicator

Only the CSS differs — a bar pinned to the container's bottom edge, sized
from `--fr-si-x` and `--fr-si-width` alone, with the theme's `translate`,
`width`, and `top` explicitly neutralised so the two geometries cannot
compose:

```css
.my-control .underline-indicator {
  translate: none;
  width: auto;
  position: absolute;
  top: auto;
  bottom: 0;
  left: var(--fr-si-x);
  right: calc(100% - var(--fr-si-x) - var(--fr-si-width));
  height: 2px;
  opacity: 0;
}

.my-control[data-fr-si-ready] .underline-indicator {
  opacity: 1;
  transition:
    left 200ms ease-out,
    right 200ms ease-out;
}
```

---

# toggleState

Source: /docs/components/utilities/toggle.md

---
---

# toggleState

The `toggleState` utility is a lightweight helper for managing boolean state in your components. It encapsulates a tracked property (`current`) and a `toggle` method that can be used to update the state. This utility supports:

- **Simple Toggling:** Calling `toggle()` without arguments simply inverts the current state.
- **Explicit State Setting:** You can pass a boolean to `toggle(true)` or `toggle(false)` to explicitly set the state.
- **Event Handling:** If an event (such as from a checkbox input) is passed, it will update the state based on the input’s `checked` property.
- **Callback Notification:** An optional callback can be provided to receive notifications whenever the state changes.

## Import

```js
import { toggleState } from 'frontile';
```

## Usage

### Creating a Toggle State

You can create a toggle state using the helper function:

```ts
import { toggleState } from 'frontile';

let state = toggleState(false, (val) => {
  console.log('State changed to:', val);
});
```

### Toggling the State

- Without arguments:

```ts
state.toggle(); // Flips the current state.
```

- With an explicit boolean value:

```ts
state.toggle(true); // Sets the state to true.
```

- With an event (e.g., from a checkbox):

```gts
// If used as an event handler, it reads the `checked` value:
<template><input type='checkbox' {{on 'change' state.toggle}} /></template>
```

### Example Component

Below is an example of a component that uses toggleState:

```gts preview collapsible
import Component from '@glimmer/component';
import { tracked } from '@glimmer/tracking';
import { toggleState } from 'frontile';
import { Button } from 'frontile';
import { on } from '@ember/modifier';

export default class MyTestComponent extends Component {
  // Create a toggle state with an initial value of false.
  showingState = toggleState(false);

  // An explicit method to set the state to true.
  show = () => {
    this.showingState.toggle(true);
  };

  <template>
    <Button
      data-test-id='button-toggle'
      {{on 'click' this.showingState.toggle}}
    >
      Toggle
    </Button>

    <Button data-test-id='button-direct' @onPress={{this.show}}>
      Show (explicit value)
    </Button>

    <input
      data-test-id='input-toggle'
      type='checkbox'
      checked={{this.showingState.current}}
      {{on 'change' this.showingState.toggle}}
    />

    {{#if this.showingState.current}}
      <div data-test-content>
        Hello World
      </div>
    {{/if}}
  </template>
}
```

### Using as a Template Helper

You can also use toggleState directly within your templates:

```gts preview
import { toggleState } from 'frontile';
import { Button } from 'frontile';

<template>
  {{#let (toggleState) as |state|}}
    <Button data-test-id='button-toggle' @onPress={{state.toggle}}>
      Toggle
    </Button>

    {{#if state.current}}
      <div data-test-content>
        Hello World
      </div>
    {{/if}}
  {{/let}}
</template>
```

### ToggleState with onChange Callback

Below is an example that demonstrates how to use `toggleState` with an `onChange` callback. The callback is invoked whenever the toggle state changes, allowing you to perform side effects such as logging or updating external state.

```gts preview
import Component from '@glimmer/component';
import { toggleState } from 'frontile';
import { Button } from 'frontile';

export default class CallbackToggleExample extends Component {
  // Create a toggle state with an initial value of false and an onChange callback.
  toggle = toggleState(false, (newValue: boolean) => {
    console.log('Toggle state changed to:', newValue);
  });

  <template>
    {{#if this.toggle.current}}
      <div data-test-content>
        The toggle is ON
      </div>
    {{else}}
      <div data-test-content>
        The toggle is OFF
      </div>
    {{/if}}

    <Button data-test-id='button-toggle' @onPress={{this.toggle.toggle}}>
      Toggle State
    </Button>
  </template>
}
```

---

# dragToDismiss

Source: /docs/components/utilities/drag-to-dismiss.md

# dragToDismiss

A modifier that turns pointer drags into a dismiss gesture along a single
axis. It tracks a pointer from `pointerdown` through `pointermove` to
`pointerup`, translates the element with the drag in real time, rubber-bands
movement away from the dismiss direction, and calls `onDismiss` when the
gesture clears either a distance or a velocity threshold. It has no knowledge
of any particular component — it only needs an axis, a direction, and a
callback — so it can drive a drawer, a sheet, a toast, or any other
draggable-to-dismiss surface.

## Import

```js
import { dragToDismiss } from 'frontile';
```

## Usage

```gts preview collapsible
import Component from '@glimmer/component';
import { tracked } from '@glimmer/tracking';
import { dragToDismiss, Button } from 'frontile';

export default class DragToDismissExample extends Component {
  @tracked isOpen = true;

  open = () => {
    this.isOpen = true;
  };

  close = () => {
    this.isOpen = false;
  };

  <template>
    <Button @color='primary' @onPress={{this.open}}>Open panel</Button>

    {{#if this.isOpen}}
      <div
        data-test-id='panel'
        class='mt-4 w-64 rounded border border-neutral-subtle bg-surface-card p-4'
        {{dragToDismiss
          axis='y'
          direction=1
          isEnabled=true
          onDismiss=this.close
          handleSelector="[data-test-id='panel-handle']"
        }}
      >
        <div
          data-test-id='panel-handle'
          class='mx-auto mb-3 h-1.5 w-10 rounded-full bg-neutral-muted'
        ></div>
        <p class='mb-3'>Drag me down to dismiss.</p>
        <Button @size='sm' @onPress={{this.close}}>Close panel</Button>
      </div>
    {{/if}}
  </template>
}
```

## Usage Notes

- **Commit thresholds**: a drag dismisses when either the displacement
  exceeds **25%** of the element's size along `axis`, or the velocity over the
  trailing **100ms** exceeds **0.4 px/ms**. Either alone is enough.
- **Animation**: a drag that does not commit springs back over **200ms** with
  `cubic-bezier(0.37, 0, 0.63, 1)`. One that commits carries on from where it
  was released to fully off-screen, over the same duration and easing.
  `onDismiss` fires when that exit animation finishes, not when the pointer is
  released — so the element is still mounted for about 200ms after the
  gesture ends.
- **Rubber-banding**: movement away from the dismiss direction is damped by a
  factor of **0.2**.
- **Handles**: pass `handleSelector` to make a specific child always
  draggable. A press there starts the drag immediately. With neither
  `handleSelector` nor `scrollSelector` set, a press anywhere on the element
  starts a drag.
- **Dragging from a scroll container**: with `scrollSelector` set, a press
  outside the handle does not start a drag straight away. It starts once the
  pointer has travelled **10px**, and only if that travel was predominantly
  along `axis`, in the dismiss `direction`, and the nearest ancestor matching
  `scrollSelector` is already scrolled to the edge the drag pulls away from.
  Anything else scrolls natively. A drag is also refused for **150ms** after
  that container last scrolled, so a fling that comes to rest against the edge
  is not mistaken for a dismiss.
- **`touch-action`**: set it on the scroll container to the axis the browser
  should keep — `pan-y` for a vertical drawer. The default `auto` also arms
  gestures like pinch-zoom, which cancels pointer tracking more readily.
- **Reduced motion**: when the user prefers reduced motion the transitions are
  skipped and `onDismiss` fires immediately.

## Accessibility

`dragToDismiss` is a pointer enhancement; it adds no role, accessible name,
keyboard interaction, or focus management. Always provide a keyboard-operable
dismiss control that calls the same callback, as the demo does. When dismissal
removes the focused surface, move focus to the control that opened it or another
logical destination.

The drag handle is only a visual affordance unless you make it an interactive
control yourself. Do not rely on gesture instructions alone, and keep the
non-gesture dismissal available when `@isEnabled` is false. Reduced-motion
preferences skip the settle animation automatically.

## API

The `dragToDismiss` modifier accepts only named arguments:

| Name             | Type         | Description                                                                                                                                                |
| ---------------- | ------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `axis`           | `'x' \| 'y'` | The axis the drag moves along.                                                                                                                             |
| `direction`      | `1 \| -1`    | Which way along the axis dismisses: `1` for down/right, `-1` for up/left.                                                                                  |
| `isEnabled`      | `boolean`    | Whether the modifier responds to pointer events at all.                                                                                                    |
| `onDismiss`      | `() => void` | Called once the gesture commits to a dismiss.                                                                                                              |
| `handleSelector` | `string`     | Optional CSS selector for an element that is always draggable (e.g. a drag handle).                                                                        |
| `scrollSelector` | `string`     | Optional CSS selector for a scrollable container inside the element that may start a drag once it's already scrolled to the edge the drag pulls away from. |

---

# press

Source: /docs/components/utilities/press.md

---
---

# press

A modifier that handles press interactions across mouse, touch, keyboard, and screen readers. It normalizes press events across browsers and platforms, and handles many nuances of dealing with pointer and keyboard events.

## Import

```js
import { press } from 'frontile';
```

## Features

- **Cross-platform** - Handles mouse, touch, and keyboard interactions
- **Keyboard accessible** - Responds to Enter and Space key presses
- **Customizable** - Supports press start, press end, and press up events
- **Optimized** - Only adds event listeners for callbacks you provide
- **Flexible** - Supports both positional and named arguments

`press` listens to user pointer and keyboard input rather than native `click`
events, so calling `element.click()` programmatically does not trigger
`onPress`. A disabled native form control cannot be pressed by a user.

## Usage

```gts preview collapsible
import Component from '@glimmer/component';
import { tracked } from '@glimmer/tracking';
import { press, type PressEvent } from 'frontile';

export default class PressExample extends Component {
  @tracked events = [];
  @tracked isPressed = false;

  handlePressStart = (e: PressEvent) => {
    this.events = [...this.events, `press start with ${e.pointerType}`];
  };

  handlePressEnd = (e: PressEvent) => {
    this.events = [...this.events, `press end with ${e.pointerType}`];
  };

  handlePress = (e: PressEvent) => {
    this.events = [...this.events, `press with ${e.pointerType}`];
  };

  handlePressChange = (isPressed) => {
    this.isPressed = isPressed;
  };

  <template>
    <div class='flex items-center space-x-2'>

      <button
        type='button'
        {{press
          onPressStart=this.handlePressStart
          onPressEnd=this.handlePressEnd
          onPress=this.handlePress
          onPressChange=this.handlePressChange
        }}
        class='rounded bg-success p-4 text-on-success transition-transform data-[pressed=true]:scale-95'
        data-pressed={{this.isPressed}}
      >
        Press me! ({{if this.isPressed 'pressed' 'not pressed'}})
      </button>
      <div
        class='w-48 h-48 overflow-auto mt-4 space-y-1 border border-neutral-subtle rounded p-2'
      >
        Output:
        <ul>
          {{#each this.events as |event index|}}
            <li class='text-sm'>{{event}}</li>
          {{/each}}
        </ul>
      </div>
    </div>
  </template>
}
```

## Usage Notes

- **Positional argument**: Pass `onPress` as the first argument: `{{press this.handlePress}}`
- **Mixed arguments**: Combine positional `onPress` with named arguments for other callbacks
- **Conflict handling**: Cannot provide both positional and named `onPress` (assertion error)
- **Performance**: Only adds the event listeners your callbacks require - a
  single callback can need more than one (e.g. `onPressChange` also needs
  `pointercancel`)
- **Accessibility**: Automatically handles Enter and Space key interactions. On a
  `<button type="button">` press also calls `preventDefault()`, which suppresses the
  browser's native activation click, so the element fires a single press per keypress
- **Cross-platform**: Supports mouse, touch, and keyboard across all browsers
- **Propagation**: By default a press stops propagation of the underlying
  event to parent elements. Call `continuePropagation()` on the `PressEvent` in
  any handler to let it through. Only events on the pressed element itself are
  stopped - a release that happens outside of the element is left untouched, so
  other listeners on the page (including document-level ones) still receive it.

> **Note:** `preventDefault()` on the keyboard event does not stop it propagating. An
> ancestor `keydown` handler that also treats Enter or Space as activation will act on the
> same keypress a second time — a calendar grid handling Enter to select the focused day
> selects twice once its day cells use `press`. Container-level key handlers above a
> press-bearing element should check `event.defaultPrevented` before acting.

## Accessibility

Apply `press` to a natively interactive element such as a button whenever
possible. The modifier normalizes Enter and Space activation, but it does not
add a role, accessible name, focusability, or disabled semantics to a generic
element. If a custom element is unavoidable, provide those semantics yourself.

On a native button, set `type="button"` unless the press should submit its form.
Disabled behavior comes from the native `disabled` attribute; the modifier does
not infer disabled state from styling or `aria-disabled` alone.

## API

The press modifier accepts an optional positional `onPress` function and the following named options:

| Name | Type | Description |
| --- | --- | --- |
| `onPress` | `(e: PressEvent) => void` | Handler called when press is released over the target. |
| `onPressStart` | `(e: PressEvent) => void` | Handler called when a press interaction starts. |
| `onPressEnd` | `(e: PressEvent) => void` | Handler called when a press interaction ends, either over the target or when the pointer leaves the target. |
| `onPressUp` | `(e: PressEvent) => void` | Handler called when a press is released over the target. Not called when the release happens outside of the target. |
| `onPressChange` | `(isPressed: boolean) => void` | Handler called when the press state changes. |

### PressEvent

Press events are normalized across different input methods and provide consistent information:

| Property | Type | Description |
| --- | --- | --- |
| `type` | `'pressstart' \| 'pressend' \| 'pressup' \| 'press'` | The type of press event. |
| `pointerType` | `'mouse' \| 'pen' \| 'touch' \| 'keyboard' \| 'virtual'` | The pointer type that triggered the event. |
| `target` | `Element` | The target element of the press event. |
| `shiftKey` | `boolean` | Whether the shift key was held during the event. |
| `ctrlKey` | `boolean` | Whether the ctrl key was held during the event. |
| `metaKey` | `boolean` | Whether the meta key was held during the event. |
| `altKey` | `boolean` | Whether the alt key was held during the event. |
| `x` | `number` | The x position relative to the target element. |
| `y` | `number` | The y position relative to the target element. |
| `continuePropagation()` | `() => void` | Allows the event to continue propagating to parent elements. |

---

# Alert

Source: /docs/components/status/alert.md

# Alert

Displays an important message inline in the page. Reach for Alert, rather than the
notifications service, when the message is part of the page and should stay there until the
page or the consumer removes it — a notification is transient and dismisses itself.

## Import

```js
import { Alert } from 'frontile';
```

## Usage

```gts preview
import { Alert } from 'frontile';

<template>
  <div class='demo-stack'>
    <Alert
      @title='Update available'
      @description='A new version is ready to install.'
    />
  </div>
</template>
```

## Statuses

```gts preview
import { Alert } from 'frontile';

<template>
  <div class='demo-stack'>
    <Alert
      @title='Default'
      @description='A neutral, general-purpose message.'
    />
    <Alert
      @title='Info'
      @description='Something worth knowing about.'
      @status='primary'
    />
    <Alert
      @title='Success'
      @description='The operation completed.'
      @status='success'
    />
    <Alert
      @title='Warning'
      @description='Something needs attention.'
      @status='warning'
    />
    <Alert
      @title='Danger'
      @description='Something went wrong.'
      @status='danger'
    />
  </div>
</template>
```

## Variants

`@variant` decides how much of the alert the status colors, from a neutral
surface with a colored icon and title through to a fully filled one. Set it
alongside `@status` — the three below are shown across all five intents.

### Default

A neutral surface; the status shows in the icon and title only. Quiet enough to
sit in a page without competing with the content around it.

```gts preview
import { Alert } from 'frontile';

<template>
  <div class='demo-stack'>
    <Alert @status='neutral' @title='Default' />
    <Alert @status='primary' @title='Info' />
    <Alert @status='success' @title='Success' />
    <Alert @status='warning' @title='Warning' />
    <Alert @status='danger' @title='Danger' />
  </div>
</template>
```

### Soft

A translucent tint of the status fills the alert, over an opaque surface. More
presence than `default` without the weight of `solid`.

```gts preview
import { Alert } from 'frontile';

<template>
  <div class='demo-stack'>
    <Alert @variant='soft' @status='neutral' @title='Default' />
    <Alert @variant='soft' @status='primary' @title='Info' />
    <Alert @variant='soft' @status='success' @title='Success' />
    <Alert @variant='soft' @status='warning' @title='Warning' />
    <Alert @variant='soft' @status='danger' @title='Danger' />
  </div>
</template>
```

### Solid

The status fills the surface, with contrast ink on top. The loudest of the
three — worth reserving for something the reader should not miss.

```gts preview
import { Alert } from 'frontile';

<template>
  <div class='demo-stack'>
    <Alert @variant='solid' @status='neutral' @title='Default' />
    <Alert @variant='solid' @status='primary' @title='Info' />
    <Alert @variant='solid' @status='success' @title='Success' />
    <Alert @variant='solid' @status='warning' @title='Warning' />
    <Alert @variant='solid' @status='danger' @title='Danger' />
  </div>
</template>
```

## Banner

`@layout='banner'` drops the radius and border and centres the content, for an
announcement spanning the width of its container — a notice under a Drawer's
header, or across the top of a panel.

Width is not what the argument controls: an Alert is full-width in either
layout. What changes is that a banner has no edges of its own, so it reads as
part of the surface it sits on rather than as a card resting on it.

```gts preview
import { Alert } from 'frontile';

<template>
  <div class='demo-stack'>
    <div
      class='w-full overflow-hidden rounded-lg border border-surface-overlay-mild'
    >
      <div class='bg-surface-modal px-4 py-3 font-label text-label-xs'>
        Panel header
      </div>
      <Alert
        @layout='banner'
        @variant='soft'
        @status='warning'
        @title='This is the banner text'
      />
      <div class='bg-surface-modal px-4 py-6 text-body-2xs text-neutral-firm'>
        Panel content
      </div>
    </div>
  </div>
</template>
```

A banner's close button is pinned to the trailing edge instead of sitting in
the row, so the centred text stays put whether or not the alert is
dismissible — two banners, one dismissible and one not, still line up with
each other.

```gts preview collapsible
import { Alert, Button } from 'frontile';
import Component from '@glimmer/component';
import { tracked } from '@glimmer/tracking';

export default class BannerCloseExample extends Component {
  @tracked isVisible = true;

  close = () => {
    this.isVisible = false;
  };

  reset = () => {
    this.isVisible = true;
  };

  <template>
    <div class='demo-stack'>
      <div
        class='w-full overflow-hidden rounded-lg border border-surface-overlay-mild'
      >
        <Alert
          @layout='banner'
          @variant='soft'
          @status='primary'
          @title='Not dismissible'
        />
        {{#if this.isVisible}}
          <Alert
            @layout='banner'
            @variant='soft'
            @status='primary'
            @title='Dismissible'
            @onClose={{this.close}}
            @closeButtonTitle='Dismiss the banner'
          />
        {{/if}}
      </div>

      {{#unless this.isVisible}}
        <Button @size='xs' @onPress={{this.reset}}>Show the banner again</Button>
      {{/unless}}
    </div>
  </template>
}
```

## Icon

The `icon` block replaces the status glyph with anything you pass it — a `Spinner` is a
convenient way to build a loading alert, since there is no dedicated loading argument.
`@hideIcon` removes it entirely and wins over the block.

```gts preview
import { Alert, Spinner } from 'frontile';

<template>
  <div class='demo-stack'>
    <Alert @title='Syncing'>
      <:icon><Spinner @size='sm' /></:icon>
    </Alert>

    <Alert @title='No icon' @hideIcon={{true}} />
  </div>
</template>
```

## Actions

The `actions` block renders buttons in a row between the content and the close button.
Alert follows the same styling convention as `NotificationCard`: `@size='xs'`, the first
button's `@status` matching the alert's own, and any further button using
`@variant='plain'`.

```gts preview
import { Alert, Button } from 'frontile';

<template>
  <div class='demo-stack'>
    <Alert
      @status='warning'
      @title='Unsaved changes'
      @description='Save before you leave?'
    >
      <:actions>
        <Button @size='xs' @status='warning'>Save</Button>
        <Button @size='xs' @variant='plain'>Discard</Button>
      </:actions>
    </Alert>
  </div>
</template>
```

## Closing

Passing `@onClose` reveals the close button. Alert does not hide itself when it is
pressed — the consumer removes the Alert from the DOM, so animating it out or persisting
the dismissal is the application's to decide.

```gts preview
import { Alert, Button } from 'frontile';
import Component from '@glimmer/component';
import { tracked } from '@glimmer/tracking';

export default class ClosableAlertExample extends Component {
  @tracked isVisible = true;

  close = () => {
    this.isVisible = false;
  };

  reset = () => {
    this.isVisible = true;
  };

  <template>
    <div class='demo-stack'>
      {{#if this.isVisible}}
        <Alert
          @status='success'
          @title='Changes saved'
          @onClose={{this.close}}
          @closeButtonTitle='Dismiss saved message'
        />
      {{else}}
        <Button @size='xs' @onPress={{this.reset}}>Show alert again</Button>
      {{/if}}
    </div>
  </template>
}
```

Set `@closeButtonTitle` when several alerts sit together, since every close button
otherwise announces as just "Close" without saying what is being dismissed.

## Rich content

The `description` block takes markup, such as a list, where the `@description` argument
only takes a string.

```gts preview
import { Alert } from 'frontile';

<template>
  <div class='demo-stack'>
    <Alert @status='primary' @title='Before you continue'>
      <:description>
        <ul class='list-disc pl-4'>
          <li>Your session expires in 10 minutes.</li>
          <li>Unsaved changes are not recovered.</li>
        </ul>
      </:description>
    </Alert>
  </div>
</template>
```

## Accessibility

`@status` sets the ARIA role along with the color and icon: `warning` and `danger` render
`role="alert"`; every other status renders `role="status"`. `@role` overrides this — use
`'none'` for an alert present in the DOM at first paint, where a live region announces
nothing useful and `alert` can interrupt a screen reader mid-page. Leave the default for an
alert inserted in response to an event, where the role is what gets it announced at all.

Colour alone should not carry the meaning of `@status`. A `danger` alert reads as a problem
to a sighted user and as an ordinary alert to everyone else, so put the state in the
`@title` or `@description` as well.

## API

### Alert

Displays an important message inline in the page.

The static counterpart to NotificationCard: same statuses and visual
recipes, but rendered as part of the page rather than pushed through the
notifications service.

**Element:** `HTMLDivElement`

**Arguments**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `class` | `string` | - | Custom class name, it will override the default ones using Tailwind Merge library. |
| `classes` | `SlotsToClasses<'icon' \| 'base' \| 'description' \| 'title' \| 'closeButton' \| 'inner' \| 'content' \| 'actions'>` | - | Custom CSS classes for styling the individual slots. |
| `closeButtonTitle` | `string` | `'Close'` | The accessible name of the close button. Worth setting when several alerts sit together, since every close button would otherwise be announced as just "Close" without saying what is being dismissed. |
| `description` | `string` | - | The supporting copy under the title. Ignored when a description block is passed — use the block for anything that needs markup, such as a list or a link. |
| `hideIcon` | `boolean` | `false` | Removes the icon. Wins over the icon block if both are supplied. |
| `layout` | `'inline' \| 'banner'` | `'inline'` | banner drops the radius and border and centres the content, for a full-bleed announcement bar spanning its container — a notice under a Drawer's header, say. Width is not what this controls: an Alert is w-full in either layout. A banner's close button is pinned to the trailing edge rather than sitting in the row, so the centred text does not shift when it is present. |
| `onClose` | `() => void` | - | Called when the close button is pressed. Passing this argument is what reveals the close button. Alert does not hide itself — the consumer removes it from the DOM, so showing it again, animating it out, or persisting the dismissal are all the application's to decide. |
| `role` | `'none' \| 'status' \| 'alert'` | - | Overrides the ARIA role, which otherwise comes from @status: warning and danger render role="alert", every other status renders role="status". That default suits an alert inserted in response to an event. Use 'none' for one present in the DOM at first paint, where a live region announces nothing useful and alert can interrupt a screen reader mid-page. |
| `status` | `AlertStatus` | `'default'` | The status of the alert, which drives its colour, its default icon, and its default ARIA role. |
| `title` | `string` | - | The alert's heading. Ignored when a title block is passed. |
| `variant` | `'solid' \| 'soft' \| 'surface'` | `'surface'` | The visual style of the alert. |

**Blocks**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `icon *` | `[]` | - | Replaces the default status glyph. Ignored when @hideIcon is set. |
| `title *` | `[]` | - | Overrides @title. |
| `description *` | `[]` | - | Overrides @description. Takes markup. |
| `actions *` | `[]` | - | Buttons, rendered in a row between the content and the close button. |

---

# ProgressBar

Source: /docs/components/status/progress-bar.md

# ProgressBar

Shows the progress of a process or task as a filled bar.

## Import

```js
import { ProgressBar } from 'frontile';
```

## Usage

```gts preview
import { ProgressBar } from 'frontile';

<template>
  <div class='demo-stack'>
    <ProgressBar @progress={{50}} @label='Progress' />
  </div>
</template>
```

## ProgressBar Colors

```gts preview collapsible
import { ProgressBar } from 'frontile';

<template>
  <div class='demo-stack'>
    <div class='grid grid-cols-6 gap-4'>
      <ProgressBar
        @progress={{50}}
        @label='Default'
        @showValueLabel={{false}}
      />
      <ProgressBar
        @progress={{50}}
        @label='Primary'
        @color='primary'
        @showValueLabel={{false}}
      />
      <ProgressBar
        @progress={{50}}
        @label='Secondary'
        @color='secondary'
        @showValueLabel={{false}}
      />
      <ProgressBar
        @progress={{50}}
        @label='Success'
        @color='success'
        @showValueLabel={{false}}
      />
      <ProgressBar
        @progress={{50}}
        @label='Warning'
        @color='warning'
        @showValueLabel={{false}}
      />
      <ProgressBar
        @progress={{50}}
        @label='Danger'
        @color='danger'
        @showValueLabel={{false}}
      />
    </div>
  </div>
</template>
```

## ProgressBar Sizes

```gts preview
import { ProgressBar } from 'frontile';

<template>
  <div class='demo-stack'>
    <div class='mt-6 grid grid-cols-4 gap-4 items-center'>
      <ProgressBar
        @progress={{50}}
        @size='xs'
        @label='XSmall'
        @showValueLabel={{false}}
      />
      <ProgressBar
        @progress={{50}}
        @size='sm'
        @label='Small'
        @showValueLabel={{false}}
      />
      <ProgressBar @progress={{50}} @label='Normal' @showValueLabel={{false}} />
      <ProgressBar
        @progress={{50}}
        @size='lg'
        @label='Large'
        @showValueLabel={{false}}
      />
    </div>
  </div>
</template>
```

## ProgressBar Radius

```gts preview collapsible
import { ProgressBar } from 'frontile';

<template>
  <div class='demo-stack'>
    <div class='mt-6 grid grid-cols-4 gap-4'>
      <ProgressBar
        @size='lg'
        @progress={{50}}
        @radius='none'
        @label='None'
        @showValueLabel={{false}}
      />
      <ProgressBar
        @size='lg'
        @progress={{50}}
        @radius='sm'
        @label='Small'
        @showValueLabel={{false}}
      />
      <ProgressBar
        @size='lg'
        @progress={{50}}
        @radius='lg'
        @label='Large'
        @showValueLabel={{false}}
      />
      <ProgressBar
        @size='lg'
        @progress={{50}}
        @radius='full'
        @label='Full'
        @showValueLabel={{false}}
      />
    </div>
  </div>
</template>
```

## ProgressBar Labels

```gts preview
import { ProgressBar } from 'frontile';
import { hash } from '@ember/helper';

<template>
  <div class='demo-stack'>
    <div class='mt-6 grid grid-cols-2 gap-4 items-end'>
      <ProgressBar @progress={{50}} @label='With label' />
      <ProgressBar
        @progress={{50}}
        @label='Hiding label value'
        @showValueLabel={{false}}
      />
      <ProgressBar
        @progress={{50}}
        @label='Custom label value'
        @valueLabel='4 out of 8'
      />
      <ProgressBar
        @progress={{50}}
        @label='Custom formatter'
        @formatOptions={{(hash style='currency' currency='USD')}}
      />
    </div>
  </div>
</template>
```

### `@formatOptions`

`@formatOptions` is passed straight to `Intl.NumberFormat`, and which number it
formats depends on the `style`:

| `style`                          | What is formatted                        | `@progress={{50}}` on a 0–100 scale |
| -------------------------------- | ---------------------------------------- | ----------------------------------- |
| `percent`                        | The position on the scale, as a fraction | `50%`                               |
| `decimal`, `currency`, `unit`, … | The raw `@progress` value                | `50`, `$50.00`, …                   |

`Intl` scales a `percent` style by 100 itself, so it is handed the fraction
rather than the already-computed percentage — otherwise `50` would be announced
as `5,000%`. Because it formats the _position_, a `percent` style respects
`@minValue`/`@maxValue`: `@progress={{20}}` on a 10–30 scale reads `50%`.

```gts preview
import { ProgressBar } from 'frontile';
import { hash } from '@ember/helper';

<template>
  <div class='demo-stack'>
    <div class='mt-6 grid grid-cols-2 gap-4 items-end'>
      <ProgressBar
        @progress={{50}}
        @label='Percent style'
        @formatOptions={{(hash style='percent')}}
      />
      <ProgressBar
        @progress={{20}}
        @minValue={{10}}
        @maxValue={{30}}
        @label='Percent style, 10–30 scale'
        @formatOptions={{(hash style='percent')}}
      />
    </div>
  </div>
</template>
```

With no `@formatOptions` and no `@valueLabel`, the value label is the position
rounded to a whole percentage — `50%`.

## Out-of-range values

The rendered width is clamped to 0–100%, so a `@progress` above `@maxValue` fills
the track rather than overflowing it, and one below `@minValue` (or negative)
renders empty. A `@minValue` equal to `@maxValue` has no meaningful position and
renders at 0% instead of emitting an invalid width.

`aria-valuenow` is clamped to the same range. Assistive technology derives the
percentage it announces from `aria-valuenow` against
`aria-valuemin`/`aria-valuemax`, so reporting a raw `150` would announce "150%"
to a screen-reader user while the bar sits pinned at 100% for everyone else —
the people who cannot see the bar would be the only ones given the wrong
number. ARIA also requires `aria-valuenow` to fall within the declared range.

In the demo below, both bars report a value on the scale — `100` and `0` —
matching what they render.

```gts preview
import { ProgressBar } from 'frontile';

<template>
  <div class='demo-stack'>
    <div class='grid grid-cols-2 gap-4 items-end'>
      <ProgressBar @progress={{150}} @label='Progress of 150' />
      <ProgressBar @progress={{-20}} @label='Progress of -20' />
    </div>
  </div>
</template>
```

Clamping is a display safeguard, not validation — nothing warns about an
out-of-range value, since a legitimately jittery source (a byte count
overshooting its total) would warn on every render. A bar pinned at 100% is the
signal.

## ProgressBar Description

```gts preview
import { ProgressBar } from 'frontile';

<template>
  <div class='demo-stack'>
    <ProgressBar
      @progress={{50}}
      @label='Uploading'
      @description='Estimated time left'
    />
  </div>
</template>
```

## Indeterminate

Pass `@isIndeterminate` when the effort or duration cannot be calculated.

```gts preview
import { ProgressBar } from 'frontile';

<template>
  <div class='demo-stack'>
    <ProgressBar @size='md' @label='Progress' @isIndeterminate={{true}} />
  </div>
</template>
```

## Customization

`@class` merges into the track's own classes through Tailwind Merge, so a
conflicting utility replaces the theme's rather than fighting it.

```gts preview
import { ProgressBar } from 'frontile';

<template>
  <div class='demo-stack'>
    <div class='grid grid-cols-2 gap-4'>
      <ProgressBar @progress={{70}} @label='Default track' />
      <ProgressBar
        @progress={{70}}
        @label='Taller track'
        @class='h-6 rounded-none'
      />
    </div>
  </div>
</template>
```

## Accessibility

The filled element carries `role="progressbar"` with `aria-valuemin`,
`aria-valuemax`, and `aria-valuenow`, so assistive technology reports the
position on the scale you defined rather than a raw percentage.

| Argument                | What it does for assistive technology                                                            |
| ----------------------- | ------------------------------------------------------------------------------------------------ |
| `@label`                | Becomes the progress bar's accessible name, wired with `aria-labelledby`.                        |
| `@minValue`/`@maxValue` | Set the scale, so `@progress={{20}}` on a 10–30 scale is reported as halfway rather than as 20%. |
| `@description`          | Visible text only. It is **not** associated with the progress bar.                               |

`aria-valuenow` is clamped to `@minValue`/`@maxValue`; see
[Out-of-range values](#out-of-range-values).

### `@label` is what names it

There is no other way to name the progress bar. `...attributes` lands on the
outer wrapper, not on the `role="progressbar"` element, so an `aria-label`
passed from outside does not reach it — a bar with no `@label` is announced as
an unnamed progress bar.

If the label should not be visible, `@showValueLabel={{false}}` only hides the
value; keep `@label` and hide the whole row visually instead:

```gts preview
import { ProgressBar, VisuallyHidden } from 'frontile';

<template>
  <div class='demo-stack'>
    <ProgressBar @progress={{40}} @label='Visible label' />

    <VisuallyHidden>
      <ProgressBar @progress={{40}} @label='Upload progress' />
    </VisuallyHidden>
    <p class='text-neutral'>
      The second bar above is present and named, but hidden — not a pattern to
      reach for often, since it hides the bar from sighted users too.
    </p>
  </div>
</template>
```

### Indeterminate bars report no value

When `@isIndeterminate` is set, `aria-valuenow` is omitted entirely rather than
sent as a number. That is what ARIA requires: a value of `0` would be announced
as "0%", which is a claim about progress, where the point of an indeterminate
bar is that no such claim can be made. See the
[Indeterminate](#indeterminate) demo above; the value label is suppressed in that
state too, for the same reason.

### Progress is not an announcement

A progress bar updating is a visual change; nothing announces it. Do not wrap it
in an `aria-live` region to compensate — a bar ticking from 1% to 100% would
interrupt the screen reader on every step. Announce the outcome instead, once,
when the work finishes.

Colour alone should not carry the meaning of `@intent`. A `danger` bar reads as
a problem to a sighted user and as an ordinary bar to everyone else, so put the
state in the `@label` or `@description` as well.

## API

### ProgressBar

**Element:** `HTMLDivElement`

**Arguments**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `class` | `string` | - | Custom class name, it will override the default ones using Tailwind Merge library. |
| `color` | `'neutral' \| 'primary' \| 'secondary' \| 'tertiary' \| 'success' \| 'warning' \| 'danger'` | - | The color of the progress bar |
| `description` | `string` | - | The content to display as the description. |
| `formatOptions` | `Object` | - | The display format of the value, passed to Intl.NumberFormat. A percent style formats the position on the min/max scale as a fraction; every other style formats the raw progress value. With no format options, the value is displayed as a whole percentage. |
| `intent` | `'default' \| 'primary' \| 'secondary' \| 'tertiary' \| 'success' \| 'warning' \| 'danger'` | - | **Deprecated.** Use `color`. `default` is now `neutral`. |
| `isIndeterminate` | `boolean` | `false` | Whether presentation is indeterminate when progress isn't known. |
| `label` | `string` | - | The content to display as the label. |
| `maxValue` | `number` | `100` | The largest value allowed for the input |
| `minValue` | `number` | `0` | The smallest value allowed for the input |
| `progress` | `number` | - | The current progress value |
| `radius` | `'sm' \| 'lg' \| 'none' \| 'full'` | - | The radius the progress bar |
| `showValueLabel` | `boolean` | - | Whether the value's label is displayed. True by default if there's a label, false by default if not. |
| `size` | `'sm' \| 'md' \| 'lg' \| 'xs'` | - | The size of the progress bar |
| `valueLabel` | `string` | - | The content to display as the value's label (e.g. 1 of 4). |

**Blocks**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `default *` | `[]` | - |  |

---

# Command

Source: /docs/components/collections/command.md

# Command

A command palette: a search field over a ranked, optionally grouped list of commands or
destinations. Results are ordered by how well they match, so the closest one is always first.

## Import

```js
import { Command, CommandDialog } from 'frontile';
```

## Usage

The usual form is a dialog, opened from a button or from a keyboard shortcut anywhere on the
page. `mod` is Cmd on Apple platforms and Ctrl elsewhere — press it now. Pass an array to
accept several, e.g. `@shortcut={{array "/" "mod+k"}}`.

```gts preview collapsible
import Component from '@glimmer/component';
import { tracked } from '@glimmer/tracking';
import { on } from '@ember/modifier';
import { CommandDialog, Button, Kbd } from 'frontile';
import {
  UserIcon,
  StarIcon,
  SearchIcon,
  CodeIcon
} from 'site/components/icons';

const commands = [
  {
    key: 'calendar',
    label: 'Calendar',
    section: 'Suggestions',
    Icon: StarIcon
  },
  {
    key: 'search-emoji',
    label: 'Search Emoji',
    section: 'Suggestions',
    Icon: SearchIcon
  },
  {
    key: 'calculator',
    label: 'Calculator',
    section: 'Suggestions',
    Icon: CodeIcon
  },
  {
    key: 'profile',
    label: 'Profile',
    section: 'Settings',
    Icon: UserIcon,
    shortcut: 'mod+p'
  },
  {
    key: 'billing',
    label: 'Billing',
    section: 'Settings',
    Icon: CodeIcon,
    shortcut: 'mod+b'
  },
  {
    key: 'settings',
    label: 'Settings',
    section: 'Settings',
    Icon: CodeIcon,
    shortcut: 'mod+s'
  }
];

export default class CommandDialogExample extends Component {
  @tracked isOpen = false;
  @tracked lastSelected;

  open = () => (this.isOpen = true);
  close = () => (this.isOpen = false);

  select = (key) => {
    this.lastSelected = key;
    this.isOpen = false;
  };

  <template>
    <div class='demo-stack items-center'>
      <div class='flex items-center gap-4'>
        <Button @variant='outline' {{on 'click' this.open}}>
          Open palette
          <Kbd @keys='mod+k' @size='sm' @variant='outline' @class='ml-2' />
        </Button>
        {{#if this.lastSelected}}
          <span class='font-body text-body-sm text-neutral'>Selected:
            {{this.lastSelected}}</span>
        {{/if}}
      </div>

      <CommandDialog
        @isOpen={{this.isOpen}}
        @onOpen={{this.open}}
        @onClose={{this.close}}
        @onSelect={{this.select}}
        @shortcut='mod+k'
        @items={{commands}}
        @groupBy='section'
        @label='Search commands'
        @placeholder='Type a command or search…'
        as |c|
      >
        <c.Input />
        <c.List>
          <:item as |ctx|>
            <ctx.Item @key={{ctx.key}} @shortcut={{ctx.item.shortcut}}>
              <:start><ctx.item.Icon /></:start>
              <:default>{{ctx.label}}</:default>
            </ctx.Item>
          </:item>
          <:empty>No results for "{{c.query}}"</:empty>
        </c.List>
        <c.Footer />
      </CommandDialog>
    </div>
  </template>
}
```

The dialog opens with a short scale-and-rise and honors `prefers-reduced-motion` by keeping
the fade but dropping the movement. An unmodified shortcut such as `/` is ignored while the
user is typing in a field, so it still types a slash in a text input.

## Anatomy

`Command` yields the palette's parts plus its current state, so you compose the layout rather
than configuring it. The same parts are yielded by `CommandDialog`.

```gts preview
import { Command } from 'frontile';

const commands = [
  { key: 'profile', label: 'Profile' },
  { key: 'billing', label: 'Billing' }
];

<template>
  <div class='demo-stack'>
    <Command @items={{commands}} @isBordered={{true}} as |c|>
      {{! the search field — carries the combobox semantics }}
      <c.Input @placeholder='Search…' />

      {{! the results — ranked, grouped, keyboard navigable }}
      <c.List>
        <:item as |ctx|>
          {{! ctx yields the item, its key, its label, and a bound Item component }}
          <ctx.Item @key={{ctx.key}}>{{ctx.label}}</ctx.Item>
        </:item>
        <:empty>Nothing matched.</:empty>
        <:loading>Searching…</:loading>
        {{! async only: shown before anything has been typed }}
        <:prompt>Start typing to search.</:prompt>
      </c.List>

      {{! keyboard hints; c.query, c.resultCount and c.isLoading are yielded too }}
      <c.Footer />
    </Command>
  </div>
</template>
```

## Inline

`Command` on its own renders in place — for a page-level search, a sidebar, or inside a
custom overlay. `@isBordered` draws its own surface.

```gts preview
import { Command } from 'frontile';

const commands = [
  { key: 'profile', label: 'Profile' },
  { key: 'billing', label: 'Billing' },
  { key: 'settings', label: 'Settings' },
  { key: 'calendar', label: 'Calendar' },
  { key: 'search-emoji', label: 'Search Emoji' }
];

<template>
  <div class='demo-stack'>
    <Command
      @items={{commands}}
      @isBordered={{true}}
      @placeholder='Type a command or search…'
      as |c|
    >
      <c.Input />
      <c.List>
        <:item as |ctx|>
          <ctx.Item @key={{ctx.key}}>{{ctx.label}}</ctx.Item>
        </:item>
      </c.List>
    </Command>
  </div>
</template>
```

## Ranking

The default filter ranks by relevance rather than filtering in place, which is what keeps an
exact match from being buried under a longer name that merely contains the query. Type `button`
below: `Button` stays on top even though `ButtonGroup` comes first in the array.

It also matches acronyms — try `bg` for ButtonGroup, or `tb` for ToggleButton.

```gts preview
import { Command } from 'frontile';

const components = [
  { key: 'button-group', label: 'ButtonGroup' },
  { key: 'toggle-button', label: 'ToggleButton' },
  { key: 'close-button', label: 'CloseButton' },
  { key: 'button', label: 'Button' },
  { key: 'checkbox-group', label: 'CheckboxGroup' }
];

<template>
  <div class='demo-stack'>
    <Command
      @items={{components}}
      @isBordered={{true}}
      @placeholder="Try 'button' or 'bg'…"
      as |c|
    >
      <c.Input />
      <c.List>
        <:item as |ctx|>
          <ctx.Item @key={{ctx.key}}>{{ctx.label}}</ctx.Item>
        </:item>
      </c.List>
    </Command>
  </div>
</template>
```

By default only the item's label is searched. `@searchFields` searches more than that — a
category, keywords — with the first field primary and the rest down-weighted and combined by
max, so a weak hit on a category never outranks a strong hit on the label.

```gts preview
import { Command } from 'frontile';

const components = [
  { key: 'button', label: 'Button', section: 'Buttons' },
  { key: 'chip', label: 'Chip', section: 'Buttons' },
  { key: 'modal', label: 'Modal', section: 'Overlays' }
];

const searchFields = (item) => [item.label, item.section];

<template>
  <div class='demo-stack'>
    <Command
      @items={{components}}
      @searchFields={{searchFields}}
      @isBordered={{true}}
      @placeholder="Try 'overlays'…"
      as |c|
    >
      <c.Input />
      <c.List>
        <:item as |ctx|>
          <ctx.Item @key={{ctx.key}} @description={{ctx.item.section}}>
            {{ctx.label}}
          </ctx.Item>
        </:item>
      </c.List>
    </Command>
  </div>
</template>
```

Pass `@filter` to score items yourself. Return a number to rank — higher first, `0` for no
match — or a boolean to filter without reordering.

```gts preview
import { Command } from 'frontile';
import { createFuzzyFilter } from 'frontile/utils/filter';

// A lower threshold trades precision for recall: this matches `btn` to Button.
const looseFilter = createFuzzyFilter({ threshold: 0 });

const components = [
  { key: 'button', label: 'Button' },
  { key: 'checkbox', label: 'Checkbox' },
  { key: 'table', label: 'Table' }
];

<template>
  <div class='demo-stack'>
    <Command
      @items={{components}}
      @filter={{looseFilter}}
      @isBordered={{true}}
      @placeholder="Try 'btn'…"
      as |c|
    >
      <c.Input />
      <c.List>
        <:item as |ctx|>
          <ctx.Item @key={{ctx.key}}>{{ctx.label}}</ctx.Item>
        </:item>
      </c.List>
    </Command>
  </div>
</template>
```

## Grouping

`@groupBy` sections the results under headings. A group whose items all filter out disappears
entirely — heading and separator with it — because sections are built from the ranked results
rather than declared as markup. Type `cal` below and watch Settings go.

By default groups are ordered by their best-scoring member, so the closest match is always on
top. `@groups` pins the groups you name to the top, in that order — anything not named still
renders after them, so pinning a "Recent" section cannot hide search results.

```gts preview collapsible
import { Command } from 'frontile';
import { array } from '@ember/helper';

const commands = [
  { key: 'calendar', label: 'Calendar', section: 'Suggestions' },
  { key: 'search-emoji', label: 'Search Emoji', section: 'Suggestions' },
  { key: 'calculator', label: 'Calculator', section: 'Suggestions' },
  { key: 'profile', label: 'Profile', section: 'Settings' },
  { key: 'billing', label: 'Billing', section: 'Settings' },
  { key: 'settings', label: 'Settings', section: 'Settings' }
];

<template>
  <div class='demo-stack'>
    <Command
      @items={{commands}}
      @groupBy='section'
      @groups={{array 'Suggestions' 'Settings'}}
      @disabledKeys={{array 'calculator'}}
      @isBordered={{true}}
      @placeholder='Type a command or search…'
      as |c|
    >
      <c.Input />
      <c.List>
        <:item as |ctx|>
          <ctx.Item @key={{ctx.key}}>{{ctx.label}}</ctx.Item>
        </:item>
      </c.List>
    </Command>
  </div>
</template>
```

## Rows

Rows are `Listbox` options, so they take the same `:start` / `:end` blocks, `@shortcut` and
`@description`. Icons in `:start` are sized and muted for you.

```gts preview
import { Command } from 'frontile';
import { UserIcon, StarIcon, SearchIcon } from 'site/components/icons';

const commands = [
  { key: 'profile', label: 'Profile', shortcut: 'mod+p', Icon: UserIcon },
  { key: 'favorites', label: 'Favorites', shortcut: 'mod+f', Icon: StarIcon },
  { key: 'search', label: 'Search', shortcut: 'mod+k', Icon: SearchIcon }
];

<template>
  <div class='demo-stack'>
    <Command @items={{commands}} @isBordered={{true}} as |c|>
      <c.Input @placeholder='Search…' />
      <c.List>
        <:item as |ctx|>
          <ctx.Item @key={{ctx.key}} @shortcut={{ctx.item.shortcut}}>
            <:start><ctx.item.Icon /></:start>
            <:default>{{ctx.label}}</:default>
          </ctx.Item>
        </:item>
      </c.List>
    </Command>
  </div>
</template>
```

## Footer

`c.Footer` renders the palette's keyboard hints. Give it a block to say something else — it
yields `Kbd` for a keycap and `Hint` for one hint's layout, so custom hints match the
built-in ones without copying any classes.

```gts preview
import { Command } from 'frontile';

const commands = [
  { key: 'button', label: 'Button' },
  { key: 'checkbox', label: 'Checkbox' }
];

<template>
  <div class='demo-stack'>
    <Command @items={{commands}} @isBordered={{true}} @size='sm' as |c|>
      <c.Input @placeholder='Search components…' />
      <c.List>
        <:item as |ctx|>
          <ctx.Item @key={{ctx.key}}>{{ctx.label}}</ctx.Item>
        </:item>
      </c.List>
      <c.Footer as |f|>
        <f.Hint><f.Kbd @keys='enter' /> Go to page</f.Hint>
        <f.Hint><f.Kbd @keys='mod+c' /> Copy link</f.Hint>
      </c.Footer>
    </Command>
  </div>
</template>
```

## Async search

Pass `@onSearch` to fetch results instead of filtering `@items`. It is debounced, and stale
responses are discarded so the latest query always wins — a slow early request can never
overwrite a newer one. Built-in filtering is disabled, since the server did the filtering.

Before anything is typed an async palette has nothing to show and nothing to report, so it
renders the `:prompt` block rather than claiming there are no results.

```gts preview collapsible
import Component from '@glimmer/component';
import { Command } from 'frontile';

const ALL = [
  'Argentina',
  'Australia',
  'Austria',
  'Brazil',
  'Canada',
  'Denmark',
  'Finland',
  'France',
  'Germany',
  'Japan',
  'Mexico',
  'Netherlands',
  'New Zealand',
  'Norway',
  'Poland',
  'South Africa',
  'Spain',
  'Sweden'
];

export default class AsyncCommandExample extends Component {
  search = async (query) => {
    // Stand-in for a network request.
    await new Promise((resolve) => setTimeout(resolve, 400));

    if (!query) return [];

    return ALL.filter((name) =>
      name.toLowerCase().includes(query.toLowerCase())
    ).map((name) => ({ key: name.toLowerCase(), label: name }));
  };

  <template>
    <div class='demo-stack'>
      <Command
        @onSearch={{this.search}}
        @isBordered={{true}}
        @placeholder='Search countries…'
        as |c|
      >
        <c.Input />
        <c.List>
          <:item as |ctx|>
            <ctx.Item @key={{ctx.key}}>{{ctx.label}}</ctx.Item>
          </:item>
          <:loading>Searching…</:loading>
          <:prompt>Search for a country…</:prompt>
          <:empty>No matches for "{{c.query}}"</:empty>
        </c.List>
      </Command>
    </div>
  </template>
}
```

To filter externally without `@onSearch` — against a store you already have, say — use
`@disableFiltering` with `@query` and `@onQueryChange`.

## Mixing static and remote results

A real palette usually has both: navigation and recents you already hold, plus records that
only the server can find. `@onSearch` alone does not cover this — when it is set, the resolved
results **replace** `@items`, and local filtering is off, so static entries would disappear as
soon as the first response landed.

Instead, own the merge and reuse the library's own scorer, which is exported:

```gts preview collapsible
import Component from '@glimmer/component';
import { tracked } from '@glimmer/tracking';
import { Command } from 'frontile';
import { filterAndRankItems } from 'frontile/utils/filter';
import { array } from '@ember/helper';

const NAVIGATION = [
  { key: 'nav:accounts', label: 'Accounts', section: 'Navigation' },
  { key: 'nav:billing', label: 'Billing', section: 'Navigation' },
  { key: 'nav:settings', label: 'Settings', section: 'Navigation' }
];

const RECENTS = [{ key: 'recent:acme', label: 'Acme Corp', section: 'Recent' }];

// Stand-in for a server that matches fields the client never sees — here, a
// trade name. Try "acme": the second row has no "acme" in its label at all.
const REMOTE = [
  { key: 'acct:1', label: 'Wile E. Coyote Enterprises', section: 'Accounts' },
  { key: 'acct:2', label: 'Acme Anvils LLC', section: 'Accounts' }
];

export default class MixedCommandExample extends Component {
  @tracked query = '';
  @tracked remote = [];
  @tracked isLoading = false;

  updateQuery = async (query) => {
    this.query = query;

    if (!query.trim()) {
      this.remote = [];
      return;
    }

    this.isLoading = true;
    await new Promise((resolve) => setTimeout(resolve, 300));
    this.remote = REMOTE;
    this.isLoading = false;
  };

  // Static entries are ranked with the same scorer the component would use.
  // Remote entries are appended as-is: the server already decided.
  get items() {
    const local =
      filterAndRankItems(
        [...RECENTS, ...NAVIGATION],
        this.query,
        (item) => item.label
      ) ?? [];

    return [...local, ...this.remote];
  }

  <template>
    <div class='demo-stack'>
      <Command
        @items={{this.items}}
        @query={{this.query}}
        @onQueryChange={{this.updateQuery}}
        @isLoading={{this.isLoading}}
        @disableFiltering={{true}}
        @groupBy='section'
        @groups={{array 'Recent' 'Navigation' 'Accounts'}}
        @isBordered={{true}}
        @placeholder="Try 'acme'…"
        as |c|
      >
        <c.Input />
        <c.List>
          <:item as |ctx|>
            <ctx.Item @key={{ctx.key}} @description={{ctx.item.section}}>
              {{ctx.label}}
            </ctx.Item>
          </:item>
          <:empty>No results for "{{c.query}}"</:empty>
        </c.List>
      </Command>
    </div>
  </template>
}
```

Three things make this work:

- **`@disableFiltering`** stops the component re-filtering your remote results. This is the
  part that bites: the server often matches on fields the client cannot see, so running the
  local fuzzy filter over its output silently discards legitimate hits — the
  `Wile E. Coyote Enterprises` row above would score `0` against `acme` and vanish.
- **`filterAndRankItems`**, exported from `frontile/utils/filter`, ranks the static half with
  exactly the same scorer, so the two halves feel consistent. It takes the same
  `labelFor`/`@filter` shapes the component does, including an array of fields.
- **`@groups`** keeps the halves in separate, pinned sections, so you never have to decide
  whether a remote hit should outrank a nav item. Groups with nothing left disappear on their
  own — type `acme` and Navigation drops out.

Debounce the fetch and discard stale responses yourself here; that is what `@onSearch` would
otherwise have done for you.

## Sizes

`@size` sets how tall the results area is. The list keeps a minimum height on purpose: without
one the palette collapses and re-expands on every keystroke as results narrow, which reads as
jitter.

```gts preview
import { Command } from 'frontile';
import { array } from '@ember/helper';

const commands = [
  { key: 'profile', label: 'Profile' },
  { key: 'billing', label: 'Billing' }
];

<template>
  <div class='demo-stack'>
    {{#each (array 'sm' 'md' 'lg') as |size|}}
      <Command @items={{commands}} @size={{size}} @isBordered={{true}} as |c|>
        <c.Input @placeholder='size={{size}}' />
        <c.List>
          <:item as |ctx|>
            <ctx.Item @key={{ctx.key}}>{{ctx.label}}</ctx.Item>
          </:item>
        </c.List>
      </Command>
    {{/each}}
  </div>
</template>
```

## Accessibility

`Command` implements the ARIA combobox-with-list-autocomplete pattern. The combobox semantics
live on the **input** — not on a wrapper — so focus never leaves the field while the user
arrows through results.

| Key                     | Behavior                                          |
| ----------------------- | ------------------------------------------------- |
| `ArrowDown` / `ArrowUp` | Move the active option, crossing group boundaries |
| `Home` / `PageUp`       | Activate the first option                         |
| `End` / `PageDown`      | Activate the last option                          |
| `Enter`                 | Select the active option                          |
| `Escape`                | Close the dialog                                  |

Provided for you:

- `role="combobox"` and `aria-autocomplete="list"` on the input, with `aria-activedescendant`
  pointing at the active option's id. `aria-expanded` reflects whether the listbox is actually
  rendered, and `aria-controls` is only set while it is — an empty result set replaces the
  listbox, so neither is left claiming a popup that is not there.
- A debounced `aria-live="polite"` region announcing "N results available" / "No results
  found", so the result count is not silent to a screen reader.
- `role="listbox"` on the list and `role="option"` with `aria-selected` on each row. Groups
  render as `role="group"` labelled by their heading, with the intervening list marked
  `role="none"` so the `listbox` → `option` ownership chain stays intact.
- Disabled rows (via `@disabledKeys`) get `aria-disabled` and cannot be selected.
- The dialog traps focus, focuses the input on open, and restores focus on close.

What you must supply:

- `@label` — the input's accessible name. Defaults to `"Search"`, which is rarely specific
  enough when a page has more than one search.
- Meaningful row text. An icon-only row needs its own accessible name.

The combobox keeps `aria-activedescendant` synchronized with the active option while keyboard
navigation crosses groups and skips disabled rows.

## API

### Command

A command palette: a search input over a ranked, optionally grouped list.

Composed of the same primitives as Autocomplete — an input driving a
Listbox through ListManager — rather than reimplementing keyboard
navigation, option roles or active-item tracking.

**Element:** `HTMLDivElement`

**Arguments**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `class` | `string` | - |  |
| `classes` | `SlotsToClasses<'loading' \| 'base' \| 'input' \| 'footer' \| 'inputWrapper' \| 'inputIcon' \| 'list' \| 'empty' \| 'footerHint' \| 'kbd'>` | - |  |
| `disabledKeys` | `string[]` | - |  |
| `disableFiltering` | `boolean` | `false` | Render @items as given, without filtering or ranking. Use with @query/@onQueryChange when filtering happens elsewhere. |
| `filter` | `FilterFn` | - | Scores or matches an item against the query. Defaults to a relevance filter; see {@link FilterFn}. |
| `groupBy` | `string \| ((item: T) => string)` | - | Groups results under headings. Either a property name on the item or a function returning the heading. Items with no group render ungrouped, ahead of any groups. |
| `groups` | `string[]` | - | Pins these groups to the top, in this order. Any group not listed still renders, after them, ordered by its best-scoring member — so pinning a "Recent" section cannot hide search results. When omitted, every group is ordered by its best-scoring member, so the closest match is always on top. |
| `isBordered` | `boolean` | - | Draw the palette's own surface, for use outside a dialog. |
| `isLoading` | `boolean` | - | Show the loading state regardless of @onSearch. |
| `items` | `T[]` | - | The items to search. Ranked and grouped by the component unless @disableFiltering is set or @onSearch is provided. |
| `label` | `string` | `'Search'` | Accessible name for the search input. |
| `onQueryChange` | `(query: string) => void` | - |  |
| `onSearch` | `(query: string) => T[] \| Promise<T[]>` | - | Async search. Called (debounced) as the user types; the resolved items are rendered and a loading state shows while pending. Stale responses are discarded, so the latest query always wins. Built-in filtering is disabled, and @items is the list shown before the first search. The resolved items replace @items — this is for a wholly remote list. To combine static entries (navigation, recents) with remote ones, do not use @onSearch: merge them yourself into @items, set @disableFiltering, and rank the static half with filterAndRankItems from frontile/utils/filter. See "Mixing static and remote results" in the docs. |
| `onSelect` | `(key: string, item?: T) => void` | - | Called when an item is chosen, by click or by Enter. |
| `placeholder` | `string` | - |  |
| `query` | `string` | - | The query text. Pass with @onQueryChange to control it. |
| `searchDebounce` | `number` | `250` | Debounce applied to @onSearch, in milliseconds. |
| `searchFields` | `(item: T) => string \| string[]` | - | The text searched for each item. Defaults to its label. Return several fields to search more than the label — a category, say, or keywords. The first is primary; the rest are down-weighted and combined by max, so a weak hit on a secondary field never outranks a strong hit on the label. |
| `size` | `'sm' \| 'md' \| 'lg'` | `'md'` |  |

**Blocks**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `default *` | `[CommandApi<T>]` | - |  |
### CommandInput

The palette's search field.

Carries the combobox semantics itself — role, aria-expanded,
aria-controls and aria-activedescendant all belong on the input, not on a
wrapper, so a screen reader announces the active option while focus never
leaves the field.

**Element:** `HTMLInputElement`

**Arguments**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `activeDescendant` | `string` | - | _(internal)_ |
| `classes` | `SlotsToClasses<'loading' \| 'base' \| 'input' \| 'footer' \| 'inputWrapper' \| 'inputIcon' \| 'list' \| 'empty' \| 'footerHint' \| 'kbd'>` | - |  |
| `controlsId` | `string` | - | _(internal)_ |
| `hasResults` | `boolean` | - | _(internal)_ |
| `label` | `string` | `'Search'` | Accessible name for the input. |
| `onInput` | `(value: string) => void` | - | _(internal)_ |
| `placeholder` | `string` | - |  |
| `setup` | `ModifierLike<{ Element: HTMLInputElement; }>` | - | _(internal)_ |
| `value` | `string` | - | _(internal)_ |

**Blocks**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `icon *` | `[]` | - | Replaces the leading search icon. |
### CommandList

Renders the ranked results.

Sections come from the ranked data rather than from markup, so a group whose
items all filtered out is simply not rendered — heading, wrapper and
separator disappear together, with no visibility tracking or forceMount
escape hatch. Reordering is a keyed {{#each}} over a sorted array, which
Glimmer handles natively.

**Element:** `HTMLUListElement`

**Arguments**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `classes` | `SlotsToClasses<'loading' \| 'base' \| 'input' \| 'footer' \| 'inputWrapper' \| 'inputIcon' \| 'list' \| 'empty' \| 'footerHint' \| 'kbd'>` | - |  |
| `disabledKeys` | `string[]` | - |  |
| `groups` | `CommandGroup<T>[]` | - | _(internal)_ |
| `id` | `string` | - | _(internal)_ |
| `inputElement` | `HTMLInputElement` | - | _(internal)_ |
| `isLoading` | `boolean` | - | _(internal)_ |
| `isSearchPrompt` | `boolean` | - | _(internal)_ |
| `onActiveItemChange` | `(key?: string, item?: ListItem) => void` | - | _(internal)_ |
| `onSelect` | `(key: string) => void` | - | _(internal)_ |
| `size` | `'sm' \| 'md' \| 'lg'` | - |  |

**Blocks**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `item *` | `[{ item: T; key: string; label: string; Item: ListboxItem (manager bound); }]` | - |  |
| `empty *` | `[]` | - |  |
| `loading *` | `[]` | - |  |
| `prompt *` | `[]` | - | Shown by an async palette before anything has been typed. |
### CommandFooter

The bar along the bottom of a palette that teaches its keyboard: how to move,
how to choose, how to leave. Renders sensible defaults when given no block.

**Element:** `HTMLDivElement`

**Arguments**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `classes` | `SlotsToClasses<'loading' \| 'base' \| 'input' \| 'footer' \| 'inputWrapper' \| 'inputIcon' \| 'list' \| 'empty' \| 'footerHint' \| 'kbd'>` | - | _(internal)_ |

**Blocks**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `default *` | `[{ Kbd: CommandKbd (classes bound); Hint: CommandHint (classes bound); }]` | - | Replaces the default hints. Yields a Kbd keycap so custom hints match the built-in ones. |
### CommandDialog

A Command palette in a dialog, with an optional global shortcut.

**Element:** `HTMLDivElement`

**Arguments**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `isOpen *` | `boolean` | - |  |
| `backdrop` | `'faded' \| 'none' \| 'transparent' \| 'blur'` | - |  |
| `class` | `string` | - |  |
| `classes` | `SlotsToClasses<'loading' \| 'base' \| 'input' \| 'footer' \| 'inputWrapper' \| 'inputIcon' \| 'list' \| 'empty' \| 'footerHint' \| 'kbd'>` | - |  |
| `didClose` | `() => void` | - |  |
| `disabledKeys` | `string[]` | - |  |
| `disableFiltering` | `boolean` | `false` | Render @items as given, without filtering or ranking. Use with @query/@onQueryChange when filtering happens elsewhere. |
| `disableTransitions` | `boolean` | - |  |
| `filter` | `FilterFn` | - | Scores or matches an item against the query. Defaults to a relevance filter; see {@link FilterFn}. |
| `groupBy` | `string \| ((item: T) => string)` | - | Groups results under headings. Either a property name on the item or a function returning the heading. Items with no group render ungrouped, ahead of any groups. |
| `groups` | `string[]` | - | Pins these groups to the top, in this order. Any group not listed still renders, after them, ordered by its best-scoring member — so pinning a "Recent" section cannot hide search results. When omitted, every group is ordered by its best-scoring member, so the closest match is always on top. |
| `isBordered` | `boolean` | - | Draw the palette's own surface, for use outside a dialog. |
| `isLoading` | `boolean` | - | Show the loading state regardless of @onSearch. |
| `items` | `T[]` | - | The items to search. Ranked and grouped by the component unless @disableFiltering is set or @onSearch is provided. |
| `label` | `string` | `'Search'` | Accessible name for the search input. |
| `onClose` | `() => void` | - |  |
| `onOpen` | `() => void` | - |  |
| `onQueryChange` | `(query: string) => void` | - |  |
| `onSearch` | `(query: string) => T[] \| Promise<T[]>` | - | Async search. Called (debounced) as the user types; the resolved items are rendered and a loading state shows while pending. Stale responses are discarded, so the latest query always wins. Built-in filtering is disabled, and @items is the list shown before the first search. The resolved items replace @items — this is for a wholly remote list. To combine static entries (navigation, recents) with remote ones, do not use @onSearch: merge them yourself into @items, set @disableFiltering, and rank the static half with filterAndRankItems from frontile/utils/filter. See "Mixing static and remote results" in the docs. |
| `onSelect` | `(key: string, item?: T) => void` | - | Called when an item is chosen, by click or by Enter. |
| `placeholder` | `string` | - |  |
| `query` | `string` | - | The query text. Pass with @onQueryChange to control it. |
| `searchDebounce` | `number` | `250` | Debounce applied to @onSearch, in milliseconds. |
| `searchFields` | `(item: T) => string \| string[]` | - | The text searched for each item. Defaults to its label. Return several fields to search more than the label — a category, say, or keywords. The first is primary; the rest are down-weighted and combined by max, so a weak hit on a secondary field never outranks a strong hit on the label. |
| `shortcut` | `string \| string[]` | - | Opens the palette from anywhere in the document, e.g. "mod+k" or "/". Requires @onOpen. Pass an array to accept more than one. An unmodified shortcut is ignored while the user is typing in a field, so / still types a slash in a text input. |
| `size` | `'sm' \| 'md' \| 'lg'` | `'md'` |  |

**Blocks**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `default *` | `[CommandApi<T>]` | - |  |

---

# Dropdown

Source: /docs/components/collections/dropdown.md

# Dropdown

A menu activated by a button, representing a set of actions or displaying a list of options for user selection. Built on top of Popover and Listbox components with keyboard navigation support.

## Import

```js
import { Dropdown } from 'frontile';
```

## Usage

### Basic Dropdown

A feature-rich action menu showcasing icons, descriptions, shortcuts, dividers, and color intents.

```gts preview collapsible
import Component from '@glimmer/component';
import { Dropdown } from 'frontile';
import {
  ViewIcon,
  EditIcon,
  DuplicateIcon,
  ShareIcon,
  DownloadIcon,
  ArchiveIcon,
  DeleteIcon
} from 'site/components/icons';

export default class BasicDropdown extends Component {
  onAction = (key: string) => {
    // eslint-disable-next-line
    console.log('Action triggered:', key);
  };

  <template>
    <Dropdown as |d|>
      <d.Trigger @color='primary' @size='sm'>
        Project Actions
      </d.Trigger>

      <d.Menu @onAction={{this.onAction}} as |Item|>
        <Item
          @key='view'
          @description='Open in read-only mode'
          @shortcut='mod+o'
        >
          <:start><ViewIcon /></:start>
          <:default>View Details</:default>
        </Item>
        <Item
          @key='edit'
          @description='Make changes to project'
          @shortcut='mod+e'
        >
          <:start><EditIcon /></:start>
          <:default>Edit Project</:default>
        </Item>
        <Item
          @key='duplicate'
          @description='Create a copy'
          @shortcut='mod+d'
          @withDivider={{true}}
        >
          <:start><DuplicateIcon /></:start>
          <:default>Duplicate</:default>
        </Item>
        <Item
          @key='share'
          @color='primary'
          @description='Invite team members'
          @shortcut='mod+shift+s'
        >
          <:start><ShareIcon /></:start>
          <:default>Share</:default>
        </Item>
        <Item @key='export' @color='success' @description='Download as file'>
          <:start><DownloadIcon /></:start>
          <:default>Export</:default>
        </Item>
        <Item
          @key='archive'
          @color='warning'
          @description='Move to archived projects'
          @withDivider={{true}}
        >
          <:start><ArchiveIcon /></:start>
          <:default>Archive Project</:default>
        </Item>
        <Item
          @key='delete'
          @color='danger'
          @description='Permanently delete'
          @class='text-danger'
          @shortcut='mod+backspace'
        >
          <:start><DeleteIcon /></:start>
          <:default>Delete Project</:default>
        </Item>
      </d.Menu>
    </Dropdown>
  </template>
}
```

### With Descriptions and Shortcuts

Add descriptions and keyboard shortcuts to menu items for better UX.

> **Note:** The `@shortcut` argument is for display purposes only. You'll need to implement actual keyboard shortcut handling in your application using a library or custom implementation.

```gts preview collapsible
import Component from '@glimmer/component';
import { Dropdown } from 'frontile';

export default class DropdownWithDetails extends Component {
  onAction = (key: string) => {
    // eslint-disable-next-line
    console.log('Action:', key);
  };

  <template>
    <Dropdown as |d|>
      <d.Trigger @color='primary' @size='sm'>Account</d.Trigger>

      <d.Menu @onAction={{this.onAction}} @color='primary' as |Item|>
        <Item @key='profile' @description='View and edit your profile'>
          My Profile
        </Item>
        <Item
          @key='settings'
          @description='Manage preferences'
          @shortcut='mod+,'
        >
          Settings
        </Item>
        <Item @key='billing' @description='View billing details'>
          Billing
        </Item>
        <Item
          @key='team'
          @description='Manage team members'
          @withDivider={{true}}
        >
          Team
        </Item>
        <Item @key='logout' @color='danger' @class='text-danger'>
          Log Out
        </Item>
      </d.Menu>
    </Dropdown>
  </template>
}
```

### With Selection

Enable single or multiple selection mode for choosing options.

```gts preview collapsible
import Component from '@glimmer/component';
import { tracked } from '@glimmer/tracking';
import { Dropdown } from 'frontile';

export default class SelectableDropdown extends Component {
  @tracked selectedKeys = ['bold'];

  handleSelectionChange = (keys: Set<string>) => {
    this.selectedKeys = Array.from(keys);
    // eslint-disable-next-line
    console.log('Selected:', this.selectedKeys);
  };

  <template>
    <div class='demo-stack items-center'>
      <Dropdown @closeOnItemSelect={{false}} as |d|>
        <d.Trigger @size='sm'>Text Formatting</d.Trigger>

        <d.Menu
          @selectionMode='multiple'
          @selectedKeys={{this.selectedKeys}}
          @onSelectionChange={{this.handleSelectionChange}}
          as |Item|
        >
          <Item @key='bold'>Bold</Item>
          <Item @key='italic'>Italic</Item>
          <Item @key='underline'>Underline</Item>
          <Item @key='strikethrough'>Strikethrough</Item>
        </d.Menu>
      </Dropdown>

      <div class='text-sm text-neutral-soft'>
        Selected:
        {{this.selectedKeys}}
      </div>
    </div>
  </template>
}
```

### Different Trigger Styles

Customize the trigger button appearance.

```gts preview collapsible
import Component from '@glimmer/component';
import { Dropdown } from 'frontile';

export default class TriggerStyles extends Component {
  onAction = (key: string) => {
    // eslint-disable-next-line
    console.log('Action:', key);
  };

  <template>
    <div class='flex gap-2 flex-wrap'>
      <Dropdown as |d|>
        <d.Trigger @color='neutral' @size='sm'>Default</d.Trigger>
        <d.Menu @onAction={{this.onAction}} as |Item|>
          <Item @key='option1'>Option 1</Item>
          <Item @key='option2'>Option 2</Item>
        </d.Menu>
      </Dropdown>

      <Dropdown as |d|>
        <d.Trigger @color='primary' @size='sm'>Primary</d.Trigger>
        <d.Menu @onAction={{this.onAction}} as |Item|>
          <Item @key='option1'>Option 1</Item>
          <Item @key='option2'>Option 2</Item>
        </d.Menu>
      </Dropdown>

      <Dropdown as |d|>
        <d.Trigger @color='secondary' @size='sm'>Secondary</d.Trigger>
        <d.Menu @onAction={{this.onAction}} as |Item|>
          <Item @key='option1'>Option 1</Item>
          <Item @key='option2'>Option 2</Item>
        </d.Menu>
      </Dropdown>

      <Dropdown as |d|>
        <d.Trigger @color='success' @size='sm'>Success</d.Trigger>
        <d.Menu @onAction={{this.onAction}} as |Item|>
          <Item @key='option1'>Option 1</Item>
          <Item @key='option2'>Option 2</Item>
        </d.Menu>
      </Dropdown>

      <Dropdown as |d|>
        <d.Trigger @color='warning' @size='sm'>Warning</d.Trigger>
        <d.Menu @onAction={{this.onAction}} as |Item|>
          <Item @key='option1'>Option 1</Item>
          <Item @key='option2'>Option 2</Item>
        </d.Menu>
      </Dropdown>

      <Dropdown as |d|>
        <d.Trigger @color='danger' @size='sm'>Danger</d.Trigger>
        <d.Menu @onAction={{this.onAction}} as |Item|>
          <Item @key='option1'>Option 1</Item>
          <Item @key='option2'>Option 2</Item>
        </d.Menu>
      </Dropdown>
    </div>
  </template>
}
```

### Menu Positioning

Control where the menu appears relative to the trigger.

```gts preview collapsible
import Component from '@glimmer/component';
import { tracked } from '@glimmer/tracking';
import { fn } from '@ember/helper';
import { Dropdown, ButtonGroup } from 'frontile';

export default class MenuPositioning extends Component {
  @tracked placement = 'bottom-start';

  placements = [
    'top',
    'top-start',
    'top-end',
    'bottom',
    'bottom-start',
    'bottom-end',
    'left',
    'right'
  ];

  setPlacement = (placement: string) => {
    this.placement = placement;
  };

  onAction = (key: string) => {
    // eslint-disable-next-line
    console.log('Action:', key);
  };

  isSelected = (p: string) => {
    return p === this.placement;
  };

  <template>
    <div class='demo-stack items-center'>
      <div class='flex gap-2 flex-wrap'>
        <ButtonGroup @size='xs' @color='primary' as |g|>
          {{#each this.placements as |p|}}
            <g.ToggleButton
              @isSelected={{this.isSelected p}}
              @onChange={{fn this.setPlacement p}}
            >
              {{p}}
            </g.ToggleButton>
          {{/each}}
        </ButtonGroup>
      </div>

      <div class='flex justify-center items-center h-32'>
        <Dropdown @placement={{this.placement}} as |d|>
          <d.Trigger @color='primary' @size='sm'>
            Menu ({{this.placement}})
          </d.Trigger>

          <d.Menu @onAction={{this.onAction}} as |Item|>
            <Item @key='option1'>Option 1</Item>
            <Item @key='option2'>Option 2</Item>
            <Item @key='option3'>Option 3</Item>
          </d.Menu>
        </Dropdown>
      </div>
    </div>
  </template>
}
```

### Disabled Items

Disable specific menu items.

```gts preview collapsible
import Component from '@glimmer/component';
import { Dropdown } from 'frontile';

export default class DisabledItems extends Component {
  disabledKeys = ['share', 'delete'];

  onAction = (key: string) => {
    // eslint-disable-next-line
    console.log('Action:', key);
  };

  <template>
    <Dropdown as |d|>
      <d.Trigger @color='primary' @size='sm'>File Actions</d.Trigger>

      <d.Menu
        @onAction={{this.onAction}}
        @disabledKeys={{this.disabledKeys}}
        as |Item|
      >
        <Item @key='open'>Open</Item>
        <Item @key='rename'>Rename</Item>
        <Item @key='share'>Share (Coming Soon)</Item>
        <Item @key='download'>Download</Item>
        <Item @key='delete' @color='danger' @class='text-danger'>
          Delete (Unavailable)
        </Item>
      </d.Menu>
    </Dropdown>
  </template>
}
```

### Keep Open on Select

Prevent the menu from closing when items are selected.

```gts preview collapsible
import Component from '@glimmer/component';
import { tracked } from '@glimmer/tracking';
import { Dropdown } from 'frontile';

export default class KeepOpenDropdown extends Component {
  @tracked filters = ['recent'];

  handleSelectionChange = (keys: Set<string>) => {
    this.filters = Array.from(keys);
    // eslint-disable-next-line
    console.log('Filters:', this.filters);
  };

  <template>
    <div class='demo-stack items-center'>
      <Dropdown @closeOnItemSelect={{false}} as |d|>
        <d.Trigger @size='sm'>Filter Options</d.Trigger>

        <d.Menu
          @selectionMode='multiple'
          @selectedKeys={{this.filters}}
          @onSelectionChange={{this.handleSelectionChange}}
          as |Item|
        >
          <Item @key='recent'>Recent</Item>
          <Item @key='starred'>Starred</Item>
          <Item @key='shared'>Shared with me</Item>
          <Item @key='archived'>Archived</Item>
        </d.Menu>
      </Dropdown>

      <div class='text-sm text-neutral-soft'>
        Active filters:
        {{this.filters}}
      </div>
    </div>
  </template>
}
```

### With Dividers and Sections

Organize menu items into logical groups.

```gts preview collapsible
import Component from '@glimmer/component';
import { Dropdown } from 'frontile';

export default class SectionedDropdown extends Component {
  onAction = (key: string) => {
    // eslint-disable-next-line
    console.log('Action:', key);
  };

  <template>
    <Dropdown as |d|>
      <d.Trigger @color='primary' @size='sm'>More Options</d.Trigger>

      <d.Menu @onAction={{this.onAction}} as |Item|>
        <Item @key='new-file'>New File</Item>
        <Item @key='new-folder'>New Folder</Item>
        <Item @key='upload' @withDivider={{true}}>Upload</Item>
        <Item @key='copy'>Copy</Item>
        <Item @key='move'>Move</Item>
        <Item @key='rename' @withDivider={{true}}>Rename</Item>
        <Item @key='export'>Export</Item>
        <Item @key='share'>Share</Item>
        <Item @key='delete' @color='danger' @class='text-danger'>
          Delete
        </Item>
      </d.Menu>
    </Dropdown>
  </template>
}
```

### Custom Click Handlers

Use individual click handlers for specific items.

```gts preview collapsible
import Component from '@glimmer/component';
import { Dropdown } from 'frontile';

export default class CustomHandlers extends Component {
  handleEdit = () => {
    alert('Edit clicked');
  };

  handleDelete = () => {
    if (confirm('Are you sure you want to delete?')) {
      alert('Deleted!');
    }
  };

  handleDownload = () => {
    alert('Downloading...');
  };

  <template>
    <Dropdown as |d|>
      <d.Trigger @color='primary' @size='sm'>Actions</d.Trigger>

      <d.Menu as |Item|>
        <Item @key='view'>View Details</Item>
        <Item @key='edit' @onClick={{this.handleEdit}}>Edit</Item>
        <Item @key='download' @onClick={{this.handleDownload}}>
          Download
        </Item>
        <Item
          @key='delete'
          @color='danger'
          @class='text-danger'
          @onClick={{this.handleDelete}}
          @withDivider={{true}}
        >
          Delete
        </Item>
      </d.Menu>
    </Dropdown>
  </template>
}
```

### With Backdrop

Control the backdrop appearance behind the dropdown menu.

```gts preview collapsible
import Component from '@glimmer/component';
import { tracked } from '@glimmer/tracking';
import { fn } from '@ember/helper';
import { Dropdown, ButtonGroup } from 'frontile';

export default class DropdownBackdrop extends Component {
  @tracked backdrop = 'none';

  setBackdrop = (type: string) => {
    this.backdrop = type;
  };

  onAction = (key: string) => {
    // eslint-disable-next-line
    console.log('Action:', key);
  };

  isActiveBackdrop = (type: string) => {
    return this.backdrop === type;
  };

  <template>
    <div class='demo-stack items-center'>
      <ButtonGroup @size='xs' @color='primary' as |g|>
        <g.ToggleButton
          @isSelected={{this.isActiveBackdrop 'none'}}
          @onChange={{fn this.setBackdrop 'none'}}
        >
          No Backdrop
        </g.ToggleButton>
        <g.ToggleButton
          @isSelected={{this.isActiveBackdrop 'faded'}}
          @onChange={{fn this.setBackdrop 'faded'}}
        >
          Faded
        </g.ToggleButton>
        <g.ToggleButton
          @isSelected={{this.isActiveBackdrop 'blur'}}
          @onChange={{fn this.setBackdrop 'blur'}}
        >
          Blur
        </g.ToggleButton>
      </ButtonGroup>

      <Dropdown as |d|>
        <d.Trigger @color='primary' @size='sm'>
          Open Menu ({{this.backdrop}})
        </d.Trigger>

        <d.Menu
          @backdrop={{this.backdrop}}
          @onAction={{this.onAction}}
          as |Item|
        >
          <Item @key='option1'>Option 1</Item>
          <Item @key='option2'>Option 2</Item>
          <Item @key='option3'>Option 3</Item>
        </d.Menu>
      </Dropdown>
    </div>
  </template>
}
```

### With Close Callback

Execute a callback when the dropdown closes.

```gts preview
import Component from '@glimmer/component';
import { Dropdown } from 'frontile';

export default class DropdownWithCallback extends Component {
  handleDidClose = () => {
    // eslint-disable-next-line
    console.log('Dropdown closed');
  };

  onAction = (key: string) => {
    // eslint-disable-next-line
    console.log('Action:', key);
  };

  <template>
    <Dropdown @didClose={{this.handleDidClose}} as |d|>
      <d.Trigger @color='primary' @size='sm'>Dropdown</d.Trigger>

      <d.Menu @onAction={{this.onAction}} as |Item|>
        <Item @key='option1'>Option 1</Item>
        <Item @key='option2'>Option 2</Item>
        <Item @key='option3'>Option 3</Item>
      </d.Menu>
    </Dropdown>
  </template>
}
```

### With Submenus

Group related actions behind a nested menu. `Sub` is a second, optional block
param yielded by `d.Menu` alongside `Item` — existing `as |Item|` code keeps
working unchanged, and you only reach for `Sub` where a nested menu is
actually needed. Submenus open on hover, on click, or with <kbd>→</kbd>, and
close with <kbd>←</kbd> or <kbd>Esc</kbd>.

```gts preview collapsible
import Component from '@glimmer/component';
import { Dropdown } from 'frontile';

export default class SubmenuDropdown extends Component {
  onAction = (key: string) => {
    // eslint-disable-next-line
    console.log('Action triggered:', key);
  };

  <template>
    <Dropdown as |d|>
      <d.Trigger @variant='outline' @size='sm'>Options</d.Trigger>

      <d.Menu @onAction={{this.onAction}} as |Item Sub|>
        <Item @key='edit' @shortcut='mod+e'>Edit</Item>
        <Item @key='duplicate' @shortcut='mod+d' @withDivider={{true}}>
          Duplicate
        </Item>

        <Sub as |s|>
          <s.Trigger>More</s.Trigger>
          <s.Menu as |Item|>
            <Item @key='move-project'>Move to project…</Item>
            <Item @key='move-folder' @withDivider={{true}}>Move to folder…</Item>
            <Item @key='advanced'>Advanced options…</Item>
          </s.Menu>
        </Sub>

        <Item @key='share'>Share</Item>
        <Item @key='delete' @color='danger' @shortcut='mod+backspace'>
          Delete
        </Item>
      </d.Menu>
    </Dropdown>
  </template>
}
```

### Nested Submenus

Submenus nest to any depth: a `Sub`'s `Menu` yields `Sub` again.

```gts preview collapsible
import Component from '@glimmer/component';
import { Dropdown } from 'frontile';

export default class NestedSubmenuDropdown extends Component {
  onAction = (key: string) => {
    // eslint-disable-next-line
    console.log('Action triggered:', key);
  };

  <template>
    <Dropdown as |d|>
      <d.Trigger @variant='outline' @size='sm'>Share</d.Trigger>

      <d.Menu @onAction={{this.onAction}} as |Item Sub|>
        <Item @key='copy-link'>Copy Link</Item>
        <Item @key='facebook'>Facebook</Item>

        <Sub as |s|>
          <s.Trigger>Other</s.Trigger>
          <s.Menu as |Item Sub|>
            <Item @key='whatsapp'>WhatsApp</Item>
            <Item @key='telegram'>Telegram</Item>

            <Sub as |s|>
              <s.Trigger>Email</s.Trigger>
              <s.Menu as |Item|>
                <Item @key='work-email'>Work email</Item>
                <Item @key='personal-email'>Personal email</Item>
              </s.Menu>
            </Sub>
          </s.Menu>
        </Sub>
      </d.Menu>
    </Dropdown>
  </template>
}
```

### Sibling Submenus

Two submenu rows next to each other are mutually exclusive: moving from one
onto the other closes the first as the second opens, so only one level is ever
on screen.

```gts preview collapsible
import Component from '@glimmer/component';
import { Dropdown } from 'frontile';

export default class SiblingSubmenuDropdown extends Component {
  onAction = (key: string) => {
    // eslint-disable-next-line
    console.log('Action triggered:', key);
  };

  <template>
    <Dropdown as |d|>
      <d.Trigger @variant='outline' @size='sm'>Organize</d.Trigger>

      <d.Menu @onAction={{this.onAction}} as |Item Sub|>
        <Item @key='rename'>Rename</Item>
        <Item @key='duplicate' @withDivider={{true}}>Duplicate</Item>

        <Sub as |s|>
          <s.Trigger>Move to</s.Trigger>
          <s.Menu as |Item|>
            <Item @key='move-inbox'>Inbox</Item>
            <Item @key='move-archive'>Archive</Item>
            <Item @key='move-trash'>Trash</Item>
          </s.Menu>
        </Sub>

        <Sub as |s|>
          <s.Trigger>Share with</s.Trigger>
          <s.Menu as |Item|>
            <Item @key='share-team'>Team</Item>
            <Item @key='share-guests'>Guests</Item>
            <Item @key='share-link'>Anyone with the link</Item>
          </s.Menu>
        </Sub>
      </d.Menu>
    </Dropdown>
  </template>
}
```

## Anatomy

Dropdown yields the pieces you assemble the menu from:

| Yielded     | Purpose                                                                                                |
| ----------- | ------------------------------------------------------------------------------------------------------ |
| `d.Trigger` | Button that opens the menu                                                                             |
| `d.Menu`    | The menu itself; yields an `Item` for each entry and, as a second block param, `Sub` for a nested menu |
| `Item`      | A single menu entry                                                                                    |
| `Sub`       | A nested menu, yielded alongside `Item`; yields its own `s.Trigger` and `s.Menu`                       |

A `Sub`'s `s.Menu` yields `Item` and `Sub` again, the same as the root `d.Menu`, so menus can
nest to any depth.

The arguments declared once on the root `d.Menu` (`@onAction`, `@selectionMode`,
`@selectedKeys`, `@disabledKeys`, `@allowEmpty`, `@onSelectionChange`, `@variant`,
`@intent`, `@shortcutVariant`, `@closeOnItemSelect`, `@disableTransitions`,
`@transitionDuration`) apply at every depth, so a nested `s.Menu` only needs its own items.
Passing one of these same arguments to a nested `s.Menu` instead of the root has no effect —
the root's value always wins, silently — so declare them once, on `d.Menu`.

`s.Trigger` needs no `@key` — `Sub` generates one, and a sub-trigger never fires
`@onAction`. `Sub` positions its menu with `@placement`, `@offsetOptions`, `@flipOptions`,
`@shiftOptions`, `@middleware` and `@strategy`, defaulting to `@placement="right-start"`.

## Accessibility

Dropdown is a Popover wrapping a Listbox with `@type="menu"`, and inherits from both.

The trigger — a real `<button>`, so it is focusable and activates on `Enter` and `Space` —
carries `aria-haspopup="true"`, `aria-controls` pointing at the menu, and `aria-expanded`
kept in sync. The menu itself is `role="menu"` and its items carry `aria-labelledby`, plus
`aria-disabled="true"` for keys in `@disabledKeys`. Their role depends on whether the menu
selects, as below.

Menu items never carry `aria-selected` — it is invalid on a menu item, which conveys state
through `aria-checked` instead. When the menu selects, its rows take the matching checkable
role and report their state: `menuitemcheckbox` with `@selectionMode="multiple"`,
`menuitemradio` with `"single"`, each with `aria-checked` kept in sync. A menu that does not
select keeps plain `menuitem` rows and no checked state, and a row that opens a submenu stays
a plain `menuitem` whatever the level selects — activating it opens a menu rather than
toggling a value.

Menu items share the Listbox's roving `tabindex`: exactly one item carries `tabindex="0"` —
the active one, falling back to the first selected item and then to the first item that is not
disabled — and every other item is `-1`.

Which keys are handled depends on where focus is:

| Focus is on the trigger | Behavior                                          |
| ----------------------- | ------------------------------------------------- |
| `Enter` / `Space`       | Opens the menu, on key release                    |
| `ArrowDown` / `ArrowUp` | Opens the menu                                    |
| any letter              | Opens the menu (not with `Cmd`/`Ctrl`/`Alt` held) |
| `Escape`                | Closes                                            |
| `Tab`                   | Closes and moves on, without pulling focus back   |

Once open, focus moves into the menu and the list takes over:

| Focus is in the menu                  | Behavior                                                                                    |
| ------------------------------------- | ------------------------------------------------------------------------------------------- |
| `ArrowDown` / `ArrowUp`               | Move the active item, within the open level                                                 |
| `ArrowRight`                          | Opens the active row's submenu and moves to its first item                                  |
| `ArrowLeft`                           | Closes the current submenu and returns focus to its trigger; does nothing at the root level |
| `Home` / `PageUp`, `End` / `PageDown` | First / last item, within the open level                                                    |
| `Enter`, `Space`                      | Runs the active item's action, or opens its submenu                                         |
| any single character                  | Type-ahead to a matching item, scoped to the open level                                     |
| `Escape`                              | Closes the innermost open menu — at the root, focus returns to the trigger                  |

Because the content is inside an Overlay with a focus trap, `Tab` from within the menu cycles
inside it rather than leaving.

Opening the menu from the keyboard — `Enter`, `Space`, `ArrowDown` or `ArrowUp` on the
trigger — activates its first row, per the WAI-ARIA menu button pattern, so the keyboard is
immediately useful. Opening it with a pointer activates nothing, since moving the highlight
somewhere the user never pointed is exactly what that pattern avoids. Pass an explicit
`@autoActivateMode` to override either behaviour.

### Submenus

A submenu also opens on hovering its trigger, after a short delay, and stays
open while the pointer travels toward it; moving onto a sibling row closes it.
Only one submenu per level is ever open: opening one closes whichever sibling
was open, so moving between two adjacent submenu rows swaps levels instead of
stacking them. Opening a submenu by hover or click highlights nothing inside it — only
opening it with the keyboard highlights its first row.

A submenu inherits its selection settings from the root menu, so `@selectionMode`,
`@selectedKeys`, `@disabledKeys`, `@allowEmpty`, `@onAction`, `@onSelectionChange` and
`@closeOnItemSelect` written once at the top apply at every depth. A submenu may also declare
any of those seven itself, which wins for that level and the levels below it — so a
navigation menu can hold a multi-select submenu without the root pretending to select. A
submenu that declares nothing keeps inheriting.

Only those seven are a submenu's to override. Appearance and timing — `@variant`, `@color`,
`@shortcutVariant`, `@disableTransitions` and `@transitionDuration` — stay the root's for the
whole chain, so one menu cannot end up looking like two.

## API

### Dropdown

**Element:** `HTMLUListElement`

**Arguments**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `closeOnItemSelect` | `boolean` | `true` | Whether the dropdown should close upon selecting an item. |
| `didClose` | `() => void` | - | Callback when closing has finished, including any exit transition. |
| `flipOptions` | `{ mainAxis?: boolean; crossAxis?: boolean \| 'alignment'; fallbackPlacements?: Placement[]; fallbackStrategy?: 'bestFit' \| 'initialPlacement'; fallbackAxisSideDirection?: 'start' \| ... 1 more ... \| 'none'; ... 5 more ...; boundary?: Boundary; }` | - | Options for the floating-ui flip middleware, which moves the content to the opposite side when it would overflow the viewport. |
| `middleware` | `{ name: string; options?: any; fn: (state: { placement: Placement; strategy: Strategy; x: number; y: number; initialPlacement: Placement; middlewareData: MiddlewareData; rects: ElementRects; platform: { ...; } &#x26; Platform; elements: Elements; }) => Promisable<...>; }[]` | - | Additional floating-ui middleware, for positioning behavior beyond what placement, offsetOptions, flipOptions, and shiftOptions cover. |
| `offsetOptions` | `OffsetOptions` | `5` |  |
| `placement` | `'top' \| 'top-start' \| 'top-end' \| 'right' \| 'right-start' \| 'right-end' \| 'bottom' \| 'bottom-start' \| 'bottom-end' \| 'left' \| 'left-start' \| 'left-end'` | `'bottom-start'` | Placement of the menu when open |
| `shiftOptions` | `{ mainAxis?: boolean; crossAxis?: boolean; rootBoundary?: RootBoundary; elementContext?: ElementContext; altBoundary?: boolean; padding?: Padding; limiter?: { ...; }; boundary?: Boundary; }` | - | Options for the floating-ui shift middleware, which nudges the content along its axis to keep it in view. |
| `strategy` | `Strategy` | `'absolute'` |  |

**Blocks**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `default *` | `[{ Trigger: Trigger (anchor, toggle, trigger, setOpenSource bound); Menu: Menu (toggle, close, Content, closeOnItemSelect bound); }]` | - |  |

---

# Listbox

Source: /docs/components/collections/listbox.md

# Listbox

A listbox presents a list of options allowing users to select one or multiple items. It serves as the foundation for other components like Select and Dropdown menus, with full keyboard navigation and accessibility support.

## Import

```js
import { Listbox } from 'frontile';
```

## Usage

### Basic Listbox with Selection

A simple listbox with single selection mode.

```gts preview collapsible
import Component from '@glimmer/component';
import { tracked } from '@glimmer/tracking';
import { Listbox } from 'frontile';

export default class BasicListbox extends Component {
  @tracked selectedKeys: string[] = ['lion'];

  animals = [
    'cheetah',
    'crocodile',
    'elephant',
    'giraffe',
    'lion',
    'panda',
    'tiger',
    'zebra'
  ];

  onSelectionChange = (keys: string[]) => {
    this.selectedKeys = keys;
  };

  <template>
    <div class='demo-stack items-center'>
      <div class='w-[260px] border px-1 py-2 rounded border-neutral-subtle'>
        <Listbox
          @isKeyboardEventsEnabled={{true}}
          @selectionMode='single'
          @items={{this.animals}}
          @selectedKeys={{this.selectedKeys}}
          @onSelectionChange={{this.onSelectionChange}}
          @color='primary'
        />
      </div>
      <div class='text-sm text-neutral-firm'>
        Selected:
        {{this.selectedKeys}}
      </div>
    </div>
  </template>
}
```

### Multiple Selection

Enable users to select multiple items from the list.

```gts preview collapsible
import Component from '@glimmer/component';
import { tracked } from '@glimmer/tracking';
import { Listbox } from 'frontile';

export default class MultipleSelection extends Component {
  @tracked selectedKeys: string[] = ['lion', 'tiger'];

  animals = [
    'cheetah',
    'crocodile',
    'elephant',
    'giraffe',
    'lion',
    'panda',
    'tiger',
    'zebra'
  ];

  onSelectionChange = (keys: string[]) => {
    this.selectedKeys = keys;
  };

  <template>
    <div class='demo-stack items-center'>
      <div class='w-[260px] border px-1 py-2 rounded border-neutral-subtle'>
        <Listbox
          @isKeyboardEventsEnabled={{true}}
          @allowEmpty={{true}}
          @selectionMode='multiple'
          @items={{this.animals}}
          @selectedKeys={{this.selectedKeys}}
          @onSelectionChange={{this.onSelectionChange}}
          @color='primary'
        />
      </div>
      <div class='text-sm text-neutral-firm'>
        Selected:
        {{this.selectedKeys}}
      </div>
    </div>
  </template>
}
```

### Static Items with Rich Content

Define items explicitly with icons, descriptions, and shortcuts.

> **Note:** The `@shortcut` argument is for display purposes only. You'll need to implement actual keyboard shortcut handling in your application.

```gts preview collapsible
import Component from '@glimmer/component';
import { Listbox } from 'frontile';
import {
  ViewIcon,
  EditIcon,
  ShareIcon,
  DeleteIcon
} from 'site/components/icons';

export default class StaticItems extends Component {
  disabledKeys = ['delete'];

  onAction = (key: string) => {
    // eslint-disable-next-line
    console.log('Action:', key);
  };

  <template>
    <div class='w-[280px] border px-1 py-2 rounded border-neutral-subtle'>
      <Listbox
        @isKeyboardEventsEnabled={{true}}
        @onAction={{this.onAction}}
        @variant='subtle'
        @disabledKeys={{this.disabledKeys}}
        as |l|
      >
        <l.Item
          @key='view'
          @description='View in read-only mode'
          @shortcut='mod+o'
        >
          <:start><ViewIcon /></:start>
          <:default>View Details</:default>
        </l.Item>
        <l.Item @key='edit' @description='Make changes' @shortcut='mod+e'>
          <:start><EditIcon /></:start>
          <:default>Edit</:default>
        </l.Item>
        <l.Item
          @key='share'
          @description='Share with team'
          @shortcut='mod+shift+s'
          @withDivider={{true}}
        >
          <:start><ShareIcon /></:start>
          <:default>Share</:default>
        </l.Item>
        <l.Item
          @key='delete'
          @description='Permanently delete'
          @color='danger'
          @class='text-danger'
          @shortcut='mod+backspace'
        >
          <:start><DeleteIcon /></:start>
          <:default>Delete</:default>
        </l.Item>
      </Listbox>
    </div>
  </template>
}
```

### Action Menu (No Selection)

Use selection mode "none" for action menus where items trigger actions rather than being selected.

```gts preview collapsible
import Component from '@glimmer/component';
import { Listbox } from 'frontile';

export default class ActionMenu extends Component {
  onAction = (key: string) => {
    // eslint-disable-next-line
    alert(`Action triggered: ${key}`);
  };

  <template>
    <div class='w-[260px] border px-1 py-2 rounded border-neutral-subtle'>
      <Listbox
        @isKeyboardEventsEnabled={{true}}
        @selectionMode='none'
        @onAction={{this.onAction}}
        as |l|
      >
        <l.Item @key='new'>New File</l.Item>
        <l.Item @key='open'>Open...</l.Item>
        <l.Item @key='save' @shortcut='mod+s'>Save</l.Item>
        <l.Item @key='save-as' @shortcut='mod+shift+s' @withDivider={{true}}>
          Save As...
        </l.Item>
        <l.Item @key='export'>Export</l.Item>
        <l.Item @key='print' @shortcut='mod+p'>Print</l.Item>
      </Listbox>
    </div>
  </template>
}
```

### Different Variants

Control the visual style with the `@variant` argument.

```gts preview collapsible
import Component from '@glimmer/component';
import { tracked } from '@glimmer/tracking';
import { fn } from '@ember/helper';
import { Listbox, ButtonGroup } from 'frontile';

export default class Variants extends Component {
  @tracked variant = 'solid';
  @tracked selectedKeys: string[] = ['option2'];

  options = ['option1', 'option2', 'option3', 'option4'];

  setVariant = (variant: string) => {
    this.variant = variant;
  };

  onSelectionChange = (keys: string[]) => {
    this.selectedKeys = keys;
  };

  isSelected = (type: string) => {
    return this.variant === type;
  };

  <template>
    <div class='demo-stack items-center'>
      <ButtonGroup @size='xs' @color='primary' as |g|>
        <g.ToggleButton
          @isSelected={{this.isSelected 'solid'}}
          @onChange={{fn this.setVariant 'solid'}}
        >
          Solid
        </g.ToggleButton>
        <g.ToggleButton
          @isSelected={{this.isSelected 'outline'}}
          @onChange={{fn this.setVariant 'outline'}}
        >
          Outline
        </g.ToggleButton>
        <g.ToggleButton
          @isSelected={{this.isSelected 'subtle'}}
          @onChange={{fn this.setVariant 'subtle'}}
        >
          Subtle
        </g.ToggleButton>
      </ButtonGroup>

      <div class='w-[260px] border px-1 py-2 rounded border-neutral-subtle'>
        <Listbox
          @isKeyboardEventsEnabled={{true}}
          @selectionMode='single'
          @items={{this.options}}
          @selectedKeys={{this.selectedKeys}}
          @onSelectionChange={{this.onSelectionChange}}
          @variant={{this.variant}}
          @color='primary'
        />
      </div>
    </div>
  </template>
}
```

### Different Colors

Apply color intents to individual items or the entire listbox.

```gts preview
import Component from '@glimmer/component';
import { Listbox } from 'frontile';

export default class IntentColors extends Component {
  <template>
    <div class='w-[260px] border px-1 py-2 rounded border-neutral-subtle'>
      <Listbox @isKeyboardEventsEnabled={{true}} @variant='subtle' as |l|>
        <l.Item @key='default'>Default Color</l.Item>
        <l.Item @key='primary' @color='primary'>Primary Color</l.Item>
        <l.Item @key='secondary' @color='secondary'>Secondary Color</l.Item>
        <l.Item @key='tertiary' @color='tertiary'>Tertiary Color</l.Item>
        <l.Item @key='success' @color='success'>Success Color</l.Item>
        <l.Item @key='warning' @color='warning'>Warning Color</l.Item>
        <l.Item @key='danger' @color='danger'>Danger Color</l.Item>
      </Listbox>
    </div>
  </template>
}
```

### Disabled Items

Prevent interaction with specific items using `@disabledKeys`.

```gts preview collapsible
import Component from '@glimmer/component';
import { tracked } from '@glimmer/tracking';
import { Listbox } from 'frontile';

export default class DisabledItems extends Component {
  @tracked selectedKeys: string[] = ['feature1'];

  disabledKeys = ['feature3', 'feature4'];

  features = ['feature1', 'feature2', 'feature3', 'feature4', 'feature5'];

  onSelectionChange = (keys: string[]) => {
    this.selectedKeys = keys;
  };

  <template>
    <div class='demo-stack items-center'>
      <div class='w-[260px] border px-1 py-2 rounded border-neutral-subtle'>
        <Listbox
          @isKeyboardEventsEnabled={{true}}
          @selectionMode='single'
          @items={{this.features}}
          @selectedKeys={{this.selectedKeys}}
          @disabledKeys={{this.disabledKeys}}
          @onSelectionChange={{this.onSelectionChange}}
          @color='primary'
        />
      </div>
      <div class='text-sm text-neutral-firm'>
        Items "feature3" and "feature4" are disabled
      </div>
    </div>
  </template>
}
```

### Custom Item Rendering

Render complex objects with custom templates.

```gts preview collapsible
import Component from '@glimmer/component';
import { tracked } from '@glimmer/tracking';
import { Listbox } from 'frontile';

export default class CustomItems extends Component {
  @tracked selectedKeys: string[] = ['user-2'];

  users = [
    {
      id: 'user-1',
      name: 'Alice Johnson',
      role: 'Admin',
      email: 'alice@example.com'
    },
    {
      id: 'user-2',
      name: 'Bob Smith',
      role: 'Developer',
      email: 'bob@example.com'
    },
    {
      id: 'user-3',
      name: 'Carol White',
      role: 'Designer',
      email: 'carol@example.com'
    },
    {
      id: 'user-4',
      name: 'David Brown',
      role: 'Manager',
      email: 'david@example.com'
    }
  ];

  onSelectionChange = (keys: string[]) => {
    this.selectedKeys = keys;
  };

  <template>
    <div class='demo-stack items-center'>
      <div class='w-[320px] border px-1 py-2 rounded border-neutral-subtle'>
        <Listbox
          @isKeyboardEventsEnabled={{true}}
          @selectionMode='single'
          @items={{this.users}}
          @selectedKeys={{this.selectedKeys}}
          @onSelectionChange={{this.onSelectionChange}}
          @color='primary'
        >
          <:item as |o|>
            <o.Item @key={{o.item.id}} @description={{o.item.email}}>
              <:default>
                {{o.item.name}}
                <span
                  class='text-xs text-neutral-firm ml-2'
                >({{o.item.role}})</span>
              </:default>
            </o.Item>
          </:item>
        </Listbox>
      </div>
      <div class='text-sm text-neutral-firm'>
        Selected:
        {{this.selectedKeys}}
      </div>
    </div>
  </template>
}
```

### With Dividers

Organize items into logical groups using dividers.

```gts preview
import Component from '@glimmer/component';
import { Listbox } from 'frontile';

export default class WithDividers extends Component {
  onAction = (key: string) => {
    // eslint-disable-next-line
    console.log('Action:', key);
  };

  <template>
    <div class='w-[260px] border px-1 py-2 rounded border-neutral-subtle'>
      <Listbox
        @isKeyboardEventsEnabled={{true}}
        @selectionMode='none'
        @onAction={{this.onAction}}
        as |l|
      >
        <l.Item @key='new-file'>New File</l.Item>
        <l.Item @key='new-folder' @withDivider={{true}}>New Folder</l.Item>
        <l.Item @key='copy'>Copy</l.Item>
        <l.Item @key='paste'>Paste</l.Item>
        <l.Item @key='cut' @withDivider={{true}}>Cut</l.Item>
        <l.Item @key='rename'>Rename</l.Item>
        <l.Item @key='delete' @color='danger'>Delete</l.Item>
      </Listbox>
    </div>
  </template>
}
```

### Controlled Empty Selection

Control whether users can deselect all items.

```gts preview collapsible
import Component from '@glimmer/component';
import { tracked } from '@glimmer/tracking';
import { Listbox, Button } from 'frontile';

export default class EmptySelection extends Component {
  @tracked allowEmpty = true;
  @tracked selectedKeys: string[] = ['option2'];

  options = ['option1', 'option2', 'option3'];

  toggleAllowEmpty = () => {
    this.allowEmpty = !this.allowEmpty;
  };

  onSelectionChange = (keys: string[]) => {
    this.selectedKeys = keys;
  };

  <template>
    <div class='demo-stack items-center'>
      <div class='flex items-center gap-2'>
        <Button @size='xs' @onPress={{this.toggleAllowEmpty}}>
          Toggle Allow Empty ({{if this.allowEmpty 'ON' 'OFF'}})
        </Button>
      </div>

      <div class='w-[260px] border px-1 py-2 rounded border-neutral-subtle'>
        <Listbox
          @isKeyboardEventsEnabled={{true}}
          @selectionMode='single'
          @allowEmpty={{this.allowEmpty}}
          @items={{this.options}}
          @selectedKeys={{this.selectedKeys}}
          @onSelectionChange={{this.onSelectionChange}}
          @color='primary'
        />
      </div>

      <div class='text-sm text-neutral-firm'>
        {{#if this.allowEmpty}}
          You can deselect all items by clicking the selected item.
        {{else}}
          At least one item must remain selected.
        {{/if}}
      </div>
    </div>
  </template>
}
```

### Grouped Options

`l.Group` renders a labelled section of options. It yields its own `Item`, and
`@withDivider` draws a separator after the group.

Grouping changes nothing about keyboard navigation: arrow keys traverse straight
across group boundaries, because navigation order is derived from the document
rather than from the nesting.

```gts preview
import { Listbox } from 'frontile';
import { array } from '@ember/helper';

<template>
  <div class='demo-stack'>
    <Listbox
      @selectionMode='single'
      @disabledKeys={{array 'calculator'}}
      as |l|
    >
      <l.Group @title='Suggestions' @withDivider={{true}} as |g|>
        <g.Item @key='calendar'>Calendar</g.Item>
        <g.Item @key='emoji'>Search Emoji</g.Item>
        <g.Item @key='calculator'>Calculator</g.Item>
      </l.Group>
      <l.Group @title='Settings' as |g|>
        <g.Item @key='profile' @shortcut='mod+p'>Profile</g.Item>
        <g.Item @key='billing' @shortcut='mod+b'>Billing</g.Item>
      </l.Group>
    </Listbox>
  </div>
</template>
```

A group without `@title` still groups its options but renders no heading, and
carries no `aria-labelledby` — there would be nothing for it to point at.

### Keyboard Shortcuts

`@shortcut` is rendered by [Kbd](../utilities/kbd), so it understands named keys
and resolves them per platform: `'mod+o'` shows `⌘O` on Apple and `Ctrl+O`
elsewhere. A string with no `+`, such as `'⌘⇧S'`, is shown exactly as given.

Keycaps default to the `inherit` variant, which takes its colour from the
option, so a shortcut stays legible on an active or filled row. Use
`@shortcutVariant` to change that for every item at once — `Command` sets
`'plain'` for its denser rows.

```gts preview
import { Listbox } from 'frontile';

<template>
  <div class='w-[280px] border px-1 py-2 rounded border-neutral-subtle'>
    <Listbox @selectionMode='none' @shortcutVariant='plain' as |l|>
      <l.Item @key='save' @shortcut='mod+s'>Save</l.Item>
      <l.Item @key='print' @shortcut='mod+p'>Print</l.Item>
    </Listbox>
  </div>
</template>
```

## Anatomy

`Listbox` renders items from `@items` automatically, or yields an `Item` component for manual
composition. Each item owns its option semantics, selection state, and optional start/end
content.

## Accessibility

| Element  | What it exposes                                                                                |
| -------- | ---------------------------------------------------------------------------------------------- |
| The list | `role="listbox"`, or `role="menu"` with `@type="menu"`                                         |
|          | `aria-multiselectable="true"` when `@selectionMode="multiple"` (listbox only)                  |
| Items    | `role="option"`, or a menu role with `@type="menu"` — see below                                |
|          | `aria-selected` reflecting selection — options only, since it is invalid on any menu item      |
|          | `aria-checked` reflecting selection — checkable menu items only                                |
|          | `aria-disabled="true"` for keys in `@disabledKeys`                                             |
|          | a roving `tabindex` — exactly one option carries `0`, every other one `-1`                     |
|          | `aria-haspopup="menu"`, `aria-expanded` and `aria-controls` on an item with `@hasSubmenu`      |

With `@type="menu"` an item's role follows how the list selects, because a menu conveys
state through `aria-checked` rather than `aria-selected`, and only on a checkable role:
`menuitemcheckbox` with `@selectionMode="multiple"`, `menuitemradio` with `"single"`, and a
plain `menuitem` with no `aria-checked` when the menu does not select. An item with
`@hasSubmenu` stays a plain `menuitem` whatever the list selects — activating it opens a menu
rather than toggling a value. The role follows `@selectionMode` if it changes at runtime.

An item that opens a nested menu takes three arguments: `@hasSubmenu` renders a trailing
chevron (unless the item supplies its own `:end` block) and switches its ARIA to
`aria-haspopup="menu"`; `@isSubmenuOpen` drives `aria-expanded` and a `data-submenu-open`
resting state; `@submenuId` points `aria-controls` at the submenu's `role="menu"` element.
An item with `@hasSubmenu` never selects, so `@onAction` and `@onSelectionChange` never fire
for it, while it still takes part in arrow navigation, type-ahead and the roving tab stop
like any other item. [Dropdown](./dropdown)'s `Sub` sets all three of these automatically.

The options form a composite you step into once and then navigate with the arrow keys, so only
one of them is ever in the tab order. That one is the active option; with nothing active it is
the first selected option, and failing that the first option that is not disabled. A
multiple-selection list with eight selections is therefore still a single stop for `Tab`, not
eight.

Keyboard, handled on the list itself:

| Key                     | Behavior                                                            |
| ----------------------- | ------------------------------------------------------------------- |
| `ArrowDown` / `ArrowUp` | Move the active item                                                |
| `Home` / `PageUp`       | Jump to the first item                                              |
| `End` / `PageDown`      | Jump to the last item                                               |
| `Enter`, `Space`        | Select the active item                                              |
| any single character    | Type-ahead: jumps to the item whose text starts with what you typed |

Two details. Type-ahead means `Space` selects only when no search is in
progress, so a space typed mid-search is treated as part of the search string rather than as
a selection. And `@elementToAddKeyboardEvents` moves the key handling onto another element —
that is how Select and Autocomplete keep focus in their input while driving the list.

Groups render as `role="group"` labelled by their heading, with the list between
the group and its options marked `role="none"` so the `listbox` → `option`
ownership chain stays intact. A group with no `@title` carries no
`aria-labelledby`.

## API

### Listbox

**Element:** `HTMLUListElement`

**Arguments**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `allowEmpty` | `boolean` | - |  |
| `appearance` | `'default' \| 'outlined' \| 'faded'` | - | **Deprecated.** Use `variant`. `default` is now `solid`, `outlined` is `outline`, and `faded` is `subtle`. |
| `autoActivateMode` | `'none' \| 'first' \| 'selected'` | `'first'` |  |
| `class` | `string` | - |  |
| `color` | `'neutral' \| 'primary' \| 'secondary' \| 'tertiary' \| 'success' \| 'warning' \| 'danger'` | - | The color of each item |
| `disabledKeys` | `string[]` | - |  |
| `elementToAddKeyboardEvents` | `HTMLElement` | `null` | The element to add keyboard events to. This does not respect the option iskeyboardEventsEnabled. |
| `intent` | `'default' \| 'primary' \| 'secondary' \| 'tertiary' \| 'success' \| 'warning' \| 'danger'` | - | **Deprecated.** Use `color`. `default` is now `neutral`. |
| `isKeyboardEventsEnabled` | `boolean` | - |  |
| `items` | `T[]` | - |  |
| `onAction` | `(key: string) => void` | - |  |
| `onActiveItemChange` | `(key?: string, item?: ListItem) => void` | - |  |
| `onSelectionChange` | `(key: string[]) => void` | - |  |
| `selectedKeys` | `string[]` | - |  |
| `selectionMode` | `SelectionMode` | - |  |
| `shortcutVariant` | `'solid' \| 'subtle' \| 'outline' \| 'plain' \| 'inherit'` | `'inherit'` | The appearance of the keycap rendered for each item's @shortcut. |
| `type` | `'listbox' \| 'menu'` | - |  |
| `variant` | `'solid' \| 'subtle' \| 'outline'` | `'solid'` | The variant of each item. |

**Blocks**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `item *` | `[{ item: T; key: string; label: string; Item: ListboxItem (manager, item bound); }]` | - |  |
| `default *` | `[{ Item: ListboxItem (manager bound); Group: ListboxGroup (manager bound); }]` | - |  |

### Listbox::Group

### ListboxGroup

A labelled section of options within a Listbox.

The markup nests the options one level deeper than an ungrouped listbox, so
the intervening list is marked role="none" to keep the
listbox -> option ownership chain intact.

Grouping deliberately adds no concepts to ListManager: navigation order is
derived from the live DOM via compareDocumentPosition, so nesting options
inside a group leaves keyboard traversal across group boundaries correct by
construction.

**Element:** `HTMLLIElement`

**Arguments**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `manager *` | `ListManager` | - |  |
| `appearance` | `'default' \| 'outlined' \| 'faded'` | - | **Deprecated.** Use `variant`. |
| `class` | `string` | - |  |
| `classes` | `Object` | - |  |
| `color` | `'neutral' \| 'primary' \| 'secondary' \| 'tertiary' \| 'success' \| 'warning' \| 'danger'` | - |  |
| `intent` | `'default' \| 'primary' \| 'secondary' \| 'tertiary' \| 'success' \| 'warning' \| 'danger'` | - |  |
| `shortcutVariant` | `'solid' \| 'subtle' \| 'outline' \| 'plain' \| 'inherit'` | - |  |
| `title` | `string` | - | The heading rendered above the group's options. When omitted, the group still groups its options but renders no heading — and carries no aria-labelledby, since there would be nothing to point at. |
| `type` | `'listbox' \| 'menu'` | - |  |
| `variant` | `'solid' \| 'subtle' \| 'outline'` | - |  |
| `withDivider` | `boolean` | - | Render a divider after the group. Groups in a palette are usually separated visually; the divider is a sibling of the group rather than a child so it does not sit inside the group's labelled region. |

**Blocks**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `default *` | `[{ Item: ListboxItem (manager, type, variant, appearance, color, intent, shortcutVariant bound); }]` | - |  |

### Listbox::Item

### ListboxItem

**Element:** `HTMLLIElement`

**Arguments**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `key *` | `string` | - |  |
| `manager *` | `ListManager` | - |  |
| `appearance` | `'default' \| 'outlined' \| 'faded'` | - | **Deprecated.** Use `variant`. `default` is now `solid`, `outlined` is `outline`, and `faded` is `subtle`. |
| `class` | `string` | - |  |
| `color` | `'neutral' \| 'primary' \| 'secondary' \| 'tertiary' \| 'success' \| 'warning' \| 'danger'` | - | The color of each item |
| `description` | `string` | - |  |
| `hasSubmenu` | `boolean` | - | Marks this option as the trigger for a submenu. It stops the option selecting: opening a submenu is not choosing anything, so onAction and onSelectionChange must not fire for it. The option still registers with the ListManager and so still takes part in arrow navigation, type-ahead and the roving tab stop. Renders aria-haspopup="menu" and a trailing chevron, unless an :end block supplies its own trailing content. |
| `intent` | `'default' \| 'primary' \| 'secondary' \| 'tertiary' \| 'success' \| 'warning' \| 'danger'` | - | **Deprecated.** Use `color`. `default` is now `neutral`. |
| `isSubmenuOpen` | `boolean` | - | Whether this option's submenu is currently open. Only meaningful alongside @hasSubmenu; drives aria-expanded and the highlighted resting state via data-submenu-open. |
| `item` | `unknown` | - | The entry of @items this option renders, remembered on the registered list item so a selection can hand it back. Bound for you on the Item yielded from the :item block; block-form options have no such entry. |
| `onClick` | `() => void` | - |  |
| `shortcut` | `string` | - | A keyboard shortcut shown at the end of the option, rendered by Kbd. Accepts named keys ("mod+k") or a literal string ("⌘K"). |
| `shortcutVariant` | `'solid' \| 'subtle' \| 'outline' \| 'plain' \| 'inherit'` | `'inherit'` | The variant of the rendered shortcut. Defaults to inherit, so the keycap follows the option's own colour on active and filled rows. |
| `submenuId` | `string` | - | The id of the role="menu" element this option opens, for aria-controls. Only meaningful alongside @hasSubmenu. |
| `textValue` | `string` | - |  |
| `type` | `'listbox' \| 'menu'` | - |  |
| `variant` | `'solid' \| 'subtle' \| 'outline'` | `'solid'` | The variant of each item. |
| `withDivider` | `boolean` | - |  |

**Blocks**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `default *` | `[]` | - |  |
| `selectedIcon *` | `[]` | - |  |
| `start *` | `[]` | - |  |
| `end *` | `[]` | - |  |

---

# SimpleTable

Source: /docs/components/collections/simple-table.md

# SimpleTable

SimpleTable renders the HTML table structure — `<table>`, `<thead>`, `<tbody>`, `<tfoot>` — with Frontile's styling, for manual composition when you want full control over layout instead of automatic rendering from data.

**Key Features:**

- **Manual composition** with block-form yielding
- Size variants and striped rows
- Sticky support when used with the Table component
- No data management — just the table structure and styling

For automatic rendering with sticky elements and data management, use [Table](./table) instead.

## Import

```js
import { SimpleTable } from 'frontile';
```

## Usage

SimpleTable uses block form composition where you manually define the table structure:

```gts preview collapsible
import Component from '@glimmer/component';
import { SimpleTable } from 'frontile';

export default class DemoComponent extends Component {
  items = [
    { id: '1', name: 'John Doe', email: 'john@example.com', role: 'admin' },
    { id: '2', name: 'Jane Smith', email: 'jane@example.com', role: 'user' }
  ];

  <template>
    <div class='demo-stack demo-stack--wide'>
      <SimpleTable as |t|>
        <t.Header>
          <t.Column>ID</t.Column>
          <t.Column>Name</t.Column>
          <t.Column>Email</t.Column>
          <t.Column>Role</t.Column>
        </t.Header>
        <t.Body>
          {{#each this.items as |item|}}
            <t.Row>
              <t.Cell>{{item.id}}</t.Cell>
              <t.Cell>{{item.name}}</t.Cell>
              <t.Cell>{{item.email}}</t.Cell>
              <t.Cell>{{item.role}}</t.Cell>
            </t.Row>
          {{/each}}
        </t.Body>
      </SimpleTable>
    </div>
  </template>
}
```

## Anatomy

`SimpleTable` yields `Header`, `Body`, `Footer`, `Column`, `Row`, and `Cell` components. Compose
those pieces in native table order; unlike `Table`, SimpleTable does not create columns or rows
from data for you.

## Advanced Composition

### Custom Headers

Create complex header layouts with custom content:

```gts preview collapsible
import Component from '@glimmer/component';
import { SimpleTable } from 'frontile';
import { Button, Chip } from 'frontile';

export default class DemoComponent extends Component {
  users = [
    {
      id: '1',
      name: 'John Doe',
      email: 'john@example.com',
      status: 'Active',
      chipColor: 'success'
    },
    {
      id: '2',
      name: 'Jane Smith',
      email: 'jane@example.com',
      status: 'Inactive',
      chipColor: 'neutral'
    },
    {
      id: '3',
      name: 'Bob Wilson',
      email: 'bob@example.com',
      status: 'Pending',
      chipColor: 'warning'
    }
  ];

  <template>
    <div class='demo-stack demo-stack--wide'>
      <SimpleTable as |t|>
        <t.Header>
          <t.Column>
            <span class='flex items-center gap-2'>
              👤 User Info
            </span>
          </t.Column>
          <t.Column>
            <span class='flex items-center gap-2'>
              📧 Contact
            </span>
          </t.Column>
          <t.Column>
            <span class='flex items-center gap-2'>
              🔄 Status
            </span>
          </t.Column>
          <t.Column>
            <span class='flex items-center gap-2'>
              ⚡ Actions
            </span>
          </t.Column>
        </t.Header>
        <t.Body>
          {{#each this.users as |user|}}
            <t.Row>
              <t.Cell>
                <div>
                  <div class='font-medium'>{{user.name}}</div>
                  <div class='text-sm text-neutral-soft'>ID: {{user.id}}</div>
                </div>
              </t.Cell>
              <t.Cell>{{user.email}}</t.Cell>
              <t.Cell>
                <Chip @color={{user.chipColor}} @size='sm'>
                  {{user.status}}
                </Chip>
              </t.Cell>
              <t.Cell>
                <Button @variant='plain' @size='sm'>
                  Edit
                </Button>
              </t.Cell>
            </t.Row>
          {{/each}}
        </t.Body>
      </SimpleTable>
    </div>
  </template>
}
```

### Custom Cell Content

SimpleTable excels at complex cell layouts and interactive content:

```gts preview collapsible
import Component from '@glimmer/component';
import { SimpleTable } from 'frontile';
import { Button, Chip } from 'frontile';

export default class DemoComponent extends Component {
  products = [
    {
      id: '1',
      name: 'Wireless Headphones',
      price: 99.99,
      stock: 15,
      stockStatus: 'In Stock',
      stockChipColor: 'success'
    },
    {
      id: '2',
      name: 'Smart Watch',
      price: 299.99,
      stock: 3,
      stockStatus: 'Low Stock',
      stockChipColor: 'warning'
    },
    {
      id: '3',
      name: 'Bluetooth Speaker',
      price: 59.99,
      stock: 0,
      stockStatus: 'Out of Stock',
      stockChipColor: 'danger'
    }
  ];

  <template>
    <div class='demo-stack demo-stack--wide'>
      <SimpleTable as |t|>
        <t.Header>
          <t.Column>Product</t.Column>
          <t.Column>Price</t.Column>
          <t.Column>Stock</t.Column>
          <t.Column>Actions</t.Column>
        </t.Header>
        <t.Body>
          {{#each this.products as |product|}}
            <t.Row>
              <t.Cell>
                <div>
                  <div class='font-medium'>{{product.name}}</div>
                  <div class='text-sm text-neutral-soft'>ID:
                    {{product.id}}</div>
                </div>
              </t.Cell>
              <t.Cell>
                <span class='font-medium'>${{product.price}}</span>
              </t.Cell>
              <t.Cell>
                <div class='flex flex-col gap-1'>
                  <div class='font-medium'>{{product.stock}} units</div>
                  <Chip @color={{product.stockChipColor}} @size='sm'>
                    {{product.stockStatus}}
                  </Chip>
                </div>
              </t.Cell>
              <t.Cell>
                <div class='flex gap-2'>
                  <Button @color='primary' @size='sm'>
                    Edit
                  </Button>
                  <Button @color='danger' @size='sm'>
                    Delete
                  </Button>
                </div>
              </t.Cell>
            </t.Row>
          {{/each}}
        </t.Body>
      </SimpleTable>
    </div>
  </template>
}
```

## Styling & Layout

### Size Variants

Control table spacing with size variants:

```gts preview collapsible
import Component from '@glimmer/component';
import { SimpleTable } from 'frontile';

export default class DemoComponent extends Component {
  data = [
    { name: 'John Doe', role: 'Developer' },
    { name: 'Jane Smith', role: 'Designer' }
  ];

  <template>
    <div class='demo-stack demo-stack--wide'>
      <div class='space-y-6'>
        <div>
          <h4 class='font-medium mb-2'>Small (sm) - Compact spacing</h4>
          <SimpleTable @size='sm' as |t|>
            <t.Header>
              <t.Column>Name</t.Column>
              <t.Column>Role</t.Column>
            </t.Header>
            <t.Body>
              {{#each this.data as |item|}}
                <t.Row>
                  <t.Cell>{{item.name}}</t.Cell>
                  <t.Cell>{{item.role}}</t.Cell>
                </t.Row>
              {{/each}}
            </t.Body>
          </SimpleTable>
        </div>

        <div>
          <h4 class='font-medium mb-2'>Medium (md) - Default spacing</h4>
          <SimpleTable @size='md' as |t|>
            <t.Header>
              <t.Column>Name</t.Column>
              <t.Column>Role</t.Column>
            </t.Header>
            <t.Body>
              {{#each this.data as |item|}}
                <t.Row>
                  <t.Cell>{{item.name}}</t.Cell>
                  <t.Cell>{{item.role}}</t.Cell>
                </t.Row>
              {{/each}}
            </t.Body>
          </SimpleTable>
        </div>

        <div>
          <h4 class='font-medium mb-2'>Large (lg) - Spacious layout</h4>
          <SimpleTable @size='lg' as |t|>
            <t.Header>
              <t.Column>Name</t.Column>
              <t.Column>Role</t.Column>
            </t.Header>
            <t.Body>
              {{#each this.data as |item|}}
                <t.Row>
                  <t.Cell>{{item.name}}</t.Cell>
                  <t.Cell>{{item.role}}</t.Cell>
                </t.Row>
              {{/each}}
            </t.Body>
          </SimpleTable>
        </div>
      </div>
    </div>
  </template>
}
```

### Layout Options

Control column sizing behavior:

```gts preview collapsible
import Component from '@glimmer/component';
import { SimpleTable } from 'frontile';

export default class DemoComponent extends Component {
  data = [
    {
      id: '1',
      name: 'John Doe',
      email: 'john.doe.longname@example-company.com',
      department: 'Engineering'
    },
    {
      id: '2',
      name: 'Jane',
      email: 'jane@ex.co',
      department: 'Design'
    }
  ];

  <template>
    <div class='demo-stack demo-stack--wide'>
      <div class='space-y-6'>
        <div>
          <h4 class='font-medium mb-2'>Auto Layout (default) - Content-based
            sizing</h4>
          <SimpleTable @layout='auto' as |t|>
            <t.Header>
              <t.Column>ID</t.Column>
              <t.Column>Name</t.Column>
              <t.Column>Email</t.Column>
              <t.Column>Department</t.Column>
            </t.Header>
            <t.Body>
              {{#each this.data as |item|}}
                <t.Row>
                  <t.Cell>{{item.id}}</t.Cell>
                  <t.Cell>{{item.name}}</t.Cell>
                  <t.Cell>{{item.email}}</t.Cell>
                  <t.Cell>{{item.department}}</t.Cell>
                </t.Row>
              {{/each}}
            </t.Body>
          </SimpleTable>
        </div>

        <div>
          <h4 class='font-medium mb-2'>Fixed Layout - Equal column widths</h4>
          <SimpleTable @layout='fixed' as |t|>
            <t.Header>
              <t.Column>ID</t.Column>
              <t.Column>Name</t.Column>
              <t.Column>Email</t.Column>
              <t.Column>Department</t.Column>
            </t.Header>
            <t.Body>
              {{#each this.data as |item|}}
                <t.Row>
                  <t.Cell>{{item.id}}</t.Cell>
                  <t.Cell>{{item.name}}</t.Cell>
                  <t.Cell>{{item.email}}</t.Cell>
                  <t.Cell>{{item.department}}</t.Cell>
                </t.Row>
              {{/each}}
            </t.Body>
          </SimpleTable>
        </div>
      </div>
    </div>
  </template>
}
```

### Striped Rows

Enable alternating row colors for better readability:

```gts preview collapsible
import Component from '@glimmer/component';
import { SimpleTable } from 'frontile';
import { Chip } from 'frontile';

export default class DemoComponent extends Component {
  users = [
    {
      name: 'John Doe',
      email: 'john@example.com',
      status: 'Active',
      statusColor: 'success'
    },
    {
      name: 'Jane Smith',
      email: 'jane@example.com',
      status: 'Active',
      statusColor: 'success'
    },
    {
      name: 'Bob Johnson',
      email: 'bob@example.com',
      status: 'Inactive',
      statusColor: 'neutral'
    },
    {
      name: 'Alice Brown',
      email: 'alice@example.com',
      status: 'Active',
      statusColor: 'success'
    }
  ];

  <template>
    <div class='demo-stack demo-stack--wide'>
      <SimpleTable @isStriped={{true}} as |t|>
        <t.Header>
          <t.Column>Name</t.Column>
          <t.Column>Email</t.Column>
          <t.Column>Status</t.Column>
        </t.Header>
        <t.Body>
          {{#each this.users as |user|}}
            <t.Row>
              <t.Cell>{{user.name}}</t.Cell>
              <t.Cell>{{user.email}}</t.Cell>
              <t.Cell>
                <Chip @color={{user.statusColor}} @size='sm'>
                  {{user.status}}
                </Chip>
              </t.Cell>
            </t.Row>
          {{/each}}
        </t.Body>
      </SimpleTable>
    </div>
  </template>
}
```

### Custom Classes

Apply custom styling to specific table elements:

```gts preview collapsible
import Component from '@glimmer/component';
import { SimpleTable } from 'frontile';
import { Chip } from 'frontile';
import { hash } from '@ember/helper';

export default class DemoComponent extends Component {
  items = [
    {
      name: 'Critical Server Issue',
      value: '$1,000',
      priority: 'High',
      priorityColor: 'danger'
    },
    {
      name: 'Feature Enhancement',
      value: '$500',
      priority: 'Medium',
      priorityColor: 'warning'
    },
    {
      name: 'Documentation Update',
      value: '$100',
      priority: 'Low',
      priorityColor: 'success'
    }
  ];

  <template>
    <div class='demo-stack demo-stack--wide'>
      <SimpleTable
        @classes={{hash
          wrapper='border-2 border-primary-soft rounded-lg overflow-hidden'
          table='border-separate border-spacing-0'
          thead='bg-gradient-to-r from-primary-subtle to-primary-soft'
          th='font-bold text-primary-strong border-b border-primary-soft'
          tr='hover:bg-primary-subtle transition-colors'
          td='border-b border-primary-subtle'
        }}
        as |t|
      >
        <t.Header>
          <t.Column>Task Name</t.Column>
          <t.Column>Estimated Value</t.Column>
          <t.Column>Priority</t.Column>
        </t.Header>
        <t.Body>
          {{#each this.items as |item|}}
            <t.Row>
              <t.Cell>{{item.name}}</t.Cell>
              <t.Cell class='font-mono'>{{item.value}}</t.Cell>
              <t.Cell>
                <Chip @color={{item.priorityColor}} @size='sm'>
                  {{item.priority}}
                </Chip>
              </t.Cell>
            </t.Row>
          {{/each}}
        </t.Body>
      </SimpleTable>
    </div>
  </template>
}
```

## Table Footers

Add footers for summaries and totals:

```gts preview collapsible
import Component from '@glimmer/component';
import { SimpleTable } from 'frontile';

export default class DemoComponent extends Component {
  orders = [
    { id: '#001', product: 'Laptop', quantity: 2, price: 999.99 },
    { id: '#002', product: 'Mouse', quantity: 5, price: 29.99 },
    { id: '#003', product: 'Keyboard', quantity: 3, price: 79.99 }
  ];

  get totalQuantity() {
    return this.orders.reduce((sum, order) => sum + order.quantity, 0);
  }

  get totalValue() {
    return this.orders.reduce(
      (sum, order) => sum + order.quantity * order.price,
      0
    );
  }

  calculateTotal = (quantity, price) => (quantity * price).toFixed(2);

  <template>
    <div class='demo-stack demo-stack--wide'>
      <SimpleTable as |t|>
        <t.Header>
          <t.Column>Order ID</t.Column>
          <t.Column>Product</t.Column>
          <t.Column>Quantity</t.Column>
          <t.Column>Unit Price</t.Column>
          <t.Column>Total</t.Column>
        </t.Header>
        <t.Body>
          {{#each this.orders as |order|}}
            <t.Row>
              <t.Cell>{{order.id}}</t.Cell>
              <t.Cell>{{order.product}}</t.Cell>
              <t.Cell>{{order.quantity}}</t.Cell>
              <t.Cell>${{order.price}}</t.Cell>
              <t.Cell>${{this.calculateTotal
                  order.quantity
                  order.price
                }}</t.Cell>
            </t.Row>
          {{/each}}
        </t.Body>
        <t.Footer>
          <t.Column colspan='2' class='font-semibold'>Order Summary</t.Column>
          <t.Column class='font-semibold'>{{this.totalQuantity}}
            items</t.Column>
          <t.Column />
          <t.Column class='font-bold text-lg'>${{this.totalValue}}</t.Column>
        </t.Footer>
      </SimpleTable>
    </div>
  </template>
}
```

## Loading State

SimpleTable supports loading states with different color variants to indicate when data is being fetched or processed.

```gts preview collapsible
import Component from '@glimmer/component';
import { SimpleTable } from 'frontile';
import { Select } from 'frontile';
import { tracked } from '@glimmer/tracking';
import { on } from '@ember/modifier';
import { Button } from 'frontile';

interface Product {
  id: string;
  name: string;
  price: number;
  category: string;
}

export default class DemoComponent extends Component {
  @tracked isLoading = true;
  @tracked loadingColor = 'primary';

  items: Product[] = [
    {
      id: '1',
      name: 'Wireless Headphones',
      price: 199.99,
      category: 'Electronics'
    },
    { id: '2', name: 'Coffee Mug', price: 12.99, category: 'Kitchen' },
    { id: '3', name: 'Notebook Set', price: 24.99, category: 'Office' }
  ];

  colorOptions = [
    { key: 'default', name: 'Default' },
    { key: 'primary', name: 'Primary' },
    { key: 'success', name: 'Success' },
    { key: 'warning', name: 'Warning' },
    { key: 'danger', name: 'Danger' }
  ];

  toggleLoading = () => {
    this.isLoading = !this.isLoading;
  };

  updateLoadingColor = (color) => {
    this.loadingColor = color;
  };

  <template>
    <div class='demo-stack demo-stack--wide'>
      <div class='space-y-4'>
        <div class='flex items-end space-x-4 justify-center'>
          <Button
            @onPress={{this.toggleLoading}}
            @size='sm'
            @variant='outline'
            @color={{if this.isLoading 'danger' 'primary'}}
          >
            {{if this.isLoading 'Stop Loading' 'Start Loading'}}
          </Button>

          <Select
            @inputSize='sm'
            @label='Color'
            @items={{this.colorOptions}}
            @selectedKey={{this.loadingColor}}
            @onSelectionChange={{this.updateLoadingColor}}
            class='w-32'
          />
        </div>

        <SimpleTable
          @isLoading={{this.isLoading}}
          @loadingColor={{this.loadingColor}}
          as |t|
        >
          <t.Header>
            <t.Column>ID</t.Column>
            <t.Column>Product</t.Column>
            <t.Column>Price</t.Column>
            <t.Column>Category</t.Column>
          </t.Header>
          <t.Body>
            {{#each this.items as |item|}}
              <t.Row>
                <t.Cell>{{item.id}}</t.Cell>
                <t.Cell>{{item.name}}</t.Cell>
                <t.Cell>${{item.price}}</t.Cell>
                <t.Cell>{{item.category}}</t.Cell>
              </t.Row>
            {{/each}}
          </t.Body>
        </SimpleTable>
      </div>
    </div>
  </template>
}
```

The loading feature supports five color variants:

- **`default`** - Standard gray loading animation
- **`primary`** - Uses the primary theme color
- **`success`** - Green loading animation for success states
- **`warning`** - Orange/yellow loading animation for warnings
- **`danger`** - Red loading animation for error states

## Accessibility

SimpleTable renders real table markup — `<table>`, `<thead>`, `<tbody>`, `<tfoot>`, `<tr>`,
`<th>`, `<td>` — so screen readers get row and column structure, dimensions, and cell
navigation from the browser rather than from ARIA. That is the whole reason to reach for it
over a grid of divs.

Header cells carry `scope="col"`, which associates a column's data cells with its header for
assistive technology. If you need a row header, put `scope="row"` on that cell yourself —
the `...attributes` spread means it overrides the default.

Two things the component cannot do for you:

- **Give the table an accessible name** when the surrounding page doesn't already. Add a
  `<caption>` in the default block, or `aria-labelledby` on the table pointing at a heading.
- **Keep the markup semantic if you nest interactive content in cells.** A button inside a
  `<td>` is fine; a click handler on the `<tr>` itself is not reachable by keyboard.

If the table scrolls (`@isScrollable`), the scroll container needs to be keyboard reachable
so someone can scroll it without a mouse — give it `tabindex="0"` and a label.

## API

### SimpleTable

**Element:** `HTMLTableElement`

**Arguments**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `classes` | `SlotsToClasses<'base' \| 'separator' \| 'wrapper' \| 'empty' \| 'table' \| 'toolbar' \| 'thead' \| 'tbody' \| 'tfoot' \| 'tr' \| 'th' \| 'sortButton' \| 'sortIcon' \| 'columnVisibilityButton' \| 'columnVisibilityIcon' \| 'td' \| 'skeleton' \| 'skeletonRow'>` | - | Custom CSS classes for different table elements (wrapper, table, th, td, etc.) |
| `hasCustomLoading` | `boolean` | - | Whether a custom loading block is provided (disables CSS loading indicator) |
| `hasWrapper` | `boolean` | `true` | Whether to render the wrapper div. |
| `isLoading` | `boolean` | - | Enable loading state styling and behavior |
| `isScrollable` | `boolean` | - | Enable scrolling for the table container |
| `isStriped` | `boolean` | - | Enable striped rows (alternating background colors) |
| `layout` | `'auto' \| 'fixed'` | `'auto'` | Table layout algorithm - 'auto' sizes columns by content, 'fixed' uses first row for sizing. |
| `loadingColor` | `'default' \| 'primary' \| 'success' \| 'warning' \| 'danger'` | `'default'` | Color variant for loading animation. |
| `selectionColor` | `'default' \| 'primary' \| 'success' \| 'warning' \| 'danger'` | `'primary'` | Color variant for selection highlight. |
| `size` | `'sm' \| 'md' \| 'lg'` | `'md'` | Size variant for table cells and headers. |

**Blocks**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `default *` | `[{ Header: SimpleTableHeader (styleFns, classes bound); Body: SimpleTableBody (styleFns, classes bound); Footer: SimpleTableFooter (styleFns, classes bound); Column: SimpleTableColumn (styleFns bound); Row: SimpleTableRow (styleFns, classes bound); Cell: SimpleTableCell (styleFns, classes bound); }]` | - |  |
### SimpleTableHeader

**Element:** `HTMLTableSectionElement`

**Arguments**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `class` | `string` | - | Additional CSS class to apply to the header section |
| `isSticky` | `boolean` | - | Whether the header should be sticky during vertical scrolling |

**Blocks**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `default *` | `[{ Column: typeof SimpleTableColumn; }]` | - |  |
### SimpleTableBody

**Element:** `HTMLTableSectionElement`

**Arguments**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `class` | `string` | - | Additional CSS class to apply to the body section |

**Blocks**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `default *` | `[{ Row: SimpleTableRow (styleFns, classes bound); Cell: SimpleTableCell (styleFns, classes bound); }]` | - |  |
### SimpleTableFooter

**Element:** `HTMLTableSectionElement`

**Arguments**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `class` | `string` | - | Additional CSS class to apply to the footer element |
| `isSticky` | `boolean` | - | Whether this footer should be sticky during vertical scrolling |

**Blocks**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `default *` | `[{ Column: typeof SimpleTableColumn; }]` | - |  |
### SimpleTableColumn

**Element:** `HTMLTableCellElement`

**Arguments**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `class` | `string` | - | Additional CSS class to apply to the header cell |
| `isSticky` | `boolean` | - | Whether this column should be sticky during horizontal scrolling |
| `stickyPosition` | `'right' \| 'left'` | - | Position where the sticky column should stick. |

**Blocks**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `default *` | `[]` | - |  |
### SimpleTableRow

**Element:** `HTMLTableRowElement`

**Arguments**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `class` | `string` | - | Additional CSS class to apply to the row |
| `hasStickyHeader` | `boolean` | - | Whether the table has a sticky header (affects positioning of sticky rows) |
| `isSticky` | `boolean` | - | Whether this row should be sticky during vertical scrolling |

**Blocks**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `default *` | `[{ Cell: SimpleTableCell (styleFns, classes bound); }]` | - |  |
### SimpleTableCell

**Element:** `HTMLTableCellElement`

**Arguments**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `class` | `string` | - | Additional CSS class to apply to the cell |
| `isInStickyRow` | `boolean` | - | Whether this cell is part of a sticky row (used for intersection styling) |
| `isSticky` | `boolean` | - | Whether this cell should be sticky during horizontal scrolling |
| `stickyPosition` | `'right' \| 'left'` | - | Position where the sticky cell should stick. |

**Blocks**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `default *` | `[]` | - |  |

---

# Table

Source: /docs/components/collections/table.md

# Table

Renders structured data automatically from `@columns` and `@items`, with sticky headers, sorting, column visibility, and scrollable containers.

**Key Features:**

- Automatic rendering with type-safe column definitions
- Row selection (single or multiple with checkboxes)
- Sticky elements (headers, footers, columns, rows)
- Scrollable containers for large datasets
- Column sorting and visibility controls
- Custom cell and header rendering
- Loading and empty states

For manual composition and custom layouts, use [SimpleTable](./simple-table) instead.

## Import

```js
import { Table, type ColumnConfig } from 'frontile';
```

## Usage

Define columns and items to render a table automatically:

```gts preview
import Component from '@glimmer/component';
import { Table, type ColumnConfig } from 'frontile';
import { users, type User } from 'site/components/table-demo-data';

export default class DemoComponent extends Component {
  columns = [
    { key: 'id', name: 'ID' },
    { key: 'name', name: 'Name' },
    { key: 'email', name: 'Email' },
    { key: 'role', name: 'Role' }
  ] as const satisfies ColumnConfig<User>[];

  <template>
    <div class='demo-stack demo-stack--wide'>
      <Table @columns={{this.columns}} @items={{users}} />
    </div>
  </template>
}
```

## Anatomy

`Table` combines a scroll container, header, body, rows, columns, and cells from `@columns`
and `@items`. Custom header and cell components receive the same column and row context used
by the default renderers.

## Column Configuration

### Custom Value Functions

Transform or compute values dynamically:

```gts preview
import Component from '@glimmer/component';
import { Table, type ColumnConfig } from 'frontile';
import { users, type User } from 'site/components/table-demo-data';

export default class DemoComponent extends Component {
  columns = [
    { key: 'name', name: 'Name' },
    {
      key: 'email',
      name: 'Contact',
      value: (ctx) => ctx.row.data.email.toUpperCase()
    },
    {
      key: 'status',
      name: 'Admin',
      value: (ctx) => (ctx.row.data.role === 'admin' ? 'Yes' : 'No')
    }
  ] as const satisfies ColumnConfig<User>[];

  <template>
    <div class='demo-stack demo-stack--wide'>
      <Table @columns={{this.columns}} @items={{users}} />
    </div>
  </template>
}
```

### Column-Level Cell Components

Define reusable Cell components in your column configuration:

```gts preview collapsible
import Component from '@glimmer/component';
import { Table, type ColumnConfig, type CellSignature } from 'frontile';
import { Chip } from 'frontile';
import { users, type User } from 'site/components/table-demo-data';
import type { TOC } from '@ember/component/template-only';

const StatusCell: TOC<CellSignature<User>> = <template>
  <Chip
    @size='sm'
    @variant='outline'
    @color='{{if (eq @row.data.status "active") "success" "danger"}}'
    @withDot={{true}}
  >
    {{@row.data.status}}
  </Chip>
</template>;

export default class DemoComponent extends Component {
  columns = [
    { key: 'name', name: 'Name' },
    { key: 'email', name: 'Email' },
    { key: 'status', name: 'Status', Cell: StatusCell }
  ] as const satisfies ColumnConfig<User>[];

  <template>
    <div class='demo-stack demo-stack--wide'>
      <Table @columns={{this.columns}} @items={{users}} />
    </div>
  </template>
}

function eq(a: string | undefined, b: string) {
  return a === b;
}
```

## Styling

Control table appearance with size, striping, and layout options:

```gts preview
import Component from '@glimmer/component';
import { Table, type ColumnConfig } from 'frontile';
import { users, type User } from 'site/components/table-demo-data';
import { hash } from '@ember/helper';

export default class DemoComponent extends Component {
  columns = [
    { key: 'name', name: 'Name' },
    { key: 'email', name: 'Email' },
    { key: 'role', name: 'Role' }
  ] as const satisfies ColumnConfig<User>[];

  <template>
    <div class='demo-stack demo-stack--wide'>
      <Table
        @columns={{this.columns}}
        @items={{users}}
        @size='sm'
        @isStriped={{true}}
        @classes={{hash wrapper='shadow-lg rounded-xl'}}
      />
    </div>
  </template>
}
```

**Options:**

- `@size` - `sm`, `md` (default), `lg`
- `@isStriped` - Alternating row colors
- `@layout` - `auto` (default), `fixed`
- `@classes` - Custom CSS classes

## Scrollable Tables

Enable scrolling with fixed heights or widths:

```gts preview
import Component from '@glimmer/component';
import { Table, type ColumnConfig } from 'frontile';
import { employees, type Employee } from 'site/components/table-demo-data';
import { hash } from '@ember/helper';

export default class DemoComponent extends Component {
  columns = [
    { key: 'id', name: 'ID' },
    { key: 'name', name: 'Name' },
    { key: 'email', name: 'Email' },
    { key: 'department', name: 'Department' },
    { key: 'role', name: 'Role' }
  ] as const satisfies ColumnConfig<Employee>[];

  <template>
    <div class='demo-stack demo-stack--wide'>
      <Table
        @columns={{this.columns}}
        @items={{employees}}
        @isScrollable={{true}}
        @classes={{hash wrapper='h-48'}}
      />
    </div>
  </template>
}
```

## Sticky Elements

Sticky parts of a table — a frozen header or footer, sticky rows, pinned columns
— are painted with `surface-table`, the same opaque surface as the table itself,
so they cover the rows and columns that scroll under them. Pinned columns keep
their row's selection, hover, and striping.

Tables assume they sit on a canvas-backed page. On any other background, point
`--color-surface-table` at it — in CSS, or through `@classes`:

```gts
<Table
  @columns={{this.columns}}
  @items={{this.items}}
  @isScrollable={{true}}
  @classes={{hash wrapper='[--color-surface-table:var(--color-surface-app)]'}}
/>
```

Whatever you point it at has to be opaque. See
[Surfaces](/docs/theming/design-tokens/surfaces) for the role itself.

### Sticky Header

Keep the header visible while scrolling:

```gts preview
import Component from '@glimmer/component';
import { Table, type ColumnConfig } from 'frontile';
import { users, type User } from 'site/components/table-demo-data';
import { hash } from '@ember/helper';

export default class DemoComponent extends Component {
  columns = [
    { key: 'name', name: 'Name' },
    { key: 'email', name: 'Email' },
    { key: 'role', name: 'Role' }
  ] as const satisfies ColumnConfig<User>[];

  moreUsers = [
    ...users,
    ...users.map((u, i) => ({ ...u, id: `${parseInt(u.id) + 3 + i}` })),
    ...users.map((u, i) => ({ ...u, id: `${parseInt(u.id) + 6 + i}` }))
  ];

  <template>
    <div class='demo-stack demo-stack--wide'>
      <Table
        @columns={{this.columns}}
        @items={{this.moreUsers}}
        @isStickyHeader={{true}}
        @isScrollable={{true}}
        @classes={{hash wrapper='h-48'}}
      />
    </div>
  </template>
}
```

### Sticky Columns

Pin columns to the left or right during horizontal scrolling:

```gts preview collapsible
import Component from '@glimmer/component';
import { Table, type ColumnConfig } from 'frontile';
import { employees, type Employee } from 'site/components/table-demo-data';
import { hash } from '@ember/helper';

export default class DemoComponent extends Component {
  columns = [
    {
      key: 'id',
      name: 'ID',
      isSticky: true,
      stickyPosition: 'left'
    },
    { key: 'name', name: 'Name' },
    { key: 'email', name: 'Email' },
    { key: 'phone', name: 'Phone' },
    { key: 'department', name: 'Department' },
    { key: 'role', name: 'Role' },
    { key: 'location', name: 'Location' },
    {
      key: 'actions',
      name: 'Actions',
      isSticky: true,
      stickyPosition: 'right',
      value: () => 'Edit'
    }
  ] as const satisfies ColumnConfig<Employee>[];

  <template>
    <div class='demo-stack demo-stack--wide'>
      <Table
        @columns={{this.columns}}
        @items={{employees}}
        @isScrollable={{true}}
        @classes={{hash wrapper='max-w-2xl'}}
      />
    </div>
  </template>
}
```

### Sticky Rows

Freeze specific rows by their keys:

```gts preview collapsible
import Component from '@glimmer/component';
import { Table, type ColumnConfig } from 'frontile';
import { type User } from 'site/components/table-demo-data';
import { array, hash } from '@ember/helper';

export default class DemoComponent extends Component {
  columns = [
    { key: 'id', name: 'ID' },
    { key: 'name', name: 'Name' },
    { key: 'email', name: 'Email' },
    { key: 'role', name: 'Role' }
  ] as const satisfies ColumnConfig<User>[];

  items: User[] = [
    {
      id: 'admin',
      name: 'Admin User',
      email: 'admin@example.com',
      role: 'Administrator'
    },
    { id: '1', name: 'John Doe', email: 'john@example.com', role: 'Developer' },
    {
      id: '2',
      name: 'Jane Smith',
      email: 'jane@example.com',
      role: 'Designer'
    },
    { id: '3', name: 'Bob Johnson', email: 'bob@example.com', role: 'Manager' },
    {
      id: 'guest',
      name: 'Guest User',
      email: 'guest@example.com',
      role: 'Read-only'
    }
  ];

  <template>
    <div class='demo-stack demo-stack--wide'>
      <Table
        @columns={{this.columns}}
        @items={{this.items}}
        @stickyKeys={{array 'admin' 'guest'}}
        @isScrollable={{true}}
        @classes={{hash wrapper='h-48'}}
      />
    </div>
  </template>
}
```

## Table Footer

Display summary information with `@footerColumns`:

```gts preview
import Component from '@glimmer/component';
import { Table, type ColumnConfig } from 'frontile';
import { products, type Product } from 'site/components/table-demo-data';

export default class DemoComponent extends Component {
  columns = [
    { key: 'name', name: 'Product' },
    { key: 'price', name: 'Price', value: (ctx) => `$${ctx.row.data.price}` },
    { key: 'category', name: 'Category' }
  ] as const satisfies ColumnConfig<Product>[];

  footerColumns = [
    { key: 'label', name: 'Total Items' },
    { key: 'total', name: '$1,109.97' },
    { key: 'categories', name: '2 Categories' }
  ] as const satisfies ColumnConfig[];

  <template>
    <div class='demo-stack demo-stack--wide'>
      <Table
        @columns={{this.columns}}
        @items={{products}}
        @footerColumns={{this.footerColumns}}
      />
    </div>
  </template>
}
```

**Sticky Footer:** Add `@isStickyFooter={{true}}` to keep the footer visible.

## Loading State

Show loading indicators while data is being fetched:

```gts preview collapsible
import Component from '@glimmer/component';
import { tracked } from '@glimmer/tracking';
import { Table, type ColumnConfig } from 'frontile';
import { products, type Product } from 'site/components/table-demo-data';
import { Button } from 'frontile';
import { Select } from 'frontile';

export default class DemoComponent extends Component {
  @tracked isLoading = true;
  @tracked loadingColor = 'primary';

  columns = [
    { key: 'name', name: 'Product' },
    { key: 'price', name: 'Price', value: (ctx) => `$${ctx.row.data.price}` },
    { key: 'category', name: 'Category' }
  ] as const satisfies ColumnConfig<Product>[];

  colorOptions = [
    { key: 'default', name: 'Default' },
    { key: 'primary', name: 'Primary' },
    { key: 'success', name: 'Success' },
    { key: 'warning', name: 'Warning' },
    { key: 'danger', name: 'Danger' }
  ];

  toggleLoading = () => {
    this.isLoading = !this.isLoading;
  };

  updateLoadingColor = (color: string) => {
    this.loadingColor = color;
  };

  <template>
    <div class='demo-stack demo-stack--wide'>
      <div class='space-y-4'>
        <div class='flex items-end space-x-4 justify-center'>
          <Button
            @onPress={{this.toggleLoading}}
            @size='sm'
            @variant='outline'
            @color={{if this.isLoading 'danger' 'primary'}}
          >
            {{if this.isLoading 'Stop Loading' 'Start Loading'}}
          </Button>
          <Select
            @inputSize='sm'
            @label='Color'
            @items={{this.colorOptions}}
            @selectedKey={{this.loadingColor}}
            @onSelectionChange={{this.updateLoadingColor}}
            class='w-32'
          />
        </div>
        <Table
          @columns={{this.columns}}
          @items={{products}}
          @isLoading={{this.isLoading}}
          @loadingColor={{this.loadingColor}}
        />
      </div>
    </div>
  </template>
}
```

The hairline under the header is a subtle indicator, for tables that already
have content and are merely refreshing it. When a table is loading with nothing
on screen yet, prefer the built-in skeleton rows below instead.

### Built-in skeleton rows

`@skeletonRows` renders placeholder rows while the table is loading and has no
items. It is opt-in, and the row count is required — there is no default.

Load the data below to watch the placeholders hand off to real rows.

```gts preview collapsible
import Component from '@glimmer/component';
import { tracked } from '@glimmer/tracking';
import { on } from '@ember/modifier';
import { Table, Button, type ColumnConfig } from 'frontile';
import { users, type User } from 'site/components/table-demo-data';

export default class DemoComponent extends Component {
  columns = [
    { key: 'name', name: 'Name' },
    { key: 'email', name: 'Email' },
    { key: 'role', name: 'Role' }
  ] as const satisfies ColumnConfig<User>[];

  @tracked isLoading = true;
  @tracked items: User[] = [];

  timer?: ReturnType<typeof setTimeout>;

  load = () => {
    this.reset();
    this.timer = setTimeout(() => {
      this.items = users;
      this.isLoading = false;
    }, 1600);
  };

  reset = () => {
    clearTimeout(this.timer);
    this.isLoading = true;
    this.items = [];
  };

  willDestroy() {
    super.willDestroy();
    clearTimeout(this.timer);
  }

  <template>
    <div class='demo-stack demo-stack--wide'>
      <div class='w-full space-y-3'>
        <div class='flex gap-2'>
          <Button @size='sm' @color='primary' {{on 'click' this.load}}>
            Load data
          </Button>
          <Button @size='sm' @variant='outline' {{on 'click' this.reset}}>
            Back to loading
          </Button>
        </div>

        <Table
          @columns={{this.columns}}
          @items={{this.items}}
          @isLoading={{this.isLoading}}
          @skeletonRows={{5}}
        />
      </div>
    </div>
  </template>
}
```

Placeholder rows fade in one after another, 60ms apart, so they arrive the way
the real rows will rather than appearing as one block. The stagger stops
growing after ten rows, and `prefers-reduced-motion` turns it off entirely.

Skeleton rows render only when `@isLoading` is true **and** there are no items,
so a refresh, a filter requery, or loading page two never throws away rows the
user is already reading. `@emptyContent` and the `empty` block stay suppressed
while they render, and a `loading` block takes precedence when present.

Each placeholder cell is a [`Skeleton`](/docs/components/utilities/skeleton)
component, sized from the table's `@size` so the bars match the row height.

#### Shaping a column's placeholder

A text bar is wrong for a column that holds an avatar. Set `skeleton` on the
column to pick a shape — it accepts the same values as `Skeleton`'s `@shape`,
and columns that omit it stay text bars.

```gts preview
import { array } from '@ember/helper';
import { Table } from 'frontile';

const columns = [
  { key: 'avatar', name: '', skeleton: 'circle' },
  { key: 'name', name: 'Name' },
  { key: 'thumb', name: 'Preview', skeleton: 'square' },
  { key: 'role', name: 'Role' }
];

<template>
  <div class='demo-stack demo-stack--wide'>
    <Table
      @columns={{columns}}
      @items={{(array)}}
      @isLoading={{true}}
      @skeletonRows={{4}}
    />
  </div>
</template>
```

Because `circle` and `square` reuse Avatar's size scale, a placeholder in an
`@size="md"` table is the same 32px as the `<Avatar @size="md">` it stands in
for.

`skeleton` sets the shape and nothing else. For anything richer — cells that
stack an icon, a name and a chip, or per-column widths — use `bodyTop` with the
yielded columns and render `Skeleton` yourself for each piece of content.

If neither the built-in skeleton rows nor a custom `bodyTop` layout fit —
for example, an overlay that needs to sit over content that is already on
screen — use the `loading` named block described next.

### Custom Loading Indicator

Use the `loading` named block for custom indicators:

```gts preview collapsible
import Component from '@glimmer/component';
import { tracked } from '@glimmer/tracking';
import { Table, type ColumnConfig } from 'frontile';
import { products, type Product } from 'site/components/table-demo-data';
import { Button } from 'frontile';
import { Spinner } from 'frontile';

export default class DemoComponent extends Component {
  @tracked isLoading = true;

  columns = [
    { key: 'name', name: 'Product' },
    { key: 'price', name: 'Price' },
    { key: 'category', name: 'Category' }
  ] as const satisfies ColumnConfig<Product>[];

  toggleLoading = () => {
    this.isLoading = !this.isLoading;
  };

  <template>
    <div class='demo-stack demo-stack--wide'>
      <div class='space-y-4'>
        <Button @onPress={{this.toggleLoading}} @size='sm' @variant='outline'>
          {{if this.isLoading 'Stop Loading' 'Start Loading'}}
        </Button>
        <div class='relative'>
          <Table
            @columns={{this.columns}}
            @items={{products}}
            @isLoading={{this.isLoading}}
          >
            <:loading>
              <div
                class='absolute inset-0 z-10 bg-surface-canvas/80 backdrop-blur-sm flex items-center justify-center'
              >
                <Spinner @size='lg' />
              </div>
            </:loading>
          </Table>
        </div>
      </div>
    </div>
  </template>
}
```

## Empty State

### Custom Empty Content

Display custom content when there are no items:

```gts preview
import Component from '@glimmer/component';
import { Table, type ColumnConfig } from 'frontile';
import { type User } from 'site/components/table-demo-data';
import { Button } from 'frontile';

export default class DemoComponent extends Component {
  columns = [
    { key: 'id', name: 'ID' },
    { key: 'name', name: 'Name' },
    { key: 'email', name: 'Email' }
  ] as const satisfies ColumnConfig<User>[];

  emptyItems: User[] = [];

  <template>
    <div class='demo-stack demo-stack--wide'>
      <Table @columns={{this.columns}} @items={{this.emptyItems}}>
        <:empty>
          <div class='text-center py-8'>
            <h3 class='text-lg font-medium mb-2'>No Users Found</h3>
            <p class='text-muted mb-4'>Get started by adding your first user.</p>
            <Button @color='primary' @size='sm'>Add User</Button>
          </div>
        </:empty>
      </Table>
    </div>
  </template>
}
```

### Simple Text

Use `@emptyContent` for plain text messages:

```gts preview
import Component from '@glimmer/component';
import { Table, type ColumnConfig } from 'frontile';
import { type User } from 'site/components/table-demo-data';

export default class DemoComponent extends Component {
  columns = [
    { key: 'id', name: 'ID' },
    { key: 'name', name: 'Name' },
    { key: 'email', name: 'Email' }
  ] as const satisfies ColumnConfig<User>[];

  emptyItems: User[] = [];

  <template>
    <div class='demo-stack demo-stack--wide'>
      <Table
        @columns={{this.columns}}
        @items={{this.emptyItems}}
        @emptyContent='No users available'
      />
    </div>
  </template>
}
```

## Custom Cell Rendering

Use the `:cell` block for custom cell content. Alternatively, you can define a `Cell` component in the [column configuration](#column-level-cell-components) for reusable cell rendering.

```gts preview collapsible
import Component from '@glimmer/component';
import { Table, type ColumnConfig } from 'frontile';
import { users, type User } from 'site/components/table-demo-data';
import { Avatar } from 'frontile';
import { Chip } from 'frontile';

export default class DemoComponent extends Component {
  columns = [
    { key: 'name', name: 'Name' },
    { key: 'email', name: 'Email' },
    { key: 'role', name: 'Role' },
    { key: 'status', name: 'Status' }
  ] as const satisfies ColumnConfig<User>[];

  <template>
    <div class='demo-stack demo-stack--wide'>
      <Table @columns={{this.columns}} @items={{users}}>
        <:cell as |c|>
          <c.For @key='name'>
            <div class='flex items-center space-x-2'>
              <Avatar
                @name={{c.value}}
                @size='sm'
                @src='https://i.pravatar.cc/150?img={{c.value}}'
              />
              <span class='font-medium'>{{c.value}}</span>
            </div>
          </c.For>

          <c.For @key='status'>
            <Chip
              @size='sm'
              @variant='outline'
              @color='{{if (eq c.value "active") "success" "danger"}}'
              @withDot={{true}}
            >
              {{c.value}}
            </Chip>

          </c.For>

          <c.Default>
            {{c.value}}
          </c.Default>
        </:cell>
      </Table>
    </div>
  </template>
}

function eq(a: string | undefined, b: string) {
  return a === b;
}
```

**Context:**

- `c.column` - Column configuration
- `c.row` - Row data
- `c.value` - Computed cell value
- `c.For` - Render for specific column key
- `c.Default` - Fallback for unmatched columns

## Custom Header Rendering

Customize column headers with the `header` block:

```gts preview collapsible
import Component from '@glimmer/component';
import { Table, type ColumnConfig } from 'frontile';
import { users, type User } from 'site/components/table-demo-data';
import { UserIcon } from 'site/components/icons';

export default class DemoComponent extends Component {
  columns = [
    { key: 'name', name: 'Full Name' },
    { key: 'email', name: 'Email' },
    { key: 'role', name: 'Role' }
  ] as const satisfies ColumnConfig<User>[];

  <template>
    <div class='demo-stack demo-stack--wide'>
      <Table @columns={{this.columns}} @items={{users}}>
        <:header as |h|>
          {{#if (eq h.column.key 'name')}}
            <div class='flex items-center space-x-2'>
              <UserIcon />
              <span>{{h.column.name}}</span>
            </div>
          {{else}}
            {{h.column.name}}
          {{/if}}
        </:header>
      </Table>
    </div>
  </template>
}

function eq(a: string, b: string) {
  return a === b;
}
```

## Body Sections

Add custom rows at the top or bottom of the table body:

```gts preview collapsible
import Component from '@glimmer/component';
import { Table, type ColumnConfig } from 'frontile';
import { products, type Product } from 'site/components/table-demo-data';

export default class DemoComponent extends Component {
  columns = [
    { key: 'name', name: 'Product' },
    { key: 'price', name: 'Price', value: (ctx) => `$${ctx.row.data.price}` }
  ] as const satisfies ColumnConfig<Product>[];

  get total() {
    return products.reduce((sum, p) => sum + p.price, 0).toFixed(2);
  }

  <template>
    <div class='demo-stack demo-stack--wide'>
      <Table @columns={{this.columns}} @items={{products}}>
        <:bodyTop>
          <tr>
            <td colspan='2' class='bg-muted/30 px-4 py-2 font-medium'>
              Order Summary
            </td>
          </tr>
        </:bodyTop>
        <:bodyBottom>
          <tr>
            <td colspan='2' class='bg-muted/50 px-4 py-3 flex justify-between'>
              <span>Total:</span>
              <span class='font-semibold'>${{this.total}}</span>
            </td>
          </tr>
        </:bodyBottom>
      </Table>
    </div>
  </template>
}
```

### Column-aligned rows in `bodyTop` / `bodyBottom`

`bodyTop` and `bodyBottom` yield the columns the table is actually rendering,
along with style-bound `Row` and `Cell` components. Use these instead of
hand-written `<tr>`/`<td>` so your rows stay aligned when a column is hidden
via `ColumnVisibility` and when `@selectionMode="multiple"` adds its checkbox
column.

```gts preview
import { array } from '@ember/helper';
import { Table, Skeleton } from 'frontile';

const columns = [
  { key: 'name', name: 'Name' },
  { key: 'email', name: 'Email' }
];

<template>
  <div class='demo-stack demo-stack--wide'>
    <Table @columns={{columns}} @items={{(array)}}>
      <:bodyTop as |b|>
        <b.Row>
          {{#each b.columns as |column|}}
            <b.Cell data-column={{column.key}}>
              <Skeleton />
            </b.Cell>
          {{/each}}
        </b.Row>
      </:bodyTop>
    </Table>
  </div>
</template>
```

`b.columns` is the rendered column list, not the `@columns` argument you passed
in. Treat `b.columns` as read-only. It is the table's live column list, not a
copy — mutating it in place (`sort`, `push`, `splice`) will corrupt the header
and the rendered rows. Copy it first if you need a different order. `b.Row`
and `b.Cell` carry the table's resolved `@size` padding, sticky handling, and
`@classes` overrides.

The `loading` block yields `{ columns }` only — it renders inside a single
spanning cell, so `Row` and `Cell` would not be valid there. Use it for an
overlay or spinner over a table that already has content; use `bodyTop` for
rows that stand in for content that has not arrived yet.

### Data attributes

These are a supported contract, stable across minor versions:

| Attribute     | Element | Value                         |
| ------------- | ------- | ----------------------------- |
| `data-key`    | `<th>`  | the column's `key`            |
| `data-column` | `<td>`  | the column's `key`            |
| `data-key`    | `<tr>`  | the row's key, from `@getKey` |

Use them for column-targeted styling and test selectors.

Every element rendering one of Table's styled parts also carries a stable
`data-part` attribute (kebab-cased from the slot name — e.g. `wrapper`,
`table`, `thead`, `tbody`, `tr`, `th`, `td`, `sort-button`, `skeleton-row`),
and the outermost wrapping `<div>` carries `data-component="table"` (it is
the element that encloses everything Table renders, including the optional
toolbar, so it is the one stable anchor for `[data-component="table"] ...`
scoping). These mirror the slot names accepted by `@classes` and are safe
to use as test selectors, e.g. `[data-part="tr"]`.

## Column Visibility

Enable users to show/hide columns with the toolbar:

```gts preview
import Component from '@glimmer/component';
import { Table, type ColumnConfig } from 'frontile';
import { users, type User } from 'site/components/table-demo-data';

export default class DemoComponent extends Component {
  columns = [
    { key: 'id', name: 'ID', isVisible: true },
    { key: 'name', name: 'Name', isVisible: true },
    { key: 'email', name: 'Email', isVisible: false },
    { key: 'role', name: 'Role', isVisible: true }
  ] as const satisfies ColumnConfig<User>[];

  <template>
    <div class='demo-stack demo-stack--wide'>
      <Table @columns={{this.columns}} @items={{users}}>
        <:toolbar as |t|>
          <div class='flex items-center justify-between mb-4'>
            <h3 class='font-semibold'>User Management</h3>
            <t.ColumnVisibility />
          </div>
        </:toolbar>
      </Table>
    </div>
  </template>
}
```

**Initial State:** Set `isVisible: false` in column config to hide by default.

The `<:toolbar>` block's own wrapping element is styled through the
`toolbar` key on `@classes` (e.g. `@classes={{hash toolbar='...'}}`), the
same way `wrapper` and `table` are.

## Sorting

Enable column sorting with `isSortable` and `@onSort`:

```gts preview collapsible
import Component from '@glimmer/component';
import { tracked } from '@glimmer/tracking';
import { Table, type ColumnConfig, type SortItem } from 'frontile';
import { type User } from 'site/components/table-demo-data';

export default class DemoComponent extends Component {
  @tracked items: User[] = [
    { id: '1', name: 'Charlie', email: 'charlie@example.com', role: 'user' },
    { id: '2', name: 'Alice', email: 'alice@example.com', role: 'admin' },
    { id: '3', name: 'Bob', email: 'bob@example.com', role: 'user' }
  ];

  columns = [
    { key: 'name', name: 'Name', isSortable: true },
    { key: 'email', name: 'Email', isSortable: true },
    { key: 'role', name: 'Role' }
  ] as const satisfies ColumnConfig<User>[];

  handleSort = (items: User[], sort: SortItem<User>) => {
    if (sort.direction === 'none') return items;

    return [...items].sort((a, b) => {
      const aVal = a[sort.property];
      const bVal = b[sort.property];
      if (!aVal || !bVal) return 0;

      if (sort.direction === 'ascending') {
        return aVal < bVal ? -1 : aVal > bVal ? 1 : 0;
      }
      return aVal > bVal ? -1 : aVal < bVal ? 1 : 0;
    });
  };

  <template>
    <div class='demo-stack demo-stack--wide'>
      <Table
        @columns={{this.columns}}
        @items={{this.items}}
        @onSort={{this.handleSort}}
      />
    </div>
  </template>
}
```

**Features:**

- Tri-state sorting: descending → ascending → none
- Custom sort property: Use `sortProperty` to sort by a different field
- Initial sort: Set with `@initialSort`

## Row Selection

Enable row selection with `@selectionMode` for single or multiple row selection.

### Multiple Selection

Use checkboxes for multi-select with `selectionMode="multiple"`:

```gts preview collapsible
import Component from '@glimmer/component';
import { tracked } from '@glimmer/tracking';
import { Table, type ColumnConfig } from 'frontile';
import { type User } from 'site/components/table-demo-data';

export default class DemoComponent extends Component {
  @tracked selectedKeys = new Set<string>();

  items: User[] = [
    { id: '1', name: 'Alice', email: 'alice@example.com', role: 'admin' },
    { id: '2', name: 'Bob', email: 'bob@example.com', role: 'user' },
    { id: '3', name: 'Charlie', email: 'charlie@example.com', role: 'user' }
  ];

  columns = [
    { key: 'name', name: 'Name' },
    { key: 'email', name: 'Email' },
    { key: 'role', name: 'Role' }
  ] as const satisfies ColumnConfig<User>[];

  handleSelectionChange = (keys: Set<string>) => {
    this.selectedKeys = keys;
  };

  <template>
    <div class='demo-stack demo-stack--wide'>
      <div>
        <p class='mb-4 text-sm'>
          Selected:
          {{this.selectedKeys.size}}
          row(s)
        </p>
        <Table
          @columns={{this.columns}}
          @items={{this.items}}
          @selectionMode='multiple'
          @selectedKeys={{this.selectedKeys}}
          @onSelectionChange={{this.handleSelectionChange}}
        />
      </div>
    </div>
  </template>
}
```

### Single Selection

Use row clicks for single selection with `selectionMode="single"`:

```gts preview collapsible
import Component from '@glimmer/component';
import { tracked } from '@glimmer/tracking';
import { Table, type ColumnConfig } from 'frontile';
import { type User } from 'site/components/table-demo-data';

export default class DemoComponent extends Component {
  @tracked selectedKeys = new Set<string>();

  items: User[] = [
    { id: '1', name: 'Alice', email: 'alice@example.com', role: 'admin' },
    { id: '2', name: 'Bob', email: 'bob@example.com', role: 'user' },
    { id: '3', name: 'Charlie', email: 'charlie@example.com', role: 'user' }
  ];

  columns = [
    { key: 'name', name: 'Name' },
    { key: 'email', name: 'Email' },
    { key: 'role', name: 'Role' }
  ] as const satisfies ColumnConfig<User>[];

  handleSelectionChange = (keys: Set<string>) => {
    this.selectedKeys = keys;
  };

  get selectedUser() {
    const key = [...this.selectedKeys][0];
    return this.items.find((item) => item.id === key);
  }

  <template>
    <div class='demo-stack demo-stack--wide'>
      <div>
        <p class='mb-4 text-sm'>
          Selected:
          {{if this.selectedUser this.selectedUser.name 'None'}}
        </p>
        <Table
          @columns={{this.columns}}
          @items={{this.items}}
          @selectionMode='single'
          @selectedKeys={{this.selectedKeys}}
          @onSelectionChange={{this.handleSelectionChange}}
        />
      </div>
    </div>
  </template>
}
```

### Disabled Rows

Prevent specific rows from being selected with `@disabledKeys`:

```gts preview collapsible
import Component from '@glimmer/component';
import { tracked } from '@glimmer/tracking';
import { Table, type ColumnConfig } from 'frontile';
import { type User } from 'site/components/table-demo-data';

export default class DemoComponent extends Component {
  @tracked selectedKeys = new Set<string>();

  items: User[] = [
    { id: '1', name: 'Alice', email: 'alice@example.com', role: 'admin' },
    { id: '2', name: 'Bob', email: 'bob@example.com', role: 'user' },
    { id: '3', name: 'Charlie', email: 'charlie@example.com', role: 'user' }
  ];

  columns = [
    { key: 'name', name: 'Name' },
    { key: 'email', name: 'Email' },
    { key: 'role', name: 'Role' }
  ] as const satisfies ColumnConfig<User>[];

  disabledKeys = ['1'];

  handleSelectionChange = (keys: Set<string>) => {
    this.selectedKeys = keys;
  };

  <template>
    <div class='demo-stack demo-stack--wide'>
      <div>
        <p class='mb-4 text-sm'>
          Note: Admin users cannot be selected
        </p>
        <Table
          @columns={{this.columns}}
          @items={{this.items}}
          @selectionMode='multiple'
          @selectedKeys={{this.selectedKeys}}
          @onSelectionChange={{this.handleSelectionChange}}
          @disabledKeys={{this.disabledKeys}}
        />
      </div>
    </div>
  </template>
}
```

### Custom Key Extraction

Provide a custom function to extract unique keys from items:

```gts preview collapsible
import Component from '@glimmer/component';
import { tracked } from '@glimmer/tracking';
import { Table, type ColumnConfig } from 'frontile';

interface Product {
  sku: string;
  name: string;
  price: number;
}

export default class DemoComponent extends Component {
  @tracked selectedKeys = new Set<string>();

  items: Product[] = [
    { sku: 'ABC-123', name: 'Widget', price: 29.99 },
    { sku: 'DEF-456', name: 'Gadget', price: 49.99 },
    { sku: 'GHI-789', name: 'Doohickey', price: 19.99 }
  ];

  columns = [
    { key: 'sku', name: 'SKU' },
    { key: 'name', name: 'Product' },
    { key: 'price', name: 'Price' }
  ] as const satisfies ColumnConfig<Product>[];

  getItemKey = (item: Product) => item.sku;

  handleSelectionChange = (keys: Set<string>) => {
    this.selectedKeys = keys;
  };

  <template>
    <div class='demo-stack demo-stack--wide'>
      <Table
        @columns={{this.columns}}
        @items={{this.items}}
        @selectionMode='multiple'
        @selectedKeys={{this.selectedKeys}}
        @onSelectionChange={{this.handleSelectionChange}}
        @getKey={{this.getItemKey}}
      />
    </div>
  </template>
}
```

### Uncontrolled Selection

The Table supports uncontrolled selection, where internal state is managed automatically. Omit `@selectedKeys` and provide `@onSelectionChange` to monitor selections:

```gts preview collapsible
import Component from '@glimmer/component';
import { Table, type ColumnConfig } from 'frontile';
import { type User } from 'site/components/table-demo-data';

export default class DemoComponent extends Component {
  items: User[] = [
    { id: '1', name: 'Alice', email: 'alice@example.com', role: 'admin' },
    { id: '2', name: 'Bob', email: 'bob@example.com', role: 'user' },
    { id: '3', name: 'Charlie', email: 'charlie@example.com', role: 'user' }
  ];

  columns = [
    { key: 'name', name: 'Name' },
    { key: 'email', name: 'Email' },
    { key: 'role', name: 'Role' }
  ] as const satisfies ColumnConfig<User>[];

  handleSelectionChange = (keys: Set<string>) => {
    console.log('Selected keys:', Array.from(keys));
  };

  <template>
    <div class='demo-stack demo-stack--wide'>
      <Table
        @columns={{this.columns}}
        @items={{this.items}}
        @selectionMode='multiple'
        @onSelectionChange={{this.handleSelectionChange}}
      />
    </div>
  </template>
}
```

### Keyboard Navigation

When selection is enabled, rows follow the WAI-ARIA grid pattern:

- **Tab**: Moves into the rows. The table is a single tab stop — it uses a
  roving `tabindex`, so exactly one row is tabbable at a time. That is the row
  focus was last on, else the first selected row, else the first row.
- **Arrow Down** / **Arrow Up**: Move focus between rows, carrying the
  `tabindex="0"` along with focus. Focus wraps: down past the last row lands on
  the first, up past the first lands on the last.
- **Home** / **End**: Move focus to the first / last row.
- **Space** or **Enter**: Toggle selection (multiple mode) or select row (single mode)
- Disabled rows (`@disabledKeys`) are marked `aria-disabled="true"`. Arrow keys,
  `Home` and `End` skip them entirely, and they never hold the tab stop — a
  table whose first row is disabled hands it to the first enabled row instead.
  They can still be focused with the pointer, but not selected.
- Rows added, removed or reordered are picked up on their own; the tab stop and
  the navigation order always follow what is rendered.
- Interactive content inside cells keeps its own keys: a button, link or input in
  a cell handles Enter, Space and the arrow keys itself, and the row does not
  toggle its selection. Row keyboard handling only applies to keys pressed on the
  row itself.

This is the shared [`rovingFocus`](/docs/components/utilities/roving-focus) utility in vertical,
manual-activation mode — arrows move focus only, and selection waits for Space or Enter.

```gts preview collapsible
import Component from '@glimmer/component';
import { Table, type ColumnConfig } from 'frontile';
import { type User } from 'site/components/table-demo-data';

export default class DemoComponent extends Component {
  items: User[] = [
    { id: '1', name: 'Alice', email: 'alice@example.com', role: 'admin' },
    { id: '2', name: 'Bob', email: 'bob@example.com', role: 'user' },
    { id: '3', name: 'Charlie', email: 'charlie@example.com', role: 'user' }
  ];

  columns = [
    { key: 'name', name: 'Name' },
    { key: 'email', name: 'Email' },
    { key: 'role', name: 'Role' }
  ] as const satisfies ColumnConfig<User>[];

  <template>
    <div class='demo-stack demo-stack--wide'>
      <div>
        <p class='mb-4 text-sm text-neutral-strong'>
          Focus a row and press Space or Enter to select it
        </p>
        <Table
          @columns={{this.columns}}
          @items={{this.items}}
          @selectionMode='multiple'
        />
      </div>
    </div>
  </template>
}
```

### Selection Color

Customize the selection highlight color with `@selectionColor`. Available colors: `default`, `primary`, `success`, `warning`, `danger`:

```gts preview collapsible
import Component from '@glimmer/component';
import { tracked } from '@glimmer/tracking';
import { Table, type ColumnConfig } from 'frontile';
import { type User } from 'site/components/table-demo-data';
import { Select } from 'frontile';

export default class DemoComponent extends Component {
  @tracked selectedKeys = new Set(['1', '2']);
  @tracked selectionColor = 'primary';

  items: User[] = [
    { id: '1', name: 'Alice', email: 'alice@example.com', role: 'admin' },
    { id: '2', name: 'Bob', email: 'bob@example.com', role: 'user' },
    { id: '3', name: 'Charlie', email: 'charlie@example.com', role: 'user' }
  ];

  columns = [
    { key: 'name', name: 'Name' },
    { key: 'email', name: 'Email' },
    { key: 'role', name: 'Role' }
  ] as const satisfies ColumnConfig<User>[];

  colorOptions = [
    { key: 'default', name: 'Default' },
    { key: 'primary', name: 'Primary' },
    { key: 'success', name: 'Success' },
    { key: 'warning', name: 'Warning' },
    { key: 'danger', name: 'Danger' }
  ];

  handleSelectionChange = (keys: Set<string>) => {
    this.selectedKeys = keys;
  };

  updateSelectionColor = (color: string) => {
    this.selectionColor = color;
  };

  <template>
    <div class='demo-stack demo-stack--wide'>
      <div class='space-y-4'>
        <div class='flex items-end justify-center'>
          <Select
            @inputSize='sm'
            @label='Selection Color'
            @items={{this.colorOptions}}
            @selectedKey={{this.selectionColor}}
            @onSelectionChange={{this.updateSelectionColor}}
            class='w-40'
          />
        </div>
        <Table
          @columns={{this.columns}}
          @items={{this.items}}
          @selectionMode='multiple'
          @selectedKeys={{this.selectedKeys}}
          @onSelectionChange={{this.handleSelectionChange}}
          @selectionColor={{this.selectionColor}}
        />
      </div>
    </div>
  </template>
}
```

**Features:**

- **Multiple selection**: Checkbox column with select all/none and indeterminate state
- **Single selection**: Row clicks, no checkboxes
- **Controlled/Uncontrolled modes**: Provide `@selectedKeys` for controlled, omit for uncontrolled
- **Keyboard navigation**: Use Space or Enter keys to select rows
- **Disabled rows**: Prevent selection with `@disabledKeys`
- **Custom keys**: Use `@getKey` for non-standard key extraction
- **Selection colors**: Customize highlight with `@selectionColor` (default, primary, success, warning, danger)
- **Sticky selection column**: Auto-sticky on horizontal scroll
- **Select all control**: Hide with `@showSelectAll={{false}}`

## Accessibility

Table builds on [SimpleTable](./simple-table.md), so it inherits real table markup and
`scope="col"` header cells — structure and navigation come from the browser rather than ARIA.
On top of that:

| Feature             | What it exposes                                                                              |
| ------------------- | -------------------------------------------------------------------------------------------- |
| Sortable column     | `aria-sort` on the header cell, tracking `none` / `ascending` / `descending`                 |
| Sort control        | A real `<button>` inside the header, so it is focusable and activates on `Enter` and `Space` |
| Sort direction icon | `aria-hidden="true"` — the chevron is decoration, `aria-sort` carries the meaning            |
| Row selection       | A checkbox per row labelled "Select row", and "Select all rows" in the header                |
| Disabled row        | `aria-disabled="true"`, which is also what keyboard navigation reads to skip it              |
| Skeleton rows       | `aria-hidden="true"` while loading, so placeholder rows are not announced as data            |

`aria-sort` is present on every header cell, including non-sortable ones, where it reads
`none`. So the attribute's presence is not a reliable signal of whether a column can be
sorted; `data-sortable` is.

Two things to supply yourself:

- **An accessible name for the table.** Add a `<caption>`, or `aria-labelledby` pointing at
  the heading above it.
- **Better selection labels when rows are identifiable.** Every row checkbox is labelled
  "Select row", which is unambiguous only when a screen reader user is already inside the
  row. If your rows have a natural name, render your own checkbox in a cell with a label
  that includes it.

Sticky headers and footers are positioned with CSS and do not change the reading order.

## API

### Table

**Element:** `HTMLTableElement`

**Arguments**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `columns *` | `TColumns` | - | Array of column configurations for automatic table generation |
| `items *` | `T[]` | - | Array of data items to display in the table |
| `classes` | `SlotsToClasses<'base' \| 'separator' \| 'wrapper' \| 'empty' \| 'table' \| 'toolbar' \| 'thead' \| 'tbody' \| 'tfoot' \| 'tr' \| 'th' \| 'sortButton' \| 'sortIcon' \| 'columnVisibilityButton' \| 'columnVisibilityIcon' \| 'td' \| 'skeleton' \| 'skeletonRow'>` | - | Custom CSS classes for different table elements (wrapper, table, th, td, etc.) |
| `disabledKeys` | `string[]` | - | Array of keys that should be disabled from selection |
| `emptyContent` | `ContentValue` | - | Content to display when no data items are provided |
| `footerColumns` | `ColumnConfig<T>[]` | - | Array of column configurations for automatic footer generation |
| `getKey` | `(item: T) => string` | - | Function to extract unique key from an item. Defaults to using keyAndLabelForItem helper. |
| `initialSort` | `SortItem<T>` | - | Initial sort descriptor to apply on mount. Only used for initial render, subsequent changes are ignored. |
| `isLoading` | `boolean` | - | Enable loading state styling and behavior |
| `isScrollable` | `boolean` | - | Enable scrolling for the table container |
| `isStickyFooter` | `boolean` | - | Make the table footer sticky during vertical scrolling |
| `isStickyHeader` | `boolean` | - | Make the table header sticky during vertical scrolling |
| `isStriped` | `boolean` | - | Enable striped rows (alternating background colors) |
| `layout` | `'auto' \| 'fixed'` | `'auto'` | Table layout algorithm - 'auto' sizes columns by content, 'fixed' uses first row for sizing. |
| `loadingColor` | `'default' \| 'primary' \| 'success' \| 'warning' \| 'danger'` | `'default'` | Color variant for loading animation. |
| `onSelectionChange` | `(selectedKeys: Set<string>) => void` | - | Callback when selection changes |
| `onSort` | `(items: T[], sortDescriptor: SortItem<T>) => T[]` | - | Function to sort items when sorting is triggered. Receives the items array and sort descriptor. Returns sorted items. |
| `selectedKeys` | `any` | - | Set of selected item keys |
| `selectionColor` | `'default' \| 'primary' \| 'success' \| 'warning' \| 'danger'` | `'primary'` | Color variant for selection highlight. |
| `selectionMode` | `SelectionMode` | `'none'` | Selection mode - 'none' (default), 'single' (row clicks only), or 'multiple' (with checkboxes). |
| `showSelectAll` | `boolean` | `true` | Show "select all" checkbox in header (only for multiple selection mode). |
| `size` | `'sm' \| 'md' \| 'lg'` | `'md'` | Size variant for table cells and headers. |
| `skeletonRows` | `number` | - | Number of placeholder rows to render while loading with no items. Omit or 0 for no skeleton. |
| `stickyKeys` | `string[]` | - | Array of item keys that should be sticky during vertical scrolling |

**Blocks**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `default *` | `never` | - |  |
| `toolbar *` | `[{ ColumnVisibility: ColumnVisibility<T> (tableInstance bound); }]` | - |  |
| `cell *` | `[{ column: Column<T>; value: ContentValue; row: Row<T>; For: CellFor<T, TColumns> (column, registry bound); Default: CellDefault<T> (column, registry bound); }]` | - |  |
| `empty *` | `[]` | - |  |
| `header *` | `[{ column: Column<T>; isSortable: boolean; sortDirection: string; isSorted: boolean; onSort: () => void; }]` | - |  |
| `loading *` | `[{ columns: Column<T>[]; }]` | - |  |
| `bodyTop *` | `[{ columns: Column<T>[]; Row: SimpleTableRow (styleFns, classes bound); Cell: SimpleTableCell (styleFns, classes bound); }]` | - |  |
| `bodyBottom *` | `[{ columns: Column<T>[]; Row: SimpleTableRow (styleFns, classes bound); Cell: SimpleTableCell (styleFns, classes bound); }]` | - |  |

### ColumnConfig

```ts
interface ColumnConfig<T = unknown> {
  key: string;
  name: string;
  value?: (ctx: CellContext<T>) => ContentValue;
  isSticky?: boolean;
  stickyPosition?: 'left' | 'right';
  isVisible?: boolean;
  isSortable?: boolean;
  sortProperty?: string;
  Cell?: ComponentLike<CellSignature<T>>;
}
```

### CellSignature

```ts
interface CellSignature<T> {
  Args: {
    row: { data: T };
    column: ColumnConfig<T>;
    value?: ContentValue;
  };
}
```

---

# Calendar

Source: /docs/components/collections/calendar.md

# Calendar

A month-grid date picker for choosing a single day or a range, with full keyboard
navigation and localization through `Intl`. Calendar renders no popover, trigger, or text
input of its own—you can compose it with an input and popover to build a date picker.

## Import

```js
import { Calendar } from 'frontile/collections';
```

## Usage

```gts preview
import { Calendar } from 'frontile/collections';

const today = new Date();

<template><Calendar @defaultValue={{today}} /></template>
```

The first visible month is resolved in this order: `@defaultMonth`, then the month of
`@defaultValue`, then the month of `@value`, then today. A calendar seeded with a selection
opens showing that selection rather than today.

## Anatomy

Calendar provides four optional named blocks for replacing or extending its rendered parts:

| Block        | Purpose                                                               |
| ------------ | --------------------------------------------------------------------- |
| `<:header>`  | Replaces the month caption and previous/next controls.                |
| `<:weekday>` | Replaces each localized weekday label.                                |
| `<:day>`     | Replaces the contents of each day button.                             |
| `<:footer>`  | Adds content below the month grid, such as presets or selection help. |

The default rendering is available when a block is omitted. See [Custom rendering](#custom-rendering)
for the values yielded to each block.

## Controlled

Pass `@value` and `@onChange` to own the selection yourself. Passing `@value` at all —
including as `undefined` — puts selection in controlled mode; omit it entirely for
uncontrolled use as in the demo above.

```gts preview
import { Calendar } from 'frontile/collections';
import Component from '@glimmer/component';
import { tracked } from '@glimmer/tracking';

export default class ControlledExample extends Component {
  @tracked value: Date | null = new Date();

  get label(): string {
    return this.value
      ? `Selected: ${this.value.toDateString()}`
      : 'No date selected';
  }

  handleChange = (value: Date | null): void => {
    this.value = value;
  };

  <template>
    <p class='mb-2 text-body-sm text-neutral'>{{this.label}}</p>
    <Calendar @value={{this.value}} @onChange={{this.handleChange}} />
  </template>
}
```

## Range

Set `@mode="range"` to select a start and end day; the first click sets the anchor and the
second commits the range. `@visibleMonths={{2}}` shows two months side by side, which is
the usual pairing for a range picker.

```gts preview
import { Calendar } from 'frontile/collections';

<template><Calendar @mode='range' @visibleMonths={{2}} /></template>
```

A controlled range `@value` whose `end` is `null` is a half-open, mid-interaction state —
Calendar won't paint a range from it. Pass a full `{ start, end }` object once both ends
are chosen.

`@showOutsideDays` defaults to `true` with one visible month and `false` once
`@visibleMonths` is greater than one, where a boundary date would otherwise appear in both
grids. Passing an explicit value always wins, in either direction.

`@pageBehavior` controls how far the previous/next buttons move: `'visible'` (the default)
pages by the whole window, `'single'` always by one month. `@fixedWeeks` renders six week
rows in every month, so the calendar's height doesn't change as you page.

## Min and max

`@minValue` and `@maxValue` bound which days are selectable. Navigation is bounded too: the
previous/next buttons disable once paging would land entirely outside the bounds, and the
month and year pickers offer only the months and years the bounds allow.
`@isDateUnavailable` does not affect navigation — you can still page to a month whose every
day is unavailable.

```gts preview
import { Calendar } from 'frontile/collections';

const septemberFirst = new Date(2026, 8, 1);
const minValue = new Date(2026, 8, 5);
const maxValue = new Date(2026, 8, 20);

<template>
  <Calendar
    @defaultMonth={{septemberFirst}}
    @minValue={{minValue}}
    @maxValue={{maxValue}}
  />
</template>
```

## Unavailable dates

`@isDateUnavailable` marks specific days as present but not selectable — a holiday, a
booked night — shown struck through rather than dimmed. It's distinct from `@minValue`/
`@maxValue`: an unavailable day is still in range, just not choosable.

```gts preview
import { Calendar } from 'frontile/collections';

function isWeekend(date: Date): boolean {
  const day = date.getDay();
  return day === 0 || day === 6;
}

<template><Calendar @isDateUnavailable={{isWeekend}} /></template>
```

In range mode, an unavailable date also blocks any range from being drawn across it — once
one endpoint is chosen, days on the far side of an unavailable day become unreachable.

Three kinds of day look muted, and they don't all behave the same way:

| Day                               | Looks          | Selectable                                          |
| --------------------------------- | -------------- | --------------------------------------------------- |
| Outside `@minValue`/`@maxValue`   | Dimmed         | No                                                  |
| Matched by `@isDateUnavailable`   | Struck through | No                                                  |
| Belonging to a neighbouring month | Dimmed         | Yes — selecting it pages the calendar to that month |

## Month and year dropdowns

`@captionLayout="dropdown"` replaces the plain month/year caption with a native month
`<select>` and a year trigger that opens a year-grid picker.

```gts preview
import { Calendar } from 'frontile/collections';

<template><Calendar @captionLayout='dropdown' /></template>
```

## Colors and sizes

`@color` sets the color of the selected day and the range band; `@size` scales the cells
and caption together.

```gts preview
import { Calendar } from 'frontile/collections';
import { array } from '@ember/helper';

const today = new Date();

<template>
  <div class='flex flex-wrap gap-6'>
    {{#each (array 'primary' 'success' 'danger') as |intent|}}
      <Calendar @color={{intent}} @size='sm' @defaultValue={{today}} />
    {{/each}}
  </div>
</template>
```

```gts preview
import { Calendar } from 'frontile/collections';
import { array } from '@ember/helper';

const today = new Date();

<template>
  <div class='flex flex-wrap items-start gap-6'>
    {{#each (array 'sm' 'md' 'lg') as |size|}}
      <Calendar @size={{size}} @defaultValue={{today}} />
    {{/each}}
  </div>
</template>
```

## Custom weekday labels

The `<:weekday>` block replaces the column headers, receiving `short`, `long`, `narrow`, and
the weekday `index`. Pairing the narrow label with a [Tooltip](../overlays/tooltip.md)
carrying the long one keeps the columns tight without losing the full weekday name.

```gts preview
import { Calendar } from 'frontile/collections';
import { Tooltip } from 'frontile';

<template>
  <Calendar>
    <:weekday as |weekday|>
      <Tooltip @content={{weekday.long}} as |t|>
        <span {{t.trigger}}>{{weekday.narrow}}</span>
      </Tooltip>
    </:weekday>
  </Calendar>
</template>
```

## Presets

The `<:footer>` block renders below the grid. Combine it with `@month`/`@onMonthChange` and
`@value`/`@onChange` to drive the calendar from preset buttons.

```gts preview collapsible
import { Calendar } from 'frontile/collections';
import { Button } from 'frontile';
import Component from '@glimmer/component';
import { tracked } from '@glimmer/tracking';
import { fn } from '@ember/helper';
import { on } from '@ember/modifier';

function addDays(date: Date, amount: number): Date {
  const result = new Date(date);
  result.setDate(result.getDate() + amount);
  result.setHours(0, 0, 0, 0);
  return result;
}

export default class PresetsExample extends Component {
  @tracked month = addDays(new Date(), 0);
  @tracked value: Date | null = null;

  applyPreset = (offset: number): void => {
    const date = addDays(new Date(), offset);
    this.month = date;
    this.value = date;
  };

  handleMonthChange = (month: Date): void => {
    this.month = month;
  };

  handleChange = (value: Date | null): void => {
    this.value = value;
  };

  <template>
    <Calendar
      @month={{this.month}}
      @onMonthChange={{this.handleMonthChange}}
      @value={{this.value}}
      @onChange={{this.handleChange}}
    >
      <:footer>
        <div class='flex gap-2 pt-2'>
          <Button
            @size='sm'
            @variant='outline'
            {{on 'click' (fn this.applyPreset 0)}}
          >
            Today
          </Button>
          <Button
            @size='sm'
            @variant='outline'
            {{on 'click' (fn this.applyPreset 1)}}
          >
            Tomorrow
          </Button>
          <Button
            @size='sm'
            @variant='outline'
            {{on 'click' (fn this.applyPreset 7)}}
          >
            In a week
          </Button>
        </div>
      </:footer>
    </Calendar>
  </template>
}
```

## Custom day content

The `<:day>` block replaces a day cell's content, receiving the day's state (selection,
availability, focus, and more). It renders inside the cell's content wrapper, so a numeral
plus a second line stacks and centres without you rebuilding that layout.

Two CSS variables size the cell around it. `--calendar-cell-radius` shapes it — a day is a
circle by default, which crops anything wider than a numeral, so content like a price wants
a smaller radius. `--calendar-cell-size` scales the whole grid, and content with a second
line needs the extra room.

Let custom content **inherit its color** rather than setting a fixed one. A selected day
swaps its text to the contrast color for the current `@color`, and anything inside it
inherits that automatically — so `opacity-70` gives you a muted second line that stays
readable on both the resting surface and the selected fill. A fixed color like
`text-neutral` looks right until the day is selected, then sits grey on a saturated
background.

```gts preview
import { Calendar } from 'frontile/collections';
import { get } from '@ember/helper';

const prices: Record<number, number> = {
  5: 120,
  6: 120,
  12: 95,
  13: 95,
  19: 140,
  20: 140
};
const septemberFirst = new Date(2026, 8, 1);

<template>
  <Calendar
    @defaultMonth={{septemberFirst}}
    style='--calendar-cell-radius: var(--radius-lg); --calendar-cell-size: 3.5rem'
  >
    <:day as |day|>
      <span class='text-body-sm'>{{day.dayOfMonth}}</span>
      {{#if (get prices day.dayOfMonth)}}
        <span class='text-caption-sm opacity-70'>
          ${{get prices day.dayOfMonth}}
        </span>
      {{/if}}
    </:day>
  </Calendar>
</template>
```

## Custom header

The `<:header>` block replaces the month caption and navigation entirely. It receives
`month`, `title`, `goToPrevious`, `goToNext`, `canGoPrevious`, `canGoNext`, `setMonth`,
`setYear`, `isYearGridOpen`, and `toggleYearGrid` — the same context the default header
uses, so nothing about paging or bounds has to be reimplemented.

Nothing is rendered for you, including the year-grid trigger: call `toggleYearGrid` from
your own control to keep it, as below, or leave it out for a calendar with no year picker.

```gts preview collapsible
import { Calendar } from 'frontile/collections';
import { Button } from 'frontile';
import { on } from '@ember/modifier';

<template>
  <Calendar>
    <:header as |header|>
      <div class='flex items-center justify-between gap-2 pb-2'>
        <Button
          @size='sm'
          @variant='outline'
          disabled={{unless header.canGoPrevious true false}}
          {{on 'click' header.goToPrevious}}
        >
          Back
        </Button>

        <Button
          @size='sm'
          @variant='plain'
          aria-expanded={{if header.isYearGridOpen 'true' 'false'}}
          {{on 'click' header.toggleYearGrid}}
        >
          {{header.title}}
        </Button>

        <Button
          @size='sm'
          @variant='outline'
          disabled={{unless header.canGoNext true false}}
          {{on 'click' header.goToNext}}
        >
          Next
        </Button>
      </div>
    </:header>
  </Calendar>
</template>
```

## Localization

`@locale` is a BCP-47 language tag (`"nl-NL"`, `"ja-JP"`) — Calendar formats months,
weekdays, and captions through `Intl.DateTimeFormat`, not a date-fns `Locale` object.
`@weekStartsOn` overrides the first day of the week the locale would otherwise imply.

```gts preview
import { Calendar } from 'frontile/collections';

<template><Calendar @locale='nl-NL' @weekStartsOn={{1}} /></template>
```

## Disabled and read-only

`@isDisabled` blocks navigation and selection entirely. `@isReadOnly` still allows paging
between months but blocks selecting a day.

```gts preview
import { Calendar } from 'frontile/collections';

const today = new Date();

<template>
  <div class='flex flex-wrap gap-6'>
    <Calendar @isDisabled={{true}} @visibleMonths={{1}} />
    <Calendar @isReadOnly={{true}} @defaultValue={{today}} />
  </div>
</template>
```

## Accessibility

The day grid is a single tab stop: `Tab` moves focus onto the currently focused day, and
arrow keys move within the grid without adding extra stops. Moving past the edge of a
visible month pages the calendar to bring the new day into view.

| Key                                     | Action                                      |
| --------------------------------------- | ------------------------------------------- |
| `←` / `→`                               | Move focus one day back / forward           |
| `↑` / `↓`                               | Move focus one week back / forward          |
| `Home` / `End`                          | Move to the start / end of the current week |
| `Page Up` / `Page Down`                 | Move back / forward one month               |
| `Shift + Page Up` / `Shift + Page Down` | Move back / forward one year                |
| `Enter` / `Space`                       | Select the focused day                      |
| `Escape`                                | Cancel a pending range selection            |

`Escape` works no matter which control inside the calendar has focus — a day cell, the
Previous/Next buttons, or the month `<select>` — so a pending range can always be
canceled without first tabbing back into the grid.

In range mode the first click emits a half-open `{ start, end: null }`, and `Escape` emits
`null` to retract it — so a controlled `@value` is cleared rather than left holding a start
date.

Each month grid has `role="grid"` with an accessible label naming the month and year, and
day cells use `role="gridcell"` with `aria-selected`. Each day button also carries a full
`aria-label` (weekday, month, day, and year) built from `Intl.DateTimeFormat`, so crossing
a month boundary with the arrow keys announces the complete new date rather than a bare
day-of-month number. The month caption is also announced through a visually hidden live
region when navigation changes it, so month changes reach screen reader users even though
focus stays on the grid. `@autofocus` moves DOM focus into the grid on insert and
only then; rendering a calendar otherwise never moves focus. `@isReadOnly` marks each grid
`aria-readonly="true"` so assistive technology knows the days are inert.

## API

### Calendar

**Element:** `HTMLDivElement`

**Arguments**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `autofocus` | `boolean` | `false` | Moves DOM focus into the grid on insert. This is the only thing that may focus the calendar on mount -- rendering a calendar must never otherwise steal focus. |
| `captionLayout` | `'label' \| 'dropdown'` | `'label'` | 'label' renders the plain month/year caption; 'dropdown' swaps it for a native month <select> plus a year trigger that opens a year-grid picker. |
| `classes` | `SlotsToClasses<'base' \| 'title' \| 'cell' \| 'header' \| 'body' \| 'footer' \| 'indicator' \| 'nav' \| 'monthSelectWrapper' \| 'monthSelectValue' \| 'monthSelect' \| 'monthSelectIcon' \| 'yearTrigger' \| ... 10 more ... \| 'yearCell'>` | - | Overrides the classes applied to individual slots. |
| `color` | `'neutral' \| 'primary' \| 'secondary' \| 'tertiary' \| 'success' \| 'warning' \| 'danger'` | `'primary'` | The color used for the selected day and the range band. |
| `defaultMonth` | `Object` | - | Seeds the visible month when uncontrolled -- the first month of the window when @visibleMonths is greater than one. |
| `defaultValue` | `CalendarValue<M>` | - | Seeds the selection when uncontrolled. |
| `fixedWeeks` | `boolean` | `false` | Renders six week rows in every month, so the calendar keeps the same height as you page between months of different lengths. |
| `isDateUnavailable` | `(date: Date) => boolean` | - | Marks a date as present but unselectable -- a holiday, a booked night. Distinct from @minValue/@maxValue, which put a date out of range entirely. |
| `isDisabled` | `boolean` | `false` | Blocks navigation and selection entirely. |
| `isReadOnly` | `boolean` | `false` | Allows paging between months but blocks selecting a day. Unlike @isDisabled, the days stay focusable so the calendar can still be read with the keyboard. |
| `labelledBy` | `string` | - | The id of an element naming this calendar, forwarded to each month grid's aria-labelledby. Use it when something outside the calendar already names it -- a date picker's own label, say -- so the grid is announced with that name instead of its month caption. An aria-labelledby passed through ...attributes lands on the root element, which has no role, so it would not reach the grid. |
| `locale` | `string` | - | BCP-47 tag. All human-readable text is produced by Intl from this. |
| `maxValue` | `Object` | - | Latest selectable date. Also clamps month navigation. |
| `minValue` | `Object` | - | Earliest selectable date. Also clamps month navigation. |
| `mode` | `M` | `'single'` | Whether a click selects one day or the two ends of a range. |
| `month` | `Object` | - | Controlled visible month -- the first month of the window when @visibleMonths is greater than one. Passing this argument at all puts the month axis in controlled mode -- passing it as undefined included. Omit it entirely to let Calendar track the visible month itself. |
| `onChange` | `(value: CalendarValue<M>) => void` | - | Called with the new selection when the user picks or clears a day. |
| `onMonthChange` | `(month: Date) => void` | - | Called with the month the user asked to move to. |
| `pageBehavior` | `'single' \| 'visible'` | `'visible'` | How far prev/next paging advances. 'visible' moves by the whole window (@visibleMonths); 'single' always moves by one month. |
| `showOutsideDays` | `boolean` | ``true` when a single month is visible, `false` once `@visibleMonths` is greater than one -- otherwise a boundary date would render twice, once per adjacent grid.` | Whether days from the adjacent month fill out a grid's leading/trailing weeks. |
| `size` | `'sm' \| 'md' \| 'lg'` | `'md'` | The size of the calendar cells and caption text. |
| `value` | `CalendarValue<M>` | - | Controlled selection. Passing this argument at all puts selection in controlled mode -- passing it as undefined included. |
| `visibleMonths` | `number` | `1` | How many months to render side by side, starting from the visible month. |
| `weekStartsOn` | `WeekDay` | - | Overrides the first day of week implied by @locale. |

**Blocks**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `day *` | `[DayState]` | - |  |
| `header *` | `[CalendarHeaderContext]` | - |  |
| `weekday *` | `[WeekdayLabel]` | - |  |
| `footer *` | `[]` | - |  |

---

# Autocomplete

Source: /docs/components/forms/autocomplete.md

# Autocomplete

The `Autocomplete` component combines a text input with a listbox popover, letting users filter a list of options by typing. It follows the [WAI-ARIA combobox pattern](https://www.w3.org/WAI/ARIA/apg/patterns/combobox/) and supports static lists, custom filtering, and options loaded asynchronously from an API. Like [Select](https://frontile.dev/docs/components/forms/select), it is built on top of the [Listbox](https://frontile.dev/docs/components/collections/listbox) and [Popover](https://frontile.dev/docs/components/overlays/popover) components and renders a hidden native `<select>` for form submission.

Use `Autocomplete` when the list is long enough that typing beats scrolling — assigning a country, a time zone, a teammate. Use `Select` when scanning a short list is faster than typing, or when you need multiple selection (`Select` supports `@selectionMode="multiple"` together with `@isFilterable`); `Autocomplete` is single-selection only.

## Import

```js
import { Autocomplete } from 'frontile';
```

## Usage

### Basic Autocomplete

Type into the input to filter the options. The default filter ranks by relevance, so the closest
match is listed first — and it matches acronyms (`nz` finds "New Zealand") as well as substrings.
Pass `@filter` to score or match options yourself.

```gts preview
import { Autocomplete } from 'frontile';

const countries = [
  'Argentina',
  'Australia',
  'Brazil',
  'Canada',
  'Denmark',
  'France',
  'Germany',
  'Japan',
  'Mexico',
  'Netherlands',
  'New Zealand',
  'Portugal',
  'South Korea',
  'Spain',
  'United Kingdom',
  'United States'
];

<template>
  <div class='demo-stack'>
    <Autocomplete @placeholder='Search countries' @items={{countries}} />
  </div>
</template>
```

### Selection

Pass `@selectedKey` and update it in `@onSelectionChange` to maintain two-way binding, the same data flow as `Select`.

```gts preview collapsible
import Component from '@glimmer/component';
import { tracked } from '@glimmer/tracking';
import { Autocomplete } from 'frontile';

const languages = [
  'Elixir',
  'Go',
  'JavaScript',
  'Python',
  'Ruby',
  'Rust',
  'TypeScript'
];

export default class LanguagePicker extends Component {
  @tracked selectedKey: string | null = null;

  onSelectionChange = (key: string | null) => {
    this.selectedKey = key;
  };

  <template>
    <div class='demo-stack'>
      <Autocomplete
        @label='Primary language'
        @placeholder='Search languages'
        @items={{languages}}
        @selectedKey={{this.selectedKey}}
        @onSelectionChange={{this.onSelectionChange}}
      />
      <p class='mt-4'>Selected: {{if this.selectedKey this.selectedKey 'none'}}</p>
    </div>
  </template>
}
```

### Async search with an API

Pass `@onSearch` to load options from an API as the user types. The component debounces calls (250ms by default, tune with `@searchDebounce`), shows a loading spinner while the returned promise is pending, and ignores stale responses so the latest query always wins. Clearing the input restores `@items` without triggering a search.

This example simulates a request with network latency:

```gts preview collapsible
import Component from '@glimmer/component';
import { tracked } from '@glimmer/tracking';
import { Autocomplete } from 'frontile';

interface City {
  key: string;
  label: string;
}

const cities: City[] = [
  { key: 'amsterdam', label: 'Amsterdam' },
  { key: 'barcelona', label: 'Barcelona' },
  { key: 'berlin', label: 'Berlin' },
  { key: 'buenos-aires', label: 'Buenos Aires' },
  { key: 'lisbon', label: 'Lisbon' },
  { key: 'london', label: 'London' },
  { key: 'melbourne', label: 'Melbourne' },
  { key: 'mexico-city', label: 'Mexico City' },
  { key: 'new-york', label: 'New York' },
  { key: 'sao-paulo', label: 'São Paulo' },
  { key: 'seoul', label: 'Seoul' },
  { key: 'tokyo', label: 'Tokyo' }
];

// Stand-in for a real API call, e.g. fetch(`/api/cities?q=${query}`)
const searchCities = (query: string): Promise<City[]> => {
  return new Promise((resolve) => {
    setTimeout(() => {
      resolve(
        cities.filter((city) =>
          city.label.toLowerCase().includes(query.toLowerCase())
        )
      );
    }, 600);
  });
};

export default class CitySearch extends Component {
  @tracked selectedKey: string | null = null;

  onSelectionChange = (key: string | null) => {
    this.selectedKey = key;
  };

  <template>
    <div class='demo-stack'>
      <Autocomplete
        @label='Destination'
        @placeholder='Search cities'
        @searchMessage='Type to search for a city...'
        @onSearch={{searchCities}}
        @selectedKey={{this.selectedKey}}
        @onSelectionChange={{this.onSelectionChange}}
      >
        <:emptyContent>No cities match your search.</:emptyContent>
      </Autocomplete>
    </div>
  </template>
}
```

Pass `@searchMessage` (or a `:searchMessage` block for rich content) to prompt users who open the dropdown before typing — it shows while the query is blank and there are no options to display, as in the example above. Without it, an opened async autocomplete with no default `@items` shows the empty content instead.

### External filtering

If you want full control over filtering — for example, filtering server-side while controlling the request lifecycle yourself — pass `@disableFiltering={{true}}` and update `@items` from `@onInputChange`:

```gts preview collapsible
import Component from '@glimmer/component';
import { tracked } from '@glimmer/tracking';
import { Autocomplete } from 'frontile';

const allTimezones = [
  'America/Chicago',
  'America/Denver',
  'America/Los_Angeles',
  'America/New_York',
  'Asia/Seoul',
  'Asia/Tokyo',
  'Australia/Sydney',
  'Europe/Berlin',
  'Europe/Lisbon',
  'Europe/London'
];

export default class TimezonePicker extends Component {
  @tracked items = allTimezones;

  onInputChange = (value: string) => {
    // Replace with your own request/filter logic
    this.items = allTimezones.filter((tz) =>
      tz.toLowerCase().includes(value.toLowerCase())
    );
  };

  <template>
    <div class='demo-stack'>
      <Autocomplete
        @label='Time zone'
        @placeholder='Search time zones'
        @items={{this.items}}
        @disableFiltering={{true}}
        @onInputChange={{this.onInputChange}}
      />
    </div>
  </template>
}
```

### Custom filter

Pass `@filter` to change how items match the typed text — here, matching only from the start of the word:

```gts preview
import { Autocomplete } from 'frontile';

const fruits = ['Apple', 'Apricot', 'Banana', 'Cherry', 'Grape', 'Pineapple'];

const startsWith = (itemValue: string, inputValue: string) =>
  itemValue.toLowerCase().startsWith(inputValue.toLowerCase());

<template>
  <div class='demo-stack'>
    <Autocomplete
      @placeholder="Try typing 'ap'"
      @items={{fruits}}
      @filter={{startsWith}}
    />
  </div>
</template>
```

### Custom items

Use the `:item` block to render richer options. Objects with `key` and `label` properties work out of the box.

```gts preview collapsible
import Component from '@glimmer/component';
import { tracked } from '@glimmer/tracking';
import { Autocomplete } from 'frontile';

const teammates = [
  { key: 'ana', label: 'Ana Souza', role: 'Design' },
  { key: 'devon', label: 'Devon Lane', role: 'Engineering' },
  { key: 'kim', label: 'Kim Park', role: 'Product' },
  { key: 'marta', label: 'Marta Silva', role: 'Engineering' },
  { key: 'ravi', label: 'Ravi Patel', role: 'Support' }
];

export default class AssigneePicker extends Component {
  @tracked selectedKey: string | null = null;

  onSelectionChange = (key: string | null) => {
    this.selectedKey = key;
  };

  <template>
    <div class='demo-stack'>
      <Autocomplete
        @label='Assignee'
        @placeholder='Search teammates'
        @items={{teammates}}
        @selectedKey={{this.selectedKey}}
        @onSelectionChange={{this.onSelectionChange}}
      >
        <:item as |l|>
          <l.Item @key={{l.key}} @description={{l.item.role}}>
            {{l.label}}
          </l.Item>
        </:item>
      </Autocomplete>
    </div>
  </template>
}
```

### Custom values

By default the input reverts to the selected option's label when the dropdown closes. Pass `@allowsCustomValue={{true}}` to keep whatever the user typed — useful when suggestions are helpful but not required. Read the final text via `@onInputChange`.

```gts preview
import Component from '@glimmer/component';
import { tracked } from '@glimmer/tracking';
import { Autocomplete } from 'frontile';

const commonRoles = ['Admin', 'Editor', 'Viewer'];

export default class RoleInput extends Component {
  @tracked value = '';

  onInputChange = (value: string) => {
    this.value = value;
  };

  <template>
    <div class='demo-stack'>
      <Autocomplete
        @label='Role'
        @description='Pick a suggestion or type your own'
        @items={{commonRoles}}
        @allowsCustomValue={{true}}
        @onInputChange={{this.onInputChange}}
      />
      <p class='mt-4'>Value: {{this.value}}</p>
    </div>
  </template>
}
```

### Clear button

Pass `@isClearable={{true}}` to show a button that clears both the selection and the typed text.

Like `Select`, this overrides `@allowEmpty` — that argument governs deselecting an
option in the listbox, while the clear button is the affordance for emptying the field. No clear button renders on a disabled Autocomplete.

```gts preview
import Component from '@glimmer/component';
import { tracked } from '@glimmer/tracking';
import { Autocomplete } from 'frontile';

const browsers = ['Chrome', 'Edge', 'Firefox', 'Safari'];

export default class BrowserPicker extends Component {
  @tracked selectedKey: string | null = 'Firefox';

  onSelectionChange = (key: string | null) => {
    this.selectedKey = key;
  };

  <template>
    <div class='demo-stack'>
      <Autocomplete
        @label='Browser'
        @items={{browsers}}
        @isClearable={{true}}
        @selectedKey={{this.selectedKey}}
        @onSelectionChange={{this.onSelectionChange}}
      />
    </div>
  </template>
}
```

### Sizes and validation

`Autocomplete` accepts the same form control arguments as other Frontile inputs: `@label`, `@description`, `@errors`, `@isInvalid`, `@isRequired`, and `@inputSize`.

`@onBlur` (and so `blur` in a Field's `@validateOn`) fires only once focus has left the
whole control — the input and its dropdown. Picking an option moves focus into the
dropdown, so a selection is never reported as a blur.

```gts preview
import { Autocomplete } from 'frontile';
import { array } from '@ember/helper';

const plans = ['Free', 'Pro', 'Enterprise'];

<template>
  <div class='demo-stack'>
    <Autocomplete @inputSize='sm' @placeholder='Small' @items={{plans}} />
    <Autocomplete @inputSize='md' @placeholder='Medium' @items={{plans}} />
    <Autocomplete @inputSize='lg' @placeholder='Large' @items={{plans}} />
    <Autocomplete
      @label='Plan'
      @isRequired={{true}}
      @isInvalid={{true}}
      @errors={{array 'Choose a plan to continue'}}
      @items={{plans}}
    />
  </div>
</template>
```

## Keyboard interaction

| Key | Action |
| --- | --- |
| Type characters | Opens the dropdown and filters the options |
| <kbd>ArrowDown</kbd> / <kbd>ArrowUp</kbd> | Opens the dropdown / moves the highlight |
| <kbd>Enter</kbd> | Selects the highlighted option |
| <kbd>Escape</kbd> | Closes the dropdown |
| <kbd>Home</kbd> / <kbd>End</kbd> | Moves the highlight to the first / last option |

## Accessibility

The input uses `role="combobox"` with `aria-autocomplete="list"`, `aria-expanded`, and `aria-controls` pointing at the popover. Focus stays on the input while <kbd>ArrowUp</kbd>/<kbd>ArrowDown</kbd> move a virtual highlight communicated through `aria-activedescendant`. A visually hidden native `<select>` mirrors the options for form submission via `@name`.

## API

### Autocomplete

Autocomplete Component - a text input combined with a listbox popover,
following the WAI-ARIA 1.2 combobox pattern.

Users filter the options by typing (type-ahead). Options can come from a
static list (built-in filtering), an externally filtered list
(disableFiltering + onInputChange), or an async source (onSearch).

**Element:** `HTMLDivElement`

**Arguments**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `allowEmpty` | `boolean` | - |  |
| `allowsCustomValue` | `boolean` | `false` | When true, the text typed by the user is kept on blur/close even if it does not match any option. By default the input reverts to the selected item's label (or empty) when the dropdown closes without a selection. |
| `appearance` | `'default' \| 'outlined' \| 'faded'` | - | **Deprecated.** Use `variant`. `default` is now `solid`, `outlined` is `outline`, and `faded` is `subtle`. |
| `backdrop` | `'faded' \| 'none' \| 'transparent' \| 'blur'` | - | How the area behind the overlay is rendered: none omits the backdrop entirely, transparent keeps it clickable but invisible, faded dims the page, and blur blurs it. |
| `backdropTransition` | `Object` | - | Transition classes for the backdrop, overriding the defaults used when it fades in and out. |
| `blockScroll` | `boolean` | `true` | Whether scrolling should be blocked when the dropdown is open. |
| `classes` | `SlotsToClasses<'icon' \| 'base' \| 'innerContainer' \| 'startContent' \| 'endContent' \| 'input' \| 'listbox' \| 'clearButton' \| 'emptyContent'>` | - | Custom classes to style different slots within the autocomplete component. |
| `closeOnEscapeKey` | `boolean` | `true` | Whether to close when the escape key is pressed |
| `closeOnItemSelect` | `boolean` | `true` | Whether the autocomplete should close upon selecting an item. |
| `closeOnOutsideClick` | `boolean` | `true` | Whether to close when the area outside (the backdrop) is clicked |
| `color` | `'neutral' \| 'primary' \| 'secondary' \| 'tertiary' \| 'success' \| 'warning' \| 'danger'` | - | The color of each item |
| `description` | `string` | - | Help text rendered between the label and the control, and referenced by the ids describedBy returns. |
| `didClose` | `() => void` | - | Callback when closing has finished, including any exit transition. |
| `disabledKeys` | `string[]` | - |  |
| `disableFiltering` | `boolean` | `false` | Disables the built-in filtering, rendering @items as-is. Use together with inputValue/onInputChange when filtering happens outside of the component (e.g. server-side). |
| `disableFocusTrap` | `boolean` | `true` | Whether the focus trap should be disabled when the dropdown is open. |
| `disableTransitions` | `boolean` | `false` | Disable css transitions |
| `endContentPointerEvents` | `'none' \| 'auto'` | `'none'` | Controls pointer-events property of endContent. Defaults to none to pass click events to the input. If your content needs to capture events, add the pointer-events-auto class to that element. |
| `errors` | `string \| string[]` | - | Validation messages for the field. A non-empty value also marks the control invalid, and an array is joined with ;  when displayed. |
| `filter` | `FilterFn` | - | Function to filter the items against the current input text. The default implementation ranks by relevance, so the closest match is listed first rather than whichever match came first in @items. |
| `flipOptions` | `{ mainAxis?: boolean; crossAxis?: boolean \| 'alignment'; fallbackPlacements?: Placement[]; fallbackStrategy?: 'bestFit' \| 'initialPlacement'; fallbackAxisSideDirection?: 'start' \| ... 1 more ... \| 'none'; ... 5 more ...; boundary?: Boundary; }` | - | Options for the floating-ui flip middleware, which moves the content to the opposite side when it would overflow the viewport. |
| `focusTrapOptions` | `any` | `{ clickOutsideDeactivates: true, allowOutsideClick: true }` | Focus trap options |
| `hideEmptyContent` | `boolean` | `false` | If true, hides the empty content when there are no options available. |
| `id` | `string` | - | The unique identifier for the autocomplete component. |
| `inputSize` | `'sm' \| 'md' \| 'lg'` | - | Defines the input size of the autocomplete. |
| `inputValue` | `string` | - | The text value of the input. Pass this together with onInputChange to control the input text externally, for example to implement server-side filtering. |
| `intent` | `'default' \| 'primary' \| 'secondary' \| 'tertiary' \| 'success' \| 'warning' \| 'danger'` | - | **Deprecated.** Use `color`. `default` is now `neutral`. |
| `isClearable` | `boolean` | `false` | Whether to include a clear button in the autocomplete component. If enabled, this allows users to clear the selection and input text. This option deliberately overrides allowEmpty: that argument governs deselecting an option in the listbox, while this is a separate affordance you opt into for exactly the purpose of emptying the field. Since allowEmpty defaults to false, honouring it here would render the button dead by default. No clear button is rendered on a disabled Autocomplete. |
| `isDisabled` | `boolean` | - | Whether the autocomplete should be disabled, preventing user interaction. |
| `isInvalid` | `boolean` | `false` | Marks the control invalid without supplying messages, for validation that is reported elsewhere. |
| `isLoading` | `boolean` | - | If true, the autocomplete will show a loading spinner instead of the dropdown icon. The spinner is also shown automatically while an onSearch promise is pending. |
| `isRequired` | `boolean` | `false` | Whether the field is required. Adds an asterisk to the label; it does not set the required attribute on the control itself. |
| `items` | `T[]` | - |  |
| `label` | `string` | - | The label text rendered above the control and associated with it via for. Use the :label block instead when the label needs markup. |
| `middleware` | `{ name: string; options?: any; fn: (state: { placement: Placement; strategy: Strategy; x: number; y: number; initialPlacement: Placement; middlewareData: MiddlewareData; rects: ElementRects; platform: { ...; } &#x26; Platform; elements: Elements; }) => Promisable<...>; }[]` | - | Additional floating-ui middleware, for positioning behavior beyond what placement, offsetOptions, flipOptions, and shiftOptions cover. |
| `name` | `string` | - | The name attribute for the autocomplete component, useful for form submissions. |
| `offsetOptions` | `OffsetOptions` | `5` |  |
| `onAction` | `(key: string) => void` | - |  |
| `onBlur` | `() => void` | - | Callback fired when focus leaves the Autocomplete. "Leaves the Autocomplete" means the whole control: the input and its dropdown, which is rendered outside the input in the DOM. Moving focus between them -- which is what clicking an option does -- is not a blur, so this does not fire while the user is picking an option. It fires once, when focus lands somewhere outside the control (or nowhere, with the dropdown closed). This is what Field drives blur validation from. |
| `onInputChange` | `(value: string) => void` | - | Callback fired whenever the user changes the input text. |
| `onSearch` | `(query: string) => T[] \| Promise<T[]>` | - | Async search function. When provided, the component calls it (debounced) as the user types and renders the resolved items, showing a loading spinner while the returned promise is pending. Stale responses are ignored (latest query wins). Built-in filtering is disabled; @items is used as the initial list before the first search. |
| `onSelectionChange` | `(key: string) => void` | - | Callback fired when the selection changes. Update your @selectedKey state in this callback to maintain two-way binding. |
| `placeholder` | `string` | - | The placeholder text displayed when the input is empty. |
| `placement` | `'top' \| 'top-start' \| 'top-end' \| 'right' \| 'right-start' \| 'right-end' \| 'bottom' \| 'bottom-start' \| 'bottom-end' \| 'left' \| 'left-start' \| 'left-end'` | `'bottom-start'` | Placement of the menu when open |
| `popoverSize` | `'sm' \| 'md' \| 'lg' \| 'trigger'` | `'trigger'` | Defines the size of the popover dropdown. 'sm': Small 'md': Medium 'lg': Large 'trigger': Same size as the trigger |
| `renderInPlace` | `boolean` | `false` | Whether to render in place or in the specified/default destination |
| `searchDebounce` | `number` | `250` | Debounce duration, in milliseconds, applied to onSearch calls. |
| `searchMessage` | `string` | - | Message shown in the dropdown of an async autocomplete (onSearch) while the query is blank — e.g. "Type to search for an address…". Prompts the user to start typing when they open the dropdown by clicking. Also customizable via the searchMessage block. |
| `selectedKey` | `string` | - | The currently selected key. Autocomplete is single-selection only — for a searchable multi-select, use Select with @isFilterable and @selectionMode="multiple". Data Flow: Pass this to set the initial selection Update this in your onSelectionChange handler to maintain two-way binding The component calls onSelectionChange whenever the user changes the selection |
| `shiftOptions` | `{ mainAxis?: boolean; crossAxis?: boolean; rootBoundary?: RootBoundary; elementContext?: ElementContext; altBoundary?: boolean; padding?: Padding; limiter?: { ...; }; boundary?: Boundary; }` | - | Options for the floating-ui shift middleware, which nudges the content along its axis to keep it in view. |
| `startContentPointerEvents` | `'none' \| 'auto'` | `'auto'` | Controls pointer-events property of startContent. If you want to pass the click event to the input, set it to none. |
| `strategy` | `Strategy` | `'absolute'` |  |
| `target` | `string \| Element` | - | The target where to render the portal. There are 3 options: 1) Element object, 2) element id, 3) portal target name. For element id, string must be prefixed with #. If no value is passed in, we will render to the closest unnamed portal target, parent portal or document.body. |
| `transition` | `Object` | `{name: 'overlay-transition--scale'}` | The transition to be used in the Modal. |
| `transitionDuration` | `number` | `200` | Duration of the animation |
| `variant` | `'solid' \| 'subtle' \| 'outline'` | `'solid'` | The variant of each item. |

**Blocks**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `item *` | `[{ item: T; key: string; label: string; Item: ListboxItem (manager, item bound); }]` | - |  |
| `default *` | `[{ Item: ListboxItem (manager bound); Group: ListboxGroup (manager bound); }]` | - |  |
| `startContent *` | `[]` | - | Content to display at the beginning of the autocomplete component. This can be an icon, a label, or any custom UI element. |
| `endContent *` | `[]` | - | Content to display at the end of the autocomplete component. This can be an icon, a button, or any custom UI element. |
| `emptyContent *` | `[]` | - | The content to display when there are no matching options. If hideEmptyContent argument is true, this content will not be shown. |
| `searchMessage *` | `[]` | - | Message shown in the dropdown of an async autocomplete while the query is blank, prompting the user to start typing. Takes priority over the searchMessage argument. |

---

# Checkbox Group

Source: /docs/components/forms/checkbox-group.md

# Checkbox Group

A checkbox group component for selecting multiple options from a set of choices. Supports labels, validation, different orientations, and accessibility features.

## Import

```js
import { CheckboxGroup } from 'frontile';
```

## Usage

### Basic Checkbox Group

The most basic usage of the CheckboxGroup component with a label and options.

```gts preview
import { CheckboxGroup } from 'frontile';

<template>
  <div class='demo-stack'>
    <CheckboxGroup @label='Interests' as |Checkbox|>
      <Checkbox @label='Music' />
      <Checkbox @label='Sports' />
      <Checkbox @label='Technology' />
    </CheckboxGroup>
  </div>
</template>
```

### Controlled Checkbox Group

You can control individual checkbox states by providing `@checked` and handling updates with `@onChange`. This example uses an array-based data structure with a single reusable handler.

```gts preview collapsible
import Component from '@glimmer/component';
import { tracked } from '@glimmer/tracking';
import { fn } from '@ember/helper';
import { CheckboxGroup } from 'frontile';

export default class ControlledCheckboxGroup extends Component {
  @tracked formData = {
    interests: [] as string[]
  };

  // Helper to check if a value is selected
  isChecked = (value: string) => {
    return this.formData.interests?.includes(value) ?? false;
  }

  isChecked(value: string) {
    return this.formData.interests?.includes(value) ?? false;
  }

  // Single reusable handler for checkbox changes
  handleCheckboxChange = (value: string, checked: boolean) => {
    const current = this.formData.interests || [];

    if (checked) {
      this.formData = { ...this.formData, interests: [...current, value] };
    } else {
      this.formData = { ...this.formData, interests: current.filter((v) => v !== value) };
    }
  };

  get selectedCount() {
    return this.formData.interests?.length ?? 0;
  }

  get selectedItems() {
    return this.formData.interests?.join(', ') ?? '';
  }

  <template>
    <div class='demo-stack'>
      <CheckboxGroup @label='What are your interests?' as |Checkbox|>
        <Checkbox
          value='music'
          @label='Music'
          @checked={{this.isChecked 'music'}}
          @onChange={{fn this.handleCheckboxChange 'music'}}
        />
        <Checkbox
          value='sports'
          @label='Sports'
          @checked={{this.isChecked 'sports'}}
          @onChange={{fn this.handleCheckboxChange 'sports'}}
        />
        <Checkbox
          value='technology'
          @label='Technology'
          @checked={{this.isChecked 'technology'}}
          @onChange={{fn this.handleCheckboxChange 'technology'}}
        />
        <Checkbox
          value='art'
          @label='Art'
          @checked={{this.isChecked 'art'}}
          @onChange={{fn this.handleCheckboxChange 'art'}}
        />
      </CheckboxGroup>

      <div class='p-3 border border-neutral-soft rounded'>
        <p class='text-sm'>
          Selected ({{this.selectedCount}}):
          {{this.selectedItems}}
        </p>
      </div>

      <div class='p-4 bg-neutral-subtle rounded'>
        <h4 class='font-medium mb-2'>Current Selection:</h4>
        <pre class='text-sm overflow-auto'>{{JSON.stringify
            this.formData
            null
            2
          }}</pre>
      </div>
    </div>
  </template>
}
```

### Form Validation

The CheckboxGroup component integrates with form validation by displaying error messages and updating ARIA attributes accordingly.

**Note:** CheckboxGroup currently supports validation on form submit, but does not support automatic field-level validation (change/blur/input events) when used with `form.Field`. This differs from `RadioGroup`, which does support field-level validation. For CheckboxGroup, validation errors will only appear after the form is submitted.

This example demonstrates the recommended pattern for using CheckboxGroup with the Form component's validation system. It uses an array-based data structure with a single reusable handler for managing checkbox state.

```gts preview collapsible
import Component from '@glimmer/component';
import { tracked } from '@glimmer/tracking';
import { fn } from '@ember/helper';
import { Form, CheckboxGroup, type FormResultData } from 'frontile';
import { Button } from 'frontile';
import * as v from 'valibot';

// Define validation schema with array of strings
const schema = v.object({
  notificationMethods: v.pipe(
    v.array(v.string()),
    v.minLength(1, 'Please select at least one notification method')
  )
});

type Schema = v.InferOutput<typeof schema>;

export default class ValidatedCheckboxGroup extends Component {
  @tracked formData: Schema = {
    notificationMethods: []
  };
  @tracked submitMessage = '';

  // Helper to check if a value is selected
  isChecked = (value: string) => {
    return this.formData.notificationMethods?.includes(value) ?? false;
  };

  // Single reusable handler for checkbox changes
  handleCheckboxChange = (value: string, checked: boolean) => {
    const current = this.formData.notificationMethods || [];

    if (checked) {
      this.formData.notificationMethods = [...current, value];
    } else {
      this.formData.notificationMethods = current.filter((v) => v !== value);
    }
  };

  handleFormChange = (data: FormResultData<Schema>) => {
    this.formData = data.data;
  };

  handleFormSubmit = (data: FormResultData<Schema>) => {
    this.submitMessage = 'Preferences saved successfully!';
    console.log('Submitted data:', data.data);
  };

  <template>
    <div class='demo-stack'>
      <Form
        @data={{this.formData}}
        @schema={{schema}}
        @onChange={{this.handleFormChange}}
        @onSubmit={{this.handleFormSubmit}}
        as |form|
      >
        <form.Field @name='notificationMethods' as |field|>
          <field.CheckboxGroup
            @label='Notification Preferences'
            @description='Choose how you would like to receive notifications'
            @isRequired={{true}}
            as |Checkbox|
          >
            <Checkbox
              value='email'
              @label='Email notifications'
              @checked={{this.isChecked 'email'}}
              @onChange={{fn this.handleCheckboxChange 'email'}}
            />
            <Checkbox
              value='sms'
              @label='SMS notifications'
              @checked={{this.isChecked 'sms'}}
              @onChange={{fn this.handleCheckboxChange 'sms'}}
            />
            <Checkbox
              value='push'
              @label='Push notifications'
              @checked={{this.isChecked 'push'}}
              @onChange={{fn this.handleCheckboxChange 'push'}}
            />
          </field.CheckboxGroup>
        </form.Field>

        <div>
          <Button type='submit'>
            Save Preferences
          </Button>
        </div>
      </Form>

      {{#if this.submitMessage}}
        <div class='p-3 bg-success-subtle text-success-strong rounded'>
          {{this.submitMessage}}
        </div>
      {{/if}}

      <div class='p-4 bg-neutral-subtle rounded'>
        <h4 class='font-medium mb-2'>Form Data:</h4>
        <pre class='text-sm overflow-auto'>{{JSON.stringify
            this.formData
            null
            2
          }}</pre>
      </div>
    </div>
  </template>
}
```

### Complete Form Example

This example shows CheckboxGroup with the Form validation system, combining multiple CheckboxGroups with other input types, array-based checkbox data, and schema validation with both required and optional checkbox groups.

```gts preview collapsible
import Component from '@glimmer/component';
import { tracked } from '@glimmer/tracking';
import { fn } from '@ember/helper';
import { Form, CheckboxGroup, type FormResultData } from 'frontile';
import { Button } from 'frontile';
import * as v from 'valibot';

// Define validation schema
const schema = v.object({
  name: v.pipe(
    v.string(),
    v.nonEmpty('Name is required'),
    v.minLength(2, 'Name must be at least 2 characters')
  ),
  interests: v.pipe(
    v.array(v.string()),
    v.minLength(1, 'Please select at least one interest')
  ),
  newsletters: v.array(v.string()) // Optional - no minimum required
});

type Schema = v.InferOutput<typeof schema>;

export default class CompleteFormWithCheckbox extends Component {
  @tracked formData: Schema = {
    name: '',
    interests: [],
    newsletters: []
  };
  @tracked submitMessage = '';

  // Helper to check if a value is selected in a field
  isChecked = (field: 'interests' | 'newsletters', value: string) => {
    return this.formData[field]?.includes(value) ?? false;
  };

  // Single reusable handler for any checkbox group
  handleCheckboxChange = (field: 'interests' | 'newsletters', value: string, checked: boolean) => {
    const current = this.formData[field] || [];

    if (checked) {
      this.formData[field] = [...current, value];
    } else {
      this.formData[field] = current.filter((v) => v !== value);
    }
  };

  handleFormChange = (data: FormResultData<Schema>) => {
    this.formData = data.data;
  };

  handleFormSubmit = (data: FormResultData<Schema>) => {
    this.submitMessage = 'Registration submitted successfully!';
    console.log('Form submitted:', data.data);
  };

  <template>
    <div class='demo-stack'>
      <Form
        @data={{this.formData}}
        @schema={{schema}}
        @onChange={{this.handleFormChange}}
        @onSubmit={{this.handleFormSubmit}}
        as |form|
      >
        <div class='flex flex-col gap-4'>
          <form.Field @name='name' as |field|>
            <field.Input
              @label='Full Name'
              @isRequired={{true}}
            />
          </form.Field>

          <form.Field @name='interests' as |field|>
            <field.CheckboxGroup
              @label='Areas of Interest'
              @description='Select topics you would like to hear about'
              @isRequired={{true}}
              @orientation='horizontal'
              as |Checkbox|
            >
              <Checkbox
                value='technology'
                @label='Technology'
                @checked={{this.isChecked 'interests' 'technology'}}
                @onChange={{fn this.handleCheckboxChange 'interests' 'technology'}}
              />
              <Checkbox
                value='sports'
                @label='Sports'
                @checked={{this.isChecked 'interests' 'sports'}}
                @onChange={{fn this.handleCheckboxChange 'interests' 'sports'}}
              />
              <Checkbox
                value='music'
                @label='Music'
                @checked={{this.isChecked 'interests' 'music'}}
                @onChange={{fn this.handleCheckboxChange 'interests' 'music'}}
              />
              <Checkbox
                value='travel'
                @label='Travel'
                @checked={{this.isChecked 'interests' 'travel'}}
                @onChange={{fn this.handleCheckboxChange 'interests' 'travel'}}
              />
            </field.CheckboxGroup>
          </form.Field>

          <form.Field @name='newsletters' as |field|>
            <field.CheckboxGroup
              @label='Newsletter Subscriptions'
              @description='Optional newsletters you can subscribe to'
              as |Checkbox|
            >
              <Checkbox
                value='weekly'
                @label='Weekly Newsletter'
                @description='Get the latest updates every week'
                @checked={{this.isChecked 'newsletters' 'weekly'}}
                @onChange={{fn this.handleCheckboxChange 'newsletters' 'weekly'}}
              />
              <Checkbox
                value='monthly'
                @label='Monthly Digest'
                @description='Monthly summary of important news and updates'
                @checked={{this.isChecked 'newsletters' 'monthly'}}
                @onChange={{fn this.handleCheckboxChange 'newsletters' 'monthly'}}
              />
            </field.CheckboxGroup>
          </form.Field>

          <div>
            <Button type='submit'>
              Submit Registration
            </Button>
          </div>
        </div>
      </Form>

      {{#if this.submitMessage}}
        <div class='p-3 bg-success-subtle text-success-strong rounded'>
          {{this.submitMessage}}
        </div>
      {{/if}}

      <div class='p-4 bg-neutral-subtle rounded'>
        <h4 class='font-medium mb-2'>Form Data:</h4>
        <pre class='text-sm overflow-auto'>{{JSON.stringify
            this.formData
            null
            2
          }}</pre>
      </div>
    </div>
  </template>
}
```

### Miscellaneous Options

This example demonstrates various optional arguments and configurations available for CheckboxGroup:

- **Orientation**: Use `@orientation='horizontal'` to arrange checkboxes horizontally (default is vertical)
- **Size**: Control checkbox size with `@size='sm'`, `@size='md'`, or `@size='lg'`
- **Description**: Add helpful text to the group with `@description`, and to individual checkboxes with `@description` on each Checkbox
- **Custom Styling**: Customize appearance with `@classes` argument

```gts preview collapsible
import { CheckboxGroup } from 'frontile';
import { hash } from '@ember/helper';

<template>
  <div class='demo-stack'>
    {{! Horizontal Orientation }}
    <CheckboxGroup
      @label='Horizontal Layout'
      @orientation='horizontal'
      as |Checkbox|
    >
      <Checkbox @label='Option A' @description='First option in horizontal layout' />
      <Checkbox @label='Option B' @description='Second option in horizontal layout' />
      <Checkbox @label='Option C' @description='Third option in horizontal layout' />
    </CheckboxGroup>

    {{! Different Sizes }}
    <div class='flex flex-col gap-4'>
      <CheckboxGroup @label='Small Size' @size='sm' as |Checkbox|>
        <Checkbox @label='Small Option A' @description='Compact checkbox size' />
        <Checkbox @label='Small Option B' @description='Another compact size' />
      </CheckboxGroup>

      <CheckboxGroup @label='Medium Size' @size='md' as |Checkbox|>
        <Checkbox @label='Medium Option A' @description='Standard checkbox size' />
        <Checkbox @label='Medium Option B' @description='Another standard size' />
      </CheckboxGroup>

      <CheckboxGroup @label='Large Size' @size='lg' as |Checkbox|>
        <Checkbox @label='Large Option A' @description='Spacious checkbox size' />
        <Checkbox @label='Large Option B' @description='Another spacious size' />
      </CheckboxGroup>
    </div>

    {{! With Group Description }}
    <CheckboxGroup
      @label='User Permissions'
      @description='Select the permissions this user should have. You can modify these later.'
      as |Checkbox|
    >
      <Checkbox @label='Read access' @description='View files and data' />
      <Checkbox @label='Write access' @description='Create and edit content' />
      <Checkbox @label='Delete access' @description='Remove files permanently' />
    </CheckboxGroup>

    {{! Custom Styling }}
    <CheckboxGroup
      @label='Custom Styled Group'
      @classes={{hash
        base='my-custom-checkbox-group'
        label='my-custom-label'
        optionsContainer='my-custom-options-container'
      }}
      as |Checkbox|
    >
      <Checkbox @label='Styled Option 1' @description='First custom styled option' />
      <Checkbox @label='Styled Option 2' @description='Second custom styled option' />
      <Checkbox @label='Styled Option 3' @description='Third custom styled option' />
    </CheckboxGroup>
  </div>
</template>
```

## Accessibility

The CheckboxGroup component follows accessibility best practices:

- Proper grouping with fieldset/legend semantics via FormControl
- Proper label association for each checkbox option
- ARIA attributes for invalid states (`aria-invalid`)
- Descriptive text association using `aria-describedby`
- Support for required field indication
- Keyboard navigation follows standard checkbox patterns (space to toggle)
- Screen reader announcements for group label, individual option labels, and validation messages

## API

### CheckboxGroup

**Element:** `HTMLDivElement`

**Arguments**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `classes` | `SlotsToClasses<'label' \| 'base' \| 'optionsContainer'>` | - | Class names for each slot of the component, merged with the theme's. |
| `description` | `string` | - | Help text rendered between the label and the control, and referenced by the ids describedBy returns. |
| `errors` | `string \| string[]` | - | Validation messages for the field. A non-empty value also marks the control invalid, and an array is joined with ;  when displayed. |
| `isDisabled` | `boolean` | `false` | Whether the field is disabled. FormControl passes this through for styling; the control it wraps is responsible for the disabled attribute. |
| `isInvalid` | `boolean` | `false` | Marks the control invalid without supplying messages, for validation that is reported elsewhere. |
| `isRequired` | `boolean` | `false` | Whether the field is required. Adds an asterisk to the label; it does not set the required attribute on the control itself. |
| `label` | `string` | - | The label text rendered above the control and associated with it via for. Use the :label block instead when the label needs markup. |
| `name` | `string` | - | The name attribute applied to every checkbox in the group, so they are submitted together as one field. |
| `onChange` | `(value: boolean, event: Event) => void` | - | Callback when a checkbox in the group is toggled. It is bound onto every yielded Checkbox, so a checkbox that sets its own @onChange replaces this one rather than running alongside it. |
| `orientation` | `'horizontal' \| 'vertical'` | `'vertical'` | How the checkboxes are laid out. |
| `size` | `'sm' \| 'md' \| 'lg'` | - | The size applied to every checkbox in the group and to the group's label. |

**Blocks**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `default *` | `[Checkbox: Checkbox (name, onChange, isDisabled bound)]` | - |  |

---

# Checkbox

Source: /docs/components/forms/checkbox.md

# Checkbox

A standalone checkbox component that allows users to select or deselect individual options. While typically used within a CheckboxGroup, it can also be used individually when you need more control over the layout and behavior. The component is controlled, requiring `@checked` and `@onChange` for state management.

## Import

```js
import { Checkbox } from 'frontile';
```

## Usage

### Basic Checkbox

The most basic usage of a Checkbox component with a label.

```gts preview
import { Checkbox } from 'frontile';

<template>
  <div class='demo-stack'>
    <Checkbox @label='Subscribe to newsletter' />
  </div>
</template>
```

### Controlled Checkbox

You can control the checkbox state by providing `@checked` and handling updates with `@onChange`.

```gts preview
import Component from '@glimmer/component';
import { tracked } from '@glimmer/tracking';
import { Checkbox } from 'frontile';

export default class ControlledCheckbox extends Component {
  @tracked isSubscribed = false;

  updateSubscription = (checked: boolean) => {
    this.isSubscribed = checked;
  };

  <template>
    <div class='demo-stack'>
      <Checkbox
        @label='Subscribe to newsletter'
        @checked={{this.isSubscribed}}
        @onChange={{this.updateSubscription}}
      />

      <div class='p-3 border border-neutral-soft rounded'>
        <p class='text-sm'>
          Status:
          {{if this.isSubscribed 'Subscribed' 'Not subscribed'}}
        </p>
      </div>
    </div>
  </template>
}
```

### Multiple Independent Checkboxes

When you need multiple independent checkboxes, each should have a unique name and state.

```gts preview collapsible
import Component from '@glimmer/component';
import { tracked } from '@glimmer/tracking';
import { Checkbox } from 'frontile';

export default class IndependentCheckboxes extends Component {
  @tracked notifications = {
    email: false,
    sms: false,
    push: false
  };

  updateEmailNotifications = (checked: boolean) => {
    this.notifications = { ...this.notifications, email: checked };
  };

  updateSmsNotifications = (checked: boolean) => {
    this.notifications = { ...this.notifications, sms: checked };
  };

  updatePushNotifications = (checked: boolean) => {
    this.notifications = { ...this.notifications, push: checked };
  };

  get enabledNotifications() {
    return Object.entries(this.notifications)
      .filter(([_, enabled]) => enabled)
      .map(([type]) => type)
      .join(', ');
  }

  <template>
    <div class='demo-stack'>
      <Checkbox
        @name='email-notifications'
        @label='Email notifications'
        @checked={{this.notifications.email}}
        @onChange={{this.updateEmailNotifications}}
      />

      <Checkbox
        @name='sms-notifications'
        @label='SMS notifications'
        @checked={{this.notifications.sms}}
        @onChange={{this.updateSmsNotifications}}
      />

      <Checkbox
        @name='push-notifications'
        @label='Push notifications'
        @checked={{this.notifications.push}}
        @onChange={{this.updatePushNotifications}}
      />

      <div class='p-4 bg-neutral-subtle rounded'>
        <h4 class='font-medium mb-2'>Enabled Notifications:</h4>
        <p class='text-sm'>
          {{if
            this.enabledNotifications
            this.enabledNotifications
            'None selected'
          }}
        </p>
      </div>
    </div>
  </template>
}
```

> **Note:** This example shows manual state management. For forms with validation, see the "Form Validation" and "Complete Form Example" sections which use Form/Field components.

### Sizes

Control the size of checkboxes using the `@size` argument.

```gts preview collapsible
import Component from '@glimmer/component';
import { tracked } from '@glimmer/tracking';
import { Checkbox } from 'frontile';

export default class CheckboxSizes extends Component {
  @tracked smallChecked = false;
  @tracked mediumChecked = false;
  @tracked largeChecked = false;

  updateSmallChecked = (checked: boolean) => {
    this.smallChecked = checked;
  };

  updateMediumChecked = (checked: boolean) => {
    this.mediumChecked = checked;
  };

  updateLargeChecked = (checked: boolean) => {
    this.largeChecked = checked;
  };

  <template>
    <div class='demo-stack'>
      <Checkbox
        @name='small-checkbox'
        @label='Small Checkbox'
        @size='sm'
        @checked={{this.smallChecked}}
        @onChange={{this.updateSmallChecked}}
      />

      <Checkbox
        @name='medium-checkbox'
        @label='Medium Checkbox'
        @size='md'
        @checked={{this.mediumChecked}}
        @onChange={{this.updateMediumChecked}}
      />

      <Checkbox
        @name='large-checkbox'
        @label='Large Checkbox'
        @size='lg'
        @checked={{this.largeChecked}}
        @onChange={{this.updateLargeChecked}}
      />
    </div>
  </template>
}
```

### Disabled State

Checkboxes can be disabled to prevent user interaction while maintaining their visual presence and current state.

```gts preview
import Component from '@glimmer/component';
import { Checkbox } from 'frontile';

export default class DisabledCheckbox extends Component {
  <template>
    <div class='demo-stack'>
      <Checkbox
        @name='disabled-checked'
        @label='Disabled Checked Checkbox'
        @checked={{true}}
        disabled={{true}}
      />

      <Checkbox
        @name='disabled-unchecked'
        @label='Disabled Unchecked Checkbox'
        @checked={{false}}
        disabled={{true}}
      />

      <Checkbox
        @name='disabled-with-description'
        @label='Disabled Checkbox with Description'
        @description='This checkbox is disabled and cannot be modified'
        @checked={{true}}
        disabled={{true}}
      />
    </div>
  </template>
}
```

### Indeterminate State

The indeterminate state represents a "partially checked" state, commonly used for "select all" checkboxes when only some child items are selected. Since HTML doesn't support setting indeterminate via an attribute, you need to use a modifier to set it via JavaScript.

```gts preview collapsible
import Component from '@glimmer/component';
import { tracked } from '@glimmer/tracking';
import { modifier } from 'ember-modifier';
import { Checkbox } from 'frontile';

export default class IndeterminateCheckbox extends Component {
  @tracked items = [
    { label: 'Email notifications', checked: true },
    { label: 'SMS notifications', checked: false },
    { label: 'Push notifications', checked: true }
  ];

  get allChecked() {
    return this.items.every((item) => item.checked);
  }

  get noneChecked() {
    return this.items.every((item) => !item.checked);
  }

  get isIndeterminate() {
    return !this.allChecked && !this.noneChecked;
  }

  setIndeterminate = modifier(
    (element: HTMLInputElement, [indeterminate]: [boolean]) => {
      element.indeterminate = indeterminate;
    }
  );

  toggleAll = (checked: boolean) => {
    this.items = this.items.map((item) => ({ ...item, checked }));
  };

  toggleItem = (index: number) => (checked: boolean) => {
    this.items = this.items.map((item, i) =>
      i === index ? { ...item, checked } : item
    );
  };

  <template>
    <div class='demo-stack'>
      <Checkbox
        @name='select-all'
        @label='Select All'
        @checked={{this.allChecked}}
        @onChange={{this.toggleAll}}
        {{this.setIndeterminate this.isIndeterminate}}
      />

      <div class='ml-6 flex flex-col gap-2'>
        {{#each this.items as |item index|}}
          <Checkbox
            @name='item-{{index}}'
            @label={{item.label}}
            @checked={{item.checked}}
            @onChange={{this.toggleItem index}}
          />
        {{/each}}
      </div>
    </div>
  </template>
}
```

> **Note:** The `indeterminate` property can only be set via JavaScript — there is no HTML attribute for it. Use the `ember-modifier` package to create a modifier that sets `element.indeterminate` on the checkbox input.

### Checkbox with Description

Add helpful description text that appears below the checkbox label.

```gts preview collapsible
import Component from '@glimmer/component';
import { tracked } from '@glimmer/tracking';
import { Checkbox } from 'frontile';

export default class CheckboxWithDescription extends Component {
  @tracked termsAccepted = false;
  @tracked marketingConsent = false;

  updateTermsAccepted = (checked: boolean) => {
    this.termsAccepted = checked;
  };

  updateMarketingConsent = (checked: boolean) => {
    this.marketingConsent = checked;
  };

  <template>
    <div class='demo-stack'>
      <Checkbox
        @name='terms-acceptance'
        @label='I agree to the terms and conditions'
        @description='By checking this box, you agree to our terms of service, privacy policy, and cookie policy. You can review these documents at any time.'
        @checked={{this.termsAccepted}}
        @onChange={{this.updateTermsAccepted}}
      />

      <Checkbox
        @name='marketing-consent'
        @label='I consent to receive marketing communications'
        @description='We will send you occasional updates about new features, promotions, and company news. You can unsubscribe at any time.'
        @checked={{this.marketingConsent}}
        @onChange={{this.updateMarketingConsent}}
      />
    </div>
  </template>
}
```

### Form Validation

**Note:** When used with `field.Checkbox` as demonstrated in the examples below, individual Checkbox components support field-level validation (validates on change/blur/input events based on `@validateOn`). This differs from CheckboxGroup, which currently only supports validation on form submit.

Checkbox integrates with the Form validation system, providing automatic error display and field-level validation. This example uses a required checkbox with the Form/Field components.

```gts preview collapsible
import Component from '@glimmer/component';
import { tracked } from '@glimmer/tracking';
import { Form, type FormResultData } from 'frontile';
import { Button } from 'frontile';
import { array } from '@ember/helper';
import * as v from 'valibot';

// Define validation schema - checkbox must be true
const schema = v.object({
  termsAccepted: v.pipe(
    v.boolean(),
    v.literal(true, 'You must accept the terms and conditions to continue')
  )
});

type Schema = v.InferOutput<typeof schema>;

export default class ValidatedCheckbox extends Component {
  @tracked formData: Schema = {
    termsAccepted: false
  };
  @tracked submitMessage = '';

  handleFormChange = (data: FormResultData<Schema>) => {
    this.formData = data.data;
  };

  handleFormSubmit = (data: FormResultData<Schema>) => {
    this.submitMessage = 'Terms accepted successfully!';
    console.log('Form submitted:', data.data);
  };

  <template>
    <div class='demo-stack'>
      <Form
        @data={{this.formData}}
        @schema={{schema}}
        @onChange={{this.handleFormChange}}
        @onSubmit={{this.handleFormSubmit}}
        @validateOn={{array 'change' 'submit'}}
        as |form|
      >
        <form.Field @name='termsAccepted' as |field|>
          <field.Checkbox
            @label='I accept the terms and conditions'
            @description='Please read and accept our terms and conditions before proceeding.'
            @isRequired={{true}}
          />
        </form.Field>

        <div>
          <Button type='submit'>
            Continue
          </Button>
        </div>
      </Form>

      {{#if this.submitMessage}}
        <div class='p-3 bg-success-subtle text-success-strong rounded'>
          {{this.submitMessage}}
        </div>
      {{/if}}

      <div class='p-4 bg-neutral-subtle rounded'>
        <h4 class='font-medium mb-2'>Form Data:</h4>
        <pre class='text-sm overflow-auto'>{{JSON.stringify
            this.formData
            null
            2
          }}</pre>
      </div>
    </div>
  </template>
}
```

### Horizontal Layout

Create a horizontal layout using CSS Grid or Flexbox.

> **Note:** For horizontal layouts of related checkboxes, consider using `CheckboxGroup` with `@orientation='horizontal'`.

```gts preview collapsible
import Component from '@glimmer/component';
import { tracked } from '@glimmer/tracking';
import { Checkbox } from 'frontile';

export default class HorizontalCheckboxes extends Component {
  @tracked preferences = {
    newsletter: false,
    updates: false,
    promotions: false
  };

  updatePreference = (key: string) => (checked: boolean) => {
    this.preferences = { ...this.preferences, [key]: checked };
  };

  <template>
    <div class='demo-stack'>
      <fieldset>
        <legend class='text-lg font-medium mb-3'>Email Preferences</legend>
        <div class='flex gap-4'>
          <Checkbox
            @name='newsletter-pref'
            @label='Newsletter'
            @checked={{this.preferences.newsletter}}
            @onChange={{this.updatePreference 'newsletter'}}
          />
          <Checkbox
            @name='updates-pref'
            @label='Product Updates'
            @checked={{this.preferences.updates}}
            @onChange={{this.updatePreference 'updates'}}
          />
          <Checkbox
            @name='promotions-pref'
            @label='Promotions'
            @checked={{this.preferences.promotions}}
            @onChange={{this.updatePreference 'promotions'}}
          />
        </div>
      </fieldset>

      <div class='p-3 border border-neutral-soft rounded'>
        <p class='text-sm'>
          Selected preferences:
          {{#each-in this.preferences as |key value|}}
            {{#if value}}{{key}} {{/if}}
          {{/each-in}}
        </p>
      </div>
    </div>
  </template>
}
```

### Complete Form Example

A registration form with an Input field, a required checkbox, and an optional checkbox, all integrated with the Form validation system.

```gts preview collapsible
import Component from '@glimmer/component';
import { tracked } from '@glimmer/tracking';
import { Form, type FormResultData } from 'frontile';
import { Button } from 'frontile';
import { array } from '@ember/helper';
import * as v from 'valibot';

// Define validation schema
const schema = v.object({
  email: v.pipe(
    v.string(),
    v.nonEmpty('Email is required'),
    v.email('Please enter a valid email address')
  ),
  termsAccepted: v.pipe(
    v.boolean(),
    v.literal(true, 'You must accept the terms and conditions')
  ),
  marketingConsent: v.boolean() // Optional checkbox - no literal(true) requirement
});

type Schema = v.InferOutput<typeof schema>;

export default class CompleteFormWithCheckbox extends Component {
  @tracked formData: Schema = {
    email: '',
    termsAccepted: false,
    marketingConsent: false
  };
  @tracked submitMessage = '';

  handleFormChange = (data: FormResultData<Schema>) => {
    this.formData = data.data;
  };

  handleFormSubmit = (data: FormResultData<Schema>) => {
    this.submitMessage = 'Account created successfully!';
    console.log('Form submitted:', data.data);
  };

  <template>
    <div class='demo-stack'>
      <Form
        @data={{this.formData}}
        @schema={{schema}}
        @onChange={{this.handleFormChange}}
        @onSubmit={{this.handleFormSubmit}}
        @validateOn={{array 'change' 'submit'}}
        as |form|
      >
        <div class='flex flex-col gap-4'>
          <form.Field @name='email' as |field|>
            <field.Input
              @label='Email Address'
              @type='email'
              @isRequired={{true}}
            />
          </form.Field>

          <form.Field @name='termsAccepted' as |field|>
            <field.Checkbox
              @label='I agree to the Terms and Conditions'
              @description='You must accept our terms to create an account'
              @isRequired={{true}}
            />
          </form.Field>

          <form.Field @name='marketingConsent' as |field|>
            <field.Checkbox
              @label='I would like to receive marketing emails'
              @description='Optional: Get updates about new features and promotions'
            />
          </form.Field>

          <div>
            <Button type='submit' disabled={{form.isSubmitting}}>
              {{if form.isSubmitting 'Creating Account...' 'Create Account'}}
            </Button>
          </div>
        </div>
      </Form>

      {{#if this.submitMessage}}
        <div class='p-3 bg-success-subtle text-success-strong rounded'>
          {{this.submitMessage}}
        </div>
      {{/if}}

      <div class='p-4 bg-neutral-subtle rounded'>
        <h4 class='font-medium mb-2'>Form Data:</h4>
        <pre class='text-sm overflow-auto'>{{JSON.stringify
            this.formData
            null
            2
          }}</pre>
      </div>
    </div>
  </template>
}
```

### Custom Styling

You can customize the appearance of different parts of the checkbox using the `@classes` argument.

```gts preview
import Component from '@glimmer/component';
import { tracked } from '@glimmer/tracking';
import { Checkbox } from 'frontile';
import { hash } from '@ember/helper';

export default class CustomStyledCheckbox extends Component {
  @tracked customChecked = false;

  updateCustomChecked = (checked: boolean) => {
    this.customChecked = checked;
  };

  <template>
    <div class='demo-stack'>
      <Checkbox
        @name='custom-styled'
        @label='Custom Styled Checkbox'
        @description='This checkbox has custom styling applied'
        @checked={{this.customChecked}}
        @onChange={{this.updateCustomChecked}}
        @classes={{hash
          base='my-custom-checkbox-base'
          input='my-custom-checkbox-input'
          labelContainer='my-custom-label-container'
          label='my-custom-checkbox-label'
        }}
      />
    </div>
  </template>
}
```

## When to Use Checkbox vs CheckboxGroup

**Use the standalone Checkbox component when:**

- You need independent boolean choices
- You want complete control over layout and spacing
- You're building a custom form layout
- Each checkbox represents a separate decision
- You need field-level validation with change/blur/input events

**Use CheckboxGroup when:**

- You have multiple related options that can be selected together
- You want automatic grouping and consistent layout
- You need group-level validation and error handling
- You want built-in label and description support for the group
- Note: CheckboxGroup currently only supports validation on form submit, not on change/blur/input events

## Accessibility

The Checkbox component follows accessibility best practices:

- Proper label association using `for` and `id` attributes
- ARIA attributes for invalid states (`aria-invalid`)
- Descriptive text association using `aria-describedby`
- Support for required field indication
- Keyboard navigation follows standard checkbox patterns (space to toggle)
- Screen reader announcements for labels, descriptions, and validation messages
- Proper focus management and visual focus indicators

## API

### Checkbox

**Element:** `HTMLInputElement`

**Arguments**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `checked` | `boolean` | - | Whether the checkbox is checked. Pair with onChange to control the checkbox; leave it unset to let the element track its own state. |
| `classes` | `SlotsToClasses<'label' \| 'base' \| 'input' \| 'labelContainer'>` | - | Class names for each slot of the component, merged with the theme's. |
| `description` | `string` | - | Help text rendered between the label and the control, and referenced by the ids describedBy returns. |
| `errors` | `string \| string[]` | - | Validation messages for the field. A non-empty value also marks the control invalid, and an array is joined with ;  when displayed. |
| `isDisabled` | `boolean` | `false` | Whether the field is disabled. FormControl passes this through for styling; the control it wraps is responsible for the disabled attribute. |
| `isInvalid` | `boolean` | `false` | Marks the control invalid without supplying messages, for validation that is reported elsewhere. |
| `isRequired` | `boolean` | `false` | Whether the field is required. Adds an asterisk to the label; it does not set the required attribute on the control itself. |
| `label` | `string` | - | The label text rendered above the control and associated with it via for. Use the :label block instead when the label needs markup. |
| `name` | `string` | - | The name attribute of the underlying input, used when the checkbox is submitted as part of a form. |
| `onBlur` | `() => void` | - | Callback when onblur is triggered |
| `onChange` | `(value: boolean, event: Event) => void` | - | Callback when onchange is triggered |
| `size` | `'sm' \| 'md' \| 'lg'` | `'md'` | The size of the checkbox and its label. |

---

# DateInput

Source: /docs/components/forms/date-input.md

# DateInput

A date that is typed rather than picked: `mm / dd / yyyy` rendered as separately
focusable segments, each one editable with digits and arrow keys. Reach for it when a
calendar is the wrong tool — a birth date, an expiry date, anything far from today. For a
field that also offers a calendar, use [DatePicker](./date-picker), which renders these
same segments and adds one.

## Import

```js
import { DateInput } from 'frontile';
```

## Usage

```gts preview
import { DateInput } from 'frontile';

<template>
  <div class='demo-stack'>
    <DateInput @label='Birth date' />
  </div>
</template>
```

## Typing a Date

Digits go into the focused segment and advance to the next one as soon as the segment
cannot take another: typing `1` in the month shows `01` and waits, a following `2` makes
`12` and moves on, while a following `5` cannot extend `12`, so the month commits and `05`
starts in the day.

A year segment holding one or two digits resolves into the hundred years running from 80
back to 19 forward when you leave it, so in 2026 `45` becomes 2045 and `99` becomes 1999.
Three or four digits are taken literally: `0045` is the year 45. Pasting follows the same
rule.

A partly filled field composes no date. Typing a month and a day fires no `@onChange`, and
the value stays `null` until every segment holds a finished number. Leaving the field
neither clears the entry nor fills in what is missing: the digits you typed stay on screen,
the segments you skipped stay empty, and the value stays `null`.

An impossible day shortens to the month's length: February with `31` in the day composes
the 28th (the 29th in a leap year), and the segment redisplays.

## Controlled vs Uncontrolled

`@value` accepts a `Date` or a `yyyy-MM-dd` string, and `@defaultValue` seeds an
uncontrolled field. `@onChange` always hands back `Date`s, regardless of which form
`@value` was given in.

The field keeps its own segments and treats `@value` as something to sync *from*: setting
it rewrites what is displayed, and typing updates the field immediately without waiting
for `@value` to come back. Passing `undefined` changes nothing, so a field whose `@value`
has no data yet still honours `@defaultValue`. This is what lets it work inside a `<Form>`,
where `@value` is bound to data the field is itself the only source of.

```gts preview
import Component from '@glimmer/component';
import { tracked } from '@glimmer/tracking';
import { DateInput } from 'frontile';

export default class ControlledDateInput extends Component {
  @tracked value: Date | null = new Date(2026, 0, 20);

  handleChange = (value: Date | null) => {
    this.value = value;
  };

  get valueLabel(): string {
    return this.value ? this.value.toDateString() : 'No date entered';
  }

  <template>
    <div class='demo-stack'>
      <DateInput
        @label='Start date'
        @value={{this.value}}
        @onChange={{this.handleChange}}
      />
      <p class='text-sm text-neutral-soft'>{{this.valueLabel}}</p>
    </div>
  </template>
}
```

## Locale and Format

`@locale` decides the order of the segments and the literals between them; it defaults to
`navigator.language`. Changing it at runtime reorders the field without emptying it.

```gts preview
import { DateInput } from 'frontile';

const value = new Date(2026, 0, 20);

<template>
  <div class='grid gap-4 md:grid-cols-3'>
    <DateInput @label='en-US' @locale='en-US' @defaultValue={{value}} />
    <DateInput @label='en-GB' @locale='en-GB' @defaultValue={{value}} />
    <DateInput @label='de-DE' @locale='de-DE' @defaultValue={{value}} />
  </div>
</template>
```

`@formatOptions` decides which segments appear and in what order. It defaults to
`{ year: 'numeric', month: '2-digit', day: '2-digit' }`. A filled segment always shows its
full width — two digits for the month and day, four for the year — so `month: 'numeric'`
and `month: '2-digit'` render the same field.

A textual month — `{ month: 'short' }`, and so any `dateStyle` preset — has no numeric
segment to type into. The month falls back to a numeric one and the component warns. Only
the month is replaced, so `{ month: 'short', day: '2-digit' }` still renders exactly those
two segments. A `dateStyle` preset names no fields at all, so it falls back to the numeric
default in full.

```gts preview
import { DateInput } from 'frontile';

const value = new Date(2026, 0, 5);
const monthAndDay = { month: '2-digit', day: '2-digit' } as const;
const yearAndMonth = { year: 'numeric', month: '2-digit' } as const;

<template>
  <div class='grid gap-4 md:grid-cols-3'>
    <DateInput @label='Default' @locale='en-US' @defaultValue={{value}} />
    <DateInput
      @label='Month and day'
      @locale='en-US'
      @defaultValue={{value}}
      @formatOptions={{monthAndDay}}
    />
    <DateInput
      @label='Year and month'
      @locale='en-US'
      @defaultValue={{value}}
      @formatOptions={{yearAndMonth}}
    />
  </div>
</template>
```

## Copy and Paste

Copying writes the field as it reads on screen, literals included, and cutting copies and
then clears.

Pasting accepts three shapes, tried in that order: an ISO `yyyy-MM-dd` string, a bare run
of digits split by segment width (`12252026`), and numbers separated by anything
non-numeric, mapped onto the segments in their locale order — so `25/12/2026` is the 25th
of December under `en-GB`. Text that yields fewer numbers than there are segments fills
what it can. A number outside its segment's bounds refuses the whole paste rather than
being clamped to fit, and text that reads as no date at all is dropped with no change.

Paste `2026-01-20`, `01/20/2026` or `01202026` into the field below.

```gts preview
import { DateInput } from 'frontile';

<template>
  <div class='demo-stack'>
    <DateInput
      @label='Start date'
      @locale='en-US'
      @description='Paste 2026-01-20 into any segment.'
    />
  </div>
</template>
```

## Validation

`@minValue` and `@maxValue` bound the allowed dates and `@isDateUnavailable` rejects
individual ones. A value outside those bounds marks the field invalid; none of them ever
block a keystroke, because a year on its way to `2020` passes through `2`, `20` and `202`
and a field that refused those could not be typed into at all.

`@errors` renders feedback of your own, exactly as on every other form field.

```gts preview
import { DateInput } from 'frontile';

const min = new Date(2026, 0, 1);
const max = new Date(2026, 0, 31);
const value = new Date(2026, 5, 14);
const isWeekend = (date: Date) => date.getDay() === 0 || date.getDay() === 6;

<template>
  <div class='demo-stack'>
    <DateInput
      @label='Appointment date'
      @locale='en-US'
      @defaultValue={{value}}
      @minValue={{min}}
      @maxValue={{max}}
      @isDateUnavailable={{isWeekend}}
      @description='Weekdays in January 2026 only.'
    />
  </div>
</template>
```

## Clearable

`@isClearable` adds a clear button at the end of the field once any segment holds a digit.
It never renders on a disabled or read-only field, and clearing moves focus to the first
segment so a keyboard user does not lose their place.

```gts preview
import { DateInput } from 'frontile';

const value = new Date(2026, 0, 20);

<template>
  <div class='demo-stack'>
    <DateInput @label='Start date' @defaultValue={{value}} @isClearable={{true}} />
  </div>
</template>
```

## Sizes

```gts preview
import { DateInput } from 'frontile';

<template>
  <div class='grid gap-4 md:grid-cols-3'>
    <DateInput @label='Small' @inputSize='sm' />
    <DateInput @label='Medium' @inputSize='md' />
    <DateInput @label='Large' @inputSize='lg' />
  </div>
</template>
```

## Disabled and Read-only

`@isDisabled` takes the segments out of the tab order entirely. `@isReadOnly` keeps them
focusable, navigable and copyable, and refuses every edit.

```gts preview
import { DateInput } from 'frontile';

const value = new Date(2026, 0, 20);

<template>
  <div class='grid gap-4 md:grid-cols-2'>
    <DateInput @label='Disabled' @defaultValue={{value}} @isDisabled={{true}} />
    <DateInput @label='Read-only' @defaultValue={{value}} @isReadOnly={{true}} />
  </div>
</template>
```

## Inside a Form

A `DateInput` given `@name` submits one field, and the wire value is the same
`yyyy-MM-dd` string `@value` accepts. An incomplete entry submits an empty string.

```gts preview
import Component from '@glimmer/component';
import { tracked } from '@glimmer/tracking';
import { Form, DateInput, type FormResultData } from 'frontile';

export default class DateInputFormExample extends Component {
  @tracked submitted: FormResultData['data'] | null = null;

  handleSubmit = ({ data }: FormResultData) => {
    this.submitted = data;
  };

  <template>
    <div class='demo-stack'>
      <Form @onSubmit={{this.handleSubmit}}>
        <DateInput @label='Start date' @name='start' />
        <button type='submit'>Save</button>
      </Form>
      {{#if this.submitted}}
        <p class='text-sm'>Submitted: {{this.submitted.start}}</p>
      {{/if}}
    </div>
  </template>
}
```

`<form.Field>` yields a bound `DateInput` alongside the bound pickers, wiring the name,
value, errors and disabled state for you.

```gts preview
import Component from '@glimmer/component';
import { tracked } from '@glimmer/tracking';
import { Form, type FormResultData } from 'frontile';

export default class DateInputFieldExample extends Component {
  @tracked submitted: FormResultData['data'] | null = null;

  handleSubmit = ({ data }: FormResultData) => {
    this.submitted = data;
  };

  <template>
    <div class='demo-stack'>
      <Form @onSubmit={{this.handleSubmit}} as |form|>
        <form.Field @name='birthday' as |field|>
          <field.DateInput @label='Birth date' @locale='en-US' />
        </form.Field>
        <button type='submit'>Save</button>
      </Form>
      {{#if this.submitted}}
        <p class='text-sm'>Submitted: {{this.submitted.birthday}}</p>
      {{/if}}
    </div>
  </template>
}
```

## Anatomy

The field's parts carry `data-part` attributes, and state that CSS can select on:

| Element                      | Attributes                                                                                                       |
| ---------------------------- | ---------------------------------------------------------------------------------------------------------------- |
| `[data-part="base"]`         | `data-component="date-input"`                                                                                    |
| `[data-part="inner-container"]` | `data-invalid`, `data-disabled` — the element that draws the field's border, background and focus ring        |
| `[data-part="group"]`        | `data-invalid`, `data-readonly`                                                                                  |
| `[data-part="segment"]`      | `data-type` (`year`, `month` or `day`), `data-placeholder`, `data-disabled`                                      |
| `[data-part="literal"]`      | the separators between segments                                                                                  |
| `[data-part="clear-button"]` | rendered only while `@isClearable` has something to clear                                                        |

`@classes` takes the matching slots: `base`, `innerContainer`, `group`, `segment`,
`literal`, `endContent` and `clearButton`.

```gts preview
import { DateInput } from 'frontile';
import { hash } from '@ember/helper';

<template>
  <div class='demo-stack'>
    <DateInput
      @label='Start date'
      @classes={{hash
        segment='data-[placeholder=true]:text-danger-soft'
        literal='text-danger'
      }}
    />
  </div>
</template>
```

## Accessibility

Each segment is a `role="spinbutton"` carrying `aria-label` (`month`, `day`, `year`, and
overridable through `@segmentLabels`), `aria-valuenow`, `aria-valuemin`, `aria-valuemax`
and `aria-valuetext`. `aria-valuetext` is what makes a month announce as "January" rather
than "1". The separators between them are `aria-hidden`.

The segments sit in a `role="group"` named by `@label` and described by `@description` and
any feedback. `role="group"` supports neither `aria-invalid` nor `aria-readonly` in ARIA
1.2, so the group carries `data-invalid` and `data-readonly` for styling while the real
`aria-invalid` and `aria-readonly` sit on the segments, where assistive technology reads
them.

Every segment is in the tab order, which is three tab stops for one field. This follows
`<input type="date">` in Chrome and Firefox.

| Key                     | Behaviour                                                                    |
| ----------------------- | ---------------------------------------------------------------------------- |
| `Tab` / `Shift+Tab`     | Move between segments                                                        |
| `←` / `→`               | Previous / next segment, skipping the literals; visual order in RTL          |
| `Home` / `End`          | First / last segment                                                         |
| `↑` / `↓`               | Increment / decrement, wrapping within the segment                           |
| `PageUp` / `PageDown`   | Larger step: day ±7, month ±3, year ±10                                      |
| digits                  | Fill the segment, advancing when it cannot take another digit                |
| `Backspace`             | Remove the last digit typed in this segment                                  |
| `Delete`                | Clear the segment                                                            |

`↑` and `↓` on an empty segment start from `@placeholderValue`, which defaults to today.
Arrow-key navigation and `Home`/`End` keep working on a read-only field; the editing keys
do not.

`@onBlur` fires when focus leaves the field, not when it moves from one segment to the
next.

## Testing

`fillIn` does not work on this field — and, importantly, **it does not fail either**.
The segments are `contenteditable`, so `fillIn` writes their text and fires `input`
without complaint, but the component renders from its own segments and listens only to
`beforeinput`/`keydown`. Nothing reaches the value. A test written that way reads green,
its `assert.dom(...).hasText('01')` passes, and the component's value is still `null`.

Use `fillDate` instead. It types the digits segment by segment the way a person does, so
the value composes through the same path as real input.

```js
import { fillDate, fillDateRange } from 'frontile/test-support';

await fillDate('[data-test-due]', '2026-01-20');
await fillDate('[data-test-due]', new Date(2026, 0, 20));

// DatePicker @mode="range"
await fillDateRange('[data-test-trip]', '2026-01-20', '2026-01-25');
```

The selector points at any element containing the field, not at a segment. Both helpers
accept a `Date` or a `yyyy-MM-dd` string, and route each run of digits by segment type —
so the same call works whatever order the locale puts them in.

Pointing `fillDate` at a `DatePicker` rendering its button trigger throws, and says so:
there is nothing to type into on that path, so click the trigger and pick from the
calendar instead.

## API

### DateInput

A date typed into segments rather than picked from a grid. DatePicker
renders the same segments and adds a calendar.

**Element:** `HTMLDivElement`

**Arguments**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `classes` | `SlotsToClasses<'icon' \| 'base' \| 'innerContainer' \| 'startContent' \| 'endContent' \| 'input' \| 'clearButton' \| 'group' \| 'segment' \| 'literal' \| 'calendarButton'>` | - | Per-slot class overrides. |
| `defaultValue` | `string \| Date` | - | Seeds the value before any @value is supplied. |
| `description` | `string` | - | Help text rendered between the label and the control, and referenced by the ids describedBy returns. |
| `errors` | `string \| string[]` | - | Validation messages for the field. A non-empty value also marks the control invalid, and an array is joined with ;  when displayed. |
| `formatOptions` | `Object` | `{ year: 'numeric', month: '2-digit', day: '2-digit' }` | Decides which segments appear, their order, and their literals. |
| `id` | `string` | - | The unique identifier for the control. |
| `inputSize` | `'sm' \| 'md' \| 'lg'` | `'md'` | The size of the field. Matches Input's and Select's @inputSize. |
| `isClearable` | `boolean` | `false` | Whether a clear button appears at the end of the field once any segment holds a digit. Never rendered on a disabled or read-only field. |
| `isDateUnavailable` | `(date: Date) => boolean` | - | Marks individual dates disallowed. A value it returns true for marks the field invalid. Like @minValue and @maxValue, it never blocks a keystroke. |
| `isDisabled` | `boolean` | `false` | Whether the field is disabled. FormControl passes this through for styling; the control it wraps is responsible for the disabled attribute. |
| `isInvalid` | `boolean` | `false` | Marks the control invalid without supplying messages, for validation that is reported elsewhere. |
| `isReadOnly` | `boolean` | `false` | Whether the value can be read and copied but not edited. The segments stay focusable and navigable. |
| `isRequired` | `boolean` | `false` | Whether the field is required. Adds an asterisk to the label; it does not set the required attribute on the control itself. |
| `label` | `string` | - | The label text rendered above the control and associated with it via for. Use the :label block instead when the label needs markup. |
| `locale` | `string` | `navigator.language` |  |
| `maxValue` | `Object` | - | The latest allowed date. A value after it marks the field invalid. |
| `minValue` | `Object` | - | The earliest allowed date. A value before it marks the field invalid. |
| `name` | `string` | - | The value submits under this name as yyyy-MM-dd. |
| `onBlur` | `() => void` | - | Fires when focus leaves the field, not when it moves between segments. |
| `onChange` | `(value: Date) => void` | - | Fires with the composed Date, or null once a complete value is no longer complete. A partially typed date composes nothing and reports nothing. |
| `placeholderValue` | `Object` | `today` | Where ArrowUp on an empty segment starts. |
| `segmentLabels` | `Partial<Record<SegmentType, string>>` | `{ year: 'year', month: 'month', day: 'day' }` | The accessible names of the segments, for localizing them. |
| `value` | `string \| Date` | - | A Date, or the same yyyy-MM-dd string this component writes to its hidden input. The field keeps its own segments and syncs from this argument: setting it replaces what is displayed, while typing updates the field immediately rather than waiting for @value to come back. undefined is ignored, which is why a <form.Field>-bound input still honors @defaultValue before form data exists. |

---

# DatePicker

Source: /docs/components/forms/date-picker.md

# DatePicker

A date field: segments the value can be typed into, and a [Calendar](../collections/calendar)
in a popover behind a calendar button. Use it for picking a single day or, with
`@mode="range"`, a start/end range. `@isEditable={{false}}` swaps the segments for a button
trigger showing the formatted value.

The segments are the same ones [DateInput](./date-input) renders, and behave the same way —
that page documents typing, pasting and the keyboard in full.

## Import

```js
import { DatePicker } from 'frontile';
```

## Usage

```gts preview
import { DatePicker } from 'frontile';

<template>
  <div class='demo-stack'>
    <DatePicker @label='Start date' />
  </div>
</template>
```

## Editable vs Button Trigger

`@isEditable` defaults to `true`, which renders the segmented field above: the value is
typed, and the calendar button at the end of the field opens the popover.

`@isEditable={{false}}` restores the button trigger, where the whole field is one
`<button>` showing the formatted value and clicking anywhere in it opens the calendar.
`@placeholder`, `@formatOptions` and the `:value` block all describe that button — a
segmented field has its own per-segment placeholders and takes its format from
`@formatOptions` differently, as *Formatting* below explains.

```gts preview
import { DatePicker } from 'frontile';

<template>
  <div class='grid gap-4 md:grid-cols-2'>
    <DatePicker @label='Editable' @locale='en-US' />
    <DatePicker
      @label='Button trigger'
      @locale='en-US'
      @isEditable={{false}}
      @placeholder='Pick a date'
    />
  </div>
</template>
```

## Controlled vs Uncontrolled

`@value` accepts a `Date` or a `yyyy-MM-dd` string, and `@defaultValue` seeds an uncontrolled
picker. `@onChange` always hands back `Date`s, regardless of which form `@value` was given in.

The field keeps its own selection and treats `@value` as something to sync *from*: setting it
replaces what is displayed, and picking a date updates the field immediately without waiting
for `@value` to come back. Passing `undefined` changes nothing, so a picker whose `@value` has
no data yet still honours `@defaultValue`. This is how `Select` behaves, and it is what lets
the field work inside a `<Form>`, where `@value` is bound to data the field is itself the only
source of.

```gts preview
import Component from '@glimmer/component';
import { tracked } from '@glimmer/tracking';
import { DatePicker } from 'frontile';

export default class ControlledDatePicker extends Component {
  @tracked value: Date | null = new Date(2026, 0, 20);

  handleChange = (value: Date | null) => {
    this.value = value;
  };

  get valueLabel(): string {
    return this.value ? this.value.toDateString() : 'No date selected';
  }

  <template>
    <div class='demo-stack'>
      <DatePicker
        @label='Start date'
        @value={{this.value}}
        @onChange={{this.handleChange}}
      />
      <p class='text-sm text-neutral-soft'>{{this.valueLabel}}</p>
    </div>
  </template>
}
```

## Range Mode

`@mode="range"` switches the calendar and the value shape to `{ start, end }`. `@visibleMonths`
shows more than one month at a time, which is typical for a range picker.

An editable range renders two groups of segments with a separator between them, one group
per end. Both are typed into, and pasting text that reads as two dates — `2026-01-20 –
2026-02-09` — into the *start* group fills both. A range is anchored at its start: segments
that compose no start compose no range at all, however complete the end group is, and
clearing the start reports `null`.

The popover sizes itself to the calendar, so showing a second month widens it automatically —
there is nothing to adjust. Pass `@popoverSize` if you need a fixed width (`"sm"`, `"md"`,
`"lg"`, `"xl"`) or want it to match the field (`"trigger"`); note that a fixed width narrower
than the grid will clip it.

```gts preview
import Component from '@glimmer/component';
import { tracked } from '@glimmer/tracking';
import { DatePicker } from 'frontile';
import type { DateRange } from 'frontile';

export default class RangeDatePicker extends Component {
  @tracked value: DateRange | null = {
    start: new Date(2026, 0, 20),
    end: new Date(2026, 1, 9)
  };

  handleChange = (value: DateRange | null) => {
    this.value = value;
  };

  <template>
    <div class='demo-stack'>
      <DatePicker
        @label='Stay'
        @mode='range'
        @visibleMonths={{2}}
        @value={{this.value}}
        @onChange={{this.handleChange}}
      />
    </div>
  </template>
}
```

A range with only its start chosen leaves the calendar open: the field shows the anchor in
its start group and waits for the second click.

## Presets

There is no `@presets` argument. Presets are ordinary buttons composed into the `:footer`
block, which yields `{ setValue, close, value, isOpen }`. `setValue` behaves exactly like
clicking a day: it fires `@onChange` and closes the popover once the value is complete.

```gts preview collapsible
import Component from '@glimmer/component';
import { tracked } from '@glimmer/tracking';
import { fn } from '@ember/helper';
import { Button, DatePicker } from 'frontile';

function startOfToday(): Date {
  const now = new Date();
  return new Date(now.getFullYear(), now.getMonth(), now.getDate());
}

function daysFromToday(days: number): Date {
  const date = startOfToday();
  date.setDate(date.getDate() + days);
  return date;
}

export default class DatePickerPresets extends Component {
  @tracked value: Date | null = null;

  presets = [
    { label: 'Today', date: startOfToday() },
    { label: 'Tomorrow', date: daysFromToday(1) },
    { label: 'In a week', date: daysFromToday(7) }
  ];

  handleChange = (value: Date | null) => {
    this.value = value;
  };

  <template>
    <div class='demo-stack'>
      <DatePicker
        @label='Due date'
        @value={{this.value}}
        @onChange={{this.handleChange}}
      >
        <:footer as |f|>
          {{#each this.presets as |preset|}}
            <Button
              @variant='subtle'
              @color='primary'
              @size='xs'
              @onPress={{fn f.setValue preset.date}}
            >{{preset.label}}</Button>
          {{/each}}

          <Button
            @variant='plain'
            @size='xs'
            @class='ml-auto'
            @onPress={{f.close}}
          >Close</Button>
        </:footer>
      </DatePicker>
    </div>
  </template>
}
```

## Custom Trigger Content

The `:value` block replaces everything the button trigger renders, receiving
`{ value, formatted, isEmpty }`. It describes the `@isEditable={{false}}` path only; an
editable field renders segments and no trigger for the block to fill. Because the block may
render nothing readable — an icon alone, for instance — the trigger is given an explicit
`aria-label` composed from `@label` and the formatted value whenever the block is
supplied.

```gts preview
import { DatePicker } from 'frontile';

const value = new Date(2026, 0, 20);

<template>
  <div class='demo-stack'>
    <DatePicker
      @label='Start date'
      @value={{value}}
      @locale='en-US'
      @isEditable={{false}}
    >
      <:value as |v|>
        {{#if v.isEmpty}}
          <span class='text-neutral-soft'>No date chosen</span>
        {{else}}
          <span class='font-medium'>{{v.formatted}}</span>
        {{/if}}
      </:value>
    </DatePicker>
  </div>
</template>
```

## Formatting

`@formatOptions` is passed to `Intl.DateTimeFormat` alongside `@locale`. On the button
trigger it formats the value for display and defaults to `{ dateStyle: 'medium' }`.

```gts preview collapsible
import { DatePicker } from 'frontile';

const value = new Date(2026, 0, 20);
const full = { dateStyle: 'full' } as const;
const numeric = { day: '2-digit', month: '2-digit', year: 'numeric' } as const;

<template>
  <div class='demo-stack'>
    <div class='grid gap-4 md:grid-cols-3'>
      <DatePicker
        @label='Default'
        @value={{value}}
        @locale='en-US'
        @isEditable={{false}}
      />
      <DatePicker
        @label='Full'
        @value={{value}}
        @locale='en-US'
        @isEditable={{false}}
        @formatOptions={{full}}
      />
      <DatePicker
        @label='Numeric'
        @value={{value}}
        @locale='en-US'
        @isEditable={{false}}
        @formatOptions={{numeric}}
      />
    </div>
  </div>
</template>
```

On the editable field the same argument decides which segments appear and in what order,
and defaults to `{ year: 'numeric', month: '2-digit', day: '2-digit' }` instead — a textual
month has no numeric segment to type into. A filled segment always shows its full width, so
`month: 'numeric'` and `month: '2-digit'` render the same field. A textual `@formatOptions`, including
the `{ dateStyle: 'medium' }` the button trigger defaults to, falls back to a numeric month
and warns; only the month is replaced, so a format naming other fields keeps them. A
`dateStyle` preset names no fields at all and so falls back to the numeric default in full.

```gts preview
import { DatePicker } from 'frontile';

const value = new Date(2026, 0, 5);
const monthAndDay = { month: '2-digit', day: '2-digit' } as const;

<template>
  <div class='grid gap-4 md:grid-cols-2'>
    <DatePicker @label='Default segments' @value={{value}} @locale='en-US' />
    <DatePicker
      @label='Month and day'
      @value={{value}}
      @locale='en-US'
      @formatOptions={{monthAndDay}}
    />
  </div>
</template>
```

## Color

`@color` picks the semantic color the calendar uses for the selected day and,
in range mode, the band between the two ends. It defaults to `primary`.

It colors the calendar only — the field itself is drawn from the form field
styles it shares with every other input, so a picker still looks like the rest
of the form.

```gts preview
import { DatePicker } from 'frontile';
import { array } from '@ember/helper';

const jan20 = new Date(2026, 0, 20);

<template>
  <div class='flex flex-wrap gap-4'>
    {{#each (array 'primary' 'success' 'warning' 'danger') as |color|}}
      <DatePicker
        @label='{{color}}'
        @color={{color}}
        @defaultValue={{jan20}}
        @locale='en-US'
      />
    {{/each}}
  </div>
</template>
```

## Restricting Selectable Dates

`@minValue` and `@maxValue` bound the range of selectable days; `@isDateUnavailable` marks
individual days unselectable within that range, such as weekends or already-booked nights.

```gts preview
import { DatePicker } from 'frontile';

const min = new Date(2026, 0, 1);
const max = new Date(2026, 0, 31);
const defaultValue = new Date(2026, 0, 20);
const isWeekend = (date: Date) => date.getDay() === 0 || date.getDay() === 6;

<template>
  <div class='demo-stack'>
    <DatePicker
      @label='Appointment date'
      @defaultValue={{defaultValue}}
      @locale='en-US'
      @minValue={{min}}
      @maxValue={{max}}
      @isDateUnavailable={{isWeekend}}
    />
  </div>
</template>
```

## Clearable

`@isClearable` adds a clear button once there is a value. It never renders on a disabled or
read-only picker.

On the editable field the clear button sits beside the calendar button, which is the only
way to open the popover there. On the button trigger the two are either/or: the trigger
itself opens the calendar, so the icon is decorative and the clear button takes its place.

```gts preview
import { DatePicker } from 'frontile';

const defaultValue = new Date(2026, 0, 20);

<template>
  <div class='grid gap-4 md:grid-cols-2'>
    <DatePicker
      @label='Editable'
      @defaultValue={{defaultValue}}
      @isClearable={{true}}
    />
    <DatePicker
      @label='Button trigger'
      @isEditable={{false}}
      @placeholder='Pick a date'
      @defaultValue={{defaultValue}}
      @isClearable={{true}}
    />
  </div>
</template>
```

## Forms

Inside a `<Form>`, a `DatePicker` given `@name` submits one field: the wire value is the same
`yyyy-MM-dd` string `@value` accepts. A range picker submits two dotted names,
`{{@name}}.start` and `{{@name}}.end`, which `Form` unflattens into one nested object.

```gts preview
import Component from '@glimmer/component';
import { tracked } from '@glimmer/tracking';
import { Form, DatePicker, type FormResultData } from 'frontile';

export default class DatePickerFormExample extends Component {
  @tracked submitted: FormResultData['data'] | null = null;

  handleSubmit = ({ data }: FormResultData) => {
    this.submitted = data;
  };

  <template>
    <div class='demo-stack'>
      <Form @onSubmit={{this.handleSubmit}}>
        <DatePicker @label='Start date' @name='start' />
        <button type='submit'>Save</button>
      </Form>
      {{#if this.submitted}}
        <p class='text-sm'>Submitted: {{this.submitted.start}}</p>
      {{/if}}
    </div>
  </template>
}
```

`<form.Field>` yields both a bound `DatePicker` and a bound `DateRangePicker` — the same
component, curried to `@mode="range"`. A range field arrives at `onSubmit` as
`{ [name]: { start, end } }`.

```gts preview
import Component from '@glimmer/component';
import { tracked } from '@glimmer/tracking';
import { Form, type FormResultData } from 'frontile';

export default class DateRangePickerFieldExample extends Component {
  @tracked submitted: FormResultData['data'] | null = null;

  handleSubmit = ({ data }: FormResultData) => {
    this.submitted = data;
  };

  <template>
    <div class='demo-stack'>
      <Form @onSubmit={{this.handleSubmit}} as |form|>
        <form.Field @name='stay' as |field|>
          <field.DateRangePicker @label='Stay' @locale='en-US' />
        </form.Field>
        <button type='submit'>Save</button>
      </Form>
      {{#if this.submitted}}
        <p class='text-sm'>
          Submitted: {{this.submitted.stay.start}} – {{this.submitted.stay.end}}
        </p>
      {{/if}}
    </div>
  </template>
}
```

## Anatomy

The field's parts carry `data-part` attributes, and state that CSS can select on:

| Element                         | Attributes                                                                                       |
| ------------------------------- | ------------------------------------------------------------------------------------------------ |
| `[data-part="base"]`            | `data-component="date-picker"`                                                                   |
| `[data-part="inner-container"]` | `data-invalid`, `data-disabled` — on the segmented path this is the element drawing the border, background and focus ring |
| `[data-part="group"]`           | `data-invalid`, `data-readonly`; one per end in range mode                                       |
| `[data-part="segment"]`         | `data-type` (`year`, `month` or `day`), `data-placeholder`, `data-disabled`                      |
| `[data-part="literal"]`         | the separators inside a group                                                                    |
| `[data-part="separator"]`       | between the two groups of an editable range                                                      |
| `[data-part="calendar-button"]` | the button opening the popover, on the segmented path                                            |
| `[data-part="clear-button"]`    | rendered only while `@isClearable` has something to clear                                        |
| `[data-part="input"]`           | the button trigger, under `@isEditable={{false}}`                                                |

`@classes` takes the matching slots, including `group`, `segment`, `literal`, `separator`
and `calendarButton`.

## Accessibility

| Element | What it exposes |
| --- | --- |
| Segment | `role="spinbutton"` with `aria-label` (`month`, `day`, `year`, overridable through `@segmentLabels`), `aria-valuenow`, `aria-valuemin`, `aria-valuemax` and `aria-valuetext` — which is what makes a month announce as "January" rather than "1". Carries the field's `aria-invalid` and `aria-readonly`. |
| Segment group | `role="group"`, named by `@label` and described by `@description` and any feedback. In range mode there are two, named `"<label> start"` and `"<label> end"`. |
| Calendar button | A `<button>` labelled `"Choose date, <label>"`, carrying the `aria-haspopup`, `aria-expanded` and `aria-controls` the popover trigger applies. |
| Trigger | Under `@isEditable={{false}}`, a `<button>` carrying the same popover trigger attributes. When a `:value` block is supplied, it also carries an explicit `aria-label` composed from `@label` and the formatted value, since the block's content may not be readable text on its own. |
| Popover content | `role="dialog"`, labeled by `@label`. |
| Calendar grid | Labeled by the field's own id, so the default calendar is always labelled. A consumer rendering their own calendar from the `:calendar` block must pass `@id` to `DatePicker` for the grid to be labelled — the block's `labelledBy` reflects `@id`, not the id `FormControl` would otherwise generate. |
| Clear button | Announced as "Clear". |

The segments take the same keys as [DateInput](./date-input#accessibility), and every one
of them is a tab stop — three for a single field, six for a range.

`role="group"` supports neither `aria-invalid` nor `aria-readonly` in ARIA 1.2, so the
group carries `data-invalid` and `data-readonly` for styling while the real ARIA sits on
the segments.

A `role="group"` is not a labelable element, so the visible `<label>` does not associate
with the segments through `for`. Each group is named by `aria-label` instead, derived from
`@label`.

Opening the picker moves focus onto the selected (or today's) day inside the grid. `Escape`
closes the calendar and returns focus to the segment that had it — or to the button trigger
— as does completing a selection or clicking outside. `@onBlur` fires only once focus
leaves the whole control — the field and its popover — not on the way into the calendar.

## Testing

The segmented trigger cannot be filled with `fillIn`, which fails silently rather than
throwing. Use `fillDate` (or `fillDateRange` for `@mode="range"`) from
`frontile/test-support`; see [DateInput](./date-input#testing) for the details and the
reason.

```js
import { fillDate, fillDateRange } from 'frontile/test-support';

await fillDate('[data-test-due]', '2026-01-20');
await fillDateRange('[data-test-trip]', '2026-01-20', '2026-01-25');
```

With `@isEditable={{false}}` there is nothing to type into: click the trigger and pick
from the calendar, as before.

## API

### DatePicker

A date field: segments the value can be typed into, a calendar button that
opens a calendar in a popover, and -- under @isEditable={{false}} -- the
older button trigger showing the formatted value instead. @mode="range"
switches both the calendar and the value shape to a { start, end } range,
and -- when editable -- renders two groups of segments with a separator
between them.

**Element:** `HTMLDivElement`

**Arguments**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `captionLayout` | `'label' \| 'dropdown'` | `'label'` | 'label' renders the plain month/year caption; 'dropdown' swaps it for a native month <select> plus a year trigger that opens a year-grid picker. |
| `classes` | `SlotsToClasses<'icon' \| 'base' \| 'innerContainer' \| 'startContent' \| 'endContent' \| 'input' \| 'clearButton' \| 'separator' \| 'placeholder' \| 'group' \| 'footer' \| 'segment' \| 'literal' \| 'calendarButton' \| 'calendar'>` | - |  |
| `closeOnEscapeKey` | `boolean` | `true` | Whether to close when the escape key is pressed |
| `closeOnOutsideClick` | `boolean` | `true` | Whether to close when the area outside (the backdrop) is clicked |
| `color` | `'neutral' \| 'primary' \| 'secondary' \| 'tertiary' \| 'success' \| 'warning' \| 'danger'` | `'primary'` | The color used for the selected day and the range band. |
| `defaultValue` | `DatePickerRangeInput \| DatePickerInput` | - | Seeds the range before any @value is supplied. Seeds the value before any @value is supplied. |
| `description` | `string` | - | Help text rendered between the label and the control, and referenced by the ids describedBy returns. |
| `didClose` | `() => void` | - | Callback when closing has finished, including any exit transition. |
| `disableTransitions` | `boolean` | `false` | Disable css transitions |
| `endContentPointerEvents` | `'none' \| 'auto'` | `'none', or 'auto' when the field is segmented` | Whether the cluster at the end of the field (the calendar icon, or the clear button) receives pointer events. Defaults to 'none' so that a click anywhere in the field -- the icon included -- falls through to the trigger and opens the picker. The clear button opts back in on its own. The segmented path defaults to 'auto' instead: there is no button trigger for a click to fall through to, and the calendar icon is itself the button that opens the popover. |
| `errors` | `string \| string[]` | - | Validation messages for the field. A non-empty value also marks the control invalid, and an array is joined with ;  when displayed. |
| `fixedWeeks` | `boolean` | `false` | Renders six week rows in every month, so the calendar keeps the same height as you page between months of different lengths. |
| `flipOptions` | `{ mainAxis?: boolean; crossAxis?: boolean \| 'alignment'; fallbackPlacements?: Placement[]; fallbackStrategy?: 'bestFit' \| 'initialPlacement'; fallbackAxisSideDirection?: 'start' \| ... 1 more ... \| 'none'; ... 5 more ...; boundary?: Boundary; }` | - | Options for the floating-ui flip middleware, which moves the content to the opposite side when it would overflow the viewport. |
| `formatOptions` | `Object` | `{ dateStyle: 'medium' }` | How the value is rendered in the trigger. Localized with @locale. |
| `id` | `string` | - | The unique identifier for the control. |
| `inputSize` | `'sm' \| 'md' \| 'lg'` | - | The size of the field. Matches Select's @inputSize. |
| `isClearable` | `boolean` | `false` | Whether a clear button replaces the calendar icon when there is a value. |
| `isDateUnavailable` | `(date: Date) => boolean` | - | Marks a date as present but unselectable -- a holiday, a booked night. Distinct from @minValue/@maxValue, which put a date out of range entirely. |
| `isDisabled` | `boolean` | `false` | Whether the field is disabled. FormControl passes this through for styling; the control it wraps is responsible for the disabled attribute. |
| `isEditable` | `boolean` | `true` | Whether the value can be typed into segments. false restores the button trigger showing the formatted value, which is what @placeholder, @formatOptions and the :value block describe. @mode="range" is segmented too: two groups with a separator between them, one for each end of the range. |
| `isInvalid` | `boolean` | `false` | Marks the control invalid without supplying messages, for validation that is reported elsewhere. |
| `isReadOnly` | `boolean` | `false` | Allows paging between months but blocks selecting a day. Unlike @isDisabled, the days stay focusable so the calendar can still be read with the keyboard. |
| `isRequired` | `boolean` | `false` | Whether the field is required. Adds an asterisk to the label; it does not set the required attribute on the control itself. |
| `label` | `string` | - | The label text rendered above the control and associated with it via for. Use the :label block instead when the label needs markup. |
| `locale` | `string` | - | BCP-47 tag. All human-readable text is produced by Intl from this. |
| `maxValue` | `Object` | - | Latest selectable date. Also clamps month navigation. |
| `middleware` | `{ name: string; options?: any; fn: (state: { placement: Placement; strategy: Strategy; x: number; y: number; initialPlacement: Placement; middlewareData: MiddlewareData; rects: ElementRects; platform: { ...; } &#x26; Platform; elements: Elements; }) => Promisable<...>; }[]` | - | Additional floating-ui middleware for the popover positioning the calendar, beyond what placement, offsetOptions, flipOptions, and shiftOptions cover. Forwarded to Popover's own @middleware. |
| `minValue` | `Object` | - | Earliest selectable date. Also clamps month navigation. |
| `mode` | `'single' \| 'range'` | `'single'` | Switches the picker, and the calendar it wraps, to range selection. Selects a single day. Set @mode="range" for a start/end range instead. |
| `name` | `string` | - | The name the value submits under. See the hidden inputs in date-picker.gts. |
| `offsetOptions` | `OffsetOptions` | `5` |  |
| `onBlur` | `() => void` | - | Fires when focus leaves the trigger and the popover. |
| `onChange` | `((value: DateRange) => void) \| ((value: Date) => void)` | - | Fires with the { start, end } range, or null after clearing. Fires with the picked Date, or null after clearing. |
| `placeholder` | `string` | - | Text shown in the trigger when there is no value. |
| `placeholderValue` | `Object` | `today` | Where ArrowUp on an empty segment starts. Only read on the segmented path. |
| `placement` | `'top' \| 'top-start' \| 'top-end' \| 'right' \| 'right-start' \| 'right-end' \| 'bottom' \| 'bottom-start' \| 'bottom-end' \| 'left' \| 'left-start' \| 'left-end'` | `'bottom-start'` | Placement of the menu when open |
| `popoverSize` | `'sm' \| 'md' \| 'lg' \| 'xl' \| 'trigger' \| 'auto'` | `'auto'` | The width of the popover holding the calendar. Defaults to 'auto' -- the calendar's own width is the meaningful one, and it changes with @visibleMonths, so a fixed width would clip the grid. 'trigger' matches the field's width; the named sizes are fixed. |
| `renderInPlace` | `boolean` | `false` | Whether to render in place or in the specified/default destination |
| `segmentLabels` | `Partial<Record<SegmentType, string>>` | `{ year: 'year', month: 'month', day: 'day' }` | The accessible names of the segments, for localizing them. |
| `shiftOptions` | `{ mainAxis?: boolean; crossAxis?: boolean; rootBoundary?: RootBoundary; elementContext?: ElementContext; altBoundary?: boolean; padding?: Padding; limiter?: { ...; }; boundary?: Boundary; }` | - | Options for the floating-ui shift middleware, which nudges the content along its axis to keep it in view. |
| `showOutsideDays` | `boolean` | ``true` when a single month is visible, `false` once `@visibleMonths` is greater than one -- otherwise a boundary date would render twice, once per adjacent grid.` | Whether days from the adjacent month fill out a grid's leading/trailing weeks. |
| `strategy` | `Strategy` | `'absolute'` |  |
| `target` | `string \| Element` | - | The target where to render the portal. There are 3 options: 1) Element object, 2) element id, 3) portal target name. For element id, string must be prefixed with #. If no value is passed in, we will render to the closest unnamed portal target, parent portal or document.body. |
| `transitionDuration` | `number` | `200` | Duration of the animation |
| `value` | `DatePickerRangeInput \| DatePickerInput` | - | A { start, end } pair, each a Date or a yyyy-MM-dd string; end may be null while only the anchor is chosen. Synced the same way as single mode's @value: setting it replaces the displayed range, undefined is ignored, and the field updates on its own as the user picks. A Date, or the same yyyy-MM-dd string this component writes to its hidden input. The field keeps its own selection and syncs from this argument: setting it replaces what is displayed, while picking a date updates the field immediately rather than waiting for @value to come back. undefined is ignored, which is why a <form.Field>-bound picker — which always passes a value key — still honors @defaultValue before form data exists. |
| `visibleMonths` | `number` | `1` | How many months to render side by side, starting from the visible month. |
| `weekStartsOn` | `WeekDay` | - | Overrides the first day of week implied by @locale. |

**Blocks**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `value *` | `[DatePickerValueBlockArg<M>]` | - |  |
| `calendar *` | `[DatePickerCalendarArgs<M>]` | - |  |
| `footer *` | `[DatePickerFooterArg<M>]` | - |  |

---

# Field

Source: /docs/components/forms/field.md

# Field

A component wrapper that provides conveniences for form fields when using built-in validation. It automatically binds the appropriate form errors by name to yielded components, simplifying error handling in validated forms.

**Important:** The Field component is designed specifically for use with the Form component's built-in validation system (`@schema` or `@validate` props). It should only be used when implementing form validation.

`@name` is looked up verbatim in the form's `errors` object and read out of the form data
with Ember's `get`, so dotted paths work — including numeric segments for array elements.
`@name='items.0.name'` picks up an issue whose path is `['items', 0, 'name']`; the index is
part of the key, so `items.0.name` and `items.1.name` never collide, and neither collapses
onto `items.name`.

## Import

```js
import { Form } from 'frontile';
// Field is yielded from Form when using validation
```

## Usage

### Basic Field with Validation

The Field component is yielded from the Form component when validation is configured. It automatically passes validation errors to the appropriate form components.

```gts preview collapsible
import Component from '@glimmer/component';
import { tracked } from '@glimmer/tracking';
import { Form, type FormResultData } from 'frontile';
import { Button } from 'frontile';
import * as v from 'valibot';

// Define validation schema
const schema = v.object({
  email: v.pipe(
    v.string(),
    v.nonEmpty('Email is required'),
    v.email('Please enter a valid email address')
  ),
  username: v.pipe(
    v.string(),
    v.nonEmpty('Username is required'),
    v.minLength(3, 'Username must be at least 3 characters')
  )
});

type Schema = v.InferOutput<typeof schema>;

export default class BasicFieldExample extends Component {
  @tracked formData: Schema = { username: 'rememberme' };

  handleFormChange = (result: FormResultData<Schema>) => {
    this.formData = result.data;
  };

  handleFormSubmit = (result: FormResultData<Schema>) => {
    console.log('Form submitted:', result);
  };

  changeEmail = () => {
    this.formData.email = 'test@test.com';
    this.formData = this.formData;
  };

  <template>
    <div class='demo-stack'>
      <Form
        @data={{this.formData}}
        @schema={{schema}}
        @onChange={{this.handleFormChange}}
        @onSubmit={{this.handleFormSubmit}}
        as |form|
      >
        <div class='flex flex-col gap-4'>
          {{! Field component automatically handles error binding }}
          <form.Field @name='username' as |field|>
            <field.Input @label='Username' @isRequired={{true}} />
          </form.Field>

          <form.Field @name='email' as |field|>
            <field.Input
              @label='Email Address'
              @type='email'
              @isRequired={{true}}
            />
          </form.Field>

          <Button type='submit'>
            Submit
          </Button>

          <Button @onPress={{this.changeEmail}}>Update Email via formData</Button>
        </div>
      </Form>
    </div>
  </template>
}
```

### Field with Multiple Component Types

The Field component yields bound versions of all form components, each automatically receiving the correct errors for its field name.

```gts preview collapsible
import Component from '@glimmer/component';
import { tracked } from '@glimmer/tracking';
import { Form, type FormResultData } from 'frontile';
import { Button } from 'frontile';
import * as v from 'valibot';

const schema = v.object({
  name: v.pipe(v.string(), v.nonEmpty('Name is required')),
  bio: v.pipe(
    v.string(),
    v.nonEmpty('Bio is required'),
    v.minLength(10, 'Bio must be at least 10 characters')
  ),
  accountType: v.pipe(
    v.fallback(v.string(), ''),
    v.string(),
    v.nonEmpty('Please select an account type')
  ),
  newsletter: v.pipe(
    v.boolean(),
    v.literal(true, 'You must subscribe to continue')
  )
});

type Schema = v.InferOutput<typeof schema>;

export default class FieldComponentTypes extends Component {
  @tracked formData: Schema = {
    accountType: 'personal',
    newsletter: true
  };

  accountTypes = [
    { label: 'Personal', key: 'personal' },
    { label: 'Business', key: 'business' },
    { label: 'Enterprise', key: 'enterprise' }
  ];

  handleFormSubmit = (data: FormResultData<Schema>) => {
    console.log('Form submitted:', data);
  };

  <template>
    <div class='demo-stack'>
      <Form
        @data={{this.data}}
        @schema={{schema}}
        @onSubmit={{this.handleFormSubmit}}
        as |form|
      >
        <div class='flex flex-col gap-4'>
          {{! Input field }}
          <form.Field @name='name' as |field|>
            <field.Input @label='Full Name' @isRequired={{true}} />
          </form.Field>

          {{! Textarea field }}
          <form.Field @name='bio' as |field|>
            <field.Textarea
              @label='Biography'
              @description='Tell us about yourself'
              @isRequired={{true}}
              rows='4'
            />
          </form.Field>

          {{! Select field }}
          <form.Field @name='accountType' as |field|>
            <field.SingleSelect
              @label='Account Type'
              @items={{this.accountTypes}}
              @placeholder='Choose account type'
              @allowEmpty={{true}}
              @isRequired={{true}}
            />
          </form.Field>

          {{! Checkbox field }}
          <form.Field @name='newsletter' as |field|>
            <field.Checkbox
              @label='Subscribe to newsletter'
              @isRequired={{true}}
            />
          </form.Field>

          <Button type='submit'>
            Create Account
          </Button>
        </div>
      </Form>
    </div>
  </template>
}
```

### Field with Custom Validation

Use custom validation functions alongside Field components for complex validation logic.

```gts preview collapsible
import Component from '@glimmer/component';
import { tracked } from '@glimmer/tracking';
import { Form, type FormResultData } from 'frontile';
import { Button } from 'frontile';
import * as v from 'valibot';

const schema = v.object({
  password: v.pipe(
    v.string(),
    v.nonEmpty('Password is required'),
    v.minLength(8, 'Password must be at least 8 characters'),
    v.regex(/[A-Z]/, 'Must contain an uppercase letter'),
    v.regex(/[0-9]/, 'Must contain a number')
  ),
  confirmPassword: v.pipe(
    v.string(),
    v.nonEmpty('Please confirm your password')
  )
});

type Schema = v.InferOutput<typeof schema>;

export default class CustomValidationField extends Component {
  // Custom validator for password matching
  customValidator = (data: Schema) => {
    if (data['password'] !== data['confirmPassword']) {
      return [
        {
          message: 'Passwords must match',
          path: [{ key: 'confirmPassword' }]
        }
      ];
    }
  };

  handleFormSubmit = (data: FormResultData<Schema>) => {
    console.log('Form submitted:', data);
  };

  <template>
    <div class='demo-stack'>
      <Form
        @schema={{schema}}
        @validate={{this.customValidator}}
        @onSubmit={{this.handleFormSubmit}}
        as |form|
      >
        <div class='flex flex-col gap-4'>
          <form.Field @name='password' as |field|>
            <field.Input
              @label='Password'
              @type='password'
              @description='Must be 8+ characters with uppercase and number'
              @isRequired={{true}}
            />
          </form.Field>

          <form.Field @name='confirmPassword' as |field|>
            <field.Input
              @label='Confirm Password'
              @type='password'
              @isRequired={{true}}
            />
          </form.Field>

          <Button type='submit'>
            Set Password
          </Button>
        </div>
      </Form>
    </div>
  </template>
}
```

### Field with Radio and Checkbox Groups

`RadioGroup` supports field-level validation (validates on change/blur/input events based on `@validateOn`), while `CheckboxGroup` currently only supports validation on form submit. Both components display validation errors and work with `form.Field`, but only RadioGroup will automatically validate when the user changes their selection before submitting the form.

**Note on Radio Components:** When using individual `field.Radio` components (not within `field.RadioGroup`), you must manually specify the `@value` prop on each radio to identify it uniquely (e.g., `@value="junior"`, `@value="senior"`). The Field component automatically binds the form data to the `@checkedValue` parameter to control which radio is selected. For most use cases, prefer using `field.RadioGroup` which handles this binding automatically.

```gts preview collapsible
import Component from '@glimmer/component';
import { tracked } from '@glimmer/tracking';
import { Form, type FormResultData } from 'frontile';
import { Button } from 'frontile';
import * as v from 'valibot';

const schema = v.object({
  experience: v.pipe(
    v.fallback(v.string(), ''),
    v.string(),
    v.nonEmpty('Please select your experience level')
  ),
  skills: v.pipe(
    v.array(v.string()),
    v.custom((value) => {
      return value.length >= 2;
    }, 'Please select at least 2 skills')
  )
});

type Schema = v.InferOutput<typeof schema>;

export default class FieldWithGroups extends Component {
  handleFormSubmit = (data: FormResultData<Schema>) => {
    console.log('Form submitted:', data);
  };

  <template>
    <div class='demo-stack'>
      <Form @schema={{schema}} @onSubmit={{this.handleFormSubmit}} as |form|>
        <div class='flex flex-col gap-4'>
          {{! RadioGroup field }}
          <form.Field @name='experience' as |field|>
            <field.RadioGroup
              @label='Experience Level'
              @isRequired={{true}}
              as |Radio|
            >
              <Radio @label='Junior (0-2 years)' @value='junior' />
              <Radio @label='Mid-level (3-5 years)' @value='mid' />
              <Radio @label='Senior (6+ years)' @value='senior' />
              <Radio @label='Lead/Principal' @value='lead' />
            </field.RadioGroup>
          </form.Field>

          {{! CheckboxGroup field }}
          <form.Field @name='skills' as |field|>
            <field.CheckboxGroup
              @label='Technical Skills'
              @description='Select at least 2 skills'
              @isRequired={{true}}
              as |Checkbox|
            >
              <Checkbox @label='Frontend Development' value='skill-frontend' />
              <Checkbox @label='Backend Development' value='skill-backend' />
              <Checkbox @label='Mobile Development' value='skill-mobile' />
              <Checkbox @label='DevOps & Infrastructure' value='skill-infra' />
            </field.CheckboxGroup>
          </form.Field>

          <Button type='submit'>
            Submit Application
          </Button>
        </div>
      </Form>
    </div>
  </template>
}
```

### Complex Form with Multiple Fields

Field components used together in a realistic form.

```gts preview collapsible
import Component from '@glimmer/component';
import { tracked } from '@glimmer/tracking';
import { Form, type FormResultData } from 'frontile';
import { Button } from 'frontile';
import * as v from 'valibot';

const schema = v.object({
  // Personal Information
  firstName: v.pipe(
    v.string(),
    v.nonEmpty('First name is required'),
    v.minLength(2, 'Must be at least 2 characters')
  ),
  lastName: v.pipe(
    v.string(),
    v.nonEmpty('Last name is required'),
    v.minLength(2, 'Must be at least 2 characters')
  ),
  email: v.pipe(
    v.string(),
    v.nonEmpty('Email is required'),
    v.email('Please enter a valid email')
  ),
  phone: v.pipe(
    v.string(),
    v.nonEmpty('Phone number is required'),
    v.regex(/^\+?[\d\s-()]+$/, 'Please enter a valid phone number')
  ),

  // Address Information
  country: v.pipe(
    v.fallback(v.string(), ''),
    v.string(),
    v.nonEmpty('Please select a country')
  ),
  bio: v.pipe(
    v.string(),
    v.nonEmpty('Bio is required'),
    v.minLength(20, 'Bio must be at least 20 characters'),
    v.maxLength(500, 'Bio must be less than 500 characters')
  ),

  // Preferences
  contactMethod: v.pipe(
    v.fallback(v.string(), ''),
    v.string(),
    v.nonEmpty('Please select a contact method')
  ),
  notifications: v.pipe(
    v.array(v.string()),
    v.custom((value) => {
      return value.length >= 1;
    }, 'Please select at least 1 notification method')
  ),

  // Legal
  terms: v.pipe(v.boolean(), v.literal(true, 'You must accept the terms')),
  privacy: v.pipe(
    v.boolean(),
    v.literal(true, 'You must accept the privacy policy')
  )
});

type Schema = v.InferOutput<typeof schema>;

export default class CompleteFieldForm extends Component {
  @tracked submitMessage = '';

  countries = [
    { label: 'United States', key: 'us' },
    { label: 'Canada', key: 'ca' },
    { label: 'United Kingdom', key: 'uk' },
    { label: 'Germany', key: 'de' },
    { label: 'France', key: 'fr' }
  ];

  handleFormSubmit = async (data: FormResultData<Schema>) => {
    // Simulate API call
    await new Promise((resolve) => setTimeout(resolve, 1500));
    this.submitMessage = 'Registration completed successfully!';
    console.log('Form submitted:', data);
  };

  <template>
    <div class='demo-stack'>
      <Form @schema={{schema}} @onSubmit={{this.handleFormSubmit}} as |form|>
        <div class='flex flex-col gap-6'>
          {{! Personal Information Section }}
          <div class='border-b border-neutral-subtle pb-6'>
            <h3 class='text-lg font-medium mb-4'>Personal Information</h3>

            <div class='grid grid-cols-2 gap-4'>
              <form.Field @name='firstName' as |field|>
                <field.Input @label='First Name' @isRequired={{true}} />
              </form.Field>

              <form.Field @name='lastName' as |field|>
                <field.Input @label='Last Name' @isRequired={{true}} />
              </form.Field>
            </div>

            <div class='mt-4 space-y-4'>
              <form.Field @name='email' as |field|>
                <field.Input
                  @label='Email Address'
                  @type='email'
                  @isRequired={{true}}
                />
              </form.Field>

              <form.Field @name='phone' as |field|>
                <field.Input
                  @label='Phone Number'
                  @type='tel'
                  @isRequired={{true}}
                />
              </form.Field>

              <form.Field @name='country' as |field|>
                <field.SingleSelect
                  @label='Country'
                  @items={{this.countries}}
                  @placeholder='Select your country'
                  @allowEmpty={{true}}
                  @isRequired={{true}}
                />
              </form.Field>

              <form.Field @name='bio' as |field|>
                <field.Textarea
                  @label='Bio'
                  @description='Tell us about yourself (20-500 characters)'
                  @isRequired={{true}}
                  rows='4'
                />
              </form.Field>
            </div>
          </div>

          {{! Communication Preferences Section }}
          <div class='border-b border-neutral-subtle pb-6'>
            <h3 class='text-lg font-medium mb-4'>Communication Preferences</h3>

            <form.Field @name='contactMethod' as |field|>
              <field.RadioGroup
                @label='Preferred Contact Method'
                @isRequired={{true}}
                as |Radio|
              >
                <Radio @label='Email' @value='email' />
                <Radio @label='Phone' @value='phone' />
                <Radio @label='SMS' @value='sms' />
              </field.RadioGroup>
            </form.Field>

            <form.Field @name='notifications' as |field|>
              <field.CheckboxGroup
                @label='Notification Preferences'
                @description='Choose how you want to receive updates'
                as |Checkbox|
              >
                <Checkbox @label='Email notifications' value='email' />
                <Checkbox @label='SMS notifications' value='sms' />
                <Checkbox @label='Push notifications' value='push' />
              </field.CheckboxGroup>
            </form.Field>
          </div>

          {{! Legal Section }}
          <div>
            <h3 class='text-lg font-medium mb-4'>Legal Agreements</h3>

            <div class='space-y-4'>
              <form.Field @name='terms' as |field|>
                <field.Checkbox
                  @label='I accept the Terms and Conditions'
                  @description='You must accept our terms to create an account'
                  @isRequired={{true}}
                />
              </form.Field>

              <form.Field @name='privacy' as |field|>
                <field.Checkbox
                  @label='I accept the Privacy Policy'
                  @description='You must accept our privacy policy to create an account'
                  @isRequired={{true}}
                />
              </form.Field>
            </div>
          </div>

          <Button type='submit' disabled={{form.isLoading}}>
            {{if form.isLoading 'Creating Account...' 'Create Account'}}
          </Button>
        </div>
      </Form>

      {{#if this.submitMessage}}
        <div class='mt-4 p-4 bg-success-subtle text-success-strong rounded'>
          {{this.submitMessage}}
        </div>
      {{/if}}
    </div>
  </template>
}
```

## Select Components with Field

When using select components **outside of `Field`**, you use the generic `Select` component. Rendering of single vs. multi is handled by `Select`.

However, when using select components **with `Field`**, you must explicitly specify which variant you need:

- **`field.SingleSelect`** - For selecting a single item
- **`field.MultiSelect`** - For selecting multiple items

`DatePicker` splits the same way, and for the same reason — `field.DatePicker` picks one
date, `field.DateRangePicker` picks a `{ start, end }` range:

```gjs
<form.Field @name='stay' as |field|>
  <field.DateRangePicker @label='Stay' />
</form.Field>
```

A range submits two dotted names, `stay.start` and `stay.end`, which `Form` unflattens into a
single `{ stay: { start, end } }`.

This distinction allows the Field component to properly bind values to the components.

### Field Select (with validation)

```gts
{{! Must specify SingleSelect or MultiSelect explicitly }}
<form.Field @name='country' as |field|>
  <field.SingleSelect
    @label='Country'
    @items={{this.countries}}
    @allowEmpty={{true}}
  />
</form.Field>

<form.Field @name='languages' as |field|>
  <field.MultiSelect
    @label='Languages'
    @items={{this.languages}}
  />
</form.Field>
```

**Key Differences:**

- With Field: Use `field.SingleSelect` or `field.MultiSelect`
- Field automatically handles value binding based on the component type

## Automatic Error Binding

The Field component automatically:

- Extracts errors for the specified field name from the form's validation errors
- Passes these errors to any yielded form component
- Updates error display in real-time as validation occurs

## Automatic Value Binding

When used with a Form component that provides `@data`, Field automatically binds values to form controls:

- Extracts the current value for the field from `form.data`
- Passes the appropriate value prop to each component type
- Provides a no-op change handler, which puts the component in controlled mode so that
  form-level `@onChange` handles every update

**Example:**

```gts
<Form @data={{this.formData}} @onChange={{this.handleChange}} as |form|>
  <form.Field @name="email" as |field|>
    {{! Value automatically bound from formData.email }}
    {{! onChange automatically handled by Form }}
    <field.Input @label="Email" />
  </form.Field>
</Form>
```

## Field-Level Validation

When the Form component's `@validateOn` argument includes `'change'` or `'input'` (defaults to `['change', 'submit']`), Field automatically validates individual fields as users interact with them. This provides feedback without waiting for form submission.

**Change Validation (`'change'`)**

Validates when a field loses focus (blur) after being modified, so errors appear once the
user has moved on to the next field.

**Note:** The `'change'` option validates on the HTML `change` event, which fires when a field loses focus (blur) after its value has been modified. It does NOT fire on every keystroke.

**Input Validation (`'input'`)**

Validates as the user types, so errors appear and clear on every keystroke.

**Note:** The `'input'` option validates on the HTML `input` event, which fires on every keystroke as the user types. This provides immediate feedback but may be distracting for some use cases.

**Example with change validation enabled (default):**

```gts
import * as v from 'valibot';

const schema = v.object({
  email: v.pipe(v.string(), v.email('Please enter a valid email address'))
});

<template>
  <Form @schema={{schema}} @onSubmit={{this.handleSubmit}} as |form|>
    {{! Change validation is enabled by default }}
    {{! Email field validates when user blurs/defocuses after changing value }}
    <form.Field @name='email' as |field|>
      <field.Input @label='Email' />
    </form.Field>
  </Form>
</template>
```

**Example with input validation enabled:**

```gts
import * as v from 'valibot';

const schema = v.object({
  password: v.pipe(
    v.string(),
    v.minLength(8, 'Password must be at least 8 characters')
  )
});

<template>
  <Form
    @schema={{schema}}
    @validateOn={{array 'input' 'submit'}}
    @onSubmit={{this.handleSubmit}}
    as |form|
  >
    {{! Input validation is enabled }}
    {{! Password field validates as user types }}
    <form.Field @name='password' as |field|>
      <field.Input @label='Password' @type='password' />
    </form.Field>
  </Form>
</template>
```

**Example with change validation disabled:**

```gts
<template>
  <Form
    @schema={{schema}}
    @validateOn={{array 'submit'}}
    @onSubmit={{this.handleSubmit}}
    as |form|
  >
    {{! Change validation is disabled }}
    {{! Email field only validates on form submit }}
    <form.Field @name='email' as |field|>
      <field.Input @label='Email' />
    </form.Field>
  </Form>
</template>
```

**When to use input validation:**

- Password fields with strength requirements
- Fields with character limits or specific format requirements
- Username fields that check availability
- Fields where immediate feedback improves the user experience

**When to disable field-level validation:**

- Long forms where validation on every interaction might be distracting
- Forms where you want to allow incomplete data entry until final submission
- Multi-step forms where validation should only run at specific steps

**Overriding validation timing per field:**

Individual Fields can override the Form's `@validateOn` setting to customize when that specific field validates:

```gts
<template>
  <Form @validateOn={{array 'submit'}} as |form|>
    <form.Field @name='username' as |field|>
      {{! Inherits Form's validateOn - validates on submit only }}
      <field.Input />
    </form.Field>

    <form.Field @name='password' @validateOn={{array 'input'}} as |field|>
      {{! Overrides to validate as user types }}
      <field.Input @type='password' />
    </form.Field>
  </Form>
</template>
```

**Important notes:**

- Field-level validation (`'change'` or `'input'`) requires using `form.Field` components
- The Field component automatically handles the validation logic
- Both `@schema` and `@validate` custom validators work with field-level validation
- Field-level validation uses the same validation rules as submit validation
- The `'change'` event fires when a field loses focus (blur) after being modified, not on every keystroke
- The `'input'` event fires on every keystroke as the user types
- Input validation may trigger many validation calls, so consider performance for complex validation logic

## Anatomy

Field yields bound versions of all form components:

- `field.Input` - Text input with automatic error and value binding
- `field.Textarea` - Textarea with automatic error and value binding
- `field.SingleSelect` - Select dropdown with automatic error and selectedKey binding
- `field.MultiSelect` - Select dropdown with automatic error and selectedKeys binding
- `field.DatePicker` - Date picker with automatic error and value binding
- `field.DateRangePicker` - Date picker in range mode; the field arrives as `{ start, end }`
- `field.Checkbox` - Single checkbox with automatic error and checked binding
- `field.CheckboxGroup` - Checkbox group with automatic error binding
- `field.RadioGroup` - Radio group with automatic error and value binding
- `field.Switch` - Toggle switch with automatic error and isSelected binding
- `field.Radio` - Individual radio button with automatic error and checkedValue binding (requires manual `@value` for each radio's unique identifier)

Each component automatically receives:

- The `@name` prop from the Field
- Any validation errors for that field name
- The current value from form data (if provided)
- A controlled change handler (when form data is provided)
- All other props passed through normally

## When to Use Field

**Use the Field component when:**

- You're implementing form validation with `@schema` or `@validate`
- You want automatic error handling for form fields
- You need consistent error binding across multiple form components
- You're building forms with complex validation requirements

**Don't use the Field component when:**

- You're building simple forms without validation
- You want direct control over error handling
- You're not using the Form component's validation features

## Matching Schema and Field Names

Ensure field names match between your validation schema and Field components:

```typescript
// Schema definition
schema = v.object({
  userEmail: v.string().email(), // Field name: 'userEmail'
});

// Field usage
<form.Field @name='userEmail' as |field|> {{! Must match schema }}
  <field.Input @label='Email' />
</form.Field>
```

## Select Fields in Validated Forms

**Important:** When working with select fields in validated forms, follow these guidelines:

1. **Schema Definition**: Always use `v.fallback(v.string(), '')` before `v.string()` to ensure null values are normalized to empty strings:

```typescript
// Correct schema for select fields
schema = v.object({
  country: v.pipe(
    v.fallback(v.string(), ''), // Normalize null to empty string
    v.string(),
    v.nonEmpty('Please select a country')
  )
});
```

2. **Component Configuration**: Specify `@allowEmpty={{true}}` on the Select component when there is no initial value:

```handlebars
<form.Field @name='country' as |field|>
  <field.SingleSelect
    @label='Country'
    @items={{this.countries}}
    @placeholder='Select a country'
    @allowEmpty={{true}}
    {{! Important when no initial value }}
    @isRequired={{true}}
  />
</form.Field>
```

These patterns ensure proper handling of select field validation, especially when fields start without a selected value.

### Blur validation on selects

With `blur` in `@validateOn`, a select-shaped field validates when focus leaves the
**whole control** — the field and its dropdown. Picking an option is not a blur, even
though the trigger does lose focus to the option: in `@selectionMode="multiple"` the
dropdown stays open, and errors like "select at least three" would otherwise appear while
the user is still on their first choice. `SingleSelect`, `MultipleSelect` and
`Autocomplete` all report blur this way, once focus has actually landed outside.

## Where Errors Appear

Field components automatically display errors, but you can customize the display:

```gts
<form.Field @name='email' as |field|>
  <field.Input
    @label='Email'
    @description='We will never share your email'
    {{! Errors appear automatically below the input }}
  />
</form.Field>
```

## Accessibility

Field itself renders no markup and sets no attributes — it binds `errors` down to the
control it yields, and the control's `FormControl` wrapper does the rest. So the behavior
below comes from the wrapped component, and holds for `field.Input`, `field.Select`,
`field.Checkbox`, `field.Textarea` and the rest alike:

| Behavior                                                               | Where it comes from                                                             |
| ---------------------------------------------------------------------- | ------------------------------------------------------------------------------- |
| `aria-invalid` on the control when the field has errors                | `FormControl`, from the bound `errors`                                          |
| `aria-describedby` linking the control to its description and feedback | `FormControl.describedBy`                                                       |
| Errors announced as they appear                                        | `FormFeedback` renders `aria-live="assertive"` for errors, `"polite"` otherwise |
| Label associated via `for`                                             | `FormControl` + `Label`                                                         |

Two consequences. Because error feedback is `aria-live="assertive"`, a form
using `@validateOn={{array "input"}}` interrupts a screen reader on **every keystroke** —
prefer `change` or `blur` for validation a user hears. And because the announcement is tied
to the feedback element rather than the control, a field whose errors you render yourself,
outside `FormControl`, gets no announcement at all.

## API

### Field

Field is a component wrapper that provides conveniences for form fields.
It automatically binds the appropriate form errors by name to yielded
components.

**Element:** `HTMLElement`

**Arguments**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `name *` | `string` | - | The name of the form field. |
| `disabled` | `boolean` | - | Whether the field should be disabled. |
| `errors` | `FormErrors` | - | The validation errors for the form, keyed by field name. |
| `formData` | `T` | - | The form data as key/value pairs. |
| `validateField` | `(data: T, name: string) => Promise<FormErrors>` | - | Function to validate a single field by name. |
| `validateOn` | `('input' \| 'blur' \| 'change')[]` | - | When to run validation. |

**Blocks**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `default *` | `[{ Checkbox: Checkbox (name, errors, checked, onChange, onBlur, isDisabled bound); CheckboxGroup: CheckboxGroup (name, errors, isDisabled bound); Input: Input (name, errors, value, onChange, onInput, onBlur, isDisabled bound); InputOtp: InputOtp (name, errors, value, onChange, onInput, onBlur, isDisabled bound); Radio: Radio (name, errors, checkedValue, onChange, onBlur, isDisabled bound); RadioGroup: RadioGroup (name, errors, value, onChange, isDisabled bound); SingleSelect: Select<S> (name, errors, selectedKey, onBlur, isDisabled bound); MultiSelect: Select<S> (selectionMode, name, errors, selectedKeys, onBlur, isDisabled bound); DatePicker: DatePicker<'single'> (name, errors, value, onBlur, isDisabled bound); DateRangePicker: DatePicker<'range'> (mode, name, errors, value, onBlur, isDisabled bound); DateInput: DateInput (name, errors, value, onBlur, isDisabled bound); Switch: Switch (name, errors, isSelected, onChange, onBlur, isDisabled bound); Textarea: Textarea (name, errors, value, onChange, onInput, onBlur, isDisabled bound); }]` | - |  |

---

# FormControl

Source: /docs/components/forms/form-control.md

# FormControl

FormControl provides the label, description and error feedback that surround a form
control, and the ids that tie them together for assistive technology. Reach for it when
you need a field Frontile doesn't ship — a file picker, a range slider, a third-party
date picker — and want it to look and announce itself like `Input`, `Select` and
`Checkbox`, which are all built on it.

## Import

```js
import { FormControl } from 'frontile';
```

## Usage

Pass `@label` and give the wrapped control the yielded `id`. That single wiring is what
associates the rendered `<label>` with your control.

```gts preview
import { FormControl } from 'frontile';

<template>
  <div class='demo-stack'>
    <FormControl @label='Attachment' as |c|>
      <input
        type='file'
        id={{c.id}}
        class='text-neutral-strong font-body text-base'
      />
    </FormControl>
  </div>
</template>
```

## Description and Errors

`@description` renders help text above the control and `@errors` renders messages below
it. Neither is connected to the control on its own: the block is responsible for the
ARIA, using the two values FormControl yields for exactly that.

- `c.describedBy` takes two flags — whether there is a description, and whether there is
  feedback — and returns the matching ids for `aria-describedby`.
- `c.isInvalid` is true when `@isInvalid` is set or `@errors` is non-empty, and is what
  you put on `aria-invalid`.

```gts preview
import { FormControl } from 'frontile';

<template>
  <div class='demo-stack'>
    <FormControl
      @label='Budget'
      @description='Whole dollars, no separators.'
      @errors='Enter an amount above 0'
      as |c|
    >
      <input
        type='number'
        id={{c.id}}
        value='0'
        aria-invalid={{if c.isInvalid 'true'}}
        aria-describedby={{c.describedBy true c.isInvalid}}
        class='bg-surface-input text-neutral-strong border-neutral-soft aria-invalid:border-danger focus:ring-focus aria-invalid:focus:ring-danger-muted w-full rounded-xl border p-3 leading-tight focus:ring-3 focus:outline-hidden'
      />
    </FormControl>
  </div>
</template>
```

## Placing the Parts Yourself

The default order — label, description, control, feedback — is what you get from the
string arguments. When a control needs a different order, such as a checkbox whose label
sits after it, use the yielded `Label`, `Description` and `Feedback` components instead
and drop the corresponding argument. They arrive with `for`, `id`, `size` and (for
`Feedback`) the error messages already bound.

`@preventErrorFeedback` suppresses the automatic feedback at the bottom so `c.Feedback`
is the only copy rendered.

Either way, FormControl also renders a visually hidden `aria-live='assertive'` region that
is always in the DOM and holds the error messages when there are any. That region is what
screen readers announce, so the visible `FormFeedback` inside a FormControl is rendered with
`@announce={{false}}` and the message is not announced twice. `@preventErrorFeedback` does
not remove the live region.

Because that region only ever carries the `@errors` text, `c.Feedback` with its own block
content announces nothing. When you render custom content there and want it announced, turn
announcing back on for that invocation with `@announce={{true}}` — an argument passed at the
invocation site wins over the one FormControl bound.

```gts preview
import { FormControl } from 'frontile';

<template>
  <div class='demo-stack'>
    <FormControl
      @errors='Accept the terms to continue'
      @preventErrorFeedback={{true}}
      as |c|
    >
      <c.Feedback />
      <div class='flex items-center gap-2'>
        <input
          type='checkbox'
          id={{c.id}}
          aria-invalid={{if c.isInvalid 'true'}}
          aria-describedby={{c.describedBy false c.isInvalid}}
        />
        <c.Label>I accept the terms</c.Label>
      </div>
    </FormControl>
  </div>
</template>
```

When the label itself needs markup rather than a plain string, use the `:label` block —
it renders inside the same `<label>` element that `@label` would have produced.

```gts preview
import { FormControl } from 'frontile';

<template>
  <div class='demo-stack'>
    <FormControl @isRequired={{true}}>
      <:label>
        API token
        <a href='#docs' class='text-primary underline'>Where do I find this?</a>
      </:label>
      <:default as |c|>
        <input
          id={{c.id}}
          required
          class='bg-surface-input text-neutral-strong border-neutral-soft focus:ring-focus w-full rounded-xl border p-3 leading-tight focus:ring-3 focus:outline-hidden'
        />
      </:default>
    </FormControl>
  </div>
</template>
```

`:description` works the same way, for help text that needs a link or inline markup. It
renders inside the same description element that `@description` would have produced, so
`c.describedBy` still points the control at it.

```gts preview
import { FormControl } from 'frontile';

<template>
  <div class='demo-stack'>
    <FormControl @label='Webhook URL'>
      <:description>
        Must be publicly reachable over HTTPS.
        <a href='#docs' class='text-primary underline'>Read the requirements</a>
      </:description>
      <:default as |c|>
        <input
          id={{c.id}}
          aria-describedby={{c.describedBy true false}}
          class='bg-surface-input text-neutral-strong border-neutral-soft focus:ring-focus w-full rounded-xl border p-3 leading-tight focus:ring-3 focus:outline-hidden'
        />
      </:default>
    </FormControl>
  </div>
</template>
```

## Sizes

`@size` scales the label, description and feedback text. It does not touch the control
inside the block — size that yourself so the two stay in proportion.

```gts preview
import { array } from '@ember/helper';
import { FormControl } from 'frontile';

<template>
  <div class='demo-stack'>
    {{#each (array 'sm' 'md' 'lg') as |size|}}
      <FormControl
        @size={{size}}
        @label='Team name'
        @description='Shown to everyone in the workspace.'
        @errors='This name is taken'
        as |c|
      >
        <input
          id={{c.id}}
          value='Platform'
          aria-invalid='true'
          aria-describedby={{c.describedBy true true}}
          class='bg-surface-input text-neutral-strong border-neutral-soft aria-invalid:border-danger focus:ring-focus aria-invalid:focus:ring-danger-muted w-full rounded-xl border p-3 leading-tight focus:ring-3 focus:outline-hidden'
        />
      </FormControl>
    {{/each}}
  </div>
</template>
```

## Accessibility

FormControl renders a plain `<div>` and has no keyboard behavior of its own — the control
you place inside it keeps whatever behavior it already had. What FormControl does is hand
you the pieces needed to describe that control correctly, and it is the block's job to
apply them:

| Yielded value   | Where it goes                                                                                 |
| --------------- | --------------------------------------------------------------------------------------------- |
| `c.id`          | The control's `id`. The rendered `<label>` already points at it with `for`                    |
| `c.isInvalid`   | `aria-invalid` on the control                                                                 |
| `c.describedBy` | `aria-describedby` on the control, called with whether a description and feedback are present |

Notes before you rely on it:

- **Required is visual.** `@isRequired` adds an asterisk to the label. Set `required` or
  `aria-required` on the control yourself.
- **Disabled is visual.** `@isDisabled` is passed through for styling only; the control
  owns its own `disabled` attribute.
- **Error feedback is announced.** The feedback element carries `aria-live`, assertive at
  the default `danger` status and polite otherwise, so messages appearing after the
  initial render are read out.
- **It groups nothing.** There is no `role='group'` and the label's `for` can only point
  at one control, so wrapping several inputs in a single FormControl leaves them
  unlabelled. Use `CheckboxGroup` or `RadioGroup`, or add `role='group'` and
  `aria-labelledby` yourself.

## API

### FormControl

**Element:** `HTMLDivElement`

**Arguments**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `class` | `string` | - | Class names for the wrapping element. |
| `description` | `string` | - | Help text rendered between the label and the control, and referenced by the ids describedBy returns. |
| `errors` | `string \| string[]` | - | Validation messages for the field. A non-empty value also marks the control invalid, and an array is joined with ;  when displayed. |
| `id` | `string` | - | The id given to the control, and the base for the description and feedback ids. Generated when omitted, so pass one only when something outside the block has to reference it. |
| `isDisabled` | `boolean` | `false` | Whether the field is disabled. FormControl passes this through for styling; the control it wraps is responsible for the disabled attribute. |
| `isInvalid` | `boolean` | `false` | Marks the control invalid without supplying messages, for validation that is reported elsewhere. |
| `isRequired` | `boolean` | `false` | Whether the field is required. Adds an asterisk to the label; it does not set the required attribute on the control itself. |
| `label` | `string` | - | The label text rendered above the control and associated with it via for. Use the :label block instead when the label needs markup. |
| `preventErrorFeedback` | `boolean` | `false` | Suppresses the automatic error feedback, for when the block renders the yielded Feedback itself or places messages elsewhere. |
| `size` | `'sm' \| 'md' \| 'lg'` | `'md'` | The size of the label, description and feedback text. |

**Blocks**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `default *` | `[{ id: string; isInvalid: boolean; describedBy: (hasDescription?: string \| boolean, hasFeedback?: string \| boolean) => string \| undefined; Label: Label (for, size, isRequired bound); Description: FormDescription (id, size bound); Feedback: FormFeedback (id, size, messages, status bound); }]` | - |  |
| `label *` | `[]` | - |  |
| `description *` | `[]` | - |  |

### Label

**Element:** `HTMLLabelElement`

**Arguments**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `class` | `string` | - | The class name to be passed to the label base slot. |
| `classes` | `SlotsToClasses<'base' \| 'asterisk'>` | - | Class names for each slot of the component, merged with the theme's. |
| `for` | `string` | - | The 'for' attribute of a . |
| `isRequired` | `boolean` | `false` | Whether the field is required or not, if true, an asterisk will be added to the label. |
| `size` | `'sm' \| 'md' \| 'lg'` | `'md'` | The size of the label text. |

**Blocks**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `default *` | `[]` | - |  |

### FormDescription

**Element:** `HTMLDivElement`

**Arguments**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `class` | `string` | - | Class names for the description element, merged with the theme's. |
| `id` | `string` | - | The id of the description element, referenced by the control's aria-describedby. |
| `size` | `'sm' \| 'md' \| 'lg'` | `'md'` | The size of the description text. |

**Blocks**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `default *` | `[]` | - |  |

### FormFeedback

**Element:** `HTMLDivElement`

**Arguments**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `announce` | `boolean` | `true` | Whether the element is itself an aria-live region. Set this to false when something else (such as FormControl, which keeps a persistent live region in the DOM) already announces the messages, so they are not announced twice. |
| `class` | `string` | - | Class names for the feedback element, merged with the theme's. |
| `id` | `string` | - | The id of the feedback element, referenced by the control's aria-describedby. |
| `intent` | `'primary' \| 'secondary' \| 'tertiary' \| 'success' \| 'warning' \| 'danger'` | - | **Deprecated.** Use `status`. The name changed because this value also decides whether the message is announced assertively. |
| `messages` | `string \| string[]` | - | A list of messages or a single message string. An array is joined with ; . |
| `size` | `'sm' \| 'md' \| 'lg'` | `'md'` | The size of the feedback text. |
| `status` | `'primary' \| 'secondary' \| 'tertiary' \| 'success' \| 'warning' \| 'danger'` | `'danger'` | The status of the feedback, which also decides whether it is announced assertively (danger) or politely. |

**Blocks**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `default *` | `[]` | - |  |

---

# Form

Source: /docs/components/forms/form.md

# Form

Form wraps a native `<form>` element, serializes its fields with `form-data-utils`, and hands
the result to `@onChange` on every change and `@onSubmit` on submission. Through the yielded
`Field` component it also runs validation and tracks which fields the user has modified.

## Import

```js
import { Form } from 'frontile';
```

## Usage

Give every control a `@name` and Form collects it. `@onSubmit` is the only required argument;
it receives the serialized data and the `SubmitEvent`, with `preventDefault()` already applied.

```gts preview collapsible
import Component from '@glimmer/component';
import { tracked } from '@glimmer/tracking';
import { Button, Form, Input, type FormResultData } from 'frontile';

export default class SimpleForm extends Component {
  @tracked submitted: FormResultData | null = null;

  handleSubmit = (data: FormResultData) => {
    this.submitted = data;
  };

  <template>
    <div class='demo-stack'>
      <Form @onSubmit={{this.handleSubmit}}>
        <div class='flex flex-col gap-4'>
          <Input @name='firstName' @label='First Name' />
          <Input @name='email' @label='Email' @type='email' />
          <Button type='submit'>Submit</Button>
        </div>
      </Form>

      {{#if this.submitted}}
        <pre class='p-4 bg-neutral-subtle rounded text-sm'>{{JSON.stringify
            this.submitted.data
            null
            2
          }}</pre>
      {{/if}}
    </div>
  </template>
}
```

## Anatomy

`Form` wraps the native form and yields `form.Field` when validation-aware binding is needed.
Each Field then yields bound Input, Textarea, Select, Checkbox, Radio, and Switch variants.

## Controlled and Uncontrolled Forms

Passing `@onChange` makes the form controlled: you own the state, and the data you assign back
to `@data` flows into the inputs. Reach for it when you need the values as they are typed —
live previews, dependent fields, computed summaries.

Without `@onChange` the form is uncontrolled. `@data` seeds the initial values, Form keeps the
current values internally, and you only see them in `@onSubmit`. Both patterns support
`@schema` and `@validate`.

```gts preview collapsible
import Component from '@glimmer/component';
import { tracked } from '@glimmer/tracking';
import { Form, Input, Select, type FormResultData } from 'frontile';
import { Button } from 'frontile';

export default class BasicForm extends Component {
  @tracked formData: FormResultData = {};
  @tracked submittedData: FormResultData = {};
  @tracked selectedCountry: string | null = null;

  countries = [
    { label: 'United States', key: 'us' },
    { label: 'Canada', key: 'ca' },
    { label: 'United Kingdom', key: 'uk' },
    { label: 'Australia', key: 'au' }
  ];

  handleFormChange = (data: FormResultData, event: Event) => {
    this.formData = data;
    console.log('Form input:', { data, event });
  };

  handleFormSubmit = (data: FormResultData, event: SubmitEvent) => {
    this.submittedData = data;
    console.log('Form submit:', { data, event });
  };

  handleCountryChange = (selectedKey: string | null) => {
    this.selectedCountry = selectedKey;
  };

  <template>
    <div class='demo-stack'>
      <Form
        @onChange={{this.handleFormChange}}
        @onSubmit={{this.handleFormSubmit}}
      >
        <div class='flex flex-col gap-4'>
          <Input @name='firstName' @label='First Name' />
          <Input @name='lastName' @label='Last Name' />
          <Input @name='email' @label='Email' @type='email' />

          <Select
            @name='country'
            @label='Country'
            @items={{this.countries}}
            @placeholder='Select your country'
            @selectedKey={{this.selectedCountry}}
            @onSelectionChange={{this.handleCountryChange}}
          />

          <Button type='submit'>
            Submit
          </Button>
        </div>
      </Form>

      <div class='grid gap-4'>
        <div class='p-4 bg-neutral-subtle rounded'>
          <h4 class='font-medium mb-2'>Current Form Data:</h4>
          <pre class='text-sm'>{{JSON.stringify this.formData null 2}}</pre>
        </div>

        <div class='p-4 bg-success-subtle rounded'>
          <h4 class='font-medium mb-2'>Last Submitted Data:</h4>
          <pre class='text-sm'>{{JSON.stringify
              this.submittedData
              null
              2
            }}</pre>
        </div>
      </div>
    </div>
  </template>
}
```

## Form Components

Every Frontile form component participates, as do plain HTML form elements. Data types follow
the markup: text inputs give strings, checkboxes and switches booleans, multi-selects arrays,
file inputs `File` objects.

```gts preview collapsible
import Component from '@glimmer/component';
import { tracked } from '@glimmer/tracking';
import {
  Form,
  Input,
  Textarea,
  Checkbox,
  CheckboxGroup,
  RadioGroup,
  NativeSelect,
  Select,
  type FormResultData
} from 'frontile';
import { Button } from 'frontile';

export default class ComprehensiveForm extends Component {
  @tracked formData: FormResultData = {};
  @tracked lastEventType = '';
  @tracked selectedSkillLevel: string | null = null;

  countries = [
    'United States',
    'Canada',
    'United Kingdom',
    'Australia',
    'Germany'
  ];

  skillLevels = [
    { label: 'Beginner (0-1 years)', key: 'beginner' },
    { label: 'Intermediate (2-5 years)', key: 'intermediate' },
    { label: 'Advanced (5+ years)', key: 'advanced' },
    { label: 'Expert (10+ years)', key: 'expert' }
  ];

  handleFormChange = (data: FormResultData, event: Event) => {
    this.formData = data;
    this.lastEventType = 'input';
    console.log('Form input:', { data, event });
  };

  handleFormSubmit = (data: FormResultData, event: SubmitEvent) => {
    this.formData = data;
    this.lastEventType = 'submit';
    console.log('Form submit:', { data, event });
  };

  handleSkillLevelChange = (selectedKey: string | null) => {
    this.selectedSkillLevel = selectedKey;
  };

  <template>
    <div class='demo-stack'>
      <Form
        @onChange={{this.handleFormChange}}
        @onSubmit={{this.handleFormSubmit}}
      >
        <div class='flex flex-col gap-4'>

          <div class='grid grid-cols-1 md:grid-cols-2 gap-4'>
            <Input @name='firstName' @label='First Name' />
            <Input @name='lastName' @label='Last Name' />
          </div>

          <Input @name='email' @label='Email Address' @type='email' />

          <Textarea
            @name='bio'
            @label='Biography'
            @description='Tell us about yourself'
            rows='4'
          />

          <NativeSelect
            @name='country'
            @label='Country'
            @items={{this.countries}}
            @placeholder='Select a country'
          />

          <Select
            @name='skillLevel'
            @label='Skill Level'
            @items={{this.skillLevels}}
            @placeholder='Select your skill level'
            @selectedKey={{this.selectedSkillLevel}}
            @onSelectionChange={{this.handleSkillLevelChange}}
          />

          <RadioGroup @name='experience' @label='Experience Level' as |Radio|>
            <Radio @label='Beginner' @value='beginner' />
            <Radio @label='Intermediate' @value='intermediate' />
            <Radio @label='Advanced' @value='advanced' />
          </RadioGroup>

          <CheckboxGroup
            @name='interests'
            @label='Areas of Interest'
            as |Checkbox|
          >
            <Checkbox @name='frontend' @label='Frontend Development' />
            <Checkbox @name='backend' @label='Backend Development' />
            <Checkbox @name='mobile' @label='Mobile Development' />
            <Checkbox @name='design' @label='UI/UX Design' />
          </CheckboxGroup>

          <div class='flex items-center gap-4'>
            <Checkbox @name='subscribe' @label='Subscribe to newsletter' />
            <Checkbox
              @name='terms'
              @label='I agree to the terms and conditions'
            />
          </div>

          <Button type='submit'>
            Submit Application
          </Button>
        </div>
      </Form>

      <div class='p-4 bg-neutral-subtle rounded'>
        <div class='flex justify-between items-center mb-2'>
          <h4 class='font-medium'>Form Data</h4>
          <span class='text-sm text-neutral'>
            Last event:
            <strong>{{this.lastEventType}}</strong>
          </span>
        </div>
        <pre class='text-sm overflow-auto max-h-64'>{{JSON.stringify
            this.formData
            null
            2
          }}</pre>
      </div>
    </div>
  </template>
}
```

## Validation

Validation is built in — running it on the right events, mapping issues back to fields, and
rendering the messages — but the schema is yours. Any
[Standard Schema](https://standardschema.dev/) library works; the examples use
[Valibot](https://valibot.dev/). `@validate` adds a hand-rolled check on top, for rules a
schema can't express (comparing two fields, for instance) and returns Standard Schema issues.

Built-in validation requires the yielded `Field` component — it is what binds a field's errors
to its control. See [Field](field) for its own arguments and more examples.

```gts preview collapsible
import Component from '@glimmer/component';
import { tracked } from '@glimmer/tracking';
import { array } from '@ember/helper';
import {
  Form,
  Input,
  Checkbox,
  Select,
  type FormResultData,
  type FormErrors
} from 'frontile';
import { Button } from 'frontile';
import * as v from 'valibot';

// Valibot schema for form validation
const schema = v.object({
  name: v.pipe(
    v.string(),
    v.nonEmpty('Name is required'),
    v.minLength(2, 'Name must be at least 2 characters')
  ),
  email: v.pipe(
    v.string(),
    v.nonEmpty('Email is required'),
    v.email('Please enter a valid email address')
  ),
  password: v.pipe(
    v.string(),
    v.nonEmpty('Password is required'),
    v.minLength(6, 'Password must be at least 6 characters'),
    v.regex(/[A-Z]/, 'Password must contain at least one uppercase letter'),
    v.regex(/[a-z]/, 'Password must contain at least one lowercase letter'),
    v.regex(/\d/, 'Password must contain at least one number')
  ),
  accountType: v.pipe(
    v.fallback(v.string(), ''),
    v.string(),
    v.nonEmpty('Please select an account type')
  ),
  communicationChannels: v.pipe(
    v.array(v.string()),
    v.minLength(1, 'Please select at least one communication channel')
  ),
  terms: v.pipe(
    v.boolean(),
    v.literal(true, 'You must accept the terms and conditions')
  )
});

type Schema = v.InferOutput<typeof schema>;

export default class ValidatedForm extends Component {
  // Provide a complete initial state for proper dirty tracking
  @tracked formData: Schema = {
    name: '',
    email: '',
    password: '',
    confirmPassword: '',
    accountType: '',
    communicationChannels: ['SMS'],
    terms: false
  };

  @tracked submitMessage = '';

  accountTypes = [
    { label: 'Personal', key: 'personal' },
    { label: 'Business', key: 'business' },
    { label: 'Enterprise', key: 'enterprise' }
  ];

  communicationChannels = [
    { label: 'Email', key: 'Email' },
    { label: 'SMS', key: 'SMS' },
    { label: 'Phone', key: 'Phone' },
    { label: 'Push Notifications', key: 'Push' }
  ];

  customValidator(data: FormResultData<Schema>) {
    if (data['password'] !== data['confirmPassword']) {
      return [
        {
          message: 'Passwords must match',
          path: [{ key: 'confirmPassword' }]
        }
      ];
    }
  }

  handleFormChange = (data: FormResultData<Schema>, event: Event) => {
    this.formData = data.data;
    console.log('Form input:', { data, event });
  };

  handleFormSubmit = async (
    data: FormResultData<Schema>,
    event: SubmitEvent
  ) => {
    // Simulate API call
    await new Promise((resolve) => setTimeout(resolve, 1000));
    this.submitMessage = 'Account created successfully!';
    console.log('Form submitted successfully:', data);
  };

  handleFormError = (errors: FormErrors, data: Schema, event: SubmitEvent) => {
    console.log('Validation errors:', errors);
  };

  get isSuccessMessage() {
    return this.submitMessage.includes('success');
  }

  <template>
    <div class='demo-stack'>
      <Form
        @data={{this.formData}}
        @schema={{schema}}
        @validate={{this.customValidator}}
        @onChange={{this.handleFormChange}}
        @onSubmit={{this.handleFormSubmit}}
        @onError={{this.handleFormError}}
        as |form|
      >
        <div class='flex flex-col gap-4'>
          <form.Field @name='name' as |field|>
            <field.Input @label='Full Name' @isRequired={{true}} />
          </form.Field>

          <form.Field @name='email' as |field|>
            <field.Input
              @label='Email Address'
              @type='email'
              @isRequired={{true}}
            />
          </form.Field>

          <form.Field
            @name='password'
            @validateOn={{array 'input' 'blur'}}
            as |field|
          >
            <field.Input
              @label='Password'
              @type='password'
              @isRequired={{true}}
            />
          </form.Field>

          <form.Field @name='confirmPassword' as |field|>
            <field.Input
              @label='Confirm Password'
              @type='password'
              @isRequired={{true}}
            />
          </form.Field>

          <form.Field @name='accountType' as |field|>
            <field.SingleSelect
              @label='Account Type'
              @items={{this.accountTypes}}
              @allowEmpty={{true}}
              @placeholder='Select account type'
              @isRequired={{true}}
            />
          </form.Field>

          <form.Field @name='communicationChannels' as |field|>
            <field.MultiSelect
              @label='Preferred Communication Channels'
              @items={{this.communicationChannels}}
              @isRequired={{true}}
            />
          </form.Field>

          <form.Field @name='terms' as |field|>
            <field.Checkbox
              @label='I agree to the terms and conditions'
              @isRequired={{true}}
            />
          </form.Field>

          <Button type='submit' @isLoading={{form.isLoading}} @class='mt-4'>
            <:default>Create Account</:default>
            <:loading>Creating Account…</:loading>
          </Button>

          <Button @variant='outline' type='reset'>Reset</Button>
        </div>
      </Form>

      {{#if this.submitMessage}}
        <div
          class='p-4 rounded
            {{if
              this.isSuccessMessage
              "bg-success-subtle text-success-strong"
              "bg-danger-subtle text-danger-strong"
            }}'
        >
          {{this.submitMessage}}
        </div>
      {{/if}}
    </div>
  </template>
}
```

### Validation Timing

`@validateOn` controls which events trigger validation. It defaults to
`{{array 'change' 'blur' 'submit'}}`.

| Value    | Validates                                                                 |
| -------- | ------------------------------------------------------------------------- |
| `change` | one field, when its value was modified and it loses focus (HTML `change`) |
| `blur`   | one field, whenever it loses focus — even if nothing changed              |
| `input`  | one field, on every keystroke                                             |
| `submit` | the whole form; on failure `@onError` runs and `@onSubmit` does not       |

```gts
{{! validate as the user types, and again on submit }}
<Form
  @schema={{schema}}
  @validateOn={{array 'input' 'submit'}}
  @onSubmit={{this.handleSubmit}}
  as |form|
>
  <form.Field @name='password' as |field|>
    <field.Input @label='Password' @type='password' />
  </form.Field>
</Form>
```

Which to pick: `change` is the least intrusive and catches most mistakes; add `blur` to flag
required fields a user tabbed straight past; use `input` only where per-keystroke feedback
earns the noise, such as password strength. Drop `submit` for long forms where an error summary
on submit would be jarring.

An empty array (`@validateOn={{array}}`) skips validation entirely: `@onSubmit` is called
regardless of validity and `@onError` never fires. That's the path for multi-step forms, draft
saves, or validating by hand inside `@onSubmit`. Everything else — dirty tracking, reset, data
snapshots — keeps working.

Two limits: the field-level values (`change`, `blur`, `input`) need
`form.Field`, and [CheckboxGroup](checkbox-group) validates only on submit.

## Dirty Field Tracking

`form.dirty` is a `Set` of the fields whose value differs from the initial `@data`. Tracking
covers only the keys present in that initial data, so a field you never seeded is never
reported dirty. Submitting clears the set.

```gts preview collapsible
import Component from '@glimmer/component';
import { tracked } from '@glimmer/tracking';
import { Form, Input, Checkbox, type FormResultData } from 'frontile';
import { Button } from 'frontile';

export default class DirtyTrackingForm extends Component {
  @tracked formData = {
    username: 'john_doe',
    email: 'john@example.com',
    notifications: true
  };

  handleFormChange = (data: FormResultData, event: Event) => {
    console.log('Dirty fields:', Array.from(data.dirty));
  };

  handleFormSubmit = (data: FormResultData, event: SubmitEvent) => {
    console.log('Submitted data:', data);
    // Reset dirty state by updating formData with submitted values
    this.formData = data.data;
  };

  <template>
    <div class='demo-stack'>
      <Form
        @data={{this.formData}}
        @onChange={{this.handleFormChange}}
        @onSubmit={{this.handleFormSubmit}}
        as |form|
      >
        <div class='flex flex-col gap-4'>
          <form.Field @name='username' as |field|>
            <field.Input @label='Username' />
          </form.Field>

          <form.Field @name='email' as |field|>
            <field.Input @label='Email' @type='email' />
          </form.Field>

          <form.Field @name='notifications' as |field|>
            <field.Checkbox @label='Enable email notifications' />
          </form.Field>

          <Button type='submit'>
            Save Changes
          </Button>
        </div>

        <div
          class='mt-4 p-4 rounded
            {{if form.dirty.size "bg-warning-subtle" "bg-neutral-subtle"}}'
        >
          {{#if form.dirty.size}}
            <p class='font-medium text-warning-strong'>
              Unsaved changes in:
              {{#each form.dirty as |field|}}
                <span
                  class='inline-block px-2 py-1 bg-warning-subtle rounded text-sm ml-1'
                >
                  {{field}}
                </span>
              {{/each}}
            </p>
          {{else}}
            <p class='text-neutral'>No unsaved changes</p>
          {{/if}}
        </div>
      </Form>
    </div>
  </template>
}
```

## Validating Without a Schema

`Field` is unnecessary when you are not using built-in validation. Pass `@errors` to each
control yourself and you keep full control of when and how validation runs.

```gts preview collapsible
import Component from '@glimmer/component';
import { tracked } from '@glimmer/tracking';
import { Form, Input, Checkbox, type FormResultData } from 'frontile';
import { Button } from 'frontile';

export default class CustomHandlingForm extends Component {
  @tracked formData: FormResultData = {};
  @tracked validationErrors: Record<string, string[]> = {};
  @tracked submitCount = 0;

  handleFormChange = (data: FormResultData, event: Event) => {
    this.formData = data;

    console.log('Form input event:', {
      data,
      timestamp: new Date(),
      target: event.target
    });

    this.handleRealTimeValidation(data);
  };

  handleFormSubmit = async (data: FormResultData, event: SubmitEvent) => {
    this.formData = data;

    console.log('Form submit event:', {
      data,
      timestamp: new Date(),
      target: event.target
    });

    await this.handleFormSubmission(data, event);
  };

  handleRealTimeValidation = (data: FormResultData) => {
    const errors: Record<string, string[]> = {};

    // Real-time email validation
    if (data['data']['email'] && typeof data['data']['email'] === 'string') {
      if (!data['data']['email'].includes('@')) {
        errors.email = ['Email must contain @ symbol'];
      } else if (!data['data']['email'].includes('.')) {
        errors.email = ['Email must contain a domain'];
      }
    }

    // Real-time password validation
    if (
      data['data']['password'] &&
      typeof data['data']['password'] === 'string'
    ) {
      const password = data['data']['password'];
      const passwordErrors = [];

      if (password.length < 8) {
        passwordErrors.push('At least 8 characters');
      }
      if (!/[A-Z]/.test(password)) {
        passwordErrors.push('At least one uppercase letter');
      }
      if (!/[a-z]/.test(password)) {
        passwordErrors.push('At least one lowercase letter');
      }
      if (!/\d/.test(password)) {
        passwordErrors.push('At least one number');
      }

      if (passwordErrors.length > 0) {
        errors.password = passwordErrors;
      }
    }

    this.validationErrors = errors;
  };

  handleFormSubmission = async (data: FormResultData, event: SubmitEvent) => {
    this.submitCount += 1;

    // Comprehensive validation on submit
    const errors: Record<string, string[]> = {};

    if (
      !data['data']['username'] ||
      typeof data['data']['username'] !== 'string' ||
      data['data']['username'].length < 3
    ) {
      errors.username = ['Username must be at least 3 characters'];
    }

    if (
      !data['data']['email'] ||
      typeof data['data']['email'] !== 'string' ||
      !data['data']['email'].includes('@')
    ) {
      errors.email = ['Valid email is required'];
    }

    if (!data['data']['agreeToTerms']) {
      errors.agreeToTerms = ['You must agree to the terms'];
    }

    if (Object.keys(errors).length > 0) {
      this.validationErrors = errors;
      return;
    }

    try {
      // Simulate API call
      await new Promise((resolve) => setTimeout(resolve, 2000));

      // Reset form on successful submission
      this.formData = {};
      this.validationErrors = {};
    } catch (error) {
      console.error('Submission failed:', error);
    }
  };

  or(a: unknown, b: unknown) {
    return a || b;
  }

  get hasValidationErrors() {
    return (
      this.validationErrors && Object.keys(this.validationErrors).length > 0
    );
  }

  <template>
    <div class='demo-stack'>
      <Form
        @onChange={{this.handleFormChange}}
        @onSubmit={{this.handleFormSubmit}}
        as |form|
      >
        <div class='flex flex-col gap-4'>

          <Input
            @name='username'
            @label='Username'
            @errors={{this.validationErrors.username}}
            @description='Must be at least 3 characters'
          />

          <Input
            @name='email'
            @label='Email'
            @type='email'
            @errors={{this.validationErrors.email}}
          />

          <Input
            @name='password'
            @label='Password'
            @type='password'
            @errors={{this.validationErrors.password}}
            @description='Must contain uppercase, lowercase, and number'
          />

          <Checkbox
            @name='agreeToTerms'
            @label='I agree to the terms and conditions'
            @errors={{this.validationErrors.agreeToTerms}}
          />

          <Button
            type='submit'
            disabled={{this.or form.isLoading this.hasValidationErrors}}
          >
            {{#if form.isLoading}}
              Submitting...
              {{this.submitCount}}
            {{else}}
              Submit Form
            {{/if}}
          </Button>
        </div>
      </Form>
    </div>
  </template>
}
```

## Nested Fields

Nested data is addressed with dot notation: `@name='user.profile.email'`. Form flattens the
object internally and unflattens it again for `@onChange` and `@onSubmit`, so your schema and
your `@data` keep the shape you actually want. Errors and dirty entries are keyed by the same
dotted path down to the leaf — `user.name.first`, never just `user`.

`__proto__`, `constructor` and `prototype` are reserved: a field whose name uses one of those
segments is dropped from the form data rather than nested. Building those keys out of untrusted
field names would let a form write onto `Object.prototype` and change every object in the
application, so they are refused outright.
Numeric segments are part of the path like any other, so a validation issue whose path is
`['items', 0, 'name']` is keyed as `items.0.name` — exactly what you would write as
`@name='items.0.name'`. Index `0` is not dropped, and per-field validation matches indexed
names too.

**Array schemas are not supported.** Form rebuilds nested data by splitting dotted names, and
a numeric segment becomes an ordinary object key, so fields named `items.0.name` and
`items.1.name` arrive at your validator as `{ items: { 0: … , 1: … } }` — an object, never an
array. A schema that declares `items` as an array therefore fails on `items` itself with a
type error, and no per-index issue is ever produced. Validate collections with `@validate`
instead, reading the indexed paths off the object you are given. The same applies to the data
handed to `@onChange` and `@onSubmit`.

```gts preview collapsible
import Component from '@glimmer/component';
import { tracked } from '@glimmer/tracking';
import { Form, type FormResultData } from 'frontile';
import { Button } from 'frontile';

const formData = {
  user: {
    name: {
      first: 'John',
      last: 'Doe'
    },
    email: 'john@example.com'
  },
  preferences: {
    theme: 'light',
    notifications: true
  }
};

export default class NestedForm extends Component {
  @tracked formData = formData;

  @tracked submittedData = {};

  handleFormChange = (data: FormResultData<typeof formData>) => {
    this.formData = data.data;
  };

  handleFormSubmit = (data: FormResultData<typeof formData>) => {
    this.submittedData = data.data;
  };

  <template>
    <div class='demo-stack'>
      <Form
        @data={{this.formData}}
        @onChange={{this.handleFormChange}}
        @onSubmit={{this.handleFormSubmit}}
        as |form|
      >
        <div class='flex flex-col gap-4'>
          <h3 class='text-lg font-semibold'>User Information</h3>

          <form.Field @name='user.name.first' as |field|>
            <field.Input @label='First Name' />
          </form.Field>

          <form.Field @name='user.name.last' as |field|>
            <field.Input @label='Last Name' />
          </form.Field>

          <form.Field @name='user.email' as |field|>
            <field.Input @label='Email' @type='email' />
          </form.Field>

          <h3 class='text-lg font-semibold mt-4'>Preferences</h3>

          <form.Field @name='preferences.theme' as |field|>
            <field.Input @label='Theme' />
          </form.Field>

          <form.Field @name='preferences.notifications' as |field|>
            <field.Checkbox @label='Enable notifications' />
          </form.Field>

          {{#if form.dirty.size}}
            <div class='p-3 bg-warning-subtle rounded text-sm'>
              <strong>Unsaved changes in:</strong>
              {{#each form.dirty as |field|}}
                <span
                  class='inline-block px-2 py-1 bg-warning-subtle rounded ml-1'
                >
                  {{field}}
                </span>
              {{/each}}
            </div>
          {{/if}}

          <Button type='submit'>
            Save Changes
          </Button>
        </div>
      </Form>

      <div class='p-4 bg-neutral-subtle rounded'>
        <h4 class='font-medium mb-2'>Submitted Data:</h4>
        <pre class='text-sm overflow-auto'>{{JSON.stringify
            this.submittedData
            null
            2
          }}</pre>
      </div>
    </div>
  </template>
}
```

### Nested Fields with Validation

Mirror the data shape in the schema and issues land on the right control.

```gts preview collapsible
import Component from '@glimmer/component';
import { tracked } from '@glimmer/tracking';
import { Form, type FormResultData, type FormErrors } from 'frontile';
import { Button } from 'frontile';
import * as v from 'valibot';

// Define nested schema
const userSchema = v.object({
  profile: v.object({
    firstName: v.pipe(
      v.string(),
      v.nonEmpty('First name is required'),
      v.minLength(2, 'Must be at least 2 characters')
    ),
    lastName: v.pipe(v.string(), v.nonEmpty('Last name is required')),
    contact: v.object({
      email: v.pipe(
        v.string(),
        v.nonEmpty('Email is required'),
        v.email('Must be a valid email address')
      ),
      phone: v.pipe(
        v.string(),
        v.nonEmpty('Phone is required'),
        v.regex(/^\+?[\d\s-()]+$/, 'Must be a valid phone number')
      )
    })
  }),
  settings: v.object({
    newsletter: v.boolean()
  })
});

type UserSchema = v.InferOutput<typeof userSchema>;

export default class ValidatedNestedForm extends Component {
  @tracked formData: UserSchema = {
    profile: {
      firstName: '',
      lastName: '',
      contact: {
        email: '',
        phone: ''
      }
    },
    settings: {
      newsletter: false
    }
  };

  @tracked submitMessage = '';

  handleFormSubmit = async (data: FormResultData<UserSchema>) => {
    // Simulate API call
    await new Promise((resolve) => setTimeout(resolve, 1000));
    this.submitMessage = 'Profile updated successfully!';
    console.log('Submitted nested data:', data.data);
  };

  handleFormError = (errors: FormErrors) => {
    this.submitMessage = '';
    console.log('Validation errors:', errors);
  };

  <template>
    <div class='demo-stack'>
      <Form
        @data={{this.formData}}
        @schema={{userSchema}}
        @onSubmit={{this.handleFormSubmit}}
        @onError={{this.handleFormError}}
        as |form|
      >
        <div class='flex flex-col gap-4'>
          <div>
            <h3 class='text-lg font-semibold mb-3'>Profile Information</h3>

            <div class='flex flex-col gap-4'>
              <form.Field @name='profile.firstName' as |field|>
                <field.Input @label='First Name' @isRequired={{true}} />
              </form.Field>

              <form.Field @name='profile.lastName' as |field|>
                <field.Input @label='Last Name' @isRequired={{true}} />
              </form.Field>
            </div>
          </div>

          <div>
            <h3 class='text-lg font-semibold mb-3'>Contact Information</h3>

            <div class='flex flex-col gap-4'>
              <form.Field @name='profile.contact.email' as |field|>
                <field.Input
                  @label='Email Address'
                  @type='email'
                  @isRequired={{true}}
                />
              </form.Field>

              <form.Field @name='profile.contact.phone' as |field|>
                <field.Input
                  @label='Phone Number'
                  @type='tel'
                  @isRequired={{true}}
                />
              </form.Field>
            </div>
          </div>

          <div>
            <h3 class='text-lg font-semibold mb-3'>Settings</h3>

            <form.Field @name='settings.newsletter' as |field|>
              <field.Checkbox @label='Subscribe to newsletter' />
            </form.Field>
          </div>

          <Button type='submit' @isLoading={{form.isLoading}}>
            <:default>Save Profile</:default>
            <:loading>Saving…</:loading>
          </Button>
        </div>
      </Form>

      {{#if this.submitMessage}}
        <div class='p-4 bg-success-subtle text-success-strong rounded'>
          {{this.submitMessage}}
        </div>
      {{/if}}
    </div>
  </template>
}
```

### Mixing Flat and Nested Fields

Flat and nested names can sit side by side in one form.

```gts preview collapsible
import Component from '@glimmer/component';
import { tracked } from '@glimmer/tracking';
import { Form, type FormResultData } from 'frontile';
import { Button } from 'frontile';

const formData = {
  // Flat fields
  username: 'johndoe',
  age: 30,
  // Nested fields
  address: {
    street: '123 Main St',
    city: 'Springfield',
    country: 'USA'
  },
  // Another flat field
  acceptTerms: true
};

export default class MixedFieldsForm extends Component {
  @tracked formData = formData;

  handleFormSubmit = (data: FormResultData<typeof formData>) => {
    console.log('Mixed data structure:', data.data);
  };

  <template>
    <div class='demo-stack'>
      <Form
        @data={{this.formData}}
        @onSubmit={{this.handleFormSubmit}}
        as |form|
      >
        <div class='flex flex-col gap-4'>
          {{! Flat fields }}
          <form.Field @name='username' as |field|>
            <field.Input @label='Username' />
          </form.Field>

          <form.Field @name='age' as |field|>
            <field.Input @label='Age' @type='number' />
          </form.Field>

          {{! Nested fields }}
          <h3 class='text-lg font-semibold mt-2'>Address</h3>

          <form.Field @name='address.street' as |field|>
            <field.Input @label='Street' />
          </form.Field>

          <form.Field @name='address.city' as |field|>
            <field.Input @label='City' />
          </form.Field>

          <form.Field @name='address.country' as |field|>
            <field.Input @label='Country' />
          </form.Field>

          {{! Another flat field }}
          <form.Field @name='acceptTerms' as |field|>
            <field.Checkbox @label='I accept the terms and conditions' />
          </form.Field>

          <Button type='submit'>Submit</Button>
        </div>
      </Form>
    </div>
  </template>
}
```

## Resetting Forms

`form.reset` calls the native form reset, restores `@data`'s initial values, clears validation
errors, and empties the dirty set. In a controlled form it reports the initial data back through
`@onChange`; in an uncontrolled one it updates the internal state. With no `@data` at all it
just clears the fields.

```gts preview collapsible
import Component from '@glimmer/component';
import { tracked } from '@glimmer/tracking';
import { Form, type FormResultData } from 'frontile';
import { Button } from 'frontile';
import { on } from '@ember/modifier';

export default class ResetForm extends Component {
  @tracked formData = {
    username: 'johndoe',
    email: 'john@example.com',
    bio: 'Software developer'
  };

  handleChange = (data: FormResultData<typeof this.formData>) => {
    this.formData = data.data;
  };

  handleSubmit = (data: FormResultData<typeof this.formData>) => {
    console.log('Form submitted:', data.data);
  };

  <template>
    <div class='demo-stack'>
      <Form
        @data={{this.formData}}
        @onChange={{this.handleChange}}
        @onSubmit={{this.handleSubmit}}
        as |form|
      >
        <div class='flex flex-col gap-4'>
          <form.Field @name='username' as |field|>
            <field.Input @label='Username' />
          </form.Field>

          <form.Field @name='email' as |field|>
            <field.Input @label='Email' @type='email' />
          </form.Field>

          <form.Field @name='bio' as |field|>
            <field.Textarea @label='Bio' rows='4' />
          </form.Field>

          {{#if form.dirty.size}}
            <div class='p-3 bg-warning-subtle rounded text-sm'>
              You have unsaved changes
            </div>
          {{/if}}

          <div class='flex gap-2'>
            <Button type='submit'>
              Save Changes
            </Button>
            <Button
              type='button'
              @color='neutral'
              @variant='outline'
              {{on 'click' form.reset}}
            >
              Reset
            </Button>
          </div>
        </div>
      </Form>
    </div>
  </template>
}
```

### Reset with Validation

Errors already on screen are cleared along with the values.

```gts preview collapsible
import Component from '@glimmer/component';
import { tracked } from '@glimmer/tracking';
import { Form, type FormResultData, type FormErrors } from 'frontile';
import { Button } from 'frontile';
import { on } from '@ember/modifier';
import * as v from 'valibot';

const schema = v.object({
  email: v.pipe(
    v.string(),
    v.nonEmpty('Email is required'),
    v.email('Must be a valid email address')
  ),
  password: v.pipe(
    v.string(),
    v.nonEmpty('Password is required'),
    v.minLength(8, 'Password must be at least 8 characters')
  )
});

type Schema = v.InferOutput<typeof schema>;

export default class ResetValidationForm extends Component {
  @tracked formData: Schema = {
    email: 'user@example.com',
    password: 'password123'
  };

  handleChange = (data: FormResultData<Schema>) => {
    this.formData = data.data;
  };

  handleSubmit = (data: FormResultData<Schema>) => {
    console.log('Form submitted:', data.data);
  };

  handleError = (errors: FormErrors) => {
    console.log('Validation errors:', errors);
  };

  <template>
    <div class='demo-stack'>
      <Form
        @data={{this.formData}}
        @schema={{schema}}
        @onChange={{this.handleChange}}
        @onSubmit={{this.handleSubmit}}
        @onError={{this.handleError}}
        as |form|
      >
        <div class='flex flex-col gap-4'>
          <form.Field @name='email' as |field|>
            <field.Input @label='Email' @type='email' @isRequired={{true}} />
          </form.Field>

          <form.Field @name='password' as |field|>
            <field.Input
              @label='Password'
              @type='password'
              @isRequired={{true}}
            />
          </form.Field>

          <div class='flex gap-2'>
            <Button type='submit' @isLoading={{form.isLoading}}>
              <:default>Save</:default>
              <:loading>Saving…</:loading>
            </Button>
            <Button
              type='button'
              @color='neutral'
              @variant='outline'
              {{on 'click' form.reset}}
            >
              Reset
            </Button>
          </div>
        </div>
      </Form>
    </div>
  </template>
}
```

## Disabled Forms

`@disabled` disables every yielded `Field` and the control inside it at once — useful while a
submission is in flight, in read-only views, or for steps of a wizard that are already done. It
reaches `Field` children only; controls used without `Field` manage their own `disabled`.

```gts preview collapsible
import Component from '@glimmer/component';
import { tracked } from '@glimmer/tracking';
import { on } from '@ember/modifier';
import { Form, type FormResultData } from 'frontile';
import { Button } from 'frontile';
import * as v from 'valibot';

const schema = v.object({
  email: v.pipe(
    v.string(),
    v.nonEmpty('Email is required'),
    v.email('Please enter a valid email address')
  ),
  password: v.pipe(
    v.string(),
    v.nonEmpty('Password is required'),
    v.minLength(6, 'Password must be at least 6 characters')
  )
});

type Schema = v.InferOutput<typeof schema>;

export default class DisabledForm extends Component {
  @tracked formData: Schema = {
    email: '',
    password: ''
  };
  @tracked isFormDisabled = false;
  @tracked submitMessage = '';

  handleFormChange = (data: FormResultData<Schema>) => {
    this.formData = data.data;
  };

  handleFormSubmit = async (data: FormResultData<Schema>) => {
    // Simulate API call
    this.isFormDisabled = true;
    await new Promise((resolve) => setTimeout(resolve, 2000));
    this.submitMessage = 'Login successful!';
    this.isFormDisabled = false;
    console.log('Form submitted:', data);
  };

  toggleDisabled = () => {
    this.isFormDisabled = !this.isFormDisabled;
  };

  or(a: unknown, b: unknown) {
    return a || b;
  }

  <template>
    <div class='demo-stack'>
      <div class='flex items-center gap-2 p-3 bg-neutral-subtle rounded'>
        <label class='flex items-center gap-2 cursor-pointer'>
          <input
            type='checkbox'
            checked={{this.isFormDisabled}}
            {{on 'change' this.toggleDisabled}}
            class='w-4 h-4'
          />
          <span class='text-sm font-medium'>Disable form</span>
        </label>
      </div>

      <Form
        @disabled={{this.isFormDisabled}}
        @data={{this.formData}}
        @schema={{schema}}
        @onChange={{this.handleFormChange}}
        @onSubmit={{this.handleFormSubmit}}
        as |form|
      >
        <div class='flex flex-col gap-4'>
          <form.Field @name='email' as |field|>
            <field.Input @label='Email' @type='email' @isRequired={{true}} />
          </form.Field>

          <form.Field @name='password' as |field|>
            <field.Input
              @label='Password'
              @type='password'
              @isRequired={{true}}
            />
          </form.Field>

          <Button
            type='submit'
            disabled={{this.or form.isLoading this.isFormDisabled}}
          >
            {{if form.isLoading 'Logging in...' 'Log In'}}
          </Button>
        </div>
      </Form>

      {{#if this.submitMessage}}
        <div class='p-4 bg-success-subtle text-success-strong rounded'>
          {{this.submitMessage}}
        </div>
      {{/if}}
    </div>
  </template>
}
```

## Feedback Messages

When a field fails validation, `Form`/`Field` render a `FormFeedback` with the `danger` status
— no wiring needed. The announcement comes from a separate, visually hidden `aria-live`
region that `FormControl` always keeps in the DOM, so it is already being observed when the
message arrives.

For feedback that isn't a validation error — hints, confirmations, warnings — render
`FormFeedback` yourself and pick a `@status` from `primary`, `secondary`, `tertiary`,
`success`, `warning`, or `danger`. Anything other than `danger` announces politely.

A standalone `FormFeedback` is its own `aria-live` region. Pass `@announce={{false}}` when
something else already announces the same text — that is exactly what `FormControl` does to
the feedback it renders, since its persistent live region has already covered the message and
announcing twice is worse than not at all. See
[FormControl](/docs/components/forms/form-control) for the full explanation and the
cases where you want to turn announcing back on.

```gts preview
import { FormFeedback } from 'frontile';

<template>
  <div class='demo-stack'>
    <FormFeedback @color='primary' @messages='Your changes are being saved.' />
    <FormFeedback
      @color='secondary'
      @messages='This field supports Markdown.'
    />
    <FormFeedback
      @color='tertiary'
      @messages='This field supports Markdown.'
    />
    <FormFeedback @color='success' @messages='Looks good!' />
    <FormFeedback
      @color='warning'
      @messages='This username is close to the limit.'
    />
    <FormFeedback @color='danger' @messages='This field is required.' />
  </div>
</template>
```

## Accessibility

Form renders a native `<form>`, so submission on <kbd>Enter</kbd>, field labelling, and
`...attributes` pass-through all behave natively.

- **Invalid fields** get `aria-invalid='true'` from `Field`, removed again once the field
  validates.
- **Error messages** render in a `FormFeedback` associated with the control through
  `aria-describedby`, and are announced from a persistent, visually hidden
  `aria-live='assertive'` region that `FormControl` renders whether or not the field is
  currently invalid.
- **Disabled fields** carry the real `disabled` attribute rather than a styling-only state.
- **Focus** is not managed or trapped by Form; it stays where the browser puts it. If you
  redirect focus to the first invalid field in `@onError`, see
  [focus management](/docs/accessibility/focus-management).

## API

The default block yields a context object:

| Property                | Description                                                       |
| ----------------------- | ----------------------------------------------------------------- |
| `data`                  | Current form data as key/value pairs                              |
| `isLoading`             | `true` while an async `@onSubmit` is in flight                    |
| `isValid` / `isInvalid` | Whether the form currently has validation errors                  |
| `errors`                | Validation errors keyed by field name                             |
| `dirty`                 | `Set` of fields changed from their initial values                 |
| `reset`                 | Resets values, errors, and dirty tracking                         |
| `Field`                 | The `Field` component, with `errors` and `formData` already bound |

### Form

A form component that handles form submissions and input changes.

**Element:** `Array`

**Arguments**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `onSubmit *` | `(result: FormResultData<T>, event: SubmitEvent) => void \| Promise<void>` | - | Callback invoked on form submission.  If onSubmit returns a promise, the form will be marked as isLoading until the promise resolves. |
| `data` | `T` | - | The initial form data as key/value pairs. This is primarily useful for setting default values in the form. This object receives changes as the user interacts with the form. |
| `disabled` | `boolean` | - | Whether the entire form and all its fields should be disabled.  This only applies when using the yielded Field component. |
| `onChange` | `(result: FormResultData<T>, event: Event) => void \| Promise<void>` | - | Optional callback invoked on input changes within the form. |
| `onError` | `(errors: FormErrors, data: T, event: SubmitEvent) => void \| Promise<void>` | - | Optional callback invoked when validation errors occur on form submission. |
| `schema` | `Object` | - | The standard schema to validate form data against. |
| `validate` | `CustomValidatorFn<T>` | - | Optional custom validation function.  A custom validator should return an array of Standard Schema issues, or undefined if there are none. This function may be async or sync. |
| `validateOn` | `('submit' \| 'input' \| 'blur' \| 'change')[]` | - | When to run validation. |

**Blocks**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `default *` | `[FormContext<T>]` | - |  |

---

# InputOtp

Source: /docs/components/forms/input-otp.md

# InputOtp

A one-time-code (OTP/PIN) field. The cells you see are decoration drawn over a single real
`<input>`, so password managers, iOS and Android SMS autofill, paste, undo and screen readers
all behave exactly as they would on an ordinary text field.

## Import

```js
import { InputOtp } from 'frontile';
```

## Usage

```gts preview
import { InputOtp } from 'frontile';

<template>
  <div class='demo-stack'>
    <InputOtp @label='Verification code' />
  </div>
</template>
```

## Groups

Split the cells into visual groups with `@groups`, an array of group sizes. `@separator`
(default `'–'`) sets the character shown between groups; it is rendered `aria-hidden`
because the underlying value never contains it.

The sizes should sum to `@length`. If they do not, the groups are adjusted to fit — you always
get exactly `@length` cells — and a warning is logged in development.

```gts preview
import { InputOtp } from 'frontile';
import { array } from '@ember/helper';

<template>
  <div class='demo-stack'>
    <InputOtp @label='Card verification' @length={{6}} @groups={{array 3 3}} @separator='-' />
  </div>
</template>
```

## Uncontrolled with `@onComplete`

The common case: let the component own its value and react only when the code is complete.
`@onComplete` fires once, when the last character lands.

```gts preview
import Component from '@glimmer/component';
import { tracked } from '@glimmer/tracking';
import { InputOtp } from 'frontile';

export default class VerifyCodeExample extends Component {
  @tracked submittedCode = '';

  handleComplete = (value: string) => {
    this.submittedCode = value;
  };

  <template>
    <div class='demo-stack'>
      <InputOtp @label='Verification code' @onComplete={{this.handleComplete}} />
      <p>Submitted: {{this.submittedCode}}</p>
    </div>
  </template>
}
```

## Controlled

Pair `@value` with `@onInput` to own the value yourself. `@onInput` fires on every
keystroke; `@onChange` follows the DOM `change` event, which on a text input fires on
blur, so a parent wired only to `@onChange` hears nothing until the field is left.

```gts preview
import Component from '@glimmer/component';
import { tracked } from '@glimmer/tracking';
import { InputOtp } from 'frontile';

export default class ControlledOtpExample extends Component {
  @tracked code = '';

  handleInput = (value: string) => {
    this.code = value;
  };

  <template>
    <div class='demo-stack'>
      <InputOtp @label='Verification code' @value={{this.code}} @onInput={{this.handleInput}} />
      <p>Current value: {{this.code}}</p>
    </div>
  </template>
}
```

## Inside a Form

Used through `<form.Field>`, InputOtp submits as a single string value under one `@name`,
the same as any other field.

```gts preview
import Component from '@glimmer/component';
import { tracked } from '@glimmer/tracking';
import { Form, type FormResultData } from 'frontile';

export default class OtpFormExample extends Component {
  @tracked formData = { code: '' };

  handleFormChange = (result: FormResultData) => {
    this.formData = result.data;
  };

  <template>
    <div class='demo-stack'>
      <Form @data={{this.formData}} @onChange={{this.handleFormChange}} as |form|>
        <form.Field @name='code' as |field|>
          <field.InputOtp @label='Verification code' />
        </form.Field>
      </Form>
      <p>Current value: {{this.formData.code}}</p>
    </div>
  </template>
}
```

## Character rules

`@allowedChars` picks a built-in rule (`digits` is the default), which also sets the on-screen
keyboard (`inputmode`) and autocapitalization.

A value that fails the rule is rejected whole rather than stripped of the offending
characters: pasting `12-456` into a `digits` field leaves the field unchanged, it does not
become `12456`. Length is applied first — anything longer than `@length` is trimmed to its
first `@length` characters, and those are what the rule checks.

```gts preview
import { InputOtp } from 'frontile';

<template>
  <div class='demo-stack'>
    <InputOtp @label='Digits' @allowedChars='digits' @length={{4}} />
    <InputOtp @label='Letters' @allowedChars='letters' @length={{4}} />
    <InputOtp @label='Alphanumeric' @allowedChars='alphanumeric' @length={{4}} />
  </div>
</template>
```

`@pattern` overrides `@allowedChars` with a custom rule.

> **A custom `@pattern` must match partial values.** It is tested against every intermediate
> value as the user types, not just the finished code. Use `/^\d+$/`, never an anchored
> `/^\d{6}$/` — a length-anchored pattern rejects the very first keystroke and makes the
> field impossible to type into.

The rule is also set as the input's native `pattern` attribute, with any regex flags (`i`,
`u`, …) dropped. Since the rule accepts partial input, native validation will also accept an
incomplete code — it does not enforce `@length`. Check for completeness with `@onComplete` or
your form's validation.

```gts preview
import Component from '@glimmer/component';
import { InputOtp } from 'frontile';

export default class EvenDigitsExample extends Component {
  evenDigitsPattern = /^[02468]*$/;

  <template>
    <div class='demo-stack'>
      <InputOtp @label='Even digits only' @length={{4}} @pattern={{this.evenDigitsPattern}} />
    </div>
  </template>
}
```

## Masked

`@isMasked` draws a bullet in place of each entered character, for PIN-style entry. Only the
display changes: autofill and password managers keep working.

```gts preview
import { InputOtp } from 'frontile';

<template>
  <div class='demo-stack'>
    <InputOtp @label='PIN' @length={{4}} @isMasked={{true}} />
  </div>
</template>
```

## Placeholder

`@placeholder` previews the shape of the code in the empty cells, and is exposed on the input
as `aria-placeholder`. It clears from every cell as soon as anything is entered. Type a digit
in the demo below to watch it go.

```gts preview
import { InputOtp } from 'frontile';

<template>
  <div class='demo-stack'>
    <InputOtp @label='Verification code' @length={{6}} @placeholder='000000' />
  </div>
</template>
```

## Sizes

```gts preview
import { InputOtp } from 'frontile';

<template>
  <div class='demo-stack'>
    <InputOtp @label='Small' @size='sm' />
    <InputOtp @label='Medium' @size='md' />
    <InputOtp @label='Large' @size='lg' />
  </div>
</template>
```

## States

```gts preview
import { InputOtp } from 'frontile';

<template>
  <div class='demo-stack'>
    <InputOtp @label='Disabled' @isDisabled={{true}} @value='123' />
    <InputOtp @label='Verification code' @isRequired={{true}} />
    <InputOtp
      @label='Verification code'
      @description="Check your phone for a text message"
    />
    <InputOtp
      @label='Verification code'
      @errors='That code is incorrect or has expired'
    />
  </div>
</template>
```

## Accessibility

- The visible cells are pure decoration: they carry `aria-hidden="true"` and no `role`,
  `tabindex`, or `aria-label` — there is exactly one tab stop, the real input underneath.
- Provide a label with `@label` (associated via `for`/`id`) or an `aria-label` passed through
  `...attributes`.
- Editing works as it does in any text field: shift-select, select-all, backspace,
  word-delete, undo and copy/cut/paste. Arrow keys move from cell to cell.
- Validation messages passed through `@errors` are associated via `aria-describedby` and set
  `aria-invalid`, the same as other form controls.

## SMS autofill

`autocomplete="one-time-code"` is set for you, which is what lets browsers and mobile OSes
offer an incoming SMS code as a one-tap suggestion. Nothing else is required on your side.

To opt into iOS 14+ domain-bound codes, the SMS *message* needs a `@example.com #123456`
footer — that is set by whatever service sends the text.

## API

### InputOtp

Ownership model, stated once.

The <input> element is the source of truth for what the user typed -- the
browser guarantees that -- so a parent-owned @value is written down into
it (by syncFromValueArg and reconcileWithParent) rather than bound over
it with value={{...}}.

That binding is what broke typing inside a <Form>. elementValue is
dirtied mid-dispatch and the template reads it (through cellGroups), so
Glimmer revalidates in a microtask that runs between event listeners --
rewriting the value attribute from a still-stale @value before the
input event had finished bubbling to the <form>, wiping the keystroke and
handing <Form> an empty value to store.

The one invariant that keeps the mirror honest: every code path that writes
element.value goes through writeValue, which re-derives the selection
mirror straight afterwards.

**Element:** `HTMLInputElement`

**Arguments**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `allowedChars` | `'digits' \| 'letters' \| 'alphanumeric'` | `'digits'` | Which characters the code may contain. Also decides the on-screen keyboard (inputmode) and autocapitalisation. |
| `classes` | `SlotsToClasses<'base' \| 'input' \| 'separator' \| 'container' \| 'group' \| 'cell' \| 'cellChar' \| 'caret'>` | - | Class names for each slot of the component, merged with the theme's. |
| `description` | `string` | - | Help text rendered between the label and the control, and referenced by the ids describedBy returns. |
| `errors` | `string \| string[]` | - | Validation messages for the field. A non-empty value also marks the control invalid, and an array is joined with ;  when displayed. |
| `groups` | `number[]` | - | Splits the cells into visual groups, e.g. [3, 3] for a six-digit code. Omit it for a single group. Entries that do not sum to length warn in development; the groups then run out of cells or take a final group of the remainder, so exactly length cells render either way. |
| `isDisabled` | `boolean` | `false` | Whether the field is disabled. FormControl passes this through for styling; the control it wraps is responsible for the disabled attribute. |
| `isInvalid` | `boolean` | `false` | Marks the control invalid without supplying messages, for validation that is reported elsewhere. |
| `isMasked` | `boolean` | `false` | Renders a bullet in place of each entered character. The real input's text is already transparent, so this is purely what the cells draw -- the input stays type="text", which type="password" would break for autofill. |
| `isRequired` | `boolean` | `false` | Whether the field is required. Adds an asterisk to the label; it does not set the required attribute on the control itself. |
| `label` | `string` | - | The label text rendered above the control and associated with it via for. Use the :label block instead when the label needs markup. |
| `length` | `number` | `6` | How many characters the code has. Also the input's maxlength. |
| `name` | `string` | - | The name attribute of the underlying input, used when the code is submitted as part of a form. |
| `onBlur` | `() => void` | - | Callback when onblur is triggered. |
| `onChange` | `(value: string, event?: Event) => void` | - | Callback when onchange is triggered. |
| `onComplete` | `(value: string) => void` | - | Called when the code becomes complete. Fires on the transition from a shorter value to exactly length characters, so re-rendering an already full value does not fire it again. |
| `onInput` | `(value: string, event?: Event) => void` | - | Callback when oninput is triggered. |
| `pattern` | `Object` | - | A custom character rule, overriding allowedChars. It is tested against every intermediate value, so it must accept partial input: /^\d+$/, not /^\d{6}$/. |
| `placeholder` | `string` | - | Characters shown in empty cells before anything is entered. Also exposed as aria-placeholder. |
| `separator` | `string` | `'–'` | The character shown between groups. Rendered aria-hidden, because the value itself contains no separator. |
| `size` | `'sm' \| 'md' \| 'lg'` | `'md'` | The size of the cells and the label. |
| `value` | `string` | - | The value of the input. Pair with onInput or onChange to control the input; leave it unset to let the component track its own value. |

---

# Input

Source: /docs/components/forms/input.md

# Input

A text input component with support for labels, validation, start/end content, and a clearable option.

## Import

```js
import { Input } from 'frontile';
```

## Usage

### Basic Input

The most basic usage of the Input component with only a label.

```gts preview
import { Input } from 'frontile';
<template>
  <div class='demo-stack'>
    <Input @label='Full Name' />
  </div>
</template>
```

### Controlled Input

You can control the input value using the Form component's data binding pattern. The Form automatically manages the input's value and updates.

```gts preview
import Component from '@glimmer/component';
import { tracked } from '@glimmer/tracking';
import { Form, type FormResultData } from 'frontile';

export default class ControlledInput extends Component {
  @tracked formData = { name: '' };

  handleFormChange = (result: FormResultData) => {
    this.formData = result.data;
  };

  <template>
    <div class='demo-stack'>
      <Form @data={{this.formData}} @onChange={{this.handleFormChange}} as |form|>
        <form.Field @name='name' as |field|>
          <field.Input @label='Your Name' />
        </form.Field>
      </Form>
      <p>Current value: {{this.formData.name}}</p>
    </div>
  </template>
}
```

### Input Types

The Input component supports different HTML input types through the `@type` argument.

```gts preview
import Component from '@glimmer/component';
import { Input } from 'frontile';

export default class InputTypes extends Component {
  <template>
    <div class='demo-stack'>
      <Input @label='Email' @type='email' />
      <Input @label='Password' @type='password' />
      <Input @label='Phone Number' @type='tel' />
      <Input @label='Age' @type='number' />
      <Input @label='Website' @type='url' />
    </div>
  </template>
}
```


### Start and End Content

You can add custom content at the beginning or end of the input using named blocks.

```gts preview
import Component from '@glimmer/component';
import { Input } from 'frontile';
import { SearchIcon } from 'site/components/icons';

export default class InputWithContent extends Component {
  <template>
    <div class='demo-stack'>
      <Input @label='Price'>
        <:startContent>
          <span class='text-neutral-soft'>$</span>
        </:startContent>
        <:endContent>
          <span class='text-neutral-soft'>USD</span>
        </:endContent>
      </Input>

      <Input @label='Search'>
        <:startContent>
          <SearchIcon />
        </:startContent>
        <:endContent>
          <button type='button'>Go</button>
        </:endContent>
      </Input>
    </div>
  </template>
}
```

### Pointer Events Control

When using interactive content in start or end slots, you can control pointer events to ensure proper click handling.

```gts preview
import Component from '@glimmer/component';
import { Input } from 'frontile';
import { on } from '@ember/modifier';
import { SearchIcon } from 'site/components/icons';

export default class SearchInput extends Component {
  handleSearch = () => {
    console.log('Search clicked');
  };

  <template>
    <div class='demo-stack'>
      <Input
        @label='Search with Button'
        @startContentPointerEvents='none'
        @endContentPointerEvents='auto'
      >
        <:startContent>
          <SearchIcon />
        </:startContent>
        <:endContent>
          <button type='button' {{on 'click' this.handleSearch}}>
            Search
          </button>
        </:endContent>
      </Input>
    </div>
  </template>
}
```

### Clearable Input

Enable a clear button that appears when the input has a value by setting `@isClearable` to `true`.

```gts preview
import Component from '@glimmer/component';
import { tracked } from '@glimmer/tracking';
import { Form, type FormResultData } from 'frontile';

export default class ClearableInput extends Component {
  @tracked formData = { searchQuery: '' };

  handleFormChange = (result: FormResultData) => {
    this.formData = result.data;
  };

  <template>
    <div class='demo-stack'>
      <Form @data={{this.formData}} @onChange={{this.handleFormChange}} as |form|>
        <form.Field @name='searchQuery' as |field|>
          <field.Input
            @label='Search Query'
            @isClearable={{true}}
            placeholder='Type to search...'
          />
        </form.Field>
      </Form>
    </div>
  </template>
}
```

### Form Validation

The Input component integrates with form validation by displaying error messages and updating ARIA attributes accordingly. This example demonstrates validation using Valibot schema with the Form/Field components.

```gts preview collapsible
import Component from '@glimmer/component';
import { tracked } from '@glimmer/tracking';
import { Form, type FormResultData, type FormErrors } from 'frontile';
import { Button } from 'frontile';
import * as v from 'valibot';

// Define validation schema
const schema = v.object({
  name: v.pipe(
    v.string(),
    v.nonEmpty('Name is required'),
    v.minLength(2, 'Name must be at least 2 characters')
  ),
  email: v.pipe(
    v.string(),
    v.nonEmpty('Email is required'),
    v.email('Please enter a valid email address')
  )
});

type Schema = v.InferOutput<typeof schema>;

export default class ValidatedInput extends Component {
  @tracked formData: Schema = {
    name: '',
    email: ''
  };

  handleFormChange = (result: FormResultData<Schema>) => {
    this.formData = result.data;
  };

  handleFormSubmit = (result: FormResultData<Schema>) => {
    console.log('Form submitted:', result.data);
  };

  handleFormError = (errors: FormErrors) => {
    console.log('Validation errors:', errors);
  };

  <template>
    <div class='demo-stack'>
      <Form
        @data={{this.formData}}
        @schema={{schema}}
        @onChange={{this.handleFormChange}}
        @onSubmit={{this.handleFormSubmit}}
        @onError={{this.handleFormError}}
        as |form|
      >
        <form.Field @name='name' as |field|>
          <field.Input @label='Name' @isRequired={{true}} />
        </form.Field>

        <form.Field @name='email' as |field|>
          <field.Input
            @label='Email Address'
            @type='email'
            @isRequired={{true}}
          />
        </form.Field>

        <Button type='submit'>Submit</Button>
      </Form>
    </div>
  </template>
}
```

### Miscellaneous Options

The Input component supports various optional configurations for sizing, states, and styling.

```gts preview collapsible
import { Input } from 'frontile';
import { hash } from '@ember/helper';

<template>
  <div class='demo-stack'>
    {{! Size variants }}
    <div>
      <h4 class='text-sm font-medium mb-2'>Size Variants</h4>
      <div class='flex flex-col gap-3'>
        <Input @label='Small Input' @size='sm' />
        <Input @label='Medium Input' @size='md' />
        <Input @label='Large Input' @size='lg' />
      </div>
    </div>

    {{! Disabled state }}
    <div>
      <h4 class='text-sm font-medium mb-2'>Disabled State</h4>
      <div class='flex flex-col gap-3'>
        <Input
          @label='Disabled Input'
          @value='Cannot edit this text'
          disabled={{true}}
        />
        <Input
          @label='Disabled with Description'
          @description='This input is disabled'
          @value='Sample value'
          disabled={{true}}
        />
      </div>
    </div>

    {{! With description }}
    <div>
      <h4 class='text-sm font-medium mb-2'>With Description</h4>
      <Input
        @label='Username'
        @description='Choose a unique username'
      />
    </div>

    {{! Custom styling }}
    <div>
      <h4 class='text-sm font-medium mb-2'>Custom Styling</h4>
      <Input
        @label='Custom Classes'
        @classes={{hash
          base='my-custom-form-control'
          input='my-custom-input-field'
        }}
      />
    </div>
  </div>
</template>
```

## Accessibility

The Input component follows accessibility best practices:

- Proper label association using `for` and `id` attributes
- ARIA attributes for invalid states (`aria-invalid`)
- Descriptive text association using `aria-describedby`
- Support for required field indication
- Keyboard navigation support for all interactive elements

## API

### Input

**Element:** `HTMLInputElement`

**Arguments**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `classes` | `SlotsToClasses<'base' \| 'innerContainer' \| 'startContent' \| 'endContent' \| 'input'>` | - | Class names for each slot of the component, merged with the theme's. |
| `description` | `string` | - | Help text rendered between the label and the control, and referenced by the ids describedBy returns. |
| `endContentPointerEvents` | `'none' \| 'auto'` | `'auto'` | Controls pointer-events property of endContent. If you want to pass the click event to the input, set it to none. |
| `errors` | `string \| string[]` | - | Validation messages for the field. A non-empty value also marks the control invalid, and an array is joined with ;  when displayed. |
| `isClearable` | `boolean` | - | Whether to include a clear button |
| `isDisabled` | `boolean` | `false` | Whether the field is disabled. FormControl passes this through for styling; the control it wraps is responsible for the disabled attribute. |
| `isInvalid` | `boolean` | `false` | Marks the control invalid without supplying messages, for validation that is reported elsewhere. |
| `isRequired` | `boolean` | `false` | Whether the field is required. Adds an asterisk to the label; it does not set the required attribute on the control itself. |
| `label` | `string` | - | The label text rendered above the control and associated with it via for. Use the :label block instead when the label needs markup. |
| `name` | `string` | - | The name attribute of the underlying input, used when the input is submitted as part of a form. |
| `onBlur` | `() => void` | - | Callback when onblur is triggered |
| `onChange` | `(value: string, event?: InputEvent) => void` | - | Callback when onchange is triggered |
| `onInput` | `(value: string, event?: InputEvent) => void` | - | Callback when oninput is triggered |
| `size` | `'sm' \| 'md' \| 'lg'` | `'md'` | The size of the input and its label. |
| `startContentPointerEvents` | `'none' \| 'auto'` | `'auto'` | Controls pointer-events property of startContent. If you want to pass the click event to the input, set it to none. |
| `type` | `string` | `'text'` | The type attribute of the underlying input element. |
| `value` | `string` | - | The value of the input. Pair with onInput or onChange to control the input; leave it unset to let the element track its own value. |

**Blocks**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `startContent *` | `[]` | - |  |
| `endContent *` | `[]` | - |  |

---

# NativeSelect

Source: /docs/components/forms/native-select.md

# NativeSelect

A select built on the browser's own `<select>` element, styled to match the rest of the form components. Reach for it when you want the platform's picker — the native dropdown on mobile, the OS list box on desktop — instead of the custom listbox that [Select](./select) renders.

## Import

```js
import { NativeSelect } from 'frontile';
```

## Usage

Pass a collection to `@items` and read the selection back from `@onSelectionChange`. Strings and numbers are used as both the key and the label.

```gts preview
import Component from '@glimmer/component';
import { tracked } from '@glimmer/tracking';
import { NativeSelect } from 'frontile';

const animals = ['Cheetah', 'Crocodile', 'Elephant'];

export default class NativeSelectUsage extends Component {
  @tracked selectedKey: string | null = 'Cheetah';

  onSelectionChange = (key: string | null) => {
    this.selectedKey = key;
  };

  <template>
    <div class='demo-stack'>
      <NativeSelect
        @label='Favorite animal'
        @items={{animals}}
        @selectedKey={{this.selectedKey}}
        @onSelectionChange={{this.onSelectionChange}}
      />
      <p class='mt-4 text-sm text-neutral'>Selected: {{this.selectedKey}}</p>
    </div>
  </template>
}
```

The component is controlled. `@selectedKey` is what the user sees selected, so it has to be updated from `@onSelectionChange` — without that, the browser's change is reverted on the next render.

## Items

Objects work too. The key comes from `key` or `id`, and the label from `label`, `value`, `name` or `title`. Anything else needs the `:item` block, which yields the raw item along with an `Item` component to render it with.

```gts preview collapsible
import Component from '@glimmer/component';
import { tracked } from '@glimmer/tracking';
import { NativeSelect } from 'frontile';

const countries = [
  { code: 'br', country: 'Brazil' },
  { code: 'ca', country: 'Canada' },
  { code: 'jp', country: 'Japan' }
];

export default class NativeSelectItemBlock extends Component {
  @tracked selectedKey: string | null = null;

  onSelectionChange = (key: string | null) => {
    this.selectedKey = key;
  };

  <template>
    <div class='demo-stack'>
      <NativeSelect
        @label='Country'
        @items={{countries}}
        @selectedKey={{this.selectedKey}}
        @onSelectionChange={{this.onSelectionChange}}
      >
        <:item as |o|>
          <o.Item @key={{o.item.code}}>{{o.item.country}}</o.Item>
        </:item>
      </NativeSelect>
      <p class='mt-4 text-sm text-neutral'>Selected: {{this.selectedKey}}</p>
    </div>
  </template>
}
```

When the options are a fixed, hand-written list, drop `@items` entirely and use the default block, which yields the same `Item` component.

```gts preview
import Component from '@glimmer/component';
import { tracked } from '@glimmer/tracking';
import { array } from '@ember/helper';
import { NativeSelect } from 'frontile';

export default class NativeSelectStaticItems extends Component {
  @tracked selectedKey: string | null = 'standard';

  onSelectionChange = (key: string | null) => {
    this.selectedKey = key;
  };

  <template>
    <div class='demo-stack'>
      <NativeSelect
        @label='Shipping'
        @selectedKey={{this.selectedKey}}
        @disabledKeys={{(array 'overnight')}}
        @onSelectionChange={{this.onSelectionChange}}
        as |l|
      >
        <l.Item @key='standard'>Standard — 5 business days</l.Item>
        <l.Item @key='express'>Express — 2 business days</l.Item>
        <l.Item @key='overnight'>Overnight — unavailable</l.Item>
      </NativeSelect>
    </div>
  </template>
}
```

`@disabledKeys` renders those options as disabled: still listed, still announced, not selectable.

## Empty Option

A native `<select>` always has something selected, so an initial "nothing chosen" state has to be a real option. `@allowEmpty` adds one, labeled with `@placeholder`, and picking it reports `null`.

```gts preview
import Component from '@glimmer/component';
import { tracked } from '@glimmer/tracking';
import { NativeSelect } from 'frontile';

const roles = ['Owner', 'Editor', 'Viewer'];

export default class NativeSelectAllowEmpty extends Component {
  @tracked selectedKey: string | null = null;

  onSelectionChange = (key: string | null) => {
    this.selectedKey = key;
  };

  <template>
    <div class='demo-stack'>
      <NativeSelect
        @label='Role'
        @items={{roles}}
        @allowEmpty={{true}}
        @placeholder='Select a role'
        @selectedKey={{this.selectedKey}}
        @onSelectionChange={{this.onSelectionChange}}
      />
      <p class='mt-4 text-sm text-neutral'>Selected:
        {{if this.selectedKey this.selectedKey 'none'}}</p>
    </div>
  </template>
}
```

## Multiple Selection

`@selectionMode='multiple'` renders the native multi-select list box. The state arguments change with it: use `@selectedKeys` instead of `@selectedKey`, and `@onSelectionChange` receives an array. Mixing them logs a warning.

```gts preview
import Component from '@glimmer/component';
import { tracked } from '@glimmer/tracking';
import { NativeSelect } from 'frontile';

const languages = ['Elixir', 'Go', 'Rust', 'TypeScript'];

export default class NativeSelectMultiple extends Component {
  @tracked selectedKeys: string[] = ['Rust'];

  onSelectionChange = (keys: string[]) => {
    this.selectedKeys = keys;
  };

  <template>
    <div class='demo-stack'>
      <NativeSelect
        @label='Languages'
        @description='Hold Cmd or Ctrl to select more than one.'
        @selectionMode='multiple'
        @items={{languages}}
        @selectedKeys={{this.selectedKeys}}
        @onSelectionChange={{this.onSelectionChange}}
      />
    </div>
  </template>
}
```

## Sizes

`@size` accepts `sm`, `md` (the default) and `lg`, matching the other form controls.

```gts preview
import { array, concat } from '@ember/helper';
import { NativeSelect } from 'frontile';

const plans = ['Basic', 'Pro'];

<template>
  <div class='demo-stack'>
    {{#each (array 'sm' 'md' 'lg') as |size|}}
      <NativeSelect
        @label={{concat 'Plan (' size ')'}}
        @size={{size}}
        @items={{plans}}
      />
    {{/each}}
  </div>
</template>
```

## Description and Validation

NativeSelect is built on the same `FormControl` as the other form components, so `@label`, `@description`, `@isRequired`, `@errors` and `@isInvalid` behave identically. Errors are wired to the control through `aria-describedby` and set `aria-invalid`.

```gts preview
import { array } from '@ember/helper';
import { NativeSelect } from 'frontile';

const environments = ['Development', 'Staging', 'Production'];

<template>
  <div class='demo-stack'>
    <NativeSelect
      @label='Environment'
      @description='Where the build will be deployed.'
      @isRequired={{true}}
      @items={{environments}}
    />

    <NativeSelect
      @label='Environment'
      @errors={{(array 'Select an environment to continue.')}}
      @allowEmpty={{true}}
      @placeholder='Select an environment'
      @items={{environments}}
    />
  </div>
</template>
```

## Start and End Content

The `:startContent` and `:endContent` named blocks place content inside the control. The chevron the component draws stays at the end, after whatever `:endContent` yields.

By default pointer events pass through end content to the select and are captured by start content; `@startContentPointerEvents` and `@endContentPointerEvents` flip that when the content itself needs to be clickable.

```gts preview
import { NativeSelect } from 'frontile';
import { SearchIcon } from 'site/components/icons';

const teams = ['Design', 'Engineering', 'Support'];

<template>
  <div class='demo-stack'>
    <NativeSelect @label='Team' @items={{teams}}>
      <:startContent>
        <SearchIcon class='size-icon-md text-neutral' />
      </:startContent>
    </NativeSelect>
  </div>
</template>
```

## Accessibility

NativeSelect renders a real `<select>`, so keyboard behavior, type-ahead and the mobile picker are the browser's own and match whatever the user's platform does elsewhere. That is the main reason to choose it over `Select`.

| Key                                                                                    | Behavior                                          |
| -------------------------------------------------------------------------------------- | ------------------------------------------------- |
| <kbd>Space</kbd> / <kbd>Alt</kbd> + <kbd>↓</kbd>                                       | Open the picker (browser dependent)               |
| <kbd>↑</kbd> / <kbd>↓</kbd>                                                            | Move through options                              |
| <kbd>Home</kbd> / <kbd>End</kbd>                                                       | First / last option                               |
| Printable characters                                                                   | Jump to the option starting with those characters |
| <kbd>Enter</kbd> / <kbd>Esc</kbd>                                                      | Commit / dismiss the open picker                  |
| <kbd>Cmd</kbd> / <kbd>Ctrl</kbd> + click, <kbd>Shift</kbd> + <kbd>↑</kbd>/<kbd>↓</kbd> | Extend the selection in `multiple` mode           |

The component's own responsibilities:

- `@label` renders a `<label>` bound to the select by `id`. Always provide it — there is no visual affordance that substitutes for it, and an unlabeled select is announced only by its current value.
- `@description` and `@errors` are referenced through `aria-describedby`, and an invalid control gets `aria-invalid="true"`.
- `@disabledKeys` sets the `disabled` attribute on the corresponding `<option>`, which screen readers announce as unavailable.
- The chevron is decorative and is not exposed to assistive technology.

For multiple selection, say so in `@description` as the demo above does: nothing in the native list box announces that Cmd or Ctrl extends the selection, and it is the most commonly missed interaction in the component.

## API

### NativeSelect

**Element:** `Array`

**Arguments**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `allowEmpty` | `boolean` | `false` | Renders an extra empty option, letting the user clear the selection. Label it with the placeholder argument. |
| `classes` | `SlotsToClasses<'icon' \| 'base' \| 'innerContainer' \| 'startContent' \| 'endContent' \| 'input'>` | - | Per-slot class overrides: base, innerContainer, input, startContent, endContent and icon. |
| `description` | `string` | - | Help text rendered between the label and the control, and referenced by the ids describedBy returns. |
| `disabledKeys` | `string[]` | - | Keys of the options that cannot be selected. Disabled options are still rendered and announced, they just cannot be picked. |
| `endContentPointerEvents` | `'none' \| 'auto'` | `'none'` | Controls pointer-events property of endContent. Defauled to none to pass the click event to the input. If your content needs to capture events, consider adding pointer-events-auto class to that element only. |
| `errors` | `string \| string[]` | - | Validation messages for the field. A non-empty value also marks the control invalid, and an array is joined with ;  when displayed. |
| `id` | `string` | - | Id applied to the select element and referenced by its label. One is generated when omitted. |
| `isDisabled` | `boolean` | `false` | Whether the field is disabled. FormControl passes this through for styling; the control it wraps is responsible for the disabled attribute. |
| `isInvalid` | `boolean` | `false` | Marks the control invalid without supplying messages, for validation that is reported elsewhere. |
| `isRequired` | `boolean` | `false` | Whether the field is required. Adds an asterisk to the label; it does not set the required attribute on the control itself. |
| `items` | `T[]` | - | Collection used to render the options. Strings and numbers become both the key and the label; objects use key or id for the key and label, value, name or title for the label. Use the :item block when your data does not follow those conventions. |
| `label` | `string` | - | The label text rendered above the control and associated with it via for. Use the :label block instead when the label needs markup. |
| `name` | `string` | - | Name of the select element, used when the surrounding form is submitted. |
| `onAction` | `(key: string) => void` | - | Called with the key of an option whenever it is acted upon, including when the same option is picked again. Use onSelectionChange to track state. |
| `onItemsChange` | `(items: ListItem[], action: 'add' \| 'remove') => void` | - | _(internal)_ |
| `onSelectionChange` | `((key: string) => void) \| ((keys: string[]) => void)` | - | Called with the newly selected key, or null when the selection is cleared through the allowEmpty option. Called with every selected key each time the selection changes. |
| `placeholder` | `string` | - | Placeholder text used when allowEmpty is set to true. |
| `selectedKey` | `string` | - | The selected key in single selection mode. The component is controlled: update this from onSelectionChange. Not available in multiple selection mode; use selectedKeys. |
| `selectedKeys` | `string[]` | - | Not available in single selection mode; use selectedKey. The selected keys in multiple selection mode. The component is controlled: update this from onSelectionChange. |
| `selectionMode` | `'single' \| 'multiple'` | `'single' 'single'` | Whether one option or several can be selected. Multiple renders the native multi-select list box and switches to selectedKeys. |
| `size` | `'sm' \| 'md' \| 'lg'` | `'md'` | The size of the control. |
| `startContentPointerEvents` | `'none' \| 'auto'` | `'auto'` | Controls pointer-events property of startContent. If you want to pass the click event to the input, set it to none. |

**Blocks**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `item *` | `[{ item: T; key: string; label: string; Item: NativeSelectItem (manager, item bound); }]` | - |  |
| `default *` | `[{ Item: NativeSelectItem (manager bound); }]` | - |  |
| `startContent *` | `[]` | - |  |
| `endContent *` | `[]` | - |  |
### NativeSelectItem

**Element:** `HTMLOptionElement`

**Arguments**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `key *` | `string` | - | Value of the rendered option, and the key reported by onSelectionChange, selectedKey or selectedKeys, and disabledKeys. |
| `manager *` | `ListManager` | - | The ListManager that tracks selection for the parent select. It is bound for you on the yielded Item component. |
| `item` | `unknown` | - | The entry of @items this option renders, remembered on the registered list item so a selection can hand it back. Bound for you on the Item yielded from the :item block; block-form options have no such entry. |
| `textValue` | `string` | - | Text representation of the option, used for matching. Defaults to the option's rendered text content. |

**Blocks**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `default *` | `[]` | - |  |
| `selectedIcon *` | `[]` | - |  |
| `start *` | `[]` | - |  |
| `end *` | `[]` | - |  |

---

# Radio Group

Source: /docs/components/forms/radio-group.md

# Radio Group

A radio group component that allows users to select a single option from a group of choices. RadioGroup integrates with the Form and Field components for automatic data binding and validation. Unlike CheckboxGroup, RadioGroup supports field-level validation (validates on change/blur/input events), providing immediate feedback to users.

## Import

```js
import { RadioGroup } from 'frontile';
```

## Usage

### Basic Radio Group

The most basic usage of the RadioGroup component with a label and options.

```gts preview
import { RadioGroup } from 'frontile';

<template>
  <div class='demo-stack'>
    <RadioGroup @name='interests' @label='Interests' as |Radio|>
      <Radio @label='Music' @value='music' />
      <Radio @label='Sports' @value='sports' />
      <Radio @label='Technology' @value='technology' />
    </RadioGroup>
  </div>
</template>
```

> **Modern Usage:** For most use cases, prefer using RadioGroup with the Form and Field components. This provides automatic data binding, validation, and state management without manual `@onChange` handlers.

> **Field-Level Validation:** RadioGroup supports field-level validation that runs on change/blur/input events based on the Form's `@validateOn` setting. This provides immediate feedback as users make selections. This differs from CheckboxGroup, which only validates on form submit.

### Controlled with Form/Field

The recommended pattern for using RadioGroup is with Form and Field components, which provides automatic data binding and state management.

```gts preview
import Component from '@glimmer/component';
import { tracked } from '@glimmer/tracking';
import { Form, type FormResultData } from 'frontile';

export default class ControlledRadioGroup extends Component {
  @tracked formData = { theme: '' };

  handleFormChange = (result: FormResultData) => {
    this.formData = result.data;
  };

  <template>
    <div class='demo-stack'>
      <Form @data={{this.formData}} @onChange={{this.handleFormChange}} as |form|>
        <form.Field @name='theme' as |field|>
          <field.RadioGroup @label='Theme Preference' as |Radio|>
            <Radio @label='Light Mode' @value='light' />
            <Radio @label='Dark Mode' @value='dark' />
            <Radio @label='System Default' @value='system' />
          </field.RadioGroup>
        </form.Field>
      </Form>

      <div class='p-3 border border-neutral-soft rounded'>
        <p class='text-sm'>Selected theme: <strong>{{this.formData.theme}}</strong></p>
      </div>
    </div>
  </template>
}
```


### Form Validation

RadioGroup integrates with Form validation through Valibot schemas. It supports field-level validation that runs on change events based on the `@validateOn` setting, providing feedback as users make selections.

```gts preview collapsible
import Component from '@glimmer/component';
import { tracked } from '@glimmer/tracking';
import { array } from '@ember/helper';
import { Form, type FormResultData } from 'frontile';
import { Button } from 'frontile';
import * as v from 'valibot';

const schema = v.object({
  fullName: v.pipe(
    v.string(),
    v.nonEmpty('Full name is required'),
    v.minLength(2, 'Name must be at least 2 characters')
  ),
  experience: v.pipe(
    v.fallback(v.string(), ''),
    v.string(),
    v.nonEmpty('Please select your experience level')
  ),
  newsletter: v.boolean()
});

type Schema = v.InferOutput<typeof schema>;

export default class FormValidation extends Component {
  @tracked formData: Schema = {
    fullName: '',
    experience: '',
    newsletter: false
  };

  handleFormChange = (result: FormResultData<Schema>) => {
    this.formData = result.data;
  };

  handleSubmit = (result: FormResultData<Schema>) => {
    console.log('Form submitted successfully:', result.data);
  };

  <template>
    <div class='demo-stack'>
      <Form
        @data={{this.formData}}
        @schema={{schema}}
        @onChange={{this.handleFormChange}}
        @onSubmit={{this.handleSubmit}}
        @validateOn={{array 'change' 'submit'}}
        as |form|
      >
        <form.Field @name='fullName' as |field|>
          <field.Input @label='Full Name' @isRequired={{true}} />
        </form.Field>

        <form.Field @name='experience' as |field|>
          <field.RadioGroup
            @label='Experience Level'
            @isRequired={{true}}
            as |Radio|
          >
            <Radio
              @label='Junior'
              @value='junior'
              @description='0-2 years of experience'
            />
            <Radio
              @label='Mid-level'
              @value='mid'
              @description='3-5 years of experience'
            />
            <Radio
              @label='Senior'
              @value='senior'
              @description='5+ years of experience'
            />
          </field.RadioGroup>
        </form.Field>

        <form.Field @name='newsletter' as |field|>
          <field.Checkbox @label='Subscribe to our newsletter' />
        </form.Field>

        <Button type='submit'>Submit Application</Button>
      </Form>
    </div>
  </template>
}
```

### Additional Features and Styling

The RadioGroup component supports various optional configurations for layout, sizing, descriptions, and custom styling.

```gts preview collapsible
import { RadioGroup } from 'frontile';
import { hash } from '@ember/helper';

<template>
  <div class='demo-stack'>
    {{! Orientation }}
    <div>
      <h4 class='text-sm font-medium mb-2'>Orientation</h4>
      <p class='text-sm text-neutral mb-3'>
        RadioGroup supports vertical (default) and horizontal orientations. This is a RadioGroup-specific feature.
      </p>
      <div class='flex flex-col gap-3'>
        <RadioGroup
          @name='orientation-vertical'
          @label='Vertical Layout (Default)'
          @orientation='vertical'
          as |Radio|
        >
          <Radio @label='Option 1' @value='option1' />
          <Radio @label='Option 2' @value='option2' />
          <Radio @label='Option 3' @value='option3' />
        </RadioGroup>

        <RadioGroup
          @name='orientation-horizontal'
          @label='Horizontal Layout'
          @orientation='horizontal'
          as |Radio|
        >
          <Radio @label='Small' @value='sm' />
          <Radio @label='Medium' @value='md' />
          <Radio @label='Large' @value='lg' />
          <Radio @label='Extra Large' @value='xl' />
        </RadioGroup>
      </div>
    </div>

    {{! Size variants }}
    <div>
      <h4 class='text-sm font-medium mb-2'>Size Variants</h4>
      <div class='flex flex-col gap-3'>
        <RadioGroup @name='size-small' @label='Small Size' @size='sm' as |Radio|>
          <Radio @label='Option A' @value='a' />
          <Radio @label='Option B' @value='b' />
        </RadioGroup>

        <RadioGroup @name='size-medium' @label='Medium Size' @size='md' as |Radio|>
          <Radio @label='Option A' @value='a' />
          <Radio @label='Option B' @value='b' />
        </RadioGroup>

        <RadioGroup @name='size-large' @label='Large Size' @size='lg' as |Radio|>
          <Radio @label='Option A' @value='a' />
          <Radio @label='Option B' @value='b' />
        </RadioGroup>
      </div>
    </div>

    {{! Descriptions }}
    <div>
      <h4 class='text-sm font-medium mb-2'>Descriptions</h4>
      <p class='text-sm text-neutral mb-3'>
        RadioGroup supports descriptions at both the group and individual radio level.
      </p>
      <div class='flex flex-col gap-3'>
        <RadioGroup
          @name='theme-preference'
          @label='Theme Preference'
          @description="Choose how you'd like the interface to appear. You can change this later in settings."
          as |Radio|
        >
          <Radio @label='Light' @value='light' />
          <Radio @label='Dark' @value='dark' />
          <Radio @label='System' @value='system' />
        </RadioGroup>

        <RadioGroup @name='subscription-plan' @label='Choose your subscription plan' as |Radio|>
          <Radio
            @label='Basic'
            @value='basic'
            @description='Perfect for individuals getting started. Includes basic features.'
          />
          <Radio
            @label='Pro'
            @value='pro'
            @description='Great for professionals. Includes advanced features and priority support.'
          />
          <Radio
            @label='Enterprise'
            @value='enterprise'
            @description='For large teams. Includes all features, dedicated support, and custom integrations.'
          />
        </RadioGroup>
      </div>
    </div>

    {{! Custom styling }}
    <div>
      <h4 class='text-sm font-medium mb-2'>Custom Styling</h4>
      <RadioGroup
        @name='custom-styled'
        @label='Custom Styled Radio Group'
        @classes={{hash
          base='my-custom-radio-group'
          label='my-custom-label'
          optionsContainer='my-custom-options-container'
        }}
        as |Radio|
      >
        <Radio @label='Option 1' @value='option1' />
        <Radio @label='Option 2' @value='option2' />
        <Radio @label='Option 3' @value='option3' />
      </RadioGroup>
    </div>
  </div>
</template>
```

## Accessibility

The RadioGroup component follows accessibility best practices:

- Proper grouping with fieldset/legend semantics via FormControl
- Unique `name` attribute ensures radio buttons work as a group
- Proper label association for each radio option
- ARIA attributes for invalid states (`aria-invalid`)
- Descriptive text association using `aria-describedby`
- Support for required field indication
- Keyboard navigation follows standard radio group patterns (arrow keys to navigate between options)
- Screen reader announcements for group label, individual option labels, and validation messages

## API

### RadioGroup

**Element:** `HTMLDivElement`

**Arguments**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `classes` | `SlotsToClasses<'label' \| 'base' \| 'optionsContainer'>` | - | Class names for each slot of the component, merged with the theme's. |
| `description` | `string` | - | Help text rendered between the label and the control, and referenced by the ids describedBy returns. |
| `errors` | `string \| string[]` | - | Validation messages for the field. A non-empty value also marks the control invalid, and an array is joined with ;  when displayed. |
| `isDisabled` | `boolean` | `false` | Whether the field is disabled. FormControl passes this through for styling; the control it wraps is responsible for the disabled attribute. |
| `isInvalid` | `boolean` | `false` | Marks the control invalid without supplying messages, for validation that is reported elsewhere. |
| `isRequired` | `boolean` | `false` | Whether the field is required. Adds an asterisk to the label; it does not set the required attribute on the control itself. |
| `label` | `string` | - | The label text rendered above the control and associated with it via for. Use the :label block instead when the label needs markup. |
| `name` | `string` | - | The name attribute applied to every radio in the group, which is what makes the browser treat them as mutually exclusive. |
| `onChange` | `(value: T, event: Event) => void` | - | Callback when the selected radio changes, receiving the new value. |
| `orientation` | `'horizontal' \| 'vertical'` | `'vertical'` | How the radios are laid out. |
| `size` | `'sm' \| 'md' \| 'lg'` | - | The size applied to every radio in the group and to the group's label. |
| `value` | `T` | - | The currently selected value. Pair with onChange to control the group. |

**Blocks**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `default *` | `[Radio: Radio (name, onChange, checkedValue, isDisabled bound)]` | - |  |

---

# Radio

Source: /docs/components/forms/radio.md

# Radio

A radio button component that allows users to select a single option from a group of choices. Radio components integrate with the Form and Field components for automatic data binding and validation. For grouped radio buttons, use RadioGroup which provides built-in grouping and state management.

## Import

```js
import { Radio } from 'frontile';
```

## Usage

### Basic Radio

The most basic usage of a Radio component with a label and value.

```gts preview
import { Radio } from 'frontile';

<template>
  <div class='demo-stack'>
    <Radio @name='terms' @label='Accept Terms' @value='accepted' />
  </div>
</template>
```

> **Modern Usage:** For most use cases, prefer using Radio components with the Form and Field components. This provides automatic data binding, validation, and state management without manual `@onChange` handlers. See the "Controlled with Form/Field" example below.

> **RadioGroup vs Individual Radio:** When you have multiple related radio options, use `field.RadioGroup` which automatically manages the grouping and state. Individual `field.Radio` components require manual `@value` specification on each radio button.

### Controlled with Form/Field

You can control the radio state using the Form component's data binding system. The Form automatically manages the radio value and updates.

```gts preview
import Component from '@glimmer/component';
import { tracked } from '@glimmer/tracking';
import { Form, type FormResultData } from 'frontile';

export default class ControlledRadio extends Component {
  @tracked formData = { newsletter: '' };

  handleFormChange = (result: FormResultData) => {
    this.formData = result.data;
  };

  <template>
    <div class='demo-stack'>
      <Form @data={{this.formData}} @onChange={{this.handleFormChange}} as |form|>
        <form.Field @name='newsletter' as |field|>
          <field.RadioGroup @label='Newsletter Preference' as |Radio|>
            <Radio @label='Daily Digest' @value='daily' />
            <Radio @label='Weekly Summary' @value='weekly' />
            <Radio @label='No Newsletter' @value='none' />
          </field.RadioGroup>
        </form.Field>
      </Form>

      <div class='p-3 border border-neutral-soft rounded'>
        <p class='text-sm'>Selected: {{this.formData.newsletter}}</p>
      </div>
    </div>
  </template>
}
```

### Form Validation

> **Field-Level Validation:** RadioGroup supports field-level validation that runs on change events based on the Form's `@validateOn` setting, providing immediate feedback.

RadioGroup integrates with Form validation through Valibot schemas. The Form component handles validation automatically and displays errors through the Field component. This example shows RadioGroup alongside other form fields:

```gts preview collapsible
import Component from '@glimmer/component';
import { tracked } from '@glimmer/tracking';
import { Form, type FormResultData } from 'frontile';
import { Button } from 'frontile';
import { array } from '@ember/helper';
import * as v from 'valibot';

const schema = v.object({
  fullName: v.pipe(
    v.string(),
    v.nonEmpty('Full name is required'),
    v.minLength(2, 'Name must be at least 2 characters')
  ),
  email: v.pipe(
    v.string(),
    v.nonEmpty('Email is required'),
    v.email('Please enter a valid email address')
  ),
  experience: v.pipe(
    v.fallback(v.string(), ''),
    v.string(),
    v.nonEmpty('Please select your experience level')
  ),
  remoteWork: v.boolean()
});

type Schema = v.InferOutput<typeof schema>;

export default class FormValidationExample extends Component {
  @tracked formData: Schema = {
    fullName: '',
    email: '',
    experience: '',
    remoteWork: false
  };

  handleFormChange = (result: FormResultData<Schema>) => {
    this.formData = result.data;
  };

  handleSubmit = (result: FormResultData<Schema>) => {
    console.log('Application submitted successfully:', result.data);
  };

  <template>
    <div class='demo-stack'>
      <Form
        @data={{this.formData}}
        @schema={{schema}}
        @onChange={{this.handleFormChange}}
        @onSubmit={{this.handleSubmit}}
        @validateOn={{array 'change' 'submit'}}
        as |form|
      >
        <div class='flex flex-col gap-4'>
          <form.Field @name='fullName' as |field|>
            <field.Input @label='Full Name' @isRequired={{true}} />
          </form.Field>

          <form.Field @name='email' as |field|>
            <field.Input
              @label='Email Address'
              @type='email'
              @isRequired={{true}}
            />
          </form.Field>

          <form.Field @name='experience' as |field|>
            <field.RadioGroup @label='Experience Level' @isRequired={{true}} as |Radio|>
              <Radio @label='Junior (0-2 years)' @value='junior' />
              <Radio @label='Mid-level (3-5 years)' @value='mid' />
              <Radio @label='Senior (5+ years)' @value='senior' />
            </field.RadioGroup>
          </form.Field>

          <form.Field @name='remoteWork' as |field|>
            <field.Checkbox @label='Open to remote work' />
          </form.Field>

          <div>
            <Button type='submit'>Submit Application</Button>
          </div>
        </div>
      </Form>
    </div>
  </template>
}
```

### Miscellaneous Options

The Radio component supports various optional configurations for sizing, states, descriptions, layout, and styling.

```gts preview collapsible
import { Radio, RadioGroup } from 'frontile';
import { hash } from '@ember/helper';

<template>
  <div class='demo-stack'>
    {{! Size variants }}
    <div>
      <h4 class='text-sm font-medium mb-2'>Size Variants</h4>
      <div class='flex flex-col gap-3'>
        <RadioGroup @name='sizeSmall' @label='Small Size' @size='sm' as |Radio|>
          <Radio @label='Option A' @value='a' />
          <Radio @label='Option B' @value='b' />
        </RadioGroup>
        <RadioGroup @name='sizeMedium' @label='Medium Size' @size='md' as |Radio|>
          <Radio @label='Option A' @value='a' />
          <Radio @label='Option B' @value='b' />
        </RadioGroup>
        <RadioGroup @name='sizeLarge' @label='Large Size' @size='lg' as |Radio|>
          <Radio @label='Option A' @value='a' />
          <Radio @label='Option B' @value='b' />
        </RadioGroup>
      </div>
    </div>

    {{! Disabled state }}
    <div>
      <h4 class='text-sm font-medium mb-2'>Disabled State</h4>
      <RadioGroup @name='subscription' @label='Subscription Plan' @value='basic' disabled={{true}} as |Radio|>
        <Radio @label='Basic Plan - $9/month' @value='basic' />
        <Radio @label='Pro Plan - $19/month' @value='pro' />
        <Radio @label='Enterprise Plan - $49/month' @value='enterprise' />
      </RadioGroup>
    </div>

    {{! With description }}
    <div>
      <h4 class='text-sm font-medium mb-2'>With Description</h4>
      <RadioGroup @name='plan' @label='Choose your subscription plan' as |Radio|>
        <Radio
          @label='Basic'
          @value='basic'
          @description='Perfect for individuals getting started. Includes basic features.'
        />
        <Radio
          @label='Pro'
          @value='pro'
          @description='Great for professionals. Includes advanced features and priority support.'
        />
        <Radio
          @label='Enterprise'
          @value='enterprise'
          @description='For large teams. Includes all features, dedicated support, and custom integrations.'
        />
      </RadioGroup>
    </div>

    {{! Horizontal layout }}
    <div>
      <h4 class='text-sm font-medium mb-2'>Horizontal Layout</h4>
      <RadioGroup @name='rating' @label='Rating' @orientation='horizontal' as |Radio|>
        <Radio @label='Poor' @value='poor' />
        <Radio @label='Fair' @value='fair' />
        <Radio @label='Good' @value='good' />
        <Radio @label='Excellent' @value='excellent' />
      </RadioGroup>
    </div>

    {{! Custom styling }}
    <div>
      <h4 class='text-sm font-medium mb-2'>Custom Styling</h4>
      <Radio
        @name='custom-styled'
        @label='Custom Styled Radio'
        @value='custom'
        @classes={{hash
          base='my-custom-radio-base'
          input='my-custom-radio-input'
          labelContainer='my-custom-label-container'
          label='my-custom-radio-label'
        }}
      />
    </div>
  </div>
</template>
```

## Accessibility

The Radio component follows accessibility best practices:

- Proper label association using `for` and `id` attributes
- ARIA attributes for invalid states (`aria-invalid`)
- Descriptive text association using `aria-describedby`
- Support for required field indication
- Keyboard navigation follows standard radio button patterns
- Screen reader announcements for labels, descriptions, and validation messages
- Proper focus management and visual focus indicators

## API

### Radio

**Element:** `HTMLInputElement`

**Arguments**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `value *` | `T` | - | The value this radio represents. It is passed to onChange when the radio is selected, and compared against checkedValue to decide whether it is. |
| `checkedValue` | `T` | - | The currently selected value of the group. This radio renders as checked when it equals value. Usually supplied by RadioGroup rather than set directly. |
| `classes` | `SlotsToClasses<'label' \| 'base' \| 'input' \| 'labelContainer'>` | - | Class names for each slot of the component, merged with the theme's. |
| `description` | `string` | - | Help text rendered between the label and the control, and referenced by the ids describedBy returns. |
| `errors` | `string \| string[]` | - | Validation messages for the field. A non-empty value also marks the control invalid, and an array is joined with ;  when displayed. |
| `isDisabled` | `boolean` | `false` | Whether the field is disabled. FormControl passes this through for styling; the control it wraps is responsible for the disabled attribute. |
| `isInvalid` | `boolean` | `false` | Marks the control invalid without supplying messages, for validation that is reported elsewhere. |
| `isRequired` | `boolean` | `false` | Whether the field is required. Adds an asterisk to the label; it does not set the required attribute on the control itself. |
| `label` | `string` | - | The label text rendered above the control and associated with it via for. Use the :label block instead when the label needs markup. |
| `name` | `string` | - | The name attribute shared by the radios in a group, which is what makes the browser treat them as mutually exclusive. |
| `onBlur` | `() => void` | - | Callback when onblur is triggered |
| `onChange` | `(value: T, event: Event) => void` | - | Callback when onchange is triggered |
| `size` | `'sm' \| 'md' \| 'lg'` | `'md'` | The size of the radio and its label. |

---

# Select

Source: /docs/components/forms/select.md

# Select

`Select` is a dropdown component. It supports both **single** and **multiple** selection modes — multiple selections render as removable chips — provides built‐in filtering, and renders a hidden native `<select>` element for accessibility. It is built on the [Listbox](https://frontile.dev/docs/collections/listbox) and [Popover](https://frontile.dev/docs/overlays/popover) components.

## Import

```js
import { Select } from 'frontile';
```

## Usage

### Basic Single Select

The most basic usage of a single-select dropdown with static options.

```gts preview
import { Select } from 'frontile';

const options = ['Option 1', 'Option 2', 'Option 3'];

<template>
  <div class='demo-stack'>
    <Select @placeholder='Select an option' @items={{options}} />
  </div>
</template>
```

> **Modern Usage:** For forms with data binding and validation, use the Form and Field components as shown in the examples below. Form/Field provides automatic state management, validation, and error handling without manual `@onChange` handlers.

### Colors

Use `@color` to color the highlighted and selected options in the dropdown. Open each
Select to see how the active option adopts the color. Available colors are
`default`, `primary`, `secondary`, `tertiary`, `success`, `warning`, and `danger`.

```gts preview
import { Select } from 'frontile';

const options = ['Option 1', 'Option 2', 'Option 3'];

<template>
  <div class='demo-stack'>
    <div class='grid grid-cols-2 gap-4'>
      <Select @color='neutral' @placeholder='Default' @items={{options}} />
      <Select @color='primary' @placeholder='Primary' @items={{options}} />
      <Select @color='secondary' @placeholder='Secondary' @items={{options}} />
      <Select @color='tertiary' @placeholder='Tertiary' @items={{options}} />
      <Select @color='success' @placeholder='Success' @items={{options}} />
      <Select @color='warning' @placeholder='Warning' @items={{options}} />
      <Select @color='danger' @placeholder='Danger' @items={{options}} />
    </div>
  </div>
</template>
```

### Data Binding with Form/Field

When working with forms, the Form component automatically manages the selected value and provides data binding:

```gts preview collapsible
import Component from '@glimmer/component';
import { tracked } from '@glimmer/tracking';
import { Form, type FormResultData } from 'frontile';

const options = ['Option 1', 'Option 2', 'Option 3'];

export default class DataBoundSingleSelect extends Component {
  @tracked formData = { selectedOption: '' };

  handleFormChange = (result: FormResultData) => {
    this.formData = result.data;
  };

  <template>
    <div class='demo-stack'>
      <Form
        @data={{this.formData}}
        @onChange={{this.handleFormChange}}
        as |form|
      >
        <form.Field @name='selectedOption' as |field|>
          <field.SingleSelect
            @placeholder='Select an option'
            @items={{options}}
          />
        </form.Field>
      </Form>
      <p>Selected: {{this.formData.selectedOption}}</p>
    </div>
  </template>
}
```

### Form Validation

The Select component integrates seamlessly with form validation by automatically displaying error messages and updating ARIA attributes. This example demonstrates both single and multiple select validation using Valibot schemas with the Form component. The example uses `@validateOn` to trigger validation on both change and submit events, providing immediate feedback as users make selections.

The multiple select here is shown in a validation context; see [Multiple Selection](#multiple-selection) for the full reference on chips, removal and the arguments that configure them.

With `blur` in `@validateOn` (or your own `@onBlur`), the Select reports blur only once
focus has left the **whole control** — the field and its dropdown. Clicking an option
moves focus into the dropdown, and in multiple mode leaves it open, so selecting is never
reported as a blur: validation waits until the user is actually done with the field.

In multiple selection mode there is one extra step. The dropdown stays open across
selections, so the click that takes the user away from the field is first spent closing
it — and closing the dropdown returns focus to the trigger. Focus is therefore still
inside the control at that point, and `@onBlur` does not fire; it fires on the next
interaction, once focus leaves. Blur validation on a multiple Select runs one
interaction later than on a single one.

```gts preview collapsible
import Component from '@glimmer/component';
import { tracked } from '@glimmer/tracking';
import { array } from '@ember/helper';
import { Form, type FormResultData } from 'frontile';
import { Button } from 'frontile';
import * as v from 'valibot';

const countries = [
  'United States',
  'Canada',
  'Mexico',
  'United Kingdom',
  'Germany',
  'France',
  'Japan',
  'Australia'
];
const interests = [
  { key: 'tech', label: 'Technology' },
  { key: 'sports', label: 'Sports' },
  { key: 'music', label: 'Music' },
  { key: 'art', label: 'Art' },
  { key: 'travel', label: 'Travel' }
];

// Define validation schema
const schema = v.object({
  country: v.pipe(
    v.fallback(v.string(), ''),
    v.nonEmpty('Please select a country')
  ),
  interests: v.pipe(
    v.array(v.string()),
    v.minLength(1, 'Please select at least one interest'),
    v.maxLength(3, 'Please select no more than 3 interests')
  )
});

type Schema = v.InferOutput<typeof schema>;

export default class SelectFormValidation extends Component {
  @tracked formData = {
    country: '',
    interests: [] as string[]
  };
  @tracked submitMessage = '';

  handleFormChange = (data: FormResultData<Schema>) => {
    this.formData = data.data;
    this.submitMessage = '';
  };

  handleFormSubmit = (data: FormResultData<Schema>) => {
    this.submitMessage = 'Form submitted successfully!';
    console.log('Submitted data:', data.data);
  };

  <template>
    <div class='demo-stack'>
      <Form
        @data={{this.formData}}
        @schema={{schema}}
        @onChange={{this.handleFormChange}}
        @onSubmit={{this.handleFormSubmit}}
        @validateOn={{array 'change' 'submit'}}
        as |form|
      >
        <div class='flex flex-col gap-4'>
          <form.Field @name='country' as |field|>
            <field.SingleSelect
              @label='Country'
              @description='Select your country of residence'
              @placeholder='Choose a country'
              @items={{countries}}
              @isRequired={{true}}
              @allowEmpty={{true}}
            />
          </form.Field>

          <form.Field @name='interests' as |field|>
            <field.MultiSelect
              @label='Interests'
              @description='Select 1-3 areas of interest'
              @placeholder='Choose your interests'
              @items={{interests}}
              @isRequired={{true}}
            >
              <:item as |o|>
                <o.Item>
                  {{o.label}}
                </o.Item>
              </:item>
            </field.MultiSelect>
          </form.Field>

          <Button type='submit'>Submit</Button>
        </div>
      </Form>

      {{#if this.submitMessage}}
        <div class='p-4 bg-success-subtle border border-success-subtle rounded'>
          <p class='text-success-strong'>{{this.submitMessage}}</p>
          <div class='mt-2 text-sm'>
            <p><strong>Country:</strong> {{this.formData.country}}</p>
            <p><strong>Interests:</strong> {{this.formData.interests}}</p>
          </div>
        </div>
      {{/if}}
    </div>
  </template>
}
```

### Filterable Select

Enable filtering so users can quickly search through the options. Filtering only applies when options are provided via the `@items` argument. Options are ranked by relevance, so the closest match is listed first; pass `@filter` to score or match them yourself. The Select component works seamlessly with Form/Field data binding while providing search functionality:

```gts preview collapsible
import Component from '@glimmer/component';
import { tracked } from '@glimmer/tracking';
import { Form, type FormResultData } from 'frontile';

const countries = [
  'Argentina',
  'Brazil',
  'Canada',
  'Denmark',
  'Egypt',
  'France',
  'Germany',
  'Italy',
  'Japan',
  'Mexico'
];

export default class FilterableSelect extends Component {
  @tracked formData = { country: '' };

  handleFormChange = (result: FormResultData) => {
    this.formData = result.data;
  };

  <template>
    <div class='demo-stack'>
      <Form
        @data={{this.formData}}
        @onChange={{this.handleFormChange}}
        as |form|
      >
        <form.Field @name='country' as |field|>
          <field.SingleSelect
            @isFilterable={{true}}
            @placeholder='Select a country'
            @items={{countries}}
          />
        </form.Field>
      </Form>
      <p>Selected: {{this.formData.country}}</p>
    </div>
  </template>
}
```

### Item Object Format

When using the `@items` argument, you can pass items as either primitives (strings or numbers) or objects. The `Select` component automatically extracts a key and label for each item using a flexible approach:

- **Key Extraction:**  
  The component first checks for a `key` property. If not present, it will look for an `id` property. If neither is available, it falls back to the string representation of the item.

- **Label Extraction:**  
  For the label, the component checks in order for `label`, `value`, `name`, or `title`. If none of these properties exist, it uses the string representation of the item.

This supports common object shapes such as:

- `{ key: 'apple', label: 'Apple' }`
- `{ key: 'apple', value: 'Apple' }`
- `{ id: 'user-1', name: 'John Doe', email: 'john@example.com' }`

### Custom Option Rendering

Customize the display of each option by yielding the item to a block. This is useful when you need to add extra information (such as a description or icon) alongside the label.

> **Note:** This example uses direct component state management (`@selectedKey` and `@onSelectionChange`) to focus on demonstrating the custom rendering feature. For form-integrated examples with validation and automatic data binding, see the "Form Validation" section.

```gts preview collapsible
import Component from '@glimmer/component';
import { tracked } from '@glimmer/tracking';
import { Select } from 'frontile';

export default class CustomUserSelect extends Component {
  @tracked selectedKey: string | null = null;

  onSelectionChange = (key: string | null) => {
    this.selectedKey = key;
  };

  <template>
    <div class='demo-stack'>
      <Select
        @isFilterable={{true}}
        @placeholder='Select a user'
        @items={{users}}
        @selectedKey={{this.selectedKey}}
        @onSelectionChange={{this.onSelectionChange}}
      >
        <:item as |o|>
          <o.Item>
            <div class='flex items-center space-x-4'>
              <img
                src='{{o.item.avatar}}'
                alt='{{o.item.name}}'
                class='w-10 h-10 rounded-full'
              />
              <div>
                <div
                  class='font-medium text-neutral-strong'
                >{{o.item.name}}</div>
                <div class='text-sm text-neutral-soft'>{{o.item.email}}</div>
              </div>
            </div>
          </o.Item>
        </:item>
      </Select>
      <p class='mt-4'>Selected: {{this.selectedKey}}</p>
    </div>
  </template>
}

const users = [
  {
    id: 'john-doe',
    name: 'John Doe',
    email: 'john.doe@example.com',
    avatar: 'https://i.pravatar.cc/150?img=1'
  },
  {
    id: 'jane-smith',
    name: 'Jane Smith',
    email: 'jane.smith@example.com',
    avatar: 'https://i.pravatar.cc/150?img=2'
  },
  {
    id: 'alice-johnson',
    name: 'Alice Johnson',
    email: 'alice.johnson@example.com',
    avatar: 'https://i.pravatar.cc/150?img=3'
  },
  {
    id: 'bob-brown',
    name: 'Bob Brown',
    email: 'bob.brown@example.com',
    avatar: 'https://i.pravatar.cc/150?img=4'
  },
  {
    id: 'charlie-davis',
    name: 'Charlie Davis',
    email: 'charlie.davis@example.com',
    avatar: 'https://i.pravatar.cc/150?img=5'
  }
];
```

### Custom Selected Item Content

`<:item>` styles an option **in the dropdown**. To style it once it is **selected**, add a
`<:selectedItem>` block. It yields the same `{ item, key, label }` the `<:item>` block does,
so markup moves between the two without being renamed, and it renders wherever the selection
is drawn as markup: inside the single-mode trigger, inside each chip in multiple mode, and
once per selection under `@selectedItemsDisplay="text"`.

Typically the dropdown row is the rich one — avatar, name and email — while the trigger keeps
a compact version of it.

> **Note:** `selected.item` is your own entry from `@items`. It is `undefined` for options
> written out with `<:default>` block syntax, because there is no collection entry behind
> them; only `key` and `label` are available in that case — so guard on it, as the demo
> below does, before reaching into your own object.

> **Note:** A **filterable** Select's trigger is an `<input>`, which cannot hold markup, so
> the block does not render there: a filterable Select still shows the selection as plain
> text inside the input. The chips beside that input do use the block.

```gts preview collapsible
import Component from '@glimmer/component';
import { tracked } from '@glimmer/tracking';
import { Select } from 'frontile';

export default class CustomSelectedItem extends Component {
  @tracked selectedKey: string | null = 'john-doe';
  @tracked selectedKeys: string[] = ['john-doe', 'jane-smith'];

  onSelectionChange = (key: string | null) => {
    this.selectedKey = key;
  };

  onMultipleSelectionChange = (keys: string[]) => {
    this.selectedKeys = keys;
  };

  <template>
    <div class='demo-stack'>
      <Select
        @label='Assignee'
        @placeholder='Select a user'
        @items={{people}}
        @selectedKey={{this.selectedKey}}
        @onSelectionChange={{this.onSelectionChange}}
      >
        <:item as |o|>
          <o.Item>
            <div class='flex items-center space-x-4'>
              <img
                src='{{o.item.avatar}}'
                alt=''
                class='w-10 h-10 rounded-full'
              />
              <div>
                <div
                  class='font-medium text-neutral-strong'
                >{{o.item.name}}</div>
                <div class='text-sm text-neutral-soft'>{{o.item.email}}</div>
              </div>
            </div>
          </o.Item>
        </:item>
        <:selectedItem as |selected|>
          <span class='flex items-center space-x-2'>
            {{#if selected.item}}
              <img
                src='{{selected.item.avatar}}'
                alt=''
                class='w-5 h-5 rounded-full'
              />
            {{/if}}
            <span>{{selected.label}}</span>
          </span>
        </:selectedItem>
      </Select>

      <Select
        @label='Reviewers'
        @selectionMode='multiple'
        @allowEmpty={{true}}
        @placeholder='Select reviewers'
        @items={{people}}
        @selectedKeys={{this.selectedKeys}}
        @onSelectionChange={{this.onMultipleSelectionChange}}
        class='mt-6'
      >
        <:item as |o|>
          <o.Item>
            <div class='flex items-center space-x-4'>
              <img
                src='{{o.item.avatar}}'
                alt=''
                class='w-10 h-10 rounded-full'
              />
              <div>
                <div
                  class='font-medium text-neutral-strong'
                >{{o.item.name}}</div>
                <div class='text-sm text-neutral-soft'>{{o.item.email}}</div>
              </div>
            </div>
          </o.Item>
        </:item>
        <:selectedItem as |selected|>
          <span class='flex items-center space-x-1'>
            {{#if selected.item}}
              <img
                src='{{selected.item.avatar}}'
                alt=''
                class='w-4 h-4 rounded-full'
              />
            {{/if}}
            <span>{{selected.label}}</span>
          </span>
        </:selectedItem>
      </Select>
    </div>
  </template>
}

const people = [
  {
    id: 'john-doe',
    name: 'John Doe',
    email: 'john.doe@example.com',
    avatar: 'https://i.pravatar.cc/150?img=1'
  },
  {
    id: 'jane-smith',
    name: 'Jane Smith',
    email: 'jane.smith@example.com',
    avatar: 'https://i.pravatar.cc/150?img=2'
  },
  {
    id: 'alice-johnson',
    name: 'Alice Johnson',
    email: 'alice.johnson@example.com',
    avatar: 'https://i.pravatar.cc/150?img=3'
  }
];
```

In multiple mode the chip chrome is kept around your content — the variant, `@chip`
options and the close button are still the Select's, so removal, `@allowEmpty` and the
`Backspace` keyboard path keep working unchanged.

### Declarative Items with Named Blocks

You can also define options directly inside the component using block syntax (referred to here as declarative items). In this case, filtering is not available. This example also demonstrates the use of the `@disabledKeys` and `@allowEmpty` options. When `@allowEmpty` is enabled, clicking a selected item will toggle its selection state (i.e. deselect it).

> **Note:** This example uses direct state management to demonstrate the declarative items feature. For most form use cases, prefer using `@items` with Form/Field as shown in earlier examples.

```gts preview collapsible
import Component from '@glimmer/component';
import { tracked } from '@glimmer/tracking';
import { array } from '@ember/helper';
import { Select } from 'frontile';

export default class DeclarativeItemsSelect extends Component {
  @tracked selectedKeys: string[] = [];

  onSelectionChange = (keys: string[]) => {
    this.selectedKeys = keys;
  };

  <template>
    <div class='demo-stack'>
      <Select
        @selectionMode='multiple'
        @placeholder='Select...'
        @onSelectionChange={{this.onSelectionChange}}
        @selectedKeys={{this.selectedKeys}}
        @disabledKeys={{array 'item-3' 'item-4'}}
        @allowEmpty={{true}}
        as |l|
      >
        <l.Item @key='item-1'>Item 1</l.Item>
        <l.Item @key='item-2'>Item 2</l.Item>
        <l.Item @key='item-3'>Item 3</l.Item>
        <l.Item @key='item-4'>Item 4</l.Item>
        <l.Item @key='item-5'>Item 5</l.Item>
      </Select>
      <p>Selected: {{this.selectedKeys}}</p>
    </div>
  </template>
}
```

### Clearable Select

The built-in clear button can be enabled using the `@isClearable` flag. This allows users to reset the selection easily.

It overrides `@allowEmpty`: that argument governs deselecting an _option_, while
`@isClearable` is the affordance for emptying the field. No clear button renders on a
disabled Select, or with nothing selected.

> **Note:** This example demonstrates the clearable feature with direct state management. The `@isClearable` option also works with Form/Field integration.

```gts preview
import Component from '@glimmer/component';
import { tracked } from '@glimmer/tracking';
import { Select } from 'frontile';

const colors = ['Red', 'Green', 'Blue'];

export default class ClearableSelectExample extends Component {
  @tracked selectedKey: string | null = null;

  onSelectionChange = (key: string | null) => {
    this.selectedKey = key;
  };

  <template>
    <div class='demo-stack'>
      <Select
        @placeholder='Select a color'
        @items={{colors}}
        @selectedKey={{this.selectedKey}}
        @onSelectionChange={{this.onSelectionChange}}
        @isClearable={{true}}
      />
      <p>Selected: {{this.selectedKey}}</p>
    </div>
  </template>
}
```

### Loading Select

Display a loading spinner in place of the dropdown icon by enabling the `@isLoading` flag. This is useful when data is being fetched asynchronously.

> **Note:** This example shows the loading state feature. The `@isLoading` option works with both standalone and Form/Field usage.

```gts preview
import Component from '@glimmer/component';
import { tracked } from '@glimmer/tracking';
import { Select } from 'frontile';

const sizes = ['Small', 'Medium', 'Large'];

export default class LoadingSelectExample extends Component {
  @tracked selectedKey: string | null = null;

  onSelectionChange = (key: string | null) => {
    this.selectedKey = key;
  };

  <template>
    <div class='demo-stack'>
      <Select
        @placeholder='Select a size'
        @items={{sizes}}
        @selectedKey={{this.selectedKey}}
        @onSelectionChange={{this.onSelectionChange}}
        @isLoading={{true}}
      />
      <p>Selected: {{this.selectedKey}}</p>
    </div>
  </template>
}
```

### Select with Custom Input Content and Empty State

This example demonstrates how to use the `:startContent`, `:endContent`, and `:emptyContent` blocks to customize the select's trigger appearance and the empty state when no results match the filter. Here, the select is filterable, so the empty content is shown when there are no matching options.

> **Note:** This example focuses on demonstrating custom content blocks. These blocks also work with Form/Field integration.

```gts preview collapsible
import Component from '@glimmer/component';
import { tracked } from '@glimmer/tracking';
import { Select } from 'frontile';

const fruits = ['Apple', 'Banana', 'Cherry', 'Date'];

export default class CustomContentBlocksSelect extends Component {
  @tracked selectedKey: string | null = null;

  onSelectionChange = (key: string | null) => {
    this.selectedKey = key;
  };

  <template>
    <div class='demo-stack'>
      <Select
        @isFilterable={{true}}
        @placeholder='Search fruits...'
        @items={{fruits}}
        @selectedKey={{this.selectedKey}}
        @onSelectionChange={{this.onSelectionChange}}
      >
        <:startContent>
          <span class='mr-2'>🔍</span>
        </:startContent>
        <:endContent>
          <span class='ml-2'>▼</span>
        </:endContent>
        <:emptyContent>
          <div class='p-2 text-center text-neutral'>
            No fruits found.
          </div>
        </:emptyContent>
      </Select>
      <p>Selected: {{this.selectedKey}}</p>
    </div>
  </template>
}
```

### Using NativeSelect

When you want the browser's own picker instead of this custom listbox — the native dropdown on mobile, the OS list box on desktop — use [NativeSelect](./native-select). It renders a real `<select>` and takes the same `@items`, `@selectedKey` and `@onSelectionChange` arguments.

```gts preview
import Component from '@glimmer/component';
import { tracked } from '@glimmer/tracking';
import { NativeSelect } from 'frontile';

const options = ['Option 1', 'Option 2', 'Option 3'];

export default class NativeSelectExample extends Component {
  @tracked selectedKey: string | null = null;

  onSelectionChange = (key: string | null) => {
    this.selectedKey = key;
  };

  <template>
    <div class='demo-stack'>
      <NativeSelect
        @allowEmpty={{true}}
        @placeholder='Select an option'
        @items={{options}}
        @selectedKey={{this.selectedKey}}
        @onSelectionChange={{this.onSelectionChange}}
      />
      <p class='mt-4'>Selected: {{this.selectedKey}}</p>
    </div>
  </template>
}
```

## Anatomy

`Select` combines a trigger or filter input, a Popover, and a Listbox. It can render options
from `@items` or yield an item builder, while `<:selectedItem>` customizes the selected value
shown in a single-select trigger.

## Multiple Selection

Set `@selectionMode='multiple'` to let the user pick more than one option. The selection is
an array: pass it as `@selectedKeys`, and `@onSelectionChange` hands you the new array back.

Every selection renders as a removable [Chip](../buttons/chip) beside the trigger — that is the
default, with no extra configuration. Use `@selectedItemsDisplay='text'` to opt back out to a
comma-joined string.

```gts preview collapsible
import Component from '@glimmer/component';
import { tracked } from '@glimmer/tracking';
import { Select } from 'frontile';

const languages = [
  { key: 'en', label: 'English' },
  { key: 'pt', label: 'Portuguese' },
  { key: 'es', label: 'Spanish' },
  { key: 'de', label: 'German' },
  { key: 'ja', label: 'Japanese' }
];

export default class BasicMultipleSelect extends Component {
  @tracked selectedKeys: string[] = ['en', 'pt'];

  onSelectionChange = (keys: string[]) => {
    this.selectedKeys = keys;
  };

  <template>
    <div class='demo-stack'>
      <Select
        @selectionMode='multiple'
        @label='Languages'
        @placeholder='Select languages'
        @items={{languages}}
        @selectedKeys={{this.selectedKeys}}
        @onSelectionChange={{this.onSelectionChange}}
      />
      <p class='mt-4'>Selected: {{this.selectedKeys}}</p>
    </div>
  </template>
}
```

Chips render in item order rather than click order, so they do not reorder underneath the
user as the selection grows.

Clicking anywhere in the field opens the dropdown, including a chip's own body — with a
single selection the trigger next to the chips can be a narrow sliver, so the whole field is a
click target. The one exception is a chip's close button, which removes that chip instead.

### Removing Selections

Each chip carries its own close button. `@allowEmpty` defaults to `false`, which means the
last remaining selection cannot be removed — its chip renders with **no close button at all**
rather than a dead one. Set `@allowEmpty={{true}}` to allow emptying the selection one chip
at a time.

`@isClearable` adds a clear button to the field that removes everything at once. It ignores
`@allowEmpty`, so a clearable Select can always be emptied even though its last chip has no
close button.

```gts preview collapsible
import Component from '@glimmer/component';
import { tracked } from '@glimmer/tracking';
import { Select } from 'frontile';

const toppings = ['Basil', 'Mushroom', 'Olive', 'Onion', 'Pepper'];

export default class RemovableChipsSelect extends Component {
  @tracked required: string[] = ['Basil', 'Olive'];
  @tracked optional: string[] = ['Basil', 'Olive'];

  onRequiredChange = (keys: string[]) => {
    this.required = keys;
  };

  onOptionalChange = (keys: string[]) => {
    this.optional = keys;
  };

  <template>
    <div class='demo-stack'>
      <div class='grid gap-4 md:grid-cols-2'>
        <Select
          @selectionMode='multiple'
          @label='At least one topping'
          @placeholder='Select toppings'
          @items={{toppings}}
          @selectedKeys={{this.required}}
          @onSelectionChange={{this.onRequiredChange}}
        />
        <Select
          @selectionMode='multiple'
          @label='Any number of toppings'
          @placeholder='Select toppings'
          @items={{toppings}}
          @selectedKeys={{this.optional}}
          @onSelectionChange={{this.onOptionalChange}}
          @allowEmpty={{true}}
          @isClearable={{true}}
        />
      </div>
    </div>
  </template>
}
```

### Customizing the Chips

`@chip` forwards variant options to every chip: `variant` (defaults to `soft`),
`color`, `size` (defaults to `sm`), `radius` and `withDot`.

`@chip.color` defaults to the Select's own `@color`, so `@color='primary'` colors the
listbox options and the chips together and you only set `@chip.color` when you want them to
differ.

```gts preview collapsible
import Component from '@glimmer/component';
import { tracked } from '@glimmer/tracking';
import { hash } from '@ember/helper';
import { Select } from 'frontile';

const tags = ['Accessibility', 'Design', 'Performance', 'Testing'];

export default class ChipOptionsSelect extends Component {
  @tracked inherited: string[] = ['Design', 'Testing'];
  @tracked customized: string[] = ['Design', 'Testing'];

  onInheritedChange = (keys: string[]) => {
    this.inherited = keys;
  };

  onCustomizedChange = (keys: string[]) => {
    this.customized = keys;
  };

  <template>
    <div class='demo-stack'>
      <div class='grid gap-4 md:grid-cols-2'>
        <Select
          @selectionMode='multiple'
          @color='primary'
          @label='Inherits @color'
          @placeholder='Select tags'
          @items={{tags}}
          @selectedKeys={{this.inherited}}
          @onSelectionChange={{this.onInheritedChange}}
        />
        <Select
          @selectionMode='multiple'
          @label='Custom @chip'
          @placeholder='Select tags'
          @items={{tags}}
          @selectedKeys={{this.customized}}
          @onSelectionChange={{this.onCustomizedChange}}
          @chip={{hash
            variant='outline'
            color='success'
            size='md'
            radius='full'
            withDot=true
          }}
        />
      </div>
    </div>
  </template>
}
```

### Text Display

`@selectedItemsDisplay='text'` renders the selection as a comma-joined string inside the
trigger instead of as chips. This was the only presentation before `0.18`, and it is worth
keeping for a dense field where a growing stack of chips would push the layout around.
Nothing is individually removable in this mode — use `@isClearable` or reopen the dropdown.

```gts preview
import Component from '@glimmer/component';
import { tracked } from '@glimmer/tracking';
import { Select } from 'frontile';

const permissions = ['Read', 'Write', 'Deploy', 'Administer'];

export default class TextDisplayMultipleSelect extends Component {
  @tracked selectedKeys: string[] = ['Read', 'Write'];

  onSelectionChange = (keys: string[]) => {
    this.selectedKeys = keys;
  };

  <template>
    <div class='demo-stack'>
      <Select
        @selectionMode='multiple'
        @selectedItemsDisplay='text'
        @label='Permissions'
        @placeholder='Select permissions'
        @items={{permissions}}
        @selectedKeys={{this.selectedKeys}}
        @onSelectionChange={{this.onSelectionChange}}
      />
    </div>
  </template>
}
```

### Filterable Multiple Selection

`@isFilterable={{true}}` turns the trigger into a text input that sits alongside the chips,
the familiar tag-input shape. The filter never echoes the selection, so there is always room
to type, and the chips reflect the selection rather than the filter — a chip stays put even
when its option is filtered out of the list.

Pressing `Backspace` while the filter is empty removes the last chip. With text in the
filter, `Backspace` edits the text as usual, and the final chip is still protected by
`@allowEmpty`.

```gts preview collapsible
import Component from '@glimmer/component';
import { tracked } from '@glimmer/tracking';
import { Select } from 'frontile';

const countries = [
  'Argentina',
  'Brazil',
  'Canada',
  'Denmark',
  'Egypt',
  'France',
  'Germany',
  'Italy',
  'Japan',
  'Mexico'
];

export default class FilterableMultipleSelect extends Component {
  @tracked selectedKeys: string[] = ['Brazil', 'Japan'];

  onSelectionChange = (keys: string[]) => {
    this.selectedKeys = keys;
  };

  <template>
    <div class='demo-stack'>
      <Select
        @selectionMode='multiple'
        @isFilterable={{true}}
        @allowEmpty={{true}}
        @label='Countries'
        @placeholder='Search countries'
        @items={{countries}}
        @selectedKeys={{this.selectedKeys}}
        @onSelectionChange={{this.onSelectionChange}}
      />
    </div>
  </template>
}
```

### Styling the Chips Area

Three `@classes` keys cover the chips: `chipsField` is the field shell that wraps the chips
and the trigger together, `chipsContainer` is the flex row holding the chips, and `chip` is
merged onto every individual chip.

```gts preview collapsible
import Component from '@glimmer/component';
import { tracked } from '@glimmer/tracking';
import { hash } from '@ember/helper';
import { Select } from 'frontile';

const teams = ['Design', 'Engineering', 'Marketing', 'Support'];

export default class StyledChipsSelect extends Component {
  @tracked selectedKeys: string[] = ['Design', 'Engineering'];

  onSelectionChange = (keys: string[]) => {
    this.selectedKeys = keys;
  };

  <template>
    <div class='demo-stack'>
      <Select
        @selectionMode='multiple'
        @label='Teams'
        @placeholder='Select teams'
        @items={{teams}}
        @selectedKeys={{this.selectedKeys}}
        @onSelectionChange={{this.onSelectionChange}}
        @allowEmpty={{true}}
        @classes={{hash
          chipsField='border-primary-soft'
          chipsContainer='gap-2'
          chip='bg-primary-subtle text-primary-strong'
        }}
      />
    </div>
  </template>
}
```

## Accessibility

Select is a custom listbox, not a native `<select>`, so its semantics are assembled from
several pieces:

| Element           | What it exposes                                                                                                                                                                                                                                                                                            |
| ----------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Trigger           | `aria-haspopup="true"`, `aria-controls` pointing at the dropdown, and `aria-expanded` kept in sync — supplied by Popover's `trigger` modifier                                                                                                                                                              |
| Dropdown          | `role="listbox"`, plus `aria-multiselectable="true"` when `@selectionMode="multiple"`                                                                                                                                                                                                                      |
| Options           | `role="option"` with `aria-labelledby`, `aria-selected` reflecting selection, and `aria-disabled="true"` on disabled keys                                                                                                                                                                                  |
| Form value        | A visually hidden native `<select>` mirrors the options, so `@name` submits normally                                                                                                                                                                                                                       |
| Chips             | Each chip's close button is named `Remove <label>` with visually hidden text, so the buttons are announced distinctly. The chips sit beside the trigger rather than inside it, so no interactive element is nested in the combobox. The close buttons carry `tabindex="-1"` — see the keyboard model below |
| `<:selectedItem>` | Supplying the block gives the **button** trigger an explicit `aria-label` composed from the field label and the option's text — see below                                                                                                                                                                  |

Keyboard handling comes from the listbox:

| Key                                   | Behavior                    |
| ------------------------------------- | --------------------------- |
| `ArrowDown` / `ArrowUp`               | Move between options        |
| `Home` / `PageUp`, `End` / `PageDown` | Jump to first / last option |
| `Enter`, `Space`                      | Select the active option    |
| `Escape`                              | Closes the dropdown         |

### The chips keyboard model

Chip close buttons are **pointer affordances**: they are set to `tabindex="-1"` and are not
tab stops, so Tabbing into the control lands on the field itself rather than on a run of
"Remove ..." buttons in front of it.

Keyboard removal is on the field instead, in **both** modes:

| Context                                | Key                            | Behavior                                                                                               |
| -------------------------------------- | ------------------------------ | ------------------------------------------------------------------------------------------------------ |
| Chips, `@isFilterable={{true}}`        | `Backspace`                    | Removes the last chip **when the filter is empty**; with text in the filter it edits the text as usual |
| Chips, non-filterable (button trigger) | `Backspace` or `Delete`        | Removes the last chip                                                                                  |
| Either                                 | `Enter` / `Space` on an option | Toggles that selection off from the dropdown                                                           |

The `@allowEmpty` rule applies throughout: with the default `@allowEmpty={{false}}` the final
selection cannot be removed, so its chip renders without a close button and `Backspace` leaves
it alone.

If you set `@chip` or restyle the chips, do not re-enable the close buttons as tab stops
without also removing this keyboard path — a visual order that disagrees with focus order is
its own WCAG 2.4.3 problem.

### Naming the trigger with `<:selectedItem>`

Left alone, the single-mode trigger takes its accessible name from its own text — the selected
label, or the placeholder. A `<:selectedItem>` block owns that text and may render nothing
readable at all (an avatar, an icon), which would leave the combobox announced as an unnamed
button.

So whenever the block is supplied, the **button** trigger carries an explicit `aria-label`
composed from two halves: the field label (falling back to `@placeholder`) and the selected
options' own text — `Assignee, John Doe` for the example above. Either half on its own is used
alone when the other is missing, so the name is never `Assignee, ` and never prefixes the
selection with the untranslatable `Select options`.

**This name replaces whatever your block renders, so keep the two in agreement.** If your
block's visible text is the option's `label`, they already agree and there is nothing to do —
hiding decorative images from assistive technology (`alt=''`) is enough. If your block shows
something _else_ — an email address, an abbreviation, an initial — then the announced name and
the visible text disagree, which fails WCAG 2.5.3 _Label in Name_ and leaves speech-input
users unable to say what they see. In that case, render the option's `label` somewhere in the
block, or set `@label` / `@placeholder` to the wording that is actually visible.

> **Note:** `aria-label` passed to `<Select>` itself does **not** override this. Attributes on
> `<Select>` land on the field's wrapper element, not on the combobox, so the composed name is
> what the trigger announces either way. The block's own text is the lever you have.

A **filterable** Select is not affected at all: its trigger is an `<input>` whose value is the
selection as text, so it is already named by that value and gets no `aria-label` — one that
duplicated the value would also change as the user typed.

Chips mode is unaffected: the trigger there is already named by `aria-label`, and the chips
are its siblings, so they are read on their own. Chip close buttons keep taking their
`Remove <label>` text from the option, never from your block, so a purely graphical chip is
still removable by name.

## API

### Select

A dropdown selection component: a custom listbox in a popover, backed by a
visually hidden native <select> so the value submits with a form.

Selection can be controlled with @selectedKey / @selectedKeys plus
@onSelectionChange, or left uncontrolled.

**Element:** `HTMLDivElement`

**Arguments**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `allowEmpty` | `boolean` | - |  |
| `appearance` | `'default' \| 'outlined' \| 'faded'` | - | **Deprecated.** Use `variant`. `default` is now `solid`, `outlined` is `outline`, and `faded` is `subtle`. |
| `backdrop` | `'faded' \| 'none' \| 'transparent' \| 'blur'` | - | How the area behind the overlay is rendered: none omits the backdrop entirely, transparent keeps it clickable but invisible, faded dims the page, and blur blurs it. |
| `backdropTransition` | `Object` | - | Transition classes for the backdrop, overriding the defaults used when it fades in and out. |
| `blockScroll` | `boolean` | `true` | Whether scrolling should be blocked when the select dropdown is open. |
| `chip` | `Object` | - | Not applicable in single selection mode. Variant of the chips rendered for each selected option. Only applies when @selectedItemsDisplay is 'chips' (the default). Options are the same ones {@link Chip } itself accepts (variant, color, size, radius, withDot), but Select applies its own defaults tuned for sitting inside a field, rather than Chip's: variant defaults to 'soft' color defaults to the Select's own @color, so @color="primary" colors the listbox items and the chips together size defaults to 'sm' radius and withDot fall back to Chip's own defaults |
| `classes` | `SlotsToClasses<'icon' \| 'base' \| 'innerContainer' \| 'startContent' \| 'endContent' \| 'input' \| 'listbox' \| 'clearButton' \| 'emptyContent' \| 'placeholder' \| 'chipsField' \| 'chipsContainer' \| 'chip'>` | - | Custom classes to style different slots within the select component. |
| `closeOnEscapeKey` | `boolean` | `true` | Whether to close when the escape key is pressed |
| `closeOnItemSelect` | `boolean` | `true` | Whether the select should close upon selecting an item. |
| `closeOnOutsideClick` | `boolean` | `true` | Whether to close when the area outside (the backdrop) is clicked |
| `color` | `'neutral' \| 'primary' \| 'secondary' \| 'tertiary' \| 'success' \| 'warning' \| 'danger'` | - | The color of each item |
| `description` | `string` | - | Help text rendered between the label and the control, and referenced by the ids describedBy returns. |
| `didClose` | `() => void` | - | Callback when closing has finished, including any exit transition. |
| `disabledKeys` | `string[]` | - |  |
| `disableFocusTrap` | `boolean` | `true` | Whether the focus trap should be disabled when the dropdown is open. |
| `disableTransitions` | `boolean` | `false` | Disable css transitions |
| `endContentPointerEvents` | `'none' \| 'auto'` | `'none'` | Controls pointer-events property of endContent. Defaults to none to pass click events to the input. If your content needs to capture events, add the pointer-events-auto class to that element. |
| `errors` | `string \| string[]` | - | Validation messages for the field. A non-empty value also marks the control invalid, and an array is joined with ;  when displayed. |
| `filter` | `FilterFn` | - | Function to filter the items in the select. The default implementation ranks by relevance, so the closest match is listed first rather than whichever match came first in @items. |
| `flipOptions` | `{ mainAxis?: boolean; crossAxis?: boolean \| 'alignment'; fallbackPlacements?: Placement[]; fallbackStrategy?: 'bestFit' \| 'initialPlacement'; fallbackAxisSideDirection?: 'start' \| ... 1 more ... \| 'none'; ... 5 more ...; boundary?: Boundary; }` | - | Options for the floating-ui flip middleware, which moves the content to the opposite side when it would overflow the viewport. |
| `focusTrapOptions` | `any` | `{ clickOutsideDeactivates: true, allowOutsideClick: true }` | Focus trap options |
| `hideEmptyContent` | `boolean` | `false` | If true, hides the empty content when there are no options available. |
| `id` | `string` | - | The unique identifier for the select component. |
| `inputSize` | `'sm' \| 'md' \| 'lg'` | - | Defines the input size of the select. |
| `intent` | `'default' \| 'primary' \| 'secondary' \| 'tertiary' \| 'success' \| 'warning' \| 'danger'` | - | **Deprecated.** Use `color`. `default` is now `neutral`. |
| `isClearable` | `boolean` | `false` | Whether to include a clear button in the select component. If enabled, this allows users to clear the selection. This option deliberately overrides allowEmpty: that argument governs deselecting an option (the listbox and the chips both refuse to remove the last one without it), while this is a separate affordance you opt into for exactly the purpose of emptying the field. Since allowEmpty defaults to false, honouring it here would render the button dead by default. No clear button is rendered on a disabled Select, or with nothing selected. |
| `isDisabled` | `boolean` | `false` | Whether the field is disabled. FormControl passes this through for styling; the control it wraps is responsible for the disabled attribute. Whether the select should be disabled, preventing user interaction. |
| `isFilterable` | `boolean` | `false` | Allows filtering of the items in the select dropdown. If true, a search input is displayed for filtering. |
| `isInvalid` | `boolean` | `false` | Marks the control invalid without supplying messages, for validation that is reported elsewhere. |
| `isLoading` | `boolean` | - | If true, the select will show a loading spinner instead of the dropdown icon. |
| `isRequired` | `boolean` | `false` | Whether the field is required. Adds an asterisk to the label; it does not set the required attribute on the control itself. |
| `items` | `T[]` | - |  |
| `label` | `string` | - | The label text rendered above the control and associated with it via for. Use the :label block instead when the label needs markup. |
| `middleware` | `{ name: string; options?: any; fn: (state: { placement: Placement; strategy: Strategy; x: number; y: number; initialPlacement: Placement; middlewareData: MiddlewareData; rects: ElementRects; platform: { ...; } &#x26; Platform; elements: Elements; }) => Promisable<...>; }[]` | - | Additional floating-ui middleware, for positioning behavior beyond what placement, offsetOptions, flipOptions, and shiftOptions cover. |
| `name` | `string` | - | The name attribute for the select component, useful for form submissions. |
| `offsetOptions` | `OffsetOptions` | `5` |  |
| `onAction` | `(key: string) => void` | - |  |
| `onBlur` | `() => void` | - | Callback fired when focus leaves the Select. "Leaves the Select" means the whole control: the field and its dropdown, which is rendered outside the field in the DOM. Moving focus between them -- which is what clicking an option does -- is not a blur, so this does not fire while the user is picking options, in either selection mode. It fires once, when focus lands somewhere outside the control (or nowhere, with the dropdown closed). This is what Field drives blur validation from. |
| `onSelectionChange` | `((key: string) => void) \| ((keys: string[]) => void)` | - | Callback fired when the selection changes in single mode. Update your @selectedKey state in this callback to maintain two-way binding. Callback fired when the selection changes in multiple mode. Update your @selectedKeys state in this callback to maintain two-way binding. |
| `placeholder` | `string` | - | The placeholder text displayed when no option is selected. |
| `placement` | `'top' \| 'top-start' \| 'top-end' \| 'right' \| 'right-start' \| 'right-end' \| 'bottom' \| 'bottom-start' \| 'bottom-end' \| 'left' \| 'left-start' \| 'left-end'` | `'bottom-start'` | Placement of the menu when open |
| `popoverSize` | `'sm' \| 'md' \| 'lg' \| 'trigger'` | `'trigger'` | Defines the size of the popover dropdown. 'sm': Small 'md': Medium 'lg': Large 'trigger': Same size as the trigger |
| `renderInPlace` | `boolean` | `false` | Whether to render in place or in the specified/default destination |
| `selectedItemsDisplay` | `'text' \| 'chips'` | `'chips'` | Not applicable in single selection mode. How the selected options are presented in the trigger. 'chips': each selection renders as a removable {@link Chip }. 'text': the selections render as a comma-joined string. |
| `selectedKey` | `string` | - | **Deprecated.** Use selectedKeys for multiple selection mode The currently selected key for single selection mode. Data Flow: Pass this to set the initial selection Update this in your onSelectionChange handler to maintain two-way binding The component calls onSelectionChange whenever the user changes the selection |
| `selectedKeys` | `string[]` | - | **Deprecated.** Use selectedKey for single selection mode The currently selected keys for multiple selection mode. Data Flow: Pass this to set the initial selection (array of keys) Update this in your onSelectionChange handler to maintain two-way binding The component calls onSelectionChange whenever the user changes the selection |
| `selectionMode` | `'single' \| 'multiple'` | `'single'` | Determines the selection mode of the select component. 'single': Only one item can be selected at a time. Determines the selection mode of the select component. 'multiple': Allows multiple selections. |
| `shiftOptions` | `{ mainAxis?: boolean; crossAxis?: boolean; rootBoundary?: RootBoundary; elementContext?: ElementContext; altBoundary?: boolean; padding?: Padding; limiter?: { ...; }; boundary?: Boundary; }` | - | Options for the floating-ui shift middleware, which nudges the content along its axis to keep it in view. |
| `startContentPointerEvents` | `'none' \| 'auto'` | `'auto'` | Controls pointer-events property of startContent. If you want to pass the click event to the input, set it to none. |
| `strategy` | `Strategy` | `'absolute'` |  |
| `target` | `string \| Element` | - | The target where to render the portal. There are 3 options: 1) Element object, 2) element id, 3) portal target name. For element id, string must be prefixed with #. If no value is passed in, we will render to the closest unnamed portal target, parent portal or document.body. |
| `transition` | `Object` | `{name: 'overlay-transition--scale'}` | The transition to be used in the Modal. |
| `transitionDuration` | `number` | `200` | Duration of the animation |
| `variant` | `'solid' \| 'subtle' \| 'outline'` | `'solid'` | The variant of each item. |

**Blocks**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `item *` | `[{ item: T; key: string; label: string; Item: ListboxItem (manager, item bound); }]` | - |  |
| `default *` | `[{ Item: ListboxItem (manager bound); Group: ListboxGroup (manager bound); }]` | - |  |
| `startContent *` | `[]` | - | Content to display at the beginning of the select component. This can be an icon, a label, or any custom UI element. Example: A search icon or a custom label. |
| `endContent *` | `[]` | - | Content to display at the end of the select component. This can be an icon, a button, or any custom UI element. Example: A clear button or a dropdown arrow. |
| `emptyContent *` | `[]` | - | The content to display when there are no available options. If hideEmptyContent argument is true, this content will not be shown. |
| `selectedItem *` | `[SelectedItemBlockArg<T>]` | - | Custom content for each selected option, in place of its plain text. Renders wherever the selection is drawn as markup: inside the single-mode trigger, inside each chip in multiple mode (the chip chrome, @chip options and close button are kept), and once per selection -- comma-separated -- under @selectedItemsDisplay="text". Not inside a filterable trigger: that is an <input>, which cannot hold markup, so a filterable Select still shows the selection as plain text there. The chips beside the input do use the block. Yields the same { item, key, label } the :item block does, so the same markup works in both. item is undefined for options written in block form rather than rendered from @items. Because a block rendering only graphics would otherwise leave the single-mode trigger with no accessible name, supplying this block also gives that (button) trigger an aria-label composed from the field label and the selected options' text. That name replaces what the block renders, so a block whose visible text is not the option's label should carry the label too, or set @label/@placeholder to the wording that is visible -- see the guide. |
### ListboxItem

**Element:** `HTMLLIElement`

**Arguments**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `key *` | `string` | - |  |
| `manager *` | `ListManager` | - |  |
| `appearance` | `'default' \| 'outlined' \| 'faded'` | - | **Deprecated.** Use `variant`. `default` is now `solid`, `outlined` is `outline`, and `faded` is `subtle`. |
| `class` | `string` | - |  |
| `color` | `'neutral' \| 'primary' \| 'secondary' \| 'tertiary' \| 'success' \| 'warning' \| 'danger'` | - | The color of each item |
| `description` | `string` | - |  |
| `hasSubmenu` | `boolean` | - | Marks this option as the trigger for a submenu. It stops the option selecting: opening a submenu is not choosing anything, so onAction and onSelectionChange must not fire for it. The option still registers with the ListManager and so still takes part in arrow navigation, type-ahead and the roving tab stop. Renders aria-haspopup="menu" and a trailing chevron, unless an :end block supplies its own trailing content. |
| `intent` | `'default' \| 'primary' \| 'secondary' \| 'tertiary' \| 'success' \| 'warning' \| 'danger'` | - | **Deprecated.** Use `color`. `default` is now `neutral`. |
| `isSubmenuOpen` | `boolean` | - | Whether this option's submenu is currently open. Only meaningful alongside @hasSubmenu; drives aria-expanded and the highlighted resting state via data-submenu-open. |
| `item` | `unknown` | - | The entry of @items this option renders, remembered on the registered list item so a selection can hand it back. Bound for you on the Item yielded from the :item block; block-form options have no such entry. |
| `onClick` | `() => void` | - |  |
| `shortcut` | `string` | - | A keyboard shortcut shown at the end of the option, rendered by Kbd. Accepts named keys ("mod+k") or a literal string ("⌘K"). |
| `shortcutVariant` | `'solid' \| 'subtle' \| 'outline' \| 'plain' \| 'inherit'` | `'inherit'` | The variant of the rendered shortcut. Defaults to inherit, so the keycap follows the option's own colour on active and filled rows. |
| `submenuId` | `string` | - | The id of the role="menu" element this option opens, for aria-controls. Only meaningful alongside @hasSubmenu. |
| `textValue` | `string` | - |  |
| `type` | `'listbox' \| 'menu'` | - |  |
| `variant` | `'solid' \| 'subtle' \| 'outline'` | `'solid'` | The variant of each item. |
| `withDivider` | `boolean` | - |  |

**Blocks**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `default *` | `[]` | - |  |
| `selectedIcon *` | `[]` | - |  |
| `start *` | `[]` | - |  |
| `end *` | `[]` | - |  |

---

# Switch

Source: /docs/components/forms/switch.md

# Switch

A toggle control that allows users to switch between two states (on/off, enabled/disabled). The Switch component integrates with the Form and Field components for automatic data binding and validation. It supports custom content blocks for icons and labels.

> **Modern Usage:** For most use cases, prefer using Switch with the Form and Field components. This provides automatic data binding, validation, and state management without manual `@onChange` handlers.

> **Field-Level Validation:** Switch supports field-level validation that runs on change/blur events based on the Form's `@validateOn` setting, providing immediate feedback as users toggle the switch.

## Import

```js
import { Switch } from 'frontile';
```

## Usage

### Basic Switch

The most basic usage of a Switch component with a label.

```gts preview
import { Switch } from 'frontile';

<template>
  <div class='demo-stack'>
    <Switch @label='Enable Notifications' />
  </div>
</template>
```

### Controlled with Form/Field

The recommended pattern for using Switch is with Form and Field components, which provides automatic data binding and state management without manual onChange handlers.

```gts preview collapsible
import Component from '@glimmer/component';
import { tracked } from '@glimmer/tracking';
import { Form, type FormResultData } from 'frontile';

export default class ControlledSwitch extends Component {
  @tracked formData = { notifications: false };

  handleFormChange = (result: FormResultData) => {
    this.formData = result.data;
  };

  <template>
    <div class='demo-stack'>
      <Form
        @data={{this.formData}}
        @onChange={{this.handleFormChange}}
        as |form|
      >
        <form.Field @name='notifications' as |field|>
          <field.Switch @label='Enable Email Notifications' />
        </form.Field>
      </Form>

      <div class='p-3 border border-neutral-soft rounded'>
        <p class='text-sm'>
          Notifications are
          <strong>{{if
              this.formData.notifications
              'enabled'
              'disabled'
            }}</strong>
        </p>
      </div>
    </div>
  </template>
}
```

### Form Validation

**Note:** Switch supports field-level validation that runs on change/blur/input events based on the Form's `@validateOn` setting, providing immediate feedback as users interact with the switch.

The Switch component integrates with the Form validation system, providing automatic error display and field-level validation. This example demonstrates using Valibot schema validation with the Form/Field components.

```gts preview collapsible
import Component from '@glimmer/component';
import { tracked } from '@glimmer/tracking';
import { Form, type FormResultData } from 'frontile';
import { Button } from 'frontile';
import { array } from '@ember/helper';
import * as v from 'valibot';

// Define validation schema
const schema = v.object({
  email: v.pipe(
    v.string(),
    v.nonEmpty('Email is required'),
    v.email('Please enter a valid email address')
  ),
  termsAccepted: v.pipe(
    v.boolean(),
    v.literal(true, 'You must accept the terms and conditions')
  ),
  notifications: v.boolean()
});

type Schema = v.InferOutput<typeof schema>;

export default class ValidatedSwitch extends Component {
  @tracked formData: Schema = {
    email: '',
    termsAccepted: false,
    notifications: true
  };
  @tracked submitMessage = '';

  handleFormChange = (data: FormResultData<Schema>) => {
    this.formData = data.data;
  };

  handleFormSubmit = (data: FormResultData<Schema>) => {
    this.submitMessage = 'Registration successful!';
    console.log('Form submitted:', data.data);
  };

  <template>
    <div class='demo-stack'>
      <Form
        @data={{this.formData}}
        @schema={{schema}}
        @onChange={{this.handleFormChange}}
        @onSubmit={{this.handleFormSubmit}}
        @validateOn={{array 'change' 'submit'}}
        as |form|
      >
        <div class='flex flex-col gap-4'>
          <form.Field @name='email' as |field|>
            <field.Input
              @label='Email Address'
              @type='email'
              @isRequired={{true}}
            />
          </form.Field>

          <form.Field @name='termsAccepted' as |field|>
            <field.Switch
              @label='I accept the terms and conditions'
              @description='You must accept our terms to continue'
              @isRequired={{true}}
            />
          </form.Field>

          <form.Field @name='notifications' as |field|>
            <field.Switch
              @label='Send me email notifications'
              @description='Optional: Receive updates about new features'
            />
          </form.Field>

          <Button type='submit'>
            Register
          </Button>
        </div>
      </Form>

      {{#if this.submitMessage}}
        <div class='p-3 bg-success-subtle text-success-strong rounded'>
          {{this.submitMessage}}
        </div>
      {{/if}}

      <div class='p-4 bg-neutral-subtle rounded'>
        <h4 class='font-medium mb-2'>Form Data:</h4>
        <pre class='text-sm overflow-auto'>{{JSON.stringify
            this.formData
            null
            2
          }}</pre>
      </div>
    </div>
  </template>
}
```

### With Icons

Customize the switch appearance by using content blocks:

- `startContent`: Renders before the switch thumb.
- `thumbContent`: Renders inside the switch thumb. It receives an object with `isSelected` to reflect the current state.
- `endContent`: Renders after the switch thumb.

```gts preview
import Component from '@glimmer/component';
import { Switch } from 'frontile';
import { SunIcon, MoonIcon } from 'site/components/icons';

export default class CustomContentSwitchExample extends Component {
  <template>
    <div class='demo-stack'>
      <Switch @label='Dark Mode'>
        <:startContent>
          <SunIcon />
        </:startContent>
        <:endContent>
          <MoonIcon />
        </:endContent>
      </Switch>
    </div>
  </template>
}
```

```gts preview
import Component from '@glimmer/component';
import { Switch } from 'frontile';
import { SunIcon, MoonIcon } from 'site/components/icons';

export default class CustomContentSwitchExample extends Component {
  <template>
    <div class='demo-stack'>
      <Switch @label='Dark Mode'>
        <:thumbContent as |o|>
          {{#if o.isSelected}}
            <MoonIcon class='size-3' />
          {{else}}
            <SunIcon class='size-3' />
          {{/if}}
        </:thumbContent>
      </Switch>
    </div>
  </template>
}
```

### Miscellaneous Options

The Switch component supports various optional configurations for sizing, visual styling, states, and custom classes.

```gts preview collapsible
import { Switch } from 'frontile';
import { hash } from '@ember/helper';

<template>
  <div class='demo-stack'>
    {{! Size variants }}
    <div>
      <h4 class='text-sm font-medium mb-2'>Size Variants</h4>
      <div class='flex gap-4'>
        <Switch @size='sm' @label='Small' />
        <Switch @size='md' @label='Medium' />
        <Switch @size='lg' @label='Large' />
      </div>
    </div>

    {{! Color variants }}
    <div>
      <h4 class='text-sm font-medium mb-2'>Color Variants</h4>
      <div class='flex gap-4'>
        <Switch @color='neutral' @label='Default' @defaultSelected={{true}} />
        <Switch @color='primary' @label='Primary' @defaultSelected={{true}} />
        <Switch
          @color='secondary'
          @label='Secondary'
          @defaultSelected={{true}}
        />
        <Switch
          @color='tertiary'
          @label='Tertiary'
          @defaultSelected={{true}}
        />
        <Switch @color='success' @label='Success' @defaultSelected={{true}} />
        <Switch @color='warning' @label='Warning' @defaultSelected={{true}} />
        <Switch @color='danger' @label='Danger' @defaultSelected={{true}} />
      </div>
    </div>

    {{! Disabled state }}
    <div>
      <h4 class='text-sm font-medium mb-2'>Disabled State</h4>
      <div class='flex flex-col gap-3'>
        <Switch
          @label='Disabled Switch (Off)'
          @defaultSelected={{false}}
          @isDisabled={{true}}
        />
        <Switch
          @label='Disabled Switch (On)'
          @defaultSelected={{true}}
          @isDisabled={{true}}
        />
        <Switch
          @label='Disabled with Description'
          @description='This switch is disabled and cannot be toggled'
          @defaultSelected={{true}}
          @isDisabled={{true}}
        />
      </div>
    </div>

    {{! Custom styling }}
    <div>
      <h4 class='text-sm font-medium mb-2'>Custom Styling</h4>
      <Switch
        @label='Custom Styled Switch'
        @description='This switch has custom styling applied'
        @classes={{hash
          base='my-custom-switch-base'
          wrapper='my-custom-switch-wrapper'
          thumb='my-custom-switch-thumb'
          label='my-custom-switch-label'
        }}
      />
    </div>
  </div>
</template>
```

## Accessibility

The Switch component follows accessibility best practices:

- Uses semantic checkbox input with `role="switch"` behavior
- Proper label association using `for` and `id` attributes
- ARIA attributes for invalid states (`aria-invalid`)
- Descriptive text association using `aria-describedby`
- Support for required field indication
- Keyboard navigation (Space to toggle, Tab to focus)
- Screen reader announcements for labels, descriptions, and validation messages
- Visual focus indicators
- Disabled state properly communicated to assistive technologies

## API

### Switch

**Element:** `HTMLInputElement`

**Arguments**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `classes` | `SlotsToClasses<'label' \| 'base' \| 'startContent' \| 'endContent' \| 'labelContainer' \| 'wrapper' \| 'hiddenInput' \| 'thumb'>` | - | Custom classes to style different slots of the Switch component. |
| `color` | `'neutral' \| 'primary' \| 'secondary' \| 'tertiary' \| 'success' \| 'warning' \| 'danger'` | `'primary'` | The color of the Switch. |
| `defaultSelected` | `boolean` | `false` | Sets the initial selected state of the Switch when used in uncontrolled mode. |
| `description` | `string` | - | Help text rendered between the label and the control, and referenced by the ids describedBy returns. |
| `errors` | `string \| string[]` | - | Validation messages for the field. A non-empty value also marks the control invalid, and an array is joined with ;  when displayed. |
| `intent` | `'default' \| 'primary' \| 'secondary' \| 'tertiary' \| 'success' \| 'warning' \| 'danger'` | - | **Deprecated.** Use `color`. `default` is now `neutral`. |
| `isDisabled` | `boolean` | - | Whether the Switch is disabled. When true, user interaction is prevented. |
| `isInvalid` | `boolean` | `false` | Marks the control invalid without supplying messages, for validation that is reported elsewhere. |
| `isRequired` | `boolean` | `false` | Whether the field is required. Adds an asterisk to the label; it does not set the required attribute on the control itself. |
| `isSelected` | `boolean` | - | Controls the current selected state of the Switch. When provided a boolean value, the component operates in a controlled mode. |
| `label` | `string` | - | The label text rendered above the control and associated with it via for. Use the :label block instead when the label needs markup. |
| `name` | `string` | - | The name attribute for the input element. Useful for form submissions. |
| `onBlur` | `() => void` | - | Callback triggered when the Switch loses focus (blur event). |
| `onChange` | `((value: boolean, event: Event) => void) \| ((value: boolean) => void)` | - | Callback triggered when the Switch value changes. Receives the new boolean value and, optionally, the triggering Event. |
| `size` | `'sm' \| 'md' \| 'lg'` | - | The size of the Switch. |

**Blocks**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `startContent *` | `[]` | - |  |
| `thumbContent *` | `[{ isSelected: boolean; }]` | - |  |
| `endContent *` | `[]` | - |  |

---

# Textarea

Source: /docs/components/forms/textarea.md

# Textarea

A textarea component for multi-line text input, with support for labels, validation, sizing, and accessibility.

## Import

```js
import { Textarea } from 'frontile';
```

## Usage

### Basic Textarea

The most basic usage of the Textarea component with only a label.

```gts preview
import { Textarea } from 'frontile';

<template>
  <div class='demo-stack'>
    <Textarea @label='Message' />
  </div>
</template>
```

### Controlled Textarea

You can control the textarea value using the Form component's data binding system.

```gts preview collapsible
import Component from '@glimmer/component';
import { tracked } from '@glimmer/tracking';
import { Form, type FormResultData } from 'frontile';

export default class ControlledTextarea extends Component {
  @tracked formData = {
    message: ''
  };

  handleFormChange = (result: FormResultData) => {
    this.formData = result.data;
  };

  <template>
    <div class='demo-stack'>
      <Form
        @data={{this.formData}}
        @onChange={{this.handleFormChange}}
        as |form|
      >
        <form.Field @name='message' as |field|>
          <field.Textarea
            @label='Your Message'
            placeholder='Enter your message here...'
          />
        </form.Field>
      </Form>

      <div class='p-3 border border-neutral-soft rounded'>
        <p class='text-sm text-neutral'>Character count:
          {{this.formData.message.length}}</p>
        <p class='text-sm'>Current message: {{this.formData.message}}</p>
      </div>
    </div>
  </template>
}
```

### Disabled State

Textarea fields can be disabled to prevent user interaction while maintaining their visual presence and current value.

```gts preview
import Component from '@glimmer/component';
import { Textarea } from 'frontile';

export default class DisabledTextarea extends Component {
  <template>
    <div class='demo-stack'>
      <Textarea
        @label='Disabled Basic Textarea'
        @value='This text cannot be edited or modified. The textarea is in a disabled state.'
        disabled={{true}}
        rows='3'
      />

      <Textarea
        @label='Disabled Textarea with Description'
        @description='This textarea is disabled and shows how the component appears when not interactive'
        @value='Lorem ipsum dolor sit amet, consectetur adipiscing elit. Sed do eiusmod tempor incididunt ut labore et dolore magna aliqua.'
        disabled={{true}}
        rows='4'
      />
    </div>
  </template>
}
```

### Form-Level Change Handling

When using Form and Field components, all change events are handled centrally by the Form component via its `@onChange` callback. This demonstrates how Form automatically captures all field updates in real-time as the user types.

```gts preview collapsible
import Component from '@glimmer/component';
import { tracked } from '@glimmer/tracking';
import { Form, type FormResultData } from 'frontile';

export default class TextareaWithFormChange extends Component {
  @tracked formData = { text: '' };
  @tracked changeEventCount = 0;

  handleFormChange = (data: FormResultData) => {
    this.formData = data.data;
    this.changeEventCount += 1;
  };

  <template>
    <div class='demo-stack'>
      <Form
        @data={{this.formData}}
        @onChange={{this.handleFormChange}}
        as |form|
      >
        <form.Field @name='text' as |field|>
          <field.Textarea
            @label='Message'
            @description='Form-level @onChange fires on every keystroke, providing real-time data updates'
            rows='4'
            placeholder='Type something to see form-level change events...'
          />
        </form.Field>
      </Form>

      <div class='p-4 bg-neutral-subtle rounded'>
        <div class='space-y-2 text-sm'>
          <div>
            <strong>Form @onChange events:</strong>
            <span class='ml-2'>{{this.changeEventCount}}</span>
            <p class='text-neutral mt-1'>
              Fires on every keystroke, providing complete form data
            </p>
          </div>
          <div class='pt-2 border-t border-neutral-subtle'>
            <strong>Current value length:</strong>
            <span class='ml-2'>{{this.formData.text.length}} characters</span>
          </div>
          <div>
            <strong>Current value:</strong>
            <p class='mt-1 break-words rounded border border-neutral-subtle bg-surface-card p-2 text-neutral-strong'>
              {{if this.formData.text this.formData.text '(empty)'}}
            </p>
          </div>
        </div>
      </div>
    </div>
  </template>
}
```

### Form Validation

The Textarea component integrates with the Form validation system, providing automatic error display and field-level validation using Valibot schema.

```gts preview collapsible
import Component from '@glimmer/component';
import { tracked } from '@glimmer/tracking';
import { array } from '@ember/helper';
import { Form, type FormResultData, type FormErrors } from 'frontile';
import { Button } from 'frontile';
import * as v from 'valibot';

// Define validation schema
const schema = v.object({
  feedback: v.pipe(
    v.string(),
    v.nonEmpty('Feedback is required'),
    v.minLength(10, 'Feedback must be at least 10 characters long'),
    v.maxLength(500, 'Feedback must be less than 500 characters')
  )
});

type Schema = v.InferOutput<typeof schema>;

export default class ValidatedTextarea extends Component {
  @tracked formData: Schema = {
    feedback: ''
  };
  @tracked submitMessage = '';

  handleFormChange = (result: FormResultData<Schema>) => {
    this.formData = result.data;
  };

  handleFormSubmit = async (result: FormResultData<Schema>) => {
    this.submitMessage = 'Feedback submitted successfully!';
    console.log('Form submitted:', result.data);
  };

  handleFormError = (errors: FormErrors) => {
    console.log('Validation errors:', errors);
  };

  <template>
    <div class='demo-stack'>
      <Form
        @data={{this.formData}}
        @schema={{schema}}
        @onChange={{this.handleFormChange}}
        @onSubmit={{this.handleFormSubmit}}
        @onError={{this.handleFormError}}
        @validateOn={{array 'change' 'submit'}}
        as |form|
      >
        <form.Field @name='feedback' as |field|>
          <field.Textarea
            @label='Your Feedback'
            @isRequired={{true}}
            rows='5'
            placeholder='Please share your thoughts...'
          />
        </form.Field>

        <div class='flex justify-between items-center text-sm text-neutral'>
          <span>{{this.formData.feedback.length}}/500 characters</span>
          <Button type='submit' disabled={{form.isLoading}}>
            {{if form.isLoading 'Submitting...' 'Submit Feedback'}}
          </Button>
        </div>
      </Form>

      {{#if this.submitMessage}}
        <div class='p-3 bg-success-subtle text-success-strong rounded'>
          {{this.submitMessage}}
        </div>
      {{/if}}
    </div>
  </template>
}
```

### Complete Form Example

This example shows a Textarea integrated with the Form validation system, combining Input and Textarea fields with Valibot schema validation.

```gts preview collapsible
import Component from '@glimmer/component';
import { tracked } from '@glimmer/tracking';
import { array } from '@ember/helper';
import { Form, type FormResultData, type FormErrors } from 'frontile';
import { Button } from 'frontile';
import * as v from 'valibot';

const schema = v.object({
  email: v.pipe(
    v.string(),
    v.nonEmpty('Email is required'),
    v.email('Please enter a valid email address')
  ),
  subject: v.pipe(
    v.string(),
    v.nonEmpty('Subject is required'),
    v.minLength(5, 'Subject must be at least 5 characters')
  ),
  message: v.pipe(
    v.string(),
    v.nonEmpty('Message is required'),
    v.minLength(20, 'Message must be at least 20 characters long'),
    v.maxLength(1000, 'Message must be less than 1000 characters')
  )
});

type Schema = v.InferOutput<typeof schema>;

export default class CompleteFormWithTextarea extends Component {
  @tracked formData: Schema = {
    email: '',
    subject: '',
    message: ''
  };

  handleFormChange = (result: FormResultData<Schema>) => {
    this.formData = result.data;
  };

  handleFormSubmit = (result: FormResultData<Schema>) => {
    console.log('Form submitted:', result.data);
  };

  <template>
    <div class='demo-stack'>
      <Form
        @data={{this.formData}}
        @schema={{schema}}
        @onChange={{this.handleFormChange}}
        @onSubmit={{this.handleFormSubmit}}
        @validateOn={{array 'change' 'submit'}}
        as |form|
      >
        <form.Field @name='email' as |field|>
          <field.Input
            @label='Email Address'
            @type='email'
            @isRequired={{true}}
          />
        </form.Field>

        <form.Field @name='subject' as |field|>
          <field.Input
            @label='Subject'
            @isRequired={{true}}
          />
        </form.Field>

        <form.Field @name='message' as |field|>
          <field.Textarea
            @label='Message'
            @isRequired={{true}}
            rows='6'
          />
        </form.Field>

        <Button type='submit'>
          Send Message
        </Button>
      </Form>
    </div>
  </template>
}
```

### Miscellaneous Options

The Textarea component supports various optional configurations for sizing, layout, and styling.

```gts preview collapsible
import { Textarea } from 'frontile';
import { hash } from '@ember/helper';

<template>
  <div class='demo-stack'>
    {{! Size variants }}
    <div>
      <h4 class='text-sm font-medium mb-2'>Size Variants</h4>
      <div class='flex flex-col gap-3'>
        <Textarea @label='Small' @size='sm' rows='3' />
        <Textarea @label='Medium' @size='md' rows='3' />
        <Textarea @label='Large' @size='lg' rows='3' />
      </div>
    </div>

    {{! Rows and resize behavior }}
    <div>
      <h4 class='text-sm font-medium mb-2'>Rows and Resize Behavior</h4>
      <div class='flex flex-col gap-3'>
        <Textarea @label='Fixed (No Resize)' rows='3' style='resize: none;' />
        <Textarea @label='Vertical Resize' rows='4' style='resize: vertical;' />
        <Textarea @label='Tall (8 rows)' rows='8' />
      </div>
    </div>

    {{! With description }}
    <div>
      <h4 class='text-sm font-medium mb-2'>With Description</h4>
      <Textarea
        @label='Biography'
        @description='Tell us about yourself'
        rows='4'
      />
    </div>

    {{! Custom styling }}
    <div>
      <h4 class='text-sm font-medium mb-2'>Custom Styling</h4>
      <Textarea
        @label='Custom Classes'
        @classes={{hash
          base='my-custom-form-control'
          input='my-custom-textarea-field'
        }}
        rows='3'
      />
    </div>
  </div>
</template>
```

## Accessibility

The Textarea component follows accessibility best practices:

- Proper label association using `for` and `id` attributes
- ARIA attributes for invalid states (`aria-invalid`)
- Descriptive text association using `aria-describedby`
- Support for required field indication
- Keyboard navigation support follows standard textarea behavior
- Screen reader announcements for validation messages and descriptions
- Maintains proper focus management

## API

### Textarea

**Element:** `HTMLTextAreaElement`

**Arguments**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `classes` | `SlotsToClasses<'base' \| 'innerContainer' \| 'startContent' \| 'endContent' \| 'input'>` | - | Class names for each slot of the component, merged with the theme's. |
| `description` | `string` | - | Help text rendered between the label and the control, and referenced by the ids describedBy returns. |
| `errors` | `string \| string[]` | - | Validation messages for the field. A non-empty value also marks the control invalid, and an array is joined with ;  when displayed. |
| `id` | `string` | - | The id attribute of the textarea, also used to associate the label and description with it. One is generated when this is omitted. |
| `isDisabled` | `boolean` | `false` | Whether the field is disabled. FormControl passes this through for styling; the control it wraps is responsible for the disabled attribute. |
| `isInvalid` | `boolean` | `false` | Marks the control invalid without supplying messages, for validation that is reported elsewhere. |
| `isRequired` | `boolean` | `false` | Whether the field is required. Adds an asterisk to the label; it does not set the required attribute on the control itself. |
| `label` | `string` | - | The label text rendered above the control and associated with it via for. Use the :label block instead when the label needs markup. |
| `name` | `string` | - | The name attribute of the underlying textarea, used when it is submitted as part of a form. |
| `onBlur` | `() => void` | - | Callback when onblur is triggered |
| `onChange` | `(value: string, event: InputEvent) => void` | - | Callback when onchange is triggered |
| `onInput` | `(value: string, event: InputEvent) => void` | - | Callback when oninput is triggered |
| `size` | `'sm' \| 'md' \| 'lg'` | `'md'` | The size of the textarea and its label. |
| `value` | `string \| number \| boolean` | - | The value of the textarea. Pair with onInput or onChange to control it; leave it unset to let the element track its own value. |

---

# Toast Notification

Source: /docs/components/notifications/notifications.md

# Toast Notification

Toast notifications give brief, non-intrusive feedback about an operation — a save
succeeded, an upload failed, an item can still be undone — through a small popup that
disappears on its own and never demands the user's attention the way a modal does. Reach
for a modal instead when the message needs a decision, and for inline validation when it's
about a specific form field.

## Import

```js
import {
  NotificationsContainer,
  type NotificationsService
} from 'frontile';
```

## Usage

`NotificationsContainer` renders `notifications.notifications` from the **shared,
application-wide** notifications service — it does not own any notification data itself.
Mount exactly one `NotificationsContainer`, in your application template, rather than one
per feature or component:

```hbs
{{! app/templates/application.hbs }}
<div id='app-content'>
  {{outlet}}
</div>

{{! Global notifications container }}
<NotificationsContainer @placement='bottom-right' />
```

> **Important**: if more than one `NotificationsContainer` is mounted at the same time,
> **every** container renders **every** notification, so each toast appears once per mounted
> container. A single global container also gives you one place to configure placement and
> handle dismissal callbacks (see [Dismissal Callbacks and Metadata](#dismissal-callbacks-and-metadata)).

With the container mounted, inject the notifications service anywhere and call `add`:

```gts preview
import Component from '@glimmer/component';
import { service } from '@ember/service';
import { Button } from 'frontile';
import type { NotificationsService } from 'frontile';

export default class BasicExample extends Component {
  @service notifications!: NotificationsService;

  showNotification = () => {
    this.notifications.add('This is a basic notification!');
  };

  <template>
    <Button @onPress={{this.showNotification}}>
      Show Notification
    </Button>
  </template>
}
```

## Statuses

Use `status` to convey the appropriate message type: `'neutral'`, `'primary'`, `'success'`,
`'warning'`, or `'danger'`. Each status renders a matching icon automatically; pass
`hideIcon: true` to suppress it.

`'neutral'` is the status used when none is given — a bare `notifications.add('message')`
produces a `neutral` toast. It still renders the same info glyph as `'primary'`, just
in a neutral color rather than the primary accent, so callers who want the old
accented look pass `status: 'primary'` explicitly.

```gts preview collapsible
import Component from '@glimmer/component';
import { service } from '@ember/service';
import { Button } from 'frontile';
import type { NotificationsService } from 'frontile';

export default class StatusExample extends Component {
  @service notifications!: NotificationsService;

  showDefault = () => {
    this.notifications.add('This is a default notification');
  };

  showInfo = () => {
    this.notifications.add('This is an info notification', {
      status: 'primary'
    });
  };

  showSuccess = () => {
    this.notifications.add('Operation completed successfully!', {
      status: 'success'
    });
  };

  showWarning = () => {
    this.notifications.add('Please check your input', {
      status: 'warning'
    });
  };

  showDanger = () => {
    this.notifications.add('Something went wrong', {
      status: 'danger'
    });
  };

  <template>
    <div class='grid grid-cols-2 gap-2'>
      <Button @onPress={{this.showDefault}}>Default</Button>
      <Button @onPress={{this.showInfo}}>Info</Button>
      <Button @onPress={{this.showSuccess}} @color='success'>Success</Button>
      <Button @onPress={{this.showWarning}} @color='warning'>Warning</Button>
      <Button @onPress={{this.showDanger}} @color='danger'>Danger</Button>
    </div>
  </template>
}
```

> **Note**: `appearance` still works but is deprecated — see [Migrating from `appearance`](#migrating-from-appearance) below.

## Title and Description

`add` takes the title as a string, with an optional `description` alongside it, or a single content object with both fields.

```gts preview collapsible
import Component from '@glimmer/component';
import { service } from '@ember/service';
import { Button } from 'frontile';
import type { NotificationsService } from 'frontile';

export default class DescriptionExample extends Component {
  @service notifications!: NotificationsService;

  showStringForm = () => {
    this.notifications.add('Event created', {
      description: 'The event starts at 8:00 AM.',
      status: 'success'
    });
  };

  showObjectForm = () => {
    this.notifications.add({
      title: 'Event created',
      description: 'The event starts at 8:00 AM.'
    });
  };

  <template>
    <div class='flex gap-2'>
      <Button @onPress={{this.showStringForm}}>
        String + Options
      </Button>
      <Button @onPress={{this.showObjectForm}} @variant='outline'>
        Content Object
      </Button>
    </div>
  </template>
}
```

## Variants

`@variant` on `NotificationsContainer` controls the surface style applied to every card in
the stack:

- **`default`** — a neutral opaque card; the status color is carried only by the icon and title.
- **`tonal`** — the same recipe as `Button`'s `variant="soft"`: an opaque neutral card
  whose inner row carries a translucent `{status}-soft` tint with its `on-{status}-soft`
  contrast text, so the card stays fully opaque while the tint reads like a tonal button.
- **`solid`** — a filled surface in the status color, with contrast text.

```gts
<NotificationsContainer @variant='tonal' />
```

Try all three live in the [Stacking](#stacking) demo below — its variant control drives the
one container mounted on this page.

## Placement

`@placement` controls which corner or edge the stack sits on: `'top-left'`, `'top-center'`,
`'top-right'`, `'bottom-left'`, `'bottom-center'`, or `'bottom-right'` (the default).
Placement only decides which edge the stack is pinned to — newer notifications always stack
toward the front regardless of placement.

```gts
<NotificationsContainer @placement='top-right' />
```

Compare placements live in the [Stacking](#stacking) demo below.

## Stacking

Collapsed, the stack shows only the front few cards peeking out from behind each other;
hovering or focusing it expands the whole stack so every toast is readable. Three
container arguments control this:

- **`@visibleToasts`** (default `3`) — how many cards stay visible while collapsed.
- **`@spacing`** (default `16`) — the peek offset between collapsed cards, in pixels, and
  also the gap between cards once the stack is expanded.
- **`@expand`** (default `false`) — keep the stack always expanded instead of collapsing it
  when it isn't hovered or focused.

Because only one `NotificationsContainer` should ever be mounted at a time, this single demo
drives that one container from every argument covered in this section as well as
[Variants](#variants) and [Placement](#placement) above — rather than mounting a second
container per argument.

```gts preview collapsible
import Component from '@glimmer/component';
import { tracked } from '@glimmer/tracking';
import { service } from '@ember/service';
import {
  Button,
  RadioGroup,
  Switch,
  NotificationsContainer,
  type NotificationsService,
  type NotificationStatus
} from 'frontile';

export default class StackingExample extends Component {
  @service notifications!: NotificationsService;

  @tracked variant: 'default' | 'tonal' | 'solid' = 'default';
  @tracked placement = 'bottom-right';
  @tracked visibleToastsKey = '3';
  @tracked expand = false;

  variants = [
    { key: 'default', label: 'Default' },
    { key: 'tonal', label: 'Tonal' },
    { key: 'solid', label: 'Solid' }
  ];

  placements = [
    { key: 'top-left', label: 'Top Left' },
    { key: 'top-center', label: 'Top Center' },
    { key: 'top-right', label: 'Top Right' },
    { key: 'bottom-left', label: 'Bottom Left' },
    { key: 'bottom-center', label: 'Bottom Center' },
    { key: 'bottom-right', label: 'Bottom Right' }
  ];

  visibleToastsOptions = [
    { key: '2', label: '2' },
    { key: '3', label: '3' },
    { key: '5', label: '5' }
  ];

  statuses: NotificationStatus[] = [
    'default',
    'info',
    'success',
    'warning',
    'danger'
  ];

  get visibleToasts() {
    return parseInt(this.visibleToastsKey, 10) || 3;
  }

  setVariant = (variant: string) => {
    this.variant = variant as 'default' | 'tonal' | 'solid';
  };

  setPlacement = (placement: string) => {
    this.placement = placement;
  };

  setVisibleToasts = (value: string) => {
    this.visibleToastsKey = value;
  };

  toggleExpand = (value: boolean) => {
    this.expand = value;
  };

  showAllStatuses = () => {
    this.statuses.forEach((status) => {
      this.notifications.add(`${status} notification`, {
        status,
        preserve: true
      });
    });
  };

  showFive = () => {
    for (let i = 1; i <= 5; i++) {
      this.notifications.add(`Notification ${i}`, { preserve: true });
    }
  };

  clear = () => {
    this.notifications.removeAll();
  };

  <template>
    <div class='flex flex-col gap-4'>
      <div class='grid grid-cols-1 sm:grid-cols-3 gap-4'>
        <RadioGroup
          @label='Variant'
          @value={{this.variant}}
          @onChange={{this.setVariant}}
          as |Radio|
        >
          {{#each this.variants as |option|}}
            <Radio @value={{option.key}} @label={{option.label}} />
          {{/each}}
        </RadioGroup>

        <RadioGroup
          @label='Placement'
          @value={{this.placement}}
          @onChange={{this.setPlacement}}
          as |Radio|
        >
          {{#each this.placements as |option|}}
            <Radio @value={{option.key}} @label={{option.label}} />
          {{/each}}
        </RadioGroup>

        <RadioGroup
          @label='Visible Toasts'
          @value={{this.visibleToastsKey}}
          @onChange={{this.setVisibleToasts}}
          as |Radio|
        >
          {{#each this.visibleToastsOptions as |option|}}
            <Radio @value={{option.key}} @label={{option.label}} />
          {{/each}}
        </RadioGroup>
      </div>

      <Switch
        @label='Keep stack expanded (@expand)'
        @isSelected={{this.expand}}
        @onChange={{this.toggleExpand}}
      />

      <div class='flex flex-wrap gap-2'>
        <Button @onPress={{this.showAllStatuses}}>Show All Statuses</Button>
        <Button @onPress={{this.showFive}}>Show 5 Notifications</Button>
        <Button @onPress={{this.clear}} @variant='outline'>Clear</Button>
      </div>

      <p class='text-body-2xs text-neutral-muted'>
        Hover or focus the stack to expand it (or toggle "Keep stack expanded"
        above). Collapsed, it shows
        {{this.visibleToasts}}
        card(s) peeking; the rest stay tucked behind them.
      </p>

      <NotificationsContainer
        @placement={{this.placement}}
        @variant={{this.variant}}
        @visibleToasts={{this.visibleToasts}}
        @expand={{this.expand}}
      />
    </div>
  </template>
}
```

## Custom Actions

Add action buttons to notifications for user interaction.

```gts preview collapsible
import Component from '@glimmer/component';
import { service } from '@ember/service';
import { tracked } from '@glimmer/tracking';
import { Button } from 'frontile';
import type { NotificationsService } from 'frontile';

export default class ActionsExample extends Component {
  @service notifications!: NotificationsService;
  @tracked result = '';

  showWithActions = () => {
    this.result = '';
    this.notifications.add('File uploaded successfully!', {
      status: 'success',
      duration: 10000, // Keep it open longer for user to act
      customActions: [
        {
          label: 'View',
          onClick: () => {
            this.result = 'User clicked View';
          }
        },
        {
          label: 'Share',
          onClick: () => {
            this.result = 'User clicked Share';
          }
        }
      ]
    });
  };

  showUndoAction = () => {
    this.result = '';
    this.notifications.add('Item deleted', {
      status: 'primary',
      duration: 8000,
      customActions: [
        {
          label: 'Undo',
          onClick: () => {
            this.result = 'Undo clicked - item restored!';
          }
        }
      ]
    });
  };

  <template>
    <div class='flex flex-col gap-4'>
      <div class='flex gap-2'>
        <Button @onPress={{this.showWithActions}}>
          Upload Success with Actions
        </Button>
        <Button @onPress={{this.showUndoAction}}>
          Show Undo Action
        </Button>
      </div>

      {{#if this.result}}
        <div
          class='p-3 rounded border bg-success-subtle text-success-strong border-success-muted'
        >
          {{this.result}}
        </div>
      {{/if}}
    </div>
  </template>
}
```

## Duration and Persistence

Every notification auto-dismisses after `duration` milliseconds (default `5000`), unless
`preserve: true` keeps it open until the user (or a custom action) closes it.

```gts preview collapsible
import Component from '@glimmer/component';
import { service } from '@ember/service';
import { tracked } from '@glimmer/tracking';
import { Button } from 'frontile';
import { Input } from 'frontile';
import type { NotificationsService } from 'frontile';

export default class TimingExample extends Component {
  @service notifications!: NotificationsService;
  @tracked duration = 3000;

  showShortDuration = () => {
    this.notifications.add('Quick notification (1 second)', {
      status: 'primary',
      duration: 1000
    });
  };

  showLongDuration = () => {
    this.notifications.add('Long notification (10 seconds)', {
      status: 'warning',
      duration: 10000
    });
  };

  showCustomDuration = () => {
    this.notifications.add(`Custom duration (${this.duration}ms)`, {
      status: 'success',
      duration: this.duration
    });
  };

  updateDuration = (value) => {
    this.duration = parseInt(value) || 3000;
  };

  <template>
    <div class='flex flex-col gap-4'>
      <Input
        @label='Duration (ms)'
        @type='number'
        @value={{this.duration}}
        @onInput={{this.updateDuration}}
      />

      <div class='flex gap-2'>
        <Button @onPress={{this.showShortDuration}}>
          1 Second
        </Button>
        <Button @onPress={{this.showLongDuration}}>
          10 Seconds
        </Button>
        <Button @onPress={{this.showCustomDuration}}>
          Custom Duration
        </Button>
      </div>
    </div>
  </template>
}
```

Use `preserve: true` to prevent automatic dismissal entirely, and `allowClosing: false` to
also hide the close button — pair the latter with a custom action so the notification still
has a way out.

```gts preview collapsible
import Component from '@glimmer/component';
import { service } from '@ember/service';
import { Button } from 'frontile';
import type { NotificationsService } from 'frontile';

export default class PersistentExample extends Component {
  @service notifications!: NotificationsService;

  showPersistent = () => {
    this.notifications.add('This notification stays until manually closed', {
      status: 'warning',
      preserve: true
    });
  };

  showWithoutCloseButton = () => {
    this.notifications.add('No close button - click actions to dismiss', {
      status: 'primary',
      preserve: true,
      allowClosing: false,
      customActions: [
        {
          label: 'Got it',
          onClick: () => {
            // This will dismiss the notification
          }
        }
      ]
    });
  };

  <template>
    <div class='flex gap-2'>
      <Button @onPress={{this.showPersistent}}>
        Persistent Notification
      </Button>
      <Button @onPress={{this.showWithoutCloseButton}}>
        No Close Button
      </Button>
    </div>
  </template>
}
```

> Auto-dismissal pauses for every visible notification while the stack is hovered or
> focused, not just the one under the pointer — see [Accessibility](#accessibility).

## Promise-Driven Notifications

`promise()` shows a loading toast with a spinner, then mutates that same toast into a
success or error state once the promise settles — no second toast is created. While
pending, the toast cannot be dismissed. `loading` takes a string or a `{ title, description }`
object; `success` and `error` each take a string, a `{ title, description }` object, or a
function of the resolved value (for `success`) or rejection reason (for `error`) returning
either.

`promise()` returns the **original promise** unchanged, so the caller still owns rejection
handling — the toast alone does not swallow a rejection. Any other notification option
passed alongside `loading`/`success`/`error` — `preserve` included — carries through to the
settled notification: the loading phase is always non-dismissible while pending, but once it
settles, a caller's own `preserve: true` is honored rather than silently overridden.

```gts preview collapsible
import Component from '@glimmer/component';
import { service } from '@ember/service';
import { Button } from 'frontile';
import type { NotificationsService } from 'frontile';

interface Event {
  name: string;
}

export default class PromiseExample extends Component {
  @service notifications!: NotificationsService;

  saveEvent = (shouldFail: boolean): Promise<Event> => {
    return new Promise((resolve, reject) => {
      setTimeout(() => {
        if (shouldFail) {
          reject(new Error('Network error'));
        } else {
          resolve({ name: 'Team sync' });
        }
      }, 1500);
    });
  };

  save = () => {
    this.notifications.promise(this.saveEvent(false), {
      loading: 'Saving event…',
      success: (event) => ({
        title: 'Event created',
        description: `${event.name} starts at 8:00 AM.`
      }),
      error: (e) => `Could not save: ${(e as Error).message}`
    });
  };

  saveWithError = () => {
    // promise() returns the original promise, so rejection handling is
    // still ours even though the toast already told the user what happened.
    this.notifications
      .promise(this.saveEvent(true), {
        loading: 'Saving event…',
        success: (event) => ({
          title: 'Event created',
          description: `${event.name} starts at 8:00 AM.`
        }),
        error: (e) => `Could not save: ${(e as Error).message}`
      })
      .catch(() => {
        // Already surfaced to the user as a toast.
      });
  };

  <template>
    <div class='flex flex-col gap-4'>
      <div class='flex gap-2'>
        <Button @onPress={{this.save}}>Save (succeeds)</Button>
        <Button @onPress={{this.saveWithError}} @variant='outline'>
          Save (fails)
        </Button>
      </div>
    </div>
  </template>
}
```

## Dismissal Callbacks and Metadata

Track notification dismissals for analytics, backend updates, or cleanup. Set the callback
on the global container, in your application template:

`@onDismiss` is called **exactly once per notification**, after it has actually been
removed — repeated dismissals of the same notification (e.g. a double-click on the close
button) do not call it again. The callback is always read from the current `@onDismiss`
argument, so changing it at runtime takes effect immediately.

```hbs
{{! app/templates/application.hbs }}
<NotificationsContainer
  @placement='bottom-right'
  @onDismiss={{this.handleNotificationDismissed}}
/>
```

```gts
// app/controllers/application.ts
import Controller from '@ember/controller';

export default class ApplicationController extends Controller {
  handleNotificationDismissed = (notification) => {
    if (notification.metadata) {
      this.analytics.track('notification_dismissed', notification.metadata);
    }
  };
}
```

Then from any component, add notifications with metadata:

```gts preview
import Component from '@glimmer/component';
import { service } from '@ember/service';
import { Button } from 'frontile';
import type { NotificationsService } from 'frontile';

export default class CallbackExample extends Component {
  @service notifications!: NotificationsService;

  showWithCallback = () => {
    this.notifications.add('Notification with tracking', {
      status: 'primary',
      metadata: {
        id: `notification_${Date.now()}`,
        source: 'demo',
        action: 'user_interaction'
      }
    });
  };

  <template>
    <Button @onPress={{this.showWithCallback}}>
      Show Tracked Notification
    </Button>
  </template>
}
```

Use a TypeScript generic on `add` for strongly-typed metadata, so a reader (or the compiler)
knows exactly what shape to expect back from `notification.metadata`:

```typescript
interface UserActionMetadata {
  userId: string;
  action: 'upload' | 'delete' | 'share';
  resourceId: string;
  timestamp: string;
}

const notification = this.notifications.add<UserActionMetadata>(
  'File uploaded successfully',
  {
    status: 'success',
    metadata: {
      userId: '123',
      action: 'upload',
      resourceId: 'file-456',
      timestamp: new Date().toISOString()
    }
  }
);

// notification.metadata is now strongly typed as UserActionMetadata
```

## Accessibility

- **ARIA Attributes**: The container uses `role="region"`, `aria-label="Notifications"`, and
  `aria-live="polite"`. Each card carries `role="status"` (default, info, success) or
  `role="alert"` (warning, danger) — `alert` is reserved for statuses that warrant interrupting the screen
  reader.
- **Screen Reader Support**: Notifications are announced as they appear, without stealing
  focus.
- **Keyboard Navigation**: The stack expands on `focusin` as well as hover, so keyboard users
  reach the same expanded view; close buttons and custom actions are focusable and operable
  with the keyboard.
- **Hover and Focus Behavior**: Auto-dismissal pauses for every visible notification while the
  stack is hovered or focused, not just the one underneath the pointer.
- **Text Contrast**: `default` uses the brightest levels of the `success`/`warning` palette scale
  at the `firm` level the other statuses' title/icon text uses, so both fall below the 4.5:1 WCAG
  AA floor at `firm` — the theme uses `bolder` for their title/icon text instead. `tonal` composites
  the translucent `{status}-soft` tint over the card's opaque surface and pairs it with the
  auto-generated `on-{status}-soft` contrast ink (the same recipe `Button`'s `variant="soft"`
  uses), which clears AA for every status in both themes without any hand-picked text level or
  background override. `solid`'s title, icon, and description all use the full-strength
  `on-{status}` ink — an earlier version put the description at 80% opacity, but compositing
  white/black at 80% over a saturated fill (e.g. `danger`'s `#e51701`) drops as low as 3.37:1 in
  light mode, well below the 4.5:1 WCAG AA floor. Measured ratios (WCAG relative luminance,
  resolving the composited `{status}-soft`-over-surface color where relevant):

  | Pairing                                                            | Light     | Dark        |
  | ------------------------------------------------------------------ | --------- | ----------- |
  | `default`/`tonal` description (`text-neutral-firm`)                | 8.1       | 8.9–11.6    |
  | `default` `success`/`warning` title (`bolder`)                     | 9.3 / 7.6 | 16.3 / 11.4 |
  | `default` `info`/`danger`/neutral title                            | ≥5.6      | ≥6.4        |
  | `tonal` `default` (`on-neutral-soft` on composited `neutral-soft`) | 15.4      | 8.1         |
  | `tonal` `info` (`on-primary-soft` on composited `primary-soft`)    | 18.0      | 12.4        |
  | `tonal` `success` (`on-success-soft` on composited `success-soft`) | 19.5      | 12.0        |
  | `tonal` `warning` (`on-warning-soft` on composited `warning-soft`) | 17.9      | 13.8        |
  | `tonal` `danger` (`on-danger-soft` on composited `danger-soft`)    | 16.4      | 16.6        |
  | `solid` `default` title/icon/description (`on-neutral`)            | 6.71      | 9.60        |
  | `solid` `info` title/icon/description (`on-primary`)               | 6.49      | 9.72        |
  | `solid` `success` title/icon/description (`on-success`)            | 16.29     | 16.29       |
  | `solid` `warning` title/icon/description (`on-warning`)            | 9.41      | 9.41        |
  | `solid` `danger` title/icon/description (`on-danger`)              | 4.71      | 6.09        |

## Migrating from `appearance`

The notification API was redesigned in 0.18: `message` became the title with a new sibling
`description`, `appearance` was renamed `status` (`'error'` became `'danger'`, `'info'` became `'primary'`), the container
gained a collapsible stack, and the theme slots changed to match. `appearance` keeps working
until 0.19, emitting a deprecation warning.

**The default status changed from `'info'` to `'neutral'`**

A bare `add()` call with no `status` option used to render as an `info`-colored (primary/teal)
toast. It now renders as a neutral `default` toast — same info icon, no accent color. This is
an intentional visual behavior change. Callers who want the previous accented look should pass
`status: 'primary'` explicitly:

```ts
// Before: a bare add() was info-colored
this.notifications.add('Saved');

// After: a bare add() is neutral; pass status explicitly for the old look
this.notifications.add('Saved', { status: 'primary' });
```

**`appearance` → `status`, `'error'` → `'danger'`**

```ts
// Before
this.notifications.add('Something went wrong', { appearance: 'error' });

// After
this.notifications.add('Something went wrong', { status: 'danger' });
```

**Reading `notification.appearance` back can now yield `'neutral'`**

The deprecated `appearance` getter on a `Notification` instance mirrors `status`, and since
`default` is now the status a bare `add()` call resolves to, `appearance` can return `'neutral'`
for it — a value that isn't part of the exported `NotificationAppearance` type (`'info' |
'success' | 'warning' | 'error'`). Code that still reads this getter should account for it:
assigning it to a `NotificationAppearance`-typed variable is a compile error, and a `switch`
over the four old names silently falls through for every notification created without an
explicit `appearance`/`status`. Add a `'neutral'` case (or switch to `status`, which is typed
to include it):

```ts
// Reading the deprecated getter still compiles, but 'default' needs handling
switch (notification.appearance) {
  case 'default':
    // new: bare add() calls land here now
    break;
  case 'info':
  case 'success':
  case 'warning':
  case 'error':
    // ...
    break;
}
```

**`notificationTransitions` removed**

`notificationTransitions` is no longer exported from `@frontile/theme`, and the
`.notification-transition--*` classes were removed from the Tailwind plugin and its safelist.
Transitions are now built into the `notificationCard` and `notificationsContainer` theme
slots directly — remove any import of `notificationTransitions` and any manual use of those
classes.

```ts
// Before
import { notificationTransitions } from '@frontile/theme';

// After
// no import needed — transitions ship with the component styles
```

**`notificationCard` theme slots**

The `message` slot was replaced by `title` and `description`, and `icon` and `content` slots
were added. Update any `registerCustomStyles({ notificationCard })` call accordingly:

```ts
// Before
registerCustomStyles({
  notificationCard: tv({
    slots: {
      base: '...',
      message: '...',
      closeButton: '...'
    }
  })
});

// After
registerCustomStyles({
  notificationCard: tv({
    slots: {
      base: '...',
      icon: '...',
      content: '...',
      title: '...',
      description: '...',
      closeButton: '...'
    }
  })
});
```

**`notificationCard` gained an `inner` slot**

The card is now two elements: `base` (the outer box — surface color, border, rounded corners,
shadow, and the collapsed-stack height clamp) and `inner` (a new slot — the flex row layout:
gap, padding, and icon/content-alignment). This split exists so the stack's height measurement
always reads the content's true natural height rather than whatever height `base` might be
clamped to while the stack is collapsed. If you override `notificationCard`, add an `inner`
slot for the row layout (`flex gap-3 p-4`) and move any padding/gap/alignment classes off
`base` and onto it; `base` should keep only box/surface classes.

**`notificationsContainer` theme slots**

`notificationsContainer` now returns `base` and `stack` slots instead of a single class
string:

```ts
// Before
registerCustomStyles({
  notificationsContainer: tv({
    base: '...'
  })
});

// After
registerCustomStyles({
  notificationsContainer: tv({
    slots: {
      base: '...',
      stack: '...'
    }
  })
});
```

**ARIA attributes**

The container's live region moved from `role="alert"` + `aria-live="assertive"` to
`role="region"` + `aria-label="Notifications"` + `aria-live="polite"`, so the whole stack no
longer interrupts a screen reader on every new toast. Each card now carries its own
`role="status"` (default/info/success) or `role="alert"` (warning/danger) instead. No consumer code
change is required, but update any test or a11y check that asserted the old attributes.

## API

### NotificationsService

The notifications service manages the global notification state and provides methods for adding and removing notifications.

| Method                  | Parameters                                                                           | Return Type               | Description                                                                                                      |
| ----------------------- | ------------------------------------------------------------------------------------ | ------------------------- | ---------------------------------------------------------------------------------------------------------------- |
| `add<TMetadata>`        | `content: string \| NotificationContent`, `options?: NotificationOptions<TMetadata>` | `Notification<TMetadata>` | Adds a new notification with optional metadata and configuration                                                 |
| `promise<T, TMetadata>` | `promise: Promise<T>`, `options: PromiseNotificationOptions<T, TMetadata>`           | `Promise<T>`              | Shows a loading toast that mutates into success or danger when the promise settles; returns the original promise |
| `remove`                | `notification?: Notification`                                                        | `void`                    | Removes a specific notification                                                                                  |
| `removeAll`             | -                                                                                    | `void`                    | Removes all current notifications                                                                                |
| `setOnRemoveCallback`   | `callback?: (notification: Notification) => void`                                    | `void`                    | Sets a global callback for when notifications are dismissed                                                      |

| Property        | Type             | Description                                |
| --------------- | ---------------- | ------------------------------------------ |
| `notifications` | `Notification[]` | Array of current notifications (read-only) |

### Notification Options

All options available when creating notifications with `add`:

| Option               | Type                                                        | Default     | Description                                                                                                                                                         |
| -------------------- | ----------------------------------------------------------- | ----------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `status`             | `'default' \| 'info' \| 'success' \| 'warning' \| 'danger'` | `'neutral'` | The status of the notification                                                                                                                                      |
| `appearance`         | `'info' \| 'success' \| 'warning' \| 'error'`               | `undefined` | **Deprecated** — use `status` instead. `'error'` maps to `'danger'`. Removed in 0.19                                                                                |
| `description`        | `string`                                                    | `undefined` | Supporting text rendered below the title (string content form only)                                                                                                 |
| `duration`           | `number`                                                    | `5000`      | Auto-dismiss time in milliseconds                                                                                                                                   |
| `preserve`           | `boolean`                                                   | `false`     | Prevent auto-dismissal                                                                                                                                              |
| `allowClosing`       | `boolean`                                                   | `true`      | Show close button                                                                                                                                                   |
| `transitionDuration` | `number`                                                    | `200`       | Duration of the enter/exit fade, in milliseconds. Card slide/scale and the container's expand-collapse height animate at a fixed 400ms, independent of this option. |
| `hideIcon`           | `boolean`                                                   | `false`     | Hide the leading status icon                                                                                                                                        |
| `customActions`      | `CustomAction[]`                                            | `undefined` | Array of action buttons                                                                                                                                             |
| `metadata`           | `TMetadata`                                                 | `undefined` | Custom data attached to the notification                                                                                                                            |

> The `title` (or `message` for backwards compatibility) comes from the `content` argument to
> `add`, either as a plain string or as `{ title, description }`.

### Promise Options

Options for `promise()`, in addition to everything above except `isLoading` (which `promise()` manages itself):

| Option    | Type                                                                         | Description                                       |
| --------- | ---------------------------------------------------------------------------- | ------------------------------------------------- |
| `loading` | `string \| NotificationContent`                                              | Shown with a spinner while the promise is pending |
| `success` | `string \| NotificationContent \| (value) => string \| NotificationContent`  | Shown when the promise resolves                   |
| `error`   | `string \| NotificationContent \| (reason) => string \| NotificationContent` | Shown when the promise rejects                    |

### CustomAction

Structure for notification action buttons:

| Property  | Type         | Description                            |
| --------- | ------------ | -------------------------------------- |
| `label`   | `string`     | Text displayed on the button           |
| `onClick` | `() => void` | Function called when button is clicked |

### NotificationsContainer

> The notifications service holds a single `onDismiss` slot. If more than one
> `NotificationsContainer` is rendered at the same time, the most recently rendered one
> owns the callback — another reason to render a single global container.

### NotificationsContainer

**Element:** `HTMLDivElement`

**Arguments**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `class` | `string` | - | Custom class name, it will override the default ones using Tailwind Merge library. |
| `expand` | `boolean` | `false` | Keep the stack expanded instead of collapsing it when not hovered. |
| `onDismiss` | `(notification: Notification<Record<string, unknown>>) => void` | - | Callback called when a notification is dismissed |
| `placement` | `containerPlacement` | `'bottom-right'` | The placement of the notifications |
| `spacing` | `number` | `16` | The peek offset between collapsed cards, and the gap between expanded cards, in px. |
| `variant` | `'solid' \| 'soft' \| 'surface'` | `'surface'` | The visual style applied to every card. |
| `visibleToasts` | `number` | `3` | How many cards stay visible while the stack is collapsed. |

---

# Drawer

Source: /docs/components/overlays/drawer.md

# Drawer

The Drawer component is a slide-out panel that appears from any edge of the screen. It's built on top of the Overlay component and includes all its accessibility features, plus drawer-specific functionality like multiple placement options and sizes.

## Import

```js
import { Drawer } from 'frontile';
```

## Usage

### Basic Drawer

A simple drawer that slides in from the right side.

```gts preview collapsible
import Component from '@glimmer/component';
import { tracked } from '@glimmer/tracking';
import { Drawer } from 'frontile';
import { Button } from 'frontile';

export default class BasicDrawer extends Component {
  @tracked isOpen = false;

  toggle = () => {
    this.isOpen = !this.isOpen;
  };

  <template>
    <div class='demo-stack demo-stack--wide items-center'>
      <Button @size='sm' @onPress={{this.toggle}}>
        Open Drawer
      </Button>

      <Drawer @isOpen={{this.isOpen}} @onClose={{this.toggle}} as |d|>
        <d.Header>
          Basic Drawer
        </d.Header>
        <d.Body>
          <p class='mb-4'>This is the main content of the drawer. You can put
            any content here including forms, lists, or other components.</p>
          <p>The drawer slides in from the right side by default and includes a
            close button in the top right corner.</p>
        </d.Body>
        <d.Footer @class='flex gap-2'>
          <Button @size='sm' @onPress={{this.toggle}}>
            Cancel
          </Button>
          <Button @size='sm' @color='primary'>
            Save
          </Button>
        </d.Footer>
      </Drawer>
    </div>
  </template>
}
```

### Variant

`@variant` controls how the header, body and footer relate to each other. `sectioned` gives
the drawer a black header band, a body on its own surface and a solid footer — this is the
banded treatment. `flat` keeps every region on the same surface as the modal — the flat look
Drawer used before v0.18, kept for consumers who don't want the restyle.

The header API is identical in both variants: `@title`/`@description` and a block yielding
`h.Icon`, `h.Title` and `h.Description` work the same way regardless of which variant is
selected.

```gts preview collapsible
import Component from '@glimmer/component';
import { tracked } from '@glimmer/tracking';
import { fn } from '@ember/helper';
import { Drawer } from 'frontile';
import { Button } from 'frontile';

export default class DrawerVariants extends Component {
  @tracked isOpen = false;
  @tracked selectedVariant = 'sectioned';

  variants = ['sectioned', 'flat'];

  openDrawer = (variant) => {
    this.selectedVariant = variant;
    this.isOpen = true;
  };

  closeDrawer = () => {
    this.isOpen = false;
  };

  <template>
    <div class='flex gap-2'>
      {{#each this.variants as |variant|}}
        <Button @size='sm' @onPress={{fn this.openDrawer variant}}>
          {{variant}}
        </Button>
      {{/each}}
    </div>

    <Drawer
      @isOpen={{this.isOpen}}
      @onClose={{this.closeDrawer}}
      @variant={{this.selectedVariant}}
      as |d|
    >
      <d.Header
        @title='{{this.selectedVariant}} variant'
        @description='Switch variants with the buttons above.'
      />
      <d.Body>
        <p>This is the body content, on its own surface in `sectioned` and flat
          in `flat`.</p>
      </d.Body>
      <d.Footer @class='flex gap-2'>
        <Button @size='sm' @onPress={{this.closeDrawer}}>Close</Button>
      </d.Footer>
    </Drawer>
  </template>
}
```

The same switch works with the block form of `<d.Header>`, including an icon:

```gts preview collapsible
import Component from '@glimmer/component';
import { tracked } from '@glimmer/tracking';
import { fn } from '@ember/helper';
import { Drawer } from 'frontile';
import { Button } from 'frontile';
import { SettingsIcon } from 'site/components/icons';

export default class DrawerVariantsIcon extends Component {
  @tracked isOpen = false;
  @tracked selectedVariant = 'sectioned';

  variants = ['sectioned', 'flat'];

  openDrawer = (variant) => {
    this.selectedVariant = variant;
    this.isOpen = true;
  };

  closeDrawer = () => {
    this.isOpen = false;
  };

  <template>
    <div class='flex gap-2'>
      {{#each this.variants as |variant|}}
        <Button @size='sm' @onPress={{fn this.openDrawer variant}}>
          {{variant}}
          with icon
        </Button>
      {{/each}}
    </div>

    <Drawer
      @isOpen={{this.isOpen}}
      @onClose={{this.closeDrawer}}
      @variant={{this.selectedVariant}}
      as |d|
    >
      <d.Header
        @title='{{this.selectedVariant}} with an icon'
        @description='The icon and text placement come from the block form.'
        as |h|
      >
        <h.Icon><SettingsIcon /></h.Icon>
        <h.Title />
        <h.Description />
      </d.Header>
      <d.Body>
        <p>Icon, title and description are placed by the block, unaffected by
          which variant is active.</p>
      </d.Body>
    </Drawer>
  </template>
}
```

### Header

`<d.Header>` accepts `@title` and `@description` directly, or a block yielding `h.Icon`,
`h.Title` and `h.Description` for when you need to place them yourself — a blockless
`<h.Title />` or `<h.Description />` falls back to `@title` / `@description`.

An icon tops out with the title when there is a description under it, and centers against
the title when there isn't.

```gts preview
import Component from '@glimmer/component';
import { tracked } from '@glimmer/tracking';
import { Drawer } from 'frontile';
import { Button } from 'frontile';

export default class DrawerHeaderArgs extends Component {
  @tracked isOpen = false;

  toggle = () => {
    this.isOpen = !this.isOpen;
  };

  <template>
    <Button @size='sm' @onPress={{this.toggle}}>
      Open Drawer
    </Button>

    <Drawer @isOpen={{this.isOpen}} @onClose={{this.toggle}} as |d|>
      <d.Header
        @title='Account settings'
        @description='Update your name, email and password.'
      />
      <d.Body>
        <p>The title and description above came from `@title` and
          `@description`, with no block needed.</p>
      </d.Body>
    </Drawer>
  </template>
}
```

```gts preview collapsible
import Component from '@glimmer/component';
import { tracked } from '@glimmer/tracking';
import { Drawer } from 'frontile';
import { Button } from 'frontile';
import { SettingsIcon } from 'site/components/icons';

export default class DrawerHeaderBlock extends Component {
  @tracked isOpen = false;

  toggle = () => {
    this.isOpen = !this.isOpen;
  };

  <template>
    <Button @size='sm' @onPress={{this.toggle}}>
      Open Drawer
    </Button>

    <Drawer @isOpen={{this.isOpen}} @onClose={{this.toggle}} as |d|>
      <d.Header
        @title='Account settings'
        @description='Update your name, email and password.'
        as |h|
      >
        <h.Icon><SettingsIcon /></h.Icon>
        <h.Title />
        <h.Description />
      </d.Header>
      <d.Body>
        <p>The title and description here are still the same `@title` and
          `@description`, only placed alongside an icon by the block.</p>
      </d.Body>
    </Drawer>
  </template>
}
```

### Header actions

Use the `:actions` named block to put controls beside the close button.

```gts preview collapsible
import Component from '@glimmer/component';
import { tracked } from '@glimmer/tracking';
import { Drawer, Button } from 'frontile';

export default class DrawerHeaderActions extends Component {
  @tracked isOpen = false;
  @tracked onlyStarred = false;

  toggle = () => {
    this.isOpen = !this.isOpen;
  };

  toggleStarred = () => {
    this.onlyStarred = !this.onlyStarred;
  };

  <template>
    <Button @size='sm' @onPress={{this.toggle}}>Open Drawer</Button>

    <Drawer @isOpen={{this.isOpen}} @onClose={{this.toggle}} as |d|>
      <d.Header @title='Filters' @description='Narrow the results below.'>
        <:actions>
          <Button @size='sm' @color='primary' @onPress={{this.toggleStarred}}>
            {{if this.onlyStarred 'Show all' 'Only starred'}}
          </Button>
        </:actions>
      </d.Header>
      <d.Body>
        <p>{{if
            this.onlyStarred
            'Showing starred results.'
            'Showing all results.'
          }}</p>
      </d.Body>
    </Drawer>
  </template>
}
```

Actions sit **in flow**, so a taller control makes the header band taller: a title-only
header is 72px on its own and grows to fit whatever you add. The close button does not
affect the band's height.

The header keeps a lane clear on its right for the close button, and drops it when
`@allowCloseButton={{false}}`.

Using `:actions` means your main header content moves into an explicit `:default` block:

```gjs
<d.Header as |h|>
  <:default>
    <h.Title>Filters</h.Title>
  </:default>
  <:actions>
    <Button @size="sm">Reset</Button>
  </:actions>
</d.Header>
```

### Banner under the header

`Header`, `Body` and `Footer` are yielded components, not fixed slots — anything you
render between them becomes a sibling in the drawer's column. The drawer applies no
padding of its own, so a full-bleed element placed there spans the panel edge to edge.

```gts preview collapsible
import Component from '@glimmer/component';
import { tracked } from '@glimmer/tracking';
import { Drawer, Button, Alert } from 'frontile';
import { SettingsIcon } from 'site/components/icons';

export default class DrawerWithBanner extends Component {
  @tracked isOpen = false;

  toggle = () => {
    this.isOpen = !this.isOpen;
  };

  <template>
    <Button @size='sm' @onPress={{this.toggle}}>Open Drawer</Button>

    <Drawer @isOpen={{this.isOpen}} @onClose={{this.toggle}} as |d|>
      <d.Header as |h|>
        <h.Icon><SettingsIcon /></h.Icon>
        <h.Title>Drawer title</h.Title>
        <h.Description>Supporting text</h.Description>
      </d.Header>

      <Alert
        @layout='banner'
        @variant='solid'
        @status='warning'
        @title='This is the banner text'
      />

      <d.Body>
        <p>The banner sits between the header and this content, spanning the
          full width of the drawer.</p>
      </d.Body>

      <d.Footer>
        <Button
          @size='sm'
          @color='primary'
          @variant='outline'
          @onPress={{this.toggle}}
        >
          Secondary
        </Button>
        <Button @size='sm' @color='primary'>Primary</Button>
      </d.Footer>
    </Drawer>
  </template>
}
```

### Placement

Drawers can slide in from any edge of the screen.

```gts preview collapsible
import Component from '@glimmer/component';
import { tracked } from '@glimmer/tracking';
import { fn } from '@ember/helper';
import { Drawer } from 'frontile';
import { Button } from 'frontile';

export default class DrawerPlacements extends Component {
  @tracked isOpen = false;
  @tracked selectedPlacement = 'right';

  placements = [
    {
      key: 'top',
      label: 'Top Drawer',
      title: 'Top Drawer',
      description: 'This drawer slides down from the top of the screen.'
    },
    {
      key: 'bottom',
      label: 'Bottom Drawer',
      title: 'Bottom Drawer',
      description: 'This drawer slides up from the bottom of the screen.'
    },
    {
      key: 'left',
      label: 'Left Drawer',
      title: 'Left Drawer',
      description: 'This drawer slides in from the left side of the screen.'
    },
    {
      key: 'right',
      label: 'Right Drawer',
      title: 'Right Drawer',
      description: 'This drawer slides in from the right side of the screen.'
    }
  ];

  openDrawer = (placement) => {
    this.selectedPlacement = placement;
    this.isOpen = true;
  };

  closeDrawer = () => {
    this.isOpen = false;
  };

  get currentPlacement() {
    return this.placements.find(
      (placement) => placement.key === this.selectedPlacement
    );
  }

  <template>
    <div class='demo-stack demo-stack--wide items-center'>
      <div class='grid grid-cols-2 gap-2'>
        {{#each this.placements as |placement|}}
          <Button @size='sm' @onPress={{fn this.openDrawer placement.key}}>
            {{placement.label}}
          </Button>
        {{/each}}
      </div>

      <Drawer
        @isOpen={{this.isOpen}}
        @onClose={{this.closeDrawer}}
        @placement={{this.selectedPlacement}}
        as |d|
      >
        <d.Header>{{this.currentPlacement.title}}</d.Header>
        <d.Body>
          <p>{{this.currentPlacement.description}}</p>
        </d.Body>
      </Drawer>
    </div>
  </template>
}
```

### Size

Control the drawer size with the `@size` argument.

```gts preview collapsible
import Component from '@glimmer/component';
import { tracked } from '@glimmer/tracking';
import { fn } from '@ember/helper';
import { Drawer } from 'frontile';
import { Button } from 'frontile';
import { on } from '@ember/modifier';

export default class DrawerSizes extends Component {
  @tracked isOpen = false;
  @tracked selectedSize = 'md';

  sizeOptions = [
    {
      key: 'xs',
      label: 'XS Size',
      title: 'Extra Small Drawer',
      description: 'This is an extra small drawer (xs).'
    },
    {
      key: 'sm',
      label: 'SM Size',
      title: 'Small Drawer',
      description: 'This is a small drawer (sm).'
    },
    {
      key: 'md',
      label: 'MD Size (Default)',
      title: 'Medium Drawer',
      description: 'This is a medium drawer (md). This is the default size.'
    },
    {
      key: 'lg',
      label: 'LG Size',
      title: 'Large Drawer',
      description: 'This is a large drawer (lg).'
    },
    {
      key: 'xl',
      label: 'XL Size',
      title: 'Extra Large Drawer',
      description: 'This is an extra large drawer (xl).'
    },
    {
      key: 'full',
      label: 'Full Size',
      title: 'Full Size Drawer',
      description: 'This drawer takes up the full width/height of the screen.'
    }
  ];

  openDrawer = (size) => {
    this.selectedSize = size;
    this.isOpen = true;
  };

  closeDrawer = () => {
    this.isOpen = false;
  };

  get currentSizeOption() {
    return this.sizeOptions.find((option) => option.key === this.selectedSize);
  }

  <template>
    <div class='demo-stack demo-stack--wide items-center'>
      <div class='grid grid-cols-3 gap-2'>
        {{#each this.sizeOptions as |option|}}
          <Button @size='sm' @onPress={{fn this.openDrawer option.key}}>
            {{option.label}}
          </Button>
        {{/each}}
      </div>

      <Drawer
        @isOpen={{this.isOpen}}
        @onClose={{this.closeDrawer}}
        @size={{this.selectedSize}}
        as |d|
      >
        <d.Header>{{this.currentSizeOption.title}}</d.Header>
        <d.Body>
          <p>{{this.currentSizeOption.description}}</p>
        </d.Body>
      </Drawer>
    </div>
  </template>
}
```

### Drag to close

`@allowDragToClose` is on by default for `top`/`bottom` and off by default for `left`/`right`.
Passing `true` opts any placement in; passing `false` turns it off for any placement. It has no
effect when `@allowClosing={{false}}` — a non-dismissible drawer stays non-dismissible either
way. Side placements default to off because a horizontal drag starting at a screen edge is
easy to miss; pass `@allowDragToClose={{true}}` to enable it there too.
The handle is a real button (labelled "Close drawer"), so keyboard and assistive-technology
users can close the drawer by activating it, without performing a gesture at all — and it
closes on click as well as on drag for everyone else.

A press on the body itself (not just the handle) can also dismiss the drawer, once the body's
own scroll position is already at the edge the drag pulls away from — so a drag toward the
handle's side dismisses, while scrolling through a longer body still scrolls normally instead
of being hijacked. This distinction is decided a few pixels into the gesture, not at the very
first touch, so tapping or starting to scroll never has a false start.

```gts preview collapsible
import Component from '@glimmer/component';
import { tracked } from '@glimmer/tracking';
import { fn } from '@ember/helper';
import { Drawer } from 'frontile';
import { Button } from 'frontile';

export default class DrawerDragBottom extends Component {
  @tracked isOpen = false;
  @tracked selectedVariant = 'sectioned';

  variants = ['sectioned', 'flat'];

  openDrawer = (variant) => {
    this.selectedVariant = variant;
    this.isOpen = true;
  };

  closeDrawer = () => {
    this.isOpen = false;
  };

  <template>
    <div class='flex gap-2'>
      {{#each this.variants as |variant|}}
        <Button @size='sm' @onPress={{fn this.openDrawer variant}}>
          Open Bottom Drawer ({{variant}})
        </Button>
      {{/each}}
    </div>

    <Drawer
      @isOpen={{this.isOpen}}
      @onClose={{this.closeDrawer}}
      @placement='bottom'
      @variant={{this.selectedVariant}}
      as |d|
    >
      <d.Header @title='Drag me down' @description='Or use the close button.' />
      <d.Body>
        <p>Drag the handle at the top of this drawer down to dismiss it, or
          release early to have it spring back. The handle bar looks the same in
          `default` and `ghost`.</p>
      </d.Body>
    </Drawer>
  </template>
}
```

```gts preview collapsible
import Component from '@glimmer/component';
import { tracked } from '@glimmer/tracking';
import { Drawer } from 'frontile';
import { Button } from 'frontile';

export default class DrawerDragRight extends Component {
  @tracked isOpen = false;

  toggle = () => {
    this.isOpen = !this.isOpen;
  };

  <template>
    <Button @size='sm' @onPress={{this.toggle}}>
      Open Right Drawer
    </Button>

    <Drawer
      @isOpen={{this.isOpen}}
      @onClose={{this.toggle}}
      @placement='right'
      @allowDragToClose={{true}}
      as |d|
    >
      <d.Header
        @title='Opted in'
        @description='Right drawers need @allowDragToClose to get the handle.'
      />
      <d.Body>
        <p>Drag the handle on the left edge toward the left to dismiss.</p>
      </d.Body>
    </Drawer>
  </template>
}
```

### Different Backdrop Types

Control the appearance of the backdrop behind the drawer.

```gts preview collapsible
import Component from '@glimmer/component';
import { tracked } from '@glimmer/tracking';
import { fn } from '@ember/helper';
import { Drawer } from 'frontile';
import { Button } from 'frontile';

export default class DrawerBackdrops extends Component {
  @tracked isOpen = false;
  @tracked selectedBackdrop = 'faded';

  backdropOptions = [
    {
      key: 'faded',
      label: 'Faded Backdrop',
      title: 'Faded Backdrop',
      description: 'Standard semi-transparent backdrop (default).'
    },
    {
      key: 'blur',
      label: 'Blurred Backdrop',
      title: 'Blurred Backdrop',
      description: 'Backdrop with blur effect behind the drawer.'
    },
    {
      key: 'none',
      label: 'No Backdrop',
      title: 'No Backdrop',
      description: 'Drawer without any backdrop overlay.'
    }
  ];

  openDrawer = (backdrop) => {
    this.selectedBackdrop = backdrop;
    this.isOpen = true;
  };

  closeDrawer = () => {
    this.isOpen = false;
  };

  get currentBackdropOption() {
    return this.backdropOptions.find(
      (option) => option.key === this.selectedBackdrop
    );
  }

  <template>
    <div class='demo-stack demo-stack--wide items-center'>
      <div class='grid grid-cols-2 gap-2'>
        {{#each this.backdropOptions as |option|}}
          <Button @size='sm' @onPress={{fn this.openDrawer option.key}}>
            {{option.label}}
          </Button>
        {{/each}}
      </div>

      <Drawer
        @isOpen={{this.isOpen}}
        @onClose={{this.closeDrawer}}
        @backdrop={{this.selectedBackdrop}}
        @placement='right'
        @size='md'
        as |d|
      >
        <d.Header>{{this.currentBackdropOption.title}}</d.Header>
        <d.Body>
          <p>{{this.currentBackdropOption.description}}</p>
          <p class='mt-2 text-sm text-neutral-soft'>Notice how the backdrop
            behind this drawer changes based on the selected type.</p>
        </d.Body>
        <d.Footer>
          <Button @size='sm' @onPress={{this.closeDrawer}}>Close</Button>
        </d.Footer>
      </Drawer>
    </div>
  </template>
}
```

### Close Button Control

Control the visibility and behavior of the close button. When you render the
yielded `d.CloseButton` yourself (the "Custom Close Button" example below),
add `data-part="close-button"` to it explicitly — Drawer cannot inject that
attribute into markup you write in your own template, so it is on you to
carry it forward for anatomy consumers styling or querying by `data-part`.

```gts preview collapsible
import Component from '@glimmer/component';
import { tracked } from '@glimmer/tracking';
import { Drawer } from 'frontile';
import { Button } from 'frontile';

export default class DrawerCloseButton extends Component {
  @tracked normalOpen = false;
  @tracked noCloseButtonOpen = false;
  @tracked customCloseOpen = false;

  toggleNormal = () => {
    this.normalOpen = !this.normalOpen;
  };

  toggleNoCloseButton = () => {
    this.noCloseButtonOpen = !this.noCloseButtonOpen;
  };

  toggleCustomClose = () => {
    this.customCloseOpen = !this.customCloseOpen;
  };

  <template>
    <div class='demo-stack demo-stack--wide items-center'>
      <div class='flex gap-2'>
        <Button @size='sm' @onPress={{this.toggleNormal}}>
          Normal Close Button
        </Button>
        <Button @size='sm' @onPress={{this.toggleNoCloseButton}}>
          No Close Button
        </Button>
        <Button @size='sm' @onPress={{this.toggleCustomClose}}>
          Custom Close Button
        </Button>
      </div>

      <Drawer @isOpen={{this.normalOpen}} @onClose={{this.toggleNormal}} as |d|>
        <d.Header>Normal Close Button</d.Header>
        <d.Body>
          <p>This drawer has the default close button in the top right corner.</p>
        </d.Body>
      </Drawer>

      <Drawer
        @isOpen={{this.noCloseButtonOpen}}
        @onClose={{this.toggleNoCloseButton}}
        @allowCloseButton={{false}}
        as |d|
      >
        <d.Header>No Close Button</d.Header>
        <d.Body>
          <p>This drawer has no close button. You can still close it by clicking
            the backdrop or pressing Escape.</p>
        </d.Body>
        <d.Footer>
          <Button @size='sm' @onPress={{this.toggleNoCloseButton}}>
            Close from Footer
          </Button>
        </d.Footer>
      </Drawer>

      <Drawer
        @isOpen={{this.customCloseOpen}}
        @onClose={{this.toggleCustomClose}}
        @allowCloseButton={{false}}
        as |d|
      >
        <d.Header>
          Custom Close Button
          <d.CloseButton data-part='close-button' />
        </d.Header>
        <d.Body>
          <p>This drawer uses a custom close button placed in the header using
            the yielded CloseButton component.</p>
        </d.Body>
      </Drawer>
    </div>
  </template>
}
```

### Non-Dismissible Drawer

A drawer that cannot be closed by normal means.

```gts preview collapsible
import Component from '@glimmer/component';
import { tracked } from '@glimmer/tracking';
import { Drawer } from 'frontile';
import { Button } from 'frontile';
import { ProgressBar } from 'frontile';

export default class NonDismissibleDrawer extends Component {
  @tracked isOpen = false;
  @tracked progress = 0;
  @tracked isProcessing = false;

  toggle = () => {
    this.isOpen = !this.isOpen;
  };

  startProcess = () => {
    this.isProcessing = true;
    this.progress = 0;

    const interval = setInterval(() => {
      this.progress += 10;
      if (this.progress >= 100) {
        clearInterval(interval);
        this.isProcessing = false;
      }
    }, 500);
  };

  forceClose = () => {
    this.isProcessing = false;
    this.progress = 0;
    this.toggle();
  };

  get allowClosing() {
    return !this.isProcessing;
  }

  <template>
    <div class='demo-stack demo-stack--wide items-center'>
      <Button @size='sm' @onPress={{this.toggle}}>
        Open Processing Drawer
      </Button>

      <Drawer
        @isOpen={{this.isOpen}}
        @onClose={{this.toggle}}
        @allowClosing={{this.allowClosing}}
        as |d|
      >
        <d.Header>
          Processing Data
        </d.Header>
        <d.Body>
          <div class='space-y-4'>
            <p>This drawer cannot be closed while processing is in progress.</p>

            {{#if this.isProcessing}}
              <ProgressBar
                @progress={{this.progress}}
                @label='Progress: {{this.progress}}%'
                @color='success'
              />
            {{else}}
              <p class='text-success'>Ready to process data.</p>
            {{/if}}
          </div>
        </d.Body>
        <d.Footer @class='flex gap-2'>
          {{#if this.isProcessing}}
            <Button @size='sm' disabled={{true}}>
              Processing...
            </Button>
            <Button @size='sm' @color='danger' @onPress={{this.forceClose}}>
              Force Close
            </Button>
          {{else}}
            <Button @size='sm' @onPress={{this.toggle}}>
              Cancel
            </Button>
            <Button @size='sm' @color='primary' @onPress={{this.startProcess}}>
              Start Processing
            </Button>
          {{/if}}
        </d.Footer>
      </Drawer>
    </div>
  </template>
}
```

### Drawers that start open

A drawer whose `@isOpen` is already true the first time it renders — deep-linked open, or
restored by a page refresh — waits for the browser's first paint before appearing, so its
animation plays against the page rather than starting before anything has been drawn. Pass
`@animateOnMount={{false}}` when an already-open drawer should simply be there, with no
reveal.

## Anatomy

Drawer yields the pieces you assemble it from:

| Yielded         | Purpose                                                          |
| --------------- | ---------------------------------------------------------------- |
| `d.Header`      | Heading region; applies the id that `aria-labelledby` points at. |
| `d.Body`        | Main content area.                                               |
| `d.Footer`      | Action row.                                                      |
| `d.CloseButton` | Styled close button wired to `@onClose`.                         |
| `d.headerId`    | The id Header uses, for labelling your own heading instead.      |

The default close button is rendered inside `<d.Header>` when one is present. A drawer with
no Header falls back to a standalone close button in its top-right corner.

## Patterns

### Form in Drawer

A practical example showing a form inside a drawer.

```gts preview collapsible
import Component from '@glimmer/component';
import { tracked } from '@glimmer/tracking';
import { Drawer } from 'frontile';
import { Button } from 'frontile';
import { Input, Textarea } from 'frontile';
import { on } from '@ember/modifier';

export default class DrawerForm extends Component {
  @tracked isOpen = false;
  @tracked name = '';
  @tracked email = '';
  @tracked message = '';

  toggle = () => {
    this.isOpen = !this.isOpen;
  };

  handleSubmit = (event) => {
    event.preventDefault();
    // Handle form submission
    console.log('Form submitted:', {
      name: this.name,
      email: this.email,
      message: this.message
    });
    this.toggle();
  };

  updateName = (value) => {
    this.name = value;
  };

  updateEmail = (value) => {
    this.email = value;
  };

  updateMessage = (value) => {
    this.message = value;
  };

  <template>
    <div class='demo-stack demo-stack--wide items-center'>
      <Button @size='sm' @onPress={{this.toggle}}>
        Open Contact Form
      </Button>

      <Drawer
        @isOpen={{this.isOpen}}
        @onClose={{this.toggle}}
        @size='lg'
        as |d|
      >
        <d.Header>
          Contact Us
        </d.Header>
        <d.Body>
          <form {{on 'submit' this.handleSubmit}} class='space-y-4'>
            <Input
              @label='Name'
              @value={{this.name}}
              @onInput={{this.updateName}}
              required
            />
            <Input
              @label='Email'
              @type='email'
              @value={{this.email}}
              @onInput={{this.updateEmail}}
              required
            />
            <Textarea
              @label='Message'
              @value={{this.message}}
              @onInput={{this.updateMessage}}
              @rows={{5}}
              required
            />
          </form>
        </d.Body>
        <d.Footer @class='flex gap-2'>
          <Button @size='sm' @onPress={{this.toggle}}>
            Cancel
          </Button>
          <Button @size='sm' @color='primary' @onPress={{this.handleSubmit}}>
            Send Message
          </Button>
        </d.Footer>
      </Drawer>
    </div>
  </template>
}
```

### Navigation Drawer

A drawer used for navigation with a list of links.

```gts preview collapsible
import Component from '@glimmer/component';
import { tracked } from '@glimmer/tracking';
import { fn } from '@ember/helper';
import { Drawer } from 'frontile';
import { Button } from 'frontile';
import { on } from '@ember/modifier';
import { Divider } from 'frontile';

export default class NavigationDrawer extends Component {
  @tracked isOpen = false;

  toggle = () => {
    this.isOpen = !this.isOpen;
  };

  navigateTo = (page) => {
    console.log('Navigate to:', page);
    this.toggle();
  };

  <template>
    <div class='demo-stack demo-stack--wide items-center'>
      <Button @size='sm' @onPress={{this.toggle}}>
        Open Navigation
      </Button>

      <Drawer
        @isOpen={{this.isOpen}}
        @onClose={{this.toggle}}
        @placement='left'
        @size='sm'
        as |d|
      >
        <d.Header>
          App Navigation
        </d.Header>
        <d.Body>
          <nav class='space-y-2'>
            <button
              {{on 'click' (fn this.navigateTo 'dashboard')}}
              class='w-full text-left px-3 py-2 rounded hover:bg-neutral-subtle transition-colors'
            >
              🏠 Dashboard
            </button>
            <button
              {{on 'click' (fn this.navigateTo 'profile')}}
              class='w-full text-left px-3 py-2 rounded hover:bg-neutral-subtle transition-colors'
            >
              👤 Profile
            </button>
            <button
              {{on 'click' (fn this.navigateTo 'settings')}}
              class='w-full text-left px-3 py-2 rounded hover:bg-neutral-subtle transition-colors'
            >
              ⚙️ Settings
            </button>
            <button
              {{on 'click' (fn this.navigateTo 'help')}}
              class='w-full text-left px-3 py-2 rounded hover:bg-neutral-subtle transition-colors'
            >
              ❓ Help
            </button>
            <Divider />
            <button
              {{on 'click' (fn this.navigateTo 'logout')}}
              class='w-full text-left px-3 py-2 rounded hover:bg-danger-subtle text-danger transition-colors'
            >
              🚪 Logout
            </button>
          </nav>
        </d.Body>
      </Drawer>
    </div>
  </template>
}
```

## Accessibility

The drawer renders as `role="dialog"` with `tabindex="0"` and `aria-modal="true"`, labelled
by `aria-labelledby` pointing at the id yielded as `headerId` — which `<d.Header>` applies.
`aria-labelledby` is only rendered while a `Header` is actually on the page, so a drawer
without one has no dangling reference — but it also has **no accessible name**. Give it one:
render a `Header`, or pass your own label through attributes.

```gts
<Drawer @isOpen={{this.isOpen}} @onClose={{this.close}} aria-label="Filters" as |d|>
  <d.Body>Filter controls</d.Body>
</Drawer>
```

If you label the drawer with a heading of your own rather than `<d.Header>`, pass
`aria-labelledby` yourself — putting the yielded `headerId` on a heading does not label the
dialog by itself, because nothing points at it:

```gts
<Drawer @isOpen={{this.isOpen}} @onClose={{this.close}} aria-labelledby={{this.titleId}} as |d|>
  <h2 id={{this.titleId}}>My Title</h2>
  <d.Body>My Content</d.Body>
</Drawer>
```

A drawer with no accessible name — no `Header`, `aria-label`, or `aria-labelledby` — is
invalid. Frontile reports this during development with the warning id
`frontile.drawer.missing-accessible-name` so it can be corrected before release.

`aria-modal="true"` is dropped when `@disableFocusTrap={{true}}`: with the trap off the page
behind really is reachable, and claiming otherwise would mislead screen reader users. Note
that the drawer still auto-focuses itself in this case, unless `@preventAutoFocus={{true}}`
is also passed — see [Overlay](./overlay.md#accessibility).

Behavior inherited from [Overlay](./overlay.md):

| Behavior       | Detail                                                 |
| -------------- | ------------------------------------------------------ |
| Focus on open  | Moves into the drawer, and a focus trap keeps it there |
| Focus on close | Returns to whatever was focused before opening         |
| `Escape`       | Closes, unless `@closeOnEscapeKey={{false}}`           |
| Backdrop click | Closes, unless `@closeOnOutsideClick={{false}}`        |
| Body scroll    | Blocked while open (reference counted for nesting)     |

The drawer needs at least one focusable element inside it, or the focus trap has nowhere to
put focus. `@allowClosing={{false}}` disables Escape, backdrop click and the close button at
once, leaving a keyboard user no way out — the Non-Dismissible example above pairs it with
explicit footer actions for that reason.

Under `prefers-reduced-motion: reduce`, the drawer fades in place instead of sliding.

Note that `@placement` is purely visual: a drawer sliding in from the left is announced no
differently from one on the right, and nothing about the placement reaches assistive
technology. Frontile also does not set `aria-describedby`.

## API

### Drawer

**Element:** `HTMLDivElement`

**Arguments**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `isOpen *` | `boolean` | - | Whether it is open or not |
| `allowCloseButton` | `boolean` | `true` | If set to false, the close button will not be displayed. |
| `allowClosing` | `boolean` | `true` | If set to false, the close button will not be displayed, closeOnOutsideClick will be set to false, and closeOnEscapeKey will also be set to false. |
| `allowDragToClose` | `boolean` | `true for `top`/`bottom`, false for `left`/`right`` | Enables the drag-to-close gesture and its grab handle. Omit it and the gesture is on for top and bottom placements and off for left and right. Pass true to opt a side drawer in, or false to turn it off entirely. Always off when allowClosing is false. |
| `animateOnMount` | `boolean` | `true` | Whether an overlay that is already open the first time it renders -- deep-linked open, or restored by a page refresh -- animates in. When true (the default) the overlay waits for the browser's first paint before mounting, so the animation plays against a page the user has already seen. Set it to false for an already-open overlay that should simply be there, with no reveal. An overlay opened later by interaction animates either way, and so does closing. |
| `backdrop` | `'faded' \| 'none' \| 'transparent' \| 'blur'` | - | How the area behind the overlay is rendered: none omits the backdrop entirely, transparent keeps it clickable but invisible, faded dims the page, and blur blurs it. |
| `backdropTransition` | `Object` | - | Transition classes for the backdrop, overriding the defaults used when it fades in and out. |
| `classes` | `SlotsToClasses<'icon' \| 'base' \| 'description' \| 'title' \| 'closeButton' \| 'headerCloseButton' \| 'header' \| 'headerContent' \| 'headerActions' \| 'body' \| 'footer' \| 'dragHandle' \| 'dragHandleBar'>` | - | Class names for each slot of the component, merged with the theme's. |
| `closeButtonSize` | `'sm' \| 'md' \| 'lg' \| 'xs' \| 'xl'` | `'lg'` | The Close Button size. |
| `closeOnEscapeKey` | `boolean` | `true` | Whether to close when the escape key is pressed |
| `closeOnOutsideClick` | `boolean` | `true` | Whether to close when the area outside (the backdrop) is clicked |
| `didClose` | `() => void` | - | A function that will be called when closing is finished executing, this includes waiting for animations/transitions to finish. |
| `disableFocusTrap` | `boolean` | `false` | Whether the focus trap is disabled or not |
| `disableTransitions` | `boolean` | `false` | Disable css transitions |
| `focusTrapOptions` | `any` | `{ clickOutsideDeactivates: true, allowOutsideClick: true }` | Focus trap options |
| `onClose` | `() => void` | - | A function that will be called when closed |
| `onOpen` | `() => void` | - | A function that will be called when opened |
| `placement` | `'top' \| 'right' \| 'bottom' \| 'left'` | `'right'` | The Drawer can appear from any side of the screen. The 'placement' option allows to choose where it appears from. |
| `preventAutoFocus` | `boolean` | `false` | When focusTrap is disabled, by default Oberlay will be auto focused. This option prevents that. |
| `renderInPlace` | `boolean` | `false` | Whether to render in place or in the specified/default destination |
| `size` | `'sm' \| 'md' \| 'lg' \| 'xs' \| 'xl' \| 'full'` | `'md'` | The Drawer size. |
| `target` | `string \| Element` | - | The target where to render the portal. There are 3 options: 1) Element object, 2) element id, 3) portal target name. For element id, string must be prefixed with #. If no value is passed in, we will render to the closest unnamed portal target, parent portal or document.body. |
| `transition` | `Object` | `{name: 'overlay-transition--slide-from-[placement]'}` | The transition to be used in the Drawer. |
| `transitionDuration` | `number` | `200` | Duration of the animation |
| `variant` | `'sectioned' \| 'flat'` | `'sectioned'` | The Drawer visual variant. sectioned gives the drawer a black header band, a distinct body surface and a solid footer. flat keeps every region on the modal surface. |

**Blocks**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `default *` | `[{ CloseButton: CloseButton (onPress, class bound); Header: DrawerHeader (labelledById, classFromParent, registerSelf, iconClass, titleClass, descriptionClass, contentClass, actionsClass, closeButton bound); Body: DrawerBody (classFromParent bound); Footer: DrawerFooter (classFromParent bound); headerId: string; }]` | - |  |

---

# Modal

Source: /docs/components/overlays/modal.md

# Modal

The Modal component is a centered dialog that appears over the main content. It's built on top of the Overlay component and includes all its accessibility features, plus modal-specific functionality like centered positioning and size variants.

## Import

```js
import { Modal } from 'frontile';
```

## Usage

### Basic Modal

A simple modal with header, body, and footer sections.

```gts preview collapsible
import Component from '@glimmer/component';
import { tracked } from '@glimmer/tracking';
import { Modal } from 'frontile';
import { Button } from 'frontile';

export default class BasicModal extends Component {
  @tracked isOpen = false;

  toggle = () => {
    this.isOpen = !this.isOpen;
  };

  <template>
    <div class='demo-stack demo-stack--wide items-center'>
      <Button @onPress={{this.toggle}}>
        Open Modal
      </Button>

      <Modal @isOpen={{this.isOpen}} @onClose={{this.toggle}} as |m|>
        <m.Header>
          Basic Modal
        </m.Header>
        <m.Body>
          <p class='mb-4'>This is the main content of the modal. Modals are
            great for displaying important information, forms, or confirmation
            dialogs.</p>
          <p>The modal appears centered on the screen with a backdrop that can
            be clicked to close it.</p>
        </m.Body>
        <m.Footer @class='flex gap-2'>
          <Button @onPress={{this.toggle}}>
            Cancel
          </Button>
          <Button @color='primary'>
            Confirm
          </Button>
        </m.Footer>
      </Modal>
    </div>
  </template>
}
```

### Different Sizes

Control the modal size with the `@size` argument.

```gts preview collapsible
import Component from '@glimmer/component';
import { tracked } from '@glimmer/tracking';
import { fn } from '@ember/helper';
import { Modal } from 'frontile';
import { Button } from 'frontile';

export default class ModalSizes extends Component {
  @tracked isOpen = false;
  @tracked selectedSize = 'lg';

  sizeOptions = [
    {
      key: 'xs',
      label: 'XS Size',
      title: 'Extra Small Modal',
      description:
        'This is an extra small modal (xs). Perfect for simple confirmations.'
    },
    {
      key: 'sm',
      label: 'SM Size',
      title: 'Small Modal',
      description:
        'This is a small modal (sm). Good for short forms or notifications.'
    },
    {
      key: 'md',
      label: 'MD Size',
      title: 'Medium Modal',
      description: 'This is a medium modal (md). Suitable for moderate content.'
    },
    {
      key: 'lg',
      label: 'LG Size (Default)',
      title: 'Large Modal',
      description:
        'This is a large modal (lg). This is the default size. Great for detailed forms or content.'
    },
    {
      key: 'xl',
      label: 'XL Size',
      title: 'Extra Large Modal',
      description:
        'This is an extra large modal (xl). Perfect for complex forms or detailed content.'
    },
    {
      key: 'full',
      label: 'Full Size',
      title: 'Full Size Modal',
      description:
        'This modal takes up the full screen. Use for complex interfaces or when you need maximum space.'
    }
  ];

  openModal = (size) => {
    this.selectedSize = size;
    this.isOpen = true;
  };

  closeModal = () => {
    this.isOpen = false;
  };

  get currentSizeOption() {
    return this.sizeOptions.find((option) => option.key === this.selectedSize);
  }

  <template>
    <div class='demo-stack demo-stack--wide items-center'>
      <div class='grid grid-cols-3 gap-2'>
        {{#each this.sizeOptions as |option|}}
          <Button @onPress={{fn this.openModal option.key}}>
            {{option.label}}
          </Button>
        {{/each}}
      </div>

      <Modal
        @isOpen={{this.isOpen}}
        @onClose={{this.closeModal}}
        @size={{this.selectedSize}}
        as |m|
      >
        <m.Header>{{this.currentSizeOption.title}}</m.Header>
        <m.Body>
          <p>{{this.currentSizeOption.description}}</p>
        </m.Body>
        <m.Footer>
          <Button @onPress={{this.closeModal}}>Close</Button>
        </m.Footer>
      </Modal>
    </div>
  </template>
}
```

### Centered vs Standard Positioning

By default the modal sits toward the top of the screen. `@isCentered={{true}}` centers it
vertically.

```gts preview collapsible
import Component from '@glimmer/component';
import { tracked } from '@glimmer/tracking';
import { Modal } from 'frontile';
import { Button } from 'frontile';

export default class ModalPositioning extends Component {
  @tracked standardOpen = false;
  @tracked centeredOpen = false;

  toggleStandard = () => {
    this.standardOpen = !this.standardOpen;
  };

  toggleCentered = () => {
    this.centeredOpen = !this.centeredOpen;
  };

  <template>
    <div class='demo-stack demo-stack--wide items-center'>
      <div class='flex gap-2'>
        <Button @onPress={{this.toggleStandard}}>
          Standard Position
        </Button>
        <Button @onPress={{this.toggleCentered}}>
          Centered Position
        </Button>
      </div>

      <Modal
        @isOpen={{this.standardOpen}}
        @onClose={{this.toggleStandard}}
        as |m|
      >
        <m.Header>Standard Positioning</m.Header>
        <m.Body>
          <p>This modal uses standard positioning (not vertically centered). It
            appears towards the top of the screen.</p>
        </m.Body>
        <m.Footer>
          <Button @onPress={{this.toggleStandard}}>Close</Button>
        </m.Footer>
      </Modal>

      <Modal
        @isOpen={{this.centeredOpen}}
        @onClose={{this.toggleCentered}}
        @isCentered={{true}}
        as |m|
      >
        <m.Header>Centered Positioning</m.Header>
        <m.Body>
          <p>This modal is vertically centered on the screen using @isCentered={{true}}.</p>
        </m.Body>
        <m.Footer>
          <Button @onPress={{this.toggleCentered}}>Close</Button>
        </m.Footer>
      </Modal>
    </div>
  </template>
}
```

### Different Backdrop Types

Control the appearance of the backdrop behind the modal.

```gts preview collapsible
import Component from '@glimmer/component';
import { tracked } from '@glimmer/tracking';
import { fn } from '@ember/helper';
import { Modal } from 'frontile';
import { Button } from 'frontile';

export default class ModalBackdrops extends Component {
  @tracked isOpen = false;
  @tracked selectedBackdrop = 'faded';

  backdropOptions = [
    {
      key: 'faded',
      label: 'Faded Backdrop',
      title: 'Faded Backdrop',
      description: 'Standard semi-transparent backdrop (default).'
    },
    {
      key: 'blur',
      label: 'Blurred Backdrop',
      title: 'Blurred Backdrop',
      description: 'Backdrop with blur effect behind the modal.'
    },
    {
      key: 'none',
      label: 'No Backdrop',
      title: 'No Backdrop',
      description: 'Modal without any backdrop overlay.'
    }
  ];

  openModal = (backdrop) => {
    this.selectedBackdrop = backdrop;
    this.isOpen = true;
  };

  closeModal = () => {
    this.isOpen = false;
  };

  get currentBackdropOption() {
    return this.backdropOptions.find(
      (option) => option.key === this.selectedBackdrop
    );
  }

  <template>
    <div class='demo-stack demo-stack--wide items-center'>
      <div class='grid grid-cols-2 gap-2'>
        {{#each this.backdropOptions as |option|}}
          <Button @onPress={{fn this.openModal option.key}}>
            {{option.label}}
          </Button>
        {{/each}}
      </div>

      <Modal
        @isOpen={{this.isOpen}}
        @onClose={{this.closeModal}}
        @backdrop={{this.selectedBackdrop}}
        @isCentered={{true}}
        as |m|
      >
        <m.Header>{{this.currentBackdropOption.title}}</m.Header>
        <m.Body>
          <p>{{this.currentBackdropOption.description}}</p>
          <p class='mt-2 text-sm text-neutral-soft'>Notice how the backdrop
            behind this modal changes based on the selected type.</p>
        </m.Body>
        <m.Footer>
          <Button @onPress={{this.closeModal}}>Close</Button>
        </m.Footer>
      </Modal>
    </div>
  </template>
}
```

### Confirmation Dialog

A practical example showing a confirmation dialog pattern.

```gts preview collapsible
import Component from '@glimmer/component';
import { tracked } from '@glimmer/tracking';
import { Modal, Button, Spinner } from 'frontile';

export default class ConfirmationDialog extends Component {
  @tracked isOpen = false;
  @tracked isDeleting = false;
  @tracked result = '';

  openDialog = () => {
    this.isOpen = true;
    this.result = '';
  };

  cancel = () => {
    this.isOpen = false;
    this.result = 'Action cancelled';
  };

  confirm = async () => {
    this.isDeleting = true;

    // Simulate async operation
    await new Promise((resolve) => setTimeout(resolve, 2000));

    this.isDeleting = false;
    this.isOpen = false;
    this.result = 'Item deleted successfully';
  };

  get allowClosing() {
    return !this.isDeleting;
  }

  <template>
    <div class='demo-stack demo-stack--wide items-center'>
      <Button @color='danger' @onPress={{this.openDialog}}>
        Delete Item
      </Button>

      {{#if this.result}}
        <div class='p-3 rounded border bg-neutral-subtle'>
          {{this.result}}
        </div>
      {{/if}}

      <Modal
        @isOpen={{this.isOpen}}
        @onClose={{this.cancel}}
        @size='sm'
        @isCentered={{true}}
        @allowClosing={{this.allowClosing}}
        as |m|
      >
        <m.Header>
          Confirm Deletion
        </m.Header>
        <m.Body>
          <div class='space-y-3'>
            <p>Are you sure you want to delete this item?</p>
            <p class='text-sm text-neutral'>This action cannot be undone.</p>

            {{#if this.isDeleting}}
              <div class='flex items-center space-x-2'>
                <Spinner @size='xs' @color='danger' />
                <span class='text-sm'>Deleting...</span>
              </div>
            {{/if}}
          </div>
        </m.Body>
        <m.Footer @class='flex gap-4 [&>*]:flex-1'>
          <Button @onPress={{this.cancel}} disabled={{this.isDeleting}}>
            Cancel
          </Button>
          <Button
            @color='danger'
            @onPress={{this.confirm}}
            disabled={{this.isDeleting}}
          >
            {{#if this.isDeleting}}
              Deleting...
            {{else}}
              Delete
            {{/if}}
          </Button>
        </m.Footer>
      </Modal>
    </div>
  </template>
}
```

### Form Modal

A modal containing a complete form with validation.

```gts preview collapsible
import Component from '@glimmer/component';
import { tracked } from '@glimmer/tracking';
import { Modal } from 'frontile';
import { Button } from 'frontile';
import { Input, Textarea, Select } from 'frontile';
import { on } from '@ember/modifier';

export default class FormModal extends Component {
  @tracked isOpen = false;
  @tracked name = '';
  @tracked email = '';
  @tracked category = null;
  @tracked message = '';
  @tracked isSubmitting = false;

  categories = [
    { key: 'support', label: 'Support' },
    { key: 'sales', label: 'Sales' },
    { key: 'feedback', label: 'Feedback' },
    { key: 'other', label: 'Other' }
  ];

  toggle = () => {
    this.isOpen = !this.isOpen;
  };

  updateName = (value) => {
    this.name = value;
  };

  updateEmail = (value) => {
    this.email = value;
  };

  updateCategory = (key) => {
    this.category = key;
  };

  updateMessage = (value) => {
    this.message = value;
  };

  handleSubmit = async (event) => {
    event.preventDefault();

    if (!this.name || !this.email || !this.message) {
      return;
    }

    this.isSubmitting = true;

    // Simulate API call
    await new Promise((resolve) => setTimeout(resolve, 2000));

    console.log('Form submitted:', {
      name: this.name,
      email: this.email,
      category: this.category,
      message: this.message
    });

    this.isSubmitting = false;
    this.resetForm();
    this.toggle();
  };

  resetForm = () => {
    this.name = '';
    this.email = '';
    this.category = null;
    this.message = '';
  };

  get isValid() {
    return this.name && this.email && this.message;
  }

  get isSubmitDisabled() {
    return !this.isValid || this.isSubmitting;
  }

  get allowClosing() {
    return !this.isSubmitting;
  }

  <template>
    <div class='demo-stack demo-stack--wide items-center'>
      <Button @onPress={{this.toggle}}>
        Open Contact Form
      </Button>

      <Modal
        @isOpen={{this.isOpen}}
        @onClose={{this.toggle}}
        @size='lg'
        @allowClosing={{this.allowClosing}}
        as |m|
      >
        <m.Header>
          Contact Us
        </m.Header>
        <m.Body>
          <form {{on 'submit' this.handleSubmit}} class='space-y-4'>
            <Input
              @label='Name'
              @value={{this.name}}
              @onInput={{this.updateName}}
              required
              disabled={{this.isSubmitting}}
            />

            <Input
              @label='Email'
              @type='email'
              @value={{this.email}}
              @onInput={{this.updateEmail}}
              required
              disabled={{this.isSubmitting}}
            />

            <Select
              @label='Category'
              @items={{this.categories}}
              @selectedKey={{this.category}}
              @onSelectionChange={{this.updateCategory}}
              @placeholder='Select a category'
              disabled={{this.isSubmitting}}
            />

            <Textarea
              @label='Message'
              @value={{this.message}}
              @onInput={{this.updateMessage}}
              @rows={{4}}
              required
              disabled={{this.isSubmitting}}
            />
          </form>
        </m.Body>
        <m.Footer @class='flex gap-2'>
          <Button @onPress={{this.toggle}} disabled={{this.isSubmitting}}>
            Cancel
          </Button>
          <Button
            @color='primary'
            @onPress={{this.handleSubmit}}
            disabled={{this.isSubmitDisabled}}
          >
            {{#if this.isSubmitting}}
              Sending...
            {{else}}
              Send Message
            {{/if}}
          </Button>
        </m.Footer>
      </Modal>
    </div>
  </template>
}
```

### Close Button Control

Control the visibility and behavior of the close button. When you render the
yielded `m.CloseButton` yourself (the "Custom Close Button" example below),
add `data-part="close-button"` to it explicitly — Modal cannot inject that
attribute into markup you write in your own template, so it is on you to
carry it forward for anatomy consumers styling or querying by `data-part`.

```gts preview collapsible
import Component from '@glimmer/component';
import { tracked } from '@glimmer/tracking';
import { Modal } from 'frontile';
import { Button } from 'frontile';

export default class ModalCloseButton extends Component {
  @tracked normalOpen = false;
  @tracked noCloseButtonOpen = false;
  @tracked customCloseOpen = false;

  toggleNormal = () => {
    this.normalOpen = !this.normalOpen;
  };

  toggleNoCloseButton = () => {
    this.noCloseButtonOpen = !this.noCloseButtonOpen;
  };

  toggleCustomClose = () => {
    this.customCloseOpen = !this.customCloseOpen;
  };

  <template>
    <div class='demo-stack demo-stack--wide items-center'>
      <div class='flex gap-2'>
        <Button @onPress={{this.toggleNormal}}>
          Normal Close Button
        </Button>
        <Button @onPress={{this.toggleNoCloseButton}}>
          No Close Button
        </Button>
        <Button @onPress={{this.toggleCustomClose}}>
          Custom Close Button
        </Button>
      </div>

      <Modal @isOpen={{this.normalOpen}} @onClose={{this.toggleNormal}} as |m|>
        <m.Header>Normal Close Button</m.Header>
        <m.Body>
          <p>This modal has the default close button in the top right corner.</p>
        </m.Body>
        <m.Footer>
          <Button @onPress={{this.toggleNormal}}>Done</Button>
        </m.Footer>
      </Modal>

      <Modal
        @isOpen={{this.noCloseButtonOpen}}
        @onClose={{this.toggleNoCloseButton}}
        @allowCloseButton={{false}}
        as |m|
      >
        <m.Header>No Close Button</m.Header>
        <m.Body>
          <p>This modal has no close button. You can still close it by clicking
            the backdrop or pressing Escape.</p>
        </m.Body>
        <m.Footer>
          <Button @onPress={{this.toggleNoCloseButton}}>
            Close from Footer
          </Button>
        </m.Footer>
      </Modal>

      <Modal
        @isOpen={{this.customCloseOpen}}
        @onClose={{this.toggleCustomClose}}
        @allowCloseButton={{false}}
        as |m|
      >
        <m.Header>
          <div class='flex justify-between items-center'>
            <span>Custom Close Button</span>
            <m.CloseButton data-part="close-button" />
          </div>
        </m.Header>
        <m.Body>
          <p>This modal uses a custom close button placed in the header using
            the yielded CloseButton component.</p>
        </m.Body>
        <m.Footer>
          <Button @onPress={{this.toggleCustomClose}}>Done</Button>
        </m.Footer>
      </Modal>
    </div>
  </template>
}
```

### Nested Modals

Example showing modals that can open other modals.

```gts preview collapsible
import Component from '@glimmer/component';
import { tracked } from '@glimmer/tracking';
import { Modal } from 'frontile';
import { Button } from 'frontile';

export default class NestedModals extends Component {
  @tracked firstModalOpen = false;
  @tracked secondModalOpen = false;
  @tracked thirdModalOpen = false;

  toggleFirst = () => {
    this.firstModalOpen = !this.firstModalOpen;
  };

  toggleSecond = () => {
    this.secondModalOpen = !this.secondModalOpen;
  };

  toggleThird = () => {
    this.thirdModalOpen = !this.thirdModalOpen;
  };

  closeAll = () => {
    this.thirdModalOpen = false;
    this.secondModalOpen = false;
    this.firstModalOpen = false;
  };

  <template>
    <div class='demo-stack demo-stack--wide items-center'>
      <Button @onPress={{this.toggleFirst}}>
        Open First Modal
      </Button>

      <!-- First Modal -->
      <Modal
        @isOpen={{this.firstModalOpen}}
        @onClose={{this.toggleFirst}}
        as |m|
      >
        <m.Header>First Modal</m.Header>
        <m.Body>
          <p class='mb-4'>This is the first modal. You can open another modal
            from here.</p>
          <p class='text-sm text-neutral'>Notice how the backdrop becomes darker
            with each modal layer.</p>

          <!-- Second Modal -->
          <Modal
            @isOpen={{this.secondModalOpen}}
            @onClose={{this.toggleSecond}}
            @size='md'
            as |m|
          >
            <m.Header>Second Modal</m.Header>
            <m.Body>
              <p class='mb-4'>This is the second modal, opened from the first
                one.</p>
              <p class='text-sm text-neutral'>You can continue nesting modals as
                needed.</p>

              <!-- Third Modal -->
              <Modal
                @isOpen={{this.thirdModalOpen}}
                @onClose={{this.toggleThird}}
                @size='sm'
                as |m|
              >
                <m.Header>Third Modal</m.Header>
                <m.Body>
                  <p class='mb-4'>This is the third and final modal in this
                    example.</p>
                  <p class='text-sm text-neutral'>Each modal maintains its own
                    focus trap and can be closed independently.</p>
                </m.Body>
                <m.Footer @class='flex gap-2'>
                  <Button @onPress={{this.toggleThird}}>
                    Close This
                  </Button>
                  <Button @color='danger' @onPress={{this.closeAll}}>
                    Close All
                  </Button>
                </m.Footer>
              </Modal>
            </m.Body>
            <m.Footer @class='flex gap-2'>
              <Button @onPress={{this.toggleSecond}}>
                Close
              </Button>
              <Button @color='primary' @onPress={{this.toggleThird}}>
                Open Third Modal
              </Button>
            </m.Footer>
          </Modal>

        </m.Body>
        <m.Footer @class='flex gap-2'>
          <Button @onPress={{this.toggleFirst}}>
            Close
          </Button>
          <Button @color='primary' @onPress={{this.toggleSecond}}>
            Open Second Modal
          </Button>
        </m.Footer>
      </Modal>

    </div>
  </template>
}
```

### Modals that start open

A modal whose `@isOpen` is already true the first time it renders — deep-linked open, or
restored by a page refresh — waits for the browser's first paint before appearing, so its
animation plays against the page rather than starting before anything has been drawn. Pass
`@animateOnMount={{false}}` when an already-open modal should simply be there, with no
reveal.

## Anatomy

Modal yields the pieces you assemble the dialog from:

| Yielded       | Purpose                                                         |
| ------------- | --------------------------------------------------------------- |
| `Header`      | Heading region; applies the id that `aria-labelledby` points at |
| `Body`        | Main content area                                               |
| `Footer`      | Action row                                                      |
| `CloseButton` | Styled close button wired to `@onClose`                         |
| `headerId`    | The id `Header` uses, for labelling your own heading instead    |

## Accessibility

The dialog element renders as `role="dialog"` with `tabindex="0"` and `aria-modal="true"`,
labelled by `aria-labelledby` pointing at the id yielded as `headerId` — which is applied by
`<m.Header>`. `aria-labelledby` is only rendered while a `Header` is actually on the page, so
a modal without one has no dangling reference — but it also has **no accessible name**. Give
it one: render a `Header`, or pass your own label through attributes.

```gts
<Modal @isOpen={{this.isOpen}} @onClose={{this.close}} aria-label="Delete account" as |m|>
  <m.Body>This cannot be undone.</m.Body>
</Modal>
```

If you label the dialog with a heading of your own rather than `<m.Header>`, pass
`aria-labelledby` yourself — putting the yielded `headerId` on a heading does not label the
dialog by itself, because nothing points at it:

```gts
<Modal @isOpen={{this.isOpen}} @onClose={{this.close}} aria-labelledby={{this.titleId}} as |m|>
  <h2 id={{this.titleId}}>My Title</h2>
  <m.Body>My Content</m.Body>
</Modal>
```

A modal with no accessible name — no `Header`, `aria-label`, or `aria-labelledby` — is
invalid. Frontile reports this during development with the warning id
`frontile.modal.missing-accessible-name` so it can be corrected before release.

`aria-modal="true"` is dropped when `@disableFocusTrap={{true}}`: with the trap off the page
behind really is reachable, and claiming otherwise would mislead screen reader users. Note
that the modal still auto-focuses itself in this case, unless `@preventAutoFocus={{true}}`
is also passed — see [Overlay](./overlay.md#accessibility).

Behavior inherited from [Overlay](./overlay.md):

| Behavior       | Detail                                                |
| -------------- | ----------------------------------------------------- |
| Focus on open  | Moves into the modal, and a focus trap keeps it there |
| Focus on close | Returns to whatever was focused before opening        |
| `Escape`       | Closes, unless `@closeOnEscapeKey={{false}}`          |
| Backdrop click | Closes, unless `@closeOnOutsideClick={{false}}`       |
| Body scroll    | Blocked while open (reference counted for nesting)    |

The modal needs at least one focusable element inside it, or the focus trap has nowhere to
put focus. Note that `@allowClosing={{false}}` disables Escape, backdrop click and the close
button together, which leaves a keyboard user no way out — reserve it for flows that provide
their own explicit resolution.

Under `prefers-reduced-motion: reduce`, the modal fades in without the zoom.

Frontile does not set `aria-describedby`. Add it yourself if your dialog needs it.

## API

### Modal

**Element:** `HTMLDivElement`

**Arguments**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `isOpen *` | `boolean` | - | Whether it is open or not |
| `allowCloseButton` | `boolean` | `true` | If set to false, the close button will not be displayed. |
| `allowClosing` | `boolean` | `true` | If set to false, the close button will not be displayed, closeOnOutsideClick will be set to false, and closeOnEscapeKey will also be set to false. |
| `animateOnMount` | `boolean` | `true` | Whether an overlay that is already open the first time it renders -- deep-linked open, or restored by a page refresh -- animates in. When true (the default) the overlay waits for the browser's first paint before mounting, so the animation plays against a page the user has already seen. Set it to false for an already-open overlay that should simply be there, with no reveal. An overlay opened later by interaction animates either way, and so does closing. |
| `backdrop` | `'faded' \| 'none' \| 'transparent' \| 'blur'` | - | How the area behind the overlay is rendered: none omits the backdrop entirely, transparent keeps it clickable but invisible, faded dims the page, and blur blurs it. |
| `backdropTransition` | `Object` | - | Transition classes for the backdrop, overriding the defaults used when it fades in and out. |
| `classes` | `SlotsToClasses<'base' \| 'closeButton' \| 'header' \| 'body' \| 'footer'>` | - | Class names for each slot of the component, merged with the theme's. |
| `closeButtonSize` | `'sm' \| 'md' \| 'lg' \| 'xs' \| 'xl'` | - | The Close Button size. |
| `closeOnEscapeKey` | `boolean` | `true` | Whether to close when the escape key is pressed |
| `closeOnOutsideClick` | `boolean` | `true` | Whether to close when the area outside (the backdrop) is clicked |
| `didClose` | `() => void` | - | A function that will be called when closing is finished executing, this includes waiting for animations/transitions to finish. |
| `disableFocusTrap` | `boolean` | `false` | Whether the focus trap is disabled or not |
| `disableTransitions` | `boolean` | `false` | Disable css transitions |
| `focusTrapOptions` | `any` | `{ clickOutsideDeactivates: true, allowOutsideClick: true }` | Focus trap options |
| `isCentered` | `boolean` | `false` | If set to true, the modal will be vertically centered |
| `onClose` | `() => void` | - | A function that will be called when closed |
| `onOpen` | `() => void` | - | A function that will be called when opened |
| `preventAutoFocus` | `boolean` | `false` | When focusTrap is disabled, by default Oberlay will be auto focused. This option prevents that. |
| `renderInPlace` | `boolean` | `false` | Whether to render in place or in the specified/default destination |
| `size` | `'sm' \| 'md' \| 'lg' \| 'xs' \| 'xl' \| 'full'` | `'lg'` | The Modal size. |
| `target` | `string \| Element` | - | The target where to render the portal. There are 3 options: 1) Element object, 2) element id, 3) portal target name. For element id, string must be prefixed with #. If no value is passed in, we will render to the closest unnamed portal target, parent portal or document.body. |
| `transition` | `Object` | `{name: 'overlay-transition--zoom'}` | The transition to be used in the Modal. |
| `transitionDuration` | `number` | `200` | Duration of the animation |

**Blocks**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `default *` | `[{ CloseButton: CloseButton (onPress, class bound); Header: ModalHeader (labelledById, classFromParent, registerSelf bound); Body: ModalBody (classFromParent bound); Footer: ModalFooter (classFromParent bound); headerId: string; }]` | - |  |

---

# Overlay

Source: /docs/components/overlays/overlay.md

# Overlay

The Overlay component is the foundation for Modal, Drawer, Popover, and similar overlays. It handles focus management, the backdrop, escape/outside-click dismissal, and scroll locking.

## Import

```js
import { Overlay } from 'frontile';
```

## Usage

### Basic Overlay

The most basic usage of the Overlay component.

```gts preview collapsible
import Component from '@glimmer/component';
import { tracked } from '@glimmer/tracking';
import { Overlay } from 'frontile';
import { Button } from 'frontile';

export default class BasicOverlay extends Component {
  @tracked isOpen = false;

  toggle = () => {
    this.isOpen = !this.isOpen;
  };

  <template>
    <div class='demo-stack demo-stack--wide items-center'>
      <Button @onPress={{this.toggle}}>
        Open Overlay
      </Button>

      <Overlay @isOpen={{this.isOpen}} @onClose={{this.toggle}}>
        <div class='bg-content1 p-8 rounded-lg shadow-lg max-w-md'>
          <h2 class='text-lg font-semibold mb-4'>Overlay Content</h2>
          <p class='mb-4'>This is the content inside the overlay. You can put
            any content here.</p>
          <div class='flex gap-2'>
            <Button @color='primary' @onPress={{this.toggle}}>
              Close
            </Button>
            <Button>
              Another Action
            </Button>
          </div>
        </div>
      </Overlay>
    </div>
  </template>
}
```

### Overlay with Different Backdrop Types

Control the appearance of the backdrop behind the overlay.

```gts preview collapsible
import Component from '@glimmer/component';
import { tracked } from '@glimmer/tracking';
import { Overlay } from 'frontile';
import { Button } from 'frontile';

export default class BackdropTypes extends Component {
  @tracked fadedOpen = false;
  @tracked blurredOpen = false;
  @tracked noneOpen = false;

  toggleFaded = () => {
    this.fadedOpen = !this.fadedOpen;
  };

  toggleBlurred = () => {
    this.blurredOpen = !this.blurredOpen;
  };

  toggleNone = () => {
    this.noneOpen = !this.noneOpen;
  };

  <template>
    <div class='demo-stack demo-stack--wide items-center'>
      <div class='flex gap-2'>
        <Button @onPress={{this.toggleFaded}}>
          Faded Backdrop
        </Button>
        <Button @onPress={{this.toggleBlurred}}>
          Blurred Backdrop
        </Button>
        <Button @onPress={{this.toggleNone}}>
          No Backdrop
        </Button>
      </div>

      <Overlay
        @isOpen={{this.fadedOpen}}
        @onClose={{this.toggleFaded}}
        @backdrop='faded'
      >
        <div class='bg-content1 p-6 rounded-lg shadow-lg'>
          <h3 class='font-semibold mb-2'>Faded Backdrop</h3>
          <p class='mb-4'>Standard semi-transparent backdrop</p>
          <Button @onPress={{this.toggleFaded}}>Close</Button>
        </div>
      </Overlay>

      <Overlay
        @isOpen={{this.blurredOpen}}
        @onClose={{this.toggleBlurred}}
        @backdrop='blur'
      >
        <div class='bg-content1 p-6 rounded-lg shadow-lg'>
          <h3 class='font-semibold mb-2'>Blurred Backdrop</h3>
          <p class='mb-4'>Backdrop with blur effect</p>
          <Button @onPress={{this.toggleBlurred}}>Close</Button>
        </div>
      </Overlay>

      <Overlay
        @isOpen={{this.noneOpen}}
        @onClose={{this.toggleNone}}
        @backdrop='none'
      >
        <div class='bg-content1 p-6 rounded-lg shadow-lg border'>
          <h3 class='font-semibold mb-2'>No Backdrop</h3>
          <p class='mb-4'>Overlay without backdrop</p>
          <Button @onPress={{this.toggleNone}}>Close</Button>
        </div>
      </Overlay>
    </div>
  </template>
}
```

### Render In Place

By default, overlays are rendered in a portal. You can render them in-place instead.

```gts preview collapsible
import Component from '@glimmer/component';
import { tracked } from '@glimmer/tracking';
import { Overlay } from 'frontile';
import { Button } from 'frontile';

export default class RenderInPlace extends Component {
  @tracked portalOpen = false;
  @tracked inPlaceOpen = false;

  togglePortal = () => {
    this.portalOpen = !this.portalOpen;
  };

  toggleInPlace = () => {
    this.inPlaceOpen = !this.inPlaceOpen;
  };

  <template>
    <div class='demo-stack demo-stack--wide items-center'>
      <div class='flex gap-2'>
        <Button @onPress={{this.togglePortal}}>
          Portal Overlay (Default)
        </Button>
        <Button @onPress={{this.toggleInPlace}}>
          In-Place Overlay
        </Button>
      </div>

      <div
        class='relative border-2 border-dashed border-neutral-soft p-4 min-h-48'
      >
        <p class='text-sm text-neutral mb-4'>This container shows the difference
          between portal and in-place rendering.</p>

        <Overlay
          @isOpen={{this.inPlaceOpen}}
          @onClose={{this.toggleInPlace}}
          @renderInPlace={{true}}
        >
          <div
            class='absolute inset-4 bg-content1 p-4 rounded shadow-lg border'
          >
            <h3 class='font-semibold mb-2'>In-Place Overlay</h3>
            <p class='text-sm mb-4'>This overlay is rendered within its parent
              container.</p>
            <Button @size='sm' @onPress={{this.toggleInPlace}}>Close</Button>
          </div>
        </Overlay>
      </div>

      <Overlay @isOpen={{this.portalOpen}} @onClose={{this.togglePortal}}>
        <div class='bg-content1 p-6 rounded-lg shadow-lg'>
          <h3 class='font-semibold mb-2'>Portal Overlay</h3>
          <p class='mb-4'>This overlay is rendered in a portal (outside the
            normal DOM tree).</p>
          <Button @onPress={{this.togglePortal}}>Close</Button>
        </div>
      </Overlay>
    </div>
  </template>
}
```

### Custom Close Behavior

Control when and how the overlay can be closed.

```gts preview collapsible
import Component from '@glimmer/component';
import { tracked } from '@glimmer/tracking';
import { Overlay } from 'frontile';
import { Button } from 'frontile';

export default class CustomCloseBehavior extends Component {
  @tracked normalOpen = false;
  @tracked noEscapeOpen = false;
  @tracked noOutsideClickOpen = false;
  @tracked confirmCloseOpen = false;

  toggleNormal = () => {
    this.normalOpen = !this.normalOpen;
  };

  toggleNoEscape = () => {
    this.noEscapeOpen = !this.noEscapeOpen;
  };

  toggleNoOutsideClick = () => {
    this.noOutsideClickOpen = !this.noOutsideClickOpen;
  };

  toggleConfirmClose = () => {
    this.confirmCloseOpen = !this.confirmCloseOpen;
  };

  handleConfirmClose = () => {
    if (confirm('Are you sure you want to close this overlay?')) {
      this.confirmCloseOpen = false;
    }
  };

  <template>
    <div class='demo-stack demo-stack--wide items-center'>
      <div class='grid grid-cols-2 gap-2'>
        <Button @onPress={{this.toggleNormal}}>
          Normal Overlay
        </Button>
        <Button @onPress={{this.toggleNoEscape}}>
          No Escape Key
        </Button>
        <Button @onPress={{this.toggleNoOutsideClick}}>
          No Outside Click
        </Button>
        <Button @onPress={{this.toggleConfirmClose}}>
          Confirm Close
        </Button>
      </div>

      <Overlay @isOpen={{this.normalOpen}} @onClose={{this.toggleNormal}}>
        <div class='bg-content1 p-6 rounded-lg shadow-lg'>
          <h3 class='font-semibold mb-2'>Normal Overlay</h3>
          <p class='mb-4'>Can be closed with Escape key, outside click, or
            button.</p>
          <Button @onPress={{this.toggleNormal}}>Close</Button>
        </div>
      </Overlay>

      <Overlay
        @isOpen={{this.noEscapeOpen}}
        @onClose={{this.toggleNoEscape}}
        @closeOnEscapeKey={{false}}
      >
        <div class='bg-content1 p-6 rounded-lg shadow-lg'>
          <h3 class='font-semibold mb-2'>No Escape Key</h3>
          <p class='mb-4'>Cannot be closed with Escape key. Try pressing Escape!</p>
          <Button @onPress={{this.toggleNoEscape}}>Close</Button>
        </div>
      </Overlay>

      <Overlay
        @isOpen={{this.noOutsideClickOpen}}
        @onClose={{this.toggleNoOutsideClick}}
        @closeOnOutsideClick={{false}}
      >
        <div class='bg-content1 p-6 rounded-lg shadow-lg'>
          <h3 class='font-semibold mb-2'>No Outside Click</h3>
          <p class='mb-4'>Cannot be closed by clicking outside. Try clicking the
            backdrop!</p>
          <Button @onPress={{this.toggleNoOutsideClick}}>Close</Button>
        </div>
      </Overlay>

      <Overlay
        @isOpen={{this.confirmCloseOpen}}
        @onClose={{this.handleConfirmClose}}
      >
        <div class='bg-content1 p-6 rounded-lg shadow-lg'>
          <h3 class='font-semibold mb-2'>Confirm Close</h3>
          <p class='mb-4'>Shows confirmation dialog before closing.</p>
          <Button @onPress={{this.handleConfirmClose}}>Close</Button>
        </div>
      </Overlay>
    </div>
  </template>
}
```

### Focus Management

Demonstrate focus trapping and restoration features.

```gts preview collapsible
import Component from '@glimmer/component';
import { tracked } from '@glimmer/tracking';
import { Overlay } from 'frontile';
import { Button } from 'frontile';
import { Input } from 'frontile';

export default class FocusManagement extends Component {
  @tracked focusTrapOpen = false;
  @tracked noFocusTrapOpen = false;

  toggleFocusTrap = () => {
    this.focusTrapOpen = !this.focusTrapOpen;
  };

  toggleNoFocusTrap = () => {
    this.noFocusTrapOpen = !this.noFocusTrapOpen;
  };

  <template>
    <div class='demo-stack demo-stack--wide items-center'>
      <div class='flex gap-2'>
        <Button @onPress={{this.toggleFocusTrap}} data-test-trigger>
          Focus Trap Enabled
        </Button>
        <Button @onPress={{this.toggleNoFocusTrap}}>
          Focus Trap Disabled
        </Button>
      </div>

      <p class='text-sm text-neutral'>
        Open an overlay and use Tab/Shift+Tab to see focus behavior. Focus
        should return to the trigger button when closed.
      </p>

      <Overlay @isOpen={{this.focusTrapOpen}} @onClose={{this.toggleFocusTrap}}>
        <div class='bg-content1 p-6 rounded-lg shadow-lg max-w-md'>
          <h3 class='font-semibold mb-4'>Focus Trap Enabled</h3>
          <p class='mb-4 text-sm'>Focus is trapped within this overlay. Try
            pressing Tab to cycle through focusable elements.</p>

          <div class='space-y-3'>
            <Input @label='First Input' />
            <Input @label='Second Input' />
            <div class='flex gap-2'>
              <Button @color='primary' @onPress={{this.toggleFocusTrap}}>
                Close
              </Button>
              <Button>
                Another Button
              </Button>
            </div>
          </div>
        </div>
      </Overlay>

      <Overlay
        @isOpen={{this.noFocusTrapOpen}}
        @onClose={{this.toggleNoFocusTrap}}
        @disableFocusTrap={{true}}
      >
        <div class='bg-content1 p-6 rounded-lg shadow-lg max-w-md'>
          <h3 class='font-semibold mb-4'>Focus Trap Disabled</h3>
          <p class='mb-4 text-sm'>Focus is not trapped. You can Tab to elements
            outside the overlay.</p>

          <div class='space-y-3'>
            <Input @label='Input Field' />
            <Button @onPress={{this.toggleNoFocusTrap}}>
              Close
            </Button>
          </div>
        </div>
      </Overlay>
    </div>
  </template>
}
```

### Animations and Transitions

Customize overlay animations and transition duration.

```gts preview collapsible
import Component from '@glimmer/component';
import { tracked } from '@glimmer/tracking';
import { Overlay } from 'frontile';
import { Button } from 'frontile';

export default class AnimationsAndTransitions extends Component {
  @tracked fastOpen = false;
  @tracked slowOpen = false;
  @tracked noAnimationOpen = false;

  toggleFast = () => {
    this.fastOpen = !this.fastOpen;
  };

  toggleSlow = () => {
    this.slowOpen = !this.slowOpen;
  };

  toggleNoAnimation = () => {
    this.noAnimationOpen = !this.noAnimationOpen;
  };

  <template>
    <div class='demo-stack demo-stack--wide items-center'>
      <div class='flex gap-2'>
        <Button @onPress={{this.toggleFast}}>
          Fast Animation (100ms)
        </Button>
        <Button @onPress={{this.toggleSlow}}>
          Slow Animation (800ms)
        </Button>
        <Button @onPress={{this.toggleNoAnimation}}>
          No Animation
        </Button>
      </div>

      <Overlay
        @isOpen={{this.fastOpen}}
        @onClose={{this.toggleFast}}
        @transitionDuration={{100}}
      >
        <div class='bg-content1 p-6 rounded-lg shadow-lg'>
          <h3 class='font-semibold mb-2'>Fast Animation</h3>
          <p class='mb-4'>This overlay opens and closes quickly (100ms).</p>
          <Button @onPress={{this.toggleFast}}>Close</Button>
        </div>
      </Overlay>

      <Overlay
        @isOpen={{this.slowOpen}}
        @onClose={{this.toggleSlow}}
        @transitionDuration={{800}}
      >
        <div class='bg-content1 p-6 rounded-lg shadow-lg'>
          <h3 class='font-semibold mb-2'>Slow Animation</h3>
          <p class='mb-4'>This overlay has a longer transition duration (800ms).</p>
          <Button @onPress={{this.toggleSlow}}>Close</Button>
        </div>
      </Overlay>

      <Overlay
        @isOpen={{this.noAnimationOpen}}
        @onClose={{this.toggleNoAnimation}}
        @disableTransitions={{true}}
      >
        <div class='bg-content1 p-6 rounded-lg shadow-lg'>
          <h3 class='font-semibold mb-2'>No Animation</h3>
          <p class='mb-4'>This overlay appears instantly without transitions.</p>
          <Button @onPress={{this.toggleNoAnimation}}>Close</Button>
        </div>
      </Overlay>
    </div>
  </template>
}
```

### Overlays that start open

An overlay whose `@isOpen` is already true the first time it renders — one that is
deep-linked open, or that a page refresh restored — waits for the browser's first paint
before appearing, so its animation plays against the page rather than starting before
anything has been drawn.

Pass `@animateOnMount={{false}}` when an already-open overlay should simply be there, with
no reveal — Modal and Drawer forward it too. An overlay opened later by interaction animates
either way, and so does closing.

```gts preview collapsible
import Component from '@glimmer/component';
import { tracked } from '@glimmer/tracking';
import { Overlay } from 'frontile';
import { Button } from 'frontile';

export default class OverlaysThatStartOpen extends Component {
  @tracked showAnimated = false;
  @tracked showImmediate = false;

  mountAnimated = () => {
    this.showAnimated = true;
  };

  mountImmediate = () => {
    this.showImmediate = true;
  };

  closeAnimated = () => {
    this.showAnimated = false;
  };

  closeImmediate = () => {
    this.showImmediate = false;
  };

  <template>
    <div class='demo-stack demo-stack--wide items-center'>
      <div class='flex gap-2'>
        <Button @onPress={{this.mountAnimated}}>
          Render already open
        </Button>
        <Button @onPress={{this.mountImmediate}}>
          Render already open, no animation
        </Button>
      </div>

      {{#if this.showAnimated}}
        <Overlay @isOpen={{true}} @onClose={{this.closeAnimated}}>
          <div class='bg-surface-modal p-6 rounded-lg shadow-lg'>
            <h3 class='font-semibold mb-2'>Animated</h3>
            <p class='mb-4'>Rendered with @isOpen already true.</p>
            <Button @onPress={{this.closeAnimated}}>Close</Button>
          </div>
        </Overlay>
      {{/if}}

      {{#if this.showImmediate}}
        <Overlay
          @isOpen={{true}}
          @onClose={{this.closeImmediate}}
          @animateOnMount={{false}}
        >
          <div class='bg-surface-modal p-6 rounded-lg shadow-lg'>
            <h3 class='font-semibold mb-2'>No mount animation</h3>
            <p class='mb-4'>It is simply there. Closing still animates.</p>
            <Button @onPress={{this.closeImmediate}}>Close</Button>
          </div>
        </Overlay>
      {{/if}}
    </div>
  </template>
}
```

### Outside Click vs Overlay Element Click

The Overlay component has two different click-to-close mechanisms that work together:

- **`@closeOnOutsideClick`** (default: `true`): Closes when clicking the backdrop/outside area
- **`@closeOnOverlayElementClick`** (default: `true`): Closes when clicking the overlay element itself

```gts preview collapsible
import Component from '@glimmer/component';
import { tracked } from '@glimmer/tracking';
import { Overlay } from 'frontile';
import { Button } from 'frontile';

export default class OverlayElementClick extends Component {
  @tracked defaultOpen = false;
  @tracked disabledOpen = false;

  toggleDefault = () => {
    this.defaultOpen = !this.defaultOpen;
  };

  toggleDisabled = () => {
    this.disabledOpen = !this.disabledOpen;
  };

  <template>
    <div class='demo-stack demo-stack--wide items-center'>
      <div class='flex gap-2'>
        <Button @onPress={{this.toggleDefault}}>
          Default Behavior
        </Button>
        <Button @onPress={{this.toggleDisabled}}>
          Overlay Element Click Disabled
        </Button>
      </div>

      <div class='text-sm space-y-2'>
        <p><strong>Default Behavior:</strong>
          Try clicking on the overlay element (the outer container) vs the inner
          content card.</p>
        <p><strong>Disabled:</strong>
          Only the backdrop (outside area) will close the overlay.</p>
      </div>

      <Overlay @isOpen={{this.defaultOpen}} @onClose={{this.toggleDefault}}>
        <div class='bg-content1 p-6 rounded-lg shadow-lg max-w-md'>
          <h3 class='font-semibold mb-2'>Default Behavior</h3>
          <p class='mb-4 text-sm'>
            <code>@closeOnOverlayElementClick={{true}}</code>
            (default)
          </p>
          <p class='mb-4'>Clicking anywhere on the overlay element will close
            it, but clicking this inner content card won't.</p>
          <Button @onPress={{this.toggleDefault}}>Close</Button>
        </div>
      </Overlay>

      <Overlay
        @isOpen={{this.disabledOpen}}
        @onClose={{this.toggleDisabled}}
        @closeOnOverlayElementClick={{false}}
      >
        <div class='bg-content1 p-6 rounded-lg shadow-lg max-w-md'>
          <h3 class='font-semibold mb-2'>Overlay Element Click Disabled</h3>
          <p class='mb-4 text-sm'>
            <code>@closeOnOverlayElementClick={{false}}</code>
          </p>
          <p class='mb-4'>Only clicking the backdrop (outside area) will not
            close this overlay because the overlay content element is on top of
            backdrop.</p>
          <Button @onPress={{this.toggleDisabled}}>Close</Button>
        </div>
      </Overlay>
    </div>
  </template>
}
```

> **Note:** Content wrapped in an inner element — a card, a dialog — is not the overlay
> element itself, so clicking your content never closes the overlay. What
> `@closeOnOverlayElementClick` covers is the area around it.

## Using Power Select inside an Overlay

`FormSelect` uses Power Select, which defaults to `@renderInPlace={{false}}` and so inserts
its dropdown outside the overlay. The focus trap then treats the dropdown as outside the
overlay and blocks access to it, including its search input.

Pass `@renderInPlace={{true}}` on the `FormSelect` so the dropdown stays inside the trap:

```gts
<FormSelect @renderInPlace={{true}} />
```

Disabling the overlay's focus trap with `@disableFocusTrap={{true}}` also works, but it
removes the trap for everything else in the overlay too — prefer the first option.

## Accessibility

Overlay is the primitive under Modal, Drawer and Popover, and supplies their shared focus
and keyboard behavior. It sets `tabindex="0"` on the content element but no role — a
semantic role is the consuming component's job, which is why Modal and Drawer add
`role="dialog"` themselves. If you build directly on Overlay, give it a role and an
accessible name.

| Behavior           | Detail                                                                                                |
| ------------------ | ----------------------------------------------------------------------------------------------------- |
| Focus on open      | Moves into the overlay; `ember-focus-trap` keeps it there                                             |
| Focus trap         | Disable with `@disableFocusTrap={{true}}`, or tune via `@focusTrapOptions`                            |
| Focus without trap | Still auto-focuses the overlay when `@disableFocusTrap={{true}}`, unless `@preventAutoFocus={{true}}` |
| Focus on close     | Returns to the previously focused element, unless `@preventFocusRestore`                              |
| `Escape`           | Closes, unless `@closeOnEscapeKey={{false}}`                                                          |
| Backdrop click     | Closes, unless `@closeOnOutsideClick={{false}}`                                                       |
| Body scroll        | Blocked while open, unless `@blockScroll={{false}}`                                                   |
| Nested scroll      | Reference counted, so closing an inner overlay keeps the outer lock                                   |

**The overlay needs at least one focusable element inside it.** A focus trap with nothing to
focus leaves the keyboard stranded, and nothing warns you at runtime.

`@focusTrapOptions` is merged over the defaults (`clickOutsideDeactivates: true`,
`allowOutsideClick: true`), so naming one option does not cost you the rest. Setting either
of those to `false` explicitly still holds outside clicks inside the trap. `setReturnFocus`
is the supported way to send focus somewhere other than the trigger when the overlay closes —
it runs when the trap tears down, which is after the close transition, so focusing an element
yourself beforehand is undone.

Overlays that block scroll are reference counted, so a Modal that opens a Drawer stays
locked until the last of them closes. Whatever inline `overflow` the page had before the
first lock is restored, rather than blanked. Overlays rendered with `@renderInPlace={{true}}`
or `@blockScroll={{false}}` never take part in that count.

Under `prefers-reduced-motion: reduce`, the built-in transitions drop their movement and
keep only the fade: `fade` is unchanged, `zoom` and `scale` stop scaling, and the
`slideFrom*` transitions fade in place instead of travelling. A custom `@transition` is
yours to adapt.

Frontile does not set `aria-modal`, `aria-labelledby` or `aria-describedby` at this level.

## API

### Overlay

**Element:** `HTMLDivElement`

**Arguments**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `isOpen *` | `boolean` | - | Whether it is open or not |
| `animateOnMount` | `boolean` | `true` | Whether an overlay that is already open the first time it renders -- deep-linked open, or restored by a page refresh -- animates in. When true (the default) the overlay waits for the browser's first paint before mounting, so the animation plays against a page the user has already seen. Set it to false for an already-open overlay that should simply be there, with no reveal. An overlay opened later by interaction animates either way, and so does closing. |
| `backdrop` | `'faded' \| 'none' \| 'transparent' \| 'blur'` | - | How the area behind the overlay is rendered: none omits the backdrop entirely, transparent keeps it clickable but invisible, faded dims the page, and blur blurs it. |
| `backdropTransition` | `Object` | - | Transition classes for the backdrop, overriding the defaults used when it fades in and out. |
| `blockScroll` | `boolean` | `true` |  |
| `class` | `string` | - | Custom class name for the content element, merged with the default ones using Tailwind Merge. |
| `closeOnEscapeKey` | `boolean` | `true` | Whether to close when the escape key is pressed |
| `closeOnOutsideClick` | `boolean` | `true` | Whether to close when the area outside (the backdrop) is clicked |
| `closeOnOverlayElementClick` | `boolean` | `true` | Whether to close when the overlay element is clicked, used for modal and drawer components. This is set to true by default to allow "outside click" functionality to work properly. Most overlay content is wrapped with an inner element, preventing accidental closure. |
| `customContentModifier` | `ModifierLike<{ Element: HTMLElement; }>` | - | An extra modifier applied to the content element, for behavior the overlay doesn't provide itself. |
| `didClose` | `() => void` | - | A function that will be called when closing is finished executing, this includes waiting for animations/transitions to finish. |
| `disableFlexContent` | `boolean` | `false` | Opt out of the flex layout applied to the content element, for overlays that need to lay their content out themselves. |
| `disableFocusTrap` | `boolean` | `false` | Whether the focus trap is disabled or not |
| `disableTransitions` | `boolean` | `false` | Disable css transitions |
| `focusTrapOptions` | `any` | `{ clickOutsideDeactivates: true, allowOutsideClick: true }` | Focus trap options |
| `onClose` | `() => void` | - | A function that will be called when closed |
| `onOpen` | `() => void` | - | A function that will be called when opened |
| `preventAutoFocus` | `boolean` | `false` | When focusTrap is disabled, by default Oberlay will be auto focused. This option prevents that. |
| `preventFocusRestore` | `boolean` | `false` |  |
| `renderInPlace` | `boolean` | `false` | Whether to render in place or in the specified/default destination |
| `target` | `string \| Element` | - | The target where to render the portal. There are 3 options: 1) Element object, 2) element id, 3) portal target name. For element id, string must be prefixed with #. If no value is passed in, we will render to the closest unnamed portal target, parent portal or document.body. |
| `transition` | `Object` | `{name:'overlay-transition--fade'}` | Transition options |
| `transitionDuration` | `number` | `200` | Duration of the animation |

**Blocks**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `default *` | `[]` | - |  |

---

# Popover

Source: /docs/components/overlays/popover.md

# Popover

A Popover shows supplementary content — a form, a menu, extra detail — next to a
trigger element, in a small overlay. It can be triggered by click, hover, or
focus.

Popover is built on [Overlay](./overlay.md), and all of Overlay's arguments are
also accepted by the `Content` yielded component.

## Import

```js
import { Popover } from 'frontile';
```

## Usage

```gts preview
import { Button } from 'frontile';
import { Popover } from 'frontile';

<template>
  <Popover as |p|>
    <Button {{p.trigger}} {{p.anchor}}>
      Toggle Popover
    </Button>

    <p.Content @class='p-2'>
      This is some example content for the popover. It can contain anything.
    </p.Content>
  </Popover>
</template>
```

## Focus Trapping

Prevents the user from tabbing outside of the popover content while it's open.
To enable this option, ensure a focusable element is rendered at all times
within the popover content.

```gts preview
import { Button } from 'frontile';
import { Popover } from 'frontile';
import { Input } from 'frontile';

<template>
  <Popover as |p|>
    <Button {{p.trigger}} {{p.anchor}}>
      Toggle Popover
    </Button>

    <p.Content @disableFocusTrap={{false}} @class='p-4'>
      <Input @label='First Name' class='mb-2' />
      <Input @label='Last Name' class='mb-2' />
      <Button>Save</Button>
    </p.Content>
  </Popover>
</template>
```

## The Trigger

Besides a click on the trigger, Popover yields `open`, `close`, and `toggle`
functions for controlling visibility directly.

In the example below, the popover shows when the user hovers the trigger button.

```gts preview
import { on } from '@ember/modifier';
import { Popover } from 'frontile';
import { Button } from 'frontile';

<template>
  <Popover as |pop|>
    <Button
      {{pop.trigger}}
      {{pop.anchor}}
      {{on 'mouseenter' pop.open}}
      {{on 'mouseleave' pop.close}}
    >
      Hover me
    </Button>

    <pop.Content @class='p-2'>
      Hovered content
    </pop.Content>
  </Popover>
</template>
```

## Hover Trigger

`{{p.trigger "hover"}}` installs a trigger that opens on pointer hover or keyboard
`focus-visible`, rather than on click. It opens after `@openDelay` (default `100`ms) and
closes after `@closeDelay` (default `100`ms) once the pointer or focus has left both the
trigger and the content. `@closeDelay` is also the window the pointer has to cross the gap
between the trigger and the content, so a very small value makes the content practically
unreachable by pointer — moving onto the content otherwise keeps the popover open. Pass
`@disableInteractive={{true}}` to `Content` to close as soon as the pointer leaves the
trigger instead.

```gts preview
import { Button } from 'frontile';
import { Popover } from 'frontile';

<template>
  <Popover @openDelay={{100}} @closeDelay={{300}} as |p|>
    <Button {{p.trigger 'hover'}} {{p.anchor}}>
      Hover me
    </Button>

    <p.Content @class='p-2'>
      You can move the pointer onto this content without it closing.
    </p.Content>
  </Popover>
</template>
```

The `aria=` option passed alongside `"hover"` (or `"click"`) controls which ARIA
relationship the trigger element carries — see [Accessibility](#accessibility).

## Blocking Window Scroll

Prevent scrolling of the main window when the popover is open, focusing the
user's attention on the popover content.

```gts preview
import { Button } from 'frontile';
import { Popover } from 'frontile';
import { Input } from 'frontile';

<template>
  <Popover as |p|>
    <Button {{p.trigger}} {{p.anchor}}>
      Toggle Popover
    </Button>

    <p.Content @blockScroll={{true}} @disableFocusTrap={{false}} @class='p-4'>
      <Input @label='First Name' class='mb-2' />
      <Input @label='Last Name' class='mb-2' />
      <Button>Save</Button>
    </p.Content>
  </Popover>
</template>
```

## Backdrop Options

Choose from various backdrop options such as none, faded, blur, or transparent.

```gts preview
import { Button } from 'frontile';
import { Popover } from 'frontile';
import { Input } from 'frontile';

const backdrops = ['none', 'faded', 'blur', 'transparent'];

<template>
  {{#each backdrops as |backdrop|}}
    <Popover as |p|>
      <Button {{p.trigger}} {{p.anchor}}>
        {{backdrop}}
      </Button>

      <p.Content
        @backdrop={{backdrop}}
        @blockScroll={{true}}
        @disableFocusTrap={{false}}
        @class='p-4'
      >
        <Input @label='First Name' class='mb-2' />
        <Input @label='Last Name' class='mb-2' />
        <Button>Save</Button>
      </p.Content>
    </Popover>
  {{/each}}
</template>
```

## Placement

Specify the placement of the popover relative to its trigger element.

```gts preview collapsible
import { Button } from 'frontile';
import { Popover } from 'frontile';

const placements = [
  'top',
  'top-start',
  'top-end',
  'right',
  'right-start',
  'right-end',
  'bottom',
  'bottom-start',
  'bottom-end',
  'left',
  'left-start',
  'left-end'
];

<template>
  <div class='flex flex-wrap md:inline-grid md:grid-cols-3 gap-4'>
    {{#each placements as |placement|}}
      <Popover @placement={{placement}} as |p|>
        <Button {{p.trigger}} {{p.anchor}}>
          {{placement}}
        </Button>
        <p.Content @class='p-4'>
          This is some example content for the popover. It can contain anything.
        </p.Content>
      </Popover>
    {{/each}}
  </div>
</template>
```

## Arrow

`@arrow={{true}}` on `Content` renders an arrow pointing at the trigger. `Content` also
carries a `data-placement` attribute with the side floating-ui actually resolved for the
current position (after any flip), which the yielded `data` exposes too, for styling or
logic that needs to know which side the popover ended up on.

```gts preview
import { Button } from 'frontile';
import { Popover } from 'frontile';

<template>
  <Popover @placement='top' as |p|>
    <Button {{p.trigger}} {{p.anchor}}>
      Toggle Popover
    </Button>

    <p.Content @arrow={{true}} @class='p-2'>
      Resolved placement: {{p.data.placement}}
    </p.Content>
  </Popover>
</template>
```

## Size

The size of the content. It can be overwritten by passing width Tailwind classes
to the `Content` yielded component.

```gts preview
import { Button } from 'frontile';
import { Popover } from 'frontile';

const sizes = ['sm', 'md', 'lg', 'xl'];

<template>
  <div class='flex flex-wrap md:inline-grid md:grid-cols-4 gap-4'>
    {{#each sizes as |size|}}
      <Popover as |p|>
        <Button {{p.trigger}} {{p.anchor}}>
          {{size}}
        </Button>
        <p.Content @size={{size}} @class='p-4'>
          This is some example content for the popover. It can contain anything.
        </p.Content>
      </Popover>
    {{/each}}
  </div>
</template>
```

### Matching a different element's width

`@size='trigger'` sizes the content from `--trigger-width`, which is the width of
whatever element carries the `trigger` modifier. That is what you want while the
toggle and the box the content should line up with are the same element. When
they are not — a field where the toggle is one of several things sitting inside
it, and the content should match the whole field — put the `measureWidth`
modifier on the element to match. It takes precedence over the `trigger`
element's own width for as long as it is installed, so the two never race, and
you do not need it at all in the usual case.

## Controlled

You can use the `isOpen` and `onOpenChange` arguments to control whether the
popover is open or closed.

```gts preview collapsible
import Component from '@glimmer/component';
import { tracked } from '@glimmer/tracking';
import { Popover } from 'frontile';
import { Divider } from 'frontile';
import { Button } from 'frontile';

export default class Example extends Component {
  @tracked isOpen = false;

  onOpenChange = (isOpen: boolean) => {
    this.isOpen = isOpen;
  };

  open = () => {
    this.isOpen = true;
  };

  close = () => {
    this.isOpen = false;
  };

  <template>
    <Button @onPress={{this.open}}>Open</Button>
    <Divider class='my-4' />

    <Popover
      @isOpen={{this.isOpen}}
      @onOpenChange={{this.onOpenChange}}
      as |pop|
    >
      <Button {{pop.trigger}} {{pop.anchor}}>
        Toggle Popover
      </Button>

      <pop.Content @class='p-4'>
        This is some example content for the popover. Check the nested popover
        by clicking the button below.

        <Button @onPress={{this.close}}>Close Popover</Button>
      </pop.Content>
    </Popover>
  </template>
}
```

## Stacking Popovers

Each Popover instance maintains its own context, so a Popover can be triggered
from within another, creating a stacked arrangement. Pressing Escape closes
the most recently opened overlay first; clicking outside behaves the same way,
closing the topmost layer before the ones beneath it.

```gts preview collapsible
import { Popover } from 'frontile';
import { Button } from 'frontile';

<template>
  <Popover as |pop|>
    <Button {{pop.trigger}} {{pop.anchor}}>
      Toggle Popover
    </Button>

    <pop.Content @class='p-4'>
      This is some example content for the popover. Check the nested popover by
      clicking the button below.

      <Popover @placement='right' as |pop|>
        <Button {{pop.trigger}} {{pop.anchor}} @class='mt-2'>
          Second Popover
        </Button>

        <pop.Content @class='p-4'>
          <p>
            More content here, the nested overlay.
          </p>
          <p class='mt-2'>
            Clicking outside or pressing Escape will close this Popover, and not
            the root Popover.
          </p>
        </pop.Content>
      </Popover>
    </pop.Content>
  </Popover>
</template>
```

## Accessibility

The `trigger` modifier sets three attributes on whatever element you attach it to, and keeps
the last one in sync as the popover opens and closes:

```
aria-haspopup="true"
aria-controls="<the content's id>"
aria-expanded="true" | "false"
```

Because those go on your element, the trigger should be something natively focusable — a
`<button>`. Attaching `trigger` to a `<div>` gives you the ARIA without the keyboard.

With the default `click` trigger type, the trigger handles:

| Key                     | Behavior                                                       |
| ----------------------- | -------------------------------------------------------------- |
| `Enter` / `Space`       | Toggles, via the element's native click                        |
| `ArrowDown` / `ArrowUp` | Opens when closed                                              |
| any letter key          | Opens when closed, for type-ahead into the content             |
| `Escape`                | Closes when open                                               |
| `Tab`                   | Closes and moves on, without pulling focus back to the trigger |

A letter pressed with <kbd>Cmd</kbd>, <kbd>Ctrl</kbd> or <kbd>Alt</kbd> held is left alone —
those combinations belong to the browser or the OS, so <kbd>Cmd</kbd>+<kbd>R</kbd> reloads
without the popover opening over the page. <kbd>Shift</kbd>+letter still opens, since a
capital letter is legitimate type-ahead.

Focus moves into the content when it opens and returns to the trigger when it closes.

`@didClose` fires once the content has finished leaving, exit transition included — not at
the moment the popover is asked to close. That makes it the right place to unmount or reset
whatever the content was showing, and it will not fire at all for a `close()` on a popover
that was not open.

**`{{p.trigger "hover"}}`** opens on pointer hover, and also on keyboard `focus-visible` —
so it is reachable without a mouse. `Escape` closes it while it's open. The pointer, and
keyboard focus, may both move off the trigger and onto the content without the popover
closing (see [Hover Trigger](#hover-trigger)). Unlike the click trigger, a hover popover
never moves focus into its content — focus stays wherever it already was, avoiding the page
jump that comes from a portaled overlay being scrolled into view. Consequently there is
nothing to restore on close either.

The `aria=` option, passed alongside the trigger type, chooses which relationship the
trigger element carries:

| Value | Effect |
| --- | --- |
| `'menu'` (default) | Sets `aria-haspopup`, `aria-controls`, and `aria-expanded`, as described above |
| `'describedby'` | Sets `aria-describedby` instead, present only while open — appropriate when the content describes the trigger rather than acting as a menu or panel |
| `'none'` | Sets none of the above, for a fully custom ARIA setup |

```gts preview
import { Button } from 'frontile';
import { Popover } from 'frontile';

<template>
  <Popover as |p|>
    <Button {{p.trigger 'hover' aria='describedby'}} {{p.anchor}}>
      Hover me
    </Button>

    <p.Content @class='p-2'>
      Announced as this button's description.
    </p.Content>
  </Popover>
</template>
```

## API

### Popover

**Element:** `HTMLUListElement`

**Arguments**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `closeDelay` | `number` | `100` | Milliseconds to wait before closing after the pointer leaves the trigger or the content. Only applies to a trigger installed in hover mode. This is also the window the pointer has to cross the gap between the trigger and the content, so setting it to 0 makes content hover unreachable in practice. |
| `didClose` | `() => void` | - | Callback when closing has finished, including any exit transition. |
| `flipOptions` | `{ mainAxis?: boolean; crossAxis?: boolean \| 'alignment'; fallbackPlacements?: Placement[]; fallbackStrategy?: 'bestFit' \| 'initialPlacement'; fallbackAxisSideDirection?: 'start' \| ... 1 more ... \| 'none'; ... 5 more ...; boundary?: Boundary; }` | - | Options for the floating-ui flip middleware, which moves the content to the opposite side when it would overflow the viewport. |
| `isOpen` | `boolean` | - | Whether the popover is open. Pair with onOpenChange to control it; leave it unset to let the popover manage its own state. |
| `middleware` | `{ name: string; options?: any; fn: (state: { placement: Placement; strategy: Strategy; x: number; y: number; initialPlacement: Placement; middlewareData: MiddlewareData; rects: ElementRects; platform: { ...; } &#x26; Platform; elements: Elements; }) => Promisable<...>; }[]` | - | Additional floating-ui middleware, for positioning behavior beyond what placement, offsetOptions, flipOptions, and shiftOptions cover. |
| `offsetOptions` | `OffsetOptions` | `5` |  |
| `onOpenChange` | `(isOpen: boolean) => void` | - | Callback when the popover opens or closes, receiving the new state. |
| `openDelay` | `number` | `100` | Milliseconds to wait before opening on hover or keyboard focus. Only applies to a trigger installed in hover mode. |
| `placement` | `'top' \| 'top-start' \| 'top-end' \| 'right' \| 'right-start' \| 'right-end' \| 'bottom' \| 'bottom-start' \| 'bottom-end' \| 'left' \| 'left-start' \| 'left-end'` | `'bottom-start'` | Placement of the menu when open |
| `shiftOptions` | `{ mainAxis?: boolean; crossAxis?: boolean; rootBoundary?: RootBoundary; elementContext?: ElementContext; altBoundary?: boolean; padding?: Padding; limiter?: { ...; }; boundary?: Boundary; }` | - | Options for the floating-ui shift middleware, which nudges the content along its axis to keep it in view. |
| `strategy` | `Strategy` | `'absolute'` |  |

**Blocks**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `default *` | `[{ anchor: ModifierLike<{ Element: HTMLElement; }>; measureWidth: ModifierLike<{ Element: HTMLElement; }>; isOpen: boolean; toggle: () => void; open: () => void; close: () => void; trigger: ModifierLike<{ Element: HTMLElement; Args: { Positional: [eventType?: 'click' \| 'hover']; Named: { aria?: 'menu' \| 'describedby' \| 'none'; }; }; }>; data: MiddlewareArguments; Content: Content (loop, isOpen, id, toggle, internalDidClose, blockScroll, backdrop, triggerWidth, preventAutoFocus, isHoverTrigger, onContentHoverStart, onContentHoverEnd, registerArrow, velcroData bound); }]` | - |  |

### Content

Component yielded from Popover

**Element:** `HTMLDivElement`

**Arguments**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `id *` | `string` | - | _(internal)_ |
| `isOpen *` | `boolean` | - | _(internal)_ |
| `loop *` | `ModifierLike<{ Element: HTMLElement; }>` | - | _(internal)_ |
| `toggle *` | `() => void` | - | _(internal)_ |
| `arrow` | `boolean` | `false` | Renders an arrow pointing at the anchor. |
| `arrowClass` | `string` | - | _(internal)_ |
| `backdrop` | `'faded' \| 'none' \| 'transparent' \| 'blur'` | - | How the area behind the overlay is rendered: none omits the backdrop entirely, transparent keeps it clickable but invisible, faded dims the page, and blur blurs it. |
| `backdropTransition` | `Object` | - | Transition classes for the backdrop, overriding the defaults used when it fades in and out. |
| `blockScroll` | `boolean` | `true` |  |
| `class` | `string` | - | Custom class name for the content element, merged with the default ones using Tailwind Merge. |
| `closeOnEscapeKey` | `boolean` | `true` | Whether to close when the escape key is pressed |
| `closeOnOutsideClick` | `boolean` | `true` | Whether to close when the area outside (the backdrop) is clicked |
| `didClose` | `() => void` | - | A function that will be called when closing is finished executing, this includes waiting for animations/transitions to finish. |
| `disableFocusTrap` | `boolean` | `true` |  |
| `disableInteractive` | `boolean` | `false` | Closes as soon as the pointer leaves the trigger, instead of letting it move into the content. Only meaningful for a hover trigger. |
| `disableTransitions` | `boolean` | `false` | Disable css transitions |
| `focusTrapOptions` | `any` | `{ clickOutsideDeactivates: true, allowOutsideClick: true }` | Focus trap options |
| `isHoverTrigger` | `boolean` | - | _(internal)_ |
| `onContentHoverEnd` | `() => void` | - | _(internal)_ |
| `onContentHoverStart` | `() => void` | - | _(internal)_ |
| `onOpen` | `() => void` | - | A function that will be called when opened |
| `preventAutoFocus` | `boolean` | `false` | When focusTrap is disabled, by default Oberlay will be auto focused. This option prevents that. |
| `preventFocusRestore` | `boolean` | - | _(internal)_ |
| `registerArrow` | `ModifierLike<{ Element: HTMLElement; }>` | - | _(internal)_ |
| `renderInPlace` | `boolean` | `false` | Whether to render in place or in the specified/default destination |
| `size` | `'sm' \| 'md' \| 'lg' \| 'xl' \| 'trigger' \| 'auto'` | `'md'` | The size of the content. |
| `target` | `string \| Element` | - | The target where to render the portal. There are 3 options: 1) Element object, 2) element id, 3) portal target name. For element id, string must be prefixed with #. If no value is passed in, we will render to the closest unnamed portal target, parent portal or document.body. |
| `transition` | `Object` | `{name: 'overlay-transition--scale'}` | The transition to be used in the Modal. |
| `transitionDuration` | `number` | `200` | Duration of the animation |
| `triggerWidth` | `number` | - | _(internal)_ |
| `velcroData` | `{ placement: Placement; strategy: Strategy; x: number; y: number; initialPlacement: Placement; middlewareData: MiddlewareData; rects: ElementRects; platform: { ...; } &#x26; Platform; elements: Elements; }` | - | _(internal)_ |

**Blocks**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `default *` | `[]` | - |  |

---

# Portal & PortalTarget

Source: /docs/components/overlays/portal.md

# Portal & PortalTarget

`Portal` renders its content somewhere else in the DOM, and `PortalTarget` marks the places it can render to. Reach for them when content has to escape a parent's `overflow: hidden` or stacking context — modals, drawers, popovers, tooltips, toasts — or when it belongs in a specific region of the page for reading order or z-index reasons.

## Import

```js
import { Portal, PortalTarget } from 'frontile';
```

## Usage

With no arguments, `Portal` renders into the closest destination it can find, falling back to `document.body`.

```gts preview
import { Portal } from 'frontile';

<template>
  <Portal>
    <div class='p-4 border border-neutral-soft rounded shadow-md'>
      This content is rendered in a portal.
    </div>
  </Portal>
</template>
```

## PortalTarget

`PortalTarget` renders a `div` marked with `data-portal-target="true"` and, when `@for` is
given, `data-portal-for="<name>"`. It takes attributes and a block, so it can be positioned
and styled like any other element and can hold content of its own.

A target with no `@for` is **unnamed**: it is the default destination for any `Portal`
rendered below it that has no `@target` of its own. A target with `@for` is only used by
portals that ask for it by name, so it never captures unrelated content.

```gts preview
import { Portal, PortalTarget } from 'frontile';

<template>
  <div class='flex flex-col space-y-4'>
    <PortalTarget />
    <PortalTarget @for='target-1' />

    <Portal @target='target-1'>
      <div class='p-4 border border-neutral-soft rounded shadow-md'>
        Rendered to target-1
      </div>
    </Portal>
  </div>
</template>
```

### Named targets as slots

Because named targets are opt-in, several can coexist and each `Portal` picks one by name.
The target's own block content stays put; portal content is appended after it.

```gts preview
import { Button, Portal, PortalTarget } from 'frontile';

<template>
  <div class='flex gap-4'>
    <PortalTarget
      @for='toolbar'
      class='flex-1 flex items-center gap-2 p-3 border border-neutral-soft rounded'
    >
      <span class='text-neutral-strong'>Toolbar</span>
    </PortalTarget>

    <PortalTarget
      @for='footer'
      class='flex-1 flex items-center gap-2 p-3 border border-neutral-soft rounded'
    >
      <span class='text-neutral-strong'>Footer</span>
    </PortalTarget>

    <Portal @target='toolbar'>
      <Button @size='sm'>Save changes</Button>
    </Portal>

    <Portal @target='footer'>
      <Button @size='sm' @variant='outline'>Cancel</Button>
    </Portal>
  </div>
</template>
```

### An application-level target

Without a target, overlays land in `document.body`, outside the element your app styles and
outside its stacking context. Rendering one unnamed `PortalTarget` near the end of the
application template gives every overlay a predictable home you control — this documentation
site does exactly that:

```gts
import { PortalTarget } from 'frontile';

<template>
  {{outlet}}

  <PortalTarget class='relative z-20' />
</template>
```

### How a destination is chosen

`Portal` resolves its destination in this order:

1. `@renderInPlace={{true}}` — no portal at all, the content stays where it is written.
2. `@target` as an `Element` — that element.
3. `@target` as a string beginning with `#` — the element with that id. Any id HTML allows
   works, including ones that are not valid CSS identifiers (`#1foo`, `#my.target`).
4. `@target` as any other string — the nearest `PortalTarget` with a matching `@for`. The
   name is compared literally, so it too may contain characters a selector would choke on.
5. Otherwise, the nearest parent portal, unless `@appendToParentPortal={{false}}`.
6. Otherwise, the nearest **unnamed** `PortalTarget`.
7. Otherwise, `document.body`.

When the destination ends up being plain `document.body`, `Portal` wraps its content in a
`PortalTarget` for you, so portals nested inside it still have somewhere to go.

## Nesting Portals

Portals nest: an inner `Portal` renders into the destination of the outer one.

```gts preview
import { Portal, PortalTarget } from 'frontile';

<template>
  <div class='h-40 relative w-32'>
    <PortalTarget />
  </div>

  <Portal
    class='absolute w-content bg-neutral/50 left-0 p-4 border border-neutral-soft rounded'
  >
    First portal (Outer)
    <Portal
      class='absolute w-content bg-primary/50 border border-primary left-12 rounded'
    >
      Second portal (Inner)
      <Portal
        class='absolute w-content bg-danger/50 border border-danger left-16 rounded'
      >
        Last portal (Inner 2)
      </Portal>
    </Portal>
  </Portal>
</template>
```

## Rendering Inline

`@renderInPlace={{true}}` skips the portal entirely and renders the content where it is
written — useful for turning portalling off conditionally.

```gts preview
import { Portal } from 'frontile';

<template>
  <div class='p-4 border border-neutral-soft rounded'>
    <Portal @renderInPlace={{true}}>
      This content is rendered inline instead of a portal.
    </Portal>
  </div>
</template>
```

## Rendering Inside a Specific DOM Element

`@target` also accepts an element id prefixed with `#`, or an `Element` reference, for
destinations that are not `PortalTarget`s — a third-party container, for instance.

```gts preview
import { Portal } from 'frontile';

<template>
  <div id='target' class='border border-neutral-soft p-4'>
    Target Element
  </div>
  <Portal @target='#target'>
    <div class='p-4 border border-neutral-soft rounded shadow-md'>
      Rendered inside target element.
    </div>
  </Portal>
</template>
```

## Append to Parent Portal

By default a `Portal` appends to the parent portal when there is one. Set
`@appendToParentPortal={{false}}` to make it resolve a destination on its own instead, which
sends it to the nearest unnamed `PortalTarget`.

```gts preview
import { Portal, PortalTarget } from 'frontile';

<template>
  <PortalTarget />

  <Portal>
    Outer portal content
    <Portal @appendToParentPortal={{false}}>
      This content is rendered separately, not appended to the parent portal.
    </Portal>
  </Portal>
</template>
```

## Server-Side Rendering

Both components work under FastBoot. `Portal` resolves its destination from the owner's
document rather than the global `document`, so portalled content is present in the
server-rendered HTML.

## Accessibility

Neither component adds a role or any ARIA attribute — `PortalTarget` is a plain `div`, so
the semantics belong to whatever you render inside it. What they do change is DOM position,
and that has consequences:

- **Reading and tab order follow the destination, not the source.** Content written next to a
  button but portalled to the end of the page is announced and reached there. Place your
  application-level `PortalTarget` after the main content so overlay content comes last.
- **Focus management is not handled here.** `Portal` does not move, trap, or restore focus.
  For dialogs use `Modal`, `Drawer`, or `Overlay`, which handle focus, focus trapping, and
  the Escape key on top of `Portal`.
- **Keep the relationship explicit.** When portalled content describes a control that stays
  behind — a popover, a tooltip, an error message — wire it up with `aria-controls`,
  `aria-describedby`, or `aria-labelledby`, since proximity in the DOM no longer implies it.
- **Give a named target only one owner.** Two portals targeting the same name append in render
  order; for a slot that should hold one thing at a time, render one `Portal` at a time.

## API

### PortalTarget

**Element:** `HTMLElement`

**Arguments**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `for` | `string` | - | Name of this target, matched against a Portal's @target argument. When omitted, the target is unnamed: any Portal rendered below it that has no @target and no parent portal will render here. A named target is only used by portals that ask for it by name. |

**Blocks**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `default *` | `[]` | - |  |
### Portal

**Element:** `HTMLDivElement`

**Arguments**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `appendToParentPortal` | `boolean` | `true` |  |
| `renderInPlace` | `boolean` | `false` | Whether to render in place or in the specified/default destination |
| `target` | `string \| Element` | - | The target where to render the portal. There are 3 options: 1) Element object, 2) element id, 3) portal target name. For element id, string must be prefixed with #. If no value is passed in, we will render to the closest unnamed portal target, parent portal or document.body. |

**Blocks**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `default *` | `[]` | - |  |

---

# Tooltip

Source: /docs/components/overlays/tooltip.md

# Tooltip

A Tooltip shows a short, non-interactive hint next to whatever a user hovers or
keyboard-focuses. It is built on [Popover](./popover.md): reach for `Popover`
instead whenever the overlay needs to hold links, buttons, or anything else a
user must be able to interact with, because a tooltip's content is announced
through `aria-describedby` as a description of the trigger, not a region of its
own — interactive elements inside it are unreachable to assistive technology.

## Import

```js
import { Tooltip } from 'frontile';
```

## Usage

Pass `@content` for the common case of a plain-text tooltip, and put the
`trigger` modifier on the element the tooltip describes.

```gts preview
import { Tooltip } from 'frontile';
import { Button } from 'frontile';

<template>
  <Tooltip @content='Add to library' as |t|>
    <Button {{t.trigger}}>Add</Button>
  </Tooltip>
</template>
```

## Placement

```gts preview
import { Tooltip } from 'frontile';
import { Button } from 'frontile';

const placements = ['top', 'right', 'bottom', 'left'];

<template>
  <div class='flex flex-wrap gap-8 p-8'>
    {{#each placements as |placement|}}
      <Tooltip @content={{placement}} @placement={{placement}} as |t|>
        <Button {{t.trigger}}>{{placement}}</Button>
      </Tooltip>
    {{/each}}
  </div>
</template>
```

## Arrow

`@arrow={{true}}` renders an arrow pointing at the trigger.

```gts preview
import { Tooltip } from 'frontile';
import { Button } from 'frontile';

<template>
  <Tooltip @content='With an arrow' @arrow={{true}} as |t|>
    <Button {{t.trigger}}>Hover me</Button>
  </Tooltip>
</template>
```

## Rich content

Use the yielded `Content` block instead of `@content` when the tooltip needs
more than a single string. Passing both `@content` and a `Content` block
asserts in development — pick one.

```gts preview
import { Tooltip } from 'frontile';
import { Button } from 'frontile';
import { Kbd } from 'frontile';

<template>
  <Tooltip as |t|>
    <Button {{t.trigger}}>Keyboard shortcuts</Button>
    <t.Content>
      <p class='font-semibold'>Save</p>
      <p class='flex items-center gap-1'>
        <Kbd @keys='mod+s' @variant='inherit' @size='sm' />
        saves the current document.
      </p>
    </t.Content>
  </Tooltip>
</template>
```

## Color

```gts preview
import { Tooltip } from 'frontile';
import { Button } from 'frontile';

const intents = [
  'default',
  'primary',
  'secondary',
  'tertiary',
  'success',
  'warning',
  'danger'
];

<template>
  <div class='flex flex-wrap gap-8 p-8'>
    {{#each intents as |intent|}}
      <Tooltip @content={{intent}} @color={{intent}} as |t|>
        <Button {{t.trigger}}>{{intent}}</Button>
      </Tooltip>
    {{/each}}
  </div>
</template>
```

## Size

```gts preview
import { Tooltip } from 'frontile';
import { Button } from 'frontile';

const sizes = ['sm', 'md', 'lg'];

<template>
  <div class='flex flex-wrap gap-8 p-8'>
    {{#each sizes as |size|}}
      <Tooltip @content={{size}} @size={{size}} as |t|>
        <Button {{t.trigger}}>{{size}}</Button>
      </Tooltip>
    {{/each}}
  </div>
</template>
```

## Delays

`@openDelay` (default `200`ms) and `@closeDelay` (default `150`ms) control how
long the tooltip waits before showing and hiding. `@closeDelay` is also the
window the pointer has to cross the gap between the trigger and the tooltip
content, so setting it very low makes the tooltip effectively non-interactive.

These defaults are longer than the underlying `Popover`'s hover defaults
(`100`ms/`100`ms): a tooltip fires on every incidental mouse pass over its
trigger, so it waits a little longer before appearing to avoid flashing at a
user who was only moving the cursor across.

```gts preview
import { Tooltip } from 'frontile';
import { Button } from 'frontile';

<template>
  <Tooltip
    @content='Opens slowly, closes fast'
    @openDelay={{600}}
    @closeDelay={{0}}
    as |t|
  >
    <Button {{t.trigger}}>Hover and wait</Button>
  </Tooltip>
</template>
```

## Interactive content

By default, moving the pointer or keyboard focus off the trigger and onto the
tooltip's own content keeps it open — useful when the content is long enough
that a reader's cursor has to cross a gap to reach it. `@disableInteractive`
closes the tooltip as soon as the pointer leaves the trigger instead, without
waiting to see whether it lands on the content.

```gts preview
import { Tooltip } from 'frontile';
import { Button } from 'frontile';

<template>
  <div class='flex flex-wrap gap-8 p-8'>
    <Tooltip @content='You can hover this tooltip' as |t|>
      <Button {{t.trigger}}>Interactive (default)</Button>
    </Tooltip>

    <Tooltip
      @content='This one closes immediately'
      @disableInteractive={{true}}
      as |t|
    >
      <Button {{t.trigger}}>Not interactive</Button>
    </Tooltip>
  </div>
</template>
```

## Controlled

Pair `@isOpen` with `@onOpenChange` to drive the tooltip from your own state.
`@isOpen` only takes effect together with `@onOpenChange` — passing `@isOpen`
alone falls back to uncontrolled behavior.

Open the tooltip in response to an interaction or after the component has
mounted, not on the very first render: the trigger installs its floating-ui
anchor through a modifier, which only runs once the element exists, so forcing
`@isOpen={{true}}` before that happens throws.

```gts preview
import Component from '@glimmer/component';
import { tracked } from '@glimmer/tracking';
import { Tooltip } from 'frontile';
import { Button } from 'frontile';

export default class ControlledTooltipExample extends Component {
  @tracked isOpen = false;

  onOpenChange = (isOpen: boolean) => {
    this.isOpen = isOpen;
  };

  show = () => {
    this.isOpen = true;
  };

  <template>
    <Button @onPress={{this.show}} class='mr-4'>Show tooltip</Button>

    <Tooltip
      @content='Opened from outside'
      @isOpen={{this.isOpen}}
      @onOpenChange={{this.onOpenChange}}
      as |t|
    >
      <Button {{t.trigger}}>Trigger</Button>
    </Tooltip>
  </template>
}
```

## Imperative Controls

Besides `@isOpen`/`@onOpenChange`, the default block also yields `isOpen`, `open`, and
`close` directly, with no external state required. `open` and `close` drive the tooltip from
anywhere on the page — a button doesn't have to be the trigger itself — and `isOpen` reports
whether the tooltip is currently open.

```gts preview
import { Tooltip } from 'frontile';
import { Button } from 'frontile';

<template>
  <Tooltip @content='Hover me, then dismiss me from the button' as |t|>
    <Button {{t.trigger}} class='mr-4'>Trigger</Button>
    <Button @variant='outline' @onPress={{t.close}}>Close tooltip</Button>
    <p class='mt-2 text-sm'>{{if t.isOpen 'Open' 'Closed'}}</p>
  </Tooltip>
</template>
```

## Disabled

`@isDisabled={{true}}` still installs the trigger element, but skips wiring up the hover and
focus listeners that open the tooltip — so the tooltip never opens, and the trigger itself
renders exactly as you wrote it, whether or not it also carries a plain `disabled` attribute.
Toggling `@isDisabled` back to `false` at runtime re-installs the listeners immediately.

The common case is disabling the tooltip alongside a disabled trigger, so a hint about an
unavailable action doesn't pop up on hover.

```gts preview
import { Tooltip } from 'frontile';
import { Button } from 'frontile';

<template>
  <div class='flex flex-wrap gap-8 p-8'>
    <Tooltip @content='Save your changes' @isDisabled={{true}} as |t|>
      <Button {{t.trigger}} disabled>Save (disabled)</Button>
    </Tooltip>

    <Tooltip @content='Save your changes' as |t|>
      <Button {{t.trigger}}>Save (enabled)</Button>
    </Tooltip>
  </div>
</template>
```

## Accessibility

The `trigger` modifier marks up the element it's applied to as the tooltip's
description, and keeps it in sync as the tooltip opens and closes:

```
aria-describedby="<the content's id>"
```

The tooltip opens on mouse hover, and on keyboard `focus-visible` after
`@openDelay`. `Escape` closes it while it's open. The content itself carries
`role="tooltip"` and is never a tab stop (`tabindex="-1"`) — focus is never
moved into it, only the description relationship changes.

Touch has no equivalent: there is no long-press emulation, so anything said
only in a tooltip is invisible to a touch-only user. Make sure the same
information is available another way — in the trigger's own label, or
elsewhere on the page — rather than relying on the tooltip alone.

## API

### Tooltip

**Element:** `HTMLDivElement`

**Arguments**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `arrow` | `boolean` | `false` | Renders an arrow pointing at the trigger. |
| `class` | `string` | - | Custom class for the tooltip, merged with the theme's using Tailwind Merge. |
| `classes` | `SlotsToClasses<'base' \| 'arrow'>` | - | Class names for each slot, merged with the theme's. |
| `closeDelay` | `number` | `150` | Milliseconds before closing. Also the window the pointer has to cross the gap into the tooltip, so a very small value makes the tooltip effectively non-interactive. |
| `color` | `'neutral' \| 'primary' \| 'secondary' \| 'tertiary' \| 'success' \| 'warning' \| 'danger'` | `'neutral'` | The tooltip's semantic color role. The arrow inherits the body's background, so it follows the chosen intent automatically. |
| `content` | `string` | - | The tooltip's text. A shorthand for the common case; pass a Content block instead when the tooltip needs markup. Passing both asserts. |
| `didClose` | `() => void` | - | Callback when closing has finished, including any exit transition. |
| `disableInteractive` | `boolean` | `false` | Closes as soon as the pointer leaves the trigger, rather than letting it move onto the tooltip. |
| `flipOptions` | `{ mainAxis?: boolean; crossAxis?: boolean \| 'alignment'; fallbackPlacements?: Placement[]; fallbackStrategy?: 'bestFit' \| 'initialPlacement'; fallbackAxisSideDirection?: 'start' \| ... 1 more ... \| 'none'; ... 5 more ...; boundary?: Boundary; }` | - | Options for the floating-ui flip middleware, which moves the tooltip to the opposite side when it would overflow the viewport. Forwarded to the underlying Popover. |
| `isDisabled` | `boolean` | `false` | Installs the trigger but never opens. For a tooltip whose text is conditionally irrelevant. |
| `isOpen` | `boolean` | - | Whether the tooltip is open. Pair with onOpenChange to control it; leave it unset to let the tooltip manage its own state. Passing isOpen alone, without onOpenChange, falls back to uncontrolled behavior. |
| `middleware` | `{ name: string; options?: any; fn: (state: { placement: Placement; strategy: Strategy; x: number; y: number; initialPlacement: Placement; middlewareData: MiddlewareData; rects: ElementRects; platform: { ...; } &#x26; Platform; elements: Elements; }) => Promisable<...>; }[]` | - | Additional floating-ui middleware, for positioning behavior beyond what placement, offsetOptions, flipOptions, and shiftOptions cover. Forwarded to the underlying Popover. |
| `offsetOptions` | `OffsetOptions` | `8` | The gap, in pixels, between the trigger and the tooltip. The default leaves room for the arrow when @arrow is enabled. |
| `onOpenChange` | `(isOpen: boolean) => void` | - | Callback when the tooltip opens or closes, receiving the new state. |
| `openDelay` | `number` | `200` | Milliseconds before opening on hover or keyboard focus. |
| `placement` | `'top' \| 'top-start' \| 'top-end' \| 'right' \| 'right-start' \| 'right-end' \| 'bottom' \| 'bottom-start' \| 'bottom-end' \| 'left' \| 'left-start' \| 'left-end'` | `'top'` | The requested placement of the tooltip relative to its trigger. This is a preference, not a guarantee: the flip middleware may resolve it to the opposite side when there is no room for it in the requested spot. |
| `shiftOptions` | `{ mainAxis?: boolean; crossAxis?: boolean; rootBoundary?: RootBoundary; elementContext?: ElementContext; altBoundary?: boolean; padding?: Padding; limiter?: { ...; }; boundary?: Boundary; }` | - | Options for the floating-ui shift middleware, which nudges the tooltip along its axis to keep it in view. Forwarded to the underlying Popover. |
| `size` | `'sm' \| 'md' \| 'lg'` | `'md'` | The tooltip's size, which scales its padding and label text. |
| `strategy` | `Strategy` | `'absolute'` | The CSS positioning strategy, forwarded to the underlying Popover/floating-ui. |

**Blocks**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `default *` | `[{ trigger: ModifierLike<{ Element: HTMLElement; }>; Content: TooltipContent (PopoverContent, classNames, arrow, disableInteractive, hasContentArg bound); isOpen: boolean; open: () => void; close: () => void; }]` | - |  |

---

# Breadcrumbs

Source: /docs/components/navigation/breadcrumbs.md

# Breadcrumbs

An ordered trail of links ending in the current page, for showing where the
current page sits in a hierarchy.

Like [TabNav](./tab-nav), it does not use roving focus: every crumb is a
link, so each one stays individually reachable by <kbd>Tab</kbd> and the
arrow keys are left to the browser.

## Import

```js
import { Breadcrumbs } from 'frontile';
```

## Usage

The docs site has no routes for `Breadcrumbs` to link to, so every demo on
this page uses `@href` rather than `@route`. In an app with routes, prefer
`@route` (below). It derives the current crumb from the router for you.

A crumb with no link target at all is the current page: `<b.Item>` needs no
arguments to say "you are here."

```gts preview
import { Breadcrumbs } from 'frontile';

<template>
  <Breadcrumbs as |b|>
    <b.Item @href='/'>Home</b.Item>
    <b.Item @href='/library'>Library</b.Item>
    <b.Item>Data</b.Item>
  </Breadcrumbs>
</template>
```

`Breadcrumbs` has two authoring forms. The block form above gives full
control over each crumb; use it by default. The `@items` form, covered under
[Collapsing long trails](#collapsing-long-trails), renders the trail from a
plain array instead, which is worth it once the trail is long enough to
collapse automatically.

## Linking to routes

Pass `@route` (with `@model`, `@models`, or `@query` as needed) and `b.Item`
renders an Ember `LinkTo`, deriving its current state from the router. No
`@isCurrent` needed. The demo below isn't rendered, since the docs site has
no matching routes; it is here as reference.

```gts
import { Breadcrumbs } from 'frontile';

<template>
  <Breadcrumbs as |b|>
    <b.Item @route='library.index'>Library</b.Item>
    <b.Item @route='library.item' @model={{@item.id}}>{{@item.title}}</b.Item>
  </Breadcrumbs>
</template>
```

`@isCurrent` always wins over the router, in both directions. Pass it to
override a route crumb the router would otherwise mark current, or to force
one current that isn't.

## Collapsing long trails

Once a trail gets long, the middle can be collapsed behind an ellipsis
marker. There are two ways to get one, matching the two authoring forms.

### `@items` and `@maxItems`

Passing `@items` renders the trail from an array instead of from blocks, and
is what makes `@maxItems` meaningful. Yielded blocks can't be counted before
they render, so in the block form there's nothing for `@maxItems` to divide.
Once `@items.length` exceeds `@maxItems`, the middle collapses into an
ellipsis marker that announces how many crumbs it stands in for. It is the
same marker `b.Ellipsis` renders when you place one by hand, below.

```gts preview
import { Breadcrumbs } from 'frontile';

const trail = [
  { label: 'Home', href: '/' },
  { label: 'Library', href: '/library' },
  { label: 'Data', href: '/library/data' },
  { label: 'Reports', href: '/library/data/reports' },
  { label: 'Q3' }
];

<template>
  <Breadcrumbs @items={{trail}} @maxItems={{3}} />
</template>
```

`@itemsBeforeCollapse` and `@itemsAfterCollapse` (each defaulting to `1`)
move where the split happens:

```gts preview
import { Breadcrumbs } from 'frontile';

const trail = [
  { label: 'Home', href: '/' },
  { label: 'Library', href: '/library' },
  { label: 'Data', href: '/library/data' },
  { label: 'Reports', href: '/library/data/reports' },
  { label: 'Q3' }
];

<template>
  <Breadcrumbs
    @items={{trail}}
    @maxItems={{4}}
    @itemsBeforeCollapse={{2}}
    @itemsAfterCollapse={{1}}
  />
</template>
```

Each entry in `@items` takes `label` (its text) plus the same arguments as
`b.Item`: `route`/`model`/`models`/`query` or `href`, `isCurrent`,
`isDisabled`. A crumb with neither `route` nor `href` is the current page,
exactly as in the block form.

### A manual `<b.Ellipsis />`

In the block form, you place the ellipsis yourself. That helps when the trail
doesn't come from a flat array, or the collapse point isn't a simple count:

```gts preview
import { Breadcrumbs } from 'frontile';

<template>
  <Breadcrumbs as |b|>
    <b.Item @href='/'>Home</b.Item>
    <b.Ellipsis @hiddenCount={{2}} />
    <b.Item>Q3</b.Item>
  </Breadcrumbs>
</template>
```

`@hiddenCount` drives the visually-hidden announcement ("2 more levels"); pass
it whenever you know how many crumbs the marker stands in for. Omit it and
the announcement falls back to an uncounted "More levels" rather than making
you count your own crumbs.

Passing a block replaces the glyph and takes over the announcement entirely.
This is where a `Dropdown` listing the hidden crumbs goes. The block
yields `hiddenCount` and `hiddenItems` (empty unless you pass `@hiddenItems`),
so you can render the crumbs it stands in for:

```gts preview
import { Breadcrumbs } from 'frontile';

const hidden = [{ label: 'Library' }, { label: 'Data' }];

<template>
  <Breadcrumbs as |b|>
    <b.Item @href='/'>Home</b.Item>
    <b.Ellipsis @hiddenItems={{hidden}} as |e|>
      <button type='button'>
        {{e.hiddenItems.length}}
        hidden &hellip;
      </button>
    </b.Ellipsis>
    <b.Item>Q3</b.Item>
  </Breadcrumbs>
</template>
```

In the `@items` form, the same two blocks are available as named blocks:
`:item` to render every crumb yourself, and `:ellipsis` to render the
auto-placed marker. `@maxItems` still computes the split while you control
the markup:

```gts
import { Breadcrumbs } from 'frontile';

<template>
  <Breadcrumbs @items={{@trail}} @maxItems={{3}}>
    <:item as |ctx|>
      <li class={{ctx.itemClass}}>
        <span class={{ctx.linkClass}}>{{ctx.item.label}}</span>
      </li>
    </:item>
    <:ellipsis as |e|>
      <button type='button'>{{e.hiddenCount}} hidden</button>
    </:ellipsis>
  </Breadcrumbs>
</template>
```

## Custom separator

`@separator` replaces the chevron glyph between crumbs with any component:

```gts preview
import { Breadcrumbs } from 'frontile';

const Slash = <template><span>/</span></template>;

<template>
  <Breadcrumbs @separator={{Slash}} as |b|>
    <b.Item @href='/'>Home</b.Item>
    <b.Item @href='/library'>Library</b.Item>
    <b.Item>Data</b.Item>
  </Breadcrumbs>
</template>
```

## Sizes, colors, and underline

`@size` (`sm` / `md` / `lg`, default `md`) scales the text and separator
glyph. `@underline` (`always` / `hover` / `none`, default `hover`) controls when
a crumb's link is underlined. The current crumb is never underlined in any
mode, since it doesn't go anywhere.

`@color` picks the hover and current-page ink, and takes `neutral` (the
default), `primary` or `danger`. That is three categories where most themed
components offer seven. The other four are fill colours, designed to carry
`text-on-*` text on top of them the way `Pagination`'s active chip does. A
breadcrumb has no fill, so its colour lands on the text itself, and as ink on
a light surface those categories fall well below the contrast a reader needs:
`success` reaches only 2.3:1 at its darkest level, against the 4.5:1 WCAG AA
asks for body text.

```gts preview
import { Breadcrumbs } from 'frontile';

<template>
  <div class='demo-stack items-start'>
    <Breadcrumbs @size='sm' @color='primary' as |b|>
      <b.Item @href='/'>Home</b.Item>
      <b.Item>Small, primary</b.Item>
    </Breadcrumbs>

    <Breadcrumbs @size='lg' @color='danger' @underline='always' as |b|>
      <b.Item @href='/'>Home</b.Item>
      <b.Item>Large, danger, always underlined</b.Item>
    </Breadcrumbs>
  </div>
</template>
```

## Disabled crumbs

`@isDisabled` drops the `href` as well as marking the crumb `aria-disabled`.
An anchor can't be natively disabled, so removing the href is what actually
stops navigation. It only affects a linked crumb; an unlinked crumb (no
`@route` or `@href`) never receives `aria-disabled`, since it isn't a link to
begin with.

```gts preview
import { Breadcrumbs } from 'frontile';

<template>
  <Breadcrumbs as |b|>
    <b.Item @href='/'>Home</b.Item>
    <b.Item @href='/library' @isDisabled={{true}}>Library</b.Item>
    <b.Item>Data</b.Item>
  </Breadcrumbs>
</template>
```

## Bring your own link component

`b` also yields `itemClass`, `linkClass`, `separatorClass`, and `setupItem`
directly, for a link component other than `b.Item`: `ember-link`, or a custom
`<AppLink>`. Apply `linkClass` to the link's class, and `{{b.setupItem
isCurrent}}` to its element, passing a boolean for whether it's the current
crumb. It then gets the same theme classes and ARIA as `b.Item`. Wrap it in an
`<li>` with `itemClass`, and add the separator yourself with `separatorClass`:

```gts
import { Breadcrumbs } from 'frontile';

<template>
  <Breadcrumbs as |b|>
    <li class={{b.itemClass}}>
      <a href='/library' class={{b.linkClass}} {{b.setupItem false}}>
        Library
      </a>
      <span class={{b.separatorClass}} aria-hidden='true'>/</span>
    </li>
    <li class={{b.itemClass}}>
      <span class={{b.linkClass}} {{b.setupItem true}}>Data</span>
    </li>
  </Breadcrumbs>
</template>
```

## Accessibility

`Breadcrumbs` renders a `<nav>` landmark with an accessible name from
`@label` (default `'Breadcrumb'`), wrapping an `<ol>`, since the trail is an
ordered list. Every crumb stays in the natural tab order; there is no roving
`tabindex` and no keyboard handling beyond ordinary link navigation.

The current crumb carries `aria-current="page"` and is rendered as a
`<span>`, not a link, since it doesn't go anywhere. `Breadcrumbs.Item`
derives current from, in order: an explicit `@isCurrent`; the router, for a
`@route` crumb; then the fallback that a crumb with no link target at all is
the page you're on. Only the last statically-current crumb keeps
`aria-current`, since two would be invalid. `Breadcrumbs` warns if `@items`
produces more than one.

A separator follows every crumb, including the last, where it is hidden by
CSS rather than omitted. It carries `aria-hidden="true"` either way, so it
never reaches assistive technology.

An ellipsis marker with no block carries `aria-hidden="true"` on its glyph
and a visually-hidden announcement ("N more levels", or "More levels" without
a count). Supplying a block to `b.Ellipsis` suppresses that built-in
announcement, since the block's own content (typically a button that opens a
menu) carries its own accessible name.

## API

### Breadcrumbs

An ordered trail of links ending in the current page.

Like TabNav, it deliberately does not use roving focus: these are
links, so every one of them stays individually reachable by Tab and the
arrow keys are left to the browser.

**Element:** `HTMLElement`

**Arguments**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `classes` | `SlotsToClasses<'base' \| 'item' \| 'separator' \| 'list' \| 'link' \| 'ellipsis'>` | - | Class names for each slot of the component, merged with the theme's. |
| `color` | `'neutral' \| 'primary' \| 'danger'` | `'neutral'` | The colour of the hover and current-page ink. Three categories rather than the usual seven: the others are fill colours, meant to carry text-on-* on top of them, and as ink on a light surface they fall below the contrast a reader needs. See breadcrumbs.ts in the theme for the measurements. |
| `items` | `BreadcrumbsItemData[]` | - | Renders the trail from an array instead of from blocks. Passing it is what makes @maxItems meaningful -- yielded blocks cannot be counted before they render, so in the block form there is nothing for it to divide. |
| `itemsAfterCollapse` | `number` | `1` |  |
| `itemsBeforeCollapse` | `number` | `1` |  |
| `label` | `string` | `'Breadcrumb'` | Accessible name for the navigation landmark. |
| `maxItems` | `number` | - | Collapses the middle of the trail once there are more crumbs than this. @items form only. |
| `separator` | `ComponentLike<{ Element: SVGElement; }>` | `ChevronRightIcon` | Replaces the separator glyph. A component argument rather than a named block because the separator is rendered inside each <li>, which Item owns -- a named block on this component cannot be handed down to a child. |
| `size` | `'sm' \| 'md' \| 'lg'` | `'md'` |  |
| `underline` | `'none' \| 'always' \| 'hover'` | `'hover'` |  |

**Blocks**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `default *` | `[{ Item: BreadcrumbsItem (itemClass, linkClass, separatorClass, separator, setupItem bound); Ellipsis: BreadcrumbsEllipsis (itemClass, ellipsisClass, separatorClass, separator bound); itemClass: string; linkClass: string; separatorClass: string; setupItem: Breadcrumbs['setupItem']; }]` | - |  |
| `item *` | `[BreadcrumbsItemContext]` | - |  |
| `ellipsis *` | `[{ hiddenCount?: number; hiddenItems: BreadcrumbsItemData[]; }]` | - |  |
### BreadcrumbsItem

One crumb: its <li>, the crumb itself, and the separator that follows it.

The separator is rendered here rather than by the root, and hidden on the
last crumb by CSS. That is what lets both authoring forms work without
either one knowing an item's position.

**Element:** `HTMLElement`

**Arguments**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `itemClass *` | `string` | - | Supplied by Breadcrumbs. Not part of the public API. _(internal)_ |
| `linkClass *` | `string` | - | _(internal)_ |
| `separatorClass *` | `string` | - | _(internal)_ |
| `setupItem *` | `ModifierLike<{ Element: HTMLElement; Args: { Positional: [boolean]; }; }>` | - | _(internal)_ |
| `class` | `string` | - | Class names appended to this crumb's theme classes. |
| `href` | `string` | - | Renders a plain anchor. |
| `isCurrent` | `boolean` | - | Overrides the current-page state. Wins over every other rule. |
| `isDisabled` | `boolean` | `false` | Marks the crumb as disabled. An anchor cannot be natively disabled, so the href is dropped as well -- aria-disabled alone still leaves it clickable. Only affects a linked crumb: an unlinked crumb (no @route or @href) renders as a <span> and never receives aria-disabled or data-disabled regardless of this arg. |
| `model` | `unknown` | - | A single dynamic segment for @route. |
| `models` | `unknown[]` | - | Dynamic segments for @route. |
| `query` | `Record<string, unknown>` | - | Query params for @route. |
| `route` | `string` | - | Renders a LinkTo for this route and derives the current state from the router. Omit it (and pass @href) to stay entirely router-free. |
| `separator` | `ComponentLike<{ Element: SVGElement; }>` | - | _(internal)_ |

**Blocks**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `default *` | `[]` | - |  |
### BreadcrumbsEllipsis

The gap marker standing in for a run of crumbs.

It renders its own <li> including a separator, structurally identical to
what Item renders -- a bare <span> would fall outside the
group-last/item:hidden scheme that hides the trailing separator, and the
trail would end in a dangling chevron whenever an ellipsis came last.

**Element:** `HTMLElement`

**Arguments**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `ellipsisClass *` | `string` | - | _(internal)_ |
| `itemClass *` | `string` | - | _(internal)_ |
| `separatorClass *` | `string` | - | _(internal)_ |
| `class` | `string` | - | Class names appended to this marker's theme classes. |
| `hiddenCount` | `number` | - | Drives the visually-hidden announcement. The @items form passes it; in the block form an author may supply it, and without it the announcement falls back to an uncounted one rather than making the author count their own crumbs. |
| `hiddenItems` | `BreadcrumbsItemData[]` | - | The crumbs this marker stands in for. Yielded straight back to the block. |
| `separator` | `ComponentLike<{ Element: SVGElement; }>` | - | _(internal)_ |

**Blocks**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `default *` | `[{ hiddenCount?: number; hiddenItems: BreadcrumbsItemData[]; }]` | - | Replaces the glyph. This is where a Dropdown goes. |

---

# ExternalLink

Source: /docs/components/navigation/external-link.md

# ExternalLink

A link to another site, marked with an external-link icon.

It opens a new tab, adds `rel="noopener noreferrer"`, and appends visually
hidden text announcing the new tab — so a link that shows the icon always
behaves the way the icon promises. For in-app navigation use
[TabNav](./tab-nav) or Ember's `LinkTo`.

## Import

```js
import { ExternalLink } from 'frontile';
```

## Usage

Pass `@href`. Everything else has a default.

```gts preview
import { ExternalLink } from 'frontile';

<template>
  <div class='not-prose text-neutral-strong p-2'>
    <ExternalLink @href='https://emberjs.com'>Ember.js</ExternalLink>
  </div>
</template>
```

The anchor is `display: inline`, so a link wraps mid-phrase inside a paragraph
like any other. The icon can end up alone on the next line when the break falls
right after the last word.

```gts preview
import { ExternalLink } from 'frontile';

<template>
  <div class='not-prose text-neutral-strong max-w-xs p-2'>
    <p>
      Frontile is built on
      <ExternalLink @href='https://emberjs.com'>Ember Octane</ExternalLink>
      and styled with
      <ExternalLink @href='https://tailwindcss.com'>Tailwind CSS</ExternalLink>.
    </p>
  </div>
</template>
```

## Color

The link inherits its color and font size from the surrounding text. Tint it
with a text utility on `@class`.

```gts preview
import { ExternalLink } from 'frontile';

<template>
  <div class='not-prose flex flex-col items-start gap-3 p-2'>
    <span class='text-neutral-strong'>
      <ExternalLink @href='https://emberjs.com'>Inherited color</ExternalLink>
    </span>
    <ExternalLink @href='https://emberjs.com' @class='text-primary'>
      Primary
    </ExternalLink>
    <ExternalLink @href='https://emberjs.com' @class='text-danger'>
      Danger
    </ExternalLink>
    <p class='text-neutral text-sm'>
      The icon scales with the text, so
      <ExternalLink @href='https://emberjs.com'>a small link</ExternalLink>
      gets a small icon.
    </p>
  </div>
</template>
```

## Underline

```gts preview
import { ExternalLink } from 'frontile';

<template>
  <div
    class='not-prose text-neutral-strong flex flex-col items-start gap-3 p-2'
  >
    <ExternalLink @href='https://emberjs.com'>
      Always underlined (default)
    </ExternalLink>
    <ExternalLink @href='https://emberjs.com' @underline='hover'>
      Underlined on hover
    </ExternalLink>
    <ExternalLink @href='https://emberjs.com' @underline='none'>
      Never underlined
    </ExternalLink>
  </div>
</template>
```

## Icon placement

```gts preview
import { ExternalLink } from 'frontile';

<template>
  <div
    class='not-prose text-neutral-strong flex flex-col items-start gap-3 p-2'
  >
    <ExternalLink @href='https://emberjs.com'>Icon at the end (default)</ExternalLink>
    <ExternalLink @href='https://emberjs.com' @iconPlacement='start'>
      Icon at the start
    </ExternalLink>
  </div>
</template>
```

Pass `@showIcon={{false}}` to drop the icon. The new tab, the `rel`, and the
screen-reader announcement stay.

```gts preview
import { ExternalLink } from 'frontile';

<template>
  <div class='not-prose text-neutral-strong p-2'>
    <ExternalLink @href='https://emberjs.com' @showIcon={{false}}>
      No icon
    </ExternalLink>
  </div>
</template>
```

## Custom icon

The `:icon` block replaces the built-in glyph and keeps its size and spacing.
Named blocks require an explicit `:default` block for the link text.

```gts preview
import { ExternalLink } from 'frontile';
import { ShareIcon } from 'site/components/icons';

<template>
  <div class='not-prose text-neutral-strong p-2'>
    <ExternalLink @href='https://emberjs.com'>
      <:default>Custom icon</:default>
      <:icon><ShareIcon /></:icon>
    </ExternalLink>
  </div>
</template>
```

## Target and rel

`@target` defaults to `_blank`, and `rel` is then `noopener noreferrer`.
Setting `@target='_self'` navigates in place: no `rel` is emitted and the
new-tab announcement is dropped, since neither would be true.

`@rel` replaces the default outright — include `noopener noreferrer` yourself
if the link still opens a new tab.

```gts preview
import { ExternalLink } from 'frontile';

<template>
  <div
    class='not-prose text-neutral-strong flex flex-col items-start gap-3 p-2'
  >
    <ExternalLink @href='https://emberjs.com'>New tab (default)</ExternalLink>
    <ExternalLink @href='https://emberjs.com' @target='_self'>
      Same tab
    </ExternalLink>
    <ExternalLink
      @href='https://emberjs.com'
      @rel='noopener noreferrer nofollow'
    >
      With nofollow
    </ExternalLink>
  </div>
</template>
```

## Accessibility

The icon is `aria-hidden`, so its meaning is carried by visually hidden text
after the link label: a screen reader announces "Ember.js (opens in a new tab)".
Translate it with `@newTabLabel`, or pass an empty string to remove it when the
surrounding copy already says so.

```gts preview
import { ExternalLink } from 'frontile';

<template>
  <div
    class='not-prose text-neutral-strong flex flex-col items-start gap-3 p-2'
  >
    <ExternalLink
      @href='https://emberjs.com'
      @newTabLabel='(abre em uma nova aba)'
    >
      Translated announcement
    </ExternalLink>
    <ExternalLink @href='https://emberjs.com' @newTabLabel=''>
      No announcement
    </ExternalLink>
  </div>
</template>
```

The announcement follows `@target`: a `_self` link never gets it. Give the link
text that reads on its own — "Ember.js" rather than "click here" — since screen
reader users often navigate by a list of links stripped of surrounding prose.

Keyboard behaviour is a plain anchor's: <kbd>Tab</kbd> to focus, <kbd>Enter</kbd>
to follow. Focus shows the standard focus ring.

## API

### ExternalLink

A link to another site.

It opens a new tab, marks itself with an external-link glyph, protects the
opener with rel="noopener noreferrer", and tells assistive technology that
a new tab is coming — so the four cannot drift apart. For in-app navigation
use TabNav or Ember's LinkTo.

**Element:** `HTMLAnchorElement`

**Arguments**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `href *` | `string` | - | The absolute URL to link to. |
| `class` | `string` | - | Custom class name, it will override the default ones using Tailwind Merge library. |
| `classes` | `SlotsToClasses<'icon' \| 'base'>` | - | Custom CSS classes for styling the individual slots: base for the anchor, icon for the glyph wrapper. |
| `iconPlacement` | `'start' \| 'end'` | `'end'` | Which side of the text the glyph sits on. |
| `newTabLabel` | `string` | `'(opens in a new tab)'` | The visually-hidden text announced when the link opens a new tab. Pass an empty or blank string to suppress it. |
| `rel` | `string` | - | Replaces the default rel. Left off, noopener noreferrer is applied whenever the link opens a new browsing context. |
| `showIcon` | `boolean` | `true` | Set to false to drop the glyph. The target, rel and new-tab announcement are unaffected. |
| `target` | `'_blank' \| '_self' \| '_parent' \| '_top' \| (string &#x26; {})` | `'_blank'` | The browsing context to open in. Any frame name is accepted; the four keywords are listed so editors can complete them. |
| `underline` | `'none' \| 'always' \| 'hover'` | `'always'` |  |

**Blocks**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `default *` | `[]` | - | The link text. |
| `icon *` | `[]` | - | Replaces the built-in glyph, keeping its size and spacing. |

---

# Pagination

Source: /docs/components/navigation/pagination.md

# Pagination

A row of controls for moving through a paged list — page chips, previous/next,
and an optional summary of the current range. Reach for it whenever a list is
too large to show at once and the user benefits from jumping to a specific
page, rather than only scrolling further into an infinite feed.

## Import

```js
import { Pagination } from 'frontile';
```

## Usage

`@total` is the only argument the shortest working control needs: pass the
item count and `Pagination` derives the page count itself, tracks the current
page, and needs no `@onChange`.

```gts preview
import { Pagination } from 'frontile';

<template><Pagination @total={{120}} /></template>
```

## Anatomy

Pagination renders its previous button, page items, and next button automatically. Two
optional named blocks let you extend or replace that structure:

| Block        | Purpose                                                                         |
| ------------ | ------------------------------------------------------------------------------- |
| `<:summary>` | Adds a result-range summary using the yielded `from`, `to`, and `total` values. |
| `<:item>`    | Replaces each page item while preserving Pagination's windowing calculations.   |

Use the default items for button-based navigation. When rendering links through `<:item>`,
provide the appropriate URL and disabled semantics described in [Disabled](#disabled).

## Controlled and uncontrolled

The mode is decided by whether `@page` is _passed_, not by what it holds —
the same rule [`SegmentedControl`](../buttons/segmented-control.md) uses for `@value`.

Without `@page` the control is uncontrolled: it tracks the current page
itself, seeded from `@defaultPage`, and `@onChange` still fires on every
navigation so you can observe the page without owning it.

```gts preview
import { Pagination } from 'frontile';

<template><Pagination @total={{120}} @defaultPage={{3}} /></template>
```

Passing `@page` makes it controlled: the rendered page then only ever
reflects what you pass, so pair it with `@onChange` and update your own
state. `@defaultPage` is ignored in this mode.

```gts preview
import Component from '@glimmer/component';
import { tracked } from '@glimmer/tracking';
import { Pagination } from 'frontile';

export default class Example extends Component {
  @tracked page = 1;

  onChange = (page: number): void => {
    this.page = page;
  };

  <template>
    <Pagination
      @total={{120}}
      @page={{this.page}}
      @onChange={{this.onChange}}
    />
  </template>
}
```

## Page count

`@total` is an item count, not a page count — `@pageSize` divides it, so
`totalPages` is `ceil(total / pageSize)`. A `@total` of 45 with the default
`@pageSize` of 10 renders 5 pages.

```gts preview
import { Pagination } from 'frontile';

<template><Pagination @total={{45}} @pageSize={{10}} /></template>
```

## Window size

`@siblingCount` sets how many page chips show on either side of the current
page. The first and last pages are always pinned, and that boundary is not
configurable.

The window keeps a constant number of slots as the page moves, so the row
never reflows as you page through — a chip near the middle of a long list
takes exactly as much space as one at either end.

```gts preview collapsible
import Component from '@glimmer/component';
import { tracked } from '@glimmer/tracking';
import { Pagination } from 'frontile';

export default class Example extends Component {
  @tracked page = 10;

  onChange = (page: number): void => {
    this.page = page;
  };

  <template>
    <div class='flex flex-col items-start gap-3'>
      <Pagination
        @total={{200}}
        @siblingCount={{0}}
        @page={{this.page}}
        @onChange={{this.onChange}}
        aria-label='Sibling count 0'
      />
      <Pagination
        @total={{200}}
        @siblingCount={{1}}
        @page={{this.page}}
        @onChange={{this.onChange}}
        aria-label='Sibling count 1'
      />
      <Pagination
        @total={{200}}
        @siblingCount={{2}}
        @page={{this.page}}
        @onChange={{this.onChange}}
        aria-label='Sibling count 2'
      />
    </div>
  </template>
}
```

## Edge controls

`@showEdges` adds jump-to-first and jump-to-last controls at the ends of the
row, for a list long enough that reaching either end by paging through
siblings would take a while.

```gts preview
import { Pagination } from 'frontile';

<template>
  <Pagination @total={{500}} @defaultPage={{10}} @showEdges={{true}} />
</template>
```

## Previous and next only

Set `@showPages={{false}}` for compact page-number navigation with no page
chips—just previous and next. The component still uses `@total` and
`@pageSize` to determine when those controls are disabled.

```gts preview
import { Pagination } from 'frontile';

<template><Pagination @total={{120}} @showPages={{false}} /></template>
```

## Summary

Providing the `<:summary>` block adds a row reporting the current range,
yielding `from`, `to`, `total`, `page`, and `totalPages`. It also switches the
layout to push the controls to the far edge, since there's now something to
justify the row against.

```gts preview
import { Pagination } from 'frontile';

<template>
  <Pagination @total={{120}} @pageSize={{10}} @defaultPage={{2}}>
    <:summary as |s|>
      Showing
      {{s.from}}-{{s.to}}
      of
      {{s.total}}
    </:summary>
  </Pagination>
</template>
```

## Links

The `<:item>` block is the deep-linking escape hatch: it replaces the page
chips with your own markup — a `LinkTo`, an anchor with a real `href` — so
each page is a navigable URL rather than a button that only calls
`@onChange`. Previous and next remain buttons in this mode; only the page
chips are replaced.

The block yields `page`, `isActive`, `classNames` (the same classes the
built-in chip would use), and `setupItem`, a modifier that writes
`data-active` and `aria-current="page"` onto whatever element you apply it
to.

```gts preview
import { Pagination } from 'frontile';

<template>
  <Pagination @total={{50}} @defaultPage={{2}}>
    <:item as |i|>
      <a
        href='/results?page={{i.page}}'
        class={{i.classNames}}
        {{i.setupItem i.isActive}}
      >{{i.page}}</a>
    </:item>
  </Pagination>
</template>
```

## Sizes

```gts preview
import { Pagination } from 'frontile';

<template>
  <div class='flex flex-col items-start gap-3'>
    <Pagination @total={{50}} @size='sm' aria-label='Small' />
    <Pagination @total={{50}} @size='md' aria-label='Medium' />
    <Pagination @total={{50}} @size='lg' aria-label='Large' />
  </div>
</template>
```

## Colors

`@color` colors the active page chip's fill.

```gts preview collapsible
import { Pagination } from 'frontile';

<template>
  <div class='flex flex-col items-start gap-3'>
    <Pagination
      @total={{50}}
      @defaultPage={{2}}
      @color='neutral'
      aria-label='Default intent'
    />
    <Pagination
      @total={{50}}
      @defaultPage={{2}}
      @color='primary'
      aria-label='Primary intent'
    />
    <Pagination
      @total={{50}}
      @defaultPage={{2}}
      @color='secondary'
      aria-label='Secondary intent'
    />
    <Pagination
      @total={{50}}
      @defaultPage={{2}}
      @color='tertiary'
      aria-label='Tertiary intent'
    />
    <Pagination
      @total={{50}}
      @defaultPage={{2}}
      @color='success'
      aria-label='Success intent'
    />
    <Pagination
      @total={{50}}
      @defaultPage={{2}}
      @color='warning'
      aria-label='Warning intent'
    />
    <Pagination
      @total={{50}}
      @defaultPage={{2}}
      @color='danger'
      aria-label='Danger intent'
    />
  </div>
</template>
```

## Disabled

`@isDisabled` disables every control in the row.

For the component's own page chips and prev/next buttons, this sets a real
`disabled` attribute, so those controls are inert. An element you
supply through `<:item>` — typically an `<a href>` — has no `disabled`
attribute to set, so only the pointer is blocked; the element stays
keyboard-reachable and `Enter`-activatable. If you render your own links,
handle the disabled state on them too, for example by dropping the `href`,
the same way [`TabNav`](./tab-nav) disables an anchor.

```gts preview
import { Pagination } from 'frontile';

<template>
  <Pagination @total={{50}} @defaultPage={{3}} @isDisabled={{true}} />
</template>
```

## Accessibility

`Pagination` renders a `<nav>` landmark, named by `@label` (defaulting to
`'pagination'`) — set it explicitly when a page has more than one pagination
control. The active page chip carries `aria-current="page"`; every other
chip carries none.

The ellipsis marking a gap in the page row is `aria-hidden`, with a visually
hidden "More pages" label so screen readers still get a name for it.

Every control — previous, next, the edge jumps, and each page chip — stays
individually reachable by <kbd>Tab</kbd>, with no roving `tabindex`. These
are navigation targets rather than a composite widget, so each one is its own
stop rather than being grouped under a single tab-managed focus point.

## API

### Pagination

A row of controls for moving through a paged list.

It deliberately does not use rovingFocus: these are navigation
targets, not a composite widget, so every control stays individually
reachable by Tab. The ARIA tabs pattern does not apply, and applying it
would remove destinations from the tab order for no gain -- the same
reasoning TabNav documents.

**Element:** `HTMLElement`

**Arguments**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `classes` | `SlotsToClasses<'base' \| 'item' \| 'list' \| 'ellipsis' \| 'summary' \| 'page' \| 'prev' \| 'next'>` | - | Class names for each slot of the component, merged with the theme's. |
| `color` | `'neutral' \| 'primary' \| 'secondary' \| 'tertiary' \| 'success' \| 'warning' \| 'danger'` | `'neutral'` | The colour of the active page chip. |
| `defaultPage` | `number` | `1` | The page to start on when uncontrolled. Ignored in controlled mode. |
| `isDisabled` | `boolean` | `false` | Disables every control. |
| `label` | `string` | `'pagination'` | Accessible name for the nav landmark. Worth setting when a page has more than one pagination on it. |
| `onChange` | `(page: number) => void` | - | Called with the new page on every navigation, in both modes. Never called with an out-of-range page, and never called when the page would not change. |
| `page` | `number` | - | The current page, 1-based. Passing this argument at all puts the component in controlled mode: the rendered page then only ever reflects what you pass, so pair it with @onChange and update your own state. Omit it entirely to let the component track the page itself, seeded by @defaultPage. |
| `pageSize` | `number` | `10` | Items shown per page. Values below 1 are treated as 1. |
| `showEdges` | `boolean` | `false` | Adds jump-to-first and jump-to-last controls at the ends of the row. |
| `showPages` | `boolean` | `true` | Set to false for compact page-number navigation with previous and next controls but no page chips. @total and @pageSize still determine the first and last pages. |
| `siblingCount` | `number` | `1` | How many page chips to show either side of the current one. The first and last pages are always shown; that boundary is not configurable. |
| `size` | `'sm' \| 'md' \| 'lg'` | `'md'` |  |
| `total` | `number` | `0` | Total number of items across all pages -- an item count, not a page count. @pageSize divides it. This is what lets the summary block be handed a real item range instead of making the caller compute one. |

**Blocks**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `summary` | `[PaginationSummary]` | - |  |
| `item` | `[PaginationItemContext]` | - |  |

---

# TabNav

Source: /docs/components/navigation/tab-nav.md

# TabNav

A navigation bar styled like [Tabs](./tabs), for links that change the page.

Unlike `Tabs`, every link stays individually reachable by <kbd>Tab</kbd> and
the arrow keys are left to the browser — the ARIA tabs pattern covers in-page
panel switching, not navigation. The active link is marked with
`aria-current="page"`, which Ember's `LinkTo` does not set on its own.

## Import

```js
import { TabNav } from 'frontile';
```

## Usage

The docs site has no routes for `TabNav` to link to, so every demo on this
page uses `@href` and `@isActive` directly rather than `@route`. In an app
with routes, `@route` (below) is the tier to reach for — it derives
`@isActive` from the router for you.

```gts preview collapsible
import Component from '@glimmer/component';
import { tracked } from '@glimmer/tracking';
import { on } from '@ember/modifier';
import { fn } from '@ember/helper';
import { TabNav } from 'frontile';

export default class Example extends Component {
  @tracked current = 'account';

  isCurrent = (name: string): boolean => this.current === name;

  // No router in this demo, so a plain click stands in for a route
  // transition -- `preventDefault` keeps the `#` href from touching the URL.
  select = (name: string, event: MouseEvent): void => {
    event.preventDefault();
    this.current = name;
  };

  <template>
    <div class='demo-stack items-center'>
      <TabNav @label='Settings' as |nav|>
        <nav.Item
          @href='#account'
          @isActive={{this.isCurrent 'account'}}
          {{on 'click' (fn this.select 'account')}}
        >
          Account
        </nav.Item>
        <nav.Item
          @href='#security'
          @isActive={{this.isCurrent 'security'}}
          {{on 'click' (fn this.select 'security')}}
        >
          Security
        </nav.Item>
        <nav.Item
          @href='#billing'
          @isActive={{this.isCurrent 'billing'}}
          {{on 'click' (fn this.select 'billing')}}
        >
          Billing
        </nav.Item>
      </TabNav>
    </div>
  </template>
}
```

## Linking to routes

Pass `@route` (with `@models`, `@model`, or `@query` as needed) and
`nav.Item` renders an Ember `LinkTo` and derives `@isActive` from the router
itself — no `@isActive` needed. This tier isn't rendered on this page, since
the docs site has no matching routes; it is shown here as reference.

```gts
import { TabNav } from 'frontile';

<template>
  <TabNav @label='Settings' as |nav|>
    <nav.Item @route='settings.account'>Account</nav.Item>
    <nav.Item @route='settings.security'>Security</nav.Item>
    <nav.Item @route='settings.billing'>Billing</nav.Item>
  </TabNav>
</template>
```

`@isActive` always wins over anything derived from the router, so it can
still override a `@route` item when needed.

The router's `isActive` check is a prefix match: a route also counts as active
while any of its descendant routes are active. So `@route='settings'` and
`@route='settings.account'` in the same list are both marked active while on
`settings.account` — not just the more specific one. Pass an explicit
`@isActive` on the parent item (e.g. comparing the current route name exactly)
if you need only the leaf to light up.

## Bring your own link component

`nav` also yields `itemClass` and `setupItem` directly, for a link
component other than `nav.Item` — `ember-link`, a custom `<AppLink>`. Apply
`itemClass` to the link's class and `{{nav.setupItem}}` (with a boolean for
whether the link is active) to its element, and it gets the same theme
classes, `data-selected`, `aria-current`, and indicator animation as
`nav.Item`. This tier isn't rendered here either, for the same reason as
`@route` above.

```gts
import { TabNav } from 'frontile';

<template>
  <TabNav @label='Settings' as |nav|>
    <a href='/settings/account' class={{nav.itemClass}} {{nav.setupItem true}}>
      Account
    </a>
  </TabNav>
</template>
```

## Variants, colors, and sizes

`TabNav` shares its theme with `Tabs`, so `@variant`, `@color`, and `@size`
behave the same way — see [Tabs](./tabs) for each option.

```gts preview
import { TabNav } from 'frontile';

<template>
  <div class='demo-stack items-center'>
    <TabNav @label='Solid' @variant='solid' @color='primary' as |nav|>
      <nav.Item @href='#account' @isActive={{true}}>Account</nav.Item>
      <nav.Item @href='#security'>Security</nav.Item>
    </TabNav>

    <TabNav @label='Underline' @variant='underline' @color='primary' as |nav|>
      <nav.Item @href='#account' @isActive={{true}}>Account</nav.Item>
      <nav.Item @href='#security'>Security</nav.Item>
    </TabNav>
  </div>
</template>
```

## Vertical

```gts preview
import { TabNav } from 'frontile';

<template>
  <div class='demo-stack items-center'>
    <TabNav @label='Settings' @orientation='vertical' as |nav|>
      <nav.Item @href='#account' @isActive={{true}}>Account</nav.Item>
      <nav.Item @href='#security'>Security</nav.Item>
      <nav.Item @href='#billing'>Billing</nav.Item>
    </TabNav>
  </div>
</template>
```

## Full width

`@isFullWidth={{true}}` stretches the bar to its container and gives every
link equal width.

```gts preview
import { TabNav } from 'frontile';

<template>
  <div class='demo-stack items-center'>
    <div class='w-96 max-w-full rounded-lg border border-neutral-soft p-4'>
      <TabNav @label='Settings' @isFullWidth={{true}} as |nav|>
        <nav.Item @href='#account' @isActive={{true}}>Account</nav.Item>
        <nav.Item @href='#security'>Security</nav.Item>
      </TabNav>
    </div>
  </div>
</template>
```

## Disabled links

`@isDisabled` drops the `href` as well as marking the link `aria-disabled` —
an anchor cannot be natively disabled, so removing the href is what actually
stops navigation.

```gts preview
import { TabNav } from 'frontile';

<template>
  <div class='demo-stack items-center'>
    <TabNav @label='Settings' as |nav|>
      <nav.Item @href='#account' @isActive={{true}}>Account</nav.Item>
      <nav.Item @href='#billing' @isDisabled={{true}}>Billing</nav.Item>
      <nav.Item @href='#security'>Security</nav.Item>
    </TabNav>
  </div>
</template>
```

## Accessibility

`TabNav` renders a `<nav>` landmark (not a `<ul>`), and each `nav.Item` is a
plain link, not a tab — these links navigate rather than switch an in-page
panel. `TabNav` needs an accessible name from `@label`, or pass
`aria-labelledby` on `TabNav` directly.

Every link stays in the natural tab order and arrow keys are left to the
browser; there is no roving `tabindex` and no keyboard handling to document
beyond ordinary link navigation. The active link carries `aria-current="page"`
and `data-selected="true"`, both a `nav.Item` derives and `{{nav.setupItem}}`
sets for a hand-rolled link — a disabled link instead carries `aria-disabled`
and drops its `href`.

## API

### TabNav

A navigation bar styled like Tabs, for links that change the page.

It deliberately does not use rovingFocus: these are links, so every one
of them stays individually reachable by Tab and the arrow keys are left to
the browser. The ARIA tabs pattern covers in-page panel switching only, and
applying it to navigation would remove links from the tab order for no gain.

**Element:** `HTMLElement`

**Arguments**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `classes` | `SlotsToClasses<'base' \| 'indicator' \| 'list' \| 'tab' \| 'panel'>` | - | Class names for each slot of the component, merged with the theme's. |
| `color` | `'neutral' \| 'primary' \| 'secondary' \| 'tertiary' \| 'success' \| 'warning' \| 'danger'` | `'neutral'` | The colour intent applied to the indicator. |
| `isFullWidth` | `boolean` | `false` | Stretches the bar to its container and gives every link equal width. |
| `label` | `string` | - | Accessible name for the navigation landmark. |
| `orientation` | `'horizontal' \| 'vertical'` | `'horizontal'` | Lays the links out in a row or a column. |
| `size` | `'sm' \| 'md' \| 'lg'` | `'md'` | The size of the links, driving padding and text size. |
| `variant` | `'solid' \| 'underline'` | `'solid'` | The visual style of the navigation bar. |

**Blocks**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `default *` | `[{ Item: TabNavItem (itemClass, setupItem bound); itemClass: string; setupItem: TabNav['setupItem']; }]` | - |  |
### TabNavItem

**Element:** `HTMLAnchorElement`

**Arguments**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `itemClass *` | `string` | - | Supplied by TabNav. Not part of the public API. _(internal)_ |
| `setupItem *` | `ModifierLike<{ Element: HTMLElement; Args: { Positional: [boolean]; }; }>` | - | Supplied by TabNav. Not part of the public API. _(internal)_ |
| `class` | `string` | - | Class names appended to this item's theme classes. |
| `href` | `string` | - | Renders a plain anchor. Ignored when @route is given. |
| `isActive` | `boolean` | - | Overrides the active state. Always wins over anything derived from the router, and is the only source of truth when @route is not used. |
| `isDisabled` | `boolean` | `false` | Marks the link as disabled. An anchor cannot be natively disabled, so the href is dropped as well -- aria-disabled alone still leaves it clickable. |
| `model` | `unknown` | - | A single dynamic segment for @route. |
| `models` | `unknown[]` | - | Dynamic segments for @route. |
| `query` | `Record<string, unknown>` | - | Query params for @route. |
| `route` | `string` | - | Renders a LinkTo for this route and derives the active state from the router. Omit it (and pass @href) to stay entirely router-free. |

**Blocks**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `default *` | `[]` | - |  |

---

# Tabs

Source: /docs/components/navigation/tabs.md

# Tabs

A set of panels shown one at a time, with an indicator that slides between the
tabs. Use it when the content belongs to one page and switching between it
should not change the URL — for navigation between routes, reach for
[TabNav](./tab-nav) instead.

## Import

```js
import { Tabs } from 'frontile';
```

## Usage

`@defaultValue` picks the tab that starts selected, and `Tabs` tracks the rest
itself. `t.List` groups the tabs and needs an accessible `@label`; each
`t.Panel` is paired with a `t.Tab` of the same `@value` and only the selected
one renders.

```gts preview
import { Tabs } from 'frontile';

<template>
  <div class='demo-stack items-center'>
    <Tabs @defaultValue='account' as |t|>
      <t.List @label='Settings'>
        <t.Tab @value='account'>Account</t.Tab>
        <t.Tab @value='security'>Security</t.Tab>
        <t.Tab @value='billing'>Billing</t.Tab>
      </t.List>

      <t.Panel @value='account'>Update your name, email, and photo.</t.Panel>
      <t.Panel @value='security'>Manage passwords and two-factor auth.</t.Panel>
      <t.Panel @value='billing'>View invoices and update your plan.</t.Panel>
    </Tabs>
  </div>
</template>
```

## Controlled and uncontrolled

The mode is decided by whether `@value` is _passed_, not by what it holds.
Omit the argument entirely and `Tabs` is uncontrolled; write it at all —
including `@value={{undefined}}` — and it is controlled.

Without `@value`, `@defaultValue` seeds the initial selection and `Tabs` keeps
the current one internally, while `@onChange` still fires on every pick so you
can observe the value without owning it. Passing `@value` makes the selection
reflect only what you pass, so pair it with `@onChange` and assign the new
value back to your own state — reach for this when something outside `Tabs`
also drives the selection, such as a query parameter.

```gts preview
import Component from '@glimmer/component';
import { tracked } from '@glimmer/tracking';
import { Tabs } from 'frontile';

export default class Example extends Component {
  @tracked section = 'account';

  onChange = (value: string): void => {
    this.section = value;
  };

  <template>
    <div class='demo-stack items-center'>
      <Tabs @value={{this.section}} @onChange={{this.onChange}} as |t|>
        <t.List @label='Settings'>
          <t.Tab @value='account'>Account</t.Tab>
          <t.Tab @value='security'>Security</t.Tab>
        </t.List>

        <t.Panel @value='account'>Account panel</t.Panel>
        <t.Panel @value='security'>Security panel</t.Panel>
      </Tabs>

      <p class='text-body-sm text-neutral-strong'>Selected: {{this.section}}</p>
    </div>
  </template>
}
```

## Variants

`@variant='solid'` (the default) renders a filled, pill-shaped indicator on a
recessed track. `@variant='underline'` drops the track and pins a thin bar to
the leading edge instead — reach for it in a denser layout, such as a page
header, where the solid track would compete with surrounding content.

```gts preview
import { Tabs } from 'frontile';

<template>
  <div class='demo-stack items-center'>
    <Tabs @defaultValue='account' @variant='solid' as |t|>
      <t.List @label='Solid'>
        <t.Tab @value='account'>Account</t.Tab>
        <t.Tab @value='security'>Security</t.Tab>
        <t.Tab @value='billing'>Billing</t.Tab>
      </t.List>
    </Tabs>

    <Tabs @defaultValue='account' @variant='underline' as |t|>
      <t.List @label='Underline'>
        <t.Tab @value='account'>Account</t.Tab>
        <t.Tab @value='security'>Security</t.Tab>
        <t.Tab @value='billing'>Billing</t.Tab>
      </t.List>
    </Tabs>
  </div>
</template>
```

## Colors

`@color` colors the indicator, so the selected tab carries the meaning
rather than the whole component. `default` keeps the neutral fill; the rest
tint it and switch the selected label to the matching contrast ink in the
`solid` variant.

```gts preview
import { Tabs } from 'frontile';
import { array } from '@ember/helper';

<template>
  <div class='demo-stack items-center'>
    {{#each
      (array
        'default' 'primary' 'secondary' 'tertiary' 'success' 'warning' 'danger'
      )
      as |intent|
    }}
      <Tabs @defaultValue='account' @color={{intent}} as |t|>
        <t.List @label='{{intent}} intent'>
          <t.Tab @value='account'>Account</t.Tab>
          <t.Tab @value='security'>Security</t.Tab>
        </t.List>
      </Tabs>
    {{/each}}
  </div>
</template>
```

## Sizes

```gts preview
import { Tabs } from 'frontile';
import { array } from '@ember/helper';

<template>
  <div class='demo-stack items-center'>
    {{#each (array 'sm' 'md' 'lg') as |size|}}
      <Tabs @defaultValue='account' @size={{size}} as |t|>
        <t.List @label='{{size}} size'>
          <t.Tab @value='account'>Account</t.Tab>
          <t.Tab @value='security'>Security</t.Tab>
        </t.List>
      </Tabs>
    {{/each}}
  </div>
</template>
```

## Vertical

`@orientation='vertical'` stacks the tabs in a column, switches the arrow
keys that move between them to up/down, and lays the panel out beside the
list rather than beneath it.

```gts preview
import { Tabs } from 'frontile';

<template>
  <div class='demo-stack items-center'>
    <Tabs @defaultValue='account' @orientation='vertical' as |t|>
      <t.List @label='Settings'>
        <t.Tab @value='account'>Account</t.Tab>
        <t.Tab @value='security'>Security</t.Tab>
        <t.Tab @value='billing'>Billing</t.Tab>
      </t.List>

      <t.Panel @value='account'>Update your name, email, and photo.</t.Panel>
      <t.Panel @value='security'>Manage passwords and two-factor auth.</t.Panel>
      <t.Panel @value='billing'>View invoices and update your plan.</t.Panel>
    </Tabs>
  </div>
</template>
```

Both variants work vertically. `underline` pins its bar to the inline start
edge and runs the rule down the side of the list, so it suits a settings
sidebar where a filled track would compete with the panel beside it.

```gts preview
import { Tabs } from 'frontile';

<template>
  <div class='demo-stack items-center'>
    <Tabs
      @defaultValue='account'
      @orientation='vertical'
      @variant='underline'
      as |t|
    >
      <t.List @label='Settings'>
        <t.Tab @value='account'>Account</t.Tab>
        <t.Tab @value='security'>Security</t.Tab>
        <t.Tab @value='billing'>Billing</t.Tab>
      </t.List>

      <t.Panel @value='account'>Update your name, email, and photo.</t.Panel>
      <t.Panel @value='security'>Manage passwords and two-factor auth.</t.Panel>
      <t.Panel @value='billing'>View invoices and update your plan.</t.Panel>
    </Tabs>
  </div>
</template>
```

## Full width

`@isFullWidth={{true}}` stretches the tab list to its container and gives
every tab equal width.

```gts preview
import { Tabs } from 'frontile';

<template>
  <div class='demo-stack items-center'>
    <div
      class='flex w-96 max-w-full flex-col items-start gap-3 rounded-lg border border-neutral-soft p-4'
    >
      <Tabs @defaultValue='account' as |t|>
        <t.List @label='Default width'>
          <t.Tab @value='account'>Account</t.Tab>
          <t.Tab @value='security'>Security</t.Tab>
        </t.List>
      </Tabs>

      <Tabs @defaultValue='account' @isFullWidth={{true}} as |t|>
        <t.List @label='Full width'>
          <t.Tab @value='account'>Account</t.Tab>
          <t.Tab @value='security'>Security</t.Tab>
        </t.List>
      </Tabs>
    </div>
  </div>
</template>
```

## Disabled tabs

An individual tab can be disabled with its own `@isDisabled`; keyboard
navigation skips it and it cannot be clicked or selected. `@isDisabled` on
`Tabs` disables every tab.

```gts preview
import { Tabs } from 'frontile';

<template>
  <div class='demo-stack items-center'>
    <Tabs @defaultValue='account' as |t|>
      <t.List @label='Settings'>
        <t.Tab @value='account'>Account</t.Tab>
        <t.Tab @value='billing' @isDisabled={{true}}>Billing</t.Tab>
        <t.Tab @value='security'>Security</t.Tab>
      </t.List>
    </Tabs>
  </div>
</template>
```

## Manual activation

`@activationMode='manual'` changes what the arrow keys do: they move focus
between tabs without selecting them, and the focused tab is only selected on
`Enter` or `Space`. The default, `automatic`, selects a tab as soon as focus
reaches it. Reach for `manual` when selecting a tab is expensive enough — a
network request, a heavy re-render — that arrowing past several tabs
shouldn't trigger it each time.

```gts preview
import { Tabs } from 'frontile';

<template>
  <div class='demo-stack items-center'>
    <Tabs @defaultValue='account' @activationMode='manual' as |t|>
      <t.List @label='Settings'>
        <t.Tab @value='account'>Account</t.Tab>
        <t.Tab @value='security'>Security</t.Tab>
        <t.Tab @value='billing'>Billing</t.Tab>
      </t.List>

      <t.Panel @value='account'>Account panel</t.Panel>
      <t.Panel @value='security'>Security panel</t.Panel>
      <t.Panel @value='billing'>Billing panel</t.Panel>
    </Tabs>
  </div>
</template>
```

## Custom styling

Every tab publishes `data-selected` (`"true"` / `"false"`) and
`data-disabled`, so a `@classes.tab` override that should only affect the
selected tab needs a `data-[selected=true]:` modifier rather than reaching
for `aria-selected` or `:disabled`.

```gts preview
import { Tabs } from 'frontile';
import { hash } from '@ember/helper';

<template>
  <div class='demo-stack items-center'>
    <Tabs
      @defaultValue='account'
      @classes={{hash
        tab='data-[selected=true]:text-on-primary'
        indicator='bg-primary'
      }}
      as |t|
    >
      <t.List @label='Settings'>
        <t.Tab @value='account'>Account</t.Tab>
        <t.Tab @value='security'>Security</t.Tab>
      </t.List>
    </Tabs>
  </div>
</template>
```

## Accessibility

`t.List` renders `role="tablist"` with `aria-orientation`, each `t.Tab` is a
`role="tab"` (`aria-selected`, `aria-controls` pointing at its panel), and
each `t.Panel` is a `role="tabpanel"` (`aria-labelledby` pointing back at its
tab, `tabindex="0"`) that only exists in the DOM while selected.

`t.List` needs an accessible name from `@label`, or pass `aria-labelledby` on
`t.List` directly.

| Key                        | Behaviour                                                                                            |
| -------------------------- | ---------------------------------------------------------------------------------------------------- |
| `Tab`                      | Moves focus into or out of the tab list. Only the selected tab is a tab stop.                        |
| `ArrowRight` / `ArrowDown` | Moves focus to the next enabled tab, wrapping at the end.                                            |
| `ArrowLeft` / `ArrowUp`    | Moves focus to the previous enabled tab, wrapping at the start.                                      |
| `Home` / `End`             | Moves focus to the first / last enabled tab.                                                         |
| `Enter` / `Space`          | Selects the focused tab. Only needed in manual activation — automatic activation selects on arrival. |

Horizontal orientation uses left/right, vertical orientation uses up/down.
Disabled tabs are skipped entirely.

## API

### Tabs

**Element:** `HTMLDivElement`

**Arguments**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `activationMode` | `'automatic' \| 'manual'` | `'automatic'` | automatic moves selection with focus, which the APG recommends when panel content is already loaded. manual moves focus only and waits for Enter or Space. |
| `classes` | `SlotsToClasses<'base' \| 'indicator' \| 'list' \| 'tab' \| 'panel'>` | - | Class names for each slot of the component, merged with the theme's. |
| `color` | `'neutral' \| 'primary' \| 'secondary' \| 'tertiary' \| 'success' \| 'warning' \| 'danger'` | `'neutral'` | The colour intent applied to the indicator. |
| `defaultValue` | `T` | - | Sets the initially selected value when uncontrolled. |
| `isDisabled` | `boolean` | `false` | Disables every tab. |
| `isFullWidth` | `boolean` | `false` | Stretches the tab list to its container and gives every tab equal width. |
| `onChange` | `(value: T) => void` | - | Called with the newly selected value when a tab is chosen. |
| `orientation` | `'horizontal' \| 'vertical'` | `'horizontal'` | Lays the tabs out in a row or a column, and switches the arrow keys that move between them to match. |
| `size` | `'sm' \| 'md' \| 'lg'` | `'md'` | The size of the tabs, driving padding and text size. |
| `value` | `T` | - | The currently selected value. Compared against each tab's @value with ===, so object values must be referentially stable. Passing this argument at all puts the component in controlled mode -- passing it as undefined included. Omit it entirely to let Tabs track the selection itself, seeded by @defaultValue. |
| `variant` | `'solid' \| 'underline'` | `'solid'` | The visual style of the tab list. |

**Blocks**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `default *` | `[{ List: TabsList<T> (context bound); Tab: TabsTab<T> (context bound); Panel: TabsPanel<T> (context bound); }]` | - |  |
### TabsTab

**Element:** `HTMLButtonElement`

**Arguments**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `context *` | `Object` | - | Supplied by Tabs. Not part of the public API. _(internal)_ |
| `value *` | `T` | - | The value this tab represents, paired with a Panel of the same value. |
| `class` | `string` | - | Class names appended to this tab's theme classes. |
| `isDisabled` | `boolean` | `false` | Disables this tab alone: it cannot be activated and keyboard navigation skips over it. |

**Blocks**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `default *` | `[{ isSelected: boolean; }]` | - |  |
### TabsPanel

**Element:** `HTMLDivElement`

**Arguments**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `context *` | `Object` | - | Supplied by Tabs. Not part of the public API. _(internal)_ |
| `value *` | `T` | - | The value this panel is paired with; must match a Tab's @value. |
| `class` | `string` | - | Class names appended to this panel's theme classes. |

**Blocks**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `default *` | `[]` | - |  |

---

# Accordion

Source: /docs/components/disclosure/accordion.md

# Accordion

A vertically stacked set of headings that each reveal a section of content. Use
it to collapse long secondary material — FAQs, settings groups, detail panels —
so the page stays scannable.

For a single expandable region with no grouping and no coordination, reach for
[Collapsible](../utilities/collapsible), which is the primitive this is built on.

## Import

```js
import { Accordion } from 'frontile';
```

## Usage

`@title` and the default block cover the common case. Nothing needs a key.

```gts preview
import { Accordion } from 'frontile';

<template>
  <div class='demo-stack'>
    <Accordion as |a|>
      <a.Item @title='What are your shipping options?'>
        Standard shipping arrives in three to five business days. Express
        arrives the next business day.
      </a.Item>
      <a.Item @title='What is your return policy?'>
        Unopened items can be returned within thirty days for a full refund.
      </a.Item>
      <a.Item @title='How can I contact support?'>
        Email support@example.com, or use the chat widget in the bottom corner.
      </a.Item>
    </Accordion>
  </div>
</template>
```

## Starting open

`@isDefaultOpen` on an item opens it on first render. In `single` mode, if
several items declare it, the first in document order wins.

```gts preview
import { Accordion } from 'frontile';

<template>
  <div class='demo-stack'>
    <Accordion as |a|>
      <a.Item @title='Shipping' @isDefaultOpen={{true}}>
        Three to five business days.
      </a.Item>
      <a.Item @title='Returns'>Thirty days, unopened.</a.Item>
    </Accordion>
  </div>
</template>
```

## Several open at once

```gts preview
import { Accordion } from 'frontile';

<template>
  <div class='demo-stack'>
    <Accordion @selectionMode='multiple' as |a|>
      <a.Item @title='Shipping' @isDefaultOpen={{true}}>
        Three to five business days.
      </a.Item>
      <a.Item @title='Returns' @isDefaultOpen={{true}}>
        Thirty days, unopened.
      </a.Item>
      <a.Item @title='Support'>Email or chat.</a.Item>
    </Accordion>
  </div>
</template>
```

## Keys, and when you need them

An item's `@key` names it so something outside the accordion can address it —
controlled mode, a query parameter, persisted state. Without one an item still
works; it just isn't addressable. Identity then falls back to a generated id,
never to a position, so an item behind an `{{#if}}` cannot inherit its
neighbour's open state.

## Controlled and uncontrolled

The mode is decided by whether `@keys` is _passed_, not by what it holds. Omit
it and `Accordion` tracks the open items itself; write it at all — including
`@keys={{undefined}}` — and it is controlled.

Note this differs from [Tabs](../navigation/tabs), which names its arguments
`@value`/`@defaultValue`. Tabs holds one scalar selection; an accordion holds a
_set_ of open items identified by each item's `@key`.

```gts preview collapsible
import Component from '@glimmer/component';
import { tracked } from '@glimmer/tracking';
import { on } from '@ember/modifier';
import { Accordion, Button } from 'frontile';

export default class ControlledAccordion extends Component {
  @tracked openKeys = ['shipping'];

  setOpenKeys = (keys) => {
    this.openKeys = keys;
  };

  openAll = () => {
    this.openKeys = ['shipping', 'returns'];
  };

  <template>
    <div class='demo-stack'>
      <Button @size='sm' {{on 'click' this.openAll}}>Open all</Button>

      <Accordion
        @selectionMode='multiple'
        @keys={{this.openKeys}}
        @onChange={{this.setOpenKeys}}
        as |a|
      >
        <a.Item @key='shipping' @title='Shipping'>
          Three to five business days.
        </a.Item>
        <a.Item @key='returns' @title='Returns'>
          Thirty days, unopened.
        </a.Item>
      </Accordion>
    </div>
  </template>
}
```

## Variants

```gts preview
import { array } from '@ember/helper';
import { Accordion } from 'frontile';

<template>
  {{! `demo-stack` has to be the demo's root for the full-width rule to fire,
      but its own `gap-4` is too tight to read as four separate groups. A
      `gap-8` utility on the same element loses to the helper's `@apply gap-4`
      on source order, so the wider rhythm goes on an inner wrapper. }}
  <div class='demo-stack'>
    <div class='flex flex-col gap-8'>
      {{#each (array 'separated' 'ghost' 'soft' 'enclosed') as |variant|}}
        <div>
          <p class='text-label-xs text-neutral-firm mb-2'>{{variant}}</p>
          <Accordion @variant={{variant}} as |a|>
            <a.Item @title='First item' @isDefaultOpen={{true}}>
              Some value 1…
            </a.Item>
            <a.Item @title='Second item'>Some value 2…</a.Item>
            <a.Item @title='Third item'>Some value 3…</a.Item>
          </Accordion>
        </div>
      {{/each}}
    </div>
  </div>
</template>
```

## Sizes

```gts preview
import { array } from '@ember/helper';
import { Accordion } from 'frontile';

<template>
  <div class='demo-stack'>
    <div class='flex flex-col gap-8'>
      {{#each (array 'sm' 'md' 'lg') as |size|}}
        <div>
          <p class='text-label-xs text-neutral-firm mb-2'>{{size}}</p>
          <Accordion @size={{size}} as |a|>
            <a.Item @title='First item' @isDefaultOpen={{true}}>
              Some value 1…
            </a.Item>
            <a.Item @title='Second item'>Some value 2…</a.Item>
          </Accordion>
        </div>
      {{/each}}
    </div>
  </div>
</template>
```

## Subtitles, icons and a custom indicator

Named blocks take over whenever the argument shortcuts are not enough. Two
Ember rules to know:

- **A default block cannot coexist with named blocks** — the moment you use
  `<:title>`, the body has to become `<:content>`.
- **Block params go on the named block, not the invocation tag.** Write
  `<:indicator as |i|>`, not `<a.Item as |i|>` — the latter errors with "the
  invocation tag cannot take block params" once any named block is present.

Every block yields `{{isOpen}}` and `{{toggle}}`.

```gts preview
import { Accordion, Avatar } from 'frontile';

<template>
  <div class='demo-stack'>
    <Accordion as |a|>
      <a.Item @key='team'>
        <:startContent><Avatar
            @name='Ada Lovelace'
            @size='sm'
          /></:startContent>
        <:title>Team</:title>
        <:subtitle>Three members</:subtitle>
        <:indicator as |i|>{{if i.isOpen '−' '+'}}</:indicator>
        <:content>Ada, Grace and Katherine.</:content>
      </a.Item>

      <a.Item @title='Billing' @subtitle='Plans and invoices'>
        Monthly or annual, cancel anytime.
      </a.Item>
    </Accordion>
  </div>
</template>
```

## Disabled items

```gts preview
import { Accordion } from 'frontile';

<template>
  <div class='demo-stack'>
    <Accordion as |a|>
      <a.Item @title='Available'>You can open this one.</a.Item>
      <a.Item @title='Unavailable' @isDisabled={{true}}>
        You cannot reach this.
      </a.Item>
    </Accordion>
  </div>
</template>
```

## Keeping one open

`@isCollapsible={{false}}` stops the open item from being closed, so something
is always showing. It applies to `single` mode only.

```gts preview
import { Accordion } from 'frontile';

<template>
  <div class='demo-stack'>
    <Accordion @isCollapsible={{false}} as |a|>
      <a.Item @title='First item' @isDefaultOpen={{true}}>Some value 1…</a.Item>
      <a.Item @title='Second item'>Some value 2…</a.Item>
    </Accordion>
  </div>
</template>
```

## Accessibility

`Accordion` implements the WAI-ARIA accordion pattern.

- Each trigger is a real `<button>` wrapped in a heading. Set `@headingLevel`
  to whatever fits the surrounding page outline — it defaults to `3`, which is
  wrong as often as it is right.
- The trigger carries `aria-expanded` and `aria-controls`; the panel is a
  `role="region"` labelled by its trigger.
- **Every header is its own tab stop**, as the pattern requires. Tab moves
  through the headers; Enter and Space toggle. Arrow Down and Arrow Up move
  between headers and wrap, Home and End jump to the first and last, and
  disabled headers are stepped over.
- Closed panels are `inert`, so anything focusable inside them leaves the tab
  order rather than being reachable by Tab while invisible.
- Content stays in the DOM when closed, so find-in-page and search engines can
  still reach it.
- The open/close animation is skipped for users who prefer reduced motion.

## API

### Accordion

**Element:** `HTMLDivElement`

**Arguments**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `classes` | `SlotsToClasses<'trigger' \| 'base' \| 'startContent' \| 'item' \| 'title' \| 'content' \| 'indicator' \| 'heading' \| 'titleWrapper' \| 'subtitle' \| 'contentBody'>` | - | Class names for each slot of the component, merged with the theme's. |
| `defaultKeys` | `string[]` | - | Seeds the open items when uncontrolled. Takes precedence over any item's @isDefaultOpen. |
| `headingLevel` | `HeadingLevel` | `3` | The heading level each trigger is wrapped in. Pick the one that fits the surrounding page outline. |
| `hideIndicator` | `boolean` | `false` | Hides the chevron on every item. |
| `isCollapsible` | `boolean` | `true` | Whether the open item can be closed again in single mode. Has no effect in multiple mode. |
| `isDisabled` | `boolean` | `false` | Disables every item. |
| `keys` | `string[]` | - | The keys of the open items. Passing this argument at all puts the component in controlled mode -- passing it as undefined included. Omit it entirely to let Accordion track the open items itself. |
| `onChange` | `(keys: string[]) => void` | - | Called with the new set of open keys whenever an item is toggled. |
| `selectionMode` | `'single' \| 'multiple'` | `'single'` | Whether one item or several may be open at a time. |
| `size` | `'sm' \| 'md' \| 'lg'` | `'md'` | Drives padding and text size. |
| `variant` | `'soft' \| 'ghost' \| 'separated' \| 'enclosed'` | `'separated'` | The container treatment. |

**Blocks**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `default *` | `[{ Item: AccordionItem (context bound); }]` | - |  |
### AccordionItem

**Element:** `HTMLDivElement`

**Arguments**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `context *` | `Object` | - | Supplied by Accordion. Not part of the public API. _(internal)_ |
| `class` | `string` | - | Class names appended to this item's theme classes. |
| `isDefaultOpen` | `boolean` | `false` | Opens this item initially, without needing a key anywhere. Ignored when the accordion is controlled or when @defaultKeys is passed. In single mode, if several items declare it, the first in document order wins. |
| `isDisabled` | `boolean` | `false` | Disables this item alone: it cannot be toggled and arrow-key navigation steps over it. |
| `key` | `string` | `a generated unique id` | Names this item so it can be addressed from outside -- @keys, @defaultKeys, a query param, persisted state. Optional: without one the item still works, it is simply not externally addressable. |
| `subtitle` | `string` | - | Shorthand for the subtitle block. |
| `title` | `string` | - | Shorthand for the title block. |

**Blocks**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `default *` | `[{ isOpen: boolean; toggle: () => void; }]` | - |  |
| `content *` | `[{ isOpen: boolean; toggle: () => void; }]` | - |  |
| `title *` | `[{ isOpen: boolean; toggle: () => void; }]` | - |  |
| `subtitle *` | `[{ isOpen: boolean; toggle: () => void; }]` | - |  |
| `startContent *` | `[{ isOpen: boolean; toggle: () => void; }]` | - |  |
| `indicator *` | `[{ isOpen: boolean; toggle: () => void; }]` | - |  |