@24i/bigscreen-sdk 1.0.38 → 1.0.40-alpha.2687

package/packages/grid/src/UnifiedGridController/UnifiedGridController.ts

@@ -1,555 +1,555 @@
-import { AnimationUtils, JSAnimations } from '@24i/bigscreen-sdk/animations';
-import { forEach } from '@24i/bigscreen-sdk/perf-utils/array';
-import { offsetPosition } from '@24i/bigscreen-sdk/utils/offsetPosition';
-import {
-    configureAnimation,
-    getOffsetObject,
-    prepareAnimatedGroups,
-    scrollPixelsToIndexBackward,
-    scrollPixelsToIndexForward,
-} from '../utils';
-import { AnimationConfiguration, GroupInfo } from '../types';
-import {
-    ControllableGrid,
-    GridConfig,
-    UnifiedGridController as IUnifiedGridController,
-} from './interface';
-
-/**
- * Number of rendered items above visibleItems (half on each side of the list)
- * that could become visible during fast scroll animation
- * If needed to be changed, keep it even
- */
-const LIMIT_EXTRA = 2;
-
-export class UnifiedGridController<T> implements IUnifiedGridController<T> {
-    /**
-     * Grid that is controlled by this controller
-     */
-    protected grid: ControllableGrid;
-
-    /**
-     * Controls scroll animation that triggers position in px, on every frame.
-     */
-    private readonly animations = new JSAnimations();
-
-    /**
-     * Defines timelines/speeds configuration for scroll animation.
-     */
-    private readonly animationConfiguration: AnimationConfiguration;
-
-    /**
-     * The scroll index being captured on every animation frame. Derived from
-     * scroll position. It can differ to `scrollIndex` during animation run.
-     */
-    protected lastAnimationScrollIndex = 0;
-
-    /**
-     * Optimization to avoid unnecessary group adjustments if scrollIndex remains the same.
-     * It can differ to `scrollIndex` during animation run.
-     */
-    protected lastScrollIndex = 0;
-
-    /**
-     * The number of pixels, that grid content is starting scroll animation at
-     * (from its left edge (LTR layout)).
-     */
-    private fromPx = 0;
-
-    /**
-     * The number of pixels, that grid content is ending scroll animation at
-     * (from its left edge (LTR layout)).
-     */
-    private toPx = 0;
-
-    /**
-     * The current value represents grid scroll in pixels
-     * Initial value is 0, if its different, please set before first scroll
-     */
-    protected currentScrollPx = 0;
-
-    /**
-     * Number which determines, when linear scroll switch start or end. Number should be
-     * size of one item (scrollStep), or average item size in case of multiple sizes
-     */
-    protected fastLinearScrollThreshold = 0;
-
-    /**
-     * Flag, if list scrolling is currently fast linear
-     */
-    protected isFastLinearScroll = false;
-
-    /**
-     * Maximum scroll length for determine if list can scroll further.
-     * If the value is 0, scroll is not limited
-     */
-    protected maxAllowedScrollLength = 0;
-
-    /**
-     * The first number where the list is scrolled on the start. The default value is NaN
-     * because it is assigned during the first scrolling.
-     */
-    protected initialScrollPx = NaN;
-
-    /**
-     * Flag, if list focus optimizing is running (when full fast focus optimization is disabled)
-     */
-    protected focusOptimizing = false;
-
-    /* Last focused index when grid is fully scrolled and forwardGroup/backwardGroup
-     * was not processed, but animation has not finished yet
-     */
-    protected lastFocusOnNotProcessed = -1;
-
-    /**
-     * Number of pixels for offsetting (cycle-shifting) rendered groups
-     */
-    protected groupOffsetStepPx = 0;
-
-    /**
-     * Number of rendered groups above visibleGroups
-     */
-    protected limitExtra = 0;
-
-    /**
-     * Moving below 0 by a half of LIMIT_EXTRA and 2 for index/length diff and 1 partially visible
-     */
-    protected leftBoundary = 0;
-
-    /**
-     * Moving above highest index by a half of LIMIT_EXTRA and 1 for partially visible
-     * index/length diff of 1 is not needed here
-     */
-    protected rightBoundary = 0;
-
-    /**
-     * Array of groups that are pre-processed for animation arrangement
-     */
-    groups: GroupInfo[] = [];
-
-    /**
-     * The number of index that a group's list is scrolled from its left edge.
-     * The zero, it is scrolled at the most left side, then increase index by 1
-     * on every scroll towards the end of content
-     */
-    scrollIndex = 0;
-
-    /**
-     * Number of groups that are being rendered in DOM. It represents the number
-     * of visible groups + extra edge items
-     */
-    groupsCount = 0;
-
-    constructor(grid: ControllableGrid, CONFIG: GridConfig) {
-        this.grid = grid;
-        this.animationConfiguration = this.grid.props.animation ? configureAnimation(
-            CONFIG.defaultAnimation, this.grid.props.animation,
-        ) : CONFIG.defaultAnimation;
-        const { scrollStep, visibleRows, visibleColumns } = this.grid.props;
-        const visibleGroups = visibleColumns || visibleRows || 0;
-        const { slowdownRatio = 0 } = this.animationConfiguration;
-        this.fastLinearScrollThreshold = scrollStep;
-        this.limitExtra = LIMIT_EXTRA;
-        this.leftBoundary = -(this.limitExtra / 2) - 1;
-        this.rightBoundary = -(this.limitExtra / 2) + 1;
-        this.groupsCount = visibleGroups + this.limitExtra;
-        this.groupOffsetStepPx = this.groupsCount * scrollStep;
-        this.maxAllowedScrollLength = scrollStep * (
-            visibleRows || visibleColumns || 0
-        ) * slowdownRatio;
-    }
-
-    componentDidMount() {
-        const grid = this.grid.base.current!;
-        this.groups = prepareAnimatedGroups(grid);
-        this.addScrollWrapFocusEvent();
-    }
-
-    componentWillUnmount() {
-        this.removeScrollWrapFocusEvent();
-    }
-
-    addScrollWrapFocusEvent() {
-        this.grid.base.current!.scroller.current!.wrapRef.current!
-            .addEventListener('focus', this.onFocusWrapper);
-    }
-
-    removeScrollWrapFocusEvent() {
-        this.grid.base.current!.scroller.current!.wrapRef.current!
-            .removeEventListener('focus', this.onFocusWrapper);
-    }
-
-    private readonly onFocusWrapper = () => {
-        this.focusCurrentItem();
-    };
-
-    private readonly 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.grid;
-        if (animate && scrollToPx === this.toPx) {
-            base.current!.animatedScrollFinished();
-        }
-        this.adjustGroupsOffsetsOnFrame(scrollToPx, backward);
-        this.handleOnScrollChanged(scrollToPx, backward);
-        this.scrollGridScroller(scrollToPx);
-        if (this.isScrollWrapFocused()) {
-            this.focusCurrentItem();
-        }
-    };
-
-    forward = () => {
-        const { continuousFocus } = this.grid.props;
-        const base = this.grid.base.current!;
-        const itemsInGroup = base.getItemsInGroup();
-        const isLastInGroup = (base.index % itemsInGroup) + 1 === itemsInGroup;
-        if (base.index < base.data.length - 1 && (!isLastInGroup || continuousFocus)) {
-            base.index += 1;
-            if (isLastInGroup) this.grid.scrollForward();
-            this.focusCurrentItem();
-            return true;
-        }
-        return false;
-    };
-
-    backward = () => {
-        const { continuousFocus } = this.grid.props;
-        const base = this.grid.base.current!;
-        const itemsInGroup = base.getItemsInGroup();
-        const isFirstInGroup = (base.index % itemsInGroup) === 0;
-        if (base.index > 0 && (!isFirstInGroup || continuousFocus)) {
-            base.index -= 1;
-            if (isFirstInGroup) this.grid.scrollBackward();
-            this.focusCurrentItem();
-            return true;
-        }
-        return false;
-    };
-
-    forwardGroup = () => {
-        const base = this.grid.base.current!;
-        const itemsInGroup = base.getItemsInGroup();
-        if (base.index < this.getMaxGroupIndex() * itemsInGroup) {
-            base.index += Math.min(base.data.length - base.index - 1, itemsInGroup);
-            this.grid.scrollForward();
-            this.focusCurrentItem();
-            return true;
-        }
-        return false;
-    };
-
-    backwardGroup = () => {
-        const base = this.grid.base.current!;
-        const itemsInGroup = base.getItemsInGroup();
-        if (base.index >= itemsInGroup) {
-            base.index -= Math.min(base.index, itemsInGroup);
-            this.grid.scrollBackward();
-            this.focusCurrentItem();
-            return true;
-        }
-        return false;
-    };
-
-    shouldApplySlowdown = () => (this.maxAllowedScrollLength
-        ? Math.abs(this.currentScrollPx - this.toPx) > this.maxAllowedScrollLength : false);
-
-    getMaxGroupIndex() {
-        const base = this.grid.base.current!;
-        const itemsInGroup = base.getItemsInGroup();
-        return Math.floor((base.data.length - 1) / itemsInGroup);
-    }
-
-    focusCurrentItem(options?: FocusOptions) {
-        const { props: { onFocusChanged } } = this.grid;
-        const base = this.grid.base.current!;
-        const index = this.getCurrentIndexInRefIndex();
-        const isFastFocusing = base.fastFocusingOptimizer.isRunning();
-        this.lastFocusOnNotProcessed = -1;
-        if (index === -1 || isFastFocusing) {
-            if (!this.isScrollWrapFocused()) {
-                this.focusScrollWrap();
-            }
-            if (index === -1
-                && !isFastFocusing
-                && !base.fastFocusingOptimizer.enabled) {
-                base.fastFocusingOptimizer.enabled = true;
-                this.focusOptimizing = true;
-            }
-            return;
-        }
-        if (this.focusOptimizing) {
-            this.focusOptimizing = false;
-            base.fastFocusingOptimizer.enabled = false;
-        }
-        const item = base.itemRefs[index];
-        if (!item) return;
-        item.current!.focus(options || { preventScroll: true });
-        onFocusChanged!(item, base.index);
-    }
-
-    focusToIndex(dataIndex: number, animate = false) {
-        const { grid } = this;
-        const base = grid.base.current!;
-        const targetScrollIndex = this.itemIndexToScrollIndex(dataIndex);
-        if (targetScrollIndex > this.scrollIndex) {
-            this.adjustGroupsOffsetsForward(targetScrollIndex);
-        } else if (targetScrollIndex < this.scrollIndex) {
-            this.adjustGroupsOffsetsBackward(targetScrollIndex);
-        }
-        if (targetScrollIndex !== this.scrollIndex) {
-            this.scroll(targetScrollIndex, animate);
-        }
-        base.index = dataIndex;
-        this.focusCurrentItem();
-        base.mrcuRef.current?.handleArrowState();
-    }
-
-    protected focusScrollWrap() {
-        this.grid.base.current!.scroller.current!.wrapRef.current!
-            .focus({ preventScroll: true });
-    }
-
-    protected isScrollWrapFocused() {
-        return this.grid.base.current!.scroller.current!.wrapRef.current === document.activeElement;
-    }
-
-    scroll(newScrollIndex: number, animate: boolean | undefined = this.grid.props.animate) {
-        if (newScrollIndex === this.scrollIndex) return;
-        if (Number.isNaN(this.initialScrollPx)) this.initialScrollPx = this.currentScrollPx;
-        this.fromPx = this.currentScrollPx;
-        this.toPx = this.scrollIndexToPixels(newScrollIndex);
-        if (animate) {
-            const { time, easing } = this.getEasingAndTime();
-            const { base } = this.grid;
-            base.current!.animatedScrollStarted();
-            this.animations
-                .start(this.fromPx, this.toPx, time, easing)
-                .onFrame(this.onFrame);
-        } else {
-            this.onFrame(this.toPx);
-        }
-        this.scrollIndex = newScrollIndex;
-    }
-
-    scrollGridScroller(scrollValuePx: number) {
-        this.grid.base.current!.scroller.current!.scroll(scrollValuePx);
-        this.currentScrollPx = scrollValuePx;
-    }
-
-    handleOnScrollChanged(scrollToPx: number, backward: boolean) {
-        const { onScrollChanged } = this.grid.props;
-        if (typeof onScrollChanged !== 'function') return;
-        const scrollFromStart = Math.abs(scrollToPx - this.initialScrollPx);
-        const scrollIndex = this.scrollPixelsToIndex(scrollFromStart, backward);
-        if (this.lastAnimationScrollIndex !== scrollIndex) {
-            const { base: { current: base } } = this.grid;
-            const itemsInGroup = base!.getItemsInGroup();
-            const indexOffset = Math.floor(base!.index / itemsInGroup) * itemsInGroup;
-            const indexInCurrentGroup = base!.index - indexOffset;
-            const indexInScrolledGroup = scrollIndex * itemsInGroup + indexInCurrentGroup;
-            const item = this.grid.base.current?.getRefAtDataIndex(indexInScrolledGroup);
-            this.lastAnimationScrollIndex = scrollIndex;
-            onScrollChanged(item!, scrollIndex);
-        }
-    }
-
-    protected getNextScrollConfig(valueToScrollToPx: number) {
-        const { currentScrollPx } = this;
-        const valueRounded = Math.round(valueToScrollToPx);
-        const backward = valueRounded < currentScrollPx;
-        const canScroll = valueRounded !== currentScrollPx;
-        return {
-            scrollToPx: valueRounded,
-            backward,
-            canScroll,
-        };
-    }
-
-    protected shouldReturnNormalAnimation(currentValue: number) {
-        if (!this.isFastLinearScroll) return false;
-        const { endRatio } = this.animationConfiguration.fastLinear!;
-        if (endRatio) {
-            const scrollLength = Math.abs(currentValue - this.toPx);
-            if (scrollLength < (this.fastLinearScrollThreshold * endRatio)) {
-                this.isFastLinearScroll = false;
-                return true;
-            }
-        } else if (currentValue === this.toPx) {
-            this.isFastLinearScroll = false;
-        }
-        return false;
-    }
-
-    protected getEasingAndTime() {
-        const { normal, fastLinear } = this.animationConfiguration;
-        if (!fastLinear) return normal;
-        const scrollLength = Math.abs(this.fromPx - this.toPx);
-        const { startRatio, time } = fastLinear;
-        if (scrollLength > this.fastLinearScrollThreshold * startRatio) {
-            this.isFastLinearScroll = true;
-            return {
-                easing: AnimationUtils.linear,
-                time,
-            };
-        }
-        this.isFastLinearScroll = false;
-        return normal;
-    }
-
-    /**
-     * Function will return index to item references in actual rendered items
-     * based on current grid index. If the current index is out of range, -1 is returned.
-     * @return {number} index of rendered item matching current list index
-     */
-    private readonly getCurrentIndexInRefIndex = () => {
-        const { groups } = this;
-        const base = this.grid.base.current!;
-        const currentIndex = base.index;
-        const itemsInGroup = base.getItemsInGroup();
-        const currentDataIndex = Math.floor(currentIndex / itemsInGroup);
-        const groupIndex = currentDataIndex % groups.length;
-        const groupDataIndex = currentDataIndex * itemsInGroup;
-        if (groupDataIndex === groups[groupIndex]?.dataIndex) {
-            return currentIndex % base.itemRefs.length;
-        }
-        return -1;
-    };
-
-    itemIndexToScrollIndex(itemIndex: number) {
-        const itemsInGroup = this.grid.base.current!.getItemsInGroup();
-        return Math.floor(itemIndex / itemsInGroup);
-    }
-
-    adjustGroupsOffsetsOnFrame(scrollValuePx: number, backward = false) {
-        let nextScrollIndex;
-        if (backward) {
-            nextScrollIndex = this.scrollPixelsToIndex(scrollValuePx, backward);
-            if (this.lastScrollIndex !== nextScrollIndex) {
-                this.adjustGroupsOffsetsBackward(nextScrollIndex);
-            }
-        } else {
-            nextScrollIndex = this.scrollPixelsToIndex(scrollValuePx, backward);
-            if (this.lastScrollIndex !== nextScrollIndex) {
-                this.adjustGroupsOffsetsForward(nextScrollIndex);
-            }
-        }
-        this.lastScrollIndex = nextScrollIndex;
-    }
-
-    adjustGroupsOffsetsForward(scrollIndex: number) {
-        const {
-            base: { current: base },
-        } = this.grid;
-        const { groupsCount, groupOffsetStepPx, groups } = this;
-        const itemsInGroup = base!.getItemsInGroup();
-        const dataOffsetStep = groupsCount * itemsInGroup;
-        forEach(groups, (group, index) => {
-            if (!this.shouldGroupRotateForward(group, scrollIndex)) return;
-            group.dataIndex += dataOffsetStep;
-            group.offset += groupOffsetStepPx;
-            this.updateItemsInGroup(group, index * itemsInGroup);
-        });
-    }
-
-    adjustGroupsOffsetsBackward(scrollIndex: number) {
-        const {
-            base: { current: base },
-        } = this.grid;
-        const { groupsCount, groupOffsetStepPx, groups } = this;
-        const itemsInGroup = base!.getItemsInGroup();
-        const dataOffsetStep = groupsCount * itemsInGroup;
-        forEach(groups, (group, index) => {
-            if (!this.shouldGroupRotateBackward(group, scrollIndex)) return;
-            group.dataIndex -= dataOffsetStep;
-            group.offset -= groupOffsetStepPx;
-            this.updateItemsInGroup(group, index * itemsInGroup);
-        });
-    }
-
-    protected shouldGroupRotateForward(group: GroupInfo, scrollIndex: number) {
-        const { base: { current: base } } = this.grid;
-        const itemsInGroup = base!.getItemsInGroup();
-        return group.dataIndex / itemsInGroup - scrollIndex < this.leftBoundary;
-    }
-
-    protected shouldGroupRotateBackward(group: GroupInfo, scrollIndex: number) {
-        const { base: { current: base } } = this.grid;
-        const itemsInGroup = base!.getItemsInGroup();
-        const visibleItems = base!.getVisibleGroups();
-        return group.dataIndex / itemsInGroup + this.rightBoundary > scrollIndex + visibleItems;
-    }
-
-    private updateItemsInGroup(group: GroupInfo, startItemIndex: number) {
-        const { base: { current: base }, props: { horizontal } } = this.grid;
-        const itemsInGroup = base!.getItemsInGroup();
-        for (let i = 0; i < itemsInGroup; i++) {
-            // group.dataIndex + i - (startItemIndex + i) explaining ↓
-            base!.updateItem(startItemIndex + i, group.dataIndex - startItemIndex);
-        }
-        offsetPosition(group.element, getOffsetObject(horizontal, group.offset));
-    }
-
-    scrollIndexToPixels(index: number) {
-        if (index === 0) return 0;
-        const { firstScrollStep, scrollStep } = this.grid.props;
-        if (typeof firstScrollStep === 'undefined') {
-            return scrollStep * index;
-        }
-        if (index === 1) return firstScrollStep;
-        return (index - 1) * scrollStep + firstScrollStep;
-    }
-
-    scrollPixelsToIndex(scrollValuePx: number, backward: boolean) {
-        const { scrollStep, firstScrollStep } = this.grid.props;
-        if (backward) {
-            return scrollPixelsToIndexBackward(scrollValuePx, scrollStep, firstScrollStep);
-        }
-        return scrollPixelsToIndexForward(scrollValuePx, scrollStep, firstScrollStep);
-    }
-
-    appendData(data: T[]) {
-        const base = this.grid.base.current!;
-        base.appendData(data);
-        if (this.groups.length < this.groupsCount) {
-            this.groups = prepareAnimatedGroups(base);
-        }
-        const itemsInGroup = base.getItemsInGroup();
-        forEach(this.groups, (group, index) => {
-            this.updateItemsInGroup(group, index * itemsInGroup);
-        });
-        base.mrcuRef.current?.handleArrowState();
-    }
-
-    prependData(data: T[]) {
-        const { scrollStep } = this.grid.props;
-        const base = this.grid.base.current!;
-        base.prependData(data);
-        if (this.groups.length < this.groupsCount) {
-            this.groups = prepareAnimatedGroups(base);
-        }
-        const dataLength = data.length;
-        base.index += dataLength;
-        const itemsInGroup = base.getItemsInGroup();
-        const prependedGroups = Math.floor(dataLength / itemsInGroup);
-        const offsetIndex = prependedGroups * itemsInGroup;
-        const offsetDiff = prependedGroups * scrollStep;
-        forEach(this.groups, (group, index) => {
-            group.dataIndex += offsetIndex;
-            group.offset += offsetDiff;
-            this.updateItemsInGroup(group, index * itemsInGroup);
-        });
-        this.scrollIndex += prependedGroups;
-        this.scrollGridScroller(
-            this.scrollIndexToPixels(this.scrollIndex),
-        );
-        this.focusCurrentItem();
-        base.mrcuRef.current?.handleArrowState();
-    }
-}
+import { AnimationUtils, JSAnimations } from '@24i/bigscreen-sdk/animations';
+import { forEach } from '@24i/bigscreen-sdk/perf-utils/array';
+import { offsetPosition } from '@24i/bigscreen-sdk/utils/offsetPosition';
+import {
+    configureAnimation,
+    getOffsetObject,
+    prepareAnimatedGroups,
+    scrollPixelsToIndexBackward,
+    scrollPixelsToIndexForward,
+} from '../utils';
+import { AnimationConfiguration, GroupInfo } from '../types';
+import {
+    ControllableGrid,
+    GridConfig,
+    UnifiedGridController as IUnifiedGridController,
+} from './interface';
+
+/**
+ * Number of rendered items above visibleItems (half on each side of the list)
+ * that could become visible during fast scroll animation
+ * If needed to be changed, keep it even
+ */
+const LIMIT_EXTRA = 2;
+
+export class UnifiedGridController<T> implements IUnifiedGridController<T> {
+    /**
+     * Grid that is controlled by this controller
+     */
+    protected grid: ControllableGrid;
+
+    /**
+     * Controls scroll animation that triggers position in px, on every frame.
+     */
+    private readonly animations = new JSAnimations();
+
+    /**
+     * Defines timelines/speeds configuration for scroll animation.
+     */
+    private readonly animationConfiguration: AnimationConfiguration;
+
+    /**
+     * The scroll index being captured on every animation frame. Derived from
+     * scroll position. It can differ to `scrollIndex` during animation run.
+     */
+    protected lastAnimationScrollIndex = 0;
+
+    /**
+     * Optimization to avoid unnecessary group adjustments if scrollIndex remains the same.
+     * It can differ to `scrollIndex` during animation run.
+     */
+    protected lastScrollIndex = 0;
+
+    /**
+     * The number of pixels, that grid content is starting scroll animation at
+     * (from its left edge (LTR layout)).
+     */
+    private fromPx = 0;
+
+    /**
+     * The number of pixels, that grid content is ending scroll animation at
+     * (from its left edge (LTR layout)).
+     */
+    private toPx = 0;
+
+    /**
+     * The current value represents grid scroll in pixels
+     * Initial value is 0, if its different, please set before first scroll
+     */
+    protected currentScrollPx = 0;
+
+    /**
+     * Number which determines, when linear scroll switch start or end. Number should be
+     * size of one item (scrollStep), or average item size in case of multiple sizes
+     */
+    protected fastLinearScrollThreshold = 0;
+
+    /**
+     * Flag, if list scrolling is currently fast linear
+     */
+    protected isFastLinearScroll = false;
+
+    /**
+     * Maximum scroll length for determine if list can scroll further.
+     * If the value is 0, scroll is not limited
+     */
+    protected maxAllowedScrollLength = 0;
+
+    /**
+     * The first number where the list is scrolled on the start. The default value is NaN
+     * because it is assigned during the first scrolling.
+     */
+    protected initialScrollPx = NaN;
+
+    /**
+     * Flag, if list focus optimizing is running (when full fast focus optimization is disabled)
+     */
+    protected focusOptimizing = false;
+
+    /* Last focused index when grid is fully scrolled and forwardGroup/backwardGroup
+     * was not processed, but animation has not finished yet
+     */
+    protected lastFocusOnNotProcessed = -1;
+
+    /**
+     * Number of pixels for offsetting (cycle-shifting) rendered groups
+     */
+    protected groupOffsetStepPx = 0;
+
+    /**
+     * Number of rendered groups above visibleGroups
+     */
+    protected limitExtra = 0;
+
+    /**
+     * Moving below 0 by a half of LIMIT_EXTRA and 2 for index/length diff and 1 partially visible
+     */
+    protected leftBoundary = 0;
+
+    /**
+     * Moving above highest index by a half of LIMIT_EXTRA and 1 for partially visible
+     * index/length diff of 1 is not needed here
+     */
+    protected rightBoundary = 0;
+
+    /**
+     * Array of groups that are pre-processed for animation arrangement
+     */
+    groups: GroupInfo[] = [];
+
+    /**
+     * The number of index that a group's list is scrolled from its left edge.
+     * The zero, it is scrolled at the most left side, then increase index by 1
+     * on every scroll towards the end of content
+     */
+    scrollIndex = 0;
+
+    /**
+     * Number of groups that are being rendered in DOM. It represents the number
+     * of visible groups + extra edge items
+     */
+    groupsCount = 0;
+
+    constructor(grid: ControllableGrid, CONFIG: GridConfig) {
+        this.grid = grid;
+        this.animationConfiguration = this.grid.props.animation ? configureAnimation(
+            CONFIG.defaultAnimation, this.grid.props.animation,
+        ) : CONFIG.defaultAnimation;
+        const { scrollStep, visibleRows, visibleColumns } = this.grid.props;
+        const visibleGroups = visibleColumns || visibleRows || 0;
+        const { slowdownRatio = 0 } = this.animationConfiguration;
+        this.fastLinearScrollThreshold = scrollStep;
+        this.limitExtra = LIMIT_EXTRA;
+        this.leftBoundary = -(this.limitExtra / 2) - 1;
+        this.rightBoundary = -(this.limitExtra / 2) + 1;
+        this.groupsCount = visibleGroups + this.limitExtra;
+        this.groupOffsetStepPx = this.groupsCount * scrollStep;
+        this.maxAllowedScrollLength = scrollStep * (
+            visibleRows || visibleColumns || 0
+        ) * slowdownRatio;
+    }
+
+    componentDidMount() {
+        const grid = this.grid.base.current!;
+        this.groups = prepareAnimatedGroups(grid);
+        this.addScrollWrapFocusEvent();
+    }
+
+    componentWillUnmount() {
+        this.removeScrollWrapFocusEvent();
+    }
+
+    addScrollWrapFocusEvent() {
+        this.grid.base.current!.scroller.current!.wrapRef.current!
+            .addEventListener('focus', this.onFocusWrapper);
+    }
+
+    removeScrollWrapFocusEvent() {
+        this.grid.base.current!.scroller.current!.wrapRef.current!
+            .removeEventListener('focus', this.onFocusWrapper);
+    }
+
+    private readonly onFocusWrapper = () => {
+        this.focusCurrentItem();
+    };
+
+    private readonly 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.grid;
+        if (animate && scrollToPx === this.toPx) {
+            base.current!.animatedScrollFinished();
+        }
+        this.adjustGroupsOffsetsOnFrame(scrollToPx, backward);
+        this.handleOnScrollChanged(scrollToPx, backward);
+        this.scrollGridScroller(scrollToPx);
+        if (this.isScrollWrapFocused()) {
+            this.focusCurrentItem();
+        }
+    };
+
+    forward = () => {
+        const { continuousFocus } = this.grid.props;
+        const base = this.grid.base.current!;
+        const itemsInGroup = base.getItemsInGroup();
+        const isLastInGroup = (base.index % itemsInGroup) + 1 === itemsInGroup;
+        if (base.index < base.data.length - 1 && (!isLastInGroup || continuousFocus)) {
+            base.index += 1;
+            if (isLastInGroup) this.grid.scrollForward();
+            this.focusCurrentItem();
+            return true;
+        }
+        return false;
+    };
+
+    backward = () => {
+        const { continuousFocus } = this.grid.props;
+        const base = this.grid.base.current!;
+        const itemsInGroup = base.getItemsInGroup();
+        const isFirstInGroup = (base.index % itemsInGroup) === 0;
+        if (base.index > 0 && (!isFirstInGroup || continuousFocus)) {
+            base.index -= 1;
+            if (isFirstInGroup) this.grid.scrollBackward();
+            this.focusCurrentItem();
+            return true;
+        }
+        return false;
+    };
+
+    forwardGroup = () => {
+        const base = this.grid.base.current!;
+        const itemsInGroup = base.getItemsInGroup();
+        if (base.index < this.getMaxGroupIndex() * itemsInGroup) {
+            base.index += Math.min(base.data.length - base.index - 1, itemsInGroup);
+            this.grid.scrollForward();
+            this.focusCurrentItem();
+            return true;
+        }
+        return false;
+    };
+
+    backwardGroup = () => {
+        const base = this.grid.base.current!;
+        const itemsInGroup = base.getItemsInGroup();
+        if (base.index >= itemsInGroup) {
+            base.index -= Math.min(base.index, itemsInGroup);
+            this.grid.scrollBackward();
+            this.focusCurrentItem();
+            return true;
+        }
+        return false;
+    };
+
+    shouldApplySlowdown = () => (this.maxAllowedScrollLength
+        ? Math.abs(this.currentScrollPx - this.toPx) > this.maxAllowedScrollLength : false);
+
+    getMaxGroupIndex() {
+        const base = this.grid.base.current!;
+        const itemsInGroup = base.getItemsInGroup();
+        return Math.floor((base.data.length - 1) / itemsInGroup);
+    }
+
+    focusCurrentItem(options?: FocusOptions) {
+        const { props: { onFocusChanged } } = this.grid;
+        const base = this.grid.base.current!;
+        const index = this.getCurrentIndexInRefIndex();
+        const isFastFocusing = base.fastFocusingOptimizer.isRunning();
+        this.lastFocusOnNotProcessed = -1;
+        if (index === -1 || isFastFocusing) {
+            if (!this.isScrollWrapFocused()) {
+                this.focusScrollWrap();
+            }
+            if (index === -1
+                && !isFastFocusing
+                && !base.fastFocusingOptimizer.enabled) {
+                base.fastFocusingOptimizer.enabled = true;
+                this.focusOptimizing = true;
+            }
+            return;
+        }
+        if (this.focusOptimizing) {
+            this.focusOptimizing = false;
+            base.fastFocusingOptimizer.enabled = false;
+        }
+        const item = base.itemRefs[index];
+        if (!item) return;
+        item.current!.focus(options || { preventScroll: true });
+        onFocusChanged!(item, base.index);
+    }
+
+    focusToIndex(dataIndex: number, animate = false) {
+        const { grid } = this;
+        const base = grid.base.current!;
+        const targetScrollIndex = this.itemIndexToScrollIndex(dataIndex);
+        if (targetScrollIndex > this.scrollIndex) {
+            this.adjustGroupsOffsetsForward(targetScrollIndex);
+        } else if (targetScrollIndex < this.scrollIndex) {
+            this.adjustGroupsOffsetsBackward(targetScrollIndex);
+        }
+        if (targetScrollIndex !== this.scrollIndex) {
+            this.scroll(targetScrollIndex, animate);
+        }
+        base.index = dataIndex;
+        this.focusCurrentItem();
+        base.mrcuRef.current?.handleArrowState();
+    }
+
+    protected focusScrollWrap() {
+        this.grid.base.current!.scroller.current!.wrapRef.current!
+            .focus({ preventScroll: true });
+    }
+
+    protected isScrollWrapFocused() {
+        return this.grid.base.current!.scroller.current!.wrapRef.current === document.activeElement;
+    }
+
+    scroll(newScrollIndex: number, animate: boolean | undefined = this.grid.props.animate) {
+        if (newScrollIndex === this.scrollIndex) return;
+        if (Number.isNaN(this.initialScrollPx)) this.initialScrollPx = this.currentScrollPx;
+        this.fromPx = this.currentScrollPx;
+        this.toPx = this.scrollIndexToPixels(newScrollIndex);
+        if (animate) {
+            const { time, easing } = this.getEasingAndTime();
+            const { base } = this.grid;
+            base.current!.animatedScrollStarted();
+            this.animations
+                .start(this.fromPx, this.toPx, time, easing)
+                .onFrame(this.onFrame);
+        } else {
+            this.onFrame(this.toPx);
+        }
+        this.scrollIndex = newScrollIndex;
+    }
+
+    scrollGridScroller(scrollValuePx: number) {
+        this.grid.base.current!.scroller.current!.scroll(scrollValuePx);
+        this.currentScrollPx = scrollValuePx;
+    }
+
+    handleOnScrollChanged(scrollToPx: number, backward: boolean) {
+        const { onScrollChanged } = this.grid.props;
+        if (typeof onScrollChanged !== 'function') return;
+        const scrollFromStart = Math.abs(scrollToPx - this.initialScrollPx);
+        const scrollIndex = this.scrollPixelsToIndex(scrollFromStart, backward);
+        if (this.lastAnimationScrollIndex !== scrollIndex) {
+            const { base: { current: base } } = this.grid;
+            const itemsInGroup = base!.getItemsInGroup();
+            const indexOffset = Math.floor(base!.index / itemsInGroup) * itemsInGroup;
+            const indexInCurrentGroup = base!.index - indexOffset;
+            const indexInScrolledGroup = scrollIndex * itemsInGroup + indexInCurrentGroup;
+            const item = this.grid.base.current?.getRefAtDataIndex(indexInScrolledGroup);
+            this.lastAnimationScrollIndex = scrollIndex;
+            onScrollChanged(item!, scrollIndex);
+        }
+    }
+
+    protected getNextScrollConfig(valueToScrollToPx: number) {
+        const { currentScrollPx } = this;
+        const valueRounded = Math.round(valueToScrollToPx);
+        const backward = valueRounded < currentScrollPx;
+        const canScroll = valueRounded !== currentScrollPx;
+        return {
+            scrollToPx: valueRounded,
+            backward,
+            canScroll,
+        };
+    }
+
+    protected shouldReturnNormalAnimation(currentValue: number) {
+        if (!this.isFastLinearScroll) return false;
+        const { endRatio } = this.animationConfiguration.fastLinear!;
+        if (endRatio) {
+            const scrollLength = Math.abs(currentValue - this.toPx);
+            if (scrollLength < (this.fastLinearScrollThreshold * endRatio)) {
+                this.isFastLinearScroll = false;
+                return true;
+            }
+        } else if (currentValue === this.toPx) {
+            this.isFastLinearScroll = false;
+        }
+        return false;
+    }
+
+    protected getEasingAndTime() {
+        const { normal, fastLinear } = this.animationConfiguration;
+        if (!fastLinear) return normal;
+        const scrollLength = Math.abs(this.fromPx - this.toPx);
+        const { startRatio, time } = fastLinear;
+        if (scrollLength > this.fastLinearScrollThreshold * startRatio) {
+            this.isFastLinearScroll = true;
+            return {
+                easing: AnimationUtils.linear,
+                time,
+            };
+        }
+        this.isFastLinearScroll = false;
+        return normal;
+    }
+
+    /**
+     * Function will return index to item references in actual rendered items
+     * based on current grid index. If the current index is out of range, -1 is returned.
+     * @return {number} index of rendered item matching current list index
+     */
+    private readonly getCurrentIndexInRefIndex = () => {
+        const { groups } = this;
+        const base = this.grid.base.current!;
+        const currentIndex = base.index;
+        const itemsInGroup = base.getItemsInGroup();
+        const currentDataIndex = Math.floor(currentIndex / itemsInGroup);
+        const groupIndex = currentDataIndex % groups.length;
+        const groupDataIndex = currentDataIndex * itemsInGroup;
+        if (groupDataIndex === groups[groupIndex]?.dataIndex) {
+            return currentIndex % base.itemRefs.length;
+        }
+        return -1;
+    };
+
+    itemIndexToScrollIndex(itemIndex: number) {
+        const itemsInGroup = this.grid.base.current!.getItemsInGroup();
+        return Math.floor(itemIndex / itemsInGroup);
+    }
+
+    adjustGroupsOffsetsOnFrame(scrollValuePx: number, backward = false) {
+        let nextScrollIndex;
+        if (backward) {
+            nextScrollIndex = this.scrollPixelsToIndex(scrollValuePx, backward);
+            if (this.lastScrollIndex !== nextScrollIndex) {
+                this.adjustGroupsOffsetsBackward(nextScrollIndex);
+            }
+        } else {
+            nextScrollIndex = this.scrollPixelsToIndex(scrollValuePx, backward);
+            if (this.lastScrollIndex !== nextScrollIndex) {
+                this.adjustGroupsOffsetsForward(nextScrollIndex);
+            }
+        }
+        this.lastScrollIndex = nextScrollIndex;
+    }
+
+    adjustGroupsOffsetsForward(scrollIndex: number) {
+        const {
+            base: { current: base },
+        } = this.grid;
+        const { groupsCount, groupOffsetStepPx, groups } = this;
+        const itemsInGroup = base!.getItemsInGroup();
+        const dataOffsetStep = groupsCount * itemsInGroup;
+        forEach(groups, (group, index) => {
+            if (!this.shouldGroupRotateForward(group, scrollIndex)) return;
+            group.dataIndex += dataOffsetStep;
+            group.offset += groupOffsetStepPx;
+            this.updateItemsInGroup(group, index * itemsInGroup);
+        });
+    }
+
+    adjustGroupsOffsetsBackward(scrollIndex: number) {
+        const {
+            base: { current: base },
+        } = this.grid;
+        const { groupsCount, groupOffsetStepPx, groups } = this;
+        const itemsInGroup = base!.getItemsInGroup();
+        const dataOffsetStep = groupsCount * itemsInGroup;
+        forEach(groups, (group, index) => {
+            if (!this.shouldGroupRotateBackward(group, scrollIndex)) return;
+            group.dataIndex -= dataOffsetStep;
+            group.offset -= groupOffsetStepPx;
+            this.updateItemsInGroup(group, index * itemsInGroup);
+        });
+    }
+
+    protected shouldGroupRotateForward(group: GroupInfo, scrollIndex: number) {
+        const { base: { current: base } } = this.grid;
+        const itemsInGroup = base!.getItemsInGroup();
+        return group.dataIndex / itemsInGroup - scrollIndex < this.leftBoundary;
+    }
+
+    protected shouldGroupRotateBackward(group: GroupInfo, scrollIndex: number) {
+        const { base: { current: base } } = this.grid;
+        const itemsInGroup = base!.getItemsInGroup();
+        const visibleItems = base!.getVisibleGroups();
+        return group.dataIndex / itemsInGroup + this.rightBoundary > scrollIndex + visibleItems;
+    }
+
+    private updateItemsInGroup(group: GroupInfo, startItemIndex: number) {
+        const { base: { current: base }, props: { horizontal } } = this.grid;
+        const itemsInGroup = base!.getItemsInGroup();
+        for (let i = 0; i < itemsInGroup; i++) {
+            // group.dataIndex + i - (startItemIndex + i) explaining ↓
+            base!.updateItem(startItemIndex + i, group.dataIndex - startItemIndex);
+        }
+        offsetPosition(group.element, getOffsetObject(horizontal, group.offset));
+    }
+
+    scrollIndexToPixels(index: number) {
+        if (index === 0) return 0;
+        const { firstScrollStep, scrollStep } = this.grid.props;
+        if (typeof firstScrollStep === 'undefined') {
+            return scrollStep * index;
+        }
+        if (index === 1) return firstScrollStep;
+        return (index - 1) * scrollStep + firstScrollStep;
+    }
+
+    scrollPixelsToIndex(scrollValuePx: number, backward: boolean) {
+        const { scrollStep, firstScrollStep } = this.grid.props;
+        if (backward) {
+            return scrollPixelsToIndexBackward(scrollValuePx, scrollStep, firstScrollStep);
+        }
+        return scrollPixelsToIndexForward(scrollValuePx, scrollStep, firstScrollStep);
+    }
+
+    appendData(data: T[]) {
+        const base = this.grid.base.current!;
+        base.appendData(data);
+        if (this.groups.length < this.groupsCount) {
+            this.groups = prepareAnimatedGroups(base);
+        }
+        const itemsInGroup = base.getItemsInGroup();
+        forEach(this.groups, (group, index) => {
+            this.updateItemsInGroup(group, index * itemsInGroup);
+        });
+        base.mrcuRef.current?.handleArrowState();
+    }
+
+    prependData(data: T[]) {
+        const { scrollStep } = this.grid.props;
+        const base = this.grid.base.current!;
+        base.prependData(data);
+        if (this.groups.length < this.groupsCount) {
+            this.groups = prepareAnimatedGroups(base);
+        }
+        const dataLength = data.length;
+        base.index += dataLength;
+        const itemsInGroup = base.getItemsInGroup();
+        const prependedGroups = Math.floor(dataLength / itemsInGroup);
+        const offsetIndex = prependedGroups * itemsInGroup;
+        const offsetDiff = prependedGroups * scrollStep;
+        forEach(this.groups, (group, index) => {
+            group.dataIndex += offsetIndex;
+            group.offset += offsetDiff;
+            this.updateItemsInGroup(group, index * itemsInGroup);
+        });
+        this.scrollIndex += prependedGroups;
+        this.scrollGridScroller(
+            this.scrollIndexToPixels(this.scrollIndex),
+        );
+        this.focusCurrentItem();
+        base.mrcuRef.current?.handleArrowState();
+    }
+}