@bitforgehq/ui 0.3.0 → 0.3.2

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

@@ -0,0 +1,77 @@
+# BfTableHarness
+
+Test harness for the data table: reads rows and cells, sorts and selects rows
+
+Class from `@bitforgehq/ui/testing` · since 0.3.1
+
+Harness for `bf-table`. It works by column header text and row position, so a test never needs
+the column keys or the row keys (except `getSort()`, which returns the column's `key`, as the
+`sort` model holds it). It reads and drives a stacked table (`stack`) the same way.
+
+```ts
+import { BfTableHarness } from '@bitforgehq/ui/testing';
+```
+
+## Signature
+
+```ts
+class BfTableHarness extends ComponentHarness
+```
+
+## Methods
+
+### `getLabel(): Promise<string>`
+
+The table's name, its visually hidden caption.
+
+### `getRowCount(): Promise<number>`
+
+The number of body rows; `0` while the empty slot shows.
+
+### `getHeaderLabels(): Promise<string[]>`
+
+The column headers' text, in order, without the selection column.
+
+### `getCellText(row: number, column: string): Promise<string>`
+
+The text of one cell.
+
+| Parameter | Type     | Description                 |
+| --------- | -------- | --------------------------- |
+| `row`     | `number` | The row's position, from 0. |
+| `column`  | `string` | The column's header text.   |
+
+### `sortBy(column: string): Promise<void>`
+
+Clicks a sortable column's header, as a user would: ascending first, then descending.
+Throws for an unknown or unsortable column.
+
+| Parameter | Type     | Description               |
+| --------- | -------- | ------------------------- |
+| `column`  | `string` | The column's header text. |
+
+### `getSort(): Promise<BfTableSort | null>`
+
+The sorted column (its `key`) and direction, from `aria-sort`.
+
+### `selectRow(index: number): Promise<void>`
+
+Checks one row's checkbox, as a user would; a selected row stays selected. Throws when the
+table is not selectable or the row does not exist.
+
+| Parameter | Type     | Description                 |
+| --------- | -------- | --------------------------- |
+| `index`   | `number` | The row's position, from 0. |
+
+### `selectAll(): Promise<void>`
+
+Checks the header checkbox, as a user would, so every row is selected. Throws when the table
+is not selectable.
+
+### `getSelectedCount(): Promise<number>`
+
+The number of selected rows (checked row checkboxes).
+
+## Uses
+
+- [BfTableSort](bf-table-sort.md)

package/ai/reference/bf-table-row-key.md

@@ -0,0 +1,21 @@
+# BfTableRowKey
+
+Function that returns the unique string key of one table row
+
+Type from `@bitforgehq/ui` · since 0.3.1
+
+Returns the string that identifies a `bf-table` row in `selection` and in the `@for` track.
+
+```ts
+import { type BfTableRowKey } from '@bitforgehq/ui';
+```
+
+## Signature
+
+```ts
+type BfTableRowKey<T> = (row: T) => string
+```
+
+## Used by
+
+- [bf-table](../components/table.md)

package/ai/reference/bf-table-sort-direction.md

@@ -0,0 +1,26 @@
+# BfTableSortDirection
+
+The direction a sorted table column is in, ascending or descending
+
+Type from `@bitforgehq/ui` · since 0.3.1
+
+The direction of a sorted `bf-table` column, as `aria-sort` names it.
+
+```ts
+import { type BfTableSortDirection } from '@bitforgehq/ui';
+```
+
+## Signature
+
+```ts
+type BfTableSortDirection = 'ascending' | 'descending'
+```
+
+## Values
+
+- `ascending`
+- `descending`
+
+## Used by
+
+- [BfTableSort](bf-table-sort.md)

package/ai/reference/bf-table-sort.md

@@ -0,0 +1,27 @@
+# BfTableSort
+
+The column key and direction a table is sorted by, set by its headers
+
+Interface from `@bitforgehq/ui` · since 0.3.1
+
+The column a `bf-table` is sorted by and the direction; the consumer sorts the rows.
+
+```ts
+import { type BfTableSort } from '@bitforgehq/ui';
+```
+
+## Properties
+
+| Name        | Type                                                   | Default  | Description                     |
+| ----------- | ------------------------------------------------------ | -------- | ------------------------------- |
+| `column`    | `string`                                               | required | The `key` of the sorted column. |
+| `direction` | `BfTableSortDirection` (`'ascending' \| 'descending'`) | required | The sort direction.             |
+
+## Uses
+
+- [BfTableSortDirection](bf-table-sort-direction.md)
+
+## Used by
+
+- [bf-table](../components/table.md)
+- [BfTableHarness](bf-table-harness.md)

