@masmarino/gabarit 1.4.0 → 2.1.0

package/copy-button/README.md

@@ -0,0 +1,90 @@
+# CopyButton
+
+A button that copies a value to the clipboard and says so. It replaces the five hand-written
+"copy + Copied for 2 s + select the text on failure" implementations of an application (clone box,
+recovery codes, file view, one-time token, row menu).
+
+**Selector**: `gbt-copy-button`. Built on [`gbt-button`](../button/README.md); the clipboard logic
+(`copyToClipboard`, `ClipboardFeedback`) lives in `clipboard.ts` and is shared with
+[`gbt-copy-field`](../copy-field/README.md), [`gbt-secret-reveal`](../secret-reveal/README.md)
+and [`gbt-badge`](../badge/README.md)'s `copyable` input.
+
+## Inputs
+
+| Input          | Type                               | Default         | Role                                                                                                |
+| -------------- | ---------------------------------- | --------------- | --------------------------------------------------------------------------------------------------- |
+| `value`        | `string \| (() => string)`         | `''`            | The text to copy. A function is called when the button is pressed (a big file body, a fresh token). |
+| `text`         | `string`                           | `''`            | Visible label. Empty: an icon-only square.                                                          |
+| `ariaLabel`    | `string \| null`                   | `null`          | Accessible name. Defaults to `Copy` when icon-only and to `text` otherwise.                         |
+| `copiedText`   | `string`                           | `'Copied'`      | Message shown and announced after a successful copy.                                                |
+| `failedText`   | `string`                           | `'Copy failed'` | Message shown and announced when the copy is refused.                                               |
+| `feedbackMs`   | `number`                           | `2000`          | How long the "copied" message stays. A failure message stays twice as long.                         |
+| `variant`      | `ButtonVariant`                    | `'secondary'`   | Same values as `gbt-button`.                                                                        |
+| `size`         | `ButtonSize`                       | `'small'`       | `small \| medium \| large`.                                                                         |
+| `icon`         | `string`                           | `'copy'`        | Glyph of the idle button (registered icon name; `copy` is built in).                                |
+| `disabled`     | `boolean`                          | `false`         |                                                                                                     |
+| `feedback`     | `'bubble' \| 'inline' \| 'hidden'` | `'bubble'`      | Where the message is drawn (see below).                                                             |
+| `selectTarget` | `HTMLElement \| null`              | `null`          | Selected when the copy fails, so the user can copy by hand with Ctrl+C / Cmd+C.                     |
+
+## Outputs
+
+| Output       | Payload  | Role                                                                                                         |
+| ------------ | -------- | ------------------------------------------------------------------------------------------------------------ |
+| `copied`     | `string` | The text that was copied.                                                                                    |
+| `copyFailed` | `void`   | Neither the Clipboard API nor the fallback could copy (the text is shown selected if `selectTarget` is set). |
+
+## How it copies
+
+1. `navigator.clipboard.writeText` (secure contexts only: HTTPS or `localhost`).
+2. Otherwise, or when the write is refused, `document.execCommand('copy')` on a throw-away textarea
+   (the focus and the selection of the page are restored). This is what makes a **plain-HTTP
+   self-hosted instance** work.
+3. Otherwise `copyFailed` is emitted, the failure message shows and `selectTarget` is selected.
+
+No browser API is read until the button is pressed, so rendering (SSR, jsdom) never touches
+`navigator.clipboard`. A write that settles after the component is destroyed schedules nothing and
+emits nothing.
+
+## Stale messages
+
+A "Copied" message belongs to the text that was copied: when `value` changes to a different **string** the message is
+dropped (a function value is left alone, since a template may hand out a new closure on every change detection).
+`reset()` (a public method) drops it on demand; `gbt-secret-reveal` calls it when the secret is hidden.
+
+The legacy fallback puts its temporary textarea inside the trigger's `dialog` / `[role="dialog"]` when there is
+one: a native modal `<dialog>` makes the rest of the page inert, and a textarea outside it could not be focused.
+
+## Feedback
+
+The accessible name never changes. The outcome is told by:
+
+- a polite `role="status"` region that is **always in the DOM** (a live region only announces changes if
+  it was already rendered), holding `copiedText` or `failedText`;
+- the icon: `copy`, then `check` (or `alert-circle` on failure), so it is never colour alone;
+- visually, according to `feedback`: `bubble` is a small pill floating above the button, right-aligned
+  (clipped by an ancestor with `overflow: hidden`: use `inline` there); `inline` is the same message in
+  the flow after the button; `hidden` is for screen readers only.
+
+The host carries `data-status="idle | copied | failed"` for styling.
+
+## Example
+
+```html
+<code #url>{{ cloneUrl }}</code>
+<gbt-copy-button
+  [value]="cloneUrl"
+  ariaLabel="Copy the clone URL"
+  copiedText="Copied"
+  failedText="Copy failed, press Ctrl+C"
+  [selectTarget]="url"
+  (copied)="analytics.track('clone-url-copied')"
+/>
+
+<!-- A label, and a value produced only when needed -->
+<gbt-copy-button text="Copy the file" [value]="() => file().content" feedback="inline" />
+```
+
+## Accessibility
+
+See [AUDIT.md](AUDIT.md). The icon-only button needs (and gets) a name; localise `ariaLabel`,
+`copiedText` and `failedText` (the defaults are English).

