@bitforgehq/ui 0.3.0

package/ai/reference/bf-keyboard-phase.md

@@ -0,0 +1,30 @@
+# BfKeyboardPhase
+
+The soft keyboard phase, hidden, showing or shown, for animations only
+
+Type from `@bitforgehq/ui/mobile` · since 0.2.0
+
+Keyboard lifecycle phase, for animations only; never gate logic on the order of the phases.
+`showing` starts at `keyboardWillShow`, `shown` at `keyboardDidShow`. Either hide event
+(`keyboardWillHide` or `keyboardDidHide`, whichever arrives first — iOS does not guarantee
+the order) moves straight to `hidden`, so there is no `hiding` phase.
+
+```ts
+import { type BfKeyboardPhase } from '@bitforgehq/ui/mobile';
+```
+
+## Signature
+
+```ts
+type BfKeyboardPhase = 'hidden' | 'showing' | 'shown'
+```
+
+## Values
+
+- `hidden`
+- `showing`
+- `shown`
+
+## Used by
+
+- [BfKeyboardService](bf-keyboard-service.md)

package/ai/reference/bf-keyboard-service.md

@@ -0,0 +1,50 @@
+# BfKeyboardService
+
+The soft keyboard state as signals: visible, its height and its phase
+
+Service from `@bitforgehq/ui/mobile` · since 0.2.0
+
+The soft keyboard as signals. On native it listens to the Capacitor Keyboard plugin
+(`@capacitor/keyboard`, loaded lazily, height known at `keyboardWillShow`); on the web it falls
+back to `visualViewport` resizes with an 80 px threshold (height known only once the viewport has
+shrunk; ignored while the page is pinch-zoomed, `visualViewport.scale` ≠ 1); in Jest and SSR it
+stays inert (height 0, never visible). The rest height (viewport with the keyboard hidden) comes
+from a fixed `100lvh` probe element, never `innerHeight`, which sticks at a wrong value after a
+field-to-field focus jump on iOS; it is measured at construction and on window resizes while the
+keyboard is hidden and no text control is focused, never at will-show. `imminent` flags a focused
+text control before any keyboard event, and `keyboardTop()` gives the keyboard's top edge in
+viewport px. It also writes the height as `--bf-keyboard-height` on `<html>` (`0px` while hidden)
+for CSS that follows the keyboard.
+
+```ts
+import { BfKeyboardService } from '@bitforgehq/ui/mobile';
+```
+
+## Properties
+
+| Name              | Type                      | Default | Description                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      |
+| ----------------- | ------------------------- | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| `height`          | `Signal<number>`          |         | Keyboard height in CSS px (iOS: includes the home-indicator strip); 0 when hidden.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               |
+| `phase`           | `Signal<BfKeyboardPhase>` |         | Lifecycle phase for animations; see `BfKeyboardPhase`.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                           |
+| `visible`         | `Signal<boolean>`         |         | True from will-show until either hide event: the moment to hide chrome such as the tab bar.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      |
+| `overlaysContent` | `Signal<boolean>`         |         | True when the keyboard overlays the WebView (native iOS, `resize: 'none'`); false when the WebView resizes.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      |
+| `restHeight`      | `Signal<number>`          |         | Viewport height with the keyboard hidden, in CSS px, from a fixed `100lvh` probe.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                |
+| `willShow`        | `Signal<number>`          |         | Increments once per keyboard show (at will-show), for one-off reactions such as closing popovers.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                |
+| `imminent`        | `Signal<boolean>`         |         | True from `focusin` on a text-entry control (see `isTextEntry`) until that control's `focusout` or either keyboard hide event; never cleared by will-show. Hide chrome such as the tab bar on `visible() \|\| imminent()`: on Android the WebView shrinks before the plugin's will-show, which lifts `position: fixed` elements above the keyboard; `focusin` is the only earlier signal. When it turns true without the keyboard up, it also clears itself after `IMMINENT_TIMEOUT_MS` (2500 ms) unless will-show or a visible keyboard arrives first, so a hardware keyboard, which fires no keyboard event, does not keep the tab bar hidden. |
+
+## Methods
+
+### `hide(): Promise<void>`
+
+Hides the keyboard: `Keyboard.hide()` on native, blurs the focused element on the web.
+
+### `keyboardTop(): number`
+
+The keyboard's top edge in viewport CSS px, read on demand. While the keyboard overlays the
+WebView (native iOS) it is `restHeight() - height()`; where the viewport shrinks for it
+(Android, the web) it is the bottom of `visualViewport` (else `innerHeight`). With the
+keyboard hidden it is `restHeight()`.
+
+## Uses
+
+- [BfKeyboardPhase](bf-keyboard-phase.md)

