# Introduction

Source: /docs/get-started/index.md

# Introduction

Frontile is a component library for Ember.js applications, built with [Tailwind CSS](https://tailwindcss.com/) and [Tailwind Variants](https://www.tailwind-variants.org/).

## Why Frontile?

Frontile provides components, helpers, modifiers, and styles for building Ember.js apps, offering both low-level primitives and high-level components.

### Key Features

- **Built for Ember** – Integrates with Ember Octane & Glimmer components
- **Accessibility** – ARIA attributes, keyboard navigation, and focus management built into every component
- **Customizable** – Uses Tailwind CSS with Tailwind Variants for styling
- **TypeScript & Glint Support** – Fully typed templates with Glint
- **Theme Support** – Dark & light mode support with theme-aware components
- **Responsive foundations** – Components can be composed with Tailwind CSS responsive utilities
- **Composable & Extensible** – Designed to be customized and extended to fit any design system

## Quick Start

Get started with Frontile in just a few steps:

### Installation

```sh
pnpm install frontile @frontile/theme
```

### Basic Setup

Add Frontile's theme configuration to your `app/styles/app.css` for Tailwind CSS v4:

```css title="app/styles/app.css"
@import 'tailwindcss' source('../../');
@plugin "@frontile/theme/plugin/default";
@import "@frontile/theme";

/* Tailwind skips node_modules when scanning for classes, so Frontile's own
   templates have to be pointed at or their classes get purged. */
@source '../../node_modules/frontile';
@source '../../node_modules/@frontile';
```

Paths are relative to the CSS file. Under Vite the entry stylesheet is usually
`app/app.css`, one level shallower, so the sources become
`'../node_modules/...'`.

The `dark` variant comes from `@import "@frontile/theme"` — you do not need to
declare `@custom-variant dark` yourself, and the version the theme ships also
handles `theme-inverse`.

### Your First Component

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

export default class Example extends Component {
  onPress = () => {
    alert('Welcome to Frontile!');
  };

  <template>
    <Button @color='primary' @size='lg' @onPress={{this.onPress}}>
      Get Started
    </Button>
  </template>
}
```

### Legacy Packages

> **Note:** The following packages are deprecated and will be removed in 0.19.0. See the [migration guides](/docs/migrations/v0-18/) for details:
>
> - [`@frontile/changeset-form`](/docs/migrations/v0-18/changeset-form) - Use `frontile` forms instead
> - [`@frontile/forms-legacy`](/docs/migrations/v0-18/forms-legacy) - Migrate to the new `frontile` forms

## Architecture Philosophy

Frontile follows a component composition pattern that prioritizes:

- **Flexibility** – Components are designed to be composed together in various ways
- **Consistency** – Unified design language across all components
- **Accessibility** – Keyboard, focus, labeling, and ARIA behavior are built into interactive components
- **Performance** – Optimized for Ember's rendering system
- **Developer Experience** – Clear APIs with TypeScript support

## Browser Support

Frontile supports all modern browsers and follows Ember.js compatibility guidelines:

- **Ember.js** v4.12 or above
- **Modern Browsers** – Chrome, Firefox, Safari, Edge

## Development Status

Frontile is currently in active development and approaching v1.0. While the API is stabilizing, breaking changes may still occur. We recommend using Frontile in production with appropriate version pinning.

## Getting Help

- 📖 **Documentation** – Visit [frontile.dev](https://frontile.dev/) for comprehensive guides and examples
- 🐛 **Issues** – Report bugs or request features on [GitHub](https://github.com/josemarluedke/frontile/issues)
- 💬 **Community** – Join discussions on the Ember.js Discord server

## Acknowledgments

Frontile draws on patterns from other component libraries and design systems:

- **[HeroUI](https://www.heroui.com/)** – React UI library with accessibility and theming
- **[IntentUI](https://intentui.com/)** – Design system focused on developer experience and component composition
- **[Mantine](https://mantine.dev/)** – Full-featured React components library with theming
- **[Chakra UI](https://chakra-ui.com/)** – Modular, accessible component library for React
- **[Ember Primitives](https://ember-primitives.pages.dev/)** – Low-level UI primitives for Ember applications

These projects have influenced Frontile's approach to component design, accessibility, theming, and developer experience.

---

See the [Installation Guide](./installation.md) to start building with Frontile.

---

# Installation

Source: /docs/get-started/installation.md

# Installation

Frontile is a component library for Ember.js that ships all its components in a single package. Modern build tools with tree-shaking include only the components you use in your final bundle.

## Install Frontile

Install the main `frontile` package along with the theme:

:::code-tabs

```sh title="pnpm"
pnpm install frontile @frontile/theme
```

```sh title="npm"
npm install frontile @frontile/theme
```

```sh title="yarn"
yarn add frontile @frontile/theme
```

:::

You now have access to all Frontile components:

```js
import { Button, Input, Modal, Table } from 'frontile';
```

With modern build tools and explicit imports (`.gts`/`.gjs`), only the components you import will be included in your application bundle through tree-shaking.

> **Note:** The following packages are deprecated and will be removed in 0.19.0. See the [migration guides](/docs/migrations/v0-18/) for details:
>
> - [`@frontile/changeset-form`](/docs/migrations/v0-18/changeset-form) - Use `frontile` forms instead
> - [`@frontile/forms-legacy`](/docs/migrations/v0-18/forms-legacy) - Migrate to the new `frontile` forms
>
> If you're currently using the separate scoped packages (`@frontile/buttons`, `@frontile/forms`, etc.), you can migrate to the consolidated `frontile` package by updating your imports:
>
> ```diff
> - import { Button } from '@frontile/buttons';
> + import { Button } from 'frontile';
> ```

## Setup Theme

### Using Default Theme

For the default theme, add this to your `app/styles/app.css`:

```css title="app/styles/app.css" {7-8}
@import 'tailwindcss' source('../../');
@plugin "@frontile/theme/plugin/default";
@import "@frontile/theme";

/* Tailwind v4 skips node_modules when scanning for classes. Without these,
   Frontile's own component classes are purged and components render unstyled. */
@source '../../node_modules/frontile';
@source '../../node_modules/@frontile';
```

Paths are relative to this file — under Vite, where the entry stylesheet is
usually `app/app.css`, they are one level shallower.

### Customizing Frontile Theme

To customize the frontile theme, create a file in the root of your project named `frontile.js` with the following content:

```js title="frontile.js"
const { frontile } = require('@frontile/theme/plugin');

module.exports = frontile({
  /* your config */
});
```

Then update your `app/styles/app.css` to use the custom configuration:

```css title="app/styles/app.css"
@import 'tailwindcss' source('../../');
@plugin "./../../frontile.js";
@import "@frontile/theme";
```

For more advanced configuration options, see the [Theme documentation](../theming/overview.md).

---

# Overview

Source: /docs/get-started/ai/index.md

# AI & Agents

Frontile publishes its documentation in forms a coding agent can read directly: a machine
index, plain-Markdown mirrors of every page, and an installable skill. Nothing here needs a
server, an account, or a plugin.

All of it exists so an agent can read the actual API instead of inventing one that looks
plausible.

## Start here

**Using a coding agent** such as Claude Code, Cursor, or Codex, install the skill:

```bash
npx skills add josemarluedke/frontile
```

It teaches the agent where to look, which component to reach for, and how the styling system
works. See [Agent Skill](./skill.md).

**Using a chat tool**, or wiring something up yourself, point it at
[`/llms.txt`](/llms.txt) and let it follow the links. See
[LLMs.txt](./llms-txt.md).

Neither is required. Every page on this site is available as Markdown at its own URL plus
`.md`, and that works with no setup at all.

## When to reach for Frontile

Frontile is an Ember.js component library built on Tailwind CSS and Tailwind Variants. It
fits when the task is:

- Building UI in an Ember app where Tailwind is acceptable, and you want accessible
  components rather than primitives to style yourself.
- Forms that handle their own labelling, validation display, and sizing.
- Collections such as tables, listboxes, dropdowns, calendars, and command palettes.
- Overlays driven from a template or from code: modals, drawers, popovers, toasts.
- Theming an app to a brand through semantic color tokens, without forking component code.

Reach for something else when the project is React, Vue, Svelte, or plain HTML, when Tailwind
is off the table, or when you want unstyled headless primitives with no prebuilt UI.

## Where an agent should look

In this order, cheapest and most trustworthy first.

**1. The type declarations in your own `node_modules`.**

```
node_modules/frontile/declarations/**/*.d.ts
```

Authoritative for arguments, types, and defaults, and exact for the version you installed,
which no published document can be. `frontile` ships `declarations/` and Glint needs it, so
this is already on disk in every app. The JSDoc survives the build:

```ts
/**
 * The button variant.
 *
 * @defaultValue 'solid'
 */
variant?: 'solid' | 'soft' | 'subtle' | 'outline' | 'ghost' | 'plain' | 'custom';
```

Anything deprecated is marked `@deprecated` here too, with the replacement named.

**2. The Markdown mirror of the component's page.** Every page on this site is also served as
plain Markdown at the same URL plus `.md`, carrying the prose, examples, and yielded blocks
that type declarations cannot express. See [LLMs.txt](./llms-txt.md).

**3. The index**, when the component's name is not yet known: [`/llms.txt`](/llms.txt).

Tier 1 decides whether the generated code compiles, and it always matches the installed
version. Tiers 2 and 3 supply prose and discovery, where reading documentation slightly ahead
of your installed version costs far less.

## Which origin serves these files

They are emitted by the documentation build, so every version subdomain serves the files for
its own version, but only for versions built after the export existed.

| Origin                                                    | Serves the agent surface |
| --------------------------------------------------------- | ------------------------ |
| [`next.frontile.dev`](https://next.frontile.dev/llms.txt) | Yes, in-development docs |
| `frontile.dev`                                            | From 0.18 onward         |
| `v0.16.frontile.dev`                                      | No, predates it          |

> **Note:** An origin that does not serve them answers with the site's HTML shell and HTTP
> 200, not a 404. A fetch that returns HTML where Markdown was expected has failed, whatever
> the status code says.

---

# LLMs.txt

Source: /docs/get-started/ai/llms-txt.md

# LLMs.txt

Every page of these docs is published twice: once as the HTML you are reading, and once as
plain Markdown for anything that would rather not parse a single-page app. Alongside them
sits an index and a set of bulk files, following the [llms.txt standard](https://llmstxt.org).

All of it is generated by the documentation build, so nothing drifts from the site.

## Which file to use

Start with `/llms.txt`. It fits in any context window and links to everything else.

| File                                           | Contents                                | Approx. tokens |
| ---------------------------------------------- | --------------------------------------- | -------------- |
| [`/llms.txt`](/llms.txt)                       | Index, with a description per component | 3K             |
| [`/llms-components.txt`](/llms-components.txt) | Every component page in full            | 230K           |
| [`/llms-theming.txt`](/llms-theming.txt)       | Theming, design tokens, configuration   | 31K            |
| [`/llms-migrations.txt`](/llms-migrations.txt) | Migration guides                        | 28K            |
| [`/llms-full.txt`](/llms-full.txt)             | Everything                              | 302K           |

`llms-full.txt` exceeds most context windows and is rarely the right choice. Reach for the
narrowest file that covers the task: an agent building a form never needs the migration
prose.

## Per-page Markdown mirrors

Any page URL plus `.md` returns that page as Markdown:

```
/docs/components/buttons/button      →  the HTML page
/docs/components/buttons/button.md   →  the same content, as Markdown
```

The mirror is the full page, not a summary. Component pages carry the generated API table:
every argument, its type, its default, and a Deprecated marker with the migration
instruction where one applies. The `<Signature />` tag is expanded into a real Markdown
table before export, so nothing arrives as an unresolved component tag.

Fetch the `.md`. Fetching the HTML and stripping tags is slower and loses the API table.

## What the index contains

Every page, grouped by section, each linking to its `.md` mirror:

```
## Buttons

- [Button](/docs/components/buttons/button.md): The base pressable action, with colors, variants, and sizes.
- [Chip](/docs/components/buttons/chip.md): A compact label for statuses, filters, and removable tags.
```

Component entries carry a one-line description, so an agent can usually pick the right
component without fetching anything. Guide pages are listed without one.

The file opens with a preamble covering the conventions most often got wrong, and marks
deprecated sections so `Forms (Legacy)` is not mistaken for current `Forms`.

## Using it with your tools

### Claude Code

Point it at the index and let it follow the links, fetching `.md` pages on demand:

```
Use Frontile documentation from https://frontile.dev/llms.txt
```

Put that line in your project's `CLAUDE.md` to apply it to every session. The
[Frontile skill](./skill.md) does this and more, without the manual step.

### Cursor

Add the URL to your project context with `@Docs`:

```
@Docs https://frontile.dev/llms.txt
```

> **Note:** Type the `@` by hand. Pasting it stops Cursor from recognising it as a context
> reference. See [Cursor's @Docs guide](https://cursor.com/docs/context/@-symbols/@-docs).

### Windsurf

Add a line to `.windsurfrules` so it applies to every conversation:

```
#docs https://frontile.dev/llms.txt
```

### ChatGPT, Claude, and other chat tools

Paste a `.md` URL and ask about that component:

```
https://frontile.dev/docs/components/forms/select.md
How do I make this filter as the user types?
```

For a whole topic, `llms-components.txt` fits in a 200K-token context. `llms-full.txt`
generally does not.

### Anything else

These are static text files over HTTPS with no authentication, so `curl`, `fetch`, or a
scheduled job all work:

```bash
curl https://frontile.dev/docs/components/buttons/button.md
```

## The component inventory

[`/component-inventory.json`](/component-inventory.json) lists every current component with
its path and one-line description, the same data behind the
[components overview](/docs/components/overview). Useful when something needs the catalogue
as structured data rather than prose. Legacy packages are excluded from it.

## Version-matched origins

These files are built per version, so each documentation origin serves its own. Only
versions built after the export existed have them:

| Origin                                                    | Agent surface    |
| --------------------------------------------------------- | ---------------- |
| [`next.frontile.dev`](https://next.frontile.dev/llms.txt) | Yes              |
| `frontile.dev`                                            | From 0.18 onward |
| `v0.16.frontile.dev`                                      | No               |

> **Note:** An origin without these files answers with the site's HTML shell and HTTP 200,
> not a 404. Check the body rather than the status code: Markdown that starts with
> `<!DOCTYPE html>` is a failed fetch.

For anything version-sensitive, such as an argument's exact type or whether it is deprecated,
read `node_modules/frontile/declarations/**/*.d.ts` in the consuming app instead. That is
exact for the installed version by construction.

## Found a problem?

If an agent generates wrong Frontile code and the cause is something these files say, or fail
to say, that is a documentation bug worth reporting.
[Open an issue](https://github.com/josemarluedke/frontile/issues).

---

# Agent Skill

Source: /docs/get-started/ai/skill.md

# Agent Skill

```bash
npx skills add josemarluedke/frontile
```

Once installed, ask your agent for UI and it builds with Frontile instead of guessing at an
API it half-remembers:

- _"Add a settings form with a name field, an email field, and a save button."_
- _"Put this destructive action behind a confirmation modal."_
- _"Make this table sortable and paginated."_
- _"Restyle these buttons to the danger color."_
- _"This Select should let people type to filter."_

## What a skill is

A skill is a set of instructions an agent loads when it recognises that a task involves
Frontile. It sits in your project, is plain Markdown you can read and edit, and needs no
server, account, or running process. The [`skills` CLI](https://skills.sh) installs it and
supports 35+ agents including Claude Code, Cursor, Codex, and Windsurf.

An MCP server answers questions over a live connection. A skill is loaded text. For a library
whose facts are already on disk in your `node_modules`, text is enough, which is why Frontile
ships a skill and no server.

## What it carries

The skill holds judgment and routes to facts. It does not restate arguments, types, or
defaults.

An installed skill is a copy of a file, frozen at install time, while your `frontile`
dependency moves independently. Any argument list written into it would eventually describe a
version nobody has. So it states where to look instead: first
`node_modules/frontile/declarations/**/*.d.ts`, which is exact for the version you installed,
then the [Markdown mirrors](./llms-txt.md) for prose and examples.

What it does carry:

- **The lookup order**, so the agent checks your installed types before inventing an argument.
- **Component selection** for the genuinely ambiguous choices: Modal versus Drawer versus
  Popover, Select versus NativeSelect versus Autocomplete, Table versus SimpleTable.
- **The semantic color system:** categories with named levels, and why `bg-primary-500` does
  not exist.
- **`.gts` conventions**, including the imports that are not where an agent expects them and
  the Tailwind `@source` lines that, when missing, leave every component unstyled.
- **The pre-0.18 argument names**, for upgrades and for the older examples still circulating.

Reference files load on demand, so a question about colors does not pull in the migration
guidance:

```
skills/frontile/
├── SKILL.md                          # Lookup order, common traps, routing table
└── references/
    ├── api-naming.md                 # Current vs pre-0.18 argument names
    ├── colors.md                     # Semantic categories and levels
    ├── component-selection.md        # Which component for which job
    └── gts-conventions.md            # Template authoring and setup
```

## Using it

Most agents load the skill on their own once they recognise the task involves Frontile. In
agents that support invoking a skill directly, `/frontile` does it explicitly.

## Installing

Project-level by default, which is usually what you want: the skill is committed with the
project, so everyone working on it gets the same guidance. Use `--global` when only some of
your projects use Frontile and you would rather not carry it in every agent's context.

```bash
npx skills add josemarluedke/frontile          # this project
npx skills add josemarluedke/frontile --global # every project on this machine
```

The CLI writes into whichever directory each detected agent reads from. For Claude Code that
is `.claude/skills/frontile`, and the files are plain Markdown you can open, edit, or commit.

Target one agent rather than every detected one:

```bash
npx skills add josemarluedke/frontile --agent claude-code
npx skills add josemarluedke/frontile --agent cursor
```

Installing offers a second skill, `frontile-contributor-docs`. That one is for work inside
the Frontile repository itself, writing the component documentation that lives beside the
source, and is of no use in an app that consumes Frontile. To skip the prompt:

```bash
npx skills add josemarluedke/frontile --skill frontile
```

## Keeping it current

Updates are manual. The CLI pulls; nothing is pushed to you:

```bash
npx skills update
```

Worth running after upgrading Frontile, particularly across a minor version. An installed
skill can sit arbitrarily far behind the version in your `package.json`, or ahead of it if
you installed while tracking the development branch.

A stale skill costs you guidance rather than correctness: the facts that decide whether
generated code compiles come from your own `node_modules`.

## Without installing anything

Everything the skill points at is fetchable directly, and [`/llms.txt`](/llms.txt) states the
same lookup order in its preamble, so an agent pointed at the index alone arrives at the same
place. See [LLMs.txt](./llms-txt.md).

## Found a problem?

If the skill steers an agent wrong, that is a bug in the skill.
[Open an issue](https://github.com/josemarluedke/frontile/issues).

## Related

- [Agent Skills specification](https://agentskills.io/home)
- [Claude Agent Skills](https://platform.claude.com/docs/en/agents-and-tools/agent-skills/overview)
- [`skills` CLI](https://skills.sh)

---

# Theme System

Source: /docs/theming/overview.md

# Theme System

Frontile's theme system is an accessible design foundation built on semantic colors, a surface system, and automatic dark mode support.

## Installation

Install the theme package using Ember CLI:

```bash
ember install @frontile/theme
```

## Configuration

### Using Default Theme

Add this to your `app/styles/app.css`:

```css title="app/styles/app.css"
@import 'tailwindcss' source('../../');
@plugin "@frontile/theme/plugin/default";
@import "@frontile/theme";
```

### Custom Theme Configuration

Create `frontile.js` in your project root:

```js title="frontile.js"
const { frontile } = require('@frontile/theme/plugin');

module.exports = frontile({
  /* your configuration */
});
```

Then update `app/styles/app.css`:

```css title="app/styles/app.css"
@import 'tailwindcss' source('../../');
@plugin "./../../frontile.js";
@import "@frontile/theme";
```

## Key Concepts

### Semantic Colors

Meaningful color categories (neutral, primary, success, danger, warning) with intuitive levels (subtle, soft, firm, strong) that adapt between light and dark themes.

### Surface System

Flexible depth system with opaque surface roles and two families of translucent veils — overlay (recedes) and lift (advances), each with subtle, soft, mild, firm, strong.

### Dark Mode

Automatic theme adaptation with color inversion. Toggle the `dark` class to switch between light and dark modes.

## Quick Example

Frontile components resolve semantic colors automatically:

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

<template>
  <Button @color='primary'>Click me</Button>
</template>
```

The Button already resolves its own semantic colors, so it adapts to light and dark themes without additional code. Under the hood the `primary` color provides the emphasis, while `on-primary` calculates the optimal contrasting text color (black or white) for accessibility — the same tokens you'd reach for on your own markup:

```gts preview
<template>
  <div class='bg-primary text-on-primary rounded px-4 py-2'>
    Your own element, same tokens
  </div>
</template>
```

## Theme Switching

Toggle between light and dark themes by adding or removing the `dark` class on a parent element (typically `<html>` or `<body>`):

```html
<html class="dark">
  <!-- Your content adapts to dark mode -->
</html>
```

Remove the `dark` class to revert to light theme. You can also explicitly use the `light` class if needed.

### How Theme Classes Work

Frontile uses custom CSS variants that apply theme-specific styles:

- **`.dark`** - When present on a parent element, all descendant elements use dark theme colors
- **`.light`** - When present on a parent element, all descendant elements use light theme colors (default)
- **`.theme-inverse`** - Inverts the current theme for a section and its descendants

The theme system uses CSS selectors to ensure proper inheritance:

```css
/* Light theme applies to .light elements and .theme-inverse within .dark */
.light *, .dark .theme-inverse *

/* Dark theme applies to .dark elements and .theme-inverse within .light */
.dark *, .light .theme-inverse *
```

This means you can nest themes and use theme-inverse sections anywhere in your application, and the colors will automatically adapt.

## Theme Inverse

Create sections with inverted theme colors using the `theme-inverse` utility class. In light mode, these sections display dark theme colors, and vice versa.

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

<template>
  <div class='space-y-8 p-8'>
    <div class='p-6 bg-surface-overlay-subtle rounded-lg'>
      <h3 class='text-lg font-bold text-neutral-strong mb-4'>Regular Theme</h3>
      <Button @color='primary'>Primary Button</Button>
    </div>

    <div class='theme-inverse p-6 bg-surface-canvas rounded-lg'>
      <div class='p-6 bg-surface-overlay-subtle rounded-lg'>
        <h3 class='text-lg font-bold text-neutral-strong mb-4'>Inverted Theme</h3>
        <Button @color='primary'>Primary Button</Button>
      </div>
    </div>
  </div>
</template>
```

[Learn more about theme-inverse →](configuration/theme-switching.md)

## Color System

Frontile provides six semantic color categories:

- **Neutral** - Default interface colors
- **Primary** - Primary brand colors (blue)
- **Accent** - Visual emphasis and highlights (violet)
- **Success** - Positive states and actions (green)
- **Danger** - Errors and destructive actions (red)
- **Warning** - Warnings and cautions (orange)

Each category spans two bands: a **surface band** of fills (`subtle`, `muted`, `soft`, `mild`, `DEFAULT`, `firm`) and an **ink band** of legible foregrounds (`strong`, `bolder`). The `on-{color}-{level}` prefix automatically provides optimal contrasting text colors (black or white) for accessibility.

<ColorPaletteGrid @category="primary" @showDescription={{false}} />
<ColorPaletteGrid @category="success" @showDescription={{false}} />
<ColorPaletteGrid @category="danger" @showDescription={{false}} />

### How Colors Adapt to Themes

Colors automatically adapt based on the current theme (`.dark`, `.light`, or `.theme-inverse`). Frontile uses CSS variables that change their values based on the theme context:

```css
/* Example: primary adapts to the theme */
.light {
  --color-primary: oklch(55.86% 0.2094 263.84);  /* Vivid teal in light mode */
}

.dark {
  --color-primary: oklch(69.83% 0.1526 252.37);  /* Lighter teal in dark mode */
}
```

When you use `bg-primary`, the actual color value comes from the CSS variable, which automatically switches based on whether the element is in a `.light` or `.dark` context.

### Using Colors in Your CSS

You can use semantic colors in custom CSS using the Tailwind `theme()` function or CSS variables:

```css
/* Using Tailwind theme function */
.my-component {
  background-color: theme(colors.primary.DEFAULT);
  color: theme(colors.on-primary.DEFAULT);
}

/* Using CSS variables directly */
.my-component {
  background-color: var(--color-primary);
  color: var(--color-on-primary);
}
```

### Customizing Colors

You can customize semantic colors using the JavaScript plugin configuration:

```js
const { frontile } = require('@frontile/theme/plugin');

module.exports = frontile({
  themes: {
    light: {
      colors: {
        primary: {
          subtle: '#eff6ff',
          soft: '#93c5fd',
          DEFAULT: '#3b82f6',
          strong: '#1e40af'
        }
      }
    },
    dark: {
      colors: {
        primary: {
          subtle: '#1e3a8a',
          soft: '#3b82f6',
          DEFAULT: '#60a5fa',
          strong: '#dbeafe'
        }
      }
    }
  }
});
```

[Learn more about semantic colors →](design-tokens/colors.md)

## Surface System

The Surface system provides two types of backgrounds:

- **Surface Solid** - Opaque base layers (0-11 scale)
- **Surface Overlay** - Translucent layers that recede into the page (subtle, soft, mild, firm, strong)
- **Surface Lift** - Translucent layers that float above the page (subtle, soft, mild, firm, strong)

<SurfaceShowcase @type="overlay" />

[Learn more about the surface system →](design-tokens/surfaces.md)

## Basic Customization

### Customizing Colors

Override semantic colors in your configuration:

```js
const { frontile } = require('@frontile/theme/plugin');

module.exports = frontile({
  themes: {
    light: {
      colors: {
        primary: {
          subtle: '#eff6ff',
          soft: '#93c5fd',
          DEFAULT: '#3b82f6',
          strong: '#1e40af'
        }
      }
    },
    dark: {
      colors: {
        primary: {
          subtle: '#1e3a8a',
          soft: '#3b82f6',
          DEFAULT: '#60a5fa',
          strong: '#dbeafe'
        }
      }
    }
  }
});

// Note: on-{color}-{level} classes are automatically generated
// based on the background colors you define above
```

### Setting Default Theme

Specify which theme loads by default:

```js
module.exports = frontile({
  defaultTheme: 'light', // or 'dark'
  themes: {
    // ... your themes
  }
});
```

## Advanced Configuration

### Customizing with CSS Variables

The recommended approach for Tailwind v4 is to customize theme values directly using CSS variables. This provides fine-grained control without JavaScript configuration and better performance.

#### Override Theme Defaults

Add your customizations in your `app/styles/app.css` after importing the theme:

```css title="app/styles/app.css"
@import 'tailwindcss' source('../../');
@plugin "@frontile/theme/plugin/default";
@import "@frontile/theme";

/* Override Tailwind theme utilities */
@theme {
  /* Custom border radius values */
  --radius: 0.75rem;        /* One knob: scales the whole rounded-* scale */
  --radius-pill: 2rem;      /* Custom pill radius (absolute, does not scale) */

  /* Custom opacity values */
  --opacity-hover: .9;
  --opacity-disabled: .4;
}

/* Override component-specific values */
:root {
  /* Modal sizes */
  --modal-md: 32rem;
  --modal-lg: 48rem;

  /* Drawer sizes */
  --drawer-md: 32rem;
  --drawer-lg: 48rem;
}
```

#### Theme-Specific Customization

Customize layout values for specific themes using the `.dark` and `.light` classes. **Important:** To properly target all instances of a theme including `.theme-inverse` sections, use both selectors:

```css
@import "@frontile/theme";

/* Light theme customization - targets .light AND .theme-inverse within .dark */
.light,
.dark .theme-inverse {
  --opacity-hover: .85;
}

/* Dark theme customization - targets .dark AND .theme-inverse within .light */
.dark,
.light .theme-inverse {
  --opacity-hover: .75;
  --modal-lg: 56rem;
}
```

**Why both selectors?**
- `.light` targets elements in light mode
- `.dark .theme-inverse` targets inverted sections within dark mode (which display light theme)
- This ensures your customizations apply consistently across both regular theme usage and theme-inverse sections

> **Note:** Variables in the `@theme` block automatically generate Tailwind utilities (e.g., `--radius-xl` creates `rounded-xl` class). Variables in `:root` or theme-specific selectors are for component-specific values that don't need utility classes. **Colors should be customized using the JavaScript plugin configuration, not CSS variables.**

### JavaScript Configuration

You can also configure the theme using JavaScript by creating a `frontile.js` file in your project root:

```js title="frontile.js" collapsible
const { frontile } = require('@frontile/theme/plugin');

module.exports = frontile({
  defaultTheme: 'dark',
  themes: {
    light: {
      colors: {
        // Customize semantic colors
        primary: {
          subtle: '#eff6ff',
          soft: '#93c5fd',
          DEFAULT: '#3b82f6',
          strong: '#1e40af'
        }
      },
      layout: {
        // Customize layout values
        opacity: {
          hover: .85,
          disabled: .4
        },
        radius: {
          DEFAULT: '0.75rem',
          pill: '2rem'
        }
      }
    },
    dark: {
      colors: {
        primary: {
          subtle: '#1e3a8a',
          soft: '#3b82f6',
          DEFAULT: '#60a5fa',
          strong: '#dbeafe'
        }
      }
    }
  }
});
```

Then reference it in your CSS:

```css
@import 'tailwindcss' source('../../');
@plugin "./../../frontile.js";
@import "@frontile/theme";
```

## Best Practices

### Use Semantic Colors

Always prefer semantic color classes over generic Tailwind utilities:

```hbs
{{! Good - uses semantic colors }}
<button class='bg-primary text-on-primary hover:bg-primary-soft'>
  Submit
</button>

{{! Avoid - hard-coded colors don't adapt to theme }}
<button class='bg-blue-500 text-white hover:bg-blue-400'>
  Submit
</button>
```

### Use Surface System for Backgrounds

Use the surface system for component backgrounds:

```hbs
{{! Good - uses a surface role for the base }}
<div class='bg-surface-app'>
  {{! Good - uses overlay for elevated surface }}
  <div class='bg-surface-overlay-soft rounded-lg p-4'>
    Card content
  </div>
</div>
```

### Test in Both Modes

Always verify your UI in both light and dark modes:

```html
<!-- Test light mode -->
<html class="light">
  <!-- Your app -->
</html>

<!-- Test dark mode -->
<html class="dark">
  <!-- Your app -->
</html>
```

---

# Component Styles

Source: /docs/theming/component-styles.md

# Customizing Component Styles

Frontile components can be customized with Tailwind Variants, either globally or per-instance. This guide covers both approaches.

## Overview

Frontile uses [Tailwind Variants](https://www.tailwind-variants.org/) to manage and customize component styles. Tailwind Variants provide a structured way to define different visual representations (or variants) for components while keeping your styles consistent and maintainable.

A **slot** represents a specific part of a component that can be styled or customized separately. Slots allow you to apply different styles to different parts of a complex component, providing more granular control.

When customizing styles in Frontile, you can either apply styles globally using `registerCustomStyles` or customize individual components using class arguments. You can override default component styles by passing your own class names to the `class` or `classes` argument, depending on whether the component has slots.

## DOM Anatomy: `data-component` and `data-part`

Every Frontile component renders a stable, documented DOM anatomy, independent
of its CSS classes. Two attributes carry it:

- **`data-component="<name>"`** — the kebab-cased `tv()` config name (e.g. the
  `notificationCard` config produces `notification-card`), written on the
  component's **outermost rendered element only**. This is the name the
  component is registered under, not its filename — `commandDialog` →
  `command-dialog`.
- **`data-part="<name>"`** — the kebab-cased `tv()` slot key, written on
  **every** element that renders a slot (`startContent` → `start-content`).
  Slot names are exactly the keys you already pass to `@classes`, so if you
  can style a part with `@classes={{hash startContent='...'}}`, you can also
  select it with `[data-part="start-content"]`.

The root element's part is usually `base`, but not always — it carries
whichever slot it actually renders. `Table`'s root is its wrapper `<div>`, so
that element is `data-part="wrapper"`; `SimpleTable` used on its own roots on
the `<table>` element, so that one is `data-part="table"`. `ProgressBar`'s
outer `<div>` renders no slot at all, so it has `data-component="progress-bar"`
and no `data-part`. Check the component's page if you need the exact shape.

Both attributes can be overridden: a `data-component` or `data-part` you pass
to a component wins over the one it would render itself.

A nested component's root legitimately carries **both** its own
`data-component` and a `data-part` belonging to its parent. `CloseButton`
rendered inside `Alert`, for instance, is simultaneously
`data-component="close-button"` (its own root) and `data-part="close-button"`
(the part it fills in `Alert`'s anatomy).

Two components can also render the same `data-component` value: `TabNav` is a
second renderer of the `tabs` config, alongside `Tabs` itself.

### Selecting by anatomy

Scope a selector to one component's own parts with:

```css
[data-component="modal"] [data-part="header"] {
  /* ... */
}
```

### Known limitation: a nested component can share a part name

`[data-component="x"] [data-part="y"]` is a plain CSS descendant combinator —
it matches **any** descendant, not just `y` parts that belong directly to
`x`. That's ambiguous whenever a nested component happens to have a part
with the same name. `Alert` renders a `CloseButton`, and `CloseButton` has
its own `icon` part (its SVG); `Alert` also has its own `icon` part (the
alert's leading icon). `[data-component="alert"] [data-part="icon"]` matches
both — the alert's own icon *and* the close button's icon glyph, because the
close button is a descendant of the alert's root.

What you usually mean is "the parts whose nearest `[data-component]` ancestor
is `x`". CSS has no "nearest enclosing" combinator, so in a stylesheet you
narrow the selector yourself, using child combinators down the path you want:

```css
/* The alert's own icon. The close button's icon is nested one level
   deeper, inside the close button, so it doesn't match. */
[data-component="alert"] > [data-part="inner"] > [data-part="icon"] {
  /* ... */
}
```

In tests, use the `ownParts(root, part)` helper from `frontile/test-support`,
which returns only the parts belonging to `root` itself:

```ts
import { ownParts } from 'frontile/test-support';

// Only Alert's own `icon` part, not CloseButton's.
const icons = ownParts(alertRootElement, 'icon');
```

### Not `data-slot`

If you're coming from shadcn/ui, Nuxt UI, or HeroUI, this convention will look
familiar but the attribute name differs — those use `data-slot`, Frontile uses
`data-part`. In Ember, "slot" already means a named block (`{{yield to="title"}}`),
which is a different thing from a styleable piece of the DOM.

`@frontile/forms-legacy` predates this convention and does not carry these
attributes.

## Customizing Styles

### Setting Up Global Customization

To apply global styles to your Frontile components, it's recommended to create a separate file for your theme settings. You can create a file named `app/theme.js` to register your global custom styles, and then import it in `app/app.js` to ensure the styles are applied across your application.

#### Example: Setting Up Global Styles

1. **Create a Theme File**: Create a new file called `app/theme.js` and add your global customizations.

   ```javascript
   // app/theme.js
   import { useStyles, registerCustomStyles, tv } from '@frontile/theme';

   const components = useStyles();

   registerCustomStyles({
     // stuff ...
   });
   ```

2. **Import the Theme File**: Import the theme file in `app/app.js` to ensure the global styles are applied.

   ```javascript
   // app/app.js
   import Application from '@ember/application';
   // stuff...
   import './theme'; // Import your theme file here

   export default class App extends Application {
     // stuff...
   }

   loadInitializers(App, config.modulePrefix);
   ```

### Global Customization with `registerCustomStyles`

The `registerCustomStyles` function allows you to override the default styles of Frontile components globally. This means that every instance of a specific component throughout your application will inherit the styles defined in `registerCustomStyles`.

#### Example: Global Customization

To globally change the styles of the Drawer, Modal, and Button components:

```javascript
import { useStyles, registerCustomStyles, tv } from '@frontile/theme';

const components = useStyles();

registerCustomStyles({
  modal: tv({
    extend: components.modal,
    slots: {
      header: 'font-header text-2xl pt-12 pl-6 pb-6',
      body: 'pt-4 pb-4 pl-6 pr-12',
      footer: 'bg-transparent py-4 px-12 pb-8'
    },
    variants: {
      size: {
        lg: 'max-w-[48rem]',
        xl: 'max-w-[64rem]'
      }
    }
  }),
  drawer: tv({
    extend: components.drawer,
    slots: {
      header: 'text-2xl px-4 py-6 bg-black text-white dark:bg-white dark:text-black rounded-none',
      footer: 'px-4 py-6'
    },
    variants: {
      size: {
        lg: 'max-w-[48rem]',
        xl: 'max-w-[64rem]'
      }
    }
  }),
  button: tv({
    ...components.button,
    base: ['font-header text-xl'],
    variants: {
      ...components.button.variants,
      appearance: {
        ...components.button.variants.appearance,
        default: 'shadow-elevation-2'
      }
    },
    compoundVariants: [
      ...components.button.compoundVariants,
      {
        appearance: 'default',
        intent: 'default',
        class: 'bg-black text-white hover:bg-black/80 dark:bg-white dark:text-black dark:hover:bg-white/80'
      }
    ]
  })
});
```

In this example:

- The `modal` component is customized globally, including changes to the header, body, and footer slots, and additional size variants.
- The `drawer` component is updated with new styles for the header and footer slots, as well as size variants.
- The `button` component's base styles and compound variants are customized, adding new default appearances.

Use global customization when you want consistency across your entire application for a particular component.

### Local Customization with Component Arguments

If you only need to customize the styles of a specific component instance, use arguments like `class` or `classes`, depending on the component. Frontile uses Tailwind Variants with `tw-merge` to merge Tailwind classes, so any class passed locally overwrites the default styles.

#### Example: Local Customization with Drawer Component

```hbs
<Drawer
  @isOpen={{true}}
  @classes={{hash
    header='bg-neutral-strong text-on-neutral-strong'
    body='bg-neutral-subtle'
    footer='bg-neutral-strong text-on-neutral-strong'
  }}
>
  <!-- Drawer content here -->
</Drawer>
```

In this example, the `Drawer` component is provided with specific styles for the `header`, `body`, and `footer` slots. The `header` and `footer` have a dark background (`bg-neutral-strong`) with automatically contrasting text (`text-on-neutral-strong`), while the `body` has a light background (`bg-neutral-subtle`). This approach allows for context-specific customizations without impacting other instances of the Drawer component.

---

# Design Tokens Overview

Source: /docs/theming/design-tokens/overview.md

# Design Tokens

Frontile extends Tailwind CSS with additional design tokens for building consistent, accessible user interfaces. These tokens automatically generate Tailwind utility classes.

## What are Design Tokens?

Design tokens are named entities that store visual design attributes. They provide a consistent language for design decisions across your application. Frontile's tokens use Tailwind v4's `@theme` directive to define CSS variables that automatically generate utility classes.

For example, defining `--radius: 8px` in your theme automatically generates the `rounded` utility class.

## Token Categories

Frontile adds these design token categories to Tailwind:

### [Colors](colors.md)

Semantic color system with five categories (neutral, primary, success, danger, warning) that automatically adapt between light and dark themes.

**Generated utilities:** `bg-primary`, `text-danger-strong`, `border-success-soft`

### [Typography](typography.md)

Text styles with semantic sizing across six categories (marquee, header, body, code, caption, label) built on a modular scale.

**Generated utilities:** `text-header-lg`, `text-body-md`, `text-label-sm`

### [Icons](icons.md)

Consistent icon sizing scale that pairs harmoniously with typography.

**Generated utilities:** `size-icon-sm`, `size-icon-md`, `size-icon-lg`

### [Borders](borders.md)

Border widths and radius tokens for consistent UI styling.

**Generated utilities:** `border-thin`, `border-heavy`, `rounded-xl`, `rounded-pill`

### [Elevation](elevation.md)

Shadow system for creating visual depth with six elevation levels (0-5).

**Generated utilities:** `shadow-elevation-1`, `shadow-elevation-3`

### [Surfaces](surfaces.md)

Background color system for creating distinct surface layers in your UI.

**Generated utilities:** `bg-surface-app`, `bg-surface-modal`, `bg-surface-overlay-soft`, `bg-surface-lift-soft`

## How Tokens Work

Frontile uses Tailwind v4's `@theme` directive to define tokens as CSS variables:

```css
@theme {
  --radius: 8px;           /* Generates: rounded */
  --radius-xl: 12px;       /* Generates: rounded-xl */
  --size-icon-md: 16px;    /* Generates: size-icon-md */
}
```

These variables:
- Automatically generate Tailwind utility classes
- Can be customized globally or per-theme
- Maintain consistency across your application
- Support light and dark theme variations

## Standard Tailwind Utilities

For layout, spacing, flexbox, grid, and other standard utilities, refer to the [Tailwind CSS documentation](https://tailwindcss.com/docs). Frontile uses Tailwind as-is for these utilities and only documents the design tokens it adds.

---

# Colors

Source: /docs/theming/design-tokens/colors.md

# Semantic Colors

Frontile's semantic color system provides meaningful, accessible colors that adapt automatically between light and dark themes.

## Overview

Instead of using arbitrary gray scales like `bg-gray-300`, Frontile's semantic colors use meaningful names that describe their purpose and visual weight. Each color automatically adapts between light and dark themes, ensuring consistent contrast and accessibility.

## Color Levels

Every category exposes the same set of levels, organized into **two bands**.
The bands share one emphasis vocabulary but are consumed by different CSS
properties — the band a level belongs to tells you what it's for.

| Band        | Levels (low → high emphasis)                              | Use for                                          |
| ----------- | ----------------------------------------------------------- | ------------------------------------------------ |
| **Surface** | `subtle` · `muted` · `soft` · `mild` · `DEFAULT` · `firm` | Fills — `bg-*` and decorative `border-*`         |
| **Ink**     | `strong` · `bolder`                                          | Legible foregrounds — `text-*`, outlined borders |

- **`DEFAULT`** is the resting fill. It has no suffix, so the bare class works:
  `bg-primary` is the DEFAULT fill, `text-primary` the DEFAULT-level text.
- **`mild`** sits between `soft` and `DEFAULT` — a lower-emphasis fill for
  cases where `soft` reads too faint but the full resting fill is too strong.
- **`firm`** is the most emphatic _fill_ (e.g. a pressed background). It sits at
  the top of the surface band, below the ink band it never competes with —
  `firm` is a background, `strong`/`bolder` are text, so they live in different
  property slots even though they share the ladder.
- **`on-{category}-{level}`** is the auto-generated black/white text that meets
  WCAG contrast on that fill (e.g. `text-on-primary` on `bg-primary`).

### Names are ranks, not brightness

A level name describes **emphasis rank**, never a specific lightness. The same
token can be dark in light mode and light in dark mode, because interaction
direction inverts between schemes (light mode lightens on hover and darkens on
press; dark mode does the reverse). A brightness word like "deep" or "light"
would be correct in one theme and wrong in the other, so the vocabulary stays
abstract.

### Why two bands instead of one numbered scale

Tailwind maps one token name to exactly one color value, reused across every
property (`bg-primary`, `text-primary`, and `border-primary` are always the
same color). A fill and the text that must stay legible on top of it are
different colors, so they can't share a single rung — they need two names. The
band split makes that boundary explicit instead of hiding it inside a flat
`50…900`-style scale.

## Color Categories

### Neutral

<ColorPaletteGrid @category="neutral" @showDescription={{true}} />

**Usage Examples:**

Text colors:

- `text-neutral-firm` - Secondary text for descriptions and metadata
- `text-neutral-strong` - Default text color for body content
- `text-neutral-bolder` - Maximum emphasis for headings

Background colors with automatic text colors:

- `bg-neutral-subtle` with `text-on-neutral-subtle` - Subtle background for hover states
- `bg-neutral-soft` with `text-on-neutral-soft` - Soft background for cards
- `bg-neutral` with `text-on-neutral` - Medium emphasis background
- `bg-neutral-strong` with `text-on-neutral-strong` - Strong emphasis background

### Primary

<ColorPaletteGrid @category="primary" @showDescription={{true}} />

**Usage Examples:**

```gts preview collapsible
<template>
  <div class='flex gap-4 flex-col'>
    {{! Filled Button }}
    <button
      class='bg-primary text-on-primary hover:bg-primary-soft px-4 py-2 rounded'
    >
      Filled Button
    </button>

    {{! Outlined Button }}
    <button
      class='border border-primary text-primary hover:bg-primary-subtle bg-transparent px-4 py-2 rounded'
    >
      Outlined Button
    </button>

    {{! Tonal Button }}
    <button
      class='bg-primary-subtle text-primary-strong hover:bg-primary-soft/20 px-4 py-2 rounded'
    >
      Tonal Button
    </button>

    {{! Text Button }}
    <button
      class='text-primary hover:bg-primary-subtle bg-transparent px-4 py-2 rounded'
    >
      Text Button
    </button>
  </div>
</template>
```

Banners:

```gts preview
<template>
  <div class='flex gap-4 flex-col'>
    {{! Filled Banner }}
    <div class='bg-primary text-on-primary p-4 rounded'>
      <div class='font-semibold'>Filled Banner</div>
      <div class='text-sm opacity-90'>High emphasis notification with brand
        colors</div>
    </div>

    {{! Tonal Banner }}
    <div class='bg-primary-subtle border border-primary-soft p-4 rounded'>
      <div class='text-primary-strong font-semibold'>Tonal Banner</div>
      <div class='text-primary-strong text-sm'>Subtle notification with brand
        colors</div>
    </div>
  </div>
</template>
```

### Accent

<ColorPaletteGrid @category="secondary" @showDescription={{true}} />

<ColorPaletteGrid @category="tertiary" @showDescription={{true}} />

**Usage Examples:**

```gts preview
<template>
  <div class='flex gap-4 flex-col'>
    {{! Accent Alert }}
    <div class='bg-secondary-subtle border border-secondary-soft p-4 rounded'>
      <div class='text-secondary-strong'>
        <div class='font-semibold'>New Feature!</div>
        <div class='text-sm'>Check out our latest updates and improvements.</div>
      </div>
    </div>

    {{! Accent Button }}
    <button
      class='bg-secondary text-on-secondary hover:bg-secondary-soft px-4 py-2 rounded'
    >
      Explore Features
    </button>
  </div>
</template>
```

### Success

<ColorPaletteGrid @category="success" @showDescription={{true}} />

**Usage Examples:**

```gts preview
<template>
  <div class='flex gap-4 flex-col'>
    {{! Success Alert }}
    <div class='bg-success-subtle border border-success-soft p-4 rounded'>
      <div class='text-success-strong'>
        <div class='font-semibold'>Success!</div>
        <div class='text-sm'>Your changes have been saved successfully.</div>
      </div>
    </div>

    {{! Success Button }}
    <button
      class='bg-success text-on-success hover:bg-success-soft px-4 py-2 rounded'
    >
      Confirm Action
    </button>
  </div>
</template>
```

### Danger

<ColorPaletteGrid @category="danger" @showDescription={{true}} />

**Usage Examples:**

```gts preview
<template>
  <div class='flex gap-4 flex-col'>
    {{! Error Alert }}
    <div class='bg-danger-subtle border border-danger-soft p-4 rounded'>
      <div class='text-danger-strong'>
        <div class='font-semibold'>Error</div>
        <div class='text-sm'>Failed to save changes. Please try again.</div>
      </div>
    </div>

    {{! Destructive Button }}
    <button
      class='bg-danger text-on-danger hover:bg-danger-soft px-4 py-2 rounded'
    >
      Delete Item
    </button>
  </div>
</template>
```

### Warning

<ColorPaletteGrid @category="warning" @showDescription={{true}} />

**Usage Examples:**

```gts preview
<template>
  <div class='flex gap-4 flex-col'>
    {{! Warning Alert }}
    <div class='bg-warning-subtle border border-warning-soft p-4 rounded'>
      <div class='text-warning-strong'>
        <div class='font-semibold'>Warning</div>
        <div class='text-sm'>This action cannot be undone.</div>
      </div>
    </div>

    {{! Warning Button }}
    <button class='bg-warning text-on-warning hover:bg-warning-soft rounded'>
      Proceed with Caution
    </button>
  </div>
</template>
```

## Choosing the Right Color Level

Pick from the band that matches the property you're setting.

### Backgrounds & decorative borders (surface band)

- **`subtle`**: Hover states, selected rows, tonal/hairline backgrounds
- **`muted`**: Hover on tonal fills, chip and close-button backgrounds
- **`soft`**: Card backgrounds, secondary surfaces, the hover step for solid fills
- **`DEFAULT`** (bare `bg-{color}`): Primary buttons, badges, tags, resting borders
- **`firm`**: Pressed/active backgrounds

### Text & outlined borders (ink band)

- **`strong`**: Default body text, readable content, outlined-control text and borders
- **`bolder`**: Headings, hover/active text, highest-emphasis foregrounds
- **`on-{color}-{level}`**: Automatic contrasting text on a colored fill (e.g., `text-on-primary` on `bg-primary`)

> **Note:** Surface-band levels (`subtle` … `firm`) are fills, not text colors.
> In dark mode they map to values that are illegible as text on dark surfaces.
> For visible text use an ink-band level (`strong`/`bolder`) or the matching
> `on-{color}` token.

## Accessibility

All color combinations in Frontile meet WCAG 2.1 Level AA contrast requirements (minimum 4.5:1 contrast ratio).

### Automatic "On-" Colors

Frontile automatically generates optimal contrasting text colors for every background color using WCAG contrast calculations. Use the `on-` prefix with the same color level:

```html
<!-- Automatically generates optimal text color (black or white) -->
<button class="bg-primary text-on-primary">
  <div class="bg-success-soft text-on-success-soft">
    <div class="bg-neutral-strong text-on-neutral-strong"></div>
  </div>
</button>
```

**How it works:**

1. Frontile calculates the relative luminance of each background color
2. Determines contrast ratio with both black and white text
3. Selects the color with better contrast (≥4.5:1 ratio)
4. Generates the appropriate `on-{color}-{level}` class automatically

**Benefits:**

- No need to manually determine text colors
- Always meets WCAG AA standards
- Automatically adapts to theme changes (light/dark mode)
- Works with custom theme colors

### Customizing On-Colors

While auto-generated on-colors work for most cases, you can override them for brand consistency or specific design requirements:

```js
const { frontile } = require('@frontile/theme/plugin');

module.exports = frontile({
  themes: {
    light: {
      colors: {
        primary: {
          subtle: '#eff6ff',
          soft: '#93c5fd',
          DEFAULT: '#3b82f6',
          strong: '#1e40af'
        },
        // Override specific on-colors
        'on-primary': {
          DEFAULT: '#ffffff', // Force white text on the bare primary fill
          strong: '#e0f2fe' // Use light blue instead of auto-generated white
        }
        // on-primary-subtle and on-primary-soft are still auto-generated
      }
    }
  }
});
```

Partial overrides are supported — only define the levels you want to customize, and the rest will be auto-generated as usual. This works for all semantic color categories: `on-neutral`, `on-primary`, `on-secondary`, `on-tertiary`, `on-success`, `on-warning`, `on-danger`, and `on-surface-modal`.

> **Note:** If a color value is a CSS variable reference (e.g., `var(--my-color)`), auto-generation is skipped for that color since contrast cannot be calculated at build time.

## Migrating from Old Colors

If you're upgrading from an older version of Frontile, see the [Semantic Colors v2 Migration Guide](../../migrations/v0.18/semantic-colors.md) for detailed instructions on updating your code.

---

# Typography

Source: /docs/theming/design-tokens/typography.md

# Typography System

Frontile's typography system is a scalable type system built on semantic text styles and a modular scale. It uses Tailwind v4's `@theme` directive for base tokens and `@layer utilities` for explicit utility classes.

## Overview

The typography system includes:

- **7 text style categories**: Marquee, Header, Strong, Body, Code, Caption, and Label
- **Multiple size variants** for each category
- **Modular scale** based on a mathematical ratio for harmonic sizing
- **Composite utility classes** that bundle all typography properties together
- **Full customization** through CSS variables

## Text Style Categories

### Marquee

Large, semibold serif display text (Domine) for hero sections and prominent headings.

```gts preview
<template>
  <div class='flex flex-col gap-6'>
    <div class='font-marquee text-marquee-3xl'>Marquee 3XL: Hero Heading</div>
    <div class='font-marquee text-marquee-2xl'>Marquee 2XL: Large Display</div>
    <div class='font-marquee text-marquee-xl'>Marquee XL: Display</div>
    <div class='font-marquee text-marquee-lg'>Marquee LG: Section Display</div>
    <div class='font-marquee text-marquee-md'>Marquee MD: Medium Display</div>
    <div class='font-marquee text-marquee-sm'>Marquee SM: Small Display</div>
  </div>
</template>
```

**Available sizes:** `5xs`, `4xs`, `3xs`, `2xs`, `xs`, `sm`, `md`, `lg`, `xl`, `2xl`, `3xl`
**Font:** Domine (serif) · **Weight:** semibold · **Best for:** Hero sections, landing page titles, major marketing headings

### Header

Semantic headings for content hierarchy with bold weight; larger sizes (`lg` and up) tighten tracking and leading.

```gts preview
<template>
  <div class='flex flex-col gap-4'>
    <h1 class='font-header text-header-3xl'>Header 3XL: Page Title</h1>
    <h2 class='font-header text-header-2xl'>Header 2XL: Major Section</h2>
    <h3 class='font-header text-header-xl'>Header XL: Section Title</h3>
    <h4 class='font-header text-header-lg'>Header LG: Subsection</h4>
    <h5 class='font-header text-header-md'>Header MD: Subheading</h5>
    <h6 class='font-header text-header-sm'>Header SM: Minor Heading</h6>
    <div class='font-header text-header-xs'>Header XS: Small Heading</div>
    <div class='font-header text-header-2xs'>Header 2XS: Tiny Heading</div>
    <div class='font-header text-header-3xs'>Header 3XS: Micro Heading</div>
    <div class='font-header text-header-4xs'>Header 4XS: Nano Heading</div>
  </div>
</template>
```

**Available sizes:** `4xs`, `3xs`, `2xs`, `xs`, `sm`, `md`, `lg`, `xl`, `2xl`, `3xl`
**Best for:** Content headings (h1-h6), section titles, hierarchical structure

### Strong

Emphasis text for numerics, prices, and metrics. Shares the Header size, tracking, and leading scale but is a distinct role so it can be styled independently.

```gts preview
<template>
  <div class='flex flex-col gap-4'>
    <div class='font-header text-strong-3xl'>$1,299</div>
    <div class='font-header text-strong-xl'>2 Gbps</div>
    <div class='font-header text-strong-md'>99.99% uptime</div>
    <div class='font-header text-strong-sm'>12 included</div>
  </div>
</template>
```

**Available sizes:** `4xs`, `3xs`, `2xs`, `xs`, `sm`, `md`, `lg`, `xl`, `2xl`, `3xl`
**Font:** Open Sans · **Weight:** bold · **Best for:** Prices, counts, metrics, any numeric emphasis

### Body

Standard body text with spacious line height optimized for readability.

```gts preview collapsible
<template>
  <div class='flex flex-col gap-6'>
    <p class='font-body text-body-3xl'>
      Body 3XL: The quick brown fox jumps over the lazy dog. This is 3XL body text with spacious line height for comfortable reading.
    </p>
    <p class='font-body text-body-2xl'>
      Body 2XL: The quick brown fox jumps over the lazy dog. This is 2XL body text with spacious line height for comfortable reading.
    </p>
    <p class='font-body text-body-xl'>
      Body XL: The quick brown fox jumps over the lazy dog. This is extra large body text with spacious line height for comfortable reading.
    </p>
    <p class='font-body text-body-lg'>
      Body LG: The quick brown fox jumps over the lazy dog. This is large body text with spacious line height for comfortable reading.
    </p>
    <p class='font-body text-body-md'>
      Body MD: The quick brown fox jumps over the lazy dog. This is default body text with spacious line height for comfortable reading.
    </p>
    <p class='font-body text-body-sm'>
      Body SM: The quick brown fox jumps over the lazy dog. This is small body text with spacious line height for comfortable reading.
    </p>
    <p class='font-body text-body-xs'>
      Body XS: The quick brown fox jumps over the lazy dog. This is extra small body text.
    </p>
    <p class='font-body text-body-2xs'>
      Body 2XS: The quick brown fox jumps over the lazy dog. This is 2XS body text.
    </p>
    <p class='font-body text-body-3xs'>
      Body 3XS: The quick brown fox jumps over the lazy dog. This is 3XS body text.
    </p>
    <p class='font-body text-body-4xs'>
      Body 4XS: The quick brown fox jumps over the lazy dog. This is 4XS body text.
    </p>
    <p class='font-body text-body-5xs'>
      Body 5XS: The quick brown fox jumps over the lazy dog. This is 5XS body text.
    </p>
  </div>
</template>
```

**Available sizes:** `5xs`, `4xs`, `3xs`, `2xs`, `xs`, `sm`, `md`, `lg`, `xl`, `2xl`, `3xl`
**Best for:** Paragraphs, article content, descriptions, general text

### Code

Monospace text for code snippets and technical content.

```gts preview
<template>
  <div class='flex flex-col gap-3'>
    <code class='font-code text-code-md bg-neutral-subtle px-2 py-1 rounded'>
      const greeting = "Hello, World!";
    </code>
    <code class='font-code text-code-sm bg-neutral-subtle px-2 py-1 rounded'>
      npm install frontile
    </code>
  </div>
</template>
```

**Available sizes:** `sm`, `md`
**Best for:** Code blocks, inline code, technical identifiers

### Caption

Secondary descriptive text with relaxed letter spacing.

```gts preview
<template>
  <div class='flex flex-col gap-3'>
    <div>
      <div class='bg-neutral-subtle rounded mb-2 h-32 flex items-center justify-center text-neutral-strong'>
        Example Image
      </div>
      <span class='font-caption text-caption-md text-neutral-strong'>Caption MD: Figure 1 - Example image caption with medium size</span>
    </div>
    <div>
      <span class='font-caption text-caption-sm text-neutral-strong'>Caption SM: Small caption text for supplementary information</span>
    </div>
  </div>
</template>
```

**Available sizes:** `sm`, `md`
**Best for:** Image captions, figure labels, supplementary text

### Label

UI labels and form labels with semibold weight and tight (100%) leading.

```gts preview
<template>
  <div class='flex flex-col gap-3'>
    <div class='font-label text-label-3xl'>Label 3XL: Extra Large Label</div>
    <div class='font-label text-label-2xl'>Label 2XL: Double Extra Large Label</div>
    <div class='font-label text-label-xl'>Label XL: Extra Large Label</div>
    <div class='font-label text-label-lg'>Label LG: Large Label</div>
    <div class='font-label text-label-md'>Label MD: Medium Label</div>
    <div class='font-label text-label-sm'>Label SM: Small Label</div>
    <div class='font-label text-label-xs'>Label XS: Extra Small Label</div>
    <div class='font-label text-label-2xs'>Label 2XS: Double Extra Small Label</div>
    <div class='font-label text-label-micro'>Label Micro: Micro Label</div>
    <div class='font-label text-label-nano'>Label Nano: Nano Label</div>
  </div>
</template>
```

**Available sizes:** `nano`, `micro`, `2xs`, `xs`, `sm`, `md`, `lg`, `xl`, `2xl`, `3xl`
**Best for:** Form labels, UI labels, buttons, navigation items, badges

## Available Utilities

All text style utilities require both a font-family utility and a sized text style utility:

```html
<!-- Complete typography requires both font-family and sized text style -->
<h1 class="font-marquee text-marquee-xl">...</h1>
<h2 class="font-header text-header-md">...</h2>
<p class="font-body text-body-md">...</p>
<code class="font-code text-code-sm">...</code>
<span class="font-caption text-caption-md">...</span>
<label class="font-label text-label-sm">...</label>
```

## Combining with Other Utilities

Typography utilities work with other Tailwind utilities:

```gts preview
<template>
  <div class='flex flex-col gap-4'>
    {{! Colored header }}
    <h2 class='font-header text-header-xl text-primary-strong'>Colored Header</h2>

    {{! Truncated body text }}
    <p class='font-body text-body-md truncate max-w-md'>
      This is a very long paragraph that will be truncated with an ellipsis when it exceeds the maximum width.
    </p>

    {{! Centered caption }}
    <span class='font-caption text-caption-md text-center block text-neutral-strong'>
      Centered caption text
    </span>

    {{! Responsive header }}
    <h1 class='font-header text-header-lg md:text-header-xl lg:text-header-2xl'>
      Responsive Heading
    </h1>
  </div>
</template>
```

## How It Works

The typography system uses Tailwind v4's `@theme` directive to automatically generate utilities from CSS variables:

1. **Base tokens** defined in `@theme` automatically generate individual utilities:
   - `--font-header` → `font-header` utility
   - `--font-size-14` → `text-14` utility
   - `--font-weight-bold` → `font-bold` utility
   - `--letter-spacing-tight` → `tracking-tight` utility
   - `--font-weight-semibold` → `font-semibold` utility

2. **Composite text style tokens** generate size/weight/spacing utilities (but NOT font-family):
   - `--text-header-md` → `text-header-md` utility (sets size, weight, spacing, line-height)
   - `--text-body-lg` → `text-body-lg` utility (sets size, weight, spacing, line-height)

**Usage pattern:** Combine font-family with text style for complete typography:

```html
<!-- ✓ Correct: Combine font-family with text style -->
<h2 class="font-header text-header-md">Heading Text</h2>
<p class="font-body text-body-lg">Body text with larger size</p>
<span class="font-label text-label-sm">Small label</span>

<!-- ✗ Incomplete: Missing font-family -->
<h2 class="text-header-md">Heading Text</h2>
```

The separation of font-family from text styles provides flexibility to mix font families with different text styles while maintaining consistent sizing, weight, spacing, and line-height.

## Customization

### Using CSS Variables

Customize typography by overriding CSS variables in your app's CSS file:

```css
@import "@frontile/theme";

/* Override font families */
@theme {
  --font-header: "Inter", system-ui, sans-serif;
  --font-body: "Inter", system-ui, sans-serif;
  --font-code: "JetBrains Mono", monospace;
}
```

### Theme-Specific Typography

Customize for light and dark themes using theme selectors:

```css
/* Light theme customization */
.light,
.dark .theme-inverse {
  --font-body: "Inter", system-ui, sans-serif;
}

/* Dark theme customization */
.dark,
.light .theme-inverse {
  --font-body: "Geist", system-ui, sans-serif;
}
```

## Using Custom Fonts

Add custom fonts by declaring them with `@font-face` and overriding the font family variables:

```css
@font-face {
  font-family: 'Inter';
  src: url('/fonts/inter-var.woff2') format('woff2');
  font-weight: 100 900;
  font-display: swap;
}

@theme {
  --font-header: 'Inter', system-ui, sans-serif;
  --font-body: 'Inter', system-ui, sans-serif;
  --font-label: 'Inter', system-ui, sans-serif;
}
```

## Best Practices

### Use Semantic Text Styles

Always prefer semantic text style utilities over combining individual properties:

```gts preview
<template>
  <div class='flex flex-col gap-4'>
    {{! Good - semantic text style }}
    <h2 class='font-header text-header-lg text-primary-strong'>
      ✓ Semantic: Easy to maintain
    </h2>

    {{! Avoid - manual combination }}
    <h2 class='text-2xl font-bold leading-tight tracking-tight text-primary-strong'>
      ✗ Manual: Harder to maintain
    </h2>
  </div>
</template>
```

### Maintain Visual Hierarchy

Use size variants to create clear content hierarchy:

```gts preview
<template>
  <article class='space-y-4'>
    <h1 class='font-header text-header-3xl text-neutral-strong'>Article Title</h1>
    <p class='font-body text-body-md text-neutral-strong'>Published on December 7, 2024</p>

    <div class='space-y-3'>
      <h2 class='font-header text-header-xl text-neutral-strong'>Major Section</h2>
      <p class='font-body text-body-md text-neutral-firm'>
        This is the main body content with comfortable line height for easy reading. The text flows naturally and maintains good readability.
      </p>

      <h3 class='font-header text-header-lg text-neutral-strong'>Subsection</h3>
      <p class='font-body text-body-md text-neutral-firm'>
        Subsection content continues the hierarchy with appropriately sized headers.
      </p>

      <span class='font-caption text-caption-sm text-neutral-strong block'>
        Figure 1: Caption providing additional context
      </span>
    </div>
  </article>
</template>
```

### Responsive Typography

Scale typography for different screen sizes:

```gts preview
<template>
  <div class='space-y-4'>
    <h1 class='font-header text-header-lg md:text-header-xl lg:text-header-2xl text-neutral-strong'>
      Responsive Heading
    </h1>
    <p class='font-body text-body-sm md:text-body-md lg:text-body-lg text-neutral-firm'>
      Body text that scales up on larger screens for better readability across all devices.
    </p>
  </div>
</template>
```

---

# Icon Sizes

Source: /docs/theming/design-tokens/icons.md

# Icon Sizes

Frontile provides an icon sizing scale that pairs with typography for consistent visual alignment.

## Overview

Icon sizes ensure visual consistency between icons and text throughout your interface. They use the same modular scale as typography, making it easy to pair icons with text styles.

The scale ranges from `pico` (smallest) to `mega` (largest), providing 14 distinct sizes for different UI contexts.

## Using Icon Sizes

Apply icon sizes using the `size-icon-*` utilities, which set both width and height:

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

<template>
  <div class='flex items-center gap-6'>
    <StarIcon class='size-icon-sm text-primary' />
    <StarIcon class='size-icon-md text-primary' />
    <StarIcon class='size-icon-lg text-primary' />
    <StarIcon class='size-icon-xl text-primary' />
  </div>
</template>
```

## Available Sizes

| Size | Utility | Usage Context |
|------|---------|---------------|
| Pico | `size-icon-pico` | Extremely small UI elements |
| Nano | `size-icon-nano` | Tiny decorative icons |
| Micro | `size-icon-micro` | Very small inline icons |
| 3XS | `size-icon-3xs` | Extra extra small icons |
| 2XS | `size-icon-2xs` | Extra small icons |
| XS | `size-icon-xs` | Small inline icons |
| SM | `size-icon-sm` | Small UI icons |
| MD | `size-icon-md` | Default icon size |
| LG | `size-icon-lg` | Large prominent icons |
| XL | `size-icon-xl` | Extra large icons |
| 2XL | `size-icon-2xl` | Double extra large icons |
| 3XL | `size-icon-3xl` | Triple extra large icons |
| Kilo | `size-icon-kilo` | Very large decorative icons |
| Mega | `size-icon-mega` | Largest decorative icons |

## All Icon Sizes

Here are all available icon sizes with visual examples:

```gts preview collapsible
import { CheckIcon } from 'site/components/icons';

<template>
  <div class='grid grid-cols-2 md:grid-cols-3 lg:grid-cols-4 gap-4'>
    <div class='flex items-center gap-3 p-3 border border-neutral rounded'>
      <CheckIcon class='size-icon-pico text-primary' />
      <div>
        <div class='font-medium'>Pico</div>
        <code class='text-xs'>size-icon-pico</code>
      </div>
    </div>
    <div class='flex items-center gap-3 p-3 border border-neutral rounded'>
      <CheckIcon class='size-icon-nano text-primary' />
      <div>
        <div class='font-medium'>Nano</div>
        <code class='text-xs'>size-icon-nano</code>
      </div>
    </div>
    <div class='flex items-center gap-3 p-3 border border-neutral rounded'>
      <CheckIcon class='size-icon-micro text-primary' />
      <div>
        <div class='font-medium'>Micro</div>
        <code class='text-xs'>size-icon-micro</code>
      </div>
    </div>
    <div class='flex items-center gap-3 p-3 border border-neutral rounded'>
      <CheckIcon class='size-icon-3xs text-primary' />
      <div>
        <div class='font-medium'>3XS</div>
        <code class='text-xs'>size-icon-3xs</code>
      </div>
    </div>
    <div class='flex items-center gap-3 p-3 border border-neutral rounded'>
      <CheckIcon class='size-icon-2xs text-primary' />
      <div>
        <div class='font-medium'>2XS</div>
        <code class='text-xs'>size-icon-2xs</code>
      </div>
    </div>
    <div class='flex items-center gap-3 p-3 border border-neutral rounded'>
      <CheckIcon class='size-icon-xs text-primary' />
      <div>
        <div class='font-medium'>XS</div>
        <code class='text-xs'>size-icon-xs</code>
      </div>
    </div>
    <div class='flex items-center gap-3 p-3 border border-neutral rounded'>
      <CheckIcon class='size-icon-sm text-primary' />
      <div>
        <div class='font-medium'>SM</div>
        <code class='text-xs'>size-icon-sm</code>
      </div>
    </div>
    <div class='flex items-center gap-3 p-3 border border-neutral rounded'>
      <CheckIcon class='size-icon-md text-primary' />
      <div>
        <div class='font-medium'>MD</div>
        <code class='text-xs'>size-icon-md</code>
      </div>
    </div>
    <div class='flex items-center gap-3 p-3 border border-neutral rounded'>
      <CheckIcon class='size-icon-lg text-primary' />
      <div>
        <div class='font-medium'>LG</div>
        <code class='text-xs'>size-icon-lg</code>
      </div>
    </div>
    <div class='flex items-center gap-3 p-3 border border-neutral rounded'>
      <CheckIcon class='size-icon-xl text-primary' />
      <div>
        <div class='font-medium'>XL</div>
        <code class='text-xs'>size-icon-xl</code>
      </div>
    </div>
    <div class='flex items-center gap-3 p-3 border border-neutral rounded'>
      <CheckIcon class='size-icon-2xl text-primary' />
      <div>
        <div class='font-medium'>2XL</div>
        <code class='text-xs'>size-icon-2xl</code>
      </div>
    </div>
    <div class='flex items-center gap-3 p-3 border border-neutral rounded'>
      <CheckIcon class='size-icon-3xl text-primary' />
      <div>
        <div class='font-medium'>3XL</div>
        <code class='text-xs'>size-icon-3xl</code>
      </div>
    </div>
    <div class='flex items-center gap-3 p-3 border border-neutral rounded'>
      <CheckIcon class='size-icon-kilo text-primary' />
      <div>
        <div class='font-medium'>Kilo</div>
        <code class='text-xs'>size-icon-kilo</code>
      </div>
    </div>
    <div class='flex items-center gap-3 p-3 border border-neutral rounded'>
      <CheckIcon class='size-icon-mega text-primary' />
      <div>
        <div class='font-medium'>Mega</div>
        <code class='text-xs'>size-icon-mega</code>
      </div>
    </div>
  </div>
</template>
```

## Pairing with Typography

Icon sizes are designed to pair harmoniously with text styles. Use these recommended pairings for visual alignment:

```gts preview
import { CheckIcon, ViewIcon, StarIcon } from 'site/components/icons';

<template>
  <div class='flex flex-col gap-4'>
    {{! Small icon pairing }}
    <div class='flex items-center gap-2'>
      <CheckIcon class='size-icon-xs text-success' />
      <span>Small text with size-icon-xs</span>
    </div>

    {{! Medium icon pairing }}
    <div class='flex items-center gap-2'>
      <ViewIcon class='size-icon-md text-primary' />
      <span>Default text with size-icon-md</span>
    </div>

    {{! Large icon pairing }}
    <div class='flex items-center gap-2'>
      <StarIcon class='size-icon-lg text-warning' />
      <span>Larger text with size-icon-lg</span>
    </div>

    {{! Extra large icon pairing }}
    <div class='flex items-center gap-3'>
      <CheckIcon class='size-icon-xl text-danger' />
      <h2>Header with size-icon-xl</h2>
    </div>
  </div>
</template>
```

### Recommended Pairings

| Text Style | Recommended Icon Size |
|------------|----------------------|
| `text-body-sm` | `size-icon-xs` or `size-icon-sm` |
| `text-body-md` | `size-icon-sm` or `size-icon-md` |
| `text-body-lg` | `size-icon-md` or `size-icon-lg` |
| `text-header-sm` | `size-icon-md` |
| `text-header-md` | `size-icon-md` or `size-icon-lg` |
| `text-header-lg` | `size-icon-lg` or `size-icon-xl` |
| `text-header-xl` | `size-icon-xl` or `size-icon-2xl` |

## Customization

Override icon sizes using CSS variables in your `@theme` block:

```css
@import "@frontile/theme";

@theme {
  /* Adjust specific sizes */
  --size-icon-sm: 14px;
  --size-icon-md: 18px;
  --size-icon-lg: 22px;
}
```

For more customization options, see the [Configuration Guide](../configuration/customization.md).

---

# Borders & Radius

Source: /docs/theming/design-tokens/borders.md

# Borders & Radius

Frontile provides border width and radius tokens for consistent UI styling across your application.

## Border Widths

Control border thickness with semantic width tokens. These tokens provide meaningful names that describe the visual weight of borders.

### Available Widths

```gts preview
<template>
  <div class='flex gap-6 flex-wrap items-center'>
    <div class='border-thin border-neutral bg-surface-canvas p-6 rounded'>
      <div class='text-label-sm mb-1'>Thin</div>
      <div class='text-body-xs text-neutral-strong'>Subtle borders</div>
    </div>
    <div class='border border-neutral bg-surface-canvas p-6 rounded'>
      <div class='text-label-sm mb-1'>Default</div>
      <div class='text-body-xs text-neutral-strong'>Standard borders</div>
    </div>
    <div class='border-heavy border-neutral bg-surface-canvas p-6 rounded'>
      <div class='text-label-sm mb-1'>Heavy</div>
      <div class='text-body-xs text-neutral-strong'>Emphasized borders</div>
    </div>
    <div class='border-aggressive border-neutral bg-surface-canvas p-6 rounded'>
      <div class='text-label-sm mb-1'>Aggressive</div>
      <div class='text-body-xs text-neutral-strong'>Strong emphasis</div>
    </div>
  </div>
</template>
```

| Width | Utility | Common Uses |
|-------|---------|-------------|
| Thin | `border-thin` | Subtle dividers, table borders, minimal separation |
| Default | `border` | Standard card borders, input fields, default UI elements |
| Heavy | `border-heavy` | Focus states, selected items, emphasized borders |
| Aggressive | `border-aggressive` | High-contrast borders, debug indicators, strong emphasis |

### Border Width Examples

```gts preview
<template>
  <div class='space-y-4'>
    {{! Subtle card }}
    <div class='border-thin border-neutral rounded p-4'>
      <h3 class='text-header-sm mb-2'>Subtle Card</h3>
      <p class='text-body-sm text-neutral-strong'>Uses thin border for minimal visual weight</p>
    </div>

    {{! Standard input }}
    <input
      type='text'
      placeholder='Standard input field'
      class='w-full border border-neutral rounded px-4 py-2 focus:outline-none focus:ring-2 focus:ring-primary'
    />

    {{! Selected item with heavy border }}
    <div class='border-heavy border-primary rounded p-4 bg-primary-subtle'>
      <h3 class='text-header-sm mb-2 text-primary-strong'>Selected Item</h3>
      <p class='text-body-sm text-primary-strong'>Uses heavy border to show selection</p>
    </div>
  </div>
</template>
```

## Border Radius

Control corner rounding with radius tokens that range from sharp edges to fully rounded elements.

Every step is a multiple of a single `--radius` base (`0.5rem` by default), so
the scale is proportional rather than arbitrary. Changing `--radius` alone
re-rounds the entire library — see [Scaling the whole system](#scaling-the-whole-system) below.

### Available Radii

```gts preview collapsible
<template>
  <div class='grid grid-cols-2 md:grid-cols-4 gap-4'>
    <div class='rounded-none bg-primary-subtle p-4 flex items-center justify-center min-h-24'>
      <span class='text-label-sm'>None</span>
    </div>
    <div class='rounded-xs bg-primary-subtle p-4 flex items-center justify-center min-h-24'>
      <span class='text-label-sm'>XS</span>
    </div>
    <div class='rounded-sm bg-primary-subtle p-4 flex items-center justify-center min-h-24'>
      <span class='text-label-sm'>SM</span>
    </div>
    <div class='rounded-md bg-primary-subtle p-4 flex items-center justify-center min-h-24'>
      <span class='text-label-sm'>MD</span>
    </div>
    <div class='rounded bg-primary-subtle p-4 flex items-center justify-center min-h-24'>
      <span class='text-label-sm'>Default</span>
    </div>
    <div class='rounded-lg bg-primary-subtle p-4 flex items-center justify-center min-h-24'>
      <span class='text-label-sm'>LG</span>
    </div>
    <div class='rounded-xl bg-primary-subtle p-4 flex items-center justify-center min-h-24'>
      <span class='text-label-sm'>XL</span>
    </div>
    <div class='rounded-2xl bg-primary-subtle p-4 flex items-center justify-center min-h-24'>
      <span class='text-label-sm'>2XL</span>
    </div>
    <div class='rounded-3xl bg-primary-subtle p-4 flex items-center justify-center min-h-24'>
      <span class='text-label-sm'>3XL</span>
    </div>
    <div class='rounded-4xl bg-primary-subtle p-4 flex items-center justify-center min-h-24'>
      <span class='text-label-sm'>4XL</span>
    </div>
    <div class='rounded-default bg-primary-subtle p-4 flex items-center justify-center min-h-24'>
      <span class='text-label-sm'>Default (Custom)</span>
    </div>
    <div class='rounded-pill bg-primary-subtle px-6 py-4 flex items-center justify-center min-h-24'>
      <span class='text-label-sm'>Pill</span>
    </div>
  </div>
</template>
```

| Radius | Utility | Multiplier | Default | Common Uses |
|--------|---------|-----------|---------|-------------|
| None | `rounded-none` | — | 0px | Sharp corners, technical interfaces, no rounding |
| XS | `rounded-xs` | 0.25x | 2px | Hairline rounding on very small marks |
| SM | `rounded-sm` | 0.5x | 4px | Keyboard shortcuts, checkboxes, tight layouts |
| MD | `rounded-md` | 0.75x | 6px | Compact controls, inline chips |
| Default | `rounded` | 1x | 8px | The base unit itself |
| LG | `rounded-lg` | 1x | 8px | Menu items nested inside a popover |
| XL | `rounded-xl` | 1.5x | 12px | Inputs, selects, popovers, dropdowns, notifications |
| 2XL | `rounded-2xl` | 2x | 16px | Modals, drawers |
| Default (Custom) | `rounded-default` | 2.5x | 20px | Tables, skeletons, soft friendly corners |
| 3XL | `rounded-3xl` | 3x | 24px | Oversized surfaces |
| 4XL | `rounded-4xl` | 4x | 32px | Hero-scale surfaces |
| Pill | `rounded-pill` | — | 9999px | Pills, badges, fully rounded buttons |

`rounded-none` and `rounded-pill` are absolutes: they stay 0 and 9999px no
matter what `--radius` is set to.

## Combining Borders and Radius

Use border widths and radius together to create various UI patterns:

```gts preview
<template>
  <div class='space-y-4'>
    {{! Alert with thin border and soft corners }}
    <div class='border-thin border-success-soft bg-success-subtle rounded-xl p-4'>
      <h4 class='text-label-md text-success-strong mb-1'>Success</h4>
      <p class='text-body-sm text-success-strong'>Your changes have been saved successfully.</p>
    </div>

    {{! Warning with heavy border and default corners }}
    <div class='border-heavy border-warning bg-warning-subtle rounded p-4'>
      <h4 class='text-label-md text-warning-strong mb-1'>Warning</h4>
      <p class='text-body-sm text-warning-strong'>This action cannot be undone.</p>
    </div>

    {{! Error with aggressive border and sharp corners }}
    <div class='border-aggressive border-danger bg-danger-subtle rounded-sm p-4'>
      <h4 class='text-label-md text-danger-strong mb-1'>Error</h4>
      <p class='text-body-sm text-danger-strong'>Failed to save changes. Please try again.</p>
    </div>
  </div>
</template>
```

## Best Practices

### Maintain Consistency

Use consistent border styles for similar UI elements throughout your application:

- **Forms**: Use default border width with default or small radius
- **Cards**: Use thin borders with medium to large radius
- **Alerts**: Use thin to heavy borders with appropriate radius for the context
- **Buttons**: Use default radius or pill for interactive elements

### Visual Hierarchy

Use border weights to establish hierarchy:

- **Thin**: Background elements, subtle divisions
- **Default**: Primary UI elements
- **Heavy**: Active states, selections, focus indicators
- **Aggressive**: Critical states, errors, important boundaries

### Radius and Component Size

Pair border radius with component size:

- **Small components** (badges, small buttons): Use `rounded` or `rounded-sm`
- **Medium components** (buttons, inputs): Use `rounded` or `rounded-md`
- **Large components** (cards, panels): Use `rounded-lg` or `rounded-xl`
- **Extra large components** (heroes, features): Use `rounded-xl` or `rounded-2xl`

## Customization

Override border widths and radius using CSS variables:

```css
@import "@frontile/theme";

@theme {
  /* Customize border widths */
  --border-width-thin: 1px;
  --border-width-default: 1.5px;
  --border-width-heavy: 3px;

  /* Customize border radius — one knob for the whole scale */
  --radius: 0.75rem;
}
```

### Scaling the whole system

Because every step is `calc(var(--radius) * n)`, one value controls how round
the entire library looks. Nothing else has to change:

| `--radius` | Menus / inputs | Menu items | Modals |
|-----------|----------------|-----------|--------|
| `0` | 0px | 0px | 0px |
| `0.25rem` | 6px | 4px | 8px |
| `0.5rem` (default) | 12px | 8px | 16px |
| `0.75rem` | 18px | 12px | 24px |
| `1rem` | 24px | 16px | 32px |

The same knob is available from the JavaScript plugin config, where it can also
differ per theme:

```js
frontile({
  layout: {
    radius: { DEFAULT: '0.75rem' }
  }
});
```

Individual steps remain overridable when you need to break one out of the
proportional scale:

```css
@theme {
  --radius: 0.5rem;
  --radius-2xl: 28px; /* modals rounder than the scale would give */
}
```

For more customization options, see the [Configuration Guide](../configuration/customization.md).

---

# Surfaces

Source: /docs/theming/design-tokens/surfaces.md

# Surface System

The Surface system creates depth and hierarchy in your interfaces using opaque roles and two families of translucent veils.

## Overview

The Surface system consists of three types:

- **Surface Roles** - Semantic, opaque surface tokens for specific UI contexts (app, canvas, card, table, modal, input)
- **Surface Overlay** (subtle, soft, mild, firm, strong) - Translucent layers that push an element _into_ its background
- **Surface Lift** (subtle, soft, mild, firm, strong) - Translucent layers that pull an element _up off_ its background

## Surface Roles

Surface roles provide semantic meaning to your surfaces based on their context in the UI hierarchy. Instead of choosing arbitrary scale values, use these semantic tokens that automatically adapt to the active theme.

<SurfaceShowcase @type="roles" />

### Available Roles

#### App (`bg-surface-app`)

Root application background layer (hierarchy level 0).

**When to use:**

- App shell root
- Full-viewport base layer
- Root layout behind navigation

```gts preview
<template>
  <div class='bg-surface-app p-4'>
    <nav class='p-4 border-b border-neutral-subtle'>
      <h1 class='text-neutral-strong text-xl'>App Navigation</h1>
    </nav>
    <main class='bg-surface-canvas p-6'>
      <p class='text-neutral-strong'>Content area with canvas background</p>
    </main>
  </div>
</template>
```

#### Canvas (`bg-surface-canvas`)

Component contrast baseline (hierarchy level 1).

**When to use:**

- Main content areas
- Page containers that need contrast from app background
- Component baseline surfaces

```gts preview
<template>
  <div class='bg-surface-app p-4'>
    <div class='bg-surface-canvas p-6'>
      <h1 class='text-neutral-strong text-2xl'>Content Area</h1>
      <p class='text-neutral-strong'>Canvas provides contrast against the app
        background</p>
    </div>
  </div>
</template>
```

#### Card (`bg-surface-card`)

Elevated card container surface (hierarchy level 1). Opaque white in light mode;
in dark mode it is a translucent veil (white @ 7%, the same value as
`overlay-subtle`), so whatever sits behind it shows through faintly. Where a
surface has to stay opaque, use `surface-table` — the same colour without the
transparency.

**When to use:**

- Product cards
- Article previews
- Content blocks

```gts preview
<template>
  <div class='bg-surface-canvas p-6'>
    <article
      class='bg-surface-card rounded-lg border border-neutral-subtle p-6'
    >
      <h2 class='text-neutral-strong text-xl mb-2'>Product Title</h2>
      <p class='text-neutral-strong'>This card is elevated off the canvas
        background</p>
    </article>
  </div>
</template>
```

#### Table (`bg-surface-table`)

Data table surface (hierarchy level 1). Usually the same color as a card, but must be opaque.

Tables need that guarantee. A sticky header, a frozen row, or a pinned column
paints over the rows and columns scrolling beneath it, and anything translucent
lets them show through.

**When to use:**

- Data table containers, and the sticky parts inside them

```gts preview
<template>
  <div class='bg-surface-canvas p-6'>
    <div class='bg-surface-table rounded-lg h-32 overflow-auto'>
      <div class='bg-surface-table sticky top-0 px-4 py-2'>
        <p class='text-neutral-bolder'>Sticky header — rows pass under it</p>
      </div>
      <div class='px-4 py-2 text-neutral-strong'>Row one</div>
      <div class='px-4 py-2 text-neutral-strong'>Row two</div>
      <div class='px-4 py-2 text-neutral-strong'>Row three</div>
      <div class='px-4 py-2 text-neutral-strong'>Row four</div>
      <div class='px-4 py-2 text-neutral-strong'>Row five</div>
    </div>
  </div>
</template>
```

#### Modal (`bg-surface-modal`)

Modal, drawer, and popover container surface, highest elevation (hierarchy level 3).

**When to use:**

- Modal dialogs
- Drawers
- Popovers and dropdown menus
- Confirmation prompts

Pair it with `bg-surface-overlay-strong dark:bg-surface-lift-strong` for the backdrop behind modals and drawers.

```gts preview
<template>
  <div class='bg-surface-canvas p-6'>
    <div class='bg-surface-modal rounded-lg shadow-2xl p-6 max-w-md'>
      <h2 class='text-on-surface-modal text-xl mb-2'>Confirm Action</h2>
      <p class='text-on-surface-modal mb-4'>Are you sure you want to continue?</p>
      <div class='flex gap-2'>
        <button
          class='bg-primary text-on-primary px-4 py-2 rounded'
        >Confirm</button>
        <button
          class='bg-neutral-subtle text-neutral-strong px-4 py-2 rounded'
        >Cancel</button>
      </div>
    </div>
  </div>
</template>
```

#### Input (`bg-surface-input`)

Form control surface for inputs, checkboxes, radios, and similar controls (hierarchy level -1).

**When to use:**

- Text inputs
- Checkboxes and radios
- Any native form control background

```gts preview
<template>
  <div class='bg-surface-canvas p-6'>
    <div>
      <label class='block text-neutral-strong text-sm mb-1'>Email</label>
      <input
        class='bg-surface-input border border-neutral rounded px-3 py-2 w-full text-neutral-strong'
        placeholder='Enter your email'
      />
    </div>
  </div>
</template>
```

### Hierarchy Levels

Surface roles are designed to create visual depth through a hierarchy system:

| Level | Role                | Purpose                                                  |
| ----- | ------------------- | -------------------------------------------------------- |
| -1    | Input               | Recessed below canvas                                    |
| 0     | App                 | Root application background                              |
| 1     | Canvas, Card, Table | Component contrast baseline and first level of elevation |
| 3     | Modal               | Highest elevation (modals, drawers, popovers, dropdowns) |

In **light mode**, elevated surfaces appear brighter (white) against gray backgrounds following the elevation-luminance principle.
In **dark mode**, elevated surfaces appear progressively lighter against near-black backgrounds.

## Surface Overlay (subtle, soft, mild, firm, strong)

Translucent overlays with alpha channel that stack on top of solid surfaces. These add depth through transparency rather than changing the base color.

### When to Use

- **Sections within components**: Modal footers, card headers, dropdown sections
- **Cards/panels on pages**: Elevated surfaces that float on top of the page background
- **Hover states**: Subtle translucent effect on hover
- **Progress bars, selection highlights**: Semi-transparent UI elements
- **`strong`**: The heaviest step (75% in light, 95% in dark), far beyond a hover or elevation hint. In light mode this is the backdrop behind modals and drawers; in dark mode the black scrim is `lift-strong` instead, since the families mirror each other — see [Surface Lift](#surface-lift-subtle-soft-mild-firm-strong)

### Example: Modal with Overlay Footer

```hbs
{{! Modal base uses the modal surface role }}
<Modal
  @classes={{hash
    base='bg-surface-modal text-on-surface-modal'
    footer='bg-surface-overlay-subtle'
  }}
>
  <:default>
    Modal content on opaque base
  </:default>

  <:footer>
    Footer with subtle overlay effect
  </:footer>
</Modal>
```

### Example: Card on Page

```hbs
{{! Page has a solid app background }}
<div class='bg-surface-app'>
  {{! Card floats on top with translucent overlay }}
  <div class='bg-surface-overlay-soft rounded-lg p-6'>
    <h3>Card Title</h3>
    <p>Card content with depth</p>
  </div>
</div>
```

### Stacking Overlays

Overlays can stack on top of each other to create progressive depth:

<SurfaceShowcase @type="overlay" />

```hbs
<div class='bg-surface-app p-6'>
  <div class='bg-surface-overlay-subtle p-4 rounded'>
    Layer 1 (subtle)
    <div class='bg-surface-overlay-soft p-4 rounded'>
      Layer 2 (soft)
      <div class='bg-surface-overlay-mild p-4 rounded'>
        Layer 3 (mild)
        <div class='bg-surface-overlay-firm p-4 rounded'>
          Layer 4 (firm)
        </div>
      </div>
    </div>
  </div>
</div>
```

### Example: Modal/Drawer Backdrop

```hbs
<Overlay
  @backdrop={{hash
    class='bg-surface-overlay-strong dark:bg-surface-lift-strong backdrop-blur-sm'
  }}
>
  Modal content
</Overlay>
```

## Surface Lift (subtle, soft, mild, firm, strong)

Lift is the mirror of overlay. Overlay darkens in light mode and lightens in dark mode, pressing an element _into_ the page. Lift does the opposite — a white veil on a light page, a black veil on a dark one — so the element reads as floating _above_ whatever it covers.

<SurfaceShowcase @type="lift" />

Both families share the same level names, and both adapt to the active theme automatically:

| Level    | Light mode  | Dark mode   |
| -------- | ----------- | ----------- |
| `subtle` | white @ 30% | black @ 10% |
| `soft`   | white @ 50% | black @ 20% |
| `mild`   | white @ 70% | black @ 30% |
| `firm`   | white @ 90% | black @ 40% |
| `strong` | white @ 95% | black @ 75% |

Every lift level flips with the scheme, `strong` included.

The two families are exact mirrors, which has one consequence worth knowing: the
heavy black veil used as a modal backdrop is `overlay-strong` in light mode but
`lift-strong` in dark mode. A component that wants a dark scrim in both schemes
pairs them — `bg-surface-overlay-strong dark:bg-surface-lift-strong` — which is
what Overlay's backdrop does.

### When to Use

- **Frosted/glass panels**: Pair with `backdrop-blur-*` for a translucent panel that stays legible over busy content
- **Sticky headers and toolbars**: Content scrolls under them without washing them out
- **Floating controls over imagery**: Media captions, hero overlays, map controls
- **Anything that must read as _above_ the page** rather than recessed into it

Reach for `surface-overlay-*` instead when the element belongs to the surface it sits on — hover states, table stripes, section fills.

### Example: Frosted Sticky Header

```hbs
<header
  class='sticky top-0 bg-surface-lift-firm backdrop-blur-md border-b border-surface-overlay-subtle'
>
  <nav>Content scrolls underneath, header stays legible</nav>
</header>
```

### Example: Caption Over an Image

```hbs
<figure class='relative'>
  <img src='/hero.jpg' alt='' />
  <figcaption
    class='absolute inset-x-0 bottom-0 bg-surface-lift-soft backdrop-blur-sm p-4'
  >
    Floats above the image in either theme
  </figcaption>
</figure>
```

### Example: Overlay vs Lift

The same nesting, one family each — overlay recedes, lift advances:

```hbs
<div class='bg-surface-canvas p-6'>
  {{! Recedes into the page }}
  <div class='bg-surface-overlay-soft p-4 rounded'>Overlay</div>

  {{! Floats above the page }}
  <div class='bg-surface-lift-soft p-4 rounded'>Lift</div>
</div>
```

## Choosing the Right Surface

Follow this decision flow:

1. **Does this match a specific UI context?**
   - If yes → Use `surface-{role}` (app, canvas, card, table, modal, input)
   - Surface roles provide semantic meaning and automatically adapt to themes.

2. **Is this the base container and no role matches?**
   - Use `surface-app` for most cases.

3. **Does it need to be translucent?**
   - If yes → Continue to next step
   - If no → Use a surface role

4. **Should it read as recessed into the surface, or floating above it?**
   - Recessed (hover states, section fills, table stripes) → Use `surface-overlay-*`
   - Floating (frosted panels, sticky headers, captions over media) → Use `surface-lift-*`
   - If it's a modal/drawer backdrop → Use `surface-overlay-strong dark:surface-lift-strong`

## Common Patterns

### Pattern 1: Page Layout with Cards

```gts preview
<template>
  <div class='bg-surface-canvas p-6'>
    <div class='max-w-4xl mx-auto space-y-4'>
      <div class='bg-surface-card rounded-lg border border-neutral-subtle p-6'>
        <h2 class='text-neutral-bolder text-lg font-semibold mb-2'>Card 1</h2>
        <p class='text-neutral-strong'>Content on elevated card surface</p>
      </div>
      <div class='bg-surface-card rounded-lg border border-neutral-subtle p-6'>
        <h2 class='text-neutral-bolder text-lg font-semibold mb-2'>Card 2</h2>
        <p class='text-neutral-strong'>Another elevated card</p>
      </div>
    </div>
  </div>
</template>
```

### Pattern 2: Sidebar Layout

```gts preview
<template>
  <div class='flex h-64'>
    <aside class='bg-surface-card w-48 border-r border-neutral-subtle p-4'>
      <h3 class='text-neutral-strong font-semibold mb-4'>Sidebar</h3>
      <nav class='space-y-2'>
        <a
          href='#'
          class='block text-neutral-strong hover:text-neutral-bolder text-sm'
        >Link 1</a>
        <a
          href='#'
          class='block text-neutral-strong hover:text-neutral-bolder text-sm'
        >Link 2</a>
      </nav>
    </aside>
    <main class='bg-surface-canvas flex-1 p-6'>
      <h1 class='text-neutral-bolder text-xl mb-2'>Main Content</h1>
      <p class='text-neutral-strong'>Content area on canvas</p>
    </main>
  </div>
</template>
```

### Pattern 3: Form with Inputs

```gts preview
<template>
  <div class='bg-surface-canvas p-6'>
    <form
      class='bg-surface-card rounded-lg border border-neutral-subtle p-6 max-w-md'
    >
      <h2 class='text-neutral-strong text-lg font-semibold mb-4'>Sign Up</h2>
      <div class='space-y-4'>
        <div>
          <label class='block text-neutral-strong text-sm mb-1'>Username</label>
          <input
            class='bg-surface-input border border-neutral rounded px-3 py-2 w-full text-neutral-strong'
            placeholder='Enter username'
          />
        </div>
        <div>
          <label class='block text-neutral-strong text-sm mb-1'>Email</label>
          <input
            class='bg-surface-input border border-neutral rounded px-3 py-2 w-full text-neutral-strong'
            placeholder='Enter email'
          />
        </div>
        <button class='bg-primary text-on-primary w-full py-2 rounded'>
          Submit
        </button>
      </div>
    </form>
  </div>
</template>
```

## Migrating from content1-4

If you're upgrading from an older version that used `content1-4`, here's the migration mapping:

| Old                            | New                                 | Reason                            |
| ------------------------------ | ----------------------------------- | --------------------------------- |
| `bg-content1`                  | `bg-surface-app`                    | Base opaque surface               |
| `bg-content3 dark:bg-content2` | `bg-surface-overlay-soft`           | Single value works in both themes |
| `selection:bg-content3`        | `selection:bg-surface-overlay-soft` | Translucent selection highlight   |

## Best Practices

### Do

- **Prefer surface roles** (`surface-canvas`, `surface-card`, etc.) over ad hoc colors when they match your UI context
- Stack overlays on a surface role for depth
- Use `overlay-strong` with `dark:lift-strong` for modal/drawer backdrops
- Test in both light and dark modes
- Follow the hierarchy levels for visual consistency

### Don't

- Don't use overlay without a solid role beneath it
- Don't mix surface system with old content1-4
- Don't use too many overlay layers (max 3-4)
- Don't forget to check contrast ratios

---

# Elevation

Source: /docs/theming/design-tokens/elevation.md

# Elevation

Frontile provides an elevation system using shadows to create visual depth and hierarchy in your interface.

## Overview

Elevation helps establish spatial relationships and visual hierarchy by making elements appear "closer" or "further" from the user. Frontile provides six elevation levels (0-5), each designed for specific UI contexts.

Higher elevations indicate elements that are more prominent or interactive, such as floating menus, modals, and tooltips.

## Elevation Levels

```gts preview collapsible
<template>
  <div class='grid grid-cols-2 md:grid-cols-3 gap-8 p-8'>
    <div class='shadow-elevation-0 bg-surface-canvas p-6 rounded'>
      <h3 class='mb-2'>Level 0</h3>
      <p class='text-neutral-strong'>No shadow</p>
      <p class='text-neutral-strong text-sm mt-2'>Flat surface</p>
    </div>
    <div class='shadow-elevation-1 bg-surface-canvas p-6 rounded'>
      <h3 class='mb-2'>Level 1</h3>
      <p class='text-neutral-strong'>Subtle lift</p>
      <p class='text-neutral-strong text-sm mt-2'>Hover states</p>
    </div>
    <div class='shadow-elevation-2 bg-surface-canvas p-6 rounded'>
      <h3 class='mb-2'>Level 2</h3>
      <p class='text-neutral-strong'>Raised surface</p>
      <p class='text-neutral-strong text-sm mt-2'>Cards, panels</p>
    </div>
    <div class='shadow-elevation-3 bg-surface-canvas p-6 rounded'>
      <h3 class='mb-2'>Level 3</h3>
      <p class='text-neutral-strong'>Floating element</p>
      <p class='text-neutral-strong text-sm mt-2'>Dropdowns</p>
    </div>
    <div class='shadow-elevation-4 bg-surface-canvas p-6 rounded'>
      <h3 class='mb-2'>Level 4</h3>
      <p class='text-neutral-strong'>Elevated overlay</p>
      <p class='text-neutral-strong text-sm mt-2'>Modals, dialogs</p>
    </div>
    <div class='shadow-elevation-5 bg-surface-canvas p-6 rounded'>
      <h3 class='mb-2'>Level 5</h3>
      <p class='text-neutral-strong'>Maximum depth</p>
      <p class='text-neutral-strong text-sm mt-2'>Top layer</p>
    </div>
  </div>
</template>
```

## When to Use Each Level

| Level | Utility              | Use Cases                         | Examples                                                  |
| ----- | -------------------- | --------------------------------- | --------------------------------------------------------- |
| 0     | `shadow-elevation-0` | Flat elements, no depth needed    | Inline content, flat buttons, embedded content            |
| 1     | `shadow-elevation-1` | Subtle separation from background | Hover states, subtle cards, list items                    |
| 2     | `shadow-elevation-2` | Standard raised surfaces          | Cards, panels, tiles, navigation bars                     |
| 3     | `shadow-elevation-3` | Floating elements above content   | Dropdowns, tooltips, popovers, date pickers               |
| 4     | `shadow-elevation-4` | Modal overlays                    | Modals, dialogs, drawers, sheets                          |
| 5     | `shadow-elevation-5` | Maximum emphasis                  | Critical alerts, system notifications, top-layer elements |

## Common Use Cases

### Cards and Panels

```gts preview collapsible
<template>
  <div class='grid md:grid-cols-2 gap-6'>
    {{! Basic card with level 2 elevation }}
    <div class='shadow-elevation-2 bg-surface-canvas rounded-xl p-6'>
      <h3 class='mb-3'>Product Card</h3>
      <p class='text-neutral-strong mb-4'>
        Standard card with level 2 elevation provides subtle depth.
      </p>
      <button
        class='bg-primary text-on-primary px-4 py-2 rounded hover:bg-primary-soft'
      >
        View Details
      </button>
    </div>

    {{! Feature card with no shadow }}
    <div
      class='shadow-elevation-0 border border-neutral bg-surface-canvas rounded-xl p-6'
    >
      <h3 class='mb-3'>Flat Card</h3>
      <p class='text-neutral-strong mb-4'>
        Uses border instead of shadow for a flatter appearance.
      </p>
      <button
        class='border border-primary text-primary px-4 py-2 rounded hover:bg-primary-subtle'
      >
        Learn More
      </button>
    </div>
  </div>
</template>
```

### Interactive States

```gts preview
<template>
  <div class='flex gap-4 flex-wrap'>
    {{! Button that lifts on hover }}
    <button
      class='bg-primary text-on-primary px-6 py-3 rounded shadow-elevation-1 hover:shadow-elevation-3 transition-shadow'
    >
      Hover to Lift
    </button>

    {{! Card that lifts on hover }}
    <div
      class='bg-surface-canvas rounded-xl p-6 shadow-elevation-1 hover:shadow-elevation-2 transition-shadow cursor-pointer'
    >
      <h4 class='mb-2'>Interactive Card</h4>
      <p class='text-neutral-strong'>Elevation increases on hover</p>
    </div>
  </div>
</template>
```

## Best Practices

### Establish Clear Hierarchy

Use elevation consistently to indicate the z-axis position of elements:

- **Base layer** (level 0-1): Page content, static elements
- **Raised layer** (level 2): Cards, panels, navigation
- **Floating layer** (level 3): Dropdowns, popovers, tooltips
- **Overlay layer** (level 4-5): Modals, critical alerts

### Avoid Elevation Confusion

Don't use high elevation for non-interactive or less important elements. Reserve levels 4-5 for elements that need to command attention.

### Transition Elevations

Animate elevation changes for smooth interactions:

```html
<div class="shadow-elevation-1 hover:shadow-elevation-3 transition-shadow">
  Smooth elevation transition
</div>
```

### Consider Dark Mode

Shadows may be less visible in dark mode. Consider combining elevation with subtle borders:

```html
<div class="shadow-elevation-2 border border-neutral/20">
  Enhanced depth with border
</div>
```

## Accessibility

### Don't Rely on Shadows Alone

Never use shadows as the only indicator of important information. Always provide additional visual cues:

- Use borders for critical boundaries
- Use semantic colors for status
- Provide clear text labels
- Ensure proper focus indicators

### Test in Different Lighting

Shadows may be difficult to perceive:

- On certain displays (high brightness, poor contrast)
- For users with visual impairments
- In different lighting conditions

Always provide alternative visual cues beyond elevation.

## Customization

Override elevation shadows using CSS variables:

```css
@import '@frontile/theme';

@theme {
  /* Customize specific elevation levels */
  --shadow-elevation-1: 0px 2px 4px rgba(0, 0, 0, 0.05);
  --shadow-elevation-2: 0px 4px 12px rgba(0, 0, 0, 0.1);
  --shadow-elevation-3: 0px 8px 24px rgba(0, 0, 0, 0.15);
  --shadow-elevation-4: 0px 16px 48px rgba(0, 0, 0, 0.2);
}
```

### Theme-Specific Shadows

Adjust shadows for light and dark themes:

```css
/* Light theme */
.light,
.dark .theme-inverse {
  --shadow-elevation-2: 0px 4px 12px rgba(0, 0, 0, 0.1);
}

/* Dark theme */
.dark,
.light .theme-inverse {
  --shadow-elevation-2: 0px 4px 12px rgba(0, 0, 0, 0.4);
}
```

For more customization options, see the [Configuration Guide](../configuration/customization.md).

---

# Configuration Overview

Source: /docs/theming/configuration/overview.md

# Configuration

Learn how to configure and customize Frontile's theme system to match your application's design requirements.

## Overview

Frontile provides two primary methods for configuring your theme:

1. **CSS Variables** - Recommended for most customizations
2. **JavaScript Configuration** - For complex theme setups and color customization

## CSS Variables (Recommended)

The most straightforward way to customize Frontile is using CSS variables in your stylesheet. This approach uses Tailwind v4's `@theme` directive for simple, performant customization.

### Quick Start

Add customizations after importing the theme in your `app/styles/app.css`:

```css title="app/styles/app.css"
@import 'tailwindcss' source('../../');
@plugin "@frontile/theme/plugin/default";
@import "@frontile/theme";

@theme {
  /* Customize design tokens */
  --radius: 12px;
  --border-width-default: 2px;
  --size-icon-md: 20px;
  --opacity-hover: .85;
}
```

### What You Can Customize

Use CSS variables to customize:

- **Border radius** - `--radius` (one knob; the whole `rounded-*` scale is derived from it), plus `--radius-pill` and individual steps as escape hatches
- **Border widths** - `--border-width-thin`, `--border-width-heavy`
- **Icon sizes** - `--size-icon-sm`, `--size-icon-md`, `--size-icon-lg`
- **Shadows** - `--shadow-elevation-1`, `--shadow-elevation-2`
- **Opacity** - `--opacity-hover`, `--opacity-disabled`
- **Typography** - Font families, sizes, and text styles
- **Component sizes** - Modal and drawer sizes

### Benefits of CSS Variables

- **Simple** - No JavaScript configuration needed
- **Fast** - Changes are applied at CSS level
- **Flexible** - Can be changed at runtime
- **Theme-specific** - Easy to customize per theme (light/dark)

### When to Use CSS Variables

Choose CSS variables when you need to:

- Override specific design token values
- Adjust border radius, spacing, or sizing
- Customize per-theme values (different in light vs dark)
- Make runtime changes via JavaScript

## JavaScript Configuration

For more complex customization, especially colors, use JavaScript configuration. This method provides programmatic control and type safety.

### Quick Start

Create `frontile.js` in your project root:

```js title="frontile.js"
const { frontile } = require('@frontile/theme/plugin');

module.exports = frontile({
  defaultTheme: 'light',
  themes: {
    light: {
      colors: {
        primary: {
          subtle: '#eff6ff',
          soft: '#93c5fd',
          DEFAULT: '#3b82f6',
          strong: '#1e40af'
        }
      }
    },
    dark: {
      colors: {
        primary: {
          subtle: '#1e3a8a',
          soft: '#3b82f6',
          DEFAULT: '#60a5fa',
          strong: '#dbeafe'
        }
      }
    }
  }
});
```

Then reference it in your CSS:

```css
@import 'tailwindcss' source('../../');
@plugin "./../../frontile.js";
@import "@frontile/theme";
```

### What You Can Customize

Use JavaScript configuration for:

- **Semantic colors** - Primary, success, danger, warning, neutral
- **Default theme** - Which theme loads by default
- **Theme variants** - Create multiple theme variations
- **Complex configurations** - Programmatic theme generation

### When to Use JavaScript Configuration

Choose JavaScript configuration when you need to:

- Customize semantic colors (primary, success, danger, etc.)
- Set the default theme (light or dark)
- Create multiple theme variants
- Generate themes programmatically
- Share configuration across projects

## Comparison

| Feature | CSS Variables | JavaScript Config |
|---------|---------------|-------------------|
| **Border radius** | ✅ Recommended | ❌ Not needed |
| **Semantic colors** | ❌ Use JS instead | ✅ Recommended |
| **Icon sizes** | ✅ Recommended | ❌ Not needed |
| **Elevation shadows** | ✅ Recommended | ❌ Not needed |
| **Typography** | ✅ Recommended | ❌ Not needed |
| **Default theme** | ❌ Not possible | ✅ Use JS |
| **Runtime changes** | ✅ Easy | ❌ Requires rebuild |
| **Per-theme values** | ✅ Simple | ⚠️ More complex |

## Common Patterns

### Pattern 1: Simple Adjustments

For minor adjustments to existing tokens, use CSS variables:

```css
@theme {
  --radius: 6px; /* scales every rounded-* step down proportionally */
  --opacity-hover: .9;
}
```

### Pattern 2: Custom Primary Colors

For primary color customization, use JavaScript:

```js
module.exports = frontile({
  themes: {
    light: {
      colors: {
        primary: {
          subtle: '#f0f9ff',
          soft: '#7dd3fc',
          DEFAULT: '#0ea5e9',
          strong: '#0c4a6e'
        }
      }
    }
  }
});
```

### Pattern 3: Mixed Approach

Combine both methods for comprehensive customization:

```js
// frontile.js - Customize colors
module.exports = frontile({
  themes: {
    light: {
      colors: { /* custom colors */ }
    }
  }
});
```

```css
/* app.css - Customize design tokens */
@theme {
  --radius: 8px;
  --size-icon-md: 18px;
}
```

### Pattern 4: Theme-Specific Overrides

Use CSS for theme-specific token values:

```css
/* Light theme */
.light,
.dark .theme-inverse {
  --opacity-hover: .85;
  --shadow-elevation-2: 0px 4px 12px rgba(0, 0, 0, 0.1);
}

/* Dark theme */
.dark,
.light .theme-inverse {
  --opacity-hover: .75;
  --shadow-elevation-2: 0px 4px 12px rgba(0, 0, 0, 0.3);
}
```

## Next Steps

- [CSS Variables Reference](css-variables.md) - Complete list of available variables
- [Theme Switching](theme-switching.md) - Implement light/dark mode
- [Customization Guide](customization.md) - Detailed customization examples

---

# CSS Variables

Source: /docs/theming/configuration/css-variables.md

# CSS Variables Reference

Complete reference of CSS variables available in Frontile's theme system for customization.

## How CSS Variables Work

Frontile uses CSS variables in two ways:

### 1. Theme Variables (`@theme` block)

Variables defined in the `@theme` block automatically generate Tailwind utility classes:

```css
@theme {
  --radius: 8px;        /* Generates: rounded utility */
  --radius-xl: 12px;    /* Generates: rounded-xl utility */
}
```

These are the primary customization points for design tokens.

### 2. Component Variables (`:root` or theme selectors)

Variables defined in `:root` or theme-specific selectors are for component-specific values:

```css
:root {
  --modal-lg: 32rem;    /* Used by Modal component */
  --drawer-md: 28rem;   /* Used by Drawer component */
}
```

## Typography Variables

### Font Families

```css
@theme {
  --font-header: system-ui, sans-serif;
  --font-body: system-ui, sans-serif;
  --font-code: 'Courier New', monospace;
  --font-label: system-ui, sans-serif;
  --font-caption: system-ui, sans-serif;
  --font-marquee: system-ui, sans-serif;
}
```

### Text Styles

Frontile provides text style variables. Each text style category has multiple size variants:

- **Marquee**: `--text-marquee-5xs` through `--text-marquee-3xl`
- **Header**: `--text-header-4xs` through `--text-header-3xl`
- **Strong**: `--text-strong-4xs` through `--text-strong-3xl`
- **Body**: `--text-body-5xs` through `--text-body-3xl`
- **Code**: `--text-code-sm`, `--text-code-md`
- **Caption**: `--text-caption-sm`, `--text-caption-md`
- **Label**: `--text-label-nano` through `--text-label-3xl`

Each text style includes font-size, font-family, font-weight, letter-spacing, and line-height properties.

See [Typography documentation](../design-tokens/typography.md) for detailed information.

## Layout Variables

### Border Width

```css
@theme {
  --border-width-thin: 0.5px;
  --border-width-default: 1px;
  --border-width-heavy: 2px;
  --border-width-aggressive: 4px;
}
```

**Generated utilities:** `border-thin`, `border`, `border-heavy`, `border-aggressive`

### Border Radius

Every step is derived from a single `--radius` base, so you can dial the
roundness of the whole library with one value:

```css
@theme {
  --radius: 0.5rem;                          /* 8px — the one knob */
  --radius-none: 0px;
  --radius-xs: calc(var(--radius) * 0.25);   /* 2px */
  --radius-sm: calc(var(--radius) * 0.5);    /* 4px */
  --radius-md: calc(var(--radius) * 0.75);   /* 6px */
  --radius-lg: calc(var(--radius) * 1);      /* 8px */
  --radius-xl: calc(var(--radius) * 1.5);    /* 12px */
  --radius-2xl: calc(var(--radius) * 2);     /* 16px */
  --radius-3xl: calc(var(--radius) * 3);     /* 24px */
  --radius-4xl: calc(var(--radius) * 4);     /* 32px */
  --radius-default: calc(var(--radius) * 2.5); /* 20px */
  --radius-pill: 9999px;
}
```

**Generated utilities:** `rounded-none`, `rounded-xs`, `rounded-sm`, `rounded-md`, `rounded`, `rounded-lg`, `rounded-xl`, `rounded-2xl`, `rounded-3xl`, `rounded-4xl`, `rounded-default`, `rounded-pill`

To make every component softer or sharper, override `--radius` alone — the rest
of the scale follows:

```css
@theme {
  --radius: 0.75rem; /* menus 18px, list items 12px, modals 24px */
}
```

```css
@theme {
  --radius: 0; /* square everything off */
}
```

`--radius-none` and `--radius-pill` are absolutes and deliberately do not scale,
so `rounded-full` buttons stay pills at any base value.

### Icon Sizes

```css
@theme {
  --size-icon-pico: /* ... */;
  --size-icon-nano: /* ... */;
  --size-icon-micro: /* ... */;
  --size-icon-3xs: /* ... */;
  --size-icon-2xs: /* ... */;
  --size-icon-xs: /* ... */;
  --size-icon-sm: /* ... */;
  --size-icon-md: /* ... */;
  --size-icon-lg: /* ... */;
  --size-icon-xl: /* ... */;
  --size-icon-2xl: /* ... */;
  --size-icon-3xl: /* ... */;
  --size-icon-kilo: /* ... */;
  --size-icon-mega: /* ... */;
}
```

**Generated utilities:** `size-icon-pico` through `size-icon-mega`

See [Icon Sizes documentation](../design-tokens/icons.md) for usage guidelines.

### Elevation Shadows

```css
@theme {
  --shadow-elevation-0: /* ... */;
  --shadow-elevation-1: /* ... */;
  --shadow-elevation-2: /* ... */;
  --shadow-elevation-3: /* ... */;
  --shadow-elevation-4: /* ... */;
  --shadow-elevation-5: /* ... */;
}
```

**Generated utilities:** `shadow-elevation-0` through `shadow-elevation-5`

See [Elevation documentation](../design-tokens/elevation.md) for usage guidelines.

### Opacity

```css
@theme {
  --opacity-hover: .8;
  --opacity-disabled: .5;
}
```

**Generated utilities:** `opacity-hover`, `opacity-disabled`

## Component Variables

These variables are used by specific Frontile components and should be defined in `:root` or theme-specific selectors (not in `@theme` block):

### Modal Sizes

```css
:root {
  --modal-xs: 22rem;
  --modal-sm: 30rem;
  --modal-md: 35rem;
  --modal-lg: 48rem;
  --modal-xl: 60rem;
  --modal-full: 100%;
}
```

### Drawer Sizes

```css
:root {
  --drawer-xs: 22rem;
  --drawer-sm: 30rem;
  --drawer-md: 48rem;
  --drawer-lg: 64rem;
  --drawer-xl: 80rem;
  --drawer-full: 100%;
}
```

## Color Variables

**Important:** Color variables should be customized using JavaScript configuration, not CSS variables directly. See [Color Customization](customization.md#colors) for details.

Frontile's semantic colors use a system that automatically calculates:
- Light and dark theme variations
- Contrasting text colors (`on-{color}` classes)
- Colors in OKLCH format for perceptual uniformity

## Overriding Variables

### Global Overrides

Override in the `@theme` block for design tokens:

```css
@import "@frontile/theme";

@theme {
  --radius: 12px;
  --border-width-default: 2px;
  --opacity-hover: .9;
  --size-icon-md: 20px;
}
```

### Theme-Specific Overrides

Use theme selectors for per-theme customization:

```css
/* Light theme - targets .light AND .theme-inverse within .dark */
.light,
.dark .theme-inverse {
  --opacity-hover: .85;
  --shadow-elevation-2: 0px 4px 12px rgba(0, 0, 0, 0.1);
}

/* Dark theme - targets .dark AND .theme-inverse within .light */
.dark,
.light .theme-inverse {
  --opacity-hover: .75;
  --shadow-elevation-2: 0px 4px 12px rgba(0, 0, 0, 0.3);
}
```

**Why both selectors?** This ensures customizations apply to:
- Regular theme usage (`.light` or `.dark`)
- Theme-inverse sections (`.theme-inverse` within opposite theme)

### Component-Specific Overrides

Override component variables in `:root`:

```css
:root {
  --modal-lg: 48rem;
  --drawer-md: 32rem;
}
```

Or per-theme:

```css
.dark {
  --modal-lg: 56rem;
}
```

## Usage Examples

### Example 1: Customize Border Radius

```css
@theme {
  /* Softer corners throughout the app */
  --radius: 12px;
  --radius-xl: 20px;
  --radius-pill: 9999px;
}
```

### Example 2: Adjust Icon Sizes

```css
@theme {
  /* Slightly larger icons */
  --size-icon-sm: 15px;
  --size-icon-md: 19px;
  --size-icon-lg: 23px;
}
```

### Example 3: Theme-Specific Shadows

```css
/* Subtler shadows in light mode */
.light,
.dark .theme-inverse {
  --shadow-elevation-1: 0px 1px 3px rgba(0, 0, 0, 0.05);
  --shadow-elevation-2: 0px 2px 8px rgba(0, 0, 0, 0.08);
}

/* Stronger shadows in dark mode */
.dark,
.light .theme-inverse {
  --shadow-elevation-1: 0px 2px 4px rgba(0, 0, 0, 0.3);
  --shadow-elevation-2: 0px 4px 12px rgba(0, 0, 0, 0.4);
}
```

### Example 4: Custom Font Families

```css
@font-face {
  font-family: 'Inter';
  src: url('/fonts/inter-var.woff2') format('woff2');
  font-weight: 100 900;
}

@theme {
  --font-header: 'Inter', system-ui, sans-serif;
  --font-body: 'Inter', system-ui, sans-serif;
  --font-label: 'Inter', system-ui, sans-serif;
}
```

### Example 5: Adjust Component Sizes

```css
:root {
  /* Larger modals for desktop */
  --modal-md: 36rem;
  --modal-lg: 48rem;
  --modal-xl: 64rem;
}

/* Smaller on mobile */
@media (max-width: 768px) {
  :root {
    --modal-md: 90vw;
    --modal-lg: 90vw;
  }
}
```

## Best Practices

### Use @theme for Design Tokens

Always use `@theme` block for variables that should generate utility classes:

```css
/* ✓ Good */
@theme {
  --radius: 10px;
}

/* ✗ Avoid */
:root {
  --radius: 10px;  /* Won't generate rounded utility */
}
```

### Use :root for Component Values

Use `:root` for component-specific values that don't need utilities:

```css
/* ✓ Good */
:root {
  --modal-lg: 48rem;
  --drawer-md: 32rem;
}
```

### Keep Theme Selectors Consistent

Always use both selectors for theme-specific overrides:

```css
/* ✓ Good - covers all cases */
.light,
.dark .theme-inverse {
  --opacity-hover: .85;
}

/* ✗ Incomplete - misses .theme-inverse */
.light {
  --opacity-hover: .85;
}
```

### Document Your Customizations

Add comments to explain custom values:

```css
@theme {
  /* Brand requires 16px minimum for icon clarity */
  --size-icon-md: 20px;

  /* Softer corners match brand guidelines */
  --radius: 12px;
}
```

## Runtime Customization

CSS variables can be changed at runtime using JavaScript:

```js
// Change globally
document.documentElement.style.setProperty('--radius', '16px');

// Change for specific element
element.style.setProperty('--opacity-hover', '0.9');

// Read current value
const radius = getComputedStyle(document.documentElement)
  .getPropertyValue('--radius');
```

This is useful for user preferences, theme builders, or dynamic customization features.

## Next Steps

- [Customization Guide](customization.md) - Detailed customization examples
- [Theme Switching](theme-switching.md) - Light/dark mode implementation
- [Design Tokens](../design-tokens/overview.md) - Understanding design tokens

---

# Theme Switching

Source: /docs/theming/configuration/theme-switching.md

# Theme Switching

Frontile supports light and dark themes, and theme inversion for creating visual contrast within your application.

## Basic Light/Dark Mode

Toggle between light and dark themes by adding or removing the `dark` class on a parent element (typically `<html>` or `<body>`):

```html
<!-- Dark mode -->
<html class="dark">
  <!-- All content uses dark theme -->
</html>

<!-- Light mode -->
<html class="light">
  <!-- All content uses light theme -->
</html>
```

The `light` class is optional since light mode is the default. However, it's useful when you want to be explicit.

## Implementing Theme Switching

### Client-Side Toggle

Here's a basic implementation. It stays a static snippet rather than a live demo
because it writes to `localStorage` and swaps classes on `<html>`, which would
fight this site's own theme switcher.

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

export default class ThemeToggle extends Component {
  @tracked isDark = false;

  constructor(owner: unknown, args: Record<string, unknown>) {
    super(owner as never, args);
    // Saved choice wins; fall back to the system preference.
    const saved = localStorage.getItem('theme');
    this.isDark = saved
      ? saved === 'dark'
      : window.matchMedia('(prefers-color-scheme: dark)').matches;
    this.applyTheme();
  }

  @action
  toggleTheme(): void {
    this.isDark = !this.isDark;
    this.applyTheme();
    localStorage.setItem('theme', this.isDark ? 'dark' : 'light');
  }

  applyTheme(): void {
    const html = document.documentElement;
    // Both classes are meaningful — `light` is what makes `theme-inverse`
    // work inside a dark region — so set one and clear the other.
    html.classList.toggle('dark', this.isDark);
    html.classList.toggle('light', !this.isDark);
  }

  <template>
    <Button @variant='outline' @onPress={{this.toggleTheme}}>
      {{if this.isDark '☀️ Light Mode' '🌙 Dark Mode'}}
    </Button>
  </template>
}
```

Frontile's own documentation site does exactly this — see
[`docfy-theme-switcher.gts`](https://github.com/josemarluedke/frontile/blob/main/site/app/components/docfy/docfy-theme-switcher.gts)
for a version that also reacts to the system preference changing while the page
is open, and guards against running during server-side rendering.

### Respecting System Preference

Detect and respond to the user's system theme preference:

```js
// Check system preference on load
const prefersDark = window.matchMedia('(prefers-color-scheme: dark)').matches;

// Listen for system preference changes
window.matchMedia('(prefers-color-scheme: dark)').addEventListener('change', (e) => {
  const isDark = e.matches;
  // Update theme
  document.documentElement.classList.toggle('dark', isDark);
  document.documentElement.classList.toggle('light', !isDark);
});
```

### Persisting Theme Choice

Store the user's theme preference:

```js
// Save preference
localStorage.setItem('theme', 'dark');

// Load preference
const savedTheme = localStorage.getItem('theme');
if (savedTheme) {
  document.documentElement.classList.add(savedTheme);
}

// Or use system preference if no saved preference
if (!savedTheme) {
  const prefersDark = window.matchMedia('(prefers-color-scheme: dark)').matches;
  document.documentElement.classList.add(prefersDark ? 'dark' : 'light');
}
```

## How Theme Classes Work

Frontile uses CSS selectors that apply theme-specific styles:

```css
/* Light theme styles apply to: */
.light *,                    /* Elements in light mode */
.dark .theme-inverse *       /* Theme-inverse within dark mode */

/* Dark theme styles apply to: */
.dark *,                     /* Elements in dark mode */
.light .theme-inverse *      /* Theme-inverse within light mode */
```

This means themes properly cascade and can be nested anywhere in your application.

## Theme Inverse

Create sections with inverted theme colors using the `theme-inverse` utility. In light mode, these sections display dark theme colors, and vice versa.

### Basic Usage

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

<template>
  <div class='space-y-8 p-8'>
    {{! Regular theme section }}
    <div class='p-6 bg-surface-overlay-subtle rounded-lg'>
      <h3 class='text-header-md text-neutral-strong mb-4'>Regular Theme</h3>
      <p class='text-body-md text-neutral-firm mb-4'>
        This section uses the current theme colors.
      </p>
      <Button @color='primary'>Primary Button</Button>
    </div>

    {{! Inverted theme section }}
    <div class='theme-inverse p-6 bg-surface-canvas rounded-lg'>
      <div class='p-6 bg-surface-overlay-subtle rounded-lg'>
        <h3 class='text-header-md text-neutral-strong mb-4'>Inverted Theme</h3>
        <p class='text-body-md text-neutral-firm mb-4'>
          This section uses the opposite theme colors automatically.
        </p>
        <Button @color='primary'>Primary Button</Button>
      </div>
    </div>
  </div>
</template>
```

### Use Cases for Theme Inverse

Theme inverse is perfect for creating visual contrast and emphasis:

- **Hero sections** - Dark hero on light page, or vice versa
- **Feature highlights** - Draw attention to specific sections
- **Sidebars/panels** - Create visual separation
- **Marketing sections** - Alternate theme for variety

### Component Examples

All Frontile components work automatically with theme-inverse:

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

<template>
  <div class='space-y-6'>
    {{! Cards with status chips }}
    <div class='theme-inverse p-6 bg-surface-canvas rounded-lg'>
      <h4 class='text-header-sm text-neutral-strong mb-3'>Project Status</h4>
      <div class='flex flex-wrap gap-2 mb-4'>
        <Chip @color='success'>Active</Chip>
        <Chip @color='warning'>In Review</Chip>
        <Chip @color='neutral'>Draft</Chip>
      </div>
      <ProgressBar @progress={{65}} @color='primary' />
    </div>
  </div>
</template>
```

## Important: Modals and Overlays

### Default Behavior

By default, Modal and Drawer components render at the top level of the DOM using portals. This means they inherit the theme from `<html>` or `<body>`, **not** from `theme-inverse` sections:

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

const state = toggleState(false);

<template>
  <div class='theme-inverse p-6 bg-surface-canvas rounded-lg'>
    <p class='text-neutral-firm mb-4'>
      This section uses inverted theme, but the modal uses root theme.
    </p>
    <Button @onPress={{state.toggle}}>Open Modal</Button>

    {{! Modal renders at top level - uses root theme }}
    <Modal @isOpen={{state.current}} @onClose={{state.toggle}} as |modal|>
      <modal.Header>Modal Header</modal.Header>
      <modal.Body>
        This modal inherits from html/body, not the theme-inverse parent.
      </modal.Body>
    </Modal>
  </div>
</template>
```

### Rendering in Place

To make modals inherit `theme-inverse`, render them in place:

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

const state = toggleState(false);

<template>
  <div class='theme-inverse p-6 bg-surface-canvas rounded-lg'>
    <Button @onPress={{state.toggle}}>Open Modal</Button>

    {{! Modal renders in place - inherits theme-inverse }}
    <Modal
      @isOpen={{state.current}}
      @onClose={{state.toggle}}
      @renderInPlace={{true}}
      as |modal|
    >
      <modal.Header>Modal Header</modal.Header>
      <modal.Body>
        This modal inherits the theme-inverse from its parent.
      </modal.Body>
    </Modal>
  </div>
</template>
```

## Best Practices

### Always Set Base Backgrounds

Surface overlay colors are semi-transparent. Always provide a solid base background:

```html
<!-- ✓ Good - has base background -->
<div class="theme-inverse bg-surface-canvas">
  <div class="bg-surface-overlay-subtle p-4">
    Content
  </div>
</div>

<!-- ✗ Bad - overlay has no base -->
<div class="theme-inverse">
  <div class="bg-surface-overlay-subtle p-4">
    Content (might be invisible!)
  </div>
</div>
```

### Use Semantic Colors

Theme-inverse works automatically with semantic colors:

```html
<div class="theme-inverse p-6 bg-surface-canvas">
  <h3 class="text-neutral-strong">Heading</h3>
  <p class="text-neutral-firm">Body text</p>
  <button class="bg-primary text-on-primary">
    Action
  </button>
</div>
```

### Test Both Themes

Always test your UI in both light and dark modes:

```html
<!-- Test light mode -->
<html class="light">
  <!-- Your app -->
</html>

<!-- Test dark mode -->
<html class="dark">
  <!-- Your app -->
</html>
```

### Avoid Hard-Coded Colors

Don't use hard-coded Tailwind colors that don't adapt to themes:

```html
<!-- ✗ Bad - doesn't adapt to theme -->
<div class="bg-gray-900 text-white">
  Content
</div>

<!-- ✓ Good - adapts automatically -->
<div class="bg-surface-canvas text-neutral-strong">
  Content
</div>
```

## Dark/Light Variants

Tailwind's `dark:` and `light:` variants work correctly with `theme-inverse`:

```html
<div class="theme-inverse p-6 bg-surface-canvas">
  <div class="bg-white dark:bg-gray-900">
    <!-- In light mode with theme-inverse: shows gray-900 (dark theme) -->
    <!-- In dark mode with theme-inverse: shows white (light theme) -->
    Content
  </div>
</div>
```

The variants understand theme-inverse contexts:
- `dark:` applies in dark mode AND in `.light .theme-inverse`
- `light:` applies in light mode AND in `.dark .theme-inverse`

## How Theme Inverse Works

Under the hood:
- Theme-inverse only works with base themes (light and dark)
- In light mode, `.light .theme-inverse` applies dark theme colors
- In dark mode, `.dark .theme-inverse` applies light theme colors
- All CSS variables are automatically swapped
- Components work without modification

## Advanced: Multiple Theme Levels

You can nest theme-inverse multiple times, though it's rarely needed:

```html
<html class="dark">
  <!-- Dark theme -->
  <div class="theme-inverse">
    <!-- Light theme -->
    <div class="theme-inverse">
      <!-- Dark theme again -->
    </div>
  </div>
</html>
```

## Next Steps

- [CSS Variables Reference](css-variables.md) - Customize theme tokens
- [Customization Guide](customization.md) - Theme customization examples
- [Colors Documentation](../design-tokens/colors.md) - Understanding semantic colors

---

# Customization

Source: /docs/theming/configuration/customization.md

# Customization Guide

Complete guide to customizing Frontile's theme system, from simple token adjustments to comprehensive brand theming.

## Quick Start

The fastest way to customize Frontile is using CSS variables in your `app/styles/app.css`:

```css title="app/styles/app.css"
@import 'tailwindcss' source('../../');
@plugin "@frontile/theme/plugin/default";
@import '@frontile/theme';

@theme {
  --radius: 12px;
  --size-icon-md: 20px;
  --opacity-hover: 0.9;
}
```

## Customizing Colors

### Using JavaScript Configuration

Colors should be customized using JavaScript configuration for best results. Create `frontile.js` in your project root:

```js title="frontile.js" collapsible
const { frontile } = require('@frontile/theme/plugin');

module.exports = frontile({
  themes: {
    light: {
      colors: {
        primary: {
          subtle: '#f0f9ff',
          soft: '#7dd3fc',
          DEFAULT: '#0ea5e9',
          strong: '#0c4a6e'
        },
        success: {
          subtle: '#f0fdf4',
          soft: '#86efac',
          DEFAULT: '#22c55e',
          strong: '#14532d'
        },
        danger: {
          subtle: '#fef2f2',
          soft: '#fca5a5',
          DEFAULT: '#ef4444',
          strong: '#7f1d1d'
        },
        warning: {
          subtle: '#fffbeb',
          soft: '#fde68a',
          DEFAULT: '#f59e0b',
          strong: '#78350f'
        }
      }
    },
    dark: {
      colors: {
        primary: {
          subtle: '#0c4a6e',
          soft: '#0ea5e9',
          DEFAULT: '#38bdf8',
          strong: '#e0f2fe'
        }
        // ... other colors
      }
    }
  }
});
```

Then reference it in your CSS:

```css
@import 'tailwindcss' source('../../');
@plugin "./../../frontile.js";
@import '@frontile/theme';
```

### How Color Customization Works

Frontile automatically:

- Generates contrasting text colors (`on-{color}-{level}`)
- Converts your colors to OKLCH format for perceptual uniformity
- Accepts any color format as input (hex, rgb, hsl, oklch, CSS variables)
- Creates theme-aware CSS variables
- Ensures proper contrast ratios

### Customizing On-Colors

By default, Frontile auto-generates optimal `on-{color}-{level}` text colors (black or white) based on WCAG contrast calculations. If you need specific on-colors for brand consistency, you can override them in your theme configuration:

```js
const { frontile } = require('@frontile/theme/plugin');

module.exports = frontile({
  themes: {
    light: {
      colors: {
        primary: {
          subtle: '#eff6ff',
          soft: '#93c5fd',
          DEFAULT: '#3b82f6',
          strong: '#1e40af'
        },
        // Override specific on-colors
        'on-primary': {
          DEFAULT: '#ffffff', // Force white text on the bare primary fill
          strong: '#e0f2fe' // Use light blue instead of white
        }
        // on-primary-subtle and on-primary-soft will still be auto-generated
      }
    }
  }
});
```

**Key behavior:**

- Partial overrides work — define only the levels you want to customize, and the rest will be auto-generated
- Works for: `on-neutral`, `on-primary`, `on-secondary`, `on-tertiary`, `on-success`, `on-warning`, `on-danger`, `on-surface-modal`
- CSS variable references (e.g., `var(--my-color)`) are passed through as-is — auto-generation is skipped since contrast can't be calculated

## Customizing Typography

### Font Families

Override font families for different text categories:

```css
@font-face {
  font-family: 'Inter';
  src: url('/fonts/inter-var.woff2') format('woff2');
  font-weight: 100 900;
  font-display: swap;
}

@font-face {
  font-family: 'JetBrains Mono';
  src: url('/fonts/jetbrains-mono.woff2') format('woff2');
  font-display: swap;
}

@theme {
  --font-header: 'Inter', system-ui, sans-serif;
  --font-body: 'Inter', system-ui, sans-serif;
  --font-label: 'Inter', system-ui, sans-serif;
  --font-code: 'JetBrains Mono', monospace;
}
```

### Theme-Specific Fonts

Use different fonts for light and dark themes:

```css
.light,
.dark .theme-inverse {
  --font-body: 'Inter', system-ui, sans-serif;
}

.dark,
.light .theme-inverse {
  --font-body: 'Geist', system-ui, sans-serif;
}
```

## Customizing Border Radius

### Global Radius

Adjust border radius throughout your application:

```css
@theme {
  /* Softer, more rounded design */
  --radius: 12px;
  --radius-xl: 20px;
  --radius-2xl: 28px;
  --radius-pill: 9999px;
}
```

### Sharp Design

Create a more angular design:

```css
@theme {
  /* Sharp, geometric design */
  --radius: 2px;
  --radius-sm: 1px;
  --radius-md: 3px;
  --radius-xl: 6px;
  --radius-2xl: 8px;
}
```

## Customizing Icon Sizes

Adjust icon sizes to match your design:

```css
@theme {
  /* Slightly larger icons */
  --size-icon-xs: 13px;
  --size-icon-sm: 15px;
  --size-icon-md: 19px;
  --size-icon-lg: 23px;
  --size-icon-xl: 27px;
}
```

## Customizing Borders

### Border Widths

Adjust border thickness:

```css
@theme {
  /* Thicker borders throughout */
  --border-width-thin: 1px;
  --border-width-default: 2px;
  --border-width-heavy: 3px;
  --border-width-aggressive: 5px;
}
```

## Customizing Elevation

### Shadow Styles

Adjust shadow intensity and style:

```css
@theme {
  /* Subtler shadows */
  --shadow-elevation-1: 0px 1px 2px rgba(0, 0, 0, 0.04);
  --shadow-elevation-2: 0px 2px 8px rgba(0, 0, 0, 0.06);
  --shadow-elevation-3: 0px 8px 16px rgba(0, 0, 0, 0.08);
  --shadow-elevation-4: 0px 16px 32px rgba(0, 0, 0, 0.12);
}
```

### Theme-Specific Shadows

Different shadows for light and dark modes:

```css
/* Light theme - softer shadows */
.light,
.dark .theme-inverse {
  --shadow-elevation-2: 0px 2px 8px rgba(0, 0, 0, 0.08);
  --shadow-elevation-3: 0px 8px 20px rgba(0, 0, 0, 0.12);
}

/* Dark theme - stronger shadows for contrast */
.dark,
.light .theme-inverse {
  --shadow-elevation-2: 0px 4px 12px rgba(0, 0, 0, 0.4);
  --shadow-elevation-3: 0px 12px 28px rgba(0, 0, 0, 0.5);
}
```

## Customizing Opacity

Adjust hover and disabled opacity:

```css
@theme {
  --opacity-hover: 0.9;
  --opacity-disabled: 0.4;
}
```

## Customizing Component Sizes

### Modal Sizes

Adjust modal dimensions:

```css
:root {
  --modal-xs: 18rem;
  --modal-sm: 22rem;
  --modal-md: 32rem;
  --modal-lg: 48rem;
  --modal-xl: 64rem;
}

/* Responsive sizing */
@media (max-width: 768px) {
  :root {
    --modal-md: 90vw;
    --modal-lg: 90vw;
    --modal-xl: 95vw;
  }
}
```

### Drawer Sizes

```css
:root {
  --drawer-sm: 20rem;
  --drawer-md: 32rem;
  --drawer-lg: 48rem;
  --drawer-xl: 64rem;
}
```

## Setting Default Theme

Specify which theme loads by default:

```js
// frontile.js
module.exports = frontile({
  defaultTheme: 'dark', // or 'light'
  themes: {
    light: {/* ... */},
    dark: {/* ... */}
  }
});
```

## Complete Brand Example

Here's a complete example of customizing Frontile for a brand:

### frontile.js

```js
const { frontile } = require('@frontile/theme/plugin');

module.exports = frontile({
  defaultTheme: 'light',
  themes: {
    light: {
      colors: {
        // Purple brand color
        primary: {
          subtle: '#faf5ff',
          soft: '#c084fc',
          DEFAULT: '#9333ea',
          strong: '#581c87'
        },
        // Success remains green
        success: {
          subtle: '#f0fdf4',
          soft: '#86efac',
          DEFAULT: '#22c55e',
          strong: '#14532d'
        },
        // Custom orange warning
        warning: {
          subtle: '#fff7ed',
          soft: '#fdba74',
          DEFAULT: '#f97316',
          strong: '#7c2d12'
        }
      }
    },
    dark: {
      colors: {
        primary: {
          subtle: '#581c87',
          soft: '#9333ea',
          DEFAULT: '#a855f7',
          strong: '#f3e8ff'
        }
        // ... other colors
      }
    }
  }
});
```

### app/styles/app.css

```css
@import 'tailwindcss' source('../../');
@plugin "./../../frontile.js";
@import '@frontile/theme';

/* Load custom fonts */
@font-face {
  font-family: 'Poppins';
  src: url('/fonts/poppins-var.woff2') format('woff2');
  font-weight: 100 900;
  font-display: swap;
}

@theme {
  /* Typography */
  --font-header: 'Poppins', system-ui, sans-serif;
  --font-body: 'Poppins', system-ui, sans-serif;
  --font-label: 'Poppins', system-ui, sans-serif;

  /* Rounded design */
  --radius: 12px;
  --radius-xl: 20px;
  --radius-2xl: 24px;

  /* Slightly larger icons */
  --size-icon-sm: 16px;
  --size-icon-md: 20px;
  --size-icon-lg: 24px;

  /* Subtle opacity changes */
  --opacity-hover: 0.9;
  --opacity-disabled: 0.5;
}

/* Component customization */
:root {
  /* Wider modals */
  --modal-md: 36rem;
  --modal-lg: 52rem;
}
```

## Common Customization Patterns

### Pattern 1: Minimal/Sharp Design

```css
@theme {
  --radius: 2px;
  --radius-xl: 4px;
  --radius-2xl: 6px;
  --border-width-default: 1px;
  --shadow-elevation-2: 0px 1px 3px rgba(0, 0, 0, 0.06);
}
```

### Pattern 2: Soft/Rounded Design

```css
@theme {
  --radius: 16px;
  --radius-xl: 24px;
  --radius-2xl: 32px;
  --shadow-elevation-2: 0px 8px 24px rgba(0, 0, 0, 0.08);
}
```

### Pattern 3: Bold/High Contrast

```css
@theme {
  --border-width-default: 2px;
  --border-width-heavy: 3px;
  --opacity-hover: 0.95;
}

.light,
.dark .theme-inverse {
  --shadow-elevation-2: 0px 4px 12px rgba(0, 0, 0, 0.15);
}
```

### Pattern 4: Subtle/Minimal

```css
@theme {
  --border-width-thin: 0.5px;
  --border-width-default: 1px;
  --opacity-hover: 0.85;
  --shadow-elevation-2: 0px 2px 4px rgba(0, 0, 0, 0.04);
}
```

## Advanced: Per-Component Customization

Override styles for specific components using Tailwind variants:

```css
/* Larger buttons */
.btn-lg {
  @apply px-6 py-3 text-label-lg;
}

/* Card with custom shadow */
.card {
  @apply rounded-2xl shadow-elevation-3;
}

/* Custom modal backdrop */
.modal-backdrop {
  @apply bg-surface-overlay-strong dark:bg-surface-lift-strong backdrop-blur-md;
}
```

## Testing Your Customizations

### Visual Regression Testing

Test your theme in different scenarios:

```html
<!-- Test light mode -->
<html class="light">
  <!-- Your components -->
</html>

<!-- Test dark mode -->
<html class="dark">
  <!-- Your components -->
</html>

<!-- Test theme-inverse -->
<div class="theme-inverse bg-surface-canvas">
  <!-- Your components -->
</div>
```

### Browser DevTools

Use browser DevTools to inspect CSS variables:

```js
// Check current value
getComputedStyle(document.documentElement).getPropertyValue('--radius');

// Test changes
document.documentElement.style.setProperty('--radius', '16px');
```

## Best Practices

### Document Your Customizations

Add comments explaining why values were chosen:

```css
@theme {
  /* Brand guideline requires 16px minimum border radius */
  --radius: 16px;

  /* Larger icons for better visibility on mobile */
  --size-icon-md: 22px;
}
```

### Use Consistent Scales

Maintain proportional relationships when customizing:

```css
/* Good - maintains scale relationships */
@theme {
  --radius-sm: 4px;
  --radius: 8px;
  --radius-xl: 16px;
  --radius-2xl: 24px;
}

/* Avoid - breaks scale relationships */
@theme {
  --radius-sm: 2px;
  --radius: 20px;
  --radius-xl: 15px;
  --radius-2xl: 8px;
}
```

### Test Accessibility

Ensure customizations maintain accessibility:

- Maintain sufficient color contrast (WCAG AA minimum 4.5:1)
- Don't reduce opacity below readable levels
- Test with screen readers
- Verify keyboard navigation remains clear

### Performance Considerations

- CSS variable changes are performant
- Avoid excessive theme switching
- Use `prefers-reduced-motion` for users who need it:

```css
@media (prefers-reduced-motion: reduce) {
  * {
    transition-duration: 0.01ms !important;
  }
}
```

## Troubleshooting

### Colors Not Updating

**Problem**: Changed color values but UI doesn't update

**Solution**: Colors must be configured via JavaScript, not CSS variables:

```js
// Correct
module.exports = frontile({
  themes: {
    light: {
      colors: {
        primary: {/* ... */}
      }
    }
  }
});
```

### Utilities Not Generated

**Problem**: Custom CSS variable doesn't generate utility class

**Solution**: Make sure the variable is in the `@theme` block:

```css
/* Generates utilities */
@theme {
  --radius-custom: 10px;
}

/* Does NOT generate utilities */
:root {
  --radius-custom: 10px;
}
```

### Theme-Specific Values Not Applying

**Problem**: Theme-specific overrides don't work

**Solution**: Use both selectors for proper theme-inverse support:

```css
/* Correct */
.light,
.dark .theme-inverse {
  --opacity-hover: 0.85;
}

/* Incomplete */
.light {
  --opacity-hover: 0.85;
}
```

## Next Steps

- [CSS Variables Reference](css-variables.md) - Complete variable list
- [Design Tokens](../design-tokens/overview.md) - Understanding tokens
- [Theme Switching](theme-switching.md) - Implement theme toggling

---

# 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 { action } from '@ember/object';
import { fn } from '@ember/helper';
import { ButtonGroup } from 'frontile';

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

  @action
  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='sm'>Chip sm</Chip>
    <Chip @size='md'>Chip md</Chip>
    <Chip @size='lg'>Chip lg</Chip>
  </div>
</template>
```

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 '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 { action } from '@ember/object';
import { ToggleButton } from 'frontile';
import { StarIcon } from 'site/components/icons';

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

  @action
  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 { action } from '@ember/object';
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
  };

  @action
  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>
```

### 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` leaves an empty avatar.** There is no automatic fallback to
  initials, so if the URL may fail, pass both a `@name` and no `@src` until you
  know the image loads, or handle the failure yourself.

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. |
| `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. |

---

# 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. |

---

# 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' \| 'separator' \| 'key'>` | - | 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` | `'rounded' \| 'square' \| 'circle' \| 'text' \| '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<'base' \| 'title' \| 'icon' \| 'content' \| 'description' \| 'closeButton' \| 'inner' \| '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<'base' \| 'footer' \| 'input' \| 'kbd' \| 'loading' \| 'inputWrapper' \| 'inputIcon' \| 'list' \| 'empty' \| 'footerHint'>` | - |  |
| `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<'base' \| 'footer' \| 'input' \| 'kbd' \| 'loading' \| 'inputWrapper' \| 'inputIcon' \| 'list' \| 'empty' \| 'footerHint'>` | - |  |
| `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<'base' \| 'footer' \| 'input' \| 'kbd' \| 'loading' \| 'inputWrapper' \| 'inputIcon' \| 'list' \| 'empty' \| 'footerHint'>` | - |  |
| `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<'base' \| 'footer' \| 'input' \| 'kbd' \| 'loading' \| 'inputWrapper' \| 'inputIcon' \| 'list' \| 'empty' \| 'footerHint'>` | - | _(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' \| 'blur' \| 'transparent'` | - |  |
| `class` | `string` | - |  |
| `classes` | `SlotsToClasses<'base' \| 'footer' \| 'input' \| 'kbd' \| 'loading' \| 'inputWrapper' \| 'inputIcon' \| 'list' \| 'empty' \| 'footerHint'>` | - |  |
| `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 { action } from '@ember/object';
import { Dropdown } from 'frontile';
import {
  ViewIcon,
  EditIcon,
  DuplicateIcon,
  ShareIcon,
  DownloadIcon,
  ArchiveIcon,
  DeleteIcon
} from 'site/components/icons';

export default class BasicDropdown extends Component {
  @action
  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 { action } from '@ember/object';
import { Dropdown } from 'frontile';

export default class DropdownWithDetails extends Component {
  @action
  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 { action } from '@ember/object';
import { Dropdown } from 'frontile';

export default class SelectableDropdown extends Component {
  @tracked selectedKeys = ['bold'];

  @action
  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 { action } from '@ember/object';
import { Dropdown } from 'frontile';

export default class TriggerStyles extends Component {
  @action
  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 { action } from '@ember/object';
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'
  ];

  @action
  setPlacement(placement: string) {
    this.placement = placement;
  }

  @action
  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 { action } from '@ember/object';
import { Dropdown } from 'frontile';

export default class DisabledItems extends Component {
  disabledKeys = ['share', 'delete'];

  @action
  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 { action } from '@ember/object';
import { Dropdown } from 'frontile';

export default class KeepOpenDropdown extends Component {
  @tracked filters = ['recent'];

  @action
  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 { action } from '@ember/object';
import { Dropdown } from 'frontile';

export default class SectionedDropdown extends Component {
  @action
  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 { action } from '@ember/object';
import { Dropdown } from 'frontile';

export default class CustomHandlers extends Component {
  @action
  handleEdit() {
    alert('Edit clicked');
  }

  @action
  handleDelete() {
    if (confirm('Are you sure you want to delete?')) {
      alert('Deleted!');
    }
  }

  @action
  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 { action } from '@ember/object';
import { fn } from '@ember/helper';
import { Dropdown, ButtonGroup } from 'frontile';

export default class DropdownBackdrop extends Component {
  @tracked backdrop = 'none';

  @action
  setBackdrop(type: string) {
    this.backdrop = type;
  }

  @action
  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 { action } from '@ember/object';
import { Dropdown } from 'frontile';

export default class DropdownWithCallback extends Component {
  @action
  handleDidClose() {
    // eslint-disable-next-line
    console.log('Dropdown closed');
  }

  @action
  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 { action } from '@ember/object';
import { Dropdown } from 'frontile';

export default class SubmenuDropdown extends Component {
  @action
  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 { action } from '@ember/object';
import { Dropdown } from 'frontile';

export default class NestedSubmenuDropdown extends Component {
  @action
  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 { action } from '@ember/object';
import { Dropdown } from 'frontile';

export default class SiblingSubmenuDropdown extends Component {
  @action
  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` | `{ padding?: Padding; mainAxis?: boolean; crossAxis?: boolean \| 'alignment'; fallbackPlacements?: Placement[]; fallbackStrategy?: 'bestFit' \| 'initialPlacement'; fallbackAxisSideDirection?: 'start' \| ... 1 more ... \| 'none'; ... 4 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: Platform; elements: Elements; }) => Promisable<...>; }[]` | - | Additional floating-ui middleware, for positioning behavior beyond what placement, offsetOptions, flipOptions, and shiftOptions cover. |
| `offsetOptions` | `OffsetOptions` | `5` |  |
| `placement` | `'bottom' \| 'left' \| 'right' \| 'top' \| 'top-start' \| 'top-end' \| 'right-start' \| 'right-end' \| 'bottom-start' \| 'bottom-end' \| 'left-start' \| 'left-end'` | `'bottom-start'` | Placement of the menu when open |
| `shiftOptions` | `{ padding?: Padding; mainAxis?: boolean; crossAxis?: boolean; rootBoundary?: RootBoundary; elementContext?: ElementContext; altBoundary?: boolean; 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 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 { action } from '@ember/object';
import { Listbox } from 'frontile';

export default class BasicListbox extends Component {
  @tracked selectedKeys: string[] = ['lion'];

  animals = [
    'cheetah',
    'crocodile',
    'elephant',
    'giraffe',
    'lion',
    'panda',
    'tiger',
    'zebra'
  ];

  @action
  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 { action } from '@ember/object';
import { Listbox } from 'frontile';

export default class MultipleSelection extends Component {
  @tracked selectedKeys: string[] = ['lion', 'tiger'];

  animals = [
    'cheetah',
    'crocodile',
    'elephant',
    'giraffe',
    'lion',
    'panda',
    'tiger',
    'zebra'
  ];

  @action
  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 { action } from '@ember/object';
import { Listbox } from 'frontile';
import {
  ViewIcon,
  EditIcon,
  ShareIcon,
  DeleteIcon
} from 'site/components/icons';

export default class StaticItems extends Component {
  disabledKeys = ['delete'];

  @action
  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 { action } from '@ember/object';
import { Listbox } from 'frontile';

export default class ActionMenu extends Component {
  @action
  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 { action } from '@ember/object';
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'];

  @action
  setVariant(variant: string) {
    this.variant = variant;
  }

  @action
  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 { action } from '@ember/object';
import { Listbox } from 'frontile';

export default class DisabledItems extends Component {
  @tracked selectedKeys: string[] = ['feature1'];

  disabledKeys = ['feature3', 'feature4'];

  features = ['feature1', 'feature2', 'feature3', 'feature4', 'feature5'];

  @action
  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 { action } from '@ember/object';
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'
    }
  ];

  @action
  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 { action } from '@ember/object';
import { Listbox } from 'frontile';

export default class WithDividers extends Component {
  @action
  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 { action } from '@ember/object';
import { Listbox, Button } from 'frontile';

export default class EmptySelection extends Component {
  @tracked allowEmpty = true;
  @tracked selectedKeys: string[] = ['option2'];

  options = ['option1', 'option2', 'option3'];

  @action
  toggleAllowEmpty() {
    this.allowEmpty = !this.allowEmpty;
  }

  @action
  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` | `'menu' \| 'listbox'` | - |  |
| `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` | `'menu' \| 'listbox'` | - |  |
| `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` | `'menu' \| 'listbox'` | - |  |
| `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 { action } from '@ember/object';
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' }
  ];

  @action
  toggleLoading() {
    this.isLoading = !this.isLoading;
  }

  @action
  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<'table' \| 'tbody' \| 'td' \| 'tfoot' \| 'th' \| 'thead' \| 'tr' \| 'separator' \| 'wrapper' \| 'empty' \| 'toolbar' \| 'sortButton' \| 'sortIcon' \| 'columnVisibilityButton' \| 'columnVisibilityIcon' \| '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` | `'left' \| 'right'` | - | 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` | `'left' \| 'right'` | - | 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 { action } from '@ember/object';
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' }
  ];

  @action toggleLoading() {
    this.isLoading = !this.isLoading;
  }

  @action 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 { action } from '@ember/object';
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>[];

  @action 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 { action } from '@ember/object';
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;
  };

  @action 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<'table' \| 'tbody' \| 'td' \| 'tfoot' \| 'th' \| 'thead' \| 'tr' \| 'separator' \| 'wrapper' \| 'empty' \| 'toolbar' \| 'sortButton' \| 'sortIcon' \| 'columnVisibilityButton' \| 'columnVisibilityIcon' \| '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' \| 'body' \| 'footer' \| 'header' \| 'nav' \| 'title' \| 'cell' \| 'indicator' \| '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' \| 'blur' \| 'transparent'` | - | 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<'base' \| 'input' \| 'icon' \| 'innerContainer' \| 'startContent' \| 'endContent' \| '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` | `{ padding?: Padding; mainAxis?: boolean; crossAxis?: boolean \| 'alignment'; fallbackPlacements?: Placement[]; fallbackStrategy?: 'bestFit' \| 'initialPlacement'; fallbackAxisSideDirection?: 'start' \| ... 1 more ... \| 'none'; ... 4 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: 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` | `'bottom' \| 'left' \| 'right' \| 'top' \| 'top-start' \| 'top-end' \| 'right-start' \| 'right-end' \| 'bottom-start' \| 'bottom-end' \| '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` | `{ padding?: Padding; mainAxis?: boolean; crossAxis?: boolean; rootBoundary?: RootBoundary; elementContext?: ElementContext; altBoundary?: boolean; 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 { action } from '@ember/object';
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
  @action
  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 { action } from '@ember/object';
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
  @action
  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);
    }
  }

  @action
  handleFormChange(data: FormResultData<Schema>) {
    this.formData = data.data;
  }

  @action
  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 { action } from '@ember/object';
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
  @action
  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);
    }
  }

  @action
  handleFormChange(data: FormResultData<Schema>) {
    this.formData = data.data;
  }

  @action
  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 { action } from '@ember/object';
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 = '';

  @action
  handleFormChange(data: FormResultData<Schema>) {
    this.formData = data.data;
  }

  @action
  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 { action } from '@ember/object';
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 = '';

  @action
  handleFormChange(data: FormResultData<Schema>) {
    this.formData = data.data;
  }

  @action
  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. |

