@bitforgehq/ui 0.3.0 → 0.3.1

package/ai/components/bar-chart.md

@@ -0,0 +1,188 @@
+# bf-bar-chart
+
+Bar chart of series over categories, grouped or stacked, vertical or horizontal
+
+`BfBarChartComponent` from `@bitforgehq/ui/charts` · Data display · since 0.3.1
+
+## Example
+
+```ts
+import { Component } from '@angular/core';
+import { BfBarChartComponent, type BfChartSeries } from '@bitforgehq/ui/charts';
+
+/**
+ * The bf-bar-chart overview.
+ *
+ * Live demo of `bf-bar-chart`: support tickets opened and closed per weekday, side by side.
+ * Hover a day, or focus the plot and use the arrow keys; hide a series in the legend; open Show
+ * data for the table.
+ */
+@Component({
+  selector: 'app-example-bar-chart-overview',
+  imports: [BfBarChartComponent],
+  template: `
+    <bf-bar-chart label="Support tickets this week" [series]="series" [categories]="days" />
+  `,
+})
+export class BarChartOverviewExampleComponent {
+  readonly days = ['Mon', 'Tue', 'Wed', 'Thu', 'Fri'];
+  readonly series: readonly BfChartSeries[] = [
+    { name: 'Opened', values: [14, 9, 12, 17, 8] },
+    { name: 'Closed', values: [11, 12, 8, 15, 13] },
+  ];
+}
+```
+
+## Overview
+
+A bar chart of one or more series over shared categories, drawn in SVG with the chart palette:
+bars side by side per category (or `stacked`), up from the baseline (or `horizontal`, along
+from it), with a value axis of nice ticks, a legend that shows and hides series, a tooltip on
+hover and on keyboard focus (Arrow keys move between the categories and a polite live region
+reads each one) and a Show data table. Bars grow in on the first render and on every data
+change, still under reduced motion; under `dir="rtl"` the horizontal axis runs from the right.
+
+A bar chart compares amounts between categories: tickets opened and closed per weekday, revenue per region, hours per project. `bf-bar-chart` draws it in SVG from `series` (each a `name` and one value per category) and `categories`, side by side or `stacked`, as vertical columns or `horizontal` bars, with a value axis of nice ticks from zero, a legend that shows and hides series, a tooltip on hover and on keyboard focus, and a Show data table. It lives in `@bitforgehq/ui/charts` (`import { BfBarChartComponent } from '@bitforgehq/ui/charts'`) and works the same in a desktop web app and in the Capacitor shell.
+
+## When to use
+
+Use `bf-bar-chart` to compare amounts between categories, or the parts of each category with `stacked`. Our charts are themed with the `--color-chart-*` tokens, follow dark mode and `dir="rtl"`, and bring their own legend, tooltip, keyboard reading and data table; bring a chart library (themed with the same tokens) only for a form they do not draw. Use [bf-line-chart](https://bitforge-ui.web.app/components/line-chart) instead for a trend over time, [bf-donut-chart](https://bitforge-ui.web.app/components/donut-chart) for the shares of one whole, and [bf-table](https://bitforge-ui.web.app/components/table) when readers look up exact values more than they compare them.
+
+## Stacked
+
+`stacked` puts the series of each category into one bar, one segment per series with a 2 px gap between them, so the bar's length is the category's total. Positive values stack up from zero and negative ones down. Use it when the total matters as much as its parts; compare the parts across categories with grouped bars instead (the default), which share one baseline.
+
+```ts
+import { Component } from '@angular/core';
+import { BfBarChartComponent, type BfChartSeries } from '@bitforgehq/ui/charts';
+
+/**
+ * A stacked bar chart.
+ *
+ * `stacked` puts the series of each month into one bar, so its length is the month's total:
+ * hours logged per month, split by kind of work.
+ */
+@Component({
+  selector: 'app-example-bar-chart-stacked',
+  imports: [BfBarChartComponent],
+  template: `
+    <bf-bar-chart
+      label="Hours logged by kind of work"
+      stacked
+      legend="top"
+      [series]="series"
+      [categories]="months"
+      [valueFormat]="hours"
+    />
+  `,
+})
+export class BarChartStackedExampleComponent {
+  readonly months = ['Jun', 'Jul', 'Aug', 'Sep', 'Oct'];
+  readonly series: readonly BfChartSeries[] = [
+    { name: 'Design', values: [42, 38, 24, 51, 47] },
+    { name: 'Build', values: [88, 96, 61, 102, 110] },
+    { name: 'Review', values: [16, 20, 12, 24, 22] },
+  ];
+  readonly hours = (value: number): string => `${value} h`;
+}
+```
+
+## Horizontal
+
+`orientation="horizontal"` runs the bars along from a vertical baseline, the category names down the start side: for long names (projects, countries) or many categories. The categories run top to bottom, and <kbd>ArrowUp</kbd> and <kbd>ArrowDown</kbd> move between them too.
+
+```ts
+import { Component } from '@angular/core';
+import { BfBarChartComponent, type BfChartSeries } from '@bitforgehq/ui/charts';
+
+/**
+ * A horizontal bar chart.
+ *
+ * `orientation="horizontal"` runs the bars along from the start side, with room for long
+ * category names: open tasks per project, sorted from most to fewest.
+ */
+@Component({
+  selector: 'app-example-bar-chart-horizontal',
+  imports: [BfBarChartComponent],
+  template: `
+    <bf-bar-chart
+      label="Open tasks per project"
+      orientation="horizontal"
+      [height]="200"
+      [series]="series"
+      [categories]="projects"
+    />
+  `,
+})
+export class BarChartHorizontalExampleComponent {
+  readonly projects = ['Atlas relaunch', 'Billing', 'Mobile app', 'Docs site'];
+  readonly series: readonly BfChartSeries[] = [{ name: 'Open tasks', values: [23, 17, 12, 6] }];
+}
+```
+
+## Data and formatting
+
+The value axis always includes zero, so every bar's length is honest; values below zero draw below (or before) the baseline. A `null` value draws no bar. `valueFormat` formats the values on the axis, in the tooltip, the announcement and the table; unset, values use `Intl.NumberFormat` in the document's language. Each series keeps its colour (`--color-chart-1` for the first) when another is hidden. Bars grow from the baseline on the first render and whenever the data change. `height` sets the plot's height in px (240 by default); the width follows the container.
+
+## Desktop
+
+Under a mouse, hovering a category highlights its band in `surface-muted` and shows its tooltip; leaving the plot hides them. The legend's buttons take a `surface-muted` fill on hover. The plot is one stop in the tab order, with the focus ring on keyboard focus: focusing it shows the first category. Under a coarse pointer (touch) a tap shows a category's tooltip, and the legend buttons and the Show data button are at least 44 px tall. Inside `provideBfShell()` it renders and behaves the same.
+
+## Theming
+
+- Bars: `--color-chart-1` … `--color-chart-8` by series (`fill-chart-n`), 2 px corner radius, at most 40 px thick.
+- Grid lines: `chart-grid`; the zero baseline: `chart-axis`; axis text: `text-micro` in `text-muted`.
+- Active category band: `surface-muted`.
+- Tooltip, legend and data table: as in [bf-line-chart](https://bitforge-ui.web.app/components/line-chart).
+- Motion: `--animate-chart-grow-y` (columns) or `--animate-chart-grow-x` (horizontal bars); none under `prefers-reduced-motion`.
+
+## Accessibility
+
+The chart is a native `figure` named by `label` (else the `bf-chart-card` title, else the `chart` label); the SVG is hidden from assistive technology. The plot is a focusable `role="group"` named by the `chartValues` label: the arrow keys move between the categories and a polite live region reads each one ("Tue: Opened 9, Closed 12"). The legend is a group of toggle buttons (`aria-pressed`); the Show data button (`aria-expanded`) shows the data as a native `table` with a caption and row headers. Every series is ≥ 3:1 against `surface` and `bg` in both modes, and the legend names each colour.
+
+### Keyboard
+
+| Key                                              | Action                                                                                |
+| ------------------------------------------------ | ------------------------------------------------------------------------------------- |
+| <kbd>Tab</kbd> / <kbd>Shift</kbd>+<kbd>Tab</kbd> | Moves through the plot, the legend buttons and the Show data button                   |
+| <kbd>ArrowRight</kbd>                            | Moves to the next category and reads it (the previous one under `dir="rtl"`)          |
+| <kbd>ArrowLeft</kbd>                             | Moves to the previous category and reads it (the next one under `dir="rtl"`)          |
+| <kbd>ArrowDown</kbd> / <kbd>ArrowUp</kbd>        | With `orientation="horizontal"`, moves to the next / previous category                |
+| <kbd>Home</kbd> / <kbd>End</kbd>                 | Moves to the first / last category                                                    |
+| <kbd>Escape</kbd>                                | Hides the tooltip                                                                     |
+| <kbd>Enter</kbd> / <kbd>Space</kbd>              | On a legend button, shows or hides its series; on Show data, shows or hides the table |
+
+## Inputs
+
+| Name          | Type                                                                              | Default      | Description                                                                                                                                     |
+| ------------- | --------------------------------------------------------------------------------- | ------------ | ----------------------------------------------------------------------------------------------------------------------------------------------- |
+| `series`      | `readonly BfChartSeries[]`                                                        | required     | The series to draw, each with one value per category.                                                                                           |
+| `categories`  | `readonly string[]`                                                               | required     | The category names along the category axis, in order.                                                                                           |
+| `label`       | `string`                                                                          | `''`         | The chart's accessible name; empty falls back to the `bf-chart-card` title, then to `provideBfLabels()`'s `chart` ("Chart").                    |
+| `height`      | `number`                                                                          | `240`        | The plot's height in px; the width follows the container.                                                                                       |
+| `orientation` | `BfBarChartOrientation` (`'vertical' \| 'horizontal'`)                            | `'vertical'` | `vertical` (default) bars rise from a horizontal baseline; `horizontal` bars run along from a vertical one, the categories down the start side. |
+| `stacked`     | `boolean`                                                                         | `false`      | Stacks the series of a category into one bar instead of side by side.                                                                           |
+| `valueFormat` | `BfChartValueFormat \| undefined`                                                 | `undefined`  | Formats the values on the axis, in the tooltip and in the table; unset uses `Intl.NumberFormat` in the document's language.                     |
+| `legend`      | `BfChartLegendPosition \| undefined` (`'top' \| 'bottom' \| 'none' \| undefined`) | `undefined`  | Where the legend goes; unset follows the `bf-chart-card`, else `bottom`. A single series draws no legend.                                       |
+
+## Notes
+
+### Do
+
+- Sort the categories by value when they have no order of their own, so the bars read as a ranking.
+- Use `horizontal` when the category names are long, rather than abbreviating them.
+
+### Don't
+
+- Don't stack series that do not add up to a meaningful total.
+- Don't draw more than eight series; fold the smallest into "Other".
+
+## Migration notes
+
+### 0.3.1
+
+New `bf-bar-chart` in `@bitforgehq/ui/charts`: series over categories as bars from a zero
+baseline, side by side or `stacked`, vertical or `orientation="horizontal"`
+(`BfBarChartOrientation`), with the line chart's value axis, legend, tooltip, keyboard reading and
+data table. Bars grow from the baseline on the first render and on every data change, not under
+reduced motion; `dir="rtl"` mirrors the horizontal axis.

package/ai/components/breadcrumb-item.md

@@ -0,0 +1,121 @@
+# li[bfBreadcrumbItem]
+
+One level of a breadcrumb trail: a link, or the current page as text
+
+`BfBreadcrumbItemComponent` from `@bitforgehq/ui` · Navigation · since 0.3.1
+
+## Example
+
+```ts
+import { Component } from '@angular/core';
+import { RouterLink } from '@angular/router';
+import { BfBreadcrumbComponent, BfBreadcrumbItemComponent } from '@bitforgehq/ui';
+
+/**
+ * The li[bfBreadcrumbItem] overview.
+ *
+ * Three levels of a `bf-breadcrumb`: two ancestor pages as router links, each followed by a
+ * chevron, and the current page as plain text, marked `aria-current="page"`.
+ */
+@Component({
+  selector: 'app-example-breadcrumb-item-overview',
+  imports: [RouterLink, BfBreadcrumbComponent, BfBreadcrumbItemComponent],
+  template: `
+    <bf-breadcrumb label="Component breadcrumb">
+      <li bfBreadcrumbItem><a routerLink="/components">Components</a></li>
+      <li bfBreadcrumbItem><a routerLink="/components/breadcrumb">Breadcrumb</a></li>
+      <li bfBreadcrumbItem>Breadcrumb item</li>
+    </bf-breadcrumb>
+  `,
+})
+export class BreadcrumbItemOverviewExampleComponent {}
+```
+
+## Overview
+
+One level of a `bf-breadcrumb` trail, on the consumer's own `<li>` so the list stays `ol > li`.
+Project an `<a routerLink>` for an ancestor page, or plain text for the current page; the last
+item is the current page (`aria-current="page"`, no link look, no separator), every other one is
+followed by a chevron.
+
+One level of a [`bf-breadcrumb`](https://bitforge-ui.web.app/components/breadcrumb) trail, as an attribute on the app's own `<li>`. It styles the link projected into it, adds the chevron after it and, on the last level, marks the current page. An item lives only inside a `bf-breadcrumb`, which decides which level is current and which ones a collapsed trail hides.
+
+## When to use
+
+Use `li[bfBreadcrumbItem]` for each level of a [bf-breadcrumb](https://bitforge-ui.web.app/components/breadcrumb), and only there. On mobile, in the Capacitor shell, use [bf-back-button](https://bitforge-ui.web.app/components/back-button) in [bf-header](https://bitforge-ui.web.app/components/header) instead.
+
+## Links and the current page
+
+Put an `<a routerLink>` (or `href`) straight inside the `li` for a page above the current one: as a direct child it takes the link look, the hover underline and the focus ring. Put plain text in the last item, the current page: it is wrapped in a span with `aria-current="page"` and shown semibold, and no chevron follows it.
+
+```ts
+import { Component } from '@angular/core';
+import { RouterLink } from '@angular/router';
+import { BfBreadcrumbComponent, BfBreadcrumbItemComponent } from '@bitforgehq/ui';
+
+/**
+ * A breadcrumb trail.
+ *
+ * Each level is the app's own `<li bfBreadcrumbItem>` holding a router link; the last one is the
+ * current page as plain text. `label` names the `nav`; this one is not the page's only breadcrumb
+ * (the docs site has its own), so it gets a name of its own.
+ */
+@Component({
+  selector: 'app-example-breadcrumb-basic',
+  imports: [RouterLink, BfBreadcrumbComponent, BfBreadcrumbItemComponent],
+  template: `
+    <bf-breadcrumb label="Docs breadcrumb">
+      <li bfBreadcrumbItem><a routerLink="/">Docs</a></li>
+      <li bfBreadcrumbItem><a routerLink="/components">Components</a></li>
+      <li bfBreadcrumbItem>Breadcrumb</li>
+    </bf-breadcrumb>
+  `,
+})
+export class BreadcrumbBasicExampleComponent {}
+```
+
+## Desktop
+
+A linked level turns from `text-muted` to `text` and is underlined on hover, with the pointer cursor; the ring shows on keyboard focus only. A link is at least 24 px tall under a fine pointer and 44 px under a coarse one (`pointer-coarse:min-h-hit`), through a min height rather than an `::after`, because it is your content. See the [bf-breadcrumb](https://bitforge-ui.web.app/components/breadcrumb) page for collapsing.
+
+## Theming
+
+- Ancestor level: `text-muted`, `text` on hover with an underline (`underline-offset-4`); `rounded-tile` with the `ring` focus ring.
+- Current page: `text`, semibold.
+- Separator: a 1.5 px CSS chevron in `text-subtle`, pointing to the inline end and mirrored under `dir="rtl"`.
+
+## Accessibility
+
+The host is your native `<li>`, so the trail stays an ordered list. Only the last item carries `aria-current="page"`. The chevron is an empty `aria-hidden` element, never announced. A level a collapsed trail hides carries `hidden`; when the ellipsis shows it and it has no link, the item takes focus itself (`tabindex="-1"`).
+
+### Keyboard
+
+| Key              | Action                    |
+| ---------------- | ------------------------- |
+| <kbd>Tab</kbd>   | Moves to the level's link |
+| <kbd>Enter</kbd> | Follows the focused link  |
+
+## Slots
+
+- `default`: The level: an `<a>` link to the page, or plain text for the current page.
+
+## Notes
+
+### Do
+
+- Project the link as the direct child of the `li`, so it takes the link look.
+- Keep the current page plain text.
+
+### Don't
+
+- Don't use `li[bfBreadcrumbItem]` outside a `bf-breadcrumb`.
+- Don't put more than one link, or a control, in one level.
+
+## Migration notes
+
+### 0.3.1
+
+New `li[bfBreadcrumbItem]` in `@bitforgehq/ui`: one level of a `bf-breadcrumb` on the app's own
+`<li>`. A projected link takes the muted link look, the hover underline and the focus ring (at
+least 24 px tall, 44 px under a coarse pointer); the last level is the current page, wrapped in
+`aria-current="page"` with no chevron.

package/ai/components/breadcrumb.md

@@ -0,0 +1,277 @@
+# bf-breadcrumb
+
+Desktop breadcrumb trail of links to the current page, with optional collapsing
+
+`BfBreadcrumbComponent` from `@bitforgehq/ui` · Navigation · since 0.3.1
+
+## Example
+
+```ts
+import { Component, signal } from '@angular/core';
+import { RouterLink } from '@angular/router';
+import { BfBreadcrumbComponent, BfBreadcrumbItemComponent } from '@bitforgehq/ui';
+
+/**
+ * The bf-breadcrumb overview.
+ *
+ * Live demo of `bf-breadcrumb`: a five-level trail collapsed to three with `maxItems`; the ellipsis
+ * shows the hidden levels in place and moves focus to the first one, which the result line
+ * reports. The demo's links stay on this page (a fragment per level); an app links each level to
+ * its route.
+ */
+@Component({
+  selector: 'app-example-breadcrumb-overview',
+  imports: [RouterLink, BfBreadcrumbComponent, BfBreadcrumbItemComponent],
+  template: `
+    <div class="flex flex-col gap-3" (focusin)="onFocus($event)">
+      <bf-breadcrumb label="Release breadcrumb" [maxItems]="3">
+        @for (level of trail; track level.id) {
+          <li bfBreadcrumbItem>
+            <a routerLink="." [fragment]="level.id">{{ level.label }}</a>
+          </li>
+        }
+        <li bfBreadcrumbItem>Release 2.4</li>
+      </bf-breadcrumb>
+      <p data-status aria-live="polite" class="text-caption text-text-muted">{{ status() }}</p>
+    </div>
+  `,
+})
+export class BreadcrumbOverviewExampleComponent {
+  readonly status = signal('Two levels are hidden.');
+  readonly trail: readonly { id: string; label: string }[] = [
+    { id: 'workspace', label: 'Workspace' },
+    { id: 'projects', label: 'Projects' },
+    { id: 'atlas', label: 'Atlas' },
+    { id: 'releases', label: 'Releases' },
+  ];
+
+  onFocus(event: FocusEvent): void {
+    if (event.target instanceof HTMLAnchorElement) {
+      this.status.set(`Focus on ${event.target.text.trim()}.`);
+    }
+  }
+}
+```
+
+## Overview
+
+Desktop breadcrumb trail: a `nav` named "Breadcrumb" around an ordered list of
+`li[bfBreadcrumbItem]` levels, the last one the current page, a CSS chevron between them. With
+`maxItems` set and a longer trail it keeps the first level and the last `maxItems - 1`, and hides
+the middle ones behind an ellipsis button that shows them in place, or behind the consumer's own
+`bfSlot="overflow"` content (a menu button of the hidden levels).
+
+A breadcrumb trail for desktop web apps: a `nav` named "Breadcrumb" around an ordered list of the pages above the current one, each a link, with the current page last. Every level is the app's own `<li bfBreadcrumbItem>`, so the list stays `ol > li` and the links stay the app's `routerLink`s; the widget draws the chevrons between them, marks the current page and, with `maxItems`, collapses a long trail behind an ellipsis.
+
+## When to use
+
+Use `bf-breadcrumb` on a desktop page that sits deep in a hierarchy (a client's billing settings, a file in a folder), so the user sees where they are and can go up any number of levels. Don't use it for a flat app with one level, where the sidebar or the top nav already says where the user is. On mobile, in the Capacitor shell, use [bf-back-button](https://bitforge-ui.web.app/components/back-button) in [bf-header](https://bitforge-ui.web.app/components/header) instead.
+
+## Basic usage
+
+Put one `li[bfBreadcrumbItem]` per level inside `bf-breadcrumb`, from the root down: an `<a routerLink>` for each page above, plain text for the current page. The last item is always the current page; it gets `aria-current="page"` and no chevron. Import `BfBreadcrumbComponent` and `BfBreadcrumbItemComponent` from `@bitforgehq/ui`. The `nav` is named "Breadcrumb"; when a page shows more than one breadcrumb (as this page does, beside the site's own), give each a distinct `label`.
+
+```ts
+import { Component } from '@angular/core';
+import { RouterLink } from '@angular/router';
+import { BfBreadcrumbComponent, BfBreadcrumbItemComponent } from '@bitforgehq/ui';
+
+/**
+ * A breadcrumb trail.
+ *
+ * Each level is the app's own `<li bfBreadcrumbItem>` holding a router link; the last one is the
+ * current page as plain text. `label` names the `nav`; this one is not the page's only breadcrumb
+ * (the docs site has its own), so it gets a name of its own.
+ */
+@Component({
+  selector: 'app-example-breadcrumb-basic',
+  imports: [RouterLink, BfBreadcrumbComponent, BfBreadcrumbItemComponent],
+  template: `
+    <bf-breadcrumb label="Docs breadcrumb">
+      <li bfBreadcrumbItem><a routerLink="/">Docs</a></li>
+      <li bfBreadcrumbItem><a routerLink="/components">Components</a></li>
+      <li bfBreadcrumbItem>Breadcrumb</li>
+    </bf-breadcrumb>
+  `,
+})
+export class BreadcrumbBasicExampleComponent {}
+```
+
+## Collapsing a long trail
+
+Set `maxItems` to collapse a trail with more levels than that: the first level and the last `maxItems - 1` stay, and the middle ones are hidden behind an ellipsis button ("Show 2 more levels", `provideBfLabels()`'s `breadcrumbExpand`). Pressing it shows every level in place and moves focus to the first one it revealed, so a keyboard user carries on from there. The trail collapses again when its levels change (on the next page). `0`, the default, never collapses; a value below 2 acts as 2, so the first level and the current page always stay.
+
+```ts
+import { Component } from '@angular/core';
+import { RouterLink } from '@angular/router';
+import { BfBreadcrumbComponent, BfBreadcrumbItemComponent } from '@bitforgehq/ui';
+
+/**
+ * A long trail collapsed in place.
+ *
+ * `maxItems="4"` keeps the first level and the last three; the ellipsis button shows the two
+ * hidden ones in place and moves focus to the first of them. The demo's links stay on this page.
+ */
+@Component({
+  selector: 'app-example-breadcrumb-collapsed',
+  imports: [RouterLink, BfBreadcrumbComponent, BfBreadcrumbItemComponent],
+  template: `
+    <bf-breadcrumb label="Invoice breadcrumb" maxItems="4">
+      @for (level of trail; track level.id) {
+        <li bfBreadcrumbItem>
+          <a routerLink="." [fragment]="level.id">{{ level.label }}</a>
+        </li>
+      }
+      <li bfBreadcrumbItem>Invoice INV-204</li>
+    </bf-breadcrumb>
+  `,
+})
+export class BreadcrumbCollapsedExampleComponent {
+  readonly trail: readonly { id: string; label: string }[] = [
+    { id: 'home', label: 'Home' },
+    { id: 'clients', label: 'Clients' },
+    { id: 'meadow', label: 'Meadow Studio' },
+    { id: 'billing', label: 'Billing' },
+    { id: 'invoices', label: 'Invoices' },
+  ];
+}
+```
+
+## A menu of the hidden levels
+
+To keep the trail on one line, project your own control in `bfSlot="overflow"`: it takes the ellipsis button's place, after the first level. A `bf-menu-button` from `@bitforgehq/ui/overlay` with an `a[bfMenuItem]` link per hidden level is the usual one (a root widget cannot open a menu itself). The hidden levels are a slice of the array you already render: `trail.slice(1, count - maxItems + 1)`, where `count` includes the current page. Name the menu button with its `label`.
+
+```ts
+import { Component, computed } from '@angular/core';
+import { RouterLink } from '@angular/router';
+import { BfBreadcrumbComponent, BfBreadcrumbItemComponent } from '@bitforgehq/ui';
+import { BfIconComponent } from '@bitforgehq/ui/icons';
+import {
+  BfMenuButtonComponent,
+  BfMenuComponent,
+  BfMenuItemDirective,
+} from '@bitforgehq/ui/overlay';
+import { Ellipsis } from 'lucide';
+
+/**
+ * A long trail collapsed behind a menu.
+ *
+ * A `bf-menu-button` in `bfSlot="overflow"` replaces the ellipsis button: its menu links to the
+ * levels the trail hides, the same slice of the app's own array (`maxItems` 3 keeps the first
+ * level and the last two). The demo's links stay on this page.
+ */
+@Component({
+  selector: 'app-example-breadcrumb-collapsed-menu',
+  imports: [
+    RouterLink,
+    BfBreadcrumbComponent,
+    BfBreadcrumbItemComponent,
+    BfIconComponent,
+    BfMenuButtonComponent,
+    BfMenuComponent,
+    BfMenuItemDirective,
+  ],
+  template: `
+    <bf-breadcrumb label="Client breadcrumb" [maxItems]="maxItems">
+      <bf-menu-button
+        bfSlot="overflow"
+        [menu]="hiddenLevels"
+        iconOnly
+        label="Hidden levels"
+        variant="text"
+        size="sm"
+      >
+        <bf-icon [icon]="ellipsis" />
+      </bf-menu-button>
+      @for (level of trail; track level.id) {
+        <li bfBreadcrumbItem>
+          <a routerLink="." [fragment]="level.id">{{ level.label }}</a>
+        </li>
+      }
+      <li bfBreadcrumbItem>Invoice INV-204</li>
+    </bf-breadcrumb>
+
+    <ng-template #hiddenLevels>
+      <bf-menu>
+        @for (level of hidden(); track level.id) {
+          <a bfMenuItem routerLink="." [fragment]="level.id">{{ level.label }}</a>
+        }
+      </bf-menu>
+    </ng-template>
+  `,
+})
+export class BreadcrumbCollapsedMenuExampleComponent {
+  readonly ellipsis = Ellipsis;
+  readonly maxItems = 3;
+  readonly trail: readonly { id: string; label: string }[] = [
+    { id: 'home', label: 'Home' },
+    { id: 'clients', label: 'Clients' },
+    { id: 'meadow', label: 'Meadow Studio' },
+    { id: 'billing', label: 'Billing' },
+    { id: 'invoices', label: 'Invoices' },
+  ];
+  /** The levels between the first and the last `maxItems - 1` (the current page counts as one). */
+  readonly hidden = computed(() =>
+    this.trail.slice(1, this.trail.length + 1 - (this.maxItems - 1)),
+  );
+}
+```
+
+## Desktop
+
+`bf-breadcrumb` is a desktop pattern. A link turns from `text-muted` to `text` and is underlined on hover, with the pointer cursor; the ellipsis button takes a `surface-muted` fill on hover. The focus ring shows on keyboard focus only. Links keep the browser's behaviour: Ctrl/Cmd-click and a middle click open a level in a new tab. Under a coarse pointer (a touch laptop) every link is at least 44 px tall (`pointer-coarse:min-h-hit`) and the ellipsis button's hit area extends to 44 px. The trail wraps onto more lines when it does not fit; collapse it with `maxItems` to keep it short.
+
+## Theming
+
+- Text: `text-label-sm`; ancestor levels `text-muted`, `text` on hover; the current page `text`, semibold.
+- Separators: a 1.5 px CSS chevron in `text-subtle`, mirrored under `dir="rtl"`.
+- Links and the ellipsis button: `rounded-tile` and the `ring` focus ring; the ellipsis button's hover fill is `surface-muted`, its pressed fill `surface-pressed`.
+
+## Accessibility
+
+The host renders a `nav` landmark named by `label` (default "Breadcrumb", `provideBfLabels()`'s `breadcrumb`) around an `ol`, so a screen reader announces the number of levels; give a second breadcrumb on the same page another `label`. The current page is wrapped in a span with `aria-current="page"`. The chevrons are empty, `aria-hidden` elements, so the trail reads as its level names only. Hidden levels carry `hidden`, so they leave the accessibility tree until the ellipsis shows them; the ellipsis is a native `<button>` named "Show N more levels", and pressing it moves focus to the first revealed level's link (a level without a link takes focus itself). Content in `bfSlot="overflow"` brings its own name and keyboard handling.
+
+### Keyboard
+
+| Key                                 | Action                                                                        |
+| ----------------------------------- | ----------------------------------------------------------------------------- |
+| <kbd>Tab</kbd>                      | Moves through the links of the visible levels and the ellipsis button         |
+| <kbd>Enter</kbd>                    | Follows the focused link                                                      |
+| <kbd>Enter</kbd> / <kbd>Space</kbd> | On the ellipsis button: shows the hidden levels and focuses the first of them |
+
+## Inputs
+
+| Name       | Type     | Default | Description                                                                                                                                                                                                      |
+| ---------- | -------- | ------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `label`    | `string` | `''`    | Accessible name of the navigation; empty falls back to `provideBfLabels()`'s `breadcrumb` ("Breadcrumb").                                                                                                        |
+| `maxItems` | `number` | `0`     | Collapse a trail longer than this: keep the first level and the last `maxItems - 1` and hide the middle ones behind an ellipsis. `0` never collapses; values below 2 act as 2, so the current page always stays. |
+
+## Slots
+
+- `overflow`: Replaces the ellipsis button of a collapsed trail, e.g. a menu of the hidden levels.
+- `default`: The levels, each a `li[bfBreadcrumbItem]`, the current page last.
+
+## Notes
+
+### Do
+
+- Keep the labels short, the page titles users know, and the current page last as plain text.
+- Collapse a trail deeper than four or five levels with `maxItems`.
+
+### Don't
+
+- Don't link the current page, and don't put anything but `li[bfBreadcrumbItem]` levels (and the `overflow` slot) inside `bf-breadcrumb`.
+- Don't use a breadcrumb as the app's main navigation, and don't show it in the Capacitor shell.
+
+## Migration notes
+
+### 0.3.1
+
+New `bf-breadcrumb` in `@bitforgehq/ui`, the desktop breadcrumb trail: a `nav` (named by
+`label`, default `provideBfLabels()`'s new `breadcrumb` key, "Breadcrumb") around an `ol` of
+`li[bfBreadcrumbItem]` levels, with CSS chevrons between them that are never announced.
+`maxItems` collapses a longer trail to the first level and the last `maxItems - 1`, behind an
+ellipsis button (the new `breadcrumbExpand` label, "Show 2 more levels") that shows the hidden
+levels in place and focuses the first one; `bfSlot="overflow"` replaces that button with the app's
+own control, such as a `bf-menu-button` of the hidden levels. It replaces the hand-built
+breadcrumb the back-button docs showed.