@startsimpli/hooks 0.1.1

package/src/__tests__/useRecentlyViewed.test.ts

@@ -0,0 +1,142 @@
+import { describe, it, expect, beforeEach, vi } from 'vitest'
+import { renderHook, act } from '@testing-library/react'
+import { useRecentlyViewed } from '../useRecentlyViewed'
+
+// Mock localStorage
+const localStorageMock = (() => {
+  let store: Record<string, string> = {}
+  return {
+    getItem: vi.fn((key: string) => store[key] || null),
+    setItem: vi.fn((key: string, value: string) => {
+      store[key] = value
+    }),
+    removeItem: vi.fn((key: string) => {
+      delete store[key]
+    }),
+    clear: vi.fn(() => {
+      store = {}
+    }),
+  }
+})()
+
+Object.defineProperty(window, 'localStorage', { value: localStorageMock })
+
+describe('useRecentlyViewed', () => {
+  beforeEach(() => {
+    localStorageMock.clear()
+    vi.clearAllMocks()
+  })
+
+  it('starts with empty items', () => {
+    const { result } = renderHook(() =>
+      useRecentlyViewed<{ id: string; name: string }>('test_recent')
+    )
+
+    expect(result.current.items).toEqual([])
+  })
+
+  it('tracks a viewed item', () => {
+    const { result } = renderHook(() =>
+      useRecentlyViewed<{ id: string; name: string }>('test_recent')
+    )
+
+    act(() => {
+      result.current.trackView({ id: '1', name: 'Item 1' })
+    })
+
+    expect(result.current.items).toHaveLength(1)
+    expect(result.current.items[0]).toEqual({ id: '1', name: 'Item 1' })
+  })
+
+  it('deduplicates by id, moving to front', () => {
+    const { result } = renderHook(() =>
+      useRecentlyViewed<{ id: string; name: string }>('test_recent')
+    )
+
+    act(() => {
+      result.current.trackView({ id: '1', name: 'Item 1' })
+    })
+    act(() => {
+      result.current.trackView({ id: '2', name: 'Item 2' })
+    })
+    act(() => {
+      result.current.trackView({ id: '1', name: 'Item 1 Updated' })
+    })
+
+    expect(result.current.items).toHaveLength(2)
+    expect(result.current.items[0]).toEqual({ id: '1', name: 'Item 1 Updated' })
+    expect(result.current.items[1]).toEqual({ id: '2', name: 'Item 2' })
+  })
+
+  it('respects maxItems limit', () => {
+    const { result } = renderHook(() =>
+      useRecentlyViewed<{ id: string; name: string }>('test_recent', 3)
+    )
+
+    act(() => {
+      result.current.trackView({ id: '1', name: 'Item 1' })
+    })
+    act(() => {
+      result.current.trackView({ id: '2', name: 'Item 2' })
+    })
+    act(() => {
+      result.current.trackView({ id: '3', name: 'Item 3' })
+    })
+    act(() => {
+      result.current.trackView({ id: '4', name: 'Item 4' })
+    })
+
+    expect(result.current.items).toHaveLength(3)
+    expect(result.current.items[0].id).toBe('4')
+    expect(result.current.items[2].id).toBe('2')
+  })
+
+  it('persists to localStorage', () => {
+    const { result } = renderHook(() =>
+      useRecentlyViewed<{ id: string; name: string }>('test_recent')
+    )
+
+    act(() => {
+      result.current.trackView({ id: '1', name: 'Item 1' })
+    })
+
+    expect(localStorageMock.setItem).toHaveBeenCalledWith(
+      'test_recent',
+      expect.any(String)
+    )
+  })
+
+  it('clears all items', () => {
+    const { result } = renderHook(() =>
+      useRecentlyViewed<{ id: string; name: string }>('test_recent')
+    )
+
+    act(() => {
+      result.current.trackView({ id: '1', name: 'Item 1' })
+    })
+
+    act(() => {
+      result.current.clear()
+    })
+
+    expect(result.current.items).toEqual([])
+    expect(localStorageMock.removeItem).toHaveBeenCalledWith('test_recent')
+  })
+
+  it('provides timestamps for viewed items', () => {
+    const { result } = renderHook(() =>
+      useRecentlyViewed<{ id: string; name: string }>('test_recent')
+    )
+
+    const before = Date.now()
+    act(() => {
+      result.current.trackView({ id: '1', name: 'Item 1' })
+    })
+    const after = Date.now()
+
+    expect(result.current.timestamps).toHaveLength(1)
+    expect(result.current.timestamps[0].id).toBe('1')
+    expect(result.current.timestamps[0].viewedAt).toBeGreaterThanOrEqual(before)
+    expect(result.current.timestamps[0].viewedAt).toBeLessThanOrEqual(after)
+  })
+})

