@startsimpli/hooks 0.4.7 → 0.4.8

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@startsimpli/hooks",
-  "version": "0.4.7",
+  "version": "0.4.8",
   "description": "Shared React hooks for StartSimpli apps",
   "main": "./src/index.ts",
   "types": "./src/index.ts",

package/src/__tests__/useAsyncOptions.test.ts

@@ -0,0 +1,136 @@
+import { describe, it, expect, vi } from 'vitest'
+import { renderHook, act, waitFor } from '@testing-library/react'
+import { useAsyncOptions } from '../useAsyncOptions'
+
+describe('useAsyncOptions', () => {
+  it('fetches data on mount and returns it', async () => {
+    const items = [{ id: 1 }, { id: 2 }]
+    const fetcher = vi.fn().mockResolvedValue(items)
+
+    const { result } = renderHook(() => useAsyncOptions(fetcher))
+
+    expect(result.current.loading).toBe(true)
+    expect(result.current.data).toEqual([])
+
+    await waitFor(() => expect(result.current.loading).toBe(false))
+
+    expect(result.current.data).toEqual(items)
+    expect(result.current.error).toBeNull()
+    expect(fetcher).toHaveBeenCalledOnce()
+  })
+
+  it('returns defaultValue while loading', async () => {
+    const defaultValue = [{ id: 0 }]
+    const fetcher = vi.fn().mockResolvedValue([{ id: 1 }])
+
+    const { result } = renderHook(() =>
+      useAsyncOptions(fetcher, { defaultValue })
+    )
+
+    expect(result.current.data).toEqual(defaultValue)
+
+    await waitFor(() => expect(result.current.loading).toBe(false))
+    expect(result.current.data).toEqual([{ id: 1 }])
+  })
+
+  it('does not fetch when enabled is false', async () => {
+    const fetcher = vi.fn().mockResolvedValue([])
+
+    const { result } = renderHook(() =>
+      useAsyncOptions(fetcher, { enabled: false })
+    )
+
+    // Give it a tick to ensure nothing fires
+    await act(async () => {
+      await new Promise((r) => setTimeout(r, 10))
+    })
+
+    expect(fetcher).not.toHaveBeenCalled()
+    expect(result.current.loading).toBe(false)
+    expect(result.current.data).toEqual([])
+  })
+
+  it('fetches when enabled changes from false to true', async () => {
+    const items = [{ id: 1 }]
+    const fetcher = vi.fn().mockResolvedValue(items)
+
+    const { result, rerender } = renderHook(
+      ({ enabled }) => useAsyncOptions(fetcher, { enabled }),
+      { initialProps: { enabled: false } }
+    )
+
+    expect(fetcher).not.toHaveBeenCalled()
+
+    rerender({ enabled: true })
+
+    await waitFor(() => expect(result.current.loading).toBe(false))
+
+    expect(result.current.data).toEqual(items)
+    expect(fetcher).toHaveBeenCalledOnce()
+  })
+
+  it('captures errors', async () => {
+    const fetcher = vi.fn().mockRejectedValue(new Error('Network error'))
+
+    const { result } = renderHook(() => useAsyncOptions(fetcher))
+
+    await waitFor(() => expect(result.current.loading).toBe(false))
+
+    expect(result.current.error).toBeInstanceOf(Error)
+    expect(result.current.error?.message).toBe('Network error')
+    expect(result.current.data).toEqual([])
+  })
+
+  it('wraps non-Error rejections', async () => {
+    const fetcher = vi.fn().mockRejectedValue('string error')
+
+    const { result } = renderHook(() => useAsyncOptions(fetcher))
+
+    await waitFor(() => expect(result.current.loading).toBe(false))
+
+    expect(result.current.error).toBeInstanceOf(Error)
+    expect(result.current.error?.message).toBe('string error')
+  })
+
+  it('refresh re-triggers the fetch', async () => {
+    let callCount = 0
+    const fetcher = vi.fn().mockImplementation(() => {
+      callCount++
+      return Promise.resolve([{ id: callCount }])
+    })
+
+    const { result } = renderHook(() => useAsyncOptions(fetcher))
+
+    await waitFor(() => expect(result.current.loading).toBe(false))
+    expect(result.current.data).toEqual([{ id: 1 }])
+
+    act(() => {
+      result.current.refresh()
+    })
+
+    await waitFor(() => expect(result.current.loading).toBe(false))
+    expect(result.current.data).toEqual([{ id: 2 }])
+    expect(fetcher).toHaveBeenCalledTimes(2)
+  })
+
+  it('does not set state after unmount', async () => {
+    let resolvePromise: (value: unknown[]) => void
+    const fetcher = vi.fn().mockImplementation(
+      () => new Promise<unknown[]>((resolve) => { resolvePromise = resolve })
+    )
+
+    const { result, unmount } = renderHook(() => useAsyncOptions(fetcher))
+
+    expect(result.current.loading).toBe(true)
+
+    unmount()
+
+    // Resolve after unmount — should not throw or update state
+    await act(async () => {
+      resolvePromise!([{ id: 1 }])
+      await new Promise((r) => setTimeout(r, 10))
+    })
+
+    // No error thrown = success (React would warn on set-state-after-unmount)
+  })
+})

