@24i/bigscreen-sdk 0.9.9-alpha.2147

package/packages/list/src/UnifiedListController/UnifiedVariedListController.ts

@@ -0,0 +1,241 @@
+import { createRef } from '@24i/bigscreen-sdk/jsx';
+import { offsetPosition } from '@24i/bigscreen-sdk/utils/offsetPosition';
+import { ListBase } from '../Base';
+import { SharedVariedProps } from '../types';
+import { getOffsetObject, prepareOffsetsPx, prepareScrollOffsetsPx } from '../utils';
+import { ControllableListBase, ListConfig } from './interface';
+import { UnifiedListControllerBase } from './UnifiedListControllerBase';
+
+export class UnifiedVariedListController<T, Props
+extends SharedVariedProps<any, any> = SharedVariedProps<any, any>>
+    extends UnifiedListControllerBase<Props, ControllableListBase<Props>, T> {
+    /**
+     * Array of item offsets in pixels in list.
+     * Offset defines position, to place an item relative to the edge of an list's box.
+     */
+    offsetsPx: number[] = [];
+
+    /**
+      * Array of scroll offsets in pixels for items (with first step scroll correction).
+      * Offset defines position, to place an item relative to the edge of an list's box.
+      */
+    scrollOffsetsPx: number[] = [];
+
+    constructor(list: ControllableListBase<Props>, CONFIG: ListConfig) {
+        super(list, CONFIG);
+        const { itemsSizesPx, firstScrollStepPx, visibleItems } = this.list.props;
+        const { slowdownRatio = 0 } = this.animationConfiguration;
+        this.maxAllowedScrollLength = Math.max(...itemsSizesPx) * visibleItems * slowdownRatio;
+        this.fastLinearScrollThreshold = itemsSizesPx.reduce(
+            (a, b) => a + b,
+        ) / itemsSizesPx.length;
+        this.itemsCount = this.calculateInitItemsLimit();
+        this.offsetsPx = prepareOffsetsPx(itemsSizesPx);
+        this.scrollOffsetsPx = prepareScrollOffsetsPx(itemsSizesPx, firstScrollStepPx!);
+    }
+
+    componentDidMount() {
+        const { horizontal } = this.list.props;
+        const base = this.list.base.current!;
+        this.items = this.prepareAnimatedItems(base, this.offsetsPx);
+        this.items.forEach((item) => {
+            offsetPosition(item.element, getOffsetObject(horizontal, item.offset));
+        });
+        this.addScrollWrapFocusEvent();
+    }
+
+    componentWillUnmount() {
+        this.removeScrollWrapFocusEvent();
+    }
+
+    /**
+     * Callback for scroll animation, called with passed new scroll value on every
+     * frame while animation is running.
+     *
+     * NOTE: Arrangement of items in carousel is controlled in this point, based
+     * on tracking scroll value. Which enables well-optimized items updating, with
+     * keeping minimum elements in DOM.
+     *
+     * @param value Scroll position in pixels
+     */
+    onFrame = (value: number) => {
+        const { scrollToPx, backward, canScroll } = this.getNextScrollConfig(value);
+        if (!canScroll) return;
+        if (this.shouldReturnNormalAnimation(value)) {
+            const { normal } = this.animationConfiguration;
+            this.animations
+                .start(value, this.toPx, normal.time, normal.easing)
+                .onFrame(this.onFrame);
+            return;
+        }
+        const { base, props: { animate } } = this.list;
+        if (animate && scrollToPx === this.toPx) {
+            base.current!.animatedScrollFinished();
+        }
+        this.handleOnScrollChanged(scrollToPx, backward);
+        this.adjustItemsOffsetsOnFrame(scrollToPx, backward);
+        this.scrollListScroller(scrollToPx);
+        if (this.isScrollWrapFocused()) {
+            // try to focus current item if available, otherwise keep focused Scroll wrap
+            this.focusCurrentItem();
+        }
+    };
+
+    scroll(_: number, animate: boolean | undefined = this.list.props.animate) {
+        const base = this.list.base.current!;
+
+        this.fromPx = this.currentScrollPx;
+        this.toPx = this.scrollIndexToPixels(base.index);
+
+        if (animate) {
+            const { time, easing } = this.getEasingAndTime();
+            base.animatedScrollStarted();
+            this.animations
+                .start(this.fromPx, this.toPx, time, easing)
+                .onFrame(this.onFrame);
+        } else {
+            this.onFrame(this.toPx);
+        }
+    }
+
+    handleOnScrollChanged(scrollToPx: number, backward: boolean) {
+        const { onScrollChanged } = this.list.props;
+        if (typeof onScrollChanged !== 'function') return;
+        let scrollIndex = 0;
+        const { scrollOffsetsPx } = this;
+        for (let i = 0; i < scrollOffsetsPx.length - 1; i++) {
+            if (backward) {
+                if (scrollToPx >= scrollOffsetsPx[i] && scrollToPx < scrollOffsetsPx[i + 1]) {
+                    scrollIndex = i;
+                    break;
+                }
+            } else if (scrollToPx > scrollOffsetsPx[i] && scrollToPx <= scrollOffsetsPx[i + 1]) {
+                scrollIndex = i + 1;
+                break;
+            }
+        }
+        if (this.lastAnimationScrollIndex !== scrollIndex) {
+            this.lastAnimationScrollIndex = scrollIndex;
+            const item = this.list.base.current?.getRefAtDataIndex(scrollIndex);
+            onScrollChanged(item!, scrollIndex);
+        }
+    }
+
+    /**
+     * Adjust items formation in carousel based on scroll value from animation
+     * @param scrollValuePx Scroll position in pixels
+     * @param backward Flag whether backward scroll is performed
+     */
+    adjustItemsOffsetsOnFrame(scrollValuePx: number, backward: boolean) {
+        const mainItemIndex = this.scrollIndex;
+        if (backward) {
+            // check position of scroll item item
+            const isScrolledRight = this.scrollOffsetsPx[mainItemIndex] > scrollValuePx;
+            if (isScrolledRight) {
+                // it is outside the placeholder for first visible item
+                const scrollIndex = this.scrollPixelsToIndex(scrollValuePx);
+                if (mainItemIndex !== scrollIndex) {
+                    this.scrollIndex = scrollIndex;
+                    this.adjustItemsOffsets(this.scrollIndex);
+                }
+            }
+        } else {
+            const isFullyOutOfViewport = (
+                this.scrollOffsetsPx[mainItemIndex + 1] <= scrollValuePx
+            );
+            if (isFullyOutOfViewport) {
+                const scrollIndex = this.scrollPixelsToIndex(scrollValuePx);
+                if (mainItemIndex !== scrollIndex) {
+                    this.scrollIndex = scrollIndex;
+                    this.adjustItemsOffsets(this.scrollIndex);
+                }
+            }
+        }
+    }
+
+    adjustItemsOffsets(scrollIndex: number) {
+        const { horizontal, extraPrevItems } = this.list.props;
+        const { itemsCount, offsetsPx } = this;
+        const base = this.list.base.current!;
+        const dataLength = this.list.base.current!.data.length;
+
+        let dataIndex = scrollIndex - extraPrevItems!;
+        if (dataIndex > dataLength - itemsCount) {
+            dataIndex = dataLength - itemsCount;
+        }
+        if (dataIndex < 0) {
+            dataIndex = 0;
+        }
+
+        const steps = Math.floor(dataIndex / itemsCount);
+        const offset = steps * itemsCount;
+
+        this.items.forEach((item, index) => {
+            let itemDataIndex = index + offset;
+            if (itemDataIndex < dataIndex) {
+                itemDataIndex += itemsCount;
+            }
+            if (itemDataIndex >= dataLength) {
+                itemDataIndex -= itemsCount;
+            }
+
+            if (item.dataIndex !== itemDataIndex) {
+                item.dataIndex = itemDataIndex;
+                item.offset = offsetsPx[item.dataIndex];
+                base.updateItem(index, item.dataIndex - index);
+                offsetPosition(item.element, getOffsetObject(horizontal, item.offset));
+            }
+        });
+    }
+
+    scrollIndexToPixels(index: number) {
+        return this.scrollOffsetsPx[index];
+    }
+
+    scrollPixelsToIndex(pixels: number) {
+        const { scrollOffsetsPx } = this;
+        let scrollIndex;
+        for (scrollIndex = 0; scrollIndex < scrollOffsetsPx.length - 1; scrollIndex++) {
+            if (scrollOffsetsPx[scrollIndex + 1] > pixels) {
+                return scrollIndex;
+            }
+        }
+        return scrollIndex;
+    }
+
+    private calculateInitItemsLimit() {
+        const { visibleItems, extraPrevItems, extraNextItems } = this.list.props;
+        return extraPrevItems! + visibleItems + extraNextItems!;
+    }
+
+    private prepareAnimatedItems(list: ListBase<any, any>, offsetsPx: number[]) {
+        const childNodes = Array.prototype.slice.call(
+            list.scroller.current!.scrollRef.current!.childNodes,
+        );
+        return childNodes.map(
+            (element: HTMLElement, dataIndex: number) => ({
+                element: createRef<HTMLElement>(element),
+                dataIndex,
+                offset: offsetsPx[dataIndex],
+            }),
+        );
+    }
+
+    adjustItemsOffsetsForward() {
+        throw new Error('Not supported');
+    }
+
+    adjustItemsOffsetsBackward() {
+        throw new Error('Not supported');
+    }
+
+    // eslint-disable-next-line @typescript-eslint/no-unused-vars
+    appendData(data: T[]) {
+        throw new Error('appendData not yet supported');
+    }
+
+    // eslint-disable-next-line @typescript-eslint/no-unused-vars
+    prependData(data: T[]) {
+        throw new Error('prependData not yet supported');
+    }
+}