package/ai/reference/bf-labels-overrides.md

@@ -0,0 +1,26 @@
+# BfLabelsOverrides
+
+The strings provideBfLabels replaces, each one falling back to the parent
+
+Type from `@bitforgehq/ui` · since 0.3.0
+
+Options of `provideBfLabels()`: any key left out keeps the parent injector's string.
+
+```ts
+import { type BfLabelsOverrides } from '@bitforgehq/ui';
+```
+
+## Signature
+
+```ts
+type BfLabelsOverrides = Partial<Omit<BfLabels, 'validation'>> & { readonly validation?: Partial<BfValidationMessages>; }
+```
+
+## Uses
+
+- [BfLabels](bf-labels.md)
+- [BfValidationMessages](bf-validation-messages.md)
+
+## Used by
+
+- [provideBfLabels](provide-bf-labels.md)

package/ai/reference/bf-labels.md

@@ -0,0 +1,44 @@
+# BfLabels
+
+Every built-in user-facing string of the library, one key per string
+
+Interface from `@bitforgehq/ui` · since 0.3.0
+
+Every built-in user-facing string of the library; replace any of them with `provideBfLabels()`.
+
+```ts
+import { type BfLabels } from '@bitforgehq/ui';
+```
+
+## Properties
+
+| Name            | Type                                          | Default                                                       | Description                                                                                                   |
+| --------------- | --------------------------------------------- | ------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------- |
+| `loading`       | `string`                                      | `'Loading'`                                                   | bf-spinner's accessible name (a loading bf-button's spinner is decorative and has none).                      |
+| `dismiss`       | `string`                                      | `'Dismiss'`                                                   | bf-alert's dismiss button.                                                                                    |
+| `tabBar`        | `string`                                      | `'Main'`                                                      | bf-tab-bar's navigation name.                                                                                 |
+| `tabBadge`      | `(count: number) => string`                   | `` (count) => `${count} new` ``                               | bf-tab's announcement of a numeric badge.                                                                     |
+| `back`          | `string`                                      | `'Back'`                                                      | bf-back-button's label.                                                                                       |
+| `ok`            | `string`                                      | `'OK'`                                                        | BfAlertDialogService's default button.                                                                        |
+| `cancel`        | `string`                                      | `'Cancel'`                                                    | BfActionSheetService's cancel row.                                                                            |
+| `actions`       | `string`                                      | `'Actions'`                                                   | An action sheet's name when it has no title.                                                                  |
+| `sheet`         | `string`                                      | `'Sheet'`                                                     | bf-sheet's name without an ariaLabel or heading.                                                              |
+| `modal`         | `string`                                      | `'Modal'`                                                     | bf-modal's name without an ariaLabel or heading.                                                              |
+| `refreshing`    | `string`                                      | `'Refreshing'`                                                | bf-refresher's status while refreshing.                                                                       |
+| `close`         | `string`                                      | `'Close'`                                                     | bf-dialog's close button, and bf-sheet's screen-reader Close.                                                 |
+| `expand`        | `string`                                      | `'Expand'`                                                    | bf-sheet's grabber button below the top snap point: the next press expands the sheet.                         |
+| `collapse`      | `string`                                      | `'Collapse'`                                                  | bf-sheet's grabber button at the top snap point: the next press collapses the sheet.                          |
+| `sheetPosition` | `(position: number, count: number) => string` | `` (position, count) => `Sheet at ${position} of ${count}` `` | bf-sheet's snap position (1-based), announced politely when it changes and part of the grabber button's name. |
+| `dialog`        | `string`                                      | `'Dialog'`                                                    | A dialog's name without an ariaLabel, a bf-dialog title or a heading.                                         |
+| `notifications` | `string`                                      | `'Notifications'`                                             | The desktop toast stack's region name.                                                                        |
+| `validation`    | `BfValidationMessages`                        | required                                                      | Default error text per validator kind (see `BfValidationMessages`).                                           |
+
+## Uses
+
+- [BfValidationMessages](bf-validation-messages.md)
+
+## Used by
+
+- [BfLabelsOverrides](bf-labels-overrides.md)
+- [BF_DEFAULT_LABELS](bf_default_labels.md)
+- [BF_LABELS](bf_labels.md)

