@bitforgehq/ui 0.3.0

package/ai/components/menu-button.md

@@ -0,0 +1,377 @@
+# bf-menu-button
+
+Styled button that opens a menu, with outline, text, tonal and icon-only looks
+
+`BfMenuButtonComponent` from `@bitforgehq/ui/overlay` · Overlays · since 0.3.0
+
+## Example
+
+```ts
+import { Component, signal } from '@angular/core';
+import { BfIconComponent } from '@bitforgehq/ui/icons';
+import {
+  BfMenuButtonComponent,
+  BfMenuComponent,
+  BfMenuItemDirective,
+} from '@bitforgehq/ui/overlay';
+import { Ellipsis } from 'lucide';
+
+/**
+ * The bf-menu-button overview.
+ *
+ * Live demo of `bf-menu-button`: the outline and text variants and an icon-only "More actions"
+ * button, all opening the same menu; the result line reports the chosen item. The triggers and
+ * the result line carry `data-testid`s for the end-to-end suite.
+ */
+@Component({
+  selector: 'app-example-menu-button-overview',
+  imports: [BfIconComponent, BfMenuButtonComponent, BfMenuComponent, BfMenuItemDirective],
+  template: `
+    <div class="flex flex-col gap-4">
+      <div class="flex flex-wrap items-center gap-2">
+        <bf-menu-button data-testid="menu-button-export" [menu]="exportMenu">Export</bf-menu-button>
+        <bf-menu-button data-testid="menu-button-export-text" [menu]="exportMenu" variant="text"
+          >Export</bf-menu-button
+        >
+        <bf-menu-button
+          data-testid="menu-button-more"
+          [menu]="exportMenu"
+          iconOnly
+          label="More actions"
+          variant="text"
+          placement="below-end"
+        >
+          <bf-icon [icon]="ellipsis" />
+        </bf-menu-button>
+      </div>
+      <p
+        data-status
+        data-testid="menu-button-result"
+        class="text-caption text-text-muted"
+        aria-live="polite"
+      >
+        {{ result() }}
+      </p>
+    </div>
+
+    <ng-template #exportMenu>
+      <bf-menu>
+        <button bfMenuItem (triggered)="result.set('Exported as CSV.')">Export as CSV</button>
+        <button bfMenuItem (triggered)="result.set('Exported as PDF.')">Export as PDF</button>
+        <button bfMenuItem (triggered)="result.set('Link copied.')">Copy link</button>
+      </bf-menu>
+    </ng-template>
+  `,
+})
+export class MenuButtonOverviewExampleComponent {
+  readonly ellipsis = Ellipsis;
+  readonly result = signal('');
+}
+```
+
+## Overview
+
+Button that opens a `bf-menu`: a native `<button>` styled like `bf-button` (or `bf-icon-button`
+with `iconOnly`) in the outline, text or tonal variant, with `aria-haspopup="menu"` and
+`aria-expanded`. Click, `Enter`, `Space` or `ArrowDown` open the menu with its first item
+focused, `ArrowUp` with its last; closing it returns focus here.
+
+A button that opens a `bf-menu`, from `@bitforgehq/ui/overlay` (needs `@angular/cdk`, no
+Capacitor). It renders a native `<button>` that looks like a `bf-button` (or a `bf-icon-button`
+with `iconOnly`) in the outline, text or tonal variant, with a caret after its label. Pass the
+`ng-template` holding the menu as `menu`. The menu page covers the items, groups, submenus and
+the keyboard. Import `BfMenuButtonComponent`, `BfMenuComponent` and `BfMenuItemDirective` from
+`@bitforgehq/ui/overlay`.
+
+## When to use
+
+Use `bf-menu-button` for a button that opens a [bf-menu](https://bitforge-ui.web.app/components/menu) of actions: Export, Sort, a "More" button on a table row. Use [bf-button](https://bitforge-ui.web.app/components/button) instead for a single action, and [bf-select](https://bitforge-ui.web.app/components/select) to pick a form value.
+
+## Basic usage
+
+```ts
+import { Component, signal } from '@angular/core';
+import {
+  BfMenuButtonComponent,
+  BfMenuComponent,
+  BfMenuItemDirective,
+} from '@bitforgehq/ui/overlay';
+
+/**
+ * An export menu button.
+ *
+ * The menu button passes its `ng-template` as `menu`; each format reports its export.
+ */
+@Component({
+  selector: 'app-example-menu-button-basic',
+  imports: [BfMenuButtonComponent, BfMenuComponent, BfMenuItemDirective],
+  template: `
+    <bf-menu-button [menu]="exportMenu">Export</bf-menu-button>
+    <p aria-live="polite" class="text-caption text-text-muted mt-3">{{ result() }}</p>
+
+    <ng-template #exportMenu>
+      <bf-menu>
+        <button bfMenuItem (triggered)="result.set('Exported as CSV.')">CSV</button>
+        <button bfMenuItem (triggered)="result.set('Exported as PDF.')">PDF</button>
+      </bf-menu>
+    </ng-template>
+  `,
+})
+export class MenuButtonBasicExampleComponent {
+  protected readonly result = signal('');
+}
+```
+
+`opened` and `closed` fire as the menu opens and closes. `disabled` disables the button (the
+menu cannot open). An icon goes in the `icon-start` slot.
+
+```ts
+import { Component, signal } from '@angular/core';
+import { BfIconComponent } from '@bitforgehq/ui/icons';
+import {
+  BfMenuButtonComponent,
+  BfMenuComponent,
+  BfMenuItemDirective,
+} from '@bitforgehq/ui/overlay';
+import { Download } from 'lucide';
+
+/**
+ * A tonal menu button with an icon.
+ *
+ * The icon goes in the icon-start slot; `closed` reports each time the menu closes.
+ */
+@Component({
+  selector: 'app-example-menu-button-icon',
+  imports: [BfIconComponent, BfMenuButtonComponent, BfMenuComponent, BfMenuItemDirective],
+  template: `
+    <bf-menu-button [menu]="exportMenu" variant="tonal" (closed)="closes.set(closes() + 1)">
+      <bf-icon bfSlot="icon-start" [icon]="download" />
+      Export
+    </bf-menu-button>
+    <p class="text-caption text-text-muted mt-3">Closed {{ closes() }} times.</p>
+
+    <ng-template #exportMenu>
+      <bf-menu>
+        <button bfMenuItem>CSV</button>
+        <button bfMenuItem>PDF</button>
+      </bf-menu>
+    </ng-template>
+  `,
+})
+export class MenuButtonIconExampleComponent {
+  protected readonly download = Download;
+  protected readonly closes = signal(0);
+}
+```
+
+## Variants
+
+`outline` (default), `text` and `tonal`, with the same colours as `bf-button`. A menu button is
+never `primary`: it opens a choice, it is not the page's main action.
+
+```ts
+import { Component, signal } from '@angular/core';
+import {
+  BfMenuButtonComponent,
+  BfMenuComponent,
+  BfMenuItemDirective,
+} from '@bitforgehq/ui/overlay';
+
+/**
+ * The outline, text and tonal menu buttons.
+ *
+ * Three triggers for one sort menu.
+ */
+@Component({
+  selector: 'app-example-menu-button-variants',
+  imports: [BfMenuButtonComponent, BfMenuComponent, BfMenuItemDirective],
+  template: `
+    <div class="flex flex-wrap gap-2">
+      <bf-menu-button [menu]="sortMenu">Sort</bf-menu-button>
+      <bf-menu-button [menu]="sortMenu" variant="text">Sort</bf-menu-button>
+      <bf-menu-button [menu]="sortMenu" variant="tonal">Sort</bf-menu-button>
+    </div>
+    <p aria-live="polite" class="text-caption text-text-muted mt-3">{{ result() }}</p>
+
+    <ng-template #sortMenu>
+      <bf-menu>
+        <button bfMenuItem (triggered)="result.set('Sorted by name.')">Name</button>
+        <button bfMenuItem (triggered)="result.set('Sorted by date.')">Date</button>
+      </bf-menu>
+    </ng-template>
+  `,
+})
+export class MenuButtonVariantsExampleComponent {
+  protected readonly result = signal('');
+}
+```
+
+## Icon only
+
+`iconOnly` renders a round button that holds only the projected icon, like `bf-icon-button`, and
+drops the caret. Set `label`: it is the button's accessible name, as the icon gives none. A
+"More" button on a table row is the typical use.
+
+```ts
+import { Component, signal } from '@angular/core';
+import { BfIconComponent } from '@bitforgehq/ui/icons';
+import {
+  BfMenuButtonComponent,
+  BfMenuComponent,
+  BfMenuItemDirective,
+} from '@bitforgehq/ui/overlay';
+import { Ellipsis } from 'lucide';
+
+/** An icon-only menu button named by its label. */
+@Component({
+  selector: 'app-example-menu-button-icon-only',
+  imports: [BfIconComponent, BfMenuButtonComponent, BfMenuComponent, BfMenuItemDirective],
+  template: `
+    <bf-menu-button [menu]="rowActions" iconOnly label="More actions" variant="text">
+      <bf-icon [icon]="ellipsis" />
+    </bf-menu-button>
+    <p aria-live="polite" class="text-caption text-text-muted mt-3">{{ result() }}</p>
+
+    <ng-template #rowActions>
+      <bf-menu>
+        <button bfMenuItem (triggered)="result.set('Renamed.')">Rename</button>
+        <button bfMenuItem (triggered)="result.set('Deleted.')">Delete</button>
+      </bf-menu>
+    </ng-template>
+  `,
+})
+export class MenuButtonIconOnlyExampleComponent {
+  protected readonly ellipsis = Ellipsis;
+  protected readonly result = signal('');
+}
+```
+
+## Sizes and placement
+
+`size` is `sm` 32, `md` 40 or `lg` 48 px; unset it follows `provideBfDefaults()` (`controlSize`,
+`md` by default). Under a coarse pointer `sm` and `md` reach 44 px without changing their look.
+`placement` sets where the menu opens: `'below-start'` (default), `'below-end'`,
+`'above-start'` or `'above-end'`, flipping when it would overflow the viewport.
+
+```ts
+import { Component, signal } from '@angular/core';
+import {
+  BfMenuButtonComponent,
+  BfMenuComponent,
+  BfMenuItemDirective,
+} from '@bitforgehq/ui/overlay';
+
+/**
+ * A small menu button that opens below its end.
+ *
+ * `size="sm"` sizes the trigger; `placement="below-end"` aligns the menu to its inline end.
+ */
+@Component({
+  selector: 'app-example-menu-button-sizes',
+  imports: [BfMenuButtonComponent, BfMenuComponent, BfMenuItemDirective],
+  template: `
+    <div class="flex justify-end">
+      <bf-menu-button [menu]="rowActions" size="sm" placement="below-end">Actions</bf-menu-button>
+    </div>
+    <p aria-live="polite" class="text-caption text-text-muted mt-3">{{ result() }}</p>
+
+    <ng-template #rowActions>
+      <bf-menu>
+        <button bfMenuItem (triggered)="result.set('Renamed.')">Rename</button>
+        <button bfMenuItem (triggered)="result.set('Archived.')">Archive</button>
+      </bf-menu>
+    </ng-template>
+  `,
+})
+export class MenuButtonSizesExampleComponent {
+  protected readonly result = signal('');
+}
+```
+
+## Desktop
+
+Hover and focus look like `bf-button` (or `bf-icon-button` with `iconOnly`): the fill, border or text darkens on hover with the pointer cursor, and the focus ring shows on keyboard focus only. A click opens the menu; a second click on the button closes it. Under a fine pointer the visible box is the hit area. Desktop density is the default `md` step; `provideBfDefaults({ size: 'sm' })`, or `{ size: 'sm' }` in a component's `providers`, makes a dense toolbar, table or sidebar ([density guide](https://bitforge-ui.web.app/density)).
+
+## Theming
+
+- Colours, border, radius, heights and the focus ring are `bf-button`'s (`bf-icon-button`'s with
+  `iconOnly`): outline `bg-surface` with a 1.5 px `border-border-strong`, text
+  `text-primary-text` (icon-only `text-text-muted` with a `surface-muted` hover), tonal
+  `bg-primary-soft` / `text-primary-strong`; disabled `bg-surface-sunken` / `text-disabled`.
+- Caret: a CSS chevron in the label's colour.
+
+## Accessibility
+
+- A native `<button type="button">` with `aria-haspopup="menu"` and `aria-expanded`, and the
+  menu it opens is named by it. Its name is its label, or `label` (`aria-label`). With `iconOnly`,
+  `label` is required. With a visible label, leave `label` empty or start it with the visible text
+  ([WCAG 2.5.3 Label in Name](https://www.w3.org/WAI/WCAG22/Understanding/label-in-name)).
+- Keyboard ([APG menu button](https://www.w3.org/WAI/ARIA/apg/patterns/menu-button/)): `Enter`,
+  `Space` or `ArrowDown` open the menu with focus on the first item, `ArrowUp` with focus on the
+  last. Closing the menu (`Escape`, `Tab`, an item) returns focus to the button.
+- The caret is drawn in CSS and adds nothing to the name.
+- Hit area: at least 32 px, 44 px under a coarse pointer (as `bf-button`).
+
+### Keyboard
+
+The keys inside the open menu are on the [bf-menu](https://bitforge-ui.web.app/components/menu#keyboard) page.
+
+| Key                                                        | Action                                                      |
+| ---------------------------------------------------------- | ----------------------------------------------------------- |
+| <kbd>Enter</kbd> / <kbd>Space</kbd> / <kbd>ArrowDown</kbd> | Opens the menu and focuses its first item                   |
+| <kbd>ArrowUp</kbd>                                         | Opens the menu and focuses its last item                    |
+| <kbd>Escape</kbd>                                          | In the open menu: closes it and returns focus to the button |
+| <kbd>Tab</kbd>                                             | In the open menu: closes it; focus moves on past the button |
+
+## Inputs
+
+| Name        | Type                                                                               | Default         | Description                                                                                                                      |
+| ----------- | ---------------------------------------------------------------------------------- | --------------- | -------------------------------------------------------------------------------------------------------------------------------- |
+| `menu`      | `TemplateRef<unknown>`                                                             | required        | The `ng-template` holding the `bf-menu` to open.                                                                                 |
+| `variant`   | `BfMenuButtonVariant` (`'outline' \| 'text' \| 'tonal'`)                           | `'outline'`     | Visual style: outline (default), text, tonal.                                                                                    |
+| `size`      | `BfSize \| undefined` (`'sm' \| 'md' \| 'lg' \| undefined`)                        | `undefined`     | Height step: sm 32, md 40, lg 48 px; unset follows `provideBfDefaults()` (`controlSize`, `md` by default).                       |
+| `placement` | `BfMenuPlacement` (`'below-start' \| 'below-end' \| 'above-start' \| 'above-end'`) | `'below-start'` | Where the menu opens against the button; it flips when it would overflow.                                                        |
+| `label`     | `string`                                                                           | `''`            | Accessible name (`aria-label`). Required with `iconOnly`; with a visible label leave it empty or start it with the visible text. |
+| `iconOnly`  | `boolean`                                                                          | `false`         | Square button holding only the projected icon, like `bf-icon-button`; set `label`.                                               |
+| `disabled`  | `boolean`                                                                          | `false`         | Disables the button; the menu cannot open.                                                                                       |
+
+## Outputs
+
+| Name     | Payload | Description      |
+| -------- | ------- | ---------------- |
+| `opened` | `void`  | The menu opened. |
+| `closed` | `void`  | The menu closed. |
+
+## Slots
+
+- `icon-start`: An icon before the label.
+- `default`: The label (the accessible name of an icon-only button).
+
+## Notes
+
+### Do
+
+- Name the button after what the menu holds ("Export", "Sort", "Actions").
+- Use the icon-only variant with a `label` for row actions ("More actions").
+
+### Don't
+
+- Don't use a menu button for a single action; use a `bf-button`.
+- Don't use it to pick a form value; use `bf-select` or `bf-radio-group`.
+
+## Migration notes
+
+### 0.3.0
+
+New `bf-menu-button` in `@bitforgehq/ui/overlay`: a native `<button>` that opens a `bf-menu`
+(`menu`, a `TemplateRef`) with `aria-haspopup="menu"` and `aria-expanded`, styled like
+`bf-button` (`variant` `outline` (default), `text`, `tonal`; a CSS caret) or, with `iconOnly`,
+like `bf-icon-button`. `size` (unset follows `controlSize`), `placement`, `label` (the
+`aria-label`, required with `iconOnly`), `disabled`, and `opened`/`closed` outputs. Its classes
+come from `bf-button`'s and `bf-icon-button`'s own class maps (internal `ɵ` exports of
+`@bitforgehq/ui`), so the looks never drift.
+
+JSDoc of `menu-button.component.ts` for the API reference: `@summary`/`@since` on the exported
+symbols; `@slot` docs for `icon-start`, `default`. No behaviour change.
+
+**Behaviour:** a pressed state (F-045): the button and icon-only forms take `bf-button`'s and `bf-icon-button`'s pressed fills from their shared class maps. None while disabled; under forced colours the system colours win.