---

# DatePicker

Source: /docs/components/forms/date-picker.md

# DatePicker

A date field: a button trigger showing the formatted value, and a [Calendar](../collections/calendar)
in a popover. Use it for picking a single day or, with `@mode="range"`, a start/end range.

## Import

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

## Usage

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

<template>
  <div class='demo-stack'>
    <DatePicker @label='Start date' @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.

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 that only has its start chosen stays open — the trigger shows the anchor alone until
a second click completes it.

## 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'
        @placeholder='Pick a 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 trigger renders, receiving
`{ value, formatted, isEmpty }`. 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'>
      <: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`, and defaults to
`{ dateStyle: 'medium' }`.

```gts preview
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' />
      <DatePicker
        @label='Full'
        @value={{value}}
        @locale='en-US'
        @formatOptions={{full}}
      />
      <DatePicker
        @label='Numeric'
        @value={{value}}
        @locale='en-US'
        @formatOptions={{numeric}}
      />
    </div>
  </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` swaps the calendar icon for a clear button once there is a value. It never
renders on a disabled picker.

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

const defaultValue = new Date(2026, 0, 20);

<template>
  <div class='demo-stack'>
    <DatePicker
      @label='Start date'
      @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>
}
```

## Accessibility

| Element | What it exposes |
| --- | --- |
| Trigger | A `<button>` with `aria-haspopup="dialog"`. 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". |

