@masmarino/gabarit 2.0.0 → 2.1.1

package/list-card/README.md

@@ -0,0 +1,144 @@
+# ListCard
+
+The card that holds a page's list: a header (state tabs, a count, filters)
+above a box that shows one of four states of the list. It is the surface
+around [`gbt-list-row`](../list-row/README.md)s and the place where
+"loading", "failed" and "empty" look the same on every list page.
+
+**Selector**: `gbt-list-card`
+
+## States
+
+| `state`   | What shows                                                                                                                                                                 |
+| --------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `ready`   | The `[list-card-header]` above the box, then the projected content in the box (usually `ul > li > gbt-list-row`). The default.                                             |
+| `loading` | A skeleton of the same shape (a header placeholder above the box, `skeletonRows` rows in it), the rows are `aria-busy`, and a polite status (`loadingLabel`) announces it. |
+| `failed`  | An error block (`failedHeading`, `failedMessage`) in the box with a retry button, and the `[list-card-failed]` slot for more actions. No header.                           |
+| `empty`   | Nothing to list at all: `emptyIllustration` or `emptyIcon`, `emptyHeading`, `emptyMessage`, and `[list-card-empty]` for the call to action, in the box. No header.         |
+
+In every state but `ready` the projected content is not rendered.
+
+## Inputs
+
+| Input               | Type                                          | Default                          | Role                                                                                        |
+| ------------------- | --------------------------------------------- | -------------------------------- | ------------------------------------------------------------------------------------------- |
+| `state`             | `'loading' \| 'failed' \| 'empty' \| 'ready'` | `'ready'`                        | Which of the four states shows.                                                             |
+| `ariaLabel`         | `string \| null`                              | `null`                           | Names the card's `<section>` (for example "Issues").                                        |
+| `loadingLabel`      | `string`                                      | `'Loading…'`                     | Visually hidden, read out politely while loading.                                           |
+| `skeletonRows`      | `number`                                      | `4`                              | Placeholder rows while loading.                                                             |
+| `skeletonHeader`    | `boolean`                                     | `true`                           | Shows a placeholder of the header while loading (turn off for a card without a header).     |
+| `failedHeading`     | `string`                                      | `'The list could not be loaded'` | Heading of the failed block.                                                                |
+| `failedMessage`     | `string`                                      | `''`                             | Optional detail under it.                                                                   |
+| `retryLabel`        | `string \| null`                              | `'Retry'`                        | Label of the retry button. `null` hides it (bring your own action in `[list-card-failed]`). |
+| `emptyHeading`      | `string`                                      | `'Nothing here yet'`             | Heading of the empty block.                                                                 |
+| `emptyMessage`      | `string`                                      | `''`                             | Optional message under it.                                                                  |
+| `emptyIllustration` | `EmptyStateIllustration \| null`              | `null`                           | The curated artwork of [`gbt-empty-state`](../empty-state/README.md) (full size).           |
+| `emptyIcon`         | `string \| null`                              | `null`                           | A registered icon name on a soft disc (compact size), when there is no illustration.        |
+
+## Outputs
+
+| Output  | Payload | Role                                              |
+| ------- | ------- | ------------------------------------------------- |
+| `retry` | `void`  | The retry button of the failed block was pressed. |
+
+## Slots
+
+| Selector             | State    | Role                                                                                                                                                                                                       |
+| -------------------- | -------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `[list-card-header]` | `ready`  | The header, above the box: state tabs (`gbt-segmented-control tinted`), a heading, a count, filters. No header when absent.                                                                                |
+| (default)            | `ready`  | The list. A direct child `ul`/`ol` loses its bullets and spacing; a direct child carrying the `list-card-message` attribute is the centred quiet message of a list that is empty under the current filter. |
+| `[list-card-failed]` | `failed` | Extra actions after the retry button.                                                                                                                                                                      |
+| `[list-card-empty]`  | `empty`  | The call to action (a `gbt-button`).                                                                                                                                                                       |
+
+## Structure: a header over a box, in one section
+
+The card renders one `<section>` (named by `ariaLabel`, carrying `data-state`) with two parts:
+
+1. **The header** (`.gbt-list-card__header`, `ready` and `loading` only): a plain row **above** the box —
+   the projected `[list-card-header]`, or its skeleton while loading. It has no background, no border and
+   no padding of its own, like [`gbt-card`](../card/README.md)'s header; `0.5rem` separates it from the
+   box. It reserves the height of a `md` control (`--gbt-control-height-md`, 38px), so the loading
+   placeholder and the ready header are the same height and the box does not move when the list arrives.
+   A header that holds only a heading (no tabs, input or button) is shorter than that on its own: expect a
+   little whitespace above the box in that case, since there is no background to make the row visible.
+2. **The box** (`.gbt-list-card__box`): the 1px edge (`--gbt-card-border`), the radius and the background.
+   It holds the list, the skeleton rows, the failed block or the empty block.
+
+```
+<gbt-list-card>
+  section.gbt-list-card            the landmark and the size container: aria-label, data-state
+    span.sr-only[role=status]      the loading announcement
+    div.gbt-list-card__header      [list-card-header], or its skeleton (ready/loading only)
+    div.gbt-list-card__box         the edge, the radius, the clipping
+      div.gbt-list-card__body      ready: your projected list
+      (or, instead of the body: the loading skeleton rows, the failed block, or the empty block —
+       exactly one of these four renders in the box at a time, depending on `state`)
+```
+
+Unlike `gbt-card`, the header stays **inside** the section: the header's tabs and filters belong to the
+named region ("Issues") exactly as the rows do. `.gbt-list-card` is the section, carrying `data-state`;
+the edge is drawn by `.gbt-list-card__box`.
+
+## Behaviour
+
+- The card is a **size container** named `gbt-list-card`, on the section (header and box): the header's
+  items sit closer under 560 px of card width, and a page can add its own
+  `@container gbt-list-card (max-width: …)` rules (hide a column, shorten a label). Never make it a
+  shrink-to-fit flex or grid item; give it a width or let it fill a block.
+- The box clips its corners (`overflow: hidden`), so the rows' hover follows the rounded edge. The header is
+  outside the box and is never clipped.
+- The failed block is a live alert (`role="alert"`). The loading status is a **persistent** polite region
+  (`role="status"`, a direct child of the section, empty unless `loading`) and is never inside the
+  `aria-busy` skeleton, so the announcement is not held back. A card that is already `loading` on its very
+  first render inserts the region with its text, which some screen readers do not announce: start in
+  `ready` and switch, or accept it.
+- **Focus after Retry**: pressing Retry usually flips the state to `loading`, which removes the focused
+  button and drops focus to the page. Move focus to a stable target yourself (the card's heading or the
+  list once it is ready), or keep the retry outside the card.
+- The empty and failed buttons reach 44 px on touch screens.
+
+## Example
+
+```html
+<gbt-list-card
+  ariaLabel="Issues"
+  [state]="state()"
+  loadingLabel="Loading issues…"
+  failedHeading="The issues could not be loaded"
+  emptyHeading="No issues yet"
+  emptyIcon="circle-dot"
+  (retry)="reload()"
+>
+  <gbt-segmented-control
+    list-card-header
+    tinted
+    ariaLabel="Issue state"
+    [options]="tabs"
+    [(value)]="tab"
+  />
+
+  @if (rows().length === 0) {
+  <p list-card-message>No {{ tab() }} issues.</p>
+  } @else {
+  <ul>
+    @for (issue of rows(); track issue.id) {
+    <li>
+      <gbt-list-row>
+        <a [href]="issue.url" [title]="issue.title">{{ issue.title }}</a>
+      </gbt-list-row>
+    </li>
+    }
+  </ul>
+  }
+
+  <gbt-button list-card-empty variant="secondary" iconName="plus" text="New issue" />
+</gbt-list-card>
+```
+
+The `failed` and `empty` slots are only rendered in their own state, so the button above shows only when
+`state` is `empty`.
+
+## Accessibility
+
+See [AUDIT.md](AUDIT.md). Note that Safari and VoiceOver drop the list semantics of a `ul` whose bullets are
+removed with `list-style: none`: add `role="list"` on the `ul` if that matters to you.

