A platform for community discussion. Free, open, simple.
DEV: Convert the windowing virtualizer to TypeScript (#44351)
Sérgio Saquetim56a91abe627f
diff --git a/frontend/discourse/app/ui-kit/-internals/windowing/virtualizer.js b/frontend/discourse/app/ui-kit/-internals/windowing/virtualizer.tssimilarity index 65%rename from frontend/discourse/app/ui-kit/-internals/windowing/virtualizer.jsrename to frontend/discourse/app/ui-kit/-internals/windowing/virtualizer.tsindex deed17b121c..4911dbe92fb 100644--- a/frontend/discourse/app/ui-kit/-internals/windowing/virtualizer.js+++ b/frontend/discourse/app/ui-kit/-internals/windowing/virtualizer.ts@@ -13,9 +13,88 @@ import {measureElement,observeElementOffset,observeElementRect,+ type Rect,Virtualizer,} from "@tanstack/virtual-core";+/* The narrow contract consumers hold. Engine types stay inside this module. */++/** A row key: an item's own primitive value, or a generated identity key. */+export type VirtualKey = number | string | bigint;++/** The indices of the first and last rows in the rendered window. */+export interface VisibleRange {+ startIndex: number;+ endIndex: number;+}++/** A {@link VisibleRange} with the overscan and total count it was computed from. */+export interface VirtualRange extends VisibleRange {+ overscan: number;+ count: number;+}++/** A row the engine has placed: its key, index, and measured or estimated box. */+export interface VirtualItem {+ key: VirtualKey;+ index: number;+ start: number;+ end: number;+ size: number;+ lane: number;+}++/** How to place a row in the viewport, and how to animate getting there. */+export interface VirtualizerScrollOptions {+ align?: "start" | "center" | "end" | "auto";+ behavior?: ScrollBehavior;+}++/** The options a caller supplies. The element-adapter plumbing is added here. */+export interface VirtualizerOptions {+ anchorTo: "start" | "end";+ count: number;+ getScrollElement: () => HTMLDivElement | null;+ estimateSize: (index: number) => number;+ getItemKey: (index: number) => VirtualKey;+ overscan: number;+ onChange: () => void;+ followOnAppend: boolean;+ scrollEndThreshold?: number;+ rangeExtractor?: (range: VirtualRange) => number[];+}++/**+ * The element-backed virtualizer as callers see it. Options are re-synced with+ * {@link updateElementVirtualizer}, never by calling the engine directly.+ */+export interface VirtualizerApi {+ range: VisibleRange | null;+ isScrolling: boolean;+ /** The viewport the engine measures and scrolls. Null until it mounts. */+ scrollElement: HTMLElement | null;++ /**+ * The engine's cached scroll offset (px). Null until the first measure. The+ * element's real `scrollTop` is the source of truth; this can drift from it+ * when the browser clamps a scroll the engine never observed.+ */+ scrollOffset: number | null;+ _didMount(): () => void;+ _willUpdate(): void;+ getTotalSize(): number;+ getVirtualItems(): VirtualItem[];+ measure(): void;+ measureElement(element: HTMLElement | null): void;+ scrollToIndex(index: number, options?: VirtualizerScrollOptions): void;+ scrollToOffset(+ offset: number,+ options?: Pick<VirtualizerScrollOptions, "behavior">+ ): void;+}++type ElementEngine = Virtualizer<HTMLElement, HTMLElement>;+let VIRTUALIZATION_ENABLED = true;/**@@ -46,16 +125,12 @@ export function enableVirtualization() {VIRTUALIZATION_ENABLED = true;}-/**- * Whether rows are windowed. False means the render-all fallback is active.- *- * @returns {boolean}- */-export function isVirtualizationEnabled() {+/** Whether rows are windowed. False means the render-all fallback is active. */+export function isVirtualizationEnabled(): boolean {return VIRTUALIZATION_ENABLED;}-const STABLE_KEYS = new WeakMap();+const STABLE_KEYS = new WeakMap<object, string>();/*** Keys for symbol items. A strong map, unlike the object one, so a symbol used as@@ -63,7 +138,7 @@ const STABLE_KEYS = new WeakMap();* sentinel values a consumer defines a fixed number of, not per-row data — but it* is the one entry here that does not release.*/-const STABLE_SYMBOL_KEYS = new Map();+const STABLE_SYMBOL_KEYS = new Map<symbol, string>();const KEY_NAMESPACE = "d-virtual-list:key:";let stableKeyCounter = 0;@@ -79,19 +154,19 @@ let stableKeyCounter = 0;** A consumer whose ids are immutable AND who rebuilds its item objects each render* (so object identity is NOT stable) should instead pass `@key` — see {@link keyFor}.- *- * @param {unknown} item- * @returns {number | string | bigint}*/-export function stableKeyFor(item) {+export function stableKeyFor(item: unknown): VirtualKey {const type = typeof item;if (type === "string") {- return item.startsWith(KEY_NAMESPACE) ? `${KEY_NAMESPACE}${item}` : item;+ // `type` is an alias of `typeof item`, which TypeScript does not narrow through.+ return (item as string).startsWith(KEY_NAMESPACE)+ ? `${KEY_NAMESPACE}${item as string}`+ : (item as string);}if (type === "number" || type === "bigint") {- return item;+ return item as number | bigint;}if (type === "boolean" || item === null || type === "undefined") {@@ -99,18 +174,19 @@ export function stableKeyFor(item) {}if (type === "symbol") {- let key = STABLE_SYMBOL_KEYS.get(item);+ let key = STABLE_SYMBOL_KEYS.get(item as symbol);if (key === undefined) {key = `${KEY_NAMESPACE}symbol:${++stableKeyCounter}`;- STABLE_SYMBOL_KEYS.set(item, key);+ STABLE_SYMBOL_KEYS.set(item as symbol, key);}return key;}- let key = STABLE_KEYS.get(item);+ // Every primitive returned above, so `item` is an object or a function here.+ let key = STABLE_KEYS.get(item as object);if (key === undefined) {key = `${KEY_NAMESPACE}object:${++stableKeyCounter}`;- STABLE_KEYS.set(item, key);+ STABLE_KEYS.set(item as object, key);}return key;}@@ -129,14 +205,10 @@ export function stableKeyFor(item) {** The single source of truth for both keying paths (the modifier's `getItemKey`* and the component's render-all fallback), so the two can never drift.- *- * @param {unknown} item- * @param {string} [field]- * @returns {number | string | bigint}*/-export function keyFor(item, field) {+export function keyFor(item: unknown, field?: string): VirtualKey {if (field != null && item != null && typeof item === "object") {- const value = item[field];+ const value = (item as Record<string, unknown>)[field];return value == null ? stableKeyFor(item) : stableKeyFor(value);}return stableKeyFor(item);@@ -151,9 +223,12 @@ export function keyFor(item, field) {* the callback lets it say so. `measure()` is not that lever: it clears the item-size cache and* never re-reads the viewport.*/-const RECT_CALLBACKS = new WeakMap();+const RECT_CALLBACKS = new WeakMap<object, (rect: Rect) => void>();-function observeElementRectWithHandle(instance, callback) {+function observeElementRectWithHandle(+ instance: ElementEngine,+ callback: (rect: Rect) => void+) {RECT_CALLBACKS.set(instance, callback);return observeElementRect(instance, callback);}@@ -169,9 +244,15 @@ function observeElementRectWithHandle(instance, callback) {* `isScrolling` for the reset delay, suppressing synchronous row measurement* for that whole window.*/-const OFFSET_CALLBACKS = new WeakMap();+const OFFSET_CALLBACKS = new WeakMap<+ object,+ (offset: number, isScrolling: boolean) => void+>();-function observeElementOffsetWithHandle(instance, callback) {+function observeElementOffsetWithHandle(+ instance: ElementEngine,+ callback: (offset: number, isScrolling: boolean) => void+) {OFFSET_CALLBACKS.set(instance, callback);return observeElementOffset(instance, callback);}@@ -179,10 +260,10 @@ function observeElementOffsetWithHandle(instance, callback) {/*** Tell the engine the viewport's current scroll offset, without pretending a* user scrolled. A no-op before the engine has mounted or once it has torn down.- *- * @param {{ scrollElement?: HTMLElement | null }} virtualizer*/-export function pushScrollOffset(virtualizer) {+export function pushScrollOffset(virtualizer: {+ scrollElement?: HTMLElement | null;+}) {const callback = OFFSET_CALLBACKS.get(virtualizer);const element = virtualizer?.scrollElement;@@ -199,10 +280,10 @@ export function pushScrollOffset(virtualizer) {** Measured the way the engine measures it — `offsetWidth`/`offsetHeight`, rounded — so a* pushed rect and an observed one are the same value and cannot disagree.- *- * @param {{ scrollElement?: HTMLElement | null }} virtualizer*/-export function remeasureViewport(virtualizer) {+export function remeasureViewport(virtualizer: {+ scrollElement?: HTMLElement | null;+}) {const callback = RECT_CALLBACKS.get(virtualizer);const element = virtualizer?.scrollElement;@@ -230,7 +311,9 @@ const ELEMENT_ADAPTER = {observeElementRect: observeElementRectWithHandle,observeElementOffset: observeElementOffsetWithHandle,measureElement,-};+} satisfies Partial<+ ConstructorParameters<typeof Virtualizer<HTMLElement, HTMLElement>>[0]+>;/*** A `rangeExtractor` extended with consumer-selected, otherwise-out-of-window@@ -259,15 +342,19 @@ const ELEMENT_ADAPTER = {* one of those changes — which, for a consumer following the documented* reactivity contract, happens on the next input change.*- * @param {(indices: readonly number[], range: { startIndex: number, endIndex: number, overscan: number, count: number }) => readonly number[] | null | undefined} pins Returns extra indices to keep mounted.- * @returns {(range: { startIndex: number, endIndex: number, overscan: number, count: number }) => number[]}+ * @param pins - Returns extra indices to keep mounted.*/-export function rangeExtractorWithPins(pins) {+export function rangeExtractorWithPins(+ pins: (+ indices: readonly number[],+ range: VirtualRange+ ) => readonly number[] | null | undefined+): (range: VirtualRange) => number[] {return (range) => {const indices = defaultRangeExtractor(range);const merged = new Set(indices);- let extra;+ let extra: readonly number[];try {extra = pins(indices, range) ?? [];} catch (e) {@@ -290,24 +377,29 @@ export function rangeExtractorWithPins(pins) {* Construct an element-backed virtualizer, filling in the element-observer* plumbing the caller does not supply. See {@link ELEMENT_ADAPTER}.*- * @param {object} options- * @returns {object} An element-backed virtualizer instance.+ * Returned as the narrow {@link VirtualizerApi}: the engine instance has to+ * satisfy it here, which is what lets callers use it without a cast.*/-export function createElementVirtualizer(options) {- return new Virtualizer({ ...ELEMENT_ADAPTER, ...options });+export function createElementVirtualizer(+ options: VirtualizerOptions+): VirtualizerApi {+ return new Virtualizer<HTMLElement, HTMLElement>({+ ...ELEMENT_ADAPTER,+ ...options,+ });}/*** Re-sync options on an existing element virtualizer, preserving the adapter* plumbing. Always use this instead of calling `setOptions` directly.*- * Typed structurally rather than as the engine's own class: callers hold their- * own narrow view of the instance, and naming the engine type here would leak it- * back across the wall this module exists to be.- *- * @param {{ setOptions: (options: object) => void }} virtualizer- * @param {object} options+ * Takes the narrow {@link VirtualizerApi} so the engine type does not leak to+ * callers. Every one was made by {@link createElementVirtualizer}, so the cast+ * back to the engine is the only place that crossing happens.*/-export function updateElementVirtualizer(virtualizer, options) {- virtualizer.setOptions({ ...ELEMENT_ADAPTER, ...options });+export function updateElementVirtualizer(+ virtualizer: VirtualizerApi,+ options: VirtualizerOptions+): void {+ (virtualizer as ElementEngine).setOptions({ ...ELEMENT_ADAPTER, ...options });}diff --git a/frontend/discourse/app/ui-kit/d-virtual-list.gts b/frontend/discourse/app/ui-kit/d-virtual-list.gtsindex ebbd0765ebd..dd80bed47c3 100644--- a/frontend/discourse/app/ui-kit/d-virtual-list.gts+++ b/frontend/discourse/app/ui-kit/d-virtual-list.gts@@ -8,19 +8,15 @@ import { modifier } from "ember-modifier";import {isVirtualizationEnabled,keyFor,+ type VirtualItem,+ type VirtualKey,+ type VirtualRange,+ type VisibleRange,} from "discourse/ui-kit/-internals/windowing/virtualizer";import dConcatClass from "discourse/ui-kit/helpers/d-concat-class";import dElement from "discourse/ui-kit/helpers/d-element";import dVirtualizer from "discourse/ui-kit/modifiers/d-virtualizer";-/** A single measured/positioned row as published by the engine. */-interface VirtualItem {- key: number | string | bigint;- index: number;- start: number;- size: number;-}-/*** The positioning modifier, applied as `{{row.place row.start row.index}}`. Its* positional args carry the row's offset and absolute index.@@ -44,7 +40,7 @@ type PlaceModifier = ModifierLike<{interface RowContext<T> {item: T;index: number;- key: number | string | bigint;+ key: VirtualKey;start: number;size: number;/**@@ -61,7 +57,7 @@ interface RowContext<T> {* AFTER {@link place} — a row reached before its `data-index` is stamped cannot be* identified, so it is skipped and keeps rendering at `@estimateSize`.*/- measure: ModifierLike<HTMLElement>;+ measure: ModifierLike<{ Element: HTMLElement }>;/*** The row's `aria-posinset`, or undefined when `@itemRole` is not a role that* defines it. Meaningful only when every entry in `@items` is a real row: a@@ -159,16 +155,6 @@ export interface DVirtualListApi {readonly isScrolling: boolean;}-interface VisibleRange {- startIndex: number;- endIndex: number;-}--interface VirtualRange extends VisibleRange {- overscan: number;- count: number;-}-/** The visible range plus the total item count, passed to an edge callback. */interface EdgeInfo extends VisibleRange {count: number;@@ -627,7 +613,7 @@ export default class DVirtualList<T> extends Component<#rowContext(item: T,index: number,- key: number | string | bigint,+ key: VirtualKey,start: number,size: number): RowContext<T> {diff --git a/frontend/discourse/app/ui-kit/modifiers/d-virtualizer.ts b/frontend/discourse/app/ui-kit/modifiers/d-virtualizer.tsindex 44e03c4712f..8bd311ba5ab 100644--- a/frontend/discourse/app/ui-kit/modifiers/d-virtualizer.ts+++ b/frontend/discourse/app/ui-kit/modifiers/d-virtualizer.ts@@ -1,4 +1,5 @@import { DEBUG } from "@glimmer/env";+import { assert } from "@ember/debug";import { isDestroying, registerDestructor } from "@ember/destroyable";import type Owner from "@ember/owner";import { cancel, schedule } from "@ember/runloop";@@ -12,11 +13,15 @@ import {rangeExtractorWithPins,remeasureViewport,updateElementVirtualizer,+ type VirtualItem,+ type VirtualizerApi,+ type VirtualizerOptions,+ type VirtualKey,+ type VirtualRange,+ type VisibleRange,} from "discourse/ui-kit/-internals/windowing/virtualizer";import type { DVirtualListApi } from "discourse/ui-kit/d-virtual-list";-type VirtualKey = number | string | bigint;-/*** How close (in rows) the visible range must come to an edge before its reach* callback arms. A few rows of lead time lets a fetch land before the reader@@ -40,16 +45,6 @@ const EDGE_HYSTERESIS = 4;*/const SCROLL_EPSILON = 1.5;-interface VisibleRange {- startIndex: number;- endIndex: number;-}--interface VirtualRange extends VisibleRange {- overscan: number;- count: number;-}-type PinnedIndices = (indices: readonly number[],range: VirtualRange@@ -60,15 +55,6 @@ interface EdgeInfo extends VisibleRange {count: number;}-interface VirtualItem {- key: VirtualKey;- index: number;- start: number;- end: number;- size: number;- lane: number;-}-interface PublishedState {/*** The rendered window. Frozen, and a copy of the engine's own array rather than@@ -91,48 +77,6 @@ interface StateSignature {>;}-interface VirtualizerOptions {- anchorTo: "start" | "end";- count: number;- getScrollElement: () => HTMLDivElement | null;- estimateSize: (index: number) => number;- getItemKey: (index: number) => VirtualKey;- overscan: number;- onChange: () => void;- followOnAppend: boolean;- scrollEndThreshold?: number;- rangeExtractor?: (range: VirtualRange) => number[];-}--interface VirtualizerApi {- range: VisibleRange | null;- isScrolling: boolean;- /** The viewport the engine measures and scrolls. Null until it mounts. */- scrollElement: HTMLElement | null;-- /**- * The engine's cached scroll offset (px). Null until the first measure. The- * element's real `scrollTop` is the source of truth; this can drift from it- * when the browser clamps a scroll the engine never observed.- */- scrollOffset: number | null;- _didMount(): () => void;- _willUpdate(): void;- getTotalSize(): number;- getVirtualItems(): VirtualItem[];- measure(): void;- measureElement(element: HTMLElement | null): void;- scrollToIndex(- index: number,- options?: Parameters<DVirtualListApi["scrollToIndex"]>[1]- ): void;- scrollToOffset(- offset: number,- options?: Parameters<DVirtualListApi["scrollToOffset"]>[1]- ): void;- setOptions(options: VirtualizerOptions): void;-}-interface DVirtualizerSignature<T> {Element: HTMLDivElement;Args: {@@ -340,12 +284,7 @@ export default class DVirtualizer<T> extends Modifier<// is already assigned, every later `modify()` takes the update branch and// the API is never registered — so `measureRow` stays a no-op and NO row is// ever measured, silently, for the life of the list.- //- // TODO(devxp-typescript-pending): Remove once the JavaScript adapter- // preserves the engine's element and option types.- const virtualizer = createElementVirtualizer(- options- ) as unknown as VirtualizerApi;+ const virtualizer = createElementVirtualizer(options);let cleanup: (() => void) | null = null;try {@@ -450,8 +389,10 @@ export default class DVirtualizer<T> extends Modifier<if (this.#syncingScroll || !element?.isConnected || isDestroying(this)) {return;}- const engineOffset = this.#virtualizer?.scrollOffset ?? null;+ const virtualizer = this.#virtualizer;+ const engineOffset = virtualizer?.scrollOffset ?? null;if (+ !virtualizer ||engineOffset === null ||Math.abs(engineOffset - element.scrollTop) < SCROLL_EPSILON) {@@ -468,7 +409,7 @@ export default class DVirtualizer<T> extends Modifier<// The flush calls again after settling the height so a shrink's forced layout// exposes the browser-clamped position before the window is read.const maxOffset = Math.max(- this.#virtualizer.getTotalSize() - element.clientHeight,+ virtualizer.getTotalSize() - element.clientHeight,0);if (engineOffset <= maxOffset + SCROLL_EPSILON) {@@ -477,7 +418,7 @@ export default class DVirtualizer<T> extends Modifier<this.#syncingScroll = true;try {- pushScrollOffset(this.#virtualizer);+ pushScrollOffset(virtualizer);} finally {this.#syncingScroll = false;}@@ -612,9 +553,13 @@ export default class DVirtualizer<T> extends Modifier<) {return;}+ // `scrollTop` only moves here because the engine scrolled, so it exists.+ const virtualizer = this.#virtualizer;+ assert("dVirtualizer: scroll synced without an engine", virtualizer);+this.#syncingScroll = true;try {- pushScrollOffset(this.#virtualizer);+ pushScrollOffset(virtualizer);} finally {this.#syncingScroll = false;}diff --git a/frontend/discourse/type-tests/ui-kit/d-virtual-list-row-errors-test.gts b/frontend/discourse/type-tests/ui-kit/d-virtual-list-row-errors-test.gtsnew file mode 100644index 00000000000..07f40779bb1--- /dev/null+++ b/frontend/discourse/type-tests/ui-kit/d-virtual-list-row-errors-test.gts@@ -0,0 +1,31 @@+// Negative type assertions for the row modifiers DVirtualList yields: every+// invocation below must fail to compile. They are quarantined here because a+// Glint error directive suppresses reporting elsewhere in its file, which would+// let a positive pass against a broken declaration. Positives live in+// d-virtual-list-row-test.gts.+import DVirtualList from "discourse/ui-kit/d-virtual-list";++interface Row {+ id: number;+ label: string;+}++declare const rows: readonly Row[];+declare function estimate(row: Row, index: number): number;++const Negatives = <template>+ <DVirtualList+ @estimateSize={{estimate}}+ @items={{rows}}+ @ownedRow={{true}}+ as |item row|+ >+ {{! @glint-expect-error - measure takes no arguments }}+ <div {{row.measure "extra"}}>{{item.label}}</div>++ {{! @glint-expect-error - measure needs an HTML element to size }}+ <svg {{row.measure}}><title>{{item.label}}</title></svg>+ </DVirtualList>+</template>;++export default Negatives;diff --git a/frontend/discourse/type-tests/ui-kit/d-virtual-list-row-test.gts b/frontend/discourse/type-tests/ui-kit/d-virtual-list-row-test.gtsnew file mode 100644index 00000000000..27e8bc4fd91--- /dev/null+++ b/frontend/discourse/type-tests/ui-kit/d-virtual-list-row-test.gts@@ -0,0 +1,27 @@+// Positive type assertions for the row modifiers DVirtualList yields: every+// invocation below must compile. Keep this file free of Glint error directives,+// because one would suppress reporting for the rest of the file. Negatives live+// in d-virtual-list-row-errors-test.gts.+import DVirtualList from "discourse/ui-kit/d-virtual-list";++interface Row {+ id: number;+ label: string;+}++declare const rows: readonly Row[];+declare function estimate(row: Row, index: number): number;++const Positives = <template>+ <DVirtualList+ @as="ul"+ @estimateSize={{estimate}}+ @items={{rows}}+ @ownedRow={{true}}+ as |item row|+ >+ <li {{row.place row.start row.index}} {{row.measure}}>{{item.label}}</li>+ </DVirtualList>+</template>;++export default Positives;