@masmarino/gabarit 1.4.0 → 2.1.0

package/alert/README.md

@@ -0,0 +1,87 @@
+# Alert
+
+Persistent inline message — a banner within a page or section, not a
+transient notification. Distinct from `Toaster` (auto-dismissing,
+stacked at a screen corner): `Alert` stays visible for as long as the
+app renders it.
+
+**Selector**: `gbt-alert`
+
+## Inputs
+
+| Input         | Type              | Default     | Role                                                                                                                                                                                                               |
+| ------------- | ----------------- | ----------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| `variant`     | `AlertVariant`    | `'info'`    | `'info' \| 'success' \| 'warning' \| 'error' \| 'neutral'` (`neutral`: a quiet grey status line or review bar).                                                                                                    |
+| `dismissible` | `boolean`         | `false`     | Shows a close button.                                                                                                                                                                                              |
+| `closeLabel`  | `string`          | `'Dismiss'` | Accessible name of the close button.                                                                                                                                                                               |
+| `live`        | `AlertLive`       | `'auto'`    | `'auto' \| 'assertive' \| 'polite' \| 'off'` — how the alert is announced (see _Role_).                                                                                                                            |
+| `heading`     | `string`          | `''`        | A short bold title above the message.                                                                                                                                                                              |
+| `size`        | `AlertSize`       | `'md'`      | `'md' \| 'sm'` — `sm` is the tighter alert for side panels, hints and dense cards.                                                                                                                                 |
+| `appearance`  | `AlertAppearance` | `'default'` | `'default' \| 'subtle'` — subtle: lighter wash, hairline edge and icon ring.                                                                                                                                       |
+| `iconAlign`   | `AlertIconAlign`  | `'auto'`    | `'auto' \| 'center' \| 'start'` — `auto` centres the icon on a single block and moves it to the first line once there is a `heading` or `[alert-actions]`; `start` forces the top, `center` opts out.             |
+
+## Outputs
+
+| Output      | Type   | Role                                                                                                                                                        |
+| ----------- | ------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `dismissed` | `void` | Emitted when the close button is clicked — `Alert` does not remove itself, like `Toaster`'s own close button; the app decides whether to stop rendering it. |
+
+## Content
+
+The message comes from projected content (`<ng-content />`), so it can
+include an action link, not just plain text.
+
+`[alert-actions]` projects buttons or links into a slot beside
+the message — they share the row while there is room and drop under the
+message when there is not:
+
+```html
+<gbt-alert variant="error">
+  Les variables n'ont pas pu être chargées.
+  <gbt-button alert-actions variant="secondary" size="small" text="Réessayer" (clicked)="retry()" />
+</gbt-alert>
+
+<gbt-alert variant="error" heading="Impossible de charger le tableau de bord">
+  Le service de métriques ne répond pas.
+  <gbt-button alert-actions variant="secondary" size="small" text="Réessayer" />
+</gbt-alert>
+```
+
+## Example
+
+```html
+<gbt-alert variant="warning">Le quota du dépôt est presque atteint.</gbt-alert>
+
+<gbt-alert variant="error" [dismissible]="true" closeLabel="Fermer" (dismissed)="showError = false">
+  Le paiement a échoué. <a href="/facturation">Mettre à jour le moyen de paiement</a>
+</gbt-alert>
+```
+
+## Role and `live`
+
+With the default `live="auto"`, `warning` and `error` use `role="alert"`
+(announced immediately), `info`, `success` and `neutral` use `role="status"`
+(announced politely) — the same split `Toaster` already uses for its
+variants.
+
+`live` overrides that mapping:
+
+| `live`        | Result                                                      |
+| ------------- | ----------------------------------------------------------- |
+| `'auto'`      | The mapping above (default).                                |
+| `'assertive'` | `role="alert"` whatever the variant.                        |
+| `'polite'`    | `role="status"` whatever the variant.                       |
+| `'off'`       | No `role`, no `aria-live`, no `aria-atomic`: a static note. |
+
+A live region only announces what appears **after** the page has loaded.
+A note that is on the page from the start (a warning above a form, a
+footnote) should be `live="off"`, otherwise a static `warning` interrupts
+screen-reader users for nothing. A message that appears as the result of an
+action (a failed save, a load error) keeps `auto`, or `polite` when it is
+not urgent. Never nest an alert inside another live region.
+
+## Touch
+
+The close button is 44 × 44 px on coarse pointers
+(`@media (pointer: coarse)`); the alert keeps its height, only the hit area
+and the focus ring grow.

package/app-shell/README.md

