@featherk/composables 0.13.1 → 0.13.2

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

@@ -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,
 });
 ```
 

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

@@ -493,21 +493,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.2",
   "main": "dist/featherk-composables.umd.js",
   "module": "dist/featherk-composables.es.js",
   "types": "dist/index.d.ts",