@startsimpli/funnels 0.1.4 → 0.1.6

package/src/components/FunnelCard/StatusBadge.tsx

@@ -0,0 +1,52 @@
+/**
+ * StatusBadge Component
+ *
+ * Displays funnel status as a color-coded pill badge.
+ *
+ * Design Rationale:
+ * - Pill shape provides soft, approachable aesthetic
+ * - Color coding enables instant status recognition
+ * - Uppercase text improves scannability
+ */
+
+import { FunnelStatus } from '../../types';
+
+interface StatusBadgeProps {
+  status: FunnelStatus;
+  className?: string;
+}
+
+const statusConfig: Record<FunnelStatus, { color: string; bgColor: string; label: string }> = {
+  active: {
+    color: 'text-green-800',
+    bgColor: 'bg-green-100',
+    label: 'ACTIVE',
+  },
+  draft: {
+    color: 'text-yellow-800',
+    bgColor: 'bg-yellow-100',
+    label: 'DRAFT',
+  },
+  paused: {
+    color: 'text-gray-800',
+    bgColor: 'bg-gray-100',
+    label: 'PAUSED',
+  },
+  archived: {
+    color: 'text-red-800',
+    bgColor: 'bg-red-100',
+    label: 'ARCHIVED',
+  },
+};
+
+export function StatusBadge({ status, className = '' }: StatusBadgeProps) {
+  const config = statusConfig[status];
+
+  return (
+    <span
+      className={`inline-flex items-center px-2.5 py-0.5 rounded-full text-xs font-medium ${config.bgColor} ${config.color} ${className}`}
+    >
+      {config.label}
+    </span>
+  );
+}

package/src/components/FunnelCard/index.ts

@@ -0,0 +1,14 @@
+/**
+ * FunnelCard Component Exports
+ *
+ * Main export: FunnelCard
+ * Sub-components exported for composition flexibility
+ */
+
+export { FunnelCard } from './FunnelCard';
+export type { FunnelCardProps } from './FunnelCard';
+
+export { StatusBadge } from './StatusBadge';
+export { StageIndicator } from './StageIndicator';
+export { MatchBar } from './MatchBar';
+export { FunnelStats } from './FunnelStats';

package/src/components/FunnelPreview/EntityCard.tsx

@@ -0,0 +1,72 @@
+/**
+ * EntityCard Component
+ *
+ * Displays a single entity in the preview list.
+ * Supports custom rendering via render prop for entity-specific display.
+ *
+ * Design Rationale:
+ * - Card design provides visual containment
+ * - Border and shadow create depth
+ * - Rounded corners match overall design system
+ * - Render prop pattern keeps component BRUTALLY GENERIC
+ *
+ * Accessibility:
+ * - Semantic article element for content
+ * - Focus states for keyboard navigation
+ */
+
+import type { ReactNode } from 'react';
+
+interface EntityCardProps {
+  entity: any;
+  renderEntity?: (entity: any) => ReactNode;
+  className?: string;
+}
+
+/**
+ * Default entity renderer
+ * Shows entity name if available, otherwise shows JSON preview
+ */
+function defaultEntityRenderer(entity: any): ReactNode {
+  if (entity.name) {
+    return (
+      <div>
+        <div className="font-medium text-gray-900">{entity.name}</div>
+        <div className="text-sm text-gray-600 mt-1">
+          {Object.keys(entity)
+            .filter((key) => key !== 'name')
+            .slice(0, 3)
+            .map((key) => (
+              <span key={key} className="mr-2">
+                {key}: {String(entity[key]).slice(0, 20)}
+              </span>
+            ))}
+        </div>
+      </div>
+    );
+  }
+
+  // Fallback: show JSON preview
+  return (
+    <div className="text-sm text-gray-700 font-mono">
+      <pre className="whitespace-pre-wrap break-all">
+        {JSON.stringify(entity, null, 2).slice(0, 150)}
+        {JSON.stringify(entity, null, 2).length > 150 ? '...' : ''}
+      </pre>
+    </div>
+  );
+}
+
+export function EntityCard({
+  entity,
+  renderEntity = defaultEntityRenderer,
+  className = '',
+}: EntityCardProps) {
+  return (
+    <article
+      className={`p-3 bg-white border border-gray-200 rounded-lg shadow-sm hover:border-gray-300 transition-colors ${className}`}
+    >
+      {renderEntity(entity)}
+    </article>
+  );
+}

