@startsimpli/funnels 0.1.4 → 0.1.5

package/src/components/FunnelPreview/FunnelPreview.tsx

@@ -0,0 +1,249 @@
+/**
+ * FunnelPreview Component
+ *
+ * Real-time preview of funnel execution on sample entities.
+ *
+ * Design Goal:
+ * Users should immediately see how their funnel configuration affects entities.
+ * Preview updates automatically as they edit rules, providing instant feedback
+ * on match rates and stage-by-stage filtering results.
+ *
+ * Visual Hierarchy Rationale:
+ * 1. Match stats bar (top) - Most important: overall funnel effectiveness
+ * 2. Stage breakdown - Shows filtering flow and where entities drop off
+ * 3. Sample entities - Concrete examples of what matched
+ *
+ * Interaction Notes:
+ * - Debounced updates (300ms) prevent excessive computation during editing
+ * - Loading skeleton maintains layout and reduces perceived lag
+ * - Custom entity renderer via render prop for domain-specific display
+ *
+ * Responsive Behavior:
+ * - Single column layout works on all screen sizes
+ * - Entity cards stack vertically
+ * - Stage breakdown scrolls horizontally on mobile if needed
+ *
+ * Accessibility Considerations:
+ * - ARIA live region announces when preview updates
+ * - Loading state communicated to screen readers
+ * - All metrics have text labels (color is supplementary)
+ * - Keyboard navigation through entity cards
+ *
+ * Component Specification:
+ * - States: loading, empty (no matches), populated
+ * - Behaviors: auto-compute on funnel/entity changes
+ * - Variations: with/without custom entity renderer
+ */
+
+import { useEffect, useState, type ReactNode } from 'react';
+import type { Funnel } from '../../types';
+import { FunnelEngine, type ExecutionResult } from '../../core/engine';
+import { useDebouncedValue } from '../../hooks/useDebouncedValue';
+import { PreviewStats } from './PreviewStats';
+import { StageBreakdown, type StagePreviewStats } from './StageBreakdown';
+import { EntityCard } from './EntityCard';
+import { LoadingPreview } from './LoadingPreview';
+
+// ============================================================================
+// Types
+// ============================================================================
+
+export interface PreviewResult {
+  totalMatched: number;
+  totalExcluded: number;
+  matchPercentage: number;
+  previewEntities: any[];
+  stageStats: Record<string, StagePreviewStats>;
+}
+
+export interface FunnelPreviewProps {
+  funnel: Funnel;
+  sampleEntities: any[];
+  onPreview?: (result: PreviewResult) => void;
+  renderEntity?: (entity: any) => ReactNode;
+  maxPreviewEntities?: number;
+  className?: string;
+}
+
+// ============================================================================
+// Helpers
+// ============================================================================
+
+/**
+ * Convert ExecutionResult to PreviewResult
+ */
+function convertToPreviewResult(
+  execResult: ExecutionResult,
+  maxEntities: number = 10
+): PreviewResult {
+  const { matched, total_matched, total_excluded, stage_stats } = execResult;
+
+  // Calculate match percentage
+  const total = total_matched + total_excluded;
+  const matchPercentage =
+    total > 0 ? Math.round((total_matched / total) * 100) : 0;
+
+  // Get preview entities (first N matched)
+  const previewEntities = matched.slice(0, maxEntities).map((r) => r.entity);
+
+  // Convert stage stats to preview format
+  const previewStageStats: Record<string, StagePreviewStats> = {};
+
+  Object.entries(stage_stats).forEach(([stageId, stats]) => {
+    previewStageStats[stageId] = {
+      stage_id: stats.stage_id,
+      stage_name: stats.stage_name,
+      input_count: stats.input_count,
+      excluded_count: stats.excluded_count,
+      remaining_count: stats.input_count - stats.excluded_count,
+    };
+  });
+
+  return {
+    totalMatched: total_matched,
+    totalExcluded: total_excluded,
+    matchPercentage,
+    previewEntities,
+    stageStats: previewStageStats,
+  };
+}
+
+// ============================================================================
+// Component
+// ============================================================================
+
+export function FunnelPreview({
+  funnel,
+  sampleEntities,
+  onPreview,
+  renderEntity,
+  maxPreviewEntities = 10,
+  className = '',
+}: FunnelPreviewProps) {
+  const [result, setResult] = useState<PreviewResult | null>(null);
+  const [isComputing, setIsComputing] = useState(false);
+
+  // Debounce funnel to avoid excessive computation
+  const debouncedFunnel = useDebouncedValue(funnel, 300);
+
+  // Compute preview when funnel or entities change
+  useEffect(() => {
+    async function compute() {
+      setIsComputing(true);
+
+      try {
+        const engine = new FunnelEngine();
+        const execResult = engine.execute(debouncedFunnel, sampleEntities);
+        const previewResult = convertToPreviewResult(
+          execResult,
+          maxPreviewEntities
+        );
+
+        setResult(previewResult);
+
+        // Notify parent component
+        if (onPreview) {
+          onPreview(previewResult);
+        }
+      } catch (error) {
+        console.error('Preview computation failed:', error);
+        // Set empty result on error
+        setResult({
+          totalMatched: 0,
+          totalExcluded: sampleEntities.length,
+          matchPercentage: 0,
+          previewEntities: [],
+          stageStats: {},
+        });
+      } finally {
+        setIsComputing(false);
+      }
+    }
+
+    compute();
+  }, [debouncedFunnel, sampleEntities, maxPreviewEntities, onPreview]);
+
+  // Loading state
+  if (isComputing && !result) {
+    return (
+      <div className={className}>
+        <LoadingPreview />
+      </div>
+    );
+  }
+
+  // No result yet
+  if (!result) {
+    return null;
+  }
+
+  const { totalMatched, totalExcluded, matchPercentage, previewEntities, stageStats } =
+    result;
+
+  return (
+    <div className={className} role="region" aria-label="Funnel preview">
+      <h2 className="text-lg font-semibold text-gray-900 mb-4">
+        Preview Results
+      </h2>
+
+      {/* Match stats */}
+      <PreviewStats
+        totalMatched={totalMatched}
+        totalExcluded={totalExcluded}
+        matchPercentage={matchPercentage}
+        className="mb-6"
+      />
+
+      {/* Stage breakdown */}
+      {funnel.stages.length > 0 && (
+        <StageBreakdown
+          stageStats={stageStats}
+          stages={funnel.stages}
+          className="mb-6"
+        />
+      )}
+
+      {/* Sample matches */}
+      <div>
+        <h3 className="text-sm font-semibold text-gray-700 mb-3">
+          Sample Matches ({Math.min(previewEntities.length, maxPreviewEntities)} of{' '}
+          {totalMatched.toLocaleString()})
+        </h3>
+
+        {previewEntities.length === 0 ? (
+          <div className="p-8 text-center bg-gray-50 rounded-lg border-2 border-dashed border-gray-300">
+            <p className="text-gray-600">No entities matched this funnel</p>
+            <p className="text-sm text-gray-500 mt-1">
+              Try adjusting your filter rules
+            </p>
+          </div>
+        ) : (
+          <div className="space-y-3">
+            {previewEntities.map((entity, index) => (
+              <EntityCard
+                key={index}
+                entity={entity}
+                renderEntity={renderEntity}
+              />
+            ))}
+            {totalMatched > maxPreviewEntities && (
+              <div className="text-center py-2 text-sm text-gray-500">
+                + {(totalMatched - maxPreviewEntities).toLocaleString()} more...
+              </div>
+            )}
+          </div>
+        )}
+      </div>
+
+      {/* Loading overlay */}
+      {isComputing && (
+        <div className="absolute inset-0 bg-white bg-opacity-75 flex items-center justify-center rounded-lg">
+          <div className="flex items-center gap-2 text-gray-600">
+            <div className="w-5 h-5 border-2 border-gray-300 border-t-blue-600 rounded-full animate-spin" />
+            <span className="text-sm font-medium">Updating preview...</span>
+          </div>
+        </div>
+      )}
+    </div>
+  );
+}

