@masmarino/gabarit 2.0.0 → 2.1.0

package/autocomplete/README.md

@@ -0,0 +1,77 @@
+# Autocomplete
+
+Text field with asynchronous suggestions. The app owns the data source
+— it supplies a `search` function, `Autocomplete` owns debouncing the
+input, tracking loading/empty/error state, and discarding a response
+that arrives after a more recent one. Integrated with reactive forms
+and `ngModel`, like `GbtInput`/`Select`.
+
+Distinct from `Select` (a fixed, known-upfront list of options) and
+from `SearchBar` (an organism dedicated exclusively to the header's
+search — not a reusable form field).
+
+**Selector**: `gbt-autocomplete`
+
+## Inputs
+
+| Input                 | Type                                             | Default              | Role                                                                                          |
+| --------------------- | ------------------------------------------------ | --------------------- | ---------------------------------------------------------------------------------------------- |
+| `id`                  | `string`                                          | generated             | DOM id, associates the `<label>`.                                                              |
+| `label`               | `string`                                          | `''`                  | Visible label.                                                                                 |
+| `search`              | `(query: string) => Observable<T[]> \| Promise<T[]>` | required           | Runs the search — `Autocomplete` never makes the HTTP call itself.                             |
+| `displayFn`           | `(item: T) => string`                             | `String(item)`        | Formats an item as text, both in the input once selected and as the default option rendering.  |
+| `itemTemplate`        | `TemplateRef<{ $implicit: T }>`                   | none                  | Custom rendering per suggestion (e.g. avatar + name), in place of the plain `displayFn` text.   |
+| `debounceMs`          | `number`                                          | `300`                 | Delay after the last keystroke before `search` runs.                                           |
+| `minLength`           | `number`                                          | `1`                   | Minimum query length (after trimming) before searching.                                        |
+| `placeholder`         | `string`                                          | `''`                  | Input placeholder.                                                                              |
+| `disabled`            | `boolean`                                         | `false`               | Disables the field.                                                                            |
+| `required`            | `boolean`                                         | `false`               | Native `required` attribute.                                                                   |
+| `errorMessage`        | `string \| null`                                  | `null`                | Error message shown under the field (form validation — distinct from a failed search).         |
+| `loadingMessage`      | `string`                                          | `'Searching…'`        | Shown in the panel and announced while `search` is pending.                                    |
+| `noResultsMessage`    | `string`                                          | `'No results'`        | Shown when `search` resolves to an empty array.                                                |
+| `searchErrorMessage`  | `string`                                          | `'Search failed'`     | Shown when `search` rejects or errors.                                                         |
+| `resultsAnnouncement` | `(count: number) => string`                       | `` `${count} result(s)` `` | Text announced to screen readers once results land.                                       |
+
+## Outputs
+
+| Output         | Type | Role                                                                                   |
+| -------------- | ---- | --------------------------------------------------------------------------------------- |
+| `itemSelected` | `T`  | Emitted when a suggestion is picked — in addition to the `ControlValueAccessor` value.  |
+
+## Behavior
+
+- Debounced: `search` only runs `debounceMs` after the last keystroke, not once per keystroke.
+- A response that resolves after a more recent one is discarded — typing "a" then "al" before the first search settles never lets the "a" results flash back over "al"'s.
+- Editing the text away from the current selection clears the form value (`null`) immediately — a stale object never lingers behind edited text.
+- Works with either a `Promise`-returning or an `Observable`-returning `search` (an active `Observable` subscription is replaced, not stacked, when a newer search starts).
+- The panel is positioned with `getBoundingClientRect()`, the same technique as `Select` — it escapes an ancestor's `overflow: hidden`.
+
+## Example
+
+```html
+<gbt-autocomplete
+  label="Utilisateur"
+  placeholder="Rechercher un utilisateur…"
+  [search]="searchUsers"
+  [displayFn]="displayUser"
+  formControlName="assignee"
+/>
+```
+
+```ts
+searchUsers = (query: string) =>
+  this.http.get<User[]>('/api/users', { params: { q: query } })
+
+displayUser = (user: User) => user.name
+```
+
+Custom rendering per suggestion, via `itemTemplate`:
+
+```html
+<gbt-autocomplete [search]="searchUsers" [displayFn]="displayUser" [itemTemplate]="userRow" formControlName="assignee">
+</gbt-autocomplete>
+<ng-template #userRow let-user>
+  <img [src]="user.avatarUrl" width="20" height="20" />
+  <span>{{ user.name }}</span>
+</ng-template>
+```

