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

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

@@ -0,0 +1,44 @@
+import React from 'react';
+import { Pressable, StyleSheet, View } from 'react-native';
+import Card from '../../nativeSpecs/A11yCardNativeComponent';
+import type { A11yCardProps } from './A11yCard.types';
+
+export type { A11yCardProps };
+
+export const A11yCard = ({
+  containerProps,
+  style,
+  testID,
+  onPress,
+  accessibility,
+  pressableProps,
+  children,
+}: A11yCardProps) => {
+  return (
+    <Card {...containerProps} style={[styles.container, containerProps?.style]}>
+      <View
+        testID={`${testID}-overlay`}
+        accessibilityRole="button"
+        {...accessibility}
+        accessible
+        pointerEvents="none"
+        onAccessibilityTap={onPress}
+        style={styles.overlay}
+      />
+      <Pressable
+        {...pressableProps}
+        accessible={false}
+        onPress={onPress}
+        testID={testID}
+        style={style}
+      >
+        {children}
+      </Pressable>
+    </Card>
+  );
+};
+
+const styles = StyleSheet.create({
+  container: { position: 'relative' },
+  overlay: StyleSheet.absoluteFillObject,
+});

package/src/components/A11yCard/A11yCard.tsx

@@ -0,0 +1,35 @@
+import React from 'react';
+import { Pressable, StyleSheet, View } from 'react-native';
+import type { A11yCardProps } from './A11yCard.types';
+
+export type { A11yCardProps };
+
+export const A11yCard = ({
+  containerProps,
+  style,
+  testID,
+  onPress,
+  accessibility,
+  pressableProps,
+  children,
+}: A11yCardProps) => {
+  return (
+    <View collapsable={false} {...containerProps}>
+      <Pressable
+        {...pressableProps}
+        accessibilityRole="button"
+        {...accessibility}
+        accessible
+        onPress={onPress}
+        testID={testID}
+        style={[style, styles.container]}
+      >
+        {children}
+      </Pressable>
+    </View>
+  );
+};
+
+const styles = StyleSheet.create({
+  container: { position: 'relative' },
+});

package/src/components/A11yCard/A11yCard.types.ts

@@ -0,0 +1,50 @@
+import type {
+  ViewStyle,
+  StyleProp,
+  ViewProps,
+  PressableProps,
+} from 'react-native';
+
+/** Accessibility props forwarded to the focusable overlay (iOS) or the Pressable (Android). */
+export type A11yCardAccessibilityProps = ViewProps;
+
+export interface A11yCardProps {
+  /**
+   * Props applied to the container View wrapping the card.
+   * Use this for layout-level concerns: position, margins, flex, etc.
+   */
+  containerProps?: ViewProps;
+
+  /**
+   * Style for the card surface (the inner Pressable).
+   * Use this for visual appearance: background color, border radius, padding, etc.
+   */
+  style?: StyleProp<ViewStyle>;
+
+  /**
+   * Used to locate this view in end-to-end tests.
+   */
+  testID?: string;
+
+  /**
+   * Called when the user taps the card.
+   */
+  onPress?: () => void;
+
+  /**
+   * View/Accessibility props for the card action — `accessibilityLabel`, `accessibilityHint`,
+   * `accessibilityRole`, `accessibilityState`, etc.
+   *
+   * On iOS these are forwarded to a full-cover overlay that VoiceOver focuses.
+   * On Android they are applied directly to the Pressable.
+   */
+  accessibility?: A11yCardAccessibilityProps;
+
+  /**
+   * Props passed directly to the underlying `Pressable`.
+   * Use this for `hitSlop`, `android_ripple`, `onLongPress`, etc.
+   */
+  pressableProps?: PressableProps;
+
+  children?: React.ReactNode;
+}

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,119 @@
+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;
+
+  /**
+   * 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;