react-native-a11y-order 0.9.1 → 0.11.0-alpha.0

package/lib/typescript/src/index.web.d.ts

@@ -1,26 +1,14 @@
-export type { IndexCommands, A11yOrderType, A11yOrderTypeEnum, A11yIndexProps, } from './types/A11yIndex.types';
-export type { A11yContainerTypeEnum, A11yUIContainerType, A11yUIContainerProps, } from './types/A11yUIContainerView.types';
-export type { ScreenReaderDescendantFocusChangedEvent } from './types/A11yView.types';
-export type { A11yViewProps } from './types/A11yView.types';
+export type { IndexCommands, A11yOrderType, A11yIndexProps, } from './components/A11yIndex/A11yIndex.types';
+export { A11yOrderTypeEnum } from './components/A11yIndex/A11yIndex.types';
+export type { ScreenReaderDescendantFocusChangedEvent } from './components/A11yView/A11yView.types';
+export type { A11yViewProps } from './components/A11yView/A11yView.types';
 export declare const A11y: {
     Order: (props: Omit<import("react-native").ViewProps, keyof {
         ref?: React.Ref<React.ComponentRef<typeof import("react-native").unstable_NativeView>>;
     }> & {
         ref?: React.Ref<React.ComponentRef<typeof import("react-native").unstable_NativeView>>;
     }) => React.ReactNode;
-    Group: (props: Omit<import("react-native").ViewProps, keyof {
-        ref?: React.Ref<React.ComponentRef<typeof import("react-native").unstable_NativeView>>;
-    }> & {
-        ref?: React.Ref<React.ComponentRef<typeof import("react-native").unstable_NativeView>>;
-    }) => React.ReactNode;
-    Index: import("react").NamedExoticComponent<{
-        children: React.ReactNode;
-        index: number;
-        orderType?: import(".").A11yOrderType;
-        onScreenReaderSubViewFocusChange?: (isFocused: boolean) => void;
-        onScreenReaderSubViewFocused?: () => void;
-        onScreenReaderSubViewBlurred?: () => void;
-    } & Readonly<Omit<Readonly<{
+    Index: import("react").NamedExoticComponent<Readonly<Omit<Readonly<{
         onAccessibilityAction?: ((event: import("react-native").AccessibilityActionEvent) => unknown) | undefined;
         onAccessibilityTap?: (() => unknown) | undefined;
         onLayout?: ((event: import("react-native").LayoutChangeEvent) => unknown) | undefined;
@@ -143,8 +131,20 @@ export declare const A11y: {
         pointerEvents?: ("auto" | "box-none" | "box-only" | "none") | undefined;
         removeClippedSubviews?: boolean | undefined;
         experimental_accessibilityOrder?: Array<string> | undefined;
-    }>, never>> & import("react").RefAttributes<import(".").IndexCommands>>;
-    Container: (props: Omit<import("react-native").ViewProps, keyof {
+    }>, never>> & {
+        children: React.ReactNode;
+        index?: number;
+        orderType?: import(".").A11yOrderType;
+        a11yUIContainer?: import("./components/A11yIndex/A11yIndex.types").A11yUIContainerType;
+        shouldGroupAccessibilityChildren?: boolean;
+        autoFocus?: boolean;
+        onScreenReaderFocused?: () => void;
+        onScreenReaderSubViewFocusChange?: (isFocused: boolean) => void;
+        onScreenReaderSubViewFocused?: () => void;
+        onScreenReaderSubViewBlurred?: () => void;
+        onScreenReaderDescendantFocusChanged?: (e: import(".").ScreenReaderDescendantFocusChangedEvent) => void;
+    } & import("react").RefAttributes<import(".").IndexCommands>>;
+    View: (props: Omit<import("react-native").ViewProps, keyof {
         ref?: React.Ref<React.ComponentRef<typeof import("react-native").unstable_NativeView>>;
     }> & {
         ref?: React.Ref<React.ComponentRef<typeof import("react-native").unstable_NativeView>>;
@@ -159,17 +159,17 @@ export declare const A11y: {
     }> & {
         ref?: React.Ref<React.ComponentRef<typeof import("react-native").unstable_NativeView>>;
     }) => React.ReactNode;
-    View: (props: Omit<import("react-native").ViewProps, keyof {
+    FocusFrame: (props: Omit<import("react-native").ViewProps, keyof {
         ref?: React.Ref<React.ComponentRef<typeof import("react-native").unstable_NativeView>>;
     }> & {
         ref?: React.Ref<React.ComponentRef<typeof import("react-native").unstable_NativeView>>;
     }) => React.ReactNode;
-    FocusFrame: (props: Omit<import("react-native").ViewProps, keyof {
+    FocusTrap: (props: Omit<import("react-native").ViewProps, keyof {
         ref?: React.Ref<React.ComponentRef<typeof import("react-native").unstable_NativeView>>;
     }> & {
         ref?: React.Ref<React.ComponentRef<typeof import("react-native").unstable_NativeView>>;
     }) => React.ReactNode;
-    FocusTrap: (props: Omit<import("react-native").ViewProps, keyof {
+    Card: (props: Omit<import("react-native").ViewProps, keyof {
         ref?: React.Ref<React.ComponentRef<typeof import("react-native").unstable_NativeView>>;
     }> & {
         ref?: React.Ref<React.ComponentRef<typeof import("react-native").unstable_NativeView>>;

package/lib/typescript/src/index.web.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.web.d.ts","sourceRoot":"","sources":["../../../src/index.web.ts"],"names":[],"mappings":"AAGA,YAAY,EACV,aAAa,EACb,aAAa,EACb,iBAAiB,EACjB,cAAc,GACf,MAAM,yBAAyB,CAAC;AAEjC,YAAY,EACV,qBAAqB,EACrB,mBAAmB,EACnB,oBAAoB,GACrB,MAAM,mCAAmC,CAAC;AAE3C,YAAY,EAAE,uCAAuC,EAAE,MAAM,wBAAwB,CAAC;AAEtF,YAAY,EAAE,aAAa,EAAE,MAAM,wBAAwB,CAAC;AAE5D,eAAO,MAAM,IAAI;;WAaiE,CAAC;;WAAyE,CAAC;;;WAA3E,CAAC;;WAAyE,CAAC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;WAA3E,CAAC;;WAAyE,CAAC;;;WAA3E,CAAC;;WAAyE,CAAC;;;WAA3E,CAAC;;WAAyE,CAAC;;;WAA3E,CAAC;;WAAyE,CAAC;;;WAA3E,CAAC;;WAAyE,CAAC;;;WAA3E,CAAC;;WAAyE,CAAC;;CAH5J,CAAC;AAEF,OAAO,EAAE,UAAU,EAAE,MAAM,8BAA8B,CAAC"}
+{"version":3,"file":"index.web.d.ts","sourceRoot":"","sources":["../../../src/index.web.ts"],"names":[],"mappings":"AAGA,YAAY,EACV,aAAa,EACb,aAAa,EACb,cAAc,GACf,MAAM,wCAAwC,CAAC;AAChD,OAAO,EAAE,iBAAiB,EAAE,MAAM,wCAAwC,CAAC;AAE3E,YAAY,EAAE,uCAAuC,EAAE,MAAM,sCAAsC,CAAC;AAEpG,YAAY,EAAE,aAAa,EAAE,MAAM,sCAAsC,CAAC;AAE1E,eAAO,MAAM,IAAI;;WAYsH,CAAC;;WAAyE,CAAC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;WAA3E,CAAC;;WAAyE,CAAC;;;WAA3E,CAAC;;WAAyE,CAAC;;;WAA3E,CAAC;;WAAyE,CAAC;;;WAA3E,CAAC;;WAAyE,CAAC;;;WAA3E,CAAC;;WAAyE,CAAC;;;WAA3E,CAAC;;WAAyE,CAAC;;CAHjN,CAAC;AAEF,OAAO,EAAE,UAAU,EAAE,MAAM,8BAA8B,CAAC"}

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

@@ -0,0 +1,8 @@
+import type { ViewProps } from 'react-native';
+export interface A11yCardNativeComponentProps extends ViewProps {
+}
+declare const _default: (props: Omit<A11yCardNativeComponentProps, "ref"> & {
+    ref?: React.Ref<import("react-native").HostInstance>;
+}) => React.ReactNode;
+export default _default;
+//# sourceMappingURL=A11yCardNativeComponent.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"A11yCardNativeComponent.d.ts","sourceRoot":"","sources":["../../../../src/nativeSpecs/A11yCardNativeComponent.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,cAAc,CAAC;AAI9C,MAAM,WAAW,4BAA6B,SAAQ,SAAS;CAAG;;;;AAElE,wBAEE"}

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

@@ -6,12 +6,19 @@ 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;
+    autoFocus?: boolean;
+    descendantFocusChangedEnabled?: boolean;
+    onScreenReaderFocused?: DirectEventHandler<{}>;
+    onScreenReaderDescendantFocusChanged?: DirectEventHandler<ScreenReaderDescendantFocusChanged>;
     onScreenReaderFocusChange?: DirectEventHandler<ScreenReaderFocusChange>;
+    containerType?: Int32;
 }
 export interface NativeCommands {
     focus: (viewRef: React.ElementRef<ComponentType>) => void;

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

@@ -1 +1 @@
-{"version":3,"file":"A11yIndexNativeComponent.d.ts","sourceRoot":"","sources":["../../../../src/nativeSpecs/A11yIndexNativeComponent.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,OAAO,CAAC;AAC3C,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,cAAc,CAAC;AAC9C,OAAO,KAAK,EACV,kBAAkB,EAClB,KAAK,EACN,MAAM,2CAA2C,CAAC;AAMnD,MAAM,MAAM,uBAAuB,GAAG,QAAQ,CAAC;IAC7C,SAAS,EAAE,OAAO,CAAC;CACpB,CAAC,CAAC;AAEH,MAAM,MAAM,kCAAkC,GAAG,QAAQ,CAAC;IACxD,MAAM,EAAE,MAAM,CAAC;CAChB,CAAC,CAAC;AAEH,MAAM,WAAW,6BAA8B,SAAQ,SAAS;IAC9D,UAAU,EAAE,KAAK,CAAC;IAClB,QAAQ,EAAE,MAAM,CAAC;IACjB,cAAc,EAAE,KAAK,CAAC;IAEtB,yBAAyB,CAAC,EAAE,kBAAkB,CAAC,uBAAuB,CAAC,CAAC;CACzE;AAED,MAAM,WAAW,cAAc;IAE7B,KAAK,EAAE,CAAC,OAAO,EAAE,KAAK,CAAC,UAAU,CAAC,aAAa,CAAC,KAAK,IAAI,CAAC;CAC3D;AAED,eAAO,MAAM,QAAQ,EAAE,cAErB,CAAC;;;;AAEH,wBAEE"}
+{"version":3,"file":"A11yIndexNativeComponent.d.ts","sourceRoot":"","sources":["../../../../src/nativeSpecs/A11yIndexNativeComponent.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,OAAO,CAAC;AAC3C,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,cAAc,CAAC;AAC9C,OAAO,KAAK,EACV,kBAAkB,EAClB,KAAK,EACN,MAAM,2CAA2C,CAAC;AAMnD,MAAM,MAAM,uBAAuB,GAAG,QAAQ,CAAC;IAC7C,SAAS,EAAE,OAAO,CAAC;CACpB,CAAC,CAAC;AAEH,MAAM,MAAM,kCAAkC,GAAG,QAAQ,CAAC;IACxD,MAAM,EAAE,MAAM,CAAC;IACf,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB,CAAC,CAAC;AAEH,MAAM,WAAW,6BAA8B,SAAQ,SAAS;IAC9D,UAAU,CAAC,EAAE,KAAK,CAAC;IACnB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,cAAc,CAAC,EAAE,KAAK,CAAC;IACvB,gCAAgC,CAAC,EAAE,KAAK,CAAC;IAEzC,SAAS,CAAC,EAAE,OAAO,CAAC;IACpB,6BAA6B,CAAC,EAAE,OAAO,CAAC;IAExC,qBAAqB,CAAC,EAAE,kBAAkB,CAAC,EAAE,CAAC,CAAC;IAC/C,oCAAoC,CAAC,EAAE,kBAAkB,CAAC,kCAAkC,CAAC,CAAC;IAC9F,yBAAyB,CAAC,EAAE,kBAAkB,CAAC,uBAAuB,CAAC,CAAC;IAExE,aAAa,CAAC,EAAE,KAAK,CAAC;CACvB;AAED,MAAM,WAAW,cAAc;IAE7B,KAAK,EAAE,CAAC,OAAO,EAAE,KAAK,CAAC,UAAU,CAAC,aAAa,CAAC,KAAK,IAAI,CAAC;CAC3D;AAED,eAAO,MAAM,QAAQ,EAAE,cAErB,CAAC;;;;AAEH,wBAEE"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "react-native-a11y-order",
-  "version": "0.9.1",
+  "version": "0.11.0-alpha.0",
   "description": "ReactNative library for managing screen reader focus ordering",
   "main": "lib/commonjs/index",
   "module": "lib/module/index",
@@ -25,10 +25,12 @@
     "!**/__fixtures__",
     "!**/__mocks__",
     "!**/.*",
-    "!**/CLAUDE.md"
+    "!**/CLAUDE.md",
+    "!**/docs"
   ],
   "scripts": {
     "example": "yarn workspace a11y-order-example",
+    "example-legacy": "yarn workspace A11yOrderExample",
     "clean": "del-cli android/build example/android/build example/android/app/build example/ios/build lib",
     "prepare": "bob build",
     "typecheck": "tsc",
@@ -64,11 +66,11 @@
     "@eslint/compat": "^1.3.2",
     "@eslint/eslintrc": "^3.3.1",
     "@eslint/js": "^9.35.0",
-    "@react-native/babel-preset": "0.83.0",
-    "@react-native/eslint-config": "0.83.0",
+    "@react-native/babel-preset": "0.76.0",
+    "@react-native/eslint-config": "0.76.0",
     "@release-it/conventional-changelog": "^10.0.1",
     "@types/jest": "^29.5.14",
-    "@types/react": "^19.2.0",
+    "@types/react": "^18.2.0",
     "commitlint": "^19.8.1",
     "del-cli": "^6.0.0",
     "eslint": "^9.35.0",
@@ -77,8 +79,8 @@
     "jest": "^29.7.0",
     "lefthook": "^2.0.3",
     "prettier": "^2.8.8",
-    "react": "19.2.0",
-    "react-native": "0.83.0",
+    "react": "18.2.0",
+    "react-native": "0.76.0",
     "react-native-builder-bob": "^0.40.18",
     "release-it": "^19.0.4",
     "turbo": "^2.5.6",
@@ -89,7 +91,8 @@
     "react-native": "*"
   },
   "workspaces": [
-    "example"
+    "example",
+    "A11yOrderExample"
   ],
   "packageManager": "yarn@4.11.0",
   "react-native-builder-bob": {
@@ -112,12 +115,10 @@
     "jsSrcsDir": "src",
     "ios": {
       "componentProvider": {
-        "A11yGroupView": "RNAOA11yGroupView",
+        "A11yCardView": "RNAOA11yCardView",
         "A11yIndexView": "RNAOA11yIndexView",
         "A11yOrderView": "RNAOA11yOrderView",
-        "A11yUIContainer": "RNAOA11yUIContainerView",
         "A11yPaneTitle": "RNAOA11yPaneTitleView",
-        "A11yView": "RNAOA11yView",
         "A11yLock": "RNAOA11yLockView"
       },
       "modulesProvider": {

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,39 @@
+import type {
+  ViewStyle,
+  StyleProp,
+  ViewProps,
+  PressableProps,
+} from 'react-native';
+
+// All screen-reader-facing props, typed directly from ViewProps so they
+// stay in sync with RN without a separate custom interface.
+export type A11yCardAccessibilityProps = ViewProps;
+
+export interface A11yCardProps {
+  // Props for the outer container (<Card> on iOS, <View> on Android).
+  // Use for margins, flex, and layout positioning in the parent.
+  containerProps?: ViewProps;
+
+  // Visual style of the inner Pressable (background, border, shadow, etc.).
+  style?: StyleProp<ViewStyle>;
+  testID?: string;
+  disabled?: boolean;
+  onPress?: () => void;
+  // Note: onLongPress fires for sighted users. For VoiceOver users add a
+  // custom action via accessibility.accessibilityActions — VoiceOver activates
+  // via double-tap (onPress), not long-press.
+  onLongPress?: () => void;
+
+  // What the screen reader announces and interacts with.
+  // On iOS applied to the overlay (first in accessibilityElements).
+  // On Android applied to the Pressable directly.
+  // disabled auto-merges into accessibility.accessibilityState.disabled so
+  // you only need to set disabled once.
+  accessibility?: A11yCardAccessibilityProps;
+
+  // Escape hatch for Pressable props not covered above (hitSlop, android_ripple, etc.).
+  // Conflicting keys are stripped to prevent accidental overrides.
+  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,102 @@
+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.
+   * Defaults to `'default'` (the index view itself).
+   */
+  orderType?: A11yOrderType;
+
+  /**
+   * iOS only — sets `UIAccessibilityContainerType`.
+   * Helps VoiceOver understand the semantic container type (list, table, landmark…).
+   */
+  a11yUIContainer?: A11yUIContainerType;
+
+  /**
+   * iOS only — controls the wrapping view's `shouldGroupAccessibilityChildren`.
+   * Determines whether VoiceOver treats descendants as one grouped unit
+   * or navigates them individually.
+   *
+   * - `true` — group descendants; VoiceOver focuses the wrapper as a single
+   *   element with a combined label built from its children.
+   * - `false` — force descendants to remain individually focusable even when
+   *   iOS would otherwise group them.
+   * - omitted — defer to the wrapping view's default behavior.
+   */
+  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. */
+  onScreenReaderFocused?: () => void;
+
+  /**
+   * Called whenever screen reader focus enters or leaves any descendant.
+   * `isFocused` is `true` on enter, `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 native event when screen reader focus changes on any descendant. */
+  onScreenReaderDescendantFocusChanged?: (
+    e: ScreenReaderDescendantFocusChangedEvent
+  ) => void;
+};