@galaxy-io/dls 1.2.7 → 1.3.1

package/dist/table/types.d.ts

@@ -0,0 +1,249 @@
+import type { ReactNode } from "react";
+import type { OnChangeFn as TanstackOnChangeFn, Row as TanstackRow, RowSelectionState as TanstackRowSelectionState, SortingState as TanstackSortingState, Table as TanstackTable } from "@tanstack/react-table";
+import type { TextVariant } from "../text/Text";
+export declare enum TableVariant {
+    BASE = "BASE",
+    PRIMARY = "PRIMARY",
+    SECONDARY = "SECONDARY",
+    TERTIARY = "TERTIARY"
+}
+export declare enum TableDensity {
+    SMALL = "SMALL",
+    MEDIUM = "MEDIUM",
+    LARGE = "LARGE"
+}
+export declare enum ColumnPin {
+    LEFT = "LEFT",
+    RIGHT = "RIGHT"
+}
+export declare enum ColumnAlign {
+    LEFT = "LEFT",
+    CENTER = "CENTER",
+    RIGHT = "RIGHT"
+}
+export declare enum ColumnResizeMode {
+    /** Column width follows the pointer while dragging. */
+    ON_CHANGE = "ON_CHANGE",
+    /** Column width commits once the drag ends. */
+    ON_END = "ON_END"
+}
+export interface ColumnDef<TData, TValue = unknown> {
+    id: string;
+    accessorFn?: (row: TData) => TValue;
+    header?: string | ((props: {
+        table: TanstackTable<TData>;
+    }) => ReactNode);
+    cell?: (props: {
+        value: TValue;
+        row: TanstackRow<TData>;
+    }) => ReactNode;
+    size?: number;
+    minSize?: number;
+    maxSize?: number;
+    pin?: ColumnPin;
+    enableSorting?: boolean;
+    sortDescFirst?: boolean;
+    enableResizing?: boolean;
+    align?: ColumnAlign;
+    cellLoading?: () => ReactNode;
+    headerAriaLabel?: string;
+}
+export interface EstimateColumnWidthOptions {
+    minWidth?: number;
+    maxWidth?: number;
+    charWidth?: number;
+    padding?: number;
+}
+/** Column widths keyed by column id, as produced by resizing. */
+export type ColumnSizingState = Record<string, number>;
+/**
+ * Props shared by every table surface — dimensions, paging, loading/error
+ * states and resizing behave identically whether or not rows are virtualized.
+ */
+export interface BaseTableProps<TData> {
+    columns: ColumnDef<TData, unknown>[];
+    getRowId?: (row: TData, index: number) => string;
+    height?: number | string;
+    width?: number | string;
+    fillWidth?: boolean;
+    fillHeight?: boolean;
+    density?: TableDensity;
+    variant?: TableVariant;
+    hasNextPage?: boolean;
+    isFetchingNextPage?: boolean;
+    fetchNextPage?: () => void;
+    isLoading?: boolean;
+    isError?: boolean;
+    error?: Error;
+    loadingRowCount?: number;
+    contentWhenEmpty?: ReactNode;
+    contentWhenError?: ReactNode | ((error?: Error) => ReactNode);
+    noHeader?: boolean;
+    noLastRowBorder?: boolean;
+    noLastRowPadding?: boolean;
+    enableColumnResizing?: boolean;
+    columnSizing?: ColumnSizingState;
+    defaultColumnSizing?: ColumnSizingState;
+    onColumnSizingChange?: (columnSizing: ColumnSizingState) => void;
+    columnResizeMode?: ColumnResizeMode;
+    ariaLabel?: string;
+    ariaLabelledBy?: string;
+}
+export interface InfiniteTableProps<TData> extends BaseTableProps<TData> {
+    data: TData[];
+    enableRowSelection?: boolean | ((row: TanstackRow<TData>) => boolean);
+    enableMultiRowSelection?: boolean;
+    rowSelection?: TanstackRowSelectionState;
+    defaultRowSelection?: TanstackRowSelectionState;
+    onRowSelectionChange?: TanstackOnChangeFn<TanstackRowSelectionState>;
+    onSelectedRowsChange?: (rows: TanstackRow<TData>[]) => void;
+    /** Renders a leading checkbox column that can actually toggle selection. */
+    showSelectionColumn?: boolean;
+    selectionColumnPin?: ColumnPin;
+    enableSelectAll?: boolean;
+    /** Shift-click selects the range between the last click and this row. */
+    enableSelectionRange?: boolean;
+    selectAllAriaLabel?: string;
+    getRowSelectAriaLabel?: (row: TanstackRow<TData>) => string;
+    enableSorting?: boolean;
+    enableMultiSort?: boolean;
+    sorting?: TanstackSortingState;
+    onSortingChange?: TanstackOnChangeFn<TanstackSortingState>;
+    manualSorting?: boolean;
+    onRowExpand?: (row: TanstackRow<TData>) => ReactNode;
+    expandedRowIds?: string[];
+    defaultExpandedRowIds?: string[];
+    onExpandedChange?: (expandedRowIds: string[]) => void;
+    getRowCanExpand?: (row: TanstackRow<TData>) => boolean;
+    /** When false, expanding a row collapses whichever row was open. */
+    enableMultiRowExpansion?: boolean;
+    showExpandColumn?: boolean;
+    expandColumnPin?: ColumnPin;
+    onRowClick?: (row: TanstackRow<TData>, event: React.MouseEvent) => void;
+    onRowDoubleClick?: (row: TanstackRow<TData>, event: React.MouseEvent) => void;
+    /** Fired by click *and* by Enter/Space when a row has keyboard focus. */
+    onRowActivate?: (row: TanstackRow<TData>, event: React.MouseEvent | React.KeyboardEvent) => void;
+    getRowAriaLabel?: (row: TanstackRow<TData>) => string;
+    enableRowFocus?: boolean;
+    onTableReady?: (table: TanstackTable<TData>) => void;
+}
+export interface VirtualizedInfiniteTableProps<TData> extends BaseTableProps<TData> {
+    totalRowCount: number;
+    getRowData: (index: number) => TData | undefined;
+    estimateRowHeight?: number;
+    overscan?: number;
+    onRowClick?: (row: TanstackRow<TData>, event: React.MouseEvent) => void;
+}
+export type { TanstackRow as Row, TanstackTable as Table };
+export declare enum CellEnrichmentStatus {
+    IDLE = "IDLE",
+    PENDING = "PENDING",
+    RUNNING = "RUNNING",
+    COMPLETE = "COMPLETE",
+    ERROR = "ERROR"
+}
+export declare enum SpreadsheetCellType {
+    TEXT = "TEXT",
+    NUMBER = "NUMBER",
+    BOOLEAN = "BOOLEAN",
+    ENUM = "ENUM",
+    DATE = "DATE",
+    READONLY = "READONLY"
+}
+/**
+ * Row access handed to a column-level enrichment action.
+ *
+ * A spreadsheet is virtualized over an index, so there is no row array to pass.
+ * Actions that genuinely need every row call `getLoadedRows()`; actions that
+ * only need a count read `totalRowCount` without paying for a full scan.
+ */
+export interface SpreadsheetRowsContext<TData> {
+    totalRowCount: number;
+    getRowData: (index: number) => TData | undefined;
+    /**
+     * Materializes every currently-loaded row, skipping indices that have not
+     * been fetched. O(totalRowCount) — call once, never per row.
+     */
+    getLoadedRows: () => TData[];
+}
+export interface SpreadsheetColumnAction<TData> {
+    id: string;
+    label: string;
+    icon?: ReactNode;
+    onAction: (columnId: string, rows: SpreadsheetRowsContext<TData>) => void;
+}
+export interface SpreadsheetHeaderAction {
+    id: string;
+    label: string;
+    icon?: ReactNode;
+    variant?: TextVariant;
+    onAction: (columnId: string) => void;
+}
+/**
+ * A spreadsheet column.
+ *
+ * Extends `ColumnDef` so `id`, `accessorFn`, sizing, `pin`, `align`,
+ * `cellLoading`, `enableResizing` and `headerAriaLabel` have one definition
+ * across the domain — and so these columns feed `useTableColumnLayout` and
+ * `useTableColumnResize` without a cast.
+ *
+ * `header` is narrowed to a string and sorting is dropped: the spreadsheet
+ * header owns its own menu affordance, and there is no table instance to hand
+ * a header render function.
+ */
+export interface SpreadsheetColumnDef<TData, TValue = unknown> extends Omit<ColumnDef<TData, TValue>, "cell" | "header" | "enableSorting" | "sortDescFirst"> {
+    header?: string;
+    /**
+     * Custom cell renderer.
+     *
+     * `row` carries only `original` and `index` — a virtualized spreadsheet has
+     * no TanStack row model behind it, so row methods (`id`, `getIsSelected`,
+     * `subRows`, `getValue`) are absent at runtime despite being on the type.
+     *
+     * `isEditing` is optional on purpose: it keeps this signature assignable to
+     * `ColumnDef["cell"]`, which is what lets the shared layout and resize hooks
+     * consume these columns unchanged.
+     */
+    cell?: (props: {
+        value: TValue;
+        row: TanstackRow<TData>;
+        isEditing?: boolean;
+    }) => ReactNode;
+    cellType: SpreadsheetCellType;
+    editable?: boolean;
+    enumOptions?: string[];
+    onCellChange?: (rowIndex: number, row: TData, value: TValue) => void;
+    headerActions?: SpreadsheetHeaderAction[];
+    enrichmentActions?: SpreadsheetColumnAction<TData>[];
+    getCellEnrichmentStatus?: (row: TData, rowIndex: number) => CellEnrichmentStatus;
+}
+export interface SpreadsheetRowAction<TData> {
+    id: string;
+    label: string;
+    icon?: ReactNode;
+    onAction: (rowIndex: number, row: TData) => void;
+}
+export interface EditingCell {
+    rowIndex: number;
+    columnId: string;
+}
+/**
+ * Inherits dimensions, density, variant, paging, loading/error state,
+ * controlled column sizing and the ARIA labels from the virtualized table.
+ *
+ * `onRowClick` is omitted deliberately: a whole-row click target would fight
+ * the per-cell click-to-edit affordance.
+ */
+export interface InfiniteSpreadsheetProps<TData> extends Omit<VirtualizedInfiniteTableProps<TData>, "columns" | "onRowClick"> {
+    columns: SpreadsheetColumnDef<TData, unknown>[];
+    /** Renders the trailing action column with an add-column control. */
+    onAddColumn?: () => void;
+    addColumnAriaLabel?: string;
+    rowActions?: SpreadsheetRowAction<TData>[];
+    getRowActionsAriaLabel?: (rowIndex: number) => string;
+    /** Controlled when provided; uncontrolled otherwise. */
+    editingCell?: EditingCell | null;
+    onEditingCellChange?: (cell: EditingCell | null) => void;
+    /** Roving-tabindex row focus and arrow-key row navigation. Defaults to true. */
+    enableRowFocus?: boolean;
+}

