Skip to content
Open
Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
29 commits
Select commit Hold shift + click to select a range
d1494dd
Select: Fix accesibility (label combobox) and restore keyboard naviga…
andreas-schultz Oct 2, 2026
2ee5001
Improve Select screen reader announcements
andreas-schultz Oct 5, 2026
90f8a9a
Merge remote-tracking branch 'origin/develop' into fix/selectAccessib…
haschek Oct 30, 2026
6d754c3
Merge remote-tracking branch 'origin/develop' into fix/selectAccessib…
haschek Nov 2, 2026
7d7c807
Fix FieldItem control discovery for Select
andreas-schultz Nov 5, 2026
4146ab4
Fix Select keyboard navigation and FieldItem label focus
andreas-schultz Nov 5, 2026
3870dac
fix inline mode after wrapper element is used by default all the time
haschek Nov 10, 2026
bcc1ace
use FieldSet und fix options (remove empty)
haschek Nov 10, 2026
cb4ad77
move combobox condition from FieldItem to Select
haschek Nov 10, 2026
e919ea8
Use non-focusable accessible target in combobox and improve a11y for …
haschek Nov 11, 2026
73dc516
fix option rendering in stories
haschek Nov 11, 2026
109bd85
do not overwrite manual display settings
haschek Nov 11, 2026
6c5bb87
respect explicitely assigned for attribute if tha target is child of …
haschek Nov 11, 2026
a251711
Merge remote-tracking branch 'origin/develop' into fix/selectAccessib…
haschek Nov 11, 2026
2ae76e1
Merge remote-tracking branch 'origin/develop' into fix/selectAccessib…
haschek Nov 11, 2026
5dbec22
Merge remote-tracking branch 'origin/fix/selectAccessibility-CMEM-815…
haschek Nov 11, 2026
e9e542e
using Space on combobox does not scroll the page anymore
haschek Nov 11, 2026
2df07cd
check for internal re-renderings of children and react with updates
haschek Nov 11, 2026
3fc03cd
only refer changes made in comparison to develop
haschek Nov 11, 2026
a969989
document other changes
haschek Nov 11, 2026
afdf564
set always an accessible label as fallback for empty clearance texts
haschek Nov 11, 2026
cbe4047
Merge pull request #442 from eccenca/fix/selectAccessibility-CMEM-815…
andreas-schultz Nov 11, 2026
071183a
put always the label reference into an existing labelledby on the tar…
haschek Nov 13, 2026
0eaeedf
improve description of preventAriaAttribution and set own label click…
haschek Nov 13, 2026
8c29d0b
improve documentation regarding buttons as targets
haschek Nov 13, 2026
b661b0b
remove wrong info
haschek Nov 13, 2026
48a7cd5
Document custom item creation in Select
andreas-schultz Nov 16, 2026
afd0d6e
Merge remote-tracking branch 'origin/develop' into fix/selectAccessib…
haschek Nov 17, 2026
0e8312d
Keep Select story option semantics on the active descendant
andreas-schultz Nov 17, 2026
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
17 changes: 17 additions & 0 deletions CHANGELOG.md
Original file line number Diff line number Diff line change
Expand Up @@ -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 `<Menu />` and used for `aria-haspopup` of the toggler
- `<MultiSuggestField />`
- 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
- `<Select />`
- 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

Expand All @@ -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
- `<FieldItem />`
- 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`.
- `<Select />`
- 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

Expand Down
140 changes: 115 additions & 25 deletions src/components/Form/FieldItem.tsx
Original file line number Diff line number Diff line change
Expand Up @@ -33,20 +33,28 @@ export interface FieldItemProps extends React.HTMLAttributes<HTMLDivElement>, 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;
}

/**
* 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`,
];

Expand All @@ -71,6 +79,9 @@ export const FieldItem = ({
...otherProps
}: FieldItemProps) => {
const fieldItemRef = React.useRef<HTMLDivElement>(null);
const connectedInputRef = React.useRef<HTMLElement | undefined>(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, "");

Expand Down Expand Up @@ -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<HTMLElement>(`.${eccgui}-fielditem__helpertext`));
const messageElement = ownPart(fieldItem.querySelectorAll<HTMLElement>(`.${eccgui}-fielditem__message`));

Expand All @@ -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)) {
Expand All @@ -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 `<Select />`, 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(() => {
Expand All @@ -183,9 +245,37 @@ export const FieldItem = ({
return () => partsObserver.disconnect();
}, [connectParts, preventAriaAttribution]);

const handleLabelClick: React.MouseEventHandler<HTMLLabelElement> = (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 = (
<Label
{...labelProps}
onClick={preventAriaAttribution ? labelProps?.onClick : handleLabelClick}
className={`${eccgui}-fielditem__label` + (labelProps?.className ? " " + labelProps.className : "")}
disabled={disabled}
/>
Expand Down
Loading
Loading