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

package/lib/typescript/src/nativeSpecs/NativeA11yAnnounceModule.d.ts

@@ -1,6 +1,26 @@
 import type { TurboModule } from 'react-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;
+    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>;
 }
 declare const _default: Spec | null | undefined;
 export default _default;

package/lib/typescript/src/nativeSpecs/NativeA11yAnnounceModule.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"NativeA11yAnnounceModule.d.ts","sourceRoot":"","sources":["../../../../src/nativeSpecs/NativeA11yAnnounceModule.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,cAAc,CAAC;AAGhD,MAAM,WAAW,IAAK,SAAQ,WAAW;IACvC,QAAQ,CAAC,OAAO,EAAE,MAAM,GAAG,IAAI,CAAC;CACjC;;AAED,wBAAmE"}
+{"version":3,"file":"NativeA11yAnnounceModule.d.ts","sourceRoot":"","sources":["../../../../src/nativeSpecs/NativeA11yAnnounceModule.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,cAAc,CAAC;AAKhD,KAAK,eAAe,GAAG,QAAQ,CAAC;IAC9B,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,KAAK,CAAC,EAAE,OAAO,CAAC;IAChB,IAAI,CAAC,EAAE,OAAO,CAAC;IACf,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,QAAQ,CAAC,EAAE,OAAO,CAAC;IACnB,WAAW,CAAC,EAAE,OAAO,CAAC;IACtB,WAAW,CAAC,EAAE,MAAM,CAAC;CACtB,CAAC,CAAC;AAEH,KAAK,kBAAkB,GAAG,QAAQ,CAAC;IACjC,EAAE,EAAE,MAAM,CAAC;IAIX,MAAM,EAAE,MAAM,CAAC;CAChB,CAAC,CAAC;AAEH,MAAM,WAAW,IAAK,SAAQ,WAAW;IACvC,+EAA+E;IAC/E,QAAQ,CACN,OAAO,EAAE,MAAM,EACf,OAAO,CAAC,EAAE,eAAe,GACxB,OAAO,CAAC,kBAAkB,CAAC,CAAC;IAC/B,4FAA4F;IAC5F,MAAM,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC,kBAAkB,CAAC,CAAC;IAChD,sDAAsD;IACtD,SAAS,IAAI,OAAO,CAAC,kBAAkB,CAAC,CAAC;CAC1C;;AAED,wBAAmE"}

package/package.json

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

package/src/components/A11yCard/A11yCard.ios.tsx

@@ -22,6 +22,7 @@ export const A11yCard = ({
         {...accessibility}
         accessible
         pointerEvents="none"
+        collapsable={false}
         onAccessibilityTap={onPress}
         style={styles.overlay}
       />
@@ -40,5 +41,11 @@ export const A11yCard = ({
 
 const styles = StyleSheet.create({
   container: { position: 'relative' },
-  overlay: StyleSheet.absoluteFillObject,
+  overlay: {
+    position: 'absolute',
+    top: 0,
+    left: 0,
+    right: 0,
+    bottom: 0,
+  },
 });

package/src/components/A11yIndex/A11yIndex.tsx

@@ -103,16 +103,17 @@ function useOrderProps(
   }
 
   const resolvedOrderType = orderType ?? 'default';
-  const importantForAccessibilityFallback =
-    resolvedOrderType === 'default' ? ('yes' as const) : undefined;
+  const isDefaultOrderType = resolvedOrderType === 'default';
+
+  const importantForAccessibility =
+    hasOrderInfo && isDefaultOrderType ? 'yes' : importantForAccessibilityProp;
 
   return {
     orderKey,
     orderFocusType: hasOrderInfo
       ? A11yOrderTypeEnum[resolvedOrderType]
       : undefined,
-    importantForAccessibility:
-      importantForAccessibilityProp ?? importantForAccessibilityFallback,
+    importantForAccessibility,
   };
 }
 

package/src/components/A11yIndex/A11yIndex.types.ts

@@ -88,11 +88,6 @@ export type A11yIndexProps = ViewProps & {
    */
   shouldGroupAccessibilityChildren?: boolean;
 
-  /**
-   * When `true`, requests screen reader focus on this element immediately after mount.
-   */
-  autoFocus?: boolean;
-
   /**
    * Called when the screen reader focuses this element directly (not a descendant).
    */

package/src/index.ts

@@ -46,4 +46,15 @@ export const A11y = {
   Card: A11yCard,
 };
 
-export { A11yModule } from './modules/A11yAnnounceModule';
+export {
+  ScreenReader,
+  announce,
+  cancel,
+  cancelAll,
+} from './modules/A11yAnnounceModule';
+export type {
+  AnnouncePriority,
+  AnnounceStatus,
+  AnnounceOptions,
+  AnnouncementResult,
+} from './modules/A11yAnnounceModule';

package/src/index.web.ts

@@ -23,4 +23,4 @@ export const A11y = {
   Card: View,
 };
 
-export { A11yModule } from './modules/A11yAnnounceModule';
+export { ScreenReader } from './modules/A11yAnnounceModule';

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();
-      }
-    }
-  }
-}