@bitforgehq/ui 0.3.0 → 0.3.1

package/ai/components/page-header.md

@@ -0,0 +1,237 @@
+# bf-page-header
+
+Desktop page header with breadcrumb, title, subtitle, badges and a row of actions
+
+`BfPageHeaderComponent` from `@bitforgehq/ui` · Navigation · since 0.3.1
+
+## Example
+
+```ts
+import { Component, signal } from '@angular/core';
+import { RouterLink } from '@angular/router';
+import {
+  BfBadgeComponent,
+  BfBreadcrumbComponent,
+  BfBreadcrumbItemComponent,
+  BfButtonComponent,
+  BfPageHeaderComponent,
+} from '@bitforgehq/ui';
+import { BfIconComponent } from '@bitforgehq/ui/icons';
+import {
+  BfMenuButtonComponent,
+  BfMenuComponent,
+  BfMenuItemDirective,
+} from '@bitforgehq/ui/overlay';
+import { Ellipsis, Plus } from 'lucide';
+
+/**
+ * The bf-page-header overview.
+ *
+ * Live demo of `bf-page-header`: a breadcrumb above the page title, a subtitle, two badges, and
+ * the actions (a ghost Share, a primary New task and an icon-only "More actions" menu button)
+ * that report to the result line and wrap under the title in a narrow window.
+ */
+@Component({
+  selector: 'app-example-page-header-overview',
+  imports: [
+    RouterLink,
+    BfBadgeComponent,
+    BfBreadcrumbComponent,
+    BfBreadcrumbItemComponent,
+    BfButtonComponent,
+    BfIconComponent,
+    BfMenuButtonComponent,
+    BfMenuComponent,
+    BfMenuItemDirective,
+    BfPageHeaderComponent,
+  ],
+  template: `
+    <div class="flex flex-col gap-3">
+      <bf-page-header
+        title="Atlas rebrand"
+        subtitle="12 of 18 tasks done · due Friday"
+        [headingLevel]="2"
+      >
+        <bf-breadcrumb bfSlot="breadcrumb" label="Page header breadcrumb">
+          @for (crumb of trail; track crumb.path) {
+            <li bfBreadcrumbItem>
+              <a [routerLink]="crumb.path">{{ crumb.label }}</a>
+            </li>
+          }
+          <li bfBreadcrumbItem>Atlas rebrand</li>
+        </bf-breadcrumb>
+        <bf-badge bfSlot="meta" variant="success">On track</bf-badge>
+        <bf-badge bfSlot="meta" variant="info">Design</bf-badge>
+        <bf-button bfSlot="actions" variant="ghost" (clicked)="status.set('Shared.')"
+          >Share</bf-button
+        >
+        <bf-button bfSlot="actions" (clicked)="status.set('New task.')">
+          <bf-icon bfSlot="icon-start" [icon]="plus" />
+          New task
+        </bf-button>
+        <bf-menu-button
+          bfSlot="actions"
+          [menu]="more"
+          iconOnly
+          label="More actions"
+          variant="text"
+          placement="below-end"
+        >
+          <bf-icon [icon]="ellipsis" />
+        </bf-menu-button>
+      </bf-page-header>
+      <p data-status aria-live="polite" class="text-caption text-text-muted">{{ status() }}</p>
+    </div>
+
+    <ng-template #more>
+      <bf-menu>
+        <button bfMenuItem (triggered)="status.set('Renamed.')">Rename</button>
+        <button bfMenuItem (triggered)="status.set('Archived.')">Archive</button>
+      </bf-menu>
+    </ng-template>
+  `,
+})
+export class PageHeaderOverviewExampleComponent {
+  protected readonly plus = Plus;
+  protected readonly ellipsis = Ellipsis;
+  protected readonly status = signal('Pick an action.');
+  protected readonly trail: readonly { path: string; label: string }[] = [
+    { path: '/', label: 'Home' },
+    { path: '/components', label: 'Projects' },
+  ];
+}
+```
+
+## Overview
+
+The top of a desktop page: a breadcrumb above, then the page title with its subtitle and
+badges, and the page's actions at the inline end, wrapping under the title in a narrow window.
+
+The top of a desktop page: a breadcrumb above, the page title with an optional subtitle and badges, and the page's actions at the inline end. `bf-page-header` lays out what you project; it draws nothing of its own.
+
+`bf-page-header` and the shell's [bf-header](https://bitforge-ui.web.app/components/header) are two siblings, not one shell-aware widget. A shell-aware mode would need the root entry to read the shell's platform and scroll state (a service and an import of `@bitforgehq/ui/mobile`, both forbidden in a root widget), and the large-title collapse and the scroll-under surface depend on `bf-content`, which a desktop page does not have. The two share the slot names that mean the same thing.
+
+## When to use
+
+Use `bf-page-header` once at the top of every page of a desktop web app, and with `headingLevel` 2 for a section further down a long page. In the Capacitor shell use [bf-header](https://bitforge-ui.web.app/components/header) instead (large title, scroll-under surface).
+
+## Basic usage
+
+Set `title` and `subtitle`, put the trail in the `breadcrumb` slot, badges in `meta` and buttons in `actions`. The main action is a primary [bf-button](https://bitforge-ui.web.app/components/button), secondary ones `ghost` or `outline`, and the rest go into an icon-only [bf-menu-button](https://bitforge-ui.web.app/components/menu-button) labelled "More actions". In a narrow window the actions wrap under the title. The example at the top of this page shows all of them.
+
+## Badges and rich titles
+
+The `meta` slot sits beside the title in a wrapping row, so badges drop under a long title instead of squeezing it. When the title needs more than text, leave `title` empty and project the content into the `title` slot; it renders inside the heading.
+
+```ts
+import { Component } from '@angular/core';
+import { BfBadgeComponent, BfPageHeaderComponent } from '@bitforgehq/ui';
+
+/**
+ * Badges beside the title.
+ *
+ * The `meta` slot holds badges (and other short facts) beside the title; they wrap under it when
+ * the title is long or the window narrow. The `title` slot takes rich title content when the
+ * plain `title` input is not enough.
+ */
+@Component({
+  selector: 'app-example-page-header-meta',
+  imports: [BfBadgeComponent, BfPageHeaderComponent],
+  template: `
+    <div class="flex flex-col gap-8">
+      <bf-page-header title="Quarterly brand refresh for the Atlas launch" [headingLevel]="2">
+        <bf-badge bfSlot="meta" variant="warning">At risk</bf-badge>
+        <bf-badge bfSlot="meta" variant="info">Design</bf-badge>
+        <bf-badge bfSlot="meta">Q4</bf-badge>
+      </bf-page-header>
+      <bf-page-header subtitle="Version 3, edited today" [headingLevel]="2">
+        <span bfSlot="title">Atlas rebrand <span class="text-text-muted">/ Brand book</span></span>
+        <bf-badge bfSlot="meta" variant="primary">Draft</bf-badge>
+      </bf-page-header>
+    </div>
+  `,
+})
+export class PageHeaderMetaExampleComponent {}
+```
+
+## Heading level
+
+The title is the page's `h1`. Set `headingLevel` to `2` for a header that opens a section of a page that already has one. The examples on this page use `2`, because the docs page has its own `h1`.
+
+```ts
+import { Component } from '@angular/core';
+import { BfButtonComponent, BfPageHeaderComponent } from '@bitforgehq/ui';
+
+/**
+ * A section header with an h2.
+ *
+ * The page's own header keeps the `h1`; a header for a section further down the same page sets
+ * `headingLevel` to `2`, so the page outline stays in order. (Every example on this docs page is
+ * at level 2, because the docs page has its own `h1`.)
+ */
+@Component({
+  selector: 'app-example-page-header-heading-level',
+  imports: [BfButtonComponent, BfPageHeaderComponent],
+  template: `
+    <div class="flex flex-col gap-8">
+      <bf-page-header title="Milestones" subtitle="3 upcoming" [headingLevel]="2">
+        <bf-button bfSlot="actions" variant="outline" size="sm">Add milestone</bf-button>
+      </bf-page-header>
+    </div>
+  `,
+})
+export class PageHeaderHeadingLevelExampleComponent {}
+```
+
+## Desktop
+
+`bf-page-header` is for desktop web pages only: it has no large-title collapse, no scroll-under surface and no safe-area padding. It sits at the top of the page's main column, under the app's top nav or beside its sidebar. On a nested page put a `bf-breadcrumb` in its `breadcrumb` slot; above a list or table, the page's `bf-toolbar` (search, filters, view switch) follows it as its own row, not inside the `actions` slot, which holds only actions on the page as a whole. Every empty slot collapses, so a header with only a title takes one line. Hover, focus and density come from the controls you project.
+
+## Theming
+
+- Title: `text-title` type, `text` color. Subtitle: `text-body` type, `text-muted` color.
+- The header adds no background, border or shadow; the projected breadcrumb, badges and buttons theme themselves.
+
+The actions row sits at the inline end: on the right, and on the left under `dir="rtl"`.
+
+## Accessibility
+
+The host renders a `<header>`; the title is an `<h1>` by default and an `<h2>` when `headingLevel` is `2`, so keep one `h1` per page. The subtitle is a plain paragraph after the heading. The header handles no keys and moves no focus: the breadcrumb's links and the actions keep their own names and keyboard behaviour, in reading order (breadcrumb, title, badges, actions). Give an icon-only action a `label`.
+
+## Inputs
+
+| Name           | Type                                  | Default | Description                                                                     |
+| -------------- | ------------------------------------- | ------- | ------------------------------------------------------------------------------- |
+| `title`        | `string`                              | `''`    | The page title, rendered as the heading; empty to use the `title` slot instead. |
+| `subtitle`     | `string`                              | `''`    | One line under the title, such as a status or a count.                          |
+| `headingLevel` | `BfPageHeaderHeadingLevel` (`1 \| 2`) | `1`     | Heading level of the title so the header fits the page outline.                 |
+
+## Slots
+
+- `breadcrumb`: The trail above the title, such as `bf-breadcrumb`.
+- `meta`: Badges beside the title, wrapping under it when they do not fit.
+- `actions`: The page's buttons and menu buttons at the inline end.
+- `title`: Rich title content inside the heading, when the `title` input is empty.
+
+## Notes
+
+### Do
+
+- Keep one primary action; put the rest in a ghost button or the "More actions" menu.
+- Keep the subtitle to one short line, such as progress or a due date.
+
+### Don't
+
+- Don't use `bf-page-header` inside the Capacitor shell; that is `bf-header`.
+- Don't put search fields or filters in `actions`; they belong in a `bf-toolbar` below the header.
+
+## Migration notes
+
+### 0.3.1
+
+New `bf-page-header` in `@bitforgehq/ui`, the desktop page header: a `breadcrumb` slot above,
+the `title` as an `h1` (`headingLevel` 2 for an `h2`, `BfPageHeaderHeadingLevel`) with an
+optional `subtitle`, a `meta` slot for badges beside the title, a `title` slot for rich title
+content, and an `actions` slot at the inline end that wraps under the title in a narrow window.
+Empty slots take no space. It is a sibling of `bf-header` (`/mobile`), not a shell-aware mode of
+it: no large title, no scroll-under surface, no safe areas.

package/ai/components/pagination.md

@@ -0,0 +1,173 @@
+# bf-pagination
+
+Previous, next and numbered page buttons for a long list or table
+
+`BfPaginationComponent` from `@bitforgehq/ui` · Navigation · since 0.3.1
+
+## Example
+
+```ts
+import { Component, computed, signal } from '@angular/core';
+import { BfPaginationComponent } from '@bitforgehq/ui';
+
+/**
+ * The bf-pagination overview.
+ *
+ * Live demo of `bf-pagination`: twelve pages of search results, the first and last page always
+ * shown, one page on each side of the current one and an ellipsis for the rest. The result line
+ * reports the page the buttons set.
+ */
+@Component({
+  selector: 'app-example-pagination-overview',
+  imports: [BfPaginationComponent],
+  template: `
+    <div class="flex flex-col gap-3">
+      <bf-pagination label="Result pages" [(page)]="page" [pageCount]="12" />
+      <p data-status aria-live="polite" class="text-caption text-text-muted">{{ status() }}</p>
+    </div>
+  `,
+})
+export class PaginationOverviewExampleComponent {
+  readonly page = signal(1);
+
+  readonly status = computed(() => {
+    const first = (this.page() - 1) * 20 + 1;
+    return `Page ${this.page()}: results ${first}–${first + 19} of 240.`;
+  });
+}
+```
+
+## Overview
+
+Page navigation for a long list or table: Previous and Next buttons around the page numbers,
+the current one marked, the hidden runs shown as an ellipsis. `compact` shows "Page 3 of 12"
+between the arrows instead, for narrow screens. The page count comes from `pageCount`, or from
+`total` and `pageSize`; the consumer shows the rows of `page`.
+
+Pagination splits a long list or table into pages and lets the user move between them: Previous and Next buttons around the page numbers, the current page marked, the first and the last page always in reach, and an ellipsis for each run of pages in between. `bf-pagination` holds only the page number. You bind `[(page)]` and show that page's rows, sliced on the client or fetched from the server. It works the same in both shells: in a desktop web app and in the Capacitor shell.
+
+## When to use
+
+Use `bf-pagination` under a table or a list of results the user moves through in steps and refers back to by position ("it was on page 3"): invoices, search results, an audit log. Use a "Load more" [bf-button](https://bitforge-ui.web.app/components/button) at the end of the list instead when the user only reads on, as in a feed, and in the Capacitor shell for a phone list that scrolls. Use [bf-tab-bar](https://bitforge-ui.web.app/components/tab-bar) or a [bf-top-nav](https://bitforge-ui.web.app/components/top-nav) for the sections of an app, not pagination.
+
+## Page count
+
+The number of pages comes from `pageCount`, or from `total` (the number of items) and `pageSize` (items per page, default 10), as `Math.ceil(total / pageSize)`. When `pageCount` is above 0 it wins and `total` is ignored; with neither set, or no items, there is one page. The count is never below 1, so an empty table still shows "1" with both arrows disabled.
+
+`page` is 1-based and starts at 1. A `page` beyond the count shows as the last page (and below 1 as the first), but the component never writes the clamped value back: when the total shrinks, after a filter or a delete, set `page` back in range yourself.
+
+## Pages around the current one
+
+The row always shows the first and the last page, the current page and `siblings` pages on each side of it (default 1). Every run of hidden pages becomes an ellipsis; a run of only one page shows that page instead. So the row keeps the same number of slots (`2 × siblings + 5`) wherever the current page is, and the buttons do not shift under the pointer as the user steps through. Set `siblings` to `0` for the shortest row, or to `2` on a wide page. With few pages every page shows.
+
+## Compact
+
+`compact` replaces the page buttons with the position as text, "Page 3 of 12" (`provideBfLabels()`'s `pageOf`), between the arrows. Use it where the full row does not fit: a narrow column, a phone, a side panel. A responsive page can render the full row from `md` up and the compact one below it (a `hidden md:block` and a `md:hidden` wrapper around two `bf-pagination`s bound to the same `page`).
+
+```ts
+import { Component, signal } from '@angular/core';
+import { BfPaginationComponent } from '@bitforgehq/ui';
+
+/**
+ * Compact pagination for a narrow space.
+ *
+ * `compact` shows "Page 3 of 12" between the arrows instead of the page buttons; the text is a
+ * polite live region, so each step is announced.
+ */
+@Component({
+  selector: 'app-example-pagination-compact',
+  imports: [BfPaginationComponent],
+  template: `<bf-pagination
+    label="Compact result pages"
+    compact
+    [(page)]="page"
+    [pageCount]="12"
+  />`,
+})
+export class PaginationCompactExampleComponent {
+  readonly page = signal(3);
+}
+```
+
+## With a table
+
+Put the pagination under the table it pages, aligned to the inline end or centred, and show only the current page's rows: slice them in a `computed()` from `page`, or fetch the page from the server in a `httpResource()` keyed on it. When the user sorts or filters, set `page` back to 1. The [table](https://bitforge-ui.web.app/components/table) page has a paged example.
+
+## Sizes
+
+`size` sets the button height: `sm` 32 px, `md` 40 px (default), `lg` 48 px; the page buttons are at least as wide as they are tall and grow for long numbers. Unset, it follows `provideBfDefaults()`'s `controlSize`, so a dense page's `{ controlSize: 'sm' }` makes it small with the rest of the page. Under a coarse pointer every button's hit area extends to 44 px tall without changing its look. When the row wraps (a narrow container), the lines keep 8 px apart, so the extended hit areas never cover a button on the next line.
+
+## Desktop
+
+The page buttons take the quiet ghost look: no fill at rest, `surface-muted` on hover, a step darker while pressed; the arrows are text icon buttons with a CSS chevron. The current page takes the `primary-soft` fill. The pointer cursor shows on every live button, the not-allowed cursor on an arrow at the end of the range. The focus ring shows on keyboard focus only. The arrows point to the inline start and end, so they mirror under `dir="rtl"`. Inside `provideBfShell()` (the Capacitor shell) it renders the same; prefer `compact` on a phone.
+
+## Theming
+
+- Page buttons: `text-muted` with a transparent fill; hover `surface-muted` and `text`, pressed `surface-pressed`; the current page `primary-soft` with `primary-strong` text, hover `primary-soft-hover`. Under forced colours the current page is outlined.
+- Arrows: `text-muted` with a transparent fill, hover `surface-muted`, pressed `primary-soft-pressed`; at the ends `text-disabled`. The chevron is drawn with 1.5 px borders in the text colour.
+- Ellipsis and the compact "Page 3 of 12": `text-muted`, bold, tabular figures.
+- Shape: `rounded-control` buttons, the `ring` focus ring. Type: `text-label-xs`, `text-label-sm` and `text-label` per size.
+
+## Accessibility
+
+The host renders a `nav` landmark named by `label`, else "Pagination" (`provideBfLabels()`'s `pagination`), around a list of native `button`s; give each pagination on a page its own `label` ("Invoice pages"). A page button reads as "Page 4" (`goToPage`), so its visible number is part of its name, and the current page carries `aria-current="page"`. The ellipses are `aria-hidden`, so the list announces only the buttons. Previous and Next are named "Previous page" and "Next page" (`previousPage`, `nextPage`); the chevrons are `aria-hidden`.
+
+At the first and the last page the arrow is disabled with `aria-disabled="true"`, not native `disabled`: it stays focusable and does nothing when pressed. This follows the WAI-ARIA guidance for controls that turn unavailable while focused: a user who presses Next until the last page keeps focus on the button instead of losing it to the page. In `compact` mode the "Page 3 of 12" text is a polite live region, so the new position is announced after each step; in the full row the pressed page button becomes the current one in place. Moving to another page does not move focus: the content that changed is the consumer's, so announce a new result count there if it matters.
+
+### Keyboard
+
+| Key                                              | Action                                                                     |
+| ------------------------------------------------ | -------------------------------------------------------------------------- |
+| <kbd>Tab</kbd> / <kbd>Shift</kbd>+<kbd>Tab</kbd> | Moves through Previous, the page buttons and Next, including disabled ends |
+| <kbd>Enter</kbd> / <kbd>Space</kbd>              | Goes to the focused page, or to the previous or next one                   |
+
+## Inputs
+
+| Name        | Type                                                        | Default     | Description                                                                                                                                               |
+| ----------- | ----------------------------------------------------------- | ----------- | --------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `pageCount` | `number`                                                    | `0`         | The number of pages; wins over `total` and `pageSize` when above 0.                                                                                       |
+| `total`     | `number`                                                    | `0`         | The number of items, used with `pageSize` while `pageCount` is 0.                                                                                         |
+| `pageSize`  | `number`                                                    | `10`        | Items per page, used with `total` while `pageCount` is 0.                                                                                                 |
+| `siblings`  | `number`                                                    | `1`         | How many pages to show on each side of the current one.                                                                                                   |
+| `compact`   | `boolean`                                                   | `false`     | Shows "Page 3 of 12" between the arrows instead of the page buttons, for narrow screens.                                                                  |
+| `size`      | `BfSize \| undefined` (`'sm' \| 'md' \| 'lg' \| undefined`) | `undefined` | Button height step: sm 32, md 40, lg 48 px (44 px hit area under a coarse pointer); unset follows `provideBfDefaults()` (`controlSize`, `md` by default). |
+| `label`     | `string`                                                    | `''`        | Accessible name of the navigation; empty falls back to `provideBfLabels()`'s `pagination` ("Pagination").                                                 |
+| `page`      | `number`                                                    | `1`         | The current page, 1-based; two-way bindable. The buttons set it; show the rows of this page. Two-way: `[(page)]`.                                         |
+
+## Methods
+
+### `go(target: number): void`
+
+Goes to a page: sets `page` when it is another page within 1…count; else does nothing.
+
+| Parameter | Type     | Description                |
+| --------- | -------- | -------------------------- |
+| `target`  | `number` | The 1-based page to go to. |
+
+## Notes
+
+### Do
+
+- Show the current page's rows and nothing else, and go back to page 1 after a sort or a filter.
+- Give every pagination a `label` when a page has more than one.
+- Use `compact` in a narrow space, and keep the full row where it fits.
+
+### Don't
+
+- Don't page a short list that fits on one screen; show it whole.
+- Don't use pagination to switch between sections or steps; it is for pages of one list.
+
+## Migration notes
+
+### 0.3.1
+
+New `bf-pagination` in `@bitforgehq/ui`, page navigation for both shells: a `nav` (named by
+`label`, else the new `pagination` label) with Previous and Next buttons around the page buttons.
+`[(page)]` is 1-based; the count comes from `pageCount`, else `total` over `pageSize` (default 10).
+The row keeps the first and the last page and `siblings` (default 1) on each side of the current
+one, which carries `aria-current="page"`, and turns hidden runs into an `aria-hidden` ellipsis, at
+a constant number of slots. `compact` shows "Page 3 of 12" (`pageOf`) between the arrows as a
+polite live region. At the ends the arrows are `aria-disabled` and stay focusable. `size` follows
+`controlSize`; the chevrons are CSS and mirror under `dir="rtl"`. New `BfPaginationHarness` in
+`@bitforgehq/ui/testing` (`getCurrentPage()`, `getPageCount()`, `getVisiblePages()`, `goTo()`,
+`next()`, `previous()`).

package/ai/components/popover.md

@@ -0,0 +1,250 @@
+# bf-popover
+
+Anchored, non-modal panel for filters, details or a small form
+
+`BfPopoverComponent` from `@bitforgehq/ui/overlay` · Overlays · since 0.3.1
+
+## Example
+
+```ts
+import { Component, computed, signal } from '@angular/core';
+import { BfButtonComponent, BfCheckboxComponent } from '@bitforgehq/ui';
+import { BfPopoverComponent, BfPopoverTriggerDirective } from '@bitforgehq/ui/overlay';
+
+type Status = 'open' | 'progress' | 'done';
+
+const STATUS_LABELS: Record<Status, string> = {
+  open: 'Open',
+  progress: 'In progress',
+  done: 'Done',
+};
+
+/**
+ * The bf-popover overview.
+ *
+ * Live demo of `bf-popover`: a Filters button opens a small filter form anchored below it. Focus
+ * moves to the first checkbox; Apply copies the choices to the task list and closes the popover
+ * through the exported trigger, while `Escape` or a click outside closes it without applying. The
+ * result line reports the filter in effect.
+ */
+@Component({
+  selector: 'app-example-popover-overview',
+  imports: [BfButtonComponent, BfCheckboxComponent, BfPopoverComponent, BfPopoverTriggerDirective],
+  template: `
+    <div class="flex flex-col items-start gap-3">
+      <bf-button
+        variant="outline"
+        [bfPopoverTriggerFor]="filters"
+        #filtersTrigger="bfPopoverTrigger"
+        (bfPopoverOpened)="draft.set(applied())"
+      >
+        Filters
+      </bf-button>
+      <p data-status aria-live="polite" class="text-caption text-text-muted">{{ status() }}</p>
+    </div>
+
+    <ng-template #filters>
+      <bf-popover class="w-72">
+        <h2 class="text-label text-text mb-3">Filter tasks</h2>
+        <div role="group" aria-label="Status" class="flex flex-col gap-2">
+          @for (status of statuses; track status) {
+            <bf-checkbox
+              [label]="labels[status]"
+              [checked]="draft().includes(status)"
+              (changed)="toggle(status, $event)"
+            />
+          }
+        </div>
+        <div class="mt-4 flex justify-end gap-2">
+          <bf-button variant="text" size="sm" (clicked)="draft.set([])">Clear</bf-button>
+          <bf-button size="sm" (clicked)="applied.set(draft()); filtersTrigger.close()">
+            Apply
+          </bf-button>
+        </div>
+      </bf-popover>
+    </ng-template>
+  `,
+})
+export class PopoverOverviewExampleComponent {
+  protected readonly statuses: readonly Status[] = ['open', 'progress', 'done'];
+  protected readonly labels = STATUS_LABELS;
+  readonly applied = signal<readonly Status[]>(['open', 'progress']);
+  readonly draft = signal<readonly Status[]>(['open', 'progress']);
+
+  readonly status = computed(() => {
+    const applied = this.applied();
+    return applied.length
+      ? `Showing ${applied.map((s) => STATUS_LABELS[s]).join(', ')} tasks.`
+      : 'Showing all tasks.';
+  });
+
+  toggle(status: Status, checked: boolean): void {
+    this.draft.update((draft) =>
+      checked ? [...draft, status] : draft.filter((s) => s !== status),
+    );
+  }
+}
+```
+
+## Overview
+
+Non-modal panel anchored to a trigger, for filters, details or a small form (role `dialog`).
+Put it in an `ng-template` that a `[bfPopoverTriggerFor]` opens; it takes the id the trigger's
+`aria-controls` points at and is named by `bfPopoverLabel`, else by its first heading, else by
+the trigger.
+
+Anchored panels for desktop and web apps, from `@bitforgehq/ui/overlay` (needs `@angular/cdk`, no
+Capacitor). A `bf-popover` is the panel; put it in an `ng-template` and open it from a button with
+`[bfPopoverTriggerFor]`. It opens beside its trigger, flips when it has no room, and leaves the
+page usable: it is non-modal, so there is no backdrop, focus is not trapped and the page does not
+become inert. It follows the
+[APG disclosure](https://www.w3.org/WAI/ARIA/apg/patterns/disclosure/) pattern with a non-modal
+`dialog` panel. Popovers open in the CDK overlay container, so they work inside a
+`BfDialogService` dialog.
+
+Import `BfPopoverComponent` and `BfPopoverTriggerDirective` from `@bitforgehq/ui/overlay`.
+
+## When to use
+
+Use `bf-popover` for a few fields or details that belong to one control and are used for a moment:
+filters for a list, the details of a value, a small form such as "Rename". Use
+[bf-menu](https://bitforge-ui.web.app/components/menu) instead for a list of actions or view settings,
+[BfDialogService](https://bitforge-ui.web.app/api/bf-dialog-service) for a task that needs the user's full attention or more
+than a few fields, a [bf-tooltip](https://bitforge-ui.web.app/components/tooltip) for a short hint with nothing to interact
+with, and in a Capacitor app a [bf-sheet](https://bitforge-ui.web.app/components/sheet).
+
+## Opening and closing
+
+The trigger toggles the popover on a click (and on `Enter` or `Space`, which click a button).
+Focus moves to the first control inside (or to the element marked `autofocus`, or to the panel
+when it holds no control). `Escape`, a click outside, `Tab` past the panel's last control or a
+navigation to another URL path close it. `Escape` and a click on nothing focusable put focus back
+on the trigger; a click on another control leaves focus there.
+
+Export the trigger as `bfPopoverTrigger` to close the popover from inside it, for example from an
+Apply button: `#trigger="bfPopoverTrigger"`, then `trigger.close()`. It also has `open()`,
+`toggle()` and `isOpen()`. `(bfPopoverOpened)` and `(bfPopoverClosed)` report its state.
+
+The trigger can be a native `button` or a `bf-button`: on a host that does not take focus itself,
+the ARIA state goes on the first control inside it.
+
+## Placement
+
+`bfPopoverPlacement` sets where the panel opens: `'below-start'` (default), `'below-end'`,
+`'above-start'` or `'above-end'`, 4 px from the trigger. `start` and `end` follow the text
+direction. When the panel would overflow the viewport, it flips to the other side vertically
+first, then to the other alignment. It scrolls past the viewport height minus 2 rem. The
+placement is read each time it opens.
+
+```ts
+import { Component } from '@angular/core';
+import { BfButtonComponent } from '@bitforgehq/ui';
+import { BfPopoverComponent, BfPopoverTriggerDirective } from '@bitforgehq/ui/overlay';
+
+/**
+ * A details popover aligned to the trigger's end.
+ *
+ * `bfPopoverPlacement="below-end"` opens the panel under the trigger, aligned to its inline end;
+ * `bfPopoverLabel` names it when it has no heading.
+ */
+@Component({
+  selector: 'app-example-popover-placement',
+  imports: [BfButtonComponent, BfPopoverComponent, BfPopoverTriggerDirective],
+  template: `
+    <div class="flex justify-end">
+      <bf-button
+        variant="text"
+        [bfPopoverTriggerFor]="details"
+        bfPopoverPlacement="below-end"
+        bfPopoverLabel="Delivery details"
+      >
+        Delivery
+      </bf-button>
+    </div>
+
+    <ng-template #details>
+      <bf-popover class="w-64">
+        <p class="text-body text-text">Arrives Thursday between 9 and 12.</p>
+        <p class="text-caption text-text-muted mt-1">Tracking updates every hour.</p>
+      </bf-popover>
+    </ng-template>
+  `,
+})
+export class PopoverPlacementExampleComponent {}
+```
+
+## Naming
+
+The panel is a `dialog` named by `bfPopoverLabel` on the trigger when you set it, else by the
+first heading inside it, else by the trigger's text. Give a popover a heading when it holds a
+form, so its purpose is announced when focus moves in.
+
+## Desktop
+
+Built for a mouse and a keyboard: the panel opens next to its trigger and the page stays usable
+around it, so a click elsewhere closes it and lands where it was aimed. `Tab` walks through the
+panel and on to the control after the trigger, closing the panel, so keyboard users never get
+stuck in it. Set the panel's width with a class on `bf-popover` (`w-72`); it never grows past the
+viewport width minus 2 rem.
+
+Under a coarse pointer it works the same, with the panel's controls at their own touch sizes;
+in the Capacitor shell a `bf-sheet` suits phone screens better.
+
+## Theming
+
+- Panel: `bg-surface`, `text-text`, a 1 px `border-border`, `rounded-card`, `shadow-floating`,
+  `p-card` (18 px).
+- The content is yours: use the library's type and field tokens inside it.
+
+## Accessibility
+
+- The trigger's control has `aria-haspopup="dialog"`, `aria-expanded` and, while open,
+  `aria-controls` pointing at the panel.
+- The panel is `role="dialog"` without `aria-modal`, named as described under Naming. It gets the
+  id that `aria-controls` names.
+- Focus: opening moves focus into the panel; `Escape` returns it to the trigger. `Tab` is not
+  trapped: past the last control the panel closes and focus continues after the trigger, and
+  `Shift+Tab` before the first control closes it onto the trigger.
+- `Escape` goes to the popover first: inside a dialog, the first `Escape` closes the popover and
+  the next one the dialog.
+
+### Keyboard
+
+| Key                                 | Where            | Action                                                  |
+| ----------------------------------- | ---------------- | ------------------------------------------------------- |
+| <kbd>Enter</kbd> / <kbd>Space</kbd> | Trigger          | Opens the popover (closes it when open), focus moves in |
+| <kbd>Tab</kbd>                      | Panel            | Next control; past the last one closes, focus moves on  |
+| <kbd>Shift</kbd>+<kbd>Tab</kbd>     | First control    | Closes the popover, focus back on the trigger           |
+| <kbd>Escape</kbd>                   | Panel or trigger | Closes the popover, focus back on the trigger           |
+
+## Slots
+
+- `default`: The panel's content: a heading, text, fields and actions.
+
+## Notes
+
+### Do
+
+- Keep a popover small: a heading, a few fields and one or two actions.
+- Give a popover with a form a heading, or set `bfPopoverLabel`.
+- Apply a filter from an explicit button, or as each field changes, and say which in the panel.
+
+### Don't
+
+- Don't put a long form or a multi-step task in a popover; use a dialog.
+- Don't open a popover on hover; it opens on a click.
+- Don't use a popover for a list of actions; use a menu.
+- Don't nest popovers.
+
+## Migration notes
+
+### 0.3.1
+
+New `[bfPopoverTriggerFor]` (`BfPopoverTriggerDirective`, exported as `bfPopoverTrigger`) and the
+`bf-popover` panel (`BfPopoverComponent`) in `@bitforgehq/ui/overlay`: a non-modal `role="dialog"`
+panel anchored to its trigger, for filters, details or a small form. `bfPopoverPlacement`
+(`BfPopoverPlacement`, the menu's four placements), `bfPopoverLabel`, `(bfPopoverOpened)` and
+`(bfPopoverClosed)`, and `open()`, `close()`, `toggle()`, `isOpen()`. The trigger's control gets
+`aria-haspopup="dialog"`, `aria-expanded` and `aria-controls`; focus moves in on open, `Tab` is not
+trapped (it closes the panel past either end), and `Escape`, a click outside or a navigation close
+it and return focus. New `BfPopoverHarness` in `@bitforgehq/ui/testing`.