@startsimpli/funnels 0.1.4 → 0.1.5

package/src/core/operators.ts

@@ -0,0 +1,241 @@
+/**
+ * @startsimpli/funnels - Operator Implementation
+ *
+ * BRUTALLY GENERIC operator logic that works with ANY data type.
+ *
+ * Each operator is a pure function: (actual, expected) => boolean
+ */
+
+import type { Operator } from '../types';
+
+/**
+ * Apply an operator to compare actual vs expected values
+ *
+ * @param operator - The comparison operator
+ * @param actual - The actual value from entity
+ * @param expected - The expected value from rule
+ * @returns Whether the comparison passes
+ */
+export function applyOperator(
+  operator: Operator,
+  actual: any,
+  expected: any
+): boolean {
+  switch (operator) {
+    // ========================================================================
+    // Equality
+    // ========================================================================
+    case 'eq':
+      return compareValues(actual, expected, (a, e) => a === e);
+
+    case 'ne':
+      return compareValues(actual, expected, (a, e) => a !== e);
+
+    // ========================================================================
+    // Comparison (numbers, dates, strings)
+    // ========================================================================
+    case 'gt':
+      return compareValues(actual, expected, (a, e) => a > e);
+
+    case 'lt':
+      return compareValues(actual, expected, (a, e) => a < e);
+
+    case 'gte':
+      return compareValues(actual, expected, (a, e) => a >= e);
+
+    case 'lte':
+      return compareValues(actual, expected, (a, e) => a <= e);
+
+    // ========================================================================
+    // String operations (case-insensitive)
+    // ========================================================================
+    case 'contains':
+      if (actual == null) return false;
+      if (expected == null) return false;
+      return String(actual).toLowerCase().includes(String(expected).toLowerCase());
+
+    case 'not_contains':
+      if (actual == null) return true; // null doesn't contain anything
+      if (expected == null) return true;
+      return !String(actual).toLowerCase().includes(String(expected).toLowerCase());
+
+    case 'startswith':
+      if (actual == null) return false;
+      if (expected == null) return false;
+      return String(actual).toLowerCase().startsWith(String(expected).toLowerCase());
+
+    case 'endswith':
+      if (actual == null) return false;
+      if (expected == null) return false;
+      return String(actual).toLowerCase().endsWith(String(expected).toLowerCase());
+
+    case 'matches':
+      if (actual == null) return false;
+      if (expected == null) return false;
+      try {
+        const regex = new RegExp(String(expected));
+        return regex.test(String(actual));
+      } catch {
+        // Invalid regex pattern
+        return false;
+      }
+
+    // ========================================================================
+    // Array/Set operations
+    // ========================================================================
+    case 'in':
+      // Value is in array: actual IN expected[]
+      if (!Array.isArray(expected)) return false;
+      return expected.some(item => compareValues(actual, item, (a, e) => a === e));
+
+    case 'not_in':
+      // Value is not in array: actual NOT IN expected[]
+      if (!Array.isArray(expected)) return true;
+      return !expected.some(item => compareValues(actual, item, (a, e) => a === e));
+
+    case 'has_any':
+      // Array has any of values: actual[] HAS ANY expected[]
+      if (!Array.isArray(actual)) return false;
+      if (!Array.isArray(expected)) return false;
+      return expected.some(expectedItem =>
+        actual.some(actualItem => compareValues(actualItem, expectedItem, (a, e) => a === e))
+      );
+
+    case 'has_all':
+      // Array has all values: actual[] HAS ALL expected[]
+      if (!Array.isArray(actual)) return false;
+      if (!Array.isArray(expected)) return false;
+      return expected.every(expectedItem =>
+        actual.some(actualItem => compareValues(actualItem, expectedItem, (a, e) => a === e))
+      );
+
+    // ========================================================================
+    // Null checks
+    // ========================================================================
+    case 'isnull':
+      return actual === null || actual === undefined;
+
+    case 'isnotnull':
+      return actual !== null && actual !== undefined;
+
+    // ========================================================================
+    // Tag operations (tags are arrays of strings)
+    // ========================================================================
+    case 'has_tag':
+      if (!Array.isArray(actual)) return false;
+      if (expected == null) return false;
+      // Case-insensitive tag match
+      const expectedTag = String(expected).toLowerCase();
+      return actual.some(tag => String(tag).toLowerCase() === expectedTag);
+
+    case 'not_has_tag':
+      if (!Array.isArray(actual)) return true; // No tags = doesn't have tag
+      if (expected == null) return true;
+      const expectedTagNot = String(expected).toLowerCase();
+      return !actual.some(tag => String(tag).toLowerCase() === expectedTagNot);
+
+    // ========================================================================
+    // Boolean
+    // ========================================================================
+    case 'is_true':
+      return actual === true;
+
+    case 'is_false':
+      return actual === false;
+
+    default:
+      throw new Error(`Unknown operator: ${operator}`);
+  }
+}
+
+/**
+ * Compare values with type normalization
+ *
+ * Handles:
+ * - Numbers: direct comparison
+ * - Dates: convert to timestamps
+ * - Strings: direct comparison (operators handle case-sensitivity)
+ * - null/undefined: handle gracefully
+ */
+function compareValues(
+  actual: any,
+  expected: any,
+  compare: (a: any, e: any) => boolean
+): boolean {
+  // Handle null/undefined
+  if (actual === null || actual === undefined) {
+    return expected === null || expected === undefined;
+  }
+  if (expected === null || expected === undefined) {
+    return false;
+  }
+
+  // Both are dates - convert to timestamps
+  if (isDate(actual) && isDate(expected)) {
+    const actualTs = toTimestamp(actual);
+    const expectedTs = toTimestamp(expected);
+    if (actualTs === null || expectedTs === null) return false;
+    return compare(actualTs, expectedTs);
+  }
+
+  // One is date - try to parse the other
+  if (isDate(actual) || isDate(expected)) {
+    const actualTs = toTimestamp(actual);
+    const expectedTs = toTimestamp(expected);
+    if (actualTs === null || expectedTs === null) return false;
+    return compare(actualTs, expectedTs);
+  }
+
+  // Both are numbers
+  if (typeof actual === 'number' && typeof expected === 'number') {
+    return compare(actual, expected);
+  }
+
+  // Try to convert to numbers if they look numeric
+  if (isNumeric(actual) && isNumeric(expected)) {
+    return compare(Number(actual), Number(expected));
+  }
+
+  // Default: direct comparison
+  return compare(actual, expected);
+}
+
+/**
+ * Check if value is a Date object or date string
+ */
+function isDate(value: any): boolean {
+  if (value instanceof Date) return true;
+  if (typeof value !== 'string') return false;
+
+  // Check if string looks like a date
+  const datePattern = /^\d{4}-\d{2}-\d{2}|^\d{1,2}\/\d{1,2}\/\d{4}/;
+  return datePattern.test(value);
+}
+
+/**
+ * Convert value to timestamp (milliseconds since epoch)
+ * Returns null if conversion fails
+ */
+function toTimestamp(value: any): number | null {
+  if (value instanceof Date) {
+    const ts = value.getTime();
+    return isNaN(ts) ? null : ts;
+  }
+
+  if (typeof value === 'string' || typeof value === 'number') {
+    const date = new Date(value);
+    const ts = date.getTime();
+    return isNaN(ts) ? null : ts;
+  }
+
+  return null;
+}
+
+/**
+ * Check if value is numeric (number or numeric string)
+ */
+function isNumeric(value: any): boolean {
+  if (typeof value === 'number') return !isNaN(value);
+  if (typeof value !== 'string') return false;
+  return !isNaN(Number(value)) && value.trim() !== '';
+}