package/ai/reference/bf-menu-button-harness.md

@@ -0,0 +1,40 @@
+# BfMenuButtonHarness
+
+Test harness for a menu button: opens it and hands out the menu it opened
+
+Class from `@bitforgehq/ui/testing` · since 0.3.0
+
+Harness for `bf-menu-button`, a button that opens a `bf-menu`. Its `label` filter matches the
+button's accessible name (its `label`, else its text).
+
+```ts
+import { BfMenuButtonHarness } from '@bitforgehq/ui/testing';
+```
+
+## Signature
+
+```ts
+class BfMenuButtonHarness extends ComponentHarness
+```
+
+## Methods
+
+### `getLabel(): Promise<string>`
+
+The button's accessible name: its `aria-label` (the `label` input), else its text.
+
+### `open(): Promise<void>`
+
+Opens the menu with a click; does nothing while it is open.
+
+### `isOpen(): Promise<boolean>`
+
+Whether the menu is open (`aria-expanded`).
+
+### `getMenu(): Promise<BfMenuHarness>`
+
+The open menu, opening it first when it is closed.
+
+## Uses
+
+- [BfMenuHarness](bf-menu-harness.md)

package/ai/reference/bf-menu-button-variant.md

@@ -0,0 +1,27 @@
+# BfMenuButtonVariant
+
+The three visual styles of a menu button, matching the button styles
+
+Type from `@bitforgehq/ui/overlay` · since 0.3.0
+
+The visual style of a `bf-menu-button`: outline, text or tonal, as `bf-button`'s.
+
+```ts
+import { type BfMenuButtonVariant } from '@bitforgehq/ui/overlay';
+```
+
+## Signature
+
+```ts
+type BfMenuButtonVariant = 'outline' | 'text' | 'tonal'
+```
+
+## Values
+
+- `outline`
+- `text`
+- `tonal`
+
+## Used by
+
+- [bf-menu-button](../components/menu-button.md)

package/ai/reference/bf-menu-divider-directive.md

@@ -0,0 +1,13 @@
+# BfMenuDividerDirective
+
+A line between groups of menu items that keyboard focus never lands on
+
+Directive from `@bitforgehq/ui/overlay` · since 0.3.0
+
+A line between groups of menu items (role `separator`, not focusable).
+
+```ts
+import { BfMenuDividerDirective } from '@bitforgehq/ui/overlay';
+```
+
+Selector: `[bfMenuDivider]`

package/ai/reference/bf-menu-group-directive.md

@@ -0,0 +1,14 @@
+# BfMenuGroupDirective
+
+Groups related menu items; radio items in one group exclude each other
+
+Directive from `@bitforgehq/ui/overlay` · since 0.3.0
+
+A group of menu items (role `group`); radio items in one group are exclusive. Name it with
+`aria-label` when its items share a topic ("Density").
+
+```ts
+import { BfMenuGroupDirective } from '@bitforgehq/ui/overlay';
+```
+
+Selector: `[bfMenuGroup]`

package/ai/reference/bf-menu-harness.md

