@startsimpli/hooks 0.4.6 → 0.4.8

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/useMessageTemplates.ts

@@ -0,0 +1,67 @@
+import { useQuery, useMutation, useQueryClient } from '@tanstack/react-query'
+import type { MessageTemplatesApi, MessageTemplateFilters, CreateMessageTemplateInput } from '@startsimpli/api'
+
+/**
+ * List message templates with optional filters (paginated)
+ */
+export function useMessageTemplates(api: MessageTemplatesApi, filters?: MessageTemplateFilters) {
+  return useQuery({
+    queryKey: ['messageTemplates', filters],
+    queryFn: () => api.list(filters),
+  })
+}
+
+/**
+ * Get a single message template by ID
+ */
+export function useMessageTemplate(api: MessageTemplatesApi, id: string) {
+  return useQuery({
+    queryKey: ['messageTemplates', id],
+    queryFn: () => api.get(id),
+    enabled: !!id,
+  })
+}
+
+/**
+ * Create a new message template
+ */
+export function useCreateMessageTemplate(api: MessageTemplatesApi) {
+  const queryClient = useQueryClient()
+
+  return useMutation({
+    mutationFn: (data: CreateMessageTemplateInput) => api.create(data),
+    onSuccess: () => {
+      queryClient.invalidateQueries({ queryKey: ['messageTemplates'] })
+    },
+  })
+}
+
+/**
+ * Update an existing message template
+ */
+export function useUpdateMessageTemplate(api: MessageTemplatesApi) {
+  const queryClient = useQueryClient()
+
+  return useMutation({
+    mutationFn: ({ id, data }: { id: string; data: Partial<CreateMessageTemplateInput> }) =>
+      api.update(id, data),
+    onSuccess: (_, variables) => {
+      queryClient.invalidateQueries({ queryKey: ['messageTemplates'] })
+      queryClient.invalidateQueries({ queryKey: ['messageTemplates', variables.id] })
+    },
+  })
+}
+
+/**
+ * Delete a message template
+ */
+export function useDeleteMessageTemplate(api: MessageTemplatesApi) {
+  const queryClient = useQueryClient()
+
+  return useMutation({
+    mutationFn: (id: string) => api.delete(id),
+    onSuccess: () => {
+      queryClient.invalidateQueries({ queryKey: ['messageTemplates'] })
+    },
+  })
+}

package/src/useMessages.ts

@@ -0,0 +1,86 @@
+import { useQuery, useMutation, useQueryClient } from '@tanstack/react-query'
+import type { MessagesApi, MessageFilters, CreateMessageInput, ScheduleMessageInput, SendTestInput } from '@startsimpli/api'
+
+/**
+ * List messages with optional filters (paginated)
+ */
+export function useMessages(api: MessagesApi, filters?: MessageFilters) {
+  return useQuery({
+    queryKey: ['messages', filters],
+    queryFn: () => api.list(filters),
+  })
+}
+
+/**
+ * Get a single message by ID
+ */
+export function useMessage(api: MessagesApi, id: string) {
+  return useQuery({
+    queryKey: ['messages', id],
+    queryFn: () => api.get(id),
+    enabled: !!id,
+  })
+}
+
+/**
+ * Create a new message (draft)
+ */
+export function useCreateMessage(api: MessagesApi) {
+  const queryClient = useQueryClient()
+
+  return useMutation({
+    mutationFn: (data: CreateMessageInput) => api.create(data),
+    onSuccess: () => {
+      queryClient.invalidateQueries({ queryKey: ['messages'] })
+    },
+  })
+}
+
+/**
+ * Send a message immediately
+ */
+export function useSendMessage(api: MessagesApi, id: string) {
+  const queryClient = useQueryClient()
+
+  return useMutation({
+    mutationFn: () => api.sendNow(id),
+    onSuccess: () => {
+      queryClient.invalidateQueries({ queryKey: ['messages'] })
+      queryClient.invalidateQueries({ queryKey: ['messages', id] })
+    },
+  })
+}
+
+/**
+ * Schedule a message for future sending
+ */
+export function useScheduleMessage(api: MessagesApi, id: string) {
+  const queryClient = useQueryClient()
+
+  return useMutation({
+    mutationFn: (input: ScheduleMessageInput) => api.schedule(id, input),
+    onSuccess: () => {
+      queryClient.invalidateQueries({ queryKey: ['messages'] })
+      queryClient.invalidateQueries({ queryKey: ['messages', id] })
+    },
+  })
+}
+
+/**
+ * Send a test message
+ */
+export function useSendTestMessage(api: MessagesApi, id: string) {
+  return useMutation({
+    mutationFn: (input?: SendTestInput) => api.sendTest(id, input),
+  })
+}
+
+/**
+ * List available messaging channels
+ */
+export function useMessageChannels(api: MessagesApi) {
+  return useQuery({
+    queryKey: ['messages', 'channels'],
+    queryFn: () => api.getChannels(),
+  })
+}

package/src/useTargetLists.ts

