@amazon-devices/vega-carousel 0.1.3

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

@@ -0,0 +1,209 @@
+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 { AnyValue } from '../../utils';
+/**
+ * Auxiliary function use to invoke the `enableInputEvents` native function on
+ * the component's native layer.
+ *
+ * Although this function is simple enough that we could inline it in the
+ * {@link CarouselNativeWrapper} component function, we decided to externalize
+ * it with dependency inversion to make the component code cleaner, and to allow
+ * us to write individual tests for it.
+ *
+ * For details about the native function itself, check the
+ * {@link CarouselScrollableRef.enableInputEvents} documentation.
+ *
+ * @param {HostComponent<CarouselNativeHostComponentProps> | null} hostComponent
+ *        The `ref` object for the native component. It accepts the component or
+ *        `null` because such a `ref` is usually created with the `null` initial
+ *        value.
+ * @param {boolean} enable Flag indicating if the list should handle input
+ *        events or not.
+ *
+ * @see {@link CarouselScrollableRef.enableInputEvents}
+ */
+export declare function callNativeEnableInputEvents(hostComponent: HostComponent<CarouselNativeHostComponentProps> | null, enable: boolean): void;
+/**
+ * Auxiliary function use to invoke the `setSelectedItem` native function on
+ * the component's native layer.
+ *
+ * Although this function is simple enough that we could inline it in the
+ * {@link CarouselNativeWrapper} component function, we decided to externalize
+ * it with dependency inversion to make the component code cleaner, and to allow
+ * us to write individual tests for it.
+ *
+ * For details about the native function itself, check the
+ * {@link CarouselScrollableRef.setSelectedItem} documentation.
+ *
+ * @param {HostComponent<CarouselNativeHostComponentProps> | null} hostComponent
+ *        The `ref` object for the native component. It accepts the component or
+ *        `null` because such a `ref` is usually created with the `null` initial
+ *        value.
+ * @param {number} index The data index of the item that should be selected
+ *        after the scroll ends.
+ * @param {boolean} animated Optional flag indicating if the requested
+ *        selection should be animated or not. It defaults to `false`.
+
+ *
+ * @see {@link CarouselScrollableRef.setSelectedItem}
+ */
+export declare function callNativeSetSelectedItem(hostComponent: HostComponent<CarouselNativeHostComponentProps> | null, index: number, animated?: boolean): void;
+/**
+ * Auxiliary function use to invoke the `setOverflowItemsVisible` native
+ * function on the component's native layer.
+ *
+ * Although this function is simple enough that we could inline it in the
+ * {@link CarouselNativeWrapper} component function, we decided to externalize
+ * it with dependency inversion to make the component code cleaner, and to allow
+ * us to write individual tests for it.
+ *
+ * For details about the native function itself, check the
+ * {@link CarouselScrollableRef.setOverflowItemsVisible} documentation.
+ *
+ * @param {HostComponent<CarouselNativeHostComponentProps> | null} hostComponent
+ *        The `ref` object for the native component. It accepts the component or
+ *        `null` because such a `ref` is usually created with the `null` initial
+ *        value.
+ * @param {boolean} visible Flag indicating if the _outer items_ should be
+ *        hidden (`false`), or shown (`true`).
+ * @param {boolean} animated Indicates if the show/hide action should be
+ *        animated or not.
+ *
+ * @see {@link CarouselScrollableRef.setOverflowItemsVisible}
+ */
+export declare function callNativeSetOverflowItemsVisible(hostComponent: HostComponent<CarouselNativeHostComponentProps> | null, visible: boolean, animated?: boolean): void;
+/**
+ * Auxiliary function use to invoke the `notifyDataChange` native function on
+ * the component's native layer.
+ *
+ * Although this function is simple enough that we could inline it in the
+ * {@link CarouselNativeWrapper} component function, we decided to externalize
+ * it with dependency inversion to make the component code cleaner, and to allow
+ * us to write individual tests for it.
+ *
+ * For details about the native function itself, check the
+ * {@link CarouselScrollableRef.notifyDataChange} documentation.
+ *
+ * @param {HostComponent<CarouselNativeHostComponentProps> | null} hostComponent
+ *        The `ref` object for the native component. It accepts the component or
+ *        `null` because such a `ref` is usually created with the `null` initial
+ *        value.
+ * @param {Array<CarouselDataChange>} changes A list of all
+ *        changes that happened to the backing data.
+ * @param {boolean} animated Flag indicating if the change operation should be
+ *        animated or not.
+ *
+ * @see {@link CarouselScrollableRef.notifyDataChange}
+ */
+export declare function callNativeNotifyDataChange(hostComponent: HostComponent<CarouselNativeHostComponentProps> | null, changes: Array<CarouselDataChange>, animated?: boolean): void;
+export declare function callReset(hostComponent: HostComponent<CarouselNativeHostComponentProps> | null): void;
+/**
+ * Helper function that can combine a base style object with a _row_ or _column_
+ * flex direction depending on the given `orientation`.
+ *
+ * @param {StyleProp<ViewStyle>} baseStyle The current style object to use as
+ *        the base property.
+ * @param {ListOrientation} orientation The list component orientation used to
+ *        define if we use a _row_ or a _column_ flex direction style.
+ *
+ * @return {StyleProp<ViewStyle>} Returns a combined style between the given
+ *         `baseStyle` and a _row_ or _column_ flex direction.
+ */
+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.
+ *
+ * It will try in different ways to get as many items as defined by the
+ * `dataLimit` argument.
+ *
+ * It only returns an array with fewer items than `dataLimit` if the given
+ * `adapter` does not have that many items.
+ *
+ * The overall workflow in this function is, as follows:
+ *
+ * 1. Get the item **at** the `initialIndex` position;
+ * 2. Get items **before** the `initialIndex` position so we have as many as
+ *    `preferredBackCount`;
+ * 3. Get items **after** the `initialIndex` position until we have a total of
+ *    `dataLimit` items, or the `adapter` has no more items;
+ * 4. If our array of items has fewer items than `dataLimit`, get items
+ *    **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.
+ *
+ * @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_,
+ *           or _stable IDs_) in the list;
+ *
+ * @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
+ */
+export declare function getInitialData<ItemT, KeyT>(adapter: CarouselDataAdapter<ItemT, KeyT>, resolver: RenderItemFunc<ItemT>, initialIndex: number, preferredBackCount: number, dataLimit: number): Array<CarouselResolvedDataValues<KeyT>>;
+/**
+ * Function to hoist the workflow logic used when the `onSelectionChanged` event
+ * happens.
+ *
+ * It checks if the required callback is present, and if it is, it will build
+ * the expected event out of the native one to pass it to the callback.
+ *
+ * @param {OnSelectionChangedCallback} callback The function to be called when
+ *        the `onSelectionChanged` event happens.
+ * @param {CarouselNativeHostComponentSelectionChangedEvent} event The native
+ *        event emitted by the native layer.
+ */
+export declare function triggerOnSelectionChangeCallback(callback: OnSelectionChangedCallback | undefined, event: CarouselNativeHostComponentSelectionChangedEvent): void;
+/**
+ * Function to hoist the workflow logic used when the `onItemUnbind` event
+ * happens.
+ *
+ * It will provide a `storeData` function to the callback that can be used to
+ * save any arbitrary data for the outbound item that can be used again when
+ * the same item gets recycled back into the list.
+ *
+ * @template ItemT The type of the data object used as an _item_ in the list
+ *           component.
+ * @template KeyT The type used as items unique identifiers (also called _keys_,
+ *           or _stable IDs_) in the list;
+ *
+ * @param {OnItemUnbindFunc<ItemT> | undefined} callback The function to be
+ *        called when the `onItemUnbind` event happens.
+ * @param {CarouselDataAdapter<ItemT, KeyT>} adapter Data adapter to use to
+ *        retrieve items and its stable ID.
+ * @param {Map<KeyT, any>} stateMap The map object that stores all the
+ *        children's state on the list component.
+ * @param {number} itemIndex The data index for the item that is about to be
+ *        unbound from its native frame.
+ */
+export declare function triggerOnItemUnbindCallback<ItemT, KeyT>(callback: OnItemUnbindFunc<ItemT> | undefined, adapter: CarouselDataAdapter<ItemT, KeyT>, stateMap: Map<KeyT, AnyValue>, itemIndex: number): void;
+/**
+ * Function to hoist the workflow logic used when the `onItemBind` event
+ * happens.
+ *
+ * It will pass a previously stored item state to the callback if one was saved
+ * by calling the `storeState` function from the `onItemUnbind` event.
+ *
+ * @template ItemT The type of the data object used as an _item_ in the list
+ *           component.
+ * @template KeyT The type used as items unique identifiers (also called _keys_,
+ *           or _stable IDs_) in the list;
+ *
+ * @param {OnItemBindFunc<ItemT> | undefined} callback The function to be called
+ *        when the `onItemBind` event happens.
+ * @param {CarouselDataAdapter<ItemT, KeyT>} adapter Data adapter to use to
+ *        retrieve items and its stable ID.
+ * @param {Map<KeyT, any>} stateMap The map object that stores all the
+ *        children's state on the list component.
+ * @param {number} itemIndex The data index for the item that is about to be
+ *        bound to its native frame.
+ */
+export declare function triggerOnItemBindCallback<ItemT, KeyT>(callback: OnItemBindFunc<ItemT> | undefined, adapter: CarouselDataAdapter<ItemT, KeyT>, stateMap: Map<KeyT, AnyValue>, itemIndex: number): void;

