@bitforgehq/ui 0.3.0

package/ai/reference/bf-nav-controller.md

@@ -0,0 +1,59 @@
+# BfNavController
+
+Stack-aware navigation that pushes, pops through the history and replaces the root
+
+Service from `@bitforgehq/ui/mobile` · since 0.2.0
+
+Stack-aware navigation. `forward` pushes, `back` pops through the real history (so the browser
+or WebView history stays in sync), `root` replaces the whole stack. Each call leaves a direction
+hint that `bf-stack-outlet` consumes on the next activation; without a hint the outlet infers
+the direction from the router event. A hint lives only as long as the navigation it started:
+when that navigation ends without an activation (a guard refused it), the hint is dropped so it
+cannot mislabel the next one. Every primary `bf-stack-outlet` registers here with its nesting
+level; `depth`, `canGoBack` and `back()` follow the **deepest active outlet** (the innermost one
+whose page is shown, e.g. the outlet inside `bf-tabs`, or the root outlet once it pushed a page
+above the tabs page). The controller also owns the priority-0 hardware back handler: it pops the
+deepest active outlet that has a page to pop, and lets the app exit only when every active
+outlet is at its first page (a parked outlet cannot be popped, so it never blocks the exit).
+
+```ts
+import { BfNavController } from '@bitforgehq/ui/mobile';
+```
+
+## Properties
+
+| Name        | Type              | Default | Description                                                               |
+| ----------- | ----------------- | ------- | ------------------------------------------------------------------------- |
+| `depth`     | `Signal<number>`  |         | Number of pages in the deepest active stack outlet (0 without an outlet). |
+| `canGoBack` | `Signal<boolean>` |         | True when the deepest active stack has a page to go back to.              |
+
+## Methods
+
+### `forward(url: BfNavTarget, extras?: NavigationExtras): Promise<boolean>`
+
+Pushes a page.
+
+| Parameter | Type               | Description                                      |
+| --------- | ------------------ | ------------------------------------------------ |
+| `url`     | `BfNavTarget`      | Where to go.                                     |
+| `extras?` | `NavigationExtras` | Router navigation extras, such as `queryParams`. |
+
+### `root(url: BfNavTarget, extras?: NavigationExtras): Promise<boolean>`
+
+Replaces the whole stack with one page (`replaceUrl`, no animation).
+
+| Parameter | Type               | Description                                      |
+| --------- | ------------------ | ------------------------------------------------ |
+| `url`     | `BfNavTarget`      | Where to go.                                     |
+| `extras?` | `NavigationExtras` | Router navigation extras, such as `queryParams`. |
+
+### `back(): void`
+
+Pops the top page of the deepest active outlet that has one to pop: always a real history
+step. When the page added history entries of its own (a query-only or nested child
+navigation), it goes back past them in one step (`Location.historyGo(-n)`) so the page below
+is shown; otherwise `Location.back()`.
+
+## Uses
+
+- [BfNavTarget](bf-nav-target.md)

package/ai/reference/bf-nav-direction.md

@@ -0,0 +1,23 @@
+# BfNavDirection
+
+The direction a stack navigation animates in: forward, back or a new root
+
+Type from `@bitforgehq/ui/mobile` · since 0.2.0
+
+The direction a navigation should animate in.
+
+```ts
+import { type BfNavDirection } from '@bitforgehq/ui/mobile';
+```
+
+## Signature
+
+```ts
+type BfNavDirection = 'forward' | 'back' | 'root'
+```
+
+## Values
+
+- `forward`
+- `back`
+- `root`

package/ai/reference/bf-nav-target.md

@@ -0,0 +1,21 @@
+# BfNavTarget
+
+A navigation target as the router accepts it: a URL, a UrlTree or commands
+
+Type from `@bitforgehq/ui/mobile` · since 0.2.0
+
+A router target: a URL string, a `UrlTree` or a commands array, as `Router` accepts.
+
+```ts
+import { type BfNavTarget } from '@bitforgehq/ui/mobile';
+```
+
+## Signature
+
+```ts
+type BfNavTarget = string | UrlTree | readonly unknown[]
+```
+
+## Used by
+
+- [BfNavController](bf-nav-controller.md)

