@bitforgehq/ui 0.3.1 → 0.3.3

package/ai/components/empty-state.md

@@ -98,6 +98,89 @@ export class EmptyStateActionExampleComponent {
 
 Set `headingLevel` to `3` when the empty state sits inside a section that already opened with an `h2`, so the page outline stays in order.
 
+## As the page
+
+When the empty state is the whole page (a not-found page, a no-access page, an app's first run), its title is the page's heading: set `headingLevel` to `1` so it renders the `h1`, and give the page no other `h1`. Centre it in the content area: a column with a minimum height (`min-h-[60vh]`) and `justify-center`. Put the primary action first in the `actions` slot (a `bfButton` link home) and an optional secondary link after it (a `text` `bfButton`, such as "Contact support").
+
+The preview below sits inside this docs page, which already has its `h1`, so it keeps `headingLevel` 2 in a shorter area; a real page uses `1`, as in the code-only example after it.
+
+```ts
+import { Component } from '@angular/core';
+import { RouterLink } from '@angular/router';
+import { BfButtonComponent, BfEmptyStateComponent } from '@bitforgehq/ui';
+import { BfIconComponent } from '@bitforgehq/ui/icons';
+import { FileQuestionMark } from 'lucide';
+
+/**
+ * An empty state as a whole page.
+ *
+ * Centred in a tall content area, with a primary action and a secondary link. This preview sits
+ * inside a docs page that has its own `h1`, so it uses `headingLevel` 2; on a real not-found page
+ * the empty state is the page, so set it to 1 (see the next example).
+ */
+@Component({
+  selector: 'app-example-empty-state-page',
+  imports: [RouterLink, BfButtonComponent, BfEmptyStateComponent, BfIconComponent],
+  template: `
+    <div class="flex min-h-96 flex-col justify-center">
+      <bf-empty-state
+        title="Page not found"
+        description="The page may have moved, or the link has a typo."
+        [headingLevel]="2"
+      >
+        <bf-icon bfSlot="icon" [icon]="fileQuestion" size="lg" />
+        <a bfSlot="actions" bfButton routerLink="/">Go to the home page</a>
+        <a bfSlot="actions" bfButton variant="text" href="mailto:support@example.com">
+          Contact support
+        </a>
+      </bf-empty-state>
+    </div>
+  `,
+})
+export class EmptyStatePageExampleComponent {
+  protected readonly fileQuestion = FileQuestionMark;
+}
+```
+
+```ts
+import { Component } from '@angular/core';
+import { RouterLink } from '@angular/router';
+import { BfButtonComponent, BfEmptyStateComponent } from '@bitforgehq/ui';
+import { BfIconComponent } from '@bitforgehq/ui/icons';
+import { FileQuestionMark } from 'lucide';
+
+/**
+ * A not-found page whose empty state is the page heading.
+ *
+ * The route's whole content: `headingLevel` 1 renders the title as the page's `h1`, and the
+ * `min-h-[60vh]` area centres the empty state vertically in the content column.
+ *
+ * @preview none
+ */
+@Component({
+  selector: 'app-example-empty-state-not-found-page',
+  imports: [RouterLink, BfButtonComponent, BfEmptyStateComponent, BfIconComponent],
+  template: `
+    <div class="flex min-h-[60vh] flex-col justify-center">
+      <bf-empty-state
+        title="Page not found"
+        description="The page may have moved, or the link has a typo."
+        [headingLevel]="1"
+      >
+        <bf-icon bfSlot="icon" [icon]="fileQuestion" size="lg" />
+        <a bfSlot="actions" bfButton routerLink="/">Go to the home page</a>
+        <a bfSlot="actions" bfButton variant="text" href="mailto:support@example.com">
+          Contact support
+        </a>
+      </bf-empty-state>
+    </div>
+  `,
+})
+export class EmptyStateNotFoundPageExampleComponent {
+  protected readonly fileQuestion = FileQuestionMark;
+}
+```
+
 ## Theming
 
 - Icon tile: `surface-sunken` background, `text-muted` icon color, `tile` radius.
@@ -105,15 +188,15 @@ Set `headingLevel` to `3` when the empty state sits inside a section that alread
 
 ## Accessibility
 
-The title renders as an `<h2>` by default and an `<h3>` when `headingLevel` is `3`, so it slots into the surrounding page outline instead of always claiming the top level. The icon and action slots carry their own accessibility — an icon should stay decorative, and the action needs its own accessible name.
+The title renders as an `<h2>` by default, an `<h3>` when `headingLevel` is `3` and an `<h1>` when it is `1` (only when the empty state is the page and the page has no other `h1`), so it slots into the surrounding page outline instead of always claiming the top level. The icon and action slots carry their own accessibility — an icon should stay decorative, and the action needs its own accessible name.
 
 ## Inputs
 
-| Name           | Type                                  | Default  | Description                                                          |
-| -------------- | ------------------------------------- | -------- | -------------------------------------------------------------------- |
-| `title`        | `string`                              | required | What is missing, as a short title.                                   |
-| `description`  | `string`                              | `''`     | One sentence on how to fill it.                                      |
-| `headingLevel` | `BfEmptyStateHeadingLevel` (`2 \| 3`) | `2`      | Heading level of the title so the empty state fits the page outline. |
+| Name           | Type                                  | Default  | Description                                                                                 |
+| -------------- | ------------------------------------- | -------- | ------------------------------------------------------------------------------------------- |
+| `title`        | `string`                              | required | What is missing, as a short title.                                                          |
+| `description`  | `string`                              | `''`     | One sentence on how to fill it.                                                             |
+| `headingLevel` | `BfEmptyStateHeading` (`2 \| 3 \| 1`) | `2`      | Heading level of the title so the empty state fits the page outline; 1 when it is the page. |
 
 ## Slots
 
@@ -129,10 +212,20 @@ The title renders as an `<h2>` by default and an `<h3>` when `headingLevel` is `
 
 ### Don't
 
+- Don't set `headingLevel` to `1` on an empty state inside a page that already has its own `h1`.
 - Don't use `bf-empty-state` for a loading screen; that is `bf-spinner`.
 
 ## Migration notes
 
+### 0.3.2
+
+`headingLevel` now takes the new named type `BfEmptyStateHeading` (`BfEmptyStateHeadingLevel |
+1`): `1` renders the title as the page's `h1`, for an empty state that is the page (a not-found
+or no-access page). The released `BfEmptyStateHeadingLevel` keeps its two members, so `Record`s
+over it keep compiling. New "As the page" docs section with the `empty-state/page` example
+(centred in a tall area, a primary action and a secondary link) and the code-only
+`empty-state/not-found-page`.
+
 ### 0.3.0
 
 New exported `BfEmptyStateHeadingLevel` (`2 | 3`), the type of `headingLevel` (was an inline union

package/ai/components/header.md

@@ -608,7 +608,7 @@ 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 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. 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`.
+`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';
@@ -748,6 +748,19 @@ The title is not in the tab order; after a push, `bf-stack-outlet` focuses it wi
 
 ## Migration notes
 
+### 0.3.3
+
+Fix: `bf-header` measures its title and slots in the next animation frame after a resize, not
+inside the `ResizeObserver` callback. Its measurement writes the title inset and height, which
+resize the observed elements, and WebKit then reported "ResizeObserver loop completed with
+undelivered notifications": an error event that an app's global error listener
+(`provideBrowserGlobalErrorListeners()`) logs as an error. Several resizes in one frame now
+measure once.
+
+### 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

package/ai/components/sidebar-toggle.md

@@ -0,0 +1,287 @@
+# bf-sidebar-toggle
+
+Icon button inside a sidebar that collapses it to an icon rail and back
+
+`BfSidebarToggleComponent` from `@bitforgehq/ui/overlay` · Navigation · since 0.3.2
+
+## Example
+
+```ts
+import { Component, computed, signal } from '@angular/core';
+import { RouterLink, RouterLinkActive } from '@angular/router';
+import { BfNavItemComponent, BfSidebarComponent } from '@bitforgehq/ui';
+import { BfIconComponent } from '@bitforgehq/ui/icons';
+import { BfSidebarToggleComponent } from '@bitforgehq/ui/overlay';
+import { type IconNode, Layers, PanelLeftClose, PanelLeftOpen, PanelTop } from 'lucide';
+
+interface NavLink {
+  readonly path: string;
+  readonly label: string;
+  readonly icon: IconNode;
+}
+
+/**
+ * The bf-sidebar-toggle overview.
+ *
+ * Live demo of `bf-sidebar-toggle` in the header of a `bf-sidebar`: a press collapses the
+ * sidebar to an icon rail and the next one expands it again. Its name and tooltip say what the
+ * next press does, and only the matching icon slot shows. The sidebar's `[(collapsed)]` keeps
+ * the state in a signal, and the result line reports it.
+ */
+@Component({
+  selector: 'app-example-sidebar-toggle-overview',
+  imports: [
+    RouterLink,
+    RouterLinkActive,
+    BfIconComponent,
+    BfNavItemComponent,
+    BfSidebarComponent,
+    BfSidebarToggleComponent,
+  ],
+  template: `
+    <div class="border-border bg-bg rounded-card flex h-72 overflow-hidden border">
+      <bf-sidebar label="Toggle demo" [(collapsed)]="collapsed">
+        <div bfSlot="header" class="flex items-center justify-between gap-2">
+          @if (!collapsed()) {
+            <span class="text-heading text-text ps-3">Atlas</span>
+          }
+          <bf-sidebar-toggle>
+            <bf-icon bfSlot="collapse-icon" [icon]="panelClose" />
+            <bf-icon bfSlot="expand-icon" [icon]="panelOpen" />
+          </bf-sidebar-toggle>
+        </div>
+        @for (link of links; track link.path) {
+          <a bfNavItem [routerLink]="link.path" routerLinkActive ariaCurrentWhenActive="page">
+            <bf-icon bfSlot="icon" [icon]="link.icon" />
+            {{ link.label }}
+          </a>
+        }
+      </bf-sidebar>
+      <div class="min-w-0 flex-1 p-4">
+        <p data-status aria-live="polite" class="text-caption text-text-muted wrap-anywhere">
+          {{ status() }}
+        </p>
+      </div>
+    </div>
+  `,
+})
+export class SidebarToggleOverviewExampleComponent {
+  readonly collapsed = signal(false);
+  readonly status = computed(() =>
+    this.collapsed() ? 'Sidebar collapsed to an icon rail.' : 'Sidebar expanded.',
+  );
+
+  protected readonly links: readonly NavLink[] = [
+    { path: '/components/sidebar-toggle', label: 'Sidebar toggle', icon: PanelTop },
+    { path: '/components/sidebar', label: 'Sidebar', icon: Layers },
+  ];
+  protected readonly panelOpen = PanelLeftOpen;
+  protected readonly panelClose = PanelLeftClose;
+}
+```
+
+## Overview
+
+The collapse button of a `bf-sidebar`: a text icon button placed inside the sidebar (usually in
+its header or footer) that flips the sidebar between full width and an icon rail. Its name and
+tooltip say what the next press does ("Collapse sidebar", "Expand sidebar"), `aria-expanded`
+follows the sidebar and `aria-controls` points at its `nav`. It shows the `collapse-icon` slot
+while expanded and the `expand-icon` slot while collapsed. It reads and writes the sidebar's
+`collapsed` model, so `[(collapsed)]` on the sidebar sees every press. Outside a `bf-sidebar`
+(in a `bf-top-nav`, or on its own) it renders nothing.
+
+The sidebar toggle collapses a [`bf-sidebar`](https://bitforge-ui.web.app/components/sidebar) to an icon rail and expands it again, from `@bitforgehq/ui/overlay` (it shows a `bfTooltip`, so it needs `@angular/cdk`; no Capacitor). Put it inside the sidebar, in its header or footer: it reads and writes the sidebar's `collapsed` model, so the sidebar's `[(collapsed)]` sees every press and the toggle needs no binding of its own. It is a text icon button whose name and tooltip say what the next press does. Import `BfSidebarToggleComponent` from `@bitforgehq/ui/overlay`.
+
+## When to use
+
+Use `bf-sidebar-toggle` for the collapse button of a desktop app's `bf-sidebar`. Bind your own [bf-icon-button](https://bitforge-ui.web.app/components/icon-button) to the sidebar's `[(collapsed)]` instead when the button must sit outside the sidebar, in a top bar. In the Capacitor shell there is no sidebar: use [bf-tabs](https://bitforge-ui.web.app/components/tabs) with a `bf-tab-bar` instead.
+
+## Icons
+
+The toggle never picks an icon. Project two, `bfSlot="collapse-icon"` (shown while the sidebar is expanded, such as Lucide's `PanelLeftClose`) and `bfSlot="expand-icon"` (shown while it is an icon rail, `PanelLeftOpen`); only the one that matches the state shows. Under a right-to-left layout pick the mirrored icons (`PanelRightClose`, `PanelRightOpen`), since the sidebar then sits at the right.
+
+## Placement
+
+The toggle renders only inside a `bf-sidebar`. In a `bf-top-nav`, which never collapses, or on its own it renders nothing and takes no space, so a misplaced toggle never shows a button that does nothing. In the header, put it after the brand and show the brand only while expanded; in the footer, put it beside the theme menu ([footer composition](https://bitforge-ui.web.app/components/sidebar#footer)). It keeps its place in the tab order either way, so a keyboard user finds it where they left it.
+
+```ts
+import { Component, computed, signal } from '@angular/core';
+import { RouterLink, RouterLinkActive } from '@angular/router';
+import { type BfColorScheme, BfNavItemComponent, BfSidebarComponent } from '@bitforgehq/ui';
+import { BfIconComponent } from '@bitforgehq/ui/icons';
+import { BfSidebarToggleComponent, BfThemeMenuButtonComponent } from '@bitforgehq/ui/overlay';
+import {
+  Inbox,
+  type IconNode,
+  Moon,
+  PanelLeftClose,
+  PanelLeftOpen,
+  Settings,
+  Sun,
+  SunMoon,
+  Users,
+} from 'lucide';
+
+interface NavLink {
+  readonly path: string;
+  readonly label: string;
+  readonly icon: IconNode;
+}
+
+/**
+ * A sidebar footer: settings, theme, toggle and version.
+ *
+ * The footer slot holds a Settings link (`a[bfNavItem]`), a row with an icon-only
+ * `bf-theme-menu-button` and the `bf-sidebar-toggle`, and a version line. Expanded, the two
+ * buttons sit at either end of the row; as an icon rail the row stacks vertically and the version
+ * line hides. The theme binds a local signal so the docs site keeps its theme; an app binds
+ * `BfColorSchemeService.scheme`.
+ */
+@Component({
+  selector: 'app-example-sidebar-footer',
+  imports: [
+    RouterLink,
+    RouterLinkActive,
+    BfIconComponent,
+    BfNavItemComponent,
+    BfSidebarComponent,
+    BfSidebarToggleComponent,
+    BfThemeMenuButtonComponent,
+  ],
+  template: `
+    <div class="border-border bg-bg rounded-card flex h-[26rem] overflow-hidden border">
+      <bf-sidebar label="Footer demo" [(collapsed)]="collapsed">
+        @for (link of links; track link.path) {
+          <a bfNavItem [routerLink]="link.path" routerLinkActive ariaCurrentWhenActive="page">
+            <bf-icon bfSlot="icon" [icon]="link.icon" />
+            {{ link.label }}
+          </a>
+        }
+        <a
+          bfSlot="footer"
+          bfNavItem
+          routerLink="/theming"
+          routerLinkActive
+          ariaCurrentWhenActive="page"
+        >
+          <bf-icon bfSlot="icon" [icon]="settings" />
+          Settings
+        </a>
+        <div bfSlot="footer" [class]="rowClasses()">
+          <bf-theme-menu-button iconOnly variant="text" placement="above-start" [(value)]="scheme">
+            <bf-icon bfSlot="icon" [icon]="themeIcon()" />
+          </bf-theme-menu-button>
+          <bf-sidebar-toggle>
+            <bf-icon bfSlot="collapse-icon" [icon]="panelClose" />
+            <bf-icon bfSlot="expand-icon" [icon]="panelOpen" />
+          </bf-sidebar-toggle>
+        </div>
+        <p bfSlot="footer" class="text-caption text-text-muted ps-3" [class.hidden]="collapsed()">
+          Version 0.3.2
+        </p>
+      </bf-sidebar>
+      <div class="min-w-0 flex-1 p-4">
+        <p data-status aria-live="polite" class="text-caption text-text-muted wrap-anywhere">
+          {{ collapsed() ? 'Icon rail' : 'Expanded' }}, theme {{ scheme() }}.
+        </p>
+      </div>
+    </div>
+  `,
+})
+export class SidebarFooterExampleComponent {
+  readonly collapsed = signal(false);
+  /** Stands in for `BfColorSchemeService.scheme`. */
+  readonly scheme = signal<BfColorScheme>('system');
+
+  /** Expanded: one row, the buttons at either end. Collapsed: a column in the rail. */
+  protected readonly rowClasses = computed(() =>
+    this.collapsed() ? 'flex flex-col items-center gap-1' : 'flex items-center justify-between',
+  );
+  protected readonly themeIcon = computed(
+    () => ({ system: SunMoon, light: Sun, dark: Moon })[this.scheme()],
+  );
+  protected readonly links: readonly NavLink[] = [
+    { path: '/components/nav-item', label: 'Inbox', icon: Inbox },
+    { path: '/components/nav-group', label: 'Team', icon: Users },
+  ];
+  protected readonly settings = Settings;
+  protected readonly panelOpen = PanelLeftOpen;
+  protected readonly panelClose = PanelLeftClose;
+}
+```
+
+## Remembering the state
+
+The toggle holds no state. To open the app with the sidebar as the user left it, bind the sidebar to `BfSidebarStateService` from `@bitforgehq/ui` and add `provideBfSidebarState()` to the app's providers ([remember the collapsed sidebar](https://bitforge-ui.web.app/components/sidebar#remember-the-collapsed-sidebar)).
+
+## Sizes
+
+`size` is `sm` 32, `md` 40 or `lg` 48 px, square; unset it follows `provideBfDefaults()`'s `controlSize`, as `bf-icon-button` does.
+
+## Labels
+
+The name and tooltip read `sidebarCollapse` ("Collapse sidebar") while the sidebar is expanded and `sidebarExpand` ("Expand sidebar") while it is an icon rail. Translate them with `provideBfLabels()`.
+
+## Testing
+
+`BfSidebarToggleHarness` from `@bitforgehq/ui/testing` reads the name with `getLabel()`, the state with `isExpanded()` and presses it with `toggle()`; filter it with `label: 'Collapse sidebar'`.
+
+## Desktop
+
+The toggle looks and behaves like a text `bf-icon-button`: the muted text colour, a `surface-muted` fill and the pointer cursor on hover, a pressed tint while pressed, and the focus ring on keyboard focus only (`focus-visible`). Its tooltip shows after a 500 ms rest of a fine pointer and at once on keyboard focus: above the button while expanded, at the inline end of the rail while collapsed. Under a fine pointer the visible box is the hit area; under a coarse pointer (a touchscreen laptop) a `sm` or `md` toggle extends vertically to 44 px, and no tooltip shows.
+
+## Theming
+
+The toggle consumes `bf-icon-button`'s text variant: `text-muted` at rest, `text` and `surface-muted` on hover, `primary-soft-pressed` while pressed, and the `ring` token for focus. The tooltip consumes `bf-tooltip`'s tokens.
+
+## Accessibility
+
+- A native `<button type="button">` named by `aria-label`: "Collapse sidebar" while expanded, "Expand sidebar" while collapsed, so the name says what a press does. The tooltip shows the same text and describes the button while it shows.
+- `aria-expanded` is `true` while the sidebar is at full width and `false` as an icon rail; `aria-controls` points at the sidebar's `nav`.
+- The projected icons add nothing to the name (`bf-icon` is `aria-hidden`).
+- Collapsing keeps focus on the toggle, and every nav item keeps its accessible name, so nothing a screen reader user relies on moves.
+
+### Keyboard
+
+| Key                                 | Action                                           |
+| ----------------------------------- | ------------------------------------------------ |
+| <kbd>Enter</kbd> / <kbd>Space</kbd> | Collapses or expands the sidebar                 |
+| <kbd>Escape</kbd>                   | Hides the tooltip while it shows                 |
+| <kbd>Tab</kbd>                      | Moves on to the next control, hiding the tooltip |
+
+## Inputs
+
+| Name   | Type                                                        | Default     | Description                                                                                                         |
+| ------ | ----------------------------------------------------------- | ----------- | ------------------------------------------------------------------------------------------------------------------- |
+| `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). |
+
+## Slots
+
+- `collapse-icon`: The icon shown while the sidebar is expanded (a panel closing).
+- `expand-icon`: The icon shown while the sidebar is an icon rail (a panel opening).
+
+## Notes
+
+### Do
+
+- Put the toggle inside the `bf-sidebar` it collapses, in its header or footer.
+- Project both icon slots, a panel closing and a panel opening.
+- Bind the sidebar to `BfSidebarStateService.collapsed` with `provideBfSidebarState()`, so the choice survives a reload.
+
+### Don't
+
+- Don't put it outside a `bf-sidebar`; it renders nothing there. Use a `bf-icon-button` bound to `[(collapsed)]` instead.
+- Don't add your own `aria-label` or tooltip; the toggle names itself by what the next press does.
+
+## Migration notes
+
+### 0.3.2
+
+New `bf-sidebar-toggle` in `@bitforgehq/ui/overlay`: a text icon button placed inside a
+`bf-sidebar` (header or footer) that flips the sidebar between full width and an icon rail by
+writing its `collapsed` model, so `[(collapsed)]` sees every press. Its name and `bfTooltip` say
+what the next press does (new label keys `sidebarCollapse` "Collapse sidebar" and `sidebarExpand`
+"Expand sidebar"); `aria-expanded` follows the sidebar and `aria-controls` points at its `nav`.
+Icons are the `collapse-icon` and `expand-icon` slots, only the matching one shown; `size` as
+`bf-icon-button`. Outside a sidebar (in a `bf-top-nav`, or alone) it renders nothing. A
+`BfSidebarToggleHarness` in `@bitforgehq/ui/testing` (`getLabel()`, `isExpanded()`, `toggle()`).