@startsimpli/ui 0.1.0

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

@@ -0,0 +1,92 @@
+'use client'
+
+import { useState, useCallback, useEffect } from 'react'
+import { ColumnVisibilityState } from '../types'
+
+export interface UseColumnVisibilityOptions {
+  defaultVisibility?: ColumnVisibilityState
+  persistKey?: string
+  onVisibilityChange?: (visibility: ColumnVisibilityState) => void
+}
+
+export function useColumnVisibility({
+  defaultVisibility = {},
+  persistKey,
+  onVisibilityChange
+}: UseColumnVisibilityOptions = {}) {
+  const [columnVisibility, setColumnVisibility] = useState<ColumnVisibilityState>(() => {
+    if (persistKey && typeof window !== 'undefined') {
+      const stored = localStorage.getItem(`column-visibility-${persistKey}`)
+      if (stored) {
+        try {
+          return JSON.parse(stored)
+        } catch {
+          return defaultVisibility
+        }
+      }
+    }
+    return defaultVisibility
+  })
+
+  useEffect(() => {
+    if (persistKey && typeof window !== 'undefined') {
+      localStorage.setItem(`column-visibility-${persistKey}`, JSON.stringify(columnVisibility))
+    }
+    onVisibilityChange?.(columnVisibility)
+  }, [columnVisibility, persistKey, onVisibilityChange])
+
+  const toggleColumn = useCallback((columnId: string) => {
+    setColumnVisibility((prev) => ({
+      ...prev,
+      [columnId]: !(prev[columnId] ?? true)
+    }))
+  }, [])
+
+  const showColumn = useCallback((columnId: string) => {
+    setColumnVisibility((prev) => ({
+      ...prev,
+      [columnId]: true
+    }))
+  }, [])
+
+  const hideColumn = useCallback((columnId: string) => {
+    setColumnVisibility((prev) => ({
+      ...prev,
+      [columnId]: false
+    }))
+  }, [])
+
+  const showAllColumns = useCallback(() => {
+    setColumnVisibility({})
+  }, [])
+
+  const hideAllColumns = useCallback((exceptColumns: string[] = []) => {
+    setColumnVisibility((prev) => {
+      const newVisibility: ColumnVisibilityState = {}
+      Object.keys(prev).forEach((key) => {
+        newVisibility[key] = exceptColumns.includes(key)
+      })
+      return newVisibility
+    })
+  }, [])
+
+  const resetVisibility = useCallback(() => {
+    setColumnVisibility(defaultVisibility)
+  }, [defaultVisibility])
+
+  const isColumnVisible = useCallback((columnId: string): boolean => {
+    return columnVisibility[columnId] ?? true
+  }, [columnVisibility])
+
+  return {
+    columnVisibility,
+    setColumnVisibility,
+    toggleColumn,
+    showColumn,
+    hideColumn,
+    showAllColumns,
+    hideAllColumns,
+    resetVisibility,
+    isColumnVisible,
+  }
+}

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

@@ -0,0 +1,53 @@
+import { useState, useCallback } from 'react'
+import { UseFiltersReturn, FilterState } from '../types'
+
+interface UseFiltersProps {
+  initialFilters?: FilterState
+  onChange?: (filters: FilterState) => void
+}
+
+export function useFilters({
+  initialFilters = {},
+  onChange,
+}: UseFiltersProps): UseFiltersReturn {
+  const [filters, setFilters] = useState<FilterState>(initialFilters)
+
+  const setFilter = useCallback((key: string, value: any) => {
+    setFilters((prev) => {
+      const next = { ...prev, [key]: value }
+      onChange?.(next)
+      return next
+    })
+  }, [onChange])
+
+  const clearFilter = useCallback((key: string) => {
+    setFilters((prev) => {
+      const next = { ...prev }
+      delete next[key]
+      onChange?.(next)
+      return next
+    })
+  }, [onChange])
+
+  const clearAllFilters = useCallback(() => {
+    setFilters({})
+    onChange?.({})
+  }, [onChange])
+
+  const hasActiveFilters = useCallback(() => {
+    return Object.keys(filters).length > 0
+  }, [filters])
+
+  const getActiveFilterCount = useCallback(() => {
+    return Object.keys(filters).length
+  }, [filters])
+
+  return {
+    filters,
+    setFilter,
+    clearFilter,
+    clearAllFilters,
+    hasActiveFilters,
+    getActiveFilterCount,
+  }
+}

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