package/src/__tests__/useSavedViews.test.ts

@@ -0,0 +1,169 @@
+import { describe, it, expect, vi, beforeEach } from 'vitest'
+import { renderHook, act, waitFor } from '@testing-library/react'
+import { useSavedViews } from '../useSavedViews'
+import type { SavedView } from '../useSavedViews'
+
+interface TestView extends SavedView {
+  filters: Record<string, unknown>
+}
+
+function makeView(id: string, name: string, isDefault = false): TestView {
+  return { id, name, isDefault, filters: {}, createdAt: new Date().toISOString() }
+}
+
+function makeOptions(views: TestView[]) {
+  const loadFn = vi.fn().mockResolvedValue(views)
+  const saveFn = vi.fn().mockImplementation((_resource: string, data: Omit<TestView, 'id' | 'createdAt'>) =>
+    Promise.resolve({ ...data, id: 'new-id', createdAt: new Date().toISOString() } as TestView)
+  )
+  const updateFn = vi.fn().mockResolvedValue(undefined)
+  const deleteFn = vi.fn().mockResolvedValue(undefined)
+
+  return {
+    resource: 'test-resource',
+    loadFn,
+    saveFn,
+    updateFn,
+    deleteFn,
+  }
+}
+
+describe('useSavedViews', () => {
+  beforeEach(() => {
+    vi.clearAllMocks()
+  })
+
+  it('loads views on mount', async () => {
+    const views = [makeView('1', 'My View')]
+    const opts = makeOptions(views)
+
+    const { result } = renderHook(() => useSavedViews<TestView>(opts))
+
+    expect(result.current.loading).toBe(true)
+
+    await waitFor(() => {
+      expect(result.current.loading).toBe(false)
+    })
+
+    expect(result.current.views).toHaveLength(1)
+    expect(result.current.views[0].name).toBe('My View')
+  })
+
+  it('sets currentViewId to default view on load', async () => {
+    const views = [makeView('1', 'Normal'), makeView('2', 'Default', true)]
+    const opts = makeOptions(views)
+
+    const { result } = renderHook(() => useSavedViews<TestView>(opts))
+
+    await waitFor(() => expect(result.current.loading).toBe(false))
+
+    expect(result.current.currentViewId).toBe('2')
+  })
+
+  it('sets currentViewId to null when no default view', async () => {
+    const views = [makeView('1', 'No Default')]
+    const opts = makeOptions(views)
+
+    const { result } = renderHook(() => useSavedViews<TestView>(opts))
+
+    await waitFor(() => expect(result.current.loading).toBe(false))
+
+    expect(result.current.currentViewId).toBeNull()
+  })
+
+  it('handles load error', async () => {
+    const opts = {
+      ...makeOptions([]),
+      loadFn: vi.fn().mockRejectedValue(new Error('Network error')),
+    }
+
+    const { result } = renderHook(() => useSavedViews<TestView>(opts))
+
+    await waitFor(() => expect(result.current.loading).toBe(false))
+
+    expect(result.current.error).toBe('Network error')
+    expect(result.current.views).toHaveLength(0)
+  })
+
+  it('saves a new view and adds it to the list', async () => {
+    const opts = makeOptions([])
+    const { result } = renderHook(() => useSavedViews<TestView>(opts))
+
+    await waitFor(() => expect(result.current.loading).toBe(false))
+
+    await act(async () => {
+      await result.current.saveView({ name: 'New View', filters: {}, isDefault: false })
+    })
+
+    expect(result.current.views).toHaveLength(1)
+    expect(result.current.views[0].name).toBe('New View')
+    expect(result.current.currentViewId).toBe('new-id')
+  })
+
+  it('loads a view by setting currentViewId', async () => {
+    const views = [makeView('1', 'First'), makeView('2', 'Second')]
+    const opts = makeOptions(views)
+
+    const { result } = renderHook(() => useSavedViews<TestView>(opts))
+
+    await waitFor(() => expect(result.current.loading).toBe(false))
+
+    act(() => {
+      result.current.loadView('1')
+    })
+
+    expect(result.current.currentViewId).toBe('1')
+  })
+
+  it('getCurrentView returns the current view object', async () => {
+    const views = [makeView('1', 'First'), makeView('2', 'Second')]
+    const opts = makeOptions(views)
+
+    const { result } = renderHook(() => useSavedViews<TestView>(opts))
+
+    await waitFor(() => expect(result.current.loading).toBe(false))
+
+    act(() => {
+      result.current.loadView('1')
+    })
+
+    const current = result.current.getCurrentView()
+    expect(current?.id).toBe('1')
+    expect(current?.name).toBe('First')
+  })
+
+  it('deleteView removes the view from the list', async () => {
+    const views = [makeView('1', 'First'), makeView('2', 'Second')]
+    const opts = makeOptions(views)
+
+    const { result } = renderHook(() => useSavedViews<TestView>(opts))
+
+    await waitFor(() => expect(result.current.loading).toBe(false))
+
+    await act(async () => {
+      await result.current.deleteView('1')
+    })
+
+    expect(opts.deleteFn).toHaveBeenCalledWith('test-resource', '1')
+    expect(result.current.views.find(v => v.id === '1')).toBeUndefined()
+  })
+
+  it('clears currentViewId when deleting the current view', async () => {
+    const views = [makeView('1', 'Current')]
+    const opts = makeOptions(views)
+
+    const { result } = renderHook(() => useSavedViews<TestView>(opts))
+
+    await waitFor(() => expect(result.current.loading).toBe(false))
+
+    act(() => {
+      result.current.loadView('1')
+    })
+
+    await act(async () => {
+      await result.current.deleteView('1')
+    })
+
+    expect(result.current.currentViewId).toBeNull()
+  })
+})