package/avatar/README.md

@@ -0,0 +1,34 @@
+# Avatar
+
+Visual representation of a user — an image, or a fallback of initials
+computed from their name if there's no image, or the image fails to
+load.
+
+**Selector**: `gbt-avatar`
+
+## Inputs
+
+| Input  | Type                    | Default | Role                                                                 |
+| ------ | ----------------------- | ------- | --------------------------------------------------------------------- |
+| `name` | `string`                | required | Full name — drives the initials fallback and the image's `alt` text. |
+| `src`  | `string \| null`        | `null`  | Image URL. Falls back to initials if absent, or if it fails to load. |
+| `size` | `'sm' \| 'md' \| 'lg'`  | `'md'`  | 24px / 32px / 48px.                                                  |
+
+## Example
+
+```html
+<gbt-avatar name="Ada Lovelace" [src]="user.avatarUrl" size="sm" />
+```
+
+## Behavior
+
+- Initials: first letter of the first and last word of `name` (e.g.
+  "Ada Lovelace" → "AL"), or the first two letters for a single-word
+  name.
+- A failed image load (`(error)`) switches to the initials fallback —
+  the broken-image icon a browser would otherwise show is never
+  visible.
+- The fallback uses a single neutral color (`--primary`/
+  `--text-on-primary`, already AAA-contrast), not a color hashed per
+  user — simpler, and one fewer palette to audit. Revisit if visually
+  distinguishing users in a dense list turns out to matter.

package/avatar-group/README.md

@@ -0,0 +1,47 @@
+# AvatarGroup
+
+A row of overlapping `Avatar`s — up to `max` shown, the rest folded
+into a "+N" indicator that opens a menu listing them. Every avatar,
+visible or in the overflow menu, is clickable — e.g. to filter a list
+down to that one user.
+
+**Selector**: `gbt-avatar-group`
+
+## Inputs
+
+| Input       | Type                       | Default   | Role                                                              |
+| ----------- | -------------------------- | --------- | -------------------------------------------------------------------- |
+| `items`     | `T[]` (`{ name, src? }`)   | required  | The users to show. `T` can carry extra fields (e.g. `id`) — the full item comes back on `itemClick`. |
+| `max`       | `number`                   | `5`       | Avatars shown before folding the rest into "+N".                     |
+| `ariaLabel` | `string`                   | `'Users'` | Accessible name of the avatar row.                                    |
+| `moreLabel` | `(count: number) => string`| `` (count) => `${count} more` `` | Accessible name of the "+N" button, and the overflow menu's label. |
+| `activeItem` | `T \| null`                | `null`    | The currently active filter, compared by reference against `items`. A visible avatar gets an outer ring; the matching row in the overflow menu gets a check icon (both also get `aria-current="true"`). |
+
+## Outputs
+
+| Output      | Type | Role                                                                 |
+| ----------- | ---- | ----------------------------------------------------------------------- |
+| `itemClick` | `T`  | Emitted when any avatar is clicked — the visible ones, or one from the overflow menu. |
+
+## Example
+
+```html
+<gbt-avatar-group
+  [items]="users"
+  [max]="5"
+  [activeItem]="selectedUser"
+  (itemClick)="selectedUser = selectedUser === $event ? null : $event"
+/>
+```
+
+```ts
+users: User[] = [{ id: '1', name: 'Ada Lovelace', src: user.avatarUrl }, ...]
+selectedUser: User | null = null
+```
+
+## Behavior
+
+- Reuses `Avatar` for each item (`md` size in the row, `sm` size in the
+  overflow menu) — no separate initials/fallback logic of its own.
+- The overflow menu is positioned the same way as `Select`/`Menu`
+  (`getBoundingClientRect`), closes on `Escape` or an outside click.

