@bitforgehq/ui 0.3.0 → 0.3.2

package/ai/reference/bf-chart-card-heading-level.md

@@ -0,0 +1,26 @@
+# BfChartCardHeadingLevel
+
+Heading level of a chart card title, two on a page or three inside
+
+Type from `@bitforgehq/ui/charts` · since 0.3.1
+
+The heading level of a `bf-chart-card` title: `2` for a card on a page, `3` inside a section.
+
+```ts
+import { type BfChartCardHeadingLevel } from '@bitforgehq/ui/charts';
+```
+
+## Signature
+
+```ts
+type BfChartCardHeadingLevel = 2 | 3
+```
+
+## Values
+
+- `2`
+- `3`
+
+## Used by
+
+- [bf-chart-card](../components/chart-card.md)

package/ai/reference/bf-chart-curve.md

@@ -0,0 +1,28 @@
+# BfChartCurve
+
+The two line shapes, straight segments or a smooth monotone curve
+
+Type from `@bitforgehq/ui/charts` · since 0.3.1
+
+The line between two points of a line chart or a sparkline: straight, or a smooth monotone
+cubic curve that never overshoots the values.
+
+```ts
+import { type BfChartCurve } from '@bitforgehq/ui/charts';
+```
+
+## Signature
+
+```ts
+type BfChartCurve = 'linear' | 'smooth'
+```
+
+## Values
+
+- `linear`
+- `smooth`
+
+## Used by
+
+- [bf-line-chart](../components/line-chart.md)
+- [bf-sparkline](../components/sparkline.md)

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

@@ -0,0 +1,51 @@
+# BfChartHarness
+
+Test harness for the charts: reads the series, toggles one and reads the data table
+
+Class from `@bitforgehq/ui/testing` · since 0.3.1
+
+Harness for the `@bitforgehq/ui/charts` charts (`bf-line-chart`, `bf-bar-chart`,
+`bf-donut-chart`). It works through what a user sees: the legend's series names, its toggle
+buttons and the Show data table, so a test never reads the SVG.
+
+```ts
+import { BfChartHarness } from '@bitforgehq/ui/testing';
+```
+
+## Signature
+
+```ts
+class BfChartHarness extends ComponentHarness
+```
+
+## Methods
+
+### `getLabel(): Promise<string>`
+
+The figure's accessible name (`label`, else the chart card's title, else the `chart` label).
+
+### `getSeriesNames(): Promise<string[]>`
+
+The series (or slice) names in the legend, in order; empty for a chart of one series, which
+draws no legend.
+
+### `isSeriesShown(name: string): Promise<boolean>`
+
+Whether the legend shows the series (or slice) with this name.
+
+| Parameter | Type     | Description      |
+| --------- | -------- | ---------------- |
+| `name`    | `string` | The series name. |
+
+### `toggleSeries(name: string): Promise<void>`
+
+Clicks the legend button of the series (or slice) with this name, as a user would, to hide
+or show it. Throws for an unknown name.
+
+| Parameter | Type     | Description      |
+| --------- | -------- | ---------------- |
+| `name`    | `string` | The series name. |
+
+### `showData(): Promise<string[][]>`
+
+Opens the Show data table (if it is closed) and reads it.

package/ai/reference/bf-chart-legend-position.md

@@ -0,0 +1,30 @@
+# BfChartLegendPosition
+
+The legend positions of a chart, above or below the plot, or none
+
+Type from `@bitforgehq/ui/charts` · since 0.3.1
+
+Where a chart draws its legend: above the plot, below it, or not at all.
+
+```ts
+import { type BfChartLegendPosition } from '@bitforgehq/ui/charts';
+```
+
+## Signature
+
+```ts
+type BfChartLegendPosition = 'top' | 'bottom' | 'none'
+```
+
+## Values
+
+- `top`
+- `bottom`
+- `none`
+
+## Used by
+
+- [bf-bar-chart](../components/bar-chart.md)
+- [bf-chart-card](../components/chart-card.md)
+- [bf-donut-chart](../components/donut-chart.md)
+- [bf-line-chart](../components/line-chart.md)

package/ai/reference/bf-chart-series.md

