feat(useFocusZone): update active descendant on mousemove

Author: dgreif

src/ActionList/Item.tsx

@@ -9,6 +9,11 @@ import {StyledHeader} from './Header'
 import {StyledDivider} from './Divider'
 import {useColorSchemeVar, useTheme} from '../ThemeProvider'
 import {uniqueId} from '../utils/uniqueId'
+import {
+  activeDescendantActivatedDirectly,
+  activeDescendantActivatedIndirectly,
+  isActiveDescendantAttribute
+} from '../behaviors/focusZone'
 
 /**
  * These colors are not yet in our default theme.  Need to remove this once they are added.
@@ -121,8 +126,6 @@ export interface ItemProps extends Omit<React.ComponentPropsWithoutRef<'div'>, '
   id?: number | string
 }
 
-export const itemActiveDescendantClass = `${uniqueId()}active-descendant`
-
 const getItemVariant = (variant = 'default', disabled?: boolean) => {
   if (disabled) {
     return {
@@ -212,16 +215,23 @@ const StyledItem = styled.div<
   // '*' instead of '&' because '&' maps to separate class names depending on 'variant'
   :focus + * ${StyledItemContent}::before,
   // - above Active Descendent
-  &.${itemActiveDescendantClass} ${StyledItemContent}::before,
+  &[${isActiveDescendantAttribute}] ${StyledItemContent}::before,
   // - below Active Descendent
-  .${itemActiveDescendantClass} + & ${StyledItemContent}::before {
+  [${isActiveDescendantAttribute}] + & ${StyledItemContent}::before {
     // '!important' because all the ':not's above give higher specificity
     border-color: transparent !important;
   }
 
-  // Focused OR Active Descendant
-  &:focus,
-  &.${itemActiveDescendantClass} {
+  // Active Descendant
+  &[${isActiveDescendantAttribute}='${activeDescendantActivatedDirectly}'] {
+    background: ${({focusBackground}) => focusBackground};
+  }
+  &[${isActiveDescendantAttribute}='${activeDescendantActivatedIndirectly}'] {
+    background: ${({hoverBackground}) => hoverBackground};
+  }
+
+  // Focused
+  &:focus {
     background: ${({focusBackground}) => focusBackground};
     outline: none;
   }

src/ActionList/List.tsx

@@ -132,7 +132,7 @@ function useListVariant(variant: ListProps['variant'] = 'inset'): {
 /**
  * Lists `Item`s, either grouped or ungrouped, with a `Divider` between each `Group`.
  */
