@amazon-devices/vega-carousel 0.1.3

package/dist/CarouselData/CarouselDataTypes.d.ts

@@ -0,0 +1,280 @@
+import React from 'react';
+import { ScaleFactor } from '../CarouselScrollable/CarouselScrollableTypes';
+/**
+ * Function that can retrieve an item on an arbitrary position (`index`) from
+ * the given `data`.
+ *
+ * @template ItemT The type of object returned by this function.
+ *
+ * @param {number} index The positional index where the returned item is
+ *        located.
+ *
+ * @return {ItemT | undefined} Returns the item located on the given position,
+ *         or `undefined`, if there are no items on the given `index`.
+ */
+export type GetItemFunc<ItemT> = (index: number) => ItemT | undefined;
+export type GetItemCountFunc = () => number;
+/**
+ * Function that can retrieve a shift value to be used for neighboring items
+ * when the given item gets focused.
+ *
+ * @template ItemT The type for the object that will have its identifier
+ *           retrieved.
+ *
+ * @param {ItemT} item The item object that will have its unique identifier
+ *        extracted.
+ * @param {number} index The index position of the given item.
+ *
+ * @return {number | undefined} Returns the shift value. If undefined is
+ *         returned, the scrollable will use the default value passed into
+ *         the scrollable component.
+ */
+export type GetSelectedItemOffsetFunc<ItemT> = (item: ItemT, index: number) => ScaleFactor | undefined;
+/**
+ * Function that can retrieve a unique (sometimes also called _stable_)
+ * identifier from a given `item`.
+ *
+ * @template ItemT The type for the object that will have its identifier
+ *           retrieved.
+ * @template KeyT The type used for the returned identifier. By default, this
+ *           function uses {@link React.Key} as the identifier's type.
+ *
+ * @param {ItemT} item The item object that will have its unique identifier
+ *        extracted.
+ * @param {number} index The index position of the given item.
+ *
+ * @return {KeyT | undefined} Returns the unique identifier for the given
+ *         {@link item}. If the function cannot extract a unique identifier for
+ *         the object, `undefined` should be returned.
+ */
+export type GetItemKeyFunc<ItemT, KeyT = React.Key> = (item: ItemT, index: number) => KeyT | undefined;
+/**
+ * Function that can resolve the given `item` into a {@link React.ReactElement}.
+ *
+ * @template ItemT The type of the data object that will be used in the
+ *           resolver.
+ *
+ * @param {ItemT} item The data item object used to create a resolved
+ *        [React element]{@link React.ReactElement}.
+ * @param {number} index The data index position of the given item.
+ *
+ * @return {React.ReactElement | undefined} Returns the resolved item as a
+ *         [React element]{@link React.ReactElement}, or `undefined` if it could
+ *         not resolve it for any reason.
+ */
+export type RenderItemFunc<ItemT> = (item: ItemT, index: number) => React.ReactElement | undefined;
+/**
+ * This enumerator is a representation of the directions a _batch read_ of
+ * elements can follow.
+ *
+ * When retrieving data from the data adaptor, the component will always request
+ * a single item at the selected position, and a series of items from the sides
+ * of the selected one.
+ *
+ * For more details on how this enum is used, check the
+ * {@link resolveDataItems} function documentation.
+ *
+ * @see resolveDataItems
+ */
+export declare enum CarouselDataReadDirection {
+    /**
+     * When reading from the target position, the component won't try to get next
+     * nor previous items.
+     */
+    AT_TARGET = 0,
+    /**
+     * When reading items backwards, after the first successful retrieval, further
+     * requests will always try to get an item from a smaller position then the
+     * previous retrieved one.
+     */
+    BACKWARDS = 1,
+    /**
+     * When reading items forward, after the first successful retrieval, further
+     * requests will always try to get an item from a higher position then the
+     * previous retrieved one.
+     */
+    FORWARD = 2
+}
+/**
+ * This type defines how the {@link resolveDataItems} will behave when trying to
+ * retrieve items.
+ *
+ * For details on the resolving process, check the {@link resolveDataItems}
+ * documentation.
+ *
+ * @see {@link resolveDataItems}
+ */
+export type CarouselDataReadConfig = {
+    /**
+     * The position where to start the reading process. Depending on the type of
+     * read executed, this might not be the last index read.
+     *
+     * @see {@link readDirection}
+     */
+    startIndex: number;
+    /**
+     * Indicates if the reading should move forward, backwards, or stay at the
+     * given {@link startIndex} position.
+     *
+     * @see {@link startIndex}
+     */
+    readDirection: CarouselDataReadDirection;
+    /**
+     * This function is a predicate called in a loop by the
+     * {@link resolveDataItems} function to know if it should stop requesting
+     * items.
+     *
+     * @param {number} lastIndexRead This function is called at the start of every
+     *        data retrieval loop, to this index represents what is its value at
+     *        the start of the process, and at every time a new loop starts.
+     *
+     * @return {boolean} This callback should return `true` if the caller wants
+     *         the retrieval API to keep requesting items, and `false` otherwise.
+     *
+     * @see {@link resolveDataItems}
+     */
+    shouldReadNext?: (lastIndexRead: number) => boolean;
+    /**
+     * The number of times the resolver can try to retrieve or resolve an item
+     * before it considers the operation a failure.
+     *
+     * @default ITEM_FAILURE_DEFAULT_MAX_RETRIES
+     */
+    maxRetries: number;
+};
+/**
+ * This enumerator represents all types of errors that can happen when handling
+ * a data item (reading it or resolving it).
+ */
+export declare enum CarouselDataErrorReason {
+    /**
+     * The data item could not be read. In practice, this means the adapter
+     * returned `null` or `undefined` when `getItem` was called.
+     */
+    CANNOT_READ = 0,
+    /**
+     * The data item could not be resolved into a {@link React.ReactElement}. This
+     * also means the adapter will have to prune the item from its data set
+     * because even though the item exists and is valid, we cannot use it in our
+     * carousels.
+     */
+    CANNOT_RENDER = 1
+}
+/**
+ * This type encapsulates all the available information available about a data
+ * error. You have the `readConfig` used while reading the item at position
+ * `index`, and if the error is a _read_ or _resolve_ problem.
+ */
+export type CarouselDataError = {
+    /**
+     * The data index of the item that caused the error being reported.
+     */
+    index: number;
+    /**
+     * The read configuration used by the {@link resolveDataItems} function when
+     * the error being reported happened.
+     */
+    readConfig: CarouselDataReadConfig;
+    /**
+     * Enumerator value indicating if this error is a _read_ or a _resolve_
+     * problem.
+     */
+    reason: CarouselDataErrorReason;
+};
+/**
+ * Type representing the function called by the list component when it
+ * encounters an error while retrieving and rendering an item.
+ *
+ * For details about this function's usage, check the {@link resolveDataItems}
+ * documentation.
+ *
+ * @param {number} index The data index of the item that caused the error.
+ * @param {CarouselDataReadDirection} readTarget The retrieve target used by
+ *        the {@link resolveDataItems} function when the error happened.
+ *
+ * @return {boolean} Returns `true` if the data adapter wants the component to
+ *         perform a retry, or `false` if this is unrecoverable.
+ *
+ * @function
+ * @see {@link resolveDataItems}
+ */
+export type CarouselDataErrorNotifyFunc = (error: CarouselDataError) => boolean;
+/**
+ * When the data backing the {@link CarouselScrollable} component changes, there are only
+ * three possible operations that happened.
+ *
+ * This enum represents the type of operations allowed in the {@link CarouselScrollable}.
+ *
+ * @see {@link CarouselScrollable}
+ * @see {@link CarouselDataChange}
+ */
+export declare enum CarouselDataChangeType {
+    /**
+     * Indicates that an item was added to the data set. The item insertion could
+     * have happened in the data edge (`prepend` or `append`) or in the middle.
+     */
+    ADD = 1,
+    /** Indicates an item was removed from the data set. */
+    REMOVE = 2,
+    /**
+     * Indicates that the item's **content** changed, and although the item itself
+     * did not change, it might render different information then before.
+     */
+    UPDATE = 3
+}
+/**
+ * When an external entity needs to report that the data backing a
+ * {@link CarouselScrollable} changed, it must send a list of operations representing all
+ * the modifications done in the data.
+ *
+ * This type represents a single operation in this list.
+ *
+ * Notice, though, that this type does not carry any _data_ information like
+ * other data adapter implementations.
+ *
+ * Since our component core is designed to not handle with data (it does not
+ * care what is being rendered on its internal frames), we don't need to carry
+ * any information within a data change operation.
+ *
+ * @see {@link CarouselScrollable}
+ * @see {@link CarouselDataChangeType}
+ */
+export type CarouselDataChange = {
+    /**
+     * Indicates what type of operation was performed in the data set (check the
+     * {@link CarouselDataChangeType} documentation for details).
+     *
+     * @see {@link CarouselDataChangeType}
+     */
+    type: CarouselDataChangeType;
+    /**
+     * Indicates the position where this operation happened.
+     *
+     * It's important to know that any data operation follows a standard array
+     * order, meaning: If the operation is an {@link ADD}, the item currently
+     * present in this position index will be moved to the right so the new item
+     * is added there;
+     */
+    position: number;
+    /**
+     * Indicates how many **sequential** items were affected by this operation.
+     */
+    count: number;
+};
+/**
+ * This type represents a function that will be called by the implementation of
+ * a data adapter when it notices that a change happened in its data set.
+ *
+ * @param {Array<CarouselDataChange>} changes The list of changes
+ *        that will represent the data change that already happened.
+ *
+ * @function
+ * @see {@link CarouselDataChange}
+ */
+export type CarouselDataChangeCallback = (changes: Array<CarouselDataChange>) => void;
+export type CarouselResolvedDataValues<KeyT = React.Key> = {
+    index: number;
+    element: React.ReactElement;
+    key?: KeyT;
+    shift?: ScaleFactor;
+};

