WIP: Select panel announcements

.changeset/mighty-doors-beg.md

@@ -0,0 +1,5 @@
+---
+"@primer/react": minor
+---
+
+Select Panel: Add built-in "No matches" item (behind feature flag `primer_react_select_panel_with_modern_action_list`)

.changeset/small-melons-fail.md

@@ -0,0 +1,5 @@
+---
+"@primer/react": patch
+---
+
+SelectPanel: Add announcements for screen readers (behind feature flag `primer_react_select_panel_with_modern_action_list`)

e2e/components/SelectPanel.test.ts

@@ -32,6 +32,10 @@ const scenarios = matrix({
       id: 'components-selectpanel-examples--height-initial-with-underflowing-items-after-fetch',
       name: 'Height Initial with Underflowing Items After Fetch',
     },
+    {
+      id: 'components-selectpanel-examples--no-matches',
+      name: 'No matches',
+    },
   ],
 })
 

packages/react/src/FilteredActionList/FilteredActionListWithModernActionList.tsx

@@ -20,6 +20,8 @@ import type {SxProp} from '../sx'
 
 import {isValidElementType} from 'react-is'
 import type {RenderItemFn} from '../deprecated/ActionList/List'
+import {CircleSlashIcon} from '@primer/octicons-react'
+import {useAnnouncements} from './useAnnouncements'
 
 const menuScrollMargins: ScrollIntoViewOptions = {startMargin: 0, endMargin: 8}
 
@@ -114,6 +116,7 @@ export function FilteredActionList({
   }, [items])
 
   useScrollFlash(scrollContainerRef)
