@masmarino/gabarit 2.0.0 → 2.1.1

package/select/README.md

@@ -0,0 +1,61 @@
+# Select
+
+Dropdown list, single or multiple selection. Integrated with reactive
+forms and `ngModel`.
+
+**Selector**: `gbt-select`
+
+## Inputs
+
+| Input                | Type                        | Default                    | Role                                                                                                                                                                                                                                                                                                                                                         |
+| -------------------- | --------------------------- | -------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| `id`                 | `string`                    | generated (`gbt-select-N`) | DOM id, associates the `<label>`.                                                                                                                                                                                                                                                                                                                            |
+| `label`              | `string`                    | `''`                       | Visible label.                                                                                                                                                                                                                                                                                                                                               |
+| `hint`               | `string`                    | `''`                       | Help text under the field, linked to the trigger with `aria-describedby`. Hidden (and unlinked) while an error shows.                                                                                                                                                                                                                                        |
+| `hideLabel`          | `boolean`                   | `false`                    | Hides the label visually; it stays in the DOM and keeps naming the trigger.                                                                                                                                                                                                                                                                                  |
+| `fullWidth`          | `boolean`                   | `false`                    | Stretches the field to the width of its container (the default sizes to the content, 180px minimum).                                                                                                                                                                                                                                                         |
+| `size`               | `'md' \| 'sm'`              | `'md'`                     | The trigger is 38px tall (`md`) or 32px (`sm`, for compact contexts like a table's rows-per-page selector, see `Pagination`): the shared `--gbt-control-height-md` / `-sm` scale, level with `gbt-input` and `gbt-button` of the same tier.                                                                                                                  |
+| `options`            | `SelectOption<T>[]`         | required                   | `{ value, label, icon?, color? }` — the offered options.                                                                                                                                                                                                                                                                                                     |
+| `multiple`           | `boolean`                   | `false`                    | Multiple selection.                                                                                                                                                                                                                                                                                                                                          |
+| `chips`              | `boolean`                   | `false`                    | When `true` together with `multiple`, renders selected options as removable colored chips below the trigger instead of a collapsed count label. Each option's `color` field sets its chip color (a 6-digit hex — see `Tag`); options without one default to a neutral grey. When the field is disabled the chips stay visible but lose their remove buttons. |
+| `placeholder`        | `string`                    | `'Select…'`                | Text shown with no selection.                                                                                                                                                                                                                                                                                                                                |
+| `disabled`           | `boolean`                   | `false`                    | Disables the field.                                                                                                                                                                                                                                                                                                                                          |
+| `required`           | `boolean`                   | `false`                    | Native `required` attribute.                                                                                                                                                                                                                                                                                                                                 |
+| `errorMessage`       | `string \| null`            | `null`                     | Error message shown under the field.                                                                                                                                                                                                                                                                                                                         |
+| `selectedCountLabel` | `(count: number) => string` | `` `${count} selected` ``  | Trigger label in multiple-selection mode, beyond a single item. In `chips` mode the trigger shows the placeholder instead, and this string is what the screen-reader status region announces as chips are added or removed.                                                                                                                                  |
+| `chipRemoveLabel`    | `(label: string) => string` | `` `Remove ${label}` ``    | Accessible label of each chip's remove button, in `chips` mode.                                                                                                                                                                                                                                                                                              |
+| `noOptionsMessage`   | `string`                    | `'No options'`             | Shown in place of the listbox when `options` is empty and the panel is opened.                                                                                                                                                                                                                                                                              |
+
+## Hint, hidden label, full width
+
+```html
+<gbt-select
+  label="Visibility"
+  hint="Who can see this repository."
+  [fullWidth]="true"
+  [options]="options"
+  formControlName="visibility"
+/>
+
+<gbt-select
+  label="Sort by"
+  [hideLabel]="true"
+  size="sm"
+  [options]="sortOptions"
+  formControlName="sort"
+/>
+```
+
+With `errorMessage` set the hint is not rendered and the trigger's
+`aria-describedby` points at the error only (chips mode's chip row is
+unaffected and still renders in the list).
+
+## Example
+
+```html
+<gbt-select
+  label="Rôle"
+  [options]="[{ value: 'read', label: 'Lecture' }, { value: 'admin', label: 'Administration' }]"
+  formControlName="role"
+/>
+```

package/skeleton/README.md

@@ -0,0 +1,49 @@
+# Skeleton
+
+Animated placeholder that echoes the shape of content still loading —
+a line of text, a circle, or a rectangle. Combine several to mimic a
+table row, a list item, or a card, instead of a generic spinner
+unrelated to what's about to appear.
+
+**Selector**: `gbt-skeleton`
+
+## Inputs
+
+| Input     | Type                          | Default | Role                                                                 |
+| --------- | ----------------------------- | ------- | --------------------------------------------------------------------- |
+| `variant` | `'text' \| 'circle' \| 'rect'` | `'text'` | Shape: rounded line, perfect circle (`aspect-ratio: 1`, sized by `width`), or rounded rectangle. |
+| `width`   | `string`                      | `'100%'` | Any CSS length (`'240px'`, `'60%'`, …).                              |
+| `height`  | `string \| null`               | `null`  | Any CSS length. Left unset, each variant falls back to a sensible default (`1em` for `text`, matches `width` for `circle`, `100px` for `rect`). |
+
+## Example
+
+```html
+<gbt-skeleton variant="text" width="60%" />
+<gbt-skeleton variant="circle" width="40px" />
+<gbt-skeleton variant="rect" width="100%" height="140px" />
+```
+
+## Composing a placeholder layout
+
+There's no dedicated `TableSkeleton` or `CardSkeleton` — combine plain
+`gbt-skeleton`s instead, e.g. a card:
+
+```html
+<div role="status" aria-label="Loading">
+  <gbt-skeleton variant="rect" width="100%" height="140px" />
+  <gbt-skeleton variant="text" width="80%" />
+  <gbt-skeleton variant="text" width="50%" />
+</div>
+```
+
+## Behavior
+
+- A soft highlight band sweeps left to right across the shape to
+  signal "loading"; the animation is disabled under
+  `prefers-reduced-motion: reduce` (the shape stays visible, flat,
+  with no motion).
+- Each `gbt-skeleton` sets `aria-hidden="true"` on itself — a screen
+  reader is never told about a dozen individual placeholder shapes.
+  Wrap the group in a single `role="status"` container with a label
+  (as in the example above) so "Loading" is announced once for the
+  whole layout, not once per shape.

package/skeleton-list/README.md

@@ -0,0 +1,40 @@
+# SkeletonList
+
+The placeholder of a list while it loads: `rows` rows of an optional leading block (a status dot, an
+avatar) and one to three text lines, at the rhythm of a real list row.
+
+**Selector**: `gbt-skeleton-list`. Built on [`gbt-skeleton`](../skeleton/README.md). `gbt-list-card`
+draws its own loading state; use this one in a settings section, a panel, a table body or any bordered box.
+
+## Inputs
+
+| Input          | Type                             | Default      | Role                                                                            |
+| -------------- | -------------------------------- | ------------ | ------------------------------------------------------------------------------- |
+| `rows`         | `number`                         | `4`          | Number of placeholder rows (`0` or less: none, only the status).                |
+| `leading`      | `'circle' \| 'square' \| 'none'` | `'circle'`   | The block before the lines: a dot or avatar, a square, or nothing.              |
+| `leadingSize`  | `string`                         | `'1rem'`     | Its size (`1rem` a status dot, `2.25rem` an avatar).                            |
+| `lines`        | `1 \| 2 \| 3`                    | `2`          | Text lines per row. The first is the longest; its width varies from row to row. |
+| `loadingLabel` | `string`                         | `'Loading…'` | Read out (visually hidden, polite) while loading.                               |
+| `divided`      | `boolean`                        | `true`       | A hairline between rows.                                                        |
+| `padded`       | `boolean`                        | `true`       | 1 rem of side padding (a row inside a card). Turn it off in a bare list.        |
+
+## Behaviour and accessibility
+
+- A `role="status"` region with `loadingLabel` is always rendered; the shapes are `aria-hidden`.
+- **No `aria-busy`**: it would sit on an ancestor of the status region, and assistive technology may then hold
+  the announcement back until the busy state ends, which is exactly when the announcement is useless.
+- Placeholders animate with `gbt-skeleton`'s shimmer, which stops under `prefers-reduced-motion`.
+
+## Example
+
+```html
+@if (loading()) {
+<gbt-skeleton-list [rows]="3" leadingSize="2.25rem" loadingLabel="Chargement des membres…" />
+} @else {
+<ul>
+  …
+</ul>
+}
+```
+
+See [AUDIT.md](AUDIT.md).

package/slider/README.md

@@ -0,0 +1,44 @@
+# Slider
+
+A numeric value picked by dragging — a styled native
+`<input type="range">`, integrated with Angular forms via
+`ControlValueAccessor`, like `Select`.
+
+**Selector**: `gbt-slider`
+
+## Inputs
+
+| Input         | Type                          | Default                | Role                                                    |
+| -------------- | ------------------------------ | ------------------------- | ----------------------------------------------------------- |
+| `label`       | `string`                       | required                  | Field label — also the accessible name of the range input. |
+| `min`/`max`   | `number`                       | `0` / `100`                | Bounds.                                                      |
+| `step`        | `number`                       | `1`                         | Increment.                                                   |
+| `disabled`    | `boolean`                      | `false`                     | —                                                             |
+| `errorMessage`| `string \| null`                | `null`                       | Rendered as `role="alert"` below the slider.                 |
+| `showValue`   | `boolean`                      | `true`                       | Shows the current value next to the label.                   |
+| `formatValue` | `(value: number) => string`    | `(v) => \`${v}\``            | Formats the displayed value (e.g. `€`, `%`).                  |
+
+## Example
+
+```html
+<gbt-slider label="Budget" [min]="0" [max]="1000" [step]="50" [formatValue]="formatEuros" [formControl]="budget" />
+```
+
+## Behavior
+
+- Built on a native `<input type="range">`, not a custom
+  `role="slider"` widget — keyboard operability (arrows, Home/End,
+  Page Up/Down) and screen reader support come from the browser for
+  free, at the cost of styling it (done here via
+  `::-webkit-slider-thumb`/`::-moz-range-thumb` and friends) rather
+  than building a widget from scratch.
+- `label` is required: a slider with no accessible name is
+  meaningless to a screen reader, and there's no universal generic
+  default text a value-picker could fall back to (unlike `Spinner`'s
+  `'Loading…'`).
+
+## Scope
+
+Single value only. A two-handle range slider (min/max) was
+deliberately left for a separate iteration if a real use case comes
+up, the same reasoning `DatePicker` applied to a date-range picker.

package/sparkline/README.md

@@ -0,0 +1,37 @@
+# Sparkline
+
+Fixed-size trend mini-chart — built to live in a table cell, where a
+`ResizeObserver` per row would be expensive for a width the caller
+already knows.
+
+**Selector**: `gbt-sparkline`
+
+Standalone, outside the dataviz base — no tooltip or keyboard
+navigation in the base's sense, but **focusable** and given an
+accessible name, with its own visually-hidden `gbt-chart-table`.
+
+## Inputs
+
+| Input          | Type       | Default  | Role                                        |
+| -------------- | ---------- | -------- | ------------------------------------------- |
+| `values`       | `number[]` | required | Series values, in order.                    |
+| `tableCaption` | `string`   | required | Caption of the component's `sr-only` table. |
+| `xColumn`      | `string`   | required | Header of that table's x-axis column.       |
+| `yColumn`      | `string`   | required | Header of that table's value column.        |
+| `locale`       | `string`   | required | Locale used to format numbers.              |
+| `emptyMessage` | `string`   | required | Message shown when `values` is empty.       |
+| `width`        | `number`   | `80`     | Width in pixels.                            |
+| `height`       | `number`   | `24`     | Height in pixels.                           |
+
+## Example
+
+```html
+<gbt-sparkline
+  [values]="[12, 18, 9, 24, 30]"
+  tableCaption="Requêtes des 7 derniers jours"
+  xColumn="Jour"
+  yColumn="Requêtes"
+  locale="fr-FR"
+  emptyMessage="Aucune donnée"
+/>
+```

package/spinner/README.md

@@ -0,0 +1,41 @@
+# Spinner
+
+A standalone loading indicator, for use anywhere `Button`'s own
+internal spinner doesn't reach — a card, a panel, a whole page section
+— and `Skeleton` (which echoes the shape of content still loading)
+isn't a fit, typically because there's no known destination layout to
+echo yet.
+
+**Selector**: `gbt-spinner`
+
+## Inputs
+
+| Input   | Type                   | Default      | Role                                           |
+| ------- | ----------------------- | -------------- | ------------------------------------------------- |
+| `size`  | `'sm' \| 'md' \| 'lg'`   | `'md'`         | 16px / 24px / 40px.                                |
+| `label` | `string`                | `'Loading…'`   | Announced once via `role="status"`, visually hidden. |
+
+## Example
+
+```html
+<gbt-spinner size="lg" label="Loading results…" />
+```
+
+## Behavior
+
+- `role="status"` with a visually-hidden label — announced once,
+  unlike `Skeleton`'s "no live announcement per shape" stance, since a
+  spinner is usually the *only* loading cue on screen, not one of a
+  dozen placeholder shapes needing a single shared announcement.
+- The ring inherits `color` (`--primary` by default) — set `color` on
+  an ancestor to recolor it, e.g. inside a button with a colored
+  background.
+- The ring is two layers: a faint static track (`::before`, 15%
+  opacity) and the spinning arc on top (`::after`) — an arc alone,
+  with no track, reads as "a circle with a bite taken out of it"
+  rather than as motion over a fixed shape.
+
+## Relationship to `Button`'s own spinner
+
+`Button`'s internal loading spinner stays private and independent — the same call made for
+`AppShell`'s mobile drawer versus `Drawer`: a separate, independent implementation.

package/stat-grid/README.md

@@ -0,0 +1,47 @@
+# StatGrid
+
+A responsive grid of [`gbt-stat-tile`](../stat-tile/README.md)s: two columns, and up to `columns` once the grid
+is 600 px wide.
+
+**Selector**: `gbt-stat-grid`
+
+## Inputs
+
+| Input          | Type                    | Default      | Role                                                          |
+| -------------- | ----------------------- | ------------ | ------------------------------------------------------------- |
+| `ariaLabel`    | `string`                | `'Summary'`  | Names the list of tiles.                                      |
+| `columns`      | `2 \| 3 \| 4 \| 5 \| 6` | `4`          | Columns once the grid is 600 px wide or more (below that: 2). |
+| `loading`      | `boolean`               | `false`      | Shows placeholder tiles instead of the projected tiles.       |
+| `loadingCount` | `number`                | `4`          | Number of placeholder tiles. `0` or less: none, only the status region (same convention as `SkeletonList`'s `rows`). |
+| `loadingLabel` | `string`                | `'Loading…'` | Read out (visually hidden, polite) while `loading`.           |
+
+## Behaviour
+
+- **Container query**: `container: gbt-stat-grid / inline-size`, breakpoint at 600 px of the GRID's width (custom
+  properties cannot be read in a container condition, so it is fixed). A grid in a 700 px column next to an aside
+  behaves like a grid on a 700 px page. The `MediumFrame` and `NarrowFrame` stories show it.
+- **Containment side effect**: `container-type: inline-size` also applies layout containment to the grid, so a
+  `position: fixed` descendant (a popover or menu panel inside a tile) is placed against the grid, not the viewport.
+  Keep fixed-position overlays out of the tiles.
+- **List semantics**: `role="list"` named by `ariaLabel`; the tiles are its `role="listitem"`s (a tile detects
+  its grid by injection: it gets the role only there).
+- **Loading**: placeholders have a loaded tile's border, radius and padding, so nothing moves when the figures
+  arrive. The real tiles are not rendered meanwhile; the list is `aria-hidden` and a `role="status"` region
+  (outside the list, always in the DOM) says `loadingLabel`. No `aria-busy` is set: some assistive technology
+  would hold the status back.
+- Tiles project directly into the grid: `<gbt-stat-tile>` elements as direct children (a wrapper `div` would
+  lose the list-item role).
+
+## Example
+
+```html
+<gbt-stat-grid ariaLabel="Overview" [columns]="4" [loading]="!stats()">
+  @for (tile of stats(); track tile.key) {
+  <gbt-stat-tile [label]="tile.label" [value]="tile.value" [icon]="tile.icon" />
+  }
+</gbt-stat-grid>
+```
+
+## Accessibility
+
+See [AUDIT.md](AUDIT.md).

package/stat-tile/README.md

@@ -0,0 +1,75 @@
+# StatTile
+
+A figure with its label: "12 open issues", "3.4 GB stored". The figure and an optional icon marker on
+top, the label under them, then an optional hint and trend.
+
+**Selector**: `gbt-stat-tile`, plus the router-agnostic link anchor `a[gbtStatTileLink]` (class `StatTileLink`,
+import it to get the stretched hit area). Put tiles in a [`gbt-stat-grid`](../stat-grid/README.md).
+
+## Inputs
+
+| Input        | Type                                | Default     | Role                                                                                                   |
+| ------------ | ----------------------------------- | ----------- | ------------------------------------------------------------------------------------------------------ |
+| `label`      | `string`                            | `''`        | The label under the figure. Not needed when a `gbtStatTileLink` is projected (its text is the label).  |
+| `value`      | `string \| number`                  | —           | Required. The figure, shown as is (format it: `1,284`, `3.4 GB`).                                      |
+| `icon`       | `string \| null`                    | `null`      | Registered icon name, on a tile-shaped [`gbt-icon-marker`](../icon-marker/README.md).         |
+| `iconTone`   | `IconMarkerTone`                    | `'info'`    | Tone of that marker.                                                                                   |
+| `hint`       | `string \| null`                    | `null`      | A precision under the label ("last 30 days").                                                          |
+| `trend`      | `'up' \| 'down' \| 'flat' \| null`  | `null`      | An arrow. Shown only with a `trendLabel`.                                                              |
+| `trendLabel` | `string \| null`                    | `null`      | The trend as text, with its sign or wording ("+12 %"): an arrow alone says nothing to a screen reader. |
+| `trendTone`  | `'neutral' \| 'success' \| 'error'` | `'neutral'` | Colours the trend by whether the movement is good or bad, whichever the direction.                     |
+| `href`       | `string \| null`                    | `null`      | Turns the label into a link whose hit area is the whole tile.                                          |
+| `muted`      | `boolean`                           | `false`     | The tile steps back (quiet figure, neutral marker): a category with nothing in it.                     |
+
+## Reading order
+
+The label comes **first in the DOM**, the figure second (the grid areas put the figure on top): a screen
+reader says "Open issues, 12". Do not swap them.
+
+## Link
+
+`href` renders the label as an anchor. With a router, project the anchor and let it replace the label:
+
+```html
+<gbt-stat-tile [value]="issues().length" icon="circle-dot">
+  <a gbtStatTileLink [routerLink]="['/issues']">Open issues</a>
+</gbt-stat-tile>
+```
+
+If you forget to import `StatTileLink`, the projected anchor is still rendered with its text (the selector matches the
+attribute), only unstyled: no stretched hit area and no tile hover, so a missing import is visible, never a silent empty label.
+
+The anchor's `::after` covers the tile (the tile is `position: relative`); its keyboard focus outlines the
+whole tile. No interactive element is nested in another.
+
+## Narrow tiles
+
+The tile is a size container named `gbt-stat-tile`: under 11 rem it tightens its padding and uses a smaller
+figure (1.375 rem) so `1,284` is not cut, whatever the grid or the viewport. A figure that is still too long is
+cut with an ellipsis, never overflowing. A tile outside a grid needs a definite width (a block).
+
+**Containment side effect.** `container-type: inline-size` also applies layout containment to the host: a
+`position: fixed` descendant (a popover, tooltip or menu panel projected into the tile) is placed against the tile,
+not the viewport. Do not put a fixed-position overlay inside a tile; open it from outside (or use a native popover
+in the top layer).
+
+## Example
+
+```html
+<gbt-stat-grid ariaLabel="Summary">
+  <gbt-stat-tile
+    label="Repositories"
+    value="1,284"
+    icon="folder"
+    hint="last 30 days"
+    trend="up"
+    trendLabel="+12 %"
+    trendTone="success"
+  />
+  <gbt-stat-tile label="Storage used" value="3.4 GB" icon="database" />
+</gbt-stat-grid>
+```
+
+## Accessibility
+
+See [AUDIT.md](AUDIT.md).

package/stepper/README.md

@@ -0,0 +1,67 @@
+# Stepper
+
+An informational progress indicator through numbered steps (a
+checkout tunnel, a multi-screen setup wizard) — distinct from
+`SegmentedControl` (an exclusive choice) and `Tabs` (free navigation
+between contents): a step can't be skipped, and this component itself
+never navigates anywhere.
+
+**Selector**: `gbt-stepper`
+
+## Inputs
+
+| Input            | Type                            | Default       | Role                                                          |
+| ----------------- | --------------------------------- | --------------- | ------------------------------------------------------------------ |
+| `steps`          | `{ label: string; hasError?: boolean }[]` | required        | The steps, in order.                                                |
+| `activeIndex`    | `number` (model)                  | `0`               | The current step's index.                                          |
+| `orientation`    | `'horizontal' \| 'vertical'`       | `'horizontal'`     | —                                                                    |
+| `completedLabel` | `string`                          | `'Completed'`      | Visually-hidden suffix announced for a completed step.              |
+| `errorLabel`     | `string`                          | `'Error'`           | Visually-hidden suffix announced for a step with `hasError`.        |
+| `interactive`    | `boolean`                         | `false`             | Renders each step as a native button that sets `selectedIndex`.     |
+| `selectedIndex`  | `number \| null` (model)          | `null`              | The step being viewed (interactive mode only); distinct from `activeIndex`. |
+| `selectedLabel`  | `string`                          | `'Selected'`        | Visually-hidden suffix announced for the selected step.             |
+
+## Example
+
+```html
+<gbt-stepper
+  [steps]="[{ label: 'Account' }, { label: 'Shipping' }, { label: 'Payment' }]"
+  [activeIndex]="step()"
+/>
+```
+
+## Interactive mode
+
+With `interactive`, every step becomes a real `<button type="button">`
+inside its `<li>`. Clicking one only sets `selectedIndex` — the step
+being *viewed* — while `activeIndex` stays the progress (and keeps
+`aria-current="step"`). The consumer decides what a selection does:
+
+```html
+<gbt-stepper
+  [steps]="steps"
+  [activeIndex]="progress()"
+  [interactive]="true"
+  [(selectedIndex)]="viewed"
+/>
+```
+
+## Behavior
+
+- Informational by default: without `interactive`, no click handler on
+  a step and no keyboard navigation of its own — this component only
+  ever *reflects* `activeIndex`, it never changes it. With
+  `interactive`, a click only sets `selectedIndex`; `activeIndex` is
+  never modified by this component.
+- A step's status is derived purely from its position relative to
+  `activeIndex` (`completed` before it, `current` at it, `upcoming`
+  after it) and its own `hasError` — a step marked `hasError` only
+  shows as `error` once reached (at or before `activeIndex`), never
+  for a step further ahead that hasn't happened yet.
+- Renders a real `<ol>`/`<li>` list — every step is rendered directly
+  by this component's own template (via the `steps` data array, not
+  content-projected per-step components), the same reasoning
+  `DescriptionList` already applied to `<dl>`/`<dt>`/`<dd>`: axe's
+  list-structure rule requires `<li>` to be a direct child of a
+  `<ul>`/`<ol>`, which a per-step custom element (even one set to
+  `display: contents`) does not satisfy.

