react-native-a11y-order 0.9.0 → 0.9.1

package/README.md

@@ -36,157 +36,6 @@ npm install react-native-a11y-order
 yarn add react-native-a11y-order
 ```
 
-## Recent Updates
-
-#### Screen Reader Focus Events
-
-| iOS | Android |
-| :-- | :-- |
-| <img src="/.github/images/screen-reader-focus-ios.gif" height="500" /> |  <img src="/.github/images/screen-reader-focus-android.gif" height="500" />  |
-
-> To enhance accessibility and provide better focus management, screen reader focus handlers have been added. These handlers allow you to capture and respond to screen reader focus events effectively, enabling features like managing animations, timers, and other interactions based on focus changes.
-
-<details>
-  <summary>More Information</summary>
-
-A11y.View Props:
-| Prop | Description |
-| :-- | :-- |
-| onScreenReaderFocused | Triggered when the view gets focus from the screen reader. |
-| onScreenReaderSubViewFocused | Triggered when a subview within the component is focused by the screen reader. |
-| onScreenReaderSubViewBlurred | Triggered when the screen reader focus moves away or is blurred from a subview. |
-| onScreenReaderSubViewFocusChange | Triggered when the focus status of a subview changes (either focused or blurred). |
-| onScreenReaderDescendantFocusChanged | Triggered when any descendant subview is focused by the screen reader. Provides an object containing the focus status and the nativeId of the focused subview, if applicable. Example: < { status: string, nativeId?: string } >. |
-
-```tsx
-<A11y.View
-  onScreenReaderDescendantFocusChanged={(e) => console.log(e)}
-  onScreenReaderSubViewFocused={() => console.log('List has been focused')}
-  onScreenReaderSubViewBlurred={() => console.log('List has been blurred')}
-  onScreenReaderFocused={() => console.log('Focused')}
->
-  ...
-</A11y.View>
-```
-</details>
-
-#### Focus Lock Functionality
-
-| iOS | Android |
-| :-- | :-- |
-| <img src="/.github/images/focus-lock-ios.gif" height="500" /> |  <img src="/.github/images/focus-lock-android.gif" height="500" />  |
-
-> The focus lock functionality has been introduced with two new components: `A11y.FocusFrame` and `A11y.FocusTrap`. These components enable more robust accessibility by managing and restricting focus within specific areas of the screen.
-
-<details>
-  <summary>More Information</summary>
-
-- On iOS, `A11y.FocusTrap` uses the native `accessibilityViewIsModal` property to keep the focus within a defined area.
-- On Android, where no equivalent to `accessibilityViewIsModal` exists, custom logic has been implemented as a workaround. By default, Android uses a custom Activity or Modal to limit focus. While using a Modal is considered the best practice for focus locking on Android, some scenarios—such as issues with React Native's Modal or library-specific constraints—may require alternative implementations.
-
-#### How It Works
-
-The focus lock functionality should be used as a pair:
-
-- `A11y.FocusFrame`: This component is used at the root level of a "screen" to detect focus leaks and ensure that focus remains contained.
-- `A11y.FocusTrap`: This component wraps the content area where focus should be explicitly locked.
-
-| Prop | Description |
-| :-- | :-- |
-| ViewProps | Includes all standard React Native View properties, such as style, testID, etc. |
-
-```tsx
-<A11y.FocusFrame>
-  ...
-  <A11y.FocusTrap>
-    <Text accessibilityRole="header">Locked Area</Text>
-    <Button
-      title="Confirm"
-      accessibilityLabel="Confirm action"
-    />
-  </A11y.FocusTrap>
-  ...
-</A11y.FocusFrame>
-```
-
-</details>
-
-#### A11y.PaneTitle and A11y.ScreenChange
-
-| iOS | Android |
-| :-- | :-- |
-| <img src="/.github/images/announce-ios.gif" height="500" /> |  <img src="/.github/images/announce-android.gif" height="500" />  |
-
-> The components `A11y.PaneTitle` and `A11y.ScreenChange` have been introduced to enhance accessibility by providing robust support for announcing screen changes and their states.
-
-<details>
-  <summary>More Information</summary>
-
-Platform-Specific Behavior
--On Android, `A11y.PaneTitle` and `A11y.ScreenChange` utilize native properties, specifically: `activity.setTitle` and `setAccessibilityPaneTitle`.
-- On iOS, due to the lack of equivalent native functionality, `A11yModule.announce` is used as a workaround to announce screen changes (see the `A11yModule.announce` section for details).
-
-##### When to Use:
-
-Currently, React Native doesn't provide APIs for announcing modal or screen transitions. To address this and improve accessibility, you can use `A11y.PaneTitle` or `A11y.ScreenChange` to announce:
-- Screen transitions, such as navigating to a new screen (e.g., "Login Screen").
-- Modal presentations, such as when a modal appears (e.g., "Confirm Modal").
-
-
-A11y.PaneTitle Props
-| Prop | Description |
-| :-- | :-- |
-| title | The title message to be announced for the screen or modal. |
-| detachMessage | The message to be announced when this component is detached (e.g., when leaving the screen). |
-| type | The type of announcement for Android. Options: activity, pane, or announce. |
-| displayed | A trigger for screen focus changes, used to properly update the Android Activity title when switching screens. |
-| withFocusRestore | Ensures that the screen reader focus is preserved and restored appropriately after a screen change. (iOS-specific) |
-
-The A11y.ScreenChange component is a specialized implementation of A11y.PaneTitle. It is preconfigured with `type="activity"` for screen change announcements on Android and works identically to `A11y.PaneTitle`.
-
-Example:
-```tsx
-export const LoginScreen = ({ navigation }) => {
-  const isFocused = useIsFocused();
-  return (
-    <View>
-      <A11y.ScreenChange
-        title="Login Screen"
-        displayed={isFocused}
-      />
-      <View style={styles.container}>
-        <Text>Welcome to the Login Screen</Text>
-        <Button title="Continue" onPress={() => navigation.navigate('Home')} />
-      </View>
-    </View>
-  );
-};
-```
-</details>
-
-#### A11yModule.announce - Alternative Announcement Function
-
-> The `A11yModule.announce` function has been introduced to improve accessibility announcement behavior on iOS.
-
-<details>
-  <summary>More Information</summary>
-Why Use `A11yModule.announce`?
-
-On iOS, the default `AccessibilityInfo.announceForAccessibility` function can be interrupted by focus changes. This means that if you attempt to announce a message, the announcement could be prematurely cut off due to various events, such as screen navigation or the display of a modal.
-
-To address this limitation, `A11yModule.announce` uses a custom solution built on native events to ensure that announcements are made reliably and are less likely to be interrupted.
-
-A11yModule API:
-| Function | Description |
-| :-- | :-- |
-| announce(message: string): void | Posts a string to be announced by the screen reader, ensuring improved reliability on iOS. |
-
-```tsx
-A11yModule.announce('This is a custom announcement, now more reliable on iOS!');
-```
-</details>
-
-
 ## Usage
 
 #### A11y.Order, A11y.Index
@@ -322,9 +171,17 @@ These components enhance accessibility by providing better control over focus ma
 - `A11y.FocusFrame`: Used at the root level of a "screen" to detect and prevent focus leaks, ensuring focus remains contained.
 - `A11y.FocusTrap`: Wraps the content area to explicitly enforce focus confinement within a defined region.
 
+On iOS, `A11y.FocusTrap` uses `accessibilityViewIsModal` to keep focus within the defined area. When `forceLock` is enabled, it additionally uses active enforcement — redirecting VoiceOver back into the trap whenever focus escapes and blocking focus from leaving at the system level.
+
+On Android, `A11y.FocusTrap` uses a custom Activity or Modal to limit focus.
+
+`A11y.FocusTrap` Props:
+
 | Prop | Description |
 | :-- | :-- |
 | ViewProps | Includes all standard React Native View properties, such as style, testID, etc. |
+| lockDisabled? | Disables the focus lock when `true`. |
+| forceLock? | (iOS only) Enables active focus enforcement — VoiceOver is redirected back into the trap whenever focus escapes. Use when `accessibilityViewIsModal` alone is not sufficient. |
 
 ```tsx
 <A11y.FocusFrame>
