@startsimpli/funnels 0.1.3 → 0.1.5

package/src/components/FunnelRunHistory/RunFilters.tsx

@@ -0,0 +1,128 @@
+/**
+ * RunFilters Component
+ *
+ * Filter controls for funnel run history.
+ *
+ * Design Rationale:
+ * - Inline filter controls for immediate feedback
+ * - Dropdown selects for constrained options
+ * - Date range picker for flexible filtering
+ * - Clear visual separation from table
+ *
+ * Interaction Notes:
+ * - Filters apply immediately on change (no "Apply" button)
+ * - Default to "Last 30 days" for performance
+ * - Clear button resets all filters
+ */
+
+import { FunnelRunStatus, TriggerType } from '../../types';
+import { RunFilters as RunFiltersType } from './types';
+
+interface RunFiltersProps {
+  filters: RunFiltersType;
+  onFiltersChange: (filters: RunFiltersType) => void;
+  className?: string;
+}
+
+export function RunFilters({
+  filters,
+  onFiltersChange,
+  className = '',
+}: RunFiltersProps) {
+  const updateFilter = <K extends keyof RunFiltersType>(
+    key: K,
+    value: RunFiltersType[K]
+  ) => {
+    onFiltersChange({ ...filters, [key]: value });
+  };
+
+  const clearFilters = () => {
+    onFiltersChange({
+      status: 'all',
+      trigger_type: 'all',
+      date_range: 'month',
+    });
+  };
+
+  const hasActiveFilters =
+    filters.status !== 'all' ||
+    filters.trigger_type !== 'all' ||
+    filters.date_range !== 'month';
+
+  return (
+    <div
+      className={`flex items-center gap-3 p-3 bg-gray-50 border-b border-gray-200 ${className}`}
+    >
+      {/* Status Filter */}
+      <div className="flex items-center gap-2">
+        <label htmlFor="status-filter" className="text-sm font-medium text-gray-700">
+          Status:
+        </label>
+        <select
+          id="status-filter"
+          value={filters.status || 'all'}
+          onChange={(e) =>
+            updateFilter('status', e.target.value as FunnelRunStatus | 'all')
+          }
+          className="px-2 py-1 text-sm border border-gray-300 rounded-md bg-white focus:outline-none focus:ring-2 focus:ring-blue-500"
+        >
+          <option value="all">All</option>
+          <option value="completed">Complete</option>
+          <option value="running">Running</option>
+          <option value="failed">Failed</option>
+          <option value="pending">Pending</option>
+          <option value="cancelled">Cancelled</option>
+        </select>
+      </div>
+
+      {/* Trigger Type Filter */}
+      <div className="flex items-center gap-2">
+        <label htmlFor="trigger-filter" className="text-sm font-medium text-gray-700">
+          Trigger:
+        </label>
+        <select
+          id="trigger-filter"
+          value={filters.trigger_type || 'all'}
+          onChange={(e) =>
+            updateFilter('trigger_type', e.target.value as TriggerType | 'all')
+          }
+          className="px-2 py-1 text-sm border border-gray-300 rounded-md bg-white focus:outline-none focus:ring-2 focus:ring-blue-500"
+        >
+          <option value="all">All</option>
+          <option value="manual">Manual</option>
+          <option value="scheduled">Scheduled</option>
+          <option value="webhook">Webhook</option>
+          <option value="api">API</option>
+        </select>
+      </div>
+
+      {/* Date Range Filter */}
+      <div className="flex items-center gap-2">
+        <label htmlFor="date-filter" className="text-sm font-medium text-gray-700">
+          Date:
+        </label>
+        <select
+          id="date-filter"
+          value={filters.date_range || 'month'}
+          onChange={(e) => updateFilter('date_range', e.target.value as any)}
+          className="px-2 py-1 text-sm border border-gray-300 rounded-md bg-white focus:outline-none focus:ring-2 focus:ring-blue-500"
+        >
+          <option value="all">All time</option>
+          <option value="today">Today</option>
+          <option value="week">Last 7 days</option>
+          <option value="month">Last 30 days</option>
+        </select>
+      </div>
+
+      {/* Clear Button */}
+      {hasActiveFilters && (
+        <button
+          onClick={clearFilters}
+          className="ml-auto px-3 py-1 text-sm font-medium text-gray-700 bg-white border border-gray-300 rounded-md hover:bg-gray-50 focus:outline-none focus:ring-2 focus:ring-blue-500"
+        >
+          Clear filters
+        </button>
+      )}
+    </div>
+  );
+}

