react-native-a11y-order 0.8.2 → 0.9.1-rc

package/README.md

@@ -6,7 +6,7 @@ Managing screen reader focus order can be challenging, especially in complex or
 
 | iOS reader                                                | Android reader                                                |
 | --------------------------------------------------------- | ------------------------------------------------------------- |
-| <img src="/.github/images/ios-reader.gif" height="500" /> | <img src="/.github/images/android-reader.gif" height="500" /> |
+| <img src="/.github/images/ios_example.gif" height="500" /> | <img src="/.github/images/android_example.gif" height="500" /> |
 
 
 - Bridgeless
@@ -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/android/src/main/java/com/a11yorder/services/focus/A11yFocusDelegate.java

@@ -1,13 +1,8 @@
 package com.a11yorder.services.focus;
 
-import android.app.Activity;
 import android.content.Context;
-import android.util.Log;
-import android.view.View;
 import android.view.ViewGroup;
-import android.view.accessibility.AccessibilityEvent;
 
-import androidx.annotation.Nullable;
 import androidx.fragment.app.Fragment;
 
 import com.a11yorder.utils.A11yHelper;
@@ -15,9 +10,6 @@ import com.a11yorder.utils.FragmentUtils;
 import com.facebook.react.bridge.ReactContext;
 
 public class A11yFocusDelegate {
-  private static final int DEFAULT_DELAY = 300;
-  private static final int DEFAULT_RETRIES = 3;
-
   private final A11yFocusProtocol delegate;
   private final Context context;
 
@@ -27,46 +19,32 @@ public class A11yFocusDelegate {
   }
 
   private void focus() {
-    A11yFocusService.getInstance().requestFocus((ViewGroup) delegate, DEFAULT_DELAY, DEFAULT_RETRIES);
+    A11yFocusService.getInstance().requestFocus((ViewGroup) delegate);
   }
 
   private void simpleFocus() {
     A11yFocusService.getInstance().simpleFocus((ViewGroup) delegate);
   }
 
-  public void onAccessibilityEvent(View child, AccessibilityEvent event) {
-    if (event.getEventType() == AccessibilityEvent.TYPE_VIEW_ACCESSIBILITY_FOCUSED) {
-      A11yFocusService.getInstance().onFocused((View) delegate);
-    }
-  }
-
-  @Nullable
-  private Activity getCurrentActivityFromContext() {
-    if (context instanceof ReactContext) {
-      return ((ReactContext) context).getCurrentActivity();
-    }
-    return null;
+  public void onFocused() {
+    A11yFocusService.getInstance().onFocused((ViewGroup) delegate);
   }
 
   public void requestFocus() {
-    if(!A11yHelper.isA11yServiceEnabled(context)) return;
+    if (!A11yHelper.isA11yServiceEnabled(context)) return;
 
-    Fragment currentFragment = FragmentUtils.findFragmentSafely((View) delegate);
+    Fragment currentFragment = FragmentUtils.findFragmentSafely((ViewGroup) delegate);
 
-    if (currentFragment != null && currentFragment.isResumed()) {
-      this.simpleFocus();
+    if (currentFragment == null) {
+      focus();
       return;
     }
 
-    if(currentFragment != null) {
-      Activity activity = getCurrentActivityFromContext();
-      FragmentUtils.waitForFragment(activity, currentFragment, this::focus);
+    if (currentFragment.isResumed()) {
+      simpleFocus();
       return;
     }
 
-    this.focus();
+    FragmentUtils.waitForFragmentResume(currentFragment, this::focus);
   }
 }
-
-
-

package/android/src/main/java/com/a11yorder/services/order/A11yOrderService.java

@@ -7,15 +7,17 @@ import com.a11yorder.services.order.linking.A11yOrderLinking;
 import com.a11yorder.utils.A11yHelper;
 
 import java.lang.ref.WeakReference;
+import java.util.Objects;
 
 public class A11yOrderService {
   public static final int ORDER_FOCUS_TYPE_DEFAULT = 0;
   public static final int ORDER_FOCUS_TYPE_CHILD = 1;
   public static final int ORDER_FOCUS_TYPE_LEGACY = 2;
+
   private final ViewGroup delegate;
-  public String orderKey;
+  private String orderKey;
   private Integer index;
-  private Integer focusType = ORDER_FOCUS_TYPE_DEFAULT;
+  private int focusType = ORDER_FOCUS_TYPE_DEFAULT;
   private WeakReference<View> orderViewRef;
   private boolean isLinked = false;
 
@@ -23,82 +25,104 @@ public class A11yOrderService {
     this.delegate = delegate;
   }
 
+  // ─── Accessors ────────────────────────────────────────────────────────────
+
   public View getStoredView() {
     return orderViewRef != null ? orderViewRef.get() : null;
   }
 
   public View getFocusView() {
-    if (focusType == ORDER_FOCUS_TYPE_LEGACY) {
-      if (orderViewRef != null && orderViewRef.get() != null) {
-        return orderViewRef.get();
+    switch (focusType) {
+      case ORDER_FOCUS_TYPE_LEGACY: {
+        View stored = getStoredView();
+        return stored != null ? stored : delegate.getChildAt(0);
       }
-
-      return delegate.getChildAt(0);
+      case ORDER_FOCUS_TYPE_CHILD:
+        return A11yHelper.findFirstAccessible(delegate, true);
+      default:
+        return delegate;
     }
-
-    if (focusType == ORDER_FOCUS_TYPE_DEFAULT) {
-      return delegate;
-    }
-
-    if (focusType == ORDER_FOCUS_TYPE_CHILD) {
-      return A11yHelper.findFirstAccessible(delegate, true);
-    }
-
-    return null;
   }
 
-  public void setIndex(int index) {
-    boolean hasBeenChanged = this.index != null;
+  // ─── Prop setters ─────────────────────────────────────────────────────────
 
+  public void setIndex(int index) {
+    if (this.index != null && this.index.equals(index)) return;
+    boolean isFirstSet = this.index == null;
     this.index = index;
-    if (hasBeenChanged) {
-      this.refresh();
+    if (isFirstSet) {
+      // Both props may now be ready for the first time — attempt registration.
+      register();
+    } else if (isLinked) {
+      refresh();
     }
   }
 
+  public void setOrderKey(String newKey) {
+    if (Objects.equals(this.orderKey, newKey)) return;
+    if (isLinked) unregister();
+    this.orderKey = newKey;
+    register();
+  }
+
   public void setFocusType(int focusType) {
-    int prevFocusType = this.focusType;
+    int prev = this.focusType;
     this.focusType = focusType;
-
-    if (isLinked && prevFocusType != focusType) {
-      this.refresh();
+    if (isLinked && prev != focusType) {
+      refresh();
     }
   }
 
-  public boolean getIsReady() {
+  // ─── Registration ─────────────────────────────────────────────────────────
+
+  private boolean isReady() {
     return orderKey != null && index != null;
   }
 
-  public void link(View view) {
-    if (orderViewRef == null || orderViewRef.get() == null) {
-      orderViewRef = new WeakReference<>(view);
+  private void register() {
+    if (!isReady() || isLinked) return;
+    View target = getFocusView();
+    if (target != null) {
+      A11yOrderLinking.getInstance().addViewRelationship(target, orderKey, index);
+      isLinked = true;
+    }
+  }
 
-      if (!this.getIsReady()) return;
+  private void unregister() {
+    if (orderKey != null && index != null) {
+      A11yOrderLinking.getInstance().removeRelationship(orderKey, index);
+    }
+    isLinked = false;
+  }
 
-      View target = getFocusView();
-      if (target != null) {
-        A11yOrderLinking.getInstance().addViewRelationship(target, orderKey, index);
-        isLinked = true;
-      }
+  private void refresh() {
+    if (!isReady()) return;
+    View target = getFocusView();
+    if (target != null) {
+      A11yOrderLinking.getInstance().refreshIndexes(target, orderKey, index);
     }
   }
 
-  public void refresh() {
-    if (!getIsReady()) return;
+  // ─── Lifecycle ────────────────────────────────────────────────────────────
 
-    View view = getFocusView();
-    if (view != null) {
-      A11yOrderLinking.getInstance().refreshIndexes(view, orderKey, index);
-    }
+  public void link(View child) {
+    if (orderViewRef != null && orderViewRef.get() != null) return;
+    orderViewRef = new WeakReference<>(child);
+    register();
+  }
+
+  public void attach() {
+    if (!isReady() || isLinked) return;
+    View child = delegate.getChildAt(0);
+    if (child != null) link(child);
   }
 
-  public void clear(View view) {
-    if (orderViewRef != null && orderViewRef.get() == view) {
+  public void clear(View child) {
+    if (orderViewRef != null && orderViewRef.get() == child) {
       orderViewRef.clear();
       orderViewRef = null;
     }
-
-    this.remove();
+    unregister();
   }
 
   public void detach() {
@@ -106,25 +130,6 @@ public class A11yOrderService {
       orderViewRef.clear();
       orderViewRef = null;
     }
-
-    this.remove();
-  }
-
-  private void remove() {
-    if (orderKey != null && index != null) {
-      A11yOrderLinking.getInstance().removeRelationship(orderKey, index);
-    }
-
-    isLinked = false;
-  }
-
-
-  public void attach() {
-    if (!getIsReady() || isLinked) return;
-
-    View child = delegate.getChildAt(0);
-    if (child == null) return;
-
-    this.link(child);
+    unregister();
   }
 }

package/android/src/main/java/com/a11yorder/services/order/linking/A11yLinkingQueue.java

@@ -3,92 +3,66 @@ package com.a11yorder.services.order.linking;
 import android.os.Build;
 import android.view.View;
 
-import java.lang.ref.WeakReference;
-import java.util.Map;
-import java.util.NavigableSet;
-import java.util.TreeSet;
-
 public class A11yLinkingQueue {
-  public WeakTreeMap viewMap = new WeakTreeMap();
+  private final WeakTreeMap viewMap = new WeakTreeMap();
 
+  // ─── Link helpers ──────────────────────────────────────────────────────────
 
   private void linkPosition(View prev, View next) {
-    if (prev != null && next != null) {
-      prev.setNextFocusForwardId(next.getId());
-      if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.LOLLIPOP_MR1) {
-        prev.setAccessibilityTraversalBefore(next.getId());
-      }
+    if (prev == null || next == null) return;
+    prev.setNextFocusForwardId(next.getId());
+    if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.LOLLIPOP_MR1) {
+      prev.setAccessibilityTraversalBefore(next.getId());
     }
   }
 
-  private void addWithLinking(int position, View currentView) {
-    viewMap.put(position, currentView);
-    View nextView = viewMap.getNext(position);
-    View prevView = viewMap.getPrev(position);
-
-    if (prevView != null) {
-      this.linkPosition(prevView, currentView);
-    }
-
-    if (nextView != null) {
-      this.linkPosition(currentView, nextView);
+  private void clearForwardLink(View view) {
+    if (view == null) return;
+    view.setNextFocusForwardId(View.NO_ID);
+    if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.LOLLIPOP_MR1) {
+      view.setAccessibilityTraversalBefore(View.NO_ID);
     }
   }
 
   private void unlinkLast() {
-    View lastView = viewMap.last();
-    if (lastView != null) {
-      lastView.setNextFocusForwardId(View.NO_ID);
-      if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.LOLLIPOP_MR1) {
-        lastView.setAccessibilityTraversalBefore(View.NO_ID);
-      }
-    }
+    clearForwardLink(viewMap.last());
   }
 
-  private void reLinkWithRemove(int position) {
-    View nextView = viewMap.getNext(position);
-    View prevView = viewMap.getPrev(position);
-
-    if (prevView != null && nextView != null) {
-      this.linkPosition(prevView, nextView);
-    }
-
-    boolean shouldUnlinkLast = nextView == null;
-    this.viewMap.remove(position);
-
-    if (shouldUnlinkLast) {
-      this.unlinkLast();
-    }
-  }
+  // ─── Public API ────────────────────────────────────────────────────────────
 
   public void addPosition(View view, int position) {
-    if (this.viewMap.get(position) == view) return;
-    this.addWithLinking(position, view);
+    if (viewMap.get(position) == view) return;
+    viewMap.put(position, view);
+    View prev = viewMap.getPrev(position);
+    View next = viewMap.getNext(position);
+    if (prev != null) linkPosition(prev, view);
+    if (next != null) linkPosition(view, next);
   }
 
   public void removeFromOrder(int position) {
-    if (!this.viewMap.containsKey(position)) return;
-    this.reLinkWithRemove(position);
+    if (!viewMap.containsKey(position)) return;
+    View prev = viewMap.getPrev(position);
+    View next = viewMap.getNext(position);
+    boolean wasLast = next == null;
+    viewMap.remove(position);
+    if (prev != null && next != null) {
+      linkPosition(prev, next);
+    } else if (wasLast) {
+      // Clear the forward link on the new last element.
+      unlinkLast();
+    }
   }
 
   public void refreshIndexes(View view, int position) {
-    this.viewMap.put(position, view);
-
-    for (Map.Entry<Integer, WeakReference<View>> positionEntry : this.viewMap.entrySet()) {
-      View currentView = WeakTreeMap.unwrapViewRef(positionEntry);
-      if (currentView != null) {
-        View nextEntry = this.viewMap.getNext(positionEntry.getKey());
-
-        if (nextEntry != null) {
-          linkPosition(currentView, nextEntry);
-        }
-      }
-    }
-
+    viewMap.put(position, view);
+    viewMap.forEachLive((pos, current) -> {
+      View next = viewMap.getNext(pos);
+      if (next != null) linkPosition(current, next);
+    });
     unlinkLast();
   }
 
-  public boolean isEmpty () {
-    return this.viewMap.isEmpty();
+  public boolean isEmpty() {
+    return viewMap.isEmpty();
   }
 }