package/switch/README.md

@@ -0,0 +1,51 @@
+# Switch
+
+Bascule on/off — alternative visuelle à `Checkbox` pour un réglage
+binaire immédiat (ex. activer une option), plutôt qu'une sélection
+dans un formulaire à valider.
+
+**Selector**: `gbt-switch`
+
+## Inputs
+
+| Input      | Type      | Default | Role                                                                 |
+| ---------- | --------- | ------- | -------------------------------------------------------------------- |
+| `id`       | `string`  | généré  | `id` du champ natif.                                                 |
+| `label`    | `string`  | `''`    | Texte affiché à côté de la bascule.                                  |
+| `disabled` | `boolean` | `false` | Désactive le contrôle.                                               |
+| `hint`     | `string`  | `''`    | Texte d'aide sous le libellé, relié au champ par `aria-describedby`. |
+
+S'intègre aux formulaires Angular via `ControlValueAccessor`, comme
+`Checkbox` — utilisable indifféremment avec `formControlName` ou
+`[formControl]`.
+
+## Exemple
+
+```html
+<gbt-switch label="Recevoir les notifications" formControlName="notifications" />
+
+<gbt-switch
+  label="Envoyer un résumé quotidien"
+  hint="Un e-mail par jour, à 8 h."
+  formControlName="digest"
+/>
+```
+
+## Texte d'aide (`hint`)
+
+Sans `hint`, le rendu ne comporte aucun élément supplémentaire (hôte inline).
+Avec `hint`, l'hôte devient un bloc et le texte
+s'affiche sous le libellé, aligné sur celui-ci (piste 2,25 rem + espace
+0,5 rem) — plus besoin d'une indentation « magique » côté application.
+Le texte est un `<p>` **hors** du `<label>` : il décrit le champ
+(`aria-describedby`) sans s'ajouter à son nom accessible.
+
+## Accessibilité
+
+Basé sur `<input type="checkbox" role="switch">` — tout le
+comportement natif (Space pour basculer, participation aux
+formulaires, focus) est conservé ; `role="switch"` fait annoncer
+"interrupteur" par les lecteurs d'écran plutôt que "case à cocher".
+L'entrée native est visuellement masquée (`opacity: 0`) mais reste
+dans l'arbre d'accessibilité et la zone cliquable — le rendu piste +
+curseur est purement du CSS piloté par `:checked`, sans JavaScript.

