SelectPanel: Add filter input label and description (#3312)

* Make placeholderText prop optional

* Add `inputLabel` prop

* Add filter input description

* Create early-beds-whisper.md

* Document inputLabel prop

* Update src/SelectPanel/SelectPanel.docs.json

* Update generated/components.json

---------

Co-authored-by: colebemis <colebemis@users.noreply.github.com>

.changeset/early-beds-whisper.md

@@ -0,0 +1,5 @@
+---
+"@primer/react": patch
+---
+
+SelectPanel: Add filter input label and description

generated/components.json

@@ -3655,6 +3655,12 @@
           "defaultValue": "",
           "description": ""
         },
+        {
+          "name": "inputLabel",
+          "type": "string",
+          "defaultValue": "Same as placeholderText",
+          "description": "The aria-label for the filter input"
+        },
         {
           "name": "overlayProps",
           "type": "Partial<OverlayProps>",

src/FilteredActionList/FilteredActionList.tsx

@@ -1,19 +1,20 @@
+import type {ScrollIntoViewOptions} from '@primer/behaviors'
+import {scrollIntoView} from '@primer/behaviors'
 import React, {KeyboardEventHandler, useCallback, useEffect, useRef} from 'react'
-import {GroupedListProps, ListPropsBase} from '../deprecated/ActionList/List'
-import TextInput, {TextInputProps} from '../TextInput'
+import styled from 'styled-components'
 import Box from '../Box'
-import {ActionList} from '../deprecated/ActionList'
 import Spinner from '../Spinner'
-import {useFocusZone} from '../hooks/useFocusZone'
-import {useProvidedStateOrCreate} from '../hooks/useProvidedStateOrCreate'
-import styled from 'styled-components'
+import TextInput, {TextInputProps} from '../TextInput'
 import {get} from '../constants'
+import {ActionList} from '../deprecated/ActionList'
+import {GroupedListProps, ListPropsBase} from '../deprecated/ActionList/List'
+import {useFocusZone} from '../hooks/useFocusZone'
+import {useId} from '../hooks/useId'
 import {useProvidedRefOrCreate} from '../hooks/useProvidedRefOrCreate'
+import {useProvidedStateOrCreate} from '../hooks/useProvidedStateOrCreate'
 import useScrollFlash from '../hooks/useScrollFlash'
-import {scrollIntoView} from '@primer/behaviors'
-import type {ScrollIntoViewOptions} from '@primer/behaviors'
+import {VisuallyHidden} from '../internal/components/VisuallyHidden'
 import {SxProp} from '../sx'
-import {useId} from '../hooks/useId'
 
 const menuScrollMargins: ScrollIntoViewOptions = {startMargin: 0, endMargin: 8}
 
@@ -22,7 +23,7 @@ export interface FilteredActionListProps
     ListPropsBase,
     SxProp {
   loading?: boolean
-  placeholderText: string
+  placeholderText?: string
   filterValue?: string
   onFilterChange: (value: string, e: React.ChangeEvent<HTMLInputElement>) => void
   textInputProps?: Partial<Omit<TextInputProps, 'onChange'>>
@@ -60,6 +61,7 @@ export function FilteredActionList({
   const inputRef = useProvidedRefOrCreate<HTMLInputElement>(providedInputRef)
   const activeDescendantRef = useRef<HTMLElement>()
   const listId = useId()
+  const inputDescriptionTextId = useId()
   const onInputKeyPress: KeyboardEventHandler = useCallback(
     event => {
       if (event.key === 'Enter' && activeDescendantRef.current) {
@@ -119,9 +121,11 @@ export function FilteredActionList({
           placeholder={placeholderText}
           aria-label={placeholderText}
           aria-controls={listId}
+          aria-describedby={inputDescriptionTextId}
           {...textInputProps}
         />
       </StyledHeader>
+      <VisuallyHidden id={inputDescriptionTextId}>Items will be filtered as you type</VisuallyHidden>
       <Box ref={scrollContainerRef} overflow="auto">
         {loading ? (
           <Box width="100%" display="flex" flexDirection="row" justifyContent="center" pt={6} pb={7}>

src/SelectPanel/SelectPanel.docs.json

@@ -18,6 +18,12 @@
       "defaultValue": "",
       "description": ""
     },
+    {
+      "name": "inputLabel",
+      "type": "string",
+      "defaultValue": "Same as placeholderText",
+      "description": "The aria-label for the filter input"
+    },
     {
       "name": "overlayProps",
       "type": "Partial<OverlayProps>",
@@ -56,4 +62,4 @@
     }
   ],
   "subcomponents": []
-}
+}

src/SelectPanel/SelectPanel.tsx

@@ -10,6 +10,7 @@ import {TextInputProps} from '../TextInput'
 import {useProvidedStateOrCreate} from '../hooks/useProvidedStateOrCreate'
 import {AnchoredOverlayWrapperAnchorProps} from '../AnchoredOverlay/AnchoredOverlay'
 import {useProvidedRefOrCreate} from '../hooks'
+import {SearchIcon} from '@primer/octicons-react'
 
 interface SelectPanelSingleSelection {
   selected: ItemInput | undefined
@@ -27,6 +28,8 @@ interface SelectPanelBaseProps {
     gesture: 'anchor-click' | 'anchor-key-press' | 'click-outside' | 'escape' | 'selection',
   ) => void
   placeholder?: string
+  // TODO: Make `inputLabel` required in next major version
+  inputLabel?: string
   overlayProps?: Partial<OverlayProps>
 }
 
@@ -53,6 +56,8 @@ export function SelectPanel({
   renderAnchor = props => <DropdownButton {...props} />,
   anchorRef: externalAnchorRef,
   placeholder,
+  placeholderText = 'Filter items',
+  inputLabel = placeholderText,
   selected,
   onSelectedChange,
   filterValue: externalFilterValue,
@@ -141,9 +146,11 @@ export function SelectPanel({
     return {
       sx: {m: 2},
       contrast: true,
+      leadingVisual: SearchIcon,
+      'aria-label': inputLabel,
       ...textInputProps,
     }
-  }, [textInputProps])
+  }, [inputLabel, textInputProps])
 
   return (
     <AnchoredOverlay
@@ -159,6 +166,7 @@ export function SelectPanel({
       <FilteredActionList
         filterValue={filterValue}
         onFilterChange={onFilterChange}
+        placeholderText={placeholderText}
         {...listProps}
         role="listbox"
         aria-multiselectable={isMultiSelectVariant(selected) ? 'true' : 'false'}