# Accordion

> Slug: `accordion` · Category: Disclosure

## When to use
- Progressive disclosure of related content sections (FAQs, settings groupings, optional details).
- When the page is long and users only need a subset of sections at a time.

## When NOT to use
- For a single expand/collapse trigger — use `AccordionButton`.
- For switching between mutually exclusive panels — use `Tabs`.
- For navigation that loads new pages — use `Subnavigation` or `DisclosureCard`.
- When users will likely need everything visible at once (just stack content).

## Variants & decision tree
`Accordion` is data-driven via the `items` array. Each item is `{ id, heading, content, icon?, iconA11yLabel? }`.

- **Single open** → `allowMultiple={false}` (default). Opening one item closes the others.
- **Multi-open** → `allowMultiple={true}`. Each item toggles independently — use for FAQs.
- **With dividers** → `hasDivider={true}` (default). Set to `false` when nesting inside a card or chrome that already provides separation.
- **Heading level** → `heading` controls the H tag (`'h2'` default through `'h6'`). Match the document outline (e.g. `h3` if the page H1/H2 are already used).

> Note: `Accordion` does **not** use `useExpandCollapse` — it manages `aria-expanded` directly.

## States
- Each item has expanded/collapsed state.
- Per-item force-state flags (`focused`, `hover`) for visual testing.
- `inverse` swaps to dark-background styling.

## Props
| Prop | Type | Default | Description |
|---|---|---|---|
| `items` | `AccordionItem[]` | — | `{ id, heading, content, icon?, iconA11yLabel? }`. |
| `allowMultiple` | `boolean` | `false` | Allow multiple open items. |
| `defaultExpandedIds` | `string[]` | `[]` | Items expanded on first render. |
| `heading` | `'h2' \| 'h3' \| 'h4' \| 'h5' \| 'h6'` | `'h2'` | Heading level for triggers. |
| `hasDivider` | `boolean` | `true` | Render dividers between items. |
| `inverse` | `boolean` | inherited | Dark-background styling. |

## Usage examples
```tsx
<Accordion
  heading="h3"
  allowMultiple
  items={[
    { id: 'faq-1', heading: 'How do I reset my password?', content: <p>…</p> },
    { id: 'faq-2', heading: 'How do I change plans?',       content: <p>…</p> },
  ]}
/>
```

## Composition
Each `content` can hold any layout (paragraphs, `Lists`, `Table`, even nested `Accordion`s). Avoid putting forms with required validation inside collapsed items unless you handle "scroll to error".

## Accessibility
- Each trigger is a `<button>` with `aria-expanded` and `aria-controls`.
- The heading wraps the button (`<h2><button>…</button></h2>`) — pick the right `heading` level so the document outline is correct.
- Provide `iconA11yLabel` for any decorative icon that conveys meaning.

## Do / Don't
- Do use `allowMultiple` for FAQ pages.
- Do set `heading` to fit the surrounding outline.
- Don't use compound syntax (`Accordion.Item`) — it doesn't exist.
- Don't hide critical information in collapsed items by default.