package/list-row/README.md

@@ -0,0 +1,72 @@
+# ListRow
+
+One item of a list (issues, merge requests, pipelines, accounts…): a
+leading status icon, the title area (the title link, then its badges and
+tags), a muted meta line under it, and trailing actions or counters on the
+right. Every column lines up on the title's first line.
+
+The page provides the list semantics and the surface around it
+(`ul > li > gbt-list-row`, inside a [`gbt-list-card`](../list-card/README.md)
+or any bordered box). The row adds hairlines between consecutive rows, a
+hover / focus-within background and title truncation.
+
+**Selector**: `gbt-list-row`
+
+## Inputs
+
+| Input  | Type                                                       | Default     | Role                                                                                  |
+| ------ | ---------------------------------------------------------- | ----------- | ------------------------------------------------------------------------------------- |
+| `tone` | `'neutral' \| 'success' \| 'warning' \| 'error' \| 'info'` | `'neutral'` | Tint of the `[row-leading]` icon: muted, or the status colour (`gbt-badge` variants). |
+
+## Slots
+
+| Selector         | Role                                                                                                                                       |
+| ---------------- | ------------------------------------------------------------------------------------------------------------------------------------------ |
+| `[row-leading]`  | A 20 px column centred on the title line: a status icon (`gbt-icon` renders as a 16 px glyph). Tinted by `tone`. Collapses when empty.     |
+| (default)        | The title area: the title **link as a direct child**, then badges, tags or a `gbt-user-chip`.                                              |
+| `[row-meta]`     | A muted line under the title (one or several `span`s, wrapping together). `code` inside is a monospace chip. Collapses when empty.         |
+| `[row-trailing]` | Counters, an avatar, a menu, right aligned. Wraps under the main column, still right aligned, when there is no room. Collapses when empty. |
+
+## Rules of use
+
+- **The title link is a DIRECT child of the row** (`<a>` straight inside `gbt-list-row`, not wrapped in a
+  `span` or a `@if` block element): only a direct child gets the truncation (one line, ellipsis) and the
+  focus ring. Give it the full title in `title`.
+- Children of the title area do not shrink (`flex: none`), except the link and a `gbt-user-chip`, which
+  truncate. Tags that do not fit beside the title wrap below it.
+- Keep **the same trailing items in every row** of a list (an empty, fixed-width `span` for a missing
+  avatar) so the columns line up.
+- The status is never told by colour alone: put an icon that differs per status and a text alternative
+  (`<span class="sr-only">Open</span>`) next to it.
+- Do not nest interactive controls inside the title link.
+
+## Separators
+
+`li + li > gbt-list-row` and `gbt-list-row + gbt-list-row` get a `--gbt-hairline` border on top. Emulated
+view encapsulation cannot express "a row after a row" from inside the component, so this is one rule
+that is not scoped to the component, keyed on the element name.
+
+## Example
+
+```html
+<ul>
+  @for (issue of issues; track issue.id) {
+  <li>
+    <gbt-list-row [tone]="issue.tone">
+      <span row-leading>
+        <gbt-icon [name]="issue.icon" />
+        <span class="sr-only">{{ issue.status }}</span>
+      </span>
+      <a [href]="issue.url" [title]="issue.title">{{ issue.title }}</a>
+      <gbt-tag [color]="'#dc2626'">bug</gbt-tag>
+      <span row-meta>#{{ issue.id }} opened {{ issue.age }} by {{ issue.author }}</span>
+      <span row-trailing><gbt-icon name="message-circle" />{{ issue.comments }}</span>
+    </gbt-list-row>
+  </li>
+  }
+</ul>
+```
+
+## Accessibility
+
+See [AUDIT.md](AUDIT.md).