@@ -0,0 +1,133 @@
+# AppShell
+
+Page shell — side navigation panel, header, content. Below the 768px
+breakpoint, the navigation becomes a drawer: the button opens it, the
+backdrop or Escape closes it, focus is trapped inside while it's open
+and returns to the button on close.
+
+The header and the navigation are held to the window: while a long page
+scrolls, both stay in view, so the version and the collapse toggle are
+always in reach. Links that outgrow the window scroll inside the
+navigation, under its bottom (version and toggle), which stays put.
+
+**Selector**: `gbt-app-shell`
+
+## Inputs
+
+| Input            | Type      | Role                                                                                                                                                                                                                               |
+| ---------------- | --------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `navLabel`       | `string`  | Required. Accessible name of the navigation (`<nav aria-label>`).                                                                                                                                                                  |
+| `skipLabel`      | `string`  | Required. Text of the skip link to the content.                                                                                                                                                                                    |
+| `openMenuLabel`  | `string`  | Required. Accessible name of the button, drawer closed.                                                                                                                                                                            |
+| `closeMenuLabel` | `string`  | Required. Accessible name of the button, drawer open.                                                                                                                                                                              |
+| `collapseLabel`  | `string`  | Required if `collapsible` is `true`. Accessible name of the collapse-toggle button, nav expanded.                                                                                                                                  |
+| `expandLabel`    | `string`  | Required if `collapsible` is `true`. Accessible name of the collapse-toggle button, nav collapsed.                                                                                                                                 |
+| `collapsed`      | `boolean` | Optional, defaults to `false`. Fully controlled — `AppShell` never persists it; bind `[(collapsed)]` to a signal you own if you want it remembered across sessions. Only has an effect at/above the 768px breakpoint.              |
+| `collapsible`    | `boolean` | Optional, defaults to `true`. Set to `false` to omit the built-in collapse-toggle button entirely — e.g. if your app drives `collapsed` from its own control elsewhere. When `false`, `collapseLabel`/`expandLabel` aren't needed. |
+
+## Outputs
+
+| Output            | Type      | Role                                                                                                                            |
+| ----------------- | --------- | ------------------------------------------------------------------------------------------------------------------------------- |
+| `collapsedChange` | `boolean` | Emitted when the collapse-toggle button is clicked, with the new desired value — `AppShell` does not update `collapsed` itself. |
+
+## Projected content
+
+| Selector         | Role                                                                                                                                                                                                                                                                                                                                                                                                                                                 |
+| ---------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `[shell-brand]`  | The brand, at the top of the navigation. With `collapsed`, plain text is clipped with an ellipsis rather than overflowing the rail — but since you already own the `collapsed` signal you bind to `[collapsed]`/`(collapsedChange)`, prefer swapping in a compact icon yourself (see example below) over relying on the ellipsis.                                                                                                                    |
+| `[shell-nav]`    | The navigation links. `.gbt-app-shell__link` (in `_utilities.scss`) for styling; `aria-current="page"` denotes the current page — never a class alone. When using `collapsed`, each link's structure must be `<gbt-icon .../><span>Label</span>` — the icon stays visible in the rail, and the `<span>` is what the hover/focus flyout reveals. For a collapsible group of links, see [`gbt-app-shell-nav-group`](app-shell-nav-group/README.md). |
+| `[shell-header]` | Header content: title, search, account menu… Several elements can project into this same slot.                                                                                                                                                                                                                                                                                                                                                       |
+| Default          | The page content, in a focusable `<main>`.                                                                                                                                                                                                                                                                                                                                                                                                           |
+
+**The collapsed rail's flyout.** In the 64 px rail a link shows only its icon; on hover or keyboard focus its
+`<span>` label appears to the right of the rail, in a small bordered bubble (`--text-primary` on `--bg-principal`,
+above the header and the page). The bubble sits outside the link and the rail, so the collapsed rail and its links
+do not clip their box (`overflow: visible`); expanded, and in the mobile drawer, they do clip. A link that is not
+the `<gbt-icon /><span>` structure (text only, a badge outside the span) spills over the page in the collapsed
+rail: give every collapsible link that structure. The bubble opens on a real hover only (`@media (hover: hover)`: a
+tap on a touch screen does not leave it painted over the page) and on keyboard focus; a bridge in front of it lets
+the pointer travel from the link onto the label without the flyout closing.
+
+`.gbt-app-shell` sets the background (`--bg-panel`) of the whole page,
+content included — cards and other surfaces left on `--bg-principal`
+stand out from it by contrast. `.gbt-container` (in `_utilities.scss`)
+centers content at reading width, to place on the default-projected
+content if needed.
+
+## Example
+
+```html
+<gbt-app-shell
+  navLabel="Navigation principale"
+  skipLabel="Aller au contenu principal"
+  openMenuLabel="Ouvrir la navigation"
+  closeMenuLabel="Fermer la navigation"
+  collapseLabel="Réduire la navigation"
+  expandLabel="Agrandir la navigation"
+>
+  <a shell-brand href="/">Hangar</a>
+  <a shell-nav href="/depots" class="gbt-app-shell__link" aria-current="page">Dépôts</a>
+  <a shell-nav href="/utilisateurs" class="gbt-app-shell__link">Utilisateurs</a>
+  <h1 shell-header>Dépôts</h1>
+  <div shell-header style="margin-left:auto">
+    <gbt-menu label="Mon compte" align="end">...</gbt-menu>
+  </div>
+
+  <p>Contenu de la page.</p>
+</gbt-app-shell>
+```
+
+With `collapsed` bound, each `[shell-nav]` link must use the `<gbt-icon
+.../><span>Label</span>` structure described in the table above, so the
+hover/focus flyout has a label to reveal. Since you already own the
+`sidebarCollapsed` signal to drive `[collapsed]`/`(collapsedChange)`, reuse
+it in `[shell-brand]` to swap in a compact logo yourself — no extra input
+or output needed on `AppShell` for this:
+
+```html
+<gbt-app-shell
+  navLabel="Navigation principale"
+  skipLabel="Aller au contenu principal"
+  openMenuLabel="Ouvrir la navigation"
+  closeMenuLabel="Fermer la navigation"
+  collapseLabel="Réduire la navigation"
+  expandLabel="Agrandir la navigation"
+  [collapsed]="sidebarCollapsed()"
+  (collapsedChange)="sidebarCollapsed.set($event)"
+>
+  <a shell-brand href="/" aria-label="Hangar">
+    @if (sidebarCollapsed()) {
+    <gbt-icon name="logo-mark" />
+    } @else {
+    <gbt-icon name="logo-full" />
+    <span>Hangar</span>
+    }
+  </a>
+  <a shell-nav href="/depots" class="gbt-app-shell__link" aria-current="page">
+    <gbt-icon name="folder" />
+    <span>Dépôts</span>
+  </a>
+  <h1 shell-header>Dépôts</h1>
+  <p>Le contenu de la page.</p>
+</gbt-app-shell>
+```
+
+With `[collapsible]="false"`, the built-in button is omitted — `collapseLabel`/
+`expandLabel` become unnecessary, and `collapsed`/`(collapsedChange)` stay
+available if you drive the state from your own control elsewhere:
+
+```html
+<gbt-app-shell
+  navLabel="Navigation principale"
+  skipLabel="Aller au contenu principal"
+  openMenuLabel="Ouvrir la navigation"
+  closeMenuLabel="Fermer la navigation"
+  [collapsible]="false"
+>
+  <a shell-brand href="/">Hangar</a>
+  <a shell-nav href="/depots" class="gbt-app-shell__link" aria-current="page">Dépôts</a>
+  <h1 shell-header>Dépôts</h1>
+  <p>Le contenu de la page.</p>
+</gbt-app-shell>
+```

