@eocrm/design-system 0.6.24 → 0.8.0

package/dist/components/DataTable/types.d.ts

@@ -0,0 +1,254 @@
+import type { ReactNode, MouseEvent as ReactMouseEvent } from 'react';
+/** Cell / header text alignment. */
+export type ColumnAlign = 'start' | 'center' | 'end';
+/** Single-column sort state. v1 is single-column only; multi-column is a future extension. */
+export interface SortState {
+    columnId: string;
+    direction: 'asc' | 'desc';
+}
+/** Ordered list of column ids (includes hidden columns at their absolute positions). */
+export type ColumnOrderState = string[];
+/** Map column id → resolved width in px. Missing entries fall back to `ColumnDef.size` or the default (120). */
+export type ColumnSizingState = Record<string, number>;
+/** Map column id → visible flag. Missing entries are treated as `true` (visible). */
+export type ColumnVisibilityState = Record<string, boolean>;
+/**
+ * Ordered pin lists per side. Phase 1 plumbs this state but does not render
+ * the sticky CSS — rendering effects ship in Phase 2.
+ */
+export interface ColumnPinningState {
+    left: string[];
+    right: string[];
+}
+/** Map row id → selected flag. Missing entries treated as `false`. */
+export type RowSelectionState = Record<string, boolean>;
+/** Map row id → expanded flag. Phase 1 plumbs state; rendering ships in Phase 3. */
+export type ExpandedRowsState = Record<string, boolean>;
+/** setState-style updater: either the next value, or a function (prev) => next. */
+export type Updater<S> = S | ((prev: S) => S);
+/** Header render-prop context. */
+export interface HeaderContext<T = unknown> {
+    column: ColumnDef<T>;
+    instance: DataTableInstance<T>;
+}
+/** Cell render-prop context. */
+export interface CellContext<T> {
+    row: T;
+    rowId: string;
+    column: ColumnDef<T>;
+    instance: DataTableInstance<T>;
+}
+/** Descriptor for one column. Keyed by `id` — used as the key for all per-column state. */
+export interface ColumnDef<T> {
+    /** Stable id. Used as key for column order, sizing, visibility, pinning state. */
+    id: string;
+    /** Header content. String, node, or a render-prop receiving HeaderContext. */
+    header: ReactNode | ((ctx: HeaderContext<T>) => ReactNode);
+    /** Cell content for a row. */
+    cell: (row: T, ctx: CellContext<T>) => ReactNode;
+    /** Cell text alignment. Defaults to 'start'. */
+    align?: ColumnAlign;
+    /** Default width in px when no entry in ColumnSizingState. Defaults to 120. */
+    size?: number;
+    /** Min width during resize (px). Defaults to 40. */
+    minSize?: number;
+    /** Max width during resize (px). Defaults to undefined (no max). */
+    maxSize?: number;
+    /** Whether the column can be reordered via drag. Defaults true. */
+    enableReorder?: boolean;
+    /** Whether the column can be resized via the handle. Defaults true. */
+    enableResize?: boolean;
+    /** Whether the column can be hidden via the visibility menu. Defaults true. */
+    enableHide?: boolean;
+    /** Whether the column can be pinned. Defaults true. (Phase 2 will use this.) */
+    enablePin?: boolean;
+    /**
+     * Server-side sortable. When true, the header label is clickable and
+     * keyboard-actionable; toggling fires onSortChange. DataTable does
+     * not perform client-side sorting.
+     */
+    sortable?: boolean;
+    /**
+     * Plain-text column label. Used by the visibility menu and, when
+     * `DataTable.collapseBelow` is set, by the visual card-field label and resize
+     * separator name. Falls back to a string `header`; card fields with neither
+     * stay visually unlabelled, and the visibility menu falls back to `id` —
+     * that menu is the one place a column's raw id can still reach a user.
+     * Resize separators do NOT: they take a generic "Resize this column".
+     *
+     * It also NAMES the column header, but only when `header` is not a
+     * text-rendering string — i.e. a ReactNode, a render function, or `''`. So
+     * `<span>Rev</span>` with `visibilityLabel: "Revenue (USD)"` announces
+     * "Revenue (USD)", NOT "Rev". A string header always names itself and this
+     * never overrides it.
+     *
+     * That override is deliberate. Deciding at runtime whether a ReactNode names
+     * itself needs the accessible name, and seven attempts to approximate that
+     * from the DOM each shipped either a raw `column.id` in the announcement or
+     * an unnamed column header. The rule is static instead, and the cost is that
+     * a node which DOES name itself is overridden when you also set this.
+     *
+     * Set it on every non-text header. Without it the component will not invent
+     * a name: `column.id` is the only candidate left and a developer identifier
+     * is not something to read aloud, so it is used for nothing — not the
+     * header, not the drag grip, not the resize handle.
+     *
+     * What such a header announces, measured off Chromium's AX tree: it falls
+     * through to NAME-FROM-CONTENT, because an `aria-labelledby` resolving to no
+     * text is marked invalid rather than treated as a name. So the cell's own
+     * controls name it — "Drag to reorder this column", or under `collapseBelow`
+     * the resize handle's live pixel width. `header: ''` is special-cased to a
+     * generic label so the width cannot win; a ReactNode that renders nothing is
+     * indistinguishable from one that names itself, so it is not.
+     *
+     * None of those is a name you chose. Set this prop on every text-less
+     * header; your axe run flags what is left via `empty-table-header`.
+     *
+     * An EMPTY string counts as unset, not as an explicit name, in ALL THREE
+     * places that read this prop — the column header (`HeaderCell`), the
+     * responsive card's field label (`BodyRow`) and the visibility menu row
+     * (`ColumnVisibilityTrigger`). Each falls back to a string `header` rather
+     * than discarding it, and the menu falls on past that to `id`. #534
+     * converted only the first, which left one prop meaning "unset" in the
+     * header and "render nothing" two files over; #536 made them agree.
+     *
+     * There is deliberately no way to blank a column's label with `''`. The menu
+     * row is the case that decides it: a blank checkbox row is unidentifiable,
+     * which is strictly worse than the raw `id` the fallback chain already
+     * treats as a last resort.
+     *
+     * A WHITESPACE-ONLY `header` is treated the same way, in all three, for the
+     * same reason: `'   '` renders no text, so it is not a label. Only the menu
+     * trimmed at first, which left the sentence above true of `''` but not of
+     * `'   '`.
+     */
+    visibilityLabel?: string;
+    /**
+     * Initial pin side for this column. Used as the derived default for
+     * `columnPinning` when the consumer doesn't pass `columnPinning` or
+     * `defaultColumnPinning`. Lower-precedence than either — explicit
+     * `defaultColumnPinning` on the hook always wins.
+     *
+     * Runtime pinning (e.g. `instance.pinColumn(id, 'right')`) updates the
+     * `columnPinning` state and takes over from this initial value.
+     */
+    pin?: 'left' | 'right';
+}
+/** Public options to `useDataTable<T>(...)`. */
+export interface UseDataTableOptions<T> {
+    data: T[];
+    pinnedRows?: T[];
+    columns: ColumnDef<T>[];
+    /** Required. Stable id per row — used by selection, expansion, and `getRowId`. */
+    getRowId: (row: T) => string;
+    /** Total server-side row count. Surfaced as `aria-rowcount` for screen readers. */
+    rowCount?: number;
+    /** Opt-in to the selection auto-column. Defaults false. */
+    enableRowSelection?: boolean;
+    /** Controlled column order. Pass with `onColumnOrderChange` to manage state externally. */
+    columnOrder?: ColumnOrderState;
+    /** Initial column order when uncontrolled. Defaults to `columns.map(c => c.id)`. */
+    defaultColumnOrder?: ColumnOrderState;
+    /** Fires when the order changes (drag-reorder or programmatic set). */
+    onColumnOrderChange?: (next: ColumnOrderState) => void;
+    /** Controlled column sizing map (column id → width in px). Pass with `onColumnSizingChange`. */
+    columnSizing?: ColumnSizingState;
+    /** Initial column sizing when uncontrolled. Missing entries fall back to `ColumnDef.size` or 120px. */
+    defaultColumnSizing?: ColumnSizingState;
+    /** Fires when any column is resized. */
+    onColumnSizingChange?: (next: ColumnSizingState) => void;
+    /** Controlled column visibility map (column id → visible flag). Pass with `onColumnVisibilityChange`. */
+    columnVisibility?: ColumnVisibilityState;
+    /** Initial column visibility when uncontrolled. Missing entries are treated as visible. */
+    defaultColumnVisibility?: ColumnVisibilityState;
+    /** Fires when column visibility toggles (e.g. via `<ColumnVisibilityTrigger>`). */
+    onColumnVisibilityChange?: (next: ColumnVisibilityState) => void;
+    /**
+     * Controlled column pinning state. Pass with `onColumnPinningChange`.
+     * Note: Phase 1 plumbs this state — sticky rendering ships in Phase 2.
+     */
+    columnPinning?: ColumnPinningState;
+    /**
+     * Initial column pinning when uncontrolled. Defaults to `{ left: [], right: [] }`.
+     * Note: Phase 1 plumbs this state — sticky rendering ships in Phase 2.
+     */
+    defaultColumnPinning?: ColumnPinningState;
+    /** Fires when a column is pinned or unpinned. */
+    onColumnPinningChange?: (next: ColumnPinningState) => void;
+    /** Controlled row selection map (row id → selected flag). Pass with `onRowSelectionChange`. */
+    rowSelection?: RowSelectionState;
+    /** Initial row selection when uncontrolled. Defaults to `{}` (nothing selected). */
+    defaultRowSelection?: RowSelectionState;
+    /** Fires when any row selection changes (per-row toggle or select-all). */
+    onRowSelectionChange?: (next: RowSelectionState) => void;
+    /**
+     * Controlled expanded-rows map (row id → expanded flag). Pass with `onExpandedRowsChange`.
+     * Note: Phase 1 plumbs this state — expansion rendering ships in Phase 3.
+     */
+    expandedRows?: ExpandedRowsState;
+    /**
+     * Initial expanded rows when uncontrolled. Defaults to `{}` (all collapsed).
+     * Note: Phase 1 plumbs this state — expansion rendering ships in Phase 3.
+     */
+    defaultExpandedRows?: ExpandedRowsState;
+    /** Fires when a row is expanded or collapsed. */
+    onExpandedRowsChange?: (next: ExpandedRowsState) => void;
+    /** Controlled single-column sort state. Pass with `onSortChange` for server-driven sorting. */
+    sort?: SortState | null;
+    /** Initial sort when uncontrolled. Defaults to `null` (unsorted). */
+    defaultSort?: SortState | null;
+    /** Fires when the sort state changes (column header click cycles null → asc → desc → null). */
+    onSortChange?: (next: SortState | null) => void;
+    onRowClick?: (row: T, event: ReactMouseEvent<HTMLTableRowElement>) => void;
+    /** Phase 1 plumbs this prop but does not render expansion. Rendering ships in Phase 3. */
+    renderExpandedRow?: (row: T) => ReactNode;
+}
+/** Returned by `useDataTable<T>(...)`. Passed into `<DataTable instance={...} />`. */
+export interface DataTableInstance<T> {
+    data: T[];
+    pinnedRows: T[];
+    columns: ColumnDef<T>[];
+    getRowId: (row: T) => string;
+    rowCount?: number;
+    enableRowSelection: boolean;
+    hasExpansion: boolean;
+    onRowClick?: UseDataTableOptions<T>['onRowClick'];
+    renderExpandedRow?: UseDataTableOptions<T>['renderExpandedRow'];
+    columnOrder: ColumnOrderState;
+    columnSizing: ColumnSizingState;
+    columnVisibility: ColumnVisibilityState;
+    columnPinning: ColumnPinningState;
+    rowSelection: RowSelectionState;
+    expandedRows: ExpandedRowsState;
+    sort: SortState | null;
+    visibleColumns: ColumnDef<T>[];
+    leftPinnedColumns: ColumnDef<T>[];
+    rightPinnedColumns: ColumnDef<T>[];
+    unpinnedColumns: ColumnDef<T>[];
+    columnSizesPx: Record<string, number>;
+    leftPinOffsets: Record<string, number>;
+    rightPinOffsets: Record<string, number>;
+    setColumnOrder: (updater: Updater<ColumnOrderState>) => void;
+    setColumnSizing: (updater: Updater<ColumnSizingState>) => void;
+    setColumnVisibility: (updater: Updater<ColumnVisibilityState>) => void;
+    setColumnPinning: (updater: Updater<ColumnPinningState>) => void;
+    setRowSelection: (updater: Updater<RowSelectionState>) => void;
+    setExpandedRows: (updater: Updater<ExpandedRowsState>) => void;
+    setSort: (updater: Updater<SortState | null>) => void;
+    /** Toggle selection of a single row by id. */
+    toggleRowSelection: (rowId: string) => void;
+    /** Toggle selection of all rows in `data` (does not affect `pinnedRows`). */
+    toggleAllOnPage: () => void;
+    /** All rows in `data` are selected (excludes `pinnedRows`). */
+    isAllOnPageSelected: () => boolean;
+    /** Some but not all rows in `data` are selected — drives the header checkbox indeterminate state. */
+    isSomeOnPageSelected: () => boolean;
+    /** Toggle expansion of a single row by id. */
+    toggleRowExpanded: (rowId: string) => void;
+    /** Toggle visibility of a column by id. Guarded against hiding the last visible hidable column when called via `<ColumnVisibilityTrigger>`. */
+    toggleColumnVisibility: (columnId: string) => void;
+    /** Pin a column to `left`, `right`, or `false` to unpin. Pinning order within a side is append-on-pin. */
+    pinColumn: (columnId: string, side: 'left' | 'right' | false) => void;
+    /** Cycle sort state for a column: null → asc → desc → null. */
+    toggleSort: (columnId: string) => void;
+}

