"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 } from "../../lib/table-properties-types" import { filterSortRows } from "./filter-sort-rows" import { useSortRules } from "./use-sort-rules" import { useFilterState } from "./use-filter-state" import { buildFilterFieldContextMap } from "../../lib/column-filter-context" import { getReflowViewportSnapshot, getServerReflowViewportSnapshot, subscribeReflowViewport, } from "../../lib/reflow-viewport" import { useIsMobile } from "../../hooks/use-mobile" import { columnPinPolicyFromDefs, mergeColOrderWithPinPolicy, reconcileColumnPins, } from "../../lib/column-pin-policy" /** * Below this scrollport width, sticky left/right pins crush the middle columns, * so pins go inert (see `stickyPinsDisabled`). Matches the `md` breakpoint. */ const STICKY_PIN_MIN_SCROLLPORT = 768 // ───────────────────────────────────────────────────────────────────────────── // Helpers // ───────────────────────────────────────────────────────────────────────────── /** Build the default widths map from column defs */ function buildDefaultWidths(columns: ColumnDef[]): Record { const map: Record = {} 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(columns: ColumnDef[]): Record { const map: Record = {} for (const col of columns) { if (col.defaultPin) map[col.key] = col.defaultPin } return map } /** Build the locked-pin set (columns that can never be unpinned) */ function buildLockedPins(columns: ColumnDef[]): Record { const map: Record = {} for (const col of columns) { if (col.lockPin && col.defaultPin) map[col.key] = col.defaultPin } return map } /** Row identity: the caller's `getId`, else the row's own `id`, else its index. */ 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) } // ───────────────────────────────────────────────────────────────────────────── // Hook // ───────────────────────────────────────────────────────────────────────────── /** * Group key for one cell value. Avatar-group / multi-value cells hold arrays of * objects, which `String()` flattens to "[object Object]" — read each item's * display field instead. */ function groupValueLabel(value: unknown): string { if (value == null || value === "") return "—" if (Array.isArray(value)) { const parts = value.map(groupValueLabel).filter(v => v !== "—") return parts.length ? parts.join(", ") : "—" } if (typeof value === "object") { const o = value as Record for (const k of ["name", "label", "displayName", "title", "email", "id", "value"]) { if (typeof o[k] === "string" && o[k]) return o[k] as string } return "—" } return String(value) } export function useTableState>( data: TData[], columns: ColumnDef[], 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, ) { const { sortRules, setSortRules, sortKey, sortDir, addSortRule, removeSortRule, toggleSortDir, handleSortByKey } = useSortRules(defaultSort) const { search, setSearch, searchOpen, setSearchOpen, searchRef, activeFilters, setActiveFilters, filterConnectors, setFilterConnectors, openFilterId, setOpenFilterId, filterBarVisible, setFilterBarVisible, drawerExpandedFilters, setDrawerExpandedFilters, toggleConnector, getConnector, filterColumns, buildEmptyFilter, addFilter, updateFilter, removeFilter } = useFilterState(columns, syncedSearchFromUrl) // ── Group by ────────────────────────────────────────────────────────────── const [groupBy, setGroupBy] = React.useState(null) // ── Per-column quick-search ─────────────────────────────────────────────── const [colMenuSearch, setColMenuSearch] = React.useState>({}) // ── Selection ───────────────────────────────────────────────────────────── const [selected, setSelected] = React.useState>(new Set()) // ── Column widths ───────────────────────────────────────────────────────── const [colWidths, setColWidths] = React.useState>(() => buildDefaultWidths(columns)) const resizeRef = React.useRef<{ key: string startX: number startW: number liveW?: number } | null>(null) // ── Column order ────────────────────────────────────────────────────────── const [colOrder, setColOrder] = React.useState(() => columns.map(c => c.key)) // ── Column pins ─────────────────────────────────────────────────────────── const [colPins, setColPins] = React.useState>(() => buildDefaultPins(columns)) const lockedPins = React.useMemo(() => buildLockedPins(columns), [columns]) const columnPinPolicy = React.useMemo(() => columnPinPolicyFromDefs(columns), [columns]) const columnKeysForOrder = React.useMemo(() => new Set(columns.map(c => c.key)), [columns]) React.useLayoutEffect(() => { setColPins(prev => { const next = reconcileColumnPins(prev, columnPinPolicy) return Object.keys(next).length === Object.keys(prev).length && Object.entries(next).every(([k, v]) => prev[k] === v) ? prev : next }) setColOrder(prev => { const next = mergeColOrderWithPinPolicy(prev, columnKeysForOrder, columnPinPolicy) return next.length === prev.length && next.every((k, i) => k === prev[i]) ? prev : next }) }, [columnPinPolicy, columnKeysForOrder]) // ── Column wrap ─────────────────────────────────────────────────────────── const [colWrap, setColWrap] = React.useState>({}) // ── 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(null) /** * Toolbar filter icon (mobile / high zoom) — opens Properties on the Filter panel. */ const openFilterPanelInDrawer = React.useCallback(() => { setSheetInitialPanel("filter") setSheetOpen(true) }, [setSheetInitialPanel, setSheetOpen]) /** * Column header **Filter by this column** — opens Properties on the Filter * panel with the target field expanded. Used instead of toolbar FilterPill * popovers so sticky floating headers stay keyboard-accessible when the * filter bar is off-screen. */ const openColumnFilterInDrawer = React.useCallback((fieldKey: string) => { // Do not rely on side effects inside `setActiveFilters` — React may defer // the updater, which left `sheetOpen` false and broke the Vitest contract. const existing = activeFilters.find(f => f.fieldKey === fieldKey) const filter = existing ?? buildEmptyFilter(fieldKey) if (!filter) return if (!existing) { setActiveFilters(prev => { if (prev.some(f => f.fieldKey === fieldKey)) return prev return [...prev, filter] }) } setDrawerExpandedFilters(() => new Set([filter.id])) setOpenFilterId(null) setSheetInitialPanel("filter") setSheetOpen(true) }, [ activeFilters, buildEmptyFilter, setActiveFilters, setDrawerExpandedFilters, setOpenFilterId, setSheetInitialPanel, setSheetOpen, ]) const [showGridlines, setShowGridlines] = React.useState(true) const [rowHeight, setRowHeight] = React.useState("default") const [hiddenCols, setHiddenCols] = React.useState>(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 locked = new Set([...lockedLeft, ...lockedRight]) const orderable = prev.filter(k => !locked.has(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(null) const [dragOverKey, setDragOverKey] = React.useState(null) // ── Scroll / overflow ───────────────────────────────────────────────────── const scrollRef = React.useRef(null) const [scrolled, setScrolled] = React.useState(false) const [scrollEnd, setScrollEnd] = React.useState(false) const [isOverflowing, setIsOverflowing] = React.useState(false) /** * Verdict, not the measurement. The scrollport width is only ever consumed as * the `STICKY_PIN_MIN_SCROLLPORT` threshold below, so storing raw pixels made * every frame of a rail or window resize a new state value and re-rendered the * whole grid to recompute one boolean that changes at most once per drag. */ const [scrollportNarrow, setScrollportNarrow] = React.useState(false) const isReflowViewport = React.useSyncExternalStore( subscribeReflowViewport, getReflowViewportSnapshot, getServerReflowViewportSnapshot, ) const isMobile = useIsMobile() // Phone / tablet (< md), a narrow table container, or WCAG reflow: sticky // L/R pins crush middle columns. Measure the table scrollport as well as the // window because secondary rails can leave a desktop viewport with a narrow // content canvas. const stickyPinsDisabled = isReflowViewport || isMobile || scrollportNarrow const filterFieldContext = React.useMemo( () => buildFilterFieldContextMap(data, filterColumns), [data, filterColumns], ) // ── 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>() for (const col of filterColumns) map.set(col.key, col) return map }, [filterColumns]) // 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. // Built on first lookup, not on first render: `useRef` has no lazy form, so // passing `new WeakMap()` would allocate one every render and drop it. const searchableTextCache = React.useRef | null>(null) const getSearchableText = React.useCallback((row: TData): string => { const cache = (searchableTextCache.current ??= new WeakMap()) 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 > | null>(null) const getLowerValue = React.useCallback((row: TData, key: string): string => { const wm = (lowerValueCache.current ??= new WeakMap()) 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 = null lowerValueCache.current = null }, [data]) // Keep the search input urgent; defer the rows pipeline so keystrokes stay // responsive on large hubs (vercel-react-best-practices: useDeferredValue). const deferredSearch = React.useDeferredValue(search) // ── Derived: filtered + sorted rows ────────────────────────────────────── const rows = React.useMemo( () => filterSortRows({ data, search: deferredSearch, activeFilters, filterConnectors, colMenuSearch, sortRules, columnsByKey, filterFieldContext, getSearchableText, getLowerValue, }), [ data, deferredSearch, activeFilters, filterConnectors, colMenuSearch, sortRules, columnsByKey, filterFieldContext, 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() rows.forEach(row => { const val = groupValueLabel(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]) // ── 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[] = [] for (const k of ordered) { if (hiddenCols.has(k)) continue const col = columnsByKey.get(k) if (col?.filterOnly) continue if (col) out.push(col) } return out }, [colOrder, colPins, hiddenCols, columnsByKey]) const totalWidth = React.useMemo( () => displayCols.reduce((s, c) => s + (colWidths[c.key] ?? c.width ?? 100), 0), [displayCols, colWidths], ) // ── 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. // Disable stickies on mobile / reflow — pinned Action + Course Name otherwise // overlap middle columns in a ~375px scrollport. const effectivePins = React.useMemo(() => { if (stickyPinsDisabled || !isOverflowing) return {} const result: Record = {} for (const [key, pin] of Object.entries(colPins)) { result[key] = pin } return result }, [colPins, isOverflowing, stickyPinsDisabled]) // ── 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, liveW: startW } const onMove = (ev: MouseEvent) => { if (!resizeRef.current) return const { key: k, startX, startW: sw } = resizeRef.current const next = Math.max(minW, sw + ev.clientX - startX) // Paint widths on the live elements during drag so the grid // tracks the pointer without a React commit per mousemove. const cols = document.querySelectorAll(`[data-dt-col="${CSS.escape(k)}"]`) for (const col of cols) col.style.width = `${next}px` resizeRef.current.liveW = next } const onUp = () => { const live = resizeRef.current?.liveW if (typeof live === "number") { setColWidths(p => ({ ...p, [key]: live })) } 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) { draggedKey.current = key e.dataTransfer.effectAllowed = "move" } function handleDragOver(key: string, e: React.DragEvent) { 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 ─────────────────────────────────────────────────────── const checkOverflow = React.useCallback(() => { const el = scrollRef.current if (!el) return // One read per call — every `clientWidth` access can flush pending layout. const width = el.clientWidth setScrollportNarrow(width < STICKY_PIN_MIN_SCROLLPORT) // Compare declared column width to scrollport — not scrollWidth, which matched // clientWidth when the table stretched with `w-full`. setIsOverflowing(totalWidth > width + 1) }, [totalWidth]) function handleScroll() { const el = scrollRef.current if (!el) return const width = el.clientWidth const nextScrolled = el.scrollLeft > 1 const nextScrollEnd = el.scrollLeft >= el.scrollWidth - width - 1 const nextNarrow = width < STICKY_PIN_MIN_SCROLLPORT const nextOverflowing = totalWidth > width + 1 setScrolled((prev) => (prev === nextScrolled ? prev : nextScrolled)) setScrollEnd((prev) => (prev === nextScrollEnd ? prev : nextScrollEnd)) setScrollportNarrow((prev) => (prev === nextNarrow ? prev : nextNarrow)) setIsOverflowing((prev) => (prev === nextOverflowing ? prev : nextOverflowing)) } React.useLayoutEffect(() => { checkOverflow() }, [checkOverflow]) // ── Selection helpers ───────────────────────────────────────────────────── 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]) /** * Select or clear a subset of rows without touching the rest of the * selection. `toggleAll` replaces the whole set, which is right for the header * checkbox and wrong for a group: picking one group must not drop the rows a * user already picked in another. */ const setRowsSelected = React.useCallback( (rowIds: (string | number)[], nextSelected: boolean) => { if (rowIds.length === 0) return setSelected(prev => { const next = new Set(prev) for (const id of rowIds) { if (nextSelected) next.add(id) else next.delete(id) } return next }) }, [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() const right = new Map() 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 (stickyPinsDisabled) 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, stickyPinsDisabled, stickyOffsets], ) 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, openColumnFilterInDrawer, // Group groupBy, setGroupBy, // Column quick-search colMenuSearch, setColMenuSearch, // Selection selected, setSelected, toggleRow, toggleAll, setRowsSelected, 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, // Derived rows, pagedRows, groupedRows, effectivePins, displayCols, isReflowViewport, stickyPinsDisabled, getStickyLeft, getStickyRight, stickyStyle, totalWidth, // Display settings sheetOpen, setSheetOpen, sheetInitialPanel, setSheetInitialPanel, openFilterPanelInDrawer, filterFieldContext, showGridlines, setShowGridlines, rowHeight, setRowHeight, hiddenCols, setHiddenCols, toggleColVisibility, } }