@bitforgehq/ui 0.3.0

package/ai/reference/bf-overscroll-stretch-directive.md

@@ -0,0 +1,163 @@
+# BfOverscrollStretchDirective
+
+Android-style stretch of a scroll container dragged past its top or bottom edge
+
+Directive from `@bitforgehq/ui/mobile` · since 0.2.0
+
+Android-style edge stretch for a scroll container: a vertical touch drag past the top or bottom
+edge scales the container's first element child (the content body) up along the y axis from
+that edge — `scaleY(1 + 0.14 × (1 − e^(−pull / 240)))` — and springs it back on release (220 ms,
+the settle curve; instant under `prefers-reduced-motion`). Touch only, with passive listeners:
+it never prevents a touch, so scrolling is untouched. It follows the finger that started the
+gesture and ignores any other. A horizontal-dominant gesture (decided after 8 px) is ignored,
+and the top edge is left alone while an active `bf-refresher` (`[data-bf-refresher]`) inside
+the container owns the top pull. `bf-content` applies it to its
+scroller in Material mode, where the WebView draws no overscroll effect of its own.
+
+```ts
+import { BfOverscrollStretchDirective } from '@bitforgehq/ui/mobile';
+```
+
+Selector: `[bfOverscrollStretch]`
+
+Android-style edge stretch for a scroll container. Android 12+ stretches a native list at the edge
+under the finger and springs it back, but an Android WebView draws no overscroll effect at all for
+an inner scroller. `bfOverscrollStretch` adds it: pull past the top or bottom edge and the
+container's first element child (the content body) stretches from that edge. `bf-content` applies
+it to its own scroller in Material mode, so most pages never use it directly; put it on a custom
+scroll container only when that container is not a `bf-content`.
+
+## When to use
+
+Use `bfOverscrollStretch` on a custom scroll container in an Android Capacitor app, for the native edge stretch. Use [bf-content](https://bitforge-ui.web.app/components/content) instead for a normal page, which applies it already in Material mode.
+
+## Basic usage
+
+```ts
+import { Component } from '@angular/core';
+import { BfListComponent, BfListItemComponent } from '@bitforgehq/ui';
+import { BfOverscrollStretchDirective } from '@bitforgehq/ui/mobile';
+
+/**
+ * A scroller whose body stretches at the ends.
+ *
+ * The directive moves the scroller's first child, so the content sits in one block body.
+ *
+ * @preview none
+ */
+@Component({
+  selector: 'app-example-overscroll-stretch-basic',
+  imports: [BfListComponent, BfListItemComponent, BfOverscrollStretchDirective],
+  template: `
+    <div class="h-full overflow-y-auto" bfOverscrollStretch>
+      <div>
+        <bf-list>
+          <bf-list-item title="Inbox" />
+          <bf-list-item title="Archive" />
+        </bf-list>
+      </div>
+    </div>
+  `,
+})
+export class OverscrollStretchBasicExampleComponent {}
+```
+
+The directive transforms the host's **first element child**, so wrap the content in one block
+element; the host itself never moves.
+
+## How it works
+
+- **Touch only.** It listens to `touchstart`, `touchmove`, `touchend` and `touchcancel` on the
+  host, all passive, and never prevents a touch: a pull at an edge scrolls nothing natively, so
+  there is nothing to cancel. Mouse and pen do nothing. It follows the finger that started the
+  gesture (by `Touch.identifier`) and ends when that finger lifts; a second finger is ignored.
+- **Axis.** Once the finger has moved 8 px from where it started, the gesture is vertical or
+  horizontal for good. A horizontal-dominant gesture (a horizontal scroller, a swipe) is ignored.
+- **Pull.** At the top (`scrollTop <= 0`) a downward move adds to the pull, stretching from the
+  top; at the bottom (`scrollTop >= scrollHeight − clientHeight − 1`) an upward move adds to it,
+  stretching from the bottom. Moving the finger back takes the pull down towards 0 (the list then
+  simply scrolls); away from both edges the pull is 0.
+- **Stretch.** The body gets `transform: scaleY(1 + 0.14 × (1 − e^(−pull / 240)))` with
+  `transform-origin: center top` or `center bottom`, and `will-change: transform` for the
+  gesture only. It approaches 1.14 and never passes it.
+- **Release.** It springs back to `scaleY(1)` with the Web Animations API (220 ms,
+  `cubic-bezier(0.2, 0.8, 0.3, 1)`), then clears `transform`, `transform-origin` and
+  `will-change`. A new touch during the spring-back resets it at once.
+- **Refresher.** While an enabled `bf-refresher` (`[data-bf-refresher]`) is inside the container,
+  the top pull belongs to it: only the bottom edge stretches.
+- **Engine, not shell mode.** `bf-content` turns the stretch on from the engine
+  (`BfPlatformService.mode()`, and off in iOS WebKit), not from `provideBfShell({ mode })`: WebKit
+  rubber-bands on its own, while Chrome never reports a negative `scrollTop` and draws nothing, so
+  an Android app forced into `mode: 'ios'` still stretches and an iOS app forced into `mode: 'md'`
+  never stacks the stretch on the bounce.
+
+## Turning it off
+
+`bfOverscrollStretch` takes a boolean (`true` when the attribute is bare); `false` leaves the
+directive inert. Bind it to the platform to stretch on Android only, where iOS already bounces
+natively. The input table is in the directive's API reference.
+
+```ts
+import { Component, inject } from '@angular/core';
+import { BfListComponent, BfListItemComponent } from '@bitforgehq/ui';
+import { BfOverscrollStretchDirective, BfPlatformService } from '@bitforgehq/ui/mobile';
+
+/**
+ * The stretch on Android only.
+ *
+ * `[bfOverscrollStretch]` takes a boolean; iOS already bounces natively.
+ *
+ * @preview none
+ */
+@Component({
+  selector: 'app-example-overscroll-stretch-conditional',
+  imports: [BfListComponent, BfListItemComponent, BfOverscrollStretchDirective],
+  template: `
+    <div class="h-full overflow-y-auto" [bfOverscrollStretch]="isAndroid">
+      <div>
+        <bf-list>
+          <bf-list-item title="Inbox" />
+        </bf-list>
+      </div>
+    </div>
+  `,
+})
+export class OverscrollStretchConditionalExampleComponent {
+  protected readonly isAndroid = inject(BfPlatformService).platform === 'android';
+}
+```
+
+## Desktop
+
+The stretch follows touch events only, so a mouse, a trackpad or the keyboard never starts it; on desktop the directive does nothing. Leave it out of desktop layouts.
+
+## Theming
+
+None — it writes only inline `transform`, `transform-origin` and `will-change` on the first
+element child during a gesture and its spring-back, and removes them afterwards. Do not rely on
+your own inline transform on that element.
+
+## Accessibility
+
+Pure feel, no behaviour: the stretch changes nothing that is read, focused or scrolled, and it
+never prevents a touch. Under `prefers-reduced-motion: reduce` the stretch still follows the
+finger (direct manipulation is not motion), but the spring-back is an instant reset.
+
+## Notes
+
+### Do
+
+- Rely on `bf-content`'s built-in stretch in Material mode; add the directive only to a custom
+  scroll container.
+- Wrap the scrollable content in a single block element, the one that stretches.
+
+### Don't
+
+- Don't use it in iOS mode, where WebKit's own rubber band already bounces the scroller.
+- Don't put it on an element that does not scroll vertically.
+
+## Inputs
+
+| Name                  | Type      | Default | Description                                            |
+| --------------------- | --------- | ------- | ------------------------------------------------------ |
+| `bfOverscrollStretch` | `boolean` | `true`  | Enables the stretch; false leaves the container inert. |

package/ai/reference/bf-page-context.md

@@ -0,0 +1,24 @@
+# BfPageContext
+
+Per-page state that the header and content of one page share
+
+Class from `@bitforgehq/ui/mobile` · since 0.2.0
+
+Per-page state shared between the parts of one `bf-page`. `bf-page` provides a fresh instance
+for each page through its element injector; `bf-content` registers its scroll container here
+on init (and clears it on destroy), so siblings such as `bf-header` can follow the page's
+scroll without querying the DOM. A plain class, like `BfViewLifecycle`: it is only ever
+provided per page, never from the root injector.
+
+```ts
+import { BfPageContext } from '@bitforgehq/ui/mobile';
+```
+
+## Properties
+
+| Name           | Type                                  | Default | Description                                                                                                                                                                                                                                                                                                                                                                                                                              |
+| -------------- | ------------------------------------- | ------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `scroller`     | `WritableSignal<HTMLElement \| null>` |         | The page's scroll container (`bf-content`'s scroller), or `null` before one registers.                                                                                                                                                                                                                                                                                                                                                   |
+| `headerHeight` | `WritableSignal<number>`              |         | Height (px) of a `translucent` `bf-header` drawn over the content, which `bf-content` pads its scroller by (`--bf-header-height`); 0 while the header sits in the page's flow (or none).                                                                                                                                                                                                                                                 |
+| `safeAreaTop`  | `WritableSignal<boolean>`             |         | Whether the page reaches the top of the screen, so its `bf-header` toolbar (and a `fullscreen` `bf-content`) pads by the top safe area. True for a page; `bf-modal` in the `sheet` presentation sets it to false, because its card already sits below the status bar.                                                                                                                                                                    |
+| `mainLandmark` | `WritableSignal<boolean>`             |         | Whether the page's `bf-content` scroller is the document's `main` landmark (`role="main"`). True for the page a `bf-stack-outlet` shows; `bf-modal` sets it to false (content in a dialog is not `main`), and so does a `bf-page` outside an outlet (a docs illustration) or nested in another page, so the document keeps exactly one `main`: parked pages are `inert` and `aria-hidden`, so only the shown page's landmark is exposed. |

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