package/src/components/FunnelRunHistory/RunRow.tsx

@@ -0,0 +1,122 @@
+/**
+ * RunRow Component
+ *
+ * Individual table row for a funnel run.
+ *
+ * Design Rationale:
+ * - Clickable row opens details modal
+ * - Hover state provides visual feedback
+ * - Action button visible on hover for cleaner UI
+ * - Tooltip on date shows full timestamp
+ *
+ * Interaction Notes:
+ * - Click anywhere on row to view details
+ * - Action dropdown prevents row click propagation
+ * - Keyboard accessible (Enter to open details)
+ */
+
+import { FunnelRun } from '../../types';
+import { RunStatusBadge } from './RunStatusBadge';
+import { RunActions } from './RunActions';
+import {
+  formatDuration,
+  formatRelativeTime,
+  formatFullTimestamp,
+  calculateMatchRate,
+  formatNumber,
+} from './utils';
+
+interface RunRowProps {
+  run: FunnelRun;
+  onViewDetails: (run: FunnelRun) => void;
+  onViewResults: (run: FunnelRun) => void;
+  onReRun: (run: FunnelRun) => void;
+  onCancel?: (run: FunnelRun) => void;
+}
+
+export function RunRow({
+  run,
+  onViewDetails,
+  onViewResults,
+  onReRun,
+  onCancel,
+}: RunRowProps) {
+  const matchRate =
+    run.status === 'completed'
+      ? calculateMatchRate(run.total_matched, run.total_input)
+      : null;
+
+  return (
+    <tr
+      onClick={() => onViewDetails(run)}
+      onKeyDown={(e) => {
+        if (e.key === 'Enter') {
+          onViewDetails(run);
+        }
+      }}
+      tabIndex={0}
+      className="border-b border-gray-200 hover:bg-gray-50 cursor-pointer transition-colors focus:outline-none focus:ring-2 focus:ring-inset focus:ring-blue-500"
+    >
+      {/* Date */}
+      <td className="px-4 py-3">
+        <span
+          className="text-sm text-gray-900"
+          title={formatFullTimestamp(run.started_at)}
+        >
+          {formatRelativeTime(run.started_at)}
+        </span>
+      </td>
+
+      {/* Status */}
+      <td className="px-4 py-3">
+        <RunStatusBadge status={run.status} />
+      </td>
+
+      {/* Trigger */}
+      <td className="px-4 py-3">
+        <span className="text-sm text-gray-700 capitalize">
+          {run.trigger_type}
+        </span>
+      </td>
+
+      {/* Duration */}
+      <td className="px-4 py-3">
+        <span className="text-sm text-gray-900">
+          {formatDuration(run.duration_ms)}
+        </span>
+      </td>
+
+      {/* Input */}
+      <td className="px-4 py-3 text-right">
+        <span className="text-sm font-medium text-gray-900">
+          {formatNumber(run.total_input)}
+        </span>
+      </td>
+
+      {/* Matched */}
+      <td className="px-4 py-3 text-right">
+        <span className="text-sm font-medium text-green-600">
+          {run.status === 'completed' ? formatNumber(run.total_matched) : '-'}
+        </span>
+      </td>
+
+      {/* Match Rate % */}
+      <td className="px-4 py-3 text-right">
+        <span className="text-sm font-medium text-gray-900">
+          {matchRate !== null ? `${matchRate}%` : '-'}
+        </span>
+      </td>
+
+      {/* Actions */}
+      <td className="px-4 py-3" onClick={(e) => e.stopPropagation()}>
+        <RunActions
+          run={run}
+          onViewDetails={onViewDetails}
+          onViewResults={onViewResults}
+          onReRun={onReRun}
+          onCancel={onCancel}
+        />
+      </td>
+    </tr>
+  );
+}

package/src/components/FunnelRunHistory/RunStatusBadge.tsx

