[TreeView] Add public API and expose focus method

docs/data/pages.ts

@@ -486,6 +486,7 @@ const pages: MuiPage[] = [
           { pathname: '/x/react-tree-view/simple-tree-view/selection' },
           { pathname: '/x/react-tree-view/simple-tree-view/expansion' },
           { pathname: '/x/react-tree-view/simple-tree-view/customization' },
+          { pathname: '/x/react-tree-view/simple-tree-view/focus' },
         ],
       },
       {

docs/data/tree-view/simple-tree-view/focus/FocusedSimpleTreeView.js

@@ -0,0 +1,40 @@
+import * as React from 'react';
+import Box from '@mui/material/Box';
+import Button from '@mui/material/Button';
+import { SimpleTreeView } from '@mui/x-tree-view/SimpleTreeView';
+import { TreeItem } from '@mui/x-tree-view/TreeItem';
+import { useTreeViewApiRef } from '@mui/x-tree-view/hooks/useTreeViewApiRef';
+
+export default function FocusedSimpleTreeView() {
+  const apiRef = useTreeViewApiRef();
+  const handleButtonClick = (e) => {
+    apiRef.current?.focusNode(e, 'pickers');
+  };
+
+  return (
+    <Box sx={{ flexGrow: 1, maxWidth: 400 }}>
+      <Box sx={{ mb: 1 }}>
+        <Button onClick={handleButtonClick}>focus pickers node</Button>
+      </Box>
+      <Box sx={{ minHeight: 264, flexGrow: 1 }}>
+        <SimpleTreeView {...{ apiRef }}>
+          <TreeItem nodeId="grid" label="Data Grid">
+            <TreeItem nodeId="grid-community" label="@mui/x-data-grid" />
+            <TreeItem nodeId="grid-pro" label="@mui/x-data-grid-pro" />
+            <TreeItem nodeId="grid-premium" label="@mui/x-data-grid-premium" />
+          </TreeItem>
+          <TreeItem nodeId="pickers" label="Date and Time Pickers">
+            <TreeItem nodeId="pickers-community" label="@mui/x-date-pickers" />
+            <TreeItem nodeId="pickers-pro" label="@mui/x-date-pickers-pro" />
+          </TreeItem>
+          <TreeItem nodeId="charts" label="Charts">
+            <TreeItem nodeId="charts-community" label="@mui/x-charts" />
+          </TreeItem>
+          <TreeItem nodeId="tree-view" label="Tree View">
+            <TreeItem nodeId="tree-view-community" label="@mui/x-tree-view" />
+          </TreeItem>
+        </SimpleTreeView>
+      </Box>
+    </Box>
+  );
+}

docs/data/tree-view/simple-tree-view/focus/FocusedSimpleTreeView.tsx

@@ -0,0 +1,40 @@
+import * as React from 'react';
+import Box from '@mui/material/Box';
+import Button from '@mui/material/Button';
+import { SimpleTreeView } from '@mui/x-tree-view/SimpleTreeView';
+import { TreeItem } from '@mui/x-tree-view/TreeItem';
+import { useTreeViewApiRef } from '@mui/x-tree-view/hooks/useTreeViewApiRef';
+
+export default function FocusedSimpleTreeView() {
+  const apiRef = useTreeViewApiRef();
+  const handleButtonClick = (e: React.SyntheticEvent) => {
+    apiRef.current?.focusNode(e, 'pickers');
+  };
+
+  return (
+    <Box sx={{ flexGrow: 1, maxWidth: 400 }}>
+      <Box sx={{ mb: 1 }}>
+        <Button onClick={handleButtonClick}>focus pickers node</Button>
+      </Box>
+      <Box sx={{ minHeight: 264, flexGrow: 1 }}>
+        <SimpleTreeView {...{ apiRef }}>
+          <TreeItem nodeId="grid" label="Data Grid">
+            <TreeItem nodeId="grid-community" label="@mui/x-data-grid" />
+            <TreeItem nodeId="grid-pro" label="@mui/x-data-grid-pro" />
+            <TreeItem nodeId="grid-premium" label="@mui/x-data-grid-premium" />
+          </TreeItem>
+          <TreeItem nodeId="pickers" label="Date and Time Pickers">
+            <TreeItem nodeId="pickers-community" label="@mui/x-date-pickers" />
+            <TreeItem nodeId="pickers-pro" label="@mui/x-date-pickers-pro" />
+          </TreeItem>
+          <TreeItem nodeId="charts" label="Charts">
+            <TreeItem nodeId="charts-community" label="@mui/x-charts" />
+          </TreeItem>
+          <TreeItem nodeId="tree-view" label="Tree View">
+            <TreeItem nodeId="tree-view-community" label="@mui/x-tree-view" />
+          </TreeItem>
+        </SimpleTreeView>
+      </Box>
+    </Box>
+  );
+}

docs/data/tree-view/simple-tree-view/focus/focus.md

@@ -0,0 +1,16 @@
+---
+productId: x-tree-view
+title: Simple Tree View - Focus
+components: SimpleTreeView, TreeItem
+packageName: '@mui/x-tree-view'
+githubLabel: 'component: tree view'
+waiAria: https://www.w3.org/WAI/ARIA/apg/patterns/treeview/
+---
+
+# Simple Tree View - Focus
+
+<p class="description">Learn how to focus Tree View items.</p>
+
+## Focus a specific node
+
+{{"demo": "FocusedSimpleTreeView.js"}}

docs/pages/x/api/tree-view/simple-tree-view.json

@@ -93,6 +93,6 @@
   "forwardsRefTo": "HTMLUListElement",
   "filename": "/packages/x-tree-view/src/SimpleTreeView/SimpleTreeView.tsx",
   "inheritance": null,
-  "demos": "<ul><li><a href=\"/x/react-tree-view/getting-started/\">Tree View - Getting Started</a></li>\n<li><a href=\"/x/react-tree-view/simple-tree-view/customization/\">Simple Tree View - Customization</a></li>\n<li><a href=\"/x/react-tree-view/simple-tree-view/expansion/\">Simple Tree View - Expansion</a></li>\n<li><a href=\"/x/react-tree-view/simple-tree-view/items/\">Simple Tree View - Items</a></li>\n<li><a href=\"/x/react-tree-view/simple-tree-view/selection/\">Simple Tree View - Selection</a></li></ul>",
+  "demos": "<ul><li><a href=\"/x/react-tree-view/getting-started/\">Tree View - Getting Started</a></li>\n<li><a href=\"/x/react-tree-view/simple-tree-view/customization/\">Simple Tree View - Customization</a></li>\n<li><a href=\"/x/react-tree-view/simple-tree-view/expansion/\">Simple Tree View - Expansion</a></li>\n<li><a href=\"/x/react-tree-view/simple-tree-view/focus/\">Simple Tree View - Focus</a></li>\n<li><a href=\"/x/react-tree-view/simple-tree-view/items/\">Simple Tree View - Items</a></li>\n<li><a href=\"/x/react-tree-view/simple-tree-view/selection/\">Simple Tree View - Selection</a></li></ul>",
   "cssComponent": false
 }

