feat(react-tree): adds active state to TreeItem

Author: bsunderhus

change/@fluentui-react-tree-2c6bbc6d-a684-40d1-9e23-b745b3027693.json

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

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

@@ -122,6 +122,7 @@ export const TreeItem: React_2.ForwardRefExoticComponent<Omit<Partial<TreeItemSl
 } & {
     style?: TreeItemCSSProperties | undefined;
 }, "ref"> & {
+    active?: boolean | undefined;
     value?: string | undefined;
     leaf?: boolean | undefined;
 } & React_2.RefAttributes<HTMLDivElement>> & (<Value = string>(props: TreeItemProps<Value>) => JSX.Element);
@@ -178,6 +179,7 @@ export type TreeItemPersonaLayoutState = ComponentState<TreeItemPersonaLayoutSlo
 
 // @public
 export type TreeItemProps<Value = string> = ComponentProps<Partial<TreeItemSlots>> & {
+    active?: boolean;
     value?: Value;
     leaf?: boolean;
 };
@@ -202,7 +204,7 @@ export type TreeItemState = ComponentState<TreeItemSlots> & {
     isLeaf: boolean;
     level: number;
     buttonSize: 'small';
-    isActionsVisible: boolean;
+    active: boolean;
 };
 
 // @public (undocumented)

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

@@ -31,6 +31,10 @@ export type TreeItemContextValues = {
  * TreeItem Props
  */
 export type TreeItemProps<Value = string> = ComponentProps<Partial<TreeItemSlots>> & {
+  /**
+   * a flag that allows control of the visibility of `actions` slot
+   */
+  active?: boolean;
   value?: Value;
   /**
    * If a TreeItem is a leaf, it'll not present the `expandIcon` slot by default.
@@ -51,5 +55,5 @@ export type TreeItemState = ComponentState<TreeItemSlots> & {
    * By design, a button included on the actions slot should be small
    */
   buttonSize: 'small';
-  isActionsVisible: boolean;
+  active: boolean;
 };

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

@@ -1,5 +1,11 @@
 import * as React from 'react';
-import { getNativeElementProps, isResolvedShorthand, resolveShorthand, useId } from '@fluentui/react-utilities';
+import {
+  getNativeElementProps,
+  isResolvedShorthand,
+  resolveShorthand,
+  useControllableState,
+  useId,
+} from '@fluentui/react-utilities';
 import { ChevronRight12Regular } from '@fluentui/react-icons';
 import { useFluent_unstable } from '@fluentui/react-shared-contexts';
 import { useEventCallback } from '@fluentui/react-utilities';
@@ -47,6 +53,8 @@ export function useTreeItem_unstable<Value = string>(
   const requestOpenChange = useTreeContext_unstable(ctx => ctx.requestOpenChange);
   const requestNavigation = useTreeContext_unstable(ctx => ctx.requestNavigation);
 
+  const [active, setActive] = useControllableState({ state: props.active, initialState: false });
+
   const isBranch = !isLeaf;
 
   const open = useTreeContext_unstable(ctx => isBranch && ctx.openItems.has(value));
@@ -148,17 +156,16 @@ export function useTreeItem_unstable<Value = string>(
     }
   });
 
-  const [isActionsVisible, setActionsVisible] = React.useState(false);
   const showActions = useEventCallback((event: React.SyntheticEvent) => {
     const isEventFromSubtree = subtreeRef.current && elementContains(subtreeRef.current, event.target as Node);
     if (!isEventFromSubtree) {
-      setActionsVisible(true);
+      setActive(true);
     }
   });
   const hideActions = useEventCallback((event: React.SyntheticEvent) => {
     const isEventFromSubtree = subtreeRef.current && elementContains(subtreeRef.current, event.target as Node);
     if (!isEventFromSubtree) {
-      setActionsVisible(false);
+      setActive(false);
     }
   });
 