package/src/__tests__/useTableFilters.test.ts

@@ -0,0 +1,110 @@
+import { describe, it, expect } from 'vitest'
+import { renderHook, act } from '@testing-library/react'
+import { useTableFilters } from '../useTableFilters'
+
+describe('useTableFilters', () => {
+  it('initializes with default page and pageSize', () => {
+    const { result } = renderHook(() => useTableFilters({}))
+
+    expect(result.current.filters.page).toBe(1)
+    expect(result.current.filters.pageSize).toBe(20)
+  })
+
+  it('accepts custom initial values', () => {
+    const { result } = renderHook(() =>
+      useTableFilters({
+        page: 2,
+        pageSize: 50,
+        status: 'active',
+      })
+    )
+
+    expect(result.current.filters.page).toBe(2)
+    expect(result.current.filters.pageSize).toBe(50)
+    expect(result.current.filters.status).toBe('active')
+  })
+
+  it('resets page to 1 when setting a filter', () => {
+    const { result } = renderHook(() =>
+      useTableFilters({ stage: '' as string })
+    )
+
+    // Navigate to page 3
+    act(() => {
+      result.current.setPage(3)
+    })
+    expect(result.current.filters.page).toBe(3)
+
+    // Setting a filter should reset page to 1
+    act(() => {
+      result.current.setFilter('stage', 'active')
+    })
+    expect(result.current.filters.page).toBe(1)
+    expect(result.current.filters.stage).toBe('active')
+  })
+
+  it('resets page to 1 when setting search', () => {
+    const { result } = renderHook(() => useTableFilters({}))
+
+    act(() => {
+      result.current.setPage(5)
+    })
+    expect(result.current.filters.page).toBe(5)
+
+    act(() => {
+      result.current.setSearch('test query')
+    })
+    expect(result.current.filters.page).toBe(1)
+    expect(result.current.filters.search).toBe('test query')
+  })
+
+  it('resets page to 1 when changing pageSize', () => {
+    const { result } = renderHook(() => useTableFilters({}))
+
+    act(() => {
+      result.current.setPage(3)
+    })
+
+    act(() => {
+      result.current.setPageSize(50)
+    })
+    expect(result.current.filters.page).toBe(1)
+    expect(result.current.filters.pageSize).toBe(50)
+  })
+
+  it('sets sort without resetting page', () => {
+    const { result } = renderHook(() => useTableFilters({}))
+
+    act(() => {
+      result.current.setPage(3)
+    })
+
+    act(() => {
+      result.current.setSort('name', 'desc')
+    })
+    expect(result.current.filters.page).toBe(3)
+    expect(result.current.filters.sortField).toBe('name')
+    expect(result.current.filters.sortDirection).toBe('desc')
+  })
+
+  it('resets all filters to initial state', () => {
+    const { result } = renderHook(() =>
+      useTableFilters({ status: '' as string })
+    )
+
+    act(() => {
+      result.current.setFilter('status', 'active')
+      result.current.setPage(5)
+      result.current.setSearch('hello')
+    })
+
+    act(() => {
+      result.current.resetFilters()
+    })
+
+    expect(result.current.filters.page).toBe(1)
+    expect(result.current.filters.pageSize).toBe(20)
+    expect(result.current.filters.status).toBe('')
+    expect(result.current.filters.search).toBeUndefined()
+  })
+})