package/copy-field/README.md

@@ -0,0 +1,54 @@
+# CopyField
+
+A read-only value in monospace with a copy button beside it: a clone URL, a webhook URL, an activation
+link, a token that is shown in full.
+
+**Selector**: `gbt-copy-field`. Built on [`gbt-copy-button`](../copy-button/README.md) (Clipboard API,
+`execCommand` fallback, live-region confirmation). For a secret that must stay masked until asked for,
+use [`gbt-secret-reveal`](../secret-reveal/README.md).
+
+## Inputs
+
+| Input        | Type                               | Default                         | Role                                                                                        |
+| ------------ | ---------------------------------- | ------------------------------- | ------------------------------------------------------------------------------------------- |
+| `value`      | `string`                           | —                               | Required. The value shown and copied.                                                       |
+| `label`      | `string \| null`                   | `null`                          | Visible label above the field. It also names the group (`role="group"`, `aria-labelledby`). |
+| `copyLabel`  | `string`                           | `'Copy'`                        | Accessible name of the copy button. Say what is copied ("Copy the clone URL").              |
+| `copiedText` | `string`                           | `'Copied'`                      | Message shown and announced after a successful copy.                                        |
+| `failedText` | `string`                           | `'Copy failed, value selected'` | Message when the copy is refused; the value is then selected for a manual Ctrl+C.           |
+| `feedbackMs` | `number`                           | `2000`                          | How long the confirmation stays (a failure stays twice as long).                            |
+| `feedback`   | `'bubble' \| 'inline' \| 'hidden'` | `'bubble'`                      | Where the confirmation is drawn (see `gbt-copy-button`).                                    |
+| `wrapAt`     | `RegExp \| null`                   | after each `/` (not in `//`)    | Where the value may wrap: it is cut after each match, with a `<wbr>`. `null`: no hint.      |
+
+## Outputs
+
+| Output       | Payload  | Role                                            |
+| ------------ | -------- | ----------------------------------------------- |
+| `copied`     | `string` | The copied value.                               |
+| `copyFailed` | `void`   | Neither copy API worked; the value is selected. |
+
+## Behaviour
+
+- The value **wraps** instead of scrolling: it stays readable in a 240 px aside or on a phone with no scroll
+  region to reach by keyboard. Break opportunities follow `wrapAt`; a segment too long for a line breaks
+  anywhere.
+- One click selects the whole value (`user-select: all`).
+- The value is cut **after** each match of `wrapAt` (a `<wbr>` is inserted); the text itself is never altered, so a
+  capturing group or a separator such as `/\//` cannot drop or duplicate characters.
+- `COPY_FIELD_WRAP_AT` (the default pattern) is exported by the component file if you want to extend it.
+
+## Example
+
+```html
+<gbt-copy-field
+  label="Clone with HTTPS"
+  copyLabel="Copy the clone URL"
+  failedText="Copy failed, press Ctrl+C"
+  [value]="repo.cloneUrl"
+  (copied)="toast.show('URL copied', 'success')"
+/>
+```
+
+## Accessibility
+
+See [AUDIT.md](AUDIT.md). Localise `label`, `copyLabel`, `copiedText` and `failedText`.

