@featherk/composables 0.9.8 → 0.10.1

package/dist/index.d.ts

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

package/dist/menu/index.d.ts

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

package/dist/menu/usePopupMenu.d.ts

@@ -0,0 +1,81 @@
+import { type ComponentPublicInstance, 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>;
+/** 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 PopupMenuCloseTrigger = Exclude<PopupMenuCloseReason, null>;
+/** Minimal event shape emitted by Kendo Menu `@select`. */
+export type KendoMenuSelectEvent = {
+    item?: {
+        text?: string;
+    };
+    event?: {
+        type?: string;
+    } | null;
+};
+/** Options for configuring {@link usePopupMenu}. */
+export type UsePopupMenuOptions = {
+    /** Reactive flag reflecting whether the popup menu is currently open. */
+    isOpen: Ref<boolean>;
+    /** Ref to the popup menu element or component. Used for outside-click detection. */
+    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;
+    /**
+     * Optional target to focus after a keyboard-driven close.
+     * Supports ordinary elements and Vue/Kendo components exposing `$el`.
+     */
+    focusTargetRef?: PopupMenuElementRef;
+    /**
+     * Resolves the focus target when it is virtualized or dynamically rendered.
+     * Takes precedence over `focusTargetRef`.
+     */
+    resolveFocusTarget?: () => HTMLElement | null;
+    /**
+     * 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 `aria-expanded` on the trigger in sync with `isOpen`.
+     * Applies only to button-like triggers. Defaults to `true`.
+     */
+    manageAriaExpanded?: boolean;
+};
+/** 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;
+    /**
+     * 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;
+    /** Closes the menu when Escape is pressed while using the menu. */
+    handleActionMenuEscape: (event: KeyboardEvent) => void;
+    /**
+     * Closes the menu after an item is chosen, then runs the optional action
+     * provided by the consuming component.
+     */
+    handleMenuSelect: (event: KendoMenuSelectEvent, onAction?: (event: KendoMenuSelectEvent) => void) => void;
+    /**
+     * Restores focus after the popup closes. Keyboard actions prefer the
+     * configured focus target; mouse menu selections return focus to the trigger.
+     */
+    handlePopupClose: () => void;
+};
+/**
+ * Composable for accessible Kendo Popup + Menu action-menu interactions.
+ *
+ * It manages toggling, menu-item focus, selection modality, and contextual
+ * focus restoration. The consuming component keeps ownership of menu state
+ * and business-specific actions.
+ *
+ * @param options - Parent-owned popup state, refs, and focus configuration.
+ * @returns Template event handlers for the action trigger, Kendo Menu, and Popup.
+ */
+export declare const usePopupMenu: (options: UsePopupMenuOptions) => UsePopupMenuReturn;

package/dist/menu/usePopupMenu.test.d.ts

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

package/docs/menu/usePopupMenu.md

