Added SR-only help text to EuiPopover and dependent components.

src-docs/src/views/suggest/suggest_example.js

@@ -73,7 +73,7 @@ export const SuggestExample = {
     {
       source: [
         {
-          type: GuideSectionTypes.JS,
+          type: GuideSectionTypes.TSX,
           code: suggestSource,
         },
       ],

src/components/date_picker/auto_refresh/auto_refresh.tsx

@@ -146,6 +146,9 @@ export const EuiAutoRefreshButton: FunctionComponent<EuiAutoRefreshButtonProps>
       closePopover={() => {
         setIsPopoverOpen(false);
       }}
+      popoverScreenReaderText={
+        isPaused ? autoRefeshLabelOff : autoRefeshLabelOn
+      }
     >
       <EuiRefreshInterval
         onRefreshChange={onRefreshChange}

src/components/form/range/dual_range.tsx

@@ -35,6 +35,7 @@ import type { EuiDualRangeProps, _SingleRangeValue } from './types';
 
 import { euiRangeStyles } from './range.styles';
 import { euiDualRangeStyles } from './dual_range.styles';
+import { EuiI18n } from '../../i18n';
 
 type ValueMember = _SingleRangeValue['value'];
 
@@ -566,6 +567,13 @@ export class EuiDualRangeClass extends Component<
         }
       : rightThumbPosition;
 
+    const dualSliderScreenReaderInstructions = (
+      <EuiI18n
+        token="euiDualRange.sliderScreenReaderInstructions"
+        default="You are in a custom range slider. Use the Up and Down arrow keys to change the minimum value. Press Tab to interact with the maximum value."
+      />
+    );
+
     const theRange = (
       <EuiRangeWrapper
         css={cssStyles}
@@ -647,8 +655,14 @@ export class EuiDualRangeClass extends Component<
                       onFocus={this.onThumbFocus}
                       onBlur={this.onThumbBlur}
                       onKeyDown={this.handleDraggableKeyDown}
-                      aria-describedby={this.props['aria-describedby']}
-                      aria-label={this.props['aria-label']}
+                      aria-describedby={
+                        showInputOnly
+                          ? undefined
+                          : this.props['aria-describedby']
+                      }
+                      aria-label={
+                        showInputOnly ? undefined : this.props['aria-label']
+                      }
                     />
                   )}
 
@@ -663,8 +677,12 @@ export class EuiDualRangeClass extends Component<
                     onFocus={this.onThumbFocus}
                     onBlur={this.onThumbBlur}
                     style={logicalStyles(leftThumbStyles)}
-                    aria-describedby={this.props['aria-describedby']}
-                    aria-label={this.props['aria-label']}
+                    aria-describedby={
+                      showInputOnly ? undefined : this.props['aria-describedby']
+                    }
+                    aria-label={
+                      showInputOnly ? undefined : this.props['aria-label']
+                    }
                   />
 
                   <EuiRangeThumb
@@ -678,8 +696,12 @@ export class EuiDualRangeClass extends Component<
                     onFocus={this.onThumbFocus}
                     onBlur={this.onThumbBlur}
                     style={logicalStyles(rightThumbStyles)}
-                    aria-describedby={this.props['aria-describedby']}
-                    aria-label={this.props['aria-label']}
+                    aria-describedby={
+                      showInputOnly ? undefined : this.props['aria-describedby']
+                    }
+                    aria-label={
+                      showInputOnly ? undefined : this.props['aria-label']
+                    }
                   />
                 </React.Fragment>
               )}
@@ -740,6 +762,7 @@ export class EuiDualRangeClass extends Component<
         closePopover={this.closePopover}
         disableFocusTrap={true}
         onPanelResize={this.onResize}
+        popoverScreenReaderText={dualSliderScreenReaderInstructions}
       >
         {theRange}
       </EuiInputPopover>

src/components/form/range/range.tsx

@@ -30,6 +30,7 @@ import { EuiRangeWrapper } from './range_wrapper';
 import type { EuiRangeProps } from './types';
 
 import { euiRangeStyles } from './range.styles';
+import { EuiI18n } from '../../i18n';
 
 export class EuiRangeClass extends Component<
   EuiRangeProps & WithEuiThemeProps
@@ -179,6 +180,13 @@ export class EuiRangeClass extends Component<
     const cssStyles = [styles.euiRange, showInput && styles.hasInput];
     const thumbColor = levels && getLevelColor(levels, Number(value));
 