package/src/components/FunnelPreview/LoadingPreview.tsx

@@ -0,0 +1,60 @@
+/**
+ * LoadingPreview Component
+ *
+ * Skeleton loading state for FunnelPreview.
+ *
+ * Design Rationale:
+ * - Skeleton shapes match actual content layout
+ * - Pulse animation indicates loading
+ * - Gray placeholders maintain visual hierarchy
+ * - Reduces perceived loading time
+ *
+ * Accessibility:
+ * - ARIA live region announces loading state
+ * - Screen readers informed of status change
+ */
+
+export function LoadingPreview() {
+  return (
+    <div className="animate-pulse" role="status" aria-live="polite">
+      <span className="sr-only">Loading preview...</span>
+
+      {/* Stats bar skeleton */}
+      <div className="space-y-2 mb-6">
+        <div className="h-8 bg-gray-200 rounded-lg" />
+        <div className="flex justify-between">
+          <div className="h-4 w-32 bg-gray-200 rounded" />
+          <div className="h-4 w-32 bg-gray-200 rounded" />
+        </div>
+      </div>
+
+      {/* Stage breakdown skeleton */}
+      <div className="mb-6">
+        <div className="h-5 w-40 bg-gray-200 rounded mb-3" />
+        <div className="space-y-2">
+          {[1, 2, 3].map((i) => (
+            <div
+              key={i}
+              className="h-12 bg-gray-100 rounded-lg flex items-center px-3 gap-3"
+            >
+              <div className="w-6 h-6 bg-gray-200 rounded-full" />
+              <div className="h-4 bg-gray-200 rounded flex-1" />
+              <div className="h-4 w-16 bg-gray-200 rounded" />
+            </div>
+          ))}
+        </div>
+      </div>
+
+      {/* Entity cards skeleton */}
+      <div className="space-y-3">
+        <div className="h-5 w-48 bg-gray-200 rounded mb-3" />
+        {[1, 2, 3].map((i) => (
+          <div key={i} className="h-20 bg-gray-100 border border-gray-200 rounded-lg p-3">
+            <div className="h-4 bg-gray-200 rounded w-3/4 mb-2" />
+            <div className="h-3 bg-gray-200 rounded w-1/2" />
+          </div>
+        ))}
+      </div>
+    </div>
+  );
+}

