@bitforgehq/ui 0.3.0

package/ai/reference/bf-alert-variant.md

@@ -0,0 +1,28 @@
+# BfAlertVariant
+
+The four tones of an alert, from neutral information to a danger message
+
+Type from `@bitforgehq/ui` · since 0.1.0
+
+The tone of a `bf-alert`: neutral, success, warning or danger.
+
+```ts
+import { type BfAlertVariant } from '@bitforgehq/ui';
+```
+
+## Signature
+
+```ts
+type BfAlertVariant = 'neutral' | 'success' | 'warning' | 'danger'
+```
+
+## Values
+
+- `neutral`
+- `success`
+- `warning`
+- `danger`
+
+## Used by
+
+- [bf-alert](../components/alert.md)

package/ai/reference/bf-autocapitalize.md

@@ -0,0 +1,30 @@
+# BfAutocapitalize
+
+How a phone keyboard capitalises the text typed into a field
+
+Type from `@bitforgehq/ui` · since 0.2.0
+
+Native `autocapitalize`: how a virtual keyboard capitalises typed text.
+
+```ts
+import { type BfAutocapitalize } from '@bitforgehq/ui';
+```
+
+## Signature
+
+```ts
+type BfAutocapitalize = 'off' | 'none' | 'on' | 'sentences' | 'words' | 'characters'
+```
+
+## Values
+
+- `off`
+- `none`
+- `on`
+- `sentences`
+- `words`
+- `characters`
+
+## Used by
+
+- [BfInputAutocapitalize](bf-input-autocapitalize.md)

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

@@ -0,0 +1,27 @@
+# BfAvatarSize
+
+The three sizes of an avatar, from a list row to a profile header
+
+Type from `@bitforgehq/ui` · since 0.1.0
+
+The size of a `bf-avatar`: sm, md or lg.
+
+```ts
+import { type BfAvatarSize } from '@bitforgehq/ui';
+```
+
+## Signature
+
+```ts
+type BfAvatarSize = 'sm' | 'md' | 'lg'
+```
+
+## Values
+
+- `sm`
+- `md`
+- `lg`
+
+## Used by
+
+- [bf-avatar](../components/avatar.md)

package/ai/reference/bf-avatar-variant.md

@@ -0,0 +1,28 @@
+# BfAvatarVariant
+
+The four colour schemes of an avatar behind its initials or icon
+
+Type from `@bitforgehq/ui` · since 0.1.0
+
+The colour scheme of a `bf-avatar`: tint, ink, warning or neutral.
+
+```ts
+import { type BfAvatarVariant } from '@bitforgehq/ui';
+```
+
+## Signature
+
+```ts
+type BfAvatarVariant = 'tint' | 'ink' | 'warning' | 'neutral'
+```
+
+## Values
+
+- `tint`
+- `ink`
+- `warning`
+- `neutral`
+
+## Used by
+
+- [bf-avatar](../components/avatar.md)

package/ai/reference/bf-back-at-root.md

@@ -0,0 +1,28 @@
+# BfBackAtRoot
+
+What Android back does at a stack root, background the app or exit it
+
+Type from `@bitforgehq/ui/mobile` · since 0.3.0
+
+What the Android back button does at the root of every stack, when no overlay or page claims
+it: `minimize` moves the app to the background (`App.minimizeApp()`), so a relaunch resumes it
+warm; `exit` finishes the activity (`App.exitApp()`), so the next launch starts cold.
+
+```ts
+import { type BfBackAtRoot } from '@bitforgehq/ui/mobile';
+```
+
+## Signature
+
+```ts
+type BfBackAtRoot = 'minimize' | 'exit'
+```
+
+## Values
+
+- `minimize`
+- `exit`
+
+## Used by
+
+- [BfShellConfig](bf-shell-config.md)

package/ai/reference/bf-back-button-service.md

