@bitforgehq/ui 0.3.0

package/ai/components/toggle.md

@@ -0,0 +1,387 @@
+# bf-toggle
+
+On/off switch for settings that apply immediately, with Signal Forms binding
+
+`BfToggleComponent` from `@bitforgehq/ui` · Forms · since 0.1.0
+
+## Example
+
+```ts
+import { Component, computed, signal } from '@angular/core';
+import { BfToggleComponent } from '@bitforgehq/ui';
+
+/**
+ * The bf-toggle overview.
+ *
+ * Live demo of `bf-toggle`: a default switch and a label-first switch in a constrained row; then the sm, md and lg sizes in a row.
+ */
+@Component({
+  selector: 'app-example-toggle-overview',
+  imports: [BfToggleComponent],
+  template: `
+    <div class="flex flex-col gap-3">
+      <bf-toggle label="Notifications" [(checked)]="notifications" />
+      <div class="w-64">
+        <bf-toggle label="Weekly summary" labelPosition="start" [(checked)]="weeklySummary" />
+      </div>
+      <bf-toggle label="Disabled" [disabled]="true" />
+      <p data-status aria-live="polite" class="text-caption text-text-muted">{{ status() }}</p>
+      <div data-sizes class="flex flex-wrap items-center gap-3">
+        <bf-toggle size="sm" label="sm · 32 px" [checked]="true" />
+        <bf-toggle label="md · 40 px" [checked]="true" />
+        <bf-toggle size="lg" label="lg · 48 px" [checked]="true" />
+      </div>
+    </div>
+  `,
+})
+export class ToggleOverviewExampleComponent {
+  readonly notifications = signal(true);
+  readonly weeklySummary = signal(false);
+
+  readonly status = computed(
+    () =>
+      `Notifications ${this.notifications() ? 'on' : 'off'} · Weekly summary ${this.weeklySummary() ? 'on' : 'off'}`,
+  );
+}
+```
+
+## Overview
+
+On/off switch for settings that apply immediately. Implements the Signal Forms checkbox contract.
+
+A switch for settings that take effect immediately: notifications, sounds, dark mode. The native checkbox underneath carries `role="switch"` so assistive tech announces it correctly.
+
+## When to use
+
+Use `bf-toggle` for a setting that applies the moment it changes: notifications, sounds, dark mode. Use [bf-checkbox](https://bitforge-ui.web.app/components/checkbox) instead inside a form that is saved or submitted later, and [bf-segmented](https://bitforge-ui.web.app/components/segmented) for a choice between two named options that are not on and off.
+
+## Basic usage
+
+```ts
+import { Component, signal } from '@angular/core';
+import { BfToggleComponent } from '@bitforgehq/ui';
+
+/** A labelled toggle that reports each change. */
+@Component({
+  selector: 'app-example-toggle-basic',
+  imports: [BfToggleComponent],
+  template: `
+    <div class="flex flex-col gap-2">
+      <bf-toggle label="Notifications" [(checked)]="notifications" (changed)="save($event)" />
+      <p aria-live="polite" class="text-caption text-text-muted">{{ status() }}</p>
+    </div>
+  `,
+})
+export class ToggleBasicExampleComponent {
+  protected readonly notifications = signal(true);
+  protected readonly status = signal('');
+
+  protected save(on: boolean): void {
+    this.status.set(on ? 'Notifications on.' : 'Notifications off.');
+  }
+}
+```
+
+## In a settings list
+
+Put the label first so a column of toggles lines up on the right, as in the Meadow Sage profile screen.
+
+```ts
+import { Component, signal } from '@angular/core';
+import { BfToggleComponent } from '@bitforgehq/ui';
+
+/** A full-width settings toggle with its label at the start. */
+@Component({
+  selector: 'app-example-toggle-settings',
+  imports: [BfToggleComponent],
+  template: `
+    <bf-toggle label="Weekly summary" labelPosition="start" class="w-full" [(checked)]="weekly" />
+  `,
+})
+export class ToggleSettingsExampleComponent {
+  protected readonly weekly = signal(true);
+}
+```
+
+When the row itself already shows the title, such as a `bf-list-item`'s `title`/`subtitle`, don't repeat it as the toggle's own `label`; give it `ariaLabel` instead so the switch still has an accessible name, or `ariaLabelledby` with the id of the element that shows the title.
+
+```ts
+import { Component, signal } from '@angular/core';
+import { BfListComponent, BfListItemComponent, BfToggleComponent } from '@bitforgehq/ui';
+
+/**
+ * A toggle in a settings row.
+ *
+ * The row shows the title and subtitle; the toggle in the trailing slot takes an `ariaLabel`.
+ */
+@Component({
+  selector: 'app-example-toggle-list-row',
+  imports: [BfListComponent, BfListItemComponent, BfToggleComponent],
+  template: `
+    <bf-list>
+      <bf-list-item title="Weekly summary" subtitle="Every Monday at 8:00">
+        <bf-toggle bfSlot="trailing" ariaLabel="Weekly summary" [(checked)]="weekly" />
+      </bf-list-item>
+    </bf-list>
+  `,
+})
+export class ToggleListRowExampleComponent {
+  protected readonly weekly = signal(false);
+}
+```
+
+## Sizes
+
+`sm` (32 px row, 24×40 track), `md` (default, 40 px row, 28×48 track), `lg` (48 px row, 32×56 track). Unset, `size` follows `provideBfDefaults()`'s `controlSize`, `md` by default (`provideBfDefaults({ size: 'lg' })` enlarges every control of a Capacitor app; `{ size: 'sm' }` in a component's `providers` makes a dense sub-tree). Under a fine pointer the row is the hit area (32 px and up, above the 24 px of WCAG 2.5.8); under a coarse pointer (touch) `sm` and `md` rows grow to 44 px. The knob travels to the inline end, so it moves left under `dir="rtl"`.
+
+```ts
+import { Component, signal } from '@angular/core';
+import { BfToggleComponent } from '@bitforgehq/ui';
+
+/** The sm, md and lg toggle sizes. */
+@Component({
+  selector: 'app-example-toggle-sizes',
+  imports: [BfToggleComponent],
+  template: `
+    <div class="flex flex-col gap-2">
+      <bf-toggle size="sm" label="Compact rows" [(checked)]="compact" />
+      <bf-toggle label="Notifications" [(checked)]="notifications" />
+      <bf-toggle size="lg" label="Sounds" [(checked)]="sounds" />
+    </div>
+  `,
+})
+export class ToggleSizesExampleComponent {
+  protected readonly compact = signal(false);
+  protected readonly notifications = signal(true);
+  protected readonly sounds = signal(false);
+}
+```
+
+## With Signal Forms
+
+```ts
+import { Component, signal } from '@angular/core';
+import { FormField, form } from '@angular/forms/signals';
+import { BfToggleComponent } from '@bitforgehq/ui';
+
+/** A toggle bound to a Signal Forms field. */
+@Component({
+  selector: 'app-example-toggle-signal-forms',
+  imports: [FormField, BfToggleComponent],
+  template: `
+    <div class="flex flex-col gap-2">
+      <bf-toggle label="Public profile" [formField]="profile.public" />
+      <p class="text-caption text-text-muted">public: {{ profile.public().value() }}</p>
+    </div>
+  `,
+})
+export class ToggleSignalFormsExampleComponent {
+  private readonly model = signal({ public: false });
+  protected readonly profile = form(this.model);
+}
+```
+
+## Read-only
+
+`readonly` shows the setting but blocks changes: clicks and Space do nothing and the switch stays
+in the tab order. The track rests on the muted surface like the other read-only controls; when on,
+it is outlined in `primary` and the knob turns `primary-strong`. Signal Forms binds it from `readonly()`
+rules.
+
+```ts
+import { Component } from '@angular/core';
+import { BfToggleComponent } from '@bitforgehq/ui';
+
+/** A read-only toggle an admin manages. */
+@Component({
+  selector: 'app-example-toggle-readonly',
+  imports: [BfToggleComponent],
+  template: `<bf-toggle label="Managed by your admin" [readonly]="true" [checked]="managed" />`,
+})
+export class ToggleReadonlyExampleComponent {
+  protected readonly managed = true;
+}
+```
+
+## Validation
+
+Once the control is touched it shows the first error as text: the error's own `message`, else the default for its kind from `provideBfLabels()`'s `validation` labels (`required` "Fill in this field", `email`, `pattern`, `parse`, `min(n)`, `max(n)`, `minLength(n)` "Use at least n characters", `maxLength(n)`, `minDate(d)`, `maxDate(d)`, and `fallback` "Check this value" for any other kind), so it never turns red without text. Reactive Forms `Validators.*` errors carry no message and get the same defaults (`minlength`/`maxlength` read their limit from the error's `context`). An explicit `errorMessage` wins over both and shows at once, e.g. for a server error.
+
+```ts
+import { Component, signal } from '@angular/core';
+import { FormField, FormRoot, form, required } from '@angular/forms/signals';
+import { BfButtonComponent, BfToggleComponent } from '@bitforgehq/ui';
+
+/**
+ * A required toggle with the default message.
+ *
+ * `required(p.consent)` has no message, so a submit shows "Fill in this field".
+ */
+@Component({
+  selector: 'app-example-toggle-validation',
+  imports: [FormField, FormRoot, BfButtonComponent, BfToggleComponent],
+  template: `
+    <form [formRoot]="settings" class="flex flex-col items-start gap-3">
+      <bf-toggle label="Share usage data" [formField]="settings.consent" />
+      <bf-button type="submit">Save</bf-button>
+    </form>
+  `,
+})
+export class ToggleValidationExampleComponent {
+  private readonly model = signal({ consent: false });
+  protected readonly settings = form(
+    this.model,
+    (p) => {
+      required(p.consent);
+    },
+    { submission: { action: () => Promise.resolve(undefined) } },
+  );
+}
+```
+
+## Desktop
+
+Hovering the row darkens the track (`primary-hover` when on, `text-muted` when off) with the pointer cursor; a read-only switch has no hover. Hover styles apply only on devices that can hover, so a tap never leaves one stuck. The ring shows around the track on keyboard focus only. Under a fine pointer the row is the hit area, at least 24 × 24 px; `sm` (32 px rows) suits dense desktop forms and tables; set it with `provideBfDefaults({ size: 'sm' })` ([density guide](https://bitforge-ui.web.app/density)).
+
+## Theming
+
+- Track: `primary` when checked, `control-off` when unchecked; hovering the row (pointer cursor)
+  darkens it to `primary-hover` / `text-muted`.
+- Pressed (the row held down): the track takes a `text` border; not while disabled or read-only.
+- Knob: `on-primary` when on (≥ 3:1 on the `primary` track for any configured primary), `surface`
+  when off, with the `segment` shadow.
+- Shape (track and knob): `rounded-control` (`--radius-control`, `9999px` by default).
+- Focus (the native input is visually hidden; the ring renders on the track through `peer-focus-visible`): `ring`.
+- Disabled: track `primary-soft` when checked, `surface-sunken` when unchecked; label `text-disabled` (never opacity).
+- Read-only: track `surface-muted`, bordered `primary` with a `primary-strong` knob when checked (≥ 3:1 on `surface-muted` for any primary) and `control-off` with the `surface` knob when unchecked (≥ 3:1 on `bg` and `surface`); no hover, default cursor.
+- Error text: `danger`.
+- Label: a long label (or a large text size) wraps beside the track, a long word breaking anywhere, instead of overflowing the row.
+
+The track sits 10 px from the label (as on `bf-checkbox` and `bf-radio-group`) and the error text 6 px under the row.
+
+## Accessibility
+
+Native `<input type="checkbox" role="switch">`, visually hidden (`sr-only`) and wrapped in a `<label>` so the whole row is tappable. Keyboard: native checkbox behaviour — Space toggles it while focused. `aria-checked` mirrors `checked`; `aria-label` carries `ariaLabel` and `aria-labelledby` carries `ariaLabelledby` whenever they are set (use them only when there is no visible `label`); `aria-invalid`, `aria-describedby` and `aria-errormessage` point at the error text once the field is touched and invalid (an explicit `errorMessage` shows immediately). Read-only: `aria-readonly="true"`, still focusable; the click (which Space also triggers) is cancelled, so the state never changes. `focus()` focuses the native switch; Signal Forms calls it from `focusBoundControl()`.
+
+### Keyboard
+
+| Key                                              | Action                                                                      |
+| ------------------------------------------------ | --------------------------------------------------------------------------- |
+| <kbd>Tab</kbd> / <kbd>Shift</kbd>+<kbd>Tab</kbd> | Moves focus to and from the switch; a `readonly` one stays in the tab order |
+| <kbd>Space</kbd>                                 | Turns it on or off; nothing while `readonly`                                |
+
+## Inputs
+
+| Name             | Type                                                        | Default     | Description                                                                                                                                                        |
+| ---------------- | ----------------------------------------------------------- | ----------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| `label`          | `string`                                                    | `''`        | Label text; the default slot works too.                                                                                                                            |
+| `ariaLabel`      | `string`                                                    | `''`        | Accessible name when no visible label is rendered (e.g. a switch in a list row).                                                                                   |
+| `ariaLabelledby` | `string`                                                    | `''`        | Id(s) of the element(s) that name the control when no visible label is rendered (e.g. a table column header).                                                      |
+| `size`           | `BfSize \| undefined` (`'sm' \| 'md' \| 'lg' \| undefined`) | `undefined` | Height step of the row: sm 32, md 40, lg 48 px (44 px under a coarse pointer for sm and md); unset follows `provideBfDefaults()` (`controlSize`, `md` by default). |
+| `labelPosition`  | `BfToggleLabelPosition` (`'end' \| 'start'`)                | `'end'`     | Put the label before the switch (as in settings lists).                                                                                                            |
+| `disabled`       | `boolean`                                                   | `false`     | Disables the control. Set by `[formField]`; do not bind it yourself.                                                                                               |
+| `readonly`       | `boolean`                                                   | `false`     | Shows the state but blocks changes; the switch stays focusable and exposes `aria-readonly`. Set by `[formField]`; do not bind it yourself.                         |
+| `required`       | `boolean`                                                   | `false`     | Marks the control required. Set by `[formField]`; do not bind it yourself.                                                                                         |
+| `invalid`        | `boolean`                                                   | `false`     | Field validity from Signal Forms. Set by `[formField]`; do not bind it yourself.                                                                                   |
+| `touched`        | `boolean`                                                   | `false`     | Whether the user has left the field. Set by `[formField]`; do not bind it yourself.                                                                                |
+| `errors`         | `readonly ValidationError.WithOptionalFieldTree[]`          | `[]`        | Validation errors from Signal Forms. Set by `[formField]`; do not bind it yourself.                                                                                |
+| `errorMessage`   | `string`                                                    | `''`        | Explicit error text; takes precedence over Signal Forms errors.                                                                                                    |
+| `name`           | `string`                                                    | `''`        | Native name attribute. Set by `[formField]`; do not bind it yourself.                                                                                              |
+| `id`             | `string`                                                    | `generated` | Control id; generated when not set.                                                                                                                                |
+| `checked`        | `boolean`                                                   | `false`     | Whether the switch is on; two-way bindable and bound by `[formField]`. Two-way: `[(checked)]`.                                                                     |
+
+## Outputs
+
+| Name      | Payload   | Description                                                                                             |
+| --------- | --------- | ------------------------------------------------------------------------------------------------------- |
+| `changed` | `boolean` | Emitted with the new state after a user change.                                                         |
+| `touch`   | `void`    | Emitted on blur so Signal Forms marks the field touched. Set by `[formField]`; do not bind it yourself. |
+
+## Slots
+
+- `default`: Rich label content after the `label` text.
+
+## Methods
+
+### `focus(options?: FocusOptions): void`
+
+Focuses the native switch; Signal Forms calls it from `focusBoundControl()`.
+
+| Parameter  | Type           | Description                                                           |
+| ---------- | -------------- | --------------------------------------------------------------------- |
+| `options?` | `FocusOptions` | Passed on to the native `focus()`, such as `{ preventScroll: true }`. |
+
+## Notes
+
+### Do
+
+- Apply the change immediately and confirm it visually; a toggle should never need a Save button.
+- Label the setting, not the state ("Notifications", not "On").
+- Use `ariaLabel` or `ariaLabelledby` only when there is no visible `label`; otherwise the visible text is the name.
+
+### Don't
+
+- Don't use a toggle inside a form that is submitted later; use `bf-checkbox`.
+
+## Migration notes
+
+### 0.3.0
+
+New `ariaLabelledby` input: the id of the element that names the switch when no visible `label`
+is shown, set as the native switch's `aria-labelledby`. Additive.
+
+New exported `BfToggleLabelPosition` (`'end' | 'start'`), the type of `labelPosition` (was an
+inline union with the same values).
+
+**Behaviour:** new `size` (`BfSize`; unset follows `provideBfDefaults()`'s `controlSize`): rows
+are `sm` 32, `md` 40 (default), `lg` 48 px under a fine pointer, and at least 44 px under a coarse
+pointer (was 44 px everywhere); the track is 24×40 / 28×48 / 32×56 px with a matching knob, and the knob
+travels to the inline end (mirrored under `dir="rtl"`).
+
+**Behaviour:** an error without a message shows its kind's default text (was a red border only):
+once touched, the field shows the first error's own `message`, else `provideBfLabels()`'s
+`validation` text for its kind (Signal Forms and Reactive interop kinds), else
+`validation.fallback`. `errorMessage` still wins. See Migration 1.
+
+**Behaviour:** the track and the knob use `rounded-control` (`--radius-control`, `9999px` by
+default, so they render as before).
+
+**Behaviour:** the knob carries the state for any configured primary: `on-primary` on the on track
+(was `surface`), `primary-strong` when read-only and on (was `primary`); off and disabled knobs
+stay `surface`.
+
+JSDoc of `toggle.component.ts` for the API reference: `@slot` docs for `default`; `@param` docs;
+template handlers and framework hooks marked `@internal`, so the reference leaves them out. No
+behaviour change.
+
+**Behaviour:** a pressed state (F-045): the track takes a `text` border while the row is held down. None while disabled or read-only; under forced colours the system colours win.
+
+**Behaviour:** sets `aria-errormessage` to its error paragraph (`<id>-error`) while
+`aria-invalid="true"`, and an error that appears while a pointer button is held down (a press
+elsewhere that blurred it) shows once the press ends, so the layout never moves under the pointer
+(F-020).
+
+**Behaviour:** the label wraps (`min-w-0 wrap-anywhere`) instead of overflowing its row at large
+text sizes (F-051): a `labelPosition="start"` label in a `bf-list-item` spilled past the row's
+start edge at the iOS AX sizes.
+
+### 0.2.0
+
+The track sits 10 px from the label (`gap-2.5`, was 12 px), like checkbox and radio. Label and
+error text are wrapped in a `flex flex-col items-start gap-1.5` column, so the error sits 6 px
+under the 44 px row (it followed with no gap). Disabled uses tokens instead of `opacity-60`: the
+track is `primary-soft` when checked and `surface-sunken` when unchecked, the label `text-disabled`.
+
+Fixed: hovering an enabled row darkens the track (`primary-hover` on, `text-muted` off).
+
+Added: `readonly` input. Behaviour change: the control ignored Signal Forms `readonly()` rules and
+could be edited; it now declares `readonly` and blocks changes. While read-only the click (which
+Space also triggers) is cancelled and `aria-readonly="true"` is set; the switch stays focusable, the
+track rests on `surface-muted` without hover, bordered `primary` with a `primary` knob when on and
+`control-off` (keeping the ≥ 3:1 boundary) when off. `focus(options?)` focuses the native control, so Signal
+Forms' `focusBoundControl()` and "focus the first invalid field" on submit now work (they were
+no-ops).
+
+### 0.1.0
+
+Added `errorMessage` and Signal Forms error rendering (matching `bf-checkbox`): a `<p>` under the label, `aria-invalid` and `aria-describedby` on the input. `labelPosition="start"` now stretches the label to `w-full` with `justify-between` for settings-list layouts. The track and knob keep a transparent 1.5px border and the focus ring clears in forced-colors mode. The host no longer reflects a static `id` attribute onto `<bf-toggle>`. Fixed the knob sitting off-centre: the track's padding was `p-[3px]` alongside its `border-[1.5px]`, so the 22px knob had unequal 4.5px/1.5px margins at the two ends of its 20px `translate-x-5` travel; padding is now `p-[1.5px]` for equal 3px margins on both sides. Also removed the redundant `box-border` from the knob (preflight already sets `box-sizing: border-box` globally). The label's clickable hit area is now `min-h-11 items-center` instead of a `::after` pseudo-element, in both `labelPosition` branches, for the same reason as `bf-checkbox`.

package/ai/reference/bf-action-directive.md

@@ -0,0 +1,21 @@
+# BfActionDirective
+
+Makes one link or button the click target of a whole card or list row
+
+Directive from `@bitforgehq/ui` · since 0.3.0
+
+The one interactive element of a `bf-card` or `bf-list-item` (the stretched-link pattern): put
+it on the `<a>` (navigation) or `<button>` (an action) that holds the card's heading text or the
+row's title. Its `::after` stretches the hit area over the nearest positioned ancestor (the card
+box, the row), so the whole surface is clickable while only the heading's link or button is
+exposed: the heading stays a heading and the accessible name is the title alone. It registers
+with the nearest card or row, which then draws the pointer, the hover and, while the action has
+keyboard focus, the focus ring; a card is never lit by the actions of rows nested in it. Give
+secondary controls inside the surface `class="relative z-1"` so they stay clickable above the
+stretched area.
+
+```ts
+import { BfActionDirective } from '@bitforgehq/ui';
+```
+
+Selector: `a[bfAction], button[bfAction]`

package/ai/reference/bf-action-sheet-action-role.md

@@ -0,0 +1,27 @@
+# BfActionSheetActionRole
+
+The role of an action sheet row, a destructive action or the cancel button
+
+Type from `@bitforgehq/ui/mobile` · since 0.3.0
+
+The role of an action sheet row: `destructive` renders it in `text-danger`, `cancel` makes it the
+separate cancel button.
+
+```ts
+import { type BfActionSheetActionRole } from '@bitforgehq/ui/mobile';
+```
+
+## Signature
+
+```ts
+type BfActionSheetActionRole = 'destructive' | 'cancel'
+```
+
+## Values
+
+- `destructive`
+- `cancel`
+
+## Used by
+
+- [BfActionSheetAction](bf-action-sheet-action.md)

package/ai/reference/bf-action-sheet-action.md

@@ -0,0 +1,28 @@
+# BfActionSheetAction
+
+One row of an action sheet, or its cancel button, with its answer and role
+
+Interface from `@bitforgehq/ui/mobile` · since 0.2.0
+
+One row of an action sheet, or its cancel action when `role: 'cancel'`.
+
+```ts
+import { type BfActionSheetAction } from '@bitforgehq/ui/mobile';
+```
+
+## Properties
+
+| Name    | Type                                                    | Default  | Description                                                                                                                                                                                                            |
+| ------- | ------------------------------------------------------- | -------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `id`    | `string`                                                |          | What `open()` resolves with when the row is tapped (default `label`); keeps the answer stable when the label is translated or two rows share a label. Ignored on the cancel action, which always resolves `undefined`. |
+| `label` | `string`                                                | required | Row text; also what `open()` resolves with when the row is tapped and has no `id`.                                                                                                                                     |
+| `icon`  | `IconNode`                                              |          | Icon rendered in the row's leading slot.                                                                                                                                                                               |
+| `role`  | `BfActionSheetActionRole` (`'destructive' \| 'cancel'`) |          | `destructive` renders the row's label in `text-danger`; `cancel` renders it as the separate cancel button instead of a row (a plain row when omitted).                                                                 |
+
+## Uses
+
+- [BfActionSheetActionRole](bf-action-sheet-action-role.md)
+
+## Used by
+
+- [BfActionSheetOptions](bf-action-sheet-options.md)

package/ai/reference/bf-action-sheet-options.md

@@ -0,0 +1,28 @@
+# BfActionSheetOptions
+
+Options of an action sheet: its title, its rows and when it closes
+
+Interface from `@bitforgehq/ui/mobile` · since 0.2.0
+
+Options of `BfActionSheetService.open()`.
+
+```ts
+import { type BfActionSheetOptions } from '@bitforgehq/ui/mobile';
+```
+
+## Properties
+
+| Name                | Type                    | Default  | Description                                                                                                                                                                                                                                                         |
+| ------------------- | ----------------------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `title`             | `string`                |          | Heading above the rows; also the panel's accessible name (default `provideBfLabels()`'s `actions`, "Actions").                                                                                                                                                      |
+| `actions`           | `BfActionSheetAction[]` | required | Rows, in order; a `cancel`-role entry becomes the separate cancel button instead of a row. Only the first `cancel`-role entry is used; any further ones are ignored.                                                                                                |
+| `closeOnNavigation` | `boolean`               | `true`   | A navigation to another URL path closes the sheet, resolving `undefined` (default true).                                                                                                                                                                            |
+| `injector`          | `Injector`              |          | Injector the action sheet resolves its labels (`BF_LABELS`) from and the parent of its content's injector (default the root injector). Pass the opening component's `inject(Injector)` so a feature-level `provideBfLabels()` and other feature providers reach it. |
+
+## Uses
+
+- [BfActionSheetAction](bf-action-sheet-action.md)
+
+## Used by
+
+- [BfActionSheetService](bf-action-sheet-service.md)

package/ai/reference/bf-action-sheet-service.md

@@ -0,0 +1,33 @@
+# BfActionSheetService
+
+Opens bottom action sheets that resolve with the row the user tapped
+
+Service from `@bitforgehq/ui/mobile` · since 0.2.0
+
+Opens action sheets: a bottom-anchored list of actions on the overlay core (`position:
+'bottom'`, not counted as a modal). Renders `title` above a `bf-list` of the non-cancel
+`actions` as interactive rows (destructive ones in `text-danger`, an icon in the leading slot
+from `icon`), and a separate `tonal` `bf-button` for the cancel action — the caller's
+first `cancel`-role entry if any (further ones are ignored), else a synthesized one labelled `provideBfLabels()`'s `cancel` ("Cancel").
+Focus starts on the cancel button. `open()` resolves with the tapped row's `id ?? label`; the
+cancel button, a backdrop tap, `Escape`, the hardware back button and a navigation to another
+URL path all resolve `undefined`.
+
+```ts
+import { BfActionSheetService } from '@bitforgehq/ui/mobile';
+```
+
+## Methods
+
+### `open(options: BfActionSheetOptions): Promise<string | undefined>`
+
+Opens the action sheet described by `options`; resolves with the tapped row's `id ?? label`,
+or `undefined` when cancelled.
+
+| Parameter | Type                   | Description                      |
+| --------- | ---------------------- | -------------------------------- |
+| `options` | `BfActionSheetOptions` | The title and rows of the sheet. |
+
+## Uses
+
+- [BfActionSheetOptions](bf-action-sheet-options.md)

package/ai/reference/bf-alert-dialog-button-role.md

@@ -0,0 +1,27 @@
+# BfAlertDialogButtonRole
+
+The role of an alert dialog button, the cancel answer or a destructive action
+
+Type from `@bitforgehq/ui/mobile` · since 0.3.0
+
+The role of an alert dialog button: `cancel` answers `Escape` and the hardware back button,
+`destructive` renders `danger`.
+
+```ts
+import { type BfAlertDialogButtonRole } from '@bitforgehq/ui/mobile';
+```
+
+## Signature
+
+```ts
+type BfAlertDialogButtonRole = 'cancel' | 'destructive'
+```
+
+## Values
+
+- `cancel`
+- `destructive`
+
+## Used by
+
+- [BfAlertDialogButton](bf-alert-dialog-button.md)

package/ai/reference/bf-alert-dialog-button.md

@@ -0,0 +1,27 @@
+# BfAlertDialogButton
+
+One button of an alert dialog: its answer, its label and its role
+
+Interface from `@bitforgehq/ui/mobile` · since 0.2.0
+
+A button of `BfAlertDialogService.open()`.
+
+```ts
+import { type BfAlertDialogButton } from '@bitforgehq/ui/mobile';
+```
+
+## Properties
+
+| Name    | Type                                                    | Default  | Description                                                                                                                                                                                             |
+| ------- | ------------------------------------------------------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `id`    | `string`                                                |          | What `open()` resolves with when the button is tapped (default `label`); keeps the answer stable when the label is translated or two buttons share a label.                                             |
+| `label` | `string`                                                | required | Button text; also the value `open()` resolves with when it is tapped and has no `id`.                                                                                                                   |
+| `role`  | `BfAlertDialogButtonRole` (`'cancel' \| 'destructive'`) |          | `cancel` renders as a `text` button, takes the initial focus and is what `Escape`/the hardware back button answer with; `destructive` renders `danger` (a plain `primary`/`tonal` button when omitted). |
+
+## Uses
+
+- [BfAlertDialogButtonRole](bf-alert-dialog-button-role.md)
+
+## Used by
+
+- [BfAlertDialogOptions](bf-alert-dialog-options.md)

package/ai/reference/bf-alert-dialog-options.md

@@ -0,0 +1,29 @@
+# BfAlertDialogOptions
+
+Options of an alert dialog: its title, message, buttons and when it closes
+
+Interface from `@bitforgehq/ui/mobile` · since 0.2.0
+
+Options of `BfAlertDialogService.open()`.
+
+```ts
+import { type BfAlertDialogOptions } from '@bitforgehq/ui/mobile';
+```
+
+## Properties
+
+| Name                | Type                    | Default  | Description                                                                                                                                                                                                                                                   |
+| ------------------- | ----------------------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `title`             | `string`                | required | Dialog heading, rendered as the `h2` the panel's `aria-labelledby` points to.                                                                                                                                                                                 |
+| `message`           | `string`                |          | Body text under the title.                                                                                                                                                                                                                                    |
+| `buttons`           | `BfAlertDialogButton[]` |          | Buttons, left to right (default one button labelled `provideBfLabels()`'s `ok`, "OK").                                                                                                                                                                        |
+| `closeOnNavigation` | `boolean`               | `true`   | A navigation to another URL path closes the alert, resolving the cancel button's answer, or `undefined` without one (default true).                                                                                                                           |
+| `injector`          | `Injector`              |          | Injector the dialog resolves its labels (`BF_LABELS`) from and the parent of its content's injector (default the root injector). Pass the opening component's `inject(Injector)` so a feature-level `provideBfLabels()` and other feature providers reach it. |
+
+## Uses
+
+- [BfAlertDialogButton](bf-alert-dialog-button.md)
+
+## Used by
+
+- [BfAlertDialogService](bf-alert-dialog-service.md)

package/ai/reference/bf-alert-dialog-service.md

@@ -0,0 +1,34 @@
+# BfAlertDialogService
+
+Opens small centred alerts that resolve with the button the user tapped
+
+Service from `@bitforgehq/ui/mobile` · since 0.2.0
+
+Opens alert dialogs: a centred, 300 px card on the overlay core (`position: 'center'`, no
+backdrop dismiss). Renders `title` as an `h2`, an optional `message`, and `buttons` (default
+one `ok` button from the app's `provideBfLabels()`, "OK") as a right-aligned row — `cancel`-role `text`, `destructive`-role
+`danger`, the first plain button `primary`, further plain ones `tonal`. Focus starts on the
+`cancel`-role button, else the first one. `open()` resolves with the tapped button's
+`id ?? label`. `Escape` and the hardware back button resolve with the cancel button's answer
+when `buttons` has one; with none, they are claimed and ignored — an alert
+with no cancel button can only be answered by tapping a button, or closed by a navigation to
+another URL path, which resolves the cancel button's answer, else `undefined`.
+
+```ts
+import { BfAlertDialogService } from '@bitforgehq/ui/mobile';
+```
+
+## Methods
+
+### `open(options: BfAlertDialogOptions): Promise<string | undefined>`
+
+Opens the alert described by `options`; resolves with the tapped button's `id ?? label`, or
+`undefined` when a navigation closes an alert that has no cancel button.
+
+| Parameter | Type                   | Description                                  |
+| --------- | ---------------------- | -------------------------------------------- |
+| `options` | `BfAlertDialogOptions` | The title, message and buttons of the alert. |
+
+## Uses
+
+- [BfAlertDialogOptions](bf-alert-dialog-options.md)