@featherk/composables 0.12.4 → 0.13.0

package/docs/menu/usePopupMenuGridOrchestration.md

@@ -0,0 +1,480 @@
+# 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
+    :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
+    :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.
+
+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).

package/docs/menu/usePopupMenuSharedInstance.md

@@ -0,0 +1,106 @@
+# usePopupMenu Shared Instances
+
+[Back to usePopupMenu](https://github.com/NantHealth/featherk/blob/integration/packages/composables/docs/menu/usePopupMenu.md)
+
+Use one `usePopupMenu` instance for many equivalent triggers when only one item may own the menu at a time.
+
+## Quick Start
+
+1. Register every trigger with `useActiveIdRegistry`.
+2. Pass `registry.isActive` and `registry.activeElement` to `usePopupMenu`.
+3. Activate or deactivate ids in a consumer-owned toggle function.
+4. Render one Popup and bind its `show`, `offset`, and close handler.
+
+```vue
+<template>
+  <ul>
+    <li v-for="record in records" :key="record.id">
+      <button
+        :ref="(element) => registerTrigger(record.id, element)"
+        type="button"
+        aria-haspopup="menu"
+        aria-expanded="false"
+        @click="toggleMenu(record.id)"
+      >
+        Actions for {{ record.name }}
+      </button>
+    </li>
+  </ul>
+
+  <Popup
+    :show="registry.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 records = [
+  { id: 1, name: "Alpha" },
+  { id: 2, name: "Beta" },
+];
+const items = [{ text: "Open" }, { text: "Archive" }];
+const registry = useActiveIdRegistry<number>();
+const menuRef = ref<ComponentPublicInstance | null>(null);
+
+// Step 2: one reactive pair follows whichever trigger id is active.
+const menu = usePopupMenu({
+  isOpen: registry.isActive,
+  triggerRef: registry.activeElement,
+  menuRef,
+  triggerMode: "button",
+  anchor: true,
+  requestShow: () => {},
+  requestHide: () => registry.deactivate(),
+});
+
+// Step 1: registration remains stable across keyed rerenders.
+const registerTrigger = (id: number, element: unknown) => {
+  registry.register(
+    id,
+    element as HTMLElement | ComponentPublicInstance | null,
+  );
+};
+
+// Step 3: shared state must distinguish closing the active id from switching ids.
+const toggleMenu = (id: number) => {
+  if (registry.isIdActive(id)) {
+    menu.handleTriggerClick();
+    return;
+  }
+
+  if (registry.isActive.value) {
+    menu.handleTriggerClick();
+  }
+  registry.activate(id);
+};
+</script>
+```
+
+## Why Offset Positioning
+
+Bind the returned `offset` instead of Kendo Popup's `anchor` prop for a shared instance. Kendo resolves an anchor ref name when the Popup mounts; it does not dynamically retarget a different trigger element. `usePopupMenu` remeasures the active registered element on scroll, resize, and trigger replacement.
+
+## Trigger Switching
+
+When an active id changes, `usePopupMenu` demotes the previous element to `aria-expanded="false"` and promotes the new trigger. Each trigger must provide the static baseline:
+
+```html
+aria-haspopup="menu" aria-expanded="false"
+```
+
+The composable does not add `aria-haspopup`, roles, or keyboard focusability.

package/docs/menu/usePopupMenuUpgrade0130.md

@@ -0,0 +1,115 @@
+# Upgrading usePopupMenu to 0.13.0
+
+[Back to usePopupMenu](https://github.com/NantHealth/featherk/blob/integration/packages/composables/docs/menu/usePopupMenu.md)
+
+This guide covers migration from `@featherk/composables` 0.12.x to 0.13.0.
+
+## Required Changes
+
+Version 0.13.0 renames three returned handlers so their names apply equally to button and row triggers.
+
+| 0.12.x                      | 0.13.0                 |
+| --------------------------- | ---------------------- |
+| `handleActionButtonClick`   | `handleTriggerClick`   |
+| `handleActionButtonKeydown` | `handleTriggerKeydown` |
+| `handleActionMenuEscape`    | `handleMenuEscape`     |
+
+Before:
+
+```vue
+<button
+  @click="menu.handleActionButtonClick"
+  @keydown="menu.handleActionButtonKeydown"
+/>
+<Menu @keydown.escape="menu.handleActionMenuEscape" />
+```
+
+After:
+
+```vue
+<button @click="menu.handleTriggerClick" @keydown="menu.handleTriggerKeydown" />
+<Menu @keydown.escape="menu.handleMenuEscape" />
+```
+
+Search all consumer source for:
+
+```text
+handleActionButtonClick
+handleActionButtonKeydown
+handleActionMenuEscape
+```
+
+The old properties are removed rather than retained as aliases.
+
+## Optional: Replace Manual Activation Geometry
+
+Custom `getRect(trigger)` remains supported. Consumers that manually store pointer coordinates relative to a trigger can remove that state and use activation-point anchoring.
+
+Before:
+
+```ts
+const point = ref<{ x: number; y: number } | null>(null);
+
+const menu = usePopupMenu({
+  // Other required options omitted.
+  anchor: {
+    intersectionThreshold: 0,
+    getRect: (trigger) => {
+      const rect = trigger.getBoundingClientRect();
+      return point.value
+        ? new DOMRect(rect.left + point.value.x, rect.top + point.value.y, 0, 0)
+        : null;
+    },
+  },
+});
+```
+
+After:
+
+```ts
+const menu = usePopupMenu({
+  // Other required options omitted.
+  anchor: {
+    activationPoint: { pointerOffset: { x: -12, y: -12 } },
+  },
+});
+
+const trigger = registry.resolve(id);
+if (trigger && menu.setAnchorActivation(trigger, context)) {
+  registry.activate(id);
+}
+```
+
+Capture before activating a shared registry id. Pointer coordinates become trigger-relative automatically; keyboard activation defaults to 8px from the left and vertically centered. Internal activation state clears when the menu closes.
+
+## Optional: Simplify Focus Restoration
+
+Before:
+
+```ts
+resolveFocusTarget: () =>
+  registry.activeElement.value?.closest(".k-table-row") ?? null,
+```
+
+After:
+
+```ts
+focusTargetContainerSelector: ".k-table-row",
+```
+
+Keep `resolveFocusTarget` when the target cannot be expressed as the trigger's closest matching ancestor. Its precedence remains higher than `focusTargetRef` and `focusTargetContainerSelector`.
+
+## Unchanged Contracts
+
+- The consumer owns `isOpen`, `requestShow`, and `requestHide`.
+- The consumer provides static `aria-haspopup="menu"` and baseline `aria-expanded="false"`.
+- `usePopupMenu` updates only `aria-expanded` unless ARIA management is disabled.
+- `anchor: true` continues to follow the trigger's bottom-left corner.
+- Custom `getRect(trigger)` remains supported and is source-compatible with zero-argument callbacks.
+- Intersection dismissal and the `"anchor-hidden"` close reason are unchanged.
+- `useActiveIdRegistry`, `useExclusiveGroup`, and `useGridRowAction` remain independent composables.
+- Package root and `@featherk/composables/menu` imports remain supported.
+
+## Custom Geometry Fallback
+
+Activation-point anchoring is optional. Retain `getRect(trigger)` when the popup must follow geometry that is not derived from a pointer or keyboard activation, such as a selection rectangle or a domain-specific virtual anchor.