@bitforgehq/ui 0.3.0 → 0.3.2

package/ai/components/popover.md

@@ -0,0 +1,250 @@
+# bf-popover
+
+Anchored, non-modal panel for filters, details or a small form
+
+`BfPopoverComponent` from `@bitforgehq/ui/overlay` · Overlays · since 0.3.1
+
+## Example
+
+```ts
+import { Component, computed, signal } from '@angular/core';
+import { BfButtonComponent, BfCheckboxComponent } from '@bitforgehq/ui';
+import { BfPopoverComponent, BfPopoverTriggerDirective } from '@bitforgehq/ui/overlay';
+
+type Status = 'open' | 'progress' | 'done';
+
+const STATUS_LABELS: Record<Status, string> = {
+  open: 'Open',
+  progress: 'In progress',
+  done: 'Done',
+};
+
+/**
+ * The bf-popover overview.
+ *
+ * Live demo of `bf-popover`: a Filters button opens a small filter form anchored below it. Focus
+ * moves to the first checkbox; Apply copies the choices to the task list and closes the popover
+ * through the exported trigger, while `Escape` or a click outside closes it without applying. The
+ * result line reports the filter in effect.
+ */
+@Component({
+  selector: 'app-example-popover-overview',
+  imports: [BfButtonComponent, BfCheckboxComponent, BfPopoverComponent, BfPopoverTriggerDirective],
+  template: `
+    <div class="flex flex-col items-start gap-3">
+      <bf-button
+        variant="outline"
+        [bfPopoverTriggerFor]="filters"
+        #filtersTrigger="bfPopoverTrigger"
+        (bfPopoverOpened)="draft.set(applied())"
+      >
+        Filters
+      </bf-button>
+      <p data-status aria-live="polite" class="text-caption text-text-muted">{{ status() }}</p>
+    </div>
+
+    <ng-template #filters>
+      <bf-popover class="w-72">
+        <h2 class="text-label text-text mb-3">Filter tasks</h2>
+        <div role="group" aria-label="Status" class="flex flex-col gap-2">
+          @for (status of statuses; track status) {
+            <bf-checkbox
+              [label]="labels[status]"
+              [checked]="draft().includes(status)"
+              (changed)="toggle(status, $event)"
+            />
+          }
+        </div>
+        <div class="mt-4 flex justify-end gap-2">
+          <bf-button variant="text" size="sm" (clicked)="draft.set([])">Clear</bf-button>
+          <bf-button size="sm" (clicked)="applied.set(draft()); filtersTrigger.close()">
+            Apply
+          </bf-button>
+        </div>
+      </bf-popover>
+    </ng-template>
+  `,
+})
+export class PopoverOverviewExampleComponent {
+  protected readonly statuses: readonly Status[] = ['open', 'progress', 'done'];
+  protected readonly labels = STATUS_LABELS;
+  readonly applied = signal<readonly Status[]>(['open', 'progress']);
+  readonly draft = signal<readonly Status[]>(['open', 'progress']);
+
+  readonly status = computed(() => {
+    const applied = this.applied();
+    return applied.length
+      ? `Showing ${applied.map((s) => STATUS_LABELS[s]).join(', ')} tasks.`
+      : 'Showing all tasks.';
+  });
+
+  toggle(status: Status, checked: boolean): void {
+    this.draft.update((draft) =>
+      checked ? [...draft, status] : draft.filter((s) => s !== status),
+    );
+  }
+}
+```
+
+## Overview
+
+Non-modal panel anchored to a trigger, for filters, details or a small form (role `dialog`).
+Put it in an `ng-template` that a `[bfPopoverTriggerFor]` opens; it takes the id the trigger's
+`aria-controls` points at and is named by `bfPopoverLabel`, else by its first heading, else by
+the trigger.
+
+Anchored panels for desktop and web apps, from `@bitforgehq/ui/overlay` (needs `@angular/cdk`, no
+Capacitor). A `bf-popover` is the panel; put it in an `ng-template` and open it from a button with
+`[bfPopoverTriggerFor]`. It opens beside its trigger, flips when it has no room, and leaves the
+page usable: it is non-modal, so there is no backdrop, focus is not trapped and the page does not
+become inert. It follows the
+[APG disclosure](https://www.w3.org/WAI/ARIA/apg/patterns/disclosure/) pattern with a non-modal
+`dialog` panel. Popovers open in the CDK overlay container, so they work inside a
+`BfDialogService` dialog.
+
+Import `BfPopoverComponent` and `BfPopoverTriggerDirective` from `@bitforgehq/ui/overlay`.
+
+## When to use
+
+Use `bf-popover` for a few fields or details that belong to one control and are used for a moment:
+filters for a list, the details of a value, a small form such as "Rename". Use
+[bf-menu](https://bitforge-ui.web.app/components/menu) instead for a list of actions or view settings,
+[BfDialogService](https://bitforge-ui.web.app/api/bf-dialog-service) for a task that needs the user's full attention or more
+than a few fields, a [bf-tooltip](https://bitforge-ui.web.app/components/tooltip) for a short hint with nothing to interact
+with, and in a Capacitor app a [bf-sheet](https://bitforge-ui.web.app/components/sheet).
+
+## Opening and closing
+
+The trigger toggles the popover on a click (and on `Enter` or `Space`, which click a button).
+Focus moves to the first control inside (or to the element marked `autofocus`, or to the panel
+when it holds no control). `Escape`, a click outside, `Tab` past the panel's last control or a
+navigation to another URL path close it. `Escape` and a click on nothing focusable put focus back
+on the trigger; a click on another control leaves focus there.
+
+Export the trigger as `bfPopoverTrigger` to close the popover from inside it, for example from an
+Apply button: `#trigger="bfPopoverTrigger"`, then `trigger.close()`. It also has `open()`,
+`toggle()` and `isOpen()`. `(bfPopoverOpened)` and `(bfPopoverClosed)` report its state.
+
+The trigger can be a native `button` or a `bf-button`: on a host that does not take focus itself,
+the ARIA state goes on the first control inside it.
+
+## Placement
+
+`bfPopoverPlacement` sets where the panel opens: `'below-start'` (default), `'below-end'`,
+`'above-start'` or `'above-end'`, 4 px from the trigger. `start` and `end` follow the text
+direction. When the panel would overflow the viewport, it flips to the other side vertically
+first, then to the other alignment. It scrolls past the viewport height minus 2 rem. The
+placement is read each time it opens.
+
+```ts
+import { Component } from '@angular/core';
+import { BfButtonComponent } from '@bitforgehq/ui';
+import { BfPopoverComponent, BfPopoverTriggerDirective } from '@bitforgehq/ui/overlay';
+
+/**
+ * A details popover aligned to the trigger's end.
+ *
+ * `bfPopoverPlacement="below-end"` opens the panel under the trigger, aligned to its inline end;
+ * `bfPopoverLabel` names it when it has no heading.
+ */
+@Component({
+  selector: 'app-example-popover-placement',
+  imports: [BfButtonComponent, BfPopoverComponent, BfPopoverTriggerDirective],
+  template: `
+    <div class="flex justify-end">
+      <bf-button
+        variant="text"
+        [bfPopoverTriggerFor]="details"
+        bfPopoverPlacement="below-end"
+        bfPopoverLabel="Delivery details"
+      >
+        Delivery
+      </bf-button>
+    </div>
+
+    <ng-template #details>
+      <bf-popover class="w-64">
+        <p class="text-body text-text">Arrives Thursday between 9 and 12.</p>
+        <p class="text-caption text-text-muted mt-1">Tracking updates every hour.</p>
+      </bf-popover>
+    </ng-template>
+  `,
+})
+export class PopoverPlacementExampleComponent {}
+```
+
+## Naming
+
+The panel is a `dialog` named by `bfPopoverLabel` on the trigger when you set it, else by the
+first heading inside it, else by the trigger's text. Give a popover a heading when it holds a
+form, so its purpose is announced when focus moves in.
+
+## Desktop
+
+Built for a mouse and a keyboard: the panel opens next to its trigger and the page stays usable
+around it, so a click elsewhere closes it and lands where it was aimed. `Tab` walks through the
+panel and on to the control after the trigger, closing the panel, so keyboard users never get
+stuck in it. Set the panel's width with a class on `bf-popover` (`w-72`); it never grows past the
+viewport width minus 2 rem.
+
+Under a coarse pointer it works the same, with the panel's controls at their own touch sizes;
+in the Capacitor shell a `bf-sheet` suits phone screens better.
+
+## Theming
+
+- Panel: `bg-surface`, `text-text`, a 1 px `border-border`, `rounded-card`, `shadow-floating`,
+  `p-card` (18 px).
+- The content is yours: use the library's type and field tokens inside it.
+
+## Accessibility
+
+- The trigger's control has `aria-haspopup="dialog"`, `aria-expanded` and, while open,
+  `aria-controls` pointing at the panel.
+- The panel is `role="dialog"` without `aria-modal`, named as described under Naming. It gets the
+  id that `aria-controls` names.
+- Focus: opening moves focus into the panel; `Escape` returns it to the trigger. `Tab` is not
+  trapped: past the last control the panel closes and focus continues after the trigger, and
+  `Shift+Tab` before the first control closes it onto the trigger.
+- `Escape` goes to the popover first: inside a dialog, the first `Escape` closes the popover and
+  the next one the dialog.
+
+### Keyboard
+
+| Key                                 | Where            | Action                                                  |
+| ----------------------------------- | ---------------- | ------------------------------------------------------- |
+| <kbd>Enter</kbd> / <kbd>Space</kbd> | Trigger          | Opens the popover (closes it when open), focus moves in |
+| <kbd>Tab</kbd>                      | Panel            | Next control; past the last one closes, focus moves on  |
+| <kbd>Shift</kbd>+<kbd>Tab</kbd>     | First control    | Closes the popover, focus back on the trigger           |
+| <kbd>Escape</kbd>                   | Panel or trigger | Closes the popover, focus back on the trigger           |
+
+## Slots
+
+- `default`: The panel's content: a heading, text, fields and actions.
+
+## Notes
+
+### Do
+
+- Keep a popover small: a heading, a few fields and one or two actions.
+- Give a popover with a form a heading, or set `bfPopoverLabel`.
+- Apply a filter from an explicit button, or as each field changes, and say which in the panel.
+
+### Don't
+
+- Don't put a long form or a multi-step task in a popover; use a dialog.
+- Don't open a popover on hover; it opens on a click.
+- Don't use a popover for a list of actions; use a menu.
+- Don't nest popovers.
+
+## Migration notes
+
+### 0.3.1
+
+New `[bfPopoverTriggerFor]` (`BfPopoverTriggerDirective`, exported as `bfPopoverTrigger`) and the
+`bf-popover` panel (`BfPopoverComponent`) in `@bitforgehq/ui/overlay`: a non-modal `role="dialog"`
+panel anchored to its trigger, for filters, details or a small form. `bfPopoverPlacement`
+(`BfPopoverPlacement`, the menu's four placements), `bfPopoverLabel`, `(bfPopoverOpened)` and
+`(bfPopoverClosed)`, and `open()`, `close()`, `toggle()`, `isOpen()`. The trigger's control gets
+`aria-haspopup="dialog"`, `aria-expanded` and `aria-controls`; focus moves in on open, `Tab` is not
+trapped (it closes the panel past either end), and `Escape`, a click outside or a navigation close
+it and return focus. New `BfPopoverHarness` in `@bitforgehq/ui/testing`.

package/ai/components/side-panel.md

@@ -0,0 +1,391 @@
+# bf-side-panel
+
+Desktop panel sliding in from the end edge, with a title, body and footer actions
+
+`BfSidePanelComponent` from `@bitforgehq/ui/overlay` · Overlays · since 0.3.1
+
+## Example
+
+```ts
+import { Component, inject, signal } from '@angular/core';
+import {
+  BfButtonComponent,
+  BfInputComponent,
+  BfListComponent,
+  BfListItemComponent,
+} from '@bitforgehq/ui';
+import {
+  BF_SIDE_PANEL_DATA,
+  BfSidePanelComponent,
+  BfSidePanelRef,
+  BfSidePanelService,
+} from '@bitforgehq/ui/overlay';
+
+/** An invoice of the demo list. */
+export interface DemoInvoice {
+  id: string;
+  customer: string;
+  amount: string;
+}
+
+/** The details panel of the demo: two fields, and Cancel and Save in the footer. */
+@Component({
+  selector: 'app-side-panel-demo-invoice',
+  imports: [BfSidePanelComponent, BfButtonComponent, BfInputComponent],
+  template: `
+    <bf-side-panel [title]="invoice.id">
+      <bf-input label="Customer" [(value)]="customer" />
+      <bf-input label="Amount" [(value)]="amount" />
+      <div bfSlot="footer">
+        <bf-button variant="outline" (clicked)="ref.close()">Cancel</bf-button>
+        <bf-button (clicked)="save()">Save</bf-button>
+      </div>
+    </bf-side-panel>
+  `,
+})
+export class SidePanelDemoInvoiceComponent {
+  protected readonly ref = inject<BfSidePanelRef<DemoInvoice>>(BfSidePanelRef);
+  protected readonly invoice = inject<DemoInvoice>(BF_SIDE_PANEL_DATA);
+
+  protected readonly customer = signal(this.invoice.customer);
+  protected readonly amount = signal(this.invoice.amount);
+
+  protected save(): void {
+    this.ref.close({ ...this.invoice, customer: this.customer(), amount: this.amount() });
+  }
+}
+
+/**
+ * The bf-side-panel overview.
+ *
+ * Live demo of `bf-side-panel` and `BfSidePanelService`: a row of the invoice list opens its
+ * details in a modal side panel from the end edge, the footer saves the edit back into the list,
+ * and the result line announces each outcome.
+ */
+@Component({
+  selector: 'app-example-side-panel-overview',
+  imports: [BfListComponent, BfListItemComponent],
+  template: `
+    <div class="flex flex-col gap-3">
+      <bf-list>
+        @for (invoice of invoices(); track invoice.id) {
+          <bf-list-item
+            [title]="invoice.id"
+            [subtitle]="invoice.customer + ' · ' + invoice.amount"
+            [interactive]="true"
+            [chevron]="true"
+            (clicked)="open(invoice)"
+          />
+        }
+      </bf-list>
+      <p data-status class="text-caption text-text-muted" aria-live="polite">{{ status() }}</p>
+    </div>
+  `,
+})
+export class SidePanelOverviewExampleComponent {
+  private readonly panels = inject(BfSidePanelService);
+
+  readonly invoices = signal<readonly DemoInvoice[]>([
+    { id: 'INV-204', customer: 'Atlas Studio', amount: 'CHF 1,200' },
+    { id: 'INV-205', customer: 'Bloom Bakery', amount: 'CHF 340' },
+    { id: 'INV-206', customer: 'Kite Labs', amount: 'CHF 2,750' },
+  ]);
+  readonly status = signal('Open an invoice to edit it.');
+
+  async open(invoice: DemoInvoice): Promise<void> {
+    const ref = this.panels.open<SidePanelDemoInvoiceComponent, DemoInvoice, DemoInvoice>(
+      SidePanelDemoInvoiceComponent,
+      { data: invoice },
+    );
+    const saved = await ref.afterClosed;
+    if (saved) {
+      this.invoices.update((list) => list.map((item) => (item.id === saved.id ? saved : item)));
+      this.status.set(`Saved ${saved.id}.`);
+    } else {
+      this.status.set(`${invoice.id} closed without changes.`);
+    }
+  }
+}
+```
+
+## Overview
+
+Layout of a side panel opened with `BfSidePanelService`: a title row with a close button, a
+scrolling body and a footer of actions kept at the bottom. The panel is labelled by the title,
+and the body becomes focusable only while its content overflows, so keyboard users can scroll
+it (a region named by the title).
+
+A full-height panel that slides in from the inline end edge, for desktop and web apps, from
+`@bitforgehq/ui/overlay` (needs `@angular/cdk`, no Capacitor). `BfSidePanelService.open()`
+renders your component or template in the panel and returns a typed `BfSidePanelRef`;
+`bf-side-panel` inside the content lays out the title, the close button, the scrolling body and
+the footer actions.
+
+## When to use
+
+Use `BfSidePanelService` to show or edit one record of a list or a table without leaving it: the
+details of an invoice, a task, a user, or a filter panel. Use [bf-dialog](https://bitforge-ui.web.app/components/dialog)
+instead for a short task or a decision that needs an answer before the page goes on, and
+[bf-menu](https://bitforge-ui.web.app/components/menu) for a few actions. In the Capacitor shell, use
+[bf-sheet](https://bitforge-ui.web.app/components/sheet) or [bf-modal](https://bitforge-ui.web.app/components/modal) instead: a side panel is a desktop
+layout.
+
+## Modal and non-modal
+
+A side panel is modal by default: a scrim covers the page, focus stays inside the panel, the page
+behind it is inert and does not scroll, and a click on the scrim closes it. Pass `modal: false`
+to keep the page usable beside the panel: no scrim, no focus trap, the page scrolls and takes
+clicks, and the panel is not `aria-modal`. Focus still moves into the panel when it opens, and
+`Escape` closes it while focus is inside it. To show another record in a non-modal panel, close
+the open one and open the next.
+
+```ts
+import { Component, inject, signal } from '@angular/core';
+import { BfListComponent, BfListItemComponent } from '@bitforgehq/ui';
+import {
+  BF_SIDE_PANEL_DATA,
+  BfSidePanelComponent,
+  type BfSidePanelRef,
+  BfSidePanelService,
+} from '@bitforgehq/ui/overlay';
+
+/** A task of the demo list. */
+export interface DemoTask {
+  title: string;
+  owner: string;
+  due: string;
+}
+
+/** The read-only details of a task. */
+@Component({
+  selector: 'app-side-panel-demo-task',
+  imports: [BfSidePanelComponent],
+  template: `
+    <bf-side-panel [title]="task.title">
+      <p class="text-body text-text-secondary">Owner: {{ task.owner }}</p>
+      <p class="text-body text-text-secondary">Due: {{ task.due }}</p>
+    </bf-side-panel>
+  `,
+})
+export class SidePanelDemoTaskComponent {
+  protected readonly task = inject<DemoTask>(BF_SIDE_PANEL_DATA);
+}
+
+/**
+ * A non-modal side panel.
+ *
+ * `modal: false` adds no scrim and leaves the list usable: pick another task while the panel is
+ * open and it shows that one instead.
+ */
+@Component({
+  selector: 'app-example-side-panel-non-modal',
+  imports: [BfListComponent, BfListItemComponent],
+  template: `
+    <div class="flex flex-col gap-3">
+      <bf-list>
+        @for (task of tasks; track task.title) {
+          <bf-list-item
+            [title]="task.title"
+            [subtitle]="task.owner"
+            [interactive]="true"
+            (clicked)="show(task)"
+          />
+        }
+      </bf-list>
+      <p data-status class="text-caption text-text-muted" aria-live="polite">{{ status() }}</p>
+    </div>
+  `,
+})
+export class SidePanelNonModalExampleComponent {
+  private readonly panels = inject(BfSidePanelService);
+  private current: BfSidePanelRef | null = null;
+
+  readonly tasks: readonly DemoTask[] = [
+    { title: 'Draft the brief', owner: 'Mia Keller', due: 'Friday' },
+    { title: 'Review the logo', owner: 'Jonas Weber', due: 'Monday' },
+  ];
+  readonly status = signal('Pick a task.');
+
+  async show(task: DemoTask): Promise<void> {
+    this.current?.close();
+    const ref = this.panels.open(SidePanelDemoTaskComponent, {
+      data: task,
+      width: 'sm',
+      modal: false,
+    });
+    this.current = ref;
+    this.status.set(`Showing ${task.title}.`);
+    await ref.afterClosed;
+    if (this.current === ref) {
+      this.current = null;
+      this.status.set('Details closed.');
+    }
+  }
+}
+```
+
+## Widths
+
+`width` sets the panel's width on its own scale: `sm` 360 px, `md` 480 px (default), `lg` 640 px.
+Each is capped at the viewport width, so on a narrow window the panel covers the page edge to
+edge. The panel always fills the viewport height; the body scrolls when the content is taller.
+
+```ts
+import { Component, type TemplateRef, inject, viewChild } from '@angular/core';
+import { BfButtonComponent } from '@bitforgehq/ui';
+import {
+  BfSidePanelComponent,
+  BfSidePanelService,
+  type BfSidePanelTemplateContext,
+  type BfSidePanelWidth,
+} from '@bitforgehq/ui/overlay';
+
+/**
+ * The three side panel widths, from a template.
+ *
+ * `sm` is 360 px, `md` 480 px and `lg` 640 px, each capped at the viewport. The `ng-template`
+ * receives `{ $implicit: ref, data }`.
+ */
+@Component({
+  selector: 'app-example-side-panel-widths',
+  imports: [BfButtonComponent, BfSidePanelComponent],
+  template: `
+    <div class="flex flex-wrap gap-2">
+      @for (width of widths; track width) {
+        <bf-button variant="outline" (clicked)="open(width)">Open {{ width }}</bf-button>
+      }
+    </div>
+
+    <ng-template #panel let-ref let-data="data">
+      <bf-side-panel [title]="'Width ' + data.width">
+        <p class="text-body text-text-secondary">{{ data.hint }}</p>
+        <div bfSlot="footer"><bf-button (clicked)="ref.close()">Done</bf-button></div>
+      </bf-side-panel>
+    </ng-template>
+  `,
+})
+export class SidePanelWidthsExampleComponent {
+  private readonly panels = inject(BfSidePanelService);
+  readonly panel =
+    viewChild.required<TemplateRef<BfSidePanelTemplateContext<{ width: string; hint: string }>>>(
+      'panel',
+    );
+  readonly widths: readonly BfSidePanelWidth[] = ['sm', 'md', 'lg'];
+
+  private readonly hints: Record<BfSidePanelWidth, string> = {
+    sm: 'A short list of details or filters.',
+    md: 'A record with a few fields to edit.',
+    lg: 'A longer form or a preview beside the list.',
+  };
+
+  open(width: BfSidePanelWidth): void {
+    this.panels.open(this.panel(), { width, data: { width, hint: this.hints[width] } });
+  }
+}
+```
+
+## Header, body and footer
+
+`title` renders as the `h2` the panel is labelled by. Anything with `bfSlot="header"` sits after
+the title in the header row (a status badge). The default slot is the body, which scrolls on its
+own; `bfSlot="footer"` is an end-aligned row of actions below the body, kept at the bottom of the
+panel while the body scrolls. The close button (×) at the top end closes with no result.
+
+## Templates and results
+
+A template opens with the same options; its context is `{ $implicit: ref, data }` (see the
+widths example above). A component injects `BfSidePanelRef` to close itself and
+`BF_SIDE_PANEL_DATA` for its input. `close(result)` resolves `afterClosed` with the result;
+`Escape`, a scrim click, the close button and a navigation to another URL path resolve
+`undefined`. `closed()` turns true once the panel is gone, and `componentInstance` is the content
+component (`null` for a template). The service is a root singleton: pass
+`injector: inject(Injector)` so a feature-level `provideBfLabels()` names the close button
+(`close`) and the fallback (`dialog`).
+
+## Desktop
+
+Built for desktop: a full-height panel against the end edge, 360 to 640 px wide, beside or over a
+list. It slides in from the end edge in 260 ms and out the same way; under
+`prefers-reduced-motion` it cross-fades instead. Under `dir="rtl"` it opens on the left. The close
+button (×) is a `text` icon button: hover tints it, and its ring shows on keyboard focus only.
+The footer buttons follow `provideBfDefaults()` like any `bf-button`.
+
+## Theming
+
+- Panel: `bg-surface`, `text-text`, `shadow-floating`, a `border-s` in `border-border` between
+  the page and the panel; widths 22.5/30/40 rem capped at `100vw`, full viewport height.
+- Title: `text-heading`; header `px-6 py-4` with a `border-b`, body `px-6 py-4`, footer
+  `px-6 py-4` with a `border-t` and `gap-2` between actions.
+- Close button: a `text` `bf-icon-button` (`sm`) with a lucide `X`.
+- Scrim (modal only): `bf-overlay-backdrop` from the overlay core (a black scrim: 40 % in light
+  mode, 60 % in dark).
+
+## Accessibility
+
+The overlay panel is `role="dialog"`, with `aria-modal="true"` only when modal, and a name:
+`ariaLabel` when given; else `aria-labelledby` pointing at the `bf-side-panel` title; else the
+first heading in the content; else the `dialog` label ("Dialog"). Its ids come from the
+library's shared counter, so they never repeat one in the page.
+
+On open, focus moves into the panel: to the element marked `autofocus` (or `cdkFocusInitial`),
+else the first field or button of the body, never the ×, which comes last in the tab order. A
+modal panel traps Tab and Shift+Tab inside it and makes the rest of the page `inert`. A
+non-modal panel leaves the page in the tab order: Tab moves out of the panel and back. On close,
+focus returns to the element that opened it; from a non-modal panel only when focus was inside
+it, so focus the user moved to the page stays there. When the body overflows, it becomes
+focusable (`tabindex="0"`, a `role="region"` labelled by the title), so keyboard users can scroll
+it with the arrow keys.
+
+### Keyboard
+
+| Key                                              | Action                                                            |
+| ------------------------------------------------ | ----------------------------------------------------------------- |
+| <kbd>Tab</kbd> / <kbd>Shift</kbd>+<kbd>Tab</kbd> | Next / previous focusable element (wrapping inside a modal panel) |
+| <kbd>Escape</kbd>                                | Closes the panel (a non-modal one only while focus is inside it)  |
+| <kbd>Enter</kbd> / <kbd>Space</kbd>              | Activates the focused button                                      |
+
+## Inputs
+
+| Name         | Type     | Default | Description                                                                              |
+| ------------ | -------- | ------- | ---------------------------------------------------------------------------------------- |
+| `title`      | `string` | `''`    | Heading of the panel, rendered as the `h2` the side panel is labelled by.                |
+| `closeLabel` | `string` | `''`    | Accessible name of the close button; empty uses `provideBfLabels()`'s `close` ("Close"). |
+
+## Slots
+
+- `header`: More header content after the title, such as a status badge.
+- `default`: The panel body.
+- `footer`: The actions, aligned at the end and kept at the bottom.
+
+## Notes
+
+### Do
+
+- Give every side panel a `title` naming the record it shows ("INV-204").
+- Put the cancel action first in the footer and the primary action last.
+- Use `modal: false` for details the user reads while working in the list beside it.
+- Pass `injector: inject(Injector)` when the opener sits under its own `provideBfLabels()`.
+
+### Don't
+
+- Don't open a side panel for a yes/no decision; use `BfDialogService.confirm()`.
+- Don't stack side panels; close the open one before showing the next record.
+- Don't use a side panel in the Capacitor shell; use a `bf-sheet` or a `bf-modal`.
+
+## Migration notes
+
+### 0.3.1
+
+New `BfSidePanelService` and `bf-side-panel` in `@bitforgehq/ui/overlay`: a full-height panel
+that slides in from the inline end edge (the left under `dir="rtl"`; a cross-fade under reduced
+motion). `open(component | template, { data, width, modal, ariaLabel, injector })` returns a
+`BfSidePanelRef<R, C>` (`close(result)`, `afterClosed`, `closed()`, `componentInstance`); the
+content injects it and `BF_SIDE_PANEL_DATA`, and a template gets `{ $implicit: ref, data }`
+(`BfSidePanelTemplateContext`). `width` is a `BfSidePanelWidth`: `sm` 360 px, `md` 480 px
+(default), `lg` 640 px, capped at the viewport. Modal by default (a scrim that closes it, a focus
+trap, an inert page, no page scroll); `modal: false` keeps the page usable beside it, and
+`Escape` closes it only while focus is inside it. `bf-side-panel` renders the `title` as the
+`h2` the panel is labelled by, a close button named by the `close` label (`closeLabel`), a
+scrolling body and a `footer` slot kept at the bottom. New `BfSidePanelHarness` in
+`@bitforgehq/ui/testing` (`getTitle()`, `close()`, `isOpen()`). Desktop only; in the Capacitor
+shell use `bf-sheet` or `bf-modal`.