@bitforgehq/ui 0.3.0

package/ai/components/desktop-toast.md

@@ -0,0 +1,420 @@
+# bf-desktop-toast
+
+Desktop notification card in a bottom corner stack of up to three
+
+`BfDesktopToastComponent` from `@bitforgehq/ui/overlay` · Overlays · since 0.3.0
+
+## Example
+
+```ts
+import { Component, inject, signal } from '@angular/core';
+import { BfButtonComponent } from '@bitforgehq/ui';
+import { BfDesktopToastService, type BfToastRef } from '@bitforgehq/ui/overlay';
+
+/**
+ * The bf-desktop-toast overview.
+ *
+ * Live demo of `BfDesktopToastService`: "Show toast" shows a timed toast, "Delete with undo" a
+ * persistent one with an Undo action, "Show three" fills the stack. The toasts appear in the
+ * page's bottom-right corner; the status line reports how the Undo toast ended. The triggers and
+ * the status line carry `data-testid`s for the end-to-end suite.
+ */
+@Component({
+  selector: 'app-example-desktop-toast-overview',
+  imports: [BfButtonComponent],
+  template: `
+    <div class="flex flex-col gap-4">
+      <div class="flex flex-wrap gap-2">
+        <bf-button data-testid="toast-show" (clicked)="showOne()">Show toast</bf-button>
+        <bf-button data-testid="toast-undo" variant="outline" (clicked)="deleteWithUndo()"
+          >Delete with undo</bf-button
+        >
+        <bf-button data-testid="toast-three" variant="tonal" (clicked)="showThree()"
+          >Show three</bf-button
+        >
+      </div>
+      <p data-status data-testid="toast-result" class="text-caption text-text-muted">
+        {{ result() }}
+      </p>
+    </div>
+  `,
+})
+export class DesktopToastOverviewExampleComponent {
+  private readonly toasts = inject(BfDesktopToastService);
+  private undo: BfToastRef | null = null;
+
+  readonly result = signal('');
+
+  showOne(): void {
+    this.toasts.show({ message: 'Changes saved' });
+  }
+
+  async deleteWithUndo(): Promise<void> {
+    this.undo?.dismiss();
+    const ref = this.toasts.show({
+      message: 'Invoice INV-204 deleted',
+      action: { label: 'Undo', handler: () => this.result.set('Restored INV-204.') },
+    });
+    this.undo = ref;
+    const reason = await ref.afterDismissed;
+    if (this.undo === ref) {
+      this.undo = null;
+    }
+    if (reason !== 'action') {
+      this.result.set('INV-204 stays deleted (not really, this is a demo).');
+    }
+  }
+
+  showThree(): void {
+    this.toasts.show({ message: 'Export started' });
+    this.toasts.show({ message: '3 files uploaded' });
+    this.toasts.show({ message: 'Report shared with the team' });
+  }
+}
+```
+
+## Overview
+
+The card `BfDesktopToastService.show()` renders in its notification stack: the message and an
+optional action button on a surface card. It is not a live region (the service announces each
+toast once through CDK `LiveAnnouncer`) and has no close button; `Escape` with focus inside it
+emits `escaped`, which dismisses the toast. Apps do not place it in templates.
+
+Desktop notifications for web apps, from `@bitforgehq/ui/overlay` (needs `@angular/cdk`, no
+Capacitor). `BfDesktopToastService.show(options)` adds a `bf-desktop-toast` card to a stack in
+the bottom-right corner of the viewport (bottom left in right-to-left pages) and returns a
+`BfToastRef`. Up to three toasts are visible at once; later ones wait and show as earlier ones
+end. You never place `<bf-desktop-toast>` in a template yourself. For Capacitor apps use the
+`/mobile` `BfToastService`, which follows the same rules one toast at a time.
+
+## When to use
+
+Use `BfDesktopToastService` in a desktop web app for a short status after an action, with at most one follow-up: "Saved", "Invoice deleted. Undo". Use [bf-alert](https://bitforge-ui.web.app/components/alert) instead for a message that must stay on the page, [BfDialogService](https://bitforge-ui.web.app/api/bf-dialog-service) `confirm()` when the user must answer, and the `/mobile` [BfToastService](https://bitforge-ui.web.app/api/bf-toast-service) in a Capacitor app.
+
+## Basic usage
+
+```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}.`);
+  }
+}
+```
+
+`dismiss()` ends the toast right away: it closes a visible toast, or drops a waiting one before
+it ever shows.
+
+```ts
+import { Component, inject } from '@angular/core';
+import { BfButtonComponent } from '@bitforgehq/ui';
+import { BfDesktopToastService, type BfToastRef } from '@bitforgehq/ui/overlay';
+
+/**
+ * A toast that stays until it is dismissed.
+ *
+ * `duration: 0` keeps "Syncing…" up; `dismiss()` ends it when the work is done.
+ */
+@Component({
+  selector: 'app-example-desktop-toast-persistent',
+  imports: [BfButtonComponent],
+  template: `
+    <div class="flex flex-wrap gap-2">
+      <bf-button variant="outline" (clicked)="start()">Start sync</bf-button>
+      <bf-button variant="text" (clicked)="finish()">Finish sync</bf-button>
+    </div>
+  `,
+})
+export class DesktopToastPersistentExampleComponent {
+  private readonly toasts = inject(BfDesktopToastService);
+  private ref: BfToastRef | null = null;
+
+  protected start(): void {
+    this.ref?.dismiss();
+    this.ref = this.toasts.show({ message: 'Syncing…', duration: 0 });
+  }
+
+  protected finish(): void {
+    this.ref?.dismiss();
+    this.ref = null;
+  }
+}
+```
+
+## Action
+
+`action` renders a real `<button>` in the card. Its `handler` runs before the toast closes with
+reason `'action'`. A toast with an action stays until the action, `Escape` or `dismiss()` ends it
+(see Timing), so keyboard, switch and screen-reader users can reach it.
+
+```ts
+import { Component, inject, signal } from '@angular/core';
+import { BfButtonComponent } from '@bitforgehq/ui';
+import { BfDesktopToastService } from '@bitforgehq/ui/overlay';
+
+/** A toast with an Undo action; it stays until Undo, Escape or a dismissal ends it. */
+@Component({
+  selector: 'app-example-desktop-toast-action',
+  imports: [BfButtonComponent],
+  template: `
+    <div class="flex flex-col items-start gap-3">
+      <bf-button variant="danger" (clicked)="remove()">Delete INV-204</bf-button>
+      <p aria-live="polite" class="text-caption text-text-muted">{{ result() }}</p>
+    </div>
+  `,
+})
+export class DesktopToastActionExampleComponent {
+  private readonly toasts = inject(BfDesktopToastService);
+  protected readonly result = signal('');
+
+  protected remove(): void {
+    this.result.set('INV-204 deleted.');
+    this.toasts.show({
+      message: 'Invoice INV-204 deleted',
+      action: { label: 'Undo', handler: () => this.result.set('INV-204 restored.') },
+    });
+  }
+}
+```
+
+## Timing
+
+`duration` (ms) is how long a toast stays before it ends with `'timeout'`. The default is `3000`
+for a toast without an action and `0` (persistent) for one with an action: an "Undo" that
+vanishes after 3 seconds is out of reach for many keyboard and screen-reader users
+([WCAG 2.2.1 Timing Adjustable](https://www.w3.org/WAI/WCAG22/Understanding/timing-adjustable)).
+An explicit `duration` always wins.
+
+While the pointer is over the stack or focus is inside it, **every** visible toast pauses, and
+each resumes with the time it had left once both have left. The stack never reflows under the
+reader's pointer. The oldest toast leaves first, because its timer started first.
+
+## Stacking and replacing
+
+Up to `maxVisible` toasts (default 3) are visible at once, the newest nearest the anchored edge
+(at the bottom of a bottom stack, at the top of a top stack). A `show()` while the stack is full
+waits in order and shows once a visible toast ends.
+
+A persistent toast (`duration: 0`, the default with an action) never blocks the queue: the next
+`show()` dismisses every persistent toast, visible or waiting, and each resolves `'dismiss'`. A
+superseded "Undo" is stale anyway. A navigation never closes a toast (a "Saved" survives the
+navigation that follows the save), so keep the ref of an action toast and `dismiss()` it once it
+is stale, for example when the user navigates away.
+
+```ts
+import { Component, inject, signal } from '@angular/core';
+import { BfButtonComponent } from '@bitforgehq/ui';
+import { BfDesktopToastService, type BfToastRef } from '@bitforgehq/ui/overlay';
+
+/**
+ * One Undo toast at a time.
+ *
+ * Each archive dismisses the previous Undo toast before it shows its own.
+ */
+@Component({
+  selector: 'app-example-desktop-toast-replace',
+  imports: [BfButtonComponent],
+  template: `
+    <div class="flex flex-col items-start gap-3">
+      <bf-button variant="outline" (clicked)="archive()">Archive the next task</bf-button>
+      <p class="text-caption text-text-muted">{{ archived() }} archived</p>
+    </div>
+  `,
+})
+export class DesktopToastReplaceExampleComponent {
+  private readonly toasts = inject(BfDesktopToastService);
+  private undo: BfToastRef | null = null;
+  protected readonly archived = signal(0);
+
+  protected archive(): void {
+    this.archived.update((n) => n + 1);
+    this.undo?.dismiss();
+    this.undo = this.toasts.show({
+      message: 'Archived',
+      action: { label: 'Undo', handler: () => this.restore() },
+    });
+  }
+
+  private restore(): void {
+    this.archived.update((n) => n - 1);
+  }
+}
+```
+
+## Position and configuration
+
+`provideBfDesktopToast()` in `ApplicationConfig.providers` sets `position`
+(`'bottom-end'` (default), `'bottom-center'`, `'top-end'` or `'top-center'`), `maxVisible`
+(default 3) and `ariaLabel` (the region's name; empty uses the `notifications` label). The stack
+sits 24 px in from the viewport edges plus the safe-area inset (the end edge is the left one in a
+right-to-left page, with the left safe area). Cards are 24 rem wide, capped at
+the viewport width minus a 16 px gutter on each side.
+
+```ts
+import { type ApplicationConfig, Component, inject } from '@angular/core';
+import { BfButtonComponent } from '@bitforgehq/ui';
+import { BfDesktopToastService, provideBfDesktopToast } from '@bitforgehq/ui/overlay';
+
+/** The app's providers: toasts at the top centre, at most two at once. */
+export const appConfig: ApplicationConfig = {
+  providers: [provideBfDesktopToast({ position: 'top-center', maxVisible: 2 })],
+};
+
+/**
+ * The toast position and stack size, set once for the app.
+ *
+ * `provideBfDesktopToast()` goes in the application config; every `show()` then uses it.
+ *
+ * @preview none
+ */
+@Component({
+  selector: 'app-example-desktop-toast-config',
+  imports: [BfButtonComponent],
+  template: `<bf-button (clicked)="notify()">Notify</bf-button>`,
+})
+export class DesktopToastConfigExampleComponent {
+  private readonly toasts = inject(BfDesktopToastService);
+
+  protected notify(): void {
+    this.toasts.show({ message: 'Shown at the top centre' });
+  }
+}
+```
+
+The region's name comes from `provideBfLabels({ notifications })`. The service is a root
+singleton: pass the feature's injector with the toast, `show({ message, injector:
+inject(Injector) })`, so a feature-level `provideBfLabels()` names the region that toast opens.
+
+## Desktop
+
+Built for desktop: the stack sits in the bottom-end corner, clear of the page's own controls. While the pointer is over the stack every visible toast pauses, and the stack never reflows under it. The action underlines on hover and shows the focus ring on keyboard focus only. Tell keyboard users about <kbd>F6</kbd>, since the stack comes after the page in the tab order.
+
+## Theming
+
+- Card: `bg-surface text-text`, a 1 px `border-border`, `rounded-card`, `shadow-floating`,
+  `text-body`.
+- Action: `text-primary-strong`, bold, underlined on hover, with the focus ring (`ring-ring`).
+- Width: `min(24rem, 100vw - 2 × --spacing-gutter)`.
+
+## Accessibility
+
+- Announcement: each toast is announced exactly once, politely, through the CDK `LiveAnnouncer`
+  as it shows: the message, then the action label ("Invoice INV-204 deleted. Undo"). A waiting
+  toast is announced when it shows. Neither the card nor the stack is a live region (no
+  `aria-live`, no `role="status"`), so nothing is read twice
+  ([WCAG 4.1.3 Status Messages](https://www.w3.org/WAI/WCAG22/Understanding/status-messages)).
+- Landmark: the stack is a `region` named "Notifications" (the `notifications` label or
+  `ariaLabel`). Screen-reader users can jump to it from the landmarks list. It exists only while a
+  toast is visible.
+- Focus: showing a toast never moves focus. There is no backdrop, no focus trap, no scroll lock,
+  and nothing becomes `inert`. The stack is rendered at the end of the page, so Tab reaches the
+  action button only after the page content, which is impractical on a long page.
+- `F6` shortcut: while a toast with an action is visible, `F6` (without Ctrl, Alt or Meta) moves
+  focus to the action of the newest such toast, and `F6` again inside the stack moves focus back
+  to where it was (landmark-region navigation, as in the
+  [APG landmark regions practice](https://www.w3.org/WAI/ARIA/apg/practices/landmark-regions/)).
+  Without an action toast the key is left to the browser. `F6` does nothing while a modal overlay
+  is open (`BfDialogService`, the `/mobile` sheet, modal or alert): its focus trap is APG-modal, so
+  the toast stays reachable only by pointer until the modal closes. Browsers also use `F6` to move
+  between the address bar and the page; where a browser keeps the key for itself, only Tab reaches
+  the action. Tell keyboard users about the shortcut (for example in your app's keyboard help), and
+  offer the same action somewhere persistent.
+- Keyboard: `Escape` while focus is inside a toast dismisses it (`'dismiss'`). The key is claimed
+  there, so a dialog underneath does not also close. There is no close button: a timed toast
+  times out, and a persistent one ends with its action, `Escape`, `dismiss()` or the next
+  `show()`.
+- Focus return: when a toast that holds focus closes, focus returns to the element focused last
+  outside it, if that element is still in the page.
+- Timing: pointer over the stack or focus inside it pauses every visible toast (see Timing).
+- Motion: a card fades in while sliding 8 px in from the anchored edge and fades out. Under
+  `prefers-reduced-motion` it only fades.
+
+### Keyboard
+
+| Key                                 | Action                                                                                                                           |
+| ----------------------------------- | -------------------------------------------------------------------------------------------------------------------------------- |
+| <kbd>F6</kbd>                       | From the page: moves focus to the action of the newest toast that has one; inside the stack: moves it back to where it came from |
+| <kbd>Tab</kbd>                      | Reaches the toast actions after the page content                                                                                 |
+| <kbd>Enter</kbd> / <kbd>Space</kbd> | Runs the focused action; the toast closes with `'action'`                                                                        |
+| <kbd>Escape</kbd>                   | With focus inside a toast: dismisses it (`'dismiss'`); a dialog underneath stays open                                            |
+
+## Inputs
+
+| Name          | Type     | Default  | Description                                         |
+| ------------- | -------- | -------- | --------------------------------------------------- |
+| `message`     | `string` | required | Text of the toast; long words wrap.                 |
+| `actionLabel` | `string` | `''`     | Text of the action button; empty renders no button. |
+
+## Outputs
+
+| Name            | Payload | Description                                                            |
+| --------------- | ------- | ---------------------------------------------------------------------- |
+| `actionClicked` | `void`  | The action button was clicked.                                         |
+| `escaped`       | `void`  | `Escape` was pressed with focus inside the toast (the key is claimed). |
+
+## Notes
+
+### Do
+
+- Keep the message short, one sentence, and make the action a single verb ("Undo", "Retry",
+  "View").
+- Keep the ref of a persistent toast and `dismiss()` it once it is stale.
+- Offer anything you put in a toast's action somewhere persistent as well.
+
+### Don't
+
+- Don't use a toast for something the user must see or answer before continuing. Use a dialog
+  (`BfDialogService.confirm()`) instead.
+- Don't show a toast for every background event. Three are visible at most, and the rest wait.
+- Don't set a short `duration` on a toast with an action.
+
+## Migration notes
+
+### 0.3.0
+
+The card's action button output is `actionClicked` (an action emits `clicked`, a sub-part's
+action `<part>Clicked`); `BfDesktopToastService` binds it.
+
+New `BfDesktopToastService` and `bf-desktop-toast` in `@bitforgehq/ui/overlay`: toasts for desktop
+and web apps with no Capacitor dependency. `show({ message, action?, duration?, injector? })`
+returns a `BfToastRef` and follows the `/mobile` toast's rules: 3000 ms by default, persistent
+(`duration` 0) with an action, a later `show()` replaces every persistent toast (`'dismiss'`),
+`Escape` inside a toast dismisses it, focus returns only when it was inside the closing toast, one
+polite `LiveAnnouncer` announcement per toast, everything ends with the injector. Up to three
+cards are visible at once in one passive overlay pane, bottom right (bottom left in RTL) 24 px in
+plus the safe area, the newest nearest the edge; later toasts wait. The pointer over the stack or
+focus inside it pauses every visible toast. The stack is a `region` named by the new
+`notifications` label ("Notifications"); no backdrop, no focus move, no scroll lock, nothing
+`inert`. Cards fade in with an 8 px slide (a fade under reduced motion). A navigation never closes
+a toast. `F6` from the page moves focus to the action of the newest toast that has one, and `F6`
+inside the stack moves it back (the key is left to the browser otherwise). In a right-to-left page
+the end inset reads the left safe area (`--spacing-safe-left`).
+`provideBfDesktopToast(config)` sets `position` (`'bottom-end'` (default), `'bottom-center'`,
+`'top-end'` or `'top-center'`), `maxVisible` (default 3) and `ariaLabel` (the region name; empty
+uses the label), over `BF_DESKTOP_TOAST_DEFAULTS`.
+
+JSDoc of `desktop-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.