@bitforgehq/ui 0.3.0

package/ai/reference/bf_default_labels.md

@@ -0,0 +1,21 @@
+# BF_DEFAULT_LABELS
+
+The library's built-in English strings, the labels every widget starts from
+
+Constant from `@bitforgehq/ui` · since 0.3.0
+
+The library's built-in English strings.
+
+```ts
+import { BF_DEFAULT_LABELS } from '@bitforgehq/ui';
+```
+
+## Signature
+
+```ts
+const BF_DEFAULT_LABELS: BfLabels
+```
+
+## Uses
+
+- [BfLabels](bf-labels.md)

package/ai/reference/bf_default_values.md

@@ -0,0 +1,21 @@
+# BF_DEFAULT_VALUES
+
+The library's built-in widget defaults, the compact md step everywhere
+
+Constant from `@bitforgehq/ui` · since 0.3.0
+
+Library defaults: compact `md` everywhere (desktop first).
+
+```ts
+import { BF_DEFAULT_VALUES } from '@bitforgehq/ui';
+```
+
+## Signature
+
+```ts
+const BF_DEFAULT_VALUES: BfDefaults
+```
+
+## Uses
+
+- [BfDefaults](bf-defaults.md)

package/ai/reference/bf_defaults.md

@@ -0,0 +1,21 @@
+# BF_DEFAULTS
+
+Injection token holding the widget defaults in effect for an injector
+
+Injection token from `@bitforgehq/ui` · since 0.3.0
+
+The widget defaults in effect for the current injector; set them with `provideBfDefaults()`.
+
+```ts
+import { BF_DEFAULTS } from '@bitforgehq/ui';
+```
+
+## Signature
+
+```ts
+const BF_DEFAULTS: InjectionToken<BfDefaults>
+```
+
+## Uses
+
+- [BfDefaults](bf-defaults.md)

package/ai/reference/bf_desktop_toast_defaults.md

@@ -0,0 +1,21 @@
+# BF_DESKTOP_TOAST_DEFAULTS
+
+The library defaults of the desktop toast settings, bottom end with three visible
+
+Constant from `@bitforgehq/ui/overlay` · since 0.3.0
+
+The library defaults of `BfDesktopToastConfig`.
+
+```ts
+import { BF_DESKTOP_TOAST_DEFAULTS } from '@bitforgehq/ui/overlay';
+```
+
+## Signature
+
+```ts
+const BF_DESKTOP_TOAST_DEFAULTS: Readonly<BfDesktopToastConfig>
+```
+
+## Uses
+
+- [BfDesktopToastConfig](bf-desktop-toast-config.md)

package/ai/reference/bf_dialog_data.md

@@ -0,0 +1,17 @@
+# BF_DIALOG_DATA
+
+Injection token carrying the data a dialog was opened with, for its content
+
+Injection token from `@bitforgehq/ui/overlay` · since 0.3.0
+
+The `data` passed to `BfDialogService.open()`, injectable in the dialog's content.
+
+```ts
+import { BF_DIALOG_DATA } from '@bitforgehq/ui/overlay';
+```
+
+## Signature
+
+```ts
+const BF_DIALOG_DATA: InjectionToken<unknown>
+```

package/ai/reference/bf_labels.md

@@ -0,0 +1,21 @@
+# BF_LABELS
+
+Injection token holding the user-facing strings in effect for an injector
+
+Injection token from `@bitforgehq/ui` · since 0.3.0
+
+The strings in effect for the current injector; set them with `provideBfLabels()`.
+
+```ts
+import { BF_LABELS } from '@bitforgehq/ui';
+```
+
+## Signature
+
+```ts
+const BF_LABELS: InjectionToken<BfLabels>
+```
+
+## Uses
+
+- [BfLabels](bf-labels.md)

package/ai/reference/bf_overlay_data.md

@@ -0,0 +1,19 @@
+# BF_OVERLAY_DATA
+
+Injection token carrying the data an overlay was opened with, for its content
+
+Injection token from `@bitforgehq/ui/overlay` · since 0.2.0
+
+Also exported from `@bitforgehq/ui/mobile` (deprecated: 0.3.0 use BF_OVERLAY_DATA from '@bitforgehq/ui/overlay'; removed in 0.4.0).
+
+The `data` passed to `BfOverlayService.open()`, injectable in the overlay's content.
+
+```ts
+import { BF_OVERLAY_DATA } from '@bitforgehq/ui/overlay';
+```
+
+## Signature
+
+```ts
+const BF_OVERLAY_DATA: InjectionToken<unknown>
+```

