fix(a11y): announce read-only state of form components to screen readers

packages/react/__tests__/__snapshots__/PublicAPI-test.js.snap

@@ -796,6 +796,9 @@ Map {
       "title": {
         "type": "string",
       },
+      "translateWithId": {
+        "type": "func",
+      },
       "warn": {
         "type": "bool",
       },
@@ -8464,6 +8467,9 @@ Map {
         "type": "bool",
       },
       "slug": [Function],
+      "translateWithId": {
+        "type": "func",
+      },
       "value": {
         "args": [
           [
@@ -8869,6 +8875,9 @@ Map {
         "type": "oneOf",
       },
       "slug": [Function],
+      "translateWithId": {
+        "type": "func",
+      },
       "warn": {
         "type": "bool",
       },
@@ -11276,6 +11285,9 @@ Map {
       "toggled": {
         "type": "bool",
       },
+      "translateWithId": {
+        "type": "func",
+      },
     },
   },
   "ToggleSkeleton" => {

packages/react/src/components/Checkbox/Checkbox.tsx

@@ -18,14 +18,27 @@ import { noopFn } from '../../internal/noopFn';
 import { useNormalizedInputProps } from '../../internal/useNormalizedInputProps';
 import { AILabel } from '../AILabel';
 import { isComponentElement } from '../../internal';
+import type { TFunc, TranslateWithId } from '../../types/common';
+
+const translationIds = {
+  'carbon.checkbox.read-only': 'carbon.checkbox.read-only',
+} as const;
+
+type TranslationKey = keyof typeof translationIds;
+
+const defaultTranslations: Record<TranslationKey, string> = {
+  [translationIds['carbon.checkbox.read-only']]: 'Read only',
+};
+
+const defaultTranslateWithId: TFunc<TranslationKey> = (messageId) => {
+  return defaultTranslations[messageId];
+};
 
 type ExcludedAttributes = 'id' | 'onChange' | 'onClick' | 'type';
 
 export interface CheckboxProps
-  extends Omit<
-    React.InputHTMLAttributes<HTMLInputElement>,
-    ExcludedAttributes
-  > {
+  extends Omit<React.InputHTMLAttributes<HTMLInputElement>, ExcludedAttributes>,
+    TranslateWithId<TranslationKey> {
   /**
    * Provide an `id` to uniquely identify the Checkbox input
    */
@@ -124,6 +137,7 @@ const Checkbox = React.forwardRef(
       invalidText,
       hideLabel,
       readOnly,
+      translateWithId: t = defaultTranslateWithId,
       title = '',
       warn,
       warnText,
@@ -150,6 +164,8 @@ const Checkbox = React.forwardRef(
 
     const checkboxGroupInstanceId = useId();
 
+    const readOnlyId = `${id}-readonly-text`;
+
     const hasHelper = hasHelperText(helperText);
     const helperId = !hasHelper
       ? undefined
@@ -212,6 +228,13 @@ const Checkbox = React.forwardRef(
           // readonly attribute not applicable to type="checkbox"
           // see - https://developer.mozilla.org/en-US/docs/Web/HTML/Element/input/checkbox
           aria-readonly={readOnly}
+          aria-describedby={
+            classNames(
+              other['aria-describedby'],
+              showHelper && helperId,
+              readOnly && readOnlyId
+            ) || undefined
+          }
           onClick={(evt) => {
             if (readOnly) {
               // prevent default stops the checkbox being updated
@@ -240,6 +263,11 @@ const Checkbox = React.forwardRef(
             )}
           </Text>
         </label>
+        {readOnly && (
+          <span id={readOnlyId} className={`${prefix}--visually-hidden`}>
+            {t('carbon.checkbox.read-only')}
+          </span>
+        )}
         <div className={`${prefix}--checkbox__validation-msg`}>
           {normalizedProps.invalid && (
             <>
@@ -336,6 +364,12 @@ Checkbox.propTypes = {
    */
   readOnly: PropTypes.bool,
 
+  /**
+   * Optional prop to specify the translation function for internationalization.
+   * Currently used to translate the read-only screen reader announcement.
+   */
+  translateWithId: PropTypes.func,
+
   /**
    * **Experimental**: Provide a `Slug` component to be rendered inside the `Checkbox` component
    */

packages/react/src/components/Checkbox/__tests__/Checkbox-test.js

@@ -213,6 +213,21 @@ describe('Checkbox', () => {
     );
   });
 
+  it('supports translateWithId for the read-only screen reader text', () => {
+    const { container } = render(
+      <Checkbox
+        labelText="Checkbox label"
+        id="checkbox-label-1"
+        readOnly
+        translateWithId={() => 'Solo lectura'}
+      />
+    );
+
+    const readOnlyText = container.querySelector(`.${prefix}--visually-hidden`);
+    expect(readOnlyText).toBeInTheDocument();
+    expect(readOnlyText).toHaveTextContent('Solo lectura');
+  });
+
   it('should respect warn prop', () => {
     const { container } = render(
       <Checkbox

packages/react/src/components/CheckboxGroup/CheckboxGroup-test.js

@@ -386,12 +386,14 @@ describe('CheckboxGroup', () => {
         class: `${prefix}--checkbox`,
         id: 'checkbox-1',
         'aria-readonly': 'true',
+        'aria-describedby': 'checkbox-1-readonly-text',
         type: 'checkbox',
       });
       expect(attributes2).toEqual({
         class: `${prefix}--checkbox`,
         id: 'checkbox-2',
         'aria-readonly': 'true',
+        'aria-describedby': 'checkbox-2-readonly-text',
         type: 'checkbox',
       });
     });
@@ -422,6 +424,7 @@ describe('CheckboxGroup', () => {
         id: 'checkbox-2',
         // Should be read-only because it inherits from the group.
         'aria-readonly': 'true',
+        'aria-describedby': 'checkbox-2-readonly-text',
         type: 'checkbox',
       });
     });
@@ -443,6 +446,7 @@ describe('CheckboxGroup', () => {
         class: `${prefix}--checkbox`,
         id: 'checkbox-1',
         'aria-readonly': 'true',
+        'aria-describedby': 'checkbox-1-readonly-text',
         type: 'checkbox',
       });
       expect(nonCheckboxAttributes).toEqual({

packages/react/src/components/Dropdown/Dropdown.tsx

@@ -77,7 +77,9 @@ export interface OnChangeData<ItemType> {
 
 export interface DropdownProps<ItemType>
   extends Omit<HTMLAttributes<HTMLDivElement>, ExcludedAttributes>,
-    TranslateWithId<ListBoxMenuIconTranslationKey> {
+    TranslateWithId<
+      ListBoxMenuIconTranslationKey | 'carbon.dropdown.read-only'
+    > {
   /**
    * Specify a label to be read by screen readers on the container node
    * 'aria-label' of the ListBox component.
@@ -596,6 +598,8 @@ const Dropdown = React.forwardRef(
       }
     }, [readOnly, onKeyDownHandler]);
 
+    const readOnlyId = `${id}-readonly-text`;
+
     const menuProps = useMemo(
       () =>
         getMenuProps({
@@ -651,18 +655,20 @@ const Dropdown = React.forwardRef(
             // aria-expanded is already being passed through {...toggleButtonProps}
             className={`${prefix}--list-box__field`}
             disabled={normalizedProps.disabled}
-            aria-disabled={readOnly ? true : undefined} // aria-disabled to remain focusable
             aria-describedby={
-              !inline &&
-              !normalizedProps.invalid &&
-              !normalizedProps.warn &&
-              helper
-                ? normalizedProps.helperId
-                : normalizedProps.invalid
-                  ? normalizedProps.invalidId
-                  : normalizedProps.warn
-                    ? normalizedProps.warnId
-                    : undefined
+              cx(
+                !inline &&
+                  !normalizedProps.invalid &&
+                  !normalizedProps.warn &&
+                  helper
+                  ? normalizedProps.helperId
+                  : normalizedProps.invalid
+                    ? normalizedProps.invalidId
+                    : normalizedProps.warn
+                      ? normalizedProps.warnId
+                      : undefined,
+                { [readOnlyId]: readOnly }
+              ) || undefined
             }
             title={
               selectedItem && itemToString !== undefined
@@ -685,6 +691,11 @@ const Dropdown = React.forwardRef(
               translateWithId={translateWithId}
             />
           </button>
+          {readOnly && (
+            <span id={readOnlyId} className={`${prefix}--visually-hidden`}>
+              {translateWithId?.('carbon.dropdown.read-only') ?? 'Read only'}
+            </span>
+          )}
           {slug ? (
             normalizedDecorator
           ) : decorator ? (

packages/react/src/components/Dropdown/__tests__/Dropdown-test.js

@@ -679,6 +679,31 @@ describe('Test useEffect ', () => {
   });
 });
 
+describe('Dropdown readOnly accessibility', () => {
+  it('should announce readOnly state to screen readers without using aria-disabled', async () => {
+    render(
+      <Dropdown
+        id="my-dropdown"
+        titleText="Dropdown label"
+        label="input"
+        items={generateItems(5, generateGenericItem)}
+        readOnly
+      />
+    );
+    await waitForPosition();
+
+    const readOnlyText = document.querySelector('.cds--visually-hidden');
+    expect(readOnlyText).toBeInTheDocument();
+    expect(readOnlyText).toHaveTextContent('Read only');
+
+    const button = screen.getByRole('combobox');
+    expect(button).not.toHaveAttribute('aria-disabled', 'true');
+    expect(button.getAttribute('aria-describedby')).toContain(
+      readOnlyText.getAttribute('id')
+    );
+  });
+});
+
 describe('Validation message ids', () => {
   const mockProps = {
     id: 'test-dropdown',
@@ -719,3 +744,25 @@ describe('Validation message ids', () => {
     );
   });
 });
+
+describe('Dropdown readOnly translation', () => {
+  it('should support a custom translateWithId for the read-only text', async () => {
+    render(
+      <Dropdown
+        id="my-dropdown"
+        titleText="Dropdown label"
+        label="input"
+        items={generateItems(5, generateGenericItem)}
+        readOnly
+        translateWithId={(id) =>
+          id === 'carbon.dropdown.read-only' ? 'Custom read only' : ''
+        }
+      />
+    );
+    await waitForPosition();
+
+    const readOnlyText = document.querySelector('.cds--visually-hidden');
+    expect(readOnlyText).toBeInTheDocument();
+    expect(readOnlyText).toHaveTextContent('Custom read only');
+  });
+});

packages/react/src/components/MultiSelect/FilterableMultiSelect.tsx

@@ -102,7 +102,9 @@ export interface FilterableMultiSelectProps<ItemType>
   extends MultiSelectSortingProps<ItemType>,
     React.RefAttributes<HTMLDivElement>,
     TranslateWithId<
-      ListBoxSelectionTranslationKey | ListBoxMenuIconTranslationKey
+      | ListBoxSelectionTranslationKey
+      | ListBoxMenuIconTranslationKey
+      | 'carbon.multi-select.read-only'
     > {
   /**
    * Specify a label to be read by screen readers on the container node
@@ -592,6 +594,7 @@ export const FilterableMultiSelect = forwardRef(function FilterableMultiSelect<
   );
   const menuId = `${id}__menu`;
   const inputId = `${id}-input`;
+  const readOnlyId = `${id}-readonly-text`;
 
   useEffect(() => {
     if (!isOpen) {
@@ -1024,6 +1027,11 @@ export const FilterableMultiSelect = forwardRef(function FilterableMultiSelect<
           <input
             className={inputClasses}
             {...inputProp}
+            aria-readonly={readOnly || undefined}
+            aria-describedby={
+              cx(inputProp['aria-describedby'], readOnly && readOnlyId) ||
+              undefined
+            }
             ref={mergedRef}
             {...readOnlyEventHandlers}
             readOnly={readOnly}
@@ -1139,6 +1147,11 @@ export const FilterableMultiSelect = forwardRef(function FilterableMultiSelect<
         </ListBox.Menu>
       </ListBox>
       {!inline && showHelperText ? helper : null}
+      {readOnly && (
+        <span id={readOnlyId} className={`${prefix}--visually-hidden`}>
+          {translateWithId?.('carbon.multi-select.read-only') ?? 'Read only'}
+        </span>
+      )}
     </div>
   );
 }) as {

packages/react/src/components/MultiSelect/MultiSelect.tsx

@@ -98,7 +98,9 @@ interface OnChangeData<ItemType> {
 export interface MultiSelectProps<ItemType>
   extends MultiSelectSortingProps<ItemType>,
     TranslateWithId<
-      ListBoxMenuIconTranslationKey | ListBoxSelectionTranslationKey
+      | ListBoxMenuIconTranslationKey
+      | ListBoxSelectionTranslationKey
+      | 'carbon.multi-select.read-only'
     > {
   /**
    * **Experimental**: Will attempt to automatically align the floating
@@ -572,6 +574,7 @@ export const MultiSelect = React.forwardRef(
       ? undefined
       : `multiselect-helper-text-${multiSelectInstanceId}`;
     const fieldLabelId = `multiselect-field-label-${multiSelectInstanceId}`;
+    const readOnlyId = `${id}-readonly-text`;
     const helperClasses = cx(`${prefix}--form__helper-text`, {
       [`${prefix}--form__helper-text--disabled`]: disabled,
     });
@@ -806,11 +809,15 @@ export const MultiSelect = React.forwardRef(
               type="button"
               className={`${prefix}--list-box__field`}
               disabled={disabled}
-              aria-disabled={disabled || readOnly}
+              aria-disabled={disabled || undefined}
+              {...toggleButtonProps}
               aria-describedby={
-                !inline && showHelperText ? helperId : undefined
+                cx(
+                  toggleButtonProps['aria-describedby'],
+                  !inline && showHelperText && helperId,
+                  readOnly && readOnlyId
+                ) || undefined
               }
-              {...toggleButtonProps}
               ref={mergedRef}
               {...readOnlyEventHandlers}>
               <span id={fieldLabelId} className={`${prefix}--list-box__label`}>
@@ -893,6 +900,11 @@ export const MultiSelect = React.forwardRef(
             {helperText}
           </div>
         )}
+        {readOnly && (
+          <span id={readOnlyId} className={`${prefix}--visually-hidden`}>
+            {translateWithId?.('carbon.multi-select.read-only') ?? 'Read only'}
+          </span>
+        )}
       </div>
     );
   }