From 4166f52aeede7e3b4185f495f71f86e3178ac6c3 Mon Sep 17 00:00:00 2001 From: Petr Duda Date: Mon, 20 Mar 2023 21:39:52 +0100 Subject: [PATCH 01/34] tree stories --- .../react-tree/stories/Tree/TreeActions.md | 3 +++ .../react-tree/stories/Tree/TreeActions.stories.tsx | 9 +++++++++ .../react-tree/stories/Tree/TreeAppearance.md | 1 + .../react-tree/stories/Tree/TreeAppearance.stories.tsx | 6 ++---- .../react-tree/stories/Tree/TreeAside.md | 1 + .../react-tree/stories/Tree/TreeAside.stories.tsx | 9 +++++++++ .../stories/Tree/TreeControllingOpenAndClose.md | 5 +++++ .../stories/Tree/TreeControllingOpenAndClose.stories.tsx | 9 +++++++++ .../react-tree/stories/Tree/TreeDefaultOpenTrees.md | 1 + .../stories/Tree/TreeDefaultOpenTrees.stories.tsx | 9 +++++++++ .../stories/Tree/TreeExpandCollapseIconOnly.md | 3 +++ .../stories/Tree/TreeExpandCollapseIconOnly.stories.tsx | 9 +++++++++ .../react-tree/stories/Tree/TreeExpandIcon.md | 3 +++ .../react-tree/stories/Tree/TreeExpandIcon.stories.tsx | 9 +++++++++ .../react-tree/stories/Tree/TreeIconAfter.md | 1 + .../react-tree/stories/Tree/TreeIconAfter.stories.tsx | 9 +++++++++ .../react-tree/stories/Tree/TreeIconBefore.md | 1 + .../react-tree/stories/Tree/TreeIconBefore.stories.tsx | 9 +++++++++ .../react-components/react-tree/stories/Tree/TreeSize.md | 1 + .../react-tree/stories/Tree/TreeSize.stories.tsx | 3 ++- .../react-tree/stories/Tree/TreeWithInlineStyle.md | 1 + .../stories/Tree/TreeWithInlineStyle.stories.tsx | 9 +++++++++ 22 files changed, 106 insertions(+), 5 deletions(-) create mode 100644 packages/react-components/react-tree/stories/Tree/TreeActions.md create mode 100644 packages/react-components/react-tree/stories/Tree/TreeAppearance.md create mode 100644 packages/react-components/react-tree/stories/Tree/TreeAside.md create mode 100644 packages/react-components/react-tree/stories/Tree/TreeControllingOpenAndClose.md create mode 100644 packages/react-components/react-tree/stories/Tree/TreeDefaultOpenTrees.md create mode 100644 packages/react-components/react-tree/stories/Tree/TreeExpandCollapseIconOnly.md create mode 100644 packages/react-components/react-tree/stories/Tree/TreeExpandIcon.md create mode 100644 packages/react-components/react-tree/stories/Tree/TreeIconAfter.md create mode 100644 packages/react-components/react-tree/stories/Tree/TreeIconBefore.md create mode 100644 packages/react-components/react-tree/stories/Tree/TreeSize.md create mode 100644 packages/react-components/react-tree/stories/Tree/TreeWithInlineStyle.md diff --git a/packages/react-components/react-tree/stories/Tree/TreeActions.md b/packages/react-components/react-tree/stories/Tree/TreeActions.md new file mode 100644 index 00000000000000..f199bcd996dd41 --- /dev/null +++ b/packages/react-components/react-tree/stories/Tree/TreeActions.md @@ -0,0 +1,3 @@ +The `Tree` component lets you add custom actions to each `TreeItem`, such as buttons or menus. This can be done by passing a component that renders the desired actions as a prop to the `TreeItem`. + +The `actions` are hidden by default and appear on the right side when the user hovers over the `TreeItem`, allowing for a clean and uncluttered display. diff --git a/packages/react-components/react-tree/stories/Tree/TreeActions.stories.tsx b/packages/react-components/react-tree/stories/Tree/TreeActions.stories.tsx index 9c765a3172e8cd..91a61b0a0db05e 100644 --- a/packages/react-components/react-tree/stories/Tree/TreeActions.stories.tsx +++ b/packages/react-components/react-tree/stories/Tree/TreeActions.stories.tsx @@ -2,6 +2,7 @@ import * as React from 'react'; import { Tree, TreeItem, TreeItemLayout } from '@fluentui/react-tree'; import { Edit20Regular, MoreHorizontal20Regular } from '@fluentui/react-icons'; import { Button, Menu, MenuItem, MenuList, MenuPopover, MenuTrigger } from '@fluentui/react-components'; +import story from './TreeActions.md'; const RenderActions = () => { return ( @@ -71,3 +72,11 @@ export const Actions = () => ( ); + +Actions.parameters = { + docs: { + description: { + story, + }, + }, +}; diff --git a/packages/react-components/react-tree/stories/Tree/TreeAppearance.md b/packages/react-components/react-tree/stories/Tree/TreeAppearance.md new file mode 100644 index 00000000000000..7583f9bbbc94cd --- /dev/null +++ b/packages/react-components/react-tree/stories/Tree/TreeAppearance.md @@ -0,0 +1 @@ +The `Tree` component supports different appearances for TreeItems. The default `appearance` is used when no appearance is specified. The `subtle` appearance minimizes emphasis on hovered or focused states, while the `transparent` appearance removes the background color. diff --git a/packages/react-components/react-tree/stories/Tree/TreeAppearance.stories.tsx b/packages/react-components/react-tree/stories/Tree/TreeAppearance.stories.tsx index 2d5edcbaa88e67..d23aca3bf0c566 100644 --- a/packages/react-components/react-tree/stories/Tree/TreeAppearance.stories.tsx +++ b/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, }, }, }; diff --git a/packages/react-components/react-tree/stories/Tree/TreeAside.md b/packages/react-components/react-tree/stories/Tree/TreeAside.md new file mode 100644 index 00000000000000..d205165dc8e46a --- /dev/null +++ b/packages/react-components/react-tree/stories/Tree/TreeAside.md @@ -0,0 +1 @@ +The `Tree` component allows for an `aside` prop to be added to individual `TreeItemLayout` or `TreeItemPersonaLayout` 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. diff --git a/packages/react-components/react-tree/stories/Tree/TreeAside.stories.tsx b/packages/react-components/react-tree/stories/Tree/TreeAside.stories.tsx index 65c77c1fb6d335..43545c80adb92c 100644 --- a/packages/react-components/react-tree/stories/Tree/TreeAside.stories.tsx +++ b/packages/react-components/react-tree/stories/Tree/TreeAside.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 './TreeAside.md'; const iconStyleProps: FluentIconsProps = { primaryFill: 'red', @@ -67,3 +68,11 @@ export const Aside = () => ( ); + +Aside.parameters = { + docs: { + description: { + story, + }, + }, +}; diff --git a/packages/react-components/react-tree/stories/Tree/TreeControllingOpenAndClose.md b/packages/react-components/react-tree/stories/Tree/TreeControllingOpenAndClose.md new file mode 100644 index 00000000000000..0e4a934b1922d9 --- /dev/null +++ b/packages/react-components/react-tree/stories/Tree/TreeControllingOpenAndClose.md @@ -0,0 +1,5 @@ +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. + +To control the open/closed state of a `TreeItem`, an `id` prop must be provided to the `TreeItem` component. This `id` prop can then be used to identify the `TreeItem` in the `handleOpenChange` function and update the `openItems` state. diff --git a/packages/react-components/react-tree/stories/Tree/TreeControllingOpenAndClose.stories.tsx b/packages/react-components/react-tree/stories/Tree/TreeControllingOpenAndClose.stories.tsx index 3144aed6a401b9..b8b92a732088a5 100644 --- a/packages/react-components/react-tree/stories/Tree/TreeControllingOpenAndClose.stories.tsx +++ b/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([]); @@ -47,3 +48,11 @@ export const OpenItemsControlled = () => { ); }; + +OpenItemsControlled.parameters = { + docs: { + description: { + story, + }, + }, +}; diff --git a/packages/react-components/react-tree/stories/Tree/TreeDefaultOpenTrees.md b/packages/react-components/react-tree/stories/Tree/TreeDefaultOpenTrees.md new file mode 100644 index 00000000000000..af5d41a2a6d049 --- /dev/null +++ b/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. diff --git a/packages/react-components/react-tree/stories/Tree/TreeDefaultOpenTrees.stories.tsx b/packages/react-components/react-tree/stories/Tree/TreeDefaultOpenTrees.stories.tsx index 7e53ddac1a3967..fa3dd1181a7d41 100644 --- a/packages/react-components/react-tree/stories/Tree/TreeDefaultOpenTrees.stories.tsx +++ b/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 = () => { ); }; + +DefaultOpenTrees.parameters = { + docs: { + description: { + story, + }, + }, +}; diff --git a/packages/react-components/react-tree/stories/Tree/TreeExpandCollapseIconOnly.md b/packages/react-components/react-tree/stories/Tree/TreeExpandCollapseIconOnly.md new file mode 100644 index 00000000000000..f79ce0dc4eb133 --- /dev/null +++ b/packages/react-components/react-tree/stories/Tree/TreeExpandCollapseIconOnly.md @@ -0,0 +1,3 @@ +By default, every `TreeItem` component that can be expanded or collapsed will respond to clicks on both the content and the expand/collapse icon. If you need to perform a different action when the `TreeItem` content is clicked, you can override this behavior. + +To do so, you can listen for the `onOpenChange` event in the root `Tree` component. When this event is triggered, you can check the type of the event data to determine whether the user clicked on the `TreeItem`'s content or the expand/collapse icon. This way, you can handle clicks on the content separately from expand/collapse events. diff --git a/packages/react-components/react-tree/stories/Tree/TreeExpandCollapseIconOnly.stories.tsx b/packages/react-components/react-tree/stories/Tree/TreeExpandCollapseIconOnly.stories.tsx index bdbdf6f2f9eced..680934dc03e9a7 100644 --- a/packages/react-components/react-tree/stories/Tree/TreeExpandCollapseIconOnly.stories.tsx +++ b/packages/react-components/react-tree/stories/Tree/TreeExpandCollapseIconOnly.stories.tsx @@ -1,6 +1,7 @@ import * as React from 'react'; import { Tree, TreeItem, TreeItemLayout } from '@fluentui/react-tree'; import { TreeOpenChangeData, TreeOpenChangeEvent } from '../../src/components/Tree/Tree.types'; +import story from './TreeExpandCollapseIconOnly.md'; export const ExpandCollapseIconOnly = () => { const onOpenChange = (event: TreeOpenChangeEvent, data: TreeOpenChangeData) => { @@ -43,3 +44,11 @@ export const ExpandCollapseIconOnly = () => { ); }; + +ExpandCollapseIconOnly.parameters = { + docs: { + description: { + story, + }, + }, +}; diff --git a/packages/react-components/react-tree/stories/Tree/TreeExpandIcon.md b/packages/react-components/react-tree/stories/Tree/TreeExpandIcon.md new file mode 100644 index 00000000000000..5a1cc26cd72f9c --- /dev/null +++ b/packages/react-components/react-tree/stories/Tree/TreeExpandIcon.md @@ -0,0 +1,3 @@ +By default, `Tree` component comes with default expand/collapse icons. However, if you wish to customize the icons, you can use the `expandIcon` property provided by the `TreeItem` component. + +To do this, you need to specify the `expandIcon` property for each expandable/collapsible `TreeItem`. The value of the expandIcon property can be any valid React component, which will be rendered in place of the default expand/collapse icon. diff --git a/packages/react-components/react-tree/stories/Tree/TreeExpandIcon.stories.tsx b/packages/react-components/react-tree/stories/Tree/TreeExpandIcon.stories.tsx index c15fc01d1d5796..1982839903d8b4 100644 --- a/packages/react-components/react-tree/stories/Tree/TreeExpandIcon.stories.tsx +++ b/packages/react-components/react-tree/stories/Tree/TreeExpandIcon.stories.tsx @@ -2,6 +2,7 @@ import * as React from 'react'; import { Tree, TreeItem, TreeItemLayout } from '@fluentui/react-tree'; import { Add12Regular, Subtract12Regular } from '@fluentui/react-icons'; import { TreeOpenChangeData, TreeOpenChangeEvent } from '../../src/Tree'; +import story from './TreeExpandIcon.md'; export const ExpandIcon = () => { const [openItems, setOpenItems] = React.useState([]); @@ -51,3 +52,11 @@ export const ExpandIcon = () => { ); }; + +ExpandIcon.parameters = { + docs: { + description: { + story, + }, + }, +}; diff --git a/packages/react-components/react-tree/stories/Tree/TreeIconAfter.md b/packages/react-components/react-tree/stories/Tree/TreeIconAfter.md new file mode 100644 index 00000000000000..c627c9d3ec0830 --- /dev/null +++ b/packages/react-components/react-tree/stories/Tree/TreeIconAfter.md @@ -0,0 +1 @@ +The `TreeItemLayout` and `TreePersonaItemLayout` components allow you to add icons before or after the text of each `TreeItem` component in a `Tree`. To add an icon before the text, use the `iconBefore` prop, and to add an icon after the text, use the `iconAfter` prop. diff --git a/packages/react-components/react-tree/stories/Tree/TreeIconAfter.stories.tsx b/packages/react-components/react-tree/stories/Tree/TreeIconAfter.stories.tsx index 7d3cb158a70c83..d10bb7149f153b 100644 --- a/packages/react-components/react-tree/stories/Tree/TreeIconAfter.stories.tsx +++ b/packages/react-components/react-tree/stories/Tree/TreeIconAfter.stories.tsx @@ -1,6 +1,7 @@ import * as React from 'react'; import { Tree, TreeItem, TreeItemLayout } from '@fluentui/react-tree'; import { LockClosed20Regular } from '@fluentui/react-icons'; +import story from './TreeIconAfter.md'; export const IconAfter = () => { return ( @@ -35,3 +36,11 @@ export const IconAfter = () => { ); }; + +IconAfter.parameters = { + docs: { + description: { + story, + }, + }, +}; diff --git a/packages/react-components/react-tree/stories/Tree/TreeIconBefore.md b/packages/react-components/react-tree/stories/Tree/TreeIconBefore.md new file mode 100644 index 00000000000000..c627c9d3ec0830 --- /dev/null +++ b/packages/react-components/react-tree/stories/Tree/TreeIconBefore.md @@ -0,0 +1 @@ +The `TreeItemLayout` and `TreePersonaItemLayout` components allow you to add icons before or after the text of each `TreeItem` component in a `Tree`. To add an icon before the text, use the `iconBefore` prop, and to add an icon after the text, use the `iconAfter` prop. diff --git a/packages/react-components/react-tree/stories/Tree/TreeIconBefore.stories.tsx b/packages/react-components/react-tree/stories/Tree/TreeIconBefore.stories.tsx index 00bbe0e165cc2e..77d8cacbd5b3c5 100644 --- a/packages/react-components/react-tree/stories/Tree/TreeIconBefore.stories.tsx +++ b/packages/react-components/react-tree/stories/Tree/TreeIconBefore.stories.tsx @@ -1,6 +1,7 @@ import * as React from 'react'; import { Tree, TreeItem, TreeItemLayout } from '@fluentui/react-tree'; import { CheckboxChecked20Filled, CheckboxUnchecked20Filled } from '@fluentui/react-icons'; +import story from './TreeIconBefore.md'; export const IconBefore = () => { return ( @@ -35,3 +36,11 @@ export const IconBefore = () => { ); }; + +IconBefore.parameters = { + docs: { + description: { + story, + }, + }, +}; diff --git a/packages/react-components/react-tree/stories/Tree/TreeSize.md b/packages/react-components/react-tree/stories/Tree/TreeSize.md new file mode 100644 index 00000000000000..5fbe0229008748 --- /dev/null +++ b/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. diff --git a/packages/react-components/react-tree/stories/Tree/TreeSize.stories.tsx b/packages/react-components/react-tree/stories/Tree/TreeSize.stories.tsx index 0ef71656b7562b..7e0f313612f458 100644 --- a/packages/react-components/react-tree/stories/Tree/TreeSize.stories.tsx +++ b/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, }, }, }; diff --git a/packages/react-components/react-tree/stories/Tree/TreeWithInlineStyle.md b/packages/react-components/react-tree/stories/Tree/TreeWithInlineStyle.md new file mode 100644 index 00000000000000..4eeeb230c9e7ce --- /dev/null +++ b/packages/react-components/react-tree/stories/Tree/TreeWithInlineStyle.md @@ -0,0 +1 @@ +The style applied to the `TreeItem` component can be easily overridden by passing a custom style object as a prop to the `TreeItem` component. This allows for greater flexibility in customizing the styling of the tree items. diff --git a/packages/react-components/react-tree/stories/Tree/TreeWithInlineStyle.stories.tsx b/packages/react-components/react-tree/stories/Tree/TreeWithInlineStyle.stories.tsx index ecaf7e95648ed4..031834cec1035f 100644 --- a/packages/react-components/react-tree/stories/Tree/TreeWithInlineStyle.stories.tsx +++ b/packages/react-components/react-tree/stories/Tree/TreeWithInlineStyle.stories.tsx @@ -7,6 +7,7 @@ import { TreeItemProps, useTreeContext_unstable, } from '@fluentui/react-tree'; +import story from './TreeWithInlineStyle.md'; const TreeItem = (props: TreeItemProps) => { const level = useTreeContext_unstable(ctx => ctx.level); @@ -46,3 +47,11 @@ export const WithInlineStyle = () => { ); }; + +WithInlineStyle.parameters = { + docs: { + description: { + story, + }, + }, +}; From 8ce1845a63d8adf61f1445ead71e9983470c825d Mon Sep 17 00:00:00 2001 From: Petr Duda Date: Mon, 20 Mar 2023 22:19:01 +0100 Subject: [PATCH 02/34] more --- .../react-tree/stories/Tree/TreeLayout.md | 5 ++ .../stories/Tree/TreeLayout.stories.tsx | 9 +++ .../react-tree/stories/Tree/Virtualization.md | 3 + .../stories/Tree/Virtualization.stories.tsx | 9 +++ .../react-tree/stories/Tree/flattenTree.md | 3 + .../stories/Tree/flattenTree.stories.tsx | 10 +++ .../react-tree/stories/Tree/index.stories.tsx | 1 - .../stories/Tree/useFlatTreeItems.stories.tsx | 74 ------------------- 8 files changed, 39 insertions(+), 75 deletions(-) create mode 100644 packages/react-components/react-tree/stories/Tree/TreeLayout.md create mode 100644 packages/react-components/react-tree/stories/Tree/Virtualization.md create mode 100644 packages/react-components/react-tree/stories/Tree/flattenTree.md delete mode 100644 packages/react-components/react-tree/stories/Tree/useFlatTreeItems.stories.tsx diff --git a/packages/react-components/react-tree/stories/Tree/TreeLayout.md b/packages/react-components/react-tree/stories/Tree/TreeLayout.md new file mode 100644 index 00000000000000..cc9c769c455046 --- /dev/null +++ b/packages/react-components/react-tree/stories/Tree/TreeLayout.md @@ -0,0 +1,5 @@ +An example of a tree with combinations of props `actions` in `TreeItem` and `aside` in `TreeItemLayout` component. + +This example demonstrates how to 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. + +Each prop is described individually and can be overridden as needed. diff --git a/packages/react-components/react-tree/stories/Tree/TreeLayout.stories.tsx b/packages/react-components/react-tree/stories/Tree/TreeLayout.stories.tsx index c76588ad8d6442..4421c7f1c7fcd4 100644 --- a/packages/react-components/react-tree/stories/Tree/TreeLayout.stories.tsx +++ b/packages/react-components/react-tree/stories/Tree/TreeLayout.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 './TreeLayout.md'; const iconStyleProps: FluentIconsProps = { primaryFill: 'red', @@ -102,3 +103,11 @@ export const Layout = () => { ); }; + +Layout.parameters = { + docs: { + description: { + story, + }, + }, +}; diff --git a/packages/react-components/react-tree/stories/Tree/Virtualization.md b/packages/react-components/react-tree/stories/Tree/Virtualization.md new file mode 100644 index 00000000000000..e9016b28685139 --- /dev/null +++ b/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 the overall performance of the tree. + +To achieve this, one can create a `flattened` version of the tree structure that can be easily consumed by a windowing library. This library renders only the items that are currently visible on the screen, which reduces the amount of memory required to run the application. diff --git a/packages/react-components/react-tree/stories/Tree/Virtualization.stories.tsx b/packages/react-components/react-tree/stories/Tree/Virtualization.stories.tsx index 1feef597e79268..a0a8f38f6e1659 100644 --- a/packages/react-components/react-tree/stories/Tree/Virtualization.stories.tsx +++ b/packages/react-components/react-tree/stories/Tree/Virtualization.stories.tsx @@ -16,6 +16,7 @@ import { } from '@fluentui/react-tree'; import { FixedSizeList, FixedSizeListProps, ListChildComponentProps } from 'react-window'; import { ForwardRefComponent, getSlots, useFluent } from '@fluentui/react-components'; +import story from './Virtualization.md'; const defaultItems: FlatTreeItemProps[] = [ { @@ -104,3 +105,11 @@ export const Virtualization = () => { /> ); }; + +Virtualization.parameters = { + docs: { + description: { + story, + }, + }, +}; diff --git a/packages/react-components/react-tree/stories/Tree/flattenTree.md b/packages/react-components/react-tree/stories/Tree/flattenTree.md new file mode 100644 index 00000000000000..9bf32b60f89407 --- /dev/null +++ b/packages/react-components/react-tree/stories/Tree/flattenTree.md @@ -0,0 +1,3 @@ +A `Tree` can be flattened, meaning that its nested structure is transformed into a flat list of items. This can be helpful when you need to display a tree in a linear fashion, such as in a list. + +In the code, the `defaultItems` array represents a flattened tree with each item containing the content to display. The `useFlatTree` hook transforms the flattened tree into a format that can be consumed by a `Tree` component. The `Tree` component handles rendering the nested structure, while the `useFlatTree` hook handles the logic for flattened data. diff --git a/packages/react-components/react-tree/stories/Tree/flattenTree.stories.tsx b/packages/react-components/react-tree/stories/Tree/flattenTree.stories.tsx index 0ca56473d8cfa5..60013bf4ba636d 100644 --- a/packages/react-components/react-tree/stories/Tree/flattenTree.stories.tsx +++ b/packages/react-components/react-tree/stories/Tree/flattenTree.stories.tsx @@ -1,5 +1,6 @@ import * as React from 'react'; import { Tree, TreeItem, TreeItemLayout, useFlatTree_unstable, flattenTree_unstable } from '@fluentui/react-tree'; +import story from './flattenTree.md'; const defaultItems = flattenTree_unstable([ { @@ -35,6 +36,7 @@ const defaultItems = flattenTree_unstable([ ], }, ]); + export const FlattenTree = () => { const flatTree = useFlatTree_unstable(defaultItems); return ( @@ -45,3 +47,11 @@ export const FlattenTree = () => { ); }; + +FlattenTree.parameters = { + docs: { + description: { + story, + }, + }, +}; diff --git a/packages/react-components/react-tree/stories/Tree/index.stories.tsx b/packages/react-components/react-tree/stories/Tree/index.stories.tsx index c642b6dabeca42..a042721286b943 100644 --- a/packages/react-components/react-tree/stories/Tree/index.stories.tsx +++ b/packages/react-components/react-tree/stories/Tree/index.stories.tsx @@ -16,7 +16,6 @@ export { Layout } from './TreeLayout.stories'; export { Size } from './TreeSize.stories'; export { Appearance } from './TreeAppearance.stories'; export { WithInlineStyle } from './TreeWithInlineStyle.stories'; -export { UseFlatTreeItems as useFlatTreeItems } from './useFlatTreeItems.stories'; export { FlattenTree as flattenTree } from './flattenTree.stories'; export { Virtualization } from './Virtualization.stories'; diff --git a/packages/react-components/react-tree/stories/Tree/useFlatTreeItems.stories.tsx b/packages/react-components/react-tree/stories/Tree/useFlatTreeItems.stories.tsx deleted file mode 100644 index 69e0e60242a51b..00000000000000 --- a/packages/react-components/react-tree/stories/Tree/useFlatTreeItems.stories.tsx +++ /dev/null @@ -1,74 +0,0 @@ -import * as React from 'react'; -import { Tree, TreeItem, TreeItemLayout, useFlatTree_unstable, FlatTreeItemProps } from '@fluentui/react-tree'; - -const defaultItems: FlatTreeItemProps[] = [ - { - id: '1', - children: Level 1, item 1, - }, - { - id: '1-1', - parentId: '1', - children: Level 2, item 1, - }, - { - id: '1-2', - parentId: '1', - children: Level 2, item 2, - }, - { - id: '1-3', - parentId: '1', - children: Level 2, item 3, - }, - { - id: '2', - children: Level 1, item 2, - }, - { - id: '2-1', - parentId: '2', - children: Level 2, item 1, - }, - { - id: '2-1-1', - parentId: '2-1', - children: Level 3, item 1, - }, - { - id: '2-2', - parentId: '2', - children: Level 2, item 2, - }, - { - id: '2-2-1', - parentId: '2-2', - children: Level 3, item 1, - }, - { - id: '2-2-2', - parentId: '2-2', - children: Level 3, item 2, - }, - { - id: '2-2-3', - parentId: '2-2', - children: Level 3, item 3, - }, - { - id: '3', - children: Level 1, item 3, - }, -]; - -export const UseFlatTreeItems = () => { - const flatTree = useFlatTree_unstable(defaultItems); - - return ( - - {Array.from(flatTree.items(), flatTreeItem => ( - - ))} - - ); -}; From d15b7d8f138e6ff6e23cac3f132f1394b588d267 Mon Sep 17 00:00:00 2001 From: Petr Duda Date: Mon, 20 Mar 2023 22:50:55 +0100 Subject: [PATCH 03/34] persona --- .../TreeItemPersonaLayout/TreeItemPersonaLayoutMedia.md | 3 +++ .../TreeItemPersonaLayoutMedia.stories.tsx | 9 +++++++++ .../TreeItemPersonaLayoutReadUnread.md | 3 +++ .../TreeItemPersonaLayoutReadUnread.stories.tsx | 9 +++++++++ .../TreeItemPersonaLayoutWithDescription.md | 1 + .../TreeItemPersonaLayoutWithDescription.stories.tsx | 9 +++++++++ 6 files changed, 34 insertions(+) create mode 100644 packages/react-components/react-tree/stories/TreeItemPersonaLayout/TreeItemPersonaLayoutMedia.md create mode 100644 packages/react-components/react-tree/stories/TreeItemPersonaLayout/TreeItemPersonaLayoutReadUnread.md create mode 100644 packages/react-components/react-tree/stories/TreeItemPersonaLayout/TreeItemPersonaLayoutWithDescription.md diff --git a/packages/react-components/react-tree/stories/TreeItemPersonaLayout/TreeItemPersonaLayoutMedia.md b/packages/react-components/react-tree/stories/TreeItemPersonaLayout/TreeItemPersonaLayoutMedia.md new file mode 100644 index 00000000000000..8b43955e7368fc --- /dev/null +++ b/packages/react-components/react-tree/stories/TreeItemPersonaLayout/TreeItemPersonaLayoutMedia.md @@ -0,0 +1,3 @@ +The `Tree` 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. Nested Tree components can also contain `TreeItem` components with `TreeItemPersonaLayout` components with different media components. This layout provides a visually appealing representation of hierarchical data. diff --git a/packages/react-components/react-tree/stories/TreeItemPersonaLayout/TreeItemPersonaLayoutMedia.stories.tsx b/packages/react-components/react-tree/stories/TreeItemPersonaLayout/TreeItemPersonaLayoutMedia.stories.tsx index 4decbda8d4598d..e8c47e1d15c2cb 100644 --- a/packages/react-components/react-tree/stories/TreeItemPersonaLayout/TreeItemPersonaLayoutMedia.stories.tsx +++ b/packages/react-components/react-tree/stories/TreeItemPersonaLayout/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 = () => { ); }; + +Media.parameters = { + docs: { + description: { + story, + }, + }, +}; diff --git a/packages/react-components/react-tree/stories/TreeItemPersonaLayout/TreeItemPersonaLayoutReadUnread.md b/packages/react-components/react-tree/stories/TreeItemPersonaLayout/TreeItemPersonaLayoutReadUnread.md new file mode 100644 index 00000000000000..8a9ba088ccf2da --- /dev/null +++ b/packages/react-components/react-tree/stories/TreeItemPersonaLayout/TreeItemPersonaLayoutReadUnread.md @@ -0,0 +1,3 @@ +The `Tree` component can be customized with different styles to make it more visually appealing. In the example below, the `TreeItemPersonaLayout` component is used to display messages with a `description` and an `Avatar` as the `media` prop. + +The `description` prop is used to provide a secondary text content that can be customized with styles. In this case, the unread class from the `makeStyles` hook is applied to the div element to make the text appear `bold` for unread messages. diff --git a/packages/react-components/react-tree/stories/TreeItemPersonaLayout/TreeItemPersonaLayoutReadUnread.stories.tsx b/packages/react-components/react-tree/stories/TreeItemPersonaLayout/TreeItemPersonaLayoutReadUnread.stories.tsx index fb6df6d7b88769..e8ff0fbab60928 100644 --- a/packages/react-components/react-tree/stories/TreeItemPersonaLayout/TreeItemPersonaLayoutReadUnread.stories.tsx +++ b/packages/react-components/react-tree/stories/TreeItemPersonaLayout/TreeItemPersonaLayoutReadUnread.stories.tsx @@ -1,6 +1,7 @@ import * as React from 'react'; import { Avatar, makeStyles } from '@fluentui/react-components'; import { Tree, TreeItem, TreeItemPersonaLayout } from '@fluentui/react-tree'; +import story from './TreeItemPersonaLayoutReadUnread.md'; const useStyles = makeStyles({ unread: { @@ -29,3 +30,11 @@ export const ReadUnread = () => { ); }; + +ReadUnread.parameters = { + docs: { + description: { + story, + }, + }, +}; diff --git a/packages/react-components/react-tree/stories/TreeItemPersonaLayout/TreeItemPersonaLayoutWithDescription.md b/packages/react-components/react-tree/stories/TreeItemPersonaLayout/TreeItemPersonaLayoutWithDescription.md new file mode 100644 index 00000000000000..3fe22df2bf7277 --- /dev/null +++ b/packages/react-components/react-tree/stories/TreeItemPersonaLayout/TreeItemPersonaLayoutWithDescription.md @@ -0,0 +1 @@ +The `TreeItemPersonaLayout` component allows you to add a `description` prop 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. diff --git a/packages/react-components/react-tree/stories/TreeItemPersonaLayout/TreeItemPersonaLayoutWithDescription.stories.tsx b/packages/react-components/react-tree/stories/TreeItemPersonaLayout/TreeItemPersonaLayoutWithDescription.stories.tsx index 3beace7f217c82..feb24dad41aada 100644 --- a/packages/react-components/react-tree/stories/TreeItemPersonaLayout/TreeItemPersonaLayoutWithDescription.stories.tsx +++ b/packages/react-components/react-tree/stories/TreeItemPersonaLayout/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 = () => { ); }; + +WithDescription.parameters = { + docs: { + description: { + story, + }, + }, +}; From 65f57c45abc5b731eb11507481507ea4b997bf68 Mon Sep 17 00:00:00 2001 From: Petr Duda Date: Mon, 20 Mar 2023 23:15:39 +0100 Subject: [PATCH 04/34] simplifiy --- .../react-tree/stories/Tree/TreeActions.md | 2 +- .../stories/Tree/TreeBestPractices.md | 31 +++++++++++++++++-- .../react-tree/stories/Tree/TreeIconAfter.md | 1 - .../stories/Tree/TreeIconAfter.stories.tsx | 9 ------ .../react-tree/stories/Tree/TreeIconBefore.md | 2 ++ .../react-tree/stories/Tree/TreeLayout.md | 4 --- .../react-tree/stories/Tree/index.stories.tsx | 14 ++++----- 7 files changed, 39 insertions(+), 24 deletions(-) delete mode 100644 packages/react-components/react-tree/stories/Tree/TreeIconAfter.md diff --git a/packages/react-components/react-tree/stories/Tree/TreeActions.md b/packages/react-components/react-tree/stories/Tree/TreeActions.md index f199bcd996dd41..8c24f1d25388a2 100644 --- a/packages/react-components/react-tree/stories/Tree/TreeActions.md +++ b/packages/react-components/react-tree/stories/Tree/TreeActions.md @@ -1,3 +1,3 @@ -The `Tree` component lets you add custom actions to each `TreeItem`, such as buttons or menus. This can be done by passing a component that renders the desired actions as a prop to the `TreeItem`. +Add custom actions to each `TreeItem` component to add extra functionality, such as buttons or menus. This can be done by passing a component that renders the desired actions as a prop to the `TreeItem`. The `actions` are hidden by default and appear on the right side when the user hovers over the `TreeItem`, allowing for a clean and uncluttered display. diff --git a/packages/react-components/react-tree/stories/Tree/TreeBestPractices.md b/packages/react-components/react-tree/stories/Tree/TreeBestPractices.md index 08ff8ddeeb5f86..94960d06967cd7 100644 --- a/packages/react-components/react-tree/stories/Tree/TreeBestPractices.md +++ b/packages/react-components/react-tree/stories/Tree/TreeBestPractices.md @@ -1,5 +1,32 @@ -## Best practices + diff --git a/packages/react-components/react-tree/stories/Tree/TreeIconAfter.md b/packages/react-components/react-tree/stories/Tree/TreeIconAfter.md deleted file mode 100644 index c627c9d3ec0830..00000000000000 --- a/packages/react-components/react-tree/stories/Tree/TreeIconAfter.md +++ /dev/null @@ -1 +0,0 @@ -The `TreeItemLayout` and `TreePersonaItemLayout` components allow you to add icons before or after the text of each `TreeItem` component in a `Tree`. To add an icon before the text, use the `iconBefore` prop, and to add an icon after the text, use the `iconAfter` prop. diff --git a/packages/react-components/react-tree/stories/Tree/TreeIconAfter.stories.tsx b/packages/react-components/react-tree/stories/Tree/TreeIconAfter.stories.tsx index d10bb7149f153b..7d3cb158a70c83 100644 --- a/packages/react-components/react-tree/stories/Tree/TreeIconAfter.stories.tsx +++ b/packages/react-components/react-tree/stories/Tree/TreeIconAfter.stories.tsx @@ -1,7 +1,6 @@ import * as React from 'react'; import { Tree, TreeItem, TreeItemLayout } from '@fluentui/react-tree'; import { LockClosed20Regular } from '@fluentui/react-icons'; -import story from './TreeIconAfter.md'; export const IconAfter = () => { return ( @@ -36,11 +35,3 @@ export const IconAfter = () => { ); }; - -IconAfter.parameters = { - docs: { - description: { - story, - }, - }, -}; diff --git a/packages/react-components/react-tree/stories/Tree/TreeIconBefore.md b/packages/react-components/react-tree/stories/Tree/TreeIconBefore.md index c627c9d3ec0830..f4e61911552d73 100644 --- a/packages/react-components/react-tree/stories/Tree/TreeIconBefore.md +++ b/packages/react-components/react-tree/stories/Tree/TreeIconBefore.md @@ -1 +1,3 @@ The `TreeItemLayout` and `TreePersonaItemLayout` components allow you to add icons before or after the text of each `TreeItem` component in a `Tree`. To add an icon before the text, use the `iconBefore` prop, and to add an icon after the text, use the `iconAfter` prop. + +You can add combine them if you need both: diff --git a/packages/react-components/react-tree/stories/Tree/TreeLayout.md b/packages/react-components/react-tree/stories/Tree/TreeLayout.md index cc9c769c455046..38442a441221cc 100644 --- a/packages/react-components/react-tree/stories/Tree/TreeLayout.md +++ b/packages/react-components/react-tree/stories/Tree/TreeLayout.md @@ -1,5 +1 @@ -An example of a tree with combinations of props `actions` in `TreeItem` and `aside` in `TreeItemLayout` component. - This example demonstrates how to 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. - -Each prop is described individually and can be overridden as needed. diff --git a/packages/react-components/react-tree/stories/Tree/index.stories.tsx b/packages/react-components/react-tree/stories/Tree/index.stories.tsx index a042721286b943..0ff805dd3ed327 100644 --- a/packages/react-components/react-tree/stories/Tree/index.stories.tsx +++ b/packages/react-components/react-tree/stories/Tree/index.stories.tsx @@ -4,20 +4,20 @@ import descriptionMd from './TreeDescription.md'; import bestPracticesMd from './TreeBestPractices.md'; export { Default } from './TreeDefault.stories'; -export { OpenItemsControlled } from './TreeControllingOpenAndClose.stories'; -export { ExpandCollapseIconOnly } from './TreeExpandCollapseIconOnly.stories'; export { DefaultOpenTrees } from './TreeDefaultOpenTrees.stories'; -export { Actions } from './TreeActions.stories'; -export { Aside } from './TreeAside.stories'; export { ExpandIcon } from './TreeExpandIcon.stories'; export { IconBefore } from './TreeIconBefore.stories'; export { IconAfter } from './TreeIconAfter.stories'; -export { Layout } from './TreeLayout.stories'; -export { Size } from './TreeSize.stories'; +export { Actions } from './TreeActions.stories'; +export { Aside } from './TreeAside.stories'; export { Appearance } from './TreeAppearance.stories'; -export { WithInlineStyle } from './TreeWithInlineStyle.stories'; +export { Size } from './TreeSize.stories'; +export { Layout } from './TreeLayout.stories'; +export { OpenItemsControlled } from './TreeControllingOpenAndClose.stories'; +export { ExpandCollapseIconOnly } from './TreeExpandCollapseIconOnly.stories'; export { FlattenTree as flattenTree } from './flattenTree.stories'; export { Virtualization } from './Virtualization.stories'; +export { WithInlineStyle } from './TreeWithInlineStyle.stories'; export default { title: 'Preview Components/Tree', From 9267728de58c9d1903f0255ce732390189b7b582 Mon Sep 17 00:00:00 2001 From: Petr Duda Date: Mon, 20 Mar 2023 23:16:16 +0100 Subject: [PATCH 05/34] description --- .../react-tree/stories/Tree/TreeDescription.md | 13 +------------ .../react-tree/stories/Tree/TreeExpandIcon.md | 4 ++-- 2 files changed, 3 insertions(+), 14 deletions(-) diff --git a/packages/react-components/react-tree/stories/Tree/TreeDescription.md b/packages/react-components/react-tree/stories/Tree/TreeDescription.md index 73f177d09a492f..7ceb91d972df25 100644 --- a/packages/react-components/react-tree/stories/Tree/TreeDescription.md +++ b/packages/react-components/react-tree/stories/Tree/TreeDescription.md @@ -1,12 +1 @@ - - -> **⚠️ Preview components are considered unstable:** -> -> ```jsx -> -> import { Tree } from '@fluentui/react-components/unstable'; -> -> ``` -> -> - Features and APIs may change before final release -> - Please contact us if you intend to use this in your product +`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. diff --git a/packages/react-components/react-tree/stories/Tree/TreeExpandIcon.md b/packages/react-components/react-tree/stories/Tree/TreeExpandIcon.md index 5a1cc26cd72f9c..52316cde22ea31 100644 --- a/packages/react-components/react-tree/stories/Tree/TreeExpandIcon.md +++ b/packages/react-components/react-tree/stories/Tree/TreeExpandIcon.md @@ -1,3 +1,3 @@ -By default, `Tree` component comes with default expand/collapse icons. However, if you wish to customize the icons, you can use the `expandIcon` property provided by the `TreeItem` component. +If you wish to customize the open/collapse icons, you can use the `expandIcon` property provided by the `TreeItem` component. -To do this, you need to specify the `expandIcon` property for each expandable/collapsible `TreeItem`. The value of the expandIcon property can be any valid React component, which will be rendered in place of the default expand/collapse icon. +This example replaces the default expand/collapse arrow icons with plus and minus characters to achieve a similar behavior. From fbf57b778425b25b4f115c5c1d81831063b35ca5 Mon Sep 17 00:00:00 2001 From: Petr Duda Date: Tue, 21 Mar 2023 11:10:55 +0100 Subject: [PATCH 06/34] persona and changes --- .../src/components/TreeItemLayout/TreeItemLayout.tsx | 5 ++++- .../TreeItemPersonaLayout/TreeItemPersonaLayout.tsx | 4 +++- .../react-tree/stories/Tree/TreeActions.md | 2 +- .../react-tree/stories/Tree/TreeAppearance.md | 2 +- .../react-tree/stories/Tree/TreeAside.md | 2 +- .../react-tree/stories/Tree/TreeAside.stories.tsx | 4 ++-- .../stories/Tree/TreeControllingOpenAndClose.md | 2 -- .../react-tree/stories/Tree/TreeIconBefore.md | 4 ++-- .../react-tree/stories/Tree/TreeLayout.md | 2 +- .../TreeItemPersonaLayoutDescription.md | 1 + .../TreeItemPersonaLayout/TreeItemPersonaLayoutMedia.md | 4 ++-- .../TreeItemPersonaLayoutReadUnread.md | 4 +--- .../TreeItemPersonaLayoutReadUnread.stories.tsx | 4 ++-- .../TreeItemPersonaLayoutWithDescription.md | 2 +- .../stories/TreeItemPersonaLayout/TreePersonaLayout.md | 1 + .../TreeItemPersonaLayout/TreePersonaLayout.stories.tsx | 9 +++++++++ .../stories/TreeItemPersonaLayout/index.stories.tsx | 6 ++---- 17 files changed, 34 insertions(+), 24 deletions(-) create mode 100644 packages/react-components/react-tree/stories/TreeItemPersonaLayout/TreePersonaLayout.md diff --git a/packages/react-components/react-tree/src/components/TreeItemLayout/TreeItemLayout.tsx b/packages/react-components/react-tree/src/components/TreeItemLayout/TreeItemLayout.tsx index 9eb0c32604cc56..2d36db6755de5c 100644 --- a/packages/react-components/react-tree/src/components/TreeItemLayout/TreeItemLayout.tsx +++ b/packages/react-components/react-tree/src/components/TreeItemLayout/TreeItemLayout.tsx @@ -6,8 +6,11 @@ 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 = React.forwardRef((props, ref) => { const state = useTreeItemLayout_unstable(props, ref); diff --git a/packages/react-components/react-tree/src/components/TreeItemPersonaLayout/TreeItemPersonaLayout.tsx b/packages/react-components/react-tree/src/components/TreeItemPersonaLayout/TreeItemPersonaLayout.tsx index 9e5b8f44b762ff..55ede65c081c02 100644 --- a/packages/react-components/react-tree/src/components/TreeItemPersonaLayout/TreeItemPersonaLayout.tsx +++ b/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 = React.forwardRef((props, ref) => { const state = useTreeItemPersonaLayout_unstable(props, ref); diff --git a/packages/react-components/react-tree/stories/Tree/TreeActions.md b/packages/react-components/react-tree/stories/Tree/TreeActions.md index 8c24f1d25388a2..385a3148f42c42 100644 --- a/packages/react-components/react-tree/stories/Tree/TreeActions.md +++ b/packages/react-components/react-tree/stories/Tree/TreeActions.md @@ -1,3 +1,3 @@ Add custom actions to each `TreeItem` component to add extra functionality, such as buttons or menus. This can be done by passing a component that renders the desired actions as a prop to the `TreeItem`. -The `actions` are hidden by default and appear on the right side when the user hovers over the `TreeItem`, allowing for a clean and uncluttered display. +The `actions` are hidden by default and appear on the right-side when the user hovers over the `TreeItem`. diff --git a/packages/react-components/react-tree/stories/Tree/TreeAppearance.md b/packages/react-components/react-tree/stories/Tree/TreeAppearance.md index 7583f9bbbc94cd..19f6bcf3eda8cd 100644 --- a/packages/react-components/react-tree/stories/Tree/TreeAppearance.md +++ b/packages/react-components/react-tree/stories/Tree/TreeAppearance.md @@ -1 +1 @@ -The `Tree` component supports different appearances for TreeItems. The default `appearance` is used when no appearance is specified. The `subtle` appearance minimizes emphasis on hovered or focused states, while the `transparent` appearance removes the background color. +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. diff --git a/packages/react-components/react-tree/stories/Tree/TreeAside.md b/packages/react-components/react-tree/stories/Tree/TreeAside.md index d205165dc8e46a..495cf8d10096b0 100644 --- a/packages/react-components/react-tree/stories/Tree/TreeAside.md +++ b/packages/react-components/react-tree/stories/Tree/TreeAside.md @@ -1 +1 @@ -The `Tree` component allows for an `aside` prop to be added to individual `TreeItemLayout` or `TreeItemPersonaLayout` 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. +The `Tree` component allows for an `aside` prop to be added to individual `TreeItemLayout` or `TreeItemPersonaLayout` 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. diff --git a/packages/react-components/react-tree/stories/Tree/TreeAside.stories.tsx b/packages/react-components/react-tree/stories/Tree/TreeAside.stories.tsx index 43545c80adb92c..08991de00650f9 100644 --- a/packages/react-components/react-tree/stories/Tree/TreeAside.stories.tsx +++ b/packages/react-components/react-tree/stories/Tree/TreeAside.stories.tsx @@ -24,7 +24,7 @@ const Actions = () => ( export const Aside = () => ( - }> + }>level 1, item 1 }> @@ -38,7 +38,7 @@ export const Aside = () => ( - }> + }>level 1, item 2 }> diff --git a/packages/react-components/react-tree/stories/Tree/TreeControllingOpenAndClose.md b/packages/react-components/react-tree/stories/Tree/TreeControllingOpenAndClose.md index 0e4a934b1922d9..ec78c4c204dc7d 100644 --- a/packages/react-components/react-tree/stories/Tree/TreeControllingOpenAndClose.md +++ b/packages/react-components/react-tree/stories/Tree/TreeControllingOpenAndClose.md @@ -1,5 +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. - -To control the open/closed state of a `TreeItem`, an `id` prop must be provided to the `TreeItem` component. This `id` prop can then be used to identify the `TreeItem` in the `handleOpenChange` function and update the `openItems` state. diff --git a/packages/react-components/react-tree/stories/Tree/TreeIconBefore.md b/packages/react-components/react-tree/stories/Tree/TreeIconBefore.md index f4e61911552d73..45a4887f6732d9 100644 --- a/packages/react-components/react-tree/stories/Tree/TreeIconBefore.md +++ b/packages/react-components/react-tree/stories/Tree/TreeIconBefore.md @@ -1,3 +1,3 @@ -The `TreeItemLayout` and `TreePersonaItemLayout` components allow you to add icons before or after the text of each `TreeItem` component in a `Tree`. To add an icon before the text, use the `iconBefore` prop, and to add an icon after the text, use the `iconAfter` prop. +The `TreeItemLayout` and `TreePersonaItemLayout` components allow you to add icons before or after the content of each `TreeItem` component. To add an icon before the text, use the `iconBefore` prop, and to add an icon after the text, use the `iconAfter` prop. -You can add combine them if you need both: +You can add both at the same time. diff --git a/packages/react-components/react-tree/stories/Tree/TreeLayout.md b/packages/react-components/react-tree/stories/Tree/TreeLayout.md index 38442a441221cc..da5e107408907b 100644 --- a/packages/react-components/react-tree/stories/Tree/TreeLayout.md +++ b/packages/react-components/react-tree/stories/Tree/TreeLayout.md @@ -1 +1 @@ -This example demonstrates how to 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. +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. diff --git a/packages/react-components/react-tree/stories/TreeItemPersonaLayout/TreeItemPersonaLayoutDescription.md b/packages/react-components/react-tree/stories/TreeItemPersonaLayout/TreeItemPersonaLayoutDescription.md index e69de29bb2d1d6..6130dc586949aa 100644 --- a/packages/react-components/react-tree/stories/TreeItemPersonaLayout/TreeItemPersonaLayoutDescription.md +++ b/packages/react-components/react-tree/stories/TreeItemPersonaLayout/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. diff --git a/packages/react-components/react-tree/stories/TreeItemPersonaLayout/TreeItemPersonaLayoutMedia.md b/packages/react-components/react-tree/stories/TreeItemPersonaLayout/TreeItemPersonaLayoutMedia.md index 8b43955e7368fc..ae06924ccf5c82 100644 --- a/packages/react-components/react-tree/stories/TreeItemPersonaLayout/TreeItemPersonaLayoutMedia.md +++ b/packages/react-components/react-tree/stories/TreeItemPersonaLayout/TreeItemPersonaLayoutMedia.md @@ -1,3 +1,3 @@ -The `Tree` component allows each `TreeItem` to be displayed with a persona layout, which supports a `media` prop such as an `Avatar`. +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. Nested Tree components can also contain `TreeItem` components with `TreeItemPersonaLayout` components with different media components. This layout provides a visually appealing representation of hierarchical data. +The `Avatar` component can be customized with different sizes and shapes to suit the design needs. diff --git a/packages/react-components/react-tree/stories/TreeItemPersonaLayout/TreeItemPersonaLayoutReadUnread.md b/packages/react-components/react-tree/stories/TreeItemPersonaLayout/TreeItemPersonaLayoutReadUnread.md index 8a9ba088ccf2da..eff0fde898036a 100644 --- a/packages/react-components/react-tree/stories/TreeItemPersonaLayout/TreeItemPersonaLayoutReadUnread.md +++ b/packages/react-components/react-tree/stories/TreeItemPersonaLayout/TreeItemPersonaLayoutReadUnread.md @@ -1,3 +1 @@ -The `Tree` component can be customized with different styles to make it more visually appealing. In the example below, the `TreeItemPersonaLayout` component is used to display messages with a `description` and an `Avatar` as the `media` prop. - -The `description` prop is used to provide a secondary text content that can be customized with styles. In this case, the unread class from the `makeStyles` hook is applied to the div element to make the text appear `bold` for unread messages. +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. diff --git a/packages/react-components/react-tree/stories/TreeItemPersonaLayout/TreeItemPersonaLayoutReadUnread.stories.tsx b/packages/react-components/react-tree/stories/TreeItemPersonaLayout/TreeItemPersonaLayoutReadUnread.stories.tsx index e8ff0fbab60928..a3a1ddddffb7ba 100644 --- a/packages/react-components/react-tree/stories/TreeItemPersonaLayout/TreeItemPersonaLayoutReadUnread.stories.tsx +++ b/packages/react-components/react-tree/stories/TreeItemPersonaLayout/TreeItemPersonaLayoutReadUnread.stories.tsx @@ -1,11 +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, }, }); diff --git a/packages/react-components/react-tree/stories/TreeItemPersonaLayout/TreeItemPersonaLayoutWithDescription.md b/packages/react-components/react-tree/stories/TreeItemPersonaLayout/TreeItemPersonaLayoutWithDescription.md index 3fe22df2bf7277..7ce381c22ba3b9 100644 --- a/packages/react-components/react-tree/stories/TreeItemPersonaLayout/TreeItemPersonaLayoutWithDescription.md +++ b/packages/react-components/react-tree/stories/TreeItemPersonaLayout/TreeItemPersonaLayoutWithDescription.md @@ -1 +1 @@ -The `TreeItemPersonaLayout` component allows you to add a `description` prop 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. +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. diff --git a/packages/react-components/react-tree/stories/TreeItemPersonaLayout/TreePersonaLayout.md b/packages/react-components/react-tree/stories/TreeItemPersonaLayout/TreePersonaLayout.md new file mode 100644 index 00000000000000..8778ca825b31c1 --- /dev/null +++ b/packages/react-components/react-tree/stories/TreeItemPersonaLayout/TreePersonaLayout.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. diff --git a/packages/react-components/react-tree/stories/TreeItemPersonaLayout/TreePersonaLayout.stories.tsx b/packages/react-components/react-tree/stories/TreeItemPersonaLayout/TreePersonaLayout.stories.tsx index 563ceb09703b92..1b72ba67dd50a2 100644 --- a/packages/react-components/react-tree/stories/TreeItemPersonaLayout/TreePersonaLayout.stories.tsx +++ b/packages/react-components/react-tree/stories/TreeItemPersonaLayout/TreePersonaLayout.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 './TreePersonaLayout.md'; const useBadgeStyles = makeStyles({ base: { @@ -132,3 +133,11 @@ export const TreePersonaLayout = () => { ); }; + +TreePersonaLayout.parameters = { + docs: { + description: { + story, + }, + }, +}; diff --git a/packages/react-components/react-tree/stories/TreeItemPersonaLayout/index.stories.tsx b/packages/react-components/react-tree/stories/TreeItemPersonaLayout/index.stories.tsx index f4134a0adaa11c..1694ff66f88245 100644 --- a/packages/react-components/react-tree/stories/TreeItemPersonaLayout/index.stories.tsx +++ b/packages/react-components/react-tree/stories/TreeItemPersonaLayout/index.stories.tsx @@ -1,12 +1,10 @@ import { TreeItemPersonaLayout } from '@fluentui/react-tree'; - import descriptionMd from './TreeItemPersonaLayoutDescription.md'; - export { Default } from './TreeItemPersonaLayoutDefault.stories'; -export { TreePersonaLayout } from './TreePersonaLayout.stories'; +export { Media } from './TreeItemPersonaLayoutMedia.stories'; export { WithDescription } from './TreeItemPersonaLayoutWithDescription.stories'; export { ReadUnread } from './TreeItemPersonaLayoutReadUnread.stories'; -export { Media } from './TreeItemPersonaLayoutMedia.stories'; +export { TreePersonaLayout } from './TreePersonaLayout.stories'; export default { title: 'Preview Components/Tree/PersonaTreeItem', From 2adef64e9b57d98f5542d762c7bda41a7d005edc Mon Sep 17 00:00:00 2001 From: Petr Duda Date: Tue, 21 Mar 2023 12:59:59 +0100 Subject: [PATCH 07/34] update desc --- .../react-tree/src/components/TreeItem/TreeItem.tsx | 9 ++++++++- .../src/components/TreeItemLayout/TreeItemLayout.tsx | 1 - .../react-tree/stories/Tree/TreeWithInlineStyle.md | 4 +++- 3 files changed, 11 insertions(+), 3 deletions(-) diff --git a/packages/react-components/react-tree/src/components/TreeItem/TreeItem.tsx b/packages/react-components/react-tree/src/components/TreeItem/TreeItem.tsx index 58c032dee313ff..2acdd0908ff19a 100644 --- a/packages/react-components/react-tree/src/components/TreeItem/TreeItem.tsx +++ b/packages/react-components/react-tree/src/components/TreeItem/TreeItem.tsx @@ -7,7 +7,14 @@ 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 can contain child items in the form of another Tree component or standalone TreeItem. + * 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 child items, an expand/collapse control is displayed, + * allowing the user to show or hide the children. + * This provides a convenient way to navigate hierarchical data, such as a file system or a category tree. */ export const TreeItem: ForwardRefComponent = React.forwardRef((props, ref) => { const state = useTreeItem_unstable(props, ref); diff --git a/packages/react-components/react-tree/src/components/TreeItemLayout/TreeItemLayout.tsx b/packages/react-components/react-tree/src/components/TreeItemLayout/TreeItemLayout.tsx index 2d36db6755de5c..7de4b11e7d2a2f 100644 --- a/packages/react-components/react-tree/src/components/TreeItemLayout/TreeItemLayout.tsx +++ b/packages/react-components/react-tree/src/components/TreeItemLayout/TreeItemLayout.tsx @@ -10,7 +10,6 @@ import type { ForwardRefComponent } from '@fluentui/react-utilities'; * 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 = React.forwardRef((props, ref) => { const state = useTreeItemLayout_unstable(props, ref); diff --git a/packages/react-components/react-tree/stories/Tree/TreeWithInlineStyle.md b/packages/react-components/react-tree/stories/Tree/TreeWithInlineStyle.md index 4eeeb230c9e7ce..0cd87707272ef0 100644 --- a/packages/react-components/react-tree/stories/Tree/TreeWithInlineStyle.md +++ b/packages/react-components/react-tree/stories/Tree/TreeWithInlineStyle.md @@ -1 +1,3 @@ -The style applied to the `TreeItem` component can be easily overridden by passing a custom style object as a prop to the `TreeItem` component. This allows for greater flexibility in customizing the styling of the tree items. +We support nested styling for the `Tree` component up to 10 levels of nesting due to performance implications. If you need to support more than 10 levels of nesting, you should consider using dynamic styling instead. + +The example below shows how to apply custom styles to `TreeItem` using inline styles to override the default static styles. From 71892ed9ee3ec8599253165b3029c565c8e67b16 Mon Sep 17 00:00:00 2001 From: Petr Duda Date: Wed, 22 Mar 2023 10:01:34 +0100 Subject: [PATCH 08/34] folder structure --- .../TreeItemLayout.md} | 0 .../TreeItemLayout.stories.tsx} | 2 +- .../stories/Layouts/TreeItemLayoutAside.md | 1 + .../TreeItemLayoutAside.stories.tsx} | 2 +- .../Layouts/TreeItemLayoutDefault.stories.tsx | 36 +++++++++++++++++++ .../TreeItemPersonaLayout.md} | 0 .../TreeItemPersonaLayout.stories.tsx} | 2 +- .../TreeItemPersonaLayoutDefault.stories.tsx | 2 +- .../TreeItemPersonaLayoutDescription.md | 0 .../TreeItemPersonaLayoutMedia.md | 0 .../TreeItemPersonaLayoutMedia.stories.tsx | 0 .../TreeItemPersonaLayoutReadUnread.md | 0 ...reeItemPersonaLayoutReadUnread.stories.tsx | 0 .../TreeItemPersonaLayoutWithDescription.md | 0 ...emPersonaLayoutWithDescription.stories.tsx | 0 .../react-tree/stories/Layouts/description.md | 5 +++ .../stories/Layouts/index.stories.tsx | 23 ++++++++++++ .../react-tree/stories/Tree/TreeAside.md | 1 - .../react-tree/stories/Tree/index.stories.tsx | 13 ++----- .../TreeItemActions.md} | 0 .../TreeItemActions.stories.tsx} | 2 +- .../TreeItem/TreeItemDefault.stories.tsx | 36 +++++++++++++++++++ .../stories/TreeItem/TreeItemDescription.md | 3 ++ .../TreeItemExpandCollapseIconOnly.md} | 0 ...reeItemExpandCollapseIconOnly.stories.tsx} | 2 +- .../TreeItemExpandIcon.md} | 0 .../TreeItemExpandIcon.stories.tsx} | 2 +- .../TreeItemIconAfter.stories.tsx} | 0 .../TreeItemIconBefore.md} | 0 .../TreeItemIconBefore.stories.tsx} | 2 +- .../TreeItemWithInlineStyle.md} | 0 .../TreeItemWithInlineStyle.stories.tsx} | 2 +- .../stories/TreeItem/index.stories.tsx | 23 ++++++++++++ .../TreeItemPersonaLayout/index.stories.tsx | 19 ---------- 34 files changed, 139 insertions(+), 39 deletions(-) rename packages/react-components/react-tree/stories/{Tree/TreeLayout.md => Layouts/TreeItemLayout.md} (100%) rename packages/react-components/react-tree/stories/{Tree/TreeLayout.stories.tsx => Layouts/TreeItemLayout.stories.tsx} (98%) create mode 100644 packages/react-components/react-tree/stories/Layouts/TreeItemLayoutAside.md rename packages/react-components/react-tree/stories/{Tree/TreeAside.stories.tsx => Layouts/TreeItemLayoutAside.stories.tsx} (98%) create mode 100644 packages/react-components/react-tree/stories/Layouts/TreeItemLayoutDefault.stories.tsx rename packages/react-components/react-tree/stories/{TreeItemPersonaLayout/TreePersonaLayout.md => Layouts/TreeItemPersonaLayout.md} (100%) rename packages/react-components/react-tree/stories/{TreeItemPersonaLayout/TreePersonaLayout.stories.tsx => Layouts/TreeItemPersonaLayout.stories.tsx} (98%) rename packages/react-components/react-tree/stories/{TreeItemPersonaLayout => Layouts}/TreeItemPersonaLayoutDefault.stories.tsx (95%) rename packages/react-components/react-tree/stories/{TreeItemPersonaLayout => Layouts}/TreeItemPersonaLayoutDescription.md (100%) rename packages/react-components/react-tree/stories/{TreeItemPersonaLayout => Layouts}/TreeItemPersonaLayoutMedia.md (100%) rename packages/react-components/react-tree/stories/{TreeItemPersonaLayout => Layouts}/TreeItemPersonaLayoutMedia.stories.tsx (100%) rename packages/react-components/react-tree/stories/{TreeItemPersonaLayout => Layouts}/TreeItemPersonaLayoutReadUnread.md (100%) rename packages/react-components/react-tree/stories/{TreeItemPersonaLayout => Layouts}/TreeItemPersonaLayoutReadUnread.stories.tsx (100%) rename packages/react-components/react-tree/stories/{TreeItemPersonaLayout => Layouts}/TreeItemPersonaLayoutWithDescription.md (100%) rename packages/react-components/react-tree/stories/{TreeItemPersonaLayout => Layouts}/TreeItemPersonaLayoutWithDescription.stories.tsx (100%) create mode 100644 packages/react-components/react-tree/stories/Layouts/description.md create mode 100644 packages/react-components/react-tree/stories/Layouts/index.stories.tsx delete mode 100644 packages/react-components/react-tree/stories/Tree/TreeAside.md rename packages/react-components/react-tree/stories/{Tree/TreeActions.md => TreeItem/TreeItemActions.md} (100%) rename packages/react-components/react-tree/stories/{Tree/TreeActions.stories.tsx => TreeItem/TreeItemActions.stories.tsx} (98%) create mode 100644 packages/react-components/react-tree/stories/TreeItem/TreeItemDefault.stories.tsx create mode 100644 packages/react-components/react-tree/stories/TreeItem/TreeItemDescription.md rename packages/react-components/react-tree/stories/{Tree/TreeExpandCollapseIconOnly.md => TreeItem/TreeItemExpandCollapseIconOnly.md} (100%) rename packages/react-components/react-tree/stories/{Tree/TreeExpandCollapseIconOnly.stories.tsx => TreeItem/TreeItemExpandCollapseIconOnly.stories.tsx} (96%) rename packages/react-components/react-tree/stories/{Tree/TreeExpandIcon.md => TreeItem/TreeItemExpandIcon.md} (100%) rename packages/react-components/react-tree/stories/{Tree/TreeExpandIcon.stories.tsx => TreeItem/TreeItemExpandIcon.stories.tsx} (97%) rename packages/react-components/react-tree/stories/{Tree/TreeIconAfter.stories.tsx => TreeItem/TreeItemIconAfter.stories.tsx} (100%) rename packages/react-components/react-tree/stories/{Tree/TreeIconBefore.md => TreeItem/TreeItemIconBefore.md} (100%) rename packages/react-components/react-tree/stories/{Tree/TreeIconBefore.stories.tsx => TreeItem/TreeItemIconBefore.stories.tsx} (96%) rename packages/react-components/react-tree/stories/{Tree/TreeWithInlineStyle.md => TreeItem/TreeItemWithInlineStyle.md} (100%) rename packages/react-components/react-tree/stories/{Tree/TreeWithInlineStyle.stories.tsx => TreeItem/TreeItemWithInlineStyle.stories.tsx} (96%) create mode 100644 packages/react-components/react-tree/stories/TreeItem/index.stories.tsx delete mode 100644 packages/react-components/react-tree/stories/TreeItemPersonaLayout/index.stories.tsx diff --git a/packages/react-components/react-tree/stories/Tree/TreeLayout.md b/packages/react-components/react-tree/stories/Layouts/TreeItemLayout.md similarity index 100% rename from packages/react-components/react-tree/stories/Tree/TreeLayout.md rename to packages/react-components/react-tree/stories/Layouts/TreeItemLayout.md diff --git a/packages/react-components/react-tree/stories/Tree/TreeLayout.stories.tsx b/packages/react-components/react-tree/stories/Layouts/TreeItemLayout.stories.tsx similarity index 98% rename from packages/react-components/react-tree/stories/Tree/TreeLayout.stories.tsx rename to packages/react-components/react-tree/stories/Layouts/TreeItemLayout.stories.tsx index 4421c7f1c7fcd4..a9fb2b1c39b43d 100644 --- a/packages/react-components/react-tree/stories/Tree/TreeLayout.stories.tsx +++ b/packages/react-components/react-tree/stories/Layouts/TreeItemLayout.stories.tsx @@ -10,7 +10,7 @@ import { SquareMultiple20Regular, } from '@fluentui/react-icons'; import { Button, CounterBadge, Menu, MenuItem, MenuList, MenuPopover, MenuTrigger } from '@fluentui/react-components'; -import story from './TreeLayout.md'; +import story from './TreeItemLayout.md'; const iconStyleProps: FluentIconsProps = { primaryFill: 'red', diff --git a/packages/react-components/react-tree/stories/Layouts/TreeItemLayoutAside.md b/packages/react-components/react-tree/stories/Layouts/TreeItemLayoutAside.md new file mode 100644 index 00000000000000..993f85a456f07b --- /dev/null +++ b/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. diff --git a/packages/react-components/react-tree/stories/Tree/TreeAside.stories.tsx b/packages/react-components/react-tree/stories/Layouts/TreeItemLayoutAside.stories.tsx similarity index 98% rename from packages/react-components/react-tree/stories/Tree/TreeAside.stories.tsx rename to packages/react-components/react-tree/stories/Layouts/TreeItemLayoutAside.stories.tsx index 08991de00650f9..6d78eb13092406 100644 --- a/packages/react-components/react-tree/stories/Tree/TreeAside.stories.tsx +++ b/packages/react-components/react-tree/stories/Layouts/TreeItemLayoutAside.stories.tsx @@ -2,7 +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 './TreeAside.md'; +import story from './TreeItemLayoutAside.md'; const iconStyleProps: FluentIconsProps = { primaryFill: 'red', diff --git a/packages/react-components/react-tree/stories/Layouts/TreeItemLayoutDefault.stories.tsx b/packages/react-components/react-tree/stories/Layouts/TreeItemLayoutDefault.stories.tsx new file mode 100644 index 00000000000000..c06f819cbf1773 --- /dev/null +++ b/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 ( + + + level 1, item 1 + + + level 2, item 1 + + + level 2, item 2 + + + level 2, item 3 + + + + + level 1, item 2 + + + level 2, item 1 + + + level 3, item 1 + + + + + + + ); +}; diff --git a/packages/react-components/react-tree/stories/TreeItemPersonaLayout/TreePersonaLayout.md b/packages/react-components/react-tree/stories/Layouts/TreeItemPersonaLayout.md similarity index 100% rename from packages/react-components/react-tree/stories/TreeItemPersonaLayout/TreePersonaLayout.md rename to packages/react-components/react-tree/stories/Layouts/TreeItemPersonaLayout.md diff --git a/packages/react-components/react-tree/stories/TreeItemPersonaLayout/TreePersonaLayout.stories.tsx b/packages/react-components/react-tree/stories/Layouts/TreeItemPersonaLayout.stories.tsx similarity index 98% rename from packages/react-components/react-tree/stories/TreeItemPersonaLayout/TreePersonaLayout.stories.tsx rename to packages/react-components/react-tree/stories/Layouts/TreeItemPersonaLayout.stories.tsx index 1b72ba67dd50a2..091de57556bdf4 100644 --- a/packages/react-components/react-tree/stories/TreeItemPersonaLayout/TreePersonaLayout.stories.tsx +++ b/packages/react-components/react-tree/stories/Layouts/TreeItemPersonaLayout.stories.tsx @@ -14,7 +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 './TreePersonaLayout.md'; +import story from './TreeItemPersonaLayout.md'; const useBadgeStyles = makeStyles({ base: { diff --git a/packages/react-components/react-tree/stories/TreeItemPersonaLayout/TreeItemPersonaLayoutDefault.stories.tsx b/packages/react-components/react-tree/stories/Layouts/TreeItemPersonaLayoutDefault.stories.tsx similarity index 95% rename from packages/react-components/react-tree/stories/TreeItemPersonaLayout/TreeItemPersonaLayoutDefault.stories.tsx rename to packages/react-components/react-tree/stories/Layouts/TreeItemPersonaLayoutDefault.stories.tsx index 8f4ded4408824d..c5e6ebf8d650e5 100644 --- a/packages/react-components/react-tree/stories/TreeItemPersonaLayout/TreeItemPersonaLayoutDefault.stories.tsx +++ b/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 ( diff --git a/packages/react-components/react-tree/stories/TreeItemPersonaLayout/TreeItemPersonaLayoutDescription.md b/packages/react-components/react-tree/stories/Layouts/TreeItemPersonaLayoutDescription.md similarity index 100% rename from packages/react-components/react-tree/stories/TreeItemPersonaLayout/TreeItemPersonaLayoutDescription.md rename to packages/react-components/react-tree/stories/Layouts/TreeItemPersonaLayoutDescription.md diff --git a/packages/react-components/react-tree/stories/TreeItemPersonaLayout/TreeItemPersonaLayoutMedia.md b/packages/react-components/react-tree/stories/Layouts/TreeItemPersonaLayoutMedia.md similarity index 100% rename from packages/react-components/react-tree/stories/TreeItemPersonaLayout/TreeItemPersonaLayoutMedia.md rename to packages/react-components/react-tree/stories/Layouts/TreeItemPersonaLayoutMedia.md diff --git a/packages/react-components/react-tree/stories/TreeItemPersonaLayout/TreeItemPersonaLayoutMedia.stories.tsx b/packages/react-components/react-tree/stories/Layouts/TreeItemPersonaLayoutMedia.stories.tsx similarity index 100% rename from packages/react-components/react-tree/stories/TreeItemPersonaLayout/TreeItemPersonaLayoutMedia.stories.tsx rename to packages/react-components/react-tree/stories/Layouts/TreeItemPersonaLayoutMedia.stories.tsx diff --git a/packages/react-components/react-tree/stories/TreeItemPersonaLayout/TreeItemPersonaLayoutReadUnread.md b/packages/react-components/react-tree/stories/Layouts/TreeItemPersonaLayoutReadUnread.md similarity index 100% rename from packages/react-components/react-tree/stories/TreeItemPersonaLayout/TreeItemPersonaLayoutReadUnread.md rename to packages/react-components/react-tree/stories/Layouts/TreeItemPersonaLayoutReadUnread.md diff --git a/packages/react-components/react-tree/stories/TreeItemPersonaLayout/TreeItemPersonaLayoutReadUnread.stories.tsx b/packages/react-components/react-tree/stories/Layouts/TreeItemPersonaLayoutReadUnread.stories.tsx similarity index 100% rename from packages/react-components/react-tree/stories/TreeItemPersonaLayout/TreeItemPersonaLayoutReadUnread.stories.tsx rename to packages/react-components/react-tree/stories/Layouts/TreeItemPersonaLayoutReadUnread.stories.tsx diff --git a/packages/react-components/react-tree/stories/TreeItemPersonaLayout/TreeItemPersonaLayoutWithDescription.md b/packages/react-components/react-tree/stories/Layouts/TreeItemPersonaLayoutWithDescription.md similarity index 100% rename from packages/react-components/react-tree/stories/TreeItemPersonaLayout/TreeItemPersonaLayoutWithDescription.md rename to packages/react-components/react-tree/stories/Layouts/TreeItemPersonaLayoutWithDescription.md diff --git a/packages/react-components/react-tree/stories/TreeItemPersonaLayout/TreeItemPersonaLayoutWithDescription.stories.tsx b/packages/react-components/react-tree/stories/Layouts/TreeItemPersonaLayoutWithDescription.stories.tsx similarity index 100% rename from packages/react-components/react-tree/stories/TreeItemPersonaLayout/TreeItemPersonaLayoutWithDescription.stories.tsx rename to packages/react-components/react-tree/stories/Layouts/TreeItemPersonaLayoutWithDescription.stories.tsx diff --git a/packages/react-components/react-tree/stories/Layouts/description.md b/packages/react-components/react-tree/stories/Layouts/description.md new file mode 100644 index 00000000000000..84d5122c05da1c --- /dev/null +++ b/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. diff --git a/packages/react-components/react-tree/stories/Layouts/index.stories.tsx b/packages/react-components/react-tree/stories/Layouts/index.stories.tsx new file mode 100644 index 00000000000000..1e6036662837c6 --- /dev/null +++ b/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'), + }, + }, + }, +}; diff --git a/packages/react-components/react-tree/stories/Tree/TreeAside.md b/packages/react-components/react-tree/stories/Tree/TreeAside.md deleted file mode 100644 index 495cf8d10096b0..00000000000000 --- a/packages/react-components/react-tree/stories/Tree/TreeAside.md +++ /dev/null @@ -1 +0,0 @@ -The `Tree` component allows for an `aside` prop to be added to individual `TreeItemLayout` or `TreeItemPersonaLayout` 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. diff --git a/packages/react-components/react-tree/stories/Tree/index.stories.tsx b/packages/react-components/react-tree/stories/Tree/index.stories.tsx index 0ff805dd3ed327..efe1a3db6fb06c 100644 --- a/packages/react-components/react-tree/stories/Tree/index.stories.tsx +++ b/packages/react-components/react-tree/stories/Tree/index.stories.tsx @@ -1,27 +1,20 @@ -import { Tree } from '@fluentui/react-tree'; +import { Tree, TreeItem, TreeItemLayout, TreeItemPersonaLayout } from '@fluentui/react-tree'; import descriptionMd from './TreeDescription.md'; import bestPracticesMd from './TreeBestPractices.md'; export { Default } from './TreeDefault.stories'; export { DefaultOpenTrees } from './TreeDefaultOpenTrees.stories'; -export { ExpandIcon } from './TreeExpandIcon.stories'; -export { IconBefore } from './TreeIconBefore.stories'; -export { IconAfter } from './TreeIconAfter.stories'; -export { Actions } from './TreeActions.stories'; -export { Aside } from './TreeAside.stories'; export { Appearance } from './TreeAppearance.stories'; export { Size } from './TreeSize.stories'; -export { Layout } from './TreeLayout.stories'; export { OpenItemsControlled } from './TreeControllingOpenAndClose.stories'; -export { ExpandCollapseIconOnly } from './TreeExpandCollapseIconOnly.stories'; export { FlattenTree as flattenTree } from './flattenTree.stories'; export { Virtualization } from './Virtualization.stories'; -export { WithInlineStyle } from './TreeWithInlineStyle.stories'; export default { - title: 'Preview Components/Tree', + title: 'Preview Components/Tree/Tree', component: Tree, + subcomponents: { TreeItem, TreeItemLayout, TreeItemPersonaLayout }, parameters: { docs: { description: { diff --git a/packages/react-components/react-tree/stories/Tree/TreeActions.md b/packages/react-components/react-tree/stories/TreeItem/TreeItemActions.md similarity index 100% rename from packages/react-components/react-tree/stories/Tree/TreeActions.md rename to packages/react-components/react-tree/stories/TreeItem/TreeItemActions.md diff --git a/packages/react-components/react-tree/stories/Tree/TreeActions.stories.tsx b/packages/react-components/react-tree/stories/TreeItem/TreeItemActions.stories.tsx similarity index 98% rename from packages/react-components/react-tree/stories/Tree/TreeActions.stories.tsx rename to packages/react-components/react-tree/stories/TreeItem/TreeItemActions.stories.tsx index 91a61b0a0db05e..f536e9418ae5a7 100644 --- a/packages/react-components/react-tree/stories/Tree/TreeActions.stories.tsx +++ b/packages/react-components/react-tree/stories/TreeItem/TreeItemActions.stories.tsx @@ -2,7 +2,7 @@ import * as React from 'react'; import { Tree, TreeItem, TreeItemLayout } from '@fluentui/react-tree'; import { Edit20Regular, MoreHorizontal20Regular } from '@fluentui/react-icons'; import { Button, Menu, MenuItem, MenuList, MenuPopover, MenuTrigger } from '@fluentui/react-components'; -import story from './TreeActions.md'; +import story from './TreeItemActions.md'; const RenderActions = () => { return ( diff --git a/packages/react-components/react-tree/stories/TreeItem/TreeItemDefault.stories.tsx b/packages/react-components/react-tree/stories/TreeItem/TreeItemDefault.stories.tsx new file mode 100644 index 00000000000000..46a49dac5010e3 --- /dev/null +++ b/packages/react-components/react-tree/stories/TreeItem/TreeItemDefault.stories.tsx @@ -0,0 +1,36 @@ +import * as React from 'react'; +import { Tree, TreeItem, TreeItemLayout } from '@fluentui/react-tree'; + +export const Default = () => { + return ( + + + level 1, item 1 + + + level 2, item 1 + + + level 2, item 2 + + + level 2, item 3 + + + + + level 1, item 2 + + + level 2, item 1 + + + level 3, item 1 + + + + + + + ); +}; diff --git a/packages/react-components/react-tree/stories/TreeItem/TreeItemDescription.md b/packages/react-components/react-tree/stories/TreeItem/TreeItemDescription.md new file mode 100644 index 00000000000000..0dc57ec18b0f55 --- /dev/null +++ b/packages/react-components/react-tree/stories/TreeItem/TreeItemDescription.md @@ -0,0 +1,3 @@ +The `TreeItem` component represents a single item in a tree. It can contain child items in the form of another `Tree` component or standalone `TreeItem`. 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 child items, an expand/collapse control is displayed, allowing the user to show or hide the children. diff --git a/packages/react-components/react-tree/stories/Tree/TreeExpandCollapseIconOnly.md b/packages/react-components/react-tree/stories/TreeItem/TreeItemExpandCollapseIconOnly.md similarity index 100% rename from packages/react-components/react-tree/stories/Tree/TreeExpandCollapseIconOnly.md rename to packages/react-components/react-tree/stories/TreeItem/TreeItemExpandCollapseIconOnly.md diff --git a/packages/react-components/react-tree/stories/Tree/TreeExpandCollapseIconOnly.stories.tsx b/packages/react-components/react-tree/stories/TreeItem/TreeItemExpandCollapseIconOnly.stories.tsx similarity index 96% rename from packages/react-components/react-tree/stories/Tree/TreeExpandCollapseIconOnly.stories.tsx rename to packages/react-components/react-tree/stories/TreeItem/TreeItemExpandCollapseIconOnly.stories.tsx index 680934dc03e9a7..e03f1cd330e98f 100644 --- a/packages/react-components/react-tree/stories/Tree/TreeExpandCollapseIconOnly.stories.tsx +++ b/packages/react-components/react-tree/stories/TreeItem/TreeItemExpandCollapseIconOnly.stories.tsx @@ -1,7 +1,7 @@ import * as React from 'react'; import { Tree, TreeItem, TreeItemLayout } from '@fluentui/react-tree'; import { TreeOpenChangeData, TreeOpenChangeEvent } from '../../src/components/Tree/Tree.types'; -import story from './TreeExpandCollapseIconOnly.md'; +import story from './TreeItemExpandCollapseIconOnly.md'; export const ExpandCollapseIconOnly = () => { const onOpenChange = (event: TreeOpenChangeEvent, data: TreeOpenChangeData) => { diff --git a/packages/react-components/react-tree/stories/Tree/TreeExpandIcon.md b/packages/react-components/react-tree/stories/TreeItem/TreeItemExpandIcon.md similarity index 100% rename from packages/react-components/react-tree/stories/Tree/TreeExpandIcon.md rename to packages/react-components/react-tree/stories/TreeItem/TreeItemExpandIcon.md diff --git a/packages/react-components/react-tree/stories/Tree/TreeExpandIcon.stories.tsx b/packages/react-components/react-tree/stories/TreeItem/TreeItemExpandIcon.stories.tsx similarity index 97% rename from packages/react-components/react-tree/stories/Tree/TreeExpandIcon.stories.tsx rename to packages/react-components/react-tree/stories/TreeItem/TreeItemExpandIcon.stories.tsx index 1982839903d8b4..49acbe0d497aec 100644 --- a/packages/react-components/react-tree/stories/Tree/TreeExpandIcon.stories.tsx +++ b/packages/react-components/react-tree/stories/TreeItem/TreeItemExpandIcon.stories.tsx @@ -2,7 +2,7 @@ import * as React from 'react'; import { Tree, TreeItem, TreeItemLayout } from '@fluentui/react-tree'; import { Add12Regular, Subtract12Regular } from '@fluentui/react-icons'; import { TreeOpenChangeData, TreeOpenChangeEvent } from '../../src/Tree'; -import story from './TreeExpandIcon.md'; +import story from './TreeItemExpandIcon.md'; export const ExpandIcon = () => { const [openItems, setOpenItems] = React.useState([]); diff --git a/packages/react-components/react-tree/stories/Tree/TreeIconAfter.stories.tsx b/packages/react-components/react-tree/stories/TreeItem/TreeItemIconAfter.stories.tsx similarity index 100% rename from packages/react-components/react-tree/stories/Tree/TreeIconAfter.stories.tsx rename to packages/react-components/react-tree/stories/TreeItem/TreeItemIconAfter.stories.tsx diff --git a/packages/react-components/react-tree/stories/Tree/TreeIconBefore.md b/packages/react-components/react-tree/stories/TreeItem/TreeItemIconBefore.md similarity index 100% rename from packages/react-components/react-tree/stories/Tree/TreeIconBefore.md rename to packages/react-components/react-tree/stories/TreeItem/TreeItemIconBefore.md diff --git a/packages/react-components/react-tree/stories/Tree/TreeIconBefore.stories.tsx b/packages/react-components/react-tree/stories/TreeItem/TreeItemIconBefore.stories.tsx similarity index 96% rename from packages/react-components/react-tree/stories/Tree/TreeIconBefore.stories.tsx rename to packages/react-components/react-tree/stories/TreeItem/TreeItemIconBefore.stories.tsx index 77d8cacbd5b3c5..111fc58d95cc7c 100644 --- a/packages/react-components/react-tree/stories/Tree/TreeIconBefore.stories.tsx +++ b/packages/react-components/react-tree/stories/TreeItem/TreeItemIconBefore.stories.tsx @@ -1,7 +1,7 @@ import * as React from 'react'; import { Tree, TreeItem, TreeItemLayout } from '@fluentui/react-tree'; import { CheckboxChecked20Filled, CheckboxUnchecked20Filled } from '@fluentui/react-icons'; -import story from './TreeIconBefore.md'; +import story from './TreeItemIconBefore.md'; export const IconBefore = () => { return ( diff --git a/packages/react-components/react-tree/stories/Tree/TreeWithInlineStyle.md b/packages/react-components/react-tree/stories/TreeItem/TreeItemWithInlineStyle.md similarity index 100% rename from packages/react-components/react-tree/stories/Tree/TreeWithInlineStyle.md rename to packages/react-components/react-tree/stories/TreeItem/TreeItemWithInlineStyle.md diff --git a/packages/react-components/react-tree/stories/Tree/TreeWithInlineStyle.stories.tsx b/packages/react-components/react-tree/stories/TreeItem/TreeItemWithInlineStyle.stories.tsx similarity index 96% rename from packages/react-components/react-tree/stories/Tree/TreeWithInlineStyle.stories.tsx rename to packages/react-components/react-tree/stories/TreeItem/TreeItemWithInlineStyle.stories.tsx index 031834cec1035f..b8535f72d223fe 100644 --- a/packages/react-components/react-tree/stories/Tree/TreeWithInlineStyle.stories.tsx +++ b/packages/react-components/react-tree/stories/TreeItem/TreeItemWithInlineStyle.stories.tsx @@ -7,7 +7,7 @@ import { TreeItemProps, useTreeContext_unstable, } from '@fluentui/react-tree'; -import story from './TreeWithInlineStyle.md'; +import story from './TreeItemWithInlineStyle.md'; const TreeItem = (props: TreeItemProps) => { const level = useTreeContext_unstable(ctx => ctx.level); diff --git a/packages/react-components/react-tree/stories/TreeItem/index.stories.tsx b/packages/react-components/react-tree/stories/TreeItem/index.stories.tsx new file mode 100644 index 00000000000000..07c739a079abeb --- /dev/null +++ b/packages/react-components/react-tree/stories/TreeItem/index.stories.tsx @@ -0,0 +1,23 @@ +import { TreeItem, TreeItemLayout, TreeItemPersonaLayout } from '@fluentui/react-tree'; +import descriptionMd from './TreeItemDescription.md'; + +export { Default } from './TreeItemDefault.stories'; +export { ExpandCollapseIconOnly } from './TreeItemExpandCollapseIconOnly.stories'; +export { ExpandIcon } from './TreeItemExpandIcon.stories'; +export { IconBefore } from './TreeItemIconBefore.stories'; +export { IconAfter } from './TreeItemIconAfter.stories'; +export { Actions } from './TreeItemActions.stories'; +export { WithInlineStyle } from './TreeItemWithInlineStyle.stories'; + +export default { + title: 'Preview Components/Tree/TreeItem', + component: TreeItem, + subcomponents: { TreeItemLayout, TreeItemPersonaLayout }, + parameters: { + docs: { + description: { + component: [descriptionMd].join('\n'), + }, + }, + }, +}; diff --git a/packages/react-components/react-tree/stories/TreeItemPersonaLayout/index.stories.tsx b/packages/react-components/react-tree/stories/TreeItemPersonaLayout/index.stories.tsx deleted file mode 100644 index 1694ff66f88245..00000000000000 --- a/packages/react-components/react-tree/stories/TreeItemPersonaLayout/index.stories.tsx +++ /dev/null @@ -1,19 +0,0 @@ -import { TreeItemPersonaLayout } from '@fluentui/react-tree'; -import descriptionMd from './TreeItemPersonaLayoutDescription.md'; -export { Default } from './TreeItemPersonaLayoutDefault.stories'; -export { Media } from './TreeItemPersonaLayoutMedia.stories'; -export { WithDescription } from './TreeItemPersonaLayoutWithDescription.stories'; -export { ReadUnread } from './TreeItemPersonaLayoutReadUnread.stories'; -export { TreePersonaLayout } from './TreePersonaLayout.stories'; - -export default { - title: 'Preview Components/Tree/PersonaTreeItem', - component: TreeItemPersonaLayout, - parameters: { - docs: { - description: { - component: [descriptionMd].join('\n'), - }, - }, - }, -}; From 7f898e1e94a5093afcbd9c8da82d34a8d1fe3364 Mon Sep 17 00:00:00 2001 From: Petr Duda Date: Wed, 22 Mar 2023 11:07:33 +0100 Subject: [PATCH 09/34] Do's --- .../stories/Tree/TreeBestPractices.md | 34 +++++-------------- 1 file changed, 9 insertions(+), 25 deletions(-) diff --git a/packages/react-components/react-tree/stories/Tree/TreeBestPractices.md b/packages/react-components/react-tree/stories/Tree/TreeBestPractices.md index 94960d06967cd7..47b6793d0c69ba 100644 --- a/packages/react-components/react-tree/stories/Tree/TreeBestPractices.md +++ b/packages/react-components/react-tree/stories/Tree/TreeBestPractices.md @@ -1,32 +1,16 @@ - + From 346ea26517fa30194258c0e103ba03f3fc1ca1ea Mon Sep 17 00:00:00 2001 From: Petr Duda Date: Wed, 22 Mar 2023 11:12:07 +0100 Subject: [PATCH 10/34] treeitem --- .../react-tree/src/components/TreeItem/TreeItem.tsx | 1 - 1 file changed, 1 deletion(-) diff --git a/packages/react-components/react-tree/src/components/TreeItem/TreeItem.tsx b/packages/react-components/react-tree/src/components/TreeItem/TreeItem.tsx index 2acdd0908ff19a..3a3823484da383 100644 --- a/packages/react-components/react-tree/src/components/TreeItem/TreeItem.tsx +++ b/packages/react-components/react-tree/src/components/TreeItem/TreeItem.tsx @@ -14,7 +14,6 @@ import { useTreeItemContextValues_unstable } from './useTreeItemContextValues'; * * When a TreeItem has child items, an expand/collapse control is displayed, * allowing the user to show or hide the children. - * This provides a convenient way to navigate hierarchical data, such as a file system or a category tree. */ export const TreeItem: ForwardRefComponent = React.forwardRef((props, ref) => { const state = useTreeItem_unstable(props, ref); From 5b0447f9747f1a08d411131e0521d6d32beb38ba Mon Sep 17 00:00:00 2001 From: Petr Duda Date: Wed, 22 Mar 2023 11:37:37 +0100 Subject: [PATCH 11/34] change --- ...ui-react-tree-7b614498-e79f-460b-a3a4-22ba4d9a2bea.json | 7 +++++++ 1 file changed, 7 insertions(+) create mode 100644 change/@fluentui-react-tree-7b614498-e79f-460b-a3a4-22ba4d9a2bea.json diff --git a/change/@fluentui-react-tree-7b614498-e79f-460b-a3a4-22ba4d9a2bea.json b/change/@fluentui-react-tree-7b614498-e79f-460b-a3a4-22ba4d9a2bea.json new file mode 100644 index 00000000000000..4bf73a21ad65c3 --- /dev/null +++ b/change/@fluentui-react-tree-7b614498-e79f-460b-a3a4-22ba4d9a2bea.json @@ -0,0 +1,7 @@ +{ + "type": "none", + "comment": "tree stories and doc update", + "packageName": "@fluentui/react-tree", + "email": "petrduda@microsoft.com", + "dependentChangeType": "none" +} From 15d527505bf557d8f20db9f8f9ac61d8c8b3f5e0 Mon Sep 17 00:00:00 2001 From: Petr Duda Date: Wed, 22 Mar 2023 14:20:07 +0100 Subject: [PATCH 12/34] Update change/@fluentui-react-tree-7b614498-e79f-460b-a3a4-22ba4d9a2bea.json Co-authored-by: Bernardo Sunderhus --- ...entui-react-tree-7b614498-e79f-460b-a3a4-22ba4d9a2bea.json | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/change/@fluentui-react-tree-7b614498-e79f-460b-a3a4-22ba4d9a2bea.json b/change/@fluentui-react-tree-7b614498-e79f-460b-a3a4-22ba4d9a2bea.json index 4bf73a21ad65c3..b59c3335f4543f 100644 --- a/change/@fluentui-react-tree-7b614498-e79f-460b-a3a4-22ba4d9a2bea.json +++ b/change/@fluentui-react-tree-7b614498-e79f-460b-a3a4-22ba4d9a2bea.json @@ -1,7 +1,7 @@ { - "type": "none", + "type": "prerelease", "comment": "tree stories and doc update", "packageName": "@fluentui/react-tree", "email": "petrduda@microsoft.com", - "dependentChangeType": "none" + "dependentChangeType": "patch" } From 17c47c6962f89f8b6cfbb45fd5396a583420cc3a Mon Sep 17 00:00:00 2001 From: Petr Duda Date: Wed, 22 Mar 2023 15:35:22 +0100 Subject: [PATCH 13/34] Update packages/react-components/react-tree/stories/Tree/Virtualization.md Co-authored-by: Bernardo Sunderhus --- .../react-components/react-tree/stories/Tree/Virtualization.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/packages/react-components/react-tree/stories/Tree/Virtualization.md b/packages/react-components/react-tree/stories/Tree/Virtualization.md index e9016b28685139..e2e4f73934d7bb 100644 --- a/packages/react-components/react-tree/stories/Tree/Virtualization.md +++ b/packages/react-components/react-tree/stories/Tree/Virtualization.md @@ -1,3 +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 the overall performance of the tree. -To achieve this, one can create a `flattened` version of the tree structure that can be easily consumed by a windowing library. This library renders only the items that are currently visible on the screen, which reduces the amount of memory required to run the application. +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. From c819c6f778f3b452ad9eaa57aebd03fdca9b72fd Mon Sep 17 00:00:00 2001 From: Petr Duda Date: Wed, 22 Mar 2023 15:36:36 +0100 Subject: [PATCH 14/34] Update packages/react-components/react-tree/stories/Tree/Virtualization.md Co-authored-by: Bernardo Sunderhus --- .../react-components/react-tree/stories/Tree/Virtualization.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/packages/react-components/react-tree/stories/Tree/Virtualization.md b/packages/react-components/react-tree/stories/Tree/Virtualization.md index e2e4f73934d7bb..4545d50951a48e 100644 --- a/packages/react-components/react-tree/stories/Tree/Virtualization.md +++ b/packages/react-components/react-tree/stories/Tree/Virtualization.md @@ -1,3 +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 the overall performance of the tree. +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. From 0f7c9bcd042db3a6c53f6049ca09aa8d5e8d93ef Mon Sep 17 00:00:00 2001 From: Petr Duda Date: Wed, 22 Mar 2023 15:43:48 +0100 Subject: [PATCH 15/34] Update packages/react-components/react-tree/stories/Tree/TreeBestPractices.md Co-authored-by: Bernardo Sunderhus --- .../react-tree/stories/Tree/TreeBestPractices.md | 1 - 1 file changed, 1 deletion(-) diff --git a/packages/react-components/react-tree/stories/Tree/TreeBestPractices.md b/packages/react-components/react-tree/stories/Tree/TreeBestPractices.md index 47b6793d0c69ba..73b5e33afe4a73 100644 --- a/packages/react-components/react-tree/stories/Tree/TreeBestPractices.md +++ b/packages/react-components/react-tree/stories/Tree/TreeBestPractices.md @@ -7,7 +7,6 @@ - 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. -- Allow users to expand and collapse nodes to focus on specific parts of the hierarchy. - 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. - Consider using virtualization to improve performance for large tree structures. From 967235051c7ae596a7f8dc74bcc9d01ebd4c2565 Mon Sep 17 00:00:00 2001 From: Petr Duda Date: Wed, 22 Mar 2023 15:44:11 +0100 Subject: [PATCH 16/34] Update packages/react-components/react-tree/stories/Tree/TreeDescription.md Co-authored-by: Bernardo Sunderhus --- .../react-tree/stories/Tree/TreeDescription.md | 13 +++++++++++++ 1 file changed, 13 insertions(+) diff --git a/packages/react-components/react-tree/stories/Tree/TreeDescription.md b/packages/react-components/react-tree/stories/Tree/TreeDescription.md index 7ceb91d972df25..0aac5c7d2efb75 100644 --- a/packages/react-components/react-tree/stories/Tree/TreeDescription.md +++ b/packages/react-components/react-tree/stories/Tree/TreeDescription.md @@ -1 +1,14 @@ `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. + + + +> **⚠️ Preview components are considered unstable:** +> +> ```jsx +> +> import { Tree } from '@fluentui/react-components/unstable'; +> +> ``` +> +> - Features and APIs may change before final release +> - Please contact us if you intend to use this in your product From 38ea28a77927665cf032f616cd6ec9d40eae9dc6 Mon Sep 17 00:00:00 2001 From: Petr Duda Date: Wed, 22 Mar 2023 16:04:40 +0100 Subject: [PATCH 17/34] fix treeitem description --- .../react-tree/src/components/TreeItem/TreeItem.tsx | 9 ++++++--- .../react-tree/stories/Tree/TreeBestPractices.md | 1 - 2 files changed, 6 insertions(+), 4 deletions(-) diff --git a/packages/react-components/react-tree/src/components/TreeItem/TreeItem.tsx b/packages/react-components/react-tree/src/components/TreeItem/TreeItem.tsx index 3a3823484da383..a20be498e2d237 100644 --- a/packages/react-components/react-tree/src/components/TreeItem/TreeItem.tsx +++ b/packages/react-components/react-tree/src/components/TreeItem/TreeItem.tsx @@ -8,11 +8,14 @@ import { useTreeItemContextValues_unstable } from './useTreeItemContextValues'; /** * The `TreeItem` component represents a single item in a tree. - * It can contain child items in the form of another Tree component or standalone TreeItem. - * The content and layout of a TreeItem can be defined using the `TreeItemLayout` or `TreeItemPersonaLayout` component, + * 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 child items, an expand/collapse control is displayed, + * 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 = React.forwardRef((props, ref) => { diff --git a/packages/react-components/react-tree/stories/Tree/TreeBestPractices.md b/packages/react-components/react-tree/stories/Tree/TreeBestPractices.md index 73b5e33afe4a73..be393f97b2ceae 100644 --- a/packages/react-components/react-tree/stories/Tree/TreeBestPractices.md +++ b/packages/react-components/react-tree/stories/Tree/TreeBestPractices.md @@ -9,7 +9,6 @@ - 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. -- Consider using virtualization to improve performance for large tree structures. - Use the `aria-label` attribute on the root of the Tree component to provide an accessible name for the tree. From eab54f64ae0ba7c82267f721d4c8b6a06f865626 Mon Sep 17 00:00:00 2001 From: Petr Duda Date: Mon, 20 Mar 2023 21:39:52 +0100 Subject: [PATCH 18/34] tree stories --- .../react-tree/stories/Tree/TreeActions.md | 3 +++ .../react-tree/stories/Tree/TreeActions.stories.tsx | 9 +++++++++ .../react-tree/stories/Tree/TreeAppearance.md | 1 + .../react-tree/stories/Tree/TreeAppearance.stories.tsx | 6 ++---- .../react-tree/stories/Tree/TreeAside.md | 1 + .../react-tree/stories/Tree/TreeAside.stories.tsx | 9 +++++++++ .../stories/Tree/TreeControllingOpenAndClose.md | 5 +++++ .../stories/Tree/TreeControllingOpenAndClose.stories.tsx | 9 +++++++++ .../react-tree/stories/Tree/TreeDefaultOpenTrees.md | 1 + .../stories/Tree/TreeDefaultOpenTrees.stories.tsx | 9 +++++++++ .../stories/Tree/TreeExpandCollapseIconOnly.md | 3 +++ .../stories/Tree/TreeExpandCollapseIconOnly.stories.tsx | 9 +++++++++ .../react-tree/stories/Tree/TreeExpandIcon.md | 3 +++ .../react-tree/stories/Tree/TreeExpandIcon.stories.tsx | 9 +++++++++ .../react-tree/stories/Tree/TreeIconAfter.md | 1 + .../react-tree/stories/Tree/TreeIconAfter.stories.tsx | 9 +++++++++ .../react-tree/stories/Tree/TreeIconBefore.md | 1 + .../react-tree/stories/Tree/TreeIconBefore.stories.tsx | 9 +++++++++ .../react-components/react-tree/stories/Tree/TreeSize.md | 1 + .../react-tree/stories/Tree/TreeSize.stories.tsx | 3 ++- .../react-tree/stories/Tree/TreeWithInlineStyle.md | 1 + .../stories/Tree/TreeWithInlineStyle.stories.tsx | 9 +++++++++ 22 files changed, 106 insertions(+), 5 deletions(-) create mode 100644 packages/react-components/react-tree/stories/Tree/TreeActions.md create mode 100644 packages/react-components/react-tree/stories/Tree/TreeAppearance.md create mode 100644 packages/react-components/react-tree/stories/Tree/TreeAside.md create mode 100644 packages/react-components/react-tree/stories/Tree/TreeControllingOpenAndClose.md create mode 100644 packages/react-components/react-tree/stories/Tree/TreeDefaultOpenTrees.md create mode 100644 packages/react-components/react-tree/stories/Tree/TreeExpandCollapseIconOnly.md create mode 100644 packages/react-components/react-tree/stories/Tree/TreeExpandIcon.md create mode 100644 packages/react-components/react-tree/stories/Tree/TreeIconAfter.md create mode 100644 packages/react-components/react-tree/stories/Tree/TreeIconBefore.md create mode 100644 packages/react-components/react-tree/stories/Tree/TreeSize.md create mode 100644 packages/react-components/react-tree/stories/Tree/TreeWithInlineStyle.md diff --git a/packages/react-components/react-tree/stories/Tree/TreeActions.md b/packages/react-components/react-tree/stories/Tree/TreeActions.md new file mode 100644 index 00000000000000..f199bcd996dd41 --- /dev/null +++ b/packages/react-components/react-tree/stories/Tree/TreeActions.md @@ -0,0 +1,3 @@ +The `Tree` component lets you add custom actions to each `TreeItem`, such as buttons or menus. This can be done by passing a component that renders the desired actions as a prop to the `TreeItem`. + +The `actions` are hidden by default and appear on the right side when the user hovers over the `TreeItem`, allowing for a clean and uncluttered display. diff --git a/packages/react-components/react-tree/stories/Tree/TreeActions.stories.tsx b/packages/react-components/react-tree/stories/Tree/TreeActions.stories.tsx index 9c765a3172e8cd..91a61b0a0db05e 100644 --- a/packages/react-components/react-tree/stories/Tree/TreeActions.stories.tsx +++ b/packages/react-components/react-tree/stories/Tree/TreeActions.stories.tsx @@ -2,6 +2,7 @@ import * as React from 'react'; import { Tree, TreeItem, TreeItemLayout } from '@fluentui/react-tree'; import { Edit20Regular, MoreHorizontal20Regular } from '@fluentui/react-icons'; import { Button, Menu, MenuItem, MenuList, MenuPopover, MenuTrigger } from '@fluentui/react-components'; +import story from './TreeActions.md'; const RenderActions = () => { return ( @@ -71,3 +72,11 @@ export const Actions = () => ( ); + +Actions.parameters = { + docs: { + description: { + story, + }, + }, +}; diff --git a/packages/react-components/react-tree/stories/Tree/TreeAppearance.md b/packages/react-components/react-tree/stories/Tree/TreeAppearance.md new file mode 100644 index 00000000000000..7583f9bbbc94cd --- /dev/null +++ b/packages/react-components/react-tree/stories/Tree/TreeAppearance.md @@ -0,0 +1 @@ +The `Tree` component supports different appearances for TreeItems. The default `appearance` is used when no appearance is specified. The `subtle` appearance minimizes emphasis on hovered or focused states, while the `transparent` appearance removes the background color. diff --git a/packages/react-components/react-tree/stories/Tree/TreeAppearance.stories.tsx b/packages/react-components/react-tree/stories/Tree/TreeAppearance.stories.tsx index 2d5edcbaa88e67..d23aca3bf0c566 100644 --- a/packages/react-components/react-tree/stories/Tree/TreeAppearance.stories.tsx +++ b/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, }, }, }; diff --git a/packages/react-components/react-tree/stories/Tree/TreeAside.md b/packages/react-components/react-tree/stories/Tree/TreeAside.md new file mode 100644 index 00000000000000..d205165dc8e46a --- /dev/null +++ b/packages/react-components/react-tree/stories/Tree/TreeAside.md @@ -0,0 +1 @@ +The `Tree` component allows for an `aside` prop to be added to individual `TreeItemLayout` or `TreeItemPersonaLayout` 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. diff --git a/packages/react-components/react-tree/stories/Tree/TreeAside.stories.tsx b/packages/react-components/react-tree/stories/Tree/TreeAside.stories.tsx index 65c77c1fb6d335..43545c80adb92c 100644 --- a/packages/react-components/react-tree/stories/Tree/TreeAside.stories.tsx +++ b/packages/react-components/react-tree/stories/Tree/TreeAside.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 './TreeAside.md'; const iconStyleProps: FluentIconsProps = { primaryFill: 'red', @@ -67,3 +68,11 @@ export const Aside = () => ( ); + +Aside.parameters = { + docs: { + description: { + story, + }, + }, +}; diff --git a/packages/react-components/react-tree/stories/Tree/TreeControllingOpenAndClose.md b/packages/react-components/react-tree/stories/Tree/TreeControllingOpenAndClose.md new file mode 100644 index 00000000000000..0e4a934b1922d9 --- /dev/null +++ b/packages/react-components/react-tree/stories/Tree/TreeControllingOpenAndClose.md @@ -0,0 +1,5 @@ +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. + +To control the open/closed state of a `TreeItem`, an `id` prop must be provided to the `TreeItem` component. This `id` prop can then be used to identify the `TreeItem` in the `handleOpenChange` function and update the `openItems` state. diff --git a/packages/react-components/react-tree/stories/Tree/TreeControllingOpenAndClose.stories.tsx b/packages/react-components/react-tree/stories/Tree/TreeControllingOpenAndClose.stories.tsx index 3144aed6a401b9..b8b92a732088a5 100644 --- a/packages/react-components/react-tree/stories/Tree/TreeControllingOpenAndClose.stories.tsx +++ b/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([]); @@ -47,3 +48,11 @@ export const OpenItemsControlled = () => { ); }; + +OpenItemsControlled.parameters = { + docs: { + description: { + story, + }, + }, +}; diff --git a/packages/react-components/react-tree/stories/Tree/TreeDefaultOpenTrees.md b/packages/react-components/react-tree/stories/Tree/TreeDefaultOpenTrees.md new file mode 100644 index 00000000000000..af5d41a2a6d049 --- /dev/null +++ b/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. diff --git a/packages/react-components/react-tree/stories/Tree/TreeDefaultOpenTrees.stories.tsx b/packages/react-components/react-tree/stories/Tree/TreeDefaultOpenTrees.stories.tsx index 7e53ddac1a3967..fa3dd1181a7d41 100644 --- a/packages/react-components/react-tree/stories/Tree/TreeDefaultOpenTrees.stories.tsx +++ b/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 = () => { ); }; + +DefaultOpenTrees.parameters = { + docs: { + description: { + story, + }, + }, +}; diff --git a/packages/react-components/react-tree/stories/Tree/TreeExpandCollapseIconOnly.md b/packages/react-components/react-tree/stories/Tree/TreeExpandCollapseIconOnly.md new file mode 100644 index 00000000000000..f79ce0dc4eb133 --- /dev/null +++ b/packages/react-components/react-tree/stories/Tree/TreeExpandCollapseIconOnly.md @@ -0,0 +1,3 @@ +By default, every `TreeItem` component that can be expanded or collapsed will respond to clicks on both the content and the expand/collapse icon. If you need to perform a different action when the `TreeItem` content is clicked, you can override this behavior. + +To do so, you can listen for the `onOpenChange` event in the root `Tree` component. When this event is triggered, you can check the type of the event data to determine whether the user clicked on the `TreeItem`'s content or the expand/collapse icon. This way, you can handle clicks on the content separately from expand/collapse events. diff --git a/packages/react-components/react-tree/stories/Tree/TreeExpandCollapseIconOnly.stories.tsx b/packages/react-components/react-tree/stories/Tree/TreeExpandCollapseIconOnly.stories.tsx index bdbdf6f2f9eced..680934dc03e9a7 100644 --- a/packages/react-components/react-tree/stories/Tree/TreeExpandCollapseIconOnly.stories.tsx +++ b/packages/react-components/react-tree/stories/Tree/TreeExpandCollapseIconOnly.stories.tsx @@ -1,6 +1,7 @@ import * as React from 'react'; import { Tree, TreeItem, TreeItemLayout } from '@fluentui/react-tree'; import { TreeOpenChangeData, TreeOpenChangeEvent } from '../../src/components/Tree/Tree.types'; +import story from './TreeExpandCollapseIconOnly.md'; export const ExpandCollapseIconOnly = () => { const onOpenChange = (event: TreeOpenChangeEvent, data: TreeOpenChangeData) => { @@ -43,3 +44,11 @@ export const ExpandCollapseIconOnly = () => { ); }; + +ExpandCollapseIconOnly.parameters = { + docs: { + description: { + story, + }, + }, +}; diff --git a/packages/react-components/react-tree/stories/Tree/TreeExpandIcon.md b/packages/react-components/react-tree/stories/Tree/TreeExpandIcon.md new file mode 100644 index 00000000000000..5a1cc26cd72f9c --- /dev/null +++ b/packages/react-components/react-tree/stories/Tree/TreeExpandIcon.md @@ -0,0 +1,3 @@ +By default, `Tree` component comes with default expand/collapse icons. However, if you wish to customize the icons, you can use the `expandIcon` property provided by the `TreeItem` component. + +To do this, you need to specify the `expandIcon` property for each expandable/collapsible `TreeItem`. The value of the expandIcon property can be any valid React component, which will be rendered in place of the default expand/collapse icon. diff --git a/packages/react-components/react-tree/stories/Tree/TreeExpandIcon.stories.tsx b/packages/react-components/react-tree/stories/Tree/TreeExpandIcon.stories.tsx index c15fc01d1d5796..1982839903d8b4 100644 --- a/packages/react-components/react-tree/stories/Tree/TreeExpandIcon.stories.tsx +++ b/packages/react-components/react-tree/stories/Tree/TreeExpandIcon.stories.tsx @@ -2,6 +2,7 @@ import * as React from 'react'; import { Tree, TreeItem, TreeItemLayout } from '@fluentui/react-tree'; import { Add12Regular, Subtract12Regular } from '@fluentui/react-icons'; import { TreeOpenChangeData, TreeOpenChangeEvent } from '../../src/Tree'; +import story from './TreeExpandIcon.md'; export const ExpandIcon = () => { const [openItems, setOpenItems] = React.useState([]); @@ -51,3 +52,11 @@ export const ExpandIcon = () => { ); }; + +ExpandIcon.parameters = { + docs: { + description: { + story, + }, + }, +}; diff --git a/packages/react-components/react-tree/stories/Tree/TreeIconAfter.md b/packages/react-components/react-tree/stories/Tree/TreeIconAfter.md new file mode 100644 index 00000000000000..c627c9d3ec0830 --- /dev/null +++ b/packages/react-components/react-tree/stories/Tree/TreeIconAfter.md @@ -0,0 +1 @@ +The `TreeItemLayout` and `TreePersonaItemLayout` components allow you to add icons before or after the text of each `TreeItem` component in a `Tree`. To add an icon before the text, use the `iconBefore` prop, and to add an icon after the text, use the `iconAfter` prop. diff --git a/packages/react-components/react-tree/stories/Tree/TreeIconAfter.stories.tsx b/packages/react-components/react-tree/stories/Tree/TreeIconAfter.stories.tsx index 7d3cb158a70c83..d10bb7149f153b 100644 --- a/packages/react-components/react-tree/stories/Tree/TreeIconAfter.stories.tsx +++ b/packages/react-components/react-tree/stories/Tree/TreeIconAfter.stories.tsx @@ -1,6 +1,7 @@ import * as React from 'react'; import { Tree, TreeItem, TreeItemLayout } from '@fluentui/react-tree'; import { LockClosed20Regular } from '@fluentui/react-icons'; +import story from './TreeIconAfter.md'; export const IconAfter = () => { return ( @@ -35,3 +36,11 @@ export const IconAfter = () => { ); }; + +IconAfter.parameters = { + docs: { + description: { + story, + }, + }, +}; diff --git a/packages/react-components/react-tree/stories/Tree/TreeIconBefore.md b/packages/react-components/react-tree/stories/Tree/TreeIconBefore.md new file mode 100644 index 00000000000000..c627c9d3ec0830 --- /dev/null +++ b/packages/react-components/react-tree/stories/Tree/TreeIconBefore.md @@ -0,0 +1 @@ +The `TreeItemLayout` and `TreePersonaItemLayout` components allow you to add icons before or after the text of each `TreeItem` component in a `Tree`. To add an icon before the text, use the `iconBefore` prop, and to add an icon after the text, use the `iconAfter` prop. diff --git a/packages/react-components/react-tree/stories/Tree/TreeIconBefore.stories.tsx b/packages/react-components/react-tree/stories/Tree/TreeIconBefore.stories.tsx index 00bbe0e165cc2e..77d8cacbd5b3c5 100644 --- a/packages/react-components/react-tree/stories/Tree/TreeIconBefore.stories.tsx +++ b/packages/react-components/react-tree/stories/Tree/TreeIconBefore.stories.tsx @@ -1,6 +1,7 @@ import * as React from 'react'; import { Tree, TreeItem, TreeItemLayout } from '@fluentui/react-tree'; import { CheckboxChecked20Filled, CheckboxUnchecked20Filled } from '@fluentui/react-icons'; +import story from './TreeIconBefore.md'; export const IconBefore = () => { return ( @@ -35,3 +36,11 @@ export const IconBefore = () => { ); }; + +IconBefore.parameters = { + docs: { + description: { + story, + }, + }, +}; diff --git a/packages/react-components/react-tree/stories/Tree/TreeSize.md b/packages/react-components/react-tree/stories/Tree/TreeSize.md new file mode 100644 index 00000000000000..5fbe0229008748 --- /dev/null +++ b/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. diff --git a/packages/react-components/react-tree/stories/Tree/TreeSize.stories.tsx b/packages/react-components/react-tree/stories/Tree/TreeSize.stories.tsx index 0ef71656b7562b..7e0f313612f458 100644 --- a/packages/react-components/react-tree/stories/Tree/TreeSize.stories.tsx +++ b/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, }, }, }; diff --git a/packages/react-components/react-tree/stories/Tree/TreeWithInlineStyle.md b/packages/react-components/react-tree/stories/Tree/TreeWithInlineStyle.md new file mode 100644 index 00000000000000..4eeeb230c9e7ce --- /dev/null +++ b/packages/react-components/react-tree/stories/Tree/TreeWithInlineStyle.md @@ -0,0 +1 @@ +The style applied to the `TreeItem` component can be easily overridden by passing a custom style object as a prop to the `TreeItem` component. This allows for greater flexibility in customizing the styling of the tree items. diff --git a/packages/react-components/react-tree/stories/Tree/TreeWithInlineStyle.stories.tsx b/packages/react-components/react-tree/stories/Tree/TreeWithInlineStyle.stories.tsx index ecaf7e95648ed4..031834cec1035f 100644 --- a/packages/react-components/react-tree/stories/Tree/TreeWithInlineStyle.stories.tsx +++ b/packages/react-components/react-tree/stories/Tree/TreeWithInlineStyle.stories.tsx @@ -7,6 +7,7 @@ import { TreeItemProps, useTreeContext_unstable, } from '@fluentui/react-tree'; +import story from './TreeWithInlineStyle.md'; const TreeItem = (props: TreeItemProps) => { const level = useTreeContext_unstable(ctx => ctx.level); @@ -46,3 +47,11 @@ export const WithInlineStyle = () => { ); }; + +WithInlineStyle.parameters = { + docs: { + description: { + story, + }, + }, +}; From 0a73e317ab68af2854d0e75c0220a9c26fc01ee2 Mon Sep 17 00:00:00 2001 From: Petr Duda Date: Mon, 20 Mar 2023 22:19:01 +0100 Subject: [PATCH 19/34] more --- .../react-tree/stories/Tree/TreeLayout.md | 5 ++ .../stories/Tree/TreeLayout.stories.tsx | 9 +++ .../react-tree/stories/Tree/Virtualization.md | 3 + .../stories/Tree/Virtualization.stories.tsx | 9 +++ .../react-tree/stories/Tree/flattenTree.md | 3 + .../stories/Tree/flattenTree.stories.tsx | 10 +++ .../react-tree/stories/Tree/index.stories.tsx | 1 - .../stories/Tree/useFlatTreeItems.stories.tsx | 74 ------------------- 8 files changed, 39 insertions(+), 75 deletions(-) create mode 100644 packages/react-components/react-tree/stories/Tree/TreeLayout.md create mode 100644 packages/react-components/react-tree/stories/Tree/Virtualization.md create mode 100644 packages/react-components/react-tree/stories/Tree/flattenTree.md delete mode 100644 packages/react-components/react-tree/stories/Tree/useFlatTreeItems.stories.tsx diff --git a/packages/react-components/react-tree/stories/Tree/TreeLayout.md b/packages/react-components/react-tree/stories/Tree/TreeLayout.md new file mode 100644 index 00000000000000..cc9c769c455046 --- /dev/null +++ b/packages/react-components/react-tree/stories/Tree/TreeLayout.md @@ -0,0 +1,5 @@ +An example of a tree with combinations of props `actions` in `TreeItem` and `aside` in `TreeItemLayout` component. + +This example demonstrates how to 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. + +Each prop is described individually and can be overridden as needed. diff --git a/packages/react-components/react-tree/stories/Tree/TreeLayout.stories.tsx b/packages/react-components/react-tree/stories/Tree/TreeLayout.stories.tsx index c76588ad8d6442..4421c7f1c7fcd4 100644 --- a/packages/react-components/react-tree/stories/Tree/TreeLayout.stories.tsx +++ b/packages/react-components/react-tree/stories/Tree/TreeLayout.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 './TreeLayout.md'; const iconStyleProps: FluentIconsProps = { primaryFill: 'red', @@ -102,3 +103,11 @@ export const Layout = () => { ); }; + +Layout.parameters = { + docs: { + description: { + story, + }, + }, +}; diff --git a/packages/react-components/react-tree/stories/Tree/Virtualization.md b/packages/react-components/react-tree/stories/Tree/Virtualization.md new file mode 100644 index 00000000000000..e9016b28685139 --- /dev/null +++ b/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 the overall performance of the tree. + +To achieve this, one can create a `flattened` version of the tree structure that can be easily consumed by a windowing library. This library renders only the items that are currently visible on the screen, which reduces the amount of memory required to run the application. diff --git a/packages/react-components/react-tree/stories/Tree/Virtualization.stories.tsx b/packages/react-components/react-tree/stories/Tree/Virtualization.stories.tsx index f739173f3bf333..b3aa74eb059529 100644 --- a/packages/react-components/react-tree/stories/Tree/Virtualization.stories.tsx +++ b/packages/react-components/react-tree/stories/Tree/Virtualization.stories.tsx @@ -16,6 +16,7 @@ import { } from '@fluentui/react-tree'; import { FixedSizeList, FixedSizeListProps, ListChildComponentProps } from 'react-window'; import { ForwardRefComponent, getSlots } from '@fluentui/react-components'; +import story from './Virtualization.md'; const defaultItems: FlatTreeItemProps[] = [ { @@ -103,3 +104,11 @@ export const Virtualization = () => { /> ); }; + +Virtualization.parameters = { + docs: { + description: { + story, + }, + }, +}; diff --git a/packages/react-components/react-tree/stories/Tree/flattenTree.md b/packages/react-components/react-tree/stories/Tree/flattenTree.md new file mode 100644 index 00000000000000..9bf32b60f89407 --- /dev/null +++ b/packages/react-components/react-tree/stories/Tree/flattenTree.md @@ -0,0 +1,3 @@ +A `Tree` can be flattened, meaning that its nested structure is transformed into a flat list of items. This can be helpful when you need to display a tree in a linear fashion, such as in a list. + +In the code, the `defaultItems` array represents a flattened tree with each item containing the content to display. The `useFlatTree` hook transforms the flattened tree into a format that can be consumed by a `Tree` component. The `Tree` component handles rendering the nested structure, while the `useFlatTree` hook handles the logic for flattened data. diff --git a/packages/react-components/react-tree/stories/Tree/flattenTree.stories.tsx b/packages/react-components/react-tree/stories/Tree/flattenTree.stories.tsx index 0ca56473d8cfa5..60013bf4ba636d 100644 --- a/packages/react-components/react-tree/stories/Tree/flattenTree.stories.tsx +++ b/packages/react-components/react-tree/stories/Tree/flattenTree.stories.tsx @@ -1,5 +1,6 @@ import * as React from 'react'; import { Tree, TreeItem, TreeItemLayout, useFlatTree_unstable, flattenTree_unstable } from '@fluentui/react-tree'; +import story from './flattenTree.md'; const defaultItems = flattenTree_unstable([ { @@ -35,6 +36,7 @@ const defaultItems = flattenTree_unstable([ ], }, ]); + export const FlattenTree = () => { const flatTree = useFlatTree_unstable(defaultItems); return ( @@ -45,3 +47,11 @@ export const FlattenTree = () => { ); }; + +FlattenTree.parameters = { + docs: { + description: { + story, + }, + }, +}; diff --git a/packages/react-components/react-tree/stories/Tree/index.stories.tsx b/packages/react-components/react-tree/stories/Tree/index.stories.tsx index c642b6dabeca42..a042721286b943 100644 --- a/packages/react-components/react-tree/stories/Tree/index.stories.tsx +++ b/packages/react-components/react-tree/stories/Tree/index.stories.tsx @@ -16,7 +16,6 @@ export { Layout } from './TreeLayout.stories'; export { Size } from './TreeSize.stories'; export { Appearance } from './TreeAppearance.stories'; export { WithInlineStyle } from './TreeWithInlineStyle.stories'; -export { UseFlatTreeItems as useFlatTreeItems } from './useFlatTreeItems.stories'; export { FlattenTree as flattenTree } from './flattenTree.stories'; export { Virtualization } from './Virtualization.stories'; diff --git a/packages/react-components/react-tree/stories/Tree/useFlatTreeItems.stories.tsx b/packages/react-components/react-tree/stories/Tree/useFlatTreeItems.stories.tsx deleted file mode 100644 index 69e0e60242a51b..00000000000000 --- a/packages/react-components/react-tree/stories/Tree/useFlatTreeItems.stories.tsx +++ /dev/null @@ -1,74 +0,0 @@ -import * as React from 'react'; -import { Tree, TreeItem, TreeItemLayout, useFlatTree_unstable, FlatTreeItemProps } from '@fluentui/react-tree'; - -const defaultItems: FlatTreeItemProps[] = [ - { - id: '1', - children: Level 1, item 1, - }, - { - id: '1-1', - parentId: '1', - children: Level 2, item 1, - }, - { - id: '1-2', - parentId: '1', - children: Level 2, item 2, - }, - { - id: '1-3', - parentId: '1', - children: Level 2, item 3, - }, - { - id: '2', - children: Level 1, item 2, - }, - { - id: '2-1', - parentId: '2', - children: Level 2, item 1, - }, - { - id: '2-1-1', - parentId: '2-1', - children: Level 3, item 1, - }, - { - id: '2-2', - parentId: '2', - children: Level 2, item 2, - }, - { - id: '2-2-1', - parentId: '2-2', - children: Level 3, item 1, - }, - { - id: '2-2-2', - parentId: '2-2', - children: Level 3, item 2, - }, - { - id: '2-2-3', - parentId: '2-2', - children: Level 3, item 3, - }, - { - id: '3', - children: Level 1, item 3, - }, -]; - -export const UseFlatTreeItems = () => { - const flatTree = useFlatTree_unstable(defaultItems); - - return ( - - {Array.from(flatTree.items(), flatTreeItem => ( - - ))} - - ); -}; From 75550381c931489d13616e53360964747325baa7 Mon Sep 17 00:00:00 2001 From: Petr Duda Date: Mon, 20 Mar 2023 22:50:55 +0100 Subject: [PATCH 20/34] persona --- .../TreeItemPersonaLayout/TreeItemPersonaLayoutMedia.md | 3 +++ .../TreeItemPersonaLayoutMedia.stories.tsx | 9 +++++++++ .../TreeItemPersonaLayoutReadUnread.md | 3 +++ .../TreeItemPersonaLayoutReadUnread.stories.tsx | 9 +++++++++ .../TreeItemPersonaLayoutWithDescription.md | 1 + .../TreeItemPersonaLayoutWithDescription.stories.tsx | 9 +++++++++ 6 files changed, 34 insertions(+) create mode 100644 packages/react-components/react-tree/stories/TreeItemPersonaLayout/TreeItemPersonaLayoutMedia.md create mode 100644 packages/react-components/react-tree/stories/TreeItemPersonaLayout/TreeItemPersonaLayoutReadUnread.md create mode 100644 packages/react-components/react-tree/stories/TreeItemPersonaLayout/TreeItemPersonaLayoutWithDescription.md diff --git a/packages/react-components/react-tree/stories/TreeItemPersonaLayout/TreeItemPersonaLayoutMedia.md b/packages/react-components/react-tree/stories/TreeItemPersonaLayout/TreeItemPersonaLayoutMedia.md new file mode 100644 index 00000000000000..8b43955e7368fc --- /dev/null +++ b/packages/react-components/react-tree/stories/TreeItemPersonaLayout/TreeItemPersonaLayoutMedia.md @@ -0,0 +1,3 @@ +The `Tree` 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. Nested Tree components can also contain `TreeItem` components with `TreeItemPersonaLayout` components with different media components. This layout provides a visually appealing representation of hierarchical data. diff --git a/packages/react-components/react-tree/stories/TreeItemPersonaLayout/TreeItemPersonaLayoutMedia.stories.tsx b/packages/react-components/react-tree/stories/TreeItemPersonaLayout/TreeItemPersonaLayoutMedia.stories.tsx index 4decbda8d4598d..e8c47e1d15c2cb 100644 --- a/packages/react-components/react-tree/stories/TreeItemPersonaLayout/TreeItemPersonaLayoutMedia.stories.tsx +++ b/packages/react-components/react-tree/stories/TreeItemPersonaLayout/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 = () => { ); }; + +Media.parameters = { + docs: { + description: { + story, + }, + }, +}; diff --git a/packages/react-components/react-tree/stories/TreeItemPersonaLayout/TreeItemPersonaLayoutReadUnread.md b/packages/react-components/react-tree/stories/TreeItemPersonaLayout/TreeItemPersonaLayoutReadUnread.md new file mode 100644 index 00000000000000..8a9ba088ccf2da --- /dev/null +++ b/packages/react-components/react-tree/stories/TreeItemPersonaLayout/TreeItemPersonaLayoutReadUnread.md @@ -0,0 +1,3 @@ +The `Tree` component can be customized with different styles to make it more visually appealing. In the example below, the `TreeItemPersonaLayout` component is used to display messages with a `description` and an `Avatar` as the `media` prop. + +The `description` prop is used to provide a secondary text content that can be customized with styles. In this case, the unread class from the `makeStyles` hook is applied to the div element to make the text appear `bold` for unread messages. diff --git a/packages/react-components/react-tree/stories/TreeItemPersonaLayout/TreeItemPersonaLayoutReadUnread.stories.tsx b/packages/react-components/react-tree/stories/TreeItemPersonaLayout/TreeItemPersonaLayoutReadUnread.stories.tsx index fb6df6d7b88769..e8ff0fbab60928 100644 --- a/packages/react-components/react-tree/stories/TreeItemPersonaLayout/TreeItemPersonaLayoutReadUnread.stories.tsx +++ b/packages/react-components/react-tree/stories/TreeItemPersonaLayout/TreeItemPersonaLayoutReadUnread.stories.tsx @@ -1,6 +1,7 @@ import * as React from 'react'; import { Avatar, makeStyles } from '@fluentui/react-components'; import { Tree, TreeItem, TreeItemPersonaLayout } from '@fluentui/react-tree'; +import story from './TreeItemPersonaLayoutReadUnread.md'; const useStyles = makeStyles({ unread: { @@ -29,3 +30,11 @@ export const ReadUnread = () => { ); }; + +ReadUnread.parameters = { + docs: { + description: { + story, + }, + }, +}; diff --git a/packages/react-components/react-tree/stories/TreeItemPersonaLayout/TreeItemPersonaLayoutWithDescription.md b/packages/react-components/react-tree/stories/TreeItemPersonaLayout/TreeItemPersonaLayoutWithDescription.md new file mode 100644 index 00000000000000..3fe22df2bf7277 --- /dev/null +++ b/packages/react-components/react-tree/stories/TreeItemPersonaLayout/TreeItemPersonaLayoutWithDescription.md @@ -0,0 +1 @@ +The `TreeItemPersonaLayout` component allows you to add a `description` prop 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. diff --git a/packages/react-components/react-tree/stories/TreeItemPersonaLayout/TreeItemPersonaLayoutWithDescription.stories.tsx b/packages/react-components/react-tree/stories/TreeItemPersonaLayout/TreeItemPersonaLayoutWithDescription.stories.tsx index 3beace7f217c82..feb24dad41aada 100644 --- a/packages/react-components/react-tree/stories/TreeItemPersonaLayout/TreeItemPersonaLayoutWithDescription.stories.tsx +++ b/packages/react-components/react-tree/stories/TreeItemPersonaLayout/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 = () => { ); }; + +WithDescription.parameters = { + docs: { + description: { + story, + }, + }, +}; From 782f0f27cb5387fb2e3ea46bfa273da9f8adb079 Mon Sep 17 00:00:00 2001 From: Petr Duda Date: Mon, 20 Mar 2023 23:15:39 +0100 Subject: [PATCH 21/34] simplifiy --- .../react-tree/stories/Tree/TreeActions.md | 2 +- .../stories/Tree/TreeBestPractices.md | 31 +++++++++++++++++-- .../react-tree/stories/Tree/TreeIconAfter.md | 1 - .../stories/Tree/TreeIconAfter.stories.tsx | 9 ------ .../react-tree/stories/Tree/TreeIconBefore.md | 2 ++ .../react-tree/stories/Tree/TreeLayout.md | 4 --- .../react-tree/stories/Tree/index.stories.tsx | 14 ++++----- 7 files changed, 39 insertions(+), 24 deletions(-) delete mode 100644 packages/react-components/react-tree/stories/Tree/TreeIconAfter.md diff --git a/packages/react-components/react-tree/stories/Tree/TreeActions.md b/packages/react-components/react-tree/stories/Tree/TreeActions.md index f199bcd996dd41..8c24f1d25388a2 100644 --- a/packages/react-components/react-tree/stories/Tree/TreeActions.md +++ b/packages/react-components/react-tree/stories/Tree/TreeActions.md @@ -1,3 +1,3 @@ -The `Tree` component lets you add custom actions to each `TreeItem`, such as buttons or menus. This can be done by passing a component that renders the desired actions as a prop to the `TreeItem`. +Add custom actions to each `TreeItem` component to add extra functionality, such as buttons or menus. This can be done by passing a component that renders the desired actions as a prop to the `TreeItem`. The `actions` are hidden by default and appear on the right side when the user hovers over the `TreeItem`, allowing for a clean and uncluttered display. diff --git a/packages/react-components/react-tree/stories/Tree/TreeBestPractices.md b/packages/react-components/react-tree/stories/Tree/TreeBestPractices.md index 08ff8ddeeb5f86..94960d06967cd7 100644 --- a/packages/react-components/react-tree/stories/Tree/TreeBestPractices.md +++ b/packages/react-components/react-tree/stories/Tree/TreeBestPractices.md @@ -1,5 +1,32 @@ -## Best practices + diff --git a/packages/react-components/react-tree/stories/Tree/TreeIconAfter.md b/packages/react-components/react-tree/stories/Tree/TreeIconAfter.md deleted file mode 100644 index c627c9d3ec0830..00000000000000 --- a/packages/react-components/react-tree/stories/Tree/TreeIconAfter.md +++ /dev/null @@ -1 +0,0 @@ -The `TreeItemLayout` and `TreePersonaItemLayout` components allow you to add icons before or after the text of each `TreeItem` component in a `Tree`. To add an icon before the text, use the `iconBefore` prop, and to add an icon after the text, use the `iconAfter` prop. diff --git a/packages/react-components/react-tree/stories/Tree/TreeIconAfter.stories.tsx b/packages/react-components/react-tree/stories/Tree/TreeIconAfter.stories.tsx index d10bb7149f153b..7d3cb158a70c83 100644 --- a/packages/react-components/react-tree/stories/Tree/TreeIconAfter.stories.tsx +++ b/packages/react-components/react-tree/stories/Tree/TreeIconAfter.stories.tsx @@ -1,7 +1,6 @@ import * as React from 'react'; import { Tree, TreeItem, TreeItemLayout } from '@fluentui/react-tree'; import { LockClosed20Regular } from '@fluentui/react-icons'; -import story from './TreeIconAfter.md'; export const IconAfter = () => { return ( @@ -36,11 +35,3 @@ export const IconAfter = () => { ); }; - -IconAfter.parameters = { - docs: { - description: { - story, - }, - }, -}; diff --git a/packages/react-components/react-tree/stories/Tree/TreeIconBefore.md b/packages/react-components/react-tree/stories/Tree/TreeIconBefore.md index c627c9d3ec0830..f4e61911552d73 100644 --- a/packages/react-components/react-tree/stories/Tree/TreeIconBefore.md +++ b/packages/react-components/react-tree/stories/Tree/TreeIconBefore.md @@ -1 +1,3 @@ The `TreeItemLayout` and `TreePersonaItemLayout` components allow you to add icons before or after the text of each `TreeItem` component in a `Tree`. To add an icon before the text, use the `iconBefore` prop, and to add an icon after the text, use the `iconAfter` prop. + +You can add combine them if you need both: diff --git a/packages/react-components/react-tree/stories/Tree/TreeLayout.md b/packages/react-components/react-tree/stories/Tree/TreeLayout.md index cc9c769c455046..38442a441221cc 100644 --- a/packages/react-components/react-tree/stories/Tree/TreeLayout.md +++ b/packages/react-components/react-tree/stories/Tree/TreeLayout.md @@ -1,5 +1 @@ -An example of a tree with combinations of props `actions` in `TreeItem` and `aside` in `TreeItemLayout` component. - This example demonstrates how to 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. - -Each prop is described individually and can be overridden as needed. diff --git a/packages/react-components/react-tree/stories/Tree/index.stories.tsx b/packages/react-components/react-tree/stories/Tree/index.stories.tsx index a042721286b943..0ff805dd3ed327 100644 --- a/packages/react-components/react-tree/stories/Tree/index.stories.tsx +++ b/packages/react-components/react-tree/stories/Tree/index.stories.tsx @@ -4,20 +4,20 @@ import descriptionMd from './TreeDescription.md'; import bestPracticesMd from './TreeBestPractices.md'; export { Default } from './TreeDefault.stories'; -export { OpenItemsControlled } from './TreeControllingOpenAndClose.stories'; -export { ExpandCollapseIconOnly } from './TreeExpandCollapseIconOnly.stories'; export { DefaultOpenTrees } from './TreeDefaultOpenTrees.stories'; -export { Actions } from './TreeActions.stories'; -export { Aside } from './TreeAside.stories'; export { ExpandIcon } from './TreeExpandIcon.stories'; export { IconBefore } from './TreeIconBefore.stories'; export { IconAfter } from './TreeIconAfter.stories'; -export { Layout } from './TreeLayout.stories'; -export { Size } from './TreeSize.stories'; +export { Actions } from './TreeActions.stories'; +export { Aside } from './TreeAside.stories'; export { Appearance } from './TreeAppearance.stories'; -export { WithInlineStyle } from './TreeWithInlineStyle.stories'; +export { Size } from './TreeSize.stories'; +export { Layout } from './TreeLayout.stories'; +export { OpenItemsControlled } from './TreeControllingOpenAndClose.stories'; +export { ExpandCollapseIconOnly } from './TreeExpandCollapseIconOnly.stories'; export { FlattenTree as flattenTree } from './flattenTree.stories'; export { Virtualization } from './Virtualization.stories'; +export { WithInlineStyle } from './TreeWithInlineStyle.stories'; export default { title: 'Preview Components/Tree', From 86231ba2930cbbff9a55b8079f8b9d1794635505 Mon Sep 17 00:00:00 2001 From: Petr Duda Date: Mon, 20 Mar 2023 23:16:16 +0100 Subject: [PATCH 22/34] description --- .../react-tree/stories/Tree/TreeDescription.md | 13 +------------ .../react-tree/stories/Tree/TreeExpandIcon.md | 4 ++-- 2 files changed, 3 insertions(+), 14 deletions(-) diff --git a/packages/react-components/react-tree/stories/Tree/TreeDescription.md b/packages/react-components/react-tree/stories/Tree/TreeDescription.md index 73f177d09a492f..7ceb91d972df25 100644 --- a/packages/react-components/react-tree/stories/Tree/TreeDescription.md +++ b/packages/react-components/react-tree/stories/Tree/TreeDescription.md @@ -1,12 +1 @@ - - -> **⚠️ Preview components are considered unstable:** -> -> ```jsx -> -> import { Tree } from '@fluentui/react-components/unstable'; -> -> ``` -> -> - Features and APIs may change before final release -> - Please contact us if you intend to use this in your product +`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. diff --git a/packages/react-components/react-tree/stories/Tree/TreeExpandIcon.md b/packages/react-components/react-tree/stories/Tree/TreeExpandIcon.md index 5a1cc26cd72f9c..52316cde22ea31 100644 --- a/packages/react-components/react-tree/stories/Tree/TreeExpandIcon.md +++ b/packages/react-components/react-tree/stories/Tree/TreeExpandIcon.md @@ -1,3 +1,3 @@ -By default, `Tree` component comes with default expand/collapse icons. However, if you wish to customize the icons, you can use the `expandIcon` property provided by the `TreeItem` component. +If you wish to customize the open/collapse icons, you can use the `expandIcon` property provided by the `TreeItem` component. -To do this, you need to specify the `expandIcon` property for each expandable/collapsible `TreeItem`. The value of the expandIcon property can be any valid React component, which will be rendered in place of the default expand/collapse icon. +This example replaces the default expand/collapse arrow icons with plus and minus characters to achieve a similar behavior. From 05d82eb16bbf069fafa161e557ce0ff5058ecf73 Mon Sep 17 00:00:00 2001 From: Petr Duda Date: Tue, 21 Mar 2023 11:10:55 +0100 Subject: [PATCH 23/34] persona and changes --- .../src/components/TreeItemLayout/TreeItemLayout.tsx | 5 ++++- .../TreeItemPersonaLayout/TreeItemPersonaLayout.tsx | 4 +++- .../react-tree/stories/Tree/TreeActions.md | 2 +- .../react-tree/stories/Tree/TreeAppearance.md | 2 +- .../react-tree/stories/Tree/TreeAside.md | 2 +- .../react-tree/stories/Tree/TreeAside.stories.tsx | 4 ++-- .../stories/Tree/TreeControllingOpenAndClose.md | 2 -- .../react-tree/stories/Tree/TreeIconBefore.md | 4 ++-- .../react-tree/stories/Tree/TreeLayout.md | 2 +- .../TreeItemPersonaLayoutDescription.md | 1 + .../TreeItemPersonaLayout/TreeItemPersonaLayoutMedia.md | 4 ++-- .../TreeItemPersonaLayoutReadUnread.md | 4 +--- .../TreeItemPersonaLayoutReadUnread.stories.tsx | 4 ++-- .../TreeItemPersonaLayoutWithDescription.md | 2 +- .../stories/TreeItemPersonaLayout/TreePersonaLayout.md | 1 + .../TreeItemPersonaLayout/TreePersonaLayout.stories.tsx | 9 +++++++++ .../stories/TreeItemPersonaLayout/index.stories.tsx | 6 ++---- 17 files changed, 34 insertions(+), 24 deletions(-) create mode 100644 packages/react-components/react-tree/stories/TreeItemPersonaLayout/TreePersonaLayout.md diff --git a/packages/react-components/react-tree/src/components/TreeItemLayout/TreeItemLayout.tsx b/packages/react-components/react-tree/src/components/TreeItemLayout/TreeItemLayout.tsx index 9eb0c32604cc56..2d36db6755de5c 100644 --- a/packages/react-components/react-tree/src/components/TreeItemLayout/TreeItemLayout.tsx +++ b/packages/react-components/react-tree/src/components/TreeItemLayout/TreeItemLayout.tsx @@ -6,8 +6,11 @@ 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 = React.forwardRef((props, ref) => { const state = useTreeItemLayout_unstable(props, ref); diff --git a/packages/react-components/react-tree/src/components/TreeItemPersonaLayout/TreeItemPersonaLayout.tsx b/packages/react-components/react-tree/src/components/TreeItemPersonaLayout/TreeItemPersonaLayout.tsx index 9e5b8f44b762ff..55ede65c081c02 100644 --- a/packages/react-components/react-tree/src/components/TreeItemPersonaLayout/TreeItemPersonaLayout.tsx +++ b/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 = React.forwardRef((props, ref) => { const state = useTreeItemPersonaLayout_unstable(props, ref); diff --git a/packages/react-components/react-tree/stories/Tree/TreeActions.md b/packages/react-components/react-tree/stories/Tree/TreeActions.md index 8c24f1d25388a2..385a3148f42c42 100644 --- a/packages/react-components/react-tree/stories/Tree/TreeActions.md +++ b/packages/react-components/react-tree/stories/Tree/TreeActions.md @@ -1,3 +1,3 @@ Add custom actions to each `TreeItem` component to add extra functionality, such as buttons or menus. This can be done by passing a component that renders the desired actions as a prop to the `TreeItem`. -The `actions` are hidden by default and appear on the right side when the user hovers over the `TreeItem`, allowing for a clean and uncluttered display. +The `actions` are hidden by default and appear on the right-side when the user hovers over the `TreeItem`. diff --git a/packages/react-components/react-tree/stories/Tree/TreeAppearance.md b/packages/react-components/react-tree/stories/Tree/TreeAppearance.md index 7583f9bbbc94cd..19f6bcf3eda8cd 100644 --- a/packages/react-components/react-tree/stories/Tree/TreeAppearance.md +++ b/packages/react-components/react-tree/stories/Tree/TreeAppearance.md @@ -1 +1 @@ -The `Tree` component supports different appearances for TreeItems. The default `appearance` is used when no appearance is specified. The `subtle` appearance minimizes emphasis on hovered or focused states, while the `transparent` appearance removes the background color. +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. diff --git a/packages/react-components/react-tree/stories/Tree/TreeAside.md b/packages/react-components/react-tree/stories/Tree/TreeAside.md index d205165dc8e46a..495cf8d10096b0 100644 --- a/packages/react-components/react-tree/stories/Tree/TreeAside.md +++ b/packages/react-components/react-tree/stories/Tree/TreeAside.md @@ -1 +1 @@ -The `Tree` component allows for an `aside` prop to be added to individual `TreeItemLayout` or `TreeItemPersonaLayout` 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. +The `Tree` component allows for an `aside` prop to be added to individual `TreeItemLayout` or `TreeItemPersonaLayout` 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. diff --git a/packages/react-components/react-tree/stories/Tree/TreeAside.stories.tsx b/packages/react-components/react-tree/stories/Tree/TreeAside.stories.tsx index 43545c80adb92c..08991de00650f9 100644 --- a/packages/react-components/react-tree/stories/Tree/TreeAside.stories.tsx +++ b/packages/react-components/react-tree/stories/Tree/TreeAside.stories.tsx @@ -24,7 +24,7 @@ const Actions = () => ( export const Aside = () => ( - }> + }>level 1, item 1 }> @@ -38,7 +38,7 @@ export const Aside = () => ( - }> + }>level 1, item 2 }> diff --git a/packages/react-components/react-tree/stories/Tree/TreeControllingOpenAndClose.md b/packages/react-components/react-tree/stories/Tree/TreeControllingOpenAndClose.md index 0e4a934b1922d9..ec78c4c204dc7d 100644 --- a/packages/react-components/react-tree/stories/Tree/TreeControllingOpenAndClose.md +++ b/packages/react-components/react-tree/stories/Tree/TreeControllingOpenAndClose.md @@ -1,5 +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. - -To control the open/closed state of a `TreeItem`, an `id` prop must be provided to the `TreeItem` component. This `id` prop can then be used to identify the `TreeItem` in the `handleOpenChange` function and update the `openItems` state. diff --git a/packages/react-components/react-tree/stories/Tree/TreeIconBefore.md b/packages/react-components/react-tree/stories/Tree/TreeIconBefore.md index f4e61911552d73..45a4887f6732d9 100644 --- a/packages/react-components/react-tree/stories/Tree/TreeIconBefore.md +++ b/packages/react-components/react-tree/stories/Tree/TreeIconBefore.md @@ -1,3 +1,3 @@ -The `TreeItemLayout` and `TreePersonaItemLayout` components allow you to add icons before or after the text of each `TreeItem` component in a `Tree`. To add an icon before the text, use the `iconBefore` prop, and to add an icon after the text, use the `iconAfter` prop. +The `TreeItemLayout` and `TreePersonaItemLayout` components allow you to add icons before or after the content of each `TreeItem` component. To add an icon before the text, use the `iconBefore` prop, and to add an icon after the text, use the `iconAfter` prop. -You can add combine them if you need both: +You can add both at the same time. diff --git a/packages/react-components/react-tree/stories/Tree/TreeLayout.md b/packages/react-components/react-tree/stories/Tree/TreeLayout.md index 38442a441221cc..da5e107408907b 100644 --- a/packages/react-components/react-tree/stories/Tree/TreeLayout.md +++ b/packages/react-components/react-tree/stories/Tree/TreeLayout.md @@ -1 +1 @@ -This example demonstrates how to 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. +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. diff --git a/packages/react-components/react-tree/stories/TreeItemPersonaLayout/TreeItemPersonaLayoutDescription.md b/packages/react-components/react-tree/stories/TreeItemPersonaLayout/TreeItemPersonaLayoutDescription.md index e69de29bb2d1d6..6130dc586949aa 100644 --- a/packages/react-components/react-tree/stories/TreeItemPersonaLayout/TreeItemPersonaLayoutDescription.md +++ b/packages/react-components/react-tree/stories/TreeItemPersonaLayout/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. diff --git a/packages/react-components/react-tree/stories/TreeItemPersonaLayout/TreeItemPersonaLayoutMedia.md b/packages/react-components/react-tree/stories/TreeItemPersonaLayout/TreeItemPersonaLayoutMedia.md index 8b43955e7368fc..ae06924ccf5c82 100644 --- a/packages/react-components/react-tree/stories/TreeItemPersonaLayout/TreeItemPersonaLayoutMedia.md +++ b/packages/react-components/react-tree/stories/TreeItemPersonaLayout/TreeItemPersonaLayoutMedia.md @@ -1,3 +1,3 @@ -The `Tree` component allows each `TreeItem` to be displayed with a persona layout, which supports a `media` prop such as an `Avatar`. +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. Nested Tree components can also contain `TreeItem` components with `TreeItemPersonaLayout` components with different media components. This layout provides a visually appealing representation of hierarchical data. +The `Avatar` component can be customized with different sizes and shapes to suit the design needs. diff --git a/packages/react-components/react-tree/stories/TreeItemPersonaLayout/TreeItemPersonaLayoutReadUnread.md b/packages/react-components/react-tree/stories/TreeItemPersonaLayout/TreeItemPersonaLayoutReadUnread.md index 8a9ba088ccf2da..eff0fde898036a 100644 --- a/packages/react-components/react-tree/stories/TreeItemPersonaLayout/TreeItemPersonaLayoutReadUnread.md +++ b/packages/react-components/react-tree/stories/TreeItemPersonaLayout/TreeItemPersonaLayoutReadUnread.md @@ -1,3 +1 @@ -The `Tree` component can be customized with different styles to make it more visually appealing. In the example below, the `TreeItemPersonaLayout` component is used to display messages with a `description` and an `Avatar` as the `media` prop. - -The `description` prop is used to provide a secondary text content that can be customized with styles. In this case, the unread class from the `makeStyles` hook is applied to the div element to make the text appear `bold` for unread messages. +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. diff --git a/packages/react-components/react-tree/stories/TreeItemPersonaLayout/TreeItemPersonaLayoutReadUnread.stories.tsx b/packages/react-components/react-tree/stories/TreeItemPersonaLayout/TreeItemPersonaLayoutReadUnread.stories.tsx index e8ff0fbab60928..a3a1ddddffb7ba 100644 --- a/packages/react-components/react-tree/stories/TreeItemPersonaLayout/TreeItemPersonaLayoutReadUnread.stories.tsx +++ b/packages/react-components/react-tree/stories/TreeItemPersonaLayout/TreeItemPersonaLayoutReadUnread.stories.tsx @@ -1,11 +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, }, }); diff --git a/packages/react-components/react-tree/stories/TreeItemPersonaLayout/TreeItemPersonaLayoutWithDescription.md b/packages/react-components/react-tree/stories/TreeItemPersonaLayout/TreeItemPersonaLayoutWithDescription.md index 3fe22df2bf7277..7ce381c22ba3b9 100644 --- a/packages/react-components/react-tree/stories/TreeItemPersonaLayout/TreeItemPersonaLayoutWithDescription.md +++ b/packages/react-components/react-tree/stories/TreeItemPersonaLayout/TreeItemPersonaLayoutWithDescription.md @@ -1 +1 @@ -The `TreeItemPersonaLayout` component allows you to add a `description` prop 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. +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. diff --git a/packages/react-components/react-tree/stories/TreeItemPersonaLayout/TreePersonaLayout.md b/packages/react-components/react-tree/stories/TreeItemPersonaLayout/TreePersonaLayout.md new file mode 100644 index 00000000000000..8778ca825b31c1 --- /dev/null +++ b/packages/react-components/react-tree/stories/TreeItemPersonaLayout/TreePersonaLayout.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. diff --git a/packages/react-components/react-tree/stories/TreeItemPersonaLayout/TreePersonaLayout.stories.tsx b/packages/react-components/react-tree/stories/TreeItemPersonaLayout/TreePersonaLayout.stories.tsx index 563ceb09703b92..1b72ba67dd50a2 100644 --- a/packages/react-components/react-tree/stories/TreeItemPersonaLayout/TreePersonaLayout.stories.tsx +++ b/packages/react-components/react-tree/stories/TreeItemPersonaLayout/TreePersonaLayout.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 './TreePersonaLayout.md'; const useBadgeStyles = makeStyles({ base: { @@ -132,3 +133,11 @@ export const TreePersonaLayout = () => { ); }; + +TreePersonaLayout.parameters = { + docs: { + description: { + story, + }, + }, +}; diff --git a/packages/react-components/react-tree/stories/TreeItemPersonaLayout/index.stories.tsx b/packages/react-components/react-tree/stories/TreeItemPersonaLayout/index.stories.tsx index f4134a0adaa11c..1694ff66f88245 100644 --- a/packages/react-components/react-tree/stories/TreeItemPersonaLayout/index.stories.tsx +++ b/packages/react-components/react-tree/stories/TreeItemPersonaLayout/index.stories.tsx @@ -1,12 +1,10 @@ import { TreeItemPersonaLayout } from '@fluentui/react-tree'; - import descriptionMd from './TreeItemPersonaLayoutDescription.md'; - export { Default } from './TreeItemPersonaLayoutDefault.stories'; -export { TreePersonaLayout } from './TreePersonaLayout.stories'; +export { Media } from './TreeItemPersonaLayoutMedia.stories'; export { WithDescription } from './TreeItemPersonaLayoutWithDescription.stories'; export { ReadUnread } from './TreeItemPersonaLayoutReadUnread.stories'; -export { Media } from './TreeItemPersonaLayoutMedia.stories'; +export { TreePersonaLayout } from './TreePersonaLayout.stories'; export default { title: 'Preview Components/Tree/PersonaTreeItem', From a592f48986822e920cc710f8319f04e8335d2dc2 Mon Sep 17 00:00:00 2001 From: Petr Duda Date: Tue, 21 Mar 2023 12:59:59 +0100 Subject: [PATCH 24/34] update desc --- .../react-tree/src/components/TreeItem/TreeItem.tsx | 9 ++++++++- .../src/components/TreeItemLayout/TreeItemLayout.tsx | 1 - .../react-tree/stories/Tree/TreeWithInlineStyle.md | 4 +++- 3 files changed, 11 insertions(+), 3 deletions(-) diff --git a/packages/react-components/react-tree/src/components/TreeItem/TreeItem.tsx b/packages/react-components/react-tree/src/components/TreeItem/TreeItem.tsx index 58c032dee313ff..2acdd0908ff19a 100644 --- a/packages/react-components/react-tree/src/components/TreeItem/TreeItem.tsx +++ b/packages/react-components/react-tree/src/components/TreeItem/TreeItem.tsx @@ -7,7 +7,14 @@ 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 can contain child items in the form of another Tree component or standalone TreeItem. + * 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 child items, an expand/collapse control is displayed, + * allowing the user to show or hide the children. + * This provides a convenient way to navigate hierarchical data, such as a file system or a category tree. */ export const TreeItem: ForwardRefComponent = React.forwardRef((props, ref) => { const state = useTreeItem_unstable(props, ref); diff --git a/packages/react-components/react-tree/src/components/TreeItemLayout/TreeItemLayout.tsx b/packages/react-components/react-tree/src/components/TreeItemLayout/TreeItemLayout.tsx index 2d36db6755de5c..7de4b11e7d2a2f 100644 --- a/packages/react-components/react-tree/src/components/TreeItemLayout/TreeItemLayout.tsx +++ b/packages/react-components/react-tree/src/components/TreeItemLayout/TreeItemLayout.tsx @@ -10,7 +10,6 @@ import type { ForwardRefComponent } from '@fluentui/react-utilities'; * 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 = React.forwardRef((props, ref) => { const state = useTreeItemLayout_unstable(props, ref); diff --git a/packages/react-components/react-tree/stories/Tree/TreeWithInlineStyle.md b/packages/react-components/react-tree/stories/Tree/TreeWithInlineStyle.md index 4eeeb230c9e7ce..0cd87707272ef0 100644 --- a/packages/react-components/react-tree/stories/Tree/TreeWithInlineStyle.md +++ b/packages/react-components/react-tree/stories/Tree/TreeWithInlineStyle.md @@ -1 +1,3 @@ -The style applied to the `TreeItem` component can be easily overridden by passing a custom style object as a prop to the `TreeItem` component. This allows for greater flexibility in customizing the styling of the tree items. +We support nested styling for the `Tree` component up to 10 levels of nesting due to performance implications. If you need to support more than 10 levels of nesting, you should consider using dynamic styling instead. + +The example below shows how to apply custom styles to `TreeItem` using inline styles to override the default static styles. From 1c58dea9c91beb13e91e6ee0e10dcbf3ade5a86e Mon Sep 17 00:00:00 2001 From: Petr Duda Date: Wed, 22 Mar 2023 10:01:34 +0100 Subject: [PATCH 25/34] folder structure --- .../TreeItemLayout.md} | 0 .../TreeItemLayout.stories.tsx} | 2 +- .../stories/Layouts/TreeItemLayoutAside.md | 1 + .../TreeItemLayoutAside.stories.tsx} | 2 +- .../Layouts/TreeItemLayoutDefault.stories.tsx | 36 +++++++++++++++++++ .../TreeItemPersonaLayout.md} | 0 .../TreeItemPersonaLayout.stories.tsx} | 2 +- .../TreeItemPersonaLayoutDefault.stories.tsx | 2 +- .../TreeItemPersonaLayoutDescription.md | 0 .../TreeItemPersonaLayoutMedia.md | 0 .../TreeItemPersonaLayoutMedia.stories.tsx | 0 .../TreeItemPersonaLayoutReadUnread.md | 0 ...reeItemPersonaLayoutReadUnread.stories.tsx | 0 .../TreeItemPersonaLayoutWithDescription.md | 0 ...emPersonaLayoutWithDescription.stories.tsx | 0 .../react-tree/stories/Layouts/description.md | 5 +++ .../stories/Layouts/index.stories.tsx | 23 ++++++++++++ .../react-tree/stories/Tree/TreeAside.md | 1 - .../react-tree/stories/Tree/index.stories.tsx | 13 ++----- .../TreeItemActions.md} | 0 .../TreeItemActions.stories.tsx} | 2 +- .../TreeItem/TreeItemDefault.stories.tsx | 36 +++++++++++++++++++ .../stories/TreeItem/TreeItemDescription.md | 3 ++ .../TreeItemExpandCollapseIconOnly.md} | 0 ...reeItemExpandCollapseIconOnly.stories.tsx} | 2 +- .../TreeItemExpandIcon.md} | 0 .../TreeItemExpandIcon.stories.tsx} | 2 +- .../TreeItemIconAfter.stories.tsx} | 0 .../TreeItemIconBefore.md} | 0 .../TreeItemIconBefore.stories.tsx} | 2 +- .../TreeItemWithInlineStyle.md} | 0 .../TreeItemWithInlineStyle.stories.tsx} | 2 +- .../stories/TreeItem/index.stories.tsx | 23 ++++++++++++ .../TreeItemPersonaLayout/index.stories.tsx | 19 ---------- 34 files changed, 139 insertions(+), 39 deletions(-) rename packages/react-components/react-tree/stories/{Tree/TreeLayout.md => Layouts/TreeItemLayout.md} (100%) rename packages/react-components/react-tree/stories/{Tree/TreeLayout.stories.tsx => Layouts/TreeItemLayout.stories.tsx} (98%) create mode 100644 packages/react-components/react-tree/stories/Layouts/TreeItemLayoutAside.md rename packages/react-components/react-tree/stories/{Tree/TreeAside.stories.tsx => Layouts/TreeItemLayoutAside.stories.tsx} (98%) create mode 100644 packages/react-components/react-tree/stories/Layouts/TreeItemLayoutDefault.stories.tsx rename packages/react-components/react-tree/stories/{TreeItemPersonaLayout/TreePersonaLayout.md => Layouts/TreeItemPersonaLayout.md} (100%) rename packages/react-components/react-tree/stories/{TreeItemPersonaLayout/TreePersonaLayout.stories.tsx => Layouts/TreeItemPersonaLayout.stories.tsx} (98%) rename packages/react-components/react-tree/stories/{TreeItemPersonaLayout => Layouts}/TreeItemPersonaLayoutDefault.stories.tsx (95%) rename packages/react-components/react-tree/stories/{TreeItemPersonaLayout => Layouts}/TreeItemPersonaLayoutDescription.md (100%) rename packages/react-components/react-tree/stories/{TreeItemPersonaLayout => Layouts}/TreeItemPersonaLayoutMedia.md (100%) rename packages/react-components/react-tree/stories/{TreeItemPersonaLayout => Layouts}/TreeItemPersonaLayoutMedia.stories.tsx (100%) rename packages/react-components/react-tree/stories/{TreeItemPersonaLayout => Layouts}/TreeItemPersonaLayoutReadUnread.md (100%) rename packages/react-components/react-tree/stories/{TreeItemPersonaLayout => Layouts}/TreeItemPersonaLayoutReadUnread.stories.tsx (100%) rename packages/react-components/react-tree/stories/{TreeItemPersonaLayout => Layouts}/TreeItemPersonaLayoutWithDescription.md (100%) rename packages/react-components/react-tree/stories/{TreeItemPersonaLayout => Layouts}/TreeItemPersonaLayoutWithDescription.stories.tsx (100%) create mode 100644 packages/react-components/react-tree/stories/Layouts/description.md create mode 100644 packages/react-components/react-tree/stories/Layouts/index.stories.tsx delete mode 100644 packages/react-components/react-tree/stories/Tree/TreeAside.md rename packages/react-components/react-tree/stories/{Tree/TreeActions.md => TreeItem/TreeItemActions.md} (100%) rename packages/react-components/react-tree/stories/{Tree/TreeActions.stories.tsx => TreeItem/TreeItemActions.stories.tsx} (98%) create mode 100644 packages/react-components/react-tree/stories/TreeItem/TreeItemDefault.stories.tsx create mode 100644 packages/react-components/react-tree/stories/TreeItem/TreeItemDescription.md rename packages/react-components/react-tree/stories/{Tree/TreeExpandCollapseIconOnly.md => TreeItem/TreeItemExpandCollapseIconOnly.md} (100%) rename packages/react-components/react-tree/stories/{Tree/TreeExpandCollapseIconOnly.stories.tsx => TreeItem/TreeItemExpandCollapseIconOnly.stories.tsx} (96%) rename packages/react-components/react-tree/stories/{Tree/TreeExpandIcon.md => TreeItem/TreeItemExpandIcon.md} (100%) rename packages/react-components/react-tree/stories/{Tree/TreeExpandIcon.stories.tsx => TreeItem/TreeItemExpandIcon.stories.tsx} (97%) rename packages/react-components/react-tree/stories/{Tree/TreeIconAfter.stories.tsx => TreeItem/TreeItemIconAfter.stories.tsx} (100%) rename packages/react-components/react-tree/stories/{Tree/TreeIconBefore.md => TreeItem/TreeItemIconBefore.md} (100%) rename packages/react-components/react-tree/stories/{Tree/TreeIconBefore.stories.tsx => TreeItem/TreeItemIconBefore.stories.tsx} (96%) rename packages/react-components/react-tree/stories/{Tree/TreeWithInlineStyle.md => TreeItem/TreeItemWithInlineStyle.md} (100%) rename packages/react-components/react-tree/stories/{Tree/TreeWithInlineStyle.stories.tsx => TreeItem/TreeItemWithInlineStyle.stories.tsx} (96%) create mode 100644 packages/react-components/react-tree/stories/TreeItem/index.stories.tsx delete mode 100644 packages/react-components/react-tree/stories/TreeItemPersonaLayout/index.stories.tsx diff --git a/packages/react-components/react-tree/stories/Tree/TreeLayout.md b/packages/react-components/react-tree/stories/Layouts/TreeItemLayout.md similarity index 100% rename from packages/react-components/react-tree/stories/Tree/TreeLayout.md rename to packages/react-components/react-tree/stories/Layouts/TreeItemLayout.md diff --git a/packages/react-components/react-tree/stories/Tree/TreeLayout.stories.tsx b/packages/react-components/react-tree/stories/Layouts/TreeItemLayout.stories.tsx similarity index 98% rename from packages/react-components/react-tree/stories/Tree/TreeLayout.stories.tsx rename to packages/react-components/react-tree/stories/Layouts/TreeItemLayout.stories.tsx index 4421c7f1c7fcd4..a9fb2b1c39b43d 100644 --- a/packages/react-components/react-tree/stories/Tree/TreeLayout.stories.tsx +++ b/packages/react-components/react-tree/stories/Layouts/TreeItemLayout.stories.tsx @@ -10,7 +10,7 @@ import { SquareMultiple20Regular, } from '@fluentui/react-icons'; import { Button, CounterBadge, Menu, MenuItem, MenuList, MenuPopover, MenuTrigger } from '@fluentui/react-components'; -import story from './TreeLayout.md'; +import story from './TreeItemLayout.md'; const iconStyleProps: FluentIconsProps = { primaryFill: 'red', diff --git a/packages/react-components/react-tree/stories/Layouts/TreeItemLayoutAside.md b/packages/react-components/react-tree/stories/Layouts/TreeItemLayoutAside.md new file mode 100644 index 00000000000000..993f85a456f07b --- /dev/null +++ b/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. diff --git a/packages/react-components/react-tree/stories/Tree/TreeAside.stories.tsx b/packages/react-components/react-tree/stories/Layouts/TreeItemLayoutAside.stories.tsx similarity index 98% rename from packages/react-components/react-tree/stories/Tree/TreeAside.stories.tsx rename to packages/react-components/react-tree/stories/Layouts/TreeItemLayoutAside.stories.tsx index 08991de00650f9..6d78eb13092406 100644 --- a/packages/react-components/react-tree/stories/Tree/TreeAside.stories.tsx +++ b/packages/react-components/react-tree/stories/Layouts/TreeItemLayoutAside.stories.tsx @@ -2,7 +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 './TreeAside.md'; +import story from './TreeItemLayoutAside.md'; const iconStyleProps: FluentIconsProps = { primaryFill: 'red', diff --git a/packages/react-components/react-tree/stories/Layouts/TreeItemLayoutDefault.stories.tsx b/packages/react-components/react-tree/stories/Layouts/TreeItemLayoutDefault.stories.tsx new file mode 100644 index 00000000000000..c06f819cbf1773 --- /dev/null +++ b/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 ( + + + level 1, item 1 + + + level 2, item 1 + + + level 2, item 2 + + + level 2, item 3 + + + + + level 1, item 2 + + + level 2, item 1 + + + level 3, item 1 + + + + + + + ); +}; diff --git a/packages/react-components/react-tree/stories/TreeItemPersonaLayout/TreePersonaLayout.md b/packages/react-components/react-tree/stories/Layouts/TreeItemPersonaLayout.md similarity index 100% rename from packages/react-components/react-tree/stories/TreeItemPersonaLayout/TreePersonaLayout.md rename to packages/react-components/react-tree/stories/Layouts/TreeItemPersonaLayout.md diff --git a/packages/react-components/react-tree/stories/TreeItemPersonaLayout/TreePersonaLayout.stories.tsx b/packages/react-components/react-tree/stories/Layouts/TreeItemPersonaLayout.stories.tsx similarity index 98% rename from packages/react-components/react-tree/stories/TreeItemPersonaLayout/TreePersonaLayout.stories.tsx rename to packages/react-components/react-tree/stories/Layouts/TreeItemPersonaLayout.stories.tsx index 1b72ba67dd50a2..091de57556bdf4 100644 --- a/packages/react-components/react-tree/stories/TreeItemPersonaLayout/TreePersonaLayout.stories.tsx +++ b/packages/react-components/react-tree/stories/Layouts/TreeItemPersonaLayout.stories.tsx @@ -14,7 +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 './TreePersonaLayout.md'; +import story from './TreeItemPersonaLayout.md'; const useBadgeStyles = makeStyles({ base: { diff --git a/packages/react-components/react-tree/stories/TreeItemPersonaLayout/TreeItemPersonaLayoutDefault.stories.tsx b/packages/react-components/react-tree/stories/Layouts/TreeItemPersonaLayoutDefault.stories.tsx similarity index 95% rename from packages/react-components/react-tree/stories/TreeItemPersonaLayout/TreeItemPersonaLayoutDefault.stories.tsx rename to packages/react-components/react-tree/stories/Layouts/TreeItemPersonaLayoutDefault.stories.tsx index 8f4ded4408824d..c5e6ebf8d650e5 100644 --- a/packages/react-components/react-tree/stories/TreeItemPersonaLayout/TreeItemPersonaLayoutDefault.stories.tsx +++ b/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 ( diff --git a/packages/react-components/react-tree/stories/TreeItemPersonaLayout/TreeItemPersonaLayoutDescription.md b/packages/react-components/react-tree/stories/Layouts/TreeItemPersonaLayoutDescription.md similarity index 100% rename from packages/react-components/react-tree/stories/TreeItemPersonaLayout/TreeItemPersonaLayoutDescription.md rename to packages/react-components/react-tree/stories/Layouts/TreeItemPersonaLayoutDescription.md diff --git a/packages/react-components/react-tree/stories/TreeItemPersonaLayout/TreeItemPersonaLayoutMedia.md b/packages/react-components/react-tree/stories/Layouts/TreeItemPersonaLayoutMedia.md similarity index 100% rename from packages/react-components/react-tree/stories/TreeItemPersonaLayout/TreeItemPersonaLayoutMedia.md rename to packages/react-components/react-tree/stories/Layouts/TreeItemPersonaLayoutMedia.md diff --git a/packages/react-components/react-tree/stories/TreeItemPersonaLayout/TreeItemPersonaLayoutMedia.stories.tsx b/packages/react-components/react-tree/stories/Layouts/TreeItemPersonaLayoutMedia.stories.tsx similarity index 100% rename from packages/react-components/react-tree/stories/TreeItemPersonaLayout/TreeItemPersonaLayoutMedia.stories.tsx rename to packages/react-components/react-tree/stories/Layouts/TreeItemPersonaLayoutMedia.stories.tsx diff --git a/packages/react-components/react-tree/stories/TreeItemPersonaLayout/TreeItemPersonaLayoutReadUnread.md b/packages/react-components/react-tree/stories/Layouts/TreeItemPersonaLayoutReadUnread.md similarity index 100% rename from packages/react-components/react-tree/stories/TreeItemPersonaLayout/TreeItemPersonaLayoutReadUnread.md rename to packages/react-components/react-tree/stories/Layouts/TreeItemPersonaLayoutReadUnread.md diff --git a/packages/react-components/react-tree/stories/TreeItemPersonaLayout/TreeItemPersonaLayoutReadUnread.stories.tsx b/packages/react-components/react-tree/stories/Layouts/TreeItemPersonaLayoutReadUnread.stories.tsx similarity index 100% rename from packages/react-components/react-tree/stories/TreeItemPersonaLayout/TreeItemPersonaLayoutReadUnread.stories.tsx rename to packages/react-components/react-tree/stories/Layouts/TreeItemPersonaLayoutReadUnread.stories.tsx diff --git a/packages/react-components/react-tree/stories/TreeItemPersonaLayout/TreeItemPersonaLayoutWithDescription.md b/packages/react-components/react-tree/stories/Layouts/TreeItemPersonaLayoutWithDescription.md similarity index 100% rename from packages/react-components/react-tree/stories/TreeItemPersonaLayout/TreeItemPersonaLayoutWithDescription.md rename to packages/react-components/react-tree/stories/Layouts/TreeItemPersonaLayoutWithDescription.md diff --git a/packages/react-components/react-tree/stories/TreeItemPersonaLayout/TreeItemPersonaLayoutWithDescription.stories.tsx b/packages/react-components/react-tree/stories/Layouts/TreeItemPersonaLayoutWithDescription.stories.tsx similarity index 100% rename from packages/react-components/react-tree/stories/TreeItemPersonaLayout/TreeItemPersonaLayoutWithDescription.stories.tsx rename to packages/react-components/react-tree/stories/Layouts/TreeItemPersonaLayoutWithDescription.stories.tsx diff --git a/packages/react-components/react-tree/stories/Layouts/description.md b/packages/react-components/react-tree/stories/Layouts/description.md new file mode 100644 index 00000000000000..84d5122c05da1c --- /dev/null +++ b/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. diff --git a/packages/react-components/react-tree/stories/Layouts/index.stories.tsx b/packages/react-components/react-tree/stories/Layouts/index.stories.tsx new file mode 100644 index 00000000000000..1e6036662837c6 --- /dev/null +++ b/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'), + }, + }, + }, +}; diff --git a/packages/react-components/react-tree/stories/Tree/TreeAside.md b/packages/react-components/react-tree/stories/Tree/TreeAside.md deleted file mode 100644 index 495cf8d10096b0..00000000000000 --- a/packages/react-components/react-tree/stories/Tree/TreeAside.md +++ /dev/null @@ -1 +0,0 @@ -The `Tree` component allows for an `aside` prop to be added to individual `TreeItemLayout` or `TreeItemPersonaLayout` 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. diff --git a/packages/react-components/react-tree/stories/Tree/index.stories.tsx b/packages/react-components/react-tree/stories/Tree/index.stories.tsx index 0ff805dd3ed327..efe1a3db6fb06c 100644 --- a/packages/react-components/react-tree/stories/Tree/index.stories.tsx +++ b/packages/react-components/react-tree/stories/Tree/index.stories.tsx @@ -1,27 +1,20 @@ -import { Tree } from '@fluentui/react-tree'; +import { Tree, TreeItem, TreeItemLayout, TreeItemPersonaLayout } from '@fluentui/react-tree'; import descriptionMd from './TreeDescription.md'; import bestPracticesMd from './TreeBestPractices.md'; export { Default } from './TreeDefault.stories'; export { DefaultOpenTrees } from './TreeDefaultOpenTrees.stories'; -export { ExpandIcon } from './TreeExpandIcon.stories'; -export { IconBefore } from './TreeIconBefore.stories'; -export { IconAfter } from './TreeIconAfter.stories'; -export { Actions } from './TreeActions.stories'; -export { Aside } from './TreeAside.stories'; export { Appearance } from './TreeAppearance.stories'; export { Size } from './TreeSize.stories'; -export { Layout } from './TreeLayout.stories'; export { OpenItemsControlled } from './TreeControllingOpenAndClose.stories'; -export { ExpandCollapseIconOnly } from './TreeExpandCollapseIconOnly.stories'; export { FlattenTree as flattenTree } from './flattenTree.stories'; export { Virtualization } from './Virtualization.stories'; -export { WithInlineStyle } from './TreeWithInlineStyle.stories'; export default { - title: 'Preview Components/Tree', + title: 'Preview Components/Tree/Tree', component: Tree, + subcomponents: { TreeItem, TreeItemLayout, TreeItemPersonaLayout }, parameters: { docs: { description: { diff --git a/packages/react-components/react-tree/stories/Tree/TreeActions.md b/packages/react-components/react-tree/stories/TreeItem/TreeItemActions.md similarity index 100% rename from packages/react-components/react-tree/stories/Tree/TreeActions.md rename to packages/react-components/react-tree/stories/TreeItem/TreeItemActions.md diff --git a/packages/react-components/react-tree/stories/Tree/TreeActions.stories.tsx b/packages/react-components/react-tree/stories/TreeItem/TreeItemActions.stories.tsx similarity index 98% rename from packages/react-components/react-tree/stories/Tree/TreeActions.stories.tsx rename to packages/react-components/react-tree/stories/TreeItem/TreeItemActions.stories.tsx index 91a61b0a0db05e..f536e9418ae5a7 100644 --- a/packages/react-components/react-tree/stories/Tree/TreeActions.stories.tsx +++ b/packages/react-components/react-tree/stories/TreeItem/TreeItemActions.stories.tsx @@ -2,7 +2,7 @@ import * as React from 'react'; import { Tree, TreeItem, TreeItemLayout } from '@fluentui/react-tree'; import { Edit20Regular, MoreHorizontal20Regular } from '@fluentui/react-icons'; import { Button, Menu, MenuItem, MenuList, MenuPopover, MenuTrigger } from '@fluentui/react-components'; -import story from './TreeActions.md'; +import story from './TreeItemActions.md'; const RenderActions = () => { return ( diff --git a/packages/react-components/react-tree/stories/TreeItem/TreeItemDefault.stories.tsx b/packages/react-components/react-tree/stories/TreeItem/TreeItemDefault.stories.tsx new file mode 100644 index 00000000000000..46a49dac5010e3 --- /dev/null +++ b/packages/react-components/react-tree/stories/TreeItem/TreeItemDefault.stories.tsx @@ -0,0 +1,36 @@ +import * as React from 'react'; +import { Tree, TreeItem, TreeItemLayout } from '@fluentui/react-tree'; + +export const Default = () => { + return ( + + + level 1, item 1 + + + level 2, item 1 + + + level 2, item 2 + + + level 2, item 3 + + + + + level 1, item 2 + + + level 2, item 1 + + + level 3, item 1 + + + + + + + ); +}; diff --git a/packages/react-components/react-tree/stories/TreeItem/TreeItemDescription.md b/packages/react-components/react-tree/stories/TreeItem/TreeItemDescription.md new file mode 100644 index 00000000000000..0dc57ec18b0f55 --- /dev/null +++ b/packages/react-components/react-tree/stories/TreeItem/TreeItemDescription.md @@ -0,0 +1,3 @@ +The `TreeItem` component represents a single item in a tree. It can contain child items in the form of another `Tree` component or standalone `TreeItem`. 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 child items, an expand/collapse control is displayed, allowing the user to show or hide the children. diff --git a/packages/react-components/react-tree/stories/Tree/TreeExpandCollapseIconOnly.md b/packages/react-components/react-tree/stories/TreeItem/TreeItemExpandCollapseIconOnly.md similarity index 100% rename from packages/react-components/react-tree/stories/Tree/TreeExpandCollapseIconOnly.md rename to packages/react-components/react-tree/stories/TreeItem/TreeItemExpandCollapseIconOnly.md diff --git a/packages/react-components/react-tree/stories/Tree/TreeExpandCollapseIconOnly.stories.tsx b/packages/react-components/react-tree/stories/TreeItem/TreeItemExpandCollapseIconOnly.stories.tsx similarity index 96% rename from packages/react-components/react-tree/stories/Tree/TreeExpandCollapseIconOnly.stories.tsx rename to packages/react-components/react-tree/stories/TreeItem/TreeItemExpandCollapseIconOnly.stories.tsx index 680934dc03e9a7..e03f1cd330e98f 100644 --- a/packages/react-components/react-tree/stories/Tree/TreeExpandCollapseIconOnly.stories.tsx +++ b/packages/react-components/react-tree/stories/TreeItem/TreeItemExpandCollapseIconOnly.stories.tsx @@ -1,7 +1,7 @@ import * as React from 'react'; import { Tree, TreeItem, TreeItemLayout } from '@fluentui/react-tree'; import { TreeOpenChangeData, TreeOpenChangeEvent } from '../../src/components/Tree/Tree.types'; -import story from './TreeExpandCollapseIconOnly.md'; +import story from './TreeItemExpandCollapseIconOnly.md'; export const ExpandCollapseIconOnly = () => { const onOpenChange = (event: TreeOpenChangeEvent, data: TreeOpenChangeData) => { diff --git a/packages/react-components/react-tree/stories/Tree/TreeExpandIcon.md b/packages/react-components/react-tree/stories/TreeItem/TreeItemExpandIcon.md similarity index 100% rename from packages/react-components/react-tree/stories/Tree/TreeExpandIcon.md rename to packages/react-components/react-tree/stories/TreeItem/TreeItemExpandIcon.md diff --git a/packages/react-components/react-tree/stories/Tree/TreeExpandIcon.stories.tsx b/packages/react-components/react-tree/stories/TreeItem/TreeItemExpandIcon.stories.tsx similarity index 97% rename from packages/react-components/react-tree/stories/Tree/TreeExpandIcon.stories.tsx rename to packages/react-components/react-tree/stories/TreeItem/TreeItemExpandIcon.stories.tsx index 1982839903d8b4..49acbe0d497aec 100644 --- a/packages/react-components/react-tree/stories/Tree/TreeExpandIcon.stories.tsx +++ b/packages/react-components/react-tree/stories/TreeItem/TreeItemExpandIcon.stories.tsx @@ -2,7 +2,7 @@ import * as React from 'react'; import { Tree, TreeItem, TreeItemLayout } from '@fluentui/react-tree'; import { Add12Regular, Subtract12Regular } from '@fluentui/react-icons'; import { TreeOpenChangeData, TreeOpenChangeEvent } from '../../src/Tree'; -import story from './TreeExpandIcon.md'; +import story from './TreeItemExpandIcon.md'; export const ExpandIcon = () => { const [openItems, setOpenItems] = React.useState([]); diff --git a/packages/react-components/react-tree/stories/Tree/TreeIconAfter.stories.tsx b/packages/react-components/react-tree/stories/TreeItem/TreeItemIconAfter.stories.tsx similarity index 100% rename from packages/react-components/react-tree/stories/Tree/TreeIconAfter.stories.tsx rename to packages/react-components/react-tree/stories/TreeItem/TreeItemIconAfter.stories.tsx diff --git a/packages/react-components/react-tree/stories/Tree/TreeIconBefore.md b/packages/react-components/react-tree/stories/TreeItem/TreeItemIconBefore.md similarity index 100% rename from packages/react-components/react-tree/stories/Tree/TreeIconBefore.md rename to packages/react-components/react-tree/stories/TreeItem/TreeItemIconBefore.md diff --git a/packages/react-components/react-tree/stories/Tree/TreeIconBefore.stories.tsx b/packages/react-components/react-tree/stories/TreeItem/TreeItemIconBefore.stories.tsx similarity index 96% rename from packages/react-components/react-tree/stories/Tree/TreeIconBefore.stories.tsx rename to packages/react-components/react-tree/stories/TreeItem/TreeItemIconBefore.stories.tsx index 77d8cacbd5b3c5..111fc58d95cc7c 100644 --- a/packages/react-components/react-tree/stories/Tree/TreeIconBefore.stories.tsx +++ b/packages/react-components/react-tree/stories/TreeItem/TreeItemIconBefore.stories.tsx @@ -1,7 +1,7 @@ import * as React from 'react'; import { Tree, TreeItem, TreeItemLayout } from '@fluentui/react-tree'; import { CheckboxChecked20Filled, CheckboxUnchecked20Filled } from '@fluentui/react-icons'; -import story from './TreeIconBefore.md'; +import story from './TreeItemIconBefore.md'; export const IconBefore = () => { return ( diff --git a/packages/react-components/react-tree/stories/Tree/TreeWithInlineStyle.md b/packages/react-components/react-tree/stories/TreeItem/TreeItemWithInlineStyle.md similarity index 100% rename from packages/react-components/react-tree/stories/Tree/TreeWithInlineStyle.md rename to packages/react-components/react-tree/stories/TreeItem/TreeItemWithInlineStyle.md diff --git a/packages/react-components/react-tree/stories/Tree/TreeWithInlineStyle.stories.tsx b/packages/react-components/react-tree/stories/TreeItem/TreeItemWithInlineStyle.stories.tsx similarity index 96% rename from packages/react-components/react-tree/stories/Tree/TreeWithInlineStyle.stories.tsx rename to packages/react-components/react-tree/stories/TreeItem/TreeItemWithInlineStyle.stories.tsx index 031834cec1035f..b8535f72d223fe 100644 --- a/packages/react-components/react-tree/stories/Tree/TreeWithInlineStyle.stories.tsx +++ b/packages/react-components/react-tree/stories/TreeItem/TreeItemWithInlineStyle.stories.tsx @@ -7,7 +7,7 @@ import { TreeItemProps, useTreeContext_unstable, } from '@fluentui/react-tree'; -import story from './TreeWithInlineStyle.md'; +import story from './TreeItemWithInlineStyle.md'; const TreeItem = (props: TreeItemProps) => { const level = useTreeContext_unstable(ctx => ctx.level); diff --git a/packages/react-components/react-tree/stories/TreeItem/index.stories.tsx b/packages/react-components/react-tree/stories/TreeItem/index.stories.tsx new file mode 100644 index 00000000000000..07c739a079abeb --- /dev/null +++ b/packages/react-components/react-tree/stories/TreeItem/index.stories.tsx @@ -0,0 +1,23 @@ +import { TreeItem, TreeItemLayout, TreeItemPersonaLayout } from '@fluentui/react-tree'; +import descriptionMd from './TreeItemDescription.md'; + +export { Default } from './TreeItemDefault.stories'; +export { ExpandCollapseIconOnly } from './TreeItemExpandCollapseIconOnly.stories'; +export { ExpandIcon } from './TreeItemExpandIcon.stories'; +export { IconBefore } from './TreeItemIconBefore.stories'; +export { IconAfter } from './TreeItemIconAfter.stories'; +export { Actions } from './TreeItemActions.stories'; +export { WithInlineStyle } from './TreeItemWithInlineStyle.stories'; + +export default { + title: 'Preview Components/Tree/TreeItem', + component: TreeItem, + subcomponents: { TreeItemLayout, TreeItemPersonaLayout }, + parameters: { + docs: { + description: { + component: [descriptionMd].join('\n'), + }, + }, + }, +}; diff --git a/packages/react-components/react-tree/stories/TreeItemPersonaLayout/index.stories.tsx b/packages/react-components/react-tree/stories/TreeItemPersonaLayout/index.stories.tsx deleted file mode 100644 index 1694ff66f88245..00000000000000 --- a/packages/react-components/react-tree/stories/TreeItemPersonaLayout/index.stories.tsx +++ /dev/null @@ -1,19 +0,0 @@ -import { TreeItemPersonaLayout } from '@fluentui/react-tree'; -import descriptionMd from './TreeItemPersonaLayoutDescription.md'; -export { Default } from './TreeItemPersonaLayoutDefault.stories'; -export { Media } from './TreeItemPersonaLayoutMedia.stories'; -export { WithDescription } from './TreeItemPersonaLayoutWithDescription.stories'; -export { ReadUnread } from './TreeItemPersonaLayoutReadUnread.stories'; -export { TreePersonaLayout } from './TreePersonaLayout.stories'; - -export default { - title: 'Preview Components/Tree/PersonaTreeItem', - component: TreeItemPersonaLayout, - parameters: { - docs: { - description: { - component: [descriptionMd].join('\n'), - }, - }, - }, -}; From ee064857e8bc05c9dde66a7b916ab1537637ea18 Mon Sep 17 00:00:00 2001 From: Petr Duda Date: Wed, 22 Mar 2023 11:07:33 +0100 Subject: [PATCH 26/34] Do's --- .../stories/Tree/TreeBestPractices.md | 34 +++++-------------- 1 file changed, 9 insertions(+), 25 deletions(-) diff --git a/packages/react-components/react-tree/stories/Tree/TreeBestPractices.md b/packages/react-components/react-tree/stories/Tree/TreeBestPractices.md index 94960d06967cd7..47b6793d0c69ba 100644 --- a/packages/react-components/react-tree/stories/Tree/TreeBestPractices.md +++ b/packages/react-components/react-tree/stories/Tree/TreeBestPractices.md @@ -1,32 +1,16 @@ - + From f7e6c11c3de7a086f4635ce29928bcf9654e4f12 Mon Sep 17 00:00:00 2001 From: Petr Duda Date: Wed, 22 Mar 2023 11:12:07 +0100 Subject: [PATCH 27/34] treeitem --- .../react-tree/src/components/TreeItem/TreeItem.tsx | 1 - 1 file changed, 1 deletion(-) diff --git a/packages/react-components/react-tree/src/components/TreeItem/TreeItem.tsx b/packages/react-components/react-tree/src/components/TreeItem/TreeItem.tsx index 2acdd0908ff19a..3a3823484da383 100644 --- a/packages/react-components/react-tree/src/components/TreeItem/TreeItem.tsx +++ b/packages/react-components/react-tree/src/components/TreeItem/TreeItem.tsx @@ -14,7 +14,6 @@ import { useTreeItemContextValues_unstable } from './useTreeItemContextValues'; * * When a TreeItem has child items, an expand/collapse control is displayed, * allowing the user to show or hide the children. - * This provides a convenient way to navigate hierarchical data, such as a file system or a category tree. */ export const TreeItem: ForwardRefComponent = React.forwardRef((props, ref) => { const state = useTreeItem_unstable(props, ref); From 98d3616e4c68c13ab35138c37e3b6c1179c98831 Mon Sep 17 00:00:00 2001 From: Petr Duda Date: Wed, 22 Mar 2023 11:37:37 +0100 Subject: [PATCH 28/34] change --- ...ui-react-tree-7b614498-e79f-460b-a3a4-22ba4d9a2bea.json | 7 +++++++ 1 file changed, 7 insertions(+) create mode 100644 change/@fluentui-react-tree-7b614498-e79f-460b-a3a4-22ba4d9a2bea.json diff --git a/change/@fluentui-react-tree-7b614498-e79f-460b-a3a4-22ba4d9a2bea.json b/change/@fluentui-react-tree-7b614498-e79f-460b-a3a4-22ba4d9a2bea.json new file mode 100644 index 00000000000000..4bf73a21ad65c3 --- /dev/null +++ b/change/@fluentui-react-tree-7b614498-e79f-460b-a3a4-22ba4d9a2bea.json @@ -0,0 +1,7 @@ +{ + "type": "none", + "comment": "tree stories and doc update", + "packageName": "@fluentui/react-tree", + "email": "petrduda@microsoft.com", + "dependentChangeType": "none" +} From 637bff2abb2bc5a1bb5a7328388fb14416f63a1c Mon Sep 17 00:00:00 2001 From: Petr Duda Date: Wed, 22 Mar 2023 14:20:07 +0100 Subject: [PATCH 29/34] Update change/@fluentui-react-tree-7b614498-e79f-460b-a3a4-22ba4d9a2bea.json Co-authored-by: Bernardo Sunderhus --- ...entui-react-tree-7b614498-e79f-460b-a3a4-22ba4d9a2bea.json | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/change/@fluentui-react-tree-7b614498-e79f-460b-a3a4-22ba4d9a2bea.json b/change/@fluentui-react-tree-7b614498-e79f-460b-a3a4-22ba4d9a2bea.json index 4bf73a21ad65c3..b59c3335f4543f 100644 --- a/change/@fluentui-react-tree-7b614498-e79f-460b-a3a4-22ba4d9a2bea.json +++ b/change/@fluentui-react-tree-7b614498-e79f-460b-a3a4-22ba4d9a2bea.json @@ -1,7 +1,7 @@ { - "type": "none", + "type": "prerelease", "comment": "tree stories and doc update", "packageName": "@fluentui/react-tree", "email": "petrduda@microsoft.com", - "dependentChangeType": "none" + "dependentChangeType": "patch" } From 762da4bb9b107ef25ae4d086cfdf7c6f8e283e12 Mon Sep 17 00:00:00 2001 From: Petr Duda Date: Wed, 22 Mar 2023 15:35:22 +0100 Subject: [PATCH 30/34] Update packages/react-components/react-tree/stories/Tree/Virtualization.md Co-authored-by: Bernardo Sunderhus --- .../react-components/react-tree/stories/Tree/Virtualization.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/packages/react-components/react-tree/stories/Tree/Virtualization.md b/packages/react-components/react-tree/stories/Tree/Virtualization.md index e9016b28685139..e2e4f73934d7bb 100644 --- a/packages/react-components/react-tree/stories/Tree/Virtualization.md +++ b/packages/react-components/react-tree/stories/Tree/Virtualization.md @@ -1,3 +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 the overall performance of the tree. -To achieve this, one can create a `flattened` version of the tree structure that can be easily consumed by a windowing library. This library renders only the items that are currently visible on the screen, which reduces the amount of memory required to run the application. +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. From e3427ee7bcfe2ebef21df744f2cc34d3801f906f Mon Sep 17 00:00:00 2001 From: Petr Duda Date: Wed, 22 Mar 2023 15:36:36 +0100 Subject: [PATCH 31/34] Update packages/react-components/react-tree/stories/Tree/Virtualization.md Co-authored-by: Bernardo Sunderhus --- .../react-components/react-tree/stories/Tree/Virtualization.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/packages/react-components/react-tree/stories/Tree/Virtualization.md b/packages/react-components/react-tree/stories/Tree/Virtualization.md index e2e4f73934d7bb..4545d50951a48e 100644 --- a/packages/react-components/react-tree/stories/Tree/Virtualization.md +++ b/packages/react-components/react-tree/stories/Tree/Virtualization.md @@ -1,3 +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 the overall performance of the tree. +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. From bcd2260e69e6939ea89a7ee138323e1b12d11883 Mon Sep 17 00:00:00 2001 From: Petr Duda Date: Wed, 22 Mar 2023 15:43:48 +0100 Subject: [PATCH 32/34] Update packages/react-components/react-tree/stories/Tree/TreeBestPractices.md Co-authored-by: Bernardo Sunderhus --- .../react-tree/stories/Tree/TreeBestPractices.md | 1 - 1 file changed, 1 deletion(-) diff --git a/packages/react-components/react-tree/stories/Tree/TreeBestPractices.md b/packages/react-components/react-tree/stories/Tree/TreeBestPractices.md index 47b6793d0c69ba..73b5e33afe4a73 100644 --- a/packages/react-components/react-tree/stories/Tree/TreeBestPractices.md +++ b/packages/react-components/react-tree/stories/Tree/TreeBestPractices.md @@ -7,7 +7,6 @@ - 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. -- Allow users to expand and collapse nodes to focus on specific parts of the hierarchy. - 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. - Consider using virtualization to improve performance for large tree structures. From cf251c13d953f5ca4190a300eb778f605e8bf47d Mon Sep 17 00:00:00 2001 From: Petr Duda Date: Wed, 22 Mar 2023 15:44:11 +0100 Subject: [PATCH 33/34] Update packages/react-components/react-tree/stories/Tree/TreeDescription.md Co-authored-by: Bernardo Sunderhus --- .../react-tree/stories/Tree/TreeDescription.md | 13 +++++++++++++ 1 file changed, 13 insertions(+) diff --git a/packages/react-components/react-tree/stories/Tree/TreeDescription.md b/packages/react-components/react-tree/stories/Tree/TreeDescription.md index 7ceb91d972df25..0aac5c7d2efb75 100644 --- a/packages/react-components/react-tree/stories/Tree/TreeDescription.md +++ b/packages/react-components/react-tree/stories/Tree/TreeDescription.md @@ -1 +1,14 @@ `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. + + + +> **⚠️ Preview components are considered unstable:** +> +> ```jsx +> +> import { Tree } from '@fluentui/react-components/unstable'; +> +> ``` +> +> - Features and APIs may change before final release +> - Please contact us if you intend to use this in your product From 1e0c25f846339a8595f510eb08ab1068c97bbf9e Mon Sep 17 00:00:00 2001 From: Petr Duda Date: Wed, 22 Mar 2023 16:04:40 +0100 Subject: [PATCH 34/34] fix treeitem description --- .../react-tree/src/components/TreeItem/TreeItem.tsx | 9 ++++++--- .../react-tree/stories/Tree/TreeBestPractices.md | 1 - 2 files changed, 6 insertions(+), 4 deletions(-) diff --git a/packages/react-components/react-tree/src/components/TreeItem/TreeItem.tsx b/packages/react-components/react-tree/src/components/TreeItem/TreeItem.tsx index 3a3823484da383..a20be498e2d237 100644 --- a/packages/react-components/react-tree/src/components/TreeItem/TreeItem.tsx +++ b/packages/react-components/react-tree/src/components/TreeItem/TreeItem.tsx @@ -8,11 +8,14 @@ import { useTreeItemContextValues_unstable } from './useTreeItemContextValues'; /** * The `TreeItem` component represents a single item in a tree. - * It can contain child items in the form of another Tree component or standalone TreeItem. - * The content and layout of a TreeItem can be defined using the `TreeItemLayout` or `TreeItemPersonaLayout` component, + * 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 child items, an expand/collapse control is displayed, + * 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 = React.forwardRef((props, ref) => { diff --git a/packages/react-components/react-tree/stories/Tree/TreeBestPractices.md b/packages/react-components/react-tree/stories/Tree/TreeBestPractices.md index 73b5e33afe4a73..be393f97b2ceae 100644 --- a/packages/react-components/react-tree/stories/Tree/TreeBestPractices.md +++ b/packages/react-components/react-tree/stories/Tree/TreeBestPractices.md @@ -9,7 +9,6 @@ - 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. -- Consider using virtualization to improve performance for large tree structures. - Use the `aria-label` attribute on the root of the Tree component to provide an accessible name for the tree.