@bitforgehq/ui 0.3.0

package/ai/components/sheet.md

@@ -0,0 +1,845 @@
+# bf-sheet
+
+Bottom sheet with snap points, drag to dismiss and a backdrop
+
+`BfSheetComponent` from `@bitforgehq/ui/mobile` · Overlays · since 0.2.0
+
+## Example
+
+```ts
+import { Component, inject, signal } from '@angular/core';
+import { BfButtonComponent } from '@bitforgehq/ui';
+import {
+  BfContentComponent,
+  BfHeaderComponent,
+  BfPageComponent,
+  BfSheetService,
+} from '@bitforgehq/ui/mobile';
+import { ShowcaseSheetComponent } from './showcase-sheet.component';
+
+/** Snap points of the showcase sheet: half the screen, then almost all of it. */
+export const SHOWCASE_SHEET_SNAP_POINTS = [0.5, 0.92];
+
+/** `bf-sheet` showcase: a button opens a form in a bottom sheet with two snap points. */
+@Component({
+  selector: 'app-sheet-showcase',
+  imports: [BfPageComponent, BfHeaderComponent, BfContentComponent, BfButtonComponent],
+  template: `
+    <bf-page data-showcase="sheet">
+      <bf-header title="Sheet" [largeTitle]="false" />
+      <bf-content>
+        <div class="flex flex-col gap-4 p-4">
+          <p class="text-caption text-text-muted">
+            Drag the grabber between the two snap points; drag it down or flick to close, or tap the
+            backdrop.
+          </p>
+          <bf-button (clicked)="open()">Open sheet</bf-button>
+          <p data-showcase-result class="text-body">{{ result() }}</p>
+        </div>
+      </bf-content>
+    </bf-page>
+  `,
+})
+export class SheetShowcasePage {
+  private readonly sheets = inject(BfSheetService);
+
+  protected readonly result = signal('No list yet.');
+
+  async open(): Promise<void> {
+    const ref = this.sheets.open<ShowcaseSheetComponent, string>(ShowcaseSheetComponent, {
+      snapPoints: SHOWCASE_SHEET_SNAP_POINTS,
+      ariaLabel: 'New list',
+    });
+    const name = await ref.afterClosed;
+    this.result.set(name ? `Created “${name}”.` : 'Dismissed.');
+  }
+}
+```
+
+## Overview
+
+The bottom-sheet container that `BfSheetService.open()` renders on the overlay core: a
+bottom-anchored `bg-surface` card with a grabber, resting at snap points (fractions of the
+viewport height, applied as `--bf-sheet-height`) and rendering the content component or
+template with `BF_OVERLAY_DATA` and `BfSheetRef` injectable. Dragging the handle row, any
+element marked `data-bf-sheet-drag` (a header) or the content (unless it can scroll up) moves
+the sheet with Pointer Events under pointer capture: rubber-banded above the top point, released
+onto the nearest point (a fling faster than 0.3 px/ms picks the direction), and dismissed when
+released more than 25 % below the lowest point or flung down from it — if the sheet is
+dismissible. The content scrolls only at the top snap point, and at every point while the soft
+keyboard is up. While the keyboard overlays the sheet's bottom edge (iOS, a mobile browser) the
+sheet is lifted by the covered height (`translate`, its bottom safe-area padding dropped); while
+the keyboard is up its height is capped at the keyboard's top edge minus the safe-area top minus
+8 px (a drag starts from that capped height), and the content region's `bfKeyboardAssist`
+scrolls the focused control 24 px clear of the keyboard. The lift follows the keyboard (250 ms,
+instant under `prefers-reduced-motion`). Hiding the keyboard restores the snap height at once
+(the drop is instant, so the top edge stays on screen) and scrolls content left scrolled below
+the top point back to its top. With two or more snap points the grabber is a button: a press,
+`Enter` or `Space` moves one point up (from the top point back to the lowest), the arrow keys
+step, `Home` and `End` jump; it is named `expand` or `collapse` (`BF_LABELS`) after the next
+press, then `sheetPosition`, and every settle on another point announces `sheetPosition`
+politely. A dismissible sheet starts with a visually hidden Close (`BF_LABELS.close`) that screen
+readers reach and a keyboard user sees when focused. Not used directly in templates.
+
+A bottom sheet. `BfSheetService.open(content, options)` renders a component or template in a
+`bf-sheet` container — a bottom-anchored card with a grabber, over a backdrop — that rests at snap
+points given as fractions of the viewport height. Drag the grabber (or a header marked
+`data-bf-sheet-drag`) to move between them; drag it far enough down, or flick it, and it closes.
+The content reads its data from `BF_OVERLAY_DATA` and closes itself with a result through the
+injected `BfSheetRef`. You never place `<bf-sheet>` in a template yourself.
+
+## When to use
+
+Use `BfSheetService` in the Capacitor shell for secondary content over the current page that the user drags between heights or away: a filter panel, a detail preview. Use [BfModalService](https://bitforge-ui.web.app/api/bf-modal-service) instead for a full task that closes itself, [BfActionSheetService](https://bitforge-ui.web.app/api/bf-action-sheet-service) for a list of actions, and [BfDialogService](https://bitforge-ui.web.app/api/bf-dialog-service) on desktop.
+
+## Basic usage
+
+The content is an ordinary standalone component. It injects the data passed as `data` and the
+`BfSheetRef`, and closes with a result; the caller awaits `afterClosed`.
+
+```ts
+import { Component, inject, signal } from '@angular/core';
+import { BfButtonComponent, BfInputComponent } from '@bitforgehq/ui';
+import { BfSheetRef, BfSheetService } from '@bitforgehq/ui/mobile';
+import { BF_OVERLAY_DATA } from '@bitforgehq/ui/overlay';
+
+/** A task as the sheet creates it. */
+export interface Task {
+  title: string;
+}
+
+/** The sheet: a draggable header, a field and Save. */
+@Component({
+  selector: 'app-new-task',
+  imports: [BfButtonComponent, BfInputComponent],
+  template: `
+    <header data-bf-sheet-drag class="text-heading px-4 pb-2">
+      New task in {{ data.listName }}
+    </header>
+    <div class="flex flex-col gap-3 px-4">
+      <bf-input label="Title" [(value)]="title" />
+      <bf-button (clicked)="save()">Save</bf-button>
+    </div>
+  `,
+})
+export class NewTaskComponent {
+  protected readonly data = inject<{ listName: string }>(BF_OVERLAY_DATA);
+  private readonly sheet = inject<BfSheetRef<Task>>(BfSheetRef);
+  protected readonly title = signal('');
+
+  save(): void {
+    this.sheet.close({ title: this.title() || 'Buy milk' });
+  }
+}
+
+/**
+ * A sheet that creates a task.
+ *
+ * `open()` passes the list name as data and awaits the new task, or `undefined` when dismissed.
+ *
+ * @preview none
+ */
+@Component({
+  selector: 'app-example-sheet-basic',
+  imports: [BfButtonComponent],
+  template: `
+    <div class="flex flex-col items-start gap-3">
+      <bf-button (clicked)="add()">New task</bf-button>
+      <p aria-live="polite" class="text-caption text-text-muted">{{ result() }}</p>
+    </div>
+  `,
+})
+export class SheetBasicExampleComponent {
+  private readonly sheets = inject(BfSheetService);
+  protected readonly result = signal('');
+
+  protected async add(): Promise<void> {
+    const ref = this.sheets.open<NewTaskComponent, Task>(NewTaskComponent, {
+      data: { listName: 'Groceries' },
+    });
+    const task = await ref.afterClosed; // undefined when dismissed
+    this.result.set(task ? `Added "${task.title}".` : 'Dismissed.');
+  }
+}
+```
+
+A template works too; its context is `{ $implicit: ref, data }`:
+
+```ts
+import { Component, type TemplateRef, inject, signal, viewChild } from '@angular/core';
+import { BfButtonComponent } from '@bitforgehq/ui';
+import { BfSheetService } from '@bitforgehq/ui/mobile';
+
+/** The filters a list shows. */
+interface Filters {
+  open: boolean;
+}
+
+/**
+ * A sheet from a template.
+ *
+ * The `ng-template` receives `{ $implicit: ref, data }`; Apply closes the sheet with the data.
+ *
+ * @preview none
+ */
+@Component({
+  selector: 'app-example-sheet-template',
+  imports: [BfButtonComponent],
+  template: `
+    <div class="flex flex-col items-start gap-3">
+      <bf-button variant="outline" (clicked)="open()">Filters</bf-button>
+      <p class="text-caption text-text-muted">{{ result() }}</p>
+    </div>
+
+    <ng-template #filters let-ref let-data="data">
+      <div class="flex flex-col gap-3 px-4 pb-4">
+        <p class="text-heading">Filters</p>
+        <bf-button (clicked)="ref.close(data)">Apply</bf-button>
+      </div>
+    </ng-template>
+  `,
+})
+export class SheetTemplateExampleComponent {
+  private readonly sheets = inject(BfSheetService);
+  private readonly filters = viewChild.required<TemplateRef<unknown>>('filters');
+  protected readonly result = signal('');
+
+  protected async open(): Promise<void> {
+    const ref = this.sheets.open<unknown, Filters>(this.filters(), { data: { open: true } });
+    const applied = await ref.afterClosed;
+    this.result.set(applied ? 'Filters applied.' : 'Dismissed.');
+  }
+}
+```
+
+## Snap points
+
+`snapPoints` are fractions of the viewport height (the keyboard-free height from
+`BfKeyboardService.restHeight()`, else `innerHeight`), default `[0.5, 0.92]`; `initial` is the index
+the sheet opens at (default 0). The height is applied as `--bf-sheet-height` on the `bf-sheet`
+host. Move programmatically with `snapTo(index)` and read the current point from `snapIndex()`:
+
+```ts
+import { Component, computed, inject } from '@angular/core';
+import { BfButtonComponent } from '@bitforgehq/ui';
+import { BfSheetRef, BfSheetService } from '@bitforgehq/ui/mobile';
+
+/** Project details that expand to the top snap point. */
+@Component({
+  selector: 'app-details',
+  imports: [BfButtonComponent],
+  template: `
+    <div class="flex flex-col gap-3 px-4 pb-4">
+      <p data-bf-sheet-drag class="text-heading">Atlas rebrand</p>
+      @if (!expanded()) {
+        <bf-button variant="tonal" (clicked)="ref.snapTo(2)">Show everything</bf-button>
+      } @else {
+        <p class="text-body">Owner, budget, milestones and files.</p>
+      }
+    </div>
+  `,
+})
+export class DetailsComponent {
+  protected readonly ref = inject(BfSheetRef);
+  protected readonly expanded = computed(() => this.ref.snapIndex() === 2);
+}
+
+/**
+ * A sheet with three snap points.
+ *
+ * It opens at the middle point (`initial: 1`); `snapTo(2)` moves it up and `snapIndex()` tracks
+ * the current point, also after a drag.
+ *
+ * @preview none
+ */
+@Component({
+  selector: 'app-example-sheet-snap-points',
+  imports: [BfButtonComponent],
+  template: `<bf-button (clicked)="open()">Project details</bf-button>`,
+})
+export class SheetSnapPointsExampleComponent {
+  private readonly sheets = inject(BfSheetService);
+
+  protected open(): void {
+    this.sheets.open(DetailsComponent, { snapPoints: [0.3, 0.6, 0.92], initial: 1 });
+  }
+}
+```
+
+On release, a fling faster than 0.3 px/ms goes to the next point in its direction; otherwise the
+sheet settles on the nearest point. Above the top point the drag is rubber-banded (30 % of the
+pointer's travel).
+
+With two or more snap points the grabber is also a button, so the sheet can be resized without
+dragging: a tap, a click, <kbd>Enter</kbd> or <kbd>Space</kbd> moves it one point up, and from the
+top point back to the lowest; the arrow keys, <kbd>Home</kbd> and <kbd>End</kbd> step and jump
+between the points (see [Keyboard](#keyboard)). Its name says what the next press does and where
+the sheet is: `provideBfLabels()`'s `expand` ("Expand") below the top point, `collapse`
+("Collapse") at it, then `sheetPosition(position, count)` ("Sheet at 1 of 2"). Each time the sheet
+settles on another snap point, however it got there (the button, a key, a drag or `snapTo()`),
+`sheetPosition` is announced politely through CDK `LiveAnnouncer`. With a single snap point the
+grabber is decorative, there is no button and nothing is announced.
+
+## Focus on open
+
+A sheet opens with focus on itself (`autoFocus: 'panel'`, the default): the panel is a named
+`role="dialog"` with `tabindex="-1"`, so a screen reader starts reading inside the sheet and no soft
+keyboard comes up to cover it (on Android, focusing a text field on open raises the keyboard at
+once). Tab moves on to the sheet's controls. Pass `autoFocus: 'first-field'` when the sheet exists
+to be typed into (a quick-add field): focus goes to the element marked `autofocus` (or
+`cdkFocusInitial`), else to the first focusable element of the content, never to the sheet's own
+Close and grabber, and the keyboard comes up with the sheet.
+
+```ts
+import { Component, inject, signal } from '@angular/core';
+import { BfButtonComponent, BfInputComponent } from '@bitforgehq/ui';
+import { BfSheetRef, BfSheetService } from '@bitforgehq/ui/mobile';
+
+/** A quick-add sheet whose only job is typing a title. */
+@Component({
+  selector: 'app-quick-add',
+  imports: [BfButtonComponent, BfInputComponent],
+  template: `
+    <div class="flex flex-col gap-3 px-4">
+      <h2 class="text-heading">Quick add</h2>
+      <bf-input label="Title" [(value)]="title" />
+      <bf-button (clicked)="save()">Add</bf-button>
+    </div>
+  `,
+})
+export class QuickAddComponent {
+  private readonly sheet = inject<BfSheetRef<string>>(BfSheetRef);
+  protected readonly title = signal('');
+
+  save(): void {
+    this.sheet.close(this.title());
+  }
+}
+
+/**
+ * A sheet that opens with the keyboard up.
+ *
+ * By default a sheet focuses itself, so no soft keyboard hides it; `autoFocus: 'first-field'`
+ * focuses the Title field instead (or the element marked `autofocus`).
+ *
+ * @preview none
+ */
+@Component({
+  selector: 'app-example-sheet-autofocus',
+  imports: [BfButtonComponent],
+  template: `
+    <div class="flex flex-col items-start gap-3">
+      <bf-button (clicked)="quickAdd()">Quick add</bf-button>
+      <p aria-live="polite" class="text-caption text-text-muted">{{ result() }}</p>
+    </div>
+  `,
+})
+export class SheetAutofocusExampleComponent {
+  private readonly sheets = inject(BfSheetService);
+  protected readonly result = signal('');
+
+  protected async quickAdd(): Promise<void> {
+    const ref = this.sheets.open<QuickAddComponent, string>(QuickAddComponent, {
+      snapPoints: [0.92],
+      autoFocus: 'first-field',
+    });
+    const title = await ref.afterClosed;
+    this.result.set(title ? `Added "${title}".` : 'Dismissed.');
+  }
+}
+```
+
+The sheet provides its content a fresh `BfPageContext` (with `mainLandmark` false), so a
+`bf-content` inside it is no second `main` and never takes over the page's scroller, also when
+the sheet is opened with the page's injector.
+
+Action sheets and modals are unchanged: `BfActionSheetService` and `BfModalService` keep the
+focus they had: an action sheet starts on its Cancel button, and a modal on the first focusable
+element of its content.
+
+## Dragging and scrolling
+
+The 24 px handle row always drags the sheet; mark any other element (typically the header of your
+content) with `data-bf-sheet-drag` to make it a drag handle too — give it `cursor-grab
+active:cursor-grabbing` as well, so its pointer affordance matches the handle row's. A press only
+becomes a drag after 6 px of vertical travel, so buttons inside a header still get their clicks.
+The same holds on the grabber button: a press released within 6 px is a click (it cycles the snap
+points), a longer one drags the sheet and does not.
+
+The content scrolls only at the top snap point (`overflow-y-auto` there, `overflow-hidden` below
+it, always `overscroll-contain`) — and at every point while the soft keyboard is up. Below the top
+point, dragging the content moves the sheet; at the top point, a downward drag on the content
+moves the sheet only once the content is scrolled to the top — the same hand-off as iOS and Ionic
+sheets.
+
+## Soft keyboard
+
+A sheet keeps its focused field and its actions above the soft keyboard:
+
+- **Lift.** Where the keyboard overlays the page (iOS with `Keyboard.resize: 'none'`, a mobile
+  browser), the sheet moves up by the covered height while the keyboard is up, and drops its
+  bottom safe-area padding (the keyboard covers the home indicator). It slides up with the
+  keyboard (250 ms, instant under `prefers-reduced-motion`); when it arrives, the content's
+  keyboard assist measures again. On Android the WebView itself shrinks above the keyboard, so
+  there is nothing to lift.
+- **Cap.** While the keyboard is up, the sheet is at most as tall as the space between the
+  keyboard's top edge and the safe-area top, minus 8 px — in phone landscape that can be less than
+  its snap height. A drag starts from that capped height.
+- **Scroll and reveal.** While the keyboard is up the content scrolls at every snap point, and its
+  keyboard assist (`bfKeyboardAssist`) scrolls the focused field 24 px above the keyboard.
+- **Restore.** Hiding the keyboard removes the lift and the cap together, at once: the sheet
+  rests at its snap height again with its top edge on screen throughout, and content left
+  scrolled below the top point starts at its top again.
+
+The snap heights themselves never change. Keep the primary action close below
+the fields, so the lifted sheet shows it without scrolling in portrait.
+
+## Dismissible
+
+By default a backdrop tap, `Escape`, the hardware back button and a release more than 25 % of the
+lowest point's height below it (or a downward fling from it) close the sheet, resolving
+`afterClosed` with `undefined`. With `dismissible: false` only `close()` does: the backdrop and
+`Escape` are ignored, a downward drag rubber-bands and settles back, and the hardware back button
+is swallowed while the sheet is open (it does not fall through to the page behind).
+
+```ts
+import { Component, inject } from '@angular/core';
+import { BfButtonComponent } from '@bitforgehq/ui';
+import { BfSheetRef, BfSheetService } from '@bitforgehq/ui/mobile';
+
+/** Terms that must be accepted. */
+@Component({
+  selector: 'app-terms-sheet',
+  imports: [BfButtonComponent],
+  template: `
+    <div class="flex flex-col gap-3 p-4">
+      <p class="text-body">Accept the updated terms to continue.</p>
+      <bf-button (clicked)="ref.close()">Done</bf-button>
+    </div>
+  `,
+})
+export class TermsComponent {
+  protected readonly ref = inject(BfSheetRef);
+}
+
+/**
+ * A sheet that must be answered.
+ *
+ * `dismissible: false` turns off the drag down, the backdrop and the back button.
+ *
+ * @preview none
+ */
+@Component({
+  selector: 'app-example-sheet-dismissible',
+  imports: [BfButtonComponent],
+  template: `<bf-button (clicked)="open()">Show the terms</bf-button>`,
+})
+export class SheetDismissibleExampleComponent {
+  private readonly sheets = inject(BfSheetService);
+
+  protected open(): void {
+    this.sheets.open(TermsComponent, { dismissible: false });
+  }
+}
+```
+
+Include a visible close or cancel control in the sheet's content, as `bf-modal` requires; the
+built-in hidden Close is the safety net for screen readers, not a replacement. Every dismissible
+sheet renders that hidden Close (`provideBfLabels()`'s `close`, "Close") as its first element: a
+screen reader reaches it by swiping, and a keyboard user sees it as a pill at the top-end corner
+when <kbd>Tab</kbd> lands on it. A `dismissible: false` sheet has none.
+
+## Navigation
+
+A navigation to another URL path closes the sheet, resolving `afterClosed` with `undefined`, also
+a `dismissible: false` one: the page it belongs to is gone. A query- or fragment-only change
+leaves it open; a matrix-parameter change (`/list;sort=name`) is a path change and closes it. In
+the `/mobile` shell every push, every pop (the header back button, swipe-back,
+`BfNavController.back()`) and every tab switch changes the path, so a sheet opened on a page
+closes when that page is left. The Android hardware back button with a sheet open closes the
+sheet only (a `dismissible: false` sheet swallows the press); its handler runs at priority 100,
+above the page pop, so one press never closes it and pops the page as well. The same holds for
+Android back in a browser (Chrome, a PWA, no Capacitor): where `CloseWatcher` exists, the back
+press closes the sheet and leaves the URL alone, and the next press goes back in history. Pass
+`closeOnNavigation: false` for a sheet that should stay over the next page.
+
+```ts
+import { Component, inject } from '@angular/core';
+import { BfButtonComponent } from '@bitforgehq/ui';
+import { BfSheetRef, BfSheetService } from '@bitforgehq/ui/mobile';
+
+/** A player that outlives its page. */
+@Component({
+  selector: 'app-player',
+  imports: [BfButtonComponent],
+  template: `
+    <div class="flex flex-col gap-3 p-4">
+      <p class="text-body">Now playing: Team call recording</p>
+      <bf-button (clicked)="ref.close()">Done</bf-button>
+    </div>
+  `,
+})
+export class PlayerComponent {
+  protected readonly ref = inject(BfSheetRef);
+}
+
+/**
+ * A sheet that stays open across navigations.
+ *
+ * `closeOnNavigation: false` keeps a player open while the page behind it changes.
+ *
+ * @preview none
+ */
+@Component({
+  selector: 'app-example-sheet-navigation',
+  imports: [BfButtonComponent],
+  template: `<bf-button (clicked)="open()">Play</bf-button>`,
+})
+export class SheetNavigationExampleComponent {
+  private readonly sheets = inject(BfSheetService);
+
+  protected open(): void {
+    this.sheets.open(PlayerComponent, { closeOnNavigation: false });
+  }
+}
+```
+
+A sheet opened before the first navigation ends (a "What's new" sheet from the root component or
+an `APP_INITIALIZER`) closes when the start URL redirects (`''` to `'today'`): open it after the
+first `NavigationEnd`, or pass `closeOnNavigation: false`. A `history.pushState()` made outside
+Angular's `Location` is not seen.
+
+A route `canDeactivate` guard protects a form sheet's unsaved input only against in-app
+navigations: the sheet stays open while the guard's confirm asks. On the web the browser's back
+button changes the URL before the guard runs, so the sheet has already closed when "Stay" is
+answered (the Android hardware back button never gets that far: the sheet takes it first). A
+sheet that must keep its draft passes `closeOnNavigation: false` or saves the draft as it
+changes.
+
+## Labels and the injector
+
+Default strings come from `provideBfLabels()` (`sheet`, "Sheet"; `close`, "Close"; `expand`,
+"Expand"; `collapse`, "Collapse"; `sheetPosition`, "Sheet at 1 of 2"). 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 sheet'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 { BfSheetRef, BfSheetService } from '@bitforgehq/ui/mobile';
+
+/** A note in the feature's language. */
+@Component({
+  selector: 'app-new-note',
+  imports: [BfButtonComponent],
+  template: `
+    <div class="flex flex-col gap-3 p-4">
+      <p class="text-body">Neue Notiz</p>
+      <bf-button (clicked)="ref.close()">Fertig</bf-button>
+    </div>
+  `,
+})
+export class NewNoteComponent {
+  protected readonly ref = inject(BfSheetRef);
+}
+
+/**
+ * A sheet that reads a feature's labels.
+ *
+ * This feature provides German labels; passing the opener's injector is what names the sheet
+ * "Blatt" for screen readers (its `sheet` label) and lets its content read the same labels.
+ *
+ * @preview none
+ */
+@Component({
+  selector: 'app-example-sheet-injector',
+  imports: [BfButtonComponent],
+  providers: [provideBfLabels({ sheet: 'Blatt' })],
+  template: `<bf-button (clicked)="open()">Neue Notiz</bf-button>`,
+})
+export class SheetInjectorExampleComponent {
+  private readonly sheets = inject(BfSheetService);
+  private readonly injector = inject(Injector);
+
+  protected open(): void {
+    this.sheets.open(NewNoteComponent, { injector: this.injector });
+  }
+}
+```
+
+## Desktop
+
+`BfSheetService`'s bottom sheet 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.
+
+Open a form or a detail view in a `bf-dialog` with `BfDialogService.open()`, and a short list of
+actions in a `bf-menu` from a `bf-menu-button`.
+
+```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);
+  }
+}
+```
+
+## Theming
+
+- Card: `bg-surface`, `rounded-t-card` (`--radius-card`), `shadow-floating`, `pb-safe-bottom`
+  (`--spacing-safe-bottom`).
+- Grabber: `bg-control-off`, 36 × 5 px, `rounded-full`; `ButtonText` under forced colors. With a
+  mouse the handle row shows a `grab` cursor (`grabbing` while pressed) and the grabber darkens to
+  `text-muted` on hover.
+- Grabber button (two or more snap points): the full-width 24 px handle row, extended to 44 px
+  under a coarse pointer, downward only (20 px into the top of the content, so a tap just above
+  the sheet still reaches the backdrop); `focus-visible:ring-4 ring-ring` (inset) for the
+  keyboard focus. Keep the content's own controls out of its top 20 px, or give them `relative`
+  positioning (library buttons have it), so they paint above the extension.
+- Hidden Close (dismissible sheets): `sr-only` until focused, then a `rounded-full
+bg-surface-muted text-label-sm` pill at the top-end corner (`end-3 top-3`) with the focus ring.
+- Backdrop: `bf-overlay-backdrop` from the overlay core (a black scrim: 40 % in light mode, 60 % in dark).
+- Height: `--bf-sheet-height` on the `bf-sheet` host, written by the component — do not override it.
+- Keyboard: inline `translate`, `padding-bottom` and `max-height` on the host while the keyboard
+  is up — do not set your own.
+
+## Accessibility
+
+The overlay panel is a `role="dialog"` with `aria-modal="true"` and a name: the
+`ariaLabel` option when given; else the first heading in the content that is not `aria-hidden`
+(`h1`–`h6` or `role="heading"`), found once the content has rendered (or when it first appears later, e.g. behind `@if`) and
+referenced through
+`aria-labelledby` (it gets an id `bf-overlay-title-<n>` when it has none); else
+`provideBfLabels()`'s `sheet` ("Sheet"); the page stack behind it is `inert`. Focus moves to the
+panel itself (or, with `autoFocus: 'first-field'`, to the content's first field), Tab is trapped
+inside, and focus returns to the element that opened the sheet on close. `Escape` and the hardware back button close a dismissible
+sheet. The sheet's own controls, the hidden Close and the grabber button, come first in the Tab
+order but never take the initial focus. VoiceOver on iOS does not deliver its two-finger scrub
+(escape) gesture to web content, so the hidden Close is how a VoiceOver user leaves a sheet: keep
+a visible close or cancel control in the content as well.
+
+With two or more snap points the grabber is a button (named after the next press and the current
+position, "Expand, Sheet at 1 of 2"), the single-pointer alternative to dragging that WCAG 2.5.7
+(Dragging Movements) asks for. A name change on a focused button is not reliably re-read, so the
+new position is also announced politely ("Sheet at 2 of 2") whenever the sheet settles on another
+point; focus stays on the button. A screen reader's double tap (a click with `detail` 0) always
+moves the sheet, and the grabber ignores key combinations with <kbd>Alt</kbd>, <kbd>Ctrl</kbd> or
+<kbd>Meta</kbd>. With one snap point the grabber is `aria-hidden`. Under
+`prefers-reduced-motion` the sheet cross-fades in and out and settles on snap points instantly;
+a drag still follows the pointer.
+
+### Keyboard
+
+The grabber button (two or more snap points) takes these keys; none of them dismisses the sheet.
+
+| Key                                              | Action                                                                 |
+| ------------------------------------------------ | ---------------------------------------------------------------------- |
+| <kbd>Tab</kbd> / <kbd>Shift</kbd>+<kbd>Tab</kbd> | Moves between the sheet's controls (Close and grabber first), wrapping |
+| <kbd>Enter</kbd> / <kbd>Space</kbd>              | Grabber: one snap point up; from the top point, back to the lowest     |
+| <kbd>ArrowUp</kbd>                               | Grabber: one snap point up (stops at the top point)                    |
+| <kbd>ArrowDown</kbd>                             | Grabber: one snap point down (stops at the lowest point, never closes) |
+| <kbd>Home</kbd>                                  | Grabber: the lowest snap point                                         |
+| <kbd>End</kbd>                                   | Grabber: the top snap point                                            |
+| <kbd>Escape</kbd>                                | Closes a dismissible sheet                                             |
+
+## Notes
+
+### Do
+
+- Name the sheet by its purpose ("New task", "Filters"): start the content with a heading, or pass `ariaLabel`.
+- Mark your content's header with `data-bf-sheet-drag` so the whole top area drags.
+- Leave `autoFocus` at `'panel'` for a sheet the user reads or picks from; use `'first-field'` only
+  for a sheet that exists to be typed into.
+- Close with a result through `BfSheetRef` and await `afterClosed` in the caller.
+- Keep a visible close or cancel control in the content; the hidden Close is for screen readers.
+
+### Don't
+
+- Don't use a non-dismissible sheet for content the user may want to leave — use a modal with an
+  explicit cancel instead.
+- Don't make the lowest snap point so small that the content's primary action is hidden.
+- Don't nest scrolling containers inside the content; let the sheet's content region scroll.
+
+## Migration notes
+
+### 0.3.0
+
+**Behaviour:** a navigation to another URL path (a push, a pop, a tab switch) closes it with no
+result, also a `dismissible: false` one; new `closeOnNavigation` option (default true). Migration:
+pass `closeOnNavigation: false` to keep it open (see Migration 19).
+
+**Behaviour:** named by the first heading: without `ariaLabel`, the panel is named by the first
+heading in its content that is not `aria-hidden` (`h1`–`h6` or `role="heading"`, given an id
+`bf-overlay-title-<n>` when it has none) through `aria-labelledby`, once the content has rendered;
+without a heading, by `provideBfLabels()`'s `sheet` ("Sheet"). An explicit `ariaLabel` always wins.
+
+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 sheet.
+
+A heading that renders after the overlay opened (behind `@if`, a `resource()`) still names it: the
+panel is watched until its first heading appears.
+
+JSDoc of `sheet-ref.ts` for the API reference: `@summary`/`@since` on the exported symbols; `@param`
+docs. No behaviour change.
+
+JSDoc of `sheet.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.
+
+**Behaviour:** the keyboard lift and cap (`translate`, `padding-bottom`, `max-height`,
+`transition`) are written in the render phase (`afterRenderEffect({ write })`) instead of an
+`effect`; internal timing only, no API change.
+
+With two or more snap points the grabber is a button (`[data-bf-sheet-grabber-button]`), so the
+sheet can be resized without dragging (WCAG 2.5.7): a tap, click, `Enter` or `Space` moves it one
+point up, and from the top point back to the lowest; `ArrowUp`/`ArrowDown` step one point (never
+past the ends, never dismissing), `Home`/`End` jump to the lowest/top point, all through
+`snapTo()` (instant under reduced motion). It is named after the next press and the position
+("Expand, Sheet at 1 of 2": `expand` below the top point, `collapse` at it, then
+`sheetPosition`); focus stays on it, and every settle on another point (button, key, drag or
+`snapTo()`) announces `sheetPosition` politely through CDK `LiveAnnouncer`. A drag that starts on
+it still drags (a pointer click within the 6 px slop is the press; a keyboard or screen-reader
+click, `detail` 0, is never swallowed). Alt, Ctrl and Meta combinations are left alone. It is
+the full-width 24 px handle row, extended downward to 44 px under a coarse pointer, so a tap just
+above the sheet reaches the backdrop. With one snap point the grabber stays decorative
+(`aria-hidden`) and nothing is announced.
+
+**Behaviour:** every dismissible sheet renders a visually hidden "Close" button
+(`provideBfLabels()`'s `close`) as its first element, shown as a pill at the top-end corner when
+focused; activating it closes the sheet. VoiceOver reaches it by swiping, since WKWebView does not
+deliver the two-finger scrub to web content. A `dismissible: false` sheet has none. The Close and
+the grabber button never take the initial focus. Keep a visible close or cancel control in the
+content (Migration 28).
+
+**Behaviour:** a sheet opens with focus on its panel (the `role="dialog"` pane, named and
+`tabindex="-1"`), so a screen reader lands inside it and no soft keyboard comes up on open. New
+option `autoFocus?: BfSheetAutoFocus` (`'panel' | 'first-field'`, default `'panel'`; new exported
+type), mapped to the overlay core's `autoFocus` (`'first-field'` → `'first-tabbable'`, which
+honours `[autofocus]`/`[cdkFocusInitial]` and skips the sheet's Close and grabber). Action sheets
+and modals are unchanged. See Migration 33.
+
+`bf-sheet` provides a fresh `BfPageContext` (`mainLandmark` false) to its content: a `bf-content`
+in a sheet opened with a page's injector no longer resolves the page's context, so it is no second
+`main` and does not replace the page's registered scroller.
+
+Android back in a browser (no Capacitor) closes an open sheet first where `CloseWatcher` exists
+(see `### overlay core`, Migration 35).
+
+### 0.2.0
+
+New `BfSheetService.open(componentOrTemplate, { snapPoints, initial, dismissible, data, ariaLabel })`
+in `@bitforgehq/ui/mobile`, a bottom sheet on the overlay core (`position: 'bottom'`, back priority
+100, not counted as a modal; slides up on open and down on close). It returns a `BfSheetRef`
+(extends `BfOverlayRef`) with `snapTo(index)` and a `snapIndex` signal; the content injects the
+caller's `data` as `BF_OVERLAY_DATA` and the ref as `BfSheetRef` and `BfOverlayRef` (a template
+gets `{ $implicit: ref, data }`). The `bf-sheet` container is a `bg-surface rounded-t-card
+shadow-floating` card with `pb-safe-bottom`, a 36 × 5 px `bg-control-off` grabber (`aria-hidden`,
+`ButtonText` under forced colors)
+in a 24 px `touch-none` handle row and a content region; its height is `--bf-sheet-height`, a snap
+point (fraction of `BfKeyboardService.restHeight()`, else `innerHeight`; default `[0.5, 0.92]`)
+re-applied on resize. Dragging the handle row, any `[data-bf-sheet-drag]` element or the content
+(below the top point, or downward at the top point while scrolled to 0) moves the sheet with
+Pointer Events under pointer capture and a non-passive `touchmove` guard: rubber-banded (30 %)
+above the top point, released onto the nearest point or, faster than 0.3 px/ms, the next one in
+the fling's direction; a release more than 25 % of the lowest point's height below it, or a
+downward fling from it, dismisses. The content scrolls (`overflow-y-auto`) only at the top point,
+`overflow-hidden` below it, always `overscroll-contain`. `dismissible: false` ignores the backdrop,
+`Escape` and downward dismissal and swallows the hardware back button while open. Settling is a
+260 ms WAAPI animation, instant under `prefers-reduced-motion` (the drag still tracks the
+pointer). The panel is `role="dialog"` `aria-modal` with `aria-label` (default "Sheet"), focus
+moves in and returns on close.
+
+Fixed: the handle row shows a `grab` cursor (`grabbing` while pressed) and the grabber darkens to
+`text-muted` on hover.
+
+Fixed (behaviour change): the soft keyboard no longer covers a sheet's focused field and actions.
+While the keyboard overlays the sheet's bottom edge (iOS with `Keyboard.resize: 'none'`, a mobile
+browser), `bf-sheet` is lifted by the covered height (an inline `translate`, bottom safe-area
+padding dropped, since the keyboard covers the home indicator); while the keyboard is up at all
+(also Android, where the WebView resizes and nothing is lifted) its height is capped at the
+keyboard's top edge minus the safe-area top minus 8 px (`max-height`), and the content region
+scrolls at every snap point, with `bfKeyboardAssist` revealing the focused control 24 px above the
+keyboard. The lift follows the keyboard with a 250 ms `translate` transition on the iOS curve
+(instant under `prefers-reduced-motion`), and is left alone once the sheet is closing. The snap
+heights (`--bf-sheet-height`) are unchanged, and a drag of a capped sheet starts from its rendered
+(capped) height, so it moves from the first pixel. Hiding the keyboard removes the lift and the
+cap together and at once (the drop is not animated, so a sheet at a snap point taller than the cap
+never has its top edge above the screen), so the sheet rests at its snap height again, and content
+left scrolled while the keyboard was up returns to its top when the keyboard hides below the top
+snap point (a drag between snap points without the keyboard keeps the scroll offset, as before).