@@ -167,21 +174,22 @@ export function useTreeItem_unstable<Value = string>(
   React.useEffect(() => {
     if (actionsRef.current) {
       const handleFocusOut = (event: FocusEvent) => {
-        setActionsVisible(elementContains(actionsRef.current, event.relatedTarget as Node));
+        setActive(elementContains(actionsRef.current, event.relatedTarget as Node));
       };
       targetDocument?.addEventListener('focusout', handleFocusOut, { passive: true });
       return () => {
         targetDocument?.removeEventListener('focusout', handleFocusOut);
       };
     }
+    // eslint-disable-next-line react-hooks/exhaustive-deps
   }, [targetDocument]);
 
   return {
     isLeaf,
     open,
     level,
     buttonSize: 'small',
-    isActionsVisible: actions ? isActionsVisible : false,
+    active: actions ? active : false,
     components: {
       content: 'div',
       root: 'div',

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

@@ -4,11 +4,11 @@ import type { TreeItemContextValue } from '../../contexts';
 import type { TreeItemContextValues, TreeItemState } from './TreeItem.types';
 
 export function useTreeItemContextValues_unstable(
-  state: Pick<TreeItemState, 'buttonSize' | 'isActionsVisible'>,
+  state: Pick<TreeItemState, 'buttonSize' | 'active'>,
 ): TreeItemContextValues {
-  const { buttonSize, isActionsVisible } = state;
+  const { buttonSize, active } = state;
 
-  const treeItem = React.useMemo<TreeItemContextValue>(() => ({ isActionsVisible }), [isActionsVisible]);
+  const treeItem = React.useMemo<TreeItemContextValue>(() => ({ active }), [active]);
   const button = React.useMemo<ButtonContextValue>(() => ({ size: buttonSize }), [buttonSize]);
 
   return { treeItem, button };

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

@@ -128,7 +128,7 @@ export const useTreeItemStyles_unstable = (state: TreeItemState): TreeItemState
 
   const appearance = useTreeContext_unstable(ctx => ctx.appearance);
 
-  const { actions, subtree, expandIcon, isActionsVisible: showActions, level } = state;
+  const { actions, subtree, expandIcon, active, level } = state;
 
   state.root.className = mergeClasses(
     treeItemClassNames.root,
@@ -152,7 +152,7 @@ export const useTreeItemStyles_unstable = (state: TreeItemState): TreeItemState
     actions.className = mergeClasses(
       treeItemClassNames.actions,
       actionsStyles.base,
-      showActions && actionsStyles.open,
+      active && actionsStyles.open,
       actions.className,
     );
   }

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

@@ -9,7 +9,7 @@ import type { TreeItemLayoutState, TreeItemLayoutSlots } from './TreeItemLayout.
  * Render the final JSX of TreeItemLayout
  */
 export const renderTreeItemLayout_unstable = (state: TreeItemLayoutState) => {
-  const { isActionsVisible } = state;
+  const { active: isActionsVisible } = state;
   const { slots, slotProps } = getSlotsNext<TreeItemLayoutSlots>(state);
   return (
     <slots.root {...slotProps.root}>

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

@@ -17,7 +17,7 @@ export const renderTreeItemPersonaLayout_unstable = (
   state: TreeItemPersonaLayoutState,
   contextValues: TreeItemPersonaLayoutContextValues,
 ) => {
-  const { isActionsVisible } = state;
+  const { active: isActionsVisible } = state;
   const { slots, slotProps } = getSlotsNext<TreeItemPersonaLayoutSlots>(state);
 
   return (

packages/react-components/react-tree/src/components/TreeItemPersonaLayout/useTreeItemPersonaLayout.ts

@@ -19,7 +19,7 @@ export const useTreeItemPersonaLayout_unstable = (
 ): TreeItemPersonaLayoutState => {
   const { media, content, children, main, description, aside, as = 'span' } = props;
   const size = useTreeContext_unstable(ctx => ctx.size);
-  const { isActionsVisible } = useTreeItemContext_unstable();
+  const { active: isActionsVisible } = useTreeItemContext_unstable();
   return {
     components: {
       content: 'div',
@@ -29,7 +29,7 @@ export const useTreeItemPersonaLayout_unstable = (
       media: 'span',
       aside: 'span',
     },
-    isActionsVisible,
+    active: isActionsVisible,
     avatarSize: treeAvatarSize[size],
     root: getNativeElementProps(as, { ...props, ref }),
     main: resolveShorthand(main, { required: true, defaultProps: { children } }),

packages/react-components/react-tree/src/contexts/treeItemContext.ts

@@ -1,11 +1,11 @@
 import * as React from 'react';
 
 export type TreeItemContextValue = {
-  isActionsVisible: boolean;
+  active: boolean;
 };
 
 const defaultContextValue: TreeItemContextValue = {
-  isActionsVisible: false,
+  active: false,
 };
 
 export const TreeItemContext: React.Context<TreeItemContextValue | undefined> = React.createContext<

packages/react-components/react-tree/stories/B_TreeItem/TreeItemActions.md

@@ -1,3 +1,5 @@
 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`.
+
+> To force the visibility of an action, use the `active` property

packages/react-components/react-tree/stories/B_TreeItem/TreeItemActions.stories.tsx

@@ -28,7 +28,7 @@ const RenderActions = () => {
 
 export const Actions = () => (
   <Tree aria-label="Tree">
-    <TreeItem actions={<RenderActions />}>
+    <TreeItem active actions={<RenderActions />}>
       <TreeItemLayout>level 1, item 1</TreeItemLayout>
       <Tree>
         <TreeItem actions={<RenderActions />}>