@masmarino/gabarit 2.0.0 → 2.1.1

package/file-upload/README.md

@@ -0,0 +1,47 @@
+# FileUpload
+
+Select one or more files by drag-and-drop or by clicking, with a
+visual selected-files list (each removable) and optional size
+validation. Integrates with Angular forms via `ControlValueAccessor`
+(`File[]`), like `Select`.
+
+**Selector**: `gbt-file-upload`
+
+## Inputs
+
+| Input             | Type                                          | Default                                              | Role                                                       |
+| ------------------ | ------------------------------------------------ | ------------------------------------------------------- | --------------------------------------------------------------- |
+| `label`           | `string`                                         | `''`                                                     | Field label.                                                     |
+| `multiple`        | `boolean`                                        | `false`                                                   | Accept more than one file. Selecting again replaces the current file when `false` — dropping or picking several files at once also keeps only the first and reports the rest as rejected (`extraFileMessage`), the same way an oversized file is reported. |
+| `accept`          | `string`                                         | `''`                                                       | Native `accept` attribute (e.g. `'image/*'`) — a hint to the OS picker and drag source, not enforced by this component. |
+| `maxSizeMb`       | `number \| null`                                  | `null`                                                     | Rejects (and reports) a file larger than this, in megabytes.    |
+| `disabled`        | `boolean`                                        | `false`                                                     | —                                                                 |
+| `errorMessage`    | `string \| null`                                  | `null`                                                       | Rendered as `role="alert"` below the file list.                  |
+| `dropLabel`       | `string`                                         | `'Drag and drop a file here, or click to browse'`             | The dropzone's own instructional text.                            |
+| `removeLabel`     | `(name: string) => string`                       | `` (name) => `Remove ${name}` ``                              | Accessible name of each file's remove button.                    |
+| `oversizeMessage` | `(name: string, maxSizeMb: number) => string`    | `` (name, max) => `${name} exceeds ${max} MB and was not added.` `` | Message shown per rejected file.                                  |
+| `extraFileMessage` | `(name: string) => string`                      | `` (name) => `${name} was not added — only one file is allowed.` `` | Message shown per extra file when more than one is dropped/picked while `multiple` is `false`. |
+
+## Example
+
+```html
+<gbt-file-upload label="Justificatif de domicile" [maxSizeMb]="5" [formControl]="proof" />
+```
+
+## Behavior
+
+- The whole dropzone is one `<button>` — clicking anywhere in it (not
+  just a nested "browse" link) opens the native file picker via a
+  hidden `<input type="file">`. A `<button>` can't contain another
+  interactive element, so there's no separate clickable "browse" word
+  inside it; the entire zone is the control.
+- The hidden native input is `tabindex="-1"` and `aria-hidden="true"`
+  — it's a pure trigger mechanism, triggered programmatically via
+  `.click()` from the visible button, never meant to be independently
+  focused or perceived.
+- Drag-and-drop has no direct keyboard equivalent, but every capability
+  it offers is also reachable via the same button (click → native
+  picker), so keyboard users lose nothing.
+- A rejected (oversized) file is never silently dropped — its name and
+  reason appear in a `role="alert"` list, replaced (not appended to)
+  on the next selection attempt.

package/funnel-chart/README.md