package/dist/table/types.js

@@ -0,0 +1,51 @@
+//#region src/table/types.ts
+var TableVariant = /* @__PURE__ */ function(TableVariant) {
+	TableVariant["BASE"] = "BASE";
+	TableVariant["PRIMARY"] = "PRIMARY";
+	TableVariant["SECONDARY"] = "SECONDARY";
+	TableVariant["TERTIARY"] = "TERTIARY";
+	return TableVariant;
+}({});
+var TableDensity = /* @__PURE__ */ function(TableDensity) {
+	TableDensity["SMALL"] = "SMALL";
+	TableDensity["MEDIUM"] = "MEDIUM";
+	TableDensity["LARGE"] = "LARGE";
+	return TableDensity;
+}({});
+var ColumnPin = /* @__PURE__ */ function(ColumnPin) {
+	ColumnPin["LEFT"] = "LEFT";
+	ColumnPin["RIGHT"] = "RIGHT";
+	return ColumnPin;
+}({});
+var ColumnAlign = /* @__PURE__ */ function(ColumnAlign) {
+	ColumnAlign["LEFT"] = "LEFT";
+	ColumnAlign["CENTER"] = "CENTER";
+	ColumnAlign["RIGHT"] = "RIGHT";
+	return ColumnAlign;
+}({});
+var ColumnResizeMode = /* @__PURE__ */ function(ColumnResizeMode) {
+	/** Column width follows the pointer while dragging. */
+	ColumnResizeMode["ON_CHANGE"] = "ON_CHANGE";
+	/** Column width commits once the drag ends. */
+	ColumnResizeMode["ON_END"] = "ON_END";
+	return ColumnResizeMode;
+}({});
+var CellEnrichmentStatus = /* @__PURE__ */ function(CellEnrichmentStatus) {
+	CellEnrichmentStatus["IDLE"] = "IDLE";
+	CellEnrichmentStatus["PENDING"] = "PENDING";
+	CellEnrichmentStatus["RUNNING"] = "RUNNING";
+	CellEnrichmentStatus["COMPLETE"] = "COMPLETE";
+	CellEnrichmentStatus["ERROR"] = "ERROR";
+	return CellEnrichmentStatus;
+}({});
+var SpreadsheetCellType = /* @__PURE__ */ function(SpreadsheetCellType) {
+	SpreadsheetCellType["TEXT"] = "TEXT";
+	SpreadsheetCellType["NUMBER"] = "NUMBER";
+	SpreadsheetCellType["BOOLEAN"] = "BOOLEAN";
+	SpreadsheetCellType["ENUM"] = "ENUM";
+	SpreadsheetCellType["DATE"] = "DATE";
+	SpreadsheetCellType["READONLY"] = "READONLY";
+	return SpreadsheetCellType;
+}({});
+//#endregion
+export { CellEnrichmentStatus, ColumnAlign, ColumnPin, ColumnResizeMode, SpreadsheetCellType, TableDensity, TableVariant };