package/ai/reference/bf-table-stack.md

@@ -0,0 +1,29 @@
+# BfTableStack
+
+When a table stacks its rows into cards: never, when narrow, or under touch
+
+Type from `@bitforgehq/ui` · since 0.3.2
+
+When a `bf-table` renders each row as a card of label/value pairs: `never` (the default),
+`narrow` while the table is narrower than 36rem (a container query), or `coarse` under a coarse
+pointer at any width.
+
+```ts
+import { type BfTableStack } from '@bitforgehq/ui';
+```
+
+## Signature
+
+```ts
+type BfTableStack = 'never' | 'narrow' | 'coarse'
+```
+
+## Values
+
+- `never`
+- `narrow`
+- `coarse`
+
+## Used by
+
+- [bf-table](../components/table.md)

package/ai/reference/bf-theme.md

@@ -4,7 +4,8 @@ The app theme choice, following the system or forcing light or dark
 
 Type from `@bitforgehq/ui/mobile` · since 0.2.0
 
-The app theme choice: follow the system, or force light or dark.
+The app theme choice: follow the system, or force light or dark. The same type as
+`BfColorScheme` from `@bitforgehq/ui`.
 
 ```ts
 import { type BfTheme } from '@bitforgehq/ui/mobile';
@@ -13,7 +14,7 @@ import { type BfTheme } from '@bitforgehq/ui/mobile';
 ## Signature
 
 ```ts
