react-native-a11y-order 0.11.0-rc → 0.11.0

package/src/modules/A11yAnnounceModule.android.ts

@@ -1,5 +1,21 @@
+// Android stub — bypasses the native bridge, uses the built-in API directly.
 import { AccessibilityInfo } from 'react-native';
 
-export const A11yModule = {
-  announce: AccessibilityInfo.announceForAccessibility,
+export const ScreenReader = {
+  announce: (message: string) => {
+    AccessibilityInfo.announceForAccessibility(message);
+    return Promise.resolve({ id: '', status: 'fired' as const });
+  },
+  cancel: () => Promise.resolve({ id: '', status: 'cancelled' as const }),
+  cancelAll: () => Promise.resolve({ id: '', status: 'cancelled' as const }),
 };
+
+export const announce = (message: string) => {
+  AccessibilityInfo.announceForAccessibility(message);
+  return Promise.resolve({ id: '', status: 'fired' as const });
+};
+
+export const cancel = () =>
+  Promise.resolve({ id: '', status: 'cancelled' as const });
+export const cancelAll = () =>
+  Promise.resolve({ id: '', status: 'cancelled' as const });

package/src/modules/A11yAnnounceModule.ts

@@ -1,19 +1,21 @@
 import { NativeModules, Platform } from 'react-native';
+import NativeA11yAnnounceModule from '../nativeSpecs/NativeA11yAnnounceModule';
 
 const LINKING_ERROR =
-  `The package 'react-native-external-keyboard' doesn't seem to be linked. Make sure: \n\n${Platform.select(
+  `The package 'react-native-a11y-order' doesn't seem to be linked. Make sure: \n\n${Platform.select(
     { ios: "- You have run 'pod install'\n", default: '' }
   )}- You rebuilt the app after installing the package\n` +
   `- You are not using Expo Go\n`;
 
 // @ts-expect-error
 const isTurboModuleEnabled = global.__turboModuleProxy != null;
-const A11yAnnounceModule = isTurboModuleEnabled
-  ? require('../nativeSpecs/NativeA11yAnnounceModule').default
+
+const A11yAnnounceNative = isTurboModuleEnabled
+  ? NativeA11yAnnounceModule
   : NativeModules.A11yAnnounceModule;
 
-export const A11yAnnounce =
-  A11yAnnounceModule ||
+const A11yAnnounceProxy: typeof NativeA11yAnnounceModule =
+  A11yAnnounceNative ??
   new Proxy(
     {},
     {
@@ -23,10 +25,152 @@ export const A11yAnnounce =
     }
   );
 
-export function announce(message: string) {
-  A11yAnnounce.announce(message);
+// ─── Types ────────────────────────────────────────────────────────────────────
+
+export type AnnouncePriority = 'low' | 'default' | 'high';
+
+export type AnnounceStatus = 'spoken' | 'fired' | 'cancelled';
+
+export type AnnounceOptions = {
+  /**
+   * Controls urgency. iOS 17+: maps to `UIAccessibilityPriority`.
+   *
+   * - `'low'`     — spoken only when the screen reader is fully idle
+   * - `'default'` — standard queued announcement (default)
+   * - `'high'`    — may preempt lower-priority pending items
+   */
+  priority?: AnnouncePriority;
+
+  /**
+   * When `true`, waits for current speech before speaking.
+   * When `false`, may interrupt current speech.
+   * Default: `true`
+   */
+  queue?: boolean;
+
+  /**
+   * Navigation-aware mode. When `true`, the announcement waits for:
+   * - Active navigation transitions to finish (1 s lock after screen change)
+   * - The screen reader to have a focused element
+   * - A 300 ms debounce to prevent overlap with focus changes
+   *
+   * Promise resolves when the service **actually fires** the announcement
+   * (not just when it's enqueued), so `await` is meaningful.
+   * Default: `false`
+   */
+  calm?: boolean;
+
+  /**
+   * Explicit delay in milliseconds before the announcement is posted.
+   * In `calm` mode the service manages its own timing; this is ignored.
+   * Default: `0`
+   */
+  delayMs?: number;
+
+  /**
+   * iOS-only speech characteristics. No-op on Android.
+   * Only relevant in direct mode (`calm: false`).
+   */
+  speech?: {
+    /**
+     * BCP-47 language tag (e.g. `'fr-FR'`). Defaults to the system language.
+     * @platform ios
+     */
+    language?: string;
+
+    /**
+     * Voice pitch multiplier, range `0.0`–`2.0`. Default: `1.0`.
+     * @platform ios
+     */
+    pitch?: number;
+
+    /**
+     * Spell each character individually.
+     * Useful for codes, CAPTCHAs, or abbreviations.
+     * @platform ios
+     */
+    spellOut?: boolean;
+
+    /**
+     * Read punctuation marks aloud (e.g. "comma", "period").
+     * @platform ios
+     */
+    punctuation?: boolean;
+
+    /**
+     * IPA pronunciation hint applied to the entire string.
+     * @platform ios
+     */
+    ipaNotation?: string;
+  };
+};
+
+export type AnnouncementResult = {
+  /** UUID assigned at enqueue time. */
+  id: string;
+  /**
+   * - `'spoken'`    — VoiceOver confirmed full speech (iOS direct mode only).
+   * - `'fired'`     — posted to the screen reader; completion not confirmed.
+   *                   Always the case on Android. iOS calm mode resolves here
+   *                   once the service actually fires the announcement.
+   * - `'cancelled'` — explicitly cancelled via `cancel()` or `cancelAll()`.
+   */
+  status: AnnounceStatus;
+};
+
+// ─── Core API ─────────────────────────────────────────────────────────────────
+
+/**
+ * Posts a screen reader announcement.
+ *
+ * **calm mode** (`calm: true`): navigation-aware — waits for transitions to
+ * settle and for VoiceOver/TalkBack to have a focused element. Promise
+ * resolves when the announcement is **actually fired** (not just enqueued).
+ *
+ * **direct mode** (`calm: false`, default): posts immediately with speech
+ * attributes. On iOS, Promise resolves when VoiceOver confirms speech finished
+ * (`status: 'spoken'`) or was interrupted (`status: 'fired'`).
+ * On Android, always resolves immediately with `status: 'fired'`.
+ */
+export function announce(
+  message: string,
+  options?: AnnounceOptions
+): Promise<AnnouncementResult> {
+  const { speech, ...rest } = options ?? {};
+  return A11yAnnounceProxy!.announce(message, {
+    ...rest,
+    ...speech,
+  }) as Promise<AnnouncementResult>;
 }
 
-export const A11yModule = {
-  announce,
+/**
+ * Cancels the announcement with the given `id`.
+ * In calm mode, removes it from the service queue if not yet fired.
+ * In direct mode, interrupts the active announcement if it matches.
+ */
+export function cancel(id: string): Promise<AnnouncementResult> {
+  return A11yAnnounceProxy!.cancel(id) as Promise<AnnouncementResult>;
+}
+
+/**
+ * Cancels all pending and active announcements.
+ * Calm-mode promises resolve with `status: 'cancelled'`.
+ */
+export function cancelAll(): Promise<AnnouncementResult> {
+  return A11yAnnounceProxy!.cancelAll() as Promise<AnnouncementResult>;
+}
+
+// ─── Namespace export (backward-compatible) ───────────────────────────────────
+
+export const ScreenReader = {
+  /**
+   * Posts a navigation-aware announcement (calm mode).
+   * Waits for transitions to finish before speaking.
+   * Promise resolves when the announcement is actually fired.
+   */
+  announce: (message: string, options?: AnnounceOptions) =>
+    announce(message, { calm: true, ...options }),
+
+  cancel,
+  cancelAll,
 };

package/src/nativeSpecs/A11yIndexNativeComponent.ts

@@ -24,7 +24,6 @@ export interface A11yIndexNativeComponentProps extends ViewProps {
   orderFocusType?: Int32;
   shouldGroupAccessibilityChildren?: Int32;
 
-  autoFocus?: boolean;
   descendantFocusChangedEnabled?: boolean;
 
   onScreenReaderFocused?: DirectEventHandler<{}>;

package/src/nativeSpecs/NativeA11yAnnounceModule.ts

@@ -1,8 +1,38 @@
 import type { TurboModule } from 'react-native';
 import { TurboModuleRegistry } from 'react-native';
 
+// Speech options are kept flat here (bridge contract).
+// The JS API groups them under `speech: {}` and flattens before calling native.
+type AnnounceOptions = Readonly<{
+  priority?: string;
+  queue?: boolean;
+  calm?: boolean;
+  delayMs?: number;
+  language?: string;
+  pitch?: number;
+  spellOut?: boolean;
+  punctuation?: boolean;
+  ipaNotation?: string;
+}>;
+
+type AnnouncementResult = Readonly<{
+  id: string;
+  // 'spoken'    — VoiceOver confirmed full speech (iOS direct only)
+  // 'fired'     — posted to screen reader; no completion confirmation
+  // 'cancelled' — explicitly cancelled via cancel() / cancelAll()
+  status: string;
+}>;
+
 export interface Spec extends TurboModule {
-  announce(message: string): void;
+  /** Enqueues a screen reader announcement. Resolves with AnnouncementResult. */
+  announce(
+    message: string,
+    options?: AnnounceOptions
+  ): Promise<AnnouncementResult>;
+  /** Cancels a specific announcement by its id. Resolves with the cancelled item's result. */
+  cancel(id: string): Promise<AnnouncementResult>;
+  /** Drains the queue and interrupts current speech. */
+  cancelAll(): Promise<AnnouncementResult>;
 }
 
 export default TurboModuleRegistry.get<Spec>('A11yAnnounceModule');

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

@@ -1,61 +0,0 @@
-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 A11yAutoFocusView extends A11yScreenReaderView implements A11yFocusProtocol {
-  private final A11yFocusDelegate a11yFocusDelegate;
-  private Boolean autoFocus = false;
-  private Boolean autoFocusOnce = false;
-  private Boolean hasBeenFocused = false;
-
-  public A11yAutoFocusView(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 setAutoFocus(Boolean value) {
-    this.autoFocus = value;
-  }
-
-  public void focus() {
-    a11yFocusDelegate.requestFocus();
-  }
-
-  @Override
-  public boolean onRequestSendAccessibilityEvent(View child, AccessibilityEvent event) {
-    int eventType = event.getEventType();
-
-    if (eventType == AccessibilityEvent.TYPE_VIEW_ACCESSIBILITY_FOCUSED && autoFocus && !hasBeenFocused) {
-      hasBeenFocused = true;
-      a11yFocusDelegate.onFocused();
-    }
-
-    return super.onRequestSendAccessibilityEvent(child, event);
-  }
-
-  @Override
-  protected void onAttachedToWindow() {
-    super.onAttachedToWindow();
-    if (autoFocus && !autoFocusOnce) {
-      autoFocusOnce = true;
-
-      if (!isViewFocused()) {
-        hasBeenFocused = false;
-        a11yFocusDelegate.requestFocus();
-      }
-    }
-  }
-}