@drivenets/design-system 0.18.0 → 0.19.0

package/src/components/ds-table/hooks/use-column-resize.ts

@@ -19,12 +19,19 @@ import {
 	collectMissingLeafSizing,
 	getColumnSizeCssVars,
 	getResizeOriginSize,
+	growFillLeavesToContainer,
+	isExplicitColumnWidth,
 	measureLeafHeaderWidths,
 	omitBuiltinColumnSizing,
+	shiftColumnTrack,
+	withUtilityColumnSizing,
 	type ColumnSizeBoundsSource,
 } from '../utils/column-size';
-import { RESIZE_MIN_COLUMN_WIDTH } from '../utils/constants';
+import { RESIZE_DIVIDER_WIDTH, RESIZE_MIN_COLUMN_WIDTH } from '../utils/constants';
 import type { DsTableResizePhase } from '../context/ds-table-context';
+import { useScrollbarSpacer, type ScrollbarSpacerWidth } from './use-scrollbar-spacer';
+
+const TRACK_MATCH_PX = 3;
 
 const INITIAL_COLUMN_SIZING_INFO: ColumnSizingInfoState = {
 	startOffset: null,
@@ -35,6 +42,14 @@ const INITIAL_COLUMN_SIZING_INFO: ColumnSizingInfoState = {
 	columnSizingStart: [],
 };
 
+const clampResizeOverlayOffset = (offset: number, tableWidth: number): number => {
+	if (tableWidth <= RESIZE_DIVIDER_WIDTH) {
+		return offset;
+	}
+
+	return Math.min(offset, tableWidth - RESIZE_DIVIDER_WIDTH);
+};
+
 export interface UseColumnResizeOptions {
 	enabled: boolean;
 	/**
@@ -49,6 +64,15 @@ export interface UseColumnResizeOptions {
 	 */
 	columns: unknown;
 	columnVisibility: VisibilityState;
+	/**
+	 * Invalidates overflow measurement (row count). Read as a dependency only.
+	 */
+	overflowKey: number;
+	/**
+	 * Authored widths for injected utility leaves. Overlaid last so they win
+	 * over persist seed and live internal state.
+	 */
+	utilityColumnSizing?: ColumnSizingState;
 }
 
 export interface DsTableResizeContextSlice {
@@ -64,6 +88,10 @@ export interface DsTableResizeContextSlice {
 	 * the persist callback, mirroring drag end.
 	 */
 	onResizeKeyboardNudge: (columnId: string, delta: number) => void;
+	/**
+	 * Overflow-only **Scrollbar spacer** width (0 or rest scrollbar size).
+	 */
+	scrollbarSpacerWidth: ScrollbarSpacerWidth;
 }
 
 export interface UseColumnResizeActiveResize {
@@ -92,6 +120,7 @@ export interface UseColumnResizeResult {
 		columnSizingInfo: ColumnSizingInfoState;
 	};
 	bind: <TData>(table: Table<TData>) => UseColumnResizeBindResult;
+	scrollbarSpacerWidth: ScrollbarSpacerWidth;
 }
 
 /**
@@ -108,6 +137,8 @@ export const useColumnResize = ({
 	onColumnSizingChange,
 	columns,
 	columnVisibility,
+	overflowKey,
+	utilityColumnSizing,
 }: UseColumnResizeOptions): UseColumnResizeResult => {
 	const [columnResizeState, setColumnResizeState] = useState<{
 		columnSizing: ColumnSizingState;
@@ -125,10 +156,11 @@ export const useColumnResize = ({
 	// drag (or seed measurement) of a persisted column still takes effect. Passed
 	// to TanStack and read for CSS vars / persist so restore, drag, and persist
 	// all see the same widths.
-	const columnSizing = useMemo<ColumnSizingState>(
-		() => (columnSizingProp ? { ...columnSizingProp, ...internalColumnSizing } : internalColumnSizing),
-		[columnSizingProp, internalColumnSizing],
-	);
+	const columnSizing = useMemo<ColumnSizingState>(() => {
+		const merged = columnSizingProp ? { ...columnSizingProp, ...internalColumnSizing } : internalColumnSizing;
+
+		return withUtilityColumnSizing(merged, utilityColumnSizing ?? {});
+	}, [columnSizingProp, internalColumnSizing, utilityColumnSizing]);
 	const [resizeHover, setResizeHover] = useState<{
 		columnId: string;
 		offset: number;
@@ -136,6 +168,10 @@ export const useColumnResize = ({
 	const dragStartOffsetRef = useRef<number | null>(null);
 	const resizeOriginSizingRef = useRef<ColumnSizingState>({});
 	const containerRef = useRef<HTMLDivElement>(null);
+	const scrollbarSpacerWidth = useScrollbarSpacer(containerRef, overflowKey);
+	const spacerWidthRef = useRef(scrollbarSpacerWidth);
+	spacerWidthRef.current = scrollbarSpacerWidth;
+	const prevSpacerWidthRef = useRef<ScrollbarSpacerWidth | null>(null);
 	// eslint-disable-next-line @typescript-eslint/no-explicit-any -- bind is generic; the ref only calls sizing APIs
 	const tableRef = useRef<Table<any> | null>(null);
 
@@ -235,6 +271,8 @@ export const useColumnResize = ({
 	);
 
 	useLayoutEffect(() => {
+		prevSpacerWidthRef.current = null;
+
 		if (!enabled) {
 			return;
 		}
@@ -258,6 +296,11 @@ export const useColumnResize = ({
 			const leaves = table.getVisibleLeafColumns();
 			const leafIds = leaves.map((column) => column.id);
 			const measured = measureLeafHeaderWidths(tableEl, leafIds);
+			const fillableIds = leaves
+				.filter((column) => !isExplicitColumnWidth(column, {}))
+				.map((column) => column.id);
+			const trackWidth = container.clientWidth - spacerWidthRef.current;
+			const missing = collectMissingLeafSizing(measured, columnSizingRef.current, trackWidth, fillableIds);
 
 			for (const column of leaves) {
 				const measuredWidth = measured[column.id];
@@ -265,17 +308,31 @@ export const useColumnResize = ({
 					continue;
 				}
 
-				resizeOriginSizingRef.current[column.id] = getResizeOriginSize(column, Math.round(measuredWidth));
+				resizeOriginSizingRef.current[column.id] = getResizeOriginSize(
+					column,
+					missing[column.id] ?? Math.round(measuredWidth),
+				);
 			}
 
-			const missing = collectMissingLeafSizing(measured, columnSizingRef.current);
 			if (Object.keys(missing).length > 0) {
+				const bounds = leafSizeBoundsRef.current;
+				const clamped = clampColumnSizing(missing, bounds);
+				const grown = growFillLeavesToContainer(
+					clamped,
+					columnSizingRef.current,
+					Object.keys(measured),
+					trackWidth,
+					fillableIds,
+					bounds,
+				);
 				handleColumnSizingChange((prev) => ({
-					...clampColumnSizing(missing, leafSizeBoundsRef.current),
+					...grown,
 					...prev,
 				}));
 			}
 
+			prevSpacerWidthRef.current = spacerWidthRef.current;
+
 			return true;
 		};
 
@@ -293,6 +350,48 @@ export const useColumnResize = ({
 		return () => observer.disconnect();
 	}, [enabled, columns, columnVisibility, handleColumnSizingChange]);
 
+	// After seed, a vertical scrollbar can appear or disappear (Infinite Scroll,
+	// filter, shorter viewport). The **Scrollbar spacer** then toggles 0↔10px.
+	// Shrink or grow the column track by that delta so leaves + spacer still
+	// fill the container — internally only, never via onColumnSizingChange.
+	// Skip when the leaves were not filling the previous track (already
+	// overflowing horizontally) so authored-wide columns are left alone.
+	useLayoutEffect(() => {
+		if (!enabled) {
+			return;
+		}
+
+		const prevSpacerWidth = prevSpacerWidthRef.current;
+		if (prevSpacerWidth === null || prevSpacerWidth === scrollbarSpacerWidth) {
+			return;
+		}
+
+		const container = containerRef.current;
+		const table = tableRef.current;
+		if (!container || !table) {
+			return;
+		}
+
+		const leafIds = table.getVisibleLeafColumns().map((column) => column.id);
+		let leafTotal = 0;
+
+		for (const id of leafIds) {
+			leafTotal += columnSizingRef.current[id] ?? 0;
+		}
+
+		const prevTrack = container.clientWidth - prevSpacerWidth;
+		prevSpacerWidthRef.current = scrollbarSpacerWidth;
+
+		if (Math.abs(leafTotal - prevTrack) > TRACK_MATCH_PX) {
+			return;
+		}
+
+		const delta = prevSpacerWidth - scrollbarSpacerWidth;
+		handleColumnSizingChange(
+			shiftColumnTrack(columnSizingRef.current, leafIds, delta, leafSizeBoundsRef.current),
+		);
+	}, [enabled, scrollbarSpacerWidth, handleColumnSizingChange]);
+
 	const tableOptions = useMemo<UseColumnResizeTableOptions>(
 		() => ({
 			enableColumnResizing: enabled,
@@ -319,7 +418,7 @@ export const useColumnResize = ({
 		const columnSizeVars: CSSProperties | undefined = resizeSizingReady
 			? {
 					...getColumnSizeCssVars(table.getFlatHeaders()),
-					width: table.getTotalSize(),
+					width: table.getTotalSize() + scrollbarSpacerWidth,
 				}
 			: undefined;
 
@@ -335,6 +434,7 @@ export const useColumnResize = ({
 					onResizeDragStart: handleResizeDragStart,
 					onResizeReset: handleResizeReset,
 					onResizeKeyboardNudge: handleResizeKeyboardNudge,
+					scrollbarSpacerWidth,
 				},
 			};
 		}
@@ -349,14 +449,15 @@ export const useColumnResize = ({
 			resizingHeader && startSize !== null
 				? resizingHeader.getSize() - startSize
 				: (columnSizingInfo.deltaOffset ?? 0);
+		const tableWidth = table.getTotalSize();
 		const activeResize: UseColumnResizeActiveResize | null =
 			isResizingColumn && dragStartOffsetRef.current !== null
 				? {
-						offset: dragStartOffsetRef.current + clampedResizeDelta,
+						offset: clampResizeOverlayOffset(dragStartOffsetRef.current + clampedResizeDelta, tableWidth),
 						phase: 'dragging',
 					}
 				: resizeHover
-					? { offset: resizeHover.offset, phase: 'hover' }
+					? { offset: clampResizeOverlayOffset(resizeHover.offset, tableWidth), phase: 'hover' }
 					: null;
 
 		return {
@@ -370,6 +471,7 @@ export const useColumnResize = ({
 				onResizeDragStart: handleResizeDragStart,
 				onResizeReset: handleResizeReset,
 				onResizeKeyboardNudge: handleResizeKeyboardNudge,
+				scrollbarSpacerWidth,
 			},
 		};
 	};
@@ -381,5 +483,6 @@ export const useColumnResize = ({
 			columnSizingInfo,
 		},
 		bind,
+		scrollbarSpacerWidth,
 	};
 };

package/src/components/ds-table/hooks/use-scrollbar-spacer.ts

@@ -0,0 +1,108 @@
+import { useLayoutEffect, useState, type RefObject } from 'react';
+import { SCROLLBAR_SPACER_WIDTH } from '../utils/constants';
+
+export type ScrollbarSpacerWidth = 0 | typeof SCROLLBAR_SPACER_WIDTH;
+
+const BODY_SCROLLBAR_COMPENSATION_CSS_VAR = '--ds-table-body-scrollbar-compensation';
+
+const bodyOverflowsVertically = (body: HTMLElement): boolean => body.scrollHeight > body.clientHeight;
+
+const verticalScrollbarOccupancy = (body: HTMLElement): number =>
+	Math.max(0, body.offsetWidth - body.clientWidth);
+
+/**
+ * Extra `padding-inline-end` on body rows so Fill columns match the header
+ * **Scrollbar spacer** when the vertical scrollbar occupies no layout (overlay).
+ * Classic scrollbars already inset `clientWidth`; do not add that occupancy twice.
+ */
+export const getBodyScrollbarCompensation = (
+	occupancyPx: number,
+	spacerWidth: ScrollbarSpacerWidth,
+): number => Math.max(0, spacerWidth - occupancyPx);
+
+const syncBodyScrollbarCompensation = (
+	container: HTMLElement,
+	body: HTMLElement | null,
+	spacerWidth: ScrollbarSpacerWidth,
+): void => {
+	if (!body) {
+		container.style.removeProperty(BODY_SCROLLBAR_COMPENSATION_CSS_VAR);
+		return;
+	}
+
+	container.style.setProperty(
+		BODY_SCROLLBAR_COMPENSATION_CSS_VAR,
+		`${String(getBodyScrollbarCompensation(verticalScrollbarOccupancy(body), spacerWidth))}px`,
+	);
+};
+
+/**
+ * Overflow-only **Scrollbar spacer** width: `SCROLLBAR_SPACER_WIDTH` while the
+ * body scroll container overflows vertically, otherwise 0.
+ *
+ * Observes container/tbody size and tbody children (rows added/removed). Does
+ * not watch `style` attributes — virtualized rows rewrite `transform` on scroll.
+ */
+export const useScrollbarSpacer = (
+	containerRef: RefObject<HTMLElement | null>,
+	overflowKey: number,
+): ScrollbarSpacerWidth => {
+	const [width, setWidth] = useState<ScrollbarSpacerWidth>(0);
+
+	useLayoutEffect(() => {
+		const container = containerRef.current;
+		if (!container) {
+			return;
+		}
+
+		const read = () => {
+			const body = container.querySelector('tbody');
+			if (!(body instanceof HTMLElement)) {
+				setWidth(0);
+				syncBodyScrollbarCompensation(container, null, 0);
+				return;
+			}
+
+			const nextWidth = bodyOverflowsVertically(body) ? SCROLLBAR_SPACER_WIDTH : 0;
+			setWidth(nextWidth);
+			syncBodyScrollbarCompensation(container, body, nextWidth);
+		};
+
+		const resizeObserver = new ResizeObserver(read);
+		const bodyChildObserver = new MutationObserver(read);
+		resizeObserver.observe(container);
+
+		let observedBody: HTMLElement | null = null;
+
+		const bindBody = () => {
+			const body = container.querySelector('tbody');
+			if (!(body instanceof HTMLElement) || body === observedBody) {
+				return;
+			}
+
+			bodyChildObserver.disconnect();
+			observedBody = body;
+			resizeObserver.observe(body);
+			bodyChildObserver.observe(body, { childList: true });
+			read();
+		};
+
+		bindBody();
+		read();
+
+		const table = container.querySelector('table');
+		const tableChildObserver = new MutationObserver(bindBody);
+		if (table) {
+			tableChildObserver.observe(table, { childList: true });
+		}
+
+		return () => {
+			resizeObserver.disconnect();
+			bodyChildObserver.disconnect();
+			tableChildObserver.disconnect();
+			container.style.removeProperty(BODY_SCROLLBAR_COMPENSATION_CSS_VAR);
+		};
+	}, [containerRef, overflowKey]);
+
+	return width;
+};

package/src/components/ds-table/hooks/use-scrollbar-spacer.unit.test.ts

@@ -0,0 +1,26 @@
+import { describe, expect, it } from 'vitest';
+import { SCROLLBAR_SPACER_WIDTH } from '../utils/constants';
+import { getBodyScrollbarCompensation } from './use-scrollbar-spacer';
+
+describe('getBodyScrollbarCompensation', () => {
+	it('reserves the full spacer when the scrollbar occupies no layout (overlay)', () => {
+		expect(getBodyScrollbarCompensation(0, SCROLLBAR_SPACER_WIDTH)).toBe(SCROLLBAR_SPACER_WIDTH);
+	});
+
+	it('adds nothing when a classic scrollbar already occupies the spacer width', () => {
+		expect(getBodyScrollbarCompensation(SCROLLBAR_SPACER_WIDTH, SCROLLBAR_SPACER_WIDTH)).toBe(0);
+	});
+
+	it('fills only the gap when a thinner scrollbar occupies part of the spacer', () => {
+		expect(getBodyScrollbarCompensation(8, SCROLLBAR_SPACER_WIDTH)).toBe(2);
+	});
+
+	it('does not shrink the body when occupancy is wider than the spacer', () => {
+		expect(getBodyScrollbarCompensation(15, SCROLLBAR_SPACER_WIDTH)).toBe(0);
+	});
+
+	it('adds nothing when the spacer is collapsed', () => {
+		expect(getBodyScrollbarCompensation(0, 0)).toBe(0);
+		expect(getBodyScrollbarCompensation(SCROLLBAR_SPACER_WIDTH, 0)).toBe(0);
+	});
+});

package/src/components/ds-table/styles/_variables.scss

@@ -1,12 +1,10 @@
 $border-radius: 4px;
 $border-width: 1px;
 $group-border-width: 2px;
-$reorder-column-width: 60px;
 $container-margin-vertical: 1rem;
 $filter-input-gap: 0.5rem;
 $filter-input-max-width: 24rem;
 $header-sort-gap: 0.5rem;
-$empty-state-height: 6rem;
 $resize-handle-hit-width: 12px;
 $resize-divider-width: 2px;
 

package/src/components/ds-table/utils/column-size.ts

@@ -188,25 +188,257 @@ export const measureLeafHeaderWidths = (
 	return widths;
 };
 
+const CONTAINER_SIZE_SNAP_PX = 1;
+
+const absorbSizingDrift = (sizing: ColumnSizingState, ids: string[], drift: number): void => {
+	for (const id of [...ids].reverse()) {
+		if (drift === 0) {
+			break;
+		}
+
+		const current = sizing[id];
+		if (current === undefined) {
+			continue;
+		}
+
+		const nextSize = Math.max(RESIZE_MIN_COLUMN_WIDTH, current - drift);
+		drift -= current - nextSize;
+		sizing[id] = nextSize;
+	}
+};
+
+const toIdSet = (ids: ReadonlySet<string> | readonly string[]): ReadonlySet<string> =>
+	ids instanceof Set ? ids : new Set(ids);
+
+/**
+ * Grows `ids` so their combined increase equals `extra`. Shares follow each
+ * id's current width; leftover rounding is absorbed on the last id.
+ */
+const distributeExtraSpace = (
+	sizing: ColumnSizingState,
+	ids: string[],
+	extra: number,
+	maxById?: ReadonlyMap<string, number>,
+): void => {
+	if (ids.length === 0 || extra <= 0) {
+		return;
+	}
+
+	let remaining = extra;
+	let open = ids.filter((id) => (sizing[id] ?? 0) < (maxById?.get(id) ?? DEFAULT_MAX_COLUMN_SIZE));
+
+	while (remaining > 0 && open.length > 0) {
+		let weightSum = 0;
+
+		for (const id of open) {
+			weightSum += sizing[id] ?? 0;
+		}
+
+		let assigned = 0;
+		const stillOpen: string[] = [];
+
+		for (const id of open) {
+			const current = sizing[id] ?? 0;
+			const max = maxById?.get(id) ?? DEFAULT_MAX_COLUMN_SIZE;
+			const room = max - current;
+			const rawShare = weightSum <= 0 ? remaining / open.length : remaining * (current / weightSum);
+			const share = Math.min(room, Math.round(rawShare));
+			sizing[id] = current + share;
+			assigned += share;
+
+			if (current + share < max) {
+				stillOpen.push(id);
+			}
+		}
+
+		let leftover = remaining - assigned;
+
+		for (const id of stillOpen) {
+			if (leftover <= 0) {
+				break;
+			}
+
+			const max = maxById?.get(id) ?? DEFAULT_MAX_COLUMN_SIZE;
+			const add = Math.min(leftover, max - (sizing[id] ?? 0));
+			sizing[id] = (sizing[id] ?? 0) + add;
+			leftover -= add;
+		}
+
+		if (assigned === 0 && leftover === remaining) {
+			break;
+		}
+
+		remaining = leftover;
+		open = stillOpen.filter((id) => (sizing[id] ?? 0) < (maxById?.get(id) ?? DEFAULT_MAX_COLUMN_SIZE));
+	}
+};
+
 /**
  * Sizing entries for leaves that are not yet in `existing`. Does not overwrite
- * user-resized (or previously snapshotted) ids.
+ * user-resized (or previously snapshotted) ids. Rounds each measurement, then
+ * shifts leftover pixels onto the last missing leaf so the visible total
+ * matches the measured width (or the container, when they differ by 1px).
+ * When the measured total is short of the container, leftover space is shared
+ * across missing fill leaves in `fillableIds`.
  */
 export const collectMissingLeafSizing = (
 	measured: Record<string, number>,
 	existing: ColumnSizingState,
+	containerWidth?: number,
+	fillableIds?: ReadonlySet<string> | readonly string[],
 ): ColumnSizingState => {
 	const next: ColumnSizingState = {};
+	const missingIds: string[] = [];
 
 	for (const [id, width] of Object.entries(measured)) {
 		if (existing[id] === undefined) {
 			next[id] = Math.round(width);
+			missingIds.push(id);
 		}
 	}
 
+	if (missingIds.length === 0) {
+		return next;
+	}
+
+	let roundedMissingSum = 0;
+	let unroundedMissingSum = 0;
+
+	for (const id of missingIds) {
+		roundedMissingSum += next[id] ?? 0;
+		unroundedMissingSum += measured[id] ?? 0;
+	}
+
+	absorbSizingDrift(next, missingIds, roundedMissingSum - Math.round(unroundedMissingSum));
+
+	if (containerWidth === undefined || !Number.isFinite(containerWidth) || containerWidth <= 0) {
+		return next;
+	}
+
+	let projected = 0;
+
+	for (const id of Object.keys(measured)) {
+		projected += existing[id] ?? next[id] ?? 0;
+	}
+
+	const delta = projected - containerWidth;
+
+	if (Math.abs(delta) <= CONTAINER_SIZE_SNAP_PX) {
+		absorbSizingDrift(next, missingIds, delta);
+		return next;
+	}
+
+	if (delta < 0 && fillableIds) {
+		const fillable = toIdSet(fillableIds);
+		distributeExtraSpace(
+			next,
+			missingIds.filter((id) => fillable.has(id)),
+			-delta,
+		);
+	}
+
 	return next;
 };
 
+const maxSizeOf = (id: string, boundsById: Map<string, ColumnSizeBoundsSource['columnDef']>): number =>
+	boundsById.get(id)?.maxSize ?? DEFAULT_MAX_COLUMN_SIZE;
+
+/**
+ * After clamp, grow fill leaves that still have room so the projected
+ * measured total matches the container. A leaf that hit `maxSize` must not
+ * leave a gap — leftover pixels go to siblings.
+ */
+export const growFillLeavesToContainer = (
+	sizing: ColumnSizingState,
+	existing: ColumnSizingState,
+	measuredIds: readonly string[],
+	containerWidth: number,
+	fillableIds: ReadonlySet<string> | readonly string[],
+	bounds: ReadonlyArray<ColumnSizeBoundsSource>,
+): ColumnSizingState => {
+	if (!Number.isFinite(containerWidth) || containerWidth <= 0 || measuredIds.length === 0) {
+		return sizing;
+	}
+
+	let projected = 0;
+
+	for (const id of measuredIds) {
+		projected += existing[id] ?? sizing[id] ?? 0;
+	}
+
+	const extra = containerWidth - projected;
+	if (extra <= 0) {
+		return sizing;
+	}
+
+	const fillable = toIdSet(fillableIds);
+	const growable = Object.keys(sizing).filter((id) => fillable.has(id));
+	if (growable.length === 0) {
+		return sizing;
+	}
+
+	const next = { ...sizing };
+	const boundsById = new Map(bounds.map((column) => [column.id, column.columnDef]));
+	distributeExtraSpace(next, growable, extra, new Map(growable.map((id) => [id, maxSizeOf(id, boundsById)])));
+
+	return next;
+};
+
+const minSizeOf = (id: string, boundsById: Map<string, ColumnSizeBoundsSource['columnDef']>): number =>
+	boundsById.get(id)?.minSize ?? RESIZE_MIN_COLUMN_WIDTH;
+
+const shrinkColumnTrack = (
+	sizing: ColumnSizingState,
+	ids: readonly string[],
+	amount: number,
+	bounds: ReadonlyArray<ColumnSizeBoundsSource>,
+): void => {
+	const boundsById = new Map(bounds.map((column) => [column.id, column.columnDef]));
+	let remaining = amount;
+
+	for (const id of [...ids].reverse()) {
+		if (remaining <= 0) {
+			break;
+		}
+
+		const current = sizing[id];
+		if (current === undefined) {
+			continue;
+		}
+
+		const nextSize = Math.max(minSizeOf(id, boundsById), current - remaining);
+		remaining -= current - nextSize;
+		sizing[id] = nextSize;
+	}
+};
+
+/**
+ * Grows or shrinks `ids` so the column track changes by `delta` (positive =
+ * grow). Used when the **Scrollbar spacer** toggles after seed; does not
+ * invent ids missing from `sizing`.
+ */
+export const shiftColumnTrack = (
+	sizing: ColumnSizingState,
+	ids: readonly string[],
+	delta: number,
+	bounds: ReadonlyArray<ColumnSizeBoundsSource>,
+): ColumnSizingState => {
+	if (!Number.isFinite(delta) || delta === 0 || ids.length === 0) {
+		return sizing;
+	}
+
+	const next = { ...sizing };
+
+	if (delta > 0) {
+		const boundsById = new Map(bounds.map((column) => [column.id, column.columnDef]));
+		distributeExtraSpace(next, [...ids], delta, new Map(ids.map((id) => [id, maxSizeOf(id, boundsById)])));
+	} else {
+		shrinkColumnTrack(next, ids, -delta, bounds);
+	}
+
+	return clampColumnSizing(next, bounds);
+};
+
 /**
  * Copy of `columnSizing` without injected utility leaves. Use at the public
  * `onColumnSizingChange` boundary so consumers persist only their own columns.
@@ -222,3 +454,44 @@ export const omitBuiltinColumnSizing = (columnSizing: ColumnSizingState): Column
 
 	return next;
 };
+
+/**
+ * Authored utility-column width, or `fallback` when the value is omitted,
+ * non-finite, or not positive.
+ */
+export const resolveUtilityColumnWidth = (width: number | undefined, fallback: number): number => {
+	if (width === undefined || !Number.isFinite(width) || width <= 0) {
+		return fallback;
+	}
+
+	return width;
+};
+
+/**
+ * Drops any utility ids from `columnSizing`, then applies `utilityColumnSizing`
+ * so those leaves always take the authored width.
+ */
+export const withUtilityColumnSizing = (
+	columnSizing: ColumnSizingState,
+	utilityColumnSizing: ColumnSizingState,
+): ColumnSizingState => ({
+	...omitBuiltinColumnSizing(columnSizing),
+	...utilityColumnSizing,
+});
+
+/**
+ * Authored sizes for injected utility leaves, keyed by column id.
+ */
+export const getUtilityColumnSizing = (
+	columns: ReadonlyArray<{ id?: string; size?: number }>,
+): ColumnSizingState => {
+	const next: ColumnSizingState = {};
+
+	for (const column of columns) {
+		if (column.id !== undefined && BUILTIN_COLUMN_IDS.has(column.id) && column.size !== undefined) {
+			next[column.id] = column.size;
+		}
+	}
+
+	return next;
+};