package/dist/table/useInfiniteScrollSentinel.d.ts

@@ -0,0 +1,24 @@
+interface UseInfiniteScrollSentinelOptions {
+    scrollRef: React.RefObject<HTMLElement | null>;
+    hasNextPage?: boolean;
+    isFetchingNextPage?: boolean;
+    fetchNextPage?: () => void;
+    /**
+     * Number of rows currently rendered. Changing it re-arms the observer, which
+     * is what makes a short first page keep paging until the viewport fills.
+     */
+    rowCount: number;
+}
+/**
+ * Drives infinite scroll from an `IntersectionObserver` on a sentinel element
+ * placed after the last row.
+ *
+ * A plain `scroll` listener can dead-end: if the first page is shorter than the
+ * viewport, no scroll event ever fires and paging never starts. Re-observing an
+ * already-intersecting sentinel re-fires the callback, so this keeps pumping
+ * until the content overflows or `hasNextPage` goes false.
+ *
+ * @returns A ref to attach to the sentinel element.
+ */
+export declare function useInfiniteScrollSentinel({ scrollRef, hasNextPage, isFetchingNextPage, fetchNextPage, rowCount, }: UseInfiniteScrollSentinelOptions): import("react").RefObject<HTMLDivElement>;
+export {};

package/dist/table/useInfiniteScrollSentinel.js