package/dist/CarouselScrollable/native/CarouselNativeLogic.js

@@ -0,0 +1,349 @@
+"use strict";
+/*
+ * Copyright (c) 2024 - 2025 Amazon.com, Inc. or its affiliates. All rights reserved.
+ *
+ * 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;
+const react_native_1 = require("react-native");
+const CarouselScrollableTypes_1 = require("../CarouselScrollableTypes");
+const CarouselNativeHostComponent_1 = require("./CarouselNativeHostComponent");
+const CarouselData_1 = require("../../CarouselData");
+const utils_1 = require("../../utils");
+/**
+ * Auxiliary function use to invoke the `enableInputEvents` native function on
+ * the component's native layer.
+ *
+ * Although this function is simple enough that we could inline it in the
+ * {@link CarouselNativeWrapper} component function, we decided to externalize
+ * it with dependency inversion to make the component code cleaner, and to allow
+ * us to write individual tests for it.
+ *
+ * For details about the native function itself, check the
+ * {@link CarouselScrollableRef.enableInputEvents} documentation.
+ *
+ * @param {HostComponent<CarouselNativeHostComponentProps> | null} hostComponent
+ *        The `ref` object for the native component. It accepts the component or
+ *        `null` because such a `ref` is usually created with the `null` initial
+ *        value.
+ * @param {boolean} enable Flag indicating if the list should handle input
+ *        events or not.
+ *
+ * @see {@link CarouselScrollableRef.enableInputEvents}
+ */
+function callNativeEnableInputEvents(hostComponent, enable) {
+    if (hostComponent) {
+        CarouselNativeHostComponent_1.CarouselNativeHostComponentCommands.enableInputEvents(hostComponent, enable);
+    }
+}
+exports.callNativeEnableInputEvents = callNativeEnableInputEvents;
+/**
+ * Auxiliary function use to invoke the `setSelectedItem` native function on
+ * the component's native layer.
+ *
+ * Although this function is simple enough that we could inline it in the
+ * {@link CarouselNativeWrapper} component function, we decided to externalize
+ * it with dependency inversion to make the component code cleaner, and to allow
+ * us to write individual tests for it.
+ *
+ * For details about the native function itself, check the
+ * {@link CarouselScrollableRef.setSelectedItem} documentation.
+ *
+ * @param {HostComponent<CarouselNativeHostComponentProps> | null} hostComponent
+ *        The `ref` object for the native component. It accepts the component or
+ *        `null` because such a `ref` is usually created with the `null` initial
+ *        value.
+ * @param {number} index The data index of the item that should be selected
+ *        after the scroll ends.
+ * @param {boolean} animated Optional flag indicating if the requested
+ *        selection should be animated or not. It defaults to `false`.
+
+ *
+ * @see {@link CarouselScrollableRef.setSelectedItem}
+ */
+function callNativeSetSelectedItem(hostComponent, index, animated) {
+    if (hostComponent) {
+        CarouselNativeHostComponent_1.CarouselNativeHostComponentCommands.setSelectedItem(hostComponent, index, animated === true);
+    }
+}
+exports.callNativeSetSelectedItem = callNativeSetSelectedItem;
+/**
+ * Auxiliary function use to invoke the `setOverflowItemsVisible` native
+ * function on the component's native layer.
+ *
+ * Although this function is simple enough that we could inline it in the
+ * {@link CarouselNativeWrapper} component function, we decided to externalize
+ * it with dependency inversion to make the component code cleaner, and to allow
+ * us to write individual tests for it.
+ *
+ * For details about the native function itself, check the
+ * {@link CarouselScrollableRef.setOverflowItemsVisible} documentation.
+ *
+ * @param {HostComponent<CarouselNativeHostComponentProps> | null} hostComponent
+ *        The `ref` object for the native component. It accepts the component or
+ *        `null` because such a `ref` is usually created with the `null` initial
+ *        value.
+ * @param {boolean} visible Flag indicating if the _outer items_ should be
+ *        hidden (`false`), or shown (`true`).
+ * @param {boolean} animated Indicates if the show/hide action should be
+ *        animated or not.
+ *
+ * @see {@link CarouselScrollableRef.setOverflowItemsVisible}
+ */
+function callNativeSetOverflowItemsVisible(hostComponent, visible, animated) {
+    if (hostComponent) {
+        CarouselNativeHostComponent_1.CarouselNativeHostComponentCommands.setOverflowItemsVisible(hostComponent, visible, animated === true);
+    }
+}
+exports.callNativeSetOverflowItemsVisible = callNativeSetOverflowItemsVisible;
+/**
+ * Auxiliary function use to invoke the `notifyDataChange` native function on
+ * the component's native layer.
+ *
+ * Although this function is simple enough that we could inline it in the
+ * {@link CarouselNativeWrapper} component function, we decided to externalize
+ * it with dependency inversion to make the component code cleaner, and to allow
+ * us to write individual tests for it.
+ *
+ * For details about the native function itself, check the
+ * {@link CarouselScrollableRef.notifyDataChange} documentation.
+ *
+ * @param {HostComponent<CarouselNativeHostComponentProps> | null} hostComponent
+ *        The `ref` object for the native component. It accepts the component or
+ *        `null` because such a `ref` is usually created with the `null` initial
+ *        value.
+ * @param {Array<CarouselDataChange>} changes A list of all
+ *        changes that happened to the backing data.
+ * @param {boolean} animated Flag indicating if the change operation should be
+ *        animated or not.
+ *
+ * @see {@link CarouselScrollableRef.notifyDataChange}
+ */
+function callNativeNotifyDataChange(hostComponent, changes, animated) {
+    if (hostComponent) {
+        CarouselNativeHostComponent_1.CarouselNativeHostComponentCommands.notifyDataChange(hostComponent, changes, animated === true);
+    }
+}
+exports.callNativeNotifyDataChange = callNativeNotifyDataChange;
+function callReset(hostComponent) {
+    if (hostComponent) {
+        CarouselNativeHostComponent_1.CarouselNativeHostComponentCommands.reset(hostComponent);
+    }
+}
+exports.callReset = callReset;
+/** Helper style containing a _row_ flex direction. */
+const FlexDirectionRow = { flexDirection: 'row' };
+/** Helper style containing a _column_ flex direction. */
+const FlexDirectionColumn = { flexDirection: 'column' };
+/**
+ * Helper function that can combine a base style object with a _row_ or _column_
+ * flex direction depending on the given `orientation`.
+ *
+ * @param {StyleProp<ViewStyle>} baseStyle The current style object to use as
+ *        the base property.
+ * @param {ListOrientation} orientation The list component orientation used to
+ *        define if we use a _row_ or a _column_ flex direction style.
+ *
+ * @return {StyleProp<ViewStyle>} Returns a combined style between the given
+ *         `baseStyle` and a _row_ or _column_ flex direction.
+ */
+function addFlexDirectionStyle(baseStyle, orientation) {
+    return react_native_1.StyleSheet.compose(baseStyle, orientation === CarouselScrollableTypes_1.ListOrientation.HORIZONTAL
+        ? FlexDirectionRow
+        : FlexDirectionColumn);
+}
+exports.addFlexDirectionStyle = addFlexDirectionStyle;
+/**
+ * This function is the core logic to retrieve items on the {@link CarouselScrollable}
+ * initial render.
+ *
+ * It will try in different ways to get as many items as defined by the
+ * `dataLimit` argument.
+ *
+ * It only returns an array with fewer items than `dataLimit` if the given
+ * `adapter` does not have that many items.
+ *
+ * The overall workflow in this function is, as follows:
+ *
+ * 1. Get the item **at** the `initialIndex` position;
+ * 2. Get items **before** the `initialIndex` position so we have as many as
+ *    `preferredBackCount`;
+ * 3. Get items **after** the `initialIndex` position until we have a total of
+ *    `dataLimit` items, or the `adapter` has no more items;
+ * 4. If our array of items has fewer items than `dataLimit`, get items
+ *    **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.
+ *
+ * @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_,
+ *           or _stable IDs_) in the list;
+ *
+ * @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
+ */
+function getInitialData(adapter, resolver, initialIndex, preferredBackCount, dataLimit) {
+    const initialData = [];
+    let startIndex = initialIndex;
+    let endIndex = initialIndex;
+    // 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);
+    });
+    // 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:
+        //   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);
+            });
+        }
+    }
+    return initialData;
+}
+exports.getInitialData = getInitialData;
+/**
+ * Function to hoist the workflow logic used when the `onSelectionChanged` event
+ * happens.
+ *
+ * It checks if the required callback is present, and if it is, it will build
+ * the expected event out of the native one to pass it to the callback.
+ *
+ * @param {OnSelectionChangedCallback} callback The function to be called when
+ *        the `onSelectionChanged` event happens.
+ * @param {CarouselNativeHostComponentSelectionChangedEvent} event The native
+ *        event emitted by the native layer.
+ */
+function triggerOnSelectionChangeCallback(callback, event) {
+    if (callback) {
+        const selectionChangedEvent = {
+            selectedIndex: event.nativeEvent.selectedIndex,
+            renderedRange: {
+                start: event.nativeEvent.renderFirstIndex,
+                end: event.nativeEvent.renderLastIndex,
+            },
+        };
+        callback(selectionChangedEvent);
+    }
+}
+exports.triggerOnSelectionChangeCallback = triggerOnSelectionChangeCallback;
+/**
+ * Function to hoist the workflow logic used when the `onItemUnbind` event
+ * happens.
+ *
+ * It will provide a `storeData` function to the callback that can be used to
+ * save any arbitrary data for the outbound item that can be used again when
+ * the same item gets recycled back into the list.
+ *
+ * @template ItemT The type of the data object used as an _item_ in the list
+ *           component.
+ * @template KeyT The type used as items unique identifiers (also called _keys_,
+ *           or _stable IDs_) in the list;
+ *
+ * @param {OnItemUnbindFunc<ItemT> | undefined} callback The function to be
+ *        called when the `onItemUnbind` event happens.
+ * @param {CarouselDataAdapter<ItemT, KeyT>} adapter Data adapter to use to
+ *        retrieve items and its stable ID.
+ * @param {Map<KeyT, any>} stateMap The map object that stores all the
+ *        children's state on the list component.
+ * @param {number} itemIndex The data index for the item that is about to be
+ *        unbound from its native frame.
+ */
+function triggerOnItemUnbindCallback(callback, adapter, stateMap, itemIndex) {
+    if (callback) {
+        const item = adapter.getItem(itemIndex);
+        if (item !== undefined) {
+            const key = adapter.getItemKey(item, itemIndex);
+            if (key !== undefined) {
+                callback(item, itemIndex, (data) => {
+                    stateMap.set(key, data);
+                });
+            }
+            else {
+                utils_1.Log.d('The item at position {0} is being unbound, but it does not have a KEY to store its state', itemIndex);
+                callback(item, itemIndex, () => { });
+            }
+        }
+        else {
+            utils_1.Log.d('There was a request to unbind item at position {0} but there is no item in that position', itemIndex);
+        }
+    }
+}
+exports.triggerOnItemUnbindCallback = triggerOnItemUnbindCallback;
+/**
+ * Function to hoist the workflow logic used when the `onItemBind` event
+ * happens.
+ *
+ * It will pass a previously stored item state to the callback if one was saved
+ * by calling the `storeState` function from the `onItemUnbind` event.
+ *
+ * @template ItemT The type of the data object used as an _item_ in the list
+ *           component.
+ * @template KeyT The type used as items unique identifiers (also called _keys_,
+ *           or _stable IDs_) in the list;
+ *
+ * @param {OnItemBindFunc<ItemT> | undefined} callback The function to be called
+ *        when the `onItemBind` event happens.
+ * @param {CarouselDataAdapter<ItemT, KeyT>} adapter Data adapter to use to
+ *        retrieve items and its stable ID.
+ * @param {Map<KeyT, any>} stateMap The map object that stores all the
+ *        children's state on the list component.
+ * @param {number} itemIndex The data index for the item that is about to be
+ *        bound to its native frame.
+ */
+function triggerOnItemBindCallback(callback, adapter, stateMap, itemIndex) {
+    if (callback) {
+        const item = adapter.getItem(itemIndex);
+        if (item !== undefined) {
+            const key = adapter.getItemKey(item, itemIndex);
+            let itemState;
+            if (key !== undefined) {
+                itemState = stateMap.get(key);
+            }
+            else {
+                utils_1.Log.d('The item at position {0} is being bound, but it does not have a KEY to retrieve its past state', itemIndex);
+            }
+            callback(item, itemIndex, itemState);
+        }
+        else {
+            utils_1.Log.d('There was a request to bind item at position {0} but there is no item in that position', itemIndex);
+        }
+    }
+}
+exports.triggerOnItemBindCallback = triggerOnItemBindCallback;

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

