# FullPageInterruption

> Slug: `full-page-interruption` · Category: Feedback

## When to use
- A blocking, full-page state when normal navigation cannot continue: critical errors, service outages, account-suspended screens, hard system warnings.
- When the user must read a message and choose between 1–3 actions before continuing.

## When NOT to use
- For inline validation or contextual notices — use `NoticeBar`.
- For dismissible toast feedback — use `Snackbar`.
- For confirmations or prompts above existing UI — use `Modal`.
- For empty states inside cards/sections — use a `SectionHeader` + body copy.

## Variants & decision tree
A single layout: warning icon, headline, body, and an action area. Composition is data-driven via children — pass a `ButtonGroup` (or any `ReactNode`) to render the actions.

- **One action** (e.g. "Try again") → render a single `<Button variant="primary">` inside the children slot. The Lit source forces a column ButtonGroup layout in this case.
- **Two actions** → primary + secondary in a `ButtonGroup` (e.g. "Retry" + "Sign out").
- **Tertiary present** → if a tertiary button is included, layout stays column on all sizes.

`headlineType` (`'h1'`–`'h6'`) lets you align with the page outline (typically `'h1'` since this is a full-screen state).

## States
- Inverse colour treatment via `inverse`.
- `iconA11yLabel` controls whether the warning icon is announced (`aria-label`) or treated as decorative.

## Props
| Prop | Type | Default | Description |
|---|---|---|---|
| `header` | `ReactNode` | — | Required headline text. |
| `body` | `ReactNode` | — | Required body text. |
| `children` | `ReactNode` | — | Required action area (typically a `ButtonGroup`). |
| `headlineType` | `'h1' \| … \| 'h6'` | — | Heading element used for `header`. |
| `icon` | `ReactNode` | warning icon | Override the default warning SVG. |
| `iconA11yLabel` | `string` | — | When set, icon gets `role="img"` + `aria-label`. |
| `inverse` | `boolean` | inherited | Dark-background styling. |

## Usage examples
```tsx
<FullPageInterruption
  headlineType="h1"
  header="We can't reach our servers"
  body="Please check your connection and try again."
  iconA11yLabel="Warning"
>
  <ButtonGroup>
    <Button variant="primary" onClick={retry}>Try again</Button>
    <Button variant="secondary" onClick={signOut}>Sign out</Button>
  </ButtonGroup>
</FullPageInterruption>
```

## Composition
Render as the only content of the route/screen — it's intended to take over the viewport. Pair with `ArrowThemeProvider` if a brand override is needed.

## Accessibility
- Set `iconA11yLabel` ("Warning", "Error", etc.) so the visual cue is announced.
- Use `headlineType="h1"` so screen-reader users understand the page changed.
- Make sure focus moves to the headline (or the primary action) when the screen mounts.

## Do / Don't
- Do limit to 1–3 actions.
- Do write a clear, actionable body — say what happened and what to do next.
- Don't use for routine empty states or recoverable inline errors.
- Don't render a `FullPageInterruption` inside another scrollable region.
