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

package/src/components/A11yIndex/A11yIndex.tsx

@@ -1,4 +1,5 @@
 import React, { useImperativeHandle, useRef } from 'react';
+import type { ViewProps } from 'react-native';
 import { A11ySequenceOrderContext } from '../../context/A11ySequenceOrderContext';
 import A11yIndexView, {
   Commands,
@@ -6,8 +7,113 @@ import A11yIndexView, {
 import {
   type A11yIndexProps,
   A11yOrderTypeEnum,
+  type A11yOrderType,
   type IndexCommands,
-} from '../../types/A11yIndex.types';
+  A11yContainerTypeEnum,
+} from './A11yIndex.types';
+
+type ScreenReaderCallbacks = Pick<
+  A11yIndexProps,
+  | 'onScreenReaderFocused'
+  | 'onScreenReaderSubViewFocusChange'
+  | 'onScreenReaderSubViewFocused'
+  | 'onScreenReaderSubViewBlurred'
+  | 'onScreenReaderDescendantFocusChanged'
+>;
+
+function useScreenReaderProps({
+  onScreenReaderFocused,
+  onScreenReaderSubViewFocusChange,
+  onScreenReaderSubViewFocused,
+  onScreenReaderSubViewBlurred,
+  onScreenReaderDescendantFocusChanged,
+}: ScreenReaderCallbacks) {
+  const hasHandler = Boolean(
+    onScreenReaderSubViewBlurred ||
+      onScreenReaderSubViewFocused ||
+      onScreenReaderSubViewFocusChange
+  );
+
+  const onScreenReaderFocusChange = React.useCallback(
+    (event: { nativeEvent: { isFocused: boolean } }) => {
+      const { isFocused } = event.nativeEvent;
+      onScreenReaderSubViewFocusChange?.(isFocused);
+      if (isFocused) {
+        onScreenReaderSubViewFocused?.();
+      } else {
+        onScreenReaderSubViewBlurred?.();
+      }
+    },
+    [
+      onScreenReaderSubViewFocusChange,
+      onScreenReaderSubViewBlurred,
+      onScreenReaderSubViewFocused,
+    ]
+  );
+
+  return {
+    onScreenReaderFocused,
+    onScreenReaderFocusChange: hasHandler
+      ? onScreenReaderFocusChange
+      : undefined,
+    descendantFocusChangedEnabled: Boolean(
+      onScreenReaderDescendantFocusChanged
+    ),
+    onScreenReaderDescendantFocusChanged,
+  };
+}
+
+function useFocusRef(ref: React.ForwardedRef<IndexCommands>) {
+  const localRef = useRef<React.ComponentRef<typeof A11yIndexView>>(null);
+
+  useImperativeHandle(ref, () => {
+    const native = localRef.current as unknown as Record<string, unknown>;
+
+    return new Proxy({} as IndexCommands, {
+      get(_target, prop: string) {
+        if (prop === 'focus') {
+          return () => {
+            if (localRef.current) {
+              // @ts-expect-error Commands.focus type is too generic in codegen
+              Commands.focus(localRef.current);
+            }
+          };
+        }
+        return native?.[prop];
+      },
+    });
+  });
+
+  return localRef;
+}
+
+function useOrderProps(
+  index: number | undefined,
+  orderType: A11yOrderType | undefined,
+  importantForAccessibilityProp: ViewProps['importantForAccessibility']
+) {
+  const orderKey = React.useContext(A11ySequenceOrderContext);
+  const hasOrderInfo = typeof index === 'number' || !!orderKey;
+
+  if (hasOrderInfo && !orderKey) {
+    throw new Error(
+      '<A11y.Index> element should be used inside of <A11y.Order> container'
+    );
+  }
+
+  const resolvedOrderType = orderType ?? 'default';
+  const importantForAccessibilityFallback =
+    resolvedOrderType === 'default' ? ('yes' as const) : undefined;
+
+  return {
+    orderKey,
+    orderFocusType: hasOrderInfo
+      ? A11yOrderTypeEnum[resolvedOrderType]
+      : undefined,
+    importantForAccessibility:
+      importantForAccessibilityProp ?? importantForAccessibilityFallback,
+  };
+}
 
 export const A11yIndex = React.memo(
   React.forwardRef<IndexCommands, A11yIndexProps>(
@@ -15,72 +121,58 @@ export const A11yIndex = React.memo(
       {
         children,
         index,
-        orderType = 'default',
-        onScreenReaderSubViewFocusChange,
-        onScreenReaderSubViewFocused,
-        onScreenReaderSubViewBlurred,
+        orderType,
+        a11yUIContainer,
+        shouldGroupAccessibilityChildren,
         ...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 {
+        onScreenReaderFocused,
+        onScreenReaderSubViewFocusChange,
+        onScreenReaderSubViewFocused,
+        onScreenReaderSubViewBlurred,
+        onScreenReaderDescendantFocusChanged,
+        importantForAccessibility: importantForAccessibilityProp,
+        ...viewProps
+      } = props;
 
-      const onScreenReaderHandlerProp = hasHandler
-        ? onScreenReaderChangeHandler
+      const containerTypeValue = a11yUIContainer
+        ? A11yContainerTypeEnum[a11yUIContainer]
         : undefined;
 
-      const orderKey = React.useContext(A11ySequenceOrderContext);
-      if (!orderKey) {
-        throw new Error(
-          '<A11y.Index> element should be used inside of <A11y.Order> container'
-        );
-      }
+      const shouldGroupChildrenValue =
+        shouldGroupAccessibilityChildren === undefined
+          ? -1
+          : shouldGroupAccessibilityChildren
+          ? 1
+          : 0;
 
-      // @ts-ignore
-      const indexRef = useRef<React.ElementRef<React.ComponentType>>(null);
+      const screenReaderNativeProps = useScreenReaderProps({
+        onScreenReaderFocused,
+        onScreenReaderSubViewFocusChange,
+        onScreenReaderSubViewFocused,
+        onScreenReaderSubViewBlurred,
+        onScreenReaderDescendantFocusChanged,
+      });
 
-      useImperativeHandle(ref, () => ({
-        focus: () => {
-          if (indexRef.current) {
-            Commands.focus(indexRef.current);
-          }
-        },
-      }));
+      const { orderKey, orderFocusType, importantForAccessibility } =
+        useOrderProps(index, orderType, importantForAccessibilityProp);
 
-      const importantForAccessibility =
-        orderType === 'default' ? 'yes' : undefined;
+      const localRef = useFocusRef(ref);
 
       return (
         <A11yIndexView
-          importantForAccessibility={
-            props.importantForAccessibility ?? importantForAccessibility
-          }
-          orderFocusType={A11yOrderTypeEnum[orderType]}
-          ref={indexRef as React.Ref<any>}
+          ref={localRef as React.Ref<any>}
+          {...viewProps}
+          containerType={containerTypeValue}
+          shouldGroupAccessibilityChildren={shouldGroupChildrenValue}
+          importantForAccessibility={importantForAccessibility}
+          orderFocusType={orderFocusType}
           orderIndex={index}
           orderKey={orderKey}
-          {...props}
-          onScreenReaderFocusChange={onScreenReaderHandlerProp}
+          {...screenReaderNativeProps}
         >
           {children}
         </A11yIndexView>

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

@@ -0,0 +1,124 @@
+import React from 'react';
+import type { NativeSyntheticEvent, View, ViewProps } from 'react-native';
+import type { ScreenReaderDescendantFocusChanged } from '../../nativeSpecs/A11yIndexNativeComponent';
+
+/** Ref handle for {@link A11y.Index} — exposes `focus()` to move screen reader focus programmatically. */
+export type IndexCommands = Omit<React.ComponentRef<typeof View>, 'focus'> & {
+  /** Moves screen reader focus to this element. */
+  focus: () => void;
+};
+
+/** Numeric backing values for {@link A11yOrderType}. Kept for consumers who need the raw number. */
+export const A11yOrderTypeEnum = {
+  default: 0,
+  child: 1,
+  subview: 2,
+} as const;
+
+/** @internal Numeric backing values for {@link A11yUIContainerType}. */
+export const A11yContainerTypeEnum = {
+  none: 0,
+  table: 1,
+  list: 2,
+  landmark: 3,
+  group: 4,
+} as const;
+
+/**
+ * iOS only — sets `UIAccessibilityContainerType` on the wrapping view.
+ * Tells VoiceOver what kind of container this is: `'list'`, `'table'`, `'landmark'`, etc.
+ */
+export type A11yUIContainerType = keyof typeof A11yContainerTypeEnum;
+
+/**
+ * Controls which element receives screen reader focus for this index slot.
+ *
+ * - `'default'` — the `A11y.Index` view itself
+ * - `'child'`   — the first accessible child (useful when the index wrapper has no visual presence)
+ * - `'subview'` — first accessible child via an older traversal path
+ */
+export type A11yOrderType = keyof typeof A11yOrderTypeEnum;
+
+/** The native event payload emitted by `onScreenReaderDescendantFocusChanged`. */
+export type ScreenReaderDescendantFocusChangedEvent =
+  NativeSyntheticEvent<ScreenReaderDescendantFocusChanged>;
+
+export type A11yIndexProps = ViewProps & {
+  children: React.ReactNode;
+
+  /**
+   * Numeric position of this element in the parent `A11y.Order` sequence.
+   * Lower numbers are focused first; ties are resolved by render order.
+   */
+  index?: number;
+
+  /**
+   * Controls which element VoiceOver / TalkBack actually focuses for this slot.
+   *
+   * - `'default'` — the `A11y.Index` view itself receives focus
+   * - `'child'`   — the first accessible descendant receives focus (useful when
+   *   the index wrapper has no visual presence of its own)
+   * - `'subview'` — focuses the first direct child view rather than the first accessible descendant
+   *
+   * Defaults to `'default'`.
+   */
+  orderType?: A11yOrderType;
+
+  /**
+   * iOS only — sets `UIAccessibilityContainerType` on the wrapping view.
+   * Helps VoiceOver understand the semantic role of the container:
+   * `'list'`, `'table'`, `'landmark'`, etc.
+   *
+   * @platform ios
+   */
+  a11yUIContainer?: A11yUIContainerType;
+
+  /**
+   * iOS only — maps to `shouldGroupAccessibilityChildren` on the native view.
+   * Determines whether VoiceOver treats descendants as one grouped unit
+   * or navigates them individually.
+   *
+   * - `true`    — VoiceOver focuses the wrapper as a single element and builds
+   *   a combined label from its children.
+   * - `false`   — descendants stay individually focusable even when iOS would
+   *   otherwise collapse them.
+   * - omitted   — defers to the platform default.
+   *
+   * @platform ios
+   */
+  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).
+   */
+  onScreenReaderFocused?: () => void;
+
+  /**
+   * Called when screen reader focus enters or leaves any descendant.
+   * Receives `true` on enter and `false` on leave.
+   */
+  onScreenReaderSubViewFocusChange?: (isFocused: boolean) => void;
+
+  /**
+   * Called when screen reader focus enters any descendant.
+   */
+  onScreenReaderSubViewFocused?: () => void;
+
+  /**
+   * Called when screen reader focus leaves any descendant.
+   */
+  onScreenReaderSubViewBlurred?: () => void;
+
+  /**
+   * Called with the full native event when screen reader focus changes on any descendant.
+   * Use this when you need the `nativeId` of the focused element.
+   */
+  onScreenReaderDescendantFocusChanged?: (
+    e: ScreenReaderDescendantFocusChangedEvent
+  ) => void;
+};

package/src/components/A11yIndex/A11yIndex.web.tsx

@@ -1,9 +1,6 @@
 import React from 'react';
 import { forwardRef, useImperativeHandle, useRef } from 'react';
-import type {
-  IndexCommands,
-  A11yIndexProps,
-} from '../../types/A11yIndex.types';
+import type { A11yIndexProps } from './A11yIndex.types';
 import { UIManager } from 'react-native';
 import { View } from 'react-native';
 
@@ -11,17 +8,15 @@ const WebUiManager = UIManager as unknown as {
   focus: (v: View) => void;
 };
 
-export const A11yIndex = forwardRef<IndexCommands, A11yIndexProps>(
-  (props, ref) => {
-    const viewRef = useRef<View>(null);
-    useImperativeHandle(ref, () => ({
-      focus: () => {
-        if (viewRef.current) {
-          WebUiManager.focus(viewRef.current);
-        }
-      },
-    }));
+export const A11yIndex = forwardRef<{}, A11yIndexProps>((props, ref) => {
+  const viewRef = useRef<View>(null);
+  useImperativeHandle(ref, () => ({
+    focus: () => {
+      if (viewRef.current) {
+        WebUiManager.focus(viewRef.current);
+      }
+    },
+  }));
 
-    return <View {...props} ref={viewRef as any} />;
-  }
-);
+  return <View {...props} ref={viewRef as any} />;
+});

package/src/components/A11yLock/A11yBaseLock/A11yBaseLock.tsx

@@ -1,6 +1,6 @@
 import React from 'react';
 import A11yLockNativeComponent from '../../../nativeSpecs/A11yLockNativeComponent';
-import type { A11yLockProps } from '../../../types/A11yLock.types';
+import type { A11yLockProps } from '../A11yLock.types';
 
 export const A11yBaseLock = React.memo<A11yLockProps>(
   ({

package/src/components/A11yLock/A11yFocusFrame/A11yFocusFrame.android.tsx

@@ -1,5 +1,5 @@
 import React from 'react';
-import type { A11yLockProps } from '../../../types/A11yLock.types';
+import type { A11yLockProps } from '../A11yLock.types';
 import { A11yBaseLock } from '../A11yBaseLock/A11yBaseLock';
 import { A11yFrameProvider } from '../../../context/A11yFocusFrameProviderContext';
 

package/src/components/A11yLock/A11yFocusFrame/A11yFocusFrame.tsx

@@ -1,8 +1,9 @@
 import React from 'react';
-import { View, type ViewProps } from 'react-native';
+import { View } from 'react-native';
 import { A11yFrameProvider } from '../../../context/A11yFocusFrameProviderContext';
+import type { A11yFocusFrameProps } from '../A11yLock.types';
 
-export const A11yFocusFrame = (props: ViewProps) => (
+export const A11yFocusFrame = (props: A11yFocusFrameProps) => (
   <A11yFrameProvider>
     <View {...props} />
   </A11yFrameProvider>

package/src/components/A11yLock/A11yFocusTrap/A11yFocusTrap.android.tsx

@@ -1,5 +1,5 @@
 import React from 'react';
-import type { A11yLockProps } from '../../../types/A11yLock.types';
+import type { A11yLockProps } from '../A11yLock.types';
 import { A11yBaseLock } from '../A11yBaseLock/A11yBaseLock';
 import { A11yFocusTrapMountWrapper } from './A11yFocusTrapMountWrapper';
 

package/src/components/A11yLock/A11yFocusTrap/A11yFocusTrap.tsx

@@ -1,13 +1,13 @@
 import React from 'react';
 import { View } from 'react-native';
-import type { A11yLockProps } from '../../../types/A11yLock.types';
+import type { A11yFocusTrapProps } from '../A11yLock.types';
 import { A11yFocusTrapMountWrapper } from './A11yFocusTrapMountWrapper';
 import { A11yBaseLock } from '../A11yBaseLock/A11yBaseLock';
 
 export const A11yFocusTrap = ({
   forceLock = false,
   ...props
-}: A11yLockProps) => {
+}: A11yFocusTrapProps) => {
   if (forceLock) {
     return (
       <A11yFocusTrapMountWrapper>

package/src/components/A11yLock/A11yLock.types.ts

@@ -0,0 +1,38 @@
+import type { ViewProps } from 'react-native';
+
+/**
+ * Props for {@link A11y.FocusTrap} — confines VoiceOver / TalkBack focus to this subtree.
+ * Useful for modals, bottom sheets, and overlays where focus must not leak out.
+ */
+export type A11yFocusTrapProps = ViewProps & {
+  /**
+   * When `true`, the focus trap is inactive and the screen reader can navigate
+   * freely outside this container.
+   *
+   * Defaults to `false`.
+   */
+  lockDisabled?: boolean;
+
+  /**
+   * When `true`, focus is moved inside the trap immediately on mount rather than
+   * waiting for the next accessibility navigation gesture.
+   * Use this for programmatically-opened modals and sheets.
+   *
+   * Defaults to `false`.
+   */
+  forceLock?: boolean;
+};
+
+/**
+ * Props for {@link A11y.FocusFrame} — detects when screen reader focus escapes
+ * this subtree, enabling focus-leak detection in complex UIs.
+ */
+export type A11yFocusFrameProps = ViewProps;
+
+/** @internal Full props accepted by the native lock component. Not part of the public API. */
+export type A11yLockProps = ViewProps & {
+  componentType?: number;
+  containerKey?: string;
+  lockDisabled?: boolean;
+  forceLock?: boolean;
+};

package/src/components/{A11ySequence/A11ySequence.tsx → A11yOrder/A11yOrder.tsx}

@@ -1,9 +1,11 @@
 import React from 'react';
-import type { ViewProps } from 'react-native';
 import { A11ySequenceOrderContext } from '../../context/A11ySequenceOrderContext';
 import A11yOrderNativeComponent from '../../nativeSpecs/A11yOrderNativeComponent';
+import type { A11yOrderProps } from './A11yOrder.types';
 
-export const A11yIndexSequence = React.memo<ViewProps>((props) => {
+export type { A11yOrderProps };
+
+export const A11yOrder = React.memo<A11yOrderProps>((props) => {
   const orderKey = React.useId();
   return (
     <A11ySequenceOrderContext.Provider value={orderKey}>

package/src/components/A11yOrder/A11yOrder.types.ts

@@ -0,0 +1,11 @@
+import type { ViewProps } from 'react-native';
+
+/**
+ * Props for {@link A11y.Order} — a container that defines an explicit screen reader
+ * focus sequence for its `A11y.Index` children.
+ *
+ * All standard `View` props are accepted and forwarded to the underlying native view.
+ * The `orderKey` that links child `A11y.Index` elements to this container is generated
+ * internally via `React.useId` and requires no prop.
+ */
+export type A11yOrderProps = ViewProps;

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'>;