@@ -0,0 +1,75 @@
+/**
+ * RunStatusBadge Component
+ *
+ * Displays funnel run status with icon and color coding.
+ *
+ * Design Rationale:
+ * - Icons provide instant visual recognition
+ * - Color coding reinforces status meaning
+ * - Spinning animation for active states
+ * - Accessible with both visual and text indicators
+ */
+
+import { FunnelRunStatus } from '../../types';
+
+interface RunStatusBadgeProps {
+  status: FunnelRunStatus;
+  className?: string;
+}
+
+interface StatusConfig {
+  icon: string;
+  label: string;
+  color: string;
+  bgColor: string;
+  spinning?: boolean;
+}
+
+const statusConfig: Record<FunnelRunStatus, StatusConfig> = {
+  completed: {
+    icon: '✓',
+    label: 'Complete',
+    color: 'text-green-800',
+    bgColor: 'bg-green-100',
+  },
+  running: {
+    icon: '⏸',
+    label: 'Running',
+    color: 'text-blue-800',
+    bgColor: 'bg-blue-100',
+    spinning: true,
+  },
+  failed: {
+    icon: '✗',
+    label: 'Failed',
+    color: 'text-red-800',
+    bgColor: 'bg-red-100',
+  },
+  pending: {
+    icon: '○',
+    label: 'Pending',
+    color: 'text-yellow-800',
+    bgColor: 'bg-yellow-100',
+  },
+  cancelled: {
+    icon: '×',
+    label: 'Cancelled',
+    color: 'text-gray-800',
+    bgColor: 'bg-gray-100',
+  },
+};
+
+export function RunStatusBadge({ status, className = '' }: RunStatusBadgeProps) {
+  const config = statusConfig[status];
+
+  return (
+    <span
+      className={`inline-flex items-center gap-1.5 px-2.5 py-0.5 rounded-full text-xs font-medium ${config.bgColor} ${config.color} ${className}`}
+    >
+      <span className={config.spinning ? 'animate-spin' : ''} aria-hidden="true">
+        {config.icon}
+      </span>
+      <span>{config.label}</span>
+    </span>
+  );
+}

package/src/components/FunnelRunHistory/StageBreakdownList.tsx

@@ -0,0 +1,110 @@
+/**
+ * StageBreakdownList Component
+ *
+ * Displays stage-by-stage execution statistics.
+ *
+ * Design Rationale:
+ * - Sequential numbering shows funnel flow
+ * - Input → Matched with delta shows filtering effect
+ * - Color coding: green for matched, red for excluded
+ * - Arrow symbols reinforce flow direction
+ *
+ * Visual Hierarchy:
+ * - Stage name is prominent
+ * - Numbers are large and easy to scan
+ * - Delta shows impact at each stage
+ */
+
+import { StageStats } from '../../types';
+import { formatNumber } from './utils';
+
+interface StageBreakdownListProps {
+  stages: StageStats[];
+  className?: string;
+}
+
+export function StageBreakdownList({
+  stages,
+  className = '',
+}: StageBreakdownListProps) {
+  return (
+    <div className={`space-y-3 ${className}`}>
+      {stages.map((stage, index) => {
+        const delta = stage.matched_count - stage.input_count;
+        const matchRate =
+          stage.input_count > 0
+            ? Math.round((stage.matched_count / stage.input_count) * 100)
+            : 0;
+
+        return (
+          <div
+            key={stage.stage_id}
+            className="p-3 bg-gray-50 rounded-lg border border-gray-200"
+          >
+            {/* Stage Header */}
+            <div className="flex items-center gap-2 mb-2">
+              <span className="flex items-center justify-center w-6 h-6 text-xs font-bold text-white bg-blue-600 rounded-full">
+                {index + 1}
+              </span>
+              <h4 className="text-sm font-semibold text-gray-900">
+                {stage.stage_name}
+              </h4>
+            </div>
+
+            {/* Stage Stats */}
+            <div className="grid grid-cols-3 gap-2 text-center">
+              {/* Input */}
+              <div>
+                <div className="text-xs text-gray-600 mb-1">Input</div>
+                <div className="text-lg font-bold text-blue-600">
+                  {formatNumber(stage.input_count)}
+                </div>
+              </div>
+
+              {/* Matched */}
+              <div>
+                <div className="text-xs text-gray-600 mb-1">Matched</div>
+                <div className="text-lg font-bold text-green-600">
+                  {formatNumber(stage.matched_count)}
+                </div>
+              </div>
+
+              {/* Match Rate */}
+              <div>
+                <div className="text-xs text-gray-600 mb-1">Rate</div>
+                <div className="text-lg font-bold text-gray-700">{matchRate}%</div>
+              </div>
+            </div>
+
+            {/* Delta */}
+            {delta !== 0 && (
+              <div className="mt-2 pt-2 border-t border-gray-200">
+                <div className="flex items-center justify-center gap-1 text-sm">
+                  <span
+                    className={`font-medium ${
+                      delta > 0 ? 'text-green-600' : 'text-red-600'
+                    }`}
+                  >
+                    {delta > 0 ? '▲' : '▼'} {formatNumber(Math.abs(delta))}
+                  </span>
+                  <span className="text-gray-500">
+                    {delta > 0 ? 'added' : 'excluded'}
+                  </span>
+                </div>
+              </div>
+            )}
+
+            {/* Error Count */}
+            {stage.error_count && stage.error_count > 0 && (
+              <div className="mt-2 pt-2 border-t border-gray-200">
+                <div className="text-sm text-red-600 text-center">
+                  ⚠ {formatNumber(stage.error_count)} errors
+                </div>
+              </div>
+            )}
+          </div>
+        );
+      })}
+    </div>
+  );
+}