@@ -0,0 +1,39 @@
+# FunnelChart
+
+Step-by-step conversion funnel.
+
+**Selector**: `gbt-funnel-chart`
+
+Standalone, outside the dataviz base — has its own hover behavior, with
+the same keyboard/pointer parity, and its own visually-hidden
+`gbt-chart-table`.
+
+## Inputs
+
+| Input              | Type                                            | Role                                                                                                                                                            |
+| ------------------ | ----------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `steps`            | `FunnelStep[]`                                  | Required. `{ label, value }` — the steps, in order.                                                                                                             |
+| `label`            | `string`                                        | Required. Accessible name of the chart.                                                                                                                         |
+| `locale`           | `string`                                        | Required. Locale used to format numbers.                                                                                                                        |
+| `emptyMessage`     | `string`                                        | Required. Message shown when `steps` is empty.                                                                                                                  |
+| `tableCaption`     | `string`                                        | Required. Caption of the `sr-only` table.                                                                                                                       |
+| `stepColumn`       | `string`                                        | Required. Header of that table's step column.                                                                                                                   |
+| `valueColumn`      | `string`                                        | Required. Header of that table's value column.                                                                                                                  |
+| `conversionColumn` | `string`                                        | Required. Header of that table's conversion column.                                                                                                             |
+| `stepAnnouncement` | `(label: string, conversion: string) => string` | Required. Builds the wording of the announcement region (hover/focus on a step) from the label and the **already formatted** conversion from the previous step. |
+
+## Example
+
+```html
+<gbt-funnel-chart
+  [steps]="[{ label: 'Visite', value: 1000 }, { label: 'Inscription', value: 320 }]"
+  label="Tunnel d'inscription"
+  locale="fr-FR"
+  emptyMessage="Aucune donnée"
+  tableCaption="Détail du tunnel d'inscription"
+  stepColumn="Étape"
+  valueColumn="Valeur"
+  conversionColumn="Conversion"
+  [stepAnnouncement]="(label, conversion) => label + ', ' + conversion"
+/>
+```

package/gauge-bar/README.md

@@ -0,0 +1,35 @@
+# GaugeBar
+
+Progress gauge with alert thresholds — standalone, outside the dataviz
+base (no tooltip, no keyboard navigation).
+
+**Selector**: `gbt-gauge-bar`
+
+## Inputs
+
+| Input            | Type                                    | Default                         | Role                                                       |
+| ---------------- | --------------------------------------- | ------------------------------- | ---------------------------------------------------------- |
+| `value`          | `number`                                | required                        | Current value.                                             |
+| `max`            | `number`                                | required                        | Maximum value.                                             |
+| `label`          | `string`                                | required                        | Accessible name of the gauge (`role="progressbar"`).       |
+| `formattedValue` | `string`                                | required                        | Displayed value, **already formatted** — "62 GB / 100 GB". |
+| `warningLabel`   | `string`                                | required                        | Label announced at the warning threshold.                  |
+| `criticalLabel`  | `string`                                | required                        | Label announced at the critical threshold.                 |
+| `thresholds`     | `{ warning: number; critical: number }` | `{ warning: 70, critical: 90 }` | Thresholds as a percentage of `max`.                       |
+
+`GaugeBar` accepts no formatting function: `formattedValue`,
+`warningLabel`, and `criticalLabel` are strings already ready to
+display — Gabarit ships no translation mechanism.
+
+## Example
+
+```html
+<gbt-gauge-bar
+  [value]="257"
+  [max]="500"
+  label="Quota du registre Docker"
+  formattedValue="257 Gio / 500 Gio"
+  warningLabel="Avertissement"
+  criticalLabel="Critique"
+/>
+```

package/git-field/README.md

@@ -0,0 +1,34 @@
+# GitField
+
+The family's animated commit graph, drawn on the graphite frame: lanes that drift slowly
+sideways, commits that blink in turn, pushes running along some lanes, over two soft fields of
+colour (the rust accent and the indigo). It sits behind the sign-in panel or a dark band.
+
+**Selector**: `gbt-git-field` · **Import**: `@masmarino/gabarit/git-field`
+
+## Usage
+
+Behind the sign-in pages, in the `[auth-backdrop]` slot of `gbt-auth-panel` and of the pages built
+on it (`gbt-auth-login`, `gbt-auth-register`, `gbt-auth-activate`, `gbt-auth-reset-password`):
+
+```html
+<gbt-auth-login (loggedIn)="signedIn()">
+  <img auth-logo src="logo.svg" alt="Acme" />
+  <gbt-git-field auth-backdrop />
+</gbt-auth-login>
+```
+
+Anywhere else, it fills its nearest positioned ancestor (`position: absolute; inset: 0`), under
+the content (`z-index: 0`): give that ancestor `position: relative` and `isolation: isolate`, and
+lift the content above it.
+
+## Behaviour
+
+- Decoration only: `aria-hidden="true"` on the host, `focusable="false"` on the SVG, no pointer
+  events.
+- The drawing comes from a seeded generator, so it is the same on the server and in the browser.
+- Two identical tiles scroll by one width and start again, so the loop has no seam.
+- It reads the frame's colours (`frame-tokens`) in both themes, since it is drawn on the graphite.
+- The graph fades out towards the middle, where a centred panel sits, and stands further back
+  (half opacity) below 48rem, where the panel takes the whole width.
+- Still under `prefers-reduced-motion: reduce`: the graph stays drawn, nothing moves.