package/dist/components/DataTable/useColumnDragShift.d.ts

@@ -0,0 +1,85 @@
+import { type RefObject } from 'react';
+import { type DragRangeX } from './columnShift.js';
+/**
+ * Measure how far the active column may travel, in px, from the REAL rendered
+ * geometry of the header cells inside `root`.
+ *
+ * Declared widths (`columnSizingPx` / the `<col>` elements) cannot be used for
+ * this. `DataTable.module.scss` sets `table-layout: fixed;
+ * width: var(--data-table-width, 0); min-width: 100%`, so whenever the column
+ * sum is narrower than the scroll wrap the table stretches and every rendered
+ * column is WIDER than declared. Summing
+ * declared widths then under-reports the travel and makes the last slot
+ * unreachable — the exact regression this replaced.
+ *
+ * The bound is the unpinned band, not the table: pinned columns are excluded
+ * from reordering and `reorderRespectingPins` rejects a drop across a pin
+ * boundary, so travelling over a pin would take the column somewhere it can
+ * never land. `orderedIds` is therefore the unpinned columns only.
+ *
+ * All three rects are read in the same instant from the same scrolling
+ * container, so the differences are correct table-space offsets no matter where
+ * the wrap happens to be scrolled.
+ *
+ * Returns a zeroed range (pin in place) when `root` or any of the three header
+ * cells cannot be found — an unmeasurable drag must not be an unbounded one.
+ */
+export declare function measureDragRangeX(root: HTMLElement | null, orderedIds: string[], activeId: string): DragRangeX;
+/**
+ * Write one custom property per shifted column onto `root`, and remove the
+ * properties for any column that shifted on the previous frame but not this
+ * one. Returns the ids written, to be passed back as `previousIds` next frame.
+ *
+ * Custom properties are set on the table element, NOT a transform — a
+ * transformed ancestor would establish a containing block and break
+ * `position: sticky` on pinned cells. Variables inherit harmlessly.
+ */
+export declare function applyColumnShifts(root: HTMLElement | null, shifts: Record<string, number>, previousIds: string[]): string[];
+/** Inputs for {@link useColumnDragShift}. */
+export interface ColumnDragShiftArgs {
+    /** The `<table>` element the custom properties are written to. */
+    rootRef: RefObject<HTMLElement | null>;
+    /** False when `dragWholeColumn` is off — the hook then does nothing. */
+    enabled: boolean;
+    /**
+     * ALL unpinned column ids in current visual order — including columns with
+     * `enableReorder: false`. Do NOT filter by reorderability: a non-reorderable
+     * column cannot be *picked up*, but it is still displaced when a reorderable
+     * column is dragged past it (and the drop moves it for real). Omit it and it
+     * never shifts, so it and its neighbour render on top of each other.
+     */
+    orderedIds: string[];
+    /** Rendered width per column id, px. */
+    widths: Record<string, number>;
+    /**
+     * Caller-owned slot for the travel range measured at drag start, so the
+     * `DndContext` modifier (which lives in the PARENT of this hook and therefore
+     * cannot read a return value from it) clamps against the same numbers.
+     * Written on drag start, nulled on drag end/cancel.
+     */
+    dragRangeRef: RefObject<DragRangeX | null>;
+    /**
+     * Caller-owned slot for the last member of `orderedIds` this drag resolved as
+     * its target, or null before it resolves one. Written here — nulled at drag
+     * start, set on every `onDragOver` whose target is in the band — and read
+     * both here, to keep the displaced neighbours parked when dnd-kit hands over
+     * something the drop cannot use, and by the drop handler in the parent — but
+     * there only in whole-column mode, where this ref IS the preview. The
+     * header-only path has its own preview (dnd-kit's strategy), which retracts
+     * in exactly this situation, so it discards instead. See the `lastSlotIdRef`
+     * comment in `DataTable` for what "cannot use" covers.
+     */
+    lastSlotIdRef: RefObject<string | null>;
+    /** Called once at drag start (true) and once at drag end/cancel (false). */
+    onDragActiveChange: (active: boolean) => void;
+}
+/**
+ * Subscribes to the surrounding `DndContext` and publishes per-column drag
+ * offsets as CSS custom properties on the table element.
+ *
+ * MUST be called from a component rendered inside `<DndContext>`. Mount it in
+ * a leaf that renders `null`, never in `DataTable` itself — `useDndMonitor`'s
+ * callbacks fire on every pointer move, and keeping them in a leaf guarantees
+ * the table body is never re-rendered mid-drag.
+ */
+export declare function useColumnDragShift({ rootRef, enabled, orderedIds, widths, dragRangeRef, lastSlotIdRef, onDragActiveChange, }: ColumnDragShiftArgs): void;

