@masmarino/gabarit 1.4.0 → 2.1.0

package/src/lib/tokens/_themes.scss

@@ -0,0 +1,144 @@
+// The themes as mixins, with no output of their own: _semantic puts them on :root, and the parts drawn
+// on the graphite frame (the shell's rail and bar, the sign-in page) take the frame's.
+//
+// Every text token reaches 7:1 on the page and on a panel (contrast.spec.ts), which is why a few of
+// them sit a shade darker (or lighter, in the dark) than the marks of the same colour. The status
+// tints are translucent, so they take the colour of the ground they sit on.
+
+@mixin light-tokens {
+  --primary: var(--slate-900);
+  --primary-hover: #383d43;
+  --bg-principal: var(--slate-0);
+  --bg-panel: var(--slate-50);
+  --bg-hover: rgba(16, 21, 28, 0.07);
+  --bg-track: var(--slate-200);
+  --bg-inverse: var(--slate-900);
+
+  // The edge of a field or a control, 3:1 on the page (WCAG 1.4.11); the hairlines stay lighter.
+  --border-color: var(--slate-500);
+  --gbt-hairline: var(--slate-300);
+  --gbt-card-border: var(--slate-300);
+
+  --text-primary: var(--slate-900);
+  --text-secondary: var(--slate-700);
+  --text-discret: var(--slate-600);
+  --text-on-color: var(--slate-0);
+  --text-on-primary: var(--slate-0);
+  --text-on-error: var(--slate-0);
+
+  --accent: var(--rust-500);
+  --accent-text: var(--rust-600);
+  --focus-ring: var(--rust-500);
+
+  --color-success-base: var(--patina-600);
+  --color-success-text: var(--patina-700);
+  --color-success-hover: #146b50;
+  --color-success-bg: rgba(21, 128, 93, 0.12);
+  --color-success-bg-text: var(--patina-800);
+  --color-success-vivid-base: var(--patina-600);
+
+  --color-warning-base: var(--amber-600);
+  --color-warning-text: var(--amber-700);
+  --color-warning-hover: #7e4d09;
+  --color-warning-bg: rgba(154, 91, 4, 0.1);
+  --color-warning-bg-text: var(--amber-800);
+  --color-warning-vivid-base: var(--amber-600);
+
+  --color-error-base: var(--red-600);
+  --color-error-fill: var(--red-700);
+  --color-error-text: var(--red-750);
+  --color-error-hover: #842b27;
+  --color-error-bg: rgba(194, 58, 50, 0.1);
+  --color-error-bg-text: var(--red-800);
+  --color-error-vivid-base: var(--red-600);
+
+  --color-info-bg: rgba(47, 73, 201, 0.09);
+  --color-info-bg-text: var(--indigo-800);
+  --color-info-vivid-base: var(--indigo-600);
+
+  --chart-series-1-base: #bd8200;
+  --chart-series-2-base: #009e73;
+  --chart-series-3-base: #0072b2;
+  --chart-series-4-base: #a6410f;
+  --chart-series-5-base: #9c3f78;
+  --chart-series-6-base: #5b4fb0;
+  --chart-grid: var(--slate-300);
+
+  --site-shadow-sm: none;
+  --site-shadow-md: 0 0 0 1px var(--slate-400);
+  --site-shadow-lg: 0 0 0 1px var(--slate-400), 0 12px 32px rgba(16, 21, 28, 0.16);
+}
+
+@mixin dark-tokens {
+  --primary: var(--graphite-100);
+  --primary-hover: #c0c5cb;
+  --bg-principal: var(--graphite-850);
+  --bg-panel: var(--graphite-900);
+  --bg-hover: rgba(231, 235, 241, 0.07);
+  --bg-track: var(--graphite-700);
+  --bg-inverse: var(--graphite-100);
+
+  --border-color: var(--graphite-500);
+  --gbt-hairline: rgba(205, 215, 230, 0.12);
+  --gbt-card-border: rgba(205, 215, 230, 0.12);
+
+  --text-primary: var(--graphite-100);
+  --text-secondary: var(--graphite-300);
+  --text-discret: var(--graphite-400);
+  --text-on-color: var(--graphite-1000);
+  --text-on-primary: var(--graphite-1000);
+  --text-on-error: var(--graphite-1000);
+
+  --accent: var(--rust-400);
+  --accent-text: var(--rust-300);
+  --focus-ring: var(--rust-400);
+
+  --color-success-base: var(--patina-400);
+  --color-success-text: var(--patina-400);
+  --color-success-hover: #61c8a7;
+  --color-success-bg: rgba(63, 191, 149, 0.16);
+  --color-success-bg-text: var(--patina-300);
+  --color-success-vivid-base: var(--patina-400);
+
+  --color-warning-base: var(--amber-400);
+  --color-warning-text: var(--amber-400);
+  --color-warning-hover: #f2bd61;
+  --color-warning-bg: rgba(245, 177, 61, 0.14);
+  --color-warning-bg-text: var(--amber-300);
+  --color-warning-vivid-base: var(--amber-400);
+
+  --color-error-base: var(--red-400);
+  --color-error-fill: var(--red-400);
+  --color-error-text: var(--red-300);
+  --color-error-hover: #f09994;
+  --color-error-bg: rgba(242, 133, 125, 0.16);
+  --color-error-bg-text: var(--red-200);
+  --color-error-vivid-base: var(--red-400);
+
+  --color-info-bg: rgba(139, 155, 255, 0.16);
+  --color-info-bg-text: var(--indigo-200);
+  --color-info-vivid-base: var(--indigo-400);
+
+  --chart-series-1-base: #e69f00;
+  --chart-series-2-base: #009e73;
+  --chart-series-3-base: #0072b2;
+  --chart-series-4-base: #e2703a;
+  --chart-series-5-base: #d691bd;
+  --chart-series-6-base: #9d94e0;
+  --chart-grid: rgba(205, 215, 230, 0.12);
+
+  --site-shadow-sm: none;
+  --site-shadow-md: 0 0 0 1px rgba(205, 215, 230, 0.26);
+  --site-shadow-lg: 0 0 0 1px rgba(205, 215, 230, 0.26), 0 12px 32px rgba(0, 0, 0, 0.4);
+}
+
+// The graphite frame, the same in both themes: the dark tokens on a ground a little deeper than the
+// dark theme's own. The rail's links are a step brighter, since light thin text on graphite reads
+// paler than its ratio says.
+@mixin frame-tokens {
+  @include dark-tokens;
+  --bg-panel: var(--graphite-950);
+  --text-secondary: var(--graphite-200);
+  color-scheme: dark;
+  color: var(--text-primary);
+}

