@featherk/composables 0.11.0 → 0.11.2

package/dist/index.d.ts

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

package/dist/menu/usePopupMenu.d.ts

@@ -41,10 +41,18 @@ export type UsePopupMenuOptions = {
      * 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;
 };
 /** Functions returned by {@link usePopupMenu} for the action menu. */
 export type UsePopupMenuReturn = {

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/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 the composable closes first and your business action runs second.
+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: run close+modality handling first, then app-specific action logic
 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 close/focus behavior runs before row action logic.
 
 ```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: let usePopupMenu close first, then run row-specific business action
 const onSelect = (event: KendoMenuSelectEvent) => {
   menu.handleMenuSelect(event, (selected) => {
     // Row-specific action logic remains here.
@@ -127,6 +132,98 @@ 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. Position the shared `Popup` using `:offset` computed from the clicked element's `getBoundingClientRect()` (or click coordinates), 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.
+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",
+  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 the offset-computation logic. `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 +238,8 @@ 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.
 
 `PopupMenuElementRef` accepts a normal `HTMLElement` ref or a Vue/Kendo component ref that exposes `$el`.
 
@@ -173,9 +270,10 @@ 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.

package/docs/registry/useActiveIdRegistry.md

@@ -0,0 +1,136 @@
+# useActiveIdRegistry
+
+[Back to Composables README](https://github.com/NantHealth/featherk/blob/integration/packages/composables/README.md)
+
+Tracks a single active id across a list of rendered elements (grid rows, tabs, action buttons, etc.) while also resolving that id back to its mounted DOM element.
+
+This helper is for shared-instance patterns where one popup/menu instance is reused across many triggers, but only a single item should be active/open at a time.
+
+## Why use it
+
+When a popup or menu instance is shared across a grid or list, a simple boolean per item is not enough to coordinate the active target. `useActiveIdRegistry` keeps two things in sync:
+
+- the active id for the list
+- the mounted element for that active id
+
+This lets consumers derive both `isOpen` and `triggerRef` from the same registry, rather than re-implementing one-off bookkeeping in each view.
+
+## Quick Start
+
+1. Create a registry instance at the shared list boundary so one active id drives the whole set of triggers.
+2. Register each mounted element by id as it appears or re-renders, including Kendo/Vue component refs via `$el`.
+3. Bind the registry's `isActive`/`activeElement` to the shared popup/menu instance and activate the item that should open.
+4. Deactivate when the item closes so the previously active trigger is demoted and the next item can become active.
+
+```ts
+// Step 1: one registry manages the list-wide active id
+const registry = useActiveIdRegistry<number>();
+
+// Step 2: register each element as it mounts or re-renders
+registry.register(1, rowElement); // Step 2
+registry.register(2, buttonElement); // Step 2
+
+// Step 3: connect the registry to a shared popup/menu instance
+const isOpen = registry.isActive;
+const triggerRef = registry.activeElement;
+
+// Step 4: activate/deactivate when the current item opens or closes
+registry.activate(2);
+
+if (registry.isIdActive(2)) {
+  // active row/button is selected
+}
+
+registry.deactivate();
+```
+
+## Basic Usage
+
+```ts
+const rowRegistry = useActiveIdRegistry<number>();
+
+const rowMenu = usePopupMenu({
+  isOpen: rowRegistry.isActive,
+  triggerRef: rowRegistry.activeElement,
+  menuRef: rowMenuRef,
+  triggerMode: "row",
+  requestShow: () => {
+    // parent-owned open state is handled by registry activation
+  },
+  requestHide: () => rowRegistry.deactivate(),
+});
+
+const toggleRowMenu = (id: number) => {
+  if (rowRegistry.isIdActive(id)) {
+    rowRegistry.deactivate();
+    return;
+  }
+
+  rowRegistry.activate(id);
+};
+```
+
+This pattern is designed for one shared popup/menu instance across many rendered items. The active id stays in sync with the mounted DOM element, so the popup opens against the correct trigger without a per-item boolean for every row.
+
+## API
+
+```ts
+const registry = useActiveIdRegistry<number>();
+
+registry.register(1, rowElement);
+registry.register(2, buttonElement);
+
+registry.activate(2);
+
+const isOpen = registry.isActive;
+const triggerRef = registry.activeElement;
+
+if (registry.isIdActive(2)) {
+  // active row/button is selected
+}
+
+registry.deactivate();
+```
+
+## Return shape
+
+- `activeId`: readonly current id or `null`
+- `isActive`: computed `true` when an id is active
+- `activeElement`: computed DOM element for the active id
+- `register(id, el)`: stores or removes the element for a given id
+- `resolve(id)`: returns the registered DOM element for `id`
+- `activate(id)`: sets the active id
+- `deactivate()`: clears the active id
+- `isIdActive(id)`: checks whether a given id is the current active id
+
+## Shared-instance popup usage
+
+```ts
+const rowRegistry = useActiveIdRegistry<number>();
+
+const rowMenu = usePopupMenu({
+  isOpen: rowRegistry.isActive,
+  triggerRef: rowRegistry.activeElement,
+  menuRef: rowMenuRef,
+  triggerMode: "row",
+  requestShow: () => {
+    // parent-owned open state is handled by activation logic
+  },
+  requestHide: () => rowRegistry.deactivate(),
+});
+
+const toggleRowMenu = (id: number) => {
+  if (rowRegistry.isIdActive(id)) {
+    rowRegistry.deactivate();
+    return;
+  }
+
+  rowRegistry.activate(id);
+};
+```
+
+## Notes
+
+- Accepts both raw DOM elements and Vue/Kendo component refs exposing `$el`.
+- Works well with virtualized or keyed re-renders because the registry re-resolves the current active element when the underlying DOM node changes.
+- This helper is intentionally generic; it does not own popup behavior or ARIA attributes itself.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@featherk/composables",
-  "version": "0.11.0",
+  "version": "0.11.2",
   "main": "dist/featherk-composables.umd.js",
   "module": "dist/featherk-composables.es.js",
   "types": "dist/index.d.ts",
@@ -40,6 +40,11 @@
       "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",
+      "require": "./dist/featherk-composables.umd.js"
+    },
     "./form": {
       "types": "./dist/form/index.d.ts",
       "import": "./dist/featherk-composables.es.js",