package/packages/list/src/UnifiedListController/interface.ts

@@ -0,0 +1,81 @@
+import { Reference } from '@24i/bigscreen-sdk/jsx';
+import { ListBase } from '../Base';
+import {
+    AnimationConfiguration,
+    BasicProps,
+} from '../types';
+
+export type ListConfig = {
+    defaultAnimation: AnimationConfiguration,
+    animate: boolean,
+};
+
+export interface UnifiedListController<T> {
+    /**
+     * Focuses current index item and calls onFocusChanged callback
+     * @param options FocusOptions
+     */
+    focusCurrentItem: (options?: FocusOptions) => void,
+    /**
+     * Scrolls list to the new scrollIndex with or without animation
+     * @param newScrollIndex new scroll index to scroll to
+     * @param animate flag whether the scroll should be animated
+     * - defaults to list.props.animate
+     */
+    scroll: (newScrollIndex: number, animate?: boolean) => void,
+    /**
+     * Scrolls the Scroller in base to the given value in pixels
+     * @param scrollValuePx pixel to scroll to
+     */
+    scrollListScroller: (scrollValuePx: number) => void,
+    /**
+     * Function to return the number of pixels to scroll to given a scrollIndex value
+     * @param index the scrollIndex for which to calculate the pixels distance
+     * @returns the number of pixels for scroll value
+     */
+    scrollIndexToPixels: (index: number) => number,
+    /**
+      * Function to scrollIndex value from scroll position in pixels
+      * @param pixels scroll position in pixels (expect positive number)
+      * @param backward boolean param for determine scroll direction (true is backward)
+      * @returns the number of pixels for scroll value
+      */
+    scrollPixelsToIndex: (scrollValuePx: number, backward: boolean) => number,
+    /**
+     * Adjusts items rotation
+     * @param scrollValuePx number of pixels that is scrolled to
+     * @param backward flag whether we scroll forward or backward
+     */
+    adjustItemsOffsetsOnFrame: (scrollValuePx: number, backward: boolean) => void,
+    /**
+     * Adjusts items rotation forward
+     * @param scrollIndex the scrollIndex scrolled to
+     */
+    adjustItemsOffsetsForward: (scrollIndex: number) => void,
+    /**
+     * Adjusts items rotation backward
+     * @param scrollIndex the scrollIndex scrolled to
+     */
+    adjustItemsOffsetsBackward: (scrollIndex: number) => void,
+    /**
+     * Appends data at the end of data array
+     * @param data data to append
+     */
+    appendData: (data: T[]) => void,
+    /**
+     * Prepends data at the start of data array
+     * @param data data to prepend
+     */
+    prependData: (data: T[]) => void,
+}
+
+export interface ControllableListBase<T extends BasicProps<any, any> = BasicProps<any, any>> {
+    /**
+     * The list Base component
+     */
+    base: Reference<ListBase<any, any>>,
+    /**
+     * Props of the list
+     */
+    props: T,
+}

