@featherk/composables 0.13.1 → 0.13.3

package/dist/index.d.ts

@@ -12,4 +12,4 @@ export { useMaskedDateRangeInput } from "./range";
 export type { RangeChangePayload } from "./range";
 export { useMaskedTimeInput } from "./time";
 export type { ChangePayload as TimeChangePayload } from "./time";
-export { usePopupTrap } from "./trap";
+export { POPUP_MENU_TRAP_OPTIONS, usePopupTrap } from "./trap";

package/dist/trap/usePopupTrap.d.ts

@@ -2,6 +2,20 @@ import { type Ref } from "vue";
 import { useFocusTrap } from "@vueuse/integrations/useFocusTrap";
 export type CloseReason = "escape" | "outside";
 export type InitialFocus = string | ((root: HTMLElement) => HTMLElement | null | undefined);
+/**
+ * Focus-restoration options for pairing `usePopupTrap` with `usePopupMenu`.
+ *
+ * `usePopupMenu` owns menu-close focus restoration. These settings disable
+ * both competing restoration paths in `usePopupTrap` and the underlying
+ * `focus-trap` implementation. Spread this preset last so those integration
+ * settings take precedence.
+ */
+export declare const POPUP_MENU_TRAP_OPTIONS: {
+    readonly returnFocusToTrigger: false;
+    readonly focusTrapOptions: {
+        readonly returnFocusOnDeactivate: false;
+    };
+};
 export declare function usePopupTrap(opts: {
     isOpen: Ref<boolean>;
     onRequestClose?: (reason: CloseReason, ev?: Event) => void;

package/docs/menu/usePopupMenu.md

@@ -11,7 +11,7 @@ Composable for accessible Kendo UI for Vue `Popup` + `Menu` action menus. It man
 1. Add static `aria-haspopup="menu"` and baseline `aria-expanded="false"` to the trigger element in your template. The composable never sets `aria-haspopup` and never removes `aria-expanded`; the consumer owns both as the closed-state baseline.
 2. Create parent-owned refs for `isOpen`, `triggerRef`, `menuRef`, and an optional keyboard focus target.
 3. Call `usePopupMenu(...)` with `requestShow`, `requestHide`, and an explicit `triggerMode: "button"` (or `"row"`).
-4. Route Kendo Menu `@select` through `handleMenuSelect(event, onAction)` so your business action runs while the active menu context is still available, before the composable closes the popup.
+4. Route Kendo Menu `@select` through `handleMenuSelect(event, onAction)` so the composable closes the popup before running your business action synchronously.
 5. Bind trigger button `@click` and `@keydown` to the composable handlers.
 6. Bind Popup `@close` and Menu `@keydown.escape` so keyboard and mouse close paths restore focus correctly.
 
@@ -70,7 +70,7 @@ const menu = usePopupMenu({
   requestHide: () => (isOpen.value = false),
 });
 
-// Step 4: act while the active context is available; usePopupMenu closes afterward
+// Step 4: usePopupMenu closes before running the business action synchronously
 const onSelect = (event: KendoMenuSelectEvent) => {
   menu.handleMenuSelect(event, (selected) => {
     // Keep application-specific actions in the consuming component.
@@ -89,7 +89,7 @@ For a virtualized Kendo Grid, use `focusTargetContainerSelector` to restore keyb
 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 `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.
+6. Route menu selection through `handleMenuSelect(event, onAction)` so the popup closes before row action logic runs synchronously.
 
 ```ts
 <script setup lang="ts">
@@ -124,7 +124,7 @@ const menu = usePopupMenu({
   focusTargetContainerSelector: ".k-table-row[data-grid-row-index]",
 });
 
-// Step 6: run row-specific business action before usePopupMenu closes
+// Step 6: usePopupMenu closes before running the row-specific business action
 const onSelect = (event: KendoMenuSelectEvent) => {
   menu.handleMenuSelect(event, (selected) => {
     // Row-specific action logic remains here.
@@ -277,14 +277,33 @@ See [Focus and Exclusivity](https://github.com/NantHealth/featherk/blob/integrat
 `usePopupTrap` already defaults `allowOutsideClick` to `true` internally - no consumer action needed for that one, but see [usePopupTrap](https://github.com/NantHealth/featherk/blob/integration/packages/composables/docs/trap/usePopupTrap.md) for why it matters: without it, a genuinely active trap swallows every outside click (e.g. a second trigger in the same grid row), not just ones that would close it.
 
 ```ts
+import {
+  POPUP_MENU_TRAP_OPTIONS,
+  usePopupTrap,
+} from "@featherk/composables/trap";
+
 usePopupTrap({
   isOpen: registry.isActive,
   triggerEl: registry.activeElement,
   // Step 6: only required when this popup coexists with another in the template.
   resolvePopupEl: () => document.getElementById("my-shared-popup"),
   initialFocus: () => document.activeElement as HTMLElement | null,
-  returnFocusToTrigger: false,
-  focusTrapOptions: { returnFocusOnDeactivate: false },
+  ...POPUP_MENU_TRAP_OPTIONS,
+});
+```
+
+`POPUP_MENU_TRAP_OPTIONS` is an optional convenience preset for this pairing.
+It disables the trap's competing focus restoration paths so `usePopupMenu`
+remains the sole owner of focus restoration. `initialFocus` stays explicit
+because it should preserve the focus behavior chosen by each menu. Spread the
+preset last in the options object so these required integration settings win
+over conflicting trap options:
+
+```ts
+usePopupTrap({
+  isOpen,
+  initialFocus: () => document.activeElement as HTMLElement | null,
+  ...POPUP_MENU_TRAP_OPTIONS,
 });
 ```
 
@@ -398,7 +417,7 @@ Whenever `anchor` is configured, `usePopupMenu` automatically flips the popup to
 - Trigger replacement and virtualization are handled by re-resolving the ref. The previous trigger is demoted to `aria-expanded="false"`, not stripped of attributes, so a shared instance can move between many rows (e.g. a grid) without losing each row's `aria-haspopup` baseline. Set `manageMenuTriggerAria` to `false` when the consumer owns `aria-expanded` too.
 - Opening focuses the first enabled Kendo Menu item after Vue renders it.
 - Outside clicks close the menu, while the trigger is ignored to prevent a close/reopen race.
-- Menu selection runs the optional business callback while the active state is still available, then records modality and closes the popup.
+- Menu selection records modality and requests close before running the optional business callback synchronously. Registry-backed consumers must snapshot business context before calling `handleMenuSelect`; `useActionCellMenu` does this internally.
 - `Escape` on the trigger or inside the menu uses the keyboard close path.
 - Keyboard-driven closes focus `resolveFocusTarget()` or `focusTargetRef`, then fall back to the trigger.
 - Mouse selection closes restore focus to the trigger.

package/docs/menu/usePopupMenuAndActiveIdRegistry.md

@@ -0,0 +1,185 @@
+# Shared Popup Menu Lifecycle with `useActiveIdRegistry`
+
+[Back to usePopupMenu](https://github.com/NantHealth/featherk/blob/integration/packages/composables/docs/menu/usePopupMenu.md)
+
+## The Story
+
+Imagine a grid with 500 rows, but only one popup menu instance mounted for the entire grid.
+
+When the user activates row `42`, the application needs to answer three questions:
+
+1. Which ID is active?
+2. Which DOM element belongs to that ID?
+3. Which shared popup should display the corresponding content?
+
+`useActiveIdRegistry` answers all three. It is the bridge between repeated grid items and a shared popup menu.
+
+## Registering Each Trigger
+
+As rows render, the consumer connects each stable row ID to its DOM element:
+
+```ts
+rowRegistry.register(props.dataItem.id, rowElement);
+```
+
+In a render callback, this commonly looks like:
+
+```ts
+ref: (el: HTMLElement | null) =>
+  rowRegistry.register(props.dataItem.id, el),
+```
+
+The registry does not discover row elements automatically. Registration is what makes `activeElement` useful.
+
+When a row is unmounted or virtualized away, the ref callback receives `null`, and the registry removes that ID.
+
+## Activating the Shared Popup
+
+When the user activates a row, the consumer first checks whether that same row is already active:
+
+```ts
+if (rowRegistry.isIdActive(id)) {
+  hideRowMenu();
+  return;
+}
+```
+
+For a new row, the consumer resolves the element, captures any positioning information, and activates the ID:
+
+```ts
+const row = rowRegistry.resolve(id);
+if (!row) return;
+
+if (!rowMenu.setAnchorActivation(row, context)) return;
+
+rowRegistry.activate(id);
+```
+
+The important ordering is:
+
+1. Resolve the element.
+2. Validate or capture activation geometry.
+3. Activate the ID.
+
+That prevents the shared popup from becoming open for an ID whose DOM element is unavailable.
+
+## Connecting the Registry to `usePopupMenu`
+
+The shared `usePopupMenu` instance consumes derived registry state:
+
+```ts
+const rowMenu = usePopupMenu({
+  isOpen: rowRegistry.isActive,
+  triggerRef: rowRegistry.activeElement,
+  menuRef: rowMenuRef,
+  triggerMode: "row",
+  requestHide: () => hideRowMenu(),
+});
+```
+
+The registry supplies the shared menu's current context:
+
+- `activeId` selects the current data item.
+- `activeElement` supplies the current trigger.
+- `isActive` controls popup visibility.
+- Computed menu items and labels derive from `activeId`.
+
+This is the central pattern used by the local shared-popup demos.
+
+## Deactivation Is the Other Half
+
+Every close path must eventually clear the registry:
+
+```ts
+const hideRowMenu = () => {
+  rowRegistry.deactivate();
+  nextTick(updateRowDomStates);
+};
+```
+
+That includes:
+
+- clicking the active trigger again
+- selecting a menu item
+- pressing Escape
+- clicking outside
+- the active row leaving the clipping area
+- switching from a row menu to a button menu
+- replacing the active ID with another ID
+
+If deactivation is missed, the popup can remain logically open after the visual UI disappears. A stale `activeId` can also cause the wrong row to be treated as active, `activeElement` to point at an old element, focus restoration to target a stale trigger, or the next popup open to reuse stale menu data.
+
+## One Registry per Popup Family
+
+The shared popup demo uses separate registries for row and button menus:
+
+```ts
+const rowRegistry = useActiveIdRegistry<number>();
+const buttonRegistry = useActiveIdRegistry<number>();
+```
+
+This is intentional. The two menu families have different trigger types, positioning rules, content, and focus semantics.
+
+When opening a row menu, close the button menu first:
+
+```ts
+hideButtonMenu();
+rowRegistry.activate(id);
+```
+
+When opening a button menu, close the row menu first:
+
+```ts
+hideRowMenu();
+buttonMenu.handleTriggerClick(id);
+```
+
+The rule is:
+
+> One registry represents one mutually exclusive active-popup family.
+
+Do not use one registry merely because two menus happen to appear on the same screen.
+
+## When Menu Families Compete
+
+Keep the registry lifecycle and popup lifecycle separate. Use
+`useExclusiveGroup` when independent menu families must never be open at the
+same time, and deactivate competing registries before activating the next
+one.
+
+For the complete exclusivity pattern and focus behavior, see [Focus and
+Exclusivity](https://github.com/NantHealth/featherk/blob/integration/packages/composables/docs/menu/usePopupMenuFocusAndExclusivity.md).
+
+## Composite IDs for ActionCell
+
+ActionCell has multiple triggers per row, so a row number alone is not enough. The consumer creates a deterministic composite ID:
+
+```ts
+const getActionTriggerId = (
+  trigger: ActionCellTrigger<Patient>,
+  patient: Patient,
+) => `${trigger.key}:${patient.id}`;
+```
+
+An active ID such as `patient:42` identifies both the trigger type and the data item. The consumer can derive the active trigger, patient, title, and menu items from that one ID.
+
+This lets one registry control all ActionCell trigger types while still identifying the exact active trigger.
+
+## Consumer Checklist
+
+For a shared popup backed by `useActiveIdRegistry`:
+
+1. Create one registry per popup family.
+2. Register each rendered trigger with a stable ID.
+3. Unregister through the ref callback when the element disappears.
+4. Pass `registry.isActive` as `usePopupMenu.isOpen`.
+5. Pass `registry.activeElement` as `triggerRef`.
+6. Derive labels and menu items from `registry.activeId`.
+7. Activate only after resolving and validating the trigger element.
+8. Deactivate on every close path.
+9. Close other registries before activating a competing menu.
+10. Use `useExclusiveGroup` when independent registry families must be mutually exclusive.
+
+The shortest mental model is:
+
+> Registration answers “where is this ID?” Activation answers “which ID owns the popup?” Deactivation answers “does the popup still have an owner?”

package/docs/menu/usePopupMenuGridOrchestration.md

@@ -340,17 +340,19 @@ const handleGridKeydown = (event: KeyboardEvent) => {
 };
 
 const handleRowMenuSelect = (event: KendoMenuSelectEvent) => {
+  const record = activeRowRecord.value;
   rowMenu.handleMenuSelect(event, (selection) => {
-    if (selection.item && activeRowRecord.value) {
-      console.log(selection.item.id, activeRowRecord.value);
+    if (selection.item && record) {
+      console.log(selection.item.id, record);
     }
   });
 };
 
 const handleButtonMenuSelect = (event: KendoMenuSelectEvent) => {
+  const record = activeButtonRecord.value;
   buttonMenu.handleMenuSelect(event, (selection) => {
-    if (selection.item && activeButtonRecord.value) {
-      console.log(selection.item.id, activeButtonRecord.value);
+    if (selection.item && record) {
+      console.log(selection.item.id, record);
     }
   });
 };
@@ -493,21 +495,24 @@ class-based lookup can't reliably tell them apart - pin each trap to its own
 Popup by the `id` it already has:
 
 ```ts
+import {
+  POPUP_MENU_TRAP_OPTIONS,
+  usePopupTrap,
+} from "@featherk/composables/trap";
+
 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 },
+  ...POPUP_MENU_TRAP_OPTIONS,
 });
 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 },
+  ...POPUP_MENU_TRAP_OPTIONS,
 });
 ```
 

package/docs/trap/usePopupTrap.md

@@ -36,6 +36,30 @@ usePopupTrap({
 </template>
 ```
 
+When pairing this composable with `usePopupMenu`, the optional
+`POPUP_MENU_TRAP_OPTIONS` export disables the trap's competing focus
+restoration paths:
+
+```ts
+import {
+  POPUP_MENU_TRAP_OPTIONS,
+  usePopupTrap,
+} from "@featherk/composables/trap";
+
+usePopupTrap({
+  isOpen,
+  triggerEl,
+  initialFocus: () => document.activeElement as HTMLElement | null,
+  ...POPUP_MENU_TRAP_OPTIONS,
+});
+```
+
+Keep `initialFocus` explicit because the correct focus target is specific to
+the popup and its owning composable. `allowOutsideClick` is already `true` by
+default and is not repeated in this preset. Spread this preset last when using
+it with `usePopupMenu`; its focus-restoration settings are required for that
+integration and should take precedence over conflicting options.
+
 ### TimePicker example (custom selectors)
 
 ```ts

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@featherk/composables",
-  "version": "0.13.1",
+  "version": "0.13.3",
   "main": "dist/featherk-composables.umd.js",
   "module": "dist/featherk-composables.es.js",
   "types": "dist/index.d.ts",