@amazon-devices/vega-carousel 0.1.3

package/dist/CarouselData/CarouselDataAdapter.d.ts

@@ -0,0 +1,141 @@
+import React from 'react';
+import { CarouselDataErrorNotifyFunc, GetItemFunc, GetItemKeyFunc, CarouselDataChangeCallback, GetItemCountFunc, GetSelectedItemOffsetFunc } from './CarouselDataTypes';
+import { ScaleFactor } from '../CarouselScrollable/CarouselScrollableTypes';
+/**
+ * This type represents the _outer properties_ for a {@link CarouselDataAdapter}
+ * object, meaning that the properties in this type are used to get data **out**
+ * of a {@link CarouselDataAdapter}.
+ *
+ * @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 CarouselDataAdapter}
+ */
+export type CarouselDataAdapterReader<ItemT, KeyT = React.Key> = {
+    /**
+     * A function that will receive an index, and return an item's data object.
+     *
+     * The object returned will be used to call other data-access functions to
+     * retrieve information about specific items.
+     *
+     * @function
+     * @see {@link GetItemFunc}
+     */
+    getItem: GetItemFunc<ItemT>;
+    getItemCount: GetItemCountFunc;
+    /**
+     * A function to retrieve a different shift value to be applied for an item.
+     *
+     * @function
+     * @see {@link GetSelectedItemOffsetFunc}
+     */
+    getSelectedItemOffset?: GetSelectedItemOffsetFunc<ItemT>;
+    /**
+     * A function to retrieve an item’s unchangeable identifier that is
+     * independent of the index position the item is currently located.
+     *
+     * @function
+     * @see {@link GetItemKeyFunc}
+     * @see {@link getItem}
+     */
+    getItemKey: GetItemKeyFunc<ItemT, KeyT>;
+    /**
+     * This function is called by the list component when an item cannot be used
+     * in the list.
+     *
+     * This happens when either {@link getItem} or {@link renderItem} functions
+     * return an `undefined` value.
+     *
+     * @function
+     * @see {@link CarouselDataErrorNotifyFunc}
+     * @see {@link getItem}
+     * @see {@link renderItem}
+     */
+    notifyDataError: CarouselDataErrorNotifyFunc;
+};
+/**
+ * A type representing a Data Adapter for the {@link CarouselScrollable} component.
+ *
+ * Because the {@link CarouselScrollable} component is a hybrid between Native and React
+ * Native code, it was designed to not pass data representing items to the
+ * Native layer.
+ *
+ * This simplified the design but created a necessity for the Native component
+ * to be an _index-based_ list.
+ *
+ * Due to the dynamic nature of the data where this component will be used, it
+ * was necessary to create a _translation layer_ between the real data set, and
+ * the sequential data the {@link CarouselScrollable} requires.
+ *
+ * The `CarouselDataAdapter` is the contract for this _translation layer_.
+ *
+ * @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 CarouselDataAdapterReader}
+ * @see {@link resolveDataItems}
+ */
+export type CarouselDataAdapter<ItemT, KeyT = React.Key> = CarouselDataAdapterReader<ItemT, KeyT> & {
+    /**
+     * Optional function that, when given, will be called by the {@link CarouselScrollable}
+     * component to register an internal function that will call the
+     * {@link CarouselScrollableRef.notifyDataChange} imperative function on behalf of the
+     * adapter.
+     *
+     * This is useful when you want to provide an implementation of
+     * `CarouselDataAdapter` that does not force the user of the object to call the
+     * list's imperative function whenever a data change happens; doing so will,
+     * essentially, create an adapter that can update a {@link CarouselScrollable}
+     * component without user intervention.
+     *
+     * @param {CarouselDataChangeCallback} callback A function to be called by the
+     *        data adapter implementation whenever there is a change happening in
+     *        the data provided to the {@link CarouselScrollable}.
+     *
+     * @function
+     * @see {@link CarouselDataChangeCallback}
+     */
+    registerDataChangeCallback?: (callback: CarouselDataChangeCallback) => void;
+};
+/**
+ * Convenience function that encapsulates the retrieval of an item's stable
+ * identifier (its _key_) from a {@link CarouselDataAdapter}.
+ *
+ * Note that this function will not distinguish from an item that can't be
+ * retrieved and an item with a key that can't be retrieved.
+ *
+ * @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 {CarouselDataAdapterReader<ItemT, KeyT>} adapter The adapter object to be
+ *        used to read the item and its key.
+ * @param {number} index The data index for the item you want to retrieve the
+ *        stable identifier from.
+ *
+ * @return {KeyT | undefined} Returns the item's key if it is found; otherwise
+ *         `undefined`.
+ */
+export declare function getItemKey<ItemT, KeyT = React.Key>(adapter: CarouselDataAdapterReader<ItemT, KeyT>, index: number): KeyT | undefined;
+/**
+ * Convenience function that encapsulates the retrieval of an item's shift
+ * from a {@link CarouselDataAdapter}.
+ *
+ * Note that this function will not distinguish from an item that can't be
+ * retrieved and an item with a shift that can't be retrieved.
+ *
+ * @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 {CarouselDataAdapterReader<ItemT, KeyT>} adapter The adapter object to be
+ *        used to read the item and its key.
+ * @param {number} index The data index for the item you want to retrieve the
+ *        stable identifier from.
+ *
+ * @return {number | undefined} Returns the item's shift if it is found; otherwise
+ *         `undefined`.
+ */
+export declare function getSelectedItemOffset<ItemT, KeyT = React.Key>(adapter: CarouselDataAdapterReader<ItemT, KeyT>, index: number): ScaleFactor | undefined;