package/src/__tests__/useWizard.test.ts

@@ -0,0 +1,76 @@
+import { describe, it, expect } from 'vitest'
+import { renderHook, act } from '@testing-library/react'
+import { useWizard } from '../useWizard'
+
+const STEPS = ['upload', 'mapping', 'importing', 'complete'] as const
+
+describe('useWizard', () => {
+  it('starts on the initial step', () => {
+    const { result } = renderHook(() => useWizard(STEPS))
+    expect(result.current.currentStep).toBe('upload')
+    expect(result.current.stepIndex).toBe(0)
+    expect(result.current.totalSteps).toBe(4)
+  })
+
+  it('respects a custom initial step', () => {
+    const { result } = renderHook(() => useWizard(STEPS, 'mapping'))
+    expect(result.current.currentStep).toBe('mapping')
+    expect(result.current.stepIndex).toBe(1)
+  })
+
+  it('advances to next step', () => {
+    const { result } = renderHook(() => useWizard(STEPS))
+    act(() => result.current.next())
+    expect(result.current.currentStep).toBe('mapping')
+    expect(result.current.stepIndex).toBe(1)
+  })
+
+  it('goes back to previous step', () => {
+    const { result } = renderHook(() => useWizard(STEPS, 'mapping'))
+    act(() => result.current.prev())
+    expect(result.current.currentStep).toBe('upload')
+  })
+
+  it('does not go before first step', () => {
+    const { result } = renderHook(() => useWizard(STEPS))
+    act(() => result.current.prev())
+    expect(result.current.currentStep).toBe('upload')
+  })
+
+  it('does not go past last step', () => {
+    const { result } = renderHook(() => useWizard(STEPS, 'complete'))
+    act(() => result.current.next())
+    expect(result.current.currentStep).toBe('complete')
+  })
+
+  it('goTo navigates to any step', () => {
+    const { result } = renderHook(() => useWizard(STEPS))
+    act(() => result.current.goTo('importing'))
+    expect(result.current.currentStep).toBe('importing')
+    expect(result.current.stepIndex).toBe(2)
+  })
+
+  it('reset returns to initial step', () => {
+    const { result } = renderHook(() => useWizard(STEPS))
+    act(() => result.current.next())
+    act(() => result.current.next())
+    act(() => result.current.reset())
+    expect(result.current.currentStep).toBe('upload')
+  })
+
+  it('exposes correct flags on first step', () => {
+    const { result } = renderHook(() => useWizard(STEPS))
+    expect(result.current.isFirstStep).toBe(true)
+    expect(result.current.isLastStep).toBe(false)
+    expect(result.current.canGoBack).toBe(false)
+    expect(result.current.canGoNext).toBe(true)
+  })
+
+  it('exposes correct flags on last step', () => {
+    const { result } = renderHook(() => useWizard(STEPS, 'complete'))
+    expect(result.current.isFirstStep).toBe(false)
+    expect(result.current.isLastStep).toBe(true)
+    expect(result.current.canGoBack).toBe(true)
+    expect(result.current.canGoNext).toBe(false)
+  })
+})

package/src/filter-encoding.ts