@@ -0,0 +1,120 @@
+import { useState, useCallback, useMemo } from 'react'
+import { UsePaginationReturn } from '../types'
+
+interface UsePaginationProps {
+  totalCount: number
+  initialPageSize?: number
+  initialPage?: number
+  serverSide?: boolean
+  onPageChange?: (page: number) => void
+}
+
+export function usePagination({
+  totalCount,
+  initialPageSize = 25,
+  initialPage = 1,
+  serverSide = false,
+  onPageChange,
+}: UsePaginationProps): UsePaginationReturn {
+  const [currentPage, setCurrentPage] = useState(initialPage)
+  const [pageSize, setPageSize] = useState(initialPageSize)
+
+  const totalPages = useMemo(() => {
+    return Math.max(1, Math.ceil(totalCount / pageSize))
+  }, [totalCount, pageSize])
+
+  const canGoNext = useMemo(() => {
+    return currentPage < totalPages
+  }, [currentPage, totalPages])
+
+  const canGoPrevious = useMemo(() => {
+    return currentPage > 1
+  }, [currentPage])
+
+  const goToPage = useCallback((page: number) => {
+    const validPage = Math.max(1, Math.min(page, totalPages))
+    setCurrentPage(validPage)
+    onPageChange?.(validPage)
+  }, [totalPages, onPageChange])
+
+  const goToFirstPage = useCallback(() => {
+    goToPage(1)
+  }, [goToPage])
+
+  const goToLastPage = useCallback(() => {
+    goToPage(totalPages)
+  }, [goToPage, totalPages])
+
+  const goToNextPage = useCallback(() => {
+    if (canGoNext) {
+      goToPage(currentPage + 1)
+    }
+  }, [canGoNext, currentPage, goToPage])
+
+  const goToPreviousPage = useCallback(() => {
+    if (canGoPrevious) {
+      goToPage(currentPage - 1)
+    }
+  }, [canGoPrevious, currentPage, goToPage])
+
+  const getPageNumbers = useCallback((): (number | '...')[] => {
+    const maxVisible = 7 // Maximum number of page buttons to show
+
+    if (totalPages <= maxVisible) {
+      // Show all pages if total is small
+      return Array.from({ length: totalPages }, (_, i) => i + 1)
+    }
+
+    const pages: (number | '...')[] = []
+
+    // Always show first page
+    pages.push(1)
+
+    if (currentPage > 3) {
+      pages.push('...')
+    }
+
+    // Show pages around current
+    const start = Math.max(2, currentPage - 1)
+    const end = Math.min(totalPages - 1, currentPage + 1)
+
+    for (let i = start; i <= end; i++) {
+      if (!pages.includes(i)) {
+        pages.push(i)
+      }
+    }
+
+    if (currentPage < totalPages - 2) {
+      pages.push('...')
+    }
+
+    // Always show last page
+    if (!pages.includes(totalPages)) {
+      pages.push(totalPages)
+    }
+
+    return pages
+  }, [currentPage, totalPages])
+
+  const getDisplayRange = useCallback(() => {
+    const start = (currentPage - 1) * pageSize + 1
+    const end = Math.min(currentPage * pageSize, totalCount)
+    return { start, end }
+  }, [currentPage, pageSize, totalCount])
+
+  return {
+    currentPage,
+    pageSize,
+    totalPages,
+    totalCount,
+    canGoNext,
+    canGoPrevious,
+    goToPage,
+    goToFirstPage,
+    goToLastPage,
+    goToNextPage,
+    goToPreviousPage,
+    getPageNumbers,
+    getDisplayRange,
+  }
+}

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