docs/pages/x/api/tree-view/tree-item.json

@@ -104,6 +104,6 @@
   "forwardsRefTo": "HTMLLIElement",
   "filename": "/packages/x-tree-view/src/TreeItem/TreeItem.tsx",
   "inheritance": null,
-  "demos": "<ul><li><a href=\"/x/react-tree-view/getting-started/\">Tree View - Getting Started</a></li>\n<li><a href=\"/x/react-tree-view/rich-tree-view/expansion/\">Rich Tree View - Expansion</a></li>\n<li><a href=\"/x/react-tree-view/rich-tree-view/items/\">Rich Tree View - Items</a></li>\n<li><a href=\"/x/react-tree-view/rich-tree-view/selection/\">Rich Tree View - Selection</a></li>\n<li><a href=\"/x/react-tree-view/simple-tree-view/customization/\">Simple Tree View - Customization</a></li>\n<li><a href=\"/x/react-tree-view/simple-tree-view/expansion/\">Simple Tree View - Expansion</a></li>\n<li><a href=\"/x/react-tree-view/simple-tree-view/items/\">Simple Tree View - Items</a></li>\n<li><a href=\"/x/react-tree-view/simple-tree-view/selection/\">Simple Tree View - Selection</a></li></ul>",
+  "demos": "<ul><li><a href=\"/x/react-tree-view/getting-started/\">Tree View - Getting Started</a></li>\n<li><a href=\"/x/react-tree-view/rich-tree-view/expansion/\">Rich Tree View - Expansion</a></li>\n<li><a href=\"/x/react-tree-view/rich-tree-view/items/\">Rich Tree View - Items</a></li>\n<li><a href=\"/x/react-tree-view/rich-tree-view/selection/\">Rich Tree View - Selection</a></li>\n<li><a href=\"/x/react-tree-view/simple-tree-view/customization/\">Simple Tree View - Customization</a></li>\n<li><a href=\"/x/react-tree-view/simple-tree-view/expansion/\">Simple Tree View - Expansion</a></li>\n<li><a href=\"/x/react-tree-view/simple-tree-view/focus/\">Simple Tree View - Focus</a></li>\n<li><a href=\"/x/react-tree-view/simple-tree-view/items/\">Simple Tree View - Items</a></li>\n<li><a href=\"/x/react-tree-view/simple-tree-view/selection/\">Simple Tree View - Selection</a></li></ul>",
   "cssComponent": false
 }

