@startsimpli/hooks 0.1.1

package/src/index.ts

@@ -0,0 +1,37 @@
+export { useTableFilters } from './useTableFilters'
+
+// Filter types (generic, no domain-specific fields)
+export type {
+  FilterOperator,
+  FilterValue,
+  FilterCondition,
+  FilterGroup,
+  FilterConfig,
+  EncodedFilterState,
+  FilterValidationError,
+  FilterValidationResult,
+} from './filter-types'
+
+// URL filter encoding utilities (pure functions, no React/Next.js dependencies)
+export {
+  encodeFilterConfig,
+  decodeFilterConfig,
+  parseUrlFilters,
+  createSimpleFilter,
+  mergeFilters,
+  getFilterDescription,
+} from './filter-encoding'
+export { useCRUDMutation } from './useCRUDMutation'
+export { useSavedViews } from './useSavedViews'
+export type { SavedView as SavedViewEntry } from './useSavedViews'
+export { useRecentlyViewed } from './useRecentlyViewed'
+export { useWizard } from './useWizard'
+export type { WizardState } from './useWizard'
+export { useCSVImport, useCSVExport } from './useCSV'
+export type {
+  CSVColumnMapping,
+  CSVPreviewResult,
+  CSVImportResult,
+  CSVImportStep,
+  UseCSVImportState,
+} from './useCSV'

package/src/useCRUDMutation.ts

@@ -0,0 +1,26 @@
+import { useMutation, useQueryClient } from '@tanstack/react-query'
+import type { QueryKey, UseMutationOptions, UseMutationResult } from '@tanstack/react-query'
+
+interface UseCRUDMutationOptions<TInput, TOutput> {
+  invalidateKeys: QueryKey[]
+  onSuccess?: (data: TOutput, variables: TInput) => void
+  onError?: (error: Error, variables: TInput) => void
+}
+
+export function useCRUDMutation<TInput, TOutput>(
+  mutationFn: (input: TInput) => Promise<TOutput>,
+  opts: UseCRUDMutationOptions<TInput, TOutput>
+): UseMutationResult<TOutput, Error, TInput> {
+  const queryClient = useQueryClient()
+
+  return useMutation({
+    mutationFn,
+    onSuccess: (data, variables) => {
+      for (const key of opts.invalidateKeys) {
+        queryClient.invalidateQueries({ queryKey: key })
+      }
+      opts.onSuccess?.(data, variables)
+    },
+    onError: opts.onError,
+  })
+}

package/src/useCSV.ts