@@ -0,0 +1,50 @@
+'use client'
+
+import { useEffect, useState } from 'react'
+
+export interface ResponsiveBreakpoints {
+  mobile: number
+  tablet: number
+  desktop: number
+}
+
+export const DEFAULT_BREAKPOINTS: ResponsiveBreakpoints = {
+  mobile: 768,
+  tablet: 1024,
+  desktop: 1280,
+}
+
+export type ViewMode = 'mobile' | 'tablet' | 'desktop'
+
+export function useResponsive(breakpoints: ResponsiveBreakpoints = DEFAULT_BREAKPOINTS) {
+  const [viewMode, setViewMode] = useState<ViewMode>('desktop')
+  const [windowWidth, setWindowWidth] = useState<number>(0)
+
+  useEffect(() => {
+    const handleResize = () => {
+      const width = window.innerWidth
+      setWindowWidth(width)
+
+      if (width < breakpoints.mobile) {
+        setViewMode('mobile')
+      } else if (width < breakpoints.tablet) {
+        setViewMode('tablet')
+      } else {
+        setViewMode('desktop')
+      }
+    }
+
+    handleResize()
+    window.addEventListener('resize', handleResize)
+    return () => window.removeEventListener('resize', handleResize)
+  }, [breakpoints])
+
+  return {
+    viewMode,
+    windowWidth,
+    isMobile: viewMode === 'mobile',
+    isTablet: viewMode === 'tablet',
+    isDesktop: viewMode === 'desktop',
+    isMobileOrTablet: viewMode === 'mobile' || viewMode === 'tablet',
+  }
+}

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

@@ -0,0 +1,152 @@
+import { useState, useCallback, useEffect, useRef } from 'react'
+import { UseSelectionReturn } from '../types'
+
+interface UseSelectionProps {
+  currentPageData: any[]
+  totalCount: number
+  getRowId: (row: any) => string
+  onSelectionChange?: (ids: Set<string>) => void
+  onSelectAllPages?: (enabled: boolean) => void
+  // External controlled state
+  externalSelectedIds?: Set<string>
+  externalSelectAllPages?: boolean
+}
+
+export function useSelection({
+  currentPageData,
+  totalCount,
+  getRowId,
+  onSelectionChange,
+  onSelectAllPages,
+  externalSelectedIds,
+  externalSelectAllPages,
+}: UseSelectionProps): UseSelectionReturn {
+  const [internalSelectedIds, setInternalSelectedIds] = useState<Set<string>>(new Set())
+  const [internalSelectAllPages, setInternalSelectAllPages] = useState(false)
+
+  // Track if we're in controlled mode
+  const isControlled = externalSelectedIds !== undefined
+
+  // Use external state if provided, otherwise internal
+  const selectedIds = isControlled ? externalSelectedIds : internalSelectedIds
+  const selectAllPages = externalSelectAllPages ?? internalSelectAllPages
+
+  // Store callbacks in refs to avoid stale closures
+  const onSelectionChangeRef = useRef(onSelectionChange)
+  const onSelectAllPagesRef = useRef(onSelectAllPages)
+  useEffect(() => {
+    onSelectionChangeRef.current = onSelectionChange
+    onSelectAllPagesRef.current = onSelectAllPages
+  }, [onSelectionChange, onSelectAllPages])
+
+  // Sync external state to internal when in controlled mode
+  const prevExternalIdsRef = useRef<Set<string> | undefined>()
+  useEffect(() => {
+    if (externalSelectedIds !== undefined && externalSelectedIds !== prevExternalIdsRef.current) {
+      setInternalSelectedIds(new Set(externalSelectedIds))
+      prevExternalIdsRef.current = externalSelectedIds
+    }
+  }, [externalSelectedIds])
+
+  useEffect(() => {
+    if (externalSelectAllPages !== undefined) {
+      setInternalSelectAllPages(externalSelectAllPages)
+    }
+  }, [externalSelectAllPages])
+
+  const toggleRow = useCallback((id: string) => {
+    setInternalSelectedIds(prev => {
+      const next = new Set(prev)
+      if (next.has(id)) {
+        next.delete(id)
+      } else {
+        next.add(id)
+      }
+      // Notify parent after state update
+      onSelectionChangeRef.current?.(next)
+      return next
+    })
+
+    // If we're toggling individual rows, turn off select all pages
+    setInternalSelectAllPages(prev => {
+      if (prev) {
+        onSelectAllPagesRef.current?.(false)
+        return false
+      }
+      return prev
+    })
+  }, [])
+
+  const toggleAll = useCallback(() => {
+    const currentPageIds = currentPageData.map(getRowId)
+
+    setInternalSelectedIds(prev => {
+      const allSelected = currentPageIds.every(id => prev.has(id))
+
+      let next: Set<string>
+      if (allSelected) {
+        // Deselect all on current page
+        next = new Set(prev)
+        currentPageIds.forEach(id => next.delete(id))
+      } else {
+        // Select all on current page
+        next = new Set(prev)
+        currentPageIds.forEach(id => next.add(id))
+      }
+
+      // Notify parent
+      onSelectionChangeRef.current?.(next)
+      return next
+    })
+
+    // Turn off select all pages if toggling individual page
+    setInternalSelectAllPages(prev => {
+      if (prev) {
+        onSelectAllPagesRef.current?.(false)
+        return false
+      }
+      return prev
+    })
+  }, [currentPageData, getRowId])
+
+  const selectAllPagesToggle = useCallback(() => {
+    setInternalSelectAllPages(prev => {
+      const next = !prev
+      // Notify parent
+      onSelectAllPagesRef.current?.(next)
+
+      if (next) {
+        // When selecting all pages, clear individual selections
+        setInternalSelectedIds(new Set())
+        onSelectionChangeRef.current?.(new Set())
+      }
+      return next
+    })
+  }, [])
+
+  const clearSelection = useCallback(() => {
+    // Update internal state
+    setInternalSelectedIds(new Set())
+    setInternalSelectAllPages(false)
+    // Notify parent
+    onSelectionChangeRef.current?.(new Set())
+    onSelectAllPagesRef.current?.(false)
+  }, [])
+
+  const getSelectedCount = useCallback(() => {
+    if (selectAllPages) {
+      return totalCount
+    }
+    return selectedIds.size
+  }, [selectAllPages, selectedIds, totalCount])
+
+  return {
+    selectedIds,
+    selectAllPages,
+    toggleRow,
+    toggleAll,
+    selectAllPagesToggle,
+    clearSelection,
+    getSelectedCount,
+  }
+}

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

