# SectionHeader

**When to use:** A reusable heading block for the top of a page, panel, card, or any section — a title with an optional subtitle, a leading icon or thumbnail, and a trailing actions area. Use it wherever you'd otherwise hand-roll a `<h2>` + subtitle + buttons row. Inside a `Card`, the card-scoped `CardHeader` remains available; `SectionHeader` is the standalone, fully slot-customisable version.

**Keywords:** page header, panel title

**Import:** `import { SectionHeader, SectionHeaderSize } from '@ahrowe/ui'`
**Types:** `import type { SectionHeaderProps, SectionHeaderAction } from '@ahrowe/ui'`

**Style variants:** `SectionHeaderSize.Small` | `SectionHeaderSize.Medium` (default) | `SectionHeaderSize.Large`

```tsx
import { SectionHeader, SectionHeaderSize } from '@ahrowe/ui';
import { faFolder, faPen, faTrash } from '@fortawesome/free-solid-svg-icons';

// Title + subtitle
<SectionHeader title="Account settings" subtitle="Manage your profile and preferences" />

// Leading icon
<SectionHeader icon={faFolder} title="Documents" subtitle="12 files" />

// Leading thumbnail (URL → background image; any other ReactNode → rendered inside)
<SectionHeader thumbnail="https://example.com/avatar.jpg" title="Jane Doe" subtitle="Designer" />

// Trailing actions — array renders ActionIcons, or pass any ReactNode
<SectionHeader
  title="Integrations"
  actions={[
    { title: 'Edit', icon: faPen, onClick: handleEdit },
    { title: 'Delete', icon: faTrash, onClick: handleDelete },
  ]}
/>
<SectionHeader title="Reports" actions={<Button>Export</Button>} />

// Larger scale, a bottom divider, and a semantic heading level for a11y
<SectionHeader
  size={SectionHeaderSize.Large}
  level={1}
  divider
  title="Dashboard"
  subtitle="Your workspace at a glance"
/>

// left / center — the title stays fixed to the left; everything else (left,
// center, actions) lives in a separate trailing block laid out with
// space-between, so `center` is centered within that block, not the whole header
<SectionHeader
  title="Team members"
  left={<Chip text="12 active" />}
  center={<SearchInput value={query} onChange={setQuery} />}
  actions={[{ title: 'Invite', icon: faPlus, onClick: handleInvite }]}
/>
```

**Enums:**

- `SectionHeaderSize`: `Small` | `Medium` (default) | `Large`

**Key props:**

| Prop | Type | Description |
|------|------|-------------|
| `title` | `ReactNode` | Main heading |
| `subtitle` | `ReactNode` | Secondary text below the title |
| `icon` | `IconDefinition \| ReactElement` | Icon shown on the left (FontAwesome icon or any React element); ignored when `thumbnail` is set |
| `thumbnail` | `string \| ReactNode` | URL → background image; any other ReactNode → rendered inside the leading circle |
| `left` | `ReactNode` | Leftmost content of the trailing block (title stays fixed to the left of it) |
| `center` | `ReactNode` | Center content of the trailing block, e.g. a search box or tabs |
| `actions` | `SectionHeaderAction[] \| ReactNode` | Rightmost content of the trailing block: array → `ActionIcon`s; ReactNode → rendered as-is |
| `level` | `1 \| 2 \| 3 \| 4 \| 5 \| 6` | Semantic heading level for the title element (default `2`) |
| `size` | `SectionHeaderSize` | Visual scale (default `Medium`) |
| `divider` | `boolean` | Render a `Divider` below the header (default `false`) |

**SectionHeaderAction:**

```ts
interface SectionHeaderAction {
  title?: string;
  icon: IconDefinition | ReactElement;
  onClick?: (e: React.MouseEvent<HTMLButtonElement>) => void;
}
```

**Global defaults:** adopts `ConfigProvider` — set defaults app-wide via `defaultProps={{ SectionHeader: { size: SectionHeaderSize.Large } }}`. See [ConfigProvider.md](ConfigProvider.md).

**Theming:** title size/weight per `size` variant come from the theme, with local fallbacks — `SectionHeaderSize.Large` uses `--header-font-size` (falls back `24px`), `Medium` uses `--header-medium-font-size` (falls back `18px`), `Small` uses `--header-small-font-size` (falls back `16px`); all three use `--header-font-weight` for the title's font weight (falls back `600`). The leading icon/thumbnail is sized at `2.2×` the title size, so it scales automatically with the theme; the subtitle size is fixed per `size` variant (not derived), since it doesn't track the title proportionally at the `Large` size. See [ThemeProvider.md](ThemeProvider.md).

**Layout:** the title and its leading icon/thumbnail sit together in an `identity` wrapper that is fixed to the left and only takes the width its content needs; they never wrap apart from each other. The title itself renders on a single line and truncates with an ellipsis (a plain-string `title` is also set as the element's `title` attribute, so the full text is available on hover); the subtitle is clamped to two lines. Everything after it — `left`, `center`, `actions` — lives in a separate `trailing` flex block laid out with `space-between`, so `center` is centered within that block (not the whole header) regardless of how wide `left`/`actions` are.

**Responsive:** the header wraps — if `trailing` (`left`/`center`/`actions`) doesn't fit next to the `identity` block, it drops to its own row; if `trailing` itself doesn't fit as one row, its own children wrap too. Below `640px` viewport width, `center` additionally takes a full-width row of its own, so a wide `center` element (e.g. a `SearchInput`) isn't squeezed alongside `left`/`actions` on small screens.

**Slots:** `root` `identity` `leading` `titles` `title` `subtitle` `trailing` `left` `center` `actions`