@featherk/composables 0.11.1 → 0.12.0

package/dist/id/index.d.ts

@@ -0,0 +1,2 @@
+export { useCompositeId } from "./useCompositeId";
+export type { CompositeIdPart, UseCompositeIdReturn } from "./useCompositeId";

package/dist/id/useCompositeId.d.ts

@@ -0,0 +1,17 @@
+/** A stable segment used to compose a component-scoped DOM identifier. */
+export type CompositeIdPart = string | number | null | undefined;
+/** Values returned by {@link useCompositeId}. */
+export type UseCompositeIdReturn = {
+    /** Unique Vue component-instance identifier, prefixed for FeatherK markup. */
+    instanceId: string;
+    /** Combines the component instance ID with stable logical identifier segments. */
+    compose: (...parts: CompositeIdPart[]) => string;
+};
+/**
+ * Creates component-scoped DOM identifiers from Vue's SSR-safe `useId()`.
+ *
+ * Use the resulting `instanceId` for a stable local base and `compose` for
+ * related trigger, menu, popup, and ARIA relationship IDs. This does not
+ * replace consumer-owned domain IDs used for shared state or registries.
+ */
+export declare const useCompositeId: (prefix?: string) => UseCompositeIdReturn;

package/dist/id/useCompositeId.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/index.d.ts

@@ -1,7 +1,10 @@
 export * from "./grid";
 export * from "./address";
 export * from "./form";
+export * from "./id";
 export * from "./menu";
+export * from "./observer";
+export * from "./registry";
 export { useMaskedDateInput } from "./date";
 export type { ChangePayload as DateChangePayload } from "./date";
 export { useMaskedDateRangeInput } from "./range";

package/dist/menu/usePopupMenu.d.ts

@@ -1,9 +1,36 @@
-import { type ComponentPublicInstance, type Ref } from "vue";
+import { type ComponentPublicInstance, type ComputedRef, type MaybeRefOrGetter, type Ref } from "vue";
 /** A template ref that may point to an element or a Vue/Kendo component. */
 export type PopupMenuElementRef = Ref<HTMLElement | ComponentPublicInstance | null>;
 export type PopupMenuTriggerMode = "button" | "row";
+export type PopupMenuOffset = {
+    left: number;
+    top: number;
+};
+/** Offset-positioning options for a Popup with a dynamically changing trigger. */
+export type PopupMenuAnchorOptions = {
+    /** 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;
+    /** Overrides the trigger rect for pointer-positioned menus. */
+    getRect?: () => DOMRect | null;
+};
 /** Why the popup was closed, including the focus policy for mouse paths. */