Opening the picker moves focus onto the selected (or today's) day inside the grid. `Escape`
closes the calendar and returns focus to the trigger, as does completing a selection or
clicking outside. `@onBlur` fires only once focus leaves the whole control — the trigger and
its popover — not on the way into the calendar.

## API

### DatePicker

A date field: a button trigger showing the formatted value, and a calendar
in a popover. @mode="range" switches both the calendar and the value shape
to a { start, end } range.

**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<'base' \| 'footer' \| 'input' \| 'icon' \| 'innerContainer' \| 'startContent' \| 'endContent' \| 'clearButton' \| 'placeholder' \| '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'` | 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. |
| `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` | `{ padding?: Padding; mainAxis?: boolean; crossAxis?: boolean \| 'alignment'; fallbackPlacements?: Placement[]; fallbackStrategy?: 'bestFit' \| 'initialPlacement'; fallbackAxisSideDirection?: 'start' \| ... 1 more ... \| 'none'; ... 4 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. |
| `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: 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. |
| `placement` | `'bottom' \| 'left' \| 'right' \| 'top' \| 'top-start' \| 'top-end' \| 'right-start' \| 'right-end' \| 'bottom-start' \| 'bottom-end' \| 'left-start' \| 'left-end'` | `'bottom-start'` | Placement of the menu when open |
| `popoverSize` | `'sm' \| 'md' \| 'lg' \| 'trigger' \| 'xl' \| '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 |
| `shiftOptions` | `{ padding?: Padding; mainAxis?: boolean; crossAxis?: boolean; rootBoundary?: RootBoundary; elementContext?: ElementContext; altBoundary?: boolean; 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 { action } from '@ember/object';
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);
  };

  @action
  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); 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` | `('input' \| 'submit' \| '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' \| 'container' \| 'separator' \| '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' \| 'input' \| 'innerContainer' \| 'startContent' \| 'endContent'>` | - | 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<'base' \| 'input' \| 'icon' \| 'innerContainer' \| 'startContent' \| 'endContent'>` | - | 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 { action } from '@ember/object';
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 = '';

  @action
  handleFormChange(data: FormResultData<Schema>) {
    this.formData = data.data;
    this.submitMessage = '';
  }

  @action
  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' \| 'blur' \| 'transparent'` | - | 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<'base' \| 'input' \| 'icon' \| 'innerContainer' \| 'startContent' \| 'endContent' \| '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` | `{ padding?: Padding; mainAxis?: boolean; crossAxis?: boolean \| 'alignment'; fallbackPlacements?: Placement[]; fallbackStrategy?: 'bestFit' \| 'initialPlacement'; fallbackAxisSideDirection?: 'start' \| ... 1 more ... \| 'none'; ... 4 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: 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` | `'bottom' \| 'left' \| 'right' \| 'top' \| 'top-start' \| 'top-end' \| 'right-start' \| 'right-end' \| 'bottom-start' \| 'bottom-end' \| '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` | `{ padding?: Padding; mainAxis?: boolean; crossAxis?: boolean; rootBoundary?: RootBoundary; elementContext?: ElementContext; altBoundary?: boolean; 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` | `'menu' \| 'listbox'` | - |  |
| `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 { action } from '@ember/object';
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 = '';

  @action
  handleFormChange(data: FormResultData<Schema>) {
    this.formData = data.data;
  }

  @action
  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' \| 'input' \| 'innerContainer' \| 'startContent' \| 'endContent'>` | - | 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. |

---

# FormCheckboxGroup

Source: /docs/components/forms-legacy/form-checkbox-group.md

# FormCheckboxGroup

## API

### FormCheckboxGroup

**Element:** `HTMLDivElement`

**Arguments**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `containerClass` | `string` | - | CSS classes to be added in the container element |
| `errors` | `string \| string[]` | - | A list of errors or a single text describing the error |
| `hasError` | `boolean` | - | If has errors |
| `hasSubmitted` | `boolean` | - | If the form has been submitted, used to force displaying errors |
| `hint` | `string` | - | A help text to be displayed |
| `isInline` | `boolean` | - | If the Checkbox should be in one line |
| `label` | `string` | - | The group label |
| `onChange` | `(value: unknown, event: Event) => void` | - | Default callback added to the yielded FormCheckbox component, called when onchange is triggered |
| `showError` | `boolean` | - | Force displaying errors |
| `size` | `'sm' \| 'md' \| 'lg'` | - | The size |

**Blocks**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `default *` | `[checkbox: FormCheckbox (privateContainerClass, _parentOnChange, size bound), api: { onChange: (value: unknown, event: Event) => void; }]` | - |  |

---

# FormCheckbox

Source: /docs/components/forms-legacy/form-checkbox.md

# FormCheckbox

## API

### FormCheckbox

**Element:** `HTMLInputElement`

**Arguments**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `checked *` | `boolean` | - | If the checkbox is checked. You must also pass onChange to update its value. |
| `onChange *` | `(value: boolean, event: Event) => void` | - | Callback when onchange is triggered |
| `containerClass` | `string` | - | CSS classes to be added in the container element |
| `hint` | `string` | - | A help text to be displayed |
| `label` | `string` | - | The input field label |
| `name` | `string` | - | The name of the checkbox |
| `size` | `'sm' \| 'md' \| 'lg'` | - | The size |

**Blocks**

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

---

# FormInput

Source: /docs/components/forms-legacy/form-input.md

# FormInput

## API

### FormInput

**Element:** `HTMLInputElement`

**Arguments**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `value *` | `string` | - | The value to be used in the input. You must also pass onChange or onInput to update its value. |
| `containerClass` | `string` | - | CSS classes to be added in the container element |
| `errors` | `string \| string[]` | - | A list of errors or a single text describing the error |
| `hasError` | `boolean` | - | If has errors |
| `hasSubmitted` | `boolean` | - | If the form has been submitted, used to force displaying errors |
| `hint` | `string` | - | A help text to be displayed |
| `inputClass` | `string` | - | CSS classes to be added in the input element |
| `label` | `string` | - | The group label |
| `onChange` | `(value: string, event: InputEvent) => void` | - | Callback when onchange is triggered |
| `onFocusIn` | `(event: FocusEvent) => void` | - | Callback when onfocus is triggered |
| `onFocusOut` | `(event: FocusEvent) => void` | - | Callback when onblur is triggered |
| `onInput` | `(value: string, event: InputEvent) => void` | - | Callback when oninput is triggered |
| `showError` | `boolean` | - | Force displaying errors |
| `size` | `'sm' \| 'md' \| 'lg'` | - | The size |
| `type` | `string` | `'text'` | The input type |

**Blocks**

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

---

# FormRadioGroup

Source: /docs/components/forms-legacy/form-radio-group.md

# FormRadioGroup

## API

### FormRadioGroup

**Element:** `HTMLDivElement`

**Arguments**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `value *` | `string \| number \| boolean` | - |  |
| `containerClass` | `string` | - | CSS classes to be added in the container element |
| `errors` | `string \| string[]` | - | A list of errors or a single text describing the error |
| `hasError` | `boolean` | - | If has errors |
| `hasSubmitted` | `boolean` | - | If the form has been submitted, used to force displaying errors |
| `hint` | `string` | - | A help text to be displayed |
| `isInline` | `boolean` | - | If the Checkbox should be in one line |
| `label` | `string` | - | The group label |
| `onChange` | `(value: unknown, event: Event) => void` | - | Default callback added to the yielded FormRadio component, called when onchange is triggered |
| `showError` | `boolean` | - | Force displaying errors |
| `size` | `'sm' \| 'md' \| 'lg'` | - | The size |

**Blocks**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `default *` | `[radio: FormRadio (checked, privateContainerClass, _parentOnChange, size, name bound)]` | - |  |

---

# FormRadio

Source: /docs/components/forms-legacy/form-radio.md

# FormRadio

## API

### FormRadio

**Element:** `HTMLInputElement`

**Arguments**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `checked *` | `unknown` | - | The current checked value. This will be used to compare against the value argument, if equal, the radio will me marked as checked. |
| `onChange *` | `(value: unknown, event: Event) => void` | - | Callback when onchange is triggered |
| `value *` | `string \| number \| boolean` | - | The value to be used in the radio button. You must also pass onChange to update its value. |
| `containerClass` | `string` | - | CSS classes to be added in the container element |
| `hint` | `string` | - | A help text to be displayed |
| `label` | `string` | - | The input field label |
| `name` | `string` | - | The name of the checkbox |
| `size` | `'sm' \| 'md' \| 'lg'` | - | The size |

**Blocks**

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

---

# FormSelect

Source: /docs/components/forms-legacy/form-select.md

# FormSelect

We use [Ember Power Select](https://github.com/cibernox/ember-power-select/)
under the hood to deliver the best select experience. Please refer to their
documentation for further customization.

In the example below, we have a label, hint, error validation, search and `allowClear`.

## API

### FormSelect

**Element:** `HTMLDivElement`

**Arguments**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `onChange *` | `(selection: any, select: Select, event?: Event) => void` | - |  |
| `afterOptionsComponent` | `string \| ComponentLike<any>` | - |  |
| `allowClear` | `boolean` | - |  |
| `animationEnabled` | `boolean` | - |  |
| `ariaDescribedBy` | `string` | - |  |
| `ariaInvalid` | `string` | - |  |
| `ariaLabel` | `string` | - |  |
| `ariaLabelledBy` | `string` | - |  |
| `beforeOptionsComponent` | `string \| ComponentLike<any>` | - |  |
| `buildSelection` | `(selected: any, select: Select) => any` | - |  |
| `calculatePosition` | `CalculatePosition` | - |  |
| `closeOnSelect` | `boolean` | - |  |
| `containerClass` | `string` | - | CSS classes to be added in the container element |
| `defaultHighlighted` | `any` | - |  |
| `destination` | `string` | - |  |
| `destinationElement` | `HTMLElement` | - |  |
| `disabled` | `boolean` | - |  |
| `dropdownClass` | `string` | - |  |
| `ebdContentComponent` | `string \| ComponentLike<any>` | - |  |
| `ebdTriggerComponent` | `string \| ComponentLike<any>` | - |  |
| `errors` | `string \| string[]` | - | A list of errors or a single text describing the error |
| `eventType` | `string` | - |  |
| `extra` | `any` | - |  |
| `groupComponent` | `string \| ComponentLike<any>` | - |  |
| `hasError` | `boolean` | - | If has errors |
| `hasSubmitted` | `boolean` | - | If the form has been submitted, used to force displaying errors |
| `highlightOnHover` | `boolean` | - |  |
| `hint` | `string` | - | A help text to be displayed |
| `horizontalPosition` | `string` | - |  |
| `initiallyOpened` | `boolean` | - |  |
| `isMultiple` | `boolean` | - | If is multiple select instead of single |
| `label` | `string` | - | The input field label |
| `labelClass` | `string` | - |  |
| `labelClickAction` | `TLabelClickAction` | - |  |
| `labelComponent` | `string \| ComponentLike<any>` | - |  |
| `labelTag` | `keyof HTMLElementTagNameMap` | - |  |
| `labelText` | `string` | - |  |
| `legacyMultiple` | `boolean` | - |  |
| `loadingMessage` | `string` | - |  |
| `matcher` | `MatcherFn` | - |  |
| `matchTriggerWidth` | `boolean` | - |  |
| `multiple` | `boolean` | - |  |
| `noMatchesMessage` | `string` | - |  |
| `noMatchesMessageComponent` | `string \| ComponentLike<any>` | - |  |
| `onBlur` | `(select: Select, event: FocusEvent) => void` | - |  |
| `onClose` | `(select: Select, e: Event) => boolean \| void` | - |  |
| `onFocus` | `(select: Select, event: FocusEvent) => void` | - |  |
| `onFocusIn` | `(select: Select, event: FocusEvent) => void` | - |  |
| `onFocusOut` | `(select: Select, event: FocusEvent) => void` | - |  |
| `onInput` | `(term: string, select: Select, e: Event) => string \| boolean \| void` | - |  |
| `onKeydown` | `(select: Select, e: KeyboardEvent) => boolean \| void` | - |  |
| `onOpen` | `(select: Select, e: Event) => boolean \| void` | - |  |
| `options` | `readonly any[] \| Promise<readonly any[]>` | - |  |
| `optionsComponent` | `string \| ComponentLike<any>` | - |  |
| `placeholder` | `string` | - |  |
| `placeholderComponent` | `string \| ComponentLike<any>` | - |  |
| `preventScroll` | `boolean` | - |  |
| `registerAPI` | `(select: Select) => void` | - |  |
| `renderInPlace` | `boolean` | - |  |
| `required` | `string` | - |  |
| `resultCountMessage` | `(resultCount: number) => string` | - |  |
| `rootEventType` | `TRootEventType` | - |  |
| `scrollTo` | `(option: any, select: Select) => void` | - |  |
| `search` | `(term: string, select: Select) => readonly any[] \| Promise<readonly any[]>` | - |  |
| `searchEnabled` | `boolean` | - |  |
| `searchField` | `string` | - |  |
| `searchFieldPosition` | `TSearchFieldPosition` | - |  |
| `searchMessage` | `string` | - |  |
| `searchMessageComponent` | `string \| ComponentLike<any>` | - |  |
| `searchPlaceholder` | `string` | - |  |
| `selected` | `any` | - |  |
| `selectedItemComponent` | `string \| ComponentLike<any>` | - |  |
| `showError` | `boolean` | - | Force displaying errors |
| `size` | `'sm' \| 'md' \| 'lg'` | - | The size |
| `tabindex` | `string \| number` | - |  |
| `title` | `string` | - |  |
| `triggerClass` | `string` | - |  |
| `triggerComponent` | `string \| ComponentLike<any>` | - |  |
| `triggerId` | `string` | - |  |
| `triggerRole` | `string` | - |  |
| `typeAheadOptionMatcher` | `MatcherFn` | - |  |
| `verticalPosition` | `string` | - |  |

**Blocks**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `default *` | `[unknown, Select]` | - |  |

---

# FormTextarea

Source: /docs/components/forms-legacy/form-textarea.md

# FormTextarea

## API

### FormTextarea

**Element:** `HTMLTextAreaElement`

**Arguments**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `value *` | `string` | - | The value to be used in the input. You must also pass onChange or onInput to update its value. |
| `containerClass` | `string` | - | CSS classes to be added in the container element |
| `errors` | `string \| string[]` | - | A list of errors or a single text describing the error |
| `hasError` | `boolean` | - | If has errors |
| `hasSubmitted` | `boolean` | - | If the form has been submitted, used to force displaying errors |
| `hint` | `string` | - | A help text to be displayed |
| `inputClass` | `string` | - | CSS classes to be added in the input element |
| `label` | `string` | - | The group label |
| `onChange` | `(value: string, event: InputEvent) => void` | - | Callback when onchange is triggered |
| `onFocusIn` | `(event: FocusEvent) => void` | - | Callback when onfocus is triggered |
| `onFocusOut` | `(event: FocusEvent) => void` | - | Callback when onblur is triggered |
| `onInput` | `(value: string, event: InputEvent) => void` | - | Callback when oninput is triggered |
| `showError` | `boolean` | - | Force displaying errors |
| `size` | `'sm' \| 'md' \| 'lg'` | - | The size |
| `type` | `string` | `'text'` | The input type |

**Blocks**

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

---

# 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 { action } from '@ember/object';
import { Drawer } from 'frontile';
import { Button } from 'frontile';

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

  @action 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 { action } from '@ember/object';
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'];

  @action openDrawer(variant) {
    this.selectedVariant = variant;
    this.isOpen = true;
  }

  @action 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 { action } from '@ember/object';
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'];

  @action openDrawer(variant) {
    this.selectedVariant = variant;
    this.isOpen = true;
  }

  @action 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 { action } from '@ember/object';
import { Drawer } from 'frontile';
import { Button } from 'frontile';

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

  @action 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 { action } from '@ember/object';
import { Drawer } from 'frontile';
import { Button } from 'frontile';
import { SettingsIcon } from 'site/components/icons';

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

  @action 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 { action } from '@ember/object';
import { Drawer, Button } from 'frontile';

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

  @action toggle() {
    this.isOpen = !this.isOpen;
  }

  @action 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 { action } from '@ember/object';
import { Drawer, Button, Alert } from 'frontile';
import { SettingsIcon } from 'site/components/icons';

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

  @action 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 { action } from '@ember/object';
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.'
    }
  ];

  @action openDrawer(placement) {
    this.selectedPlacement = placement;
    this.isOpen = true;
  }

  @action 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 { action } from '@ember/object';
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.'
    }
  ];

  @action openDrawer(size) {
    this.selectedSize = size;
    this.isOpen = true;
  }

  @action 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 { action } from '@ember/object';
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'];

  @action openDrawer(variant) {
    this.selectedVariant = variant;
    this.isOpen = true;
  }

  @action 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 { action } from '@ember/object';
