@bitforgehq/ui 0.3.0

package/ai/components/alert-dialog.md

@@ -0,0 +1,509 @@
+# bf-alert-dialog
+
+Centred confirmation dialog with a title, message and a row of role-styled buttons
+
+`BfAlertDialogComponent` from `@bitforgehq/ui/mobile` · Overlays · since 0.2.0
+
+## Example
+
+```ts
+import { Component, inject, signal } from '@angular/core';
+import { BfButtonComponent } from '@bitforgehq/ui';
+import {
+  BfAlertDialogService,
+  BfContentComponent,
+  BfHeaderComponent,
+  BfPageComponent,
+} from '@bitforgehq/ui/mobile';
+
+/**
+ * `bf-alert-dialog` showcase: a confirmation with a cancel and a destructive button, and an
+ * informational alert with a single OK.
+ */
+@Component({
+  selector: 'app-alert-dialog-showcase',
+  imports: [BfPageComponent, BfHeaderComponent, BfContentComponent, BfButtonComponent],
+  template: `
+    <bf-page data-showcase="alert-dialog">
+      <bf-header title="Alert dialog" [largeTitle]="false" />
+      <bf-content>
+        <div class="flex flex-col gap-4 p-4">
+          <p class="text-caption text-text-muted">
+            An alert must be answered: there is no backdrop dismiss, and Escape answers with the
+            cancel button when there is one.
+          </p>
+          <bf-button variant="danger" (clicked)="confirmDelete()">Delete draft</bf-button>
+          <bf-button variant="tonal" (clicked)="inform()">Show sync status</bf-button>
+          <p data-showcase-result class="text-body">{{ result() }}</p>
+        </div>
+      </bf-content>
+    </bf-page>
+  `,
+})
+export class AlertDialogShowcasePage {
+  private readonly alerts = inject(BfAlertDialogService);
+
+  protected readonly result = signal('No answer yet.');
+
+  async confirmDelete(): Promise<void> {
+    const answer = await this.alerts.open({
+      title: 'Delete draft?',
+      message: 'This cannot be undone.',
+      buttons: [
+        { label: 'Cancel', role: 'cancel' },
+        { label: 'Delete', role: 'destructive' },
+      ],
+    });
+    this.report(answer);
+  }
+
+  async inform(): Promise<void> {
+    const answer = await this.alerts.open({
+      title: 'All synced',
+      message: 'Your notes are up to date on every device.',
+    });
+    this.report(answer);
+  }
+
+  /** A navigation closes an alert without a cancel button with no answer (`undefined`). */
+  private report(answer: string | undefined): void {
+    this.result.set(answer === undefined ? 'Closed without an answer.' : `Answered “${answer}”.`);
+  }
+}
+```
+
+## Overview
+
+The alert dialog card that `BfAlertDialogService.open()` renders on the overlay core
+(`position: 'center'`): an `h2.text-heading` title, an optional `text-body text-text-secondary`
+message, and a right-aligned row of `bf-button`s (`cancel`-role `text`, `destructive`-role
+`danger`, the first plain button `primary`, further plain ones `tonal`). Focus starts on the
+`cancel`-role button, else the first one. Tapping a button resolves the overlay with its
+`id ?? label`. There is no backdrop dismiss; `Escape` and the hardware
+back button are handled by `BfAlertDialogService` (the cancel button's answer, or claimed and
+ignored when there is none). Not used directly in templates.
+
+A centred confirmation dialog. `BfAlertDialogService.open({ title, message?, buttons? })` renders
+`bf-alert-dialog` on the overlay core: a title, an optional message and a row of buttons. It
+resolves a `Promise<string>` with the tapped button's `id`, or its label when it has none — always
+a string, never `undefined`, because the dialog cannot be dismissed without answering it. You never place `<bf-alert-dialog>`
+in a template yourself.
+
+## When to use
+
+Use `BfAlertDialogService` in the Capacitor shell for a short question the user must answer before going on: discard a draft, delete an item. Use [BfActionSheetService](https://bitforge-ui.web.app/api/bf-action-sheet-service) instead for a choice between several actions, and [BfDialogService](https://bitforge-ui.web.app/api/bf-dialog-service) `confirm()` on desktop.
+
+## Basic usage
+
+Without `buttons`, the dialog shows a single button labelled with `provideBfLabels()`'s `ok` ("OK").
+
+```ts
+import { Component, inject, signal } from '@angular/core';
+import { BfButtonComponent } from '@bitforgehq/ui';
+import { BfAlertDialogService } from '@bitforgehq/ui/mobile';
+
+/**
+ * An alert with a message and the default OK button.
+ *
+ * `open()` resolves once the alert is answered.
+ *
+ * @preview none
+ */
+@Component({
+  selector: 'app-example-alert-dialog-basic',
+  imports: [BfButtonComponent],
+  template: `
+    <div class="flex flex-col items-start gap-3">
+      <bf-button (clicked)="open()">Sync</bf-button>
+      <p aria-live="polite" class="text-caption text-text-muted">{{ result() }}</p>
+    </div>
+  `,
+})
+export class AlertDialogBasicExampleComponent {
+  private readonly alerts = inject(BfAlertDialogService);
+  protected readonly result = signal('');
+
+  protected async open(): Promise<void> {
+    await this.alerts.open({
+      title: 'Sync failed',
+      message: 'Check your connection and try again.',
+    });
+    this.result.set('Alert closed.');
+  }
+}
+```
+
+## Confirmation with a cancel button
+
+Give `buttons` a `cancel`-role entry to let the dialog be dismissed by `Escape` or the hardware
+back button too — both resolve with that button's answer. The cancel button also takes the
+initial focus, wherever it sits in the row.
+
+```ts
+import { Component, inject, signal } from '@angular/core';
+import { BfButtonComponent } from '@bitforgehq/ui';
+import { BfAlertDialogService } from '@bitforgehq/ui/mobile';
+
+/**
+ * A confirmation with a cancel button.
+ *
+ * The `cancel`-role button answers a dismissal; the destructive one renders in the danger colour.
+ *
+ * @preview none
+ */
+@Component({
+  selector: 'app-example-alert-dialog-confirm',
+  imports: [BfButtonComponent],
+  template: `
+    <div class="flex flex-col items-start gap-3">
+      <bf-button variant="danger" (clicked)="open()">Delete list…</bf-button>
+      <p aria-live="polite" class="text-caption text-text-muted">{{ result() }}</p>
+    </div>
+  `,
+})
+export class AlertDialogConfirmExampleComponent {
+  private readonly alerts = inject(BfAlertDialogService);
+  protected readonly result = signal('');
+
+  protected async open(): Promise<void> {
+    const answer = await this.alerts.open({
+      title: 'Delete list?',
+      message: 'This cannot be undone.',
+      buttons: [
+        { id: 'cancel', label: 'Cancel', role: 'cancel' },
+        { id: 'delete', label: 'Delete', role: 'destructive' },
+      ],
+    });
+    this.result.set(answer === 'delete' ? 'Deleted.' : 'Kept.');
+  }
+}
+```
+
+## Answers with ids
+
+Give each button an `id` and compare against it: `open()` resolves `id ?? label`, so the check
+keeps working when the labels are translated, and two buttons that end up with the same label are
+still told apart. Without an `id` the label is the answer, as before.
+
+```ts
+import { Component, inject, signal } from '@angular/core';
+import { BfButtonComponent } from '@bitforgehq/ui';
+import { BfAlertDialogService } from '@bitforgehq/ui/mobile';
+
+/** The app's translated labels (German here): the ids, not these, carry the answer. */
+const LABELS = { cancel: 'Abbrechen', device: 'Auf diesem Gerät', cloud: 'In der Cloud' };
+
+/**
+ * Buttons answered by id.
+ *
+ * The ids stay the same whatever the translated labels say.
+ *
+ * @preview none
+ */
+@Component({
+  selector: 'app-example-alert-dialog-ids',
+  imports: [BfButtonComponent],
+  template: `
+    <div class="flex flex-col items-start gap-3">
+      <bf-button (clicked)="open()">Save a copy</bf-button>
+      <p aria-live="polite" class="text-caption text-text-muted">{{ result() }}</p>
+    </div>
+  `,
+})
+export class AlertDialogIdsExampleComponent {
+  private readonly alerts = inject(BfAlertDialogService);
+  protected readonly result = signal('');
+
+  protected async open(): Promise<void> {
+    const where = await this.alerts.open({
+      title: 'Save a copy?',
+      buttons: [
+        { id: 'cancel', label: LABELS.cancel, role: 'cancel' },
+        { id: 'device', label: LABELS.device },
+        { id: 'cloud', label: LABELS.cloud },
+      ],
+    });
+    this.result.set(where ?? 'Dismissed.');
+  }
+}
+```
+
+## Button variants
+
+Buttons render left to right in the order given: a `cancel`-role button is `text`, a
+`destructive`-role button is `danger`, the first plain button is `primary`, and any further plain
+button is `tonal`.
+
+```ts
+import { Component, inject, signal } from '@angular/core';
+import { BfButtonComponent } from '@bitforgehq/ui';
+import { BfAlertDialogService } from '@bitforgehq/ui/mobile';
+
+/**
+ * The button variants of an alert.
+ *
+ * The first plain button is primary, further plain ones tonal, and a destructive one danger.
+ *
+ * @preview none
+ */
+@Component({
+  selector: 'app-example-alert-dialog-variants',
+  imports: [BfButtonComponent],
+  template: `
+    <div class="flex flex-col items-start gap-3">
+      <bf-button (clicked)="open()">Close the draft</bf-button>
+      <p aria-live="polite" class="text-caption text-text-muted">{{ result() }}</p>
+    </div>
+  `,
+})
+export class AlertDialogVariantsExampleComponent {
+  private readonly alerts = inject(BfAlertDialogService);
+  protected readonly result = signal('');
+
+  protected async open(): Promise<void> {
+    const answer = await this.alerts.open({
+      title: 'Keep editing?',
+      buttons: [
+        { label: 'Discard', role: 'destructive' },
+        { label: 'Save as draft' }, // tonal (a plain button after the primary one)
+        { label: 'Save' }, // primary (the first plain button)
+      ],
+    });
+    this.result.set(answer ?? 'Dismissed.');
+  }
+}
+```
+
+## Navigation
+
+A navigation to another URL path closes the alert: `open()` resolves the cancel button's answer
+when it has one, else `undefined` (so `open()` returns `Promise<string | undefined>`; treat
+`undefined` like cancel). A query- or fragment-only change leaves it open. In the `/mobile` shell
+every push, every pop (the header back button, swipe-back, `BfNavController.back()`) and every tab
+switch changes the path, so an alert opened on a page closes when that page is left. The Android
+hardware back button with an alert open never pops the page (its handler runs at priority 100,
+above the page pop): it answers with the cancel button, or is ignored without one. Android back
+in a browser without Capacitor (Chrome, a PWA) does the same where `CloseWatcher` exists, and
+the URL stays: an alert without a cancel button swallows it and stays open. An alert
+opened before the first navigation ends closes when the start URL redirects. Pass
+`closeOnNavigation: false` to keep it open until a button is tapped.
+
+```ts
+import { Component, inject, signal } from '@angular/core';
+import { BfButtonComponent } from '@bitforgehq/ui';
+import { BfAlertDialogService } from '@bitforgehq/ui/mobile';
+
+/**
+ * An alert that stays open across navigations.
+ *
+ * `closeOnNavigation: false` keeps it open when the route changes underneath.
+ *
+ * @preview none
+ */
+@Component({
+  selector: 'app-example-alert-dialog-navigation',
+  imports: [BfButtonComponent],
+  template: `
+    <div class="flex flex-col items-start gap-3">
+      <bf-button (clicked)="open()">Sync</bf-button>
+      <p aria-live="polite" class="text-caption text-text-muted">{{ result() }}</p>
+    </div>
+  `,
+})
+export class AlertDialogNavigationExampleComponent {
+  private readonly alerts = inject(BfAlertDialogService);
+  protected readonly result = signal('');
+
+  protected async open(): Promise<void> {
+    const answer = await this.alerts.open({ title: 'Sync failed', closeOnNavigation: false });
+    this.result.set(answer ?? 'Dismissed.');
+  }
+}
+```
+
+## Labels and the injector
+
+Default strings come from `provideBfLabels()` (`ok`, "OK"). The service is a root singleton, so it reads
+the app-level labels; to use a feature's own `provideBfLabels()` (in a component's `providers`),
+pass that component's injector. It then also becomes the parent of the dialog's content injector,
+so the content resolves the feature's providers.
+
+```ts
+import { Component, Injector, inject } from '@angular/core';
+import { BfButtonComponent, provideBfLabels } from '@bitforgehq/ui';
+import { BfAlertDialogService } from '@bitforgehq/ui/mobile';
+
+/**
+ * An alert that reads a feature's labels.
+ *
+ * This feature provides German labels; passing the opener's injector is what makes the alert's
+ * default button read "Verstanden" instead of the app's "OK".
+ *
+ * @preview none
+ */
+@Component({
+  selector: 'app-example-alert-dialog-injector',
+  imports: [BfButtonComponent],
+  providers: [provideBfLabels({ ok: 'Verstanden' })],
+  template: `<bf-button (clicked)="open()">Speichern</bf-button>`,
+})
+export class AlertDialogInjectorExampleComponent {
+  private readonly alerts = inject(BfAlertDialogService);
+  private readonly injector = inject(Injector);
+
+  protected open(): void {
+    void this.alerts.open({ title: 'Gespeichert', injector: this.injector });
+  }
+}
+```
+
+## Desktop
+
+`bf-alert-dialog` is phone-shaped and meant for the Capacitor shell (`provideBfShell()`). On a
+desktop web app, use the desktop overlays from `@bitforgehq/ui/overlay` instead: they need only
+`@angular/cdk`, no Capacitor and no router. A desktop dialog locks the page's scroll, makes the page
+behind it `inert`, and traps and restores focus.
+
+`BfDialogService.confirm()` is the desktop alert dialog: the same `buttons` (ids, `cancel` and
+`destructive` roles), focus on the cancel button, and an answer of `id ?? label`.
+
+```ts
+import { Component, inject, signal } from '@angular/core';
+import { BfButtonComponent } from '@bitforgehq/ui';
+import { BfDialogService } from '@bitforgehq/ui/overlay';
+
+/**
+ * A destructive confirmation.
+ *
+ * `confirm()` resolves with the pressed button's id: `delete`, `cancel`, or the cancel answer on
+ * `Escape`.
+ */
+@Component({
+  selector: 'app-example-dialog-confirm',
+  imports: [BfButtonComponent],
+  template: `
+    <div class="flex flex-col items-start gap-3">
+      <bf-button variant="danger" (clicked)="remove()">Delete project…</bf-button>
+      <p aria-live="polite" class="text-caption text-text-muted">{{ result() }}</p>
+    </div>
+  `,
+})
+export class DialogConfirmExampleComponent {
+  private readonly dialogs = inject(BfDialogService);
+  protected readonly result = signal('');
+
+  protected async remove(): Promise<void> {
+    const answer = await this.dialogs.confirm({
+      title: 'Delete project?',
+      message: 'Its tasks and files are deleted too. This cannot be undone.',
+      buttons: [
+        { id: 'cancel', label: 'Cancel', role: 'cancel' },
+        { id: 'delete', label: 'Delete', role: 'destructive' },
+      ],
+    });
+    this.result.set(answer === 'delete' ? 'Deleted (not really).' : 'Kept.');
+  }
+}
+```
+
+## Theming
+
+- Card: `bg-surface`, `rounded-card` (`--radius-card`), `shadow-floating`, fixed `w-75` (300 px)
+  (`max-w-[calc(100vw-2*var(--spacing-gutter))]` on narrow viewports).
+- Title: `text-heading`; message: `text-body text-text-secondary`.
+- Buttons: `bf-button` (`text`, `danger`, `primary`, `tonal` — see Button variants).
+- Backdrop: `bf-overlay-backdrop` from the overlay core (a black scrim: 40 % in light mode, 60 % in dark), rendered but never
+  dismissing.
+
+## Accessibility
+
+The overlay panel is a `role="alertdialog"` with `aria-modal="true"`, `aria-labelledby`
+pointing at the title and, when there is a `message`, `aria-describedby` pointing at it; the page stack behind it is `inert`. Focus lands on the `cancel`-role
+button, else on the first button (the title and message hold no focusable content), so Enter on
+open never confirms a destructive action ([APG alert dialog](https://www.w3.org/WAI/ARIA/apg/patterns/alertdialog/):
+focus the least destructive choice). Tab is trapped inside, and focus returns to the
+element that opened the dialog on close. There is no backdrop dismiss. `Escape` and the hardware
+back button resolve with the cancel button's `id ?? label` when `buttons` has one; with none, both are
+claimed and otherwise ignored, so the dialog stays open — **an alert must have a cancel button to
+be dismissible** any other way than tapping a button. Either way the key stops at the alert: an
+alert opened over a sheet never lets `Escape` close the sheet underneath. Under `prefers-reduced-motion` the card
+cross-fades in and out instead of scaling.
+
+### Keyboard
+
+| Key                                              | Action                                                                                                          |
+| ------------------------------------------------ | --------------------------------------------------------------------------------------------------------------- |
+| <kbd>Tab</kbd> / <kbd>Shift</kbd>+<kbd>Tab</kbd> | Moves between the buttons, wrapping inside the dialog; focus starts on the `cancel`-role button, else the first |
+| <kbd>Enter</kbd> / <kbd>Space</kbd>              | Activates the focused button                                                                                    |
+| <kbd>Escape</kbd>                                | Answers with the `cancel`-role button; without one, it is claimed and ignored                                   |
+
+## Notes
+
+### Do
+
+- Give every dismissible confirmation a `cancel`-role button, so `Escape` and the hardware back
+  button work the way people expect.
+- Keep `message` short and put the consequence in it ("This cannot be undone") rather than in the
+  title.
+- Use `role: 'destructive'` on the button that causes data loss, and word it as the action
+  ("Delete", not "Yes").
+
+### Don't
+
+- Don't open an alert with no cancel button unless every button is a safe, equally valid answer
+  (an informational dialog with just "OK") — otherwise give it a cancel button.
+- Don't stack more than two or three buttons; use an action sheet (`BfActionSheetService`) for a
+  longer list of choices.
+- Don't rely on a backdrop tap to close the dialog — there is none, by design, so the user must
+  make a choice.
+
+## Migration notes
+
+### 0.3.0
+
+New exported `BfAlertDialogButtonRole` (`'cancel' | 'destructive'`), the type of
+`BfAlertDialogButton.role` (was an inline union with the same values).
+
+**Type:** `open()` returns `Promise<string | undefined>` (was `Promise<string>`): a navigation to
+another URL path closes the alert and resolves the cancel button's answer, else `undefined`. New
+`closeOnNavigation` option (default true). Migration: handle `undefined` like cancel (see
+Migration 18).
+
+**Behaviour:** the default button (no `buttons`) is labelled with `provideBfLabels()`'s `ok`
+("OK").
+
+New `injector` option: labels resolve from it per call (default the root injector) and it becomes
+the parent of the content's injector, so a feature-level `provideBfLabels()` and the feature's
+other providers reach the dialog.
+
+`BfAlertDialogButton` gains `id?: string`; `open()` resolves the tapped button's `id ?? label`,
+and `Escape` and the hardware back button the cancel button's. Buttons render with
+`track $index`, so two buttons with the same label both render.
+
+**Behaviour:** focus starts on the `cancel`-role button, else the first button (APG alert dialog),
+even when a destructive button comes first (see Migration 17).
+
+JSDoc of `alert-dialog.service.ts` for the API reference: `@summary`/`@since` on the exported
+symbols; `@default` on the option properties the code applies; `@param` docs. No behaviour change.
+
+The docs say that Android back in a browser with `CloseWatcher` answers with the cancel button,
+and that an alert without one swallows it; see `### overlay core` and Migration 35.
+
+### 0.2.0
+
+New `BfAlertDialogService.open({ title, message?, buttons? })` in `@bitforgehq/ui/mobile`,
+resolving `Promise<string>` with the tapped button's label. Renders `bf-alert-dialog` on the
+overlay core (`position: 'center'`, back priority 100, not counted as a modal, no backdrop
+dismiss, `role="alertdialog"` with `aria-labelledby` the generated title id and, when there is a
+message, `aria-describedby` its paragraph). The card (`w-75
+max-w-[calc(100vw-2*var(--spacing-gutter))] bg-surface rounded-card shadow-floating p-6 flex flex-col gap-4`) is an
+`h2.text-heading` title, an optional `text-body text-text-secondary` message and a right-aligned
+`buttons` row (default `[{ label: 'OK' }]`): `cancel`-role renders `text`, `destructive`-role
+`danger`, the first plain button `primary`, further plain ones `tonal`. Unlike every other
+overlay, `Escape` and the hardware back button do not close through the core's
+`dismissOnEscape`/back handling (the service passes `onEscape` and claims the back button itself):
+they
+resolve with the cancel button's label when `buttons` has one, and are otherwise claimed and
+ignored, since an alert with no cancel button can only be answered by tapping a button. Focus
+lands on the first button — the core's first-tabbable search, since the title and message hold no
+focusable content. `provideBfShell()` now also provides `BfAlertDialogService`.