-type BfTheme = 'system' | 'light' | 'dark'
+type BfTheme = BfColorScheme
 ```
 
 ## Values
@@ -22,6 +23,6 @@ type BfTheme = 'system' | 'light' | 'dark'
 - `light`
 - `dark`
 
-## Used by
+## Uses
 
-- [BfPlatformService](bf-platform-service.md)
+- [BfColorScheme](bf-color-scheme.md)

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

@@ -0,0 +1,67 @@
+# BfTimeInputHarness
+
+Test harness for the time input: types a time or picks one from its list
+
+Class from `@bitforgehq/ui/testing` · since 0.3.1
+
+Harness for `bf-time-input`. It reads and types the field as a user sees it and picks a time
+from the popover list.
+
+```ts
+import { BfTimeInputHarness } from '@bitforgehq/ui/testing';
+```
+
+## Signature
+
+```ts
+class BfTimeInputHarness 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:30" or "02:30 PM"); the ISO value in native mode.
+
+### `setValue(text: string): Promise<void>`
+
+Types a 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 "2:30 PM" in a 12-hour field. In native mode it sets the
+platform input to the ISO value.
+
+| Parameter | Type     | Description                     |
+| --------- | -------- | ------------------------------- |
+| `text`    | `string` | The 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 list of times with a click on its button; throws when the field has none or it is disabled.
+
+### `isPickerOpen(): Promise<boolean>`
+
+Whether the list of times is open (`aria-expanded` on its button).
+
+### `pickTime(time: string): Promise<void>`
+
+Picks a time in the list as a user would: opens the list (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-time-input-hour-cycle.md

@@ -0,0 +1,27 @@
+# BfTimeInputHourCycle
+
+A twelve-hour clock with AM and PM, or a twenty-four-hour clock
+
+Type from `@bitforgehq/ui/overlay` · since 0.3.1
+
+The clock of a time field: `h12` counts 1–12 with an AM/PM part, `h23` counts 0–23.
+
+```ts
+import { type BfTimeInputHourCycle } from '@bitforgehq/ui/overlay';
+```
+
+## Signature
+
+```ts
+type BfTimeInputHourCycle = 'h12' | 'h23'
+```
+
+## Values
+
+- `h12`
+- `h23`
+
+## Used by
+
+- [bf-datetime-input](../components/datetime-input.md)
+- [bf-time-input](../components/time-input.md)

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

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

package/ai/reference/bf-tooltip-directive.md

@@ -0,0 +1,43 @@
+# BfTooltipDirective
+
+Adds a hover and keyboard-focus tooltip to any control on desktop
+
+Directive from `@bitforgehq/ui/overlay` · since 0.3.1
+
+Shows a short `bf-tooltip` beside an element: after a 500 ms rest of a fine pointer, at once on
+keyboard focus. It hides when the pointer leaves (it stays while the pointer moves onto the
+tooltip itself), on blur and on `Escape`, and while it shows, the focusable element (the host,
+or the first control inside it, so it works on a `bf-icon-button`) is described by it
+(`aria-describedby`). Nothing shows under a coarse pointer (touch), so never put information
+only in a tooltip. The tooltip flips to the opposite side when it would overflow the viewport.
+
+```ts
+import { BfTooltipDirective } from '@bitforgehq/ui/overlay';
+```
+
+Selector: `[bfTooltip]`
+
+## Inputs
+
+| Name                 | Type                                                           | Default  | Description                                                                      |
+| -------------------- | -------------------------------------------------------------- | -------- | -------------------------------------------------------------------------------- |
+| `bfTooltip`          | `string`                                                       | required | The tooltip's text; empty shows no tooltip.                                      |
+| `bfTooltipPlacement` | `BfTooltipPlacement` (`'top' \| 'bottom' \| 'start' \| 'end'`) | `'top'`  | The side it shows on (flipping when it would overflow), read each time it shows. |
+
+## Methods
+
+### `isShown(): boolean`
+
+Whether the tooltip is showing.
+
+### `show(): void`
+
+Shows the tooltip now (no delay). Does nothing under a coarse pointer or without text.
+
+### `hide(): void`
+
+Hides the tooltip now and cancels a pending show.
+
+## Uses
+
+- [BfTooltipPlacement](bf-tooltip-placement.md)

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

@@ -0,0 +1,43 @@
+# BfTooltipHarness
+
+Test harness for a tooltip: shows it, reads its text and whether it shows
+
+Class from `@bitforgehq/ui/testing` · since 0.3.1
+
+Harness for an element with a `[bfTooltip]`. The tooltip renders in the CDK overlay container
+only while it shows, so `show()` focuses the element (the tooltip shows at once on keyboard
+focus; a 500 ms hover would need real time) and `getText()` reads the `bf-tooltip` its control
+is described by. Its `label` filter matches the element's accessible name (`aria-label`, else
+its text). Under a coarse pointer no tooltip shows.
+
+```ts
+import { BfTooltipHarness } from '@bitforgehq/ui/testing';
+```
+
+## Signature
+
+```ts
+class BfTooltipHarness extends ComponentHarness
+```
+
+## Methods
+
+### `getLabel(): Promise<string>`
+
+The element's accessible name: its control's `aria-label`, else its text.
+
+### `show(): Promise<void>`
+
+Shows the tooltip by focusing the element (or the first control inside it).
+
+### `hide(): Promise<void>`
+
+Hides the tooltip by moving focus off the element.
+
+### `isOpen(): Promise<boolean>`
+
+Whether the tooltip shows.
+
+### `getText(): Promise<string>`
+
+The tooltip's text, showing it first when it is hidden.

package/ai/reference/bf-tooltip-placement.md

@@ -0,0 +1,28 @@
+# BfTooltipPlacement
+
+Which side of its element a tooltip sits on: top, bottom, start or end
+
+Type from `@bitforgehq/ui/overlay` · since 0.3.1
+
+Which side of its element a tooltip sits on; `start` and `end` follow the text direction.
+
+```ts
+import { type BfTooltipPlacement } from '@bitforgehq/ui/overlay';
+```
+
+## Signature
+
+```ts
+type BfTooltipPlacement = 'top' | 'bottom' | 'start' | 'end'
+```
+
+## Values
+
+- `top`
+- `bottom`
+- `start`
+- `end`
+
+## Used by
+
+- [BfTooltipDirective](bf-tooltip-directive.md)

package/ai/reference/bf_color_scheme_storage.md

