@bitforgehq/ui 0.3.0 → 0.3.2

package/ai/components/time-input.md

@@ -0,0 +1,240 @@
+# bf-time-input
+
+Typed time-of-day field with a popover list of times, valued as an ISO string
+
+`BfTimeInputComponent` from `@bitforgehq/ui/overlay` · Forms · since 0.3.1
+
+## Example
+
+```ts
+import { Component, computed, signal } from '@angular/core';
+import { BfTimeInputComponent } from '@bitforgehq/ui/overlay';
+
+/**
+ * The bf-time-input overview.
+ *
+ * Live demo of `bf-time-input`: a start time typed as hour and minute (24-hour in British
+ * English) or picked from the list of times every 30 minutes, which opens scrolled to the value.
+ * The value is an ISO time string; the status line shows it.
+ */
+@Component({
+  selector: 'app-example-time-input-overview',
+  imports: [BfTimeInputComponent],
+  template: `
+    <div class="flex max-w-xs flex-col gap-3">
+      <bf-time-input label="Start" locale="en-GB" [(value)]="start" />
+      <p data-status aria-live="polite" class="text-caption text-text-muted">{{ status() }}</p>
+    </div>
+  `,
+})
+export class TimeInputOverviewExampleComponent {
+  /** The start time, 'HH:mm'; null while empty or incomplete. */
+  readonly start = signal<string | null>('09:30');
+
+  readonly status = computed(() => `Start: ${this.start() ?? 'none'}`);
+}
+```
+
+## Overview
+
+Time field typed part by part (hour, minute, optional seconds, AM/PM under a 12-hour clock)
+with a popover list of times, valued as an ISO time string.
+
+A time-of-day field typed part by part: the hour and the minute (and the seconds with `seconds`) in the locale's order and clock, with an AM/PM part under a 12-hour clock. A clock button opens a list of times every `step` minutes in a popover, scrolled to the value. The value is an ISO time string (`'14:30'`, `'14:30:05'` with seconds) on a 24-hour clock whatever the field shows, with no date and no time zone.
+
+Import `BfTimeInputComponent` from `@bitforgehq/ui/overlay` (it needs `@angular/cdk` for the popover). The parts work as in [bf-date-input](https://bitforge-ui.web.app/components/date-input); for a date and a time in one field use [bf-datetime-input](https://bitforge-ui.web.app/components/datetime-input).
+
+## When to use
+
+Use `bf-time-input` for a time of day in a form: a start time, an alarm, opening hours. Use [bf-select](https://bitforge-ui.web.app/components/select) or [bf-segmented](https://bitforge-ui.web.app/components/segmented) instead for a handful of fixed slots (morning, afternoon), and [bf-number-input](https://bitforge-ui.web.app/components/number-input) for a duration ("90 minutes"), which is not a time of day. It works in both shells; in a Capacitor app set `native`, so a phone shows its own time picker (see Native picker).
+
+## Typing a time
+
+Each part takes digits and moves on once it is complete ("7" in the hour of a 24-hour clock waits for a second digit, "3" moves on), and a part takes its value only then or when you leave it, so typing "30" minutes never passes through 03. <kbd>ArrowUp</kbd> and <kbd>ArrowDown</kbd> step a part and wrap (59 to 00), <kbd>Backspace</kbd> clears it, <kbd>ArrowLeft</kbd> and <kbd>ArrowRight</kbd> move between parts and <kbd>:</kbd> moves on. `value` is `null` while any part is empty, and `(changed)` emits the new value right after a user change.
+
+## 12-hour clock
+
+The clock follows the locale (`Intl.DateTimeFormat`'s `hourCycle`): American English counts 1 to 12 with an AM/PM part, British English and German count 0 to 23. `hourCycle` forces `h12` or `h23`. The AM/PM part takes the first letter of the locale's AM or PM name, or the arrows; the names come from `Intl`, its spinbutton name from the `timeInputDayPeriod` label. The value stays a 24-hour time: 2:30 PM is `'14:30'`, 12:05 AM is `'00:05'`.
+
+```ts
+import { Component, signal } from '@angular/core';
+import { BfTimeInputComponent } from '@bitforgehq/ui/overlay';
+
+/**
+ * A 12-hour clock.
+ *
+ * American English counts hours 1 to 12 with an AM/PM part (type A or P, or press the arrows);
+ * `hourCycle="h12"` forces it in any locale. The value stays a 24-hour ISO time: 2:30 PM is
+ * '14:30'.
+ */
+@Component({
+  selector: 'app-example-time-input-twelve-hour',
+  imports: [BfTimeInputComponent],
+  template: `<bf-time-input class="max-w-xs" label="Alarm" locale="en-US" [(value)]="alarm" />`,
+})
+export class TimeInputTwelveHourExampleComponent {
+  readonly alarm = signal<string | null>('14:30');
+}
+```
+
+## List of times
+
+The clock button opens a list of times every `step` minutes from midnight (30 by default, any number from 1 to 720), written in the locale's clock. It opens scrolled to the value (else to the next time from now) with keyboard focus on it; <kbd>ArrowUp</kbd> and <kbd>ArrowDown</kbd> move, <kbd>Enter</kbd> or a click picks a time, closes the list and returns focus to the button. `min` and `max` disable the times outside them, and a typed time outside them shows `timeInputMin` / `timeInputMax` once focus leaves the field; an incomplete time shows `timeInputInvalid`. `picker="none"` leaves the field typed only.
+
+```ts
+import { Component, signal } from '@angular/core';
+import { BfTimeInputComponent } from '@bitforgehq/ui/overlay';
+
+/**
+ * Step, min and max.
+ *
+ * `step="15"` lists a time every 15 minutes, and `min` and `max` disable the times outside
+ * opening hours; a typed time outside them shows an error once focus leaves the field.
+ */
+@Component({
+  selector: 'app-example-time-input-step',
+  imports: [BfTimeInputComponent],
+  template: `
+    <bf-time-input
+      class="max-w-xs"
+      label="Pickup"
+      locale="en-GB"
+      helpText="Between 08:00 and 18:00."
+      step="15"
+      min="08:00"
+      max="18:00"
+      [(value)]="pickup"
+    />
+  `,
+})
+export class TimeInputStepExampleComponent {
+  readonly pickup = signal<string | null>(null);
+}
+```
+
+## Seconds
+
+`seconds` adds a seconds part, and the value becomes `'HH:mm:ss'`; the list's times then end in `:00`. Leave it off unless the seconds matter (a log filter, a timer).
+
+## Native picker
+
+`native` renders an `input type="time"` with the same label, help and error text when the primary pointer is coarse (`matchMedia('(pointer: coarse)')`), and the segmented field under a mouse. `min`, `max` and `seconds` go to the native input. Recommended in the Capacitor shell: phones show their own time wheel, and typing into the parts needs a hardware keyboard.
+
+## With Signal Forms
+
+Bind the field with `[formField]`: required, touched, errors, disabled and readonly flow in, the first error shows once focus has left the field, and `focus()` focuses the first empty part. The [bf-date-input](https://bitforge-ui.web.app/components/date-input) page shows a booking form with both fields. Under `[formField]` the form owns `min` and `max`: give them through the schema with a metadata key (`metadata(path.time, OPENS, () => '09:00')` and `metadata(path.time, MIN, () => OPENS)`, with `OPENS = createMetadataKey<string | undefined>()`). In specs, `BfTimeInputHarness` from `@bitforgehq/ui/testing` types a time (`setValue('2:30 PM')`) or picks one from the list (`pickTime('14:30')`).
+
+## Desktop
+
+The field shows the `primary` border and focus ring while any part has focus, the focused part tinted `primary-soft`. The list's times tint `surface-muted` on hover; the keyboard's active time carries the focus ring while the list has keyboard focus. Fields default to `md` (40 px); `size` and `provideBfDefaults({ fieldSize })` set the step as on `bf-input` ([density guide](https://bitforge-ui.web.app/density)).
+
+## Theming
+
+- Field, parts and button: as `bf-date-input` (`surface`, `border-strong`, `primary` focus, `primary-soft` focused part, `text-muted` placeholders).
+- List: times `text` with `rounded-control` pills, hover `surface-muted`; the selected time `primary` with `on-primary`, bold; disabled times `text-disabled`; the active time `ring`.
+- Popover: `surface`, `border`, `rounded-card`, `shadow-floating`.
+
+## Accessibility
+
+The parts are a `role="group"` named by `label` (else `ariaLabel` or `ariaLabelledby`); each part is a `role="spinbutton"` named from the `timeInputHour`, `timeInputMinute`, `timeInputSecond` and `timeInputDayPeriod` labels, with `aria-valuemin`, `aria-valuemax`, `aria-valuenow` and `aria-valuetext` (the AM or PM name), and the field's `aria-invalid`, `aria-errormessage`, `aria-required`, `aria-readonly` and `aria-disabled`. The clock button is named by `timeInputOpenList`, with `aria-haspopup="dialog"`, `aria-expanded` and `aria-controls`. The list is a `role="listbox"` named by the same label, its times `role="option"` with `aria-selected` and `aria-disabled`; focus stays on the list and `aria-activedescendant` names the active time.
+
+### Keyboard
+
+| Key                                              | Where | Action                                                   |
+| ------------------------------------------------ | ----- | -------------------------------------------------------- |
+| <kbd>Tab</kbd> / <kbd>Shift</kbd>+<kbd>Tab</kbd> | Field | Moves through the parts, then to the clock button        |
+| <kbd>0</kbd>–<kbd>9</kbd>                        | Part  | Types into the part; moves on once no further digit fits |
+| <kbd>A</kbd> / <kbd>P</kbd>                      | AM/PM | Sets the day period (the first letter of its name)       |
+| <kbd>ArrowUp</kbd> / <kbd>ArrowDown</kbd>        | Part  | Next / previous value, wrapping                          |
+| <kbd>ArrowRight</kbd> / <kbd>ArrowLeft</kbd>     | Part  | Next / previous part (swapped under `dir="rtl"`)         |
+| <kbd>Backspace</kbd> / <kbd>Delete</kbd>         | Part  | Clears the part                                          |
+| <kbd>:</kbd>                                     | Part  | Moves on to the next part                                |
+| <kbd>Alt</kbd>+<kbd>ArrowDown</kbd>              | Part  | Opens the list                                           |
+| <kbd>ArrowDown</kbd> / <kbd>ArrowUp</kbd>        | List  | Next / previous time (skipping disabled ones)            |
+| <kbd>Home</kbd> / <kbd>End</kbd>                 | List  | First / last time                                        |
+| <kbd>Enter</kbd> / <kbd>Space</kbd>              | List  | Picks the active time and closes the list                |
+| <kbd>Escape</kbd>                                | List  | Closes the list, focus back on the button                |
+| <kbd>Tab</kbd>                                   | List  | Closes the list and moves on                             |
+
+## Inputs
+
+| Name             | Type                                                                | Default     | Description                                                                                                                                                          |
+| ---------------- | ------------------------------------------------------------------- | ----------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `min`            | `string \| undefined`                                               | `undefined` | The earliest valid time ('HH:mm'): earlier times show an error and are disabled in the list. Set by `[formField]`; do not bind it yourself.                          |
+| `max`            | `string \| undefined`                                               | `undefined` | The latest valid time ('HH:mm'): later times show an error and are disabled in the list. Set by `[formField]`; do not bind it yourself.                              |
+| `step`           | `number`                                                            | `30`        | Minutes between the times of the list, from midnight (1–720).                                                                                                        |
+| `seconds`        | `boolean`                                                           | `false`     | Adds a seconds part; the value becomes 'HH:mm:ss'.                                                                                                                   |
+| `hourCycle`      | `BfTimeInputHourCycle \| undefined` (`'h12' \| 'h23' \| undefined`) | `undefined` | Forces a 12-hour (`h12`, with AM/PM) or 24-hour (`h23`) clock; unset follows the locale.                                                                             |
+| `picker`         | `BfTimeInputPicker` (`'list' \| 'none'`)                            | `'list'`    | `list` adds the button that opens the list of times; `none` keeps the field typed only.                                                                              |
+| `native`         | `boolean`                                                           | `false`     | Renders the platform's time picker (`input type="time"`) under a coarse pointer (touch).                                                                             |
+| `locale`         | `string`                                                            | `''`        | BCP 47 locale of the part order, the separators, the clock and the AM/PM names; empty follows the document's `lang`, else English.                                   |
+| `size`           | `BfSize \| undefined` (`'sm' \| 'md' \| 'lg' \| undefined`)         | `undefined` | Height step: sm 32, md 40, lg 48 px; unset follows `provideBfDefaults()` (`fieldSize`, `md` by default).                                                             |
+| `label`          | `string`                                                            | `''`        | Visible label above the field.                                                                                                                                       |
+| `ariaLabel`      | `string`                                                            | `''`        | Accessible name when no visible label is rendered. Ignored when `label` is set.                                                                                      |
+| `ariaLabelledby` | `string`                                                            | `''`        | Id(s) of the element(s) that name the field when no visible label is rendered. Ignored when `label` is set.                                                          |
+| `helpText`       | `string`                                                            | `''`        | Helper text under the field.                                                                                                                                         |
+| `errorMessage`   | `string`                                                            | `''`        | Explicit error text; takes precedence over the field's own errors and Signal Forms errors.                                                                           |
+| `disabled`       | `boolean`                                                           | `false`     | Disables the field and its list button. Set by `[formField]`; do not bind it yourself.                                                                               |
+| `readonly`       | `boolean`                                                           | `false`     | Shows the time but blocks changes; the parts stay focusable and expose `aria-readonly`. Set by `[formField]`; do not bind it yourself.                               |
+| `required`       | `boolean`                                                           | `false`     | Marks the field required. Set by `[formField]`; do not bind it yourself.                                                                                             |
+| `invalid`        | `boolean`                                                           | `false`     | Field validity from Signal Forms. Set by `[formField]`; do not bind it yourself.                                                                                     |
+| `touched`        | `boolean`                                                           | `false`     | Whether the user has left the field. Set by `[formField]`; do not bind it yourself.                                                                                  |
+| `errors`         | `readonly ValidationError.WithOptionalFieldTree[]`                  | `[]`        | Validation errors from Signal Forms. Set by `[formField]`; do not bind it yourself.                                                                                  |
+| `name`           | `string`                                                            | `''`        | Native name attribute of the platform input (`native` under a coarse pointer). Set by `[formField]`; do not bind it yourself.                                        |
+| `id`             | `string`                                                            | `generated` | Field id; generated when not set.                                                                                                                                    |
+| `value`          | `string \| null`                                                    | `null`      | The time as an ISO string ('HH:mm', 'HH:mm:ss' with `seconds`), `null` while empty or incomplete; two-way bindable and bound by `[formField]`. Two-way: `[(value)]`. |
+
+## Outputs
+
+| Name      | Payload          | Description                                                                                                                               |
+| --------- | ---------------- | ----------------------------------------------------------------------------------------------------------------------------------------- |
+| `changed` | `string \| null` | Emitted with the new time right after a user change: `null` once it is cleared or incomplete.                                             |
+| `touch`   | `void`           | Emitted when focus leaves the field (not into its list), so Signal Forms marks it touched. Set by `[formField]`; do not bind it yourself. |
+
+## Methods
+
+### `focus(options?: FocusOptions): void`
+
+Focuses the first empty part (else the first part); Signal Forms calls it from
+`focusBoundControl()`.
+
+| Parameter  | Type           | Description                                                           |
+| ---------- | -------------- | --------------------------------------------------------------------- |
+| `options?` | `FocusOptions` | Passed on to the native `focus()`, such as `{ preventScroll: true }`. |
+
+### `openPicker(): void`
+
+Opens the list of times; does nothing without a picker, or while disabled or read-only.
+
+### `closePicker(): void`
+
+Closes the list of times, focus back on its button; does nothing while it is closed.
+
+## Notes
+
+### Do
+
+- Give the field a `label`.
+- Store the value as the ISO time it is, and combine it with a date only where you know the time zone.
+- Pick a `step` that matches the slots you accept (15 for appointments).
+
+### Don't
+
+- Don't use it for a duration; a time input is a time of day.
+- Don't add `seconds` for times people pick by the quarter hour.
+- Don't format the value yourself for display in the field; it follows the locale's clock.
+
+## Migration notes
+
+### 0.3.1
+
+New `bf-time-input` in `@bitforgehq/ui/overlay`: a time-of-day field typed as hour and minute
+(and second with `seconds`), with an AM/PM part under a 12-hour clock. The clock follows the
+locale; `hourCycle` (`BfTimeInputHourCycle`: `'h12'` or `'h23'`) forces one. The value is an ISO
+time on a 24-hour clock (`'HH:mm'`, `'HH:mm:ss'` with seconds). `picker` (`BfTimeInputPicker`:
+`'list'`, the default, or `'none'`) adds a button that opens a listbox of times every `step`
+minutes (30 by default), scrolled to the value; `min` and `max` disable the times outside them
+and show an error for a typed one. `native` renders `input type="time"` under a coarse pointer.
+New label keys `timeInputHour`, `timeInputMinute`, `timeInputSecond`, `timeInputDayPeriod`,
+`timeInputOpenList`, `timeInputInvalid`, `timeInputMin` and `timeInputMax`, and a
+`BfTimeInputHarness` in `@bitforgehq/ui/testing` (`setValue(text)`, `pickTime(time)`).

package/ai/components/toolbar.md

@@ -0,0 +1,354 @@
+# bf-toolbar
+
+Dense row of search, filters, view switch, result count and actions
+
+`BfToolbarComponent` from `@bitforgehq/ui` · Actions · since 0.3.1
+
+## Example
+
+```ts
+import { Component, computed, signal } from '@angular/core';
+import {
+  BfButtonComponent,
+  BfInputComponent,
+  BfSegmentedComponent,
+  BfSelectComponent,
+  BfToolbarComponent,
+  type BfSegmentOption,
+  type BfSelectOption,
+} from '@bitforgehq/ui';
+
+type ProjectStatus = 'active' | 'paused' | 'done';
+type StatusFilter = ProjectStatus | 'all';
+type View = 'list' | 'grid';
+
+interface Project {
+  readonly name: string;
+  readonly status: ProjectStatus;
+}
+
+/**
+ * The bf-toolbar overview.
+ *
+ * Live demo of `bf-toolbar`: a search field and a status filter narrow a list of projects, a
+ * view switch lays it out as a list or a grid, the toolbar's status announces the count, and a
+ * primary action adds a project. Every control in the row is `sm` from the toolbar's density.
+ */
+@Component({
+  selector: 'app-example-toolbar-overview',
+  imports: [
+    BfButtonComponent,
+    BfInputComponent,
+    BfSegmentedComponent,
+    BfSelectComponent,
+    BfToolbarComponent,
+  ],
+  template: `
+    <div class="flex flex-col gap-3">
+      <bf-toolbar label="Project filters" [status]="count()">
+        <bf-input
+          type="search"
+          ariaLabel="Search projects"
+          placeholder="Search projects"
+          class="w-full sm:w-56"
+          [(value)]="query"
+        />
+        <bf-select
+          ariaLabel="Status"
+          class="w-full sm:w-40"
+          [options]="statuses"
+          [(value)]="filter"
+        />
+        <bf-segmented bfSlot="view" label="View" [options]="views" [(value)]="view" />
+        <bf-button bfSlot="actions" (clicked)="add()">New project</bf-button>
+      </bf-toolbar>
+      <ul [class]="view() === 'grid' ? 'grid grid-cols-2 gap-2' : 'flex flex-col gap-1'">
+        @for (project of visible(); track project.name) {
+          <li class="bg-surface rounded-field text-body px-3 py-2">{{ project.name }}</li>
+        }
+      </ul>
+      <p data-status aria-live="polite" class="text-caption text-text-muted">{{ status() }}</p>
+    </div>
+  `,
+})
+export class ToolbarOverviewExampleComponent {
+  protected readonly query = signal('');
+  protected readonly filter = signal<StatusFilter | null>('all');
+  protected readonly view = signal<View | null>('list');
+  protected readonly projects = signal<readonly Project[]>([
+    { name: 'Atlas rebrand', status: 'active' },
+    { name: 'Billing revamp', status: 'active' },
+    { name: 'Carbon audit', status: 'paused' },
+    { name: 'Docs refresh', status: 'done' },
+    { name: 'Onboarding flow', status: 'active' },
+  ]);
+
+  protected readonly statuses: BfSelectOption<StatusFilter>[] = [
+    { value: 'all', label: 'All statuses' },
+    { value: 'active', label: 'Active' },
+    { value: 'paused', label: 'Paused' },
+    { value: 'done', label: 'Done' },
+  ];
+  protected readonly views: BfSegmentOption<View>[] = [
+    { value: 'list', label: 'List' },
+    { value: 'grid', label: 'Grid' },
+  ];
+
+  protected readonly visible = computed(() => {
+    const query = this.query().trim().toLowerCase();
+    const filter = this.filter() ?? 'all';
+    return this.projects().filter(
+      (p) =>
+        (filter === 'all' || p.status === filter) &&
+        (!query || p.name.toLowerCase().includes(query)),
+    );
+  });
+
+  protected readonly count = computed(() => {
+    const n = this.visible().length;
+    return n === 1 ? '1 project' : `${n} projects`;
+  });
+
+  protected readonly status = computed(
+    () => `Showing ${this.visible().length} of ${this.projects().length} · ${this.view()} view`,
+  );
+
+  protected add(): void {
+    const next = this.projects().length + 1;
+    this.projects.update((list) => [...list, { name: `Project ${next}`, status: 'active' }]);
+  }
+}
+```
+
+## Overview
+
+Row of search, filters, a view switch and trailing actions above a list or table. Every
+control projected into it is `sm` unless it sets `size` itself.
+
+A dense row above a list or table: the search field and filters, a view switch, a live result count and the trailing actions. `bf-toolbar` lays the row out, wraps it in a narrow column and makes every control in it `sm`; the controls themselves are ordinary `bf-input`, `bf-select`, `bf-chip-group`, `bf-segmented` and `bf-button`s.
+
+## When to use
+
+Use `bf-toolbar` on a desktop page for the controls that narrow or act on the collection below it: search, filters, list or grid, "New". Use [bf-action-bar](https://bitforge-ui.web.app/components/action-bar) instead for actions on a selection while it lasts. In the Capacitor shell, put the main action in [bf-header](https://bitforge-ui.web.app/components/header) actions and move filters into a [bf-sheet](https://bitforge-ui.web.app/components/sheet) instead.
+
+## Layout
+
+Project the search field and the filters as content, in the order they read. `bfSlot="view"` takes a view switch after them, and `bfSlot="actions"` the trailing actions, pushed to the inline end. Each field needs its own `ariaLabel` (or `label`), since the row shows no field labels. Bind `status` to the result count.
+
+## Status
+
+`status` renders a polite live region (`role="status"`) after the view switch, in muted caption text. Keep it short and countable ("24 results", "No matches"); it is announced each time it changes, without moving focus. The region is always in the DOM, so the first count after an empty one is announced too; while it is empty it takes no space.
+
+```ts
+import { Component, computed, signal } from '@angular/core';
+import { BfChipComponent, BfChipGroupComponent, BfToolbarComponent } from '@bitforgehq/ui';
+
+type Filter = 'all' | 'open' | 'done';
+
+interface Task {
+  readonly title: string;
+  readonly done: boolean;
+}
+
+/**
+ * A result count in the status line.
+ *
+ * The toolbar's `status` is a polite live region: picking a filter changes the count, and a
+ * screen reader announces it without moving focus.
+ */
+@Component({
+  selector: 'app-example-toolbar-status',
+  imports: [BfChipComponent, BfChipGroupComponent, BfToolbarComponent],
+  template: `
+    <bf-toolbar label="Task filters" [status]="count()">
+      <bf-chip-group label="Status" [(value)]="filter">
+        <bf-chip variant="ink" value="all">All</bf-chip>
+        <bf-chip variant="ink" value="open">Open</bf-chip>
+        <bf-chip variant="ink" value="done">Done</bf-chip>
+      </bf-chip-group>
+    </bf-toolbar>
+  `,
+})
+export class ToolbarStatusExampleComponent {
+  protected readonly filter = signal<Filter | null>('all');
+  private readonly tasks: readonly Task[] = [
+    { title: 'Draft the brief', done: true },
+    { title: 'Review the logo', done: false },
+    { title: 'Book the venue', done: false },
+  ];
+
+  protected readonly count = computed(() => {
+    const filter = this.filter() ?? 'all';
+    const n = this.tasks.filter((t) => filter === 'all' || t.done === (filter === 'done')).length;
+    return n === 1 ? '1 task' : `${n} tasks`;
+  });
+}
+```
+
+## Wrapping
+
+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';
+import {
+  BfButtonComponent,
+  BfInputComponent,
+  BfSelectComponent,
+  BfToolbarComponent,
+  type BfSelectOption,
+} from '@bitforgehq/ui';
+
+/**
+ * A toolbar that wraps.
+ *
+ * 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',
+  imports: [BfButtonComponent, BfInputComponent, BfSelectComponent, BfToolbarComponent],
+  template: `
+    <div class="max-w-sm">
+      <bf-toolbar label="Invoice filters" status="18 invoices">
+        <bf-input type="search" ariaLabel="Search invoices" placeholder="Search invoices" />
+        <bf-select ariaLabel="Customer" [options]="customers" value="all" />
+        <bf-select ariaLabel="Period" [options]="periods" value="month" />
+        <bf-button bfSlot="actions" variant="outline">Export</bf-button>
+        <bf-button bfSlot="actions">New invoice</bf-button>
+      </bf-toolbar>
+    </div>
+  `,
+})
+export class ToolbarWrappingExampleComponent {
+  protected readonly customers: BfSelectOption[] = [
+    { value: 'all', label: 'All customers' },
+    { value: 'acme', label: 'Acme' },
+  ];
+  protected readonly periods: BfSelectOption[] = [
+    { value: 'month', label: 'This month' },
+    { value: 'year', label: 'This year' },
+  ];
+}
+```
+
+## 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.
+
+Place it directly under `bf-page-header` and above the `bf-table` or `bf-list` it filters, with the page's own vertical gap (`gap-4`) between them: the page header names the page and holds its page-level actions, the toolbar holds what narrows the collection, and the count in `status` describes the rows below.
+
+## Theming
+
+The row has no surface, border or radius of its own; it sits on the page background, and each projected control themes itself.
+
+- Status text: `text-caption` in `text-muted`.
+- Layout: `gap-2` (8 px) between items and rows, in logical properties, so under `dir="rtl"` the row mirrors and the actions sit at the left end.
+
+## Accessibility
+
+The host is `role="group"`, named by `aria-label` from `label` ("Project filters"). It is a group, not `role="toolbar"`: that role promises arrow-key movement between its controls with one tab stop, and the search field needs the arrow keys to move its caret, so each control keeps its own tab stop and its own keys. Without `label` the group is left unnamed rather than given a generic default: a page has one toolbar under a heading that already names the context, and a stock name such as "Toolbar" would add noise to every focus entry without telling the user anything. Pass a `label` when the page has more than one toolbar.
+
+The `status` element is `role="status"` (an `aria-live="polite"` region), always rendered, so a changed count is read after the user's current input finishes. The toolbar sets no focus and handles no keys; <kbd>Tab</kbd> moves through the projected controls in DOM order (filters, view switch, actions).
+
+## Inputs
+
+| Name     | Type     | Default | Description                                                                            |
+| -------- | -------- | ------- | -------------------------------------------------------------------------------------- |
+| `label`  | `string` | `''`    | The group's accessible name, such as "Project filters"; unnamed when empty.            |
+| `status` | `string` | `''`    | The result count or a short state, such as "24 results", announced politely on change. |
+
+## Slots
+
+- `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, beside the status.
+
+## Notes
+
+### Do
+
+- Name each field with `ariaLabel` (or a `label`), and keep the order: search, filters, view, actions.
+- Bind `status` to the number of rows the filters leave, and update it as they change.
+
+### Don't
+
+- Don't put the page's title or page-level actions in it; they belong in `bf-page-header`.
+- Don't use it in the Capacitor shell; use `bf-header` actions and a `bf-sheet` of filters.
+
+## 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
+filters (default slot), a view switch (`bfSlot="view"`) and the trailing actions
+(`bfSlot="actions"`, kept together at the inline end). `label` names the group; `status` renders
+a polite `role="status"` live region for the result count. Its providers set
+`provideBfDefaults({ size: 'sm' })`, so every projected control and field is `sm` unless it sets
+`size` itself. Desktop only; in the Capacitor shell use `bf-header` actions and a `bf-sheet` of
+filters.