@xcelsior/ui-spreadsheets 1.2.2 → 1.3.0

package/plans/20260330-1230-spreadsheet-features/phase-04-integration.md

@@ -0,0 +1,193 @@
+# Phase 04: Integration + Loading Overlay
+
+**Parallel group:** B (runs AFTER Phase 1, 2, 3)
+**Files owned:** `Spreadsheet.tsx`, `SpreadsheetHeader.tsx`, `SpreadsheetCell.tsx`, `SpreadsheetSettingsModal.tsx`, `index.ts`
+
+## Work
+
+### 1. Wire Duplicate Detection into Spreadsheet.tsx
+
+**Add hook usage:**
+```ts
+import { useSpreadsheetDuplicates } from '../hooks/useSpreadsheetDuplicates';
+
+// In component body:
+const [duplicateCheckColumns, setDuplicateCheckColumns] = useState<string[]>(
+  initialSettings?.duplicateCheckColumns ?? props.duplicateCheckColumns ?? []
+);
+
+const { isCellDuplicate } = useSpreadsheetDuplicates({
+  data,
+  columns,
+  duplicateCheckColumns,
+  getRowId,
+});
+
+const handleDuplicateCheckToggle = useCallback((columnId: string) => {
+  setDuplicateCheckColumns(prev => {
+    const next = prev.includes(columnId)
+      ? prev.filter(id => id !== columnId)
+      : [...prev, columnId];
+    onDuplicateCheckChange?.(next);
+    return next;
+  });
+}, [onDuplicateCheckChange]);
+```
+
+**Pass to SpreadsheetCell:**
+```tsx
+<SpreadsheetCell
+  ...existingProps
+  isDuplicate={isCellDuplicate(rowId, column.id)}
+/>
+```
+
+**Pass to SpreadsheetHeader (via ColumnHeaderActions props):**
+```tsx
+<MemoizedSpreadsheetHeader
+  ...existingProps
+  hasDuplicateCheck={duplicateCheckColumns.includes(column.id)}
+  onDuplicateCheckClick={() => handleDuplicateCheckToggle(column.id)}
+/>
+```
+
+### 2. Wire Filter Portal into Spreadsheet.tsx
+
+**Add ref for each header cell:**
+The filter dropdown currently renders as a child of `<MemoizedSpreadsheetHeader>`. Change to:
+
+```tsx
+// Create a ref map for header cells
+const headerRefsMap = useRef<Map<string, HTMLElement>>(new Map());
+
+// In the header render, pass ref callback:
+// SpreadsheetHeader already renders a <th> -- capture via data attribute + ref callback
+```
+
+**Simpler approach:** Pass a `triggerRef` from the `<th>` element. Since `SpreadsheetFilterDropdown` is rendered inside `MemoizedSpreadsheetHeader`'s children slot, add a ref to the `<th>` in `SpreadsheetHeader.tsx`:
+
+In `SpreadsheetHeader.tsx`:
+```tsx
+const thRef = useRef<HTMLTableCellElement>(null);
+// Add ref={thRef} to <th>
+// Pass thRef to children via render prop or context
+```
+
+**Preferred approach:** Use a ref on the `<th>` in SpreadsheetHeader and pass it down to the filter dropdown.
+
+Add `headerRef` prop to `SpreadsheetHeaderProps` in types.ts -- wait, types.ts is Phase 1. Instead, use `useRef` locally in SpreadsheetHeader and pass to filter dropdown child via cloneElement or direct prop.
+
+**Implementation:** In `SpreadsheetHeader.tsx`, add a ref to the `<th>` and expose it. Then in `Spreadsheet.tsx`, when rendering the `SpreadsheetFilterDropdown` as children of the header, pass the `triggerRef`:
+
+```tsx
+// SpreadsheetHeader.tsx changes:
+const thRef = useRef<HTMLTableCellElement>(null);
+// <th ref={thRef} ...>
+// Pass thRef to children via React.Children.map + cloneElement
+{React.Children.map(children, child =>
+  React.isValidElement(child) ? React.cloneElement(child, { triggerRef: thRef }) : child
+)}
+```
+
+### 3. Update SpreadsheetHeader.tsx
+
+- Add `thRef` and pass to `<th ref={thRef}>`
+- Clone children with `triggerRef={thRef}`
+- Add `hasDuplicateCheck` and `onDuplicateCheckClick` props, pass through to `ColumnHeaderActions`:
+```tsx
+<ColumnHeaderActions
+  ...existingProps
+  resolvedWidth={resolvedWidth}
+  enableDuplicateCheck={true}
+  hasDuplicateCheck={hasDuplicateCheck}
+  onDuplicateCheckClick={onDuplicateCheckClick}
+/>
+```
+- Update memo comparison to include `hasDuplicateCheck`
+
+### 4. Update SpreadsheetCell.tsx
+
+**Add duplicate highlight:**
+In `getBackgroundColor()`:
+```ts
+if (isDuplicate) return 'rgb(254 226 226)'; // red-100 - light red for duplicates
+```
+Priority: duplicate highlight should be BELOW explicit `highlightColor` but ABOVE row selection/hover.
+
+Updated order:
+```ts
+const getBackgroundColor = () => {
+  if (highlightColor) return highlightColor;
+  if (isDuplicate) return 'rgb(254 226 226)'; // red-100
+  if (isRowSelected) return 'rgb(219 234 254)'; // blue-100
+  if (isRowHovered) return 'rgb(243 244 246)'; // gray-100
+  if (isOddRow) return 'rgb(249 250 251)'; // gray-50
+  return 'white';
+};
+```
+
+**Update memo comparison** to include `isDuplicate`.
+
+### 5. Client-Side Loading Overlay
+
+**Add processing state to Spreadsheet.tsx:**
+```ts
+const [isProcessing, setIsProcessing] = useState(false);
+```
+
+Wrap expensive operations with processing state:
+- `handleSort`: set processing before, clear after
+- `handleFilterChangeWithReset`: set processing before, clear after
+- `handleDuplicateCheckToggle`: set processing before, clear after
+
+Use `React.startTransition` for the state updates that trigger re-renders of the data:
+```ts
+const handleSort = useCallback((columnId: string) => {
+  setIsProcessing(true);
+  startTransition(() => {
+    // existing sort logic
+    setIsProcessing(false);
+  });
+}, [...]);
+```
+
+**Overlay rendering in tbody:**
+```tsx
+{(isProcessing) && (
+  <div className="absolute inset-0 bg-white/60 flex items-center justify-center z-50 pointer-events-none">
+    <div className="flex items-center gap-2 text-gray-500">
+      <div className="w-4 h-4 border-2 border-blue-600 border-t-transparent rounded-full animate-spin" />
+      Processing...
+    </div>
+  </div>
+)}
+```
+
+The table wrapper div needs `position: relative` to anchor the overlay.
+
+### 6. Update SpreadsheetSettingsModal.tsx
+
+Add `duplicateCheckColumns` to `SpreadsheetSettings` interface:
+```ts
+duplicateCheckColumns?: string[];
+```
+
+### 7. Update index.ts
+
+Export the new hook:
+```ts
+export { useSpreadsheetDuplicates } from './hooks/useSpreadsheetDuplicates';
+```
+
+### Acceptance criteria:
+- [ ] Duplicate check toggle works from column header actions (both inline and overflow menu)
+- [ ] Duplicate cells show light red background; explicit highlight color takes priority
+- [ ] Filter dropdown renders as portal, positioned correctly relative to header cell
+- [ ] Filter dropdown repositions on scroll/resize, closes on outside click + Escape
+- [ ] Processing overlay shows during sort/filter/duplicate-check on large datasets
+- [ ] `duplicateCheckColumns` prop controls which columns have duplicate checking
+- [ ] `onDuplicateCheckChange` callback fires when user toggles duplicate check
+- [ ] Settings persist `duplicateCheckColumns` like pinned columns
+- [ ] `useSpreadsheetDuplicates` exported from package index
+- [ ] No regressions: pinning, sorting, filtering, editing, sticky header, column resize all work
+- [ ] MemoizedSpreadsheetCell and MemoizedSpreadsheetHeader updated to include new comparison props

