@bitforgehq/ui 0.3.0

package/ai/components/dialog.md

@@ -0,0 +1,962 @@
+# bf-dialog
+
+Desktop modal dialog with a title, scrolling body, footer actions and focus trap
+
+`BfDialogComponent` from `@bitforgehq/ui/overlay` · Overlays · since 0.3.0
+
+## Example
+
+```ts
+import { Component, inject, signal } from '@angular/core';
+import { BfButtonComponent, BfInputComponent } from '@bitforgehq/ui';
+import {
+  BF_DIALOG_DATA,
+  BfDialogComponent,
+  BfDialogRef,
+  BfDialogService,
+  BfMenuButtonComponent,
+  BfMenuComponent,
+  BfMenuItemDirective,
+} from '@bitforgehq/ui/overlay';
+
+/** The project a demo dialog edits. */
+export interface DemoProject {
+  name: string;
+  owner: string;
+}
+
+/** The form dialog of the demo: two fields, Cancel and Save. */
+@Component({
+  selector: 'app-dialog-demo-edit',
+  imports: [BfDialogComponent, BfButtonComponent, BfInputComponent],
+  template: `
+    <bf-dialog title="Edit project">
+      <bf-input label="Name" [(value)]="name" />
+      <bf-input label="Owner" [(value)]="owner" />
+      <div bfSlot="footer">
+        <bf-button variant="outline" (clicked)="ref.close()">Cancel</bf-button>
+        <bf-button (clicked)="save()">Save</bf-button>
+      </div>
+    </bf-dialog>
+  `,
+})
+export class DialogDemoEditComponent {
+  protected readonly ref = inject<BfDialogRef<DemoProject>>(BfDialogRef);
+  private readonly project = inject<DemoProject>(BF_DIALOG_DATA);
+
+  protected readonly name = signal(this.project.name);
+  protected readonly owner = signal(this.project.owner);
+
+  protected save(): void {
+    this.ref.close({ name: this.name(), owner: this.owner() });
+  }
+}
+
+/** The sections of the long dialog: more text than fits, so its body scrolls. */
+const RELEASE_NOTES: readonly { title: string; body: string }[] = [
+  { title: 'Boards', body: 'Columns keep their width when you collapse the sidebar.' },
+  { title: 'Search', body: 'Results group by project, and the newest match comes first.' },
+  { title: 'Invoices', body: 'Drafts save every few seconds, so a closed tab loses nothing.' },
+  { title: 'Calendar', body: 'Week view starts on the day your team settings name.' },
+  { title: 'Files', body: 'Uploads resume after a lost connection instead of starting over.' },
+  { title: 'Comments', body: 'Mentions notify once, even when you edit the comment later.' },
+  { title: 'Reports', body: 'Exports keep the filters and the column order you chose.' },
+  { title: 'Tasks', body: 'Recurring tasks skip public holidays when you ask them to.' },
+  { title: 'Team', body: 'Guests see only the projects they were invited to.' },
+  { title: 'Settings', body: 'The theme follows your system until you pick one yourself.' },
+];
+
+/** A dialog whose body is taller than the viewport allows: the body scrolls, the page does not. */
+@Component({
+  selector: 'app-dialog-demo-notes',
+  imports: [BfDialogComponent, BfButtonComponent],
+  template: `
+    <bf-dialog title="Release notes">
+      @for (note of notes; track note.title) {
+        <section class="flex flex-col gap-1">
+          <h3 class="text-label font-bold">{{ note.title }}</h3>
+          <p class="text-body text-text-secondary">{{ note.body }}</p>
+          <p class="text-body text-text-secondary">
+            Nothing changes for your existing data, and you can switch it back in the settings.
+          </p>
+        </section>
+      }
+      <div bfSlot="footer">
+        <bf-button (clicked)="ref.close(true)">Got it</bf-button>
+      </div>
+    </bf-dialog>
+  `,
+})
+export class DialogDemoNotesComponent {
+  protected readonly ref = inject<BfDialogRef<boolean>>(BfDialogRef);
+  protected readonly notes = RELEASE_NOTES;
+}
+
+/** Who can open a shared project link. */
+export type DemoAccess = 'Only the team' | 'Anyone with the link';
+
+/**
+ * A dialog with a menu button in its footer: `Escape` in the open menu closes the menu only, and
+ * a second `Escape` closes the dialog.
+ */
+@Component({
+  selector: 'app-dialog-demo-share',
+  imports: [
+    BfDialogComponent,
+    BfButtonComponent,
+    BfMenuButtonComponent,
+    BfMenuComponent,
+    BfMenuItemDirective,
+  ],
+  template: `
+    <bf-dialog title="Share project">
+      <p class="text-body text-text-secondary">Link access: {{ access() }}</p>
+      <div bfSlot="footer">
+        <bf-menu-button data-testid="dialog-share-access" [menu]="accessMenu">
+          Link access
+        </bf-menu-button>
+        <bf-button (clicked)="ref.close(access())">Done</bf-button>
+      </div>
+    </bf-dialog>
+
+    <ng-template #accessMenu>
+      <bf-menu>
+        <button bfMenuItem (triggered)="access.set('Only the team')">Only the team</button>
+        <button bfMenuItem (triggered)="access.set('Anyone with the link')">
+          Anyone with the link
+        </button>
+      </bf-menu>
+    </ng-template>
+  `,
+})
+export class DialogDemoShareComponent {
+  protected readonly ref = inject<BfDialogRef<DemoAccess>>(BfDialogRef);
+  protected readonly access = signal<DemoAccess>('Only the team');
+}
+
+/**
+ * The bf-dialog overview.
+ *
+ * Live demo of `bf-dialog` and `BfDialogService`, rendered in place: "Edit project" opens a form
+ * dialog, "Delete…" a `confirm()` alert dialog, "Release notes" a dialog whose body scrolls and
+ * "Share…" a dialog with a menu button in its footer; the result line announces each outcome
+ * (the `confirm()` answer id included). The triggers and the result line carry `data-testid`s
+ * for the end-to-end suite.
+ */
+@Component({
+  selector: 'app-example-dialog-overview',
+  imports: [BfButtonComponent],
+  template: `
+    <div class="flex flex-col gap-4">
+      <p class="text-heading">{{ project().name }}</p>
+      <p class="text-body text-text-secondary">Owner: {{ project().owner }}</p>
+      <div class="flex flex-wrap gap-2">
+        <bf-button data-testid="dialog-edit" (clicked)="edit()">Edit project</bf-button>
+        <bf-button data-testid="dialog-delete" variant="danger" (clicked)="remove()">
+          Delete…
+        </bf-button>
+        <bf-button data-testid="dialog-notes" variant="outline" (clicked)="readNotes()">
+          Release notes
+        </bf-button>
+        <bf-button data-testid="dialog-share" variant="tonal" (clicked)="share()">
+          Share…
+        </bf-button>
+      </div>
+      <p
+        data-status
+        data-testid="dialog-result"
+        class="text-caption text-text-muted"
+        aria-live="polite"
+      >
+        {{ result() }}
+      </p>
+    </div>
+  `,
+})
+export class DialogOverviewExampleComponent {
+  private readonly dialogs = inject(BfDialogService);
+
+  readonly project = signal<DemoProject>({ name: 'Atlas rebrand', owner: 'Mia Keller' });
+  readonly result = signal('');
+
+  async edit(): Promise<void> {
+    const ref = this.dialogs.open<DialogDemoEditComponent, DemoProject, DemoProject>(
+      DialogDemoEditComponent,
+      { data: this.project() },
+    );
+    const saved = await ref.afterClosed;
+    if (saved) {
+      this.project.set(saved);
+      this.result.set('Saved.');
+    } else {
+      this.result.set('Edit cancelled.');
+    }
+  }
+
+  async remove(): Promise<void> {
+    const answer = await this.dialogs.confirm({
+      title: `Delete ${this.project().name}?`,
+      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'
+        ? 'Answer "delete": deleted (not really, this is a demo).'
+        : `Answer "${answer ?? 'none'}": kept.`,
+    );
+  }
+
+  async readNotes(): Promise<void> {
+    const read = await this.dialogs.open<DialogDemoNotesComponent, unknown, boolean>(
+      DialogDemoNotesComponent,
+    ).afterClosed;
+    this.result.set(read ? 'Release notes read.' : 'Release notes closed.');
+  }
+
+  async share(): Promise<void> {
+    const access = await this.dialogs.open<DialogDemoShareComponent, unknown, DemoAccess>(
+      DialogDemoShareComponent,
+    ).afterClosed;
+    this.result.set(access ? `Link access: ${access}.` : 'Sharing unchanged.');
+  }
+}
+```
+
+## Overview
+
+Layout of a modal dialog opened with `BfDialogService`: a title row, a scrolling body and a
+footer of actions. The panel is labelled by the title, and the body becomes focusable only
+while its content overflows, so keyboard users can scroll it (a region named by the title when
+there is one).
+
+A modal dialog for desktop and web apps, from `@bitforgehq/ui/overlay` (needs `@angular/cdk`, no
+Capacitor). `BfDialogService.open()` renders your component or template centred over a backdrop
+and returns a typed `BfDialogRef`; `bf-dialog` inside the content lays out the title, the
+scrolling body and the footer actions. `confirm()` opens an alert dialog in one call.
+
+## When to use
+
+Use `BfDialogService` for a task or a decision that needs the user's full attention before the page goes on: a form, a detail view, a destructive confirmation (`confirm()`). Use [bf-menu](https://bitforge-ui.web.app/components/menu) instead for a short list of actions, [BfDesktopToastService](https://bitforge-ui.web.app/api/bf-desktop-toast-service) for a status that needs no answer, and [bf-alert](https://bitforge-ui.web.app/components/alert) for information that fits in the page. In the Capacitor shell, use [BfModalService](https://bitforge-ui.web.app/api/bf-modal-service) or [BfAlertDialogService](https://bitforge-ui.web.app/api/bf-alert-dialog-service) instead.
+
+## Basic usage
+
+Write the dialog as a component whose template is a `bf-dialog`. It injects `BfDialogRef` to
+close itself and `BF_DIALOG_DATA` for its input. Put the actions in `bfSlot="footer"`.
+
+```ts
+import { Component, inject, signal } from '@angular/core';
+import { BfButtonComponent, BfInputComponent } from '@bitforgehq/ui';
+import {
+  BF_DIALOG_DATA,
+  BfDialogComponent,
+  BfDialogRef,
+  BfDialogService,
+} from '@bitforgehq/ui/overlay';
+
+/** The dialog: a `bf-dialog` that closes itself with the new name. */
+@Component({
+  selector: 'app-rename-dialog',
+  imports: [BfDialogComponent, BfButtonComponent, BfInputComponent],
+  template: `
+    <bf-dialog title="Rename project">
+      <bf-input label="Name" [(value)]="name" />
+      <div bfSlot="footer">
+        <bf-button variant="outline" (clicked)="ref.close()">Cancel</bf-button>
+        <bf-button (clicked)="ref.close(name())">Save</bf-button>
+      </div>
+    </bf-dialog>
+  `,
+})
+export class RenameDialogComponent {
+  protected readonly ref = inject<BfDialogRef<string>>(BfDialogRef);
+  protected readonly name = signal(inject<{ name: string }>(BF_DIALOG_DATA).name);
+}
+
+/**
+ * A dialog that renames a project.
+ *
+ * `open()` passes the current name as data and awaits the result: the new name, or `undefined`
+ * when the dialog is dismissed.
+ */
+@Component({
+  selector: 'app-example-dialog-basic',
+  imports: [BfButtonComponent],
+  template: `
+    <div class="flex flex-col items-start gap-3">
+      <p class="text-heading">{{ project().name }}</p>
+      <bf-button (clicked)="rename()">Rename…</bf-button>
+      <p aria-live="polite" class="text-caption text-text-muted">{{ result() }}</p>
+    </div>
+  `,
+})
+export class DialogBasicExampleComponent {
+  private readonly dialogs = inject(BfDialogService);
+  protected readonly project = signal({ name: 'Atlas rebrand' });
+  protected readonly result = signal('');
+
+  protected async rename(): Promise<void> {
+    const ref = this.dialogs.open<RenameDialogComponent, { name: string }, string>(
+      RenameDialogComponent,
+      { data: { name: this.project().name } },
+    );
+    const newName = await ref.afterClosed; // undefined when dismissed
+    if (newName) {
+      this.project.set({ name: newName });
+    }
+    this.result.set(newName ? `Renamed to ${newName}.` : 'Not renamed.');
+  }
+}
+```
+
+## Sizes
+
+`size` sets the dialog's width on its own scale (not `BfSize`, which is a control-height
+scale): `sm` 24 rem, `md` 32 rem (default), `lg` 48 rem, `xl` 64 rem. Each is capped at the
+viewport width minus the gutter on both sides, and the height at the viewport height minus the
+gutters; the body scrolls when the content is taller. `fullscreen` fills the viewport without a
+card radius.
+
+```ts
+import { Component, inject } from '@angular/core';
+import { BfButtonComponent } from '@bitforgehq/ui';
+import { BfDialogComponent, BfDialogRef, BfDialogService } from '@bitforgehq/ui/overlay';
+
+/** A wide report. */
+@Component({
+  selector: 'app-report-dialog',
+  imports: [BfDialogComponent, BfButtonComponent],
+  template: `
+    <bf-dialog title="Quarterly report">
+      <p>Revenue grew in every region; the details follow in the full report.</p>
+      <div bfSlot="footer"><bf-button (clicked)="ref.close()">Close</bf-button></div>
+    </bf-dialog>
+  `,
+})
+export class ReportDialogComponent {
+  protected readonly ref = inject(BfDialogRef);
+}
+
+/** A full-screen editor. */
+@Component({
+  selector: 'app-editor-dialog',
+  imports: [BfDialogComponent, BfButtonComponent],
+  template: `
+    <bf-dialog title="Edit the brief">
+      <p>A full-screen dialog fills the viewport, without a card radius.</p>
+      <div bfSlot="footer"><bf-button (clicked)="ref.close()">Done</bf-button></div>
+    </bf-dialog>
+  `,
+})
+export class EditorDialogComponent {
+  protected readonly ref = inject(BfDialogRef);
+}
+
+/** A large dialog and a full-screen dialog. */
+@Component({
+  selector: 'app-example-dialog-sizes',
+  imports: [BfButtonComponent],
+  template: `
+    <div class="flex flex-wrap gap-2">
+      <bf-button variant="outline" (clicked)="dialogs.open(report, { size: 'lg' })"
+        >Large</bf-button
+      >
+      <bf-button variant="outline" (clicked)="dialogs.open(editor, { size: 'fullscreen' })"
+        >Full screen</bf-button
+      >
+    </div>
+  `,
+})
+export class DialogSizesExampleComponent {
+  protected readonly dialogs = inject(BfDialogService);
+  protected readonly report = ReportDialogComponent;
+  protected readonly editor = EditorDialogComponent;
+}
+```
+
+## Header, body and footer
+
+`title` renders as the `h2` the dialog is labelled by. Anything with `bfSlot="header"` sits
+after the title in the header row (a status chip, a step count). The default slot is the body;
+`bfSlot="footer"` is an end-aligned row of actions that wraps on narrow screens. The close button
+(×) at the top end closes with no result; hide it with `[closeButton]="false"` when the footer
+has a cancel action.
+
+```ts
+import { Component, inject, signal } from '@angular/core';
+import { BfBadgeComponent, BfButtonComponent } from '@bitforgehq/ui';
+import { BfDialogComponent, BfDialogRef, BfDialogService } from '@bitforgehq/ui/overlay';
+
+/** A dialog with a header badge, a body and footer actions, and no close button. */
+@Component({
+  selector: 'app-invite-dialog',
+  imports: [BfBadgeComponent, BfButtonComponent, BfDialogComponent],
+  template: `
+    <bf-dialog title="Invite people" [closeButton]="false">
+      <bf-badge bfSlot="header">Step 2 of 3</bf-badge>
+      <p>Add the people who work on this project.</p>
+      <div bfSlot="footer">
+        <bf-button variant="outline" (clicked)="ref.close()">Back</bf-button>
+        <bf-button (clicked)="ref.close('next')">Next</bf-button>
+      </div>
+    </bf-dialog>
+  `,
+})
+export class InviteDialogComponent {
+  protected readonly ref = inject<BfDialogRef<string>>(BfDialogRef);
+}
+
+/**
+ * The header, body and footer of a dialog.
+ *
+ * The title and a step badge in the header, the body text, then Back and Next in the footer.
+ */
+@Component({
+  selector: 'app-example-dialog-sections',
+  imports: [BfButtonComponent],
+  template: `
+    <div class="flex flex-col items-start gap-3">
+      <bf-button (clicked)="invite()">Invite people</bf-button>
+      <p aria-live="polite" class="text-caption text-text-muted">{{ result() }}</p>
+    </div>
+  `,
+})
+export class DialogSectionsExampleComponent {
+  private readonly dialogs = inject(BfDialogService);
+  protected readonly result = signal('');
+
+  protected async invite(): Promise<void> {
+    const step = await this.dialogs.open<InviteDialogComponent, unknown, string>(
+      InviteDialogComponent,
+    ).afterClosed;
+    this.result.set(step === 'next' ? 'On to step 3.' : 'Back to step 1.');
+  }
+}
+```
+
+## Template dialogs
+
+A template opens with the same options. Its context is `{ $implicit: ref, data }`.
+
+```ts
+import { Component, type TemplateRef, inject, viewChild } from '@angular/core';
+import { BfButtonComponent } from '@bitforgehq/ui';
+import {
+  BfDialogComponent,
+  BfDialogService,
+  type BfDialogTemplateContext,
+} from '@bitforgehq/ui/overlay';
+
+/**
+ * A dialog from a template.
+ *
+ * The `ng-template` receives `{ $implicit: ref, data }`; `open()` takes the same options as for a
+ * component.
+ */
+@Component({
+  selector: 'app-example-dialog-template',
+  imports: [BfButtonComponent, BfDialogComponent],
+  template: `
+    <bf-button variant="outline" (clicked)="open()">Keyboard shortcuts</bf-button>
+
+    <ng-template #shortcuts let-ref let-data="data">
+      <bf-dialog title="Keyboard shortcuts">
+        <p>{{ data.hint }}</p>
+        <div bfSlot="footer"><bf-button (clicked)="ref.close()">Got it</bf-button></div>
+      </bf-dialog>
+    </ng-template>
+  `,
+})
+export class DialogTemplateExampleComponent {
+  private readonly dialogs = inject(BfDialogService);
+  readonly shortcuts =
+    viewChild.required<TemplateRef<BfDialogTemplateContext<{ hint: string }>>>('shortcuts');
+
+  open(): void {
+    this.dialogs.open(this.shortcuts(), { size: 'sm', data: { hint: 'Press ? anywhere.' } });
+  }
+}
+```
+
+## Confirmations
+
+`confirm()` opens an alert dialog with a title, an optional message and a row of buttons, and
+resolves with the pressed button's `id` (its `label` when it has no id). Buttons render in order,
+right-aligned: a `cancel`-role button is `outline`, a `destructive` one `danger`, the first plain
+one `primary`, further plain ones `tonal`. Without `buttons` it shows Cancel and OK from
+`provideBfLabels()` (ids `cancel` and `ok`). `size` is `sm` (default) or `md`.
+
+```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.');
+  }
+}
+```
+
+## Results
+
+`BfDialogRef<R, C>` carries the result type `R` and the content type `C`. `close(result)`
+resolves `afterClosed` with it; `Escape`, a backdrop click, the close button and a navigation
+resolve `undefined`. `closed()` turns true once the dialog is gone, and `componentInstance` is the
+content component (`null` for a template).
+
+```ts
+import { Component, inject, signal } from '@angular/core';
+import { BfButtonComponent, BfCheckboxComponent } from '@bitforgehq/ui';
+import {
+  BF_DIALOG_DATA,
+  BfDialogComponent,
+  BfDialogRef,
+  BfDialogService,
+} from '@bitforgehq/ui/overlay';
+
+/** The filters a list shows. */
+export interface Filters {
+  open: boolean;
+  mine: boolean;
+}
+
+/** A filter dialog that returns the edited filters and can highlight one of them. */
+@Component({
+  selector: 'app-filter-dialog',
+  imports: [BfButtonComponent, BfCheckboxComponent, BfDialogComponent],
+  template: `
+    <bf-dialog title="Filters">
+      <div class="flex flex-col gap-2">
+        <bf-checkbox
+          label="Open tasks only"
+          [class]="highlighted() === 'status' ? 'bg-primary-soft rounded-field' : ''"
+          [(checked)]="open"
+        />
+        <bf-checkbox label="Assigned to me" [(checked)]="mine" />
+      </div>
+      <div bfSlot="footer">
+        <bf-button variant="outline" (clicked)="ref.close()">Cancel</bf-button>
+        <bf-button (clicked)="ref.close({ open: open(), mine: mine() })">Apply</bf-button>
+      </div>
+    </bf-dialog>
+  `,
+})
+export class FilterDialogComponent {
+  protected readonly ref = inject<BfDialogRef<Filters>>(BfDialogRef);
+  private readonly current = inject<Filters>(BF_DIALOG_DATA);
+  protected readonly open = signal(this.current.open);
+  protected readonly mine = signal(this.current.mine);
+  protected readonly highlighted = signal('');
+
+  highlight(field: string): void {
+    this.highlighted.set(field);
+  }
+}
+
+/**
+ * A typed dialog result.
+ *
+ * `BfDialogRef<Filters, FilterDialogComponent>` types both the result and `componentInstance`;
+ * a dismissed dialog keeps the current filters.
+ */
+@Component({
+  selector: 'app-example-dialog-results',
+  imports: [BfButtonComponent],
+  template: `
+    <div class="flex flex-col items-start gap-3">
+      <bf-button variant="outline" (clicked)="edit()">Filters…</bf-button>
+      <p class="text-caption text-text-muted">
+        {{ filters().open ? 'Open' : 'All' }} tasks · {{ filters().mine ? 'mine' : 'everyone' }}
+      </p>
+    </div>
+  `,
+})
+export class DialogResultsExampleComponent {
+  private readonly dialogs = inject(BfDialogService);
+  protected readonly filters = signal<Filters>({ open: true, mine: false });
+
+  protected async edit(): Promise<void> {
+    const current = this.filters();
+    const ref = this.dialogs.open<FilterDialogComponent, Filters, Filters>(FilterDialogComponent, {
+      data: current,
+    });
+    ref.componentInstance?.highlight('status');
+    this.filters.set((await ref.afterClosed) ?? current);
+  }
+}
+```
+
+## Focus and dismissal
+
+Focus moves to the element marked `autofocus` (or `cdkFocusInitial`) — itself when it is
+focusable (a control, or an element with a `tabindex`, also `-1` for a region to start reading
+at), else the first control inside it — else the first field or button in the body, never the ×,
+which comes last in the tab order. `autoFocus: 'panel'` focuses the dialog itself, so a screen
+reader starts at the top of a long text. `Escape` closes the dialog unless
+`dismissOnEscape: false`; a backdrop click closes a `dialog` unless `dismissOnBackdrop: false`,
+and never an `alertdialog`. In a browser with `CloseWatcher` (Chrome on Android, a PWA), Android
+back closes the dialog the same way as `Escape` and leaves the URL alone; with
+`dismissOnEscape: false` the dialog swallows it and stays open. A desktop browser's Back button is
+no close request: it navigates, and the navigation closes the dialog. On close, focus returns to the element that opened it
+(`restoreFocus: false` to skip); when that element is gone, to the topmost dialog still open,
+else it stays on the page body. After a destructive `confirm()` that removes the opener (a
+deleted row), move focus yourself to a logical place, such as the next row or the list's
+heading. An `alertdialog` you open yourself (`open(…, { role: 'alertdialog' })`) needs
+`ariaDescribedBy` pointing at its message; `confirm()` wires it for you. The service is a root
+singleton: pass
+`injector: inject(Injector)` so a feature-level `provideBfLabels()` names the close button
+(`close`) and the fallback (`dialog`).
+
+```ts
+import {
+  Component,
+  ElementRef,
+  Injector,
+  afterNextRender,
+  inject,
+  signal,
+  viewChildren,
+} from '@angular/core';
+import { BfButtonComponent } from '@bitforgehq/ui';
+import { BfDialogComponent, BfDialogRef, BfDialogService } from '@bitforgehq/ui/overlay';
+
+/** Focuses the native button inside a `bf-button` host (a type guard, not an assertion). */
+function focusButtonIn(host: unknown): void {
+  if (host instanceof HTMLElement) {
+    host.querySelector('button')?.focus();
+  }
+}
+
+/** Terms that must be answered: an alert dialog described by its text. */
+@Component({
+  selector: 'app-terms-dialog',
+  imports: [BfButtonComponent, BfDialogComponent],
+  template: `
+    <bf-dialog title="Updated terms" [closeButton]="false">
+      <p id="terms-text">We changed how long we keep deleted projects: 30 days instead of 7.</p>
+      <div bfSlot="footer"><bf-button (clicked)="ref.close(true)">Accept</bf-button></div>
+    </bf-dialog>
+  `,
+})
+export class TermsDialogComponent {
+  protected readonly ref = inject<BfDialogRef<boolean>>(BfDialogRef);
+}
+
+/**
+ * Initial focus, dismissal and focus after a deletion.
+ *
+ * The terms open as an `alertdialog` that starts reading at the panel and ignores `Escape`. Each
+ * row's Delete confirms first; the deleted row opened the dialog, so focus moves to the next row.
+ */
+@Component({
+  selector: 'app-example-dialog-focus',
+  imports: [BfButtonComponent],
+  template: `
+    <div class="flex flex-col items-start gap-3">
+      <bf-button variant="outline" (clicked)="showTerms()">Show the terms</bf-button>
+      <ul class="flex flex-col gap-2 self-stretch">
+        @for (row of rows(); track row) {
+          <li class="flex items-center justify-between gap-3">
+            <span class="text-body">{{ row }}</span>
+            <bf-button #rowButton variant="text" size="sm" (clicked)="remove(row)"
+              >Delete {{ row }}</bf-button
+            >
+          </li>
+        }
+      </ul>
+    </div>
+  `,
+})
+export class DialogFocusExampleComponent {
+  private readonly dialogs = inject(BfDialogService);
+  private readonly injector = inject(Injector);
+  private readonly rowButtons = viewChildren('rowButton', {
+    read: ElementRef,
+  });
+  protected readonly rows = signal(['Brief', 'Moodboard', 'Deck']);
+
+  protected showTerms(): void {
+    this.dialogs.open(TermsDialogComponent, {
+      role: 'alertdialog',
+      ariaDescribedBy: 'terms-text',
+      autoFocus: 'panel',
+      dismissOnEscape: false,
+      injector: this.injector,
+    });
+  }
+
+  protected async remove(row: string): Promise<void> {
+    const answer = await this.dialogs.confirm({
+      title: `Delete ${row}?`,
+      buttons: [
+        { id: 'cancel', label: 'Cancel', role: 'cancel' },
+        { id: 'delete', label: 'Delete', role: 'destructive' },
+      ],
+    });
+    if (answer === 'delete') {
+      // After a destructive confirmation, focus the next row: the deleted one opened the dialog.
+      const next = this.rows().indexOf(row);
+      this.rows.update((rows) => rows.filter((r) => r !== row));
+      afterNextRender(
+        () => {
+          const buttons = this.rowButtons();
+          const target = buttons[next] ?? buttons.at(-1);
+          focusButtonIn(target?.nativeElement);
+        },
+        { injector: this.injector },
+      );
+    }
+  }
+}
+```
+
+## Navigation
+
+A navigation to another URL path closes the dialog: a router navigation (a link inside it, a
+redirect after a save, a deep link) and the browser's back and forward buttons. `afterClosed`
+resolves `undefined`; `confirm()` resolves the cancel button's answer, else `undefined`. A query-
+or fragment-only change (a tab kept in `?tab=`) leaves it open. It listens through `Location` from
+`@angular/common`, so it works with or without `@angular/router`. A `confirm()` opened from a
+`canDeactivate` guard stays open: the path it records is the one the guard runs on. Focus
+returns to the opener when it is still in the page, as on any close. Pass
+`closeOnNavigation: false` for a dialog that outlives its page, such as one that walks through
+several routes.
+
+```ts
+import { Component, inject } from '@angular/core';
+import { BfButtonComponent } from '@bitforgehq/ui';
+import { BfDialogComponent, BfDialogRef, BfDialogService } from '@bitforgehq/ui/overlay';
+
+/** A setup wizard that walks through several routes, so it outlives a navigation. */
+@Component({
+  selector: 'app-setup-wizard',
+  imports: [BfButtonComponent, BfDialogComponent],
+  template: `
+    <bf-dialog title="Set up your workspace">
+      <p>This dialog stays open while the page behind it changes.</p>
+      <div bfSlot="footer"><bf-button (clicked)="ref.close()">Finish</bf-button></div>
+    </bf-dialog>
+  `,
+})
+export class SetupWizardComponent {
+  protected readonly ref = inject(BfDialogRef);
+}
+
+/** A dialog that stays open across navigations. */
+@Component({
+  selector: 'app-example-dialog-navigation',
+  imports: [BfButtonComponent],
+  template: `<bf-button variant="outline" (clicked)="open()">Start the setup</bf-button>`,
+})
+export class DialogNavigationExampleComponent {
+  private readonly dialogs = inject(BfDialogService);
+
+  protected open(): void {
+    this.dialogs.open(SetupWizardComponent, { closeOnNavigation: false });
+  }
+}
+```
+
+A matrix-parameter change (`/projects;view=grid`) is a path change and closes it. A
+`history.pushState()` made outside Angular's `Location` is not seen and does not. A dialog opened
+before the first navigation ends (from the root component or an `APP_INITIALIZER`) closes when
+the start URL redirects (`''` to `'projects'`): open it after the first `NavigationEnd`, or pass
+`closeOnNavigation: false`.
+
+A route `canDeactivate` guard protects a dialog's unsaved input only against in-app navigations:
+the dialog stays open while the guard's `confirm()` asks. The browser's back and forward buttons
+change the URL before the guard runs, so the dialog has already closed when "Stay" is answered. A
+dialog that must keep its draft passes `closeOnNavigation: false` or saves the draft as it
+changes.
+
+```ts
+import { Component, inject, signal } from '@angular/core';
+import { type CanDeactivateFn } from '@angular/router';
+import { BfTextareaComponent } from '@bitforgehq/ui';
+import { BfDialogService } from '@bitforgehq/ui/overlay';
+
+/** Asks before the editor's unsaved changes are lost; `true` lets the navigation go on. */
+export const unsavedChanges: CanDeactivateFn<DialogGuardExampleComponent> = async (page) =>
+  !page.dirty() ||
+  (await inject(BfDialogService).confirm({
+    title: 'Discard changes?',
+    buttons: [
+      { id: 'stay', label: 'Stay', role: 'cancel' },
+      { id: 'discard', label: 'Discard', role: 'destructive' },
+    ],
+  })) === 'discard';
+
+/**
+ * A route guard that asks before unsaved changes are lost.
+ *
+ * `unsavedChanges` goes on the editor's route:
+ * `{ path: 'editor', component: DialogGuardExampleComponent, canDeactivate: [unsavedChanges] }`.
+ * The `confirm()` it opens stays open while the guard waits for the answer.
+ *
+ * @preview none
+ */
+@Component({
+  selector: 'app-example-dialog-guard',
+  imports: [BfTextareaComponent],
+  template: `<bf-textarea label="Draft" [value]="draft()" (valueChange)="edit($event)" />`,
+})
+export class DialogGuardExampleComponent {
+  readonly draft = signal('');
+  readonly dirty = signal(false);
+
+  protected edit(text: string): void {
+    this.draft.set(text);
+    this.dirty.set(true);
+  }
+}
+```
+
+## Desktop
+
+Built for desktop: a centred card over a backdrop, at `sm` 24 rem to `xl` 64 rem wide, or `fullscreen`. By default a backdrop click closes a `dialog` and leaves an `alertdialog` open; `dismissOnBackdrop` overrides either. The page behind is inert and does not scroll, so the mouse wheel scrolls only the dialog body. The close button (×) is a `text` icon button: hover tints it, and its ring shows on keyboard focus only. The footer buttons follow `provideBfDefaults()` like any `bf-button`.
+
+## Theming
+
+- Card: `bg-surface`, `text-text`, `rounded-card` (`--radius-card`), `shadow-floating`; widths
+  24/32/48/64 rem capped at `100vw - 2 × --spacing-gutter`, height capped at
+  `100dvh - 2 × --spacing-gutter`. `fullscreen` has no radius or shadow.
+- Title: `text-heading`; body padding `px-6 py-4`, header `px-6 pt-6`, footer `px-6 pb-6`
+  with `gap-2` between actions.
+- Close button: a `text` `bf-icon-button` (`sm`) with a lucide `X`.
+- Backdrop: `bf-overlay-backdrop` from the overlay core (a black scrim: 40 % in light mode, 60 %
+  in dark).
+- Confirm message: `text-body text-text-secondary`.
+
+## Accessibility
+
+The overlay panel is `role="dialog"` (or `alertdialog`) with `aria-modal="true"` and
+a name: `ariaLabel` when given; else `aria-labelledby` pointing at the `bf-dialog` title; else
+the first heading in the content; else the `dialog` label ("Dialog"). It never points
+`aria-labelledby` at a missing element, and its ids come from the library's shared counter, so
+they never repeat one in the page. `confirm()` is an `alertdialog` whose
+`aria-describedby` points at the message, with initial focus on the cancel button (the least
+destructive action), else the first button.
+
+On open, focus moves into the dialog; Tab and Shift+Tab cycle inside it (the CDK focus trap), and
+a press on the backdrop never moves it out (a `confirm()` stays open with focus on its button); on
+close it returns to the opener (to the topmost dialog still open when the opener is gone). While it is open the page behind it is `inert` (every other child
+of `<body>`; under `provideBfShell()` the page stack) and the document does not scroll. Nested
+dialogs stack: `Escape` closes only the top one. When the body overflows, it becomes focusable
+(`tabindex="0"`, a `role="region"` labelled by the title when there is one), so keyboard users
+can scroll it with the arrow keys. Under
+`prefers-reduced-motion` the dialog cross-fades instead of scaling.
+
+### Keyboard
+
+| Key                                              | Action                                                                         |
+| ------------------------------------------------ | ------------------------------------------------------------------------------ |
+| <kbd>Tab</kbd> / <kbd>Shift</kbd>+<kbd>Tab</kbd> | Next / previous focusable element, wrapping inside the dialog                  |
+| <kbd>Escape</kbd>                                | Closes the dialog (a confirmation: answers with its cancel button, or nothing) |
+| <kbd>Enter</kbd> / <kbd>Space</kbd>              | Activates the focused button                                                   |
+
+## Inputs
+
+| Name          | Type      | Default | Description                                                                              |
+| ------------- | --------- | ------- | ---------------------------------------------------------------------------------------- |
+| `title`       | `string`  | `''`    | Heading of the dialog, rendered as the `h2` the dialog panel is labelled by.             |
+| `closeButton` | `boolean` | `true`  | Shows a close button (×) at the top end that closes the dialog with no result.           |
+| `closeLabel`  | `string`  | `''`    | Accessible name of the close button; empty uses `provideBfLabels()`'s `close` ("Close"). |
+
+## Slots
+
+- `header`: More header content after the title, such as a status badge.
+- `default`: The dialog body.
+- `footer`: The actions, aligned at the end.
+
+## Notes
+
+### Do
+
+- Give every dialog a `title`, and word the primary action as the verb ("Save", "Delete").
+- Put the cancel action first in the footer and the primary action last.
+- Use `confirm()` for a yes/no decision and `role: 'destructive'` on the action that loses data.
+- Pass `injector: inject(Injector)` when the opener sits under its own `provideBfLabels()`.
+
+### Don't
+
+- Don't open a dialog for information that fits inline (a `bf-alert`) or a transient status (a
+  toast).
+- Don't nest more than two dialogs; finish or close the first one instead.
+- Don't make a form dialog an `alertdialog` just to block the backdrop; pass
+  `dismissOnBackdrop: false`.
+- Don't use `/mobile` sheets or modals on desktop pages; they are phone presentations.
+
+## Migration notes
+
+### 0.3.0
+
+New exported `BfConfirmSize` (`'sm' | 'md'`), the type of `BfConfirmOptions.size`,
+`BfDialogRole` (`'dialog' | 'alertdialog'`), the type of `BfDialogConfig.role`, and
+`BfConfirmButtonRole` (`'cancel' | 'destructive'`), the type of `BfConfirmButton.role`;
+`BfDialogConfig` `autoFocus` takes the new `BfOverlayAutoFocus`.
+
+New `bf-dialog` and `BfDialogService` in `@bitforgehq/ui/overlay`: a centred modal dialog for
+desktop and web apps with no Capacitor dependency. `open(component | template, config)` returns
+a typed `BfDialogRef<R, C>` (`afterClosed`, `closed()`, `componentInstance`, `close(result)`);
+the content injects `BfDialogRef` and `BF_DIALOG_DATA`, a template gets `{ $implicit: ref, data }`.
+`BfDialogConfig`: `data`, `size` (`sm` 24, `md` 32 (default), `lg` 48, `xl` 64 rem, capped at the
+viewport minus the gutters, or `fullscreen`), `role` (`dialog`/`alertdialog`), `ariaLabel`,
+`ariaDescribedBy`, `dismissOnBackdrop` (default true for `dialog`, false for `alertdialog`),
+`dismissOnEscape`, `autoFocus`, `restoreFocus`, `panelClass`, `injector`. `bf-dialog` lays out a
+`title` (the `h2` the panel is labelled by), `[bfSlot=header]`, a scrolling body (focusable only
+while it overflows, then a region named by the title when there is one) and an end-aligned
+`[bfSlot=footer]`, with a close button (`closeButton`, `closeLabel`, default the `close` label)
+last in the tab order. `confirm({ title, message?, buttons?, size?, injector? })` opens an alert
+dialog and resolves with the pressed button's `id ?? label` (default buttons Cancel and OK, ids
+`cancel` and `ok`); focus starts on the cancel button, `Escape` answers with it or is ignored
+without one. A navigation to another URL path closes a dialog with no result and a `confirm()`
+with the cancel button's answer (else `undefined`); `closeOnNavigation: false` (on `BfDialogConfig`
+and `confirm()`) keeps it open. Title and message ids come from the library's shared id counter,
+so they never repeat an id of a `bf-dialog` rendered in the page. Focus is trapped and restored,
+the page behind is `inert` and document scroll is locked (APG dialog (modal) and alert dialog
+patterns).
+
+JSDoc of `dialog-ref.ts` for the API reference: `@summary`/`@since` on the exported symbols;
+`@param` docs. No behaviour change.
+
+JSDoc of `dialog.component.ts` for the API reference: `@slot` docs for `header`, `default`,
+`footer`. No behaviour change.
+
+JSDoc of `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 `bf-dialog` host carries `data-bf-dialog-id` (its title id, also without a rendered title), so
+`BfDialogHarness` finds the overlay panel the card sits in, also under a stacked dialog.
+
+The docs say that Android back in a browser with `CloseWatcher` closes the dialog like `Escape`
+(and that `dismissOnEscape: false` swallows it); see `### overlay core` and Migration 35.