@startsimpli/funnels 0.1.4 → 0.1.6

package/src/components/FunnelVisualFlow/example.tsx

@@ -0,0 +1,227 @@
+/**
+ * FunnelVisualFlow Example Usage
+ *
+ * This example demonstrates how to integrate FunnelVisualFlow
+ * into a real application with state management, API calls, etc.
+ */
+
+import React, { useState, useEffect } from 'react';
+import { FunnelVisualFlow } from './FunnelVisualFlow';
+import { Funnel, FunnelStage, FunnelRun } from '../../types';
+
+/**
+ * Example: Funnel Details Page
+ *
+ * Shows a funnel's visual flow with latest run data.
+ * Clicking a stage opens a details modal.
+ * Clicking an edge shows excluded entities.
+ */
+export function FunnelDetailsPage({ funnelId }: { funnelId: string }) {
+  const [funnel, setFunnel] = useState<Funnel | null>(null);
+  const [latestRun, setLatestRun] = useState<FunnelRun | null>(null);
+  const [selectedStage, setSelectedStage] = useState<FunnelStage | null>(null);
+  const [isLoading, setIsLoading] = useState(true);
+
+  // Load funnel and latest run
+  useEffect(() => {
+    async function loadData() {
+      setIsLoading(true);
+      try {
+        // Fetch funnel
+        const funnelRes = await fetch(`/api/funnels/${funnelId}`);
+        const funnelData = await funnelRes.json();
+        setFunnel(funnelData);
+
+        // Fetch latest run
+        const runsRes = await fetch(`/api/funnels/${funnelId}/runs?limit=1`);
+        const runsData = await runsRes.json();
+        if (runsData.results.length > 0) {
+          setLatestRun(runsData.results[0]);
+        }
+      } catch (error) {
+        console.error('Failed to load funnel:', error);
+      } finally {
+        setIsLoading(false);
+      }
+    }
+
+    loadData();
+  }, [funnelId]);
+
+  const handleStageClick = (stage: FunnelStage) => {
+    setSelectedStage(stage);
+    // Could open a modal, navigate to stage details, etc.
+  };
+
+  const handleEdgeClick = (fromStageId: string, toStageId: string) => {
+    // Show excluded entities between these stages
+    console.log('Show excluded entities:', fromStageId, '->', toStageId);
+    // Could fetch excluded entities and show in a modal
+  };
+
+  if (isLoading) {
+    return <div>Loading funnel...</div>;
+  }
+
+  if (!funnel) {
+    return <div>Funnel not found</div>;
+  }
+
+  return (
+    <div className="funnel-details-page">
+      <header className="page-header">
+        <h1>{funnel.name}</h1>
+        {funnel.description && <p>{funnel.description}</p>}
+      </header>
+
+      <div className="funnel-flow-container">
+        <FunnelVisualFlow
+          funnel={funnel}
+          runData={latestRun || undefined}
+          onStageClick={handleStageClick}
+          onEdgeClick={handleEdgeClick}
+          height={800}
+          className="shadow-lg"
+        />
+      </div>
+
+      {/* Stage Details Modal */}
+      {selectedStage && (
+        <StageDetailsModal
+          stage={selectedStage}
+          onClose={() => setSelectedStage(null)}
+        />
+      )}
+
+      {/* Latest Run Info */}
+      {latestRun && (
+        <div className="run-info">
+          <h2>Latest Run</h2>
+          <p>Status: {latestRun.status}</p>
+          <p>Started: {new Date(latestRun.started_at).toLocaleString()}</p>
+          <p>
+            Results: {latestRun.total_matched} / {latestRun.total_input} matched
+          </p>
+        </div>
+      )}
+    </div>
+  );
+}
+
+/**
+ * Example: Stage Details Modal
+ */
+function StageDetailsModal({
+  stage,
+  onClose,
+}: {
+  stage: FunnelStage;
+  onClose: () => void;
+}) {
+  return (
+    <div className="modal-overlay" onClick={onClose}>
+      <div className="modal-content" onClick={(e) => e.stopPropagation()}>
+        <header className="modal-header">
+          <h2>{stage.name}</h2>
+          <button onClick={onClose}>×</button>
+        </header>
+
+        <div className="modal-body">
+          {stage.description && <p>{stage.description}</p>}
+
+          <h3>Rules ({stage.rules.length})</h3>
+          <ul>
+            {stage.rules.map((rule, index) => (
+              <li key={index}>
+                {rule.field_path} {rule.operator} {JSON.stringify(rule.value)}
+              </li>
+            ))}
+          </ul>
+
+          <h3>Actions</h3>
+          <p>Match: {stage.match_action}</p>
+          <p>No Match: {stage.no_match_action}</p>
+
+          {stage.match_tags && stage.match_tags.length > 0 && (
+            <>
+              <h3>Match Tags</h3>
+              <ul>
+                {stage.match_tags.map((tag) => (
+                  <li key={tag}>{tag}</li>
+                ))}
+              </ul>
+            </>
+          )}
+        </div>
+      </div>
+    </div>
+  );
+}
+
+/**
+ * Example: Embedded in Dashboard
+ *
+ * Shows multiple funnels with their visual flows in a grid.
+ */
+export function FunnelsDashboard() {
+  const [funnels, setFunnels] = useState<Funnel[]>([]);
+
+  useEffect(() => {
+    async function loadFunnels() {
+      const res = await fetch('/api/funnels');
+      const data = await res.json();
+      setFunnels(data.results);
+    }
+    loadFunnels();
+  }, []);
+
+  return (
+    <div className="funnels-dashboard">
+      <h1>Active Funnels</h1>
+
+      <div className="funnels-grid">
+        {funnels.map((funnel) => (
+          <div key={funnel.id} className="funnel-card">
+            <h2>{funnel.name}</h2>
+            <FunnelVisualFlow
+              funnel={funnel}
+              height={400}
+              onStageClick={(stage) => {
+                console.log('Stage clicked:', stage.name);
+              }}
+            />
+          </div>
+        ))}
+      </div>
+    </div>
+  );
+}
+
+/**
+ * Example: Side-by-Side Comparison
+ *
+ * Compare two funnels visually.
+ */
+export function FunnelComparison({
+  funnelA,
+  funnelB,
+}: {
+  funnelA: Funnel;
+  funnelB: Funnel;
+}) {
+  return (
+    <div className="funnel-comparison">
+      <div className="comparison-side">
+        <h2>{funnelA.name}</h2>
+        <FunnelVisualFlow funnel={funnelA} height={600} />
+      </div>
+
+      <div className="comparison-divider" />
+
+      <div className="comparison-side">
+        <h2>{funnelB.name}</h2>
+        <FunnelVisualFlow funnel={funnelB} height={600} />
+      </div>
+    </div>
+  );
+}

