[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'>;