@bitforgehq/ui 0.3.0 → 0.3.2

package/ai/components/sidebar.md

@@ -0,0 +1,541 @@
+# bf-sidebar
+
+Vertical app navigation with brand, grouped links, footer and an icon rail mode
+
+`BfSidebarComponent` from `@bitforgehq/ui` · Navigation · since 0.3.1
+
+## Example
+
+```ts
+import { Component, computed, signal } from '@angular/core';
+import { RouterLink, RouterLinkActive } from '@angular/router';
+import {
+  BfIconButtonComponent,
+  BfNavGroupComponent,
+  BfNavItemComponent,
+  BfSidebarComponent,
+} from '@bitforgehq/ui';
+import { BfIconComponent } from '@bitforgehq/ui/icons';
+import {
+  BookOpen,
+  Layers,
+  type IconNode,
+  PanelLeftClose,
+  PanelLeftOpen,
+  PanelTop,
+  Rows3,
+  Settings,
+  Smartphone,
+} from 'lucide';
+
+interface NavLink {
+  readonly path: string;
+  readonly label: string;
+  readonly icon: IconNode;
+  readonly badge?: number;
+}
+
+/**
+ * The bf-sidebar overview.
+ *
+ * Live demo of `bf-sidebar`: a brand and a collapse toggle in the header, two `bf-nav-group`s of
+ * `a[bfNavItem]` router links (this page is the current one, one item has a count badge) and a
+ * footer link. The toggle binds `[(collapsed)]`; collapsed, the items show their icon only and
+ * name themselves in a tooltip. The result line reports the state.
+ */
+@Component({
+  selector: 'app-example-sidebar-overview',
+  imports: [
+    RouterLink,
+    RouterLinkActive,
+    BfIconComponent,
+    BfIconButtonComponent,
+    BfNavGroupComponent,
+    BfNavItemComponent,
+    BfSidebarComponent,
+  ],
+  template: `
+    <div class="border-border bg-bg rounded-card flex h-96 overflow-hidden border">
+      <bf-sidebar label="Docs" [(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-icon-button
+            variant="text"
+            [label]="collapsed() ? 'Expand sidebar' : 'Collapse sidebar'"
+            (clicked)="collapsed.set(!collapsed())"
+          >
+            <bf-icon [icon]="collapsed() ? panelOpen : panelClose" />
+          </bf-icon-button>
+        </div>
+        <bf-nav-group label="Desktop">
+          @for (link of desktop; track link.path) {
+            <a
+              bfNavItem
+              [routerLink]="link.path"
+              routerLinkActive
+              ariaCurrentWhenActive="page"
+              [badge]="link.badge ?? null"
+            >
+              <bf-icon bfSlot="icon" [icon]="link.icon" />
+              {{ link.label }}
+            </a>
+          }
+        </bf-nav-group>
+        <bf-nav-group label="Shell">
+          @for (link of shell; track link.path) {
+            <a
+              bfNavItem
+              [routerLink]="link.path"
+              routerLinkActive
+              ariaCurrentWhenActive="page"
+              [badge]="link.badge ?? null"
+            >
+              <bf-icon bfSlot="icon" [icon]="link.icon" />
+              {{ link.label }}
+            </a>
+          }
+        </bf-nav-group>
+        <a
+          bfSlot="footer"
+          bfNavItem
+          routerLink="/theming"
+          routerLinkActive
+          ariaCurrentWhenActive="page"
+        >
+          <bf-icon bfSlot="icon" [icon]="settings" />
+          Theming
+        </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 SidebarOverviewExampleComponent {
+  readonly collapsed = signal(false);
+  readonly status = computed(() =>
+    this.collapsed() ? 'Sidebar collapsed to an icon rail.' : 'Sidebar expanded.',
+  );
+
+  protected readonly desktop: readonly NavLink[] = [
+    { path: '/components/sidebar', label: 'Sidebar', icon: PanelTop },
+    { path: '/components/top-nav', label: 'Top nav', icon: Rows3 },
+    { path: '/components/nav-group', label: 'Nav group', icon: Layers },
+  ];
+  protected readonly shell: readonly NavLink[] = [
+    { path: '/components/tabs', label: 'Tabs', icon: Smartphone, badge: 3 },
+    { path: '/mobile', label: 'Mobile guide', icon: BookOpen },
+  ];
+  protected readonly settings = Settings;
+  protected readonly panelOpen = PanelLeftOpen;
+  protected readonly panelClose = PanelLeftClose;
+}
+```
+
+## Overview
+
+The vertical navigation of a desktop app: a `nav` landmark with a `header` slot (the brand),
+the destinations (`a[bfNavItem]` links, optionally in `bf-nav-group`s) and a `footer` slot.
+`collapsed` turns it into an icon rail: put a `bf-sidebar-toggle` (`@bitforgehq/ui/overlay`) in
+it, or bind `[(collapsed)]` to your own button. Below a breakpoint hide it
+(`class="hidden md:flex"`) and drive a `bf-menu-button` from the same routes.
+
+The vertical navigation of a desktop web app: a `nav` landmark down the inline-start edge with a `header` slot for the brand, the destinations as [`a[bfNavItem]`](https://bitforge-ui.web.app/components/nav-item) links (optionally in titled [`bf-nav-group`](https://bitforge-ui.web.app/components/nav-group)s) and a `footer` slot for settings or the account. `collapsed` turns it into an icon rail. Its horizontal sibling for apps with few sections is [`bf-top-nav`](https://bitforge-ui.web.app/components/top-nav); both share the same item, so the current page, the badge and the focus ring look the same in either.
+
+## When to use
+
+Use `bf-sidebar` for the top-level destinations of a desktop web app with more than four or five sections, or with sections that fall into groups. Use [bf-top-nav](https://bitforge-ui.web.app/components/top-nav) instead for an app with a handful of sections, and [bf-segmented](https://bitforge-ui.web.app/components/segmented) to switch a view in place. In the Capacitor shell use [bf-tabs](https://bitforge-ui.web.app/components/tabs) with [bf-tab-bar](https://bitforge-ui.web.app/components/tab-bar) instead.
+
+## Basic usage
+
+Put `bfNavItem` on your own `<a routerLink routerLinkActive ariaCurrentWhenActive="page">`: the router sets `aria-current="page"` on the current page's link and the item shows it in the tonal fill. The widget never imports the router. Group the links with `bf-nav-group`, put the brand in `bfSlot="header"` and secondary links in `bfSlot="footer"`. Name the landmark with `label` (it falls back to `provideBfLabels()`'s `navigation`, "Main").
+
+## Collapsing to an icon rail
+
+`collapsed` is a model. Put a [`bf-sidebar-toggle`](https://bitforge-ui.web.app/components/sidebar-toggle) (`@bitforgehq/ui/overlay`) in the header or footer: it flips the model, names itself by what the next press does ("Collapse sidebar", "Expand sidebar") and takes its two icons as slots, since a widget never imports one. Bind `[(collapsed)]` to keep the state in your own signal, or bind it to your own button outside the sidebar. Collapsed, every item shows only its icon, centred in a square; its label stays in the DOM as screen-reader text, so its accessible name does not change, and becomes the link's `title`, the tooltip a pointer user sees on hover. A count badge becomes a small dot that is still announced, and the group headings are hidden visually but still name their groups. The width follows the rail (`w-auto`); expanded the sidebar is `w-60` (240 px).
+
+## Remember the collapsed sidebar
+
+`BfSidebarStateService` (from `@bitforgehq/ui`) holds a `collapsed` signal: bind the sidebar's `[(collapsed)]` to it (`sidebarState.collapsed`) and add `provideBfSidebarState()` to the app's providers, and every change is stored under `bf-sidebar-collapsed` (`localStorage` in the browser, `BF_SIDEBAR_STATE_STORAGE` to keep it elsewhere) and read back at the next start, so the app opens as the user left it. Without the provider the signal still holds the state but nothing is stored; on the server it starts expanded and reads nothing. The widget itself injects no service.
+
+```ts
+import { Component, inject } from '@angular/core';
+import { RouterLink, RouterLinkActive, RouterOutlet } from '@angular/router';
+import { BfNavItemComponent, BfSidebarComponent, BfSidebarStateService } from '@bitforgehq/ui';
+import { BfIconComponent } from '@bitforgehq/ui/icons';
+import { BfSidebarToggleComponent } from '@bitforgehq/ui/overlay';
+import { Inbox, PanelLeftClose, PanelLeftOpen } from 'lucide';
+
+/**
+ * A sidebar that opens collapsed or expanded, as the user left it.
+ *
+ * `[(collapsed)]` binds `BfSidebarStateService.collapsed`; with `provideBfSidebarState()` in the
+ * app's providers every change is stored under `bf-sidebar-collapsed` (`localStorage` in the
+ * browser) and read back at the next start.
+ *
+ * @preview none
+ */
+@Component({
+  selector: 'app-example-sidebar-remembered',
+  imports: [
+    RouterLink,
+    RouterLinkActive,
+    RouterOutlet,
+    BfIconComponent,
+    BfNavItemComponent,
+    BfSidebarComponent,
+    BfSidebarToggleComponent,
+  ],
+  template: `
+    <div class="flex min-h-dvh">
+      <bf-sidebar [(collapsed)]="sidebarState.collapsed" class="sticky top-0 h-dvh">
+        <a bfNavItem routerLink="/inbox" routerLinkActive ariaCurrentWhenActive="page">
+          <bf-icon bfSlot="icon" [icon]="inbox" />
+          Inbox
+        </a>
+        <bf-sidebar-toggle bfSlot="footer">
+          <bf-icon bfSlot="collapse-icon" [icon]="panelClose" />
+          <bf-icon bfSlot="expand-icon" [icon]="panelOpen" />
+        </bf-sidebar-toggle>
+      </bf-sidebar>
+      <main class="min-w-0 flex-1 p-6"><router-outlet /></main>
+    </div>
+  `,
+})
+export class SidebarRememberedExampleComponent {
+  // app.config.ts: providers: [provideBfSidebarState()]
+  protected readonly sidebarState = inject(BfSidebarStateService);
+  protected readonly inbox = Inbox;
+  protected readonly panelOpen = PanelLeftOpen;
+  protected readonly panelClose = PanelLeftClose;
+}
+```
+
+## Footer
+
+The footer slot takes several elements, stacked with a 4 px gap: a Settings link as an `a[bfNavItem]`, a row holding an icon-only text [`bf-theme-menu-button`](https://bitforge-ui.web.app/components/theme-menu-button) and the `bf-sidebar-toggle`, and an optional version line in `text-caption text-text-muted`. Expanded, the row puts the two buttons at either end (`flex items-center justify-between`). As an icon rail every footer element is centred: switch the row to a column (`flex flex-col items-center gap-1`) so both buttons fit the rail, and hide the version line (`[class.hidden]="collapsed()"`), which has no icon to shrink to. Open the theme menu upwards (`placement="above-start"`), since the footer sits at the bottom of the screen.
+
+```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;
+}
+```
+
+## Responsive layouts
+
+Below a breakpoint the sidebar does not turn itself into a menu: a root widget cannot render `bf-menu`. Keep one array of destinations (ideally derived from your route config) and drive every surface from it: the sidebar from `md` up (`class="hidden md:flex"` on `bf-sidebar`; its own `flex` loses to your `hidden`), and below it a [`bf-menu-button`](https://bitforge-ui.web.app/components/menu-button) of `a[bfMenuItem]` router links (`class="md:hidden"`, from `@bitforgehq/ui/overlay`). Each surface keeps the router's `routerLinkActive`. [`bf-app-frame`](https://bitforge-ui.web.app/components/app-frame) does this layout for you: it shows the sidebar in a sticky column from the breakpoint up and the menu button in a header bar below it.
+
+```ts
+import { Component } from '@angular/core';
+import { RouterLink, RouterLinkActive } from '@angular/router';
+import { BfNavItemComponent, BfSidebarComponent } from '@bitforgehq/ui';
+import { BfIconComponent } from '@bitforgehq/ui/icons';
+import {
+  BfMenuButtonComponent,
+  BfMenuComponent,
+  BfMenuItemDirective,
+} from '@bitforgehq/ui/overlay';
+import { type IconNode, Layers, Menu, PanelTop, Rows3 } from 'lucide';
+
+/** One top-level destination of the app. */
+interface Destination {
+  readonly path: string;
+  readonly label: string;
+  readonly icon: IconNode;
+}
+
+/**
+ * One route array, two surfaces.
+ *
+ * The same destinations drive the sidebar from the `md` breakpoint up (`hidden md:flex`) and a
+ * `bf-menu-button` of `a[bfMenuItem]` router links below it (`md:hidden`). Each surface keeps
+ * the router's `routerLinkActive`; resize the window to switch between them.
+ */
+@Component({
+  selector: 'app-example-sidebar-responsive',
+  imports: [
+    RouterLink,
+    RouterLinkActive,
+    BfIconComponent,
+    BfMenuButtonComponent,
+    BfMenuComponent,
+    BfMenuItemDirective,
+    BfNavItemComponent,
+    BfSidebarComponent,
+  ],
+  template: `
+    <div class="flex flex-col gap-3 md:flex-row">
+      <bf-sidebar label="Desktop components" class="hidden md:flex">
+        @for (destination of destinations; track destination.path) {
+          <a
+            bfNavItem
+            [routerLink]="destination.path"
+            routerLinkActive
+            ariaCurrentWhenActive="page"
+          >
+            <bf-icon bfSlot="icon" [icon]="destination.icon" />
+            {{ destination.label }}
+          </a>
+        }
+      </bf-sidebar>
+      <bf-menu-button class="md:hidden" [menu]="navMenu">
+        <bf-icon bfSlot="icon-start" [icon]="menu" />
+        Sections
+      </bf-menu-button>
+      <p class="text-caption text-text-muted min-w-0 flex-1">
+        The page content sits here, beside the sidebar or under the menu button.
+      </p>
+    </div>
+
+    <ng-template #navMenu>
+      <bf-menu>
+        @for (destination of destinations; track destination.path) {
+          <a
+            bfMenuItem
+            [routerLink]="destination.path"
+            routerLinkActive
+            ariaCurrentWhenActive="page"
+            >{{ destination.label }}</a
+          >
+        }
+      </bf-menu>
+    </ng-template>
+  `,
+})
+export class SidebarResponsiveExampleComponent {
+  /** In an app, derive this from the route config, so a new route appears on every surface. */
+  protected readonly destinations: readonly Destination[] = [
+    { path: '/components/sidebar', label: 'Sidebar', icon: PanelTop },
+    { path: '/components/top-nav', label: 'Top nav', icon: Rows3 },
+    { path: '/components/nav-group', label: 'Nav group', icon: Layers },
+  ];
+  protected readonly menu = Menu;
+}
+```
+
+Inside the Capacitor shell the same array drives the `bf-tab`s of a `bf-tab-bar` in `bf-tabs`; each destination's path is a tab id and a child route of the tabs.
+
+```ts
+import { Component } from '@angular/core';
+import { BfTabBarComponent, BfTabComponent } from '@bitforgehq/ui';
+import { BfIconComponent } from '@bitforgehq/ui/icons';
+import { BfStackOutletComponent, BfTabsComponent } from '@bitforgehq/ui/mobile';
+import { Folder, type IconNode, Inbox, Settings } from 'lucide';
+
+/** One top-level destination: `path` is the route under the tabs, and the tab's id. */
+interface Destination {
+  readonly path: string;
+  readonly label: string;
+  readonly icon: IconNode;
+}
+
+/**
+ * The same destinations inside the Capacitor shell.
+ *
+ * In the shell the destinations array that drives the desktop sidebar drives a `bf-tab-bar`
+ * inside `bf-tabs` instead: each destination's `path` is a child route of `app` and the tab's id.
+ * On desktop the same array feeds `a[bfNavItem]` links (`routerLink="/app/{path}"`).
+ *
+ * @preview none
+ */
+@Component({
+  selector: 'app-example-sidebar-shell',
+  imports: [
+    BfIconComponent,
+    BfStackOutletComponent,
+    BfTabBarComponent,
+    BfTabComponent,
+    BfTabsComponent,
+  ],
+  template: `
+    <bf-tabs tabsPath="app">
+      <bf-stack-outlet />
+      <bf-tab-bar>
+        @for (destination of destinations; track destination.path) {
+          <bf-tab [id]="destination.path" [label]="destination.label"
+            ><bf-icon [icon]="destination.icon"
+          /></bf-tab>
+        }
+      </bf-tab-bar>
+    </bf-tabs>
+  `,
+})
+export class SidebarShellExampleComponent {
+  protected readonly destinations: readonly Destination[] = [
+    { path: 'inbox', label: 'Inbox', icon: Inbox },
+    { path: 'projects', label: 'Projects', icon: Folder },
+    { path: 'settings', label: 'Settings', icon: Settings },
+  ];
+}
+```
+
+## Desktop
+
+The sidebar is a desktop pattern. Its items take a `surface-muted` fill and the pointer on hover, a `surface-pressed` fill while pressed and the focus ring on keyboard focus only (`focus-visible`); the current page keeps its tonal fill with its own hover and pressed steps. The destinations scroll on their own when they outgrow the height, while the header and footer stay put; a 4 px inset keeps the focus ring inside the scroll box. Item height follows `provideBfDefaults()` (`controlSize`); under a coarse pointer (a touchscreen laptop) every item is at least 44 px tall. Collapsed, the `title` tooltip names each item on hover. A link keeps the browser's behaviour: Ctrl/Cmd-click and a middle click open it in a new tab.
+
+## Theming
+
+- Surface: `surface` with a `border` line on its inline-end edge (`border-e`); 12 px padding and 24 px between the header, the groups and the footer.
+- Width: `w-60` (240 px) expanded, the icon rail's own width collapsed.
+- The items' and the groups' tokens are on the [nav item](https://bitforge-ui.web.app/components/nav-item#theming) and [nav group](https://bitforge-ui.web.app/components/nav-group#theming) pages.
+
+## Accessibility
+
+`bf-sidebar` renders a native `<nav>` landmark named by `label`, else `provideBfLabels()`'s `navigation` ("Main"); give each landmark on a page a different name. The header, the destinations and the footer all sit inside it, in that DOM order. The current page is the link the router marks with `aria-current="page"`; the tonal fill is never the only cue under forced colours, where an outline marks it. Collapsing changes only what is visible: every item keeps its label as screen-reader text and each group its name, so the accessible names stay the same. `bf-sidebar-toggle` is a native button named by what it does ("Collapse sidebar"), with `aria-expanded` and `aria-controls` on the `nav`; your own toggle should do the same, and sit in the sidebar or right before it.
+
+### Keyboard
+
+| Key                                              | Action                                             |
+| ------------------------------------------------ | -------------------------------------------------- |
+| <kbd>Tab</kbd> / <kbd>Shift</kbd>+<kbd>Tab</kbd> | Moves through the header, the links and the footer |
+| <kbd>Enter</kbd>                                 | Follows the focused link                           |
+
+## Inputs
+
+| Name        | Type      | Default | Description                                                                                                                                                                                                          |
+| ----------- | --------- | ------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `label`     | `string`  | `''`    | Accessible name of the navigation; empty falls back to `provideBfLabels()`'s `navigation` ("Main"). Name each landmark differently when a page has more than one.                                                    |
+| `collapsed` | `boolean` | `false` | Collapses the sidebar to an icon rail: items show their icon only, their label stays for screen readers and becomes a tooltip. A `bf-sidebar-toggle` inside flips it; bind `[(collapsed)]` to keep it in your state. |
+
+## Slots
+
+- `header`: The brand or app switcher above the destinations.
+- `default`: The destinations: `a[bfNavItem]` links and `bf-nav-group`s.
+- `footer`: Content under the destinations, such as settings or the account.
+
+## Notes
+
+### Do
+
+- Mark the current page with `routerLinkActive` and `ariaCurrentWhenActive="page"` on every link.
+- Drive the sidebar, the small-screen menu and the shell's tab bar from one array of destinations.
+- Remember the collapsed state with `BfSidebarStateService` and `provideBfSidebarState()`.
+
+### Don't
+
+- Don't put actions (Create, Log out) among the destinations; a sidebar is for places, so put an action in the header or footer as a button.
+- Don't use `bf-sidebar` inside the Capacitor shell; use `bf-tabs` with a `bf-tab-bar` there.
+
+## Migration notes
+
+### 0.3.2
+
+New `BfSidebarStateService` (a `collapsed` signal) and `provideBfSidebarState()` in
+`@bitforgehq/ui`: bind the sidebar's `[(collapsed)]` to `sidebarState.collapsed` and the provider
+stores every change under `bf-sidebar-collapsed` in `BF_SIDEBAR_STATE_STORAGE` (`localStorage` in
+the browser, memory elsewhere), read back at the next start; without the provider nothing is
+written, and on the server nothing is read. The sidebar's `nav` now has an id, for a toggle's
+`aria-controls`. The docs gain "Remember the collapsed sidebar" and a "Footer" composition
+(Settings link, theme menu, toggle, version line) that works expanded and as an icon rail.
+
+### 0.3.1
+
+New `bf-sidebar`: the vertical navigation of a desktop app, a `nav` landmark with `header`,
+default and `footer` slots, named by `label` (else the new `navigation` label, "Main").
+`collapsed` (a model the app binds to its own toggle button) turns it into an icon rail. Below a
+breakpoint, hide it with `hidden md:flex` and drive a `bf-menu-button` from the same routes.