Documentation navigation

Published API · 0.1.0-rc.1

foldkit-ui · virtualList

Published foldkit-ui API declarations for virtualList.

./virtualList

@wsagency/wseffect-foldkit-ui · MIT · source · MIT license · WS-AGENCY-NOTICE · THIRD-PARTY-NOTICES

This entry point is published in @wsagency/wseffect-foldkit-ui@0.1.0-rc.1. Import it from the package subpath shown below; the signatures and documentation are read from the installed package declarations.

import * as Wseffect from '@wsagency/wseffect-foldkit-ui/virtualList'

Exported declarations

ContentAlignment

Alignment of content when its total height is shorter than the viewport.

ContentAlignment: Schema.Literals<readonly ["Start", "End"]>

ContentAlignment

export type ContentAlignment = typeof ContentAlignment.Type;

informItemsChanged

Notifies VirtualList that its parent-owned items changed. The next view resolves the stored stable-key anchor against the new items, and the Command restores that anchor after the DOM patch.

informItemsChanged: (model: Model, itemKeys: ReadonlyArray<string>) => ScrollReturn

init

Creates an initial virtual list model from a config. The container starts in `Unmeasured` state until its Mount reports the first measurement.

init: (config: InitConfig) => Model

InitConfig

Configuration for creating a virtual list model with `init`.

export type InitConfig = Readonly<{
    id: string;
    rowHeightPx: number;
    initialContainerHeight?: number;
    initialScrollTop?: number;
    initialScroll?: Readonly<{
        target: ScrollTarget;
        alignment?: ScrollAlignment;
    }>;
    followEnd?: Readonly<{
        thresholdPx?: number;
    }>;
}>;

Message

export type Message = typeof Message.Type;

Message

Union of all messages the virtual list component can produce.

Message: import("@wsagency/wseffect-foldkit/message").MessageUnion<{
    readonly ObservedContainerScroll: {
        scrollTop: Schema.Number;
        scrollHeight: Schema.Number;
        containerHeight: Schema.Number;
        anchor: import("@wsagency/wseffect-foldkit/schema").TaggedUnion<{
            readonly None: {};
            readonly Row: {
                key: Schema.String;
                index: Schema.Number;
                viewportOffset: Schema.Number;
            };
        }>;
    };
    readonly ResizedContainer: {
        containerWidth: Schema.Number;
        containerHeight: Schema.Number;
        leadingOffsetPx: Schema.optional<Schema.Number>;
    };
    readonly MeasuredRows: {
        measurements: Schema.$Array<Schema.Struct<{
            readonly key: Schema.String;
            readonly height: Schema.Number;
            readonly layoutVersion: Schema.Number;
        }>>;
    };
    readonly CompletedApplyScroll: {
        version: Schema.Number;
        outcome: import("@wsagency/wseffect-foldkit/schema").TaggedUnion<{
            readonly Applied: {
                scrollTop: Schema.Number;
                scrollHeight: Schema.Number;
                containerHeight: Schema.Number;
                anchor: import("@wsagency/wseffect-foldkit/schema").TaggedUnion<{
                    readonly None: {};
                    readonly Row: {
                        key: Schema.String;
                        index: Schema.Number;
                        viewportOffset: Schema.Number;
                    };
                }>;
            };
            readonly Skipped: {};
        }>;
    };
}>

Model

export type Model = typeof Model.Type;

Model

Schema for the virtual list's state. Tracks scroll position, container measurement, and any in-flight programmatic scroll.

