From cec9171ce41e823fe67d91a95de2352d35554827 Mon Sep 17 00:00:00 2001 From: Srividya Ramaswamy Date: Tue, 27 Oct 2026 13:31:22 -0700 Subject: [PATCH] fix(radio): expose native selection with the Select action Preserve externally owned state and original accessibility events. Use UI Automation RadioButton SelectionItem state, not an inappropriate Toggle pattern, and add runtime/native regressions. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> Copilot-Session: 4b66f3ef-85ac-4405-bd35-dcc167a077b1 --- .changeset/two-forks-double.md | 5 + .../components/src/components/radio/SPEC.md | 23 +++-- .../src/components/radio/radio.stories.tsx | 96 ++++++++++++++++++- .../src/components/radio/radio.test.tsx | 51 +++++++++- .../components/radio/spec/accessibility.md | 9 ++ .../src/components/radio/spec/interaction.md | 4 + .../src/components/radio/spec/source.json | 2 +- .../src/components/radio/spec/usage.md | 6 ++ .../src/components/radio/useRadio.ts | 8 +- .../agentic/components/tsconfig.stories.json | 1 + 10 files changed, 186 insertions(+), 19 deletions(-) create mode 100644 .changeset/two-forks-double.md diff --git a/.changeset/two-forks-double.md b/.changeset/two-forks-double.md new file mode 100644 index 0000000000..869d164553 --- /dev/null +++ b/.changeset/two-forks-double.md @@ -0,0 +1,5 @@ +--- +"@fluentui-react-native/components": patch +--- + +Declare Radio's native Select action and project caller-owned selection to UI Automation without synthesizing presses or changing the selected value. diff --git a/packages/agentic/components/src/components/radio/SPEC.md b/packages/agentic/components/src/components/radio/SPEC.md index 7c802ced4e..5ab41514b8 100644 --- a/packages/agentic/components/src/components/radio/SPEC.md +++ b/packages/agentic/components/src/components/radio/SPEC.md @@ -46,7 +46,8 @@ rather than explicitly hiding the indicator and text children. - **RAD-002:** Render the indicator, dot, label, and optional supporting text in the fixed order. - **RAD-003:** Render externally owned checked state without self-selection - and preserve press reporting. + and preserve press reporting. Declare the native Select action and project + the same owned value through native selection state. - **RAD-004:** Apply selection, disabled, hovered, pressed, and user-style precedence to the documented token bindings. - **RAD-005:** Expose radio semantics, accessible naming, disabled behavior, @@ -70,8 +71,10 @@ These hook options do not add new component props. Scenes require `ThemedRoot`. ## Platform behavior On Windows and macOS the root is an accessible React Native `Pressable` with -the `radio` role. UIA and AX receive its name, checked value, and disabled -value from the root. Disabled radios cannot be focused or activated. The +the `radio` role. UIA RadioButton exposes its value through SelectionItem, +not the Toggle pattern; the root projects its owned value to both React +Native checked and selected state. Native Select events are forwarded without +synthesizing presses or changing the caller's value. Disabled radios cannot be focused or activated. The indicator and text subtrees are explicitly hidden from assistive technology so the named root is the single announced element. @@ -96,10 +99,10 @@ implemented by the component that renders the radios. ## Conformance -| Requirement | Evidence | -| ----------- | -------------------------------------------------------- | -| RAD-001 | `radio.types.ts`, `useRadio.ts`, `radio.types.test.ts` | -| RAD-002 | `renderRadio.tsx`, `useRadioStyles.ts`, `radio.test.tsx` | -| RAD-003 | `useRadio.ts`, `radio.test.tsx`, `radio.stories.tsx` | -| RAD-004 | `radio.styles.ts`, `useRadioStyles.ts`, `radio.test.tsx` | -| RAD-005 | `useRadio.ts`, `useRadioStyles.ts`, `radio.test.tsx` | +| Requirement | Evidence | +| ----------- | ------------------------------------------------------------------------- | +| RAD-001 | `radio.types.ts`, `useRadio.ts`, `radio.types.test.ts` | +| RAD-002 | `renderRadio.tsx`, `useRadioStyles.ts`, `radio.test.tsx` | +| RAD-003 | `useRadio.ts`, `radio.test.tsx`, `radio.stories.tsx` | +| RAD-004 | `radio.styles.ts`, `useRadioStyles.ts`, `radio.test.tsx` | +| RAD-005 | `useRadio.ts`, `useRadioStyles.ts`, `radio.test.tsx`, `radio.stories.tsx` | diff --git a/packages/agentic/components/src/components/radio/radio.stories.tsx b/packages/agentic/components/src/components/radio/radio.stories.tsx index dc2501c7fb..2553e01fef 100644 --- a/packages/agentic/components/src/components/radio/radio.stories.tsx +++ b/packages/agentic/components/src/components/radio/radio.stories.tsx @@ -2,10 +2,14 @@ import { useState } from 'react'; import type { ReactNode } from 'react'; import { StyleSheet, Text, View } from 'react-native'; +import type { AccessibilityActionEvent } from 'react-native'; +import type { WdioStory } from '@fluentui-react-native/storybook-desktop/testing'; import type { Meta, StoryObj } from '@storybook/react-native'; import { Radio } from './radio'; +import type { RadioProps } from './radio.types'; +import { StoryStatus } from '../../common/StoryStatus.story-helpers'; type StoryGroupProps = { children: ReactNode; @@ -48,12 +52,100 @@ const meta: Meta = { export default meta; -type Story = StoryObj; +type Story = WdioStory>; export const Default: Story = {}; +export const NativeSelectionSemantics: Story = { + render: () => { + const Scene = () => { + const [actions, setActions] = useState(0); + const [presses, setPresses] = useState(0); + const [lastAction, setLastAction] = useState('none'); + const recordAction = (event: AccessibilityActionEvent) => { + setLastAction(event.nativeEvent.actionName); + setActions((value) => value + 1); + }; + return ( + + setPresses((value) => value + 1)} + /> + + setPresses((value) => value + 1)} + /> + {String(actions)} + {String(presses)} + {lastAction} + + ); + }; + return ; + }, + wdio: { + 'RAD-003 RAD-005 Win32 exposes native RadioButton selection, names and disabled state': async ({ browser, expect, platform, skip }) => { + if (platform !== 'win32') { + skip('This case qualifies Win32 UI Automation SelectionItem projection.'); + return; + } + for (const [id, name, selected] of [ + ['radio-native-off', 'Unselected option', false], + ['radio-native-on', 'Selected option', true], + ['radio-native-disabled', 'Disabled option', true], + ] as const) { + const radio = await browser.$(`~${id}`); + expect(await radio.getTagName()).toBe('radio'); + expect(await radio.getProperty('name')).toBe(name); + expect(await radio.getProperty('selected')).toBe(selected); + } + await expect(await browser.$('~radio-native-disabled')).toBeDisabled(); + }, + 'RAD-003 Win32 Select forwards once without self-selection or presses and disabled public activation rejects': async ({ + browser, + expect, + platform, + skip, + }) => { + if (platform !== 'win32') { + skip('This case qualifies Win32 UI Automation Select transport.'); + return; + } + const radio = await browser.$('~radio-native-off'); + const disabled = await browser.$('~radio-native-disabled'); + const actions = await browser.$('~radio-native-actions'); + const presses = await browser.$('~radio-native-presses'); + await expect(actions).toHaveAttribute('name', '0'); + await radio.click(); + await expect(actions).toHaveAttribute('name', '1'); + await expect(await browser.$('~radio-native-last-action')).toHaveAttribute('name', 'Select'); + await expect(presses).toHaveAttribute('name', '0'); + expect(await radio.getProperty('selected')).toBe(false); + let rejection: unknown; + try { + await disabled.click(); + } catch (error) { + rejection = error; + } + expect(rejection).toBeDefined(); + await expect(actions).toHaveAttribute('name', '1'); + await expect(presses).toHaveAttribute('name', '0'); + expect(await disabled.getProperty('selected')).toBe(true); + }, + }, +}; + export const Overview: Story = { - render: ({ label, secondaryText }) => ( + render: ({ label, secondaryText }: RadioProps) => ( diff --git a/packages/agentic/components/src/components/radio/radio.test.tsx b/packages/agentic/components/src/components/radio/radio.test.tsx index ce62aca4ac..db83b7fe2b 100644 --- a/packages/agentic/components/src/components/radio/radio.test.tsx +++ b/packages/agentic/components/src/components/radio/radio.test.tsx @@ -1,5 +1,5 @@ /** @jsxImportSource @fluentui-react-native/framework-base */ -import { StyleSheet } from 'react-native'; +import { Platform, StyleSheet } from 'react-native'; import type { ComponentProps } from 'react'; import { fireEvent } from '@testing-library/react-native'; @@ -46,7 +46,7 @@ describe('Radio', () => { const root = getRoot(component); expect(root.props.accessibilityLabel).toBe('Label'); - expect(root.props.accessibilityState).toEqual({ checked: false, disabled: false }); + expect(root.props.accessibilityState).toEqual({ checked: false, selected: false, disabled: false }); expect(root.props.focusable).toBe(true); expect(getText(component, 'Label')).toBeOnTheScreen(); expect(component.queryByText('Description')).toBeNull(); @@ -96,7 +96,7 @@ describe('Radio', () => { const component = await renderRadio({ label: 'Choice', selected: true }); const root = getRoot(component); - expect(root.props.accessibilityState).toEqual({ checked: true, disabled: false }); + expect(root.props.accessibilityState).toEqual({ checked: true, selected: true, disabled: false }); expect(StyleSheet.flatten(getTestId(component, 'radio-indicator').props.style).borderColor).toBe(tokens.strokeBrandLoud); expect(StyleSheet.flatten(getTestId(component, 'radio-dot').props.style)).toMatchObject({ backgroundColor: tokens.foregroundBrandPrimary, @@ -135,7 +135,7 @@ describe('Radio', () => { expect(root).toBeDisabled(); expect(root.props.focusable).toBe(false); - expect(root.props.accessibilityState).toEqual({ busy: true, checked: false, disabled: true }); + expect(root.props.accessibilityState).toEqual({ busy: true, checked: false, selected: false, disabled: true }); }); it('applies user styles last and allows constrained labels to shrink', async () => { @@ -168,4 +168,47 @@ describe('Radio', () => { importantForAccessibility: 'no-hide-descendants', }); }); + + it.each([ + ['win32', 'Select'], + ['windows', 'select'], + ['macos', 'Select'], + ] as const)('declares the native selection action on %s', async (platform, actionName) => { + const replacement = jest.replaceProperty(Platform, 'OS', platform as typeof Platform.OS); + try { + const component = await renderRadio({}); + expect(getRoot(component).props.accessibilityActions).toEqual([{ name: actionName }]); + } finally { + replacement.restore(); + } + }); + + it('preserves caller action labels and deduplicates selection declarations', async () => { + const component = await renderRadio({ + accessibilityActions: [{ name: 'Select', label: 'Choose option' }, { name: 'Select' }, { name: 'custom' }], + }); + expect(getRoot(component).props.accessibilityActions).toEqual([{ name: 'Select', label: 'Choose option' }, { name: 'custom' }]); + }); + + it.each([false, true])('owns native checked and selection state when selected is %s', async (selected) => { + const component = await renderRadio({ + selected, + accessibilityState: { busy: true, checked: !selected, selected: !selected }, + 'aria-checked': !selected, + 'aria-selected': !selected, + }); + expect(getRoot(component).props.accessibilityState).toEqual({ busy: true, checked: selected, selected, disabled: false }); + }); + + it.each([false, true])('forwards the original native action without pressing or selecting when disabled is %s', async (disabled) => { + const onAccessibilityAction = jest.fn(); + const onPress = jest.fn(); + const component = await renderRadio({ disabled, selected: false, onAccessibilityAction, onPress }); + const event = { nativeEvent: { actionName: 'Select' } }; + getRoot(component).props.onAccessibilityAction(event); + expect(onAccessibilityAction).toHaveBeenCalledTimes(1); + expect(onAccessibilityAction).toHaveBeenCalledWith(event); + expect(onPress).not.toHaveBeenCalled(); + expect(getRoot(component).props.accessibilityState).toMatchObject({ checked: false, selected: false }); + }); }); diff --git a/packages/agentic/components/src/components/radio/spec/accessibility.md b/packages/agentic/components/src/components/radio/spec/accessibility.md index e7b6edfa1a..200706ff97 100644 --- a/packages/agentic/components/src/components/radio/spec/accessibility.md +++ b/packages/agentic/components/src/components/radio/spec/accessibility.md @@ -14,6 +14,15 @@ value and cannot announce decorative descendants separately. The owning group must provide a group name and any positional or peer relationship information. +The root declares the platform's resolved Select action, preserving caller +actions and labels. UIA RadioButton uses SelectionItem.IsSelected rather than +Toggle.ToggleState, so the externally owned value also owns native selected +state and takes precedence over conflicting checked/selected ARIA aliases. +Native actions are forwarded unchanged, once, to onAccessibilityAction; Radio +does not synthesize onPress or select itself. An owner supporting native Select +updates its own value from that event. Other native endpoints require separate +qualification. + The focus target follows the [shared focus visual policy](../../../../references/higher-order-components.md#focus-visual-policy). Windows/macOS default to the native ring, with no custom subtree. Win32 defaults to a private `FocusRing` slot. Its configured ring Views remain mounted on the diff --git a/packages/agentic/components/src/components/radio/spec/interaction.md b/packages/agentic/components/src/components/radio/spec/interaction.md index e69be4305d..56757f0140 100644 --- a/packages/agentic/components/src/components/radio/spec/interaction.md +++ b/packages/agentic/components/src/components/radio/spec/interaction.md @@ -5,6 +5,10 @@ their corresponding caller handlers are forwarded. Disabled state prevents activation and focus. Pressing reports through `onPress`; Radio never changes its own selected value. +Native Select is a separate accessibility transport. The caller handles +onAccessibilityAction to update its owned value; the component only declares +the action and forwards the original event, without manufacturing onPress. + On Windows and macOS, native Pressable behavior activates a focused radio. Hover and press states change the token-derived colors. diff --git a/packages/agentic/components/src/components/radio/spec/source.json b/packages/agentic/components/src/components/radio/spec/source.json index 70ee7c04a2..b44eddca78 100644 --- a/packages/agentic/components/src/components/radio/spec/source.json +++ b/packages/agentic/components/src/components/radio/spec/source.json @@ -106,7 +106,7 @@ }, { "id": "RAD-005", - "evidence": ["useRadio.ts", "useRadioStyles.ts", "radio.test.tsx"] + "evidence": ["useRadio.ts", "useRadioStyles.ts", "radio.test.tsx", "radio.stories.tsx"] } ] } diff --git a/packages/agentic/components/src/components/radio/spec/usage.md b/packages/agentic/components/src/components/radio/spec/usage.md index bfb5429c91..40e6516584 100644 --- a/packages/agentic/components/src/components/radio/spec/usage.md +++ b/packages/agentic/components/src/components/radio/spec/usage.md @@ -18,6 +18,12 @@ component does not clear a selected peer or manage directional navigation, so the surrounding group must perform those duties. Use `disabled` only for an unavailable option, not to represent an unselected one. +To support native selection, handle onAccessibilityAction as well as onPress. +Compare its actionName with +resolveAccessibilityAction('select', Platform.OS).name and update the +group's owned value. Import the resolver from framework-base. Radio declares +the action; the caller must not synthesize a press. + ## Scene root Render the scene inside `ThemedRoot` so focus policy can query `useRootSettings`. diff --git a/packages/agentic/components/src/components/radio/useRadio.ts b/packages/agentic/components/src/components/radio/useRadio.ts index e1ded38796..f81d79fcda 100644 --- a/packages/agentic/components/src/components/radio/useRadio.ts +++ b/packages/agentic/components/src/components/radio/useRadio.ts @@ -1,6 +1,6 @@ -import { Pressable } from 'react-native'; +import { Platform, Pressable } from 'react-native'; -import { useFocusablePressable, useSlot } from '@fluentui-react-native/framework-base'; +import { resolveAccessibilityAction, useFocusablePressable, useSlot } from '@fluentui-react-native/framework-base'; import { useThemeState } from '@fluentui-react-native/design'; import { useFocusVisuals } from '../../common/useFocusVisuals'; @@ -27,14 +27,18 @@ export function useRadio_unstable(props: RadioProps): RadioState { const themeState = useThemeState(); const [pressableProps, pressableState, focusBinding] = useFocusablePressable({ ...rest, + accessibilityActions: resolveAccessibilityAction('select', Platform.OS, rest.accessibilityActions).accessibilityActions, accessibilityLabel: accessibilityLabel ?? label, accessibilityHint: accessibilityHint ?? (showSecondaryText ? secondaryText : undefined), accessibilityRole: 'radio', accessibilityState: { ...accessibilityState, checked: selected, + selected, disabled, }, + 'aria-checked': selected, + 'aria-selected': selected, accessible: rest.accessible ?? true, disabled, focusable: !disabled && (rest.focusable ?? true), diff --git a/packages/agentic/components/tsconfig.stories.json b/packages/agentic/components/tsconfig.stories.json index 3c3f82336e..9d45118dd0 100644 --- a/packages/agentic/components/tsconfig.stories.json +++ b/packages/agentic/components/tsconfig.stories.json @@ -17,6 +17,7 @@ "src/components/menu/menu.stories.tsx", "src/components/menu-button/menu-button.stories.tsx", "src/components/popover/popover.stories.tsx", + "src/components/radio/radio.stories.tsx", "src/components/skeleton/skeleton.stories.tsx", "src/components/spinner/spinner.stories.tsx", "src/components/switch/switch.stories.tsx",