@bitforgehq/ui 0.3.0

package/ai/reference/max_complete_ms.md

@@ -0,0 +1,17 @@
+# MAX_COMPLETE_MS
+
+The longest a released swipe-back may take to settle, in milliseconds
+
+Constant from `@bitforgehq/ui/mobile` · since 0.2.0
+
+Upper bound of the settle animation after a released swipe.
+
+```ts
+import { MAX_COMPLETE_MS } from '@bitforgehq/ui/mobile';
+```
+
+## Signature
+
+```ts
+const MAX_COMPLETE_MS = 540
+```

package/ai/reference/md-transition.md

@@ -0,0 +1,31 @@
+# mdTransition
+
+Builds the Material fade-up page transition of a push or a pop
+
+Function from `@bitforgehq/ui/mobile` · since 0.2.0
+
+Material fade-up: the entering page fades in while rising 16 px; a pop is the reverse on the
+leaving page. No parallax, no dim.
+
+```ts
+import { mdTransition } from '@bitforgehq/ui/mobile';
+```
+
+## Signature
+
+```ts
+function mdTransition(kind: BfTransitionKind, entering: HTMLElement, leaving: HTMLElement): BfStackTransition
+```
+
+## Parameters
+
+| Parameter  | Type               | Description                    |
+| ---------- | ------------------ | ------------------------------ |
+| `kind`     | `BfTransitionKind` | `push` or `pop`.               |
+| `entering` | `HTMLElement`      | The page that becomes visible. |
+| `leaving`  | `HTMLElement`      | The page that goes away.       |
+
+## Uses
+
+- [BfStackTransition](bf-stack-transition.md)
+- [BfTransitionKind](bf-transition-kind.md)

package/ai/reference/md_duration.md

@@ -0,0 +1,17 @@
+# MD_DURATION
+
+The duration of the Material fade-up stack transition, in milliseconds
+
+Constant from `@bitforgehq/ui/mobile` · since 0.2.0
+
+Material fade-up.
+
+```ts
+import { MD_DURATION } from '@bitforgehq/ui/mobile';
+```
+
+## Signature
+
+```ts
+const MD_DURATION: 220
+```

package/ai/reference/md_easing.md

@@ -0,0 +1,17 @@
+# MD_EASING
+
+The Material standard easing curve of the Android page fade-up transition
+
+Constant from `@bitforgehq/ui/mobile` · since 0.2.0
+
+Material standard easing (the Android fade-up).
+
+```ts
+import { MD_EASING } from '@bitforgehq/ui/mobile';
+```
+
+## Signature
+
+```ts
+const MD_EASING = 'cubic-bezier(0.2, 0, 0, 1)'
+```

package/ai/reference/overlay_duration.md

@@ -0,0 +1,21 @@
+# OVERLAY_DURATION
+
+The duration of every overlay enter and exit animation, in milliseconds
+
+Constant from `@bitforgehq/ui/overlay` · since 0.2.0
+
+Also exported from `@bitforgehq/ui/mobile` (deprecated: 0.3.0 use OVERLAY_DURATION from '@bitforgehq/ui/overlay'; removed in 0.4.0).
+
+Motion constants of the overlay core. `@bitforgehq/ui/mobile` reuses them for its own motion
+(`DURATION_OVERLAY`, `DURATION_FAST`, `IOS_EASING`).
+Overlay enter and exit (ms).
+
+```ts
+import { OVERLAY_DURATION } from '@bitforgehq/ui/overlay';
+```
+
+## Signature
+
+```ts
+const OVERLAY_DURATION = 260
+```

package/ai/reference/overlay_easing.md

@@ -0,0 +1,19 @@
+# OVERLAY_EASING
+
+The easing curve of the overlay animations, the UIKit sheet curve
+
+Constant from `@bitforgehq/ui/overlay` · since 0.2.0
+
+Also exported from `@bitforgehq/ui/mobile` (deprecated: 0.3.0 use OVERLAY_EASING from '@bitforgehq/ui/overlay'; removed in 0.4.0).
+
+The overlays' curve: UIKit's navigation and sheet curve.
+
+```ts
+import { OVERLAY_EASING } from '@bitforgehq/ui/overlay';
+```
+
+## Signature
+
+```ts
+const OVERLAY_EASING = 'cubic-bezier(0.32, 0.72, 0, 1)'
+```

package/ai/reference/overlay_reduced_duration.md