Model: Schema.Struct<{
    readonly id: Schema.String;
    readonly rowHeightPx: Schema.Number;
    readonly scrollTop: Schema.Number;
    readonly measurement: import("@wsagency/wseffect-foldkit/schema").TaggedUnion<{
        readonly Unmeasured: {};
        readonly Measured: {
            containerWidth: Schema.Number;
            containerHeight: Schema.Number;
        };
    }>;
    readonly initialContainerHeight: Schema.optional<Schema.Number>;
    readonly leadingOffsetPx: Schema.optional<Schema.Number>;
    readonly viewportAnchor: import("@wsagency/wseffect-foldkit/schema").TaggedUnion<{
        readonly Offset: {
            scrollTop: Schema.Number;
        };
        readonly Row: {
            key: Schema.String;
            index: Schema.Number;
            viewportOffset: Schema.Number;
        };
        readonly End: {};
    }>;
    readonly measuredRowHeights: Schema.$Record<Schema.String, Schema.Number>;
    readonly layoutVersion: Schema.Number;
    readonly initialScroll: import("@wsagency/wseffect-foldkit/schema").TaggedUnion<{
        readonly Applied: {};
        readonly Pending: {
            target: import("@wsagency/wseffect-foldkit/schema").TaggedUnion<{
                readonly Index: {
                    index: Schema.Number;
                };
                readonly Key: {
                    key: Schema.String;
                };
                readonly Offset: {
                    offset: Schema.Number;
                };
                readonly End: {};
            }>;
            alignment: Schema.Literals<readonly ["Start", "Center", "End", "Nearest"]>;
        };
    }>;
    readonly endBehavior: import("@wsagency/wseffect-foldkit/schema").TaggedUnion<{
        readonly PreserveAnchor: {};
        readonly Follow: {
            thresholdPx: Schema.Number;
        };
    }>;
    readonly pendingScroll: import("@wsagency/wseffect-foldkit/schema").TaggedUnion<{
        readonly Idle: {};
        readonly Pending: {
            request: import("@wsagency/wseffect-foldkit/schema").TaggedUnion<{
                readonly Target: {
                    target: import("@wsagency/wseffect-foldkit/schema").TaggedUnion<{
                        readonly Index: {
                            index: Schema.Number;
                        };
                        readonly Key: {
                            key: Schema.String;
                        };
                        readonly Offset: {
                            offset: Schema.Number;
                        };
                        readonly End: {};
                    }>;
                    alignment: Schema.Literals<readonly ["Start", "Center", "End", "Nearest"]>;
                };
                readonly Anchor: {
                    anchor: import("@wsagency/wseffect-foldkit/schema").TaggedUnion<{
                        readonly Offset: {
                            scrollTop: Schema.Number;
                        };
                        readonly Row: {
                            key: Schema.String;
                            index: Schema.Number;
                            viewportOffset: Schema.Number;
                        };
                        readonly End: {};
                    }>;
                };
            }>;
            version: Schema.Number;
        };
    }>;
    readonly pendingScrollVersion: Schema.Number;
}>

renderedRange

Returns the item-index range rendered for a VirtualList view, including its measured leading offset and row-height strategy. An optional scrollTop evaluates the same window at a prospective viewport position.

renderedRange: <Item>(model: Model, inputs: Pick<ViewInputs<Item>, 'items' | 'itemToKey' | 'itemToRowHeightPx' | 'dynamicRowHeights' | 'itemToEstimatedRowHeightPx' | 'overscan' | 'contentAlignment'>, scrollTop?: number) => Readonly<{
    startIndex: number;
    endIndex: number;
}>

RowHeightInputs

Mutually exclusive configuration for fixed, exact variable, or measured dynamic row heights.

export type RowHeightInputs<Item> = Readonly<{
    itemToRowHeightPx?: undefined;
    dynamicRowHeights?: undefined;
    itemToEstimatedRowHeightPx?: never;
}> | Readonly<{
    itemToRowHeightPx?: never;
    dynamicRowHeights: true;
    itemToEstimatedRowHeightPx?: (item: Item, index: number) => number;
}> | Readonly<{
    itemToRowHeightPx: (item: Item, index: number) => number;
    dynamicRowHeights?: never;
    itemToEstimatedRowHeightPx?: never;
}>;

ScrollAlignment

export type ScrollAlignment = typeof ScrollAlignment.Type;

ScrollAlignment

Alignment of a row within the viewport after a programmatic scroll.

ScrollAlignment: Schema.Literals<readonly ["Start", "Center", "End", "Nearest"]>

ScrollTarget

export type ScrollTarget = typeof ScrollTarget.Type;

ScrollTarget

Logical destination for initial and programmatic scrolling.

ScrollTarget: import("@wsagency/wseffect-foldkit/schema").TaggedUnion<{
    readonly Index: {
        index: Schema.Number;
    };
    readonly Key: {
        key: Schema.String;
    };
    readonly Offset: {
        offset: Schema.Number;
    };
    readonly End: {};
}>

scrollTo

Programmatically scrolls to a logical target.

scrollTo: (model: Model, target: ScrollTarget, options?: ScrollToOptions) => ScrollReturn

scrollToEnd

Programmatically scrolls to the end of the list.

scrollToEnd: (model: Model) => ScrollReturn

scrollToIndex

Programmatically scrolls the container so the row at `index` is visible. The next view resolves the logical index with its current sizing mode, and the Command aligns the live rendered row.

scrollToIndex: (model: Model, index: number, options?: ScrollToOptions) => ScrollReturn

scrollToKey