@@ -0,0 +1,20 @@
+# BF_COLOR_SCHEME_STORAGE
+
+Injection token for the store that keeps the colour scheme choice between visits
+
+Injection token from `@bitforgehq/ui` · since 0.3.1
+
+Where `BfColorSchemeService` keeps the colour scheme choice (the key `bf-theme`): `localStorage`
+when it is available, otherwise an in-memory map. Provide another store (a native preferences
+plugin, or an in-memory one in tests) to keep the choice elsewhere. `BF_THEME_STORAGE` from
+`@bitforgehq/ui/mobile` is this same token.
+
+```ts
+import { BF_COLOR_SCHEME_STORAGE } from '@bitforgehq/ui';
+```
+
+## Signature
+
+```ts
+const BF_COLOR_SCHEME_STORAGE: InjectionToken<Pick<Storage, "getItem" | "setItem">>
+```

package/ai/reference/bf_side_panel_data.md

@@ -0,0 +1,17 @@
+# BF_SIDE_PANEL_DATA
+
+Injection token carrying the data a side panel was opened with, for its content
+
+Injection token from `@bitforgehq/ui/overlay` · since 0.3.1
+
+The `data` passed to `BfSidePanelService.open()`, injectable in the panel's content.
+
+```ts
+import { BF_SIDE_PANEL_DATA } from '@bitforgehq/ui/overlay';
+```
+
+## Signature
+
+```ts
+const BF_SIDE_PANEL_DATA: InjectionToken<unknown>
+```

package/ai/reference/bf_sidebar_state_storage.md

@@ -0,0 +1,20 @@
+# BF_SIDEBAR_STATE_STORAGE
+
+Injection token for the store that keeps the collapsed sidebar between visits
+
+Injection token from `@bitforgehq/ui` · since 0.3.2
+
+Where `BfSidebarStateService` keeps whether the sidebar is collapsed (the key
+`bf-sidebar-collapsed`, `'true'` or `'false'`): `localStorage` when it is available, otherwise
+an in-memory map. Provide another store (`sessionStorage`, or an in-memory one in tests) to keep
+it elsewhere.
+
+```ts
+import { BF_SIDEBAR_STATE_STORAGE } from '@bitforgehq/ui';
+```
+
+## Signature
+
+```ts
+const BF_SIDEBAR_STATE_STORAGE: InjectionToken<Pick<Storage, "getItem" | "setItem">>
+```

package/ai/reference/bf_theme_storage.md

@@ -6,7 +6,9 @@ Injection token from `@bitforgehq/ui/mobile` · since 0.3.0
 
 Where `BfPlatformService` keeps the theme choice (the key `bf-theme`): `localStorage` when it is
 available, otherwise an in-memory map. Provide another store (a native preferences plugin, or an
-in-memory one in tests, as `provideBfShellTesting()` does) to keep the choice elsewhere.
+in-memory one in tests, as `provideBfShellTesting()` does) to keep the choice elsewhere. It is
+the same token as `BF_COLOR_SCHEME_STORAGE` from `@bitforgehq/ui`, which `BfColorSchemeService`
+reads, so providing either one moves the choice for both.
 
 ```ts
 import { BF_THEME_STORAGE } from '@bitforgehq/ui/mobile';

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

@@ -0,0 +1,20 @@
+# provideBfColorScheme
+
+Applies the stored colour scheme choice to html, for desktop web apps
+
+Function from `@bitforgehq/ui` · since 0.3.1
+
+Lets `BfColorSchemeService` own the app's colour scheme: it toggles `dark` on `<html>`, follows
+`prefers-color-scheme` under `system` and stores the choice (key `bf-theme`). For a desktop web
+app; a Capacitor app gets it from `provideBfShell()`. Add it to `ApplicationConfig.providers`
+and switch with `inject(BfColorSchemeService).scheme.set('dark')`.
+
+```ts
+import { provideBfColorScheme } from '@bitforgehq/ui';
+```
+
+## Signature
+
+```ts
+function provideBfColorScheme(): EnvironmentProviders
+```

package/ai/reference/provide-bf-labels.md

@@ -7,10 +7,19 @@ Function from `@bitforgehq/ui` · since 0.3.0
 Replaces built-in strings, merged over the parent's (validation merged key by key); a key left
 out or set to `undefined` keeps the parent's string. In `ApplicationConfig.providers` it covers
 every string. In a component's `providers` it covers that sub-tree's widgets and form controls
-(`loading`, `dismiss`, `tabBar`, `tabBadge`, `back`, `refreshing`, `validation`); the overlay
-services (`ok`, `cancel`, `actions`, `sheet`, `modal`, `close`, `expand`, `collapse`,
-`sheetPosition`, `dialog`, `notifications`) are
-root singletons and pick it up only when the caller passes its injector:
+(`loading`, `dismiss`, `tabBar`, `tabBadge`, `back`, `refreshing`, `tableSelectAll`, `tableSortBy`,
+`tableSortAscending`, `tableSortDescending`, `theme`, `themeSystem`, `themeLight`, `themeDark`,
+`breadcrumb`, `breadcrumbExpand`, `navigation`, `navBadge`, `sidebarCollapse`, `sidebarExpand`,
+`skipToContent`, `pagination`, `previousPage`, `nextPage`, `pageOf`, `goToPage`, `tabGroup`,
+`calendarPreviousMonth`, `calendarNextMonth`, `calendarChooseMonth`, `calendarChooseYear`,
+`statTrendUp`, `statTrendDown`, `statTrendFlat`, `comboboxEmpty`, `comboboxRemove`,
+`dateInputDay`, `dateInputMonth`, `dateInputYear`, `dateInputOpenCalendar`, `dateInputInvalid`,
+`dateInputUnavailable`, `timeInputHour`, `timeInputMinute`, `timeInputSecond`,
+`timeInputDayPeriod`, `timeInputOpenList`, `timeInputInvalid`, `timeInputMin`, `timeInputMax`,
+`chart`, `chartLegend`, `chartValues`, `chartShowData`, `chartHideData`, `chartCategory`,
+`chartValue`, `chartEmpty`, `chartError`, `validation`); the overlay services (`ok`, `cancel`,
+`actions`, `sheet`, `modal`, `close`, `expand`, `collapse`, `sheetPosition`, `dialog`,
+`notifications`) are root singletons and pick it up only when the caller passes its injector:
 `open(…, { injector: inject(Injector) })`.
 
 ```ts