package/dist/CarouselData/CarouselDataAdapter.js

@@ -0,0 +1,67 @@
+"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.getSelectedItemOffset = exports.getItemKey = void 0;
+const utils_1 = require("../utils");
+/**
+ * Convenience function that encapsulates the retrieval of an item's stable
+ * identifier (its _key_) from a {@link CarouselDataAdapter}.
+ *
+ * Note that this function will not distinguish from an item that can't be
+ * retrieved and an item with a key that can't be retrieved.
+ *
+ * @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 {CarouselDataAdapterReader<ItemT, KeyT>} adapter The adapter object to be
+ *        used to read the item and its key.
+ * @param {number} index The data index for the item you want to retrieve the
+ *        stable identifier from.
+ *
+ * @return {KeyT | undefined} Returns the item's key if it is found; otherwise
+ *         `undefined`.
+ */
+function getItemKey(adapter, index) {
+    const item = adapter.getItem(index);
+    if (item !== undefined) {
+        return adapter.getItemKey(item, index);
+    }
+    else {
+        utils_1.Log.d('Trying to read the "key" of an item that does not exist in the given adapter: index={0}', index);
+    }
+}
+exports.getItemKey = getItemKey;
+/**
+ * Convenience function that encapsulates the retrieval of an item's shift
+ * from a {@link CarouselDataAdapter}.
+ *
+ * Note that this function will not distinguish from an item that can't be
+ * retrieved and an item with a shift that can't be retrieved.
+ *
+ * @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 {CarouselDataAdapterReader<ItemT, KeyT>} adapter The adapter object to be
+ *        used to read the item and its key.
+ * @param {number} index The data index for the item you want to retrieve the
+ *        stable identifier from.
+ *
+ * @return {number | undefined} Returns the item's shift if it is found; otherwise
+ *         `undefined`.
+ */
+function getSelectedItemOffset(adapter, index) {
+    const item = adapter.getItem(index);
+    if (item !== undefined) {
+        return adapter.getSelectedItemOffset?.(item, index);
+    }
+    else {
+        utils_1.Log.d('Trying to read the "shift" of an item that does not exist in the given adapter: index={0}', index);
+    }
+}
+exports.getSelectedItemOffset = getSelectedItemOffset;

package/dist/CarouselData/CarouselDataResolver.d.ts