package/icon/README.md

@@ -0,0 +1,52 @@
+# Icon
+
+Renders an SVG icon registered in `IconRegistry` — always `aria-hidden`,
+never meaningful on its own.
+
+**Selector**: `gbt-icon`
+
+## Inputs
+
+| Input  | Type     | Role                                                                           |
+| ------ | -------- | ------------------------------------------------------------------------------ |
+| `name` | `string` | Name of the registered icon. Required. Nothing renders if the name is unknown. |
+
+## Built-in icons
+
+Gabarit ships the icons its own components use plus the generic UI glyphs
+most applications need (Lucide, inner markup only). Browse them in Storybook
+(`Atoms/Icon`, story `Gallery`).
+
+- Components' own: `search`, `x`, `eye`, `eye-off`, `chevron-down`,
+  `chevron-left`, `chevron-right`, `chevrons-left`, `chevrons-right`,
+  `ellipsis-vertical`, `check`, `copy`, `check-circle`, `alert-circle`,
+  `alert-triangle`, `info`, `arrow-up`, `arrow-down`, `calendar`, `upload`,
+  `folder`, `file`.
+- General-purpose UI glyphs: `home`, `folders`, `folder-open`, `server`, `lock`, `key`,
+  `settings`, `log-out`, `user`, `users`, `user-plus`, `bell`, `activity`,
+  `layout-dashboard`, `arrow-left`, `plus`, `list`, `kanban`, `layers`,
+  `download`, `refresh-cw`, `trash-2`, `pencil`, `send`, `mail`,
+  `message-circle`, `star`, `flag`, `tag`, `globe`, `book-open`, `bug`,
+  `sparkles`, `play`, `clock`, `database`, `hard-drive`, `smartphone`,
+  `shield-check`, `shield-alert`, `square-check`, `flask-conical`, and the
+  circled `circle-dot`, `circle-check`, `circle-x`, `circle-play`,
+  `circle-slash`.
+
+Domain glyphs (a `git-branch`, an issue ring…) stay with the application. An
+application overrides any of them, or adds its own, at startup:
+
+```typescript
+inject(IconRegistry).registerAll({
+  package: '<path d="…" />',
+  user: '<circle cx="12" cy="7" r="4" />',
+})
+```
+
+The expected markup is the **inner** content of an `<svg>` — without
+the `<svg>` tag itself.
+
+## Example
+
+```html
+<gbt-icon name="check" />
+```

package/icon-marker/README.md

