@startsimpli/funnels 0.1.4 → 0.1.5

package/src/components/FunnelPreview/README.md

@@ -0,0 +1,337 @@
+# FunnelPreview Component
+
+Real-time preview of funnel execution on sample entities.
+
+## Purpose
+
+Shows users how their funnel configuration affects entities BEFORE running the full funnel. Updates automatically as they edit filter rules, providing instant feedback on match rates and stage-by-stage results.
+
+## Usage
+
+### Basic Example
+
+```tsx
+import { FunnelPreview } from '@simpli/funnels';
+
+function MyComponent() {
+  const funnel = {
+    id: 'my-funnel',
+    name: 'Investor Qualification',
+    status: 'active',
+    input_type: 'contacts',
+    stages: [
+      {
+        id: 'stage-1',
+        order: 0,
+        name: 'Series A or Later',
+        filter_logic: 'AND',
+        rules: [
+          {
+            field_path: 'firm.stage',
+            operator: 'in',
+            value: ['Series A', 'Series B', 'Series C'],
+          },
+        ],
+        match_action: 'continue',
+        no_match_action: 'exclude',
+      },
+    ],
+    created_at: new Date().toISOString(),
+    updated_at: new Date().toISOString(),
+  };
+
+  const sampleInvestors = [
+    { name: 'John Doe', firm: { name: 'Acme VC', stage: 'Series A' }, score: 85 },
+    { name: 'Jane Smith', firm: { name: 'TechCo', stage: 'Seed' }, score: 92 },
+    // ... more investors
+  ];
+
+  return (
+    <FunnelPreview
+      funnel={funnel}
+      sampleEntities={sampleInvestors}
+    />
+  );
+}
+```
+
+### With Custom Entity Renderer
+
+```tsx
+<FunnelPreview
+  funnel={funnel}
+  sampleEntities={investors}
+  renderEntity={(investor) => (
+    <div>
+      <div className="font-medium">{investor.name}</div>
+      <div className="text-sm text-gray-600">
+        {investor.firm.name} · {investor.firm.stage} · Score: {investor.score}
+      </div>
+    </div>
+  )}
+/>
+```
+
+### With Preview Callback
+
+```tsx
+<FunnelPreview
+  funnel={funnel}
+  sampleEntities={entities}
+  onPreview={(result) => {
+    console.log('Matched:', result.totalMatched);
+    console.log('Excluded:', result.totalExcluded);
+    console.log('Match %:', result.matchPercentage);
+  }}
+/>
+```
+
+### Customize Preview Limit
+
+```tsx
+<FunnelPreview
+  funnel={funnel}
+  sampleEntities={entities}
+  maxPreviewEntities={20}  // Show up to 20 entities (default: 10)
+/>
+```
+
+## Props
+
+| Prop | Type | Required | Default | Description |
+|------|------|----------|---------|-------------|
+| `funnel` | `Funnel` | Yes | - | The funnel to preview |
+| `sampleEntities` | `any[]` | Yes | - | Sample entities to process |
+| `onPreview` | `(result: PreviewResult) => void` | No | - | Callback when preview updates |
+| `renderEntity` | `(entity: any) => ReactNode` | No | Default renderer | Custom entity display |
+| `maxPreviewEntities` | `number` | No | `10` | Max entities to show |
+| `className` | `string` | No | `''` | Additional CSS classes |
+
+## Preview Result
+
+The `onPreview` callback receives a `PreviewResult`:
+
+```typescript
+interface PreviewResult {
+  totalMatched: number;
+  totalExcluded: number;
+  matchPercentage: number;
+  previewEntities: any[];
+  stageStats: Record<string, StagePreviewStats>;
+}
+
+interface StagePreviewStats {
+  stage_id: string;
+  stage_name: string;
+  input_count: number;
+  excluded_count: number;
+  remaining_count: number;
+}
+```
+
+## Features
+
+### Debounced Updates
+
+Preview automatically re-computes when funnel or entities change, with a 300ms debounce to prevent excessive computation during editing.
+
+### Loading States
+
+Shows skeleton UI on initial load and a subtle overlay during updates.
+
+### Empty States
+
+Displays helpful message when no entities match the funnel.
+
+### Stage Breakdown
+
+Visual flow showing how many entities are filtered at each stage.
+
+### Match Statistics
+
+Progress bar and counts showing overall funnel effectiveness.
+
+## Subcomponents
+
+All subcomponents are exported and can be used independently:
+
+### PreviewStats
+
+Shows matched vs excluded counts with progress bar.
+
+```tsx
+import { PreviewStats } from '@simpli/funnels';
+
+<PreviewStats
+  totalMatched={235}
+  totalExcluded={765}
+  matchPercentage={23.5}
+/>
+```
+
+### StageBreakdown
+
+Shows per-stage statistics in funnel flow.
+
+```tsx
+import { StageBreakdown } from '@simpli/funnels';
+
+<StageBreakdown
+  stageStats={stageStats}
+  stages={funnel.stages}
+/>
+```
+
+### EntityCard
+
+Displays a single entity with custom renderer.
+
+```tsx
+import { EntityCard } from '@simpli/funnels';
+
+<EntityCard
+  entity={investor}
+  renderEntity={(inv) => (
+    <div>{inv.name} - {inv.firm.name}</div>
+  )}
+/>
+```
+
+### LoadingPreview
+
+Skeleton loading state.
+
+```tsx
+import { LoadingPreview } from '@simpli/funnels';
+
+{isLoading && <LoadingPreview />}
+```
+
+## Examples
+
+### Recipe Funnel
+
+```tsx
+const recipeFunnel = {
+  id: 'recipe-filter',
+  name: 'Recipe Recommendations',
+  status: 'active',
+  input_type: 'any',
+  stages: [
+    {
+      id: 'dietary',
+      order: 0,
+      name: 'Dietary Restrictions',
+      filter_logic: 'AND',
+      rules: [
+        { field_path: 'tags', operator: 'has_tag', value: 'vegetarian' },
+      ],
+      match_action: 'continue',
+      no_match_action: 'exclude',
+    },
+  ],
+  created_at: new Date().toISOString(),
+  updated_at: new Date().toISOString(),
+};
+
+<FunnelPreview
+  funnel={recipeFunnel}
+  sampleEntities={recipes}
+  renderEntity={(recipe) => (
+    <div>
+      <div className="font-medium">{recipe.name}</div>
+      <div className="text-sm text-gray-600">
+        {recipe.cuisine} · {recipe.difficulty} · {recipe.cookTime}
+      </div>
+    </div>
+  )}
+/>
+```
+
+### Lead Scoring Funnel
+
+```tsx
+const leadFunnel = {
+  id: 'lead-scoring',
+  name: 'Qualified Leads',
+  status: 'active',
+  input_type: 'any',
+  stages: [
+    {
+      id: 'company-size',
+      order: 0,
+      name: 'Company Size',
+      filter_logic: 'AND',
+      rules: [
+        { field_path: 'company.employees', operator: 'gte', value: 50 },
+      ],
+      match_action: 'continue',
+      no_match_action: 'exclude',
+    },
+    {
+      id: 'engagement',
+      order: 1,
+      name: 'Engagement Score',
+      filter_logic: 'AND',
+      rules: [
+        { field_path: 'engagement_score', operator: 'gte', value: 7 },
+      ],
+      match_action: 'output',
+      no_match_action: 'exclude',
+    },
+  ],
+  created_at: new Date().toISOString(),
+  updated_at: new Date().toISOString(),
+};
+
+<FunnelPreview
+  funnel={leadFunnel}
+  sampleEntities={leads}
+  renderEntity={(lead) => (
+    <div>
+      <div className="font-medium">{lead.name}</div>
+      <div className="text-sm text-gray-600">
+        {lead.company.name} · {lead.company.employees} employees · Score: {lead.engagement_score}
+      </div>
+    </div>
+  )}
+/>
+```
+
+## Accessibility
+
+- ARIA progressbar role on stats bar
+- ARIA live region announces updates
+- Loading states communicated to screen readers
+- Keyboard navigation through entity cards
+- Color is supplementary (text labels provide meaning)
+- Sufficient color contrast (WCAG AA)
+
+## Performance
+
+- Debounced updates (300ms) prevent excessive re-computation
+- Efficient execution via FunnelEngine
+- Limits preview entities (default 10) for fast rendering
+- Skeleton UI reduces perceived loading time
+
+## Design System
+
+Uses Tailwind CSS classes matching the Simpli design system:
+
+- Colors: `blue-*` (input), `green-*` (matched), `red-*` (excluded), `gray-*` (neutral)
+- Spacing: `gap-2`, `gap-3`, `mb-3`, `mb-6`
+- Typography: `text-sm`, `text-lg`, `font-medium`, `font-semibold`
+- Borders: `rounded-lg`, `border-gray-200`
+- Shadows: `shadow-sm`
+
+## BRUTALLY GENERIC
+
+Works with ANY entity type:
+
+- Investors, firms, contacts, organizations
+- Recipes, ingredients, cooking instructions
+- Leads, opportunities, tasks, projects
+- GitHub repos, PRs, issues, users
+- Products, orders, customers, shipments
+
+No domain-specific logic. All filtering based on generic field paths and operators.

