@startsimpli/funnels 0.1.4 → 0.1.6

package/src/components/FunnelVisualFlow/README.md

@@ -0,0 +1,323 @@
+# FunnelVisualFlow Component
+
+Interactive funnel visualization using React Flow. Shows funnel stages as nodes in a vertical flow with edges connecting them, displaying entity counts and exclusions between stages.
+
+## Features
+
+- **Visual Stage Flow**: Stages displayed as nodes with vertical layout
+- **Run Statistics**: Shows input/matched/excluded counts when run data provided
+- **Color-Coded Actions**: Nodes colored by action type (continue=blue, exclude=red, tag=yellow, output=green)
+- **Interactive**: Click stages for details, click edges to see excluded entities
+- **Auto-Layout**: Vertical flow with automatic positioning
+- **Zoom & Pan**: React Flow controls for navigation
+- **Responsive**: Works on mobile, tablet, and desktop
+
+## Installation
+
+The component is part of `@simpli/funnels`. React Flow is included as a dependency.
+
+```bash
+npm install @xyflow/react
+```
+
+## Basic Usage
+
+```tsx
+import { FunnelVisualFlow } from '@simpli/funnels';
+
+function MyFunnelView() {
+  const funnel = {
+    id: 'funnel-1',
+    name: 'Frontend Developer Funnel',
+    stages: [
+      {
+        id: 'stage-1',
+        order: 0,
+        name: 'High ICP Score',
+        filter_logic: 'AND',
+        rules: [{ field_path: 'score', operator: 'gte', value: 50 }],
+        match_action: 'continue',
+        no_match_action: 'exclude',
+      },
+      // ... more stages
+    ],
+    // ... other funnel properties
+  };
+
+  return (
+    <FunnelVisualFlow
+      funnel={funnel}
+      height={600}
+    />
+  );
+}
+```
+
+## With Run Data
+
+Show statistics from a funnel run:
+
+```tsx
+import { FunnelVisualFlow } from '@simpli/funnels';
+
+function MyFunnelView() {
+  const runData = {
+    id: 'run-1',
+    funnel_id: 'funnel-1',
+    status: 'completed',
+    trigger_type: 'manual',
+    started_at: new Date().toISOString(),
+    total_input: 1000,
+    total_matched: 235,
+    total_excluded: 765,
+    total_tagged: 0,
+    stage_stats: {
+      'stage-1': {
+        stage_id: 'stage-1',
+        stage_name: 'High ICP Score',
+        input_count: 1000,
+        matched_count: 500,
+        not_matched_count: 500,
+        excluded_count: 500,
+        tagged_count: 0,
+        continued_count: 500,
+      },
+      // ... more stage stats
+    },
+  };
+
+  return (
+    <FunnelVisualFlow
+      funnel={funnel}
+      runData={runData}
+      height={600}
+    />
+  );
+}
+```
+
+## Interactive Mode
+
+Handle clicks on stages and edges:
+
+```tsx
+function MyFunnelView() {
+  const handleStageClick = (stage: FunnelStage) => {
+    console.log('Clicked stage:', stage.name);
+    // Show stage details modal, etc.
+  };
+
+  const handleEdgeClick = (fromStageId: string, toStageId: string) => {
+    console.log('Clicked edge:', fromStageId, '->', toStageId);
+    // Show excluded entities, etc.
+  };
+
+  return (
+    <FunnelVisualFlow
+      funnel={funnel}
+      runData={runData}
+      onStageClick={handleStageClick}
+      onEdgeClick={handleEdgeClick}
+      height={600}
+    />
+  );
+}
+```
+
+## Props
+
+### FunnelVisualFlowProps
+
+| Prop | Type | Required | Description |
+|------|------|----------|-------------|
+| `funnel` | `Funnel` | Yes | Funnel definition to visualize |
+| `runData` | `FunnelRun` | No | Optional run data for showing counts |
+| `onStageClick` | `(stage: FunnelStage) => void` | No | Callback when stage node is clicked |
+| `onEdgeClick` | `(fromStage: string, toStage: string) => void` | No | Callback when edge is clicked |
+| `className` | `string` | No | Additional CSS classes |
+| `height` | `number \| string` | No | Height of flow container (default: 600px) |
+
+## Visual Design
+
+### Node Colors (by Action Type)
+
+- **Blue** (#3b82f6): Continue to next stage
+- **Red** (#ef4444): Exclude entities
+- **Yellow** (#eab308): Tag entities
+- **Green** (#22c55e): Final output
+
+### Node Layout
+
+```
+┌──────────────────────┐
+│   ① High ICP Score   │  ← Circled number (①②③)
+│   3 rules            │  ← Rule count
+│   Continue           │  ← Action label
+├──────────────────────┤
+│ Input:      1000     │  ← Statistics (when run data provided)
+│ Matched:     500     │
+│ Excluded:    500     │
+└──────────────────────┘
+```
+
+### Edge Labels
+
+Edges show the number of entities excluded between stages:
+```
+Stage 1 (500 continued)
+    ↓ -500           ← 500 entities excluded
+Stage 2 (350 continued)
+```
+
+## Keyboard Navigation
+
+- **Tab**: Navigate between nodes
+- **Enter/Space**: Activate focused node
+- **+/-**: Zoom in/out
+- **Arrow keys**: Pan the view
+
+## Customization
+
+### Custom Height
+
+```tsx
+<FunnelVisualFlow
+  funnel={funnel}
+  height="100vh"  // Full viewport height
+/>
+```
+
+### Custom Styling
+
+```tsx
+<FunnelVisualFlow
+  funnel={funnel}
+  className="my-custom-flow"
+/>
+```
+
+```css
+.my-custom-flow {
+  border: 2px solid #e5e7eb;
+  border-radius: 12px;
+}
+
+/* Customize node appearance */
+.my-custom-flow .stage-node {
+  box-shadow: 0 4px 12px rgba(0, 0, 0, 0.2);
+}
+
+/* Customize edge appearance */
+.my-custom-flow .react-flow__edge-path {
+  stroke-width: 3;
+}
+```
+
+## Empty State
+
+When a funnel has no stages, an empty state is shown:
+
+```tsx
+<FunnelVisualFlow funnel={emptyFunnel} />
+// Renders: "No stages to visualize"
+```
+
+## Components
+
+### StageNode
+
+Custom React Flow node component for stages. Automatically used by FunnelVisualFlow.
+
+```tsx
+import { StageNode } from '@simpli/funnels';
+```
+
+### FlowLegend
+
+Legend panel explaining color coding. Automatically included in FunnelVisualFlow.
+
+```tsx
+import { FlowLegend } from '@simpli/funnels';
+```
+
+## Utilities
+
+### getCircledNumber
+
+Converts numbers to circled number characters (①②③):
+
+```tsx
+import { getCircledNumber } from '@simpli/funnels';
+
+getCircledNumber(1);  // '①'
+getCircledNumber(2);  // '②'
+getCircledNumber(10); // '⑩'
+getCircledNumber(11); // '11' (plain number for > 10)
+```
+
+## Accessibility
+
+- **Keyboard Navigation**: Full keyboard support via React Flow
+- **ARIA Labels**: All interactive elements have proper labels
+- **Focus Indicators**: Visible focus rings for keyboard navigation
+- **Color + Text**: Not relying on color alone (action labels provided)
+- **Screen Reader**: Semantic HTML with proper roles
+
+## Performance
+
+- **Virtualization**: React Flow handles large graphs efficiently
+- **Memoization**: Node and edge calculations are memoized
+- **CSS-only**: No images, pure CSS styling
+- **Lazy Rendering**: Only visible nodes are rendered
+
+## Browser Support
+
+- Chrome/Edge: Full support
+- Firefox: Full support
+- Safari: Full support
+- Mobile browsers: Full support with touch gestures
+
+## Examples
+
+See `FunnelVisualFlow.stories.tsx` for comprehensive examples:
+
+- Empty state
+- Single stage
+- Simple funnel (3 stages)
+- Complex funnel (5+ stages)
+- With run data
+- Different action types
+- Interactive mode
+- Large funnels (10+ stages)
+
+## Generic Design
+
+This component is **BRUTALLY GENERIC** and works with any funnel structure:
+
+- Investor qualification funnels
+- Recipe recommendation funnels
+- Lead scoring funnels
+- Task prioritization funnels
+- Any sequential filtering workflow
+
+No domain-specific logic—purely visualizes the funnel structure.
+
+## Testing
+
+Tests cover:
+
+- Rendering with 0, 1, and multiple stages
+- Rendering with/without run data
+- Click callbacks
+- Custom props
+- Utility functions
+
+Run tests:
+
+```bash
+npm run test -- FunnelVisualFlow.test
+```
+
+## License
+
+Part of the @simpli/funnels package.

package/src/components/FunnelVisualFlow/StageNode.tsx

@@ -0,0 +1,188 @@
+/**
+ * StageNode Component
+ *
+ * Custom React Flow node representing a funnel stage.
+ *
+ * Visual Design:
+ * - Circled number indicator (①②③)
+ * - Stage name (truncated if too long)
+ * - Rule count
+ * - Match/exclude counts (if run data available)
+ * - Color-coded border based on action type
+ *
+ * Color Coding:
+ * - Continue: Blue (#3b82f6)
+ * - Exclude/Tag+Exclude: Red (#ef4444)
+ * - Tag/Tag+Continue: Yellow (#eab308)
+ * - Output: Green (#22c55e)
+ *
+ * Interaction:
+ * - Hover: Border darkens, shadow increases
+ * - Click: Triggers onStageClick callback
+ * - Focus: Keyboard accessible with ring outline
+ *
+ * Accessibility:
+ * - Semantic HTML with proper roles
+ * - ARIA labels for screen readers
+ * - Keyboard navigation support
+ */
+
+import React from 'react';
+import { Handle, Position, NodeProps } from '@xyflow/react';
+import { FunnelStage, StageStats, MatchAction, NoMatchAction } from '../../types';
+import { getCircledNumber } from './FunnelVisualFlow';
+
+export interface StageNodeData {
+  stage: FunnelStage;
+  stats?: StageStats;
+  onStageClick?: (stage: FunnelStage) => void;
+}
+
+/**
+ * Get color based on stage actions
+ */
+function getStageColor(stage: FunnelStage): string {
+  // Primary action determines color
+  const matchAction = stage.match_action;
+  const noMatchAction = stage.no_match_action;
+
+  // Output stages are green
+  if (matchAction === 'output') {
+    return '#22c55e'; // green-500
+  }
+
+  // Exclude stages are red
+  if (noMatchAction === 'exclude' || noMatchAction === 'tag_exclude') {
+    return '#ef4444'; // red-500
+  }
+
+  // Tag stages are yellow
+  if (matchAction === 'tag' || matchAction === 'tag_continue') {
+    return '#eab308'; // yellow-500
+  }
+
+  // Default: continue is blue
+  return '#3b82f6'; // blue-500
+}
+
+/**
+ * Get action label for display
+ */
+function getActionLabel(stage: FunnelStage): string {
+  const matchAction = stage.match_action;
+  const noMatchAction = stage.no_match_action;
+
+  if (matchAction === 'output') return 'Output';
+  if (noMatchAction === 'exclude') return 'Exclude Non-Matches';
+  if (noMatchAction === 'tag_exclude') return 'Tag & Exclude';
+  if (matchAction === 'tag') return 'Tag Matches';
+  if (matchAction === 'tag_continue') return 'Tag & Continue';
+
+  return 'Continue';
+}
+
+export function StageNode({ data }: NodeProps) {
+  const { stage, stats, onStageClick } = data as unknown as StageNodeData;
+  const color = getStageColor(stage);
+  const actionLabel = getActionLabel(stage);
+
+  const handleClick = () => {
+    if (onStageClick) {
+      onStageClick(stage);
+    }
+  };
+
+  const handleKeyDown = (event: React.KeyboardEvent) => {
+    if (event.key === 'Enter' || event.key === ' ') {
+      event.preventDefault();
+      handleClick();
+    }
+  };
+
+  return (
+    <>
+      {/* Input handle (top) - hidden for first stage */}
+      <Handle
+        type="target"
+        position={Position.Top}
+        style={{ background: color, opacity: 0 }}
+        isConnectable={false}
+      />
+
+      <div
+        className="stage-node"
+        onClick={handleClick}
+        onKeyDown={handleKeyDown}
+        role="button"
+        tabIndex={0}
+        aria-label={`Stage ${stage.order + 1}: ${stage.name}`}
+        style={{
+          borderColor: color,
+          borderWidth: '2px',
+          borderStyle: 'solid',
+        }}
+      >
+        {/* Stage number */}
+        <div className="stage-number" style={{ color }}>
+          {getCircledNumber(stage.order + 1)}
+        </div>
+
+        {/* Stage name */}
+        <div className="stage-name" title={stage.name}>
+          {stage.name}
+        </div>
+
+        {/* Rule count */}
+        <div className="stage-rules">
+          {stage.rules.length} {stage.rules.length === 1 ? 'rule' : 'rules'}
+        </div>
+
+        {/* Action label */}
+        <div className="stage-action" style={{ color }}>
+          {actionLabel}
+        </div>
+
+        {/* Stats (if available) */}
+        {stats && (
+          <div className="stage-stats">
+            <div className="stat-row">
+              <span className="stat-label">Input:</span>
+              <span className="stat-value">{stats.input_count}</span>
+            </div>
+            <div className="stat-row">
+              <span className="stat-label">Matched:</span>
+              <span className="stat-value text-green-600">
+                {stats.matched_count}
+              </span>
+            </div>
+            {stats.excluded_count > 0 && (
+              <div className="stat-row">
+                <span className="stat-label">Excluded:</span>
+                <span className="stat-value text-red-600">
+                  {stats.excluded_count}
+                </span>
+              </div>
+            )}
+          </div>
+        )}
+
+        {/* Description tooltip */}
+        {stage.description && (
+          <div className="stage-description" title={stage.description}>
+            {stage.description.length > 50
+              ? `${stage.description.substring(0, 50)}...`
+              : stage.description}
+          </div>
+        )}
+      </div>
+
+      {/* Output handle (bottom) - hidden for last stage */}
+      <Handle
+        type="source"
+        position={Position.Bottom}
+        style={{ background: color, opacity: 0 }}
+        isConnectable={false}
+      />
+    </>
+  );
+}