From 5ebbc6cab01e6e669d19f064aaba8dbec8b60886 Mon Sep 17 00:00:00 2001
From: dgreif <dustin.greif@gmail.com>
Date: Tue, 15 Jun 2021 08:20:52 -0700
Subject: [PATCH 01/12] feat(useFocusZone): update active descendant on
 mousemove

---
 src/ActionList/Item.tsx                       | 25 ++++---
 src/ActionList/List.tsx                       |  8 ++-
 src/FilteredActionList/FilteredActionList.tsx | 22 ++----
 .../__snapshots__/ActionMenu.tsx.snap         |  4 +-
 .../__snapshots__/AnchoredOverlay.tsx.snap    |  4 +-
 .../__snapshots__/DropdownMenu.tsx.snap       |  4 +-
 .../__snapshots__/SelectPanel.tsx.snap        |  4 +-
 src/__tests__/behaviors/focusZone.tsx         | 45 ++++++++++---
 src/behaviors/focusZone.ts                    | 67 +++++++++++++++----
 9 files changed, 125 insertions(+), 58 deletions(-)

diff --git a/src/ActionList/Item.tsx b/src/ActionList/Item.tsx
index 46d9dd521c4..e250f4bf6f4 100644
--- a/src/ActionList/Item.tsx
+++ b/src/ActionList/Item.tsx
@@ -8,7 +8,11 @@ import styled from 'styled-components'
 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 +125,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 +214,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;
   }
diff --git a/src/ActionList/List.tsx b/src/ActionList/List.tsx
index b9ddc67408a..04e915a709d 100644
--- a/src/ActionList/List.tsx
+++ b/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'
diff --git a/src/FilteredActionList/FilteredActionList.tsx b/src/FilteredActionList/FilteredActionList.tsx
index ca471baaffe..c667389e202 100644
--- a/src/FilteredActionList/FilteredActionList.tsx
+++ b/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>
diff --git a/src/__tests__/__snapshots__/ActionMenu.tsx.snap b/src/__tests__/__snapshots__/ActionMenu.tsx.snap
index 7db066bfa39..a92e9626f63 100644
--- a/src/__tests__/__snapshots__/ActionMenu.tsx.snap
+++ b/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_10000"
   className="c0"
-  id="__primer_id_10001"
+  id="__primer_id_10000"
   onClick={[Function]}
   onKeyDown={[Function]}
   tabIndex={0}
diff --git a/src/__tests__/__snapshots__/AnchoredOverlay.tsx.snap b/src/__tests__/__snapshots__/AnchoredOverlay.tsx.snap
index 037610aad09..52b524b1beb 100644
--- a/src/__tests__/__snapshots__/AnchoredOverlay.tsx.snap
+++ b/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_10000"
   className="c0"
-  id="__primer_id_10001"
+  id="__primer_id_10000"
   onClick={[Function]}
   onKeyDown={[Function]}
   tabIndex={0}
diff --git a/src/__tests__/__snapshots__/DropdownMenu.tsx.snap b/src/__tests__/__snapshots__/DropdownMenu.tsx.snap
index 0e1fd83dd83..fae08d6b458 100644
--- a/src/__tests__/__snapshots__/DropdownMenu.tsx.snap
+++ b/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_10000"
   className="c0"
-  id="__primer_id_10001"
+  id="__primer_id_10000"
   onClick={[Function]}
   onKeyDown={[Function]}
   tabIndex={0}
diff --git a/src/__tests__/__snapshots__/SelectPanel.tsx.snap b/src/__tests__/__snapshots__/SelectPanel.tsx.snap
index ca231625b02..dc1343aa3f5 100644
--- a/src/__tests__/__snapshots__/SelectPanel.tsx.snap
+++ b/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_10000"
     className="c1"
-    id="__primer_id_10001"
+    id="__primer_id_10000"
     onClick={[Function]}
     onKeyDown={[Function]}
     tabIndex={0}
