@featherk/composables 0.12.5 → 0.13.1

package/docs/menu/usePopupMenuFocusAndExclusivity.md

@@ -0,0 +1,105 @@
+# usePopupMenu Focus and Exclusivity
+
+[Back to usePopupMenu](https://github.com/NantHealth/featherk/blob/integration/packages/composables/docs/menu/usePopupMenu.md)
+
+This guide covers keyboard focus restoration and coordination between independently configured popup menus.
+
+## Focus Target Precedence
+
+For keyboard menu selection and Escape, configured focus targets resolve in this order:
+
+1. `resolveFocusTarget()`
+2. `focusTargetRef`
+3. `focusTargetContainerSelector`, resolved with `trigger.closest(selector)`
+4. For Escape only: `escapeFocusTarget()`
+5. For Escape only: `escapeFocusContainerSelector`
+6. The trigger
+
+Use the selector option for the common case where a button menu should return keyboard focus to its containing row or toolbar group:
+
+```ts
+const menu = usePopupMenu({
+  isOpen,
+  triggerRef,
+  menuRef,
+  triggerMode: "button",
+  focusTargetContainerSelector: ".k-table-row",
+  requestShow: () => (isOpen.value = true),
+  requestHide: () => (isOpen.value = false),
+});
+```
+
+The target is captured before `requestHide()` runs, so it remains available when shared state immediately clears `triggerRef`.
+
+## Close Behavior
+
+| Close path              | Focus behavior                                   |
+| ----------------------- | ------------------------------------------------ |
+| Keyboard menu selection | Configured focus target, then trigger            |
+| Escape                  | Configured target, Escape fallback, then trigger |
+| Pointer menu selection  | Trigger                                          |
+| Outside click           | Browser retains control                          |
+| Trigger click           | Browser retains control                          |
+| Anchor fully clipped    | No focus restoration                             |
+
+## Multiple Exclusive Menus
+
+Keep exclusivity outside `usePopupMenu`. `useExclusiveGroup` coordinates registries without coupling popup lifecycle to application state.
+
+```ts
+import { ref } from "vue";
+import { usePopupMenu } from "@featherk/composables/menu";
+import {
+  useActiveIdRegistry,
+  useExclusiveGroup,
+} from "@featherk/composables/registry";
+
+const group = useExclusiveGroup();
+const rowRegistry = useActiveIdRegistry<number>();
+const buttonRegistry = useActiveIdRegistry<number>();
+const rowMenuRef = ref<HTMLElement | null>(null);
+const buttonMenuRef = ref<HTMLElement | null>(null);
+
+group.register(rowRegistry);
+group.register(buttonRegistry);
+
+const rowMenu = usePopupMenu({
+  isOpen: rowRegistry.isActive,
+  triggerRef: rowRegistry.activeElement,
+  menuRef: rowMenuRef,
+  triggerMode: "row",
+  anchor: { activationPoint: true },
+  requestShow: () => {},
+  requestHide: () => rowRegistry.deactivate(),
+});
+
+const buttonMenu = usePopupMenu({
+  isOpen: buttonRegistry.isActive,
+  triggerRef: buttonRegistry.activeElement,
+  menuRef: buttonMenuRef,
+  triggerMode: "button",
+  anchor: true,
+  focusTargetContainerSelector: ".k-table-row",
+  requestShow: () => {},
+  requestHide: () => buttonRegistry.deactivate(),
+});
+
+const openRowMenu = (id: number, row: HTMLElement, event: MouseEvent) => {
+  group.deactivateOthers(rowRegistry);
+  if (
+    rowMenu.setAnchorActivation(row, {
+      triggerType: "click",
+      coordinates: { clientX: event.clientX, clientY: event.clientY },
+    })
+  ) {
+    rowRegistry.activate(id);
+  }
+};
+
+const openButtonMenu = (id: number) => {
+  group.deactivateOthers(buttonRegistry);
+  buttonRegistry.activate(id);
+};
+```
+
+`useExclusiveGroup` changes only active registry state. Each `usePopupMenu` instance continues to own its own ARIA, positioning, close reason, and focus behavior.

package/docs/menu/usePopupMenuGridOrchestration.md

@@ -0,0 +1,520 @@
+# Grid Popup Menu Orchestration
+
+[Back to usePopupMenu](https://github.com/NantHealth/featherk/blob/integration/packages/composables/docs/menu/usePopupMenu.md)
+
+This guide is the starting point for a Kendo Grid that uses `useGridA11y` and
+needs both a row context menu and an action-button menu.
+
+## Big Picture
+
+A grid with 100 rows may appear to need 100 row popups and 100 button popups.
+It does not. Those are logical menus: each interaction belongs to a particular
+record, but only one record in each menu family can be active at a time.
+
+Render one physical `Popup`/`Menu` pair for all row triggers and one physical
+pair for all equivalent button triggers. A registry connects each shared pair
+to the trigger that is active now.
+
+For a grid with both trigger kinds, the final architecture has:
+
+- two `useActiveIdRegistry` instances: one for rows and one for buttons;
+- one `useExclusiveGroup` containing those registries;
+- two `usePopupMenu` instances: one with `triggerMode: "row"` and one with
+  `triggerMode: "button"`;
+- two rendered `Popup`/`Menu` pairs total, regardless of row count.
+
+It is one shared popup controller and template **per menu behavior**, not one
+controller per row. A row trigger and a button trigger should not share the same
+`usePopupMenu` instance because they have different trigger semantics,
+positioning, menu items, and focus behavior.
+
+```mermaid
+flowchart LR
+  A[Grid row click or key] --> B[useGridRowAction]
+  B --> C[Row registry]
+  C --> D[Shared row usePopupMenu]
+  D --> E[One row Popup and Menu]
+
+  F[Action button click or key] --> G[Button registry]
+  G --> H[Shared button usePopupMenu]
+  H --> I[One button Popup and Menu]
+
+  C <--> J[useExclusiveGroup]
+  G <--> J
+  K[Grid keyboard event] --> L[useGridA11y]
+  K --> B
+```
+
+## Why This Orchestration Exists
+
+A boolean answers whether a menu is open, but a shared popup also needs to know
+which record owns it and which current DOM element should anchor it. This matters
+when sorting, paging, or virtualization replaces grid rows.
+
+Each composable owns one part of that problem:
+
+| Composable            | Responsibility                                                                                                                          |
+| --------------------- | --------------------------------------------------------------------------------------------------------------------------------------- |
+| `useGridA11y`         | Moves focus through the grid and maintains grid keyboard behavior. It does not open menus.                                              |
+| `useGridRowAction`    | Converts valid row clicks and Enter/Space presses into one normalized row action. It ignores buttons and other interactive descendants. |
+| `useActiveIdRegistry` | Tracks the active record id and resolves that id to its currently mounted row or button element.                                        |
+| `useExclusiveGroup`   | Closes the other registry before a row menu or button menu opens. It does not decide which id to activate.                              |
+| `usePopupMenu`        | Owns menu toggling, ARIA synchronization, positioning, outside-click handling, selection modality, and focus restoration.               |
+
+The registry is the bridge. Its `isActive` becomes `usePopupMenu.isOpen`, and
+its `activeElement` becomes `usePopupMenu.triggerRef`. Computed menu items and
+labels use `activeId` to resolve the active record.
+
+The exclusivity group coordinates independent registries without coupling
+`usePopupMenu` to grid policy. The consumer calls `deactivateOthers(registry)`
+before activating that registry. This guarantees that the row and button menus
+cannot remain open together.
+
+The shared popup uses `offset` positioning because Kendo's `anchor` prop resolves
+a template-ref name when the Popup mounts; it cannot reliably retarget one
+mounted Popup from row A to row B. `usePopupMenu` can remeasure the registry's
+current element after scrolling, resizing, or DOM replacement.
+
+## Quick Start
+
+1. Create one registry for each menu behavior and register both with one
+   `useExclusiveGroup`.
+2. Register every rendered row and button under its record id.
+3. Create one `usePopupMenu` instance per registry.
+4. Route row activation through `useGridRowAction` and button activation through
+   the button popup controller, deactivating the other group member first.
+5. Render one Popup/Menu pair per controller and derive its content from the
+   active id.
+
+## Complete Example
+
+The template contains many triggers but only two popup trees:
+
+```html
+<template>
+  <div ref="gridContainerRef" class="grid-container">
+    <Grid
+      ref="gridRef"
+      :data-items="records"
+      :columns="columns"
+      :data-item-key="'id'"
+      :row-render="renderRow"
+      @rowclick="handleRowClick"
+      @keydown="handleGridKeydown"
+    >
+      <template #actionsCell="{ props }">
+        <td>
+          <Button
+            :ref="
+              (element) =>
+                buttonRegistry.register(props.dataItem.id, element)
+            "
+            :svg-icon="moreVerticalIcon"
+            type="button"
+            aria-label="Quick actions"
+            aria-haspopup="menu"
+            aria-expanded="false"
+            tabindex="-1"
+            @click="toggleButtonMenu(props.dataItem.id)"
+            @keydown="handleButtonKeydown(props.dataItem.id, $event)"
+          />
+        </td>
+      </template>
+    </Grid>
+  </div>
+
+  <!-- Step 5: one physical row menu for every row trigger. -->
+  <Popup
+    id="shared-row-menu-popup"
+    :show="rowRegistry.isActive.value"
+    :offset="rowMenu.offset.value"
+    @close="rowMenu.handlePopupClose"
+  >
+    <strong>{{ rowMenuLabel }}</strong>
+    <Menu
+      ref="rowMenuRef"
+      :items="rowMenuItems"
+      :vertical="true"
+      @keydown.escape="rowMenu.handleMenuEscape"
+      @select="handleRowMenuSelect"
+    />
+  </Popup>
+
+  <!-- Step 5: one physical button menu for every action button. -->
+  <Popup
+    id="shared-button-menu-popup"
+    :show="buttonRegistry.isActive.value"
+    :offset="buttonMenu.offset.value"
+    @close="buttonMenu.handlePopupClose"
+  >
+    <strong>{{ buttonMenuLabel }}</strong>
+    <Menu
+      ref="buttonMenuRef"
+      :items="buttonMenuItems"
+      :vertical="true"
+      @keydown.escape="buttonMenu.handleMenuEscape"
+      @select="handleButtonMenuSelect"
+    />
+  </Popup>
+</template>
+
+<script setup lang="ts">
+import {
+  computed,
+  onMounted,
+  ref,
+  type ComponentPublicInstance,
+} from "vue";
+import { Grid } from "@progress/kendo-vue-grid";
+import { Button } from "@progress/kendo-vue-buttons";
+import { Menu } from "@progress/kendo-vue-layout";
+import { Popup } from "@progress/kendo-vue-popup";
+import { moreVerticalIcon } from "@progress/kendo-svg-icons";
+import {
+  useGridA11y,
+  useGridRowAction,
+  type RowActionContext,
+} from "@featherk/composables/grid";
+import {
+  usePopupMenu,
+  type KendoMenuSelectEvent,
+} from "@featherk/composables/menu";
+import {
+  useActiveIdRegistry,
+  useExclusiveGroup,
+} from "@featherk/composables/registry";
+
+type RecordItem = {
+  id: number;
+  name: string;
+  status: string;
+};
+
+const records = ref<RecordItem[]>([
+  { id: 1, name: "Alpha", status: "Active" },
+  { id: 2, name: "Beta", status: "Pending" },
+]);
+
+const columns = [
+  { field: "name", title: "Name" },
+  { field: "status", title: "Status" },
+  { cell: "actionsCell", title: "Actions", width: "90px" },
+];
+
+const gridRef = ref<ComponentPublicInstance | null>(null);
+const gridContainerRef = ref<HTMLElement | null>(null);
+const rowMenuRef = ref<ComponentPublicInstance | null>(null);
+const buttonMenuRef = ref<ComponentPublicInstance | null>(null);
+
+// Step 1: each menu behavior has one registry. The group coordinates them.
+const rowRegistry = useActiveIdRegistry<number>();
+const buttonRegistry = useActiveIdRegistry<number>();
+const menuGroup = useExclusiveGroup();
+menuGroup.register(rowRegistry);
+menuGroup.register(buttonRegistry);
+
+const activeRowRecord = computed(() =>
+  records.value.find((record) => record.id === rowRegistry.activeId.value),
+);
+const activeButtonRecord = computed(() =>
+  records.value.find((record) => record.id === buttonRegistry.activeId.value),
+);
+
+const rowMenuLabel = computed(() =>
+  activeRowRecord.value ? `Row actions for ${activeRowRecord.value.name}` : "",
+);
+const buttonMenuLabel = computed(() =>
+  activeButtonRecord.value
+    ? `Quick actions for ${activeButtonRecord.value.name}`
+    : "",
+);
+const rowMenuItems = computed(() => [
+  { text: "Open record", id: "open" },
+  { text: "View history", id: "history" },
+]);
+const buttonMenuItems = computed(() => [
+  { text: "Edit", id: "edit" },
+  { text: "Archive", id: "archive" },
+]);
+
+const closeRowMenu = () => rowRegistry.deactivate();
+const closeButtonMenu = () => buttonRegistry.deactivate();
+
+// Step 3: this single instance follows whichever row id is active.
+const rowMenu = usePopupMenu({
+  isOpen: rowRegistry.isActive,
+  triggerRef: rowRegistry.activeElement,
+  menuRef: rowMenuRef,
+  triggerMode: "row",
+  menuLabel: rowMenuLabel,
+  anchor: {
+    clipRoot: gridContainerRef,
+    activationPoint: true,
+  },
+  // Row activation captures its point before activating the registry.
+  requestShow: () => {},
+  requestHide: closeRowMenu,
+});
+
+// Step 3: this single instance follows whichever action button is active.
+const buttonMenu = usePopupMenu({
+  isOpen: buttonRegistry.isActive,
+  triggerRef: buttonRegistry.activeElement,
+  menuRef: buttonMenuRef,
+  triggerMode: "button",
+  menuLabel: buttonMenuLabel,
+  anchor: { clipRoot: gridContainerRef },
+  requestShow: (id) => {
+    if (typeof id === "number") buttonRegistry.activate(id);
+  },
+  requestHide: closeButtonMenu,
+});
+
+// Step 2: Kendo rowRender registers every current row DOM element. Static ARIA
+// remains on every row; usePopupMenu changes only aria-expanded.
+const renderRow = (h: any, tr: any, slots: any, props: any) =>
+  h(
+    "tr",
+    {
+      ...tr.props,
+      "aria-label": `${props.dataItem.name}, ${props.dataItem.status}`,
+      "aria-haspopup": "menu",
+      "aria-expanded": "false",
+      ref: (element: HTMLElement | null) =>
+        rowRegistry.register(props.dataItem.id, element),
+    },
+    slots,
+  );
+
+// Step 4: useGridRowAction ignores the nested Button automatically, so a
+// button click cannot also open the row menu.
+const { handleRowClick, handleRowKeyDown } = useGridRowAction<RecordItem>({
+  dataItems: records,
+  onRowAction: (record, context) => toggleRowMenu(record.id, context),
+});
+
+const toggleRowMenu = (
+  id: number,
+  context: RowActionContext<RecordItem>,
+) => {
+  if (rowRegistry.isIdActive(id)) {
+    closeRowMenu();
+    return;
+  }
+
+  const row = rowRegistry.resolve(id);
+  if (!row || !rowMenu.setAnchorActivation(row, context)) return;
+
+  // The group owns cross-menu exclusivity; this consumer owns the row id.
+  menuGroup.deactivateOthers(rowRegistry);
+  rowRegistry.activate(id);
+};
+
+const toggleButtonMenu = (id: number) => {
+  if (buttonRegistry.isIdActive(id)) {
+    buttonMenu.handleTriggerClick(id);
+    return;
+  }
+
+  // The group closes the row menu. Switching within this registry still needs
+  // a close first so handleTriggerClick takes its open path for the new id.
+  menuGroup.deactivateOthers(buttonRegistry);
+  if (buttonRegistry.isActive.value) closeButtonMenu();
+  buttonMenu.handleTriggerClick(id);
+};
+
+const handleButtonKeydown = (id: number, event: KeyboardEvent) => {
+  if (event.key === "Enter" || event.code === "Space") {
+    event.preventDefault();
+    toggleButtonMenu(id);
+    return;
+  }
+
+  buttonMenu.handleTriggerKeydown(event);
+};
+
+const { handleGridKeyDown, initA11y } = useGridA11y(gridRef);
+const handleGridKeydown = (event: KeyboardEvent) => {
+  handleGridKeyDown(event);
+  handleRowKeyDown(event);
+};
+
+const handleRowMenuSelect = (event: KendoMenuSelectEvent) => {
+  rowMenu.handleMenuSelect(event, (selection) => {
+    if (selection.item && activeRowRecord.value) {
+      console.log(selection.item.id, activeRowRecord.value);
+    }
+  });
+};
+
+const handleButtonMenuSelect = (event: KendoMenuSelectEvent) => {
+  buttonMenu.handleMenuSelect(event, (selection) => {
+    if (selection.item && activeButtonRecord.value) {
+      console.log(selection.item.id, activeButtonRecord.value);
+    }
+  });
+};
+
+onMounted(initA11y);
+</script>
+```
+
+## What Happens When a Row Opens
+
+1. `useGridRowAction` validates the click or keyboard event and supplies the
+   record plus activation coordinates.
+2. The consumer resolves the row element from `rowRegistry`.
+3. `setAnchorActivation` stores a trigger-relative pointer or keyboard point.
+4. `menuGroup.deactivateOthers(rowRegistry)` closes the button menu.
+5. `rowRegistry.activate(id)` changes both `isOpen` and `activeElement`.
+6. The one row Popup renders content for that id, and `usePopupMenu` sets the
+   active row's `aria-expanded` to `true`.
+
+When another row opens, the registry changes identity. `usePopupMenu` demotes the
+old row, follows the new row element, and reuses the same Popup/Menu tree.
+
+## What Happens When a Button Opens
+
+1. The button is already registered under its record id by its template ref.
+2. `menuGroup.deactivateOthers(buttonRegistry)` closes the row menu.
+3. `handleTriggerClick(id)` forwards the id to `requestShow`.
+4. `buttonRegistry.activate(id)` makes that button the active trigger.
+5. The one button Popup follows the active button and derives its content from
+   `buttonRegistry.activeId`.
+
+`useGridRowAction` ignores button descendants by default. This prevents a button
+click from also being interpreted as a row activation; no propagation workaround
+is required.
+
+## Multiple Buttons Per Row
+
+The button registry is not limited to one button in each row. It can register
+any number of equivalent buttons that all use the same shared Popup/Menu. Give
+each trigger a composite id containing both its button key and row id:
+
+```ts
+type ButtonKey = "edit" | "more";
+type ButtonTriggerId = `${ButtonKey}:${number}`;
+
+const buttonRegistry = useActiveIdRegistry<ButtonTriggerId>();
+
+const getButtonTriggerId = (
+  key: ButtonKey,
+  rowId: number,
+): ButtonTriggerId => `${key}:${rowId}`;
+```
+
+Register and activate each button with that composite id:
+
+```vue
+<Button
+  :ref="
+    (element) =>
+      buttonRegistry.register(
+        getButtonTriggerId('edit', props.dataItem.id),
+        element,
+      )
+  "
+  aria-label="Edit actions"
+  aria-haspopup="menu"
+  aria-expanded="false"
+  @click="toggleButtonMenu(getButtonTriggerId('edit', props.dataItem.id))"
+/>
+
+<Button
+  :ref="
+    (element) =>
+      buttonRegistry.register(
+        getButtonTriggerId('more', props.dataItem.id),
+        element,
+      )
+  "
+  aria-label="More actions"
+  aria-haspopup="menu"
+  aria-expanded="false"
+  @click="toggleButtonMenu(getButtonTriggerId('more', props.dataItem.id))"
+/>
+```
+
+The active composite id tells the consumer both which row and which button owns
+the popup. Parse it to derive the shared menu's label and items:
+
+```ts
+const activeButton = computed(() => {
+  const id = buttonRegistry.activeId.value;
+  if (!id) return null;
+
+  const [key, rowId] = id.split(":") as [ButtonKey, string];
+  const record = records.value.find((item) => item.id === Number(rowId));
+  return record ? { key, record } : null;
+});
+
+const buttonMenuItems = computed(() =>
+  activeButton.value?.key === "edit"
+    ? [{ text: "Rename", id: "rename" }]
+    : [{ text: "Archive", id: "archive" }],
+);
+```
+
+This still uses one button registry, one `usePopupMenu`, and one Popup/Menu tree
+for the whole grid. Use separate registries and popup controllers only when the
+buttons represent genuinely different menu behaviors, such as different focus,
+positioning, lifecycle, or exclusivity rules. For a reusable collection of
+ActionCell triggers, `@featherk/ui` also provides `useActionCellMenu`, which owns
+this composite-id orchestration.
+
+## Rules to Keep
+
+- Keep separate registries and popup controllers for row and button behavior.
+- One button registry may contain many buttons per row when they share one menu
+  behavior; use composite ids so every trigger remains unique.
+- Register both registries with `useExclusiveGroup` and call
+  `deactivateOthers` before activating either one.
+- Render `aria-haspopup="menu"` and `aria-expanded="false"` on every trigger.
+- Register elements through template refs so rerenders and virtualization update
+  the registry.
+- Capture row activation before activating the row id.
+- Bind `usePopupMenu.offset` instead of dynamically changing Kendo's `anchor`.
+- Derive labels, items, and business context from the active registry id.
+- Do not add row roles or focus behavior in popup code; `useGridA11y` and the
+  grid's interaction model own those semantics.
+
+## Trapping Focus in a Shared Popup
+
+Neither `rowMenu` nor `buttonMenu` above traps `Tab` inside its Popup - that's
+intentional (see `usePopupMenu.md`'s intro). If a specific shared popup needs
+it anyway, pair it with `usePopupTrap` using the same registry, and disable
+both its own Escape-focus logic and the underlying `focus-trap` library's
+independent `returnFocusOnDeactivate` default, so `usePopupMenu` remains the
+sole owner of close/focus-restoration decisions. Both shared Popups above stay
+permanently mounted (only `:show` toggles visibility) with pure `:offset`
+positioning (no real Kendo `anchor` ref), so `usePopupTrap`'s default
+class-based lookup can't reliably tell them apart - pin each trap to its own
+Popup by the `id` it already has:
+
+```ts
+usePopupTrap({
+  isOpen: rowRegistry.isActive,
+  triggerEl: rowRegistry.activeElement,
+  resolvePopupEl: () => document.getElementById("shared-row-menu-popup"),
+  initialFocus: () => document.activeElement as HTMLElement | null,
+  returnFocusToTrigger: false,
+  focusTrapOptions: { returnFocusOnDeactivate: false },
+});
+usePopupTrap({
+  isOpen: buttonRegistry.isActive,
+  triggerEl: buttonRegistry.activeElement,
+  resolvePopupEl: () => document.getElementById("shared-button-menu-popup"),
+  initialFocus: () => document.activeElement as HTMLElement | null,
+  returnFocusToTrigger: false,
+  focusTrapOptions: { returnFocusOnDeactivate: false },
+});
+```
+
+`usePopupTrap` already defaults `allowOutsideClick` to `true` - without it, a
+genuinely active trap on one menu would swallow clicks on the *other* trigger
+in the same row (e.g. the row menu trapping Tab while the user tries to click
+the action button). See `usePopupMenu.md`'s "Pairing with `usePopupTrap`"
+section for why each of these options is required.
+
+For deeper details, see [Shared Instances](https://github.com/NantHealth/featherk/blob/integration/packages/composables/docs/menu/usePopupMenuSharedInstance.md), [Activation-Point Anchors](https://github.com/NantHealth/featherk/blob/integration/packages/composables/docs/menu/usePopupMenuActivationAnchor.md), [Focus and Exclusivity](https://github.com/NantHealth/featherk/blob/integration/packages/composables/docs/menu/usePopupMenuFocusAndExclusivity.md), and [useExclusiveGroup](https://github.com/NantHealth/featherk/blob/integration/packages/composables/docs/registry/useExclusiveGroup.md).