@featherk/composables 0.10.6 → 0.10.8

package/dist/grid/index.d.ts

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

package/dist/grid/useGridRowAction.d.ts

@@ -0,0 +1,86 @@
+/**
+ * useGridRowAction
+ *
+ * Composable that provides safe, accessible row click and keyboard activation
+ * handlers for Kendo UI for Vue Grid instances.
+ *
+ * Highlights:
+ * - Guards against triggers when clicking interactive elements (buttons, links, inputs, checkboxes).
+ * - Suppresses activation when the user is highlighting/selecting text inside a cell.
+ * - Restricts mouse actions to primary (left) click.
+ * - Provides keyboard activation (Enter / Space) for focused grid rows.
+ * - Action-agnostic: executes consumer-supplied `onRowAction` callback with `dataItem` and context.
+ */
+import type { Ref } from "vue";
+import type { GridRowClickEvent } from "../types/kendo";
+export interface RowActionContext<T = any> {
+    /**
+     * Data item associated with the activated row.
+     */
+    dataItem: T;
+    /**
+     * Row index if provided by Kendo event or row DOM attribute.
+     */
+    rowIndex?: number;
+    /**
+     * Field name if click originated on a specific column cell.
+     */
+    field?: string;
+    /**
+     * Original native browser event.
+     */
+    event: Event;
+    /**
+     * Interaction trigger type ('click' | 'keyboard').
+     */
+    triggerType: "click" | "keyboard";
+    /**
+     * Modifier key states during activation.
+     */
+    ctrlKey: boolean;
+    shiftKey: boolean;
+    metaKey: boolean;
+    altKey: boolean;
+}
+export interface UseGridRowActionOptions<T = any> {
+    /**
+     * Action callback invoked when a row is clicked or activated via keyboard.
+     */
+    onRowAction: (dataItem: T, context: RowActionContext<T>) => void;
+    /**
+     * Optional ref to Kendo Grid component instance or array/ref of data items.
+     * Used to resolve the row `dataItem` when row is activated via grid-level `@keydown`.
+     */
+    gridRef?: Ref<any>;
+    dataItems?: Ref<T[]> | T[];
+    /**
+     * Additional CSS selectors inside row cells that should prevent the row action.
+     */
+    ignoreSelectors?: string[];
+    /**
+     * Custom predicate function to check if an event target should be ignored.
+     * Return `true` to ignore row action, `false` to proceed.
+     */
+    shouldIgnoreTarget?: (target: HTMLElement, event: Event) => boolean;
+    /**
+     * Whether to enable Enter/Space keyboard activation on focused grid rows.
+     * Default: true
+     */
+    enableKeyboardAction?: boolean;
+}
+export interface UseGridRowActionReturn<T = any> {
+    /**
+     * Grid row click handler to bind to Kendo Grid's `@rowclick` event.
+     */
+    handleRowClick: (event: GridRowClickEvent<T>) => void;
+    /**
+     * Grid keyboard handler to bind to Kendo Grid's `@keydown` event.
+     * Optionally accepts explicit `dataItem` if bound at the row/slot level.
+     */
+    handleRowKeyDown: (event: KeyboardEvent, explicitDataItem?: T) => void;
+    /**
+     * Helper function to test if a given DOM element is an ignored target.
+     */
+    isIgnoredTarget: (target: HTMLElement, event?: Event) => boolean;
+}
+export declare const useGridRowAction: <T = any>(options: UseGridRowActionOptions<T>) => UseGridRowActionReturn<T>;

package/dist/grid/useGridRowAction.test.d.ts

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

package/dist/types/kendo.d.ts

@@ -20,3 +20,10 @@ export interface GridSortChangeEvent {
         sort: SortDescriptor[];
     };
 }
+export interface GridRowClickEvent<T = any> {
+    dataItem: T;
+    rowIndex?: number;
+    field?: string;
+    htmlEvent?: MouseEvent;
+    [key: string]: any;
+}

package/docs/grid/useGridRowAction.md

