# Accordion
An accordion is a group of vertically stacked, collapsible sections that allow users to toggle the visibility of related content.

## Overview
Accordions help reduce scrolling by hiding non-essential information until it's needed. They organize content into collapsible sections, making it easier for users to find and focus on information relevant to them. This is especially useful for long pages where not all information needs to be visible at once.

<daff-docs-example-viewer example="basic-accordion"></daff-docs-example-viewer>

## Best practices

**When to use**
- To organize related information
- To shorten pages and reduce scrolling when screen space is limited and content is not crucial to read

**When not to use**
- When most users will need to see all content anyway
- The content is very short and hiding it adds unnecessary complexity (use [List](/libs/design/list/README.md) instead)

## Usage
Import `DAFF_ACCORDION_COMPONENTS` into your component:

```ts
import { DAFF_ACCORDION_COMPONENTS } from '@daffodil/design/accordion';

@Component({
  selector: 'custom-component',
  templateUrl: './custom-component.component.html',
  imports: [
    DAFF_ACCORDION_COMPONENTS,
  ],
})
export class CustomComponent {}
```

## Anatomy
An accordion is composed of a container, items, titles, and content:

```html
<daff-accordion>
  <daff-accordion-item>
    <h3 daffAccordionItemTitle>Title</h3>
    <div>Expandable content</div>
  </daff-accordion-item>
</daff-accordion>
```

- **`<daff-accordion>`**: The wrapper component that groups all accordion items together.
- **`<daff-accordion-item>`**: Individual collapsible section containing a title and content. Handles expansion and collapse on user interaction.
- **`[daffAccordionItemTitle]`**: The clickable header that toggles the accordion item's visibility.
- **Content**: Content placed inside `<daff-accordion-item>` (excluding the title) forms the collapsible panel content that is shown or hidden when toggled.

## Features

### Default expansion
Use the `initiallyExpanded` property on the accordion item to have an item open by default.

<daff-docs-example-viewer example="initially-expanded-accordion"></daff-docs-example-viewer>

### Disabled item
Use the `disabled` property on the accordion item to disable and prevent it from being expanded or collapsed.

<daff-docs-example-viewer example="disabled-accordion"></daff-docs-example-viewer>

## Accessibility
Accordion follows the [Accordion WAI-ARIA design pattern](https://www.w3.org/WAI/ARIA/apg/patterns/accordion/).

### Built-in behavior
- `role="button"` on titles with `aria-expanded` to indicate current state and `aria-controls` linking to the associated panel
- `role="region"` on content panels with `aria-labelledby` linking back to the corresponding title
- Unique IDs autogenerated for titles and panels (overridable via the `contentId` and `itemId` inputs on `<daff-accordion-item>`)

#### Keyboard interactions
| Key | Action |
| --- | ------ |
| `Tab` | Moves focus to the next focusable element. |
| `Enter` / `Space` | Expands or collapses the focused accordion item's panel content. |

### Developer responsibilities
- Wrap titles in an appropriate heading element (`<h2>`, `<h3>`, etc.) so the accordion contributes to the page's heading structure
- Provide concise, descriptive title text