@@ -0,0 +1,55 @@
+# BfMenuHarness
+
+Test harness for a menu: lists its items and clicks one, through submenus
+
+Class from `@bitforgehq/ui/testing` · since 0.3.0
+
+Harness for `bf-menu`, the card a `bfMenuTriggerFor` trigger or `bf-menu-button` opens. It
+renders in the CDK overlay container, so get it from `BfMenuButtonHarness.getMenu()` or through
+`TestbedHarnessEnvironment.documentRootLoader(fixture)`. Its `label` filter matches the menu's
+accessible name (its `ariaLabel`, else its trigger's text).
+
+```ts
+import { BfMenuHarness } from '@bitforgehq/ui/testing';
+```
+
+## Signature
+
+```ts
+class BfMenuHarness extends ComponentHarness
+```
+
+## Methods
+
+### `getLabel(): Promise<string>`
+
+The menu's accessible name: its `aria-label`, else the text of the element it is labelled
+by (its trigger).
+
+### `getItems(filter?: BfHarnessFilters): Promise<BfMenuItemHarness[]>`
+
+The menu's rows, in order (a submenu's rows belong to the submenu).
+
+| Parameter | Type               | Description                                             |
+| --------- | ------------------ | ------------------------------------------------------- |
+| `filter?` | `BfHarnessFilters` | Only the rows matching it, e.g. `{ label: 'Archive' }`. |
+
+### `clickItem(label: string, submenuPath?: string[]): Promise<void>`
+
+Clicks the row with this text; with a `submenuPath`, the row opens a submenu and the path's
+labels are clicked in the submenus that open, in order. Throws for an unknown label.
+
+| Parameter      | Type       | Description                                              |
+| -------------- | ---------- | -------------------------------------------------------- |
+| `label`        | `string`   | The row's text.                                          |
+| `submenuPath?` | `string[]` | The labels to click in the submenus that open, in order. |
+
+## Uses
+
+- [BfHarnessFilters](bf-harness-filters.md)
+- [BfMenuItemHarness](bf-menu-item-harness.md)
+
+## Used by
+
+- [BfMenuButtonHarness](bf-menu-button-harness.md)
+- [BfMenuItemHarness](bf-menu-item-harness.md)

package/ai/reference/bf-menu-item-checkbox-directive.md

@@ -0,0 +1,31 @@
+# BfMenuItemCheckboxDirective
+
+A menu row that toggles an option on and off with a check mark
+
+Directive from `@bitforgehq/ui/overlay` · since 0.3.0
+
+A toggle row of a `bf-menu` (role `menuitemcheckbox`) with a check mark while `checked`.
+Activating it (click, `Enter`, `Space`) flips its own `checked` (`aria-checked`), emits
+`triggered`, then `changed` (and `checkedChange`) with the new state, and closes the menu. Bind
+it two-way, `[(checked)]`, so your state always follows the item.
+
+```ts
+import { BfMenuItemCheckboxDirective } from '@bitforgehq/ui/overlay';
+```
+
+Selector: `button[bfMenuItemCheckbox]`
+
+## Inputs
+
+| Name                  | Type             | Default | Description                                                                                                                         |
+| --------------------- | ---------------- | ------- | ----------------------------------------------------------------------------------------------------------------------------------- |
+| `checked`             | `boolean`        | `false` | Whether the item is checked. The item flips it itself on activation (and emits `checkedChange`), so bind it two-way: `[(checked)]`. |
+| `bfMenuItemDisabled`  | `boolean`        |         | Whether the item is disabled: it stays focusable and announced, but does not activate.                                              |
+| `bfMenuItemTypeahead` | `string \| null` |         | The text typeahead matches the item by (default: its text content).                                                                 |
+
+## Outputs
+
+| Name        | Payload   | Description                                                                           |
+| ----------- | --------- | ------------------------------------------------------------------------------------- |
+| `changed`   | `boolean` | Emitted with the new state right after the user toggles the item.                     |
+| `triggered` | `void`    | Emits when the item is activated (click, `Enter` or `Space`), before `checked` flips. |

package/ai/reference/bf-menu-item-directive.md

