@bitforgehq/ui 0.3.1 → 0.3.3

package/ai/components/toolbar.md

@@ -187,7 +187,7 @@ export class ToolbarStatusExampleComponent {
 
 ## Wrapping
 
-The row is a wrapping flex row with an 8 px gap between items and between rows. In a narrow column the filters wrap onto new rows, and the actions wrap as one group, kept together at the inline end. Give a search field a width (`class="w-full sm:w-56"`) so it fills a phone-wide row and stays compact on a wide one.
+The row is a wrapping flex row with an 8 px gap between items and between rows. The status and the actions are one group that takes the rest of the last row: on a wide row the status follows the view switch and the actions sit at the inline end; when the group no longer fits beside the filters, it wraps onto a row of its own as a whole, with the status at the start and the actions at the end. So the actions never end up alone on a row, and they stay on the last filter row whenever the group fits there. Give a search field a width (`class="w-full sm:w-56"`) so it fills a phone-wide row and stays compact on a wide one.
 
 ```ts
 import { Component } from '@angular/core';
@@ -202,8 +202,8 @@ import {
 /**
  * A toolbar that wraps.
  *
- * In a narrow column the filters wrap onto new rows 8 px apart, and the actions move down
- * together, still at the inline end.
+ * In a narrow column the filters wrap onto new rows 8 px apart, and the status and the actions
+ * move down together: the count at the start of the last row, the actions at the inline end.
  */
 @Component({
   selector: 'app-example-toolbar-wrapping',
@@ -232,6 +232,63 @@ export class ToolbarWrappingExampleComponent {
 }
 ```
 
+## Phone width
+
+At phone width (in a desktop web app's narrow window or a narrow column) the search takes a row, the filters share the next, and the status and actions share the last row. A toolbar without actions keeps the status as a plain item after the filters.
+
+```ts
+import { Component, signal } from '@angular/core';
+import {
+  BfButtonComponent,
+  BfInputComponent,
+  BfSelectComponent,
+  BfToolbarComponent,
+  type BfSelectOption,
+} from '@bitforgehq/ui';
+
+/**
+ * A toolbar at phone width.
+ *
+ * In a phone-wide column the search fills its own row, the two filters share the next one, and
+ * the status and the Refresh action share the last row: the count at the start, the action at the
+ * end, never alone on a row of its own.
+ */
+@Component({
+  selector: 'app-example-toolbar-narrow',
+  imports: [BfButtonComponent, BfInputComponent, BfSelectComponent, BfToolbarComponent],
+  template: `
+    <div class="max-w-xs">
+      <bf-toolbar label="Order filters" [status]="count()">
+        <bf-input
+          type="search"
+          ariaLabel="Search orders"
+          placeholder="Search orders"
+          class="w-full"
+        />
+        <bf-select ariaLabel="Status" [options]="statuses" value="open" />
+        <bf-select ariaLabel="Period" [options]="periods" value="week" />
+        <bf-button bfSlot="actions" variant="outline" (clicked)="refresh()">Refresh</bf-button>
+      </bf-toolbar>
+    </div>
+  `,
+})
+export class ToolbarNarrowExampleComponent {
+  protected readonly count = signal('12 orders');
+  protected readonly statuses: BfSelectOption[] = [
+    { value: 'open', label: 'Open' },
+    { value: 'shipped', label: 'Shipped' },
+  ];
+  protected readonly periods: BfSelectOption[] = [
+    { value: 'week', label: 'This week' },
+    { value: 'month', label: 'This month' },
+  ];
+
+  protected refresh(): void {
+    this.count.set('12 orders, updated');
+  }
+}
+```
+
 ## Desktop
 
 `bf-toolbar` is a desktop pattern. Every control and field projected into it resolves its unset `size` to `sm` (32 px tall), because its `providers` set `provideBfDefaults({ size: 'sm' })` for its content; a control that sets `size` itself keeps it, and nothing outside the toolbar changes ([density guide](https://bitforge-ui.web.app/density)). Hover, the pointer cursor and the `focus-visible` ring come from each control; the row adds none of its own. Under a fine pointer each control's visual box is its hit area; under a coarse pointer the `sm` touch extensions reach up to 7.5 px past the visual edge, which the 8 px gap keeps off the neighbouring row.
@@ -262,7 +319,7 @@ The `status` element is `role="status"` (an `aria-live="polite"` region), always
 
 - `default`: The search field and the filters (bf-input, bf-select, bf-chip-group), in order.
 - `view`: A view switch after the filters, such as a bf-segmented of list and grid.
-- `actions`: The trailing actions, kept together at the inline end of the row.
+- `actions`: The trailing actions, kept together at the inline end of the row, beside the status.
 
 ## Notes
 
@@ -278,6 +335,14 @@ The `status` element is `role="status"` (an `aria-live="polite"` region), always
 
 ## Migration notes
 
+### 0.3.2
+
+On a narrow row the actions no longer end up alone on a row of their own: the status and the
+actions are now one group that takes the rest of the last row and wraps as a whole, with the
+status at the start and the actions at the inline end. The wide layout is unchanged, and a
+toolbar without actions keeps the status as a plain item of the row. New `toolbar/narrow`
+example at phone width.
+
 ### 0.3.1
 
 New `bf-toolbar` in `@bitforgehq/ui`: a wrapping `role="group"` row for the search field and

package/ai/reference/bf-app-frame-breakpoint.md

@@ -0,0 +1,27 @@
+# BfAppFrameBreakpoint
+
+The breakpoint where an app frame switches from its header bar to the sidebar
+
+Type from `@bitforgehq/ui` · since 0.3.2
+
+The viewport width from which `bf-app-frame` shows its sidebar column instead of the narrow
+header bar: Tailwind's `md` (768 px) or `lg` (1024 px).
+
+```ts
+import { type BfAppFrameBreakpoint } from '@bitforgehq/ui';
+```
+
+## Signature
+
+```ts
+type BfAppFrameBreakpoint = 'md' | 'lg'
+```
+
+## Values
+
+- `md`
+- `lg`
+
+## Used by
+
+- [bf-app-frame](../components/app-frame.md)

package/ai/reference/bf-app-frame-content-width.md

@@ -0,0 +1,29 @@
+# BfAppFrameContentWidth
+
+The maximum width of an app frame's content column, from medium to full
+
+Type from `@bitforgehq/ui` · since 0.3.2
+
+The maximum width of `bf-app-frame`'s content column: `md` 48rem, `lg` 64rem, `xl` 80rem, or
+`full` for no limit.
+
+```ts
+import { type BfAppFrameContentWidth } from '@bitforgehq/ui';
+```
+
+## Signature
+
+```ts
+type BfAppFrameContentWidth = 'md' | 'lg' | 'xl' | 'full'
+```
+
+## Values
+
+- `md`
+- `lg`
+- `xl`
+- `full`
+
+## Used by
+
+- [bf-app-frame](../components/app-frame.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)

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

@@ -0,0 +1,33 @@
+# BfEmptyStateHeading
+
+The heading level of an empty state title, one for a whole page
+
+Type from `@bitforgehq/ui` · since 0.3.2
+
+The heading level a `bf-empty-state` title takes: a `BfEmptyStateHeadingLevel`, or `1` when the
+empty state is the page itself (a not-found or no-access page). A new type, so `Record`s over
+the released `BfEmptyStateHeadingLevel` keep compiling.
+
+```ts
+import { type BfEmptyStateHeading } from '@bitforgehq/ui';
+```
+
+## Signature
+
+```ts
+type BfEmptyStateHeading = BfEmptyStateHeadingLevel | 1
+```
+
+## Values
+
+- `2`
+- `3`
+- `1`
+
+## Uses
+
+- [BfEmptyStateHeadingLevel](bf-empty-state-heading-level.md)
+
+## Used by
+
+- [bf-empty-state](../components/empty-state.md)

package/ai/reference/bf-labels.md

@@ -32,6 +32,10 @@ import { type BfLabels } from '@bitforgehq/ui';
 | `dialog`                | `string`                                      | `'Dialog'`                                                                       | A dialog's or side panel's name without an ariaLabel, a title or a heading.                                    |
 | `notifications`         | `string`                                      | `'Notifications'`                                                                | The desktop toast stack's region name.                                                                         |
 | `tableSelectAll`        | `string`                                      | `'Select all rows'`                                                              | bf-table's header checkbox, which selects or clears every row.                                                 |
+| `tableSortBy`           | `string`                                      | `'Sort by'`                                                                      | The label of a stacked bf-table's sort select.                                                                 |
+| `tableSortNone`         | `string`                                      | `'Not sorted'`                                                                   | A stacked bf-table's first sort option: rows in the order given, no column sorted.                             |
+| `tableSortAscending`    | `(column: string) => string`                  | `` (column) => `${column}, ascending` ``                                         | A stacked bf-table's sort option for a column in ascending order.                                              |
+| `tableSortDescending`   | `(column: string) => string`                  | `` (column) => `${column}, descending` ``                                        | A stacked bf-table's sort option for a column in descending order.                                             |
 | `theme`                 | `string`                                      | `'Theme'`                                                                        | bf-theme-switch's and bf-theme-menu-button's name without a label.                                             |
 | `themeSystem`           | `string`                                      | `'System'`                                                                       | The theme choice that follows the system's colour scheme.                                                      |
 | `themeLight`            | `string`                                      | `'Light'`                                                                        | The theme choice that forces the light colour scheme.                                                          |
@@ -40,6 +44,9 @@ import { type BfLabels } from '@bitforgehq/ui';
 | `breadcrumbExpand`      | `(count: number) => string`                   | ``(count) => (count === 1 ? 'Show 1 more level' : `Show ${count} more levels`)`` | bf-breadcrumb's ellipsis button, which shows the levels a `maxItems` trail hides.                              |
 | `navigation`            | `string`                                      | `'Main'`                                                                         | bf-sidebar's and bf-top-nav's navigation name.                                                                 |
 | `navBadge`              | `(count: number) => string`                   | `` (count) => `${count} new` ``                                                  | a[bfNavItem]'s announcement of its count badge.                                                                |
+| `sidebarCollapse`       | `string`                                      | `'Collapse sidebar'`                                                             | bf-sidebar-toggle's name and tooltip while the sidebar is expanded.                                            |
+| `sidebarExpand`         | `string`                                      | `'Expand sidebar'`                                                               | bf-sidebar-toggle's name and tooltip while the sidebar is an icon rail.                                        |
+| `skipToContent`         | `string`                                      | `'Skip to main content'`                                                         | bf-app-frame's skip link, the first stop of the tab order, which moves focus to the content.                   |
 | `pagination`            | `string`                                      | `'Pagination'`                                                                   | bf-pagination's navigation name.                                                                               |
 | `previousPage`          | `string`                                      | `'Previous page'`                                                                | bf-pagination's button to the previous page.                                                                   |
 | `nextPage`              | `string`                                      | `'Next page'`                                                                    | bf-pagination's button to the next page.                                                                       |

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

@@ -68,3 +68,7 @@ Focuses the native select.
 ### `blur(): Promise<void>`
 
 Blurs the native select, which marks a bound form field touched.
+
+## Used by
+
+- [BfTableHarness](bf-table-harness.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

@@ -48,6 +48,7 @@ type BfSize = 'sm' | 'md' | 'lg'
 - [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)

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-variant.md

@@ -23,4 +23,4 @@ type BfStatVariant = 'plain' | 'card'
 
 ## Used by
 
-- [bf-stat](../components/stat.md)
+- [BfStatAppearance](bf-stat-appearance.md)

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

@@ -6,7 +6,7 @@ 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).
+`sort` model holds it). It reads and drives a stacked table (`stack`) the same way.
 
 ```ts
 import { BfTableHarness } from '@bitforgehq/ui/testing';
@@ -54,6 +54,11 @@ Throws for an unknown or unsortable column.
 
 The sorted column (its `key`) and direction, from `aria-sort`.
 
+### `getSortSelect(): Promise<BfSelectHarness | null>`
+
+The Sort by select in a stacked table's bar: its first option, Not sorted (`tableSortNone`),
+sets `sort` to null and shows while it is; then each sortable column ascending and descending.
+
 ### `selectRow(index: number): Promise<void>`
 
 Checks one row's checkbox, as a user would; a selected row stays selected. Throws when the
@@ -74,4 +79,5 @@ The number of selected rows (checked row checkboxes).
 
 ## Uses
 
+- [BfSelectHarness](bf-select-harness.md)
 - [BfTableSort](bf-table-sort.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_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/provide-bf-labels.md

@@ -7,9 +7,10 @@ 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`, `tableSelectAll`, `theme`,
-`themeSystem`, `themeLight`, `themeDark`, `breadcrumb`, `breadcrumbExpand`, `navigation`,
-`navBadge`, `pagination`, `previousPage`, `nextPage`, `pageOf`, `goToPage`, `tabGroup`,
+(`loading`, `dismiss`, `tabBar`, `tabBadge`, `back`, `refreshing`, `tableSelectAll`, `tableSortBy`,
+`tableSortNone`, `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`,

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
+```