package/src/components/FunnelRunHistory/index.ts

@@ -0,0 +1,51 @@
+/**
+ * FunnelRunHistory - Component Suite
+ *
+ * Comprehensive run history display with filtering, sorting, and detailed views.
+ *
+ * Primary Export:
+ * - FunnelRunHistory: Main component
+ *
+ * Sub-Components (for custom layouts):
+ * - RunStatusBadge: Status display
+ * - RunFilters: Filter controls
+ * - RunRow: Table row
+ * - RunActions: Action dropdown
+ * - RunDetailsModal: Details modal
+ * - StageBreakdownList: Stage statistics
+ *
+ * Utilities:
+ * - formatDuration: Format ms to human-readable
+ * - formatRelativeTime: Format date to relative time
+ * - calculateMatchRate: Calculate percentage
+ * - formatNumber: Format with commas
+ *
+ * Types:
+ * - RunFilters: Filter state type
+ * - RunSort: Sort configuration
+ * - Pagination: Pagination state
+ * - RunAction: Action types
+ */
+
+export { FunnelRunHistory } from './FunnelRunHistory';
+export { RunStatusBadge } from './RunStatusBadge';
+export { RunFilters } from './RunFilters';
+export { RunRow } from './RunRow';
+export { RunActions } from './RunActions';
+export { RunDetailsModal } from './RunDetailsModal';
+export { StageBreakdownList } from './StageBreakdownList';
+
+export {
+  formatDuration,
+  formatRelativeTime,
+  calculateMatchRate,
+  formatNumber,
+  formatFullTimestamp,
+} from './utils';
+
+export type {
+  RunFilters as RunFiltersType,
+  RunSort,
+  Pagination,
+  RunAction,
+} from './types';

package/src/components/FunnelRunHistory/types.ts

@@ -0,0 +1,40 @@
+/**
+ * FunnelRunHistory Types
+ *
+ * Shared types for the run history component suite
+ */
+
+import { FunnelRun, FunnelRunStatus, TriggerType } from '../../types';
+
+/**
+ * Filter state for run history
+ */
+export interface RunFilters {
+  status?: FunnelRunStatus | 'all';
+  trigger_type?: TriggerType | 'all';
+  date_range?: 'all' | 'today' | 'week' | 'month' | 'custom';
+  start_date?: Date;
+  end_date?: Date;
+}
+
+/**
+ * Sort configuration for run history
+ */
+export interface RunSort {
+  field: 'started_at' | 'status' | 'match_rate' | 'duration_ms';
+  direction: 'asc' | 'desc';
+}
+
+/**
+ * Pagination state
+ */
+export interface Pagination {
+  page: number;
+  page_size: number;
+  total: number;
+}
+
+/**
+ * Run action types
+ */
+export type RunAction = 'view_details' | 'view_results' | 're_run' | 'cancel';

package/src/components/FunnelRunHistory/utils.test.ts