@@ -0,0 +1,31 @@
+# BfMenuItemDirective
+
+An action row of a menu on a native button or link, with keyboard rules
+
+Directive from `@bitforgehq/ui/overlay` · since 0.3.0
+
+An action row of a `bf-menu` (role `menuitem`), on a native `<button>` or a link (`<a>` with
+`href` or `routerLink`). Activating it (click, `Enter`, `Space`) emits `triggered`, closes every
+open menu and returns focus to the trigger. With `[bfMenuTriggerFor]` on the same element it
+opens a submenu instead (and shows a chevron). A disabled item stays focusable and announces
+itself as disabled, but does not activate; a disabled link does not navigate either, also with
+`routerLink`.
+
+```ts
+import { BfMenuItemDirective } from '@bitforgehq/ui/overlay';
+```
+
+Selector: `button[bfMenuItem], a[bfMenuItem]`
+
+## Inputs
+
+| Name                  | Type             | Default | Description                                                                            |
+| --------------------- | ---------------- | ------- | -------------------------------------------------------------------------------------- |
+| `bfMenuItemDisabled`  | `boolean`        |         | Whether the item is disabled: it stays focusable and announced, but does not activate. |
+| `bfMenuItemTypeahead` | `string \| null` |         | The text typeahead matches the item by (default: its text content).                    |
+
+## Outputs
+
+| Name        | Payload | Description                                                                              |
+| ----------- | ------- | ---------------------------------------------------------------------------------------- |
+| `triggered` | `void`  | Emits when the item is activated (click, `Enter` or `Space`), unless it opens a submenu. |

package/ai/reference/bf-menu-item-harness.md

@@ -0,0 +1,52 @@
+# BfMenuItemHarness
+
+Test harness for a menu row: its text, disabled, checked and submenu state
+
+Class from `@bitforgehq/ui/testing` · since 0.3.0
+
+Harness for one row of a `bf-menu`: a `bfMenuItem`, `bfMenuItemCheckbox` or `bfMenuItemRadio`
+button (or `a[bfMenuItem]` link). Its `label` filter matches the row's text.
+
+```ts
+import { BfMenuItemHarness } from '@bitforgehq/ui/testing';
+```
+
+## Signature
+
+```ts
+class BfMenuItemHarness extends ComponentHarness
+```
+
+## Methods
+
+### `getText(): Promise<string>`
+
+The row's text.
+
+### `isDisabled(): Promise<boolean>`
+
+Whether the row is disabled (`aria-disabled`; a disabled row stays focusable).
+
+### `isChecked(): Promise<boolean>`
+
+Whether a checkbox or radio row is checked.
+
+### `hasSubmenu(): Promise<boolean>`
+
+Whether the row opens a submenu.
+
+### `click(): Promise<void>`
+
+Clicks the row: runs its action (closing the menu), toggles it, or opens its submenu.
+
+### `getSubmenu(): Promise<BfMenuHarness | null>`
+
+The submenu this row opened, or `null` while it is closed or when it has none.
+
+## Uses
+
+- [BfMenuHarness](bf-menu-harness.md)
+
+## Used by
+
+- [BfMenuHarness](bf-menu-harness.md)

package/ai/reference/bf-menu-item-radio-directive.md

@@ -0,0 +1,29 @@
+# BfMenuItemRadioDirective
+
+One choice of a set of exclusive options in a menu, marked with a dot
+
+Directive from `@bitforgehq/ui/overlay` · since 0.3.0
+
+One choice of a set (role `menuitemradio`) with a dot while `checked`. Put the choices of one
+set in a `bfMenuGroup`: choosing one (click, `Enter`, `Space`) unchecks the others, emits
+`triggered` and closes the menu.
+
+```ts
+import { BfMenuItemRadioDirective } from '@bitforgehq/ui/overlay';
+```
+
+Selector: `button[bfMenuItemRadio]`
+
+## Inputs
+
+| Name                  | Type             | Default | Description                                                                            |
+| --------------------- | ---------------- | ------- | -------------------------------------------------------------------------------------- |
+| `checked`             | `boolean`        |         | Whether this choice is the selected one of its group (shown with a dot).               |
+| `bfMenuItemDisabled`  | `boolean`        |         | Whether the item is disabled: it stays focusable and announced, but does not activate. |
+| `bfMenuItemTypeahead` | `string \| null` |         | The text typeahead matches the item by (default: its text content).                    |
+
+## Outputs
+
+| Name        | Payload | Description                                                                          |
+| ----------- | ------- | ------------------------------------------------------------------------------------ |
+| `triggered` | `void`  | Emits when the choice is activated (click, `Enter` or `Space`); set your state here. |