package/src/components/FunnelPreview/PreviewStats.tsx

@@ -0,0 +1,78 @@
+/**
+ * PreviewStats Component
+ *
+ * Progress bar showing matched vs excluded entities with percentage.
+ *
+ * Design Rationale:
+ * - Horizontal progress bar shows match rate at a glance
+ * - Green (matched) and red (excluded) create clear visual distinction
+ * - Percentage provides quick understanding of funnel effectiveness
+ * - Counts below bar provide exact numbers
+ *
+ * Accessibility:
+ * - ARIA progressbar role for screen readers
+ * - Text labels provide non-visual indication
+ * - Sufficient color contrast
+ */
+
+interface PreviewStatsProps {
+  totalMatched: number;
+  totalExcluded: number;
+  matchPercentage: number;
+  className?: string;
+}
+
+export function PreviewStats({
+  totalMatched,
+  totalExcluded,
+  matchPercentage,
+  className = '',
+}: PreviewStatsProps) {
+  const total = totalMatched + totalExcluded;
+
+  return (
+    <div className={`space-y-2 ${className}`}>
+      {/* Progress bar */}
+      <div className="relative h-8 bg-gray-200 rounded-lg overflow-hidden">
+        <div
+          className="absolute inset-y-0 left-0 bg-gradient-to-r from-green-500 to-green-600 transition-all duration-300 flex items-center justify-center"
+          style={{ width: `${matchPercentage}%` }}
+          role="progressbar"
+          aria-valuenow={matchPercentage}
+          aria-valuemin={0}
+          aria-valuemax={100}
+          aria-label={`${totalMatched} of ${total} matched (${matchPercentage}%)`}
+        >
+          {matchPercentage > 15 && (
+            <span className="text-xs font-semibold text-white">
+              {totalMatched.toLocaleString()}/{total.toLocaleString()} ({matchPercentage}%)
+            </span>
+          )}
+        </div>
+        {matchPercentage <= 15 && (
+          <div className="absolute inset-0 flex items-center justify-center">
+            <span className="text-xs font-semibold text-gray-600">
+              {totalMatched.toLocaleString()}/{total.toLocaleString()} ({matchPercentage}%)
+            </span>
+          </div>
+        )}
+      </div>
+
+      {/* Match/Exclude counts */}
+      <div className="flex items-center justify-between text-sm">
+        <div className="flex items-center gap-1.5">
+          <div className="w-3 h-3 rounded-sm bg-green-500" />
+          <span className="font-medium text-gray-700">
+            {totalMatched.toLocaleString()} Matched
+          </span>
+        </div>
+        <div className="flex items-center gap-1.5">
+          <div className="w-3 h-3 rounded-sm bg-gray-300" />
+          <span className="font-medium text-gray-700">
+            {totalExcluded.toLocaleString()} Excluded
+          </span>
+        </div>
+      </div>
+    </div>
+  );
+}