react-native-a11y-order 1.0.0-rc → 1.0.0

package/README.md

@@ -3,7 +3,7 @@
 # React Native A11y Order
 
 <div>
-  <img align="right" width="35%" src="/.github/images/ios_example.gif">
+  <img align="right" width="35%" src="/.github/images/a11y-order-ios.gif">
 </div>
 
 Native-first React Native library for controlling screen reader focus order on iOS (VoiceOver) and Android (TalkBack).
@@ -40,6 +40,8 @@ Get started with the [getting started guide](./docs/getting-started/getting-star
 
 ## What's available
 
+**Components**
+
 | Export | Purpose |
 | :-- | :-- |
 | [`A11y.Order`](./docs/guides/a11y-order.md) | Container that defines a named focus-order sequence. |
@@ -50,7 +52,12 @@ Get started with the [getting started guide](./docs/getting-started/getting-star
 | [`A11y.FocusFrame`](./docs/components/A11yFocusTrap.md) | Root boundary required by `A11y.FocusTrap`; detects focus escaping the region. |
 | [`A11y.PaneTitle`](./docs/components/A11yPaneTitle.md) | Announces screen or panel transitions to VoiceOver/TalkBack. |
 | [`A11y.ScreenChange`](./docs/components/A11yPaneTitle.md) | Shorthand for `A11y.PaneTitle` with `type="activity"` pre-set. |
-| [`A11yModule`](./docs/leftovers/announce.md) | Reliable programmatic announcements on iOS. |
+
+**API**
+
+| Export | Purpose |
+| :-- | :-- |
+| [`ScreenReader`](./docs/api/ScreenReader.md) | Reliable programmatic announcements for VoiceOver and TalkBack. |
 
 ---
 

package/android/src/main/java/com/a11yorder/core/A11yManagedFocusView.java

@@ -0,0 +1,29 @@
+package com.a11yorder.core;
+
+import android.content.Context;
+import android.view.View;
+import android.view.accessibility.AccessibilityEvent;
+
+import com.a11yorder.services.focus.A11yFocusDelegate;
+import com.a11yorder.services.focus.A11yFocusProtocol;
+import com.facebook.react.bridge.ReactContext;
+
+public class A11yManagedFocusView extends A11yScreenReaderView implements A11yFocusProtocol {
+  private final A11yFocusDelegate a11yFocusDelegate;
+
+  public A11yManagedFocusView(Context context) {
+    super(context);
+    this.a11yFocusDelegate = new A11yFocusDelegate((ReactContext) context, this);
+  }
+
+  @Override
+  public boolean isViewFocused() {
+    View focusTarget = this.isFocusable() ? this : this.getSubChild();
+    if (focusTarget == null) return false;
+    return focusTarget.isAccessibilityFocused();
+  }
+
+  public void focus() {
+    a11yFocusDelegate.requestFocus();
+  }
+}

package/android/src/main/java/com/a11yorder/core/A11yViewOrder.java

@@ -5,7 +5,7 @@ import android.view.View;
 
 import com.a11yorder.services.order.A11yOrderService;
 
-public class A11yViewOrder extends A11yAutoFocusView {
+public class A11yViewOrder extends A11yManagedFocusView {
   private final A11yOrderService orderService;
 
   public A11yViewOrder(Context context) {

package/android/src/main/java/com/a11yorder/modules/A11yAnnounceModule.java

@@ -1,13 +1,12 @@
 package com.a11yorder.modules;
 
-import com.a11yorder.A11yAnnounceModuleSpec;
-import android.content.Context;
-import android.content.SharedPreferences;
-import android.util.Log;
+import androidx.annotation.Nullable;
 
-import com.facebook.proguard.annotations.DoNotStrip;
+import com.a11yorder.A11yAnnounceModuleSpec;
+import com.facebook.react.bridge.Promise;
 import com.facebook.react.bridge.ReactApplicationContext;
 import com.facebook.react.bridge.ReactMethod;
+import com.facebook.react.bridge.ReadableMap;
 
 public class A11yAnnounceModule extends A11yAnnounceModuleSpec {
 
@@ -22,8 +21,22 @@ public class A11yAnnounceModule extends A11yAnnounceModuleSpec {
     return NAME;
   }
 
+  // stub — announcement is handled by the JS layer on Android
+  @Override
+  @ReactMethod
+  public void announce(String message, @Nullable ReadableMap options, Promise promise) {
+    promise.resolve(null);
+  }
+
+  @Override
+  @ReactMethod
+  public void cancel(String id, Promise promise) {
+    promise.resolve(null);
+  }
+
+  @Override
   @ReactMethod
-  public void announce(String message) {
-    //stub
+  public void cancelAll(Promise promise) {
+    promise.resolve(null);
   }
 }

package/android/src/main/java/com/a11yorder/views/A11yIndexView/A11yIndexViewManager.java

@@ -80,12 +80,6 @@ public class A11yIndexViewManager extends com.a11yorder.A11yIndexViewManagerSpec
   }
 
 
-  @Override
-  @ReactProp(name = "autoFocus")
-  public void setAutoFocus(A11yIndexView view, boolean value) {
-    view.setAutoFocus(value);
-  }
-
   @Override
   public void setDescendantFocusChangedEnabled(A11yIndexView view, boolean value) {
     //stub

package/android/src/oldarch/A11yAnnounceModuleSpec.java

@@ -1,12 +1,19 @@
 package com.a11yorder;
 
+import androidx.annotation.Nullable;
+import com.facebook.react.bridge.Promise;
 import com.facebook.react.bridge.ReactApplicationContext;
 import com.facebook.react.bridge.ReactContextBaseJavaModule;
+import com.facebook.react.bridge.ReadableMap;
 
 public abstract class A11yAnnounceModuleSpec extends ReactContextBaseJavaModule {
   protected A11yAnnounceModuleSpec(ReactApplicationContext context) {
     super(context);
   }
 
-  public abstract void announce(String message);
+  public abstract void announce(String message, @Nullable ReadableMap options, Promise promise);
+
+  public abstract void cancel(String id, Promise promise);
+
+  public abstract void cancelAll(Promise promise);
 }

package/android/src/oldarch/A11yIndexViewManagerSpec.java

@@ -13,7 +13,6 @@ public abstract class A11yIndexViewManagerSpec<T extends A11yIndexView> extends
 
   public abstract void focus(T view);
 
-  public abstract void setAutoFocus(A11yIndexView view, boolean value);
   public abstract void setDescendantFocusChangedEnabled(A11yIndexView view, boolean value);
 
   public abstract void setContainerType(A11yIndexView view, int value);

package/ios/helpers/RNAOSpeechAttributes.h

@@ -0,0 +1,35 @@
+//
+//  RNAOSpeechAttributes.h
+//  react-native-a11y-order
+//
+
+#ifndef RNAOSpeechAttributes_h
+#define RNAOSpeechAttributes_h
+
+#import <Foundation/Foundation.h>
+#import <UIKit/UIKit.h>
+
+NS_ASSUME_NONNULL_BEGIN
+
+/**
+ * Builds an NSAttributedString suitable for UIAccessibilityPostNotification
+ * from a flat options dictionary. Keys consumed:
+ *
+ *   priority     NSString  "low" | "default" | "high" | "critical"
+ *   queue        NSNumber  BOOL (defaults to YES; "critical" forces NO)
+ *   language     NSString  BCP-47 tag
+ *   pitch        NSNumber  0.0–2.0 (skipped at 1.0 ± 0.001)
+ *   spellOut     NSNumber  BOOL
+ *   punctuation  NSNumber  BOOL
+ *   ipaNotation  NSString
+ */
+@interface RNAOSpeechAttributes : NSObject
+
++ (NSAttributedString *)attributedStringFor:(NSString *)message
+                                    options:(NSDictionary *)options;
+
+@end
+
+NS_ASSUME_NONNULL_END
+
+#endif /* RNAOSpeechAttributes_h */

package/ios/helpers/RNAOSpeechAttributes.mm

@@ -0,0 +1,64 @@
+//
+//  RNAOSpeechAttributes.mm
+//  react-native-a11y-order
+//
+
+#import "RNAOSpeechAttributes.h"
+
+@implementation RNAOSpeechAttributes
+
++ (NSAttributedString *)attributedStringFor:(NSString *)message
+                                    options:(NSDictionary *)options
+{
+    NSMutableDictionary<NSAttributedStringKey, id> *attrs = [NSMutableDictionary new];
+
+    BOOL shouldQueue = options[@"queue"] ? [options[@"queue"] boolValue] : YES;
+
+    if (@available(iOS 11.0, *)) {
+        attrs[UIAccessibilitySpeechAttributeQueueAnnouncement] = @(shouldQueue);
+    }
+
+    if (@available(iOS 17.0, *)) {
+        NSString *priority = options[@"priority"] ?: @"default";
+        UIAccessibilityPriority nativePriority = UIAccessibilityPriorityDefault;
+        if ([priority isEqualToString:@"low"])
+            nativePriority = UIAccessibilityPriorityLow;
+        else if ([priority isEqualToString:@"high"])
+            nativePriority = UIAccessibilityPriorityHigh;
+        attrs[UIAccessibilitySpeechAttributeAnnouncementPriority] = nativePriority;
+    }
+
+    id langVal = options[@"language"];
+    if ([langVal isKindOfClass:[NSString class]]) {
+        attrs[UIAccessibilitySpeechAttributeLanguage] = langVal;
+    }
+
+    // Pitch only written when it deviates from default 1.0.
+    id pitchVal = options[@"pitch"];
+    if (pitchVal && ![pitchVal isEqual:[NSNull null]]) {
+        CGFloat raw = [pitchVal floatValue];
+        if (fabs(raw - 1.0f) > 0.001f) {
+            attrs[UIAccessibilitySpeechAttributePitch] = @(MAX(0.0f, MIN(2.0f, raw)));
+        }
+    }
+
+    if (@available(iOS 13.0, *)) {
+        if ([options[@"spellOut"] boolValue]) {
+            attrs[UIAccessibilitySpeechAttributeSpellOut] = @YES;
+        }
+    }
+
+    if (@available(iOS 11.0, *)) {
+        if ([options[@"punctuation"] boolValue]) {
+            attrs[UIAccessibilitySpeechAttributePunctuation] = @YES;
+        }
+        id ipaVal = options[@"ipaNotation"];
+        if ([ipaVal isKindOfClass:[NSString class]]) {
+            attrs[UIAccessibilitySpeechAttributeIPANotation] = ipaVal;
+        }
+    }
+
+    return [[NSAttributedString alloc] initWithString:message attributes:attrs];
+}
+
+@end

package/ios/modules/RNAOA11yAnnounceModule.h

@@ -1,14 +1,11 @@
 //
 //  RNAOA11yAnnounceModule.h
-//  Pods
-//
-//  Created by Artur Kalach on 06/12/2025.
+//  react-native-a11y-order
 //
 
 #ifndef RNAOA11yAnnounceModule_h
 #define RNAOA11yAnnounceModule_h
 
-
 #import <Foundation/Foundation.h>
 
 #ifdef RCT_NEW_ARCH_ENABLED
@@ -16,19 +13,26 @@
 
 @interface RNAOA11yAnnounceModule : NSObject <NativeA11yAnnounceModuleSpec>
 
-@end
-
 #else
 
 #import <React/RCTBridgeModule.h>
 
-
 @interface RNAOA11yAnnounceModule : NSObject <RCTBridgeModule>
 
-- (void)announce:(NSString *)message;
+- (void)announce:(NSString *)message
+         options:(NSDictionary *)options
+         resolve:(RCTPromiseResolveBlock)resolve
+          reject:(RCTPromiseRejectBlock)reject;
 
-@end
+- (void)cancel:(NSString *)announcementId
+        resolve:(RCTPromiseResolveBlock)resolve
+         reject:(RCTPromiseRejectBlock)reject;
+
+- (void)cancelAll:(RCTPromiseResolveBlock)resolve
+           reject:(RCTPromiseRejectBlock)reject;
 
 #endif
 
+@end
+
 #endif /* RNAOA11yAnnounceModule_h */

package/ios/modules/RNAOA11yAnnounceModule.mm

@@ -1,40 +1,246 @@
 //
-//  RNAOA11yAnnounceModule.m
+//  RNAOA11yAnnounceModule.mm
 //  react-native-a11y-order
 //
-//  Created by Artur Kalach on 06/12/2025.
-//
 
 #import <Foundation/Foundation.h>
+#import <UIKit/UIKit.h>
 #import "RNAOA11yAnnounceModule.h"
 #import "RNAOA11yAnnounceService.h"
+#import "RNAOSpeechAttributes.h"
 
 #ifdef RCT_NEW_ARCH_ENABLED
-
 using namespace facebook::react;
-
 #endif
 
+// ─────────────────────────────────────────────────────────────────────────────
+// MARK: - Pending entry
+// ─────────────────────────────────────────────────────────────────────────────
+
+@interface RNAOPendingAnnouncement : NSObject
+@property (nonatomic, copy)   RCTPromiseResolveBlock resolve;
+@property (nonatomic, copy)   NSString *text;      // for direct-mode finish-notification matching
+@property (nonatomic, assign) BOOL isDirect;
+@end
+@implementation RNAOPendingAnnouncement
+@end
+
+
+// ─────────────────────────────────────────────────────────────────────────────
+// MARK: - Private interface
+// ─────────────────────────────────────────────────────────────────────────────
+
+@interface RNAOA11yAnnounceModule ()
+
+// Single source of truth: announcementId → entry.
+@property (nonatomic, strong) NSMutableDictionary<NSString *, RNAOPendingAnnouncement *> *pending;
+
+// At most one direct announcement is in-flight; pointer into `pending`.
+@property (nonatomic, copy, nullable) NSString *currentDirectId;
+
+@end
+
+
+// ─────────────────────────────────────────────────────────────────────────────
+// MARK: - Implementation
+// ─────────────────────────────────────────────────────────────────────────────
+
 @implementation RNAOA11yAnnounceModule
 
++ (BOOL)requiresMainQueueSetup { return YES; }
 
-+ (BOOL)requiresMainQueueSetup
-{
-    return YES;
+RCT_EXPORT_MODULE(A11yAnnounceModule);
+
+- (instancetype)init {
+    if (self = [super init]) {
+        _pending = [NSMutableDictionary new];
+        [[NSNotificationCenter defaultCenter]
+             addObserver:self
+                selector:@selector(_handleAnnouncementFinished:)
+                    name:UIAccessibilityAnnouncementDidFinishNotification
+                  object:nil];
+    }
+    return self;
 }
 
+- (void)dealloc {
+    [[NSNotificationCenter defaultCenter] removeObserver:self];
+}
 
-RCT_EXPORT_MODULE(A11yAnnounceModule);
 
-RCT_EXPORT_METHOD(announce: (nonnull NSString*) title) {
-  [[RNAOA11yAnnounceService shared] announce: title];
+// ─────────────────────────────────────────────────────────────────────────────
+// MARK: - announce  (arch-split: C++ struct vs NSDictionary)
+// ─────────────────────────────────────────────────────────────────────────────
+
+/**
+ * calm: true  — Routes through RNAOA11yAnnounceService (300 ms debounce +
+ *               navigation-lock + VoiceOver-state guard). Promise resolves
+ *               when the service **actually fires** the announcement, not just
+ *               when it is enqueued, so `await` is meaningful.
+ *
+ * calm: false — Posts via UIAccessibilityPostNotification with speech attrs.
+ *               Promise resolves when UIAccessibilityAnnouncementDidFinishNotification
+ *               fires ('spoken') or the announcement is interrupted ('fired').
+ */
+- (void)_announceMessage:(NSString *)message
+                     opts:(NSDictionary *)opts
+                  resolve:(RCTPromiseResolveBlock)resolve
+                   reject:(RCTPromiseRejectBlock)reject
+{
+    if (!message || [message stringByTrimmingCharactersInSet:
+                     [NSCharacterSet whitespaceAndNewlineCharacterSet]].length == 0) {
+        message = @"";
+    }
+
+    NSString *announcementId = [[NSUUID UUID] UUIDString];
+    BOOL calm = [opts[@"calm"] boolValue];
+
+    RNAOPendingAnnouncement *entry = [RNAOPendingAnnouncement new];
+    entry.resolve  = resolve;
+    entry.text     = message;
+    entry.isDirect = !calm;
+    self.pending[announcementId] = entry;
+
+    if (calm) {
+        __weak RNAOA11yAnnounceModule *weakSelf = self;
+        [[RNAOA11yAnnounceService shared] announce:message onFired:^{
+            // Guard against cancel:id that already removed the entry — avoids double-resolve.
+            [weakSelf _resolveId:announcementId status:@"fired"];
+        }];
+        return;
+    }
+
+    // Direct mode: at most one in-flight; supersede any previous.
+    if (self.currentDirectId && ![self.currentDirectId isEqualToString:announcementId]) {
+        [self _resolveId:self.currentDirectId status:@"fired"];
+    }
+    self.currentDirectId = announcementId;
+
+    NSAttributedString *attrStr = [RNAOSpeechAttributes attributedStringFor:message options:opts];
+    NSTimeInterval delayMs = [opts[@"delayMs"] doubleValue];
+
+    dispatch_block_t post = ^{
+        UIAccessibilityPostNotification(UIAccessibilityAnnouncementNotification, attrStr);
+    };
+
+    if (delayMs > 0) {
+        dispatch_after(
+            dispatch_time(DISPATCH_TIME_NOW, (int64_t)(delayMs * NSEC_PER_MSEC)),
+            dispatch_get_main_queue(),
+            post
+        );
+    } else {
+        dispatch_async(dispatch_get_main_queue(), post);
+    }
 }
 
 #ifdef RCT_NEW_ARCH_ENABLED
-- (std::shared_ptr<facebook::react::TurboModule>)getTurboModule:(const facebook::react::ObjCTurboModule::InitParams &)params {
-  return std::make_shared<facebook::react::NativeA11yAnnounceModuleSpecJSI>(params);
+
+- (void)announce:(NSString *)message
+         options:(JS::NativeA11yAnnounceModule::AnnounceOptions &)options
+         resolve:(RCTPromiseResolveBlock)resolve
+          reject:(RCTPromiseRejectBlock)reject
+{
+    NSMutableDictionary *opts = [NSMutableDictionary new];
+
+    if (options.calm().has_value())        opts[@"calm"]        = @(*options.calm());
+    if (options.priority())                opts[@"priority"]    = options.priority();
+    if (options.queue().has_value())       opts[@"queue"]       = @(*options.queue());
+    if (options.delayMs().has_value())     opts[@"delayMs"]     = @(*options.delayMs());
+    // Speech options (flat at bridge level, grouped under `speech` in JS API)
+    if (options.language())                opts[@"language"]    = options.language();
+    if (options.pitch().has_value())       opts[@"pitch"]       = @(*options.pitch());
+    if (options.spellOut().has_value())    opts[@"spellOut"]    = @(*options.spellOut());
+    if (options.punctuation().has_value()) opts[@"punctuation"] = @(*options.punctuation());
+    if (options.ipaNotation())             opts[@"ipaNotation"] = options.ipaNotation();
+
+    [self _announceMessage:message opts:opts resolve:resolve reject:reject];
 }
 
+#else
+
+RCT_EXPORT_METHOD(announce:(NSString *)message
+                   options:(NSDictionary *)options
+                   resolve:(RCTPromiseResolveBlock)resolve
+                    reject:(RCTPromiseRejectBlock)reject)
+{
+    NSDictionary *opts = ([options isKindOfClass:[NSDictionary class]]) ? options : @{};
+    [self _announceMessage:message opts:opts resolve:resolve reject:reject];
+}
+
+#endif // RCT_NEW_ARCH_ENABLED
+
+
+// ─────────────────────────────────────────────────────────────────────────────
+// MARK: - cancel / cancelAll
+// ─────────────────────────────────────────────────────────────────────────────
+
+RCT_EXPORT_METHOD(cancel:(NSString *)announcementId
+                  resolve:(RCTPromiseResolveBlock)resolve
+                   reject:(RCTPromiseRejectBlock)reject)
+{
+    [self _resolveId:announcementId status:@"cancelled"];
+    resolve(@{ @"id": announcementId ?: @"", @"status": @"cancelled" });
+}
+
+RCT_EXPORT_METHOD(cancelAll:(RCTPromiseResolveBlock)resolve
+                      reject:(RCTPromiseRejectBlock)reject)
+{
+    [[RNAOA11yAnnounceService shared] cancelAll];
+
+    NSDictionary<NSString *, RNAOPendingAnnouncement *> *snapshot = [self.pending copy];
+    [self.pending removeAllObjects];
+    self.currentDirectId = nil;
+
+    for (NSString *aid in snapshot) {
+        snapshot[aid].resolve(@{ @"id": aid, @"status": @"cancelled" });
+    }
+    resolve(@{ @"id": @"", @"status": @"cancelled" });
+}
+
+
+// ─────────────────────────────────────────────────────────────────────────────
+// MARK: - VoiceOver finish notification (direct mode only)
+// ─────────────────────────────────────────────────────────────────────────────
+
+- (void)_handleAnnouncementFinished:(NSNotification *)note {
+    NSString *directId = self.currentDirectId;
+    if (!directId) return;
+
+    RNAOPendingAnnouncement *entry = self.pending[directId];
+    if (!entry) return;
+
+    NSString *spokenText = note.userInfo[UIAccessibilityAnnouncementKeyStringValue];
+    if (![entry.text isEqualToString:spokenText]) return;
+
+    BOOL wasSuccessful = [note.userInfo[UIAccessibilityAnnouncementKeyWasSuccessful] boolValue];
+    [self _resolveId:directId status:wasSuccessful ? @"spoken" : @"fired"];
+}
+
+
+// ─────────────────────────────────────────────────────────────────────────────
+// MARK: - Resolve helper
+// ─────────────────────────────────────────────────────────────────────────────
+
+- (void)_resolveId:(NSString *)announcementId status:(NSString *)status {
+    if (!announcementId) return;
+    RNAOPendingAnnouncement *entry = self.pending[announcementId];
+    if (!entry) return;
+
+    [self.pending removeObjectForKey:announcementId];
+    if ([self.currentDirectId isEqualToString:announcementId]) {
+        self.currentDirectId = nil;
+    }
+    entry.resolve(@{ @"id": announcementId, @"status": status });
+}
+
+
+#ifdef RCT_NEW_ARCH_ENABLED
+- (std::shared_ptr<facebook::react::TurboModule>)getTurboModule:
+    (const facebook::react::ObjCTurboModule::InitParams &)params
+{
+    return std::make_shared<facebook::react::NativeA11yAnnounceModuleSpecJSI>(params);
+}
 #endif
-@end
 
+@end

package/ios/services/RNAOA11yAnnounceService/RNAOA11yAnnounceService.h

@@ -15,10 +15,20 @@
 
 + (instancetype)shared;
 
+/**
+ * Enqueues `announcement` and schedules a navigation-aware debounced post.
+ * `onFired` is called on the main queue when the service actually speaks
+ * the announcement. Pass nil if no completion callback is needed.
+ * If cancelAll is called before the service fires, `onFired` is NOT called.
+ */
+- (void)announce:(NSString *)announcement onFired:(nullable dispatch_block_t)onFired;
+
+/** Convenience — equivalent to announce:onFired:nil. */
 - (void)announce:(NSString *)announcement;
+
+- (void)cancelAll;
 - (void)temporarilyLockAnnounce;
 - (void)temporarilyLockAnnounce:(NSTimeInterval)interval;
-//@property (nonatomic, assign) BOOL announceLock;
 
 @end