package/src/__tests__/useEntityTable.test.ts

@@ -0,0 +1,322 @@
+import { describe, it, expect, vi, beforeEach, afterEach } from 'vitest'
+import { renderHook, act } from '@testing-library/react'
+import { useEntityTable } from '../useEntityTable'
+
+interface TestEntity {
+  id: string
+  name: string
+  value: number
+  createdAt: string
+}
+
+function makeEntity(id: string, name: string, value: number): TestEntity {
+  return { id, name, value, createdAt: '2026-01-15T00:00:00Z' }
+}
+
+function makeOptions(items: TestEntity[]) {
+  return {
+    items,
+    csvFilename: 'test-export',
+    csvColumns: ['Name', 'Value', 'Created'],
+    csvRowMapper: (item: TestEntity) => [
+      item.name,
+      item.value.toString(),
+      new Date(item.createdAt).toLocaleDateString(),
+    ],
+  }
+}
+
+// Mock URL APIs for CSV export
+beforeEach(() => {
+  vi.clearAllMocks()
+  vi.stubGlobal('URL', {
+    createObjectURL: vi.fn().mockReturnValue('blob:test'),
+    revokeObjectURL: vi.fn(),
+  })
+})
+
+/**
+ * Patches document.createElement so only 'a' tags return a fake anchor,
+ * while React's internal DOM calls go through the real implementation.
+ */
+function mockAnchorElement() {
+  const clickSpy = vi.fn()
+  const realCreateElement = document.createElement.bind(document)
+  const spy = vi.spyOn(document, 'createElement').mockImplementation((tag: string, options?: ElementCreationOptions) => {
+    if (tag === 'a') {
+      return { href: '', download: '', click: clickSpy } as unknown as HTMLAnchorElement
+    }
+    return realCreateElement(tag, options)
+  })
+  return { clickSpy, restore: () => spy.mockRestore() }
+}
+
+describe('useEntityTable', () => {
+  describe('modal state', () => {
+    it('initializes with null/closed state', () => {
+      const { result } = renderHook(() =>
+        useEntityTable<TestEntity>(makeOptions([]))
+      )
+
+      expect(result.current.selectedItem).toBeNull()
+      expect(result.current.editingItem).toBeNull()
+      expect(result.current.viewMode).toBeNull()
+      expect(result.current.showCreateForm).toBe(false)
+    })
+
+    it('openView sets selectedItem and viewMode to view', () => {
+      const entity = makeEntity('1', 'Acme', 100)
+      const { result } = renderHook(() =>
+        useEntityTable<TestEntity>(makeOptions([entity]))
+      )
+
+      act(() => {
+        result.current.openView(entity)
+      })
+
+      expect(result.current.selectedItem).toBe(entity)
+      expect(result.current.editingItem).toBeNull()
+      expect(result.current.viewMode).toBe('view')
+      expect(result.current.showCreateForm).toBe(false)
+    })
+
+    it('openEdit sets editingItem and viewMode to edit', () => {
+      const entity = makeEntity('1', 'Acme', 100)
+      const { result } = renderHook(() =>
+        useEntityTable<TestEntity>(makeOptions([entity]))
+      )
+
+      act(() => {
+        result.current.openEdit(entity)
+      })
+
+      expect(result.current.selectedItem).toBeNull()
+      expect(result.current.editingItem).toBe(entity)
+      expect(result.current.viewMode).toBe('edit')
+      expect(result.current.showCreateForm).toBe(false)
+    })
+
+    it('openCreate shows create form and clears other state', () => {
+      const entity = makeEntity('1', 'Acme', 100)
+      const { result } = renderHook(() =>
+        useEntityTable<TestEntity>(makeOptions([entity]))
+      )
+
+      act(() => {
+        result.current.openView(entity)
+      })
+
+      act(() => {
+        result.current.openCreate()
+      })
+
+      expect(result.current.selectedItem).toBeNull()
+      expect(result.current.editingItem).toBeNull()
+      expect(result.current.viewMode).toBeNull()
+      expect(result.current.showCreateForm).toBe(true)
+    })
+
+    it('closePanel resets all modal state', () => {
+      const entity = makeEntity('1', 'Acme', 100)
+      const { result } = renderHook(() =>
+        useEntityTable<TestEntity>(makeOptions([entity]))
+      )
+
+      act(() => {
+        result.current.openEdit(entity)
+      })
+
+      act(() => {
+        result.current.closePanel()
+      })
+
+      expect(result.current.selectedItem).toBeNull()
+      expect(result.current.editingItem).toBeNull()
+      expect(result.current.viewMode).toBeNull()
+      expect(result.current.showCreateForm).toBe(false)
+    })
+
+    it('openView clears create form', () => {
+      const entity = makeEntity('1', 'Acme', 100)
+      const { result } = renderHook(() =>
+        useEntityTable<TestEntity>(makeOptions([entity]))
+      )
+
+      act(() => {
+        result.current.openCreate()
+      })
+      expect(result.current.showCreateForm).toBe(true)
+
+      act(() => {
+        result.current.openView(entity)
+      })
+      expect(result.current.showCreateForm).toBe(false)
+      expect(result.current.viewMode).toBe('view')
+    })
+
+    it('openEdit clears create form', () => {
+      const entity = makeEntity('1', 'Acme', 100)
+      const { result } = renderHook(() =>
+        useEntityTable<TestEntity>(makeOptions([entity]))
+      )
+
+      act(() => {
+        result.current.openCreate()
+      })
+
+      act(() => {
+        result.current.openEdit(entity)
+      })
+      expect(result.current.showCreateForm).toBe(false)
+      expect(result.current.viewMode).toBe('edit')
+    })
+  })
+
+  describe('CSV export', () => {
+    let anchorMock: { clickSpy: ReturnType<typeof vi.fn>; restore: () => void }
+
+    afterEach(() => {
+      anchorMock?.restore()
+    })
+
+    it('exports all items when no IDs provided', async () => {
+      const items = [
+        makeEntity('1', 'Acme', 100),
+        makeEntity('2', 'Beta', 200),
+      ]
+      const { result } = renderHook(() =>
+        useEntityTable<TestEntity>(makeOptions(items))
+      )
+
+      anchorMock = mockAnchorElement()
+
+      await act(async () => {
+        await result.current.exportCSV()
+      })
+
+      expect(anchorMock.clickSpy).toHaveBeenCalledOnce()
+    })
+
+    it('exports only selected items when IDs provided', async () => {
+      const items = [
+        makeEntity('1', 'Acme', 100),
+        makeEntity('2', 'Beta', 200),
+        makeEntity('3', 'Gamma', 300),
+      ]
+      const { result } = renderHook(() =>
+        useEntityTable<TestEntity>(makeOptions(items))
+      )
+
+      anchorMock = mockAnchorElement()
+
+      await act(async () => {
+        await result.current.exportCSV(new Set(['1', '3']))
+      })
+
+      expect(anchorMock.clickSpy).toHaveBeenCalledOnce()
+      // After export, exportIdsRef should be cleared
+      expect(result.current.exportIdsRef.current).toBeNull()
+    })
+
+    it('clears exportIdsRef after export completes', async () => {
+      const items = [makeEntity('1', 'Acme', 100)]
+      const { result } = renderHook(() =>
+        useEntityTable<TestEntity>(makeOptions(items))
+      )
+
+      anchorMock = mockAnchorElement()
+      result.current.exportIdsRef.current = new Set(['1'])
+
+      await act(async () => {
+        await result.current.exportCSV()
+      })
+
+      expect(result.current.exportIdsRef.current).toBeNull()
+    })
+
+    it('provides exportIdsRef for external use', () => {
+      const { result } = renderHook(() =>
+        useEntityTable<TestEntity>(makeOptions([]))
+      )
+
+      expect(result.current.exportIdsRef).toBeDefined()
+      expect(result.current.exportIdsRef.current).toBeNull()
+    })
+  })
+
+  describe('custom idField', () => {
+    interface CustomIdEntity {
+      internalId: string
+      label: string
+    }
+
+    let anchorMock: { clickSpy: ReturnType<typeof vi.fn>; restore: () => void }
+
+    afterEach(() => {
+      anchorMock?.restore()
+    })
+
+    it('uses custom idField for CSV filtering', async () => {
+      const items: CustomIdEntity[] = [
+        { internalId: 'a', label: 'Alpha' },
+        { internalId: 'b', label: 'Bravo' },
+      ]
+
+      const { result } = renderHook(() =>
+        useEntityTable<CustomIdEntity>({
+          items,
+          idField: 'internalId',
+          csvFilename: 'custom',
+          csvColumns: ['Label'],
+          csvRowMapper: (item) => [item.label],
+        })
+      )
+
+      anchorMock = mockAnchorElement()
+
+      await act(async () => {
+        await result.current.exportCSV(new Set(['a']))
+      })
+
+      // Should not throw; idField 'internalId' was used for filtering
+      expect(result.current.exportIdsRef.current).toBeNull()
+    })
+  })
+
+  describe('generic typing', () => {
+    it('preserves entity type in selectedItem', () => {
+      const entity = makeEntity('1', 'Acme', 100)
+      const { result } = renderHook(() =>
+        useEntityTable<TestEntity>(makeOptions([entity]))
+      )
+
+      act(() => {
+        result.current.openView(entity)
+      })
+
+      // TypeScript compile-time check: selectedItem is TestEntity | null
+      const item = result.current.selectedItem
+      if (item) {
+        expect(item.name).toBe('Acme')
+        expect(item.value).toBe(100)
+      }
+    })
+
+    it('preserves entity type in editingItem', () => {
+      const entity = makeEntity('1', 'Acme', 100)
+      const { result } = renderHook(() =>
+        useEntityTable<TestEntity>(makeOptions([entity]))
+      )
+
+      act(() => {
+        result.current.openEdit(entity)
+      })
+
+      const item = result.current.editingItem
+      if (item) {
+        expect(item.name).toBe('Acme')
+        expect(item.value).toBe(100)
+      }
+    })
+  })
+})