package/plans/20260330-1230-spreadsheet-features/plan.md

@@ -0,0 +1,59 @@
+# Spreadsheet Features - Implementation Plan
+
+## Context
+Add 4 features to `packages/ui/ui-spreadsheets`: duplicate check on columns, header icon overflow menu, client-side loading overlay, and filter dropdown portal. All must be parallel-safe with exclusive file ownership per phase.
+
+## Dependency Graph
+
+```
+Phase 1 (Types + Hook)          Phase 2 (Filter Portal)
+   types.ts                      SpreadsheetFilterDropdown.tsx
+   useSpreadsheetDuplicates.ts   (NEW)
+        |                              |
+        v                              v
+Phase 3 (Column Header Overflow) Phase 4 (Integration)
+   ColumnHeaderActions.tsx        Spreadsheet.tsx
+                                  SpreadsheetHeader.tsx
+                                  SpreadsheetCell.tsx
+                                  SpreadsheetSettingsModal.tsx
+                                  index.ts
+```
+
+**Parallel execution:**
+- Phase 1 and Phase 2: PARALLEL (no shared files)
+- Phase 3: PARALLEL with Phase 1 and Phase 2 (no shared files)
+- Phase 4: SEQUENTIAL after Phase 1 + 2 + 3 (integrates all features into Spreadsheet.tsx)
+
+## File Ownership Matrix
+
+| File | Phase 1 | Phase 2 | Phase 3 | Phase 4 |
+|------|---------|---------|---------|---------|
+| `types.ts` | WRITE | - | - | - |
+| `hooks/useSpreadsheetDuplicates.ts` (NEW) | WRITE | - | - | - |
+| `SpreadsheetFilterDropdown.tsx` | - | WRITE | - | - |
+| `ColumnHeaderActions.tsx` | - | - | WRITE | - |
+| `Spreadsheet.tsx` | - | - | - | WRITE |
+| `SpreadsheetHeader.tsx` | - | - | - | WRITE |
+| `SpreadsheetCell.tsx` | - | - | - | WRITE |
+| `SpreadsheetSettingsModal.tsx` | - | - | - | WRITE |
+| `index.ts` | - | - | - | WRITE |
+
+## Execution Strategy
+
+1. Run **Phase 1, 2, 3 in parallel** -- they touch completely independent files
+2. Run **Phase 4 sequentially** -- it wires everything together in Spreadsheet.tsx and updates dependent components
+
+## Phases
+
+- [Phase 01: Types + Duplicate Detection Hook](./phase-01-types-and-duplicates-hook.md)
+- [Phase 02: Filter Dropdown Portal](./phase-02-filter-dropdown-portal.md)
+- [Phase 03: Column Header Overflow Menu](./phase-03-header-overflow-menu.md)
+- [Phase 04: Integration + Loading Overlay](./phase-04-integration.md)
+
+## Success Criteria
+- All 4 features functional with 2000+ rows x 30+ columns
+- No regressions in pinning, sorting, filtering, editing, sticky header, column resize
+- Duplicate check columns controllable via props for DB persistence
+- Filter dropdown renders via portal, repositions on scroll/resize
+- Header actions collapse to "..." when column width < 80px
+- Loading overlay shows during expensive client-side operations

