test/docs: cover VirtualList onScroll

Add an integration test for wheel + key-driven scroll callbacks and document the onScroll range semantics.

Author: RtlZeroMemory

docs/widgets/virtual-list.md

@@ -42,6 +42,7 @@ ui.virtualList({
 
 - Use `itemHeight` callback for variable-height rows.
 - `renderItem` receives a `focused` flag for styling.
+- The `range` passed to `onScroll` is `[startIndex, endIndex)` and includes overscan.
 
 ## Related
 

packages/core/src/app/__tests__/widgetRenderer.integration.test.ts

@@ -18,6 +18,25 @@ function keyEvent(key: number, mods = 0): ZrevEvent {
   return { kind: "key", timeMs: 0, key, mods, action: "down" };
 }
 
+function mouseEvent(
+  x: number,
+  y: number,
+  mouseKind: 1 | 2 | 3 | 4 | 5,
+  opts: Readonly<{ wheelX?: number; wheelY?: number }> = {},
+): ZrevEvent {
+  return {
+    kind: "mouse",
+    timeMs: 0,
+    x,
+    y,
+    mouseKind,
+    mods: 0,
+    buttons: 0,
+    wheelX: opts.wheelX ?? 0,
+    wheelY: opts.wheelY ?? 0,
+  };
+}
+
 function createNoopBackend(): RuntimeBackend {
   return {
     start: async () => {},
@@ -243,6 +262,42 @@ describe("WidgetRenderer integration battery", () => {
     assert.deepEqual(selected, ["b:1"]);
   });
 
+  test("virtualList onScroll fires for wheel and key-driven scroll", () => {
+    const backend = createNoopBackend();
+    const renderer = new WidgetRenderer<void>({
+      backend,
+      requestRender: () => {},
+    });
+
+    const scrolled: Array<Readonly<{ scrollTop: number; range: [number, number] }>> = [];
+
+    const vnode = ui.virtualList({
+      id: "v",
+      items: new Array<number>(100).fill(0).map((_, i) => i),
+      itemHeight: 1,
+      renderItem: (item) => ui.text(String(item)),
+      onScroll: (scrollTop, range) => scrolled.push(Object.freeze({ scrollTop, range })),
+    });
+
+    const res = renderer.submitFrame(
+      () => vnode,
+      undefined,
+      { cols: 20, rows: 10 },
+      defaultTheme,
+      noRenderHooks(),
+    );
+    assert.ok(res.ok);
+
+    renderer.routeEngineEvent(mouseEvent(1, 1, 5, { wheelY: 1 }));
+    renderer.routeEngineEvent(keyEvent(3 /* TAB */));
+    renderer.routeEngineEvent(keyEvent(13 /* END */));
+
+    assert.deepEqual(scrolled, [
+      { scrollTop: 3, range: [0, 16] },
+      { scrollTop: 90, range: [87, 100] },
+    ]);
+  });
+
   test("table routing moves focused row and activates on Enter", () => {
     const backend = createNoopBackend();
     const renderer = new WidgetRenderer<void>({