package/packages/list/src/__test__/utils.spec.ts

@@ -0,0 +1,59 @@
+import {
+    calcVisibleItemCount,
+    prepareOffsetsPx,
+    prepareScrollOffsetsPx,
+    scrollPixelsToIndexForward,
+    scrollPixelsToIndexBackward,
+} from '../utils';
+
+describe('calcVisibleItemCount', () => {
+    it('should return number of visible item for given viewport and item size', () => {
+        expect(calcVisibleItemCount(100, 20)).toBe(6);
+        expect(calcVisibleItemCount(110, 20)).toBe(6);
+        expect(calcVisibleItemCount(111, 20)).toBe(7);
+        expect(calcVisibleItemCount(120, 20)).toBe(7);
+    });
+});
+
+describe('prepareOffsetsPx', () => {
+    it('should return array of offsets for given sizes', () => {
+        const offsetsPx = prepareOffsetsPx([10, 10, 50, 10]);
+        expect(offsetsPx).toEqual([0, 10, 20, 70]);
+    });
+});
+
+describe('prepareScrollOffsetsPx', () => {
+    it('should return array of offsets for given sizes and zero first scroll step', () => {
+        const offsetsPx = prepareScrollOffsetsPx([20, 10, 50, 10], 0);
+        expect(offsetsPx).toEqual([0, 20, 30, 80]);
+    });
+
+    it('should return array of offsets for given sizes and non-zero first scroll step', () => {
+        const offsetsPx = prepareScrollOffsetsPx([20, 10, 50, 10], 17);
+        expect(offsetsPx).toEqual([0, 17, 27, 77]);
+    });
+});
+
+describe('scrollPixelsToIndex(forward/backward)', () => {
+    it('should get proper values for forward', () => {
+        let value = scrollPixelsToIndexForward(0, 10);
+        expect(value).toEqual(0);
+        value = scrollPixelsToIndexForward(10, 8);
+        expect(value).toEqual(2);
+        value = scrollPixelsToIndexForward(1, 2, 3);
+        expect(value).toEqual(1);
+        value = scrollPixelsToIndexForward(100, 20, 10);
+        expect(value).toEqual(6);
+    });
+
+    it('should get proper values for backward', () => {
+        let value = scrollPixelsToIndexBackward(0, 10);
+        expect(value).toEqual(0);
+        value = scrollPixelsToIndexBackward(10, 8);
+        expect(value).toEqual(1);
+        value = scrollPixelsToIndexBackward(1, 2, 3);
+        expect(value).toEqual(0);
+        value = scrollPixelsToIndexBackward(100, 20, 10);
+        expect(value).toEqual(5);
+    });
+});