package/src/components/FunnelPreview/StageBreakdown.tsx

@@ -0,0 +1,94 @@
+/**
+ * StageBreakdown Component
+ *
+ * Shows per-stage statistics in a funnel flow visualization.
+ *
+ * Design Rationale:
+ * - Sequential list shows funnel flow from top to bottom
+ * - Stage numbers (①②③) provide clear ordering
+ * - Exclusion count (-N) shows entities removed at each stage
+ * - Remaining count shows entities continuing to next stage
+ * - Color coding: gray for excluded, green for final matched
+ *
+ * Accessibility:
+ * - Semantic list structure
+ * - Clear text labels for all metrics
+ * - Color is supplementary to text
+ */
+
+import type { StageStats } from '../../types';
+
+export interface StagePreviewStats {
+  stage_id: string;
+  stage_name: string;
+  input_count: number;
+  excluded_count: number;
+  remaining_count: number;
+}
+
+interface StageBreakdownProps {
+  stageStats: Record<string, StagePreviewStats>;
+  stages: Array<{ id: string; name: string; order: number }>;
+  className?: string;
+}
+
+export function StageBreakdown({
+  stageStats,
+  stages,
+  className = '',
+}: StageBreakdownProps) {
+  // Sort stages by order
+  const sortedStages = [...stages].sort((a, b) => a.order - b.order);
+
+  return (
+    <div className={className}>
+      <h3 className="text-sm font-semibold text-gray-700 mb-3">
+        Stage Breakdown
+      </h3>
+
+      <ol className="space-y-2">
+        {sortedStages.map((stage, index) => {
+          const stats = stageStats[stage.id];
+          if (!stats) return null;
+
+          const isLast = index === sortedStages.length - 1;
+          const excludedCount = stats.excluded_count;
+          const remainingCount = stats.remaining_count;
+
+          return (
+            <li
+              key={stage.id}
+              className="flex items-center justify-between py-2 px-3 bg-gray-50 rounded-lg"
+            >
+              {/* Stage info */}
+              <div className="flex items-center gap-2 flex-1 min-w-0">
+                <span className="flex-shrink-0 w-6 h-6 flex items-center justify-center bg-blue-100 text-blue-700 rounded-full text-xs font-bold">
+                  {index + 1}
+                </span>
+                <span className="text-sm font-medium text-gray-900 truncate">
+                  {stage.name}
+                </span>
+              </div>
+
+              {/* Stats */}
+              <div className="flex items-center gap-3 text-sm">
+                {excludedCount > 0 && (
+                  <span className="text-red-600 font-medium">
+                    -{excludedCount.toLocaleString()}
+                  </span>
+                )}
+                <span
+                  className={`font-semibold ${
+                    isLast ? 'text-green-600' : 'text-gray-700'
+                  }`}
+                >
+                  {remainingCount.toLocaleString()} {isLast ? 'final' : 'left'}
+                </span>
+              </div>
+            </li>
+          );
+        })}
+      </ol>
+    </div>
+  );
+}

