@bitforgehq/ui 0.3.0

package/ai/components/action-sheet.md

@@ -0,0 +1,526 @@
+# bf-action-sheet
+
+Bottom panel of labelled actions with a separate cancel button, destructive ones shown in red
+
+`BfActionSheetComponent` from `@bitforgehq/ui/mobile` · Overlays · since 0.2.0
+
+## Example
+
+```ts
+import { Component, inject, signal } from '@angular/core';
+import { BfButtonComponent } from '@bitforgehq/ui';
+import {
+  type BfActionSheetAction,
+  BfActionSheetService,
+  BfContentComponent,
+  BfHeaderComponent,
+  BfPageComponent,
+} from '@bitforgehq/ui/mobile';
+import { Copy, Share, Trash2 } from 'lucide';
+
+/** The showcase's rows: two plain actions with icons and a destructive one. */
+export const SHOWCASE_ACTIONS: readonly BfActionSheetAction[] = [
+  { label: 'Copy link', icon: Copy },
+  { label: 'Share', icon: Share },
+  { label: 'Delete', icon: Trash2, role: 'destructive' },
+];
+
+/** `bf-action-sheet` showcase: a button opens a titled action sheet with a destructive row. */
+@Component({
+  selector: 'app-action-sheet-showcase',
+  imports: [BfPageComponent, BfHeaderComponent, BfContentComponent, BfButtonComponent],
+  template: `
+    <bf-page data-showcase="action-sheet">
+      <bf-header title="Action sheet" [largeTitle]="false" />
+      <bf-content>
+        <div class="flex flex-col gap-4 p-4">
+          <p class="text-caption text-text-muted">
+            Tap a row to choose it; Cancel, the backdrop and Escape dismiss the sheet without a
+            choice.
+          </p>
+          <bf-button (clicked)="open()">Photo actions</bf-button>
+          <p data-showcase-result class="text-body">{{ result() }}</p>
+        </div>
+      </bf-content>
+    </bf-page>
+  `,
+})
+export class ActionSheetShowcasePage {
+  private readonly actionSheets = inject(BfActionSheetService);
+
+  protected readonly result = signal('Nothing chosen yet.');
+
+  async open(): Promise<void> {
+    const choice = await this.actionSheets.open({
+      title: 'Holiday photo',
+      actions: [...SHOWCASE_ACTIONS],
+    });
+    this.result.set(choice ? `Chose “${choice}”.` : 'Dismissed.');
+  }
+}
+```
+
+## Overview
+
+The action sheet panel that `BfActionSheetService.open()` renders on the overlay core
+(`position: 'bottom'`): an optional title above a `bf-list` of interactive rows for the
+actions (destructive ones in `text-danger`, an icon in the leading slot) and a separate
+`tonal` `bf-button` for the cancel action — rendered even when the caller passes none,
+labelled "Cancel", which takes the initial focus. Tapping a row resolves the overlay with its
+`id ?? label`; the cancel button, like
+the backdrop, `Escape` and the hardware back button, resolves `undefined`. Not used directly
+in templates.
+
+A bottom sheet of actions. `BfActionSheetService.open({ title?, actions })` renders `bf-action-sheet`
+on the overlay core: an optional title above a list of tappable rows and a separate cancel
+button. It resolves a `Promise` with the tapped row's `id` (its label when it has none), or
+`undefined` when the sheet is dismissed. You never place `<bf-action-sheet>` in a template yourself.
+
+## When to use
+
+Use `BfActionSheetService` in the Capacitor shell for a choice between a few actions on one item, raised from the bottom of the screen, with a separate Cancel. Use [BfAlertDialogService](https://bitforge-ui.web.app/api/bf-alert-dialog-service) instead for a yes/no question that must be answered, and [bf-menu](https://bitforge-ui.web.app/components/menu) on desktop.
+
+## Basic usage
+
+```ts
+import { Component, inject, signal } from '@angular/core';
+import { BfButtonComponent } from '@bitforgehq/ui';
+import { BfActionSheetService } from '@bitforgehq/ui/mobile';
+
+/**
+ * An action sheet that shares a list.
+ *
+ * `open()` resolves with the chosen action's label (its `id` when it has one), or `undefined` when
+ * dismissed.
+ *
+ * @preview none
+ */
+@Component({
+  selector: 'app-example-action-sheet-basic',
+  imports: [BfButtonComponent],
+  template: `
+    <div class="flex flex-col items-start gap-3">
+      <bf-button (clicked)="open()">Share…</bf-button>
+      <p aria-live="polite" class="text-caption text-text-muted">{{ result() }}</p>
+    </div>
+  `,
+})
+export class ActionSheetBasicExampleComponent {
+  private readonly sheets = inject(BfActionSheetService);
+  protected readonly result = signal('');
+
+  protected async open(): Promise<void> {
+    const label = await this.sheets.open({
+      title: 'Share list',
+      actions: [{ label: 'Copy link' }, { label: 'Send a copy' }],
+    });
+    this.result.set(label === 'Copy link' ? 'Link copied.' : (label ?? 'Dismissed.'));
+  }
+}
+```
+
+`open()` resolves once, either with the tapped row's `id ?? label` or with `undefined` — tapping
+the cancel button, a backdrop tap, `Escape` and the hardware back button all resolve `undefined`.
+
+## Answers with ids
+
+Give each row an `id` and compare against it, so the check survives translated labels and two
+rows with the same label stay distinct. A row without an `id` answers with its label.
+
+```ts
+import { Component, inject, signal } from '@angular/core';
+import { BfButtonComponent } from '@bitforgehq/ui';
+import { BfActionSheetService } from '@bitforgehq/ui/mobile';
+
+/** The app's translated labels (German here): the ids, not these, carry the answer. */
+const LABELS = { share: 'Teilen', delete: 'Löschen' };
+
+/**
+ * Actions answered by id.
+ *
+ * Each action has an `id`, so the answer stays the same whatever the translated
+ * label says.
+ *
+ * @preview none
+ */
+@Component({
+  selector: 'app-example-action-sheet-ids',
+  imports: [BfButtonComponent],
+  template: `
+    <div class="flex flex-col items-start gap-3">
+      <bf-button (clicked)="open()">Actions</bf-button>
+      <p aria-live="polite" class="text-caption text-text-muted">{{ result() }}</p>
+    </div>
+  `,
+})
+export class ActionSheetIdsExampleComponent {
+  private readonly sheets = inject(BfActionSheetService);
+  protected readonly result = signal('');
+
+  protected async open(): Promise<void> {
+    const answer = await this.sheets.open({
+      actions: [
+        { id: 'share', label: LABELS.share },
+        { id: 'delete', label: LABELS.delete, role: 'destructive' },
+      ],
+    });
+    this.result.set(answer === 'delete' ? 'List deleted.' : (answer ?? 'Dismissed.'));
+  }
+}
+```
+
+## Destructive actions
+
+An action with `role: 'destructive'` renders its label in `text-danger` instead of the default
+text color; nothing else changes.
+
+```ts
+import { Component, inject, signal } from '@angular/core';
+import { BfButtonComponent } from '@bitforgehq/ui';
+import { BfActionSheetService } from '@bitforgehq/ui/mobile';
+
+/**
+ * A destructive action.
+ *
+ * `role: 'destructive'` renders the action in the danger colour.
+ *
+ * @preview none
+ */
+@Component({
+  selector: 'app-example-action-sheet-destructive',
+  imports: [BfButtonComponent],
+  template: `
+    <div class="flex flex-col items-start gap-3">
+      <bf-button variant="danger" (clicked)="open()">Delete list…</bf-button>
+      <p aria-live="polite" class="text-caption text-text-muted">{{ result() }}</p>
+    </div>
+  `,
+})
+export class ActionSheetDestructiveExampleComponent {
+  private readonly sheets = inject(BfActionSheetService);
+  protected readonly result = signal('');
+
+  protected async open(): Promise<void> {
+    const label = await this.sheets.open({
+      title: 'Delete list?',
+      actions: [{ label: 'Delete', role: 'destructive' }],
+    });
+    this.result.set(label ? 'Deleted.' : 'Kept.');
+  }
+}
+```
+
+## Icons
+
+Pass `icon` (a Lucide `IconNode`, e.g. `Share` from `lucide`) to render it in the row's leading
+slot.
+
+```ts
+import { Component, inject, signal } from '@angular/core';
+import { BfButtonComponent } from '@bitforgehq/ui';
+import { BfActionSheetService } from '@bitforgehq/ui/mobile';
+import { Share, Trash2 } from 'lucide';
+
+/**
+ * Actions with icons.
+ *
+ * Pass Lucide icon data as `icon`; it renders before the label.
+ *
+ * @preview none
+ */
+@Component({
+  selector: 'app-example-action-sheet-icons',
+  imports: [BfButtonComponent],
+  template: `
+    <div class="flex flex-col items-start gap-3">
+      <bf-button (clicked)="open()">More</bf-button>
+      <p aria-live="polite" class="text-caption text-text-muted">{{ result() }}</p>
+    </div>
+  `,
+})
+export class ActionSheetIconsExampleComponent {
+  private readonly sheets = inject(BfActionSheetService);
+  protected readonly result = signal('');
+
+  protected async open(): Promise<void> {
+    const label = await this.sheets.open({
+      actions: [
+        { label: 'Share', icon: Share },
+        { label: 'Delete', icon: Trash2, role: 'destructive' },
+      ],
+    });
+    this.result.set(label ?? 'Dismissed.');
+  }
+}
+```
+
+## Cancel button
+
+A separate `tonal` `bf-button` always sits under the rows. Give one of your `actions` `role:
+'cancel'` to control its label; without one, the sheet adds a cancel button of its own, labelled with `provideBfLabels()`'s `cancel` ("Cancel") — either
+way, tapping it resolves `afterClosed`/`open()` with `undefined` (an `id` on it is ignored), and it
+never appears as a row. It takes the initial focus.
+Only the first `cancel`-role action is used; any further `cancel`-role actions are ignored.
+
+```ts
+import { Component, inject, signal } from '@angular/core';
+import { BfButtonComponent } from '@bitforgehq/ui';
+import { BfActionSheetService } from '@bitforgehq/ui/mobile';
+
+/**
+ * A sheet with its own cancel action.
+ *
+ * A `cancel`-role action replaces the built-in Cancel button and answers a dismissal.
+ *
+ * @preview none
+ */
+@Component({
+  selector: 'app-example-action-sheet-cancel',
+  imports: [BfButtonComponent],
+  template: `
+    <div class="flex flex-col items-start gap-3">
+      <bf-button (clicked)="open()">Close editor</bf-button>
+      <p aria-live="polite" class="text-caption text-text-muted">{{ result() }}</p>
+    </div>
+  `,
+})
+export class ActionSheetCancelExampleComponent {
+  private readonly sheets = inject(BfActionSheetService);
+  protected readonly result = signal('');
+
+  protected async open(): Promise<void> {
+    const label = await this.sheets.open({
+      actions: [
+        { label: 'Discard changes', role: 'destructive' },
+        { label: "Don't discard", role: 'cancel' },
+      ],
+    });
+    this.result.set(label ?? 'Dismissed.');
+  }
+}
+```
+
+## Navigation
+
+A navigation to another URL path closes the action sheet and `open()` resolves `undefined`, as
+its cancel button does. A query- or fragment-only change leaves it open. In the `/mobile` shell
+every push, every pop (the header back button, swipe-back, `BfNavController.back()`) and every tab
+switch changes the path, so an action sheet opened on a page closes when that page is left. The
+Android hardware back button with an action sheet open closes the action sheet only (its handler
+runs at priority 100, above the page pop), so one press never closes it and pops the page as
+well. Android back in a browser without Capacitor (Chrome, a PWA) does the same where
+`CloseWatcher` exists: it closes the action sheet, resolving `undefined`, and leaves the URL
+alone. An action sheet opened before the first navigation ends closes when the start URL
+redirects. Pass `closeOnNavigation: false` to keep it open.
+
+```ts
+import { Component, inject, signal } from '@angular/core';
+import { BfButtonComponent } from '@bitforgehq/ui';
+import { BfActionSheetService } from '@bitforgehq/ui/mobile';
+
+/**
+ * An action sheet that stays open across navigations.
+ *
+ * `closeOnNavigation: false` keeps it open when the route changes underneath.
+ *
+ * @preview none
+ */
+@Component({
+  selector: 'app-example-action-sheet-navigation',
+  imports: [BfButtonComponent],
+  template: `
+    <div class="flex flex-col items-start gap-3">
+      <bf-button (clicked)="open()">Actions</bf-button>
+      <p aria-live="polite" class="text-caption text-text-muted">{{ result() }}</p>
+    </div>
+  `,
+})
+export class ActionSheetNavigationExampleComponent {
+  private readonly sheets = inject(BfActionSheetService);
+  protected readonly result = signal('');
+  private readonly actions = [{ label: 'Pin' }, { label: 'Archive' }];
+
+  protected async open(): Promise<void> {
+    const answer = await this.sheets.open({ actions: this.actions, closeOnNavigation: false });
+    this.result.set(answer ?? 'Dismissed.');
+  }
+}
+```
+
+## Labels and the injector
+
+Default strings come from `provideBfLabels()` (`cancel` "Cancel", `actions` "Actions"). 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 action 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 { BfActionSheetService } from '@bitforgehq/ui/mobile';
+
+/**
+ * An action sheet that reads a feature's labels.
+ *
+ * This feature provides German labels; the service is a root singleton, so passing the opener's
+ * injector is what makes the sheet's Cancel button read "Abbrechen" and its name "Aktionen".
+ *
+ * @preview none
+ */
+@Component({
+  selector: 'app-example-action-sheet-injector',
+  imports: [BfButtonComponent],
+  providers: [provideBfLabels({ cancel: 'Abbrechen', actions: 'Aktionen' })],
+  template: `<bf-button (clicked)="open()">Aktionen</bf-button>`,
+})
+export class ActionSheetInjectorExampleComponent {
+  private readonly actionSheets = inject(BfActionSheetService);
+  private readonly injector = inject(Injector);
+  private readonly actions = [{ label: 'Anheften' }, { label: 'Archivieren' }];
+
+  protected open(): void {
+    void this.actionSheets.open({ actions: this.actions, injector: this.injector });
+  }
+}
+```
+
+## Desktop
+
+`bf-action-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.
+
+A list of actions belongs in a `bf-menu`, opened by a `bf-menu-button` next to the thing it acts on;
+a single destructive choice in `BfDialogService.confirm()`.
+
+```ts
+import { Component, signal } from '@angular/core';
+import {
+  BfMenuButtonComponent,
+  BfMenuComponent,
+  BfMenuItemDirective,
+} from '@bitforgehq/ui/overlay';
+
+/**
+ * Row actions in a menu.
+ *
+ * A `bf-menu-button` opens the menu; each item reports its `triggered`, and Archive is disabled.
+ */
+@Component({
+  selector: 'app-example-menu-basic',
+  imports: [BfMenuButtonComponent, BfMenuComponent, BfMenuItemDirective],
+  template: `
+    <bf-menu-button [menu]="rowActions">Actions</bf-menu-button>
+    <p aria-live="polite" class="text-caption text-text-muted mt-3">{{ result() }}</p>
+
+    <ng-template #rowActions>
+      <bf-menu>
+        <button bfMenuItem (triggered)="result.set('Renamed.')">Rename</button>
+        <button bfMenuItem (triggered)="result.set('Duplicated.')">Duplicate</button>
+        <button bfMenuItem bfMenuItemDisabled>Archive</button>
+      </bf-menu>
+    </ng-template>
+  `,
+})
+export class MenuBasicExampleComponent {
+  protected readonly result = signal('');
+}
+```
+
+## Theming
+
+- Panel: `bg-surface`, `rounded-t-card` (`--radius-card`), `shadow-floating`, `w-screen` (edge to
+  edge), `pb-[max(var(--spacing-safe-bottom),16px)]` (the safe area, at least 16 px).
+- Title: `text-caption text-text-muted`.
+- Rows: `bf-list-item` (`text-danger` for destructive labels); Backdrop: `bf-overlay-backdrop`
+  from the overlay core (a black scrim: 40 % in light mode, 60 % in dark).
+- Cancel button: `bf-button variant="tonal" [fullWidth]="true"`, spanning the panel.
+- Inset: `px-3` (12 px), deliberately tighter than the 16 px screen gutter: the rows add their own
+  14 px padding, so row text still sits 26 px from the screen edge.
+
+## Accessibility
+
+The overlay panel is a `role="dialog"` with `aria-modal="true"` and an `aria-label` from `title`
+(default `provideBfLabels()`'s `actions`, "Actions"); the page stack behind it is `inert`. Focus starts on the cancel button, the
+least destructive choice, even when a destructive row comes first; Shift+Tab reaches the rows. Tab
+is trapped inside, and focus returns to the element that
+opened the sheet on close. `Escape`, a backdrop tap and the hardware back button all resolve
+`undefined`. Under `prefers-reduced-motion` the panel cross-fades in and out instead of sliding.
+
+### Keyboard
+
+| Key                                              | Action                                                                               |
+| ------------------------------------------------ | ------------------------------------------------------------------------------------ |
+| <kbd>Tab</kbd> / <kbd>Shift</kbd>+<kbd>Tab</kbd> | Moves between the rows and Cancel, wrapping inside the sheet; focus starts on Cancel |
+| <kbd>Enter</kbd> / <kbd>Space</kbd>              | Activates the focused row or Cancel                                                  |
+| <kbd>Escape</kbd>                                | Closes the sheet; the promise resolves `undefined`                                   |
+
+## Notes
+
+### Do
+
+- Order destructive actions clearly and keep the cancel action's intent obvious ("Discard",
+  "Keep editing") rather than relying on its position alone.
+- Give the sheet a `title` when the actions need context ("Delete list?", "Share via").
+- Use icons consistently — either every row has one, or none does.
+
+### Don't
+
+- Don't put more than one destructive action in the same sheet; ask a confirming alert dialog
+  instead for anything hard to undo.
+- Don't rely on the synthesized "Cancel" label meaning "no" for a destructive prompt — pass an
+  explicit `cancel`-role action with wording that matches ("Keep list").
+- Don't use an action sheet for a single choice with only one outcome; use `BfAlertDialogService`
+  for confirmations that need a message.
+
+## Migration notes
+
+### 0.3.0
+
+New exported `BfActionSheetActionRole` (`'destructive' | 'cancel'`), the type of
+`BfActionSheetAction.role` (was an inline union with the same values).
+
+**Behaviour:** a navigation to another URL path closes it, resolving `undefined`; new
+`closeOnNavigation` option (default true). Migration: pass `closeOnNavigation: false` to keep it
+open (see Migration 19).
+
+**Behaviour:** the synthesized cancel button is labelled with `provideBfLabels()`'s `cancel`
+("Cancel"), and a sheet without `title` is named by its `actions` label ("Actions").
+
+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 action sheet.
+
+`BfActionSheetAction` gains `id?: string`; `open()` resolves the tapped row's `id ?? label` (the
+cancel action still resolves `undefined`). Rows render with `track $index`, so two rows with the
+same label both render.
+
+**Behaviour:** focus starts on the cancel button, not the first row (see Migration 17).
+
+JSDoc of `action-sheet.component.ts` for the API reference: `@summary`/`@since` on the exported
+symbols. No behaviour change.
+
+JSDoc of `action-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.
+
+The docs say that Android back in a browser with `CloseWatcher` closes the action sheet, resolving
+`undefined`; see `### overlay core` and Migration 35.
+
+### 0.2.0
+
+New `BfActionSheetService.open({ title?, actions })` in `@bitforgehq/ui/mobile`, resolving
+`Promise<string | undefined>`. Renders `bf-action-sheet` on the overlay core (`position:
+'bottom'`, back priority 100, not counted as a modal, `role="dialog"` with `aria-label` = `title`
+or "Actions"; slides up on open and down on close). The panel (`bg-surface rounded-t-card
+shadow-floating w-screen px-3 pt-3 pb-[max(var(--spacing-safe-bottom),16px)]`, spanning the
+screen with at least 16 px under the cancel button) is an optional `title` caption over a `bf-list
+[inset]="false"` of the non-`cancel` `actions` as interactive rows (an icon from `icon` in the
+leading slot; `destructive`-role labels render `text-danger`, projected through the row's default
+slot since `bf-list-item` has no way to colour its own title), and a separate `tonal` `bf-button`
+(`fullWidth`) for the cancel action — the caller's first `cancel`-role entry if any (further ones are
+ignored), else a synthesized "Cancel". Destructive labels truncate like the other rows.
+Tapping a row resolves with its label; the cancel button, a backdrop tap, `Escape` and the
+hardware back button all resolve `undefined` (the overlay core's defaults, unchanged). The panel's
+`px-3` inset is deliberately tighter than the 16 px gutter: the rows add their own 14 px.
+`provideBfShell()` now also provides `BfActionSheetService`.