@@ -0,0 +1,68 @@
+import React from 'react';
+import { CarouselScrollableProps } from '../CarouselScrollableProps';
+import type { CarouselScrollableRef } from '../CarouselScrollableRef';
+/**
+ * Internal implementation of the {@link CarouselNativeWrapper} component.
+ *
+ * Check the {@link CarouselNativeWrapper} documentation for details on this component.
+ *
+ * @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_,
+ *           or _stable IDs_) in the list;
+ *
+ * @see {@link CarouselNativeWrapper}
+ */
+declare function CarouselNativeInner<ItemT, KeyT = React.Key>(rawProps: CarouselScrollableProps<ItemT, KeyT>, ref?: React.Ref<CarouselScrollableRef>): React.JSX.Element;
+/**
+ * The Kepler {@link CarouselScrollable} definition.
+ *
+ * This implementation of the list uses a Native Turbo Module to control user
+ * interaction, animations, and native frame recycling.
+ *
+ * This native layer only has information about indexes; therefore, when it
+ * initially renders, it will have the knowledge about its rendered items and
+ * nothing more.
+ *
+ * As the user interacts with the component, the native layer will send messages
+ * to the JS components, and expect updates from it about any change occurring
+ * on the data backing the scrollable list.
+ *
+ * Check the documentation of {@link CarouselScrollableRef} for details about the
+ * information that the user can send to the native side.
+ *
+ * If you're required to have an encapsulated object to handle the data side of
+ * your application, check the {@link CarouselDataAdapter} documentation for a
+ * contract you can implement and use with this component.
+ *
+ * To avoid problems when using the list component, you need to understand its
+ * relation with your data.
+ *
+ * At no point, the scrollable will have any information about the _things_ your
+ * application is displaying in it, and it will never try to infer any change on
+ * your data.
+ *
+ * The user of this component is the sole owner of the data backing it, and as
+ * such, is responsible for any data change on the data set, together with the
+ * notification to the list informing it about them.
+ *
+ * With this concept, one can implement a variety of composable components
+ * taking full advantage of the scrollable list one.
+ *
+ * @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_,
+ *           or _stable IDs_) in the list;
+ *
+ * @param {CarouselScrollableProps<ItemT, KeyT>} props All of the configuration
+ *        attributes one can change in the scrollable list.
+ * @param {React.Ref<CarouselScrollableRef>} ref An optional {@link React.Ref} object
+ *        that allows one to access the imperative functions from the
+ *        {@link CarouselScrollableRef.}
+ *
+ * @see {@link CarouselScrollableProps}
+ * @see {@link CarouselScrollableRef}
+ * @see {@link CarouselDataAdapter}
+ */
+export declare const CarouselNativeWrapper: <ItemT, KeyT = React.Key>(props: CarouselScrollableProps<ItemT, KeyT> & {
+    ref?: React.Ref<CarouselScrollableRef> | undefined;
+}) => React.JSX.Element;
+export {};