import { Drawer } from 'frontile';
import { Button } from 'frontile';

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

  @action 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 { action } from '@ember/object';
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.'
    }
  ];

  @action openDrawer(backdrop) {
    this.selectedBackdrop = backdrop;
    this.isOpen = true;
  }

  @action 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 { action } from '@ember/object';
import { Drawer } from 'frontile';
import { Button } from 'frontile';

export default class DrawerCloseButton extends Component {
  @tracked normalOpen = false;
  @tracked noCloseButtonOpen = false;
  @tracked customCloseOpen = false;

  @action toggleNormal() {
    this.normalOpen = !this.normalOpen;
  }

  @action toggleNoCloseButton() {
    this.noCloseButtonOpen = !this.noCloseButtonOpen;
  }

  @action 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 { action } from '@ember/object';
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;

  @action toggle() {
    this.isOpen = !this.isOpen;
  }

  @action startProcess() {
    this.isProcessing = true;
    this.progress = 0;

    const interval = setInterval(() => {
      this.progress += 10;
      if (this.progress >= 100) {
        clearInterval(interval);
        this.isProcessing = false;
      }
    }, 500);
  }

  @action 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 { action } from '@ember/object';
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 = '';

  @action toggle() {
    this.isOpen = !this.isOpen;
  }

  @action handleSubmit(event) {
    event.preventDefault();
    // Handle form submission
    console.log('Form submitted:', {
      name: this.name,
      email: this.email,
      message: this.message
    });
    this.toggle();
  }