diff --git a/src/__tests__/behaviors/focusZone.tsx b/src/__tests__/behaviors/focusZone.tsx
index 0c93ab96eb1..a943c52b2e8 100644
--- a/src/__tests__/behaviors/focusZone.tsx
+++ b/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()
 })
diff --git a/src/behaviors/focusZone.ts b/src/behaviors/focusZone.ts
index bab31ae8fde..37ea31e31ab 100644
--- a/src/behaviors/focusZone.ts
+++ b/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

From b98d2da969a05dff515007fa34b980f0b947ee0e Mon Sep 17 00:00:00 2001
From: dgreif <dustin.greif@gmail.com>
Date: Tue, 22 Jun 2021 10:44:37 -0700
Subject: [PATCH 02/12] feat(ActionList): prevent hover state if another item
 is active/focused

---
 src/ActionList/Item.tsx    | 9 +++++++--
 src/ActionList/List.tsx    | 6 ++++++
 src/behaviors/focusZone.ts | 3 +++
 3 files changed, 16 insertions(+), 2 deletions(-)

diff --git a/src/ActionList/Item.tsx b/src/ActionList/Item.tsx
index e250f4bf6f4..ecfe0576dc4 100644
--- a/src/ActionList/Item.tsx
+++ b/src/ActionList/Item.tsx
@@ -181,7 +181,8 @@ const StyledItem = styled.div<
 
   @media (hover: hover) and (pointer: fine) {
     :hover {
-      background: ${({hoverBackground}) => hoverBackground};
+      // allow override in case another item in the list is active/focused
+      background: var(--item-hover-bg-override, ${({hoverBackground}) => hoverBackground});
       cursor: ${({variant, item}) => getItemVariant(variant, item?.disabled).hoverCursor};
     }
   }
@@ -207,7 +208,11 @@ const StyledItem = styled.div<
   &:hover ${StyledItemContent}::before,
   // - below Hovered
   // '*' instead of '&' because '&' maps to separate class names depending on 'variant'
-  :hover + * ${StyledItemContent}::before,
+  :hover + * ${StyledItemContent}::before {
+    // allow override in case another item in the list is active/focused
+    border-color: var(--item-hover-divider-border-color-override, transparent) !important;
+  }
+
   // - above Focused
   &:focus ${StyledItemContent}::before,
   // - below Focused
diff --git a/src/ActionList/List.tsx b/src/ActionList/List.tsx
index 04e915a709d..d785cfe4dd4 100644
--- a/src/ActionList/List.tsx
+++ b/src/ActionList/List.tsx
@@ -6,6 +6,7 @@ import {Divider} from './Divider'
 import styled from 'styled-components'
 import {get} from '../constants'
 import {SystemCssProperties} from '@styled-system/css'
+import {hasActiveDescendantAttribute} from '../behaviors/focusZone'
 
 export type ItemInput = ItemProps | (Partial<ItemProps> & {renderItem: typeof Item})
 
