@masmarino/gabarit 1.4.0 → 2.1.0

package/breadcrumb/README.md

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

package/button/README.md

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

package/card/README.md

@@ -0,0 +1,179 @@
+# Card
+
+Titled container: an optional heading over a box. Two looks for the box —
+`elevated` (a shadow) and `outlined` (a quiet 1px edge) —, an optional
+description and counter under / after the heading, a flush body for rows, a
+tone and a selected state, and a link mode that makes the whole box
+clickable.
+
+**Selector**: `gbt-card` (+ the `CardHeader` directive and the `a[gbtCardLink]`
+component, see below)
+
+## Inputs
+
+| Input           | Type                                             | Default      | Role                                                                                                                                                                                  |
+| --------------- | ------------------------------------------------ | ------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `hoverable`     | `boolean`                                        | `false`      | Adds a visual hover treatment.                                                                                                                                                        |
+| `heading`       | `string`                                         | `''`         | Header title. Empty by default: no header is rendered without it (or a `[card-header]` slot).                                                                                         |
+| `icon`          | `string`                                         | `''`         | Icon shown beside the title, in the header. A toned header without one shows the tone's icon.                                                                                         |
+| `headingLevel`  | `1 \| 2 \| 3 \| 4 \| 5 \| 6`                     | `2`          | Level of the rendered heading — choose it based on the block's place in the page hierarchy (RGAA 9.1).                                                                                |
+| `variant`       | `'elevated' \| 'outlined'`                       | `'elevated'` | `outlined` swaps the box's shadow for a border.                                                                                                                                       |
+| `description`   | `string`                                         | `''`         | One-line help text under the heading (built-in header only).                                                                                                                          |
+| `count`         | `number \| null`                                 | `null`       | Counter pill after the heading, `0` included.                                                                                                                                          |
+| `flush`         | `boolean`                                        | `false`      | No padding inside the box: rows and tables reach its edges (clipped to its rounded corners).                                                                                          |
+| `tone`          | `'default' \| 'success' \| 'warning' \| 'error'` | `'default'`  | Colours the header's icon and title (`error` for a subsystem that is down, `success` for a result). Needs a header; the box is never tinted.                                          |
+| `selected`      | `boolean`                                        | `false`      | Accent ring (2px) and a faint wash on the box — the chosen option of a set of cards.                                                                                                   |
+| `selectedLabel` | `string`                                         | `'Selected'` | Visually hidden text read by screen readers on a `selected` card (colour and ring are not enough). Empty removes it.                                                                   |
+| `href`          | `string \| null`                                 | `null`       | Link mode: the heading becomes a link whose hit area covers the card's box (see below).                                                                                                |
+| `linkLabel`     | `string \| null`                                 | `null`       | `aria-label` of the link — the name of a link-mode card that has NO heading text. Ignored when there is a heading (the visible text stays the name: WCAG label in name).              |
+
+There is no `headerStyle` input: the header has a single look. A static
+`headerStyle="…"` attribute still compiles (it renders as an inert
+`headerstyle` DOM attribute); a bound `[headerStyle]="…"` fails to compile
+(NG8002).
+
+## Structure: a heading over a box
+
+The component renders two siblings:
+
+1. **The header** (`.gbt-card__header`, only when there is a `heading` or a
+   `[card-header]`): a plain heading **above** the card, like a section title
+   over a panel. It has no background, no border and no radius of its own —
+   the icon, the title (with its count), the description under it, and the
+   `[card-header-actions]` on the right. `0.5rem` separates it from the box
+   (the heading-to-content gap of `gbt-panel`).
+2. **The box** (`.gbt-card`): the card itself — shadow (`elevated`) or 1px
+   edge (`outlined`), background, padding, and a full radius on all four
+   corners. It holds the body only. `selected` and the link target are the
+   box's; the header is a label over it.
+
+```
+<gbt-card>                       display: grid, position: relative
+  div.gbt-card__header           heading, count, description, actions
+  div.gbt-card                   the box: data-variant, data-flush, data-selected, data-link
+    div.gbt-card__body           your content
+```
+
+`tone` is carried by the header (`data-tone` on `.gbt-card__header`), the
+other states by the box. To restyle the box (padding, a flex column…), target
+`.gbt-card`: it does not contain the heading.
+
+## Projected content
+
+- Default: the card's body. It sits in a `.gbt-card__body` wrapper that is `display: contents` (invisible to layout) unless the card is `flush`, so a `display: flex; gap` you put on the box (`.gbt-card`) still reaches your children directly.
+- `[card-header-actions]`: actions shown on the right of the header (button, menu…).
+- `[card-header]`: replaces the `heading` / `icon` / `description` / `count` block with your own header content, above the box. **Import the `CardHeader` directive next to `Card`** for the header layout (flex row, actions on the right). Without the import the marked element is still rendered — plain, at the top of the box, above the body — never dropped (same fallback as `gbt-menu`'s `MenuTrigger`).
+
+## Tone
+
+`tone` colours the header's icon and title in the tone's text colour
+(`--color-success-text`, `--color-warning-text`, `--color-error-text` — the
+pair `gbt-badge`'s outline look uses on the page). No wash, no tinted edge:
+the box, the description and the count stay neutral. A toned header always
+shows an icon — the one you give, or the tone's own (`check-circle`,
+`alert-triangle`, `alert-circle`, as `gbt-alert`) — so the tone is never
+conveyed by colour alone; the title text carries the meaning. A card without a
+header shows no tone.
+
+With a custom `[card-header]`, `tone` only sets `data-tone` on
+`.gbt-card__header` — it does not colour your projected content or add an
+icon (there is no built-in icon or title to colour). Style your own header
+content by tone if needed, and pair the colour with an icon or a word so the
+tone is not conveyed by colour alone:
+
+```css
+/* A global stylesheet, or behind `:host ::ng-deep` in a component's styles:
+   .gbt-card__header is gbt-card's own element, outside your encapsulation. */
+.gbt-card__header[data-tone='warning'] .my-title {
+  color: var(--color-warning-text);
+}
+```
+
+## Flush
+
+`flush` only removes the box's padding: rows, a table, a `gbt-list-row` or a
+`gbt-empty-state` reach the box's edges, and the body clips them to the box's
+inner corners. The header is not in the box, so it is not affected.
+
+## Examples
+
+```html
+<gbt-card heading="Registre Docker" [headingLevel]="2">
+  <gbt-gauge-bar ... />
+</gbt-card>
+
+<!-- A settings card: outlined, a heading above it, rows to the edges -->
+<gbt-card
+  variant="outlined"
+  heading="Variables"
+  icon="key"
+  description="Injectées dans chaque job."
+  [count]="variables().length"
+  [flush]="true"
+>
+  <gbt-button card-header-actions size="small" text="Ajouter" />
+  <ul>
+    …
+  </ul>
+</gbt-card>
+
+<!-- Your own header -->
+<gbt-card variant="outlined">
+  <div card-header><strong>src/app/app.ts</strong> <gbt-badge>+12 −3</gbt-badge></div>
+</gbt-card>
+```
+
+## Whole-card link
+
+Two ways, both use the **stretched link** pattern: the anchor stays the heading
+text only (that is its accessible name), and a pseudo-element of the anchor
+stretches its hit area over the card's **box**. There is **no interactive
+content nested inside the link**, so screen readers announce one clear link and
+axe's `nested-interactive` rule is satisfied.
+
+The heading sits above the box, so the anchor is not inside the box: the host
+is a positioned grid (`gbt-card-header` / `gbt-card-box` areas) and the
+anchor's overlay names the `gbt-card-box` area, which makes the box's area its
+containing block. The overlay therefore covers the box exactly — not the
+heading row, whose only target is the heading text itself — and the hover
+shadow and the focus ring are drawn on the box. Keep the host's
+`display: grid` (do not set `display: block` on `gbt-card`): when the grid
+does not apply, the overlay covers the header row too. The header's controls
+(`[card-header-actions]`, anything interactive in a `[card-header]`) still
+stay operable then, because they are lifted above the overlay the same way the
+body's controls are (see below).
+
+```html
+<!-- 1. href: the heading becomes the link -->
+<gbt-card
+  variant="outlined"
+  heading="Guide de démarrage"
+  href="/guide"
+  description="Installer le projet"
+/>
+
+<!-- 2. a projected anchor — router-agnostic, works with routerLink -->
+<gbt-card variant="outlined">
+  <h3 card-header><a gbtCardLink [routerLink]="['/releases', id]">Release {{ version }}</a></h3>
+  <gbt-button card-header-actions size="small" variant="secondary" text="Télécharger" />
+  <p>Notes de version…</p>
+  <a [routerLink]="['/releases', id, 'notes']">Notes</a>
+</gbt-card>
+```
+
+Import `CardLink` (and `CardHeader` for the second form). Rules of the pattern:
+
+- **One link per card.** The stretched anchor is the card's target; put the heading, not a paragraph, in it. No heading? Use `href` with `linkLabel`.
+- **Other controls stay separate.** Buttons, menus and links elsewhere in the card — in the box or in the header — are lifted above the stretched area (`z-index: 2`, and `position: relative` unless the control positions itself — a `gbt-switch`'s hidden input stays `absolute`) so they stay clickable and keep their own tab stop. The lifting rule has zero specificity: your own `position`/`z-index` on such a control wins. Do not wrap them in the link and do not put the link around the card (`<a>` around interactive content is a nested-interactive trap).
+- The focus ring is drawn around the box (inside its edge).
+- Trade-off of the pattern: text inside a linked card cannot be selected with the mouse.
+
+## Heading level
+
+`headingLevel` (default `2`) picks the `h1`…`h6`. Choose it from the card's
+place in the page, not its size.
+
+## Container queries
+
+The card is not a size container: a page that adapts its contents to the card's
+width should wrap the card in its own `container-type: inline-size` element.

package/checkbox/README.md

@@ -0,0 +1,50 @@
+# Checkbox
+
+Checkbox, integrated with reactive forms and `ngModel`.
+
+**Selector**: `gbt-checkbox`
+
+Implements `ControlValueAccessor` — driven via `formControlName` or
+`[(ngModel)]`. Without Angular forms, use the `checked` model
+(`[checked]` + `(checkedChange)`, or `[(checked)]`).
+
+## Inputs
+
+| Input      | Type              | Default                      | Role                                                                                                |
+| ---------- | ----------------- | ---------------------------- | --------------------------------------------------------------------------------------------------- |
+| `id`       | `string`          | generated (`gbt-checkbox-N`) | DOM id, associates the `<label>`.                                                                   |
+| `label`    | `string`          | `''`                         | Visible label.                                                                                      |
+| `disabled` | `boolean`         | `false`                      | Disables the checkbox (cumulative with the form's disabled state).                                  |
+| `hint`     | `string`          | `''`                         | Help text under the label, linked to the input with `aria-describedby`.                             |
+| `checked`  | `boolean` (model) | `false`                      | Checked state for use **without** Angular forms: `[checked]` sets it, `(checkedChange)` follows it. |
+
+## Outputs
+
+| Output          | Type      | Role                                             |
+| --------------- | --------- | ------------------------------------------------ |
+| `checkedChange` | `boolean` | Emitted when the user toggles the box (`model`). |
+
+## Example
+
+```html
+<gbt-checkbox label="Se souvenir de moi" formControlName="remember" />
+```
+
+## Without Angular forms (`checked` model)
+
+```html
+<gbt-checkbox label="Push" [checked]="selected().has('push')" (checkedChange)="toggle('push')" />
+```
+
+The native box reflects the bound value, and the user's toggle is reported
+through `checkedChange` — the pattern for a list of options whose state lives
+in a signal or a `Set`. For a whole group use [`gbt-checkbox-group`](../checkbox-group/README.md).
+`checked` and the form value are the same state: do not bind both.
+Set it with a binding, `[checked]="true"`: a bare `checked` attribute is not a boolean
+attribute here (the model is not transformed) and fails strict templates.
+
+## Hint
+
+Without `hint` nothing is added. With it, the host becomes a block and the text
+shows under the label, aligned with the label text; it is a `<p>` outside the
+`<label>`, so it describes the checkbox (`aria-describedby`) without joining its name.

package/checkbox-group/README.md

@@ -0,0 +1,78 @@
+# CheckboxGroup
+
+A set of checkboxes that answer one question ("Which events?") — a
+`<fieldset>` with a `<legend>`, whose value is the **array of the checked
+options' values**. Use [`Checkbox`](../checkbox/README.md) for a single
+yes/no, [`RadioGroup`](../radio-group/README.md) for a single choice.
+
+**Selector**: `gbt-checkbox-group`
+
+Implements `ControlValueAccessor` (`formControlName`, `[(ngModel)]`) **and** exposes a
+`value` model, so it also works without Angular forms (`[(value)]`).
+
+## Inputs
+
+| Input          | Type                        | Default                            | Role                                                                                                                                                                                                                                       |
+| -------------- | --------------------------- | ---------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| `legend`       | `string`                    | required                           | The group's question, rendered as the `<legend>` (its accessible name).                                                                                                                                                                    |
+| `options`      | `CheckboxGroupOption<T>[]`  | `[]`                               | Flat list of options.                                                                                                                                                                                                                      |
+| `groups`       | `CheckboxGroupSection<T>[]` | `[]`                               | Options split into named sections, rendered after `options`. Each section is a `role="group"` named by its heading.                                                                                                                        |
+| `value`        | `T[]` (model)               | `[]`                               | The checked options' values, in option order. Also the form value.                                                                                                                                                                         |
+| `columns`      | `number \| 'auto'`          | `1`                                | Equal columns, or `'auto'` to fit as many (min 11rem) as the width allows. On the flat list, or on the sections when there are `groups`. Only `'auto'` collapses on a narrow screen; a fixed count keeps its columns (short options only). |
+| `hint`         | `string`                    | `''`                               | Help text under the legend, linked with `aria-describedby`; replaced by the error while one shows.                                                                                                                                         |
+| `errorMessage` | `string \| null`            | `null`                             | Error text (`role="alert"`), `aria-describedby` and `aria-invalid` on the fieldset.                                                                                                                                                        |
+| `required`     | `boolean`                   | `false`                            | Adds ` *` to the legend (same convention as `RadioGroup`).                                                                                                                                                                                 |
+| `hideLegend`   | `boolean`                   | `false`                            | Keeps the legend for assistive technology, removes it from the layout.                                                                                                                                                                     |
+| `disabled`     | `boolean`                   | `false`                            | Disables every checkbox (cumulative with the form's disabled state).                                                                                                                                                                       |
+| `id`           | `string`                    | generated (`gbt-checkbox-group-N`) | Prefix of the ids of the checkboxes, hint and error.                                                                                                                                                                                       |
+
+```ts
+interface CheckboxGroupOption<T = string> {
+  value: T
+  label: string
+  hint?: string // help text under this option
+  disabled?: boolean // disables this option only
+}
+
+interface CheckboxGroupSection<T = string> {
+  label: string // visible heading, names the role="group"
+  options: CheckboxGroupOption<T>[]
+}
+```
+
+`T` is compared by identity (`includes`), so primitives and shared object
+references both work.
+
+## Examples
+
+```html
+<!-- With Angular forms -->
+<gbt-checkbox-group legend="Notify me about" [options]="options" formControlName="events" />
+
+<!-- Without: two-way model -->
+<gbt-checkbox-group legend="Notify me about" [options]="options" [(value)]="events" />
+
+<!-- Named sections, as many columns as fit -->
+<gbt-checkbox-group
+  legend="Events"
+  [groups]="eventGroups"
+  columns="auto"
+  formControlName="events"
+/>
+```
+
+## Behavior
+
+- Toggling a box emits the new array (`valueChange` / form `onChange`) **in
+  option order**, not click order, so the value is stable; values that match no
+  option are kept at the end. The control is marked touched on the first toggle.
+- Unchecking the last box emits `[]`, never `null`. `writeValue(null)` reads as `[]`.
+
+## Accessibility
+
+Native checkboxes (each is the existing `gbt-checkbox`) inside a
+`<fieldset>`/`<legend>`: the group name is announced with each box, every box
+is a tab stop and Space toggles it — no scripted keyboard handling, no roving
+tabindex (it is a set of independent controls, not a composite widget). Named
+sections add `role="group"` + `aria-labelledby` on the visible heading. See
+[`AUDIT.md`](AUDIT.md).

package/confirm-danger-modal/README.md

@@ -0,0 +1,77 @@
+# ConfirmDangerModal
+
+A confirmation dialog for a destructive, hard-to-reverse action. Two forms:
+
+- **Typed** (`confirmText` given): the confirm button stays disabled until the user types an exact
+  match of a given string (e.g. the name of the thing being deleted), the same "type-to-confirm"
+  pattern GitLab uses for project/group deletion.
+- **Light** (`confirmText` left out): no field, a normal confirm button, and a tinted icon beside
+  the message. For what is easy to redo (a webhook, a token, a collaborator).
+
+**Selector**: `gbt-confirm-danger-modal`
+
+Built on `Modal`: Escape, a backdrop click, or its own close button all
+already work exactly as `Modal` documents them (including `busy`); this component only adds
+the optional typed-confirmation gate and the Cancel/Confirm footer.
+
+## Inputs
+
+| Input               | Type                                 | Default             | Role                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          |
+| ------------------- | ------------------------------------ | ------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `isOpen`            | `boolean`                            | required            | Open/closed state, driven by the application.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |
+| `heading`           | `string`                             | required            | Dialog title.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |
+| `message`           | `string`                             | required            | Warning text shown above the confirmation input (typed) or beside the icon (light).                                                                                                                                                                                                                                                                                                                                                                                                                                                           |
+| `confirmText`       | `string \| null \| undefined`        | `undefined`         | The exact string the user must type before the confirm button enables — typically the name of the item being deleted. **Absent (or `null`): no typing gate, a light confirmation.** An empty string is still typed and fail-closed: it disables the confirm button permanently. An unresolved binding (`[confirmText]="repo()?.name"` while `repo()` is still `null`/`undefined`) also counts as absent and yields a light, one-click confirmation: for a destructive action, guard the `@if` that renders the modal until the name is known. |
+| `confirmInputLabel` | `string`                             | `'Type to confirm'` | Label of the confirmation text field (typed form).                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            |
+| `confirmLabel`      | `string`                             | `'Confirm'`         | Text of the confirm button.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   |
+| `cancelLabel`       | `string`                             | `'Cancel'`          | Text of the cancel button.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    |
+| `closeLabel`        | `string`                             | `'Close'`           | Accessible name of the modal's own close (X) button.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          |
+| `busy`              | `boolean`                            | `false`             | The request is running: the confirm button shows a spinner (and is disabled), Cancel is disabled, and Escape, the backdrop, the close button and a second click are ignored — nothing is emitted. The typing field is locked too.                                                                                                                                                                                                                                                                                                             |
+| `busyLabel`         | `string`                             | `'Working'`         | Read out on the confirm button and by the dialog while `busy`.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                |
+| `confirmIcon`       | `string \| null`                     | `null`              | Icon (a registered `gbt-icon` name) before the confirm label. None by default.                                                                                                                                                                                                                                                                                                                                                                                                                                                                |
+| `tone`              | `'danger' \| 'warning' \| 'neutral'` | `'danger'`          | `danger`: red confirm button and disc. `warning`: primary button, amber disc. `neutral`: primary button, blue disc (a plain confirmation). The disc only shows on the light form.                                                                                                                                                                                                                                                                                                                                                             |
+
+## Outputs
+
+| Output      | Type   | Role                                                                                                                                                                                         |
+| ----------- | ------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `confirmed` | `void` | Emitted only when the confirm button is clicked — for a typed confirmation, only once the typed text exactly matches `confirmText`; never while `busy`.                                      |
+| `closed`    | `void` | Emitted on Cancel, Escape, the close button, or a backdrop click (never while `busy`). The application must respond by setting `isOpen` to `false`. Never emitted together with `confirmed`. |
+
+Whatever the user typed is cleared automatically whenever the modal closes,
+so a later reopen never shows a stale value.
+
+## Example
+
+```html
+<gbt-confirm-danger-modal
+  [isOpen]="confirming()"
+  heading="Supprimer le dépôt"
+  message="Cette action supprimera définitivement le dépôt et tout son contenu."
+  [confirmText]="repo().name"
+  confirmInputLabel="Tapez le nom du dépôt pour confirmer"
+  confirmLabel="Supprimer"
+  cancelLabel="Annuler"
+  closeLabel="Fermer"
+  (confirmed)="deleteRepository()"
+  (closed)="confirming.set(false)"
+/>
+```
+
+A light confirmation whose request is running:
+
+```html
+@if (pending(); as webhook) {
+<gbt-confirm-danger-modal
+  [isOpen]="true"
+  heading="Delete the webhook"
+  [message]="'Deliveries to ' + webhook.url + ' will stop.'"
+  confirmLabel="Delete"
+  confirmIcon="trash-2"
+  [busy]="deleting()"
+  busyLabel="Deleting"
+  (confirmed)="delete(webhook)"
+  (closed)="pending.set(null)"
+/>
+}
+```