ContentAlignment
Alignment of content when its total height is shorter than the viewport.
ContentAlignment: Schema.Literals<readonly ["Start", "End"]>Effect-native UI toolkit
Interactive demosPublished API · 0.1.0-rc.1
Published foldkit-ui API declarations for 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'ContentAlignmentAlignment of content when its total height is shorter than the viewport.
ContentAlignment: Schema.Literals<readonly ["Start", "End"]>ContentAlignmentexport type ContentAlignment = typeof ContentAlignment.Type;informItemsChangedNotifies 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>) => ScrollReturninitCreates an initial virtual list model from a config. The container starts in `Unmeasured` state until its Mount reports the first measurement.
init: (config: InitConfig) => ModelInitConfigConfiguration 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;
}>;
}>;Messageexport type Message = typeof Message.Type;MessageUnion 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: {};
}>;
};
}>Modelexport type Model = typeof Model.Type;ModelSchema 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;
}>renderedRangeReturns 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;
}>RowHeightInputsMutually 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;
}>;ScrollAlignmentexport type ScrollAlignment = typeof ScrollAlignment.Type;ScrollAlignmentAlignment of a row within the viewport after a programmatic scroll.
ScrollAlignment: Schema.Literals<readonly ["Start", "Center", "End", "Nearest"]>ScrollTargetexport type ScrollTarget = typeof ScrollTarget.Type;ScrollTargetLogical 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: {};
}>scrollToProgrammatically scrolls to a logical target.
scrollTo: (model: Model, target: ScrollTarget, options?: ScrollToOptions) => ScrollReturnscrollToEndProgrammatically scrolls to the end of the list.
scrollToEnd: (model: Model) => ScrollReturnscrollToIndexProgrammatically 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) => ScrollReturnscrollToKeyProgrammatically 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) => ScrollReturnscrollToOffsetProgrammatically scrolls to an exact pixel offset from the start of the list. Negative offsets clamp to zero.
scrollToOffset: (model: Model, offset: number) => ScrollReturnScrollToOptionsOptions shared by row-targeted programmatic scrolling helpers.
export type ScrollToOptions = Readonly<{
alignment?: ScrollAlignment;
}>;updateProcesses 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;
}>viewview: <Item>() => ViewForItem<Item>ViewInputsexport type ViewInputs<Item> = BaseViewInputs<Item> & RowHeightInputs<Item>;