@@ -0,0 +1,132 @@
+import { useQuery, useMutation, useQueryClient } from '@tanstack/react-query'
+import type {
+  TargetList,
+  TargetListMember,
+  CreateTargetListInput,
+  UpdateTargetListInput,
+  TargetListFilters,
+  TargetListMemberFilters,
+  AddMembersResult,
+  RemoveMembersResult,
+  RefreshResult,
+  PaginatedResponse,
+} from '@startsimpli/api'
+
+export const TARGET_LIST_KEYS = {
+  all: ['target-lists'] as const,
+  lists: (filters?: TargetListFilters) => [...TARGET_LIST_KEYS.all, filters] as const,
+  detail: (id: string) => ['target-list', id] as const,
+  members: (listId: string, filters?: TargetListMemberFilters) =>
+    ['list-members', listId, filters] as const,
+}
+
+export interface TargetListApiFns {
+  list: (filters?: TargetListFilters) => Promise<PaginatedResponse<TargetList>>
+  get: (id: string) => Promise<TargetList>
+  create: (data: CreateTargetListInput) => Promise<TargetList>
+  update: (id: string, data: UpdateTargetListInput) => Promise<TargetList>
+  delete: (id: string) => Promise<void>
+  getMembers: (listId: string, filters?: TargetListMemberFilters) => Promise<PaginatedResponse<TargetListMember>>
+  addMembers: (listId: string, contactIds: string[]) => Promise<AddMembersResult>
+  removeMembers: (listId: string, contactIds: string[]) => Promise<RemoveMembersResult>
+  refresh: (listId: string) => Promise<RefreshResult>
+}
+
+export function useTargetListDetail(
+  id: string,
+  apiFns: Pick<TargetListApiFns, 'get'>
+) {
+  return useQuery({
+    queryKey: TARGET_LIST_KEYS.detail(id),
+    queryFn: () => apiFns.get(id),
+    enabled: !!id,
+  })
+}
+
+export interface UseTargetListMutationsOptions {
+  apiFns: Pick<TargetListApiFns, 'create' | 'update' | 'delete' | 'addMembers' | 'removeMembers' | 'refresh'>
+  onSuccess?: (action: string) => void
+  onError?: (action: string) => void
+}
+
+export function useTargetListMutations({
+  apiFns,
+  onSuccess,
+  onError,
+}: UseTargetListMutationsOptions) {
+  const queryClient = useQueryClient()
+
+  const invalidateList = (listId?: string) => {
+    queryClient.invalidateQueries({ queryKey: TARGET_LIST_KEYS.all })
+    if (listId) {
+      queryClient.invalidateQueries({ queryKey: TARGET_LIST_KEYS.detail(listId) })
+      queryClient.invalidateQueries({ queryKey: ['list-members', listId] })
+    }
+  }
+
+  const createList = useMutation({
+    mutationFn: (data: CreateTargetListInput) => apiFns.create(data),
+    onSuccess: () => {
+      invalidateList()
+      onSuccess?.('List created')
+    },
+    onError: () => onError?.('Failed to create list'),
+  })
+
+  const updateList = useMutation({
+    mutationFn: ({ id, data }: { id: string; data: UpdateTargetListInput }) =>
+      apiFns.update(id, data),
+    onSuccess: (_, variables) => {
+      invalidateList(variables.id)
+      onSuccess?.('List updated')
+    },
+    onError: () => onError?.('Failed to update list'),
+  })
+
+  const deleteList = useMutation({
+    mutationFn: (id: string) => apiFns.delete(id),
+    onSuccess: () => {
+      invalidateList()
+      onSuccess?.('List deleted')
+    },
+    onError: () => onError?.('Failed to delete list'),
+  })
+
+  const addMembersMutation = useMutation({
+    mutationFn: ({ listId, contactIds }: { listId: string; contactIds: string[] }) =>
+      apiFns.addMembers(listId, contactIds),
+    onSuccess: (_, variables) => {
+      invalidateList(variables.listId)
+      onSuccess?.('Members added')
+    },
+    onError: () => onError?.('Failed to add members'),
+  })
+
+  const removeMembersMutation = useMutation({
+    mutationFn: ({ listId, contactIds }: { listId: string; contactIds: string[] }) =>
+      apiFns.removeMembers(listId, contactIds),
+    onSuccess: (_, variables) => {
+      invalidateList(variables.listId)
+      onSuccess?.('Members removed')
+    },
+    onError: () => onError?.('Failed to remove members'),
+  })
+
+  const refreshList = useMutation({
+    mutationFn: (listId: string) => apiFns.refresh(listId),
+    onSuccess: (_, listId) => {
+      invalidateList(listId)
+      onSuccess?.('List refreshed')
+    },
+    onError: () => onError?.('Failed to refresh list'),
+  })
+
+  return {
+    createList,
+    updateList,
+    deleteList,
+    addMembers: addMembersMutation,
+    removeMembers: removeMembersMutation,
+    refreshList,
+  }
+}

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,
   }
 }