feat(AnalyticalTable): introduce useF2CellEdit plugin hook

Lukas742 · Lukas742 · commit 8e1c00110b7a · 2025-08-18T16:35:27.000+02:00
diff --git a/packages/main/src/components/AnalyticalTable/hooks/useKeyboardNavigation.ts b/packages/main/src/components/AnalyticalTable/hooks/useKeyboardNavigation.ts
@@ -1,9 +1,20 @@
+import type { KeyboardEventHandler } from 'react';
 import { useCallback, useEffect, useRef } from 'react';
 import { actions } from 'react-table';
 import type { ColumnType, ReactTableHooks, TableInstance } from '../types/index.js';
 import { getLeafHeaders } from '../util/index.js';
 
 const CELL_DATA_ATTRIBUTES = ['visibleColumnIndex', 'columnIndex', 'rowIndex', 'visibleRowIndex'];
+const NAVIGATION_KEYS = new Set([
+  'End',
+  'Home',
+  'PageDown',
+  'PageUp',
+  'ArrowRight',
+  'ArrowLeft',
+  'ArrowDown',
+  'ArrowUp',
+]);
 
 const getFirstVisibleCell = (target, currentlyFocusedCell, noData) => {
   if (
@@ -175,9 +186,13 @@ const useGetTableProps = (
           currentlyFocusedCell.current.dataset.rowIndex ?? currentlyFocusedCell.current.dataset.subcomponentRowIndex,
           10,
         );
+
+        if (NAVIGATION_KEYS.has(e.key)) {
+          e.preventDefault();
+        }
+
         switch (e.key) {
           case 'End': {
-            e.preventDefault();
             const visibleColumns = tableRef.current.querySelector(
               `div[data-component-name="AnalyticalTableHeaderRow"]`,
             ).children;
@@ -200,15 +215,13 @@ const useGetTableProps = (
             break;
           }
           case 'Home': {
-            e.preventDefault();
             const newElement = tableRef.current.querySelector(
               `div[data-visible-column-index="0"][data-row-index="${rowIndex}"]`,
             );
             setFocus(currentlyFocusedCell, newElement);
             break;
           }
           case 'PageDown': {
-            e.preventDefault();
             if (currentlyFocusedCell.current.dataset.rowIndex === '0') {
               const newElement = tableRef.current.querySelector(
                 `div[data-column-index="${columnIndex}"][data-row-index="${rowIndex + 1}"]`,
@@ -225,7 +238,6 @@ const useGetTableProps = (
             break;
           }
           case 'PageUp': {
-            e.preventDefault();
             if (currentlyFocusedCell.current.dataset.rowIndex <= '1') {
               const newElement = tableRef.current.querySelector(
                 `div[data-column-index="${columnIndex}"][data-row-index="0"]`,
@@ -240,7 +252,6 @@ const useGetTableProps = (
             break;
           }
           case 'ArrowRight': {
-            e.preventDefault();
             if (isActiveItemInSubComponent) {
               navigateFromActiveSubCompItem(currentlyFocusedCell, e);
               return;
@@ -256,7 +267,6 @@ const useGetTableProps = (
             break;
           }
           case 'ArrowLeft': {
-            e.preventDefault();
             if (isActiveItemInSubComponent) {
               navigateFromActiveSubCompItem(currentlyFocusedCell, e);
               return;
@@ -272,7 +282,6 @@ const useGetTableProps = (
             break;
           }
           case 'ArrowDown': {
-            e.preventDefault();
             if (isActiveItemInSubComponent) {
               navigateFromActiveSubCompItem(currentlyFocusedCell, e);
               return;
@@ -296,7 +305,6 @@ const useGetTableProps = (
             break;
           }
           case 'ArrowUp': {
-            e.preventDefault();
             if (isActiveItemInSubComponent) {
               navigateFromActiveSubCompItem(currentlyFocusedCell, e);
               return;
@@ -332,11 +340,25 @@ const useGetTableProps = (
   if (showOverlay) {
     return tableProps;
   }
+
+  // keyboard nav is only enabled if the table is not in edit mode
+  const handleEditModeKeyDown: KeyboardEventHandler<HTMLDivElement> = (e) => {
+    if (typeof tableProps.onKeyDown === 'function') {
+      tableProps.onKeyDown(e);
+    }
+    if (NAVIGATION_KEYS.has(e.key)) {
+      e.preventDefault();
+    }
+  };
+
   return [
     tableProps,
     {
       onFocus: onTableFocus,
-      onKeyDown: onKeyboardNavigation,
+      onKeyDown:
+        state.cellContentTabIndex === -1 || state.cellContentTabIndex == null
+          ? onKeyboardNavigation
+          : handleEditModeKeyDown,
       onBlur: onTableBlur,
     },
   ];
diff --git a/packages/main/src/components/AnalyticalTable/pluginHooks/AnalyticalTableHooks.ts b/packages/main/src/components/AnalyticalTable/pluginHooks/AnalyticalTableHooks.ts
@@ -1,4 +1,5 @@
 import { useAnnounceEmptyCells } from './useAnnounceEmptyCells.js';
+import { useF2CellEdit } from './useF2CellEdit.js';
 import { useIndeterminateRowSelection } from './useIndeterminateRowSelection.js';
 import { useManualRowSelect } from './useManualRowSelect.js';
 import { useOnColumnResize } from './useOnColumnResize.js';
@@ -7,6 +8,7 @@ import { useRowDisableSelection } from './useRowDisableSelection.js';
 
 export {
   useAnnounceEmptyCells,
+  useF2CellEdit,
   useIndeterminateRowSelection,
   useManualRowSelect,
   useOnColumnResize,
diff --git a/packages/main/src/components/AnalyticalTable/pluginHooks/useF2CellEdit.ts b/packages/main/src/components/AnalyticalTable/pluginHooks/useF2CellEdit.ts
@@ -0,0 +1,131 @@
+import type { Ui5DomRef } from '@ui5/webcomponents-react-base';
+import { useI18nBundle } from '@ui5/webcomponents-react-base';
+import type { FocusEventHandler, KeyboardEventHandler } from 'react';
+import { useCallback } from 'react';
+import { INCLUDES_X } from '../../../i18n/i18n-defaults.js';
+import type { ReactTableHooks, TableInstance } from '../types/index.js';
+
+//todo: how to export
+export const useEditModeCallbackRef = (props) => {
+  const cellContentTabIndex =
+    props.state.cellContentTabIndex === -1 || props.state.cellContentTabIndex === undefined ? '-1' : '0';
+  return useCallback(
+    (node: HTMLElement) => {
+      if (node) {
+        if (node.tagName.startsWith('UI5')) {
+          void (node as Ui5DomRef)
+            .getFocusDomRefAsync()
+            .then((focusNode) => focusNode.setAttribute('tabindex', cellContentTabIndex))
+            .catch(() => {
+              // fail silently
+            });
+        } else {
+          node.setAttribute('tabindex', cellContentTabIndex);
+        }
+      }
+    },
+    [cellContentTabIndex],
+  );
+};
+
+//todo: memoize everything - getCellProps is called often
+export const useF2CellEdit = (hooks: ReactTableHooks) => {
+  const i18nBundle = useI18nBundle('@ui5/webcomponents-react');
+
+  const setCellProps = useCallback(
+    (props, { cell, instance }: { cell: Record<string, any>; instance: TableInstance }) => {
+      const { dispatch } = instance;
+      const { interactiveElementName } = cell.column;
+      const inputName =
+        typeof interactiveElementName === 'function' ? interactiveElementName(cell) : interactiveElementName;
+      const ariaLabel =
+        (interactiveElementName ? i18nBundle.getText(INCLUDES_X, inputName) : '') + ' ' + props['aria-label'];
+
+      const handleKeyDown: KeyboardEventHandler<HTMLDivElement> = (e) => {
+        if (e.key === 'F2') {
+          e.preventDefault();
+          if (e.currentTarget === e.target && interactiveElementName) {
+            const interactiveElement = findFirstFocusableInside(e.target as HTMLElement);
+            if (interactiveElement) {
+              dispatch({ type: 'CELL_CONTENT_TAB_INDEX', payload: 0 });
+              e.currentTarget.tabIndex = -1;
+              requestAnimationFrame(() => {
+                interactiveElement.focus();
+              });
+            }
+          }
+          if (e.currentTarget !== e.target) {
+            dispatch({ type: 'CELL_CONTENT_TAB_INDEX', payload: -1 });
+            e.currentTarget.tabIndex = 0;
+            e.currentTarget.focus();
+          }
+        }
+      };
+
+      const handleFocus: FocusEventHandler<HTMLDivElement> = (e) => {
+        if (typeof props.onFocus === 'function') {
+          props.onFocus(e);
+        }
+
+        if (e.currentTarget !== e.target) {
+          dispatch({ type: 'CELL_CONTENT_TAB_INDEX', payload: 0 });
+        } else {
+          dispatch({ type: 'CELL_CONTENT_TAB_INDEX', payload: -1 });
+        }
+      };
+
+      return [props, { onKeyDown: handleKeyDown, onFocus: handleFocus, 'aria-label': ariaLabel }];
+    },
+    [i18nBundle],
+  );
+
+  hooks.getCellProps.push(setCellProps);
+  hooks.stateReducers.push(stateReducer);
+};
+useF2CellEdit.pluginName = 'useF2CellEdit';
+
+const stateReducer: TableInstance['stateReducer'] = (state, action, _prevState) => {
+  const { payload, type } = action;
+
+  if (type === 'CELL_CONTENT_TAB_INDEX') {
+    return { ...state, cellContentTabIndex: payload };
+  }
+  return state;
+};
+
+function findFirstFocusableInside(element: HTMLElement) {
+  if (!element) return null;
+
+  function recursiveFindInteractiveElement(el) {
+    for (const child of el.children) {
+      const style = getComputedStyle(child);
+      if (child.disabled || style.display === 'none' || style.visibility === 'hidden') {
+        continue;
+      }
+
+      const focusableSelectors = [
+        'a[href]',
+        'button',
+        'input',
+        'textarea',
+        'select',
+        '[tabindex]:not([tabindex="-1"])',
+      ];
+
+      if (child.matches(focusableSelectors.join(','))) {
+        return child;
+      }
+
+      if (child.shadowRoot) {
+        const shadowFocusable = recursiveFindInteractiveElement(child.shadowRoot);
+        if (shadowFocusable) return shadowFocusable;
+      }
+
+      const nestedFocusable = recursiveFindInteractiveElement(child);
+      if (nestedFocusable) return nestedFocusable;
+    }
+    return null;
+  }
+
+  return recursiveFindInteractiveElement(element);
+}
diff --git a/packages/main/src/components/AnalyticalTable/types/index.ts b/packages/main/src/components/AnalyticalTable/types/index.ts
@@ -103,7 +103,7 @@ export interface TableInstance {
   disableSortBy?: boolean;
   dispatch?: (action: {
     type: string;
-    payload?: Record<string, unknown> | AnalyticalTableState['popInColumns'] | boolean | string;
+    payload?: Record<string, unknown> | AnalyticalTableState['popInColumns'] | boolean | string | number;
     clientX?: number;
   }) => void;
   expandedDepth?: number;
@@ -319,6 +319,7 @@ export interface AnalyticalTableState {
   interactiveRowsHavePopIn?: boolean;
   tableColResized?: true;
   triggerScroll?: TriggerScrollState;
+  cellContentTabIndex?: number;
 }
 
 interface Filter {
diff --git a/packages/main/src/i18n/messagebundle.properties b/packages/main/src/i18n/messagebundle.properties
@@ -378,7 +378,9 @@ HAS_DETAILS=Has Details
 #XACT: Message Item counter label
 COUNTER=Counter
 
-#ACT: Screen reader announcement text for selection in the SelectDialog component when multi-selection mode is active. The placeholder represents a number.
+#XACT: Screen reader announcement text for selection in the SelectDialog component when multi-selection mode is active. The placeholder represents a number.
 SELECTED_ITEMS=Selected Items {0}
 
+#XACT: Screen reader announcement for table cell that includes interactive element/s. The placeholder is the name of the element (e.g. "Input").
+INCLUDES_X=Includes {0}
 