@@ -102,6 +103,11 @@ const StyledList = styled.div`
    * hardcoded '20px'
    */
   line-height: 20px;
+
+  &[${hasActiveDescendantAttribute}], &:focus-within {
+    --item-hover-bg-override: none;
+    --item-hover-divider-border-color-override: ${get('colors.selectMenu.borderSecondary')};
+  }
 `
 
 /**
diff --git a/src/behaviors/focusZone.ts b/src/behaviors/focusZone.ts
index 37ea31e31ab..551f3788d28 100644
--- a/src/behaviors/focusZone.ts
+++ b/src/behaviors/focusZone.ts
@@ -315,6 +315,7 @@ function shouldIgnoreFocusHandling(keyboardEvent: KeyboardEvent, activeElement:
 export const isActiveDescendantAttribute = 'data-is-active-descendant'
 export const activeDescendantActivatedDirectly = 'activated-directly'
 export const activeDescendantActivatedIndirectly = 'activated-indirectly'
+export const hasActiveDescendantAttribute = 'data-has-active-descendant'
 
 /**
  * Sets up the arrow key focus behavior for all focusable elements in the given `container`.
@@ -381,6 +382,7 @@ export function focusZone(container: HTMLElement, settings?: FocusZoneSettings):
     }
 
     activeDescendantControl.setAttribute('aria-activedescendant', to.id)
+    container.setAttribute(hasActiveDescendantAttribute, to.id)
     to.setAttribute(
       isActiveDescendantAttribute,
       directlyActivated ? activeDescendantActivatedDirectly : activeDescendantActivatedIndirectly
@@ -394,6 +396,7 @@ export function focusZone(container: HTMLElement, settings?: FocusZoneSettings):
     }
 
     activeDescendantControl?.removeAttribute('aria-activedescendant')
+    container.removeAttribute(hasActiveDescendantAttribute)
     previouslyActiveElement?.removeAttribute(isActiveDescendantAttribute)
     activeDescendantCallback?.(undefined, previouslyActiveElement, false)
   }

From a9762f4d851aba4f89e2c69332fb54b266b76042 Mon Sep 17 00:00:00 2001
From: dgreif <dustin.greif@gmail.com>
Date: Tue, 22 Jun 2021 11:50:29 -0700
Subject: [PATCH 03/12] test: update snapshots

---
 src/FilteredActionList/FilteredActionList.tsx   | 10 +++-------
 src/__tests__/__snapshots__/ActionList.tsx.snap |  6 ++++++
 2 files changed, 9 insertions(+), 7 deletions(-)

diff --git a/src/FilteredActionList/FilteredActionList.tsx b/src/FilteredActionList/FilteredActionList.tsx
index c667389e202..85a3408d742 100644
--- a/src/FilteredActionList/FilteredActionList.tsx
+++ b/src/FilteredActionList/FilteredActionList.tsx
@@ -93,17 +93,13 @@ export function FilteredActionList({
     containerRef: listContainerRef,
     focusOutBehavior: 'wrap',
     focusableElementFilter: element => {
-      if (element instanceof HTMLInputElement) {
-        // No active-descendant focus on checkboxes in list items
-        return false
-      }
-      return true
+      return !(element instanceof HTMLInputElement)
     },
     activeDescendantFocus: inputRef,
-    onActiveDescendantChanged: (current, previous, activatedByKeyboardNavigation) => {
+    onActiveDescendantChanged: (current, previous, directlyActivated) => {
       activeDescendantRef.current = current
 
-      if (current && scrollContainerRef.current && activatedByKeyboardNavigation) {
+      if (current && scrollContainerRef.current && directlyActivated) {
         scrollIntoViewingArea(current, scrollContainerRef.current)
       }
     }
diff --git a/src/__tests__/__snapshots__/ActionList.tsx.snap b/src/__tests__/__snapshots__/ActionList.tsx.snap
index 5b561ba1bc7..5d1308e0c23 100644
--- a/src/__tests__/__snapshots__/ActionList.tsx.snap
+++ b/src/__tests__/__snapshots__/ActionList.tsx.snap
@@ -11,6 +11,12 @@ exports[`ActionList renders consistently 1`] = `
   line-height: 20px;
 }
 
+.c0[data-has-active-descendant],
+.c0:focus-within {
+  --item-hover-bg-override: none;
+  --item-hover-divider-border-color-override: hsla(214,13%,93%,1);
+}
+
 <div
   className="c0"
 >

From 1345d6e34edb9c61dd6ca44d39d5eb69d1431c5d Mon Sep 17 00:00:00 2001
From: dgreif <dustin.greif@gmail.com>
Date: Tue, 22 Jun 2021 11:57:15 -0700
Subject: [PATCH 04/12] fix(focusZone): consider focusing a descendant to be a
 direct action

---
 src/behaviors/focusZone.ts | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/src/behaviors/focusZone.ts b/src/behaviors/focusZone.ts
index 551f3788d28..c4d7ab01825 100644
--- a/src/behaviors/focusZone.ts
+++ b/src/behaviors/focusZone.ts
@@ -506,7 +506,7 @@ export function focusZone(container: HTMLElement, settings?: FocusZoneSettings):
       if (event.target instanceof HTMLElement && focusableElements.includes(event.target)) {
         // Move focus to the activeDescendantControl if one of the descendants is focused
         activeDescendantControl.focus()
-        updateFocusedElement(event.target)
+        updateFocusedElement(event.target, true)
       }
     })
     container.addEventListener(

From 9e6f0afde91ee167f7d08034fac0b0916ad03860 Mon Sep 17 00:00:00 2001
From: dgreif <dustin.greif@gmail.com>
Date: Tue, 22 Jun 2021 12:00:47 -0700
Subject: [PATCH 05/12] fix(FilteredActionList): use correct container for
 scrolling when items change

---
 src/FilteredActionList/FilteredActionList.tsx | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/src/FilteredActionList/FilteredActionList.tsx b/src/FilteredActionList/FilteredActionList.tsx
index 85a3408d742..9a5c98d8c5a 100644
--- a/src/FilteredActionList/FilteredActionList.tsx
+++ b/src/FilteredActionList/FilteredActionList.tsx
@@ -107,8 +107,8 @@ export function FilteredActionList({
 
   useEffect(() => {
     // if items changed, we want to instantly move active descendant into view
-    if (activeDescendantRef.current && listContainerRef.current) {
-      scrollIntoViewingArea(activeDescendantRef.current, listContainerRef.current, undefined, 'auto')
+    if (activeDescendantRef.current && scrollContainerRef.current) {
+      scrollIntoViewingArea(activeDescendantRef.current, scrollContainerRef.current, undefined, 'auto')
     }
   }, [items])
 

From bc819749db2a9b67a1ae5bb42158aa6b9ad76c76 Mon Sep 17 00:00:00 2001
From: dgreif <dustin.greif@gmail.com>
Date: Tue, 22 Jun 2021 12:14:45 -0700
Subject: [PATCH 06/12] fix(ActionList.Item): darker background while mouse is
 down

---
 src/ActionList/Item.tsx    | 21 ++++++++++++++++++++-
 src/behaviors/focusZone.ts |  2 +-
 2 files changed, 21 insertions(+), 2 deletions(-)

diff --git a/src/ActionList/Item.tsx b/src/ActionList/Item.tsx
index ecfe0576dc4..61eb1eb3491 100644
--- a/src/ActionList/Item.tsx
+++ b/src/ActionList/Item.tsx
@@ -178,6 +178,8 @@ const StyledItem = styled.div<
   display: flex;
   border-radius: ${get('radii.2')};
   color: ${({variant, item}) => getItemVariant(variant, item?.disabled).color};
+  // 2 frames on a 60hz monitor
+  transition: background 133.333ms linear;
 
   @media (hover: hover) and (pointer: fine) {
     :hover {
@@ -234,12 +236,29 @@ const StyledItem = styled.div<
     background: ${({hoverBackground}) => hoverBackground};
   }
 
-  // Focused
   &:focus {
     background: ${({focusBackground}) => focusBackground};
     outline: none;
   }
 
+  &:active {
+    background: ${({focusBackground}) => focusBackground};
+    animation: actionList-item-active-bg 4s forwards ${get('animation.easeOutCubic')};
+
+    @keyframes actionList-item-active-bg {
+      0% {
+      }
+      50% {
+        transform: scale(1);
+        box-shadow: inset 0 0 0 rgba(#000, 0.04);
+      }
+      100% {
+        transform: scale(0.97);
+        box-shadow: inset 0 3px 9px rgba(#000, 0.04);
+      }
+    }
+  }
+
   ${sx}
 `
 
diff --git a/src/behaviors/focusZone.ts b/src/behaviors/focusZone.ts
index c4d7ab01825..551f3788d28 100644
--- a/src/behaviors/focusZone.ts
+++ b/src/behaviors/focusZone.ts
@@ -506,7 +506,7 @@ export function focusZone(container: HTMLElement, settings?: FocusZoneSettings):
       if (event.target instanceof HTMLElement && focusableElements.includes(event.target)) {
         // Move focus to the activeDescendantControl if one of the descendants is focused
         activeDescendantControl.focus()
-        updateFocusedElement(event.target, true)
+        updateFocusedElement(event.target)
       }
     })
     container.addEventListener(

From bc64c79426372fbc53aae7c0112d0afe2674aad3 Mon Sep 17 00:00:00 2001
From: dgreif <dustin.greif@gmail.com>
Date: Tue, 22 Jun 2021 12:18:10 -0700
Subject: [PATCH 07/12] fix(ActionList.Item): use `scale.black` instead of #000

---
 src/ActionList/Item.tsx | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/src/ActionList/Item.tsx b/src/ActionList/Item.tsx
index 61eb1eb3491..c925819923b 100644
--- a/src/ActionList/Item.tsx
+++ b/src/ActionList/Item.tsx
@@ -250,11 +250,11 @@ const StyledItem = styled.div<
       }
       50% {
         transform: scale(1);
-        box-shadow: inset 0 0 0 rgba(#000, 0.04);
+        box-shadow: inset 0 0 0 rgba(${get('colors.scale.black')}, 0.04);
       }
       100% {
         transform: scale(0.97);
-        box-shadow: inset 0 3px 9px rgba(#000, 0.04);
+        box-shadow: inset 0 3px 9px rgba(${get('colors.scale.black')}, 0.04);
       }
     }
   }

From 44580b10b4e9899f1f587eecc711585d4737ec47 Mon Sep 17 00:00:00 2001
From: Vinicius Depizzol <vdepizzol@github.com>
Date: Tue, 22 Jun 2021 12:30:45 -0700
Subject: [PATCH 08/12] fix `transition` between bg states

---
 src/ActionList/Item.tsx | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/src/ActionList/Item.tsx b/src/ActionList/Item.tsx
index c925819923b..edd4c2fb236 100644
--- a/src/ActionList/Item.tsx
+++ b/src/ActionList/Item.tsx
@@ -179,7 +179,7 @@ const StyledItem = styled.div<
   border-radius: ${get('radii.2')};
   color: ${({variant, item}) => getItemVariant(variant, item?.disabled).color};
   // 2 frames on a 60hz monitor
-  transition: background 133.333ms linear;
+  transition: background 33.333ms linear;
 
   @media (hover: hover) and (pointer: fine) {
     :hover {

From cdc79e633d42f8eaeeec793046423cd09764912d Mon Sep 17 00:00:00 2001
From: Dusty Greif <dgreif@users.noreply.github.com>
Date: Tue, 22 Jun 2021 15:40:35 -0700
Subject: [PATCH 09/12] fix(Item): remove :active transforms

Co-authored-by: Vinicius Depizzol <vdepizzol@github.com>
---
 src/ActionList/Item.tsx | 14 --------------
 1 file changed, 14 deletions(-)

diff --git a/src/ActionList/Item.tsx b/src/ActionList/Item.tsx
index edd4c2fb236..cfc2839c430 100644
--- a/src/ActionList/Item.tsx
+++ b/src/ActionList/Item.tsx
@@ -243,20 +243,6 @@ const StyledItem = styled.div<
 
   &:active {
     background: ${({focusBackground}) => focusBackground};
-    animation: actionList-item-active-bg 4s forwards ${get('animation.easeOutCubic')};
-
-    @keyframes actionList-item-active-bg {
-      0% {
-      }
-      50% {
-        transform: scale(1);
-        box-shadow: inset 0 0 0 rgba(${get('colors.scale.black')}, 0.04);
-      }
-      100% {
-        transform: scale(0.97);
-        box-shadow: inset 0 3px 9px rgba(${get('colors.scale.black')}, 0.04);
-      }
-    }
   }
 
   ${sx}

From 0a6057c65a41d71d7f57f711803a7d2a6853c289 Mon Sep 17 00:00:00 2001
From: dgreif <dustin.greif@gmail.com>
Date: Wed, 23 Jun 2021 16:32:49 -0700
Subject: [PATCH 10/12] refactor: pr feedback

---
 src/behaviors/focusZone.ts | 14 +++++++++++++-
 1 file changed, 13 insertions(+), 1 deletion(-)

diff --git a/src/behaviors/focusZone.ts b/src/behaviors/focusZone.ts
index 551f3788d28..4df5e3eae82 100644
--- a/src/behaviors/focusZone.ts
+++ b/src/behaviors/focusZone.ts
@@ -313,7 +313,19 @@ function shouldIgnoreFocusHandling(keyboardEvent: KeyboardEvent, activeElement:
 }
 
 export const isActiveDescendantAttribute = 'data-is-active-descendant'
+/**
+ * A value of activated-directly for data-is-active-descendant indicates the descendant was activated
+ * by a manual user interaction with intent to move active descendant.  This usually translates to the
+ * user pressing one of the bound keys (up/down arrow, etc) to move through the focus zone.  This is
+ * intended to be roughly equivalent to the :focus-visible pseudo-class
+ **/
 export const activeDescendantActivatedDirectly = 'activated-directly'