package/src/__tests__/useWizard.test.ts

@@ -1,10 +1,12 @@
-import { describe, it, expect } from 'vitest'
+import { describe, it, expect, vi } from 'vitest'
 import { renderHook, act } from '@testing-library/react'
 import { useWizard } from '../useWizard'
 
 const STEPS = ['upload', 'mapping', 'importing', 'complete'] as const
 
 describe('useWizard', () => {
+  // ---------- backward compatibility ----------
+
   it('starts on the initial step', () => {
     const { result } = renderHook(() => useWizard(STEPS))
     expect(result.current.currentStep).toBe('upload')
@@ -20,41 +22,41 @@ describe('useWizard', () => {
 
   it('advances to next step', () => {
     const { result } = renderHook(() => useWizard(STEPS))
-    act(() => result.current.next())
+    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())
+    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())
+    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())
+    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'))
+    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())
+    act(() => { result.current.next() })
+    act(() => { result.current.next() })
+    act(() => { result.current.reset() })
     expect(result.current.currentStep).toBe('upload')
   })
 
@@ -73,4 +75,194 @@ describe('useWizard', () => {
     expect(result.current.canGoBack).toBe(true)
     expect(result.current.canGoNext).toBe(false)
   })
+
+  it('next() returns null when no validation is configured', () => {
+    const { result } = renderHook(() => useWizard(STEPS))
+    let returnVal: ReturnType<typeof result.current.next>
+    act(() => { returnVal = result.current.next() })
+    expect(returnVal!).toBeNull()
+  })
+
+  it('errors is null by default', () => {
+    const { result } = renderHook(() => useWizard(STEPS))
+    expect(result.current.errors).toBeNull()
+  })
+
+  // ---------- per-step validation ----------
+
+  describe('with validation', () => {
+    const FORM_STEPS = ['details', 'sequence', 'review'] as const
+
+    it('blocks next() when validator returns errors', () => {
+      const validate = {
+        details: () => ({ name: 'Name is required' }),
+      }
+      const { result } = renderHook(() =>
+        useWizard(FORM_STEPS, { validate })
+      )
+
+      let errors: Record<string, string> | null
+      act(() => { errors = result.current.next() })
+
+      expect(errors!).toEqual({ name: 'Name is required' })
+      expect(result.current.currentStep).toBe('details')
+      expect(result.current.errors).toEqual({ name: 'Name is required' })
+    })
+
+    it('advances when validator returns null', () => {
+      const validate = {
+        details: () => null,
+      }
+      const { result } = renderHook(() =>
+        useWizard(FORM_STEPS, { validate })
+      )
+
+      let returnVal: Record<string, string> | null
+      act(() => { returnVal = result.current.next() })
+
+      expect(returnVal!).toBeNull()
+      expect(result.current.currentStep).toBe('sequence')
+      expect(result.current.errors).toBeNull()
+    })
+
+    it('advances when validator returns empty object', () => {
+      const validate = {
+        details: () => ({}),
+      }
+      const { result } = renderHook(() =>
+        useWizard(FORM_STEPS, { validate })
+      )
+
+      act(() => { result.current.next() })
+      expect(result.current.currentStep).toBe('sequence')
+      expect(result.current.errors).toBeNull()
+    })
+
+    it('skips validation for steps without a validator', () => {
+      const validate = {
+        details: () => null,
+        // no validator for 'sequence'
+      }
+      const { result } = renderHook(() =>
+        useWizard(FORM_STEPS, { validate })
+      )
+
+      // advance past details (has validator returning null)
+      act(() => { result.current.next() })
+      expect(result.current.currentStep).toBe('sequence')
+
+      // advance past sequence (no validator)
+      act(() => { result.current.next() })
+      expect(result.current.currentStep).toBe('review')
+    })
+
+    it('clearErrors resets errors to null', () => {
+      const validate = {
+        details: () => ({ name: 'Required' }),
+      }
+      const { result } = renderHook(() =>
+        useWizard(FORM_STEPS, { validate })
+      )
+
+      act(() => { result.current.next() })
+      expect(result.current.errors).toEqual({ name: 'Required' })
+
+      act(() => { result.current.clearErrors() })
+      expect(result.current.errors).toBeNull()
+    })
+
+    it('reset clears errors', () => {
+      const validate = {
+        details: () => ({ name: 'Required' }),
+      }
+      const { result } = renderHook(() =>
+        useWizard(FORM_STEPS, { validate })
+      )
+
+      act(() => { result.current.next() })
+      expect(result.current.errors).not.toBeNull()
+
+      act(() => { result.current.reset() })
+      expect(result.current.errors).toBeNull()
+    })
+
+    it('works with initialStep and opts together', () => {
+      const validate = {
+        sequence: () => ({ steps: 'Add at least one step' }),
+      }
+      const { result } = renderHook(() =>
+        useWizard(FORM_STEPS, 'sequence', { validate })
+      )
+
+      expect(result.current.currentStep).toBe('sequence')
+
+      let errors: Record<string, string> | null
+      act(() => { errors = result.current.next() })
+
+      expect(errors!).toEqual({ steps: 'Add at least one step' })
+      expect(result.current.currentStep).toBe('sequence')
+    })
+
+    it('calls the validator for the current step only', () => {
+      const detailsValidator = vi.fn(() => null)
+      const sequenceValidator = vi.fn(() => null)
+
+      const validate = {
+        details: detailsValidator,
+        sequence: sequenceValidator,
+      }
+      const { result } = renderHook(() =>
+        useWizard(FORM_STEPS, { validate })
+      )
+
+      act(() => { result.current.next() })
+      expect(detailsValidator).toHaveBeenCalledTimes(1)
+      expect(sequenceValidator).not.toHaveBeenCalled()
+
+      act(() => { result.current.next() })
+      expect(sequenceValidator).toHaveBeenCalledTimes(1)
+    })
+
+    it('clears previous errors on successful next()', () => {
+      let shouldFail = true
+      const validate = {
+        details: () => (shouldFail ? { name: 'Required' } : null),
+      }
+      const { result } = renderHook(() =>
+        useWizard(FORM_STEPS, { validate })
+      )
+
+      // First call fails
+      act(() => { result.current.next() })
+      expect(result.current.errors).toEqual({ name: 'Required' })
+      expect(result.current.currentStep).toBe('details')
+
+      // Fix the data, try again
+      shouldFail = false
+      act(() => { result.current.next() })
+      expect(result.current.errors).toBeNull()
+      expect(result.current.currentStep).toBe('sequence')
+    })
+
+    it('returns multiple errors from a single validator', () => {
+      const validate = {
+        details: () => ({
+          name: 'Name is required',
+          channel: 'Select a channel',
+        }),
+      }
+      const { result } = renderHook(() =>
+        useWizard(FORM_STEPS, { validate })
+      )
+
+      let errors: Record<string, string> | null
+      act(() => { errors = result.current.next() })
+
+      expect(errors!).toEqual({
+        name: 'Name is required',
+        channel: 'Select a channel',
+      })
+      expect(result.current.currentStep).toBe('details')
+    })
+  })
 })

