@masmarino/gabarit 2.0.0 → 2.1.1

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)"
+/>
+}
+```

package/copy-button/README.md

@@ -0,0 +1,90 @@
+# CopyButton
+
+A button that copies a value to the clipboard and says so. It replaces the five hand-written
+"copy + Copied for 2 s + select the text on failure" implementations of an application (clone box,
+recovery codes, file view, one-time token, row menu).
+
+**Selector**: `gbt-copy-button`. Built on [`gbt-button`](../button/README.md); the clipboard logic
+(`copyToClipboard`, `ClipboardFeedback`) lives in `clipboard.ts` and is shared with
+[`gbt-copy-field`](../copy-field/README.md), [`gbt-secret-reveal`](../secret-reveal/README.md)
+and [`gbt-badge`](../badge/README.md)'s `copyable` input.
+
+## Inputs
+
+| Input          | Type                               | Default         | Role                                                                                                |
+| -------------- | ---------------------------------- | --------------- | --------------------------------------------------------------------------------------------------- |
+| `value`        | `string \| (() => string)`         | `''`            | The text to copy. A function is called when the button is pressed (a big file body, a fresh token). |
+| `text`         | `string`                           | `''`            | Visible label. Empty: an icon-only square.                                                          |
+| `ariaLabel`    | `string \| null`                   | `null`          | Accessible name. Defaults to `Copy` when icon-only and to `text` otherwise.                         |
+| `copiedText`   | `string`                           | `'Copied'`      | Message shown and announced after a successful copy.                                                |
+| `failedText`   | `string`                           | `'Copy failed'` | Message shown and announced when the copy is refused.                                               |
+| `feedbackMs`   | `number`                           | `2000`          | How long the "copied" message stays. A failure message stays twice as long.                         |
+| `variant`      | `ButtonVariant`                    | `'secondary'`   | Same values as `gbt-button`.                                                                        |
+| `size`         | `ButtonSize`                       | `'small'`       | `small \| medium \| large`.                                                                         |
+| `icon`         | `string`                           | `'copy'`        | Glyph of the idle button (registered icon name; `copy` is built in).                                |
+| `disabled`     | `boolean`                          | `false`         |                                                                                                     |
+| `feedback`     | `'bubble' \| 'inline' \| 'hidden'` | `'bubble'`      | Where the message is drawn (see below).                                                             |
+| `selectTarget` | `HTMLElement \| null`              | `null`          | Selected when the copy fails, so the user can copy by hand with Ctrl+C / Cmd+C.                     |
+
+## Outputs
+
+| Output       | Payload  | Role                                                                                                         |
+| ------------ | -------- | ------------------------------------------------------------------------------------------------------------ |
+| `copied`     | `string` | The text that was copied.                                                                                    |
+| `copyFailed` | `void`   | Neither the Clipboard API nor the fallback could copy (the text is shown selected if `selectTarget` is set). |
+
+## How it copies
+
+1. `navigator.clipboard.writeText` (secure contexts only: HTTPS or `localhost`).
+2. Otherwise, or when the write is refused, `document.execCommand('copy')` on a throw-away textarea
+   (the focus and the selection of the page are restored). This is what makes a **plain-HTTP
+   self-hosted instance** work.
+3. Otherwise `copyFailed` is emitted, the failure message shows and `selectTarget` is selected.
+
+No browser API is read until the button is pressed, so rendering (SSR, jsdom) never touches
+`navigator.clipboard`. A write that settles after the component is destroyed schedules nothing and
+emits nothing.
+
+## Stale messages
+
+A "Copied" message belongs to the text that was copied: when `value` changes to a different **string** the message is
+dropped (a function value is left alone, since a template may hand out a new closure on every change detection).
+`reset()` (a public method) drops it on demand; `gbt-secret-reveal` calls it when the secret is hidden.
+
+The legacy fallback puts its temporary textarea inside the trigger's `dialog` / `[role="dialog"]` when there is
+one: a native modal `<dialog>` makes the rest of the page inert, and a textarea outside it could not be focused.
+
+## Feedback
+
+The accessible name never changes. The outcome is told by:
+
+- a polite `role="status"` region that is **always in the DOM** (a live region only announces changes if
+  it was already rendered), holding `copiedText` or `failedText`;
+- the icon: `copy`, then `check` (or `alert-circle` on failure), so it is never colour alone;
+- visually, according to `feedback`: `bubble` is a small pill floating above the button, right-aligned
+  (clipped by an ancestor with `overflow: hidden`: use `inline` there); `inline` is the same message in
+  the flow after the button; `hidden` is for screen readers only.
+
+The host carries `data-status="idle | copied | failed"` for styling.
+
+## Example
+
+```html
+<code #url>{{ cloneUrl }}</code>
+<gbt-copy-button
+  [value]="cloneUrl"
+  ariaLabel="Copy the clone URL"
+  copiedText="Copied"
+  failedText="Copy failed, press Ctrl+C"
+  [selectTarget]="url"
+  (copied)="analytics.track('clone-url-copied')"
+/>
+
+<!-- A label, and a value produced only when needed -->
+<gbt-copy-button text="Copy the file" [value]="() => file().content" feedback="inline" />
+```
+
+## Accessibility
+
+See [AUDIT.md](AUDIT.md). The icon-only button needs (and gets) a name; localise `ariaLabel`,
+`copiedText` and `failedText` (the defaults are English).

package/copy-field/README.md

@@ -0,0 +1,54 @@
+# CopyField
+
+A read-only value in monospace with a copy button beside it: a clone URL, a webhook URL, an activation
+link, a token that is shown in full.
+
+**Selector**: `gbt-copy-field`. Built on [`gbt-copy-button`](../copy-button/README.md) (Clipboard API,
+`execCommand` fallback, live-region confirmation). For a secret that must stay masked until asked for,
+use [`gbt-secret-reveal`](../secret-reveal/README.md).
+
+## Inputs
+
+| Input        | Type                               | Default                         | Role                                                                                        |
+| ------------ | ---------------------------------- | ------------------------------- | ------------------------------------------------------------------------------------------- |
+| `value`      | `string`                           | —                               | Required. The value shown and copied.                                                       |
+| `label`      | `string \| null`                   | `null`                          | Visible label above the field. It also names the group (`role="group"`, `aria-labelledby`). |
+| `copyLabel`  | `string`                           | `'Copy'`                        | Accessible name of the copy button. Say what is copied ("Copy the clone URL").              |
+| `copiedText` | `string`                           | `'Copied'`                      | Message shown and announced after a successful copy.                                        |
+| `failedText` | `string`                           | `'Copy failed, value selected'` | Message when the copy is refused; the value is then selected for a manual Ctrl+C.           |
+| `feedbackMs` | `number`                           | `2000`                          | How long the confirmation stays (a failure stays twice as long).                            |
+| `feedback`   | `'bubble' \| 'inline' \| 'hidden'` | `'bubble'`                      | Where the confirmation is drawn (see `gbt-copy-button`).                                    |
+| `wrapAt`     | `RegExp \| null`                   | after each `/` (not in `//`)    | Where the value may wrap: it is cut after each match, with a `<wbr>`. `null`: no hint.      |
+
+## Outputs
+
+| Output       | Payload  | Role                                            |
+| ------------ | -------- | ----------------------------------------------- |
+| `copied`     | `string` | The copied value.                               |
+| `copyFailed` | `void`   | Neither copy API worked; the value is selected. |
+
+## Behaviour
+
+- The value **wraps** instead of scrolling: it stays readable in a 240 px aside or on a phone with no scroll
+  region to reach by keyboard. Break opportunities follow `wrapAt`; a segment too long for a line breaks
+  anywhere.
+- One click selects the whole value (`user-select: all`).
+- The value is cut **after** each match of `wrapAt` (a `<wbr>` is inserted); the text itself is never altered, so a
+  capturing group or a separator such as `/\//` cannot drop or duplicate characters.
+- `COPY_FIELD_WRAP_AT` (the default pattern) is exported by the component file if you want to extend it.
+
+## Example
+
+```html
+<gbt-copy-field
+  label="Clone with HTTPS"
+  copyLabel="Copy the clone URL"
+  failedText="Copy failed, press Ctrl+C"
+  [value]="repo.cloneUrl"
+  (copied)="toast.show('URL copied', 'success')"
+/>
+```
+
+## Accessibility
+
+See [AUDIT.md](AUDIT.md). Localise `label`, `copyLabel`, `copiedText` and `failedText`.