-export type PopupMenuCloseReason = "keyboard" | "mouse-selection" | "outside-click" | "trigger-click" | null;
+export type PopupMenuCloseReason = 
+/** Keyboard-driven menu selection (Enter/Space on a menu item); restores the configured focus target. */
+"keyboard"
+/** Escape key; restores the configured focus target, then `escapeFocusTarget`, then the trigger. */
+ | "escape"
+/** Pointer menu selection; restores focus to the trigger. */
+ | "mouse-selection"
+/** Pointer interaction outside the menu; leaves browser focus unchanged. */
+ | "outside-click"
+/** Interaction with the open trigger; leaves browser focus unchanged. */
+ | "trigger-click"
+/** Trigger left its clipping area; closes without scrolling it back into view. */
+ | "anchor-hidden"
+/** No close has been requested yet. */
+ | null;
 export type PopupMenuCloseTrigger = Exclude<PopupMenuCloseReason, null>;
 /** Minimal event shape emitted by Kendo Menu `@select`. */
 export type KendoMenuSelectEvent = {
@@ -22,10 +49,10 @@ export type UsePopupMenuOptions = {
     menuRef: PopupMenuElementRef;
     /** Ref to the trigger button element or component. Ignored by outside-click detection. */
     triggerRef: PopupMenuElementRef;
-    /** Called to open the popup menu. */
-    requestShow: () => void;
-    /** Called to close the popup menu. */
-    requestHide: () => void;
+    /** Called to open the popup menu. Kendo passes its event args as a rest tuple. */
+    requestShow: (...args: unknown[]) => void;
+    /** Called to close the popup menu. Kendo passes its event args as a rest tuple. */
+    requestHide: (...args: unknown[]) => void;
     /**
      * Optional target to focus after a keyboard-driven close.
      * Supports ordinary elements and Vue/Kendo components exposing `$el`.
@@ -36,25 +63,53 @@ export type UsePopupMenuOptions = {
      * Takes precedence over `focusTargetRef`.
      */
     resolveFocusTarget?: () => HTMLElement | null;
+    /**
+     * Resolves a fallback focus target for Escape closes when no `focusTargetRef`/
+     * `resolveFocusTarget` is configured, e.g. the trigger's containing grid row so
+     * keyboard users land back in row navigation instead of on the trigger button.
+     * Only consulted for `triggerMode: "button"`; row triggers already restore to
+     * themselves. Takes effect only for Escape, not keyboard menu selection.
+     * Takes precedence over `escapeFocusContainerSelector`.
+     */
+    escapeFocusTarget?: () => HTMLElement | null;
+    /**
+     * CSS selector for the closest ancestor of the trigger (or, if the menu was
+     * never opened, of `document.activeElement`) to focus on Escape. Sugar over
+     * `escapeFocusTarget` for the common "collapse back into the row" case.
+     * Defaults to `".k-table-row"` for `triggerMode: "button"`; harmless to leave
+     * at its default for non-grid button triggers since a missing ancestor simply
+     * falls through to focusing the trigger. Ignored when `escapeFocusTarget` is set.
+     */
+    escapeFocusContainerSelector?: string;
     /**
      * CSS selector used to find the first focusable menu item after open.
      * Defaults to `".k-menu-item:not(.k-disabled)"` for Kendo Menu.
      */
     menuItemSelector?: string;
-    /** Keeps menu-trigger ARIA attributes in sync with `isOpen`. Defaults to `true`. */
+    /**
+     * Keeps `aria-expanded` in sync with `isOpen` on the resolved `triggerRef`.
+     * Defaults to `true`. The consumer is always responsible for the static
+     * `aria-haspopup="menu"` and baseline `aria-expanded="false"` attributes.
+     */
     manageMenuTriggerAria?: boolean;
-    /** Allows a table row to own the menu trigger semantics without adding button behavior. */
-    triggerMode?: PopupMenuTriggerMode;
+    /**
+     * Declares whether `triggerRef` is a button or a `tr.k-table-row`. Required so
+     * misrouted refs (e.g. a button-mode ref that resolves to a row) are never
+     * silently managed.
+     */
+    triggerMode: PopupMenuTriggerMode;
+    /** Enables offset positioning and lifecycle tracking for a dynamic trigger. */
+    anchor?: PopupMenuAnchorOptions | true;
 };
 /** Functions returned by {@link usePopupMenu} for the action menu. */
 export type UsePopupMenuReturn = {
     /** Opens the menu, or closes it when it is already open. */
-    handleActionButtonClick: () => void;
+    handleActionButtonClick: (...args: unknown[]) => void;
     /**
      * Handles keyboard input on the action button. Enter and Space open or close
      * the menu. Escape closes an open menu or moves focus to the configured target.
      */
-    handleActionButtonKeydown: (event: KeyboardEvent) => void;
+    handleActionButtonKeydown: (...args: unknown[]) => void;
     /** Closes the menu when Escape is pressed while using the menu. */
     handleActionMenuEscape: (event: KeyboardEvent) => void;
     /**
@@ -67,6 +122,8 @@ export type UsePopupMenuReturn = {
      * configured focus target; mouse menu selections return focus to the trigger.
      */
     handlePopupClose: () => void;
+    /** Bind to Kendo Popup's `offset` prop when `anchor` is enabled. */
+    offset: ComputedRef<PopupMenuOffset>;
 };
 /**
  * Composable for accessible Kendo Popup + Menu action-menu interactions.

package/dist/observer/index.d.ts

@@ -0,0 +1 @@
+export * from "./useIntersectionObserver";

package/dist/observer/useIntersectionObserver.d.ts

@@ -0,0 +1,31 @@
+import { type Ref } from "vue";
+export type UseIntersectionObserverOptions = {
+    /** Element to observe; the observer reinitializes whenever this ref changes. */
+    target: Readonly<Ref<Element | null>>;
+    /**
+     * Resolves the scroll container that clips the target. Grid consumers must
+     * provide the actual scrolling container, such as `.k-grid-content`. The
+     * observer reinitializes whenever the resolved root element changes.
+     */
+    root: () => Element | null;
+    /**
+     * One or more intersection ratios from `0` through `1`. `0` observes entry
+     * and complete departure; `1` observes full visibility. Defaults to `1`.
+     */
+    threshold?: number | number[];
+    /** Called whenever the target's intersection state changes. */
+    onChange: (entry: IntersectionObserverEntry) => void;
+};
+export type UseIntersectionObserverReturn = {
+    /** Stops observing the current target. Observation resumes if the target ref changes. */
+    disconnect: () => void;
+};
+/**
+ * Observes a reactive element against a lazily resolved clipping root.
+ *
+ * By default, the observer uses a threshold of `1`, so consumers are notified
+ * when the target is no longer fully visible within its root. The observer
+ * reinitializes whenever the target or resolved root changes. If
+ * `IntersectionObserver` is unavailable (e.g. SSR), this is a no-op.
+ */
+export declare const useIntersectionObserver: (options: UseIntersectionObserverOptions) => UseIntersectionObserverReturn;