package/src/index.ts

@@ -42,8 +42,10 @@ 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 type { WizardState, WizardOptions } from './useWizard'
 export { useCSVImport, useCSVExport } from './useCSV'
+export { useEntityTable } from './useEntityTable'
+export type { UseEntityTableOptions, UseEntityTableReturn } from './useEntityTable'
 export { useTargetListDetail, useTargetListMutations, TARGET_LIST_KEYS } from './useTargetLists'
 export type { TargetListApiFns, UseTargetListMutationsOptions } from './useTargetLists'
 export { useEnrichment, useBatchEnrichment, useQueueStatus } from './useEnrichment'
@@ -62,3 +64,5 @@ export type {
   CSVImportStep,
   UseCSVImportState,
 } from './useCSV'
+export { useAsyncOptions } from './useAsyncOptions'
+export type { UseAsyncOptionsResult } from './useAsyncOptions'

package/src/useAsyncOptions.ts

@@ -0,0 +1,60 @@
+import { useState, useEffect, useCallback, useRef } from 'react'
+
+export interface UseAsyncOptionsResult<T> {
+  data: T[]
+  loading: boolean
+  error: Error | null
+  refresh: () => void
+}
+
+export function useAsyncOptions<T>(
+  fetcher: () => Promise<T[]>,
+  opts?: { enabled?: boolean; defaultValue?: T[] }
+): UseAsyncOptionsResult<T> {
+  const enabled = opts?.enabled ?? true
+  const defaultValue = opts?.defaultValue ?? []
+
+  const [data, setData] = useState<T[]>(defaultValue)
+  const [loading, setLoading] = useState(enabled)
+  const [error, setError] = useState<Error | null>(null)
+  const mountedRef = useRef(true)
+  const fetcherRef = useRef(fetcher)
+  fetcherRef.current = fetcher
+
+  const doFetch = useCallback(() => {
+    setLoading(true)
+    setError(null)
+
+    fetcherRef.current()
+      .then((result) => {
+        if (mountedRef.current) {
+          setData(result)
+        }
+      })
+      .catch((err: unknown) => {
+        if (mountedRef.current) {
+          setError(err instanceof Error ? err : new Error(String(err)))
+        }
+      })
+      .finally(() => {
+        if (mountedRef.current) {
+          setLoading(false)
+        }
+      })
+  }, [])
+
+  useEffect(() => {
+    mountedRef.current = true
+    return () => {
+      mountedRef.current = false
+    }
+  }, [])
+
+  useEffect(() => {
+    if (enabled) {
+      doFetch()
+    }
+  }, [enabled, doFetch])
+
+  return { data, loading, error, refresh: doFetch }
+}

