@xcelsior/ui-spreadsheets 1.0.1

package/src/hooks/useSpreadsheetFiltering.ts

@@ -0,0 +1,379 @@
+import { useCallback, useMemo, useState } from 'react';
+import type { SpreadsheetColumn, SpreadsheetColumnFilter, SpreadsheetSortConfig } from '../types';
+import { isBlankValue } from '../utils';
+
+export interface UseSpreadsheetFilteringOptions<T> {
+    data: T[];
+    columns: SpreadsheetColumn<T>[];
+    onFilterChange?: (filters: Record<string, SpreadsheetColumnFilter>) => void;
+    onSortChange?: (sortConfig: SpreadsheetSortConfig | null) => void;
+    /**
+     * Enable server-side mode. When true, filtering and sorting are skipped
+     * and data is returned as-is (expecting server to handle these operations).
+     * @default false
+     */
+    serverSide?: boolean;
+    /**
+     * Controlled filters state. When provided, filters become controlled by parent.
+     * Use with serverSide mode for server-side filtering.
+     */
+    controlledFilters?: Record<string, SpreadsheetColumnFilter>;
+    /**
+     * Controlled sort configuration. When provided, sorting becomes controlled by parent.
+     * Use with serverSide mode for server-side sorting.
+     */
+    controlledSortConfig?: SpreadsheetSortConfig | null;
+}
+
+export interface UseSpreadsheetFilteringReturn<T> {
+    filters: Record<string, SpreadsheetColumnFilter>;
+    sortConfig: SpreadsheetSortConfig | null;
+    filteredData: T[];
+    activeFilterColumn: string | null;
+    setActiveFilterColumn: (columnId: string | null) => void;
+    handleFilterChange: (columnId: string, filter: SpreadsheetColumnFilter | undefined) => void;
+    handleSort: (columnId: string) => void;
+    clearAllFilters: () => void;
+    hasActiveFilters: boolean;
+}
+
+export function useSpreadsheetFiltering<T extends Record<string, any>>({
+    data,
+    columns,
+    onFilterChange,
+    onSortChange,
+    serverSide = false,
+    controlledFilters,
+    controlledSortConfig,
+}: UseSpreadsheetFilteringOptions<T>): UseSpreadsheetFilteringReturn<T> {
+    // Internal state for uncontrolled mode
+    const [internalFilters, setInternalFilters] = useState<Record<string, SpreadsheetColumnFilter>>(
+        {}
+    );
+    const [internalSortConfig, setInternalSortConfig] = useState<SpreadsheetSortConfig | null>(
+        null
+    );
+    const [activeFilterColumn, setActiveFilterColumn] = useState<string | null>(null);
+
+    // Use controlled state if provided, otherwise use internal state
+    const filters = controlledFilters ?? internalFilters;
+    const sortConfig =
+        controlledSortConfig !== undefined ? controlledSortConfig : internalSortConfig;
+
+    // Helper function to apply text condition filter
+    const applyTextCondition = useCallback(
+        (value: any, condition: { operator: string; value?: string }): boolean => {
+            const strValue = String(value ?? '').toLowerCase();
+            const filterValue = (condition.value ?? '').toLowerCase();
+
+            switch (condition.operator) {
+                case 'contains':
+                    return strValue.includes(filterValue);
+                case 'notContains':
+                    return !strValue.includes(filterValue);
+                case 'equals':
+                    return strValue === filterValue;
+                case 'notEquals':
+                    return strValue !== filterValue;
+                case 'startsWith':
+                    return strValue.startsWith(filterValue);
+                case 'endsWith':
+                    return strValue.endsWith(filterValue);
+                case 'isEmpty':
+                    return isBlankValue(value);
+                case 'isNotEmpty':
+                    return !isBlankValue(value);
+                default:
+                    return true;
+            }
+        },
+        []
+    );
+
+    // Helper function to apply number condition filter
+    const applyNumberCondition = useCallback(
+        (
+            value: any,
+            condition: { operator: string; value?: number; valueTo?: number }
+        ): boolean => {
+            if (condition.operator === 'isEmpty') return isBlankValue(value);
+            if (condition.operator === 'isNotEmpty') return !isBlankValue(value);
+
+            const numValue = typeof value === 'number' ? value : parseFloat(value);
+            if (Number.isNaN(numValue)) return false;
+
+            const filterValue = condition.value;
+            const filterValueTo = condition.valueTo;
+
+            switch (condition.operator) {
+                case 'equals':
+                    return filterValue !== undefined && numValue === filterValue;
+                case 'notEquals':
+                    return filterValue !== undefined && numValue !== filterValue;
+                case 'greaterThan':
+                    return filterValue !== undefined && numValue > filterValue;
+                case 'greaterThanOrEqual':
+                    return filterValue !== undefined && numValue >= filterValue;
+                case 'lessThan':
+                    return filterValue !== undefined && numValue < filterValue;
+                case 'lessThanOrEqual':
+                    return filterValue !== undefined && numValue <= filterValue;
+                case 'between':
+                    return (
+                        filterValue !== undefined &&
+                        filterValueTo !== undefined &&
+                        numValue >= filterValue &&
+                        numValue <= filterValueTo
+                    );
+                default:
+                    return true;
+            }
+        },
+        []
+    );
+
+    // Helper function to apply date condition filter
+    const applyDateCondition = useCallback(
+        (
+            value: any,
+            condition: { operator: string; value?: string; valueTo?: string }
+        ): boolean => {
+            if (condition.operator === 'isEmpty') return isBlankValue(value);
+            if (condition.operator === 'isNotEmpty') return !isBlankValue(value);
+
+            const dateValue = value ? new Date(value) : null;
+            if (!dateValue || Number.isNaN(dateValue.getTime())) return false;
+
+            const today = new Date();
+            today.setHours(0, 0, 0, 0);
+
+            const getStartOfWeek = (date: Date) => {
+                const d = new Date(date);
+                const day = d.getDay();
+                const diff = d.getDate() - day;
+                return new Date(d.setDate(diff));
+            };
+
+            const getStartOfMonth = (date: Date) =>
+                new Date(date.getFullYear(), date.getMonth(), 1);
+            const getStartOfYear = (date: Date) => new Date(date.getFullYear(), 0, 1);
+
+            switch (condition.operator) {
+                case 'equals':
+                    if (!condition.value) return false;
+                    return dateValue.toDateString() === new Date(condition.value).toDateString();
+                case 'notEquals':
+                    if (!condition.value) return false;
+                    return dateValue.toDateString() !== new Date(condition.value).toDateString();
+                case 'before':
+                    if (!condition.value) return false;
+                    return dateValue < new Date(condition.value);
+                case 'after':
+                    if (!condition.value) return false;
+                    return dateValue > new Date(condition.value);
+                case 'between':
+                    if (!condition.value || !condition.valueTo) return false;
+                    return (
+                        dateValue >= new Date(condition.value) &&
+                        dateValue <= new Date(condition.valueTo)
+                    );
+                case 'today':
+                    return dateValue.toDateString() === today.toDateString();
+                case 'yesterday': {
+                    const yesterday = new Date(today);
+                    yesterday.setDate(yesterday.getDate() - 1);
+                    return dateValue.toDateString() === yesterday.toDateString();
+                }
+                case 'thisWeek': {
+                    const thisWeekStart = getStartOfWeek(today);
+                    const thisWeekEnd = new Date(thisWeekStart);
+                    thisWeekEnd.setDate(thisWeekEnd.getDate() + 7);
+                    return dateValue >= thisWeekStart && dateValue < thisWeekEnd;
+                }
+                case 'lastWeek': {
+                    const lastWeekStart = getStartOfWeek(today);
+                    lastWeekStart.setDate(lastWeekStart.getDate() - 7);
+                    const lastWeekEnd = getStartOfWeek(today);
+                    return dateValue >= lastWeekStart && dateValue < lastWeekEnd;
+                }
+                case 'thisMonth': {
+                    const thisMonthStart = getStartOfMonth(today);
+                    const thisMonthEnd = new Date(today.getFullYear(), today.getMonth() + 1, 1);
+                    return dateValue >= thisMonthStart && dateValue < thisMonthEnd;
+                }
+                case 'lastMonth': {
+                    const lastMonthStart = new Date(today.getFullYear(), today.getMonth() - 1, 1);
+                    const lastMonthEnd = getStartOfMonth(today);
+                    return dateValue >= lastMonthStart && dateValue < lastMonthEnd;
+                }
+                case 'thisYear': {
+                    const thisYearStart = getStartOfYear(today);
+                    const thisYearEnd = new Date(today.getFullYear() + 1, 0, 1);
+                    return dateValue >= thisYearStart && dateValue < thisYearEnd;
+                }
+                default:
+                    return true;
+            }
+        },
+        []
+    );
+
+    // Filter and sort data (skip in server-side mode)
+    const filteredData = useMemo(() => {
+        if (!data || !Array.isArray(data)) return [];
+
+        // In server-side mode, return data as-is (server handles filtering/sorting)
+        if (serverSide) {
+            return data;
+        }
+
+        if (!columns || !Array.isArray(columns)) return data;
+        let result = [...data];
+
+        // Apply filters
+        for (const [columnId, filter] of Object.entries(filters)) {
+            if (!filter) continue;
+
+            const column = columns.find((c) => c.id === columnId);
+            if (!column) continue;
+
+            result = result.filter((row) => {
+                const value = column.getValue ? column.getValue(row) : row[columnId];
+
+                // Handle blanks filter
+                if (filter.includeBlanks && isBlankValue(value)) {
+                    return true;
+                }
+                if (filter.excludeBlanks && isBlankValue(value)) {
+                    return false;
+                }
+
+                // Text condition filter (advanced)
+                if (filter.textCondition) {
+                    return applyTextCondition(value, filter.textCondition);
+                }
+
+                // Number condition filter (advanced)
+                if (filter.numberCondition) {
+                    return applyNumberCondition(value, filter.numberCondition);
+                }
+
+                // Date condition filter (advanced)
+                if (filter.dateCondition) {
+                    return applyDateCondition(value, filter.dateCondition);
+                }
+
+                // Text/selected values filter (legacy and value-based)
+                if (filter.selectedValues && filter.selectedValues.length > 0) {
+                    const strValue = String(value ?? '');
+                    return filter.selectedValues.includes(strValue);
+                }
+
+                // Range filter (legacy)
+                if (filter.min !== undefined || filter.max !== undefined) {
+                    const numValue = typeof value === 'number' ? value : parseFloat(value);
+                    if (Number.isNaN(numValue)) return false;
+                    if (filter.min !== undefined && numValue < Number(filter.min)) return false;
+                    if (filter.max !== undefined && numValue > Number(filter.max)) return false;
+                }
+
+                return true;
+            });
+        }
+
+        // Apply sorting
+        if (sortConfig) {
+            const column = columns.find((c) => c.id === sortConfig.columnId);
+            result.sort((a, b) => {
+                const aValue = column?.getValue ? column.getValue(a) : a[sortConfig.columnId];
+                const bValue = column?.getValue ? column.getValue(b) : b[sortConfig.columnId];
+
+                if (aValue === null || aValue === undefined) return 1;
+                if (bValue === null || bValue === undefined) return -1;
+
+                if (typeof aValue === 'string' && typeof bValue === 'string') {
+                    return sortConfig.direction === 'asc'
+                        ? aValue.localeCompare(bValue)
+                        : bValue.localeCompare(aValue);
+                }
+
+                return sortConfig.direction === 'asc'
+                    ? aValue < bValue
+                        ? -1
+                        : aValue > bValue
+                          ? 1
+                          : 0
+                    : aValue > bValue
+                      ? -1
+                      : aValue < bValue
+                        ? 1
+                        : 0;
+            });
+        }
+
+        return result;
+    }, [
+        data,
+        filters,
+        sortConfig,
+        columns,
+        serverSide,
+        applyDateCondition,
+        applyNumberCondition,
+        applyTextCondition,
+    ]);
+
+    const handleFilterChange = useCallback(
+        (columnId: string, filter: SpreadsheetColumnFilter | undefined) => {
+            const newFilters = { ...filters };
+            if (filter) {
+                newFilters[columnId] = filter;
+            } else {
+                delete newFilters[columnId];
+            }
+            // Only update internal state if not controlled
+            if (controlledFilters === undefined) {
+                setInternalFilters(newFilters);
+            }
+            onFilterChange?.(newFilters);
+        },
+        [filters, onFilterChange, controlledFilters]
+    );
+
+    const handleSort = useCallback(
+        (columnId: string) => {
+            const newSortConfig: SpreadsheetSortConfig =
+                sortConfig?.columnId === columnId
+                    ? { columnId, direction: sortConfig.direction === 'asc' ? 'desc' : 'asc' }
+                    : { columnId, direction: 'asc' };
+            // Only update internal state if not controlled
+            if (controlledSortConfig === undefined) {
+                setInternalSortConfig(newSortConfig);
+            }
+            onSortChange?.(newSortConfig);
+        },
+        [sortConfig, onSortChange, controlledSortConfig]
+    );
+
+    const clearAllFilters = useCallback(() => {
+        // Only update internal state if not controlled
+        if (controlledFilters === undefined) {
+            setInternalFilters({});
+        }
+        onFilterChange?.({});
+    }, [onFilterChange, controlledFilters]);
+
+    const hasActiveFilters = Object.keys(filters).length > 0;
+
+    return {
+        filters,
+        sortConfig,
+        filteredData,
+        activeFilterColumn,
+        setActiveFilterColumn,
+        handleFilterChange,
+        handleSort,
+        clearAllFilters,
+        hasActiveFilters,
+    };
+}

