@amazon-devices/vega-carousel 1.0.0 → 1.0.1

package/dist/Carousel/Carousel.js

@@ -33,7 +33,7 @@ const react_1 = __importStar(require("react"));
 const CarouselScrollable_1 = require("../CarouselScrollable");
 const Utils_1 = require("./Utils");
 function Scrollable({ dataAdapter: { getItem, getItemCount, getItemKey, notifyDataError }, renderItem: renderItemProp, testID, uniqueId, orientation = 'horizontal', renderedItemsCount = 8, numOffsetItems = 2, navigableScrollAreaMargin = 0, hasPreferredFocus = false, initialStartIndex = 0, hideItemsBeforeSelection = false, trapSelectionOnOrientation = false, containerStyle, itemStyle = {
-    itemPadding: 20,
+    itemPadding: 10,
     pressedItemScaleFactor: 0.8,
     selectedItemScaleFactor: 1,
 }, animationDuration = {

package/dist/CarouselScrollable/native/CarouselNativeItemWrapper.d.ts

@@ -34,13 +34,6 @@ export type CarouselNativeItemProps<ItemT, KeyT = React.Key> = ViewProps & Carou
      * @see {@link parentId}
      */
     dataIndex?: number;
-    /**
-     * The shift associated with this item.
-     *
-     * @default undefined
-     * @see {@link parentId}
-     */
-    itemShift?: ScaleFactor;
     /**
      * When this flag is set to `true`, the selected item will have a styleable
      * border enveloping the selected item.
@@ -78,15 +71,6 @@ export type CarouselNativeItemProps<ItemT, KeyT = React.Key> = ViewProps & Carou
      */
     focusedItemScaleFactor: number;
     shiftItemsScaleFactor: ScaleFactor;
-    /**
-     * This element is used on the very first time the {@link CarouselNativeItemWrapper}
-     * resolvers.
-     *
-     * Further resolvers will use the {@link dataAdapter} and {@link renderItem}
-     * properties to generate the {@link React.ReactElement} to be used.
-     */
-    initialElement?: React.ReactElement;
-    initialKey?: KeyT;
     /**
      * This function is called whenever the item receives a message from the
      * native layer telling it to rebind itself to another data item.
@@ -129,7 +113,10 @@ export type CarouselNativeItemState = {
      */
     refreshToggle: boolean;
     /**
-     * This field is used for specifying per-item shift value.
+     * Per-item shift (layout offset) resolved from the data adapter. The child
+     * is the source of truth for its own shift — the parent only tells us which
+     * `dataIndex` to display, and we read the shift directly from the adapter
+     * here. See VEGATV-115306.
      */
     itemShift?: ScaleFactor;
 };
@@ -154,8 +141,12 @@ export type CarouselNativeItemState = {
  */
 export declare class CarouselNativeItemWrapper<ItemT, KeyT = React.Key> extends React.Component<CarouselNativeItemProps<ItemT, KeyT>, CarouselNativeItemState> {
     private currentKey;
-    private useInitialElement;
     constructor(props: CarouselNativeItemProps<ItemT, KeyT>);
+    /**
+     * Snapshot the rendered key after every committed update.
+     * This runs in the commit phase (safe for CR). See VEGATV-115306.
+     */
+    componentDidUpdate(): void;
     /**
      * Function called by the framework right before calling {@link render}, both
      * on the initial mount, and on the following updates.
@@ -202,13 +193,8 @@ export declare class CarouselNativeItemWrapper<ItemT, KeyT = React.Key> extends
      */
     shouldComponentUpdate(nextProps: Readonly<CarouselNativeItemProps<ItemT, KeyT>>, nextState: Readonly<CarouselNativeItemState>): boolean;
     /**
-     * Called whenever the framework needs the component's definition to render a
-     * view in the screen.
-     *
-     * When this method is called, there is nothing for this component to resolve,
-     * so this call is as fast as it can be. However, be mindful that the other
-     * lifecycle methods in this class were already called, and the _perceived_
-     * render performance is a combination of all these methods.
+     * Pure render — computes the item element fresh from props/state each time.
+     * Does NOT write to `this`. See VEGATV-115306.
      *
      * @see [Official API documentation](https://react.dev/reference/react/Component#render)
      */
@@ -232,24 +218,21 @@ export declare class CarouselNativeItemWrapper<ItemT, KeyT = React.Key> extends
      *
      * @param {CarouselNativeItemState} state An optional state used to read the
      *        item's data index instead of the component's state.
-     *
-     * @param {CarouselNativeItemProps} props Optional props used to override the current props if newer props are known
-     * @return {React.ReactElement | undefined} Returns the fully resolved
-     *         element or `undefined` if it is not found.
+     * @param {CarouselNativeItemProps} props Optional props used to override the
+     *        current props if newer props are known.
+     * @return {React.ReactElement} Returns the fully resolved element, or an
+     *         empty fragment if it cannot be resolved.
      *
      * @see {@link CarouselNativeItemState}
      * @see {@link resolveDataItems}
      */
     private resolveUpdatedItemContent;
     /**
-     * Convenience method to render a native component with the
+     * Convenience method to render a native component with the given
      * {@link itemElement} as its child component.
-     */
-    private renderStateItem;
-    /**
-     * This property is used to cache the resolved element of this item.
      *
-     * @private
+     * @param {React.ReactElement} itemElement The resolved element to render
+     *        inside the native host.
      */
-    private itemElement;
+    private renderStateItem;
 }

package/dist/CarouselScrollable/native/CarouselNativeItemWrapper.js

@@ -43,18 +43,27 @@ const defaultBorderStyle = {
  * @see {@link CarouselScrollable}
  */
 class CarouselNativeItemWrapper extends react_1.default.Component {
+    // Snapshot of the last-rendered key. Seeded in the constructor and updated
+    // in commit-phase only (componentDidUpdate/onBind) for CR safety.
+    // See VEGATV-115306.
     currentKey;
-    useInitialElement;
     constructor(props) {
         super(props);
+        const dataIndex = this.props.dataIndex ?? -1;
         this.state = {
-            dataIndex: this.props.dataIndex ?? -1,
+            dataIndex,
             parentId: this.props.parentId,
             refreshToggle: false,
-            itemShift: this.props.itemShift,
+            itemShift: (0, CarouselData_1.getSelectedItemOffset)(this.props.dataAdapter, dataIndex),
         };
-        this.currentKey = this.props.initialKey;
-        this.useInitialElement = true;
+        this.currentKey = (0, CarouselData_1.getItemKey)(this.props.dataAdapter, dataIndex);
+    }
+    /**
+     * Snapshot the rendered key after every committed update.
+     * This runs in the commit phase (safe for CR). See VEGATV-115306.
+     */
+    componentDidUpdate() {
+        this.currentKey = (0, CarouselData_1.getItemKey)(this.props.dataAdapter, this.state.dataIndex);
     }
     ////////////////////////////////////////
     /// Lifecycle methods
@@ -112,69 +121,35 @@ class CarouselNativeItemWrapper extends react_1.default.Component {
      * @see [Official API documentation](https://react.dev/reference/react/Component#shouldcomponentupdate)
      */
     shouldComponentUpdate(nextProps, nextState) {
-        let shouldUpdate = false;
         const nextKey = (0, CarouselData_1.getItemKey)(nextProps.dataAdapter, nextState.dataIndex);
         if (this.currentKey !== nextKey) {
-            shouldUpdate = true;
+            return true;
         }
         // the state will govern whether we should update the component
-        if (!shouldUpdate &&
-            (this.state.dataIndex !== nextState.dataIndex ||
-                this.state.parentId !== nextState.parentId ||
-                this.state.refreshToggle !== nextState.refreshToggle)) {
-            shouldUpdate = true;
+        if (this.state.dataIndex !== nextState.dataIndex ||
+            this.state.parentId !== nextState.parentId ||
+            this.state.refreshToggle !== nextState.refreshToggle) {
+            return true;
         }
-        if (!shouldUpdate &&
-            (this.props.focusedItemScaleFactor !== nextProps.focusedItemScaleFactor ||
-                this.props.shiftItemsScaleFactor.width !==
-                    nextProps.shiftItemsScaleFactor.width ||
-                this.props.shiftItemsScaleFactor.height !==
-                    nextProps.shiftItemsScaleFactor.height)) {
+        if (this.props.focusedItemScaleFactor !== nextProps.focusedItemScaleFactor ||
+            this.props.shiftItemsScaleFactor.width !==
+                nextProps.shiftItemsScaleFactor.width ||
+            this.props.shiftItemsScaleFactor.height !==
+                nextProps.shiftItemsScaleFactor.height) {
             utils_1.Log.d('shouldComponentUpdate: PROPS CHANGED');
-            shouldUpdate = true;
-        }
-        // If the state did not determine if we should update, then check the new and current key
-        if (!shouldUpdate) {
-            if (nextKey !== this.currentKey) {
-                utils_1.Log.d('shouldComponentUpdate: KEYS CHANGED');
-                shouldUpdate = true;
-            }
-        }
-        // If we should update, ensure that the itemElement gets updated as well
-        if (shouldUpdate) {
-            this.currentKey = nextKey;
-            this.itemElement = this.resolveUpdatedItemContent(nextState, nextProps);
+            return true;
         }
-        return shouldUpdate;
+        return false;
     }
     /**
-     * Called whenever the framework needs the component's definition to render a
-     * view in the screen.
-     *
-     * When this method is called, there is nothing for this component to resolve,
-     * so this call is as fast as it can be. However, be mindful that the other
-     * lifecycle methods in this class were already called, and the _perceived_
-     * render performance is a combination of all these methods.
+     * Pure render — computes the item element fresh from props/state each time.
+     * Does NOT write to `this`. See VEGATV-115306.
      *
      * @see [Official API documentation](https://react.dev/reference/react/Component#render)
      */
     render() {
-        try {
-            if (!this.itemElement) {
-                // This is the initial resolver of the item
-                if (this.useInitialElement && this.props.initialElement) {
-                    this.itemElement = this.props.initialElement;
-                }
-                else {
-                    this.itemElement = <></>;
-                    this.useInitialElement = false;
-                }
-            }
-            return this.renderStateItem();
-        }
-        finally {
-            this.useInitialElement = false;
-        }
+        const itemElement = this.resolveUpdatedItemContent();
+        return this.renderStateItem(itemElement);
     }
     ////////////////////////////////////////
     /// Private callback functions
@@ -196,10 +171,11 @@ class CarouselNativeItemWrapper extends react_1.default.Component {
                 dataIndex: nativeEvent.nativeEvent.index,
                 itemShift: (0, CarouselData_1.getSelectedItemOffset)(this.props.dataAdapter, nativeEvent.nativeEvent.index),
             };
-            this.props.unbindCallback(this.state.dataIndex);
-            this.itemElement = this.resolveUpdatedItemContent(newState);
-            // Every time a frame gets re-bound/recycled update the currentKey
+            // Every time a frame gets re-bound/recycled update the currentKey.
+            // This runs in an event handler (commit-safe), not during render.
+            // See VEGATV-115306.
             this.currentKey = (0, CarouselData_1.getItemKey)(this.props.dataAdapter, nativeEvent.nativeEvent.index);
+            this.props.unbindCallback(this.state.dataIndex);
             this.setState(newState);
             this.props.bindCallback(nativeEvent.nativeEvent.index);
         }
@@ -221,31 +197,34 @@ class CarouselNativeItemWrapper extends react_1.default.Component {
      *
      * @param {CarouselNativeItemState} state An optional state used to read the
      *        item's data index instead of the component's state.
-     *
-     * @param {CarouselNativeItemProps} props Optional props used to override the current props if newer props are known
-     * @return {React.ReactElement | undefined} Returns the fully resolved
-     *         element or `undefined` if it is not found.
+     * @param {CarouselNativeItemProps} props Optional props used to override the
+     *        current props if newer props are known.
+     * @return {React.ReactElement} Returns the fully resolved element, or an
+     *         empty fragment if it cannot be resolved.
      *
      * @see {@link CarouselNativeItemState}
      * @see {@link resolveDataItems}
      */
     resolveUpdatedItemContent = (state, props) => {
+        const targetIndex = state?.dataIndex ?? this.state.dataIndex;
+        const adapter = props?.dataAdapter ?? this.props.dataAdapter;
         let element;
-        (0, CarouselData_1.resolveDataItems)(props?.dataAdapter ?? this.props.dataAdapter, props?.renderItem ?? this.props.renderItem, (0, CarouselData_1.dataReadAtTargetConfig)(state?.dataIndex ?? this.state.dataIndex), (resolved) => {
+        (0, CarouselData_1.resolveDataItems)(adapter, props?.renderItem ?? this.props.renderItem, (0, CarouselData_1.dataReadAtTargetConfig)(targetIndex), (resolved) => {
             element = resolved.element;
         });
         // We need to update all undefined elements with an empty view in order to account for the loading state
         // TODO : Update this logic once Scrollable getItem APIs support a loading state instead of just valid and invalid cases
-        if (!element) {
-            element = <></>;
-        }
+        element ??= <></>;
         return element;
     };
     /**
-     * Convenience method to render a native component with the
+     * Convenience method to render a native component with the given
      * {@link itemElement} as its child component.
+     *
+     * @param {React.ReactElement} itemElement The resolved element to render
+     *        inside the native host.
      */
-    renderStateItem = () => {
+    renderStateItem = (itemElement) => {
         return (<CarouselNativeItemHostComponent_1.CarouselNativeItemHost testID={this.props.testID} parentId={this.state.parentId} dataIndex={this.state.dataIndex} showSelectionBorder={this.props.showSelectionBorder ?? false} selectionBorderColor={this.props.showSelectionBorder
                 ? (0, react_native_1.processColor)(this.props.selectionBorderStyle?.borderColor ??
                     defaultBorderStyle.borderColor)
@@ -263,16 +242,8 @@ class CarouselNativeItemWrapper extends react_1.default.Component {
                 : this.props.shiftItemsScaleFactor.width} shiftItemsHeightScaleFactor={this.state.itemShift
                 ? this.state.itemShift.height
                 : this.props.shiftItemsScaleFactor.height} onBind={this.onBind}>
-        {this.itemElement}
+        {itemElement}
       </CarouselNativeItemHostComponent_1.CarouselNativeItemHost>);
     };
-    ////////////////////////////////////////
-    /// Private attributes
-    /**
-     * This property is used to cache the resolved element of this item.
-     *
-     * @private
-     */
-    itemElement = undefined;
 }
 exports.CarouselNativeItemWrapper = CarouselNativeItemWrapper;

package/dist/CarouselScrollable/native/CarouselNativeLogic.d.ts

@@ -1,7 +1,7 @@
 import { HostComponent, StyleProp, ViewStyle } from 'react-native';
 import { ListOrientation, OnItemBindFunc, OnItemUnbindFunc, OnSelectionChangedCallback } from '../CarouselScrollableTypes';
 import { CarouselNativeHostComponentSelectionChangedEvent, CarouselNativeHostComponentProps } from './CarouselNativeHostComponent';
-import { CarouselDataAdapter, CarouselDataChange, CarouselResolvedDataValues, RenderItemFunc } from '../../CarouselData';
+import { CarouselDataAdapter, CarouselDataChange } from '../../CarouselData';
 import { AnyValue } from '../../utils';
 /**
  * Auxiliary function use to invoke the `enableInputEvents` native function on
@@ -113,8 +113,14 @@ export declare function callReset(hostComponent: HostComponent<CarouselNativeHos
  */
 export declare function addFlexDirectionStyle(baseStyle: StyleProp<ViewStyle>, orientation: ListOrientation): StyleProp<ViewStyle>;
 /**
- * This function is the core logic to retrieve items on the {@link CarouselScrollable}
- * initial render.
+ * This function determines which data indices should fill the
+ * {@link CarouselScrollable}'s initial render window.
+ *
+ * It does NOT eagerly resolve per-item content (key, shift, JSX). Each child
+ * component looks those up itself from the same adapter using its assigned
+ * `dataIndex`. This function only checks **whether data is available** at each
+ * candidate index — it walks the adapter, calling `getItem` to confirm a slot
+ * is fillable, and collects the indices that succeed.
  *
  * It will try in different ways to get as many items as defined by the
  * `dataLimit` argument.
@@ -133,9 +139,11 @@ export declare function addFlexDirectionStyle(baseStyle: StyleProp<ViewStyle>, o
  *    **before** the last item retrieved at step 2 until we have a total of
  *    `dataLimit` items, or the last item we retrieved was at position `0`;
  *
- * Internally, `getInitialData` uses the {@link resolveDataItems} function to
- * guarantee that failed items are resolved (and accounted for) by the given
- * adapter.
+ * This function walks the adapter with retry logic to handle transient item
+ * retrieval failures (same retry semantics as resolveDataItems). It returns
+ * only the indices of items that exist; per-item properties (key, shift,
+ * resolved element) are looked up by each child component from the same
+ * adapter. See VEGATV-115306.
  *
  * @template ItemT The type of data items the list will use to render its items.
  * @template KeyT The type used as items unique identifiers (also called _keys_,
@@ -143,12 +151,16 @@ export declare function addFlexDirectionStyle(baseStyle: StyleProp<ViewStyle>, o
  *
  * @param {CarouselDataAdapter<ItemT, KeyT>} adapter An object with the data access
  *        APIs that allow us to retrieve items from an external source.
- * @param {RenderItemFunc<ItemT>} resolver
- * @param {number} initialIndex
- * @param {number} preferredBackCount
- * @param {number} dataLimit
+ * @param {number} initialIndex The data position to start retrieving from.
+ * @param {number} preferredBackCount Maximum number of items to place before
+ *        the initial selection.
+ * @param {number} dataLimit Maximum total items to retrieve.
+ *
+ * @return {number[]} The data indices of the items that should fill the
+ *         initial render window. Each child reads its own key, shift, and
+ *         resolved element from the adapter using these indices.
  */
-export declare function getInitialData<ItemT, KeyT>(adapter: CarouselDataAdapter<ItemT, KeyT>, resolver: RenderItemFunc<ItemT>, initialIndex: number, preferredBackCount: number, dataLimit: number): Array<CarouselResolvedDataValues<KeyT>>;
+export declare function computeInitialIndexWindow<ItemT, KeyT>(adapter: CarouselDataAdapter<ItemT, KeyT>, initialIndex: number, preferredBackCount: number, dataLimit: number): number[];
 /**
  * Function to hoist the workflow logic used when the `onSelectionChanged` event
  * happens.

package/dist/CarouselScrollable/native/CarouselNativeLogic.js

@@ -5,7 +5,7 @@
  * PROPRIETARY/CONFIDENTIAL. USE IS SUBJECT TO LICENSE TERMS.
  */
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.triggerOnItemBindCallback = exports.triggerOnItemUnbindCallback = exports.triggerOnSelectionChangeCallback = exports.getInitialData = exports.addFlexDirectionStyle = exports.callReset = exports.callNativeNotifyDataChange = exports.callNativeSetOverflowItemsVisible = exports.callNativeSetSelectedItem = exports.callNativeEnableInputEvents = void 0;
+exports.triggerOnItemBindCallback = exports.triggerOnItemUnbindCallback = exports.triggerOnSelectionChangeCallback = exports.computeInitialIndexWindow = exports.addFlexDirectionStyle = exports.callReset = exports.callNativeNotifyDataChange = exports.callNativeSetOverflowItemsVisible = exports.callNativeSetSelectedItem = exports.callNativeEnableInputEvents = void 0;
 const react_native_1 = require("react-native");
 const CarouselScrollableTypes_1 = require("../CarouselScrollableTypes");
 const CarouselNativeHostComponent_1 = require("./CarouselNativeHostComponent");
@@ -155,8 +155,24 @@ function addFlexDirectionStyle(baseStyle, orientation) {
 }
 exports.addFlexDirectionStyle = addFlexDirectionStyle;
 /**
- * This function is the core logic to retrieve items on the {@link CarouselScrollable}
- * initial render.
+ * Step values used by {@link computeInitialIndexWindow}'s walk helper. The
+ * numeric value doubles as the arithmetic increment used to advance the
+ * position: `BACKWARD` is `-1`, `FORWARD` is `+1`.
+ */
+var WalkStep;
+(function (WalkStep) {
+    WalkStep[WalkStep["BACKWARD"] = -1] = "BACKWARD";
+    WalkStep[WalkStep["FORWARD"] = 1] = "FORWARD";
+})(WalkStep || (WalkStep = {}));
+/**
+ * This function determines which data indices should fill the
+ * {@link CarouselScrollable}'s initial render window.
+ *
+ * It does NOT eagerly resolve per-item content (key, shift, JSX). Each child
+ * component looks those up itself from the same adapter using its assigned
+ * `dataIndex`. This function only checks **whether data is available** at each
+ * candidate index — it walks the adapter, calling `getItem` to confirm a slot
+ * is fillable, and collects the indices that succeed.
  *
  * It will try in different ways to get as many items as defined by the
  * `dataLimit` argument.
@@ -175,9 +191,11 @@ exports.addFlexDirectionStyle = addFlexDirectionStyle;
  *    **before** the last item retrieved at step 2 until we have a total of
  *    `dataLimit` items, or the last item we retrieved was at position `0`;
  *
- * Internally, `getInitialData` uses the {@link resolveDataItems} function to
- * guarantee that failed items are resolved (and accounted for) by the given
- * adapter.
+ * This function walks the adapter with retry logic to handle transient item
+ * retrieval failures (same retry semantics as resolveDataItems). It returns
+ * only the indices of items that exist; per-item properties (key, shift,
+ * resolved element) are looked up by each child component from the same
+ * adapter. See VEGATV-115306.
  *
  * @template ItemT The type of data items the list will use to render its items.
  * @template KeyT The type used as items unique identifiers (also called _keys_,
@@ -185,59 +203,125 @@ exports.addFlexDirectionStyle = addFlexDirectionStyle;
  *
  * @param {CarouselDataAdapter<ItemT, KeyT>} adapter An object with the data access
  *        APIs that allow us to retrieve items from an external source.
- * @param {RenderItemFunc<ItemT>} resolver
- * @param {number} initialIndex
- * @param {number} preferredBackCount
- * @param {number} dataLimit
+ * @param {number} initialIndex The data position to start retrieving from.
+ * @param {number} preferredBackCount Maximum number of items to place before
+ *        the initial selection.
+ * @param {number} dataLimit Maximum total items to retrieve.
+ *
+ * @return {number[]} The data indices of the items that should fill the
+ *         initial render window. Each child reads its own key, shift, and
+ *         resolved element from the adapter using these indices.
  */
-function getInitialData(adapter, resolver, initialIndex, preferredBackCount, dataLimit) {
+function computeInitialIndexWindow(adapter, initialIndex, preferredBackCount, dataLimit) {
     const initialData = [];
     let startIndex = initialIndex;
     let endIndex = initialIndex;
+    const maxRetries = CarouselData_1.ITEM_FAILURE_DEFAULT_MAX_RETRIES;
+    // Helper: attempt to read a single item at `index` and add its index to the
+    // collection via `addIndex` on success. Retries on transient adapter failures
+    // up to `maxRetries` or until `notifyDataError` returns false. Returns true
+    // if an index was added, false if the read failed permanently.
+    function tryReadAndAddItem(index, errorReadConfig, addIndex) {
+        let retryCount = 0;
+        while (retryCount < maxRetries) {
+            const itemData = adapter.getItem(index);
+            if (itemData !== undefined) {
+                addIndex(index);
+                return true;
+            }
+            // Notify the adapter about the read failure and check if we should retry
+            const shouldRetry = adapter.notifyDataError({
+                index,
+                readConfig: { ...errorReadConfig, maxRetries },
+                reason: CarouselData_1.CarouselDataErrorReason.CANNOT_READ,
+            });
+            if (!shouldRetry) {
+                break;
+            }
+            retryCount++;
+        }
+        return false;
+    }
+    // Helper: walk in a direction (forward or backward) reading items until the
+    // predicate stops or a read fails permanently. Each per-position read with
+    // retries is delegated to tryReadAndAddItem so retry semantics live in one
+    // place.
+    //
+    // The `step` enum value doubles as the arithmetic increment for advancing
+    // the position. We map it to the corresponding CarouselDataReadDirection
+    // value so the notifyDataError payload uses the public direction enum.
+    //
+    // Note: shouldContinue is consulted once per position rather than on every
+    // retry within tryReadAndAddItem. Existing callers' predicates depend only
+    // on `index` (which doesn't change mid-retry) and on initialData.length
+    // (which only grows on success), so this is observably equivalent to
+    // checking on every attempt.
+    function walkItems(start, step, shouldContinue, addIndex) {
+        const errorReadConfig = {
+            startIndex: start,
+            readDirection: step === WalkStep.BACKWARD
+                ? CarouselData_1.CarouselDataReadDirection.BACKWARDS
+                : CarouselData_1.CarouselDataReadDirection.FORWARD,
+        };
+        let index = start;
+        let lastSuccessIndex;
+        while (shouldContinue(index)) {
+            if (!tryReadAndAddItem(index, errorReadConfig, addIndex)) {
+                break;
+            }
+            lastSuccessIndex = index;
+            index += step;
+        }
+        return lastSuccessIndex;
+    }
     // To get our initial data set without information about how many items are
     // available, we'll need to preemptively request items from our data adapter,
     // and stop when there is no more data available, or we got `maxRenderItems`
     // items.
-    // We start by pulling the item in the selected index position...
-    (0, CarouselData_1.resolveDataItems)(adapter, resolver, (0, CarouselData_1.dataReadAtTargetConfig)(initialIndex), (resolved) => {
-        initialData.push(resolved);
+    // Step 1: We start by pulling the item in the selected index position...
+    tryReadAndAddItem(initialIndex, {
+        startIndex: initialIndex,
+        readDirection: CarouselData_1.CarouselDataReadDirection.AT_TARGET,
+    }, index => {
+        initialData.push(index);
     });
     // If our adapter did not return an item for the initial position, we can
     // assume this list is empty for now.
     if (initialData.length > 0) {
-        // If we have the initial index, we try to get items to place **before** the
-        // selected one; we do this because of the `scrollOffsetCount` property that
-        // limits how many items we can have before the selected one, and not after
-        // it.
-        startIndex =
-            (0, CarouselData_1.resolveDataItems)(adapter, resolver, (0, CarouselData_1.dataReadBackwardsConfig)(initialIndex - 1, index => index >= 0 &&
-                initialData.length <= dataLimit &&
-                initialIndex - index <= preferredBackCount), (resolved) => {
-                initialData.unshift(resolved);
-            }) ?? initialIndex;
-        // Once we have all the items before the selected one, we're free to request
-        // the rest of the items in our initial data set after the selected item.
-        endIndex =
-            (0, CarouselData_1.resolveDataItems)(adapter, resolver, (0, CarouselData_1.dataReadForwardConfig)(initialIndex + 1, () => initialData.length < dataLimit), (resolved) => {
-                initialData.push(resolved);
-            }) ?? initialIndex;
-        // Sometimes, after retrieving items before and after the selected one, we
-        // still don't have enough items to match `renderedItemsCount` count, and when
-        // this happens, there are two possible reasons:
+        // Step 2: If we have the initial index, we try to get items to place
+        // **before** the selected one; we do this because of the
+        // `scrollOffsetCount` property that limits how many items we can have
+        // before the selected one, and not after it.
+        const backResult = walkItems(initialIndex - 1, WalkStep.BACKWARD, index => index >= 0 &&
+            initialData.length <= dataLimit &&
+            initialIndex - index <= preferredBackCount, index => {
+            initialData.unshift(index);
+        });
+        startIndex = backResult ?? initialIndex;
+        // Step 3: Once we have all the items before the selected one, we're free
+        // to request the rest of the items in our initial data set after the
+        // selected item.
+        const forwardResult = walkItems(initialIndex + 1, WalkStep.FORWARD, () => initialData.length < dataLimit, index => {
+            initialData.push(index);
+        });
+        endIndex = forwardResult ?? initialIndex;
+        // Step 4: Sometimes, after retrieving items before and after the selected
+        // one, we still don't have enough items to match `renderedItemsCount`
+        // count, and when this happens, there are two possible reasons:
         //   1. There is no more data available in the data set;
         //   2. The `initialStartIndex` is close to the end of the data set;
         // In the first case, there is nothing for us to do, but on the second one,
         // we should try to go backwards while we still have data to fill our
         // initial data array.
         if (endIndex - startIndex < dataLimit - 1) {
-            (0, CarouselData_1.resolveDataItems)(adapter, resolver, (0, CarouselData_1.dataReadBackwardsConfig)(startIndex - 1, index => index >= 0 && initialData.length < dataLimit), (resolved) => {
-                initialData.unshift(resolved);
+            walkItems(startIndex - 1, WalkStep.BACKWARD, index => index >= 0 && initialData.length < dataLimit, index => {
+                initialData.unshift(index);
             });
         }
     }
     return initialData;
 }
-exports.getInitialData = getInitialData;
+exports.computeInitialIndexWindow = computeInitialIndexWindow;
 /**
  * Function to hoist the workflow logic used when the `onSelectionChanged` event
  * happens.

package/dist/CarouselScrollable/native/CarouselNativeWrapper.js

@@ -62,9 +62,7 @@ function CarouselNativeInner(rawProps, ref) {
     // To conform to the logic on the native layer and to accomplish the same behavior we multiple the two scale factors together to yield 1.316. Instead of applying this adjusted scale factor to the selected dimensions
     // we apply this scale factor to the unselected dimensions which the user perceives as the item shrinking when the item is pressed
     const adjustedPressedItemScaleFactor = focusedItemScaleFactor * pressedItemScaleFactor;
-    const renderedFrames = react_1.default.useRef(renderedItemsCount);
-    const lastInitialData = react_1.default.useRef(undefined);
-    const lastParentId = react_1.default.useRef(undefined);
+    const [renderedFrames] = react_1.default.useState(() => renderedItemsCount);
     const onNativeSelectionChanged = react_1.default.useCallback(event => {
         (0, CarouselNativeLogic_1.triggerOnSelectionChangeCallback)(onSelectionChanged, event);
     }, [onSelectionChanged]);
@@ -84,34 +82,41 @@ function CarouselNativeInner(rawProps, ref) {
         };
     });
     const styleWithFlexDirection = react_1.default.useMemo(() => (0, CarouselNativeLogic_1.addFlexDirectionStyle)(style, orientation), [style, orientation]);
-    let initialData = lastInitialData.current && lastInitialData.current.length !== 0
-        ? lastInitialData.current
-        : (0, CarouselNativeLogic_1.getInitialData)(dataAdapter, renderItem, initialStartIndexInternal, numOffsetItems, renderedFrames.current);
-    if (!lastParentId.current || !lastInitialData.current) {
-        lastParentId.current = uniqueId;
-        lastInitialData.current = initialData;
-    }
-    if (lastParentId.current !== uniqueId) {
-        initialData = (0, CarouselNativeLogic_1.getInitialData)(dataAdapter, renderItem, initialStartIndexInternal, numOffsetItems, renderedFrames.current);
-        lastParentId.current = uniqueId;
-        lastInitialData.current = initialData;
-    }
+    const initialDataLimit = Math.min(renderedFrames, dataAdapter.getItemCount());
+    const hasData = initialDataLimit > 0;
+    // Cache initialData (the array of dataIndices to seed the children with)
+    // on (uniqueId, hasData). The events where the parent's initialData is
+    // actually consumed by the rest of the system are first render, uniqueId
+    // change (soft rebind), and the empty -> non-empty data arrival. Outside
+    // those moments children are driven by native onBind callbacks and
+    // shouldComponentUpdate blocks parent-driven re-renders, so a wider cache
+    // key would just do unnecessary work.
+    //
+    // react-hooks/exhaustive-deps is suppressed because the closure references
+    // dataAdapter / initialStartIndexInternal / numOffsetItems /
+    // initialDataLimit, which we intentionally do NOT include in the dep array
+    // — those values are re-read fresh from the closure when the memo
+    // recomputes, and adding them to the deps would invalidate on every
+    // adapter reference change without a corresponding need to refresh
+    // initialData. See VEGATV-115306.
+    const initialData = react_1.default.useMemo(() => (0, CarouselNativeLogic_1.computeInitialIndexWindow)(dataAdapter, initialStartIndexInternal, numOffsetItems, initialDataLimit), 
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+    [uniqueId, hasData]);
     (0, react_1.useEffect)(() => {
         dataAdapter.registerDataChangeCallback?.(onDataChangeCallback);
     }, [dataAdapter, onDataChangeCallback]);
     const startIndex = 0;
     const endIndex = dataAdapter.getItemCount();
-    const indices = initialData.map(data => data.index);
     const relativeInitialStartIndex = react_1.default.useMemo(() => {
-        const relativeIndex = indices.indexOf(initialStartIndexInternal);
+        const relativeIndex = initialData.indexOf(initialStartIndexInternal);
         return relativeIndex < 0 ? 0 : relativeIndex;
-    }, [indices, initialStartIndexInternal]);
-    utils_1.Log.i(`[CarouselScrollable] Rendering Carousel Native Wrapper "${uniqueId || ''}", startIndex = ${startIndex}, endIndex = ${endIndex}, initialSelectedIndex : ${initialStartIndexInternal}, initialData Length : ${initialData.length}, initialData Indices : ${JSON.stringify(indices)}`);
+    }, [initialData, initialStartIndexInternal]);
+    utils_1.Log.i(`[CarouselScrollable] Rendering Carousel Native Wrapper "${uniqueId ?? ''}", startIndex = ${startIndex}, endIndex = ${endIndex}, initialSelectedIndex : ${initialStartIndexInternal}, initialData Length : ${initialData.length}, initialData Indices : ${JSON.stringify(initialData)}`);
     return (<CarouselNativeHostComponent_1.CarouselNativeHostComponent {...props} initialStartIndex={initialStartIndexInternal} relativeInitialStartIndex={relativeInitialStartIndex} dataStartIndex={startIndex} dataLimitIndex={endIndex} style={styleWithFlexDirection} scaleItemOnPress={pressedItemScaleFactor != 1.0} scaleItemOnSelection={focusedItemScaleFactor !== 1.0} shiftItemsOnSelection={shiftItemsOnSelection.width !== 1.0 ||
             shiftItemsOnSelection.height !== 1.0} onSelectionChanged={onNativeSelectionChanged} ref={hostRef}>
-      {Array(renderedFrames.current)
+      {Array(renderedFrames)
             .fill({})
-            .map((_, index) => (<CarouselNativeItemWrapper_1.CarouselNativeItemWrapper key={index} parentId={uniqueId} dataIndex={initialData[index]?.index} itemShift={initialData[index]?.shift} initialElement={initialData[index]?.element} initialKey={initialData[index]?.key} showSelectionBorder={showSelectionBorder} selectionBorderStyle={selectionBorderStyle} selectionBorderStrategy={selectionBorderStrategy} focusedItemScaleFactor={focusedItemScaleFactor} pressedItemScaleFactor={adjustedPressedItemScaleFactor} shiftItemsScaleFactor={shiftItemsOnSelection} dataAdapter={dataAdapter} renderItem={renderItem} bindCallback={bindCallback} unbindCallback={unbindCallback}/>))}
+            .map((_, index) => (<CarouselNativeItemWrapper_1.CarouselNativeItemWrapper key={index} parentId={uniqueId} dataIndex={initialData[index]} showSelectionBorder={showSelectionBorder} selectionBorderStyle={selectionBorderStyle} selectionBorderStrategy={selectionBorderStrategy} focusedItemScaleFactor={focusedItemScaleFactor} pressedItemScaleFactor={adjustedPressedItemScaleFactor} shiftItemsScaleFactor={shiftItemsOnSelection} dataAdapter={dataAdapter} renderItem={renderItem} bindCallback={bindCallback} unbindCallback={unbindCallback}/>))}
     </CarouselNativeHostComponent_1.CarouselNativeHostComponent>);
 }
 /**

package/dist/CarouselScrollable/recyclerview/JSRecyclerViewList.js

@@ -101,9 +101,14 @@ function JSRecyclerViewListInner(props, _ref) {
         if (!c || !c.props) {
             return c;
         }
+        // Build override props without mutating the original element. React 18+
+        // freezes element.props in development, so direct assignment to
+        // c.props throws TypeError. cloneElement returns a new element with
+        // the merged props instead. See VEGATV-115306.
+        const overrideProps = {};
         if (hasProperty(c.props, 'onFocusChanged')) {
             const { onFocusChanged } = c.props;
-            c.props.onFocusChanged = (event) => {
+            overrideProps.onFocusChanged = (event) => {
                 if (event.focused) {
                     scrollableRef.current?.scrollToIndex(index, true);
                 }
@@ -112,14 +117,16 @@ function JSRecyclerViewListInner(props, _ref) {
         }
         if (hasProperty(c.props, 'onItemFocusChanged')) {
             const { onItemFocusChanged } = c.props;
-            c.props.onItemFocusChanged = (childItem) => {
+            overrideProps.onItemFocusChanged = (childItem) => {
                 if (childItem.childEvent.focused) {
                     scrollableRef.current?.scrollToIndex(index, true);
                 }
                 onItemFocusChanged(childItem);
             };
         }
-        return c;
+        return Object.keys(overrideProps).length > 0
+            ? React.cloneElement(c, overrideProps)
+            : c;
     }, [dataAdapter, renderItem]);
     const minStyle = {
         minHeight: 1,

package/package.json

@@ -1 +1 @@
-{"name": "@amazon-devices/vega-carousel", "version": "1.0.0", "main": "dist/index.js", "types": "dist/index.d.ts", "files": ["dist", "react-native.config.js", "THIRD_PARTY_NOTICES.txt"], "scripts": {"clean": "rm -rf build dist generated logs node_modules", "test:snapshot": "jest --colors --updateSnapshot", "start": "node node_modules/react-native/local-cli/cli.js start", "test": "jest --colors", "lint": "eslint src --ext .ts,.tsx", "lint:fix": "eslint src --ext .ts,.tsx --fix", "lint-staged": "lint-staged --allow-empty", "format": "clang-format -i --glob=\"native/**/*.{cpp,h}\"", "git-commit-template": "git-commit-template .git-commit-template", "compile": "tsc -p tsconfig-build.json", "release": "npm-run-all format build", "build:js": "tsc -p tsconfig-build.json", "build:native:debug": "vega build -b Debug", "build:native:release": "vega build -b Release", "build:debug": "npm-run-all build:js build:native:debug", "build": "npm-run-all build:js build:native:debug build:native:release"}, "dependencies": {"ansi-colors": "^4.1.3"}, "devDependencies": {"@amazon-devices/react-native-kepler": "^4.0.0", "@babel/core": "^7.20.0", "@babel/plugin-transform-private-methods": "^7.23.3", "@babel/runtime": "^7.20.0", "@bam.tech/jest-junit-reports-merger": "^1.1.0", "@react-native-community/eslint-config": "^3.2.0", "@testing-library/jest-native": "^5.4.3", "@testing-library/react-native": "^13.0.0", "@types/jest": "^28.0.0", "@types/react": "^19.0.0", "@types/react-test-renderer": "^19.0.0", "@typescript-eslint/eslint-plugin": "^5.18.0", "babel-jest": "^29.0.0", "clang-format": "^1.8.0", "eslint": "^8.19.0", "eslint-plugin-react-native": "^4.1.0", "git-commit-template": "^1.0.5", "lint-staged": "^12.3.7", "jest": "^29.0.0", "jest-junit": "^16.0.0", "metro-react-native-babel-preset": "^0.76.5", "npm-run-all": "^4.1.5", "prettier": "^3.0.0", "react": "^19.0.0", "react-native": "^0.83.0", "react-test-renderer": "^19.0.0", "recyclerlistview": "4.2.1", "ts-jest": "^29.0.0", "typedoc": "^0.25.7", "typescript": "4.9.5", "@amazon-devices/kepler-cli-platform": "^0", "@react-native-community/cli": "^11.2.0"}, "peerDependencies": {"@amazon-devices/react-native-kepler": "^4.0.0", "react": "^19.0.0", "react-native": "^0.83.0"}, "kepler": {"projectType": "turbomodule", "toolchain": "clang", "targets": ["tv"], "os": ["vega"]}, "eslintConfig": {"extends": "@react-native-community", "parser": "@typescript-eslint/parser", "plugins": ["@typescript-eslint"], "root": true}, "prettier": {"arrowParens": "avoid", "bracketSameLine": true, "bracketSpacing": false, "singleQuote": true, "trailingComma": "all"}, "npm-pretty-much": {"allowUnsafeName": "reason for using a unsafe name"}, "license": "See license in LICENSE"}
+{"name": "@amazon-devices/vega-carousel", "version": "1.0.1", "main": "dist/index.js", "types": "dist/index.d.ts", "files": ["dist", "react-native.config.js", "THIRD_PARTY_NOTICES.txt"], "scripts": {"clean": "rm -rf build dist generated logs node_modules", "test:snapshot": "jest --colors --updateSnapshot", "start": "node node_modules/react-native/local-cli/cli.js start", "test": "jest --colors", "lint": "eslint src --ext .ts,.tsx", "lint:fix": "eslint src --ext .ts,.tsx --fix", "lint-staged": "lint-staged --allow-empty", "format": "clang-format -i --glob=\"native/**/*.{cpp,h}\"", "git-commit-template": "git-commit-template .git-commit-template", "compile": "tsc -p tsconfig-build.json", "release": "npm-run-all format build", "build:js": "tsc -p tsconfig-build.json", "build:native:debug": "vega build -b Debug", "build:native:release": "vega build -b Release", "build:debug": "npm-run-all build:js build:native:debug", "build": "npm-run-all build:js build:native:debug build:native:release"}, "dependencies": {"ansi-colors": "^4.1.3"}, "devDependencies": {"@amazon-devices/react-native-kepler": "^4.0.0", "@babel/core": "^7.20.0", "@babel/plugin-transform-private-methods": "^7.23.3", "@babel/runtime": "^7.20.0", "@bam.tech/jest-junit-reports-merger": "^1.1.0", "@react-native-community/eslint-config": "^3.2.0", "@testing-library/jest-native": "^5.4.3", "@testing-library/react-native": "^13.0.0", "@types/jest": "^28.0.0", "@types/react": "^19.0.0", "@types/react-test-renderer": "^19.0.0", "@typescript-eslint/eslint-plugin": "^5.18.0", "babel-jest": "^29.0.0", "clang-format": "^1.8.0", "eslint": "^8.19.0", "eslint-plugin-react-native": "^4.1.0", "git-commit-template": "^1.0.5", "lint-staged": "^12.3.7", "jest": "^29.0.0", "jest-junit": "^16.0.0", "metro-react-native-babel-preset": "^0.76.5", "npm-run-all": "^4.1.5", "prettier": "^3.0.0", "react": "^19.0.0", "react-native": "^0.83.0", "react-test-renderer": "^19.0.0", "recyclerlistview": "4.2.1", "ts-jest": "^29.0.0", "typedoc": "^0.25.7", "typescript": "4.9.5", "@amazon-devices/kepler-cli-platform": "^0", "@react-native-community/cli": "^11.2.0"}, "peerDependencies": {"@amazon-devices/react-native-kepler": "^4.0.0", "react": "^19.0.0", "react-native": "^0.83.0"}, "kepler": {"projectType": "turbomodule", "toolchain": "clang", "targets": ["tv"], "os": ["vega"]}, "eslintConfig": {"extends": "@react-native-community", "parser": "@typescript-eslint/parser", "plugins": ["@typescript-eslint"], "root": true}, "prettier": {"arrowParens": "avoid", "bracketSameLine": true, "bracketSpacing": false, "singleQuote": true, "trailingComma": "all"}, "npm-pretty-much": {"allowUnsafeName": "reason for using a unsafe name"}, "license": "See license in LICENSE"}