@@ -0,0 +1,100 @@
+import { CarouselDataReadConfig, CarouselResolvedDataValues, RenderItemFunc } from './CarouselDataTypes';
+import React from 'react';
+import { CarouselDataAdapterReader } from './CarouselDataAdapter';
+/**
+ * Constant representing the default number of times the
+ * {@link resolveDataItems} function will call the
+ * {@link CarouselDataAdapterReader.getItem} function from the adapter before it
+ * considers the item failed to be retrieved.
+ *
+ * @see {@link resolveDataItems}
+ */
+export declare const ITEM_FAILURE_DEFAULT_MAX_RETRIES = 2;
+/**
+ * Helper function to create a {@link CarouselDataReadConfig} object that read a
+ * single item on the given `index`.
+ *
+ * @param {number} index The data position to try to read the item.
+ * @param {number} maxRetries Optional maximum number of retries that the
+ *        {@link resolveDataItems} function will attempt before failing.
+ *
+ * @return {CarouselDataReadConfig} Returns a read configuration object with the
+ *         specifications for a single item read.
+ */
+export declare function dataReadAtTargetConfig(index: number, maxRetries?: number): CarouselDataReadConfig;
+/**
+ * Helper function to create a {@link CarouselDataReadConfig} object that read a
+ * multiple items, starting from the given `startIndex`, going backwards, and
+ * stopping when the `shouldReadNext` predicate returns `false` (or an item
+ * failed to resolve `maxRetries` times).
+ *
+ * @param {number} startIndex The data position to try to read the item.
+ * @param {(lastIndexRead: number) => boolean} shouldReadNext A predicate that
+ *        informs the {@link resolveDataItems} function if it should read the
+ *        previous item or not.
+ * @param {number} maxRetries Optional maximum number of retries that the
+ *        {@link resolveDataItems} function will attempt before failing.
+ *
+ * @return {CarouselDataReadConfig} Returns a read configuration object with the
+ *         specifications for a multiple items backwards read call.
+ */
+export declare function dataReadBackwardsConfig(startIndex: number, shouldReadNext: (lastIndexRead: number) => boolean, maxRetries?: number): CarouselDataReadConfig;
+/**
+ * Helper function to create a {@link CarouselDataReadConfig} object that read a
+ * multiple items, starting from the given `startIndex`, going forward, and
+ * stopping when the `shouldReadNext` predicate returns `false` (or an item
+ * failed to resolve `maxRetries` times).
+ *
+ * @param {number} startIndex The data position to try to read the item.
+ * @param {(lastIndexRead: number) => boolean} shouldReadNext A predicate that
+ *        informs the {@link resolveDataItems} function if it should read the
+ *        next item or not.
+ * @param {number} maxRetries Optional maximum number of retries that the
+ *        {@link resolveDataItems} function will attempt before failing.
+ *
+ * @return {CarouselDataReadConfig} Returns a read configuration object with the
+ *         specifications for a multiple items forward read call.
+ */
+export declare function dataReadForwardConfig(startIndex: number, shouldReadNext: (lastIndexRead: number) => boolean, maxRetries?: number): CarouselDataReadConfig;
+/**
+ * Function used to retrieve and resolve items from an adapter with safeguards
+ * for failures, and retry logic.
+ *
+ * One can retrieve a single item or a series of them (reading backwards or
+ * forward) depending on the read configuration given in the `readConfig`
+ * parameter.
+ *
+ * When there is a problem retrieving or resolving an item, this function will
+ * call the {@link CarouselDataAdapterReader.notifyDataError} function to give an
+ * opportunity for the adapter to adjust its data, and be prepared for a retry.
+ *
+ * An important point on the _retry logic_ used here, is the concept that, if
+ * the function called {@link CarouselDataAdapterReader.notifyDataError}, it is
+ * communicating that there is no way for the failed item to be resolved and
+ * used from now on, and such an item should not be part of the data set.
+ *
+ * @template ItemT The type of the data object retrieved by the adapter and
+ *           resolved by the resolver.
+ * @template KeyT Optional type used as data items unique identifiers (also
+ *           called _stable IDs_, or _keys_); when not provided, defaults to
+ *           {@link React.Key}.
+ *
+ * @param {CarouselDataAdapterReader<ItemT, KeyT>} dataAdapter The data adapter
+ *        reader used to retrieve item objects to resolve.
+ * @param {RenderItemFunc<ItemT>} renderItem The resolver function. This
+ *        function is responsible for reading an item object and resolve it to a
+ *        {@link React.ReactElement} one.
+ * @param {CarouselDataReadConfig} readConfig The object containing the
+ *        configuration values that will drive the resolve call.
+ * @param {(item: React.ReactElement) => void} onItemResolved Callback called
+ *        when the `resolveDataItems` function finishes retrieving and resolving
+ *        an item from a Data Adapter.
+ *
+ * @return {number | undefined} Returns the last index fully resolved, or
+ *         `undefined` if the function could not resolve anything.
+ *
+ * @see {@link CarouselDataAdapterReader}
+ * @see {@link RenderItemFunc}
+ * @see {@link CarouselDataReadConfig}
+ */
+export declare function resolveDataItems<ItemT, KeyT = React.Key>(dataAdapter: CarouselDataAdapterReader<ItemT, KeyT>, renderItem: RenderItemFunc<ItemT>, readConfig: CarouselDataReadConfig, onItemResolved: (resolved: CarouselResolvedDataValues<KeyT>) => void): number | undefined;