@@ -0,0 +1,53 @@
+# BfPlatformService
+
+Platform facts and the app theme: native or web, iOS or Android, light or dark
+
+Service from `@bitforgehq/ui/mobile` · since 0.2.0
+
+Platform facts and the app theme: native or web, iOS or Android, the shell mode that follows
+from it, and the user's theme choice (system, light, dark) reflected as the `dark` class on
+`<html>`. `matchMedia('(prefers-color-scheme: dark)')` is the single source for the system
+theme on every platform.
+
+The `theme`/`dark` signals always compute, but the `<html>` class and storage writes
+only run when `provideBfShell()` provided `BF_SHELL_CONFIG` — i.e. this service is the app's
+own shell, not merely injected by something that wants `platform`/`mode`. Without it (e.g. a
+docs demo that instantiates `BfPlatformService` directly to preview `bf-tabs`), this service
+would otherwise fight the host page's own theme: its `effect` runs on construction and would
+immediately overwrite `<html class="dark">` with whatever `prefers-color-scheme` says.
+
+With `provideBfShell()` on a native platform it also makes the viewport meta forbid zoom
+(`maximum-scale=1, user-scalable=no`, other directives kept; the meta is created if missing):
+WKWebView zooms a focused control whose font is under 16 px and never zooms back, so the native
+shell forbids zoom — pinch, double tap and focus alike — and honours the system text size
+instead (iOS Dynamic Type through `BfTextScaleService`, Android's font scale in the WebView).
+On the web the meta is never touched, so a web build keeps pinch zoom (the owner's ruling,
+audit §12): ship `index.html` without `maximum-scale`/`user-scalable`.
+
+With `provideBfShell()` on native iOS and Android (unless `syncSystemBars: false`) the status-bar
+and navigation-bar icons follow `dark()`: `SystemBars.setStyle()` with `bfSystemBarsStyle()`,
+on start and on every theme change (Android WebView < 140 keeps `Default`, see there).
+
+```ts
+import { BfPlatformService } from '@bitforgehq/ui/mobile';
+```
+
+## Properties
+
+| Name       | Type                                         | Default | Description                                                                                         |
+| ---------- | -------------------------------------------- | ------- | --------------------------------------------------------------------------------------------------- |
+| `isNative` | `boolean`                                    |         | True inside the native iOS or Android app, false in a browser.                                      |
+| `platform` | `BfPlatform` (`'ios' \| 'android' \| 'web'`) |         | The platform the app runs on.                                                                       |
+| `mode`     | `Signal<BfShellMode>`                        |         | The platform's shell mode: `ios` on iOS, else `md`; `resolveShellMode()` applies the config.        |
+| `theme`    | `WritableSignal<BfTheme>`                    |         | The user's theme choice, stored in `BF_THEME_STORAGE` (`localStorage`); set it with `theme.set(…)`. |
+| `dark`     | `Signal<boolean>`                            |         | Whether the app is dark now: the theme choice, or the system's under `system`.                      |
+
+## Uses
+
+- [BfPlatform](bf-platform.md)
+- [BfShellMode](bf-shell-mode.md)
+- [BfTheme](bf-theme.md)
+
+## Used by
+
+- [resolveShellMode](resolve-shell-mode.md)

package/ai/reference/bf-platform.md

@@ -0,0 +1,28 @@
+# BfPlatform
+
+The platform the app runs on, native iOS, native Android or the web
+
+Type from `@bitforgehq/ui/mobile` · since 0.2.0
+
+The platform the app runs on: native iOS, native Android, or a browser.
+
+```ts
+import { type BfPlatform } from '@bitforgehq/ui/mobile';
+```
+
+## Signature
+
+```ts
+type BfPlatform = 'ios' | 'android' | 'web'
+```
+
+## Values
+
+- `ios`
+- `android`
+- `web`
+
+## Used by
+
+- [BfPlatformService](bf-platform-service.md)
+- [bfSystemBarsStyle](bf-system-bars-style.md)

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

@@ -0,0 +1,26 @@
+# BfProgressSize
+
+The two track heights of a progress bar, thin and regular
+
+Type from `@bitforgehq/ui` · since 0.1.0
+
+The track height of a `bf-progress`: sm or md.
+
+```ts
+import { type BfProgressSize } from '@bitforgehq/ui';
+```
+
+## Signature
+
+```ts
+type BfProgressSize = 'sm' | 'md'
+```
+
+## Values
+
+- `sm`
+- `md`
+
+## Used by
+
+- [bf-progress](../components/progress.md)

package/ai/reference/bf-progress-tone.md

@@ -0,0 +1,28 @@
+# BfProgressTone
+
+The four fill colours of a progress bar, from primary to danger
+
+Type from `@bitforgehq/ui` · since 0.1.0
+
+The fill colour of a `bf-progress`: primary, success, warning or danger.
+
+```ts
+import { type BfProgressTone } from '@bitforgehq/ui';
+```
+
+## Signature
+
+```ts
+type BfProgressTone = 'primary' | 'success' | 'warning' | 'danger'
+```
+
+## Values
+
+- `primary`
+- `success`
+- `warning`
+- `danger`
+
+## Used by
+
+- [bf-progress](../components/progress.md)

package/ai/reference/bf-radio-group-harness.md

@@ -0,0 +1,49 @@
+# BfRadioGroupHarness
+
+Test harness for the radio group: reads its options and selects one by label
+
+Class from `@bitforgehq/ui/testing` · since 0.3.0
+
+Harness for `bf-radio-group`. It works by option label, so a test never needs the native radio
+values (an object option's native value is its index).
+
+```ts
+import { BfRadioGroupHarness } from '@bitforgehq/ui/testing';
+```
+
+## Signature
+
+```ts
+class BfRadioGroupHarness extends ComponentHarness
+```
+
+## Methods
+
+### `getLabel(): Promise<string>`
+
+The legend, else the group's `aria-label`.
+
+### `getOptionLabels(): Promise<string[]>`
+
+The labels of the options, in order.
+
+### `getSelectedLabel(): Promise<string | null>`
+
+The selected option's label, `null` while nothing is selected.
+
+### `select(label: string): Promise<void>`
+
+Clicks the option with this label, as a user would. Throws for an unknown label, and for a
+disabled option or group (a user's click would do nothing).
+
+| Parameter | Type     | Description         |
+| --------- | -------- | ------------------- |
+| `label`   | `string` | The option's label. |
+
+### `isDisabled(): Promise<boolean>`
+
+Whether the whole group is disabled.
+
+### `getErrorText(): Promise<string>`
+
+The error text under the options.

package/ai/reference/bf-radio-group-orientation.md

@@ -0,0 +1,26 @@
+# BfRadioGroupOrientation
+
+Whether a radio group stacks its options or sets them in a row
+
+Type from `@bitforgehq/ui` · since 0.3.0
+
+How a `bf-radio-group` lays out its options: stacked (`vertical`) or in a row (`horizontal`).
+
+```ts
+import { type BfRadioGroupOrientation } from '@bitforgehq/ui';
+```
+
+## Signature
+
+```ts
+type BfRadioGroupOrientation = 'vertical' | 'horizontal'
+```
+
+## Values
+
+- `vertical`
+- `horizontal`
+
+## Used by
+
+- [bf-radio-group](../components/radio-group.md)

package/ai/reference/bf-radio-option.md

@@ -0,0 +1,30 @@
+# BfRadioOption
+
+One choice of a radio group with its value, label and optional description
+
+Interface from `@bitforgehq/ui` · since 0.1.0
+
+One choice of `bf-radio-group`; `value` is any type (a string by default).
+
+```ts
+import { type BfRadioOption } from '@bitforgehq/ui';
+```
+
+## Signature
+
+```ts
+interface BfRadioOption<T = string>
+```
+
+## Properties
+
+| Name          | Type      | Default  | Description                                                                 |
+| ------------- | --------- | -------- | --------------------------------------------------------------------------- |
+| `value`       | `T`       | required | The value the group's `value` takes when this option is chosen.             |
+| `label`       | `string`  | required | The visible label, also the radio's accessible name.                        |
+| `description` | `string`  |          | A second line under the label, linked to the radio with `aria-describedby`. |
+| `disabled`    | `boolean` |          | Whether this option cannot be chosen.                                       |
+
+## Used by
+
+- [bf-radio-group](../components/radio-group.md)

package/ai/reference/bf-refresher-refresh-event.md

@@ -0,0 +1,22 @@
+# BfRefresherRefreshEvent
+
+What a pull-to-refresh request carries: the callback that ends the refresh
+
+Interface from `@bitforgehq/ui/mobile` · since 0.3.0
+
+The payload of `bf-refresher`'s `refreshRequested` output: call `complete()` once the reload is
+done to animate the disc away.
+
+```ts
+import { type BfRefresherRefreshEvent } from '@bitforgehq/ui/mobile';
+```
+
+## Properties
+
+| Name       | Type         | Default  | Description                                                        |
+| ---------- | ------------ | -------- | ------------------------------------------------------------------ |
+| `complete` | `() => void` | required | Ends the refresh: animates the disc away and resets the refresher. |
+
+## Used by
+
+- [bf-refresher](../components/refresher.md)

package/ai/reference/bf-segment-option.md

@@ -0,0 +1,29 @@
+# BfSegmentOption
+
+One segment of a segmented control with its value, its label and a disabled flag
+
+Interface from `@bitforgehq/ui` · since 0.1.0
+
+One segment of `bf-segmented`; `value` is any type (a string by default).
+
+```ts
+import { type BfSegmentOption } from '@bitforgehq/ui';
+```
+
+## Signature
+
+```ts
+interface BfSegmentOption<T = string>
+```
+
+## Properties
+
+| Name       | Type      | Default  | Description                                                          |
+| ---------- | --------- | -------- | -------------------------------------------------------------------- |
+| `value`    | `T`       | required | The value the control's `value` takes when this segment is selected. |
+| `label`    | `string`  | required | The segment's visible label, also its accessible name.               |
+| `disabled` | `boolean` |          | Whether this segment cannot be selected.                             |
+
+## Used by
+
+- [bf-segmented](../components/segmented.md)

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

@@ -0,0 +1,48 @@
+# BfSegmentedHarness
+
+Test harness for the segmented control: reads its segments and selects one
+
+Class from `@bitforgehq/ui/testing` · since 0.3.0
+
+Harness for `bf-segmented`. It works by segment label, so a test never needs the option values.
+
+```ts
+import { BfSegmentedHarness } from '@bitforgehq/ui/testing';
+```
+
+## Signature
+
+```ts
+class BfSegmentedHarness extends ComponentHarness
+```
+
+## Methods
+
+### `getLabel(): Promise<string>`
+
+The group's accessible name (`label`, else `ariaLabel`); it is not rendered visibly.
+
+### `getOptionLabels(): Promise<string[]>`
+
+The labels of the segments, in order.
+
+### `getSelectedLabel(): Promise<string | null>`
+
+The selected segment's label, `null` while nothing is selected.
+
+### `select(label: string): Promise<void>`
+
+Clicks the segment with this label, as a user would. Throws for an unknown label, and for a
+disabled segment or control (a user's click would do nothing).
+
+| Parameter | Type     | Description          |
+| --------- | -------- | -------------------- |
+| `label`   | `string` | The segment's label. |
+
+### `isDisabled(): Promise<boolean>`
+
+Whether the control is disabled: every segment is.
+
+### `getErrorText(): Promise<string>`
+
+The error text under the track.

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

@@ -0,0 +1,29 @@
+# BfSegmentedSize
+
+Former name of the shared size scale for segmented controls, kept until 1.0.0
+
+Type from `@bitforgehq/ui` · since 0.1.0
+
+**Deprecated** 0.3.0 use BfSize; removed in 1.0.0
+
+The height step of a `bf-segmented`; the same scale as every sized widget.
+
+```ts
+import { type BfSegmentedSize } from '@bitforgehq/ui';
+```
+
+## Signature
+
+```ts
+type BfSegmentedSize = BfSize
+```
+
+## Values
+
+- `sm`
+- `md`
+- `lg`
+
+## Uses
+
+- [BfSize](bf-size.md)

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

@@ -0,0 +1,70 @@
+# BfSelectHarness
+
+Test harness for the select: reads its label and options and picks one
+
+Class from `@bitforgehq/ui/testing` · since 0.3.0
+
+Harness for `bf-select`. It works by option label, so a test never needs the native option
+values (an object option's native value is its index).
+
+```ts
+import { BfSelectHarness } from '@bitforgehq/ui/testing';
+```
+
+## Signature
+
+```ts
+class BfSelectHarness extends ComponentHarness
+```
+
+## Methods
+
+### `getLabel(): Promise<string>`
+
+The visible label without the required mark, else the `aria-label`.
+
+### `getValueLabel(): Promise<string>`
+
+The selected option's label, `''` while nothing is selected.
+
+### `getOptionLabels(): Promise<string[]>`
+
+The labels of the options, in order, without the placeholder.
+
+### `selectOption(label: string): Promise<void>`
+
+Chooses the option with this label, as a user would: the select's `value` becomes that
+option's value. Throws, leaving the value as it is, for an unknown or disabled option and
+while the select itself is disabled.
+
+| Parameter | Type     | Description         |
+| --------- | -------- | ------------------- |
+| `label`   | `string` | The option's label. |
+
+### `isDisabled(): Promise<boolean>`
+
+Whether the select is disabled.
+
+### `isReadonly(): Promise<boolean>`
+
+Whether the select is read-only (`aria-readonly`).
+
+### `isRequired(): Promise<boolean>`
+
+Whether the select is required.
+
+### `getErrorText(): Promise<string>`
+
+The error text under the select (an explicit message, or the first form error once touched).
+
+### `getHelpText(): Promise<string>`
+
+The help text under the select; it is hidden while an error shows.
+
+### `focus(): Promise<void>`
+
+Focuses the native select.
+
+### `blur(): Promise<void>`
+
+Blurs the native select, which marks a bound form field touched.

package/ai/reference/bf-select-option.md

@@ -0,0 +1,29 @@
+# BfSelectOption
+
+One choice of a select with its value, its label and a disabled flag
+
+Interface from `@bitforgehq/ui` · since 0.1.0
+
+One choice of `bf-select`; `value` is any type (a string by default).
+
+```ts
+import { type BfSelectOption } from '@bitforgehq/ui';
+```
+
+## Signature
+
+```ts
+interface BfSelectOption<T = string>
+```
+
+## Properties
+
+| Name       | Type      | Default  | Description                                                      |
+| ---------- | --------- | -------- | ---------------------------------------------------------------- |
+| `value`    | `T`       | required | The value the select's `value` takes when this option is chosen. |
+| `label`    | `string`  | required | The text of the native `option`.                                 |
+| `disabled` | `boolean` |          | Whether this option cannot be chosen.                            |
+
+## Used by
+
+- [bf-select](../components/select.md)