feat: add setDomFocus argument to focusItem methods

Author: lukasbach

next-release-notes.md

@@ -1,6 +1,5 @@
-<!--
-### Breaking Changes
 ### Features
-### Bug Fixes and Improvements
-### Other Changes
--->
+
+- Add `setDomFocus` argument to focus-item methods to provide an escape hatch to set the focus state of an item in RCT
+  without updating the DOM focus. This defaults to true in all existing methods to maintain the current behavior if
+  it is absent.

packages/core/src/controlledEnvironment/useControlledTreeEnvironmentProps.ts

@@ -45,8 +45,8 @@ export const useControlledTreeEnvironmentProps = ({
   const onFocusItemHandler = useCallback<
     Required<TreeChangeHandlers>['onFocusItem']
   >(
-    (item, treeId) => {
-      if (autoFocus ?? true) {
+    (item, treeId, setDomFocus = true) => {
+      if ((autoFocus ?? true) && setDomFocus) {
         const newItem = getDocument()?.querySelector(
           `[data-rct-tree="${treeId}"] [data-rct-item-id="${item.index}"]`
         );

packages/core/src/environmentActions/EnvironmentActionsProvider.tsx

@@ -76,8 +76,8 @@ export const EnvironmentActionsProvider = React.forwardRef<
   );
 
   const focusItem = useCallback(
-    (itemId: TreeItemIndex, treeId: string) => {
-      onFocusItem?.(items[itemId], treeId);
+    (itemId: TreeItemIndex, treeId: string, setDomFocus = true) => {
+      onFocusItem?.(items[itemId], treeId, setDomFocus);
     },
     [items, onFocusItem]
   );

packages/core/src/treeActions/TreeActionsProvider.tsx

@@ -1,6 +1,7 @@
 import * as React from 'react';
 import { PropsWithChildren, useMemo } from 'react';
 import {
+  TreeChangeActions,
   TreeChangeActionsContextProps,
   TreeItemIndex,
   TreeRef,
@@ -26,7 +27,7 @@ export const TreeActionsProvider = React.forwardRef<
 
   // TODO change tree childs to use actions rather than output events where possible
   // TODO maybe replace with stable handlers
-  const actions = useMemo(
+  const actions = useMemo<TreeChangeActions>(
     () => ({
       abortRenamingItem(): void {
         tree.setRenamingItem(null);
@@ -43,8 +44,8 @@ export const TreeActionsProvider = React.forwardRef<
       expandItem(itemId: TreeItemIndex): void {
         envActions.expandItem(itemId, tree.treeId);
       },
-      focusItem(itemId: TreeItemIndex): void {
-        envActions.focusItem(itemId, tree.treeId);
+      focusItem(itemId: TreeItemIndex, setDomFocus = true): void {
+        envActions.focusItem(itemId, tree.treeId, setDomFocus);
       },
       focusTree(autoFocus = true): void {
         envActions.focusTree(tree.treeId, autoFocus);

packages/core/src/treeItem/useTreeItemRenderContext.ts

@@ -119,8 +119,8 @@ export const useTreeItemRenderContext = (item?: TreeItem) => {
       stopRenamingItem: () => {
         setRenamingItem(null);
       },
-      focusItem: () => {
-        environment.onFocusItem?.(item, treeId);
+      focusItem: (setDomFocus = true) => {
+        environment.onFocusItem?.(item, treeId, setDomFocus);
       },
       startDragging: () => {
         let selectedItems = viewState?.selectedItems ?? [];

packages/core/src/types.ts

@@ -35,7 +35,9 @@ export interface TreeItemActions {
   addToSelectedItems: () => void;
   selectUpTo: (overrideOldSelection?: boolean) => void;
   startDragging: () => void;
-  focusItem: () => void;
+
+  /** @param setDomFocus - Defaults to true. */
+  focusItem: (setDomFocus?: boolean) => void;
   // toggleSelectedState: () => void;
 }
 
@@ -216,7 +218,11 @@ export interface TreeChangeHandlers<T = any> {
   onCollapseItem?: (item: TreeItem<T>, treeId: string) => void;
   onExpandItem?: (item: TreeItem<T>, treeId: string) => void;
   onSelectItems?: (items: TreeItemIndex[], treeId: string) => void; // TODO TreeItem instead of just index
-  onFocusItem?: (item: TreeItem<T>, treeId: string) => void;
+  onFocusItem?: (
+    item: TreeItem<T>,
+    treeId: string,
+    setDomFocus?: boolean
+  ) => void;
   onDrop?: (items: TreeItem<T>[], target: DraggingPosition) => void;
   onPrimaryAction?: (items: TreeItem<T>, treeId: string) => void;
   onRegisterTree?: (tree: TreeConfiguration) => void;
@@ -234,7 +240,14 @@ export interface TreeEnvironmentChangeActions {
   selectItems: (itemsIds: TreeItemIndex[], treeId: string) => void;
   toggleItemSelectStatus: (itemId: TreeItemIndex, treeId: string) => void;
   invokePrimaryAction: (itemId: TreeItemIndex, treeID: string) => void;
-  focusItem: (itemId: TreeItemIndex, treeId: string) => void;
+
+  /** @param setDomFocus - Defaults to true. */
+  focusItem: (
+    itemId: TreeItemIndex,
+    treeId: string,
+    setDomFocus?: boolean
+  ) => void;
+
   moveFocusUp: (treeId: string) => void;
   moveFocusDown: (treeId: string) => void;
   startProgrammaticDrag: () => void;
@@ -396,7 +409,10 @@ export interface TreeChangeActions {
   toggleItemExpandedState: (itemId: TreeItemIndex) => void;
   selectItems: (itemsIds: TreeItemIndex[]) => void;
   toggleItemSelectStatus: (itemId: TreeItemIndex) => void;
-  focusItem: (itemId: TreeItemIndex) => void;
+
+  /** @param setDomFocus - Defaults to true. */
+  focusItem: (itemId: TreeItemIndex, setDomFocus?: boolean) => void;
+
   moveFocusUp: () => void;
   moveFocusDown: () => void;
   invokePrimaryAction: (itemId: TreeItemIndex) => void;