@@ -0,0 +1,158 @@
+import { useState, useCallback } from 'react'
+
+export interface CSVColumnMapping {
+  csv_column: string
+  target_field: string
+}
+
+export interface CSVPreviewResult<TField extends string = string> {
+  columns: string[]
+  sample_rows: Record<string, string>[]
+  suggested_mappings?: CSVColumnMapping[]
+  total_rows?: number
+}
+
+export interface CSVImportResult {
+  total_rows: number
+  successful: number
+  failed: number
+  errors: Array<{ row: number; message: string }>
+}
+
+export type CSVImportStep = 'upload' | 'mapping' | 'importing' | 'complete'
+
+export interface UseCSVImportOptions<TField extends string = string> {
+  previewFn: (file: File) => Promise<CSVPreviewResult<TField>>
+  importFn: (file: File, mappings: CSVColumnMapping[]) => Promise<CSVImportResult>
+  onSuccess?: (result: CSVImportResult) => void
+}
+
+export interface UseCSVImportState {
+  step: CSVImportStep
+  file: File | null
+  preview: CSVPreviewResult | null
+  mappings: CSVColumnMapping[]
+  result: CSVImportResult | null
+  isLoading: boolean
+  error: string | null
+  handleFileSelect: (file: File) => Promise<void>
+  updateMapping: (csvColumn: string, targetField: string) => void
+  startImport: () => Promise<void>
+  reset: () => void
+  goBack: () => void
+}
+
+export function useCSVImport<TField extends string = string>({
+  previewFn,
+  importFn,
+  onSuccess,
+}: UseCSVImportOptions<TField>): UseCSVImportState {
+  const [step, setStep] = useState<CSVImportStep>('upload')
+  const [file, setFile] = useState<File | null>(null)
+  const [preview, setPreview] = useState<CSVPreviewResult | null>(null)
+  const [mappings, setMappings] = useState<CSVColumnMapping[]>([])
+  const [result, setResult] = useState<CSVImportResult | null>(null)
+  const [isLoading, setIsLoading] = useState(false)
+  const [error, setError] = useState<string | null>(null)
+
+  const handleFileSelect = useCallback(
+    async (selectedFile: File) => {
+      setFile(selectedFile)
+      setError(null)
+      setIsLoading(true)
+      try {
+        const previewData = await previewFn(selectedFile)
+        setPreview(previewData)
+        setMappings(previewData.suggested_mappings ?? [])
+        setStep('mapping')
+      } catch {
+        setError('Failed to preview CSV file')
+      } finally {
+        setIsLoading(false)
+      }
+    },
+    [previewFn]
+  )
+
+  const updateMapping = useCallback((csvColumn: string, targetField: string) => {
+    setMappings((prev) => {
+      const existing = prev.find((m) => m.csv_column === csvColumn)
+      if (existing) {
+        return prev.map((m) =>
+          m.csv_column === csvColumn ? { ...m, target_field: targetField } : m
+        )
+      }
+      return [...prev, { csv_column: csvColumn, target_field: targetField }]
+    })
+  }, [])
+
+  const startImport = useCallback(async () => {
+    if (!file) return
+    setStep('importing')
+    setError(null)
+    try {
+      const importResult = await importFn(file, mappings)
+      setResult(importResult)
+      setStep('complete')
+      onSuccess?.(importResult)
+    } catch {
+      setError('Failed to import CSV')
+      setStep('mapping')
+    }
+  }, [file, mappings, importFn, onSuccess])
+
+  const reset = useCallback(() => {
+    setStep('upload')
+    setFile(null)
+    setPreview(null)
+    setMappings([])
+    setResult(null)
+    setError(null)
+  }, [])
+
+  const goBack = useCallback(() => {
+    if (step === 'mapping') setStep('upload')
+  }, [step])
+
+  return {
+    step,
+    file,
+    preview,
+    mappings,
+    result,
+    isLoading,
+    error,
+    handleFileSelect,
+    updateMapping,
+    startImport,
+    reset,
+    goBack,
+  }
+}
+
+export interface UseCSVExportOptions {
+  exportFn: () => Promise<Blob | string>
+  filename?: string
+}
+
+export function useCSVExport({ exportFn, filename = 'export.csv' }: UseCSVExportOptions) {
+  const [isExporting, setIsExporting] = useState(false)
+
+  const exportCSV = useCallback(async () => {
+    setIsExporting(true)
+    try {
+      const data = await exportFn()
+      const blob = typeof data === 'string' ? new Blob([data], { type: 'text/csv' }) : data
+      const url = URL.createObjectURL(blob)
+      const a = document.createElement('a')
+      a.href = url
+      a.download = filename
+      a.click()
+      URL.revokeObjectURL(url)
+    } finally {
+      setIsExporting(false)
+    }
+  }, [exportFn, filename])
+
+  return { exportCSV, isExporting }
+}

package/src/useRecentlyViewed.ts

@@ -0,0 +1,67 @@
+import { useState, useCallback, useEffect } from 'react'
+
+interface StoredItem<T> {
+  item: T
+  viewedAt: number
+}
+
+export function useRecentlyViewed<T extends { id: string }>(
+  storageKey: string,
+  maxItems: number = 5
+) {
+  const [items, setItems] = useState<StoredItem<T>[]>([])
+
+  // Load from localStorage on mount
+  useEffect(() => {
+    if (typeof window === 'undefined') return
+    try {
+      const raw = localStorage.getItem(storageKey)
+      if (raw) {
+        setItems(JSON.parse(raw) as StoredItem<T>[])
+      }
+    } catch {
+      // Corrupted storage, start fresh
+    }
+  }, [storageKey])
+
+  const persist = useCallback(
+    (updated: StoredItem<T>[]) => {
+      if (typeof window === 'undefined') return
+      try {
+        localStorage.setItem(storageKey, JSON.stringify(updated))
+      } catch {
+        // Storage quota exceeded
+      }
+    },
+    [storageKey]
+  )
+
+  const trackView = useCallback(
+    (item: T) => {
+      setItems(prev => {
+        const deduped = prev.filter(entry => entry.item.id !== item.id)
+        const updated = [{ item, viewedAt: Date.now() }, ...deduped].slice(0, maxItems)
+        persist(updated)
+        return updated
+      })
+    },
+    [maxItems, persist]
+  )
+
+  const clear = useCallback(() => {
+    setItems([])
+    if (typeof window === 'undefined') return
+    try {
+      localStorage.removeItem(storageKey)
+    } catch {
+      // ignore
+    }
+  }, [storageKey])
+
+  return {
+    items: items.map(entry => entry.item),
+    timestamps: items.map(entry => ({ id: entry.item.id, viewedAt: entry.viewedAt })),
+    trackView,
+    clear,
+  }
+}