  @action updateName(value) {
    this.name = value;
  }

  @action updateEmail(value) {
    this.email = value;
  }

  @action 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 { action } from '@ember/object';
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;

  @action toggle() {
    this.isOpen = !this.isOpen;
  }

  @action 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' \| 'blur' \| 'transparent'` | - | 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' \| 'body' \| 'footer' \| 'header' \| 'title' \| 'icon' \| 'description' \| 'closeButton' \| 'headerCloseButton' \| 'headerContent' \| 'headerActions' \| '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` | `'bottom' \| 'left' \| 'right' \| 'top'` | `'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 { action } from '@ember/object';
import { Modal } from 'frontile';
import { Button } from 'frontile';

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

  @action 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 { action } from '@ember/object';
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.'
    }
  ];

  @action openModal(size) {
    this.selectedSize = size;
    this.isOpen = true;
  }

  @action 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 { action } from '@ember/object';
import { Modal } from 'frontile';
import { Button } from 'frontile';

export default class ModalPositioning extends Component {
  @tracked standardOpen = false;
  @tracked centeredOpen = false;

  @action toggleStandard() {
    this.standardOpen = !this.standardOpen;
  }

  @action 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 { action } from '@ember/object';
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.'
    }
  ];

  @action openModal(backdrop) {
    this.selectedBackdrop = backdrop;
    this.isOpen = true;
  }

  @action 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 { action } from '@ember/object';
import { Modal, Button, Spinner } from 'frontile';

export default class ConfirmationDialog extends Component {
  @tracked isOpen = false;
  @tracked isDeleting = false;
  @tracked result = '';

  @action openDialog() {
    this.isOpen = true;
    this.result = '';
  }

  @action cancel() {
    this.isOpen = false;
    this.result = 'Action cancelled';
  }

  @action async confirm() {
    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 { action } from '@ember/object';
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' }
  ];

  @action toggle() {
    this.isOpen = !this.isOpen;
  }

  @action updateName(value) {
    this.name = value;
  }

  @action updateEmail(value) {
    this.email = value;
  }

  @action updateCategory(key) {
    this.category = key;
  }

  @action updateMessage(value) {
    this.message = value;
  }

  @action async handleSubmit(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();
  }

  @action 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 { action } from '@ember/object';
import { Modal } from 'frontile';
import { Button } from 'frontile';

export default class ModalCloseButton extends Component {
  @tracked normalOpen = false;
  @tracked noCloseButtonOpen = false;
  @tracked customCloseOpen = false;

  @action toggleNormal() {
    this.normalOpen = !this.normalOpen;
  }

  @action toggleNoCloseButton() {
    this.noCloseButtonOpen = !this.noCloseButtonOpen;
  }

  @action 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 { action } from '@ember/object';
import { Modal } from 'frontile';
import { Button } from 'frontile';

export default class NestedModals extends Component {
  @tracked firstModalOpen = false;
  @tracked secondModalOpen = false;
  @tracked thirdModalOpen = false;

  @action toggleFirst() {
    this.firstModalOpen = !this.firstModalOpen;
  }

  @action toggleSecond() {
    this.secondModalOpen = !this.secondModalOpen;
  }

  @action toggleThird() {
    this.thirdModalOpen = !this.thirdModalOpen;
  }

