@bitforgehq/ui 0.3.0 → 0.3.1

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

@@ -0,0 +1,36 @@
+# BfBadgeAppearance
+
+Every badge tone, the five variants plus the informational info tone
+
+Type from `@bitforgehq/ui` · since 0.3.1
+
+Every tone the `variant` input of a `bf-badge` takes: the five `BfBadgeVariant` tones plus
+`info`, for an informational label such as a category. A new type, so `Record`s and exhaustive
+switches over `BfBadgeVariant` keep compiling.
+
+```ts
+import { type BfBadgeAppearance } from '@bitforgehq/ui';
+```
+
+## Signature
+
+```ts
+type BfBadgeAppearance = BfBadgeVariant | 'info'
+```
+
+## Values
+
+- `neutral`
+- `primary`
+- `success`
+- `warning`
+- `danger`
+- `info`
+
+## Uses
+
+- [BfBadgeVariant](bf-badge-variant.md)
+
+## Used by
+
+- [bf-badge](../components/badge.md)

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

@@ -26,4 +26,4 @@ type BfBadgeVariant = 'neutral' | 'primary' | 'success' | 'warning' | 'danger'
 
 ## Used by
 
-- [bf-badge](../components/badge.md)
+- [BfBadgeAppearance](bf-badge-appearance.md)

package/ai/reference/bf-bar-chart-orientation.md

@@ -0,0 +1,27 @@
+# BfBarChartOrientation
+
+The two bar directions, vertical columns or horizontal bars
+
+Type from `@bitforgehq/ui/charts` · since 0.3.1
+
+The direction of a `bf-bar-chart`'s bars: up from a horizontal baseline, or along from a
+vertical one (for long category names or many categories).
+
+```ts
+import { type BfBarChartOrientation } from '@bitforgehq/ui/charts';
+```
+
+## Signature
+
+```ts
+type BfBarChartOrientation = 'vertical' | 'horizontal'
+```
+
+## Values
+
+- `vertical`
+- `horizontal`
+
+## Used by
+
+- [bf-bar-chart](../components/bar-chart.md)

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

@@ -0,0 +1,36 @@
+# BfButtonAppearance
+
+Every button style, the five variants plus the quiet neutral ghost
+
+Type from `@bitforgehq/ui` · since 0.3.1
+
+Every value the `variant` input of a `bf-button` takes: the five `BfButtonVariant` styles plus
+`ghost`, the quiet neutral one. A new type, so `Record`s and exhaustive switches over
+`BfButtonVariant` keep compiling.
+
+```ts
+import { type BfButtonAppearance } from '@bitforgehq/ui';
+```
+
+## Signature
+
+```ts
+type BfButtonAppearance = BfButtonVariant | 'ghost'
+```
+
+## Values
+
+- `primary`
+- `tonal`
+- `outline`
+- `text`
+- `danger`
+- `ghost`
+
+## Uses
+
+- [BfButtonVariant](bf-button-variant.md)
+
+## Used by
+
+- [bf-button](../components/button.md)

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

@@ -26,4 +26,4 @@ type BfButtonVariant = 'primary' | 'tonal' | 'outline' | 'text' | 'danger'
 
 ## Used by
 
-- [bf-button](../components/button.md)
+- [BfButtonAppearance](bf-button-appearance.md)

package/ai/reference/bf-calendar-disabled-date.md

@@ -0,0 +1,23 @@
+# BfCalendarDisabledDate
+
+A function that marks an ISO date as not pickable in a calendar
+
+Type from `@bitforgehq/ui` · since 0.3.1
+
+Tells `bf-calendar` which dates cannot be picked, such as weekends or booked days.
+
+```ts
+import { type BfCalendarDisabledDate } from '@bitforgehq/ui';
+```
+
+## Signature
+
+```ts
+type BfCalendarDisabledDate = (iso: string) => boolean
+```
+
+## Used by
+
+- [bf-calendar](../components/calendar.md)
+- [bf-date-input](../components/date-input.md)
+- [bf-datetime-input](../components/datetime-input.md)

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

@@ -0,0 +1,51 @@
+# BfCalendarHarness
+
+Test harness for the calendar: reads the month and picks a date by ISO string
+
+Class from `@bitforgehq/ui/testing` · since 0.3.1
+
+Harness for `bf-calendar`. It works with ISO dates ('YYYY-MM-DD'), as the calendar's value
+does, and drives it as a user would: `selectDate()` jumps to another month through the month
+and year views, then clicks the day.
+
+```ts
+import { BfCalendarHarness } from '@bitforgehq/ui/testing';
+```
+
+## Signature
+
+```ts
+class BfCalendarHarness extends ComponentHarness
+```
+
+## Methods
+
+### `getLabel(): Promise<string>`
+
+The calendar's accessible name (`label`, else `ariaLabel`); it is not rendered visibly.
+
+### `getMonthLabel(): Promise<string>`
+
+The shown month and year as the header writes them, in the calendar's locale.
+
+### `getSelected(): Promise<string | null>`
+
+The picked date while it is in the shown month.
+
+### `nextMonth(): Promise<void>`
+
+Clicks the next-month button. Throws when it is disabled (the month is past `max`).
+
+### `previousMonth(): Promise<void>`
+
+Clicks the previous-month button. Throws when it is disabled (the month is before `min`).
+
+### `selectDate(iso: string): Promise<void>`
+
+Picks a date as a user would: when it is in another month, opens the month view, then the
+year view, clicks its year and month, then clicks the day. Throws for an invalid date, one
+the views do not list, and a disabled date or calendar.
+
+| Parameter | Type     | Description                                 |
+| --------- | -------- | ------------------------------------------- |
+| `iso`     | `string` | The ISO date to pick, such as '2026-11-03'. |

package/ai/reference/bf-calendar-weekday.md

@@ -0,0 +1,31 @@
+# BfCalendarWeekday
+
+A weekday number from 0 for Sunday to 6 for Saturday, as Date counts
+
+Type from `@bitforgehq/ui` · since 0.3.1
+
+A weekday as `Date.getDay()` counts it: 0 Sunday, 1 Monday … 6 Saturday.
+
+```ts
+import { type BfCalendarWeekday } from '@bitforgehq/ui';
+```
+
+## Signature
+
+```ts
+type BfCalendarWeekday = 0 | 1 | 2 | 3 | 4 | 5 | 6
+```
+
+## Values
+
+- `0`
+- `1`
+- `2`
+- `3`
+- `4`
+- `5`
+- `6`
+
+## Used by
+
+- [bf-calendar](../components/calendar.md)

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)