@amazon-devices/vega-carousel 0.1.3

package/dist/CarouselScrollable/CarouselScrollableProps.js

@@ -0,0 +1,211 @@
+"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.getDataAdapter = exports.useDefaults = exports.shiftItemsOnSelectionValue = exports.pinnedFocusOffsetValue = exports.CarouselScrollableDefaults = void 0;
+const CarouselScrollableTypes_1 = require("./CarouselScrollableTypes");
+/**
+ * This is a helper constant that holds all the _default values_ defined by the
+ * list.
+ *
+ * The values in this object will be updated whenever the documentation of the
+ * associated value changes, and vice versa.
+ *
+ * Refer to the documentation of the {@link CarouselScrollableConfigProps} type for
+ * details about each one of these fields.
+ *
+ * @see {@link CarouselScrollableConfigProps}
+ * @see {@link CarouselScrollableProps}
+ */
+exports.CarouselScrollableDefaults = {
+    orientation: CarouselScrollableTypes_1.ListOrientation.HORIZONTAL,
+    renderedItemsCount: 8,
+    numOffsetItems: 2,
+    navigableScrollOffset: 100,
+    initialStartIndex: 0,
+    itemPadding: 0,
+    itemPaddingOnFocus: 0,
+    showSelectionBorder: false,
+    selectionBorderStyle: {},
+    selectionBorderStrategy: 'outset',
+    trapFocusOnOrientation: false,
+    offsetNestedSelectionShift: false,
+    pressedItemScaleFactor: 0.8,
+    focusedItemScaleFactor: 1.0,
+    shiftItemsOnSelection: false,
+    selectionStrategy: CarouselScrollableTypes_1.ListSelectionStrategy.ANCHORED,
+    pinnedFocusOffset: 'center',
+    hideItemsBeforeSelection: false,
+    discardLastFocus: false,
+    scaleOrigin: CarouselScrollableTypes_1.ScaleOriginStrategy.TOP_LEFT,
+    shouldSelectedOverlap: false,
+    itemPressedDuration: 0.15,
+    itemScrollDuration: 0.2,
+    containerFocusChangeDuration: 0.2,
+    hasPreferredFocus: false,
+};
+/**
+ * Helper function to normalize a
+ * {@link CarouselScrollableConfigProps.pinnedFocusOffset} value to a number with
+ * value between the accepted range.
+ *
+ * @param {number | 'start' | 'center' | 'end'} value The
+ *        {@link CarouselScrollableConfigProps.pinnedFocusOffset} value to be
+ *        normalized.
+ *
+ * @return {number} - Returns the normalized number value for the
+ *         {@link CarouselScrollableConfigProps.pinnedFocusOffset} field.
+ *
+ * @see {@link CarouselScrollableConfigProps.pinnedFocusOffset}
+ */
+function pinnedFocusOffsetValue(value) {
+    if (typeof value === 'number') {
+        return Math.min(Math.max(value, 0), 1);
+    }
+    switch (value) {
+        case 'start':
+            return 0;
+        case 'center':
+            return 0.5;
+        case 'end':
+            return 1;
+    }
+}
+exports.pinnedFocusOffsetValue = pinnedFocusOffsetValue;
+function makeScaleFactor(value) {
+    return { width: value, height: value };
+}
+function shiftItemsOnSelectionValue(value, focusedItemScaleFactor) {
+    if (typeof value === 'boolean') {
+        if (value) {
+            return makeScaleFactor(focusedItemScaleFactor ??
+                exports.CarouselScrollableDefaults.focusedItemScaleFactor);
+        }
+        return makeScaleFactor(1);
+    }
+    else if (typeof value === 'number') {
+        return makeScaleFactor(value);
+    }
+    else if (typeof value === 'undefined') {
+        return makeScaleFactor(1);
+    }
+    return { width: value.width ?? 1, height: value.height ?? 1 };
+}
+exports.shiftItemsOnSelectionValue = shiftItemsOnSelectionValue;
+/**
+ * Helper function that returns a {@link CarouselScrollableProps} with any missing value
+ * set to their defined default.
+ *
+ * @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 The {@link CarouselScrollableProps} to fill
+ *        out default values.
+ *
+ * @return {RequiredCarouselScrollableProps<ItemT, KeyT>} Returns a "_properties_" object
+ *         where all the fields from the {@link CarouselScrollableConfigProps} are not
+ *         optionals, and have default values where the given `props` did not
+ *         have anything.
+ *
+ * @see {@link CarouselScrollableProps}
+ * @see {@link CarouselScrollableConfigProps}
+ */
+function useDefaults(props) {
+    return {
+        // Start with the given props;
+        ...props,
+        // Get default values for undefined props;
+        orientation: props.orientation ?? exports.CarouselScrollableDefaults.orientation,
+        navigableScrollOffset: props.navigableScrollOffset ??
+            exports.CarouselScrollableDefaults.navigableScrollOffset,
+        itemPadding: props.itemPadding ?? exports.CarouselScrollableDefaults.itemPadding,
+        itemPaddingOnFocus: props.itemPaddingOnFocus ?? exports.CarouselScrollableDefaults.itemPaddingOnFocus,
+        showSelectionBorder: props.showSelectionBorder ??
+            exports.CarouselScrollableDefaults.showSelectionBorder,
+        selectionBorderStyle: props.selectionBorderStyle ??
+            exports.CarouselScrollableDefaults.selectionBorderStyle,
+        selectionBorderStrategy: props.selectionBorderStrategy ??
+            exports.CarouselScrollableDefaults.selectionBorderStrategy,
+        trapFocusOnOrientation: props.trapFocusOnOrientation !== undefined
+            ? props.trapFocusOnOrientation
+            : exports.CarouselScrollableDefaults.trapFocusOnOrientation,
+        offsetNestedSelectionShift: props.offsetNestedSelectionShift !== undefined
+            ? props.offsetNestedSelectionShift
+            : exports.CarouselScrollableDefaults.offsetNestedSelectionShift,
+        pressedItemScaleFactor: props.pressedItemScaleFactor ??
+            exports.CarouselScrollableDefaults.pressedItemScaleFactor,
+        focusedItemScaleFactor: props.focusedItemScaleFactor ??
+            exports.CarouselScrollableDefaults.focusedItemScaleFactor,
+        selectionStrategy: props.selectionStrategy ?? exports.CarouselScrollableDefaults.selectionStrategy,
+        hideItemsBeforeSelection: props.hideItemsBeforeSelection !== undefined
+            ? props.hideItemsBeforeSelection
+            : exports.CarouselScrollableDefaults.hideItemsBeforeSelection,
+        discardLastFocus: props.discardLastFocus ?? exports.CarouselScrollableDefaults.discardLastFocus,
+        itemPressedDuration: props.itemPressedDuration ??
+            exports.CarouselScrollableDefaults.itemPressedDuration,
+        itemScrollDuration: props.itemScrollDuration ?? exports.CarouselScrollableDefaults.itemScrollDuration,
+        // Overlay any special trim or transform as the last action:
+        // -------------------------------------------------------------------------
+        // renderedItemsCount should have at least one element;
+        renderedItemsCount: Math.max(1, props.renderedItemsCount ?? exports.CarouselScrollableDefaults.renderedItemsCount),
+        // numOffsetItems shouldn't be a negative number and should be less than renderedItemsCount
+        numOffsetItems: props.numOffsetItems !== undefined &&
+            props.numOffsetItems >= 0 &&
+            props.numOffsetItems <
+                (props.renderedItemsCount ??
+                    exports.CarouselScrollableDefaults.renderedItemsCount)
+            ? props.numOffsetItems
+            : 0,
+        // initialStartIndex shouldn't be a negative number
+        initialStartIndex: Math.max(0, props.initialStartIndex ?? exports.CarouselScrollableDefaults.initialStartIndex),
+        // shiftItemsOnSelectionRatio should always be represented as a full
+        // ScaleFactor object;
+        shiftItemsOnSelection: shiftItemsOnSelectionValue(props.shiftItemsOnSelection ??
+            exports.CarouselScrollableDefaults.shiftItemsOnSelection, props.focusedItemScaleFactor),
+        // pinnedFocusOffset should be a number, even when one of the alias
+        // strings is given;
+        pinnedFocusOffset: pinnedFocusOffsetValue(props.pinnedFocusOffset ?? exports.CarouselScrollableDefaults.pinnedFocusOffset),
+        // scaleOrigin top-left or center;
+        scaleOrigin: props.scaleOrigin ?? exports.CarouselScrollableDefaults.scaleOrigin,
+        // shouldSelectedOverlap;
+        shouldSelectedOverlap: props.shouldSelectedOverlap ??
+            exports.CarouselScrollableDefaults.shouldSelectedOverlap,
+        // containerFocusChangeDuration, when not provided, should use the
+        // value set to the itemScrollDuration property, but only if it's not
+        // `undefined`, if it is, use the `itemScrollDuration` default value;
+        containerFocusChangeDuration: props.containerFocusChangeDuration ??
+            props.itemScrollDuration ??
+            exports.CarouselScrollableDefaults.itemScrollDuration,
+        hasPreferredFocus: props.hasPreferredFocus ?? exports.CarouselScrollableDefaults.hasPreferredFocus,
+    };
+}
+exports.useDefaults = useDefaults;
+/**
+ * Helper function to retrieve a {@link CarouselDataAdapter} from a
+ * {@link CarouselScrollableProps}.
+ *
+ * This function will use either the `dataAdapter` field if it is present, or
+ * the functions from the functional API to return an adapter.
+ *
+ * It allows you to not have to check which API style the user decides to use.
+ *
+ * @param {CarouselScrollableProps} props The property object used to extract a
+ *        {@link CarouselDataAdapter} from.
+ *
+ * @return {CarouselDataAdapter} Returns a data adapter object driving the data
+ *         used on the list component.
+ *
+ * @see {@link CarouselDataAdapter}
+ * @see {@link CarouselScrollableProps}
+ */
+function getDataAdapter(props) {
+    if (Object.keys(props).includes('getItem')) {
+        return props;
+    }
+    return props.dataAdapter;
+}
+exports.getDataAdapter = getDataAdapter;

