Skip to content

A fast 2D and 3D game engine — TypeScript SDK, C++/WebAssembly core, visual editor. Ship one project to web, desktop, WeChat MiniGames, playable ads, and native Android / iOS.

15.5 KB
Raw Blame
// SPDX-License-Identifier: Apache-2.0
// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team
/**
 * @file    list-view.ts
 * @brief   createListView — the ergonomic widget factory over the collection core.
 *
 * A one-call, data-driven, virtualized list/grid that composes the existing
 * primitives (DataSource + LayoutProvider + ViewPool + ListView + ScrollContainer
 * + UIMask) — matching the createButton/createDialog factory-and-handle shape.
 *
 * Items are positioned by UINode Absolute inset (not Transform, which the UI
 * layout owns); the content frame is translated by the scroll offset; a
 * Scissor UIMask on the viewport clips. Wheel and drag/touch scrolling (with
 * a kinetic fling) are handled by the behavior plugin once the viewport is a
 * hovered raycast target.
 */
import type { Entity, Vec2 } from '../../types';
import type { World } from '../../ecs/world';

import { UINode, UIDisplay, UIPositionType, type UINodeData } from '../core/ui-node';
import { px, auto } from '../core/dimension';
import { UIMask, MaskMode } from '../core/ui-mask';

import { spawnUIEntity, setUIVisible, type UINodeInit, type UIVisualInit } from '../core/compose';
import { makeWidgetInteractable } from '../input/interactable';

import {
    type DataSource,
    ArrayDataSource,
} from '../collection/data-source';
import {
    type LayoutProvider,
    type Rect,
    LinearLayoutProvider,
    MeasuredLinearLayoutProvider,
    GridLayoutProvider,
} from '../collection/layout-provider';
import { ListView, type ListViewOptions } from '../collection/list-view';
import { ScrollContainer } from '../collection/scroll-container';
import { worldEngineApi, type EngineApi } from '../../ecs/bridge/engineApi';
import { WasmBridge } from '../../wasm/WasmBridge';

class ViewportBridge extends WasmBridge<NonNullable<EngineApi>> {
    protected readonly label = 'listViewport';
}

/** Linear UI items fill the resolved cross axis; custom layouts keep their own sizes. */
class CrossAxisLayout implements LayoutProvider {
    constructor(private readonly base_: LayoutProvider, private readonly axis_: 'vertical' | 'horizontal',
        private crossSize_: number) {}

    resize(size: Vec2): void {
        this.crossSize_ = this.axis_ === 'vertical' ? size.x : size.y;
    }

    getContentSize(count: number): Vec2 {
        const size = this.base_.getContentSize(count);
        if (count <= 0) return size;
        return this.axis_ === 'vertical' ? { x: this.crossSize_, y: size.y } : { x: size.x, y: this.crossSize_ };
    }

    getItemRect(index: number): Rect {
        const rect = this.base_.getItemRect(index);
        return this.axis_ === 'vertical' ? { ...rect, width: this.crossSize_ } : { ...rect, height: this.crossSize_ };
    }

    getVisibleRange(viewport: Rect, count: number): [number, number] {
        return this.base_.getVisibleRange(viewport, count);
    }

    invalidate(): void {
        (this.base_ as LayoutProvider & { invalidate?: () => void }).invalidate?.();
    }
}

/** The actual UI box owns the visible range and scroll bounds, in layout-local units. */
class LayoutBoundListView<T> extends ListView<T> {
    private uiDisposed_ = false;
    private readonly viewportWorld_: World;
    private readonly bounds_ = new ViewportBridge();
    private boundsEngine_: EngineApi | null = null;

    constructor(opts: ListViewOptions<T>, private readonly viewport_: Entity,
        private readonly scroll_: ScrollContainer, private readonly crossLayout_: CrossAxisLayout | null) {
        super(opts);
        this.viewportWorld_ = opts.world;
    }