package/src/hooks/useSpreadsheetHighlighting.ts

@@ -0,0 +1,201 @@
+import { useCallback, useState } from 'react';
+import type { CellHighlight } from '../types';
+
+// Standard color palettes
+export const HIGHLIGHT_COLORS = {
+    // Darker colors for rows (more visible)
+    row: [
+        '#fef08a', // yellow
+        '#bbf7d0', // green
+        '#bfdbfe', // blue
+        '#fecaca', // red
+        '#e9d5ff', // purple
+        '#fed7aa', // orange
+        '#a5f3fc', // cyan
+        '#fce7f3', // pink
+        '#d1d5db', // gray
+    ],
+    // Lighter colors for columns/headers (subtle background)
+    column: [
+        '#fef9c3', // yellow-100
+        '#dcfce7', // green-100
+        '#dbeafe', // blue-100
+        '#fee2e2', // red-100
+        '#f3e8ff', // purple-100
+        '#ffedd5', // orange-100
+        '#cffafe', // cyan-100
+        '#fce7f3', // pink-100
+        '#e5e7eb', // gray-200
+    ],
+} as const;
+
+export interface UseSpreadsheetHighlightingOptions {
+    /** External row highlights (controlled mode) */
+    externalRowHighlights?: CellHighlight[];
+    /** Callback when row highlight changes (controlled mode) */
+    onRowHighlight?: (rowId: string | number, color: string | null) => void;
+}
+
+export interface UseSpreadsheetHighlightingReturn {
+    // Cell highlights
+    cellHighlights: CellHighlight[];
+    getCellHighlight: (rowId: string | number, columnId: string) => string | undefined;
+    handleCellHighlightToggle: (rowId: string | number, columnId: string, color?: string) => void;
+
+    // Row highlights
+    rowHighlights: CellHighlight[];
+    getRowHighlight: (rowId: string | number) => CellHighlight | undefined;
+    handleRowHighlightToggle: (rowId: string | number, color: string | null) => void;
+
+    // Column highlights (unified - includes row index)
+    columnHighlights: Record<string, string>;
+    getColumnHighlight: (columnId: string) => string | undefined;
+    handleColumnHighlightToggle: (columnId: string, color: string | null) => void;
+
+    // Picker state management
+    highlightPickerRow: string | number | null;
+    setHighlightPickerRow: (rowId: string | number | null) => void;
+    highlightPickerColumn: string | null;
+    setHighlightPickerColumn: (columnId: string | null) => void;
+
+    // Utility
+    clearAllHighlights: () => void;
+}
+
+// Special column ID for row index
+export const ROW_INDEX_COLUMN_ID = '__row_index__';
+
+export function useSpreadsheetHighlighting({
+    externalRowHighlights,
+    onRowHighlight,
+}: UseSpreadsheetHighlightingOptions = {}): UseSpreadsheetHighlightingReturn {
+    // Cell-level highlights
+    const [cellHighlights, setCellHighlights] = useState<CellHighlight[]>([]);
+
+    // Row-level highlights (internal state, can be overridden by external)
+    const [rowHighlightsInternal, setRowHighlightsInternal] = useState<CellHighlight[]>([]);
+
+    // Column-level highlights (includes row index column using ROW_INDEX_COLUMN_ID)
+    const [columnHighlights, setColumnHighlights] = useState<Record<string, string>>({});
+
+    // Picker states
+    const [highlightPickerRow, setHighlightPickerRow] = useState<string | number | null>(null);
+    const [highlightPickerColumn, setHighlightPickerColumn] = useState<string | null>(null);
+
+    // Use external row highlights if provided, otherwise use internal
+    const rowHighlights = externalRowHighlights || rowHighlightsInternal;
+
+    // Get highlight color for a specific cell
+    const getCellHighlight = useCallback(
+        (rowId: string | number, columnId: string): string | undefined => {
+            return cellHighlights.find((h) => h.rowId === rowId && h.columnId === columnId)?.color;
+        },
+        [cellHighlights]
+    );
+
+    // Toggle cell highlight
+    const handleCellHighlightToggle = useCallback(
+        (rowId: string | number, columnId: string, color: string = '#fef08a') => {
+            setCellHighlights((prev) => {
+                const existing = prev.find((h) => h.rowId === rowId && h.columnId === columnId);
+                if (existing) {
+                    return prev.filter((h) => !(h.rowId === rowId && h.columnId === columnId));
+                }
+                return [...prev, { rowId, columnId, color }];
+            });
+        },
+        []
+    );
+
+    // Get row-level highlight
+    const getRowHighlight = useCallback(
+        (rowId: string | number): CellHighlight | undefined => {
+            return rowHighlights.find((h) => h.rowId === rowId && !h.columnId);
+        },
+        [rowHighlights]
+    );
+
+    // Handle row highlight toggle
+    const handleRowHighlightToggle = useCallback(
+        (rowId: string | number, color: string | null) => {
+            if (onRowHighlight) {
+                // Controlled mode
+                onRowHighlight(rowId, color);
+            } else {
+                // Uncontrolled mode
+                setRowHighlightsInternal((prev) => {
+                    const existing = prev.find((h) => h.rowId === rowId && !h.columnId);
+                    if (existing) {
+                        if (color === null) {
+                            return prev.filter((h) => !(h.rowId === rowId && !h.columnId));
+                        }
+                        return prev.map((h) =>
+                            h.rowId === rowId && !h.columnId ? { ...h, color } : h
+                        );
+                    }
+                    if (color) {
+                        return [...prev, { rowId, color }];
+                    }
+                    return prev;
+                });
+            }
+            setHighlightPickerRow(null);
+        },
+        [onRowHighlight]
+    );
+
+    // Get column highlight (works for both regular columns and row index)
+    const getColumnHighlight = useCallback(
+        (columnId: string): string | undefined => {
+            return columnHighlights[columnId];
+        },
+        [columnHighlights]
+    );
+
+    // Handle column highlight toggle (works for both regular columns and row index)
+    const handleColumnHighlightToggle = useCallback((columnId: string, color: string | null) => {
+        setColumnHighlights((prev) => {
+            const newHighlights = { ...prev };
+            if (color === null) {
+                delete newHighlights[columnId];
+            } else {
+                newHighlights[columnId] = color;
+            }
+            return newHighlights;
+        });
+        setHighlightPickerColumn(null);
+    }, []);
+
+    // Clear all highlights
+    const clearAllHighlights = useCallback(() => {
+        setCellHighlights([]);
+        setRowHighlightsInternal([]);
+        setColumnHighlights({});
+    }, []);
+
+    return {
+        // Cell highlights
+        cellHighlights,
+        getCellHighlight,
+        handleCellHighlightToggle,
+
+        // Row highlights
+        rowHighlights,
+        getRowHighlight,
+        handleRowHighlightToggle,
+
+        // Column highlights
+        columnHighlights,
+        getColumnHighlight,
+        handleColumnHighlightToggle,
+
+        // Picker state
+        highlightPickerRow,
+        setHighlightPickerRow,
+        highlightPickerColumn,
+        setHighlightPickerColumn,
+
+        // Utility
+        clearAllHighlights,
+    };
+}