package/date-picker/README.md

@@ -0,0 +1,84 @@
+# DatePicker
+
+Single-date selection — a trigger button showing the chosen date, and
+a calendar grid dropdown, positioned like `Select`/`Menu`. Integrates
+with Angular forms via `ControlValueAccessor`, like `Select` and
+`Textarea`.
+
+**Selector**: `gbt-date-picker`
+
+## Inputs
+
+| Input                | Type                | Default              | Role                                                              |
+| --------------------- | -------------------- | ---------------------- | -------------------------------------------------------------------- |
+| `label`              | `string`            | `''`                  | Field label.                                                       |
+| `placeholder`        | `string`            | `'Select a date…'`    | Shown in the trigger when no date is selected.                     |
+| `locale`             | `string`            | `'en-US'`             | Passed to `Intl.DateTimeFormat` for the trigger's date, the month/year heading, and weekday names. |
+| `weekStartsOn`       | `0 \| 1`             | `1` (Monday)          | `0` for a Sunday-first week.                                        |
+| `disabled`           | `boolean`           | `false`                | —                                                                    |
+| `required`           | `boolean`           | `false`                | Appends `*` to the label.                                          |
+| `errorMessage`       | `string \| null`     | `null`                | Rendered as `role="alert"` below the field.                        |
+| `previousMonthLabel` | `string`            | `'Previous month'`    | Accessible name of the "go back a month" button.                   |
+| `nextMonthLabel`     | `string`            | `'Next month'`        | Accessible name of the "go forward a month" button.                |
+| `clearable`          | `boolean`           | `false`                | Shows a clear button in place of the calendar icon once a date is selected. |
+| `clearLabel`         | `string`            | `'Clear date'`         | Accessible name of the clear button.                                |
+| `visibleMonths`      | `1 \| 2`             | `1`                     | Shows one or two consecutive months side by side.                   |
+| `monthSelectLabel`   | `string`            | `'Month'`               | Accessible name of the month dropdown.                              |
+| `yearSelectLabel`    | `string`            | `'Year'`                | Accessible name of the year dropdown.                               |
+| `minYear`/`maxYear`  | `number`            | current year ∓ 100/+10  | Bounds the year dropdown's options.                                 |
+
+## Example
+
+```html
+<gbt-date-picker label="Appointment date" [formControl]="date" />
+```
+
+## Behavior
+
+- The trigger is a plain button showing the formatted date (or the
+  placeholder) — not an editable text field. Typing a date string
+  would need locale-aware parsing this component doesn't attempt; the
+  calendar is the only way to set a value.
+- Keyboard, inside the open grid: `ArrowLeft`/`Right`/`Up`/`Down` move
+  focus by a day/week, rolling into the next or previous month at the
+  edges; `Home`/`End` jump to the start/end of the focused week;
+  `PageUp`/`PageDown` shift the view a month; `Shift+PageUp`/`PageDown`
+  shift a year; `Enter`/`Space` select the focused day. This matches
+  the WAI-ARIA "Date Picker Dialog" pattern.
+- Clicking a leading/trailing day from an adjacent month (shown dimmed)
+  selects it and shifts the view to that month.
+- `Escape` and an outside click close the panel without changing the
+  value; `Escape` also returns focus to the trigger.
+- With `clearable`, a clear button replaces the calendar icon once a
+  date is selected — same position, so nothing shifts. It's a separate
+  button next to the trigger, not inside it (a `<button>` can't
+  contain another interactive element), overlapping the trigger's icon
+  slot visually. Hidden while `disabled`.
+- The previous/next buttons sit on their own full-width row above the
+  calendar(s), one at each outer edge — not tied to either month's own
+  heading. With `visibleMonths="2"`, they move both visible months
+  together (the second is always the first's next month — the two
+  aren't independently navigable). Arrowing past the last day of the
+  first visible month moves focus into the second (already visible)
+  month without shifting the view; only arrowing past the *last*
+  visible month, or before the first, slides the view by one month.
+- The first visible month's heading is two native `<select>` dropdowns
+  (month, year) for jumping directly anywhere, instead of plain text —
+  reused as-is rather than nesting the library's own `Select` (a
+  floating-panel component) inside this panel's own floating panel,
+  which would multiply the positioning/z-index/outside-click concerns
+  for no real benefit here. A second visible month (with
+  `visibleMonths="2"`) keeps a plain-text heading, sized to match the
+  selects' height exactly so both calendars stay aligned.
+
+## Scope
+
+Single date only. A range picker (start/end) is [`DateRangePicker`](date-range-picker/README.md),
+a separate component rather than a mode of this one. `min`/`max` date bounds (disabling
+out-of-range days) are also out of scope: nothing in the current use cases needs them, and they're a
+straightforward addition later if one does.
+
+No date library (day.js, date-fns) is used — calendar math (month
+grid, leap years) is hand-rolled in `date-picker-calendar.ts` on top of
+native `Date`/`Intl`, consistent with the rest of this library having
+no such dependency.

