# SectionHeader

> Slug: `section-header` · Category: Display

## When to use
- Title a section of a page with optional supporting subheadline and trailing controls (link, action, status, icon button).
- Provide a heading row that aligns with Arrow's section spacing rules.
- Optionally make the entire heading a navigation link via `isAction`.

## When NOT to use
- Page-level hero titles with body copy — use `Title`.
- Plain inline headings without trailing controls — use a typography utility (`tdds:text-title-2` etc.).
- A row that is fundamentally a list item or a filter — use `ListItem` / `FilterChip`.

## Variants & decision tree
- Plain section heading -> set `headLine` (and optional `subHeadline`).
- Heading + trailing control (e.g., "View all" link, `IconButton`) -> add `trailingContent`. Trailing content is hidden when `isAction` is true.
- Whole heading navigates -> `isAction` + `actionHref`. Renders an inline `<a>` wrapping the heading text.

## States
- `focused` -> force-focus class on the action link (design review only).
- Inverse-aware (theme or `inverse` prop).
- Returns `null` if `headLine` is falsy.

## Props
| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| **`headLine`** | `ReactNode` | — | Visible heading text. |
| `subHeadline` | `ReactNode` | — | Secondary line below the headline. |
| `heading` | `'h1' \| 'h2' \| ... \| 'h6'` | `'h2'` | Semantic heading element. |
| `id` | `string` | — | id on the heading element. |
| `isAction` | `boolean` | `false` | Wrap heading text in an `<a>`. Hides `trailingContent`. |
| `actionHref` | `string` | `'#'` | Href for the action link. |
| `trailingContent` | `ReactNode` | — | Right-aligned controls. Ignored when `isAction`. |
| `inverse` | `boolean` | inherits | Dark-background styling. |
| `focused` | `boolean` | `false` | Force focus on action link. |

## Usage examples
```tsx
import { SectionHeader, LinkStyledAsButton, IconButton } from 'arrow-react-bootstrap';

// Heading with "View all" link
<SectionHeader
  headLine="Recommended for you"
  trailingContent={<LinkStyledAsButton href="/all" label="View all" variant="tertiary" />}
/>

// Heading with subheadline
<SectionHeader
  heading="h3"
  headLine="Account"
  subHeadline="Profile, security, and notifications"
/>

// Action heading — whole row navigates
<SectionHeader
  isAction
  actionHref="/billing"
  headLine="Billing & payments"
/>

// Heading with trailing icon button
<SectionHeader
  headLine="Notifications"
  trailingContent={<IconButton a11yLabel="Settings" icon={SettingsIcon} size="small" />}
/>
```

## Composition
- Place atop `List`, `Lists`, `Table`, `Tile`, `BillCard`, or content blocks.
- Combine with `Divider` below for visually separated sections.

## Accessibility
- Renders a real heading element; keep document outline coherent (`h2` after `h1`, etc.).
- When `isAction`, the heading text is wrapped in an `<a>` — ensure target and route exist.
- Trailing controls retain their own roles (link, button) and are skipped when `isAction` is set.

## Do / Don't
- Do: pick `heading` to match the document outline (often `h2` or `h3`).
- Do: use `trailingContent` for a single concise control ("View all", a settings icon).
- Don't: combine `isAction` with `trailingContent` — the latter is suppressed.
- Don't: pass interactive elements inside `headLine`; use `isAction` instead.