docs/pages/x/react-tree-view/simple-tree-view/focus.js

@@ -0,0 +1,7 @@
+import * as React from 'react';
+import MarkdownDocs from 'docs/src/modules/components/MarkdownDocs';
+import * as pageProps from 'docsx/data/tree-view/simple-tree-view/focus/focus.md?@mui/markdown';
+
+export default function Page() {
+  return <MarkdownDocs {...pageProps} />;
+}

packages/x-tree-view/src/hooks/index.ts

@@ -0,0 +1 @@
+export { useTreeViewApiRef } from './useTreeViewApiRef';

packages/x-tree-view/src/hooks/useTreeViewApiRef.tsx

@@ -0,0 +1,10 @@
+import * as React from 'react';
+import { TreeViewAnyPluginSignature, TreeViewUsedPublicAPI } from '../internals/models';
+
+/**
+ * Hook that instantiate a [[TreeViewApiRef]].
+ */
+export const useTreeViewApiRef = <
+  T extends TreeViewAnyPluginSignature,
+  Api extends TreeViewUsedPublicAPI<T>,
+>() => React.useRef({}) as React.MutableRefObject<Api>;

packages/x-tree-view/src/index.ts

@@ -6,3 +6,5 @@ export { unstable_resetCleanupTracking } from './internals/hooks/useInstanceEven
 
 export * from './models';
 export * from './icons';
+
+export * from './hooks';

packages/x-tree-view/src/internals/models/helpers.ts