package/src/components/ColorPickerPopover.tsx

@@ -1,16 +1,18 @@
+import { useState, useRef } from 'react';
 import { cn } from '../utils';
-import { HIGHLIGHT_COLORS } from '../hooks/useSpreadsheetHighlighting';
 
 export type ColorPaletteType = 'row' | 'column';
 
 export interface ColorPickerPopoverProps {
     /** Title displayed in the popover */
     title: string;
-    /** Type of color palette to use */
+    /** Type of color palette to use (unused — kept for API compat) */
     paletteType?: ColorPaletteType;
-    /** Custom colors array (overrides paletteType) */
+    /** Custom colors array (unused — kept for API compat) */
     colors?: (string | null)[];
-    /** Callback when a color is selected */
+    /** Recently used colors */
+    recentColors?: string[];
+    /** Callback when a color is confirmed */
     onSelectColor: (color: string | null) => void;
     /** Callback when the popover is closed/cancelled */
     onClose: () => void;
@@ -19,48 +21,91 @@ export interface ColorPickerPopoverProps {
 }
 
 /**
- * A reusable color picker popover component for highlighting.
- * Supports both row (darker) and column (lighter) color palettes.
+ * Color picker popover using the native HTML color input for full flexibility,
+ * with a recent colors row and confirm/clear actions.
  */
 export function ColorPickerPopover({
     title,
-    paletteType = 'column',
-    colors,
+    recentColors = [],
     onSelectColor,
     onClose,
     className,
 }: ColorPickerPopoverProps) {
-    // Use custom colors if provided, otherwise use palette based on type
-    const colorPalette = colors ?? [...HIGHLIGHT_COLORS[paletteType], null];
+    const [selectedColor, setSelectedColor] = useState('#fef08a');
+    const colorInputRef = useRef<HTMLInputElement>(null);
+
+    const handleConfirm = () => {
+        onSelectColor(selectedColor);
+    };
 
     return (
-        <div className="fixed inset-0 z-50 flex items-center justify-center bg-black/50">
-            <div className={cn('bg-white rounded-lg shadow-xl p-4 w-64', className)}>
+        <div className="fixed inset-0 z-50 flex items-center justify-center bg-black/50" onClick={onClose}>
+            <div
+                className={cn('bg-white rounded-lg shadow-xl p-4 w-72', className)}
+                onClick={(e) => e.stopPropagation()}
+            >
                 <h3 className="text-sm font-semibold mb-3">{title}</h3>
-                <div className="grid grid-cols-5 gap-2">
-                    {colorPalette.map((color) => (
-                        <button
-                            key={color || 'clear'}
-                            type="button"
-                            onClick={() => onSelectColor(color)}
-                            className={cn(
-                                'w-8 h-8 rounded border-2 transition-transform hover:scale-110',
-                                color
-                                    ? 'border-gray-300'
-                                    : 'border-gray-300 bg-white flex items-center justify-center text-gray-400 text-xs'
-                            )}
-                            style={color ? { backgroundColor: color } : undefined}
-                            title={color || 'Clear highlight'}
-                        >
-                            {!color && '✕'}
-                        </button>
-                    ))}
+
+                {/* Native color picker with preview */}
+                <div className="flex items-center gap-3 mb-3">
+                    <input
+                        ref={colorInputRef}
+                        type="color"
+                        value={selectedColor}
+                        onChange={(e) => setSelectedColor(e.target.value)}
+                        className="w-10 h-10 rounded border border-gray-200 cursor-pointer p-0.5"
+                    />
+                    <div className="flex-1">
+                        <div
+                            className="w-full h-8 rounded border border-gray-200"
+                            style={{ backgroundColor: selectedColor }}
+                        />
+                        <span className="text-xs text-gray-500 mt-1 block">{selectedColor}</span>
+                    </div>
                 </div>
-                <div className="flex justify-end mt-4">
+
+                {/* Recent colors */}
+                {recentColors.length > 0 && (
+                    <div className="mb-3">
+                        <span className="text-xs text-gray-500 mb-1.5 block">Recent</span>
+                        <div className="flex gap-1.5">
+                            {recentColors.map((color) => (
+                                <button
+                                    key={color}
+                                    type="button"
+                                    onClick={() => setSelectedColor(color)}
+                                    className={cn(
+                                        'w-7 h-7 rounded border-2 transition-transform hover:scale-110',
+                                        selectedColor === color ? 'border-blue-500' : 'border-gray-200 hover:border-gray-400'
+                                    )}
+                                    style={{ backgroundColor: color }}
+                                    title={color}
+                                />
+                            ))}
+                        </div>
+                    </div>
+                )}
+
+                {/* Actions */}
+                <div className="flex items-center gap-2 pt-2 border-t border-gray-100">
+                    <button
+                        type="button"
+                        onClick={handleConfirm}
+                        className="flex-1 px-2.5 py-1.5 text-xs text-white bg-blue-600 hover:bg-blue-700 rounded transition-colors font-medium"
+                    >
+                        Apply
+                    </button>
+                    <button
+                        type="button"
+                        onClick={() => onSelectColor(null)}
+                        className="px-2.5 py-1.5 text-xs text-red-600 hover:bg-red-50 rounded border border-red-200 transition-colors"
+                    >
+                        Clear
+                    </button>
                     <button
                         type="button"
                         onClick={onClose}
-                        className="px-3 py-1.5 text-sm text-gray-600 hover:bg-gray-100 rounded transition-colors"
+                        className="px-2.5 py-1.5 text-xs text-gray-600 hover:bg-gray-100 rounded transition-colors"
                     >
                         Cancel
                     </button>

package/src/components/ColumnHeaderActions.tsx

@@ -1,4 +1,6 @@
-import { HiFilter } from 'react-icons/hi';
+import { useEffect, useRef, useState } from 'react';
+import { createPortal } from 'react-dom';
+import { HiFilter, HiSortAscending, HiSortDescending, HiDotsVertical, HiExclamation } from 'react-icons/hi';
 import { AiFillHighlight } from 'react-icons/ai';
 import { MdOutlinePushPin, MdPushPin } from 'react-icons/md';
 import { cn } from '../utils';
@@ -16,6 +18,12 @@ export interface ColumnHeaderActionsProps {
     hasActiveHighlight?: boolean;
     /** Whether the column is currently pinned */
     isPinned?: boolean;
+    /** Whether sorting is enabled for this column */
+    enableSorting?: boolean;
+    /** Current sort direction for this column (null if not sorted) */
+    sortDirection?: 'asc' | 'desc' | null;
+    /** Callback when sort button is clicked */
+    onSortClick?: () => void;
     /** Callback when filter button is clicked */
     onFilterClick?: () => void;
     /** Callback when highlight button is clicked */
@@ -32,11 +40,20 @@ export interface ColumnHeaderActionsProps {
     unpinnedTitle?: string;
     /** Additional className */
     className?: string;
+    /** Resolved column width -- when < 80px, actions collapse to overflow menu */
+    resolvedWidth?: number;
+    /** Whether duplicate check is enabled for this column */
+    enableDuplicateCheck?: boolean;
+    /** Whether duplicate check is active */
+    hasDuplicateCheck?: boolean;
+    /** Callback when duplicate check is toggled */
+    onDuplicateCheckClick?: () => void;
 }
 
 /**
  * Reusable action buttons for column headers (filter, highlight, pin).
  * Works for both regular columns and the row index column.
+ * When resolvedWidth < 80px, all actions collapse into a single overflow "..." menu.
  */
 export function ColumnHeaderActions({
     enableFiltering = false,
@@ -45,6 +62,9 @@ export function ColumnHeaderActions({
     hasActiveFilter = false,
     hasActiveHighlight = false,
     isPinned = false,
+    enableSorting = false,
+    sortDirection = null,
+    onSortClick,
     onFilterClick,
     onHighlightClick,
     onPinClick,
@@ -53,9 +73,209 @@ export function ColumnHeaderActions({
     pinnedTitle = 'Unpin column',
     unpinnedTitle = 'Pin column',
     className,
+    resolvedWidth,
+    enableDuplicateCheck = false,
+    hasDuplicateCheck = false,
+    onDuplicateCheckClick,
 }: ColumnHeaderActionsProps) {
+    const [overflowOpen, setOverflowOpen] = useState(false);
+    const overflowRef = useRef<HTMLDivElement>(null);
+    const triggerRef = useRef<HTMLButtonElement>(null);
+    const [dropdownPos, setDropdownPos] = useState<{ top: number; right: number } | null>(null);
+
+    const isCompact = resolvedWidth !== undefined && resolvedWidth < 80;
+
+    useEffect(() => {
+        if (!overflowOpen) return;
+        const handler = (e: MouseEvent) => {
+            if (
+                overflowRef.current &&
+                !overflowRef.current.contains(e.target as Node) &&
+                triggerRef.current &&
+                !triggerRef.current.contains(e.target as Node)
+            ) {
+                setOverflowOpen(false);
+            }
+        };
+        document.addEventListener('mousedown', handler);
+        return () => document.removeEventListener('mousedown', handler);
+    }, [overflowOpen]);
+
+    const openOverflow = (e: React.MouseEvent) => {
+        e.stopPropagation();
+        if (!overflowOpen && triggerRef.current) {
+            const rect = triggerRef.current.getBoundingClientRect();
+            setDropdownPos({
+                top: rect.bottom + window.scrollY + 4,
+                right: window.innerWidth - rect.right - window.scrollX,
+            });
+        }
+        setOverflowOpen((prev) => !prev);
+    };
+
+    if (isCompact) {
+        return (
+            <div className={cn('flex items-center', className)}>
+                <button
+                    ref={triggerRef}
+                    type="button"
+                    onClick={openOverflow}
+                    className="p-0.5 hover:bg-gray-200 rounded text-gray-400 opacity-0 group-hover:opacity-100 transition-opacity"
+                    title="Column actions"
+                >
+                    <HiDotsVertical className="h-3 w-3" />
+                </button>
+
+                {overflowOpen &&
+                    dropdownPos &&
+                    createPortal(
+                        <div
+                            ref={overflowRef}
+                            style={{
+                                position: 'absolute',
+                                top: dropdownPos.top,
+                                right: dropdownPos.right,
+                            }}
+                            className="bg-white border border-gray-200 shadow-lg rounded-md py-1 w-44 z-[9999]"
+                        >
+                            {enableSorting && onSortClick && (
+                                <button
+                                    type="button"
+                                    onClick={(e) => {
+                                        e.stopPropagation();
+                                        onSortClick();
+                                        setOverflowOpen(false);
+                                    }}
+                                    className={cn(
+                                        'flex items-center gap-2 w-full px-3 py-1.5 text-xs hover:bg-gray-100 text-left',
+                                        sortDirection ? 'text-blue-600' : 'text-gray-700'
+                                    )}
+                                >
+                                    {sortDirection === 'desc' ? (
+                                        <HiSortDescending className="h-3.5 w-3.5 shrink-0" />
+                                    ) : (
+                                        <HiSortAscending className="h-3.5 w-3.5 shrink-0" />
+                                    )}
+                                    {sortDirection === 'asc'
+                                        ? 'Sorted ascending'
+                                        : sortDirection === 'desc'
+                                          ? 'Sorted descending'
+                                          : 'Sort'}
+                                </button>
+                            )}
+
+                            {enableFiltering && onFilterClick && (
+                                <button
+                                    type="button"
+                                    onClick={(e) => {
+                                        e.stopPropagation();
+                                        onFilterClick();
+                                        setOverflowOpen(false);
+                                    }}
+                                    className={cn(
+                                        'flex items-center gap-2 w-full px-3 py-1.5 text-xs hover:bg-gray-100 text-left',
+                                        hasActiveFilter ? 'text-blue-600' : 'text-gray-700'
+                                    )}
+                                >
+                                    <HiFilter className="h-3.5 w-3.5 shrink-0" />
+                                    Filter
+                                    {hasActiveFilter && (
+                                        <span className="ml-auto h-1.5 w-1.5 rounded-full bg-blue-500 shrink-0" />
+                                    )}
+                                </button>
+                            )}
+
+                            {enableHighlighting && onHighlightClick && (
+                                <button
+                                    type="button"
+                                    onClick={(e) => {
+                                        e.stopPropagation();
+                                        onHighlightClick();
+                                        setOverflowOpen(false);
+                                    }}
+                                    className={cn(
+                                        'flex items-center gap-2 w-full px-3 py-1.5 text-xs hover:bg-gray-100 text-left',
+                                        hasActiveHighlight ? 'text-amber-500' : 'text-gray-700'
+                                    )}
+                                >
+                                    <AiFillHighlight className="h-3.5 w-3.5 shrink-0" />
+                                    Highlight
+                                </button>
+                            )}
+
+                            {enablePinning && onPinClick && (
+                                <button
+                                    type="button"
+                                    onClick={(e) => {
+                                        e.stopPropagation();
+                                        onPinClick();
+                                        setOverflowOpen(false);
+                                    }}
+                                    className={cn(
+                                        'flex items-center gap-2 w-full px-3 py-1.5 text-xs hover:bg-gray-100 text-left',
+                                        isPinned ? 'text-blue-600' : 'text-gray-700'
+                                    )}
+                                >
+                                    {isPinned ? (
+                                        <MdPushPin className="h-3.5 w-3.5 shrink-0" />
+                                    ) : (
+                                        <MdOutlinePushPin className="h-3.5 w-3.5 shrink-0" />
+                                    )}
+                                    {isPinned ? 'Unpin' : 'Pin'}
+                                </button>
+                            )}
+
+                            {enableDuplicateCheck && onDuplicateCheckClick && (
+                                <button
+                                    type="button"
+                                    onClick={(e) => {
+                                        e.stopPropagation();
+                                        onDuplicateCheckClick();
+                                        setOverflowOpen(false);
+                                    }}
+                                    className={cn(
+                                        'flex items-center gap-2 w-full px-3 py-1.5 text-xs hover:bg-gray-100 text-left',
+                                        hasDuplicateCheck ? 'text-purple-600' : 'text-gray-700'
+                                    )}
+                                >
+                                    <HiExclamation className="h-3.5 w-3.5 shrink-0" />
+                                    Check Duplicates
+                                </button>
+                            )}
+                        </div>,
+                        document.body
+                    )}
+            </div>
+        );
+    }
+
+    // Normal (wide) mode: inline icon buttons
     return (
         <div className={cn('flex items-center gap-0.5', className)}>
+            {/* Sort button */}
+            {enableSorting && onSortClick && (
+                <button
+                    type="button"
+                    onClick={(e) => {
+                        e.stopPropagation();
+                        onSortClick();
+                    }}
+                    className={cn(
+                        'p-0.5 hover:bg-gray-200 rounded transition-opacity',
+                        sortDirection
+                            ? 'text-blue-600 opacity-100'
+                            : 'text-gray-400 opacity-0 group-hover:opacity-100'
+                    )}
+                    title={sortDirection === 'asc' ? 'Sorted ascending' : sortDirection === 'desc' ? 'Sorted descending' : 'Sort column'}
+                >
+                    {sortDirection === 'desc' ? (
+                        <HiSortDescending className="h-3 w-3" />
+                    ) : (
+                        <HiSortAscending className="h-3 w-3" />
+                    )}
+                </button>
+            )}
+
             {/* Filter button */}
             {enableFiltering && onFilterClick && (
                 <button
@@ -119,6 +339,26 @@ export function ColumnHeaderActions({
                     )}
                 </button>
             )}
+
+            {/* Duplicate check button */}
+            {enableDuplicateCheck && onDuplicateCheckClick && (
+                <button
+                    type="button"
+                    onClick={(e) => {
+                        e.stopPropagation();
+                        onDuplicateCheckClick();
+                    }}
+                    className={cn(
+                        'p-0.5 hover:bg-gray-200 rounded transition-opacity',
+                        hasDuplicateCheck
+                            ? 'text-purple-600 opacity-100'
+                            : 'text-gray-400 opacity-0 group-hover:opacity-100'
+                    )}
+                    title="Check duplicates"
+                >
+                    <HiExclamation className="h-3 w-3" />
+                </button>
+            )}
         </div>
     );
 }