From a979f728ab760ce88dabc8e0022dec6161051de8 Mon Sep 17 00:00:00 2001 From: Anastasiia Beriia Date: Mon, 2 Nov 2026 12:32:43 +0300 Subject: [PATCH 01/10] feat: support declarative column auto sizing --- src/hooks/useColumnsAutoSize/README.md | 60 +++ .../domMeasurement.test.tsx | 222 +++++++++++ src/hooks/useColumnsAutoSize/index.ts | 2 +- src/hooks/useColumnsAutoSize/types.ts | 41 +- .../useColumnsAutoSize/useColumnsAutoSize.tsx | 362 ++++++++++++------ .../utils/createDOMMeasureElement.ts | 48 +++ .../utils/measureDOMColumns.test.ts | 92 +++++ .../utils/measureDOMColumns.ts | 141 +++++++ src/index.ts | 2 + 9 files changed, 852 insertions(+), 118 deletions(-) create mode 100644 src/hooks/useColumnsAutoSize/domMeasurement.test.tsx create mode 100644 src/hooks/useColumnsAutoSize/utils/createDOMMeasureElement.ts create mode 100644 src/hooks/useColumnsAutoSize/utils/measureDOMColumns.test.ts create mode 100644 src/hooks/useColumnsAutoSize/utils/measureDOMColumns.ts diff --git a/src/hooks/useColumnsAutoSize/README.md b/src/hooks/useColumnsAutoSize/README.md index 90d0931..dacaa52 100644 --- a/src/hooks/useColumnsAutoSize/README.md +++ b/src/hooks/useColumnsAutoSize/README.md @@ -241,3 +241,63 @@ TanStack `columnSizing` and predefined widths retain priority over auto widths. Callbacks are emitted for changes, not simply because the table mounts or a callback prop changes. The callback requests an update in controlled mode: only new `columnWidths` props change the rendered widths. + +### Lightweight measurement through column configuration + +Describe a column's visible text in `meta.autoSize` to measure it without mounting +its React cell renderer. No DOM or measurement-renderer callback is required: + +```tsx +const columns = React.useMemo[]>( + () => [ + { + id: 'duration', + accessorKey: 'duration', + header: 'Duration', + cell: ({getValue}) => , + meta: { + autoSize: { + text: (value) => formatDuration(value), + extraWidth: 24, // space occupied by the cell's icon/button + }, + }, + }, + ], + [], +); +``` + +`meta.autoSize: {}` measures the accessor's primitive value. Optional fields: + +- `text`: formatted text, or `(value, row) => text`. Share formatting with the real cell. +- `extraWidth`: reserved space in px or a CSS length expression, optionally a function + of `(value, row)` for controls that are absent in empty cells. +- `style` and `className`: typography/cell styles and the text class, either static + or functions of `(value, row)`. Numeric CSS lengths use React's px semantics. +- `header`: text or `{text, extraWidth?, style?, className?}` for a custom React header. + String/number headers are inferred automatically. +- `footer`: an array of text values or the same text descriptions for footer rows. + +The library creates lightweight DOM, inserts all described columns together, +reads once per column and removes the batch. It uses the styled table's cell and +header classes. `padding` and `headerPadding` supply horizontal spacing; cell +`style` can override it. Columns without a description, unsupported values, +custom React headers without a text description and broken formatters keep the +existing React measurement path. Visible cell rendering is unchanged. + +Optional hook arguments: + +- `measurementContainerRef`: inherit fonts/theme variables from the table's parent; + attach this ref even while showing a loader. Defaults to `document.body`. +- `measurementClassName`: additional table classes for the temporary container. +- `measurementRevision`: a stable theme/style revision. Changing it refreshes even + `measureOnce` widths. Font loading triggers a refresh automatically. + +Register the table using `React.useLayoutEffect(() => setTableInstance(table), +[table, setTableInstance])` to measure before paint. Sampling uses the current +sorted/filtered row model. Predefined widths, user resizing, controlled widths and +`measureOnce` retain their priority. No width cache is shared between mounts. + +`options.deferUpdates` defaults to `false`. Enable it to let React 18+ interrupt +rendering real cells after measurement. React 17 applies updates normally. DOM +measurement stays synchronous, so very large samples can still block the thread. diff --git a/src/hooks/useColumnsAutoSize/domMeasurement.test.tsx b/src/hooks/useColumnsAutoSize/domMeasurement.test.tsx new file mode 100644 index 0000000..b3dea6c --- /dev/null +++ b/src/hooks/useColumnsAutoSize/domMeasurement.test.tsx @@ -0,0 +1,222 @@ +/* eslint-disable testing-library/no-node-access -- Native DOM is the measurement API under test. */ +import * as React from 'react'; + +import type {ColumnDef} from '@tanstack/react-table'; +import {act, renderHook, waitFor} from '@testing-library/react'; + +import {useTable} from '../useTable'; + +import {useMeasureCellWidth} from './hooks/useMeasureCellWidth'; +import {useColumnsAutoSize} from './useColumnsAutoSize'; + +jest.mock('./hooks/useMeasureCellWidth'); +type Item = {id: string; value: number}; +const formatText = jest.fn((value: unknown, _row: Item) => String(80 + Number(value))); +const columns: ColumnDef[] = [ + {id: 'value', accessorKey: 'value', header: 'Value', meta: {autoSize: {text: formatText}}}, +]; +const initialData: Item[] = [{id: 'same-id', value: 1}]; +const measureReact = jest.fn(async () => 120); + +function useTestTable({ + data = initialData, + defs = columns, + revision, + measureOnce = false, +}: { + data?: Item[]; + defs?: ColumnDef[]; + revision?: unknown; + measureOnce?: boolean; +} = {}) { + const result = useColumnsAutoSize({ + columns: defs, + measurementRevision: revision, + options: {minWidth: 80, maxWidth: 500, measureOnce}, + }); + const table = useTable({ + data, + columns: result.columnsWithAutoSizes, + getRowId: (row) => row.id, + enableSorting: true, + enableColumnResizing: true, + }); + const {setTableInstance} = result; + React.useLayoutEffect(() => setTableInstance(table), [table, setTableInstance]); + return {...result, table}; +} + +beforeEach(() => { + formatText.mockClear(); + measureReact.mockReset(); + measureReact.mockResolvedValue(120); + jest.mocked(useMeasureCellWidth).mockReturnValue(measureReact); + jest.spyOn(HTMLElement.prototype, 'getBoundingClientRect').mockImplementation(function ( + this: HTMLElement, + ) { + expect(this.isConnected).toBe(true); + return { + width: Number(this.querySelector('.gt-table__cell span')?.textContent ?? 0), + } as DOMRect; + }); +}); +afterEach(() => jest.restoreAllMocks()); + +test('measures column descriptions before paint without debounce, React renderers or retained DOM', () => { + const {result} = renderHook(() => useTestTable()); + expect(result.current.columnWidths).toEqual({value: 81}); + expect(result.current.isMeasuring).toBe(false); + expect(formatText).toHaveBeenCalledTimes(1); + expect(measureReact).not.toHaveBeenCalled(); + expect(document.querySelector('[aria-hidden="true"]')).toBeNull(); +}); +test('updates data with unchanged IDs and applies min/max bounds', () => { + const {result, rerender} = renderHook(({data}) => useTestTable({data}), { + initialProps: {data: initialData}, + }); + rerender({data: [{id: 'same-id', value: 120}]}); + expect(result.current.columnWidths.value).toBe(200); + rerender({data: [{id: 'same-id', value: 1000}]}); + expect(result.current.columnWidths.value).toBe(500); + rerender({data: [{id: 'same-id', value: -40}]}); + expect(result.current.columnWidths.value).toBe(80); +}); +test('keeps user widths and does not remeasure other columns on resize', () => { + const defs: ColumnDef[] = [ + ...columns, + {id: 'other', accessorKey: 'value', meta: {autoSize: {text: formatText}}}, + ]; + const {result, rerender} = renderHook(({data}) => useTestTable({data, defs}), { + initialProps: {data: initialData}, + }); + expect(formatText).toHaveBeenCalledTimes(2); + act(() => result.current.table.setColumnSizing({value: 60})); + expect(result.current.table.getColumn('value')?.getSize()).toBe(60); + expect(formatText).toHaveBeenCalledTimes(2); + rerender({data: [{id: 'same-id', value: 120}]}); + expect(result.current.table.getColumn('value')?.getSize()).toBe(60); + expect(formatText).toHaveBeenCalledTimes(3); +}); +test('uses the first 100 sorted rows and never measures fixed columns', () => { + const data = Array.from({length: 150}, (_, value) => ({id: String(value), value})); + const defs: ColumnDef[] = [...columns, {id: 'fixed', size: 32}]; + const {result} = renderHook(() => useTestTable({data, defs})); + act(() => result.current.table.setSorting([{id: 'value', desc: true}])); + expect(formatText.mock.calls.slice(-100).map(([, row]) => row)).toEqual( + data.slice(50).reverse(), + ); + expect(result.current.columnWidths.fixed).toBe(32); +}); +test('measureOnce waits for data, measures new columns and refreshes on a style revision', () => { + const {result, rerender} = renderHook((props) => useTestTable({...props, measureOnce: true}), { + initialProps: {data: [] as Item[], defs: columns, revision: undefined as unknown}, + }); + expect(formatText).not.toHaveBeenCalled(); + rerender({data: initialData, defs: columns, revision: undefined}); + rerender({data: [{id: 'same-id', value: 120}], defs: columns, revision: undefined}); + expect(result.current.columnWidths.value).toBe(81); + expect(formatText).toHaveBeenCalledTimes(1); + const defs: ColumnDef[] = [ + ...columns, + {id: 'other', accessorKey: 'value', meta: {autoSize: {text: formatText}}}, + ]; + rerender({data: initialData, defs, revision: undefined}); + expect(formatText).toHaveBeenCalledTimes(2); + rerender({data: initialData, defs, revision: 'new-theme'}); + expect(formatText).toHaveBeenCalledTimes(4); +}); +test('remeasures after fonts load, including measureOnce, and removes its listener on unmount', () => { + const descriptor = Object.getOwnPropertyDescriptor(document, 'fonts'); + const fonts = new EventTarget(); + Object.defineProperty(document, 'fonts', {value: fonts, configurable: true}); + try { + const remove = jest.spyOn(fonts, 'removeEventListener'); + const {unmount} = renderHook(() => useTestTable({measureOnce: true})); + act(() => fonts.dispatchEvent(new Event('loadingdone'))); + expect(formatText).toHaveBeenCalledTimes(2); + unmount(); + expect(remove).toHaveBeenCalledWith('loadingdone', expect.any(Function)); + } finally { + if (descriptor) Object.defineProperty(document, 'fonts', descriptor); + else Reflect.deleteProperty(document, 'fonts'); + } +}); +test('falls back to React for unsupported columns without slowing the described columns', async () => { + const defs: ColumnDef[] = [ + ...columns, + {id: 'unsupported', accessorKey: 'value', header: 'Unsupported'}, + ]; + const {result} = renderHook(() => useTestTable({defs})); + await waitFor(() => expect(result.current.columnWidths.unsupported).toBe(144)); + expect(result.current.columnWidths.value).toBe(81); + expect(measureReact).toHaveBeenCalled(); + expect(document.querySelector('[aria-hidden="true"]')).toBeNull(); +}); +test('a stale React fallback cannot overwrite a newer DOM measurement', async () => { + let finish = (_value: number) => {}; + measureReact.mockImplementationOnce( + () => + new Promise((resolve) => { + finish = resolve; + }), + ); + const defs: ColumnDef[] = [ + { + ...columns[0], + meta: { + autoSize: { + text: (value) => { + if (value === 1) throw Error('fallback'); + return String(80 + Number(value)); + }, + }, + }, + }, + ]; + const {result, rerender} = renderHook(({data}) => useTestTable({data, defs}), { + initialProps: {data: initialData}, + }); + await waitFor(() => expect(measureReact).toHaveBeenCalled()); + rerender({data: [{id: 'same-id', value: 2}]}); + expect(result.current.columnWidths.value).toBe(82); + await act(async () => finish(999)); + expect(result.current.columnWidths.value).toBe(82); +}); + +test('restarts asynchronous fallback correctly under StrictMode', async () => { + const defs: ColumnDef[] = [ + ...columns, + {id: 'unsupported', accessorKey: 'value', header: 'Unsupported'}, + ]; + const {result} = renderHook(() => useTestTable({defs}), {wrapper: React.StrictMode}); + await waitFor(() => expect(result.current.columnWidths.unsupported).toBe(144)); + expect(result.current.columnWidths.value).toBe(81); +}); + +test('keeps a new described column pending until the controlled owner accepts its width', () => { + const onChangeColumnWidths = jest.fn(); + const {result, rerender} = renderHook( + ({defs}) => { + const sized = useColumnsAutoSize({ + columns: defs, + columnWidths: {value: 81}, + onChangeColumnWidths, + options: {measureOnce: true}, + }); + const table = useTable({data: initialData, columns: sized.columnsWithAutoSizes}); + const {setTableInstance} = sized; + React.useLayoutEffect(() => setTableInstance(table), [table, setTableInstance]); + return sized; + }, + {initialProps: {defs: columns}}, + ); + expect(result.current.isMeasuring).toBe(false); + rerender({ + defs: [ + ...columns, + {id: 'other', accessorKey: 'value', meta: {autoSize: {text: formatText}}}, + ], + }); + expect(result.current.isMeasuring).toBe(true); + expect(onChangeColumnWidths).toHaveBeenLastCalledWith({value: 81, other: 81}); +}); diff --git a/src/hooks/useColumnsAutoSize/index.ts b/src/hooks/useColumnsAutoSize/index.ts index 8066014..9d56a15 100644 --- a/src/hooks/useColumnsAutoSize/index.ts +++ b/src/hooks/useColumnsAutoSize/index.ts @@ -1,4 +1,4 @@ export {useColumnsAutoSize} from './useColumnsAutoSize'; export {renderElementForMeasure} from './utils/renderElementForMeasure'; export type {UseColumnsAutoSizeProps} from './useColumnsAutoSize'; -export type {UseColumnsAutoSizeOptions} from './types'; +export type {UseColumnsAutoSizeOptions, ColumnAutoSize, AutoSizeContent} from './types'; diff --git a/src/hooks/useColumnsAutoSize/types.ts b/src/hooks/useColumnsAutoSize/types.ts index bd346f1..312071a 100644 --- a/src/hooks/useColumnsAutoSize/types.ts +++ b/src/hooks/useColumnsAutoSize/types.ts @@ -1,4 +1,6 @@ -import type {ColumnDef, Row} from '@tanstack/react-table'; +import type * as React from 'react'; + +import type {ColumnDef, Row, RowData} from '@tanstack/react-table'; import {useTable} from '../useTable'; @@ -14,6 +16,42 @@ export type UseColumnsAutoSizeOptions = { respectExistingWidths?: boolean; respectResizedWidths?: boolean; measureOnce?: boolean; + /** Let React 18+ interrupt rendering cells after measurement. No-op in React 17. */ + deferUpdates?: boolean; +}; + +export type AutoSizeContent = { + text: string | number; + /** Space reserved for icons/buttons, in px or as a CSS length expression. */ + extraWidth?: number | string; + className?: string; + style?: React.CSSProperties; +}; + +type AutoSizeValue = TResult | ((value: TValue, row: TData) => TResult); + +export type ColumnAutoSize = { + /** Formatted visible text. Defaults to the column accessor's primitive value. */ + text?: AutoSizeValue; + extraWidth?: AutoSizeValue; + className?: AutoSizeValue; + style?: AutoSizeValue; + /** Required for custom React headers; string headers are inferred automatically. */ + header?: string | number | AutoSizeContent; + footer?: ReadonlyArray; +}; + +declare module '@tanstack/react-table' { + interface ColumnMeta { + /** Opt into lightweight DOM sizing without mounting the cell renderer. */ + autoSize?: ColumnAutoSize; + } +} + +export type DOMMeasurementOptions = { + containerRef?: React.RefObject; + className?: string; + revision?: unknown; }; export type CalculateColumnWidthsArgs = UseColumnsAutoSizeOptions & { @@ -24,4 +62,5 @@ export type CalculateColumnWidthsArgs = UseColumnsAutoSiz measurementGeneration: number; sampledRows: Row[]; previousColumnWidths: Record; + domMeasurement?: DOMMeasurementOptions; }; diff --git a/src/hooks/useColumnsAutoSize/useColumnsAutoSize.tsx b/src/hooks/useColumnsAutoSize/useColumnsAutoSize.tsx index 2cf42b5..4cd014c 100644 --- a/src/hooks/useColumnsAutoSize/useColumnsAutoSize.tsx +++ b/src/hooks/useColumnsAutoSize/useColumnsAutoSize.tsx @@ -6,19 +6,30 @@ import {useDeepCompareEffect} from 'react-use'; import type {useTable} from '..'; import {useConditionallyControlledState} from '../useConditionallyControlledState'; +import {useIsomorphicLayoutEffect} from '../useIsomorphicLayoutEffect'; import {cellDefaultWidth, emptyColumnSizing, emptyRows, headerDefaultWidth} from './constants'; import {useMeasureCellWidth} from './hooks/useMeasureCellWidth'; import type {UseMeasureCellWidthProps} from './hooks/useMeasureCellWidth'; -import type {CalculateColumnWidthsArgs, UseColumnsAutoSizeOptions} from './types'; +import type { + CalculateColumnWidthsArgs, + DOMMeasurementOptions, + UseColumnsAutoSizeOptions, +} from './types'; import {getValueFromCell} from './utils/getValueFromCell'; import {hasDefinedWidth} from './utils/hasDefinedWidth'; +import {measureDOMColumns} from './utils/measureDOMColumns'; import {renderHeaderContent} from './utils/renderHeaderContent'; import {setColumnAutoSizes} from './utils/setColumnAutoSizes'; export type UseColumnsAutoSizeProps = { columns: ColumnDef[]; options?: UseColumnsAutoSizeOptions; + /** Font/theme inheritance context for columns with meta.autoSize. Defaults to body. */ + measurementContainerRef?: React.RefObject; + measurementClassName?: string; + /** Invalidate measureOnce after a theme/style change. Font loading is automatic. */ + measurementRevision?: unknown; /** Controlled auto widths, keyed by column ID. Pass with onChangeColumnWidths. */ columnWidths?: Record; /** Called when auto widths change, in controlled or uncontrolled mode. */ @@ -29,6 +40,9 @@ export function useColumnsAutoSize({ columns, options, renderElementForMeasure, + measurementContainerRef, + measurementClassName, + measurementRevision, columnWidths: controlledColumnWidths, onChangeColumnWidths, }: UseColumnsAutoSizeProps) { @@ -59,6 +73,19 @@ export function useColumnsAutoSize({ > | null>(null); const measurementGenerationRef = React.useRef(0); + const domEnabled = columns.some((column) => column.meta?.autoSize !== undefined); + const domMeasurement = React.useMemo( + () => + domEnabled + ? { + containerRef: measurementContainerRef, + className: measurementClassName, + revision: measurementRevision, + } + : undefined, + [domEnabled, measurementContainerRef, measurementClassName, measurementRevision], + ); + const [, refreshSizing] = React.useReducer((revision: number) => revision + 1, 0); const rows = tableInstance?.getRowModel().rows ?? emptyRows; @@ -96,145 +123,248 @@ export function useColumnsAutoSize({ renderElementForMeasure, }); - const calculateWidths = React.useMemo( - () => - debounce( - async ({ - columnSizing, - columns, - measureCellWidth, - sampledRows, - tableInstance, - measurementGeneration, - minWidth = 50, - maxWidth = 500, - padding = 16, - headerPadding = 24, - measureHeaderText = true, - respectExistingWidths = true, - respectResizedWidths = true, - measureOnce = false, - previousColumnWidths, - }: CalculateColumnWidthsArgs) => { - const newWidths: Record = {}; - - const userResizedColumns = respectResizedWidths ? columnSizing : {}; - const isStale = () => - measurementGeneration !== measurementGenerationRef.current; - - for (const column of columns) { - if (isStale()) { - return; - } - - const id = - column.id || - ('accessorKey' in column && String(column.accessorKey)) || - ''; + const calculateWidthsImmediately = React.useCallback( + async ({ + columnSizing, + columns, + measureCellWidth, + sampledRows, + tableInstance, + measurementGeneration, + minWidth = 50, + maxWidth = 500, + padding = 16, + headerPadding = 24, + measureHeaderText = true, + respectExistingWidths = true, + respectResizedWidths = true, + measureOnce = false, + previousColumnWidths, + domMeasurement: dom, + deferUpdates = false, + }: CalculateColumnWidthsArgs) => { + const newWidths: Record = {}; + + const userResizedColumns = respectResizedWidths ? columnSizing : {}; + const isStale = () => measurementGeneration !== measurementGenerationRef.current; + + const domWidths = dom + ? measureDOMColumns({ + columns: columns.filter((column) => { + const id = + column.id || + ('accessorKey' in column && String(column.accessorKey)) || + ''; + return ( + id && + userResizedColumns[id] === undefined && + !(respectExistingWidths && hasDefinedWidth(column)) && + !(measureOnce && previousColumnWidths[id] !== undefined) + ); + }), + rows: sampledRows, + measurement: dom, + options: {padding, headerPadding, measureHeaderText}, + }) + : {}; + + for (const column of columns) { + if (isStale()) { + return; + } - if (!id) continue; + const id = + column.id || ('accessorKey' in column && String(column.accessorKey)) || ''; - if (respectResizedWidths && userResizedColumns[id]) { - newWidths[id] = userResizedColumns[id]; + if (!id) continue; - continue; - } + if (respectResizedWidths && userResizedColumns[id]) { + newWidths[id] = userResizedColumns[id]; - if (respectExistingWidths && hasDefinedWidth(column)) { - if (typeof column.size === 'number') { - newWidths[id] = column.size; - } else if ( - typeof column.minSize === 'number' && - typeof column.maxSize === 'number' && - column.minSize === column.maxSize - ) { - newWidths[id] = column.minSize; - } + continue; + } - continue; - } + if (respectExistingWidths && hasDefinedWidth(column)) { + if (typeof column.size === 'number') { + newWidths[id] = column.size; + } else if ( + typeof column.minSize === 'number' && + typeof column.maxSize === 'number' && + column.minSize === column.maxSize + ) { + newWidths[id] = column.minSize; + } - if (measureOnce && previousColumnWidths[id] !== undefined) { - newWidths[id] = previousColumnWidths[id]; - continue; - } + continue; + } - let maxContentWidth = 0; - - if (measureHeaderText && column.header) { - try { - const headerContent = await renderHeaderContent( - tableInstance, - column, - ); - - if (isStale()) { - return; - } - - const headerWidth = await measureCellWidth(headerContent, 'header'); - - if (isStale()) { - return; - } - - if (headerWidth === 0) { - maxContentWidth = headerDefaultWidth + headerPadding; - } else { - maxContentWidth = headerWidth + headerPadding; - } - } catch { - maxContentWidth = headerDefaultWidth + headerPadding; - } - } + if (measureOnce && previousColumnWidths[id] !== undefined) { + newWidths[id] = previousColumnWidths[id]; + continue; + } - for (const row of sampledRows) { - if (isStale()) { - return; - } + if (domWidths[id] !== undefined) { + newWidths[id] = Math.min(Math.max(domWidths[id], minWidth), maxWidth); + continue; + } - try { - const cellValue = getValueFromCell(tableInstance, column, row); + let maxContentWidth = 0; - if (cellValue === null || cellValue === undefined) { - continue; - } + if (measureHeaderText && column.header) { + try { + const headerContent = await renderHeaderContent(tableInstance, column); - const cellWidth = await measureCellWidth(cellValue, 'cell'); + if (isStale()) { + return; + } - if (isStale()) { - return; - } + const headerWidth = await measureCellWidth(headerContent, 'header'); - maxContentWidth = Math.max(maxContentWidth, cellWidth + padding); - } catch {} + if (isStale()) { + return; } - if (maxContentWidth <= padding) { - maxContentWidth = cellDefaultWidth; + if (headerWidth === 0) { + maxContentWidth = headerDefaultWidth + headerPadding; + } else { + maxContentWidth = headerWidth + headerPadding; } - - newWidths[id] = Math.min(Math.max(maxContentWidth, minWidth), maxWidth); + } catch { + maxContentWidth = headerDefaultWidth + headerPadding; } + } + for (const row of sampledRows) { if (isStale()) { return; } - setColumnWidths((currentWidths) => - Object.keys(currentWidths).length === Object.keys(newWidths).length && - Object.keys(newWidths).every((id) => currentWidths[id] === newWidths[id]) - ? currentWidths - : newWidths, - ); - setIsMeasuring(false); - }, - 100, - ), + try { + const cellValue = getValueFromCell(tableInstance, column, row); + + if (cellValue === null || cellValue === undefined) { + continue; + } + + const cellWidth = await measureCellWidth(cellValue, 'cell'); + + if (isStale()) { + return; + } + + maxContentWidth = Math.max(maxContentWidth, cellWidth + padding); + } catch {} + } + + if (maxContentWidth <= padding) { + maxContentWidth = cellDefaultWidth; + } + + newWidths[id] = Math.min(Math.max(maxContentWidth, minWidth), maxWidth); + } + + if (isStale()) { + return; + } + + const commit = () => { + setColumnWidths((currentWidths) => + Object.keys(currentWidths).length === Object.keys(newWidths).length && + Object.keys(newWidths).every((id) => currentWidths[id] === newWidths[id]) + ? currentWidths + : newWidths, + ); + setIsMeasuring(false); + }; + if (deferUpdates && React.startTransition) React.startTransition(commit); + else commit(); + }, [setColumnWidths], ); + const calculateWidths = React.useMemo( + () => debounce(calculateWidthsImmediately, 100), + [calculateWidthsImmediately], + ); + const [fontRevision, onFontsLoaded] = React.useReducer((revision: number) => revision + 1, 0); + const lastDOMRevision = React.useRef({revision: domMeasurement?.revision, fontRevision}); + const containerRef = domMeasurement?.containerRef; + React.useEffect(() => { + if (!domEnabled) return undefined; + const fonts = (containerRef?.current?.ownerDocument ?? document).fonts; + if (!fonts) return undefined; + fonts.addEventListener('loadingdone', onFontsLoaded); + return () => fonts.removeEventListener('loadingdone', onFontsLoaded); + }, [domEnabled, containerRef]); + + const optionsKey = JSON.stringify(options); + const lastDOMInputs = React.useRef<{ + rows: typeof rows; + columns: typeof columns; + measurement: typeof domMeasurement; + optionsKey: string | undefined; + controlledWidths: typeof controlledColumnWidths; + fontRevision: number; + }>(); + useIsomorphicLayoutEffect(() => { + if (!domMeasurement || !tableInstance) return undefined; + // The owner calls useTable after this hook. Read the model after all hooks + // have updated table.options, not from the preceding render's table state. + const currentRows = tableInstance.getRowModel().rows; + // useTable has just applied the owner's sizing state. Refresh column defs + // once if this hook observed the preceding render's minSize/resize state. + if (tableInstance.getState().columnSizing !== columnSizing) refreshSizing(); + const previous = lastDOMInputs.current; + if ( + previous?.rows === currentRows && + previous.columns === columns && + previous.measurement === domMeasurement && + previous.optionsKey === optionsKey && + previous.controlledWidths === controlledColumnWidths && + previous.fontRevision === fontRevision + ) + return undefined; + lastDOMInputs.current = { + rows: currentRows, + columns, + measurement: domMeasurement, + optionsKey, + controlledWidths: controlledColumnWidths, + fontRevision, + }; + const measurementGeneration = ++measurementGenerationRef.current; + if (!currentRows.length) return undefined; + calculateWidths.cancel(); + const refresh = + !Object.is(lastDOMRevision.current.revision, domMeasurement.revision) || + lastDOMRevision.current.fontRevision !== fontRevision; + lastDOMRevision.current = {revision: domMeasurement.revision, fontRevision}; + calculateWidthsImmediately({ + columnSizing: tableInstance.getState().columnSizing, + columns, + measureCellWidth, + sampledRows: currentRows.slice(0, options?.sampleSize ?? 100), + tableInstance, + ...options, + measureOnce: options?.measureOnce && !refresh, + previousColumnWidths: columnWidths, + measurementGeneration, + domMeasurement, + }); + // Resize alone does not invalidate the input snapshot: dragging must not + // remeasure the other columns. Async React fallbacks check the generation. + return undefined; + }); + React.useEffect( + () => () => { + measurementGenerationRef.current += 1; + lastDOMInputs.current = undefined; + }, + [], + ); + useDeepCompareEffect(() => { + if (domMeasurement) return undefined; const measurementGeneration = ++measurementGenerationRef.current; const cancelMeasurement = () => { if (measurementGenerationRef.current === measurementGeneration) { @@ -269,7 +399,7 @@ export function useColumnsAutoSize({ }); return cancelMeasurement; - }, [columnSizing, rowsDataKey, columnsKey, controlledColumnWidths]); + }, [columnSizing, rowsDataKey, columnsKey, controlledColumnWidths, Boolean(domMeasurement)]); const columnsWithAutoSizes = React.useMemo( () => setColumnAutoSizes(columns, columnWidths, columnSizing), @@ -280,6 +410,6 @@ export function useColumnsAutoSize({ columnWidths, setTableInstance, columnsWithAutoSizes, - isMeasuring: isMeasuring && !hasAllWidths, + isMeasuring: domEnabled ? !hasAllWidths : isMeasuring && !hasAllWidths, }; } diff --git a/src/hooks/useColumnsAutoSize/utils/createDOMMeasureElement.ts b/src/hooks/useColumnsAutoSize/utils/createDOMMeasureElement.ts new file mode 100644 index 0000000..f82c082 --- /dev/null +++ b/src/hooks/useColumnsAutoSize/utils/createDOMMeasureElement.ts @@ -0,0 +1,48 @@ +import type * as React from 'react'; + +const unitlessProperties = new Set( + ( + 'animationIterationCount aspectRatio borderImageOutset borderImageSlice borderImageWidth ' + + 'boxFlex boxFlexGroup boxOrdinalGroup columnCount columns flex flexGrow flexPositive flexShrink ' + + 'flexNegative flexOrder gridArea gridRow gridRowEnd gridRowSpan gridRowStart gridColumn ' + + 'gridColumnEnd gridColumnSpan gridColumnStart fontWeight lineClamp lineHeight opacity order ' + + 'orphans scale tabSize widows zIndex zoom fillOpacity floodOpacity stopOpacity strokeDasharray ' + + 'strokeDashoffset strokeMiterlimit strokeOpacity strokeWidth' + ).split(' '), +); + +export function createDOMMeasureElementFactory(document: Document): ( + tagName: 'div' | 'span', + properties?: { + className?: string; + textContent?: string | number; + styleText?: string; + style?: React.CSSProperties; + }, +) => HTMLElement { + return (tagName, {className, textContent, styleText, style} = {}) => { + const element = document.createElement(tagName); + if (className) element.className = className; + if (textContent !== undefined) element.textContent = String(textContent); + if (styleText) element.style.cssText = styleText; + for (const [property, value] of Object.entries(style ?? {})) { + if (value === undefined || value === null) continue; + const name = property.startsWith('--') + ? property + : property + .replace(/[A-Z]/g, (letter) => `-${letter.toLowerCase()}`) + .replace(/^ms-/, '-ms-'); + const unprefixed = property.replace( + /^(Webkit|Moz|ms|O)([A-Z])/, + (_, _prefix, letter: string) => letter.toLowerCase(), + ); + const needsPx = + typeof value === 'number' && + value !== 0 && + !name.startsWith('--') && + !unitlessProperties.has(unprefixed); + element.style.setProperty(name, needsPx ? `${value}px` : String(value)); + } + return element; + }; +} diff --git a/src/hooks/useColumnsAutoSize/utils/measureDOMColumns.test.ts b/src/hooks/useColumnsAutoSize/utils/measureDOMColumns.test.ts new file mode 100644 index 0000000..4a33c5c --- /dev/null +++ b/src/hooks/useColumnsAutoSize/utils/measureDOMColumns.test.ts @@ -0,0 +1,92 @@ +import type * as React from 'react'; + +import type {ColumnDef, Row} from '@tanstack/react-table'; + +import {createDOMMeasureElementFactory} from './createDOMMeasureElement'; +import {measureDOMColumns} from './measureDOMColumns'; +afterEach(() => jest.restoreAllMocks()); + +test('inserts all columns before a single width read per column, inherits context and cleans up', () => { + const container = document.createElement('section'); + document.body.append(container); + const columns: ColumnDef[] = [ + {id: 'one', meta: {autoSize: {}}}, + {id: 'two', meta: {autoSize: {}}}, + ]; + const read = jest + .spyOn(HTMLElement.prototype, 'getBoundingClientRect') + .mockImplementation(function (this: HTMLElement) { + expect(this.parentElement?.parentElement).toBe(container); + expect(this.parentElement?.children).toHaveLength(2); + expect(this.parentElement?.getAttribute('aria-hidden')).toBe('true'); + return {width: 123.25} as DOMRect; + }); + expect( + measureDOMColumns({ + columns, + rows: [], + measurement: {containerRef: {current: container}}, + options: {}, + }), + ).toEqual({one: 124, two: 124}); + expect(read).toHaveBeenCalledTimes(2); + expect(container.children).toHaveLength(0); + container.remove(); +}); +test('isolates broken text formatters and includes headers, footers and reserved control width', () => { + const rows = [{original: {}, getValue: () => 42}] as unknown as Row[]; + jest.spyOn(HTMLElement.prototype, 'getBoundingClientRect').mockImplementation(function ( + this: HTMLElement, + ) { + expect(this.querySelector('.gt-table__header-cell')?.textContent).toBe('Header'); + expect(this.querySelector('.gt-table__footer-cell')?.textContent).toBe('Total: 42'); + expect(this.querySelector('.gt-table__cell')?.children).toHaveLength(2); + return {width: 100} as DOMRect; + }); + expect( + measureDOMColumns({ + columns: [ + { + id: 'broken', + meta: { + autoSize: { + text: () => { + throw Error('broken'); + }, + }, + }, + }, + { + id: 'healthy', + header: 'Header', + meta: {autoSize: {extraWidth: 24, footer: ['Total: 42']}}, + }, + ], + rows, + measurement: {}, + options: {}, + }), + ).toEqual({healthy: 100}); +}); +test('the DOM factory preserves text and React numeric style semantics', () => { + const createElement = createDOMMeasureElementFactory(document); + const element = createElement('span', { + textContent: ' & 0', + style: { + fontSize: 18, + fontWeight: 700, + letterSpacing: 2, + lineHeight: 1.5, + padding: 0, + flexShrink: 0, + '--size': 20, + } as React.CSSProperties, + }); + expect(element.textContent).toBe(' & 0'); + expect(element.children).toHaveLength(0); + expect(element.style.fontSize).toBe('18px'); + expect(element.style.fontWeight).toBe('700'); + expect(element.style.letterSpacing).toBe('2px'); + expect(element.style.lineHeight).toBe('1.5'); + expect(element.style.getPropertyValue('--size')).toBe('20'); +}); diff --git a/src/hooks/useColumnsAutoSize/utils/measureDOMColumns.ts b/src/hooks/useColumnsAutoSize/utils/measureDOMColumns.ts new file mode 100644 index 0000000..02934c8 --- /dev/null +++ b/src/hooks/useColumnsAutoSize/utils/measureDOMColumns.ts @@ -0,0 +1,141 @@ +import type {ColumnDef, Row} from '@tanstack/react-table'; + +import type {AutoSizeContent, DOMMeasurementOptions, UseColumnsAutoSizeOptions} from '../types'; + +import {createDOMMeasureElementFactory} from './createDOMMeasureElement'; + +const resolve = ( + property: TResult | ((value: unknown, row: TData) => TResult), + value: unknown, + row: TData, +): TResult => + typeof property === 'function' + ? (property as (value: unknown, row: TData) => TResult)(value, row) + : property; + +// Insert all lightweight columns before reading widths. +export function measureDOMColumns({ + columns, + rows, + measurement, + options, +}: { + columns: ColumnDef[]; + rows: Row[]; + measurement: DOMMeasurementOptions; + options: Pick; +}): Record { + const container = measurement.containerRef?.current ?? document.body; + const createElement = createDOMMeasureElementFactory(container.ownerDocument); + const root = createElement('div', { + className: `gt-table gt-styled-table ${measurement.className ?? ''}`, + style: { + position: 'fixed', + top: 0, + left: 0, + visibility: 'hidden', + overflow: 'hidden', + width: 'max-content', + height: 0, + pointerEvents: 'none', + contain: 'layout style', + }, + }); + root.setAttribute('aria-hidden', 'true'); + const createCell = (content: AutoSizeContent, kind: 'cell' | 'header-cell' | 'footer-cell') => { + const cell = createElement('div', { + className: `gt-table__${kind} gt-styled-table__${kind}`, + styleText: `padding-inline:${(kind === 'header-cell' ? (options.headerPadding ?? 24) : (options.padding ?? 16)) / 2}px`, + style: content.style, + }); + cell.append( + createElement('span', { + className: content.className, + textContent: content.text, + styleText: 'display:inline-block;white-space:nowrap', + }), + ); + if (content.extraWidth !== undefined) { + cell.append( + createElement('span', { + styleText: 'display:inline-block', + style: {width: content.extraWidth}, + }), + ); + } + return cell; + }; + const asContent = (value: string | number | AutoSizeContent): AutoSizeContent => + typeof value === 'object' ? value : {text: value}; + const elements: Array<{id: string; element: HTMLElement}> = []; + for (const column of columns) { + const config = column.meta?.autoSize; + const id = column.id || ('accessorKey' in column && String(column.accessorKey)) || ''; + if (!config || !id) continue; + try { + const element = createElement('div', {style: {width: 'max-content'}}); + if (options.measureHeaderText !== false && column.header !== undefined) { + const header = config.header ?? column.header; + // Arbitrary React headers still require the existing React path. + if ( + typeof header !== 'string' && + typeof header !== 'number' && + (typeof header !== 'object' || !('text' in header)) + ) + continue; + element.append( + createCell( + asContent(header as string | number | AutoSizeContent), + 'header-cell', + ), + ); + } + for (const row of rows) { + const value = row.getValue(id); + const text = + config.text === undefined ? value : resolve(config.text, value, row.original); + if ( + text !== null && + text !== undefined && + typeof text !== 'string' && + typeof text !== 'number' + ) { + throw new Error('A lightweight measurement requires primitive text'); + } + element.append( + createCell( + { + text: text ?? '', + extraWidth: resolve(config.extraWidth, value, row.original), + className: resolve(config.className, value, row.original), + style: resolve(config.style, value, row.original), + }, + 'cell', + ), + ); + } + for (const footer of config.footer ?? []) + element.append(createCell(asContent(footer), 'footer-cell')); + root.append(element); + elements.push({id, element}); + } catch { + // An unsupported value or broken formatter falls back for this column only. + } + } + if (!elements.length) return {}; + container.append(root); + try { + const widths: Record = {}; + for (const {id, element} of elements) { + try { + const width = element.getBoundingClientRect().width; + if (Number.isFinite(width) && width >= 0) widths[id] = Math.ceil(width); + } catch { + // Keep measuring the remaining columns and fall back for this one. + } + } + return widths; + } finally { + root.remove(); + } +} diff --git a/src/index.ts b/src/index.ts index 6fd9952..98437a9 100644 --- a/src/index.ts +++ b/src/index.ts @@ -55,6 +55,8 @@ export type { UseTableSettingsOptions, UseColumnsAutoSizeOptions, UseColumnsAutoSizeProps, + ColumnAutoSize, + AutoSizeContent, } from './hooks'; export {getColumnAwareRowOverscan, getVirtualRowRangeExtractor} from './utils'; From c4f0bc507324475206653196b36225a252cca5c2 Mon Sep 17 00:00:00 2001 From: Anastasiia Beriia Date: Mon, 2 Nov 2026 12:41:52 +0300 Subject: [PATCH 02/10] chore: remove auto sizing test additions --- .../domMeasurement.test.tsx | 222 ------------------ .../utils/measureDOMColumns.test.ts | 92 -------- 2 files changed, 314 deletions(-) delete mode 100644 src/hooks/useColumnsAutoSize/domMeasurement.test.tsx delete mode 100644 src/hooks/useColumnsAutoSize/utils/measureDOMColumns.test.ts diff --git a/src/hooks/useColumnsAutoSize/domMeasurement.test.tsx b/src/hooks/useColumnsAutoSize/domMeasurement.test.tsx deleted file mode 100644 index b3dea6c..0000000 --- a/src/hooks/useColumnsAutoSize/domMeasurement.test.tsx +++ /dev/null @@ -1,222 +0,0 @@ -/* eslint-disable testing-library/no-node-access -- Native DOM is the measurement API under test. */ -import * as React from 'react'; - -import type {ColumnDef} from '@tanstack/react-table'; -import {act, renderHook, waitFor} from '@testing-library/react'; - -import {useTable} from '../useTable'; - -import {useMeasureCellWidth} from './hooks/useMeasureCellWidth'; -import {useColumnsAutoSize} from './useColumnsAutoSize'; - -jest.mock('./hooks/useMeasureCellWidth'); -type Item = {id: string; value: number}; -const formatText = jest.fn((value: unknown, _row: Item) => String(80 + Number(value))); -const columns: ColumnDef[] = [ - {id: 'value', accessorKey: 'value', header: 'Value', meta: {autoSize: {text: formatText}}}, -]; -const initialData: Item[] = [{id: 'same-id', value: 1}]; -const measureReact = jest.fn(async () => 120); - -function useTestTable({ - data = initialData, - defs = columns, - revision, - measureOnce = false, -}: { - data?: Item[]; - defs?: ColumnDef[]; - revision?: unknown; - measureOnce?: boolean; -} = {}) { - const result = useColumnsAutoSize({ - columns: defs, - measurementRevision: revision, - options: {minWidth: 80, maxWidth: 500, measureOnce}, - }); - const table = useTable({ - data, - columns: result.columnsWithAutoSizes, - getRowId: (row) => row.id, - enableSorting: true, - enableColumnResizing: true, - }); - const {setTableInstance} = result; - React.useLayoutEffect(() => setTableInstance(table), [table, setTableInstance]); - return {...result, table}; -} - -beforeEach(() => { - formatText.mockClear(); - measureReact.mockReset(); - measureReact.mockResolvedValue(120); - jest.mocked(useMeasureCellWidth).mockReturnValue(measureReact); - jest.spyOn(HTMLElement.prototype, 'getBoundingClientRect').mockImplementation(function ( - this: HTMLElement, - ) { - expect(this.isConnected).toBe(true); - return { - width: Number(this.querySelector('.gt-table__cell span')?.textContent ?? 0), - } as DOMRect; - }); -}); -afterEach(() => jest.restoreAllMocks()); - -test('measures column descriptions before paint without debounce, React renderers or retained DOM', () => { - const {result} = renderHook(() => useTestTable()); - expect(result.current.columnWidths).toEqual({value: 81}); - expect(result.current.isMeasuring).toBe(false); - expect(formatText).toHaveBeenCalledTimes(1); - expect(measureReact).not.toHaveBeenCalled(); - expect(document.querySelector('[aria-hidden="true"]')).toBeNull(); -}); -test('updates data with unchanged IDs and applies min/max bounds', () => { - const {result, rerender} = renderHook(({data}) => useTestTable({data}), { - initialProps: {data: initialData}, - }); - rerender({data: [{id: 'same-id', value: 120}]}); - expect(result.current.columnWidths.value).toBe(200); - rerender({data: [{id: 'same-id', value: 1000}]}); - expect(result.current.columnWidths.value).toBe(500); - rerender({data: [{id: 'same-id', value: -40}]}); - expect(result.current.columnWidths.value).toBe(80); -}); -test('keeps user widths and does not remeasure other columns on resize', () => { - const defs: ColumnDef[] = [ - ...columns, - {id: 'other', accessorKey: 'value', meta: {autoSize: {text: formatText}}}, - ]; - const {result, rerender} = renderHook(({data}) => useTestTable({data, defs}), { - initialProps: {data: initialData}, - }); - expect(formatText).toHaveBeenCalledTimes(2); - act(() => result.current.table.setColumnSizing({value: 60})); - expect(result.current.table.getColumn('value')?.getSize()).toBe(60); - expect(formatText).toHaveBeenCalledTimes(2); - rerender({data: [{id: 'same-id', value: 120}]}); - expect(result.current.table.getColumn('value')?.getSize()).toBe(60); - expect(formatText).toHaveBeenCalledTimes(3); -}); -test('uses the first 100 sorted rows and never measures fixed columns', () => { - const data = Array.from({length: 150}, (_, value) => ({id: String(value), value})); - const defs: ColumnDef[] = [...columns, {id: 'fixed', size: 32}]; - const {result} = renderHook(() => useTestTable({data, defs})); - act(() => result.current.table.setSorting([{id: 'value', desc: true}])); - expect(formatText.mock.calls.slice(-100).map(([, row]) => row)).toEqual( - data.slice(50).reverse(), - ); - expect(result.current.columnWidths.fixed).toBe(32); -}); -test('measureOnce waits for data, measures new columns and refreshes on a style revision', () => { - const {result, rerender} = renderHook((props) => useTestTable({...props, measureOnce: true}), { - initialProps: {data: [] as Item[], defs: columns, revision: undefined as unknown}, - }); - expect(formatText).not.toHaveBeenCalled(); - rerender({data: initialData, defs: columns, revision: undefined}); - rerender({data: [{id: 'same-id', value: 120}], defs: columns, revision: undefined}); - expect(result.current.columnWidths.value).toBe(81); - expect(formatText).toHaveBeenCalledTimes(1); - const defs: ColumnDef[] = [ - ...columns, - {id: 'other', accessorKey: 'value', meta: {autoSize: {text: formatText}}}, - ]; - rerender({data: initialData, defs, revision: undefined}); - expect(formatText).toHaveBeenCalledTimes(2); - rerender({data: initialData, defs, revision: 'new-theme'}); - expect(formatText).toHaveBeenCalledTimes(4); -}); -test('remeasures after fonts load, including measureOnce, and removes its listener on unmount', () => { - const descriptor = Object.getOwnPropertyDescriptor(document, 'fonts'); - const fonts = new EventTarget(); - Object.defineProperty(document, 'fonts', {value: fonts, configurable: true}); - try { - const remove = jest.spyOn(fonts, 'removeEventListener'); - const {unmount} = renderHook(() => useTestTable({measureOnce: true})); - act(() => fonts.dispatchEvent(new Event('loadingdone'))); - expect(formatText).toHaveBeenCalledTimes(2); - unmount(); - expect(remove).toHaveBeenCalledWith('loadingdone', expect.any(Function)); - } finally { - if (descriptor) Object.defineProperty(document, 'fonts', descriptor); - else Reflect.deleteProperty(document, 'fonts'); - } -}); -test('falls back to React for unsupported columns without slowing the described columns', async () => { - const defs: ColumnDef[] = [ - ...columns, - {id: 'unsupported', accessorKey: 'value', header: 'Unsupported'}, - ]; - const {result} = renderHook(() => useTestTable({defs})); - await waitFor(() => expect(result.current.columnWidths.unsupported).toBe(144)); - expect(result.current.columnWidths.value).toBe(81); - expect(measureReact).toHaveBeenCalled(); - expect(document.querySelector('[aria-hidden="true"]')).toBeNull(); -}); -test('a stale React fallback cannot overwrite a newer DOM measurement', async () => { - let finish = (_value: number) => {}; - measureReact.mockImplementationOnce( - () => - new Promise((resolve) => { - finish = resolve; - }), - ); - const defs: ColumnDef[] = [ - { - ...columns[0], - meta: { - autoSize: { - text: (value) => { - if (value === 1) throw Error('fallback'); - return String(80 + Number(value)); - }, - }, - }, - }, - ]; - const {result, rerender} = renderHook(({data}) => useTestTable({data, defs}), { - initialProps: {data: initialData}, - }); - await waitFor(() => expect(measureReact).toHaveBeenCalled()); - rerender({data: [{id: 'same-id', value: 2}]}); - expect(result.current.columnWidths.value).toBe(82); - await act(async () => finish(999)); - expect(result.current.columnWidths.value).toBe(82); -}); - -test('restarts asynchronous fallback correctly under StrictMode', async () => { - const defs: ColumnDef[] = [ - ...columns, - {id: 'unsupported', accessorKey: 'value', header: 'Unsupported'}, - ]; - const {result} = renderHook(() => useTestTable({defs}), {wrapper: React.StrictMode}); - await waitFor(() => expect(result.current.columnWidths.unsupported).toBe(144)); - expect(result.current.columnWidths.value).toBe(81); -}); - -test('keeps a new described column pending until the controlled owner accepts its width', () => { - const onChangeColumnWidths = jest.fn(); - const {result, rerender} = renderHook( - ({defs}) => { - const sized = useColumnsAutoSize({ - columns: defs, - columnWidths: {value: 81}, - onChangeColumnWidths, - options: {measureOnce: true}, - }); - const table = useTable({data: initialData, columns: sized.columnsWithAutoSizes}); - const {setTableInstance} = sized; - React.useLayoutEffect(() => setTableInstance(table), [table, setTableInstance]); - return sized; - }, - {initialProps: {defs: columns}}, - ); - expect(result.current.isMeasuring).toBe(false); - rerender({ - defs: [ - ...columns, - {id: 'other', accessorKey: 'value', meta: {autoSize: {text: formatText}}}, - ], - }); - expect(result.current.isMeasuring).toBe(true); - expect(onChangeColumnWidths).toHaveBeenLastCalledWith({value: 81, other: 81}); -}); diff --git a/src/hooks/useColumnsAutoSize/utils/measureDOMColumns.test.ts b/src/hooks/useColumnsAutoSize/utils/measureDOMColumns.test.ts deleted file mode 100644 index 4a33c5c..0000000 --- a/src/hooks/useColumnsAutoSize/utils/measureDOMColumns.test.ts +++ /dev/null @@ -1,92 +0,0 @@ -import type * as React from 'react'; - -import type {ColumnDef, Row} from '@tanstack/react-table'; - -import {createDOMMeasureElementFactory} from './createDOMMeasureElement'; -import {measureDOMColumns} from './measureDOMColumns'; -afterEach(() => jest.restoreAllMocks()); - -test('inserts all columns before a single width read per column, inherits context and cleans up', () => { - const container = document.createElement('section'); - document.body.append(container); - const columns: ColumnDef[] = [ - {id: 'one', meta: {autoSize: {}}}, - {id: 'two', meta: {autoSize: {}}}, - ]; - const read = jest - .spyOn(HTMLElement.prototype, 'getBoundingClientRect') - .mockImplementation(function (this: HTMLElement) { - expect(this.parentElement?.parentElement).toBe(container); - expect(this.parentElement?.children).toHaveLength(2); - expect(this.parentElement?.getAttribute('aria-hidden')).toBe('true'); - return {width: 123.25} as DOMRect; - }); - expect( - measureDOMColumns({ - columns, - rows: [], - measurement: {containerRef: {current: container}}, - options: {}, - }), - ).toEqual({one: 124, two: 124}); - expect(read).toHaveBeenCalledTimes(2); - expect(container.children).toHaveLength(0); - container.remove(); -}); -test('isolates broken text formatters and includes headers, footers and reserved control width', () => { - const rows = [{original: {}, getValue: () => 42}] as unknown as Row[]; - jest.spyOn(HTMLElement.prototype, 'getBoundingClientRect').mockImplementation(function ( - this: HTMLElement, - ) { - expect(this.querySelector('.gt-table__header-cell')?.textContent).toBe('Header'); - expect(this.querySelector('.gt-table__footer-cell')?.textContent).toBe('Total: 42'); - expect(this.querySelector('.gt-table__cell')?.children).toHaveLength(2); - return {width: 100} as DOMRect; - }); - expect( - measureDOMColumns({ - columns: [ - { - id: 'broken', - meta: { - autoSize: { - text: () => { - throw Error('broken'); - }, - }, - }, - }, - { - id: 'healthy', - header: 'Header', - meta: {autoSize: {extraWidth: 24, footer: ['Total: 42']}}, - }, - ], - rows, - measurement: {}, - options: {}, - }), - ).toEqual({healthy: 100}); -}); -test('the DOM factory preserves text and React numeric style semantics', () => { - const createElement = createDOMMeasureElementFactory(document); - const element = createElement('span', { - textContent: ' & 0', - style: { - fontSize: 18, - fontWeight: 700, - letterSpacing: 2, - lineHeight: 1.5, - padding: 0, - flexShrink: 0, - '--size': 20, - } as React.CSSProperties, - }); - expect(element.textContent).toBe(' & 0'); - expect(element.children).toHaveLength(0); - expect(element.style.fontSize).toBe('18px'); - expect(element.style.fontWeight).toBe('700'); - expect(element.style.letterSpacing).toBe('2px'); - expect(element.style.lineHeight).toBe('1.5'); - expect(element.style.getPropertyValue('--size')).toBe('20'); -}); From e06327d7de22f5a2d7f81439c32c6e46e1c33d61 Mon Sep 17 00:00:00 2001 From: Anastasiia Beriia Date: Mon, 2 Nov 2026 13:26:10 +0300 Subject: [PATCH 03/10] fix: harden column auto sizing lifecycle and layout --- src/hooks/useColumnsAutoSize/README.md | 32 +- .../domMeasurement.test.tsx | 358 ++++++++++++++++++ src/hooks/useColumnsAutoSize/types.ts | 4 +- .../useColumnsAutoSize/useColumnsAutoSize.tsx | 321 ++++++++++------ .../utils/createDOMMeasureElement.ts | 1 + .../useColumnsAutoSize/utils/getColumnId.ts | 14 + .../utils/measureDOMColumns.test.ts | 159 ++++++++ .../utils/measureDOMColumns.ts | 98 +++-- .../utils/setColumnAutoSizes.ts | 16 +- 9 files changed, 861 insertions(+), 142 deletions(-) create mode 100644 src/hooks/useColumnsAutoSize/domMeasurement.test.tsx create mode 100644 src/hooks/useColumnsAutoSize/utils/getColumnId.ts create mode 100644 src/hooks/useColumnsAutoSize/utils/measureDOMColumns.test.ts diff --git a/src/hooks/useColumnsAutoSize/README.md b/src/hooks/useColumnsAutoSize/README.md index dacaa52..57130b4 100644 --- a/src/hooks/useColumnsAutoSize/README.md +++ b/src/hooks/useColumnsAutoSize/README.md @@ -254,10 +254,10 @@ const columns = React.useMemo[]>( id: 'duration', accessorKey: 'duration', header: 'Duration', - cell: ({getValue}) => , + cell: ({getValue}) => ()} />, meta: { autoSize: { - text: (value) => formatDuration(value), + text: (value) => (typeof value === 'number' ? formatDuration(value) : '–'), extraWidth: 24, // space occupied by the cell's icon/button }, }, @@ -301,3 +301,31 @@ sorted/filtered row model. Predefined widths, user resizing, controlled widths a `options.deferUpdates` defaults to `false`. Enable it to let React 18+ interrupt rendering real cells after measurement. React 17 applies updates normally. DOM measurement stays synchronous, so very large samples can still block the thread. + +### Measurement lifecycle and invalidation + +Only positive layout widths are committed. Hidden or detached containers defer +measurement and retry when layout/visibility changes; they do not finalize +`measureOnce` at `minWidth`. CSS layout widths are used rather than transformed +client rectangles, so an ancestor's `transform: scale(...)` does not change sizing. +Empty tables finish loading and can size headers/footers. Header-only widths are +refreshed when the first data arrives, even with `measureOnce`. + +Descriptions on leaf columns inside groups are supported. Equivalent column +arrays, options and controlled-width records are compared structurally. Formatter +functions are compared by identity: use stable callbacks when their behavior has +not changed. `measurementRevision` accepts a string, number, boolean or null; use +a primitive version key rather than an object literal for external style changes. + +DOM descriptions are measured synchronously. In a mixed table their widths can +update immediately, but `isMeasuring` waits for the remaining React columns. +React fallback requests retain the 100 ms debounce and stale results are ignored. +Without a header or nonempty content, the existing default cell width is used. +Resetting TanStack column sizing measures the latest data again rather than +promoting a user's manual width to an automatic width. + +Measurement inherits the table's header, body, row and footer classes. Arbitrary +custom DOM layouts still need a matching text/style description or React fallback. +Broken text formatters and unsupported values produce a development warning before +falling back. The numeric-style utility follows the linked React unitless-property +list; it does not run React renderers during DOM measurement. diff --git a/src/hooks/useColumnsAutoSize/domMeasurement.test.tsx b/src/hooks/useColumnsAutoSize/domMeasurement.test.tsx new file mode 100644 index 0000000..02d2814 --- /dev/null +++ b/src/hooks/useColumnsAutoSize/domMeasurement.test.tsx @@ -0,0 +1,358 @@ +/* eslint-disable testing-library/no-node-access -- Native DOM is the measurement API under test. */ +import * as React from 'react'; + +import type {ColumnDef} from '@tanstack/react-table'; +import {act, renderHook, waitFor} from '@testing-library/react'; + +import {useTable} from '../useTable'; + +import {useMeasureCellWidth} from './hooks/useMeasureCellWidth'; +import {useColumnsAutoSize} from './useColumnsAutoSize'; + +jest.mock('./hooks/useMeasureCellWidth'); +type Item = {id: string; value: number}; +const formatText = jest.fn((value: unknown, _row: Item) => String(80 + Number(value))); +const columns: ColumnDef[] = [ + {id: 'value', accessorKey: 'value', header: 'Value', meta: {autoSize: {text: formatText}}}, +]; +const initialData: Item[] = [{id: 'same-id', value: 1}]; +const measureReact = jest.fn(async () => 120); + +function useTestTable({ + data = initialData, + defs = columns, + revision, + measureOnce = false, + containerRef, +}: { + data?: Item[]; + defs?: ColumnDef[]; + revision?: string | number | boolean | null; + containerRef?: React.RefObject; + measureOnce?: boolean; +} = {}) { + const result = useColumnsAutoSize({ + columns: defs, + measurementRevision: revision, + measurementContainerRef: containerRef, + options: {minWidth: 80, maxWidth: 500, measureOnce}, + }); + const table = useTable({ + data, + columns: result.columnsWithAutoSizes, + getRowId: (row) => row.id, + enableSorting: true, + enableColumnResizing: true, + }); + const {setTableInstance} = result; + React.useLayoutEffect(() => setTableInstance(table), [table, setTableInstance]); + return {...result, table}; +} + +beforeEach(() => { + jest.spyOn(HTMLElement.prototype, 'getClientRects').mockImplementation(function ( + this: HTMLElement, + ) { + return (this.isConnected ? [{}] : []) as unknown as DOMRectList; + }); + jest.spyOn(HTMLElement.prototype, 'offsetWidth', 'get').mockImplementation(function ( + this: HTMLElement, + ) { + return this.getBoundingClientRect().width; + }); + + formatText.mockClear(); + measureReact.mockReset(); + measureReact.mockResolvedValue(120); + jest.mocked(useMeasureCellWidth).mockReturnValue(measureReact); + jest.spyOn(HTMLElement.prototype, 'getBoundingClientRect').mockImplementation(function ( + this: HTMLElement, + ) { + expect(this.isConnected).toBe(true); + return { + width: Number(this.querySelector('.gt-table__cell span')?.textContent ?? 0), + } as DOMRect; + }); +}); +afterEach(() => jest.restoreAllMocks()); + +test('measures column descriptions before paint without debounce, React renderers or retained DOM', () => { + const {result} = renderHook(() => useTestTable()); + expect(result.current.columnWidths).toEqual({value: 81}); + expect(result.current.isMeasuring).toBe(false); + expect(formatText).toHaveBeenCalledTimes(1); + expect(measureReact).not.toHaveBeenCalled(); + expect(document.querySelector('[aria-hidden="true"]')).toBeNull(); +}); +test('updates data with unchanged IDs and applies min/max bounds', () => { + const {result, rerender} = renderHook(({data}) => useTestTable({data}), { + initialProps: {data: initialData}, + }); + rerender({data: [{id: 'same-id', value: 120}]}); + expect(result.current.columnWidths.value).toBe(200); + rerender({data: [{id: 'same-id', value: 1000}]}); + expect(result.current.columnWidths.value).toBe(500); + rerender({data: [{id: 'same-id', value: -40}]}); + expect(result.current.columnWidths.value).toBe(80); +}); +test('keeps user widths and does not remeasure other columns on resize', () => { + const defs: ColumnDef[] = [ + ...columns, + {id: 'other', accessorKey: 'value', meta: {autoSize: {text: formatText}}}, + ]; + const {result, rerender} = renderHook(({data}) => useTestTable({data, defs}), { + initialProps: {data: initialData}, + }); + expect(formatText).toHaveBeenCalledTimes(2); + act(() => result.current.table.setColumnSizing({value: 60})); + expect(result.current.table.getColumn('value')?.getSize()).toBe(60); + expect(formatText).toHaveBeenCalledTimes(2); + rerender({data: [{id: 'same-id', value: 120}]}); + expect(result.current.table.getColumn('value')?.getSize()).toBe(60); + expect(formatText).toHaveBeenCalledTimes(3); +}); +test('uses the first 100 sorted rows and never measures fixed columns', () => { + const data = Array.from({length: 150}, (_, value) => ({id: String(value), value})); + const defs: ColumnDef[] = [...columns, {id: 'fixed', size: 32}]; + const {result} = renderHook(() => useTestTable({data, defs})); + act(() => result.current.table.setSorting([{id: 'value', desc: true}])); + expect(formatText.mock.calls.slice(-100).map(([, row]) => row)).toEqual( + data.slice(50).reverse(), + ); + expect(result.current.columnWidths.fixed).toBe(32); +}); +test('measureOnce waits for data, measures new columns and refreshes on a style revision', () => { + const {result, rerender} = renderHook((props) => useTestTable({...props, measureOnce: true}), { + initialProps: { + data: [] as Item[], + defs: columns, + revision: undefined as string | undefined, + }, + }); + expect(formatText).not.toHaveBeenCalled(); + rerender({data: initialData, defs: columns, revision: undefined}); + rerender({data: [{id: 'same-id', value: 120}], defs: columns, revision: undefined}); + expect(result.current.columnWidths.value).toBe(81); + expect(formatText).toHaveBeenCalledTimes(1); + const defs: ColumnDef[] = [ + ...columns, + {id: 'other', accessorKey: 'value', meta: {autoSize: {text: formatText}}}, + ]; + rerender({data: initialData, defs, revision: undefined}); + expect(formatText).toHaveBeenCalledTimes(2); + rerender({data: initialData, defs, revision: 'new-theme'}); + expect(formatText).toHaveBeenCalledTimes(4); +}); +test('remeasures after fonts load, including measureOnce, and removes its listener on unmount', () => { + const descriptor = Object.getOwnPropertyDescriptor(document, 'fonts'); + const fonts = new EventTarget(); + Object.defineProperty(document, 'fonts', {value: fonts, configurable: true}); + try { + const remove = jest.spyOn(fonts, 'removeEventListener'); + const {unmount} = renderHook(() => useTestTable({measureOnce: true})); + act(() => fonts.dispatchEvent(new Event('loadingdone'))); + expect(formatText).toHaveBeenCalledTimes(2); + unmount(); + expect(remove).toHaveBeenCalledWith('loadingdone', expect.any(Function)); + } finally { + if (descriptor) Object.defineProperty(document, 'fonts', descriptor); + else Reflect.deleteProperty(document, 'fonts'); + } +}); +test('falls back to React for unsupported columns without slowing the described columns', async () => { + const defs: ColumnDef[] = [ + ...columns, + {id: 'unsupported', accessorKey: 'value', header: 'Unsupported'}, + ]; + const {result} = renderHook(() => useTestTable({defs})); + await waitFor(() => expect(result.current.columnWidths.unsupported).toBe(144)); + expect(result.current.columnWidths.value).toBe(81); + expect(measureReact).toHaveBeenCalled(); + expect(document.querySelector('[aria-hidden="true"]')).toBeNull(); +}); +test('a stale React fallback cannot overwrite a newer DOM measurement', async () => { + let finish = (_value: number) => {}; + measureReact.mockImplementationOnce( + () => + new Promise((resolve) => { + finish = resolve; + }), + ); + const defs: ColumnDef[] = [ + { + ...columns[0], + meta: { + autoSize: { + text: (value) => { + if (value === 1) throw Error('fallback'); + return String(80 + Number(value)); + }, + }, + }, + }, + ]; + const {result, rerender} = renderHook(({data}) => useTestTable({data, defs}), { + initialProps: {data: initialData}, + }); + await waitFor(() => expect(measureReact).toHaveBeenCalled()); + rerender({data: [{id: 'same-id', value: 2}]}); + expect(result.current.columnWidths.value).toBe(82); + await act(async () => finish(999)); + expect(result.current.columnWidths.value).toBe(82); +}); + +test('restarts asynchronous fallback correctly under StrictMode', async () => { + const defs: ColumnDef[] = [ + ...columns, + {id: 'unsupported', accessorKey: 'value', header: 'Unsupported'}, + ]; + const {result} = renderHook(() => useTestTable({defs}), {wrapper: React.StrictMode}); + await waitFor(() => expect(result.current.columnWidths.unsupported).toBe(144)); + expect(result.current.columnWidths.value).toBe(81); +}); + +test('keeps a new described column pending until the controlled owner accepts its width', () => { + const onChangeColumnWidths = jest.fn(); + const {result, rerender} = renderHook( + ({defs}) => { + const sized = useColumnsAutoSize({ + columns: defs, + columnWidths: {value: 81}, + onChangeColumnWidths, + options: {measureOnce: true}, + }); + const table = useTable({data: initialData, columns: sized.columnsWithAutoSizes}); + const {setTableInstance} = sized; + React.useLayoutEffect(() => setTableInstance(table), [table, setTableInstance]); + return sized; + }, + {initialProps: {defs: columns}}, + ); + expect(result.current.isMeasuring).toBe(false); + rerender({ + defs: [ + ...columns, + {id: 'other', accessorKey: 'value', meta: {autoSize: {text: formatText}}}, + ], + }); + expect(result.current.isMeasuring).toBe(true); + expect(onChangeColumnWidths).toHaveBeenLastCalledWith({value: 81, other: 81}); +}); + +test('empty data finishes loading and measureOnce still measures the first data', () => { + jest.spyOn(HTMLElement.prototype, 'offsetWidth', 'get').mockImplementation(function ( + this: HTMLElement, + ) { + return Number(this.querySelector('.gt-table__cell span')?.textContent ?? 100); + }); + const {result, rerender} = renderHook(({data}) => useTestTable({data, measureOnce: true}), { + initialProps: {data: [] as Item[]}, + }); + expect(result.current.isMeasuring).toBe(false); + expect(result.current.columnWidths.value).toBe(100); + rerender({data: [{id: 'same-id', value: 120}]}); + expect(result.current.columnWidths.value).toBe(200); +}); + +test('resetting resize restores auto sizing for the latest data, also with measureOnce', () => { + const {result, rerender} = renderHook(({data}) => useTestTable({data, measureOnce: true}), { + initialProps: {data: initialData}, + }); + act(() => result.current.table.setColumnSizing({value: 200})); + rerender({data: [{id: 'same-id', value: 120}]}); + expect(result.current.columnWidths.value).toBe(81); + act(() => result.current.table.resetColumnSizing()); + expect(result.current.columnWidths.value).toBe(200); + expect(result.current.table.getColumn('value')?.getSize()).toBe(200); +}); + +test('equivalent fresh arrays and controlled widths do not trigger measurements', () => { + const {rerender} = renderHook( + ({tick: _tick}) => { + const sized = useColumnsAutoSize({ + columns: columns.map((c) => ({...c})), + columnWidths: {value: 81}, + onChangeColumnWidths: () => {}, + }); + const table = useTable({data: initialData, columns: sized.columnsWithAutoSizes}); + const {setTableInstance} = sized; + React.useLayoutEffect(() => setTableInstance(table), [table, setTableInstance]); + return sized; + }, + {initialProps: {tick: 0}}, + ); + const count = formatText.mock.calls.length; + rerender({tick: 1}); + rerender({tick: 2}); + expect(formatText).toHaveBeenCalledTimes(count); +}); + +test('leaf descriptions work inside grouped columns', () => { + const defs: ColumnDef[] = [{id: 'group', header: 'Group', columns}]; + const {result} = renderHook(() => useTestTable({defs})); + expect(result.current.columnWidths.value).toBe(81); +}); + +test('mixed-column React fallback remains debounced while DOM descriptions update immediately', async () => { + const defs: ColumnDef[] = [ + ...columns, + {id: 'fallback', accessorKey: 'value', header: 'Fallback'}, + ]; + const {result, rerender} = renderHook(({data}) => useTestTable({defs, data}), { + initialProps: {data: initialData}, + }); + rerender({data: [{id: 'same-id', value: 2}]}); + rerender({data: [{id: 'same-id', value: 3}]}); + expect(result.current.columnWidths.value).toBe(83); + expect(measureReact).not.toHaveBeenCalled(); + await waitFor(() => expect(result.current.columnWidths.fallback).toBe(144)); + expect(measureReact).toHaveBeenCalledTimes(2); +}); + +test('a hidden measureOnce table retries on visibility and never freezes minWidth', () => { + let retry = () => {}; + const original = Object.getOwnPropertyDescriptor(globalThis, 'ResizeObserver'); + Object.defineProperty(globalThis, 'ResizeObserver', { + configurable: true, + value: class { + constructor(callback: () => void) { + retry = callback; + } + observe() {} + disconnect() {} + }, + }); + const container = document.createElement('div'); + document.body.append(container); + let visible = false; + jest.spyOn(container, 'getClientRects').mockImplementation( + () => (visible ? [{}] : []) as unknown as DOMRectList, + ); + try { + const {result, unmount} = renderHook(() => + useTestTable({measureOnce: true, containerRef: {current: container}}), + ); + expect(result.current.columnWidths.value).toBeUndefined(); + visible = true; + act(() => retry()); + expect(result.current.columnWidths.value).toBe(81); + expect(result.current.isMeasuring).toBe(false); + unmount(); + } finally { + container.remove(); + if (original) Object.defineProperty(globalThis, 'ResizeObserver', original); + else Reflect.deleteProperty(globalThis, 'ResizeObserver'); + } +}); + +test('resize ticks do not force another owner render', () => { + const rendered = jest.fn(); + const {result} = renderHook(() => { + rendered(); + return useTestTable(); + }); + act(() => result.current.table.setColumnSizing({value: 200})); + const before = rendered.mock.calls.length; + act(() => result.current.table.setColumnSizing({value: 210})); + expect(rendered.mock.calls.length - before).toBe(1); +}); diff --git a/src/hooks/useColumnsAutoSize/types.ts b/src/hooks/useColumnsAutoSize/types.ts index 312071a..e72711d 100644 --- a/src/hooks/useColumnsAutoSize/types.ts +++ b/src/hooks/useColumnsAutoSize/types.ts @@ -51,7 +51,7 @@ declare module '@tanstack/react-table' { export type DOMMeasurementOptions = { containerRef?: React.RefObject; className?: string; - revision?: unknown; + revision?: string | number | boolean | null; }; export type CalculateColumnWidthsArgs = UseColumnsAutoSizeOptions & { @@ -62,5 +62,5 @@ export type CalculateColumnWidthsArgs = UseColumnsAutoSiz measurementGeneration: number; sampledRows: Row[]; previousColumnWidths: Record; - domMeasurement?: DOMMeasurementOptions; + partial?: boolean; }; diff --git a/src/hooks/useColumnsAutoSize/useColumnsAutoSize.tsx b/src/hooks/useColumnsAutoSize/useColumnsAutoSize.tsx index 4cd014c..ed813be 100644 --- a/src/hooks/useColumnsAutoSize/useColumnsAutoSize.tsx +++ b/src/hooks/useColumnsAutoSize/useColumnsAutoSize.tsx @@ -2,6 +2,7 @@ import * as React from 'react'; import type {ColumnDef} from '@tanstack/react-table'; import debounce from 'lodash/debounce.js'; +import isEqual from 'lodash/isEqual.js'; import {useDeepCompareEffect} from 'react-use'; import type {useTable} from '..'; @@ -16,6 +17,7 @@ import type { DOMMeasurementOptions, UseColumnsAutoSizeOptions, } from './types'; +import {getColumnId, getLeafColumns} from './utils/getColumnId'; import {getValueFromCell} from './utils/getValueFromCell'; import {hasDefinedWidth} from './utils/hasDefinedWidth'; import {measureDOMColumns} from './utils/measureDOMColumns'; @@ -29,7 +31,7 @@ export type UseColumnsAutoSizeProps = { measurementContainerRef?: React.RefObject; measurementClassName?: string; /** Invalidate measureOnce after a theme/style change. Font loading is automatic. */ - measurementRevision?: unknown; + measurementRevision?: string | number | boolean | null; /** Controlled auto widths, keyed by column ID. Pass with onChangeColumnWidths. */ columnWidths?: Record; /** Called when auto widths change, in controlled or uncontrolled mode. */ @@ -46,6 +48,7 @@ export function useColumnsAutoSize({ columnWidths: controlledColumnWidths, onChangeColumnWidths, }: UseColumnsAutoSizeProps) { + const leafColumns = React.useMemo(() => getLeafColumns(columns), [columns]); const [rawColumnWidths, setColumnWidths] = useConditionallyControlledState( controlledColumnWidths, onChangeColumnWidths, @@ -53,16 +56,17 @@ export function useColumnsAutoSize({ ); const columnWidths = React.useMemo(() => { const widths: Record = {}; - for (const column of columns) { - const id = column.id || ('accessorKey' in column && String(column.accessorKey)) || ''; + for (const column of leafColumns) { + const id = getColumnId(column); const width = rawColumnWidths[id]; if (width !== undefined && Number.isFinite(width) && width > 0) widths[id] = width; } return widths; - }, [columns, rawColumnWidths]); - const hasAllWidths = columns.every((column) => { - const id = column.id || ('accessorKey' in column && String(column.accessorKey)) || ''; + }, [leafColumns, rawColumnWidths]); + const hasAllWidths = leafColumns.every((column) => { + const id = getColumnId(column); return ( + !id || columnWidths[id] !== undefined || (options?.respectExistingWidths !== false && hasDefinedWidth(column)) ); @@ -73,7 +77,7 @@ export function useColumnsAutoSize({ > | null>(null); const measurementGenerationRef = React.useRef(0); - const domEnabled = columns.some((column) => column.meta?.autoSize !== undefined); + const domEnabled = leafColumns.some((column) => column.meta?.autoSize !== undefined); const domMeasurement = React.useMemo( () => domEnabled @@ -85,7 +89,6 @@ export function useColumnsAutoSize({ : undefined, [domEnabled, measurementContainerRef, measurementClassName, measurementRevision], ); - const [, refreshSizing] = React.useReducer((revision: number) => revision + 1, 0); const rows = tableInstance?.getRowModel().rows ?? emptyRows; @@ -93,9 +96,7 @@ export function useColumnsAutoSize({ const columnSizing = tableInstance?.getState().columnSizing ?? emptyColumnSizing; const rowsDataKey = sampledRows.map((row) => row.id).join(','); - const columnIds = columns.map( - (column) => column.id || ('accessorKey' in column && String(column.accessorKey)) || '', - ); + const columnIds = leafColumns.map(getColumnId); const columnsKey = JSON.stringify(columnIds); React.useEffect(() => { @@ -140,7 +141,7 @@ export function useColumnsAutoSize({ respectResizedWidths = true, measureOnce = false, previousColumnWidths, - domMeasurement: dom, + partial = false, deferUpdates = false, }: CalculateColumnWidthsArgs) => { const newWidths: Record = {}; @@ -148,38 +149,17 @@ export function useColumnsAutoSize({ const userResizedColumns = respectResizedWidths ? columnSizing : {}; const isStale = () => measurementGeneration !== measurementGenerationRef.current; - const domWidths = dom - ? measureDOMColumns({ - columns: columns.filter((column) => { - const id = - column.id || - ('accessorKey' in column && String(column.accessorKey)) || - ''; - return ( - id && - userResizedColumns[id] === undefined && - !(respectExistingWidths && hasDefinedWidth(column)) && - !(measureOnce && previousColumnWidths[id] !== undefined) - ); - }), - rows: sampledRows, - measurement: dom, - options: {padding, headerPadding, measureHeaderText}, - }) - : {}; - for (const column of columns) { if (isStale()) { return; } - const id = - column.id || ('accessorKey' in column && String(column.accessorKey)) || ''; + const id = getColumnId(column); if (!id) continue; if (respectResizedWidths && userResizedColumns[id]) { - newWidths[id] = userResizedColumns[id]; + if (!partial) newWidths[id] = userResizedColumns[id]; continue; } @@ -203,11 +183,6 @@ export function useColumnsAutoSize({ continue; } - if (domWidths[id] !== undefined) { - newWidths[id] = Math.min(Math.max(domWidths[id], minWidth), maxWidth); - continue; - } - let maxContentWidth = 0; if (measureHeaderText && column.header) { @@ -268,16 +243,25 @@ export function useColumnsAutoSize({ } const commit = () => { - setColumnWidths((currentWidths) => - Object.keys(currentWidths).length === Object.keys(newWidths).length && - Object.keys(newWidths).every((id) => currentWidths[id] === newWidths[id]) - ? currentWidths - : newWidths, - ); + setColumnWidths((currentWidths) => { + const result = partial ? {...currentWidths, ...newWidths} : newWidths; + // Never copy a manual width into the auto-width store. + if (partial) + for (const id of Object.keys( + tableInstance?.getState().columnSizing ?? {}, + )) { + if (currentWidths[id] === undefined) delete result[id]; + else result[id] = currentWidths[id]; + } + return isEqual(currentWidths, result) ? currentWidths : result; + }); setIsMeasuring(false); }; - if (deferUpdates && React.startTransition) React.startTransition(commit); - else commit(); + if (deferUpdates && React.startTransition) { + React.startTransition(commit); + } else { + commit(); + } }, [setColumnWidths], ); @@ -287,80 +271,192 @@ export function useColumnsAutoSize({ [calculateWidthsImmediately], ); const [fontRevision, onFontsLoaded] = React.useReducer((revision: number) => revision + 1, 0); - const lastDOMRevision = React.useRef({revision: domMeasurement?.revision, fontRevision}); - const containerRef = domMeasurement?.containerRef; - React.useEffect(() => { + const [layoutRevision, retryLayout] = React.useReducer((revision: number) => revision + 1, 0); + const [waitingForLayout, setWaitingForLayout] = React.useState(false); + const headerOnly = React.useRef(new Set()); + const previousSizing = React.useRef>({}); + const lastDOMInputs = React.useRef< + | { + rows: Array<{id: string; original: TData}>; + columns: ColumnDef[]; + measurement: { + container: HTMLElement | null; + className?: string; + revision?: typeof measurementRevision; + }; + options: typeof options; + controlledWidths: typeof controlledColumnWidths; + fontRevision: number; + layoutRevision: number; + } + | undefined + >(undefined); + useIsomorphicLayoutEffect(() => { if (!domEnabled) return undefined; - const fonts = (containerRef?.current?.ownerDocument ?? document).fonts; + const fonts = (measurementContainerRef?.current?.ownerDocument ?? document).fonts; if (!fonts) return undefined; - fonts.addEventListener('loadingdone', onFontsLoaded); - return () => fonts.removeEventListener('loadingdone', onFontsLoaded); - }, [domEnabled, containerRef]); - - const optionsKey = JSON.stringify(options); - const lastDOMInputs = React.useRef<{ - rows: typeof rows; - columns: typeof columns; - measurement: typeof domMeasurement; - optionsKey: string | undefined; - controlledWidths: typeof controlledColumnWidths; - fontRevision: number; - }>(); + let active = true; + let initialPending = fonts.status === 'loading'; + const loaded = () => { + if (!active || fonts.status === 'loading') return; + initialPending = false; + onFontsLoaded(); + }; + // Subscribe before measuring. ready also covers a load started before mount. + fonts.addEventListener('loadingdone', loaded); + fonts.ready?.then(() => { + if (initialPending) loaded(); + }); + return () => { + active = false; + fonts.removeEventListener('loadingdone', loaded); + }; + }, [domEnabled, measurementContainerRef]); + React.useEffect(() => { + if (!waitingForLayout) return undefined; + const container = measurementContainerRef?.current ?? document.body; + let wasConnected = container.isConnected; + const retry = () => { + if ( + !container.isConnected || + (!container.getClientRects().length && + container.ownerDocument.defaultView?.getComputedStyle(container).display !== + 'contents') + ) + return; + retryLayout(); + }; + const resize = typeof ResizeObserver === 'function' ? new ResizeObserver(retry) : undefined; + const mutation = new MutationObserver((records) => { + if ( + records.some( + (record) => + record.type === 'attributes' && + (record.target === container || + (record.target as Element).contains(container)), + ) || + (!wasConnected && container.isConnected) + ) + retry(); + wasConnected = container.isConnected; + }); + resize?.observe(container); + mutation.observe(container.ownerDocument.documentElement, { + attributes: true, + childList: true, + subtree: true, + }); + return () => { + resize?.disconnect(); + mutation.disconnect(); + }; + }, [waitingForLayout, measurementContainerRef]); + useIsomorphicLayoutEffect(() => { - if (!domMeasurement || !tableInstance) return undefined; - // The owner calls useTable after this hook. Read the model after all hooks - // have updated table.options, not from the preceding render's table state. - const currentRows = tableInstance.getRowModel().rows; - // useTable has just applied the owner's sizing state. Refresh column defs - // once if this hook observed the preceding render's minSize/resize state. - if (tableInstance.getState().columnSizing !== columnSizing) refreshSizing(); - const previous = lastDOMInputs.current; - if ( - previous?.rows === currentRows && - previous.columns === columns && - previous.measurement === domMeasurement && - previous.optionsKey === optionsKey && - previous.controlledWidths === controlledColumnWidths && - previous.fontRevision === fontRevision - ) - return undefined; - lastDOMInputs.current = { - rows: currentRows, - columns, - measurement: domMeasurement, - optionsKey, + if (!domMeasurement || !tableInstance) return; + const currentRows = tableInstance.getRowModel().rows.slice(0, options?.sampleSize ?? 100); + const inputs = { + rows: currentRows.map((row) => ({id: row.id, original: row.original})), + columns: leafColumns, + measurement: { + container: measurementContainerRef?.current ?? null, + className: measurementClassName, + revision: measurementRevision, + }, + options, controlledWidths: controlledColumnWidths, fontRevision, + layoutRevision, }; - const measurementGeneration = ++measurementGenerationRef.current; - if (!currentRows.length) return undefined; + const sizing = tableInstance.getState().columnSizing; + const released = Object.keys(previousSizing.current).filter( + (id) => sizing[id] === undefined, + ); + const added = Object.keys(sizing).filter((id) => previousSizing.current[id] === undefined); + previousSizing.current = sizing; + const previous = lastDOMInputs.current; + const changed = !isEqual(previous, inputs); + if (!changed && !released.length && !added.length) return; + lastDOMInputs.current = inputs; + const generation = ++measurementGenerationRef.current; calculateWidths.cancel(); const refresh = - !Object.is(lastDOMRevision.current.revision, domMeasurement.revision) || - lastDOMRevision.current.fontRevision !== fontRevision; - lastDOMRevision.current = {revision: domMeasurement.revision, fontRevision}; - calculateWidthsImmediately({ - columnSizing: tableInstance.getState().columnSizing, - columns, - measureCellWidth, - sampledRows: currentRows.slice(0, options?.sampleSize ?? 100), - tableInstance, - ...options, - measureOnce: options?.measureOnce && !refresh, - previousColumnWidths: columnWidths, - measurementGeneration, - domMeasurement, + previous && + (previous.fontRevision !== fontRevision || + previous.measurement.revision !== measurementRevision); + const force = new Set(released); + if (currentRows.length) for (const id of headerOnly.current) force.add(id); + const pending = leafColumns.filter((column) => { + const id = getColumnId(column); + if (!id || (options?.respectExistingWidths !== false && hasDefinedWidth(column))) + return false; + if (options?.respectResizedWidths !== false && sizing[id] !== undefined) return false; + if (!changed && !force.has(id) && columnWidths[id] !== undefined) return false; + return ( + !options?.measureOnce || refresh || force.has(id) || columnWidths[id] === undefined + ); }); - // Resize alone does not invalidate the input snapshot: dragging must not - // remeasure the other columns. Async React fallbacks check the generation. - return undefined; + const measured = measureDOMColumns({ + columns: pending, + rows: currentRows, + measurement: domMeasurement, + options: options ?? {}, + }); + if (measured === undefined) { + setWaitingForLayout(true); + if (!currentRows.length) setIsMeasuring(false); + return; + } + setWaitingForLayout(false); + const fallback = pending.filter((column) => measured[getColumnId(column)] === undefined); + for (const column of fallback) { + const id = getColumnId(column); + if (!currentRows.length) headerOnly.current.add(id); + else headerOnly.current.delete(id); + } + const widths = {...columnWidths}; + for (const column of leafColumns) { + const id = getColumnId(column); + if (!id) continue; + if (options?.respectExistingWidths !== false && hasDefinedWidth(column)) { + widths[id] = column.size ?? column.minSize!; + } + if (measured[id] !== undefined) { + widths[id] = Math.min( + options?.maxWidth ?? 500, + Math.max(options?.minWidth ?? 50, measured[id]), + ); + if (!currentRows.length) headerOnly.current.add(id); + else headerOnly.current.delete(id); + } + } + const commit = () => { + setColumnWidths((current) => (isEqual(current, widths) ? current : widths)); + if (isMeasuring !== fallback.length > 0) setIsMeasuring(fallback.length > 0); + }; + if (options?.deferUpdates && React.startTransition) React.startTransition(commit); + else commit(); + if (fallback.length) + calculateWidths({ + columns: fallback, + columnSizing: sizing, + sampledRows: currentRows, + tableInstance, + measureCellWidth, + measurementGeneration: generation, + ...options, + measureOnce: false, + previousColumnWidths: widths, + partial: true, + }); }); React.useEffect( () => () => { measurementGenerationRef.current += 1; + calculateWidths.cancel(); lastDOMInputs.current = undefined; }, - [], + [calculateWidths], ); useDeepCompareEffect(() => { @@ -389,7 +485,7 @@ export function useColumnsAutoSize({ calculateWidths({ columnSizing, - columns, + columns: leafColumns, measureCellWidth, sampledRows, tableInstance, @@ -401,15 +497,18 @@ export function useColumnsAutoSize({ return cancelMeasurement; }, [columnSizing, rowsDataKey, columnsKey, controlledColumnWidths, Boolean(domMeasurement)]); + const appliedSizing = domEnabled ? emptyColumnSizing : columnSizing; const columnsWithAutoSizes = React.useMemo( - () => setColumnAutoSizes(columns, columnWidths, columnSizing), - [columns, columnWidths, columnSizing], + () => setColumnAutoSizes(columns, columnWidths, appliedSizing, !domEnabled), + [columns, columnWidths, appliedSizing, domEnabled], ); return { columnWidths, setTableInstance, columnsWithAutoSizes, - isMeasuring: domEnabled ? !hasAllWidths : isMeasuring && !hasAllWidths, + isMeasuring: domEnabled + ? rows.length > 0 && (!hasAllWidths || isMeasuring) + : isMeasuring && !hasAllWidths, }; } diff --git a/src/hooks/useColumnsAutoSize/utils/createDOMMeasureElement.ts b/src/hooks/useColumnsAutoSize/utils/createDOMMeasureElement.ts index f82c082..609865e 100644 --- a/src/hooks/useColumnsAutoSize/utils/createDOMMeasureElement.ts +++ b/src/hooks/useColumnsAutoSize/utils/createDOMMeasureElement.ts @@ -1,5 +1,6 @@ import type * as React from 'react'; +// Numeric CSS rules follow React: https://github.com/facebook/react/blob/v19.0.0/packages/react-dom-bindings/src/shared/isUnitlessNumber.js const unitlessProperties = new Set( ( 'animationIterationCount aspectRatio borderImageOutset borderImageSlice borderImageWidth ' + diff --git a/src/hooks/useColumnsAutoSize/utils/getColumnId.ts b/src/hooks/useColumnsAutoSize/utils/getColumnId.ts new file mode 100644 index 0000000..61ac634 --- /dev/null +++ b/src/hooks/useColumnsAutoSize/utils/getColumnId.ts @@ -0,0 +1,14 @@ +import type {ColumnDef} from '@tanstack/react-table'; + +export function getColumnId(column: ColumnDef): string { + if (column.id !== undefined) return column.id; + if ('accessorKey' in column && column.accessorKey) + return String(column.accessorKey).replace(/\./g, '_'); + return typeof column.header === 'string' ? column.header : ''; +} + +export function getLeafColumns(columns: ColumnDef[]): ColumnDef[] { + return columns.flatMap((column) => + 'columns' in column && column.columns ? getLeafColumns(column.columns) : [column], + ); +} diff --git a/src/hooks/useColumnsAutoSize/utils/measureDOMColumns.test.ts b/src/hooks/useColumnsAutoSize/utils/measureDOMColumns.test.ts new file mode 100644 index 0000000..890fd98 --- /dev/null +++ b/src/hooks/useColumnsAutoSize/utils/measureDOMColumns.test.ts @@ -0,0 +1,159 @@ +import type * as React from 'react'; + +import type {ColumnDef, Row} from '@tanstack/react-table'; + +import {createDOMMeasureElementFactory} from './createDOMMeasureElement'; +import {measureDOMColumns} from './measureDOMColumns'; +afterEach(() => jest.restoreAllMocks()); +beforeEach(() => { + jest.spyOn(HTMLElement.prototype, 'getClientRects').mockImplementation(function ( + this: HTMLElement, + ) { + return (this.isConnected ? [{}] : []) as unknown as DOMRectList; + }); + jest.spyOn(HTMLElement.prototype, 'offsetWidth', 'get').mockImplementation(function ( + this: HTMLElement, + ) { + return this.getBoundingClientRect().width; + }); +}); + +test('inserts all columns before a single width read per column, inherits context and cleans up', () => { + const container = document.createElement('section'); + document.body.append(container); + const columns: ColumnDef[] = [ + {id: 'one', meta: {autoSize: {}}}, + {id: 'two', meta: {autoSize: {}}}, + ]; + const read = jest + .spyOn(HTMLElement.prototype, 'getBoundingClientRect') + .mockImplementation(function (this: HTMLElement) { + expect(this.parentElement?.parentElement).toBe(container); + expect(this.parentElement?.children).toHaveLength(2); + expect(this.parentElement?.getAttribute('aria-hidden')).toBe('true'); + return {width: 123.25} as DOMRect; + }); + expect( + measureDOMColumns({ + columns, + rows: [], + measurement: {containerRef: {current: container}}, + options: {}, + }), + ).toEqual({one: 124, two: 124}); + expect(read).toHaveBeenCalledTimes(2); + expect(container.children).toHaveLength(0); + container.remove(); +}); +test('isolates broken text formatters and includes headers, footers and reserved control width', () => { + const rows = [{original: {}, getValue: () => 42}] as unknown as Row[]; + jest.spyOn(HTMLElement.prototype, 'getBoundingClientRect').mockImplementation(function ( + this: HTMLElement, + ) { + expect(this.querySelector('.gt-table__header-cell')?.textContent).toBe('Header'); + expect(this.querySelector('.gt-table__footer-cell')?.textContent).toBe('Total: 42'); + expect(this.querySelector('.gt-table__cell')?.children).toHaveLength(2); + return {width: 100} as DOMRect; + }); + expect( + measureDOMColumns({ + columns: [ + { + id: 'broken', + meta: { + autoSize: { + text: () => { + throw Error('broken'); + }, + }, + }, + }, + { + id: 'healthy', + header: 'Header', + meta: {autoSize: {extraWidth: 24, footer: ['Total: 42']}}, + }, + ], + rows, + measurement: {}, + options: {}, + }), + ).toEqual({healthy: 100}); +}); +test('the DOM factory preserves text and React numeric style semantics', () => { + const createElement = createDOMMeasureElementFactory(document); + const element = createElement('span', { + textContent: ' & 0', + style: { + fontSize: 18, + fontWeight: 700, + letterSpacing: 2, + lineHeight: 1.5, + padding: 0, + flexShrink: 0, + '--size': 20, + } as React.CSSProperties, + }); + expect(element.textContent).toBe(' & 0'); + expect(element.children).toHaveLength(0); + expect(element.style.fontSize).toBe('18px'); + expect(element.style.fontWeight).toBe('700'); + expect(element.style.letterSpacing).toBe('2px'); + expect(element.style.lineHeight).toBe('1.5'); + expect(element.style.getPropertyValue('--size')).toBe('20'); +}); + +test('detached, hidden and zero-width containers defer instead of accepting minWidth', () => { + const columns: ColumnDef[] = [{id: 'a', header: 'A', meta: {autoSize: {}}}]; + const container = document.createElement('div'); + expect( + measureDOMColumns({ + columns, + rows: [], + measurement: {containerRef: {current: container}}, + options: {}, + }), + ).toBeUndefined(); + document.body.append(container); + jest.spyOn(container, 'getClientRects').mockReturnValue([] as unknown as DOMRectList); + expect( + measureDOMColumns({ + columns, + rows: [], + measurement: {containerRef: {current: container}}, + options: {}, + }), + ).toBeUndefined(); + expect(container.children).toHaveLength(0); + container.remove(); +}); + +test('uses untransformed layout width and preserves function-based extra space', () => { + jest.spyOn(HTMLElement.prototype, 'offsetWidth', 'get').mockReturnValue(160); + jest.spyOn(HTMLElement.prototype, 'getBoundingClientRect').mockReturnValue({ + width: 80, + } as DOMRect); + const extra = jest.fn((value: unknown) => Number(value)); + const rows = [{original: {}, getValue: () => 24}] as unknown as Row[]; + const widths = measureDOMColumns({ + columns: [{id: 'a', meta: {autoSize: {extraWidth: extra}}}], + rows, + measurement: {}, + options: {}, + }); + expect(widths).toEqual({a: 160}); + expect(extra).toHaveBeenCalledWith(24, {}); +}); + +test('a connected but zero-width measurement is never committed', () => { + jest.spyOn(HTMLElement.prototype, 'offsetWidth', 'get').mockReturnValue(0); + expect( + measureDOMColumns({ + columns: [{id: 'a', header: 'A', meta: {autoSize: {}}}], + rows: [], + measurement: {}, + options: {}, + }), + ).toBeUndefined(); + expect(document.querySelector('[aria-hidden="true"]')).toBeNull(); +}); diff --git a/src/hooks/useColumnsAutoSize/utils/measureDOMColumns.ts b/src/hooks/useColumnsAutoSize/utils/measureDOMColumns.ts index 02934c8..2b302be 100644 --- a/src/hooks/useColumnsAutoSize/utils/measureDOMColumns.ts +++ b/src/hooks/useColumnsAutoSize/utils/measureDOMColumns.ts @@ -1,8 +1,12 @@ import type {ColumnDef, Row} from '@tanstack/react-table'; +import {b as base} from '../../../components/BaseTable/BaseTable.classname'; +import {b as styled} from '../../../components/Table/Table.classname'; +import {cellDefaultWidth, headerDefaultWidth} from '../constants'; import type {AutoSizeContent, DOMMeasurementOptions, UseColumnsAutoSizeOptions} from '../types'; import {createDOMMeasureElementFactory} from './createDOMMeasureElement'; +import {getColumnId} from './getColumnId'; const resolve = ( property: TResult | ((value: unknown, row: TData) => TResult), @@ -24,11 +28,18 @@ export function measureDOMColumns({ rows: Row[]; measurement: DOMMeasurementOptions; options: Pick; -}): Record { +}): Record | undefined { + if (!columns.length) return {}; const container = measurement.containerRef?.current ?? document.body; + if ( + !container.isConnected || + (!container.getClientRects().length && + container.ownerDocument.defaultView?.getComputedStyle(container).display !== 'contents') + ) + return undefined; const createElement = createDOMMeasureElementFactory(container.ownerDocument); const root = createElement('div', { - className: `gt-table gt-styled-table ${measurement.className ?? ''}`, + className: `${base()} ${styled()} ${measurement.className ?? ''}`, style: { position: 'fixed', top: 0, @@ -44,7 +55,7 @@ export function measureDOMColumns({ root.setAttribute('aria-hidden', 'true'); const createCell = (content: AutoSizeContent, kind: 'cell' | 'header-cell' | 'footer-cell') => { const cell = createElement('div', { - className: `gt-table__${kind} gt-styled-table__${kind}`, + className: `${base(kind)} ${styled(kind)}`, styleText: `padding-inline:${(kind === 'header-cell' ? (options.headerPadding ?? 24) : (options.padding ?? 16)) / 2}px`, style: content.style, }); @@ -70,10 +81,31 @@ export function measureDOMColumns({ const elements: Array<{id: string; element: HTMLElement}> = []; for (const column of columns) { const config = column.meta?.autoSize; - const id = column.id || ('accessorKey' in column && String(column.accessorKey)) || ''; + const id = getColumnId(column); if (!config || !id) continue; try { const element = createElement('div', {style: {width: 'max-content'}}); + const wrap = (section: 'header' | 'body' | 'footer') => { + const node = createElement('div', { + className: `${base(section)} ${styled(section)}`, + }); + element.append(node); + return node; + }; + const appendRow = ( + section: HTMLElement, + content: AutoSizeContent, + kind: 'cell' | 'header-cell' | 'footer-cell', + ) => { + const rowKind = + kind === 'cell' ? 'row' : kind === 'header-cell' ? 'header-row' : 'footer-row'; + const row = createElement('div', { + className: `${base(rowKind)} ${styled(rowKind)}`, + }); + row.append(createCell(content, kind)); + section.append(row); + }; + let hasContent = false; if (options.measureHeaderText !== false && column.header !== undefined) { const header = config.header ?? column.header; // Arbitrary React headers still require the existing React path. @@ -83,13 +115,13 @@ export function measureDOMColumns({ (typeof header !== 'object' || !('text' in header)) ) continue; - element.append( - createCell( - asContent(header as string | number | AutoSizeContent), - 'header-cell', - ), - ); + const content = asContent(header as string | number | AutoSizeContent); + hasContent = true; + if (!String(content.text).trim()) + element.style.minWidth = `${headerDefaultWidth + (options.headerPadding ?? 24)}px`; + appendRow(wrap('header'), content, 'header-cell'); } + const body = wrap('body'); for (const row of rows) { const value = row.getValue(id); const text = @@ -102,34 +134,50 @@ export function measureDOMColumns({ ) { throw new Error('A lightweight measurement requires primitive text'); } - element.append( - createCell( - { - text: text ?? '', - extraWidth: resolve(config.extraWidth, value, row.original), - className: resolve(config.className, value, row.original), - style: resolve(config.style, value, row.original), - }, - 'cell', - ), + hasContent ||= Boolean(String(text ?? '').trim()); + appendRow( + body, + { + text: text ?? '', + extraWidth: resolve(config.extraWidth, value, row.original), + className: resolve(config.className, value, row.original), + style: resolve(config.style, value, row.original), + }, + 'cell', ); } - for (const footer of config.footer ?? []) - element.append(createCell(asContent(footer), 'footer-cell')); + if (config.footer?.length) { + const footer = wrap('footer'); + for (const value of config.footer) { + hasContent = true; + appendRow(footer, asContent(value), 'footer-cell'); + } + } + if (!hasContent) element.style.minWidth = `${cellDefaultWidth}px`; root.append(element); elements.push({id, element}); } catch { - // An unsupported value or broken formatter falls back for this column only. + if (process.env.NODE_ENV !== 'production') + console.warn( + `[table] Auto-size description for column ${id} failed; using React measurement.`, + ); } } if (!elements.length) return {}; container.append(root); try { + if (!root.isConnected || !root.getClientRects().length) return undefined; const widths: Record = {}; for (const {id, element} of elements) { try { - const width = element.getBoundingClientRect().width; - if (Number.isFinite(width) && width >= 0) widths[id] = Math.ceil(width); + const layoutWidth = element.offsetWidth; + if (layoutWidth <= 0) return undefined; + // Computed CSS width is fractional and independent of ancestor transforms. + const width = + Number.parseFloat( + container.ownerDocument.defaultView?.getComputedStyle(element).width ?? '', + ) || layoutWidth; + if (Number.isFinite(width) && width > 0) widths[id] = Math.ceil(width); } catch { // Keep measuring the remaining columns and fall back for this one. } diff --git a/src/hooks/useColumnsAutoSize/utils/setColumnAutoSizes.ts b/src/hooks/useColumnsAutoSize/utils/setColumnAutoSizes.ts index a8bce2f..604fb6b 100644 --- a/src/hooks/useColumnsAutoSize/utils/setColumnAutoSizes.ts +++ b/src/hooks/useColumnsAutoSize/utils/setColumnAutoSizes.ts @@ -1,18 +1,30 @@ import type {ColumnDef} from '@tanstack/react-table'; +import {getColumnId} from './getColumnId'; import {hasDefinedWidth} from './hasDefinedWidth'; export function setColumnAutoSizes( columns: ColumnDef[], columnWidths: Record, columnSizing: Record, + autoMinSize = true, ): ColumnDef[] { if (!Object.keys(columnWidths).length) { return columns; } return columns.map((column) => { - const id = column.id || ('accessorKey' in column && String(column.accessorKey)) || ''; + if ('columns' in column && column.columns) + return { + ...column, + columns: setColumnAutoSizes( + column.columns, + columnWidths, + columnSizing, + autoMinSize, + ), + }; + const id = getColumnId(column); if (!id) return column; const hasUserResized = Object.keys(columnSizing).length > 0 && columnSizing[id]; @@ -28,7 +40,7 @@ export function setColumnAutoSizes( return { ...column, size: columnWidths[id], - minSize: columnWidths[id], + minSize: autoMinSize ? columnWidths[id] : column.minSize, }; } From f9e7ad9cf9b9aaa9f9b2778946be18623fd2de81 Mon Sep 17 00:00:00 2001 From: Anastasiia Beriia Date: Mon, 2 Nov 2026 13:57:30 +0300 Subject: [PATCH 04/10] fix: stabilize auto size inputs and verify browser layout --- .../testDOMMeasurement/testDOMMeasurement.ts | 62 +++++++++ .storybook/test-runner.ts | 5 + CHANGELOG.md | 11 ++ src/hooks/useColumnsAutoSize/README.md | 16 +++ .../__stories__/DOMMeasurementRegression.tsx | 126 ++++++++++++++++++ .../useColumnsAutoSize.stories.tsx | 3 + .../domMeasurement.test.tsx | 27 ++++ .../useColumnsAutoSize/useColumnsAutoSize.tsx | 108 ++++++++++----- .../utils/getColumnId.test.ts | 27 ++++ .../useColumnsAutoSize/utils/getColumnId.ts | 17 +++ .../utils/getValueFromCell.ts | 46 +++---- .../utils/hasDefinedWidth.ts | 19 ++- .../utils/measureDOMColumns.test.ts | 46 ++++++- .../utils/measureDOMColumns.ts | 14 +- .../utils/renderHeaderContent.ts | 6 +- 15 files changed, 455 insertions(+), 78 deletions(-) create mode 100644 .storybook/browser-tests/testDOMMeasurement/testDOMMeasurement.ts create mode 100644 src/hooks/useColumnsAutoSize/__stories__/DOMMeasurementRegression.tsx create mode 100644 src/hooks/useColumnsAutoSize/utils/getColumnId.test.ts diff --git a/.storybook/browser-tests/testDOMMeasurement/testDOMMeasurement.ts b/.storybook/browser-tests/testDOMMeasurement/testDOMMeasurement.ts new file mode 100644 index 0000000..12fe8e6 --- /dev/null +++ b/.storybook/browser-tests/testDOMMeasurement/testDOMMeasurement.ts @@ -0,0 +1,62 @@ +import type {TestRunnerConfig} from '@storybook/test-runner'; + +type Page = Parameters>[0]; + +/** Compare against real rendered cells, real fonts and real browser layout. */ +export async function testDOMMeasurement(page: Page) { + const status = page.locator('[data-qa="auto-size-width"]'); + await status.waitFor({state: 'attached'}); + if ((await status.textContent()) !== '') throw new Error('Hidden table committed a width'); + await page.locator('[data-qa="auto-size-show"]').click(); + const verify = async () => { + await page.waitForFunction(() => { + const node = document.querySelector('[data-qa="auto-size-width"]'); + return node?.getAttribute('data-ready') === 'true' && Number(node.textContent) > 0; + }); + return page.evaluate(async () => { + await document.fonts.ready; + const table = document.querySelector('table.gt-table'); + if (!table) throw new Error('Missing rendered table'); + const measured = Number( + document.querySelector('[data-qa="auto-size-width"]')?.textContent, + ); + const probe = document.createElement('div'); + probe.className = table.className; + probe.style.cssText = + 'position:absolute;visibility:hidden;width:max-content;left:0;top:0'; + document.body.append(probe); + try { + let expected = 50; + for (const cell of table.querySelectorAll('tbody td, tfoot th')) { + const clone = cell.cloneNode(true) as HTMLElement; + clone.style.width = 'max-content'; + clone.style.minWidth = '0'; + clone.style.maxWidth = 'none'; + clone.style.display = 'block'; + probe.append(clone); + expected = Math.max(expected, Math.ceil(clone.getBoundingClientRect().width)); + clone.remove(); + } + expected = Math.min(500, expected); + if (Math.abs(measured - expected) > 1) + throw new Error(`Width ${measured} differs from rendered cells ${expected}`); + return measured; + } finally { + probe.remove(); + } + }); + }; + const natural = await verify(); + await page.locator('[data-qa="auto-size-scale"]').click(); + const scaled = await verify(); + if (scaled !== natural) throw new Error('Ancestor scale changed auto width'); + await page.locator('[data-qa="auto-size-empty"]').click(); + await verify(); + await page.locator('[data-qa="auto-size-data"]').click(); + await page.waitForFunction( + (width) => + Number(document.querySelector('[data-qa="auto-size-width"]')?.textContent) === width, + natural, + ); + await verify(); +} diff --git a/.storybook/test-runner.ts b/.storybook/test-runner.ts index caa4f49..a58644e 100644 --- a/.storybook/test-runner.ts +++ b/.storybook/test-runner.ts @@ -2,6 +2,7 @@ import type {TestRunnerConfig} from '@storybook/test-runner'; import {toMatchImageSnapshot} from 'jest-image-snapshot'; import {testAdaptiveVirtualization} from './browser-tests/testAdaptiveVirtualization/testAdaptiveVirtualization'; +import {testDOMMeasurement} from './browser-tests/testDOMMeasurement/testDOMMeasurement'; import {testVirtualizedTreeReordering} from './browser-tests/testVirtualizedTreeReordering/testVirtualizedTreeReordering'; const ADAPTIVE_VIRTUALIZATION_STORY = 'basetable--heavy-table-with-adaptive-virtualization'; @@ -13,6 +14,10 @@ const config: TestRunnerConfig = { expect.extend({toMatchImageSnapshot}); }, async postVisit(page, context) { + if (context.id === 'hooks-usecolumnsautosize--dom-measurement-regression-case') { + await testDOMMeasurement(page); + return; + } if (context.id === ADAPTIVE_VIRTUALIZATION_STORY) { await testAdaptiveVirtualization(page); return; diff --git a/CHANGELOG.md b/CHANGELOG.md index 10882b0..6bcf88d 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -1,5 +1,16 @@ # Changelog +## Unreleased + +### Column auto-size migration + +- Auto-size width keys now consistently use TanStack column IDs. `accessorKey: 'a.b'` + resolves to `a_b` in both measurement paths. Update controlled width/sizing keys, + or specify `id: 'a.b'` explicitly to keep an existing dotted key. +- Described DOM columns use automatic widths as their initial size without raising + `minSize`. Manual sizing follows explicit `minSize`/`maxSize` from the first drag + event. The existing React measurement path retains its auto-minimum behavior. + ## [1.24.0](https://github.com/gravity-ui/table/compare/v1.23.0...v1.24.0) (2026-10-26) diff --git a/src/hooks/useColumnsAutoSize/README.md b/src/hooks/useColumnsAutoSize/README.md index 57130b4..80b0895 100644 --- a/src/hooks/useColumnsAutoSize/README.md +++ b/src/hooks/useColumnsAutoSize/README.md @@ -329,3 +329,19 @@ custom DOM layouts still need a matching text/style description or React fallbac Broken text formatters and unsupported values produce a development warning before falling back. The numeric-style utility follows the linked React unitless-property list; it does not run React renderers during DOM measurement. + +### Column IDs and manual sizing + +Controlled `columnWidths` and TanStack `columnSizing` use resolved column IDs. +A dotted accessor key such as `a.b` resolves to `a_b`, consistently in DOM and React +measurement. Migrate old `a.b` map keys or set `id: 'a.b'` explicitly to retain them. + +For DOM descriptions an auto width initializes `size`, but does not raise +`minSize`: manual resizing may shrink below that width immediately, subject to +explicit column `minSize`/`maxSize`. The React path still applies the measured +width as an initial minimum and releases it after a manual resize. Hook +`minWidth`/`maxWidth` constrain automatic measurements, not manual resizing. + +The Storybook **DOMMeasurementRegressionCase** has a browser regression test that +compares widths with cloned real rendered cells in Arial, including copy buttons +and footers, hidden mounting, ancestor scale and empty-to-data transitions. diff --git a/src/hooks/useColumnsAutoSize/__stories__/DOMMeasurementRegression.tsx b/src/hooks/useColumnsAutoSize/__stories__/DOMMeasurementRegression.tsx new file mode 100644 index 0000000..2d3272d --- /dev/null +++ b/src/hooks/useColumnsAutoSize/__stories__/DOMMeasurementRegression.tsx @@ -0,0 +1,126 @@ +import * as React from 'react'; + +import {ClipboardButton} from '@gravity-ui/uikit'; +import type {ColumnDef} from '@tanstack/react-table'; + +import {Table} from '../../../components'; +import {useTable} from '../../useTable'; +import {useColumnsAutoSize} from '../useColumnsAutoSize'; + +type Item = {value: string | number | null}; +const rows: Item[] = [ + {value: 'WWWWWWWWWWWWWWWWWWWWWWWW'}, + {value: 'iiiiiiiiiiiiiiiiiiiiiiii'}, + {value: 'Кириллица и длинное значение'}, + {value: '🛠️ 😀 example'}, + {value: ' repeated spaces '}, + {value: 'line\nnext'}, + {value: 1234567.89}, + {value: 0}, + {value: null}, +]; +const font = { + fontFamily: 'Arial, sans-serif', + fontSize: 13, + fontVariantNumeric: 'tabular-nums', +} as const; +const format = (value: unknown) => + value === null || value === undefined + ? '–' + : typeof value === 'number' + ? value.toLocaleString('en-US', {minimumFractionDigits: 2}) + : String(value); +const total = 'Total: 1,234,567.89'; +const renderValue = (text: string, copy?: string) => ( +
+ {text} + {copy !== undefined && } +
+); +const columns: ColumnDef[] = [ + { + id: 'value', + accessorKey: 'value', + cell: ({getValue}) => + renderValue( + format(getValue()), + getValue() === null || getValue() === undefined ? undefined : String(getValue()), + ), + footer: () => renderValue(total, total), + meta: { + autoSize: { + text: format, + extraWidth: (value) => (value === null || value === undefined ? 0 : 24), + style: font, + footer: [{text: total, extraWidth: 24, style: font}], + }, + }, + }, +]; + +function Measured({hidden, scaled, empty}: {hidden: boolean; scaled: boolean; empty: boolean}) { + const containerRef = React.useRef(null); + const sized = useColumnsAutoSize({ + columns, + measurementContainerRef: containerRef, + options: {measureOnce: true, measureHeaderText: false, minWidth: 50, maxWidth: 500}, + }); + const table = useTable({columns: sized.columnsWithAutoSizes, data: empty ? [] : rows}); + const {setTableInstance} = sized; + React.useLayoutEffect(() => setTableInstance(table), [setTableInstance, table]); + return ( + + + {sized.columnWidths.value ?? ''} + +