package/list-toolbar/README.md

@@ -0,0 +1,52 @@
+# ListToolbar
+
+Search + sort controls for a local list or grid — a text filter, a
+sort-field selector, and a direction toggle. Purely a set of controls:
+it never filters or sorts anything itself, and takes no `data` input.
+
+**Selector**: `gbt-list-toolbar`
+
+## Inputs
+
+| Input               | Type                        | Default                    | Role                                    |
+| -------------------- | --------------------------- | --------------------------- | ---------------------------------------- |
+| `searchValue`        | `string`                    | `''`                        | Current search text (controlled).       |
+| `searchLabel`        | `string`                    | —                            | Required. Visible label for the search field. |
+| `searchPlaceholder`  | `string`                    | `''`                        | Placeholder for the search field.       |
+| `sortOptions`        | `ListToolbarSortOption<T>[]`| —                            | Required. `{ value, label }[]`.         |
+| `sortValue`          | `T`                         | —                            | Required. Currently selected sort field.|
+| `sortDirection`      | `'asc' \| 'desc'`           | `'asc'`                      | Current sort direction.                 |
+| `sortLabel`          | `string`                    | `'Sort by'`                  | Visible label for the sort selector.    |
+| `directionLabel`     | `string`                    | `'Reverse sort direction'`   | Accessible name for the direction button.|
+
+## Outputs
+
+| Output                 | Payload            | When                                    |
+| ------------------------ | ------------------- | ------------------------------------------ |
+| `searchValueChange`      | `string`            | On every keystroke in the search field.   |
+| `sortValueChange`        | `T`                 | When a different sort field is selected.  |
+| `sortDirectionChange`    | `'asc' \| 'desc'`   | When the direction button is clicked (flips the current direction). |
+
+## Example
+
+```html
+<gbt-list-toolbar
+  searchLabel="Rechercher un dépôt"
+  [searchValue]="search()"
+  [sortOptions]="[{ value: 'name', label: 'Nom' }, { value: 'date', label: 'Date' }]"
+  [sortValue]="sort()"
+  [sortDirection]="direction()"
+  (searchValueChange)="search.set($event)"
+  (sortValueChange)="sort.set($event)"
+  (sortDirectionChange)="direction.set($event)"
+/>
+```
+
+The consumer owns the actual filtering/sorting, typically as a
+`computed()` over its own data driven by these three signals — the
+same pattern used throughout consuming apps for local list filtering.
+
+To avoid re-declaring the three signals and the filter/sort on every page,
+use `createListToolbarState()` (see "List toolbar state" in the root README):
+it exposes `search`, `sortValue`, `direction` and `sortOptions` ready to bind to
+this component, plus `apply()` / `filtered()`.

