@exxatdesignux/ui 0.2.19 → 0.4.0

package/src/components/data-table/use-table-state.ts

@@ -0,0 +1,767 @@
+"use client"
+
+// ─────────────────────────────────────────────────────────────────────────────
+// useTableState — all non-display state shared by DataTable and DataTablePaginated
+// ─────────────────────────────────────────────────────────────────────────────
+
+import * as React from "react"
+import type { RowHeight } from "../../lib/row-height"
+import type { ColumnDef, SortDir } from "./types"
+import type { ActiveFilter, FilterOperator, SortRule } from "../../lib/table-properties-types"
+import { parseRowDateToYmd } from "../../lib/date-filter"
+
+let _filterId = 0
+function nextFilterId() { return `f-${++_filterId}` }
+
+/**
+ * “Reflow” / high-zoom short viewport. At 200% zoom a 1080p monitor’s CSS
+ * height is ≈ 540px — `500px` was too low and never disabled pins. 640px
+ * catches typical 200% cases and small laptop tops without breaking `500px` flows.
+ * Column stickies + edge shadows harm reflow (WCAG 1.4.10).
+ */
+const REFLOW_VIEWPORT_MQ = "(max-height: 640px)"
+
+function subscribeReflowViewport(callback: () => void) {
+  if (typeof window === "undefined") return () => {}
+  const mql = window.matchMedia(REFLOW_VIEWPORT_MQ)
+  mql.addEventListener("change", callback)
+  return () => mql.removeEventListener("change", callback)
+}
+function getReflowViewportSnapshot() {
+  if (typeof window === "undefined") return false
+  return window.matchMedia(REFLOW_VIEWPORT_MQ).matches
+}
+function getServerReflowViewportSnapshot() {
+  return false
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Helpers
+// ─────────────────────────────────────────────────────────────────────────────
+
+function digitsOnly(s: string): string {
+  return s.replace(/\D/g, "")
+}
+
+/** Build the default widths map from column defs */
+function buildDefaultWidths<TData>(columns: ColumnDef<TData>[]): Record<string, number> {
+  const map: Record<string, number> = {}
+  for (const col of columns) {
+    if (col.width !== undefined) map[col.key] = col.width
+  }
+  return map
+}
+
+/** Build the initial pin state from column defs */
+function buildDefaultPins<TData>(columns: ColumnDef<TData>[]): Record<string, "left" | "right"> {
+  const map: Record<string, "left" | "right"> = {}
+  for (const col of columns) {
+    if (col.defaultPin) map[col.key] = col.defaultPin
+  }
+  return map
+}
+
+function compareUnknownSort(a: unknown, b: unknown): number {
+  if (a === b) return 0
+  if (a == null && b == null) return 0
+  if (a == null) return 1
+  if (b == null) return -1
+  if (typeof a === "number" && typeof b === "number") return a < b ? -1 : a > b ? 1 : 0
+  if (typeof a === "string" && typeof b === "string") return a < b ? -1 : a > b ? 1 : 0
+  const as = String(a)
+  const bs = String(b)
+  return as < bs ? -1 : as > bs ? 1 : 0
+}
+
+/** Build the locked-pin set (columns that can never be unpinned) */
+function buildLockedPins<TData>(columns: ColumnDef<TData>[]): Record<string, "left" | "right"> {
+  const map: Record<string, "left" | "right"> = {}
+  for (const col of columns) {
+    if (col.lockPin && col.defaultPin) map[col.key] = col.defaultPin
+  }
+  return map
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Hook
+// ─────────────────────────────────────────────────────────────────────────────
+
+export function useTableState<TData extends Record<string, unknown>>(
+  data: TData[],
+  columns: ColumnDef<TData>[],
+  defaultSort?: { key: string; dir: SortDir },
+  paginationOverride?: { page: number; pageSize: number },
+  /**
+   * When defined (including `""`), toolbar search is synced from the URL (`?q=`).
+   * Use `searchParams.get("q") ?? ""` on library list routes; omit for other hubs.
+   */
+  syncedSearchFromUrl?: string,
+) {
+  // ── Sort ──────────────────────────────────────────────────────────────────
+  const [sortRules, setSortRules] = React.useState<SortRule[]>(() => {
+    if (defaultSort) {
+      return [{ id: "sort-default", fieldKey: defaultSort.key, direction: defaultSort.dir }]
+    }
+    return []
+  })
+
+  const primarySort = sortRules[0] ?? null
+  const sortKey: string = primarySort?.fieldKey ?? ""
+  const sortDir: SortDir = primarySort?.direction ?? "asc"
+
+  const addSortRule = React.useCallback((fieldKey: string) => {
+    setSortRules(prev => {
+      if (prev.some(r => r.fieldKey === fieldKey)) return prev
+      // New drawer sorts are primary (same as column-header sort), not trailing.
+      return [{ id: `sort-${Date.now()}`, fieldKey, direction: "asc" }, ...prev]
+    })
+  }, [setSortRules])
+
+  const removeSortRule = React.useCallback((id: string) => {
+    setSortRules(prev => prev.filter(r => r.id !== id))
+  }, [setSortRules])
+
+  const toggleSortDir = React.useCallback((id: string) => {
+    setSortRules(prev => prev.map(r =>
+      r.id === id ? { ...r, direction: r.direction === "asc" ? "desc" : "asc" } : r
+    ))
+  }, [setSortRules])
+
+  const handleSortByKey = React.useCallback((colKey: string) => {
+    setSortRules(prev => {
+      const idx = prev.findIndex(r => r.fieldKey === colKey)
+      if (idx === 0) {
+        return prev.map((r, i) => i === 0 ? { ...r, direction: r.direction === "asc" ? "desc" : "asc" } : r)
+      }
+      const filtered = prev.filter(r => r.fieldKey !== colKey)
+      return [{ id: `sort-${Date.now()}`, fieldKey: colKey, direction: "asc" }, ...filtered]
+    })
+  }, [setSortRules])
+
+  // ── Filters ───────────────────────────────────────────────────────────────
+  const [search, setSearch] = React.useState(() =>
+    syncedSearchFromUrl !== undefined ? syncedSearchFromUrl.trim() : "",
+  )
+  const [searchOpen, setSearchOpen] = React.useState(() =>
+    syncedSearchFromUrl !== undefined && Boolean(syncedSearchFromUrl.trim()),
+  )
+  const searchRef = React.useRef<HTMLInputElement>(null)
+  const [activeFilters, setActiveFilters] = React.useState<ActiveFilter[]>([])
+  const [filterConnectors, setFilterConnectors] = React.useState<Record<string, "and" | "or">>({})
+  const [openFilterId, setOpenFilterId] = React.useState<string | null>(null)
+  const [filterBarVisible, setFilterBarVisible] = React.useState(true)
+  const [drawerExpandedFilters, setDrawerExpandedFilters] = React.useState<Set<string>>(new Set())
+
+  React.useEffect(() => {
+    if (syncedSearchFromUrl === undefined) return
+    const next = syncedSearchFromUrl.trim()
+    setSearch(next)
+    setSearchOpen(next.length > 0)
+  }, [syncedSearchFromUrl])
+
+  const toggleConnector = React.useCallback((leftId: string) => {
+    setFilterConnectors(prev => ({ ...prev, [leftId]: prev[leftId] === "or" ? "and" : "or" }))
+  }, [setFilterConnectors])
+
+  function getConnector(leftId: string): "and" | "or" {
+    return filterConnectors[leftId] ?? "and"
+  }
+
+  const addFilter = React.useCallback((fieldKey: string, fromDrawer = false) => {
+    const col = columns.find(c => c.key === fieldKey)
+    if (!col?.filter) return
+    const id = nextFilterId()
+    const f = col.filter
+    const firstOperator: FilterOperator = (() => {
+      if (f.type === "select" || f.type === "date") {
+        const pick = f.operators?.find(o => o === "is" || o === "is_not")
+        return pick ?? "is"
+      }
+      return f.operators?.[0] ?? "contains"
+    })()
+    const newFilter: ActiveFilter = { id, fieldKey, operator: firstOperator, values: [] }
+    setActiveFilters(prev => [...prev, newFilter])
+    if (fromDrawer) {
+      setDrawerExpandedFilters(() => new Set([id]))
+      // Keep toolbar pills hidden until a value is chosen — avoids mounting every
+      // FilterPill (heavy) on each drawer "Add filter" click.
+    } else {
+      setOpenFilterId(id)
+      setFilterBarVisible(true)
+    }
+  }, [columns, setActiveFilters, setDrawerExpandedFilters, setOpenFilterId, setFilterBarVisible])
+
+  const updateFilter = React.useCallback((id: string, patch: Partial<ActiveFilter>) => {
+    let shouldShowFilterBar = false
+    setActiveFilters(prev => {
+      const next = prev.map(f => {
+        if (f.id !== id) return f
+        const merged = { ...f, ...patch }
+        const col = columns.find(c => c.key === merged.fieldKey)
+        if (merged.values.length > 0) {
+          shouldShowFilterBar =
+            col?.filter?.type === "text"
+              ? (merged.values[0] ?? "").trim().length > 0
+              : true
+        }
+        return merged
+      })
+      return next
+    })
+    if (shouldShowFilterBar) setFilterBarVisible(true)
+  }, [columns, setActiveFilters, setFilterBarVisible])
+
+  const removeFilter = React.useCallback((id: string) => {
+    // Use functional updates only — no stale-closure risk on activeFilters.
+    setActiveFilters(prev => {
+      const idx = prev.findIndex(f => f.id === id)
+      const next = prev.filter(f => f.id !== id)
+      setFilterConnectors(prevC => {
+        const c = { ...prevC }
+        if (idx > 0 && next.length > 0) {
+          const leftId = prev[idx - 1].id
+          c[leftId] = prevC[id] ?? prevC[leftId] ?? "and"
+        }
+        delete c[id]
+        return c
+      })
+      return next
+    })
+    setOpenFilterId(prev => prev === id ? null : prev)
+  }, [setActiveFilters, setFilterConnectors, setOpenFilterId])
+
+  // ── Group by ──────────────────────────────────────────────────────────────
+  const [groupBy, setGroupBy] = React.useState<string | null>(null)
+
+  // ── Per-column quick-search ───────────────────────────────────────────────
+  const [colMenuSearch, setColMenuSearch] = React.useState<Record<string, string>>({})
+
+  // ── Selection ─────────────────────────────────────────────────────────────
+  const [selected, setSelected] = React.useState<Set<string | number>>(new Set())
+
+  // ── Column widths ─────────────────────────────────────────────────────────
+  const [colWidths, setColWidths] = React.useState<Record<string, number>>(() => buildDefaultWidths(columns))
+  const resizeRef = React.useRef<{ key: string; startX: number; startW: number } | null>(null)
+
+  // ── Column order ──────────────────────────────────────────────────────────
+  const [colOrder, setColOrder] = React.useState<string[]>(() => columns.map(c => c.key))
+
+  // ── Column pins ───────────────────────────────────────────────────────────
+  const [colPins, setColPins] = React.useState<Record<string, "left" | "right">>(() => buildDefaultPins(columns))
+  const lockedPins = React.useMemo(() => buildLockedPins(columns), [columns])
+
+  // ── Column wrap ───────────────────────────────────────────────────────────
+  const [colWrap, setColWrap] = React.useState<Record<string, boolean>>({})
+
+  // ── Drawer / display settings ─────────────────────────────────────────────
+  const [sheetOpen, setSheetOpen] = React.useState(false)
+  /**
+   * Deep-link target for the Properties drawer. When a callsite wants to open
+   * the drawer focused on a specific panel (e.g. "conditional-rules" from the
+   * column header menu), it sets this before calling `setSheetOpen(true)`. The
+   * drawer's `initialPanel` prop reads it and syncs its internal `sheetPanel`
+   * accordingly. The toolbar Properties button clears it so it opens to "main".
+   */
+  const [sheetInitialPanel, setSheetInitialPanel] = React.useState<string | null>(null)
+  const [showGridlines, setShowGridlines] = React.useState(true)
+  const [rowHeight, setRowHeight] = React.useState<RowHeight>("default")
+  const [hiddenCols, setHiddenCols] = React.useState<Set<string>>(new Set())
+
+  const toggleColVisibility = React.useCallback((key: string) => {
+    setHiddenCols(prev => {
+      const next = new Set(prev)
+      if (next.has(key)) next.delete(key)
+      else next.add(key)
+      return next
+    })
+  }, [setHiddenCols])
+
+  const moveCol = React.useCallback((key: string, dir: "up" | "down") => {
+    setColOrder(prev => {
+      const lockedLeft = columns.filter(c => c.lockPin && c.defaultPin === "left").map(c => c.key)
+      const lockedRight = columns.filter(c => c.lockPin && c.defaultPin === "right").map(c => c.key)
+      const orderable = prev.filter(k => !lockedLeft.includes(k) && !lockedRight.includes(k))
+      const idx = orderable.indexOf(key)
+      if (dir === "up" && idx <= 0) return prev
+      if (dir === "down" && idx >= orderable.length - 1) return prev
+      const next = [...orderable]
+      const swap = dir === "up" ? idx - 1 : idx + 1
+      ;[next[idx], next[swap]] = [next[swap], next[idx]]
+      return [...lockedLeft, ...next, ...lockedRight]
+    })
+  }, [columns, setColOrder])
+
+  // ── Drag-to-reorder ───────────────────────────────────────────────────────
+  const draggedKey = React.useRef<string | null>(null)
+  const [dragOverKey, setDragOverKey] = React.useState<string | null>(null)
+
+  // ── Scroll / overflow ─────────────────────────────────────────────────────
+  const scrollRef = React.useRef<HTMLDivElement>(null)
+  const [scrolled, setScrolled] = React.useState(false)
+  const [scrollEnd, setScrollEnd] = React.useState(false)
+  const [isOverflowing, setIsOverflowing] = React.useState(false)
+
+  const isReflowViewport = React.useSyncExternalStore(
+    subscribeReflowViewport,
+    getReflowViewportSnapshot,
+    getServerReflowViewportSnapshot,
+  )
+
+  // ── Hovered row ───────────────────────────────────────────────────────────
+  const [hoveredRow, setHoveredRow] = React.useState<string | number | null>(null)
+
+  // ── Column lookup index (stable per `columns` reference) ─────────────────
+  // The previous implementation called `columns.find(c => c.key === ...)` inside
+  // every filter/sort comparator and every sticky-offset getter — for large
+  // datasets that's O(rows × cols) per render. Map lookups make those O(1).
+  const columnsByKey = React.useMemo(() => {
+    const map = new Map<string, ColumnDef<TData>>()
+    for (const col of columns) map.set(col.key, col)
+    return map
+  }, [columns])
+
+  // Searchable text cache. Per row, concatenate every value into one
+  // lower-cased blob ONCE and reuse it across keystrokes. Keyed by row
+  // identity via WeakMap so it never holds onto rows the consumer dropped.
+  const searchableTextCache = React.useRef<WeakMap<object, string>>(new WeakMap())
+  const getSearchableText = React.useCallback((row: TData): string => {
+    const cache = searchableTextCache.current
+    const cached = cache.get(row)
+    if (cached !== undefined) return cached
+    let blob = ""
+    for (const v of Object.values(row)) {
+      if (v == null) continue
+      blob += String(v).toLowerCase() + "\n"
+    }
+    cache.set(row, blob)
+    return blob
+  }, [])
+
+  // Per-row per-column lower-cased value cache (column quick-search +
+  // text-mask filters). One `Map` per row, lazily filled on first lookup.
+  const lowerValueCache = React.useRef<WeakMap<object, Map<string, string>>>(new WeakMap())
+  const getLowerValue = React.useCallback((row: TData, key: string): string => {
+    const wm = lowerValueCache.current
+    let perRow = wm.get(row)
+    if (!perRow) {
+      perRow = new Map()
+      wm.set(row, perRow)
+    }
+    const cached = perRow.get(key)
+    if (cached !== undefined) return cached
+    const computed = String(row[key] ?? "").toLowerCase()
+    perRow.set(key, computed)
+    return computed
+  }, [])
+
+  // Reset the row-keyed caches whenever the dataset reference changes so we
+  // don't pin stale strings for rows the consumer just replaced.
+  React.useEffect(() => {
+    searchableTextCache.current = new WeakMap()
+    lowerValueCache.current = new WeakMap()
+  }, [data])
+
+  // ── Derived: filtered + sorted rows ──────────────────────────────────────
+  const rows = React.useMemo(() => {
+    let result = data.slice()
+
+    const q = search.trim().toLowerCase()
+    if (q) {
+      result = result.filter(r => getSearchableText(r).includes(q))
+    }
+
+    const activeWithValues = activeFilters.filter(f => {
+      if (f.values.length === 0) return false
+      const col = columnsByKey.get(f.fieldKey)
+      if (col?.filter?.type === "text") {
+        return (f.values[0] ?? "").trim().length > 0
+      }
+      return true
+    })
+    if (activeWithValues.length > 0) {
+      // Pre-resolve column, operator, normalised needle, and select-value Set
+      // for each active filter ONCE (instead of per row).
+      type CompiledFilter = {
+        col: ColumnDef<TData>
+        id: string
+        type: "select" | "date" | "text"
+        operator: ActiveFilter["operator"]
+        selectValues?: Set<string>
+        dateTarget?: string
+        textNeedle?: string
+        digitsNeedle?: string
+        isDigitsMask?: boolean
+      }
+      const compiled: CompiledFilter[] = []
+      for (const f of activeWithValues) {
+        const col = columnsByKey.get(f.fieldKey)
+        if (!col?.filter) continue
+        if (col.filter.type === "select") {
+          compiled.push({
+            col,
+            id: f.id,
+            type: "select",
+            operator: f.operator,
+            selectValues: new Set(f.values),
+          })
+        } else if (col.filter.type === "date") {
+          compiled.push({
+            col,
+            id: f.id,
+            type: "date",
+            operator: f.operator,
+            dateTarget: f.values[0],
+          })
+        } else {
+          const raw = f.values[0] ?? ""
+          const isDigitsMask = col.filter.textMask === "phone" || col.filter.textMask === "zip"
+          compiled.push({
+            col,
+            id: f.id,
+            type: "text",
+            operator: f.operator,
+            isDigitsMask,
+            digitsNeedle: isDigitsMask ? digitsOnly(raw) : undefined,
+            textNeedle: !isDigitsMask ? raw.toLowerCase() : undefined,
+          })
+        }
+      }
+
+      const matchesCompiled = (r: TData, f: CompiledFilter): boolean => {
+        const rowVal = String(r[f.col.key] ?? "")
+        if (f.type === "select") {
+          const hit = f.selectValues!.has(rowVal)
+          return f.operator === "is" ? hit : !hit
+        }
+        if (f.type === "date") {
+          if (!f.dateTarget) return true
+          const rowYmd = parseRowDateToYmd(rowVal)
+          const op = f.operator === "is_not" ? "is_not" : "is"
+          if (rowYmd === null) return op === "is_not"
+          return op === "is" ? rowYmd === f.dateTarget : rowYmd !== f.dateTarget
+        }
+        if (f.isDigitsMask) {
+          if (!f.digitsNeedle) return true
+          const hay = digitsOnly(rowVal)
+          return f.operator === "contains" ? hay.includes(f.digitsNeedle) : !hay.includes(f.digitsNeedle)
+        }
+        if (!f.textNeedle) return true
+        const hay = getLowerValue(r, f.col.key)
+        return f.operator === "contains" ? hay.includes(f.textNeedle) : !hay.includes(f.textNeedle)
+      }
+
+      if (compiled.length > 0) {
+        result = result.filter(r => {
+          let res = matchesCompiled(r, compiled[0])
+          for (let i = 1; i < compiled.length; i++) {
+            const connector = filterConnectors[compiled[i - 1].id] ?? "and"
+            const match = matchesCompiled(r, compiled[i])
+            res = connector === "and" ? res && match : res || match
+          }
+          return res
+        })
+      }
+    }
+
+    // Column menu quick-search — pre-normalise needles outside the row loop.
+    const colMenuEntries: { key: string; lower: string }[] = []
+    for (const [key, raw] of Object.entries(colMenuSearch)) {
+      const trimmed = raw.trim()
+      if (trimmed) colMenuEntries.push({ key, lower: trimmed.toLowerCase() })
+    }
+    if (colMenuEntries.length > 0) {
+      result = result.filter(r => {
+        for (const { key, lower } of colMenuEntries) {
+          if (!getLowerValue(r, key).includes(lower)) return false
+        }
+        return true
+      })
+    }
+
+    // Sort — resolve each rule's sort key ONCE, then run the comparator over
+    // an indexed list so the inner loop is a tight array walk, not a chain of
+    // `columns.find` lookups per comparison.
+    if (sortRules.length > 0) {
+      const resolved: { sk: string; dir: SortDir }[] = []
+      for (const rule of sortRules) {
+        const col = columnsByKey.get(rule.fieldKey)
+        const sk = col?.sortKey ?? col?.key
+        if (sk) resolved.push({ sk: sk as string, dir: rule.direction })
+      }
+      if (resolved.length > 0) {
+        result.sort((a, b) => {
+          for (let i = 0; i < resolved.length; i++) {
+            const { sk, dir } = resolved[i]
+            const cmp = compareUnknownSort(a[sk], b[sk])
+            if (cmp !== 0) return dir === "asc" ? cmp : -cmp
+          }
+          return 0
+        })
+      }
+    }
+
+    return result
+  }, [
+    data,
+    search,
+    activeFilters,
+    filterConnectors,
+    colMenuSearch,
+    sortRules,
+    columnsByKey,
+    getSearchableText,
+    getLowerValue,
+  ])
+
+  // ── Paged rows (slice of rows when pagination is active) ─────────────────
+  const pagedRows = React.useMemo(() => {
+    if (!paginationOverride || paginationOverride.pageSize <= 0) return rows
+    const { page, pageSize } = paginationOverride
+    const safePage = Math.max(1, page)
+    return rows.slice((safePage - 1) * pageSize, safePage * pageSize)
+  // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [rows, paginationOverride?.page, paginationOverride?.pageSize])
+
+  // ── Grouped rows ──────────────────────────────────────────────────────────
+  const groupedRows = React.useMemo(() => {
+    if (!groupBy) return [{ groupKey: null as string | null, groupLabel: null as string | null, rows }]
+    const groups = new Map<string, TData[]>()
+    rows.forEach(row => {
+      const val = String(row[groupBy] ?? "—")
+      if (!groups.has(val)) groups.set(val, [])
+      groups.get(val)!.push(row)
+    })
+    return [...groups.entries()]
+      .sort(([a], [b]) => a.localeCompare(b))
+      .map(([key, groupRows]) => ({ groupKey: key, groupLabel: key, rows: groupRows }))
+  }, [rows, groupBy])
+
+  // ── Effective pins (respect overflow) ─────────────────────────────────────
+  const LOCKED_KEYS = React.useMemo(() => new Set(Object.keys(lockedPins)), [lockedPins])
+
+  // When the table fits within its container (not overflowing) there is no need
+  // to sticky-pin any column — even locked ones.  Pins only activate once the
+  // user has to scroll horizontally so the selection / action edges stay visible.
+  // In reflow viewports (high zoom), disable all column stickies — shadow + sticky
+  // fight the short viewport and overlap content.
+  const effectivePins = React.useMemo(() => {
+    if (isReflowViewport || !isOverflowing) return {}
+    const result: Record<string, "left" | "right"> = {}
+    for (const [key, pin] of Object.entries(colPins)) {
+      result[key] = pin
+    }
+    return result
+  }, [colPins, isOverflowing, isReflowViewport])
+
+  // ── Display columns ───────────────────────────────────────────────────────
+  const displayCols = React.useMemo(() => {
+    const leftPinned: string[] = []
+    const free: string[] = []
+    const rightPinned: string[] = []
+    for (const k of colOrder) {
+      const pin = colPins[k]
+      if (pin === "left") leftPinned.push(k)
+      else if (pin === "right") rightPinned.push(k)
+      else free.push(k)
+    }
+    const ordered = [...leftPinned, ...free, ...rightPinned]
+    const out: ColumnDef<TData>[] = []
+    for (const k of ordered) {
+      if (hiddenCols.has(k)) continue
+      const col = columnsByKey.get(k)
+      if (col) out.push(col)
+    }
+    return out
+  }, [colOrder, colPins, hiddenCols, columnsByKey])
+
+  // ── Column actions ────────────────────────────────────────────────────────
+  function startResize(key: string, e: React.MouseEvent) {
+    e.preventDefault()
+    e.stopPropagation()
+    const minW = columns.find(c => c.key === key)?.minWidth ?? 60
+    const startW = colWidths[key] ?? (columns.find(c => c.key === key)?.width ?? 100)
+    resizeRef.current = { key, startX: e.clientX, startW }
+    const onMove = (ev: MouseEvent) => {
+      if (!resizeRef.current) return
+      const { key: k, startX, startW: sw } = resizeRef.current
+      setColWidths(p => ({ ...p, [k]: Math.max(minW, sw + ev.clientX - startX) }))
+    }
+    const onUp = () => {
+      resizeRef.current = null
+      document.removeEventListener("mousemove", onMove)
+      document.removeEventListener("mouseup", onUp)
+    }
+    document.addEventListener("mousemove", onMove)
+    document.addEventListener("mouseup", onUp)
+  }
+
+  function handleDragStart(key: string, e: React.DragEvent<HTMLTableCellElement>) {
+    draggedKey.current = key
+    e.dataTransfer.effectAllowed = "move"
+  }
+  function handleDragOver(key: string, e: React.DragEvent<HTMLTableCellElement>) {
+    e.preventDefault()
+    e.dataTransfer.dropEffect = "move"
+    if (draggedKey.current && draggedKey.current !== key) setDragOverKey(key)
+  }
+  function handleDrop(key: string) {
+    if (!draggedKey.current || draggedKey.current === key) { setDragOverKey(null); return }
+    const order = [...colOrder]
+    const from  = order.indexOf(draggedKey.current)
+    const to    = order.indexOf(key)
+    order.splice(from, 1)
+    order.splice(to, 0, draggedKey.current!)
+    setColOrder(order)
+    draggedKey.current = null
+    setDragOverKey(null)
+  }
+  function handleDragEnd() { draggedKey.current = null; setDragOverKey(null) }
+
+  function pinColumn(key: string, pin: "left" | "right") {
+    setColPins(p => ({ ...p, [key]: pin }))
+  }
+  function unpinColumn(key: string) {
+    if (lockedPins[key]) return
+    setColPins(p => { const n = { ...p }; delete n[key]; return n })
+  }
+  function toggleWrap(key: string) {
+    setColWrap(p => ({ ...p, [key]: !p[key] }))
+  }
+
+  // ── Scroll handlers ───────────────────────────────────────────────────────
+  function checkOverflow() {
+    const el = scrollRef.current
+    if (!el) return
+    setIsOverflowing(el.scrollWidth > el.clientWidth + 1)
+  }
+  function handleScroll() {
+    const el = scrollRef.current
+    if (!el) return
+    setScrolled(el.scrollLeft > 1)
+    setScrollEnd(el.scrollLeft >= el.scrollWidth - el.clientWidth - 1)
+    setIsOverflowing(el.scrollWidth > el.clientWidth + 1)
+  }
+
+  // ── Selection helpers ─────────────────────────────────────────────────────
+  function getRowId(row: TData, index: number, getIdFn?: (r: TData, i: number) => string | number): string | number {
+    return getIdFn ? getIdFn(row, index) : (row.id as string | number ?? index)
+  }
+
+  const toggleRow = React.useCallback((id: string | number) => {
+    setSelected(prev => {
+      const next = new Set(prev)
+      if (next.has(id)) next.delete(id)
+      else next.add(id)
+      return next
+    })
+  }, [setSelected])
+
+  const toggleAll = React.useCallback((allRowIds: (string | number)[]) => {
+    setSelected(prev => prev.size === allRowIds.length ? new Set() : new Set(allRowIds))
+  }, [setSelected])
+
+  // ── Sticky offset calculations ────────────────────────────────────────────
+  // Precompute every pinned column's offset ONCE per render so the per-cell
+  // `stickyStyle()` call is an O(1) map lookup instead of an O(cols) walk.
+  // With `cells = rows × cols`, the previous O(rows × cols²) became the
+  // dominant cost on wide tables.
+  const stickyOffsets = React.useMemo(() => {
+    const left = new Map<string, number>()
+    const right = new Map<string, number>()
+    let leftOffset = 0
+    for (const col of displayCols) {
+      if (effectivePins[col.key] !== "left") break
+      left.set(col.key, leftOffset)
+      leftOffset += colWidths[col.key] ?? col.width ?? 100
+    }
+    let rightOffset = 0
+    for (let i = displayCols.length - 1; i >= 0; i--) {
+      const col = displayCols[i]
+      if (effectivePins[col.key] !== "right") break
+      right.set(col.key, rightOffset)
+      rightOffset += colWidths[col.key] ?? col.width ?? 100
+    }
+    return { left, right }
+  }, [displayCols, effectivePins, colWidths])
+
+  const getStickyLeft = React.useCallback((key: string): number => {
+    return stickyOffsets.left.get(key) ?? 0
+  }, [stickyOffsets])
+
+  const getStickyRight = React.useCallback((key: string): number => {
+    return stickyOffsets.right.get(key) ?? 0
+  }, [stickyOffsets])
+
+  const stickyStyle = React.useCallback(
+    (key: string, isHeader = false): React.CSSProperties => {
+      if (isReflowViewport) return {}
+      const pin = effectivePins[key]
+      if (pin === "left") {
+        return isHeader
+          ? { position: "sticky", left: stickyOffsets.left.get(key) ?? 0, top: 0 }
+          : { position: "sticky", left: stickyOffsets.left.get(key) ?? 0 }
+      }
+      if (pin === "right") {
+        return isHeader
+          ? { position: "sticky", right: stickyOffsets.right.get(key) ?? 0, top: 0 }
+          : { position: "sticky", right: stickyOffsets.right.get(key) ?? 0 }
+      }
+      return isHeader ? { position: "sticky", top: 0 } : {}
+    },
+    [effectivePins, isReflowViewport, stickyOffsets],
+  )
+
+  const totalWidth = React.useMemo(
+    () => displayCols.reduce((s, c) => s + (colWidths[c.key] ?? c.width ?? 100), 0),
+    [displayCols, colWidths],
+  )
+
+  return {
+    // Sort
+    sortRules, setSortRules,
+    sortKey, sortDir,
+    addSortRule, removeSortRule, toggleSortDir, handleSortByKey,
+    // Filters
+    search, setSearch,
+    searchOpen, setSearchOpen,
+    searchRef,
+    activeFilters, setActiveFilters,
+    filterConnectors, setFilterConnectors, toggleConnector, getConnector,
+    openFilterId, setOpenFilterId,
+    filterBarVisible, setFilterBarVisible,
+    drawerExpandedFilters, setDrawerExpandedFilters,
+    addFilter, updateFilter, removeFilter,
+    // Group
+    groupBy, setGroupBy,
+    // Column quick-search
+    colMenuSearch, setColMenuSearch,
+    // Selection
+    selected, setSelected, toggleRow, toggleAll, getRowId,
+    // Column widths / order / pins / wrap
+    colWidths, setColWidths, resizeRef, startResize,
+    colOrder, setColOrder, moveCol,
+    colPins, setColPins, lockedPins, LOCKED_KEYS,
+    pinColumn, unpinColumn,
+    colWrap, setColWrap, toggleWrap,
+    // Drag-to-reorder
+    draggedKey, dragOverKey,
+    handleDragStart, handleDragOver, handleDrop, handleDragEnd,
+    // Scroll
+    scrollRef, scrolled, scrollEnd, isOverflowing,
+    checkOverflow, handleScroll,
+    // Hover
+    hoveredRow, setHoveredRow,
+    // Derived
+    rows, pagedRows, groupedRows,
+    effectivePins, displayCols,
+    isReflowViewport,
+    getStickyLeft, getStickyRight, stickyStyle,
+    totalWidth,
+    // Display settings
+    sheetOpen, setSheetOpen,
+    sheetInitialPanel, setSheetInitialPanel,
+    showGridlines, setShowGridlines,
+    rowHeight, setRowHeight,
+    hiddenCols, setHiddenCols, toggleColVisibility,
+  }
+}