package/ai/reference/bf_overlay_host.md

@@ -0,0 +1,21 @@
+# BF_OVERLAY_HOST
+
+Optional injection token through which a host shell plugs into the overlay core
+
+Injection token from `@bitforgehq/ui/overlay` · since 0.3.0
+
+Optional; without it overlays register no back handler and lock document scroll.
+
+```ts
+import { BF_OVERLAY_HOST } from '@bitforgehq/ui/overlay';
+```
+
+## Signature
+
+```ts
+const BF_OVERLAY_HOST: InjectionToken<BfOverlayHost>
+```
+
+## Uses
+
+- [BfOverlayHost](bf-overlay-host.md)

package/ai/reference/bf_sheet_default_snap_points.md

@@ -0,0 +1,17 @@
+# BF_SHEET_DEFAULT_SNAP_POINTS
+
+The snap points a bottom sheet rests at when none are given, half and full
+
+Constant from `@bitforgehq/ui/mobile` · since 0.2.0
+
+Snap points used when none (or no valid ones) are given.
+
+```ts
+import { BF_SHEET_DEFAULT_SNAP_POINTS } from '@bitforgehq/ui/mobile';
+```
+
+## Signature
+
+```ts
+const BF_SHEET_DEFAULT_SNAP_POINTS: readonly number[]
+```

package/ai/reference/bf_shell_config.md

@@ -0,0 +1,21 @@
+# BF_SHELL_CONFIG
+
+Injection token holding the resolved mobile shell configuration of the app
+
+Injection token from `@bitforgehq/ui/mobile` · since 0.2.0
+
+The resolved shell configuration.
+
+```ts
+import { BF_SHELL_CONFIG } from '@bitforgehq/ui/mobile';
+```
+
+## Signature
+
+```ts
+const BF_SHELL_CONFIG: InjectionToken<BfShellConfig>
+```
+
+## Uses
+
+- [BfShellConfig](bf-shell-config.md)

package/ai/reference/bf_shell_defaults.md

@@ -0,0 +1,21 @@
+# BF_SHELL_DEFAULTS
+
+The mobile shell defaults that provideBfShell merges the app settings over
+
+Constant from `@bitforgehq/ui/mobile` · since 0.2.0
+
+The shell defaults, merged under the overrides given to `provideBfShell()`.
+
+```ts
+import { BF_SHELL_DEFAULTS } from '@bitforgehq/ui/mobile';
+```
+
+## Signature
+
+```ts
+const BF_SHELL_DEFAULTS: Readonly<BfShellConfig>
+```
+
+## Uses
+
+- [BfShellConfig](bf-shell-config.md)

package/ai/reference/bf_tab_bar.md

@@ -0,0 +1,21 @@
+# BF_TAB_BAR
+
+Injection token through which each tab reaches its enclosing tab bar
+
+Injection token from `@bitforgehq/ui` · since 0.1.0
+
+The enclosing `bf-tab-bar`, as its tabs inject it.
+
+```ts
+import { BF_TAB_BAR } from '@bitforgehq/ui';
+```
+
+## Signature
+
+```ts
+const BF_TAB_BAR: InjectionToken<BfTabBarHost>
+```
+
+## Uses
+
+- [BfTabBarHost](bf-tab-bar-host.md)

package/ai/reference/bf_tab_bar_controller.md

@@ -0,0 +1,21 @@
+# BF_TAB_BAR_CONTROLLER
+
+Injection token through which a parent drives the selection and hiding of its tab bar
+
+Injection token from `@bitforgehq/ui` · since 0.3.0
+
+The controller of a tab bar projected into a parent that drives it, provided by `bf-tabs`.
+
+```ts
+import { BF_TAB_BAR_CONTROLLER } from '@bitforgehq/ui';
+```
+
+## Signature
+
+```ts
+const BF_TAB_BAR_CONTROLLER: InjectionToken<BfTabBarController>
+```
+
+## Uses
+
+- [BfTabBarController](bf-tab-bar-controller.md)

package/ai/reference/bf_tab_context.md