package/dist/components/DataTable/useColumnDragShift.js

@@ -0,0 +1,114 @@
+'use client';
+import { clampX, computeColumnShifts, shiftVarName } from "./columnShift.js";
+import { useRef } from "react";
+import { useDndMonitor } from "@dnd-kit/core";
+// src/components/DataTable/useColumnDragShift.ts
+/**
+* Measure how far the active column may travel, in px, from the REAL rendered
+* geometry of the header cells inside `root`.
+*
+* Declared widths (`columnSizingPx` / the `<col>` elements) cannot be used for
+* this. `DataTable.module.scss` sets `table-layout: fixed;
+* width: var(--data-table-width, 0); min-width: 100%`, so whenever the column
+* sum is narrower than the scroll wrap the table stretches and every rendered
+* column is WIDER than declared. Summing
+* declared widths then under-reports the travel and makes the last slot
+* unreachable — the exact regression this replaced.
+*
+* The bound is the unpinned band, not the table: pinned columns are excluded
+* from reordering and `reorderRespectingPins` rejects a drop across a pin
+* boundary, so travelling over a pin would take the column somewhere it can
+* never land. `orderedIds` is therefore the unpinned columns only.
+*
+* All three rects are read in the same instant from the same scrolling
+* container, so the differences are correct table-space offsets no matter where
+* the wrap happens to be scrolled.
+*
+* Returns a zeroed range (pin in place) when `root` or any of the three header
+* cells cannot be found — an unmeasurable drag must not be an unbounded one.
+*/
+function measureDragRangeX(root, orderedIds, activeId) {
+	const zero = {
+		min: 0,
+		max: 0
+	};
+	if (!root || orderedIds.length === 0) return zero;
+	const rectOf = (id) => root.querySelector(`th[data-dt-column-id=${CSS.escape(id)}]`)?.getBoundingClientRect();
+	const active = rectOf(activeId);
+	const first = rectOf(orderedIds[0]);
+	const last = rectOf(orderedIds[orderedIds.length - 1]);
+	if (!active || !first || !last) return zero;
+	return {
+		min: first.left - active.left,
+		max: last.right - active.right
+	};
+}
+/**
+* Write one custom property per shifted column onto `root`, and remove the
+* properties for any column that shifted on the previous frame but not this
+* one. Returns the ids written, to be passed back as `previousIds` next frame.
+*
+* Custom properties are set on the table element, NOT a transform — a
+* transformed ancestor would establish a containing block and break
+* `position: sticky` on pinned cells. Variables inherit harmlessly.
+*/
+function applyColumnShifts(root, shifts, previousIds) {
+	if (!root) return [];
+	for (const id of previousIds) if (!(id in shifts)) root.style.removeProperty(shiftVarName(id));
+	const written = [];
+	for (const [id, px] of Object.entries(shifts)) {
+		root.style.setProperty(shiftVarName(id), `${Math.round(px)}px`);
+		written.push(id);
+	}
+	return written;
+}
+/**
+* Subscribes to the surrounding `DndContext` and publishes per-column drag
+* offsets as CSS custom properties on the table element.
+*
+* MUST be called from a component rendered inside `<DndContext>`. Mount it in
+* a leaf that renders `null`, never in `DataTable` itself — `useDndMonitor`'s
+* callbacks fire on every pointer move, and keeping them in a leaf guarantees
+* the table body is never re-rendered mid-drag.
+*/
+function useColumnDragShift({ rootRef, enabled, orderedIds, widths, dragRangeRef, lastSlotIdRef, onDragActiveChange }) {
+	const writtenRef = useRef([]);
+	const clear = () => {
+		writtenRef.current = applyColumnShifts(rootRef.current, {}, writtenRef.current);
+		dragRangeRef.current = null;
+		onDragActiveChange(false);
+	};
+	useDndMonitor({
+		onDragStart(event) {
+			dragRangeRef.current = measureDragRangeX(rootRef.current, orderedIds, String(event.active.id));
+			lastSlotIdRef.current = null;
+			if (!enabled) return;
+			onDragActiveChange(true);
+		},
+		onDragOver(event) {
+			const id = event.over ? String(event.over.id) : null;
+			if (id != null && orderedIds.includes(id)) lastSlotIdRef.current = id;
+		},
+		onDragMove(event) {
+			if (!enabled) return;
+			const shifts = computeColumnShifts({
+				orderedIds,
+				activeId: String(event.active.id),
+				overId: lastSlotIdRef.current,
+				widths,
+				deltaX: clampX(event.delta.x, dragRangeRef.current ?? {
+					min: 0,
+					max: 0
+				})
+			});
+			writtenRef.current = applyColumnShifts(rootRef.current, shifts, writtenRef.current);
+		},
+		onDragEnd() {
+			clear();
+		},
+		onDragCancel() {
+			clear();
+		}
+	});
+}
+export { applyColumnShifts, measureDragRangeX, useColumnDragShift };

