@masmarino/gabarit 1.4.0 → 2.1.0

package/auth-register/README.md

@@ -0,0 +1,104 @@
+# AuthRegister
+
+The free registration page of the auth kit, outside the app shell, in the sign-in panel
+([`gbt-auth-panel`](../auth/auth-panel/auth-panel.ts)). It asks the backend whether registration is open,
+shows the form (or "Registration is closed"), creates the account, then takes the new account through
+the mandatory first MFA enrolment ([`gbt-mfa-enrollment`](../mfa-enrollment/mfa-enrollment.ts)) right
+in the panel. It never talks HTTP, never touches storage and never navigates: the backend is the
+application's `AUTH_PORT`, and the page tells the application where to go through its outputs.
+
+**Selector**: `gbt-auth-register`
+
+## States
+
+| State     | What shows                                                                                                                                                                                                                                                         |
+| --------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| loading   | Until `AuthPort.authConfig()` answers: a skeleton of the form (`role="status"`, `aria-busy`, a visually hidden "Loading"), no heading, never a flash of the form.                                                                                                  |
+| open      | The form: username, email address, password, one primary "Create my account", then the projected sign-in link. Also shown when `authConfig()` fails: the server enforces the switch anyway.                                                                        |
+| closed    | `registrationEnabled` is false (or the server answered "registration is disabled" to a submit): a lock state with "Registration is closed", its explanation and one "Sign in" button.                                                                              |
+| enrolment | The server answered an `mfaToken`: the panel widens (`wide`), its heading becomes "Two-factor authentication" and `gbt-mfa-enrollment` replaces the form. A passkey is offered when `authConfig().passkeysAvailable` is true and the browser supports WebAuthn.    |
+| created   | The enrolment was left ("Back") or its token expired: the account exists, so the page says "Your account has been created", names it (lower-cased, as stored; "The setup has expired." first when it expired) and offers one "Sign in" button. No session is held. |
+
+## Inputs
+
+| Input               | Type                      | Default                                | Role                                                                                                                                           |
+| ------------------- | ------------------------- | -------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------- |
+| `labels`            | `Partial<RegisterLabels>` | `{}`                                   | Strings to change, over `provideAuthLabels({ register })` and the English defaults (`DEFAULT_REGISTER_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 error.                                    |
+| `usernamePattern`   | `RegExp`                  | `USERNAME_PATTERN` (a letter, 3 to 32) | The server's username rule, checked on the trimmed name before the round trip. Adjust the `usernameHint` and `usernameInvalid` labels with it. |
+
+The enrolment's own strings are `MfaEnrollmentLabels`: localise them with `provideAuthLabels({ mfaEnrollment })`.
+
+**A custom `usernamePattern` must not use the `g` or `y` regex flags (they make `.test()` stateful across
+calls, so the same name would pass and fail in turn) and must mirror the server's own rule.** The same goes
+for `minPasswordLength`: both only spare a round trip, the server stays the authority.
+
+## Outputs
+
+| Output       | Payload | Role                                                                                                                                                                                                            |
+| ------------ | ------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `registered` | `void`  | The account exists and has a session: either the backend issued one at once (the port stored it), or the enrolment finished and the held-back session was handed to `AuthPort.setToken`. Navigate into the app. |
+| `signIn`     | `void`  | "Sign in" was pressed in the closed or created state: 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 "Already have an account?". An `a gbtButton variant="link"` carrying `routerLink` or `href`. No footer when absent. |
+
+## Behaviour
+
+- **Checks before the request.** Nothing is said while the user types; after a first "Create my account"
+  every wrong field shows its rule (in place of its hint, as its only `aria-describedby`) and the focus moves
+  to the first wrong one. The checks then stay live. Nothing is sent while a field is wrong.
+- **Sent**: `register(username.trim(), email.trim(), password)`. A second submit while in flight is ignored;
+  the button shows its spinner and is disabled. The password is emptied as soon as the server answered.
+- **Failures** are worded from the labels, never from the backend's text, in an alert (`role="alert"`), and the
+  focus goes where the user retypes: a 400 naming a field focuses that field ("Check the fields"); a 400 naming
+  none focuses the alert; a reserved name, a taken name or address (409) focus the field concerned; a 429 says
+  to wait; anything else (5xx, network, a browser error) says the creation failed and keeps what was typed. A
+  400 "registration is disabled" switches to the closed state. The recognised bodies are in
+  `AUTH_PORT_ERROR_BODIES`.
+- **Focus**: the form starts in the username field; the closed and created states move the focus to their
+  `h1` (focusable by script, not a tab stop) so the change is announced.
+- **Sessions**: the page never stores one. A backend without MFA enforcement answers a `token` (the port stores
+  it): `registered` fires at once. Otherwise the enrolment keeps the session until the backup codes are
+  acknowledged, then the page hands it to `AuthPort.setToken` and emits `registered`.
+
+## 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({ register: { intro: 'Join Acme to host your repositories.' } }),
+]
+```
+
+```ts
+@Component({
+  imports: [AuthRegister, Button, AuthFooterLink, RouterLink],
+  template: `
+    <gbt-auth-register
+      (registered)="router.navigateByUrl('/home')"
+      (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-register>
+  `,
+})
+export class RegisterRoute {
+  protected readonly router = inject(Router)
+}
+```
+
+## Accessibility
+
+See [AUDIT.md](AUDIT.md). The panel owns the page's `<main>` landmark and its `h1`.

package/auth-reset-password/README.md

@@ -0,0 +1,120 @@
+# AuthResetPassword
+
+The password-reset page of the auth kit: where the link of a password-reset mail lands, outside the app
+shell, in the sign-in panel ([`gbt-auth-panel`](../auth/auth-panel/auth-panel.ts)). An administrator has
+reset the password of an existing account; the user follows the link and chooses a new password. No
+session comes out of it: they sign in afterwards, through their second factor as on any sign-in (a
+password reset leaves the account's factors untouched). 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-reset-password`
+
+It is the sibling of [`gbt-auth-activate`](../auth-activate/README.md): same one-time link mechanics, same
+form, same failure handling; only the call (`resetPassword` instead of `activate`), the output and the
+wording differ.
+
+## Views
+
+| View    | What shows                                                                                                                                                                                  |
+| ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| form    | A token was given: "Choose a new password", why (an administrator reset it), New password (with its hint), Confirm the new password, one primary "Set new password", then the projected sign-in link. |
+| success | The server accepted: "Your password has been changed", sign in with the new one, 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 an administrator for a new link, one "Sign in".            |
+
+## Inputs
+
+| Input               | Type                           | Default                   | Role                                                                                                                                                                                                        |
+| ------------------- | ------------------------------ | ------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `token`             | `string \| null`               | `null`                    | The reset link's token, as the application read it from its URL with `activationToken(fragment, null)`. `null` (or `''`) is the dead link, without any request. A new value starts the page over. |
+| `labels`            | `Partial<ResetPasswordLabels>` | `{}`                      | Strings to change, over `provideAuthLabels({ resetPassword })` and the English defaults (`DEFAULT_RESET_PASSWORD_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.                                                                                                |
+
+## Outputs
+
+| Output          | Payload | Role                                                                                 |
+| --------------- | ------- | ------------------------------------------------------------------------------------ |
+| `passwordReset` | `void`  | The server accepted the new 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.      |
+
+The success output is `passwordReset`, not `reset`: an output named after a native DOM event would
+also catch the `reset` events bubbling from the page's own `<form>`.
+
+## 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 "Already set your new password?". An `a gbtButton variant="link"` carrying `routerLink` or `href`. No footer when absent. |
+
+## Behaviour
+
+- **The token.** The page sends it with the new password (`resetPassword(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**
+  (`/reset-password#token=…`) so that no server, proxy or access log ever sees it; read it once with
+  `activationToken(route.snapshot.fragment, null)` (the helper is shared with the activation: a token not
+  shaped like the server's, 64 hexadecimal characters by default, is `null`; pass your own `shape` as its
+  third argument if your backend's differs); then remove it (and any other parameter) from the address bar
+  and the history entry, e.g. `router.navigateByUrl('/reset-password', { replaceUrl: true })` after the
+  first render, so it does not linger in a screenshot or a shared tab. Unlike the activation, there is no
+  older `?token=` link to support: read the fragment only.
+- **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.
+- **`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 new 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 new
+  password could not be set and the same token can be retried. Any other 400 is the dead link: the server
+  is expected to answer one generic 400 for an unknown, expired, used or malformed token, so that nobody
+  probing links can tell them apart; the page words them all the same way. The failures are read by
+  `classifyActivateFailure`, shared with the activation.
+- **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({ resetPassword: { signInPrompt: 'Password already changed?' } }),
+]
+```
+
+```ts
+@Component({
+  imports: [AuthResetPassword, Button, AuthFooterLink, RouterLink],
+  template: `
+    <gbt-auth-reset-password [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-reset-password>
+  `,
+})
+export class ResetPasswordRoute {
+  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, null)
+
+  constructor() {
+    const { fragment, queryParamMap } = this.route.snapshot
+    if (fragment !== null || queryParamMap.keys.length > 0) {
+      afterNextRender(() => void this.router.navigateByUrl('/reset-password', { replaceUrl: true }))
+    }
+  }
+}
+```
+
+## Accessibility
+
+See [AUDIT.md](AUDIT.md). The panel owns the page's `<main>` landmark and its `h1`.

package/autocomplete/README.md

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

package/avatar/README.md

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

package/avatar-group/README.md

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

package/badge/README.md

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

package/bar-chart/README.md

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