package/packages/list/src/animate.animated.ts

@@ -0,0 +1 @@
+export const animate = true;

package/packages/list/src/animate.ts

@@ -0,0 +1 @@
+export const animate = false;

package/packages/list/src/index.ts

@@ -0,0 +1 @@
+throw new Error('This package has no index export. Please use the path submodules.');

package/packages/list/src/interface.ts

@@ -0,0 +1,41 @@
+import { Component, Reference } from '@24i/bigscreen-sdk/jsx';
+import { IFocusable } from '@24i/bigscreen-sdk/focus';
+import { SharedProps, SharedVariedProps, Item } from './types';
+
+export interface List<
+    T extends Item<U>, U, V extends SharedProps<T, U> = SharedProps<T, U>,
+> extends IFocusable, Component<V> {
+    appendData(data: U[]): void,
+    prependData(data: U[]): void,
+    scrollTo(index: number): void,
+}
+
+export interface VariedList<
+    T extends Item<U>, U, V extends SharedVariedProps<T, U> = SharedVariedProps<T, U>,
+> extends IFocusable, Component<V> {
+    appendData(data: U[]): void,
+    prependData(data: U[]): void,
+    scrollTo(index: number): void,
+}
+
+export interface ListComponent<
+    T extends Item<U>, U, V extends SharedProps<T, U> = SharedProps<T, U>,
+> {
+    new (props: V): List<T, U, V>,
+}
+
+export interface ItemComponent<T> {
+    new (props: any): Item<T>,
+}
+
+export type AttachDetachItemData<T, U> = {
+    data: U,
+    ref: Reference<T>,
+    isFastScrolling: boolean,
+    node?: HTMLElement,
+};
+
+export {
+    SharedProps as Props,
+    Item,
+};

package/packages/list/src/mocks/index.tsx