package/ai/reference/bf-menu-placement.md

@@ -0,0 +1,29 @@
+# BfMenuPlacement
+
+Where a menu opens against its trigger, above or below, at either end
+
+Type from `@bitforgehq/ui/overlay` · since 0.3.0
+
+Where a menu opens against its trigger; `start`/`end` follow the text direction.
+
+```ts
+import { type BfMenuPlacement } from '@bitforgehq/ui/overlay';
+```
+
+## Signature
+
+```ts
+type BfMenuPlacement = 'below-start' | 'below-end' | 'above-start' | 'above-end'
+```
+
+## Values
+
+- `below-start`
+- `below-end`
+- `above-start`
+- `above-end`
+
+## Used by
+
+- [bf-menu-button](../components/menu-button.md)
+- [BfMenuTriggerDirective](bf-menu-trigger-directive.md)

package/ai/reference/bf-menu-trigger-directive.md

@@ -0,0 +1,46 @@
+# BfMenuTriggerDirective
+
+Opens a menu from any element with the keyboard and focus rules of menus
+
+Directive from `@bitforgehq/ui/overlay` · since 0.3.0
+
+Opens a `bf-menu` template from any element on the Angular CDK menu trigger: it sets
+`aria-haspopup="menu"` and `aria-expanded`, opens on click, `Enter`, `Space` and `ArrowDown`
+(first item focused) or `ArrowUp` (last item), and takes focus back when the menu closes. A
+navigation to another URL path closes the open menu (with its submenus); the URL is watched
+only while the menu is open. On a
+`bfMenuItem` it opens a submenu beside the item instead (`ArrowRight`, `ArrowLeft` in RTL).
+`bf-menu-button` wraps it in a styled button.
+
+```ts
+import { BfMenuTriggerDirective } from '@bitforgehq/ui/overlay';
+```
+
+Selector: `[bfMenuTriggerFor]`
+
+## Inputs
+
+| Name                | Type                                                                               | Default         | Description                                                                                                                        |
+| ------------------- | ---------------------------------------------------------------------------------- | --------------- | ---------------------------------------------------------------------------------------------------------------------------------- |
+| `bfMenuPlacement`   | `BfMenuPlacement` (`'below-start' \| 'below-end' \| 'above-start' \| 'above-end'`) | `'below-start'` | Where the menu opens (flipping when it would overflow). A submenu always opens beside its item, at the inline end, and ignores it. |
+| `bfMenuTriggerFor`  | `TemplateRef<unknown> \| null`                                                     |                 | The `ng-template` holding the `bf-menu` this element opens.                                                                        |
+| `bfMenuTriggerData` | `unknown`                                                                          |                 | The context the menu template receives, for a menu shared by many triggers.                                                        |
+
+## Outputs
+
+| Name           | Payload | Description                                                                      |
+| -------------- | ------- | -------------------------------------------------------------------------------- |
+| `bfMenuOpened` | `void`  | Emits when the menu opens.                                                       |
+| `bfMenuClosed` | `void`  | Emits when the menu closes (an item, `Escape`, a click outside or a navigation). |
+
+## Methods
+
+### `labelId(): string`
+
+The trigger element's id (assigned when it has none), which names the menu it opens. It is
+read when the menu opens: an `[id]` bound on the trigger that changes while the menu is open
+names the menu from its next opening.
+
+## Uses
+
+- [BfMenuPlacement](bf-menu-placement.md)

package/ai/reference/bf-modal-options.md

