@bitforgehq/ui 0.3.0

package/ai/components/toast.md

@@ -0,0 +1,522 @@
+# bf-toast
+
+Passive status pill with an optional action that never steals focus
+
+`BfToastComponent` 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,
+  type BfToastOptions,
+  BfToastService,
+} from '@bitforgehq/ui/mobile';
+
+/** `bf-toast` showcase: a bottom toast, a top toast and one with an Undo action. */
+@Component({
+  selector: 'app-toast-showcase',
+  imports: [BfPageComponent, BfHeaderComponent, BfContentComponent, BfButtonComponent],
+  template: `
+    <bf-page data-showcase="toast">
+      <bf-header title="Toast" [largeTitle]="false" />
+      <bf-content>
+        <div class="flex flex-col gap-4 p-4">
+          <p class="text-caption text-text-muted">
+            Toasts queue: tap several buttons quickly and each shows once the one before it ends.
+          </p>
+          <bf-button (clicked)="show({ message: 'Saved' })">Bottom toast</bf-button>
+          <bf-button
+            variant="tonal"
+            (clicked)="show({ message: 'No connection', position: 'top' })"
+          >
+            Top toast
+          </bf-button>
+          <bf-button variant="outline" (clicked)="showWithUndo()">Toast with action</bf-button>
+          <p data-showcase-result class="text-body">{{ result() }}</p>
+        </div>
+      </bf-content>
+    </bf-page>
+  `,
+})
+export class ToastShowcasePage {
+  private readonly toasts = inject(BfToastService);
+
+  protected readonly result = signal('No toast yet.');
+
+  async show(options: BfToastOptions): Promise<void> {
+    const reason = await this.toasts.show(options).afterDismissed;
+    this.result.set(`“${options.message}” ended: ${reason}.`);
+  }
+
+  async showWithUndo(): Promise<void> {
+    const reason = await this.toasts.show({ message: 'Task deleted', action: { label: 'Undo' } })
+      .afterDismissed;
+    this.result.set(reason === 'action' ? 'Task restored.' : `“Task deleted” ended: ${reason}.`);
+  }
+}
+```
+
+## Overview
+
+The status pill that `BfToastService.show()` renders on the overlay core (`passive: true`, no
+backdrop, no focus trap, no inert page and no back handler — it never steals focus): an ink
+`bg-text text-bg rounded-full shadow-floating` pill holding the message (truncated to two lines)
+and an optional action. The pill is not a live region: the service announces each toast once
+through CDK `LiveAnnouncer`. The pointer over it or focus inside it pauses its timer, and
+`Escape` with focus inside dismisses it. `position: 'bottom'` (default) sits 16 px above the
+tab-bar inset (`--bf-tab-bar-inset-global`, published on `<html>` by `bf-tabs`, which leaves
+8 px above the floating bar, so the toast clears it by 24 px) and the soft keyboard
+(`--bf-toast-keyboard` on the host: `BfKeyboardService.height()` where the keyboard overlays
+the WebView — native iOS — and 0 where the WebView already shrinks); `position: 'top'` sits
+16 px below the status bar (a top margin of the safe-area inset plus 16 px, outside the pill)
+instead. Not used directly in templates.
+
+A status pill. `BfToastService.show(options)` renders `bf-toast` on the overlay core
+(`passive: true`): an ink pill above the floating tab bar and the soft keyboard, with an optional
+action. Only one toast is visible at a time — later calls queue and show once the current one
+ends. You never place `<bf-toast>` in a template yourself.
+
+## When to use
+
+Use `BfToastService` in the Capacitor shell for a short status after an action, one at a time above the tab bar: "Saved", "Task deleted. Undo". Use [BfDesktopToastService](https://bitforge-ui.web.app/api/bf-desktop-toast-service) instead in a desktop web app, and [BfAlertDialogService](https://bitforge-ui.web.app/api/bf-alert-dialog-service) when the user must answer.
+
+## Basic usage
+
+```ts
+import { Component, inject, signal } from '@angular/core';
+import { BfButtonComponent } from '@bitforgehq/ui';
+import { BfToastService } from '@bitforgehq/ui/mobile';
+
+/**
+ * A toast and how it ended.
+ *
+ * `afterDismissed` resolves with the reason: `timeout`, `action` or `dismiss`.
+ *
+ * @preview none
+ */
+@Component({
+  selector: 'app-example-toast-basic',
+  imports: [BfButtonComponent],
+  template: `
+    <div class="flex flex-col items-start gap-3">
+      <bf-button (clicked)="open()">Save</bf-button>
+      <p aria-live="polite" class="text-caption text-text-muted">{{ result() }}</p>
+    </div>
+  `,
+})
+export class ToastBasicExampleComponent {
+  private readonly toasts = inject(BfToastService);
+  protected readonly result = signal('');
+
+  protected async open(): Promise<void> {
+    const ref = this.toasts.show({ message: 'Saved' });
+    const reason = await ref.afterDismissed; // 'timeout' | 'action' | 'dismiss'
+    this.result.set(`The toast ended: ${reason}.`);
+  }
+}
+```
+
+`dismiss()` ends the toast right away — closing it if it is the one currently shown, or dropping
+it from the queue before it ever shows.
+
+```ts
+import { Component, inject, signal } from '@angular/core';
+import { BfButtonComponent } from '@bitforgehq/ui';
+import { BfToastService } from '@bitforgehq/ui/mobile';
+
+/**
+ * A toast that stays until it is dismissed.
+ *
+ * `duration: 0` keeps "Uploading…" up; `dismiss()` ends it when the upload is done.
+ *
+ * @preview none
+ */
+@Component({
+  selector: 'app-example-toast-persistent',
+  imports: [BfButtonComponent],
+  template: `
+    <div class="flex flex-col items-start gap-3">
+      <bf-button (clicked)="open()">Upload</bf-button>
+      <p aria-live="polite" class="text-caption text-text-muted">{{ result() }}</p>
+    </div>
+  `,
+})
+export class ToastPersistentExampleComponent {
+  private readonly toasts = inject(BfToastService);
+  protected readonly result = signal('');
+  /** Stands in for the real upload. */
+  private upload(): Promise<void> {
+    return new Promise((resolve) => setTimeout(resolve, 1500));
+  }
+
+  protected async open(): Promise<void> {
+    const ref = this.toasts.show({ message: 'Uploading…', duration: 0 });
+    await this.upload();
+    ref.dismiss();
+    this.result.set('Uploaded.');
+  }
+}
+```
+
+## Action
+
+`action` renders a real, keyboard-reachable `<button>` inside the pill. Its `handler` runs before
+the toast closes with reason `'action'`. A toast with an action stays until the action or
+`dismiss()` ends it (see Duration), so keyboard and switch users can always reach it.
+
+```ts
+import { Component, inject, signal } from '@angular/core';
+import { BfButtonComponent } from '@bitforgehq/ui';
+import { BfToastService } from '@bitforgehq/ui/mobile';
+
+/**
+ * A toast with an Undo action.
+ *
+ * The action's `handler` runs before the toast closes with reason `action`.
+ *
+ * @preview none
+ */
+@Component({
+  selector: 'app-example-toast-action',
+  imports: [BfButtonComponent],
+  template: `
+    <div class="flex flex-col items-start gap-3">
+      <bf-button variant="danger" (clicked)="open()">Delete task</bf-button>
+      <p aria-live="polite" class="text-caption text-text-muted">{{ result() }}</p>
+    </div>
+  `,
+})
+export class ToastActionExampleComponent {
+  private readonly toasts = inject(BfToastService);
+  protected readonly result = signal('');
+
+  protected open(): void {
+    this.result.set('Task deleted.');
+    this.toasts.show({
+      message: 'Task deleted',
+      action: { label: 'Undo', handler: () => this.result.set('Task restored.') },
+    });
+  }
+}
+```
+
+## Duration
+
+`duration` (ms) is how long the toast stays before it auto-dismisses, resolving `'timeout'`. It
+defaults to `3000` for a toast without an action and to `0` for a toast with one: an action toast
+persists until its action or `dismiss()` ends it, because an "Undo" that vanishes after 3 s is out
+of reach for many keyboard, switch and screen-reader users (WCAG 2.2.1 Timing Adjustable). An
+explicit `duration` always wins. `duration: 0` also suits a toast that tracks an ongoing
+operation (an upload, a sync) rather than a one-off confirmation.
+
+```ts
+import { Component, inject, signal } from '@angular/core';
+import { BfButtonComponent } from '@bitforgehq/ui';
+import { BfToastService } from '@bitforgehq/ui/mobile';
+
+/**
+ * An action toast with a timeout.
+ *
+ * An action toast persists until Undo or `dismiss()`; `duration` opts it back into a timeout.
+ *
+ * @preview none
+ */
+@Component({
+  selector: 'app-example-toast-duration',
+  imports: [BfButtonComponent],
+  template: `
+    <div class="flex flex-col items-start gap-3">
+      <bf-button (clicked)="open()">Delete task</bf-button>
+      <p aria-live="polite" class="text-caption text-text-muted">{{ result() }}</p>
+    </div>
+  `,
+})
+export class ToastDurationExampleComponent {
+  private readonly toasts = inject(BfToastService);
+  protected readonly result = signal('');
+
+  protected open(): void {
+    const undo = (): void => this.result.set('Task restored.');
+    this.result.set('Task deleted.');
+    this.toasts.show({
+      message: 'Task deleted',
+      action: { label: 'Undo', handler: undo },
+      duration: 8000,
+    });
+  }
+}
+```
+
+The timer pauses while the pointer is over the toast or focus is inside it, and resumes with the
+time that was left once both have left — a toast never times out under the reader's pointer or
+while its action is focused.
+
+## Position
+
+`position` is `'bottom'` (default) or `'top'`. `'bottom'` sits 16 px above the tab-bar inset
+(`--bf-tab-bar-inset-global`, published on `<html>` by `bf-tabs`; it already leaves 8 px above the
+floating bar, so the toast clears the bar by 24 px) and the soft keyboard,
+recomputed live as either changes — `BfKeyboardService.height()` where the keyboard overlays the
+WebView (native iOS), nothing where the WebView already shrinks for it (Android, the web); `'top'` sits 16 px below the status bar (a top margin of the safe-area inset plus 16 px), for a toast that would
+otherwise sit under a keyboard-focused control.
+
+```ts
+import { Component, inject } from '@angular/core';
+import { BfButtonComponent } from '@bitforgehq/ui';
+import { BfToastService } from '@bitforgehq/ui/mobile';
+
+/**
+ * A toast at the top of the screen.
+ *
+ * `position: 'top'` shows it under the status bar instead of above the tab bar.
+ *
+ * @preview none
+ */
+@Component({
+  selector: 'app-example-toast-position',
+  imports: [BfButtonComponent],
+  template: `<bf-button (clicked)="open()">Go offline</bf-button>`,
+})
+export class ToastPositionExampleComponent {
+  private readonly toasts = inject(BfToastService);
+
+  protected open(): void {
+    this.toasts.show({ message: 'No connection', position: 'top' });
+  }
+}
+```
+
+## Queueing
+
+`show()` never interrupts a visible timed toast: a second call while one is up queues in order and
+shows once the first ends (however it ends — timeout, action or `dismiss()`). Each call still
+returns its own `BfToastRef` immediately, so callers can `dismiss()` or await `afterDismissed` on a
+toast that hasn't shown yet.
+
+Persistent toasts (`duration: 0`, which is the default for a toast with an action) never block the
+queue: the next `show()` replaces one, visible or still waiting, and it resolves `'dismiss'` — a
+superseded "Undo" is stale anyway (the Material snackbar model). A navigation (a push, a pop, a
+tab switch) never closes a toast, so a "Saved" survives the navigation that follows the save. Keep
+the ref of an action toast and `dismiss()` it yourself as soon as it goes stale, for example when the user navigates away or
+takes the next action.
+
+```ts
+import { Component, inject, signal } from '@angular/core';
+import { BfButtonComponent } from '@bitforgehq/ui';
+import { type BfToastRef, BfToastService } from '@bitforgehq/ui/mobile';
+
+/**
+ * One Undo toast at a time.
+ *
+ * Each archive dismisses the previous Undo toast before it shows its own.
+ *
+ * @preview none
+ */
+@Component({
+  selector: 'app-example-toast-queueing',
+  imports: [BfButtonComponent],
+  template: `
+    <div class="flex flex-col items-start gap-3">
+      <bf-button (clicked)="open()">Archive</bf-button>
+      <p aria-live="polite" class="text-caption text-text-muted">{{ result() }}</p>
+    </div>
+  `,
+})
+export class ToastQueueingExampleComponent {
+  private readonly toasts = inject(BfToastService);
+  protected readonly result = signal('');
+  private undo: BfToastRef | null = null;
+
+  protected open(): void {
+    this.undo?.dismiss();
+    this.undo = this.toasts.show({
+      message: 'Archived',
+      action: { label: 'Undo', handler: () => this.result.set('Restored.') },
+    });
+    this.result.set('Archived.');
+  }
+}
+```
+
+## Desktop
+
+`BfToastService` shows one phone-width toast at a time and is meant for the Capacitor shell
+(`provideBfShell()`). On a desktop web app, use `BfDesktopToastService` from
+`@bitforgehq/ui/overlay` instead: it needs only `@angular/cdk`, no Capacitor and no router, stacks
+up to three cards in the bottom-right corner and follows the same rules (timing, actions, replacing,
+one announcement per toast). A toast never locks the page's scroll or makes it `inert`.
+
+```ts
+import { Component, inject, signal } from '@angular/core';
+import { BfButtonComponent } from '@bitforgehq/ui';
+import { BfDesktopToastService } from '@bitforgehq/ui/overlay';
+
+/**
+ * A toast and how it ended.
+ *
+ * `afterDismissed` resolves with the reason: `timeout`, `action` or `dismiss`.
+ */
+@Component({
+  selector: 'app-example-desktop-toast-basic',
+  imports: [BfButtonComponent],
+  template: `
+    <div class="flex flex-col items-start gap-3">
+      <bf-button (clicked)="save()">Save</bf-button>
+      <p aria-live="polite" class="text-caption text-text-muted">{{ result() }}</p>
+    </div>
+  `,
+})
+export class DesktopToastBasicExampleComponent {
+  private readonly toasts = inject(BfDesktopToastService);
+  protected readonly result = signal('');
+
+  protected async save(): Promise<void> {
+    const ref = this.toasts.show({ message: 'Changes saved' });
+    const reason = await ref.afterDismissed; // 'timeout' | 'action' | 'dismiss'
+    this.result.set(`The toast ended: ${reason}.`);
+  }
+}
+```
+
+## Theming
+
+- Pill: `bg-text text-bg` (the ink surface, inverted from the rest of the UI), `rounded-full`,
+  `shadow-floating`.
+- Action label: `text-bg` with an underline — `bf-button`'s `text` variant uses `text-primary`,
+  which has no contrast against the ink pill, so the action is a plain styled `<button>` instead.
+  Its hit area is 44 px tall (`min-h-hit`) and reaches into the pill's padding with negative margins,
+  so the pill keeps its 48 px height and its width. It shows a pointer cursor and fades to 80 %
+  opacity on hover.
+- Width: at most the viewport minus the 16 px gutter on each side.
+
+## Accessibility
+
+- Announcement: `BfToastService` announces each toast exactly once, politely, through the CDK
+  `LiveAnnouncer` (a persistent live region that exists before the toast does) as the toast
+  shows: the message, followed by the action label when there is one ("Task deleted. Undo"). A
+  queued toast is announced when it shows, never while it waits. The pill itself is not a live
+  region (no `role`, no `aria-live`), and the overlay pane around it has no role either, so
+  nothing is read twice.
+- Focus: the toast is opened `passive` on the overlay core: no backdrop, no focus trap, the page
+  behind it is never made `inert`, and it never moves focus — the action button is reachable by
+  Tab like any other control on the page.
+- Keyboard: `Escape` while focus is inside the toast dismisses it (resolving `'dismiss'`); the key
+  is claimed there, so it never also reaches a dialog. `Escape` elsewhere on the page is not the
+  toast's. There is no close button.
+- Focus return: when a toast that still holds focus closes for any reason (its action, `Escape`,
+  `dismiss()`, a replacing `show()`), focus returns, with `preventScroll`, to the element focused
+  last outside the toast — the one focused when it opened, or one focused since — if that element
+  is still in the page. Once focus has fallen to the page body (a click on empty space) there is no
+  such element and focus is not moved. A toast that no longer holds focus leaves it alone, and an
+  action `handler` that moves focus elsewhere keeps that. A mouse click on the action focuses it
+  in most browsers, so it returns focus the same way.
+- Timing: action toasts persist by default, and every toast pauses while hovered or focused (see
+  Duration).
+- Only one toast is ever visible, so announcements don't overlap. Under `prefers-reduced-motion` it
+  fades in and out without the 12 px slide.
+
+### Keyboard
+
+| Key                                 | Action                                                                                  |
+| ----------------------------------- | --------------------------------------------------------------------------------------- |
+| <kbd>Tab</kbd>                      | Reaches the action button in page order, like any control; the toast never takes focus  |
+| <kbd>Enter</kbd> / <kbd>Space</kbd> | Runs the focused action; the toast closes with `'action'`                               |
+| <kbd>Escape</kbd>                   | With focus inside the toast: dismisses it (`'dismiss'`); a dialog underneath stays open |
+
+## Notes
+
+### Do
+
+- Keep the message short — it truncates to two lines.
+- Keep the ref of a persistent toast and `dismiss()` it once it is stale (navigation, the next
+  action); the next `show()` replaces it anyway, but until then it stays up.
+- Give `action.handler` a fast, synchronous-feeling effect (undo, retry) — the toast closes right
+  after it runs.
+- Leave action toasts on their default (no timeout); if you set a `duration` on one, make it
+  generous and offer the same action somewhere persistent too.
+
+### Don't
+
+- Don't rely on the toast for anything the user must see — it can be missed, it waits in the queue
+  behind the one already up, and a persistent toast is replaced by the next `show()`.
+- Don't put more than one action in the pill; it holds a single action button.
+- Don't use a toast for anything the user must actively respond to before continuing — it never
+  traps focus or blocks the page; reach for a dialog or sheet instead.
+
+## Migration notes
+
+### 0.3.0
+
+The toast engine (timing, hold, replace, focus return, announcements, teardown) moved into
+`@bitforgehq/ui/overlay`, shared with the new desktop toast; `BfToastService` renders one toast at
+a time on it exactly as before. `BfToastRef`, `BfToastDismissReason` and `BfToastAction` are now
+also exported from `@bitforgehq/ui/overlay`; the `/mobile` exports stay (not deprecated) and are
+the same types and class. No behaviour change: a navigation never closes a toast (it opts out of
+the core's new `closeOnNavigation`).
+
+JSDoc of `toast.component.ts` for the API reference: `@summary`/`@since` on the exported symbols. No
+behaviour change.
+
+JSDoc of `toast.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:** `--bf-toast-keyboard` is written in the render phase (`afterRenderEffect`) instead
+of an `effect`; internal timing only, no API change.
+
+### 0.2.0
+
+New `BfToastService.show({ message, action?, duration, position })` in `@bitforgehq/ui/mobile`, a
+queued status pill on the overlay core opened `passive: true` (no backdrop, no focus trap, the page
+stays interactive and it never counts towards `BfOverlayStack.count()`). Only one toast shows at a
+time; later `show()` calls queue in order behind a timed toast and appear once it ends (a persistent
+one gives way, see the behaviour changes below). It returns a `BfToastRef` (`dismiss()`,
+`afterDismissed: Promise<'timeout' | 'action' | 'dismiss'>`) — the toast resolves `'timeout'` after
+`duration` ms (`0` keeps it up until `dismiss()` or its action; the default is 3000 without an
+action and 0 with one, see below), `'action'` when the optional action button is clicked (its
+`handler` runs first), and `'dismiss'` from `dismiss()`, whether the toast is showing or still
+queued. `bf-toast` is an ink `bg-text text-bg rounded-full shadow-floating` pill (message
+`line-clamp-2`, announced through `LiveAnnouncer`, see the "Changed" note below); the action renders
+as a plain underlined `text-bg` button rather than `bf-button`'s `text` variant, which has no
+contrast on the ink surface. `position: 'bottom'` (default) keeps 16 px clear of the floating tab
+bar (`--bf-tab-bar-inset-global` on `<html>`, see `### tabs`) and the soft keyboard, written live as
+`--bf-toast-keyboard`: `BfKeyboardService.height()` where the keyboard overlays the WebView (native
+iOS), `0` where the WebView already resizes (Android, the web); `position: 'top'` sits 16 px below
+the status bar instead, as a top margin (`mt-[calc(var(--spacing-safe-top)+var(--spacing)*4)]`)
+outside the pill: an earlier `pt-safe-top` on the host overrode the pill's own `py-3` (0 top padding
+on the web, about 50 px on a notched iPhone). Enter fades in with a 12 px slide from its anchored
+edge, exit is a plain fade; both collapse to a fade-only under `prefers-reduced-motion`.
+`provideBfShell()` now also provides `BfToastService`. The action button has a 44 px hit area
+(`min-h-hit px-3`) that reaches into the pill's padding (`-my-2.5 -mx-3`), so the pill keeps its 48
+px height and width.
+
+Fixed: the action button shows a pointer cursor and fades to 80 % opacity on hover.
+
+Changed: with the new tab-bar inset (see `### tabs`, which now includes 8 px above the bar) a
+bottom toast sits 16 px above the inset and so clears the floating tab bar by 24 px (was 16 px).
+
+Behaviour change: a toast with an `action` no longer auto-dismisses by default (`duration`
+defaults to `0` with an action, still `3000` without one; an explicit `duration` wins), so an
+"Undo" stays reachable for keyboard, switch and screen-reader users (WCAG 2.2.1). Every toast's
+timer pauses while the pointer is over it or focus is inside it and resumes with the remaining
+time. When a toast that holds focus closes (action or `dismiss()`), focus returns with
+`preventScroll` to the element it came from (the first `focusin`'s `relatedTarget`, else the
+element focused when it opened), if still in the page; before, it fell to `<body>`.
+
+Changed: toasts are announced through CDK `LiveAnnouncer` (`announce(text, 'polite')`, once per
+toast as it shows; the text is the message plus the action label). The `bf-toast` host no longer
+carries `role="status"`/`aria-live="polite"`: a live region inserted together with its text was
+not reliably announced. Tests locating the pill by `role="status"` should use `bf-toast`.
+
+Behaviour change: persistent toasts (`duration` 0, the default with an action) never block the
+queue — the next `show()` dismisses one, visible or still queued, resolving `'dismiss'` (the
+Material snackbar model; a timed toast still queues the next one). `Escape` while focus is inside a
+toast dismisses it (`'dismiss'`) and is claimed there. Focus returns only while the toast still
+holds focus at close time, to the element focused last outside it; once focus has fallen to the
+page body it is not moved to the element that was focused when the toast opened. The service ends
+every toast (timers and document listeners included) when its injector is destroyed, and the
+announcement joins a message ending in `:`, `;` or `,` to the action label with a space.