package/src/components/FunnelVisualFlow/index.ts

@@ -0,0 +1,10 @@
+/**
+ * FunnelVisualFlow Component Exports
+ */
+
+export { FunnelVisualFlow } from './FunnelVisualFlow';
+export type { FunnelVisualFlowProps } from './FunnelVisualFlow';
+export { StageNode } from './StageNode';
+export type { StageNodeData } from './StageNode';
+export { FlowLegend } from './FlowLegend';
+export { getCircledNumber } from './FunnelVisualFlow';

package/src/components/index.ts

@@ -0,0 +1,102 @@
+/**
+ * @startsimpli/funnels/components
+ *
+ * React components for building funnel UIs
+ *
+ * @packageDocumentation
+ */
+
+// Export FunnelPreview
+export {
+  FunnelPreview,
+  PreviewStats,
+  StageBreakdown,
+  EntityCard,
+  LoadingPreview,
+} from './FunnelPreview';
+export type {
+  FunnelPreviewProps,
+  PreviewResult,
+  StagePreviewStats,
+} from './FunnelPreview';
+
+// Export FunnelCard
+export {
+  FunnelCard,
+  StatusBadge,
+  StageIndicator,
+  MatchBar,
+  FunnelStats,
+} from './FunnelCard';
+export type { FunnelCardProps } from './FunnelCard';
+
+// Export FunnelVisualFlow
+export {
+  FunnelVisualFlow,
+  StageNode,
+  FlowLegend,
+  getCircledNumber,
+} from './FunnelVisualFlow';
+export type {
+  FunnelVisualFlowProps,
+  StageNodeData,
+} from './FunnelVisualFlow';
+
+// Export FilterRuleEditor
+export {
+  FilterRuleEditor,
+  LogicToggle,
+  FieldSelector,
+  OperatorSelector,
+  RuleRow,
+  TextValueInput,
+  NumberValueInput,
+  DateValueInput,
+  BooleanValueInput,
+  ChoiceValueInput,
+  MultiChoiceValueInput,
+  OPERATOR_LABELS,
+  NULL_VALUE_OPERATORS,
+  MULTI_VALUE_OPERATORS,
+} from './FilterRuleEditor';
+export type { FilterRuleEditorProps } from './FilterRuleEditor';
+
+// Export FunnelStageBuilder
+export {
+  FunnelStageBuilder,
+  StageCard,
+  StageForm,
+  StageActions,
+  TagInput,
+  AddStageButton,
+} from './FunnelStageBuilder';
+export type {
+  FunnelStageBuilderProps,
+  StageCardProps,
+  StageFormProps,
+  StageActionsProps,
+  TagInputProps,
+  AddStageButtonProps,
+} from './FunnelStageBuilder';
+
+// Export FunnelRunHistory
+export {
+  FunnelRunHistory,
+  RunStatusBadge,
+  RunFilters,
+  RunRow,
+  RunActions,
+  RunDetailsModal,
+  StageBreakdownList,
+  formatDuration,
+  formatRelativeTime,
+  calculateMatchRate,
+  formatNumber,
+  formatFullTimestamp,
+} from './FunnelRunHistory';
+export type {
+  RunFiltersType,
+  RunSort,
+  Pagination,
+  RunAction,
+} from './FunnelRunHistory';

