@bitforgehq/ui 0.3.0

package/ai/components/action-bar.md

@@ -0,0 +1,209 @@
+# bf-action-bar
+
+Floating pill of contextual actions that appears while items are selected
+
+`BfActionBarComponent` from `@bitforgehq/ui` · Actions · since 0.1.0
+
+## Example
+
+```ts
+import { Component, computed, signal } from '@angular/core';
+import { BfActionBarComponent, BfButtonComponent } from '@bitforgehq/ui';
+
+/**
+ * The bf-action-bar overview.
+ *
+ * Live demo of `bf-action-bar`: a selection count whose Clear, Move and Mark done actions act on it.
+ */
+@Component({
+  selector: 'app-example-action-bar-overview',
+  imports: [BfActionBarComponent, BfButtonComponent],
+  template: `
+    <div class="flex flex-col gap-3">
+      <bf-action-bar [label]="label()">
+        @if (selected() > 0) {
+          <bf-button variant="text" size="sm" (clicked)="clear()">Clear</bf-button>
+          <bf-button variant="text" size="sm" (clicked)="move()">Move</bf-button>
+          <bf-button size="sm" (clicked)="markDone()">Mark done</bf-button>
+        } @else {
+          <bf-button variant="text" size="sm" (clicked)="selectTwo()">Select 2</bf-button>
+        }
+      </bf-action-bar>
+      <p data-status aria-live="polite" class="text-caption text-text-muted">{{ status() }}</p>
+    </div>
+  `,
+})
+export class ActionBarOverviewExampleComponent {
+  readonly selected = signal(2);
+  readonly status = signal('Pick an action.');
+
+  readonly label = computed(() =>
+    this.selected() > 0 ? `${this.selected()} selected` : 'Nothing selected',
+  );
+
+  clear(): void {
+    this.selected.set(0);
+    this.status.set('Selection cleared.');
+  }
+
+  move(): void {
+    this.status.set(`Moved ${this.selected()} tasks to Atlas.`);
+  }
+
+  markDone(): void {
+    this.status.set(`Marked ${this.selected()} tasks done.`);
+    this.selected.set(0);
+  }
+
+  selectTwo(): void {
+    this.selected.set(2);
+    this.status.set('Selected 2 tasks.');
+  }
+}
+```
+
+## Overview
+
+Floating pill of actions that appears when items are selected. Position it yourself
+(bottom-centre, above the safe area on mobile); the bar only styles itself.
+
+A floating pill of actions that appears when items are selected, such as rows in a `bf-list`. `bf-action-bar` only styles the pill; you position it and control when it appears.
+
+## When to use
+
+Use `bf-action-bar` for the actions that apply to a selection while it lasts: delete, move or share the selected rows. Use [bf-menu-button](https://bitforge-ui.web.app/components/menu-button) instead for actions on a single item, and a row of [bf-button](https://bitforge-ui.web.app/components/button)s in a toolbar for actions that are always available.
+
+## Basic usage
+
+```ts
+import { Component, computed, signal } from '@angular/core';
+import { BfActionBarComponent, BfButtonComponent } from '@bitforgehq/ui';
+
+/**
+ * An action bar for a selection.
+ *
+ * The label counts the selected tasks; Clear empties the selection, Mark done completes it.
+ */
+@Component({
+  selector: 'app-example-action-bar-basic',
+  imports: [BfActionBarComponent, BfButtonComponent],
+  template: `
+    <div class="flex flex-col items-center gap-3">
+      <bf-action-bar [label]="selected().length + ' selected'">
+        <bf-button variant="text" size="sm" (clicked)="clear()">Clear</bf-button>
+        <bf-button size="sm" (clicked)="complete()">Mark done</bf-button>
+      </bf-action-bar>
+      <p aria-live="polite" class="text-caption text-text-muted">{{ status() }}</p>
+    </div>
+  `,
+})
+export class ActionBarBasicExampleComponent {
+  protected readonly selected = signal(['Brief', 'Moodboard', 'Deck']);
+  private readonly done = signal(0);
+  protected readonly status = computed(() => `${this.done()} done`);
+
+  protected clear(): void {
+    this.selected.set([]);
+  }
+
+  protected complete(): void {
+    this.done.update((n) => n + this.selected().length);
+    this.selected.set([]);
+  }
+}
+```
+
+## Positioning
+
+On the web, fix it to the bottom-centre of the viewport or the scroll container. On mobile, add `pb-safe-bottom` so it clears the tab bar and the device's safe area instead of sitting under it.
+
+```ts
+import { Component, signal } from '@angular/core';
+import { BfActionBarComponent, BfButtonComponent } from '@bitforgehq/ui';
+
+/**
+ * An action bar pinned above the bottom edge.
+ *
+ * The app positions the bar: a fixed, centred row that keeps clear of the home indicator
+ * (`pb-safe-bottom`).
+ *
+ * @preview none
+ */
+@Component({
+  selector: 'app-example-action-bar-positioning',
+  imports: [BfActionBarComponent, BfButtonComponent],
+  template: `
+    <div class="pb-safe-bottom fixed inset-x-0 bottom-6 flex justify-center">
+      <bf-action-bar [label]="selected().length + ' selected'">
+        <bf-button variant="text" size="sm" (clicked)="selected.set([])">Clear</bf-button>
+        <bf-button size="sm" (clicked)="selected.set([])">Mark done</bf-button>
+      </bf-action-bar>
+    </div>
+  `,
+})
+export class ActionBarPositioningExampleComponent {
+  protected readonly selected = signal(['Brief', 'Deck']);
+}
+```
+
+## Theming
+
+The pill itself carries the only tokens on `bf-action-bar`; the projected `bf-button`s theme themselves.
+
+- Background: `surface`; text: `text`.
+- Elevation: `shadow-floating`.
+- Shape: `rounded-control` (`--radius-control`, `9999px` by default, so a pill).
+
+The bar never grows past its container: the `label` never truncates (a long word breaks only past the bar's width), the buttons keep their size and wrap onto a second row when they do not fit beside it.
+
+The pill's padding is logical (18 px at the inline start, 6 px at the end), so the label leads under `dir="rtl"` too.
+
+## Accessibility
+
+The pill has `role="group"`; when `label` is set it also gets `aria-labelledby` pointing at the label text, so assistive tech announces the count before the actions. The bar sets no focus state of its own — keyboard and focus behaviour come entirely from the `bf-button`s projected into it.
+
+## Inputs
+
+| Name    | Type     | Default | Description                      |
+| ------- | -------- | ------- | -------------------------------- |
+| `label` | `string` | `''`    | Leading text, e.g. "2 selected". |
+
+## Slots
+
+- `default`: The actions: buttons and icon buttons, laid out in the bar.
+
+## Notes
+
+### Do
+
+- Show the bar only while at least one item is selected; remove it otherwise.
+- Keep it to two or three actions; more belongs in an overflow menu.
+
+### Don't
+
+- Don't rely on `bf-action-bar` for layout; it never positions itself.
+
+## Migration notes
+
+### 0.3.0
+
+**Behaviour:** logical properties: the pill's and the label's padding use `ps-*`/`pe-*`, so the
+label leads under `dir="rtl"`.
+
+**Behaviour:** shaped with the new `rounded-control` (`--radius-control`, `9999px` by default, so it renders as before); override the token to move off the pill.
+
+JSDoc of `action-bar.component.ts` for the API reference: `@slot` docs for `default`. No behaviour
+change.
+
+### 0.2.0
+
+The bar and its host are capped at `max-w-full`, so a long label no longer pushes the actions out
+of a narrow container (the label keeps its width and the actions wrap, see "Changed" below).
+
+Changed: the label (the selection count) never truncates: it keeps its width (`shrink-0`, breaking a
+long word only past the bar's width), and the bar is `flex-wrap`, so actions that do not fit beside
+it move to a second row.
+
+### 0.1.0
+
+New `bf-action-bar`: a floating pill for actions on a selection, with an optional leading `label` and a default slot for buttons. It only styles itself; the consumer positions it (fixed bottom-centre on web, `pb-safe-bottom` on mobile). Uses `role="group"` (was toolbar): the bar's contents aren't a fixed, single-tab-stop toolbar of controls, so `group` is the correct ARIA role; `aria-labelledby` now points at the `label` span instead of relying on visible text alone.