@@ -0,0 +1,206 @@
+import { useEffect, useCallback, useRef, useState, RefObject } from 'react'
+
+export interface UseTableKeyboardProps<TData> {
+  data: TData[]
+  getRowId: (row: TData) => string
+  selectedIds?: Set<string>
+  onToggleRow?: (id: string) => void
+  onToggleAll?: () => void
+  onRowClick?: (row: TData) => void
+  onDelete?: (ids: Set<string>) => void
+  tableRef: RefObject<HTMLElement>
+  enabled?: boolean
+}
+
+export interface UseTableKeyboardReturn {
+  focusedRowIndex: number
+  setFocusedRowIndex: (index: number) => void
+  handleKeyDown: (event: React.KeyboardEvent) => void
+}
+
+/**
+ * Hook for handling keyboard navigation in UnifiedTable
+ *
+ * Features:
+ * - Arrow Up/Down: Navigate between rows
+ * - Enter: Expand/click row (trigger onRowClick)
+ * - Space: Toggle row selection
+ * - Tab: Move between interactive elements (native browser behavior)
+ * - Escape: Close menus/dialogs (handled by menu components)
+ * - Ctrl/Cmd+A: Select all rows
+ * - Delete: Trigger delete action if available
+ */
+export function useTableKeyboard<TData>({
+  data,
+  getRowId,
+  selectedIds,
+  onToggleRow,
+  onToggleAll,
+  onRowClick,
+  onDelete,
+  tableRef,
+  enabled = true,
+}: UseTableKeyboardProps<TData>): UseTableKeyboardReturn {
+  // Use state for reactive updates so consumers get re-renders
+  const [focusedRowIndex, setFocusedRowIndexState] = useState<number>(-1)
+  // Keep a ref in sync for use in callbacks to avoid stale closures
+  const focusedRowIndexRef = useRef<number>(-1)
+
+  const setFocusedRowIndex = useCallback((index: number) => {
+    focusedRowIndexRef.current = index
+    setFocusedRowIndexState(index)
+  }, [])
+
+  const handleKeyDown = useCallback((event: React.KeyboardEvent) => {
+    if (!enabled || data.length === 0) return
+
+    const { key, ctrlKey, metaKey, shiftKey } = event
+    const isModifierPressed = ctrlKey || metaKey
+
+    // Ctrl/Cmd + A: Select all rows
+    if (key === 'a' && isModifierPressed && onToggleAll) {
+      event.preventDefault()
+      onToggleAll()
+      return
+    }
+
+    // Delete: Trigger delete action if available
+    if (key === 'Delete' && onDelete && selectedIds && selectedIds.size > 0) {
+      event.preventDefault()
+      onDelete(selectedIds)
+      return
+    }
+
+    // Arrow navigation
+    if (key === 'ArrowDown') {
+      event.preventDefault()
+      const nextIndex = Math.min(focusedRowIndexRef.current + 1, data.length - 1)
+      setFocusedRowIndex(nextIndex)
+
+      // Focus the row element
+      if (tableRef.current) {
+        const rowElement = tableRef.current.querySelector(
+          `[data-row-index="${nextIndex}"]`
+        ) as HTMLElement
+        if (rowElement && typeof rowElement.focus === 'function') {
+          rowElement.focus()
+        }
+      }
+      return
+    }
+
+    if (key === 'ArrowUp') {
+      event.preventDefault()
+      const prevIndex = Math.max(focusedRowIndexRef.current - 1, 0)
+      setFocusedRowIndex(prevIndex)
+
+      // Focus the row element
+      if (tableRef.current) {
+        const rowElement = tableRef.current.querySelector(
+          `[data-row-index="${prevIndex}"]`
+        ) as HTMLElement
+        if (rowElement) {
+          rowElement.focus()
+        }
+      }
+      return
+    }
+
+    // Enter: Trigger row click
+    if (key === 'Enter' && focusedRowIndexRef.current >= 0 && onRowClick) {
+      event.preventDefault()
+      const row = data[focusedRowIndexRef.current]
+      if (row) {
+        onRowClick(row)
+      }
+      return
+    }
+
+    // Space: Toggle row selection
+    if (key === ' ' && focusedRowIndexRef.current >= 0 && onToggleRow) {
+      event.preventDefault()
+      const row = data[focusedRowIndexRef.current]
+      if (row) {
+        const rowId = getRowId(row)
+        onToggleRow(rowId)
+      }
+      return
+    }
+
+    // Home: Focus first row
+    if (key === 'Home') {
+      event.preventDefault()
+      setFocusedRowIndex(0)
+
+      if (tableRef.current) {
+        const rowElement = tableRef.current.querySelector(
+          '[data-row-index="0"]'
+        ) as HTMLElement
+        if (rowElement) {
+          rowElement.focus()
+        }
+      }
+      return
+    }
+
+    // End: Focus last row
+    if (key === 'End') {
+      event.preventDefault()
+      const lastIndex = data.length - 1
+      setFocusedRowIndex(lastIndex)
+
+      if (tableRef.current) {
+        const rowElement = tableRef.current.querySelector(
+          `[data-row-index="${lastIndex}"]`
+        ) as HTMLElement
+        if (rowElement) {
+          rowElement.focus()
+        }
+      }
+      return
+    }
+  }, [
+    enabled,
+    data,
+    getRowId,
+    selectedIds,
+    onToggleRow,
+    onToggleAll,
+    onRowClick,
+    onDelete,
+    tableRef,
+    setFocusedRowIndex,
+  ])
+
+  // Set up keyboard event listener on the table
+  useEffect(() => {
+    if (!enabled || !tableRef.current) return
+
+    const handleKeyboardEvent = (event: KeyboardEvent) => {
+      // Convert native event to React synthetic event shape
+      const syntheticEvent = {
+        key: event.key,
+        ctrlKey: event.ctrlKey,
+        metaKey: event.metaKey,
+        shiftKey: event.shiftKey,
+        preventDefault: () => event.preventDefault(),
+        stopPropagation: () => event.stopPropagation(),
+      } as React.KeyboardEvent
+
+      handleKeyDown(syntheticEvent)
+    }
+
+    const tableElement = tableRef.current
+    tableElement.addEventListener('keydown', handleKeyboardEvent as any)
+
+    return () => {
+      tableElement.removeEventListener('keydown', handleKeyboardEvent as any)
+    }
+  }, [enabled, tableRef, handleKeyDown])
+
+  return {
+    focusedRowIndex,
+    setFocusedRowIndex,
+    handleKeyDown,
+  }
+}