feature(react-tree): introduces navigationMode property (#33658)

microsoft · Jan 21, 2025 · 246f5b3 · 246f5b3
1 parent b987de6
commit 246f5b3
Show file tree

Hide file tree

Showing 21 changed files with 398 additions and 71 deletions.
diff --git a/change/@fluentui-react-tree-69773403-5633-414b-866a-f20aedf4bc0c.json b/change/@fluentui-react-tree-69773403-5633-414b-866a-f20aedf4bc0c.json
@@ -0,0 +1,7 @@
+{
+  "type": "minor",
+  "comment": "feature: introduces navigationMode property",
+  "packageName": "@fluentui/react-tree",
+  "email": "[email protected]",
+  "dependentChangeType": "patch"
+}
diff --git a/packages/react-components/react-tree/library/etc/react-tree.api.md b/packages/react-components/react-tree/library/etc/react-tree.api.md
@@ -62,6 +62,7 @@ export type FlatTreeItemProps = TreeItemProps & {
 
 // @public (undocumented)
 export type FlatTreeProps = ComponentProps<TreeSlots> & {
+    navigationMode?: 'tree' | 'treegrid';
     appearance?: 'subtle' | 'subtle-alpha' | 'transparent';
     size?: 'small' | 'medium';
     openItems?: Iterable<TreeItemValue>;
@@ -160,6 +161,7 @@ export type TreeContextValue = {
     checkedItems: ImmutableMap<TreeItemValue, 'mixed' | boolean>;
     requestTreeResponse(request: TreeItemRequest): void;
     forceUpdateRovingTabIndex?(): void;
+    navigationMode?: 'tree' | 'treegrid';
 };
 
 // @public (undocumented)
@@ -331,6 +333,9 @@ export type TreeNavigationData_unstable = {
 // @public (undocumented)
 export type TreeNavigationEvent_unstable = TreeNavigationData_unstable['event'];
 
+// @public (undocumented)
+export type TreeNavigationMode = 'tree' | 'treegrid';
+
 // @public (undocumented)
 export type TreeOpenChangeData = {
     open: boolean;
@@ -366,6 +371,7 @@ export type TreeOpenChangeEvent = TreeOpenChangeData['event'];
 
 // @public (undocumented)
 export type TreeProps = ComponentProps<TreeSlots> & {
+    navigationMode?: TreeNavigationMode;
     appearance?: 'subtle' | 'subtle-alpha' | 'transparent';
     size?: 'small' | 'medium';
     openItems?: Iterable<TreeItemValue>;

diff --git a/packages/react-components/react-tree/library/src/Tree.ts b/packages/react-components/react-tree/library/src/Tree.ts
@@ -10,6 +10,7 @@ export type {
   TreeSelectionValue,
   TreeSlots,
   TreeState,
+  TreeNavigationMode,
 } from './components/Tree/index';
 export {
   Tree,

diff --git a/packages/react-components/react-tree/library/src/components/FlatTree/FlatTree.cy.tsx b/packages/react-components/react-tree/library/src/components/FlatTree/FlatTree.cy.tsx
@@ -207,6 +207,25 @@ describe('FlatTree', () => {
       cy.document().realPress('Tab');
       cy.get('#action').should('be.focused');
     });
+    describe('navigationMode="treegrid"', () => {
+      it('should focus on actions/treeitem when pressing right/left arrow', () => {
+        mount(
+          <TreeTest openItems={['item1']} navigationMode="treegrid" id="tree" aria-label="Tree">
+            <TreeItem itemType="branch" value="item1" data-testid="item1">
+              <TreeItemLayout actions={<Button id="action">action</Button>}>level 1, item 1</TreeItemLayout>
+              <Tree>
+                <TreeItem itemType="leaf" value="item1__item1" data-testid="item1__item1">
+                  <TreeItemLayout>level 2, item 1</TreeItemLayout>
+                </TreeItem>
+              </Tree>
+            </TreeItem>
+          </TreeTest>,
+        );
+        cy.get('[data-testid="item1"]').focus().realPress('{rightarrow}');
+        cy.get('#action').should('be.focused').realPress('{leftarrow}');
+        cy.get('[data-testid="item1"]').should('be.focused');
+      });
+    });
     it('should not expand/collapse item on actions Enter/Space key', () => {
       mount(
         <TreeTest id="tree" aria-label="Tree">
@@ -250,25 +269,50 @@ describe('FlatTree', () => {
         cy.get('[data-testid="item2"]').should('be.focused');
         cy.focused().realPress('Tab').should('not.exist');
       });
-      it('should move with Left/Right keys', () => {
-        mount(<TreeTest defaultOpenItems={['item2', 'item2__item1']} />);
-        cy.get('[data-testid="item1"]').focus().realPress('{downarrow}');
-        cy.get('[data-testid="item2"]').should('be.focused').realPress('{rightarrow}');
-        cy.get('[data-testid="item2__item1"]').should('be.focused').realPress('{rightarrow}');
-        cy.get('[data-testid="item2__item1__item1"]').should('be.focused').realPress('{leftarrow}');
-        cy.get('[data-testid="item2__item1"]').should('be.focused').realPress('{leftarrow}').realPress('{leftarrow}');
-        cy.get('[data-testid="item2"]').should('be.focused');
-      });
-      it('should not move with Alt + Left/Right keys', () => {
-        mount(<TreeTest defaultOpenItems={['item2', 'item2__item1']} />);
-        cy.get('[data-testid="item1"]').focus().realPress('{downarrow}');
-        cy.get('[data-testid="item2"]').should('be.focused').realPress(['Alt', '{rightarrow}']);
-        cy.get('[data-testid="item2"]').should('be.focused').realPress('{rightarrow}');
-        cy.get('[data-testid="item2__item1"]').should('be.focused').realPress('{rightarrow}');
-        cy.get('[data-testid="item2__item1__item1"]').should('be.focused').realPress(['Alt', '{leftarrow}']);
-        cy.get('[data-testid="item2__item1__item1"]').should('be.focused').realPress('{leftarrow}');
-        cy.get('[data-testid="item2__item1"]').should('be.focused').realPress('{leftarrow}').realPress('{leftarrow}');
-        cy.get('[data-testid="item2"]').should('be.focused');
+      describe('navigationMode="treegrid"', () => {
+        it('should move with Up/Down keys', () => {
+          mount(
+            <TreeTest openItems={['item1']} navigationMode="treegrid" id="tree" aria-label="Tree">
+              <TreeItem itemType="branch" value="item1" data-testid="item1">
+                <TreeItemLayout>level 1, item 1</TreeItemLayout>
+                <Tree>
+                  <TreeItem itemType="leaf" value="item1__item1" data-testid="item1__item1">
+                    <TreeItemLayout actions={<Button id="action">action</Button>}>level 2, item 1</TreeItemLayout>
+                  </TreeItem>
+                  <TreeItem itemType="leaf" value="item1__item2" data-testid="item1__item2">
+                    <TreeItemLayout>level 2, item 2</TreeItemLayout>
+                  </TreeItem>
+                </Tree>
+              </TreeItem>
+            </TreeTest>,
+          );
+          cy.get('[data-testid="item1__item1"]').focus().realPress('{rightarrow}');
+          cy.get('#action').should('be.focused').realPress('{uparrow}');
+          cy.get('[data-testid="item1"]').should('be.focused');
+          cy.get('[data-testid="item1__item1"]').focus().realPress('{rightarrow}');
+          cy.get('#action').should('be.focused').realPress('{downarrow}');
+          cy.get('[data-testid="item1__item2"]').should('be.focused');
+        });
+        it('should move with Left keys', () => {
+          mount(<TreeTest navigationMode="treegrid" defaultOpenItems={['item2', 'item2__item1']} />);
+          cy.get('[data-testid="item1"]').focus().realPress('{downarrow}');
+          cy.get('[data-testid="item2"]').should('be.focused').realPress('{downarrow}');
+          cy.get('[data-testid="item2__item1"]').should('be.focused').realPress('{downarrow}');
+          cy.get('[data-testid="item2__item1__item1"]').should('be.focused').realPress('{leftarrow}');
+          cy.get('[data-testid="item2__item1"]').should('be.focused').realPress('{leftarrow}').realPress('{leftarrow}');
+          cy.get('[data-testid="item2"]').should('be.focused');
+        });
+
+        it('should not move with Alt + Left keys', () => {
+          mount(<TreeTest navigationMode="treegrid" defaultOpenItems={['item2', 'item2__item1']} />);
+          cy.get('[data-testid="item1"]').focus().realPress('{downarrow}');
+          cy.get('[data-testid="item2"]').should('be.focused').realPress('{downarrow}');
+          cy.get('[data-testid="item2__item1"]').should('be.focused').realPress('{downarrow}');
+          cy.get('[data-testid="item2__item1__item1"]').should('be.focused').realPress(['Alt', '{leftarrow}']);
+          cy.get('[data-testid="item2__item1__item1"]').should('be.focused').realPress('{leftarrow}');
+          cy.get('[data-testid="item2__item1"]').should('be.focused').realPress('{leftarrow}').realPress('{leftarrow}');
+          cy.get('[data-testid="item2"]').should('be.focused');
+        });
       });
       it('should move to last item with End key', () => {
         mount(<TreeTest defaultOpenItems={['item1', 'item2', 'item2__item1']} />);

diff --git a/packages/react-components/react-tree/library/src/components/FlatTree/FlatTree.types.ts b/packages/react-components/react-tree/library/src/components/FlatTree/FlatTree.types.ts
@@ -19,6 +19,13 @@ export type FlatTreeContextValues = {
 };
 
 export type FlatTreeProps = ComponentProps<TreeSlots> & {
+  /**
+   * Indicates how navigation between a treeitem and its actions work
+   * - 'tree' (default): The default navigation, pressing right arrow key navigates inward the first inner children of a branch treeitem
+   * - 'treegrid': Pressing right arrow key navigate towards the actions of a treeitem
+   * @default 'tree'
+   */
+  navigationMode?: 'tree' | 'treegrid';
   /**
    * A tree item can have various appearances:
    * - 'subtle' (default): The default tree item styles.

diff --git a/packages/react-components/react-tree/library/src/components/FlatTree/useFlatTree.ts b/packages/react-components/react-tree/library/src/components/FlatTree/useFlatTree.ts
@@ -22,7 +22,7 @@ export const useFlatTree_unstable: (props: FlatTreeProps, ref: React.Ref<HTMLEle
 };
 
 function useRootFlatTree(props: FlatTreeProps, ref: React.Ref<HTMLElement>): FlatTreeState {
-  const navigation = useFlatTreeNavigation();
+  const navigation = useFlatTreeNavigation(props.navigationMode);
 
   return Object.assign(
     useRootTree(

diff --git a/...s/react-components/react-tree/library/src/components/FlatTree/useFlatTreeContextValues.ts b/...s/react-components/react-tree/library/src/components/FlatTree/useFlatTreeContextValues.ts
@@ -9,6 +9,7 @@ export const useFlatTreeContextValues_unstable = (state: FlatTreeState): FlatTre
     treeType,
     checkedItems,
     selectionMode,
+    navigationMode,
     appearance,
     size,
     requestTreeResponse,
@@ -25,6 +26,7 @@ export const useFlatTreeContextValues_unstable = (state: FlatTreeState): FlatTre
     appearance,
     checkedItems,
     selectionMode,
+    navigationMode,
     contextType,
     level,
     requestTreeResponse,

diff --git a/packages/react-components/react-tree/library/src/components/Tree/Tree.cy.tsx b/packages/react-components/react-tree/library/src/components/Tree/Tree.cy.tsx
@@ -188,6 +188,25 @@ describe('Tree', () => {
       cy.document().realPress('Tab');
       cy.get('#action').should('be.focused');
     });
+    describe('navigationMode="treegrid"', () => {
+      it('should focus on actions/treeitem when pressing right/left arrow', () => {
+        mount(
+          <TreeTest openItems={['item1']} navigationMode="treegrid" id="tree" aria-label="Tree">
+            <TreeItem itemType="branch" value="item1" data-testid="item1">
+              <TreeItemLayout actions={<Button id="action">action</Button>}>level 1, item 1</TreeItemLayout>
+              <Tree>
+                <TreeItem itemType="leaf" value="item1__item1" data-testid="item1__item1">
+                  <TreeItemLayout>level 2, item 1</TreeItemLayout>
+                </TreeItem>
+              </Tree>
+            </TreeItem>
+          </TreeTest>,
+        );
+        cy.get('[data-testid="item1"]').focus().realPress('{rightarrow}');
+        cy.get('#action').should('be.focused').realPress('{leftarrow}');
+        cy.get('[data-testid="item1"]').should('be.focused');
+      });
+    });
     it('should not expand/collapse item on actions Enter/Space key', () => {
       mount(
         <TreeTest id="tree" aria-label="Tree">
@@ -231,25 +250,49 @@ describe('Tree', () => {
         cy.get('[data-testid="item2"]').should('be.focused');
         cy.focused().realPress('Tab').should('not.exist');
       });
-      it('should move with Left/Right keys', () => {
-        mount(<TreeTest defaultOpenItems={['item2', 'item2__item1']} />);
-        cy.get('[data-testid="item1"]').focus().realPress('{downarrow}');
-        cy.get('[data-testid="item2"]').should('be.focused').realPress('{rightarrow}');
-        cy.get('[data-testid="item2__item1"]').should('be.focused').realPress('{rightarrow}');
-        cy.get('[data-testid="item2__item1__item1"]').should('be.focused').realPress('{leftarrow}');
-        cy.get('[data-testid="item2__item1"]').should('be.focused').realPress('{leftarrow}').realPress('{leftarrow}');
-        cy.get('[data-testid="item2"]').should('be.focused');
-      });
-      it('should not move with Alt + Left/Right keys', () => {
-        mount(<TreeTest defaultOpenItems={['item2', 'item2__item1']} />);
-        cy.get('[data-testid="item1"]').focus().realPress('{downarrow}');
-        cy.get('[data-testid="item2"]').should('be.focused').realPress(['Alt', '{rightarrow}']);
-        cy.get('[data-testid="item2"]').should('be.focused').realPress('{rightarrow}');
-        cy.get('[data-testid="item2__item1"]').should('be.focused').realPress('{rightarrow}');
-        cy.get('[data-testid="item2__item1__item1"]').should('be.focused').realPress(['Alt', '{leftarrow}']);
-        cy.get('[data-testid="item2__item1__item1"]').should('be.focused').realPress('{leftarrow}');
-        cy.get('[data-testid="item2__item1"]').should('be.focused').realPress('{leftarrow}').realPress('{leftarrow}');
-        cy.get('[data-testid="item2"]').should('be.focused');
+      describe('navigationMode="treegrid"', () => {
+        it('should move with Up/Down keys', () => {
+          mount(
+            <TreeTest openItems={['item1']} navigationMode="treegrid" id="tree" aria-label="Tree">
+              <TreeItem itemType="branch" value="item1" data-testid="item1">
+                <TreeItemLayout>level 1, item 1</TreeItemLayout>
+                <Tree>
+                  <TreeItem itemType="leaf" value="item1__item1" data-testid="item1__item1">
+                    <TreeItemLayout actions={<Button id="action">action</Button>}>level 2, item 1</TreeItemLayout>
+                  </TreeItem>
+                  <TreeItem itemType="leaf" value="item1__item2" data-testid="item1__item2">
+                    <TreeItemLayout>level 2, item 2</TreeItemLayout>
+                  </TreeItem>
+                </Tree>
+              </TreeItem>
+            </TreeTest>,
+          );
+          cy.get('[data-testid="item1__item1"]').focus().realPress('{rightarrow}');
+          cy.get('#action').should('be.focused').realPress('{uparrow}');
+          cy.get('[data-testid="item1"]').should('be.focused');
+          cy.get('[data-testid="item1__item1"]').focus().realPress('{rightarrow}');
+          cy.get('#action').should('be.focused').realPress('{downarrow}');
+          cy.get('[data-testid="item1__item2"]').should('be.focused');
+        });
+        it('should move with Left keys', () => {
+          mount(<TreeTest navigationMode="treegrid" defaultOpenItems={['item2', 'item2__item1']} />);
+          cy.get('[data-testid="item1"]').focus().realPress('{downarrow}');
+          cy.get('[data-testid="item2"]').should('be.focused').realPress('{downarrow}');
+          cy.get('[data-testid="item2__item1"]').should('be.focused').realPress('{downarrow}');
+          cy.get('[data-testid="item2__item1__item1"]').should('be.focused').realPress('{leftarrow}');
+          cy.get('[data-testid="item2__item1"]').should('be.focused').realPress('{leftarrow}').realPress('{leftarrow}');
+          cy.get('[data-testid="item2"]').should('be.focused');
+        });
+        it('should not move with Alt + Left keys', () => {
+          mount(<TreeTest navigationMode="treegrid" defaultOpenItems={['item2', 'item2__item1']} />);
+          cy.get('[data-testid="item1"]').focus().realPress('{downarrow}');
+          cy.get('[data-testid="item2"]').should('be.focused').realPress('{downarrow}');
+          cy.get('[data-testid="item2__item1"]').should('be.focused').realPress('{downarrow}');
+          cy.get('[data-testid="item2__item1__item1"]').should('be.focused').realPress(['Alt', '{leftarrow}']);
+          cy.get('[data-testid="item2__item1__item1"]').should('be.focused').realPress('{leftarrow}');
+          cy.get('[data-testid="item2__item1"]').should('be.focused').realPress('{leftarrow}').realPress('{leftarrow}');
+          cy.get('[data-testid="item2"]').should('be.focused');
+        });
       });
       it('should move to last item with End key', () => {
         mount(<TreeTest defaultOpenItems={['item1', 'item2', 'item2__item1']} />);

diff --git a/packages/react-components/react-tree/library/src/components/Tree/Tree.types.ts b/packages/react-components/react-tree/library/src/components/Tree/Tree.types.ts
@@ -91,7 +91,16 @@ export type TreeContextValues = {
   tree: TreeContextValue | SubtreeContextValue;
 };
 
+export type TreeNavigationMode = 'tree' | 'treegrid';
+
 export type TreeProps = ComponentProps<TreeSlots> & {
+  /**
+   * Indicates how navigation between a treeitem and its actions work
+   * - 'tree' (default): The default navigation, pressing right arrow key navigates inward the first inner children of a branch treeitem
+   * - 'treegrid': Pressing right arrow key navigate towards the actions of a treeitem
+   * @default 'tree'
+   */
+  navigationMode?: TreeNavigationMode;
   /**
    * A tree item can have various appearances:
    * - 'subtle' (default): The default tree item styles.

diff --git a/packages/react-components/react-tree/library/src/components/Tree/index.ts b/packages/react-components/react-tree/library/src/components/Tree/index.ts
@@ -11,6 +11,7 @@ export type {
   TreeSelectionValue,
   TreeSlots,
   TreeState,
+  TreeNavigationMode,
 } from './Tree.types';
 export { useTree_unstable } from './useTree';
 export { useTreeContextValues_unstable } from './useTreeContextValues';

diff --git a/packages/react-components/react-tree/library/src/components/Tree/useTree.ts b/packages/react-components/react-tree/library/src/components/Tree/useTree.ts
@@ -26,7 +26,7 @@ function useNestedRootTree(props: TreeProps, ref: React.Ref<HTMLElement>): TreeS
 
   const [openItems, setOpenItems] = useControllableOpenItems(props);
   const checkedItems = useNestedCheckedItems(props);
-  const navigation = useTreeNavigation();
+  const navigation = useTreeNavigation(props.navigationMode);
 
   return Object.assign(
     useRootTree(

diff --git a/packages/react-components/react-tree/library/src/components/Tree/useTreeContextValues.ts b/packages/react-components/react-tree/library/src/components/Tree/useTreeContextValues.ts
@@ -13,6 +13,7 @@ export function useTreeContextValues_unstable(state: TreeState): TreeContextValu
       treeType,
       checkedItems,
       selectionMode,
+      navigationMode,
       appearance,
       size,
       requestTreeResponse,
@@ -29,6 +30,7 @@ export function useTreeContextValues_unstable(state: TreeState): TreeContextValu
       appearance,
       checkedItems,
       selectionMode,
+      navigationMode,
       contextType,
       level,
       requestTreeResponse,