@bitforgehq/ui 0.3.0

package/ai/components/menu.md

@@ -0,0 +1,661 @@
+# bf-menu
+
+Keyboard-operable menu panel with items, checkbox and radio items, groups and submenus
+
+`BfMenuComponent` from `@bitforgehq/ui/overlay` · Overlays · since 0.3.0
+
+## Example
+
+```ts
+import { Component, signal } from '@angular/core';
+import { RouterLink } from '@angular/router';
+import {
+  BfMenuButtonComponent,
+  BfMenuComponent,
+  BfMenuDividerDirective,
+  BfMenuGroupDirective,
+  BfMenuItemCheckboxDirective,
+  BfMenuItemDirective,
+  BfMenuItemRadioDirective,
+  BfMenuTriggerDirective,
+} from '@bitforgehq/ui/overlay';
+
+type Density = 'compact' | 'comfortable';
+
+/**
+ * The bf-menu overview.
+ *
+ * Live demo of `bf-menu`: row actions with a "Move to" submenu, a disabled item, a link item that
+ * navigates to the `bf-menu-button` page (closing the menu) and a destructive item after a divider, then a view menu with a "Show grid" checkbox item and a density radio
+ * group; the result line reports each choice. The triggers and the result line carry
+ * `data-testid`s for the end-to-end suite.
+ */
+@Component({
+  selector: 'app-example-menu-overview',
+  imports: [
+    BfMenuButtonComponent,
+    BfMenuComponent,
+    BfMenuDividerDirective,
+    BfMenuGroupDirective,
+    BfMenuItemCheckboxDirective,
+    BfMenuItemDirective,
+    BfMenuItemRadioDirective,
+    BfMenuTriggerDirective,
+    RouterLink,
+  ],
+  template: `
+    <div class="flex flex-col gap-4">
+      <div class="flex flex-wrap items-center gap-2">
+        <bf-menu-button data-testid="menu-actions" [menu]="rowActions">Actions</bf-menu-button>
+        <bf-menu-button data-testid="menu-view" [menu]="view" variant="text">View</bf-menu-button>
+      </div>
+      <p
+        data-status
+        data-testid="menu-result"
+        class="text-caption text-text-muted"
+        aria-live="polite"
+      >
+        {{ result() }}
+      </p>
+    </div>
+
+    <ng-template #rowActions>
+      <bf-menu>
+        <button bfMenuItem (triggered)="result.set('Renamed Atlas rebrand.')">Rename</button>
+        <button bfMenuItem (triggered)="result.set('Duplicated Atlas rebrand.')">Duplicate</button>
+        <button bfMenuItem [bfMenuTriggerFor]="moveTo">Move to</button>
+        <button bfMenuItem bfMenuItemDisabled>Share</button>
+        <a bfMenuItem routerLink="/components/menu-button">Open the menu button page</a>
+        <div bfMenuDivider></div>
+        <button bfMenuItem (triggered)="result.set('Deleted (not really, this is a demo).')">
+          Delete
+        </button>
+      </bf-menu>
+    </ng-template>
+
+    <ng-template #moveTo>
+      <bf-menu>
+        <button bfMenuItem (triggered)="result.set('Moved to Inbox.')">Inbox</button>
+        <button bfMenuItem (triggered)="result.set('Moved to In progress.')">In progress</button>
+        <button bfMenuItem (triggered)="result.set('Moved to Done.')">Done</button>
+      </bf-menu>
+    </ng-template>
+
+    <ng-template #view>
+      <bf-menu>
+        <button bfMenuItemCheckbox [(checked)]="showGrid" (changed)="reportGrid($event)">
+          Show grid
+        </button>
+        <div bfMenuDivider></div>
+        <div bfMenuGroup aria-label="Density">
+          <button
+            bfMenuItemRadio
+            [checked]="density() === 'compact'"
+            (triggered)="setDensity('compact')"
+          >
+            Compact
+          </button>
+          <button
+            bfMenuItemRadio
+            [checked]="density() === 'comfortable'"
+            (triggered)="setDensity('comfortable')"
+          >
+            Comfortable
+          </button>
+        </div>
+      </bf-menu>
+    </ng-template>
+  `,
+})
+export class MenuOverviewExampleComponent {
+  readonly result = signal('');
+  readonly showGrid = signal(false);
+  readonly density = signal<Density>('compact');
+
+  reportGrid(shown: boolean): void {
+    this.result.set(shown ? 'Grid shown.' : 'Grid hidden.');
+  }
+
+  setDensity(density: Density): void {
+    this.density.set(density);
+    this.result.set(density === 'compact' ? 'Compact rows.' : 'Comfortable rows.');
+  }
+}
+```
+
+## Overview
+
+Menu panel of actions, choices and submenus on the Angular CDK menu (role `menu`, arrow keys,
+Home/End, type-ahead, `Escape` returning focus to the trigger). Put it in an `ng-template` that
+a `bf-menu-button` or a `[bfMenuTriggerFor]` opens, and fill it with `bfMenuItem`,
+`bfMenuItemCheckbox`, `bfMenuItemRadio` (in a `bfMenuGroup`) and `bfMenuDivider` parts.
+
+Menus of actions and choices for desktop and web apps, from `@bitforgehq/ui/overlay` (needs
+`@angular/cdk`, no Capacitor). A `bf-menu` is the panel; put it in an `ng-template` and open it
+from a `bf-menu-button` or from any element with `[bfMenuTriggerFor]`. Fill it with item parts:
+`bfMenuItem` (an action or a link), `bfMenuItemCheckbox` (a toggle), `bfMenuItemRadio` (one
+choice of a set, inside a `bfMenuGroup`) and `bfMenuDivider`. The menu is built on the Angular
+CDK menu, which provides the roles and the keyboard behaviour of the
+[APG menu button](https://www.w3.org/WAI/ARIA/apg/patterns/menu-button/) pattern. Menus open in
+the CDK overlay container, so they work inside a `BfDialogService` dialog.
+
+Import the parts you use from `@bitforgehq/ui/overlay`: `BfMenuButtonComponent`, `BfMenuComponent`,
+`BfMenuDividerDirective`, `BfMenuGroupDirective`, `BfMenuItemCheckboxDirective`,
+`BfMenuItemDirective`, `BfMenuItemRadioDirective` and `BfMenuTriggerDirective`.
+
+## When to use
+
+Use `bf-menu` for a short list of actions or view settings that opens from a button: Rename, Move to, Delete; Show grid, Density. Use [bf-select](https://bitforge-ui.web.app/components/select) instead to choose a form value, [BfDialogService](https://bitforge-ui.web.app/api/bf-dialog-service) when the choice needs fields or explanation, links in a `nav` for site navigation, and [BfActionSheetService](https://bitforge-ui.web.app/api/bf-action-sheet-service) in a Capacitor app.
+
+## Basic usage
+
+Items are native `<button>` elements. `triggered` fires when one is activated with a click,
+`Enter` or `Space`; the menu then closes and focus returns to the button that opened it.
+
+```ts
+import { Component, signal } from '@angular/core';
+import {
+  BfMenuButtonComponent,
+  BfMenuComponent,
+  BfMenuItemDirective,
+} from '@bitforgehq/ui/overlay';
+
+/**
+ * Row actions in a menu.
+ *
+ * A `bf-menu-button` opens the menu; each item reports its `triggered`, and Archive is disabled.
+ */
+@Component({
+  selector: 'app-example-menu-basic',
+  imports: [BfMenuButtonComponent, BfMenuComponent, BfMenuItemDirective],
+  template: `
+    <bf-menu-button [menu]="rowActions">Actions</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('Duplicated.')">Duplicate</button>
+        <button bfMenuItem bfMenuItemDisabled>Archive</button>
+      </bf-menu>
+    </ng-template>
+  `,
+})
+export class MenuBasicExampleComponent {
+  protected readonly result = signal('');
+}
+```
+
+`bfMenuItemDisabled` disables an item. It stays focusable and is announced as disabled
+(`aria-disabled`), but it does not activate. Put icons inside the item before the label; the
+item lays them out with a 12 px gap. `bfMenuItemTypeahead` sets the text that type-ahead matches
+when the label starts with something else (an emoji, a count).
+
+Any element can open a menu with `[bfMenuTriggerFor]`, for example your own toolbar button.
+`(bfMenuOpened)` and `(bfMenuClosed)` report its state, and `bfMenuTriggerData` passes a context
+to the template.
+
+```ts
+import { Component, signal } from '@angular/core';
+import { BfIconComponent } from '@bitforgehq/ui/icons';
+import {
+  BfMenuComponent,
+  BfMenuItemDirective,
+  BfMenuTriggerDirective,
+} from '@bitforgehq/ui/overlay';
+import { Settings2 } from 'lucide';
+
+/**
+ * A menu opened from your own button.
+ *
+ * `[bfMenuTriggerFor]` turns any element into the trigger; `bfMenuClosed` reports when the menu closes.
+ */
+@Component({
+  selector: 'app-example-menu-trigger',
+  imports: [BfIconComponent, BfMenuComponent, BfMenuItemDirective, BfMenuTriggerDirective],
+  template: `
+    <button
+      type="button"
+      class="border-border-strong text-text rounded-control inline-flex h-10 items-center gap-2 border px-4"
+      [bfMenuTriggerFor]="options"
+      (bfMenuClosed)="result.set('Layout saved.')"
+    >
+      <bf-icon [icon]="settings" size="sm" />
+      Options
+    </button>
+    <p aria-live="polite" class="text-caption text-text-muted mt-3">{{ result() }}</p>
+
+    <ng-template #options>
+      <bf-menu>
+        <button bfMenuItem (triggered)="result.set('Pinned.')">Pin</button>
+        <button bfMenuItem (triggered)="result.set('Hidden.')">Hide</button>
+      </bf-menu>
+    </ng-template>
+  `,
+})
+export class MenuTriggerExampleComponent {
+  protected readonly settings = Settings2;
+  protected readonly result = signal('');
+}
+```
+
+## Groups and dividers
+
+`bfMenuDivider` draws a line between groups of items (role `separator`, skipped by the arrow
+keys). `bfMenuGroup` groups items (role `group`). Name a group with `aria-label` when its items
+share a topic.
+
+```ts
+import { Component, signal } from '@angular/core';
+import {
+  BfMenuButtonComponent,
+  BfMenuComponent,
+  BfMenuDividerDirective,
+  BfMenuItemDirective,
+} from '@bitforgehq/ui/overlay';
+
+/**
+ * A menu with a divider before the destructive item.
+ *
+ * Items in reading order: the clipboard actions, a `bfMenuDivider`, then Delete.
+ */
+@Component({
+  selector: 'app-example-menu-groups',
+  imports: [BfMenuButtonComponent, BfMenuComponent, BfMenuDividerDirective, BfMenuItemDirective],
+  template: `
+    <bf-menu-button [menu]="edit" variant="text">Edit</bf-menu-button>
+    <p aria-live="polite" class="text-caption text-text-muted mt-3">{{ result() }}</p>
+
+    <ng-template #edit>
+      <bf-menu>
+        <button bfMenuItem (triggered)="result.set('Cut.')">Cut</button>
+        <button bfMenuItem (triggered)="result.set('Copied.')">Copy</button>
+        <div bfMenuDivider></div>
+        <button bfMenuItem (triggered)="result.set('Deleted.')">Delete</button>
+      </bf-menu>
+    </ng-template>
+  `,
+})
+export class MenuGroupsExampleComponent {
+  protected readonly result = signal('');
+}
+```
+
+## Checkbox and radio items
+
+`bfMenuItemCheckbox` is a toggle (role `menuitemcheckbox`) with a check mark while `checked`.
+`bfMenuItemRadio` is one choice of a set (role `menuitemradio`) with a dot while `checked`. Radio
+items in the same `bfMenuGroup` are exclusive. Activating either one closes the menu.
+
+A checkbox item flips its own `checked` when activated and emits `changed` (and the model's
+`checkedChange`) with the new state, so bind it two-way, `[(checked)]="showGrid"`, and react in
+`(changed)`. With a one-way `[checked]` binding, always
+update your state in `(triggered)`: if you skip the update (a guarded toggle), the item's
+`aria-checked` no longer matches your state. For radio items, bind `[checked]` and set your state
+in `(triggered)`.
+
+```ts
+import { Component, signal } from '@angular/core';
+import {
+  BfMenuButtonComponent,
+  BfMenuComponent,
+  BfMenuDividerDirective,
+  BfMenuGroupDirective,
+  BfMenuItemCheckboxDirective,
+  BfMenuItemRadioDirective,
+} from '@bitforgehq/ui/overlay';
+
+type Density = 'compact' | 'comfortable';
+
+/**
+ * Checkbox and radio items.
+ *
+ * "Show grid" is a two-way bound checkbox item; the density radio items share one `bfMenuGroup`.
+ */
+@Component({
+  selector: 'app-example-menu-checkable',
+  imports: [
+    BfMenuButtonComponent,
+    BfMenuComponent,
+    BfMenuDividerDirective,
+    BfMenuGroupDirective,
+    BfMenuItemCheckboxDirective,
+    BfMenuItemRadioDirective,
+  ],
+  template: `
+    <bf-menu-button [menu]="view" variant="text">View</bf-menu-button>
+    <p class="text-caption text-text-muted mt-3">
+      Grid {{ showGrid() ? 'on' : 'off' }} · {{ density() }}
+    </p>
+
+    <ng-template #view>
+      <bf-menu>
+        <button bfMenuItemCheckbox [(checked)]="showGrid">Show grid</button>
+        <div bfMenuDivider></div>
+        <div bfMenuGroup aria-label="Density">
+          <button
+            bfMenuItemRadio
+            [checked]="density() === 'compact'"
+            (triggered)="density.set('compact')"
+          >
+            Compact
+          </button>
+          <button
+            bfMenuItemRadio
+            [checked]="density() === 'comfortable'"
+            (triggered)="density.set('comfortable')"
+          >
+            Comfortable
+          </button>
+        </div>
+      </bf-menu>
+    </ng-template>
+  `,
+})
+export class MenuCheckableExampleComponent {
+  protected readonly showGrid = signal(true);
+  protected readonly density = signal<Density>('comfortable');
+}
+```
+
+## Submenus
+
+Put `[bfMenuTriggerFor]` on a `bfMenuItem` to open another `bf-menu` from it. The item shows a
+chevron at the inline end and gets `aria-haspopup="menu"` and `aria-expanded`. The submenu opens
+beside the item, at its inline end (to the left in right-to-left pages), and flips when there is
+no room. `ArrowRight` (`ArrowLeft` in RTL), `Enter`, `Space` or the pointer open it. `ArrowLeft`
+(`ArrowRight` in RTL) or `Escape` close it and put focus back on the item. Activating an item in
+a submenu closes every menu.
+
+```ts
+import { Component, signal } from '@angular/core';
+import {
+  BfMenuButtonComponent,
+  BfMenuComponent,
+  BfMenuItemDirective,
+  BfMenuTriggerDirective,
+} from '@bitforgehq/ui/overlay';
+
+/**
+ * A menu item that opens a submenu.
+ *
+ * An item with `[bfMenuTriggerFor]` opens the next menu beside it (ArrowRight opens it too).
+ */
+@Component({
+  selector: 'app-example-menu-submenus',
+  imports: [BfMenuButtonComponent, BfMenuComponent, BfMenuItemDirective, BfMenuTriggerDirective],
+  template: `
+    <bf-menu-button [menu]="rowActions">Actions</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 [bfMenuTriggerFor]="moveTo">Move to</button>
+      </bf-menu>
+    </ng-template>
+
+    <ng-template #moveTo>
+      <bf-menu>
+        <button bfMenuItem (triggered)="result.set('Moved to Inbox.')">Inbox</button>
+        <button bfMenuItem (triggered)="result.set('Moved to Archive.')">Archive</button>
+      </bf-menu>
+    </ng-template>
+  `,
+})
+export class MenuSubmenusExampleComponent {
+  protected readonly result = signal('');
+}
+```
+
+## Links as items
+
+A navigation item is a real link: put `bfMenuItem` on an `<a>` with `href`, or with your app's
+`routerLink` (the library itself does not depend on the router). It keeps its link semantics for
+the browser (open in a new tab, the status bar URL) and gets role `menuitem`. `Enter` and a click
+follow it, and so does `Space`, which a plain link ignores. Activating an item closes the menu;
+any navigation to another URL path (a link item, the browser's back button, a redirect) closes an
+open menu too, while a query- or fragment-only change leaves it open. A disabled link item
+(`bfMenuItemDisabled`) does not navigate on a click or `Enter`, with `href` or `routerLink`.
+
+```ts
+import { Component } from '@angular/core';
+import { RouterLink } from '@angular/router';
+import {
+  BfMenuButtonComponent,
+  BfMenuComponent,
+  BfMenuItemDirective,
+} from '@bitforgehq/ui/overlay';
+
+/** Links as menu items: a router link and an external link. */
+@Component({
+  selector: 'app-example-menu-links',
+  imports: [RouterLink, BfMenuButtonComponent, BfMenuComponent, BfMenuItemDirective],
+  template: `
+    <bf-menu-button [menu]="help" variant="text">Help</bf-menu-button>
+
+    <ng-template #help>
+      <bf-menu>
+        <a bfMenuItem routerLink="/components/menu-button">Menu button docs</a>
+        <a bfMenuItem href="https://bitforge.ch">Bitforge</a>
+      </bf-menu>
+    </ng-template>
+  `,
+})
+export class MenuLinksExampleComponent {}
+```
+
+## Placement
+
+`bfMenuPlacement` on a trigger (`placement` on `bf-menu-button`) sets where the menu opens:
+`'below-start'` (default), `'below-end'`, `'above-start'` or `'above-end'`. `start` and `end`
+follow the text direction. When the menu would overflow the viewport, it flips to the other
+side vertically first, then to the other alignment. The panel is at least 12 rem wide and
+scrolls past 24 rem or the viewport height minus 2 rem.
+
+```ts
+import { Component, signal } from '@angular/core';
+import { BfIconComponent } from '@bitforgehq/ui/icons';
+import {
+  BfMenuComponent,
+  BfMenuItemDirective,
+  BfMenuTriggerDirective,
+} from '@bitforgehq/ui/overlay';
+import { Columns3 } from 'lucide';
+
+/**
+ * A menu aligned to the trigger's end.
+ *
+ * `bfMenuPlacement="below-end"` opens the menu under the trigger, aligned to its inline end.
+ */
+@Component({
+  selector: 'app-example-menu-placement',
+  imports: [BfIconComponent, BfMenuComponent, BfMenuItemDirective, BfMenuTriggerDirective],
+  template: `
+    <div class="flex justify-end">
+      <button
+        type="button"
+        class="border-border-strong text-text rounded-control inline-flex h-10 items-center gap-2 border px-4"
+        [bfMenuTriggerFor]="columns"
+        bfMenuPlacement="below-end"
+      >
+        <bf-icon [icon]="columnsIcon" size="sm" />
+        Columns
+      </button>
+    </div>
+    <p aria-live="polite" class="text-caption text-text-muted mt-3">{{ result() }}</p>
+
+    <ng-template #columns>
+      <bf-menu>
+        <button bfMenuItem (triggered)="result.set('Owner column shown.')">Owner</button>
+        <button bfMenuItem (triggered)="result.set('Due date column shown.')">Due date</button>
+      </bf-menu>
+    </ng-template>
+  `,
+})
+export class MenuPlacementExampleComponent {
+  protected readonly columnsIcon = Columns3;
+  protected readonly result = signal('');
+}
+```
+
+## Sizes
+
+Items are 32 (`sm`), 36 (`md`) or 44 px (`lg`) tall. Unset, `size` follows `provideBfDefaults()`
+(`controlSize`, `md` by default). Under a coarse pointer (touch) `sm` and `md` rows grow to 44 px.
+
+```ts
+import { Component, signal } from '@angular/core';
+import {
+  BfMenuButtonComponent,
+  BfMenuComponent,
+  BfMenuItemDirective,
+} from '@bitforgehq/ui/overlay';
+
+/**
+ * A small menu for a dense toolbar.
+ *
+ * `size="sm"` sets the item height to 32 px, independent of the trigger's size.
+ */
+@Component({
+  selector: 'app-example-menu-sizes',
+  imports: [BfMenuButtonComponent, BfMenuComponent, BfMenuItemDirective],
+  template: `
+    <bf-menu-button [menu]="sort" size="sm" variant="text">Sort</bf-menu-button>
+    <p aria-live="polite" class="text-caption text-text-muted mt-3">{{ result() }}</p>
+
+    <ng-template #sort>
+      <bf-menu size="sm">
+        <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 MenuSizesExampleComponent {
+  protected readonly result = signal('');
+}
+```
+
+## Desktop
+
+Built for desktop: hovering an item gives it the `surface-muted` fill and the pointer cursor (a disabled item shows `not-allowed` and no fill), and the focus ring is added for keyboard focus only. A submenu opens on hover and stays open while the pointer moves diagonally towards it. Items are 36 px (`md`) by default, 32 px at `sm` for dense apps, and 44 px under a coarse pointer.
+
+## Theming
+
+- Panel: `bg-surface`, `text-text`, a 1 px `border-border`, `rounded-card`, `shadow-floating`,
+  `p-1`.
+- Item: `rounded-field`, `text-body` (`text-label-sm` at `sm`); hover and focus
+  `bg-surface-muted`, keyboard focus adds the `ring-ring` focus ring; disabled `text-disabled`.
+- Divider: a 1 px `border-border` line. The check mark, the radio dot and the submenu chevron are
+  drawn in the item's text colour.
+
+## Accessibility
+
+- Roles: the panel is `role="menu"` (vertical). Items are `menuitem`, `menuitemcheckbox` or
+  `menuitemradio` with `aria-checked`, groups are `group` and dividers `separator`. The trigger
+  has `aria-haspopup="menu"`, `aria-expanded` and, while open, `aria-controls`. A menu is named
+  by the trigger that opened it (`aria-labelledby`; the trigger gets an id when it has none,
+  read each time the menu opens) unless you set `ariaLabel` or `ariaLabelledby`. A submenu is
+  named by its parent item.
+- The check mark, the dot and the chevron are CSS drawings: they add nothing to an item's
+  accessible name, and they stay visible under forced colours (Windows High Contrast), where the
+  focused item is drawn in `Highlight` (a focused disabled item in `GrayText` with a `Highlight`
+  outline).
+- Disabled items stay focusable, so screen-reader users find them, and announce
+  `aria-disabled="true"` (APG). They do not activate.
+- Focus: opening the menu moves focus to its first item (to the last with `ArrowUp`). Closing it
+  with `Escape`, `Tab` or an item returns focus to the trigger. The items are not in the page's
+  tab order; `Tab` leaves the menu. A menu opened inside a dialog closes on `Escape` without
+  closing the dialog.
+- Pointer: rows are at least 32 px tall, 44 px under a coarse pointer. An open submenu stays open
+  while the pointer moves diagonally towards it across other items (CDK menu aim).
+
+### Keyboard
+
+From the [APG menu button](https://www.w3.org/WAI/ARIA/apg/patterns/menu-button/) and
+[menu](https://www.w3.org/WAI/ARIA/apg/patterns/menubar/) patterns:
+
+| Key                                                        | Where           | Action                                                          |
+| ---------------------------------------------------------- | --------------- | --------------------------------------------------------------- |
+| <kbd>Enter</kbd> / <kbd>Space</kbd> / <kbd>ArrowDown</kbd> | Trigger         | Opens the menu and focuses the first item                       |
+| <kbd>ArrowUp</kbd>                                         | Trigger         | Opens the menu and focuses the last item                        |
+| <kbd>ArrowDown</kbd> / <kbd>ArrowUp</kbd>                  | Menu            | Next / previous item, wrapping at the ends                      |
+| <kbd>Home</kbd> / <kbd>End</kbd>                           | Menu            | First / last item                                               |
+| <kbd>A</kbd>–<kbd>Z</kbd>, <kbd>0</kbd>–<kbd>9</kbd>       | Menu            | Next item whose label starts with the typed text                |
+| <kbd>Enter</kbd> / <kbd>Space</kbd>                        | Item            | Activates the item (toggles a checkbox, picks a radio), closes  |
+| <kbd>ArrowRight</kbd> (RTL <kbd>ArrowLeft</kbd>)           | Submenu item    | Opens the submenu and focuses its first item                    |
+| <kbd>ArrowLeft</kbd> (RTL <kbd>ArrowRight</kbd>)           | Submenu         | Closes the submenu, focus back on its item                      |
+| <kbd>Escape</kbd>                                          | Menu or submenu | Closes it; focus back on the trigger (or the parent item)       |
+| <kbd>Tab</kbd>                                             | Menu            | Closes every menu, focus back on the trigger, then Tab moves on |
+
+## Inputs
+
+| Name             | Type                                                        | Default     | Description                                                                                                                                           |
+| ---------------- | ----------------------------------------------------------- | ----------- | ----------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `size`           | `BfSize \| undefined` (`'sm' \| 'md' \| 'lg' \| undefined`) | `undefined` | Row height of its items: sm 32, md 36, lg 44 px (44 px under a coarse pointer); unset follows `provideBfDefaults()` (`controlSize`, `md` by default). |
+| `ariaLabel`      | `string`                                                    | `''`        | Accessible name of the menu. Empty: the menu is named by the trigger that opened it (APG).                                                            |
+| `ariaLabelledby` | `string`                                                    | `''`        | Id of the element that names the menu; wins over the trigger.                                                                                         |
+
+## Slots
+
+- `default`: The items (`bfMenuItem`, `bfMenuItemCheckbox`, `bfMenuItemRadio`), groups and dividers.
+
+## Notes
+
+### Do
+
+- Word items as verbs or destinations ("Rename", "Move to", "Settings") and keep the list short.
+- Put destructive items last, after a divider.
+- Use checkbox and radio items for view settings that apply at once ("Show grid", "Density").
+- Use `<a bfMenuItem>` for items that navigate, so they are real links.
+
+### Don't
+
+- Don't put form fields, sliders or other widgets inside a menu; use a dialog.
+- Don't nest submenus more than one level deep.
+- Don't hide the only way to do something in a menu; frequent actions belong in the toolbar.
+- Don't use a menu for site navigation (a list of pages); use links in a `nav`.
+
+## Migration notes
+
+### 0.3.0
+
+New `changed` output on `bfMenuItemCheckbox`: the new `checked` state right after the user toggles
+the item (after `triggered`, beside the model's `checkedChange`), so it has the one `changed` of
+every value control.
+
+New `bf-menu` and its parts in `@bitforgehq/ui/overlay`, on the Angular CDK menu (APG menu button
+and menu patterns): `bfMenuItem` on a `<button>` or a link (`<a>` with `href` or `routerLink`),
+`bfMenuItemCheckbox` and `bfMenuItemRadio` (`checked`, CSS-drawn check mark and dot),
+`bfMenuGroup` (radio items exclusive), `bfMenuDivider` and `[bfMenuTriggerFor]` (on any element,
+or on an item for a submenu with a CSS chevron, mirrored in RTL). Items take `bfMenuItemDisabled`
+(focusable, `aria-disabled`) and `bfMenuItemTypeahead` and emit `triggered`; the trigger takes
+`bfMenuTriggerData` and `bfMenuPlacement` (`below-start` (default), `below-end`, `above-start`,
+`above-end`, flipping on overflow; submenus open beside their item) and emits `bfMenuOpened` and
+`bfMenuClosed`. `bf-menu` takes `size` (item rows `sm` 32, `md` 36, `lg` 44 px, 44 px under a
+coarse pointer; unset follows `provideBfDefaults()` `controlSize`), `ariaLabel` and
+`ariaLabelledby`; without either it is named by its trigger. Keyboard: `Enter`, `Space`,
+`ArrowDown` open on the first item, `ArrowUp` on the last; arrows wrap, `Home`/`End`, type-ahead,
+`Escape` and `Tab` close with focus back on the trigger, `ArrowRight`/`ArrowLeft` open and close
+submenus (swapped in RTL); `Space` also follows a link item (once, ignoring auto-repeat), and a
+disabled link item never navigates, also with `routerLink`. `bfMenuItemCheckbox` emits
+`checkedChange` with the state it flipped to, so `[(checked)]` binds it two-way. An open submenu
+stays open while the pointer moves diagonally towards it (CDK menu aim). Under forced colours the
+focused item is drawn in `Highlight`, a focused disabled one in `GrayText` on `Canvas` with a
+`Highlight` outline. A navigation to another URL path closes an open menu (query- and
+fragment-only changes do not); the trigger watches the URL only while its menu is open.
+
+JSDoc of `menu-item.directive.ts` for the API reference: `@summary`/`@since` on the exported
+symbols; `@binding` docs for the host-directive bindings `bfMenuItemDisabled`,
+`bfMenuItemTypeahead`, `triggered`, `checked`. No behaviour change.
+
+JSDoc of `menu-trigger.directive.ts` for the API reference: `@summary`/`@since` on the exported
+symbols; `@binding` docs for the host-directive bindings `bfMenuTriggerFor`, `bfMenuTriggerData`,
+`bfMenuOpened`, `bfMenuClosed`. No behaviour change.
+
+JSDoc of `menu.component.ts` for the API reference: `@slot` docs for `default`. No behaviour change.
+
+The two effects that write into the CDK host directives (`bfMenuItemCheckbox`'s `checked`,
+`bfMenuTrigger`'s `menuPosition` and `ngOnChanges`) carry an `effect-justified` comment: the CDK
+exposes no input they could derive from. No behaviour change.