diff --git a/CHANGELOG.md b/CHANGELOG.md
index 93be23c7..4427357b 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -38,6 +38,9 @@ The format is based on [Keep a Changelog](http://keepachangelog.com/) and this p
- `role` property: `menu` (default) or `listbox`, forwarded to the included `
` and used for `aria-haspopup` of the toggler
- ``
- keyboard interaction follows the [WAI-ARIA combobox pattern](https://www.w3.org/WAI/ARIA/apg/patterns/combobox/#keyboardinteraction): `Tab` and `Shift+Tab` only move the focus, they do not select the active option or create a new item from the query anymore, use `Enter` for it
+- ``
+ - The clear action shows `onClearanceText` as native `title` instead of a `Tooltip`.
+ - If not filterable, the focusable combobox renders its default target without a button, and hides focusable elements of custom `children` from the Tab order and screen readers.
### Fixed
@@ -46,6 +49,20 @@ The format is based on [Keep a Changelog](http://keepachangelog.com/) and this p
- improve keyboard navigation, tag removal and focus handling
- improve screen reader labels and selection announcements
- preserve filters and keep the dropdown open when toggling existing options
+- ``
+ - Clicking a label focuses its control when a native label association is not available, e.g. for CodeEditor.
+ - An explicit `labelProps.htmlFor` that refers to an input element of the field item selects the connected input element.
+ - Helper text and message are connected to this input element via `aria-describedby`, not always to the first one.
+ - A label ID added to `aria-labelledby` by the field item is removed again if the label or the connected input element changes, also if the label ID is set by the application.
+ - If the input element already has an `aria-labelledby` of the application, the label ID is put in front of it, because that `aria-labelledby` would overrule the native connection via `for`.
+- ``
+ - Restore keyboard navigation for non-filterable Select.
+ - Restore predictable Enter, arrow key, Escape, and Tab behavior, with a visible focus indicator.
+ - Keep focus on the combobox and expose the active option to screen readers.
+ - Keep the clear action reachable with Tab and Shift+Tab and support clearing with Enter or Space without opening the options.
+ - Expose the clear action as a button named by `onClearanceText`, and as disabled if the Select is disabled.
+ - Prevent any interaction with the clear action of a disabled Select.
+ - Without `fill`, the wrapper element used for `wrapperProps` and test IDs is displayed inline, like the Select itself.
## [26.2.1] - 2026-11-02
diff --git a/src/components/Form/FieldItem.tsx b/src/components/Form/FieldItem.tsx
index 410d5275..87a900c8 100644
--- a/src/components/Form/FieldItem.tsx
+++ b/src/components/Form/FieldItem.tsx
@@ -33,7 +33,8 @@ export interface FieldItemProps extends React.HTMLAttributes, Te
/**
* Prevent the automatic connection of the field item parts.
* By default, label, input element, helper text and message are connected to each
- * other via `for`, `aria-labelledby` and `aria-describedby`.
+ * other via `for`, `aria-labelledby` and `aria-describedby`, and a click on the label focuses
+ * input elements that cannot be connected natively via `for`.
* Set it to `true` if the using application manages the accessibility attributes itself.
*/
preventAriaAttribution?: boolean;
@@ -41,12 +42,19 @@ export interface FieldItemProps extends React.HTMLAttributes, Te
/**
* Input elements that could be connected to the label and the help texts of the field item.
+ *
+ * Input elements that get their accessible name from their content, e.g. `button` or `output`,
+ * should refer to themselves via `aria-labelledby`, otherwise the connected label replaces their content as name.
+ * The field item puts its label ID in front of this self-reference, so label and content are both announced.
+ * This only works if `preventAriaAttribution` is not `true`. Otherwise, the connection between label
+ * and input element needs to be managed manually according to the WAI-ARIA specifications anyway.
*/
const connectableInputSelectors = [
- "input",
+ 'input:not([type="hidden"])',
"textarea",
"select",
- `.${eccgui}-select button`,
+ `.${eccgui}-select[role="combobox"]`,
+ `.${eccgui}-select:not([role="combobox"]) button`,
`.${eccgui}-codeeditor .cm-content`,
];
@@ -71,6 +79,9 @@ export const FieldItem = ({
...otherProps
}: FieldItemProps) => {
const fieldItemRef = React.useRef(null);
+ const connectedInputRef = React.useRef(undefined);
+ /** label ID that was added to `aria-labelledby` by the field item itself, it may be set by the application */
+ const labelledByRef = React.useRef<{ element: HTMLElement; id: string } | undefined>(undefined);
/** unique ID of this field item, used as suffix for the IDs of its parts */
const fieldItemId = React.useId().replace(/[^a-zA-Z0-9_-]/g, "");
@@ -100,7 +111,10 @@ export const FieldItem = ({
connectableInputSelectors.map((selector) => `.${eccgui}-fielditem__inputfields ${selector}`).join(", "),
),
);
- const inputElement = inputElements[0];
+ // an explicit `for` of the label selects the connected input element, otherwise the first one is used
+ const labelTarget = labelElement instanceof HTMLLabelElement ? labelElement.getAttribute("for") : null;
+ const inputElement =
+ inputElements.find((element) => labelTarget && element.id === labelTarget) ?? inputElements[0];
const helpElement = ownPart(fieldItem.querySelectorAll(`.${eccgui}-fielditem__helpertext`));
const messageElement = ownPart(fieldItem.querySelectorAll(`.${eccgui}-fielditem__message`));
@@ -114,16 +128,16 @@ export const FieldItem = ({
setMissingId(helpElement, `help_${fieldItemId}`);
setMissingId(messageElement, `message_${fieldItemId}`);
- if (!inputElement) {
- return;
- }
-
/**
* Update a list of ID references, only the IDs created by this field item are removed if their part is gone.
* References set by the using application always stay untouched.
*/
- const updateReferences = (attribute: string, parts: [HTMLElement | undefined, string][]) => {
- const references = (inputElement.getAttribute(attribute) ?? "").split(" ").filter(Boolean);
+ const updateReferences = (
+ element: HTMLElement,
+ attribute: string,
+ parts: [HTMLElement | undefined, string][],
+ ) => {
+ const references = (element.getAttribute(attribute) ?? "").split(" ").filter(Boolean);
parts.forEach(([element, ownId]) => {
if (element) {
if (!references.includes(element.id)) {
@@ -134,35 +148,83 @@ export const FieldItem = ({
}
});
if (references.length > 0) {
- inputElement.setAttribute(attribute, references.join(" "));
+ element.setAttribute(attribute, references.join(" "));
} else {
- inputElement.removeAttribute(attribute);
+ element.removeAttribute(attribute);
}
};
- if (labelElement instanceof HTMLLabelElement && labelableElements.includes(inputElement.tagName)) {
- // an already set `for` is only kept if it refers to a labelable input element of this field item
- const labelTarget = labelElement.getAttribute("for");
- const refersToOwnInput = inputElements.some(
- (element) => element.id === labelTarget && labelableElements.includes(element.tagName),
- );
- if (!refersToOwnInput) {
+ const previousInput = connectedInputRef.current;
+ if (previousInput && previousInput !== inputElement) {
+ if (previousInput.id === `input_${fieldItemId}`) {
+ previousInput.removeAttribute("id");
+ }
+ updateReferences(previousInput, "aria-labelledby", [[undefined, `label_${fieldItemId}`]]);
+ updateReferences(previousInput, "aria-describedby", [
+ [undefined, `message_${fieldItemId}`],
+ [undefined, `help_${fieldItemId}`],
+ ]);
+ }
+ connectedInputRef.current = inputElement;
+
+ // remove the label ID added before if that label is not connected to that input element anymore
+ const labelledBy = labelledByRef.current;
+ if (labelledBy && (labelledBy.element !== inputElement || labelledBy.id !== labelElement?.id)) {
+ updateReferences(labelledBy.element, "aria-labelledby", [[undefined, labelledBy.id]]);
+ labelledByRef.current = undefined;
+ }
+
+ if (!inputElement) {
+ return;
+ }
+
+ const connectsNatively =
+ labelElement instanceof HTMLLabelElement && labelableElements.includes(inputElement.tagName);
+
+ if (connectsNatively) {
+ // a `for` that does not refer to an input element of this field item is replaced
+ if (labelTarget !== inputElement.id) {
labelElement.setAttribute("for", inputElement.id);
}
- } else if (labelElement) {
+ } else if (labelElement instanceof HTMLLabelElement) {
// labels that are not `label` elements, e.g. of disabled field items, cannot use `for`
// the same is true for input elements that cannot be referenced by `for`
- if (!inputElement.getAttribute("aria-labelledby")) {
- inputElement.setAttribute("aria-labelledby", labelElement.id);
+ labelElement.removeAttribute("for");
+ }
+
+ if (labelElement) {
+ /** references of the using application, without the label ID added by the field item itself */
+ const ownLabelId = labelledByRef.current?.id;
+ const applicationReferences = (inputElement.getAttribute("aria-labelledby") ?? "")
+ .split(" ")
+ .filter((id) => id && id !== ownLabelId);
+ /**
+ * A native connection via `for` is overruled by an `aria-labelledby` of the application,
+ * so the label ID is put in front of those references then.
+ * This is also necessary for input elements that have an own content as name, e.g. `button` or `output`:
+ * a native label would replace that name, so they need to refer to themselves via `aria-labelledby`,
+ * e.g. the toggle button of ``, then the name consists of the field item label and their content.
+ * Otherwise `aria-labelledby` is only set if the application does not manage it itself.
+ */
+ const addLabelId = connectsNatively
+ ? applicationReferences.length > 0 && !applicationReferences.includes(labelElement.id)
+ : applicationReferences.length === 0;
+ if (addLabelId) {
+ inputElement.setAttribute("aria-labelledby", [labelElement.id, ...applicationReferences].join(" "));
+ labelledByRef.current = { element: inputElement, id: labelElement.id };
+ } else if (ownLabelId) {
+ updateReferences(inputElement, "aria-labelledby", [[undefined, ownLabelId]]);
+ labelledByRef.current = undefined;
}
} else {
- updateReferences("aria-labelledby", [[undefined, `label_${fieldItemId}`]]);
+ updateReferences(inputElement, "aria-labelledby", [[undefined, `label_${fieldItemId}`]]);
}
- updateReferences("aria-describedby", [
+ const descriptions: [HTMLElement | undefined, string][] = [
[messageElement, `message_${fieldItemId}`],
[helpElement, `help_${fieldItemId}`],
- ]);
+ ];
+ updateReferences(inputElement, "aria-describedby", descriptions);
}, [fieldItemId, preventAriaAttribution]);
React.useEffect(() => {
@@ -183,9 +245,37 @@ export const FieldItem = ({
return () => partsObserver.disconnect();
}, [connectParts, preventAriaAttribution]);
+ const handleLabelClick: React.MouseEventHandler = (event) => {
+ labelProps?.onClick?.(event);
+ if (event.defaultPrevented || disabled) {
+ return;
+ }
+ const labelElement = event.currentTarget;
+ if (labelElement instanceof HTMLLabelElement && labelElement.control) {
+ return;
+ }
+ if (!(event.target instanceof Node) || !labelElement.contains(event.target)) {
+ return;
+ }
+ const interactiveTarget =
+ event.target instanceof Element
+ ? event.target.closest(
+ "a[href], button, input, select, textarea, summary, [tabindex], [contenteditable=true], [role=button], [role=link]",
+ )
+ : null;
+ if (interactiveTarget && labelElement.contains(interactiveTarget)) {
+ return;
+ }
+ const control = connectedInputRef.current;
+ if (control && !control.matches(':disabled, [aria-disabled="true"], [contenteditable="false"]')) {
+ control.focus();
+ }
+ };
+
const label = (
diff --git a/src/components/Form/tests/FieldItem.test.tsx b/src/components/Form/tests/FieldItem.test.tsx
index 1ea4f683..bfdfb130 100644
--- a/src/components/Form/tests/FieldItem.test.tsx
+++ b/src/components/Form/tests/FieldItem.test.tsx
@@ -1,5 +1,7 @@
import React from "react";
-import { render, waitFor } from "@testing-library/react";
+import { createPortal } from "react-dom";
+import { render, screen, waitFor } from "@testing-library/react";
+import userEvent from "@testing-library/user-event";
import "@testing-library/jest-dom";
@@ -71,8 +73,9 @@ describe("FieldItem", () => {
expect(label).toHaveAttribute("for", input.id);
});
it("should keep a `for` that refers to another input element of the field item", () => {
- const { label } = renderFieldItem({
+ const { label, fieldItem } = renderFieldItem({
labelProps: { text: "Label text", htmlFor: "otherinput" },
+ helperText: "Help text",
children: (
<>
@@ -81,6 +84,45 @@ describe("FieldItem", () => {
),
});
expect(label).toHaveAttribute("for", "otherinput");
+ // the explicitly labelled input element is the connected one, also for the descriptions
+ expect(fieldItem.querySelector("#otherinput")).toHaveAccessibleDescription("Help text");
+ expect(fieldItem.querySelector("#custominput")).not.toHaveAttribute("aria-describedby");
+ });
+ it.each([
+ [
+ "a non-filterable Select",
+
+ Value
+
,
+ ],
+ [
+ "a code editor",
+
+
+
,
+ ],
+ ])("should keep a `for` that refers to an input element after %s", async (_, firstElement) => {
+ const user = userEvent.setup();
+ const { label, fieldItem } = renderFieldItem({
+ labelProps: { text: "Label text", htmlFor: "otherinput" },
+ helperText: "Help text",
+ children: (
+ <>
+ {firstElement}
+
+ >
+ ),
+ });
+ const otherInput = fieldItem.querySelector("#otherinput");
+
+ expect(label).toHaveAttribute("for", "otherinput");
+ expect(otherInput).toHaveAccessibleName("Label text");
+ expect(otherInput).toHaveAccessibleDescription("Help text");
+ expect(fieldItem.querySelector("[aria-labelledby]")).not.toBeInTheDocument();
+ expect(fieldItem.querySelector("[aria-describedby]")).toBe(otherInput);
+
+ await user.click(screen.getByText("Label text"));
+ expect(otherInput).toHaveFocus();
});
it("should replace a `for` that refers to an input element outside of the field item", () => {
const { container } = render(
@@ -146,6 +188,47 @@ describe("FieldItem", () => {
expect(label).toHaveAttribute("for", "custominput");
expect(input).toHaveAttribute("aria-describedby", `customhelp ${message.id} ${help.id}`);
});
+ it("should put the label ID in front of an `aria-labelledby` of the application", () => {
+ const { container } = render(
+ <>
+ Custom label
+
+
+
+ >,
+ );
+ const label = container.getElementsByClassName(`${eccgui}-fielditem__label`)[0] as HTMLElement;
+ const input = container.querySelector("input") as HTMLElement;
+ expect(label).toHaveAttribute("for", input.id);
+ expect(input).toHaveAttribute("aria-labelledby", `${label.id} customlabel`);
+ expect(input).toHaveAccessibleName("Label text Custom label");
+ });
+ it("should not add the label ID to an `aria-labelledby` of the application that contains it already", () => {
+ const { label, input } = renderFieldItem({
+ labelProps: { text: "Label text", id: "customlabel" },
+ children: ,
+ });
+ expect(label).toHaveAttribute("for", input.id);
+ expect(input).toHaveAttribute("aria-labelledby", "otherlabel customlabel");
+ });
+ it("should remove the added label ID if the application removes its `aria-labelledby`", () => {
+ const fieldItem = (labelledBy?: string) => (
+
+
+
+ );
+ const { container, rerender } = render(fieldItem("customlabel"));
+ const label = container.getElementsByClassName(`${eccgui}-fielditem__label`)[0] as HTMLElement;
+ const input = container.querySelector("input") as HTMLElement;
+ expect(input).toHaveAttribute("aria-labelledby", `${label.id} customlabel`);
+
+ rerender(fieldItem("otherlabel"));
+ expect(input).toHaveAttribute("aria-labelledby", `${label.id} otherlabel`);
+
+ rerender(fieldItem());
+ expect(input).not.toHaveAttribute("aria-labelledby");
+ expect(label).toHaveAttribute("for", input.id);
+ });
it("should not set IDs and connections if `preventAriaAttribution` is set", () => {
const { label, input, help, message } = renderFieldItem({
preventAriaAttribution: true,
@@ -185,6 +268,99 @@ describe("FieldItem", () => {
expect(label).toHaveAttribute("for", input.id);
});
});
+ it("connects the Select combobox instead of its inner button", () => {
+ const { fieldItem, label } = renderFieldItem({
+ labelProps: { text: "Filter by language" },
+ helperText: "Only matching values are shown.",
+ messageText: "Choose a language.",
+ children: (
+