@@ -0,0 +1,55 @@
+import { createRef, Component } from '@24i/bigscreen-sdk/jsx';
+import { Item } from '../types';
+
+export type MockData = { id: number };
+
+export const getMockData = (amount: number) => {
+    const data = [];
+    for (let i = 0; i < amount; i++) {
+        data.push({ id: i });
+    }
+    return data;
+};
+
+type Props = {
+    className: string,
+    id: number,
+};
+
+export class MockItem extends Component<Props> implements Item<MockData> {
+    div = createRef<HTMLDivElement>();
+
+    show = jest.fn();
+
+    hide = jest.fn();
+
+    focus(options?: FocusOptions) {
+        this.div.current!.focus(options);
+    }
+
+    updateData(data: MockData) {
+        this.div.current!.id = data.id.toString();
+    }
+
+    hasDom(dom: HTMLElement) {
+        return this.div.current === dom;
+    }
+
+    render() {
+        const { id, className } = this.props;
+        return (
+            <div
+                tabIndex={0}
+                className={className}
+                id={id.toString()}
+                ref={this.div}
+            />
+        );
+    }
+}
+
+export const callNTimes = (fn: Function, times: number) => {
+    for (let i = times; i > 0; i--) {
+        fn();
+    }
+};

package/packages/list/src/types.ts

@@ -0,0 +1,120 @@
+import { Reference, Component } from '@24i/bigscreen-sdk/jsx';
+import { EasingType } from '@24i/bigscreen-sdk/animations';
+
+export interface Item<T> extends Component<any> {
+    focus: (options?: FocusOptions) => void,
+    show: () => void,
+    hide: () => void,
+    updateData: (item: T, index: number) => void,
+    hasDom?: (target: HTMLElement) => boolean,
+    onFastScrolling?: (isFastScrolling: boolean) => void,
+}
+
+export type ItemInfo = {
+    element: Reference<HTMLElement>,
+    dataIndex: number,
+    offset: number,
+};
+
+export type BasicProps<T extends Item<U>, U> = {
+    /**
+     * Array of items data for list
+     */
+    data: U[],
+    /**
+     * Function to render item in list
+     * @param item The item to be rendered
+     * @param index Index of item in the array
+     * @param ref Reference has to be set to rendered item component
+     */
+    renderItem: (item: U, index: number, ref: Reference<T>) => JSX.Element,
+    /**
+     * Number of visible items, which be rendered in list DOM.
+     */
+    visibleItems: number,
+    /**
+     * Additional class name to be added to list DOM element
+     */
+    className?: string,
+    /**
+     * Flag of list orientation. true for horizontal, otherwise vertical.
+     */
+    horizontal?: boolean,
+    /**
+     * Function called every time when focus of item is changed in list
+     * @param item Reference to new focused item
+     * @param index Index of item in the array
+     */
+    onFocusChanged?: (item: Reference<T>, index: number) => void,
+    /**
+     * Flag of animated/non animated behaviour. Default value is taken from list
+     * config files
+     */
+    animate?: boolean,
+    animation?: AnimationConfiguration,
+
+    /**
+     * Flag that allows speed up scrolling with built in feature in Item
+     * (onFastScrolling) by reducing amount of elements during scrolling.
+     */
+    fastScrolling?: boolean,
+
+    /**
+     * Flag that enables fast focusing optimization for scrolling. It prevents
+     * focusing items during scrolling that reduces possible reflow performance
+     * issues.
+     */
+    fastFocusingOptimization?: boolean,
+
+    /**
+     * Function called every time before list performs one full scroll.
+     * @param item Reference to item on current scroll
+     * @param scrollIndex index of current scroll in list
+     */
+    onScrollChanged?: (item: Reference<T>, scrollIndex: number) => void,
+};
+
+export type SharedProps<T extends Item<U>, U> = BasicProps<T, U> & {
+    scrollStep: number,
+    firstScrollStep?: number,
+};
+
+export type SharedVariedProps<T extends Item<U>, U> = BasicProps<T, U> & {
+    /**
+     * Size of visible list area in pixels.
+     * Provide width size for horizontal list, otherwise height size.
+     */
+    viewportSizePx: number,
+    /**
+     * Sizes of items in pixels.
+     * Provide item's width size for horizontal list, otherwise height size.
+     */
+    itemsSizesPx: number[],
+    /**
+     * Number of rendered items above visibleItems at beginning side of list.
+     */
+    extraPrevItems?: number,
+    /**
+     * Number of rendered items above visibleItems at end side of list.
+     */
+    extraNextItems?: number,
+    /**
+     * Size in pixels applied to first scroll. Enables previous item to be
+     * partially visible in viewport while another content scrolls, should be
+     * used in combination with extraPrevItems=1
+     */
+    firstScrollStepPx?: number,
+};
+
+export type AnimationConfiguration = {
+    normal: {
+        time: number,
+        easing: EasingType,
+    },
+    fastLinear?: {
+        time: number,
+        startRatio: number,
+        endRatio?: number,
+    }
+    slowdownRatio?: number,
+};