feat: implements selection (#28497)

* feat: implements selection

* chore: adds unstable suffix to immutable interfaces

* chore: begins implementation of createNextFlatCheckedItems

* chore: implements selection in flat scenario

* tree selection stories for single and multi select

* chore: adds short circuit to improve performance on selection

* chore: removes checkedItem from TreeCheckedChangeData
+ exports TreeCheckedChangeData and TreeCheckedChangeEvent

* chore: uses aria-checked for multiselect

* chore: creates generator to properly navigate through the flat tree

* chore: stops change event prevention

---------

Co-authored-by: petdud <petrduda@microsoft.com>

change/@fluentui-react-tree-322a0d03-169c-4ca6-9fba-65de83877ac2.json

@@ -0,0 +1,7 @@
+{
+  "type": "prerelease",
+  "comment": "feat: implements selection",
+  "packageName": "@fluentui/react-tree",
+  "email": "bernardo.sunderhus@gmail.com",
+  "dependentChangeType": "patch"
+}

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

@@ -13,6 +13,8 @@ import type { ArrowUp } from '@fluentui/keyboard-keys';
 import type { AvatarContextValue } from '@fluentui/react-avatar';
 import type { AvatarSize } from '@fluentui/react-avatar';
 import { ButtonContextValue } from '@fluentui/react-button';
+import type { Checkbox } from '@fluentui/react-checkbox';
+import { CheckboxProps } from '@fluentui/react-checkbox';
 import type { ComponentProps } from '@fluentui/react-utilities';
 import type { ComponentState } from '@fluentui/react-utilities';
 import { ContextSelector } from '@fluentui/react-context-selector';
@@ -24,7 +26,10 @@ import type { ForwardRefComponent } from '@fluentui/react-utilities';
 import type { Home } from '@fluentui/keyboard-keys';
 import { Provider } from 'react';
 import { ProviderProps } from 'react';
+import type { Radio } from '@fluentui/react-radio';
+import { RadioProps } from '@fluentui/react-radio';
 import * as React_2 from 'react';
+import { SelectionMode as SelectionMode_2 } from '@fluentui/react-utilities';
 import type { Slot } from '@fluentui/react-utilities';
 import type { SlotClassNames } from '@fluentui/react-utilities';
 
@@ -44,7 +49,7 @@ export type FlatTree<Props extends FlatTreeItemProps = FlatTreeItemProps> = {
 export type FlatTreeItem<Props extends FlatTreeItemProps = FlatTreeItemProps> = {
     index: number;
     level: number;
-    childrenSize: number;
+    childrenValues: TreeItemValue[];
     value: TreeItemValue;
     parentValue: TreeItemValue | undefined;
     getTreeItemProps(): Required<Pick<Props, 'value' | 'aria-setsize' | 'aria-level' | 'aria-posinset' | 'itemType'>> & Omit<Props, 'parentId'>;
@@ -57,7 +62,7 @@ export type FlatTreeItemProps = Omit<TreeItemProps, 'itemType' | 'value'> & Part
 };
 
 // @public (undocumented)
-export type FlatTreeProps = Required<Pick<TreeProps, 'openItems' | 'onOpenChange' | 'onNavigation_unstable'>> & {
+export type FlatTreeProps = Required<Pick<TreeProps, 'openItems' | 'onOpenChange' | 'onNavigation_unstable' | 'checkedItems' | 'onCheckedChange'>> & {
     ref: React_2.Ref<HTMLDivElement>;
     openItems: ImmutableSet<TreeItemValue>;
 };
@@ -83,15 +88,34 @@ export const renderTreeItemPersonaLayout_unstable: (state: TreeItemPersonaLayout
 // @public
 export const Tree: ForwardRefComponent<TreeProps>;
 
+// @public (undocumented)
+export type TreeCheckedChangeData = {
+    value: TreeItemValue;
+    target: HTMLElement;
+    event: React_2.ChangeEvent<HTMLElement>;
+    type: 'Change';
+} & ({
+    selectionMode: 'multiselect';
+    checked: MultiSelectValue;
+} | {
+    selectionMode: 'single';
+    checked: SingleSelectValue;
+});
+
+// @public (undocumented)
+export type TreeCheckedChangeEvent = TreeCheckedChangeData['event'];
+
 // @public (undocumented)
 export const treeClassNames: SlotClassNames<TreeSlots>;
 
 // @public (undocumented)
 export type TreeContextValue = {
     level: number;
+    selectionMode: 'none' | SelectionMode_2;
     appearance: 'subtle' | 'subtle-alpha' | 'transparent';
     size: 'small' | 'medium';
     openItems: ImmutableSet<TreeItemValue>;
+    checkedItems: ImmutableMap<TreeItemValue, 'mixed' | boolean>;
     requestTreeResponse(request: TreeItemRequest): void;
 };
 
@@ -168,6 +192,8 @@ export type TreeItemSlots = {
     actions?: Slot<ExtractSlotProps<Slot<'div'> & {
         visible?: boolean;
     }>>;
+    checkboxIndicator?: Slot<typeof Checkbox>;
+    radioIndicator?: Slot<typeof Radio>;
 };
 
 // @public
@@ -217,7 +243,6 @@ export type TreeOpenChangeData = {
     open: boolean;
     value: TreeItemValue;
     target: HTMLElement;
-    openItems: ImmutableSet<TreeItemValue>;
 } & ({
     event: React_2.MouseEvent<HTMLElement>;
     type: 'ExpandIconClick';
@@ -246,11 +271,18 @@ export type TreeProps = ComponentProps<TreeSlots> & {
     defaultOpenItems?: Iterable<TreeItemValue>;
     onOpenChange?(event: TreeOpenChangeEvent, data: TreeOpenChangeData): void;
     onNavigation_unstable?(event: TreeNavigationEvent_unstable, data: TreeNavigationData_unstable): void;
+    selectionMode?: SelectionMode_2;
+    checkedItems?: Iterable<TreeItemValue | [TreeItemValue, TreeSelectionValue]>;
+    defaultCheckedItems?: Iterable<TreeItemValue | [TreeItemValue, TreeSelectionValue]>;
+    onCheckedChange?(event: TreeCheckedChangeEvent, data: TreeCheckedChangeData): void;
 };
 
 // @public (undocumented)
 export const TreeProvider: Provider<TreeContextValue | undefined> & FC<ProviderProps<TreeContextValue | undefined>>;
 
+// @public (undocumented)
+export type TreeSelectionValue = MultiSelectValue | SingleSelectValue;
+
 // @public (undocumented)
 export type TreeSlots = {
     root: Slot<'div'>;

packages/react-components/react-tree/package.json

@@ -40,9 +40,11 @@
     "@fluentui/react-aria": "^9.3.26",
     "@fluentui/react-avatar": "^9.5.12",
     "@fluentui/react-button": "^9.3.23",
+    "@fluentui/react-checkbox": "^9.1.24",
     "@fluentui/react-context-selector": "^9.1.26",
     "@fluentui/react-icons": "^2.0.203",
     "@fluentui/react-portal": "^9.3.1",
+    "@fluentui/react-radio": "^9.1.24",
     "@fluentui/react-shared-contexts": "^9.6.0",
     "@fluentui/react-tabster": "^9.10.0",
     "@fluentui/react-theme": "^9.1.9",

packages/react-components/react-tree/src/components/Tree/Tree.test.tsx

@@ -2,9 +2,10 @@ import * as React from 'react';
 import { render } from '@testing-library/react';
 import { Tree } from './Tree';
 import { isConformant } from '../../testing/isConformant';
+import { TreeProps } from './index';
 
 describe('Tree', () => {
-  isConformant({
+  isConformant<TreeProps>({
     Component: Tree,
     displayName: 'Tree',
     disabledTests: ['consistent-callback-args'],

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

@@ -1,9 +1,14 @@
 import type * as React from 'react';
-import type { ComponentProps, ComponentState, Slot } from '@fluentui/react-utilities';
+import type { ComponentProps, ComponentState, SelectionMode, Slot } from '@fluentui/react-utilities';
 import type { TreeContextValue } from '../../contexts/treeContext';
 import type { ArrowDown, ArrowLeft, ArrowRight, ArrowUp, End, Enter, Home } from '@fluentui/keyboard-keys';
 import type { TreeItemValue } from '../TreeItem/TreeItem.types';
-import { ImmutableSet } from '../../utils/ImmutableSet';
+import { CheckboxProps } from '@fluentui/react-checkbox';
+import { RadioProps } from '@fluentui/react-radio';
+
+export type MultiSelectValue = NonNullable<CheckboxProps['checked']>;
+export type SingleSelectValue = NonNullable<RadioProps['checked']>;
+export type TreeSelectionValue = MultiSelectValue | SingleSelectValue;
 
 export type TreeSlots = {
   root: Slot<'div'>;
@@ -28,7 +33,6 @@ export type TreeOpenChangeData = {
   open: boolean;
   value: TreeItemValue;
   target: HTMLElement;
-  openItems: ImmutableSet<TreeItemValue>;
 } & (
   | { event: React.MouseEvent<HTMLElement>; type: 'ExpandIconClick' }
   | { event: React.MouseEvent<HTMLElement>; type: 'Click' }
@@ -39,6 +43,24 @@ export type TreeOpenChangeData = {
 
 export type TreeOpenChangeEvent = TreeOpenChangeData['event'];
 
+export type TreeCheckedChangeData = {
+  value: TreeItemValue;
+  target: HTMLElement;
+  event: React.ChangeEvent<HTMLElement>;
+  type: 'Change';
+} & (
+  | {
+      selectionMode: 'multiselect';
+      checked: MultiSelectValue;
+    }
+  | {
+      selectionMode: 'single';
+      checked: SingleSelectValue;
+    }
+);
+
+export type TreeCheckedChangeEvent = TreeCheckedChangeData['event'];
+
 export type TreeContextValues = {
   tree: TreeContextValue;
 };
@@ -90,6 +112,37 @@ export type TreeProps = ComponentProps<TreeSlots> & {
    */
   // eslint-disable-next-line @typescript-eslint/naming-convention
   onNavigation_unstable?(event: TreeNavigationEvent_unstable, data: TreeNavigationData_unstable): void;
+
+  /**
+   * This refers to the selection mode of the tree.
+   * - undefined: No selection can be done.
+   * - 'single': Only one tree item can be selected, radio buttons are rendered.
+   * - 'multiselect': Multiple tree items can be selected, checkboxes are rendered.
+   *
+   * @default undefined
+   */
+  selectionMode?: SelectionMode;
+  /**
+   * This refers to a list of ids of checked tree items, or a list of tuples of ids and checked state.
+   * Controls the state of the checked tree items.
+   * These property is ignored for subtrees.
+   */
+  checkedItems?: Iterable<TreeItemValue | [TreeItemValue, TreeSelectionValue]>;
+  /**
+   * This refers to a list of ids of checked tree items, or a list of tuples of ids and checked state.
+   * Default value for the uncontrolled state of checked tree items.
+   * These property is ignored for subtrees.
+   */
+  defaultCheckedItems?: Iterable<TreeItemValue | [TreeItemValue, TreeSelectionValue]>;
+  /**
+   * Callback fired when the component changes value from checked state.
+   * These property is ignored for subtrees.
+   *
+   * @param event - a React's Synthetic event
+   * @param data - A data object with relevant information,
+   * such as checked value and type of interaction that created the event.
+   */
+  onCheckedChange?(event: TreeCheckedChangeEvent, data: TreeCheckedChangeData): void;
 };
 
 /**

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

@@ -1,8 +1,19 @@
 import * as React from 'react';
 import * as ReactDOM from 'react-dom';
-import { getNativeElementProps, useEventCallback, useMergedRefs } from '@fluentui/react-utilities';
-import type { TreeOpenChangeData, TreeProps, TreeState, TreeNavigationData_unstable } from './Tree.types';
-import { createNextOpenItems, useControllableOpenItems, useNestedTreeNavigation } from '../../hooks';
+import { SelectionMode, getNativeElementProps, useEventCallback, useMergedRefs } from '@fluentui/react-utilities';
+import {
+  TreeOpenChangeData,
+  TreeProps,
+  TreeState,
+  TreeNavigationData_unstable,
+  TreeCheckedChangeData,
+} from './Tree.types';
+import {
+  useControllableOpenItems,
+  useNestedTreeNavigation,
+  useNestedControllableCheckedItems,
+  createNextOpenItems,
+} from '../../hooks';
 import { treeDataTypes } from '../../utils/tokens';
 import { TreeItemRequest } from '../../contexts';
 
@@ -15,19 +26,26 @@ import { TreeItemRequest } from '../../contexts';
 export function useRootTree(props: TreeProps, ref: React.Ref<HTMLElement>): TreeState {
   warnIfNoProperPropsRootTree(props);
 
-  const { appearance = 'subtle', size = 'medium' } = props;
+  const { appearance = 'subtle', size = 'medium', selectionMode = 'none' } = props;
 
   const [openItems, setOpenItems] = useControllableOpenItems(props);
 
+  const [checkedItems] = useNestedControllableCheckedItems(props);
   const [navigate, navigationRef] = useNestedTreeNavigation();
 
-  const requestOpenChange = (data: Omit<TreeOpenChangeData, 'openItems'>) => {
-    const nextOpenItems = createNextOpenItems(data, openItems);
-    props.onOpenChange?.(data.event, { ...data, openItems: nextOpenItems } as TreeOpenChangeData);
+  const requestOpenChange = (data: TreeOpenChangeData) => {
+    props.onOpenChange?.(data.event, data);
     if (data.event.isDefaultPrevented()) {
       return;
     }
-    return setOpenItems(nextOpenItems);
+    return setOpenItems(createNextOpenItems(data, openItems));
+  };
+
+  const requestCheckedChange = (data: TreeCheckedChangeData) => {
+    props.onCheckedChange?.(data.event, data);
+    // TODO:
+    // we should implement the logic for nested tree selection
+    // return setCheckedItems(checkedItems);
   };
 
   const requestNavigation = (data: TreeNavigationData_unstable) => {
@@ -77,22 +95,33 @@ export function useRootTree(props: TreeProps, ref: React.Ref<HTMLElement>): Tree
       case treeDataTypes.ArrowDown:
       case treeDataTypes.TypeAhead:
         return requestNavigation({ ...request, target: request.event.currentTarget });
+      case treeDataTypes.Change: {
+        const previousCheckedValue = checkedItems.get(request.value);
+        return requestCheckedChange({
+          ...request,
+          selectionMode: selectionMode as SelectionMode,
+          checked: previousCheckedValue === 'mixed' ? true : !previousCheckedValue,
+        });
+      }
     }
   });
 
   return {
     components: {
       root: 'div',
     },
+    selectionMode,
     open: true,
     appearance,
     size,
     level: 1,
     openItems,
+    checkedItems,
     requestTreeResponse,
     root: getNativeElementProps('div', {
       ref: useMergedRefs(navigationRef, ref),
       role: 'tree',
+      'aria-multiselectable': selectionMode === 'multiselect' ? true : undefined,
       ...props,
     }),
   };

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

@@ -18,7 +18,9 @@ export function useSubtree(props: TreeProps, ref: React.Ref<HTMLElement>): TreeS
   const { appearance = contextAppearance ?? 'subtle', size = contextSize ?? 'medium' } = props;
 
   const parentLevel = useTreeContext_unstable(ctx => ctx.level);
+  const selectionMode = useTreeContext_unstable(ctx => ctx.selectionMode);
   const openItems = useTreeContext_unstable(ctx => ctx.openItems);
+  const checkedItems = useTreeContext_unstable(ctx => ctx.checkedItems);
   const requestTreeResponse = useTreeContext_unstable(ctx => ctx.requestTreeResponse);
 
   const open = openItems.has(value);
@@ -30,13 +32,15 @@ export function useSubtree(props: TreeProps, ref: React.Ref<HTMLElement>): TreeS
     },
     appearance,
     size,
+    selectionMode,
     level: parentLevel + 1,
     root: getNativeElementProps('div', {
       ref: useMergedRefs(ref, subtreeRef),
       role: 'group',
       ...props,
     }),
     openItems,
+    checkedItems,
     requestTreeResponse,
   };
 }

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

@@ -2,16 +2,18 @@ import { TreeContextValue } from '../../contexts';
 import type { TreeContextValues, TreeState } from './Tree.types';
 
 export function useTreeContextValues_unstable(state: TreeState): TreeContextValues {
-  const { openItems, level, appearance, size, requestTreeResponse } = state;
+  const { openItems, checkedItems, selectionMode, level, appearance, size, requestTreeResponse } = state;
   /**
    * This context is created with "@fluentui/react-context-selector",
    * there is no sense to memoize it
    */
   const tree: TreeContextValue = {
-    appearance,
     size,
     level,
     openItems,
+    appearance,
+    checkedItems,
+    selectionMode,
     requestTreeResponse,
   };
 

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

@@ -3,6 +3,8 @@ import type { TreeItemContextValue } from '../../contexts';
 import { treeItemLevelToken } from '../../utils/tokens';
 import * as React from 'react';
 import { TreeItemSlotsContextValue } from '../../contexts/treeItemSlotsContext';
+import type { Checkbox } from '@fluentui/react-checkbox';
+import type { Radio } from '@fluentui/react-radio';
 
 export type TreeItemCSSProperties = React.CSSProperties & { [treeItemLevelToken]?: string | number };
 
@@ -30,6 +32,14 @@ export type TreeItemSlots = {
       }
     >
   >;
+  /**
+   * Selection indicator if selection type is checkbox
+   */
+  checkboxIndicator?: Slot<typeof Checkbox>;
+  /**
+   * Selection indicator if selection type is radio
+   */
+  radioIndicator?: Slot<typeof Radio>;
 };
 
 export type TreeItemInternalSlot = Pick<TreeItemSlots, 'root'>;