react-native-a11y-order 0.9.1 → 0.11.0-rc1

package/src/components/A11yPaneTitle/A11yPaneTitle.tsx

@@ -1,22 +1,16 @@
 import React from 'react';
-import { type ViewProps } from 'react-native';
 import A11yPaneTitleNative from '../../nativeSpecs/A11yPaneTitleNativeComponent';
+import type {
+  A11yPaneTitleProps,
+  A11yPaneType,
+  A11yScreenChangeProps,
+} from './A11yPaneTitle.types';
 
-enum PaneEnum {
-  activity = 0,
-  pane = 1,
-  announce = 2,
-}
-
-type PaneType = keyof typeof PaneEnum;
-
-type A11yPaneTitleType = React.PropsWithChildren<{
-  title?: string;
-  detachMessage?: string;
-  type?: PaneType;
-  withFocusRestore?: boolean;
-  displayed?: boolean;
-}>;
+const PaneTypeValue: Record<A11yPaneType, number> = {
+  activity: 0,
+  pane: 1,
+  announce: 2,
+};
 
 export const A11yPaneTitle = ({
   title,
@@ -25,21 +19,21 @@ export const A11yPaneTitle = ({
   children,
   displayed,
   withFocusRestore = true,
-}: ViewProps & A11yPaneTitleType) => {
+}: A11yPaneTitleProps) => {
   if (displayed === false) return null;
 
   return (
     <A11yPaneTitleNative
       title={title}
       detachMessage={detachMessage}
-      type={PaneEnum[type]}
+      type={PaneTypeValue[type]}
       children={children}
       withFocusRestore={withFocusRestore}
     />
   );
 };
 
-export const A11yScreenChange = (props: Omit<A11yPaneTitleType, 'type'>) => (
+export const A11yScreenChange = (props: A11yScreenChangeProps) => (
   <A11yPaneTitle
     title={props.title}
     detachMessage={props.detachMessage}

package/src/components/A11yPaneTitle/A11yPaneTitle.types.ts

@@ -0,0 +1,58 @@
+import React from 'react';
+
+/**
+ * Controls the native accessibility announcement mechanism.
+ *
+ * - `'pane'`      — layout-changed notification with a title (default, use for panels/sheets)
+ * - `'activity'`  — screen-change notification (use for full-screen transitions)
+ * - `'announce'`  — plain announcement with no focus shift (use for status updates)
+ */
+export type A11yPaneType = 'activity' | 'pane' | 'announce';
+
+/**
+ * Props for {@link A11y.PaneTitle} — announces a screen or panel transition to
+ * VoiceOver / TalkBack and optionally restores focus when the view unmounts.
+ */
+export type A11yPaneTitleProps = React.PropsWithChildren<{
+  /**
+   * The title announced to the screen reader when this component mounts.
+   */
+  title?: string;
+
+  /**
+   * A message announced to the screen reader when this component unmounts.
+   * Use to signal the end of a flow, e.g. `"Modal closed"` or `"Drawer closed"`.
+   */
+  detachMessage?: string;
+
+  /**
+   * Controls the native announcement mechanism. Defaults to `'pane'`.
+   *
+   * - `'pane'`     — layout-changed notification with a title (panels, sheets)
+   * - `'activity'` — screen-change notification (full-screen navigation)
+   * - `'announce'` — plain announcement with no focus shift (status updates)
+   */
+  type?: A11yPaneType;
+
+  /**
+   * When `true`, VoiceOver / TalkBack restores focus to the previously focused
+   * element when this component unmounts.
+   *
+   * Defaults to `true`.
+   */
+  withFocusRestore?: boolean;
+
+  /**
+   * When `false`, the component renders nothing and posts no announcement.
+   * Use this to conditionally suppress the view without unmounting its subtree.
+   *
+   * Defaults to `true`.
+   */
+  displayed?: boolean;
+}>;
+
+/**
+ * Props for {@link A11y.ScreenChange} — shorthand for `A11y.PaneTitle` with
+ * `type="activity"` pre-set for full-screen navigation transitions.
+ */
+export type A11yScreenChangeProps = Omit<A11yPaneTitleProps, 'type'>;

package/src/components/A11yView/A11yView.tsx

@@ -1,63 +1,8 @@
-import React from 'react';
-import A11yViewNativeComponent from '../../nativeSpecs/A11yViewNativeComponent';
-import type { A11yViewProps } from '../../types/A11yView.types';
-
-// Unknown ref type for better react-native support
-type ViewRefType = {};
-
-export const A11yView = React.memo(
-  React.forwardRef<ViewRefType, A11yViewProps>(
-    (
-      {
-        onScreenReaderFocused,
-        onScreenReaderSubViewFocusChange,
-        onScreenReaderSubViewFocused,
-        onScreenReaderSubViewBlurred,
-        onScreenReaderDescendantFocusChanged,
-        ...props
-      },
-      ref
-    ) => {
-      const hasHandler = Boolean(
-        onScreenReaderSubViewBlurred ||
-          onScreenReaderSubViewFocused ||
-          onScreenReaderSubViewFocusChange
-      );
-
-      const onScreenReaderChangeHandler = React.useCallback(
-        (event: { nativeEvent: { isFocused: boolean } }) => {
-          onScreenReaderSubViewFocusChange?.(event.nativeEvent.isFocused);
-          if (event.nativeEvent.isFocused) {
-            onScreenReaderSubViewFocused?.();
-          } else {
-            onScreenReaderSubViewBlurred?.();
-          }
-        },
-        [
-          onScreenReaderSubViewFocusChange,
-          onScreenReaderSubViewBlurred,
-          onScreenReaderSubViewFocused,
-        ]
-      );
-
-      const onScreenReaderHandlerProp = hasHandler
-        ? onScreenReaderChangeHandler
-        : undefined;
-
-      return (
-        <A11yViewNativeComponent
-          {...props}
-          ref={ref as React.Ref<any>}
-          descendantFocusChangedEnabled={Boolean(
-            onScreenReaderDescendantFocusChanged
-          )}
-          onScreenReaderFocused={onScreenReaderFocused}
-          onScreenReaderFocusChange={onScreenReaderHandlerProp}
-          onScreenReaderDescendantFocusChanged={
-            onScreenReaderDescendantFocusChanged
-          }
-        />
-      );
-    }
-  )
-);
+import { A11yIndex } from '../A11yIndex/A11yIndex';
+
+/**
+ * Standalone focus-tracking view with no ordering context.
+ * Use when you need screen reader focus events but no position in a sequence.
+ * For ordered elements, use {@link A11yIndex} inside an Order container.
+ */
+export const A11yView = A11yIndex;

package/src/components/A11yView/A11yView.types.ts

@@ -0,0 +1,11 @@
+import type { A11yIndexProps } from '../A11yIndex/A11yIndex.types';
+
+export type { ScreenReaderDescendantFocusChangedEvent } from '../A11yIndex/A11yIndex.types';
+
+/**
+ * Props for {@link A11y.View} — a standalone focus-tracking view with no ordering context.
+ *
+ * All screen reader focus events from {@link A11yIndexProps} are available.
+ * `index` and `orderType` are omitted because they only apply inside an `A11y.Order` sequence.
+ */
+export type A11yViewProps = Omit<A11yIndexProps, 'index' | 'orderType'>;

package/src/index.ts

@@ -1,7 +1,5 @@
 import { A11yIndex } from './components/A11yIndex/A11yIndex';
-import { A11yIndexSequence } from './components/A11ySequence/A11ySequence';
-import { A11yGroup } from './components/A11yGroup/A11yGroup';
-import { A11yUIContainer } from './components/A11yUIContainer/A11yUIContainer';
+import { A11yOrder } from './components/A11yOrder/A11yOrder';
 import {
   A11yPaneTitle,
   A11yScreenChange,
@@ -9,34 +7,54 @@ import {
 import { A11yView } from './components/A11yView/A11yView';
 import { A11yFocusFrame } from './components/A11yLock/A11yFocusFrame/A11yFocusFrame';
 import { A11yFocusTrap } from './components/A11yLock/A11yFocusTrap/A11yFocusTrap';
+import { A11yCard } from './components/A11yCard/A11yCard';
 
+// ─── Component props ──────────────────────────────────────────────────────────
+
+export type { A11yCardProps } from './components/A11yCard/A11yCard.types';
+export type { A11yOrderProps } from './components/A11yOrder/A11yOrder.types';
 export type {
-  IndexCommands,
-  A11yOrderType,
-  A11yOrderTypeEnum,
   A11yIndexProps,
-} from './types/A11yIndex.types';
-
+  A11yOrderType,
+  IndexCommands,
+} from './components/A11yIndex/A11yIndex.types';
+export { A11yOrderTypeEnum } from './components/A11yIndex/A11yIndex.types';
 export type {
-  A11yContainerTypeEnum,
-  A11yUIContainerType,
-  A11yUIContainerProps,
-} from './types/A11yUIContainerView.types';
-
-export type { ScreenReaderDescendantFocusChangedEvent } from './types/A11yView.types';
+  A11yViewProps,
+  ScreenReaderDescendantFocusChangedEvent,
+} from './components/A11yView/A11yView.types';
+export type {
+  A11yFocusTrapProps,
+  A11yFocusFrameProps,
+} from './components/A11yLock/A11yLock.types';
+export type {
+  A11yPaneTitleProps,
+  A11yScreenChangeProps,
+  A11yPaneType,
+} from './components/A11yPaneTitle/A11yPaneTitle.types';
 
-export type { A11yViewProps } from './types/A11yView.types';
+// ─── Namespace ────────────────────────────────────────────────────────────────
 
 export const A11y = {
-  Order: A11yIndexSequence,
+  Order: A11yOrder,
   Index: A11yIndex,
-  Group: A11yGroup,
-  Container: A11yUIContainer,
+  View: A11yView,
   PaneTitle: A11yPaneTitle,
   ScreenChange: A11yScreenChange,
-  View: A11yView,
   FocusFrame: A11yFocusFrame,
   FocusTrap: A11yFocusTrap,
+  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

@@ -4,30 +4,23 @@ import { View } from 'react-native';
 export type {
   IndexCommands,
   A11yOrderType,
-  A11yOrderTypeEnum,
   A11yIndexProps,
-} from './types/A11yIndex.types';
+} from './components/A11yIndex/A11yIndex.types';
+export { A11yOrderTypeEnum } from './components/A11yIndex/A11yIndex.types';
 
-export type {
-  A11yContainerTypeEnum,
-  A11yUIContainerType,
-  A11yUIContainerProps,
-} from './types/A11yUIContainerView.types';
-
-export type { ScreenReaderDescendantFocusChangedEvent } from './types/A11yView.types';
+export type { ScreenReaderDescendantFocusChangedEvent } from './components/A11yView/A11yView.types';
 
-export type { A11yViewProps } from './types/A11yView.types';
+export type { A11yViewProps } from './components/A11yView/A11yView.types';
 
 export const A11y = {
   Order: View,
-  Group: View,
   Index: A11yIndex,
-  Container: View,
+  View: View,
   PaneTitle: View,
   ScreenChange: View,
-  View: View,
   FocusFrame: View,
   FocusTrap: View,
+  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/{lib/module/nativeSpecs/A11yGroupNativeComponent.ts → src/nativeSpecs/A11yCardNativeComponent.ts}

@@ -2,8 +2,8 @@ import type { ViewProps } from 'react-native';
 // eslint-disable-next-line @react-native/no-deep-imports
 import codegenNativeComponent from 'react-native/Libraries/Utilities/codegenNativeComponent';
 
-export interface A11yGroupNativeComponentProps extends ViewProps {}
+export interface A11yCardNativeComponentProps extends ViewProps {}
 
-export default codegenNativeComponent<A11yGroupNativeComponentProps>(
-  'A11yGroupView'
+export default codegenNativeComponent<A11yCardNativeComponentProps>(
+  'A11yCardView'
 );

package/src/nativeSpecs/A11yIndexNativeComponent.ts

@@ -15,14 +15,22 @@ export type ScreenReaderFocusChange = Readonly<{
 
 export type ScreenReaderDescendantFocusChanged = Readonly<{
   status: string;
+  nativeId?: string;
 }>;
 
 export interface A11yIndexNativeComponentProps extends ViewProps {
-  orderIndex: Int32;
-  orderKey: string;
-  orderFocusType: Int32;
+  orderIndex?: Int32;
+  orderKey?: string;
+  orderFocusType?: Int32;
+  shouldGroupAccessibilityChildren?: Int32;
 
+  descendantFocusChangedEnabled?: boolean;
+
+  onScreenReaderFocused?: DirectEventHandler<{}>;
+  onScreenReaderDescendantFocusChanged?: DirectEventHandler<ScreenReaderDescendantFocusChanged>;
   onScreenReaderFocusChange?: DirectEventHandler<ScreenReaderFocusChange>;
+
+  containerType?: Int32;
 }
 
 export interface NativeCommands {

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/views/A11yGroupView/A11yGroupViewManager.java

@@ -1,25 +0,0 @@
-package com.a11yorder.views.A11yGroupView;
-
-import android.view.ViewGroup;
-
-import androidx.annotation.NonNull;
-
-import com.a11yorder.A11yGroupViewManagerSpec;
-import com.facebook.react.uimanager.ThemedReactContext;
-import com.facebook.react.views.view.ReactViewGroup;
-
-public class A11yGroupViewManager extends A11yGroupViewManagerSpec<ViewGroup> {
-  public static final String REACT_CLASS = "A11yGroupView";
-
-  @NonNull
-  @Override
-  public String getName() {
-    return REACT_CLASS;
-  }
-
-  @NonNull
-  @Override
-  protected ReactViewGroup createViewInstance(@NonNull ThemedReactContext context) {
-    return new ReactViewGroup(context);
-  }
-}

package/android/src/main/java/com/a11yorder/views/A11yUIContainerView/A11yUIContainerViewManager.java

@@ -1,30 +0,0 @@
-package com.a11yorder.views.A11yUIContainerView;
-
-import android.view.ViewGroup;
-
-import androidx.annotation.NonNull;
-
-import com.a11yorder.A11yUIContainerViewManagerSpec;
-import com.facebook.react.uimanager.ThemedReactContext;
-import com.facebook.react.views.view.ReactViewGroup;
-
-public class A11yUIContainerViewManager extends A11yUIContainerViewManagerSpec<ViewGroup> {
-  public static final String REACT_CLASS = "A11yUIContainer";
-
-  @NonNull
-  @Override
-  public String getName() {
-    return REACT_CLASS;
-  }
-
-  @NonNull
-  @Override
-  protected ReactViewGroup createViewInstance(@NonNull ThemedReactContext context) {
-    return new ReactViewGroup(context);
-  }
-
-  @Override
-  public void setContainerType(ViewGroup view, int value) {
-    //stub
-  }
-}