@@ -0,0 +1,40 @@
+# BfBackButtonService
+
+The Android hardware back button queue that overlays and navigation stacks share
+
+Service from `@bitforgehq/ui/mobile` · since 0.2.0
+
+The hardware back button queue: on native Android it listens to `@capacitor/app`'s
+`backButton` event; on iOS and web nothing is registered (there is no hardware button to
+listen to), but `register` and `dispatch` still work so overlays and tests can drive the same
+queue. `register` adds a handler at a priority (an open overlay registers at 100,
+`BfNavController` at 0 — it pops the deepest active `bf-stack-outlet`); `dispatch` runs the
+queue from the highest priority down until one handler returns true; on equal priority the
+newest registration runs first, so stacked overlays close top-down. When none does (every
+stack is at its first page), the app moves to the background (`App.minimizeApp()`), so a
+relaunch resumes it warm; `provideBfShell({ backAtRoot: 'exit' })` finishes it instead
+(`App.exitApp()`).
+
+```ts
+import { BfBackButtonService } from '@bitforgehq/ui/mobile';
+```
+
+## Methods
+
+### `register(priority: number, handler: () => boolean | Promise<boolean>): () => void`
+
+Adds a handler at `priority` (higher priority runs first; on a tie, the handler registered
+last runs first). Returns a function that removes
+it again; call it when the registrant (an overlay, an outlet) is torn down.
+
+| Parameter  | Type                                | Description                                                       |
+| ---------- | ----------------------------------- | ----------------------------------------------------------------- |
+| `priority` | `number`                            | Higher runs first: an open overlay uses 100, `BfNavController` 0. |
+| `handler`  | `() => boolean \| Promise<boolean>` | Returns (or resolves) true when it handled the press.             |
+
+### `dispatch(): Promise<void>`
+
+Runs the registered handlers from highest to lowest priority until one claims the event
+(returns true); when none does, minimizes the app (or exits it with `backAtRoot: 'exit'`).
+Public so tests and the native listener share one code path, and so overlays outside the
+native listener's reach (phase 2c) can still be driven by it, e.g. `Escape`.

package/ai/reference/bf-badge-variant.md

@@ -0,0 +1,29 @@
+# BfBadgeVariant
+
+The five tones of a badge, from neutral counts to danger states
+
+Type from `@bitforgehq/ui` · since 0.1.0
+
+The tone of a `bf-badge`: neutral, primary, success, warning or danger.
+
+```ts
+import { type BfBadgeVariant } from '@bitforgehq/ui';
+```
+
+## Signature
+
+```ts
+type BfBadgeVariant = 'neutral' | 'primary' | 'success' | 'warning' | 'danger'
+```
+
+## Values
+
+- `neutral`
+- `primary`
+- `success`
+- `warning`
+- `danger`
+
+## Used by
+
+- [bf-badge](../components/badge.md)

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