package/ai/reference/bf-number-input-mode.md

@@ -0,0 +1,28 @@
+# BfNumberInputMode
+
+The virtual keyboards a number field can ask a phone to show
+
+Type from `@bitforgehq/ui/number-input` · since 0.3.0
+
+The virtual keyboard of a `bf-number-input` (native `inputmode`); `''` picks one from `min` and
+`step`.
+
+```ts
+import { type BfNumberInputMode } from '@bitforgehq/ui/number-input';
+```
+
+## Signature
+
+```ts
+type BfNumberInputMode = 'numeric' | 'decimal' | ''
+```
+
+## Values
+
+- `numeric`
+- `decimal`
+- ``
+
+## Used by
+
+- [bf-number-input](../components/number-input.md)

package/ai/reference/bf-number-input-step.md

@@ -0,0 +1,25 @@
+# BfNumberInputStep
+
+The step of a number field, a number or any for no step check
+
+Type from `@bitforgehq/ui/number-input` · since 0.3.0
+
+The `step` of a `bf-number-input`: a number, or `'any'` for no step check.
+
+```ts
+import { type BfNumberInputStep } from '@bitforgehq/ui/number-input';
+```
+
+## Signature
+
+```ts
+type BfNumberInputStep = number | 'any'
+```
+
+## Values
+
+- `any`
+
+## Used by
+
+- [bf-number-input](../components/number-input.md)

package/ai/reference/bf-overlay-auto-focus.md

@@ -0,0 +1,29 @@
+# BfOverlayAutoFocus
+
+Where focus lands when an overlay opens, its first control or the panel
+
+Type from `@bitforgehq/ui/overlay` · since 0.3.0
+
+Where focus goes when an overlay opens: the first tabbable element of the content
+(`first-tabbable`, skipping the container's own controls such as `bf-sheet`'s hidden Close) or
+the panel itself (`panel`).
+
+```ts
+import { type BfOverlayAutoFocus } from '@bitforgehq/ui/overlay';
+```
+
+## Signature
+
+```ts
+type BfOverlayAutoFocus = 'first-tabbable' | 'panel'
+```
+
+## Values
+
+- `first-tabbable`
+- `panel`
+
+## Used by
+
+- [BfDialogConfig](bf-dialog-config.md)
+- [BfOverlayOptions](bf-overlay-options.md)

package/ai/reference/bf-overlay-controller.md

@@ -0,0 +1,22 @@
+# BfOverlayController
+
+What the overlay service does for a ref: close it and re-apply its position
+
+Interface from `@bitforgehq/ui/overlay` · since 0.2.0
+
+What the overlay service does for a ref. Exported for entries that extend `BfOverlayRef` with
+their own controller (the `/mobile` `BfSheetRef`); apps never implement it.
+
+```ts
+import { type BfOverlayController } from '@bitforgehq/ui/overlay';
+```
+
+## Methods
+
+### `close(): Promise<void>`
+
+Plays the exit animation, detaches the overlay and cleans up. Never rejects.
+
+### `updatePosition(): void`
+
+Re-applies the overlay's position (after its size changed).

package/ai/reference/bf-overlay-host.md

