@eocrm/design-system 0.0.0-stage → 0.6.17

package/src/components/DataTable/useColumnDragShift.ts

@@ -0,0 +1,216 @@
+import { useRef, type RefObject } from 'react';
+import { useDndMonitor } from '@dnd-kit/core';
+import { clampX, computeColumnShifts, shiftVarName, type DragRangeX } from './columnShift';
+
+/**
+ * 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: max-content;
+ * 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 function measureDragRangeX(
+  root: HTMLElement | null,
+  orderedIds: string[],
+  activeId: string,
+): DragRangeX {
+  const zero = { min: 0, max: 0 };
+  if (!root || orderedIds.length === 0) return zero;
+
+  // Column ids are consumer-supplied and routinely contain dots, spaces, or
+  // non-ASCII text — CSS.escape is what keeps them legal in a selector.
+  const rectOf = (id: string) =>
+    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.
+ */
+export function applyColumnShifts(
+  root: HTMLElement | null,
+  shifts: Record<string, number>,
+  previousIds: string[],
+): string[] {
+  if (!root) return [];
+
+  for (const id of previousIds) {
+    if (!(id in shifts)) root.style.removeProperty(shiftVarName(id));
+  }
+
+  const written: string[] = [];
+  for (const [id, px] of Object.entries(shifts)) {
+    // Round: sub-pixel precision is invisible and would rewrite the style
+    // attribute on every pointer event for no visual gain.
+    root.style.setProperty(shiftVarName(id), `${Math.round(px)}px`);
+    written.push(id);
+  }
+  return written;
+}
+
+/** 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 function useColumnDragShift({
+  rootRef,
+  enabled,
+  orderedIds,
+  widths,
+  dragRangeRef,
+  lastSlotIdRef,
+  onDragActiveChange,
+}: ColumnDragShiftArgs): void {
+  const writtenRef = useRef<string[]>([]);
+
+  const clear = () => {
+    writtenRef.current = applyColumnShifts(rootRef.current, {}, writtenRef.current);
+    dragRangeRef.current = null;
+    onDragActiveChange(false);
+  };
+
+  useDndMonitor({
+    onDragStart(event) {
+      // Measured even when `enabled` is false: the header-only path does not
+      // use this hook's shift variables, but its DndContext modifier reads the
+      // very same range out of `dragRangeRef`.
+      dragRangeRef.current = measureDragRangeX(
+        rootRef.current,
+        orderedIds,
+        String(event.active.id),
+      );
+      // Ungated deliberately, even though only the whole-column path reads it:
+      // `dragWholeColumn` can be flipped between drags, so a clear that ran
+      // only while enabled would leave a stale target behind for the first
+      // drag after it is switched back on. Cleared at drag START rather than
+      // at drag end so one drag can never inherit the previous drag's target,
+      // and so the drop handler is free to read it without depending on which
+      // of dnd-kit's two end callbacks runs first.
+      lastSlotIdRef.current = null;
+      if (!enabled) return;
+      onDragActiveChange(true);
+    },
+    onDragOver(event) {
+      // Band members only. A pinned column is a live droppable (dnd-kit's
+      // boolean `disabled` stands down the draggable alone) and, being sticky,
+      // it covers the band's last columns on a scrolled table — so it wins
+      // collisions it can never accept a drop from.
+      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),
+        // #383: the last BAND slot, which is `over` itself whenever `over` is
+        // one — `onDragOver` above has already recorded it. Reading `event.over`
+        // raw is what used to collapse the preview: `computeColumnShifts` finds
+        // no index for an out-of-band id, returns the active column's offset
+        // alone, and every displaced neighbour snaps back, leaving the dragged
+        // column overlapping the slot it is about to take. The drop commits
+        // this same id, so preview and commit cannot disagree.
+        overId: lastSlotIdRef.current,
+        widths,
+        // Clamping HERE, not only in the modifier, is what actually bounds the
+        // column. dnd-kit computes `delta` as
+        // `scrollAdjustedTranslate = add(modifiedTranslate, scrollAdjustment)`
+        // — the scroll adjustment is added AFTER modifiers run, so a
+        // modifier-only clamp is escaped by horizontal auto-scroll. Worse, it
+        // ran away: the translated header inflated `scrollWidth`, which let
+        // `scrollLeft` grow, which grew `scrollAdjustment`. `delta` is the
+        // post-adjustment value, so clamping it is authoritative and the
+        // feedback loop cannot start.
+        // Fail CLOSED: an unmeasurable drag is a pinned one, never an
+        // unbounded one. Unreachable today (onDragStart always sets the ref)
+        // but the `??` keeps the guarantee if that ever stops being true.
+        deltaX: clampX(event.delta.x, dragRangeRef.current ?? { min: 0, max: 0 }),
+      });
+      writtenRef.current = applyColumnShifts(rootRef.current, shifts, writtenRef.current);
+    },
+    // Deliberately ungated (unlike onDragStart/onDragMove above): `enabled`
+    // can flip to false mid-drag, and if cleanup were also gated the
+    // properties written at drag start would never be removed and
+    // onDragActiveChange(false) would never fire — the table would be stuck
+    // showing a shifted column. clear() is harmless as a no-op when nothing
+    // was written, so running it unconditionally is always safe.
+    onDragEnd() {
+      clear();
+    },
+    onDragCancel() {
+      clear();
+    },
+  });
+}

package/src/components/DataTable/useDataTable.ts

@@ -0,0 +1,372 @@
+import { useCallback, useMemo } from 'react';
+import { useControllableState } from '../_internal/useControllableState';
+import type {
+  ColumnOrderState,
+  ColumnPinningState,
+  ColumnSizingState,
+  ColumnVisibilityState,
+  DataTableInstance,
+  ExpandedRowsState,
+  RowSelectionState,
+  SortState,
+  UseDataTableOptions,
+} from './types';
+
+const EMPTY_PINNING: ColumnPinningState = { left: [], right: [] };
+
+/**
+ * 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 function useDataTable<T>(options: UseDataTableOptions<T>): DataTableInstance<T> {
+  const {
+    data,
+    pinnedRows = [],
+    columns,
+    getRowId,
+    rowCount,
+    enableRowSelection = false,
+    onRowClick,
+    renderExpandedRow,
+  } = options;
+
+  const defaultColumnOrder = useMemo(
+    () => options.defaultColumnOrder ?? columns.map((c) => c.id),
+    // Intentionally not depending on `columns` — defaultColumnOrder is a
+    // one-time initial value. If columns change identity, consumer must
+    // pass a controlled columnOrder.
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+    [],
+  );
+
+  // Initial pinning derived from `ColumnDef.pin` when the consumer didn't
+  // pass `defaultColumnPinning`. Like `defaultColumnOrder`, this is a one-time
+  // initial value — after mount, runtime calls to `instance.pinColumn(...)`
+  // update the controllable state and take over. Columns with
+  // `enablePin: false` are skipped — a column that opted out of pinning
+  // shouldn't be pinned by its own `pin` field either.
+  const derivedColumnPinning = useMemo<ColumnPinningState>(
+    () => {
+      const left: string[] = [];
+      const right: string[] = [];
+      for (const c of columns) {
+        if (c.enablePin === false) continue;
+        if (c.pin === 'left') left.push(c.id);
+        else if (c.pin === 'right') right.push(c.id);
+      }
+      return left.length === 0 && right.length === 0 ? EMPTY_PINNING : { left, right };
+    },
+    // Same one-time-init rationale as defaultColumnOrder.
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+    [],
+  );
+
+  const [columnOrder, setColumnOrder] = useControllableState<ColumnOrderState>({
+    value: options.columnOrder,
+    defaultValue: defaultColumnOrder,
+    onChange: options.onColumnOrderChange,
+  });
+
+  const [columnSizing, setColumnSizing] = useControllableState<ColumnSizingState>({
+    value: options.columnSizing,
+    defaultValue: options.defaultColumnSizing ?? {},
+    onChange: options.onColumnSizingChange,
+  });
+
+  const [columnVisibility, setColumnVisibility] = useControllableState<ColumnVisibilityState>({
+    value: options.columnVisibility,
+    defaultValue: options.defaultColumnVisibility ?? {},
+    onChange: options.onColumnVisibilityChange,
+  });
+
+  const [columnPinning, setColumnPinning] = useControllableState<ColumnPinningState>({
+    value: options.columnPinning,
+    defaultValue: options.defaultColumnPinning ?? derivedColumnPinning,
+    onChange: options.onColumnPinningChange,
+  });
+
+  const [rowSelection, setRowSelection] = useControllableState<RowSelectionState>({
+    value: options.rowSelection,
+    defaultValue: options.defaultRowSelection ?? {},
+    onChange: options.onRowSelectionChange,
+  });
+
+  const [expandedRows, setExpandedRows] = useControllableState<ExpandedRowsState>({
+    value: options.expandedRows,
+    defaultValue: options.defaultExpandedRows ?? {},
+    onChange: options.onExpandedRowsChange,
+  });
+
+  const [sort, setSort] = useControllableState<SortState | null>({
+    value: options.sort,
+    defaultValue: options.defaultSort ?? null,
+    onChange: options.onSortChange,
+  });
+
+  const DEFAULT_COL_WIDTH = 120;
+
+  const columnsById = useMemo(() => {
+    const m = new Map<string, (typeof columns)[number]>();
+    for (const c of columns) m.set(c.id, c);
+    return m;
+  }, [columns]);
+
+  // columnSizesPx: id → resolved width (sizing state > ColumnDef.size > default)
+  const columnSizesPx = useMemo<Record<string, number>>(() => {
+    const out: Record<string, number> = {};
+    for (const c of columns) {
+      out[c.id] = columnSizing[c.id] ?? c.size ?? DEFAULT_COL_WIDTH;
+    }
+    return out;
+  }, [columns, columnSizing]);
+
+  // visibleColumns: ordered (per columnOrder) and filtered (visibility !== false)
+  const visibleColumns = useMemo(() => {
+    const isVisible = (id: string) => columnVisibility[id] !== false;
+    const ordered: typeof columns = [];
+    for (const id of columnOrder) {
+      const col = columnsById.get(id);
+      if (col && isVisible(id)) ordered.push(col);
+    }
+    // Any column not in columnOrder (e.g. added after init) goes to the end.
+    for (const c of columns) {
+      if (!columnOrder.includes(c.id) && isVisible(c.id)) ordered.push(c);
+    }
+    return ordered;
+  }, [columns, columnsById, columnOrder, columnVisibility]);
+
+  // Pin grouping. Pinning order within a side is given by columnPinning.left/right.
+  const leftPinnedColumns = useMemo(
+    () =>
+      columnPinning.left
+        .map((id) => columnsById.get(id))
+        .filter((c): c is (typeof columns)[number] => !!c && columnVisibility[c.id] !== false),
+    [columnPinning.left, columnsById, columnVisibility],
+  );
+
+  const rightPinnedColumns = useMemo(
+    () =>
+      columnPinning.right
+        .map((id) => columnsById.get(id))
+        .filter((c): c is (typeof columns)[number] => !!c && columnVisibility[c.id] !== false),
+    [columnPinning.right, columnsById, columnVisibility],
+  );
+
+  const unpinnedColumns = useMemo(() => {
+    const pinned = new Set([...columnPinning.left, ...columnPinning.right]);
+    return visibleColumns.filter((c) => !pinned.has(c.id));
+  }, [visibleColumns, columnPinning.left, columnPinning.right]);
+
+  // Pin offsets — cumulative widths from the pinned edge inward.
+  const leftPinOffsets = useMemo<Record<string, number>>(() => {
+    const out: Record<string, number> = {};
+    let acc = 0;
+    for (const col of leftPinnedColumns) {
+      out[col.id] = acc;
+      acc += columnSizesPx[col.id] ?? DEFAULT_COL_WIDTH;
+    }
+    return out;
+  }, [leftPinnedColumns, columnSizesPx]);
+
+  const rightPinOffsets = useMemo<Record<string, number>>(() => {
+    const out: Record<string, number> = {};
+    let acc = 0;
+    // Rightmost pinned column has offset 0; walk right-to-left accumulating.
+    for (let i = rightPinnedColumns.length - 1; i >= 0; i--) {
+      const col = rightPinnedColumns[i]!;
+      out[col.id] = acc;
+      acc += columnSizesPx[col.id] ?? DEFAULT_COL_WIDTH;
+    }
+    return out;
+  }, [rightPinnedColumns, columnSizesPx]);
+
+  const toggleRowSelection = useCallback(
+    (rowId: string) => {
+      setRowSelection((prev) => {
+        const next = { ...prev };
+        if (next[rowId]) delete next[rowId];
+        else next[rowId] = true;
+        return next;
+      });
+    },
+    [setRowSelection],
+  );
+
+  const toggleAllOnPage = useCallback(() => {
+    setRowSelection((prev) => {
+      const pageIds = data.map(getRowId);
+      const allSelected = pageIds.every((id) => prev[id]);
+      if (allSelected) {
+        const next = { ...prev };
+        for (const id of pageIds) delete next[id];
+        return next;
+      }
+      const next = { ...prev };
+      for (const id of pageIds) next[id] = true;
+      return next;
+    });
+  }, [data, getRowId, setRowSelection]);
+
+  const isAllOnPageSelected = useCallback(() => {
+    if (data.length === 0) return false;
+    return data.every((row) => rowSelection[getRowId(row)] === true);
+  }, [data, getRowId, rowSelection]);
+
+  const isSomeOnPageSelected = useCallback(() => {
+    if (data.length === 0) return false;
+    let some = false;
+    let all = true;
+    for (const row of data) {
+      if (rowSelection[getRowId(row)]) some = true;
+      else all = false;
+    }
+    return some && !all;
+  }, [data, getRowId, rowSelection]);
+
+  const toggleRowExpanded = useCallback(
+    (rowId: string) => {
+      setExpandedRows((prev) => {
+        const next = { ...prev };
+        if (next[rowId]) delete next[rowId];
+        else next[rowId] = true;
+        return next;
+      });
+    },
+    [setExpandedRows],
+  );
+
+  const toggleColumnVisibility = useCallback(
+    (columnId: string) => {
+      setColumnVisibility((prev) => ({
+        ...prev,
+        [columnId]: prev[columnId] === false ? true : false,
+      }));
+    },
+    [setColumnVisibility],
+  );
+
+  const pinColumn = useCallback(
+    (columnId: string, side: 'left' | 'right' | false) => {
+      setColumnPinning((prev) => {
+        const left = prev.left.filter((id) => id !== columnId);
+        const right = prev.right.filter((id) => id !== columnId);
+        if (side === 'left') left.push(columnId);
+        else if (side === 'right') right.push(columnId);
+        return { left, right };
+      });
+    },
+    [setColumnPinning],
+  );
+
+  const toggleSort = useCallback(
+    (columnId: string) => {
+      setSort((prev) => {
+        if (!prev || prev.columnId !== columnId) {
+          return { columnId, direction: 'asc' };
+        }
+        if (prev.direction === 'asc') return { columnId, direction: 'desc' };
+        return null;
+      });
+    },
+    [setSort],
+  );
+
+  return {
+    data,
+    pinnedRows,
+    columns,
+    getRowId,
+    rowCount,
+    enableRowSelection,
+    hasExpansion: renderExpandedRow != null,
+    onRowClick,
+    renderExpandedRow,
+
+    columnOrder,
+    columnSizing,
+    columnVisibility,
+    columnPinning,
+    rowSelection,
+    expandedRows,
+    sort,
+
+    visibleColumns,
+    leftPinnedColumns,
+    rightPinnedColumns,
+    unpinnedColumns,
+    columnSizesPx,
+    leftPinOffsets,
+    rightPinOffsets,
+
+    setColumnOrder,
+    setColumnSizing,
+    setColumnVisibility,
+    setColumnPinning,
+    setRowSelection,
+    setExpandedRows,
+    setSort,
+
+    toggleRowSelection,
+    toggleAllOnPage,
+    isAllOnPageSelected,
+    isSomeOnPageSelected,
+    toggleRowExpanded,
+    toggleColumnVisibility,
+    pinColumn,
+    toggleSort,
+  };
+}

package/src/components/DataTable/useResizeHandle.ts

@@ -0,0 +1,97 @@
+import { useCallback, useEffect, useRef, useState } from 'react';
+import type { PointerEvent as ReactPointerEvent } from 'react';
+
+interface UseResizeHandleOptions {
+  initialWidth: number;
+  minWidth: number;
+  maxWidth?: number;
+  onResize: (nextWidth: number) => void;
+}
+
+interface ResizeHandleApi {
+  isResizing: boolean;
+  onPointerDown: (e: ReactPointerEvent<HTMLElement>) => void;
+}
+
+/**
+ * Pointer-based resize-handle hook. Attach `onPointerDown` to the handle
+ * element. While dragging, `pointermove` on window fires `onResize` with
+ * the clamped width; `pointerup` / `pointercancel` ends the drag.
+ *
+ * `initialWidth` is captured at pointerdown — callers don't need to keep
+ * it in sync between events (the hook holds the start width internally).
+ *
+ * @remarks
+ * **When NOT to use / anti-patterns**
+ *
+ * - Do not use this hook outside of a column-resize context. It is
+ *   purpose-built for DataTable header cells and assumes a horizontal
+ *   drag interaction with a fixed start width.
+ * - Do not wire `onPointerDown` to a full cell — only the narrow resize
+ *   handle element. Attaching it to the whole header cell will intercept
+ *   sort clicks and other cell interactions.
+ * - Do not rely on `setPointerCapture` being functional in all
+ *   environments (it is best-effort / no-op in jsdom). The hook falls
+ *   back to window-level listeners for cross-browser reliability.
+ */
+export function useResizeHandle(options: UseResizeHandleOptions): ResizeHandleApi {
+  const { minWidth, maxWidth, onResize } = options;
+  const [isResizing, setIsResizing] = useState(false);
+
+  // Held in refs so handlers attached to window don't go stale.
+  const startXRef = useRef(0);
+  const startWidthRef = useRef(0);
+  const onResizeRef = useRef(onResize);
+  onResizeRef.current = onResize;
+  const minRef = useRef(minWidth);
+  minRef.current = minWidth;
+  const maxRef = useRef(maxWidth);
+  maxRef.current = maxWidth;
+
+  const onPointerDown = useCallback(
+    (e: ReactPointerEvent<HTMLElement>) => {
+      e.stopPropagation?.();
+      startXRef.current = e.clientX;
+      startWidthRef.current = options.initialWidth;
+      try {
+        e.currentTarget.setPointerCapture(e.pointerId);
+      } catch {
+        // No-op for older browsers / jsdom.
+      }
+      setIsResizing(true);
+    },
+    [options.initialWidth],
+  );
+
+  useEffect(() => {
+    if (!isResizing) return;
+
+    function clamp(n: number) {
+      const min = minRef.current;
+      const max = maxRef.current;
+      let v = Math.max(min, n);
+      if (max != null) v = Math.min(max, v);
+      return v;
+    }
+
+    function onMove(e: PointerEvent) {
+      const delta = e.clientX - startXRef.current;
+      const next = clamp(startWidthRef.current + delta);
+      onResizeRef.current(next);
+    }
+    function onEnd() {
+      setIsResizing(false);
+    }
+
+    window.addEventListener('pointermove', onMove);
+    window.addEventListener('pointerup', onEnd);
+    window.addEventListener('pointercancel', onEnd);
+    return () => {
+      window.removeEventListener('pointermove', onMove);
+      window.removeEventListener('pointerup', onEnd);
+      window.removeEventListener('pointercancel', onEnd);
+    };
+  }, [isResizing]);
+
+  return { isResizing, onPointerDown };
+}