@bitforgehq/ui 0.3.0 → 0.3.2

package/ai/reference/bf-popover-trigger-directive.md

@@ -0,0 +1,56 @@
+# BfPopoverTriggerDirective
+
+Opens an anchored, non-modal popover panel from any element or button
+
+Directive from `@bitforgehq/ui/overlay` · since 0.3.1
+
+Opens an `ng-template` (usually a `bf-popover`) as a non-modal panel anchored to the element:
+a click (`Enter` or `Space` on a button) toggles it, focus moves to its first control, `Tab`
+moves through it and on out (closing it, past the trigger), and `Escape`, a click outside or a
+navigation to another URL path close it, returning focus to the trigger. The control it
+decorates (the host, or the first control inside it, such as a `bf-button`'s button) carries
+`aria-haspopup="dialog"`, `aria-expanded` and, while open, `aria-controls`. Export it as
+`bfPopoverTrigger` to open and close it from code or from inside the panel.
+
+```ts
+import { BfPopoverTriggerDirective } from '@bitforgehq/ui/overlay';
+```
+
+Selector: `[bfPopoverTriggerFor]`
+
+## Inputs
+
+| Name                  | Type                                                                                  | Default         | Description                                                                        |
+| --------------------- | ------------------------------------------------------------------------------------- | --------------- | ---------------------------------------------------------------------------------- |
+| `bfPopoverTriggerFor` | `TemplateRef<unknown>`                                                                | required        | The `ng-template` holding the panel (a `bf-popover`) this element opens.           |
+| `bfPopoverPlacement`  | `BfPopoverPlacement` (`'below-start' \| 'below-end' \| 'above-start' \| 'above-end'`) | `'below-start'` | Where the panel opens (flipping when it would overflow), read each time it opens.  |
+| `bfPopoverLabel`      | `string`                                                                              | `''`            | Accessible name of the panel. Empty: its first heading names it, else the trigger. |
+
+## Outputs
+
+| Name              | Payload | Description                                                                               |
+| ----------------- | ------- | ----------------------------------------------------------------------------------------- |
+| `bfPopoverOpened` | `void`  | Emits when the panel opens.                                                               |
+| `bfPopoverClosed` | `void`  | Emits when the panel closes (`Escape`, a click outside, `Tab` out, a navigation or code). |
+
+## Methods
+
+### `open(): void`
+
+Opens the panel and moves focus into it; does nothing while it is open.
+
+### `close(restoreFocus?: boolean): void`
+
+Closes the panel; does nothing while it is closed.
+
+| Parameter       | Type      | Description                                     |
+| --------------- | --------- | ----------------------------------------------- |
+| `restoreFocus?` | `boolean` | Moves focus back to the trigger (default true). |
+
+### `toggle(): void`
+
+Opens the panel when it is closed, closes it when it is open.
+
+## Uses
+
+- [BfPopoverPlacement](bf-popover-placement.md)

package/ai/reference/bf-side-panel-config.md

@@ -0,0 +1,35 @@
+# BfSidePanelConfig
+
+Options of a side panel: its data, width, modality, name and injector
+
+Interface from `@bitforgehq/ui/overlay` · since 0.3.1
+
+Options of `BfSidePanelService.open()`.
+
+```ts
+import { type BfSidePanelConfig } from '@bitforgehq/ui/overlay';
+```
+
+## Signature
+
+```ts
+interface BfSidePanelConfig<D = unknown>
+```
+
+## Properties
+
+| Name        | Type                                        | Default | Description                                                                                                                                                                           |
+| ----------- | ------------------------------------------- | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `data`      | `D`                                         |         | Injected into the content as `BF_SIDE_PANEL_DATA` (and a template's `data`).                                                                                                          |
+| `width`     | `BfSidePanelWidth` (`'sm' \| 'md' \| 'lg'`) | `'md'`  | Width of the `bf-side-panel` in the content (default `md`, 480 px), capped at the viewport.                                                                                           |
+| `modal`     | `boolean`                                   | `true`  | A modal panel (default true) has a scrim, traps focus and makes the page behind it inert; `false` keeps the page usable beside it.                                                    |
+| `ariaLabel` | `string`                                    |         | Accessible name, when the content renders no `bf-side-panel` title and no heading.                                                                                                    |
+| `injector`  | `Injector`                                  |         | Parent of the content's injector and source of its labels (default the root injector). Pass the opener's `inject(Injector)` so a feature-level `provideBfLabels()` reaches the panel. |
+
+## Uses
+
+- [BfSidePanelWidth](bf-side-panel-width.md)
+
+## Used by
+
+- [BfSidePanelService](bf-side-panel-service.md)

package/ai/reference/bf-side-panel-harness.md

@@ -0,0 +1,34 @@
+# BfSidePanelHarness
+
+Test harness for a side panel: its title, its close button and its state
+
+Class from `@bitforgehq/ui/testing` · since 0.3.1
+
+Harness for `bf-side-panel`, the panel `BfSidePanelService` opens. Side panels render in the
+CDK overlay container outside the tested component, so get it through
+`TestbedHarnessEnvironment.documentRootLoader(fixture)`.
+
+```ts
+import { BfSidePanelHarness } from '@bitforgehq/ui/testing';
+```
+
+## Signature
+
+```ts
+class BfSidePanelHarness extends ComponentHarness
+```
+
+## Methods
+
+### `getTitle(): Promise<string>`
+
+The title heading.
+
+### `close(): Promise<void>`
+
+Clicks the close button (×), which closes the side panel with no result.
+
+### `isOpen(): Promise<boolean>`
+
+Whether the side panel is open: its overlay pane is in the page and not sliding out. The pane
+is found by the panel's own `data-bf-side-panel-id`.

package/ai/reference/bf-side-panel-ref.md

@@ -0,0 +1,44 @@
+# BfSidePanelRef
+
+Handle on an open side panel that closes it and resolves with its result
+
+Class from `@bitforgehq/ui/overlay` · since 0.3.1
+
+Handle to an open side panel, returned by `BfSidePanelService.open()` and injectable in the
+panel's content (`inject(BfSidePanelRef)`). `close(result)` slides the panel out, detaches it
+and resolves `afterClosed` with `result`; later calls are ignored. Closing with `Escape`, the
+backdrop, the `bf-side-panel` close button or a navigation resolves `undefined`.
+
+```ts
+import { BfSidePanelRef } from '@bitforgehq/ui/overlay';
+```
+
+## Signature
+
+```ts
+class BfSidePanelRef<R = unknown, C = unknown>
+```
+
+## Properties
+
+| Name                | Type                      | Default | Description                                                                              |
+| ------------------- | ------------------------- | ------- | ---------------------------------------------------------------------------------------- |
+| `id`                | `string`                  |         | Unique id of the side panel (its overlay's `bf-overlay-N`).                              |
+| `afterClosed`       | `Promise<R \| undefined>` |         | Resolves with the result given to `close()`, or `undefined`, once the panel is detached. |
+| `closed`            | `Signal<boolean>`         |         | True once the panel has been detached.                                                   |
+| `componentInstance` | `C \| null`               |         | The content component; `null` for a panel opened from a template.                        |
+
+## Methods
+
+### `close(result?: R): void`
+
+Closes the panel with an optional result; ignored once closing.
+
+| Parameter | Type | Description                            |
+| --------- | ---- | -------------------------------------- |
+| `result?` | `R`  | The value `afterClosed` resolves with. |
+
+## Used by
+
+- [BfSidePanelService](bf-side-panel-service.md)
+- [BfSidePanelTemplateContext](bf-side-panel-template-context.md)

package/ai/reference/bf-side-panel-service.md

@@ -0,0 +1,43 @@
+# BfSidePanelService
+
+Opens a full-height panel from the end edge, modal or beside the page
+
+Service from `@bitforgehq/ui/overlay` · since 0.3.1
+
+Opens side panels on the overlay core: a component or template in a full-height pane that
+slides in from the inline end edge (the right, the left under `dir="rtl"`; a cross-fade under
+reduced motion), labelled by its `bf-side-panel` title, with focus moved in, `Escape` closing
+it and focus returned to the opener. A modal panel (the default) adds a scrim that closes it on
+a click, traps focus, locks document scroll and makes the page behind it `inert`, as a dialog
+does; `modal: false` keeps the page usable and scrollable beside it, and `Escape` closes it
+only while focus is inside it. A navigation to another URL path closes it. Desktop only.
+
+```ts
+import { BfSidePanelService } from '@bitforgehq/ui/overlay';
+```
+
+## Methods
+
+### `open<C, D = unknown, R = unknown>(component: Type<C>, config?: BfSidePanelConfig<D>): BfSidePanelRef<R, C>`
+
+Opens `component` as a side panel; it injects `BfSidePanelRef` and `BF_SIDE_PANEL_DATA`.
+
+| Parameter   | Type                   | Description                                                                    |
+| ----------- | ---------------------- | ------------------------------------------------------------------------------ |
+| `component` | `Type<C>`              | The component to render; it injects `BfSidePanelRef` and `BF_SIDE_PANEL_DATA`. |
+| `config?`   | `BfSidePanelConfig<D>` | The panel's data, width, modality, name and injector.                          |
+
+### `open<D = unknown, R = unknown>(template: TemplateRef<BfSidePanelTemplateContext<D, R>>, config?: BfSidePanelConfig<D>): BfSidePanelRef<R>`
+
+Opens `template` as a side panel; its context is `{ $implicit: ref, data }`.
+
+| Parameter  | Type                                            | Description                                                          |
+| ---------- | ----------------------------------------------- | -------------------------------------------------------------------- |
+| `template` | `TemplateRef<BfSidePanelTemplateContext<D, R>>` | The template to render, with the context `{ $implicit: ref, data }`. |
+| `config?`  | `BfSidePanelConfig<D>`                          | The panel's data, width, modality, name and injector.                |
+
+## Uses
+
+- [BfSidePanelConfig](bf-side-panel-config.md)
+- [BfSidePanelRef](bf-side-panel-ref.md)
+- [BfSidePanelTemplateContext](bf-side-panel-template-context.md)

package/ai/reference/bf-side-panel-template-context.md

@@ -0,0 +1,32 @@
+# BfSidePanelTemplateContext
+
+The context a template opened as a side panel receives: its ref and its data
+
+Interface from `@bitforgehq/ui/overlay` · since 0.3.1
+
+Context of a template opened with `BfSidePanelService.open()`: `let-ref` and `let-data="data"`.
+
+```ts
+import { type BfSidePanelTemplateContext } from '@bitforgehq/ui/overlay';
+```
+
+## Signature
+
+```ts
+interface BfSidePanelTemplateContext<D = unknown, R = unknown>
+```
+
+## Properties
+
+| Name        | Type                | Default  | Description                                               |
+| ----------- | ------------------- | -------- | --------------------------------------------------------- |
+| `$implicit` | `BfSidePanelRef<R>` | required | The panel's ref (`let-ref`), to close it with a result.   |
+| `data`      | `D`                 | required | The `data` the panel was opened with (`let-data="data"`). |
+
+## Uses
+
+- [BfSidePanelRef](bf-side-panel-ref.md)
+
+## Used by
+
+- [BfSidePanelService](bf-side-panel-service.md)

package/ai/reference/bf-side-panel-width.md

@@ -0,0 +1,28 @@
+# BfSidePanelWidth
+
+The side panel widths, from a 360 px detail list to a 640 px form
+
+Type from `@bitforgehq/ui/overlay` · since 0.3.1
+
+The side panel's width scale: `sm` 360 px, `md` 480 px, `lg` 640 px (22.5, 30 and 40 rem), each
+never wider than the viewport.
+
+```ts
+import { type BfSidePanelWidth } from '@bitforgehq/ui/overlay';
+```
+
+## Signature
+
+```ts
+type BfSidePanelWidth = 'sm' | 'md' | 'lg'
+```
+
+## Values
+
+- `sm`
+- `md`
+- `lg`
+
+## Used by
+
+- [BfSidePanelConfig](bf-side-panel-config.md)

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

@@ -0,0 +1,21 @@
+# BfSidebarStateService
+
+The sidebar's collapsed state, kept in storage between visits of the app
+
+Service from `@bitforgehq/ui` · since 0.3.2
+
+Whether the app's `bf-sidebar` is collapsed to an icon rail, remembered between visits: the app
+binds the sidebar's `[(collapsed)]` to `sidebarState.collapsed`. With `provideBfSidebarState()`
+every change is stored in `BF_SIDEBAR_STATE_STORAGE` under `bf-sidebar-collapsed`; without it
+the signal still holds the state but nothing is written. Storage is read in the browser only, so a
+server render starts expanded and writes nothing. The widgets never inject it.
+
+```ts
+import { BfSidebarStateService } from '@bitforgehq/ui';
+```
+
+## Properties
+
+| Name        | Type                      | Default | Description                                                                                                                   |
+| ----------- | ------------------------- | ------- | ----------------------------------------------------------------------------------------------------------------------------- |
+| `collapsed` | `WritableSignal<boolean>` |         | Whether the sidebar is collapsed: the stored state in the browser, else false. Bind it two-way to `bf-sidebar`'s `collapsed`. |

package/ai/reference/bf-sidebar-toggle-harness.md

@@ -0,0 +1,32 @@
+# BfSidebarToggleHarness
+
+Test harness for a sidebar toggle: reads and flips the collapsed sidebar
+
+Class from `@bitforgehq/ui/testing` · since 0.3.2
+
+Harness for `bf-sidebar-toggle`, the button that collapses a `bf-sidebar` to an icon rail. Its
+`label` filter matches the button's name ("Collapse sidebar" or "Expand sidebar").
+
+```ts
+import { BfSidebarToggleHarness } from '@bitforgehq/ui/testing';
+```
+
+## Signature
+
+```ts
+class BfSidebarToggleHarness extends ComponentHarness
+```
+
+## Methods
+
+### `getLabel(): Promise<string>`
+
+The button's name, which says what the next press does.
+
+### `isExpanded(): Promise<boolean>`
+
+Whether the sidebar is at full width (`aria-expanded`).
+
+### `toggle(): Promise<void>`
+
+Flips the sidebar with a click.

package/ai/reference/bf-size.md

@@ -26,8 +26,12 @@ type BfSize = 'sm' | 'md' | 'lg'
 
 - [bf-button](../components/button.md)
 - [BfButtonSize](bf-button-size.md)
+- [bf-calendar](../components/calendar.md)
 - [bf-checkbox](../components/checkbox.md)
 - [bf-chip](../components/chip.md)
+- [bf-combobox](../components/combobox.md)
+- [bf-date-input](../components/date-input.md)
+- [bf-datetime-input](../components/datetime-input.md)
 - [BfDefaults](bf-defaults.md)
 - [BfDefaultsOptions](bf-defaults-options.md)
 - [BfFieldControlState](bf-field-control-state.md)
@@ -36,10 +40,19 @@ type BfSize = 'sm' | 'md' | 'lg'
 - [bf-input](../components/input.md)
 - [bf-menu-button](../components/menu-button.md)
 - [bf-menu](../components/menu.md)
+- [bf-multi-combobox](../components/multi-combobox.md)
+- [a[bfNavItem]](../components/nav-item.md)
 - [bf-number-input](../components/number-input.md)
+- [bf-pagination](../components/pagination.md)
 - [bf-radio-group](../components/radio-group.md)
 - [bf-segmented](../components/segmented.md)
 - [BfSegmentedSize](bf-segmented-size.md)
 - [bf-select](../components/select.md)
+- [bf-sidebar-toggle](../components/sidebar-toggle.md)
+- [bf-tab-group](../components/tab-group.md)
+- [bf-table](../components/table.md)
 - [bf-textarea](../components/textarea.md)
+- [bf-theme-menu-button](../components/theme-menu-button.md)
+- [bf-theme-switch](../components/theme-switch.md)
+- [bf-time-input](../components/time-input.md)
 - [bf-toggle](../components/toggle.md)

package/ai/reference/bf-skeleton-shape.md

@@ -0,0 +1,28 @@
+# BfSkeletonShape
+
+The three skeleton shapes, text lines, a rectangle or a circle
+
+Type from `@bitforgehq/ui` · since 0.3.1
+
+The shape of a `bf-skeleton`: text lines, a rectangle (an image, a chart, a field) or a circle
+(an avatar).
+
+```ts
+import { type BfSkeletonShape } from '@bitforgehq/ui';
+```
+
+## Signature
+
+```ts
+type BfSkeletonShape = 'text' | 'rect' | 'circle'
+```
+
+## Values
+
+- `text`
+- `rect`
+- `circle`
+
+## Used by
+
+- [bf-skeleton](../components/skeleton.md)

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

@@ -0,0 +1,33 @@
+# BfStatAppearance
+
+The three stat surfaces, plain, an outlined card or a sunken tile
+
+Type from `@bitforgehq/ui` · since 0.3.2
+
+The surface of a `bf-stat`, as its `variant` input takes it: a `BfStatVariant` or tile (a
+sunken, borderless tile for a stats row inside a raised card). A new type, so `Record`s over
+the released `BfStatVariant` keep compiling.
+
+```ts
+import { type BfStatAppearance } from '@bitforgehq/ui';
+```
+
+## Signature
+
+```ts
+type BfStatAppearance = BfStatVariant | 'tile'
+```
+
+## Values
+
+- `plain`
+- `card`
+- `tile`
+
+## Uses
+
+- [BfStatVariant](bf-stat-variant.md)
+
+## Used by
+
+- [bf-stat](../components/stat.md)

package/ai/reference/bf-stat-trend-intent.md

@@ -0,0 +1,27 @@
+# BfStatTrendIntent
+
+Whether a rising or a falling figure is the good news for a stat
+
+Type from `@bitforgehq/ui` · since 0.3.1
+
+Which direction of a `bf-stat` delta is good: positive (up is good, such as revenue) or
+negative (down is good, such as costs or churn).
+
+```ts
+import { type BfStatTrendIntent } from '@bitforgehq/ui';
+```
+
+## Signature
+
+```ts
+type BfStatTrendIntent = 'positive' | 'negative'
+```
+
+## Values
+
+- `positive`
+- `negative`
+
+## Used by
+
+- [bf-stat](../components/stat.md)

package/ai/reference/bf-stat-trend.md

@@ -0,0 +1,27 @@
+# BfStatTrend
+
+The three directions of a stat's delta pill, up, down or no change
+
+Type from `@bitforgehq/ui` · since 0.3.1
+
+The direction of a `bf-stat` delta: up, down or flat (no change).
+
+```ts
+import { type BfStatTrend } from '@bitforgehq/ui';
+```
+
+## Signature
+
+```ts
+type BfStatTrend = 'up' | 'down' | 'flat'
+```
+
+## Values
+
+- `up`
+- `down`
+- `flat`
+
+## Used by
+
+- [bf-stat](../components/stat.md)

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

@@ -0,0 +1,26 @@
+# BfStatVariant
+
+The two stat surfaces, plain on its container or an outlined card tile
+
+Type from `@bitforgehq/ui` · since 0.3.1
+
+The surface of a `bf-stat`: plain (on whatever holds it) or card (its own outlined tile).
+
+```ts
+import { type BfStatVariant } from '@bitforgehq/ui';
+```
+
+## Signature
+
+```ts
+type BfStatVariant = 'plain' | 'card'
+```
+
+## Values
+
+- `plain`
+- `card`
+
+## Used by
+
+- [BfStatAppearance](bf-stat-appearance.md)

package/ai/reference/bf-tab-group-harness.md

@@ -0,0 +1,44 @@
+# BfTabGroupHarness
+
+Test harness for the tab group: reads its tabs and panel and selects a tab
+
+Class from `@bitforgehq/ui/testing` · since 0.3.1
+
+Harness for `bf-tab-group`. It works by tab label, so a test never needs the panel values.
+
+```ts
+import { BfTabGroupHarness } from '@bitforgehq/ui/testing';
+```
+
+## Signature
+
+```ts
+class BfTabGroupHarness extends ComponentHarness
+```
+
+## Methods
+
+### `getLabel(): Promise<string>`
+
+The tablist's accessible name (`label`, else the `tabGroup` label).
+
+### `getTabLabels(): Promise<string[]>`
+
+The tabs' labels, in order (without their badges).
+
+### `getSelectedLabel(): Promise<string | null>`
+
+The selected tab's label, `null` when the group has no tabs.
+
+### `selectTab(label: string): Promise<void>`
+
+Clicks the tab with this label, as a user would. Throws for an unknown label, and for a
+disabled tab (a user's click would do nothing).
+
+| Parameter | Type     | Description      |
+| --------- | -------- | ---------------- |
+| `label`   | `string` | The tab's label. |
+
+### `getPanelText(): Promise<string>`
+
+The text of the panel shown.

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

@@ -0,0 +1,26 @@
+# BfTableAlign
+
+The inline alignment of a table column, start for text or end for numbers
+
+Type from `@bitforgehq/ui` · since 0.3.1
+
+Where a `bf-table` column lines up its header and cells: `start` for text, `end` for numbers.
+
+```ts
+import { type BfTableAlign } from '@bitforgehq/ui';
+```
+
+## Signature
+
+```ts
+type BfTableAlign = 'start' | 'end'
+```
+
+## Values
+
+- `start`
+- `end`
+
+## Used by
+
+- [BfTableColumn](bf-table-column.md)

package/ai/reference/bf-table-cell-context.md

@@ -0,0 +1,24 @@
+# BfTableCellContext
+
+The row and its index that a custom table cell template receives
+
+Interface from `@bitforgehq/ui` · since 0.3.1
+
+What a `bf-table` cell template receives: the row (`let-row`) and its position in `rows`.
+
+```ts
+import { type BfTableCellContext } from '@bitforgehq/ui';
+```
+
+## Signature
+
+```ts
+interface BfTableCellContext<T>
+```
+
+## Properties
+
+| Name        | Type     | Default  | Description                                                     |
+| ----------- | -------- | -------- | --------------------------------------------------------------- |
+| `$implicit` | `T`      | required | The row the cell belongs to (`let-row`).                        |
+| `index`     | `number` | required | The row's position in the table's `rows` (`let-index="index"`). |

package/ai/reference/bf-table-cell-directive.md

@@ -0,0 +1,22 @@
+# BfTableCellDirective
+
+Custom template for the cells of one table column, with the row typed
+
+Directive from `@bitforgehq/ui` · since 0.3.1
+
+Replaces the default text of one `bf-table` column with a template, such as a badge, an avatar
+or a link. `bfTableCell` names the column's `key`; bind `bfTableCellOf` to the table's rows so
+`let-row` is typed as one of them (it is `unknown` otherwise).
+
+```ts
+import { BfTableCellDirective } from '@bitforgehq/ui';
+```
+
+Selector: `ng-template[bfTableCell]`
+
+## Inputs
+
+| Name            | Type           | Default  | Description                                                       |
+| --------------- | -------------- | -------- | ----------------------------------------------------------------- |
+| `bfTableCell`   | `string`       | required | The `key` of the column whose cells this template renders.        |
+| `bfTableCellOf` | `readonly T[]` | `[]`     | The table's rows; only types `let-row`, the table never reads it. |

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

@@ -0,0 +1,28 @@
+# BfTableColumn
+
+One table column with its row key, header label, sorting and alignment
+
+Interface from `@bitforgehq/ui` · since 0.3.1
+
+One column of a `bf-table`: the row property it shows, its header and how it behaves.
+
+```ts
+import { type BfTableColumn } from '@bitforgehq/ui';
+```
+
+## Properties
+
+| Name       | Type                                | Default   | Description                                                                           |
+| ---------- | ----------------------------------- | --------- | ------------------------------------------------------------------------------------- |
+| `key`      | `string`                            | required  | The row property the default cell shows; also the key a `bfTableCell` template names. |
+| `label`    | `string`                            | required  | The header text.                                                                      |
+| `sortable` | `boolean`                           | `false`   | Whether the header is a button that sets the table's `sort`.                          |
+| `align`    | `BfTableAlign` (`'start' \| 'end'`) | `'start'` | The inline alignment of the header and cells; `end` also sets tabular figures.        |
+
+## Uses
+
+- [BfTableAlign](bf-table-align.md)
+
+## Used by
+
+- [bf-table](../components/table.md)