package/src/useEntityTable.ts

@@ -0,0 +1,134 @@
+import { useState, useCallback, useRef, useMemo } from 'react'
+import { useCSVExport } from './useCSV'
+
+export interface UseEntityTableOptions<T> {
+  /** All items currently available (from Redux store, React Query, etc.) */
+  items: T[]
+  /** Field to use as the unique identifier (defaults to 'id') */
+  idField?: keyof T
+  /** Filename for CSV exports (date suffix added automatically) */
+  csvFilename: string
+  /** CSV column headers */
+  csvColumns: string[]
+  /** Maps an entity to an array of CSV cell values */
+  csvRowMapper: (item: T) => string[]
+}
+
+export interface UseEntityTableReturn<T> {
+  /** Currently selected item for viewing */
+  selectedItem: T | null
+  /** Currently selected item for editing */
+  editingItem: T | null
+  /** Current view mode */
+  viewMode: 'view' | 'edit' | null
+  /** Whether the create form is open */
+  showCreateForm: boolean
+  /** Ref to set selected IDs for CSV export filtering */
+  exportIdsRef: React.MutableRefObject<Set<string> | null>
+  /** Export CSV, optionally filtered to the given IDs */
+  exportCSV: (selectedIds?: Set<string>) => Promise<void>
+  /** Whether a CSV export is in progress */
+  isExporting: boolean
+  /** Open the view panel for an item */
+  openView: (item: T) => void
+  /** Open the edit panel for an item */
+  openEdit: (item: T) => void
+  /** Open the create form */
+  openCreate: () => void
+  /** Close view/edit panel and create form */
+  closePanel: () => void
+}
+
+export function useEntityTable<T>({
+  items,
+  idField = 'id' as keyof T,
+  csvFilename,
+  csvColumns,
+  csvRowMapper,
+}: UseEntityTableOptions<T>): UseEntityTableReturn<T> {
+  const [selectedItem, setSelectedItem] = useState<T | null>(null)
+  const [editingItem, setEditingItem] = useState<T | null>(null)
+  const [viewMode, setViewMode] = useState<'view' | 'edit' | null>(null)
+  const [showCreateForm, setShowCreateForm] = useState(false)
+  const exportIdsRef = useRef<Set<string> | null>(null)
+
+  const buildCSV = useCallback(
+    (rows: T[]): string => {
+      const dataRows = rows.map((item) =>
+        csvRowMapper(item).map((cell) => `"${cell}"`)
+      )
+      return [
+        csvColumns.map((col) => `"${col}"`).join(','),
+        ...dataRows.map((row) => row.join(',')),
+      ].join('\n')
+    },
+    [csvColumns, csvRowMapper]
+  )
+
+  const dateSuffix = useMemo(() => new Date().toISOString().split('T')[0], [])
+  const filename = `${csvFilename}-${dateSuffix}.csv`
+
+  const { exportCSV: doExport, isExporting } = useCSVExport({
+    exportFn: async () => {
+      const ids = exportIdsRef.current
+      const filtered = ids
+        ? items.filter((item) => ids.has(String(item[idField])))
+        : items
+      return buildCSV(filtered)
+    },
+    filename,
+  })
+
+  const exportCSV = useCallback(
+    async (selectedIds?: Set<string>) => {
+      if (selectedIds) {
+        exportIdsRef.current = selectedIds
+      }
+      await doExport()
+      exportIdsRef.current = null
+    },
+    [doExport]
+  )
+
+  const openView = useCallback((item: T) => {
+    setSelectedItem(item)
+    setEditingItem(null)
+    setViewMode('view')
+    setShowCreateForm(false)
+  }, [])
+
+  const openEdit = useCallback((item: T) => {
+    setSelectedItem(null)
+    setEditingItem(item)
+    setViewMode('edit')
+    setShowCreateForm(false)
+  }, [])
+
+  const openCreate = useCallback(() => {
+    setSelectedItem(null)
+    setEditingItem(null)
+    setViewMode(null)
+    setShowCreateForm(true)
+  }, [])
+
+  const closePanel = useCallback(() => {
+    setSelectedItem(null)
+    setEditingItem(null)
+    setViewMode(null)
+    setShowCreateForm(false)
+  }, [])
+
+  return {
+    selectedItem,
+    editingItem,
+    viewMode,
+    showCreateForm,
+    exportIdsRef,
+    exportCSV,
+    isExporting,
+    openView,
+    openEdit,
+    openCreate,
+    closePanel,
+  }
+}