+    const sliderScreenReaderInstructions = (
+      <EuiI18n
+        token="euiRange.sliderScreenReaderInstructions"
+        default="You are in a custom range slider. Use the Up and Down arrow keys to change the value."
+      />
+    );
+
     const theRange = (
       <EuiRangeWrapper
         className={classes}
@@ -203,7 +211,7 @@ export class EuiRangeClass extends Component<
           levels={levels}
           onChange={this.handleOnChange}
           value={value}
-          aria-hidden={showInput === true}
+          aria-hidden={!!showInput}
           showRange={showRange}
         >
           {(trackWidth) => (
@@ -227,7 +235,7 @@ export class EuiRangeClass extends Component<
                 }
                 onFocus={showInput === true ? undefined : onFocus}
                 onBlur={showInputOnly ? this.onInputBlur : onBlur}
-                aria-hidden={showInput === true ? true : false}
+                aria-hidden={!!showInput}
                 thumbColor={thumbColor}
                 {...rest}
               />
@@ -291,6 +299,7 @@ export class EuiRangeClass extends Component<
         isOpen={this.state.isPopoverOpen}
         closePopover={this.closePopover}
         disableFocusTrap={true}
+        popoverScreenReaderText={sliderScreenReaderInstructions}
       >
         {theRange}
       </EuiInputPopover>

src/components/popover/popover.tsx

@@ -681,6 +681,7 @@ export class EuiPopover extends Component<Props, State> {
       let focusTrapScreenReaderText;
       if (ownFocus || popoverScreenReaderText) {
         ariaDescribedby = this.descriptionId;
+
         focusTrapScreenReaderText = (
           <EuiScreenReaderOnly>
             <p id={this.descriptionId}>

src/components/selectable/__snapshots__/selectable.test.tsx.snap

@@ -4,12 +4,6 @@ exports[`EuiSelectable custom options with data 1`] = `
 <div
   class="euiSelectable"
 >
-  <p
-    class="emotion-euiScreenReaderOnly"
-    id="generated-id_instructions"
-  >
-    Filter options
-  </p>
   <div
     class="euiSelectableList"
     data-test-subj="euiSelectableList"
@@ -119,12 +113,6 @@ exports[`EuiSelectable errorMessage prop can render an element as the message 1`
 <div
   class="euiSelectable"
 >
-  <p
-    class="emotion-euiScreenReaderOnly"
-    id="generated-id_instructions"
-  >
-    Filter options
-  </p>
   <div
     class="euiText euiSelectableMessage emotion-euiText-xs-euiTextColor-subdued"
     data-test-subj="euiSelectableMessage"
@@ -141,12 +129,6 @@ exports[`EuiSelectable errorMessage prop does not render the message when not de
 <div
   class="euiSelectable"
 >
-  <p
-    class="emotion-euiScreenReaderOnly"
-    id="generated-id_instructions"
-  >
-    Filter options
-  </p>
   <div
     class="euiSelectableList"
     data-test-subj="euiSelectableList"
@@ -257,12 +239,6 @@ exports[`EuiSelectable errorMessage prop does renders the message when defined 1
 <div
   class="euiSelectable"
 >
-  <p
-    class="emotion-euiScreenReaderOnly"
-    id="generated-id_instructions"
-  >
-    Filter options
-  </p>
   <div
     class="euiText euiSelectableMessage emotion-euiText-xs-euiTextColor-subdued"
     data-test-subj="euiSelectableMessage"
@@ -357,12 +333,6 @@ exports[`EuiSelectable search value supports inheriting initialSearchValue from
       </p>
     </div>
   </div>
-  <p
-    class="emotion-euiScreenReaderOnly"
-    id="generated-id_instructions"
-  >
-    Filter options
-  </p>
   <div
     class="euiText euiSelectableMessage emotion-euiText-xs-euiTextColor-subdued"
     data-test-subj="euiSelectableMessage"
@@ -383,6 +353,7 @@ exports[`EuiSelectable search value supports inheriting initialSearchValue from
     >
       <input
         aria-activedescendant=""
+        aria-describedby="generated-id_instructions"
         aria-haspopup="listbox"
         aria-label="Filter options"
         autocomplete="off"
@@ -422,6 +393,12 @@ exports[`EuiSelectable search value supports inheriting initialSearchValue from
       </div>
     </div>
   </div>
+  <p
+    class="emotion-euiScreenReaderOnly"
+    id="generated-id_instructions"
+  >
+    Use the Up and Down arrow keys to move focus over options. Press Enter to select. Press Escape to collapse options.
+  </p>
 </div>
 `;
 

src/components/selectable/selectable.tsx

@@ -170,6 +170,11 @@ export type EuiSelectableProps<T = {}> = CommonProps &
      * Default: false
      */
     isPreFiltered?: boolean;
+    /**
+     * Screen readers will announce the selectableScreenReaderText after they
+     * read the `EuiSelectable` label and a brief pause
+     */
+    selectableScreenReaderText?: string;
   };
 
 export interface EuiSelectableState<T> {
@@ -503,6 +508,7 @@ export class EuiSelectable<T = {}> extends Component<
       noMatchesMessage,
       emptyMessage,
       errorMessage,
+      selectableScreenReaderText,
       isPreFiltered,
       ...rest
     } = this.props;
@@ -673,26 +679,44 @@ export class EuiSelectable<T = {}> extends Component<
       Object.keys(searchAccessibleName).length
     );
     const search = searchable ? (
-      <EuiI18n token="euiSelectable.placeholderName" default="Filter options">
-        {(placeholderName: string) => (
-          <EuiSelectableSearch<T>
-            key="listSearch"
-            options={options}
-            value={searchValue}
-            onChange={this.onSearchChange}
-            listId={this.optionsListRef.current ? this.listId : undefined} // Only pass the listId if it exists on the page
-            aria-activedescendant={this.makeOptionId(activeOptionIndex)} // the current faux-focused option
-            placeholder={placeholderName}
-            isPreFiltered={isPreFiltered ?? false}
-            inputRef={(node) => {
-              this.inputRef = node;
-              searchProps?.inputRef?.(node);
-            }}
-            {...(searchHasAccessibleName
-              ? searchAccessibleName
-              : { 'aria-label': placeholderName })}
-            {...cleanedSearchProps}
-          />
+      <EuiI18n
+        tokens={[
+          'euiSelectable.screenReaderInstructions',
+          'euiSelectable.placeholderName',
+        ]}
+        defaults={[
+          'Use the Up and Down arrow keys to move focus over options. Press Enter to select. Press Escape to collapse options.',
+          'Filter options',
+        ]}
+      >
+        {([screenReaderInstructions, placeholderName]: string[]) => (
+          <>
+            <EuiSelectableSearch<T>
+              aria-describedby={listAriaDescribedbyId}
+              key="listSearch"
+              options={options}
+              value={searchValue}
+              onChange={this.onSearchChange}
+              listId={this.optionsListRef.current ? this.listId : undefined} // Only pass the listId if it exists on the page
+              aria-activedescendant={this.makeOptionId(activeOptionIndex)} // the current faux-focused option
+              placeholder={placeholderName}
+              isPreFiltered={isPreFiltered ?? false}
+              inputRef={(node) => {
+                this.inputRef = node;
+                searchProps?.inputRef?.(node);
+              }}
+              {...(searchHasAccessibleName
+                ? searchAccessibleName
+                : { 'aria-label': placeholderName })}
+              {...cleanedSearchProps}
+            />
+
+            <EuiScreenReaderOnly>
+              <p id={listAriaDescribedbyId}>
+                {selectableScreenReaderText ?? screenReaderInstructions}
+              </p>
+            </EuiScreenReaderOnly>
+          </>
         )}
       </EuiI18n>
     ) : undefined;
@@ -718,17 +742,8 @@ export class EuiSelectable<T = {}> extends Component<
       Object.keys(listAccessibleName).length
     );
     const list = (
-      <EuiI18n
-        tokens={[
-          'euiSelectable.screenReaderInstructions',
-          'euiSelectable.placeholderName',
-        ]}
-        defaults={[
-          'Use up and down arrows to move focus over options. Enter to select. Escape to collapse options.',
-          'Filter options',
-        ]}
-      >
-        {([placeholderName, screenReaderInstructions]: string[]) => (
+      <EuiI18n token="euiSelectable.placeholderName" default="Filter options">
+        {(placeholderName: string) => (
           <>
             {searchable && (
               <EuiScreenReaderLive
@@ -738,10 +753,6 @@ export class EuiSelectable<T = {}> extends Component<
               </EuiScreenReaderLive>
             )}
 
-            <EuiScreenReaderOnly>
-              <p id={listAriaDescribedbyId}>{screenReaderInstructions}</p>
-            </EuiScreenReaderOnly>
-
             {messageContent ? (
               <EuiSelectableMessage
                 data-test-subj="euiSelectableMessage"

src/components/selectable/selectable_list/selectable_list.tsx

@@ -197,7 +197,7 @@ export class EuiSelectableList<T> extends Component<EuiSelectableListProps<T>> {
       }
 
       if (typeof ariaDescribedby === 'string') {
-        ref.setAttribute('aria-labelledby', ariaDescribedby);
+        ref.setAttribute('aria-describedby', ariaDescribedby);
       }
     }
   };