@seed-ship/mcp-ui-solid 1.2.2 → 2.0.0

package/src/hooks/useAction.ts

@@ -1,10 +1,27 @@
 /**
  * useAction - Hook for executing MCP actions from components
  * Phase 5.0: Quick Wins - Simplified API for ActionRenderer and custom components
+ * Sprint 2: Lifecycle callbacks and retry support
  */
 
 import { createSignal, Accessor } from 'solid-js'
 import { useMCPActionSafe, ActionRequest, ActionResult } from '../context/MCPActionContext'
+import type { ActionLifecycleCallbacks } from '../types'
+
+/**
+ * Options for useAction hook
+ */
+export interface UseActionOptions extends ActionLifecycleCallbacks {
+  /**
+   * Number of retry attempts on failure
+   */
+  retryCount?: number
+
+  /**
+   * Delay between retries in milliseconds
+   */
+  retryDelay?: number
+}
 
 /**
  * Return type for useAction hook
@@ -34,6 +51,21 @@ export interface UseActionReturn {
    * Last error (if any)
    */
   lastError: Accessor<string | undefined>
+
+  /**
+   * Retry the last failed action
+   */
+  retry: () => Promise<ActionResult | undefined>
+
+  /**
+   * Clear the last error
+   */
+  clearError: () => void
+
+  /**
+   * Reset all state
+   */
+  reset: () => void
 }
 
 /**
@@ -58,36 +90,131 @@ export interface UseActionReturn {
  *   )
  * }
  * ```
+ *
+ * @example With lifecycle callbacks
+ * ```tsx
+ * function MyActionButton() {
+ *   const { execute, retry, clearError, lastError } = useAction({
+ *     onBefore: (req) => {
+ *       console.log('About to execute:', req.toolName)
+ *       return true // proceed
+ *     },
+ *     onSuccess: (result) => {
+ *       toast.success('Action completed!')
+ *     },
+ *     onError: (error) => {
+ *       toast.error(`Action failed: ${error}`)
+ *     },
+ *     retryCount: 3,
+ *     retryDelay: 1000,
+ *   })
+ *
+ *   return (
+ *     <div>
+ *       <button onClick={() => execute('search.hub', { query: 'test' })}>
+ *         Search
+ *       </button>
+ *       <Show when={lastError()}>
+ *         <button onClick={retry}>Retry</button>
+ *         <button onClick={clearError}>Dismiss</button>
+ *       </Show>
+ *     </div>
+ *   )
+ * }
+ * ```
  */