package/description-list/README.md

@@ -0,0 +1,63 @@
+# DescriptionList
+
+Label/value pairs for a detail page (owner, creation date, size…),
+built on the semantic `<dl>`/`<dt>`/`<dd>` elements rather than a
+`<table>`. For a list of _records_ instead of a single item's
+attributes, use `Table` or `DimensionCard`.
+
+**Selector**: `gbt-description-list`
+
+## Inputs
+
+| Input        | Type                                                        | Default      | Role                                                                                                                                                                                                                                                                                |
+| ------------ | ----------------------------------------------------------- | ------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `items`      | `{ term: string; value: string \| TemplateRef<unknown> }[]` | required     | Each pair. `value` is either plain text, or a `TemplateRef` for rich content (a `Badge`, a link, …).                                                                                                                                                                                |
+| `layout`     | `'stacked' \| 'inline'`                                     | `'stacked'`  | `stacked`: term above value. `inline`: term left, value right, in a two-column grid. Falls back to `stacked` below 768px either way (see `responsive`).                                                                                                                             |
+| `valueAlign` | `'start' \| 'end'`                                          | `'start'`    | `end` right-aligns the values (the fact-sheet look: term on the left, value on the far edge of its row). When an inline list collapses to one column, values go back to the start edge. With `layout="stacked"` the values stay on the end edge at every width (under their terms). |
+| `responsive` | `'viewport' \| 'container'`                                 | `'viewport'` | What an inline list stacks on. `viewport` (default): stacks below a 768px viewport. `container`: the list's own width — it stacks below 30rem, whatever the viewport.                                                                                                              |
+
+### `responsive="container"`
+
+The component becomes a size container (`display: block; container-type: inline-size`), so an inline
+list in a narrow card or side panel stacks even on a wide screen, and keeps two columns in a
+wide card even on a phone-sized viewport. Things to know:
+
+- The host takes the width its parent gives it. In a flex row, give it `flex: 1` or a width (a size
+  container has no intrinsic inline size of its own).
+- Browsers without container queries (`@supports (container-type: inline-size)` false) ignore the
+  option: the list stays on two columns at every width. Every evergreen browser has supported them
+  since early 2023.
+- It is opt-in: with the default `viewport`, the list only uses the plain viewport media query described above.
+
+## Example
+
+```html
+<ng-template #statusValue>
+  <gbt-badge variant="success">Actif</gbt-badge>
+</ng-template>
+
+<gbt-description-list
+  layout="inline"
+  [items]="[
+    { term: 'Propriétaire', value: 'Ada Lovelace' },
+    { term: 'Créé le', value: '12 mars 2024' },
+    { term: 'Statut', value: statusValue },
+  ]"
+/>
+```
+
+```ts
+statusValue = viewChild.required<TemplateRef<unknown>>('statusValue')
+```
+
+## Why `items` + `TemplateRef`, not projected `<gbt-description-list-item>`s
+
+`<dl>` may only directly contain `<dt>`/`<dd>` (or a `<div>` wrapping a
+pair) — axe flags any other element, including a custom element set to
+`display: contents`, as an invalid child, because that CSS property
+changes rendering, not the actual DOM parent/child relationship the HTML
+content model and ARIA role mapping both depend on. Rendering every
+`<dt>`/`<dd>` directly from this component's own template (via `items`)
+keeps them genuine direct children of `<dl>` while still supporting rich
+values, which is why `value` accepts a `TemplateRef` instead of a
+projected `<gbt-description-list-item>`.