    override update(): void {
        if (this.uiDisposed_ || !this.viewportWorld_.valid(this.viewport_)) return;
        const engine = worldEngineApi(this.viewportWorld_);
        const registry = this.viewportWorld_.getCppRegistry();
        if (engine && registry && engine !== this.boundsEngine_) {
            this.bounds_.connect(engine);
            this.boundsEngine_ = engine;
        }
        const bounds = engine && registry ? this.bounds_.module : null;
        const x = bounds?.getUINodeComputedWidth?.(registry!, this.viewport_) ?? 0;
        const y = bounds?.getUINodeComputedHeight?.(registry!, this.viewport_) ?? 0;
        const current = this.getViewport();
        // Unresolved layout keeps the initial hint; only finite resolved boxes resize.
        if (Number.isFinite(x) && Number.isFinite(y) && x > 0 && y > 0
            && (x !== current.width || y !== current.height)) {
            const size = { x, y };
            this.crossLayout_?.resize(size);
            this.setViewportSize(size);
            this.scroll_.setSizes(size, this.getContentSize());
        }
        super.update();
    }

    override dispose(): void {
        this.uiDisposed_ = true;
        this.bounds_.disconnect();
        this.boundsEngine_ = null;
        super.dispose();
    }
}

/**
 * The per-frame runtime a list view plugs into: the tick registry that drives
 * virtualization and the scroll input hookup. The composed `uiPlugin` (and the
 * granular `uiBehaviorPlugin`) satisfy this — passed explicitly so the factory
 * works against whichever plugin instance owns the app, never a module
 * singleton.
 */
export interface ListViewHost {
    registerListView(list: ListView<unknown>): void;
    unregisterListView(list: ListView<unknown>): void;
    attachScrollContainer(entity: Entity, container: ScrollContainer): void;
    detachScrollContainer(entity: Entity): void;
}

/** A single item type: how to build the entity and how to bind data to it. */
export interface ListItemTemplate<T> {
    /** Create one item entity (use `spawnUIEntity` so it carries a UINode). */
    create: (world: World, parent: Entity) => Entity;
    /** Apply data to an item; called on every (re)bind, so keep it idempotent. */
    bind: (entity: Entity, data: T, index: number) => void;
}

/** Layout sugar. A column list, a row list, or a grid (`columns`). */
export type ListLayoutSpec =
    | { itemHeight: number | ((index: number) => number); spacing?: number; direction?: 'column' }
    | { itemWidth: number; spacing?: number; direction: 'row' }
    | { columns: number; itemSize: Vec2; spacing?: Vec2 };

export interface CreateListViewOptions<T> {
    world: World;
    /** The plugin that ticks virtualization + routes scroll input (`uiPlugin`). */
    host: ListViewHost;
    parent?: Entity;
    /** Initial UI layout size; virtualization and scroll bounds follow the resolved box. */
    viewportSize: Vec2;
    /** Extra viewport UINode props (its size defaults to `viewportSize`). */
    node?: UINodeInit;
    /** Viewport background. Default: a transparent hit-target (so the wheel works). */
    background?: UIVisualInit;
    /** Backing data — a `DataSource<T>` or a raw array (wrapped in an ArrayDataSource). */
    data: DataSource<T> | readonly T[];
    /** Layout sugar (`itemHeight` / `columns` …) or a full `LayoutProvider`. */
    layout: ListLayoutSpec | LayoutProvider;
    /** One template, or a map of item type → template for heterogeneous rows. */
    item: ListItemTemplate<T> | Record<string, ListItemTemplate<T>>;
    /** Scroll axis. Defaults from the layout (column→vertical, row→horizontal). */
    direction?: 'vertical' | 'horizontal' | 'both';
    /** Extra indices kept mounted on each side of the visible range. Default 2. */
    recycleBuffer?: number;
    /** Wheel delta multiplier. Default 1. */
    wheelSpeed?: number;
    /** Drag/touch scrolling with a kinetic fling. Default true. */
    dragScroll?: boolean;
    /** Fling velocity fraction left after 1s of coasting. Default 0.135. */
    decelerationRate?: number;
    /** Called after each item bind. */
    onItemBound?: (entity: Entity, data: T, index: number) => void;
}