package/src/lib/tokens/_utilities.scss

@@ -1,3 +1,5 @@
+@use 'a11y';
+
 .gbt-form-error {
   margin: 0 0 0.75rem;
   font-size: 0.875rem;
@@ -85,8 +87,7 @@
   }
 }
 
-// Global, so it reaches the links the app projects: each piece of the rail keeps its height, and a rail taller than the
-// window scrolls rather than squeezing its links together.
+// Global to reach the projected links: a rail taller than the window scrolls instead of squeezing them.
 .gbt-app-shell__nav > * {
   flex-shrink: 0;
 }
@@ -101,6 +102,7 @@
   border-radius: var(--site-border-radius-sm);
   color: var(--text-secondary);
   font-size: 0.875rem;
+  font-weight: 500;
   text-decoration: none;
   overflow: hidden;
   white-space: nowrap;
@@ -118,16 +120,15 @@
   }
 
   &:focus-visible {
-    outline: 2px solid var(--gbt-focus-ring, var(--primary));
-    outline-offset: -2px;
+    @include a11y.focus-ring(-2px);
   }
 
   // An app can tone the current page down to a tint with a mark on its edge (--gbt-nav-active-*).
   &[aria-current] {
-    background: var(--gbt-nav-active-bg, var(--primary));
-    color: var(--gbt-nav-active-text, var(--text-on-primary));
+    background: var(--gbt-nav-active-bg, color-mix(in srgb, var(--text-primary) 9%, transparent));
+    color: var(--gbt-nav-active-text, var(--text-primary));
     font-weight: 600;
-    box-shadow: inset 2px 0 0 var(--gbt-nav-active-mark, transparent);
+    box-shadow: inset 2px 0 0 var(--gbt-nav-active-mark, var(--accent));
   }
 }
 
@@ -223,7 +224,7 @@
   gap: 0.5rem;
   width: 100%;
   padding: 8px 10px;
-  border-radius: var(--gbt-radius-menu, 8px);
+  border-radius: var(--gbt-radius-menu, 4px);
   color: var(--text-primary);
   font-size: 14px;
   text-align: left;
@@ -238,8 +239,7 @@
   }
 
   &:focus-visible {
-    outline: 2px solid var(--gbt-focus-ring, var(--primary));
-    outline-offset: -2px;
+    @include a11y.focus-ring(-2px);
   }
 }
 

package/src/lib/tokens/index.scss

@@ -1,3 +1,6 @@
 @forward 'palette';
 @forward 'semantic';