package/dist/CarouselData/CarouselDataTypes.js

@@ -0,0 +1,84 @@
+"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.CarouselDataChangeType = exports.CarouselDataErrorReason = exports.CarouselDataReadDirection = void 0;
+/**
+ * This enumerator is a representation of the directions a _batch read_ of
+ * elements can follow.
+ *
+ * When retrieving data from the data adaptor, the component will always request
+ * a single item at the selected position, and a series of items from the sides
+ * of the selected one.
+ *
+ * For more details on how this enum is used, check the
+ * {@link resolveDataItems} function documentation.
+ *
+ * @see resolveDataItems
+ */
+var CarouselDataReadDirection;
+(function (CarouselDataReadDirection) {
+    /**
+     * When reading from the target position, the component won't try to get next
+     * nor previous items.
+     */
+    CarouselDataReadDirection[CarouselDataReadDirection["AT_TARGET"] = 0] = "AT_TARGET";
+    /**
+     * When reading items backwards, after the first successful retrieval, further
+     * requests will always try to get an item from a smaller position then the
+     * previous retrieved one.
+     */
+    CarouselDataReadDirection[CarouselDataReadDirection["BACKWARDS"] = 1] = "BACKWARDS";
+    /**
+     * When reading items forward, after the first successful retrieval, further
+     * requests will always try to get an item from a higher position then the
+     * previous retrieved one.
+     */
+    CarouselDataReadDirection[CarouselDataReadDirection["FORWARD"] = 2] = "FORWARD";
+})(CarouselDataReadDirection = exports.CarouselDataReadDirection || (exports.CarouselDataReadDirection = {}));
+/**
+ * This enumerator represents all types of errors that can happen when handling
+ * a data item (reading it or resolving it).
+ */
+var CarouselDataErrorReason;
+(function (CarouselDataErrorReason) {
+    /**
+     * The data item could not be read. In practice, this means the adapter
+     * returned `null` or `undefined` when `getItem` was called.
+     */
+    CarouselDataErrorReason[CarouselDataErrorReason["CANNOT_READ"] = 0] = "CANNOT_READ";
+    /**
+     * The data item could not be resolved into a {@link React.ReactElement}. This
+     * also means the adapter will have to prune the item from its data set
+     * because even though the item exists and is valid, we cannot use it in our
+     * carousels.
+     */
+    CarouselDataErrorReason[CarouselDataErrorReason["CANNOT_RENDER"] = 1] = "CANNOT_RENDER";
+})(CarouselDataErrorReason = exports.CarouselDataErrorReason || (exports.CarouselDataErrorReason = {}));
+/**
+ * When the data backing the {@link CarouselScrollable} component changes, there are only
+ * three possible operations that happened.
+ *
+ * This enum represents the type of operations allowed in the {@link CarouselScrollable}.
+ *
+ * @see {@link CarouselScrollable}
+ * @see {@link CarouselDataChange}
+ */
+var CarouselDataChangeType;
+(function (CarouselDataChangeType) {
+    /**
+     * Indicates that an item was added to the data set. The item insertion could
+     * have happened in the data edge (`prepend` or `append`) or in the middle.
+     */
+    CarouselDataChangeType[CarouselDataChangeType["ADD"] = 1] = "ADD";
+    /** Indicates an item was removed from the data set. */
+    CarouselDataChangeType[CarouselDataChangeType["REMOVE"] = 2] = "REMOVE";
+    /**
+     * Indicates that the item's **content** changed, and although the item itself
+     * did not change, it might render different information then before.
+     */
+    CarouselDataChangeType[CarouselDataChangeType["UPDATE"] = 3] = "UPDATE";
+})(CarouselDataChangeType = exports.CarouselDataChangeType || (exports.CarouselDataChangeType = {}));