@@ -0,0 +1,21 @@
+# BF_TAB_CONTEXT
+
+Injection token through which the tabs page tells its outlet about the tabs
+
+Injection token from `@bitforgehq/ui/mobile` · since 0.2.0
+
+Provided by `bf-tabs`; injected optionally by `bf-stack-outlet`.
+
+```ts
+import { BF_TAB_CONTEXT } from '@bitforgehq/ui/mobile';
+```
+
+## Signature
+
+```ts
+const BF_TAB_CONTEXT: InjectionToken<BfTabContext>
+```
+
+## Uses
+
+- [BfTabContext](bf-tab-context.md)

package/ai/reference/bf_tab_links.md

@@ -0,0 +1,21 @@
+# BF_TAB_LINKS
+
+Injection token that turns a projected tab bar into a navigation of links
+
+Injection token from `@bitforgehq/ui` · since 0.3.0
+
+The link source of a tab bar in link mode, provided by `bf-tabs`.
+
+```ts
+import { BF_TAB_LINKS } from '@bitforgehq/ui';
+```
+
+## Signature
+
+```ts
+const BF_TAB_LINKS: InjectionToken<BfTabLinks>
+```
+
+## Uses
+
+- [BfTabLinks](bf-tab-links.md)

package/ai/reference/bf_theme_storage.md

@@ -0,0 +1,19 @@
+# BF_THEME_STORAGE
+
+Injection token for the store that keeps the app theme choice between visits
+
+Injection token from `@bitforgehq/ui/mobile` · since 0.3.0
+
+Where `BfPlatformService` keeps the theme choice (the key `bf-theme`): `localStorage` when it is
+available, otherwise an in-memory map. Provide another store (a native preferences plugin, or an
+in-memory one in tests, as `provideBfShellTesting()` does) to keep the choice elsewhere.
+
+```ts
+import { BF_THEME_STORAGE } from '@bitforgehq/ui/mobile';
+```
+
+## Signature
+
+```ts
+const BF_THEME_STORAGE: InjectionToken<Pick<Storage, "getItem" | "setItem">>
+```

package/ai/reference/create-transition.md

@@ -0,0 +1,36 @@
+# createTransition
+
+Builds the iOS push or pop with its slide, parallax and dimming layers
+
+Function from `@bitforgehq/ui/mobile` · since 0.2.0
+
+The iOS push or pop. `pop` is written as the literal reverse of a push but as forward
+keyframes, so `currentTime` maps directly to swipe progress (0 = nothing moved, duration = pop
+complete). Returns three animations: the top page (slide and edge shadow), the page under it
+(parallax) and the dim layer.
+
+```ts
+import { createTransition } from '@bitforgehq/ui/mobile';
+```
+
+## Signature
+
+```ts
+function createTransition(kind: BfTransitionKind, entering: HTMLElement, leaving: HTMLElement, dim: HTMLElement, width: number, easing?: string): BfStackTransition
+```
+
+## Parameters
+
+| Parameter  | Type               | Description                                        |
+| ---------- | ------------------ | -------------------------------------------------- |
+| `kind`     | `BfTransitionKind` | `push` or `pop`.                                   |
+| `entering` | `HTMLElement`      | The page that becomes visible.                     |
+| `leaving`  | `HTMLElement`      | The page that goes away.                           |
+| `dim`      | `HTMLElement`      | The dimming layer between the two pages.           |
+| `width`    | `number`           | The width the pages travel (the outlet width, px). |
+| `easing?`  | `string`           | The curve of the transition.                       |
+
+## Uses
+
+- [BfStackTransition](bf-stack-transition.md)
+- [BfTransitionKind](bf-transition-kind.md)

package/ai/reference/duration_fast.md

@@ -0,0 +1,17 @@
+# DURATION_FAST
+
+The duration of colour transitions and the reduced-motion fade, in milliseconds
+
+Constant from `@bitforgehq/ui/mobile` · since 0.2.0
+
+Colour transitions and the reduced-motion cross-fade (ms); the overlay core's reduced fade.
+
+```ts
+import { DURATION_FAST } from '@bitforgehq/ui/mobile';
+```
+
+## Signature
+
+```ts
+const DURATION_FAST: 150
+```

package/ai/reference/duration_md.md

@@ -0,0 +1,17 @@
+# DURATION_MD
+
+The duration of the Material fade-up and the refresher settle, in milliseconds
+
+Constant from `@bitforgehq/ui/mobile` · since 0.2.0
+
+Material fade-up and the refresher settle (ms).
+
+```ts
+import { DURATION_MD } from '@bitforgehq/ui/mobile';
+```
+
+## Signature
+
+```ts
+const DURATION_MD = 220
+```

package/ai/reference/duration_overlay.md

