@startsimpli/hooks 0.4.8 → 0.4.11

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@startsimpli/hooks",
-  "version": "0.4.8",
+  "version": "0.4.11",
   "description": "Shared React hooks for StartSimpli apps",
   "main": "./src/index.ts",
   "types": "./src/index.ts",
@@ -23,9 +23,9 @@
     "clean": "rm -rf dist"
   },
   "peerDependencies": {
-    "react": ">=18.0.0",
+    "@startsimpli/api": "workspace:*",
     "@tanstack/react-query": ">=5.0.0",
-    "@startsimpli/api": "workspace:*"
+    "react": ">=18.0.0"
   },
   "peerDependenciesMeta": {
     "@tanstack/react-query": {
@@ -37,14 +37,14 @@
   },
   "devDependencies": {
     "@startsimpli/api": "workspace:*",
-    "@tanstack/react-query": "^5.0.0",
-    "@testing-library/react": "^14.0.0",
-    "@types/node": "^20.11.0",
-    "@types/react": "^18.2.0",
-    "react": "^18.2.0",
-    "react-dom": "^18.2.0",
+    "@tanstack/react-query": "^5.99.2",
+    "@testing-library/react": "^16.3.2",
+    "@types/node": "^20.19.39",
+    "@types/react": "^19.2.14",
+    "react": "^19.2.5",
+    "react-dom": "^19.2.5",
     "tsup": "^8.5.1",
-    "typescript": "^5.3.3",
-    "vitest": "^1.2.0"
+    "typescript": "^6.0.3",
+    "vitest": "^4.1.5"
   }
 }

package/src/__tests__/useReducedMotion.test.ts

@@ -0,0 +1,77 @@
+/**
+ * Contract tests for useReducedMotion (bead swb1).
+ *
+ * Written to fail until the hook is moved into @startsimpli/hooks.
+ * Currently duplicated in raise-simpli/web-app/src/hooks/useReducedMotion.ts
+ * — after the move, the app imports this one and deletes the local copy.
+ */
+
+import { describe, it, expect, vi, beforeEach, afterEach } from 'vitest'
+import { renderHook, act } from '@testing-library/react'
+import { useReducedMotion } from '../useReducedMotion'
+
+// Minimal MediaQueryList mock that matchMedia returns.
+function makeMediaQueryList(matches: boolean) {
+  const listeners = new Set<(e: MediaQueryListEvent) => void>()
+  return {
+    matches,
+    media: '(prefers-reduced-motion: reduce)',
+    addEventListener: (_: string, cb: (e: MediaQueryListEvent) => void) => {
+      listeners.add(cb)
+    },
+    removeEventListener: (_: string, cb: (e: MediaQueryListEvent) => void) => {
+      listeners.delete(cb)
+    },
+    dispatch(nextMatches: boolean) {
+      for (const cb of listeners)
+        cb({ matches: nextMatches } as unknown as MediaQueryListEvent)
+    },
+    listenerCount() {
+      return listeners.size
+    },
+  }
+}
+
+describe('useReducedMotion', () => {
+  let mql: ReturnType<typeof makeMediaQueryList>
+
+  beforeEach(() => {
+    mql = makeMediaQueryList(false)
+    window.matchMedia = vi.fn().mockReturnValue(mql) as unknown as typeof window.matchMedia
+  })
+
+  afterEach(() => {
+    vi.restoreAllMocks()
+  })
+
+  it('returns the current prefers-reduced-motion value on mount', () => {
+    mql = makeMediaQueryList(true)
+    window.matchMedia = vi.fn().mockReturnValue(mql) as unknown as typeof window.matchMedia
+
+    const { result } = renderHook(() => useReducedMotion())
+    expect(result.current).toBe(true)
+  })
+
+  it('updates when the media query changes', () => {
+    const { result } = renderHook(() => useReducedMotion())
+    expect(result.current).toBe(false)
+
+    act(() => {
+      mql.dispatch(true)
+    })
+    expect(result.current).toBe(true)
+
+    act(() => {
+      mql.dispatch(false)
+    })
+    expect(result.current).toBe(false)
+  })
+
+  it('cleans up the media query listener on unmount', () => {
+    const { unmount } = renderHook(() => useReducedMotion())
+    expect(mql.listenerCount()).toBe(1)
+
+    unmount()
+    expect(mql.listenerCount()).toBe(0)
+  })
+})

package/src/__tests__/useRefetchOnFocus.test.ts

