@bitforgehq/ui 0.3.0

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

@@ -0,0 +1,41 @@
+# BfHapticsService
+
+Haptic feedback on native devices that silently does nothing on the web
+
+Service from `@bitforgehq/ui/mobile` · since 0.2.0
+
+Haptic feedback: `impact`, `selection` and `notification` forward to `@capacitor/haptics` on
+native (loaded lazily on first use, the import cached like `BfKeyboardService`'s plugin); on
+the web, and when the plugin fails to load (an app that didn't add the optional dependency),
+every method resolves as a silent no-op.
+
+```ts
+import { BfHapticsService } from '@bitforgehq/ui/mobile';
+```
+
+## Methods
+
+### `impact(style: BfHapticsImpactStyle): Promise<void>`
+
+Impact feedback: a collision between UI elements of the given weight.
+
+| Parameter | Type                   | Description               |
+| --------- | ---------------------- | ------------------------- |
+| `style`   | `BfHapticsImpactStyle` | The weight of the impact. |
+
+### `selection(): Promise<void>`
+
+A light tick for a discrete selection change (scrubbing a picker, crossing a threshold).
+
+### `notification(type: BfHapticsNotificationType): Promise<void>`
+
+Feedback for the outcome of a task.
+
+| Parameter | Type                        | Description              |
+| --------- | --------------------------- | ------------------------ |
+| `type`    | `BfHapticsNotificationType` | The outcome of the task. |
+
+## Uses
+
+- [BfHapticsImpactStyle](bf-haptics-impact-style.md)
+- [BfHapticsNotificationType](bf-haptics-notification-type.md)

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

@@ -0,0 +1,29 @@
+# BfHarnessFilters
+
+Filters a library harness query by selector, ancestor and the widget label
+
+Interface from `@bitforgehq/ui/testing` · since 0.3.0
+
+Filters of every `@bitforgehq/ui/testing` harness's `with()`: the CDK's `selector` and
+`ancestor`, plus the widget's label (a select's label, a dialog's title, a toast's message, a
+menu item's text).
+
+```ts
+import { type BfHarnessFilters } from '@bitforgehq/ui/testing';
+```
+
+## Signature
+
+```ts
+interface BfHarnessFilters extends BaseHarnessFilters
+```
+
+## Properties
+
+| Name    | Type               | Default | Description                                                                            |
+| ------- | ------------------ | ------- | -------------------------------------------------------------------------------------- |
+| `label` | `string \| RegExp` |         | The label the harness's `getLabel()` (or equivalent) returns: exact text or a pattern. |
+
+## Used by
+
+- [BfMenuHarness](bf-menu-harness.md)

package/ai/reference/bf-horizontal-scroll-directive.md

@@ -0,0 +1,129 @@
+# BfHorizontalScrollDirective
+
+Deprecated touch-action opt-in for horizontal scrollers in stack pages, not needed
+
+Directive from `@bitforgehq/ui/mobile` · since 0.2.0
+
+**Deprecated** 0.3.0 use a plain overflow-x-auto scroller, which pans on its own; removed in 0.4.0
+
+Sets `touch-action: pan-x pan-y` (and a `data-bf-horizontal-scroll` marker) on a horizontally
+scrolling element inside a `bf-stack-outlet` page. Not needed: `touch-action` is not inherited,
+and a touch's effective value is the intersection of the values from the touched element up to
+its nearest scroll container only, so an `overflow-x-auto` row (a chips row, a carousel) pans
+on its own under the outlet's `touch-action: pan-y`, on iOS and on Android. Only the 50 px
+left-edge zone belongs to the swipe-back, with or without the directive.
+
+```ts
+import { BfHorizontalScrollDirective } from '@bitforgehq/ui/mobile';
+```
+
+Selector: `[bfHorizontalScroll]`
+
+**Deprecated in 0.3.0, removed in 0.4.0: not needed.** `bfHorizontalScroll` sets
+`touch-action: pan-x pan-y` and a `data-bf-horizontal-scroll` marker on a horizontally scrolling
+element inside a `bf-stack-outlet` page. A horizontal scroller pans on its own there, so drop the
+attribute: it changes nothing a finger can feel.
+
+## When to use
+
+Do not use it in new code. Use a plain `overflow-x-auto` row instead: a chips row or a carousel inside a [bf-stack-outlet](https://bitforge-ui.web.app/components/stack-outlet) page scrolls sideways with it alone. Remove `bfHorizontalScroll` (and its import) where it is used; it keeps working until 0.4.0.
+
+## Basic usage
+
+The directive on a chips row; without it the row scrolls the same way.
+
+```ts
+import { Component } from '@angular/core';
+import { BfChipComponent } from '@bitforgehq/ui';
+import { BfHorizontalScrollDirective } from '@bitforgehq/ui/mobile';
+
+/**
+ * A chip row with the deprecated directive.
+ *
+ * The row scrolls sideways the same way without `bfHorizontalScroll`; remove it.
+ *
+ * @preview none
+ */
+@Component({
+  selector: 'app-example-horizontal-scroll-basic',
+  imports: [BfChipComponent, BfHorizontalScrollDirective],
+  template: `
+    <div bfHorizontalScroll class="flex gap-2 overflow-x-auto">
+      <bf-chip>All</bf-chip>
+      <bf-chip>Open</bf-chip>
+      <bf-chip>Done</bf-chip>
+    </div>
+  `,
+})
+export class HorizontalScrollBasicExampleComponent {}
+```
+
+## Why it is not needed
+
+`touch-action` is not inherited. For a touch, the browser intersects the `touch-action` values
+from the touched element up to its nearest scroll container, and stops there (the Pointer Events
+model). An `overflow-x-auto` row is a scroll container itself, so the outlet host's
+`touch-action: pan-y` above it never reaches a touch inside the row: the row pans horizontally by
+itself. The outlet's value only constrains touches whose nearest scroll container is the outlet
+host (outside every scroller of the page, such as the header), so the edge swipe-back keeps
+receiving its pointer events there.
+
+Verified on the iOS Simulator (WKWebView) and the Android emulator (WebView 134): a row without
+the directive scrolled under a finger drag that started outside the 50 px edge zone.
+
+The swipe-back owns only the 50 px left-edge zone. A drag that starts there is the swipe-back,
+with or without the directive; anywhere else a horizontal scroller keeps its own scrolling.
+
+```ts
+import { Component } from '@angular/core';
+import { BfCardComponent } from '@bitforgehq/ui';
+import { BfHorizontalScrollDirective } from '@bitforgehq/ui/mobile';
+
+/**
+ * A snapping carousel.
+ *
+ * Anywhere outside the 50 px edge a carousel scrolls horizontally on its own, with or without the
+ * deprecated directive; the edge zone belongs to the swipe-back either way.
+ *
+ * @preview none
+ */
+@Component({
+  selector: 'app-example-horizontal-scroll-carousel',
+  imports: [BfCardComponent, BfHorizontalScrollDirective],
+  template: `
+    <div bfHorizontalScroll class="flex snap-x gap-3 overflow-x-auto">
+      @for (slide of slides; track slide) {
+        <bf-card variant="tint" class="w-64 shrink-0 snap-center">{{ slide }}</bf-card>
+      }
+    </div>
+  `,
+})
+export class HorizontalScrollCarouselExampleComponent {
+  protected readonly slides = ['Moodboard', 'Deck', 'Brand book'];
+}
+```
+
+## Desktop
+
+It only sets `touch-action`, so it changes nothing for a mouse, a trackpad or the keyboard.
+
+## Theming
+
+None: the directive only sets `touch-action` and a data attribute; it draws nothing itself.
+
+## Accessibility
+
+A touch-behaviour directive only; it changes no ARIA state and adds no role. Give the scroller
+itself the role and labelling its content needs (a `role="list"` of `bf-chip` toggles already
+carries its own state).
+
+## Notes
+
+### Do
+
+- Remove `bfHorizontalScroll` from your templates; `overflow-x-auto` is enough.
+
+### Don't
+
+- Don't add it to new code; it is removed in 0.4.0.
+- Don't expect it to win inside the 50 px left edge; the edge zone always belongs to the swipe-back.

package/ai/reference/bf-icon-button-variant.md

@@ -0,0 +1,28 @@
+# BfIconButtonVariant
+
+The four visual styles of an icon button, from tonal to plain text
+
+Type from `@bitforgehq/ui` · since 0.1.0
+
+The visual style of a `bf-icon-button`: tonal, primary, outline or text.
+
+```ts
+import { type BfIconButtonVariant } from '@bitforgehq/ui';
+```
+
+## Signature
+
+```ts
+type BfIconButtonVariant = 'tonal' | 'primary' | 'outline' | 'text'
+```
+
+## Values
+
+- `tonal`
+- `primary`
+- `outline`
+- `text`
+
+## Used by
+
+- [bf-icon-button](../components/icon-button.md)

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

@@ -0,0 +1,27 @@
+# BfIconSize
+
+The three icon sizes, 16, 20 and 24 pixels, matching the text sizes
+
+Type from `@bitforgehq/ui/icons` · since 0.1.0
+
+The size of a `bf-icon`: sm 16, md 20 or lg 24 px.
+
+```ts
+import { type BfIconSize } from '@bitforgehq/ui/icons';
+```
+
+## Signature
+
+```ts
+type BfIconSize = 'sm' | 'md' | 'lg'
+```
+
+## Values
+
+- `sm`
+- `md`
+- `lg`
+
+## Used by
+
+- [bf-icon](../components/icon.md)

package/ai/reference/bf-input-autocapitalize.md

@@ -0,0 +1,36 @@
+# BfInputAutocapitalize
+
+A text field's capitalisation setting, a mode or empty to leave it off
+
+Type from `@bitforgehq/ui` · since 0.3.0
+
+The `autocapitalize` of a `bf-input`: a `BfAutocapitalize`, or `''` (the default) to leave the
+native `autocapitalize` off.
+
+```ts
+import { type BfInputAutocapitalize } from '@bitforgehq/ui';
+```
+
+## Signature
+
+```ts
+type BfInputAutocapitalize = BfAutocapitalize | ''
+```
+
+## Values
+
+- `off`
+- `none`
+- `on`
+- `sentences`
+- `words`
+- `characters`
+- ``
+
+## Uses
+
+- [BfAutocapitalize](bf-autocapitalize.md)
+
+## Used by
+
+- [bf-input](../components/input.md)

package/ai/reference/bf-input-enter-key-hint.md

@@ -0,0 +1,38 @@
+# BfInputEnterKeyHint
+
+A field's Enter key label setting, a label or empty to leave it off
+
+Type from `@bitforgehq/ui` · since 0.3.0
+
+The `enterKeyHint` of a `bf-input` or `bf-number-input`: a `BfEnterKeyHint`, or `''` (the
+default) to leave the native `enterkeyhint` off.
+
+```ts
+import { type BfInputEnterKeyHint } from '@bitforgehq/ui';
+```
+
+## Signature
+
+```ts
+type BfInputEnterKeyHint = BfEnterKeyHint | ''
+```
+
+## Values
+
+- `enter`
+- `done`
+- `go`
+- `next`
+- `previous`
+- `search`
+- `send`
+- ``
+
+## Uses
+
+- [BfEnterKeyHint](bf-enter-key-hint.md)
+
+## Used by
+
+- [bf-input](../components/input.md)
+- [bf-number-input](../components/number-input.md)

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

@@ -0,0 +1,38 @@
+# BfInputInputMode
+
+A text field's virtual keyboard setting, a keyboard or empty to leave it off
+
+Type from `@bitforgehq/ui` · since 0.3.0
+
+The `inputMode` of a `bf-input`: a `BfInputMode`, or `''` (the default) to leave the native
+`inputmode` off.
+
+```ts
+import { type BfInputInputMode } from '@bitforgehq/ui';
+```
+
+## Signature
+
+```ts
+type BfInputInputMode = BfInputMode | ''
+```
+
+## Values
+
+- `none`
+- `text`
+- `decimal`
+- `numeric`
+- `tel`
+- `search`
+- `email`
+- `url`
+- ``
+
+## Uses
+
+- [BfInputMode](bf-input-mode.md)
+
+## Used by
+
+- [bf-input](../components/input.md)

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

@@ -0,0 +1,32 @@
+# BfInputMode
+
+The virtual keyboards a phone can show for a text field
+
+Type from `@bitforgehq/ui` · since 0.2.0
+
+Native `inputmode`: the virtual keyboard a phone shows.
+
+```ts
+import { type BfInputMode } from '@bitforgehq/ui';
+```
+
+## Signature
+
+```ts
+type BfInputMode = 'none' | 'text' | 'decimal' | 'numeric' | 'tel' | 'search' | 'email' | 'url'
+```
+
+## Values
+
+- `none`
+- `text`
+- `decimal`
+- `numeric`
+- `tel`
+- `search`
+- `email`
+- `url`
+
+## Used by
+
+- [BfInputInputMode](bf-input-input-mode.md)

package/ai/reference/bf-input-type.md

@@ -0,0 +1,35 @@
+# BfInputType
+
+The native input types a text field supports, all bound as strings
+
+Type from `@bitforgehq/ui` · since 0.1.0
+
+The native `type` of a `bf-input`; the value stays a string (for numbers, use `bf-number-input`).
+
+```ts
+import { type BfInputType } from '@bitforgehq/ui';
+```
+
+## Signature
+
+```ts
+type BfInputType = | 'text' | 'email' | 'password' | 'number' | 'tel' | 'url' | 'search' | 'date' | 'time' | 'datetime-local' | 'month'
+```
+
+## Values
+
+- `text`
+- `email`
+- `password`
+- `number`
+- `tel`
+- `url`
+- `search`
+- `date`
+- `time`
+- `datetime-local`
+- `month`
+
+## Used by
+
+- [bf-input](../components/input.md)

package/ai/reference/bf-jsdom-shim-options.md

@@ -0,0 +1,22 @@
+# BfJsdomShimOptions
+
+Options of the jsdom shims: the matchMedia stub and its reduced-motion answer
+
+Interface from `@bitforgehq/ui/testing` · since 0.3.0
+
+Options of `installBfJsdomShims()`.
+
+```ts
+import { type BfJsdomShimOptions } from '@bitforgehq/ui/testing';
+```
+
+## Properties
+
+| Name            | Type      | Default | Description                                                                                                                                                           |
+| --------------- | --------- | ------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `matchMedia`    | `boolean` | `true`  | Install a `matchMedia` stub where missing (all queries false).                                                                                                        |
+| `reducedMotion` | `boolean` | `false` | With the stub: report `(prefers-reduced-motion: reduce)` as matching, so overlays use their short fade. Has no effect where the environment already has `matchMedia`. |
+
+## Used by
+
+- [installBfJsdomShims](install-bf-jsdom-shims.md)

package/ai/reference/bf-keyboard-assist-behavior.md

@@ -0,0 +1,26 @@
+# BfKeyboardAssistBehavior
+
+Whether the keyboard assist scrolls a focused field into view smoothly or at once
+
+Type from `@bitforgehq/ui/mobile` · since 0.3.0
+
+How `bfKeyboardAssist` scrolls the focused control into view: `smooth` or `instant`.
+
+```ts
+import { type BfKeyboardAssistBehavior } from '@bitforgehq/ui/mobile';
+```
+
+## Signature
+
+```ts
+type BfKeyboardAssistBehavior = 'smooth' | 'instant'
+```
+
+## Values
+
+- `smooth`
+- `instant`
+
+## Used by
+
+- [BfKeyboardAssistDirective](bf-keyboard-assist-directive.md)

package/ai/reference/bf-keyboard-assist-directive.md

@@ -0,0 +1,185 @@
+# BfKeyboardAssistDirective
+
+Keeps the focused text field of a scroll container clear of the soft keyboard
+
+Directive from `@bitforgehq/ui/mobile` · since 0.2.0
+
+Keeps the focused text control of a scroll container clear of the soft keyboard. On keyboard
+will-show it pads the scroller by the part below the keyboard's top edge
+(`BfKeyboardService.keyboardTop()`: `padding-bottom`, plus `scroll-padding-bottom` with the
+margin for engine scrolls), then scrolls the focused `input`, `textarea` or `[contenteditable]`
+up until it sits `bfKeyboardAssistMargin` px above the keyboard (or down until it sits the margin
+below the scroller's top edge; in a scroller too short for the control and both margins, the gap
+above the control shrinks first, then the one above the keyboard, so a control shorter than the
+scroller stays whole; a taller one keeps its bottom at the keyboard top). The covered part is
+measured again at did-show and on every window or `visualViewport` resize, so a WebView that
+resizes for the keyboard (Android) gets no padding and a padding never outlives the keyboard,
+even on a detached page. A hidden host (a parked page, `visibility: hidden`) is never padded or
+scrolled. The reveal waits for the engine's own focus scroll to settle (100 ms without a `scroll`
+event, 120 ms if none arrives, at most 400 ms), then scrolls once; one correction follows at
+did-show once the scroller is quiet (skipped while a reveal is pending). Focus moving to another
+field while the keyboard is open re-arms the reveal, and both paddings go away on hide.
+`refresh()` measures and corrects again for a container that moved on its own. `bf-content`
+applies it to its own scroller; use it directly only on a custom scroll container.
+
+```ts
+import { BfKeyboardAssistDirective } from '@bitforgehq/ui/mobile';
+```
+
+Selector: `[bfKeyboardAssist]`
+
+Keeps the focused text control of a scroll container clear of the soft keyboard. `bf-content`
+applies it to its own scroller, so most pages never use it directly; put it on a custom scroll
+container only when that container is not a `bf-content`. It reads `BfKeyboardService`: plugin
+events on native (`@capacitor/keyboard`), a `visualViewport` fallback on the web.
+
+## When to use
+
+Use `bfKeyboardAssist` on a custom scroll container with text fields in a Capacitor app, so the soft keyboard never covers the focused field. Use [bf-content](https://bitforge-ui.web.app/components/content) instead for a normal page, which applies it already.
+
+## Basic usage
+
+```ts
+import { Component, signal } from '@angular/core';
+import { BfInputComponent, BfTextareaComponent } from '@bitforgehq/ui';
+import { BfKeyboardAssistDirective } from '@bitforgehq/ui/mobile';
+
+/**
+ * A scroll container that keeps the focused field above the keyboard.
+ *
+ * `bf-content` applies the directive itself; put it on any other scroller.
+ *
+ * @preview none
+ */
+@Component({
+  selector: 'app-example-keyboard-assist-basic',
+  imports: [BfInputComponent, BfKeyboardAssistDirective, BfTextareaComponent],
+  template: `
+    <div class="h-full overflow-y-auto" bfKeyboardAssist>
+      <bf-input label="Name" [(value)]="name" />
+      <bf-textarea label="Notes" [(value)]="notes" />
+    </div>
+  `,
+})
+export class KeyboardAssistBasicExampleComponent {
+  protected readonly name = signal('');
+  protected readonly notes = signal('');
+}
+```
+
+## How it works
+
+- **On keyboard will-show** it sets `padding-bottom` to the part of the scroller below the
+  keyboard's top edge (`BfKeyboardService.keyboardTop()`) and `scroll-padding-bottom` to that plus
+  the margin. On iOS, where the keyboard overlays the WebView, the top edge is the `100lvh` rest
+  height minus the keyboard height, so the padding is the keyboard height (minus anything below
+  the scroller). On Android and the web, where the viewport shrinks for the keyboard, it is the
+  bottom of the visual viewport: the scroller already ends there, so nothing is padded.
+- **At did-show and on every resize** (window `resize` and `visualViewport` `resize`, keyboard up
+  or not) it measures the covered part again, so a padding never outlives the keyboard — even on a
+  parked page whose view is detached.
+- **A hidden host** (a parked page, `visibility: hidden`) gets no padding and no reveal, and loses
+  any padding it had at its next measurement.
+- **Then it reveals** the focused `input`, `textarea` or `[contenteditable]`: it scrolls the
+  container once until the control's bottom sits `bfKeyboardAssistMargin` px above the keyboard
+  (a control hidden above the container's top edge scrolls down until its top sits the margin
+  below it). In a container too short for the control and both margins — a sheet or modal capped
+  by the keyboard in phone landscape — the gap above the control shrinks first, then the one above
+  the keyboard, so a control shorter than the container stays whole (a taller one, such as a
+  multi-line textarea, keeps its bottom at the keyboard's top edge).
+  It first waits for the engine's own focus scroll to settle — 100 ms without a `scroll` event on
+  the container, 120 ms if none arrives, at most 400 ms — and then measures, so its scroll is
+  never added on top of one still running.
+- **At did-show** it corrects the reveal once (instantly), after any scroll in progress has been
+  quiet for 100 ms; it skips the correction while the reveal is still pending.
+- **Field to field** while the keyboard is open (no new will-show), a `focusin` re-arms the
+  settled reveal.
+- **On hide** it removes both paddings and cancels any pending reveal.
+- `select`, buttons, checkboxes and other non-text controls open no keyboard and are ignored.
+- **`refresh()`** measures the covered part again and, while the keyboard is up, corrects the
+  reveal once. Call it on a container that moves with the keyboard on its own — `bf-sheet` calls
+  it when its lift above the keyboard has finished sliding.
+
+## Margin and behaviour
+
+```ts
+import { Component, signal } from '@angular/core';
+import { BfTextareaComponent } from '@bitforgehq/ui';
+import { BfKeyboardAssistDirective } from '@bitforgehq/ui/mobile';
+
+/**
+ * A larger margin above the keyboard and an instant scroll.
+ *
+ * @preview none
+ */
+@Component({
+  selector: 'app-example-keyboard-assist-options',
+  imports: [BfKeyboardAssistDirective, BfTextareaComponent],
+  template: `
+    <div
+      class="h-full overflow-y-auto"
+      bfKeyboardAssist
+      [bfKeyboardAssistMargin]="32"
+      bfKeyboardAssistBehavior="instant"
+    >
+      <bf-textarea label="Reply" [(value)]="reply" />
+    </div>
+  `,
+})
+export class KeyboardAssistOptionsExampleComponent {
+  protected readonly reply = signal('');
+}
+```
+
+`bfKeyboardAssistMargin` (default `24`) is the gap above the keyboard;
+`bfKeyboardAssistBehavior` (`'smooth'` default, or `'instant'`) is the scroll behaviour of the
+delayed reveal. Set `[bfKeyboardAssist]="false"` to turn it off.
+
+## Desktop
+
+A desktop browser has no soft keyboard, so the directive adds no padding and never scrolls there; leave it out of desktop layouts.
+
+## Theming
+
+None — it writes only inline `padding-bottom` and `scroll-padding-bottom` on its host while the
+keyboard is open, and removes them again on hide. Do not rely on your own inline bottom padding on
+the same element.
+
+## Accessibility
+
+It keeps the focused control and the text being typed visible above the soft keyboard and never
+moves focus itself. `scroll-padding-bottom` also keeps engine-driven scrolls (moving to the next
+field with the keyboard's arrows or `Tab`) clear of the keyboard.
+
+## Notes
+
+### Do
+
+- Rely on `bf-content`'s built-in assist; add the directive only to a custom scroll container.
+- Turn it off (`[bfKeyboardAssist]="false"`) for screens that pin their own composer above the
+  keyboard.
+
+### Don't
+
+- Don't put it on an element that does not scroll; it scrolls its own host.
+- Don't combine it with your own keyboard padding on the same scroller.
+
+## Inputs
+
+| Name                       | Type                                                 | Default    | Description                                                                                         |
+| -------------------------- | ---------------------------------------------------- | ---------- | --------------------------------------------------------------------------------------------------- |
+| `bfKeyboardAssist`         | `boolean`                                            | `true`     | Enables the assist; set it false for screens that manage the keyboard themselves (a chat composer). |
+| `bfKeyboardAssistMargin`   | `number`                                             | `24`       | Gap kept between the focused control and the top of the keyboard, in px.                            |
+| `bfKeyboardAssistBehavior` | `BfKeyboardAssistBehavior` (`'smooth' \| 'instant'`) | `'smooth'` | Scroll behaviour of the reveal.                                                                     |
+
+## Methods
+
+### `refresh(): void`
+
+Measures the covered part again and, while the keyboard is up, corrects the reveal once
+(instantly, after any scroll in progress). For a container that moves with the keyboard
+outside the keyboard events — `bf-sheet` calls it once its lift above the keyboard has ended.
+
+## Uses
+
+- [BfKeyboardAssistBehavior](bf-keyboard-assist-behavior.md)