@bitforgehq/ui 0.3.0 → 0.3.2

package/ai/components/nav-item.md

@@ -0,0 +1,210 @@
+# a[bfNavItem]
+
+Navigation link for a sidebar or top nav, with icon, label and count
+
+`BfNavItemComponent` from `@bitforgehq/ui` · Navigation · since 0.3.1
+
+## Example
+
+```ts
+import { Component } from '@angular/core';
+import { RouterLink, RouterLinkActive } from '@angular/router';
+import { BfNavItemComponent, BfSidebarComponent } from '@bitforgehq/ui';
+import { BfIconComponent } from '@bitforgehq/ui/icons';
+import { Bell, Inbox, ListTodo } from 'lucide';
+
+/**
+ * The a[bfNavItem] overview.
+ *
+ * Live demo of `a[bfNavItem]`: router links with an icon, the current page (this one) in the
+ * tonal fill, a count badge and the sm, md and lg heights; then the same links in a collapsed
+ * sidebar, icon only, the badge a dot and the label a tooltip.
+ */
+@Component({
+  selector: 'app-example-nav-item-overview',
+  imports: [RouterLink, RouterLinkActive, BfIconComponent, BfNavItemComponent, BfSidebarComponent],
+  template: `
+    <div class="flex flex-wrap items-start gap-4">
+      <bf-sidebar label="Nav items">
+        <a
+          bfNavItem
+          routerLink="/components/nav-item"
+          routerLinkActive
+          ariaCurrentWhenActive="page"
+        >
+          <bf-icon bfSlot="icon" [icon]="listTodo" />
+          Nav item
+        </a>
+        <a
+          bfNavItem
+          routerLink="/components/badge"
+          routerLinkActive
+          ariaCurrentWhenActive="page"
+          [badge]="12"
+        >
+          <bf-icon bfSlot="icon" [icon]="inbox" />
+          Badge
+        </a>
+        <a bfNavItem size="sm" routerLink="/density" routerLinkActive ariaCurrentWhenActive="page">
+          <bf-icon bfSlot="icon" [icon]="bell" />
+          Small · 32
+        </a>
+        <a bfNavItem size="lg" routerLink="/density" routerLinkActive ariaCurrentWhenActive="page">
+          <bf-icon bfSlot="icon" [icon]="bell" />
+          Large · 48
+        </a>
+      </bf-sidebar>
+      <bf-sidebar label="Nav items, collapsed" [collapsed]="true">
+        <a
+          bfNavItem
+          routerLink="/components/nav-item"
+          routerLinkActive
+          ariaCurrentWhenActive="page"
+        >
+          <bf-icon bfSlot="icon" [icon]="listTodo" />
+          Nav item
+        </a>
+        <a
+          bfNavItem
+          routerLink="/components/badge"
+          routerLinkActive
+          ariaCurrentWhenActive="page"
+          [badge]="12"
+        >
+          <bf-icon bfSlot="icon" [icon]="inbox" />
+          Badge
+        </a>
+      </bf-sidebar>
+    </div>
+  `,
+})
+export class NavItemOverviewExampleComponent {
+  protected readonly listTodo = ListTodo;
+  protected readonly inbox = Inbox;
+  protected readonly bell = Bell;
+}
+```
+
+## Overview
+
+One destination of a `bf-sidebar` or `bf-top-nav`: put `bfNavItem` on your own `<a>` with
+`routerLink`, `routerLinkActive` and `ariaCurrentWhenActive="page"`, and the item shows the
+current page from `aria-current`. An icon goes in the `icon` slot, the label in the default
+slot; `badge` adds a count. In a collapsed sidebar only the icon shows, the label stays for
+screen readers and becomes the `title` tooltip.
+
+One destination of a [`bf-sidebar`](https://bitforge-ui.web.app/components/sidebar) or a [`bf-top-nav`](https://bitforge-ui.web.app/components/top-nav): put `bfNavItem` on your own `<a>` with `routerLink`, `routerLinkActive` and `ariaCurrentWhenActive="page"`. An icon goes in `bfSlot="icon"`, the label in the default slot, and `badge` adds a count. The item reads its layout from its container: a full-width row in a sidebar, an inline item in a top nav, an icon in a collapsed sidebar.
+
+## When to use
+
+Use `a[bfNavItem]` for each link of a `bf-sidebar` or `bf-top-nav`. Use [`a[bfButton]`](https://bitforge-ui.web.app/components/button) with `variant="ghost"` instead for a link that is not part of the app's navigation, and [bf-list-item](https://bitforge-ui.web.app/components/list-item) with a `bfAction` link for a row of a list. In the Capacitor shell use [bf-tabs](https://bitforge-ui.web.app/components/tabs) with [bf-tab-bar](https://bitforge-ui.web.app/components/tab-bar) instead.
+
+## Basic usage
+
+The router sets `aria-current="page"` on the current page's link (`routerLinkActive` with `ariaCurrentWhenActive="page"`), and the item shows it in the tonal fill (`primary-soft`, the same as an `a[bfButton]` ghost link); the widget never imports the router. Other items are neutral (`text-muted`) until hovered. The label truncates with an ellipsis in a narrow sidebar.
+
+## Count badge
+
+`badge` takes a number and shows it as a pill at the inline end; `null` (the default) shows none. The pill is hidden from screen readers and the count is announced after the label with `provideBfLabels()`'s `navBadge(count)` ("3 new"), so the link's name is "Inbox 3 new".
+
+## Collapsed
+
+In a collapsed `bf-sidebar` the item shows only its icon in a square of its height step. The label stays in the DOM as screen-reader text, so the link's name does not change, and becomes the link's `title` (the tooltip on hover, kept up to date when the label changes); your own `title` comes back when the sidebar expands. The badge becomes a small dot on the icon's corner and is still announced. Give every item an icon, or it shows nothing while collapsed. For a styled tooltip that also shows on keyboard focus, add `bfTooltip` from `@bitforgehq/ui/overlay` with the label's text while collapsed (an empty text while expanded shows none) and `bfTooltipPlacement="end"` (see [bf-tooltip](https://bitforge-ui.web.app/components/tooltip)).
+
+## Sizes
+
+`size` sets the height: `sm` 32, `md` 40, `lg` 48 px. Unset, it follows `provideBfDefaults()` (`controlSize`, `md` by default). The height is a minimum, so a label at a large text size grows the item instead of clipping it.
+
+```ts
+import { Component } from '@angular/core';
+import { BfNavItemComponent, BfSidebarComponent } from '@bitforgehq/ui';
+import { BfIconComponent } from '@bitforgehq/ui/icons';
+import { Bell } from 'lucide';
+
+/**
+ * The three heights of a nav item.
+ *
+ * `size` sets 32, 40 or 48 px; unset, the item follows `provideBfDefaults()`'s `controlSize`.
+ */
+@Component({
+  selector: 'app-example-nav-item-sizes',
+  imports: [BfIconComponent, BfNavItemComponent, BfSidebarComponent],
+  template: `
+    <bf-sidebar label="Nav item sizes">
+      <a bfNavItem size="sm" href="#sizes">
+        <bf-icon bfSlot="icon" [icon]="bell" />
+        Small · 32
+      </a>
+      <a bfNavItem size="md" href="#sizes">
+        <bf-icon bfSlot="icon" [icon]="bell" />
+        Medium · 40
+      </a>
+      <a bfNavItem size="lg" href="#sizes">
+        <bf-icon bfSlot="icon" [icon]="bell" />
+        Large · 48
+      </a>
+    </bf-sidebar>
+  `,
+})
+export class NavItemSizesExampleComponent {
+  protected readonly bell = Bell;
+}
+```
+
+## Desktop
+
+Hover gives a `surface-muted` fill with the `text` colour and the pointer; pressing gives `surface-pressed`. The current page keeps its tonal fill, one step darker on hover and again while pressed. The focus ring shows on keyboard focus only (`focus-visible`). Under a fine pointer the item's box is its hit area; under a coarse pointer (a touchscreen laptop) it grows to at least 44 px tall (`pointer-coarse:min-h-hit`) instead of extending an invisible hit area over its neighbours, because it holds your label. A link keeps the browser's behaviour: Ctrl/Cmd-click and a middle click open it in a new tab.
+
+## Theming
+
+- Rest: transparent with `text-muted`; hover `surface-muted` with `text`; pressed `surface-pressed`.
+- Current page (`aria-current="page"`): `primary-soft` with `primary-strong`, hover `primary-soft-hover`, pressed `primary-soft-pressed`; under forced colours a `LinkText` outline.
+- Shape: `rounded-control`; label `font-bold`, `text-label-xs` / `text-label-sm` / `text-label` by size.
+- Badge: `primary` with `on-primary`, `text-micro`; collapsed, a `primary` dot (`CanvasText` under forced colours).
+- Focus: `ring` (4 px).
+
+## Accessibility
+
+The item is the consumer's native `<a>`: exposed as a link, reached with Tab and followed with Enter, its name being its label (plus the badge announcement). The current page carries `aria-current="page"`, which screen readers announce; the fill is not the only cue, as an outline marks it under forced colours. The icon slot is decorative (a `bf-icon` is `aria-hidden` by default). Collapsed, the label is visually hidden but still the name, and `title` adds a pointer tooltip only; the badge dot is `aria-hidden`, its count announced through the screen-reader text. In Safari, Tab reaches links only when the user turns on "Press Tab to highlight each item" (Option+Tab otherwise).
+
+### Keyboard
+
+| Key              | Action                                            |
+| ---------------- | ------------------------------------------------- |
+| <kbd>Tab</kbd>   | Moves focus to the link                           |
+| <kbd>Enter</kbd> | Follows the link; a link ignores <kbd>Space</kbd> |
+
+## Inputs
+
+| Name    | Type                                                        | Default     | Description                                                                                                                                             |
+| ------- | ----------------------------------------------------------- | ----------- | ------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `size`  | `BfSize \| undefined` (`'sm' \| 'md' \| 'lg' \| undefined`) | `undefined` | Height step: sm 32, md 40, lg 48 px (44 px at least under a coarse pointer); unset follows `provideBfDefaults()` (`controlSize`, `md` by default).      |
+| `badge` | `number \| null`                                            | `null`      | A count shown as a pill at the inline end (a dot while collapsed), announced with `provideBfLabels()`'s `navBadge(count)` ("3 new"); `null` shows none. |
+
+## Slots
+
+- `icon`: An icon before the label, a `bf-icon`; the only thing shown while collapsed.
+- `default`: The label.
+
+## Notes
+
+### Do
+
+- Put `routerLinkActive` and `ariaCurrentWhenActive="page"` on every item, so the current page shows.
+- Give every item in a collapsible sidebar an icon.
+
+### Don't
+
+- Don't put `bfNavItem` on a `<button>`; a destination is a link, and an action belongs in the header or footer as a button.
+- Don't set `aria-current` yourself on more than one item.
+
+## Migration notes
+
+### 0.3.1
+
+New `a[bfNavItem]`: one destination of a `bf-sidebar` or `bf-top-nav` on the app's own
+`<a routerLink routerLinkActive ariaCurrentWhenActive="page">`. Neutral at rest, the tonal fill
+for the current page from `aria-current="page"` (as an `a[bfButton]` ghost link), an `icon` slot,
+`size` from `controlSize` (44 px at least under a coarse pointer) and a `badge` count announced
+with the new `navBadge(count)` label ("3 new"). In a collapsed sidebar it shows its icon only,
+keeps its label as screen-reader text and as its `title`, and turns the badge into a dot.

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()`).