Programmatically scrolls to the row whose `itemToKey` result matches `key`. The next view resolves the key against its current items.

scrollToKey: (model: Model, key: string, options?: ScrollToOptions) => ScrollReturn

scrollToOffset

Programmatically scrolls to an exact pixel offset from the start of the list. Negative offsets clamp to zero.

scrollToOffset: (model: Model, offset: number) => ScrollReturn

ScrollToOptions

Options shared by row-targeted programmatic scrolling helpers.

export type ScrollToOptions = Readonly<{
    alignment?: ScrollAlignment;
}>;

update

Processes a VirtualList Message and returns the next Model and optional Commands.

update: (model: Model, message: Message) => Readonly<{
    model: {
        readonly id: string;
        readonly rowHeightPx: number;
        readonly scrollTop: number;
        readonly measurement: {
            readonly _tag: "Measured";
            readonly containerWidth: number;
            readonly containerHeight: number;
        } | {
            readonly _tag: "Unmeasured";
        };
        readonly initialContainerHeight?: number | undefined;
        readonly leadingOffsetPx?: number | undefined;
        readonly viewportAnchor: {
            readonly _tag: "End";
        } | {
            readonly _tag: "Row";
            readonly key: string;
            readonly index: number;
            readonly viewportOffset: number;
        } | {
            readonly _tag: "Offset";
            readonly scrollTop: number;
        };
        readonly measuredRowHeights: {
            readonly [x: string]: number;
        };
        readonly layoutVersion: number;
        readonly initialScroll: {
            readonly _tag: "Applied";
        } | {
            readonly _tag: "Pending";
            readonly target: {
                readonly _tag: "End";
            } | {
                readonly _tag: "Index";
                readonly index: number;
            } | {
                readonly _tag: "Key";
                readonly key: string;
            } | {
                readonly _tag: "Offset";
                readonly offset: number;
            };
            readonly alignment: "Center" | "End" | "Nearest" | "Start";
        };
        readonly endBehavior: {
            readonly _tag: "Follow";
            readonly thresholdPx: number;
        } | {
            readonly _tag: "PreserveAnchor";
        };
        readonly pendingScroll: {
            readonly _tag: "Idle";
        } | {
            readonly _tag: "Pending";
            readonly request: {
                readonly _tag: "Anchor";
                readonly anchor: {
                    readonly _tag: "End";
                } | {
                    readonly _tag: "Row";
                    readonly key: string;
                    readonly index: number;
                    readonly viewportOffset: number;
                } | {
                    readonly _tag: "Offset";
                    readonly scrollTop: number;
                };
            } | {
                readonly _tag: "Target";
                readonly target: {
                    readonly _tag: "End";
                } | {
                    readonly _tag: "Index";
                    readonly index: number;
                } | {
                    readonly _tag: "Key";
                    readonly key: string;
                } | {
                    readonly _tag: "Offset";
                    readonly offset: number;
                };
                readonly alignment: "Center" | "End" | "Nearest" | "Start";
            };
            readonly version: number;
        };
        readonly pendingScrollVersion: number;
    };
    commands?: Update.Commands<{
        readonly _tag: "CompletedApplyScroll";
        readonly version: number;
        readonly outcome: {
            readonly _tag: "Applied";
            readonly scrollTop: number;
            readonly scrollHeight: number;
            readonly containerHeight: number;
            readonly anchor: {
                readonly _tag: "None";
            } | {
                readonly _tag: "Row";
                readonly key: string;
                readonly index: number;
                readonly viewportOffset: number;
            };
        } | {
            readonly _tag: "Skipped";
        };
    } | {
        readonly _tag: "MeasuredRows";
        readonly measurements: readonly {
            readonly key: string;
            readonly height: number;
            readonly layoutVersion: number;
        }[];
    } | {
        readonly _tag: "ObservedContainerScroll";
        readonly scrollTop: number;
        readonly scrollHeight: number;
        readonly containerHeight: number;
        readonly anchor: {
            readonly _tag: "None";
        } | {
            readonly _tag: "Row";
            readonly key: string;
            readonly index: number;
            readonly viewportOffset: number;
        };
    } | {
        readonly _tag: "ResizedContainer";
        readonly containerWidth: number;
        readonly containerHeight: number;
        readonly leadingOffsetPx?: number | undefined;
    }, never>;
    outMessage?: never;
}>

view

view: <Item>() => ViewForItem<Item>

ViewInputs

export type ViewInputs<Item> = BaseViewInputs<Item> & RowHeightInputs<Item>;