+  useAnnouncements(items, listContainerRef, inputRef)
 
   function getItemListForEachGroup(groupId: string) {
     const itemsInGroup = []
@@ -151,7 +154,14 @@ export function FilteredActionList({
             <Spinner />
           </Box>
         ) : (
-          <ActionList ref={listContainerRef} showDividers={showItemDividers} {...listProps} role="listbox" id={listId}>
+          <ActionList
+            ref={listContainerRef}
+            showDividers={showItemDividers}
+            {...listProps}
+            role="listbox"
+            id={listId}
+            selectionVariant={items.length === 0 ? undefined : listProps.selectionVariant}
+          >
             {groupMetadata?.length
               ? groupMetadata.map((group, index) => {
                   return (
@@ -168,6 +178,15 @@ export function FilteredActionList({
               : items.map((item, index) => {
                   return <MappedActionListItem key={index} {...item} renderItem={listProps.renderItem} />
                 })}
+
+            {items.length === 0 ? (
+              <ActionList.Item disabled={true}>
+                <ActionList.LeadingVisual>
+                  <CircleSlashIcon />
+                </ActionList.LeadingVisual>
+                No matches
+              </ActionList.Item>
+            ) : undefined}
           </ActionList>
         )}
       </Box>

packages/react/src/FilteredActionList/useAnnouncements.tsx

@@ -0,0 +1,97 @@
+// Announcements for FilteredActionList (and SelectPanel) based
+// on https://github.com/github/multi-select-user-testing
+
+import {announce} from '@primer/live-region-element'
+import {useEffect, useRef} from 'react'
+import type {FilteredActionListProps} from './FilteredActionListEntry'
+
+// we add a delay so that it does not interrupt default screen reader announcement and queues after it
+const delayMs = 500
+
+const useFirstRender = () => {
+  const firstRender = useRef(true)
+  useEffect(() => {
+    firstRender.current = false
+  }, [])
+  return firstRender.current
+}
+
+const getItemWithActiveDescendant = (
+  listRef: React.RefObject<HTMLUListElement>,
+  items: FilteredActionListProps['items'],
+) => {
+  const listElement = listRef.current
+  const activeItemElement = listElement?.querySelector('[data-is-active-descendant]')
+
+  if (!listElement || !activeItemElement?.textContent) return
+
+  const optionElements = listElement.querySelectorAll('[role="option"]')
+
+  const index = Array.from(optionElements).indexOf(activeItemElement)
+  const activeItem = items[index]
+
+  const text = activeItem.text
+  const selected = activeItem.selected
+
+  return {index, text, selected}
+}
+
+export const useAnnouncements = (
+  items: FilteredActionListProps['items'],
+  listContainerRef: React.RefObject<HTMLUListElement>,
+  inputRef: React.RefObject<HTMLInputElement>,
+) => {
+  useEffect(
+    function announceInitialFocus() {
+      const focusHandler = () => {
+        // give @primer/behaviors a moment to apply active-descendant
+        window.requestAnimationFrame(() => {
+          const activeItem = getItemWithActiveDescendant(listContainerRef, items)
+          if (!activeItem) return
+          const {index, text, selected} = activeItem
+
+          const announcementText = [
+            `Focus on filter text box and list of labels`,
+            `Focused item: ${text}`,
+            `${selected ? 'selected' : 'not selected'}`,
+            `${index + 1} of ${items.length}`,
+          ].join(', ')
+          announce(announcementText, {delayMs})
+        })
+      }
+
+      const inputElement = inputRef.current
+      inputElement?.addEventListener('focus', focusHandler)
+      return () => inputElement?.removeEventListener('focus', focusHandler)
+    },
+    [listContainerRef, inputRef, items],
+  )
+
+  const isFirstRender = useFirstRender()
+  useEffect(
+    function announceListUpdates() {
+      if (isFirstRender) return // ignore on first render as announceInitialFocus will also announce
+
+      if (items.length === 0) {
+        announce('No matching items.', {delayMs})
+        return
+      }
+
+      // give @primer/behaviors a moment to update active-descendant
+      window.requestAnimationFrame(() => {
+        const activeItem = getItemWithActiveDescendant(listContainerRef, items)
+        if (!activeItem) return
+        const {index, text, selected} = activeItem
+
+        const announcementText = [
+          `List updated`,
+          `Focused item: ${text}`,
+          `${selected ? 'selected' : 'not selected'}`,
+          `${index} of ${items.length}`,
+        ].join(', ')
+        announce(announcementText, {delayMs})
+      })
+    },
+    [listContainerRef, inputRef, items, isFirstRender],
+  )
+}

packages/react/src/SelectPanel/SelectPanel.examples.stories.tsx

@@ -309,3 +309,32 @@ export const CustomItemRenderer = () => {
     </>
   )
 }
+
+export const NoMatches = () => {
+  const [selected, setSelected] = React.useState<ItemInput[]>([items[0], items[1]])
+  const [filter, setFilter] = React.useState('no-matches-for-this')
+  const filteredItems = items.filter(item => item.text.toLowerCase().startsWith(filter.toLowerCase()))
+  const [open, setOpen] = useState(false)
+
+  return (
+    <>
+      <h1>No matches</h1>
+      <SelectPanel
+        title="Select files"
+        renderAnchor={({...anchorProps}) => (
+          <Button trailingAction={TriangleDownIcon} {...anchorProps}>
+            Select files
+          </Button>
+        )}
+        open={open}
+        onOpenChange={setOpen}
+        items={filteredItems}
+        selected={selected}
+        onSelectedChange={setSelected}
+        filterValue={filter}
+        onFilterChange={setFilter}
+        overlayProps={{width: 'medium'}}
+      />
+    </>
+  )
+}

packages/react/src/SelectPanel/SelectPanel.test.tsx

@@ -1,10 +1,11 @@
-import {render, screen} from '@testing-library/react'
+import {render, screen, waitFor} from '@testing-library/react'
 import React from 'react'
 import {SelectPanel, type SelectPanelProps} from '../SelectPanel'
 import type {ItemInput, GroupedListProps} from '../deprecated/ActionList/List'
 import {userEvent} from '@testing-library/user-event'
 import ThemeProvider from '../ThemeProvider'
 import {FeatureFlags} from '../FeatureFlags'
+import {getLiveRegion} from '../utils/testing'
 
 const renderWithFlag = (children: React.ReactNode, flag: boolean) => {
   return render(
@@ -336,39 +337,39 @@ for (const useModernActionList of [false, true]) {
         })
       })
 
-      describe('filtering', () => {
-        function FilterableSelectPanel() {
-          const [selected, setSelected] = React.useState<SelectPanelProps['items']>([])
-          const [filter, setFilter] = React.useState('')
-          const [open, setOpen] = React.useState(false)
-
-          const onSelectedChange = (selected: SelectPanelProps['items']) => {
-            setSelected(selected)
-          }
+      function FilterableSelectPanel() {
+        const [selected, setSelected] = React.useState<SelectPanelProps['items']>([])
+        const [filter, setFilter] = React.useState('')
+        const [open, setOpen] = React.useState(false)
 
-          return (
-            <ThemeProvider>
-              <SelectPanel
-                title="test title"
-                subtitle="test subtitle"
-                items={items.filter(item => item.text?.includes(filter))}
-                placeholder="Select items"
-                placeholderText="Filter items"
-                selected={selected}
-                onSelectedChange={onSelectedChange}
-                filterValue={filter}
-                onFilterChange={value => {
-                  setFilter(value)
-                }}
-                open={open}
-                onOpenChange={isOpen => {
-                  setOpen(isOpen)
-                }}
-              />
-            </ThemeProvider>
-          )
+        const onSelectedChange = (selected: SelectPanelProps['items']) => {
+          setSelected(selected)
         }
 
+        return (
+          <ThemeProvider>
+            <SelectPanel
+              title="test title"
+              subtitle="test subtitle"
+              items={items.filter(item => item.text?.includes(filter))}
+              placeholder="Select items"
+              placeholderText="Filter items"
+              selected={selected}
+              onSelectedChange={onSelectedChange}
+              filterValue={filter}
+              onFilterChange={value => {
+                setFilter(value)
+              }}
+              open={open}
+              onOpenChange={isOpen => {
+                setOpen(isOpen)
+              }}
+            />
+          </ThemeProvider>
+        )
+      }
+
+      describe('filtering', () => {
         it('should filter the list of items when the user types into the input', async () => {
           const user = userEvent.setup()
 
@@ -381,10 +382,68 @@ for (const useModernActionList of [false, true]) {
           await user.type(document.activeElement!, 'two')
           expect(screen.getAllByRole('option')).toHaveLength(1)
         })
+      })
+
+      describe('screen reader announcements', () => {
+        // this is only implemented with the feature flag
+        if (!useModernActionList) return
+
+        it('should announce initial focused item', async () => {
+          const user = userEvent.setup()
+          renderWithFlag(<FilterableSelectPanel />, useModernActionList)
+
+          await user.click(screen.getByText('Select items'))
+          expect(screen.getByLabelText('Filter items')).toHaveFocus()
+
+          // we wait because announcement is intentionally updated after a timeout to not interrupt user input
+          await waitFor(async () => {
+            expect(getLiveRegion().getMessage('polite')).toBe(
+              'Focus on filter text box and list of labels, Focused item: item one, not selected, 1 of 3',
+            )
+          })
+        })
+
+        it('should announce filtered results', async () => {
+          const user = userEvent.setup()
+          renderWithFlag(<FilterableSelectPanel />, useModernActionList)
+
+          await user.click(screen.getByText('Select items'))
+          await user.type(document.activeElement!, 'o')
+          expect(screen.getAllByRole('option')).toHaveLength(2)
+
+          await waitFor(
+            async () => {
+              expect(getLiveRegion().getMessage('polite')).toBe(
+                'List updated, Focused item: item one, not selected, 1 of 2',
+              )
+            },
+            {timeout: 3000}, // increased timeout because we don't want the test to compare with previous announcement
+          )
+
+          await user.type(document.activeElement!, 'ne') // now: one
+          expect(screen.getAllByRole('option')).toHaveLength(1)
+
+          await waitFor(async () => {
+            expect(getLiveRegion().getMessage('polite')).toBe(
+              'List updated, Focused item: item one, not selected, 1 of 1',
+            )
+          })
+        })
 
-        it.todo('should announce the number of results')
+        it('should announce when no results are available', async () => {
+          const user = userEvent.setup()
+          renderWithFlag(<FilterableSelectPanel />, useModernActionList)
 
-        it.todo('should announce when no results are available')
+          await user.click(screen.getByText('Select items'))
+
+          await user.type(document.activeElement!, 'zero')
+          expect(screen.queryByRole('option')).toBeNull()
+          expect(screen.getByText('No matches')).toBeVisible()
+
+          await waitFor(async () => {
+            expect(getLiveRegion().getMessage('polite')).toBe('No matching items.')
+          })
+        })
       })
 
       describe('with footer', () => {