@@ -0,0 +1,17 @@
+# OVERLAY_REDUCED_DURATION
+
+The duration of the fade that replaces overlay motion under reduced motion
+
+Constant from `@bitforgehq/ui/overlay` · since 0.3.0
+
+The opacity fade that replaces every overlay animation under reduced motion (ms).
+
+```ts
+import { OVERLAY_REDUCED_DURATION } from '@bitforgehq/ui/overlay';
+```
+
+## Signature
+
+```ts
+const OVERLAY_REDUCED_DURATION = 150
+```

package/ai/reference/pop-frames-at.md

@@ -0,0 +1,25 @@
+# popFramesAt
+
+The positions of the pop layers at a given progress, for scrubbing a swipe
+
+Function from `@bitforgehq/ui/mobile` · since 0.2.0
+
+Frame values of the pop at progress `p` (0 = start, 1 = done), used to hand a scrubbed gesture
+over to a fresh eased animation on release.
+
+```ts
+import { popFramesAt } from '@bitforgehq/ui/mobile';
+```
+
+## Signature
+
+```ts
+function popFramesAt(p: number, width: number): { top: number; under: number; dim: number }
+```
+
+## Parameters
+
+| Parameter | Type     | Description                              |
+| --------- | -------- | ---------------------------------------- |
+| `p`       | `number` | The pop progress, 0 (start) to 1 (done). |
+| `width`   | `number` | The outlet width (px).                   |

package/ai/reference/prefers-reduced-motion.md

@@ -0,0 +1,25 @@
+# prefersReducedMotion
+
+Tells whether the user asked the system to minimise motion
+
+Function from `@bitforgehq/ui/overlay` · since 0.2.0
+
+Also exported from `@bitforgehq/ui/mobile`.
+
+True when the user asked the system to minimise motion.
+
+```ts
+import { prefersReducedMotion } from '@bitforgehq/ui/overlay';
+```
+
+## Signature
+
+```ts
+function prefersReducedMotion(view: Window | null | undefined): boolean
+```
+
+## Parameters
+
+| Parameter | Type                          | Description                                                             |
+| --------- | ----------------------------- | ----------------------------------------------------------------------- |
+| `view`    | `Window \| null \| undefined` | The window to ask, usually `document.defaultView`; none reads as false. |

package/ai/reference/provide-bf-defaults.md