package/dimension-card/README.md

@@ -0,0 +1,39 @@
+# DimensionCard
+
+Dimension table, with the hovered row accented — a decorative accent
+only, everything it highlights is already in the visible table; its rows
+are therefore not focusable.
+
+**Selector**: `gbt-dimension-card`
+
+Standalone, outside the dataviz base: no tooltip, no keyboard
+navigation, no separate `sr-only` table — `gbt-dimension-card` **is**
+already a real, visible table.
+
+## Inputs
+
+| Input          | Type             | Role                                          |
+| -------------- | ---------------- | --------------------------------------------- |
+| `rows`         | `DimensionRow[]` | Required. `{ label, value, display? }` rows.  |
+| `caption`      | `string`         | Required. Table caption.                      |
+| `labelColumn`  | `string`         | Required. Header of the label column.         |
+| `valueColumn`  | `string`         | Required. Header of the value column.         |
+| `emptyMessage` | `string`         | Required. Message shown when `rows` is empty. |
+| `locale`       | `string`         | Required. Locale used to format numbers.      |
+
+A row's `display` replaces the formatted number in the value column, for
+values a locale-aware number format can't express — bytes, durations, a
+currency. The bar still scales on `value`, so the comparison stays honest.
+
+## Example
+
+```html
+<gbt-dimension-card
+  [rows]="[{ label: 'Europe', value: 4200 }, { label: 'Amériques', value: 3100 }]"
+  caption="Requêtes par région"
+  labelColumn="Région"
+  valueColumn="Requêtes"
+  emptyMessage="Aucune donnée"
+  locale="fr-FR"
+/>
+```

package/disclosure/README.md