package/src/components/FunnelPreview/example.tsx

@@ -0,0 +1,286 @@
+/**
+ * FunnelPreview Example Usage
+ *
+ * This file shows how to use the FunnelPreview component
+ * in different scenarios.
+ */
+
+import { FunnelPreview } from './FunnelPreview';
+import type { Funnel } from '../../types';
+
+// ============================================================================
+// Example 1: Investor Qualification Funnel
+// ============================================================================
+
+const investorFunnel: Funnel = {
+  id: 'investor-qualification',
+  name: 'Investor Qualification',
+  description: 'Filter investors by firm stage and check size',
+  status: 'active',
+  input_type: 'contacts',
+  stages: [
+    {
+      id: 'stage-1',
+      order: 0,
+      name: 'Series A or Later',
+      filter_logic: 'OR',
+      rules: [
+        { field_path: 'firm.stage', operator: 'eq', value: 'Series A' },
+        { field_path: 'firm.stage', operator: 'eq', value: 'Series B' },
+        { field_path: 'firm.stage', operator: 'eq', value: 'Series C' },
+      ],
+      match_action: 'continue',
+      no_match_action: 'exclude',
+    },
+    {
+      id: 'stage-2',
+      order: 1,
+      name: 'High ICP Score',
+      filter_logic: 'AND',
+      rules: [{ field_path: 'icp_score', operator: 'gte', value: 80 }],
+      match_action: 'output',
+      no_match_action: 'exclude',
+    },
+  ],
+  created_at: new Date().toISOString(),
+  updated_at: new Date().toISOString(),
+};
+
+const sampleInvestors = [
+  {
+    name: 'John Doe',
+    firm: { name: 'Acme VC', stage: 'Series A' },
+    icp_score: 85,
+    email: 'john@acme.vc',
+  },
+  {
+    name: 'Jane Smith',
+    firm: { name: 'TechCo Ventures', stage: 'Seed' },
+    icp_score: 92,
+    email: 'jane@techco.com',
+  },
+  {
+    name: 'Bob Wilson',
+    firm: { name: 'Growth Capital', stage: 'Series B' },
+    icp_score: 78,
+    email: 'bob@growth.capital',
+  },
+  {
+    name: 'Alice Johnson',
+    firm: { name: 'Early Stage Fund', stage: 'Series A' },
+    icp_score: 88,
+    email: 'alice@earlystage.fund',
+  },
+];
+
+export function InvestorQualificationExample() {
+  return (
+    <div className="max-w-2xl mx-auto p-6">
+      <h1 className="text-2xl font-bold mb-6">Investor Qualification Preview</h1>
+
+      <FunnelPreview
+        funnel={investorFunnel}
+        sampleEntities={sampleInvestors}
+        renderEntity={(investor) => (
+          <div>
+            <div className="font-medium text-gray-900">{investor.name}</div>
+            <div className="text-sm text-gray-600 mt-1">
+              {investor.firm.name} · {investor.firm.stage} · ICP Score:{' '}
+              {investor.icp_score}
+            </div>
+            <div className="text-xs text-gray-500 mt-0.5">{investor.email}</div>
+          </div>
+        )}
+        onPreview={(result) => {
+          console.log('Preview updated:', {
+            matched: result.totalMatched,
+            excluded: result.totalExcluded,
+            percentage: result.matchPercentage,
+          });
+        }}
+      />
+    </div>
+  );
+}
+
+// ============================================================================
+// Example 2: Recipe Filtering
+// ============================================================================
+
+const recipeFunnel: Funnel = {
+  id: 'recipe-filter',
+  name: 'Recipe Recommendations',
+  description: 'Filter recipes by dietary restrictions and difficulty',
+  status: 'active',
+  input_type: 'any',
+  stages: [
+    {
+      id: 'dietary',
+      order: 0,
+      name: 'Vegetarian',
+      filter_logic: 'AND',
+      rules: [{ field_path: 'tags', operator: 'has_tag', value: 'vegetarian' }],
+      match_action: 'continue',
+      no_match_action: 'exclude',
+    },
+    {
+      id: 'difficulty',
+      order: 1,
+      name: 'Easy to Moderate',
+      filter_logic: 'OR',
+      rules: [
+        { field_path: 'difficulty', operator: 'eq', value: 'easy' },
+        { field_path: 'difficulty', operator: 'eq', value: 'moderate' },
+      ],
+      match_action: 'output',
+      no_match_action: 'exclude',
+    },
+  ],
+  created_at: new Date().toISOString(),
+  updated_at: new Date().toISOString(),
+};
+
+const sampleRecipes = [
+  {
+    name: 'Vegetable Stir Fry',
+    cuisine: 'Asian',
+    difficulty: 'easy',
+    cookTime: '20 min',
+    tags: ['vegetarian', 'quick', 'healthy'],
+  },
+  {
+    name: 'Beef Tacos',
+    cuisine: 'Mexican',
+    difficulty: 'easy',
+    cookTime: '30 min',
+    tags: ['quick', 'family-friendly'],
+  },
+  {
+    name: 'Veggie Curry',
+    cuisine: 'Indian',
+    difficulty: 'moderate',
+    cookTime: '45 min',
+    tags: ['vegetarian', 'spicy'],
+  },
+];
+
+export function RecipeFilterExample() {
+  return (
+    <div className="max-w-2xl mx-auto p-6">
+      <h1 className="text-2xl font-bold mb-6">Recipe Filter Preview</h1>
+
+      <FunnelPreview
+        funnel={recipeFunnel}
+        sampleEntities={sampleRecipes}
+        renderEntity={(recipe) => (
+          <div>
+            <div className="font-medium text-gray-900">{recipe.name}</div>
+            <div className="text-sm text-gray-600 mt-1">
+              {recipe.cuisine} · {recipe.difficulty} · {recipe.cookTime}
+            </div>
+            <div className="text-xs text-gray-500 mt-1">
+              {recipe.tags.join(', ')}
+            </div>
+          </div>
+        )}
+        maxPreviewEntities={5}
+      />
+    </div>
+  );
+}
+
+// ============================================================================
+// Example 3: Lead Scoring
+// ============================================================================
+
+const leadFunnel: Funnel = {
+  id: 'lead-scoring',
+  name: 'Qualified Leads',
+  description: 'Score and filter leads based on company size and engagement',
+  status: 'active',
+  input_type: 'any',
+  stages: [
+    {
+      id: 'company-size',
+      order: 0,
+      name: 'Mid-Market and Above',
+      filter_logic: 'AND',
+      rules: [{ field_path: 'company.employees', operator: 'gte', value: 50 }],
+      match_action: 'continue',
+      no_match_action: 'exclude',
+    },
+    {
+      id: 'engagement',
+      order: 1,
+      name: 'High Engagement',
+      filter_logic: 'AND',
+      rules: [{ field_path: 'engagement_score', operator: 'gte', value: 7 }],
+      match_action: 'tag_continue',
+      no_match_action: 'continue',
+      match_tags: ['high-engagement'],
+    },
+    {
+      id: 'industry',
+      order: 2,
+      name: 'Target Industries',
+      filter_logic: 'OR',
+      rules: [
+        { field_path: 'company.industry', operator: 'eq', value: 'Technology' },
+        { field_path: 'company.industry', operator: 'eq', value: 'SaaS' },
+        { field_path: 'company.industry', operator: 'eq', value: 'FinTech' },
+      ],
+      match_action: 'output',
+      no_match_action: 'exclude',
+    },
+  ],
+  created_at: new Date().toISOString(),
+  updated_at: new Date().toISOString(),
+};
+
+const sampleLeads = [
+  {
+    name: 'Sarah Chen',
+    title: 'VP of Engineering',
+    company: { name: 'TechCorp', industry: 'Technology', employees: 150 },
+    engagement_score: 8,
+  },
+  {
+    name: 'Mike Brown',
+    title: 'CTO',
+    company: { name: 'SmallCo', industry: 'Retail', employees: 20 },
+    engagement_score: 9,
+  },
+  {
+    name: 'Lisa Wang',
+    title: 'Head of Product',
+    company: { name: 'FinanceApp', industry: 'FinTech', employees: 200 },
+    engagement_score: 6,
+  },
+];
+
+export function LeadScoringExample() {
+  return (
+    <div className="max-w-2xl mx-auto p-6">
+      <h1 className="text-2xl font-bold mb-6">Lead Scoring Preview</h1>
+
+      <FunnelPreview
+        funnel={leadFunnel}
+        sampleEntities={sampleLeads}
+        renderEntity={(lead) => (
+          <div>
+            <div className="font-medium text-gray-900">
+              {lead.name} - {lead.title}
+            </div>
+            <div className="text-sm text-gray-600 mt-1">
+              {lead.company.name} · {lead.company.industry} ·{' '}
+              {lead.company.employees} employees
+            </div>
+            <div className="text-xs text-gray-500 mt-0.5">
+              Engagement Score: {lead.engagement_score}/10
+            </div>
+          </div>
+        )}
+      />
+    </div>
+  );
+}