package/src/components/FunnelPreview/FunnelPreview.stories.tsx

@@ -0,0 +1,227 @@
+/**
+ * FunnelPreview Storybook stories
+ */
+
+import type { Meta, StoryObj } from '@storybook/react';
+import { FunnelPreview } from './FunnelPreview';
+import { sampleInvestors, investorFunnelExample, sampleRecipes, recipeFunnelExample, sampleLeads, leadFunnelExample } from '../../stories/demo-data';
+
+const meta: Meta<typeof FunnelPreview> = {
+  title: 'Components/FunnelPreview',
+  component: FunnelPreview,
+  parameters: {
+    layout: 'padded',
+    docs: {
+      description: {
+        component: 'Real-time preview of funnel execution on sample entities. Shows match stats and stage-by-stage breakdown.',
+      },
+    },
+  },
+  tags: ['autodocs'],
+};
+
+export default meta;
+type Story = StoryObj<typeof FunnelPreview>;
+
+// Investor funnel preview
+export const InvestorPreview: Story = {
+  args: {
+    funnel: investorFunnelExample,
+    entities: sampleInvestors,
+    renderEntity: (entity) => (
+      <div style={{ padding: '0.5rem' }}>
+        <div style={{ fontWeight: 600 }}>{entity['firm.name']}</div>
+        <div style={{ fontSize: '0.875rem', color: '#666' }}>
+          {entity['investor.name']} • {entity['investor.title']}
+        </div>
+        <div style={{ fontSize: '0.875rem', color: '#666', marginTop: '0.25rem' }}>
+          Stage: {entity['firm.stage']} | Score: {entity['investor.score']}
+        </div>
+      </div>
+    ),
+  },
+};
+
+// Recipe funnel preview
+export const RecipePreview: Story = {
+  args: {
+    funnel: recipeFunnelExample,
+    entities: sampleRecipes,
+    renderEntity: (entity) => (
+      <div style={{ padding: '0.5rem' }}>
+        <div style={{ fontWeight: 600 }}>{entity['recipe.name']}</div>
+        <div style={{ fontSize: '0.875rem', color: '#666' }}>
+          {entity['recipe.cuisine']} • {entity['recipe.difficulty']}
+        </div>
+        <div style={{ fontSize: '0.875rem', color: '#666', marginTop: '0.25rem' }}>
+          {entity['recipe.cookTimeMinutes']} min | {entity['recipe.calories']} cal | ⭐ {entity['recipe.rating']}
+        </div>
+      </div>
+    ),
+  },
+};
+
+// Lead scoring preview
+export const LeadPreview: Story = {
+  args: {
+    funnel: leadFunnelExample,
+    entities: sampleLeads,
+    renderEntity: (entity) => (
+      <div style={{ padding: '0.5rem' }}>
+        <div style={{ fontWeight: 600 }}>{entity['lead.name']}</div>
+        <div style={{ fontSize: '0.875rem', color: '#666' }}>
+          {entity['lead.company']} • {entity['lead.industry']}
+        </div>
+        <div style={{ fontSize: '0.875rem', color: '#666', marginTop: '0.25rem' }}>
+          Score: {entity['lead.score']} | Status: {entity['lead.status']}
+        </div>
+      </div>
+    ),
+  },
+};
+
+// No matches
+export const NoMatches: Story = {
+  args: {
+    funnel: {
+      ...investorFunnelExample,
+      stages: [
+        {
+          id: 'stage-1',
+          name: 'Impossible Filter',
+          description: 'Filter that matches nothing',
+          order: 0,
+          rules: [
+            {
+              field: 'investor.score',
+              operator: 'gte',
+              value: 1000, // Impossible score
+              logicalOperator: 'AND',
+            },
+          ],
+        },
+      ],
+    },
+    entities: sampleInvestors,
+    renderEntity: (entity) => (
+      <div style={{ padding: '0.5rem' }}>
+        <div style={{ fontWeight: 600 }}>{entity['firm.name']}</div>
+      </div>
+    ),
+  },
+};
+
+// Large dataset
+export const LargeDataset: Story = {
+  args: {
+    funnel: investorFunnelExample,
+    entities: Array.from({ length: 100 }, (_, i) => ({
+      id: `inv-${i}`,
+      'firm.name': `Firm ${i}`,
+      'firm.stage': i % 3 === 0 ? 'Seed' : i % 3 === 1 ? 'Series A' : 'Pre-Seed',
+      'firm.checkSizeMin': 500000 + i * 10000,
+      'firm.checkSizeMax': 2000000 + i * 50000,
+      'firm.sectors': i % 2 === 0 ? ['SaaS'] : ['AI/ML'],
+      'investor.name': `Investor ${i}`,
+      'investor.title': i % 2 === 0 ? 'Partner' : 'Principal',
+      'investor.score': 70 + (i % 30),
+      'firm.lastContactDays': i % 20,
+      'firm.portfolioSize': 20 + i,
+    })),
+    renderEntity: (entity) => (
+      <div style={{ padding: '0.5rem' }}>
+        <div style={{ fontWeight: 600 }}>{entity['firm.name']}</div>
+        <div style={{ fontSize: '0.875rem', color: '#666' }}>
+          Score: {entity['investor.score']}
+        </div>
+      </div>
+    ),
+  },
+};
+
+// Empty funnel (no stages)
+export const EmptyFunnel: Story = {
+  args: {
+    funnel: {
+      ...investorFunnelExample,
+      stages: [],
+    },
+    entities: sampleInvestors,
+    renderEntity: (entity) => (
+      <div style={{ padding: '0.5rem' }}>
+        <div style={{ fontWeight: 600 }}>{entity['firm.name']}</div>
+      </div>
+    ),
+  },
+};
+
+// Custom entity renderer (minimal)
+export const MinimalEntityRenderer: Story = {
+  args: {
+    funnel: investorFunnelExample,
+    entities: sampleInvestors,
+    renderEntity: (entity) => (
+      <div style={{ padding: '1rem', textAlign: 'center', fontWeight: 600 }}>
+        {entity['firm.name']}
+      </div>
+    ),
+  },
+};
+
+// Custom entity renderer (detailed)
+export const DetailedEntityRenderer: Story = {
+  args: {
+    funnel: investorFunnelExample,
+    entities: sampleInvestors,
+    renderEntity: (entity) => (
+      <div style={{ padding: '1rem', border: '2px solid #e5e7eb', borderRadius: '8px' }}>
+        <div style={{ display: 'flex', justifyContent: 'space-between', alignItems: 'start' }}>
+          <div>
+            <div style={{ fontSize: '1.125rem', fontWeight: 700, marginBottom: '0.25rem' }}>
+              {entity['firm.name']}
+            </div>
+            <div style={{ fontSize: '0.875rem', color: '#6b7280', marginBottom: '0.5rem' }}>
+              {entity['investor.name']} • {entity['investor.title']}
+            </div>
+          </div>
+          <div style={{
+            padding: '0.25rem 0.75rem',
+            backgroundColor: entity['investor.score'] >= 85 ? '#dcfce7' : '#fef3c7',
+            color: entity['investor.score'] >= 85 ? '#166534' : '#92400e',
+            borderRadius: '9999px',
+            fontSize: '0.875rem',
+            fontWeight: 600,
+          }}>
+            Score: {entity['investor.score']}
+          </div>
+        </div>
+        <div style={{
+          display: 'grid',
+          gridTemplateColumns: 'repeat(2, 1fr)',
+          gap: '0.5rem',
+          marginTop: '0.75rem',
+          fontSize: '0.875rem',
+        }}>
+          <div>
+            <div style={{ color: '#9ca3af', marginBottom: '0.125rem' }}>Stage</div>
+            <div style={{ fontWeight: 600 }}>{entity['firm.stage']}</div>
+          </div>
+          <div>
+            <div style={{ color: '#9ca3af', marginBottom: '0.125rem' }}>Check Size</div>
+            <div style={{ fontWeight: 600 }}>
+              ${(entity['firm.checkSizeMin'] / 1000000).toFixed(1)}M - ${(entity['firm.checkSizeMax'] / 1000000).toFixed(1)}M
+            </div>
+          </div>
+          <div>
+            <div style={{ color: '#9ca3af', marginBottom: '0.125rem' }}>Last Contact</div>
+            <div style={{ fontWeight: 600 }}>{entity['firm.lastContactDays']} days ago</div>
+          </div>
+          <div>
+            <div style={{ color: '#9ca3af', marginBottom: '0.125rem' }}>Portfolio</div>
+            <div style={{ fontWeight: 600 }}>{entity['firm.portfolioSize']} companies</div>
+          </div>
+        </div>
+      </div>
+    ),
+  },
+};