  @action 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' \| 'blur' \| 'transparent'` | - | 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' \| 'body' \| 'footer' \| 'header' \| 'closeButton'>` | - | 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 { action } from '@ember/object';
import { Overlay } from 'frontile';
import { Button } from 'frontile';

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

  @action 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 { action } from '@ember/object';
import { Overlay } from 'frontile';
import { Button } from 'frontile';

export default class BackdropTypes extends Component {
  @tracked fadedOpen = false;
  @tracked blurredOpen = false;
  @tracked noneOpen = false;

  @action toggleFaded() {
    this.fadedOpen = !this.fadedOpen;
  }

  @action toggleBlurred() {
    this.blurredOpen = !this.blurredOpen;
  }

  @action 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 { action } from '@ember/object';
import { Overlay } from 'frontile';
import { Button } from 'frontile';

export default class RenderInPlace extends Component {
  @tracked portalOpen = false;
  @tracked inPlaceOpen = false;

  @action togglePortal() {
    this.portalOpen = !this.portalOpen;
  }

  @action 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 { action } from '@ember/object';
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;

  @action toggleNormal() {
    this.normalOpen = !this.normalOpen;
  }

  @action toggleNoEscape() {
    this.noEscapeOpen = !this.noEscapeOpen;
  }

  @action toggleNoOutsideClick() {
    this.noOutsideClickOpen = !this.noOutsideClickOpen;
  }

  @action toggleConfirmClose() {
    this.confirmCloseOpen = !this.confirmCloseOpen;
  }

  @action 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 { action } from '@ember/object';
import { Overlay } from 'frontile';
import { Button } from 'frontile';
import { Input } from 'frontile';

export default class FocusManagement extends Component {
  @tracked focusTrapOpen = false;
  @tracked noFocusTrapOpen = false;

  @action toggleFocusTrap() {
    this.focusTrapOpen = !this.focusTrapOpen;
  }

  @action 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 { action } from '@ember/object';
import { Overlay } from 'frontile';
import { Button } from 'frontile';

export default class AnimationsAndTransitions extends Component {
  @tracked fastOpen = false;
  @tracked slowOpen = false;
  @tracked noAnimationOpen = false;

  @action toggleFast() {
    this.fastOpen = !this.fastOpen;
  }

  @action toggleSlow() {
    this.slowOpen = !this.slowOpen;
  }

  @action 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 { action } from '@ember/object';
import { Overlay } from 'frontile';
import { Button } from 'frontile';

export default class OverlaysThatStartOpen extends Component {
  @tracked showAnimated = false;
  @tracked showImmediate = false;

  @action mountAnimated() {
    this.showAnimated = true;
  }

  @action mountImmediate() {
    this.showImmediate = true;
  }

  @action closeAnimated() {
    this.showAnimated = false;
  }

  @action 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 { action } from '@ember/object';
import { Overlay } from 'frontile';
import { Button } from 'frontile';

export default class OverlayElementClick extends Component {
  @tracked defaultOpen = false;
  @tracked disabledOpen = false;

  @action toggleDefault() {
    this.defaultOpen = !this.defaultOpen;
  }

  @action 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' \| 'blur' \| 'transparent'` | - | 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` | `{ padding?: Padding; mainAxis?: boolean; crossAxis?: boolean \| 'alignment'; fallbackPlacements?: Placement[]; fallbackStrategy?: 'bestFit' \| 'initialPlacement'; fallbackAxisSideDirection?: 'start' \| ... 1 more ... \| 'none'; ... 4 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: 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` | `'bottom' \| 'left' \| 'right' \| 'top' \| 'top-start' \| 'top-end' \| 'right-start' \| 'right-end' \| 'bottom-start' \| 'bottom-end' \| 'left-start' \| 'left-end'` | `'bottom-start'` | Placement of the menu when open |
| `shiftOptions` | `{ padding?: Padding; mainAxis?: boolean; crossAxis?: boolean; rootBoundary?: RootBoundary; elementContext?: ElementContext; altBoundary?: boolean; 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' \| 'blur' \| 'transparent'` | - | 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' \| 'trigger' \| 'xl' \| '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: 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` | `{ padding?: Padding; mainAxis?: boolean; crossAxis?: boolean \| 'alignment'; fallbackPlacements?: Placement[]; fallbackStrategy?: 'bestFit' \| 'initialPlacement'; fallbackAxisSideDirection?: 'start' \| ... 1 more ... \| 'none'; ... 4 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: 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` | `'bottom' \| 'left' \| 'right' \| 'top' \| 'top-start' \| 'top-end' \| 'right-start' \| 'right-end' \| 'bottom-start' \| 'bottom-end' \| '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` | `{ padding?: Padding; mainAxis?: boolean; crossAxis?: boolean; rootBoundary?: RootBoundary; elementContext?: ElementContext; altBoundary?: boolean; 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<'base' \| 'icon'>` | - | 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' \| 'summary' \| 'item' \| 'list' \| 'page' \| 'prev' \| 'next' \| 'ellipsis'>` | - | 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<'base' \| 'title' \| 'trigger' \| 'content' \| 'startContent' \| 'item' \| '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; }]` | - |  |

---

# Accessibility overview

Source: /docs/accessibility/index.md

# Accessibility

Frontile's components handle a substantial amount of accessibility work for you: focus
management, keyboard navigation, and the ARIA attributes each component's role requires are
built in and covered by the test suite. This section documents the mechanisms that are
shared across components. For the exact ARIA attributes and keyboard bindings a specific
component uses, see that component's own **Accessibility** section — for example
[Table's](../../packages/frontile/src/components/collections/table.md#accessibility),
[Modal's](../../packages/frontile/src/components/overlays/modal.md#accessibility), or
[Dropdown's](../../packages/frontile/src/components/collections/dropdown.md#accessibility).

## What Frontile handles vs. what you own

Frontile owns:

- Correct ARIA roles, states, and relationships for each component (e.g. `aria-modal`,
  `aria-invalid`).
- Keyboard navigation within a component — arrow keys, Home/End, typeahead, and Tab
  behavior for lists, menus, tables, and grouped controls.
- Focus behavior around opening and closing overlays — where focus goes when a modal opens,
  and where it returns when it closes.
- The `:focus-visible` behavior that shows a focus ring for keyboard users without showing
  one for mouse users.

You own:

- An accessible name for anything Frontile can't infer one for — e.g. passing `aria-label`
  or `aria-labelledby` to a `Modal`, or wrapping icon-only buttons in `VisuallyHidden` text.
- The meaning of your own content — alt text on images you render inside a component,
  correct heading levels in the content you put inside a `Modal.Header`.
- Testing your specific application with a screen reader. Frontile's ARIA wiring gives
  assistive technology the right information, but only you know whether your page's content
  makes sense when read in order.

## Where to look for component-specific detail

Every component's `.md` file has its own `## Accessibility` section documenting the exact
ARIA attributes it sets and the exact keys it responds to. This section (`docs/accessibility/`)
covers the *shared* mechanisms behind those components — read both when you need the full
picture for a specific component.

## Testing posture

Frontile's integration test suite asserts ARIA attributes and keyboard behavior across the
component set — concentrated in `roving-focus-test.gts`, `listbox-test.gts`, `table-test.gts`,
`command-test.gts`, `dropdown-test.gts`, `select-test.gts`, `autocomplete-test.gts`, and
`segmented-control-test.gts`, plus the forms and overlays suites. That gives strong regression
coverage for the behavior these docs describe, but it is not the same as a formal accessibility
audit or a tested matrix of screen readers and browsers. If you're shipping something
compliance-critical, test it yourself with a real screen reader (VoiceOver, NVDA, or JAWS) —
don't rely on Frontile's test suite as a substitute.

---

# Focus management

Source: /docs/accessibility/focus-management.md

# Focus management

Focus indicators (typically an outline around a focused element) help keyboard users navigate and identify which element currently has focus, allowing users to interact with elements by pressing `Enter` instead of using a mouse.

They're also unnecessary when using a mouse, so Frontile only shows them for keyboard input.

## How it works

Frontile includes a [library](https://github.com/WICG/focus-visible) based on the proposed CSS `:focus-visible` pseudo-selector. It adds a `focus-visible` class to focused elements **only when keyboard navigation is detected** (`Tab`, `Shift + Tab`, or arrow keys).

When the mouse is used to focus an element, the class is not added—except for text inputs and textareas, where focus indicators are always helpful.

## Example

Try focusing these elements with both keyboard (`Tab` key) and mouse to see the difference:

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

<template>
  <div class='space-y-4'>
    <Input placeholder='Focus me with Tab or mouse' />

    <Button @color='primary'>
      Focus me with Tab or mouse
    </Button>
  </div>
</template>
```

Notice how the keyboard focus is clearly visible with `Tab`, but clicking with the mouse doesn't show the focus ring on the button.

## Focus lifecycle in overlays

Modal, Drawer, Popover, and Dropdown are all built on the shared `Overlay` primitive, which
manages focus around opening and closing:

- **On open**, focus moves into the overlay's content. By default the focus trap is active,
  and moving focus into the content is handled by the focus-trap library itself as part of
  activating the trap. If `@disableFocusTrap={{true}}` is passed, the trap doesn't run at
  all — in that case Overlay focuses the content itself instead, unless
  `@preventAutoFocus={{true}}` is also passed. (`@preventAutoFocus` only has an effect when
  the trap is disabled; it does nothing when the trap is active.)
- **While open**, a focus trap keeps Tab and Shift+Tab cycling within the overlay's content,
  so keyboard users can't tab out to the page behind it. This is configurable via
  `@focusTrapOptions` and can be turned off entirely with `@disableFocusTrap={{true}}`.
- **On close**, focus returns to whatever element had focus before the overlay opened —
  typically the button that triggered it — unless `@preventFocusRestore={{true}}` is passed.
- On `Modal` and `Drawer`, `aria-modal="true"` tracks whether the trap is actually active, so
  assistive technology isn't told the page is modal when the trap has been disabled.

## Used by

- [Overlay](../../packages/frontile/src/components/overlays/overlay.md)
- [Modal](../../packages/frontile/src/components/overlays/modal.md)
- [Drawer](../../packages/frontile/src/components/overlays/drawer.md)
- [Popover](../../packages/frontile/src/components/overlays/popover.md)
- [Dropdown](../../packages/frontile/src/components/collections/dropdown.md)

---

# Keyboard navigation

Source: /docs/accessibility/keyboard-navigation.md

# Keyboard navigation

Several components — lists, menus, tables, and grouped controls — share the same keyboard
model rather than each inventing their own: the group is a **single Tab stop**, and once
focus is inside it, arrow keys move between items. This is the model the WAI-ARIA authoring
practices call for grids, listboxes, menus, and radio groups, and it's what makes Tab predictable
regardless of how many items a list contains.

## The shared model

- **Tab** enters or leaves the group in one press — it never steps through every item.
- **Arrow keys** move focus between items. Horizontal groups (e.g. `SegmentedControl`) use
  Left/Right; vertical groups (e.g. `Table`, `Listbox`) use Up/Down.
- **Home** / **End** jump to the first / last enabled item, in components built on
  `rovingFocus`. `Listbox` implements the same Home/End behavior itself via a separate,
  hand-rolled key handler rather than through `ListManager`, and additionally treats
  PageUp/PageDown the same as Home/End.
- **Typeahead** — typing a letter jumps to the next item whose text starts with it, in
  components that support text search (Listbox, Select, Autocomplete, Command).
- **Disabled items are skipped** — navigation is computed from the enabled items only, so
  wrapping and Home/End always land on something usable.
- In a right-to-left layout, `rovingFocus`-based horizontal groups swap Left/Right so "next"
  and "previous" still match the direction the user reads in. Vertical navigation is
  unaffected.

## Two activation styles

How arrow-key navigation relates to selection differs by component, matching how each one is
actually used:

- **Automatic activation** — arrowing to an item selects it immediately, the way a native
  radio group works. `SegmentedControl` uses this.
- **Manual activation** — arrowing only moves focus; selecting requires a separate action
  (`Enter`/`Space`, or a click). This is the right model when moving focus is cheap but
  activating is not — `Table`'s row navigation uses this, since arrowing across rows
  shouldn't fire a selection on every keystroke.

## Two primitives, same shape

Frontile has two building blocks that implement this model, at different levels of
functionality:

- **`rovingFocus`** (`packages/frontile/src/utils/roving-focus.ts`) is the minimal version:
  it owns only keyboard handling and `tabindex` bookkeeping, reading selected/disabled state
  directly off each element's attributes (`data-selected`, `aria-checked`, `aria-selected`,
  `:disabled`, `aria-disabled`). It renders nothing and knows nothing about selection state
  itself. `SegmentedControl` and `Table` use it directly — see the
  [`rovingFocus` reference](../../packages/frontile/src/utils/roving-focus.md) for the full
  API.
- **`ListManager`** (`packages/frontile/src/utils/listManager.ts`) is the fuller-featured
  engine behind `Listbox`, `Dropdown`, `Select`, `Autocomplete`, `NativeSelect`, and `Command`.
  It additionally owns selection state (single/multiple/none), typeahead search, and
  auto-activation of the first or previously-selected item when a list opens.

You won't normally interact with either primitive directly unless you're building a new
list-like component — as a consumer, what matters is that the keyboard behavior above is
consistent everywhere you see it.

## Used by

- [Table](../../packages/frontile/src/components/collections/table.md)
- [Listbox](../../packages/frontile/src/components/collections/listbox.md)
- [Dropdown](../../packages/frontile/src/components/collections/dropdown.md)
- [Select](../../packages/frontile/src/components/forms/select.md)
- [Autocomplete](../../packages/frontile/src/components/forms/autocomplete.md)
- [Command](../../packages/frontile/src/components/collections/command.md)
- [SegmentedControl](../../packages/frontile/src/components/buttons/segmented-control.md)
- [rovingFocus reference](../../packages/frontile/src/utils/roving-focus.md)

---

# Screen reader support

Source: /docs/accessibility/screen-reader-support.md

# Screen reader support

Some information matters to assistive technology even when it's invisible on screen, or when
it changes without the user taking an action that would naturally draw their attention to it.
This page covers the three places Frontile handles that: live regions, labeling, and the
combobox pattern.

## Live regions

When content changes without a user interaction that would move focus there — a toast
notification appearing, or a search result count updating — screen readers need to be told
explicitly, because nothing about the DOM change otherwise gets announced.

Frontile uses live regions for this in three places today:

- `NotificationsContainer` wraps its toasts in an `aria-live="polite"` region, so a
  notification is announced when it appears without moving focus away from what the user was
  doing.
- `Command`'s result list uses `aria-live="polite"` to announce its result count as the user
  types, so a screen reader user knows how many matches exist without needing to navigate into
  the list.
- `FormControl` mounts an always-present, visually hidden `aria-live="assertive"` region for a
  field's error text, empty until an error occurs. It's mounted unconditionally (rather than
  only once the field becomes invalid) because a live region that appears at the same moment
  as its content is not reliably announced — assistive technology needs to already be
  observing the region before the message lands in it. This is what makes the error text
  described in the Labeling section below actually get announced the moment it appears,
  rather than only being discoverable via `aria-describedby` if the user happens to
  re-navigate to the field.

There's no reusable "announcer" utility in Frontile yet — each of these is a
component-specific `aria-live` region. If you need the same pattern in your own application
code (e.g. announcing that a background save succeeded), you'll need to add your own
`aria-live` region rather than reaching for something Frontile exports.

## Labeling

Two mechanisms cover the common labeling needs:

- **`VisuallyHidden`** hides text visually while keeping it in the accessibility tree — the
  standard way to give an icon-only button a real name. See the
  [`VisuallyHidden` docs](../../packages/frontile/src/components/utilities/visually-hidden.md)
  for examples.
- **`FormControl` and `Field`** automatically wire `aria-describedby` to point at a field's
  description and error text, and set `aria-invalid` when a field is in an error state. This
  happens for you when you use `c.describedBy(...)` as the form components already do — you
  should let it do this rather than wiring `aria-describedby` by hand, since Frontile also
  handles the case where a field has both a description and an error present at once.

## The combobox pattern

`Command` and `Autocomplete` implement the ARIA combobox pattern: the text input carries
`role="combobox"`, `aria-autocomplete="list"`, `aria-expanded` (reflecting whether there are
results to show, not simply whether the list is open), `aria-controls` (pointing at the
list), and `aria-activedescendant` (pointing at
whichever item is currently highlighted, without moving DOM focus off the input). Together
these let a screen reader track "which item is highlighted in the open list" purely from
attributes on the input the user is actually typing into.

## Used by

- [VisuallyHidden](../../packages/frontile/src/components/utilities/visually-hidden.md)
- [FormControl](../../packages/frontile/src/components/forms/form-control.md)
- [Field](../../packages/frontile/src/components/forms/field.md)
- [Command](../../packages/frontile/src/components/collections/command.md)
- [Autocomplete](../../packages/frontile/src/components/forms/autocomplete.md)
- [Notifications](../../packages/frontile/docs/notifications-usage.md)

---

# Color contrast & motion

Source: /docs/accessibility/color-and-motion.md

# Color contrast & motion

## Contrast

Frontile's semantic color system generates a matching `on-{category}-{level}` contrast color
for every background — e.g. `text-on-primary-firm` is the readable text color for a
`bg-primary-firm` background. These aren't hand-picked; they're computed by choosing whichever
of black or white has the higher WCAG contrast ratio against the paired background, in both
light and dark mode, and regenerated whenever the underlying color changes. See
[Colors](../../docs/theming/design-tokens/colors.md) in the theming docs for the full token
reference and how to override them in your own theme configuration.

Practically, this means: when you use a semantic background utility, use its matching `on-*`
text utility rather than picking a text color yourself, and you get the better of black or
white against that background without having to check it yourself.

## Motion

Frontile handles `prefers-reduced-motion` in several places, via `motion-reduce:` Tailwind
utilities and `@media (prefers-reduced-motion: reduce)` blocks built into `@frontile/theme`:

- **`Command`'s palette** animation drops its scale/rise transform under reduced motion while
  keeping the opacity fade, so the palette still reads as appearing or disappearing without
  any travel. (`Modal`, `Drawer`, and `Popover` use their own transform-based transitions —
  zoom, slide, and scale respectively — which don't currently have the same reduced-motion
  handling; `Dropdown`'s default transition is a plain opacity fade with no transform to begin
  with.)
- **Notifications** — `NotificationCard` drops its transform-based slide/scale choreography
  entirely and falls back to a faster opacity-only transition; `NotificationsContainer`'s
  own height transition (used when the toast stack expands or collapses) is removed
  altogether.
- **`SegmentedControl`** removes the transition on its sliding selection indicator.
- **`Table`** disables the entrance animation on skeleton loading rows.
- **`InputOTP`** stops its caret from blinking.

This is applied per-component in the theme rather than being a systematic, enforced guarantee
across the library — there's no mechanism that would catch a future animation added without a
`motion-reduce:` variant. And it only covers what Frontile itself renders: any custom
animation you write in your own application code (including inside a component's yielded
content) is your own responsibility to make reduced-motion-aware.

---

# Upgrading to v0.18

Source: /docs/migrations/v0-18/index.md

# Upgrading to v0.18

Frontile v0.18 is a major release with several breaking changes to theming, colors, DOM anatomy, and component APIs. This guide gives an overview of all of them and links to a detailed migration guide for each.

## What breaks, and how loudly

Two of these changes stop your app from working. The rest are cleanup, and one of
them is optional for the whole 0.18 line.

| Change                                                                    | If you skip it                                                               | Fails how?                                                      |
| ------------------------------------------------------------------------- | ---------------------------------------------------------------------------- | --------------------------------------------------------------- |
| Missing `@import "@frontile/theme"`                                       | No Frontile styles at all                                                    | Loudly — the app is visibly unstyled                            |
| Numbered color classes (`bg-primary-500`)                                 | Those elements render unstyled                                               | **Silently**                                                    |
| `bg-background` → `bg-surface-canvas`                                     | Those elements render unstyled                                               | **Silently**                                                    |
| `--frontile-*` variable references                                        | The declaration is dropped                                                   | **Silently**                                                    |
| Nested `LayoutTheme` config                                               | Build or type error                                                          | Loudly, and only if you customize the theme                     |
| `@frontile/*` package imports                                             | Nothing — they still work in 0.18.x                                          | Deprecation warning only                                        |
| `@frontile/forms-legacy` / `@frontile/changeset-form`                     | Nothing — they still work in 0.18.x, but are removed in 0.19.0               | Deprecation warning only                                        |
| Derived border-radius scale                                               | Slightly rounder corners on menus and small marks                            | Visual only — nothing to fix                                    |
| Multi-select renders chips                                                | Multi-selects look different — selections become removable chips             | Visual only — nothing to fix                                    |
| Filtered lists are ranked                                                 | `Autocomplete`/`Select` list the closest match first instead of source order | Visual only — nothing to fix                                    |
| `text-body-pico`/`-nano`/`-micro`                                         | Those elements render unstyled                                               | **Silently**                                                    |
| Body text-scale font sizes corrected                                      | Body text (`xs` through `xl`) renders larger than intended                   | Visual only — nothing to fix                                    |
| `data-fr-*` / mismatched `data-component` / most `data-test-id` selectors | Those selectors stop matching                                                | **Silently**, if you select Frontile-rendered elements yourself |

**The silent ones are the reason to take this in order.** A class Tailwind can't
resolve produces no error, no warning, and no CSS — the element just renders
without the style you asked for. We hit this in Frontile's own documentation
during the 0.18 work: thirteen demos were shipping with `bg-success-50` and
`bg-warning-50`, rendering with no background at all, and nobody noticed until a
linter went looking. Budget time for looking at the result, not just for the
find-and-replace.

## Migration order

### 1. Theme configuration — do this first

Nothing else is verifiable until the theme loads. Add the CSS import, and update
your config shape if you customize it.

**Impact:** required. **Time:** 15–30 minutes.

- Add `@import "@frontile/theme"` to your `app/styles/app.css`
- `LayoutTheme` moved from a flat to a nested structure (`hoverOpacity` becomes
  `opacity: { hover }`)
- CSS variables lost the `--frontile-` prefix; colors gained `--color-`

**See:** [Theme Configuration](./theme-configuration.md)

### 2. Colors and surfaces — the bulk of the work

One pass over your classes and custom CSS. Everything in this step fails
silently, so verify visually as you go rather than at the end.

**Impact:** required, and touches every colored element. **Time:** an hour or two
for a small app, a day or more for a large one.

- Numbered scales (`50`, `100`, … `950`) become named levels (`subtle`, `muted`,
  `soft`, `mild`, DEFAULT, `firm`, `strong`, `bolder`)
- `default-*` becomes `neutral-*`
- `bg-background` becomes `bg-surface-canvas`
- `{color}-foreground` and `contrast-1`/`contrast-2` become `on-{color}-{level}`
- `text-foreground` is gone
- `theme-inverse` flips every semantic token in a region, for panels that should read as the opposite theme

Colors also moved from HSL to OKLCH. That part is automatic — you may notice
small perceptual differences, but there is nothing to change.

**See:** [Semantic Colors](./semantic-colors.md)

### 3. Package consolidation — optional, any time before 0.19

Seven `@frontile/*` component packages became the single `frontile` package. The
old packages still re-export everything and only log a deprecation warning, so
**your imports keep working for all of 0.18.x.**

Leave this until the app builds and looks right. It rewrites every Frontile
import in your codebase, and doing that first buries the changes above in a diff
you can't read — which matters precisely because those changes fail silently.

**Impact:** none until 0.19. **Time:** 10–30 minutes, mostly automated.

**See:** [Package Consolidation](./package-consolidation.md)

### Forms Legacy & Changeset Form — optional, any time before 0.19

`@frontile/forms-legacy` and `@frontile/changeset-form` are deprecated and,
unlike the wrapper packages above, are being removed entirely in 0.19.0, not
just re-exported. If you depend on either, migrate to the modern `frontile`
forms (Form + Field pattern with Valibot, Zod, or a custom validator).

**Impact:** none until 0.19, unless you already depend on one of these
packages. **Time:** varies with form count and validation complexity — see
each guide's migration checklist.

**See:** [Forms Legacy Migration Guide](./forms-legacy.md), [Changeset Form Migration Guide](./changeset-form.md)

### Filtered lists are ranked by relevance — visual only

`Autocomplete` and filterable `Select` used to filter with a case-insensitive
"contains" check and render whatever survived **in the order you passed it**.
They now score each option and list the closest match first, and additionally
match acronyms (`nz` finds "New Zealand").

Nothing that matched before stops matching, so there is nothing to fix unless
you pass your own `@filter` — which now also accepts a score:

```ts
filter?: (itemValue: string, inputValue: string) => boolean | number;
```

**See:** [Filter Ranking](./filter-ranking.md)

### 4. Multi-select renders chips — visual only

`Select` with `@selectionMode="multiple"` used to show its selections as a
comma-joined string inside the trigger. It now renders each selection as a
removable [Chip](https://frontile.dev/docs/components/buttons/chip), so users
can drop one selection without reopening the dropdown. The control grows taller as chips
wrap, and a chips field is deliberately the same height as a same-size single
select (46px at `md`).

Nothing breaks, but the field is taller and looks different. If a layout
depends on the old fixed-height appearance, opt back out per-select:

```gts
<Select @selectionMode='multiple' @selectedItemsDisplay='text' />
```

Chips inherit the Select's `@intent` and default to the `faded` appearance;
`@chip={{hash appearance='outlined' size='md'}}` tunes appearance, intent,
size, radius and `withDot`. `@allowEmpty` defaults to `false`, so the final
selection's chip renders with no close button; `@isClearable` clears
everything and ignores `@allowEmpty`. Chip close buttons are deliberately not
in the tab order — the combobox is the single tab stop, and `Backspace` on
the field removes the last chip in both filterable and non-filterable modes.
See the [Select docs](https://frontile.dev/docs/components/forms/select#multiple-selection)
for the full section.

**Impact:** visual only. **Time:** none required; a few minutes if you want to
opt out.

### 5. DOM anatomy attributes — required only if you select internals

Every component now carries a stable `data-component`/`data-part` DOM
anatomy. The old `data-fr-*` attributes are gone, several mismatched
`data-component` values were corrected, and most `data-test-id` attributes
that existed only as anatomy selectors were replaced. This only affects you
if your own CSS, `querySelector` calls, or tests select Frontile-rendered
elements directly — the public component API (`@classes`, yielded blocks,
etc.) is unchanged.

**Impact:** required only if you select internals directly (silent — the
selector just stops matching); otherwise none. **Time:** a few minutes to a
couple hours, depending on how many selectors your app has.

**See:** [DOM Anatomy Attributes Migration](./anatomy-attributes.md),
[Customizing Component Styles](../../theming/component-styles.md) for the
ongoing contract.

### 6. Component API naming: `@appearance` → `@variant`, `@intent` → `@color`/`@status` — required only if you set them

Both styling axes are renamed. `@appearance` becomes `@variant` with a shared
value vocabulary (`solid`, `soft`, `subtle`, `outline`, `ghost`, `plain`), and
`@intent` becomes `@color` — or `@status` on `Alert`, `NotificationCard` and
`FormFeedback`, the three where the value also selects an icon, an ARIA role, or
whether a message is announced assertively. `default` becomes `neutral`
throughout; on Alert and NotificationCard, `info` folds into `primary`.

On the components whose API shipped in v0.17.1, the old props still work through
0.18.x and log a deprecation warning; they are removed in v0.19.0. Components
added during the 0.18 pre-release cycle are renamed outright with no warning —
if you tracked a `0.18.0-alpha.*`/`beta.*` build, read that guide's second
section.

**Impact:** required only if you pass `@appearance` or `@intent` today;
otherwise none. **Time:** a few minutes to an hour, depending on how many call
sites you have.

**See:** [Component API Naming Migration](./component-api-naming.md)

### 7. Body typography scale corrected

The `--text-body-*` tokens were mapped to the wrong steps of the modular scale,
so `xs` through `xl` rendered larger than the design spec (e.g. `md` shipped at
20.74px instead of 16px). These now match spec, and the scale gained `4xs`,
`5xs`, `2xl`, and `3xl` sizes to fill it out.

The non-standard `text-body-pico`, `text-body-nano`, and `text-body-micro`
tokens are gone — the body scale now uses the same `5xs`…`3xl` naming as every
other text-style category. Replace them with the equivalent standard size,
which renders at the same pixel value:

| Removed           | Use instead     |
| ----------------- | --------------- |
| `text-body-pico`  | `text-body-4xs` |
| `text-body-nano`  | `text-body-3xs` |
| `text-body-micro` | `text-body-2xs` |

**Impact:** required only if you use `text-body-pico`/`-nano`/`-micro`
directly (silent — the class stops resolving to any style); otherwise visual
only, from the corrected sizes. **Time:** a few minutes; search your codebase
for `text-body-pico`, `text-body-nano`, and `text-body-micro`.

**See:** [Typography](../../theming/design-tokens/typography.md)

## Checklist

- [ ] `@import "@frontile/theme"` added to `app.css`
- [ ] `LayoutTheme` config nested, if you customize it
- [ ] `--frontile-*` variable references renamed (colors take `--color-`)
- [ ] Numbered color classes replaced with named levels
- [ ] `default-*` renamed to `neutral-*`
- [ ] `bg-background` replaced with `bg-surface-canvas`
- [ ] `{color}-foreground` / `contrast-*` replaced with `on-{color}-{level}`
- [ ] **Looked at the running app**, not just the diff
- [ ] Imports moved to `frontile` (optional until 0.19)
- [ ] Migrated off `@frontile/forms-legacy` / `@frontile/changeset-form`, if used (required before 0.19)
- [ ] Looked at any multi-selects — they now render chips and are taller
- [ ] Replaced `text-body-pico`/`-nano`/`-micro` with `text-body-4xs`/`-3xs`/`-2xs`
- [ ] Replaced any `data-fr-*`, mismatched `data-component`, or retired
      `data-test-id` selectors with the new `data-component`/`data-part`
      attributes (see [DOM Anatomy Attributes Migration](./anatomy-attributes.md))
- [ ] `@appearance` replaced with `@variant`, and `@intent` with `@color` —
      or `@status` on Alert, NotificationCard and FormFeedback — with
      `default` replaced by `neutral` (see
      [Component API Naming Migration](./component-api-naming.md))

## New projects

Starting fresh on v0.18 needs no migration. Follow
[Getting Started](../../get-started/index.md).

## Need help?

- The individual guides linked above
- The [documentation](../../get-started/index.md) for current usage examples
- Search or open an issue on [GitHub](https://github.com/josemarluedke/frontile)

---

# Semantic Colors Migration

Source: /docs/migrations/v0-18/semantic-colors.md

# Semantic Colors v2 Migration Guide

This guide helps you migrate from the old numbered color system to the new semantic color levels in Frontile v0.18+.

## Overview

The semantic color system has been redesigned to use named levels instead of numbered scales. Names describe emphasis rank (subtle, soft, firm, strong) rather than a numbered step, contrast colors are defined explicitly instead of inferred, and levels are chosen for how they read in both light and dark mode.

## Breaking Changes

### Color Categories Renamed

| Old Name    | New Name    | Notes                                                    |
| ----------- | ----------- | -------------------------------------------------------- |
| `default-*` | `neutral-*` | Renamed to better indicate non-semantic UI elements      |

### Inverted Surfaces

There is no `inverse` color category. Content on an inverted surface is handled
one of two ways.

For a single element sitting on a filled background, use the automatic contrast
color for that background level:

```gts
<div class="bg-neutral-strong text-on-neutral-strong">
  Content with guaranteed contrast
</div>
```

For a whole region that should read as the opposite theme — a dark panel in light
mode, or a light one in dark mode — add the `theme-inverse` class. Every semantic
token inside it resolves to its other-theme value, so ordinary classes keep
working:

```gts
<div class="theme-inverse bg-surface-canvas p-6">
  <h3 class="text-neutral-bolder">Reads as dark in light mode</h3>
  <p class="text-neutral-strong">And as light in dark mode.</p>
</div>
```

`theme-inverse` is a selector the theme defines, not a color. It is unrelated to
the `inverse` category that appeared briefly during the 0.18 alpha cycle and was
removed before release.

### Surface Roles Simplified

The surface system (introduced during the v0.18 alpha cycle) has been simplified before its first stable release:

| Removed                       | Replacement          | Notes                                                                                   |
| ------------------------------ | --------------------- | ---------------------------------------------------------------------------------------- |
| `surface-solid-0` … `surface-solid-11` | *(removed)*    | The 12-step scale is gone. Use a surface role (`app`, `canvas`, `card`, `modal`, `input`) instead |
| `text-surface-solid-*`         | `text-neutral-*` or `text-on-surface-modal` | Use the neutral text scale for body copy, or the auto-generated on-color for content on `surface-modal` |
| `surface-popover`              | `surface-modal`       | Popovers, dropdowns, modals, and drawers now share one "highest elevation" surface        |
| `surface-overlay-content`      | `surface-modal`       | Same merge as above — this was already identical in value to `surface-popover`            |
| `surface-panel`                | *(removed)*           | Had no real consumer; use `surface-card` for elevated sidebar/panel containers            |
| `surface-inset`                | *(removed)*           | Had no real consumer; use `surface-overlay-subtle`/`soft` for recessed translucent wells   |
| `surface-overlay-inverse-*`    | `surface-overlay-strong` (for backdrops) | Had no real consumer. If you need a heavy backdrop tint, use `strong`; for a normal darken/lighten step, use `subtle`/`soft`/`mild`/`firm` |
| *(new)* `surface-input`        | —                     | Dedicated surface for text inputs, checkboxes, and radios (previously `surface-solid-0`)   |

`surface-card` also changed value: it's now translucent (`white @ 90%` in light mode) instead of fully opaque, and resolves to `base-800` in dark mode instead of `base-700`.

```gts
// Before
<div class="bg-surface-popover rounded-md shadow-lg">Menu</div>
<div class="bg-surface-overlay-content rounded-lg">Modal</div>
<input class="bg-surface-solid-0" />

// After
<div class="bg-surface-modal rounded-md shadow-lg">Menu</div>
<div class="bg-surface-modal rounded-lg">Modal</div>
<input class="bg-surface-input" />
```

See the [Surfaces](../../theming/design-tokens/surfaces.md) guide for the full, current token set.

### Surface Overlay Levels Renamed

The translucent overlay levels were renamed to line up with the named levels used
by every other color category (`subtle` → `soft` → `mild` → `firm` → `strong`).
The values did not change — only the names:

| Old                        | New                      | Notes                                                          |
| -------------------------- | ------------------------ | -------------------------------------------------------------- |
| `surface-overlay-medium`   | `surface-overlay-mild`   | Same value, renamed to match the shared level names             |
| `surface-overlay-strong`   | `surface-overlay-firm`   | Same value, shifted down one name                               |
| `surface-overlay-scrim`    | `surface-overlay-strong` | The heavy modal/drawer backdrop is now just the top level       |

```gts
// Before
<div class="bg-surface-overlay-medium" />
<div class="border-surface-overlay-strong" />
<div class="fixed inset-0 bg-surface-overlay-scrim" />

// After
<div class="bg-surface-overlay-mild" />
<div class="border-surface-overlay-firm" />
<div class="fixed inset-0 bg-surface-overlay-strong" />
```


### New: Surface Lift

`surface-lift-*` is a new translucent family alongside `surface-overlay-*`, with
the same five levels. Overlay darkens in light mode and lightens in dark mode,
pressing an element into the page; lift does the opposite, so the element floats
above what it covers.

```gts
// Recedes — hover states, section fills
<div class="bg-surface-overlay-soft" />

// Floats — frosted panels, sticky headers, captions over media
<header class="bg-surface-lift-firm backdrop-blur-md" />
```

Nothing is deprecated by this: existing `surface-overlay-*` usage is unaffected.
See the [Surfaces](../../theming/design-tokens/surfaces.md) guide for the level
table and usage guidance.

### Color Scale Changed

The numbered scale (50, 100, 200, ..., 950) has been replaced with named levels:

| Old Pattern          | New Pattern           | Description                               |
| -------------------- | --------------------- | ----------------------------------------- |
| `{color}-{number}`   | `{color}-{level}`     | Named emphasis levels                     |
| `{color}-foreground` | `on-{color}-{level}`  | Automatic contrasting colors (black/white) |

## Color Level Mapping

### Understanding the New Levels

Each semantic color is organized into two bands that share one emphasis
vocabulary but are consumed by different CSS properties. Names describe emphasis
**rank**, never brightness — a level may be dark in light mode and light in dark
mode, since interaction direction inverts between the two schemes.

**Surface band** — fills for backgrounds and decorative borders (low → high emphasis):

- **`subtle`** — Faintest tint, for hairline backgrounds and tonal rests
- **`muted`** — Light tint, for hover on tonal surfaces
- **`soft`** — Soft fill, the hover step for solid fills
- **`DEFAULT`** — Resting fill, the bare `bg-{color}` token
- **`firm`** — Most emphatic fill, for pressed/active backgrounds

**Ink band** — legible foregrounds for text and outlined borders (low → high emphasis):

- **`strong`** — Default legible foreground, for body text and outlined-control text/borders
- **`bolder`** — Highest-emphasis foreground, for headings and hover/active text

**`on-{color}-{level}`** — Automatic contrasting color (black or white)
calculated for optimal WCAG contrast on the specified background level.

### Migration Mapping Table

#### Neutral (formerly Default)

| Old Class                 | New Class                                      | Context                    |
| ------------------------- | ---------------------------------------------- | -------------------------- |
| `bg-default-50`           | `bg-neutral-subtle`                            | Very light backgrounds     |
| `bg-default-100`          | `bg-neutral-subtle`                            | Light backgrounds, borders |
| `bg-default-200`          | `bg-neutral-subtle`                            | Light surfaces             |
| `bg-default-300`          | `bg-neutral-soft`                              | Moderate backgrounds       |
| `bg-default-400`          | `bg-neutral-soft`                              | Borders, dividers          |
| `bg-default-500`          | `bg-neutral-soft` or `bg-neutral`       | Medium emphasis            |
| `bg-default-600`          | `bg-neutral`                            | Standard emphasis          |
| `bg-default-700`          | `bg-neutral` or `bg-neutral-strong`     | Strong emphasis            |
| `bg-default-800`          | `bg-neutral-strong`                            | Maximum emphasis, buttons  |
| `bg-default-900`          | `bg-neutral-strong`                            | Darkest backgrounds        |
| `bg-default-950`          | `bg-neutral-strong`                            | Maximum contrast           |
| `text-default`            | `text-neutral-strong` or `text-neutral-bolder` | Body text                  |
| `text-default-foreground` | `text-on-neutral`                       | Contrasting text on bg     |
| `border-default`          | `border-neutral-soft`                          | Standard borders           |

#### Primary

| Old Class                 | New Class                                  | Context                |
| ------------------------- | ------------------------------------------ | ---------------------- |
| `bg-primary-500`          | `bg-primary-soft` or `bg-primary`   | Hover states           |
| `bg-primary-600`          | `bg-primary`                        | Default buttons        |
| `bg-primary-700`          | `bg-primary` or `bg-primary-strong` | Strong emphasis        |
| `bg-primary-800`          | `bg-primary-strong`                        | Active/pressed states  |
| `text-primary-foreground` | `text-on-primary`                   | Contrasting text on bg |
| `ring-primary-500`        | `ring-primary-soft`                        | Focus rings            |

#### Success

| Old Class                 | New Class                                  | Context                  |
| ------------------------- | ------------------------------------------ | ------------------------ |
| `bg-success-100`          | `bg-success-subtle`                        | Alert backgrounds        |
| `bg-success-500`          | `bg-success-soft` or `bg-success`   | Moderate emphasis        |
| `bg-success-600`          | `bg-success` or `bg-success-strong` | Buttons, hover           |
| `bg-success-800`          | `bg-success-strong`                        | Active states            |
| `text-success-foreground` | `text-on-success`                   | Contrasting text on bg   |
| `ring-success-500`        | `ring-success-soft`                        | Focus rings              |

#### Warning

| Old Class                 | New Class                                  | Context                  |
| ------------------------- | ------------------------------------------ | ------------------------ |
| `bg-warning-100`          | `bg-warning-subtle`                        | Alert backgrounds        |
| `bg-warning-500`          | `bg-warning-soft` or `bg-warning`   | Moderate emphasis        |
| `bg-warning-600`          | `bg-warning` or `bg-warning-strong` | Buttons, hover           |
| `bg-warning-800`          | `bg-warning-strong`                        | Active states            |
| `text-warning-foreground` | `text-on-warning`                   | Contrasting text on bg   |

#### Danger

| Old Class                | New Class                                | Context                 |
| ------------------------ | ---------------------------------------- | ----------------------- |
| `bg-danger-100`          | `bg-danger-subtle`                       | Alert backgrounds       |
| `bg-danger-500`          | `bg-danger-soft` or `bg-danger`   | Moderate emphasis       |
| `bg-danger-600`          | `bg-danger` or `bg-danger-strong` | Buttons, hover          |
| `bg-danger-800`          | `bg-danger-strong`                       | Active states           |
| `text-danger-foreground` | `text-on-danger`                  | Contrasting text on bg  |

## Common UI Pattern Migrations

### Buttons

#### Default Button

```gts
// Before
<button class="bg-default-800 text-default-100 hover:bg-default-800/80">
  Click me
</button>

// After
<button class="bg-neutral-strong text-on-neutral-strong hover:bg-neutral">
  Click me
</button>
```

#### Primary Button

```gts
// Before
<button class="bg-primary text-primary-foreground hover:bg-primary-500">
  Submit
</button>

// After
<button class="bg-primary text-on-primary hover:bg-primary-soft">
  Submit
</button>
```

#### Outlined Button

```gts
// Before
<button class="border-primary text-primary hover:bg-primary hover:text-primary-foreground">
  Cancel
</button>

// After
<button class="border-primary text-primary hover:bg-primary hover:text-on-primary">
  Cancel
</button>
```

### Alerts and Notifications

#### Success Alert

```gts
// Before
<div class="bg-success-100 border-success-500 text-success-900">
  <Icon class="text-success" />
  <p>Success message</p>
</div>

// After
<div class="bg-success-subtle border-success-soft text-on-success-subtle">
  <Icon class="text-success" />
  <p>Success message</p>
</div>
```

#### Error Alert

```gts
// Before
<div class="bg-danger-100 border-danger text-danger-foreground">
  Error occurred
</div>

// After
<div class="bg-danger-subtle border-danger text-on-danger-subtle">
  Error occurred
</div>
```

### Form Inputs

```gts
// Before
<input class="border-default-700 focus:border-primary text-default-900" />

// After
<input class="border-neutral-soft focus:border-primary text-neutral-strong" />
```

### Text Hierarchy

```gts
// Before
<h1 class="text-default-900">Heading</h1>
<p class="text-default-700">Body text</p>
<span class="text-default-500">Caption</span>

// After
<h1 class="text-neutral-bolder">Heading</h1>
<p class="text-neutral-strong">Body text</p>
<span class="text-neutral-firm">Caption</span>
```

### Badges

```gts
// Before
<span class="bg-success text-success-foreground">
  Active
</span>

// After
<span class="bg-success-strong text-on-success-strong">
  Active
</span>
```

## Dark Mode Considerations

The new semantic colors automatically adapt to dark mode. Key changes:

- In dark mode, `strong` becomes the **lightest** shade (inverted from light mode)
- `subtle` uses darker base colors with lower alpha
- `on-{color}-{level}` automatically maintains WCAG accessibility standards

**No changes needed** — your dark mode classes will work automatically:

```gts
// Both light and dark modes handled
<div class="bg-neutral-subtle text-neutral-strong">
  Content
</div>
```

## Migration Strategy

### Step 1: Identify Old Patterns

Search your codebase for old color patterns:

```bash
# Find numbered color classes
grep -r "default-[0-9]" --include="*.{tsx,ts,gts,gjs,md}"
grep -r "primary-[0-9]" --include="*.{tsx,ts,gts,gjs,md}"

# Find foreground classes
grep -r "foreground" --include="*.{tsx,ts,gts,gjs,md}"
```

### Step 2: Update Theme Configuration

If you've customized Frontile's theme, update your color definitions:

```typescript
// Before
import { themeColors } from '@frontile/theme';

colors: {
  default: themeColors.light.default,
  primary: themeColors.light.primary,
}

// After
import semanticColors from '@frontile/theme/colors/semantic';

colors: {
  neutral: semanticColors.light.neutral,
  primary: semanticColors.light.primary,
}
```

### Step 3: Update Component Styles

Replace old color classes with new semantic levels:

1. Start with theme components (highest impact)
2. Move to your custom components
3. Update documentation and examples
4. Update tests

### Step 4: Test Thoroughly

- **Visual regression**: Check all components in both light and dark modes
- **Accessibility**: Verify contrast ratios still meet WCAG AA standards
- **Interactive states**: Test hover, focus, active, and disabled states

## Interactive states

The tables above map each old number to a resting level. They deliberately do not
try to guess hover, pressed, or disabled variants, because the old numbered scale
encoded those by stepping the number and the new one has dedicated levels:

| Old | New | Level |
| --- | --- | --- |
| `hover:bg-primary-500` on a `bg-primary-600` element | `hover:bg-primary-soft` | `soft` is the hover step for solid fills |
| `active:bg-primary-800` | `active:bg-primary-firm` | `firm` is the most emphatic fill |
| `hover:bg-default-200` on a tonal surface | `hover:bg-neutral-muted` | `muted` is the hover step for tonal surfaces |
| A fill between resting and firm | `bg-primary-mild` | `mild` |

If you had a three-state solid button — `bg-primary-600`, `hover:bg-primary-500`,
`active:bg-primary-700` — it becomes `bg-primary`, `hover:bg-primary-soft`,
`active:bg-primary-firm`.

## Automated migration

There is no supported codemod for this. A find-and-replace can do the
unambiguous half — the category rename and the `foreground` suffix — but it
cannot pick emphasis levels, and it cannot tell a resting fill from a hover one:

```bash
# The mechanical part only. Review everything it touches.
# GNU sed: drop the '' after -i
find . -type f \( -name "*.hbs" -o -name "*.gts" -o -name "*.gjs" -o -name "*.ts" \) \
  -exec sed -i '' \
  -e 's/\bbg-default-/bg-neutral-/g' \
  -e 's/\btext-default-/text-neutral-/g' \
  -e 's/\bborder-default-/border-neutral-/g' \
  -e 's/\bbg-background\b/bg-surface-canvas/g' \
  {} +
```

Then find what's left by hand — anything still carrying a number needs a level
chosen for it:

```bash
grep -rnE '(bg|text|border|ring|from|to|via)-(neutral|primary|secondary|tertiary|success|warning|danger)-[0-9]{2,3}' .
```

That grep is worth keeping in CI for a release or two. A leftover numbered class
produces no CSS and no error, so it will not show up any other way.

## Decision Guide

When choosing between levels, ask:

### Background Colors

- **Maximum emphasis button?** → `{color}-strong`
- **Standard button/element?** → `{color}` (DEFAULT)
- **Hover state?** → `{color}-soft`
- **Light alert background?** → `{color}-subtle`

### Text Colors

- **On colored background?** → `on-{color}-{level}` (automatically white or black based on WCAG contrast)
- **On neutral background?** → `neutral-bolder` (heading), `neutral-strong` (body), `neutral-firm` (caption)

### Borders

- **Colored semantic borders?** → `{color}` or `{color}-soft`
- **Neutral dividers?** → `neutral-soft` or `neutral-subtle`

---

# Theme Configuration Migration

Source: /docs/migrations/v0-18/theme-configuration.md

# Theme Configuration Migration Guide

This guide helps you migrate your Frontile theme configuration to v0.18, which adopts Tailwind v4's CSS-first configuration approach.

## Overview

Frontile v0.18 updates the theme system to align with Tailwind CSS v4's CSS-first configuration. Theme values are now CSS variables you can read and override directly in your stylesheets, instead of JavaScript config processed at build time, and the `--frontile-` prefix is gone from variable names.

## Breaking Changes

### 1. CSS Import Required

**You must add** `@import "@frontile/theme"` to your application's entry
stylesheet — `app/styles/app.css` on a classic Ember build, `app/app.css` under
Vite. It has to come after the `@plugin` line.

#### Before (v0.17)

```css
@import 'tailwindcss' source('../../');
@plugin "@frontile/theme/plugin/default";
```

#### After (v0.18)

```css
@import 'tailwindcss' source('../../');
@plugin "@frontile/theme/plugin/default";
@import "@frontile/theme";
```

**Why:** The `@import "@frontile/theme"` statement loads Frontile's base CSS styles, custom variants, and animations that are now CSS-based rather than plugin-generated.

### 2. Tailwind Content Detection

This one is a consequence of [package
consolidation](./package-consolidation.md) rather than of the theme itself, and
it is the easiest to miss.

Tailwind v4 skips `node_modules` when it scans for classes. Frontile's own
component templates live there, so they have to be pointed at explicitly or
their classes are purged and components render unstyled — with no error, since a
purged class is simply a class that no longer exists.

In v0.17 one `@source` covered everything, because every component shipped under
the `@frontile` scope:

```css
@source '../../node_modules/@frontile';
```

In v0.18 the components moved to the unscoped `frontile` package, so that line no
longer reaches them:

```css
@source '../../node_modules/frontile';
/* Keep the scoped line too if you use @frontile/forms-legacy or
   @frontile/changeset-form, which remain separate packages. */
@source '../../node_modules/@frontile';
```

Paths are relative to the CSS file, so adjust the depth to match where yours
lives. This applies whether or not you have migrated your imports: the classes
come from `frontile` either way, because the old packages only re-export from it.

**If components look unstyled after upgrading and the theme import is present,
this is almost always why.**

### 3. CSS Variable Names

The `--frontile-` prefix is gone. What replaces it depends on the kind of token:

| Token kind | v0.17 | v0.18 |
| --- | --- | --- |
| Colors | `--frontile-primary-500` | `--color-primary-firm` (a `--color-` prefix, and a named level) |
| Everything else | `--frontile-hover-opacity` | `--opacity-hover` (no prefix) |

Colors are the case to watch. They did not simply lose a prefix — they gained
`--color-`, and the numbered scale they used is gone, so there is no
`--color-primary-500` either. Pick the level that matches the emphasis you
wanted; see the [semantic colors guide](./semantic-colors.md) for the mapping.

#### Before (v0.17)

```css
.my-component {
  background: var(--frontile-primary-500);
  opacity: var(--frontile-hover-opacity);
}
```

#### After (v0.18)

```css
.my-component {
  background: var(--color-primary);
  opacity: var(--opacity-hover);
}
```

**Migration:** search your codebase for `--frontile-`. Nothing errors if you
miss one — an undefined custom property silently resolves to nothing, so the
declaration is simply dropped:

```bash
grep -rn -- "--frontile-" --include="*.css" --include="*.scss" \
  --include="*.gts" --include="*.gjs" --include="*.ts" --include="*.js" .
```

### 4. LayoutTheme Interface (Nested Structure)

If you're using TypeScript and customizing the theme configuration, the `LayoutTheme` interface has changed from flat to nested.

#### Before (v0.17)

```typescript
import { frontile } from '@frontile/theme/plugin';

module.exports = frontile({
  hoverOpacity: 0.9,
  disabledOpacity: 0.4
});
```

#### After (v0.18)

```typescript
import { frontile } from '@frontile/theme/plugin';

module.exports = frontile({
  opacity: {
    hover: 0.9,
    disabled: 0.4
  }
});
```

**Why:** The nested structure provides better organization for related theme properties and aligns with CSS custom property conventions.

### 5. Border Radius Is Now a Derived Scale

Every `rounded-*` step is now `calc(var(--radius) * n)` instead of a hardcoded
value, so `--radius` is a single knob for how round the whole library looks.

#### Before (v0.17)

```css
--radius-xs: 1px;
--radius-sm: 2px;
--radius-md: 4px;
--radius: 8px;
--radius-xl: 12px;
--radius-2xl: 16px;
--radius-default: 20px;
```

#### After (v0.18)

```css
--radius: 0.5rem;                            /* 8px — the base */
--radius-xs: calc(var(--radius) * 0.25);     /* 2px */
--radius-sm: calc(var(--radius) * 0.5);      /* 4px */
--radius-md: calc(var(--radius) * 0.75);     /* 6px */
--radius-lg: calc(var(--radius) * 1);        /* 8px */
--radius-xl: calc(var(--radius) * 1.5);      /* 12px */
--radius-2xl: calc(var(--radius) * 2);       /* 16px */
--radius-3xl: calc(var(--radius) * 3);       /* 24px */
--radius-4xl: calc(var(--radius) * 4);       /* 32px */
--radius-default: calc(var(--radius) * 2.5); /* 20px */
```

**What actually changes visually.** Three steps got slightly larger, bringing the
scale back in line with stock Tailwind v4:

| Utility | v0.17 | v0.18 |
| --- | --- | --- |
| `rounded-xs` | 1px | 2px |
| `rounded-sm` | 2px | 4px |
| `rounded-md` | 4px | 6px |

Everything from `rounded` upward keeps its value. If you relied on `rounded-sm`
being 2px, use `rounded-xs`, or pin the step explicitly:

```css
@theme {
  --radius-sm: 2px; /* opt this one step out of the derived scale */
}
```

**Popover surfaces are rounder.** Dropdown and Popover panels moved from
`rounded-sm` (2px) to `rounded-xl` (12px), Listbox and menu items to
`rounded-lg` (8px), and NotificationCard to `rounded-xl`. Select and
Autocomplete inherit the change through Popover. This is a visual change only —
no API moved. To go back to square-ish menus, set `--radius: 0`, or override the
component classes via `@classes`.

**Why:** The old scale was smaller than stock Tailwind at every step, which made
`rounded-sm` a surprise for anyone reading the class name, and left popover
surfaces visibly sharper than the Modal and Drawer they sit alongside. Deriving
the scale from one value fixes the inconsistency and makes overall roundness a
one-line theme decision.

**Dialing it from the plugin config**, including per theme:

```typescript
module.exports = frontile({
  layout: {
    radius: { DEFAULT: '0.75rem' }
  }
});
```

## Migration Steps

### Step 1: Update CSS Imports

Add the `@import "@frontile/theme"` statement to your entry stylesheet:

```css
@import 'tailwindcss' source('../../');
@plugin "@frontile/theme/plugin/default";
@import "@frontile/theme";

/* Your custom styles */
```

**For custom theme configurations**, update to reference your custom config file:

```css
@import 'tailwindcss' source('../../');
@plugin "./../../frontile.js";
@import "@frontile/theme";
```

### Step 2: Update CSS Variable References

If you reference Frontile's CSS variables directly in your own stylesheets or
components:

1. **Find all references:**

```bash
grep -rn -- "--frontile-" --include="*.css" --include="*.scss" \
  --include="*.gts" --include="*.gjs" .
```

2. **Rename them.** Colors take a `--color-` prefix and a named level; other
   tokens just drop the prefix:

```diff
- background: var(--frontile-primary);
+ background: var(--color-primary);

- border-color: var(--frontile-primary-700);
+ border-color: var(--color-primary-firm);

- opacity: var(--frontile-hover-opacity);
+ opacity: var(--opacity-hover);
```

3. **Update computed styles in JavaScript:**

```diff
- const color = getComputedStyle(el).getPropertyValue('--frontile-primary-500');
+ const color = getComputedStyle(el).getPropertyValue('--color-primary');
```

   `getPropertyValue` returns an empty string for a variable that doesn't
   exist, so a missed rename here reads as "no color" rather than throwing.

### Step 3: Update Theme Configuration (If Customized)

If you have a custom `frontile.js` configuration file, update the structure:

#### Before (v0.17)

```javascript
const { frontile } = require('@frontile/theme/plugin');

module.exports = frontile({
  hoverOpacity: 0.9,
  disabledOpacity: 0.4,
  // other flat properties
});
```

#### After (v0.18)

```javascript
const { frontile } = require('@frontile/theme/plugin');

module.exports = frontile({
  opacity: {
    hover: 0.9,
    disabled: 0.4
  },
  // other nested properties
});
```

**Common property mappings:**

| Old Property (v0.17) | New Property (v0.18) |
| --- | --- |
| `hoverOpacity` | `opacity.hover` |
| `disabledOpacity` | `opacity.disabled` |

### Step 4: Test Your Application

After making these changes:

1. **Rebuild your application** to ensure all changes are applied
2. **Test interactive states** (hover, disabled) to verify opacity values
3. **Check custom styled components** that reference CSS variables directly
4. **Verify in both light and dark modes** if your app supports theming

## Common Issues and Solutions

### Issue: Styles Not Applied

**Problem:** Components don't have expected Frontile styles

**Solution:** Ensure you've added `@import "@frontile/theme"` to your CSS file. This import is now required.

### Issue: CSS Variables Undefined

**Problem:** Browser console shows `undefined` for CSS variables

**Solution:**
1. Check that you removed the `--frontile-` prefix
2. Verify the import order in your CSS file (plugin first, then theme import)
3. Rebuild your application

### Issue: TypeScript Errors in Config

**Problem:** TypeScript errors in `frontile.js` configuration

**Solution:** Update to the nested structure. Ensure you're using `opacity.hover` instead of `hoverOpacity`.

## Migration Checklist

Use this checklist to track your theme configuration migration:

- [ ] Added `@import "@frontile/theme"` to app.css
- [ ] Removed `--frontile-` prefix from all CSS variable references
- [ ] Updated `frontile.js` config to use nested structure (if applicable)
- [ ] Rebuilt application and verified styles are applied
- [ ] Tested hover and disabled states
- [ ] Verified custom components using CSS variables
- [ ] Tested in both light and dark modes (if applicable)

## Need Help?

If you encounter issues:

- Review the [Theme documentation](../../theming/overview.md) for the latest configuration options
- Check the [Getting Started guide](../../get-started/index.md) for setup examples
- Search or create an issue on [GitHub](https://github.com/josemarluedke/frontile/issues)

---

# Package Consolidation

Source: /docs/migrations/v0-18/package-consolidation.md

# Package Consolidation Migration Guide

## Overview

Starting with version **0.18.0**, Frontile consolidates seven separate `@frontile/*` packages into a single `frontile` package:

- `@frontile/buttons`
- `@frontile/collections`
- `@frontile/forms`
- `@frontile/overlays`
- `@frontile/notifications`
- `@frontile/status`
- `@frontile/utilities`

> **This one is optional for all of 0.18.x.** The old packages re-export
> everything and only log a deprecation warning, so your imports keep working
> until 0.19. Do the [theme configuration](./theme-configuration.md) and
> [color](./semantic-colors.md) migrations first — those actually break things,
> and mostly do it silently. Rewriting every import before them produces a diff
> large enough to hide the changes you need to review.

**Why?** Modern Ember.js applications use explicit imports via `.gts`/`.gjs` template tag format. With explicit imports, bundlers can tree-shake unused code automatically, making the multi-package architecture unnecessary overhead. A single package simplifies installation, version management, and dependency resolution without sacrificing bundle size.

**Timeline:**

| Version | What happens |
|---------|--------------|
| **0.18.0** | The old `@frontile/*` packages become thin deprecation wrappers that re-export from `frontile`. All existing import paths continue to work, but emit deprecation warnings at build time. |
| **0.19.0** | The old `@frontile/*` wrapper packages are removed. You must update imports to use `frontile` directly. |

## Quick Start

Update your app in two steps:

### 1. Swap packages

```bash
# Remove old packages
npm uninstall @frontile/buttons @frontile/collections @frontile/forms \
  @frontile/overlays @frontile/notifications @frontile/status @frontile/utilities

# Install the consolidated package (if not already installed)
npm install frontile @frontile/theme
```

If you use **pnpm** or **yarn**, substitute the appropriate commands:

```bash
# pnpm
pnpm remove @frontile/buttons @frontile/collections @frontile/forms \
  @frontile/overlays @frontile/notifications @frontile/status @frontile/utilities
pnpm add frontile @frontile/theme

# yarn
yarn remove @frontile/buttons @frontile/collections @frontile/forms \
  @frontile/overlays @frontile/notifications @frontile/status @frontile/utilities
yarn add frontile @frontile/theme
```

### 2. Update imports

Replace `@frontile/<package>` with `frontile/<package>` (or just `frontile`) in your source files. See the [Import Path Changes](#import-path-changes) section below for details.

## Import Path Changes

Three import styles are supported with the consolidated package:

### Flat barrel import

Import everything from one place:

```typescript
import { Button, Modal, Input, ProgressBar } from 'frontile';
```

### Scoped sub-exports (by category)

Import from a category-specific path. This mirrors the old package names without the `@frontile/` prefix:

```typescript
import { Button, ButtonGroup, Chip } from 'frontile/buttons';
import { Modal, Drawer, Overlay, Popover } from 'frontile/overlays';
import { Input, Select, Checkbox, Textarea } from 'frontile/forms';
import { Table, Listbox, Dropdown } from 'frontile/collections';
import { NotificationCard, NotificationsContainer } from 'frontile/notifications';
import { ProgressBar } from 'frontile/status';
import { Avatar, Collapsible, Divider, Spinner } from 'frontile/utilities';
```

### Direct component file imports

For maximum control and tree-shaking, import directly from the component file:

```typescript
import Button from 'frontile/components/buttons/button';
import Modal from 'frontile/components/overlays/modal';
import Header from 'frontile/components/overlays/modal/header';
import Input from 'frontile/components/forms/input';
```

## Import Mapping Table

The table below shows how old import paths map to the new paths.

### Barrel imports

| Old Import | New Import |
|---|---|
| `from '@frontile/buttons'` | `from 'frontile/buttons'` or `from 'frontile'` |
| `from '@frontile/forms'` | `from 'frontile/forms'` or `from 'frontile'` |
| `from '@frontile/collections'` | `from 'frontile/collections'` or `from 'frontile'` |
| `from '@frontile/overlays'` | `from 'frontile/overlays'` or `from 'frontile'` |
| `from '@frontile/notifications'` | `from 'frontile/notifications'` or `from 'frontile'` |
| `from '@frontile/status'` | `from 'frontile/status'` or `from 'frontile'` |
| `from '@frontile/utilities'` | `from 'frontile/utilities'` or `from 'frontile'` |

### Sub-path imports

| Old Import | New Import |
|---|---|
| `from '@frontile/overlays/components/modal'` | `from 'frontile/components/overlays/modal'` |
| `from '@frontile/overlays/components/modal/header'` | `from 'frontile/components/overlays/modal/header'` |
| `from '@frontile/overlays/components/drawer'` | `from 'frontile/components/overlays/drawer'` |
| `from '@frontile/overlays/components/overlay'` | `from 'frontile/components/overlays/overlay'` |
| `from '@frontile/overlays/components/popover'` | `from 'frontile/components/overlays/popover'` |
| `from '@frontile/forms/test-support'` | `from 'frontile/test-support'` |
| `from '@frontile/utilities/utils/safe-styles'` | `from 'frontile/utils/safe-styles'` |
| `from '@frontile/notifications/services/notifications'` | `from 'frontile/services/notifications'` |

## Automated Migration Script

Save the following script as `migrate-frontile.sh` and run it from your project root to update all import paths automatically.

```bash
#!/bin/bash
# Migrate Frontile imports from @frontile/* to frontile
# Run from your project root
#
# Usage:
#   chmod +x migrate-frontile.sh
#   ./migrate-frontile.sh

set -euo pipefail

echo "Migrating @frontile/* imports to frontile..."

# Sub-path imports (must run BEFORE barrel imports to avoid partial matches)
find app tests -name '*.ts' -o -name '*.gts' -o -name '*.js' -o -name '*.gjs' | \
  xargs sed -i '' \
    -e "s|from '@frontile/overlays/components/|from 'frontile/components/overlays/|g" \
    -e "s|from '@frontile/notifications/services/|from 'frontile/services/|g" \
    -e "s|from '@frontile/forms/test-support|from 'frontile/test-support|g" \
    -e "s|from '@frontile/utilities/utils/|from 'frontile/utils/|g" \
    -e "s|from '@frontile/collections/utils/|from 'frontile/utils/|g"

# Barrel imports
find app tests -name '*.ts' -o -name '*.gts' -o -name '*.js' -o -name '*.gjs' | \
  xargs sed -i '' \
    -e "s|from '@frontile/buttons'|from 'frontile/buttons'|g" \
    -e "s|from '@frontile/collections'|from 'frontile/collections'|g" \
    -e "s|from '@frontile/forms'|from 'frontile/forms'|g" \
    -e "s|from '@frontile/overlays'|from 'frontile/overlays'|g" \
    -e "s|from '@frontile/notifications'|from 'frontile/notifications'|g" \
    -e "s|from '@frontile/status'|from 'frontile/status'|g" \
    -e "s|from '@frontile/utilities'|from 'frontile/utilities'|g"

echo "Done! Review the changes with: git diff"
```

**Note:** The `sed -i ''` syntax is for macOS. On Linux, use `sed -i` (without the empty quotes) instead.

## Packages NOT Affected

The following packages are **not** part of this consolidation. Their imports remain unchanged:

- **`@frontile/theme`** -- The styling system. Stays as a separate package because it provides Tailwind CSS configuration and has a distinct role in the build pipeline.
- **`@frontile/forms-legacy`** -- Legacy form components. Deprecated, and removed in 0.19.0 alongside the wrapper packages above. See the [Forms Legacy migration guide](./forms-legacy.md).
- **`@frontile/changeset-form`** -- Changeset integration. Deprecated, and removed in 0.19.0 alongside the wrapper packages above. See the [Changeset Form migration guide](./changeset-form.md).

## Deprecation Timeline

| Version | Status |
|---------|--------|
| **0.18.0** | Old `@frontile/*` packages become thin wrappers that re-export from `frontile`. `@frontile/forms-legacy` and `@frontile/changeset-form` are also marked deprecated. All of them emit deprecation warnings at build time. All existing import paths continue to work. |
| **0.19.0** | All of the above are removed: the `@frontile/*` wrapper packages, `@frontile/forms-legacy`, and `@frontile/changeset-form`. You must update imports to use `frontile` directly, and migrate off legacy forms and changeset integration. |

During the **0.18.x** cycle, you can migrate at your own pace. Both old and new import paths work simultaneously. However, we recommend migrating sooner rather than later to avoid a last-minute rush before 0.19.0.

## For .hbs Template Users

If you use `.hbs` templates (not `.gts`/`.gjs`), components remain auto-importable through the deprecated wrapper packages during the 0.18.x cycle. However, you should plan to migrate to `.gts` explicit imports before 0.19.0, as the wrapper packages will be removed.

During 0.18.x, `.hbs` users should:

1. Keep the deprecated `@frontile/*` packages installed so that auto-imports continue to work.
2. Plan migration to `.gts`/`.gjs` template format for new code.
3. Use explicit imports in any new `.gts`/`.gjs` files.

Once you have migrated all templates to `.gts`/`.gjs`, you can remove the deprecated wrapper packages and use the new `frontile` imports exclusively.

---

# Filter Ranking

Source: /docs/migrations/v0-18/filter-ranking.md

# Filtered lists are now ranked by relevance

`Autocomplete` and filterable `Select` used to filter with a case-insensitive
"contains" check and render whatever survived **in the order you passed it**.
They now score each item and list the closest match first.

Nothing to change unless you pass your own `@filter`. The results are ordered
differently, which is the point.

## Why it changed

The old default could only answer "does this item match?", never "how well?":

```ts
// before
function defaultFilter(itemValue: string, filterValue: string): boolean {
  return itemValue.toLowerCase().includes(filterValue.toLowerCase());
}
```

A predicate filters but cannot reorder, so an exact match sat wherever `@items`
happened to put it. Typing `button` into a list ordered alphabetically returned
`ButtonGroup` above `Button` — both "match", and source order decided the rest.

## What you get now

Typing `butt`:

| | Before | After |
| --- | --- | --- |
| 1 | ButtonGroup | **Button** |
| 2 | Button Group | ButtonGroup |
| 3 | Button | Button Group |

Acronyms also match now, which "contains" could never do:

- `bg` → `ButtonGroup`
- `nz` → `New Zealand`
- `prog` → `ProgressBar`

**Nothing that matched before stops matching.** The threshold is calibrated so
every result the old `includes()` filter returned is still returned; the change
is additive plus reordering.

## `@filter` accepts a score

```ts
filter?: (itemValue: string, inputValue: string) => boolean | number;
```

Return a **number** to rank — higher sorts first, `0` means no match. Return a
**boolean** to filter only, preserving the order of `@items`.

Existing boolean filters are unaffected:

```gts
{{! still works exactly as before, including source ordering }}
<Autocomplete @filter={{this.startsWith}} @items={{this.items}} />
```

```ts
startsWith = (itemValue: string, inputValue: string) =>
  itemValue.toLowerCase().startsWith(inputValue.toLowerCase());
```

### Keeping the old behavior

Pass the previous implementation explicitly:

```ts
const containsFilter = (itemValue: string, inputValue: string) =>
  itemValue.toLowerCase().includes(inputValue.toLowerCase());
```

```gts
<Select @isFilterable={{true}} @filter={{containsFilter}} @items={{this.items}} />
```

## Tuning how loose matching is

Fuzzy matching is looser than "contains", so a threshold keeps out noise. It
cannot distinguish a useful abbreviation from a coincidence — `btn` → `Button`
and `sa` → `Spain` are the same shape, both scattered mid-word subsequences —
so the default favors precision and matches neither.

To trade precision for recall, build your own:

```ts
import { createFuzzyFilter } from 'frontile/utils/filter';

// matches btn -> Button, at the cost of also matching sa -> Spain
const looseFilter = createFuzzyFilter({ threshold: 0 });
```

```gts
<Autocomplete @filter={{looseFilter}} @items={{this.items}} />
```

`DEFAULT_MATCH_THRESHOLD` is `0.4`. Raise it for stricter matching, lower it for
looser.

---

# Migrating from Forms Legacy

Source: /docs/migrations/v0-18/forms-legacy.md

# Migrating from Forms Legacy

This guide covers migrating from the legacy `@frontile/forms-legacy` package to the modern `frontile` forms: a smaller API surface, better ARIA/keyboard support, slot-based customization, and no dependency on `ember-power-select` or `ember-basic-dropdown`.

`@frontile/forms-legacy` is deprecated and will be removed in 0.19.0.

## Overview

### What's New in Frontile Forms

- Simpler component API with better TypeScript support
- Better ARIA support and keyboard navigation
- Slot-based content insertion and CSS class customization
- No dependency on `ember-power-select` or `ember-basic-dropdown`
- New components: a `Form` wrapper with automatic data extraction, and `Switch`
- Simplified error handling, and tighter integration with validation libraries

### Migration Effort

- **Low**: FormInput, FormTextarea, FormCheckbox, FormRadio (minor API changes)
- **Medium**: FormCheckboxGroup, FormRadioGroup (API restructuring)
- **High**: FormSelect (complete API redesign)

## Installation

```bash
# Remove the legacy package
npm uninstall @frontile/forms-legacy

# Install the new package
npm install frontile @frontile/theme
```

Update your imports:

```js
// Before (forms-legacy)
import FormInput from '@frontile/forms-legacy/components/form-input';
import FormCheckbox from '@frontile/forms-legacy/components/form-checkbox';

// After (forms)
import { Input, Checkbox } from 'frontile';
```

## Recommended Approach: Form + Field Pattern

The modern `frontile` package introduces a **Form + Field pattern** that handles data binding and validation for you. This is the recommended approach for new forms and migrations.

### Why Use Form + Field?

- No manual state management — `form.Field` binds value and errors automatically
- Built-in validation with Valibot, Zod, or a custom validator
- Nested data support via dot notation in field names

### Quick Example

```gts
import Component from '@glimmer/component';
import { Form } from 'frontile';
import type { FormResultData } from 'frontile';
import * as v from 'valibot';

const loginSchema = v.object({
  email: v.pipe(
    v.string(),
    v.nonEmpty('Email is required'),
    v.email('Please enter a valid email')
  ),
  password: v.pipe(
    v.string(),
    v.minLength(6, 'Password must be at least 6 characters')
  )
});

type LoginSchema = v.InferOutput<typeof loginSchema>;

export default class LoginForm extends Component {
  schema = loginSchema;

  handleSubmit = (result: FormResultData<LoginSchema>) => {
    if (result.isValid) {
      // result.data is typed as LoginSchema
      this.login(result.data);
    }
  };

  <template>
    <Form
      @schema={{this.schema}}
      @onSubmit={{this.handleSubmit}}
      as |form|
    >
      <form.Field @name='email' as |field|>
        <field.Input @label='Email' @type='email' />
      </form.Field>

      <form.Field @name='password' as |field|>
        <field.Input @label='Password' @type='password' />
      </form.Field>

      <button type='submit'>Login</button>
    </Form>
  </template>
}
```

Compared to manual binding:

- `form.Field` automatically binds the value and errors to the input
- Validation runs automatically based on the schema
- No need to manually manage `@tracked` properties for form data
- `result.data` contains all form values on submit

For complete documentation on the Form component, validation patterns, nested data, and advanced features, see the [Form Component Documentation](https://frontile.dev/docs/components/forms/form).

## Migrating Validation

If you're using manual validation with forms-legacy, you can migrate to schema-based validation with Valibot instead.

### Before (forms-legacy with manual validation)

```gts
import { tracked } from '@glimmer/tracking';
import { Input, Textarea } from '@frontile/forms-legacy';

export default class UserProfileForm extends Component {
  @tracked email = '';
  @tracked bio = '';
  @tracked errors = {};

  validateForm = () => {
    const errors = {};

    if (!this.email) {
      errors.email = 'Email is required';
    } else if (!this.email.includes('@')) {
      errors.email = 'Invalid email format';
    }

    if (this.bio && this.bio.length < 10) {
      errors.bio = 'Bio must be at least 10 characters';
    }

    return errors;
  };

  handleSubmit = (event) => {
    event.preventDefault();
    this.errors = this.validateForm();

    if (Object.keys(this.errors).length === 0) {
      this.saveProfile({ email: this.email, bio: this.bio });
    }
  };

  <template>
    <form {{on 'submit' this.handleSubmit}}>
      <FormInput
        @label='Email'
        @value={{this.email}}
        @onInput={{fn (mut this.email)}}
        @errors={{this.errors.email}}
      />

      <FormTextarea
        @label='Bio'
        @value={{this.bio}}
        @onInput={{fn (mut this.bio)}}
        @errors={{this.errors.bio}}
      />

      <button type='submit'>Save Profile</button>
    </form>
  </template>
}
```

### After (forms with Valibot validation)

```gts
import Component from '@glimmer/component';
import { Form } from 'frontile';
import type { FormResultData } from 'frontile';
import * as v from 'valibot';

const profileSchema = v.object({
  email: v.pipe(
    v.string(),
    v.nonEmpty('Email is required'),
    v.email('Invalid email format')
  ),
  bio: v.optional(
    v.pipe(
      v.string(),
      v.minLength(10, 'Bio must be at least 10 characters')
    )
  )
});

type ProfileSchema = v.InferOutput<typeof profileSchema>;

export default class UserProfileForm extends Component {
  schema = profileSchema;

  handleSubmit = (result: FormResultData<ProfileSchema>) => {
    if (result.isValid) {
      // result.data is typed as ProfileSchema
      this.saveProfile(result.data);
    }
  };

  <template>
    <Form
      @schema={{this.schema}}
      @onSubmit={{this.handleSubmit}}
      as |form|
    >
      <form.Field @name='email' as |field|>
        <field.Input @label='Email' @type='email' />
      </form.Field>

      <form.Field @name='bio' as |field|>
        <field.Textarea @label='Bio' />
      </form.Field>

      <button type='submit'>Save Profile</button>
    </Form>
  </template>
}
```

Compared to the manual version:

- No need for `@tracked` properties or manual state management
- Validation logic is declarative and reusable
- Errors are automatically displayed by Field components
- Validation runs automatically on blur and submit (configurable with `@validateOn`)

For complex validation scenarios or custom validation functions, see the [Form Component Documentation](https://frontile.dev/docs/components/forms/form).

## Nested Data Support

The Form + Field pattern supports nested data structures using dot notation in field names. This makes it easy to work with complex data models without flattening your data structure.

```gts
import Component from '@glimmer/component';
import { Form } from 'frontile';
import type { FormResultData } from 'frontile';
import * as v from 'valibot';

const userSchema = v.object({
  user: v.object({
    profile: v.object({
      email: v.pipe(v.string(), v.email()),
      firstName: v.string(),
      lastName: v.string()
    }),
    settings: v.object({
      notifications: v.boolean()
    })
  })
});

type UserSchema = v.InferOutput<typeof userSchema>;

export default class UserSettingsForm extends Component {
  schema = userSchema;

  handleSubmit = (result: FormResultData<UserSchema>) => {
    if (result.isValid) {
      // result.data.user.profile.email is fully typed
      this.saveUserSettings(result.data);
    }
  };

  <template>
    <Form @schema={{this.schema}} @onSubmit={{this.handleSubmit}} as |form|>
      <form.Field @name='user.profile.email' as |field|>
        <field.Input @label='Email' />
      </form.Field>

      <form.Field @name='user.profile.firstName' as |field|>
        <field.Input @label='First Name' />
      </form.Field>

      <form.Field @name='user.settings.notifications' as |field|>
        <field.Checkbox @label='Enable notifications' />
      </form.Field>

      <button type='submit'>Save</button>
    </Form>
  </template>
}
```

The Form component automatically handles data flattening and unflattening. On submit, `result.data` will contain the properly nested structure. See the [Form Component Documentation](https://frontile.dev/docs/components/forms/form) for more details.

## Breaking Changes

### 1. Component Names

All component names have dropped the `Form` prefix:

- `FormInput` → `Input`
- `FormTextarea` → `Textarea`
- `FormCheckbox` → `Checkbox`
- etc.

### 2. Import Strategy

Changed from default imports to named imports from the package index.

### 3. Error Handling

The error handling approach has been simplified:

- Removed `hasSubmitted`, `hasError`, `showError` props
- Use `errors` and `isInvalid` for error states
- Automatic error display based on `errors` presence

### 4. Validation Integration

Better integration with form validation libraries through the new `Form` component.

### 5. CSS Classes

Theme classes have been updated - check `@frontile/theme` for new class names.

## Component Migration

### FormInput → Input

The Input component now supports start/end content slots and clearable functionality.

#### Before (forms-legacy)

```hbs
<FormInput
  @label='First Name'
  @value={{this.firstName}}
  @onInput={{this.setFirstName}}
  @errors={{this.validationErrors.firstName}}
  @hasSubmitted={{this.hasSubmitted}}
  @size='md'
  @hint='Enter your first name'
  @containerClass='custom-container'
  @inputClass='custom-input'
/>
```

#### After (forms)

```hbs
<Input
  @label='First Name'
  @value={{this.firstName}}
  @onInput={{this.setFirstName}}
  @errors={{this.validationErrors.firstName}}
  @size='md'
  @description='Enter your first name'
  @classes={{hash base='custom-container' input='custom-input'}}
  @isClearable={{true}}
>
  <:startContent>
    <SearchIcon />
  </:startContent>
  <:endContent>
    <Button @size='sm'>Go</Button>
  </:endContent>
</Input>
```

#### Key Changes

- `@hint` → `@description`
- `@containerClass` → `@classes={{hash base="..."}}`
- `@inputClass` → `@classes={{hash input="..."}}`
- Removed `@hasSubmitted`, `@hasError`, `@showError`
- Added `@isClearable` option
- Added `<:startContent>` and `<:endContent>` slots
- Added `@startContentPointerEvents` and `@endContentPointerEvents` for click handling

### FormTextarea → Textarea

Minimal changes required for textarea migration.

#### Before (forms-legacy)

```hbs
<FormTextarea
  @label='Description'
  @value={{this.description}}
  @onInput={{this.setDescription}}
  @errors={{this.validationErrors.description}}
  @hasSubmitted={{this.hasSubmitted}}
  @rows='4'
/>
```

#### After (forms)

```hbs
<Textarea
  @label='Description'
  @value={{this.description}}
  @onInput={{this.setDescription}}
  @errors={{this.validationErrors.description}}
  rows='4'
/>
```

#### Key Changes

- Move `@rows` to attributes (`rows="4"`)
- Removed error state props (`@hasSubmitted`, etc.)

### FormCheckbox → Checkbox

The Checkbox component now has better standalone usage and improved accessibility.

#### Before (forms-legacy)

```hbs
<FormCheckbox
  @label='I agree to the terms'
  @checked={{this.agreedToTerms}}
  @onChange={{this.setAgreedToTerms}}
  @errors={{this.validationErrors.terms}}
  @hasSubmitted={{this.hasSubmitted}}
/>
```

#### After (forms)

```hbs
<Checkbox
  @label='I agree to the terms'
  @checked={{this.agreedToTerms}}
  @onChange={{this.setAgreedToTerms}}
  @errors={{this.validationErrors.terms}}
/>
```

#### Key Changes

- **No change** - Still uses `@checked`
- Removed error state props (`@hasSubmitted`, etc.)

### FormCheckboxGroup → CheckboxGroup

CheckboxGroup now uses a component-as-block pattern instead of an items-based API.

#### Before (forms-legacy)

```hbs
<FormCheckboxGroup
  @label='Select your interests'
  @onChange={{this.setInterests}}
  @errors={{this.validationErrors.interests}}
  as |Checkbox|
>
  {{#each this.interestOptions as |option|}}
    <Checkbox
      @value={{option.value}}
      @checked={{this.isInterestSelected option.value}}
    >
      {{option.label}}
    </Checkbox>
  {{/each}}
</FormCheckboxGroup>
```

#### After (forms)

```hbs
<CheckboxGroup
  @label='Select your interests'
  @onChange={{this.setInterests}}
  @errors={{this.validationErrors.interests}}
  @name='interests'
  as |Checkbox|
>
  {{#each this.interestOptions as |option|}}
    <Checkbox
      @value={{option.value}}
      @checked={{this.isInterestSelected option.value}}
    >
      {{option.label}}
    </Checkbox>
  {{/each}}
</CheckboxGroup>
```

#### Key Changes

- **No change** - Still uses `@onChange`
- Add `@name` prop for shared name attribute
- Still uses block params, not items-based API
- CheckboxGroup provides shared onChange to child checkboxes
- Manual tracking of selected values still required

#### Data Management (No Change)

```js
// Tracking selected values (same pattern as before)
@tracked selectedInterests = [];

isInterestSelected(value) {
  return this.selectedInterests.includes(value);
}

setInterests = (value, isChecked) => {
  if (isChecked) {
    this.selectedInterests = [...this.selectedInterests, value];
  } else {
    this.selectedInterests = this.selectedInterests.filter(v => v !== value);
  }
};
```

### FormRadio → Radio

Minimal changes required for radio migration.

#### Before (forms-legacy)

```hbs
<FormRadio
  @name='plan'
  @value='premium'
  @checked={{this.selectedPlan}}
  @onChange={{this.setPlan}}
>
  Premium Plan
</FormRadio>
```

#### After (forms)

```hbs
<Radio
  @name='plan'
  @value='premium'
  @checkedValue={{this.selectedPlan}}
  @onChange={{this.setPlan}}
>
  Premium Plan
</Radio>
```

#### Key Changes

- `@checked` → `@checkedValue` (same concept, just renamed)
- Both expect the currently selected value, not a boolean
- Removed error state props (`@hasSubmitted`, etc.)

### FormRadioGroup → RadioGroup

RadioGroup now uses a component-as-block pattern instead of an items-based API.

#### Before (forms-legacy)

```hbs
<FormRadioGroup
  @label='Select a plan'
  @onChange={{this.setPlan}}
  @errors={{this.validationErrors.plan}}
  as |Radio|
>
  {{#each this.planOptions as |option|}}
    <Radio
      @value={{option.value}}
      @checked={{eq this.selectedPlan option.value}}
    >
      {{option.label}}
    </Radio>
  {{/each}}
</FormRadioGroup>
```

#### After (forms)

```hbs
<RadioGroup
  @label='Select a plan'
  @value={{this.selectedPlan}}
  @onChange={{this.setPlan}}
  @errors={{this.validationErrors.plan}}
  @name='plan'
  as |Radio|
>
  {{#each this.planOptions as |option|}}
    <Radio @value={{option.value}}>
      {{option.label}}
    </Radio>
  {{/each}}
</RadioGroup>
```

#### Key Changes

- **No change** - Still uses `@onChange`
- Uses `@value` for current selected value
- Add `@name` prop for shared name attribute
- Still uses block params, not items-based API
- RadioGroup automatically passes `@checkedValue` to child radios

### FormSelect → Select

This is the most significant change. The new Select component is completely rebuilt and no longer depends on ember-power-select.

#### Before (forms-legacy)

```hbs
<FormSelect
  @label='Select Country'
  @options={{this.countries}}
  @selected={{this.selectedCountry}}
  @onChange={{this.setCountry}}
  @searchEnabled={{true}}
  @searchField='name'
  @errors={{this.validationErrors.country}}
  @placeholder='Choose a country'
  as |country|
>
  {{country.name}}
</FormSelect>
```

#### After (forms)

```hbs
{{! Single selection mode (default) }}
<Select
  @label='Select Country'
  @items={{this.countries}}
  @selectedKey={{this.selectedCountryKey}}
  @onSelectionChange={{this.setCountry}}
  @isFilterable={{true}}
  @errors={{this.validationErrors.country}}
  @placeholder='Choose a country'
>
  <:item as |item|>
    <item.Item @key={{item.key}}>{{item.label}}</item.Item>
  </:item>
</Select>
```

#### Key Changes

- `@options` → `@items`
- `@selected` → `@selectedKey` (string | null for single selection)
- `@onChange` → `@onSelectionChange` (callback receives string | null for single selection)
- `@searchEnabled` → `@isFilterable`
- Removed `@searchField` (filtering works on label automatically)
- Use `<:item>` slot instead of block param
- Built-in filtering instead of external dependency

#### Data Format Migration

```js
// Before: Object-based selection
@tracked selectedCountry = null;
@tracked countries = [
  { id: 1, name: 'United States', code: 'US' },
  { id: 2, name: 'Canada', code: 'CA' }
];

setCountry = (country) => {
  this.selectedCountry = country;
};

// After: Key-based selection (single mode)
@tracked selectedCountryKey = null;
@tracked countries = [
  { key: 'us', label: 'United States', code: 'US' },
  { key: 'ca', label: 'Canada', code: 'CA' }
];

setCountry = (key) => {
  this.selectedCountryKey = key;
};

```

#### Multiple Selection

```hbs
{{! Multiple selection }}
<Select
  @selectionMode='multiple'
  @selectedKeys={{this.selectedCountryKeys}}
  @onSelectionChange={{this.setCountries}}
  @items={{this.countries}}
/>
```

```js
// Multiple selection data handling
@tracked selectedCountryKeys = [];

setCountries = (keys) => {
  this.selectedCountryKeys = keys; // receives array of strings
};
```

#### Advanced Select Features

```hbs
{{! Single selection with advanced features }}
<Select
  @items={{this.countries}}
  @selectedKey={{this.selectedKey}}
  @onSelectionChange={{this.onChange}}
  @isFilterable={{true}}
  @isClearable={{true}}
  @isLoading={{this.isLoading}}
  @filter={{this.customFilter}}
  @popoverSize='lg'
>
  <:startContent>
    <SearchIcon />
  </:startContent>
  <:item as |item|>
    <item.Item @key={{item.key}}>
      <div class='flex items-center gap-2'>
        <img src={{item.flag}} alt='' class='w-5 h-5' />
        {{item.label}}
      </div>
    </item.Item>
  </:item>
  <:emptyContent>
    <div class='text-center p-4'>
      No countries found matching your search.
    </div>
  </:emptyContent>
</Select>
```

```js
// Handler for single selection
onChange = (key) => {
  this.selectedKey = key; // receives string | null
};
```

## New Components

### Form Component

The new Form component provides automatic form data extraction, validation, and handling. See the [Recommended Approach section](#recommended-approach-form--field-pattern) above for a complete example with validation.

### Switch Component

A new toggle/switch component not available in forms-legacy.

```hbs
{{! Controlled mode }}
<Switch
  @label='Enable notifications'
  @isSelected={{this.notificationsEnabled}}
  @onChange={{this.setNotificationsEnabled}}
>
  <:startContent>
    <NotificationIcon />
  </:startContent>
</Switch>

{{! Uncontrolled mode }}
<Switch
  @label='Enable notifications'
  @defaultSelected={{false}}
  @onChange={{this.setNotificationsEnabled}}
>
  <:startContent>
    <NotificationIcon />
  </:startContent>
</Switch>
```

### NativeSelect Component

For simple dropdown needs without the complexity of the full Select component.

```hbs
<NativeSelect
  @label='Priority'
  @selectedKeys={{this.selectedPriority}}
  @onSelectionChange={{this.setPriority}}
  @items={{this.priorityOptions}}
>
  <:item as |item|>
    <item.Option @key={{item.key}}>{{item.label}}</item.Option>
  </:item>
</NativeSelect>
```

## Common Patterns

### Error Handling

```hbs
{{! Before: Multiple error state props }}
<FormInput
  @errors={{this.errors}}
  @hasSubmitted={{this.hasSubmitted}}
  @showError={{this.forceShowErrors}}
/>

{{! After: Simplified approach }}
<Input @errors={{this.errors}} @isInvalid={{this.hasErrors}} />
```

### Custom Styling

```hbs
{{! Before: Individual class props }}
<FormInput
  @containerClass='my-container'
  @inputClass='my-input'
  @labelClass='my-label'
/>

{{! After: Classes object }}
<Input
  @classes={{hash base='my-container' input='my-input' label='my-label'}}
/>
```

For form validation patterns, see the [Migrating Validation](#migrating-validation) section above.

## Migration Checklist

### 1. Package Setup

- [ ] Uninstall `@frontile/forms-legacy`
- [ ] Install `frontile` and `@frontile/theme`
- [ ] Update `@frontile/theme` to compatible version
- [ ] Update imports to use named imports

### 2. Choose Your Migration Strategy

**Option A: Full Migration to Form + Field (Recommended)**

- [ ] Install validation library (`valibot` or `zod`)
- [ ] Define validation schemas for your forms
- [ ] Wrap forms with `<Form>` component
- [ ] Wrap fields with `<form.Field>` component
- [ ] Remove manual state management (`@tracked` properties)
- [ ] Update submit handlers to use `result.data`

**Option B: Component-Level Migration**

- [ ] Rename all `Form*` components (drop `Form` prefix)
- [ ] Update error handling props (remove `@hasSubmitted`, `@hasError`)
- [ ] Migrate `@hint` to `@description`
- [ ] Update CSS class props to `@classes` object
- [ ] **Radio**: Rename `@checked` to `@checkedValue`
- [ ] **Select**: Convert to key-based selection (see [Select Migration](#formselect--select))

### 3. Testing

- [ ] Test all form interactions
- [ ] Verify error states display correctly
- [ ] Test validation behavior
- [ ] Verify keyboard navigation and accessibility

### 4. Optional Enhancements

- [ ] Add `@isClearable` to appropriate inputs
- [ ] Use start/end content slots for icons or buttons
- [ ] Consider using `Switch` component for toggles
- [ ] Implement nested data patterns where beneficial

---

For detailed Form component documentation, see [frontile.dev/docs/forms/form](https://frontile.dev/docs/components/forms/form).

---

# Migrating from Changeset Form

Source: /docs/migrations/v0-18/changeset-form.md

# Migrating from Changeset Form

This guide covers migrating from the deprecated `@frontile/changeset-form` package to the modern `frontile` forms. We recommend the Form + Field pattern with Valibot validation, and also cover paths for teams that need to keep `ember-changeset` validation.

## Overview

The `@frontile/changeset-form` package is deprecated and will be removed in 0.19.0. This guide presents three migration paths based on your project's constraints and goals.

## Key Architectural Patterns

**Form + Field pattern** (Approach 1): Automatic data binding, validation, and state management via `<Form>` and `<form.Field>` components.

**Standalone components** (Approaches 2 & 3): Use form components directly with manual binding and validation integration.

See the [Form documentation](https://frontile.dev/docs/components/forms/form) for detailed architecture information.

## Migration Approach Overview

You have three main migration paths, **ordered by recommendation**:

| Approach                                | Validation | Components                           | Effort     | Tech Debt | Best For                                       |
| --------------------------------------- | ---------- | ------------------------------------ | ---------- | --------- | ---------------------------------------------- |
| **1. Modern Forms + Valibot**           | Valibot    | Form + Field pattern                 | Low-Medium | None      | New features, best long-term choice            |
| **2. Changeset + Modern Components**    | Changeset  | Standalone modern components         | Medium     | Medium    | Keep validation, modernize UI                  |
| **3. Changeset + Forms-Legacy**         | Changeset  | Legacy components                    | Medium     | High      | Large codebases needing gradual migration only |

**Recommendation:** choose Approach 1 (Modern Forms + Valibot) unless you have a specific constraint that requires changeset validation.

## Before You Start

Build the package you'll use: `pnpm --filter frontile build` (Approaches 1 & 2) or `pnpm --filter forms-legacy build` (Approach 3)

---

## Approach 1: Modern Forms + Valibot (Recommended)

Uses the modern Form + Field pattern with Valibot validation.

### When to Choose This Approach

- Starting new features or components — a clean break from legacy patterns
- Modernizing existing forms
- Want type-safe, TypeScript-first validation schemas
- Want simpler validation logic without changeset dependencies

### Step 1: Install Dependencies

```bash
# Remove old packages
npm uninstall @frontile/changeset-form @frontile/forms-legacy
npm uninstall ember-changeset ember-changeset-validations

# Install new packages
npm install frontile @frontile/theme valibot
```

### Step 2: Migrate to Form + Field Pattern

#### Before (changeset-form)

```hbs
{{#let (changeset this.model this.validations) as |changeset|}}
  <ChangesetForm @changeset={{changeset}} as |Form|>
    <Form.Input @fieldName='firstName' @label='First Name' />
    <Form.Textarea @fieldName='comments' @label='Comments' />
    <Form.Select
      @fieldName='country'
      @label='Country'
      @options={{this.countries}}
      as |option|
    >
      {{option}}
    </Form.Select>
    <Button @type='submit'>Save</Button>
  </ChangesetForm>
{{/let}}
```

#### After (Modern Forms + Valibot)

Complete GTS component with template:

```gts title="app/components/user-form.gts" 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 schema outside class (replaces changeset validations)
const UserFormSchema = v.object({
  user: v.object({
    firstName: v.pipe(v.string(), v.nonEmpty('Required')),
    email: v.pipe(v.string(), v.nonEmpty('Required'), v.email('Invalid'))
  }),
  country: v.pipe(
    v.fallback(v.string(), ''),  // Required for Select fields
    v.string(),
    v.nonEmpty('Please select a country')
  ),
  plan: v.pipe(
    v.fallback(v.string(), ''),
    v.string(),
    v.nonEmpty('Please select a plan')
  )
});

type UserFormSchema = v.InferOutput<typeof UserFormSchema>;

export default class UserFormComponent extends Component {
  @tracked formData: UserFormSchema = {
    user: { firstName: '', email: '' },
    country: '',
    plan: ''
  };

  countries = [
    { key: 'us', label: 'United States' },
    { key: 'ca', label: 'Canada' }
  ];

  handleChange = (result: FormResultData<UserFormSchema>) => {
    this.formData = result.data;
  };

  handleSubmit = async (result: FormResultData<UserFormSchema>) => {
    // Data is already validated
    await this.saveUser(result.data);
  };

  async saveUser(data: UserFormSchema) {
    // Your API call
  }

  <template>
    <Form
      @data={{this.formData}}
      @schema={{UserFormSchema}}
      @validateOn={{array "change" "submit"}}
      @onChange={{this.handleChange}}
      @onSubmit={{this.handleSubmit}}
      as |form|
    >
      {{! Nested data with dotted notation }}
      <form.Field @name="user.firstName" as |field|>
        <field.Input @label="First Name" />
      </form.Field>

      <form.Field @name="user.email" as |field|>
        <field.Input @type="email" @label="Email" />
      </form.Field>

      <form.Field @name="country" as |field|>
        <field.SingleSelect @label="Country" @items={{this.countries}} @allowEmpty={{true}} />
      </form.Field>

      <form.Field @name="plan" as |field|>
        <field.RadioGroup @label="Select Plan" as |Radio|>
          <Radio @label="Free" @value="free" />
          <Radio @label="Pro" @value="pro" />
        </field.RadioGroup>
      </form.Field>

      <Button @type="submit">Save</Button>
    </Form>
  </template>
}
```

For advanced features like dirty tracking, loading states, and validation timing control, see the [Form documentation](https://frontile.dev/docs/components/forms/form).

---

## Approach 2: Keep Changeset, Use Modern Components

This approach keeps ember-changeset validation while using modern `frontile` form components in **standalone mode** (without Form/Field wrappers).

**Important:** This approach uses modern form components (Input, Select, Switch, etc.) directly, NOT the Form or Field components. You maintain manual control over data binding and validation.

### When to Choose This Approach

- Complex changeset validation you don't want to rewrite
- Need modern UI features — slots, clearable, filtering, better accessibility
- Modernizing components now and validation later
- Team is familiar with changeset and wants to minimize the learning curve
- Willing to accept the extra boilerplate that manual binding requires

### Step 1: Install Modern Forms

```bash
npm uninstall @frontile/changeset-form
npm install frontile @frontile/theme
# Keep: ember-changeset ember-changeset-validations
```

### Step 2: Standalone Components with Changeset

Use modern components directly without Form/Field wrappers:

#### Before (changeset-form)

```hbs
{{#let (changeset this.model this.validations) as |changeset|}}
  <ChangesetForm @changeset={{changeset}} as |Form|>
    <Form.Input @fieldName='firstName' @label='First Name' />

    <Form.Select
      @fieldName='country'
      @label='Country'
      @options={{this.countries}}
      @isMultiple={{true}}
      as |option|
    >
      {{option}}
    </Form.Select>

    <Button @type='submit'>Save</Button>
  </ChangesetForm>
{{/let}}
```

#### After (Changeset + Modern Components Standalone)

```hbs
{{#let (changeset this.model this.validations) as |changeset|}}
  <form {{on 'submit' (fn this.handleSubmit changeset)}}>
    {{! Manual binding required for standalone components }}
    <Input
      @label="First Name"
      @value={{get changeset 'firstName'}}
      @onChange={{fn this.updateField changeset 'firstName'}}
      @errors={{this.getFieldErrors changeset 'firstName'}}
    />

    {{! Key-based Select (not object-based!) }}
    <Select
      @label="Country"
      @items={{this.countries}}
      @selectedKey={{this.getSelectedCountry changeset}}
      @onSelectionChange={{fn this.updateCountry changeset}}
      @allowEmpty={{true}}
      @errors={{this.getFieldErrors changeset 'country'}}
    >
      <:item as |item|>
        <item.Item @key={{item.key}}>{{item.label}}</item.Item>
      </:item>
    </Select>

    {{! Radio uses @checkedValue, not @checked }}
    <Radio
      @label="Free"
      @value="free"
      @checkedValue={{get changeset 'plan'}}
      @onChange={{fn this.updateField changeset 'plan'}}
    />
    <Radio
      @label="Pro"
      @value="pro"
      @checkedValue={{get changeset 'plan'}}
      @onChange={{fn this.updateField changeset 'plan'}}
    />

    <Button @type="submit">Save</Button>
  </form>
{{/let}}
```

### Step 3: Component Class

Key changes: manual binding and Select key-based selection.

```typescript
import Component from '@glimmer/component';
import { tracked } from '@glimmer/tracking';
import { action } from '@ember/object';

export default class ChangesetFormComponent extends Component {
  @tracked hasSubmitted = false;

  // Keep existing changeset validations
  validations = {
    firstName: validatePresence(true),
    country: validatePresence(true),
    plan: validatePresence(true)
  };

  countries = [
    { key: 'us', label: 'United States' },
    { key: 'ca', label: 'Canada' }
  ];

  @action
  updateField(changeset, fieldName, value) {
    changeset.set(fieldName, value);
    changeset.validate(fieldName);
  }

  // Select components use keys, need conversion for changeset
  @action
  updateCountry(changeset, selectedKey) {
    changeset.set('country', selectedKey);
    changeset.validate('country');
  }

  getSelectedCountry(changeset) {
    return changeset.get('country') || null;
  }

  @action
  async handleSubmit(changeset, event) {
    event.preventDefault();
    await changeset.validate();
    this.hasSubmitted = true;

    if (changeset.isValid) {
      await changeset.save({});
    }
  }

  getFieldErrors(changeset, fieldName) {
    if (!this.hasSubmitted) return [];
    return changeset.errors
      .filter(e => e.key === fieldName)
      .map(e => e.validation)
      .flat();
  }
}
```

---

## Approach 3: Keep Changeset, Use Forms-Legacy

This is the minimal-effort approach for large codebases that need gradual migration. It keeps changeset validation while using legacy form components.

**Warning:** this approach carries the most technical debt of the three, and should only be chosen when time or resource constraints rule out the other two.

### When to Choose This Approach

- Very large codebase — hundreds of forms to migrate
- Limited development resources, need the smallest possible effort now
- Extensive custom changeset validation logic
- A short-term solution you plan to revisit later, accepting the technical debt as a stopgap

### Step 1: Install Forms-Legacy

```bash
npm uninstall @frontile/changeset-form
npm install @frontile/forms-legacy
# Keep: ember-changeset ember-changeset-validations

# Build the package
pnpm --filter forms-legacy build
```

### Step 2: Key Changes

Replace `ChangesetForm` wrapper with manual changeset binding to `@frontile/forms-legacy` components:

```hbs
{{! Before }}
<ChangesetForm @changeset={{changeset}} as |Form|>
  <Form.Input @fieldName='firstName' @label='First Name' />
</ChangesetForm>

{{! After }}
<form {{on 'submit' (fn this.handleSubmit changeset)}}>
  <FormInput
    @label='First Name'
    @value={{get changeset 'firstName'}}
    @onInput={{fn this.updateField changeset 'firstName'}}
    @errors={{this.getFieldErrors changeset 'firstName'}}
    @hasSubmitted={{this.hasSubmitted}}
  />
</form>
```

See the [Forms Legacy Migration Guide](forms-legacy.md) for complete component mappings and detailed migration steps.

**Recommendation:** Plan to migrate to Approach 1 when resources allow.

---

## Common Gotchas

Key API changes when migrating to modern forms:

### 1. Radio: `@checked` → `@checkedValue`

```hbs
{{! Legacy }}
<FormRadio @checked={{this.plan}} @value="free" />

{{! Modern }}
<Radio @checkedValue={{this.plan}} @value="free" />
```

In Approach 1, use `field.RadioGroup` which handles this automatically.

### 2. Select: Object-Based → Key-Based

```hbs
{{! Legacy (object selection) }}
<FormSelect @selected={{this.countryObject}} />

{{! Modern (key selection) }}
<Select @selectedKey="us" />  {{! Just the key string }}
```

Modern Select components use string keys instead of full objects. Add `v.fallback(v.string(), '')` to validation schemas for Select fields.

### 3. Form + Field vs Standalone

**Approach 1** uses Form + Field: `<form.Field @name="email" as |field|><field.Input /></form.Field>`

**Approaches 2 & 3** use standalone components with manual binding: `<Input @value={{this.email}} @onChange={{this.setEmail}} />`

Don't mix these patterns in the same form.

---

## Additional Resources

- [Form documentation](https://frontile.dev/docs/components/forms/form) - Complete Form + Field pattern guide
- [Forms Legacy Migration Guide](forms-legacy.md) - Component-specific migration details
- [Valibot documentation](https://valibot.dev/) - Validation schema reference

---

# DOM Anatomy Attributes Migration

Source: /docs/migrations/v0-18/anatomy-attributes.md

# DOM Anatomy Attributes Migration Guide

v0.18 gives every Frontile component a stable, documented DOM anatomy: two
attributes, `data-component` and `data-part`, replace three older and
inconsistent conventions — ad hoc `data-component` values that didn't match
any real hierarchy, one-off `data-fr-*` attributes on `Accordion`, and most of
the `data-test-id` attributes that existed purely as selectors.

**See also:** [Customizing Component Styles](../../theming/component-styles.md)
for the full contract — what the two attributes mean, how scoping works, and
its known limitation with nested components.

## Impact

**Required only if you select Frontile-rendered elements** — in your own
CSS, in `querySelector`/`closest` calls, or in tests — using any of the
retired attributes below. If you only pass `@classes`/`@class` or use
components through their public API, nothing changes for you.

## `data-component` renames

Several elements carried a `data-component` value that named something other
than the actual `tv()` config, or that belonged on an element that isn't a
real anatomy root. Each now carries the correct `data-component` (the
kebab-cased `tv()` config name, on the component's outermost element) plus a
`data-part` for the slot it renders, if any.

| Component | Old | New |
| --- | --- | --- |
| Alert | `data-component="alert"` (unchanged) + `data-test-id="alert"` | `data-component="alert"` `data-part="base"` |
| Autocomplete trigger `<input>` | `data-component="autocomplete-trigger"` + `data-test-id="trigger"` | `data-part="input"` (Autocomplete's own `input` slot; the trigger is not a separate component) |
| Checkbox `<input>` | `data-component="checkbox"` (on the `<input>`) | `data-component="checkbox"` moves to Checkbox's root; the `<input>` becomes `data-part="input"` |
| Command | `data-test-id="command"` alongside `data-component="command"` | `data-component="command"` `data-part="base"` |
| Command Dialog | `data-test-id="command-dialog"` | `data-component="command-dialog"` `data-part="base"` |
| Command Dialog panel | `data-test-id="command-dialog-panel"` | `data-part="panel"` |
| Command Footer | `data-component="command-footer"` + `data-test-id="command-footer"` | `data-part="footer"` (a part of `command`, not its own component) |
| Command Input | `data-component="command-input"` + `data-test-id="command-input"` | `data-part="input"` |
| FormControl live region | `data-component="form-feedback-live-region"` | `data-test-id="form-feedback-live-region"` (demoted — see [Kept as `data-test-id`](#kept-as-data-test-id) below) |
| Input `<input>` | `data-component="input"` (on the `<input>`) | `data-component="input"` moves to Input's root (the `FormControl` wrapper); the `<input>` becomes `data-part="input"` |
| InputOtp container | `data-component="input-otp"` (on the container `<div>`) | `data-component="input-otp"` moves to the root; the container becomes `data-part="container"` |
| InputOtp `<input>` | `data-component="input-otp-input"` | `data-part="input"` |
| NativeSelect `<select>` | `data-component="native-select"` | `data-component="native-select"` moves to NativeSelect's root (the `FormControl` wrapper); the `<select>` becomes `data-part="input"` (it keeps `data-test-id="native-select"` too — see [Kept](#kept-as-data-test-id)) |
| Radio `<input>` | `data-component="radio"` (on the `<input>`) | `data-component="radio"` moves to Radio's root; the `<input>` becomes `data-part="input"` |
| Select trigger | `data-component="select-trigger"` + `data-test-id="trigger"` | `data-part="input"` (Select's own `input` slot, not a separate component) |
| Switch | `data-component="switch"` | `data-component="switch-input"` (renamed to match the `switchInput` `tv()` config) `data-part="base"` |
| Table wrapper | `data-component="table-wrapper"` | `data-component="table"` `data-part="wrapper"` |
| Table toolbar | `data-component="table-toolbar"` (plain class, no `tv()` styling) | `data-part="toolbar"` (now themed via a real `toolbar` slot — see [Table's `toolbar` slot](#tables-toolbar-slot)) |
| Table `<table>` (composed via `SimpleTable`) | `data-component="table"` unconditionally | `data-component="table"` only when `SimpleTable` is the anatomy root (`@isRoot` true, the default); `Table` passes `@isRoot={{false}}` since its own wrapper is the real root — see [Customizing Component Styles](../../theming/component-styles.md#known-limitation-a-nested-component-can-share-a-part-name) |
| Textarea `<textarea>` | `data-component="textarea"` (on the `<textarea>`) | `data-component="textarea"` moves to Textarea's root; the `<textarea>` becomes `data-part="input"` |
| SimpleTable body/cell/column/footer/header/row | `data-component="table-body"`, `"table-cell"`, `"table-column"`, `"table-footer"`, `"table-header"`, `"table-row"` | No `data-component` — these are parts of `table`: `data-part="tbody"`, `"td"`, `"th"`, `"tfoot"`, `"thead"`, `"tr"` respectively |

## `data-fr-*` retirement

Every `data-fr-*` attribute on `Accordion` is gone, replaced by
`data-component`/`data-part`. `data-fr-si-ready` is the one exception —
it is **not** an anatomy attribute; it's a lifecycle marker written by the
[selection-indicator](https://frontile.dev/docs/components/utilities/selection-indicator)
utility (used by `SegmentedControl`, `TabNav`, `Tabs`) to signal that the
indicator has measured and is ready to transition, and it was deliberately
kept as-is.

| Old | New |
| --- | --- |
| `data-fr-accordion` | `data-component="accordion"` `data-part="base"` |
| `data-fr-accordion-trigger` | `data-part="trigger"` |
| `data-fr-si-ready` | **Kept, unchanged** — not an anatomy attribute |

## Removed `data-test-id`s and their replacements

Most `data-test-id` attributes that existed only to name a piece of a
component's anatomy are gone; select by `data-part` (scoped under the
component's `data-component`) instead. A handful of valued `data-test-*`
attributes that carry real state (not just an anatomy label) were
deliberately left alone — e.g. `data-test-intent` on `Alert`.

| Old `data-test-id` | New |
| --- | --- |
| `alert` | `data-component="alert"` |
| `alert-actions` | `data-part="actions"` |
| `alert-close-button` | `data-part="close-button"` |
| `alert-content` | `data-part="content"` |
| `alert-description` | `data-part="description"` |
| `alert-icon` | `data-part="icon"` |
| `alert-title` | `data-part="title"` |
| `command` | `data-component="command"` |
| `command-dialog` | `data-component="command-dialog"` |
| `command-dialog-panel` | `data-part="panel"` |
| `command-empty` | `data-part="empty"` |
| `command-footer` | `data-part="footer"` |
| `command-hint` | `data-part="footer-hint"` |
| `command-input` | `data-part="input"` |
| `command-input-wrapper` | `data-part="input-wrapper"` |
| `command-kbd` | `data-part="kbd"` |
| `command-list` | `data-part="list"` |
| `command-loading` | `data-part="loading"` |
| `command-prompt` | `data-part="empty"` |
| `divider` | `data-component="divider"` |
| `empty-content` | `data-part="empty-content"` (on Select's and Autocomplete's "no results" element) |
| `external-link` | `data-component="external-link"` |
| `external-link-icon` | `data-part="icon"` |
| `input-clear-button` | `data-part="clear-button"` |
| `input-end-content` | `data-part="end-content"` |
| `input-otp-caret` | `data-part="caret"` |
| `input-otp-cell` | `data-part="cell"` |
| `input-otp-separator` | `data-part="separator"` |
| `input-start-content` | `data-part="start-content"` |
| `kbd` | `data-component="kbd"` |
| `kbd-key` | `data-part="key"` |
| `kbd-separator` | `data-part="separator"` |
| `listbox` | `data-component="listbox"` |
| `listbox-group` | `data-component="listbox-group"` |
| `listbox-group-title` | `data-part="title"` |
| `listbox-item` | `data-component="listbox-item"` |
| `listbox-item-description` | `data-part="description"` |
| `listbox-item-label` | `data-part="label"` |
| `listbox-item-selected-icon` | `data-part="selected-icon"` |
| `listbox-item-submenu-indicator` | `data-part="submenu-indicator"` |
| `loading-spinner` | `data-component="spinner"` (Spinner already carries its own root `data-component`; the wrapping `data-test-id` was redundant) |
| `option` | *(removed, no replacement — `NativeSelectItem`'s `<option>` has no styled part of its own)* |
| `search-message` | `data-part="empty-content"` |
| `selected-chip` | `data-part="chip"` |
| `selected-chips` | `data-part="chips-container"` |
| `switch-end-content` | `data-part="end-content"` |
| `switch-start-content` | `data-part="start-content"` |
| `switch-thumb-content` | `data-part="thumb"` |
| `table` | `data-component="table"` (on the `<table>` when it is the anatomy root) |
| `table-body` | `data-part="tbody"` |
| `table-cell` | `data-part="td"` |
| `table-column` | `data-part="th"` |
| `table-empty-cell` | `data-part="empty"` |
| `table-footer` | `data-part="tfoot"` |
| `table-header` | `data-part="thead"` |
| `table-row` | `data-part="tr"` |
| `table-skeleton-row` | `data-part="skeleton-row"` |
| `trigger` | `data-part="input"` (on both `Autocomplete` and `Select` triggers) |

### Kept as `data-test-id`

Two attributes moved in the *opposite* direction — from `data-component` to
`data-test-id` — because they don't name a real anatomy root:

- **`FormControl`'s live region**: was `data-component="form-feedback-live-region"`,
  is now `data-test-id="form-feedback-live-region"`. The live region is an
  implementation detail of `FormControl`'s error announcing, not a themed
  slot or a component of its own.
- **`NativeSelect`'s `<select>`**: keeps `data-test-id="native-select"` (it
  already had this) as its stable selector, since `data-component="native-select"`
  now lives on the outer `FormControl` root, one level up — the `<select>`
  itself is `data-part="input"`. `frontile/test-support`'s `changeOption`
  helper was updated to select by `data-test-id="native-select"` rather than
  the old `data-component="native-select"`.

## Table's `@classes.base` key removed

`Table`'s `tv()` config (`packages/theme/src/components/table.ts`) no longer
has a `base` slot. It was dead: no element ever called `.base()` or rendered
a `base` part, so a `@classes={{hash base='...'}}` override was silently
doing nothing. If your app passed `@classes.base` to `Table`, remove it —
there is no behavior to preserve, and no other slot inherits its styles.

## Table's `toolbar` slot

The `<:toolbar>` block's wrapping `<div>` used to carry a hardcoded class
string (`class="table-toolbar px-4 pt-3"`) and `data-component="table-toolbar"`,
outside the `tv()` system entirely. It is now a real `toolbar` slot —
themeable via `@classes={{hash toolbar='...'}}` the same way `wrapper` and
`table` are — and the element carries `data-part="toolbar"` instead of its
own `data-component`.

## Checklist

- [ ] Replaced any selector on a retired `data-fr-*` attribute with the
      matching `[data-part="..."]` (see table above)
- [ ] Replaced any selector on a retired `data-test-id` with the matching
      `[data-component="..."]` / `[data-part="..."]` pair
- [ ] Replaced `data-component="table-wrapper"`, `"table-body"`,
      `"table-cell"`, `"table-column"`, `"table-footer"`, `"table-header"`,
      `"table-row"` and `"table-toolbar"` selectors — none of these
      `data-component` values exist anymore; they're all parts of `table`
      now
- [ ] Removed any `@classes.base` passed to `Table` — it was already a no-op
- [ ] If selecting `Switch`'s root by `data-component`, updated
      `"switch"` → `"switch-input"`
- [ ] Read [Customizing Component Styles](../../theming/component-styles.md)
      for the full `data-component`/`data-part` contract, including its
      "nearest ancestor" scoping limitation

---

# Component API Naming Migration

Source: /docs/migrations/v0-18/component-api-naming.md

# Component API Naming Migration Guide

v0.18 renames **both** of Frontile's styling axes onto the vocabulary the wider
ecosystem uses. They ship together, so migrate them together.

| Axis                | Before        | After                                                            |
| ------------------- | ------------- | ---------------------------------------------------------------- |
| How it is **drawn** | `@appearance` | `@variant`                                                       |
| What it **means**   | `@intent`     | `@color` — or `@status` on Alert, NotificationCard, FormFeedback |

## The two axes

`@variant` controls how a component is drawn — filled, tinted, bordered, or
bare:

```
solid | soft | subtle | outline | ghost | plain
```

`@color` controls which semantic color it uses:

```
neutral | primary | secondary | tertiary | success | warning | danger
```

### Why three components use `@status` instead of `@color`

**`@color` is decoration. `@status` is meaning.**

On most components the value only picks a color — a `danger` Button is a red
Button. On three components it also decides what a screen reader does:

| Component          | The value also selects                                       |
| ------------------ | ------------------------------------------------------------ |
| `Alert`            | the icon, and the ARIA role (`status` vs `alert`)            |
| `NotificationCard` | the icon, the ARIA role, and the action button's color       |
| `FormFeedback`     | whether the message is announced **assertively or politely** |

Naming that `@color` would mean a prop named for decoration silently deciding
whether a screen reader interrupts the user. Those three take `@status`:

```
neutral | primary | success | warning | danger
```

## Value renames

`default` becomes **`neutral`** on every color axis — the palette category has
always been called `neutral`.

```hbs
{{! before }}
<Button @intent='default'>Cancel</Button>

{{! after }}
<Button @color='neutral'>Cancel</Button>
```

On `Alert` and `NotificationCard`, `info` becomes **`primary`**. It was already
a pure alias, painting `primary`'s classes and differing only in the default
glyph, which stays attached to `primary`.

## Upgrading from v0.17

These components had a stable axis in v0.17.1. The old spelling still works in
all of 0.18.x: it maps to the new value and logs a deprecation warning. It is
removed in v0.19.0.

| Component                                  | `@appearance` → `@variant`                                                         | `@intent` → `@color`/`@status` |
| ------------------------------------------ | ---------------------------------------------------------------------------------- | ------------------------------ |
| Button / ButtonGroup / ToggleButton        | `default \| outlined \| minimal \| custom` → `solid \| outline \| plain \| custom` | `@color`                       |
| Chip                                       | `default \| outlined \| faded` → `solid \| outline \| soft`                        | `@color`                       |
| Listbox / Dropdown / Select / Autocomplete | `default \| outlined \| faded` → `solid \| outline \| subtle`                      | `@color`                       |
| CloseButton                                | `transparent \| subtle` → `ghost \| soft` (prop was already `@variant`)            | —                              |
| Spinner, ProgressBar, Switch               | —                                                                                  | `@color`                       |
| FormFeedback                               | —                                                                                  | **`@status`**                  |

Notes:

- Chip's `faded` becomes `soft` (a borderless tint). Listbox's `faded` becomes
  `subtle` (a tint **with** a border). Same old name, different treatments —
  do not assume one map applies to both.
- `@appearance="custom"` on Button keeps its name and passes through unchanged.
- Select, Dropdown, and Autocomplete forward both axes to the Listbox they
  render internally. Pass the new prop at whichever level you set the old one.

### Example

```gts
{{! Before }}
<Button @appearance='outlined' @intent='danger'>Delete</Button>
<Chip @appearance='faded' @intent='default'>Draft</Chip>

{{! After }}
<Button @variant='outline' @color='danger'>Delete</Button>
<Chip @variant='soft' @color='neutral'>Draft</Chip>
```

### Deprecation ids

Silence them individually while you migrate if you need to:

```
frontile.button.appearance        frontile.button.intent
frontile.button-group.appearance  frontile.button-group.intent
frontile.toggle-button.appearance frontile.toggle-button.intent
frontile.chip.appearance          frontile.chip.intent
frontile.listbox.appearance       frontile.listbox.intent
frontile.dropdown.appearance      frontile.dropdown.intent
frontile.select.appearance        frontile.select.intent
frontile.autocomplete.appearance  frontile.autocomplete.intent
frontile.close-button.variant-values
frontile.spinner.intent           frontile.progress-bar.intent
frontile.switch.intent            frontile.form-feedback.intent
```

## Upgrading from a v0.18 pre-release

> **`@appearance="soft"` on Button changes meaning rather than breaking.** It
> used to be a tint **with** a border; `@variant="soft"` is a tint **without**
> one. `soft` is still a valid value, so nothing catches this — not Glint, not
> a runtime assertion, not a test that only asserts a class is present. If you
> used `@appearance="soft"`, you want `@variant="subtle"`.

The components and values in this section were added during the 0.18
alpha/beta cycle and never shipped in a stable release. There is nothing to
deprecate them from, so **renaming them produces no runtime warning** — this
guide is the only signal you get. Everything else here fails loudly: the old
spelling leaves the type union, so Glint rejects it at build time.

| Component                                                          | Pre-release                                  | v0.18 final                                                            |
| ------------------------------------------------------------------ | -------------------------------------------- | ---------------------------------------------------------------------- |
| Kbd                                                                | `@appearance="default \| outlined \| faded"` | `@variant="solid \| outline \| subtle"` (`inherit`, `plain` unchanged) |
| Accordion                                                          | `@variant="outlined \| faded"`               | `@variant="separated \| soft"` (`ghost`, `enclosed` unchanged)         |
| Drawer                                                             | `@appearance="default \| ghost"`             | `@variant="sectioned \| flat"`                                         |
| Alert / NotificationCard                                           | `@variant="default \| tonal"`                | `@variant="surface \| soft"` (`solid` unchanged)                       |
| Alert / NotificationCard                                           | `@intent="default \| info"`                  | `@status="neutral \| primary"`                                         |
| Calendar, Kbd, Pagination, SegmentedControl, Tabs, TabNav, Tooltip | `@intent`                                    | `@color`                                                               |
| Button                                                             | `@appearance="soft"`                         | `@variant="subtle"`                                                    |
| Button                                                             | `@appearance="tonal"`                        | `@variant="soft"`                                                      |

### The notifications service option

The notification `intent:` option was also added during the 0.18 cycle. It is
now `status:`:

```js
this.notifications.add('Saved', { status: 'success' });
```

`NotificationIntent` is renamed `NotificationStatus`.

The older `appearance:` option — which _did_ ship in v0.17 — still works and
still warns, but its advice now names `status` directly rather than routing you
through `intent`. `error` continues to map onto `danger`.

## Mixing the axes across levels

`Listbox` forwards its value down to its items, and an item's own arg wins. But
mixing the old and new names across those two levels does **not** behave as you
might hope:

```hbs
{{! the listbox-level @color wins — the item renders primary, not danger }}
<Listbox @color='primary' as |l|>
  <l.Item @intent='danger'>…</l.Item>
</Listbox>
```

The inherited value arrives as the new arg, and the new arg takes precedence
over the deprecated one. `@variant`/`@appearance` behaves the same way.

**Migrate a `Listbox` and its items together** and this never arises.

## Need help?

- [Upgrading to v0.18](./index.md) for the full list of 0.18 breaking changes
- Search or open an issue on [GitHub](https://github.com/josemarluedke/frontile)

---

# Releases

Source: /docs/releases/index.md

# Releases

This section covers notable Frontile releases: what changed, what it means for
your app, and where to look for the details. Each page favors highlights and,
where it helps, live demos over an exhaustive PR list.

- **[v0.18](./v0.18.md)** — the largest release in the project's history: fourteen
  new components, a rebuilt OKLCH-based design system, and a single consolidated
  `frontile` package.
- **[v0.17](./v0.17.md)** — Table, Avatar, Switch, filterable Select, Portal, and the
  move to Tailwind CSS v4.
- **[v0.16](./v0.16.md)** — the Addon V2 + Glint + template tag migration that moved
  every package onto Ember's modern addon format.

For the complete history, including older versions and patch releases, see the
[GitHub releases page](https://github.com/josemarluedke/frontile/releases).

---

# v0.18

Source: /docs/releases/v0-18.md

# Frontile v0.18

Ten months, 27 prereleases, and roughly two hundred merged pull requests after
v0.17.1. This is the largest release Frontile has had, and the one where the
library's shape settles.

## Why this took a while

The gap was deliberate.

Frontile had accumulated a set of changes that could not be made gently:
the color system, the way themes are configured, the package layout, the
naming of component arguments, and the DOM that components render. Every one
of them was breaking. Spread across five releases, they would have been five
migrations, five rounds of upgrade work. Batched into one, they are a single
migration you do once.

So v0.18 took the whole cost up front. What comes out the other side is a
design system with a coherent vocabulary, a single package instead of eight,
and component APIs that are named consistently enough that you can guess them.

None of it was developed in the dark. Those 27 prereleases — 21 alphas and 6
betas — go back to `0.18.0-alpha.0` in February 2026, each published and
installable.

**And it has been running in production.** Multiple applications at
[Underline](https://underline.com) have tracked the prerelease line for several
months, so these APIs have already survived real use.

## New components

Fourteen of them. Every demo below is live.

### DatePicker

A date field combining a text trigger with a Calendar popover, for single dates
or ranges. [Docs →](https://frontile.dev/docs/components/forms/date-picker)

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

<template>
  <div class='demo-stack'>
    <DatePicker @label='Start date' @placeholder='Pick a date' />
  </div>
</template>
```

### Calendar

The month grid on its own: keyboard navigable, localized through `Intl`, and
composable into your own pickers.
[Docs →](https://frontile.dev/docs/components/collections/calendar)

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

const today = new Date();

<template><Calendar @defaultValue={{today}} /></template>
```

### Command

A searchable, relevance-ranked command palette. Use it inline, as below, or as
`CommandDialog` for the ⌘K treatment.
[Docs →](https://frontile.dev/docs/components/collections/command)

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

const commands = [
  { key: 'profile', label: 'Profile' },
  { key: 'billing', label: 'Billing' },
  { key: 'settings', label: 'Settings' }
];

<template>
  <Command @items={{commands}} @isBordered={{true}} @placeholder='Type a command…' as |c|>
    <c.Input />
    <c.List>
      <:item as |ctx|>
        <ctx.Item @key={{ctx.key}}>{{ctx.label}}</ctx.Item>
      </:item>
    </c.List>
  </Command>
</template>
```

### Autocomplete

A text input that filters and ranks as you type. It matches substrings and
acronyms both. Type `nz` and New Zealand comes up.
[Docs →](https://frontile.dev/docs/components/forms/autocomplete)

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

const countries = [
  'Brazil',
  'Canada',
  'Japan',
  'Netherlands',
  'New Zealand',
  'United Kingdom'
];

<template>
  <div class='demo-stack'>
    <Autocomplete @placeholder='Search countries' @items={{countries}} />
  </div>
</template>
```

### Accordion

Collapsible sections for progressive disclosure.
[Docs →](https://frontile.dev/docs/components/disclosure/accordion)

```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>
    </Accordion>
  </div>
</template>
```

### Tabs

Panels shown one at a time, with an indicator that slides between them.
[Docs →](https://frontile.dev/docs/components/navigation/tabs)

```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>
```

### TabNav

Tabs' appearance, but built for real navigation: genuine links, `aria-current`,
each one individually tabbable.
[Docs →](https://frontile.dev/docs/components/navigation/tab-nav)

```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>
```

### Tooltip

A short hint on hover or focus, built on a reworked Popover hover foundation.
[Docs →](https://frontile.dev/docs/components/overlays/tooltip)

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

<template>
  <Tooltip @content='Add to library' as |t|>
    <Button {{t.trigger}}>Add</Button>
  </Tooltip>
</template>
```

### Alert

A persistent, inline message, rather than a notification that comes and goes.
Also available as a full-width banner layout.
[Docs →](https://frontile.dev/docs/components/status/alert)

```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>
```

### Breadcrumbs

Where the current page sits in a hierarchy.
[Docs →](https://frontile.dev/docs/components/navigation/breadcrumbs)

```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>
```

### Pagination

Page chips, previous/next, an optional summary. The simplest case needs only
`@total`. [Docs →](https://frontile.dev/docs/components/navigation/pagination)

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

<template><Pagination @total={{120}} /></template>
```

### SegmentedControl

Mutually exclusive options with a sliding indicator, for small fixed choices.
[Docs →](https://frontile.dev/docs/components/buttons/segmented-control)

```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>
```

### Skeleton

A placeholder that hints at the shape of what's loading.
[Docs →](https://frontile.dev/docs/components/utilities/skeleton)

```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>
```

### ExternalLink

A link that marks itself as external: icon, `rel="noopener noreferrer"`, and
hidden text announcing the new tab.
[Docs →](https://frontile.dev/docs/components/navigation/external-link)

```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>
```

## Components that got better

**Dropdown gained nested submenus**, with the keyboard and pointer behavior
that implies.

**Drawer was restyled and learned to drag closed.** Grab it and throw it off
the edge.

**Select renders multiple selections as chips.** They used to be a comma-joined
string inside the trigger; now each is a removable
[Chip](https://frontile.dev/docs/components/buttons/chip), so a user can drop
one without reopening the dropdown. Opt back out with
`@selectedItemsDisplay='text'`.

**Listbox gained groups, and filtering is ranked by relevance.** `Autocomplete`
and filterable `Select` used to filter with a case-insensitive "contains" check
and render survivors in source order. They now score each option and put the
closest match first, and match acronyms. Nothing that matched before stops
matching. See [Filter Ranking](../migrations/v0.18/filter-ranking.md).

**Table** moved its keyboard navigation onto the shared `rovingFocus` utility,
gained opt-in skeleton rows via `@skeletonRows`, and now yields its rendered
columns and cell components to body blocks.

**Button has `@isLoading`.**

**Notifications were redesigned**: opaque surfaces, proper stacking, and
promise support, so a toast can follow an async operation through pending,
resolved and rejected without you wiring it.

**Overlays that render already open now animate**, after first paint, instead of
appearing fully formed.

**Divider gained a `sketch` variant**, a hand-drawn rule that recolors with the
standard `bg-*` utilities.

```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>
```

## The design system

The visual foundation was rebuilt.

**Colors are semantic, not numbered.** The old `primary-500` style scale is
gone. Colors are now categories — `neutral`, `primary`, `secondary`,
`tertiary`, `success`, `warning`, `danger`, and the `surface-*` family — each
with named levels that run from `subtle` through `muted`, `soft`, `mild`,
DEFAULT, `firm`, `strong`, to `bolder`. `bg-primary` is the resting fill;
`bg-primary-firm` is the emphatic one. You pick by intent rather than by
memorizing which number meant "hover".

**Contrast text is automatic.** `text-on-primary-firm` resolves to whichever of
black or white meets WCAG contrast on that background, generated rather than
hand-maintained.

**Colors moved to OKLCH**, which makes the levels perceptually even in a way
HSL never managed. This is invisible in your code: you may notice small
differences in rendered color, but there is nothing to change.

**`theme-inverse` flips a subtree.** Every token is emitted for both schemes, so
adding `.theme-inverse` to an element re-resolves the entire palette to the
opposite scheme inside it. Dark panels on light pages stop being a hand-built
special case.

**Radius derives from one knob.** The whole border-radius scale is computed from
a single `--radius` variable.

**The typography scale was corrected.** The `--text-body-*` tokens had been
mapped to the wrong steps of the modular scale: `md` was shipping at 20.74px
where the spec said 16px. They now match, and the scale gained `4xs`, `5xs`,
`2xl` and `3xl` to fill it out.

## Theming and developer experience

**One package.** The seven `@frontile/*` component packages — buttons,
collections, forms, overlays, notifications, status, utilities — are now a
single `frontile` package, organized internally by category. The old packages
still re-export everything and only log a deprecation warning, so your existing
imports keep working throughout 0.18.x.

**CSS-first configuration.** Theme configuration moved to Tailwind v4's CSS-native
approach. Frontile's styles now arrive through `@import "@frontile/theme"` in
your `app.css`.

**A stable DOM anatomy.** Every component renders `data-component` and
`data-part` attributes, giving you a documented, stable way to target internals
from your own CSS or tests. The ad-hoc `data-fr-*` attributes are gone, and the
`data-test-id` attributes that existed only as anatomy selectors went with them.

**Consistent argument naming.** `@appearance` became `@variant`, with one shared
vocabulary across components: `solid`, `soft`, `subtle`, `outline`, `ghost`,
`plain`. `@intent` became `@color`, or `@status` on `Alert`,
`NotificationCard` and `FormFeedback`, the three where the value also picks an
icon, an ARIA role, or whether a message is announced assertively. `default`
became `neutral` throughout. The old names still work through 0.18.x with a
deprecation warning.

**Glint v2.** The whole repo moved to `@glint/ember-tsc`.

## Documentation, and the tool that builds it

The docs site was rebuilt, and a meaningful share of that work went into
[Docfy](https://github.com/josemarluedke/docfy) — the static site generator
behind frontile.dev — rather than into Frontile.

Three upstream Docfy releases landed capabilities these docs needed:

- **v0.12.0 — static Markdown export.** Every page now has a `.md` mirror,
  alongside generated `llms.txt` and `llms-full.txt`. The documentation is
  readable without running JavaScript, which matters for agents and for anyone
  reading from a terminal.
- **v0.14.0 — a Shiki code-block pipeline.** Real `glimmer-js` and
  `glimmer-ts` TextMate grammars, so `.gts` and `.gjs` fences highlight
  properly instead of being approximated. It replaced three separate
  in-repo highlighters, and brought copy buttons, titles, collapsing and line
  highlighting with it.
- **v0.14.2 — richer `llms.txt`.** Per-entry descriptions, project framing, and
  topic-scoped bundles, so an agent fetching the index gets something
  navigable rather than a flat list of URLs.

Each was built and verified against a real build of these docs before shipping.

On top of that, the site keeps a few local Docfy plugins for things only
Frontile needs: one resolves `<Signature />` tags into real argument tables in
the exported Markdown, another maps a maintained component inventory onto page
descriptions, and a hand-written preamble supplies the framing an automated
export cannot generate: what Frontile is for, and which older argument names
still silently resolve. The **Copy Page** controls on every docs page are local
UI built on the exported URLs.

None of it required forking Docfy. The local pieces stayed thin and the heavy
lifting went upstream, where other projects get it too.

### For AI agents

Frontile now ships an installable agent skill. In a project that depends on
Frontile, `npx skills add josemarluedke/frontile` gives a coding agent the
component vocabulary, the semantic color system, and the `@intent`/`@appearance`
rename, so it writes current Frontile rather than what it remembers from
training data.

## Breaking changes

There are a lot. The [v0.18 migration guide](../migrations/v0.18/index.md)
covers each one and orders the work so that each step is verifiable before the
next one begins.

**Several of these changes fail silently.** A Tailwind class that no longer
resolves produces no error, no warning, and no CSS; the element renders without
the style you asked for. Frontile's own documentation shipped thirteen demos with unresolvable
background classes during this cycle, and nobody noticed until a linter went
looking. Budget time for looking at the running app, not only at the diff.

## What's next: v0.19

**v0.19 is a cleanup release, and it is coming soon.**

Its purpose is to remove what v0.18 deprecated, so the project stops carrying
two of everything. It will remove:

- `@frontile/forms-legacy` and `@frontile/changeset-form`, removed entirely
  rather than re-exported
- the `@frontile/*` wrapper packages (move your imports to `frontile`)
- the old `@intent` and `@appearance` argument names

It may carry new features and bug fixes too, but the cleanup drives its
timing.

**This shortens the runway on the optional migrations.** The v0.18 guide marks
package consolidation and the move off `forms-legacy` as "optional, any time
before 0.19", which is true, but "before 0.19" is sooner than it sounds. If
you are upgrading to v0.18 now, doing those two while you are already in the
code is the cheaper order.

## Full changelog

The complete list of merged pull requests, categorized, is in the
[v0.18.0 release on GitHub](https://github.com/josemarluedke/frontile/releases/tag/v0.18.0).

---

# v0.17

Source: /docs/releases/v0-17.md

# v0.17

Released November 2025 (v0.17.0, then a v0.17.1 follow-up a week later), v0.17
was the last release before the v0.18 redesign and consolidated a long run of
feature work: new components, a reworked forms system, and the first step
toward Tailwind CSS v4. This page is a thin archive; the GitHub releases linked below have the full PR
list.

- **New components.** Table, Avatar, Switch, Portal, and a filterable Select
  landed, alongside Dropdown and Listbox from earlier work maturing into their
  current form.
- **Forms got a rewrite.** Whole-form `disabled`, dirty-field tracking, data
  binding, automatic and on-blur validation, `validateOn` for `change`/`input`/
  `submit`, and standard-schema validation support all shipped together. The
  forms system moved from ad hoc validation to a coherent model.
- **Package layout changed.** Older form components moved to a new
  `forms-legacy` package, `Overlay` was refactored with new `Popover` and
  `Backdrop` components, and separate `collections`, `status`, and `utilities`
  packages were introduced (with `core` renamed to `utilities`).
- **Selection API breaking change.** Select components moved to a
  `selectedKey`/`selectedKeys` API, replacing the previous value-based
  approach.
- **Tailwind CSS v4 support.** The theme plugin was refactored for v4
  compatibility, including a default export and updated class names; the
  docs site itself moved to Vite during this window.
- **Docs site refresh.** Navigation was redesigned with collapsible sections,
  and the forms and theming documentation was substantially rewritten.
- **v0.17.1** followed a week later with a headless-browser test reliability
  fix and further docs-site polish (homepage, SEO meta tags, favicon).

See the [v0.17.0](https://github.com/josemarluedke/frontile/releases/tag/v0.17.0)
and [v0.17.1](https://github.com/josemarluedke/frontile/releases/tag/v0.17.1)
GitHub releases for the complete list of merged PRs.

---

# v0.16

Source: /docs/releases/v0-16.md

# v0.16

Released December 2023 as "Addon V2 + Glint + Template tag," v0.16 was an
internal-facing release: it didn't add components so much as move the ground
under all of them. Every package was migrated to Ember's v2 addon format and
converted to `.gts`/template-tag syntax, with Glint type-checking added along
the way. There is a nearly two-year gap between this release and v0.17. This
page is a thin archive covering v0.16.0 through v0.16.2; the GitHub releases
linked below have the full PR list.

- **Addon V2 migration.** `core`, `buttons`, `forms`, `changeset-form`,
  `notifications`, and `overlays` were all moved from the legacy (v1) addon
  format to Ember's v2 addon format.
- **Template tag (gts) conversion.** Components across every package were
  rewritten from classic templates to `.gts` with embedded `<template>` tags,
  ahead of Frontile standardizing on that format.
- **Glint support added.** Type-checked templates arrived with the core
  package's v2 migration and extended outward as each package converted.
- **Embroider compatibility fix.** A follow-up patch (v0.16.1) moved
  `modal`/`drawer` out of `index.gts` files, since Embroider does not resolve
  those the same way the classic build did.
- **Package manager switch.** v0.16.2 moved the project from Yarn v1 to pnpm,
  the workspace tooling this monorepo still uses.

See the
[v0.16.0](https://github.com/josemarluedke/frontile/releases/tag/v0.16.0),
[v0.16.1](https://github.com/josemarluedke/frontile/releases/tag/v0.16.1), and
[v0.16.2](https://github.com/josemarluedke/frontile/releases/tag/v0.16.2)
GitHub releases for the complete list of merged PRs.