package/src/useSavedViews.ts

@@ -0,0 +1,117 @@
+import { useState, useEffect, useCallback } from 'react'
+
+export interface SavedView {
+  id: string
+  name: string
+  isDefault?: boolean
+  createdAt?: string
+  [key: string]: unknown
+}
+
+interface SavedViewsState<T extends SavedView> {
+  views: T[]
+  currentViewId: string | null
+  loading: boolean
+  error: string | null
+}
+
+interface UseSavedViewsOptions<T extends SavedView> {
+  resource: string
+  loadFn: (resource: string) => Promise<T[]>
+  saveFn: (resource: string, view: Omit<T, 'id' | 'createdAt'>) => Promise<T>
+  updateFn: (resource: string, viewId: string, updates: Partial<T>) => Promise<T>
+  deleteFn: (resource: string, viewId: string) => Promise<void>
+}
+
+export function useSavedViews<T extends SavedView>({
+  resource,
+  loadFn,
+  saveFn,
+  updateFn,
+  deleteFn,
+}: UseSavedViewsOptions<T>) {
+  const [state, setState] = useState<SavedViewsState<T>>({
+    views: [],
+    currentViewId: null,
+    loading: true,
+    error: null,
+  })
+
+  const fetchViews = useCallback(async () => {
+    setState(prev => ({ ...prev, loading: true, error: null }))
+    try {
+      const views = await loadFn(resource)
+      const defaultView = views.find(v => v.isDefault)
+      setState(prev => ({
+        ...prev,
+        views,
+        currentViewId: defaultView?.id || null,
+        loading: false,
+      }))
+    } catch (error) {
+      setState(prev => ({
+        ...prev,
+        loading: false,
+        error: error instanceof Error ? error.message : 'Failed to load views',
+      }))
+    }
+  }, [resource, loadFn])
+
+  useEffect(() => {
+    fetchViews()
+  }, [fetchViews])
+
+  const saveView = useCallback(
+    async (viewData: Omit<T, 'id' | 'createdAt'>): Promise<T> => {
+      const newView = await saveFn(resource, viewData)
+      setState(prev => ({
+        ...prev,
+        views: [...prev.views, newView],
+        currentViewId: newView.id,
+      }))
+      return newView
+    },
+    [resource, saveFn]
+  )
+
+  const updateView = useCallback(
+    async (viewId: string, updates: Partial<T>): Promise<void> => {
+      await updateFn(resource, viewId, updates)
+      await fetchViews()
+    },
+    [resource, updateFn, fetchViews]
+  )
+
+  const deleteView = useCallback(
+    async (viewId: string): Promise<void> => {
+      await deleteFn(resource, viewId)
+      setState(prev => ({
+        ...prev,
+        views: prev.views.filter(v => v.id !== viewId),
+        currentViewId: prev.currentViewId === viewId ? null : prev.currentViewId,
+      }))
+    },
+    [resource, deleteFn]
+  )
+
+  const loadView = useCallback((viewId: string) => {
+    setState(prev => ({ ...prev, currentViewId: viewId }))
+  }, [])
+
+  const getCurrentView = useCallback((): T | null => {
+    return state.views.find(v => v.id === state.currentViewId) || null
+  }, [state.views, state.currentViewId])
+
+  return {
+    views: state.views,
+    currentViewId: state.currentViewId,
+    loading: state.loading,
+    error: state.error,
+    saveView,
+    updateView,
+    deleteView,
+    loadView,
+    getCurrentView,
+    refreshViews: fetchViews,
+  }
+}

package/src/useTableFilters.ts