@@ -0,0 +1,29 @@
+# BfButtonSize
+
+Former name of the shared size scale for buttons, 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-button`; the same scale as every sized widget.
+
+```ts
+import { type BfButtonSize } from '@bitforgehq/ui';
+```
+
+## Signature
+
+```ts
+type BfButtonSize = BfSize
+```
+
+## Values
+
+- `sm`
+- `md`
+- `lg`
+
+## Uses
+
+- [BfSize](bf-size.md)

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

@@ -0,0 +1,28 @@
+# BfButtonType
+
+The native button types, for a plain action, a form submit or reset
+
+Type from `@bitforgehq/ui` · since 0.1.0
+
+The native `type` of a `bf-button`: button, submit or reset.
+
+```ts
+import { type BfButtonType } from '@bitforgehq/ui';
+```
+
+## Signature
+
+```ts
+type BfButtonType = 'button' | 'submit' | 'reset'
+```
+
+## Values
+
+- `button`
+- `submit`
+- `reset`
+
+## Used by
+
+- [bf-button](../components/button.md)
+- [bf-icon-button](../components/icon-button.md)

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

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

package/ai/reference/bf-card-padding.md

@@ -0,0 +1,26 @@
+# BfCardPadding
+
+The two inner paddings of a card, regular and roomy
+
+Type from `@bitforgehq/ui` · since 0.1.0
+
+The inner padding of a `bf-card`: md or lg.
+
+```ts
+import { type BfCardPadding } from '@bitforgehq/ui';
+```
+
+## Signature
+
+```ts
+type BfCardPadding = 'md' | 'lg'
+```
+
+## Values
+
+- `md`
+- `lg`
+
+## Used by
+
+- [bf-card](../components/card.md)

package/ai/reference/bf-card-variant.md

@@ -0,0 +1,28 @@
+# BfCardVariant
+
+The four card surfaces, from a raised panel to a flat outline
+
+Type from `@bitforgehq/ui` · since 0.1.0
+
+The surface of a `bf-card`: raised, tint, ink or flat.
+
+```ts
+import { type BfCardVariant } from '@bitforgehq/ui';
+```
+
+## Signature
+
+```ts
+type BfCardVariant = 'raised' | 'tint' | 'ink' | 'flat'
+```
+
+## Values
+
+- `raised`
+- `tint`
+- `ink`
+- `flat`
+
+## Used by
+
+- [bf-card](../components/card.md)

package/ai/reference/bf-chip-group-mode.md

@@ -0,0 +1,27 @@
+# BfChipGroupMode
+
+Whether a chip group picks exactly one chip or lets each chip toggle alone
+
+Type from `@bitforgehq/ui` · since 0.3.0
+
+How a `bf-chip-group` treats its chips: one selected at a time (`single`, a radio group) or
+independent toggles (`multiple`).
+
+```ts
+import { type BfChipGroupMode } from '@bitforgehq/ui';
+```
+
+## Signature
+
+```ts
+type BfChipGroupMode = 'single' | 'multiple'
+```
+
+## Values
+
+- `single`
+- `multiple`
+
+## Used by
+
+- [bf-chip-group](../components/chip-group.md)

package/ai/reference/bf-chip-variant.md

@@ -0,0 +1,26 @@
+# BfChipVariant
+
+The two chip colours, a soft tonal tint or a dark ink fill
+
+Type from `@bitforgehq/ui` · since 0.1.0
+
+The colour of a `bf-chip`: tonal or ink.
+
+```ts
+import { type BfChipVariant } from '@bitforgehq/ui';
+```
+
+## Signature
+
+```ts
+type BfChipVariant = 'tonal' | 'ink'
+```
+
+## Values
+
+- `tonal`
+- `ink`
+
+## Used by
+
+- [bf-chip](../components/chip.md)

package/ai/reference/bf-compare-with.md

@@ -0,0 +1,24 @@
+# BfCompareWith
+
+Equality of choice values, for options that are objects rather than primitives
+
+Type from `@bitforgehq/ui` · since 0.3.0
+
+Equality that matches a bound value to an option's value (`compareWith` of the choice controls).
+Called as `compareWith(optionValue, value)`: the option's value first, the bound value second.
+
+```ts
+import { type BfCompareWith } from '@bitforgehq/ui';
+```
+
+## Signature
+
+```ts
+type BfCompareWith<T> = (optionValue: T, value: T) => boolean
+```
+
+## Used by
+
+- [bf-radio-group](../components/radio-group.md)
+- [bf-segmented](../components/segmented.md)
+- [bf-select](../components/select.md)

package/ai/reference/bf-component-overlay-ref.md

@@ -0,0 +1,33 @@
+# BfComponentOverlayRef
+
+Overlay handle whose content is a component, with access to its ComponentRef
+
+Class from `@bitforgehq/ui/overlay` · since 0.2.0
+
+Also exported from `@bitforgehq/ui/mobile` (deprecated: 0.3.0 use BfComponentOverlayRef from '@bitforgehq/ui/overlay'; removed in 0.4.0).
+
+An overlay ref whose content is a component, exposing its `ComponentRef`.
+
+```ts
+import { BfComponentOverlayRef } from '@bitforgehq/ui/overlay';
+```
+
+## Signature
+
+```ts
+class BfComponentOverlayRef<C, T = unknown> extends BfOverlayRef<T>
+```
+
+## Properties
+
+| Name           | Type              | Default | Description                                                   |
+| -------------- | ----------------- | ------- | ------------------------------------------------------------- |
+| `componentRef` | `ComponentRef<C>` |         | The content component; available as soon as `open()` returns. |
+
+## Uses
+
+- [BfOverlayRef](bf-overlay-ref.md)
+
+## Used by
+
+- [BfOverlayService](bf-overlay-service.md)

package/ai/reference/bf-confirm-button-role.md

@@ -0,0 +1,26 @@
+# BfConfirmButtonRole
+
+The role of a confirm dialog button, the cancel answer or a destructive action
+
+Type from `@bitforgehq/ui/overlay` · since 0.3.0
+
+The role of a confirm dialog button: `cancel` answers `Escape`, `destructive` renders `danger`.
+
+```ts
+import { type BfConfirmButtonRole } from '@bitforgehq/ui/overlay';
+```
+
+## Signature
+
+```ts
+type BfConfirmButtonRole = 'cancel' | 'destructive'
+```
+
+## Values
+
+- `cancel`
+- `destructive`
+
+## Used by
+
+- [BfConfirmButton](bf-confirm-button.md)

package/ai/reference/bf-confirm-button.md

@@ -0,0 +1,27 @@
+# BfConfirmButton
+
+One button of a confirm dialog: its answer, its label and its role
+
+Interface from `@bitforgehq/ui/overlay` · since 0.3.0
+
+A button of `BfDialogService.confirm()`.
+
+```ts
+import { type BfConfirmButton } from '@bitforgehq/ui/overlay';
+```
+
+## Properties
+
+| Name    | Type                                                | Default  | Description                                                                       |
+| ------- | --------------------------------------------------- | -------- | --------------------------------------------------------------------------------- |
+| `id`    | `string`                                            |          | The value `confirm()` resolves with (default the `label`).                        |
+| `label` | `string`                                            | required | Button text.                                                                      |
+| `role`  | `BfConfirmButtonRole` (`'cancel' \| 'destructive'`) |          | `cancel` answers `Escape` and gets initial focus; `destructive` renders `danger`. |
+
+## Uses
+
+- [BfConfirmButtonRole](bf-confirm-button-role.md)
+
+## Used by
+
+- [BfConfirmOptions](bf-confirm-options.md)

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

@@ -0,0 +1,31 @@
+# BfConfirmOptions
+
+Options of a confirm dialog: its title, message, buttons and width
+
+Interface from `@bitforgehq/ui/overlay` · since 0.3.0
+
+Options of `BfDialogService.confirm()`.
+
+```ts
+import { type BfConfirmOptions } from '@bitforgehq/ui/overlay';
+```
+
+## Properties
+
+| Name                | Type                             | Default  | Description                                                                                                                          |
+| ------------------- | -------------------------------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------ |
+| `title`             | `string`                         | required | Heading, rendered as the `h2` the alert dialog is labelled by.                                                                       |
+| `message`           | `string`                         |          | Text under the title; the dialog's `aria-describedby` points to it.                                                                  |
+| `buttons`           | `readonly BfConfirmButton[]`     |          | Buttons, in order, right-aligned (default Cancel and OK from `provideBfLabels()`, ids `cancel` and `ok`).                            |
+| `size`              | `BfConfirmSize` (`'sm' \| 'md'`) | `'sm'`   | Width (default `sm`, 24 rem).                                                                                                        |
+| `closeOnNavigation` | `boolean`                        | `true`   | A navigation to another URL path closes the dialog, resolving the cancel button's answer, or `undefined` without one (default true). |
+| `injector`          | `Injector`                       |          | Source of the default button labels and parent of the content's injector.                                                            |
+
+## Uses
+
+- [BfConfirmButton](bf-confirm-button.md)
+- [BfConfirmSize](bf-confirm-size.md)
+
+## Used by
+
+- [BfDialogService](bf-dialog-service.md)

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

@@ -0,0 +1,26 @@
+# BfConfirmSize
+
+The two widths a confirm dialog comes in, small or medium
+
+Type from `@bitforgehq/ui/overlay` · since 0.3.0
+
+The width of a confirm dialog: `sm` (24 rem) or `md`.
+
+```ts
+import { type BfConfirmSize } from '@bitforgehq/ui/overlay';
+```
+
+## Signature
+
+```ts
+type BfConfirmSize = 'sm' | 'md'
+```
+
+## Values
+
+- `sm`
+- `md`
+
+## Used by
+
+- [BfConfirmOptions](bf-confirm-options.md)

package/ai/reference/bf-content-scroll-event.md

@@ -0,0 +1,21 @@
+# BfContentScrollEvent
+
+What a content scroll event carries: the scroller's current top offset
+
+Interface from `@bitforgehq/ui/mobile` · since 0.3.0
+
+The payload of `bf-content`'s `scrolled` output: the scroller's `scrollTop` after the scroll.
+
+```ts
+import { type BfContentScrollEvent } from '@bitforgehq/ui/mobile';
+```
+
+## Properties
+
+| Name        | Type     | Default  | Description                        |
+| ----------- | -------- | -------- | ---------------------------------- |
+| `scrollTop` | `number` | required | The scroller's `scrollTop`, in px. |
+
+## Used by
+
+- [bf-content](../components/content.md)

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

@@ -0,0 +1,32 @@
+# BfDefaultsOptions
+
+The size steps provideBfDefaults sets, each one falling back to the parent
+
+Interface from `@bitforgehq/ui` · since 0.3.0
+
+Options of `provideBfDefaults()`: any step left out keeps the parent injector's value.
+
+```ts
+import { type BfDefaultsOptions } from '@bitforgehq/ui';
+```
+
+## Signature
+
+```ts
+interface BfDefaultsOptions extends Partial<BfDefaults>
+```
+
+## Properties
+
+| Name   | Type                              | Default | Description                                                                              |
+| ------ | --------------------------------- | ------- | ---------------------------------------------------------------------------------------- |
+| `size` | `BfSize` (`'sm' \| 'md' \| 'lg'`) |         | Sets `fieldSize` and `controlSize` together; an explicit `fieldSize`/`controlSize` wins. |
+
+## Uses
+
+- [BfDefaults](bf-defaults.md)
+- [BfSize](bf-size.md)
+
+## Used by
+
+- [provideBfDefaults](provide-bf-defaults.md)

package/ai/reference/bf-defaults.md

@@ -0,0 +1,28 @@
+# BfDefaults
+
+The default height steps of text fields and of actions and choice controls
+
+Interface from `@bitforgehq/ui` · since 0.3.0
+
+App-wide widget defaults, read by every sized widget whose `size` input is left unset.
+
+```ts
+import { type BfDefaults } from '@bitforgehq/ui';
+```
+
+## Properties
+
+| Name          | Type                              | Default | Description                                                                                                                           |
+| ------------- | --------------------------------- | ------- | ------------------------------------------------------------------------------------------------------------------------------------- |
+| `fieldSize`   | `BfSize` (`'sm' \| 'md' \| 'lg'`) | `'md'`  | Height step of text fields: bf-input, bf-number-input, bf-select, bf-textarea.                                                        |
+| `controlSize` | `BfSize` (`'sm' \| 'md' \| 'lg'`) | `'md'`  | Height step of actions and choice controls: bf-button, bf-icon-button, bf-chip, bf-segmented, bf-checkbox, bf-toggle, bf-radio-group. |
+
+## Uses
+
+- [BfSize](bf-size.md)
+
+## Used by
+
+- [BfDefaultsOptions](bf-defaults-options.md)
+- [BF_DEFAULT_VALUES](bf_default_values.md)
+- [BF_DEFAULTS](bf_defaults.md)