@amazon-devices/vega-carousel 0.1.3

package/dist/CarouselScrollable/CarouselScrollableProps.d.ts

@@ -0,0 +1,499 @@
+import type { ViewProps } from 'react-native';
+import React from 'react';
+import { ListOrientation, ListSelectionStrategy, OnItemBindFunc, OnItemUnbindFunc, OnSelectionChangedCallback, ScaleFactor, ScaleOriginStrategy, SelectionBorderStrategy, SelectionBorderStyle } from './CarouselScrollableTypes';
+import { CarouselDataAdapter, RenderItemFunc } from '../CarouselData';
+/**
+ * This type contains properties that relate to how {@link CarouselScrollable}
+ * is identified.
+ *
+ * @see {@link CarouselScrollable}
+ * @see {@link CarouselScrollableProps}
+ */
+export type CarouselScrollableInfoProps = {
+    /**
+     * An arbitrary and unique identifier for this list that will be used
+     * to determine when to recycle the list and its items.
+     *
+     * @default undefined
+     */
+    uniqueId?: string;
+};
+/**
+ * This type represents the group of properties for the {@link CarouselScrollable}
+ * component that will change how it is displayed and how it behaves.
+ *
+ * These properties are not intended to change during the component's lifecycle.
+ * If you require changing them, you will need to force a re-render on the list
+ * component.
+ *
+ * @see {@link CarouselScrollable}
+ * @see {@link CarouselScrollableProps}
+ */
+export type CarouselScrollableConfigProps = {
+    /**
+     * Indicates if the list is horizontal or vertical.
+     *
+     * @default listOrientation.HORIZONTAL
+     * @see {@link ListOrientation}
+     */
+    orientation?: ListOrientation;
+    /**
+     * The number of items to be rendered at a given time.
+     *
+     * Always set this value to a number bigger than the number of items that fit
+     * in the screen.
+     *
+     * When a selection change triggers a scroll, the last item in the opposite
+     * direction will be _"recycled"_ so the next one, in the same direction as
+     * the selection, can use that recycled frame to render.
+     *
+     * @default 10
+     */
+    renderedItemsCount?: number;
+    /**
+     * A secondary margin that exists only on the orientation axis of the
+     * component (left and right for {@link ListOrientation.HORIZONTAL} lists, and
+     * top and bottom for {@link ListOrientation.VERTICAL} lists).
+     *
+     * This secondary margin is mostly used to restrict the “navigable” range of
+     * the list’s selection, but other features of the component use this margin
+     * as reference for their behavior.
+     *
+     * Since the “scroll offset margin” exists on both ends of the component, when
+     * an item is rendered there, we say the item is _outside the scroll offset
+     * area_, or that the item is an “_overflown item_” in the list.
+     *
+     * @default 100
+     * @see {@link ListOrientation}
+     */
+    navigableScrollOffset?: number;
+    /**
+     * The screen distance that each item on the list will have between its
+     * neighbor items.
+     *
+     * @default 0
+     */
+    itemPadding?: number;
+    /**
+     * The extra screen distance that each item on the list will have between its
+     * neighbor items when list is focused.
+     *
+     * @default 0
+     */
+    itemPaddingOnFocus?: number;
+    /**
+     * Allow us to have the list component start its lifecycle with a different
+     * item selected instead of the item in the first available position.
+     *
+     * When omitted (set to `undefined`), the item in the first available position
+     * will be used as the initial selection.
+     *
+     * @default 0
+     */
+    initialStartIndex?: number;
+    /**
+     * When laying out its items, depending on the selection index, the scrollable
+     * might need to render items before the selected item.
+     *
+     * This option defines how many items to place “before” the left “Scroll
+     * Offset” margin ({@link navigableScrollOffset}), and together with the “max number
+     * of mounted items” ({@link renderedItemsCount}) one, allows you to control the
+     * recycling “buffer” of the list.
+     *
+     * @default 2
+     * @see {@link navigableScrollOffset}
+     * @see {@link renderedItemsCount}
+     */
+    numOffsetItems?: number;
+    /**
+     * 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.
+     *
+     * @default 'outset'
+     * @see {@link SelectionBorderStrategy}
+     */
+    selectionBorderStrategy?: SelectionBorderStrategy;
+    /**
+     * This flag will prevent the focus from progressing to the nearest component
+     * outside the list, alongside its orientation axis.
+     *
+     * Meaning, if the list is horizontal and the selected item is:
+     *
+     *   1. The first item and the user presses left;
+     *   2. The last item and the user presses right;
+     *
+     * Then this flag will prevent the focus from escaping the list.
+     *
+     * @default false
+     */
+    trapFocusOnOrientation?: boolean;
+    /**
+     * This flag will force the scrollable list to check its items for a nested
+     * scrollable list.
+     *
+     * When found, it will make the component to counter-offset its child
+     * selection shift so the nested items won't move on the orientation of the
+     * parent scrollable.
+     *
+     * @default false
+     */
+    offsetNestedSelectionShift?: boolean;
+    /**
+     * A scale multiplier to be applied to the item when it is being activated by
+     * the user (e.g., the user pressed down the select button on the device's
+     * remote control).
+     *
+     * NOTE : This value should be based on the selected dimensions of a card.
+     *
+     * @default 0.8
+     */
+    pressedItemScaleFactor?: number;
+    /**
+     * A scale multiplier to be applied to the selected item.
+     *
+     * When this value is `1.0`, it means there will be no scaling happening to
+     * the selected item while the user scrolls through the list.
+     *
+     * @default 1.0
+     */
+    focusedItemScaleFactor?: number;
+    /**
+     * This flag indicates to the scrollable list the scaling strategy of the items when
+     * selected.
+     * *Currently on scaling from top-left corner of item or center scaling is supported*
+     * top-left - scale from top-left
+     * center - scale from center
+     *
+     * @default ScaleOriginStrategy.TOP_LEFT
+     */
+    scaleOrigin?: ScaleOriginStrategy;
+    /**
+     * This flag indicates to the scrollable list the enabling of overlapping the items
+     * when scaling while the items are selected
+     * By default the shift will be turned off
+     *
+     * @default false
+     */
+    shouldSelectedOverlap?: boolean;
+    /**
+     * This property defines a *scale factor* that will be used to calculate an
+     * *orientation shift* of the selected item and its predecessors, whenever the
+     * list selection changes.
+     *
+     * You can pass a {@link ScaleFactor} object to define different shifts on
+     * each component's axes, a _single number_ that will be used on all axes, or
+     * a _`boolean`_ flag that, when `true`, will force the component to use the
+     * {@link focusedItemScaleFactor} value as its shift factor on all axes.
+     *
+     * The base dimension used to calculate the shift distance, it is always the
+     * selected item's full size, without any scale factor applied to it.
+     *
+     * It's important to notice that the shift of items on selection is
+     * independent of the {@link focusedItemScaleFactor} property, and can always
+     * be applied even if the selected item is not being scaled-up.
+     *
+     * @default false
+     * @see {@link focusedItemScaleFactor}
+     */
+    shiftItemsOnSelection?: boolean | number | ScaleFactor;
+    /**
+     * This option defines the relation between item selection change and
+     * scrolling.
+     *
+     * For details on how this property affects the list component, check the
+     * {@link ListSelectionStrategy} documentation.
+     *
+     * @default ScrollSelectionStrategy.ANCHORED
+     * @see {@link ListSelectionStrategy}
+     */
+    selectionStrategy?: ListSelectionStrategy;
+    /**
+     * Defines the component's size fraction used as the pinned selected position
+     * value.
+     *
+     * This property must be a value between `0.0` and `1.0` and only has any
+     * effect when the {@link selectionStrategy} property is set to
+     * {@link ListSelectionStrategy.PINNED}.
+     *
+     * Alternatively, you can set this property to one of the three pre-defined
+     * positions strings: `'start'` (will set this property to `0.0`), `'center'`
+     * (will set this property to `0.5`), and `'end'` (will set this property to
+     * `0.1`).
+     *
+     * @default 'center'
+     * @see {@link selectionStrategy}
+     * @see {@link ListSelectionStrategy}
+     */
+    pinnedFocusOffset?: number | 'start' | 'center' | 'end';
+    /**
+     * This flag indicates to the scrollable list that it can “over-optimize” its
+     * render stack by detaching items from the view tree, as soon as they cross
+     * the “Scroll Offset” margin.
+     *
+     * Be careful with this property; although it can improve performance, it
+     * might cause the list component to “vanish” items before they're fully
+     * positioned outside the visible area.
+     *
+     * @default false
+     */
+    hideItemsBeforeSelection?: boolean;
+    /**
+     * This flag indicates to the scrollable list that it can “discard the last focused item”,
+     * to override the default behavior of retaining the last focused item.
+     *
+     *
+     * @default false
+     */
+    discardLastFocus?: boolean;
+    /**
+     * Number of seconds that the item activation animation takes to complete.
+     *
+     * @default 0.15 seconds
+     */
+    itemPressedDuration?: number;
+    /**
+     * Number of seconds that a selection change animation takes to complete.
+     *
+     * @default 0.2 seconds
+     */
+    itemScrollDuration?: number;
+    /**
+     * Number of seconds that a selection change animation takes to complete when
+     * the component is gaining or losing focus.
+     *
+     * The animation that this option controls is the same animation used by the
+     * “Selection Change” but this option is only used if the list itself gains
+     * or loses focus.
+     *
+     * @default CarouselScrollableConfigProps.itemScrollDuration
+     */
+    containerFocusChangeDuration?: number;
+    /**
+     * Determines whether this component should automatically receive focus when rendered.
+     * When true, the component will attempt to gain focus during the initial mount or when the prop value changes.
+     *
+     * @default false
+     */
+    hasPreferredFocus?: boolean;
+};
+/**
+ * This type encapsulates the function used by the {@link CarouselScrollable} to resolve
+ * its child items.
+ *
+ * @see {@link CarouselScrollable}
+ * @see {@link CarouselScrollableProps}
+ */
+export type CarouselScrollableResolverProps<ItemT> = {
+    /**
+     * This function is called whenever the scrollable component needs to get the
+     * item’s declaration.
+     *
+     * If the item is not ready to be displayed when this function is invoked, it
+     * should return a **placeholder** component to allow the list to display
+     * something for the item.
+     *
+     * Returning an `undefined` value from this function will indicate to the
+     * component that the item cannot be used in the list during the current
+     * component's lifecycle.
+     *
+     * When that happens, the component will notify the caller that this
+     * particular data item failed by calling the {@link notifyDataError}
+     * function.
+     *
+     * @function
+     * @see {@link getItem}
+     * @see {@link CarouselDataAdapterReader.notifyDataError}
+     * @see {@link RenderItemFunc}
+     */
+    renderItem: RenderItemFunc<ItemT>;
+};
+/**
+ * This type wrap all of the {@link CarouselDataAdapter} functions into a single
+ * property.
+ *
+ * @see {@link CarouselScrollable}
+ * @see {@link CarouselScrollableProps}
+ * @see {@link CarouselDataAdapter}
+ */
+export type CarouselScrollableDataAdapterProps<ItemT, KeyT = React.Key> = {
+    /**
+     * The object used to retrieve items and other information about them.
+     *
+     * For details on the {@link CarouselDataAdapter} object, check its
+     * documentation.
+     *
+     * @see {@link CarouselDataAdapter}
+     */
+    dataAdapter: CarouselDataAdapter<ItemT, KeyT>;
+};
+/**
+ * The functions in this type, when present, will be called when an internal
+ * important event happened, to give the opportunity to the caller to act on
+ * those scenarios.
+ *
+ * @see {@link CarouselScrollable}
+ * @see {@link CarouselScrollableProps}
+ */
+export type CarouselScrollableCallbackProps<ItemT> = {
+    /**
+     * Function called when the Scrollable List is binding an item to a new native
+     * frame.
+     *
+     * The argument `savedStateData` is whatever the user passed to the
+     * `saveStateData` function on the {@link onItemUnbind} when it was previously
+     * unbound, or undefined if there is no known data for the item.
+     *
+     * @function
+     * @default undefined
+     * @see {@link OnItemBindFunc}
+     */
+    onItemBind?: OnItemBindFunc<ItemT>;
+    /**
+     * Function called when the list is not rendering an item anymore,
+     * and is ready to re-use the item's view with some other item.
+     *
+     * This happens **before** a component item is recycled during a scroll.
+     *
+     * @function
+     * @default undefined
+     * @see {@link OnItemUnbindFunc}
+     */
+    onItemUnbind?: OnItemUnbindFunc<ItemT>;
+    /**
+     * Function called whenever the current selected item on the list changes
+     * (it's not called when the list gains or loses focus).
+     *
+     * If the user needs that information, the {@link initialStartIndex}
+     * should be stored in a {@link React.Ref}, and updated whenever the
+     * `onSelectionChange` is called, then, the user can use the standard
+     * `onFocus` and `onBlur` callbacks on the scrollable list to trigger some
+     * special behavior.
+     *
+     * @function
+     * @default undefined
+     * @see {@link initialStartIndex}
+     * @see {@link OnSelectionChangedCallback}
+     * @see {@link SelectionChangeEvent}
+     */
+    onSelectionChanged?: OnSelectionChangedCallback;
+};
+/**
+ * Configurable properties of a {@link CarouselScrollable} component.
+ *
+ * This type groups all the `CarouselScrollable*` property types, with a special behavior
+ * for the Data Adapter properties.
+ *
+ * The user can choose between a functional API style or a Data Adapter object
+ *
+ * @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 ViewProps}
+ * @see {@link CarouselScrollableInfoProps}
+ * @see {@link CarouselScrollableResolverProps}
+ * @see {@link CarouselScrollableCallbackProps}
+ * @see {@link CarouselScrollableDataAdapterProps}
+ * @see {@link CarouselDataAdapter}
+ */
+export type CarouselScrollableProps<ItemT, KeyT = React.Key> = ViewProps & CarouselScrollableInfoProps & CarouselScrollableConfigProps & (CarouselDataAdapter<ItemT, KeyT> | CarouselScrollableDataAdapterProps<ItemT, KeyT>) & CarouselScrollableResolverProps<ItemT> & CarouselScrollableCallbackProps<ItemT>;
+/**
+ * Helper type to hold the fields of a {@link CarouselScrollableProps} with its config
+ * props set to their default value when not present.
+ *
+ * @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 CarouselScrollableProps}
+ * @see {@link Required}
+ */
+export type RequiredCarouselScrollableProps<ItemT, KeyT = React.Key> = ViewProps & CarouselScrollableInfoProps & Omit<Required<CarouselScrollableConfigProps>, 'pinnedFocusOffset' | 'shiftItemsOnSelection'> & (CarouselDataAdapter<ItemT, KeyT> | CarouselScrollableDataAdapterProps<ItemT, KeyT>) & CarouselScrollableResolverProps<ItemT> & CarouselScrollableCallbackProps<ItemT> & {
+    pinnedFocusOffset: number;
+    shiftItemsOnSelection: ScaleFactor;
+};
+/**
+ * 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}
+ */
+export declare const CarouselScrollableDefaults: Required<CarouselScrollableConfigProps>;
+/**
+ * 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}
+ */
+export declare function pinnedFocusOffsetValue(value: number | 'start' | 'center' | 'end'): number;
+export declare function shiftItemsOnSelectionValue(value: boolean | number | ScaleFactor | undefined, focusedItemScaleFactor: number | undefined): ScaleFactor;
+/**
+ * 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}
+ */
+export declare function useDefaults<ItemT, KeyT = React.Key>(props: CarouselScrollableProps<ItemT, KeyT>): RequiredCarouselScrollableProps<ItemT, KeyT>;
+/**
+ * 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}
+ */
+export declare function getDataAdapter<ItemT, KeyT = React.Key>(props: CarouselScrollableProps<ItemT, KeyT>): CarouselDataAdapter<ItemT, KeyT>;