@@ -0,0 +1,30 @@
+# BfModalOptions
+
+Options of a modal: its data, presentation, dismissal and accessible name
+
+Interface from `@bitforgehq/ui/mobile` · since 0.2.0
+
+Options of `BfModalService.open()`.
+
+```ts
+import { type BfModalOptions } from '@bitforgehq/ui/mobile';
+```
+
+## Properties
+
+| Name                | Type                                              | Default   | Description                                                                                                                                                                                                                                                                                                          |
+| ------------------- | ------------------------------------------------- | --------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `data`              | `unknown`                                         |           | Injected into the content as `BF_OVERLAY_DATA`.                                                                                                                                                                                                                                                                      |
+| `presentation`      | `BfModalPresentation` (`'sheet' \| 'fullscreen'`) | `'sheet'` | A page-sheet card over the parked page stack (default), or a fullscreen frame.                                                                                                                                                                                                                                       |
+| `dismissible`       | `boolean`                                         | `true`    | `Escape` and the hardware back button close the modal (default true); with false only the content's own close control does, or a navigation (see `closeOnNavigation`), and back is swallowed while the modal is open instead of falling through to the page behind. There is no backdrop dismiss or drag-to-dismiss. |
+| `closeOnNavigation` | `boolean`                                         | `true`    | A navigation to another URL path closes the modal with no result (default true).                                                                                                                                                                                                                                     |
+| `ariaLabel`         | `string`                                          |           | Accessible name of the modal panel. Without it the modal is named by the first heading in its content (`aria-labelledby`, e.g. the `bf-header` title), else by `provideBfLabels()`'s `modal` ("Modal").                                                                                                              |
+| `injector`          | `Injector`                                        |           | Injector the modal 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
+
+- [BfModalPresentation](bf-modal-presentation.md)
+
+## Used by
+
+- [BfModalService](bf-modal-service.md)

package/ai/reference/bf-modal-presentation.md

@@ -0,0 +1,26 @@
+# BfModalPresentation
+
+How a modal is presented: a page-sheet card over the stack, or fullscreen
+
+Type from `@bitforgehq/ui/mobile` · since 0.2.0
+
+Where `bf-modal` sits: a page-sheet card, or edge to edge.
+
+```ts
+import { type BfModalPresentation } from '@bitforgehq/ui/mobile';
+```
+
+## Signature
+
+```ts
+type BfModalPresentation = 'sheet' | 'fullscreen'
+```
+
+## Values
+
+- `sheet`
+- `fullscreen`
+
+## Used by
+
+- [BfModalOptions](bf-modal-options.md)

package/ai/reference/bf-modal-service.md

@@ -0,0 +1,38 @@
+# BfModalService
+
+Opens a component as a modal page sheet over the stack, or fullscreen
+
+Service from `@bitforgehq/ui/mobile` · since 0.2.0
+
+Opens modals: a component in a `bf-modal` frame on the overlay core (`position: 'fullscreen'`,
+no backdrop dismiss). `presentation: 'sheet'` (default) is a page-sheet card 10 px below the
+top safe area over the parked page stack, which in iOS mode scales down and grows rounded corners
+behind it (`countsAsModal: true`, driving `--bf-modal-depth` on the registered
+`bf-stack-outlet` roots; Material mode leaves the page unscaled); `'fullscreen'` covers the
+viewport edge to edge and does not count towards that depth. iOS mode
+slides the card up and down; Material mode fades it up (and down) 16 px. The content supplies
+its own `bf-header` (`largeTitle="false"`, typically a close `bf-icon-button` in `start`) and
+`bf-content` — `bf-modal` provides a `BfPageContext` for them, like `bf-page`. It injects the
+caller's `data` as `BF_OVERLAY_DATA` and closes itself with a result through the injected
+`BfOverlayRef`, which `open()` also returns. A navigation to another URL path closes it with no
+result (`closeOnNavigation`).
+
+```ts
+import { BfModalService } from '@bitforgehq/ui/mobile';
+```
+
+## Methods
+
+### `open<C, T = unknown>(component: Type<C>, options?: BfModalOptions): BfOverlayRef<T>`
+
+Opens `component` as a modal.
+
+| Parameter   | Type             | Description                                                               |
+| ----------- | ---------------- | ------------------------------------------------------------------------- |
+| `component` | `Type<C>`        | The component to render; it injects `BfOverlayRef` and `BF_OVERLAY_DATA`. |
+| `options?`  | `BfModalOptions` | The modal's data, presentation, dismissal and name.                       |
+
+## Uses
+
+- [BfModalOptions](bf-modal-options.md)
+- [BfOverlayRef](bf-overlay-ref.md)