@featherk/composables 0.10.9 → 0.11.0

package/dist/grid/index.d.ts

@@ -1,4 +1,4 @@
 export { useGridA11y } from "./useGridA11y";
 export { useGridActiveFilter } from "./useGridActiveFilter";
 export { useGridRowAction } from "./useGridRowAction";
-export type { UseGridRowActionOptions, UseGridRowActionReturn, RowActionContext, } from "./useGridRowAction";
+export type { UseGridRowActionOptions, UseGridRowActionReturn, RowActionContext, RowActionCoordinates, } from "./useGridRowAction";

package/dist/grid/useGridRowAction.d.ts

@@ -13,6 +13,14 @@
  */
 import type { Ref } from "vue";
 import type { GridRowClickEvent } from "../types/kendo";
+export interface RowActionCoordinates {
+    clientX: number;
+    clientY: number;
+    pageX: number;
+    pageY: number;
+    screenX: number;
+    screenY: number;
+}
 export interface RowActionContext<T = any> {
     /**
      * Data item associated with the activated row.
@@ -41,6 +49,12 @@ export interface RowActionContext<T = any> {
     shiftKey: boolean;
     metaKey: boolean;
     altKey: boolean;
+    /**
+     * Pointer coordinates of the activation. Derived from the native mouse event
+     * for clicks, or from the focused row's bounding box for keyboard activation.
+     * `undefined` when neither source is available.
+     */
+    coordinates?: RowActionCoordinates;
 }
 export interface UseGridRowActionOptions<T = any> {
     /**

package/dist/menu/usePopupMenu.d.ts

@@ -1,6 +1,7 @@
 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>;
+export type PopupMenuTriggerMode = "button" | "row";
 /** 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>;
@@ -40,11 +41,10 @@ export type UsePopupMenuOptions = {
      * 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;
+    /** Keeps menu-trigger ARIA attributes in sync with `isOpen`. Defaults to `true`. */
+    manageMenuTriggerAria?: boolean;
+    /** Allows a table row to own the menu trigger semantics without adding button behavior. */
+    triggerMode?: PopupMenuTriggerMode;
 };
 /** Functions returned by {@link usePopupMenu} for the action menu. */
 export type UsePopupMenuReturn = {

package/docs/grid/useGridRowAction.md

@@ -10,7 +10,7 @@ Composable that provides safe, accessible row click and keyboard activation hand
 - **Text Selection Protection**: Automatically suppresses row actions when the user is highlighting/selecting text inside a cell within the row.
 - **Primary Mouse Button**: Restricts click activation to primary (left) mouse clicks.
 - **Keyboard Accessibility**: Supports keyboard row activation (`Enter` / `Space`) when focus is on a data row.
-- **Action Decoupled**: Provides normalized row event context (`dataItem`, `rowIndex`, `field`, `triggerType`, modifier keys) while leaving action logic (dialog, route navigation, context menu) to the consumer.
+- **Action Decoupled**: Provides normalized row event context (`dataItem`, `rowIndex`, `field`, `triggerType`, modifier keys, and optional coordinates) while leaving action logic (dialog, route navigation, context menu) to the consumer.
 - **Composable Combination**: Integrates seamlessly with `useGridA11y` for combined row navigation and row action handling.
 
 ## Prerequisites
@@ -125,40 +125,67 @@ onMounted(() => {
 
 `useGridRowAction(options: UseGridRowActionOptions<T>)` accepts the following configuration:
 
-| Option | Type | Default | Description |
-| :--- | :--- | :--- | :--- |
-| `onRowAction` | `(dataItem: T, context: RowActionContext<T>) => void` | **Required** | Callback executed when a valid row click or keyboard activation occurs. |
-| `dataItems` | `Ref<T[]> \| T[]` | `undefined` | Grid data array or ref used to resolve the `dataItem` on grid-level `@keydown` activation. |
-| `gridRef` | `Ref<any>` | `undefined` | Optional ref to Kendo Grid instance as an alternative `dataItem` lookup source. |
-| `ignoreSelectors` | `string[]` | `[]` | Additional CSS selectors inside row cells that should prevent triggering row actions. |
-| `shouldIgnoreTarget` | `(target: HTMLElement, event: Event) => boolean` | `undefined` | Custom predicate function for advanced target element filtering. |
-| `enableKeyboardAction` | `boolean` | `true` | Whether to enable `Enter`/`Space` key activation on focused rows. |
+| Option                 | Type                                                  | Default      | Description                                                                                |
+| :--------------------- | :---------------------------------------------------- | :----------- | :----------------------------------------------------------------------------------------- |
+| `onRowAction`          | `(dataItem: T, context: RowActionContext<T>) => void` | **Required** | Callback executed when a valid row click or keyboard activation occurs.                    |
+| `dataItems`            | `Ref<T[]> \| T[]`                                     | `undefined`  | Grid data array or ref used to resolve the `dataItem` on grid-level `@keydown` activation. |
+| `gridRef`              | `Ref<any>`                                            | `undefined`  | Optional ref to Kendo Grid instance as an alternative `dataItem` lookup source.            |
+| `ignoreSelectors`      | `string[]`                                            | `[]`         | Additional CSS selectors inside row cells that should prevent triggering row actions.      |
+| `shouldIgnoreTarget`   | `(target: HTMLElement, event: Event) => boolean`      | `undefined`  | Custom predicate function for advanced target element filtering.                           |
+| `enableKeyboardAction` | `boolean`                                             | `true`       | Whether to enable `Enter`/`Space` key activation on focused rows.                          |
 
 ## Returns Reference
 
 `useGridRowAction` returns an object containing:
 
-| Property | Type | Description |
-| :--- | :--- | :--- |
-| `handleRowClick` | `(event: GridRowClickEvent) => void` | Primary click handler to bind to Kendo Grid's `@rowclick`. |
+| Property           | Type                                                   | Description                                                                                                                  |
+| :----------------- | :----------------------------------------------------- | :--------------------------------------------------------------------------------------------------------------------------- |
+| `handleRowClick`   | `(event: GridRowClickEvent) => void`                   | Primary click handler to bind to Kendo Grid's `@rowclick`.                                                                   |
 | `handleRowKeyDown` | `(event: KeyboardEvent, explicitDataItem?: T) => void` | Primary keyboard handler to bind to Kendo Grid's `@keydown`. Accepts optional `explicitDataItem` if bound at slot/row level. |
-| `isIgnoredTarget` | `(target: HTMLElement, event?: Event) => boolean` | Utility function to test if a given DOM element matches default or custom ignore selectors. |
+| `isIgnoredTarget`  | `(target: HTMLElement, event?: Event) => boolean`      | Utility function to test if a given DOM element matches default or custom ignore selectors.                                  |
 
 ## Callback Context Reference
 
 The `onRowAction` callback receives `(dataItem, context)` where `context` contains:
 
-| Property | Type | Description |
-| :--- | :--- | :--- |
-| `dataItem` | `T` | The row's data item. |
-| `rowIndex` | `number \| undefined` | Row index in the grid data. |
-| `field` | `string \| undefined` | Column field name if clicked on a specific cell. |
-| `event` | `Event` | Original native browser DOM event. |
-| `triggerType` | `'click' \| 'keyboard'` | Interaction source that triggered the action (`click` or `keyboard`). |
-| `ctrlKey` | `boolean` | `true` if Ctrl key was held down during activation. |
-| `shiftKey` | `boolean` | `true` if Shift key was held down during activation. |
-| `metaKey` | `boolean` | `true` if Cmd / Meta key was held down during activation. |
-| `altKey` | `boolean` | `true` if Alt key was held down during activation. |
+| Property      | Type                                | Description                                                                                                                                  |
+| :------------ | :---------------------------------- | :------------------------------------------------------------------------------------------------------------------------------------------- |
+| `dataItem`    | `T`                                 | The row's data item.                                                                                                                         |
+| `rowIndex`    | `number \| undefined`               | Row index in the grid data.                                                                                                                  |
+| `field`       | `string \| undefined`               | Column field name if clicked on a specific cell.                                                                                             |
+| `event`       | `Event`                             | Original native browser DOM event.                                                                                                           |
+| `triggerType` | `'click' \| 'keyboard'`             | Interaction source that triggered the action (`click` or `keyboard`).                                                                        |
+| `ctrlKey`     | `boolean`                           | `true` if Ctrl key was held down during activation.                                                                                          |
+| `shiftKey`    | `boolean`                           | `true` if Shift key was held down during activation.                                                                                         |
+| `metaKey`     | `boolean`                           | `true` if Cmd / Meta key was held down during activation.                                                                                    |
+| `altKey`      | `boolean`                           | `true` if Alt key was held down during activation.                                                                                           |
+| `coordinates` | `RowActionCoordinates \| undefined` | Activation coordinates when available. Mouse clicks use native pointer coordinates; keyboard activation uses the focused row's bounding box. |
+
+### Row Action Coordinates
+
+`RowActionCoordinates` is exported from `@featherk/composables` and contains the following values:
+
+| Property             | Description                                                                                                                                              |
+| :------------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `clientX`, `clientY` | Coordinates relative to the browser viewport.                                                                                                            |
+| `pageX`, `pageY`     | Coordinates relative to the full document, including scroll offset.                                                                                      |
+| `screenX`, `screenY` | Coordinates relative to the physical screen for pointer activation. For keyboard activation, these are approximated from the row's viewport coordinates. |
+
+The coordinates can be used to position a context menu, popover, tooltip, or other contextual UI near the activated row:
+
+```ts
+onRowAction: (dataItem, context) => {
+  if (context.coordinates) {
+    openContextMenu({
+      dataItem,
+      left: context.coordinates.clientX,
+      top: context.coordinates.clientY,
+    });
+  }
+},
+```
+
+For mouse activation, the values come from the native mouse or pointer event. For keyboard activation, there is no actual pointer location, so the composable derives the values from the focused row's bounding box using its left edge and bottom edge. The `coordinates` property is therefore optional.
 
 ## Default Ignored Selectors
 

package/docs/menu/usePopupMenu.md

@@ -19,7 +19,7 @@ Composable for accessible Kendo UI for Vue `Popup` + `Menu` action menus. It man
     <button
       ref="triggerRef"
       type="button"
-      aria-haspopup="true"
+      aria-haspopup="menu"
       @click="menu.handleActionButtonClick"
       @keydown="menu.handleActionButtonKeydown"
     >
@@ -141,7 +141,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)`.
-- `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.
+- `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.
 
 `PopupMenuElementRef` accepts a normal `HTMLElement` ref or a Vue/Kendo component ref that exposes `$el`.
 
@@ -172,7 +173,9 @@ export type KendoMenuSelectEvent = {
 ## 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`.
+- `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.
 - 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/package.json

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