@@ -0,0 +1,53 @@
+import "./utils.js";
+import { useEffect, useRef } from "react";
+//#region src/table/useInfiniteScrollSentinel.ts
+/**
+* Drives infinite scroll from an `IntersectionObserver` on a sentinel element
+* placed after the last row.
+*
+* A plain `scroll` listener can dead-end: if the first page is shorter than the
+* viewport, no scroll event ever fires and paging never starts. Re-observing an
+* already-intersecting sentinel re-fires the callback, so this keeps pumping
+* until the content overflows or `hasNextPage` goes false.
+*
+* @returns A ref to attach to the sentinel element.
+*/
+function useInfiniteScrollSentinel({ scrollRef, hasNextPage, isFetchingNextPage, fetchNextPage, rowCount }) {
+	const sentinelRef = useRef(null);
+	const fetchNextPageRef = useRef(fetchNextPage);
+	useEffect(() => {
+		fetchNextPageRef.current = fetchNextPage;
+	});
+	const canFetch = fetchNextPage !== void 0;
+	useEffect(() => {
+		const root = scrollRef.current;
+		const sentinel = sentinelRef.current;
+		if (!root || !sentinel || !canFetch || !hasNextPage || isFetchingNextPage) return;
+		if (typeof IntersectionObserver === "undefined") {
+			const onScroll = () => {
+				const { scrollHeight, scrollTop, clientHeight } = root;
+				if (scrollHeight - scrollTop - clientHeight < 500) fetchNextPageRef.current?.();
+			};
+			onScroll();
+			root.addEventListener("scroll", onScroll, { passive: true });
+			return () => root.removeEventListener("scroll", onScroll);
+		}
+		const observer = new IntersectionObserver((entries) => {
+			if (entries.some((entry) => entry.isIntersecting)) fetchNextPageRef.current?.();
+		}, {
+			root,
+			rootMargin: `0px 0px 500px 0px`
+		});
+		observer.observe(sentinel);
+		return () => observer.disconnect();
+	}, [
+		scrollRef,
+		canFetch,
+		hasNextPage,
+		isFetchingNextPage,
+		rowCount
+	]);
+	return sentinelRef;
+}
+//#endregion
+export { useInfiniteScrollSentinel };

