@featherk/composables 0.10.2 → 0.10.4

package/docs/menu/usePopupMenu.md

@@ -6,35 +6,16 @@ Composable for accessible Kendo UI for Vue `Popup` + `Menu` action menus. It man
 
 ## Quick Start
 
-```ts
-<script setup lang="ts">
-import { computed, ref } from "vue";
-import { usePopupMenu } from "@featherk/composables/menu";
-
-const isOpen = ref(false);
-const triggerRef = ref<HTMLElement | null>(null);
-const menuRef = ref<HTMLElement | null>(null);
-const panelRef = ref<HTMLElement | null>(null);
-
-const menu = usePopupMenu({
-  isOpen,
-  triggerRef,
-  menuRef,
-  focusTargetRef: panelRef,
-  requestShow: () => (isOpen.value = true),
-  requestHide: () => (isOpen.value = false),
-});
-
-const onSelect = (event: Parameters<typeof menu.handleMenuSelect>[0]) => {
-  menu.handleMenuSelect(event, (selected) => {
-    // Keep application-specific actions in the consuming component.
-    if (selected.item?.text === "Archive") archiveRecord();
-  });
-};
-</script>
+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.
 
+```vue
 <template>
   <section ref="panelRef">
+    <!-- Step 4: bind trigger handlers -->
     <button
       ref="triggerRef"
       type="button"
@@ -45,6 +26,7 @@ const onSelect = (event: Parameters<typeof menu.handleMenuSelect>[0]) => {
       Actions
     </button>
 
+    <!-- Step 5: bind popup/menu close hooks for modality-aware focus restoration -->
     <Popup :show="isOpen" @close="menu.handlePopupClose">
       <Menu
         ref="menuRef"
@@ -54,16 +36,57 @@ const onSelect = (event: Parameters<typeof menu.handleMenuSelect>[0]) => {
     </Popup>
   </section>
 </template>
+
+<script setup lang="ts">
+import { ref } from "vue";
+import {
+  usePopupMenu,
+  type KendoMenuSelectEvent,
+} from "@featherk/composables/menu";
+
+// Step 1: 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
+const menu = usePopupMenu({
+  isOpen,
+  triggerRef,
+  menuRef,
+  focusTargetRef: panelRef,
+  requestShow: () => (isOpen.value = true),
+  requestHide: () => (isOpen.value = false),
+});
+
+// Step 3: 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.
+    if (selected.item?.text === "Archive") archiveRecord();
+  });
+};
+</script>
 ```
 
 ## Grid Action Cell
 
 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.
+
 ```ts
 <script setup lang="ts">
 import { computed, ref, type ComponentPublicInstance } from "vue";
-import { usePopupMenu } from "@featherk/composables/menu";
+import {
+  usePopupMenu,
+  type KendoMenuSelectEvent,
+} from "@featherk/composables/menu";
 
 const props = defineProps<{ dataItem: { id: string; showMenu: boolean } }>();
 const emit = defineEmits<{
@@ -71,15 +94,21 @@ const emit = defineEmits<{
   "update:hideMenu": [id: string];
 }>();
 
+// Step 1: 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
 const triggerRef = ref<ComponentPublicInstance | null>(null);
 const menuRef = ref<ComponentPublicInstance | null>(null);
 
+// Step 3: keep popup ownership in parent row state via emits
 const menu = usePopupMenu({
-  isOpen: computed(() => props.dataItem.showMenu),
+  isOpen,
   triggerRef,
   menuRef,
   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
   resolveFocusTarget: () => {
     const trigger = triggerRef.value?.$el as HTMLElement | undefined;
     return (
@@ -88,7 +117,8 @@ const menu = usePopupMenu({
   },
 });
 
-const onSelect = (event: Parameters<typeof menu.handleMenuSelect>[0]) => {
+// Step 5: let usePopupMenu close first, then run row-specific business action
+const onSelect = (event: KendoMenuSelectEvent) => {
   menu.handleMenuSelect(event, (selected) => {
     // Row-specific action logic remains here.
     runGridAction(props.dataItem.id, selected.item?.text);
@@ -126,8 +156,13 @@ const onSelect = (event: Parameters<typeof menu.handleMenuSelect>[0]) => {
 #### Types
 
 ```ts
-export type PopupMenuCloseReason = "keyboard" | "mouse" | null;
-export type PopupMenuCloseTrigger = "keyboard" | "mouse";
+export type PopupMenuCloseReason =
+  | "keyboard"
+  | "mouse-selection"
+  | "outside-click"
+  | "trigger-click"
+  | null;
+export type PopupMenuCloseTrigger = Exclude<PopupMenuCloseReason, null>;
 export type KendoMenuSelectEvent = {
   item?: { text?: string };
   event?: { type?: string } | null;
@@ -140,7 +175,9 @@ export type KendoMenuSelectEvent = {
 - `aria-expanded` is written to the trigger whenever it is a `<button>`, has `role="button"`, or declares `aria-haspopup`.
 - 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.
-- Selection and Escape preserve keyboard versus mouse modality.
-- Mouse-driven closes restore focus to the trigger.
+- Menu selection records keyboard or mouse modality from the selection event type.
+- `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.
 - Business-specific actions are never implemented by the composable.

package/package.json

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