export interface ListViewHandle<T> {
    /** The viewport entity (the clipped window; add it to your UI tree). */
    readonly entity: Entity;
    /** The scrolling content frame that items are parented to. */
    readonly content: Entity;
    /** The data source — mutate an `ArrayDataSource` here to update the list. */
    readonly data: DataSource<T>;
    /** The scroll model (escape hatch: `scroll.scrollBy`, `onScroll`, …). */
    readonly scroll: ScrollContainer;
    /** The virtualization driver (escape hatch). */
    readonly view: ListView<T>;
    /** Force a re-sync of mounted items on the next frame. */
    refresh(): void;
    /** Scroll so item `index` is at the top-left of the viewport. */
    scrollToIndex(index: number): void;
    /** Number of item entities currently mounted (for virtualization checks). */
    mountedCount(): number;
    /** Tear down: unregister, release items, drop scroll/data subscriptions. */
    dispose(): void;
}

function isDataSource<T>(d: DataSource<T> | readonly T[]): d is DataSource<T> {
    return !Array.isArray(d) && typeof (d as DataSource<T>).getCount === 'function';
}

function isLayoutProvider(l: ListLayoutSpec | LayoutProvider): l is LayoutProvider {
    return typeof (l as LayoutProvider).getItemRect === 'function';
}

function buildLayout(spec: ListLayoutSpec, viewport: Vec2): { layout: LayoutProvider; axis: 'vertical' | 'horizontal' } {
    if ('columns' in spec) {
        return {
            layout: new GridLayoutProvider({ columns: spec.columns, itemSize: spec.itemSize, spacing: spec.spacing }),
            axis: 'vertical',
        };
    }
    if ('itemWidth' in spec) {
        return {
            layout: new LinearLayoutProvider({ direction: 'row', itemSize: { x: spec.itemWidth, y: viewport.y }, spacing: spec.spacing }),
            axis: 'horizontal',
        };
    }
    if (typeof spec.itemHeight === 'function') {
        const mainSizeOf = spec.itemHeight;
        return {
            layout: new MeasuredLinearLayoutProvider({ direction: 'column', crossSize: viewport.x, mainSizeOf, spacing: spec.spacing }),
            axis: 'vertical',
        };
    }
    return {
        layout: new LinearLayoutProvider({ direction: 'column', itemSize: { x: viewport.x, y: spec.itemHeight }, spacing: spec.spacing }),
        axis: 'vertical',
    };
}

/** Position an item within the content by its computed rect (Absolute inset). */
function placeByInset(world: World, entity: Entity, rect: Rect): void {
    if (!world.has(entity, UINode)) return;
    const n = world.get(entity, UINode) as UINodeData;
    n.position = UIPositionType.Absolute;
    n.insetLeft = px(rect.x);
    n.insetTop = px(rect.y);
    n.insetRight = auto();
    n.insetBottom = auto();
    n.width = px(rect.width);
    n.height = px(rect.height);
    world.insert(entity, UINode, n);
}

/**
 * Build a virtualized list (or grid) in one call.
 *
 * @example
 * const list = createListView<Player>({
 *   world, parent, viewportSize: { x: 320, y: 480 },
 *   data: arrayDataSource(players),
 *   layout: { itemHeight: 56 },
 *   item: {
 *     create: (w, parent) => spawnUIEntity({ world: w, parent, node: { height: px(56) } }),
 *     bind: (e, p) => setText(e, p.name),
 *   },
 * });
 * list.data.append([newPlayer]);   // auto-refreshes
 */