package/dist/CarouselScrollable/CarouselScrollableRef.d.ts

@@ -0,0 +1,80 @@
+import { CarouselDataChange } from '../CarouselData';
+/**
+ * Contract for imperative operations allowed by the Carousel components.
+ *
+ * @template KeyT The type used on data items unique identifiers (also called
+ *           _stable IDs_, or _keys_) in the list;
+ */
+export interface CarouselScrollableRef {
+    /**
+     * When this function is called, it will change the list ability to handle
+     * input events.
+     *
+     * When the scrollable is set to not handle input events, it will _swallow_
+     * all the input events directed to it; therefore, preventing any object in
+     * the ancestry hierarchy to handle the input.
+     *
+     * If an object not related to the direct list's hierarchy is defined before
+     * the list, it still can consume input events normally.
+     *
+     * @param {boolean} enable Flag indicating if the list should handle input
+     *        events or not.
+     */
+    enableInputEvents(enable: boolean): void;
+    /**
+     * When this function is called, it will force the list to select the item on
+     * the given `index` position. Depending on the `ListSelectionStrategy`
+     * configured in the list, this function call may trigger a component scroll
+     * as the result of the selection.
+     *
+     * If the given `index` is outside the available data range, nothing will
+     * happen, and the list will log a warning message.
+     *
+     * If the selection operation finished successfully, a
+     * {@link SelectionChangeEvent} event will be emitted by the list at the end
+     * of the operation.
+     *
+     * @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 SelectionChangeEvent}
+     */
+    setSelectedItem(index: number, animated?: boolean): void;
+    /**
+     * This function allows one to hide or show items (depending on the value of
+     * the `visible` argument) that are positioned outside the “Scroll Offset”
+     * area, optionally, animating the process.
+     *
+     * When animating, the hide will be done with a _fade-out_ animation, and the
+     * "show" will use a _fade-in_; both animations will use the focus gain/lose
+     * duration property ({@link containerFocusChangeDuration}) for
+     * their duration.
+     *
+     * @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 CarouselScrollableConfigProps.containerFocusChangeDuration}
+     */
+    setOverflowItemsVisible(visible: boolean, animated?: boolean): void;
+    /**
+     * This function should be called be the user whenever the backing data for
+     * the list component changed somehow (one or more items were added, removed,
+     * or updated).
+     *
+     * This will allow the native layout to adjust its internal state to match the
+     * expectations about the data.
+     *
+     * @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 CarouselDataChange}
+     */
+    notifyDataChange(changes: Array<CarouselDataChange>, animated?: boolean): void;
+    reset(): void;
+}