@@ -0,0 +1,33 @@
+# provideBfDefaults
+
+Sets the default field and control sizes for an app or a sub-tree
+
+Function from `@bitforgehq/ui` · since 0.3.0
+
+App-wide (ApplicationConfig) or sub-tree (a component's `providers`) widget defaults, merged
+over the nearest parent's. Capacitor apps: `provideBfDefaults({ fieldSize: 'lg' })` keeps the
+0.2 phone look; `{ size: 'lg' }` enlarges every control.
+
+```ts
+import { provideBfDefaults } from '@bitforgehq/ui';
+```
+
+## Signature
+
+```ts
+function provideBfDefaults(options: BfDefaultsOptions): Provider
+```
+
+## Parameters
+
+| Parameter | Type                | Description                                             |
+| --------- | ------------------- | ------------------------------------------------------- |
+| `options` | `BfDefaultsOptions` | The steps to set; any step left out keeps the parent's. |
+
+## Uses
+
+- [BfDefaultsOptions](bf-defaults-options.md)
+
+## Used by
+
+- [BfTestingOptions](bf-testing-options.md)

package/ai/reference/provide-bf-desktop-toast.md

@@ -0,0 +1,28 @@
+# provideBfDesktopToast
+
+Sets where desktop toasts appear and how many show at once, app-wide
+
+Function from `@bitforgehq/ui/overlay` · since 0.3.0
+
+Sets where the desktop toast stack sits, how many toasts it shows at once and its region name,
+merged over the defaults. Add it to `ApplicationConfig.providers`.
+
+```ts
+import { provideBfDesktopToast } from '@bitforgehq/ui/overlay';
+```
+
+## Signature
+
+```ts
+function provideBfDesktopToast(config?: Partial<BfDesktopToastConfig>): EnvironmentProviders
+```
+
+## Parameters
+
+| Parameter | Type                            | Description                                                            |
+| --------- | ------------------------------- | ---------------------------------------------------------------------- |
+| `config?` | `Partial<BfDesktopToastConfig>` | The settings to change; any left out keep `BF_DESKTOP_TOAST_DEFAULTS`. |
+
+## Uses
+
+- [BfDesktopToastConfig](bf-desktop-toast-config.md)

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

@@ -0,0 +1,38 @@
+# provideBfLabels
+
+Replaces built-in strings for an app or a sub-tree, such as a translation
+
+Function from `@bitforgehq/ui` · since 0.3.0
+
+Replaces built-in strings, merged over the parent's (validation merged key by key); a key left
+out or set to `undefined` keeps the parent's string. In `ApplicationConfig.providers` it covers
+every string. In a component's `providers` it covers that sub-tree's widgets and form controls
+(`loading`, `dismiss`, `tabBar`, `tabBadge`, `back`, `refreshing`, `validation`); the overlay
+services (`ok`, `cancel`, `actions`, `sheet`, `modal`, `close`, `expand`, `collapse`,
+`sheetPosition`, `dialog`, `notifications`) are
+root singletons and pick it up only when the caller passes its injector:
+`open(…, { injector: inject(Injector) })`.
+
+```ts
+import { provideBfLabels } from '@bitforgehq/ui';
+```
+
+## Signature
+
+```ts
+function provideBfLabels(overrides: BfLabelsOverrides): Provider
+```
+
+## Parameters
+
+| Parameter   | Type                | Description                                                  |
+| ----------- | ------------------- | ------------------------------------------------------------ |
+| `overrides` | `BfLabelsOverrides` | The strings to replace; any key left out keeps the parent's. |
+
+## Uses
+
+- [BfLabelsOverrides](bf-labels-overrides.md)
+
+## Used by
+
+- [BfTestingOptions](bf-testing-options.md)

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

@@ -0,0 +1,34 @@
+# provideBfShellTesting
+
+Test providers for the mobile shell: router, shell, in-memory theme and cleanup
+
+Function from `@bitforgehq/ui/mobile` · since 0.3.0
+
+Test providers for an app on the mobile shell: `provideRouter(routes ?? [],
+withComponentInputBinding(), withBfShellRouting())` plus `provideBfShell({ swipeBack: false,
+hapticsOnTabChange: false, ...config })`, an in-memory `BF_THEME_STORAGE` (so a theme change
+never reaches `localStorage`), and the same document cleanup as `provideBfTesting()` from
+`@bitforgehq/ui/testing` on teardown (`dark` and `cdk-global-scrollblock` on `<html>`, `inert` on
+body children, stray overlay panes). Like that cleanup, it needs TestBed's default
+`teardown: { destroyAfterEach: true }`. Use it instead of the app's own shell providers in
+`TestBed.configureTestingModule()`.
+
+```ts
+import { provideBfShellTesting } from '@bitforgehq/ui/mobile';
+```
+
+## Signature
+
+```ts
+function provideBfShellTesting(options?: BfShellTestingOptions): EnvironmentProviders
+```
+
+## Parameters
+
+| Parameter  | Type                    | Description                        |
+| ---------- | ----------------------- | ---------------------------------- |
+| `options?` | `BfShellTestingOptions` | The routes and the shell settings. |
+
+## Uses
+
+- [BfShellTestingOptions](bf-shell-testing-options.md)

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

@@ -0,0 +1,41 @@
+# provideBfShell
+
+Provides the Capacitor app shell: its configuration, navigation and platform services
+
+Function from `@bitforgehq/ui/mobile` · since 0.2.0
+
+Provides the mobile shell: its configuration, the stack-aware route reuse strategy
+(`BfStackReuseStrategy`) and `BF_OVERLAY_HOST` (the hardware back button closes the top overlay
+through `BfBackButtonService`, which on native Android also stands in for the overlays'
+`CloseWatcher`, and the document never scrolls, so overlays skip the scroll lock). An environment initializer starts `BfPlatformService` (theme sync, the `dark` class),
+`BfBackButtonService` (the Android hardware back listener), `BfKeyboardService` (keyboard
+listeners and the rest-height probe), `BfHapticsService` (its native plugin loads lazily on first
+use, so this only makes the singleton available) and `BfTextScaleService` (iOS Dynamic Type on
+the root font size) at bootstrap, before any page renders. Every service is
+`providedIn: 'root'`, so this function lists none of them: `BfNavController` and the overlay
+services (`BfOverlayStack`, `BfOverlayService`, `BfSheetService`, `BfModalService`,
+`BfToastService`, `BfActionSheetService`, `BfAlertDialogService`) are created on first
+injection, and an app that never injects an overlay service bundles no overlay code. Use it
+together with `provideRouter(routes, withComponentInputBinding(), withBfShellRouting())`, in the
+application providers: in a lazy route's environment injector the services still resolve from
+the root injector.
+
+```ts
+import { provideBfShell } from '@bitforgehq/ui/mobile';
+```
+
+## Signature
+
+```ts
+function provideBfShell(config?: Partial<BfShellConfig>): EnvironmentProviders
+```
+
+## Parameters
+
+| Parameter | Type                     | Description                                                    |
+| --------- | ------------------------ | -------------------------------------------------------------- |
+| `config?` | `Partial<BfShellConfig>` | The settings to change; any left out keep `BF_SHELL_DEFAULTS`. |
+
+## Uses
+
+- [BfShellConfig](bf-shell-config.md)

package/ai/reference/provide-bf-testing.md

@@ -0,0 +1,33 @@
+# provideBfTesting
+
+Test providers for the widgets and overlays, with document cleanup after each test
+
+Function from `@bitforgehq/ui/testing` · since 0.3.0
+
+Test providers for apps using the root and overlay entries: passes `defaults`/`labels` to 3b's
+providers, and on environment teardown removes what overlays and themes leave on the document —
+`dark` and `cdk-global-scrollblock` on `<html>`, `inert` on body children, stray
+`.cdk-overlay-container` children. The cleanup runs when TestBed destroys the test environment,
+so it needs TestBed's default `teardown: { destroyAfterEach: true }`; with `destroyAfterEach:
+false` nothing is cleaned between tests. Mobile shell apps use `provideBfShellTesting()` from
+`@bitforgehq/ui/mobile` instead.
+
+```ts
+import { provideBfTesting } from '@bitforgehq/ui/testing';
+```
+
+## Signature
+
+```ts
+function provideBfTesting(options?: BfTestingOptions): EnvironmentProviders
+```
+
+## Parameters
+
+| Parameter  | Type               | Description                              |
+| ---------- | ------------------ | ---------------------------------------- |
+| `options?` | `BfTestingOptions` | The size defaults and labels to provide. |
+
+## Uses
+
+- [BfTestingOptions](bf-testing-options.md)

package/ai/reference/reduced-transition.md

@@ -0,0 +1,28 @@
+# reducedTransition
+
+Builds the cross-fade that replaces page motion when the user reduces motion
+
+Function from `@bitforgehq/ui/mobile` · since 0.2.0
+
+Reduced motion: a 150 ms cross-fade of the two pages, nothing moves.
+
+```ts
+import { reducedTransition } from '@bitforgehq/ui/mobile';
+```
+
+## Signature
+
+```ts
+function reducedTransition(entering: HTMLElement, leaving: HTMLElement): BfStackTransition
+```
+
+## Parameters
+
+| Parameter  | Type          | Description                    |
+| ---------- | ------------- | ------------------------------ |
+| `entering` | `HTMLElement` | The page that becomes visible. |
+| `leaving`  | `HTMLElement` | The page that goes away.       |
+
+## Uses
+
+- [BfStackTransition](bf-stack-transition.md)

package/ai/reference/reduced_duration.md

@@ -0,0 +1,17 @@
+# REDUCED_DURATION
+
+The duration of the cross-fade that replaces page motion under reduced motion
+
+Constant from `@bitforgehq/ui/mobile` · since 0.2.0
+
+Cross-fade used under `prefers-reduced-motion`.
+
+```ts
+import { REDUCED_DURATION } from '@bitforgehq/ui/mobile';
+```
+
+## Signature
+
+```ts
+const REDUCED_DURATION: 150
+```

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

@@ -0,0 +1,33 @@
+# resolveShellMode
+
+Resolves the shell mode in effect from the configuration and the platform
+
+Function from `@bitforgehq/ui/mobile` · since 0.2.0
+
+The shell mode in effect: `config.mode`, or the platform's (`BfPlatformService.mode()`: iOS on
+iOS, else Material) when it is `'auto'`. The one resolution every mode-dependent part of the
+shell (stack outlet, modal, header, back button) shares; apps use it (or `injectShellMode()`)
+to follow the same per-mode conventions, e.g. text vs icon header actions.
+
+```ts
+import { resolveShellMode } from '@bitforgehq/ui/mobile';
+```
+
+## Signature
+
+```ts
+function resolveShellMode(config: Readonly<BfShellConfig>, platform: BfPlatformService): BfShellMode
+```
+
+## Parameters
+
+| Parameter  | Type                      | Description                                                 |
+| ---------- | ------------------------- | ----------------------------------------------------------- |
+| `config`   | `Readonly<BfShellConfig>` | The shell configuration, usually `inject(BF_SHELL_CONFIG)`. |
+| `platform` | `BfPlatformService`       | The platform service.                                       |
+
+## Uses
+
+- [BfPlatformService](bf-platform-service.md)
+- [BfShellConfig](bf-shell-config.md)
+- [BfShellMode](bf-shell-mode.md)

package/ai/reference/scale-in.md

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

package/ai/reference/settle-duration.md

@@ -0,0 +1,25 @@
+# settleDuration
+
+The duration of the settle animation after a released swipe-back gesture
+
+Function from `@bitforgehq/ui/mobile` · since 0.2.0
+
+Duration of the settle animation after a release: the remaining distance at the release speed
+(at least 0.5 px/ms), clamped to 120 ms … `MAX_COMPLETE_MS`.
+
+```ts
+import { settleDuration } from '@bitforgehq/ui/mobile';
+```
+
+## Signature
+
+```ts
+function settleDuration(remainingPx: number, velocity: number): number
+```
+
+## Parameters
+
+| Parameter     | Type     | Description                       |
+| ------------- | -------- | --------------------------------- |
+| `remainingPx` | `number` | The distance left to travel (px). |
+| `velocity`    | `number` | The release speed (px/ms).        |

package/ai/reference/settle-pop.md

@@ -0,0 +1,33 @@
+# settlePop
+
+Animates a released swipe-back from its progress to done or back to the start
+
+Function from `@bitforgehq/ui/mobile` · since 0.2.0
+
+Animates top, under and dim from pop progress `from` to `to` with an ease-out.
+
+```ts
+import { settlePop } from '@bitforgehq/ui/mobile';
+```
+
+## Signature
+
+```ts
+function settlePop(top: HTMLElement, under: HTMLElement, dim: HTMLElement, width: number, from: number, to: number, duration: number): BfStackTransition
+```
+
+## Parameters
+
+| Parameter  | Type          | Description                                                   |
+| ---------- | ------------- | ------------------------------------------------------------- |
+| `top`      | `HTMLElement` | The page being popped.                                        |
+| `under`    | `HTMLElement` | The page under it.                                            |
+| `dim`      | `HTMLElement` | The dimming layer.                                            |
+| `width`    | `number`      | The outlet width (px).                                        |
+| `from`     | `number`      | The progress at release, 0 to 1.                              |
+| `to`       | `number`      | The progress to settle at: 1 completes the pop, 0 cancels it. |
+| `duration` | `number`      | The settle duration (ms), see `settleDuration`.               |
+
+## Uses
+
+- [BfStackTransition](bf-stack-transition.md)

package/ai/reference/settle_easing.md

@@ -0,0 +1,17 @@
+# SETTLE_EASING
+
+The ease-out curve a released swipe-back or refresher gesture settles with
+
+Constant from `@bitforgehq/ui/mobile` · since 0.2.0
+
+Ease-out of a released gesture settling into place (swipe-back, refresher).
+
+```ts
+import { SETTLE_EASING } from '@bitforgehq/ui/mobile';
+```
+
+## Signature
+
+```ts
+const SETTLE_EASING = 'cubic-bezier(0.2, 0.8, 0.3, 1)'
+```

package/ai/reference/should-complete-pop.md

@@ -0,0 +1,26 @@
+# shouldCompletePop
+
+Decides whether a released swipe-back completes the pop or settles back
+
+Function from `@bitforgehq/ui/mobile` · since 0.2.0
+
+The release rule of the swipe-back: a flick (`velocity` above 0.2 px/ms) or a drag past half
+the width completes the pop; anything else settles back.
+
+```ts
+import { shouldCompletePop } from '@bitforgehq/ui/mobile';
+```
+
+## Signature
+
+```ts
+function shouldCompletePop(velocity: number, delta: number, width: number): boolean
+```
+
+## Parameters
+
+| Parameter  | Type     | Description                                               |
+| ---------- | -------- | --------------------------------------------------------- |
+| `velocity` | `number` | The release speed (px/ms, positive towards the end edge). |
+| `delta`    | `number` | The distance swiped (px).                                 |
+| `width`    | `number` | The outlet width (px).                                    |

package/ai/reference/slide-down.md

@@ -0,0 +1,26 @@
+# slideDown
+
+Slides an element down out of place, the exit animation of a bottom sheet
+
+Function from `@bitforgehq/ui/overlay` · since 0.2.0
+
+Also exported from `@bitforgehq/ui/mobile` (deprecated: 0.3.0 use slideDown from '@bitforgehq/ui/overlay'; removed in 0.4.0).
+
+Slides `el` down out of place by `distance` (default: its own height).
+
+```ts
+import { slideDown } from '@bitforgehq/ui/overlay';
+```
+
+## Signature
+
+```ts
+function slideDown(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.  |