@bitforgehq/ui 0.3.0 → 0.3.2

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