# Dropdown

## Overview

The dropdown component presents a short list of actions or links through a native `<details>` disclosure that visually matches the select control.

The component uses a scoped `.dropdown` class on `<details>` so it can style the trigger and menu without colliding with the global accordion treatment.

## When to use

Use a dropdown to reveal a short, compact list of navigation links or in-place actions from one trigger.

## When not to use

Do not use a dropdown for a submitted form value or primary navigation that should remain visible; use select or nav.

## Usage

```html
<details class="dropdown">
  <summary>Dropdown</summary>
  <ul>
    <li><a href="#">Solid</a></li>
    <li><a href="#">Liquid</a></li>
    <li><a href="#">Gas</a></li>
    <li><a href="#">Plasma</a></li>
  </ul>
</details>
```

Use this component when the user needs to reveal a compact list of navigation targets or actions from a single trigger.

The list can also contain labels with direct child checkbox or radio inputs when users need to make compact, browser-managed choices without JavaScript.

Use `select` instead when the field is part of form submission and the browser should manage value selection, validation, and picker semantics.

Keep the summary label short enough to read like a control label rather than a sentence.

## Behavior

Covered by [Playwright behavior tests](../../tests/e2e/components.spec.js).

- DRP-001: The closed trigger should align visually with the shared select control, including border, padding, focus ring, and downward chevron treatment.
- DRP-002: The disclosure remains native `<details>` and `<summary>` behavior, so keyboard interaction and open state management stay browser-driven.
- DRP-003: The menu panel should stay scoped to `.dropdown` and should not restyle unrelated `details` disclosures.
- DRP-004: The revealed list should accept simple anchor-only menu items without extra wrapper markup.
- DRP-005: Menu item hover and focus surfaces should stay flush with the list while clipping to the panel's rounded border.
- DRP-006: The indicator uses `--dropdown-icon-source` as a mask and `--dropdown-icon-color` as its theme-aware fill so consumers can customize its artwork and color independently.
- DRP-007: Comfortable and compact density should both come from shared layout tokens.
- DRP-008: A dropdown list item may contain a label with a direct child checkbox or radio, making the full padded row clickable while preserving native form behavior.
- DRP-009: Choice rows should expose native checked, radio-group, focus, and disabled behavior without closing the disclosure automatically.
- DRP-010: The chevron should remain centered at the trigger's configured inline offset, point down while closed, and rotate 180 degrees to point up while open.

## Accessibility

- Use a native `<summary>` as the visible trigger label.
- Keep menu item text descriptive on its own because each link may be announced without surrounding context.
- Use real links for navigation destinations and buttons only when the revealed items trigger in-place actions.
- Use `select` or another true form control when the user is choosing a submitted value rather than opening a short action list.
- Keep native checkbox and radio inputs visible, put each input inside its visible label, and use a shared `name` for related controls.

## Variables

| Variable | Type | Description |
| --- | --- | --- |
| `--dropdown-color-accent-subtle` | `<color>` | Sets --dropdown-color-accent-subtle so the component can default to shared theme or layout tokens while exposing an overrideable component API. |
| `--dropdown-color-border-subtle` | `<color>` | Sets --dropdown-color-border-subtle so the component can default to shared theme or layout tokens while exposing an overrideable component API. |
| `--dropdown-color-focus-ring` | `<color>` | Sets --dropdown-color-focus-ring so the component can default to shared theme or layout tokens while exposing an overrideable component API. |
| `--dropdown-color-primary` | `<color>` | Sets --dropdown-color-primary so the component can default to shared theme or layout tokens while exposing an overrideable component API. |
| `--dropdown-color-primary-subtle` | `<color>` | Sets --dropdown-color-primary-subtle so the component can default to shared theme or layout tokens while exposing an overrideable component API. |
| `--dropdown-color-text` | `<color>` | Sets --dropdown-color-text so the component can default to shared theme or layout tokens while exposing an overrideable component API. |
| `--dropdown-control-border-width` | `<length>` | Sets --dropdown-control-border-width so the component can default to shared theme or layout tokens while exposing an overrideable component API. |
| `--dropdown-control-gap` | `<length>` | Sets --dropdown-control-gap so the component can default to shared theme or layout tokens while exposing an overrideable component API. |
| `--dropdown-control-min-height` | `<length>` | Sets --dropdown-control-min-height so the component can default to shared theme or layout tokens while exposing an overrideable component API. |
| `--dropdown-control-padding-block` | `<length>` | Sets --dropdown-control-padding-block so the component can default to shared theme or layout tokens while exposing an overrideable component API. |
| `--dropdown-control-padding-inline` | `<length>` | Sets --dropdown-control-padding-inline so the component can default to shared theme or layout tokens while exposing an overrideable component API. |
| `--dropdown-control-radius` | `<length>` | Sets --dropdown-control-radius so the component can default to shared theme or layout tokens while exposing an overrideable component API. |
| `--dropdown-focus-ring-size` | `<length>` | Sets --dropdown-focus-ring-size so the component can default to shared theme or layout tokens while exposing an overrideable component API. |
| `--dropdown-font-size` | `<length>` | Sets --dropdown-font-size so the component can default to shared theme or layout tokens while exposing an overrideable component API. |
| `--dropdown-icon-color` | `<color>` | Sets the dropdown chevron color; change it when the disclosure indicator needs a different semantic emphasis. |
| `--dropdown-icon-offset` | `<length>` | Sets the inline offset between the dropdown chevron and the control edge; change it when padding or icon alignment changes. |
| `--dropdown-icon-size` | `<length>` | Sets the chevron size in dropdown controls; change it when the icon should scale differently from the control text. |
| `--dropdown-icon-source` | `<image> | none` | Sets the chevron mask used for dropdown controls; change it to swap the indicator artwork independently from its color. |
| `--dropdown-line-height` | `<number>` | Sets --dropdown-line-height so the component can default to shared theme or layout tokens while exposing an overrideable component API. |
| `--dropdown-panel-offset` | `<length>` | Sets the gap between the trigger and dropdown panel; change it when the popover should sit tighter to or farther from the control. |

## Depends On

- `--color-accent-subtle`
- `--color-border-subtle`
- `--color-focus-ring`
- `--color-primary`
- `--color-primary-subtle`
- `--color-text`
- `--color-text-accent`
- `--font-line-height-body`
- `--font-size`
- `--layout-control-border-width`
- `--layout-control-gap`
- `--layout-control-icon-size`
- `--layout-control-min-height`
- `--layout-control-padding-block`
- `--layout-control-padding-inline`
- `--layout-control-radius`
- `--layout-focus-ring-size`
- `--layout-space-inline`