Tree documentation and stories

change/@fluentui-react-tree-7b614498-e79f-460b-a3a4-22ba4d9a2bea.json

@@ -0,0 +1,7 @@
+{
+  "type": "prerelease",
+  "comment": "tree stories and doc update",
+  "packageName": "@fluentui/react-tree",
+  "email": "[email protected]",
+  "dependentChangeType": "patch"
+}

packages/react-components/react-tree/src/components/TreeItem/TreeItem.tsx

@@ -7,7 +7,16 @@ import type { ForwardRefComponent } from '@fluentui/react-utilities';
 import { useTreeItemContextValues_unstable } from './useTreeItemContextValues';
 
 /**
- * TreeItem component - TODO: add more docs
+ * The `TreeItem` component represents a single item in a tree.
+ * It expects a certain order of children to work properly: the first child should be the node itself,
+ * and the second child should be a nested subtree in the form of another Tree component or a standalone TreeItem.
+ * This order follows the same order as document traversal for the TreeWalker API in JavaScript:
+ * https://developer.mozilla.org/en-US/docs/Web/API/TreeWalker.
+ * The content and layout of a TreeItem can be defined using the TreeItemLayout or TreeItemPersonaLayout component,
+ * which should be used as a direct child of TreeItem.
+ *
+ * When a TreeItem has nsted child subtree, an expand/collapse control is displayed,
+ * allowing the user to show or hide the children.
  */
 export const TreeItem: ForwardRefComponent<TreeItemProps> = React.forwardRef((props, ref) => {
   const state = useTreeItem_unstable(props, ref);

packages/react-components/react-tree/src/components/TreeItemLayout/TreeItemLayout.tsx

@@ -6,7 +6,9 @@ import type { TreeItemLayoutProps } from './TreeItemLayout.types';
 import type { ForwardRefComponent } from '@fluentui/react-utilities';
 
 /**
- * TreeItemLayout component - TODO: add more docs
+ * The `TreeItemLayout` component is used as a child of `TreeItem` to define the content and layout of a tree item.
+ * It provides a consistent visual structure for tree items in a `Tree` component.
+ * This component should only be used as a direct child of `TreeItem`.
  */
 export const TreeItemLayout: ForwardRefComponent<TreeItemLayoutProps> = React.forwardRef((props, ref) => {
   const state = useTreeItemLayout_unstable(props, ref);

packages/react-components/react-tree/src/components/TreeItemPersonaLayout/TreeItemPersonaLayout.tsx

@@ -7,7 +7,9 @@ import type { ForwardRefComponent } from '@fluentui/react-utilities';
 import { useTreeItemPersonaLayoutContextValues_unstable } from './useTreeItemPersonaLayoutContextValues';
 
 /**
- * TreeItemPersonaLayout component - TODO: add more docs
+ * The `TreeItemPersonaLayout` component is used as a child of `TreeItem` to display a `TreeItem` with a media (typically an avatar) and a description.
+ * It provides a more visually appealing representation of a `TreeItem` and is typically used to display a list of people or topics.
+ * This component should only be used as a direct child of `TreeItem`.
  */
 export const TreeItemPersonaLayout: ForwardRefComponent<TreeItemPersonaLayoutProps> = React.forwardRef((props, ref) => {
   const state = useTreeItemPersonaLayout_unstable(props, ref);

packages/react-components/react-tree/stories/Layouts/TreeItemLayout.md

@@ -0,0 +1 @@
+You can combine multiple props to customize the appearance and behavior of a `Tree` component. It includes the use of `icons`, `badges`, `actions`, and layouts, which can be composed together to create a more complex and flexible user interface.

packages/react-components/react-tree/stories/Tree/TreeLayout.stories.tsx → packages/react-components/react-tree/stories/Layouts/TreeItemLayout.stories.tsx

@@ -10,6 +10,7 @@ import {
   SquareMultiple20Regular,
 } from '@fluentui/react-icons';
 import { Button, CounterBadge, Menu, MenuItem, MenuList, MenuPopover, MenuTrigger } from '@fluentui/react-components';
+import story from './TreeItemLayout.md';
 
 const iconStyleProps: FluentIconsProps = {
   primaryFill: 'red',
@@ -102,3 +103,11 @@ export const Layout = () => {
     </Tree>
   );
 };
+
+Layout.parameters = {
+  docs: {
+    description: {
+      story,
+    },
+  },
+};

packages/react-components/react-tree/stories/Layouts/TreeItemLayoutAside.md

@@ -0,0 +1 @@
+The `Tree` component allows for an `aside` prop to be added to individual `TreeItemLayout` or `TreeItemPersonaLayout` layout components. This creates an area on the right side of the `TreeItem` where additional information can be displayed, such as a badge with notification count or an icon indicating importance. When actions are specified using the `actions` prop, they will overlay the `aside` area on hover.

packages/react-components/react-tree/stories/Tree/TreeAside.stories.tsx → packages/react-components/react-tree/stories/Layouts/TreeItemLayoutAside.stories.tsx

@@ -2,6 +2,7 @@ import * as React from 'react';
 import { Tree, TreeItem, TreeItemLayout } from '@fluentui/react-tree';
 import { Button, CounterBadge } from '@fluentui/react-components';
 import { Edit20Regular, FluentIconsProps, Important16Regular, MoreHorizontal20Regular } from '@fluentui/react-icons';
+import story from './TreeItemLayoutAside.md';
 
 const iconStyleProps: FluentIconsProps = {
   primaryFill: 'red',
@@ -23,7 +24,7 @@ const Actions = () => (
 
 export const Aside = () => (
   <Tree aria-label="Tree">
-    <TreeItem actions={<Actions />}>
+    <TreeItem>
       <TreeItemLayout aside={<RenderAside />}>level 1, item 1</TreeItemLayout>
       <Tree>
         <TreeItem actions={<Actions />}>
@@ -37,7 +38,7 @@ export const Aside = () => (
         </TreeItem>
       </Tree>
     </TreeItem>
-    <TreeItem actions={<Actions />}>
+    <TreeItem>
       <TreeItemLayout aside={<RenderAside />}>level 1, item 2</TreeItemLayout>
       <Tree>
         <TreeItem actions={<Actions />}>
@@ -67,3 +68,11 @@ export const Aside = () => (
     </TreeItem>
   </Tree>
 );
+
+Aside.parameters = {
+  docs: {
+    description: {
+      story,
+    },
+  },
+};

packages/react-components/react-tree/stories/Layouts/TreeItemLayoutDefault.stories.tsx

@@ -0,0 +1,36 @@
+import * as React from 'react';
+import { Tree, TreeItem, TreeItemLayout } from '@fluentui/react-tree';
+
+export const DefaultTreeItemLayout = () => {
+  return (
+    <Tree aria-label="Tree">
+      <TreeItem>
+        <TreeItemLayout>level 1, item 1</TreeItemLayout>
+        <Tree>
+          <TreeItem>
+            <TreeItemLayout>level 2, item 1</TreeItemLayout>
+          </TreeItem>
+          <TreeItem>
+            <TreeItemLayout>level 2, item 2</TreeItemLayout>
+          </TreeItem>
+          <TreeItem>
+            <TreeItemLayout>level 2, item 3</TreeItemLayout>
+          </TreeItem>
+        </Tree>
+      </TreeItem>
+      <TreeItem>
+        <TreeItemLayout>level 1, item 2</TreeItemLayout>
+        <Tree>
+          <TreeItem>
+            <TreeItemLayout>level 2, item 1</TreeItemLayout>
+            <Tree>
+              <TreeItem>
+                <TreeItemLayout>level 3, item 1</TreeItemLayout>
+              </TreeItem>
+            </Tree>
+          </TreeItem>
+        </Tree>
+      </TreeItem>
+    </Tree>
+  );
+};

packages/react-components/react-tree/stories/Layouts/TreeItemPersonaLayout.md

@@ -0,0 +1 @@
+With `TreeItemPersonaLayout`, `TreeItem`, and `Tree`, you can create a highly customizable and flexible UI by leveraging various props like `media`, `icons`, `badges`, and `actions`. Here are some examples of how you can use these components together to achieve different layouts and appearances.

packages/react-components/react-tree/stories/TreeItemPersonaLayout/TreePersonaLayout.stories.tsx → packages/react-components/react-tree/stories/Layouts/TreeItemPersonaLayout.stories.tsx

@@ -14,6 +14,7 @@ import {
 } from '@fluentui/react-components';
 import { Tree, TreeItem, TreeItemPersonaLayout } from '@fluentui/react-tree';
 import { Flag20Regular, FluentIconsProps, Important16Regular, MoreHorizontal20Regular } from '@fluentui/react-icons';
+import story from './TreeItemPersonaLayout.md';
 
 const useBadgeStyles = makeStyles({
   base: {
@@ -132,3 +133,11 @@ export const TreePersonaLayout = () => {
     </Tree>
   );
 };
+
+TreePersonaLayout.parameters = {
+  docs: {
+    description: {
+      story,
+    },
+  },
+};

packages/react-components/react-tree/stories/TreeItemPersonaLayout/TreeItemPersonaLayoutDefault.stories.tsx → packages/react-components/react-tree/stories/Layouts/TreeItemPersonaLayoutDefault.stories.tsx

@@ -2,7 +2,7 @@ import * as React from 'react';
 import { Avatar } from '@fluentui/react-components';
 import { Tree, TreeItem, TreeItemPersonaLayout } from '@fluentui/react-tree';
 
-export const Default = () => {
+export const DefaultTreeItemPersonaLayout = () => {
   return (
     <Tree aria-label="Tree">
       <TreeItem>

packages/react-components/react-tree/stories/Layouts/TreeItemPersonaLayoutDescription.md

@@ -0,0 +1 @@
+`TreeItemPersonaLayout` is a layout component used to display a `TreeItem` with a media (such as an avatar) and a description. Its purpose is to provide a more visually appealing representation of a `TreeItem`, often used to display a list of people or related topics.

packages/react-components/react-tree/stories/Layouts/TreeItemPersonaLayoutMedia.md

@@ -0,0 +1,3 @@
+The `TreeItemPersonaLayout` component allows each `TreeItem` to be displayed with a persona layout, which supports a `media` prop such as an `Avatar`.
+
+The `Avatar` component can be customized with different sizes and shapes to suit the design needs.

packages/react-components/react-tree/stories/TreeItemPersonaLayout/TreeItemPersonaLayoutMedia.stories.tsx → packages/react-components/react-tree/stories/Layouts/TreeItemPersonaLayoutMedia.stories.tsx

@@ -1,6 +1,7 @@
 import * as React from 'react';
 import { Avatar } from '@fluentui/react-components';
 import { Tree, TreeItem, TreeItemPersonaLayout } from '@fluentui/react-tree';
+import story from './TreeItemPersonaLayoutMedia.md';
 
 export const Media = () => {
   return (
@@ -36,3 +37,11 @@ export const Media = () => {
     </Tree>
   );
 };
+
+Media.parameters = {
+  docs: {
+    description: {
+      story,
+    },
+  },
+};

packages/react-components/react-tree/stories/Layouts/TreeItemPersonaLayoutReadUnread.md

@@ -0,0 +1 @@
+Layout components can be customized with different styles to make it more visually appealing. In the example below, the component is used to display chat messages. We differentiate between read and unread messages by applying customized styles using the `makeStyles` hook.

packages/react-components/react-tree/stories/TreeItemPersonaLayout/TreeItemPersonaLayoutReadUnread.stories.tsx → packages/react-components/react-tree/stories/Layouts/TreeItemPersonaLayoutReadUnread.stories.tsx

@@ -1,10 +1,11 @@
 import * as React from 'react';
-import { Avatar, makeStyles } from '@fluentui/react-components';
+import { Avatar, makeStyles, tokens } from '@fluentui/react-components';
 import { Tree, TreeItem, TreeItemPersonaLayout } from '@fluentui/react-tree';
+import story from './TreeItemPersonaLayoutReadUnread.md';
 
 const useStyles = makeStyles({
   unread: {
-    fontWeight: 'bold',
+    fontWeight: tokens.fontWeightSemibold,
   },
 });
 
@@ -29,3 +30,11 @@ export const ReadUnread = () => {
     </Tree>
   );
 };
+
+ReadUnread.parameters = {
+  docs: {
+    description: {
+      story,
+    },
+  },
+};

packages/react-components/react-tree/stories/Layouts/TreeItemPersonaLayoutWithDescription.md

@@ -0,0 +1 @@
+You can add a `description` prop to the `TreeItemPersonaLayout` that can be used to display secondary text content beneath the primary text content. This is useful for providing additional information or context about the primary content.

packages/react-components/react-tree/stories/TreeItemPersonaLayout/TreeItemPersonaLayoutWithDescription.stories.tsx → packages/react-components/react-tree/stories/Layouts/TreeItemPersonaLayoutWithDescription.stories.tsx

@@ -1,6 +1,7 @@
 import * as React from 'react';
 import { Avatar } from '@fluentui/react-components';
 import { Tree, TreeItem, TreeItemPersonaLayout } from '@fluentui/react-tree';
+import story from './TreeItemPersonaLayoutWithDescription.md';
 
 export const WithDescription = () => {
   return (
@@ -49,3 +50,11 @@ export const WithDescription = () => {
     </Tree>
   );
 };
+
+WithDescription.parameters = {
+  docs: {
+    description: {
+      story,
+    },
+  },
+};

packages/react-components/react-tree/stories/Layouts/description.md

@@ -0,0 +1,5 @@
+The `TreeItem` component allows for flexible display of items in a tree structure by supporting two types of layouts: `TreeItemLayout` and `TreeItemPersonaLayout`.
+
+The `TreeItemLayout` component is designed to provide a consistent and functional structure for displaying a tree item. It defines the content and layout of the item in a simple and straightforward manner. This layout is ideal for displaying information about items that do not require additional visual elements, such as files or folders in a file system.
+
+On the other hand, the `TreeItemPersonaLayout` component provides a more visually appealing representation of a tree item by including a media element, typically an avatar, alongside a description. This layout is perfect for displaying lists of people or topics, where the media element can represent an individual or a topic icon. As with `TreeItemLayout`, `TreeItemPersonaLayout` should only be used as a direct child of TreeItem.

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

@@ -0,0 +1,23 @@
+import { TreeItemLayout, TreeItemPersonaLayout } from '@fluentui/react-tree';
+import descriptionMd from './description.md';
+
+export { DefaultTreeItemLayout } from './TreeItemLayoutDefault.stories';
+export { DefaultTreeItemPersonaLayout } from './TreeItemPersonaLayoutDefault.stories';
+export { Aside } from './TreeItemLayoutAside.stories';
+export { Media } from './TreeItemPersonaLayoutMedia.stories';
+export { WithDescription } from './TreeItemPersonaLayoutWithDescription.stories';
+export { ReadUnread } from './TreeItemPersonaLayoutReadUnread.stories';
+export { Layout } from './TreeItemLayout.stories';
+export { TreePersonaLayout } from './TreeItemPersonaLayout.stories';
+
+export default {
+  title: 'Preview Components/Tree/Layouts',
+  component: [TreeItemPersonaLayout, TreeItemLayout],
+  parameters: {
+    docs: {
+      description: {
+        component: [descriptionMd].join('\n'),
+      },
+    },
+  },
+};

packages/react-components/react-tree/stories/Tree/TreeAppearance.md

@@ -0,0 +1 @@
+The `Tree` component supports different appearances for TreeItems. The default apperance value is `subtle`. The `subtle-alpha` appearance minimizes emphasis on hovered or focused states, while the `transparent` appearance removes the background color.

packages/react-components/react-tree/stories/Tree/TreeAppearance.stories.tsx

@@ -1,5 +1,6 @@
 import * as React from 'react';
 import { Tree, TreeItem, TreeItemLayout } from '@fluentui/react-tree';
+import story from './TreeAppearance.md';
 
 export const Appearance = () => {
   return (
@@ -26,10 +27,7 @@ export const Appearance = () => {
 Appearance.parameters = {
   docs: {
     description: {
-      story:
-        '- `(undefined)`: the tree item appears with the default style\n' +
-        '- `subtle`: minimizes emphasis on hovered or focused states\n' +
-        '- `transparent`: removes background color.\n',
+      story,
     },
   },
 };

packages/react-components/react-tree/stories/Tree/TreeBestPractices.md

@@ -1,5 +1,14 @@
-## Best practices
+<details>
+<summary>
+ Best Practices
+</summary>
 
 ### Do
 
-### Don't
+- Use the `Tree` component to create a tree structure with `TreeItem` components as children.
+- Organize nodes in a clear hierarchy, with parent nodes at higher levels and child nodes at lower levels.
+- Use custom styles if the tree needs to support more than 10 levels of nesting.
+- Provide an alternative way to represent the tree structure by flattening it into a list of items.
+- Use the `aria-label` attribute on the root of the Tree component to provide an accessible name for the tree.
+
+</details>

packages/react-components/react-tree/stories/Tree/TreeControllingOpenAndClose.md

@@ -0,0 +1,3 @@
+The `Tree` component provides a way to control the open/closed state of individual `TreeItem` components using the `openItems` and `onOpenChange` props.
+
+The `openItems` prop takes an array of `TreeItem` IDs that are currently open, while the `onOpenChange` callback function is called whenever a `TreeItem` is opened or closed. You can then use the callback to update the `openItems` array and keep track of which `TreeItems` are open or closed.

packages/react-components/react-tree/stories/Tree/TreeControllingOpenAndClose.stories.tsx

@@ -7,6 +7,7 @@ import {
   TreeOpenChangeData,
   TreeOpenChangeEvent,
 } from '@fluentui/react-tree';
+import story from './TreeControllingOpenAndClose.md';
 
 export const OpenItemsControlled = () => {
   const [openItems, setOpenItems] = React.useState<TreeItemId[]>([]);
@@ -47,3 +48,11 @@ export const OpenItemsControlled = () => {
     </Tree>
   );
 };
+
+OpenItemsControlled.parameters = {
+  docs: {
+    description: {
+      story,
+    },
+  },
+};

packages/react-components/react-tree/stories/Tree/TreeDefaultOpenTrees.md

@@ -0,0 +1 @@
+The `Tree` component allows you to set the default open/closed state using the `defaultOpenItems` prop for expandable `TreeItem` components. This prop takes an array of `TreeItem` IDs that should be open by default. When the `Tree` is first rendered, the `TreeItem` components listed in `defaultOpenItems` will be open by default, while all other expandable `TreeItem` components will be closed.

packages/react-components/react-tree/stories/Tree/TreeDefaultOpenTrees.stories.tsx

@@ -1,5 +1,6 @@
 import * as React from 'react';
 import { Tree, TreeItem, TreeItemLayout } from '@fluentui/react-tree';
+import story from './TreeDefaultOpenTrees.md';
 
 export const DefaultOpenTrees = () => {
   const defaultOpenTrees = ['default-subtree-1', 'default-subtree-2', 'default-subtree-2-1'];
@@ -42,3 +43,11 @@ export const DefaultOpenTrees = () => {
     </Tree>
   );
 };
+
+DefaultOpenTrees.parameters = {
+  docs: {
+    description: {
+      story,
+    },
+  },
+};

packages/react-components/react-tree/stories/Tree/TreeDescription.md

@@ -1,3 +1,5 @@
+`Tree` is a hierarchical structure for displaying data in a collapsible and expandable way. It consists of a root node that branches out to child nodes, which can also have their own child nodes. Each node can have a content, which is displayed in the tree. The tree is usually used to represent a hierarchy of information, such as a file system, or organization chart. Users can interact with the tree by expanding or collapsing nodes, selecting nodes, or performing actions.
+
 <!-- Don't allow prettier to collapse code block into single line -->
 <!-- prettier-ignore -->
 > **⚠️ Preview components are considered unstable:**

packages/react-components/react-tree/stories/Tree/TreeSize.md

@@ -0,0 +1 @@
+The `size` prop is used to change the size of the `Tree` and its items. It accepts two values: `medium` (default) and `small`. You can set this prop on the `Tree` component to change the size of all items within the tree.

packages/react-components/react-tree/stories/Tree/TreeSize.stories.tsx

@@ -1,5 +1,6 @@
 import * as React from 'react';
 import { Tree, TreeItem, TreeItemLayout } from '@fluentui/react-tree';
+import story from './TreeSize.md';
 
 export const Size = () => {
   return (
@@ -44,7 +45,7 @@ export const Size = () => {
 Size.parameters = {
   docs: {
     description: {
-      story: 'A tree item supports `small` and `medium` sizes.',
+      story,
     },
   },
 };

packages/react-components/react-tree/stories/Tree/Virtualization.md

@@ -0,0 +1,3 @@
+A `Tree` can be virtualized to optimize the rendering of a large tree structure. This technique involves creating a virtual version of the tree that only loads the visible nodes at any given time. By doing so, it reduces the number of DOM nodes that need to be rendered, which in turn improves time to interaction of large trees.
+
+To achieve this, one can create a `flattened` version of the tree structure that can be easily consumed by a virtualization library. This library renders only the items that are currently visible on the screen, which improves TTI metrics.