@@ -0,0 +1,67 @@
+import { useState, useCallback } from 'react'
+
+interface TableFilterBase {
+  page: number
+  pageSize: number
+  search?: string
+  sortField?: string
+  sortDirection?: 'asc' | 'desc'
+}
+
+type TableFilters<TFilters extends Record<string, unknown>> = TFilters & TableFilterBase
+
+interface UseTableFiltersReturn<TFilters extends Record<string, unknown>> {
+  filters: TableFilters<TFilters>
+  setFilter: <K extends keyof TFilters>(key: K, value: TFilters[K]) => void
+  setPage: (page: number) => void
+  setPageSize: (pageSize: number) => void
+  setSearch: (search: string) => void
+  setSort: (field: string, direction: 'asc' | 'desc') => void
+  resetFilters: () => void
+}
+
+export function useTableFilters<TFilters extends Record<string, unknown>>(
+  initial: TFilters & { page?: number; pageSize?: number; sortField?: string; sortDirection?: 'asc' | 'desc' }
+): UseTableFiltersReturn<TFilters> {
+  const defaultFilters: TableFilters<TFilters> = {
+    page: 1,
+    pageSize: 20,
+    ...initial,
+  } as TableFilters<TFilters>
+
+  const [filters, setFilters] = useState<TableFilters<TFilters>>(defaultFilters)
+
+  const setFilter = useCallback(<K extends keyof TFilters>(key: K, value: TFilters[K]) => {
+    setFilters(prev => ({ ...prev, [key]: value, page: 1 }))
+  }, [])
+
+  const setPage = useCallback((page: number) => {
+    setFilters(prev => ({ ...prev, page }))
+  }, [])
+
+  const setPageSize = useCallback((pageSize: number) => {
+    setFilters(prev => ({ ...prev, pageSize, page: 1 }))
+  }, [])
+
+  const setSearch = useCallback((search: string) => {
+    setFilters(prev => ({ ...prev, search, page: 1 }))
+  }, [])
+
+  const setSort = useCallback((field: string, direction: 'asc' | 'desc') => {
+    setFilters(prev => ({ ...prev, sortField: field, sortDirection: direction }))
+  }, [])
+
+  const resetFilters = useCallback(() => {
+    setFilters(defaultFilters)
+  }, []) // eslint-disable-line react-hooks/exhaustive-deps
+
+  return {
+    filters,
+    setFilter,
+    setPage,
+    setPageSize,
+    setSearch,
+    setSort,
+    resetFilters,
+  }
+}

package/src/useWizard.ts

@@ -0,0 +1,60 @@
+import { useState, useCallback } from 'react'
+
+export interface WizardState<TStep extends string> {
+  currentStep: TStep
+  stepIndex: number
+  totalSteps: number
+  isFirstStep: boolean
+  isLastStep: boolean
+  canGoBack: boolean
+  canGoNext: boolean
+  goTo: (step: TStep) => void
+  next: () => void
+  prev: () => void
+  reset: () => void
+}
+
+export function useWizard<TStep extends string>(
+  steps: readonly TStep[],
+  initialStep?: TStep
+): WizardState<TStep> {
+  const [currentStep, setCurrentStep] = useState<TStep>(initialStep ?? steps[0])
+
+  const stepIndex = steps.indexOf(currentStep)
+  const totalSteps = steps.length
+  const isFirstStep = stepIndex === 0
+  const isLastStep = stepIndex === totalSteps - 1
+
+  const goTo = useCallback(
+    (step: TStep) => {
+      if (steps.includes(step)) setCurrentStep(step)
+    },
+    [steps]
+  )
+
+  const next = useCallback(() => {
+    if (!isLastStep) setCurrentStep(steps[stepIndex + 1])
+  }, [isLastStep, stepIndex, steps])
+
+  const prev = useCallback(() => {
+    if (!isFirstStep) setCurrentStep(steps[stepIndex - 1])
+  }, [isFirstStep, stepIndex, steps])
+
+  const reset = useCallback(() => {
+    setCurrentStep(initialStep ?? steps[0])
+  }, [initialStep, steps])
+
+  return {
+    currentStep,
+    stepIndex,
+    totalSteps,
+    isFirstStep,
+    isLastStep,
+    canGoBack: !isFirstStep,
+    canGoNext: !isLastStep,
+    goTo,
+    next,
+    prev,
+    reset,
+  }
+}