package/src/core/README.md

@@ -0,0 +1,307 @@
+# @simpli/funnels - Core Evaluation Engine
+
+BRUTALLY GENERIC rule evaluation engine for filtering ANY entity type.
+
+## Overview
+
+The core evaluation engine consists of three main components:
+
+1. **Field Resolver** (`field-resolver.ts`) - Resolves field values from entities using dot-notation paths
+2. **Operators** (`operators.ts`) - Implements all comparison operators (eq, gt, contains, in, etc.)
+3. **Evaluator** (`evaluator.ts`) - Combines field resolution + operators to evaluate filter rules
+
+## Quick Start
+
+```typescript
+import { evaluateRule, filterEntities } from '@simpli/funnels';
+import type { FilterRule } from '@simpli/funnels';
+
+// Define your entity type (any shape!)
+interface Investor {
+  name: string;
+  firm: {
+    stage: string;
+    aum: number;
+  };
+  tags: string[];
+}
+
+const investors: Investor[] = [
+  { name: 'John', firm: { stage: 'Series A', aum: 100000000 }, tags: ['qualified'] },
+  { name: 'Jane', firm: { stage: 'Seed', aum: 50000000 }, tags: ['active'] },
+];
+
+// Single rule evaluation
+const rule: FilterRule = {
+  field_path: 'firm.aum',
+  operator: 'gte',
+  value: 100000000
+};
+
+console.log(evaluateRule(investors[0], rule)); // true
+console.log(evaluateRule(investors[1], rule)); // false
+
+// Filter array of entities
+const rules: FilterRule[] = [
+  { field_path: 'firm.stage', operator: 'eq', value: 'Series A' },
+  { field_path: 'tags', operator: 'has_tag', value: 'qualified' }
+];
+
+const qualified = filterEntities(investors, rules, 'AND');
+// Returns: [{ name: 'John', ... }]
+```
+
+## Supported Operators
+
+### Equality
+- `eq` - Equal to
+- `ne` - Not equal to
+
+### Comparison (numbers, dates, strings)
+- `gt` - Greater than
+- `lt` - Less than
+- `gte` - Greater than or equal
+- `lte` - Less than or equal
+
+### String Operations (case-insensitive)
+- `contains` - String contains substring
+- `not_contains` - String does not contain substring
+- `startswith` - String starts with
+- `endswith` - String ends with
+- `matches` - Regex match
+
+### Array Operations
+- `in` - Value is in array
+- `not_in` - Value is not in array
+- `has_any` - Array has any of these values
+- `has_all` - Array has all of these values
+
+### Null Checks
+- `isnull` - Field is null/undefined
+- `isnotnull` - Field is not null/undefined
+
+### Tag Operations
+- `has_tag` - Entity has tag (case-insensitive)
+- `not_has_tag` - Entity does not have tag
+
+### Boolean
+- `is_true` - Boolean is true
+- `is_false` - Boolean is false
+
+## Field Resolution
+
+The evaluator uses dot-notation paths to access nested fields:
+
+```typescript
+const entity = {
+  name: 'John',
+  firm: {
+    stage: 'Series A',
+    aum: 100000000
+  },
+  tags: ['qualified', 'active'],
+  metrics: {
+    arr_usd: 5000000
+  }
+};
+
+// Simple field
+{ field_path: 'name', operator: 'eq', value: 'John' }
+
+// Nested field
+{ field_path: 'firm.stage', operator: 'eq', value: 'Series A' }
+
+// Deep nesting
+{ field_path: 'metrics.arr_usd', operator: 'gte', value: 1000000 }
+
+// Array field
+{ field_path: 'tags', operator: 'has_tag', value: 'qualified' }
+```
+
+## Type Handling
+
+The evaluator automatically handles type conversions:
+
+### Numbers
+```typescript
+// Direct comparison
+{ field_path: 'age', operator: 'gt', value: 30 }
+
+// Numeric string comparison
+{ field_path: 'age', operator: 'gt', value: '30' } // Coerced to number
+```
+
+### Dates
+```typescript
+// Date object
+{ field_path: 'created_at', operator: 'gte', value: new Date('2024-01-01') }
+
+// Date string
+{ field_path: 'created_at', operator: 'gte', value: '2024-01-01' }
+
+// Mixed (Date vs string)
+{ field_path: 'created_at', operator: 'eq', value: '2024-01-15' } // Works!
+```
+
+### Strings
+```typescript
+// Case-insensitive operations
+{ field_path: 'name', operator: 'contains', value: 'john' } // Matches 'John Doe'
+{ field_path: 'email', operator: 'endswith', value: '@ACME.COM' } // Matches '@acme.com'
+
+// Regex
+{ field_path: 'email', operator: 'matches', value: '^[a-z]+@example\\.com$' }
+```
+
+### Arrays
+```typescript
+// Check if value is in array
+{ field_path: 'firm.stage', operator: 'in', value: ['Series A', 'Series B'] }
+
+// Check if array has value
+{ field_path: 'tags', operator: 'has_tag', value: 'qualified' }
+
+// Check if array has all values
+{ field_path: 'tags', operator: 'has_all', value: ['active', 'qualified'] }
+
+// Check if array has any value
+{ field_path: 'tags', operator: 'has_any', value: ['premium', 'enterprise'] }
+```
+
+### Null/Undefined
+```typescript
+// Check if field is null
+{ field_path: 'email', operator: 'isnull', value: null }
+
+// Check if field exists
+{ field_path: 'profile.linkedin_url', operator: 'isnotnull', value: null }
+```
+
+## Multiple Rules
+
+Combine multiple rules with AND/OR logic:
+
+### AND Logic (all rules must match)
+```typescript
+const rules: FilterRule[] = [
+  { field_path: 'firm.stage', operator: 'eq', value: 'Series A' },
+  { field_path: 'firm.aum', operator: 'gte', value: 100000000 },
+  { field_path: 'tags', operator: 'has_tag', value: 'qualified' }
+];
+
+// All rules must pass
+const qualified = filterEntities(investors, rules, 'AND');
+
+// Or using helper
+const match = evaluateRulesAND(investor, rules);
+```
+
+### OR Logic (at least one rule must match)
+```typescript
+const rules: FilterRule[] = [
+  { field_path: 'firm.stage', operator: 'eq', value: 'Series A' },
+  { field_path: 'firm.aum', operator: 'gte', value: 500000000 } // OR very large
+];
+
+// Any rule can pass
+const flexible = filterEntities(investors, rules, 'OR');
+
+// Or using helper
+const match = evaluateRulesOR(investor, rules);
+```
+
+## Negation
+
+Use the `negate` flag to invert a rule's result:
+
+```typescript
+// Match investors NOT in Series A
+const rule: FilterRule = {
+  field_path: 'firm.stage',
+  operator: 'eq',
+  value: 'Series A',
+  negate: true // Invert the result
+};
+
+// Match investors WITHOUT 'archived' tag
+const notArchived: FilterRule = {
+  field_path: 'tags',
+  operator: 'has_tag',
+  value: 'archived',
+  negate: true
+};
+```
+
+## Detailed Results
+
+Get diagnostic information about rule evaluation:
+
+```typescript
+import { evaluateRuleWithResult, evaluateRulesWithResults } from '@simpli/funnels';
+
+// Single rule with details
+const result = evaluateRuleWithResult(investor, {
+  field_path: 'firm.aum',
+  operator: 'gte',
+  value: 100000000
+});
+
+console.log(result);
+// {
+//   field_path: 'firm.aum',
+//   operator: 'gte',
+//   value: 100000000,
+//   actual_value: 150000000,
+//   matched: true
+// }
+
+// Multiple rules with details
+const results = evaluateRulesWithResults(investor, rules, 'AND');
+
+console.log(results);
+// {
+//   matched: true,
+//   logic: 'AND',
+//   rule_results: [
+//     { field_path: 'firm.stage', operator: 'eq', value: 'Series A', actual_value: 'Series A', matched: true },
+//     { field_path: 'firm.aum', operator: 'gte', value: 100000000, actual_value: 150000000, matched: true }
+//   ]
+// }
+```
+
+## Testing
+
+The evaluation engine has comprehensive test coverage:
+
+- `operators.test.ts` - 105 tests covering all operators with various data types
+- `evaluator.test.ts` - 76 tests covering rule evaluation, multiple rules, filtering
+- `field-resolver.test.ts` - 57 tests covering field resolution logic
+
+Total: **286 tests** ensuring robust operation.
+
+Run tests:
+```bash
+npm test
+```
+
+## Examples
+
+See `evaluator.example.ts` for comprehensive examples including:
+- Investor qualification funnels
+- Recipe filtering with dietary restrictions
+- GitHub repository filtering
+- Multi-stage funnel simulation
+- Advanced patterns (negation, regex, OR logic)
+
+## Philosophy
+
+This evaluator follows the **BRUTALLY GENERIC** principle:
+
+- Works with ANY entity type (no domain-specific code)
+- Field paths use simple dot-notation (no magic)
+- Operators are pure functions (no side effects)
+- Type coercion is automatic and sensible
+- Null/undefined handling is consistent
+- Errors are graceful (no crashes)
+
+**The goal: Write rules once, filter anything.**