package/auth/README.md

@@ -0,0 +1,155 @@
+# Auth kit
+
+The public sign-in pages and the account's second-factor settings, as components an application uses
+as they are: login (with the MFA challenge), free registration, invitation activation, the new
+password after an administrator's reset, the mandatory
+first MFA enrolment (authenticator app or passkey, then backup codes), and the account cards for the
+authenticator app and the passkeys. Every application that uses them gets the same behaviour, the same
+accessibility and the same look, by construction.
+
+The kit is **router-agnostic** (it never imports `@angular/router`: it emits outputs and shows the
+links the application projects), **backend-agnostic** (it never talks HTTP: every call goes through a
+port the application implements), **storage-agnostic** (it never touches `localStorage`: sessions are
+the port's business) and **locale-agnostic** (every string is a label with an English default).
+
+| Component                                                 | Selector               | Port                                     |
+| --------------------------------------------------------- | ---------------------- | ---------------------------------------- |
+| [`AuthLogin`](../auth-login/README.md)                          | `gbt-auth-login`       | `AUTH_PORT`                              |
+| [`AuthRegister`](../auth-register/README.md)                    | `gbt-auth-register`    | `AUTH_PORT`                              |
+| [`AuthActivate`](../auth-activate/README.md)                    | `gbt-auth-activate`    | `AUTH_PORT`                              |
+| [`AuthResetPassword`](../auth-reset-password/README.md)         | `gbt-auth-reset-password` | `AUTH_PORT`                           |
+| [`MfaEnrollment`](../mfa-enrollment/README.md)             | `gbt-mfa-enrollment`   | `AUTH_PORT`                              |
+| [`MfaSettings`](../mfa-settings/README.md)                 | `gbt-mfa-settings`     | `MFA_PORT`                               |
+| [`PasskeySettings`](../passkey-settings/README.md)         | `gbt-passkey-settings` | `MFA_PORT` (and `AUTH_PORT` if provided) |
+| [`AuthPanel`](auth-panel/README.md)                     | `gbt-auth-panel`       | —                                        |
+| [`AuthFooter`, `AuthFooterLink`](auth-footer/README.md) | `gbt-auth-footer`      | —                                        |
+| [`TotpQr`](../mfa-enrollment/totp-qr/README.md)                           | `gbt-totp-qr`          | — (`TOTP_QR_RENDERER`)                   |
+| [`BackupCodes`](../mfa-enrollment/backup-codes/README.md)                 | `gbt-backup-codes`     | —                                        |
+
+## Wiring
+
+```ts
+// app.config.ts
+providers: [
+  { provide: AUTH_PORT, useExisting: AuthService }, // your service implements AuthPort
+  { provide: MFA_PORT, useExisting: MfaService }, // your service implements MfaPort
+  {
+    provide: TOTP_QR_RENDERER, // Gabarit ships no QR encoder: bring one, loaded lazily
+    useValue: (text: string, options: TotpQrRenderOptions) =>
+      import('qrcode').then((qr) => qr.toDataURL(text, options)),
+  },
+  provideAuthLabels(MY_AUTH_LABELS), // optional: localise the whole kit once
+]
+```
+
+> **Security: `TOTP_QR_RENDERER` receives the user's TOTP secret.** It is called with the full
+> `otpauth://…?secret=…` URL, raw secret included. The renderer **must encode locally**, in the
+> browser (a bundled library such as `qrcode`, as above): **no network call, never a hosted or
+> third-party QR service** (a `https://…?data=otpauth…` image would hand every user's second factor
+> to that service and its access logs). It **must not log** the text, nor send it to analytics or
+> error reports. See [TotpQr](../mfa-enrollment/totp-qr/README.md).
+
+```html
+<!-- login.page.html: a thin wrapper, routed at /login -->
+<gbt-auth-login (loggedIn)="router.navigateByUrl('/home')">
+  <img auth-logo src="logo.svg" alt="Acme" width="480" height="120" />
+  <a gbtButton variant="link" gbtAuthFooterLink routerLink="/register">Create an account</a>
+</gbt-auth-login>
+```
+
+Every page takes the application's logo in its `[auth-logo]` slot (an `img`, a `picture` or an
+`svg`) and the link of its footer in `[gbtAuthFooterLink]` (an `a[gbtButton]` in its `link` variant,
+carrying the application's `routerLink` or `href`). A page without a projected footer link shows no
+footer.
+
+**`gbt-auth-register`, `gbt-auth-activate` and `gbt-auth-reset-password` also emit `(signIn)`**, from
+their own terminal states (registration closed, account created, activation succeeded, password
+changed, dead link), where "Sign in" is a button
+rather than the projected link. That output is in addition to the projected `[gbtAuthFooterLink]`,
+not instead of it: **wire both** (`(signIn)="router.navigateByUrl('/login')"` and the footer link)
+for every path to reach the sign-in page.
+
+## The `AuthPort` contract
+
+- **Sessions.** `login`, `register`, `verifyMfa` and `finishPasskeyChallenge` store the session they
+  obtain, when there is one (`LoginResponse.token` not null), then the page emits its success output.
+  `confirmTotp` and `finishPasskeySetup` must **not** store theirs: the enrolment holds the session
+  back until the user has acknowledged the backup codes (shown once), then the page hands it to
+  `setToken(token)` and emits.
+- **MFA.** A `LoginResponse` with `token: null` and an `mfaToken` sends the user to the challenge
+  (`mfaHasTotp`, `mfaHasPasskey` say what they can use) or, with `mfaSetupRequired`, to the mandatory
+  enrolment.
+- **Configuration.** `authConfig()` is read once by the login page (a failed read hides the
+  registration link; passkeys stay "unknown", which does not block them) and by the registration page
+  (a failed read shows the form: the server has the last word).
+
+## The error contract
+
+A failed port call errors with `{ status, error }`: the HTTP status and the response body, the shape
+of Angular's `HttpErrorResponse` (an adapter on `HttpClient` passes its errors through untouched). A
+browser's WebAuthn error (a `DOMException`, no `status`) is told apart from a server answer by that
+shape. The kit words every failure itself; the server's text is never shown. What it recognises
+(`AUTH_PORT_ERROR_BODIES` holds the strings):
+
+| Call                                  | Answer                                                                                                             | Read as                                                                      |
+| ------------------------------------- | ------------------------------------------------------------------------------------------------------------------ | ---------------------------------------------------------------------------- |
+| `login`                               | 401                                                                                                                | wrong username or password (any other failure: "sign-in failed")             |
+| any                                   | 429                                                                                                                | too many attempts                                                            |
+| MFA calls with an `mfaToken`          | 401 `invalid or expired token`                                                                                     | the sign-in expired: back to the credentials                                 |
+| `verifyMfa`, `finishPasskeyChallenge` | 401 (any other body)                                                                                               | wrong code / passkey refused                                                 |
+| `confirmTotp`, `confirm`              | 400 `invalid code`                                                                                                 | wrong code                                                                   |
+| enrolment calls                       | 400 `MFA is already set up`                                                                                        | the account got a factor meanwhile: back to the credentials                  |
+| passkey calls                         | 503                                                                                                                | passkeys not available on this server                                        |
+| `finishPasskeySetup`, registration    | 409                                                                                                                | this key is already registered                                               |
+| password-gated `MfaPort` calls        | 400 `current password is incorrect` (exactly)                                                                      | wrong password (never a 401, which an interceptor would take for a sign-out) |
+| `startPasskeyRegistration`/`finish…`  | 400 `too many passkeys`                                                                                            | the account holds the most passkeys the server keeps                         |
+| `deletePasskey`                       | 404                                                                                                                | already gone: removed from the list, nobody signed out                       |
+| `register`                            | 400 `registration is disabled`                                                                                     | the closed state                                                             |
+| `register`                            | 400 `username is reserved` / `username …` / `email is not a valid address` / `password must be at least …` / other | the field concerned, else "check the fields"                                 |
+| `register`                            | 409 `email already in use` / other 409                                                                             | address taken / name taken                                                   |
+| `activate`, `resetPassword`           | 400 `password must be at least …` / other 400                                                                      | weak password (the link still works) / dead link                             |
+
+An adapter for a backend that words these differently maps its answers onto them with `catchError`.
+
+## Session revocation
+
+`MfaPort.disable` and `MfaPort.deletePasskey` revoke the caller's own session on the server (MFA
+being mandatory, removing a factor signs every device out). The cards then emit `sessionRevoked`:
+the application must discard its local session and go to its sign-in page. As a safety net, the card
+that revoked the session also turns inert ("You have been signed out", its `signedOut` label, and no
+action left), so an unbound output never leaves a live card acting on a dead session; it cannot clear
+the application's stored session, though: binding `sessionRevoked` stays mandatory.
+
+## Activation and password-reset links
+
+The mail should carry the token in the URL fragment (`/activate#token=…`,
+`/reset-password#token=…`), which no server ever sees. The application's wrapper reads it once with
+`activationToken(fragment, query)`, removes it from the address bar and history
+(`navigateByUrl('/activate', { replaceUrl: true })`), and hands it to the `token` input of
+`gbt-auth-activate` or `gbt-auth-reset-password`.
+
+**The `token` input must be a one-time snapshot of the URL, never a value that reactively follows the
+URL (e.g. a signal derived from `route.fragment`): the component resets when it changes.** Scrubbing
+the URL would otherwise turn the token into `null` and flip the page to the dead-link view, even over
+its success view.
+
+## Labels
+
+Each component has a `labels` input (a partial object) over `provideAuthLabels({ … })` over its
+English defaults (`DEFAULT_LOGIN_LABELS`, …); nested pieces (`gbt-mfa-enrollment` inside the login
+page, `gbt-totp-qr` and `gbt-backup-codes` inside the enrolment and the settings) read the provided
+labels, so an application localises the whole kit in one place. Interpolated strings are functions
+(`step(current, total)`, `codesLeft(count)`, `passkeyAdded(name)`…).
+
+## The account cards together
+
+`gbt-mfa-settings` and `gbt-passkey-settings` are meant to sit side by side. They share
+`MfaSettingsState` (root-provided; provide it on a page to scope it): the factors as last read or
+changed by either card, so the app becomes optional as soon as a passkey is added and deleting the
+only key is flagged as removing the last factor; and which card owns the open form, so a view never
+shows two password prompts (two primary buttons) at once.
+
+## Theming
+
+`--gbt-auth-panel-logo-width` (15rem) sizes the logo; `--gbt-auth-panel-logo-offset` (0) pulls it
+up when the artwork has a transparent margin above its drawing.

