TreeView: Support async behavior

.changeset/breezy-bobcats-explain.md

@@ -0,0 +1,5 @@
+---
+"@primer/react": patch
+---
+
+TreeView: Add `TreeView.LoadingItem` component

docs/content/TreeView.mdx

@@ -181,6 +181,10 @@ Since stateful directory icons are a common use case for TreeView, we provide a
 </Box>
 ```
 
+### With asynchronously loaded items
+
+See [Storybook](https://primer.style/react/storybook?path=/story/components-treeview--async-success) for examples with asynchronously loaded items.
+
 ## Props
 
 ### TreeView
@@ -266,6 +270,10 @@ Since stateful directory icons are a common use case for TreeView, we provide a
   {/* <PropsTableSxRow /> */}
 </PropsTable>
 
+### TreeView.LoadingItem
+
+<PropsTable>{/* <PropsTableSxRow /> */}</PropsTable>
+
 ### TreeView.SubTree
 
 <PropsTable>
@@ -299,8 +307,6 @@ Since stateful directory icons are a common use case for TreeView, we provide a
 
 <PropsTable>{/* <PropsTableSxRow /> */}</PropsTable>
 
-<!-- TODO: Add components to support async behavior (e.g. LoadingItem) -->
-
 ## Status
 
 <ComponentChecklist

src/TreeView/TreeView.stories.tsx

@@ -1,12 +1,13 @@
-import React from 'react'
 import {DiffAddedIcon, DiffModifiedIcon, DiffRemovedIcon, DiffRenamedIcon, FileIcon} from '@primer/octicons-react'
 import {Meta, Story} from '@storybook/react'
+import React from 'react'
+import {ActionList} from '../ActionList'
+import {ActionMenu} from '../ActionMenu'
 import Box from '../Box'
+import {Button} from '../Button'
+import {ConfirmationDialog} from '../Dialog/ConfirmationDialog'
 import StyledOcticon from '../StyledOcticon'
 import {TreeView} from './TreeView'
-import {Button} from '../Button'
-import {ActionMenu} from '../ActionMenu'
-import {ActionList} from '../ActionList'
 
 const meta: Meta = {
   title: 'Components/TreeView',
@@ -404,4 +405,148 @@ function TreeItem({
   )
 }
 
+async function wait(ms: number) {
+  return new Promise(resolve => setTimeout(resolve, ms))
+}
+
+async function loadItems(responseTime: number) {
+  await wait(responseTime)
+  return ['Avatar.tsx', 'Button.tsx', 'Checkbox.tsx']
+}
+
+export const AsyncSuccess: Story = args => {
+  const [isLoading, setIsLoading] = React.useState(false)
+  const [asyncItems, setAsyncItems] = React.useState<string[]>([])
+
+  return (
+    <Box sx={{p: 3}}>
+      <nav aria-label="File navigation">
+        <TreeView aria-label="File navigation">
+          <TreeView.Item
+            onExpandedChange={async isExpanded => {
+              if (asyncItems.length === 0 && isExpanded) {
+                // Show loading indicator after a short delay
+                const timeout = setTimeout(() => setIsLoading(true), 300)
+
+                // Load items
+                const items = await loadItems(args.responseTime)
+
+                clearTimeout(timeout)
+                setIsLoading(false)
+                setAsyncItems(items)
+              }
+            }}
+          >
+            <TreeView.LeadingVisual>
+              <TreeView.DirectoryIcon />
+            </TreeView.LeadingVisual>
+            Directory with async items
+            <TreeView.SubTree>
+              {isLoading ? <TreeView.LoadingItem /> : null}
+              {asyncItems.map(item => (
+                <TreeView.Item key={item}>
+                  <TreeView.LeadingVisual>
+                    <FileIcon />
+                  </TreeView.LeadingVisual>
+                  {item}
+                </TreeView.Item>
+              ))}
+            </TreeView.SubTree>
+          </TreeView.Item>
+        </TreeView>
+      </nav>
+    </Box>
+  )
+}
+
+AsyncSuccess.args = {
+  responseTime: 2000
+}
+
+async function alwaysFails(responseTime: number) {
+  await wait(responseTime)
+  throw new Error('Failed to load items')
+  return []
+}
+
+export const AsyncError: Story = args => {
+  const [isLoading, setIsLoading] = React.useState(false)
+  const [isExpanded, setIsExpanded] = React.useState(false)
+  const [asyncItems, setAsyncItems] = React.useState<string[]>([])
+  const [error, setError] = React.useState<Error | null>(null)
+
+  async function loadItems() {
+    if (asyncItems.length === 0) {
+      // Show loading indicator after a short delay
+      const timeout = setTimeout(() => setIsLoading(true), 300)
+      try {
+        // Try to load items
+        const items = await alwaysFails(args.responseTime)
+        setAsyncItems(items)
+      } catch (error) {
+        setError(error as Error)
+      } finally {
+        clearTimeout(timeout)
+        setIsLoading(false)
+      }
+    }
+  }
+
+  return (
+    <Box sx={{p: 3}}>
+      <nav aria-label="File navigation">
+        <TreeView aria-label="File navigation">
+          <TreeView.Item
+            expanded={isExpanded}
+            onExpandedChange={isExpanded => {
+              setIsExpanded(isExpanded)
+
+              if (isExpanded) {
+                loadItems()
+              }
+            }}
+          >
+            <TreeView.LeadingVisual>
+              <TreeView.DirectoryIcon />
+            </TreeView.LeadingVisual>
+            Directory with async items
+            <TreeView.SubTree>
+              {isLoading ? <TreeView.LoadingItem /> : null}
+              {error ? (
+                <ConfirmationDialog
+                  title="Error"
+                  onClose={gesture => {
+                    setError(null)
+
+                    if (gesture === 'confirm') {
+                      loadItems()
+                    } else {
+                      setIsExpanded(false)
+                    }
+                  }}
+                  confirmButtonContent="Retry"
+                >
+                  {error.message}
+                </ConfirmationDialog>
+              ) : null}
+              {asyncItems.map(item => (
+                <TreeView.Item key={item}>
+                  <TreeView.LeadingVisual>
+                    <FileIcon />
+                  </TreeView.LeadingVisual>
+                  {item}
+                </TreeView.Item>
+              ))}
+            </TreeView.SubTree>
+          </TreeView.Item>
+        </TreeView>
+      </nav>
+    </Box>
+  )
+}
+
+AsyncError.args = {
+  responseTime: 2000
+}
+
 export default meta

src/TreeView/TreeView.tsx

@@ -8,8 +8,9 @@ import {useSSRSafeId} from '@react-aria/ssr'
 import React from 'react'
 import styled from 'styled-components'
 import Box from '../Box'
-import StyledOcticon from '../StyledOcticon'
 import {useControllableState} from '../hooks/useControllableState'
+import Spinner from '../Spinner'
+import StyledOcticon from '../StyledOcticon'
 import sx, {SxProp} from '../sx'
 import Text from '../Text'
 import {Theme} from '../ThemeProvider'
@@ -282,7 +283,6 @@ const Item: React.FC<TreeViewItemProps> = ({
           >
             <Slots>
               {slots => (
-                // QUESTION: How should leading and trailing visuals impact the aria-label?
                 <>
                   {slots.LeadingVisual}
                   <Text
@@ -362,6 +362,23 @@ const LinkItem: React.FC<TreeViewLinkItemProps> = ({href, onSelect, ...props}) =
   )
 }
 
+// ----------------------------------------------------------------------------
+// TreeView.LoadingItem
+
+const LoadingItem: React.FC = () => {
+  return (
+    // TODO: What aria attributes do we need to add here?
+    <Item>
+      <LeadingVisual>
+        <Spinner size="small" />
+      </LeadingVisual>
+      <Text sx={{color: 'fg.muted'}}>Loading...</Text>
+    </Item>
+  )
+}
+
+LoadingItem.displayName = 'TreeView.LoadingItem'
+
 // ----------------------------------------------------------------------------
 // TreeView.SubTree
 
@@ -417,7 +434,7 @@ const LeadingVisual: React.FC<TreeViewVisualProps> = props => {
   const children = typeof props.children === 'function' ? props.children({isExpanded}) : props.children
   return (
     <Slot name="LeadingVisual">
-      <Box sx={{color: 'fg.muted'}}>{children}</Box>
+      <Box sx={{display: 'flex', color: 'fg.muted'}}>{children}</Box>
     </Slot>
   )
 }
@@ -427,7 +444,7 @@ const TrailingVisual: React.FC<TreeViewVisualProps> = props => {
   const children = typeof props.children === 'function' ? props.children({isExpanded}) : props.children
   return (
     <Slot name="TrailingVisual">
-      <Box sx={{color: 'fg.muted'}}>{children}</Box>
+      <Box sx={{display: 'flex', color: 'fg.muted'}}>{children}</Box>
     </Slot>
   )
 }
@@ -448,6 +465,7 @@ const DirectoryIcon = () => {
 export const TreeView = Object.assign(Root, {
   Item,
   LinkItem,
+  LoadingItem,
   SubTree,
   LeadingVisual,
   TrailingVisual,