An open source design system that's fully customizable and agent ready
TypeScript
fix(core): deterministic tab stop for unselected RadioList groups (#3390)
Cindy Zhang45c58e9ff5dd
diff --git a/.changeset/radiolist-focus-no-selection.md b/.changeset/radiolist-focus-no-selection.mdnew file mode 100644index 0000000000..a05bdd8242--- /dev/null+++ b/.changeset/radiolist-focus-no-selection.md@@ -0,0 +1,6 @@+---+'@astryxdesign/core': patch+---++[fix] RadioList: give an unselected radio group a deterministic keyboard tab stop. When focus enters a group with no selected value, the group now normalizes the entry point — first radio when tabbing forward, last radio when tabbing backward — matching the ARIA radio-group pattern. A selected value keeps its native tab stop, and moving between radios inside the group is never redirected. (#3390)+@cixzhangdiff --git a/packages/core/src/RadioList/RadioList.test.tsx b/packages/core/src/RadioList/RadioList.test.tsxindex 27409cfb3d..22c6e52e6a 100644--- a/packages/core/src/RadioList/RadioList.test.tsx+++ b/packages/core/src/RadioList/RadioList.test.tsx@@ -104,11 +104,7 @@ describe('RadioList', () => {const user = userEvent.setup();const handleChange = vi.fn();render(- <RadioList- label="Preference"- value=""- onChange={handleChange}- isDisabled>+ <RadioList label="Preference" value="" onChange={handleChange} isDisabled><RadioListItem label="Option A" value="a" /></RadioList>,);@@ -257,11 +253,7 @@ describe('RadioList', () => {it('supports data-testid on RadioListItem', () => {render(<RadioList label="Preference" value="" onChange={() => {}}>- <RadioListItem- label="Option A"- value="a"- data-testid="my-radio-item"- />+ <RadioListItem label="Option A" value="a" data-testid="my-radio-item" /></RadioList>,);expect(screen.getByTestId('my-radio-item')).toBeInTheDocument();@@ -340,4 +332,106 @@ describe('RadioList', () => {'true',);});++ describe('focus management (no-selection tab stop)', () => {+ it('keeps focus on the selected radio when a value is selected', () => {+ render(+ <RadioList label="Preference" value="b" onChange={() => {}}>+ <RadioListItem label="Option A" value="a" />+ <RadioListItem label="Option B" value="b" />+ <RadioListItem label="Option C" value="c" />+ </RadioList>,+ );+ const selected = screen.getByLabelText('Option B');+ // A selected value provides a deterministic native tab stop; focusing it+ // must not be redirected elsewhere.+ selected.focus();+ expect(selected).toHaveFocus();+ });++ it('redirects to the first radio when focus enters an unselected group forward', () => {+ render(+ <>+ <button type="button">before</button>+ <RadioList label="Preference" value="" onChange={() => {}}>+ <RadioListItem label="Option A" value="a" />+ <RadioListItem label="Option B" value="b" />+ <RadioListItem label="Option C" value="c" />+ </RadioList>+ </>,+ );+ const radios = screen.getAllByRole('radio');+ const outside = screen.getByText('before');+ outside.focus();+ // Forward entry: the browser lands on a leading radio; the group keeps the+ // first radio as the deterministic tab stop.+ radios[0].focus();+ expect(radios[0]).toHaveFocus();++ // Landing on a middle radio from outside is normalized to the first.+ outside.focus();+ radios[1].focus();+ expect(radios[0]).toHaveFocus();+ });++ it('redirects to the last radio when focus enters an unselected group backward', () => {+ render(+ <>+ <RadioList label="Preference" value="" onChange={() => {}}>+ <RadioListItem label="Option A" value="a" />+ <RadioListItem label="Option B" value="b" />+ <RadioListItem label="Option C" value="c" />+ </RadioList>+ <button type="button">after</button>+ </>,+ );+ const radios = screen.getAllByRole('radio');+ const outside = screen.getByText('after');+ outside.focus();+ // Backward (Shift+Tab) entry: the browser focuses the last radio; the+ // group keeps it as the deterministic tab stop rather than jumping away.+ radios[radios.length - 1].focus();+ expect(radios[radios.length - 1]).toHaveFocus();+ });++ it('does not hijack focus moving between radios within the group', () => {+ render(+ <RadioList label="Preference" value="" onChange={() => {}}>+ <RadioListItem label="Option A" value="a" />+ <RadioListItem label="Option B" value="b" />+ <RadioListItem label="Option C" value="c" />+ </RadioList>,+ );+ const radios = screen.getAllByRole('radio');+ // Enter the group from outside, then move to a middle radio as arrow-key+ // navigation would. Intra-group movement must not be redirected back.+ radios[0].focus();+ radios[1].focus();+ expect(radios[1]).toHaveFocus();+ radios[2].focus();+ expect(radios[2]).toHaveFocus();+ });++ it('skips disabled radios when choosing the deterministic tab stop', () => {+ render(+ <>+ <button type="button">before</button>+ <RadioList label="Preference" value="" onChange={() => {}}>+ <RadioListItem label="Option A" value="a" isDisabled />+ <RadioListItem label="Option B" value="b" />+ <RadioListItem label="Option C" value="c" />+ <RadioListItem label="Option D" value="d" />+ </RadioList>+ </>,+ );+ const outside = screen.getByText('before');+ const optionB = screen.getByLabelText('Option B');+ const optionC = screen.getByLabelText('Option C');+ // A middle enabled radio (C) entered from outside is normalized to the+ // first *enabled* radio (B) — the disabled Option A is skipped.+ outside.focus();+ optionC.focus();+ expect(optionB).toHaveFocus();+ });+ });});diff --git a/packages/core/src/RadioList/RadioList.tsx b/packages/core/src/RadioList/RadioList.tsxindex 4fe6933dd4..aab1b6faa1 100644--- a/packages/core/src/RadioList/RadioList.tsx+++ b/packages/core/src/RadioList/RadioList.tsx@@ -4,7 +4,7 @@/*** @file RadioList.tsx- * @input Uses React useId, createContext, ReactNode, Field, InputStatus+ * @input Uses React useId, useCallback, useRef, createContext, ReactNode, Field, InputStatus* @output Exports RadioList component, RadioListProps, RadioListContext* @position Core implementation; consumed by index.ts, tested by RadioList.test.tsx*@@ -16,7 +16,14 @@* - /packages/cli/templates/blocks/components/RadioList/ (showcase blocks)*/-import React, {createContext, useId, useMemo, type ReactNode} from 'react';+import React, {+ createContext,+ useCallback,+ useId,+ useMemo,+ useRef,+ type ReactNode,+} from 'react';import * as stylex from '@stylexjs/stylex';import {spacingVars} from '../theme/tokens.stylex';import {Field} from '../Field/Field';@@ -41,8 +48,9 @@ export interface RadioListContextValue {status?: InputStatus;}-export const RadioListContext =- createContext<RadioListContextValue | null>(null);+export const RadioListContext = createContext<RadioListContextValue | null>(+ null,+);RadioListContext.displayName = 'RadioListContext';const styles = stylex.create({@@ -178,11 +186,95 @@ export function RadioList({const descriptionID = useId();const statusMessageID = useId();+ const groupRef = useRef<HTMLDivElement>(null);+const contextValue = useMemo<RadioListContextValue>(() => ({name, value, onChange, isDisabled, isRequired, size, status}),[name, value, onChange, isDisabled, isRequired, size, status],);+ /**+ * Make the tab stop deterministic when a radio group has no selected value.+ *+ * Native `<input type="radio">` groups (same `name`) implement roving+ * tabindex for free: when a value is selected, that radio is the single tab+ * stop and receives focus, so no correction is needed there. But the ARIA+ * radio-group pattern (APG) also requires a deterministic tab stop when the+ * group has *no* selection — and browsers disagree here. Chrome, when+ * Shift+Tab moves focus backward into an unselected group, lands on the+ * *last* radio; forward Tab lands on the *first*. To keep the entry point+ * predictable we redirect focus:+ * - forward entry → first enabled radio (APG default)+ * - backward entry → last enabled radio (matches Chrome's backward tab)+ *+ * The redirect only runs when focus arrives from *outside* the group's own+ * radios (guarded via `relatedTarget` containment). Moving between radios+ * inside the group — arrow keys, clicks, programmatic focus of a sibling —+ * is never hijacked.+ */+ const handleFocus = useCallback(+ (e: React.FocusEvent<HTMLDivElement>) => {+ // Only correct the no-selection case; a selected value already provides+ // a deterministic native tab stop.+ if (value !== '') {+ return;+ }++ const group = groupRef.current;+ if (!group) {+ return;+ }++ // Ignore focus moving *within* the group. `relatedTarget` is the element+ // losing focus; if it was inside the group, this is intra-group movement+ // (arrow keys, clicking a sibling) and must not be hijacked. Some browsers+ // report a null `relatedTarget`; fall back to checking whether the group+ // already contained the active element before this focus landed.+ const relatedTarget = e.relatedTarget as Node | null;+ if (relatedTarget) {+ if (group.contains(relatedTarget)) {+ return;+ }+ } else if (+ document.activeElement &&+ document.activeElement !== e.target &&+ group.contains(document.activeElement)+ ) {+ return;+ }++ const radios = Array.from(+ group.querySelectorAll<HTMLInputElement>(+ 'input[type="radio"]:not([disabled])',+ ),+ );+ if (radios.length === 0) {+ return;+ }++ const target = e.target as HTMLElement;+ const targetIndex = radios.findIndex(radio => radio === target);+ // Only correct when the focus target is one of our enabled radios (not a+ // nested control such as end-content).+ if (targetIndex === -1) {+ return;+ }++ // Infer tab direction from which end the browser chose. On a backward+ // (Shift+Tab) entry into an unselected group, browsers focus the *last*+ // radio; keep it as the deterministic backward tab stop. Any other entry+ // (forward Tab, or a browser that lands mid-group) is normalized to the+ // *first* enabled radio, the APG default.+ const isBackwardEntry = targetIndex === radios.length - 1;+ const intended = isBackwardEntry ? radios[radios.length - 1] : radios[0];++ if (target !== intended) {+ intended.focus();+ }+ },+ [value],+ );+return (<Fieldref={ref}@@ -211,8 +303,10 @@ export function RadioList({className={className}style={style}><div+ ref={groupRef}role="radiogroup"aria-label={label}+ onFocus={handleFocus}aria-describedby={[description ? descriptionID : null,@@ -230,9 +324,7 @@ export function RadioList({orientation === 'vertical' ? styles.vertical : styles.horizontal,),)}>- <RadioListContext value={contextValue}>- {children}- </RadioListContext>+ <RadioListContext value={contextValue}>{children}</RadioListContext></div></Field>);