package/badge/README.md

@@ -0,0 +1,177 @@
+# Badge
+
+Short status/category label — a colored pill for text content (e.g. a
+role, a status, a count), purely informational. Not interactive by default;
+see [Copy](#copy) for the one exception (a small copy button inside the
+pill). Not removable; see the component's GitHub issue if you need a
+dismissible chip variant later.
+
+**Selector**: `gbt-badge`. Also replaces the former `gbt-code-chip` (via the
+`mono`/`copyable` inputs below) and `gbt-counter` (via `value`) — see
+[Migrating from CodeChip](#migrating-from-codechip) and
+[Migrating from Counter](#migrating-from-counter).
+
+## Inputs
+
+| Input         | Type                    | Default         | Role                                                                                                                                |
+| ------------- | ----------------------- | --------------- | ----------------------------------------------------------------------------------------------------------------------------------- |
+| `variant`     | `BadgeVariant`          | `'neutral'`     | `'neutral' \| 'success' \| 'warning' \| 'error' \| 'info'`.                                                                         |
+| `icon`        | `string`                | none            | Optional `gbt-icon` name, shown before the label.                                                                                   |
+| `appearance`  | `'filled' \| 'outline'` | `'filled'`      | `outline`: transparent, 1px border in the variant's text colour (`--border-color` for `neutral`). Same height as `filled`.          |
+| `size`        | `'md' \| 'sm'`          | `'md'`          | `sm`: smaller pill (11px), for counters and dense rows.                                                                             |
+| `truncate`    | `boolean`               | `false`         | The badge may shrink below its content and ellipsises its label (see below).                                                        |
+| `tabularNums` | `boolean`               | `false`         | `font-variant-numeric: tabular-nums`, so a live count keeps a steady width.                                                         |
+| `mono`        | `boolean`               | `false`         | Monospace font, hairline border, tighter shape — the look of the former `gbt-code-chip`. See [below](#mono-monospacecode).          |
+| `maxWidth`    | `string \| null`        | `null`          | Caps the pill's width (any CSS length, `12rem`). From `gbt-code-chip`.                                                              |
+| `fullText`    | `string \| null`        | `null`          | The complete text, as a native tooltip (`title`) on the label: useful when `truncate` cuts it. From `gbt-code-chip`.                |
+| `copyable`    | `boolean`               | `false`         | Adds a small copy button inside the badge. From `gbt-code-chip`.                                                                    |
+| `copyValue`   | `string \| null`        | `null`          | What the button copies; by default the badge's own visible text.                                                                    |
+| `copyLabel`   | `string`                | `'Copy'`        | Accessible name of the copy button ("Copy the commit SHA").                                                                         |
+| `copiedText`  | `string`                | `'Copied'`      | Announced after a copy (visually hidden live region: the glyph turns into a check).                                                 |
+| `failedText`  | `string`                | `'Copy failed'` | Announced when the copy is refused; the badge text is selected for a manual copy.                                                   |
+| `feedbackMs`  | `number`                | `2000`          | How long the copied glyph stays.                                                                                                    |
+| `value`       | `number \| null`        | `null`          | Numeric counter mode: replaces the projected content with this count. From `gbt-counter`. See [below](#value-numeric-counter-mode). |
+| `max`         | `number \| null`        | `null`          | Counter mode: caps the display, e.g. `max` `99` shows `120` as `99+`. `null`: no cap.                                               |
+| `hideZero`    | `boolean`               | `false`         | Counter mode: hides the badge (`hidden` on the host) when the shown count is `0`.                                                   |
+| `label`       | `string \| null`        | `null`          | Counter mode: visually hidden text read after the number ("12 open issues").                                                        |
+
+## Outputs
+
+| Output       | Type     | Role                                                                    |
+| ------------ | -------- | ----------------------------------------------------------------------- |
+| `copied`     | `string` | Emitted with the copied text after a successful copy (`copyable` only). |
+| `copyFailed` | `void`   | Emitted when the copy is refused (`copyable` only).                     |
+
+## Content
+
+The badge's text comes from projected content (`<ng-content />`), not
+an input — like a native `<span>`, so it composes naturally with
+interpolation, `@if`, or plain text — **except** in `value` mode (see
+below), where the projected content is ignored and the computed count is
+rendered instead.
+
+## Truncation
+
+In a narrow row a long label pushes its badge past the container. With `truncate`
+the host and the pill are allowed to shrink (`min-width: 0`, `max-width: 100%`) and
+the label ends in an ellipsis; a `max-width` on `<gbt-badge>` (or the `maxWidth` input)
+caps it below the container width. The full text stays in the DOM for assistive
+technology; add a `title` on the host, or the `fullText` input, for a hover tooltip.
+If the badge is a flex item, give its wrapper `min-width: 0` as well.
+
+```html
+<li style="display: flex; min-width: 0">
+  <gbt-badge appearance="outline" truncate [attr.title]="event">{{ event }}</gbt-badge>
+</li>
+```
+
+## `mono` (monospace/code)
+
+`mono` gives the badge the monospace font, hairline border and tighter shape
+suited for a commit SHA, a tag, a branch name or a repository path, in a row,
+a meta line or a sentence. It
+layers on top of `variant`/`appearance`: an explicit colored variant still
+wins for background/color (declared later in `badge.scss`); `mono` alone
+only changes the shape and the type.
+
+```html
+<gbt-badge mono icon="git-commit" fullText="{{ sha }}">{{ sha.slice(0, 7) }}</gbt-badge>
+```
+
+## Copy
+
+Same engine as [`gbt-copy-button`](../copy-button/README.md) (Clipboard API, `execCommand` fallback,
+refusal selects the text), reusing `ClipboardFeedback` — no logic is duplicated. The badge itself is
+not interactive: only its copy button is, with a 24 px hit area (drawn outside the pill so it does not
+grow). The outcome is announced by a `role="status"` region that exists as long as the badge is
+`copyable`.
+
+```html
+<gbt-badge mono icon="git-commit" copyable [copyValue]="commit.sha" copyLabel="Copy the commit SHA"
+  >{{ commit.sha.slice(0, 7) }}</gbt-badge
+>
+```
+
+## `value` (numeric counter mode)
+
+Setting `value` switches the badge into the former `gbt-counter`'s mode: the
+projected content is **ignored**, and the badge computes and renders the
+count itself — fractions cut, negatives and non-numbers count as `0` — capped
+by `max` (`120` with `max` `99` shows `99+`) and hideable at `0` with
+`hideZero` (via the `hidden` attribute — the element stays in the DOM, no
+`@if` needed around it). `label` adds a visually hidden suffix after the
+number ("12 open issues"): **a bare number is ambiguous for assistive
+technology** unless the surrounding context (a heading, a tab) already says
+what it counts — see [AUDIT.md](AUDIT.md).
+
+```html
+<h2>Pages <gbt-badge [value]="pages().length" hideZero label="pages" /></h2>
+
+<button gbtTab>Closed <gbt-badge [value]="closed()" [max]="99" size="sm" /></button>
+<gbt-badge [value]="toReview()" variant="info" size="sm" label="to review" />
+```
+
+Badge already has `tabularNums` for equal-width digits (a live count does not
+jitter) — set it explicitly in counter usage: it is not implied by `value`.
+
+## Migrating from CodeChip
+
+`gbt-code-chip` is gone; use `gbt-badge` with `mono` (its label is a `<span>`, not a `<code>`
+wrapper, styled the same way). Every other `gbt-code-chip` input keeps its name:
+
+```html
+<!-- before -->
+<gbt-code-chip icon="git-commit" copyable [copyValue]="sha" copyLabel="Copy the commit SHA"
+  >{{ sha.slice(0, 7) }}</gbt-code-chip
+>
+
+<!-- after -->
+<gbt-badge mono icon="git-commit" copyable [copyValue]="sha" copyLabel="Copy the commit SHA"
+  >{{ sha.slice(0, 7) }}</gbt-badge
+>
+```
+
+One behavioural difference: `gbt-code-chip`'s `truncate` defaulted to `true`
+(and `truncate="false"` made it wrap instead of overflowing, via
+`white-space: normal; overflow-wrap: anywhere`). `gbt-badge`'s `truncate`
+keeps its own default of `false` and has no such wrapping mode — a mono
+badge that needs the ellipsis behaviour should set `truncate` explicitly; one
+that needs to wrap instead should sit inside a block-level container.
+
+## Migrating from Counter
+
+`gbt-counter` is gone; use `gbt-badge` with `value` (and the same `max` /
+`hideZero` / `label` names):
+
+```html
+<!-- before -->
+<gbt-counter [value]="pages().length" hideZero label="pages" />
+
+<!-- after -->
+<gbt-badge [value]="pages().length" hideZero label="pages" />
+```
+
+`gbt-counter`'s `appearance` (`'neutral' | 'primary'`) has no exact `gbt-badge`
+equivalent: Badge's own `variant`/`appearance`/`size` axes replace it.
+`appearance="neutral"` (the old default) is closest to `gbt-badge`'s own
+default look (no `variant`, `appearance="filled"`); there is no ready-made
+"brand-filled" look for the old `appearance="primary"` — pick the semantic
+`variant` that fits (e.g. `variant="info"`) or a custom class. `size="sm"`/
+`"md"` map directly. This is a visual difference to review when migrating a
+call site, not just a rename.
+
+## Example
+
+```html
+<gbt-badge variant="success">Actif</gbt-badge>
+<gbt-badge variant="error" icon="alert-triangle">Erreur</gbt-badge>
+```
+
+```html
+<gbt-badge appearance="outline" variant="success">Current version</gbt-badge>
+<gbt-badge size="sm" tabularNums>1,118</gbt-badge>
+```
+
+## Accessibility
+
+See [AUDIT.md](AUDIT.md).

package/bar-chart/README.md

@@ -0,0 +1,44 @@
+# BarChart
+
+Bar chart on the dataviz base — measures its container, reacts to the
+pointer and keyboard, carries its own visually-hidden
+`gbt-chart-table`.
+
+**Selector**: `gbt-bar-chart`
+
+## Inputs
+
+| Input          | Type                                        | Default  | Role                                                             |
+| -------------- | ------------------------------------------- | -------- | ---------------------------------------------------------------- |
+| `series`       | `ChartSeries<string>`                       | required | `{ label, points, pattern? }` — a series, category axis.         |
+| `locale`       | `string`                                    | required | Locale used to format numbers.                                   |
+| `label`        | `string`                                    | required | Accessible name of the chart.                                    |
+| `tableCaption` | `string`                                    | required | Caption of the `sr-only` table.                                  |
+| `xColumn`      | `string`                                    | required | Header of that table's x-axis column.                            |
+| `emptyMessage` | `string`                                    | required | Message shown when the series is empty.                          |
+| `yTickCount`   | `number`                                    | `5`      | Target number of ticks on the y-axis.                            |
+| `size`         | `{ width: number; height: number } \| null` | `null`   | Explicit dimensions — reserved for server rendering, tests.      |
+| `heading`      | `string`                                    | `''`     | Block title. Empty by default: no header is rendered without it. |
+| `headingLevel` | `1 \| 2 \| 3 \| 4 \| 5 \| 6`                | `2`      | Level of the rendered heading.                                   |
+| `headline`     | `string`                                    | `''`     | Current value, already formatted — "360 GiB".                    |
+| `trend`        | `string`                                    | `''`     | Change over the period, already formatted.                       |
+
+**Fluid width with a chosen height** — the common case — is achieved by
+setting the height in CSS on the wrapping container, without passing
+`[size]`. See [`../chart-frame/README.md`](../chart/chart-frame/README.md) for
+the full sizing contract and hover behavior.
+
+## Example
+
+```html
+<div style="height: 18rem">
+  <gbt-bar-chart
+    [series]="{ label: 'Requêtes', points: [{ x: 'Lun', y: 12 }, { x: 'Mar', y: 40 }] }"
+    locale="fr-FR"
+    label="Requêtes par jour"
+    tableCaption="Détail des requêtes par jour"
+    xColumn="Jour"
+    emptyMessage="Aucune donnée"
+  />
+</div>
+```

package/breadcrumb/README.md

@@ -0,0 +1,38 @@
+# Breadcrumb
+
+Trail of ancestor links plus a current segment — purely presentational,
+no router dependency.
+
+**Selector**: `gbt-breadcrumb`
+
+## Inputs
+
+| Input       | Type     | Role                                                 |
+| ----------- | -------- | ---------------------------------------------------- |
+| `ariaLabel` | `string` | Required. Accessible name of the breadcrumb `<nav>`. |
+
+## Projected content
+
+| Selector                | Role                                                                                                                                                                                                                                                                                                                     |
+| ----------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| `[breadcrumb-ancestor]` | Zero or more ancestor items, in order — each projected as `<li breadcrumb-ancestor>` wrapping a real link (the `<ol>` content model and the CSS separator rule both depend on the projected node being an `<li>`, not the link itself). `.gbt-breadcrumb__item` (in `_utilities.scss`) for styling, applied to the link. |
+| Default                 | The current segment: plain text, or an interactive element like `gbt-menu` if the current item doubles as a switcher.                                                                                                                                                                                                    |
+
+Separators (`/`) between items are rendered automatically via CSS — the
+consuming app never adds them itself.
+
+## Example
+
+```html
+<gbt-breadcrumb ariaLabel="Fil d'Ariane">
+  <li breadcrumb-ancestor><a class="gbt-breadcrumb__item" routerLink="/groupe">Groupe</a></li>
+  <li breadcrumb-ancestor>
+    <a class="gbt-breadcrumb__item" routerLink="/groupe/sous-groupe">Sous-groupe</a>
+  </li>
+  <gbt-menu label="Dépôt" align="start">
+    <a role="menuitem" class="gbt-menu__item" routerLink="/groupe/sous-groupe/autre-depot"
+      >autre-depot</a
+    >
+  </gbt-menu>
+</gbt-breadcrumb>
+```

package/button/README.md

@@ -0,0 +1,175 @@
+# Button
+
+Action button, or an anchor styled the same way — visual variants, sizes,
+loading state, toggle and disclosure semantics. One component, two selectors
+on the same class:
+
+- **`gbt-button`** — a `<button>`, for an in-page action.
+- **`a[gbtButton]`** — a real `<a>` that looks exactly like a `gbt-button`,
+  for a router link, a download, or any navigation. It is
+  **router-agnostic**: it never imports `@angular/router`. Put `routerLink`
+  (or a plain `href`), a `download`… on the same element yourself.
+
+```ts
+import { Button } from '@masmarino/gabarit'
+```
+
+## Inputs (button form — `gbt-button`)
+
+| Input          | Type                                                                          | Default     | Role                                                                                                                                                                                           |
+| -------------- | ----------------------------------------------------------------------------- | ----------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `variant`      | `'primary' \| 'secondary' \| 'danger' \| 'ghost' \| 'ghost-danger' \| 'link'` | `'primary'` | Visual treatment. See [Variants](#variants).                                                                                                                                                   |
+| `size`         | `'small' \| 'medium' \| 'large'`                                              | `'medium'`  | Button size: at least 32 / 38 / 44px tall for `small` / `medium` / `large` (the shared `--gbt-control-height-*` scale, level with a field of the same tier); `large` is the 44px touch target. |
+| `type`         | `'button' \| 'submit'`                                                        | `'button'`  | Native `type` attribute.                                                                                                                                                                       |
+| `text`         | `string`                                                                      | `''`        | Visible label. The text `<span>` is only rendered when this is not empty.                                                                                                                      |
+| `iconName`     | `string \| null`                                                              | `null`      | Icon shown before the text, if provided.                                                                                                                                                       |
+| `ariaLabel`    | `string \| null`                                                              | `null`      | Accessible name, when the visible label isn't enough (mandatory for an icon-only button).                                                                                                      |
+| `loading`      | `boolean`                                                                     | `false`     | Shows a loading indicator, disables the button.                                                                                                                                                |
+| `loadingLabel` | `string`                                                                      | `'Loading'` | Text announced while loading (`.sr-only`).                                                                                                                                                     |
+| `disabled`     | `boolean`                                                                     | `false`     | Disables the button.                                                                                                                                                                           |
+| `pressed`      | `boolean \| null`                                                             | `null`      | Toggle button: renders `aria-pressed="true"` / `"false"`. `null` renders no attribute (an ordinary button).                                                                                    |
+| `ariaExpanded` | `boolean \| null`                                                             | `null`      | Disclosure or menu trigger: renders `aria-expanded`. `null` renders no attribute.                                                                                                              |
+| `ariaControls` | `string \| null`                                                              | `null`      | Id of the element the button controls (`aria-controls`).                                                                                                                                       |
+| `ariaHaspopup` | `'menu' \| 'listbox' \| 'tree' \| 'grid' \| 'dialog' \| boolean \| null`      | `null`      | Kind of popup the button opens (`aria-haspopup`); `true` means a menu.                                                                                                                         |
+| `block`        | `boolean`                                                                     | `false`     | Stretches the button to the width of its container.                                                                                                                                            |
+| `iconOnly`     | `boolean`                                                                     | `false`     | Squares the button around its icon (same padding on every side, as wide as tall: 32 / 38 / 44px for `small` / `medium` / `large`). Set `ariaLabel`.                                            |
+
+## Outputs (button form)
+
+| Output    | Type   | Role                                          |
+| --------- | ------ | --------------------------------------------- |
+| `clicked` | `void` | Emitted on click (not disabled, not loading). |
+
+## Inputs (anchor form — `a[gbtButton]`)
+
+| Input      | Type                                                                          | Default     | Role                                                                                                             |
+| ---------- | ----------------------------------------------------------------------------- | ----------- | ---------------------------------------------------------------------------------------------------------------- |
+| `variant`  | `'primary' \| 'secondary' \| 'danger' \| 'ghost' \| 'ghost-danger' \| 'link'` | `'primary'` | Visual treatment (same as `gbt-button`).                                                                         |
+| `size`     | `'small' \| 'medium' \| 'large'`                                              | `'medium'`  | Size: at least 32 / 38 / 44px tall for `small` / `medium` / `large` (the shared `--gbt-control-height-*` scale). |
+| `iconName` | `string \| null`                                                              | `null`      | Icon shown before the projected text.                                                                            |
+| `block`    | `boolean`                                                                     | `false`     | Stretches the link to the width of its container.                                                                |
+| `iconOnly` | `boolean`                                                                     | `false`     | Squares the link around its icon. Give the anchor an `aria-label`.                                               |
+| `disabled` | `boolean`                                                                     | `false`     | Link "disabled" semantics: `aria-disabled="true"`, `tabindex="-1"`, the click is swallowed (see below).          |
+
+The anchor's label is the projected content. Keep it a single text node or
+wrap richer content in one `<span>`: the direct children are laid out as a
+flex row with a 0.5rem gap, exactly like the button's icon and text. The
+anchor form has no `type`, `text`, `ariaLabel`, `loading`, `loadingLabel`,
+`pressed`, `ariaExpanded`, `ariaControls` or `ariaHaspopup` input — those are
+native-`<button>` concerns the anchor form doesn't need (they exist on the
+shared class but have no effect there; the anchor's accessible name is its
+own `aria-label` attribute or its projected text, same as any link).
+
+## One class, two selectors
+
+`Button` is a single Angular class with `selector: 'gbt-button, a[gbtButton]'`.
+Its constructor inspects `ElementRef.nativeElement.tagName` once to tell
+which form it is applied to:
+
+- On `<gbt-button>` it renders an internal native `<button>` carrying
+  `type`/`disabled`/the ARIA attributes above, and emits `clicked` on a real
+  click (guarded by `disabled`/`loading`).
+- On `a[gbtButton]` there is no internal wrapper: the host **is** the anchor.
+  The button-look classes (`gbt-button`, `gbt-button--{variant}`,
+  `gbt-button--{size}`, `gbt-button--icon-only`) are put on the host itself,
+  and a capture-phase `click`/`auxclick` listener plus a tabindex-restore
+  effect implement the disabled-link semantics below. It never imports
+  `@angular/router`.
+
+Both forms share the same variant/size look: `_button-look.scss` is a single
+Sass mixin, called once for the inner `<button>` (class selectors) and once
+more with `$host: true` for the anchor (`:host(...)` selectors) — there is
+exactly one place that defines "the gbt-button look".
+
+## Variants
+
+| Variant        | Use                                                                                                        |
+| -------------- | ---------------------------------------------------------------------------------------------------------- |
+| `primary`      | The main action of a view.                                                                                 |
+| `secondary`    | A neutral action, outlined.                                                                                |
+| `danger`       | A destructive action, filled.                                                                              |
+| `ghost`        | A quiet action: no fill, no border until hovered — toolbars, rows, icon-only buttons.                      |
+| `ghost-danger` | A quiet destructive action (delete in a row): looks like `ghost` until hovered or focused, then turns red. |
+| `link`         | A text action inside running content: primary colour, underlined, no box.                                  |
+
+## Icon-only
+
+`text` is left empty: no text `<span>` is rendered, so nothing but the icon
+sits in the flex row (no stray gap). Add `iconOnly` to square the box, and an
+`ariaLabel` for the accessible name:
+
+```html
+<gbt-button
+  variant="ghost-danger"
+  size="small"
+  iconName="x"
+  [iconOnly]="true"
+  ariaLabel="Delete label"
+/>
+```
+
+Without `iconOnly` an icon-only button keeps the button's normal padding (a
+slightly wider box) and renders no text `<span>` or gap around the icon.
+
+## Toggle and disclosure
+
+`pressed`, `ariaExpanded`, `ariaControls` and `ariaHaspopup` only reflect state:
+the consumer flips it in its `clicked` handler. A pressed button also draws a
+2px ring inside its box, so the state is not conveyed by colour alone.
+
+```html
+<gbt-button
+  variant="secondary"
+  [text]="following() ? 'Following' : 'Follow'"
+  [pressed]="following()"
+  (clicked)="toggle()"
+/>
+
+<gbt-button
+  text="Advanced"
+  iconName="chevron-down"
+  [ariaExpanded]="open()"
+  ariaControls="advanced"
+  (clicked)="open.set(!open())"
+/>
+```
+
+## Anchor: disabled
+
+A link cannot be `disabled` natively. With `[disabled]="true"` the anchor gets
+`aria-disabled="true"` and `tabindex="-1"` (a `tabindex` you had set is restored when it is enabled again), is dimmed with a `not-allowed`
+cursor, and every `click` and middle click (`auxclick`) on it — including one
+that lands on the icon — is stopped in the capture phase, before a `routerLink`
+on the same element (or your own `(click)`) can run. `href` is left in place:
+the attribute belongs to the consumer.
+
+## Examples
+
+```html
+<gbt-button text="Enregistrer" variant="primary" (clicked)="save()" />
+<gbt-button text="Se connecter" size="large" [block]="true" type="submit" />
+
+<a gbtButton href="/groups">Groups</a>
+
+<a gbtButton variant="secondary" iconName="folder" routerLink="/repositories">Repositories</a>
+
+<a
+  gbtButton
+  variant="ghost"
+  size="small"
+  [iconOnly]="true"
+  iconName="plus"
+  aria-label="New group"
+  routerLink="/groups/new"
+></a>
+
+<a gbtButton href="/export.csv" download [disabled]="!ready()">Download</a>
+```
+
+With a router, activeness/`aria-current` stay the consumer's business
+(`routerLinkActive`); the anchor renders exactly the attributes you put on it,
+plus the ones above.
+
+## Accessibility
+
+See [AUDIT.md](AUDIT.md).