@ixfx/components 0.3.1 → 0.4.0

package/docs-user/menu.md

@@ -0,0 +1,319 @@
+# Menu Infrastructure
+
+A custom menu system built on native HTML popovers with keyboard navigation, tickled focus management, and command routing.
+
+## Components
+
+| Component | Description |
+|------------|-------------|
+| `ixfx-menu-bar` | Horizontal container for menu triggers; handles arrow-key navigation between top-level menus |
+| `ixfx-menu-trigger` | Button or slot that opens a menu popover. Modes: `trigger` (button), `dropdown` (slot-only), `context` (right-click) |
+| `ixfx-menu-container` | The popover panel holding menu items; manages keyboard focus and tickled state |
+| `ixfx-menu-item` | Basic menu item that dispatches a `command` event |
+| `ixfx-menu-check-item` | Toggle checkbox item; dispatches `command` with `checked` state |
+| `ixfx-menu-radio-item` | Radio button item for use inside `ixfx-menu-radio-group` |
+| `ixfx-menu-radio-group` | Groups radio items; dispatches `radio-change` when selection changes |
+| `ixfx-menu-sub-trigger` | Menu item that reveals a nested submenu on hover or ArrowRight |
+| `ixfx-menu-separator` | Visual divider between menu sections |
+| `ixfx-menu-header` | Section label header |
+
+## Architecture
+
+Menus are built on the native HTML `<popover>` API. `ixfx-menu-trigger` owns a `<popover>` element and uses `showPopover()`/`hidePopover()` to open/close it. `ixfx-menu-container` is slotted into the popover and handles:
+
+- **Tickled focus management** — tracks which item should be focused based on keyboard vs mouse input
+- **Keyboard navigation** — Arrow keys, Home/End, Enter/Space to activate
+- **Icon section alignment** — detects whether any item in a section has an icon and pads all items consistently
+
+## Usage
+
+### Declarative Style
+
+Static menu markup in HTML:
+
+```html
+<ixfx-menu-bar>
+  <ixfx-menu-trigger label="File" @menu-command=${handleCommand}>
+    <ixfx-menu-container slot="menu">
+      <ixfx-menu-item command="new" label="New"></ixfx-menu-item>
+      <ixfx-menu-item command="open" label="Open"></ixfx-menu-item>
+      <ixfx-menu-separator></ixfx-menu-separator>
+      <ixfx-menu-item command="exit" label="Exit"></ixfx-menu-item>
+    </ixfx-menu-container>
+  </ixfx-menu-trigger>
+
+  <ixfx-menu-trigger label="Edit" @menu-command=${handleCommand}>
+    <ixfx-menu-container slot="menu">
+      <ixfx-menu-check-item command="bold" label="Bold" checked></ixfx-menu-check-item>
+      <ixfx-menu-check-item command="italic" label="Italic"></ixfx-menu-check-item>
+    </ixfx-menu-container>
+  </ixfx-menu-trigger>
+</ixfx-menu-bar>
+```
+
+### Imperative Style
+
+Building menus programmatically via Lit templates:
+
+```ts
+import { html } from 'lit';
+import { MenuItem } from './menu/menu-item.js';
+import { MenuContainer } from './menu/menu-container.js';
+import { MenuTrigger } from './menu/menu-trigger.js';
+import { MenuSeparator } from './menu/menu-separator.js';
+import { MenuCheckItem } from './menu/menu-check-item.js';
+
+function buildEditMenu(onCommand: (cmd: string) => void) {
+  return html`
+    <ixfx-menu-container slot="menu">
+      <ixfx-menu-check-item
+        command="bold"
+        label="Bold"
+        @command=${(e: CustomEvent) => onCommand(e.detail.command)}
+      ></ixfx-menu-check-item>
+      <ixfx-menu-check-item
+        command="italic"
+        label="Italic"
+        @command=${(e: CustomEvent) => onCommand(e.detail.command)}
+      ></ixfx-menu-check-item>
+    </ixfx-menu-container>
+  `;
+}
+
+const trigger = document.createElement('ixfx-menu-trigger');
+trigger.label = 'Edit';
+trigger.addEventListener('menu-command', (e) => console.log(e.detail));
+trigger.appendChild(buildEditMenu(myHandler));
+```
+
+### Building Menus from TreeNode Structure
+
+Use `menuFromTree()` or `menuFromTreeToElements()` to construct menus from a `TreeNode[]` array:
+
+```ts
+import { menuFromTree, menuFromTreeToElements } from './menu/menu-from-tree.js';
+import type { TreeNode } from './tree/types.js';
+
+const nodes: TreeNode[] = [
+  { item: { key: 'new', label: 'New' } },
+  { item: { key: 'open', label: 'Open...' } },
+  { item: { key: 'sep1', label: '-' } }, // becomes separator
+  { item: { key: 'sep2', label: '# File' } }, // becomes header "File"
+  {
+    item: { key: 'submenu', label: 'Submenu' },
+    children: [
+      { item: { key: 'action1', label: 'Action 1' } },
+      { item: { key: 'action2', label: 'Action 2' } },
+    ],
+  },
+  { item: { key: 'quit', label: 'Quit' } },
+];
+```
+
+**Rules:**
+- `label === "-"` → separator
+- `label.startsWith("# ")` → header (prefix stripped)
+- Node has `children` → submenu trigger (no command)
+- Leaf node → menu item with `command = item.key`
+
+**In Lit templates** (declarative):
+```ts
+// Inside a Lit component's render()
+return html`
+  <ixfx-menu-trigger label="File">
+    <ixfx-menu-container slot="menu">
+      ${menuFromTree(nodes, { onCommand: this.handleCommand, registry: this.registry })}
+    </ixfx-menu-container>
+  </ixfx-menu-trigger>
+`;
+```
+
+**Imperatively** (using DOM):
+```ts
+const elements = menuFromTreeToElements(nodes, { onCommand: handleCommand });
+for (const el of elements) {
+  container.appendChild(el);
+}
+```
+
+### Programmatic Open/Close
+
+```ts
+const trigger = document.querySelector('ixfx-menu-trigger');
+
+// Open
+trigger.openMenu();
+
+// Close
+trigger.closeMenu();
+
+// Check state
+console.log(trigger.isOpen);
+```
+
+### Submenus
+
+Use `ixfx-menu-sub-trigger` with a nested `ixfx-menu-container` in its `submenu` slot:
+
+```html
+<ixfx-menu-item command="view" label="View">
+  <ixfx-menu-container slot="submenu">
+    <ixfx-menu-item command="zoom-in" label="Zoom In"></ixfx-menu-item>
+    <ixfx-menu-item command="zoom-out" label="Zoom Out"></ixfx-menu-item>
+  </ixfx-menu-container>
+</ixfx-menu-item>
+```
+
+### Radio Groups
+
+```html
+<ixfx-menu-radio-group name="alignment" value="left" @radio-change=${handleAlign}>
+  <ixfx-menu-radio-item value="left" label="Left"></ixfx-menu-radio-item>
+  <ixfx-menu-radio-item value="center" label="Center"></ixfx-menu-radio-item>
+  <ixfx-menu-radio-item value="right" label="Right"></ixfx-menu-radio-item>
+</ixfx-menu-radio-group>
+```
+
+### Context Menu Mode
+
+Set `mode="context"` on the trigger. The menu appears at the cursor position on right-click:
+
+```html
+<ixfx-menu-trigger mode="context" @menu-command=${handleContextMenu}>
+  <ixfx-menu-container slot="menu">
+    <ixfx-menu-item command="cut" label="Cut"></ixfx-menu-item>
+    <ixfx-menu-item command="copy" label="Copy"></ixfx-menu-item>
+    <ixfx-menu-item command="paste" label="Paste"></ixfx-menu-item>
+  </ixfx-menu-container>
+</ixfx-menu-trigger>
+```
+
+### Command Registry Integration
+
+Pass a `CommandRegistry` to the trigger and/or container. Items resolve their label and icon from the registry if not explicitly set:
+
+```ts
+import { CommandRegistry } from '@clinth/ui-commands';
+
+const registry = new CommandRegistry();
+registry.register('bold', { label: 'Bold', icon: 'bold' });
+registry.register('italic', { label: 'Italic', icon: 'italic' });
+
+trigger.registry = registry;
+container.registry = registry;
+```
+
+```html
+<!-- label and icon resolved from registry -->
+<ixfx-menu-item command="bold"></ixfx-menu-item>
+<ixfx-menu-item command="italic"></ixfx-item>
+```
+
+### Keyboard Shortcuts
+
+Pass a `KeyboardManager` to display shortcuts next to menu items:
+
+```ts
+import { KeyboardManager } from '@clinth/ui-commands';
+
+keyboardManager.bind('bold', { key: 'b', modifiers: ['ctrl'] });
+keyboardManager.bind('italic', { key: 'i', modifiers: ['ctrl'] });
+
+trigger.keyboardManager = keyboardManager;
+```
+
+## Styling
+
+### CSS Custom Properties
+
+| Variable | Default | Description |
+|----------|---------|-------------|
+| `--_item-hover-bg` | `var(--surface-6)` | Background on mouse hover |
+| `--_item-focused-bg` | `var(--surface-6)` | Background when keyboard-focused (tickled) |
+| `--_trigger-hover-bg` | `var(--surface-4)` | Trigger button hover background |
+| `--_trigger-hover-opacity` | `1` | Trigger button hover opacity |
+
+The popup surface uses these from `popupSurfaceStyles`:
+
+| Variable | Description |
+|----------|-------------|
+| `--surface-5` | Menu background |
+| `--surface-6` | Menu border |
+| `--surface-5-text` | Menu text color |
+| `--shadow-m` | Box shadow |
+
+### Custom Item Background Colors
+
+```css
+/* Apply to ixfx-menu-container */
+ixfx-menu-container {
+  --_item-hover-bg: #ffdddd;
+  --_item-focused-bg: #ffcccc;
+}
+```
+
+### Custom Trigger Styling
+
+```css
+ixfx-menu-trigger {
+  --_trigger-hover-bg: #eeeeee;
+  --_trigger-hover-opacity: 0.8;
+}
+```
+
+### Per-Item Styling
+
+Style menu items from the outside by targeting their tag name or by attaching a class attribute and selecting within:
+
+```css
+ixfx-menu-item[command="delete"] .item {
+  color: red;
+}
+
+/* Target a specific menu via a wrapper */
+.file-menu ixfx-menu-item .item {
+  font-weight: bold;
+}
+```
+
+## Events
+
+| Event | Detail | Description |
+|-------|--------|-------------|
+| `command` | `{ command, args, checked? }` | Fired by `ixfx-menu-item`, `ixfx-menu-check-item` |
+| `radio-select` | `{ value }` | Fired by `ixfx-menu-radio-item` |
+| `radio-change` | `{ name, value }` | Fired by `ixfx-menu-radio-group` when selection changes |
+| `menu-command` | `{ command, value?, checked? }` | Bubbles up from `ixfx-menu-trigger` |
+
+## `ixfx-menu-command-controller`
+
+A helper class that listens for `command` events and invokes a `CommandRegistry`:
+
+```ts
+import { MenuCommandController } from './menu/menu-command-controller.js';
+
+const ctrl = new MenuCommandController({ registry, target: document });
+ctrl.start();
+
+// Now any menu item with a matching command will invoke the registry
+```
+
+## Mode Reference
+
+`ixfx-menu-trigger` supports three `mode` values:
+
+| Mode | Trigger Behavior |
+|------|-----------------|
+| `trigger` | Shows a button labeled with the `label` property |
+| `dropdown` | No button shown; expects a custom trigger in the `trigger` slot |
+| `context` | Opens at cursor position on right-click |
+
+## Placement
+
+The `placement` attribute controls popover anchoring:
+
+| Value | Position |
+|-------|----------|
+| `bottom-start` | Below trigger, left edge aligned (default) |
+| `bottom-end` | Below trigger, right edge aligned |
+| `right-start` | To the right of trigger, top edge aligned |