package/auth-activate/README.md

@@ -0,0 +1,119 @@
+# AuthActivate
+
+The activation page of the auth kit: where the link of an invitation mail lands, outside the app shell,
+in the sign-in panel ([`gbt-auth-panel`](../auth/auth-panel/auth-panel.ts)). The invited user chooses a
+password; no session comes out of it: they sign in afterwards and are taken through the mandatory MFA
+enrolment like everybody. It never talks HTTP, never reads the URL and never navigates: the backend is
+the application's `AUTH_PORT`, the token is an input, and the page tells the application where to go
+through its outputs.
+
+**Selector**: `gbt-auth-activate`
+
+## Views
+
+| View    | What shows                                                                                                                                                                |
+| ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| form    | A token was given: "Activate your account", New password (with its hint), Confirm the password, one primary "Activate my account", then the projected sign-in link.       |
+| success | The server accepted: "Your account is activated", what comes next, one "Sign in" button.                                                                                  |
+| invalid | No token (`null` or `''`), or the server refused it (unknown, expired or used): an error-toned state, "This link does not work", ask for a new invitation, one "Sign in". |
+
+## Inputs
+
+| Input               | Type                      | Default                   | Role                                                                                                                                                                                               |
+| ------------------- | ------------------------- | ------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `token`             | `string \| null`          | `null`                    | The invitation's token, as the application read it from its URL with `activationToken(fragment, query)`. `null` (or `''`) is the dead link, without any request. A new value starts the page over. |
+| `labels`            | `Partial<ActivateLabels>` | `{}`                      | Strings to change, over `provideAuthLabels({ activate })` and the English defaults (`DEFAULT_ACTIVATE_LABELS`).                                                                                    |
+| `minPasswordLength` | `number`                  | `MIN_PASSWORD_LENGTH` (8) | The server's minimum password length, checked before the round trip; also worded in the hint and the errors.                                                                                       |
+| `chooseUsername`    | `boolean`                 | `false`                   | For servers where the administrator invites by e-mail only: a Username field comes first, and the invitee's choice is sent as `activate(token, password, username)`.                             |
+| `usernamePattern`   | `RegExp`                  | `USERNAME_PATTERN`        | The server's username rule, checked before the round trip when `chooseUsername` is on.                                                                                                             |
+
+## Outputs
+
+| Output      | Payload | Role                                                                             |
+| ----------- | ------- | -------------------------------------------------------------------------------- |
+| `activated` | `void`  | The server accepted the password: the success view shows. No session was opened. |
+| `signIn`    | `void`  | "Sign in" was pressed in the success or dead-link view: go to the sign-in page.  |
+
+## Slots
+
+| Selector              | Role                                                                                                                                                                          |
+| --------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `[auth-logo]`         | The application's logo (an `img`, `picture` or `svg`), on top of the panel. Optional.                                                                                         |
+| `[auth-backdrop]` | What is drawn on the graphite page, behind the panel: `gbt-git-field`, the family's animated commit graph (`@masmarino/gabarit/git-field`). Optional. |
+| `[gbtAuthFooterLink]` | The link to the sign-in page, under the form after "Is your account already active?". An `a gbtButton variant="link"` carrying `routerLink` or `href`. No footer when absent. |
+
+## Behaviour
+
+- **The token.** The page sends it with the password (`activate(token, password)`) and never renders it
+  (not in the markup, not in a field). Once spent (success) or refused (a 400 other than a weak password),
+  it is dropped: the page does not send it again until a new `token` arrives.
+- **The application's part** (it owns the URL): put the token in the link's **fragment**
+  (`/activate#token=…`) so that no server, proxy or access log ever sees it; read it once with
+  `activationToken(route.snapshot.fragment, route.snapshot.queryParamMap.get('token'))` (the query is only a
+  fallback for older links; a token not shaped like the server's is `null`); then remove it (and any other
+  parameter) from the address bar and the history entry, e.g.
+  `router.navigateByUrl('/activate', { replaceUrl: true })` after the first render, so it does not linger in
+  a screenshot or a shared tab.
+- **The `token` input must be a one-time snapshot of the URL, never a value that reactively follows the
+  URL (e.g. a signal derived from `route.fragment`): the component resets when it changes.** Scrubbing the
+  URL as above would otherwise turn the token into `null` and flip the page to the dead-link view, even over
+  its success view. Read it into a plain field, as in the example below.
+- **`chooseUsername`.** The intro becomes `introWithUsername`, the Username field (with `usernameHint`) comes
+  before the passwords and takes the first focus, and it is checked first (`usernameEmpty`,
+  `usernameInvalid`). The value is sent trimmed; the server keeps the final say: a 400 `username is reserved`
+  (`usernameReserved`), another 400 starting with `username ` (`usernameInvalid`) or a 409
+  (`usernameTaken`) keeps the form, in an alert, the focus in the Username field.
+- **`minPasswordLength` must mirror the server's own rule.** It only spares a round trip: the server stays
+  the authority, and a looser value only moves the refusal to the server's answer.
+- **Checks before the request.** Nothing is said while typing; after a first attempt the password rule and
+  the confirmation ("Confirm your password", "The passwords do not match") show under their fields, the
+  focus moves to the first wrong one, and the checks stay live.
+- **Failures** are worded from the labels, in an alert, the focus back in the password field: a weak-password
+  400 keeps the form (the link is still good), a 429 says to wait, anything else (5xx, network) says the
+  activation failed and the same token can be retried. Any other 400 (but the username ones, with
+  `chooseUsername`) is the dead link.
+- **Focus**: the form starts in the new-password field; the success and dead-link views move the focus to
+  their `h1` (focusable by script, not a tab stop). The passwords are emptied when the server accepted or
+  refused the link.
+
+## Example
+
+```ts
+// app.config.ts
+providers: [
+  { provide: AUTH_PORT, useClass: HttpAuthPort }, // your adapter over HttpClient
+  provideAuthLabels({ activate: { signInPrompt: 'Already signed up?' } }),
+]
+```
+
+```ts
+@Component({
+  imports: [AuthActivate, Button, AuthFooterLink, RouterLink],
+  template: `
+    <gbt-auth-activate [token]="token" (signIn)="router.navigateByUrl('/login')">
+      <img auth-logo src="/logo.svg" alt="Acme" width="160" height="40" />
+      <a gbtButton variant="link" gbtAuthFooterLink routerLink="/login">Sign in</a>
+    </gbt-auth-activate>
+  `,
+})
+export class ActivateRoute {
+  protected readonly router = inject(Router)
+  private readonly route = inject(ActivatedRoute)
+  // Read once, then scrubbed from the address bar and the history entry.
+  protected readonly token = activationToken(
+    this.route.snapshot.fragment,
+    this.route.snapshot.queryParamMap.get('token'),
+  )
+
+  constructor() {
+    const { fragment, queryParamMap } = this.route.snapshot
+    if (fragment !== null || queryParamMap.keys.length > 0) {
+      afterNextRender(() => void this.router.navigateByUrl('/activate', { replaceUrl: true }))
+    }
+  }
+}
+```
+
+## Accessibility
+
+See [AUDIT.md](AUDIT.md). The panel owns the page's `<main>` landmark and its `h1`.

