@startsimpli/hooks 0.4.6 → 0.4.8

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@startsimpli/hooks",
-  "version": "0.4.6",
+  "version": "0.4.8",
   "description": "Shared React hooks for StartSimpli apps",
   "main": "./src/index.ts",
   "types": "./src/index.ts",
@@ -24,14 +24,19 @@
   },
   "peerDependencies": {
     "react": ">=18.0.0",
-    "@tanstack/react-query": ">=5.0.0"
+    "@tanstack/react-query": ">=5.0.0",
+    "@startsimpli/api": "workspace:*"
   },
   "peerDependenciesMeta": {
     "@tanstack/react-query": {
       "optional": true
+    },
+    "@startsimpli/api": {
+      "optional": true
     }
   },
   "devDependencies": {
+    "@startsimpli/api": "workspace:*",
     "@tanstack/react-query": "^5.0.0",
     "@testing-library/react": "^14.0.0",
     "@types/node": "^20.11.0",

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)
+      }
+    })
+  })
+})