@masmarino/gabarit 2.0.0 → 2.1.1

package/passkey-settings/README.md

@@ -0,0 +1,120 @@
+# PasskeySettings
+
+The account settings card of the signed-in user's **passkeys** (WebAuthn): the keys already
+registered (name, when each was added, when it was last used), adding a new one, and deleting one.
+It is the second factor next to the authenticator app of [`gbt-mfa-settings`](../mfa-settings/mfa-settings.ts):
+the two cards sit side by side on an account security page and coordinate through the root-provided
+`MfaSettingsState`.
+
+**Selector**: `gbt-passkey-settings`
+
+## States
+
+| State   | What shows                                                                                                                                                                                                                                                            |
+| ------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| loading | Two skeleton rows and a polite status (`labels.loading`), outside any `aria-busy` region.                                                                                                                                                                             |
+| failed  | An error alert (`role="alert"`) with a Retry button, which reads the status again.                                                                                                                                                                                    |
+| ready   | The list (`ul`, named by `labels.listLabel`, the count beside the card heading) or the empty state (`labels.emptyHeading`), a polite result line, then "Add a passkey" — or, in its place, the add form. Each row opens its own delete prompt.                        |
+| revoked | After a successful delete (the server revoked every session, this one included): an inert card, only "You have been signed out" (`labels.signedOut`), no list and no action left. `sessionRevoked` fires too: the card cannot clear the application's session itself. |
+
+## Inputs
+
+| Input    | Type                             | Default | Role                                                                                                                                                       |
+| -------- | -------------------------------- | ------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `labels` | `Partial<PasskeySettingsLabels>` | `{}`    | Strings to change, string by string, over `provideAuthLabels({ passkeySettings })` and the English defaults (`DEFAULT_PASSKEY_SETTINGS_LABELS`).           |
+| `locale` | `string \| null`                 | `null`  | The locale of the dates (relative times such as "2 hr. ago", dates such as `03/12/2025`, the exact date and time on hover). `null`: Angular's `LOCALE_ID`. |
+
+## Outputs
+
+| Output           | Payload | Role                                                                                                                                                                                                                                                                                  |
+| ---------------- | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `sessionRevoked` | `void`  | A passkey was deleted: the server revoked every session of the account, this one included. Sign out locally and go to the sign-in page (when the key was the last factor, the user goes through a new enrolment at the next sign-in). Bind it: the card only turns inert (`revoked`). |
+
+## Slots
+
+None.
+
+## Dependencies (injection)
+
+| Token              | Required | Role                                                                                                                                                                                                    |
+| ------------------ | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `MFA_PORT`         | yes      | `status`, `startPasskeyRegistration`, `finishPasskeyRegistration`, `deletePasskey` (see `MfaPort`).                                                                                                     |
+| `AUTH_PORT`        | no       | Only `authConfig()`, read alongside the status: `passkeysAvailable: false` blocks adding. Without an `AUTH_PORT`, or when the config cannot be read, the availability is unknown and adding is allowed. |
+| `MfaSettingsState` | root     | Shared with `gbt-mfa-settings`. Nothing to provide; provide it on the page (`providers: [MfaSettingsState]`) to scope it.                                                                               |
+| `AUTH_LABELS`      | no       | The application-wide strings (`provideAuthLabels`).                                                                                                                                                     |
+
+## Behaviour
+
+- **Adding** opens an inline form in place of the button: an optional name (the placeholder and the
+  default name are `labels.defaultPasskeyName`, trimmed, at most 40 characters counted as code
+  points, no control characters) and the **current password**. The server checks the password on
+  `startPasskeyRegistration` before any ceremony (a stolen session alone must not plant a key); the
+  browser's prompt then opens (`labels.promptOpen` is said politely meanwhile) and
+  `finishPasskeyRegistration` receives the credential and the name. The new key joins the list, the
+  result line announces it, and the focus moves to its row.
+- **Failures** of adding: a wrong password is an error under the password field (refocused); 429, 503
+  (passkeys unavailable), too many passkeys, a duplicate (409 or the browser's `InvalidStateError`)
+  and any other failure are an alert above the form, the focus back on the submit button. A dismissed
+  browser prompt is a quiet `info` note (`role="status"`), and the password is kept for a one-click
+  retry.
+- **Leaving the form** while a request or the browser's prompt is under way is allowed: a late answer
+  is dropped (no prompt opens, nothing is listed). A key whose finish still succeeded is counted in
+  `MfaSettingsState`.
+- **Deleting** opens a password prompt under that row (a warning alert first when it is the account's
+  last factor: one key and no authenticator app, as read or as changed by the sibling card), then a
+  confirmation dialog that says every device is signed out. Confirming calls `deletePasskey` once;
+  success emits `sessionRevoked`. A wrong password, a 429 or a server failure bring the user back to
+  the prompt with the message; a 404 (already gone) takes the key off the list and announces it,
+  nobody is signed out.
+- **Where adding is impossible** (a browser without WebAuthn, or `passkeysAvailable: false`), an
+  information note says why and the button is disabled; the keys stay listed and deletable.
+- **One prompt at a time**: opening the add form closes a delete prompt and the reverse; when the app
+  card takes the form (`MfaSettingsState.formOwner`), this card's open prompts close quietly; while the
+  app card is mid-enrolment (`appFlowActive`), "Add a passkey" is disabled with a hint. At most one
+  primary button is on screen.
+- **Secrets**: passwords live in signals until their request answers or the form closes, and are
+  cleared when the component is destroyed; the credential the browser returns is never stored.
+- **Dates**: an addition or a last use older than 30 days is shown as a date (`labels.added(true)`,
+  "Added on"), a recent one as a relative time (`labels.added(false)`, "Added"); the `<time>` element
+  carries the ISO date and the exact date and time as its `title`.
+
+## Example
+
+```ts
+// app.config.ts
+import { AUTH_PORT, MFA_PORT, provideAuthLabels } from '@masmarino/gabarit'
+
+export const appConfig: ApplicationConfig = {
+  providers: [
+    { provide: MFA_PORT, useClass: HttpMfaPort }, // your adapter over HttpClient
+    { provide: AUTH_PORT, useClass: HttpAuthPort }, // optional here: only authConfig() is read
+    provideAuthLabels({ passkeySettings: { heading: "Clés d'accès" /* … */ } }),
+  ],
+}
+```
+
+```ts
+// account-security.page.ts
+@Component({
+  imports: [MfaSettings, PasskeySettings],
+  template: `
+    <gbt-mfa-settings (sessionRevoked)="signOut()" />
+    <gbt-passkey-settings locale="fr" (sessionRevoked)="signOut()" />
+  `,
+})
+export class AccountSecurityPage {
+  private readonly session = inject(SessionService)
+  private readonly router = inject(Router)
+
+  signOut(): void {
+    this.session.clear()
+    this.router.navigateByUrl('/login')
+  }
+}
+```
+
+The card never navigates and never touches storage: signing out after a deletion is the page's job.
+
+## Accessibility
+
+See [AUDIT.md](AUDIT.md).

package/pie-chart/README.md

@@ -0,0 +1,85 @@
+# PieChart
+
+A pie or donut chart for showing how a total splits across categories
+— traffic sources, storage by type, budget allocation. One component
+covers both shapes: `innerRadiusRatio` at `0` draws a full pie, a
+value like `0.6` draws a donut.
+
+Distinct from `BarChart`/`LineChart`/`TimelineChart`: those are
+cartesian (an x/y axis, built on `ChartFrame`), while `PieChart` has
+no axis at all — it shares that trait with `FunnelChart`, and follows
+the same architecture (see "Why not `ChartFrame`" below).
+
+**Selector**: `gbt-pie-chart`
+
+## Inputs
+
+| Input               | Type                                                            | Role                                                                 |
+| -------------------- | ------------------------------------------------------------------ | --------------------------------------------------------------------- |
+| `slices`            | `{ label: string; value: number }[]`                              | Required. One entry per category.                                     |
+| `label`             | `string`                                                          | Required. Accessible name of the chart (`<svg role="group">`).          |
+| `locale`            | `string`                                                          | Required. Locale used to format numbers and percentages.                |
+| `emptyMessage`      | `string`                                                          | Required. Message shown when `slices` is empty.                         |
+| `tableCaption`      | `string`                                                          | Required. Caption of the `sr-only` data table.                          |
+| `categoryColumn`    | `string`                                                          | Required. Header of that table's category column.                       |
+| `valueColumn`       | `string`                                                          | Required. Header of that table's value column.                          |
+| `shareColumn`       | `string`                                                          | Required. Header of that table's share-of-total column.                 |
+| `sliceAnnouncement` | `(label: string, value: string, share: string) => string`         | Required. Formats the live-region message for the hovered/focused slice. |
+| `innerRadiusRatio`  | `number`                                                          | Optional, defaults to `0`. `0` = pie, e.g. `0.6` = donut.                |
+
+## Example
+
+```html
+<gbt-pie-chart
+  [slices]="trafficSources"
+  label="Répartition du trafic"
+  locale="fr-FR"
+  emptyMessage="Aucune donnée."
+  tableCaption="Répartition du trafic"
+  categoryColumn="Source"
+  valueColumn="Visites"
+  shareColumn="Part"
+  [sliceAnnouncement]="sliceAnnouncement"
+  [innerRadiusRatio]="0.6"
+/>
+```
+
+## Behavior
+
+- Each slice's angle is its share of the sum of all `slices` values.
+  An all-zero total renders every slice at 0% rather than dividing by
+  zero.
+- A slice's percentage is written directly next to it only once it
+  reaches 15% of the total — below that, the number on the slice would
+  overlap its neighbors. Every slice's exact share is always available
+  in the legend and in the `sr-only` table regardless of this
+  threshold.
+- Hovering or focusing a slice highlights it **and** its matching
+  legend entry at the same time, in both directions — hovering the
+  legend entry highlights the slice too. One shared `activeIndex`
+  drives both.
+- Up to 6 slices get a distinguishable color from `--chart-series-1`
+  through `--chart-series-6`; beyond that the palette cycles and a
+  console warning is logged in dev mode, the same convention
+  `LineChart` uses for its own `MAX_SERIES`.
+- The empty state (`ChartEmpty`) gets a small pie icon — a circle with
+  one filled wedge, not a chart-agnostic placeholder — via
+  `ChartEmpty`'s `[gbtChartEmptyIcon]` projection slot.
+
+## Why not `ChartFrame`
+
+The shared cartesian base (`ChartFrame`, `ChartContext`, `ChartAxis`,
+`ChartTooltip`) computes everything — scales, tick positions, the
+active point's pixel offset — from an x/y axis. A pie chart has
+neither: its geometry is angles around a center, not positions along
+axes. Forcing it through that base would mean fighting types built for
+a different geometry rather than reusing anything real, so `PieChart`
+instead follows the one existing precedent for a categorical,
+axis-less chart in this library, `FunnelChart`: no `ChartFrame`, a
+locally-owned `activeIndex` signal, and a hand-rolled `aria-live`
+announcement, reusing only the genuinely generic building blocks
+(`ChartEmpty`, `ChartTable`, and now `ChartLegend`).
+
+## Accessibility
+
+See `AUDIT.md` for the full RGAA checklist.

package/popover/README.md

@@ -0,0 +1,62 @@
+# Popover
+
+Generic floating panel that wraps any projected trigger and shows
+arbitrary projected content near it, opened/closed by a click — for
+rich content (a mini-form, a list of actions, a long text) that
+`Tooltip`'s hover-triggered short text doesn't fit.
+
+**Selector**: `gbt-popover` (`exportAs="gbtPopover"`)
+
+## Inputs
+
+| Input   | Type              | Default   | Role                                                    |
+| ------- | ----------------- | --------- | -------------------------------------------------------- |
+| `align` | `'start' \| 'end'` | `'start'` | Aligns the panel's left or right edge with the trigger's. |
+
+## Content
+
+| Slot                          | Role                                                             |
+| ------------------------------ | ----------------------------------------------------------------- |
+| Default (unmarked)             | The trigger — any element(s), shown as-is, click anywhere toggles the panel. |
+| `[popover-content]`            | The panel's body — fully free-form, no role or structure imposed. |
+
+## Example
+
+```html
+<gbt-popover #pop="gbtPopover">
+  <button type="button" [attr.aria-expanded]="pop.open()" [attr.aria-controls]="pop.panelId">
+    Options
+  </button>
+  <div popover-content>
+    <p>Any content: a form, a list, plain text…</p>
+    <button type="button" (click)="pop.close()">Close</button>
+  </div>
+</gbt-popover>
+```
+
+## Behavior
+
+- Opens on a click anywhere inside the trigger slot; closes on an
+  outside click or `Escape` — never on a click inside the panel's own
+  content, since that content can be a form or contain its own buttons.
+- `Escape` returns focus to the first focusable element found inside
+  the trigger slot.
+- No collision/flip handling if the panel would render off-screen —
+  the same trade-off `gbt-menu` already makes; choose an `align` that
+  fits the layout.
+
+## Accessibility
+
+`gbt-popover` wraps arbitrary projected content, so it cannot reach
+into it to set `aria-expanded`/`aria-controls` on your own trigger
+element — the same limitation `gbt-tooltip` has for `aria-describedby`.
+Wire them yourself using the instance exposed by `exportAs="gbtPopover"`:
+
+- `pop.open()` — a signal, `true` while the panel is shown.
+- `pop.panelId` — the panel's DOM id, for `aria-controls`.
+- `pop.toggle()` / `pop.close()` — for a close button inside your own
+  content (see the example above).
+
+The panel itself carries no ARIA role — it's your content, so it's
+your responsibility to give it one if it needs it (e.g. `role="dialog"`
+for a form, or leave it out entirely for a plain block of text).

package/radio-group/README.md

@@ -0,0 +1,47 @@
+# RadioGroup
+
+Groupe de boutons radio pour un choix exclusif parmi plusieurs options.
+S'intègre aux formulaires Angular via `ControlValueAccessor`, comme
+`Checkbox` et `Select`.
+
+**Selector**: `gbt-radio-group`
+
+## Inputs
+
+| Input          | Type                            | Default    | Role                                                    |
+| -------------- | -------------------------------- | ---------- | -------------------------------------------------------- |
+| `label`        | `string`                         | required   | Légende du groupe (`<legend>`).                          |
+| `options`      | `RadioOption<T>[]`               | required   | Options du groupe.                                       |
+| `orientation`  | `'vertical' \| 'horizontal'`     | `'vertical'` | Disposition des options.                                |
+| `disabled`     | `boolean`                        | `false`    | Désactive tout le groupe.                                |
+| `required`     | `boolean`                        | `false`    | Affiche un `*` à côté du label.                          |
+| `errorMessage` | `string \| null`                 | `null`     | Message d'erreur, associé via `aria-describedby`.        |
+
+```ts
+interface RadioOption<T = string> {
+  value: T
+  label: string
+  disabled?: boolean // désactive uniquement cette option
+}
+```
+
+## Exemple
+
+```html
+<gbt-radio-group label="Statut" [options]="statusOptions" formControlName="status" />
+```
+
+```ts
+statusOptions: RadioOption[] = [
+  { value: 'draft', label: 'Brouillon' },
+  { value: 'published', label: 'Publié' },
+  { value: 'archived', label: 'Archivé' },
+]
+```
+
+## Accessibilité
+
+Boutons radio natifs (`<input type="radio">`) partageant le même
+`name`, dans un `<fieldset>`/`<legend>` — le regroupement, l'état
+coché mutuellement exclusif et la navigation clavier (flèches) sont
+gérés nativement par le navigateur, sans JavaScript additionnel.

package/save-status/README.md

@@ -0,0 +1,44 @@
+# SaveStatus
+
+The save state of a field or form that saves on its own: "Saving…", "Saved", "Not saved".
+
+**Selector**: `gbt-save-status`
+
+## Inputs
+
+| Input         | Type                                       | Default       | Role                                                                                                    |
+| ------------- | ------------------------------------------ | ------------- | ------------------------------------------------------------------------------------------------------- |
+| `state`       | `'idle' \| 'saving' \| 'saved' \| 'error'` | `'idle'`      | The state to show. Set it from your save logic; nothing resets itself.                                  |
+| `savingLabel` | `string`                                   | `'Saving…'`   | Text of `saving`.                                                                                       |
+| `savedLabel`  | `string`                                   | `'Saved'`     | Text of `saved`.                                                                                        |
+| `errorLabel`  | `string`                                   | `'Not saved'` | Text of `error`.                                                                                        |
+| `message`     | `string \| null`                           | `null`        | Replaces the current state's text with a specific one; keeps its icon and colour. Ignored while `idle`. |
+
+## The live region
+
+The text lives in a `role="status"` element that is **always rendered**, also when `idle` (empty). A live
+region only announces changes if it was already in the accessibility tree, so never put the component
+behind an `@if` on the state: bind `[state]` instead. `idle` keeps the 20 px line, so nothing moves when a
+state appears. The host carries no role; the inner `.gbt-save-status` has `data-state`.
+
+Each state has an icon as well as text and colour: a spinning ring (a static ring under
+`prefers-reduced-motion`), a check, an alert.
+
+## Example
+
+```html
+<gbt-input label="Instance name" [(ngModel)]="name" (blur)="save()" />
+<gbt-save-status
+  [state]="nameState()"
+  savingLabel="Enregistrement…"
+  savedLabel="Enregistré"
+  errorLabel="Non enregistré"
+/>
+
+<!-- A form-level result with its own wording -->
+<gbt-save-status [state]="result().state" [message]="result().message" />
+```
+
+## Accessibility
+
+See [AUDIT.md](AUDIT.md).

package/search-bar/README.md

@@ -0,0 +1,84 @@
+# SearchBar
+
+Search field with grouped or flat results, keyboard navigation, and a
+blurred backdrop over the rest of the page while searching.
+
+**Selector**: `gbt-search-bar`
+
+Up/down arrows to move through results, Enter to select, Escape to
+close. The trigger and the results panel stay sharp above the backdrop;
+the rest of the page blurs behind it.
+
+## Inputs
+
+| Input                 | Type                                | Default                        | Role                                                                     |
+| --------------------- | ----------------------------------- | ------------------------------ | ------------------------------------------------------------------------ |
+| `id`                  | `string`                            | generated (`gbt-search-bar-N`) | Prefix of the generated DOM ids.                                         |
+| `results`             | `T[] \| null`                       | `null`                         | Flat results — an alternative to `groupedResults`.                       |
+| `groupedResults`      | `SearchResultCategory<T>[] \| null` | `null`                         | Results grouped by category — `{ label, icon?, items }`.                 |
+| `placeholder`         | `string`                            | `'Search…'`                    | Field placeholder text.                                                  |
+| `ariaLabel`           | `string`                            | `''`                           | Accessible name of the field, when the placeholder isn't enough.         |
+| `displayFn`           | `(item: T) => string`               | `String(item)`                 | Formats a result into displayed text.                                    |
+| `itemTemplate`        | `TemplateRef<unknown>`              | —                              | Custom template for rendering a result.                                  |
+| `keepQueryOnSelect`   | `boolean`                           | `false`                        | Keeps the chosen result's text in the field, instead of clearing it.     |
+| `noResultsMessage`    | `string`                            | `'No results'`                 | Message when there are no results.                                       |
+| `noResultsHint`       | `string`                            | `'Try a different search.'`    | Subtext under the "no results" message.                                  |
+| `clearLabel`          | `string`                            | `'Clear search'`               | Accessible name of the clear button.                                     |
+| `resultsAnnouncement` | `(count: number) => string`         | `` `${count} result(s)` ``     | Live ARIA announcement of the result count.                              |
+| `navigateHint`        | `string`                            | `'Navigate'`                   | Footer text, keyboard hint.                                              |
+| `selectHint`          | `string`                            | `'Select'`                     | Footer text, keyboard hint.                                              |
+| `closeHint`           | `string`                            | `'Close'`                      | Footer text, keyboard hint.                                              |
+| `collapsible`         | `boolean \| 'narrow'`               | `false`                        | Compact mode for a mobile header (see below).                            |
+| `expanded`            | `boolean` (model)                   | `false`                        | Whether the field is shown while `collapsible`. Two-way: `[(expanded)]`. |
+| `openLabel`           | `string`                            | `'Search'`                     | Accessible name of the compact icon button.                              |
+| `closeLabel`          | `string`                            | `'Close search'`               | Accessible name of the compact field's back-arrow close button.          |
+
+## Outputs
+
+| Output         | Type     | Role                                  |
+| -------------- | -------- | ------------------------------------- |
+| `queryChange`  | `string` | Emitted on every keystroke.           |
+| `itemSelected` | `T`      | Emitted when a result is selected.    |
+| `clear`        | `void`   | Emitted on click of the clear button. |
+
+## Compact mode (`collapsible`)
+
+For a mobile header where the field cannot stay inline: the field is replaced by an icon button (44 px) that
+expands it over the row and focuses it. Off by default: the field is always shown.
+
+- `collapsible` (or `[collapsible]="true"`): always compact.
+- `collapsible="narrow"`: compact only up to 768 px, the full field above (pure CSS: nothing to observe).
+- `[(expanded)]` lets the header hide its other items (title, account menu) while the search has the row.
+- Escape folds the field back (with results open, the first Escape closes them); so does leaving the field while it
+  is empty, and choosing a result (unless `keepQueryOnSelect`). Escape returns focus to the icon button.
+- The icon button is a native `<button aria-expanded="false" aria-controls>` named by `openLabel`; it is removed
+  from the tree while the field is shown.
+- While the field is shown, a back-arrow button named by `closeLabel` (default `'Close search'`) stands in for the
+  search glyph and folds it back, keeping the typed text: on a phone there is no Escape key, and leaving a field
+  that holds text does not fold it. It is not rendered above 768 px in `narrow` mode.
+
+```html
+<header class="app-header">
+  @if (!searchOpen()) {
+  <h1>Dashboard</h1>
+  }
+  <gbt-search-bar
+    collapsible="narrow"
+    [(expanded)]="searchOpen"
+    openLabel="Rechercher"
+    [groupedResults]="results()"
+  />
+</header>
+```
+
+## Example
+
+```html
+<gbt-search-bar
+  [groupedResults]="categories"
+  [displayFn]="(depot) => depot.nom"
+  ariaLabel="Rechercher un dépôt"
+  placeholder="Rechercher…"
+  (itemSelected)="ouvrir($event)"
+/>
+```

package/secret-reveal/README.md

@@ -0,0 +1,60 @@
+# SecretReveal
+
+A secret shown once or on demand: an API token, a runner registration token, a recovery code. Masked
+until the user shows it; copies whether it is shown or not.
+
+**Selector**: `gbt-secret-reveal`. Built on [`gbt-button`](../button/README.md) (show / hide) and
+[`gbt-copy-button`](../copy-button/README.md).
+
+## Inputs
+
+| Input         | Type                               | Default                                    | Role                                                                                        |
+| ------------- | ---------------------------------- | ------------------------------------------ | ------------------------------------------------------------------------------------------- |
+| `value`       | `string`                           | —                                          | Required. The secret.                                                                       |
+| `revealed`    | `boolean` (model)                  | `false`                                    | Whether the secret is shown; two-way `[(revealed)]`. Start it `true` for a one-time secret. |
+| `label`       | `string \| null`                   | `null`                                     | Visible label above the field; it also names the group.                                     |
+| `showLabel`   | `string`                           | `'Show the secret'`                        | Accessible name of the toggle while masked.                                                 |
+| `hideLabel`   | `string`                           | `'Hide the secret'`                        | Accessible name of the toggle while shown.                                                  |
+| `hiddenLabel` | `string`                           | `'Secret hidden'`                          | Read by screen readers in place of the bullets.                                             |
+| `copyLabel`   | `string`                           | `'Copy the secret'`                        | Accessible name of the copy button.                                                         |
+| `copiedText`  | `string`                           | `'Copied'`                                 | Confirmation after a copy.                                                                  |
+| `failedText`  | `string`                           | `'Copy failed, secret shown and selected'` | Message when the copy is refused.                                                           |
+| `feedbackMs`  | `number`                           | `2000`                                     | How long the confirmation stays.                                                            |
+| `feedback`    | `'bubble' \| 'inline' \| 'hidden'` | `'bubble'`                                 | Where the confirmation is drawn.                                                            |
+| `maskLength`  | `number`                           | `24`                                       | Bullets drawn while masked (fixed: the real length is not disclosed).                       |
+
+## Outputs
+
+| Output           | Payload   | Role                                                                |
+| ---------------- | --------- | ------------------------------------------------------------------- |
+| `copied`         | `string`  | The copied secret.                                                  |
+| `copyFailed`     | `void`    | Neither copy API worked: the secret has been revealed and selected. |
+| `revealedChange` | `boolean` | The user showed or hid the secret (the model's change event).       |
+
+## Behaviour
+
+- **Masked, the secret is not in the DOM** (only bullets, `aria-hidden`, and a visually hidden `hiddenLabel`):
+  it cannot be read by assistive technology, found by in-page search or taken from a DOM snapshot.
+- The copy button copies the real secret without showing it.
+- A refused copy (plain-HTTP page, permissions) reveals the secret and selects it for a manual Ctrl+C.
+- The toggle carries `aria-controls` (the value element) and swaps its accessible name; it is not also
+  `aria-pressed` (one signal, not two).
+
+## Example
+
+```html
+<gbt-secret-reveal
+  label="Runner token"
+  showLabel="Show the token"
+  hideLabel="Hide the token"
+  hiddenLabel="Token hidden"
+  copyLabel="Copy the token"
+  [value]="runner.token"
+  [revealed]="true"
+  (copied)="tokenCopied.set(true)"
+/>
+```
+
+## Accessibility
+
+See [AUDIT.md](AUDIT.md). Localise every string input.

package/segmented-control/README.md

@@ -0,0 +1,79 @@
+# SegmentedControl
+
+Compact, exclusive-choice button group — e.g. switching a view between
+"Day / Week / Month". Unlike `Tabs`, it carries no navigation
+semantics (`role="radiogroup"`, not `role="tablist"`): it's a value
+selector, not a way to move between different page contents.
+
+**Selector**: `gbt-segmented-control`
+
+## Inputs
+
+| Input       | Type                                                | Default  | Role                                                                                                                                                          |
+| ----------- | --------------------------------------------------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `options`   | `{ value: T; label: string; disabled?: boolean }[]` | required | The choices, in display order.                                                                                                                                |
+| `value`     | `T` (model)                                         | required | The selected option's value. Bind `[value]`/`[(value)]` to control or observe it from outside.                                                                |
+| `ariaLabel` | `string`                                            | `''`     | Accessible name of the group — there's no visible legend, so provide one (e.g. "Période").                                                                    |
+| `disabled`  | `boolean`                                           | `false`  | Disables every option at once.                                                                                                                                |
+| `label`     | `string`                                            | `''`     | Visible label above the control; it names the group (`aria-labelledby`) and takes over from `ariaLabel`.                                                      |
+| `fullWidth` | `boolean`                                           | `false`  | Fills the container; the options share the width equally.                                                                                                     |
+| `wrap`      | `boolean`                                           | `false`  | Lets the options flow onto several rows when they do not fit. A label never breaks in the middle.                                                             |
+| `size`      | `'md' \| 'sm'`                                      | `'md'`   | Both sizes are 32px tall, track included (`--gbt-control-height-sm`: level with a small button and the `sm` fields); `sm` has smaller text and tighter sides. |
+| `tinted`    | `boolean`                                           | `false`  | Draws the track with `--bg-track` (a step darker than `--bg-panel`) so it stays visible on a panel and on the page background.                                |
+
+## Example
+
+```html
+<gbt-segmented-control
+  [options]="[
+    { value: 'day', label: 'Jour' },
+    { value: 'week', label: 'Semaine' },
+    { value: 'month', label: 'Mois' },
+  ]"
+  [(value)]="period"
+  ariaLabel="Période"
+/>
+```
+
+## Layout options
+
+```html
+<!-- visible label + full width, tinted track -->
+<gbt-segmented-control label="Sort" fullWidth tinted [options]="sorts" [(value)]="sort" />
+
+<!-- state tabs with counts in a narrow column -->
+<gbt-segmented-control wrap size="sm" ariaLabel="Result type" [options]="types" [(value)]="type" />
+```
+
+- **Track token.** The default track is `--bg-panel`, which is the page background
+  in the app shell and vanishes on a panel. `tinted` uses the semantic token
+  `--bg-track` (`slate-200` in light, `graphite-700` in dark; `contrast.spec.ts` checks the
+  option text on it and that it stays distinguishable from the page and from
+  `--bg-panel`).
+- `label` gives the group one visible name, referenced by `aria-labelledby` — the
+  alternative is an `ariaLabel` with no visible text.
+- With `wrap`, arrow keys still follow the DOM order, row after row.
+
+## Behavior
+
+- Left/right arrow keys (also up/down) move selection _and_ focus
+  together, immediately — the same behavior as a native
+  `<input type="radio">` group, not `Tabs`' "arrows move focus only,
+  the option was already selected" (there is nothing to "activate"
+  separately). `Home`/`End` jump to the first/last enabled option.
+  Disabled options are skipped when navigating.
+- Roving tabindex: only the selected option is a tab stop.
+
+## Why not a `ControlValueAccessor`
+
+`RadioGroup` already covers a real form field. `SegmentedControl`'s
+primary use is switching a displayed view (a chart's period, a list's
+sort order) — a `model()`-based `value`, the same pattern `Tabs` uses
+for `activeIndex`, fits that without pulling in Angular Forms. Use
+`RadioGroup` instead if you need this exact choice as part of a form.
+
+## How many options
+
+Designed for a small, fixed set (2–5) shown at a glance. Beyond that,
+the segments get cramped and `Select` becomes the better fit — this
+isn't enforced by the component, it's a design judgment call.