feat(TreeView): add count prop to TreeView.SubTree

.changeset/tender-turtles-serve.md

@@ -0,0 +1,5 @@
+---
+'@primer/react': patch
+---
+
+TreeView: Add support for a skeleton state with the TreeView.SubTree `count` prop

docs/content/TreeView.mdx

@@ -307,7 +307,12 @@ See [Storybook](https://primer.style/react/storybook?path=/story/components-tree
       </>
     }
   />
-  {/* <PropsTableSxRow /> */}
+  <PropsTableRow
+    name="count"
+    type="number"
+    description="The number of items expected to be in the subtree. When in the loading state, the subtree will render a skeleton loading placeholder with the specified count of items"
+  />
+  <PropsTableSxRow />
 </PropsTable>
 
 ### TreeView.LeadingVisual

src/TreeView/TreeView.stories.tsx

@@ -459,6 +459,107 @@ AsyncSuccess.args = {
   responseTime: 2000
 }
 
+export const AsyncWithCount: Story = args => {
+  const [isLoading, setIsLoading] = React.useState(false)
+  const [asyncItems, setAsyncItems] = React.useState<string[]>([])
+
+  let state: SubTreeState = 'initial'
+
+  if (isLoading) {
+    state = 'loading'
+  } else if (asyncItems.length > 0) {
+    state = 'done'
+  }
+
+  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) {
+                setIsLoading(true)
+
+                // Load items
+                const items = await loadItems(args.responseTime)
+
+                setIsLoading(false)
+                setAsyncItems(items)
+              }
+            }}
+          >
+            <TreeView.LeadingVisual>
+              <TreeView.DirectoryIcon />
+            </TreeView.LeadingVisual>
+            Directory with async items
+            <TreeView.SubTree state={state} count={args.count}>
+              {asyncItems.map(item => (
+                <TreeView.Item key={item}>
+                  <TreeView.LeadingVisual>
+                    <FileIcon />
+                  </TreeView.LeadingVisual>
+                  {item}
+                </TreeView.Item>
+              ))}
+            </TreeView.SubTree>
+          </TreeView.Item>
+          <TreeView.LinkItem href="#src">
+            <TreeView.LeadingVisual>
+              <TreeView.DirectoryIcon />
+            </TreeView.LeadingVisual>
+            src
+            <TreeView.SubTree>
+              <TreeView.LinkItem href="#avatar-tsx">
+                <TreeView.LeadingVisual>
+                  <FileIcon />
+                </TreeView.LeadingVisual>
+                Avatar.tsx
+              </TreeView.LinkItem>
+              <TreeView.LinkItem href="#button" current>
+                <TreeView.LeadingVisual>
+                  <TreeView.DirectoryIcon />
+                </TreeView.LeadingVisual>
+                Button
+                <TreeView.SubTree>
+                  <TreeView.LinkItem href="#button-tsx">
+                    <TreeView.LeadingVisual>
+                      <FileIcon />
+                    </TreeView.LeadingVisual>
+                    Button.tsx
+                  </TreeView.LinkItem>
+                  <TreeView.LinkItem href="#button-test-tsx">
+                    <TreeView.LeadingVisual>
+                      <FileIcon />
+                    </TreeView.LeadingVisual>
+                    Button.test.tsx
+                  </TreeView.LinkItem>
+                </TreeView.SubTree>
+              </TreeView.LinkItem>
+              <TreeView.Item>
+                <TreeView.LeadingVisual>
+                  <FileIcon />
+                </TreeView.LeadingVisual>
+                ReallyLongFileNameThatShouldBeTruncated.tsx
+              </TreeView.Item>
+            </TreeView.SubTree>
+          </TreeView.LinkItem>
+        </TreeView>
+      </nav>
+    </Box>
+  )
+}
+
+AsyncWithCount.args = {
+  responseTime: 2000,
+  count: 3
+}
+
+AsyncWithCount.argTypes = {
+  count: {
+    type: 'number'
+  }
+}
+
 async function alwaysFails(responseTime: number) {
   await wait(responseTime)
   throw new Error('Failed to load items')

src/TreeView/TreeView.tsx

@@ -6,13 +6,14 @@ import {
 } from '@primer/octicons-react'
 import {useSSRSafeId} from '@react-aria/ssr'
 import React from 'react'
-import styled from 'styled-components'
+import styled, {keyframes} from 'styled-components'
 import Box from '../Box'
+import {get} from '../constants'
 import {useControllableState} from '../hooks/useControllableState'
 import useSafeTimeout from '../hooks/useSafeTimeout'
 import Spinner from '../Spinner'
 import StyledOcticon from '../StyledOcticon'
-import sx, {SxProp} from '../sx'
+import sx, {SxProp, merge} from '../sx'
 import Text from '../Text'
 import {Theme} from '../ThemeProvider'
 import createSlots from '../utils/create-slots'
@@ -112,12 +113,15 @@ export type TreeViewItemProps = {
   expanded?: boolean
   onExpandedChange?: (expanded: boolean) => void
   onSelect?: (event: React.MouseEvent<HTMLElement> | React.KeyboardEvent<HTMLElement>) => void
-}
+} & SxProp
 
 const {Slots, Slot} = createSlots(['LeadingVisual', 'TrailingVisual'])
 
 const Item = React.forwardRef<HTMLElement, TreeViewItemProps>(
-  ({current: isCurrentItem = false, defaultExpanded = false, expanded, onExpandedChange, onSelect, children}, ref) => {
+  (
+    {current: isCurrentItem = false, defaultExpanded = false, expanded, onExpandedChange, onSelect, children, sx = {}},
+    ref
+  ) => {
     const itemId = useSSRSafeId()
     const labelId = useSSRSafeId()
     const leadingVisualId = useSSRSafeId()
@@ -219,54 +223,57 @@ const Item = React.forwardRef<HTMLElement, TreeViewItemProps>(
                 toggle(event)
               }
             }}
-            sx={{
-              '--toggle-width': '1rem', // 16px
-              position: 'relative',
-              display: 'grid',
-              gridTemplateColumns: `calc(${level - 1} * (var(--toggle-width) / 2)) var(--toggle-width) 1fr`,
-              gridTemplateAreas: `"spacer toggle content"`,
-              width: '100%',
-              height: '2rem', // 32px
-              fontSize: 1,
-              color: 'fg.default',
-              borderRadius: 2,
-              cursor: 'pointer',
-              '&:hover': {
-                backgroundColor: 'actionListItem.default.hoverBg',
-                '@media (forced-colors: active)': {
-                  outline: '2px solid transparent',
-                  outlineOffset: -2
-                }
-              },
-              '@media (pointer: coarse)': {
-                '--toggle-width': '1.5rem', // 24px
-                height: '2.75rem' // 44px
-              },
-              // WARNING: styled-components v5.2 introduced a bug that changed
-              // how it expands `&` in CSS selectors. The following selectors
-              // are unnecessarily specific to work around that styled-components bug.
-              // Reference issue: https://github.com/styled-components/styled-components/issues/3265
-              [`#${itemId}:focus-visible  > &:is(div)`]: {
-                boxShadow: (theme: Theme) => `inset 0 0 0 2px ${theme.colors.accent.emphasis}`,
-                '@media (forced-colors: active)': {
-                  outline: '2px solid SelectedItem',
-                  outlineOffset: -2
+            sx={merge.all([
+              {
+                '--toggle-width': '1rem', // 16px
+                position: 'relative',
+                display: 'grid',
+                gridTemplateColumns: `calc(${level - 1} * (var(--toggle-width) / 2)) var(--toggle-width) 1fr`,
+                gridTemplateAreas: `"spacer toggle content"`,
+                width: '100%',
+                minHeight: '2rem', // 32px
+                fontSize: 1,
+                color: 'fg.default',
+                borderRadius: 2,
+                cursor: 'pointer',
+                '&:hover': {
+                  backgroundColor: 'actionListItem.default.hoverBg',
+                  '@media (forced-colors: active)': {
+                    outline: '2px solid transparent',
+                    outlineOffset: -2
+                  }
+                },
+                '@media (pointer: coarse)': {
+                  '--toggle-width': '1.5rem', // 24px
+                  minHeight: '2.75rem' // 44px
+                },
+                // WARNING: styled-components v5.2 introduced a bug that changed
+                // how it expands `&` in CSS selectors. The following selectors
+                // are unnecessarily specific to work around that styled-components bug.
+                // Reference issue: https://github.com/styled-components/styled-components/issues/3265
+                [`#${itemId}:focus-visible  > &:is(div)`]: {
+                  boxShadow: (theme: Theme) => `inset 0 0 0 2px ${theme.colors.accent.emphasis}`,
+                  '@media (forced-colors: active)': {
+                    outline: '2px solid SelectedItem',
+                    outlineOffset: -2
+                  }
+                },
+                '[role=treeitem][aria-current=true] > &:is(div)': {
+                  bg: 'actionListItem.default.selectedBg',
+                  '&::after': {
+                    position: 'absolute',
+                    top: 'calc(50% - 12px)',
+                    left: -2,
+                    width: '4px',
+                    height: '24px',
+                    content: '""',
+                    bg: 'accent.fg',
+                    borderRadius: 2
+                  }
                 }
               },
-              '[role=treeitem][aria-current=true] > &:is(div)': {
-                bg: 'actionListItem.default.selectedBg',
-                '&::after': {
-                  position: 'absolute',
-                  top: 'calc(50% - 12px)',
-                  left: -2,
-                  width: '4px',
-                  height: '24px',
-                  content: '""',
-                  bg: 'accent.fg',
-                  borderRadius: 2
-                }
-              }
-            }}
+              sx as SxProp
+            ])}
           >
             <Box sx={{gridArea: 'spacer', display: 'flex'}}>
               <LevelIndicatorLines level={level} />
@@ -401,9 +408,13 @@ export type SubTreeState = 'initial' | 'loading' | 'done' | 'error'
 export type TreeViewSubTreeProps = {
   children?: React.ReactNode
   state?: SubTreeState
+  /**
+   * Display a skeleton loading state with the specified count of items
+   */
+  count?: number
 }
 
-const SubTree: React.FC<TreeViewSubTreeProps> = ({state, children}) => {
+const SubTree: React.FC<TreeViewSubTreeProps> = ({count, state, children}) => {
   const {announceUpdate} = React.useContext(RootContext)
   const {itemId, isExpanded} = React.useContext(ItemContext)
   const [isLoadingItemVisible, setIsLoadingItemVisible] = React.useState(false)
@@ -469,14 +480,112 @@ const SubTree: React.FC<TreeViewSubTreeProps> = ({state, children}) => {
         margin: 0
       }}
     >
-      {isLoadingItemVisible ? <LoadingItem ref={loadingItemRef} /> : children}
+      {isLoadingItemVisible ? <LoadingItem ref={loadingItemRef} count={count} /> : children}
     </Box>
   )
 }
 
 SubTree.displayName = 'TreeView.SubTree'
 
-const LoadingItem = React.forwardRef<HTMLElement>((props, ref) => {
+const shimmer = keyframes`
+  from { mask-position: 200%; }
+  to { mask-position: 0%; }
+`
+
+const SkeletonItem = styled.span`
+  display: flex;
+  align-items: center;
+  column-gap: 0.5rem;
+  height: 2rem;
+
+  @media (pointer: coarse) {
+    height: 2.75rem;
+  }
+
+  @media (prefers-reduced-motion: no-preference) {
+    mask-image: linear-gradient(75deg, #000 30%, rgba(0, 0, 0, 0.65) 80%);
+    mask-size: 200%;
+    animation: ${shimmer};
+    animation-duration: 1s;
+    animation-iteration-count: infinite;
+  }
+
+  &::before {
+    content: '';
+    display: block;
+    width: 1rem;
+    height: 1rem;
+    background-color: ${get('colors.neutral.subtle')};
+    border-radius: 3px;
+    @media (forced-colors: active) {
+      outline: 1px solid transparent;
+      outline-offset: -1px;
+    }
+  }
+
+  &::after {
+    content: '';
+    display: block;
+    width: var(--tree-item-loading-width, 67%);
+    height: 1rem;
+    background-color: ${get('colors.neutral.subtle')};
+    border-radius: 3px;
+    @media (forced-colors: active) {
+      outline: 1px solid transparent;
+      outline-offset: -1px;
+    }
+  }
+
+  &:nth-of-type(5n + 1) {
+    --tree-item-loading-width: 67%;
+  }
+
+  &:nth-of-type(5n + 2) {
+    --tree-item-loading-width: 47%;
+  }
+
+  &:nth-of-type(5n + 3) {
+    --tree-item-loading-width: 73%;
+  }
+
+  &:nth-of-type(5n + 4) {
+    --tree-item-loading-width: 64%;
+  }
+
+  &:nth-of-type(5n + 5) {
+    --tree-item-loading-width: 50%;
+  }
+`
+
+type LoadingItemProps = {
+  count?: number
+}
+
+const LoadingItem = React.forwardRef<HTMLElement, LoadingItemProps>((props, ref) => {
+  const {count} = props
+
+  if (count) {
+    return (
+      <Item
+        ref={ref}
+        sx={{
+          '&:hover': {
+            backgroundColor: 'transparent',
+            cursor: 'default',
+            '@media (forced-colors: active)': {
+              outline: 'none'
+            }
+          }
+        }}
+      >
+        {Array.from({length: count}).map((_, i) => {
+          return <SkeletonItem aria-hidden={true} key={i} />
+        })}
+        <VisuallyHidden>Loading {count} items</VisuallyHidden>
+      </Item>
+    )
+  }
+
   return (
     <Item ref={ref}>
       <LeadingVisual>