From bc18ffc8be52390871a8349a0f8a679b05f95a95 Mon Sep 17 00:00:00 2001 From: Asish Kumar Date: Fri, 20 Nov 2026 05:34:50 +0530 Subject: [PATCH] docs(virtual-core): document indexAttribute and test shared-cell measuring The indexAttribute option is part of VirtualizerOptions but was only described in the Marko docs. Add an entry to the API reference covering its default, where the attribute is read (measureElement and the resize observer), the warning logged when it is missing, and the grid use case where a row and a column virtualizer measure the same cell through distinct attributes. Add core tests: a row virtualizer and a column virtualizer measure one cell carrying data-row-index and data-column-index and each updates only its own index, and the default attribute / missing-attribute warning behavior. Closes #1386 --- docs/api/virtualizer.md | 42 ++++++++++ .../virtual-core/tests/measurement.test.ts | 81 +++++++++++++++++++ 2 files changed, 123 insertions(+) diff --git a/docs/api/virtualizer.md b/docs/api/virtualizer.md index a5715fbc1..dba8cc240 100644 --- a/docs/api/virtualizer.md +++ b/docs/api/virtualizer.md @@ -226,6 +226,48 @@ gap?: number This option allows you to set the spacing between items in the virtualized list. It's particularly useful for maintaining a consistent visual separation between items without having to manually adjust each item's margin or padding. The value is specified in pixels. +### `indexAttribute` + +```tsx +indexAttribute?: string +``` + +**Default:** `'data-index'` + +The name of the DOM attribute the virtualizer reads to find out which item a measured element belongs to. It is read by `measureElement` and by the `ResizeObserver` that keeps measurements up to date, so every element you measure must carry it, set to the item's index. + +The default is enough for a single virtualizer. Change it when **two virtualizers measure the same element**, as in a grid with both a row and a column virtualizer: a cell can't carry two different indexes in one `data-index` attribute, so give each virtualizer its own attribute: + +```tsx +const rowVirtualizer = useVirtualizer({ + count: rows.length, + getScrollElement: () => parentRef.current, + estimateSize: () => 35, + indexAttribute: 'data-row-index', +}) + +const columnVirtualizer = useVirtualizer({ + horizontal: true, + count: columns.length, + getScrollElement: () => parentRef.current, + estimateSize: () => 100, + indexAttribute: 'data-column-index', +}) + +// ... + +
{ + rowVirtualizer.measureElement(node) + columnVirtualizer.measureElement(node) + }} +/> +``` + +If the attribute is missing on a measured element, the virtualizer logs a warning (`Missing attribute name '={index}' on measured element.`) and skips the measurement. + ### `lanes` ```tsx diff --git a/packages/virtual-core/tests/measurement.test.ts b/packages/virtual-core/tests/measurement.test.ts index a53db446c..af6981456 100644 --- a/packages/virtual-core/tests/measurement.test.ts +++ b/packages/virtual-core/tests/measurement.test.ts @@ -1225,3 +1225,84 @@ test('refreshes horizontal end alignment when a scrollbar toggles', () => { } virtualizer._didMount()() }) + +// ─── indexAttribute ────────────────────────────────────────────────────────── + +test('indexAttribute lets a row and a column virtualizer measure the same cell', () => { + const createVirtualizer = (horizontal: boolean, indexAttribute?: string) => { + const virtualizer = new Virtualizer({ + count: 10, + horizontal, + indexAttribute, + estimateSize: () => 50, + getScrollElement: () => null, + scrollToFn: vi.fn(), + observeElementRect: (_instance, cb) => { + cb({ width: 400, height: 400 }) + return () => {} + }, + observeElementOffset: (_instance, cb) => { + cb(0, false) + return () => {} + }, + }) + virtualizer._willUpdate() + // Seed the measurements, as a render does before refs call measureElement. + virtualizer['getMeasurements']() + return virtualizer + } + + const rows = createVirtualizer(false, 'data-row-index') + const columns = createVirtualizer(true, 'data-column-index') + + // A grid cell at row 2, column 5. A single `data-index` could not carry both. + const attributes: Record = { + 'data-row-index': '2', + 'data-column-index': '5', + } + const cell = { + getAttribute: (name: string) => attributes[name] ?? null, + offsetHeight: 80, + offsetWidth: 120, + isConnected: true, + } as unknown as HTMLElement + + rows.measureElement(cell) + columns.measureElement(cell) + + expect(rows.elementsCache.get(2)).toBe(cell) + expect(columns.elementsCache.get(5)).toBe(cell) + const rowMeasurements = rows['getMeasurements']() + const columnMeasurements = columns['getMeasurements']() + expect(rowMeasurements[2]!.size).toBe(80) + expect(columnMeasurements[5]!.size).toBe(120) + // Neither virtualizer touched the other's index. + expect(rowMeasurements[5]!.size).toBe(50) + expect(columnMeasurements[2]!.size).toBe(50) +}) + +test('indexAttribute defaults to data-index and warns when the attribute is missing', () => { + const virtualizer = new Virtualizer({ + count: 3, + estimateSize: () => 50, + getScrollElement: () => null, + scrollToFn: vi.fn(), + observeElementRect: vi.fn(), + observeElementOffset: vi.fn(), + }) + const node = { + getAttribute: (name: string) => (name === 'data-index' ? '1' : null), + } as unknown as HTMLElement + expect(virtualizer.indexFromElement(node)).toBe(1) + + const custom = new Virtualizer({ + ...virtualizer.options, + indexAttribute: 'data-row-index', + }) + const warn = vi.spyOn(console, 'warn').mockImplementation(() => {}) + expect(custom.indexFromElement(node)).toBe(-1) + expect(warn).toHaveBeenCalledWith( + "Missing attribute name 'data-row-index={index}' on measured element.", + ) + warn.mockRestore() +})