@xcelsior/ui-spreadsheets 1.2.1 → 1.3.0

package/src/components/SpreadsheetFilterDropdown.tsx

@@ -1,5 +1,6 @@
 import type React from 'react';
-import { useEffect, useRef, useState } from 'react';
+import { useCallback, useEffect, useRef, useState } from 'react';
+import { createPortal } from 'react-dom';
 import { HiCheck, HiX } from 'react-icons/hi';
 import { cn } from '../utils';
 import type {
@@ -53,9 +54,17 @@ const DATE_OPERATORS: { value: DateFilterOperator; label: string }[] = [
     { value: 'isNotEmpty', label: 'Is not empty' },
 ];
 
+const DROPDOWN_WIDTH = 256; // w-64 = 16rem = 256px
+const DROPDOWN_HEIGHT = 340; // approximate max height
+const ARROW_SIZE = 6; // px, half-width of the arrow caret
+
 /**
  * SpreadsheetFilterDropdown component - Condition-based filter dropdown for columns.
  * Supports text conditions, number conditions, and date conditions.
+ *
+ * When `triggerRef` is provided the dropdown renders via React.createPortal at
+ * document.body and positions itself relative to the trigger element.
+ * Falls back to absolute positioning when no triggerRef is given.
  */
 export const SpreadsheetFilterDropdown: React.FC<SpreadsheetFilterDropdownProps> = ({
     column,
@@ -63,7 +72,12 @@ export const SpreadsheetFilterDropdown: React.FC<SpreadsheetFilterDropdownProps>
     onFilterChange,
     onClose,
     className,
+    triggerRef,
+    hasDuplicateCheck = false,
 }) => {
+    const [showDuplicatesOnly, setShowDuplicatesOnly] = useState(
+        filter?.showDuplicatesOnly ?? false
+    );
     const [textOperator, setTextOperator] = useState<TextFilterOperator>(
         filter?.textCondition?.operator || 'contains'
     );
@@ -87,17 +101,91 @@ export const SpreadsheetFilterDropdown: React.FC<SpreadsheetFilterDropdownProps>
 
     const dropdownRef = useRef<HTMLDivElement>(null);
 
+    /** Portal positioning state */
+    const [position, setPosition] = useState<{
+        top: number;
+        left: number;
+        arrowLeft: number;
+        flippedUp: boolean;
+    }>({ top: 0, left: 0, arrowLeft: DROPDOWN_WIDTH / 2, flippedUp: false });
+
     const isNumeric = column.type === 'number';
     const isDate = column.type === 'date';
 
+    const updatePosition = useCallback(() => {
+        if (!triggerRef?.current) return;
+        const rect = triggerRef.current.getBoundingClientRect();
+
+        let top = rect.bottom + 4; // 4px gap below anchor
+        let flippedUp = false;
+
+        // Flip up if overflows bottom of viewport
+        if (top + DROPDOWN_HEIGHT > window.innerHeight) {
+            top = rect.top - DROPDOWN_HEIGHT - 4;
+            flippedUp = true;
+        }
+
+        // Prefer left-aligned with anchor, shift left if overflows right
+        let left = rect.left;
+        if (left + DROPDOWN_WIDTH > window.innerWidth) {
+            left = window.innerWidth - DROPDOWN_WIDTH - 8;
+        }
+        // Never go off-screen left
+        if (left < 8) {
+            left = 8;
+        }
+
+        // Arrow points to center of the anchor element, clamped within dropdown
+        const anchorCenter = rect.left + rect.width / 2;
+        const arrowLeft = Math.min(
+            Math.max(anchorCenter - left, ARROW_SIZE + 4),
+            DROPDOWN_WIDTH - ARROW_SIZE - 4
+        );
+
+        setPosition({ top, left, arrowLeft, flippedUp });
+    }, [triggerRef]);
+
+    // Reposition on mount, scroll (capture phase), and resize
+    useEffect(() => {
+        if (!triggerRef?.current) return;
+        updatePosition();
+        window.addEventListener('scroll', updatePosition, true);
+        window.addEventListener('resize', updatePosition);
+        return () => {
+            window.removeEventListener('scroll', updatePosition, true);
+            window.removeEventListener('resize', updatePosition);
+        };
+    }, [updatePosition, triggerRef]);
+
+    // Close on outside click (delayed to avoid closing on the same click that opened the dropdown)
     useEffect(() => {
         const handleClickOutside = (event: MouseEvent) => {
-            if (dropdownRef.current && !dropdownRef.current.contains(event.target as Node)) {
+            const target = event.target as Node;
+            if (dropdownRef.current && !dropdownRef.current.contains(target)) {
+                // Don't close if clicking the trigger element itself
+                if (triggerRef?.current?.contains(target)) return;
                 onClose();
             }
         };
-        document.addEventListener('mousedown', handleClickOutside);
-        return () => document.removeEventListener('mousedown', handleClickOutside);
+        // Use requestAnimationFrame to skip the current event loop tick
+        const rafId = requestAnimationFrame(() => {
+            document.addEventListener('mousedown', handleClickOutside);
+        });
+        return () => {
+            cancelAnimationFrame(rafId);
+            document.removeEventListener('mousedown', handleClickOutside);
+        };
+    }, [onClose, triggerRef]);
+
+    // Close on Escape key
+    useEffect(() => {
+        const handleKeyDown = (event: KeyboardEvent) => {
+            if (event.key === 'Escape') {
+                onClose();
+            }
+        };
+        document.addEventListener('keydown', handleKeyDown);
+        return () => document.removeEventListener('keydown', handleKeyDown);
     }, [onClose]);
 
     const handleApplyFilter = () => {
@@ -105,18 +193,22 @@ export const SpreadsheetFilterDropdown: React.FC<SpreadsheetFilterDropdownProps>
 
         if (isNumeric) {
             const needsValue = !['isEmpty', 'isNotEmpty'].includes(numberOperator);
-            if (needsValue && !numberValue) {
+            if (needsValue && !numberValue && !showDuplicatesOnly) {
                 onFilterChange(undefined);
                 onClose();
                 return;
             }
             newFilter = {
-                numberCondition: {
+                numberCondition: needsValue || !numberValue ? {
                     operator: numberOperator,
                     value: numberValue ? parseFloat(numberValue) : undefined,
                     valueTo: numberValueTo ? parseFloat(numberValueTo) : undefined,
-                },
+                } : undefined,
+                ...(showDuplicatesOnly && { showDuplicatesOnly: true }),
             };
+            if (!newFilter.numberCondition && !newFilter.showDuplicatesOnly) {
+                newFilter = undefined;
+            }
         } else if (isDate) {
             const needsValue = ![
                 'isEmpty',
@@ -129,7 +221,7 @@ export const SpreadsheetFilterDropdown: React.FC<SpreadsheetFilterDropdownProps>
                 'lastMonth',
                 'thisYear',
             ].includes(dateOperator);
-            if (needsValue && !dateValue) {
+            if (needsValue && !dateValue && !showDuplicatesOnly) {
                 onFilterChange(undefined);
                 onClose();
                 return;
@@ -140,20 +232,25 @@ export const SpreadsheetFilterDropdown: React.FC<SpreadsheetFilterDropdownProps>
                     value: dateValue || undefined,
                     valueTo: dateValueTo || undefined,
                 },
+                ...(showDuplicatesOnly && { showDuplicatesOnly: true }),
             };
         } else {
             const needsValue = !['isEmpty', 'isNotEmpty'].includes(textOperator);
-            if (needsValue && !textValue) {
+            if (needsValue && !textValue && !showDuplicatesOnly) {
                 onFilterChange(undefined);
                 onClose();
                 return;
             }
             newFilter = {
-                textCondition: {
+                textCondition: needsValue || !textValue ? {
                     operator: textOperator,
                     value: textValue || undefined,
-                },
+                } : undefined,
+                ...(showDuplicatesOnly && { showDuplicatesOnly: true }),
             };
+            if (!newFilter.textCondition && !newFilter.showDuplicatesOnly) {
+                newFilter = undefined;
+            }
         }
 
         onFilterChange(newFilter);
@@ -161,6 +258,7 @@ export const SpreadsheetFilterDropdown: React.FC<SpreadsheetFilterDropdownProps>
     };
 
     const handleClearFilter = () => {
+        setShowDuplicatesOnly(false);
         setTextValue('');
         setNumberValue('');
         setNumberValueTo('');
@@ -170,6 +268,14 @@ export const SpreadsheetFilterDropdown: React.FC<SpreadsheetFilterDropdownProps>
         onClose();
     };
 
+    // Submit filter on Enter key press
+    const handleFilterKeyDown = (e: React.KeyboardEvent) => {
+        if (e.key === 'Enter') {
+            e.preventDefault();
+            handleApplyFilter();
+        }
+    };
+
     const textNeedsValue = !['isEmpty', 'isNotEmpty'].includes(textOperator);
     const numberNeedsValue = !['isEmpty', 'isNotEmpty'].includes(numberOperator);
     const dateNeedsValue = ![
@@ -184,19 +290,67 @@ export const SpreadsheetFilterDropdown: React.FC<SpreadsheetFilterDropdownProps>
         'thisYear',
     ].includes(dateOperator);
 
-    return (
+    const dropdownContent = (
         <div
             ref={dropdownRef}
             className={cn(
-                'absolute top-full left-0 mt-1 bg-white border border-gray-200 shadow-lg rounded-lg w-64 overflow-hidden flex flex-col z-[100]',
+                'bg-white border border-gray-200 shadow-lg rounded-lg w-64 overflow-hidden flex flex-col',
+                !triggerRef && 'absolute top-full left-0 mt-1 z-[100]',
                 className
             )}
+            style={
+                triggerRef
+                    ? { position: 'fixed', top: position.top, left: position.left, zIndex: 9999 }
+                    : undefined
+            }
             onClick={(e) => e.stopPropagation()}
         >
+            {/* Arrow caret pointing to the anchor column */}
+            {triggerRef && (
+                <div
+                    className="absolute pointer-events-none"
+                    style={
+                        position.flippedUp
+                            ? {
+                                  bottom: -ARROW_SIZE,
+                                  left: position.arrowLeft - ARROW_SIZE,
+                                  width: 0,
+                                  height: 0,
+                                  borderLeft: `${ARROW_SIZE}px solid transparent`,
+                                  borderRight: `${ARROW_SIZE}px solid transparent`,
+                                  borderTop: `${ARROW_SIZE}px solid #e5e7eb`,
+                              }
+                            : {
+                                  top: -ARROW_SIZE,
+                                  left: position.arrowLeft - ARROW_SIZE,
+                                  width: 0,
+                                  height: 0,
+                                  borderLeft: `${ARROW_SIZE}px solid transparent`,
+                                  borderRight: `${ARROW_SIZE}px solid transparent`,
+                                  borderBottom: `${ARROW_SIZE}px solid #e5e7eb`,
+                              }
+                    }
+                />
+            )}
+
             <div className="px-3 py-2 border-b border-gray-200 bg-gray-50">
                 <span className="text-xs font-medium text-gray-700">Filter: {column.label}</span>
             </div>
 
+            {hasDuplicateCheck && (
+                <div className="px-3 pt-2 pb-2 border-b border-gray-200">
+                    <label className="flex items-center gap-2 cursor-pointer select-none">
+                        <input
+                            type="checkbox"
+                            checked={showDuplicatesOnly}
+                            onChange={(e) => setShowDuplicatesOnly(e.target.checked)}
+                            className="h-3 w-3 rounded border-gray-300 text-red-600 focus:ring-red-500"
+                        />
+                        <span className="text-xs text-gray-700">Show only duplicates</span>
+                    </label>
+                </div>
+            )}
+
             <div className="p-3 space-y-3">
                 {isNumeric ? (
                     <>
@@ -224,6 +378,7 @@ export const SpreadsheetFilterDropdown: React.FC<SpreadsheetFilterDropdownProps>
                                     placeholder="Enter value"
                                     value={numberValue}
                                     onChange={(e) => setNumberValue(e.target.value)}
+                                    onKeyDown={handleFilterKeyDown}
                                     className="w-full px-2 py-1.5 text-xs border border-gray-300 rounded focus:outline-none focus:ring-1 focus:ring-blue-500"
                                 />
                             </div>
@@ -236,6 +391,7 @@ export const SpreadsheetFilterDropdown: React.FC<SpreadsheetFilterDropdownProps>
                                     placeholder="Enter end value"
                                     value={numberValueTo}
                                     onChange={(e) => setNumberValueTo(e.target.value)}
+                                    onKeyDown={handleFilterKeyDown}
                                     className="w-full px-2 py-1.5 text-xs border border-gray-300 rounded focus:outline-none focus:ring-1 focus:ring-blue-500"
                                 />
                             </div>
@@ -266,6 +422,7 @@ export const SpreadsheetFilterDropdown: React.FC<SpreadsheetFilterDropdownProps>
                                     type="date"
                                     value={dateValue}
                                     onChange={(e) => setDateValue(e.target.value)}
+                                    onKeyDown={handleFilterKeyDown}
                                     className="w-full px-2 py-1.5 text-xs border border-gray-300 rounded focus:outline-none focus:ring-1 focus:ring-blue-500"
                                 />
                             </div>
@@ -277,6 +434,7 @@ export const SpreadsheetFilterDropdown: React.FC<SpreadsheetFilterDropdownProps>
                                     type="date"
                                     value={dateValueTo}
                                     onChange={(e) => setDateValueTo(e.target.value)}
+                                    onKeyDown={handleFilterKeyDown}
                                     className="w-full px-2 py-1.5 text-xs border border-gray-300 rounded focus:outline-none focus:ring-1 focus:ring-blue-500"
                                 />
                             </div>
@@ -308,6 +466,7 @@ export const SpreadsheetFilterDropdown: React.FC<SpreadsheetFilterDropdownProps>
                                     placeholder="Enter text"
                                     value={textValue}
                                     onChange={(e) => setTextValue(e.target.value)}
+                                    onKeyDown={handleFilterKeyDown}
                                     className="w-full px-2 py-1.5 text-xs border border-gray-300 rounded focus:outline-none focus:ring-1 focus:ring-blue-500"
                                 />
                             </div>
@@ -336,6 +495,12 @@ export const SpreadsheetFilterDropdown: React.FC<SpreadsheetFilterDropdownProps>
             </div>
         </div>
     );
+
+    if (triggerRef) {
+        return createPortal(dropdownContent, document.body);
+    }
+
+    return dropdownContent;
 };
 
 SpreadsheetFilterDropdown.displayName = 'SpreadsheetFilterDropdown';

package/src/components/SpreadsheetHeader.tsx

@@ -1,12 +1,11 @@
-import type React from 'react';
+import React, { memo, useRef } from 'react';
 import { HiChevronDown, HiChevronUp } from 'react-icons/hi';
 import { cn } from '../utils';
 import type { SpreadsheetHeaderProps } from '../types';
 import { ColumnHeaderActions } from './ColumnHeaderActions';
-import { MIN_PINNED_COLUMN_WIDTH } from '../hooks/useSpreadsheetPinning';
 
-const cellPaddingCompact = 'px-1 py-0.5';
-const cellPaddingNormal = 'px-2 py-1.5';
+const cellPaddingCompact = 'px-1.5 py-1';
+const cellPaddingNormal = 'px-2 py-2';
 
 /**
  * SpreadsheetHeader component - A column header cell with sorting, filtering, and pinning capabilities.
@@ -34,12 +33,21 @@ export const SpreadsheetHeader: React.FC<
     highlightColor,
     compactMode = false,
     onClick,
+    pinnedZIndex,
+    onSortClick,
     onFilterClick,
     onPinClick,
     onHighlightClick,
+    hasDuplicateCheck = false,
+    onDuplicateCheckClick,
+    duplicateCount,
+    resizeHandleProps,
+    resolvedWidth,
+    topOffset = 0,
     className,
     children,
 }) => {
+    const thRef = useRef<HTMLTableCellElement>(null);
     const isSorted = sortConfig?.columnId === column.id;
     const sortDirection = isSorted ? sortConfig.direction : null;
 
@@ -58,33 +66,31 @@ export const SpreadsheetHeader: React.FC<
 
     return (
         <th
-            onClick={column.sortable ? onClick : undefined}
+            ref={thRef}
+            data-column-id={column.id}
+            onClick={onClick}
             className={cn(
-                'border border-gray-200 font-semibold text-gray-700 sticky group',
-                compactMode ? 'text-[10px]' : 'text-xs',
+                'border border-gray-200 font-semibold text-gray-700 group relative cursor-pointer',
+                isPinned && 'sticky',
+                compactMode ? 'text-xs' : 'text-sm',
                 cellPadding,
                 column.align === 'right' && 'text-right',
                 column.align === 'center' && 'text-center',
-                column.sortable && 'cursor-pointer hover:bg-gray-100',
-                isPinned ? 'z-30' : 'z-20',
+                'hover:bg-gray-100',
+                !isPinned && 'z-20',
                 className
             )}
             style={{
                 backgroundColor: highlightColor || 'rgb(243 244 246)', // gray-100
-                minWidth: column.minWidth || column.width,
-                // Pinned columns must have a fixed width so sticky offsets stay correct.
-                // Enforce MIN_PINNED_COLUMN_WIDTH so header actions (pin/filter/highlight) always fit.
-                ...(isPinned && {
-                    width: Math.max(
-                        column.minWidth || column.width || MIN_PINNED_COLUMN_WIDTH,
-                        MIN_PINNED_COLUMN_WIDTH
-                    ),
-                    maxWidth: Math.max(
-                        column.minWidth || column.width || MIN_PINNED_COLUMN_WIDTH,
-                        MIN_PINNED_COLUMN_WIDTH
-                    ),
+                // Always set explicit width to prevent layout shift on selection/re-render
+                ...(resolvedWidth ? {
+                    width: resolvedWidth,
+                    minWidth: resolvedWidth,
+                } : {
+                    width: column.width || column.minWidth,
+                    minWidth: column.minWidth || column.width,
                 }),
-                top: 0, // For sticky header
+                ...(isPinned && pinnedZIndex !== undefined && { zIndex: pinnedZIndex + 10 }), // +10 so headers are above cells
                 ...positionStyles,
             }}
         >
@@ -101,10 +107,21 @@ export const SpreadsheetHeader: React.FC<
                             )}
                         </span>
                     )}
+                    {hasDuplicateCheck && duplicateCount != null && duplicateCount > 0 && (
+                        <span
+                            className="inline-flex items-center px-1 py-0.5 rounded-full bg-red-100 text-red-600 text-[10px] font-medium leading-none"
+                            title={`${duplicateCount} duplicate values found`}
+                        >
+                            {duplicateCount}
+                        </span>
+                    )}
                 </span>
 
                 {/* Action buttons using unified ColumnHeaderActions */}
                 <ColumnHeaderActions
+                    enableSorting={column.sortable}
+                    sortDirection={isSorted ? sortDirection : null}
+                    onSortClick={onSortClick}
                     enableFiltering={column.filterable}
                     enableHighlighting={column.highlightable !== false && !!onHighlightClick}
                     enablePinning={column.pinnable !== false}
@@ -114,12 +131,50 @@ export const SpreadsheetHeader: React.FC<
                     onFilterClick={onFilterClick}
                     onHighlightClick={onHighlightClick}
                     onPinClick={onPinClick}
+                    resolvedWidth={resolvedWidth}
+                    enableDuplicateCheck={true}
+                    hasDuplicateCheck={hasDuplicateCheck}
+                    onDuplicateCheckClick={onDuplicateCheckClick}
                 />
             </div>
-            {/* Filter dropdown rendered inside th for proper positioning */}
-            {children}
+            {/* Filter dropdown rendered inside th for proper positioning, cloned with triggerRef */}
+            {children && React.Children.map(children, (child) =>
+                React.isValidElement(child)
+                    ? React.cloneElement(child as React.ReactElement<any>, { triggerRef: thRef })
+                    : child
+            )}
+            {/* Resize handle */}
+            {resizeHandleProps && (
+                <div
+                    onMouseDown={resizeHandleProps.onMouseDown}
+                    style={resizeHandleProps.style}
+                    className={resizeHandleProps.className}
+                />
+            )}
         </th>
     );
 };
 
 SpreadsheetHeader.displayName = 'SpreadsheetHeader';
+
+export const MemoizedSpreadsheetHeader = memo(SpreadsheetHeader, (prevProps, nextProps) => {
+    if (prevProps.column.id !== nextProps.column.id) return false;
+    if (prevProps.sortConfig?.columnId !== nextProps.sortConfig?.columnId) return false;
+    if (prevProps.sortConfig?.direction !== nextProps.sortConfig?.direction) return false;
+    if (prevProps.hasActiveFilter !== nextProps.hasActiveFilter) return false;
+    if (prevProps.isPinned !== nextProps.isPinned) return false;
+    if (prevProps.pinSide !== nextProps.pinSide) return false;
+    if (prevProps.leftOffset !== nextProps.leftOffset) return false;
+    if (prevProps.rightOffset !== nextProps.rightOffset) return false;
+    if (prevProps.highlightColor !== nextProps.highlightColor) return false;
+    if (prevProps.compactMode !== nextProps.compactMode) return false;
+    if (prevProps.pinnedZIndex !== nextProps.pinnedZIndex) return false;
+    if (prevProps.resolvedWidth !== nextProps.resolvedWidth) return false;
+    if (prevProps.topOffset !== nextProps.topOffset) return false;
+    if (prevProps.hasDuplicateCheck !== nextProps.hasDuplicateCheck) return false;
+    if (prevProps.duplicateCount !== nextProps.duplicateCount) return false;
+    if (prevProps.children !== nextProps.children) return false;
+    return true;
+});
+
+MemoizedSpreadsheetHeader.displayName = 'MemoizedSpreadsheetHeader';

package/src/components/SpreadsheetSettingsModal.tsx

@@ -18,6 +18,10 @@ export interface SpreadsheetSettings {
     autoSave?: boolean;
     /** Whether compact view is enabled */
     compactView?: boolean;
+    /** Persisted column widths (columnId → width in px) */
+    columnWidths?: Record<string, number>;
+    /** Column IDs with duplicate checking enabled */
+    duplicateCheckColumns?: string[];
 }
 
 export interface SpreadsheetSettingsModalProps {

package/src/hooks/useSpreadsheetColumnResize.ts

@@ -0,0 +1,143 @@
+import { useCallback, useState, useRef } from 'react';
+
+export interface UseSpreadsheetColumnResizeOptions {
+    /** Minimum column width in pixels */
+    minWidth?: number;
+    /** Initial column widths to restore from persisted settings */
+    initialColumnWidths?: Record<string, number>;
+    /** Callback when a column is resized (for external persistence) */
+    onColumnResize?: (columnId: string, width: number) => void;
+}
+
+export interface UseSpreadsheetColumnResizeReturn {
+    /** Map of column ID to resized width */
+    columnWidths: Map<string, number>;
+    /** Get the effective width for a column (resized or fallback) */
+    getColumnWidth: (columnId: string, defaultWidth?: number) => number | undefined;
+    /** Props to spread on the resize handle element */
+    getResizeHandleProps: (columnId: string, currentWidth: number) => {
+        onMouseDown: (e: React.MouseEvent) => void;
+        style: React.CSSProperties;
+        className: string;
+    };
+    /** Whether a column is currently being resized */
+    isResizing: boolean;
+    /** The column ID currently being resized */
+    resizingColumnId: string | null;
+}
+
+const DEFAULT_MIN_WIDTH = 40;
+
+/**
+ * Hook for managing column resize via drag handles on header edges.
+ * Uses direct DOM updates during drag for smooth performance, committing to state on mouseup.
+ */
+export function useSpreadsheetColumnResize({
+    minWidth = DEFAULT_MIN_WIDTH,
+    initialColumnWidths,
+    onColumnResize,
+}: UseSpreadsheetColumnResizeOptions = {}): UseSpreadsheetColumnResizeReturn {
+    const [columnWidths, setColumnWidths] = useState<Map<string, number>>(() => {
+        if (initialColumnWidths) {
+            return new Map(Object.entries(initialColumnWidths));
+        }
+        return new Map();
+    });
+    const [resizingColumnId, setResizingColumnId] = useState<string | null>(null);
+    const startXRef = useRef(0);
+    const startWidthRef = useRef(0);
+    const rafRef = useRef<number | null>(null);
+
+    const getColumnWidth = useCallback(
+        (columnId: string, defaultWidth?: number): number | undefined => {
+            return columnWidths.get(columnId) ?? defaultWidth;
+        },
+        [columnWidths]
+    );
+
+    /**
+     * Directly update DOM widths for the column during drag (no React re-render).
+     * Targets both <th> and <td> elements with the matching data-column-id.
+     */
+    const updateColumnDom = useCallback((columnId: string, width: number) => {
+        const widthPx = `${width}px`;
+        const cells = document.querySelectorAll(`[data-column-id="${columnId}"]`);
+        for (let i = 0; i < cells.length; i++) {
+            const el = cells[i] as HTMLElement;
+            el.style.width = widthPx;
+            el.style.minWidth = widthPx;
+        }
+    }, []);
+
+    const getResizeHandleProps = useCallback(
+        (columnId: string, currentWidth: number) => {
+            return {
+                onMouseDown: (e: React.MouseEvent) => {
+                    e.preventDefault();
+                    e.stopPropagation();
+
+                    startXRef.current = e.clientX;
+                    startWidthRef.current = columnWidths.get(columnId) ?? currentWidth;
+                    setResizingColumnId(columnId);
+
+                    document.body.style.cursor = 'col-resize';
+                    document.body.style.userSelect = 'none';
+
+                    let latestWidth = startWidthRef.current;
+
+                    const moveHandler = (ev: MouseEvent) => {
+                        const diff = ev.clientX - startXRef.current;
+                        latestWidth = Math.max(minWidth, startWidthRef.current + diff);
+
+                        // Throttle DOM updates to animation frames
+                        if (rafRef.current === null) {
+                            rafRef.current = requestAnimationFrame(() => {
+                                rafRef.current = null;
+                                updateColumnDom(columnId, latestWidth);
+                            });
+                        }
+                    };
+
+                    const upHandler = () => {
+                        document.removeEventListener('mousemove', moveHandler);
+                        document.removeEventListener('mouseup', upHandler);
+
+                        if (rafRef.current !== null) {
+                            cancelAnimationFrame(rafRef.current);
+                            rafRef.current = null;
+                        }
+
+                        // Commit final width to React state
+                        setColumnWidths((prev) => {
+                            const next = new Map(prev);
+                            next.set(columnId, latestWidth);
+                            return next;
+                        });
+                        onColumnResize?.(columnId, latestWidth);
+
+                        setResizingColumnId(null);
+                        document.body.style.cursor = '';
+                        document.body.style.userSelect = '';
+                    };
+
+                    document.addEventListener('mousemove', moveHandler);
+                    document.addEventListener('mouseup', upHandler);
+                },
+                style: {
+                    cursor: 'col-resize' as const,
+                } as React.CSSProperties,
+                className:
+                    'absolute top-0 right-0 w-1 h-full hover:bg-blue-400 transition-colors z-10',
+            };
+        },
+        [columnWidths, minWidth, onColumnResize, updateColumnDom]
+    );
+
+    return {
+        columnWidths,
+        getColumnWidth,
+        getResizeHandleProps,
+        isResizing: resizingColumnId !== null,
+        resizingColumnId,
+    };
+}