@featherk/composables 0.12.5 → 0.13.1

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.

package/docs/trap/usePopupTrap.md

@@ -101,7 +101,7 @@ export type InitialFocus = string | ((root: HTMLElement) => HTMLElement | null |
   - `.k-popup`
   - `.k-timepicker-popup`
   - `.k-menu-popup`
-- **Focus trap**: Uses `useFocusTrap(popupRef)` with a fallback/initial focus inside the popup. `escapeDeactivates` and `clickOutsideDeactivates` are disabled; closing is managed explicitly.
+- **Focus trap**: Uses `useFocusTrap(popupRef)` with a fallback/initial focus inside the popup. `escapeDeactivates` and `clickOutsideDeactivates` are disabled; closing is managed explicitly. `allowOutsideClick` defaults to `true` - without it, `focus-trap`'s own default (`false`) `preventDefault()`s and swallows *every* outside pointerdown/click while the trap is active, not just ones that would close it, blocking interaction with anything else on the page (e.g. a second trigger in the same grid row) until the trap deactivates. Override via `focusTrapOptions` only if a specific popup genuinely needs that stricter modal-style behavior.
 - **Escape to close**: Adds a `keydown` listener on the popup when opened; pressing Escape calls `onRequestClose('escape', event)` and stops propagation.
 - **Outside click to close**: Uses `onClickOutside(popupRef, ...)` to call `onRequestClose('outside', event)` when open.
 - **Open/close lifecycle**: When `isOpen` becomes true, discovers the popup, sets `popupRef`, and activates the focus trap. When it becomes false, deactivates, removes listeners, clears `popupRef`, and optionally returns focus to `triggerEl`.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@featherk/composables",
-  "version": "0.12.5",
+  "version": "0.13.1",
   "main": "dist/featherk-composables.umd.js",
   "module": "dist/featherk-composables.es.js",
   "types": "dist/index.d.ts",
@@ -45,6 +45,11 @@
       "import": "./dist/featherk-composables.es.js",
       "require": "./dist/featherk-composables.umd.js"
     },
+    "./geometry": {
+      "types": "./dist/geometry/index.d.ts",
+      "import": "./dist/featherk-composables.es.js",
+      "require": "./dist/featherk-composables.umd.js"
+    },
     "./registry": {
       "types": "./dist/registry/index.d.ts",
       "import": "./dist/featherk-composables.es.js",