package/dist/CarouselData/CarouselDataResolver.js

@@ -0,0 +1,224 @@
+"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.resolveDataItems = exports.dataReadForwardConfig = exports.dataReadBackwardsConfig = exports.dataReadAtTargetConfig = exports.ITEM_FAILURE_DEFAULT_MAX_RETRIES = void 0;
+const CarouselDataTypes_1 = require("./CarouselDataTypes");
+const utils_1 = require("../utils");
+/**
+ * Constant representing the default number of times the
+ * {@link resolveDataItems} function will call the
+ * {@link CarouselDataAdapterReader.getItem} function from the adapter before it
+ * considers the item failed to be retrieved.
+ *
+ * @see {@link resolveDataItems}
+ */
+exports.ITEM_FAILURE_DEFAULT_MAX_RETRIES = 2;
+/**
+ * Helper function to create a {@link CarouselDataReadConfig} object that read a
+ * single item on the given `index`.
+ *
+ * @param {number} index The data position to try to read the item.
+ * @param {number} maxRetries Optional maximum number of retries that the
+ *        {@link resolveDataItems} function will attempt before failing.
+ *
+ * @return {CarouselDataReadConfig} Returns a read configuration object with the
+ *         specifications for a single item read.
+ */
+function dataReadAtTargetConfig(index, maxRetries = exports.ITEM_FAILURE_DEFAULT_MAX_RETRIES) {
+    return {
+        startIndex: index,
+        readDirection: CarouselDataTypes_1.CarouselDataReadDirection.AT_TARGET,
+        maxRetries,
+    };
+}
+exports.dataReadAtTargetConfig = dataReadAtTargetConfig;
+/**
+ * Helper function to create a {@link CarouselDataReadConfig} object that read a
+ * multiple items, starting from the given `startIndex`, going backwards, and
+ * stopping when the `shouldReadNext` predicate returns `false` (or an item
+ * failed to resolve `maxRetries` times).
+ *
+ * @param {number} startIndex The data position to try to read the item.
+ * @param {(lastIndexRead: number) => boolean} shouldReadNext A predicate that
+ *        informs the {@link resolveDataItems} function if it should read the
+ *        previous item or not.
+ * @param {number} maxRetries Optional maximum number of retries that the
+ *        {@link resolveDataItems} function will attempt before failing.
+ *
+ * @return {CarouselDataReadConfig} Returns a read configuration object with the
+ *         specifications for a multiple items backwards read call.
+ */
+function dataReadBackwardsConfig(startIndex, shouldReadNext, maxRetries = exports.ITEM_FAILURE_DEFAULT_MAX_RETRIES) {
+    return {
+        startIndex,
+        readDirection: CarouselDataTypes_1.CarouselDataReadDirection.BACKWARDS,
+        shouldReadNext,
+        maxRetries,
+    };
+}
+exports.dataReadBackwardsConfig = dataReadBackwardsConfig;
+/**
+ * Helper function to create a {@link CarouselDataReadConfig} object that read a
+ * multiple items, starting from the given `startIndex`, going forward, and
+ * stopping when the `shouldReadNext` predicate returns `false` (or an item
+ * failed to resolve `maxRetries` times).
+ *
+ * @param {number} startIndex The data position to try to read the item.
+ * @param {(lastIndexRead: number) => boolean} shouldReadNext A predicate that
+ *        informs the {@link resolveDataItems} function if it should read the
+ *        next item or not.
+ * @param {number} maxRetries Optional maximum number of retries that the
+ *        {@link resolveDataItems} function will attempt before failing.
+ *
+ * @return {CarouselDataReadConfig} Returns a read configuration object with the
+ *         specifications for a multiple items forward read call.
+ */
+function dataReadForwardConfig(startIndex, shouldReadNext, maxRetries = exports.ITEM_FAILURE_DEFAULT_MAX_RETRIES) {
+    return {
+        startIndex,
+        readDirection: CarouselDataTypes_1.CarouselDataReadDirection.FORWARD,
+        shouldReadNext,
+        maxRetries,
+    };
+}
+exports.dataReadForwardConfig = dataReadForwardConfig;
+/**
+ * Helper function that performs the required tasks when an item resolve request
+ * fails.
+ *
+ * It will notify the adapter about the error, and check if the
+ * {@link resolveDataItems} should retry the request.
+ *
+ * @template ItemT The type of the data object retrieved by the adapter and
+ *           resolved by the resolver.
+ * @template KeyT Optional type used as data items unique identifiers (also
+ *           called _stable IDs_, or _keys_); when not provided, defaults to
+ *           {@link React.Key}.
+ *
+ * @param {CarouselDataAdapterReader<ItemT, KeyT>} dataAdapter The data adapter
+ *        reader used to retrieve the item that failed.
+ * @param {CarouselDataReadConfig} readConfig The object containing the
+ *        configuration values that drove the resolve call.
+ * @param {number} currentRetryCount The number of prior attempts the
+ *        {@link resolveDataItems} function tried to resolve the failed item.
+ * @param {number} index The data index of the item that failed to resolve.
+ * @param {CarouselDataErrorReason} errorType The reason for the failure that will
+ *        be passed to the adapter when we notify if about the error.
+ *
+ * @return {boolean} Returns `true` if the {@link resolveDataItems} function
+ *         should retry the request, and `false` otherwise.
+ *
+ * @see {@link resolveDataItems}
+ */
+function handleResolveError(dataAdapter, readConfig, currentRetryCount, index, errorType) {
+    const shouldRetry = dataAdapter.notifyDataError({
+        index,
+        readConfig,
+        reason: errorType,
+    });
+    if (shouldRetry && currentRetryCount < readConfig.maxRetries) {
+        utils_1.Log.d('Failed to retrieve the data item for the index {0} (retries: {1})... Will retry...', index, currentRetryCount);
+    }
+    else {
+        utils_1.Log.d('Failed to retrieve the data item for the index {0} (retries: {1})', index, currentRetryCount);
+    }
+    return shouldRetry;
+}
+/**
+ * Function used to retrieve and resolve items from an adapter with safeguards
+ * for failures, and retry logic.
+ *
+ * One can retrieve a single item or a series of them (reading backwards or
+ * forward) depending on the read configuration given in the `readConfig`
+ * parameter.
+ *
+ * When there is a problem retrieving or resolving an item, this function will
+ * call the {@link CarouselDataAdapterReader.notifyDataError} function to give an
+ * opportunity for the adapter to adjust its data, and be prepared for a retry.
+ *
+ * An important point on the _retry logic_ used here, is the concept that, if
+ * the function called {@link CarouselDataAdapterReader.notifyDataError}, it is
+ * communicating that there is no way for the failed item to be resolved and
+ * used from now on, and such an item should not be part of the data set.
+ *
+ * @template ItemT The type of the data object retrieved by the adapter and
+ *           resolved by the resolver.
+ * @template KeyT Optional type used as data items unique identifiers (also
+ *           called _stable IDs_, or _keys_); when not provided, defaults to
+ *           {@link React.Key}.
+ *
+ * @param {CarouselDataAdapterReader<ItemT, KeyT>} dataAdapter The data adapter
+ *        reader used to retrieve item objects to resolve.
+ * @param {RenderItemFunc<ItemT>} renderItem The resolver function. This
+ *        function is responsible for reading an item object and resolve it to a
+ *        {@link React.ReactElement} one.
+ * @param {CarouselDataReadConfig} readConfig The object containing the
+ *        configuration values that will drive the resolve call.
+ * @param {(item: React.ReactElement) => void} onItemResolved Callback called
+ *        when the `resolveDataItems` function finishes retrieving and resolving
+ *        an item from a Data Adapter.
+ *
+ * @return {number | undefined} Returns the last index fully resolved, or
+ *         `undefined` if the function could not resolve anything.
+ *
+ * @see {@link CarouselDataAdapterReader}
+ * @see {@link RenderItemFunc}
+ * @see {@link CarouselDataReadConfig}
+ */
+function resolveDataItems(dataAdapter, renderItem, readConfig, onItemResolved) {
+    const [stepValue, indexAdjustment] = (() => {
+        switch (readConfig.readDirection) {
+            case CarouselDataTypes_1.CarouselDataReadDirection.AT_TARGET:
+                return [0, 0];
+            case CarouselDataTypes_1.CarouselDataReadDirection.BACKWARDS:
+                return [-1, 1];
+            case CarouselDataTypes_1.CarouselDataReadDirection.FORWARD:
+                return [1, -1];
+        }
+    })();
+    let itemData;
+    let element;
+    let index = readConfig.startIndex;
+    let retryCount = 0;
+    let retry = true;
+    while (retry &&
+        retryCount < readConfig.maxRetries &&
+        (readConfig.shouldReadNext?.(index) ?? true)) {
+        itemData = dataAdapter.getItem(index);
+        if (itemData !== undefined) {
+            element = renderItem(itemData, index);
+            if (element !== undefined) {
+                onItemResolved({
+                    index,
+                    element,
+                    key: dataAdapter.getItemKey(itemData, index),
+                    shift: dataAdapter.getSelectedItemOffset?.(itemData, index),
+                });
+                retryCount = 0; // reset the retry count when we resolve an item
+                index += stepValue;
+                if (readConfig.readDirection === CarouselDataTypes_1.CarouselDataReadDirection.AT_TARGET) {
+                    // If this is a targeted read, we know we won't request more items on
+                    // this call, so we can short-circuit this loop and leave earlier.
+                    // This will also help not to get stuck on an infinite loop when the
+                    // user forgets to add the correct _stop check_ to the
+                    // `canRequestMoreData` function.
+                    break;
+                }
+            }
+            else {
+                retry = handleResolveError(dataAdapter, readConfig, ++retryCount, index, CarouselDataTypes_1.CarouselDataErrorReason.CANNOT_RENDER);
+            }
+        }
+        else {
+            retry = handleResolveError(dataAdapter, readConfig, ++retryCount, index, CarouselDataTypes_1.CarouselDataErrorReason.CANNOT_READ);
+        }
+    }
+    if (retryCount < readConfig.maxRetries && itemData !== undefined) {
+        return index + indexAdjustment;
+    }
+}
+exports.resolveDataItems = resolveDataItems;