-export function useAction(): UseActionReturn {
+export function useAction(options: UseActionOptions = {}): UseActionReturn {
   const context = useMCPActionSafe()
   const [lastError, setLastError] = createSignal<string>()
+  const [lastRequest, setLastRequest] = createSignal<ActionRequest>()
+  const [retryAttempt, setRetryAttempt] = createSignal(0)
 
-  const execute = async (toolName: string, params?: Record<string, any>): Promise<ActionResult> => {
+  const executeWithLifecycle = async (request: ActionRequest): Promise<ActionResult> => {
     setLastError(undefined)
+    setLastRequest(request)
 
-    const result = await context.executeAction({
-      toolName,
-      params,
-    })
+    // onBefore callback (can cancel)
+    if (options.onBefore) {
+      const shouldProceed = await options.onBefore({
+        toolName: request.toolName,
+        params: request.params,
+      })
+      if (!shouldProceed) {
+        const cancelledResult: ActionResult = {
+          success: false,
+          error: 'Action cancelled by onBefore callback',
+          timestamp: new Date().toISOString(),
+          toolName: request.toolName,
+        }
+        return cancelledResult
+      }
+    }
+
+    const result = await context.executeAction(request)
 
-    if (!result.success && result.error) {
+    if (result.success) {
+      options.onSuccess?.({
+        success: result.success,
+        data: result.data,
+        timestamp: result.timestamp,
+        toolName: result.toolName,
+      })
+    } else {
       setLastError(result.error)
+      options.onError?.(result.error || 'Unknown error', {
+        toolName: request.toolName,
+        params: request.params,
+      })
     }
 
+    options.onComplete?.({
+      success: result.success,
+      data: result.data,
+      error: result.error,
+      timestamp: result.timestamp,
+      toolName: result.toolName,
+    })
+
     return result
   }
 
+  const execute = async (toolName: string, params?: Record<string, any>): Promise<ActionResult> => {
+    setRetryAttempt(0)
+    return executeWithLifecycle({ toolName, params })
+  }
+
   const executeAction = async (request: ActionRequest): Promise<ActionResult> => {
-    setLastError(undefined)
+    setRetryAttempt(0)
+    return executeWithLifecycle(request)
+  }
 
-    const result = await context.executeAction(request)
+  const retry = async (): Promise<ActionResult | undefined> => {
+    const request = lastRequest()
+    if (!request) return undefined
 
-    if (!result.success && result.error) {
-      setLastError(result.error)
+    const maxRetries = options.retryCount || 3
+    const attempt = retryAttempt() + 1
+
+    if (attempt > maxRetries) {
+      setLastError(`Max retries (${maxRetries}) exceeded`)
+      return undefined
     }
 
-    return result
+    setRetryAttempt(attempt)
+
+    if (options.retryDelay) {
+      await new Promise((r) => setTimeout(r, options.retryDelay))
+    }
+
+    return executeWithLifecycle(request)
+  }
+
+  const clearError = () => setLastError(undefined)
+
+  const reset = () => {
+    setLastError(undefined)
+    setLastRequest(undefined)
+    setRetryAttempt(0)
   }
 
   return {
@@ -96,9 +223,25 @@ export function useAction(): UseActionReturn {
     isExecuting: context.isExecuting,
     lastResult: context.lastResult,
     lastError,
+    retry,
+    clearError,
+    reset,
   }
 }
 
+/**
+ * Return type for useToolAction hook
+ */
+export interface UseToolActionReturn {
+  execute: (params?: Record<string, any>) => Promise<ActionResult>
+  isExecuting: Accessor<boolean>
+  lastResult: Accessor<ActionResult | undefined>
+  lastError: Accessor<string | undefined>
+  retry: () => Promise<ActionResult | undefined>
+  clearError: () => void
+  reset: () => void
+}
+
 /**
  * Hook for binding action to a specific tool
  *
@@ -114,14 +257,40 @@ export function useAction(): UseActionReturn {
  *   )
  * }
  * ```
+ *
+ * @example With lifecycle callbacks
+ * ```tsx
+ * function SearchButton() {
+ *   const { execute, retry, lastError } = useToolAction('search.hub', {
+ *     onSuccess: (result) => toast.success('Search complete!'),
+ *     onError: (error) => toast.error(`Search failed: ${error}`),
+ *     retryCount: 2,
+ *   })
+ *
+ *   return (
+ *     <div>
+ *       <button onClick={() => execute({ query: 'test' })}>Search</button>
+ *       <Show when={lastError()}>
+ *         <button onClick={retry}>Retry</button>
+ *       </Show>
+ *     </div>
+ *   )
+ * }
+ * ```
  */
-export function useToolAction(toolName: string): {
-  execute: (params?: Record<string, any>) => Promise<ActionResult>
-  isExecuting: Accessor<boolean>
-  lastResult: Accessor<ActionResult | undefined>
-  lastError: Accessor<string | undefined>
-} {
-  const { execute: baseExecute, isExecuting, lastResult, lastError } = useAction()
+export function useToolAction(
+  toolName: string,
+  options: UseActionOptions = {}
+): UseToolActionReturn {
+  const {
+    execute: baseExecute,
+    isExecuting,
+    lastResult,
+    lastError,
+    retry,
+    clearError,
+    reset,
+  } = useAction(options)
 
   const execute = async (params?: Record<string, any>): Promise<ActionResult> => {
     return baseExecute(toolName, params)
@@ -132,6 +301,9 @@ export function useToolAction(toolName: string): {
     isExecuting,
     lastResult,
     lastError,
+    retry,
+    clearError,
+    reset,
   }
 }
 

package/src/hooks/useConditionalField.ts

@@ -0,0 +1,92 @@
+/**
+ * useConditionalField - Evaluates showWhen conditions for form fields
+ * Sprint 2: Form Advanced
+ */
+
+import { Accessor, createMemo } from 'solid-js'
+import type { ShowWhenCondition } from '../types'
+
+export interface UseConditionalFieldOptions {
+  condition?: ShowWhenCondition
+  formData: Accessor<Record<string, any>>
+}
+
+/**
+ * Evaluates a showWhen condition against form data
+ */
+export function evaluateCondition(
+  condition: ShowWhenCondition,
+  formData: Record<string, any>
+): boolean {
+  const fieldValue = formData[condition.field]
+
+  switch (condition.operator) {
+    case 'equals':
+      return fieldValue === condition.value
+
+    case 'notEquals':
+      return fieldValue !== condition.value
+
+    case 'in':
+      return Array.isArray(condition.value) && condition.value.includes(fieldValue)
+
+    case 'notIn':
+      return Array.isArray(condition.value) && !condition.value.includes(fieldValue)
+
+    case 'contains':
+      return typeof fieldValue === 'string' && fieldValue.includes(condition.value as string)
+
+    case 'startsWith':
+      return typeof fieldValue === 'string' && fieldValue.startsWith(condition.value as string)
+
+    case 'endsWith':
+      return typeof fieldValue === 'string' && fieldValue.endsWith(condition.value as string)
+
+    case 'greaterThan':
+      return typeof fieldValue === 'number' && fieldValue > (condition.value as number)
+
+    case 'lessThan':
+      return typeof fieldValue === 'number' && fieldValue < (condition.value as number)
+
+    case 'isEmpty':
+      return fieldValue === undefined || fieldValue === null || fieldValue === ''
+
+    case 'isNotEmpty':
+      return fieldValue !== undefined && fieldValue !== null && fieldValue !== ''
+
+    case 'isTrue':
+      return fieldValue === true
+
+    case 'isFalse':
+      return fieldValue === false
+
+    default:
+      return true
+  }
+}
+
+/**
+ * Hook for conditional field visibility
+ *
+ * @example
+ * ```tsx
+ * const { isVisible } = useConditionalField({
+ *   condition: field.showWhen,
+ *   formData: formDataAccessor
+ * })
+ *
+ * return (
+ *   <Show when={isVisible()}>
+ *     <input ... />
+ *   </Show>
+ * )
+ * ```
+ */
+export function useConditionalField(options: UseConditionalFieldOptions) {
+  const isVisible = createMemo(() => {
+    if (!options.condition) return true
+    return evaluateCondition(options.condition, options.formData())
+  })
+
+  return { isVisible }
+}

package/src/hooks/useFormPersistence.test.ts

@@ -0,0 +1,265 @@
+/**
+ * useFormPersistence Tests
+ * Sprint 4: State & Charts
+ */
+
+import { describe, it, expect, vi, beforeEach, afterEach } from 'vitest'
+import { createSignal, createRoot } from 'solid-js'
+import { useFormPersistence } from './useFormPersistence'
+
+// Mock localStorage
+const createMockStorage = (): Storage => {
+  const 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(() => {
+      Object.keys(store).forEach((key) => delete store[key])
+    }),
+    key: vi.fn((index: number) => Object.keys(store)[index] || null),
+    get length() {
+      return Object.keys(store).length
+    },
+  }
+}
+
+describe('useFormPersistence', () => {
+  let mockStorage: Storage
+
+  beforeEach(() => {
+    mockStorage = createMockStorage()
+    vi.useFakeTimers()
+  })
+
+  afterEach(() => {
+    vi.useRealTimers()
+    vi.clearAllMocks()
+  })
+
+  it('does not save before initialization', () => {
+    createRoot((dispose) => {
+      const [formData, setFormData] = createSignal<Record<string, unknown>>({ name: 'test' })
+
+      useFormPersistence({
+        persistKey: 'test-form',
+        formData,
+        setFormData,
+        storage: mockStorage,
+      })
+
+      // Should not save immediately (before onMount)
+      vi.advanceTimersByTime(600)
+      expect(mockStorage.setItem).not.toHaveBeenCalled()
+
+      dispose()
+    })
+  })
+
+  it('clears persisted data with clearPersisted', () => {
+    createRoot((dispose) => {
+      const [formData, setFormData] = createSignal<Record<string, unknown>>({})
+
+      // Pre-populate storage
+      const stored = JSON.stringify({
+        data: { name: 'stored' },
+        timestamp: Date.now(),
+        version: 1,
+      })
+      ;(mockStorage.getItem as any).mockReturnValue(stored)
+
+      const { clearPersisted } = useFormPersistence({
+        persistKey: 'test-form',
+        formData,
+        setFormData,
+        storage: mockStorage,
+      })
+
+      clearPersisted()
+      expect(mockStorage.removeItem).toHaveBeenCalledWith('mcp-ui-form:test-form')
+
+      dispose()
+    })
+  })
+
+  it('returns false for hasPersisted when no data exists', () => {
+    createRoot((dispose) => {
+      const [formData, setFormData] = createSignal<Record<string, unknown>>({})
+
+      const { hasPersisted } = useFormPersistence({
+        persistKey: 'test-form',
+        formData,
+        setFormData,
+        storage: mockStorage,
+      })
+
+      expect(hasPersisted()).toBe(false)
+
+      dispose()
+    })
+  })
+
+  it('returns true for hasPersisted when valid data exists', () => {
+    createRoot((dispose) => {
+      const [formData, setFormData] = createSignal<Record<string, unknown>>({})
+
+      // Pre-populate storage
+      const stored = JSON.stringify({
+        data: { name: 'stored' },
+        timestamp: Date.now(),
+        version: 1,
+      })
+      ;(mockStorage.getItem as any).mockReturnValue(stored)
+
+      const { hasPersisted } = useFormPersistence({
+        persistKey: 'test-form',
+        formData,
+        setFormData,
+        storage: mockStorage,
+      })
+
+      expect(hasPersisted()).toBe(true)
+
+      dispose()
+    })
+  })
+
+  it('returns false for hasPersisted when data is expired', () => {
+    createRoot((dispose) => {
+      const [formData, setFormData] = createSignal<Record<string, unknown>>({})
+
+      // Pre-populate storage with old timestamp
+      const stored = JSON.stringify({
+        data: { name: 'stored' },
+        timestamp: Date.now() - 10000, // 10 seconds ago
+        version: 1,
+      })
+      ;(mockStorage.getItem as any).mockReturnValue(stored)
+
+      const { hasPersisted } = useFormPersistence({
+        persistKey: 'test-form',
+        formData,
+        setFormData,
+        storage: mockStorage,
+        expiresIn: 5000, // 5 seconds
+      })
+
+      expect(hasPersisted()).toBe(false)
+
+      dispose()
+    })
+  })
+
+  it('returns null for getPersistedTimestamp when no data exists', () => {
+    createRoot((dispose) => {
+      const [formData, setFormData] = createSignal<Record<string, unknown>>({})
+
+      const { getPersistedTimestamp } = useFormPersistence({
+        persistKey: 'test-form',
+        formData,
+        setFormData,
+        storage: mockStorage,
+      })
+
+      expect(getPersistedTimestamp()).toBeNull()
+
+      dispose()
+    })
+  })
+
+  it('returns timestamp for getPersistedTimestamp when data exists', () => {
+    createRoot((dispose) => {
+      const [formData, setFormData] = createSignal<Record<string, unknown>>({})
+
+      const timestamp = Date.now()
+      const stored = JSON.stringify({
+        data: { name: 'stored' },
+        timestamp,
+        version: 1,
+      })
+      ;(mockStorage.getItem as any).mockReturnValue(stored)
+
+      const { getPersistedTimestamp } = useFormPersistence({
+        persistKey: 'test-form',
+        formData,
+        setFormData,
+        storage: mockStorage,
+      })
+
+      expect(getPersistedTimestamp()).toBe(timestamp)
+
+      dispose()
+    })
+  })
+
+  it('handles null storage gracefully (SSR)', () => {
+    createRoot((dispose) => {
+      const [formData, setFormData] = createSignal<Record<string, unknown>>({ name: 'test' })
+
+      const { clearPersisted, hasPersisted, getPersistedTimestamp } = useFormPersistence({
+        persistKey: 'test-form',
+        formData,
+        setFormData,
+        storage: null,
+      })
+
+      // Should not throw errors
+      expect(hasPersisted()).toBe(false)
+      expect(getPersistedTimestamp()).toBeNull()
+      clearPersisted() // Should not throw
+
+      dispose()
+    })
+  })
+
+  it('ignores data with wrong version', () => {
+    createRoot((dispose) => {
+      const [formData, setFormData] = createSignal<Record<string, unknown>>({})
+
+      // Pre-populate storage with wrong version
+      const stored = JSON.stringify({
+        data: { name: 'stored' },
+        timestamp: Date.now(),
+        version: 999, // Wrong version
+      })
+      ;(mockStorage.getItem as any).mockReturnValue(stored)
+
+      const { hasPersisted } = useFormPersistence({
+        persistKey: 'test-form',
+        formData,
+        setFormData,
+        storage: mockStorage,
+      })
+
+      expect(hasPersisted()).toBe(false)
+
+      dispose()
+    })
+  })
+
+  it('handles JSON parse errors gracefully', () => {
+    createRoot((dispose) => {
+      const [formData, setFormData] = createSignal<Record<string, unknown>>({})
+
+      // Pre-populate storage with invalid JSON
+      ;(mockStorage.getItem as any).mockReturnValue('invalid json{')
+
+      const { hasPersisted, getPersistedTimestamp } = useFormPersistence({
+        persistKey: 'test-form',
+        formData,
+        setFormData,
+        storage: mockStorage,
+      })
+
+      // Should handle gracefully
+      expect(hasPersisted()).toBe(false)
+      expect(getPersistedTimestamp()).toBeNull()
+
+      dispose()
+    })
+  })
+})