@ticatec/topside-elements 1.0.0

package/dist/overlay/context-menu/README.md

@@ -0,0 +1,361 @@
+# ContextMenu
+
+A right-click context menu with full keyboard navigation, focus management, and ARIA support. Call `contextMenu.show(event, items)` from a `contextmenu` handler to display `ContextMenuItem` actions at the cursor position. The menu auto-flips to stay within the viewport, traps keyboard focus while open, and dismisses on outside-click, Escape, or focus loss.
+
+## Architecture
+
+ContextMenu is a **singleton controller** plus an internal **panel component** that auto-mounts itself on first use:
+
+- **`contextMenu` (singleton)** — a module-level instance holding `$state` (`visible`, `position`, `items`, `theme`, …). Import it from anywhere and call `.show(...)` / `.hide()` to drive the menu.
+- **Panel (internal)** — the first `show()` call lazily mounts the panel to `document.body` via Svelte's `mount()`. Subsequent calls reuse the same instance. **No `<ContextMenu />` to mount anywhere.**
+
+Like `MessageBox`, `Toast`, and `Indicator`, `ContextMenu` uses an auto-mounting singleton controller: all these controllers automatically mount their internal panels on first use without needing explicit board components in the component tree.
+
+## Features
+
+- **Right-Click Triggered**: Wired via the native `contextmenu` event.
+- **No Setup**: just import `contextMenu` and call `show()`. The panel mounts itself on first use.
+- **Full Keyboard Navigation**:
+  - **Arrow Up/Down**: Move focus between items (skips disabled and separator items; wraps around).
+  - **Enter / Space**: Execute the focused item.
+  - **Escape**: Close the menu.
+  - **Tab**: Trapped — `preventDefault` keeps focus inside.
+- **Focus Management**: On open, focus moves to the menu container; `aria-activedescendant` tracks the focused item for screen readers.
+- **Edge-Aware Positioning**: Clamps x/y so the menu stays in the viewport.
+- **Multiple Dismiss Paths**: Outside-click, Escape, or focus leaving the menu all close it.
+- **Hover Sync**: Mouse hover updates the same `.focused` state as keyboard navigation — visual highlighting is unified.
+- **Disabled & Separator Items**: Disabled items are dimmed and non-interactive; separator items render as a horizontal rule.
+- **Per-Item Icons**: Optional `icon` URL rendered as a 16×16 thumbnail.
+- **Per-Call Theme**: Optional 5th arg to `show()` renders as `data-theme` on the menu root — useful when the same menu needs to adapt to a dark drawer in a light page, etc.
+
+## Installation
+
+```bash
+npm install @ticatec/topside-elements
+```
+
+## Import
+
+```typescript
+import contextMenu, { type ContextMenuItem, type ActionCallback } from "@ticatec/topside-elements/ContextMenu";
+```
+
+(`contextMenu` is also available as a named export if you prefer: `import { contextMenu } from …`.)
+
+## Basic Usage
+
+Import the singleton and call `show()` from any `contextmenu` handler. **No app-root mounting needed** — the panel auto-mounts on first use.
+
+```svelte
+<script lang="ts">
+  import contextMenu from "@ticatec/topside-elements/ContextMenu";
+
+  const items = [
+    { text: "Copy",  action: () => console.log("copy") },
+    { text: "Paste", action: () => console.log("paste") },
+    { separator: true },
+    { text: "Delete", action: () => console.log("delete") }
+  ];
+</script>
+
+<div oncontextmenu={(e) => contextMenu.show(e, items)}>
+  Right-click here
+</div>
+```
+
+## API
+
+### `contextMenu` singleton
+
+| Method | Signature | Description |
+|--------|-----------|-------------|
+| `show` | `(event: MouseEvent, items: ContextMenuItem[], width?: number, height?: number, theme?: string) => void` | Opens the menu at `event.clientX/Y`, clamped to the viewport. `event.preventDefault()` is called internally. `width` / `height` default to `150` and are used both for the panel's min-size and for the viewport-edge clamp math. `theme`, if provided, is rendered as `data-theme` on the menu root for scoped styling. **First call lazily mounts the panel to `document.body`.** Calling `show()` while already open first resets state and re-renders at the new position. |
+| `hide` | `() => void` | Closes the menu. No-op if already hidden. |
+
+The controller also exposes its `$state` fields (`visible`, `position`, `items`, `width`, `height`, `theme`) — you can read them but normally don't need to.
+
+### `ContextMenuItem`
+
+```typescript
+interface ContextMenuItem {
+  text: string;            // Required: label text
+  action?: () => void;     // Run on click or Enter/Space (skipped for disabled/separator)
+  disabled?: boolean;      // Dimmed, non-interactive, skipped by keyboard nav
+  separator?: boolean;     // Renders as a horizontal rule (other fields ignored)
+  icon?: string;           // Image URL/path rendered in a 16×16 <img>
+  style?: string;          // Inline CSS applied to this item only
+}
+```
+
+### `ActionCallback`
+
+```typescript
+type ActionCallback = () => void;
+```
+
+### `OnContextMenu`
+
+```typescript
+type OnContextMenu = (event: MouseEvent, data: any) => void;
+```
+
+A convenience type for **your** `contextmenu` handlers — the controller itself doesn't take this signature (it takes `(event, items, …)`). Use it when you want a typed wrapper that captures per-target data alongside the event:
+
+```svelte
+<script lang="ts">
+  import { contextMenu, type OnContextMenu } from "@ticatec/topside-elements/ContextMenu";
+
+  // Typed handler — `data` is the row the user right-clicked
+  const handleContext: OnContextMenu = (event, data) => {
+    contextMenu.show(event, buildItemsFor(data));
+  };
+</script>
+
+{#each rows as row}
+  <div oncontextmenu={(e) => handleContext(e, row)}>{row.name}</div>
+{/each}
+```
+
+## Keyboard Navigation
+
+| Key | Action |
+|-----|--------|
+| **ArrowDown** | Move focus to the next enabled item (wraps to top). |
+| **ArrowUp** | Move focus to the previous enabled item (wraps to bottom). |
+| **Enter** / **Space** | Execute the focused item's `action` and close. |
+| **Escape** | Close the menu. |
+| **Tab** | Trapped — the menu keeps focus until dismissed. |
+
+Disabled items and separators are skipped during navigation. The `moveSelection` algorithm computes the list of enabled indices and cycles through them.
+
+## Behavior
+
+### Open Flow
+
+1. Caller invokes `contextMenu.show(event, items, …)` from an event handler.
+2. **First call only**: `show()` checks if the panel is mounted; if not, it lazily `mount(ContextMenuPanel, { target: document.body })` and flags it as mounted. Subsequent calls skip this.
+3. `show()` calls `event.preventDefault()` and resets `visible` to `false` (forces a clean re-render if a menu is already open).
+4. It writes `items`, `width`, `height`, `theme` into state, clamps `x`/`y` against the viewport, then flips `visible` to `true`.
+5. The panel's `$effect` notices the change, resets `focusedIndex` to `-1`, and after `await tick()` calls `.focus()` on the panel root — which is what makes the subsequent keyboard events land on the menu.
+
+> **`event.preventDefault()` must run synchronously.** If your `contextmenu` handler is `async` and you `await` something before calling `contextMenu.show(event, …)`, the browser will already have shown its native context menu — `preventDefault()` called inside `show()` is too late. Do any async work after `show()` (e.g. fetch the latest items, then call `show()` again with the fresh list).
+
+### Dismiss Flow
+
+Dismiss happens via the panel's `onblur` handler (no global window listener):
+
+- **Outside click**: Clicking outside the menu moves focus to `document.body` or another element → `onblur` fires → if `relatedTarget` is outside the panel, `hide()` is called.
+- **Escape key**: `handleKeyDown` calls `hide()` directly.
+- **Item click / Enter / Space**: runs the item's `action`, then `hide()`.
+- **Programmatic `hide()`**: Always available; no-op when already hidden.
+
+If `relatedTarget` is **inside** the panel (e.g. focus moving between items), the blur is ignored — the menu only closes when focus truly leaves.
+
+### ARIA
+
+- The menu root has `role="menu"`, items have `role="menuitem"`, separators have `role="separator"`.
+- `aria-activedescendant` on the root mirrors the focused item's `id` (`topside-menu-item-{index}`), so screen readers announce the highlighted item without moving DOM focus.
+- `aria-disabled` on disabled items.
+
+## Styling
+
+The panel reads these CSS custom properties. Defaults come from `topside-root.scss` — the names **match**, so overriding the root tokens or redefining them per-scope both work.
+
+```scss
+.topside-context-menu {
+  background-color: var(--topside-contextmenu-color-surface);
+  color: var(--topside-contextmenu-color);
+  border: 1px solid var(--topside-color-border-secondary);
+  box-shadow: var(--topside-contextmenu-shadow);
+  padding: var(--topside-contextmenu-margin);
+  min-width: var(--topside-contextmenu-minimal-width);
+  min-height: var(--topside-contextmenu-minimal-height);
+
+  .menu-item {
+    padding: var(--topside-contextmenu-item-margin);
+    gap: var(--topside-contextmenu-spacing);
+    border-radius: var(--topside-radius);
+    // hover / focused bg/color:
+    background-color: var(--topside-contextmenu-color-hover-surface);
+    color: var(--topside-contextmenu-color-hover);
+  }
+
+  .menu-separator {
+    background-color: var(--topside-contextmenu-color-separator);
+    margin: var(--topside-contextmenu-separator-margin) 0;
+  }
+}
+```
+
+| Variable | Default in `topside-root.scss` |
+|----------|--------------------------------|
+| `--topside-contextmenu-color-surface` | `var(--topside-color-surface)` (resolves to the theme surface) |
+| `--topside-contextmenu-color` | `var(--topside-color-primary)` (resolves to the theme text) |
+| `--topside-color-border-secondary` | `#e5e7eb` light / `#2d2d2d` dark (shared border token — same one used by Box / Indicator / Editor) |
+| `--topside-contextmenu-shadow` | `0 2px 4px -1px rgba(0,0,0,0.06), 0 4px 12px rgba(0,0,0,0.08)` |
+| `--topside-contextmenu-margin` | `6px 8px` |
+| `--topside-contextmenu-minimal-width` | `150px` |
+| `--topside-contextmenu-minimal-height` | `100px` |
+| `--topside-contextmenu-item-margin` | `8px` |
+| `--topside-contextmenu-spacing` | `8px` |
+| `--topside-contextmenu-separator-margin` | `8px` |
+| `--topside-contextmenu-color-hover-surface` | `#f3f4f6` |
+| `--topside-contextmenu-color-hover` | `#111827` |
+| `--topside-contextmenu-color-separator` | `#e5e7eb` |
+
+Because the surface/text/border tokens fall through to the theme-level `--topside-color-*` variables, **dark mode works automatically** — the `[data-theme="dark"]` block in `topside-root.scss` overrides those theme tokens and the menu picks up the change.
+
+### Custom Styling
+
+```css
+/* Rebrand the menu surface */
+:root {
+  --topside-contextmenu-color-surface: #ffffff;
+  --topside-contextmenu-color: #1f2937;
+}
+
+/* Tighter, denser menu */
+:root {
+  --topside-contextmenu-margin: 4px;
+  --topside-contextmenu-item-margin: 6px;
+  --topside-contextmenu-spacing: 6px;
+}
+```
+
+### Per-call theme
+
+Pass a `theme` string as the 5th arg to `show()` and target `[data-theme="…"].topside-context-menu` in CSS:
+
+```svelte
+<script>
+  // Open the same menu styled for a dark panel even when the page is light
+  function onDarkPanelContext(e) {
+    contextMenu.show(e, items, 150, 150, "dark-panel");
+  }
+</script>
+
+<style>
+  :global([data-theme="dark-panel"].topside-context-menu) {
+    background-color: #1f2937;
+    color: #f9fafb;
+  }
+</style>
+```
+
+## Examples
+
+### With Icons and Disabled Items
+
+```svelte
+<script>
+  import { contextMenu } from "@ticatec/topside-elements/ContextMenu";
+
+  let clipboardEmpty = true;
+
+  const items = [
+    { text: "Cut",    action: () => cut() },
+    { text: "Copy",   action: () => copy() },
+    { text: "Paste",  action: () => paste(), disabled: clipboardEmpty },
+    { separator: true },
+    { text: "Delete", action: () => del() }
+  ];
+</script>
+
+<div oncontextmenu={(e) => contextMenu.show(e, items)}>
+  Right-click for edit actions
+</div>
+```
+
+### Dynamic Items Per Target
+
+```svelte
+<script>
+  import { contextMenu } from "@ticatec/topside-elements/ContextMenu";
+
+  function itemsFor(node) {
+    const items = [{ text: "Properties", action: () => showProps(node) }];
+    if (node.type === "file") {
+      items.unshift(
+        { text: "Open", action: () => open(node) },
+        { separator: true }
+      );
+    }
+    return items;
+  }
+</script>
+
+{#each nodes as node}
+  <div oncontextmenu={(e) => contextMenu.show(e, itemsFor(node))}>
+    {node.name}
+  </div>
+{/each}
+```
+
+### Keyboard-Triggered
+
+The component itself doesn't expose a keyboard entry point — wire one yourself using the standard **Shift+F10** shortcut:
+
+```svelte
+<script>
+  import { contextMenu } from "@ticatec/topside-elements/ContextMenu";
+
+  let triggerEl;
+
+  const items = [
+    { text: "Rename", action: () => rename() },
+    { text: "Delete", action: () => del() }
+  ];
+
+  function handleKeydown(e) {
+    if ((e.shiftKey && e.key === "F10") || e.key === "ContextMenu") {
+      e.preventDefault();
+      const rect = triggerEl.getBoundingClientRect();
+      const fakeEvent = {
+        preventDefault: () => {},
+        clientX: rect.left,
+        clientY: rect.bottom
+      };
+      contextMenu.show(fakeEvent as MouseEvent, items);
+    }
+  }
+</script>
+
+<span
+  bind:this={triggerEl}
+  tabindex="0"
+  oncontextmenu={(e) => contextMenu.show(e, items)}
+  onkeydown={handleKeydown}
+>
+  Right-click or press Shift+F10
+</span>
+```
+
+## Best Practices
+
+1. **No setup needed.** Just `import contextMenu` and call `show()` from your `contextmenu` handler — the panel auto-mounts on first use.
+2. **Stop propagation on nested triggers** if you have multiple context-menu zones: `oncontextmenu={(e) => { e.stopPropagation(); contextMenu.show(e, items); }}`.
+3. **Disable rather than hide** unavailable actions — users learn what's possible from greyed-out items.
+4. **Use separators to group related actions** — more than 6–7 ungrouped items hurts scanability.
+5. **Keep labels short and verb-led** — "Delete", "Rename", "Properties".
+6. **Provide icons as small images** — they render at 16×16 with `object-fit: contain`; larger source images are scaled down.
+7. **Don't try to open two menus at once.** The controller is a singleton — calling `show()` while a menu is visible resets state and re-opens at the new position.
+8. **Provide a keyboard alternative** — Shift+F10 is the convention; see the example above.
+
+## Accessibility
+
+The component implements the standard menu keyboard model (ARIA Authoring Practices):
+
+- `role="menu"` / `role="menuitem"` / `role="separator"`
+- `aria-activedescendant` mirrors keyboard focus
+- `aria-disabled` on disabled items
+- Full keyboard support (Arrow keys, Enter, Space, Escape, Tab trap)
+- Focus moves to the menu on open and returns to a sane state on close
+
+## Related Components
+
+- [Dialog](../dialog/README.md) — Centered modal for custom content.
+- [MessageBox](../message-box/README.md) — Modal confirmations and acknowledged messages.
+- [Toast](../toast/README.md) — Transient notifications.
+- [Indicator](../indicator/README.md) — Full-screen loading spinner.
+- [Drawer](../drawer/README.md) — Slide-out side panel.
+- [Tooltip](../tooltip/README.md) — Hover-based contextual hints.