chore: expand support for custom trees

.changeset/expand-actionlist-roles.md

@@ -0,0 +1,7 @@
+---
+'@primer/react': minor
+---
+
+- ActionList: Expand `selectableRoles` and `listRoleTypes` to include `treeitem` and `tree`. 
+- Export `ActionListContainerContext` as `ActionList.ContainerContext`. 
+- Export `useRovingTabIndex` from the public API with additional configuration options (`preventScroll`, `focusOutBehavior`, `wrapAround`, and `dependencies`).

packages/react/src/ActionList/Item.tsx

@@ -80,8 +80,8 @@ const baseSlots = {
 const slotsConfig = {...baseSlots, description: Description}
 
 // Pre-allocated array for selectableRoles check, avoids per-render allocation
-const selectableRoles = ['menuitemradio', 'menuitemcheckbox', 'option']
-const listRoleTypes = ['listbox', 'menu', 'list']
+const selectableRoles = ['menuitemradio', 'menuitemcheckbox', 'option', 'treeitem']
+const listRoleTypes = ['listbox', 'menu', 'list', 'tree']
 
 const UnwrappedItem = <As extends React.ElementType = 'li'>(
   {

packages/react/src/ActionList/index.ts

@@ -7,6 +7,7 @@ import {Description} from './Description'
 import {TrailingAction} from './TrailingAction'
 import {LeadingVisual, TrailingVisual} from './Visuals'
 import {Heading} from './Heading'
+import {ActionListContainerContext} from './ActionListContainerContext'
 
 export type {ActionListProps} from './shared'
 export type {ActionListGroupProps, ActionListGroupHeadingProps} from './Group'
@@ -22,6 +23,8 @@ export type {ActionListTrailingActionProps} from './TrailingAction'
  * Collection of list-related components.
  */
 export const ActionList = Object.assign(List, {
+  /** Context for the `ActionList` container. */
+  ContainerContext: ActionListContainerContext,
   /** Collects related `Items` in an `ActionList`. */
   Group,
 

packages/react/src/TreeView/useRovingTabIndex.ts

@@ -2,80 +2,104 @@ import type React from 'react'
 import {FocusKeys, useFocusZone} from '../hooks/useFocusZone'
 import {getScrollContainer} from '../utils/scroll'
 
-export function useRovingTabIndex({
-  containerRef,
-  mouseDownRef,
-}: {
-  containerRef: React.RefObject<HTMLElement>
-  mouseDownRef: React.RefObject<boolean>
-}) {
-  // TODO: Initialize focus to the aria-current item if it exists
-  useFocusZone({
+export function useRovingTabIndex(
+  {
     containerRef,
-    bindKeys:
-      FocusKeys.ArrowVertical |
-      FocusKeys.ArrowHorizontal |
-      FocusKeys.HomeAndEnd |
-      FocusKeys.Backspace |
-      FocusKeys.PageUpDown,
-    preventScroll: true,
-    getNextFocusable: (direction, from, event) => {
-      if (!(from instanceof HTMLElement)) return
-
-      // Skip elements within a modal dialog
-      // This need to be in a try/catch to avoid errors in
-      // non-supported browsers
-      try {
-        if (from.closest('dialog:modal')) {
-          return
+    mouseDownRef,
+    focusOutBehavior,
+    preventScroll = true,
+    wrapAround = false,
+  }: {
+    containerRef: React.RefObject<HTMLElement | null>
+    mouseDownRef?: React.RefObject<boolean>
+    preventScroll?: boolean
+    focusOutBehavior?: 'stop' | 'wrap'
+    wrapAround?: boolean
+  },
+  dependencies: React.DependencyList = [],
+) {
+  // TODO: Initialize focus to the aria-current item if it exists
+  useFocusZone(
+    {
+      containerRef,
+      bindKeys:
+        FocusKeys.ArrowVertical |
+        FocusKeys.ArrowHorizontal |
+        FocusKeys.HomeAndEnd |
+        FocusKeys.Backspace |
+        FocusKeys.PageUpDown,
+      preventScroll,
+      getNextFocusable: (direction, from, event) => {
+        if (!(from instanceof HTMLElement)) return
+
+        // Skip elements within a modal dialog
+        // This need to be in a try/catch to avoid errors in
+        // non-supported browsers
+        try {
+          if (from.closest('dialog:modal')) {
+            return
+          }
+        } catch {
+          // Don't return
         }
-      } catch {
-        // Don't return
-      }
 
-      return getNextFocusableElement(from, event) ?? from
-    },
-    focusInStrategy: () => {
-      // Don't try to execute the focusInStrategy if focus is coming from a click.
-      // The clicked row will receive focus correctly by default.
-      // If a chevron is clicked, setting the focus through the focuszone will prevent its toggle.
-      if (mouseDownRef.current) {
-        return undefined
-      }
-
-      const currentItem = containerRef.current?.querySelector('[aria-current]')
-      const firstItem = containerRef.current?.querySelector('[role="treeitem"]')
-
-      // Focus the aria-current item if it exists
-      if (currentItem instanceof HTMLElement) {
-        return currentItem
-      }
-
-      // Otherwise, focus the activeElement if it's a treeitem
-      if (
-        document.activeElement instanceof HTMLElement &&
-        containerRef.current?.contains(document.activeElement) &&
-        document.activeElement.getAttribute('role') === 'treeitem'
-      ) {
-        return document.activeElement
-      }
-
-      // Otherwise, focus the first treeitem
-      return firstItem instanceof HTMLElement ? firstItem : undefined
+        return getNextFocusableElement(from, event, wrapAround) ?? from
+      },
+      ...(focusOutBehavior ? {focusOutBehavior} : {}),
+      focusInStrategy: () => {
+        // Don't try to execute the focusInStrategy if focus is coming from a click.
+        // The clicked row will receive focus correctly by default.
+        // If a chevron is clicked, setting the focus through the focuszone will prevent its toggle.
+        if (mouseDownRef?.current) {
+          return undefined
+        }
+
+        const currentItem = containerRef.current?.querySelector('[aria-current]')
+        const firstItem = containerRef.current?.querySelector('[role="treeitem"]')
+
+        // Focus the aria-current item if it exists
+        if (currentItem instanceof HTMLElement) {
+          return currentItem
+        }
+
+        // Otherwise, focus the activeElement if it's a treeitem
+        if (
+          document.activeElement instanceof HTMLElement &&
+          containerRef.current?.contains(document.activeElement) &&
+          document.activeElement.getAttribute('role') === 'treeitem'
+        ) {
+          return document.activeElement
+        }
+
+        // Otherwise, focus the first treeitem
+        return firstItem instanceof HTMLElement ? firstItem : undefined
+      },
     },
-  })
+    dependencies,
+  )
 }
 
 // DOM utilities used for focus management
 
-export function getNextFocusableElement(activeElement: HTMLElement, event: KeyboardEvent): HTMLElement | undefined {
-  const elementState = getElementState(activeElement)
+export function getNextFocusableElement(
+  activeElement: HTMLElement,
+  event: KeyboardEvent,
+  wrapAround: boolean = false,
+): HTMLElement | undefined {
+  // If focus is on a non-treeitem child (e.g. GroupHeadingWrap), resolve to the closest treeitem ancestor.
+  const treeitem =
+    activeElement.getAttribute('role') === 'treeitem'
+      ? activeElement
+      : activeElement.closest<HTMLElement>('[role="treeitem"]')
+  if (!treeitem) return
+
+  const elementState = getElementState(treeitem)
 
   // Reference: https://www.w3.org/WAI/ARIA/apg/patterns/treeview/#keyboard-interaction-24
   switch (`${elementState} ${event.key}`) {
     case 'open ArrowRight':
       // Focus first child node
-      return getFirstChildElement(activeElement)
+      return getFirstChildElement(treeitem)
 
     case 'open ArrowLeft':
       // Close node; don't change focus
@@ -87,43 +111,43 @@ export function getNextFocusableElement(activeElement: HTMLElement, event: Keybo
 
     case 'closed ArrowLeft':
       // Focus parent element
-      return getParentElement(activeElement)
+      return getParentElement(treeitem)
 
     case 'end ArrowRight':
       // Do nothing
       return
 
     case 'end ArrowLeft':
       // Focus parent element
-      return getParentElement(activeElement)
+      return getParentElement(treeitem)
   }
 
   // ArrowUp, ArrowDown, Home, and End behavior are the same regardless of element state
   switch (event.key) {
     case 'ArrowUp':
       // Focus previous visible element
-      return getVisibleElement(activeElement, 'previous')
+      return getVisibleElement(treeitem, 'previous', wrapAround)
 
     case 'ArrowDown':
       // Focus next visible element
-      return getVisibleElement(activeElement, 'next')
+      return getVisibleElement(treeitem, 'next', wrapAround)
 
     case 'Backspace':
-      return getParentElement(activeElement)
+      return getParentElement(treeitem)
 
     case 'Home':
       // Focus first visible element
-      return getFirstElement(activeElement)
+      return getFirstElement(treeitem)
 
     case 'End':
       // Focus last visible element
-      return getLastElement(activeElement)
+      return getLastElement(treeitem)
 
     case 'PageUp':
-      return getPreviousPageElement(activeElement)
+      return getPreviousPageElement(treeitem)
 
     case 'PageDown':
-      return getNextPageElement(activeElement)
+      return getNextPageElement(treeitem)
   }
 }
 
@@ -142,7 +166,11 @@ export function getElementState(element: HTMLElement): 'open' | 'closed' | 'end'
   }
 }
 
-export function getVisibleElement(element: HTMLElement, direction: 'next' | 'previous'): HTMLElement | undefined {
+export function getVisibleElement(
+  element: HTMLElement,
+  direction: 'next' | 'previous',
+  wrapAround = false,
+): HTMLElement | undefined {
   const root = element.closest('[role=tree]')
 
   if (!root) return
@@ -165,6 +193,11 @@ export function getVisibleElement(element: HTMLElement, direction: 'next' | 'pre
     next = direction === 'next' ? walker.nextNode() : walker.previousNode()
   }
 
+  // Wrap around if we reached the end/beginning of the tree
+  if (!next && wrapAround) {
+    return direction === 'next' ? getFirstElement(element) : getLastElement(element)
+  }
+
   return next instanceof HTMLElement ? next : undefined
 }
 

packages/react/src/__tests__/__snapshots__/exports.test.ts.snap

@@ -230,6 +230,7 @@ exports[`@primer/react > should not update exports without a semver change 1`] =
   "useRefObjectAsForwardedRef",
   "useResizeObserver",
   "useResponsiveValue",
+  "useRovingTabIndex",
   "useSafeTimeout",
   "useSyncedState",
   "useTheme",

packages/react/src/index.ts

@@ -199,6 +199,7 @@ export {default as Textarea} from './Textarea'
 export type {TextareaProps} from './Textarea'
 
 export {TreeView} from './TreeView'
+export {useRovingTabIndex} from './TreeView/useRovingTabIndex'
 export type {
   TreeViewProps,
   TreeViewItemProps,