@@ -0,0 +1,23 @@
+# BfChartSeries
+
+One named series of chart values, one per category, null for a gap
+
+Interface from `@bitforgehq/ui/charts` · since 0.3.1
+
+One named row of values in a chart, one value per category; `null` leaves a gap.
+
+```ts
+import { type BfChartSeries } from '@bitforgehq/ui/charts';
+```
+
+## Properties
+
+| Name     | Type                          | Default  | Description                                                                       |
+| -------- | ----------------------------- | -------- | --------------------------------------------------------------------------------- |
+| `name`   | `string`                      | required | The series name, shown in the legend, the tooltip and the data table.             |
+| `values` | `readonly (number \| null)[]` | required | One value per category, in the categories' order; `null` where there is no value. |
+
+## Used by
+
+- [bf-bar-chart](../components/bar-chart.md)
+- [bf-line-chart](../components/line-chart.md)

package/ai/reference/bf-chart-value-format.md

@@ -0,0 +1,23 @@
+# BfChartValueFormat
+
+Function that formats one chart value for axes, tooltips and the table
+
+Type from `@bitforgehq/ui/charts` · since 0.3.1
+
+Formats a chart value for the axis, the tooltip, the announcements and the data table.
+
+```ts
+import { type BfChartValueFormat } from '@bitforgehq/ui/charts';
+```
+
+## Signature
+
+```ts
+type BfChartValueFormat = (value: number) => string
+```
+
+## Used by
+
+- [bf-bar-chart](../components/bar-chart.md)
+- [bf-donut-chart](../components/donut-chart.md)
+- [bf-line-chart](../components/line-chart.md)

package/ai/reference/bf-color-scheme-service.md

@@ -0,0 +1,30 @@
+# BfColorSchemeService
+
+The app colour scheme choice and dark state, applied to html and stored
+
+Service from `@bitforgehq/ui` · since 0.3.1
+
+The app's colour scheme: the user's choice (system, light, dark), kept in
+`BF_COLOR_SCHEME_STORAGE` under `bf-theme`, and whether the app is dark now. With
+`provideBfColorScheme()` (or `provideBfShell()` in a Capacitor app) it toggles the `dark` class
+on `<html>` and stores every change; `prefers-color-scheme` is the source under `system` and is
+followed live. Without either, the signals still compute but nothing is written, so a page that
+merely injects the service never fights the host page's own theme. Storage and the media query are read in the browser only, so a server render
+starts at `system`, light, and writes nothing. No Capacitor: a desktop web app uses it as is,
+and the shell's `BfPlatformService.theme` and `dark` are these same signals.
+
+```ts
+import { BfColorSchemeService } from '@bitforgehq/ui';
+```
+
+## Properties
+
+| Name         | Type                            | Default | Description                                                                                       |
+| ------------ | ------------------------------- | ------- | ------------------------------------------------------------------------------------------------- |
+| `scheme`     | `WritableSignal<BfColorScheme>` |         | The user's choice, stored when `provideBfColorScheme()` is provided; set it with `scheme.set(…)`. |
+| `systemDark` | `Signal<boolean>`               |         | Whether the system prefers dark (`prefers-color-scheme: dark`), followed live.                    |
+| `dark`       | `Signal<boolean>`               |         | Whether the app is dark now: the choice, or the system's under `system`.                          |
+
+## Uses
+
+- [BfColorScheme](bf-color-scheme.md)

package/ai/reference/bf-color-scheme.md

@@ -0,0 +1,31 @@
+# BfColorScheme
+
+The colour scheme choice, following the system or forcing light or dark
+
+Type from `@bitforgehq/ui` · since 0.3.1
+
+The app's colour scheme choice: follow the system, or force light or dark.
+
+```ts
+import { type BfColorScheme } from '@bitforgehq/ui';
+```
+
+## Signature
+
+```ts
+type BfColorScheme = 'system' | 'light' | 'dark'
+```
+
+## Values
+
+- `system`
+- `light`
+- `dark`
+
+## Used by
+
+- [BfColorSchemeService](bf-color-scheme-service.md)
+- [BfPlatformService](bf-platform-service.md)
+- [BfTheme](bf-theme.md)
+- [bf-theme-menu-button](../components/theme-menu-button.md)
+- [bf-theme-switch](../components/theme-switch.md)

package/ai/reference/bf-combobox-filter.md

@@ -0,0 +1,27 @@
+# BfComboboxFilter
+
+Decides whether a combobox option matches the text typed into the field
+
+Type from `@bitforgehq/ui/overlay` · since 0.3.1
+
+Whether an option matches the typed query (the `filter` of the comboboxes). Called only for a
+query that is not empty.
+
+```ts
+import { type BfComboboxFilter } from '@bitforgehq/ui/overlay';
+```
+
+## Signature
+
+```ts
+type BfComboboxFilter<T = string> = (option: BfComboboxOption<T>, query: string) => boolean
+```
+
+## Uses
+
+- [BfComboboxOption](bf-combobox-option.md)
+
+## Used by
+
+- [bf-combobox](../components/combobox.md)
+- [bf-multi-combobox](../components/multi-combobox.md)

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

