fix: improve combobox aria-label handling and selection announcing

Author: HedwigJDoets

packages/pluggableWidgets/combobox-web/src/components/MultiSelection/MultiSelection.tsx

@@ -2,7 +2,12 @@ import classNames from "classnames";
 import { Fragment, KeyboardEvent, ReactElement, useMemo, useRef } from "react";
 import { ClearButton } from "../../assets/icons";
 import { MultiSelector, SelectionBaseProps } from "../../helpers/types";
-import { getInputLabel, getSelectedCaptionsPlaceholder, getValidationErrorId } from "../../helpers/utils";
+import {
+    getComboboxAriaLabels,
+    getInputLabel,
+    getSelectedCaptionsPlaceholder,
+    getValidationErrorId
+} from "../../helpers/utils";
 import { useDownshiftMultiSelectProps } from "../../hooks/useDownshiftMultiSelectProps";
 import { useLazyLoading } from "../../hooks/useLazyLoading";
 import { ComboboxWrapper } from "../ComboboxWrapper";
@@ -37,10 +42,7 @@ export function MultiSelection({
     } = useDownshiftMultiSelectProps(selector, options, inputRef, a11yConfig.a11yStatusMessage);
     const isSelectedItemsBoxStyle = selector.selectedItemsStyle === "boxes";
     const isOptionsSelected = selector.isOptionsSelected();
-    const inputLabel = getInputLabel(options.inputId);
     const errorId = getValidationErrorId(options.inputId);
-    const hasLabel = useMemo(() => Boolean(inputLabel), [inputLabel]);
-    const labelText = inputLabel?.textContent?.trim() || "";
     const inputProps = getInputProps({
         ...getDropdownProps(
             {
@@ -66,8 +68,7 @@ export function MultiSelection({
         },
         disabled: selector.readOnly,
         readOnly: selector.options.filterType === "none",
-        "aria-required": ariaRequired.value,
-        "aria-label": !hasLabel && options.ariaLabel ? options.ariaLabel : undefined
+        "aria-required": ariaRequired.value
     });
 
     const memoizedselectedCaptions = useMemo(
@@ -88,6 +89,20 @@ export function MultiSelection({
         readOnly: selector.readOnly
     });
 
+    const inputLabel = getInputLabel(options.inputId);
+    const ariaLabels = useMemo(
+        () =>
+            getComboboxAriaLabels({
+                isOpen,
+                hasSelection: selectedItems.length > 0,
+                selectedValue: selectedItems.map(id => selector.caption.get(id)).join(", "),
+                inputLabel,
+                labelledBy: inputProps["aria-labelledby"],
+                fallbackAriaLabel: options.ariaLabel
+            }),
+        [isOpen, selectedItems, inputLabel, inputProps, options.ariaLabel, selector.caption]
+    );
+
     return (
         <Fragment>
             <ComboboxWrapper
@@ -141,16 +156,8 @@ export function MultiSelection({
                         tabIndex={tabIndex}
                         placeholder=" "
                         {...inputProps}
-                        aria-label={
-                            !isOpen && selectedItems.length > 0 && hasLabel
-                                ? `${labelText}, ${selectedItems.map(id => selector.caption.get(id)).join(", ")}`
-                                : !isOpen && selectedItems.length > 0
-                                  ? selectedItems.map(id => selector.caption.get(id)).join(", ")
-                                  : !hasLabel
-                                    ? options.ariaLabel
-                                    : undefined
-                        }
-                        aria-labelledby={hasLabel && isOpen ? inputProps["aria-labelledby"] : undefined}
+                        aria-label={ariaLabels.ariaLabel}
+                        aria-labelledby={ariaLabels.ariaLabelledBy}
                         aria-describedby={selector.validation ? errorId : undefined}
                         aria-invalid={selector.validation ? true : undefined}
                         aria-busy={selector.options.isLoading || undefined}

packages/pluggableWidgets/combobox-web/src/components/SingleSelection/SingleSelection.tsx

@@ -2,7 +2,7 @@ import classNames from "classnames";
 import { Fragment, KeyboardEventHandler, ReactElement, useMemo, useRef } from "react";
 import { ClearButton } from "../../assets/icons";
 import { SelectionBaseProps, SingleSelector } from "../../helpers/types";
-import { getInputLabel, getValidationErrorId } from "../../helpers/utils";
+import { getComboboxAriaLabels, getInputLabel, getValidationErrorId } from "../../helpers/utils";
 import { useDownshiftSingleSelectProps } from "../../hooks/useDownshiftSingleSelectProps";
 import { useLazyLoading } from "../../hooks/useLazyLoading";
 import { ComboboxWrapper } from "../ComboboxWrapper";
@@ -57,10 +57,7 @@ export function SingleSelection({
         ]
     );
 
-    const inputLabel = getInputLabel(options.inputId);
     const errorId = getValidationErrorId(options.inputId);
-    const hasLabel = useMemo(() => Boolean(inputLabel), [inputLabel]);
-    const labelText = inputLabel?.textContent?.trim() || "";
     const onInputKeyDown = useMemo<KeyboardEventHandler<HTMLInputElement> | undefined>(() => {
         if (!selector.clearable) {
             return undefined;
@@ -79,11 +76,25 @@ export function SingleSelection({
             readOnly: selector.options.filterType === "none",
             ref: inputRef,
             "aria-required": ariaRequired.value,
-            "aria-label": !hasLabel && options.ariaLabel ? options.ariaLabel : undefined,
             onKeyDown: onInputKeyDown
         },
         { suppressRefError: true }
     );
+
+    const inputLabel = getInputLabel(options.inputId);
+    const ariaLabels = useMemo(
+        () =>
+            getComboboxAriaLabels({
+                isOpen,
+                hasSelection: Boolean(selectedItem),
+                selectedValue: selectedItem ? selector.caption.get(selectedItem) : "",
+                inputLabel,
+                labelledBy: inputProps["aria-labelledby"],
+                fallbackAriaLabel: options.ariaLabel
+            }),
+        [isOpen, selectedItem, inputLabel, inputProps, options.ariaLabel, selector.caption]
+    );
+
     return (
         <Fragment>
             <ComboboxWrapper
@@ -108,16 +119,8 @@ export function SingleSelection({
                         tabIndex={tabIndex}
                         {...inputProps}
                         placeholder=" "
-                        aria-label={
-                            !isOpen && selectedItem && hasLabel
-                                ? `${labelText}, ${selector.caption.get(selectedItem)}`
-                                : !isOpen && selectedItem
-                                  ? selector.caption.get(selectedItem)
-                                  : !hasLabel
-                                    ? options.ariaLabel
-                                    : undefined
-                        }
-                        aria-labelledby={hasLabel && isOpen ? inputProps["aria-labelledby"] : undefined}
+                        aria-label={ariaLabels.ariaLabel}
+                        aria-labelledby={ariaLabels.ariaLabelledBy}
                         aria-describedby={selector.validation ? errorId : undefined}
                         aria-invalid={selector.validation ? true : undefined}
                         aria-busy={selector.options.isLoading || undefined}

packages/pluggableWidgets/combobox-web/src/helpers/utils.ts

@@ -157,3 +157,49 @@ export function getInputLabel(inputId: string): Element | null {
 export function getValidationErrorId(inputId?: string): string | undefined {
     return inputId ? inputId + "-validation-message" : undefined;
 }
+
+/**
+ * Computes aria-label and aria-labelledby values for combobox input element.
+ *
+ * Announcement logic:
+ * - With selection (open or closed): Announce "name, selected value(s)"
+ * - Without selection: Announce "name" only
+ *
+ * Name source:
+ * - hasLabel = true: Use visible label via aria-labelledby
+ * - hasLabel = false: Use fallback aria-label
+ *
+ * Note: aria-labelledby has the highest precedence in the ARIA spec, so when we want
+ * aria-label to be announced, we must NOT set aria-labelledby at all.
+ */
+export function getComboboxAriaLabels(params: {
+    isOpen: boolean;
+    hasSelection: boolean;
+    selectedValue: string;
+    inputLabel: Element | null;
+    labelledBy: string | undefined;
+    fallbackAriaLabel?: string;
+}): { ariaLabel: string | undefined; ariaLabelledBy: string | undefined } {
+    const { hasSelection, selectedValue, inputLabel, labelledBy, fallbackAriaLabel } = params;
+
+    const hasLabel = Boolean(inputLabel);
+    const labelText = inputLabel?.textContent?.trim() || fallbackAriaLabel;
+
+    let ariaLabel: string | undefined;
+
+    // With selection: announce both name and selected value(s)
+    if (hasSelection) {
+        const name = hasLabel ? labelText : fallbackAriaLabel;
+        ariaLabel = name ? `${name}, ${selectedValue}` : selectedValue;
+    }
+    // No visible label: always use fallback aria-label
+    else if (!hasLabel) {
+        ariaLabel = fallbackAriaLabel;
+    }
+    // Otherwise: use aria-labelledby for visible label (when no selection)
+
+    return {
+        ariaLabel,
+        ariaLabelledBy: ariaLabel ? undefined : hasLabel ? labelledBy : undefined
+    };
+}

packages/pluggableWidgets/combobox-web/typings/ComboboxProps.d.ts

@@ -3,8 +3,8 @@
  * WARNING: All changes made to this file will be overwritten
  * @author Mendix Widgets Framework Team
  */
-import { ActionValue, DynamicValue, EditableValue, ListAttributeValue, ListExpressionValue, ListValue, ListWidgetValue, Option, ReferenceSetValue, ReferenceValue, SelectionMultiValue, SelectionSingleValue } from "mendix";
 import { ComponentType, ReactNode } from "react";
+import { ActionValue, DynamicValue, EditableValue, ListValue, Option, ListAttributeValue, ListExpressionValue, ListWidgetValue, ReferenceValue, ReferenceSetValue, SelectionSingleValue, SelectionMultiValue } from "mendix";
 import { Big } from "big.js";
 
 export type SourceEnum = "context" | "database" | "static";