@bitforgehq/ui 0.3.0 → 0.3.1

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