@@ -0,0 +1,89 @@
+# BfComboboxHarness
+
+Test harness for the comboboxes: types, reads and picks options and tags
+
+Class from `@bitforgehq/ui/testing` · since 0.3.1
+
+Harness for `bf-combobox` and `bf-multi-combobox`. Its option list renders in the CDK overlay
+container while open (found through the input's `aria-controls`); it works by option label, so a
+test never needs the option values. Its `label` filter matches the visible label, else the
+`aria-label`.
+
+```ts
+import { BfComboboxHarness } from '@bitforgehq/ui/testing';
+```
+
+## Signature
+
+```ts
+class BfComboboxHarness extends ComponentHarness
+```
+
+## Methods
+
+### `getLabel(): Promise<string>`
+
+The visible label without the required mark, else the `aria-label`.
+
+### `open(): Promise<void>`
+
+Opens the option list with a click into the field; does nothing while it is open.
+
+### `close(): Promise<void>`
+
+Closes the option list with `Escape`, as a user would; does nothing while it is closed.
+
+### `isOpen(): Promise<boolean>`
+
+Whether the option list is open (`aria-expanded`).
+
+### `type(query: string): Promise<void>`
+
+Replaces the field's text with `query`, key by key as a user types; the list opens filtered.
+
+| Parameter | Type     | Description       |
+| --------- | -------- | ----------------- |
+| `query`   | `string` | The text to type. |
+
+### `getOptionLabels(): Promise<string[]>`
+
+The labels of the listed options, in order, opening the list first when it is closed.
+
+### `selectOption(label: string): Promise<void>`
+
+Picks the listed option with this label with a click, opening the list first when it is
+closed. Throws for an unknown or disabled option.
+
+| Parameter | Type     | Description         |
+| --------- | -------- | ------------------- |
+| `label`   | `string` | The option's label. |
+
+### `getValueText(): Promise<string>`
+
+The field's text: the picked option's label on a `bf-combobox` (or the text being typed), the
+typed text on a `bf-multi-combobox` (its picks are tags, see `getChipLabels()`).
+
+### `getChipLabels(): Promise<string[]>`
+
+The labels of a `bf-multi-combobox`'s tags, in order; empty for a `bf-combobox`.
+
+### `removeChip(label: string): Promise<void>`
+
+Removes the tag with this label with its remove button. Throws for an unknown tag or one
+without a remove button (a disabled or read-only field).
+
+| Parameter | Type     | Description      |
+| --------- | -------- | ---------------- |
+| `label`   | `string` | The tag's label. |
+
+### `isDisabled(): Promise<boolean>`
+
+Whether the field is disabled.
+
+### `focus(): Promise<void>`
+
+Focuses the input.
+
+### `blur(): Promise<void>`
+
+Blurs the input, which closes the list and marks a bound form field touched.

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

@@ -0,0 +1,33 @@
+# BfComboboxOption
+
+One combobox choice with its value, label, description, group and disabled flag
+
+Interface from `@bitforgehq/ui/overlay` · since 0.3.1
+
+One choice of `bf-combobox` and `bf-multi-combobox`; `value` is any type (a string by default).
+
+```ts
+import { type BfComboboxOption } from '@bitforgehq/ui/overlay';
+```
+
+## Signature
+
+```ts
+interface BfComboboxOption<T = string>
+```
+
+## Properties
+
+| Name          | Type      | Default  | Description                                                                               |
+| ------------- | --------- | -------- | ----------------------------------------------------------------------------------------- |
+| `value`       | `T`       | required | The value the combobox takes when this option is picked.                                  |
+| `label`       | `string`  | required | The option's text in the list, and the field's text once it is picked.                    |
+| `description` | `string`  |          | A second, muted line under the label (an email, a role).                                  |
+| `disabled`    | `boolean` |          | Whether this option cannot be picked; it stays in the list, skipped by the arrow keys.    |
+| `group`       | `string`  |          | The heading this option is listed under; options with the same group are listed together. |
+
+## Used by
+
+- [bf-combobox](../components/combobox.md)
+- [BfComboboxFilter](bf-combobox-filter.md)
+- [bf-multi-combobox](../components/multi-combobox.md)

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

@@ -19,6 +19,8 @@ type BfCompareWith<T> = (optionValue: T, value: T) => boolean
 
 ## Used by
 
+- [bf-combobox](../components/combobox.md)
+- [bf-multi-combobox](../components/multi-combobox.md)
 - [bf-radio-group](../components/radio-group.md)
 - [bf-segmented](../components/segmented.md)
 - [bf-select](../components/select.md)

package/ai/reference/bf-date-input-harness.md

@@ -0,0 +1,67 @@
+# BfDateInputHarness
+
+Test harness for the date input: types a date or picks one in its calendar
+
+Class from `@bitforgehq/ui/testing` · since 0.3.1
+
+Harness for `bf-date-input`. It reads and types the field as a user sees it (in its locale's
+order) and picks a date through the calendar popover with `BfCalendarHarness`.
+
+```ts
+import { BfDateInputHarness } from '@bitforgehq/ui/testing';
+```
+
+## Signature
+
+```ts
+class BfDateInputHarness extends ComponentHarness
+```
+
+## Methods
+
+### `getLabel(): Promise<string>`
+
+The visible label without the required mark, else the field's `aria-label`.
+
+### `getValue(): Promise<string>`
+
+The field's text as the locale shows it ("14/10/2026"); the ISO value in native mode.
+
+### `setValue(text: string): Promise<void>`
+
+Types a date as a user would: clears the field, then types each run of digits (or letters)
+into the next part in the field's order, such as "14/10/2026" in an en-GB field. In native mode it sets the
+platform input to the ISO value.
+
+| Parameter | Type     | Description                     |
+| --------- | -------- | ------------------------------- |
+| `text`    | `string` | The date as the field shows it. |
+
+### `clear(): Promise<void>`
+
+Clears every part with `Backspace`, as a user would.
+
+### `isInvalid(): Promise<boolean>`
+
+Whether the field shows its error state (`aria-invalid` on its parts or native input).
+
+### `isDisabled(): Promise<boolean>`
+
+Whether the field is disabled.
+
+### `openPicker(): Promise<void>`
+
+Opens the calendar popover with a click on its button; throws when the field has none or it is disabled.
+
+### `isPickerOpen(): Promise<boolean>`
+
+Whether the calendar popover is open (`aria-expanded` on its button).
+
+### `pickDate(iso: string): Promise<void>`
+
+Picks a date in the calendar as a user would: opens the popover (when closed), then picks the
+day through the calendar's harness, which closes it.
+
+| Parameter | Type     | Description                                 |
+| --------- | -------- | ------------------------------------------- |
+| `iso`     | `string` | The ISO date to pick, such as '2026-11-03'. |

package/ai/reference/bf-date-input-picker.md

@@ -0,0 +1,27 @@
+# BfDateInputPicker
+
+Whether a date input offers a calendar popover besides typing
+
+Type from `@bitforgehq/ui/overlay` · since 0.3.1
+
+How `bf-date-input` picks a date besides typing: `calendar` adds a button that opens a
+`bf-calendar` in a popover, `none` keeps the field typed only.
+
+```ts
+import { type BfDateInputPicker } from '@bitforgehq/ui/overlay';
+```
+
+## Signature
+
+```ts
+type BfDateInputPicker = 'calendar' | 'none'
+```
+
+## Values
+
+- `calendar`
+- `none`
+
+## Used by
+
+- [bf-date-input](../components/date-input.md)

package/ai/reference/bf-date-time-input-harness.md

@@ -0,0 +1,76 @@
+# BfDateTimeInputHarness
+
+Test harness for the date and time input: types or picks a date and time
+
+Class from `@bitforgehq/ui/testing` · since 0.3.1
+
+Harness for `bf-datetime-input`. It reads and types the field as a user sees it and picks the
+date in the popover's calendar and the time in its list.
+
+```ts
+import { BfDateTimeInputHarness } from '@bitforgehq/ui/testing';
+```
+
+## Signature
+
+```ts
+class BfDateTimeInputHarness extends ComponentHarness
+```
+
+## Methods
+
+### `getLabel(): Promise<string>`
+
+The visible label without the required mark, else the field's `aria-label`.
+
+### `getValue(): Promise<string>`
+
+The field's text as the locale shows it ("14/10/2026, 09:30"); the ISO value in native mode.
+
+### `setValue(text: string): Promise<void>`
+
+Types a date and time as a user would: clears the field, then types each run of digits (or letters)
+into the next part in the field's order, such as "14/10/2026, 09:30" in an en-GB field. In native mode it sets the
+platform input to the ISO value.
+
+| Parameter | Type     | Description                              |
+| --------- | -------- | ---------------------------------------- |
+| `text`    | `string` | The date and time as the field shows it. |
+
+### `clear(): Promise<void>`
+
+Clears every part with `Backspace`, as a user would.
+
+### `isInvalid(): Promise<boolean>`
+
+Whether the field shows its error state (`aria-invalid` on its parts or native input).
+
+### `isDisabled(): Promise<boolean>`
+
+Whether the field is disabled.
+
+### `openPicker(): Promise<void>`
+
+Opens the popover with a click on its button; throws when the field has none or it is disabled.
+
+### `isPickerOpen(): Promise<boolean>`
+
+Whether the popover is open (`aria-expanded` on its button).
+
+### `pickDate(iso: string): Promise<void>`
+
+Picks a date in the calendar as a user would: opens the popover (when closed), then picks the
+day through the calendar's harness. The popover stays open, with focus on its time list.
+
+| Parameter | Type     | Description                                 |
+| --------- | -------- | ------------------------------------------- |
+| `iso`     | `string` | The ISO date to pick, such as '2026-11-03'. |
+
+### `pickTime(time: string): Promise<void>`
+
+Picks a time in the list as a user would: opens the popover (when closed), then clicks the
+time, which closes it. Throws for a time the list does not hold (off the `step`) or disables.
+
+| Parameter | Type     | Description                            |
+| --------- | -------- | -------------------------------------- |
+| `time`    | `string` | The ISO time to pick, such as '14:30'. |

package/ai/reference/bf-date-time-input-picker.md

@@ -0,0 +1,27 @@
+# BfDateTimeInputPicker
+
+Whether a date and time input offers a calendar and time list popover
+
+Type from `@bitforgehq/ui/overlay` · since 0.3.1
+
+How `bf-datetime-input` picks a date and time besides typing: `popover` adds a button that
+opens a calendar and a list of times side by side, `none` keeps the field typed only.
+
+```ts
+import { type BfDateTimeInputPicker } from '@bitforgehq/ui/overlay';
+```
+
+## Signature
+
+```ts
+type BfDateTimeInputPicker = 'popover' | 'none'
+```
+
+## Values
+
+- `popover`
+- `none`
+
+## Used by
+
+- [bf-datetime-input](../components/datetime-input.md)

package/ai/reference/bf-description-list-layout.md

@@ -0,0 +1,26 @@
+# BfDescriptionListLayout
+
+The two description list layouts, divided label-value rows or a grid of tiles
+
+Type from `@bitforgehq/ui` · since 0.3.1
+
+The layout of a `bf-description-list`: `rows` (label beside value, divided) or `grid` (tiles).
+
+```ts
+import { type BfDescriptionListLayout } from '@bitforgehq/ui';
+```
+
+## Signature
+
+```ts
+type BfDescriptionListLayout = 'rows' | 'grid'
+```
+
+## Values
+
+- `rows`
+- `grid`
+
+## Used by
+
+- [bf-description-list](../components/description-list.md)

package/ai/reference/bf-donut-slice.md

@@ -0,0 +1,22 @@
+# BfDonutSlice
+
+One labelled slice of a donut chart with its value
+
+Interface from `@bitforgehq/ui/charts` · since 0.3.1
+
+One slice of a `bf-donut-chart`.
+
+```ts
+import { type BfDonutSlice } from '@bitforgehq/ui/charts';
+```
+
+## Properties
+
+| Name    | Type     | Default  | Description                                                                                       |
+| ------- | -------- | -------- | ------------------------------------------------------------------------------------------------- |
+| `label` | `string` | required | The slice name, shown in the legend, the tooltip and the data table.                              |
+| `value` | `number` | required | The slice's value; its share of the total sets its angle. Zero and negative values draw no slice. |
+
+## Used by
+
+- [bf-donut-chart](../components/donut-chart.md)

package/ai/reference/bf-empty-state-heading-level.md

@@ -23,4 +23,4 @@ type BfEmptyStateHeadingLevel = 2 | 3
 
 ## Used by
 
-- [bf-empty-state](../components/empty-state.md)
+- [BfEmptyStateHeading](bf-empty-state-heading.md)