package/dist/observer/useIntersectionObserver.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/registry/index.d.ts

@@ -0,0 +1,2 @@
+export { useActiveIdRegistry } from "./useActiveIdRegistry";
+export type { RegisterableElement, UseActiveIdRegistryReturn, } from "./useActiveIdRegistry";

package/dist/registry/useActiveIdRegistry.d.ts

@@ -0,0 +1,35 @@
+import { type ComputedRef, type DeepReadonly, type Ref } from "vue";
+/** An element ref value that may be a plain element or a Vue/Kendo ref-like object exposing `$el`. */
+export type RegisterableElement = HTMLElement | {
+    $el?: HTMLElement | null;
+} | null;
+/** Functions and state returned by {@link useActiveIdRegistry}. */
+export type UseActiveIdRegistryReturn<Id> = {
+    /** The currently active id, or `null` when nothing is active. Read-only; use `activate`/`deactivate` to change it. */
+    activeId: DeepReadonly<Ref<Id | null>>;
+    /** `true` while any id is active. */
+    isActive: ComputedRef<boolean>;
+    /** The registered element for the active id, or `null`. */
+    activeElement: ComputedRef<HTMLElement | null>;
+    /** Registers (or unregisters, when `el` is `null`) the element for `id`. */
+    register: (id: Id, el: RegisterableElement) => void;
+    /** Returns the currently registered element for `id`, if any. */
+    resolve: (id: Id) => HTMLElement | null;
+    /** Marks `id` as active. */
+    activate: (id: Id) => void;
+    /** Clears the active id. */
+    deactivate: () => void;
+    /** Returns whether `id` is the currently active id. */
+    isIdActive: (id: Id) => boolean;
+};
+/**
+ * Tracks which single id, out of a rendered list of items (grid rows, tabs,
+ * action buttons, etc.), is currently "active," alongside a registry
+ * resolving each id to its mounted DOM element.
+ *
+ * This helper is useful for shared-instance patterns where one popup/menu instance
+ * is reused across a list while a single item remains active at a time.
+ *
+ * @returns Active-id state, an element registry, and activation helpers.
+ */
+export declare const useActiveIdRegistry: <Id = string | number>() => UseActiveIdRegistryReturn<Id>;

package/dist/registry/useActiveIdRegistry.test.d.ts

@@ -0,0 +1 @@
+export {};

package/docs/date/useMaskedDateInput.md

