Doc: Tree lazy loading

change/@fluentui-react-tree-d2b17f80-1a10-4456-a7dd-89b53f9a27f4.json

@@ -0,0 +1,7 @@
+{
+  "type": "prerelease",
+  "comment": "feat: adds lazy loading story",
+  "packageName": "@fluentui/react-tree",
+  "email": "[email protected]",
+  "dependentChangeType": "patch"
+}

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

@@ -60,6 +60,7 @@ export type FlatTreeItemProps<Value = string> = TreeItemProps<Value> & {
 // @public (undocumented)
 export type FlatTreeProps<Value = string> = Required<Pick<TreeProps<Value>, 'openItems' | 'onOpenChange' | 'onNavigation_unstable'>> & {
     ref: React_2.Ref<HTMLDivElement>;
+    openItems: ImmutableSet<Value>;
 };
 
 // @public (undocumented)

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

@@ -12,6 +12,7 @@ import type {
   TreeProps,
 } from '../Tree';
 import type { TreeItemProps } from '../TreeItem';
+import { ImmutableSet } from '../utils/ImmutableSet';
 
 export type FlatTreeItemProps<Value = string> = TreeItemProps<Value> & {
   value: Value;
@@ -40,7 +41,10 @@ export type FlatTreeItem<Props extends FlatTreeItemProps<unknown> = FlatTreeItem
 
 export type FlatTreeProps<Value = string> = Required<
   Pick<TreeProps<Value>, 'openItems' | 'onOpenChange' | 'onNavigation_unstable'>
-> & { ref: React.Ref<HTMLDivElement> };
+> & {
+  ref: React.Ref<HTMLDivElement>;
+  openItems: ImmutableSet<Value>;
+};
 
 /**
  * FlatTree API to manage all required mechanisms to convert a list of items into renderable TreeItems

packages/react-components/react-tree/stories/D_flatTree/TreeLazyLoading.md

@@ -0,0 +1 @@
+In this lazy-loading hierarchical `Tree` structure example, the `LazyTreeItem` component and `useFlatTree` hook are utilized to create an efficient and dynamic tree. The tree loads and displays data on-demand, improving initial rendering time and performance. The `LazyTreeItem` component handles loading states and tree structure updates upon clicking a tree item. The `useFlatTree` hook converts the flat array of items into a tree structure, and allows control over individual `TreeItem` components' open/closed states using the `openItems` and `onOpenChange` props.

packages/react-components/react-tree/stories/D_flatTree/TreeLazyLoading.stories.tsx

@@ -0,0 +1,113 @@
+import * as React from 'react';
+import {
+  FlatTreeItemProps,
+  Tree,
+  TreeItem,
+  TreeItemLayout,
+  TreeOpenChangeData,
+  TreeOpenChangeEvent,
+  useFlatTree_unstable,
+} from '@fluentui/react-tree';
+import story from './TreeLazyLoading.md';
+import { Spinner } from '@fluentui/react-components';
+
+interface Result {
+  results: { name: string }[];
+}
+
+type Entity = FlatTreeItemProps & { name: string };
+
+export const LazyLoading = () => {
+  const peopleTree = useQuery<Entity[]>([]);
+  const planetsTree = useQuery<Entity[]>([]);
+  const starshipsTree = useQuery<Entity[]>([]);
+  const trees = {
+    people: peopleTree,
+    planets: planetsTree,
+    starships: starshipsTree,
+  };
+
+  const tree = React.useMemo<Entity[]>(
+    () => [
+      {
+        name: 'People',
+        value: 'people',
+        leaf: false,
+      },
+      ...peopleTree.value,
+      {
+        name: 'Planets',
+        value: 'planets',
+        leaf: false,
+      },
+      ...planetsTree.value,
+      {
+        name: 'Starship',
+        value: 'starships',
+        leaf: false,
+      },
+      ...starshipsTree.value,
+    ],
+    [peopleTree, planetsTree, starshipsTree],
+  );
+
+  const handleOpenChange = (_: TreeOpenChangeEvent, data: TreeOpenChangeData) => {
+    if (data.open) {
+      if (
+        (data.value === 'people' || data.value === 'planets' || data.value === 'starships') &&
+        !trees[data.value].isLoaded
+      ) {
+        trees[data.value].query(() =>
+          fetch(`https://swapi.dev/api/${data.value}`)
+            .then(result => result.json())
+            .then((json: Result) =>
+              json.results.map<Entity>(people => ({
+                value: `${data.value}/${people.name}`,
+                parentValue: data.value,
+                name: people.name,
+              })),
+            ),
+        );
+      }
+    }
+  };
+
+  const flatTree = useFlatTree_unstable(tree, { onOpenChange: handleOpenChange });
+  const treeProps = flatTree.getTreeProps();
+  return (
+    <Tree {...treeProps} aria-label="Tree">
+      {Array.from(flatTree.items(), item => {
+        const { name, ...itemProps } = item.getTreeItemProps();
+        const { isLoading = false } = trees[item.value as 'people' | 'planets' | 'starships'] ?? {};
+        return (
+          <TreeItem expandIcon={isLoading ? <Spinner size="tiny" /> : undefined} key={item.value} {...itemProps}>
+            <TreeItemLayout>{name}</TreeItemLayout>
+          </TreeItem>
+        );
+      })}
+    </Tree>
+  );
+};
+
+LazyLoading.parameters = {
+  docs: {
+    description: {
+      story,
+    },
+  },
+};
+
+/**
+ * This function is just for the sake of the example,
+ * a library for fetching data (like react-query) might be a better option
+ */
+function useQuery<Value>(initialValue: Value) {
+  const [queryResult, setQueryResult] = React.useState({ value: initialValue, isLoading: false, isLoaded: false });
+  const query = (fn: () => Promise<Value> | Value) => {
+    setQueryResult(curr => ({ ...curr, isLoading: true }));
+    Promise.resolve(fn()).then(nextValue => {
+      setQueryResult({ value: nextValue, isLoaded: true, isLoading: false });
+    });
+  };
+  return { ...queryResult, query } as const;
+}

packages/react-components/react-tree/stories/D_flatTree/index.stories.tsx

@@ -5,6 +5,7 @@ export { UseFlatTree as Default } from './useFlatTree.stories';
 export { FlattenTree as flattenTree } from './flattenTree.stories';
 export { Virtualization } from './Virtualization.stories';
 export { AddRemoveTreeItem } from './TreeItemAddRemove.stories';
+export { LazyLoading } from './TreeLazyLoading.stories';
 
 export default {
   title: 'Preview Components/Tree/flatTree',