@startsimpli/funnels 0.1.4 → 0.1.5

package/src/components/FunnelStageBuilder/FunnelStageBuilder.tsx

@@ -0,0 +1,321 @@
+/**
+ * FunnelStageBuilder - Main component for creating/editing funnel stages
+ *
+ * Features:
+ * - Drag-and-drop reordering
+ * - Add/remove stages
+ * - Stage configuration (name, description, filters, actions)
+ * - Visual flow with arrows
+ * - Expandable stage cards
+ */
+
+import React, { useState, useCallback } from 'react';
+import {
+  DndContext,
+  closestCenter,
+  KeyboardSensor,
+  PointerSensor,
+  useSensor,
+  useSensors,
+  DragEndEvent,
+} from '@dnd-kit/core';
+import {
+  arrayMove,
+  SortableContext,
+  sortableKeyboardCoordinates,
+  verticalListSortingStrategy,
+} from '@dnd-kit/sortable';
+import { Funnel, FunnelStage, FieldDefinition } from '../../types';
+import { StageCard } from './StageCard';
+import { AddStageButton } from './AddStageButton';
+
+export interface FunnelStageBuilderProps {
+  /** The funnel being edited */
+  funnel: Funnel;
+
+  /** Callback when funnel is updated */
+  onUpdate: (funnel: Funnel) => void;
+
+  /** Available fields for filter rules */
+  fieldRegistry: FieldDefinition[];
+
+  /** Optional CSS class */
+  className?: string;
+}
+
+/**
+ * Generate unique stage ID
+ */
+function generateStageId(): string {
+  return `stage-${Date.now()}-${Math.random().toString(36).substr(2, 9)}`;
+}
+
+/**
+ * Create a new empty stage
+ */
+function createEmptyStage(order: number): FunnelStage {
+  return {
+    id: generateStageId(),
+    order,
+    name: `Stage ${order + 1}`,
+    description: '',
+    filter_logic: 'AND',
+    rules: [],
+    match_action: 'continue',
+    no_match_action: 'continue',
+    match_tags: [],
+    no_match_tags: [],
+  };
+}
+
+/**
+ * Validate stage name uniqueness
+ */
+function validateStageName(name: string, stages: FunnelStage[], currentStageId?: string): string | null {
+  const trimmedName = name.trim();
+
+  if (!trimmedName) {
+    return 'Stage name is required';
+  }
+
+  const duplicate = stages.find(
+    s => s.id !== currentStageId && s.name.trim().toLowerCase() === trimmedName.toLowerCase()
+  );
+
+  if (duplicate) {
+    return 'Stage name must be unique';
+  }
+
+  return null;
+}
+
+/**
+ * Main FunnelStageBuilder component
+ */
+export function FunnelStageBuilder({
+  funnel,
+  onUpdate,
+  fieldRegistry,
+  className = '',
+}: FunnelStageBuilderProps) {
+  // Track expanded stages
+  const [expandedStages, setExpandedStages] = useState<Set<string>>(
+    new Set(funnel.stages.map(s => s.id))
+  );
+
+  // Validation errors
+  const [errors, setErrors] = useState<Map<string, string>>(new Map());
+
+  // Configure drag-and-drop sensors
+  const sensors = useSensors(
+    useSensor(PointerSensor),
+    useSensor(KeyboardSensor, {
+      coordinateGetter: sortableKeyboardCoordinates,
+    })
+  );
+
+  /**
+   * Toggle stage expanded/collapsed
+   */
+  const toggleExpanded = useCallback((stageId: string) => {
+    setExpandedStages(prev => {
+      const next = new Set(prev);
+      if (next.has(stageId)) {
+        next.delete(stageId);
+      } else {
+        next.add(stageId);
+      }
+      return next;
+    });
+  }, []);
+
+  /**
+   * Add new stage
+   */
+  const handleAddStage = useCallback((insertAfterIndex?: number) => {
+    const newOrder = insertAfterIndex !== undefined ? insertAfterIndex + 1 : funnel.stages.length;
+    const newStage = createEmptyStage(newOrder);
+
+    // Update orders for stages after insertion point
+    const updatedStages = funnel.stages.map(stage => {
+      if (stage.order >= newOrder) {
+        return { ...stage, order: stage.order + 1 };
+      }
+      return stage;
+    });
+
+    // Insert new stage
+    updatedStages.splice(newOrder, 0, newStage);
+
+    // Expand new stage
+    setExpandedStages(prev => new Set(prev).add(newStage.id));
+
+    onUpdate({
+      ...funnel,
+      stages: updatedStages,
+    });
+  }, [funnel, onUpdate]);
+
+  /**
+   * Remove stage
+   */
+  const handleRemoveStage = useCallback((stageId: string) => {
+    const stageIndex = funnel.stages.findIndex(s => s.id === stageId);
+    if (stageIndex === -1) return;
+
+    // Remove stage
+    const updatedStages = funnel.stages.filter(s => s.id !== stageId);
+
+    // Reorder remaining stages
+    updatedStages.forEach((stage, index) => {
+      stage.order = index;
+    });
+
+    // Remove from expanded set
+    setExpandedStages(prev => {
+      const next = new Set(prev);
+      next.delete(stageId);
+      return next;
+    });
+
+    // Remove validation errors
+    setErrors(prev => {
+      const next = new Map(prev);
+      next.delete(stageId);
+      return next;
+    });
+
+    onUpdate({
+      ...funnel,
+      stages: updatedStages,
+    });
+  }, [funnel, onUpdate]);
+
+  /**
+   * Update stage
+   */
+  const handleUpdateStage = useCallback((updatedStage: FunnelStage) => {
+    // Validate stage name
+    const nameError = validateStageName(updatedStage.name, funnel.stages, updatedStage.id);
+
+    setErrors(prev => {
+      const next = new Map(prev);
+      if (nameError) {
+        next.set(updatedStage.id, nameError);
+      } else {
+        next.delete(updatedStage.id);
+      }
+      return next;
+    });
+
+    const updatedStages = funnel.stages.map(stage =>
+      stage.id === updatedStage.id ? updatedStage : stage
+    );
+
+    onUpdate({
+      ...funnel,
+      stages: updatedStages,
+    });
+  }, [funnel, onUpdate]);
+
+  /**
+   * Handle drag end
+   */
+  const handleDragEnd = useCallback((event: DragEndEvent) => {
+    const { active, over } = event;
+
+    if (!over || active.id === over.id) {
+      return;
+    }
+
+    const oldIndex = funnel.stages.findIndex(s => s.id === active.id);
+    const newIndex = funnel.stages.findIndex(s => s.id === over.id);
+
+    if (oldIndex === -1 || newIndex === -1) {
+      return;
+    }
+
+    // Reorder stages
+    const reorderedStages = arrayMove(funnel.stages, oldIndex, newIndex);
+
+    // Update order values
+    reorderedStages.forEach((stage, index) => {
+      stage.order = index;
+    });
+
+    onUpdate({
+      ...funnel,
+      stages: reorderedStages,
+    });
+  }, [funnel, onUpdate]);
+
+  return (
+    <div className={`funnel-stage-builder ${className}`}>
+      {/* Add stage at top */}
+      <div className="mb-4">
+        <AddStageButton onClick={() => handleAddStage()} position="top" />
+      </div>
+
+      {/* Stage list with drag-and-drop */}
+      <DndContext
+        sensors={sensors}
+        collisionDetection={closestCenter}
+        onDragEnd={handleDragEnd}
+      >
+        <SortableContext
+          items={funnel.stages.map(s => s.id)}
+          strategy={verticalListSortingStrategy}
+        >
+          {funnel.stages.map((stage, index) => (
+            <div key={stage.id} className="stage-wrapper">
+              <StageCard
+                stage={stage}
+                expanded={expandedStages.has(stage.id)}
+                onToggleExpanded={() => toggleExpanded(stage.id)}
+                onUpdate={handleUpdateStage}
+                onRemove={() => handleRemoveStage(stage.id)}
+                fieldRegistry={fieldRegistry}
+                error={errors.get(stage.id)}
+                showWarnings={stage.rules.length === 0}
+              />
+
+              {/* Flow arrow between stages */}
+              {index < funnel.stages.length - 1 && (
+                <div className="stage-arrow">
+                  <svg width="24" height="24" viewBox="0 0 24 24" fill="none">
+                    <path
+                      d="M12 5v14m0 0l-4-4m4 4l4-4"
+                      stroke="currentColor"
+                      strokeWidth="2"
+                      strokeLinecap="round"
+                      strokeLinejoin="round"
+                    />
+                  </svg>
+                </div>
+              )}
+            </div>
+          ))}
+        </SortableContext>
+      </DndContext>
+
+      {/* Add stage at bottom */}
+      {funnel.stages.length > 0 && (
+        <div className="mt-4">
+          <AddStageButton
+            onClick={() => handleAddStage(funnel.stages.length - 1)}
+            position="bottom"
+          />
+        </div>
+      )}
+
+      {/* Empty state */}
+      {funnel.stages.length === 0 && (
+        <div className="empty-state">
+          <p className="text-gray-500 text-center py-8">
+            No stages yet. Add your first stage to get started.
+          </p>
+        </div>
+      )}
+    </div>
+  );
+}

