@bitforgehq/ui 0.3.0

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

@@ -0,0 +1,29 @@
+# BfSheetAutoFocus
+
+Where focus lands when a sheet opens, the sheet itself or its first field
+
+Type from `@bitforgehq/ui/mobile` · since 0.3.0
+
+Where focus goes when a sheet opens: the sheet itself (`panel`), so no soft keyboard comes up
+and a screen reader starts reading at the sheet, or its first field (`first-field`): the element
+marked `[autofocus]`/`[cdkFocusInitial]`, else the first focusable element of the content, which
+raises the keyboard on Android when it is a text field.
+
+```ts
+import { type BfSheetAutoFocus } from '@bitforgehq/ui/mobile';
+```
+
+## Signature
+
+```ts
+type BfSheetAutoFocus = 'panel' | 'first-field'
+```
+
+## Values
+
+- `panel`
+- `first-field`
+
+## Used by
+
+- [BfSheetOptions](bf-sheet-options.md)

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

@@ -0,0 +1,32 @@
+# BfSheetOptions
+
+Options of a bottom sheet: where it rests, how it closes and its name
+
+Interface from `@bitforgehq/ui/mobile` · since 0.2.0
+
+Options of `BfSheetService.open()`.
+
+```ts
+import { type BfSheetOptions } from '@bitforgehq/ui/mobile';
+```
+
+## Properties
+
+| Name                | Type                                            | Default       | Description                                                                                                                                                                                                                                                                                                                                                                                                                      |
+| ------------------- | ----------------------------------------------- | ------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `snapPoints`        | `number[]`                                      | `[0.5, 0.92]` | Heights the sheet rests at, as fractions of the viewport height (default `[0.5, 0.92]`).                                                                                                                                                                                                                                                                                                                                         |
+| `initial`           | `number`                                        | `0`           | Index of the snap point the sheet opens at (default 0).                                                                                                                                                                                                                                                                                                                                                                          |
+| `dismissible`       | `boolean`                                       | `true`        | The backdrop, `Escape`, the hardware back button and a downward drag close the sheet (default true). When false only `close()` does, or a navigation (see `closeOnNavigation`).                                                                                                                                                                                                                                                  |
+| `data`              | `unknown`                                       |               | Injected into the content as `BF_OVERLAY_DATA`.                                                                                                                                                                                                                                                                                                                                                                                  |
+| `closeOnNavigation` | `boolean`                                       | `true`        | A navigation to another URL path (a pushed or popped page, a tab switch) closes the sheet with no result (default true), also a non-dismissible one.                                                                                                                                                                                                                                                                             |
+| `ariaLabel`         | `string`                                        |               | Accessible name of the sheet. Without it the sheet is named by the first heading in its content (`aria-labelledby`), else by `provideBfLabels()`'s `sheet` ("Sheet").                                                                                                                                                                                                                                                            |
+| `autoFocus`         | `BfSheetAutoFocus` (`'panel' \| 'first-field'`) | `'panel'`     | Where focus goes on open: `panel` (default) focuses the sheet itself (a `role="dialog"` with a name and `tabindex="-1"`), so a screen reader lands inside it and no soft keyboard hides it; `first-field` focuses the element marked `[autofocus]`/`[cdkFocusInitial]`, else the first focusable element of the content (never the sheet's own Close and grabber), which raises the keyboard on Android when it is a text field. |
+| `injector`          | `Injector`                                      |               | Injector the 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
+
+- [BfSheetAutoFocus](bf-sheet-auto-focus.md)
+
+## Used by
+
+- [BfSheetService](bf-sheet-service.md)

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

@@ -0,0 +1,45 @@
+# BfSheetRef
+
+Handle on an open bottom sheet that moves it between snap points and closes it
+
+Class from `@bitforgehq/ui/mobile` · since 0.2.0
+
+Handle to an open bottom sheet, returned by `BfSheetService.open()` and injectable in the
+sheet's content as `BfSheetRef` (and as `BfOverlayRef`). On top of `close(result)` and
+`afterClosed` it moves the sheet between its snap points: `snapTo(index)` animates to a point
+and `snapIndex()` tracks the current one (also after a drag).
+
+```ts
+import { BfSheetRef } from '@bitforgehq/ui/mobile';
+```
+
+## Signature
+
+```ts
+class BfSheetRef<T = unknown> extends BfOverlayRef<T>
+```
+
+## Properties
+
+| Name        | Type             | Default | Description                                                            |
+| ----------- | ---------------- | ------- | ---------------------------------------------------------------------- |
+| `snapIndex` | `Signal<number>` |         | Index of the snap point the sheet rests at (or is settling to).        |
+| `isClosing` | `boolean`        |         | True from the first close on, whichever way the sheet is being closed. |
+
+## Methods
+
+### `snapTo(index: number): void`
+
+Animates the sheet to the snap point at `index` (clamped to the configured points).
+
+| Parameter | Type     | Description                                     |
+| --------- | -------- | ----------------------------------------------- |
+| `index`   | `number` | The position of the snap point in `snapPoints`. |
+
+## Uses
+
+- [BfOverlayRef](bf-overlay-ref.md)
+
+## Used by
+
+- [BfSheetService](bf-sheet-service.md)

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

@@ -0,0 +1,34 @@
+# BfSheetService
+
+Opens bottom sheets that rest at snap points and close with a result
+
+Service from `@bitforgehq/ui/mobile` · since 0.2.0
+
+Opens bottom sheets: a component or template in a `bf-sheet` container on the overlay core,
+bottom-anchored over a backdrop, resting at snap points (fractions of the viewport height).
+The content injects `BF_OVERLAY_DATA` and `BfSheetRef` (also as `BfOverlayRef`) to read its
+data, move between snap points and close with a result. A dismissible sheet (the default)
+closes on a backdrop tap, `Escape`, the hardware back button and a drag below its lowest
+point; a non-dismissible one only through `close()`, and swallows the back button while open.
+A navigation to another URL path closes either (`closeOnNavigation`). On open, focus goes to the
+sheet itself, so no soft keyboard comes up (`autoFocus: 'first-field'` focuses the first field).
+
+```ts
+import { BfSheetService } from '@bitforgehq/ui/mobile';
+```
+
+## Methods
+
+### `open<C, T = unknown>(content: Type<C> | TemplateRef<unknown>, options?: BfSheetOptions): BfSheetRef<T>`
+
+Opens `content` (a component or a template) in a bottom sheet.
+
+| Parameter  | Type                              | Description                                        |
+| ---------- | --------------------------------- | -------------------------------------------------- |
+| `content`  | `Type<C> \| TemplateRef<unknown>` | The component or template to render in the sheet.  |
+| `options?` | `BfSheetOptions`                  | Where the sheet rests, how it closes and its name. |
+
+## Uses
+
+- [BfSheetOptions](bf-sheet-options.md)
+- [BfSheetRef](bf-sheet-ref.md)

package/ai/reference/bf-shell-config-mode.md

@@ -0,0 +1,28 @@
+# BfShellConfigMode
+
+The shell style setting, iOS, Material or automatic from the platform
+
+Type from `@bitforgehq/ui/mobile` · since 0.3.0
+
+The shell's transition and gesture style: `ios`, `md` (Material), or `auto` (iOS on iOS, else
+`md`).
+
+```ts
+import { type BfShellConfigMode } from '@bitforgehq/ui/mobile';
+```
+
+## Signature
+
+```ts
+type BfShellConfigMode = 'ios' | 'md' | 'auto'
+```
+
+## Values
+
+- `ios`
+- `md`
+- `auto`
+
+## Used by
+
+- [BfShellConfig](bf-shell-config.md)

