@featherk/composables 0.12.1 → 0.12.2

package/dist/menu/usePopupMenu.d.ts

@@ -33,10 +33,13 @@ export type PopupMenuCloseReason =
  | null;
 export type PopupMenuCloseTrigger = Exclude<PopupMenuCloseReason, null>;
 /** Minimal event shape emitted by Kendo Menu `@select`. */
-export type KendoMenuSelectEvent = {
-    item?: {
-        text?: string;
-    };
+export type KendoMenuSelectEvent<TItem = {
+    text?: string;
+    id?: string;
+    cssClass?: string;
+    data?: unknown;
+}> = {
+    item?: TItem;
     event?: {
         type?: string;
     } | null;
@@ -92,6 +95,8 @@ export type UsePopupMenuOptions = {
      * `aria-haspopup="menu"` and baseline `aria-expanded="false"` attributes.
      */
     manageMenuTriggerAria?: boolean;
+    /** Applies an accessible name to the rendered `role="menubar"` when provided. */
+    menuLabel?: MaybeRefOrGetter<string | null | undefined>;
     /**
      * 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

package/dist/registry/index.d.ts

@@ -1,2 +1,4 @@
+export { useExclusiveGroup } from "./useExclusiveGroup";
+export type { ExclusiveGroupMember, UseExclusiveGroupReturn, } from "./useExclusiveGroup";
 export { useActiveIdRegistry } from "./useActiveIdRegistry";
 export type { RegisterableElement, UseActiveIdRegistryReturn, } from "./useActiveIdRegistry";

package/dist/registry/useExclusiveGroup.d.ts

@@ -0,0 +1,20 @@
+/** A participant that can be deactivated when another group member becomes active. */
+export type ExclusiveGroupMember = {
+    deactivate: () => void;
+};
+/** Coordinates mutually exclusive activation across registered members. */
+export type UseExclusiveGroupReturn = {
+    /** Adds a member and unregisters it automatically when the current owner unmounts. */
+    register: (member: ExclusiveGroupMember) => void;
+    /** Deactivates every registered member except the activating member. */
+    deactivateOthers: (activeMember: ExclusiveGroupMember) => void;
+    /** Deactivates every registered member. */
+    deactivateAll: () => void;
+};
+/**
+ * Coordinates mutually exclusive active-id registries within a Vue owner.
+ *
+ * Registered members are removed automatically when their owning component or composable
+ * unmounts. Call `register` from setup so Vue can associate cleanup with that owner.
+ */
+export declare const useExclusiveGroup: () => UseExclusiveGroupReturn;

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

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

package/docs/address/useZipTextBox.md

@@ -21,7 +21,7 @@ Kendo Vue's `MaskedTextBox` does not handle dynamic mask switching between a 5-d
 <script setup lang="ts">
 import { TextBox } from "@progress/kendo-vue-inputs";
 import { Error } from "@progress/kendo-vue-labels";
-import { useZipTextBox } from "@featherk/composables";
+import { useZipTextBox } from "@featherk/composables/address";
 
 const {
   zipDisplay,

package/docs/grid/useGridA11y.md

@@ -28,7 +28,7 @@ Place inside a `<script setup lang="ts">` block. Provide a Grid ref and call the
 
 ```ts
 import { ref, onMounted, watch } from 'vue';
-import { useGridA11y } from '@featherk/composables';
+import { useGridA11y } from '@featherk/composables/grid';
 
 const gridRef = ref(null);
 const dataResult = ref({ data: [] }); // example data container

package/docs/grid/useGridActiveFilter.md

@@ -23,10 +23,10 @@ npm install @featherk/composables
 
 ## Import
 
-`useGridActiveFilter` is exported from the package root:
+`useGridActiveFilter` is exported from the grid feature barrel:
 
 ```ts
-import { useGridActiveFilter } from "@featherk/composables";
+import { useGridActiveFilter } from "@featherk/composables/grid";
 ```
 
 ## Quick Start
@@ -35,7 +35,7 @@ import { useGridActiveFilter } from "@featherk/composables";
 import { computed, ref } from "vue";
 import type { CompositeFilterDescriptor } from "@progress/kendo-data-query";
 import type { GridFilterChangeEvent, GridColumnProps } from "@progress/kendo-vue-grid";
-import { useGridActiveFilter } from "@featherk/composables";
+import { useGridActiveFilter } from "@featherk/composables/grid";
 
 const filter = ref<CompositeFilterDescriptor | undefined>(undefined);
 

package/docs/grid/useGridRowAction.md

@@ -48,7 +48,7 @@ npm install @featherk/composables
 <script setup lang="ts">
 import { ref } from "vue";
 import { Grid } from "@progress/kendo-vue-grid";
-import { useGridRowAction, type RowActionContext } from "@featherk/composables";
+import { useGridRowAction, type RowActionContext } from "@featherk/composables/grid";
 
 interface Patient {
   id: number;
@@ -96,7 +96,7 @@ When combining `useGridA11y` (for `ArrowUp`/`ArrowDown` row focus navigation) wi
 <script setup lang="ts">
 import { onMounted, ref } from "vue";
 import { Grid } from "@progress/kendo-vue-grid";
-import { useGridA11y, useGridRowAction } from "@featherk/composables";
+import { useGridA11y, useGridRowAction } from "@featherk/composables/grid";
 
 const gridRef = ref(null);
 const patients = ref([{ id: 1, name: "Alice Johnson" }]);

package/docs/id/useCompositeId.md

@@ -11,7 +11,7 @@ Creates SSR-safe, component-scoped DOM IDs using Vue's `useId()`. Use it for rel
 3. Use `compose(...)` for related IDs with stable logical segments.
 
 ```ts
-import { useCompositeId } from "@featherk/composables";
+import { useCompositeId } from "@featherk/composables/id";
 
 // Step 1: Vue creates a unique ID for this rendered component instance.
 const ids = useCompositeId("action-cell");

package/docs/menu/usePopupMenu.md

@@ -30,6 +30,9 @@ Composable for accessible Kendo UI for Vue `Popup` + `Menu` action menus. It man
 
     <!-- Step 6: bind popup/menu close hooks for modality-aware focus restoration -->
     <Popup :show="isOpen" @close="menu.handlePopupClose">
+      <strong v-if="menuTitle" class="fk-menu-title">
+        {{ menuTitle }}
+      </strong>
       <Menu
         ref="menuRef"
         @keydown.escape="menu.handleActionMenuEscape"
@@ -51,6 +54,7 @@ const isOpen = ref(false);
 const triggerRef = ref<HTMLElement | null>(null);
 const menuRef = ref<HTMLElement | null>(null);
 const panelRef = ref<HTMLElement | null>(null);
+const menuTitle = ref("Record actions");
 
 // Step 3: wire composable show/hide ownership to parent state
 const menu = usePopupMenu({
@@ -58,6 +62,7 @@ const menu = usePopupMenu({
   triggerRef,
   menuRef,
   triggerMode: "button",
+  menuLabel: menuTitle,
   focusTargetRef: panelRef,
   requestShow: () => (isOpen.value = true),
   requestHide: () => (isOpen.value = false),
@@ -240,6 +245,7 @@ See [UsePopupMenu.vue](https://github.com/NantHealth/featherk/blob/integration/d
 - `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-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.
+- `menuLabel?: MaybeRefOrGetter<string | null | undefined>`: Optional accessible name applied as `aria-label` to the rendered `ul[role="menubar"]`. Empty labels remove the managed attribute.
 - `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.
 

package/docs/observer/useIntersectionObserver.md

@@ -33,7 +33,7 @@ The composable works the same way with a regular HTML table. Place the table in
 
 <script setup lang="ts">
 import { ref } from "vue";
-import { useIntersectionObserver } from "@featherk/composables";
+import { useIntersectionObserver } from "@featherk/composables/observer";
 
 // Step 1: bind refs to the native scroll wrapper and target table row.
 const tableViewportRef = ref<HTMLElement | null>(null);
@@ -66,7 +66,7 @@ useIntersectionObserver({
 
 ```ts
 import { ref } from "vue";
-import { useIntersectionObserver } from "@featherk/composables";
+import { useIntersectionObserver } from "@featherk/composables/observer";
 
 // Step 1: bind this ref to the target element.
 const cellRef = ref<Element | null>(null);

package/docs/registry/useExclusiveGroup.md

@@ -0,0 +1,73 @@
+# useExclusiveGroup
+
+[Back to Composables README](https://github.com/NantHealth/featherk/blob/integration/packages/composables/README.md)
+
+`useExclusiveGroup` coordinates a set of independently owned active-id registries so that
+activating one can deactivate the others.
+
+This is a Vue composable: `register()` automatically removes each member when the component or
+composable that called it unmounts. Create the group and register members from Vue setup.
+
+## Quick Start
+
+1. Create one group for the interactions that must be mutually exclusive.
+2. Create each active-id registry and register it with the group.
+3. Before activating a registry, deactivate the other group members.
+
+```ts
+import {
+  useActiveIdRegistry,
+  useExclusiveGroup,
+} from "@featherk/composables/registry";
+
+// Step 1: create one group for the related interactions.
+const menuGroup = useExclusiveGroup();
+
+// Step 2: create and register the related registries.
+const actionRegistry = useActiveIdRegistry<string>();
+const rowRegistry = useActiveIdRegistry<number>();
+menuGroup.register(actionRegistry);
+menuGroup.register(rowRegistry);
+
+const openAction = (id: string) => {
+  // Step 3: close sibling interactions before activating this registry.
+  menuGroup.deactivateOthers(actionRegistry);
+  actionRegistry.activate(id);
+};
+```
+
+## With usePopupMenu
+
+`usePopupMenu` stays independent of exclusivity groups. A standalone popup joins through the
+registry that owns its `isOpen`, `requestShow`, and `requestHide` state:
+
+```ts
+const rowRegistry = useActiveIdRegistry<number>();
+const menuGroup = useExclusiveGroup();
+menuGroup.register(rowRegistry);
+
+const rowMenu = usePopupMenu({
+  isOpen: rowRegistry.isActive,
+  triggerRef: rowRegistry.activeElement,
+  menuRef,
+  triggerMode: "row",
+  requestShow: () => {},
+  requestHide: () => rowRegistry.deactivate(),
+});
+
+const openRowMenu = (rowId: number) => {
+  menuGroup.deactivateOthers(rowRegistry);
+  rowRegistry.activate(rowId);
+};
+```
+
+`useActionCellMenu` follows this same pattern internally when its optional `group` is set: it
+registers its own active-id registry and deactivates group peers before it opens its popup.
+
+## API
+
+| Method | Description |
+| --- | --- |
+| `register(member)` | Adds a `{ deactivate(): void }` member and removes it automatically when the current Vue owner unmounts. |
+| `deactivateOthers(activeMember)` | Deactivates all registered members except `activeMember`. |
+| `deactivateAll()` | Deactivates all registered members. |

package/docs/time/useMaskedTimeInput.md

@@ -20,7 +20,8 @@ import { ref } from "vue";
 import { TimePicker } from "@progress/kendo-vue-dateinputs";
 import { MaskedTextBox } from "@progress/kendo-vue-inputs";
 import { Error } from "@progress/kendo-vue-labels";
-import { useMaskedTimeInput, usePopupTrap } from "@featherk/composables";
+import { useMaskedTimeInput } from "@featherk/composables/time";
+import { usePopupTrap } from "@featherk/composables/trap";
 
 // Shared model for TimePicker and composable
 const selectedTime = ref<Date | null | undefined>();

package/package.json

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