@@ -0,0 +1,36 @@
+# BfOverlayHost
+
+What a host shell tells the overlay core: back handling and document scroll
+
+Interface from `@bitforgehq/ui/overlay` · since 0.3.0
+
+What a host shell (the `/mobile` `provideBfShell()`) tells the overlay core. The core itself
+depends on no platform code: without a host, overlays register no hardware back handler and
+lock document scroll behind a modal overlay, and where the browser has `CloseWatcher`, its close
+requests (Android back in Chrome) close the top overlay.
+
+```ts
+import { type BfOverlayHost } from '@bitforgehq/ui/overlay';
+```
+
+## Properties
+
+| Name                | Type      | Default  | Description                                                                                                                                                                                                                                                |
+| ------------------- | --------- | -------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `documentScrolls`   | `boolean` | required | False when the document never scrolls (the mobile shell): overlays skip the scroll lock.                                                                                                                                                                   |
+| `handlesSystemBack` | `boolean` |          | True when the host already delivers the system back action to `registerBack` (the mobile shell on native Android, through Capacitor's `backButton` event): overlays then create no `CloseWatcher` of their own, so one back press never closes two things. |
+
+## Methods
+
+### `registerBack(priority: number, handler: () => boolean | Promise<boolean>): () => void`
+
+Registers a hardware back handler at `priority`; returns its unregister function.
+
+| Parameter  | Type                                | Description                                                |
+| ---------- | ----------------------------------- | ---------------------------------------------------------- |
+| `priority` | `number`                            | Higher runs first; the overlay core uses 100.              |
+| `handler`  | `() => boolean \| Promise<boolean>` | Returns (or resolves) true when it handled the back press. |
+
+## Used by
+
+- [BF_OVERLAY_HOST](bf_overlay_host.md)

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

@@ -0,0 +1,53 @@
+# BfOverlayOptions
+
+Options of an overlay: its data, backdrop, focus, dismissal, position and motion
+
+Interface from `@bitforgehq/ui/overlay` · since 0.2.0
+
+Also exported from `@bitforgehq/ui/mobile` (deprecated: 0.3.0 use BfOverlayOptions from '@bitforgehq/ui/overlay'; removed in 0.4.0).
+
+Options of `BfOverlayService.open()`.
+
+```ts
+import { type BfOverlayOptions } from '@bitforgehq/ui/overlay';
+```
+
+## Properties
+
+| Name                | Type                                                                  | Default                 | Description                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             |
+| ------------------- | --------------------------------------------------------------------- | ----------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `data`              | `unknown`                                                             |                         | Injected into the content as `BF_OVERLAY_DATA`.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         |
+| `panelClass`        | `string[]`                                                            |                         | Extra classes on the panel (it always carries `bf-overlay-panel`).                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      |
+| `backdrop`          | `boolean`                                                             | `true`                  | Renders a backdrop behind the panel (default true; never for passive overlays).                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         |
+| `backdropClass`     | `string`                                                              | `'bf-overlay-backdrop'` | Class of the backdrop (default `bf-overlay-backdrop`: a black scrim, 40 % light / 60 % dark).                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                           |
+| `dismissOnBackdrop` | `boolean`                                                             | `true`                  | A backdrop click closes the overlay (default true).                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     |
+| `dismissOnEscape`   | `boolean`                                                             | `true`                  | `Escape` closes the overlay (default true).                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             |
+| `onEscape`          | `() => void`                                                          |                         | Runs instead of closing when the overlay is on top and `Escape` is pressed (e.g. an alert resolving with its cancel button). The key is always claimed by the topmost non-passive overlay, so it never reaches an overlay underneath.                                                                                                                                                                                                                                                                                                                                                                                                                                                                   |
+| `role`              | `BfOverlayRole` (`'dialog' \| 'alertdialog' \| 'status'`)             | `'dialog'`              | Role of the panel (default `dialog`; passive overlays get none unless one is given — a toast is announced through `LiveAnnouncer`).                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     |
+| `ariaLabel`         | `string`                                                              |                         | Accessible name of the panel.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                           |
+| `ariaLabelledBy`    | `string`                                                              |                         | Id of the element naming the panel. Dropped after the content renders when no element inside the panel carries it and `ariaLabel` is unset, so the panel never points at nothing.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       |
+| `ariaDescribedBy`   | `string`                                                              |                         | Id of the element describing the panel (an alert's message).                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            |
+| `trapFocus`         | `boolean`                                                             | `true`                  | Traps Tab focus inside the panel (default true).                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        |
+| `autoFocus`         | `BfOverlayAutoFocus` (`'first-tabbable' \| 'panel'`)                  | `'first-tabbable'`      | Where focus goes on open (non-passive overlays): `first-tabbable` (default) — the element marked `[autofocus]`/`[cdkFocusInitial]` when it is focusable (a control, or any element with a `tabindex`, also `-1`), else the first tabbable element inside it, else (all its controls disabled) the first tabbable element of the panel, else the panel; `panel` — the panel itself, so a long text is read from its start (APG dialog pattern). `first-tabbable` skips the library's own container controls (`bf-sheet`'s hidden Close and grabber button, marked with the internal `data-bf-overlay-chrome`): they stay in the Tab order but never take the initial focus, so it lands on your content. |
+| `restoreFocus`      | `boolean`                                                             | `true`                  | Returns focus to the previously focused element on close (default true); when that element is gone, to the topmost overlay still open, else focus stays on the body (move it yourself, e.g. to the next row after a delete).                                                                                                                                                                                                                                                                                                                                                                                                                                                                            |
+| `position`          | `BfOverlayPosition` (`'bottom' \| 'center' \| 'top' \| 'fullscreen'`) | `'center'`              | Placement of the panel (default `center`).                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              |
+| `closeOnNavigation` | `boolean`                                                             | `true`                  | Closes the overlay when the URL path changes (default true; false for passive overlays): a router navigation, a link, the browser's back and forward buttons. Query- or fragment-only changes never close; a matrix-parameter change (`/a;x=1`) is a path change and closes. Read from `Location.onUrlChange()`, so no router is needed, and a `history.pushState()` made outside Angular's `Location` is not seen. An overlay opened before the first navigation ends (root component, `APP_INITIALIZER`) closes when the start URL redirects: open it after the first `NavigationEnd`, or pass false.                                                                                                 |
+| `onNavigation`      | `() => void`                                                          |                         | Runs instead of `close()` when a navigation closes the overlay (e.g. an alert answering with its cancel id); it should close the overlay.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               |
+| `backPriority`      | `number`                                                              | `100`                   | Priority of the hardware back handler that closes the overlay (default 100).                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            |
+| `countsAsModal`     | `boolean`                                                             | `false`                 | Counts towards `BfOverlayStack.depth()` / `--bf-modal-depth` (default false).                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                           |
+| `passive`           | `boolean`                                                             | `false`                 | A passive overlay (a toast) has no backdrop, no focus trap, does not move focus, does not count in `BfOverlayStack.count()`, registers no back handler and leaves the page interactive.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |
+| `enter`             | `(el: HTMLElement) => Animation \| null`                              | `fadeIn`                | Enter animation of the panel (default `fadeIn`); return null for none.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  |
+| `exit`              | `(el: HTMLElement) => Animation \| null`                              | `fadeOut`               | Exit animation of the panel (default `fadeOut`), awaited before detaching.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              |
+| `injector`          | `Injector`                                                            |                         | Parent of the content's injector (default the root injector), so the content resolves the opener's providers, e.g. a feature-level `provideBfLabels()`.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |
+| `providers`         | `(ref: BfOverlayRef<unknown>) => StaticProvider[]`                    |                         | Extra providers of the content's injector, next to `BF_OVERLAY_DATA` and `BfOverlayRef`, built with the new overlay's ref (e.g. a typed ref of a service built on the core).                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            |
+
+## Uses
+
+- [BfOverlayAutoFocus](bf-overlay-auto-focus.md)
+- [BfOverlayPosition](bf-overlay-position.md)
+- [BfOverlayRef](bf-overlay-ref.md)
+- [BfOverlayRole](bf-overlay-role.md)
+
+## Used by
+
+- [BfOverlayService](bf-overlay-service.md)

package/ai/reference/bf-overlay-position.md

@@ -0,0 +1,30 @@
+# BfOverlayPosition
+
+Where an overlay panel sits in the viewport: bottom, centre, top or fullscreen
+
+Type from `@bitforgehq/ui/overlay` · since 0.2.0
+
+Also exported from `@bitforgehq/ui/mobile` (deprecated: 0.3.0 use BfOverlayPosition from '@bitforgehq/ui/overlay'; removed in 0.4.0).
+
+Where the overlay's panel sits in the viewport.
+
+```ts
+import { type BfOverlayPosition } from '@bitforgehq/ui/overlay';
+```
+
+## Signature
+
+```ts
+type BfOverlayPosition = 'bottom' | 'center' | 'top' | 'fullscreen'
+```
+
+## Values
+
+- `bottom`
+- `center`
+- `top`
+- `fullscreen`
+
+## Used by
+
+- [BfOverlayOptions](bf-overlay-options.md)

package/ai/reference/bf-overlay-ref.md

@@ -0,0 +1,53 @@
+# BfOverlayRef
+
+Handle on an open overlay that closes it and resolves with its result
+
+Class from `@bitforgehq/ui/overlay` · since 0.2.0
+
+Also exported from `@bitforgehq/ui/mobile` (deprecated: 0.3.0 use BfOverlayRef from '@bitforgehq/ui/overlay'; removed in 0.4.0).
+
+Handle to an open overlay, returned by `BfOverlayService.open()` and injectable in the
+overlay's content. `close(result)` plays the exit animation, detaches the overlay and resolves
+`afterClosed` with `result`; later calls are ignored.
+
+```ts
+import { BfOverlayRef } from '@bitforgehq/ui/overlay';
+```
+
+## Signature
+
+```ts
+class BfOverlayRef<T = unknown>
+```
+
+## Properties
+
+| Name          | Type                      | Default | Description                                                                      |
+| ------------- | ------------------------- | ------- | -------------------------------------------------------------------------------- |
+| `id`          | `string`                  |         | Unique id of the overlay (`bf-overlay-N`).                                       |
+| `afterClosed` | `Promise<T \| undefined>` |         | Resolves with the result given to `close()` once the overlay is detached.        |
+| `closed`      | `Signal<boolean>`         |         | True once the overlay has been detached.                                         |
+| `isClosing`   | `boolean`                 |         | True from the first `close()` call on (the exit animation may still be running). |
+
+## Methods
+
+### `close(result?: T): void`
+
+Closes the overlay with an optional result; ignored once closing.
+
+| Parameter | Type | Description                            |
+| --------- | ---- | -------------------------------------- |
+| `result?` | `T`  | The value `afterClosed` resolves with. |
+
+### `updatePosition(): void`
+
+Re-applies the overlay's position (after its size changed).
+
+## Used by
+
+- [BfComponentOverlayRef](bf-component-overlay-ref.md)
+- [BfModalService](bf-modal-service.md)
+- [BfOverlayOptions](bf-overlay-options.md)
+- [BfOverlayService](bf-overlay-service.md)
+- [BfOverlayTemplateContext](bf-overlay-template-context.md)
+- [BfSheetRef](bf-sheet-ref.md)

package/ai/reference/bf-overlay-role.md

@@ -0,0 +1,27 @@
+# BfOverlayRole
+
+The role an overlay panel carries: a dialog, an alert dialog or a status
+
+Type from `@bitforgehq/ui/overlay` · since 0.3.0
+
+The ARIA role of an overlay panel: a `dialog`, an `alertdialog` or a passive `status`.
+
+```ts
+import { type BfOverlayRole } from '@bitforgehq/ui/overlay';
+```
+
+## Signature
+
+```ts
+type BfOverlayRole = 'dialog' | 'alertdialog' | 'status'
+```
+
+## Values
+
+- `dialog`
+- `alertdialog`
+- `status`
+
+## Used by
+
+- [BfOverlayOptions](bf-overlay-options.md)

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

@@ -0,0 +1,53 @@
+# BfOverlayService
+
+Opens a component or template in an overlay panel on the Angular CDK
+
+Service from `@bitforgehq/ui/overlay` · since 0.2.0
+
+Also exported from `@bitforgehq/ui/mobile` (deprecated: 0.3.0 use BfOverlayService from '@bitforgehq/ui/overlay'; removed in 0.4.0).
+
+Opens overlays on the Angular CDK `Overlay`: a component or template in a panel with a
+backdrop, a focus trap, `role`/`aria-modal`/`aria-labelledby`, `Escape` and backdrop click
+closing it, and the page behind it `inert` (see `BfOverlayStack`). A non-passive overlay blocks
+document scroll (CDK `block()` scroll strategy); passive overlays, and every overlay under a
+`BF_OVERLAY_HOST` whose document never scrolls (the `/mobile` `provideBfShell()`), use `noop()`.
+Under `provideBfShell()` the hardware back button (priority 100) closes it too; without a host
+no back handler is registered. Where the browser has `CloseWatcher` (Chromium 120+), a close
+request (Android back in Chrome or a PWA) runs the `Escape` path on the top non-passive overlay,
+unless the host handles the system back itself (`handlesSystemBack`). An overlay that does not
+close on it (`dismissOnEscape: false` without `onEscape`, or an `onEscape` that keeps it open)
+swallows Android web back for as long as it is open, as a non-dismissible sheet swallows the
+hardware back button. A navigation to another URL path closes every non-passive
+overlay (`closeOnNavigation`, read from `Location`, so no router is needed). The content
+injects `BF_OVERLAY_DATA` and `BfOverlayRef` (plus any `providers`). `BfDialogService` and the
+`/mobile` sheet, modal, toast, action sheet and alert services build on it.
+
+```ts
+import { BfOverlayService } from '@bitforgehq/ui/overlay';
+```
+
+## Methods
+
+### `open<C, T = unknown>(component: Type<C>, options?: BfOverlayOptions): BfComponentOverlayRef<C, T>`
+
+Opens `component` in an overlay.
+
+| Parameter   | Type               | Description                                                          |
+| ----------- | ------------------ | -------------------------------------------------------------------- |
+| `component` | `Type<C>`          | The component to render in the panel.                                |
+| `options?`  | `BfOverlayOptions` | The overlay's data, backdrop, focus, dismissal, position and motion. |
+
+### `open<T = unknown>(template: TemplateRef<unknown>, options?: BfOverlayOptions): BfOverlayRef<T>`
+
+Opens `template` in an overlay; its context is `{ $implicit: ref, data }`.
+
+| Parameter  | Type                   | Description                                                          |
+| ---------- | ---------------------- | -------------------------------------------------------------------- |
+| `template` | `TemplateRef<unknown>` | The template to render in the panel.                                 |
+| `options?` | `BfOverlayOptions`     | The overlay's data, backdrop, focus, dismissal, position and motion. |
+
+## Uses
+
+- [BfComponentOverlayRef](bf-component-overlay-ref.md)
+- [BfOverlayOptions](bf-overlay-options.md)
+- [BfOverlayRef](bf-overlay-ref.md)

package/ai/reference/bf-overlay-stack-options.md

@@ -0,0 +1,24 @@
+# BfOverlayStackOptions
+
+How an overlay takes part in the stack: its back priority and modal depth
+
+Interface from `@bitforgehq/ui/overlay` · since 0.2.0
+
+Also exported from `@bitforgehq/ui/mobile` (deprecated: 0.3.0 use BfOverlayStackOptions from '@bitforgehq/ui/overlay'; removed in 0.4.0).
+
+How an overlay takes part in the stack.
+
+```ts
+import { type BfOverlayStackOptions } from '@bitforgehq/ui/overlay';
+```
+
+## Properties
+
+| Name            | Type      | Default | Description                                                          |
+| --------------- | --------- | ------- | -------------------------------------------------------------------- |
+| `backPriority`  | `number`  | `100`   | Priority of its hardware back handler (default 100).                 |
+| `countsAsModal` | `boolean` | `false` | Counts towards `depth()` and `--bf-modal-depth` (page-sheet modals). |
+
+## Used by
+
+- [BfOverlayStack](bf-overlay-stack.md)

package/ai/reference/bf-overlay-stack.md

@@ -0,0 +1,81 @@
+# BfOverlayStack
+
+Keeps the open overlays in order and makes the page behind them inert
+
+Service from `@bitforgehq/ui/overlay` · since 0.2.0
+
+Also exported from `@bitforgehq/ui/mobile` (deprecated: 0.3.0 use BfOverlayStack from '@bitforgehq/ui/overlay'; removed in 0.4.0).
+
+The open modal-like overlays, in order. While any is open, every registered page root (the
+`/mobile` `bf-stack-outlet` hosts register themselves) is `inert`, and `--bf-modal-depth` on the
+roots carries the number of open modals. With no registered root (a desktop page), every direct
+child of `document.body` becomes `inert` instead, except those holding a CDK overlay container
+(`.cdk-overlay-container`, found without importing the CDK), the CDK live
+announcer and `AriaDescriber` containers, `script`/`style`/`template`/`link` and body children
+carrying `data-bf-overlay-keep`; an element that was already `inert` keeps it on close. When
+the stack's injector is destroyed (the app torn down with an overlay open), it removes every
+`inert` and `--bf-modal-depth` it set. Under a `BF_OVERLAY_HOST`
+(`provideBfShell()`) each pushed overlay registers a hardware back handler that closes it; on
+equal priority the newest overlay closes first. Passive overlays (toasts) are never pushed.
+
+```ts
+import { BfOverlayStack } from '@bitforgehq/ui/overlay';
+```
+
+## Properties
+
+| Name    | Type             | Default | Description                                                               |
+| ------- | ---------------- | ------- | ------------------------------------------------------------------------- |
+| `count` | `Signal<number>` |         | Number of open modal-like overlays.                                       |
+| `depth` | `Signal<number>` |         | Number of open overlays that count as modals (drives `--bf-modal-depth`). |
+
+## Methods
+
+### `registerRoot(el: HTMLElement): () => void`
+
+Registers a page root that becomes `inert` while an overlay is open. Returns a function that
+unregisters it (and clears what the stack set on it).
+
+| Parameter | Type          | Description                                      |
+| --------- | ------------- | ------------------------------------------------ |
+| `el`      | `HTMLElement` | The page root, such as a `bf-stack-outlet` host. |
+
+### `push(ref: BfStackedOverlay, options?: BfOverlayStackOptions): void`
+
+Adds an overlay on top of the stack. Outside a shell, every body child that holds a CDK
+overlay container (`.cdk-overlay-container`) stays active, so an overlay created on the CDK
+directly, not through `BfOverlayService`, can be pushed as well.
+
+| Parameter  | Type                    | Description                                         |
+| ---------- | ----------------------- | --------------------------------------------------- |
+| `ref`      | `BfStackedOverlay`      | The overlay's ref.                                  |
+| `options?` | `BfOverlayStackOptions` | Its back priority and whether it counts as a modal. |
+
+### `pop(ref: BfStackedOverlay): void`
+
+Removes an overlay from the stack.
+
+| Parameter | Type               | Description        |
+| --------- | ------------------ | ------------------ |
+| `ref`     | `BfStackedOverlay` | The overlay's ref. |
+
+### `isTop(ref: BfStackedOverlay): boolean`
+
+True when `ref` is the newest overlay in the stack (the one that answers `Escape`).
+
+| Parameter | Type               | Description        |
+| --------- | ------------------ | ------------------ |
+| `ref`     | `BfStackedOverlay` | The overlay's ref. |
+
+### `releaseBack(ref: BfStackedOverlay): void`
+
+Stops the back handler of an overlay that is closing, while it stays in the stack.
+
+| Parameter | Type               | Description        |
+| --------- | ------------------ | ------------------ |
+| `ref`     | `BfStackedOverlay` | The overlay's ref. |
+
+## Uses
+
+- [BfOverlayStackOptions](bf-overlay-stack-options.md)
+- [BfStackedOverlay](bf-stacked-overlay.md)

package/ai/reference/bf-overlay-template-context.md

@@ -0,0 +1,24 @@
+# BfOverlayTemplateContext
+
+The context a template opened as an overlay receives: its ref and data
+
+Interface from `@bitforgehq/ui/overlay` · since 0.2.0
+
+Also exported from `@bitforgehq/ui/mobile` (deprecated: 0.3.0 use BfOverlayTemplateContext from '@bitforgehq/ui/overlay'; removed in 0.4.0).
+
+Context of a template opened as an overlay: `let-ref` and `let-data="data"`.
+
+```ts
+import { type BfOverlayTemplateContext } from '@bitforgehq/ui/overlay';
+```
+
+## Properties
+
+| Name        | Type                    | Default  | Description                                                 |
+| ----------- | ----------------------- | -------- | ----------------------------------------------------------- |
+| `$implicit` | `BfOverlayRef<unknown>` | required | The overlay's ref (`let-ref`), to close it with a result.   |
+| `data`      | `unknown`               | required | The `data` the overlay was opened with (`let-data="data"`). |
+
+## Uses
+
+- [BfOverlayRef](bf-overlay-ref.md)