@masmarino/gabarit 1.4.0 → 2.1.0

package/mfa-settings/README.md

@@ -0,0 +1,154 @@
+# MfaSettings
+
+The account settings card of the signed-in user's **authenticator app** (TOTP) and **backup codes**.
+It sits next to [`gbt-passkey-settings`](../passkey-settings/passkey-settings.ts): a second factor is
+an app OR a passkey, so this card reads both (the app is only "Optional" once a passkey exists). It
+talks to the application's backend through the `MFA_PORT` it injects, and signals the one thing the
+application must act on, a revoked session, through an output.
+
+**Selector**: `gbt-mfa-settings`
+
+## States
+
+| State        | What shows                                                                                                                                                                                                                                                                                                                                         |
+| ------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| loading      | Skeleton rows (`aria-busy`) and, beside them (never inside the busy block, which would keep it quiet), a visually hidden `role="status"` ("Loading two-factor authentication…"), while `status()` runs.                                                                                                                                            |
+| failed       | An error alert (`role="alert"`) with a **Retry** button that reads the status again.                                                                                                                                                                                                                                                               |
+| app on       | "App configured" with an **On** badge; the backup codes left (warning-toned, with an icon and a sentence, from `lowCodesThreshold` down) and **Regenerate backup codes**; **Reset** (the app is the only factor) or **Remove** (a passkey remains). Each action opens an inline current-password prompt.                                           |
+| passkey only | "No app configured" with an **Optional** badge and **Add an app**; the backup codes row as above; no reset.                                                                                                                                                                                                                                        |
+| no factor    | Defensive (a live session without a factor should not exist: removing the last one signs the user out): a static warning that MFA is required and a primary **Set up now**.                                                                                                                                                                        |
+| enrolling    | After the password: the QR ([`gbt-totp-qr`](../mfa-enrollment/totp-qr/totp-qr.ts)), the secret as text, a 6-digit code field, **Activate** and **Cancel**.                                                                                                                                                                                                        |
+| codes        | After an enrolment or a regeneration: the ten backup codes, shown **once** ([`gbt-backup-codes`](../mfa-enrollment/backup-codes/backup-codes.ts): copy, download, acknowledgement), a static "Do not leave this page" warning until acknowledged, and **Done** (disabled until acknowledged; it returns to the ready state with the new count, without a reload). |
+| revoked      | After a successful reset/removal (the server revoked this session): an inert card, only "You have been signed out" (`signedOut`), no action left. `sessionRevoked` fires too: the card cannot clear the application's session itself.                                                                                                              |
+
+## Inputs
+
+| Input               | Type                         | Default | Role                                                                                                                                         |
+| ------------------- | ---------------------------- | ------- | -------------------------------------------------------------------------------------------------------------------------------------------- |
+| `labels`            | `Partial<MfaSettingsLabels>` | `{}`    | The strings to change, string by string, over `provideAuthLabels({ mfaSettings })` and the English defaults (`DEFAULT_MFA_SETTINGS_LABELS`). |
+| `lowCodesThreshold` | `number`                     | `3`     | From this many backup codes left (inclusive), the count turns to a warning asking the user to regenerate them.                               |
+
+## Outputs
+
+| Output           | Payload | Role                                                                                                                                                                                                                                                              |
+| ---------------- | ------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `sessionRevoked` | `void`  | The app was reset/removed (`MfaPort.disable` succeeded) and the server revoked this very session with it. Sign out locally and go to the sign-in page (a new enrolment is forced there unless a passkey remains). Bind it: the card only turns inert (`revoked`). |
+
+## Slots
+
+None.
+
+## Dependencies (DI)
+
+| Token              | Required | Role                                                                                                                                                                                                              |
+| ------------------ | -------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `MFA_PORT`         | yes      | The application's `MfaPort`: `status`, `enroll`, `confirm`, `regenerate`, `disable` are used here. A wrong current password must be a **400** `{ "error": "current password is incorrect" }` (see `mfa.port.ts`). |
+| `TOTP_QR_RENDERER` | no       | Draws the QR. Without one, `gbt-totp-qr` shows its fallback text and the secret to type by hand.                                                                                                                  |
+| `AUTH_LABELS`      | no       | The kit's strings for the whole application (`provideAuthLabels`). The nested backup codes and QR take theirs from here (`backupCodes`, `totpQr`), not from this card's `labels`.                                 |
+| `MfaSettingsState` | (root)   | What this card and `gbt-passkey-settings` share: the factors as last read or changed, which card owns the open form, whether the app is mid-flow. Root-provided; provide it on the page to scope it.              |
+
+## Behaviour
+
+- **One password prompt at a time**, in place of the button that opened it: opening another drops the
+  first one's password. Opening one claims the form in `MfaSettingsState`; when the passkeys card
+  claims it, this card closes its prompt (and its dialog) quietly. The enrolment and the codes step
+  are never interrupted (the passkeys card holds back instead, through `appFlowActive`).
+- **At most one primary button** per state. The reset/remove prompt submits with a quiet
+  **Continue**; the one destructive action is in the confirmation dialog
+  (`gbt-confirm-danger-modal`), which sends the request. A second confirm while it runs is ignored.
+- **Failures**: an empty field or a wrong password/code is said under the field
+  (`Enter your password`, `Incorrect password`, `Enter the 6-digit code from your app`,
+  `Incorrect code`, the refused code being emptied); a 429 or any other failure is an alert above
+  the form, which stays. The backend's own text is never shown.
+- **Secrets**: the password lives only until its request answers (or the prompt closes); the secret,
+  the otpauth URL, the code and the backup codes are dropped as soon as they did their job, and
+  everything is emptied when the component is destroyed. Spaces in the typed code are removed.
+- **Codes shown once**: while they are on screen and not acknowledged, closing or reloading the tab
+  asks the browser to confirm (`beforeunload` on the host document's window); the listener is
+  removed once they are acknowledged or the card is destroyed.
+- **Focus** follows the state: the password or code field when it opens or after a refusal, the
+  instruction line (`tabindex="-1"`) of the scan and codes steps and of the ready state after
+  **Done**, the opener after **Cancel**.
+- After a confirmed enrolment the card tells `MfaSettingsState` (`totpConfirmed`), so the passkeys card
+  knows deleting a key no longer removes the last factor; a passkey added by the passkeys card makes
+  the mandatory warning give way to "No app configured" at once.
+
+## Example
+
+```ts
+// app.config.ts
+import { HttpClient, provideHttpClient } from '@angular/common/http'
+import { type ApplicationConfig, Injectable, inject } from '@angular/core'
+import {
+  type BackupCodesResult,
+  MFA_PORT,
+  type MfaPort,
+  type MfaStatus,
+  TOTP_QR_RENDERER,
+  type TotpEnrollment,
+  type TotpQrRenderOptions,
+  provideAuthLabels,
+} from '@masmarino/gabarit'
+
+@Injectable({ providedIn: 'root' })
+export class HttpMfaPort implements MfaPort {
+  private http = inject(HttpClient)
+  status = () => this.http.get<MfaStatus>('/api/me/mfa')
+  enroll = (currentPassword: string) =>
+    this.http.post<TotpEnrollment>('/api/me/mfa/totp/enroll', { currentPassword })
+  confirm = (code: string) =>
+    this.http.post<BackupCodesResult>('/api/me/mfa/totp/confirm', { code })
+  regenerate = (currentPassword: string) =>
+    this.http.post<BackupCodesResult>('/api/me/mfa/backup-codes/regenerate', { currentPassword })
+  disable = (currentPassword: string) =>
+    this.http.post<void>('/api/me/mfa/totp/disable', { currentPassword })
+  // … and the passkey calls used by gbt-passkey-settings.
+}
+
+export const appConfig: ApplicationConfig = {
+  providers: [
+    provideHttpClient(),
+    { provide: MFA_PORT, useExisting: HttpMfaPort },
+    {
+      provide: TOTP_QR_RENDERER,
+      useValue: (text: string, options: TotpQrRenderOptions) =>
+        import('qrcode').then((qr) => qr.toDataURL(text, options)),
+    },
+    // Optional: localise the whole kit once.
+    provideAuthLabels({
+      mfaSettings: { heading: "Application d'authentification", enabled: 'Activée' /* … */ },
+      backupCodes: { copy: 'Copier les codes' /* … */ },
+    }),
+  ],
+}
+```
+
+```ts
+// security-page.ts
+import { Component, inject } from '@angular/core'
+import { Router } from '@angular/router'
+import { MfaSettings, PasskeySettings } from '@masmarino/gabarit'
+import { AuthService } from './auth.service' // the application's own session holder
+
+@Component({
+  imports: [MfaSettings, PasskeySettings],
+  template: `
+    <gbt-mfa-settings [lowCodesThreshold]="3" (sessionRevoked)="signedOut()" />
+    <gbt-passkey-settings (sessionRevoked)="signedOut()" />
+  `,
+})
+export class SecurityPage {
+  private auth = inject(AuthService)
+  private router = inject(Router)
+
+  /** The server revoked the session with the factor: forget it locally and sign in again. */
+  signedOut() {
+    this.auth.logout()
+    this.router.navigateByUrl('/login')
+  }
+}
+```
+
+## Accessibility
+
+See [AUDIT.md](AUDIT.md).

package/modal/README.md

@@ -0,0 +1,72 @@
+# Modal
+
+Modal dialog box — traps focus, closes on Escape or a click on the
+backdrop, and stays shut while a request is running (`busy`).
+
+**Selector**: `gbt-modal`
+
+## Inputs
+
+| Input          | Type                         | Default         | Role                                                                                                                                                                                                                                                                                                                                          |
+| -------------- | ---------------------------- | --------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `isOpen`       | `boolean`                    | required        | Open/closed state, driven by the application.                                                                                                                                                                                                                                                                                                 |
+| `heading`      | `string`                     | `''`            | Dialog title.                                                                                                                                                                                                                                                                                                                                 |
+| `headingLevel` | `1 \| 2 \| 3 \| 4 \| 5 \| 6` | `2`             | Level of the rendered heading.                                                                                                                                                                                                                                                                                                                |
+| `closeLabel`   | `string`                     | `'Close'`       | Accessible name of the close button.                                                                                                                                                                                                                                                                                                          |
+| `busy`         | `boolean`                    | `false`         | A request is in flight: Escape, a click on the backdrop and the close button are ignored (no `closed`). The body reports `aria-busy="true"` (the status region below is deliberately outside it: a busy ancestor can suppress live announcements), the close button `aria-disabled="true"` (it stays focusable), and `busyLabel` is read out. |
+| `busyLabel`    | `string`                     | `'Please wait'` | Text read out by a visually hidden `role="status"` region while `busy`.                                                                                                                                                                                                                                                                       |
+| `returnFocus`  | `boolean`                    | `true`          | Gives focus back to the element that had it when the dialog opened, once it closes. Turn it off when the opener is gone or you move focus yourself.                                                                                                                                                                                           |
+
+## Slots
+
+| Slot             | Role                                                                                                                                                                                                                                                                                                                                      |
+| ---------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| default          | The body.                                                                                                                                                                                                                                                                                                                                 |
+| `[modal-footer]` | Actions under a hairline, kept in view while a long body scrolls. Nothing to import: add the attribute `modal-footer` to the element. A `div`, `footer` or `section` carrying it is the actions row itself (right aligned, wrapping, spaced); any other element (a button, a link) is one item of that row. Nothing projected, no footer. |
+
+## Outputs
+
+| Output   | Type   | Role                                                                                                                                     |
+| -------- | ------ | ---------------------------------------------------------------------------------------------------------------------------------------- |
+| `closed` | `void` | Emitted on Escape, a click outside the box, or a click on the close button. The application must respond by setting `isOpen` to `false`. |
+
+## Busy
+
+While `busy` is `true`, pass it on from the request's state and disable your own cancel button; the
+dialog keeps focus (it comes back to the dialog if the button you pressed was disabled) and closes
+again as soon as `busy` is `false`. Setting `isOpen` to `false` yourself still closes it.
+
+## Touch
+
+On a coarse pointer (`pointer: coarse`) the close button is 44 × 44 px; the header keeps its height.
+
+## Example
+
+```html
+<gbt-modal [isOpen]="ouvert()" heading="Confirmer" closeLabel="Fermer" (closed)="ouvert.set(false)">
+  Contenu de la boîte de dialogue.
+</gbt-modal>
+```
+
+With a footer and a running request:
+
+```html
+<gbt-modal
+  [isOpen]="open()"
+  [busy]="saving()"
+  busyLabel="Saving"
+  heading="Rename"
+  (closed)="open.set(false)"
+>
+  <gbt-input label="Name" [(ngModel)]="name" />
+  <div modal-footer>
+    <gbt-button
+      variant="secondary"
+      text="Cancel"
+      [disabled]="saving()"
+      (clicked)="open.set(false)"
+    />
+    <gbt-button text="Save" [loading]="saving()" (clicked)="save()" />
+  </div>
+</gbt-modal>
+```

package/nav-tabs/README.md

@@ -0,0 +1,106 @@
+# NavTabs (`gbt-nav-tabs` and `a[gbtNavTab]`)
+
+A navigation between the sections of a page (repository settings, account settings…) as **real links**: the
+application projects `a[gbtNavTab]` items into `gbt-nav-tabs`. It is the link counterpart of
+[`gbt-tabs`](../tabs/README.md), which is for panels that switch in place.
+
+It is **router-agnostic**: no `@angular/router` anywhere in the library. The application decides which item is
+active (`[active]`) and puts `routerLink` or a plain `href` on each anchor, so sections stay deep-linkable, the
+back button walks through them, and middle-click / "open in a new tab" keep working. Keyboard behaviour is that of
+native links: Tab, Shift+Tab and Enter (no roving tabindex, no arrow-key handling — it is a list of links, not a
+`tablist`).
+
+**Selectors**: `gbt-nav-tabs` (class `NavTabs`) and `a[gbtNavTab]` (class `NavTab`), both standalone.
+
+```ts
+import { NavTab, NavTabs } from '@masmarino/gabarit'
+```
+
+## `gbt-nav-tabs` inputs
+
+| Input         | Type                         | Default        | Role                                                                                                                                                      |
+| ------------- | ---------------------------- | -------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `ariaLabel`   | `string`                     | `''`           | Accessible name of the `<nav>` landmark. Give one (it is what a screen-reader user hears in the landmark list); ignored when `landmark` is `false`.       |
+| `orientation` | `'horizontal' \| 'vertical'` | `'horizontal'` | `horizontal`: underline tabs above a section. `vertical`: a list of pill links for a side column.                                                         |
+| `landmark`    | `boolean`                    | `true`         | Render the links in a `<nav>` of their own. Pass `false` inside a navigation that already exists (a `gbt-page-layout` `[page-nav]`): no nested landmarks. |
+
+## `a[gbtNavTab]` inputs
+
+| Input    | Type                       | Default | Role                                                                                                                         |
+| -------- | -------------------------- | ------- | ---------------------------------------------------------------------------------------------------------------------------- |
+| `active` | `boolean`                  | `false` | This item is the current page or section: sets `aria-current="page"` and the active look. At most one item should be active. |
+| `icon`   | `string \| null`           | `null`  | Registered icon name before the label. Decorative (`aria-hidden`): the label names the link.                                 |
+| `badge`  | `number \| string \| null` | `null`  | A counter pill after the label — `0` and `'20+'` included, `null` and `''` show nothing. Read as part of the link's name.    |
+
+The label is the projected content.
+
+## Behaviour
+
+- **Horizontal** is a row of underline tabs with a hairline under it. When the tabs overflow, the row scrolls to
+  the active one (keeping a glimpse of the previous tab) — the list scrolls, never the page — and fades at the edge
+  that hides tabs. A tab keeps the width of its bold state, so nothing shifts when the active tab changes.
+- **Vertical** is a list of pills, the active one with an accent bar on its leading edge (not the tint alone). While
+  a [`gbt-page-layout`](../page-layout/README.md) stacks its columns (its container is ≤ 768 px wide),
+  a vertical nav folds into that same row of tabs above the section, instead of pushing it far down. Outside a page
+  layout it stays a list.
+- Both look at the active tab through `aria-current="page"`, which is what assistive technology reads.
+
+## Examples
+
+Router-less (plain hrefs; the application owns the active section):
+
+```html
+<gbt-nav-tabs ariaLabel="Repository settings">
+  <a
+    gbtNavTab
+    href="#general"
+    icon="settings"
+    [active]="section() === 'general'"
+    (click)="section.set('general')"
+    >General</a
+  >
+  <a
+    gbtNavTab
+    href="#webhooks"
+    icon="bell"
+    [badge]="3"
+    [active]="section() === 'webhooks'"
+    (click)="section.set('webhooks')"
+    >Webhooks</a
+  >
+</gbt-nav-tabs>
+```
+
+With the Angular router, in the application (the library never imports it):
+
+```html
+<gbt-nav-tabs ariaLabel="Account settings">
+  @for (section of sections; track section.path) {
+  <a
+    gbtNavTab
+    [routerLink]="section.path"
+    routerLinkActive
+    #rla="routerLinkActive"
+    [active]="rla.isActive"
+    [icon]="section.icon"
+    >{{ section.label }}</a
+  >
+  }
+</gbt-nav-tabs>
+```
+
+Do not also set `ariaCurrentWhenActive` on the same element: `active` already sets `aria-current`. A matcher of your
+own just computes the boolean you feed to `[active]`.
+
+Inside a page layout's nav column, without a second landmark:
+
+```html
+<gbt-page-layout navLabel="Repository settings">
+  <gbt-nav-tabs page-nav orientation="vertical" [landmark]="false">…</gbt-nav-tabs>
+  …the section…
+</gbt-page-layout>
+```
+
+## Accessibility
+
+See [AUDIT.md](AUDIT.md).

package/notification-dot/README.md

@@ -0,0 +1,43 @@
+# NotificationDot
+
+A small dot or count badge overlaid on the corner of whatever it
+wraps — an icon, an avatar, a button — for an "unread"/"new" signal
+(e.g. a bell icon with an unread-notifications count). Distinct from
+`Badge`, which is a standalone inline label, not an overlay on another
+element.
+
+**Selector**: `gbt-notification-dot` (`exportAs="gbtNotificationDot"`)
+
+## Inputs
+
+| Input     | Type                                          | Default   | Role                                                   |
+| --------- | ------------------------------------------------ | ----------- | --------------------------------------------------------- |
+| `count`   | `number \| null`                                  | `null`      | `null` shows a plain dot; a number shows it as text.        |
+| `max`     | `number`                                          | `99`         | A count above this shows as `"{max}+"`.                     |
+| `variant` | `'error' \| 'warning' \| 'success' \| 'info'`     | `'error'`    | Reuses `Badge`'s own semantic color tokens.                 |
+| `hidden`  | `boolean`                                          | `false`      | Force-hides the dot regardless of `count`.                  |
+
+A `count` of exactly `0` also hides the dot — there's rarely a reason
+to show "0" as a notification badge.
+
+## Example
+
+```html
+<gbt-notification-dot #dot="gbtNotificationDot" [count]="unreadCount()">
+  <button type="button" [attr.aria-label]="'Notifications, ' + dot.count() + ' unread'">
+    <gbt-icon name="bell" />
+  </button>
+</gbt-notification-dot>
+```
+
+## Accessibility
+
+Like `Tooltip` and `Popover`, `gbt-notification-dot` wraps arbitrary
+projected content and cannot inject an accessible name onto it — the
+visual dot itself is `aria-hidden="true"`, since a screen reader
+reading "3" out of context (disconnected from what it's a count of)
+isn't useful. Instead, `count` is exposed publicly via
+`exportAs="gbtNotificationDot"` so the consumer can fold it into
+*their own* trigger's accessible name (as in the example above),
+producing one coherent announcement ("Notifications, 3 unread") rather
+than two disconnected ones.