@@ -0,0 +1,48 @@
+# Disclosure
+
+A single disclosure: a toggle button and the panel it shows or hides ("Advanced options", "Files", "More
+details"). It is [`gbt-accordion-item`](../accordion-item/README.md) without the accordion around it: no parent
+group, no index, an `open` model you can bind.
+
+**Selector**: `gbt-disclosure`
+
+## Inputs
+
+| Input          | Type                            | Default      | Role                                                                                                    |
+| -------------- | ------------------------------- | ------------ | ------------------------------------------------------------------------------------------------------- |
+| `label`        | `string`                        | —            | Required. The text of the toggle.                                                                       |
+| `open`         | `boolean` (model)               | `false`      | Whether the panel is shown. Two-way: `[(open)]`.                                                        |
+| `icon`         | `string \| null`                | `null`       | Registered icon name before the label.                                                                  |
+| `appearance`   | `'bordered' \| 'plain'`         | `'bordered'` | `bordered`: a framed box with a tinted panel. `plain`: only the toggle and the panel.                   |
+| `headingLevel` | `2 \| 3 \| 4 \| 5 \| 6 \| null` | `null`       | Wraps the toggle in a heading of that level (when the disclosure titles a section). `null`: no heading. |
+
+`openChange` is emitted by the model each time the user toggles.
+
+## Pattern
+
+The ARIA disclosure pattern, on the repo's accordion-item ground:
+
+- a native `<button type="button">` with `aria-expanded` and `aria-controls` (Enter and Space work natively);
+- a panel that is **`inert` while closed** (nothing in it can be focused or read) and `visibility: hidden`
+  once the 200 ms collapse has run;
+- a chevron that turns (not under `prefers-reduced-motion`).
+
+The panel's content is always instantiated: a heavy component inside is created while closed. Wrap it in
+`@if (open())` if that matters (the `open` model is right there).
+
+## Example
+
+```html
+<gbt-disclosure label="Advanced options" [(open)]="advancedOpen">
+  <gbt-switch label="CI enabled" [(ngModel)]="ciEnabled" />
+  <gbt-input label="Pipeline file path" [(ngModel)]="pipelineFile" />
+</gbt-disclosure>
+
+<gbt-disclosure label="Danger zone" icon="alert-triangle" [headingLevel]="3">…</gbt-disclosure>
+```
+
+## Accessibility
+
+See [AUDIT.md](AUDIT.md). Not covered: a disclosure that is open at a wide width and collapsible only on a
+phone (the file view's "Files" toggle) is a layout decision of the page: bind `[open]` to a breakpoint signal
+you own.

package/divider/README.md

@@ -0,0 +1,31 @@
+# Divider
+
+A thin separating line between sections or list items, with an
+optional centered label (e.g. "OR" between two sign-in buttons).
+
+**Selector**: `gbt-divider`
+
+## Inputs
+
+| Input         | Type                          | Default        | Role                                                         |
+| ------------- | ------------------------------ | ---------------- | --------------------------------------------------------------- |
+| `orientation` | `'horizontal' \| 'vertical'`   | `'horizontal'`   | `vertical` needs a defined height from its context — it stretches to fill it (`align-self: stretch`), it doesn't invent one. |
+| `label`       | `string`                       | `''`             | Optional text centered between two line segments.               |
+
+## Example
+
+```html
+<gbt-divider />
+<gbt-divider label="OR" />
+<gbt-divider orientation="vertical" />
+```
+
+## Behavior
+
+- `role="separator"`, with `aria-orientation="vertical"` only for the
+  vertical case — `horizontal` is the ARIA default, so the attribute
+  is omitted rather than stated redundantly.
+- A vertical divider inside a flex row needs the row to give it a
+  height (e.g. via `align-items: stretch`, the flex default, or an
+  explicit height on the row) — it has none of its own to fall back
+  on.

package/drawer/README.md

@@ -0,0 +1,49 @@
+# Drawer
+
+Side panel that slides in from an edge of the screen — traps focus,
+closes on Escape or a click on the backdrop, same control pattern as
+`Modal`. Unlike `Modal` (centered, blocks the whole page for a focused
+task), `Drawer` is for application content that sits alongside the
+page — a detail panel, advanced filters.
+
+**Selector**: `gbt-drawer`
+
+## Inputs
+
+| Input          | Type                                     | Default   | Role                                            |
+| -------------- | ----------------------------------------- | --------- | ------------------------------------------------ |
+| `isOpen`       | `boolean`                                 | required  | Open/closed state, driven by the application.     |
+| `edge`         | `'right' \| 'left' \| 'top' \| 'bottom'`  | `'right'` | Which edge the panel slides in from.               |
+| `heading`      | `string`                                  | `''`      | Panel title.                                       |
+| `headingLevel` | `1 \| 2 \| 3 \| 4 \| 5 \| 6`              | `2`       | Level of the rendered heading.                     |
+| `closeLabel`   | `string`                                  | `'Close'` | Accessible name of the close button.               |
+
+## Outputs
+
+| Output   | Type   | Role                                                                                                                                     |
+| -------- | ------ | ------------------------------------------------------------------------------------------------------------------------------------------ |
+| `closed` | `void` | Emitted on Escape, a click outside the panel, or a click on the close button. The application must respond by setting `isOpen` to `false`. |
+
+## Example
+
+```html
+<gbt-drawer [isOpen]="open()" edge="right" heading="Filtres" (closed)="open.set(false)">
+  Contenu du tiroir.
+</gbt-drawer>
+```
+
+## Behavior
+
+- Slides in/out with a matching backdrop fade (200ms), instead of
+  appearing/disappearing instantly like `Modal` — the panel stays
+  mounted for the closing animation's duration after `isOpen` becomes
+  `false`, then unmounts and returns focus, exactly like `Modal`
+  otherwise does immediately. Both animations are skipped under
+  `prefers-reduced-motion: reduce`.
+- Sized `min(90vw, 400px)` for `left`/`right`, `min(90vh, 400px)` for
+  `top`/`bottom` — adapts to the viewport with a fixed cap, same
+  reasoning as `Modal`'s own `min(90vw, 480px)` dialog width.
+- `AppShell`'s own mobile navigation drawer is a separate,
+  independent implementation, not built on `gbt-drawer`: its needs (a
+  fixed nav-link list, no arbitrary content) are narrower than this
+  component's.

package/empty-state/README.md

@@ -0,0 +1,84 @@
+# EmptyState
+
+A placeholder shown instead of an empty list/grid: an illustration, a
+heading, an optional message, and an optional action (a button)
+projected as content — used to distinguish "there is genuinely nothing
+here yet" from a plain "no results" text message.
+
+**Selector**: `gbt-empty-state`
+
+## Inputs
+
+| Input              | Type                                 | Default     | Role                                                                                                                                        |
+| ------------------ | ------------------------------------ | ----------- | ------------------------------------------------------------------------------------------------------------------------------------------- |
+| `illustration`     | `EmptyStateIllustration`             | `null`      | One of `'folder' \| 'star' \| 'checklist' \| 'merge' \| 'pipeline' \| 'tag' \| 'book' \| 'server'`. Optional. |
+| `heading`          | `string`                             | —           | Required. The primary message.                                                                                                              |
+| `message`          | `string`                             | `''`        | Optional secondary text, e.g. a hint or call to action description.                                                                         |
+| `icon`             | `string \| null`                     | `null`      | A registered icon name on a soft disc, in place of the artwork (ignored when an `illustration` is set).                                    |
+| `size`             | `'default' \| 'compact'`             | `'default'` | `compact` is the in-card block: smaller disc/artwork, tighter padding and type.                                                             |
+| `tone`             | `'default' \| 'error'`               | `'default'` | `error` tints the disc (or the artwork) in the error colours — a list that could not be loaded.                                             |
+| `headingLevel`     | `1 \| 2 \| 3 \| 4 \| 5 \| 6 \| null` | `null`      | Renders the heading as an `h1`…`h6` (default: a `<p>`).                                                                                     |
+| `headingId`        | `string \| null`                     | `null`      | `id` of the heading element, so a region can use `aria-labelledby`.                                                                         |
+| `headingFocusable` | `boolean`                            | `false`     | Gives the heading `tabindex="-1"` (a programmatic focus target, not a tab stop; it shows no focus ring, being no control).                  |
+
+## Methods
+
+| Method           | Role                                                                                                                                    |
+| ---------------- | --------------------------------------------------------------------------------------------------------------------------------------- |
+| `focusHeading()` | Moves focus to the heading — needs `headingFocusable`. For a result page (activation done, link expired) that moves focus to its title. |
+
+## Content
+
+An optional action (typically a `<gbt-button>`) is projected via
+`<ng-content />`, rendered below the message.
+
+## Example
+
+```html
+<gbt-empty-state
+  illustration="folder"
+  heading="Aucun dépôt pour l'instant"
+  message="Créez votre premier dépôt pour commencer."
+>
+  <gbt-button text="Nouveau dépôt" (clicked)="openCreate()" />
+</gbt-empty-state>
+```
+
+## Icon, compact and in-card states
+
+The 96 px artwork suits a whole page or an empty list. Inside a card, use the
+compact block with an icon:
+
+```html
+<gbt-card variant="outlined" heading="Variables" flush>
+  <gbt-empty-state
+    size="compact"
+    icon="key"
+    heading="Aucune variable définie"
+    message="Les variables sont injectées dans chaque job."
+  />
+</gbt-card>
+
+<gbt-empty-state size="compact" tone="error" icon="alert-circle" heading="Chargement impossible">
+  <gbt-button variant="secondary" size="small" text="Réessayer" (clicked)="retry()" />
+</gbt-empty-state>
+```
+
+With neither `illustration` nor `icon` a compact state is a bare heading (and
+message): the "Not found." block.
+
+## Heading level
+
+By default the heading is a `<p>` — the component cannot know where it sits in
+your page outline. Pass `headingLevel` when the state stands for a section (or
+the whole page, `1`), and `headingId` to name a surrounding `<section>`.
+
+## Choosing an illustration
+
+Each illustration is a fixed, curated piece of art shipped by Gabarit —
+not an extensible registry like `gbt-icon`'s. Pick whichever of the
+eight best matches the empty collection: `folder` for
+repositories/groups, `star` for a starred/favorites list, `checklist`
+for issues, `merge` for merge/pull requests, `pipeline` for CI
+pipelines, `tag` for releases, `book` for a wiki, `server` for
+infrastructure (e.g. CI runners).