@@ -0,0 +1,17 @@
+# DURATION_OVERLAY
+
+The duration of overlay enter and exit and the modal depth effect, in milliseconds
+
+Constant from `@bitforgehq/ui/mobile` · since 0.2.0
+
+Overlay enter/exit and the modal depth effect (ms); the overlay core's duration.
+
+```ts
+import { DURATION_OVERLAY } from '@bitforgehq/ui/mobile';
+```
+
+## Signature
+
+```ts
+const DURATION_OVERLAY: 260
+```

package/ai/reference/duration_push.md

@@ -0,0 +1,17 @@
+# DURATION_PUSH
+
+The duration of the iOS push and pop page transitions, in milliseconds
+
+Constant from `@bitforgehq/ui/mobile` · since 0.2.0
+
+iOS push/pop (ms).
+
+```ts
+import { DURATION_PUSH } from '@bitforgehq/ui/mobile';
+```
+
+## Signature
+
+```ts
+const DURATION_PUSH = 500
+```

package/ai/reference/fade-down.md

@@ -0,0 +1,26 @@
+# fadeDown
+
+Fades an element out while it sinks, the reverse of the fadeUp animation
+
+Function from `@bitforgehq/ui/overlay` · since 0.2.0
+
+Also exported from `@bitforgehq/ui/mobile` (deprecated: 0.3.0 use fadeDown from '@bitforgehq/ui/overlay'; removed in 0.4.0).
+
+Fades `el` out while it sinks by `distance` (default 16 px; the reverse of `fadeUp`).
+
+```ts
+import { fadeDown } from '@bitforgehq/ui/overlay';
+```
+
+## Signature
+
+```ts
+function fadeDown(el: HTMLElement, distance?: string): Animation
+```
+
+## Parameters
+
+| Parameter   | Type          | Description                                        |
+| ----------- | ------------- | -------------------------------------------------- |
+| `el`        | `HTMLElement` | The element to animate, usually the overlay panel. |
+| `distance?` | `string`      | How far below its place it ends, as a CSS length.  |

package/ai/reference/fade-in.md

@@ -0,0 +1,25 @@
+# fadeIn
+
+Fades an element in, the default enter animation of an overlay
+
+Function from `@bitforgehq/ui/overlay` · since 0.2.0
+
+Also exported from `@bitforgehq/ui/mobile` (deprecated: 0.3.0 use fadeIn from '@bitforgehq/ui/overlay'; removed in 0.4.0).
+
+Fades `el` in.
+
+```ts
+import { fadeIn } from '@bitforgehq/ui/overlay';
+```
+
+## Signature
+
+```ts
+function fadeIn(el: HTMLElement): Animation
+```
+
+## Parameters
+
+| Parameter | Type          | Description                                        |
+| --------- | ------------- | -------------------------------------------------- |
+| `el`      | `HTMLElement` | The element to animate, usually the overlay panel. |

package/ai/reference/fade-out.md

@@ -0,0 +1,25 @@
+# fadeOut
+
+Fades an element out, the default exit animation of an overlay
+
+Function from `@bitforgehq/ui/overlay` · since 0.2.0
+
+Also exported from `@bitforgehq/ui/mobile` (deprecated: 0.3.0 use fadeOut from '@bitforgehq/ui/overlay'; removed in 0.4.0).
+
+Fades `el` out.
+
+```ts
+import { fadeOut } from '@bitforgehq/ui/overlay';
+```
+
+## Signature
+
+```ts
+function fadeOut(el: HTMLElement): Animation
+```
+
+## Parameters
+
+| Parameter | Type          | Description                                        |
+| --------- | ------------- | -------------------------------------------------- |
+| `el`      | `HTMLElement` | The element to animate, usually the overlay panel. |

package/ai/reference/fade-up.md

@@ -0,0 +1,26 @@
+# fadeUp
+
+Fades an element in while it rises, the Material modal enter animation
+
+Function from `@bitforgehq/ui/overlay` · since 0.2.0
+
+Also exported from `@bitforgehq/ui/mobile` (deprecated: 0.3.0 use fadeUp from '@bitforgehq/ui/overlay'; removed in 0.4.0).
+
+Fades `el` in while it rises by `distance` (default 16 px; the Material modal enter).
+
+```ts
+import { fadeUp } from '@bitforgehq/ui/overlay';
+```
+
+## Signature
+
+```ts
+function fadeUp(el: HTMLElement, distance?: string): Animation
+```
+
+## Parameters
+
+| Parameter   | Type          | Description                                         |
+| ----------- | ------------- | --------------------------------------------------- |
+| `el`        | `HTMLElement` | The element to animate, usually the overlay panel.  |
+| `distance?` | `string`      | How far below its place it starts, as a CSS length. |

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