package/dist/CarouselData/index.d.ts

@@ -0,0 +1,3 @@
+export * from './CarouselDataAdapter';
+export * from './CarouselDataResolver';
+export * from './CarouselDataTypes';

package/dist/CarouselData/index.js

@@ -0,0 +1,24 @@
+"use strict";
+/*
+ * Copyright (c) 2024 - 2025 Amazon.com, Inc. or its affiliates. All rights reserved.
+ *
+ * PROPRIETARY/CONFIDENTIAL. USE IS SUBJECT TO LICENSE TERMS.
+ */
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+__exportStar(require("./CarouselDataAdapter"), exports);
+__exportStar(require("./CarouselDataResolver"), exports);
+__exportStar(require("./CarouselDataTypes"), exports);

package/dist/CarouselScrollable/CarouselScrollable.d.ts

@@ -0,0 +1,67 @@
+/// <reference types="react" />
+/**
+ * `CarouselScrollable` is a recyclable list component that offers granular control over
+ * how its data is retrieved and rendered.
+ *
+ * It uses a minimal functional style to define how to access the data backing
+ * the list, with `4` required fields on its properties.
+ *
+ * Optionally, if you prefer to use a more object-oriented API, you can pass an
+ * object implementing the {@link CarouselDataAdapter} contract and a single
+ * function called when the list needs to render an item, making the number of
+ * required fields to be `2`.
+ *
+ * Check the {@link CarouselScrollableProps} documentation for details on the properties
+ * used by this component, and the {@link CarouselDataAdapter} for the data access
+ * documentation.
+ *
+ * @example
+ * The following is an example of a minimal `CarouselScrollable` component using the
+ * functional style API:
+ * ```tsx
+ * function MyComponent(dataAdapter: CarouselDataAdapter) {
+ *   const renderItem = React.useCallback(
+ *     (item: MyDataItem) => <View>{item.render()}</View>
+ *     []
+ *   )
+ *   return (
+ *     <CarouselScrollable
+ *       getItem={dataAdapter.getItem}
+ *       getItemKey={dataAdapter.getItemKey}
+ *       notifyDataFailure={dataAdapter.notifyDataFailure}
+ *       renderItem={renderItem} />
+ *   )
+ * }
+ * ```
+ *
+ * @example
+ * If, like the sample above, have an object that can implement the Data Adapter
+ * API, then you can have an even simpler usage:
+ * ```tsx
+ * function MyComponent(dataAdapter: CarouselDataAdapter) {
+ *   const renderItem = React.useCallback(
+ *     (item: MyDataItem) => <View>{item.render()}</View>
+ *     []
+ *   )
+ *   return (
+ *     <CarouselScrollable dataAdapter={dataAdapter} renderItem={renderItem} />
+ *   )
+ * }
+ * ```
+ *
+ * If you can guarantee that your data will be a standard `Array`, you should
+ * use the {@link CarouselSimple} component, which is a wrapper around this
+ * list with defaults targeted for data as an {@link Array} of items.
+ *
+ * Internally, we have different implementations of the `CarouselScrollable` component.
+ * One of these implementations will be selected to **be** the `CarouselScrollable` type
+ * during runtime. For internal details on these implementations, check their
+ * documentation.
+ *
+ * @see {@link CarouselScrollableProps}
+ * @see {@link CarouselDataAdapter}
+ * @see {@link CarouselSimple}
+ */
+export declare const CarouselScrollable: <ItemT, KeyT = import("react").Key>(props: import("./CarouselScrollableProps").CarouselScrollableProps<ItemT, KeyT> & {
+    ref?: import("react").Ref<import("./CarouselScrollableRef").CarouselScrollableRef> | undefined;
+}) => import("react").JSX.Element;