@@ -0,0 +1,169 @@
+# useGridRowAction
+
+[← Back to Composables README](https://github.com/NantHealth/featherk/blob/integration/packages/composables/README.md)
+
+Composable that provides safe, accessible row click and keyboard activation handlers for Kendo UI for Vue `Grid` components.
+
+## Features
+
+- **Safe Row Clicks**: Ignores clicks originating on interactive child elements (`button`, `a`, `input`, `.k-checkbox`, kebab menus, etc.).
+- **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.
+- **Composable Combination**: Integrates seamlessly with `useGridA11y` for combined row navigation and row action handling.
+
+## Prerequisites
+
+- Vue 3 Composition API
+- `@progress/kendo-vue-grid`
+- `@featherk/composables`
+
+Install:
+
+```bash
+npm install @featherk/composables
+```
+
+## Quick Start
+
+### Implementation Checklist
+
+1. Import `useGridRowAction` and configure `onRowAction` with your action handler.
+2. Bind `@rowclick` on the Kendo Grid to `handleRowClick`.
+3. Bind `@keydown` on the Kendo Grid to `handleRowKeyDown`.
+
+```vue
+<template>
+  <!-- Step 2: Wire @rowclick to handleRowClick -->
+  <!-- Step 3: Wire @keydown to handleRowKeyDown -->
+  <Grid
+    :data-items="gridData"
+    :columns="columns"
+    @rowclick="handleRowClick"
+    @keydown="handleRowKeyDown"
+  />
+</template>
+
+<script setup lang="ts">
+import { ref } from "vue";
+import { Grid } from "@progress/kendo-vue-grid";
+import { useGridRowAction, type RowActionContext } from "@featherk/composables";
+
+interface Patient {
+  id: number;
+  name: string;
+  status: string;
+}
+
+const gridData = ref<Patient[]>([
+  { id: 1, name: "Jane Doe", status: "Active" },
+  { id: 2, name: "John Smith", status: "Pending" },
+]);
+
+const columns = [
+  { field: "id", title: "ID", width: "80px" },
+  { field: "name", title: "Patient Name" },
+  { field: "status", title: "Status" },
+];
+
+// Step 1: Initialize useGridRowAction with options and action handler
+const { handleRowClick, handleRowKeyDown } = useGridRowAction<Patient>({
+  dataItems: gridData,
+  onRowAction: (dataItem: Patient, context: RowActionContext<Patient>) => {
+    console.log(`Row activated (${context.triggerType}):`, dataItem);
+    // Execute consumer action (e.g., open dialog, router.push, etc.)
+  },
+});
+</script>
+```
+
+## Integrating with `useGridA11y`
+
+When combining `useGridA11y` (for `ArrowUp`/`ArrowDown` row focus navigation) with `useGridRowAction` (for `Enter`/`Space` row activation), delegate both handlers in a single `@keydown` listener:
+
+```vue
+<template>
+  <Grid
+    ref="gridRef"
+    :data-items="patients"
+    :columns="columns"
+    @rowclick="handleRowClick"
+    @keydown="handleKeyDown"
+  />
+</template>
+
+<script setup lang="ts">
+import { onMounted, ref } from "vue";
+import { Grid } from "@progress/kendo-vue-grid";
+import { useGridA11y, useGridRowAction } from "@featherk/composables";
+
+const gridRef = ref(null);
+const patients = ref([{ id: 1, name: "Alice Johnson" }]);
+
+const { handleGridKeyDown, initA11y } = useGridA11y(gridRef);
+const { handleRowClick, handleRowKeyDown } = useGridRowAction({
+  dataItems: patients,
+  onRowAction: (patient) => {
+    // Perform row action
+  },
+});
+
+// Delegate keydown to both composable handlers
+const handleKeyDown = (event: KeyboardEvent) => {
+  handleGridKeyDown(event);
+  handleRowKeyDown(event);
+};
+
+onMounted(() => {
+  initA11y();
+});
+</script>
+```
+
+## Options Reference
+
+`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. |
+
+## Returns Reference
+
+`useGridRowAction` returns an object containing:
+
+| 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. |
+
+## 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. |
+
+## Default Ignored Selectors
+
+The following elements and interactive controls are automatically ignored by default:
+
+- `button`, `a`, `input`, `select`, `textarea`
+- `[role="button"]`, `[role="checkbox"]`, `[role="link"]`, `[role="menuitem"]`, `[role="option"]`
+- `.k-checkbox`, `.k-button`, `.k-dropdown`, `.k-picker`, `.k-hierarchy-cell`, `.k-grid-header-menu`, `.k-column-menu`

package/package.json

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