package/table/README.md

@@ -0,0 +1,75 @@
+# Table
+
+Data table with optional clickable rows.
+
+**Selector**: `gbt-table`
+
+## Inputs
+
+| Input           | Type                            | Default     | Role                                               |
+| --------------- | ------------------------------- | ----------- | -------------------------------------------------- |
+| `data`          | `T[]`                           | required    | The rows.                                          |
+| `columns`       | `TableColumn<T>[]`              | required    | `{ key, label, format?, cellTemplate? }` — the columns, in order. |
+| `trackBy`       | `((row: T) => unknown) \| null` | `null`      | Row tracking function.                             |
+| `emptyMessage`  | `string`                        | `'No data'` | Message shown when `data` is empty.                |
+| `caption`       | `string`                        | required    | Table caption.                                     |
+| `clickableRows` | `boolean`                       | `false`     | Makes rows focusable and keyboard-activatable.     |
+
+## Outputs
+
+| Output     | Type | Role                                                                     |
+| ---------- | ---- | ------------------------------------------------------------------------ |
+| `rowClick` | `T`  | Emitted on click or keyboard activation of a row (`clickableRows` only). |
+
+## Example
+
+```html
+<gbt-table
+  caption="Dépôts"
+  [data]="depots"
+  [columns]="[{ key: 'nom', label: 'Nom' }, { key: 'taille', label: 'Taille' }]"
+/>
+```
+
+## Rich cell content: `cellTemplate`
+
+A column's `format`/`key` can only ever produce plain text — there is
+no way to put a link, a `Badge`, or a `Menu` in a cell through them.
+`cellTemplate` renders a `TemplateRef` instead, with the row projected
+as the template's `$implicit` context (the same escape hatch
+`DescriptionList` offers for a value, adapted here to run once per
+row):
+
+```html
+<ng-template #actionsCell let-repo>
+  <gbt-menu label="Actions" triggerIcon="ellipsis-vertical">
+    <button role="menuitem" class="gbt-menu__item" type="button" (click)="delete(repo)">Supprimer</button>
+  </gbt-menu>
+</ng-template>
+
+<gbt-table
+  caption="Dépôts"
+  [data]="depots"
+  [columns]="[
+    { key: 'nom', label: 'Nom' },
+    { key: 'actions', label: 'Actions', cellTemplate: actionsCell },
+  ]"
+/>
+```
+
+`key` still identifies the column (for `@for` tracking) even on a
+template-only column — it doesn't have to name a real property of `T`,
+a synthetic name like `'actions'` is fine since `format`/`row[key]` is
+never reached for that column.
+
+A `cellTemplate` cell is the consumer's own content, so its
+accessibility is the consumer's responsibility — same delegation
+`Table` already applies to `format`'s plain text, extended to richer
+markup. An interactive element inside a `cellTemplate` (a link, a
+`Menu` trigger) works normally with `Tab`/`Enter` since it's ordinary
+projected DOM inside a `<td>`, nothing about `Table` intercepts it.
+Combining it with `clickableRows` is supported: a click or `Enter`/`Space` on the projected
+interactive element (a native control, a `<label>`, a `<summary>`, a `contenteditable` region, or an
+element carrying an interactive WAI-ARIA widget role such as `button`, `link`, `checkbox`, `switch`,
+`radio`, `tab`, `option`, `menuitem`, `textbox`, `searchbox`, `slider`) activates that element only
+— it does not also fire `rowClick` — while the same click or key elsewhere in the row still does.