package/src/useWizard.ts

@@ -1,4 +1,8 @@
-import { useState, useCallback } from 'react'
+import { useState, useCallback, useRef } from 'react'
+
+export interface WizardOptions<TStep extends string> {
+  validate?: Partial<Record<TStep, () => Record<string, string> | null>>
+}
 
 export interface WizardState<TStep extends string> {
   currentStep: TStep
@@ -8,23 +12,41 @@ export interface WizardState<TStep extends string> {
   isLastStep: boolean
   canGoBack: boolean
   canGoNext: boolean
+  errors: Record<string, string> | null
   goTo: (step: TStep) => void
-  next: () => void
+  next: () => Record<string, string> | null
   prev: () => void
   reset: () => void
+  clearErrors: () => void
 }
 
 export function useWizard<TStep extends string>(
   steps: readonly TStep[],
-  initialStep?: TStep
+  initialStepOrOpts?: TStep | WizardOptions<TStep>,
+  opts?: WizardOptions<TStep>
 ): WizardState<TStep> {
+  // Support both old signature (steps, initialStep?) and new (steps, opts?) and (steps, initialStep, opts?)
+  const initialStep: TStep | undefined =
+    typeof initialStepOrOpts === 'string' ? initialStepOrOpts : undefined
+  const options: WizardOptions<TStep> | undefined =
+    typeof initialStepOrOpts === 'object' ? initialStepOrOpts : opts
+
   const [currentStep, setCurrentStep] = useState<TStep>(initialStep ?? steps[0])
+  const [errors, setErrors] = useState<Record<string, string> | null>(null)
+
+  // Keep validate ref stable to avoid stale closures while keeping validators current
+  const validateRef = useRef(options?.validate)
+  validateRef.current = options?.validate
 
   const stepIndex = steps.indexOf(currentStep)
   const totalSteps = steps.length
   const isFirstStep = stepIndex === 0
   const isLastStep = stepIndex === totalSteps - 1
 
+  const clearErrors = useCallback(() => {
+    setErrors(null)
+  }, [])
+
   const goTo = useCallback(
     (step: TStep) => {
       if (steps.includes(step)) setCurrentStep(step)
@@ -32,8 +54,18 @@ export function useWizard<TStep extends string>(
     [steps]
   )
 
-  const next = useCallback(() => {
+  const next = useCallback((): Record<string, string> | null => {
+    const validator = validateRef.current?.[steps[stepIndex] as TStep]
+    if (validator) {
+      const result = validator()
+      if (result && Object.keys(result).length > 0) {
+        setErrors(result)
+        return result
+      }
+    }
+    setErrors(null)
     if (!isLastStep) setCurrentStep(steps[stepIndex + 1])
+    return null
   }, [isLastStep, stepIndex, steps])
 
   const prev = useCallback(() => {
@@ -42,6 +74,7 @@ export function useWizard<TStep extends string>(
 
   const reset = useCallback(() => {
     setCurrentStep(initialStep ?? steps[0])
+    setErrors(null)
   }, [initialStep, steps])
 
   return {
@@ -52,9 +85,11 @@ export function useWizard<TStep extends string>(
     isLastStep,
     canGoBack: !isFirstStep,
     canGoNext: !isLastStep,
+    errors,
     goTo,
     next,
     prev,
     reset,
+    clearErrors,
   }
 }