package/dist/CarouselScrollable/CarouselScrollable.js

@@ -0,0 +1,77 @@
+"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.CarouselScrollable = void 0;
+const react_native_1 = require("react-native");
+const JSRecyclerViewList_1 = require("./recyclerview/JSRecyclerViewList");
+const native_1 = require("./native");
+/**
+ * `CarouselScrollable` is a recyclable list component that offers granular control over
+ * how its data is retrieved and rendered.
+ *
+ * It uses a minimal functional style to define how to access the data backing
+ * the list, with `4` required fields on its properties.
+ *
+ * Optionally, if you prefer to use a more object-oriented API, you can pass an
+ * object implementing the {@link CarouselDataAdapter} contract and a single
+ * function called when the list needs to render an item, making the number of
+ * required fields to be `2`.
+ *
+ * Check the {@link CarouselScrollableProps} documentation for details on the properties
+ * used by this component, and the {@link CarouselDataAdapter} for the data access
+ * documentation.
+ *
+ * @example
+ * The following is an example of a minimal `CarouselScrollable` component using the
+ * functional style API:
+ * ```tsx
+ * function MyComponent(dataAdapter: CarouselDataAdapter) {
+ *   const renderItem = React.useCallback(
+ *     (item: MyDataItem) => <View>{item.render()}</View>
+ *     []
+ *   )
+ *   return (
+ *     <CarouselScrollable
+ *       getItem={dataAdapter.getItem}
+ *       getItemKey={dataAdapter.getItemKey}
+ *       notifyDataFailure={dataAdapter.notifyDataFailure}
+ *       renderItem={renderItem} />
+ *   )
+ * }
+ * ```
+ *
+ * @example
+ * If, like the sample above, have an object that can implement the Data Adapter
+ * API, then you can have an even simpler usage:
+ * ```tsx
+ * function MyComponent(dataAdapter: CarouselDataAdapter) {
+ *   const renderItem = React.useCallback(
+ *     (item: MyDataItem) => <View>{item.render()}</View>
+ *     []
+ *   )
+ *   return (
+ *     <CarouselScrollable dataAdapter={dataAdapter} renderItem={renderItem} />
+ *   )
+ * }
+ * ```
+ *
+ * If you can guarantee that your data will be a standard `Array`, you should
+ * use the {@link CarouselSimple} component, which is a wrapper around this
+ * list with defaults targeted for data as an {@link Array} of items.
+ *
+ * Internally, we have different implementations of the `CarouselScrollable` component.
+ * One of these implementations will be selected to **be** the `CarouselScrollable` type
+ * during runtime. For internal details on these implementations, check their
+ * documentation.
+ *
+ * @see {@link CarouselScrollableProps}
+ * @see {@link CarouselDataAdapter}
+ * @see {@link CarouselSimple}
+ */
+exports.CarouselScrollable = react_native_1.Platform.OS === 'android' && react_native_1.Platform.isTV
+    ? /* istanbul ignore next */ JSRecyclerViewList_1.JSRecyclerViewList
+    : native_1.CarouselNativeWrapper;