@startsimpli/ui 0.1.0

package/src/components/unified-table/hooks/useTableURL.ts

@@ -0,0 +1,301 @@
+'use client'
+
+import { useCallback, useEffect, useRef } from 'react'
+import { useSearchParams, useRouter, usePathname } from 'next/navigation'
+import { SortState, FilterState } from '../types'
+
+export interface UseTableURLConfig {
+  tableId: string
+  persistToUrl: boolean
+  debounceMs?: number
+}
+
+export interface TableURLState {
+  sortBy: string | null
+  sortDirection: 'asc' | 'desc'
+  filters: FilterState
+  page: number
+  search: string
+}
+
+export interface UseTableURLReturn {
+  // Read state from URL
+  getURLState: () => TableURLState
+
+  // Update individual state pieces
+  setSortToURL: (sort: SortState) => void
+  setFiltersToURL: (filters: FilterState) => void
+  setPageToURL: (page: number) => void
+  setSearchToURL: (search: string) => void
+
+  // Clear state
+  clearURLState: () => void
+
+  // Check if URL has state
+  hasURLState: () => boolean
+}
+
+/**
+ * Hook for persisting table state to URL query parameters.
+ * Enables shareability and browser navigation for table state.
+ *
+ * URL params are namespaced with tableId prefix:
+ * - {tableId}_sortBy: column ID
+ * - {tableId}_sortDir: 'asc' | 'desc'
+ * - {tableId}_page: current page number
+ * - {tableId}_search: search term
+ * - {tableId}_filter_{filterKey}: filter values (JSON encoded)
+ *
+ * @example
+ * const urlState = useTableURL({
+ *   tableId: 'firms',
+ *   persistToUrl: true,
+ *   debounceMs: 300
+ * })
+ *
+ * // Read initial state from URL
+ * const initialState = urlState.getURLState()
+ *
+ * // Update URL when state changes
+ * urlState.setSortToURL({ sortBy: 'name', sortDirection: 'asc' })
+ * urlState.setSearchToURL('acme')
+ */
+export function useTableURL({
+  tableId,
+  persistToUrl,
+  debounceMs = 300,
+}: UseTableURLConfig): UseTableURLReturn {
+  const searchParams = useSearchParams()
+  const router = useRouter()
+  const pathname = usePathname()
+
+  // Debounce timer ref
+  const debounceTimerRef = useRef<NodeJS.Timeout | null>(null)
+
+  // Track if we're currently applying URL changes to avoid loops
+  const isApplyingURLRef = useRef(false)
+
+  /**
+   * Build namespaced param key
+   */
+  const getParamKey = useCallback((key: string): string => {
+    return `${tableId}_${key}`
+  }, [tableId])
+
+  /**
+   * Parse URL state from current search params
+   */
+  const getURLState = useCallback((): TableURLState => {
+    if (!persistToUrl) {
+      return {
+        sortBy: null,
+        sortDirection: 'asc',
+        filters: {},
+        page: 1,
+        search: '',
+      }
+    }
+
+    const sortBy = searchParams.get(getParamKey('sortBy'))
+    const sortDirection = searchParams.get(getParamKey('sortDir')) as 'asc' | 'desc' | null
+    const page = parseInt(searchParams.get(getParamKey('page')) || '1', 10)
+    const search = searchParams.get(getParamKey('search')) || ''
+
+    // Parse filters (any param starting with tableId_filter_)
+    const filters: FilterState = {}
+    const filterPrefix = getParamKey('filter_')
+
+    searchParams.forEach((value, key) => {
+      if (key.startsWith(filterPrefix)) {
+        const filterKey = key.substring(filterPrefix.length)
+        try {
+          // Try to parse as JSON first (for complex values)
+          filters[filterKey] = JSON.parse(value)
+        } catch {
+          // Fall back to raw string value
+          filters[filterKey] = value
+        }
+      }
+    })
+
+    return {
+      sortBy: sortBy || null,
+      sortDirection: sortDirection || 'asc',
+      filters,
+      page: isNaN(page) || page < 1 ? 1 : page,
+      search,
+    }
+  }, [searchParams, persistToUrl, getParamKey])
+
+  /**
+   * Update URL with new params (debounced)
+   */
+  const updateURL = useCallback((updates: Record<string, string | null>) => {
+    if (!persistToUrl) return
+
+    // Clear existing debounce timer
+    if (debounceTimerRef.current) {
+      clearTimeout(debounceTimerRef.current)
+    }
+
+    // Debounce the URL update
+    debounceTimerRef.current = setTimeout(() => {
+      const newParams = new URLSearchParams(searchParams.toString())
+
+      // Apply updates
+      Object.entries(updates).forEach(([key, value]) => {
+        if (value === null || value === '') {
+          newParams.delete(key)
+        } else {
+          newParams.set(key, value)
+        }
+      })
+
+      // Only update if params actually changed
+      const newParamsString = newParams.toString()
+      const currentParamsString = searchParams.toString()
+
+      if (newParamsString !== currentParamsString) {
+        isApplyingURLRef.current = true
+        const newURL = newParamsString ? `${pathname}?${newParamsString}` : pathname
+        router.replace(newURL, { scroll: false })
+
+        // Reset flag after a short delay
+        setTimeout(() => {
+          isApplyingURLRef.current = false
+        }, 50)
+      }
+    }, debounceMs)
+  }, [persistToUrl, searchParams, pathname, router, debounceMs])
+
+  /**
+   * Update sort state in URL
+   */
+  const setSortToURL = useCallback((sort: SortState) => {
+    if (!persistToUrl) return
+
+    updateURL({
+      [getParamKey('sortBy')]: sort.sortBy,
+      [getParamKey('sortDir')]: sort.sortBy ? sort.sortDirection : null,
+      // Reset to page 1 when sorting changes
+      [getParamKey('page')]: '1',
+    })
+  }, [persistToUrl, updateURL, getParamKey])
+
+  /**
+   * Update filters in URL
+   */
+  const setFiltersToURL = useCallback((filters: FilterState) => {
+    if (!persistToUrl) return
+
+    // Build updates object - clear old filters and set new ones
+    const updates: Record<string, string | null> = {}
+    const filterPrefix = getParamKey('filter_')
+
+    // Clear all existing filter params
+    searchParams.forEach((_, key) => {
+      if (key.startsWith(filterPrefix)) {
+        updates[key] = null
+      }
+    })
+
+    // Set new filter params
+    Object.entries(filters).forEach(([key, value]) => {
+      const paramKey = `${filterPrefix}${key}`
+      if (value === undefined || value === null || value === '') {
+        updates[paramKey] = null
+      } else if (typeof value === 'object') {
+        // Encode complex values as JSON
+        updates[paramKey] = JSON.stringify(value)
+      } else {
+        updates[paramKey] = String(value)
+      }
+    })
+
+    // Reset to page 1 when filters change
+    updates[getParamKey('page')] = '1'
+
+    updateURL(updates)
+  }, [persistToUrl, updateURL, getParamKey, searchParams])
+
+  /**
+   * Update page in URL
+   */
+  const setPageToURL = useCallback((page: number) => {
+    if (!persistToUrl) return
+
+    updateURL({
+      [getParamKey('page')]: page > 1 ? String(page) : null, // Remove param if page 1
+    })
+  }, [persistToUrl, updateURL, getParamKey])
+
+  /**
+   * Update search term in URL
+   */
+  const setSearchToURL = useCallback((search: string) => {
+    if (!persistToUrl) return
+
+    updateURL({
+      [getParamKey('search')]: search || null,
+      // Reset to page 1 when search changes
+      [getParamKey('page')]: '1',
+    })
+  }, [persistToUrl, updateURL, getParamKey])
+
+  /**
+   * Clear all table-related URL params
+   */
+  const clearURLState = useCallback(() => {
+    if (!persistToUrl) return
+
+    const newParams = new URLSearchParams(searchParams.toString())
+    const keysToDelete: string[] = []
+
+    // Find all params for this table
+    newParams.forEach((_, key) => {
+      if (key.startsWith(`${tableId}_`)) {
+        keysToDelete.push(key)
+      }
+    })
+
+    // Delete them
+    keysToDelete.forEach(key => newParams.delete(key))
+
+    const newURL = newParams.toString() ? `${pathname}?${newParams.toString()}` : pathname
+    router.replace(newURL, { scroll: false })
+  }, [persistToUrl, searchParams, pathname, router, tableId])
+
+  /**
+   * Check if URL has any state for this table
+   */
+  const hasURLState = useCallback((): boolean => {
+    if (!persistToUrl) return false
+
+    let hasState = false
+    searchParams.forEach((_, key) => {
+      if (key.startsWith(`${tableId}_`)) {
+        hasState = true
+      }
+    })
+    return hasState
+  }, [persistToUrl, searchParams, tableId])
+
+  // Cleanup debounce timer on unmount
+  useEffect(() => {
+    return () => {
+      if (debounceTimerRef.current) {
+        clearTimeout(debounceTimerRef.current)
+      }
+    }
+  }, [])
+
+  return {
+    getURLState,
+    setSortToURL,
+    setFiltersToURL,
+    setPageToURL,
+    setSearchToURL,
+    clearURLState,
+    hasURLState,
+  }
+}