@@ -0,0 +1,37 @@
+# IconMarker
+
+An icon on a soft tinted disc (or rounded tile): the marker of an activity on a timeline, the icon of a stat
+tile, a key, a decision.
+
+**Selector**: `gbt-icon-marker`. The icon is a registered [`gbt-icon`](../icon/README.md) name.
+
+## Inputs
+
+| Input        | Type                                                                    | Default     | Role                                                                                                                              |
+| ------------ | ----------------------------------------------------------------------- | ----------- | --------------------------------------------------------------------------------------------------------------------------------- |
+| `icon`       | `string`                                                                | —           | Required. A registered icon name.                                                                                                 |
+| `tone`       | `'neutral' \| 'primary' \| 'success' \| 'warning' \| 'error' \| 'info'` | `'neutral'` | The tint. `neutral` is quiet (the wash of the empty-state disc), `primary` is the brand colour.                                   |
+| `size`       | `'sm' \| 'md' \| 'lg' \| 'xl'`                                          | `'md'`      | 24, 32, 40 and 52 px. The glyph scales with it.                                                                                   |
+| `shape`      | `'disc' \| 'tile'`                                                      | `'disc'`    | Round, or a square with 8 px corners.                                                                                             |
+| `appearance` | `'soft' \| 'outline'`                                                   | `'soft'`    | `soft`: a tinted fill. `outline`: the page background, a hairline border and the tone's colour on the glyph (a marker on a rail). |
+| `label`      | `string \| null`                                                        | `null`      | Makes the marker an image (`role="img"`) with this name. Empty: decorative (`aria-hidden`).                                       |
+
+## Colours
+
+Status tones use the pair designed for a tinted background (`--color-<tone>-bg` + `--color-<tone>-bg-text`,
+the alert and badge pairs, 7:1 in both themes). `neutral` is 18 % of `--border-color` under `--text-secondary`;
+`primary` is 12 % of `--primary` under `--primary`. No new token: all pairs are asserted in
+`tokens/contrast.spec.ts`.
+
+## Accessibility
+
+The marker is decorative unless it has a `label`: the meaning (approved, blocked) must be told by the text
+next to it, never by the tint alone. See [AUDIT.md](AUDIT.md).
+
+## Example
+
+```html
+<li><gbt-icon-marker icon="check" size="sm" tone="success" /> bastien approved these changes</li>
+<gbt-icon-marker icon="key" shape="tile" tone="info" />
+<gbt-icon-marker icon="git-commit" size="sm" appearance="outline" label="Commit" />
+```

package/input/README.md

