@startsimpli/funnels 0.1.3 → 0.1.5

package/src/store/README.md

@@ -0,0 +1,342 @@
+# Funnel Store
+
+Zustand state management for @simpli/funnels.
+
+## Features
+
+- **Factory Pattern** - Create isolated store instances for multi-editor scenarios
+- **Optimistic Updates** - UI updates immediately, rollback on error
+- **Dirty Tracking** - Track unsaved changes
+- **Loading States** - Better UX with loading indicators
+- **Error Handling** - Automatic error capture and rollback
+- **Generic** - Works with any entity type (no product-specific logic)
+
+## Usage
+
+### Basic Setup
+
+```typescript
+import { createFunnelStore } from '@simpli/funnels';
+import { FetchAdapter, FunnelApiClient } from '@simpli/funnels';
+
+// Create API client
+const adapter = new FetchAdapter({
+  headers: {
+    'Authorization': 'Bearer your-token',
+  },
+});
+
+const apiClient = new FunnelApiClient(adapter, 'https://api.example.com');
+
+// Create store instance
+const useFunnelStore = createFunnelStore(apiClient);
+```
+
+### In React Components
+
+```typescript
+function FunnelEditor() {
+  const {
+    funnels,
+    selectedFunnel,
+    isLoading,
+    error,
+    loadFunnels,
+    selectFunnel,
+    updateFunnel,
+  } = useFunnelStore();
+
+  useEffect(() => {
+    loadFunnels({ status: 'active' });
+  }, [loadFunnels]);
+
+  const handleSave = async () => {
+    if (!selectedFunnel) return;
+
+    try {
+      await updateFunnel(selectedFunnel.id, {
+        name: 'Updated Name',
+      });
+    } catch (error) {
+      // Error handled automatically, UI rolled back
+      console.error('Failed to save:', error);
+    }
+  };
+
+  if (isLoading) return <div>Loading...</div>;
+  if (error) return <div>Error: {error.message}</div>;
+
+  return (
+    <div>
+      {funnels.map(funnel => (
+        <div key={funnel.id} onClick={() => selectFunnel(funnel.id)}>
+          {funnel.name}
+        </div>
+      ))}
+    </div>
+  );
+}
+```
+
+### Multiple Store Instances
+
+The factory pattern allows multiple independent stores:
+
+```typescript
+// Editor 1
+const editor1ApiClient = new FunnelApiClient(adapter1, baseUrl);
+const useEditor1Store = createFunnelStore(editor1ApiClient);
+
+// Editor 2
+const editor2ApiClient = new FunnelApiClient(adapter2, baseUrl);
+const useEditor2Store = createFunnelStore(editor2ApiClient);
+
+// Each store is completely isolated
+```
+
+## API
+
+### State
+
+```typescript
+interface FunnelStore<TEntity = any> {
+  // Data
+  funnels: Funnel<TEntity>[];
+  selectedFunnel: Funnel<TEntity> | null;
+  selectedStage: FunnelStage<TEntity> | null;
+  runs: FunnelRun[];
+  pagination: { count, next, previous, currentPage, pageSize };
+
+  // UI State
+  isLoading: boolean;
+  error: Error | null;
+  isDirty: boolean;
+}
+```
+
+### Actions
+
+#### Funnel Management
+
+```typescript
+// Load funnels with filters
+await loadFunnels({ status: 'active', page: 1 });
+
+// Select funnel for editing
+selectFunnel('funnel-id');
+
+// Create new funnel
+const funnel = await createFunnel({
+  name: 'My Funnel',
+  status: 'draft',
+  input_type: 'contacts',
+  stages: [],
+});
+
+// Update funnel (optimistic)
+await updateFunnel('funnel-id', {
+  name: 'Updated Name',
+});
+
+// Delete funnel (optimistic)
+await deleteFunnel('funnel-id');
+
+// Duplicate funnel
+const copy = await duplicateFunnel('funnel-id');
+```
+
+#### Stage Management
+
+```typescript
+// Select stage
+selectStage('stage-id');
+
+// Create stage
+const stage = await createStage('funnel-id', {
+  order: 0,
+  name: 'Qualification',
+  filter_logic: 'AND',
+  rules: [],
+  match_action: 'continue',
+  no_match_action: 'exclude',
+});
+
+// Update stage (optimistic)
+await updateStage('funnel-id', 'stage-id', {
+  name: 'Updated Name',
+});
+
+// Delete stage (optimistic)
+await deleteStage('funnel-id', 'stage-id');
+
+// Reorder stages (optimistic)
+await reorderStages('funnel-id', ['stage-2', 'stage-1', 'stage-3']);
+```
+
+#### Run Operations
+
+```typescript
+// Run funnel
+const run = await runFunnel('funnel-id', {
+  trigger_type: 'manual',
+});
+
+// Load run history
+await loadRuns('funnel-id', {
+  status: 'completed',
+  page: 1,
+});
+
+// Cancel running funnel
+await cancelRun('run-id');
+```
+
+#### UI State
+
+```typescript
+// Set dirty flag
+setDirty(true);
+
+// Clear error
+clearError();
+
+// Reset store
+reset();
+```
+
+## Optimistic Updates
+
+The store automatically implements optimistic updates for:
+- `updateFunnel` - Update funnel data
+- `deleteFunnel` - Remove funnel
+- `updateStage` - Update stage data
+- `deleteStage` - Remove stage
+- `reorderStages` - Reorder stages
+
+On error, the store automatically rolls back to the previous state.
+
+### How It Works
+
+```typescript
+// 1. User clicks save
+await updateFunnel('funnel-1', { name: 'New Name' });
+
+// 2. UI updates immediately (optimistic)
+// -> funnels[0].name = 'New Name'
+
+// 3. API call happens in background
+// -> POST /api/v1/funnels/funnel-1/
+
+// 4a. Success: Update with server response
+// -> funnels[0] = serverResponse
+
+// 4b. Error: Rollback to previous state
+// -> funnels[0].name = 'Old Name'
+// -> error = Error('Update failed')
+```
+
+## Dirty Tracking
+
+Track unsaved changes:
+
+```typescript
+const { isDirty, setDirty } = useFunnelStore();
+
+// Set dirty when user makes changes
+const handleChange = (value) => {
+  setDirty(true);
+};
+
+// Clear dirty on save
+const handleSave = async () => {
+  await updateFunnel(selectedFunnel.id, data);
+  // isDirty automatically set to false
+};
+
+// Warn on navigation
+useEffect(() => {
+  const handleBeforeUnload = (e) => {
+    if (isDirty) {
+      e.preventDefault();
+      e.returnValue = '';
+    }
+  };
+
+  window.addEventListener('beforeunload', handleBeforeUnload);
+  return () => window.removeEventListener('beforeunload', handleBeforeUnload);
+}, [isDirty]);
+```
+
+## Error Handling
+
+Errors are automatically captured and stored:
+
+```typescript
+const { error, clearError } = useFunnelStore();
+
+// Errors set automatically
+await updateFunnel('bad-id', { name: 'New' });
+// -> error = Error('Not found')
+
+// Clear error manually
+clearError();
+
+// Or display in UI
+{error && <Alert>{error.message}</Alert>}
+```
+
+## Testing
+
+See `create-funnel-store.test.ts` for comprehensive test examples.
+
+```typescript
+import { createFunnelStore } from '@simpli/funnels';
+import { vi } from 'vitest';
+
+// Mock API client
+const mockClient = {
+  listFunnels: vi.fn(),
+  createFunnel: vi.fn(),
+  // ... other methods
+};
+
+// Create store with mock
+const useFunnelStore = createFunnelStore(mockClient);
+
+// Test actions
+const { loadFunnels } = useFunnelStore.getState();
+await loadFunnels();
+
+expect(mockClient.listFunnels).toHaveBeenCalled();
+```
+
+## TypeScript
+
+The store is fully typed with generics:
+
+```typescript
+interface InvestorEntity {
+  id: string;
+  name: string;
+  stage: string;
+}
+
+const useFunnelStore = createFunnelStore<InvestorEntity>(apiClient);
+
+// TypeScript knows entity type
+const { funnels } = useFunnelStore();
+// funnels: Funnel<InvestorEntity>[]
+```
+
+## Performance
+
+- **Selective Rendering** - Use Zustand selectors to prevent unnecessary re-renders
+- **Pagination** - Load funnels in pages
+- **Debounced Updates** - Debounce rapid updates
+
+```typescript
+// Selective rendering
+const selectedFunnel = useFunnelStore(state => state.selectedFunnel);
+
+// Only re-renders when selectedFunnel changes
+```