+@forward 'themes';
+@forward 'a11y';
+@forward 'base';
 @forward 'utilities';

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>
+```

package/tag/README.md

@@ -0,0 +1,34 @@
+# Tag
+
+A small chip rendering an arbitrary background color with automatically
+computed readable text, used for user-defined labels (e.g. issue labels)
+that don't fit the fixed `Badge` semantic variants. Optionally removable.
+
+**Selector:** `gbt-tag`
+
+**Inputs**
+
+| Input | Type | Default | Role |
+|---|---|---|---|
+| `color` | `string` (required) | — | Background color as a **6-digit hex** string, with or without the leading `#` (e.g. `#dc2626`, `dc2626`). Text color is computed automatically for WCAG-readable contrast (`#ffffff` or `#000000`, worst case 4.58:1). Shorthand hex (`#abc`), CSS named colors, `rgb()`/`hsl()` and custom properties are **not** supported and throw — silently guessing would paint unreadable text. |
+| `removable` | `boolean` | `false` | Shows a remove (`×`) button when `true`. |
+| `removeLabel` | `string` | `'Remove'` | Accessible label for the remove button. English by default, like every other default string in the library — externalize it per the caller's own i18n strings in a non-English context. |
+| `disabled` | `boolean` | `false` | Marks the chip `aria-disabled="true"` — for a container-level disabled state (e.g. `TagInput`, `Select` in chips mode) that visually dims the chip via CSS `opacity`, so contrast-checking tools recognize it as an inactive component rather than flagging its now-lower-contrast text. Purely an ARIA signal — pair it with `[removable]="false"` to actually remove the remove button. |
+
+**Outputs**
+
+| Output | Payload | Fires when |
+|---|---|---|
+| `removed` | `void` | The remove button is clicked. The click does not bubble to any parent click handler. |
+
+**Content**
+
+Project the tag's visible text via `<ng-content />`.
+
+**Example**
+
+```html
+<gbt-tag color="#dc2626" [removable]="true" removeLabel="Retirer Bug" (removed)="onRemoveLabel()">
+  Bug
+</gbt-tag>
+```

package/tag-input/README.md

@@ -0,0 +1,45 @@
+# TagInput
+
+Freely-typed values, each shown as a removable `Tag` — for values the
+consumer invents (custom labels, email recipients), not chosen from a
+predefined list. Distinct from `Select`'s chips, which pick among
+fixed options. Integrates with Angular forms via
+`ControlValueAccessor` (`string[]`), like `Select`.
+
+**Selector**: `gbt-tag-input`
+
+## Inputs
+
+| Input             | Type                          | Default                       | Role                                                       |
+| ------------------ | ------------------------------- | -------------------------------- | --------------------------------------------------------------- |
+| `label`           | `string`                        | `''`                               | Field label.                                                      |
+| `placeholder`     | `string`                        | `''`                               | Shown only while the list of tags is empty.                       |
+| `disabled`        | `boolean`                       | `false`                             | —                                                                  |
+| `errorMessage`    | `string \| null`                  | `null`                               | Rendered as `role="alert"` below the field.                       |
+| `separatorKeys`   | `string[]`                      | `['Enter', ',']`                     | Keys that commit the current text as a new tag.                   |
+| `allowDuplicates` | `boolean`                       | `false`                              | Silently ignores a duplicate value when `false`.                  |
+| `color`           | `string`                        | `'#6b7280'`                          | Background color passed to each `Tag` (a 6-digit hex, per `Tag`'s own contract). |
+| `removeLabel`     | `(value: string) => string`     | `` (v) => `Remove ${v}` ``            | Accessible name of each tag's remove button.                      |
+
+## Example
+
+```html
+<gbt-tag-input label="Labels" placeholder="Add a label…" [formControl]="labels" />
+```
+
+## Behavior
+
+- Typing text and pressing a `separatorKeys` key (Enter or comma by
+  default) commits it as a new tag and clears the field. A pending
+  draft is also committed on blur, so nothing is silently lost if the
+  user clicks away instead of pressing Enter.
+- `Backspace` on an *empty* field removes the last tag — the same
+  convenience most tag/recipient fields offer (Gmail's "To" field,
+  GitHub's label picker), not triggered while there's still text to
+  delete normally.
+- Clicking anywhere in the field (not just precisely on the thin text
+  input) focuses it — a documented lint exception, since the real
+  keyboard equivalent (Tab to the input directly) already exists; see
+  `AUDIT.md`.
+- Reuses `gbt-tag` for display, inheriting its automatic
+  readable-text-color computation — no separate contrast logic here.