@@ -0,0 +1,126 @@
+/**
+ * Utils Tests
+ */
+
+import { describe, it, expect } from 'vitest';
+import {
+  formatDuration,
+  formatRelativeTime,
+  calculateMatchRate,
+  formatNumber,
+  formatFullTimestamp,
+} from './utils';
+
+describe('formatDuration', () => {
+  it('should format milliseconds', () => {
+    expect(formatDuration(500)).toBe('500ms');
+    expect(formatDuration(999)).toBe('999ms');
+  });
+
+  it('should format seconds', () => {
+    expect(formatDuration(1000)).toBe('1s');
+    expect(formatDuration(5000)).toBe('5s');
+    expect(formatDuration(59000)).toBe('59s');
+  });
+
+  it('should format minutes and seconds', () => {
+    expect(formatDuration(60000)).toBe('1m');
+    expect(formatDuration(65000)).toBe('1m 5s');
+    expect(formatDuration(125000)).toBe('2m 5s');
+  });
+
+  it('should format hours and minutes', () => {
+    expect(formatDuration(3600000)).toBe('1h');
+    expect(formatDuration(3660000)).toBe('1h 1m');
+    expect(formatDuration(7320000)).toBe('2h 2m');
+  });
+
+  it('should return "-" for undefined', () => {
+    expect(formatDuration(undefined)).toBe('-');
+  });
+
+  it('should handle zero duration', () => {
+    expect(formatDuration(0)).toBe('0ms');
+  });
+});
+
+describe('formatRelativeTime', () => {
+  it('should format recent times', () => {
+    const now = new Date();
+
+    // Just now
+    const justNow = new Date(now.getTime() - 30000); // 30 seconds ago
+    expect(formatRelativeTime(justNow)).toBe('Just now');
+  });
+
+  it('should format minutes ago', () => {
+    const now = new Date();
+    const fiveMinAgo = new Date(now.getTime() - 5 * 60 * 1000);
+    expect(formatRelativeTime(fiveMinAgo)).toBe('5m ago');
+  });
+
+  it('should format hours ago', () => {
+    const now = new Date();
+    const twoHoursAgo = new Date(now.getTime() - 2 * 60 * 60 * 1000);
+    expect(formatRelativeTime(twoHoursAgo)).toBe('2h ago');
+  });
+
+  it('should format days ago', () => {
+    const now = new Date();
+    const threeDaysAgo = new Date(now.getTime() - 3 * 24 * 60 * 60 * 1000);
+    expect(formatRelativeTime(threeDaysAgo)).toBe('3d ago');
+  });
+
+  it('should handle string dates', () => {
+    const now = new Date();
+    const yesterday = new Date(now.getTime() - 24 * 60 * 60 * 1000);
+    expect(formatRelativeTime(yesterday.toISOString())).toBe('1d ago');
+  });
+});
+
+describe('calculateMatchRate', () => {
+  it('should calculate percentage', () => {
+    expect(calculateMatchRate(50, 100)).toBe(50);
+    expect(calculateMatchRate(1, 3)).toBe(33);
+    expect(calculateMatchRate(2, 3)).toBe(67);
+  });
+
+  it('should handle zero total', () => {
+    expect(calculateMatchRate(0, 0)).toBe(0);
+    expect(calculateMatchRate(5, 0)).toBe(0);
+  });
+
+  it('should round to nearest integer', () => {
+    expect(calculateMatchRate(1, 3)).toBe(33); // 33.33... rounds to 33
+    expect(calculateMatchRate(2, 3)).toBe(67); // 66.66... rounds to 67
+  });
+});
+
+describe('formatNumber', () => {
+  it('should format with commas', () => {
+    expect(formatNumber(1000)).toBe('1,000');
+    expect(formatNumber(1234567)).toBe('1,234,567');
+    expect(formatNumber(999)).toBe('999');
+  });
+
+  it('should handle zero', () => {
+    expect(formatNumber(0)).toBe('0');
+  });
+});
+
+describe('formatFullTimestamp', () => {
+  it('should format date object', () => {
+    const date = new Date('2025-01-15T10:30:45Z');
+    const formatted = formatFullTimestamp(date);
+    // Format will vary by locale, just check it's a string
+    expect(typeof formatted).toBe('string');
+    expect(formatted.length).toBeGreaterThan(0);
+  });
+
+  it('should format ISO string', () => {
+    const isoString = '2025-01-15T10:30:45Z';
+    const formatted = formatFullTimestamp(isoString);
+    expect(typeof formatted).toBe('string');
+    expect(formatted.length).toBeGreaterThan(0);
+  });
+});