-export function List(props: ListProps): JSX.Element {
+export const List = React.forwardRef<HTMLDivElement, ListProps>((props, forwardedRef): JSX.Element => {
   // Get `sx` prop values for `List` children matching the given `List` style variation.
   const {firstGroupStyle, lastGroupStyle, headerStyle, itemStyle} = useListVariant(props.variant)
 
@@ -216,7 +216,7 @@ export function List(props: ListProps): JSX.Element {
   }
 
   return (
-    <StyledList {...props}>
+    <StyledList {...props} ref={forwardedRef}>
       {groups.map(({header, ...groupProps}, index) => {
         const hasFilledHeader = header?.variant === 'filled'
         const shouldShowDivider = index > 0 && !hasFilledHeader
@@ -242,4 +242,6 @@ export function List(props: ListProps): JSX.Element {
       })}
     </StyledList>
   )
-}
+})
+
+List.displayName = 'ActionList'

src/FilteredActionList/FilteredActionList.tsx

@@ -7,7 +7,6 @@ import {ActionList} from '../ActionList'
 import Spinner from '../Spinner'
 import {useFocusZone} from '../hooks/useFocusZone'
 import {uniqueId} from '../utils/uniqueId'
-import {itemActiveDescendantClass} from '../ActionList/Item'
 import {useProvidedStateOrCreate} from '../hooks/useProvidedStateOrCreate'
 import styled from 'styled-components'
 import {get} from '../constants'
@@ -71,6 +70,7 @@ export function FilteredActionList({
     [onFilterChange, setInternalFilterValue]
   )
 
+  const scrollContainerRef = useRef<HTMLDivElement>(null)
   const listContainerRef = useRef<HTMLDivElement>(null)
   const inputRef = useProvidedRefOrCreate<HTMLInputElement>(providedInputRef)
   const activeDescendantRef = useRef<HTMLElement>()
@@ -100,19 +100,11 @@ export function FilteredActionList({
       return true
     },
     activeDescendantFocus: inputRef,
-    onActiveDescendantChanged: (current, previous) => {
+    onActiveDescendantChanged: (current, previous, activatedByKeyboardNavigation) => {
       activeDescendantRef.current = current
 
-      if (previous) {
-        previous.classList.remove(itemActiveDescendantClass)
-      }
-
-      if (current) {
-        current.classList.add(itemActiveDescendantClass)
-
-        if (listContainerRef.current) {
-          scrollIntoViewingArea(current, listContainerRef.current)
-        }
+      if (current && scrollContainerRef.current && activatedByKeyboardNavigation) {
+        scrollIntoViewingArea(current, scrollContainerRef.current)
       }
     }
   })
@@ -124,7 +116,7 @@ export function FilteredActionList({
     }
   }, [items])
 
-  useScrollFlash(listContainerRef)
+  useScrollFlash(scrollContainerRef)
 
   return (
     <Flex flexDirection="column" overflow="hidden">
@@ -143,13 +135,13 @@ export function FilteredActionList({
           {...textInputProps}
         />
       </StyledHeader>
-      <Box ref={listContainerRef} overflow="auto">
+      <Box ref={scrollContainerRef} overflow="auto">
         {loading ? (
           <Box width="100%" display="flex" flexDirection="row" justifyContent="center" pt={6} pb={7}>
             <Spinner />
           </Box>
         ) : (
-          <ActionList items={items} {...listProps} role="listbox" id={listId} />
+          <ActionList ref={listContainerRef} items={items} {...listProps} role="listbox" id={listId} />
         )}
       </Box>
     </Flex>

src/__tests__/__snapshots__/ActionMenu.tsx.snap

@@ -70,9 +70,9 @@ exports[`ActionMenu renders consistently 1`] = `
 <button
   aria-haspopup="listbox"
   aria-label="menu"
-  aria-labelledby="__primer_id_10001"
+  aria-labelledby="__primer_id_10002"
   className="c0"
-  id="__primer_id_10001"
+  id="__primer_id_10002"
   onClick={[Function]}
   onKeyDown={[Function]}
   tabIndex={0}

src/__tests__/__snapshots__/AnchoredOverlay.tsx.snap

@@ -69,9 +69,9 @@ exports[`AnchoredOverlay renders consistently 1`] = `
 
 <button
   aria-haspopup="listbox"
-  aria-labelledby="__primer_id_10001"
+  aria-labelledby="__primer_id_10002"
   className="c0"
-  id="__primer_id_10001"
+  id="__primer_id_10002"
   onClick={[Function]}
   onKeyDown={[Function]}
   tabIndex={0}

src/__tests__/__snapshots__/DropdownMenu.tsx.snap

@@ -73,9 +73,9 @@ exports[`DropdownMenu renders consistently 1`] = `
 
 <button
   aria-haspopup="listbox"
-  aria-labelledby="__primer_id_10001"
+  aria-labelledby="__primer_id_10002"
   className="c0"
-  id="__primer_id_10001"
+  id="__primer_id_10002"
   onClick={[Function]}
   onKeyDown={[Function]}
   tabIndex={0}

src/__tests__/__snapshots__/SelectPanel.tsx.snap

@@ -85,9 +85,9 @@ exports[`SelectPanel renders consistently 1`] = `
 >
   <button
     aria-haspopup="listbox"
-    aria-labelledby="__primer_id_10001"
+    aria-labelledby="__primer_id_10002"
     className="c1"
-    id="__primer_id_10001"
+    id="__primer_id_10002"
     onClick={[Function]}
     onKeyDown={[Function]}
     tabIndex={0}

src/__tests__/behaviors/focusZone.tsx

@@ -1,7 +1,7 @@
 import React from 'react'
-import {render} from '@testing-library/react'
+import {fireEvent, render} from '@testing-library/react'
 import userEvent from '@testing-library/user-event'
-import {FocusKeys, focusZone} from '../../behaviors/focusZone'
+import {FocusKeys, focusZone, FocusZoneSettings} from '../../behaviors/focusZone'
 
 async function nextTick() {
   return new Promise(resolve => setTimeout(resolve, 0))
@@ -419,24 +419,49 @@ it('Should call onActiveDescendantChanged properly', () => {
     activeDescendantControl: control,
     onActiveDescendantChanged: activeDescendantChangedCallback
   })
+  type ActiveDescendantChangedCallbackParameters = Parameters<
+    Exclude<FocusZoneSettings['onActiveDescendantChanged'], undefined>
+  >
 
   control.focus()
-  userEvent.type(control, '{arrowdown}')
-  expect(activeDescendantChangedCallback).toHaveBeenCalledWith<[HTMLElement | undefined, HTMLElement | undefined]>(
+  expect(activeDescendantChangedCallback).toHaveBeenLastCalledWith<ActiveDescendantChangedCallbackParameters>(
     firstButton,
-    undefined
+    undefined,
+    false
   )
   userEvent.type(control, '{arrowdown}')
-  expect(activeDescendantChangedCallback).toHaveBeenCalledWith<[HTMLElement | undefined, HTMLElement | undefined]>(
+  expect(activeDescendantChangedCallback).toHaveBeenLastCalledWith<ActiveDescendantChangedCallbackParameters>(
+    secondButton,
+    firstButton,
+    true
+  )
+  userEvent.type(control, '{arrowup}')
+  expect(activeDescendantChangedCallback).toHaveBeenLastCalledWith<ActiveDescendantChangedCallbackParameters>(
+    firstButton,
+    secondButton,
+    true
+  )
+  fireEvent.mouseMove(secondButton)
+  expect(activeDescendantChangedCallback).toHaveBeenLastCalledWith<ActiveDescendantChangedCallbackParameters>(
     secondButton,
-    firstButton
+    firstButton,
+    false
   )
   userEvent.type(control, '{arrowup}')
+  expect(activeDescendantChangedCallback).toHaveBeenLastCalledWith<ActiveDescendantChangedCallbackParameters>(
+    firstButton,
+    secondButton,
+    true
+  )
   userEvent.type(control, '{arrowUp}')
-  expect(activeDescendantChangedCallback).toHaveBeenCalledWith<[HTMLElement | undefined, HTMLElement | undefined]>(
-    undefined,
-    firstButton
+  expect(activeDescendantChangedCallback).toHaveBeenLastCalledWith<ActiveDescendantChangedCallbackParameters>(
+    firstButton,
+    firstButton,
+    true
   )
+  activeDescendantChangedCallback.mockReset()
+  fireEvent.mouseMove(firstButton)
+  expect(activeDescendantChangedCallback).not.toBeCalled()
 
   controller.abort()
 })

src/behaviors/focusZone.ts

@@ -189,7 +189,8 @@ export interface FocusZoneSettings {
    */
   onActiveDescendantChanged?: (
     newActiveDescendant: HTMLElement | undefined,
-    previousActiveDescendant: HTMLElement | undefined
+    previousActiveDescendant: HTMLElement | undefined,
+    directlyActivated: boolean
   ) => void
 
   /**
@@ -311,6 +312,10 @@ function shouldIgnoreFocusHandling(keyboardEvent: KeyboardEvent, activeElement:
   return false
 }
 
+export const isActiveDescendantAttribute = 'data-is-active-descendant'
+export const activeDescendantActivatedDirectly = 'activated-directly'
+export const activeDescendantActivatedIndirectly = 'activated-indirectly'
+
 /**
  * Sets up the arrow key focus behavior for all focusable elements in the given `container`.
  * @param container
@@ -337,13 +342,13 @@ export function focusZone(container: HTMLElement, settings?: FocusZoneSettings):
     return document.activeElement === activeDescendantControl
   }
 
-  function updateFocusedElement(to?: HTMLElement) {
+  function updateFocusedElement(to?: HTMLElement, directlyActivated = false) {
     const from = currentFocusedElement
     currentFocusedElement = to
 
     if (activeDescendantControl) {
       if (to && isActiveDescendantInputFocused()) {
-        setActiveDescendant(from, to)
+        setActiveDescendant(from, to, directlyActivated)
       } else {
         clearActiveDescendant()
       }
@@ -358,13 +363,29 @@ export function focusZone(container: HTMLElement, settings?: FocusZoneSettings):
     to?.setAttribute('tabindex', '0')
   }
 
-  function setActiveDescendant(from: HTMLElement | undefined, to: HTMLElement) {
+  function setActiveDescendant(from: HTMLElement | undefined, to: HTMLElement, directlyActivated = false) {
     if (!to.id) {
       to.setAttribute('id', uniqueId())
     }
 
-    activeDescendantControl?.setAttribute('aria-activedescendant', to.id)
-    activeDescendantCallback?.(to, from === to ? undefined : from)
+    if (from && from !== to) {
+      from.removeAttribute(isActiveDescendantAttribute)
+    }
+
+    if (
+      !activeDescendantControl ||
+      (!directlyActivated && activeDescendantControl.getAttribute('aria-activedescendant') === to.id)
+    ) {
+      // prevent active descendant callback from being called repeatedly if the same element is activated (e.g. via mousemove)
+      return
+    }
+
+    activeDescendantControl.setAttribute('aria-activedescendant', to.id)
+    to.setAttribute(
+      isActiveDescendantAttribute,
+      directlyActivated ? activeDescendantActivatedDirectly : activeDescendantActivatedIndirectly
+    )
+    activeDescendantCallback?.(to, from, directlyActivated)
   }
 
   function clearActiveDescendant(previouslyActiveElement = currentFocusedElement) {
@@ -373,7 +394,8 @@ export function focusZone(container: HTMLElement, settings?: FocusZoneSettings):
     }
 
     activeDescendantControl?.removeAttribute('aria-activedescendant')
-    activeDescendantCallback?.(undefined, previouslyActiveElement)
+    previouslyActiveElement?.removeAttribute(isActiveDescendantAttribute)
+    activeDescendantCallback?.(undefined, previouslyActiveElement, false)
   }
 
   function beginFocusManagement(...elements: HTMLElement[]) {
@@ -484,6 +506,23 @@ export function focusZone(container: HTMLElement, settings?: FocusZoneSettings):
         updateFocusedElement(event.target)
       }
     })
+    container.addEventListener(
+      'mousemove',
+      ({target}) => {
+        if (!(target instanceof HTMLElement)) {
+          return
+        }
+
+        const focusableElement = focusableElements.find(element => element.contains(target))
+
+        if (focusableElement) {
+          updateFocusedElement(focusableElement)
+        }
+      },
+      {signal, capture: true}
+    )
+
+    // Listeners specifically on the controlling element
     activeDescendantControl.addEventListener('focusin', () => {
       // Focus moved into the active descendant input.  Activate current or first descendant.
       if (!currentFocusedElement) {
@@ -637,13 +676,13 @@ export function focusZone(container: HTMLElement, settings?: FocusZoneSettings):
             }
           }
 
-          if (nextElementToFocus) {
-            if (activeDescendantControl) {
-              updateFocusedElement(nextElementToFocus)
-            } else {
-              lastKeyboardFocusDirection = direction
-              nextElementToFocus.focus()
-            }
+          if (activeDescendantControl) {
+            updateFocusedElement(nextElementToFocus || currentFocusedElement, true)
+          } else if (nextElementToFocus) {
+            lastKeyboardFocusDirection = direction
+
+            // updateFocusedElement will be called implicitly when focus moves, as long as the event isn't prevented somehow
+            nextElementToFocus.focus()
           }
           // Tab should always allow escaping from this container, so only
           // preventDefault if tab key press already resulted in a focus movement