@@ -0,0 +1,146 @@
+# usePopupMenu
+
+[Back to Composables README](https://github.com/NantHealth/featherk/blob/integration/packages/composables/README.md)
+
+Composable for accessible Kendo UI for Vue `Popup` + `Menu` action menus. It manages trigger toggling, first-item focus, outside clicks, input-modality tracking, and focus restoration. It does not trap focus or own popup state; keep `usePopupTrap` separate when focus trapping or generic popup lifecycle behavior is needed.
+
+## 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>
+
+<template>
+  <section ref="panelRef">
+    <button
+      ref="triggerRef"
+      type="button"
+      aria-haspopup="true"
+      @click="menu.handleActionButtonClick"
+      @keydown="menu.handleActionButtonKeydown"
+    >
+      Actions
+    </button>
+
+    <Popup :show="isOpen" @close="menu.handlePopupClose">
+      <Menu
+        ref="menuRef"
+        @keydown.escape="menu.handleActionMenuEscape"
+        @select="onSelect"
+      />
+    </Popup>
+  </section>
+</template>
+```
+
+## 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.
+
+```ts
+<script setup lang="ts">
+import { computed, ref, type ComponentPublicInstance } from "vue";
+import { usePopupMenu } from "@featherk/composables/menu";
+
+const props = defineProps<{ dataItem: { id: string; showMenu: boolean } }>();
+const emit = defineEmits<{
+  "update:showMenu": [id: string];
+  "update:hideMenu": [id: string];
+}>();
+
+const triggerRef = ref<ComponentPublicInstance | null>(null);
+const menuRef = ref<ComponentPublicInstance | null>(null);
+
+const menu = usePopupMenu({
+  isOpen: computed(() => props.dataItem.showMenu),
+  triggerRef,
+  menuRef,
+  requestShow: () => emit("update:showMenu", props.dataItem.id),
+  requestHide: () => emit("update:hideMenu", props.dataItem.id),
+  resolveFocusTarget: () => {
+    const trigger = triggerRef.value?.$el as HTMLElement | undefined;
+    return (
+      trigger?.closest(".k-table-row[data-grid-row-index]") ?? null
+    ) as HTMLElement | null;
+  },
+});
+
+const onSelect = (event: Parameters<typeof menu.handleMenuSelect>[0]) => {
+  menu.handleMenuSelect(event, (selected) => {
+    // Row-specific action logic remains here.
+    runGridAction(props.dataItem.id, selected.item?.text);
+  });
+};
+</script>
+```
+
+## API
+
+### `usePopupMenu(options)`
+
+#### Options
+
+- `isOpen: Ref<boolean>`: Parent-owned popup visibility state.
+- `menuRef: PopupMenuElementRef`: Ref to the Kendo `Menu` element or component.
+- `triggerRef: PopupMenuElementRef`: Ref to the action trigger element or component.
+- `requestShow(): void`: Opens the parent-owned popup state.
+- `requestHide(): void`: Closes the parent-owned popup state.
+- `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)`.
+- `manageAriaExpanded?: boolean`: Keeps `aria-expanded` on a button-like trigger in sync with `isOpen`. Defaults to `true`; set to `false` to bind the attribute yourself.
+
+`PopupMenuElementRef` accepts a normal `HTMLElement` ref or a Vue/Kendo component ref that exposes `$el`.
+
+#### Returns
+
+- `handleActionButtonClick()`: Toggles the menu and focuses the first enabled item after opening.
+- `handleActionButtonKeydown(event)`: `Enter` and `Space` toggle; `Escape` closes, or focuses the configured target when already closed.
+- `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.
+
+#### Types
+
+```ts
+export type PopupMenuCloseReason = "keyboard" | "mouse" | null;
+export type PopupMenuCloseTrigger = "keyboard" | "mouse";
+export type KendoMenuSelectEvent = {
+  item?: { text?: string };
+  event?: { type?: string } | null;
+};
+```
+
+## Behavior
+
+- Pointer click, `Enter`, and `Space` toggle the menu.
+- `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.
+- Keyboard-driven closes focus `resolveFocusTarget()` or `focusTargetRef`, then fall back to the trigger.
+- Business-specific actions are never implemented by the composable.

package/docs/range/useMaskedDateRangeInput.md

@@ -145,8 +145,9 @@ Creates a controller for a masked date range input.
 - **`debugEnabled: Ref<boolean>`** and **`debugLines: Computed<Array<{label:string; value:string}>>`**: Debug info for UI display.
 - **`digitsOnly: Computed<string>`**: The raw string with non-digits removed.
 - **`valid: Ref<boolean | undefined>`**: Managed validity state (mirrored into `externalValid` when enabled).
-- **`validComputed: Readonly<ComputedRef<boolean | undefined>>`**: Derived validity considering mask completeness, min/max clamping, ordering, and span constraints.
-- **`reason: Readonly<ComputedRef<string | undefined>>`**: Explanation for invalid states; returns `'valid'` when the range passes validation.
+- **`validComputed: Readonly<ComputedRef<boolean | undefined>>`**: Derived validity considering mask completeness, min/max clamping, ordering, and span constraints. Not flagged until the first blur/clear; live thereafter.
+- **`reason: Readonly<ComputedRef<string | undefined>>`**: Explanation for invalid states; returns `'valid'` when the range passes validation and `undefined` before the first blur/clear.
+- **`validationMessage: Readonly<ComputedRef<string>>`**: User-facing message derived from `reason`; always in sync with `validComputed`.
 - **`spanDays: Readonly<ComputedRef<number | undefined>>`**: Span in days between clamped start/end; `undefined` when incomplete or invalid.
 - Readonly computed parts: **`month1`**, **`day1`**, **`year1`**, **`month2`**, **`day2`**, **`year2`** (strings). Useful for diagnostics.
 - **`initStyling(): void`**: Re-applies the `fk-daterangepicker` class to the input's parent container. Exposed so consumers can re-run theming after Kendo manipulates the DOM; the function is idempotent.  Use this to apply the fk-daterangepicker style hook when the date range picker isn't available on initial load
@@ -165,7 +166,9 @@ Creates a controller for a masked date range input.
 
 - **Mask and parsing**: Expects `00/00/0000 - 00/00/0000`. Parsing requires both dates to be complete (10 chars each) and valid per calendar rules.
 - **Validation**:
-  - Validation is performed only when the input loses focus (on blur).
+  - No validation is reported until the input first loses focus (or is cleared), matching `useMaskedDateInput`'s required-field behavior.
+  - After that first blur, `validComputed`, `reason`, and `validationMessage` all update live from the same source, so the invalid styling and the error text always appear and clear together.
+  - `valid` (the managed ref mirrored into `externalValid`) is still committed on blur/clear. Bind `:valid="validComputed"` for the live-after-blur styling.
   - Each side must be a valid date (including month/day bounds like Feb 29).
   - Clamped to `min`/`max` if provided; outside results in `value=null`.
   - Ordered range required unless `allowReverse=true`.

package/package.json

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