package/dist/CarouselScrollable/CarouselScrollableRef.js

@@ -0,0 +1,7 @@
+"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 });

package/dist/CarouselScrollable/CarouselScrollableTypes.d.ts

@@ -0,0 +1,224 @@
+import { ColorValue } from 'react-native';
+import { AnyValue } from '../utils';
+/**
+ * A callback called whenever a list item needs to update its content with a new
+ * data item. This function can be called as the result of an item recycle, or a
+ * new item added to the list after the first list render, but never during the
+ * initial list mounting.
+ *
+ * @template ItemT The type of the data items the list is using to back its
+ *           data.
+ *
+ * @param {ItemT} item The data item that is about to be bound to a new frame;
+ * @param {number} index The positional index where this item is found in the
+ *        data set used in the list;
+ * @param {any} storedData An optional data stored by the item when it was
+ *        previously unbound. If this callback is invoked during the first
+ *        render of an item, this value will be `null`. In all other cases, this
+ *        value will be whatever the item passed to the `storeData` function
+ *        given to the `OnItemUnbindFunc` callback.
+ */
+export type OnItemBindFunc<ItemT> = (item: ItemT, index: number, storedData?: AnyValue) => void;
+/**
+ * A callback that will be called whenever an item in the list is about to be
+ * unbound, and will have its UI component released for recycle.
+ *
+ * This callback is always called **before** the _actual_ component recycle.
+ *
+ * @template ItemT The type of the data items the list is using to back its
+ *           data.
+ *
+ * @param {ItemT} item The data item that is about to be unbound from its frame;
+ * @param {number} index The positional index where this item is found in the
+ *        data set used in the list;
+ * @param {(dataValue: AnyValue) => void} storeData A function that the item should
+ *        call to store important information about its current state that will
+ *        be relevant the next time it is bound to a component.
+ */
+export type OnItemUnbindFunc<ItemT> = (item: ItemT, index: number, storeData: (dataValue: AnyValue) => void) => void;
+/**
+ * Callback called whenever the selected item changes in the list.
+ *
+ * The _selected item_ in the list is always the same as the _focused item_.
+ * Selection and Focus can be used interchangeably.
+ *
+ * @param {SelectionChangeEvent} event The current list selection state.
+ *
+ * @see {@link SelectionChangeEvent}
+ */
+export type OnSelectionChangedCallback = (event: SelectionChangeEvent) => void;
+/**
+ * Callback called whenever the selected item is activated by the user.
+ *
+ * An item activation happens when the user presses the selected button on the
+ * device's remote control, or when the user taps on the item on a touch-based
+ * device.
+ *
+ * @param {number} index The data index for the item that was just activated.
+ */
+export type OnItemActivatedCallback = (index: number) => void;
+/**
+ * Enumeration used to represent a list orientation.
+ *
+ * @enum {number}
+ */
+export declare enum ListOrientation {
+    VERTICAL = 0,
+    HORIZONTAL = 1
+}
+/**
+ * Enumeration used to represent the type of selection change supported by the
+ * list.
+ */
+export declare enum ListSelectionStrategy {
+    /**
+     * Represents the FlexList _no strategy_.
+     *
+     * Without selection strategy, changing the selected item will not cause the
+     * component to scroll unless the newly selected item is outside the _scroll
+     * offset_ area.
+     *
+     * Every time the next item about to be selected is outside the _scroll
+     * offset_ area, the selection change will cause the list component to scroll.
+     */
+    NATURAL = 0,
+    /**
+     * In this strategy, the selected item will always be positioned at the
+     * beginning of the _scroll offset_ area.
+     */
+    ANCHORED = 1,
+    /**
+     * This strategy will force the list component to scroll if the next selected
+     * item crosses the pinned position defined in the configuration. Differently
+     * from the {@link ANCHORED} strategy though, the `PINNED` strategy will not
+     * make the list scroll its contents if the last (or first) item in the list
+     * is already positioned at the scroll offset position.
+     *
+     * The `PINNED` behavior can be defined by the following:
+     *
+     * - If the list is rendering its start, and the selected itm is _before_ the
+     *   configured pinned position, selecting the next item will simply **move**
+     *   the selection to the next item without making the component scroll its
+     *   contents;
+     *
+     * - If the list is rendering its end, and the selected item is _after_ the
+     *   configured pinned position, selecting the previous item will simply
+     *   **move** the selection to the previous item without making the component
+     *   scroll its contents;
+     *
+     * - If selecting the _next_ or _previous_ item, makes the selection cross the
+     *   configured pinned position, the selection will move to the target item.
+     *   The list will scroll its contents, so the selected item is centralized
+     *   in the configured pinned position.
+     *
+     * - If the selected item is centralized at the configured pinned position,
+     *   and the first or last items are not positioned on the _edge_ of the
+     *   scroll offset area, any selection change will cause the list to scroll
+     *   its contents to keep the selected item centralized at the configured
+     *   pinned position;
+     *
+     * - When the last (or first) item in the list is positioned at the edge of
+     *   the scroll-offset area, changing the selection towards that edge will
+     *   make the selection to move and not the contents to scroll;
+     */
+    PINNED = 2
+}
+/**
+ * Enumeration used to represent the type of scale origin strategy supported by the
+ * list. Currently only scaling from top-left and center is supported
+ */
+export declare enum ScaleOriginStrategy {
+    TOP_LEFT = 0,
+    CENTER = 1
+}
+/**
+ * Enumeration used to represent different border rendering strategies for selection borders.
+ */
+export declare enum CarouselBorderStrategy {
+    /**
+     * Border is outside original content bounds and content stays the same size.
+     * This increases item size to include the border and then shrinks content back to its original size.
+     */
+    OUTSET = 0,
+    /**
+     * Border within the original content bounds and content remains the same size so border overlays content.
+     */
+    INSET = 1
+}
+/**
+ * String union type used to represent the selection border rendering strategy.
+ */
+export type SelectionBorderStrategy = 'inset' | 'outset';
+/**
+ * Helper function to convert SelectionBorderStrategy string to CarouselBorderStrategy enum.
+ * @param strategy The string strategy to convert
+ * @returns The corresponding CarouselBorderStrategy enum value
+ */
+export declare function selectionBorderStrategyToBorderStrategy(strategy: SelectionBorderStrategy): CarouselBorderStrategy;
+/**
+ * Contract for an object representing an **inclusive** range of data indexes.
+ */
+export type IndexRange = {
+    /**
+     * The first index in the range. Accessing an item at this index should give
+     * you the _first_ item.
+     */
+    start: number;
+    /**
+     * The last index in the range. Accessing an item at this index should give
+     * you the _last_ item.
+     */
+    end: number;
+};
+/**
+ * The current selection state in the list.
+ *
+ * It has information about the items being rendered at the moment, as well as
+ * the current selected one.
+ *
+ * @see {@link OnSelectionChangedCallback}
+ */
+export type SelectionChangeEvent = {
+    /**
+     * After the selection is changed, this range represents the indexes of all
+     * items being rendered in the component.
+     */
+    renderedRange: IndexRange;
+    /**
+     * This is the index of the item selected after the selection change finished.
+     */
+    selectedIndex: number;
+};
+export type ScaleFactor = {
+    width: number;
+    height: number;
+};
+/**
+ * This type represents all the styling options for the native selection border
+ * for the List component.
+ */
+export type SelectionBorderStyle = {
+    /** How thick the border surrounding the selected item should be. */
+    borderWidth?: number;
+    /**
+     * If the selection border should have rounded corners, this value represents
+     * how big the radius of those corners are.
+     */
+    borderRadius?: number;
+    /** What color to use on the selected item's border. */
+    borderColor?: ColorValue;
+    /**
+     * How thick the outline stroke that separates the border from the content
+     * should be.
+     */
+    borderStrokeWidth?: number;
+    /**
+     * A different radius for the rounded rect representing the outline stroke
+     * that separates the border from the content.
+     */
+    borderStrokeRadius?: number;
+    /**
+     * A different color to use on the selection border stroke.
+     */
+    borderStrokeColor?: ColorValue;
+};

