@amazon-devices/vega-carousel 0.1.3

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

@@ -0,0 +1,255 @@
+import React from 'react';
+import { CarouselScrollableDataAdapterProps, CarouselScrollableResolverProps } from '../CarouselScrollableProps';
+import { ScaleFactor, SelectionBorderStyle, SelectionBorderStrategy } from '../CarouselScrollableTypes';
+import { ViewProps } from 'react-native';
+/**
+ * Internal properties used by the wrapper item object used as children of the
+ * {@link CarouselNativeWrapper} component.
+ *
+ * @see {@link CarouselNativeWrapper}
+ * @see {@link CarouselScrollableDataAdapterProps}
+ * @see {@link CarouselScrollableResolverProps}
+ */
+export type CarouselNativeItemProps<ItemT, KeyT = React.Key> = ViewProps & CarouselScrollableDataAdapterProps<ItemT, KeyT> & CarouselScrollableResolverProps<ItemT> & {
+    /**
+     * The parent's identifier ({@link CarouselScrollableProps.uniqueId}) for the list
+     * containing the item.
+     *
+     * Different from the parent's {@link CarouselScrollableProps.uniqueId}, this property
+     * has functional value, as, together with the {@link dataIndex}, it is used
+     * to determine when this item is being recycled.
+     *
+     * @default undefined
+     * @see {@link CarouselScrollableProps}
+     * @see {@link dataIndex}
+     */
+    parentId?: string;
+    /**
+     * The data index associated with this item.
+     *
+     * This and the {@link parentId} are used to control when this item is being
+     * recycled.
+     *
+     * @default undefined
+     * @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.
+     *
+     * The look-and-feel of the selection border can be configured by the
+     * {@link selectionBorderStyle} property.
+     *
+     * @default false
+     * @see {@link selectionBorderStyle}
+     */
+    showSelectionBorder?: boolean;
+    /**
+     * This property defines the look-and-feel of the border surrounding the
+     * selected item when it is enabled.
+     */
+    selectionBorderStyle?: SelectionBorderStyle;
+    /**
+     * This property defines the strategy used for rendering the selection border
+     * relative to the content area.
+     */
+    selectionBorderStrategy?: SelectionBorderStrategy;
+    /**
+     * The scale factor for an item being activated by the user (e.g., the user
+     * pressed down the select button in the device's remote control).
+     *
+     * @default 1.0
+     * @see {@link CarouselScrollableConfigProps.pressedItemScaleFactor}
+     */
+    pressedItemScaleFactor: number;
+    /**
+     * The scale factor for selected items set on the parent's list.
+     *
+     * @default 1.0
+     * @see {@link CarouselScrollableConfigProps.focusedItemScaleFactor}
+     */
+    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.
+     *
+     * @param {number} index The `dataIndex` this item had before the binding.
+     */
+    unbindCallback: (index: number) => void;
+    /**
+     * This function is called whenever the item receives a message from the
+     * native layer telling it to rebind itself to another data item.
+     *
+     * @param {number} index The `dataIndex` this item will have **after** the
+     *        binding.
+     */
+    bindCallback: (index: number) => void;
+};
+/**
+ * Type representing a list item state. Changes on any of the fields in this
+ * type generate a re-render of the object.
+ */
+export type CarouselNativeItemState = {
+    /**
+     * The data index associated with this item. For details, check the
+     * documentation of {@link CarouselNativeItemProps.dataIndex}.
+     *
+     * @see {@link CarouselNativeItemProps.dataIndex}
+     */
+    dataIndex: number;
+    /**
+     * The parent's identifier ({@link CarouselScrollableProps.uniqueId}) for the list
+     * containing the item. For details, check the documentation of
+     * {@link CarouselNativeItemProps.parentId}.
+     *
+     * @see {@link CarouselNativeItemProps.parentId}
+     */
+    parentId?: string;
+    /**
+     * This field is used by the "force-refresh" mechanism. It flips its value any
+     * time one needs to cause a re-render of this component.
+     */
+    refreshToggle: boolean;
+    /**
+     * This field is used for specifying per-item shift value.
+     */
+    itemShift?: ScaleFactor;
+};
+/**
+ * Class component used to hoist a list item from {@link CarouselScrollable}.
+ *
+ * Although functional components are generally more performant than class ones,
+ * a functional component will always re-render when the parent re-renders, and
+ * for a recyclable list use-case, we need more control over _when_ that will
+ * happen.
+ *
+ * The `CarouselNativeItem` component will also be the entry point of a re-bind
+ * operation.
+ *
+ * @template ItemT The type of data item this component will use to resolve its
+ *           child component.
+ * @template KeyT The type used as items unique identifiers (also called _keys_,
+ *           or _stable IDs_) when verifying if this component should update;
+ *
+ * @see {@link CarouselNativeWrapper}
+ * @see {@link CarouselScrollable}
+ */
+export declare class CarouselNativeItemWrapper<ItemT, KeyT = React.Key> extends React.Component<CarouselNativeItemProps<ItemT, KeyT>, CarouselNativeItemState> {
+    private currentKey;
+    private useInitialElement;
+    constructor(props: CarouselNativeItemProps<ItemT, KeyT>);
+    /**
+     * Function called by the framework right before calling {@link render}, both
+     * on the initial mount, and on the following updates.
+     *
+     * The framework will use the returned state to check if the component's state
+     * changed, and to pass it to {@link shouldComponentUpdate}.
+     *
+     * When this function returns a new state the framework will re-render this
+     * component, even if {@link shouldComponentUpdate} returns `false`.
+     *
+     * @param {CarouselNativeItemProps<ItemT, KeyT>} props The next props that
+     *        the component is about to render with.
+     * @param {CarouselNativeItemState} state The next state that the component
+     *        is about to render with.
+     *
+     * @return {CarouselNativeItemState | null} Returns an object to update the
+     *         component's state, or `null` to update nothing.
+     *
+     * @see [Official API documentation](https://react.dev/reference/react/Component#static-getderivedstatefromprops)
+     */
+    static getDerivedStateFromProps<ItemT, KeyT>(props: CarouselNativeItemProps<ItemT, KeyT>, state: CarouselNativeItemState): CarouselNativeItemState | null;
+    /**
+     * Component should re-resolve if:
+     *
+     *   1. The `dataIndex` is different (component is changing frames);
+     *   2. The `refreshToggle` changed (it's a force refresh);
+     *   3. The item's key is different (component is changed within the same
+     *      frame at the same location)
+     *
+     * When the third update state can be performance costly since it retrieves
+     * the data item and its key from the already rendered item, plus the one to
+     * be updated, even though, when we have an update, the new data item will be
+     * re-resolved.
+     *
+     * @param {Readonly<CarouselNativeItemProps<ItemT, KeyT>>} nextProps The
+     *        updated properties for the list item.
+     * @param {Readonly<CarouselNativeItemState>} nextState The next state
+     *        calculated by the {@link getDerivedStateFromProps} function.
+     *
+     * @return {boolean} Returns `true` if the component should update, and
+     *         `false` otherwise.
+     *
+     * @see [Official API documentation](https://react.dev/reference/react/Component#shouldcomponentupdate)
+     */
+    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.
+     *
+     * @see [Official API documentation](https://react.dev/reference/react/Component#render)
+     */
+    render(): React.ReactNode;
+    /**
+     * Callback called by the native layer whenever it emits the `bind` event.
+     *
+     * This function will only perform any operation if the target bind index is
+     * different from the one it already has defined.
+     *
+     * @param {CarouselNativeItemHostComponentBindEvent} nativeEvent The event
+     *        emitted by the native layer.
+     *
+     * @see {@link CarouselNativeItemHostComponentBindEvent}
+     */
+    private onBind;
+    /**
+     * Data pooling function. This function will use the {@link resolveDataItems}
+     * function to retrieve and resolve an item at the component's data index
+     * position.
+     *
+     * @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.
+     *
+     * @see {@link CarouselNativeItemState}
+     * @see {@link resolveDataItems}
+     */
+    private resolveUpdatedItemContent;
+    /**
+     * Convenience method to render a native component with the
+     * {@link itemElement} as its child component.
+     */
+    private renderStateItem;
+    /**
+     * This property is used to cache the resolved element of this item.
+     *
+     * @private
+     */
+    private itemElement;
+}

package/dist/CarouselScrollable/native/CarouselNativeItemWrapper.js

@@ -0,0 +1,276 @@
+"use strict";
+/*
+ * Copyright (c) 2024 - 2025 Amazon.com, Inc. or its affiliates. All rights reserved.
+ *
+ * PROPRIETARY/CONFIDENTIAL. USE IS SUBJECT TO LICENSE TERMS.
+ */
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.CarouselNativeItemWrapper = void 0;
+const react_1 = __importDefault(require("react"));
+const CarouselNativeItemHostComponent_1 = require("./CarouselNativeItemHostComponent");
+const CarouselData_1 = require("../../CarouselData");
+const CarouselScrollableTypes_1 = require("../CarouselScrollableTypes");
+const utils_1 = require("../../utils");
+const react_native_1 = require("react-native");
+const defaultBorderStyle = {
+    borderColor: '#ffffff',
+    borderWidth: 8,
+    borderRadius: 8,
+    borderStrokeColor: '#000000',
+    borderStrokeWidth: 3,
+    borderStrokeRadius: 4,
+};
+/**
+ * Class component used to hoist a list item from {@link CarouselScrollable}.
+ *
+ * Although functional components are generally more performant than class ones,
+ * a functional component will always re-render when the parent re-renders, and
+ * for a recyclable list use-case, we need more control over _when_ that will
+ * happen.
+ *
+ * The `CarouselNativeItem` component will also be the entry point of a re-bind
+ * operation.
+ *
+ * @template ItemT The type of data item this component will use to resolve its
+ *           child component.
+ * @template KeyT The type used as items unique identifiers (also called _keys_,
+ *           or _stable IDs_) when verifying if this component should update;
+ *
+ * @see {@link CarouselNativeWrapper}
+ * @see {@link CarouselScrollable}
+ */
+class CarouselNativeItemWrapper extends react_1.default.Component {
+    currentKey;
+    useInitialElement;
+    constructor(props) {
+        super(props);
+        this.state = {
+            dataIndex: this.props.dataIndex ?? -1,
+            parentId: this.props.parentId,
+            refreshToggle: false,
+            itemShift: this.props.itemShift,
+        };
+        this.currentKey = this.props.initialKey;
+        this.useInitialElement = true;
+    }
+    ////////////////////////////////////////
+    /// Lifecycle methods
+    /**
+     * Function called by the framework right before calling {@link render}, both
+     * on the initial mount, and on the following updates.
+     *
+     * The framework will use the returned state to check if the component's state
+     * changed, and to pass it to {@link shouldComponentUpdate}.
+     *
+     * When this function returns a new state the framework will re-render this
+     * component, even if {@link shouldComponentUpdate} returns `false`.
+     *
+     * @param {CarouselNativeItemProps<ItemT, KeyT>} props The next props that
+     *        the component is about to render with.
+     * @param {CarouselNativeItemState} state The next state that the component
+     *        is about to render with.
+     *
+     * @return {CarouselNativeItemState | null} Returns an object to update the
+     *         component's state, or `null` to update nothing.
+     *
+     * @see [Official API documentation](https://react.dev/reference/react/Component#static-getderivedstatefromprops)
+     */
+    static getDerivedStateFromProps(props, state) {
+        if (props.parentId !== state.parentId) {
+            return {
+                dataIndex: props.dataIndex ?? -1,
+                parentId: props.parentId,
+                refreshToggle: state.refreshToggle,
+            };
+        }
+        return null;
+    }
+    /**
+     * Component should re-resolve if:
+     *
+     *   1. The `dataIndex` is different (component is changing frames);
+     *   2. The `refreshToggle` changed (it's a force refresh);
+     *   3. The item's key is different (component is changed within the same
+     *      frame at the same location)
+     *
+     * When the third update state can be performance costly since it retrieves
+     * the data item and its key from the already rendered item, plus the one to
+     * be updated, even though, when we have an update, the new data item will be
+     * re-resolved.
+     *
+     * @param {Readonly<CarouselNativeItemProps<ItemT, KeyT>>} nextProps The
+     *        updated properties for the list item.
+     * @param {Readonly<CarouselNativeItemState>} nextState The next state
+     *        calculated by the {@link getDerivedStateFromProps} function.
+     *
+     * @return {boolean} Returns `true` if the component should update, and
+     *         `false` otherwise.
+     *
+     * @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;
+        }
+        // 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 (!shouldUpdate &&
+            (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 shouldUpdate;
+    }
+    /**
+     * 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.
+     *
+     * @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 = react_1.default.createElement(react_1.default.Fragment, null);
+                    this.useInitialElement = false;
+                }
+            }
+            return this.renderStateItem();
+        }
+        finally {
+            this.useInitialElement = false;
+        }
+    }
+    ////////////////////////////////////////
+    /// Private callback functions
+    /**
+     * Callback called by the native layer whenever it emits the `bind` event.
+     *
+     * This function will only perform any operation if the target bind index is
+     * different from the one it already has defined.
+     *
+     * @param {CarouselNativeItemHostComponentBindEvent} nativeEvent The event
+     *        emitted by the native layer.
+     *
+     * @see {@link CarouselNativeItemHostComponentBindEvent}
+     */
+    onBind = (nativeEvent) => {
+        if (this.state.dataIndex !== nativeEvent.nativeEvent.index) {
+            const newState = {
+                ...this.state,
+                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
+            this.currentKey = (0, CarouselData_1.getItemKey)(this.props.dataAdapter, nativeEvent.nativeEvent.index);
+            this.setState(newState);
+            this.props.bindCallback(nativeEvent.nativeEvent.index);
+        }
+        else {
+            const newState = {
+                ...this.state,
+                refreshToggle: !this.state.refreshToggle,
+                itemShift: (0, CarouselData_1.getSelectedItemOffset)(this.props.dataAdapter, this.state.dataIndex),
+            };
+            this.setState(newState);
+        }
+    };
+    ////////////////////////////////////////
+    /// Private utility functions
+    /**
+     * Data pooling function. This function will use the {@link resolveDataItems}
+     * function to retrieve and resolve an item at the component's data index
+     * position.
+     *
+     * @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.
+     *
+     * @see {@link CarouselNativeItemState}
+     * @see {@link resolveDataItems}
+     */
+    resolveUpdatedItemContent = (state, props) => {
+        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) => {
+            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 = react_1.default.createElement(react_1.default.Fragment, null);
+        }
+        return element;
+    };
+    /**
+     * Convenience method to render a native component with the
+     * {@link itemElement} as its child component.
+     */
+    renderStateItem = () => {
+        return (react_1.default.createElement(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)
+                : 0, selectionBorderWidth: this.props.selectionBorderStyle?.borderWidth ??
+                defaultBorderStyle.borderWidth, selectionBorderRadius: this.props.selectionBorderStyle?.borderRadius ??
+                defaultBorderStyle.borderRadius, selectionBorderStrokeColor: this.props.showSelectionBorder
+                ? (0, react_native_1.processColor)(this.props.selectionBorderStyle?.borderStrokeColor ??
+                    defaultBorderStyle.borderStrokeColor)
+                : 0, selectionBorderStrokeWidth: this.props.selectionBorderStyle?.borderStrokeWidth ??
+                defaultBorderStyle.borderStrokeWidth, selectionBorderStrokeRadius: this.props.selectionBorderStyle?.borderStrokeRadius ??
+                defaultBorderStyle.borderStrokeRadius, selectionBorderStrategy: this.props.selectionBorderStrategy
+                ? (0, CarouselScrollableTypes_1.selectionBorderStrategyToBorderStrategy)(this.props.selectionBorderStrategy)
+                : 0, pressedItemScaleFactor: this.props.pressedItemScaleFactor, focusedItemScaleFactor: this.props.focusedItemScaleFactor, shiftItemsWidthScaleFactor: this.state.itemShift
+                ? this.state.itemShift.width
+                : this.props.shiftItemsScaleFactor.width, shiftItemsHeightScaleFactor: this.state.itemShift
+                ? this.state.itemShift.height
+                : this.props.shiftItemsScaleFactor.height, onBind: this.onBind }, this.itemElement));
+    };
+    ////////////////////////////////////////
+    /// Private attributes
+    /**
+     * This property is used to cache the resolved element of this item.
+     *
+     * @private
+     */
+    itemElement = undefined;
+}
+exports.CarouselNativeItemWrapper = CarouselNativeItemWrapper;