@@ -340,6 +197,22 @@ These components enhance accessibility by providing better control over focus ma
 </A11y.FocusFrame>
 ```
 
+Use `forceLock` when the standard lock is not enough to keep VoiceOver inside the trap:
+
+```tsx
+<A11y.FocusFrame>
+  ...
+  <A11y.FocusTrap forceLock>
+    <Text accessibilityRole="header">Locked Area</Text>
+    <Button
+      title="Confirm"
+      accessibilityLabel="Confirm action"
+    />
+  </A11y.FocusTrap>
+  ...
+</A11y.FocusFrame>
+```
+
 ## A11y.PaneTitle, A11y.ScreenChange
 
 Components for screen change announcements

package/android/build.gradle

@@ -1,19 +1,3 @@
-buildscript {
-  // Buildscript is evaluated before everything else so we can't use getExtOrDefault
-  def kotlin_version = rootProject.ext.has("kotlinVersion") ? rootProject.ext.get("kotlinVersion") : project.properties["ExternalKeyboard_kotlinVersion"]
-
-  repositories {
-    google()
-    mavenCentral()
-  }
-
-  dependencies {
-    classpath "com.android.tools.build:gradle:7.2.1"
-    // noinspection DifferentKotlinGradleVersion
-    classpath "org.jetbrains.kotlin:kotlin-gradle-plugin:$kotlin_version"
-  }
-}
-
 def reactNativeArchitectures() {
   def value = rootProject.getProperties().get("reactNativeArchitectures")
   return value ? value.split(",") : ["armeabi-v7a", "x86", "x86_64", "arm64-v8a"]
@@ -24,7 +8,6 @@ def isNewArchitectureEnabled() {
 }
 
 apply plugin: "com.android.library"
-apply plugin: "kotlin-android"
 
 
 def appProject = rootProject.allprojects.find { it.plugins.hasPlugin('com.android.application') }
@@ -115,7 +98,6 @@ dependencies {
   // For > 0.71, this will be replaced by `com.facebook.react:react-android:$version` by react gradle plugin
   //noinspection GradleDynamicVersion
   implementation "com.facebook.react:react-native:+"
-  implementation "org.jetbrains.kotlin:kotlin-stdlib:$kotlin_version"
 }
 
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "react-native-a11y-order",
-  "version": "0.9.0",
+  "version": "0.9.1",
   "description": "ReactNative library for managing screen reader focus ordering",
   "main": "lib/commonjs/index",
   "module": "lib/module/index",