@@ -0,0 +1,102 @@
+/**
+ * Contract tests for useRefetchOnFocus (bead swb1).
+ *
+ * Hook is framework-agnostic — the caller passes in `pathname` so the hook
+ * doesn't take a Next dependency. In the raise-simpli app, callers pass
+ * usePathname() from 'next/navigation'.
+ */
+
+import { describe, it, expect, vi, beforeEach, afterEach } from 'vitest'
+import { renderHook, act } from '@testing-library/react'
+import { useRefetchOnFocus } from '../useRefetchOnFocus'
+
+describe('useRefetchOnFocus', () => {
+  beforeEach(() => {
+    Object.defineProperty(document, 'visibilityState', {
+      configurable: true,
+      get: () => 'visible',
+    })
+  })
+
+  afterEach(() => {
+    vi.useRealTimers()
+  })
+
+  it('does not call refetch on initial mount', () => {
+    const refetch = vi.fn()
+    renderHook(() => useRefetchOnFocus(refetch, '/dashboard'))
+    expect(refetch).not.toHaveBeenCalled()
+  })
+
+  it('calls refetch when the pathname changes', () => {
+    const refetch = vi.fn()
+    const { rerender } = renderHook(
+      ({ path }) => useRefetchOnFocus(refetch, path),
+      { initialProps: { path: '/dashboard' } }
+    )
+    expect(refetch).not.toHaveBeenCalled()
+
+    rerender({ path: '/investors' })
+    expect(refetch).toHaveBeenCalledTimes(1)
+  })
+
+  it('calls refetch when the tab becomes visible after being hidden', () => {
+    vi.useFakeTimers()
+    const refetch = vi.fn()
+    const { rerender } = renderHook(
+      ({ path }) => useRefetchOnFocus(refetch, path),
+      { initialProps: { path: '/dashboard' } }
+    )
+
+    // Clear the initial-mount skip by triggering one pathname change, then
+    // advance past the 2s debounce window so the visibility event isn't
+    // suppressed.
+    rerender({ path: '/next' })
+    refetch.mockClear()
+    vi.advanceTimersByTime(2100)
+
+    Object.defineProperty(document, 'visibilityState', {
+      configurable: true,
+      get: () => 'visible',
+    })
+    act(() => {
+      document.dispatchEvent(new Event('visibilitychange'))
+    })
+    expect(refetch).toHaveBeenCalledTimes(1)
+  })
+
+  it('debounces rapid refetches to ≤1 per 2-second window', () => {
+    vi.useFakeTimers()
+    const refetch = vi.fn()
+    const { rerender } = renderHook(
+      ({ path }) => useRefetchOnFocus(refetch, path),
+      { initialProps: { path: '/dashboard' } }
+    )
+
+    rerender({ path: '/a' })
+    expect(refetch).toHaveBeenCalledTimes(1)
+
+    rerender({ path: '/b' })
+    expect(refetch).toHaveBeenCalledTimes(1) // within debounce
+
+    vi.advanceTimersByTime(2100)
+    rerender({ path: '/c' })
+    expect(refetch).toHaveBeenCalledTimes(2)
+  })
+
+  it('no-ops when enabled=false', () => {
+    const refetch = vi.fn()
+    const { rerender } = renderHook(
+      ({ path, enabled }) => useRefetchOnFocus(refetch, path, enabled),
+      { initialProps: { path: '/dashboard', enabled: false } }
+    )
+
+    rerender({ path: '/other', enabled: false })
+
+    act(() => {
+      document.dispatchEvent(new Event('visibilitychange'))
+    })
+
+    expect(refetch).not.toHaveBeenCalled()
+  })
+})

package/src/index.ts

@@ -49,6 +49,8 @@ export type { UseEntityTableOptions, UseEntityTableReturn } from './useEntityTab
 export { useTargetListDetail, useTargetListMutations, TARGET_LIST_KEYS } from './useTargetLists'
 export type { TargetListApiFns, UseTargetListMutationsOptions } from './useTargetLists'
 export { useEnrichment, useBatchEnrichment, useQueueStatus } from './useEnrichment'
+export { useReducedMotion } from './useReducedMotion'
+export { useRefetchOnFocus } from './useRefetchOnFocus'
 export type {
   UseEnrichmentState,
   UseEnrichmentOptions,

package/src/useReducedMotion.ts

@@ -0,0 +1,27 @@
+/**
+ * useReducedMotion Hook
+ * Detects if user prefers reduced motion for accessibility
+ */
+
+'use client'
+
+import { useEffect, useState } from 'react'
+
+export function useReducedMotion(): boolean {
+  const [prefersReducedMotion, setPrefersReducedMotion] = useState(false)
+
+  useEffect(() => {
+    const mediaQuery = window.matchMedia('(prefers-reduced-motion: reduce)')
+
+    setPrefersReducedMotion(mediaQuery.matches)
+
+    const handleChange = (event: MediaQueryListEvent) => {
+      setPrefersReducedMotion(event.matches)
+    }
+
+    mediaQuery.addEventListener('change', handleChange)
+    return () => mediaQuery.removeEventListener('change', handleChange)
+  }, [])
+
+  return prefersReducedMotion
+}

package/src/useRefetchOnFocus.ts

@@ -0,0 +1,53 @@
+import { useEffect, useRef } from 'react'
+
+/**
+ * Calls `refetch` when the page regains visibility (tab switch back)
+ * or when the provided `pathname` changes (route navigation).
+ *
+ * Skips the initial mount — only fires on subsequent focus/navigation events.
+ * Debounces to prevent rapid re-fetches (minimum 2s between calls).
+ *
+ * Framework-agnostic: in Next.js apps pass `usePathname()` from
+ * 'next/navigation'. In non-Next environments pass any string that
+ * represents the current route (or '' if not applicable).
+ */
+export function useRefetchOnFocus(
+  refetch: () => void,
+  pathname: string,
+  enabled = true
+): void {
+  const mounted = useRef(false)
+  const lastRefetch = useRef(0)
+
+  useEffect(() => {
+    if (!enabled) return
+
+    if (!mounted.current) {
+      mounted.current = true
+      return
+    }
+
+    const now = Date.now()
+    if (now - lastRefetch.current < 2000) return
+
+    lastRefetch.current = now
+    refetch()
+  // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [pathname, enabled])
+
+  useEffect(() => {
+    if (!enabled) return
+
+    function handleVisibilityChange() {
+      if (document.visibilityState === 'visible' && mounted.current) {
+        const now = Date.now()
+        if (now - lastRefetch.current < 2000) return
+        lastRefetch.current = now
+        refetch()
+      }
+    }
+
+    document.addEventListener('visibilitychange', handleVisibilityChange)
+    return () => document.removeEventListener('visibilitychange', handleVisibilityChange)
+  }, [refetch, enabled])
+}