feat(react-tree): flat tree supports navigation without useHeadlessFlatTree

change/@fluentui-react-tree-a0c03a32-7116-4e69-9da0-e5d936c3f433.json

@@ -0,0 +1,7 @@
+{
+  "type": "minor",
+  "comment": "feat: FlatTree supports navigation without useHeadlessFlatTree",
+  "packageName": "@fluentui/react-tree",
+  "email": "bernardo.sunderhus@gmail.com",
+  "dependentChangeType": "patch"
+}

packages/react-components/react-tree/etc/react-tree.api.md

@@ -256,6 +256,7 @@ export type TreeItemProps = ComponentProps<Partial<TreeItemSlots>> & {
     value?: TreeItemValue;
     open?: boolean;
     onOpenChange?: (e: TreeItemOpenChangeEvent, data: TreeItemOpenChangeData) => void;
+    parentValue?: TreeItemValue;
 };
 
 // @public (undocumented)
@@ -281,6 +282,7 @@ export type TreeItemValue = string | number;
 export type TreeNavigationData_unstable = {
     target: HTMLElement;
     value: TreeItemValue;
+    parentValue: TreeItemValue | undefined;
 } & ({
     event: React_2.MouseEvent<HTMLElement>;
     type: 'Click';

packages/react-components/react-tree/src/components/FlatTree/useFlatTree.ts

@@ -1,10 +1,70 @@
 import * as React from 'react';
 import { useRootTree } from '../../hooks/useRootTree';
-import { FlatTreeProps, FlatTreeState } from './FlatTree.types';
+import { FlatTreeProps, FlatTreeSlots, FlatTreeState } from './FlatTree.types';
+import { useFlatTreeNavigation } from './useFlatTreeNavigation';
+import { HTMLElementWalker, createHTMLElementWalker } from '../../utils/createHTMLElementWalker';
+import { useFluent_unstable } from '@fluentui/react-shared-contexts';
+import { treeItemFilter } from '../../utils/treeItemFilter';
+import { ExtractSlotProps, slot, useEventCallback, useMergedRefs } from '@fluentui/react-utilities';
+import type { TreeNavigationData_unstable, TreeNavigationEvent_unstable } from '../Tree/Tree.types';
+import { useTreeContext_unstable } from '../../contexts/treeContext';
+import { useSubtree } from '../../hooks/useSubtree';
+
+export const useFlatTree_unstable: (props: FlatTreeProps, ref: React.Ref<HTMLElement>) => FlatTreeState = (
+  props,
+  ref,
+) => {
+  const level = useTreeContext_unstable(ctx => ctx.level);
+  // as level is static, this doesn't break rule of hooks
+  // and if this becomes an issue later on, this can be easily converted
+  // eslint-disable-next-line react-hooks/rules-of-hooks
+  return level > 1 ? useSubFlatTree(props, ref) : useRootFlatTree(props, ref);
+};
+
+function useRootFlatTree(props: FlatTreeProps, ref: React.Ref<HTMLElement>): FlatTreeState {
+  const { navigate, initialize } = useFlatTreeNavigation();
+  const walkerRef = React.useRef<HTMLElementWalker>();
+  const { targetDocument } = useFluent_unstable();
+
+  const initializeWalker = React.useCallback(
+    (root: HTMLElement | null) => {
+      if (root && targetDocument) {
+        walkerRef.current = createHTMLElementWalker(root, targetDocument, treeItemFilter);
+        initialize(walkerRef.current);
+      }
+    },
+    [initialize, targetDocument],
+  );
+
+  const handleNavigation = useEventCallback(
+    (event: TreeNavigationEvent_unstable, data: TreeNavigationData_unstable) => {
+      props.onNavigation?.(event, data);
+      if (walkerRef.current && !event.isDefaultPrevented()) {
+        navigate(data, walkerRef.current);
+      }
+    },
+  );
 
-export const useFlatTree_unstable = (props: FlatTreeProps, ref: React.Ref<HTMLElement>): FlatTreeState => {
   return {
     treeType: 'flat',
-    ...useRootTree(props, ref),
+    ...useRootTree({ ...props, onNavigation: handleNavigation }, useMergedRefs(ref, initializeWalker)),
   };
-};
+}
+
+function useSubFlatTree(props: FlatTreeProps, ref: React.Ref<HTMLElement>): FlatTreeState {
+  if (process.env.NODE_ENV === 'development') {
+    // eslint-disable-next-line no-console
+    console.error(/* #__DE-INDENT__ */ `
+      @fluentui/react-tree [useFlatTree]:
+      Subtrees are not allowed in a FlatTree!
+      You cannot use a <FlatTree> component inside of another <FlatTree> component.
+    `);
+  }
+  return {
+    ...useSubtree(props, ref),
+    open: false,
+    treeType: 'flat',
+    components: { root: React.Fragment },
+    root: slot.always<ExtractSlotProps<FlatTreeSlots['root']>>(undefined, { elementType: React.Fragment }),
+  };
+}

packages/react-components/react-tree/src/components/FlatTree/useFlatTreeNavigation.ts

@@ -1,15 +1,15 @@
 import { useFluent_unstable } from '@fluentui/react-shared-contexts';
 import { useEventCallback } from '@fluentui/react-utilities';
 import { TreeNavigationData_unstable } from '../../Tree';
-import { HeadlessTree, HeadlessTreeItemProps } from '../../utils/createHeadlessTree';
 import { nextTypeAheadElement } from '../../utils/nextTypeAheadElement';
 import { treeDataTypes } from '../../utils/tokens';
 import { treeItemFilter } from '../../utils/treeItemFilter';
 import { useRovingTabIndex } from '../../hooks/useRovingTabIndexes';
-import { dataTreeItemValueAttrName, getTreeItemValueFromElement } from '../../utils/getTreeItemValueFromElement';
 import { HTMLElementWalker } from '../../utils/createHTMLElementWalker';
+import { TreeItemValue } from '../../TreeItem';
+import { dataTreeItemValueAttrName } from '../../utils/getTreeItemValueFromElement';
 
-export function useFlatTreeNavigation<Props extends HeadlessTreeItemProps>(virtualTree: HeadlessTree<Props>) {
+export function useFlatTreeNavigation() {
   const { targetDocument } = useFluent_unstable();
   const { rove, initialize } = useRovingTabIndex(treeItemFilter);
 
@@ -23,11 +23,39 @@ export function useFlatTreeNavigation<Props extends HeadlessTreeItemProps>(virtu
       case treeDataTypes.TypeAhead:
         walker.currentElement = data.target;
         return nextTypeAheadElement(walker, data.event.key);
-      case treeDataTypes.ArrowLeft:
-        return parentElement(virtualTree, data.target, walker);
-      case treeDataTypes.ArrowRight:
+      case treeDataTypes.ArrowLeft: {
+        const nextElement = parentElement(data.parentValue, walker);
+        if (!nextElement && process.env.NODE_ENV !== 'production') {
+          // eslint-disable-next-line no-console
+          console.warn(
+            /* #__DE-INDENT__ */ `
+            @fluentui/react-tree [useFlatTreeNavigation]:
+            \'ArrowLeft\' navigation was not possible.
+            No parent element found for the current element:
+          `,
+            data.target,
+          );
+        }
+        return nextElement;
+      }
+      case treeDataTypes.ArrowRight: {
         walker.currentElement = data.target;
-        return firstChild(data.target, walker);
+        const nextElement = firstChild(data.target, walker);
+        if (!nextElement && process.env.NODE_ENV !== 'production') {
+          const ariaLevel = Number(data.target.getAttribute('aria-level'));
+          // eslint-disable-next-line no-console
+          console.warn(
+            /* #__DE-INDENT__ */ `
+            @fluentui/react-tree [useFlatTreeNavigation]:
+            \'ArrowRight\' navigation was not possible.
+            No element with "aria-posinset=1" and "aria-level=${ariaLevel + 1}"
+            was found after the current element!
+          `,
+            data.target,
+          );
+        }
+        return nextElement;
+      }
       case treeDataTypes.End:
         walker.currentElement = walker.root;
         return walker.lastChild();
@@ -65,20 +93,9 @@ function firstChild(target: HTMLElement, treeWalker: HTMLElementWalker): HTMLEle
   return null;
 }
 
-function parentElement(
-  virtualTreeItems: HeadlessTree<HeadlessTreeItemProps>,
-  target: HTMLElement,
-  treeWalker: HTMLElementWalker,
-) {
-  const value = getTreeItemValueFromElement(target);
-  if (value === null) {
+function parentElement(parentValue: TreeItemValue | undefined, treeWalker: HTMLElementWalker) {
+  if (parentValue === undefined) {
     return null;
   }
-  const virtualTreeItem = virtualTreeItems.get(value);
-  if (virtualTreeItem?.parentValue) {
-    return treeWalker.root.querySelector<HTMLElement>(
-      `[${dataTreeItemValueAttrName}="${virtualTreeItem.parentValue}"]`,
-    );
-  }
-  return null;
+  return treeWalker.root.querySelector<HTMLElement>(`[${dataTreeItemValueAttrName}="${parentValue}"]`);
 }

packages/react-components/react-tree/src/components/FlatTree/useHeadlessFlatTree.ts

@@ -13,7 +13,6 @@ import {
   TreeCheckedChangeData,
   TreeCheckedChangeEvent,
   TreeNavigationData_unstable,
-  TreeNavigationEvent_unstable,
   TreeOpenChangeData,
   TreeOpenChangeEvent,
   TreeProps,
@@ -119,7 +118,7 @@ export function useHeadlessFlatTree_unstable<Props extends HeadlessTreeItemProps
   const headlessTree = React.useMemo(() => createHeadlessTree(props), [props]);
   const [openItems, setOpenItems] = useControllableOpenItems(options);
   const [checkedItems, setCheckedItems] = useFlatControllableCheckedItems(options, headlessTree);
-  const { initialize, navigate } = useFlatTreeNavigation(headlessTree);
+  const { initialize, navigate } = useFlatTreeNavigation();
   const { targetDocument } = useFluent_unstable();
   const walkerRef = React.useRef<HTMLElementWalker>();
   const initializeWalker = React.useCallback(
@@ -151,15 +150,6 @@ export function useHeadlessFlatTree_unstable<Props extends HeadlessTreeItemProps
     setCheckedItems(nextCheckedItems);
   });
 
-  const handleNavigation = useEventCallback(
-    (event: TreeNavigationEvent_unstable, data: TreeNavigationData_unstable) => {
-      options.onNavigation?.(event, data);
-      if (walkerRef.current) {
-        navigate(data, walkerRef.current);
-      }
-    },
-  );
-
   const getNextNavigableItem = useEventCallback(
     (visibleItems: HeadlessTreeItem<Props>[], data: TreeNavigationData_unstable) => {
       const item = headlessTree.get(data.value);
@@ -198,10 +188,10 @@ export function useHeadlessFlatTree_unstable<Props extends HeadlessTreeItemProps
       checkedItems,
       onOpenChange: handleOpenChange,
       onCheckedChange: handleCheckedChange,
-      onNavigation: handleNavigation,
+      onNavigation: options.onNavigation ?? noop,
     }),
     // eslint-disable-next-line react-hooks/exhaustive-deps
-    [openItems, checkedItems],
+    [openItems, checkedItems, options.selectionMode, options.onNavigation],
   );
 
   const items = React.useCallback(() => headlessTree.visibleItems(openItems), [openItems, headlessTree]);
@@ -221,3 +211,7 @@ export function useHeadlessFlatTree_unstable<Props extends HeadlessTreeItemProps
     [navigate, getTreeProps, getNextNavigableItem, getElementFromItem, items],
   );
 }
+
+function noop() {
+  /* noop */
+}

packages/react-components/react-tree/src/components/Tree/Tree.types.ts

@@ -1,6 +1,6 @@
 import type * as React from 'react';
 import type { ComponentProps, ComponentState, SelectionMode, Slot } from '@fluentui/react-utilities';
-import type { TreeContextValue } from '../../contexts/treeContext';
+import type { TreeContextValue } from '../../contexts';
 import type { ArrowDown, ArrowLeft, ArrowRight, ArrowUp, End, Enter, Home } from '@fluentui/keyboard-keys';
 import type { TreeItemValue } from '../TreeItem/TreeItem.types';
 import { CheckboxProps } from '@fluentui/react-checkbox';
@@ -15,7 +15,11 @@ export type TreeSlots = {
 };
 
 // eslint-disable-next-line @typescript-eslint/naming-convention
-export type TreeNavigationData_unstable = { target: HTMLElement; value: TreeItemValue } & (
+export type TreeNavigationData_unstable = {
+  target: HTMLElement;
+  value: TreeItemValue;
+  parentValue: TreeItemValue | undefined;
+} & (
   | { event: React.MouseEvent<HTMLElement>; type: 'Click' }
   | { event: React.KeyboardEvent<HTMLElement>; type: 'TypeAhead' }
   | { event: React.KeyboardEvent<HTMLElement>; type: typeof ArrowRight }

packages/react-components/react-tree/src/components/Tree/useTree.ts

@@ -34,6 +34,7 @@ function useNestedRootTree(props: TreeProps, ref: React.Ref<HTMLElement>): TreeS
   const { navigate, initialize } = useTreeNavigation();
   const walkerRef = React.useRef<HTMLElementWalker>();
   const { targetDocument } = useFluent_unstable();
+
   const initializeWalker = React.useCallback(
     (root: HTMLElement | null) => {
       if (root && targetDocument) {
@@ -65,7 +66,7 @@ function useNestedRootTree(props: TreeProps, ref: React.Ref<HTMLElement>): TreeS
   const handleNavigation = useEventCallback(
     (event: TreeNavigationEvent_unstable, data: TreeNavigationData_unstable) => {
       props.onNavigation?.(event, data);
-      if (walkerRef.current) {
+      if (walkerRef.current && !event.isDefaultPrevented()) {
         navigate(data, walkerRef.current);
       }
     },

packages/react-components/react-tree/src/components/TreeItem/TreeItem.types.ts

@@ -55,6 +55,10 @@ export type TreeItemProps = ComponentProps<Partial<TreeItemSlots>> & {
    */
   open?: boolean;
   onOpenChange?: (e: TreeItemOpenChangeEvent, data: TreeItemOpenChangeData) => void;
+  /**
+   * This property is inferred through context on a nested tree, and required for a flat tree.
+   */
+  parentValue?: TreeItemValue;
 };
 
 /**