@24i/bigscreen-sdk 1.0.54-alpha.2836 → 1.0.54-alpha.2838

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@24i/bigscreen-sdk",
-    "version": "1.0.54-alpha.2836",
+    "version": "1.0.54-alpha.2838",
     "description": "SmartApps BIGscreen SDK monorepo",
     "main": "index.js",
     "scripts": {
@@ -193,6 +193,7 @@
         "./l10n": "./packages/l10n/src/index.ts",
         "./list/AttachDetachItem": "./packages/list/AttachDetachItem/index.ts",
         "./list/Basic": "./packages/list/BasicList/index.ts",
+        "./list/Double": "./packages/list/DoubleList/index.ts",
         "./list/Basic/static": "./packages/list/BasicList/static.ts",
         "./list/Centered": "./packages/list/CenteredList/index.ts",
         "./list/Centered/static": "./packages/list/CenteredList/static.ts",

package/packages/list/DoubleList/README.md

@@ -0,0 +1,105 @@
+---
+id: README
+title: DoubleList
+hide_title: true
+sidebar_label: DoubleList
+---
+
+# DoubleList
+
+`DoubleList` renders a dataset into two synchronized rows (TOP and BOTTOM) for big-screen navigation.
+
+Internally it splits the original `data` into:
+- TOP row: items from original indices `0, 2, 4, ...`
+- BOTTOM row: items from original indices `1, 3, 5, ...`
+
+## List Specific Props
+- `firstScrollStep` - value in pixels to move on the first scroll
+- `scrollStep` - value to move on other scrolls (should be equal to item width + its spacing)
+- `rowClassName` - CSS class applied to each row
+- `animation` - animation configuration overrides
+
+## Default Animation Configuration
+- normal: 700ms with easeOutQuart
+
+## Usage
+
+```tsx
+import { createRef } from '@24i/bigscreen-sdk/jsx';
+import { DoubleList } from '@24i/bigscreen-sdk/list/DoubleList';
+
+type Item = { id: string; title: string };
+
+const listRef = createRef<DoubleList<any, Item>>();
+
+export const Example = ({ items }: { items: Item[] }) => (
+    <DoubleList<any, Item>
+        ref={listRef as any}
+        data={items}
+        visibleItems={6}
+        firstScrollStep={50}
+        scrollStep={100}
+        animate={true}
+        renderItem={(item, columnIndex, ref) => (
+            <div ref={ref as any} className="card">
+                {item.title}
+            </div>
+        )}
+        onFocusChanged={(ref, columnIndex) => {
+            // `columnIndex` is row-local (column within the active row).
+            //
+            // To access the component-tracked absolute index, read it from the instance:
+            const absoluteIndex = (listRef.current as any)?.absoluteIndex;
+            // Use `absoluteIndex` for analytics/selection.
+        }}
+    />
+);
+```
+
+### onFocusChanged
+
+`onFocusChanged(itemRef, index)` receives:
+- `itemRef`: reference to the focused item
+- `index`: **row-local index** (column index within the focused row)
+
+> `DoubleList` tracks an internal `absoluteIndex` value, but it is **not** passed as the callback argument.
+> Read it from the `DoubleList` instance (via `ref`) after focus updates.
+
+## Indices
+
+### Column index (row-local)
+
+Used by:
+- `renderItem(item, columnIndex, ref)`
+- `onFocusChanged(ref, columnIndex)`
+
+### Absolute index (tracked by the component)
+
+`DoubleList` maintains `absoluteIndex` to represent the position in the original `data[]`.
+
+To consume it externally:
+- keep a ref to the component
+- read `ref.current.absoluteIndex` after focus updates
+
+---
+
+## Instance methods (ref API)
+
+`DoubleList` implements `DoubleRowList<T, U>`:
+
+- `appendData(data: U[]): void`
+- `prependData(data: U[]): void`
+- `scrollTo(index: number, animate?: boolean): void`
+- `focus(options?: FocusOptions): void`
+
+Example:
+
+```tsx
+listRef.current?.scrollTo(10, true);
+listRef.current?.focus();
+```
+
+## Notes
+
+- If `data.length` is odd, TOP row will contain one more item than BOTTOM row.
+- For external analytics/selection logic that needs original `data[]` positions, use the component’s tracked `absoluteIndex` via `ref`.

package/packages/list/DoubleList/index.ts

@@ -0,0 +1 @@
+export { DoubleList } from '../src/DoubleList/DoubleList';

package/packages/list/src/DoubleList/DoubleList.tsx

@@ -0,0 +1,267 @@
+import { Component, DeclareProps } from '@24i/bigscreen-sdk/jsx';
+import { noop } from '@24i/bigscreen-sdk/utils/noop';
+import { device } from '@24i/bigscreen-sdk/device';
+import { ListBase } from '../Base';
+import { RowType, DirectionType, DIRECTION, ROW, DoubleRowList, Props } from './interface';
+import { Item } from '../types';
+import { DoubleListAdapter } from './DoubleListAdapter';
+import { CONFIG, VISIBLE_ITEMS_OFFSET } from './config';
+
+export class DoubleList<T extends Item<U>, U>
+    extends Component<Props<T, U>> implements DoubleRowList<T, U> {
+    /*
+     * Adapter managing the two row lists and their controllers
+    */
+    adapter: DoubleListAdapter<T, U>;
+
+    /**
+     * Track which row is currently active
+    */
+    currentRow: RowType = ROW.TOP;
+
+    /**
+     * Track column position for vertical navigation
+    */
+    columnIndex = 0;
+
+    /**
+     * Track absolute index for onFocusChanged callback
+     */
+    absoluteIndex: number | null = -1;
+
+    static defaultProps = {
+        animation: CONFIG.defaultAnimation,
+        // eslint-disable-next-line react/default-props-match-prop-types
+        horizontal: true,
+        // eslint-disable-next-line react/default-props-match-prop-types
+        onFocusChanged: noop,
+        // eslint-disable-next-line react/default-props-match-prop-types
+        animate: CONFIG.animate,
+    };
+
+    declare props: DeclareProps<Props<T, U>, typeof DoubleList.defaultProps>;
+
+    constructor(props: Props<T, U>) {
+        super(props);
+        this.adapter = new DoubleListAdapter<T, U>(props);
+    }
+
+    componentDidMount(): void {
+        this.adapter.mount();
+        this.absoluteIndex = -1;
+    }
+
+    componentWillUnmount(): void {
+        this.adapter.unmount();
+        this.absoluteIndex = null;
+    }
+
+    /**
+     * Private helper: Switch between rows at the same column
+     * @param targetRow - The row to switch to (ROW.TOP or ROW.BOTTOM)
+     */
+    private switchToRow = (targetRow: RowType): boolean => {
+        const { data } = this.props;
+        const targetAbsoluteIndex = this.adapter.getAbsoluteIndex(targetRow, this.columnIndex);
+
+        // Check if target item exists in data
+        if (targetAbsoluteIndex >= data.length) {
+            return false;
+        }
+
+        const targetList = this.adapter.getList(targetRow);
+        const targetController = this.adapter.getController(targetRow);
+
+        if (!targetList) {
+            return false;
+        }
+        targetList.setIndex(this.columnIndex);
+        this.currentRow = targetRow;
+        this.absoluteIndex = targetAbsoluteIndex;
+
+        targetController.focusCurrentItem();
+        return true;
+    };
+
+    /**
+     * Private helper: Handle DOWN key navigation
+     * @param event - The keyboard event
+     */
+    private handleDownKey = (event: KeyboardEvent): boolean => {
+        if (this.currentRow !== ROW.TOP) {
+            return false;
+        }
+
+        const switched = this.switchToRow(ROW.BOTTOM);
+        if (switched) {
+            event.preventDefault();
+            event.stopPropagation();
+        }
+        return switched;
+    };
+
+    /**
+     * Private helper: Handle UP key navigation
+     * @param event - The keyboard event
+     */
+    private handleUpKey = (event: KeyboardEvent): boolean => {
+        if (this.currentRow !== ROW.BOTTOM) {
+            return false;
+        }
+
+        const switched = this.switchToRow(ROW.TOP);
+        if (switched) {
+            event.preventDefault();
+            event.stopPropagation();
+        }
+        return switched;
+    };
+
+    /**
+     * Handle keyboard events
+     * Intercepts UP/DOWN keys for vertical navigation
+     * Delegates LEFT/RIGHT keys to forward/backward handlers
+     * @param event - The keyboard event
+     */
+    handleKeyDown = (event: KeyboardEvent): boolean => {
+        const { horizontal } = this.props;
+        if (!horizontal) return false;
+        if (device.isDirectionDown(event)) return this.handleDownKey(event);
+        if (device.isDirectionUp(event)) return this.handleUpKey(event);
+        return false;
+    };
+
+    /**
+     * Handle LEFT/RIGHT navigation
+     * @param direction
+     * @returns boolean - whether the move was successful
+     */
+    move = (direction: DirectionType): boolean => {
+        const { visibleItems, firstScrollStep, scrollStep } = this.props;
+        const { controller, list } = this.adapter.getActiveRow(this.currentRow);
+        const { controller: inactiveController } = this.adapter.getInactiveRow(this.currentRow);
+        const currentList = list.current;
+
+        if (!currentList) return false;
+
+        const delta = direction === DIRECTION.FORWARD ? 1 : -1;
+        const nextIndex = currentList.index + delta;
+        if (nextIndex < 0 || nextIndex > currentList.data.length - 1) return false;
+
+        currentList.index = nextIndex;
+
+        if (delta > 0) {
+            const scrollTargetIndex = currentList.index - visibleItems + VISIBLE_ITEMS_OFFSET;
+            if (scrollTargetIndex > controller.scrollIndex) {
+                controller.scroll(scrollTargetIndex);
+                inactiveController.scroll(scrollTargetIndex);
+            }
+        } else {
+            const offset = firstScrollStep < scrollStep ? 1 : 0;
+            if (currentList.index - offset < controller.scrollIndex) {
+                controller.scroll(currentList.index);
+                inactiveController.scroll(currentList.index);
+            }
+        }
+
+        this.columnIndex = currentList.index;
+        this.absoluteIndex = this.adapter.getAbsoluteIndex(this.currentRow, this.columnIndex);
+        controller.focusCurrentItem();
+        return true;
+    };
+
+    forward = (): boolean => this.move(DIRECTION.FORWARD);
+
+    backward = (): boolean => this.move(DIRECTION.BACKWARD);
+
+    appendData = (data: U[]): void => this.adapter.appendData(data);
+
+    prependData = (data: U[]): void => this.adapter.prependData(data);
+
+    focus(options?: FocusOptions) {
+        const { controller } = this.adapter.getActiveRow(this.currentRow);
+        this.absoluteIndex = this.adapter.getAbsoluteIndex(this.currentRow, this.columnIndex);
+        controller.focusCurrentItem(options);
+    }
+
+    scrollTo(index: number, animate?: boolean): void {
+        const { data, visibleItems, firstScrollStep, scrollStep } = this.props;
+
+        const safeIndex = Math.max(0, Math.min(index, data.length - 1));
+        const targetRow = (safeIndex % 2 === 0) ? ROW.TOP : ROW.BOTTOM;
+        const targetColumnIndex = Math.floor(safeIndex / 2);
+
+        // Keep internal state consistent with requested target.
+        this.currentRow = targetRow;
+        this.columnIndex = targetColumnIndex;
+        this.absoluteIndex = safeIndex;
+
+        const { topRowList, bottomRowList } = this.adapter;
+        const topList = topRowList.current;
+        const bottomList = bottomRowList.current;
+
+        if (!topList || !bottomList) return;
+
+        // Keep both row indices aligned so switching rows preserves column.
+        topRowList.setIndex(Math.min(targetColumnIndex, Math.max(0, topList.data.length - 1)));
+        const bottomMaxIndex = Math.max(0, bottomList.data.length - 1);
+        bottomRowList.setIndex(Math.min(targetColumnIndex, bottomMaxIndex));
+
+        const targetController = this.adapter.getController(targetRow);
+
+        // Scroll both controllers in sync using the same logic as forward/backward.
+        const offset = firstScrollStep < scrollStep ? 1 : 0;
+        if (targetColumnIndex >= targetController.scrollIndex) {
+            const scrollTargetIndex = targetColumnIndex - visibleItems + VISIBLE_ITEMS_OFFSET;
+            if (scrollTargetIndex > targetController.scrollIndex) {
+                topRowList.controller.scroll(scrollTargetIndex, animate);
+                bottomRowList.controller.scroll(scrollTargetIndex, animate);
+            }
+        } else if (targetColumnIndex - offset < targetController.scrollIndex) {
+            topRowList.controller.scroll(targetColumnIndex, animate);
+            bottomRowList.controller.scroll(targetColumnIndex, animate);
+        }
+        targetController.focusCurrentItem();
+    }
+
+    render() {
+        const {
+            data,
+            className,
+            rowClassName,
+            renderItem,
+            visibleItems,
+            horizontal,
+        } = this.props;
+        const { topData, bottomData } = this.adapter.splitData(data);
+        const { topRowList, bottomRowList } = this.adapter;
+        return (
+            <div className={className} onKeyDown={this.handleKeyDown}>
+                <ListBase
+                    ref={topRowList.base}
+                    data={topData}
+                    renderItem={renderItem}
+                    visibleItems={visibleItems}
+                    forward={this.forward}
+                    backward={this.backward}
+                    shouldApplySlowdown={topRowList.controller.shouldApplySlowdown}
+                    className={rowClassName}
+                    horizontal={horizontal}
+                    limit={topRowList.controller.itemsCount}
+                />
+                <ListBase
+                    ref={bottomRowList.base}
+                    data={bottomData}
+                    renderItem={renderItem}
+                    visibleItems={visibleItems}
+                    forward={this.forward}
+                    backward={this.backward}
+                    shouldApplySlowdown={bottomRowList.controller.shouldApplySlowdown}
+                    className={rowClassName}
+                    horizontal={horizontal}
+                    limit={bottomRowList.controller.itemsCount}
+                />
+            </div>
+        );
+    }
+}

package/packages/list/src/DoubleList/DoubleListAdapter.ts

@@ -0,0 +1,72 @@
+import { createRef } from '@24i/bigscreen-sdk/jsx';
+import { ListBase } from '../Base';
+import { UnifiedListController } from '../UnifiedListController/UnifiedListController';
+import { RowList, RowType, ROW, Props } from './interface';
+import { Item } from '../types';
+
+/*
+  * DoubleListAdapter class to manage two RowList instances
+*/
+export class DoubleListAdapter<T extends Item<U>, U> {
+    readonly topRowList: RowList<T, U>;
+
+    readonly bottomRowList: RowList<T, U>;
+
+    constructor(props: Props<T, U>) {
+        this.topRowList = new RowList<T, U>(createRef<ListBase<T, U>>(), props);
+        this.bottomRowList = new RowList<T, U>(createRef<ListBase<T, U>>(), props);
+    }
+
+    mount(): void {
+        this.topRowList.controller.componentDidMount();
+        this.bottomRowList.controller.componentDidMount();
+    }
+
+    unmount(): void {
+        this.topRowList.controller.componentWillUnmount();
+        this.bottomRowList.controller.componentWillUnmount();
+    }
+
+    splitData = (data: U[]): { topData: U[]; bottomData: U[] } => {
+        const topData: U[] = [];
+        const bottomData: U[] = [];
+        data.forEach((item, index) => ((index % 2 === 0) ? topData : bottomData).push(item));
+        return { topData, bottomData };
+    };
+
+    appendData(data: U[]): void {
+        const { topData, bottomData } = this.splitData(data);
+        this.topRowList.appendData(topData);
+        this.bottomRowList.appendData(bottomData);
+    }
+
+    getAbsoluteIndex = (row: RowType, columnIndex: number): number => (
+        row === ROW.TOP ? columnIndex * 2 : (columnIndex * 2) + 1
+    );
+
+    prependData(data: U[]): void {
+        const { topData, bottomData } = this.splitData(data);
+        this.topRowList.prependData(topData);
+        this.bottomRowList.prependData(bottomData);
+    }
+
+    getController(row: RowType): UnifiedListController<U> {
+        return row === ROW.TOP ? this.topRowList.controller : this.bottomRowList.controller;
+    }
+
+    getList(row: RowType): RowList<T, U> {
+        return row === ROW.TOP ? this.topRowList : this.bottomRowList;
+    }
+
+    getActiveRow(row: RowType): { controller: UnifiedListController<U>; list: RowList<T, U> } {
+        return row === ROW.TOP
+            ? { controller: this.topRowList.controller, list: this.topRowList }
+            : { controller: this.bottomRowList.controller, list: this.bottomRowList };
+    }
+
+    getInactiveRow(row: RowType): { controller: UnifiedListController<U>; list: RowList<T, U> } {
+        return row === ROW.TOP
+            ? { controller: this.bottomRowList.controller, list: this.bottomRowList }
+            : { controller: this.topRowList.controller, list: this.topRowList };
+    }
+}

package/packages/list/src/DoubleList/config.ts

@@ -0,0 +1,15 @@
+import { AnimationUtils } from '@24i/bigscreen-sdk/animations';
+import { AnimationConfiguration } from '../types';
+import { animate } from '../animate';
+
+export const CONFIG = {
+    defaultAnimation: {
+        normal: {
+            time: 700,
+            easing: AnimationUtils.easeOutQuart,
+        },
+    } as AnimationConfiguration,
+    animate,
+};
+
+export const VISIBLE_ITEMS_OFFSET = 3;

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

@@ -0,0 +1,82 @@
+import { IFocusable } from '@24i/bigscreen-sdk/focus';
+import { Component } from '@24i/bigscreen-sdk/jsx';
+import { ListBase } from '../Base';
+import { UnifiedListController } from '../UnifiedListController/UnifiedListController';
+import { Item, SharedProps, AnimationConfiguration } from '../types';
+import { CONFIG } from './config';
+
+/**
+ * Constants for row identification
+ */
+export const ROW = {
+    TOP: 'top',
+    BOTTOM: 'bottom',
+} as const;
+
+export type RowType = typeof ROW[keyof typeof ROW];
+
+/*
+ * Constants for horizontal scroll direction
+ */
+export const DIRECTION = {
+    FORWARD: 'forward',
+    BACKWARD: 'backward',
+} as const;
+
+export type DirectionType = typeof DIRECTION[keyof typeof DIRECTION];
+
+export type Props<T extends Item<U>, U> = SharedProps<T, U> & {
+    firstScrollStep: number,
+    animation?: Partial<AnimationConfiguration>,
+    rowClassName?: string,
+};
+
+/**
+ * Interface for DoubleList component
+ */
+export interface DoubleRowList<T extends Item<U>, U>
+    extends IFocusable, Component<SharedProps<T, U>> {
+    appendData(data: U[]): void;
+    prependData(data: U[]): void;
+    scrollTo(index: number, animate?: boolean): void;
+    focus(options?: FocusOptions): void;
+    forward(): boolean;
+    backward(): boolean;
+}
+
+/*
+ * RowList class representing a single row in the DoubleList
+*/
+export class RowList<T extends Item<U>, U> {
+    base: React.RefObject<ListBase<T, U>>;
+
+    props: Props<T, U>;
+
+    controller: UnifiedListController<U>;
+
+    constructor(
+        base: React.RefObject<ListBase<T, U>>,
+        props: Props<T, U>,
+    ) {
+        this.base = base;
+        this.props = props;
+        this.controller = new UnifiedListController<U>(this as any, CONFIG);
+    }
+
+    get current() {
+        return this.base.current;
+    }
+
+    setIndex(index: number): void {
+        if (!this.base.current) return;
+        this.base.current.index = index;
+    }
+
+    appendData(data: U[]): void {
+        this.controller.appendData(data);
+    }
+
+    prependData(data: U[]): void {
+        this.controller.prependData(data);
+    }
+}