package/menu/README.md

@@ -0,0 +1,90 @@
+# Menu
+
+Generic dropdown menu — trigger and action list, the WAI-ARIA "menu
+button" pattern.
+
+**Selector**: `gbt-menu`
+
+Click or Enter/Space opens it while focusing the first item; the
+up/down arrows on the closed trigger open it while focusing the first
+or last item respectively; the up/down arrows inside the list cycle
+through the items with wraparound (Home/End jump to the first/last);
+Escape closes it and returns focus to the trigger; activating an item
+closes the menu and **returns focus to the trigger** (the item that had
+it is gone); a click outside the menu or a focus-out (tabbing) closes
+it without stealing focus. Focus is never trapped: Tab leaves the menu.
+
+## Inputs
+
+| Input              | Type               | Default   | Role                                                                                                                                                                            |
+| ------------------ | ------------------ | --------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `label`            | `string`           | required  | Trigger text, and accessible name of the list.                                                                                                                                  |
+| `align`            | `'start' \| 'end'` | `'start'` | Horizontal alignment of the list relative to the trigger.                                                                                                                       |
+| `triggerIcon`      | `string \| null`   | `null`    | When set, the trigger renders only this icon (no visible label, no chevron) and `label` becomes its `aria-label` instead — for an icon-only trigger such as a "⋮" kebab button. |
+| `triggerAriaLabel` | `string \| null`   | `null`    | Accessible name of the trigger button when a custom trigger (below) has no text of its own, e.g. an avatar alone. Left out, the button is named by its content.                 |
+| `chevron`          | `boolean`          | `true`    | The chevron after the label or the custom trigger. Never shown with `triggerIcon`.                                                                                              |
+
+## Outputs
+
+| Output   | Type   | Role                                                                                                                                |
+| -------- | ------ | ----------------------------------------------------------------------------------------------------------------------------------- |
+| `opened` | `void` | Emitted once per closed→open transition — never on close. Useful for lazily loading the menu's contents the first time it's opened. |
+
+If you lazily populate the menu's contents on `opened`, project a placeholder item (e.g. `<a role="menuitem" class="gbt-menu__item">Chargement…</a>`) so the menu is never empty while the real content loads — otherwise a keyboard user's first ArrowDown-triggered open has nothing to focus, and other users briefly see an empty dropdown.
+
+## Projected content
+
+The list of menu items — each carries `role="menuitem"`. Write them with
+[`gbtMenuItem`](menu-item/README.md) (`<button gbtMenuItem>` / `<a gbtMenuItem>`, with
+`icon`, `variant="danger"` and `disabled`), or by hand with the `.gbt-menu__item` class (in
+`_utilities.scss`, for styling; projected content escapes the component's encapsulation) — both
+work, side by side. A real link or button, never a decorative element: it's what receives focus.
+
+One more slot, the custom trigger: an element marked `gbtMenuTrigger`.
+
+## Custom trigger (avatar + name…)
+
+By default the trigger shows `label` and a chevron. To show anything else — a user's avatar and
+name, say — project an element marked `gbtMenuTrigger` (import the `MenuTrigger` directive). Its
+content goes **inside** the trigger button, replacing the label; the menu's behaviour, the chevron
+and the list's name (`label`) are unchanged.
+
+```html
+<gbt-menu label="Account" align="end">
+  <span gbtMenuTrigger class="who">
+    <span aria-hidden="true"><gbt-avatar name="Ada Lovelace" size="sm" /></span>
+    <span>ada.lovelace</span>
+  </span>
+  <a gbtMenuItem icon="user" href="/account">My account</a>
+  <button gbtMenuItem icon="log-out" (click)="logout()">Sign out</button>
+</gbt-menu>
+```
+
+- The slot lives in a `<button>`: phrasing content only, nothing interactive.
+- The button is named by that content. Put a visible name next to a decorative avatar
+  (`aria-hidden` on the avatar avoids reading the name twice). For an avatar alone, set
+  `triggerAriaLabel`.
+- A long name can ellipsise: give the slot `min-width: 0` and the name `overflow: hidden;
+text-overflow: ellipsis; white-space: nowrap`; the trigger itself may shrink (`max-width: 100%`).
+- The marked element is always projected into the trigger; without the `MenuTrigger` import it
+  only misses the layout refinements (shrinking, padding), so import it.
+
+## Example
+
+```html
+<gbt-menu label="Mon compte" align="end">
+  <a role="menuitem" class="gbt-menu__item" href="/compte">Mon compte</a>
+  <button role="menuitem" class="gbt-menu__item" type="button" (click)="logout()">
+    Déconnexion
+  </button>
+</gbt-menu>
+```
+
+## Icon-only trigger (e.g. a kebab menu)
+
+```html
+<gbt-menu label="Actions" triggerIcon="ellipsis-vertical" align="end">
+  <a role="menuitem" class="gbt-menu__item" href="/x">Copier le chemin</a>
+  <button role="menuitem" class="gbt-menu__item" type="button" (click)="delete()">Supprimer</button>
+</gbt-menu>
+```

package/mfa-enrollment/README.md

@@ -0,0 +1,189 @@
+# MfaEnrollment
+
+The mandatory first enrolment of a second factor, shown inside the sign-in panel when the password
+step (or a free registration) answered "setup required". The user picks a factor, sets it up, then
+acknowledges the backup codes; only then does the component hand the new session to its host.
+
+It is embedded by [`gbt-auth-login`](../auth-login/login.ts) and [`gbt-auth-register`](../auth-register/register.ts)
+inside their [`gbt-auth-panel`](../auth/auth-panel/auth-panel.ts). Use it directly only to build your own
+sign-in page. The panel (logo, page heading) belongs to the host page.
+
+**Selector**: `gbt-mfa-enrollment`
+
+## Steps
+
+The step counter reads "Step n of 3".
+
+| Step      | #   | What shows                                                                                                                                                                                                                                                         |
+| --------- | --- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| `choice`  | 1   | Where a passkey can be made (`passkeysAvailable` and a browser with WebAuthn): two option cards, "Passkey" (Recommended, the single primary button) and "Authenticator app". Otherwise: the introduction of the authenticator path, three steps and "Get started". |
+| `scan`    | 2   | The QR code of the `otpauth://` URL and the secret as text ([`gbt-totp-qr`](totp-qr/totp-qr.ts)), the one-time-code field and "Activate".                                                                                                                       |
+| `passkey` | 2   | An optional key name (its default, "Passkey", is the placeholder), then "Create the passkey" opens the browser's prompt.                                                                                                                                           |
+| `codes`   | 3   | The backup codes ([`gbt-backup-codes`](backup-codes/backup-codes.ts)), shown once, and "Continue", disabled until "I have saved my backup codes" is ticked. No way back from here.                                                                              |
+
+A note ("Two-factor authentication is required…") sits on the first step, as a plain information
+note, not a live region.
+
+## Inputs
+
+| Input               | Type                           | Default    | Role                                                                                                                                                 |
+| ------------------- | ------------------------------ | ---------- | ---------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `mfaToken`          | `string`                       | (required) | The short-lived token of the password step (`LoginResponse.mfaToken`): the credential of every enrolment call.                                       |
+| `passkeysAvailable` | `boolean`                      | `false`    | The server can run passkey ceremonies (`AuthConfig.passkeysAvailable`). A passkey is offered only when the browser can too (read once, on creation). |
+| `labels`            | `Partial<MfaEnrollmentLabels>` | `{}`       | Strings to change, over `provideAuthLabels({ mfaEnrollment })` and the English defaults (`DEFAULT_MFA_ENROLLMENT_LABELS`).                           |
+
+## Outputs
+
+| Output      | Payload  | Role                                                                                                                                                                                                                 |
+| ----------- | -------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `completed` | `string` | The codes are acknowledged and "Continue" was pressed: the SESSION token. Hand it to `AuthPort.setToken` (the login and register pages do) and move on. The component never stores it.                               |
+| `cancelled` | `void`   | "Back" on the first step, or on the second when there is no choice to go back to: return to the credentials.                                                                                                         |
+| `expired`   | `void`   | The `mfaToken` is no longer usable (a 401 `invalid or expired token`, or a 400 `MFA is already set up`): return to the credentials. The component also shows why, in its alert, in case the host keeps it on screen. |
+
+## Slots
+
+None. The nested QR and backup codes take their strings from `provideAuthLabels({ totpQr, backupCodes })`
+(or `DEFAULT_TOTP_QR_LABELS` / `DEFAULT_BACKUP_CODES_LABELS`); the component's `labels` input only covers
+its own strings.
+
+## Dependencies
+
+| Token              | Required | Used for                                                                                                                                                                                               |
+| ------------------ | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| `AUTH_PORT`        | yes      | `enrollTotp(mfaToken)`, `confirmTotp(mfaToken, code)`, `startPasskeySetup(mfaToken)`, `finishPasskeySetup(mfaToken, challengeId, credential, name)`. The two confirmations must NOT store the session. |
+| `TOTP_QR_RENDERER` | no       | Draws the QR (Gabarit ships no encoder). Without one, `gbt-totp-qr` shows its fallback and the secret to type by hand.                                                                                 |
+| `AUTH_LABELS`      | no       | Application-wide strings (`provideAuthLabels`).                                                                                                                                                        |
+
+## Behaviour
+
+- **Nothing is asked before a choice.** The first call is made by "Get started" / "Use an app"
+  (`enrollTotp`) or "Create the passkey" (`startPasskeySetup`); choosing "Use a passkey" only opens the
+  name step.
+- **The code** is sent stripped of spaces. An empty field is refused without a call ("Enter the 6-digit
+  code from your app").
+- **The passkey name** is trimmed; empty or blank, the key is named `defaultPasskeyName`. More than 40
+  characters (code points) or control characters are refused before any call, with the focus on the field.
+- **Busy states.** The primary button of the step shows its spinner while a call is in flight and a second
+  submit is ignored; the busy state is rolled back on any failure. On the passkey step a polite note
+  ("Confirm on your device to create the key.") shows while the browser's prompt is open, and "Back" stays
+  enabled (the prompt can be lost behind a window).
+- **Stale ceremonies are dropped.** Leaving the passkey step while the server or the browser has not answered
+  yet opens no prompt and sends no attestation.
+- **Recreate this component per `mfaToken`** (e.g. with an `@if` / `*ngIf` keyed on the token, as
+  `gbt-auth-login` and `gbt-auth-register` already do): **it does not reset its internal state when the input
+  changes.** Its step, the held-back session and the acknowledgement would survive a new token, and a later
+  "Continue" could emit the previous flow's session.
+- **Known race: "Back" while a passkey `finish` call is in flight.** Pressing "Back" once the browser has
+  answered and `finishPasskeySetup` is still on its way cancels the flow (`cancelled` fires) and its answer is
+  dropped: the passkey and its backup codes may then exist on the server without the user ever seeing the
+  codes: at the next sign-in the account already has that passkey, and regenerating the codes from the
+  account settings replaces the unseen ones.
+- **No backup codes, no codes step.** A server that issues none with the chosen factor (an empty
+  `backupCodes`) ends the enrolment there: `completed` carries the session token at once.
+- **The session is held back** until the codes are acknowledged; the secret, the `otpauth://` URL and the code
+  are dropped as soon as the factor is confirmed.
+- **Focus.** Each step opens on its heading (`h2`, `tabindex="-1"`), so the change is announced and the QR stays
+  in view (no phone keyboard over it). After a failure the focus goes back where the user acts: the field, or
+  the button that was disabled while loading.
+
+### Failures
+
+The port's errors are read by status and by the `error` string of their body (see
+[`AUTH_PORT_ERROR_BODIES`](../auth/shared/port-error.ts)). The backend's own wording is never shown.
+
+| Answer                                   | Where                | Message (label)                                                          | `expired` |
+| ---------------------------------------- | -------------------- | ------------------------------------------------------------------------ | --------- |
+| 401 `invalid or expired token`           | any call             | `loginExpired`                                                           | yes       |
+| 400 `MFA is already set up`              | any call             | `alreadySetUp`                                                           | yes       |
+| 429                                      | any call             | `tooManyAttempts`                                                        | no        |
+| 400 `invalid code` (or another 401)      | `confirmTotp`        | `wrongCode`, the field emptied                                           | no        |
+| 409                                      | passkey calls        | `alreadyRegistered`                                                      | no        |
+| 503                                      | passkey calls        | `passkeysUnavailable`                                                    | no        |
+| anything else (network failure included) | the call             | `startFailed`, `activationFailed` or `passkeyFailed`                     | no        |
+| `NotAllowedError` / `AbortError`         | the browser's prompt | `cancelled`, as a quiet information note (`role="status"`), not an error | no        |
+| `InvalidStateError`                      | the browser's prompt | `alreadyRegistered`                                                      | no        |
+| `NotSupportedError`                      | the browser's prompt | `browserUnsupported`                                                     | no        |
+| any other browser error                  | the browser's prompt | `passkeyFailed`                                                          | no        |
+
+## Example
+
+The application provides its backend once:
+
+```ts
+// app.config.ts
+import { type ApplicationConfig } from '@angular/core'
+import { provideHttpClient } from '@angular/common/http'
+import { AUTH_PORT, TOTP_QR_RENDERER, provideAuthLabels } from '@masmarino/gabarit'
+import { HttpAuthPort } from './auth/http-auth-port' // your AuthPort over HttpClient
+
+export const appConfig: ApplicationConfig = {
+  providers: [
+    provideHttpClient(),
+    { provide: AUTH_PORT, useClass: HttpAuthPort },
+    {
+      provide: TOTP_QR_RENDERER,
+      // Loaded only when the QR is drawn. It receives the raw TOTP secret: a LOCAL encoder only, never a
+      // hosted QR service, never logged (see ../totp-qr/README.md).
+      useValue: (text: string, options: object) =>
+        import('qrcode').then((m) => m.toDataURL(text, options)),
+    },
+    // Optional: localise the kit once (each part partial).
+    provideAuthLabels({
+      mfaEnrollment: { choiceHeading: 'Protégez votre compte', begin: 'Commencer' },
+      totpQr: { secretLabel: 'Ou saisissez cette clé dans votre application' },
+      backupCodes: { acknowledge: "J'ai enregistré mes codes de secours" },
+    }),
+  ],
+}
+```
+
+With `gbt-auth-login` (or `gbt-auth-register`) there is nothing more to wire: the page shows the enrolment,
+hands the session to `AuthPort.setToken` and emits `loggedIn` (`registered`). Its footer link is projected
+by the application, for example with the router:
+
+```html
+<gbt-auth-login (loggedIn)="router.navigateByUrl('/')">
+  <img auth-logo src="/logo.svg" alt="Acme" />
+  <a gbtButton variant="link" gbtAuthFooterLink routerLink="/register">Create an account</a>
+</gbt-auth-login>
+```
+
+A page of your own embeds the component in the panel and handles its outputs:
+
+```ts
+@Component({
+  selector: 'app-setup-mfa',
+  imports: [AuthPanel, MfaEnrollment],
+  template: `
+    <gbt-auth-panel wide heading="Two-factor authentication">
+      <img auth-logo src="/logo.svg" alt="Acme" />
+      <gbt-mfa-enrollment
+        [mfaToken]="mfaToken"
+        [passkeysAvailable]="passkeysAvailable"
+        (completed)="done($event)"
+        (cancelled)="router.navigateByUrl('/login')"
+        (expired)="router.navigateByUrl('/login')"
+      />
+    </gbt-auth-panel>
+  `,
+})
+export class SetupMfaPage {
+  protected readonly router = inject(Router)
+  private readonly auth = inject(AUTH_PORT)
+  // From the password step (LoginResponse.mfaToken) and AuthConfig.passkeysAvailable.
+  mfaToken = '…'
+  passkeysAvailable = false
+
+  done(sessionToken: string): void {
+    this.auth.setToken(sessionToken)
+    this.router.navigateByUrl('/')
+  }
+}
+```
+
+The login and register pages do not forward a `labels` input to the enrolment: localise it there with
+`provideAuthLabels({ mfaEnrollment })`.
+
+## Accessibility
+
+See [AUDIT.md](AUDIT.md).