An open source design system that's fully customizable and agent ready
TypeScript
fix(radiolist): label the group via aria-labelledby, drop orphaned htmlFor (forms-14) (#3453)
Cindy Zhanga8eb271eebaa
diff --git a/.changeset/radiolist-label-association.md b/.changeset/radiolist-label-association.mdnew file mode 100644index 0000000000..c6758eb571--- /dev/null+++ b/.changeset/radiolist-label-association.md@@ -0,0 +1,6 @@+---+'@astryxdesign/core': patch+---++[fix] RadioList: the group is now named via `aria-labelledby` pointing at the field label element, and the label no longer carries an orphaned `htmlFor` (it pointed at an id no radio used, so clicking it did nothing and the group was double-labeled). `Field`/`FieldLabel` gain optional `labelID` and `isGroupLabel` props to support grouping controls (#3343).+@cixzhangdiff --git a/packages/core/src/Field/Field.test.tsx b/packages/core/src/Field/Field.test.tsxindex 9def555302..b7c309dc9c 100644--- a/packages/core/src/Field/Field.test.tsx+++ b/packages/core/src/Field/Field.test.tsx@@ -93,6 +93,38 @@ describe('Field', () => {expect(label).toBeVisible();});+ it('renders a single-control label as a <label> with htmlFor', () => {+ render(+ <Field label="Email" inputID="email-input">+ <input id="email-input" />+ </Field>,+ );+ const labelEl = screen.getByText('Email');+ expect(labelEl.tagName).toBe('LABEL');+ expect(labelEl).toHaveAttribute('for', 'email-input');+ });++ it('renders a group label as a <span> (not <label>) with no htmlFor', () => {+ render(+ <Field+ label="Plan"+ inputID="plan-group"+ labelElementID="plan-label"+ isGroupLabel>+ <div role="radiogroup" aria-labelledby="plan-label" />+ </Field>,+ );+ const labelEl = screen.getByText('Plan');+ // A group's accessible-name element must not be a literal <label>.+ expect(labelEl.tagName).toBe('SPAN');+ expect(labelEl.closest('label')).toBeNull();+ expect(labelEl).not.toHaveAttribute('for');+ // labelElementID is applied to the label element and referenced by the group.+ expect(labelEl).toHaveAttribute('id', 'plan-label');+ const group = screen.getByRole('radiogroup', {name: 'Plan'});+ expect(group.getAttribute('aria-labelledby')).toBe(labelEl.id);+ });+it('forwards ref correctly', () => {const ref = vi.fn();render(diff --git a/packages/core/src/Field/Field.tsx b/packages/core/src/Field/Field.tsxindex 368f5c8728..5247b3bced 100644--- a/packages/core/src/Field/Field.tsx+++ b/packages/core/src/Field/Field.tsx@@ -99,9 +99,26 @@ export interface FieldProps extends Omit<*/description?: string;/**- * ID for the input element (used for label's htmlFor attribute).+ * ID of the input element this label points AT (used as the label's+ * `htmlFor`). This is the id of the *control*, not of the label element —+ * see `labelElementID` for the latter.*/inputID: string;+ /**+ * The `id` applied TO the label element itself (distinct from `inputID`,+ * which is the control the label points at). A grouping control+ * (radiogroup, checkbox group) references this via `aria-labelledby` to take+ * the label as its accessible name. Pair with `isGroupLabel`.+ */+ labelElementID?: string;+ /**+ * When the field wraps a group of controls rather than a single input, set+ * this so the label renders as a non-`<label>` element (a `<span>`): a+ * `<label>` semantically names one control and can't be associated with a+ * group. Pair with `labelElementID` + `aria-labelledby` on the group.+ * @default false+ */+ isGroupLabel?: boolean;/*** ID for the description element (use for aria-describedby on the input).*/@@ -172,6 +189,8 @@ export function Field({isLabelHidden = false,description,inputID,+ labelElementID,+ isGroupLabel = false,descriptionID,isOptional = false,isRequired = false,@@ -206,6 +225,8 @@ export function Field({<FieldLabellabel={label}inputID={inputID}+ labelElementID={labelElementID}+ isGroupLabel={isGroupLabel}isLabelHidden={isLabelHidden}isDisabled={isDisabled}isOptional={isOptional}@@ -245,10 +266,7 @@ export function Field({<div {...stylex.props(styles.horizontalLabelAlign)}>{labelNode}</div><div {...stylex.props(styles.inputStatusWrapper)}>{description && (- <Text- type="supporting"- display="block"- id={resolvedDescriptionID}>+ <Text type="supporting" display="block" id={resolvedDescriptionID}>{description}</Text>)}diff --git a/packages/core/src/Field/FieldLabel.tsx b/packages/core/src/Field/FieldLabel.tsxindex 49fd029492..04f776db6a 100644--- a/packages/core/src/Field/FieldLabel.tsx+++ b/packages/core/src/Field/FieldLabel.tsx@@ -82,9 +82,28 @@ export interface FieldLabelProps extends BaseProps<HTMLLabelElement> {*/label: string;/**- * ID of the input element this label is for.+ * ID of the input element this label points AT (rendered as `htmlFor` on the+ * label). This is *not* the id of the label element itself — see+ * `labelElementID` for that.*/inputID: string;+ /**+ * The `id` applied TO the label element itself (not the element it points+ * at — that's `inputID`). A grouping control (e.g. `role="radiogroup"`) can+ * reference this via `aria-labelledby` to take the label as its accessible+ * name.+ */+ labelElementID?: string;+ /**+ * When true, the field wraps a *group* of controls (e.g. a radiogroup)+ * rather than a single input. In that case the label is rendered as a+ * `<span>` instead of a `<label>` — a `<label>` semantically names one form+ * control and can't be associated with a group, so it must not be a literal+ * label element. The group takes the label as its name via+ * `labelElementID` + `aria-labelledby`.+ * @default false+ */+ isGroupLabel?: boolean;/*** Whether to visually hide the label and description (still accessible* to screen readers). When hidden, the entire label group is rendered@@ -142,6 +161,8 @@ export interface FieldLabelProps extends BaseProps<HTMLLabelElement> {export function FieldLabel({label,inputID,+ labelElementID,+ isGroupLabel = false,isLabelHidden = false,isDisabled = false,isOptional = false,@@ -154,11 +175,38 @@ export function FieldLabel({}: FieldLabelProps) {const statusText = isOptional ? 'Optional' : isRequired ? 'Required' : null;+ // A group label (e.g. for a radiogroup) must not be a literal `<label>`+ // element: a `<label>` semantically names a single form control and can't be+ // associated with a group. Render it as a `<span>` instead, keeping all the+ // label styling and slots. The group references it via `aria-labelledby`.+ const LabelElement = isGroupLabel ? 'span' : 'label';++ const labelContent = (+ <>+ {labelIcon && renderIconSlot(labelIcon, {size: 'sm', color: 'inherit'})}+ {label}+ {statusText && (+ <span {...stylex.props(styles.optionalRequired)}>+ <span aria-hidden="true"> ∙ </span>+ {statusText}+ </span>+ )}+ {labelTooltip && (+ <Tooltip content={labelTooltip} placement="above">+ <Icon icon="info" size="sm" color="inherit" />+ </Tooltip>+ )}+ </>+ );+return (<>- <label+ <LabelElementref={ref}- htmlFor={inputID}+ id={labelElementID}+ // `htmlFor` only applies to a real `<label>` associating with a single+ // control; a group label (span) has no `htmlFor`.+ htmlFor={isGroupLabel ? undefined : inputID}{...mergeProps(themeProps('field-label'),stylex.props(@@ -167,20 +215,8 @@ export function FieldLabel({isLabelHidden && styles.srOnly,),)}>- {labelIcon && renderIconSlot(labelIcon, {size: 'sm', color: 'inherit'})}- {label}- {statusText && (- <span {...stylex.props(styles.optionalRequired)}>- <span aria-hidden="true"> ∙ </span>- {statusText}- </span>- )}- {labelTooltip && (- <Tooltip content={labelTooltip} placement="above">- <Icon icon="info" size="sm" color="inherit" />- </Tooltip>- )}- </label>+ {labelContent}+ </LabelElement>{description && (<spanid={descriptionID}diff --git a/packages/core/src/RadioList/RadioList.test.tsx b/packages/core/src/RadioList/RadioList.test.tsxindex 22c6e52e6a..7e8f58987c 100644--- a/packages/core/src/RadioList/RadioList.test.tsx+++ b/packages/core/src/RadioList/RadioList.test.tsx@@ -271,11 +271,32 @@ describe('RadioList', () => {);const label = screen.getByText('Hidden label');expect(label).toBeInTheDocument();- // The radiogroup should still be labeled- expect(screen.getByRole('radiogroup')).toHaveAttribute(- 'aria-label',- 'Hidden label',+ // The radiogroup is named by the label element via aria-labelledby (not a+ // duplicated aria-label), so its accessible name is still "Hidden label".+ expect(+ screen.getByRole('radiogroup', {name: 'Hidden label'}),+ ).toBeInTheDocument();+ expect(screen.getByRole('radiogroup')).toHaveAttribute('aria-labelledby');+ expect(screen.getByRole('radiogroup')).not.toHaveAttribute('aria-label');+ });++ it('renders the group label as a span, not a label element (forms-14)', () => {+ render(+ <RadioList label="Plan" value="" onChange={() => {}}>+ <RadioListItem label="Free" value="free" />+ <RadioListItem label="Pro" value="pro" />+ </RadioList>,);+ // A radiogroup's accessible name must not come from a literal `<label>`+ // element — a `<label>` names a single control and can't be associated+ // with a group. It is rendered as a `<span>` and referenced via+ // aria-labelledby (with no orphaned htmlFor).+ const labelEl = screen.getByText('Plan');+ expect(labelEl.tagName).toBe('SPAN');+ expect(labelEl.closest('label')).toBeNull();+ expect(labelEl).not.toHaveAttribute('for');+ const group = screen.getByRole('radiogroup', {name: 'Plan'});+ expect(group.getAttribute('aria-labelledby')).toBe(labelEl.id);});it('renders description on items', () => {diff --git a/packages/core/src/RadioList/RadioList.tsx b/packages/core/src/RadioList/RadioList.tsxindex aab1b6faa1..5d864f1dfd 100644--- a/packages/core/src/RadioList/RadioList.tsx+++ b/packages/core/src/RadioList/RadioList.tsx@@ -183,6 +183,7 @@ export function RadioList({}: RadioListProps) {const name = useId();const inputID = useId();+ const labelElementID = useId();const descriptionID = useId();const statusMessageID = useId();@@ -283,6 +284,8 @@ export function RadioList({isLabelHidden={isLabelHidden}description={description}inputID={inputID}+ labelElementID={labelElementID}+ isGroupLabeldescriptionID={description ? descriptionID : undefined}isOptional={isOptional}isRequired={isRequired}@@ -305,7 +308,7 @@ export function RadioList({<divref={groupRef}role="radiogroup"- aria-label={label}+ aria-labelledby={labelElementID}onFocus={handleFocus}aria-describedby={[