package/tabs/README.md

@@ -0,0 +1,34 @@
+# Tabs
+
+Tab navigation, with `gbt-tab` as projected content.
+
+**Selector**: `gbt-tabs` (container), `gbt-tab` (each tab)
+
+Left/right arrows to move between triggers, with wraparound.
+
+`activeIndex` is an Angular `model()`, so it works uncontrolled (omit
+the binding entirely, as every existing usage does) or controlled
+(bind `[activeIndex]`/`(activeIndexChange)` to keep it in sync with,
+e.g., a URL query parameter).
+
+## Inputs of `gbt-tabs`
+
+| Input | Type     | Default                  | Role                                                    |
+| ----- | -------- | ------------------------ | ------------------------------------------------------- |
+| `id`  | `string` | generated (`gbt-tabs-N`) | Prefix of the DOM ids generated for each trigger/panel. |
+| `activeIndex` | `number` (model) | `0` | The active tab's index. Bind `[activeIndex]` (one-way — `Tabs` still updates it internally on click/arrow-key) or `[(activeIndex)]` (two-way) to control or observe it from outside. |
+
+## Inputs of `gbt-tab`
+
+| Input   | Type     | Role                     |
+| ------- | -------- | ------------------------ |
+| `label` | `string` | Required. Trigger label. |
+
+## Example
+
+```html
+<gbt-tabs>
+  <gbt-tab label="Détails">...</gbt-tab>
+  <gbt-tab label="Historique">...</gbt-tab>
+</gbt-tabs>
+```