package/dist/components/DataTable/useDataTable.d.ts

@@ -0,0 +1,60 @@
+import type { DataTableInstance, UseDataTableOptions } from './types.js';
+/**
+ * Headless state machine for `<DataTable>`. Implements the Radix-style
+ * controlled/uncontrolled pattern for every state piece. Returns an
+ * `instance` object passed into `<DataTable instance={...} />` and any
+ * companion components (e.g. `<DataTable.ColumnVisibilityTrigger>`).
+ *
+ * Pure logic — no DOM, no refs to elements, no side effects beyond firing
+ * the consumer's onChange callbacks.
+ *
+ * @example
+ * const instance = useDataTable<Deal>({
+ *   data,
+ *   columns,
+ *   getRowId: (r) => r.id,
+ *   sort,
+ *   onSortChange: setSort,
+ * });
+ * <DataTable instance={instance} aria-label="Deals" />
+ *
+ * @example
+ * // With row selection and column visibility:
+ * const instance = useDataTable<Deal>({
+ *   data,
+ *   columns,
+ *   getRowId: (r) => r.id,
+ *   enableRowSelection: true,
+ *   onRowSelectionChange: setRowSelection,
+ * });
+ * <Cluster justify="end">
+ *   <ColumnVisibilityTrigger instance={instance} />
+ * </Cluster>
+ * <DataTable instance={instance} aria-label="Deals" />
+ *
+ * @example
+ * // Fully controlled column order + sizing (e.g. persisted to localStorage):
+ * const instance = useDataTable<Deal>({
+ *   data,
+ *   columns,
+ *   getRowId: (r) => r.id,
+ *   columnOrder: savedOrder,
+ *   onColumnOrderChange: setSavedOrder,
+ *   columnSizing: savedSizing,
+ *   onColumnSizingChange: setSavedSizing,
+ * });
+ *
+ * @remarks When NOT to use
+ * - For a read-only static table — use `<Table>` directly. `useDataTable`
+ *   adds overhead you don't need when there's no column or row interactivity.
+ *
+ * @remarks Anti-patterns
+ * - ❌ Passing both `value` and `defaultValue` for the same state piece — `value`
+ *   wins and `defaultValue` is silently ignored. Pick one.
+ * - ❌ Mutating `columns` identity across renders. The hook captures
+ *   `defaultColumnOrder` from `columns` once at mount; later identity changes
+ *   don't trigger a re-derive. Pass a stable reference (`useMemo` or module-level).
+ * - ❌ Client-sorting `data` AND passing controlled `sort`. DataTable is
+ *   server-driven — `data` must be the pre-sorted slice the server returned.
+ */
+export declare function useDataTable<T>(options: UseDataTableOptions<T>): DataTableInstance<T>;