Repository navigation
fix(macos): Fabric accessibility roles and state, and TextInput read-only and Tab-stop fixes - #3136
Merged
Merged
Conversation
+[RCTConvert accessibilityRoleFromTraits:useAriaMappings:] passed the whole array, rather than the current element, to the ARIA lookup, so array input never matched an ARIA role. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
…ityRole On macOS, RCTViewComponentView mapped only accessibilityTraits to a role. The C++ props convert just a few role strings to traits, so roles such as menuitem, option, tab, combobox and textbox reported AXUnknown. The role was also set on the component view rather than its accessibility element, so the field behind a TextInput never received it. Resolve the role the way Paper does: role with the ARIA table, then accessibilityRole with the legacy table, then the traits, and otherwise the element's default role. Write it to accessibilityElement. Add the missing legacy textbox mapping and an RNTester example. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Fabric ignored accessibilityState on macOS, so VoiceOver and automation reported disabled elements as enabled and never reported AXSelected or AXExpanded. Project the state, including the NotEnabled and Selected traits, onto the accessibility element. This replaces the trait-only accessibilityEnabled update, which wrote to the component view instead of the element. As in Paper, expose an attribute only when JS provides it: setting an NSAccessibility state makes AppKit advertise the attribute, so an element without expanded must not report AXExpanded. Add an RNTester example. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
…State.disabled
editable={false} disabled the single-line NSTextField, so read-only fields
could not be focused, selected or copied and reported AXEnabled = NO, while
accessibilityState.disabled did not disable the field at all.
- RCTUITextField: editable now only controls editing. Read-only fields stay
enabled, selectable and reachable with Tab.
- accessibilityState.disabled sets a new enabled property on the backing
text input on both renderers. RCTUITextView implements it for multiline
input: it refuses first responder and reports AXEnabled = NO.
- Paper: clear the previous state when accessibilityState is removed.
Disabled fields now use AppKit's disabled appearance; read-only fields no
longer do. Add an RNTester example.
Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
RCTTextInputComponentView and, for multiline input, RCTWrappedTextView only
host the editor but were in the key view loop, so each TextInput took two
Tab presses. TextInput's default focusable={true} also let the component
view become first responder.
Keep both wrappers out of the key view loop and the responder chain; focus()
already targets the editor. RNTester now recalculates its key view loop like
RCTAppDelegate, so Tab moves between views in the new example.
Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
… view Changing multiline or secureTextEntry, including on a recycled view, replaces the backing view and copies its accessibility role. An unset role reads back as AXUnknown, so the new NSTextField reported AXUnknown instead of AXTextField. Do not copy an unset role. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
7 tasks
Jason Morse (JasonVMo)
added a commit
that referenced
this pull request
Nov 10, 2026
<!-- Thanks for submitting a pull request! We appreciate you spending the time to work on these changes. Please provide enough information so that others can review your pull request. The four fields below are mandatory. --> <!-- This fork of react-native provides React Native for macOS for the community. It also contains some changes that are required for usage internal to Microsoft. We are working on reducing the diff between Facebook's public version of react-native and our microsoft/react-native-macos fork. Long term, we want this fork to only contain macOS concerns and have the other iOS and Android concerns contributed upstream. If you are making a new change then one of the following should be done: - Consider if it is possible to achieve the desired behavior without making a change to microsoft/react-native-macos. Often a change can be made in a layer above in facebook/react-native instead. - Create a corresponding PR against [facebook/react-native](https://github.com/facebook/react-native) **Note:** Ideally you would wait for Facebook feedback before submitting to Microsoft, since we want to ensure that this fork doesn't deviate from upstream. --> ## Summary: > Stacked on #3157. Review only the top commit (`fd13876983`). macOS accessibility in this fork depends on AppKit behavior that isn't obvious from headers. For example, a getter can return `AXUnknown` while AX clients see a different role. Paper and Fabric also resolve roles differently. Agents and contributors keep rediscovering these details, or they copy iOS patterns that don't hold on macOS. This PR records the verified behavior as knowledge topics. It also adds a repeatable way to check what VoiceOver and other AX clients actually see. New topics, loaded from a new `AGENTS.md` row for accessibility, focus, or Tab-order work: - **`a11y.appkit`:** AppKit AX behavior observed out of process. Rules: - Never copy an unset role. - Read a control's default role from its cell. - Gate state attributes. - Target the AX element. - Verify out of process. - **`a11y.roles`:** Role resolution in Paper and in Fabric, side by side. Rules: - Resolve `role`, then `accessibilityRole`, then the element's default role. - Restore the default role when both props are unset. - Don't import Paper's `RCTConvert` into Fabric. - **`a11y.state`:** How `accessibilityState` maps to AX attributes and value words. Rules: - Stop advertising state that's been removed. - Advertise `AXPress` only when the element handles it. - **`a11y.text-input`:** `editable={false}` semantics on every platform, plus the single-line (`RCTUITextField`) and multiline (`RCTWrappedTextView`) backings. - **`a11y.keyboard`:** `focusable`, first responder, and the key view loop, including why a Fabric TextInput takes two Tab stops on `main`. - **`testing.ax-probes`:** A procedure with a small Swift AX probe. It dumps elements by `testID`, reports focus, and clicks Fabric views, all driven with `osascript` keys. The topics state facts and the open questions in #3136 without recommending how to resolve them. They watch #3136, so they'll be updated when it lands. This PR also corrects `testing.rntester-macos`. `yarn start` fails under the repository's `nodeLinker: pnpm`, because Yarn resolves the `react-native-macos` binary under `.yarn/__virtual__`, which the pnpm linker never creates. Running `cli.js` directly without `NODE_PATH` starts Metro without its `/status` route, so the app reports "No script URL provided". The topic now gives a command that works. Knowledge files only, with no product code changes, so there's no corresponding facebook/react-native PR. ## Test Plan: Environment: macOS 27.2 (26B123), Xcode 26.4.1, Node 24.18.0. Run at `fd13876983`. **Knowledge checks (the steps CI runs):** | Command | Result | | --- | --- | | `node .agents/knowledge/tools/knowledge.mts check --ci` | Passed: `26 files checked: 0 errors, 0 warnings.` | | `node --test .agents/knowledge/tools/knowledge.test.mts` | Passed: 21 pass, 0 fail | | `yarn markdownlint-cli2 --no-globs AGENTS.md ".agents/knowledge/**/*.md" ".claude/skills/rnmacos-*/**/*.md" .github/copilot-instructions.md` | Passed: `Summary: 0 error(s)` | | `yarn format-check` | Passed (exit 0) | **Fact verification:** - Checked every code claim against `main`. The `asserts` front matter keeps key lines tied to source, and I confirmed it's enforced: a deliberately broken assert produced a warning. - Verified AppKit claims with the probe against small standalone AppKit apps: `NSView`, `NSTextField`, and `NSTextView`, before and after setting roles and state. **Procedure verification in RNTester-macOS on `main`:** | Step | Result | | --- | --- | | `RCT_NEW_ARCH_ENABLED=1 pod install` (Homebrew CocoaPods 1.17.0; local Ruby couldn't `bundle install`), then `.ado/scripts/xcodebuild.sh packages/rn-tester/RNTesterPods.xcworkspace macosx Debug RNTester-macOS build` | `Build Succeeded` | | `NODE_PATH="$PWD/node_modules" node ../react-native/cli.js start` from `packages/rn-tester`, then `curl localhost:8081/status` | `packager-status:running` (without `NODE_PATH`: `Cannot GET /status`) | | `testing.ax-probes` procedure, run verbatim from a fresh launch | Navigated APIs → Accessibility; `example_search role=AXTextField enabled=1` | | `ax dump` of the TextInput module | Both `secureTextEntry` inputs report `role=AXUnknown enabled=1`, which matches the `RCTCopyBackedTextInput` fact | | Tab from `example_search` in the TextInput module, with `autorecalculatesKeyViewLoop = YES` added to RNTester's `AppDelegate` locally (not committed) | Focus alternates `AXScrollArea`, `AXTextField`, `AXScrollArea`, `AXTextField`…; Shift-Tab returns to `AXScrollArea`. This matches `a11y.keyboard` | | Same Tab test without that change | Focus stays on `example_search`, which matches the `a11y.keyboard.test-recalculated-loop` rule |
…into user/jasonvmo/a11y-fixes
- Fabric: resolve role mappings locally instead of depending on Paper's RCTConvert, and document why role, accessibilityRole and accessibilityTraits are compared separately. - RCTUITextView: replace the early return in -setEnabled: with a guarded body. - TextInput: document the desktop read-only behavior and shorten the Tab-stop comment. - RNTester: rename the macOS role example's variables to make its macOS-specific intent clear. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Saad Najmi (Saadnajmi)
approved these changes
Nov 12, 2026
This was referenced Nov 12, 2026
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary:
On macOS, Fabric loses most accessibility information that Paper exposes, and TextInput handles focus and read-only state incorrectly:
role/accessibilityRolevalues such asmenuitem,option,tab,comboboxandtextboxreportAXUnknown.accessibilityStatedisabled,selectedandexpandednever reach AppKit.editable={false}is disabled instead of read-only. It can't be focused or selected, whileaccessibilityState.disableddoesn't disable it at all.FluentUI React Native works around these with a Yarn patch on 0.81.9 (microsoft/fluentui-react-native#4386). This PR fixes them on
main. All changes are macOS-only and tagged. The 0.81 backport and the Paper checks that can't run onmainare tracked in #3135.Each commit is a separate fix and builds on its own:
RCTConvert: the ARIA path for array input passed the whole array instead of each element.rolewith the ARIA table, thenaccessibilityRolewith the legacy table, then the traits, then the element's default. Write it toaccessibilityElement, so TextInput's backing field receives it. Also add the missing legacytextboxmapping.disabled,selectedandexpanded, including the NotEnabled and Selected traits, onto the accessibility element. As in Paper,isAccessibilitySelectorAllowed:exposes an attribute only when JS provides it, so a view withoutexpandeddoesn't report AXExpanded.editableonly controls editing; read-only fields stay enabled, selectable and reachable with Tab.accessibilityState.disableddrives a newenabledproperty on the backing input on both renderers.RCTUITextViewimplements it for multiline. On Paper, removing theaccessibilityStateprop now clears the previous state.RCTWrappedTextViewstay out of the key-view loop. The component view also refuses first responder, since TextInput defaultsfocusableto true. RNTester-macOS now recalculates its key-view loop, matchingRCTAppDelegate.AXUnknown. The new field then reportedAXUnknowninstead ofAXTextField.New RNTester examples cover each fix: Accessibility "Roles from role and accessibilityRole" and "Disabled, selected and expanded state"; TextInput "Read-only and disabled" and "Tab stops".
Follow-ups outside this PR:
roleoraccessibilityRolekeeps the previous value, because sharedAccessibilityPropsparsing treatsnullas unset.role="none"restores the default role.accessibilityValueoverride still appends "expanded", which may make VoiceOver say it twice now that AXExpanded is exposed.checkedandbusyaren't projected, and Fabric views expose no AXPress action.Test Plan:
RCT_NEW_ARCH_ENABLED=1 pod install(inpackages/rn-tester)xcodebuild -workspace packages/rn-tester/RNTesterPods.xcworkspace -sdk macosx -configuration Debug -scheme RNTester-macOS CODE_SIGNING_ALLOWED=NO buildxcodebuild -workspace packages/rn-tester/RNTesterPods.xcworkspace -sdk iphonesimulator -configuration Debug -scheme RNTester -destination 'generic/platform=iOS Simulator' CODE_SIGNING_ALLOWED=NO buildyarn flow checkyarn exec eslint --max-warnings 0andyarn exec prettier --checkon the two example filesI ran the new examples in RNTester-macOS (new architecture) and inspected them from a separate process with
AXUIElementCopyAttributeValue. Both runs used the RNTester key-view change, so Tab can move between views.mainrole="menuitem"/"option"/"tab"AXUnknownAXMenuItem/AXStaticText/AXRadioButtonaccessibilityRole="textbox"AXTextField"none"AXUnknown"none"restoresAXUnknownrole="combobox", then"none"AXUnknownAXComboBox, thenAXTextFielddisabled,selected,expandedon and offexpandededitable={false}accessibilityState={{disabled: true}}, single-line and multilineAXUnknownAXTextFieldNot run:
maindoesn't build the legacy architecture; tracked in Backport macOS accessibility and TextInput fixes to 0.81-stable, with Paper validation #3135.RNTester-macOSUnitTestsalready fails to compile onmain(RCTImageLoaderTests.musesUIImage).