package/dist/{spreadsheet/hooks → table}/useSpreadsheetEditing.d.ts

@@ -1,4 +1,4 @@
-import type { EditingCell } from "../types";
+import type { EditingCell } from "./types";
 interface UseSpreadsheetEditingOptions {
     editingCell?: EditingCell | null;
     onEditingCellChange?: (cell: EditingCell | null) => void;

package/dist/{spreadsheet/hooks → table}/useSpreadsheetEditing.js

@@ -1,5 +1,5 @@
 import { useCallback, useEffect, useState } from "react";
-//#region src/spreadsheet/hooks/useSpreadsheetEditing.ts
+//#region src/table/useSpreadsheetEditing.ts
 function useSpreadsheetEditing(options) {
 	const { editingCell: controlledCell, onEditingCellChange } = options;
 	const isControlled = controlledCell !== void 0;

package/dist/table/useTableColumnLayout.d.ts

@@ -0,0 +1,28 @@
+import { type ColumnDef, type ColumnSizingState } from "./types";
+export interface TableColumnLayout<TData> {
+    /**
+     * Resolved width for a column, or `undefined` when the column is flexible
+     * and should share the leftover space.
+     */
+    getColumnWidth: (column: ColumnDef<TData, unknown>) => number | undefined;
+    /** Sticky offset in pixels, keyed by column id, for pinned columns only. */
+    pinnedOffsets: Map<string, number>;
+    /** Sum of every column's resolved width — the table's minimum content width. */
+    rowMinWidth: number;
+}
+interface UseTableColumnLayoutOptions<TData> {
+    columns: ColumnDef<TData, unknown>[];
+    /** Widths produced by resizing; they win over the column's declared `size`. */
+    columnSizing?: ColumnSizingState;
+    /** Reserved space at the trailing edge, ahead of any right-pinned columns. */
+    rightOffsetBase?: number;
+}
+/**
+ * Derives column widths, sticky offsets for pinned columns, and the row's
+ * minimum content width from plain column definitions.
+ *
+ * Deliberately independent of any TanStack table instance so the virtualized
+ * table — which has none — shares exactly the same layout maths.
+ */
+export declare function useTableColumnLayout<TData>({ columns, columnSizing, rightOffsetBase, }: UseTableColumnLayoutOptions<TData>): TableColumnLayout<TData>;
+export {};

package/dist/table/useTableColumnLayout.js

@@ -0,0 +1,63 @@
+import { ColumnPin } from "./types.js";
+import "./utils.js";
+import { useEffect, useMemo } from "react";
+//#region src/table/useTableColumnLayout.ts
+function resolveColumnWidth(column, columnSizing) {
+	const override = columnSizing?.[column.id];
+	if (override !== void 0) return override;
+	if (column.size !== void 0) return column.size;
+	if (column.pin) return column.minSize ?? 150;
+}
+/**
+* Derives column widths, sticky offsets for pinned columns, and the row's
+* minimum content width from plain column definitions.
+*
+* Deliberately independent of any TanStack table instance so the virtualized
+* table — which has none — shares exactly the same layout maths.
+*/
+function useTableColumnLayout({ columns, columnSizing, rightOffsetBase = 0 }) {
+	const layout = useMemo(() => {
+		const widths = /* @__PURE__ */ new Map();
+		let rowMinWidth = 0;
+		columns.forEach((column) => {
+			const width = resolveColumnWidth(column, columnSizing);
+			widths.set(column.id, width);
+			rowMinWidth += width ?? column.minSize ?? 0;
+		});
+		const pinnedOffsets = /* @__PURE__ */ new Map();
+		let leftOffset = 0;
+		columns.forEach((column) => {
+			if (column.pin !== ColumnPin.LEFT) return;
+			pinnedOffsets.set(column.id, leftOffset);
+			leftOffset += widths.get(column.id) ?? 150;
+		});
+		let rightOffset = rightOffsetBase;
+		[...columns].reverse().forEach((column) => {
+			if (column.pin !== ColumnPin.RIGHT) return;
+			pinnedOffsets.set(column.id, rightOffset);
+			rightOffset += widths.get(column.id) ?? 150;
+		});
+		return {
+			widths,
+			pinnedOffsets,
+			rowMinWidth
+		};
+	}, [
+		columns,
+		columnSizing,
+		rightOffsetBase
+	]);
+	const unsizedPinnedColumnIds = useMemo(() => columns.filter((column) => column.pin && column.size === void 0 && column.minSize === void 0).map((column) => column.id), [columns]);
+	useEffect(() => {
+		if (unsizedPinnedColumnIds.length === 0) return;
+		console.warn(`[InfiniteTable] Pinned columns need an explicit \`size\` so their sticky offset is correct. Falling back to 150px for: ${unsizedPinnedColumnIds.join(", ")}.`);
+	}, [unsizedPinnedColumnIds]);
+	const { widths, pinnedOffsets, rowMinWidth } = layout;
+	return {
+		getColumnWidth: useMemo(() => (column) => widths.get(column.id), [widths]),
+		pinnedOffsets,
+		rowMinWidth
+	};
+}
+//#endregion
+export { useTableColumnLayout };

package/dist/table/useTableColumnResize.d.ts

@@ -0,0 +1,38 @@
+import { ColumnResizeMode, type ColumnDef, type ColumnSizingState } from "./types";
+interface UseTableColumnResizeOptions<TData> {
+    columns: ColumnDef<TData, unknown>[];
+    enabled?: boolean;
+    columnSizing?: ColumnSizingState;
+    defaultColumnSizing?: ColumnSizingState;
+    onColumnSizingChange?: (columnSizing: ColumnSizingState) => void;
+    mode?: ColumnResizeMode;
+}
+export interface TableColumnResize<TData> {
+    columnSizing: ColumnSizingState;
+    /** TanStack-shaped setter, so `state.columnSizing` stays in sync. */
+    onColumnSizingChange: (updater: ColumnSizingState | ((old: ColumnSizingState) => ColumnSizingState)) => void;
+    resizingColumnId: string | null;
+    canResizeColumn: (column: ColumnDef<TData, unknown>) => boolean;
+    /**
+     * `measuredWidth` is the column's rendered width. Pass it for flexible
+     * columns — they have no declared `size`, so without it the drag would jump
+     * to the fallback width on the first pointer move.
+     */
+    startResize: (columnId: string, clientX: number, measuredWidth?: number) => void;
+    resizeByKeyboard: (columnId: string, event: React.KeyboardEvent) => void;
+    /** `current` is undefined for a flexible column that has not been resized. */
+    getColumnResizeBounds: (columnId: string) => {
+        min: number;
+        max: number;
+        current: number | undefined;
+    };
+}
+/**
+ * Drag- and keyboard-driven column resizing, controlled or uncontrolled.
+ *
+ * Pointer listeners live on `window` so the drag survives the pointer leaving
+ * the header, and the teardown is held in a ref so unmounting mid-drag cannot
+ * leave listeners or the `col-resize` body cursor behind.
+ */
+export declare function useTableColumnResize<TData>({ columns, enabled, columnSizing, defaultColumnSizing, onColumnSizingChange, mode, }: UseTableColumnResizeOptions<TData>): TableColumnResize<TData>;
+export {};

package/dist/table/useTableColumnResize.js

@@ -0,0 +1,155 @@
+import { ColumnResizeMode } from "./types.js";
+import "./utils.js";
+import { useCallback, useEffect, useMemo, useRef, useState } from "react";
+//#region src/table/useTableColumnResize.ts
+/** Keyboard resize step, and the step while shift is held. */
+var KEYBOARD_RESIZE_STEP_PX = 8;
+var KEYBOARD_RESIZE_STEP_LARGE_PX = 32;
+function clampWidth(column, width) {
+	const min = column?.minSize ?? 60;
+	const max = column?.maxSize ?? 800;
+	return Math.min(max, Math.max(min, width));
+}
+/**
+* Drag- and keyboard-driven column resizing, controlled or uncontrolled.
+*
+* Pointer listeners live on `window` so the drag survives the pointer leaving
+* the header, and the teardown is held in a ref so unmounting mid-drag cannot
+* leave listeners or the `col-resize` body cursor behind.
+*/
+function useTableColumnResize({ columns, enabled = false, columnSizing, defaultColumnSizing, onColumnSizingChange, mode = ColumnResizeMode.ON_CHANGE }) {
+	const [internalSizing, setInternalSizing] = useState(defaultColumnSizing ?? {});
+	const [resizingColumnId, setResizingColumnId] = useState(null);
+	const isControlled = columnSizing !== void 0;
+	const resolvedSizing = isControlled ? columnSizing : internalSizing;
+	const sizingRef = useRef(resolvedSizing);
+	const columnsRef = useRef(columns);
+	const onChangeRef = useRef(onColumnSizingChange);
+	useEffect(() => {
+		sizingRef.current = resolvedSizing;
+		columnsRef.current = columns;
+		onChangeRef.current = onColumnSizingChange;
+	});
+	const dragRef = useRef(null);
+	const teardownRef = useRef(null);
+	useEffect(() => () => teardownRef.current?.(), []);
+	const commitWidth = useCallback((columnId, width) => {
+		const next = {
+			...sizingRef.current,
+			[columnId]: width
+		};
+		sizingRef.current = next;
+		if (!isControlled) setInternalSizing(next);
+		onChangeRef.current?.(next);
+	}, [isControlled]);
+	const handleColumnSizingChange = useCallback((updater) => {
+		const next = typeof updater === "function" ? updater(sizingRef.current) : updater;
+		sizingRef.current = next;
+		if (!isControlled) setInternalSizing(next);
+		onChangeRef.current?.(next);
+	}, [isControlled]);
+	const findColumn = useCallback((columnId) => columnsRef.current.find((column) => column.id === columnId), []);
+	const getColumnWidth = useCallback((columnId) => {
+		const column = findColumn(columnId);
+		return sizingRef.current[columnId] ?? column?.size ?? 150;
+	}, [findColumn]);
+	const canResizeColumn = useCallback((column) => enabled && column.enableResizing !== false, [enabled]);
+	const startResize = useCallback((columnId, clientX, measuredWidth) => {
+		const column = findColumn(columnId);
+		if (!enabled || !column || column.enableResizing === false) return;
+		teardownRef.current?.();
+		const startWidth = measuredWidth ?? getColumnWidth(columnId);
+		dragRef.current = {
+			columnId,
+			startX: clientX,
+			startWidth,
+			latestWidth: startWidth
+		};
+		setResizingColumnId(columnId);
+		const onPointerMove = (event) => {
+			const drag = dragRef.current;
+			if (!drag) return;
+			const width = clampWidth(findColumn(drag.columnId), drag.startWidth + (event.clientX - drag.startX));
+			drag.latestWidth = width;
+			if (mode === ColumnResizeMode.ON_CHANGE) commitWidth(drag.columnId, width);
+		};
+		const teardown = () => {
+			window.removeEventListener("pointermove", onPointerMove);
+			window.removeEventListener("pointerup", onPointerUp);
+			window.removeEventListener("pointercancel", onPointerUp);
+			document.body.style.cursor = "";
+			document.body.style.userSelect = "";
+			dragRef.current = null;
+			teardownRef.current = null;
+			setResizingColumnId(null);
+		};
+		function onPointerUp() {
+			const drag = dragRef.current;
+			if (drag && mode === ColumnResizeMode.ON_END) commitWidth(drag.columnId, drag.latestWidth);
+			teardown();
+		}
+		teardownRef.current = teardown;
+		window.addEventListener("pointermove", onPointerMove);
+		window.addEventListener("pointerup", onPointerUp);
+		window.addEventListener("pointercancel", onPointerUp);
+		document.body.style.cursor = "col-resize";
+		document.body.style.userSelect = "none";
+	}, [
+		enabled,
+		mode,
+		commitWidth,
+		findColumn,
+		getColumnWidth
+	]);
+	const resizeByKeyboard = useCallback((columnId, event) => {
+		const column = findColumn(columnId);
+		if (!enabled || !column || column.enableResizing === false) return;
+		const step = event.shiftKey ? KEYBOARD_RESIZE_STEP_LARGE_PX : KEYBOARD_RESIZE_STEP_PX;
+		if (event.key === "ArrowLeft") {
+			event.preventDefault();
+			commitWidth(columnId, clampWidth(column, getColumnWidth(columnId) - step));
+			return;
+		}
+		if (event.key === "ArrowRight") {
+			event.preventDefault();
+			commitWidth(columnId, clampWidth(column, getColumnWidth(columnId) + step));
+			return;
+		}
+		if (event.key === "Home") {
+			event.preventDefault();
+			commitWidth(columnId, clampWidth(column, column.size ?? 150));
+		}
+	}, [
+		enabled,
+		commitWidth,
+		findColumn,
+		getColumnWidth
+	]);
+	const getColumnResizeBounds = useCallback((columnId) => {
+		const column = findColumn(columnId);
+		return {
+			min: column?.minSize ?? 60,
+			max: column?.maxSize ?? 800,
+			current: sizingRef.current[columnId] ?? column?.size
+		};
+	}, [findColumn]);
+	return useMemo(() => ({
+		columnSizing: resolvedSizing,
+		onColumnSizingChange: handleColumnSizingChange,
+		resizingColumnId,
+		canResizeColumn,
+		startResize,
+		resizeByKeyboard,
+		getColumnResizeBounds
+	}), [
+		resolvedSizing,
+		handleColumnSizingChange,
+		resizingColumnId,
+		canResizeColumn,
+		startResize,
+		resizeByKeyboard,
+		getColumnResizeBounds
+	]);
+}
+//#endregion
+export { useTableColumnResize };