@@ -0,0 +1,120 @@
+# Input
+
+Text, email, password, number, search or URL field, with a visibility toggle, a
+hint, an error message, a compact size, a monospace mode and a leading icon.
+Integrated with reactive forms and `ngModel`.
+
+**Selector**: `gbt-input`
+
+**The exported class is called `GbtInput`, not `Input`** — `Input`
+would collide with `@angular/core`'s `Input` decorator.
+
+## Inputs
+
+| Input               | Type                                                                                          | Default                   | Role                                                                                                                                                                                 |
+| ------------------- | --------------------------------------------------------------------------------------------- | ------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| `id`                | `string`                                                                                      | generated (`gbt-input-N`) | DOM id, associates the `<label>`.                                                                                                                                                    |
+| `label`             | `string`                                                                                      | `''`                      | Visible label.                                                                                                                                                                       |
+| `type`              | `'text' \| 'password' \| 'email' \| 'number' \| 'search' \| 'url'`                            | `'text'`                  | In `password` mode, a button toggles visibility.                                                                                                                                     |
+| `required`          | `boolean`                                                                                     | `false`                   | Native `required` attribute.                                                                                                                                                         |
+| `disabled`          | `boolean`                                                                                     | `false`                   | Disables the field.                                                                                                                                                                  |
+| `placeholder`       | `string`                                                                                      | `''`                      | Placeholder text.                                                                                                                                                                    |
+| `errorMessage`      | `string \| null`                                                                              | `null`                    | Error message shown under the field, associated via `aria-describedby`.                                                                                                              |
+| `autocomplete`      | `string`                                                                                      | `'off'`                   | Native `autocomplete` attribute.                                                                                                                                                     |
+| `showPasswordLabel` | `string`                                                                                      | `'Show password'`         | Accessible name of the button when the password is hidden.                                                                                                                           |
+| `hidePasswordLabel` | `string`                                                                                      | `'Hide password'`         | Accessible name of the button when the password is visible.                                                                                                                          |
+| `hint`              | `string`                                                                                      | `''`                      | Help text under the field, linked with `aria-describedby`. Hidden (and unlinked) while an error shows.                                                                               |
+| `hideLabel`         | `boolean`                                                                                     | `false`                   | Hides the label visually; it stays in the DOM and keeps naming the field.                                                                                                            |
+| `size`              | `'md' \| 'sm'`                                                                                | `'md'`                    | The field is 38px tall (`md`) or 32px (`sm`): the shared `--gbt-control-height-md` / `-sm` scale, the height of `gbt-select` and `gbt-button` (`medium` / `small`) of the same tier. |
+| `mono`              | `boolean`                                                                                     | `false`                   | Monospace text (`--gbt-font-mono` when defined, else the system monospace stack).                                                                                                    |
+| `leadingIcon`       | `string \| null`                                                                              | `null`                    | Icon name shown inside the field, at its start (decorative, `aria-hidden`).                                                                                                          |
+| `inputmode`         | `'none' \| 'text' \| 'tel' \| 'url' \| 'email' \| 'numeric' \| 'decimal' \| 'search' \| null` | `null`                    | Native `inputmode` (virtual keyboard). Attribute left out when `null`.                                                                                                               |
+| `spellcheck`        | `boolean \| null`                                                                             | `null`                    | Native `spellcheck`. Left to the browser when `null`.                                                                                                                                |
+| `autocapitalize`    | `'off' \| 'none' \| 'on' \| 'sentences' \| 'words' \| 'characters' \| null`                   | `null`                    | Native `autocapitalize`. Left to the browser when `null`.                                                                                                                            |
+| `enterkeyhint`      | `'enter' \| 'done' \| 'go' \| 'next' \| 'previous' \| 'search' \| 'send' \| null`             | `null`                    | Native `enterkeyhint` (label of the virtual keyboard's enter key).                                                                                                                   |
+| `maxlength`         | `number \| null`                                                                              | `null`                    | Native `maxlength`.                                                                                                                                                                  |
+| `min` / `max`       | `number \| string \| null`                                                                    | `null`                    | Native `min` / `max` (number, date types…).                                                                                                                                          |
+| `combobox`          | `InputCombobox \| null`                                                                       | `null`                    | Makes the field the combobox of a list of suggestions: `role`, `aria-autocomplete="list"`, `aria-expanded`, `aria-controls`, `aria-activedescendant` (see below).                     |
+
+Every optional input defaults to "off": a field that leaves them unset renders
+the same markup and the same pixels.
+
+## Outputs
+
+| Output      | Payload  | Role                                               |
+| ----------- | -------- | -------------------------------------------------- |
+| `committed` | `string` | Fires on blur, with the value the user settled on. |
+
+`committed` is for anything that persists. A field bound straight to a
+request sends `2` and then `24` while the user types `24`, and walking away
+mid-edit saves the half-typed value; listening to `committed` instead sends
+one request, with what the user actually settled on. Local state — a signal
+backing another control — is better served by the form binding, which
+updates on every keystroke.
+
+## Hint, hidden label and compact search
+
+```html
+<gbt-input label="Repository name" hint="Letters, digits, - and _ only." formControlName="name" />
+
+<gbt-input
+  label="Search repositories"
+  [hideLabel]="true"
+  size="sm"
+  type="search"
+  leadingIcon="search"
+  placeholder="Search…"
+/>
+```
+
+The hint sits under the field (`<p id="<id>-hint">`) and is the field's
+`aria-describedby`. While `errorMessage` is set the hint is not rendered at
+all and the error takes its place, so a screen reader only reads one
+description.
+
+## Search with suggestions
+
+The field does not render the suggestions: the caller keeps the listbox, the active option and the keys, and
+hands the field what it must announce. Keys typed in the field reach the host, so `(keydown)` listens to them.
+
+```html
+<gbt-input
+  label="Search packages"
+  [hideLabel]="true"
+  type="search"
+  leadingIcon="search"
+  [combobox]="{ expanded: open(), controls: 'suggestions', activeDescendant: activeId() }"
+  [ngModel]="text()"
+  (ngModelChange)="suggest($event)"
+  (keydown)="onKeydown($event)"
+  (committed)="close()"
+/>
+<ul id="suggestions" role="listbox" [hidden]="!open()">…</ul>
+```
+
+## One-time code
+
+```html
+<gbt-input
+  label="6-digit code"
+  [mono]="true"
+  inputmode="numeric"
+  autocomplete="one-time-code"
+  [maxlength]="6"
+  [spellcheck]="false"
+  autocapitalize="off"
+  enterkeyhint="go"
+/>
+```
+
+## Example
+
+```html
+<gbt-input
+  label="Mot de passe"
+  type="password"
+  showPasswordLabel="Afficher le mot de passe"
+  hidePasswordLabel="Masquer le mot de passe"
+  formControlName="password"
+/>
+```

package/job-graph/README.md

@@ -0,0 +1,76 @@
+# JobGraph
+
+A read-only graph of pipeline jobs, laid out as one column per stage,
+with a curved link drawn from each job to every job it depends on
+(GitHub-Actions style). Each job is a native button: clicking one only
+emits its id — this component never navigates anywhere and never keeps
+a selection of its own.
+
+**Selector**: `gbt-job-graph`
+
+## Inputs
+
+| Input           | Type                             | Default           | Role                                                                                                          |
+| --------------- | -------------------------------- | ----------------- | ------------------------------------------------------------------------------------------------------------- |
+| `stages`        | `JobGraphStage[]`                | required          | The stages, in order, each with its jobs.                                                                     |
+| `selectedJobId` | `string \| null`                 | `null`            | The job being viewed; gets `aria-current="true"` and a highlight.                                             |
+| `statusLabels`  | `Record<JobGraphStatus, string>` | English labels    | Visually-hidden status text announced for each job (`Pending`, `Running`, `Succeeded`, `Failed`, `Canceled`). |
+| `needsLabel`    | `string`                         | `'Needs'`         | Visually-hidden prefix announced before a job's dependencies.                                                 |
+| `ariaLabel`     | `string`                         | `'Pipeline jobs'` | Accessible name of the list of stages.                                                                        |
+
+## Outputs
+
+| Output        | Payload  | Role                                              |
+| ------------- | -------- | ------------------------------------------------- |
+| `jobSelected` | `string` | Emits the `id` of the job whose node was clicked. |
+
+## Types
+
+```ts
+type JobGraphStatus = 'pending' | 'running' | 'success' | 'failed' | 'canceled'
+
+interface JobGraphJob {
+  id: string
+  name: string
+  status: JobGraphStatus
+  durationLabel?: string
+  needs: string[] // job NAMES (not ids)
+}
+
+interface JobGraphStage {
+  name: string
+  jobs: JobGraphJob[]
+}
+```
+
+`needs` holds the **names** of the jobs a job depends on, not their
+ids, so job names must be unique within a graph. A name that matches no
+job simply draws no link.
+
+## Example
+
+```html
+<gbt-job-graph
+  [stages]="[
+    { name: 'build', jobs: [{ id: 'a', name: 'compile', status: 'success', durationLabel: '3s', needs: [] }] },
+    { name: 'test', jobs: [{ id: 'b', name: 'unit', status: 'running', needs: ['compile'] }] },
+  ]"
+  [selectedJobId]="selected()"
+  (jobSelected)="selected.set($event)"
+/>
+```
+
+## Behavior
+
+- Each job renders a glyph whose **shape** depends on its status
+  (check for `success`, alert for `failed`, cross for `canceled`, a
+  ring for `pending`, a spinning ring for `running`), so status never
+  relies on colour alone; a visually-hidden text also states it. The glyph
+  is [`gbt-job-status`](../job-status/README.md), which you can use on its own
+  (a pipeline sidebar, a job header).
+- The links are measured from the rendered nodes and redrawn when
+  `stages` changes or the container is resized. They scroll with the
+  content when the graph overflows horizontally. A link is drawn as
+  "done" when the job it starts from succeeded.
+- The running spinner is replaced by a solid dot under
+  `prefers-reduced-motion: reduce`.

package/job-status/README.md

@@ -0,0 +1,34 @@
+# JobStatus
+
+The status glyph of a CI job: a check (`success`), an alert (`failed`), a cross (`canceled`), a spinning ring
+(`running`) or a still ring (`pending`). [`gbt-job-graph`](../job-graph/README.md) renders its
+nodes with this same component (same DOM position, same size, same colours), so a pipeline sidebar, a job
+header or a summary shows the glyph the graph shows.
+
+**Selector**: `gbt-job-status`
+
+## Inputs
+
+| Input    | Type             | Default | Role                                                                                                  |
+| -------- | ---------------- | ------- | ----------------------------------------------------------------------------------------------------- |
+| `status` | `JobStatusValue` | —       | Required. `'pending' \| 'running' \| 'success' \| 'failed' \| 'canceled'` (same as `JobGraphStatus`). |
+| `label`  | `string \| null` | `null`  | The status in words, read by screen readers and hidden visually. Empty: the glyph is decorative.      |
+
+## Colours and motion
+
+`success` `--color-success-text`, `failed` `--color-error-text`, `canceled` `--text-secondary`; the rings take
+`--border-color` (pending) and `--primary` (running, spinning). Under `prefers-reduced-motion: reduce` the running
+ring stops and becomes a filled dot. The host carries `data-status`.
+
+## Accessibility
+
+The glyph tells the status by its **shape**, never colour alone. Without `label` the host is `aria-hidden`:
+say the status in text next to it (as `gbt-job-graph` does in its node text). With `label` the host is exposed,
+the glyph stays hidden and the label is announced. See [AUDIT.md](AUDIT.md).
+
+## Example
+
+```html
+<gbt-job-status status="failed" label="Failed" />
+<li><gbt-job-status status="running" /> integration <span class="sr-only">Running</span></li>
+```

package/line-chart/README.md

@@ -0,0 +1,52 @@
+# LineChart
+
+Line(s) on the dataviz base — measures its container, reacts to the
+pointer and keyboard, carries its own visually-hidden
+`gbt-chart-table`.
+
+**Selector**: `gbt-line-chart`
+
+## Inputs
+
+| Input          | Type                                        | Default  | Role                                                        |
+| -------------- | ------------------------------------------- | -------- | ----------------------------------------------------------- |
+| `series`       | `ChartSeries<X>[]`                          | required | `{ label, points, pattern? }[]` — one or more series.       |
+| `xKind`        | `'linear' \| 'time'`                        | required | Nature of the x-axis.                                       |
+| `locale`       | `string`                                    | required | Locale used to format numbers and dates.                    |
+| `label`        | `string`                                    | required | Accessible name of the chart.                               |
+| `tableCaption` | `string`                                    | required | Caption of the `sr-only` table.                             |
+| `xColumn`      | `string`                                    | required | Header of that table's x-axis column.                       |
+| `emptyMessage` | `string`                                    | required | Message shown when the series are empty.                    |
+| `area`         | `boolean`                                   | `false`  | Fills the area under the line.                              |
+| `yZero`        | `boolean`                                   | `true`   | Forces the y-axis domain to contain zero.                   |
+| `yTickCount`   | `number`                                    | `5`      | Target number of ticks on the y-axis.                       |
+| `xTickCount`   | `number`                                    | `5`      | Target number of ticks on the x-axis.                       |
+| `size`         | `{ width: number; height: number } \| null` | `null`   | Explicit dimensions — reserved for server rendering, tests. |
+| `heading`      | `string`                                    | `''`     | Block title. Empty by default.                              |
+| `headingLevel` | `1 \| 2 \| 3 \| 4 \| 5 \| 6`                | `2`      | Level of the rendered heading.                              |
+| `headline`     | `string`                                    | `''`     | Current value, already formatted.                           |
+| `trend`        | `string`                                    | `''`     | Change over the period, already formatted.                  |
+
+`x` is a number on a linear axis, a `Date` on a time axis — `xKind`
+must match the actual type of `series`' `x` values.
+
+**Fluid width with a chosen height** — the common case — is achieved by
+setting the height in CSS on the wrapping container, without passing
+`[size]`. See [`../chart-frame/README.md`](../chart/chart-frame/README.md) for
+the full sizing contract and hover behavior.
+
+## Example
+
+```html
+<div style="height: 18rem">
+  <gbt-line-chart
+    [series]="[{ label: 'Requêtes', points: [{ x: 0, y: 12 }, { x: 1, y: 40 }] }]"
+    xKind="linear"
+    locale="fr-FR"
+    label="Requêtes"
+    tableCaption="Détail des requêtes"
+    xColumn="Jour"
+    emptyMessage="Aucune donnée"
+  />
+</div>
+```