export function createListView<T>(opts: CreateListViewOptions<T>): ListViewHandle<T> {
    const { world, host, viewportSize } = opts;

    // 1) Viewport: sized box + Scissor mask + a hovered hit-target (for the wheel).
    const viewport = spawnUIEntity({
        world,
        parent: opts.parent,
        node: { width: opts.node?.fill ? auto() : px(viewportSize.x), height: opts.node?.fill ? auto() : px(viewportSize.y), ...opts.node },
        visual: opts.background ?? { color: { r: 0, g: 0, b: 0, a: 0 } },
    });
    world.insert(viewport, UIMask, { enabled: true, mode: MaskMode.Scissor });
    makeWidgetInteractable(world, viewport, { focusable: false });

    // 2) Content: an Absolute frame translated by the scroll offset; items live here.
    const content = spawnUIEntity({
        world,
        parent: viewport,
        node: { position: UIPositionType.Absolute, insetLeft: px(0), insetTop: px(0), width: px(viewportSize.x), height: px(viewportSize.y) },
    });

    // 3) Resolve data + layout.
    const data: DataSource<T> = isDataSource(opts.data) ? opts.data : new ArrayDataSource<T>(opts.data);
    const resolved = isLayoutProvider(opts.layout)
        ? { layout: opts.layout, axis: 'vertical' as const }
        : buildLayout(opts.layout, viewportSize);
    const { axis } = resolved;
    const crossLayout = !isLayoutProvider(opts.layout) && !('columns' in opts.layout)
        ? new CrossAxisLayout(resolved.layout, axis, axis === 'vertical' ? viewportSize.x : viewportSize.y)
        : null;
    const layout = crossLayout ?? resolved.layout;

    // 4) Item templates → ViewPool template shape ({ factory, binder }).
    const single = 'create' in opts.item && 'bind' in opts.item;
    const templateMap = (single ? { default: opts.item as ListItemTemplate<T> } : opts.item as Record<string, ListItemTemplate<T>>);
    const templates: Record<string, { factory: (w: World, p: Entity) => Entity; binder: (e: Entity, d: T, i: number) => void }> = {};
    for (const [type, tpl] of Object.entries(templateMap)) {
        templates[type] = { factory: tpl.create, binder: tpl.bind };
    }

    // The scroll model and virtualization driver share the resolved viewport.
    const scroll = new ScrollContainer({
        viewportSize,
        contentSize: layout.getContentSize(data.getCount()),
        direction: opts.direction ?? axis,
        wheelSpeed: opts.wheelSpeed,
        dragScroll: opts.dragScroll,
        decelerationRate: opts.decelerationRate,
    });
    const view = new LayoutBoundListView<T>({
        world,
        parent: content,
        dataSource: data,
        layout,
        viewportSize,
        templates,
        recycleBuffer: opts.recycleBuffer,
        placeItem: (w, e, rect) => placeByInset(w, e, rect),
        setVisible: (w, e, visible) => {
            // Recycled rows include text, nested controls and style prefabs.
            // Hide the subtree, rather than only its background quad.
            if (w.valid(e) && w.has(e, UINode)) {
                const node = w.get(e, UINode), display = visible ? UIDisplay.Flex : UIDisplay.None;
                if (node.display !== display) w.insert(e, UINode, { ...node, display });
            }
            setUIVisible(w, e, visible);
        },
        onItemBound: opts.onItemBound,
    }, viewport, scroll, crossLayout);
    host.registerListView(view as ListView<unknown>);

    // Scroll input translates the content and pushes the same offset into the driver.
    const offScroll = scroll.onScroll((offset) => {
        const n = world.get(content, UINode) as UINodeData;
        n.insetLeft = px(-offset.x);
        n.insetTop = px(-offset.y);
        world.insert(content, UINode, n);
        view.setScrollOffset(offset);
    });
    host.attachScrollContainer(viewport, scroll);

    // 7) Keep the scroll range in step with the data count.
    const offData = data.subscribe?.(() => {
        scroll.setContentSize(layout.getContentSize(data.getCount()));
    });

    let disposed = false;
    return {
        entity: viewport,
        content,
        data,
        scroll,
        view,
        refresh: () => view.refresh(),
        scrollToIndex: (index) => {
            const rect = layout.getItemRect(index);
            scroll.setOffset({ x: rect.x, y: rect.y });
        },
        mountedCount: () => view.getMountedCount(),
        dispose: () => {
            if (disposed) return;
            disposed = true;
            offScroll();
            offData?.();
            host.unregisterListView(view as ListView<unknown>);
            host.detachScrollContainer(viewport);
            scroll.dispose();
            view.dispose();
            if (world.valid(viewport)) world.despawn(viewport);
        },
    };
}