Fully autonomous AI Agents system capable of performing complex penetration testing tasks
Go ai-agentsai-security-toolanthropicautonomous-agentsgolanggptgraphqlmulti-agent-systemoffensive-securityopen-sourceopenaipenetration-testingpenetration-testing-toolsreactsecurity-automationsecurity-testingsecurity-toolsself-hosted
refactor(frontend): extract DataTable virtualization into a headless hook
Sergey Kozyrenko831f0e213ec3
diff --git a/frontend/src/components/ui/data-table.test.tsx b/frontend/src/components/ui/data-table.test.tsxindex 2b82bc5d..dd2219d5 100644--- a/frontend/src/components/ui/data-table.test.tsx+++ b/frontend/src/components/ui/data-table.test.tsx@@ -1068,3 +1068,143 @@ describe('cycleColumnSort', () => {expect(column.getIsSorted).toHaveBeenCalledTimes(1);});});++describe('DataTable — virtualization', () => {+ // 60 rows on a single page (pageSize 100) so the rendered set clears the+ // 50-row threshold and `isVirtualized` actually activates.+ const VIRTUAL_ROWS: Row[] = Array.from({ length: 60 }, (_, index) => ({+ id: String(index + 1),+ name: `Row ${index + 1}`,+ }));++ let rectSpy: ReturnType<typeof vi.spyOn>;++ beforeEach(() => {+ // jsdom reports a zero rect for everything. Pin a realistic row height+ // so the window virtualizer culls a deterministic subset instead of+ // collapsing zero-height rows and rendering all of them.+ rectSpy = vi.spyOn(HTMLElement.prototype, 'getBoundingClientRect').mockReturnValue({+ bottom: 53,+ height: 53,+ left: 0,+ right: 800,+ toJSON: () => ({}),+ top: 0,+ width: 800,+ x: 0,+ y: 0,+ } as DOMRect);+ });++ afterEach(() => {+ rectSpy.mockRestore();+ });++ // Body rows carry `data-index`; padding spacers and the header row don't.+ const dataRows = () => document.querySelectorAll('tbody tr[data-index]');++ it('renders only a subset of rows once past the threshold', async () => {+ render(+ <DataTable<Row>+ columns={COLUMNS}+ data={VIRTUAL_ROWS}+ initialPageSize={100}+ isVirtualized+ />,+ { wrapper: Wrapper },+ );++ await waitFor(() => expect(dataRows().length).toBeGreaterThan(0));+ // The viewport can't hold all 60 estimated rows, so the window virtualizer+ // culls the rest — far fewer rows reach the DOM than exist in the data.+ expect(dataRows().length).toBeLessThan(VIRTUAL_ROWS.length);+ });++ it('exposes the true row total via aria-rowcount while virtualized', async () => {+ render(+ <DataTable<Row>+ columns={COLUMNS}+ data={VIRTUAL_ROWS}+ initialPageSize={100}+ isVirtualized+ />,+ { wrapper: Wrapper },+ );++ await waitFor(() => expect(dataRows().length).toBeGreaterThan(0));+ // 60 data rows + 1 header row — what a screen reader announces as the total.+ expect(document.querySelector('table')).toHaveAttribute('aria-rowcount', '61');+ // Header occupies aria-rowindex 1; each data row is its data index + 2+ // (1-based, past the header). Assert the relationship rather than a fixed+ // index so the check is independent of which window the virtualizer renders.+ expect(document.querySelector('thead tr')).toHaveAttribute('aria-rowindex', '1');+ const firstDataRow = dataRows()[0];+ const dataIndex = Number(firstDataRow.getAttribute('data-index'));+ expect(firstDataRow).toHaveAttribute('aria-rowindex', String(dataIndex + 2));+ });++ it('keeps data-index on rows wrapped in a context menu (Radix asChild path)', async () => {+ // Production /flows pairs `isVirtualized` with `renderRowContextMenu`, so+ // every virtual row is wrapped in <ContextMenuTrigger asChild>. The+ // measureElement ref and `data-index` must survive Radix's prop/ref+ // merge or dynamic measurement silently breaks.+ render(+ <DataTable<Row>+ columns={COLUMNS}+ data={VIRTUAL_ROWS}+ initialPageSize={100}+ isVirtualized+ renderRowContextMenu={(row) => <div>menu for {row.name}</div>}+ />,+ { wrapper: Wrapper },+ );++ await waitFor(() => expect(dataRows().length).toBeGreaterThan(0));+ dataRows().forEach((row) => expect(row).toHaveAttribute('data-index'));+ });++ it('does not virtualize at or below the threshold (full DOM, no aria-rowcount)', () => {+ const fewRows: Row[] = Array.from({ length: 30 }, (_, index) => ({+ id: String(index + 1),+ name: `Row ${index + 1}`,+ }));++ render(+ <DataTable<Row>+ columns={COLUMNS}+ data={fewRows}+ initialPageSize={100}+ isVirtualized+ />,+ { wrapper: Wrapper },+ );++ // Every row is in the DOM, so native enumeration works — no spacer, no+ // virtualization wiring, no aria-rowcount override.+ expect(screen.getByText('Row 1')).toBeInTheDocument();+ expect(screen.getByText('Row 30')).toBeInTheDocument();+ expect(dataRows().length).toBe(0);+ expect(document.querySelector('tbody tr[aria-hidden]')).not.toBeInTheDocument();+ expect(document.querySelector('table')).not.toHaveAttribute('aria-rowcount');+ });++ it('disables virtualization when renderSubComponent is set, even past the threshold', () => {+ render(+ <DataTable<Row>+ columns={COLUMNS}+ data={VIRTUAL_ROWS}+ initialPageSize={100}+ isVirtualized+ renderSubComponent={({ row }) => <div>expanded {row.original.name}</div>}+ />,+ { wrapper: Wrapper },+ );++ // Expanded-row support wins over virtualization: the full set renders+ // and no measurement wiring is attached.+ expect(dataRows().length).toBe(0);+ expect(screen.getByText('Row 1')).toBeInTheDocument();+ expect(screen.getByText('Row 60')).toBeInTheDocument();+ expect(document.querySelector('table')).not.toHaveAttribute('aria-rowcount');+ });+});diff --git a/frontend/src/components/ui/data-table.tsx b/frontend/src/components/ui/data-table.tsxindex 79fde482..ddce6007 100644--- a/frontend/src/components/ui/data-table.tsx+++ b/frontend/src/components/ui/data-table.tsx@@ -14,7 +14,6 @@ import {useReactTable,type VisibilityState,} from '@tanstack/react-table';-import { useWindowVirtualizer } from '@tanstack/react-virtual';import {ArrowDown,ArrowUp,@@ -30,7 +29,6 @@ import {} from 'lucide-react';import {type ChangeEvent,- Fragment,type ReactElement,type ReactNode,useCallback,@@ -59,6 +57,7 @@ import { Table, TableBody, TableCell, TableHead, TableHeader, TableRow } from '@import { useEffectAfterMount } from '@/hooks/use-effect-after-mount';import { useLatestRef } from '@/hooks/use-latest-ref';import { usePageStorageKeys } from '@/hooks/use-page-storage-keys';+import { useWindowVirtualList } from '@/hooks/use-window-virtual-list';import { migrateLegacyTableState, updateTableState } from '@/lib/table-state';import { cn } from '@/lib/utils';@@ -105,12 +104,18 @@ interface DataTableProps<TData, TValue = unknown> {initialPageSize?: number;initialSorting?: SortingState;/**- * Render only rows visible in the viewport via `@tanstack/react-virtual`.- * Activates only when the rendered row count exceeds the threshold- * (50 by default) so short tables stay fully rendered for native- * Find-in-page / printing. Not compatible with `renderSubComponent`- * (variable-height expanded rows would need per-row remeasurement),- * so the flag is silently ignored when one is provided.+ * Render only the viewport-visible rows via window-scrolled+ * virtualization (`@tanstack/react-virtual`). Activates only when the+ * rendered row count exceeds `VIRTUALIZATION_THRESHOLD` so short tables+ * stay fully rendered for native Find-in-page and printing.+ *+ * Constraints:+ * - Silently ignored when `renderSubComponent` is set — variable-height+ * expanded rows would need per-row remeasurement this component+ * doesn't wire.+ * - Assumes the page scrolls via `window`. Layouts with an inner+ * `overflow-auto` container (e.g. settings-layout's `<main>`) are not+ * supported and will misposition rows.*/isVirtualized?: boolean;onColumnVisibilityChange?: (visibility: VisibilityState) => void;@@ -143,6 +148,17 @@ interface DataTableProps<TData, TValue = unknown> {const PAGE_SIZE_OPTIONS = [10, 15, 20, 50, 100] as const;+// Row count above which `isVirtualized` actually activates. Short tables+// stay fully rendered so native Find-in-page and printing keep working.+const VIRTUALIZATION_THRESHOLD = 50;++// Pixel estimate handed to the virtualizer until the first real measurement.+// Matches the rendered height of a single-line `TableCell` with `p-4` padding+// plus the `border-b`; rows still resize correctly once `measureItem`+// observes them — this only affects the initial scroll-anchor math.+const ROW_HEIGHT_ESTIMATE = 53;+const estimateRowSize = () => ROW_HEIGHT_ESTIMATE;+const columnPickerLabel = <TData,>(column: Column<TData, unknown>): string =>column.columnDef.meta?.columnMenuLabel ?? column.id;@@ -216,6 +232,32 @@ interface DataTableColumnHeaderProps<TData, TValue> {title: ReactNode;}+interface DataTableRowProps<TData> {+ isRowInteractive: boolean;+ /**+ * Virtualization wiring, present only when the row is rendered inside+ * `VirtualizedTableBody`. Bundling `index` and `ref` into one object keeps+ * the "both or neither" invariant in the type: `index` feeds both+ * `data-index` (read back by `measureElement` to attribute a measured rect)+ * and `aria-rowindex` (1-based, offset past the header row); `ref` is the+ * virtualizer's `measureElement`.+ */+ measurement?: { index: number; ref: (node: Element | null) => void };+ onRowClick: (row: Row<TData>) => void;+ renderRowContextMenu?: (row: TData) => ReactNode;+ renderSubComponent?: (props: { row: Row<TData> }) => ReactElement;+ row: Row<TData>;+}++interface VirtualizedTableBodyProps<TData> {+ isRowInteractive: boolean;+ onRowClick: (row: Row<TData>) => void;+ renderRowContextMenu?: (row: TData) => ReactNode;+ renderSubComponent?: (props: { row: Row<TData> }) => ReactElement;+ rows: Row<TData>[];+ visibleColumnCount: number;+}+/*** Cycle a TanStack column through `none → asc → desc → none`. Pure with* respect to React (no hooks called) so a header `onClick` can invoke it@@ -582,58 +624,8 @@ function DataTable<TData, TValue = unknown>({const rows = table.getRowModel().rows;const visibleColumnCount = table.getVisibleLeafColumns().length;-- const VIRTUALIZATION_THRESHOLD = 50;const isVirtualizationActive = isVirtualized && !renderSubComponent && rows.length > VIRTUALIZATION_THRESHOLD;- const tableContainerRef = useRef<HTMLDivElement>(null);- const [scrollMargin, setScrollMargin] = useState(0);-- useEffect(() => {- if (!isVirtualizationActive) {- return;- }-- const updateScrollMargin = () => {- const element = tableContainerRef.current;-- if (!element) {- return;- }-- setScrollMargin(element.getBoundingClientRect().top + window.scrollY);- };-- updateScrollMargin();-- const resizeObserver = new ResizeObserver(updateScrollMargin);-- if (tableContainerRef.current) {- resizeObserver.observe(tableContainerRef.current);- }-- window.addEventListener('resize', updateScrollMargin);-- return () => {- resizeObserver.disconnect();- window.removeEventListener('resize', updateScrollMargin);- };- }, [isVirtualizationActive]);-- const rowVirtualizer = useWindowVirtualizer({- count: isVirtualizationActive ? rows.length : 0,- estimateSize: () => 53,- overscan: 10,- scrollMargin,- });-- const virtualItems = isVirtualizationActive ? rowVirtualizer.getVirtualItems() : [];- const totalSize = isVirtualizationActive ? rowVirtualizer.getTotalSize() : 0;- // useWindowVirtualizer's item.start/.end are in document coordinates.- const paddingTop = virtualItems.length > 0 ? virtualItems[0]!.start - scrollMargin : 0;- const paddingBottom =- virtualItems.length > 0 ? totalSize - (virtualItems[virtualItems.length - 1]!.end - scrollMargin) : 0;-const pageSizeValue = pagination.pageSize >= data.length && data.length > 0 ? 'all' : String(pagination.pageSize);const totalRows = table.getFilteredRowModel().rows.length;@@ -768,14 +760,14 @@ function DataTable<TData, TValue = unknown>({</DropdownMenuContent></DropdownMenu></div>- <div- className="rounded-md border"- ref={tableContainerRef}- >- <Table>+ <div className="rounded-md border">+ <Table aria-rowcount={isVirtualizationActive ? rows.length + 1 : undefined}><TableHeader>{table.getHeaderGroups().map((headerGroup) => (- <TableRow key={headerGroup.id}>+ <TableRow+ aria-rowindex={isVirtualizationActive ? 1 : undefined}+ key={headerGroup.id}+ >{headerGroup.headers.map((header) => (<TableHeadclassName={header.column.columnDef.meta?.headerClassName}@@ -798,8 +790,8 @@ function DataTable<TData, TValue = unknown>({</TableRow>))}</TableHeader>- <TableBody>- {rows.length === 0 ? (+ {rows.length === 0 ? (+ <TableBody><TableRow><TableCellclassName={cn('text-center', empty?.entityName ? 'py-12' : 'h-24')}@@ -811,102 +803,30 @@ function DataTable<TData, TValue = unknown>({/></TableCell></TableRow>- ) : (- <>- {paddingTop > 0 ? (- <tr aria-hidden>- <td- colSpan={visibleColumnCount}- style={{ height: paddingTop }}- />- </tr>- ) : null}- {(isVirtualizationActive- ? virtualItems.map((virtualItem) => ({- row: rows[virtualItem.index]!,- virtualItem,- }))- : rows.map((row) => ({ row, virtualItem: null }))- ).map(({ row, virtualItem }) => {- const contextMenuContent = renderRowContextMenu?.(row.original);-- const tableRow = (- <TableRow- className={cn(- 'group hover:bg-muted/50 data-[state=open]:bg-muted/50 has-[[data-state=open]]:bg-muted/50',- isRowInteractive && 'cursor-pointer',- contextMenuContent &&- 'pointer-coarse:select-none pointer-coarse:[-webkit-touch-callout:none]',- )}- data-index={virtualItem?.index}- ref={- virtualItem- ? (node: HTMLTableRowElement | null) =>- rowVirtualizer.measureElement(node)- : undefined- }- {...(row.getIsSelected() ? { 'data-state': 'selected' } : {})}- onClick={() => handleRowClick(row)}- >- {row.getVisibleCells().map((cell) => (- <TableCell- className={cell.column.columnDef.meta?.cellClassName}- key={cell.id}- onClick={(event) => {- if (cell.column.columnDef.meta?.preventRowClick) {- event.stopPropagation();- }- }}- style={- cell.column.columnDef.size- ? {- maxWidth: cell.column.columnDef.size,- minWidth: cell.column.columnDef.size,- width: cell.column.columnDef.size,- }- : undefined- }- >- {flexRender(cell.column.columnDef.cell, cell.getContext())}- </TableCell>- ))}- </TableRow>- );-- return (- <Fragment key={row.id}>- {contextMenuContent ? (- <ContextMenu>- <ContextMenuTrigger asChild>{tableRow}</ContextMenuTrigger>- <ContextMenuContent>{contextMenuContent}</ContextMenuContent>- </ContextMenu>- ) : (- tableRow- )}- {row.getIsExpanded() && renderSubComponent && (- <TableRow className="cursor-default border-0 hover:bg-transparent">- <TableCell- className="p-0"- colSpan={row.getVisibleCells().length}- >- {renderSubComponent({ row })}- </TableCell>- </TableRow>- )}- </Fragment>- );- })}- {paddingBottom > 0 ? (- <tr aria-hidden>- <td- colSpan={visibleColumnCount}- style={{ height: paddingBottom }}- />- </tr>- ) : null}- </>- )}- </TableBody>+ </TableBody>+ ) : isVirtualizationActive ? (+ <VirtualizedTableBody+ isRowInteractive={isRowInteractive}+ onRowClick={handleRowClick}+ renderRowContextMenu={renderRowContextMenu}+ renderSubComponent={renderSubComponent}+ rows={rows}+ visibleColumnCount={visibleColumnCount}+ />+ ) : (+ <TableBody>+ {rows.map((row) => (+ <DataTableRow+ isRowInteractive={isRowInteractive}+ key={row.id}+ onRowClick={handleRowClick}+ renderRowContextMenu={renderRowContextMenu}+ renderSubComponent={renderSubComponent}+ row={row}+ />+ ))}+ </TableBody>+ )}</Table></div><div className="flex flex-wrap items-center justify-between gap-4 px-4 py-4">@@ -1137,4 +1057,161 @@ function DataTableFilter({ onQueryChange, placeholder, query }: DataTableFilterP);}+/**+ * Single row in the `DataTable` body. Renders the visible cells, wraps with+ * a context-menu trigger when one is supplied, and emits the expanded+ * sub-component row when the row is expanded. Both `VirtualizedTableBody`+ * and the plain branch render the same markup by reusing this component;+ * the only difference is whether `measurement` is supplied.+ */+function DataTableRow<TData>({+ isRowInteractive,+ measurement,+ onRowClick,+ renderRowContextMenu,+ renderSubComponent,+ row,+}: DataTableRowProps<TData>) {+ const contextMenuContent = renderRowContextMenu?.(row.original);++ const tableRow = (+ <TableRow+ aria-rowindex={measurement ? measurement.index + 2 : undefined}+ className={cn(+ 'group hover:bg-muted/50 data-[state=open]:bg-muted/50 has-[[data-state=open]]:bg-muted/50',+ isRowInteractive && 'cursor-pointer',+ contextMenuContent && 'pointer-coarse:select-none pointer-coarse:[-webkit-touch-callout:none]',+ )}+ data-index={measurement?.index}+ ref={measurement?.ref}+ {...(row.getIsSelected() ? { 'data-state': 'selected' } : {})}+ onClick={() => onRowClick(row)}+ >+ {row.getVisibleCells().map((cell) => (+ <TableCell+ className={cell.column.columnDef.meta?.cellClassName}+ key={cell.id}+ onClick={(event) => {+ if (cell.column.columnDef.meta?.preventRowClick) {+ event.stopPropagation();+ }+ }}+ style={+ cell.column.columnDef.size+ ? {+ maxWidth: cell.column.columnDef.size,+ minWidth: cell.column.columnDef.size,+ width: cell.column.columnDef.size,+ }+ : undefined+ }+ >+ {flexRender(cell.column.columnDef.cell, cell.getContext())}+ </TableCell>+ ))}+ </TableRow>+ );++ return (+ <>+ {contextMenuContent ? (+ <ContextMenu>+ <ContextMenuTrigger asChild>{tableRow}</ContextMenuTrigger>+ <ContextMenuContent>{contextMenuContent}</ContextMenuContent>+ </ContextMenu>+ ) : (+ tableRow+ )}+ {row.getIsExpanded() && renderSubComponent ? (+ <TableRow className="cursor-default border-0 hover:bg-transparent">+ <TableCell+ className="p-0"+ colSpan={row.getVisibleCells().length}+ >+ {renderSubComponent({ row })}+ </TableCell>+ </TableRow>+ ) : null}+ </>+ );+}++/**+ * Empty `<tr>` spacer that pushes the virtualized window into the correct+ * scroll position. Raw `<tr>` / `<td>` (not `TableRow` / `TableCell`) so the+ * spacer doesn't inherit row border and hover-background styles.+ * `aria-hidden` keeps it out of the accessibility tree.+ */+function PaddingRow({ colSpan, height }: { colSpan: number; height: number }) {+ return (+ <tr aria-hidden>+ <td+ colSpan={colSpan}+ style={{ height }}+ />+ </tr>+ );+}++/**+ * Window-scrolled virtualization for `DataTable`'s `<tbody>`. Mounted only+ * when `DataTable` decides virtualization should activate, so the underlying+ * `useWindowVirtualList` (and its window/body listeners) never run on tables+ * that don't need them. Padding `<tr>` spacers preserve `<table>` / `<tbody>`+ * / `<tr>` semantics — no absolute positioning, no `display: grid` override.+ */+function VirtualizedTableBody<TData>({+ isRowInteractive,+ onRowClick,+ renderRowContextMenu,+ renderSubComponent,+ rows,+ visibleColumnCount,+}: VirtualizedTableBodyProps<TData>) {+ // Key the measurement cache by TanStack's row id, not the bare index, so it+ // follows row identity once the table opts into `getRowId` (today's default+ // ids are positional, making this equivalent to the index). Recreated on+ // every `rows` change so the cache tracks the current row set.+ const getItemKey = useCallback((index: number) => rows[index].id, [rows]);++ const { anchorRef, measureItem, paddingEnd, paddingStart, virtualItems } =+ useWindowVirtualList<HTMLTableSectionElement>({+ count: rows.length,+ estimateSize: estimateRowSize,+ getItemKey,+ });++ return (+ <TableBody ref={anchorRef}>+ {paddingStart > 0 ? (+ <PaddingRow+ colSpan={visibleColumnCount}+ height={paddingStart}+ />+ ) : null}+ {virtualItems.map((virtualItem) => {+ const row = rows[virtualItem.index];++ return (+ <DataTableRow+ isRowInteractive={isRowInteractive}+ key={row.id}+ measurement={{ index: virtualItem.index, ref: measureItem }}+ onRowClick={onRowClick}+ renderRowContextMenu={renderRowContextMenu}+ renderSubComponent={renderSubComponent}+ row={row}+ />+ );+ })}+ {paddingEnd > 0 ? (+ <PaddingRow+ colSpan={visibleColumnCount}+ height={paddingEnd}+ />+ ) : null}+ </TableBody>+ );+}+export { DataTable, DataTableColumnHeader };diff --git a/frontend/src/hooks/use-window-virtual-list.ts b/frontend/src/hooks/use-window-virtual-list.tsnew file mode 100644index 00000000..dcc15736--- /dev/null+++ b/frontend/src/hooks/use-window-virtual-list.ts@@ -0,0 +1,166 @@+import { useWindowVirtualizer, type VirtualItem, type Virtualizer } from '@tanstack/react-virtual';+import { type RefObject, useLayoutEffect, useRef, useState } from 'react';++/**+ * Headless window-scrolled list virtualization.+ *+ * Wraps `@tanstack/react-virtual`'s `useWindowVirtualizer` and supplies the+ * three pieces its raw API leaves to the caller:+ *+ * - keeps `scrollMargin` in sync with the anchor element's document-Y+ * position, including when content above the anchor shifts size (page+ * header growing, banner appearing, sidebar variant flipping);+ * - exposes the stable `measureElement` reference so dynamic row heights+ * work without recreating the ref callback on every render;+ * - returns ready-to-render spacer pixels (`paddingStart` / `paddingEnd`)+ * so consumers don't reimplement the arithmetic.+ *+ * Render structure the consumer is responsible for:+ *+ * ```+ * <Anchor ref={anchorRef}>+ * <Spacer height={paddingStart} />+ * {virtualItems.map((vi) => (+ * <Item key={...} ref={measureItem} data-index={vi.index} />+ * ))}+ * <Spacer height={paddingEnd} />+ * </Anchor>+ * ```+ *+ * Anchor placement — its top edge defines item 0's document position. For+ * tables that's `<tbody>` (the header sits above it, so attaching the ref to+ * the table wrapper would offset all items by the header height); for+ * div-based lists it's the list container itself.+ *+ * Anchor must be present when the hook mounts. The `scrollMargin` sync runs+ * once in `useLayoutEffect` and does not re-attach if the anchor renders+ * later. If the anchor is conditional in the consumer, mount/unmount the+ * hook owner together with it (the recommended pattern below already does+ * this).+ *+ * Mount the hook owner conditionally. The underlying virtualizer attaches+ * window scroll/resize listeners on every mount — there is no `enabled`+ * option that skips them. Pattern: render `<VirtualizedX/>` only when+ * `count > threshold`, so non-virtualized consumers of the same parent never+ * pay the listener cost.+ *+ * Scroll container — assumes `window`. Layouts with an inner `overflow-auto`+ * container (e.g. settings-layout's `<main>`) need `useVirtualizer` with an+ * explicit scroll element instead; this hook will misposition items there.+ *+ * `overscan` defaults to 5 (not react-virtual's default of 1) so the user+ * sees rows materialize ahead of the viewport edge during fast scrolling.+ */+type UseWindowVirtualListOptions = {+ /** Number of items in the underlying collection. */+ count: number;+ /**+ * Estimated item size in pixels. Pass a memoized reference (`useCallback`+ * or module-scope constant) so the virtualizer doesn't treat each render+ * as a measurement-affecting change.+ */+ estimateSize: () => number;+ /**+ * Stable identifier per index. TanStack uses this as the key for the+ * internal measurement cache; without it the cache is keyed by index,+ * which mis-attributes measurements when rows reorder (sort, filter) and+ * heights vary.+ */+ getItemKey?: (index: number) => number | string;+ /** Items rendered above + below the viewport. */+ overscan?: number;+};++type UseWindowVirtualListResult<T extends Element> = {+ /**+ * Attach to the element whose top edge marks item 0's document-Y+ * position. See the structural example in the module JSDoc.+ */+ anchorRef: RefObject<null | T>;+ /**+ * Stable ref to forward to each rendered item. Pair with+ * `data-index={virtualItem.index}` on the same node — TanStack reads the+ * attribute to know which item the measurement belongs to.+ */+ measureItem: (node: Element | null) => void;+ /** Pixels of spacer to render after the last visible item. */+ paddingEnd: number;+ /** Pixels of spacer to render before the first visible item. */+ paddingStart: number;+ /** Sum of all item sizes — the list's full scrollable height. */+ totalSize: number;+ /** Items currently in the render window (visible + overscan). */+ virtualItems: VirtualItem[];+ /** Escape hatch for callers needing `scrollToIndex`, `scrollToOffset`, … */+ virtualizer: Virtualizer<Window, Element>;+};++export function useWindowVirtualList<T extends Element = HTMLDivElement>({+ count,+ estimateSize,+ getItemKey,+ overscan = 5,+}: UseWindowVirtualListOptions): UseWindowVirtualListResult<T> {+ const anchorRef = useRef<null | T>(null);+ const [scrollMargin, setScrollMargin] = useState(0);++ useLayoutEffect(() => {+ if (!anchorRef.current) {+ return;+ }++ const syncScrollMargin = () => {+ const node = anchorRef.current;++ if (!node) {+ return;+ }++ // Anchor's document-Y (scroll-invariant): rect.top + scrollY.+ setScrollMargin(node.getBoundingClientRect().top + window.scrollY);+ };++ syncScrollMargin();++ // Re-sync when content *above* the anchor changes height (header+ // growth, banner mount, sidebar variant flip) and shifts its+ // document-Y. The anchor's own resize can't move its own top edge, so+ // observing `document.body` is both necessary and sufficient.+ const observer = new ResizeObserver(syncScrollMargin);++ observer.observe(document.body);++ window.addEventListener('resize', syncScrollMargin);++ return () => {+ observer.disconnect();+ window.removeEventListener('resize', syncScrollMargin);+ };+ }, []);++ const virtualizer = useWindowVirtualizer({+ count,+ estimateSize,+ getItemKey,+ overscan,+ scrollMargin,+ });++ const virtualItems = virtualizer.getVirtualItems();+ const totalSize = virtualizer.getTotalSize();++ const firstItem = virtualItems[0];+ const lastItem = virtualItems.at(-1);+ const paddingStart = firstItem ? firstItem.start - scrollMargin : 0;+ const paddingEnd = lastItem ? totalSize - (lastItem.end - scrollMargin) : 0;++ return {+ anchorRef,+ measureItem: virtualizer.measureElement,+ paddingEnd,+ paddingStart,+ totalSize,+ virtualItems,+ virtualizer,+ };+}