package/ai/reference/provide-bf-sidebar-state.md

@@ -0,0 +1,20 @@
+# provideBfSidebarState
+
+Remembers the collapsed sidebar between visits, for desktop web apps
+
+Function from `@bitforgehq/ui` · since 0.3.2
+
+Lets `BfSidebarStateService` remember the collapsed sidebar: it stores every change of its
+`collapsed` signal (key `bf-sidebar-collapsed`, `localStorage` in the browser), so the app opens
+with the sidebar as the user left it. Add it to `ApplicationConfig.providers` and bind the
+sidebar's `[(collapsed)]` to `sidebarState.collapsed`.
+
+```ts
+import { provideBfSidebarState } from '@bitforgehq/ui';
+```
+
+## Signature
+
+```ts
+function provideBfSidebarState(): EnvironmentProviders
+```

package/ai/reference/slide-in-from-end.md

@@ -0,0 +1,24 @@
+# slideInFromEnd
+
+Slides an element in from the inline end, the enter animation of a side panel
+
+Function from `@bitforgehq/ui/overlay` · since 0.3.1
+
+Slides `el` in from beyond the inline end edge of the viewport (the right, the left under
+`dir="rtl"`) by its own width: the enter animation of a side panel.
+
+```ts
+import { slideInFromEnd } from '@bitforgehq/ui/overlay';
+```
+
+## Signature
+
+```ts
+function slideInFromEnd(el: HTMLElement): Animation
+```
+
+## Parameters
+
+| Parameter | Type          | Description                                        |
+| --------- | ------------- | -------------------------------------------------- |
+| `el`      | `HTMLElement` | The element to animate, usually the overlay panel. |

package/ai/reference/slide-out-to-end.md

@@ -0,0 +1,24 @@
+# slideOutToEnd
+
+Slides an element out past the inline end, the exit animation of a side panel
+
+Function from `@bitforgehq/ui/overlay` · since 0.3.1
+
+Slides `el` out past the inline end edge of the viewport by its own width (the reverse of
+`slideInFromEnd`): the exit animation of a side panel.
+
+```ts
+import { slideOutToEnd } from '@bitforgehq/ui/overlay';
+```
+
+## Signature
+
+```ts
+function slideOutToEnd(el: HTMLElement): Animation
+```
+
+## Parameters
+
+| Parameter | Type          | Description                                        |
+| --------- | ------------- | -------------------------------------------------- |
+| `el`      | `HTMLElement` | The element to animate, usually the overlay panel. |