package/ai/reference/bf-shell-config.md

@@ -0,0 +1,38 @@
+# BfShellConfig
+
+The mobile shell settings: mode, swipe-back, haptics, Dynamic Type and system bars
+
+Interface from `@bitforgehq/ui/mobile` · since 0.2.0
+
+Configuration of the mobile shell, set once through `provideBfShell()`.
+
+```ts
+import { type BfShellConfig } from '@bitforgehq/ui/mobile';
+```
+
+## Properties
+
+| Name                   | Type                                                      | Default              | Description                                                                                                                                                                                                                                                                                                                                                                                                                                                |
+| ---------------------- | --------------------------------------------------------- | -------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `mode`                 | `BfShellConfigMode` (`'ios' \| 'md' \| 'auto'`)           | `'auto'`             | Transition and gesture style: `ios`, `md` (Material), or `auto` (iOS on iOS, else `md`). Overscroll is not part of it: `bf-content`'s iOS bounce and Android stretch and `bf-refresher`'s iOS bounce mode follow the engine (`BfPlatformService.mode()`), because the bounce is WebKit's own and Chrome never reports a negative `scrollTop`.                                                                                                              |
+| `swipeBack`            | `boolean`                                                 | `true`               | Enables the iOS edge swipe-back in every stack outlet (iOS mode only).                                                                                                                                                                                                                                                                                                                                                                                     |
+| `deferTransitionStart` | `boolean`                                                 | `true`               | Holds a transition at frame 0 for two animation frames while the entering page renders.                                                                                                                                                                                                                                                                                                                                                                    |
+| `hapticsOnTabChange`   | `boolean`                                                 | `true`               | Plays a light haptic tick on tab changes (native only).                                                                                                                                                                                                                                                                                                                                                                                                    |
+| `dynamicType`          | `BfShellDynamicType` (`false \| BfShellDynamicTypeLimit`) | `{ maxScale: 2.35 }` | iOS Dynamic Type (native iOS only; see `BfTextScaleService`): the root font size follows the user's text size. `false` opts out; `maxScale` caps the root scale (default 2.35, the AX3 size, at least 200 %). `Infinity` removes the cap entirely; a non-finite value other than `Infinity` (e.g. `NaN`) falls back to the default cap. Left out, the default applies. Android needs no setting: its WebView applies the system font scale.                |
+| `syncSystemBars`       | `boolean`                                                 | `true`               | Native iOS and Android only: the status-bar and navigation-bar icons follow the in-app theme (`BfPlatformService.dark()`) through Capacitor's `SystemBars.setStyle()`, on start and on every theme change (see `bfSystemBarsStyle()`). `false` leaves the system bars to the app.                                                                                                                                                                          |
+| `backAtRoot`           | `BfBackAtRoot` (`'minimize' \| 'exit'`)                   | `'minimize'`         | Native Android only: what the back button does when no overlay and no stack can go back (every stack is at its first page). `minimize` (default) moves the app to the background, as Android does for a root activity, so a relaunch resumes it warm on the same tab; `exit` finishes the activity, as 0.2 did, so the next launch starts cold.                                                                                                            |
+| `maxLivePages`         | `number`                                                  | `Infinity`           | How many pages of one stack stay alive in each `bf-stack-outlet` (default `Infinity`: every page). Above it, the deepest pages are destroyed and kept as a record (route, URL, history position and the content's scroll position); a pop back to one creates the page again, fires its lifecycle and restores its scroll. Deep pages come back fresh: their component state and the stacks of outlets nested in them are gone. Values below 1 count as 1. |
+
+## Uses
+
+- [BfBackAtRoot](bf-back-at-root.md)
+- [BfShellConfigMode](bf-shell-config-mode.md)
+- [BfShellDynamicType](bf-shell-dynamic-type.md)
+
+## Used by
+
+- [BfShellTestingOptions](bf-shell-testing-options.md)
+- [BF_SHELL_CONFIG](bf_shell_config.md)
+- [BF_SHELL_DEFAULTS](bf_shell_defaults.md)
+- [provideBfShell](provide-bf-shell.md)
+- [resolveShellMode](resolve-shell-mode.md)

package/ai/reference/bf-shell-dynamic-type-limit.md

@@ -0,0 +1,21 @@
+# BfShellDynamicTypeLimit
+
+The largest root font scale iOS Dynamic Type may apply in the shell
+
+Interface from `@bitforgehq/ui/mobile` · since 0.3.0
+
+The cap of iOS Dynamic Type: the largest root font scale the shell applies.
+
+```ts
+import { type BfShellDynamicTypeLimit } from '@bitforgehq/ui/mobile';
+```
+
+## Properties
+
+| Name       | Type     | Default  | Description                                                                               |
+| ---------- | -------- | -------- | ----------------------------------------------------------------------------------------- |
+| `maxScale` | `number` | required | The largest root font scale (2.35, the AX3 size, by default); `Infinity` removes the cap. |
+
+## Used by
+
+- [BfShellDynamicType](bf-shell-dynamic-type.md)

package/ai/reference/bf-shell-dynamic-type.md

@@ -0,0 +1,25 @@
+# BfShellDynamicType
+
+Whether the shell follows iOS Dynamic Type, and up to which scale
+
+Type from `@bitforgehq/ui/mobile` · since 0.3.0
+
+The shell's iOS Dynamic Type setting: `false` opts out, a `BfShellDynamicTypeLimit` caps it.
+
+```ts
+import { type BfShellDynamicType } from '@bitforgehq/ui/mobile';
+```
+
+## Signature
+
+```ts
+type BfShellDynamicType = false | BfShellDynamicTypeLimit
+```
+
+## Uses
+
+- [BfShellDynamicTypeLimit](bf-shell-dynamic-type-limit.md)
+
+## Used by
+
+- [BfShellConfig](bf-shell-config.md)

package/ai/reference/bf-shell-mode.md

@@ -0,0 +1,28 @@
+# BfShellMode
+
+The shell's look and motion conventions, iOS or Material Design
+
+Type from `@bitforgehq/ui/mobile` · since 0.2.0
+
+The shell's look and motion: `ios`, or `md` (Material) everywhere else.
+
+```ts
+import { type BfShellMode } from '@bitforgehq/ui/mobile';
+```
+
+## Signature
+
+```ts
+type BfShellMode = 'ios' | 'md'
+```
+
+## Values
+
+- `ios`
+- `md`
+
+## Used by
+
+- [BfPlatformService](bf-platform-service.md)
+- [injectShellMode](inject-shell-mode.md)
+- [resolveShellMode](resolve-shell-mode.md)

package/ai/reference/bf-shell-testing-options.md

@@ -0,0 +1,26 @@
+# BfShellTestingOptions
+
+Options of the shell test providers: the routes and the shell settings
+
+Interface from `@bitforgehq/ui/mobile` · since 0.3.0
+
+Options of `provideBfShellTesting()`.
+
+```ts
+import { type BfShellTestingOptions } from '@bitforgehq/ui/mobile';
+```
+
+## Properties
+
+| Name     | Type                     | Default | Description                                                                              |
+| -------- | ------------------------ | ------- | ---------------------------------------------------------------------------------------- |
+| `routes` | `Routes`                 | `[]`    | The routes of the test router.                                                           |
+| `config` | `Partial<BfShellConfig>` |         | Shell settings over the test defaults (`swipeBack: false`, `hapticsOnTabChange: false`). |
+
+## Uses
+
+- [BfShellConfig](bf-shell-config.md)
+
+## Used by
+
+- [provideBfShellTesting](provide-bf-shell-testing.md)

package/ai/reference/bf-size.md

@@ -0,0 +1,45 @@
+# BfSize
+
+The three height steps every sized field and control shares
+
+Type from `@bitforgehq/ui` · since 0.3.0
+
+The one control-height scale: sm 32 px, md 40 px, lg 48 px.
+
+```ts
+import { type BfSize } from '@bitforgehq/ui';
+```
+
+## Signature
+
+```ts
+type BfSize = 'sm' | 'md' | 'lg'
+```
+
+## Values
+
+- `sm`
+- `md`
+- `lg`
+
+## Used by
+
+- [bf-button](../components/button.md)
+- [BfButtonSize](bf-button-size.md)
+- [bf-checkbox](../components/checkbox.md)
+- [bf-chip](../components/chip.md)
+- [BfDefaults](bf-defaults.md)
+- [BfDefaultsOptions](bf-defaults-options.md)
+- [BfFieldControlState](bf-field-control-state.md)
+- [BfFieldSize](bf-field-size.md)
+- [bf-icon-button](../components/icon-button.md)
+- [bf-input](../components/input.md)
+- [bf-menu-button](../components/menu-button.md)
+- [bf-menu](../components/menu.md)
+- [bf-number-input](../components/number-input.md)
+- [bf-radio-group](../components/radio-group.md)
+- [bf-segmented](../components/segmented.md)
+- [BfSegmentedSize](bf-segmented-size.md)
+- [bf-select](../components/select.md)
+- [bf-textarea](../components/textarea.md)
+- [bf-toggle](../components/toggle.md)

package/ai/reference/bf-spinner-size.md

@@ -0,0 +1,27 @@
+# BfSpinnerSize
+
+The three spinner diameters, from inline text to a page loading state
+
+Type from `@bitforgehq/ui` · since 0.1.0
+
+The diameter of a `bf-spinner`: sm, md or lg.
+
+```ts
+import { type BfSpinnerSize } from '@bitforgehq/ui';
+```
+
+## Signature
+
+```ts
+type BfSpinnerSize = 'sm' | 'md' | 'lg'
+```
+
+## Values
+
+- `sm`
+- `md`
+- `lg`
+
+## Used by
+
+- [bf-spinner](../components/spinner.md)

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

@@ -0,0 +1,22 @@
+# BfStackChange
+
+What a stack outlet reports after its stack changed: the depth and the tab
+
+Interface from `@bitforgehq/ui/mobile` · since 0.2.0
+
+Emitted by `bf-stack-outlet` after every change of its stack.
+
+```ts
+import { type BfStackChange } from '@bitforgehq/ui/mobile';
+```
+
+## Properties
+
+| Name     | Type             | Default  | Description                                                                           |
+| -------- | ---------------- | -------- | ------------------------------------------------------------------------------------- |
+| `depth`  | `number`         | required | Number of pages in the active stack.                                                  |
+| `tabKey` | `string \| null` | required | Key of the active tab's stack inside `bf-tabs`; null for an outlet outside `bf-tabs`. |
+
+## Used by
+
+- [bf-stack-outlet](../components/stack-outlet.md)

package/ai/reference/bf-stack-reuse-strategy.md

@@ -0,0 +1,32 @@
+# BfStackReuseStrategy
+
+Route reuse strategy that treats a changed path parameter as a new stack page
+
+Service from `@bitforgehq/ui/mobile` · since 0.2.0
+
+The route reuse strategy the stack needs: the default one, except that a route whose _path
+params_ change (`/items/4` → `/items/5`) is a new page, not an in-place update. The default only
+compares `routeConfig`, so the router would reuse the component and never call the outlet, and
+the stack would no longer match the history. Query-param changes still reuse the page (filters,
+tabs). Exported so an app can extend it for its own reuse rules.
+
+```ts
+import { BfStackReuseStrategy } from '@bitforgehq/ui/mobile';
+```
+
+## Signature
+
+```ts
+class BfStackReuseStrategy extends BaseRouteReuseStrategy
+```
+
+## Methods
+
+### `shouldReuseRoute(future: ActivatedRouteSnapshot, curr: ActivatedRouteSnapshot): boolean`
+
+Whether the router may reuse the current page for `future`: same route config and path params.
+
+| Parameter | Type                     | Description                   |
+| --------- | ------------------------ | ----------------------------- |
+| `future`  | `ActivatedRouteSnapshot` | The route being navigated to. |
+| `curr`    | `ActivatedRouteSnapshot` | The route shown now.          |

package/ai/reference/bf-stack-transition-event.md

@@ -0,0 +1,26 @@
+# BfStackTransitionEvent
+
+What a stack outlet reports around a page transition: its kind and animation
+
+Interface from `@bitforgehq/ui/mobile` · since 0.2.0
+
+Emitted by `bf-stack-outlet` around a transition between two pages.
+
+```ts
+import { type BfStackTransitionEvent } from '@bitforgehq/ui/mobile';
+```
+
+## Properties
+
+| Name       | Type                                   | Default  | Description                                                                   |
+| ---------- | -------------------------------------- | -------- | ----------------------------------------------------------------------------- |
+| `kind`     | `BfTransitionKind` (`'push' \| 'pop'`) | required | `push` for a new page (also a `replaceUrl` navigation), `pop` for going back. |
+| `animated` | `boolean`                              | required | False when the pages switched without an animation (`animated=false`).        |
+
+## Uses
+
+- [BfTransitionKind](bf-transition-kind.md)
+
+## Used by
+
+- [bf-stack-outlet](../components/stack-outlet.md)

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

@@ -0,0 +1,26 @@
+# BfStackTransition
+
+A running set of page transition animations that finish together
+
+Interface from `@bitforgehq/ui/mobile` · since 0.2.0
+
+A running set of animations that finish together.
+
+```ts
+import { type BfStackTransition } from '@bitforgehq/ui/mobile';
+```
+
+## Properties
+
+| Name         | Type            | Default  | Description                                                             |
+| ------------ | --------------- | -------- | ----------------------------------------------------------------------- |
+| `animations` | `Animation[]`   | required | The Web Animations of the transition, one per moving layer.             |
+| `duration`   | `number`        | required | Their shared duration (ms).                                             |
+| `finished`   | `Promise<void>` | required | Resolves when every animation finished or was cancelled; never rejects. |
+
+## Used by
+
+- [createTransition](create-transition.md)
+- [mdTransition](md-transition.md)
+- [reducedTransition](reduced-transition.md)
+- [settlePop](settle-pop.md)

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

@@ -0,0 +1,23 @@
+# BfStackedOverlay
+
+What the overlay stack needs of an overlay: a way to close it
+
+Interface from `@bitforgehq/ui/overlay` · since 0.2.0
+
+Also exported from `@bitforgehq/ui/mobile` (deprecated: 0.3.0 use BfStackedOverlay from '@bitforgehq/ui/overlay'; removed in 0.4.0).
+
+What the stack needs of an overlay: a way to close it (a `BfOverlayRef` of any result type).
+
+```ts
+import { type BfStackedOverlay } from '@bitforgehq/ui/overlay';
+```
+
+## Methods
+
+### `close(): void`
+
+Closes the overlay (the stack calls it for the hardware back button).
+
+## Used by
+
+- [BfOverlayStack](bf-overlay-stack.md)

package/ai/reference/bf-system-bars-style.md

@@ -0,0 +1,38 @@
+# bfSystemBarsStyle
+
+The system-bar icon style that keeps the bars readable in the in-app theme
+
+Function from `@bitforgehq/ui/mobile` · since 0.3.0
+
+The SystemBars style for a theme: Dark = light icons. Android WebView < 140 pads the WebView, so
+the bar areas show the activity's window background (which follows the system theme): use
+Default there.
+
+The WebView ≥ 140 case assumes the shell's setup: `viewport-fit=cover` and Capacitor's default
+`SystemBars.insetsHandling: 'css'`, so the page draws under the bars. With `insetsHandling`
+`'disable'` or `'native'` the page never reaches under them and the bars show the window
+background as on older WebViews; pass `syncSystemBars: false` and style them yourself there.
+`webViewMajor` is read from `Chrome/<n>` in the user agent (Capacitor reads the WebView
+package, which normally agrees).
+
+```ts
+import { bfSystemBarsStyle } from '@bitforgehq/ui/mobile';
+```
+
+## Signature
+
+```ts
+function bfSystemBarsStyle(dark: boolean, platform: BfPlatform, webViewMajor: number | null): SystemBarsStyle
+```
+
+## Parameters
+
+| Parameter      | Type             | Description                                                                                   |
+| -------------- | ---------------- | --------------------------------------------------------------------------------------------- |
+| `dark`         | `boolean`        | Whether the app is dark now (`BfPlatformService.dark()`).                                     |
+| `platform`     | `BfPlatform`     | The platform the app runs on.                                                                 |
+| `webViewMajor` | `number \| null` | The Android WebView's major version (`Chrome/<n>` in the user agent), or `null` when unknown. |
+
+## Uses
+
+- [BfPlatform](bf-platform.md)

package/ai/reference/bf-tab-bar-controller.md

@@ -0,0 +1,51 @@
+# BfTabBarController
+
+The state a parent that drives a projected tab bar gives it to derive from
+
+Interface from `@bitforgehq/ui` · since 0.3.0
+
+Provided by a parent that projects the bar and drives it (bf-tabs); the bar derives its state from it.
+
+```ts
+import { type BfTabBarController } from '@bitforgehq/ui';
+```
+
+## Signature
+
+```ts
+interface BfTabBarController extends BfTabLinks
+```
+
+## Properties
+
+| Name             | Type                     | Default  | Description                                                                                             |
+| ---------------- | ------------------------ | -------- | ------------------------------------------------------------------------------------------------------- |
+| `current`        | `Signal<string \| null>` | required | The tab the parent shows: the in-flight navigation's target, else the current URL's; null when unknown. |
+| `hidden`         | `Signal<boolean>`        | required | Hide the bar (e.g. while the soft keyboard is open or about to open).                                   |
+| `hideTransition` | `Signal<boolean>`        | required | Animate hiding (iOS) or switch instantly.                                                               |
+
+## Methods
+
+### `select(id: string): void`
+
+Called by the bar on a user selection of another tab.
+
+| Parameter | Type     | Description                   |
+| --------- | -------- | ----------------------------- |
+| `id`      | `string` | The `id` of the selected tab. |
+
+### `reselect(id: string): void`
+
+Called by the bar on a user selection of the active tab.
+
+| Parameter | Type     | Description                 |
+| --------- | -------- | --------------------------- |
+| `id`      | `string` | The `id` of the active tab. |
+
+## Uses
+
+- [BfTabLinks](bf-tab-links.md)
+
+## Used by
+
+- [BF_TAB_BAR_CONTROLLER](bf_tab_bar_controller.md)