@@ -22,9 +22,10 @@ import { ref } from "vue";
 import { DatePicker } from "@progress/kendo-vue-dateinputs";
 import { MaskedTextBox } from "@progress/kendo-vue-inputs";
 import { Error } from "@progress/kendo-vue-labels";
-import { useMaskedDateInput, usePopupTrap } from "@featherk/composables";
+import { useMaskedDateInput } from "@featherk/composables/date";
+import { usePopupTrap } from "@featherk/composables/trap";
 
-const selectedDate = ref<Date | null | undefined>();
+const selectedDate = ref<Date | undefined>();
 const showPicker = ref(false);
 const pickerRoot = ref<HTMLElement | null>(null);
 
@@ -35,7 +36,7 @@ const masked = useMaskedDateInput({
   id: "startDate",
   onChange: ({ value }) => { selectedDate.value = value ?? undefined; },
   onShowCalendar: () => (showPicker.value = true),
-  externalValue: selectedDate as any,
+  externalValue: selectedDate,
   min: MIN_DATE,
   max: MAX_DATE,
   required: true,
@@ -105,6 +106,11 @@ Note: Destructure only the values used as component props that would otherwise r
 
 `useMaskedDateInput` can also power a custom masked input inside Kendo `DatePicker` via the `dateInput="masked"` slot. See the full reference in [src/components/custom-date-picker/CustomDatePicker.vue](../src/components/custom-date-picker/CustomDatePicker.vue).
 
+When binding to Kendo `DatePicker`, use `Ref<Date | undefined>` for the calendar
+`v-model`. The composable's `ChangePayload` uses `Date | null` to represent an
+incomplete or invalid mask, so normalize that payload at the callback boundary with
+`value ?? undefined` before assigning it to the DatePicker model.
+
 ## API
 
 ### `useMaskedDateInput(options)`

package/docs/id/useCompositeId.md

@@ -0,0 +1,29 @@
+# useCompositeId
+
+[Back to Composables README](https://github.com/NantHealth/featherk/blob/integration/packages/composables/README.md)
+
+Creates SSR-safe, component-scoped DOM IDs using Vue's `useId()`. Use it for related trigger, popup, menu, and ARIA relationship IDs within one rendered component instance.
+
+## Quick Start
+
+1. Call `useCompositeId()` from component setup.
+2. Use `instanceId` when one component-level DOM ID is needed.
+3. Use `compose(...)` for related IDs with stable logical segments.
+
+```ts
+import { useCompositeId } from "@featherk/composables";
+
+// Step 1: Vue creates a unique ID for this rendered component instance.
+const ids = useCompositeId("action-cell");
+
+// Step 2: use the component-level ID where a single DOM ID is needed.
+const cellId = ids.instanceId;
+
+// Step 3: compose related DOM and ARIA relationship IDs.
+const triggerId = ids.compose("patient", "trigger");
+const menuId = ids.compose("patient", "menu");
+```
+
+The default prefix is `fkid`, producing IDs like `fkid-v-0-patient-menu`. Pass a custom prefix when a component-specific DOM prefix improves inspection or debugging.
+
+`useCompositeId` is for component-scoped DOM identifiers. Keep deterministic row/trigger IDs used with `useActiveIdRegistry` consumer-owned, for example `patient:42`.

package/docs/menu/usePopupMenu.md

@@ -6,27 +6,29 @@ Composable for accessible Kendo UI for Vue `Popup` + `Menu` action menus. It man
 
 ## Quick Start
 
-1. Create parent-owned refs for `isOpen`, `triggerRef`, `menuRef`, and an optional keyboard focus target.
-2. Call `usePopupMenu(...)` with `requestShow` and `requestHide` that update the parent-owned `isOpen` state.
-3. Route Kendo Menu `@select` through `handleMenuSelect(event, onAction)` so the composable closes first and your business action runs second.
-4. Bind trigger button `@click` and `@keydown` to the composable handlers.
-5. Bind Popup `@close` and Menu `@keydown.escape` so keyboard and mouse close paths restore focus correctly.
+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.
+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.
 
 ```vue
 <template>
   <section ref="panelRef">
-    <!-- Step 4: bind trigger handlers -->
+    <!-- Step 1: static aria-haspopup/aria-expanded baseline; Step 5: bind trigger handlers -->
     <button
       ref="triggerRef"
       type="button"
       aria-haspopup="menu"
+      aria-expanded="false"
       @click="menu.handleActionButtonClick"
       @keydown="menu.handleActionButtonKeydown"
     >
       Actions
     </button>
 
-    <!-- Step 5: bind popup/menu close hooks for modality-aware focus restoration -->
+    <!-- Step 6: bind popup/menu close hooks for modality-aware focus restoration -->
     <Popup :show="isOpen" @close="menu.handlePopupClose">
       <Menu
         ref="menuRef"
@@ -44,23 +46,24 @@ import {
   type KendoMenuSelectEvent,
 } from "@featherk/composables/menu";
 
-// Step 1: parent-owned menu state and element refs
+// Step 2: parent-owned menu state and element refs
 const isOpen = ref(false);
 const triggerRef = ref<HTMLElement | null>(null);
 const menuRef = ref<HTMLElement | null>(null);
 const panelRef = ref<HTMLElement | null>(null);
 
-// Step 2: wire composable show/hide ownership to parent state
+// Step 3: wire composable show/hide ownership to parent state
 const menu = usePopupMenu({
   isOpen,
   triggerRef,
   menuRef,
+  triggerMode: "button",
   focusTargetRef: panelRef,
   requestShow: () => (isOpen.value = true),
   requestHide: () => (isOpen.value = false),
 });
 
-// Step 3: run close+modality handling first, then app-specific action logic
+// Step 4: act while the active context is available; usePopupMenu closes afterward
 const onSelect = (event: KendoMenuSelectEvent) => {
   menu.handleMenuSelect(event, (selected) => {
     // Keep application-specific actions in the consuming component.
@@ -74,11 +77,12 @@ const onSelect = (event: KendoMenuSelectEvent) => {
 
 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.
 
-1. Read `showMenu` from the row item and keep open/close state parent-owned.
-2. Create trigger and menu refs as component refs (`ComponentPublicInstance`) for Kendo wrappers.
-3. Call `usePopupMenu(...)` and map `requestShow`/`requestHide` to row-specific emits.
-4. Provide `resolveFocusTarget` so keyboard close restores focus to the current virtualized row.
-5. Route menu selection through `handleMenuSelect(event, onAction)` so close/focus behavior runs before row action logic.
+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.
+6. Route menu selection through `handleMenuSelect(event, onAction)` so row action logic can use its active state before the popup closes.
 
 ```ts
 <script setup lang="ts">
@@ -94,21 +98,22 @@ const emit = defineEmits<{
   "update:hideMenu": [id: string];
 }>();
 
-// Step 1: read row-owned open state from the data item
+// Step 2: read row-owned open state from the data item
 const isOpen = computed(() => props.dataItem.showMenu);
 
-// Step 2: Kendo refs are component instances; usePopupMenu resolves $el internally
+// Step 3: Kendo refs are component instances; usePopupMenu resolves $el internally
 const triggerRef = ref<ComponentPublicInstance | null>(null);
 const menuRef = ref<ComponentPublicInstance | null>(null);
 
-// Step 3: keep popup ownership in parent row state via emits
+// Step 4: keep popup ownership in parent row state via emits
 const menu = usePopupMenu({
   isOpen,
   triggerRef,
   menuRef,
+  triggerMode: "button",
   requestShow: () => emit("update:showMenu", props.dataItem.id),
   requestHide: () => emit("update:hideMenu", props.dataItem.id),
-  // Step 4: keyboard close restores focus to current virtualized grid row
+  // Step 5: keyboard close restores focus to current virtualized grid row
   resolveFocusTarget: () => {
     const trigger = triggerRef.value?.$el as HTMLElement | undefined;
     return (
@@ -117,7 +122,7 @@ const menu = usePopupMenu({
   },
 });
 
-// Step 5: let usePopupMenu close first, then run row-specific business action
+// Step 6: run row-specific business action before usePopupMenu closes
 const onSelect = (event: KendoMenuSelectEvent) => {
   menu.handleMenuSelect(event, (selected) => {
     // Row-specific action logic remains here.
@@ -127,6 +132,99 @@ const onSelect = (event: KendoMenuSelectEvent) => {
 </script>
 ```
 
+## Row + Button Dual Trigger
+
+A grid row can have both a row-level context menu (`triggerMode: "row"`) and a nested button-level quick-actions menu (`triggerMode: "button"`). Each trigger role needs its own composable instance and its own resolved DOM node; sharing a `triggerRef` between them lets one instance silently overwrite the other's `aria-expanded` state.
+
+1. Add static `aria-haspopup="menu"` and `aria-expanded="false"` to every menu-capable trigger (the row's rendered `tr` and the nested button) up front, in the template, not through the composable.
+2. Create one `usePopupMenu` instance per trigger role, each with its own `triggerRef`, `isOpen`, `requestShow`, and `requestHide`.
+3. Resolve the row instance's `triggerRef` from a stable cell inside the row (e.g. `cellRef.value?.closest(".k-table-row")`); resolve the button instance's `triggerRef` from the button component ref directly. Never derive one from the other.
+4. Set `triggerMode` explicitly for each instance (`"row"` for the row trigger, `"button"` for the nested button).
+5. Verify in devtools that each instance's `triggerRef.value` resolves to a distinct DOM node before wiring `requestShow`/`requestHide`.
+
+```ts
+// Step 2-4: independent instances, independent triggerRef, explicit triggerMode
+const rowTriggerRef = computed(() => cellRef.value?.closest(".k-table-row") as HTMLElement | null);
+
+const buttonMenu = usePopupMenu({
+  isOpen: computed(() => props.dataItem.showButtonMenu),
+  triggerRef: buttonRef,
+  menuRef: buttonMenuRef,
+  triggerMode: "button",
+  requestShow: () => emit("update:toggleButtonMenu", props.dataItem.id),
+  requestHide: () => emit("update:hideButtonMenu", props.dataItem.id),
+});
+
+const rowMenu = usePopupMenu({
+  isOpen: computed(() => props.dataItem.showRowMenu),
+  triggerRef: rowTriggerRef,
+  menuRef: rowMenuRef,
+  triggerMode: "row",
+  requestShow: () => emit("update:toggleRowMenu", props.dataItem.id),
+  requestHide: () => emit("update:hideRowMenu", props.dataItem.id),
+});
+```
+
+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.
+
+## Sharing One Instance Across Many Triggers (Grid-Wide)
+
+A single `usePopupMenu` instance can manage an entire list of same-mode triggers (every row, or every row's action button) instead of instantiating one composable per row. This avoids one popup lifecycle, one `onClickOutside` listener, and one set of watchers per row in large grids. It requires a small amount of consumer-owned bookkeeping the composable itself does not provide; the public helper `useActiveIdRegistry` from `@featherk/composables` handles that bookkeeping so each view does not need to reimplement it.
+
+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.
+
+```ts
+// Step 1: one registry tracks the active id and resolves it to its DOM element
+const rowRegistry = useActiveIdRegistry<number>();
+
+// Step 3: isOpen/triggerRef derive from the registry, not a per-row prop
+const rowMenu = usePopupMenu({
+  isOpen: rowRegistry.isActive,
+  triggerRef: rowRegistry.activeElement,
+  menuRef: rowMenuRef,
+  triggerMode: "row",
+  anchor: true,
+  requestShow: () => {}, // state is set directly by the row click handler, not by the composable
+  requestHide: () => rowRegistry.deactivate(),
+});
+
+// Step 2: register each row's element as it renders (e.g. inside a Grid row-render function)
+const registerRowTrigger = (id: number, el: HTMLElement | null) => {
+  rowRegistry.register(id, el);
+};
+
+// Step 5: toggle logic owns the open/close decision; the composable only reacts
+const toggleRowMenu = (id: number) => {
+  if (rowRegistry.isIdActive(id)) {
+    rowRegistry.deactivate(); // closes: the reactive watcher demotes aria-expanded
+    return;
+  }
+  rowRegistry.activate(id); // switches directly: previous trigger is demoted, new one promoted
+};
+```
+
+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:
+
+```ts
+const toggleButtonMenu = (id: number) => {
+  if (buttonRegistry.isIdActive(id)) {
+    buttonMenu.handleActionButtonClick(); // closes: triggerRef still matches this id
+    return;
+  }
+  if (buttonRegistry.isActive.value) {
+    buttonMenu.handleActionButtonClick(); // 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.
+
 ## API
 
 ### `usePopupMenu(options)`
@@ -141,8 +239,9 @@ const onSelect = (event: KendoMenuSelectEvent) => {
 - `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.
 - `menuItemSelector?: string`: Selector for the first enabled item. Defaults to `.k-menu-item:not(.k-disabled)`.
-- `manageMenuTriggerAria?: boolean`: Keeps `aria-haspopup="menu"` and `aria-expanded` in sync with `isOpen` on the resolved `triggerRef` element. Defaults to `true`; while enabled, the composable owns both attributes and removes them when the trigger is replaced or the component unmounts. Set to `false` to own both attributes yourself.
-- `triggerMode?: "button" | "row"`: Selects the trigger semantics. Defaults to `"button"`; use `"row"` only when a `tr.k-table-row` owns the menu trigger. Row mode manages ARIA attributes but does not add `role`, `tabindex`, or keyboard behavior.
+- `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.
+- `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`, and `getRect` for pointer-positioned menus. Internally, the anchor-hidden policy uses `useIntersectionObserver` with `threshold: 1`; a clipped trigger closes with `"anchor-hidden"` without restoring focus.
 
 `PopupMenuElementRef` accepts a normal `HTMLElement` ref or a Vue/Kendo component ref that exposes `$el`.
 
@@ -153,6 +252,7 @@ const onSelect = (event: KendoMenuSelectEvent) => {
 - `handleActionMenuEscape(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.
 
 #### Types
 
@@ -162,6 +262,7 @@ export type PopupMenuCloseReason =
   | "mouse-selection"
   | "outside-click"
   | "trigger-click"
+  | "anchor-hidden"
   | null;
 export type PopupMenuCloseTrigger = Exclude<PopupMenuCloseReason, null>;
 export type KendoMenuSelectEvent = {
@@ -173,14 +274,16 @@ export type KendoMenuSelectEvent = {
 ## Behavior
 
 - Pointer click, `Enter`, and `Space` toggle the menu.
-- `aria-haspopup="menu"` and `aria-expanded` are written to every resolved `triggerRef` element, including native buttons and Vue/Kendo component refs resolved through `$el`.
-- A `tr.k-table-row` is managed only with `triggerMode: "row"`; rows are never automatically made keyboard buttons.
-- Trigger replacement and virtualization are handled by re-resolving the ref. Managed attributes are removed from the previous trigger and on unmount. Set `manageMenuTriggerAria` to `false` when the consumer owns the attributes.
+- `aria-haspopup="menu"` is a static, consumer-owned template attribute; the composable never sets or removes it.
+- `aria-expanded` is written to every resolved `triggerRef` element, including native buttons and Vue/Kendo component refs resolved through `$el`. The consumer provides the baseline `aria-expanded="false"` in the template; the composable only ever updates the value afterward.
+- A `tr.k-table-row` is managed only with `triggerMode: "row"`; rows are never automatically made keyboard buttons. A mismatched `triggerMode`/resolved-element combination logs a `console.warn` and skips management for that element.
+- 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 records keyboard or mouse modality from the selection event type.
+- Menu selection runs the optional business callback while the active state is still available, then records modality and closes the popup.
 - `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.
 - Outside-click and trigger-click closes do not force focus restoration.
+- An anchor-hidden close does not restore focus, preventing an off-screen grid row from being scrolled back into view.
 - Business-specific actions are never implemented by the composable.