Merge branch 'main' into esm-and-eslint-flat-config

Author: Simek

docs/_experimental-api-warning.mdx

@@ -0,0 +1,5 @@
+:::important Experimental 🧪
+
+**This API is experimental.** Experimental APIs may contain bugs and are likely to change in a future version of React Native. Don't use them in production.
+
+:::

docs/_getting-started-linux-android.md

@@ -6,7 +6,7 @@ While you can use any editor of your choice to develop your app, you will need t
 
 <h3>Node</h3>
 
-Follow the [installation instructions for your Linux distribution](https://nodejs.org/en/download/package-manager/) to install Node 18.18 or newer.
+Follow the [installation instructions for your Linux distribution](https://nodejs.org/en/download/package-manager/) to install Node 20.19.4 or newer.
 
 <h3>Java Development Kit</h3>
 
@@ -26,7 +26,9 @@ Setting up your development environment can be somewhat tedious if you're new to
 
 Then, click "Next" to install all of these components.
 
-> If the checkboxes are grayed out, you will have a chance to install these components later on.
+:::note
+If the checkboxes are grayed out, you will have a chance to install these components later on.
+:::
 
 Once setup has finalized and you're presented with the Welcome screen, proceed to the next step.
 
@@ -36,7 +38,9 @@ Android Studio installs the latest Android SDK by default. Building a React Nati
 
 To do that, open Android Studio, click on "Configure" button and select "SDK Manager".
 
-> The SDK Manager can also be found within the Android Studio "Settings" dialog, under **Languages & Frameworks** → **Android SDK**.
+:::tip
+The SDK Manager can also be found within the Android Studio "Settings" dialog, under **Languages & Frameworks** → **Android SDK**.
+:::
 
 Select the "SDK Platforms" tab from within the SDK Manager, then check the box next to "Show Package Details" in the bottom right corner. Look for and expand the `Android 15 (VanillaIceCream)` entry, then make sure the following items are checked:
 
@@ -59,17 +63,23 @@ export PATH=$PATH:$ANDROID_HOME/emulator
 export PATH=$PATH:$ANDROID_HOME/platform-tools
 ```
 
-> `.bash_profile` is specific to `bash`. If you're using another shell, you will need to edit the appropriate shell-specific config file.
+:::note
+`.bash_profile` is specific to `bash`. If you're using another shell, you will need to edit the appropriate shell-specific config file.
+:::
 
 Type `source $HOME/.bash_profile` for `bash` or `source $HOME/.zprofile` to load the config into your current shell. Verify that ANDROID_HOME has been set by running `echo $ANDROID_HOME` and the appropriate directories have been added to your path by running `echo $PATH`.
 
-> Please make sure you use the correct Android SDK path. You can find the actual location of the SDK in the Android Studio "Settings" dialog, under **Languages & Frameworks** → **Android SDK**.
+:::note
+Please make sure you use the correct Android SDK path. You can find the actual location of the SDK in the Android Studio "Settings" dialog, under **Languages & Frameworks** → **Android SDK**.
+:::
 
 <h3>Watchman</h3>
 
 Follow the [Watchman installation guide](https://facebook.github.io/watchman/docs/install#buildinstall) to compile and install Watchman from source.
 
-> [Watchman](https://facebook.github.io/watchman/docs/install) is a tool by Facebook for watching changes in the filesystem. It is highly recommended you install it for better performance and increased compatibility in certain edge cases (translation: you may be able to get by without installing this, but your mileage may vary; installing this now may save you from a headache later).
+:::info
+[Watchman](https://facebook.github.io/watchman/docs/install) is a tool by Facebook for watching changes in the filesystem. It is highly recommended you install it for better performance and increased compatibility in certain edge cases (translation: you may be able to get by without installing this, but your mileage may vary; installing this now may save you from a headache later).
+:::
 
 <h2>Preparing the Android device</h2>
 
@@ -89,7 +99,9 @@ If you use Android Studio to open `./AwesomeProject/android`, you can see the li
 
 If you have recently installed Android Studio, you will likely need to [create a new AVD](https://developer.android.com/studio/run/managing-avds.html). Select "Create Virtual Device...", then pick any Phone from the list and click "Next", then select the **VanillaIceCream** API Level 35 image.
 
-> We recommend configuring [VM acceleration](https://developer.android.com/studio/run/emulator-acceleration.html#vm-linux) on your system to improve performance. Once you've followed those instructions, go back to the AVD Manager.
+:::tip
+We recommend configuring [VM acceleration](https://developer.android.com/studio/run/emulator-acceleration.html#vm-linux) on your system to improve performance. Once you've followed those instructions, go back to the AVD Manager.
+:::
 
 Click "Next" then "Finish" to create your AVD. At this point you should be able to click on the green triangle button next to your AVD to launch it.
 

docs/_getting-started-macos-android.md

@@ -13,7 +13,7 @@ brew install node
 brew install watchman
 ```
 
-If you have already installed Node on your system, make sure it is Node 18.18 or newer.
+If you have already installed Node on your system, make sure it is Node 20.19.4 or newer.
 
 [Watchman](https://facebook.github.io/watchman) is a tool by Facebook for watching changes in the filesystem. It is highly recommended you install it for better performance.
 
@@ -65,7 +65,9 @@ Setting up your development environment can be somewhat tedious if you're new to
 
 Then, click "Next" to install all of these components.
 
-> If the checkboxes are grayed out, you will have a chance to install these components later on.
+::note
+If the checkboxes are grayed out, you will have a chance to install these components later on.
+:::
 
 Once setup has finalized and you're presented with the Welcome screen, proceed to the next step.
 
@@ -77,7 +79,9 @@ To do that, open Android Studio, click on "More Actions" button and select "SDK
 
 ![Android Studio Welcome](/docs/assets/GettingStartedAndroidStudioWelcomeMacOS.png)
 
-> The SDK Manager can also be found within the Android Studio "Settings" dialog, under **Languages & Frameworks** → **Android SDK**.
+:::tip
+The SDK Manager can also be found within the Android Studio "Settings" dialog, under **Languages & Frameworks** → **Android SDK**.
+:::
 
 Select the "SDK Platforms" tab from within the SDK Manager, then check the box next to "Show Package Details" in the bottom right corner. Look for and expand the `Android 15 (VanillaIceCream)` entry, then make sure the following items are checked:
 
@@ -102,7 +106,9 @@ export PATH=$PATH:$ANDROID_HOME/platform-tools
 
 Run `source ~/.zprofile` (or `source ~/.bash_profile` for `bash`) to load the config into your current shell. Verify that ANDROID_HOME has been set by running `echo $ANDROID_HOME` and the appropriate directories have been added to your path by running `echo $PATH`.
 
-> Please make sure you use the correct Android SDK path. You can find the actual location of the SDK in the Android Studio "Settings" dialog, under **Languages & Frameworks** → **Android SDK**.
+:::note
+Please make sure you use the correct Android SDK path. You can find the actual location of the SDK in the Android Studio "Settings" dialog, under **Languages & Frameworks** → **Android SDK**.
+:::
 
 <h2>Preparing the Android device</h2>
 

docs/_getting-started-macos-ios.md

@@ -13,7 +13,7 @@ brew install node
 brew install watchman
 ```
 
-If you have already installed Node on your system, make sure it is Node 18.18 or newer.
+If you have already installed Node on your system, make sure it is Node 20.19.4 or newer.
 
 [Watchman](https://facebook.github.io/watchman) is a tool by Facebook for watching changes in the filesystem. It is highly recommended you install it for better performance.
 

docs/_getting-started-windows-android.md

@@ -20,9 +20,13 @@ choco install -y nodejs-lts microsoft-openjdk17
 
 If you have already installed Node on your system, make sure it is Node 18 or newer. If you already have a JDK on your system, we recommend JDK17. You may encounter problems using higher JDK versions.
 
-> You can find additional installation options on [Node's Downloads page](https://nodejs.org/en/download/).
+:::note
+You can find additional installation options on [Node's Downloads page](https://nodejs.org/en/download/).
+:::
 
-> If you're using the latest version of Java Development Kit, you'll need to change the Gradle version of your project so it can recognize the JDK. You can do that by going to `{project root folder}\android\gradle\wrapper\gradle-wrapper.properties` and changing the `distributionUrl` value to upgrade the Gradle version. You can check out [here the latest releases of Gradle](https://gradle.org/releases/).
+:::info
+If you're using the latest version of Java Development Kit, you'll need to change the Gradle version of your project so it can recognize the JDK. You can do that by going to `{project root folder}\android\gradle\wrapper\gradle-wrapper.properties` and changing the `distributionUrl` value to upgrade the Gradle version. You can check out [here the latest releases of Gradle](https://gradle.org/releases/).
+:::
 
 <h3>Android development environment</h3>
 
@@ -39,7 +43,9 @@ Setting up your development environment can be somewhat tedious if you're new to
 
 Then, click "Next" to install all of these components.
 
-> If the checkboxes are grayed out, you will have a chance to install these components later on.
+:::note
+If the checkboxes are grayed out, you will have a chance to install these components later on.
+:::
 
 Once setup has finalized and you're presented with the Welcome screen, proceed to the next step.
 
@@ -51,7 +57,9 @@ To do that, open Android Studio, click on "More Actions" button and select "SDK
 
 ![Android Studio Welcome](/docs/assets/GettingStartedAndroidStudioWelcomeWindows.png)
 
-> The SDK Manager can also be found within the Android Studio "Settings" dialog, under **Languages & Frameworks** → **Android SDK**.
+:::tip
+The SDK Manager can also be found within the Android Studio "Settings" dialog, under **Languages & Frameworks** → **Android SDK**.
+:::
 
 Select the "SDK Platforms" tab from within the SDK Manager, then check the box next to "Show Package Details" in the bottom right corner. Look for and expand the `Android 15 (VanillaIceCream)` entry, then make sure the following items are checked:
 
@@ -120,7 +128,9 @@ If you use Android Studio to open `./AwesomeProject/android`, you can see the li
 
 If you have recently installed Android Studio, you will likely need to [create a new AVD](https://developer.android.com/studio/run/managing-avds.html). Select "Create Virtual Device...", then pick any Phone from the list and click "Next", then select the **VanillaIceCream** API Level 35 image.
 
-> If you don't have HAXM installed, click on "Install HAXM" or follow [these instructions](https://github.com/intel/haxm/wiki/Installation-Instructions-on-Windows) to set it up, then go back to the AVD Manager.
+:::note
+If you don't have HAXM installed, click on "Install HAXM" or follow [these instructions](https://github.com/intel/haxm/wiki/Installation-Instructions-on-Windows) to set it up, then go back to the AVD Manager.
+:::
 
 Click "Next" then "Finish" to create your AVD. At this point you should be able to click on the green triangle button next to your AVD to launch it.
 

docs/_remove-global-cli.md

@@ -1,5 +1,8 @@
-> If you previously installed a global `react-native-cli` package, please remove it as it may cause unexpected issues:
->
-> ```shell
-> npm uninstall -g react-native-cli @react-native-community/cli
-> ```
+:::warning
+If you previously installed a global `react-native-cli` package, please remove it as it may cause unexpected issues:
+
+```shell
+npm uninstall -g react-native-cli @react-native-community/cli
+```
+
+:::

docs/accessibility.md

@@ -4,6 +4,8 @@ title: Accessibility
 description: Create mobile apps accessible to assistive technology with React Native's suite of APIs designed to work with Android and iOS.
 ---
 
+import ExperimentalAPIWarning from './\_experimental-api-warning.mdx';
+
 Both Android and iOS provide APIs for integrating apps with assistive technologies like the bundled screen readers VoiceOver (iOS) and TalkBack (Android). React Native has complementary APIs that let your app accommodate all users.
 
 :::info
@@ -222,9 +224,9 @@ For example, in a window that contains sibling views `A` and `B`, setting `acces
 
 ### `accessibilityElementsHidden` <div className="label ios">iOS</div>
 
-A boolean value indicating whether the accessibility elements contained within this accessibility element are hidden.
+A boolean value indicating whether the given accessibility element, and any accessibility elements it contains, are hidden.
 
-For example, in a window that contains sibling views `A` and `B`, setting `accessibilityElementsHidden` to `true` on view `B` causes VoiceOver to ignore the elements in view `B`. This is similar to the Android property `importantForAccessibility="no-hide-descendants"`.
+For example, in a window that contains sibling views `A` and `B`, setting `accessibilityElementsHidden` to `true` on view `B` causes VoiceOver to ignore the `B` view and any elements it contains. This is similar to the Android property `importantForAccessibility="no-hide-descendants"`.
 
 ### `aria-valuemax`
 
@@ -276,17 +278,17 @@ Indicates whether an expandable element is currently expanded or collapsed.
 
 ### `aria-hidden`
 
-Indicates whether the accessibility elements contained within this accessibility element are hidden.
+Indicates whether the element is hidden from assistive technologies.
 
-For example, in a window that contains sibling views `A` and `B`, setting `aria-hidden` to `true` on view `B` causes VoiceOver to ignore the elements in view `B`.
+For example, in a window that contains sibling views `A` and `B`, setting `aria-hidden` to `true` on view `B` causes VoiceOver to ignore the `B` element and its children.
 
 | Type    | Default |
 | ------- | ------- |
 | boolean | false   |
 
 ### `aria-label`
 
-Defines a string value that labels an interactive element.
+Defines a string value that can be used to name an element.
 
 | Type   |
 | ------ |
@@ -337,6 +339,99 @@ Indicates whether a selectable element is currently selected or not.
 | ------- |
 | boolean |
 
+### `experimental_accessibilityOrder`
+
+<ExperimentalAPIWarning />
+
+:::note
+For the sake of brevity, layout is excluded in the following examples even though it dictates the default focus order. Assume the document order matches the layout order.
+:::
+
+`experimental_accessibilityOrder` lets you define the order in which assistive technologies focus descendant components. It is an array of [`nativeIDs`](view.md#nativeid) that are set on the components whose order you are controlling. For example:
+
+```
+<View experimental_accessibilityOrder={['B', 'C', 'A']}>
+  <View accessible={true} nativeID="A"/>
+  <View accessible={true} nativeID="B"/>
+  <View accessible={true} nativeID="C"/>
+</View>
+```
+
+Assistive technologies will focus the `View` with `nativeID` of `B`, then `C`, then `A`.
+
+`experimental_accessibilityOrder` will not “turn on” accessibility for the components it references, that still needs to be done. So if we remove `accessible={true}` on `C` above like so
+
+```
+<View experimental_accessibilityOrder={['B', 'C', 'A']}>
+  <View accessible={true} nativeID="A"/>
+  <View accessible={true} nativeID="B"/>
+  <View nativeID="C"/>
+</View>
+```
+
+then the new order will be `B` then `A`, even though `C` is still in `experimental_accessibilityOrder`.
+
+`experimental_accessibilityOrder` will “turn off” accessibility of components it doesn’t reference, however.
+
+```
+<View experimental_accessibilityOrder={['B', 'C', 'A']}>
+  <View accessible={true} nativeID="A"/>
+  <View accessible={true} nativeID="B"/>
+  <View accessible={true} nativeID="C"/>
+  <View accessible={true} nativeID="D"/>
+</View>
+```
+
+The order of the above example would be `B`, `C`, `A`. `D` will never get focused. In this sense `experimental_accessibilityOrder` is _exhaustive_.
+
+There are still valid reasons to include an non-accessible component in `experimental_accessibilityOrder`. Consider
+
+```
+<View experimental_accessibilityOrder={['B', 'C', 'A']}>
+  <View accessible={true} nativeID="A"/>
+  <View accessible={true} nativeID="B"/>
+  <View nativeID="C">
+    <View accessible={true} nativeID="D"/>
+    <View accessible={true} nativeID="E"/>
+    <View accessible={true} nativeID="F"/>
+  </View>
+</View>
+```
+
+The focus order will be `B`, `D`, `E`, `F`, `A`. Even though `D`, `E`, and `F` are not directly referenced in `experimental_accessibilityOrder`, `C` is directly referenced. In this instance `C` in an _accessibility container_ - it contains accessible elements, but is not accessible itself. If an accessibility container is referenced in `experimental_accessibilityOrder` then the default order of the elements it contains is applied. In this sense `experimental_accessibilityOrder` is _nestable_.
+
+`experimental_accessibilityOrder` can also reference another component with `experimental_accessibilityOrder`
+
+```
+<View experimental_accessibilityOrder={['B', 'C', 'A']}>
+  <View accessible={true} nativeID="A"/>
+  <View accessible={true} nativeID="B"/>
+  <View nativeID="C" experimental_accessibilityOrder={['F', 'E', 'D']}>
+    <View accessible={true} nativeID="D"/>
+    <View accessible={true} nativeID="E"/>
+    <View accessible={true} nativeID="F"/>
+  </View>
+</View>
+```
+
+The focus order will be `B`, `F`, `E`, `D`, `A`.
+
+A component cannot be both an accessibility container and an accessibility element (`accessible={true}`). So if we have
+
+```
+<View experimental_accessibilityOrder={['B', 'C', 'A']}>
+  <View accessible={true} nativeID="A"/>
+  <View accessible={true} nativeID="B"/>
+  <View accessible={true} nativeID="C" experimental_accessibilityOrder={['F', 'E', 'D']}>
+    <View accessible={true} nativeID="D"/>
+    <View accessible={true} nativeID="E"/>
+    <View accessible={true} nativeID="F"/>
+  </View>
+</View>
+```
+
+The focus order would be `B`, `C`, `A`. `D`, `E`, and `F` are no longer in a container, so the exhaustive nature of `experimental_accessibilityOrder` means they will be excluded.
+
 ### `importantForAccessibility` <div className="label android">Android</div>
 
 In the case of two overlapping UI components with the same parent, default accessibility focus can have unpredictable behavior. The `importantForAccessibility` property will resolve this by controlling if a view fires accessibility events and if it is reported to accessibility services. It can be set to `auto`, `yes`, `no` and `no-hide-descendants` (the last value will force accessibility services to ignore the component and all of its children).

docs/accessibilityinfo.md

@@ -158,7 +158,9 @@ static isAccessibilityServiceEnabled(): Promise<boolean>;
 
 Check whether any accessibility service is enabled. This includes TalkBack but also any third-party accessibility app that may be installed. To only check whether TalkBack is enabled, use [isScreenReaderEnabled](#isscreenreaderenabled). Returns a promise which resolves to a boolean. The result is `true` when some accessibility services is enabled and `false` otherwise.
 
-> **Note**: Please use [isScreenReaderEnabled](#isscreenreaderenabled) if you only want to check the status of TalkBack.
+:::note
+Please use [`isScreenReaderEnabled`](#isscreenreaderenabled) if you only want to check the status of TalkBack.
+:::
 
 ---
 
@@ -242,4 +244,6 @@ Set accessibility focus to a React component.
 
 On Android, this calls `UIManager.sendAccessibilityEvent` method with passed `reactTag` and `UIManager.AccessibilityEventTypes.typeViewFocused` arguments.
 
-> **Note**: Make sure that any `View` you want to receive the accessibility focus has `accessible={true}`.
+:::note
+Make sure that any `View` you want to receive the accessibility focus has `accessible={true}`.
+:::