package/dist/CarouselScrollable/CarouselScrollableTypes.js

@@ -0,0 +1,116 @@
+"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.selectionBorderStrategyToBorderStrategy = exports.CarouselBorderStrategy = exports.ScaleOriginStrategy = exports.ListSelectionStrategy = exports.ListOrientation = void 0;
+/**
+ * Enumeration used to represent a list orientation.
+ *
+ * @enum {number}
+ */
+var ListOrientation;
+(function (ListOrientation) {
+    ListOrientation[ListOrientation["VERTICAL"] = 0] = "VERTICAL";
+    ListOrientation[ListOrientation["HORIZONTAL"] = 1] = "HORIZONTAL";
+})(ListOrientation = exports.ListOrientation || (exports.ListOrientation = {}));
+/**
+ * Enumeration used to represent the type of selection change supported by the
+ * list.
+ */
+var ListSelectionStrategy;
+(function (ListSelectionStrategy) {
+    /**
+     * Represents the FlexList _no strategy_.
+     *
+     * Without selection strategy, changing the selected item will not cause the
+     * component to scroll unless the newly selected item is outside the _scroll
+     * offset_ area.
+     *
+     * Every time the next item about to be selected is outside the _scroll
+     * offset_ area, the selection change will cause the list component to scroll.
+     */
+    ListSelectionStrategy[ListSelectionStrategy["NATURAL"] = 0] = "NATURAL";
+    /**
+     * In this strategy, the selected item will always be positioned at the
+     * beginning of the _scroll offset_ area.
+     */
+    ListSelectionStrategy[ListSelectionStrategy["ANCHORED"] = 1] = "ANCHORED";
+    /**
+     * This strategy will force the list component to scroll if the next selected
+     * item crosses the pinned position defined in the configuration. Differently
+     * from the {@link ANCHORED} strategy though, the `PINNED` strategy will not
+     * make the list scroll its contents if the last (or first) item in the list
+     * is already positioned at the scroll offset position.
+     *
+     * The `PINNED` behavior can be defined by the following:
+     *
+     * - If the list is rendering its start, and the selected itm is _before_ the
+     *   configured pinned position, selecting the next item will simply **move**
+     *   the selection to the next item without making the component scroll its
+     *   contents;
+     *
+     * - If the list is rendering its end, and the selected item is _after_ the
+     *   configured pinned position, selecting the previous item will simply
+     *   **move** the selection to the previous item without making the component
+     *   scroll its contents;
+     *
+     * - If selecting the _next_ or _previous_ item, makes the selection cross the
+     *   configured pinned position, the selection will move to the target item.
+     *   The list will scroll its contents, so the selected item is centralized
+     *   in the configured pinned position.
+     *
+     * - If the selected item is centralized at the configured pinned position,
+     *   and the first or last items are not positioned on the _edge_ of the
+     *   scroll offset area, any selection change will cause the list to scroll
+     *   its contents to keep the selected item centralized at the configured
+     *   pinned position;
+     *
+     * - When the last (or first) item in the list is positioned at the edge of
+     *   the scroll-offset area, changing the selection towards that edge will
+     *   make the selection to move and not the contents to scroll;
+     */
+    ListSelectionStrategy[ListSelectionStrategy["PINNED"] = 2] = "PINNED";
+})(ListSelectionStrategy = exports.ListSelectionStrategy || (exports.ListSelectionStrategy = {}));
+/**
+ * Enumeration used to represent the type of scale origin strategy supported by the
+ * list. Currently only scaling from top-left and center is supported
+ */
+var ScaleOriginStrategy;
+(function (ScaleOriginStrategy) {
+    ScaleOriginStrategy[ScaleOriginStrategy["TOP_LEFT"] = 0] = "TOP_LEFT";
+    ScaleOriginStrategy[ScaleOriginStrategy["CENTER"] = 1] = "CENTER";
+})(ScaleOriginStrategy = exports.ScaleOriginStrategy || (exports.ScaleOriginStrategy = {}));
+/**
+ * Enumeration used to represent different border rendering strategies for selection borders.
+ */
+var CarouselBorderStrategy;
+(function (CarouselBorderStrategy) {
+    /**
+     * Border is outside original content bounds and content stays the same size.
+     * This increases item size to include the border and then shrinks content back to its original size.
+     */
+    CarouselBorderStrategy[CarouselBorderStrategy["OUTSET"] = 0] = "OUTSET";
+    /**
+     * Border within the original content bounds and content remains the same size so border overlays content.
+     */
+    CarouselBorderStrategy[CarouselBorderStrategy["INSET"] = 1] = "INSET";
+})(CarouselBorderStrategy = exports.CarouselBorderStrategy || (exports.CarouselBorderStrategy = {}));
+/**
+ * Helper function to convert SelectionBorderStrategy string to CarouselBorderStrategy enum.
+ * @param strategy The string strategy to convert
+ * @returns The corresponding CarouselBorderStrategy enum value
+ */
+function selectionBorderStrategyToBorderStrategy(strategy) {
+    switch (strategy) {
+        case 'inset':
+            return CarouselBorderStrategy.INSET;
+        case 'outset':
+            return CarouselBorderStrategy.OUTSET;
+        default:
+            return CarouselBorderStrategy.OUTSET; // Default fallback
+    }
+}
+exports.selectionBorderStrategyToBorderStrategy = selectionBorderStrategyToBorderStrategy;