@@ -35,6 +35,7 @@ export type ConvertPluginsIntoSignatures<TPlugins extends readonly any[]> =
 export interface MergePlugins<TPlugins extends readonly any[]> {
   state: MergePluginsProperty<TPlugins, 'state'>;
   instance: MergePluginsProperty<TPlugins, 'instance'>;
+  publicAPI: MergePluginsProperty<TPlugins, 'publicAPI'>;
   params: MergePluginsProperty<TPlugins, 'params'>;
   defaultizedParams: MergePluginsProperty<TPlugins, 'defaultizedParams'>;
   dependantPlugins: MergePluginsProperty<TPlugins, 'dependantPlugins'>;

packages/x-tree-view/src/internals/models/plugin.ts

@@ -8,6 +8,7 @@ import type { TreeItemProps } from '../../TreeItem';
 
 export interface TreeViewPluginOptions<TSignature extends TreeViewAnyPluginSignature> {
   instance: TreeViewUsedInstance<TSignature>;
+  publicAPI: TreeViewUsedPublicAPI<TSignature>;
   params: TreeViewUsedDefaultizedParams<TSignature>;
   state: TreeViewUsedState<TSignature>;
   slots: TSignature['slots'];
@@ -36,6 +37,7 @@ export type TreeViewPluginSignature<
     params?: {};
     defaultizedParams?: {};
     instance?: {};
+    publicAPI?: {};
     events?: { [key in keyof T['events']]: TreeViewEventLookupElement };
     state?: {};
     contextValue?: {};
@@ -48,6 +50,7 @@ export type TreeViewPluginSignature<
   params: T extends { params: {} } ? T['params'] : {};
   defaultizedParams: T extends { defaultizedParams: {} } ? T['defaultizedParams'] : {};
   instance: T extends { instance: {} } ? T['instance'] : {};
+  publicAPI: T extends { publicAPI: {} } ? T['publicAPI'] : {};
   events: T extends { events: {} } ? T['events'] : {};
   state: T extends { state: {} } ? T['state'] : {};
   contextValue: T extends { contextValue: {} } ? T['contextValue'] : {};
@@ -74,6 +77,7 @@ export type TreeViewAnyPluginSignature = {
   slots: any;
   slotProps: any;
   models: any;
+  publicAPI: any;
 };
 
 type TreeViewUsedPlugins<TSignature extends TreeViewAnyPluginSignature> = [
@@ -97,6 +101,15 @@ export type TreeViewUsedInstance<TSignature extends TreeViewAnyPluginSignature>
       $$signature: TSignature;
     };
 
+export type TreeViewUsedPublicAPI<TSignature extends TreeViewAnyPluginSignature> =
+  TSignature['publicAPI'] &
+    MergePluginsProperty<TreeViewUsedPlugins<TSignature>, 'publicAPI'> & {
+      /**
+       * Private property only defined in TypeScript to be able to access the plugin signature from the publicAPI object.
+       */
+      $$signature: TSignature;
+    };
+
 type TreeViewUsedState<TSignature extends TreeViewAnyPluginSignature> = TSignature['state'] &
   MergePluginsProperty<TreeViewUsedPlugins<TSignature>, 'state'>;
 

packages/x-tree-view/src/internals/models/treeView.ts

@@ -29,3 +29,6 @@ export interface TreeViewModel<TValue> {
 
 export type TreeViewInstance<TSignatures extends readonly TreeViewAnyPluginSignature[]> =
   MergePluginsProperty<TSignatures, 'instance'>;
+
+export type TreeViewPublicAPI<TSignatures extends readonly TreeViewAnyPluginSignature[]> =
+  MergePluginsProperty<TSignatures, 'publicAPI'>;

packages/x-tree-view/src/internals/plugins/useTreeViewFocus/useTreeViewFocus.ts

@@ -3,32 +3,43 @@ import useEventCallback from '@mui/utils/useEventCallback';
 import { EventHandlers } from '@mui/base/utils';
 import ownerDocument from '@mui/utils/ownerDocument';
 import { TreeViewPlugin } from '../../models';
-import { populateInstance } from '../../useTreeView/useTreeView.utils';
+import { populateInstance, populatePublicAPI } from '../../useTreeView/useTreeView.utils';
 import { UseTreeViewFocusSignature } from './useTreeViewFocus.types';
 import { useInstanceEventHandler } from '../../hooks/useInstanceEventHandler';
 
 export const useTreeViewFocus: TreeViewPlugin<UseTreeViewFocusSignature> = ({
   instance,
+  publicAPI,
   params,
   state,
   setState,
   models,
   rootRef,
 }) => {
+  const focusedNodeId = state.focusedNodeId;
   const setFocusedNodeId = useEventCallback((nodeId: React.SetStateAction<string | null>) => {
-    const cleanNodeId = typeof nodeId === 'function' ? nodeId(state.focusedNodeId) : nodeId;
-    setState((prevState) => ({ ...prevState, focusedNodeId: cleanNodeId }));
+    const cleanNodeId = typeof nodeId === 'function' ? nodeId(focusedNodeId) : nodeId;
+    if (focusedNodeId !== cleanNodeId) {
+      setState((prevState) => ({ ...prevState, focusedNodeId: cleanNodeId }));
+    }
   });
 
+  const isTreeFocused = React.useCallback(
+    () => rootRef.current === document.activeElement,
+    [rootRef],
+  );
+
   const isNodeFocused = React.useCallback(
-    (nodeId: string) => state.focusedNodeId === nodeId,
-    [state.focusedNodeId],
+    (nodeId: string) => focusedNodeId === nodeId && isTreeFocused(),
+    [focusedNodeId, isTreeFocused],
   );
 
   const focusNode = useEventCallback((event: React.SyntheticEvent, nodeId: string | null) => {
     if (nodeId) {
+      if (!isTreeFocused()) {
+        instance.focusRoot();
+      }
       setFocusedNodeId(nodeId);
-
       if (params.onNodeFocus) {
         params.onNodeFocus(event, nodeId);
       }
@@ -45,6 +56,10 @@ export const useTreeViewFocus: TreeViewPlugin<UseTreeViewFocusSignature> = ({
     focusRoot,
   });
 
+  populatePublicAPI<UseTreeViewFocusSignature>(publicAPI, {
+    focusNode,
+  });
+
   useInstanceEventHandler(instance, 'removeNode', ({ id }) => {
     setFocusedNodeId((oldFocusedNodeId) => {
       if (
@@ -60,7 +75,6 @@ export const useTreeViewFocus: TreeViewPlugin<UseTreeViewFocusSignature> = ({
   const createHandleFocus =
     (otherHandlers: EventHandlers) => (event: React.FocusEvent<HTMLUListElement>) => {
       otherHandlers.onFocus?.(event);
-
       // if the event bubbled (which is React specific) we don't want to steal focus
       if (event.target === event.currentTarget) {
         const isNodeVisible = (nodeId: string) => {
@@ -69,7 +83,9 @@ export const useTreeViewFocus: TreeViewPlugin<UseTreeViewFocusSignature> = ({
         };
 
         let nodeToFocusId: string | null | undefined;
-        if (Array.isArray(models.selectedNodes.value)) {
+        if (focusedNodeId) {
+          nodeToFocusId = focusedNodeId;
+        } else if (Array.isArray(models.selectedNodes.value)) {
           nodeToFocusId = models.selectedNodes.value.find(isNodeVisible);
         } else if (
           models.selectedNodes.value != null &&
@@ -81,7 +97,6 @@ export const useTreeViewFocus: TreeViewPlugin<UseTreeViewFocusSignature> = ({
         if (nodeToFocusId == null) {
           nodeToFocusId = instance.getNavigableChildrenIds(null)[0];
         }
-
         instance.focusNode(event, nodeToFocusId);
       }
     };
@@ -92,7 +107,7 @@ export const useTreeViewFocus: TreeViewPlugin<UseTreeViewFocusSignature> = ({
       setFocusedNodeId(null);
     };
 
-  const focusedNode = instance.getNode(state.focusedNodeId!);
+  const focusedNode = instance.getNode(focusedNodeId!);
   const activeDescendant = focusedNode
     ? instance.getTreeItemId(focusedNode.id, focusedNode.idAttribute)
     : null;

packages/x-tree-view/src/internals/plugins/useTreeViewFocus/useTreeViewFocus.types.ts

@@ -10,6 +10,9 @@ export interface UseTreeViewFocusInstance {
   focusNode: (event: React.SyntheticEvent, nodeId: string | null) => void;
   focusRoot: () => void;
 }
+export interface UseTreeViewFocusPublicAPI {
+  focusNode: (event: React.SyntheticEvent, nodeId: string | null) => void;
+}
 
 export interface UseTreeViewFocusParameters {
   /**
@@ -31,6 +34,7 @@ export type UseTreeViewFocusSignature = TreeViewPluginSignature<{
   params: UseTreeViewFocusParameters;
   defaultizedParams: UseTreeViewFocusDefaultizedParameters;
   instance: UseTreeViewFocusInstance;
+  publicAPI: UseTreeViewFocusPublicAPI;
   state: UseTreeViewFocusState;
   dependantPlugins: [
     UseTreeViewIdSignature,

packages/x-tree-view/src/internals/useTreeView/useTreeView.ts

@@ -7,6 +7,7 @@ import {
   TreeViewPlugin,
   ConvertPluginsIntoSignatures,
   MergePluginsProperty,
+  TreeViewPublicAPI,
 } from '../models';
 import {
   UseTreeViewDefaultizedParameters,
@@ -18,6 +19,18 @@ import { useTreeViewModels } from './useTreeViewModels';
 import { TreeViewContextValue } from '../TreeViewProvider';
 import { TREE_VIEW_CORE_PLUGINS } from '../corePlugins';
 
+export function useTreeViewApiInitialization<T>(
+  inputApiRef: React.MutableRefObject<T> | undefined,
+): React.MutableRefObject<T> {
+  const fallbackPublicApiRef = React.useRef({}) as React.MutableRefObject<T>;
+
+  if (inputApiRef) {
+    return inputApiRef;
+  }
+
+  return fallbackPublicApiRef;
+}
+
 export const useTreeView = <Plugins extends readonly TreeViewPlugin<TreeViewAnyPluginSignature>[]>(
   inParams: UseTreeViewParameters<Plugins>,
 ): UseTreeViewReturnValue<ConvertPluginsIntoSignatures<Plugins>> => {
@@ -40,6 +53,10 @@ export const useTreeView = <Plugins extends readonly TreeViewPlugin<TreeViewAnyP
     {} as TreeViewInstance<Signatures>,
   );
   const instance = instanceRef.current as TreeViewInstance<Signatures>;
+
+  const publicAPIRef = useTreeViewApiInitialization<TreeViewPublicAPI<Signatures>>(inParams.apiRef);
+  const publicAPI = publicAPIRef.current as TreeViewPublicAPI<Signatures>;
+
   const innerRootRef = React.useRef(null);
   const handleRootRef = useForkRef(innerRootRef, inParams.rootRef);
 
@@ -68,6 +85,7 @@ export const useTreeView = <Plugins extends readonly TreeViewPlugin<TreeViewAnyP
     const pluginResponse =
       plugin({
         instance,
+        publicAPI,
         params,
         slots: params.slots,
         slotProps: params.slotProps,

packages/x-tree-view/src/internals/useTreeView/useTreeView.types.ts

@@ -17,6 +17,7 @@ export type UseTreeViewParameters<
 export interface UseTreeViewBaseParameters<
   TPlugins extends readonly TreeViewPlugin<TreeViewAnyPluginSignature>[],
 > {
+  apiRef?: React.MutableRefObject<{}> | undefined;
   rootRef?: React.Ref<HTMLUListElement> | undefined;
   plugins: TPlugins;
   slots: MergePluginsProperty<ConvertPluginsIntoSignatures<TPlugins>, 'slots'>;