package/src/components/FunnelPreview/FunnelPreview.test.tsx

@@ -0,0 +1,316 @@
+/**
+ * FunnelPreview Component Tests
+ */
+
+import { describe, it, expect, vi } from 'vitest';
+import type { Funnel } from '../../types';
+
+// Mock entities for testing
+const mockEntities = [
+  { name: 'John Doe', firm: { stage: 'Series A' }, score: 85 },
+  { name: 'Jane Smith', firm: { stage: 'Seed' }, score: 92 },
+  { name: 'Bob Wilson', firm: { stage: 'Series B' }, score: 78 },
+  { name: 'Alice Johnson', firm: { stage: 'Series A' }, score: 88 },
+  { name: 'Charlie Brown', firm: { stage: 'Seed' }, score: 95 },
+];
+
+// Mock funnel with multiple stages
+const mockFunnel: Funnel = {
+  id: 'test-funnel',
+  name: 'Test Funnel',
+  description: 'A test funnel',
+  status: 'active',
+  input_type: 'contacts',
+  stages: [
+    {
+      id: 'stage-1',
+      order: 0,
+      name: 'High Score',
+      filter_logic: 'AND',
+      rules: [
+        {
+          field_path: 'score',
+          operator: 'gte',
+          value: 80,
+        },
+      ],
+      match_action: 'continue',
+      no_match_action: 'exclude',
+    },
+    {
+      id: 'stage-2',
+      order: 1,
+      name: 'Series A or Seed',
+      filter_logic: 'OR',
+      rules: [
+        {
+          field_path: 'firm.stage',
+          operator: 'eq',
+          value: 'Series A',
+        },
+        {
+          field_path: 'firm.stage',
+          operator: 'eq',
+          value: 'Seed',
+        },
+      ],
+      match_action: 'output',
+      no_match_action: 'exclude',
+    },
+  ],
+  created_at: new Date().toISOString(),
+  updated_at: new Date().toISOString(),
+};
+
+describe('FunnelPreview', () => {
+  describe('Preview Computation', () => {
+    it('should compute preview with matched entities', async () => {
+      const { FunnelEngine } = await import('../../core/engine');
+      const engine = new FunnelEngine();
+      const result = engine.execute(mockFunnel, mockEntities);
+
+      expect(result.total_input).toBe(5);
+      expect(result.total_matched).toBeGreaterThan(0);
+      expect(result.total_excluded).toBeGreaterThan(0);
+      expect(result.matched.length).toBe(result.total_matched);
+    });
+
+    it('should handle empty entities', async () => {
+      const { FunnelEngine } = await import('../../core/engine');
+      const engine = new FunnelEngine();
+      const result = engine.execute(mockFunnel, []);
+
+      expect(result.total_input).toBe(0);
+      expect(result.total_matched).toBe(0);
+      expect(result.total_excluded).toBe(0);
+      expect(result.matched).toEqual([]);
+    });
+
+    it('should handle empty funnel (no stages)', async () => {
+      const emptyFunnel: Funnel = {
+        ...mockFunnel,
+        stages: [],
+      };
+
+      const { FunnelEngine } = await import('../../core/engine');
+      const engine = new FunnelEngine();
+      const result = engine.execute(emptyFunnel, mockEntities);
+
+      // With no stages, all entities should match
+      expect(result.total_matched).toBe(5);
+      expect(result.total_excluded).toBe(0);
+    });
+  });
+
+  describe('Stage Statistics', () => {
+    it('should track entities at each stage', async () => {
+      const { FunnelEngine } = await import('../../core/engine');
+      const engine = new FunnelEngine();
+      const result = engine.execute(mockFunnel, mockEntities);
+
+      // Should have stats for both stages
+      expect(result.stage_stats['stage-1']).toBeDefined();
+      expect(result.stage_stats['stage-2']).toBeDefined();
+
+      // Stage 1 should process all entities
+      expect(result.stage_stats['stage-1'].input_count).toBe(5);
+    });
+
+    it('should count exclusions per stage', async () => {
+      const { FunnelEngine } = await import('../../core/engine');
+      const engine = new FunnelEngine();
+      const result = engine.execute(mockFunnel, mockEntities);
+
+      // Sum of excluded across all stages should equal total excluded
+      const totalExcludedAcrossStages = Object.values(result.stage_stats).reduce(
+        (sum, stats) => sum + stats.excluded_count,
+        0
+      );
+
+      expect(totalExcludedAcrossStages).toBeLessThanOrEqual(result.total_excluded);
+    });
+  });
+
+  describe('Preview Result Conversion', () => {
+    it('should calculate match percentage correctly', async () => {
+      const { FunnelEngine } = await import('../../core/engine');
+      const engine = new FunnelEngine();
+      const result = engine.execute(mockFunnel, mockEntities);
+
+      const total = result.total_matched + result.total_excluded;
+      const expectedPercentage =
+        total > 0 ? Math.round((result.total_matched / total) * 100) : 0;
+
+      expect(expectedPercentage).toBeGreaterThanOrEqual(0);
+      expect(expectedPercentage).toBeLessThanOrEqual(100);
+    });
+
+    it('should limit preview entities to maxPreviewEntities', async () => {
+      const { FunnelEngine } = await import('../../core/engine');
+      const engine = new FunnelEngine();
+      const result = engine.execute(mockFunnel, mockEntities);
+
+      const maxPreview = 2;
+      const previewEntities = result.matched.slice(0, maxPreview);
+
+      expect(previewEntities.length).toBeLessThanOrEqual(maxPreview);
+    });
+  });
+
+  describe('Multi-stage Funnel', () => {
+    it('should process entities through all stages', async () => {
+      const multiFunnel: Funnel = {
+        ...mockFunnel,
+        stages: [
+          {
+            id: 'stage-1',
+            order: 0,
+            name: 'Stage 1',
+            filter_logic: 'AND',
+            rules: [{ field_path: 'score', operator: 'gte', value: 80 }],
+            match_action: 'continue',
+            no_match_action: 'exclude',
+          },
+          {
+            id: 'stage-2',
+            order: 1,
+            name: 'Stage 2',
+            filter_logic: 'AND',
+            rules: [{ field_path: 'score', operator: 'lte', value: 90 }],
+            match_action: 'continue',
+            no_match_action: 'exclude',
+          },
+          {
+            id: 'stage-3',
+            order: 2,
+            name: 'Stage 3',
+            filter_logic: 'AND',
+            rules: [{ field_path: 'firm.stage', operator: 'eq', value: 'Series A' }],
+            match_action: 'output',
+            no_match_action: 'exclude',
+          },
+        ],
+      };
+
+      const { FunnelEngine } = await import('../../core/engine');
+      const engine = new FunnelEngine();
+      const result = engine.execute(multiFunnel, mockEntities);
+
+      // Should have stats for all 3 stages
+      expect(Object.keys(result.stage_stats).length).toBe(3);
+      expect(result.stage_stats['stage-1']).toBeDefined();
+      expect(result.stage_stats['stage-2']).toBeDefined();
+      expect(result.stage_stats['stage-3']).toBeDefined();
+    });
+
+    it('should track remaining entities correctly', async () => {
+      const { FunnelEngine } = await import('../../core/engine');
+      const engine = new FunnelEngine();
+      const result = engine.execute(mockFunnel, mockEntities);
+
+      // For each stage, remaining = input - excluded
+      Object.values(result.stage_stats).forEach((stats) => {
+        const remaining = stats.input_count - stats.excluded_count;
+        expect(remaining).toBeGreaterThanOrEqual(0);
+        expect(remaining).toBeLessThanOrEqual(stats.input_count);
+      });
+    });
+  });
+
+  describe('Edge Cases', () => {
+    it('should handle 0 entities', async () => {
+      const { FunnelEngine } = await import('../../core/engine');
+      const engine = new FunnelEngine();
+      const result = engine.execute(mockFunnel, []);
+
+      expect(result.total_input).toBe(0);
+      expect(result.total_matched).toBe(0);
+      expect(result.total_excluded).toBe(0);
+    });
+
+    it('should handle 100 entities', async () => {
+      const largeEntities = Array.from({ length: 100 }, (_, i) => ({
+        name: `Entity ${i}`,
+        score: 70 + (i % 30),
+        firm: { stage: i % 2 === 0 ? 'Series A' : 'Seed' },
+      }));
+
+      const { FunnelEngine } = await import('../../core/engine');
+      const engine = new FunnelEngine();
+      const result = engine.execute(mockFunnel, largeEntities);
+
+      expect(result.total_input).toBe(100);
+      expect(result.total_matched + result.total_excluded).toBe(100);
+    });
+
+    it('should handle funnel with no rules', async () => {
+      const noRulesFunnel: Funnel = {
+        ...mockFunnel,
+        stages: [
+          {
+            id: 'stage-1',
+            order: 0,
+            name: 'Pass All',
+            filter_logic: 'AND',
+            rules: [],
+            match_action: 'output',
+            no_match_action: 'exclude',
+          },
+        ],
+      };
+
+      const { FunnelEngine } = await import('../../core/engine');
+      const engine = new FunnelEngine();
+      const result = engine.execute(noRulesFunnel, mockEntities);
+
+      // With no rules, all entities should match
+      expect(result.total_matched).toBe(5);
+      expect(result.total_excluded).toBe(0);
+    });
+
+    it('should handle custom evaluator', async () => {
+      const customFunnel: Funnel = {
+        ...mockFunnel,
+        stages: [
+          {
+            id: 'stage-1',
+            order: 0,
+            name: 'Custom',
+            filter_logic: 'AND',
+            rules: [],
+            match_action: 'output',
+            no_match_action: 'exclude',
+            custom_evaluator: (entity: any) => entity.score > 85,
+          },
+        ],
+      };
+
+      const { FunnelEngine } = await import('../../core/engine');
+      const engine = new FunnelEngine();
+      const result = engine.execute(customFunnel, mockEntities);
+
+      // Should match entities with score > 85
+      expect(result.total_matched).toBe(3); // Jane(92), Alice(88), Charlie(95)
+    });
+  });
+
+  describe('Performance', () => {
+    it('should complete in reasonable time for 100 entities', async () => {
+      const largeEntities = Array.from({ length: 100 }, (_, i) => ({
+        name: `Entity ${i}`,
+        score: 70 + (i % 30),
+        firm: { stage: i % 2 === 0 ? 'Series A' : 'Seed' },
+      }));
+
+      const { FunnelEngine } = await import('../../core/engine');
+      const engine = new FunnelEngine();
+
+      const start = Date.now();
+      engine.execute(mockFunnel, largeEntities);
+      const duration = Date.now() - start;
+
+      // Should complete in less than 100ms for 100 entities
+      expect(duration).toBeLessThan(100);
+    });
+  });
+});