@@ -0,0 +1,23 @@
+# injectShellMode
+
+Reads the shell mode in effect from the injector, iOS or Material
+
+Function from `@bitforgehq/ui/mobile` · since 0.2.0
+
+`resolveShellMode()` from the injector: `BF_SHELL_CONFIG` (the defaults, i.e. `'auto'`, without
+`provideBfShell()`) and `BfPlatformService`. Call it in an injection context (a field
+initializer or constructor); the mode is fixed for the app's lifetime.
+
+```ts
+import { injectShellMode } from '@bitforgehq/ui/mobile';
+```
+
+## Signature
+
+```ts
+function injectShellMode(): BfShellMode
+```
+
+## Uses
+
+- [BfShellMode](bf-shell-mode.md)

package/ai/reference/install-bf-jsdom-shims.md

@@ -0,0 +1,31 @@
+# installBfJsdomShims
+
+Installs the browser APIs jsdom lacks and the library needs, only where missing
+
+Function from `@bitforgehq/ui/testing` · since 0.3.0
+
+Installs, only where missing: `Element.prototype.animate` (an Animation whose `finished`
+resolves at once), `PointerEvent` (a MouseEvent subclass with pointerId, isPrimary, pointerType,
+width, height, pressure) and optionally `matchMedia`. Idempotent; returns a function that removes
+exactly what it installed. Call it once in the test runner's setup file (Vitest `setupFiles`,
+Jest `setupFilesAfterEnv`).
+
+```ts
+import { installBfJsdomShims } from '@bitforgehq/ui/testing';
+```
+
+## Signature
+
+```ts
+function installBfJsdomShims(options?: BfJsdomShimOptions): () => void
+```
+
+## Parameters
+
+| Parameter  | Type                 | Description                                                                |
+| ---------- | -------------------- | -------------------------------------------------------------------------- |
+| `options?` | `BfJsdomShimOptions` | Whether to stub `matchMedia`, and whether the stub reports reduced motion. |
+
+## Uses
+
+- [BfJsdomShimOptions](bf-jsdom-shim-options.md)

package/ai/reference/ios_duration.md

@@ -0,0 +1,17 @@
+# IOS_DURATION
+
+The duration of the iOS push and pop stack transitions, in milliseconds
+
+Constant from `@bitforgehq/ui/mobile` · since 0.2.0
+
+The iOS push and pop (ms), `DURATION_PUSH`.
+
+```ts
+import { IOS_DURATION } from '@bitforgehq/ui/mobile';
+```
+
+## Signature
+
+```ts
+const IOS_DURATION: 500
+```

package/ai/reference/ios_easing.md

@@ -0,0 +1,17 @@
+# IOS_EASING
+
+The UIKit navigation and sheet easing curve of pushes, pops and overlays
+
+Constant from `@bitforgehq/ui/mobile` · since 0.2.0
+
+UIKit's navigation and sheet curve (push/pop, overlays, modal depth); `OVERLAY_EASING` too.
+
+```ts
+import { IOS_EASING } from '@bitforgehq/ui/mobile';
+```
+
+## Signature
+
+```ts
+const IOS_EASING = 'cubic-bezier(0.32, 0.72, 0, 1)'
+```

package/ai/reference/is-text-entry.md

@@ -0,0 +1,25 @@
+# isTextEntry
+
+Tells whether focusing an element opens the soft keyboard on a phone
+
+Function from `@bitforgehq/ui/mobile` · since 0.2.0
+
+True for an element that opens the soft keyboard when focused: a text-like `input` (not a
+button, checkbox, color, file, hidden, image, radio, range, reset or submit), a `textarea`, or
+a `[contenteditable]` element other than `contenteditable="false"`.
+
+```ts
+import { isTextEntry } from '@bitforgehq/ui/mobile';
+```
+
+## Signature
+
+```ts
+function isTextEntry(element: Element | null): element is HTMLElement
+```
+
+## Parameters
+
+| Parameter | Type              | Description                                            |
+| --------- | ----------------- | ------------------------------------------------------ |
+| `element` | `Element \| null` | The element to test, usually `document.activeElement`. |