@@ -0,0 +1,115 @@
+/**
+ * URL filter encoding utilities.
+ *
+ * Provides base64 encode/decode for FilterConfig (so filter state can be
+ * stored in URL query params as compact strings) plus helpers for common
+ * filter operations.
+ *
+ * These are pure functions with no React or Next.js dependencies.
+ */
+
+import type {
+  FilterConfig,
+  FilterCondition,
+  FilterGroup,
+  FilterOperator,
+  FilterValue,
+  EncodedFilterState,
+} from './filter-types'
+
+/**
+ * Encode a FilterConfig to a URL-safe base64 string.
+ */
+export function encodeFilterConfig(config: FilterConfig): string {
+  const json = JSON.stringify(config)
+  return btoa(json).replace(/\+/g, '-').replace(/\//g, '_').replace(/=/g, '')
+}
+
+/**
+ * Decode a URL-safe base64 string back to a FilterConfig.
+ * Returns null if the string is invalid or cannot be parsed.
+ */
+export function decodeFilterConfig(encoded: string): FilterConfig | null {
+  try {
+    // Convert URL-safe base64 back to standard base64
+    const standardBase64 = encoded.replace(/-/g, '+').replace(/_/g, '/')
+    // Add padding if needed
+    const padded = standardBase64 + '==='.slice(0, (4 - standardBase64.length % 4) % 4)
+    const decoded = atob(padded)
+    return JSON.parse(decoded) as FilterConfig
+  } catch {
+    return null
+  }
+}
+
+/**
+ * Parse URLSearchParams into an EncodedFilterState.
+ */
+export function parseUrlFilters(params: URLSearchParams): EncodedFilterState {
+  const result: EncodedFilterState = {}
+
+  if (params.has('f')) result.f = params.get('f')!
+  if (params.has('s')) result.s = params.get('s')!
+  if (params.has('d')) result.d = params.get('d')!
+
+  if (params.has('p')) {
+    const page = parseInt(params.get('p')!, 10)
+    if (!isNaN(page) && page > 0) result.p = page
+  }
+
+  if (params.has('l')) {
+    const limit = parseInt(params.get('l')!, 10)
+    if (!isNaN(limit) && limit > 0 && limit <= 1000) result.l = limit
+  }
+
+  return result
+}
+
+/**
+ * Build a single-condition FilterConfig.
+ */
+export function createSimpleFilter(
+  field: string,
+  operator: FilterOperator,
+  value: FilterValue
+): FilterConfig {
+  return {
+    groups: [{ logic: 'AND', conditions: [{ field, operator, value }] }],
+    globalLogic: 'AND',
+  }
+}
+
+/**
+ * Merge multiple FilterConfigs with AND logic.
+ */
+export function mergeFilters(...configs: FilterConfig[]): FilterConfig {
+  if (configs.length === 0) return { groups: [] }
+  if (configs.length === 1) return configs[0]
+
+  return {
+    groups: configs.map(config => ({
+      logic: 'AND' as const,
+      conditions: [] as FilterCondition[],
+      groups: config.groups,
+    })),
+    globalLogic: 'AND',
+  }
+}
+
+/**
+ * Get a human-readable description of a FilterConfig.
+ */
+export function getFilterDescription(config: FilterConfig): string {
+  if (config.groups.length === 0) return 'No filters applied'
+
+  function describeGroup(group: FilterGroup): string {
+    const conditionDescs = group.conditions.map(
+      c => `${c.field} ${c.operator} ${c.value}`
+    )
+    const groupDescs = group.groups?.map(g => `(${describeGroup(g)})`) ?? []
+    return [...conditionDescs, ...groupDescs].join(` ${group.logic} `)
+  }
+
+  const groupDescs = config.groups.map(describeGroup)
+  return groupDescs.join(` ${config.globalLogic ?? 'AND'} `)
+}

package/src/filter-types.ts

@@ -0,0 +1,82 @@
+/**
+ * Generic filter types for table/list filtering across StartSimpli apps.
+ *
+ * These types define the shape of a filter configuration that supports
+ * AND/OR logic, multiple operators, and nested groups.
+ *
+ * Domain-specific field types (e.g. FirmFilterField) extend these in each app.
+ */
+
+export type FilterOperator =
+  | 'equals'
+  | 'not_equals'
+  | 'in'
+  | 'not_in'
+  | 'contains'
+  | 'not_contains'
+  | 'starts_with'
+  | 'ends_with'
+  | 'greater_than'
+  | 'greater_than_or_equal'
+  | 'less_than'
+  | 'less_than_or_equal'
+  | 'is_null'
+  | 'is_not_null'
+  | 'between'
+  | 'not_between'
+  | 'fuzzy_search'
+
+export type FilterValue =
+  | string
+  | number
+  | boolean
+  | null
+  | string[]
+  | number[]
+  | [number, number]
+  | [string, string]
+
+export interface FilterCondition {
+  field: string
+  operator: FilterOperator
+  value: FilterValue
+}
+
+export interface FilterGroup {
+  logic: 'AND' | 'OR'
+  conditions: FilterCondition[]
+  groups?: FilterGroup[]
+}
+
+export interface FilterConfig {
+  groups: FilterGroup[]
+  globalLogic?: 'AND' | 'OR'
+  metadata?: {
+    name?: string
+    description?: string
+    tags?: string[]
+  }
+}
+
+/** URL-encoded representation of table state */
+export interface EncodedFilterState {
+  f?: string  // filter config (base64 encoded)
+  s?: string  // sort field
+  d?: string  // sort direction
+  p?: number  // page
+  l?: number  // limit
+}
+
+export interface FilterValidationError {
+  field?: string
+  operator?: string
+  value?: FilterValue
+  message: string
+  code: string
+}
+
+export interface FilterValidationResult {
+  isValid: boolean
+  errors: FilterValidationError[]
+  warnings: string[]
+}