@bitforgehq/ui 0.3.0 → 0.3.2

package/ai/components/header.md

@@ -103,7 +103,7 @@ the collapse is pure CSS and scrolling never schedules Angular change detection.
 
 ## When to use
 
-Use `bf-header` at the top of every `bf-page` in the Capacitor shell: the bar with its start and end actions and the collapsing large title. Use a plain `h1` and a toolbar row of [bf-button](https://bitforge-ui.web.app/components/button)s instead on a desktop web page, and [bf-back-button](https://bitforge-ui.web.app/components/back-button) in its `start` slot on a pushed page.
+Use `bf-header` at the top of every `bf-page` in the Capacitor shell: the bar with its start and end actions and the collapsing large title. Use [bf-page-header](https://bitforge-ui.web.app/components/page-header) instead on a desktop web page, and [bf-back-button](https://bitforge-ui.web.app/components/back-button) in its `start` slot on a pushed page.
 
 ## Basic usage
 
@@ -608,7 +608,67 @@ inside one.
 
 ## Desktop
 
-`bf-header` is part of the Capacitor shell (`provideBfShell()`), shaped like an iOS or Material app bar. On a desktop web page, give the page a plain `h1` and put its actions in a toolbar row of [bf-button](https://bitforge-ui.web.app/components/button)s and a [bf-menu-button](https://bitforge-ui.web.app/components/menu-button); the large title and the scroll-under surface are phone patterns. Under the shell, a browser window shorter than 500 px gets the compact bar (no large title), as a phone in landscape does.
+`bf-header` is part of the Capacitor shell (`provideBfShell()`), shaped like an iOS or Material app bar. On a desktop web page use [bf-page-header](https://bitforge-ui.web.app/components/page-header): the page's one `h1` (`title`) with an optional `subtitle`, badges in `meta`, and the actions in `actions` (the main action as a primary [bf-button](https://bitforge-ui.web.app/components/button), secondary ones as `ghost` or `outline` buttons, the rest in an icon-only [bf-menu-button](https://bitforge-ui.web.app/components/menu-button) labelled "More actions"); the actions wrap under the title in a narrow window. On a nested page, put a [bf-breadcrumb](https://bitforge-ui.web.app/components/breadcrumb) in its `breadcrumb` slot, and a [bf-toolbar](https://bitforge-ui.web.app/components/toolbar) under it for search and filters. Below the breakpoint, [bf-app-frame](https://bitforge-ui.web.app/components/app-frame) supplies the app-level header bar (brand, navigation menu, actions) above the page header. The two are siblings rather than one shell-aware widget: the large title and the scroll-under surface are phone patterns that depend on `bf-content`.
+
+```ts
+import { Component, signal } from '@angular/core';
+import { 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 desktop replacement for a header: a bf-page-header.
+ *
+ * The page's `h1` with a subtitle, and its actions in the `actions` slot: a ghost button, the
+ * primary action and a menu button for the rest; the actions wrap under the title in a narrow
+ * window.
+ */
+@Component({
+  selector: 'app-example-header-desktop-header',
+  imports: [
+    BfButtonComponent,
+    BfIconComponent,
+    BfMenuButtonComponent,
+    BfMenuComponent,
+    BfMenuItemDirective,
+    BfPageHeaderComponent,
+  ],
+  template: `
+    <bf-page-header title="Atlas rebrand" subtitle="12 of 18 tasks done · due Friday">
+      <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">
+        <bf-icon [icon]="ellipsis" />
+      </bf-menu-button>
+    </bf-page-header>
+    <p aria-live="polite" class="text-caption text-text-muted mt-3">{{ status() }}</p>
+
+    <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 HeaderDesktopHeaderExampleComponent {
+  protected readonly plus = Plus;
+  protected readonly ellipsis = Ellipsis;
+  protected readonly status = signal('');
+}
+```
+
+Under the shell, a browser window shorter than 500 px gets the compact bar (no large title), as a phone in landscape does.
 
 ## Theming
 
@@ -688,6 +748,15 @@ The title is not in the tab order; after a push, `bf-stack-outlet` focuses it wi
 
 ## Migration notes
 
+### 0.3.2
+
+The `## Desktop` docs say `bf-app-frame` supplies the app-level header bar below its breakpoint.
+
+### 0.3.1
+
+The `## Desktop` docs and When to use name the desktop replacement, `bf-page-header` (with
+`bf-breadcrumb` and `bf-toolbar`), with an example. No code change.
+
 ### 0.3.0
 
 JSDoc of `header.component.ts` for the API reference: `@slot` docs for `start`, `default`, `end`. No

package/ai/components/icon-button.md

@@ -60,8 +60,12 @@ export class IconButtonOverviewExampleComponent {
 
 ## Overview
 
+Also matches: `a[bfIconButton]`
+
 Round button that holds a single icon, for toolbars, headers and list rows. The `label` is
-required because the icon alone gives assistive tech no name.
+required because the icon alone gives assistive tech no name. For navigation, put
+`bfIconButton` on your own `<a>` (with `href` or `routerLink`): it renders as a real link that
+looks like the icon button.
 
 A round button for a single icon: search in a header, close on a sheet, more-actions on a row. `label` is required and becomes the accessible name.
 
@@ -133,6 +137,47 @@ export class IconButtonVariantsExampleComponent {
 }
 ```
 
+## As a link
+
+An icon-only "back", "open" or "edit" that navigates is a link: put `bfIconButton` on your own `<a>` and give it `href` or `routerLink`. The `<a>` takes the icon button's variant, size, focus ring and hit area itself (no inner `<button>`, no underline), and `label` becomes its `aria-label`, so it still has a name. The browser treats it as a link: Enter follows it (Space does not), Ctrl/Cmd-click and a middle click open it in a new tab, and the URL shows on hover. `clicked` still emits on every click. `type` and `disabled` do not apply: a link is never disabled, so render a disabled `bf-icon-button` while the destination is unavailable. This mirrors `a[bfButton]` ([bf-button](https://bitforge-ui.web.app/components/button)).
+
+```ts
+import { Component } from '@angular/core';
+import { RouterLink } from '@angular/router';
+import { BfIconButtonComponent } from '@bitforgehq/ui';
+import { BfIconComponent } from '@bitforgehq/ui/icons';
+import { ArrowLeft, ExternalLink, Pencil } from 'lucide';
+
+/**
+ * Icon-only links.
+ *
+ * `bfIconButton` on your own `<a>`: a back link and an edit link with `routerLink`, and an
+ * external link with `href`. Each `label` is the link's accessible name.
+ */
+@Component({
+  selector: 'app-example-icon-button-link',
+  imports: [RouterLink, BfIconButtonComponent, BfIconComponent],
+  template: `
+    <div class="flex items-center gap-3">
+      <a bfIconButton variant="text" label="Back to components" routerLink="/components">
+        <bf-icon [icon]="arrowLeft" />
+      </a>
+      <a bfIconButton label="Edit the button page" routerLink="/components/button">
+        <bf-icon [icon]="pencil" />
+      </a>
+      <a bfIconButton variant="outline" label="Open bitforge.ch" href="https://bitforge.ch">
+        <bf-icon [icon]="externalLink" />
+      </a>
+    </div>
+  `,
+})
+export class IconButtonLinkExampleComponent {
+  protected readonly arrowLeft = ArrowLeft;
+  protected readonly pencil = Pencil;
+  protected readonly externalLink = ExternalLink;
+}
+```
+
 ## Desktop
 
 Hover tints the button (`tonal`, `text`) or darkens it (`primary`, the `outline` border), with the pointer cursor; disabled shows `not-allowed`. Hover styles apply only on devices that can hover, so a tap never leaves one stuck. The focus ring shows on keyboard focus only. There is no built-in tooltip, and `label` is read by assistive tech only, so keep to icons whose meaning is clear without one. Under a fine pointer the 32/40/48 px square is the hit area. Desktop density is the default `md` step; `provideBfDefaults({ size: 'sm' })`, or `{ size: 'sm' }` in a component's `providers`, makes a dense toolbar, table or sidebar ([density guide](https://bitforge-ui.web.app/density)).
@@ -154,30 +199,33 @@ Cursor: `pointer` while enabled, `not-allowed` when disabled. Disabled (any vari
 
 ## Accessibility
 
-Native `<button>`; its `type` reflects the `type` input. `label` is required and becomes the button's `aria-label`, since the icon inside carries no text of its own. `disabled` sets the native attribute, which also removes it from the tab order and swallows clicks.
+`bf-icon-button` renders a native `<button>`; its `type` reflects the `type` input. `label` is required and becomes the button's `aria-label`, since the icon inside carries no text of its own. `disabled` sets the native attribute, which also removes it from the tab order and swallows clicks.
+
+`a[bfIconButton]` is your own `<a>`, so it keeps the link role and link keyboard behaviour ([WAI-ARIA APG link pattern](https://www.w3.org/WAI/ARIA/apg/patterns/link/)), with `label` as its `aria-label`. It is in the tab order while it has an `href` (in Safari and iOS WKWebView, Tab reaches links only when the user turns on "Press Tab to highlight each item" (Option+Tab otherwise); VoiceOver and Full Keyboard Access are unaffected). Use it whenever activation navigates to a URL.
 
 ### Keyboard
 
-| Key                                 | Action                                                 |
-| ----------------------------------- | ------------------------------------------------------ |
-| <kbd>Tab</kbd>                      | Moves focus to the button; a `disabled` one is skipped |
-| <kbd>Enter</kbd> / <kbd>Space</kbd> | Activates it and emits `clicked`                       |
+| Key                                 | Action                                                         |
+| ----------------------------------- | -------------------------------------------------------------- |
+| <kbd>Tab</kbd>                      | Moves focus to the button; a `disabled` one is skipped         |
+| <kbd>Enter</kbd> / <kbd>Space</kbd> | `bf-icon-button`: activates it and emits `clicked`             |
+| <kbd>Enter</kbd>                    | `a[bfIconButton]`: follows the link; <kbd>Space</kbd> does not |
 
 ## Inputs
 
-| Name       | Type                                                                  | Default     | Description                                                                                                         |
-| ---------- | --------------------------------------------------------------------- | ----------- | ------------------------------------------------------------------------------------------------------------------- |
-| `variant`  | `BfIconButtonVariant` (`'tonal' \| 'primary' \| 'outline' \| 'text'`) | `'tonal'`   | Visual style: tonal (soft tint, default), primary, outline, text.                                                   |
-| `size`     | `BfSize \| undefined` (`'sm' \| 'md' \| 'lg' \| undefined`)           | `undefined` | Height step: sm 32, md 40, lg 48 px (square); unset follows `provideBfDefaults()` (`controlSize`, `md` by default). |
-| `type`     | `BfButtonType` (`'button' \| 'submit' \| 'reset'`)                    | `'button'`  | Native button type.                                                                                                 |
-| `disabled` | `boolean`                                                             | `false`     | Disables the control and swallows clicks.                                                                           |
-| `label`    | `string`                                                              | required    | Accessible name announced instead of the icon.                                                                      |
+| Name       | Type                                                                  | Default     | Description                                                                                                                                   |
+| ---------- | --------------------------------------------------------------------- | ----------- | --------------------------------------------------------------------------------------------------------------------------------------------- |
+| `variant`  | `BfIconButtonVariant` (`'tonal' \| 'primary' \| 'outline' \| 'text'`) | `'tonal'`   | Visual style: tonal (soft tint, default), primary, outline, text.                                                                             |
+| `size`     | `BfSize \| undefined` (`'sm' \| 'md' \| 'lg' \| undefined`)           | `undefined` | Height step: sm 32, md 40, lg 48 px (square); unset follows `provideBfDefaults()` (`controlSize`, `md` by default).                           |
+| `type`     | `BfButtonType` (`'button' \| 'submit' \| 'reset'`)                    | `'button'`  | Native button type. Ignored on `a[bfIconButton]`.                                                                                             |
+| `disabled` | `boolean`                                                             | `false`     | Disables the control and swallows clicks. Ignored on `a[bfIconButton]`: a link is never disabled; render a disabled `bf-icon-button` instead. |
+| `label`    | `string`                                                              | required    | Accessible name announced instead of the icon; on `a[bfIconButton]`, the link's `aria-label`.                                                 |
 
 ## Outputs
 
-| Name      | Payload | Description                     |
-| --------- | ------- | ------------------------------- |
-| `clicked` | `Event` | Emitted on click while enabled. |
+| Name      | Payload | Description                                                                                      |
+| --------- | ------- | ------------------------------------------------------------------------------------------------ |
+| `clicked` | `Event` | Emitted on click while enabled; on `a[bfIconButton]`, on every click (the link still navigates). |
 
 ## Slots
 
@@ -189,13 +237,23 @@ Native `<button>`; its `type` reflects the `type` input. `label` is required and
 
 - Write the label as the action ("Search", "Close"), not the icon name.
 - Use `text` inside list rows and cards so the row stays calm.
+- Use `a[bfIconButton]` for an icon-only link (back, open, edit page), never a `bf-icon-button` that navigates in `(clicked)`.
 
 ### Don't
 
 - Don't put text in the slot; use `bf-button` with an icon slot instead.
+- Don't disable a link; render a disabled `bf-icon-button` while the destination is unavailable.
 
 ## Migration notes
 
+### 0.3.1
+
+New `a[bfIconButton]` selector: put `bfIconButton` on your own `<a>` (with `href` or `routerLink`)
+for an icon-only link such as back, open or edit. The `<a>` takes the variant, size, focus ring
+and touch hit area, `label` becomes its `aria-label` (still required), and it behaves as a link
+(Enter, Ctrl/Cmd-click and middle click open it; `clicked` emits on every click). `type` and
+`disabled` do not apply, as on `a[bfButton]`. The `bf-icon-button` element is unchanged.
+
 ### 0.3.0
 
 **Behaviour:** `size` is a `BfSize` and, unset, follows `provideBfDefaults()`'s `controlSize`. The

package/ai/components/icon.md

@@ -45,7 +45,7 @@ export class IconOverviewExampleComponent {
 Renders a Lucide icon from its data, tree-shakably and without a registry.
 Import the icon you need from `lucide` (e.g. `import { Search } from 'lucide'`) and bind it.
 Decorative by default; pass `label` when the icon carries meaning on its own (e.g. an icon-only
-control without visible text).
+control without visible text). `filled` fills a solid shape such as a heart or a star.
 
 Renders a Lucide icon from its data. Import the icon you need from `lucide` and bind it; nothing is registered globally and unused icons are tree-shaken. Every widget's icon slot accepts a `bf-icon`, and also any other SVG or component, including privately licensed icon sets.
 
@@ -119,9 +119,52 @@ export class IconFilledExampleComponent {
 }
 ```
 
+## Filled shapes
+
+`filled` fills the whole shape with `currentColor` and keeps the stroke, for a state that an outline alone makes too easy to miss: a favourite heart, a starred item, a saved bookmark. Bind it to the state (`[filled]="favourite()"`). Only icons whose every shape is closed are filled (`Heart`, `Star`, `Bookmark`, `Circle`, `Square`); an icon with an open stroke stays an outline, because filling it would paint the area a check mark or a line encloses, or hide inner strokes (the check of `CircleCheck`, the clapper of `Bell`) under the same colour. So `filled` on a pure line icon does nothing.
+
+```ts
+import { Component, signal } from '@angular/core';
+import { BfButtonComponent, BfIconButtonComponent } from '@bitforgehq/ui';
+import { BfIconComponent } from '@bitforgehq/ui/icons';
+import { Heart, Star } from 'lucide';
+
+/**
+ * Filled heart and star toggles.
+ *
+ * `filled` follows the state, and the control's name says it too: the icon button's label
+ * changes, and the button's text does.
+ */
+@Component({
+  selector: 'app-example-icon-filled-shape',
+  imports: [BfButtonComponent, BfIconButtonComponent, BfIconComponent],
+  template: `
+    <div class="flex flex-wrap items-center gap-3">
+      <bf-icon-button
+        variant="text"
+        [label]="favourite() ? 'Remove from favourites' : 'Add to favourites'"
+        (clicked)="favourite.update((on) => !on)"
+      >
+        <bf-icon [icon]="heart" [filled]="favourite()" [class.text-danger]="favourite()" />
+      </bf-icon-button>
+      <bf-button variant="ghost" (clicked)="starred.update((on) => !on)">
+        <bf-icon bfSlot="icon-start" [icon]="star" [filled]="starred()" />
+        {{ starred() ? 'Starred' : 'Star' }}
+      </bf-button>
+    </div>
+  `,
+})
+export class IconFilledShapeExampleComponent {
+  protected readonly heart = Heart;
+  protected readonly star = Star;
+  protected readonly favourite = signal(true);
+  protected readonly starred = signal(false);
+}
+```
+
 ## Theming
 
-`bf-icon` defines no color of its own; its stroke (and any fill Lucide sets) uses `currentColor`, so it takes on whatever text color its parent sets (a class like `text-text-muted`, or the button/link text color around it).
+`bf-icon` defines no color of its own; its stroke (and any fill Lucide sets, and the `filled` shape) uses `currentColor`, so it takes on whatever text color its parent sets (a class like `text-text-muted`, or the button/link text color around it).
 
 ## Accessibility
 
@@ -143,13 +186,16 @@ export class IconLabelledExampleComponent {
 }
 ```
 
+A filled icon is a picture of a state, and assistive tech never sees it: put the state in the control as well, in its name ("Remove from favourites", "Starred") or with `aria-pressed` on a toggle button, never in the fill alone. The fill also must not be the only visible cue where colour carries the meaning; a filled shape plus a changed label is enough.
+
 ## Inputs
 
-| Name    | Type                                  | Default  | Description                                                             |
-| ------- | ------------------------------------- | -------- | ----------------------------------------------------------------------- |
-| `icon`  | `IconNode`                            | required | Lucide icon data, e.g. `Search` from `lucide`.                          |
-| `size`  | `BfIconSize` (`'sm' \| 'md' \| 'lg'`) | `'md'`   | Visual size: 16, 20 or 24 px.                                           |
-| `label` | `string`                              | `''`     | Accessible name. Leave empty for decorative icons next to visible text. |
+| Name     | Type                                  | Default  | Description                                                                                                                                                                                                                         |
+| -------- | ------------------------------------- | -------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `icon`   | `IconNode`                            | required | Lucide icon data, e.g. `Search` from `lucide`.                                                                                                                                                                                      |
+| `size`   | `BfIconSize` (`'sm' \| 'md' \| 'lg'`) | `'md'`   | Visual size: 16, 20 or 24 px.                                                                                                                                                                                                       |
+| `label`  | `string`                              | `''`     | Accessible name. Leave empty for decorative icons next to visible text.                                                                                                                                                             |
+| `filled` | `boolean`                             | `false`  | Fills the shape with `currentColor` (a favourite heart, a starred item); the stroke stays. Only icons whose every shape is closed are filled; a stroke icon (a check, a line) or an outline holding inner strokes renders as usual. |
 
 ## Notes
 
@@ -157,14 +203,24 @@ export class IconLabelledExampleComponent {
 
 - Put icons in a widget's `icon-start` / `icon-end` slot rather than in its default slot.
 - Use `label` only when there is no visible text saying the same thing.
+- Bind `filled` to a state and put the same state in the control's name or `aria-pressed`.
 
 ### Don't
 
 - Don't inline `<svg>` markup in app templates; use `bf-icon` or an icon component.
+- Don't expect `filled` to fill a stroke icon (a check, an arrow); it leaves those as outlines.
 - Don't ship Streamline pro icons in a public package; use them in your app's private code through the slots.
 
 ## Migration notes
 
+### 0.3.1
+
+New `filled` input: fills the shape with `currentColor` and keeps the stroke, for a favourite
+heart or a starred item. Only icons whose every shape is closed are filled (`Heart`, `Star`,
+`Bookmark`, …); a stroke icon or an outline holding inner strokes renders as before, so `filled`
+never paints the area a check mark encloses or hides a stroke. Put the state in the control's name
+or `aria-pressed` too.
+
 ### 0.3.0
 
 JSDoc of `icon.component.ts` for the API reference: `@summary`/`@since` on the exported symbols. No

package/ai/components/line-chart.md

@@ -0,0 +1,234 @@
+# bf-line-chart
+
+Line chart of series over categories, with tooltip, legend and data table
+
+`BfLineChartComponent` from `@bitforgehq/ui/charts` · Data display · since 0.3.1
+
+## Example
+
+```ts
+import { Component, computed, signal } from '@angular/core';
+import { BfSegmentedComponent, type BfSegmentOption } from '@bitforgehq/ui';
+import { BfLineChartComponent, type BfChartSeries } from '@bitforgehq/ui/charts';
+
+type Period = 'week' | 'quarter' | 'year';
+
+interface PeriodData {
+  readonly categories: readonly string[];
+  readonly series: readonly BfChartSeries[];
+}
+
+const DATA: Record<Period, PeriodData> = {
+  week: {
+    categories: ['Mon', 'Tue', 'Wed', 'Thu', 'Fri', 'Sat', 'Sun'],
+    series: [
+      { name: 'Online', values: [3.2, 3.8, 3.5, 4.1, 4.6, 5.9, 5.2] },
+      { name: 'In store', values: [2.1, 2.4, 2.2, 2.6, 3.4, 4.8, 3.1] },
+    ],
+  },
+  quarter: {
+    categories: ['Jul', 'Aug', 'Sep'],
+    series: [
+      { name: 'Online', values: [96, 104, 121] },
+      { name: 'In store', values: [71, 64, 78] },
+    ],
+  },
+  year: {
+    categories: [
+      'Jan',
+      'Feb',
+      'Mar',
+      'Apr',
+      'May',
+      'Jun',
+      'Jul',
+      'Aug',
+      'Sep',
+      'Oct',
+      'Nov',
+      'Dec',
+    ],
+    series: [
+      { name: 'Online', values: [62, 58, 71, 76, 83, 88, 96, 104, 121, 118, 139, 162] },
+      { name: 'In store', values: [54, 51, 57, 60, 66, 69, 71, 64, 78, 80, 92, 121] },
+    ],
+  },
+};
+
+/**
+ * The bf-line-chart overview.
+ *
+ * Live demo of `bf-line-chart`: revenue online and in store in thousands of francs, with a
+ * segmented period switch above it. Hover the plot, or focus it and use the arrow keys; hide a
+ * series in the legend; open Show data for the table.
+ */
+@Component({
+  selector: 'app-example-line-chart-overview',
+  imports: [BfLineChartComponent, BfSegmentedComponent],
+  template: `
+    <div class="flex w-full flex-col gap-4">
+      <bf-segmented label="Period" [options]="periods" [(value)]="period" />
+      <bf-line-chart
+        label="Revenue by channel"
+        [series]="data().series"
+        [categories]="data().categories"
+        [valueFormat]="format"
+      />
+      <p data-status aria-live="polite" class="text-caption text-text-muted">
+        Showing {{ data().categories.length }} points: {{ periodLabel() }}
+      </p>
+    </div>
+  `,
+})
+export class LineChartOverviewExampleComponent {
+  readonly periods: BfSegmentOption<Period>[] = [
+    { value: 'week', label: 'Week' },
+    { value: 'quarter', label: 'Quarter' },
+    { value: 'year', label: 'Year' },
+  ];
+  readonly period = signal<Period | null>('year');
+  readonly data = computed(() => DATA[this.period() ?? 'year']);
+  readonly periodLabel = computed(
+    () => this.periods.find((p) => p.value === this.period())?.label ?? '',
+  );
+
+  private readonly francs = new Intl.NumberFormat('en', { maximumFractionDigits: 1 });
+  /** Thousands of francs, as "CHF 121k". */
+  readonly format = (value: number): string => `CHF ${this.francs.format(value)}k`;
+}
+```
+
+## Overview
+
+A line chart of one or more series over shared categories (months, days, steps), drawn in SVG
+with the chart palette: value axis with nice ticks and grid lines, a legend that shows and
+hides series, a crosshair 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. `area` fills under
+each line; `curve="smooth"` draws a monotone curve. The lines draw in on the first render and on
+every data change, still under reduced motion; under `dir="rtl"` the categories run from the
+right.
+
+A line chart shows how one or more values change over shared categories: revenue per month, sign-ups per day, response time per release. `bf-line-chart` draws it in SVG from `series` (each a `name` and one value per category, `null` for a gap) and `categories`, with a value axis of nice ticks, a legend that shows and hides series, a crosshair tooltip on hover and on keyboard focus, and a Show data table. It lives in its own entry point, `@bitforgehq/ui/charts` (`import { BfLineChartComponent } from '@bitforgehq/ui/charts'`), which needs nothing beyond the widgets entry, and it works the same in a desktop web app and in the Capacitor shell.
+
+## When to use
+
+Use `bf-line-chart` for a trend over an ordered axis (time, steps, versions), with up to about eight series. Our charts are themed with the `--color-chart-*` tokens, follow dark mode, density and `dir="rtl"`, and bring their own legend, tooltip, keyboard reading and data table, so reach for them before a chart library; bring a library (and theme it with the same chart tokens) only for a form they do not draw, such as a scatter plot, a map or a zoomable time series of thousands of points. Use [bf-bar-chart](https://bitforge-ui.web.app/components/bar-chart) instead to compare amounts between categories that have no order, [bf-sparkline](https://bitforge-ui.web.app/components/sparkline) for a tiny trend beside a figure, and put the chart in a [bf-chart-card](https://bitforge-ui.web.app/components/chart-card) for a title, a period control and loading states.
+
+## Area and curve
+
+`area` fills under each line in its series' colour at 16 %, and starts the value axis at zero so the filled area stays honest. `curve="smooth"` draws a monotone cubic curve through the points: it never overshoots a value, so a plateau stays flat and a peak is never drawn higher than it was. Without `area` the value axis spans the data, rounded out to nice numbers.
+
+```ts
+import { Component } from '@angular/core';
+import { BfLineChartComponent, type BfChartSeries } from '@bitforgehq/ui/charts';
+
+/**
+ * A smooth area chart.
+ *
+ * `area` fills under the line and starts the value axis at zero; `curve="smooth"` draws a
+ * monotone curve that never overshoots a value. Active users per week, with a gap where the
+ * tracking was down.
+ */
+@Component({
+  selector: 'app-example-line-chart-area',
+  imports: [BfLineChartComponent],
+  template: `
+    <bf-line-chart
+      label="Weekly active users"
+      area
+      curve="smooth"
+      [height]="200"
+      [series]="series"
+      [categories]="weeks"
+    />
+  `,
+})
+export class LineChartAreaExampleComponent {
+  readonly weeks = ['W1', 'W2', 'W3', 'W4', 'W5', 'W6', 'W7', 'W8'];
+  readonly series: readonly BfChartSeries[] = [
+    { name: 'Active users', values: [1240, 1310, 1290, null, 1480, 1620, 1610, 1790] },
+  ];
+}
+```
+
+## Data and formatting
+
+Each series has one value per category, in the categories' order; `null` (or a missing value) leaves a gap in the line, and a point with gaps on both sides draws as a dot. `valueFormat` formats every value on the axis, in the tooltip, the announcement and the table, for a unit or a currency (`(v) => formatter.format(v)`); unset, values use `Intl.NumberFormat` in the document's language. The colour of a series follows its position (`--color-chart-1` for the first): hiding one in the legend never repaints the others. The lines draw in on the first render and again whenever `series` or `categories` change.
+
+## Size
+
+`height` sets the plot's height in px (240 by default); the width follows the container, measured with a `ResizeObserver`, so a chart in a grid column or a card reflows by itself. Category labels thin out when they would collide. On the server, before the first measure, the chart draws at 600 px wide and scales to its box.
+
+## Desktop
+
+Under a mouse, hovering the plot shows the crosshair, a ring marker on each line and the tooltip of the nearest category; 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, and the arrow keys move from there. Under a coarse pointer (touch) a tap or a drag across the plot moves the 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
+
+- Lines: `--color-chart-1` … `--color-chart-8` by series (`stroke-chart-n`), 2 px; areas the same colour at 16 % (`fill-chart-n/16`).
+- Grid lines: `chart-grid`; the baseline and the crosshair: `chart-axis`; axis text: `text-micro` in `text-muted`.
+- Markers: `surface` fill with the series' colour as a 2 px ring.
+- Tooltip: `surface`, a `border` edge, `shadow-floating`, `rounded-tile`, `text-caption`.
+- Legend: `text-caption` in `text-secondary` (a hidden series in `text-muted`, struck through, its swatch an empty `text-subtle` ring); hover `surface-muted`.
+- Show data: `text-label-xs` in `primary-text`; the table takes `bf-table`'s look (`border`, `divider`, `text-label-xs` headers in `text-muted`).
+- Motion: `--animate-chart-draw` (the line) and `--animate-chart-fade` (the area); none under `prefers-reduced-motion`.
+
+## Accessibility
+
+The chart is a native `figure` named by `label` (else the `bf-chart-card` title, else `provideBfLabels()`'s `chart`); 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 ("Mar: Online 15, Store 11", a dash for a gap). The tooltip repeats what the region reads and is hidden from assistive technology. The legend is a group of toggle buttons (`aria-pressed`) named by the `chartLegend` label. The Show data button (`aria-expanded`, `aria-controls`) shows the data as a native `table` with a `caption`, a header row and a row header per category. Every series is ≥ 3:1 against `surface` and `bg` in both modes, and the legend names each colour, so no value rests on colour alone.
+
+### 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>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 horizontal 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.                                                                    |
+| `area`        | `boolean`                                                                         | `false`     | Fills the area under each line in the series' colour (the value axis then starts at zero).                                   |
+| `curve`       | `BfChartCurve` (`'linear' \| 'smooth'`)                                           | `'linear'`  | The line between points: `linear` (default) or `smooth`, a monotone curve.                                                   |
+| `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
+
+- Give every chart a `label` that says what it shows ("Revenue by month, 2026"), or put it in a `bf-chart-card` with a title.
+- Format values with their unit in `valueFormat`, so the axis, the tooltip and the table read the same.
+
+### Don't
+
+- Don't draw more than eight series; fold the smallest into an "Other" series or split the chart.
+- Don't put two measures of different scale on one chart; draw two charts.
+
+## Migration notes
+
+### 0.3.1
+
+New `bf-line-chart` in the new `@bitforgehq/ui/charts` entry (which imports only Angular core and
+common and the root entry): one or more `series` (`BfChartSeries`: `name`, `values` with `null`
+for a gap) over `categories`, drawn in SVG with the `--color-chart-*` tokens. A value axis of nice
+ticks (1, 2 or 5 × 10ⁿ), a legend that shows and hides series (`aria-pressed`; `legend`:
+`BfChartLegendPosition` `top`, `bottom` or `none`), a crosshair tooltip with markers on hover and
+on keyboard focus (the plot is focusable; the arrow keys, `Home`, `End` and `Escape` move between
+the categories and a polite live region reads each one), and a Show data toggle that shows the data
+as a table. `area` fills under the lines, `curve` (`BfChartCurve`: `linear` or `smooth`, a monotone
+cubic) shapes them, `valueFormat` formats every value (default `Intl.NumberFormat` in the document's
+language), `height` sets the plot's height and the width follows the container (`ResizeObserver`;
+600 px on the server). Lines draw in on the first render and on every data change, not under
+reduced motion; `dir="rtl"` mirrors the category axis.
+New `BfChartHarness` in `@bitforgehq/ui/testing` for the line, bar and donut charts:
+`getLabel()`, `getSeriesNames()`, `isSeriesShown()`, `toggleSeries()` and `showData()` (the data
+table's rows).