package/auth-login/README.md

@@ -0,0 +1,113 @@
+# AuthLogin
+
+The sign-in page of the auth kit, outside the app shell: the application's logo,
+a heading, the username and password fields and one "Sign in" button; then,
+when the password is accepted, the second factor. It is router-, storage- and
+backend-agnostic: every call goes through the application's
+[`AuthPort`](../auth/ports/auth.port.ts), and the page tells the application the
+user is signed in with `loggedIn` (the application navigates).
+
+**Selector**: `gbt-auth-login`
+
+## States
+
+| State       | When                                                                           | What shows                                                                                                                                                                                                                                                    |
+| ----------- | ------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| Credentials | On open, after "Back", after an expired second step.                           | "Sign in", the two fields, the submit button; the registration footer when registration is open and the application projected a link.                                                                                                                         |
+| Challenge   | `login` answered an `mfaToken` without `mfaSetupRequired`.                     | "Two-step verification", with what this user can do here: their passkey (when they have one and both the browser and the server can run it), the 6-digit code of their app (when they have one), and always a backup code.                                    |
+| Enrolment   | `login` answered an `mfaToken` with `mfaSetupRequired` (no second factor yet). | "Two-factor authentication" and [`gbt-mfa-enrollment`](../mfa-enrollment/mfa-enrollment.ts) in a wider panel: the mandatory first set-up of an app or a passkey, then the backup codes. The session is only handed over once the user acknowledged the codes. |
+
+## Inputs
+
+| Input    | Type                   | Default | Role                                                                                                                        |
+| -------- | ---------------------- | ------- | --------------------------------------------------------------------------------------------------------------------------- |
+| `labels` | `Partial<LoginLabels>` | `{}`    | Strings to change, string by string, over `provideAuthLabels({ login })` and the English defaults (`DEFAULT_LOGIN_LABELS`). |
+
+The enrolment takes its strings from `provideAuthLabels({ mfaEnrollment, totpQr, backupCodes })`.
+
+## Outputs
+
+| Output     | Payload | Role                                                                                                                                                                                                                       |
+| ---------- | ------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `loggedIn` | `void`  | The user is signed in: the port stored the session (`login`, `verifyMfa`, `finishPasskeyChallenge`), or the page handed the held-back session of a finished enrolment to `AuthPort.setToken`. Navigate to the application. |
+
+## Slots
+
+| Selector              | Role                                                                                                                                                                                                                        |
+| --------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `[auth-logo]`         | The application's logo (an `img`, a `picture`, an `svg`) at the top of the panel, on every state. Give it its `alt`.                                                                                                        |
+| `[auth-backdrop]` | What is drawn on the graphite page, behind the panel: `gbt-git-field`, the family's animated commit graph (`@masmarino/gabarit/git-field`). Optional. |
+| `[gbtAuthFooterLink]` | The link to the application's registration page (`<a gbtButton variant="link" gbtAuthFooterLink routerLink="/register">`). Shown under the form, after "No account yet?", only when `authConfig` says registration is open. |
+| `[auth-notice]`       | Something the application has to say before the credentials (a session that ended, a sign-in link that failed), e.g. a `gbt-alert`. First in the form, on the credentials step only.                                        |
+
+## Providers
+
+| Token                               | Required               | Role                                                                                                                                       |
+| ----------------------------------- | ---------------------- | ------------------------------------------------------------------------------------------------------------------------------------------ |
+| `AUTH_PORT`                         | Yes                    | The backend: `authConfig`, `login`, `verifyMfa`, `startPasskeyChallenge`, `finishPasskeyChallenge`, `setToken`, and the enrolment's calls. |
+| `TOTP_QR_RENDERER`                  | For the enrolment's QR | The QR encoder of the authenticator-app set-up. Without one the enrolment shows the secret to type by hand.                                |
+| `AUTH_LABELS` (`provideAuthLabels`) | No                     | The application's wording, once for the whole kit.                                                                                         |
+
+## Behaviour
+
+- **Configuration.** `authConfig` is read once, when the page opens. A failed read only hides
+  the registration link, and is not taken for "no passkeys on this server": signing in never
+  depends on it.
+- **Password step.** Only a 401 says "Incorrect username or password"; a 429 says to wait; any
+  other failure (a 5xx, a network error, an answer with neither `token` nor `mfaToken`) says the
+  sign-in failed. The password is dropped from memory as soon as the server accepted it.
+- **Challenge.** One primary button per view: "Use a passkey" when it is offered, else "Verify".
+  A user with both factors gets the passkey first and the code form under "or". Spaces are
+  stripped from a code. A refused code empties the field; a 429 keeps it. A passkey-only user
+  whose passkey cannot run here (no WebAuthn in the browser, or passkeys off on the server) is
+  told why and given the backup-code form, never a dead end.
+- **Passkey.** `startPasskeyChallenge`, the browser's prompt, then `finishPasskeyChallenge`. A
+  dismissed prompt is a quiet "Operation cancelled" (not an error) and keeps the screen. While
+  the prompt is open "Use a backup code" and "Back" stay usable; leaving drops the ceremony, so a
+  late answer is never sent.
+- **Expiry.** A dead `mfaToken` (401 `invalid or expired token`, at the challenge, the passkey
+  or the enrolment) goes back to the credentials with "Your sign-in has expired, sign in again."
+  and the username kept.
+- **Enrolment.** The page embeds `gbt-mfa-enrollment`: `completed` hands the session to
+  `AuthPort.setToken` then emits `loggedIn`; `cancelled` ("Back") returns to the credentials;
+  `expired` returns with the expiry message. The passkey option is only offered when the
+  server said `passkeysAvailable: true` and the browser has WebAuthn.
+- **Focus.** On open the username field; after a failed sign-in the password field; on the
+  challenge the passkey button or the code field; after a failure the field (or button) to retry;
+  after "Back" the password field.
+
+Failures are classified by status and by the body's `error` string (see
+`AUTH_PORT_ERROR_BODIES`): the backend's own text is never shown.
+
+## Example
+
+```ts
+// app.config.ts
+providers: [
+  { provide: AUTH_PORT, useClass: HttpAuthPort }, // your adapter over HttpClient
+  {
+    provide: TOTP_QR_RENDERER,
+    useValue: (text, options) => import('qrcode').then((m) => m.toDataURL(text, options)),
+  },
+  provideAuthLabels({ login: { heading: 'Connexion', submit: 'Se connecter' /* … */ } }),
+]
+```
+
+```ts
+@Component({
+  imports: [AuthLogin, Button, AuthFooterLink, RouterLink],
+  template: `
+    <gbt-auth-login (loggedIn)="router.navigateByUrl('/home')">
+      <img auth-logo src="/logo.svg" alt="Acme" width="160" height="40" />
+      <a gbtButton variant="link" gbtAuthFooterLink routerLink="/register">Create an account</a>
+    </gbt-auth-login>
+  `,
+})
+export class LoginPage {
+  protected readonly router = inject(Router)
+}
+```
+
+## Accessibility
+
+See [AUDIT.md](AUDIT.md). The page title (`<title>`) is the application's: set it on the route.