package/src/components/unified-table/index.ts

@@ -0,0 +1,16 @@
+export { UnifiedTable } from './UnifiedTable'
+export * from './types'
+
+export { MobileView, Card, CardActions } from './components/MobileView'
+export type {
+  MobileViewProps,
+  MobileCardConfig,
+  MobileCardField,
+  MobileCardAction,
+  CardProps,
+  CardActionsProps,
+} from './components/MobileView'
+export { MOBILE_BREAKPOINT } from './components/MobileView'
+
+export * from './hooks'
+export * from './utils'

package/src/components/unified-table/types.ts

@@ -0,0 +1,393 @@
+import { ReactNode } from 'react'
+import { LucideIcon } from 'lucide-react'
+
+// Core table configuration
+export interface UnifiedTableProps<TData> {
+  // Data & Columns
+  data: TData[]
+  columns: ColumnConfig<TData>[]
+
+  // Identification
+  tableId: string
+  getRowId: (row: TData) => string
+
+  // Pagination
+  pagination?: PaginationConfig
+
+  // Selection
+  selection?: SelectionConfig
+
+  // Filters
+  filters?: FiltersConfig
+
+  // Bulk Actions
+  bulkActions?: BulkAction[]
+
+  // Row Actions
+  rowActions?: RowAction<TData>[]
+
+  // Search
+  search?: SearchConfig
+
+  // Sorting
+  sorting?: SortingConfig
+
+  // Column Visibility
+  columnVisibility?: ColumnVisibilityConfig
+
+  // Column Reordering
+  columnReorder?: ColumnReorderConfig
+
+  // Column Resizing
+  columnResize?: ColumnResizeConfig
+
+  // Inline Editing
+  inlineEdit?: InlineEditConfig<TData>
+
+  // Saved Views
+  savedViews?: SavedViewsConfig
+
+  // URL Persistence
+  urlPersistence?: URLPersistenceConfig
+
+  // Export
+  export?: ExportConfig
+
+  // Navigation
+  onRowClick?: (row: TData) => void
+
+  // Mobile
+  mobileConfig?: MobileCardConfig<TData>
+
+  // Loading States
+  loading?: boolean
+  loadingRows?: Set<string>
+
+  // Customization
+  className?: string
+  emptyState?: ReactNode
+  errorState?: ReactNode
+}
+
+// Column Configuration
+export interface ColumnConfig<TData> {
+  id: string
+  header: string | ((props: any) => ReactNode)
+  accessorKey?: string
+  accessorFn?: (row: TData) => any
+  cell?: (row: TData) => ReactNode
+  sortable?: boolean
+  sortingFn?: (a: TData, b: TData) => number
+  width?: string | number
+  minWidth?: string | number
+  maxWidth?: string | number
+  mobilePrimary?: boolean
+  mobileSecondary?: boolean
+  hideOnMobile?: boolean
+  hideable?: boolean // Whether this column can be hidden (default: true)
+  editable?: boolean // Whether this column can be edited inline (default: false)
+  editType?: 'text' | 'number' | 'select' | 'date' // Type of editor to use
+  editOptions?: string[] // Options for select type
+  validate?: (value: any, row: TData) => string | null // Validation function (returns error message or null)
+}
+
+// Pagination Configuration
+export interface PaginationConfig {
+  enabled: boolean
+  pageSize: number
+  totalCount: number
+  currentPage: number
+  serverSide: boolean
+  onPageChange: (page: number) => void
+}
+
+// Selection Configuration
+export interface SelectionConfig {
+  enabled: boolean
+  selectAllPages?: boolean
+  selectedIds?: Set<string>
+  onSelectionChange?: (ids: Set<string>) => void
+  onSelectAllPages?: (enabled: boolean) => void
+  renderSelectionCell?: (row: any) => ReactNode
+}
+
+// Filter Configuration
+export interface FiltersConfig {
+  enabled: boolean
+  position: 'top' | 'side'
+  collapsible: boolean
+  config: FilterConfig
+  value: FilterState
+  onChange: (filters: FilterState) => void
+  presets?: FilterPreset[]
+  showPresets?: boolean // Show preset chips in toolbar (default: true if presets provided)
+}
+
+export interface FilterConfig {
+  sections: FilterSection[]
+}
+
+export interface FilterSection {
+  id: string
+  type: 'chips' | 'buckets' | 'dropdown' | 'search' | 'range' | 'date' | 'collapsible' | 'custom'
+  label?: string
+  filters?: FilterItem[]
+  buckets?: FilterBucket[]
+  // Custom filter handler for complex filter logic (type: 'custom')
+  customFilter?: CustomFilterHandler
+}
+
+export interface CustomFilterHandler {
+  // Render the custom filter UI
+  render: (value: any, onChange: (value: any) => void) => ReactNode
+  // Apply filter to data (client-side filtering)
+  apply?: <TData>(data: TData[], filterValue: any) => TData[]
+  // Convert filter value to API query params (server-side filtering)
+  toApiParams?: (filterValue: any) => Record<string, string>
+  // Default value for the filter
+  defaultValue?: any
+  // Check if filter is active (for showing clear button, etc.)
+  isActive?: (value: any) => boolean
+}
+
+export interface FilterItem {
+  id: string
+  label: string
+  type?: 'chips' | 'dropdown' | 'search' | 'checkbox'
+  options?: string[]
+  multiple?: boolean
+}
+
+export interface FilterBucket {
+  label: string
+  min: number
+  max: number
+}
+
+export interface FilterState {
+  [key: string]: any
+}
+
+export interface FilterPreset {
+  id: string
+  label: string
+  icon?: LucideIcon
+  filters: FilterState
+  description?: string // Tooltip text
+}
+
+// Bulk Actions
+export interface BulkAction {
+  id: string
+  label: string
+  icon: LucideIcon
+  variant: 'default' | 'gradient-purple' | 'gradient-green' | 'gradient-indigo' | 'gradient-orange' | 'gradient-blue'
+  onClick: (selectedIds: Set<string>) => Promise<void> | void
+  maxSelection?: number
+  confirmMessage?: string
+  disabled?: (selectedIds: Set<string>) => boolean
+}
+
+// Row Actions
+export interface RowAction<TData> {
+  id: string
+  label: string
+  icon?: LucideIcon
+  onClick: (row: TData) => void
+  disabled?: (row: TData) => boolean
+  destructive?: boolean
+  separator?: boolean
+}
+
+// Search Configuration
+export interface SearchConfig {
+  enabled: boolean
+  placeholder: string
+  value: string
+  onChange: (value: string) => void
+  debounceMs?: number
+  autoFocus?: boolean
+  preserveFocus?: boolean
+}
+
+// Sorting Configuration
+export interface SortingConfig {
+  enabled: boolean
+  serverSide: boolean
+  value?: SortState
+  onChange?: (sort: SortState) => void
+}
+
+export interface SortState {
+  sortBy: string | null
+  sortDirection: 'asc' | 'desc'
+}
+
+// URL Persistence Configuration
+export interface URLPersistenceConfig {
+  enabled: boolean
+  debounceMs?: number
+}
+
+// Column Visibility Configuration
+export interface ColumnVisibilityConfig {
+  enabled: boolean
+  defaultVisible?: string[] // Column IDs that are visible by default (if not set, all are visible)
+  alwaysVisible?: string[] // Column IDs that cannot be hidden
+  persistKey?: string // localStorage key to persist visibility state
+}
+
+export interface ColumnVisibilityState {
+  [columnId: string]: boolean
+}
+
+// Column Reorder Configuration
+export interface ColumnReorderConfig {
+  enabled: boolean
+  initialOrder?: string[] | null // Initial column order (from saved preferences)
+  onOrderChange?: (order: string[]) => void // Callback when order changes (for persistence)
+}
+
+// Column Resize Configuration
+export interface ColumnResizeConfig {
+  enabled: boolean
+  initialWidths?: { [columnId: string]: number } | null // Initial column widths (from saved preferences)
+  minWidth?: number // Minimum column width in pixels (default: 50)
+  onWidthChange?: (widths: { [columnId: string]: number }) => void // Callback when widths change
+}
+
+// Inline Edit Configuration
+export interface InlineEditConfig<TData> {
+  enabled: boolean
+  onSave: (rowId: string, columnId: string, value: any, row: TData) => Promise<void> // Save callback
+  onCancel?: () => void // Cancel callback
+  optimisticUpdate?: boolean // Apply changes immediately before save completes (default: true)
+}
+
+// Saved View Configuration
+export interface SavedView {
+  id: string
+  name: string
+  isDefault?: boolean
+  createdAt: string
+  // View settings
+  columnVisibility?: { [columnId: string]: boolean }
+  columnOrder?: string[]
+  sortBy?: string | null
+  sortDirection?: 'asc' | 'desc'
+  filters?: { [key: string]: any }
+  pageSize?: number
+}
+
+export interface SavedViewsConfig {
+  enabled: boolean
+  views?: SavedView[] // Initial saved views
+  currentViewId?: string | null // Currently active view
+  onSaveView: (view: Omit<SavedView, 'id' | 'createdAt'>) => Promise<SavedView> // Save a new view
+  onUpdateView?: (viewId: string, updates: Partial<SavedView>) => Promise<void> // Update existing view
+  onDeleteView?: (viewId: string) => Promise<void> // Delete a view
+  onLoadView?: (viewId: string) => void // Called when user loads a view
+  getCurrentViewState?: () => Omit<SavedView, 'id' | 'name' | 'createdAt'> // Get current table state for saving
+}
+
+// Export Configuration
+export interface ExportConfig {
+  enabled: boolean
+  baseFilename?: string // Base filename for exports (default: 'export')
+  formats?: ('csv' | 'excel')[] // Available export formats (default: both)
+  showProgress?: boolean // Show progress during export (default: true)
+  onExportStart?: (format: 'csv' | 'excel', scope: 'all' | 'filtered' | 'selected') => void
+  onExportComplete?: (format: 'csv' | 'excel', scope: 'all' | 'filtered' | 'selected', rowCount: number) => void
+  onExportError?: (error: Error) => void
+}
+
+// Mobile Card Configuration
+export interface MobileCardConfig<TData> {
+  titleKey: string
+  subtitleKey?: string
+  descriptionKey?: string
+  primaryFields: string[]
+  secondaryFields?: string[]
+  renderCustomContent?: (row: TData) => ReactNode
+}
+
+// Internal State Types
+export interface TableState<TData> {
+  data: TData[]
+  filteredData: TData[]
+  displayedData: TData[]
+
+  // Pagination
+  currentPage: number
+  pageSize: number
+  totalPages: number
+  totalCount: number
+
+  // Selection
+  selectedIds: Set<string>
+  selectAllPages: boolean
+
+  // Filters
+  activeFilters: FilterState
+
+  // Sorting
+  sortBy: string | null
+  sortDirection: 'asc' | 'desc'
+
+  // Search
+  searchTerm: string
+  debouncedSearchTerm: string
+
+  // UI
+  loading: boolean
+  loadingRows: Set<string>
+  error: Error | null
+  viewMode: 'table' | 'card'
+}
+
+// Hook Return Types
+export interface UseTableStateReturn<TData> {
+  state: TableState<TData>
+  setData: (data: TData[]) => void
+  setPage: (page: number) => void
+  setPageSize: (size: number) => void
+  setLoading: (loading: boolean) => void
+  setLoadingRows: (ids: Set<string>) => void
+  setError: (error: Error | null) => void
+  setViewMode: (mode: 'table' | 'card') => void
+}
+
+export interface UseSelectionReturn {
+  selectedIds: Set<string>
+  selectAllPages: boolean
+  toggleRow: (id: string) => void
+  toggleAll: () => void
+  selectAllPagesToggle: () => void
+  clearSelection: () => void
+  getSelectedCount: () => number
+}
+
+export interface UsePaginationReturn {
+  currentPage: number
+  pageSize: number
+  totalPages: number
+  totalCount: number
+  canGoNext: boolean
+  canGoPrevious: boolean
+  goToPage: (page: number) => void
+  goToFirstPage: () => void
+  goToLastPage: () => void
+  goToNextPage: () => void
+  goToPreviousPage: () => void
+  getPageNumbers: () => (number | '...')[]
+  getDisplayRange: () => { start: number; end: number }
+}
+
+export interface UseFiltersReturn {
+  filters: FilterState
+  setFilter: (key: string, value: any) => void
+  clearFilter: (key: string) => void
+  clearAllFilters: () => void
+  hasActiveFilters: () => boolean
+  getActiveFilterCount: () => number
+}