package/src/components/FunnelStageBuilder/README.md

@@ -0,0 +1,341 @@
+# FunnelStageBuilder
+
+Visual builder component for creating and editing funnel stages with drag-and-drop reordering.
+
+## Overview
+
+The FunnelStageBuilder provides a complete interface for managing funnel stages:
+
+- **Drag-and-Drop Reordering** - Reorder stages visually using @dnd-kit
+- **Add/Remove Stages** - Add stages at top, bottom, or inline
+- **Stage Configuration** - Name, description, filter logic, actions, and tags
+- **Visual Flow** - Arrows showing flow between stages
+- **Expandable Cards** - Collapse stages to see high-level summary
+
+## Installation
+
+```bash
+npm install @dnd-kit/core @dnd-kit/sortable @dnd-kit/utilities react react-dom
+```
+
+## Basic Usage
+
+```tsx
+import { FunnelStageBuilder } from '@simpli/funnels/components';
+import { Funnel, FieldDefinition } from '@simpli/funnels';
+
+const fieldRegistry: FieldDefinition[] = [
+  {
+    name: 'firm.stage',
+    label: 'Investment Stage',
+    type: 'string',
+    operators: ['eq', 'ne', 'in'],
+    category: 'Firm',
+  },
+  // ... more fields
+];
+
+function MyComponent() {
+  const [funnel, setFunnel] = useState<Funnel>({
+    id: 'funnel-1',
+    name: 'My Funnel',
+    status: 'draft',
+    input_type: 'contacts',
+    stages: [],
+    created_at: new Date().toISOString(),
+    updated_at: new Date().toISOString(),
+  });
+
+  return (
+    <FunnelStageBuilder
+      funnel={funnel}
+      onUpdate={setFunnel}
+      fieldRegistry={fieldRegistry}
+    />
+  );
+}
+```
+
+## Props
+
+### FunnelStageBuilderProps
+
+| Prop | Type | Required | Description |
+|------|------|----------|-------------|
+| `funnel` | `Funnel` | Yes | The funnel being edited |
+| `onUpdate` | `(funnel: Funnel) => void` | Yes | Callback when funnel is updated |
+| `fieldRegistry` | `FieldDefinition[]` | Yes | Available fields for filter rules |
+| `className` | `string` | No | Optional CSS class |
+
+## Features
+
+### 1. Drag-and-Drop Reordering
+
+Uses @dnd-kit for accessible, performant drag-and-drop:
+
+```tsx
+// Automatically handles:
+// - Stage reordering
+// - Order value updates
+// - Visual feedback during drag
+// - Keyboard navigation (Space/Enter to grab, Arrow keys to move)
+```
+
+### 2. Add/Remove Stages
+
+```tsx
+// Add stage at top
+<AddStageButton onClick={() => handleAddStage()} position="top" />
+
+// Add stage at bottom
+<AddStageButton onClick={() => handleAddStage(lastIndex)} position="bottom" />
+
+// Remove stage
+<button onClick={() => handleRemoveStage(stageId)}>Delete</button>
+```
+
+### 3. Stage Configuration
+
+Each stage can be configured with:
+
+- **Name** - Required, must be unique
+- **Description** - Optional
+- **Filter Logic** - AND (all rules must match) or OR (at least one must match)
+- **Rules** - Array of filter rules (requires FilterRuleEditor component)
+- **Match Action** - What to do when rules match:
+  - `continue` - Continue to next stage
+  - `tag` - Add tags and stop
+  - `tag_continue` - Add tags and continue
+  - `output` - Add to output and stop
+- **No Match Action** - What to do when rules don't match:
+  - `continue` - Continue to next stage
+  - `exclude` - Exclude from output and stop
+  - `tag_exclude` - Add tags, exclude, and stop
+- **Tags** - Tags to add on match/no-match
+
+### 4. Validation
+
+Built-in validation for:
+
+- **Required name** - Stage must have a name
+- **Unique names** - No duplicate stage names
+- **Warning for empty rules** - Shows warning if stage has no filter rules
+
+```tsx
+// Validation errors shown inline
+<div className="error-message">
+  Stage name must be unique
+</div>
+
+// Warnings shown inline
+<div className="warning-message">
+  Stage has no filter rules
+</div>
+```
+
+### 5. Debounced Updates
+
+Text inputs (name, description) use debounced updates to avoid excessive callbacks:
+
+```tsx
+// Name updates after 300ms
+// Description updates after 500ms
+```
+
+## Components
+
+### FunnelStageBuilder
+
+Main container component that orchestrates all functionality.
+
+### StageCard
+
+Individual stage card with:
+- Drag handle
+- Expand/collapse toggle
+- Delete button
+- Validation errors/warnings
+- Collapsed summary
+- Expanded form
+
+### StageForm
+
+Stage configuration form with:
+- Name input
+- Description textarea
+- Filter logic toggle
+- Match/no-match actions
+- Tags input
+- Rules editor placeholder
+
+### StageActions
+
+Action dropdowns for match/no-match actions with descriptions.
+
+### TagInput
+
+Multi-tag input component:
+- Add tags with Enter or comma
+- Remove tags with click
+- Visual tag chips
+- Duplicate prevention
+
+### AddStageButton
+
+Button to add new stages with context-aware labels.
+
+## Styling
+
+The component comes with base styles in `FunnelStageBuilder.css`:
+
+```tsx
+import './FunnelStageBuilder.css';
+```
+
+Key CSS classes:
+
+- `.funnel-stage-builder` - Main container
+- `.stage-card` - Stage card
+- `.stage-header` - Card header
+- `.stage-form` - Stage configuration form
+- `.drag-handle` - Drag handle button
+- `.tag-chip` - Tag pill
+- `.error-message` - Validation error
+- `.warning-message` - Warning message
+
+Override styles by targeting these classes or passing custom `className`.
+
+## Accessibility
+
+The component follows accessibility best practices:
+
+- **Keyboard Navigation** - Full keyboard support for drag-and-drop
+- **ARIA Labels** - All interactive elements have appropriate labels
+- **Focus Management** - Logical tab order
+- **Screen Reader Support** - Semantic HTML and ARIA attributes
+
+## Testing
+
+The component includes comprehensive tests:
+
+```bash
+npm run test
+```
+
+Test coverage includes:
+
+- Rendering with 0, 1, and multiple stages
+- Adding stages at top/bottom
+- Removing stages
+- Reordering stages (drag-and-drop)
+- Expanding/collapsing stages
+- Form input changes
+- Validation (unique names, required fields)
+- Tag input (add/remove tags)
+- Action dropdowns
+
+## Integration Notes
+
+### FilterRuleEditor Integration
+
+The component includes a placeholder for the FilterRuleEditor:
+
+```tsx
+{/* TODO: Integrate FilterRuleEditor component once available */}
+<div className="rules-placeholder">
+  <p>FilterRuleEditor component will be integrated here</p>
+</div>
+```
+
+When integrating FilterRuleEditor:
+
+```tsx
+import { FilterRuleEditor } from '../FilterRuleEditor';
+
+// In StageForm.tsx
+<FilterRuleEditor
+  rules={stage.rules}
+  onUpdate={(rules) => onUpdate({ ...stage, rules })}
+  fieldRegistry={fieldRegistry}
+/>
+```
+
+### State Management
+
+The component is stateless - all state is managed by parent:
+
+```tsx
+// Parent manages funnel state
+const [funnel, setFunnel] = useState<Funnel>(...);
+
+// Component calls onUpdate when user makes changes
+<FunnelStageBuilder
+  funnel={funnel}
+  onUpdate={setFunnel}
+  fieldRegistry={fieldRegistry}
+/>
+```
+
+For global state management, wrap with your state library:
+
+```tsx
+// With Zustand
+import { useFunnelStore } from './store';
+
+function MyComponent() {
+  const { funnel, updateFunnel } = useFunnelStore();
+
+  return (
+    <FunnelStageBuilder
+      funnel={funnel}
+      onUpdate={updateFunnel}
+      fieldRegistry={fieldRegistry}
+    />
+  );
+}
+```
+
+## Examples
+
+See `FunnelStageBuilder.stories.tsx` for interactive examples:
+
+- Empty state
+- Single stage
+- Multiple stages
+- With validation errors
+- Different action combinations
+
+Run Storybook to view:
+
+```bash
+npm run storybook
+```
+
+## Generic Design
+
+This component works with **any** entity type and field registry:
+
+```tsx
+// Works for investors
+const investorFields = [
+  { name: 'firm.stage', label: 'Stage', type: 'string', operators: ['eq'] },
+];
+
+// Works for recipes
+const recipeFields = [
+  { name: 'recipe.cuisine', label: 'Cuisine', type: 'string', operators: ['eq'] },
+];
+
+// Works for leads
+const leadFields = [
+  { name: 'lead.score', label: 'Score', type: 'number', operators: ['gt'] },
+];
+
+// Same component, different field registries!
+```
+
+No domain-specific logic. Pure, generic UI.
+
+## License
+
+MIT