@featherk/composables 0.12.4 → 0.13.0

package/dist/menu/usePopupMenu.d.ts

@@ -6,17 +6,43 @@ export type PopupMenuOffset = {
     left: number;
     top: number;
 };
-/** Offset-positioning options for a Popup with a dynamically changing trigger. */
-export type PopupMenuAnchorOptions = {
+export type PopupMenuAnchorActivation = {
+    triggerType: "click" | "keyboard";
+    coordinates?: {
+        clientX: number;
+        clientY: number;
+    };
+};
+export type PopupMenuActivationPointOptions = {
+    /** Added to pointer coordinates after they are made trigger-relative. */
+    pointerOffset?: {
+        x?: number;
+        y?: number;
+    };
+    /** Trigger-relative keyboard position. Defaults to 8px from the left and vertically centered. */
+    keyboardPosition?: {
+        x?: number;
+        y?: number | "top" | "center" | "bottom";
+    };
+};
+type PopupMenuAnchorBaseOptions = {
     /** Scrollable/clipping container used for out-of-view dismissal. */
     clipRoot?: MaybeRefOrGetter<Element | null>;
     /** Closes the menu after its trigger leaves the clipping container. */
     hideWhenAnchorClipped?: boolean;
-    /** Intersection ratio required to keep the anchor considered visible. Defaults to `0.5`. */
+    /** Intersection ratio required to keep the anchor considered visible. */
     intersectionThreshold?: number | number[];
-    /** Overrides the trigger rect for pointer-positioned menus. */
-    getRect?: () => DOMRect | null;
 };
+/** Offset-positioning options for a Popup with a dynamically changing trigger. */
+export type PopupMenuAnchorOptions = PopupMenuAnchorBaseOptions & ({
+    /** Tracks a pointer or keyboard activation point relative to the trigger. */
+    activationPoint: true | PopupMenuActivationPointOptions;
+    getRect?: never;
+} | {
+    activationPoint?: never;
+    /** Resolves a custom anchor rect from the current trigger element. */
+    getRect?: (trigger: HTMLElement) => DOMRect | null;
+});
 /** Why the popup was closed, including the focus policy for mouse paths. */
 export type PopupMenuCloseReason = 
 /** Keyboard-driven menu selection (Enter/Space on a menu item); restores the configured focus target. */
@@ -48,8 +74,8 @@ export type KendoMenuSelectEvent<TItem = {
 };
 /** Options for configuring {@link usePopupMenu}. */
 export type UsePopupMenuOptions = {
-    /** Reactive flag reflecting whether the popup menu is currently open. */
-    isOpen: Ref<boolean>;
+    /** Read-only reactive flag reflecting whether the popup menu is currently open. */
+    isOpen: Readonly<Ref<boolean>>;
     /** Ref to the popup menu element or component. Used for outside-click detection. */
     menuRef: PopupMenuElementRef;
     /** Ref to the trigger button element or component. Ignored by outside-click detection. */
@@ -68,6 +94,12 @@ export type UsePopupMenuOptions = {
      * Takes precedence over `focusTargetRef`.
      */
     resolveFocusTarget?: () => HTMLElement | null;
+    /**
+     * Resolves the closest matching ancestor of the trigger as the configured
+     * keyboard-close focus target. Used after `resolveFocusTarget` and
+     * `focusTargetRef`.
+     */
+    focusTargetContainerSelector?: string;
     /**
      * Resolves a fallback focus target for Escape closes when no `focusTargetRef`/
      * `resolveFocusTarget` is configured, e.g. the trigger's containing grid row so
@@ -110,15 +142,17 @@ export type UsePopupMenuOptions = {
 };
 /** Functions returned by {@link usePopupMenu} for the action menu. */
 export type UsePopupMenuReturn = {
+    /** Captures an activation relative to a trigger for activation-point anchoring. */
+    setAnchorActivation: (trigger: HTMLElement | ComponentPublicInstance | null, activation: PopupMenuAnchorActivation) => boolean;
     /** Opens the menu, or closes it when it is already open. */
-    handleActionButtonClick: (...args: unknown[]) => void;
+    handleTriggerClick: (...args: unknown[]) => void;
     /**
-     * Handles keyboard input on the action button. Enter and Space open or close
+     * Handles keyboard input on the trigger. Enter and Space open or close
      * the menu. Escape closes an open menu or moves focus to the configured target.
      */
-    handleActionButtonKeydown: (...args: unknown[]) => void;
+    handleTriggerKeydown: (...args: unknown[]) => void;
     /** Closes the menu when Escape is pressed while using the menu. */
-    handleActionMenuEscape: (event: KeyboardEvent) => void;
+    handleMenuEscape: (event: KeyboardEvent) => void;
     /**
      * Closes the menu after an item is chosen, then runs the optional action
      * provided by the consuming component.
@@ -143,3 +177,4 @@ export type UsePopupMenuReturn = {
  * @returns Template event handlers for the action trigger, Kendo Menu, and Popup.
  */
 export declare const usePopupMenu: (options: UsePopupMenuOptions) => UsePopupMenuReturn;
+export {};

package/docs/menu/usePopupMenu.md

@@ -2,6 +2,8 @@
 
 [Back to Composables README](https://github.com/NantHealth/featherk/blob/integration/packages/composables/README.md)
 
+New to coordinating row and button menus in a Kendo Grid? Start with [Grid Popup Menu Orchestration](https://github.com/NantHealth/featherk/blob/integration/packages/composables/docs/menu/usePopupMenuGridOrchestration.md).
+
 Composable for accessible Kendo UI for Vue `Popup` + `Menu` action menus. It manages trigger toggling, first-item focus, outside clicks, input-modality tracking, and focus restoration. It does not trap focus or own popup state; keep `usePopupTrap` separate when focus trapping or generic popup lifecycle behavior is needed.
 
 ## Quick Start
@@ -22,8 +24,8 @@ Composable for accessible Kendo UI for Vue `Popup` + `Menu` action menus. It man
       type="button"
       aria-haspopup="menu"
       aria-expanded="false"
-      @click="menu.handleActionButtonClick"
-      @keydown="menu.handleActionButtonKeydown"
+      @click="menu.handleTriggerClick"
+      @keydown="menu.handleTriggerKeydown"
     >
       Actions
     </button>
@@ -35,7 +37,7 @@ Composable for accessible Kendo UI for Vue `Popup` + `Menu` action menus. It man
       </strong>
       <Menu
         ref="menuRef"
-        @keydown.escape="menu.handleActionMenuEscape"
+        @keydown.escape="menu.handleMenuEscape"
         @select="onSelect"
       />
     </Popup>
@@ -80,13 +82,13 @@ const onSelect = (event: KendoMenuSelectEvent) => {
 
 ## Grid Action Cell
 
-For a virtualized Kendo Grid, use `resolveFocusTarget` to locate the current row when the popup closes by keyboard. The resolver is evaluated at focus time, after the grid and popup have settled.
+For a virtualized Kendo Grid, use `focusTargetContainerSelector` to restore keyboard focus to the trigger's current row without reaching through a registry.
 
 1. Add static `aria-haspopup="menu"` and `aria-expanded="false"` to the row's trigger button template.
 2. Read `showMenu` from the row item and keep open/close state parent-owned.
 3. Create trigger and menu refs as component refs (`ComponentPublicInstance`) for Kendo wrappers.
 4. Call `usePopupMenu(...)` with an explicit `triggerMode: "button"` and map `requestShow`/`requestHide` to row-specific emits.
-5. Provide `resolveFocusTarget` so keyboard close restores focus to the current virtualized row.
+5. Provide `focusTargetContainerSelector` so keyboard close restores focus to the current virtualized row.
 6. Route menu selection through `handleMenuSelect(event, onAction)` so row action logic can use its active state before the popup closes.
 
 ```ts
@@ -118,13 +120,8 @@ const menu = usePopupMenu({
   triggerMode: "button",
   requestShow: () => emit("update:showMenu", props.dataItem.id),
   requestHide: () => emit("update:hideMenu", props.dataItem.id),
-  // Step 5: keyboard close restores focus to current virtualized grid row
-  resolveFocusTarget: () => {
-    const trigger = triggerRef.value?.$el as HTMLElement | undefined;
-    return (
-      trigger?.closest(".k-table-row[data-grid-row-index]") ?? null
-    ) as HTMLElement | null;
-  },
+  // Step 5: keyboard close restores focus to the trigger's current row
+  focusTargetContainerSelector: ".k-table-row[data-grid-row-index]",
 });
 
 // Step 6: run row-specific business action before usePopupMenu closes
@@ -149,7 +146,9 @@ A grid row can have both a row-level context menu (`triggerMode: "row"`) and a n
 
 ```ts
 // Step 2-4: independent instances, independent triggerRef, explicit triggerMode
-const rowTriggerRef = computed(() => cellRef.value?.closest(".k-table-row") as HTMLElement | null);
+const rowTriggerRef = computed(
+  () => cellRef.value?.closest(".k-table-row") as HTMLElement | null,
+);
 
 const buttonMenu = usePopupMenu({
   isOpen: computed(() => props.dataItem.showButtonMenu),
@@ -170,7 +169,7 @@ const rowMenu = usePopupMenu({
 });
 ```
 
-See [UsePopupMenu.vue](https://github.com/NantHealth/featherk/blob/integration/demos/src/views/composables/UsePopupMenu.vue) for the full reference implementation: exactly two shared instances (one row-mode, one button-mode) for the whole grid, with per-row/button trigger registries and offset-positioned Popups instead of per-row `usePopupMenu` calls.
+For a complete shared-instance implementation, see [Shared Instance Menus](https://github.com/NantHealth/featherk/blob/integration/packages/composables/docs/menu/usePopupMenuSharedInstance.md).
 
 ## Sharing One Instance Across Many Triggers (Grid-Wide)
 
@@ -179,8 +178,8 @@ A single `usePopupMenu` instance can manage an entire list of same-mode triggers
 1. Track exactly one "active id" for the whole list, instead of a boolean per row item, via `useActiveIdRegistry<Id>()`. Only one trigger in the list can be open at a time. It exposes a read-only `activeId`, a reactive `isActive`/`activeElement` pair, and `register`/`resolve`/`activate`/`deactivate`/`isIdActive` helpers.
 2. Register each row/button element into the registry as it mounts (e.g. a `row-render` ref callback, or a component `:ref` callback) via `registry.register(id, el)`. The registry's internal element map is reactive, so `activeElement` stays correct even if a keyed/virtualized re-render swaps out the active id's underlying DOM node.
 3. Feed `isOpen: registry.isActive` and `triggerRef: registry.activeElement` straight into `usePopupMenu`, rather than deriving them from a per-row prop.
-4. Enable `anchor: true` and bind the shared `Popup` to `:offset="menu.offset"`, not `:anchor`. Kendo's `Popup.anchor` only resolves a static template-ref name once at mount; it cannot dynamically retarget a different element after the popup is already mounted. Use Kendo's `anchorAlign` and `popupAlign` props when the popup should align to a specific edge of its button. Use `anchor: { getRect: () => ... }` for cursor-positioned menus.
-5. Drive show/hide through `registry.activate(id)` / `registry.deactivate()` rather than binding `handleActionButtonClick` directly to every trigger's `@click`. A single instance's `isOpen` is one shared boolean, so `handleActionButtonClick()` cannot tell "close this trigger" apart from "open a different trigger" — calling it while another id is active will close the wrong thing.
+4. Enable `anchor: true` and bind the shared `Popup` to `:offset="menu.offset"`, not `:anchor`. Kendo's `Popup.anchor` only resolves a static template-ref name once at mount; it cannot dynamically retarget a different element after the popup is already mounted. Use `anchor.activationPoint` for pointer/keyboard context menus and `getRect(trigger)` only for custom geometry.
+5. Drive show/hide through `registry.activate(id)` / `registry.deactivate()` rather than binding `handleTriggerClick` directly to every shared trigger. A single instance's `isOpen` is one shared boolean, so the generic toggle handler cannot distinguish closing the current id from opening another id.
 
 ```ts
 // Step 1: one registry tracks the active id and resolves it to its DOM element
@@ -212,23 +211,49 @@ const toggleRowMenu = (id: number) => {
 };
 ```
 
-For a second shared instance driven by a real `@click` handler on each trigger (e.g. a per-row action button, where `handleActionButtonClick` toggle semantics would otherwise misfire on a different trigger), close the currently active trigger explicitly through the composable before switching the active id, so its `triggerRef` still resolves to the correct element at close time:
+### Cursor-Positioned Row Menus That Follow Scrolling
+
+Enable `anchor.activationPoint`, call `setAnchorActivation(row, context)` before activating the shared row id, and bind `offset` to the Popup. The composable owns trigger-relative coordinate conversion, keyboard placement, scroll reconstruction, clipping, and cleanup.
+
+```ts
+const rowMenu = usePopupMenu({
+  isOpen: rowRegistry.isActive,
+  triggerRef: rowRegistry.activeElement,
+  menuRef: rowMenuRef,
+  triggerMode: "row",
+  anchor: {
+    activationPoint: { pointerOffset: { x: -20, y: -20 } },
+  },
+  requestShow: () => {},
+  requestHide: () => rowRegistry.deactivate(),
+});
+
+const openRowMenu = (id: number, context: RowActionContext) => {
+  const row = rowRegistry.resolve(id);
+  if (!row || !rowMenu.setAnchorActivation(row, context)) return;
+  rowRegistry.activate(id);
+};
+```
+
+See [Activation-Point Anchors](https://github.com/NantHealth/featherk/blob/integration/packages/composables/docs/menu/usePopupMenuActivationAnchor.md) for the complete standalone setup and custom keyboard placement.
+
+For a second shared instance driven by a real `@click` handler on each trigger, close the currently active trigger explicitly before switching the active id, so its `triggerRef` still resolves to the correct element at close time:
 
 ```ts
 const toggleButtonMenu = (id: number) => {
   if (buttonRegistry.isIdActive(id)) {
-    buttonMenu.handleActionButtonClick(); // closes: triggerRef still matches this id
+    buttonMenu.handleTriggerClick(); // closes: triggerRef still matches this id
     return;
   }
   if (buttonRegistry.isActive.value) {
-    buttonMenu.handleActionButtonClick(); // closes the OTHER trigger correctly, before switching
+    buttonMenu.handleTriggerClick(); // closes the OTHER trigger correctly, before switching
   }
   buttonRegistry.activate(id); // the reactive watcher promotes the new trigger's aria-expanded
   nextTick(focusFirstMenuItem); // reproduce first-item focus manually; the "open" branch never ran
 };
 ```
 
-See [UsePopupMenu.vue](https://github.com/NantHealth/featherk/blob/integration/demos/src/views/composables/UsePopupMenu.vue) for the complete working version of both patterns, including the registry-building `row-render` function and composable-owned offset tracking. `useActiveIdRegistry` is now part of `@featherk/composables`, so shared-instance consumers can import it directly instead of keeping a demo-local copy.
+See [Focus and Exclusivity](https://github.com/NantHealth/featherk/blob/integration/packages/composables/docs/menu/usePopupMenuFocusAndExclusivity.md) for complete focus precedence and multi-menu coordination examples.
 
 ## API
 
@@ -236,26 +261,28 @@ See [UsePopupMenu.vue](https://github.com/NantHealth/featherk/blob/integration/d
 
 #### Options
 
-- `isOpen: Ref<boolean>`: Parent-owned popup visibility state.
+- `isOpen: Readonly<Ref<boolean>>`: Parent-owned popup visibility state observed, but never mutated, by the composable.
 - `menuRef: PopupMenuElementRef`: Ref to the Kendo `Menu` element or component.
 - `triggerRef: PopupMenuElementRef`: Ref to the action trigger element or component.
 - `requestShow(): void`: Opens the parent-owned popup state.
 - `requestHide(): void`: Closes the parent-owned popup state.
 - `focusTargetRef?: PopupMenuElementRef`: Optional element/component to focus after a keyboard-driven close.
 - `resolveFocusTarget?: () => HTMLElement | null`: Dynamic focus-target resolver. It takes precedence over `focusTargetRef` and is useful for virtualized grid rows.
+- `focusTargetContainerSelector?: string`: Closest trigger ancestor to focus after any keyboard-driven close. Used after `resolveFocusTarget` and `focusTargetRef`.
 - `menuItemSelector?: string`: Selector for the first enabled item. Defaults to `.k-menu-item:not(.k-disabled)`.
 - `manageMenuTriggerAria?: boolean`: Keeps `aria-expanded` in sync with `isOpen` on the resolved `triggerRef` element. Defaults to `true`. The consumer always owns the static `aria-haspopup="menu"` attribute and the baseline `aria-expanded="false"`; the composable only ever writes `aria-expanded` and never removes it. Set to `false` to own `aria-expanded` yourself too.
 - `menuLabel?: MaybeRefOrGetter<string | null | undefined>`: Optional accessible name applied as `aria-label` to the rendered `ul[role="menubar"]`. Empty labels remove the managed attribute.
 - `triggerMode: "button" | "row"`: Required. Declares the trigger semantics so a misrouted `triggerRef` (e.g. one that unexpectedly resolves to a `tr.k-table-row` while `triggerMode: "button"` is set) is never silently managed; a mismatch logs a `console.warn` and skips ARIA management for that resolution. Use `"row"` only when a `tr.k-table-row` owns the menu trigger. Neither mode adds `role`, `tabindex`, or keyboard behavior.
-- `anchor?: true | PopupMenuAnchorOptions`: Enables document-relative `offset` tracking for dynamically retargeted Popups. `true` uses the resolved trigger's rectangle and nearest scrollable ancestor. `PopupMenuAnchorOptions` accepts `clipRoot`, `hideWhenAnchorClipped`, `intersectionThreshold`, and `getRect` for pointer-positioned menus. The threshold defaults to `0.5`; use `intersectionThreshold: 0` when any partially visible trigger should remain open. A fully clipped trigger closes with `"anchor-hidden"` without restoring focus.
+- `anchor?: true | PopupMenuAnchorOptions`: Enables document-relative offset tracking. `true` follows the trigger's bottom-left corner. `activationPoint` captures pointer/keyboard positions relative to the trigger and defaults its clipping threshold to `0`; `getRect(trigger)` remains the mutually exclusive custom-geometry escape hatch. Without `clipRoot`, the composable prefers the nearest overflow-enabled ancestor that can actually scroll, skipping styled wrappers with no overflow. Other anchors default to threshold `0.5`. A fully clipped trigger closes with `"anchor-hidden"` without restoring focus.
 
 `PopupMenuElementRef` accepts a normal `HTMLElement` ref or a Vue/Kendo component ref that exposes `$el`.
 
 #### Returns
 
-- `handleActionButtonClick()`: Toggles the menu and focuses the first enabled item after opening.
-- `handleActionButtonKeydown(event)`: `Enter` and `Space` toggle; `Escape` closes, or focuses the configured target when already closed.
-- `handleActionMenuEscape(event)`: Closes an open menu with keyboard modality.
+- `setAnchorActivation(trigger, activation)`: Captures a pointer or keyboard activation for `anchor.activationPoint`; returns `false` when activation anchoring or a trigger is unavailable.
+- `handleTriggerClick()`: Toggles the menu and focuses the first enabled item after opening.
+- `handleTriggerKeydown(event)`: `Enter` and `Space` toggle; `Escape` closes, or focuses the configured target when already closed.
+- `handleMenuEscape(event)`: Closes an open menu with keyboard modality.
 - `handleMenuSelect(event, onAction?)`: Records the selection modality, requests close, then invokes optional business logic.
 - `handlePopupClose()`: Restores focus after Kendo Popup has closed.
 - `offset`: A computed `{ left, top }` value for Kendo Popup's `:offset`; it is `{ left: 0, top: 0 }` while closed.

package/docs/menu/usePopupMenuActivationAnchor.md

@@ -0,0 +1,132 @@
+# usePopupMenu Activation-Point Anchors
+
+[Back to usePopupMenu](https://github.com/NantHealth/featherk/blob/integration/packages/composables/docs/menu/usePopupMenu.md)
+
+Use an activation-point anchor when a context menu must open near a pointer or at a predictable keyboard position and continue following its trigger during scrolling.
+
+## Quick Start
+
+1. Register each trigger element by id.
+2. Enable `anchor.activationPoint` and bind `menu.offset` to the Popup.
+3. Capture the activation against the trigger before activating its id.
+4. Keep visibility parent-owned through the registry.
+
+```vue
+<template>
+  <table>
+    <tbody>
+      <tr
+        v-for="row in rows"
+        :key="row.id"
+        :ref="(element) => registerRow(row.id, element)"
+        class="k-table-row"
+        tabindex="0"
+        aria-haspopup="menu"
+        aria-expanded="false"
+        @click="openFromPointer(row.id, $event)"
+        @keydown.enter.prevent="openFromKeyboard(row.id)"
+        @keydown.space.prevent="openFromKeyboard(row.id)"
+      >
+        <td>{{ row.name }}</td>
+      </tr>
+    </tbody>
+  </table>
+
+  <Popup
+    :show="rowRegistry.isActive.value"
+    :offset="menu.offset.value"
+    @close="menu.handlePopupClose"
+  >
+    <Menu
+      ref="menuRef"
+      :items="items"
+      :vertical="true"
+      @keydown.escape="menu.handleMenuEscape"
+      @select="menu.handleMenuSelect"
+    />
+  </Popup>
+</template>
+
+<script setup lang="ts">
+import { ref, type ComponentPublicInstance } from "vue";
+import { Popup } from "@progress/kendo-vue-popup";
+import { Menu } from "@progress/kendo-vue-layout";
+import { usePopupMenu } from "@featherk/composables/menu";
+import { useActiveIdRegistry } from "@featherk/composables/registry";
+
+const rows = [
+  { id: 1, name: "Alpha" },
+  { id: 2, name: "Beta" },
+];
+const items = [{ text: "Open" }, { text: "Archive" }];
+const rowRegistry = useActiveIdRegistry<number>();
+const menuRef = ref<ComponentPublicInstance | null>(null);
+
+// Step 2: pointer coordinates receive 12px of visual clearance. Keyboard
+// activation defaults to x=8 and the trigger's vertical center.
+const menu = usePopupMenu({
+  isOpen: rowRegistry.isActive,
+  triggerRef: rowRegistry.activeElement,
+  menuRef,
+  triggerMode: "row",
+  anchor: {
+    activationPoint: { pointerOffset: { x: -12, y: -12 } },
+  },
+  requestShow: () => {},
+  requestHide: () => rowRegistry.deactivate(),
+});
+
+// Step 1: the registry resolves an id to the current DOM element, including
+// after keyed or virtualized rendering replaces it.
+const registerRow = (id: number, element: unknown) => {
+  rowRegistry.register(id, element as HTMLElement | null);
+};
+
+const activate = (
+  id: number,
+  activation: Parameters<typeof menu.setAnchorActivation>[1],
+) => {
+  const row = rowRegistry.resolve(id);
+  // Step 3: capture before activation because triggerRef is still null or may
+  // still resolve to the previously active row.
+  if (!row || !menu.setAnchorActivation(row, activation)) return;
+
+  // Step 4: the registry remains the owner of open state.
+  rowRegistry.activate(id);
+};
+
+const openFromPointer = (id: number, event: MouseEvent) => {
+  activate(id, {
+    triggerType: "click",
+    coordinates: { clientX: event.clientX, clientY: event.clientY },
+  });
+};
+
+const openFromKeyboard = (id: number) => {
+  activate(id, { triggerType: "keyboard" });
+};
+</script>
+```
+
+## Keyboard Position
+
+The default keyboard point is 8px inside the trigger's left edge and vertically centered. Override it when needed:
+
+```ts
+anchor: {
+  activationPoint: {
+    keyboardPosition: { x: 12, y: "bottom" },
+  },
+}
+```
+
+`y` accepts a number or `"top"`, `"center"`, or `"bottom"`.
+
+## Behavior
+
+- Pointer coordinates are converted to a trigger-relative point once.
+- Scroll and resize measurements reconstruct that point from the trigger's current rectangle.
+- The clipping threshold defaults to `0`; the menu stays open while any part of the trigger remains visible.
+- A fully clipped trigger closes with `"anchor-hidden"` without restoring focus.
+- Activation metadata is cleared whenever `isOpen` becomes false.
+- Use custom `getRect(trigger)` instead when positioning does not originate from a pointer or keyboard activation.

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.