# ARIA Patterns

Accessible Rich Internet Applications (ARIA) roles, states, and properties.

## When to Use ARIA

> "No ARIA is better than bad ARIA."

1. Use semantic HTML first (`<button>`, `<nav>`, `<dialog>`)
2. Add ARIA only when native semantics aren't sufficient
3. Ensure custom controls have proper keyboard support

## Common Roles

| Role | Use For |
|------|---------|
| `button` | Clickable non-button elements |
| `link` | Clickable non-anchor navigation |
| `dialog` | Modal windows |
| `alert` | Important messages |
| `alertdialog` | Modal with alert |
| `menu` / `menuitem` | Application menus |
| `tablist` / `tab` / `tabpanel` | Tab interfaces |
| `listbox` / `option` | Custom selects |
| `tree` / `treeitem` | Hierarchical lists |

## States & Properties

### aria-expanded
```html
<!-- Accordion header -->
<button aria-expanded="false" aria-controls="panel-1">
  Section 1
</button>
<div id="panel-1" hidden>Content...</div>
```

### aria-selected
```html
<!-- Tab -->
<div role="tablist">
  <button role="tab" aria-selected="true" aria-controls="panel-1">Tab 1</button>
  <button role="tab" aria-selected="false" aria-controls="panel-2">Tab 2</button>
</div>
```

### aria-pressed
```html
<!-- Toggle button -->
<button aria-pressed="false">Dark Mode</button>
```

### aria-current
```html
<!-- Current page in nav -->
<nav>
  <a href="/" aria-current="page">Home</a>
  <a href="/about">About</a>
</nav>
```

### aria-live
```html
<!-- Dynamic content announcements -->
<div aria-live="polite">
  <!-- Updates announced after user stops interacting -->
</div>

<div aria-live="assertive">
  <!-- Updates announced immediately (use sparingly) -->
</div>
```

## Labeling

### aria-label
```html
<!-- When visible text isn't sufficient -->
<button aria-label="Close dialog">×</button>
```

### aria-labelledby
```html
<!-- Reference another element's text -->
<dialog aria-labelledby="dialog-title">
  <h2 id="dialog-title">Confirm Action</h2>
</dialog>
```

### aria-describedby
```html
<!-- Additional description -->
<input aria-describedby="password-hint" type="password">
<p id="password-hint">Must be at least 8 characters</p>
```

## Component Examples

### Modal Dialog
```typescript
template = html`
  <div 
    role="dialog"
    aria-modal="true"
    aria-labelledby="dialog-title"
    aria-describedby="dialog-desc"
  >
    <h2 id="dialog-title">${x => x.title}</h2>
    <p id="dialog-desc">${x => x.description}</p>
    <slot></slot>
  </div>
`;
```

### Custom Checkbox
```typescript
template = html`
  <div
    role="checkbox"
    aria-checked="${x => x.checked}"
    tabindex="0"
    @click="${x => x.toggle()}"
    @keydown="${(x, c) => x.handleKeydown(c.event)}"
  >
    ${when(x => x.checked, html`✓`)}
    <slot></slot>
  </div>
`;
```

### Alert
```typescript
// Announce to screen readers
showAlert(message: string) {
  const alert = document.createElement('div');
  alert.setAttribute('role', 'alert');
  alert.textContent = message;
  document.body.appendChild(alert);
  setTimeout(() => alert.remove(), 5000);
}
```