+/**
+ * A value of activated-indirectly for data-is-active-descendant indicates the descendant was activated
+ * implicitly, and not by a direct key press.  This includes focus zone being created from scratch, focusable
+ * elements being added/removed, and mouseover events. This is intended to be roughly equivalent
+ * to :focus:not(:focus-visible)
+ **/
 export const activeDescendantActivatedIndirectly = 'activated-indirectly'
 export const hasActiveDescendantAttribute = 'data-has-active-descendant'
 
@@ -512,7 +524,7 @@ export function focusZone(container: HTMLElement, settings?: FocusZoneSettings):
     container.addEventListener(
       'mousemove',
       ({target}) => {
-        if (!(target instanceof HTMLElement)) {
+        if (!(target instanceof Node)) {
           return
         }
 

From 19ad96a5fe398e7a7688d286ca83d3cdd388c33d Mon Sep 17 00:00:00 2001
From: Dusty Greif <dgreif@users.noreply.github.com>
Date: Thu, 24 Jun 2021 12:46:23 -0700
Subject: [PATCH 11/12] Create funny-birds-allow.md

---
 .changeset/funny-birds-allow.md | 5 +++++
 1 file changed, 5 insertions(+)
 create mode 100644 .changeset/funny-birds-allow.md

diff --git a/.changeset/funny-birds-allow.md b/.changeset/funny-birds-allow.md
new file mode 100644
index 00000000000..6db68717d10
--- /dev/null
+++ b/.changeset/funny-birds-allow.md
@@ -0,0 +1,5 @@
+---
+"@primer/components": patch
+---
+
+Focus zones will now update active-descendant on `mousemove` over focusable elements.  ActionList has been updated to handle direct (key press) vs inderect (`mousemove`, DOM change, etc.) changes to active-descendant, and will use a slightly darker background color for the directly activated items.

From 2f3567d9efed42a016523d2a958ddd51a49a184f Mon Sep 17 00:00:00 2001
From: Dusty Greif <dgreif@users.noreply.github.com>
Date: Thu, 24 Jun 2021 12:48:31 -0700
Subject: [PATCH 12/12] Update funny-birds-allow.md

---
 .changeset/funny-birds-allow.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/.changeset/funny-birds-allow.md b/.changeset/funny-birds-allow.md
index 6db68717d10..edc31f10fed 100644
--- a/.changeset/funny-birds-allow.md
+++ b/.changeset/funny-birds-allow.md
@@ -2,4 +2,4 @@
 "@primer/components": patch
 ---
 
-Focus zones will now update active-descendant on `mousemove` over focusable elements.  ActionList has been updated to handle direct (key press) vs inderect (`mousemove`, DOM change, etc.) changes to active-descendant, and will use a slightly darker background color for the directly activated items.
+Focus zones will now update active-descendant on `mousemove` over focusable elements.  ActionList has been updated to handle direct (key press) vs indirect (`mousemove`, DOM change, etc.) changes to active-descendant, and will use a distinct background color for the directly activated items.