@bitforgehq/ui 0.3.0

package/ai/components/modal.md

@@ -0,0 +1,613 @@
+# bf-modal
+
+Modal overlay shown as an inset card over the scaled-down page, or full screen
+
+`BfModalComponent` 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,
+  type BfModalPresentation,
+  BfModalService,
+  BfPageComponent,
+} from '@bitforgehq/ui/mobile';
+import { type ShowcaseModalData, ShowcaseModalComponent } from './showcase-modal.component';
+
+/** `bf-modal` showcase: the same note editor as a page-sheet card and as a fullscreen modal. */
+@Component({
+  selector: 'app-modal-showcase',
+  imports: [BfPageComponent, BfHeaderComponent, BfContentComponent, BfButtonComponent],
+  template: `
+    <bf-page data-showcase="modal">
+      <bf-header title="Modal" [largeTitle]="false" />
+      <bf-content>
+        <div class="flex flex-col gap-4 p-4">
+          <p class="text-caption text-text-muted">
+            In iPhone mode the sheet presentation scales the page behind it down; the fullscreen one
+            leaves it as it is.
+          </p>
+          <bf-button (clicked)="open('sheet')">Open sheet modal</bf-button>
+          <bf-button variant="tonal" (clicked)="open('fullscreen')"
+            >Open fullscreen modal</bf-button
+          >
+          <p data-showcase-result class="text-body">{{ result() }}</p>
+        </div>
+      </bf-content>
+    </bf-page>
+  `,
+})
+export class ModalShowcasePage {
+  private readonly modals = inject(BfModalService);
+
+  protected readonly result = signal('No note yet.');
+
+  async open(presentation: BfModalPresentation): Promise<void> {
+    const data: ShowcaseModalData = { presentation };
+    const ref = this.modals.open<ShowcaseModalComponent, string>(ShowcaseModalComponent, {
+      data,
+      presentation,
+      ariaLabel: 'New note',
+    });
+    const title = await ref.afterClosed;
+    this.result.set(title ? `Saved “${title}”.` : 'Closed without saving.');
+  }
+}
+```
+
+## Overview
+
+The modal frame that `BfModalService.open()` renders on the overlay core, `position:
+'fullscreen'`: a `sheet` presentation (default) is a card whose top sits 10 px below the top
+safe area (UIKit's page-sheet inset; `bg-bg rounded-t-card shadow-floating`) over the parked page stack, which scales down and
+grows rounded corners behind it (`--bf-modal-depth`, written by `BfOverlayStack`, consumed by
+`bf-stack-outlet`'s host rule); `fullscreen` covers the viewport edge to edge with no scale.
+Like `bf-page`, it provides a fresh `BfPageContext` so the content's `bf-header` and
+`bf-content` work inside it (with `mainLandmark` false, so its content is no `main` landmark,
+and in the `sheet` presentation with `safeAreaTop` false, so the header adds no status-bar band
+inside the card) — the content supplies its own header (typically a close
+`bf-icon-button` in `start`) and content region. While the soft keyboard overlays the bottom of
+a `sheet` card (iOS, a mobile browser), the card is padded at the bottom by the covered height,
+so the content's `bf-content` ends at the keyboard's top edge and its keyboard assist reveals
+the focused control there. Not used directly in templates.
+
+A page-level modal. `BfModalService.open(component, options)` renders a component in a `bf-modal`
+frame on the overlay core, either a page-sheet card over the page stack (default) or a fullscreen
+frame. Unlike `bf-sheet`, there is no backdrop dismiss and no drag-to-dismiss — the content closes
+itself, typically from a close control in its own `bf-header`. You never place `<bf-modal>` in a
+template yourself.
+
+## When to use
+
+Use `BfModalService` in the Capacitor shell for a self-contained task that takes over the screen and closes itself: compose a message, edit a profile. Use [BfSheetService](https://bitforge-ui.web.app/api/bf-sheet-service) instead for content the user can drag away or keep half open, and [BfDialogService](https://bitforge-ui.web.app/api/bf-dialog-service) on desktop.
+
+## Basic usage
+
+The content is an ordinary standalone component with its own `bf-header` (`largeTitle="false"`)
+and `bf-content` — `bf-modal` gives it a `BfPageContext`, exactly like `bf-page`, so the two work
+together (the header can, for example, collapse against the content's scroll).
+
+```ts
+import { Component, inject, signal } from '@angular/core';
+import { BfButtonComponent, BfIconButtonComponent, BfInputComponent } from '@bitforgehq/ui';
+import { BfIconComponent } from '@bitforgehq/ui/icons';
+import { BfContentComponent, BfHeaderComponent, BfModalService } from '@bitforgehq/ui/mobile';
+import { BF_OVERLAY_DATA, BfOverlayRef } from '@bitforgehq/ui/overlay';
+import { X } from 'lucide';
+
+/** A task as the modal edits it. */
+export interface Task {
+  id: string;
+  title: string;
+}
+
+/** The modal: its own header with a close button and Save, then the form. */
+@Component({
+  selector: 'app-edit-task',
+  imports: [
+    BfHeaderComponent,
+    BfContentComponent,
+    BfIconButtonComponent,
+    BfIconComponent,
+    BfButtonComponent,
+    BfInputComponent,
+  ],
+  template: `
+    <bf-header title="Edit task" [largeTitle]="false">
+      <bf-icon-button bfSlot="start" variant="text" label="Close" (clicked)="close()">
+        <bf-icon [icon]="xIcon" />
+      </bf-icon-button>
+      <bf-button bfSlot="end" variant="text" (clicked)="save()">Save</bf-button>
+    </bf-header>
+    <bf-content class="px-4">
+      <bf-input label="Title" [(value)]="title" />
+    </bf-content>
+  `,
+})
+export class EditTaskComponent {
+  private readonly data = inject<{ taskId: string }>(BF_OVERLAY_DATA);
+  private readonly ref = inject<BfOverlayRef<Task>>(BfOverlayRef);
+  protected readonly xIcon = X;
+  protected readonly title = signal('Buy milk');
+
+  close(): void {
+    this.ref.close();
+  }
+
+  save(): void {
+    this.ref.close({ id: this.data.taskId, title: this.title() });
+  }
+}
+
+/**
+ * A modal that edits a task.
+ *
+ * `open()` passes the task id as data and awaits the saved task, or `undefined` when closed
+ * without a result.
+ *
+ * @preview none
+ */
+@Component({
+  selector: 'app-example-modal-basic',
+  imports: [BfButtonComponent],
+  template: `
+    <div class="flex flex-col items-start gap-3">
+      <bf-button (clicked)="edit('task-1')">Edit task</bf-button>
+      <p aria-live="polite" class="text-caption text-text-muted">{{ result() }}</p>
+    </div>
+  `,
+})
+export class ModalBasicExampleComponent {
+  private readonly modals = inject(BfModalService);
+  protected readonly result = signal('');
+
+  protected async edit(taskId: string): Promise<void> {
+    const ref = this.modals.open<EditTaskComponent, Task>(EditTaskComponent, {
+      data: { taskId },
+    });
+    const saved = await ref.afterClosed; // undefined when closed without a result
+    this.result.set(saved ? `Saved "${saved.title}".` : 'Closed.');
+  }
+}
+```
+
+## Presentations
+
+`presentation: 'sheet'` (default) is a card whose top edge sits 10 px below the top safe area
+(`top-[calc(var(--spacing-safe-top)+10px)]`, UIKit's page-sheet inset, so the card starts below
+the status bar and the parent page peeks above it; `bg-bg rounded-t-card shadow-floating`) over
+the parked page stack; in iOS mode opening it scales the page stack down and
+rounds its corners behind the card (Material mode leaves the page stack full size) (driven by `--bf-modal-depth`, written by `BfOverlayStack` on every
+registered `bf-stack-outlet` root, consumed by the outlet's own host styles). `presentation:
+'fullscreen'` covers the viewport edge to edge and leaves the page stack full size — use it for
+forms and flows that need the whole screen.
+
+The sheet card already sits below the status bar, so it sets its `BfPageContext`'s `safeAreaTop`
+to false: the content's `bf-header` (and a `fullscreen` `bf-content`) adds no status-bar band of
+its own inside the card. A fullscreen modal reaches the top of the screen and keeps `safeAreaTop`
+true, like a page.
+
+A `bf-page` inside a sheet modal's content (for example a stack of its own) is not supported: it
+provides a fresh `BfPageContext` with `safeAreaTop` true, so its header would add the status-bar
+band back inside the card. Put the `bf-header` and `bf-content` directly in the modal's content
+component, or use the `fullscreen` presentation for a flow that needs its own pages.
+
+```ts
+import { Component, inject } from '@angular/core';
+import { BfButtonComponent } from '@bitforgehq/ui';
+import { BfModalService } from '@bitforgehq/ui/mobile';
+import { BfOverlayRef } from '@bitforgehq/ui/overlay';
+
+/** Onboarding that fills the screen. */
+@Component({
+  selector: 'app-onboarding',
+  imports: [BfButtonComponent],
+  template: `
+    <div class="flex flex-col gap-3 p-4">
+      <p class="text-body">Welcome! Three steps set up your workspace.</p>
+      <bf-button (clicked)="ref.close()">Done</bf-button>
+    </div>
+  `,
+})
+export class OnboardingComponent {
+  protected readonly ref = inject(BfOverlayRef);
+}
+
+/**
+ * A full-screen modal.
+ *
+ * `presentation: 'fullscreen'` covers the whole screen instead of the card.
+ *
+ * @preview none
+ */
+@Component({
+  selector: 'app-example-modal-presentations',
+  imports: [BfButtonComponent],
+  template: `<bf-button (clicked)="open()">Start onboarding</bf-button>`,
+})
+export class ModalPresentationsExampleComponent {
+  private readonly modals = inject(BfModalService);
+
+  protected open(): void {
+    this.modals.open(OnboardingComponent, { presentation: 'fullscreen' });
+  }
+}
+```
+
+In iOS mode, stacking two sheet modals scales the page stack twice as much (`--bf-modal-depth: 2`); a
+fullscreen modal never adds to that depth.
+
+iOS mode slides the card (or frame) up from the bottom and back down on close; Material mode fades
+it up 16 px and back down.
+
+## Dismissible
+
+By default (`dismissible: true`) `Escape` and the hardware back button close the modal in addition
+to the content's own close control. With `dismissible: false` only the content closes it: `Escape`
+is ignored and the back button is swallowed while the modal is open instead of falling through to
+the page behind (like a non-dismissible `bf-sheet`). There is no backdrop dismiss for either case —
+give the content an explicit close control.
+
+```ts
+import { Component, inject } from '@angular/core';
+import { BfButtonComponent } from '@bitforgehq/ui';
+import { BfModalService } from '@bitforgehq/ui/mobile';
+import { BfOverlayRef } from '@bitforgehq/ui/overlay';
+
+/** Terms that must be accepted. */
+@Component({
+  selector: 'app-terms',
+  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(BfOverlayRef);
+}
+
+/**
+ * A modal that must be answered.
+ *
+ * `dismissible: false` turns off the swipe down and the back button; only its own button closes it.
+ *
+ * @preview none
+ */
+@Component({
+  selector: 'app-example-modal-dismissible',
+  imports: [BfButtonComponent],
+  template: `<bf-button (clicked)="open()">Show the terms</bf-button>`,
+})
+export class ModalDismissibleExampleComponent {
+  private readonly modals = inject(BfModalService);
+
+  protected open(): void {
+    this.modals.open(TermsComponent, { dismissible: false });
+  }
+}
+```
+
+## Navigation
+
+A navigation to another URL path closes the modal, resolving `afterClosed` with `undefined`, also
+a `dismissible: false` one. 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 modal opened on a page closes when that page is left. The Android hardware
+back button with a modal open closes the modal only (a `dismissible: false` modal 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. Pass `closeOnNavigation: false` for a modal that should stay over the next
+page.
+
+```ts
+import { Component, inject } from '@angular/core';
+import { BfButtonComponent } from '@bitforgehq/ui';
+import { BfModalService } from '@bitforgehq/ui/mobile';
+import { BfOverlayRef } from '@bitforgehq/ui/overlay';
+
+/** A message being written. */
+@Component({
+  selector: 'app-compose',
+  imports: [BfButtonComponent],
+  template: `
+    <div class="flex flex-col gap-3 p-4">
+      <p class="text-body">Your draft stays while you look something up.</p>
+      <bf-button (clicked)="ref.close()">Done</bf-button>
+    </div>
+  `,
+})
+export class ComposeComponent {
+  protected readonly ref = inject(BfOverlayRef);
+}
+
+/**
+ * A modal that stays open across navigations.
+ *
+ * `closeOnNavigation: false` keeps a compose modal open while the page behind it changes.
+ *
+ * @preview none
+ */
+@Component({
+  selector: 'app-example-modal-navigation',
+  imports: [BfButtonComponent],
+  template: `<bf-button (clicked)="open()">Compose</bf-button>`,
+})
+export class ModalNavigationExampleComponent {
+  private readonly modals = inject(BfModalService);
+
+  protected open(): void {
+    this.modals.open(ComposeComponent, { closeOnNavigation: false });
+  }
+}
+```
+
+A modal opened before the first navigation ends (an onboarding modal 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 modal's unsaved input only against in-app
+navigations: the modal 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 modal has already closed when "Stay" is
+answered (the Android hardware back button never gets that far: the modal takes it first). A
+modal that must keep its draft passes `closeOnNavigation: false` or saves the draft as it
+changes.
+
+## Soft keyboard
+
+A sheet modal ends above the soft keyboard. Where the keyboard overlays the page (iOS with
+`Keyboard.resize: 'none'`, a mobile browser), `bf-modal` pads its bottom by the covered height
+while the keyboard is up, so the content's `bf-content` ends at the keyboard's top edge and its
+keyboard assist scrolls the focused field 24 px clear of it. Hiding the keyboard removes the
+padding. On Android the WebView itself shrinks, so nothing is added; a fullscreen modal leaves the
+keyboard to its `bf-content`, as a page does. Put the form in the content's `bf-content` and its
+primary action in the header (`end` slot), where the keyboard never reaches it.
+
+## Labels and the injector
+
+Default strings come from `provideBfLabels()` (`modal`, "Modal"). 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 modal'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 { BfModalService } from '@bitforgehq/ui/mobile';
+import { BfOverlayRef } from '@bitforgehq/ui/overlay';
+
+/** A note in the feature's language. */
+@Component({
+  selector: 'app-note',
+  imports: [BfButtonComponent],
+  template: `
+    <div class="flex flex-col gap-3 p-4">
+      <p class="text-body">Notiz bearbeiten</p>
+      <bf-button (clicked)="ref.close()">Fertig</bf-button>
+    </div>
+  `,
+})
+export class NoteComponent {
+  protected readonly ref = inject(BfOverlayRef);
+}
+
+/**
+ * A modal that reads a feature's labels.
+ *
+ * This feature provides German labels; passing the opener's injector is what names the modal
+ * "Fenster" for screen readers (its `modal` label) and lets its content read the same labels.
+ *
+ * @preview none
+ */
+@Component({
+  selector: 'app-example-modal-injector',
+  imports: [BfButtonComponent],
+  providers: [provideBfLabels({ modal: 'Fenster' })],
+  template: `<bf-button (clicked)="open()">Notiz bearbeiten</bf-button>`,
+})
+export class ModalInjectorExampleComponent {
+  private readonly modals = inject(BfModalService);
+  private readonly injector = inject(Injector);
+
+  protected open(): void {
+    this.modals.open(NoteComponent, { injector: this.injector });
+  }
+}
+```
+
+## Desktop
+
+`BfModalService`'s modal 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.open()` renders the same kind of content (your component, with a typed ref and
+`BF_DIALOG_DATA`) centred over a backdrop; lay it out with `bf-dialog`.
+
+```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.');
+  }
+}
+```
+
+## Theming
+
+- Sheet card: `bg-bg`, `rounded-t-card` (`--radius-card`), `shadow-floating`; its top at
+  `--spacing-safe-top` plus 10 px.
+- Fullscreen frame: `bg-bg`, no radius or shadow.
+- Page stack behind a sheet modal (iOS mode): scaled and rounded through `--bf-modal-depth` on the
+  `bf-stack-outlet` host — do not set that variable yourself.
+- Keyboard: an inline `padding-bottom` on the sheet card while the keyboard overlays it — do not
+  set your own inline bottom padding on `bf-modal`.
+
+## 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"`, such as the `bf-header` title), 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 `modal` ("Modal"). The page stack behind it is `inert`. Focus moves to the first focusable element of the
+content (or the panel), unlike a sheet, which focuses its panel; Tab is trapped inside, and focus
+returns to the element that opened the modal on close. The content's `bf-content` is no `main`
+landmark (the modal's `BfPageContext.mainLandmark` is false): content in a dialog is not the
+page's main content, and the page behind keeps its `main`, `inert` while the modal is open.
+`Escape`, the hardware back button and, in a browser with `CloseWatcher`, Android back close a
+dismissible modal. Under
+`prefers-reduced-motion` the modal cross-fades in and out instead of sliding or rising, and the
+page stack behind a sheet modal skips the scale/rounding transition.
+
+### Keyboard
+
+| Key                                              | Action                                                 |
+| ------------------------------------------------ | ------------------------------------------------------ |
+| <kbd>Tab</kbd> / <kbd>Shift</kbd>+<kbd>Tab</kbd> | Moves between the modal's controls, wrapping inside it |
+| <kbd>Escape</kbd>                                | Closes a dismissible modal                             |
+
+## Notes
+
+### Do
+
+- Give the content its own `bf-header` with a close control (`bf-icon-button` in `start`) —
+  `bf-modal` never adds one for you.
+- Use `presentation: 'sheet'` for editors and detail forms opened from a page; reserve
+  `'fullscreen'` for onboarding and other flows that need the whole screen.
+- Close with a result through the injected `BfOverlayRef` and await `afterClosed` in the caller.
+
+### Don't
+
+- Don't rely on a backdrop tap or a drag to close the modal — there is neither; always give the
+  content a close control.
+- Don't use `dismissible: false` without a way out in the content itself (a close or cancel
+  control) — the user would otherwise be stuck.
+- Don't nest a `bf-modal` inside another modal's content by hand; open the second one through
+  `BfModalService` so it stacks and the depth scale is correct.
+- Don't wrap a sheet modal's content in a `bf-page`: it brings the status-bar band back (see
+  Presentations).
+
+## Migration notes
+
+### 0.3.0
+
+**Behaviour:** a navigation to another URL path 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` (such as the `bf-header` title) through
+`aria-labelledby`, once the content has rendered; without a heading, by `provideBfLabels()`'s
+`modal` ("Modal"). 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 modal.
+
+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 `modal.component.ts` for the API reference: `@summary`/`@since` on the exported symbols. No
+behaviour change.
+
+JSDoc of `modal.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 page-sheet card (`presentation: 'sheet'`) starts 10 px below the top safe
+area (`top-[calc(var(--spacing-safe-top)+10px)]`, UIKit's page-sheet inset; was `top-3`), so it
+sits below the status bar and the parent page peeks above it, and it sets its `BfPageContext`'s
+`safeAreaTop` to false, so its content's header adds no second status-bar band (Migration 29). A
+fullscreen modal is unchanged.
+
+**Behaviour:** its content is no `main` landmark: `bf-modal` sets its `BfPageContext.mainLandmark`
+to false (content in a dialog is not the page's main content; the page behind stays `main`, inert
+while the modal is open). Android web back closes it where `CloseWatcher` exists (Migration 35).
+
+### 0.2.0
+
+New `BfModalService.open(component, { data, presentation, dismissible, ariaLabel })` in
+`@bitforgehq/ui/mobile`, a page-level modal on the overlay core (`position: 'fullscreen'`, back
+priority 100, no backdrop dismiss). `presentation: 'sheet'` (default) renders `bf-modal` as a card
+inset 12 px from the top (`bg-bg rounded-t-card shadow-floating`) and, in iOS mode only, counts as
+a modal, driving `--bf-modal-depth` on every registered `bf-stack-outlet` root (see
+`### stack-outlet`) so the page behind scales down (Material mode leaves it unscaled);
+`'fullscreen'` renders it edge to edge (`bg-bg`, no radius or shadow) and does not count towards
+that depth. iOS mode slides the frame up on enter and down on exit; Material mode fades it up 16 px
+on enter and down on exit (new `fadeUp`/`fadeDown` helpers in `overlay-animations.ts`). It returns
+the `BfOverlayRef<T>` the content also injects (with the caller's `data` as `BF_OVERLAY_DATA`) and
+closes with a result through; unlike `bf-sheet` there is no drag-to-dismiss, so the content needs
+its own close control. `dismissible: false` (default true) ignores `Escape` and swallows the
+hardware back button while open instead of closing or falling through to the page behind. Like
+`bf-page`, `bf-modal` provides a fresh `BfPageContext` so the content's own `bf-header`
+(`largeTitle="false"`, typically a close `bf-icon-button` in `start`) and `bf-content` work
+inside it. `provideBfShell()` now also provides `BfSheetService` and `BfModalService`.
+
+Fixed (behaviour change): a `presentation: 'sheet'` modal ends above the soft keyboard. While the
+keyboard overlays the card's bottom edge (iOS, a mobile browser), `bf-modal` gets an inline
+`padding-bottom` of the covered height, so the content's `bf-content` ends at the keyboard's top
+edge and its keyboard assist reveals the focused control there; it goes away with the keyboard. A
+`fullscreen` modal, and Android, where the WebView resizes, are unchanged.