package/src/hooks/index.ts

@@ -0,0 +1,5 @@
+/**
+ * @startsimpli/funnels - React Hooks
+ */
+
+export { useDebouncedValue } from './useDebouncedValue';

package/src/hooks/useDebouncedValue.ts

@@ -0,0 +1,28 @@
+/**
+ * useDebouncedValue Hook
+ *
+ * Returns a debounced version of the input value that only updates
+ * after the specified delay has elapsed without changes.
+ *
+ * Use for expensive computations that shouldn't run on every keystroke.
+ */
+
+import { useEffect, useState } from 'react';
+
+export function useDebouncedValue<T>(value: T, delay: number = 300): T {
+  const [debouncedValue, setDebouncedValue] = useState<T>(value);
+
+  useEffect(() => {
+    // Set timeout to update debounced value after delay
+    const handler = setTimeout(() => {
+      setDebouncedValue(value);
+    }, delay);
+
+    // Cleanup: cancel timeout if value changes before delay elapses
+    return () => {
+      clearTimeout(handler);
+    };
+  }, [value, delay]);
+
+  return debouncedValue;
+}

package/src/index.ts

@@ -0,0 +1,155 @@
+/**
+ * @startsimpli/funnels
+ *
+ * BRUTALLY GENERIC funnel system for filtering and processing ANY entity type.
+ *
+ * Works for:
+ * - Investors, firms, contacts, organizations
+ * - Recipes, ingredients, cooking instructions
+ * - Leads, opportunities, tasks, projects
+ * - GitHub repos, PRs, issues, users
+ * - Products, orders, customers, shipments
+ * - Literally ANY data that needs sequential filtering
+ *
+ * Core concept:
+ * 1. Start with entities (any type)
+ * 2. Apply sequential filter stages
+ * 3. Each stage: keep/exclude/tag based on rules
+ * 4. End with filtered subset + accumulated tags/context
+ *
+ * Example use cases:
+ * - Investor qualification funnel (firm stage, check size, geography, etc)
+ * - Recipe recommendation funnel (dietary restrictions, cuisine, difficulty)
+ * - Lead scoring funnel (company size, industry, engagement level)
+ * - Task prioritization funnel (urgency, importance, dependencies)
+ *
+ * @packageDocumentation
+ */
+
+// Export all types
+export * from './types';
+
+// Export core utilities
+export {
+  resolveField,
+  setField,
+  hasField,
+  getFields,
+} from './core/field-resolver';
+
+// Export rule evaluator
+export {
+  evaluateRule,
+  evaluateRuleWithResult,
+  evaluateRules,
+  evaluateRulesAND,
+  evaluateRulesOR,
+  evaluateRulesWithResults,
+  filterEntities,
+} from './core/evaluator';
+
+// Export operators
+export { applyOperator } from './core/operators';
+
+// Export funnel engine
+export { FunnelEngine } from './core/engine';
+export type { ExecutionResult } from './core/engine';
+
+// Export API client
+export * from './api';
+
+// Export store
+export * from './store';
+
+// Export hooks
+export { useDebouncedValue } from './hooks';
+
+// Export components
+export {
+  FunnelPreview,
+  PreviewStats,
+  StageBreakdown,
+  EntityCard,
+  LoadingPreview,
+} from './components/FunnelPreview';
+export type {
+  FunnelPreviewProps,
+  PreviewResult,
+  StagePreviewStats,
+} from './components/FunnelPreview';
+
+export {
+  FunnelCard,
+  StatusBadge,
+  StageIndicator,
+  MatchBar,
+  FunnelStats,
+} from './components/FunnelCard';
+export type { FunnelCardProps } from './components/FunnelCard';
+
+export {
+  FunnelVisualFlow,
+  StageNode,
+  FlowLegend,
+  getCircledNumber,
+} from './components/FunnelVisualFlow';
+export type {
+  FunnelVisualFlowProps,
+  StageNodeData,
+} from './components/FunnelVisualFlow';
+
+export {
+  FilterRuleEditor,
+  LogicToggle,
+  FieldSelector,
+  OperatorSelector,
+  RuleRow,
+  TextValueInput,
+  NumberValueInput,
+  DateValueInput,
+  BooleanValueInput,
+  ChoiceValueInput,
+  MultiChoiceValueInput,
+  OPERATOR_LABELS,
+  NULL_VALUE_OPERATORS,
+  MULTI_VALUE_OPERATORS,
+} from './components/FilterRuleEditor';
+export type { FilterRuleEditorProps } from './components/FilterRuleEditor';
+
+export {
+  FunnelStageBuilder,
+  StageCard,
+  StageForm,
+  StageActions,
+  TagInput,
+  AddStageButton,
+} from './components/FunnelStageBuilder';
+export type {
+  FunnelStageBuilderProps,
+  StageCardProps,
+  StageFormProps,
+  StageActionsProps,
+  TagInputProps,
+  AddStageButtonProps,
+} from './components/FunnelStageBuilder';
+
+export {
+  FunnelRunHistory,
+  RunStatusBadge,
+  RunFilters,
+  RunRow,
+  RunActions,
+  RunDetailsModal,
+  StageBreakdownList,
+  formatDuration,
+  formatRelativeTime,
+  calculateMatchRate,
+  formatNumber,
+  formatFullTimestamp,
+} from './components/FunnelRunHistory';
+export type {
+  RunFiltersType,
+  RunSort,
+  Pagination,
+  RunAction,
+} from './components/FunnelRunHistory';