package/date-picker/README.md

@@ -0,0 +1,84 @@
+# DatePicker
+
+Single-date selection — a trigger button showing the chosen date, and
+a calendar grid dropdown, positioned like `Select`/`Menu`. Integrates
+with Angular forms via `ControlValueAccessor`, like `Select` and
+`Textarea`.
+
+**Selector**: `gbt-date-picker`
+
+## Inputs
+
+| Input                | Type                | Default              | Role                                                              |
+| --------------------- | -------------------- | ---------------------- | -------------------------------------------------------------------- |
+| `label`              | `string`            | `''`                  | Field label.                                                       |
+| `placeholder`        | `string`            | `'Select a date…'`    | Shown in the trigger when no date is selected.                     |
+| `locale`             | `string`            | `'en-US'`             | Passed to `Intl.DateTimeFormat` for the trigger's date, the month/year heading, and weekday names. |
+| `weekStartsOn`       | `0 \| 1`             | `1` (Monday)          | `0` for a Sunday-first week.                                        |
+| `disabled`           | `boolean`           | `false`                | —                                                                    |
+| `required`           | `boolean`           | `false`                | Appends `*` to the label.                                          |
+| `errorMessage`       | `string \| null`     | `null`                | Rendered as `role="alert"` below the field.                        |
+| `previousMonthLabel` | `string`            | `'Previous month'`    | Accessible name of the "go back a month" button.                   |
+| `nextMonthLabel`     | `string`            | `'Next month'`        | Accessible name of the "go forward a month" button.                |
+| `clearable`          | `boolean`           | `false`                | Shows a clear button in place of the calendar icon once a date is selected. |
+| `clearLabel`         | `string`            | `'Clear date'`         | Accessible name of the clear button.                                |
+| `visibleMonths`      | `1 \| 2`             | `1`                     | Shows one or two consecutive months side by side.                   |
+| `monthSelectLabel`   | `string`            | `'Month'`               | Accessible name of the month dropdown.                              |
+| `yearSelectLabel`    | `string`            | `'Year'`                | Accessible name of the year dropdown.                               |
+| `minYear`/`maxYear`  | `number`            | current year ∓ 100/+10  | Bounds the year dropdown's options.                                 |
+
+## Example
+
+```html
+<gbt-date-picker label="Appointment date" [formControl]="date" />
+```
+
+## Behavior
+
+- The trigger is a plain button showing the formatted date (or the
+  placeholder) — not an editable text field. Typing a date string
+  would need locale-aware parsing this component doesn't attempt; the
+  calendar is the only way to set a value.
+- Keyboard, inside the open grid: `ArrowLeft`/`Right`/`Up`/`Down` move
+  focus by a day/week, rolling into the next or previous month at the
+  edges; `Home`/`End` jump to the start/end of the focused week;
+  `PageUp`/`PageDown` shift the view a month; `Shift+PageUp`/`PageDown`
+  shift a year; `Enter`/`Space` select the focused day. This matches
+  the WAI-ARIA "Date Picker Dialog" pattern.
+- Clicking a leading/trailing day from an adjacent month (shown dimmed)
+  selects it and shifts the view to that month.
+- `Escape` and an outside click close the panel without changing the
+  value; `Escape` also returns focus to the trigger.
+- With `clearable`, a clear button replaces the calendar icon once a
+  date is selected — same position, so nothing shifts. It's a separate
+  button next to the trigger, not inside it (a `<button>` can't
+  contain another interactive element), overlapping the trigger's icon
+  slot visually. Hidden while `disabled`.
+- The previous/next buttons sit on their own full-width row above the
+  calendar(s), one at each outer edge — not tied to either month's own
+  heading. With `visibleMonths="2"`, they move both visible months
+  together (the second is always the first's next month — the two
+  aren't independently navigable). Arrowing past the last day of the
+  first visible month moves focus into the second (already visible)
+  month without shifting the view; only arrowing past the *last*
+  visible month, or before the first, slides the view by one month.
+- The first visible month's heading is two native `<select>` dropdowns
+  (month, year) for jumping directly anywhere, instead of plain text —
+  reused as-is rather than nesting the library's own `Select` (a
+  floating-panel component) inside this panel's own floating panel,
+  which would multiply the positioning/z-index/outside-click concerns
+  for no real benefit here. A second visible month (with
+  `visibleMonths="2"`) keeps a plain-text heading, sized to match the
+  selects' height exactly so both calendars stay aligned.
+
+## Scope
+
+Single date only. A range picker (start/end) is [`DateRangePicker`](date-range-picker/README.md),
+a separate component rather than a mode of this one. `min`/`max` date bounds (disabling
+out-of-range days) are also out of scope: nothing in the current use cases needs them, and they're a
+straightforward addition later if one does.
+
+No date library (day.js, date-fns) is used — calendar math (month
+grid, leap years) is hand-rolled in `date-picker-calendar.ts` on top of
+native `Date`/`Intl`, consistent with the rest of this library having
+no such dependency.