@startsimpli/funnels 0.1.4 → 0.1.5

package/src/components/FunnelCard/INSTALLATION.md

@@ -0,0 +1,304 @@
+# FunnelCard Installation Guide
+
+## Quick Start
+
+The FunnelCard component is already built and ready to use. It just needs React dependencies to render.
+
+## Install React Dependencies
+
+Since this package currently only has TypeScript/Zustand dependencies, you'll need to add React:
+
+```bash
+cd /Users/qosha/Repos/small-bizs/startsimpli/start-simpli-api/packages/funnels
+
+# Add React (peer dependency)
+npm install --save-peer react react-dom
+
+# Add React types (dev dependency)
+npm install --save-dev @types/react @types/react-dom
+```
+
+## Optional: Testing Dependencies
+
+To run the React component tests (`FunnelCard.test.tsx`):
+
+```bash
+# Install testing libraries
+npm install --save-dev @testing-library/react @testing-library/jest-dom @testing-library/user-event
+```
+
+## Optional: Storybook
+
+To view the Storybook stories (`FunnelCard.stories.tsx`):
+
+```bash
+# Initialize Storybook
+npx storybook@latest init
+
+# Start Storybook
+npm run storybook
+```
+
+## Tailwind CSS Setup
+
+FunnelCard uses Tailwind CSS classes. If your project doesn't have Tailwind:
+
+### 1. Install Tailwind
+
+```bash
+npm install --save-dev tailwindcss postcss autoprefixer
+npx tailwindcss init -p
+```
+
+### 2. Configure Tailwind
+
+**tailwind.config.js**:
+```javascript
+/** @type {import('tailwindcss').Config} */
+module.exports = {
+  content: [
+    './src/**/*.{ts,tsx}',
+  ],
+  theme: {
+    extend: {},
+  },
+  plugins: [],
+}
+```
+
+### 3. Add Tailwind Directives
+
+Create `src/styles.css`:
+```css
+@tailwind base;
+@tailwind components;
+@tailwind utilities;
+```
+
+Import in your entry file:
+```typescript
+import './styles.css';
+```
+
+## Verify Installation
+
+Test that components compile:
+
+```bash
+# Type check
+npm run type-check
+
+# Run tests (data validation tests work without React)
+npm test src/components/FunnelCard/FunnelCard.test.ts
+```
+
+## Usage in Your Project
+
+### Import Components
+
+```typescript
+import { FunnelCard } from '@simpli/funnels';
+
+// Or import sub-components directly
+import { StatusBadge, StageIndicator, MatchBar, FunnelStats } from '@simpli/funnels';
+```
+
+### Basic Example
+
+```tsx
+import { FunnelCard } from '@simpli/funnels';
+
+function MyComponent() {
+  const funnel = {
+    id: 'funnel-1',
+    name: 'Test Funnel',
+    status: 'active',
+    input_type: 'any',
+    stages: [
+      {
+        id: 'stage-1',
+        order: 0,
+        name: 'Stage 1',
+        filter_logic: 'AND',
+        rules: [{ field_path: 'name', operator: 'eq', value: 'test' }],
+        match_action: 'continue',
+        no_match_action: 'exclude',
+      },
+    ],
+    created_at: new Date().toISOString(),
+    updated_at: new Date().toISOString(),
+  };
+
+  const latestRun = {
+    id: 'run-1',
+    funnel_id: 'funnel-1',
+    status: 'completed',
+    trigger_type: 'manual',
+    started_at: new Date().toISOString(),
+    total_input: 1000,
+    total_matched: 50,
+    total_excluded: 950,
+    total_tagged: 50,
+    stage_stats: {},
+  };
+
+  return (
+    <FunnelCard
+      funnel={funnel}
+      latestRun={latestRun}
+      onViewFlow={(f) => console.log('View:', f.id)}
+    />
+  );
+}
+```
+
+## Integration with Next.js
+
+If using in a Next.js app:
+
+### 1. Mark as Client Component
+
+```tsx
+'use client';
+
+import { FunnelCard } from '@simpli/funnels';
+
+export default function FunnelsPage() {
+  // ...
+}
+```
+
+### 2. Import Tailwind Styles
+
+In `app/layout.tsx` or `_app.tsx`:
+```tsx
+import '@simpli/funnels/dist/styles.css'; // If package exports styles
+// OR import Tailwind directly:
+import 'tailwindcss/tailwind.css';
+```
+
+## Integration with Django Backend
+
+If using with Django API:
+
+### 1. Fetch Funnel Data
+
+```typescript
+async function fetchFunnels() {
+  const response = await fetch('/api/funnels/', {
+    headers: {
+      'Authorization': `Bearer ${token}`,
+    },
+  });
+  return response.json();
+}
+```
+
+### 2. Render Cards
+
+```tsx
+function FunnelDashboard() {
+  const [funnels, setFunnels] = useState([]);
+
+  useEffect(() => {
+    fetchFunnels().then(setFunnels);
+  }, []);
+
+  return (
+    <div className="grid grid-cols-1 md:grid-cols-2 lg:grid-cols-3 gap-6">
+      {funnels.map(funnel => (
+        <FunnelCard
+          key={funnel.id}
+          funnel={funnel}
+          latestRun={funnel.latest_run}
+          onViewFlow={(f) => router.push(`/funnels/${f.id}`)}
+        />
+      ))}
+    </div>
+  );
+}
+```
+
+## Troubleshooting
+
+### Issue: "Cannot find module 'react'"
+
+**Solution**: Install React dependencies
+```bash
+npm install react react-dom @types/react @types/react-dom
+```
+
+### Issue: "Unknown at rule @tailwind"
+
+**Solution**: Install and configure Tailwind CSS (see above)
+
+### Issue: Tests failing with "ReferenceError: React is not defined"
+
+**Solution**: Import React in test file
+```typescript
+import React from 'react';
+import { render } from '@testing-library/react';
+```
+
+### Issue: Styles not applying
+
+**Solution**: Ensure Tailwind is configured and CSS is imported
+```typescript
+import 'tailwindcss/tailwind.css';
+```
+
+### Issue: Type errors in Storybook
+
+**Solution**: Install Storybook types
+```bash
+npm install --save-dev @storybook/react @storybook/addon-essentials
+```
+
+## Production Build
+
+When building for production:
+
+```bash
+# Build package
+npm run build
+
+# Or if using with bundler (webpack, vite, etc.)
+# Components will be tree-shaken automatically
+```
+
+## CDN Usage (Not Recommended)
+
+For quick prototyping only:
+
+```html
+<!-- React -->
+<script crossorigin src="https://unpkg.com/react@18/umd/react.production.min.js"></script>
+<script crossorigin src="https://unpkg.com/react-dom@18/umd/react-dom.production.min.js"></script>
+
+<!-- Tailwind CSS -->
+<script src="https://cdn.tailwindcss.com"></script>
+
+<!-- Your bundled package -->
+<script src="/dist/funnels.umd.js"></script>
+```
+
+Use npm install for production.
+
+## Next Steps
+
+1. ✓ Install React dependencies
+2. ✓ Configure Tailwind CSS
+3. ✓ Import FunnelCard component
+4. ✓ Pass funnel and latestRun props
+5. ✓ Handle onViewFlow callback
+6. View README.md for detailed usage
+7. View DESIGN.md for design specifications
+8. Check out Storybook for visual examples
+
+## Questions?
+
+See other documentation files:
+- `README.md` - Component usage guide
+- `DESIGN.md` - Design specifications and rationale
+- `IMPLEMENTATION_SUMMARY.md` - Complete implementation details
+- `FunnelCard.tsx` - Source code with inline comments

package/src/components/FunnelCard/MatchBar.tsx

@@ -0,0 +1,49 @@
+/**
+ * MatchBar Component
+ *
+ * Progress bar showing match percentage with count label.
+ *
+ * Design Rationale:
+ * - Green gradient conveys success/completion
+ * - Rounded corners match card aesthetic
+ * - Label shows absolute count (more actionable than percentage alone)
+ * - Gray background shows full scale
+ *
+ * Accessibility:
+ * - Text label provides non-visual indication of value
+ * - Sufficient contrast between bar and background
+ */
+
+interface MatchBarProps {
+  matched: number;
+  total: number;
+  className?: string;
+}
+
+export function MatchBar({ matched, total, className = '' }: MatchBarProps) {
+  const percentage = total > 0 ? Math.round((matched / total) * 100) : 0;
+
+  return (
+    <div className={`space-y-1 ${className}`}>
+      {/* Progress bar */}
+      <div className="relative h-6 bg-gray-200 rounded-md overflow-hidden">
+        <div
+          className="absolute inset-y-0 left-0 bg-gradient-to-r from-green-500 to-green-600 transition-all duration-300"
+          style={{ width: `${percentage}%` }}
+          role="progressbar"
+          aria-valuenow={percentage}
+          aria-valuemin={0}
+          aria-valuemax={100}
+          aria-label={`${matched} of ${total} matched`}
+        />
+      </div>
+
+      {/* Match count label */}
+      <div className="text-right">
+        <span className="text-sm font-medium text-gray-700">
+          {matched.toLocaleString()} matched
+        </span>
+      </div>
+    </div>
+  );
+}

package/src/components/FunnelCard/README.md

@@ -0,0 +1,294 @@
+# FunnelCard Component
+
+BRUTALLY GENERIC funnel card component matching Django admin screenshot design.
+
+## Overview
+
+FunnelCard displays a funnel overview with:
+- **Header**: Funnel name + color-coded status badge
+- **Description**: Optional descriptive text
+- **Stage List**: Sequential stages with numbered indicators and rule counts
+- **Match Bar**: Visual progress bar showing match percentage
+- **Stats**: Three-column metrics (INPUT / MATCHED / EXCLUDED)
+- **Action**: "View Flow" button
+
+## Usage
+
+```tsx
+import { FunnelCard } from '@simpli/funnels';
+
+function MyComponent() {
+  const funnel = {
+    id: 'funnel-1',
+    name: 'Series A Investor Qualification',
+    description: 'Identifies qualified Series A investors',
+    status: 'active',
+    input_type: 'contacts',
+    stages: [
+      {
+        id: 'stage-1',
+        order: 0,
+        name: 'Stage Filter',
+        filter_logic: 'AND',
+        rules: [
+          { field_path: 'firm.stage', operator: 'in', value: ['Series A'] }
+        ],
+        match_action: 'continue',
+        no_match_action: 'exclude',
+      },
+      // ... more stages
+    ],
+    created_at: '2024-01-01T00:00:00Z',
+    updated_at: '2024-01-01T00:00:00Z',
+  };
+
+  const latestRun = {
+    id: 'run-1',
+    funnel_id: 'funnel-1',
+    status: 'completed',
+    trigger_type: 'manual',
+    started_at: '2024-01-01T00:00:00Z',
+    completed_at: '2024-01-01T00:01:00Z',
+    total_input: 83061,
+    total_matched: 235,
+    total_excluded: 82826,
+    total_tagged: 235,
+    stage_stats: {},
+  };
+
+  return (
+    <FunnelCard
+      funnel={funnel}
+      latestRun={latestRun}
+      onViewFlow={(funnel) => console.log('View:', funnel.id)}
+    />
+  );
+}
+```
+
+## Props
+
+| Prop | Type | Required | Description |
+|------|------|----------|-------------|
+| `funnel` | `Funnel` | Yes | Funnel definition (BRUTALLY GENERIC) |
+| `latestRun` | `FunnelRun` | No | Latest run results. Shows "no runs yet" if missing |
+| `onViewFlow` | `(funnel: Funnel) => void` | No | Callback when "View Flow" button clicked |
+| `onEdit` | `(funnel: Funnel) => void` | No | Callback for edit action (future use) |
+| `className` | `string` | No | Additional CSS classes |
+
+## Visual States
+
+### Status Badges
+- **ACTIVE** - Green badge (bg-green-100, text-green-800)
+- **DRAFT** - Yellow badge (bg-yellow-100, text-yellow-800)
+- **PAUSED** - Gray badge (bg-gray-100, text-gray-800)
+- **ARCHIVED** - Red badge (bg-red-100, text-red-800)
+
+### Run States
+- **Completed** - Shows match bar + stats
+- **Running** - Shows "Running..." message
+- **Failed** - Shows "Last run failed" message
+- **No runs** - Shows "No runs yet" message
+
+### Empty States
+- **No stages** - Shows "No stages defined" in stage section
+- **No description** - Description section omitted
+- **Zero matches** - Match bar at 0%, stats show zeros
+
+## Sub-Components
+
+All sub-components are exported for composition flexibility:
+
+### StatusBadge
+```tsx
+import { StatusBadge } from '@simpli/funnels';
+
+<StatusBadge status="active" />
+```
+
+### StageIndicator
+```tsx
+import { StageIndicator } from '@simpli/funnels';
+
+<StageIndicator
+  order={0}
+  name="Stage Filter"
+  ruleCount={3}
+  isLast={false}
+/>
+```
+
+### MatchBar
+```tsx
+import { MatchBar } from '@simpli/funnels';
+
+<MatchBar matched={235} total={83061} />
+```
+
+### FunnelStats
+```tsx
+import { FunnelStats } from '@simpli/funnels';
+
+<FunnelStats input={83061} matched={235} excluded={82826} />
+```
+
+## Design Specifications
+
+### Layout
+```
+┌─────────────────────────────────────────┐
+│ Funnel Name              [ACTIVE badge] │  Header
+│ Description text here...                │
+│                                         │
+│ ① Stage 1 Name            1 rule       │  Stages
+│ │                                       │
+│ ② Stage 2 Name            3 rules      │
+│ │                                       │
+│ ③ Stage 3 Name            2 rules      │
+│                                         │
+│ ████████████░░░░░░░░  235 matched      │  Match Bar
+│                                         │
+│ 83061 INPUT  235 MATCHED  82826 EXCLUDED │  Stats
+│                                         │
+│              [View Flow →]               │  Action
+└─────────────────────────────────────────┘
+```
+
+### Spacing
+- Card padding: 24px (px-6)
+- Section spacing: 16px (py-4)
+- Stage gap: 0px (vertical line connects)
+- Stats grid gap: 8px (gap-2)
+
+### Colors
+- Card: white background, gray-200 border, shadow-sm
+- Status Active: green-100 bg, green-800 text
+- Status Draft: yellow-100 bg, yellow-800 text
+- Status Paused: gray-100 bg, gray-800 text
+- Status Archived: red-100 bg, red-800 text
+- Match Bar: green-500 to green-600 gradient
+- Stats INPUT: blue-50 bg, blue-600 text
+- Stats MATCHED: green-50 bg, green-600 text
+- Stats EXCLUDED: red-50 bg, red-600 text
+
+### Typography
+- Funnel name: text-lg, font-semibold
+- Description: text-sm, text-gray-600
+- Stage name: text-sm, font-medium
+- Rule count: text-xs, text-gray-500
+- Stats label: text-xs, font-medium
+- Stats value: text-lg, font-bold
+- Button: text-sm, font-medium
+
+### Responsive Behavior
+- Mobile (< 640px): Full width, single column
+- Tablet (640px - 1024px): Constrained width
+- Desktop (> 1024px): Max width, centered
+
+## Accessibility
+
+### Semantic HTML
+- `<article>` for card container
+- `<header>` for funnel name + status
+- `<section>` for each major area
+- `<footer>` for action button
+- `<dl>/<dt>/<dd>` for stats
+
+### ARIA Attributes
+- `aria-label` on article: "Funnel: {name}"
+- `aria-label` on sections: "Funnel stages", "Match results", etc.
+- `aria-label` on button: "View flow details for {name}"
+- `role="progressbar"` on match bar with aria-value* attributes
+
+### Keyboard Navigation
+- Button is fully keyboard accessible
+- Focus visible with ring-2 ring-blue-500
+- Tab order follows visual flow
+
+### Color Contrast
+- All text meets WCAG AA 4.5:1 minimum
+- Status badges: 4.5:1 contrast
+- Stats: 4.5:1 contrast
+- Button: 4.5:1 contrast
+
+## Examples
+
+### Investor Funnel
+```tsx
+<FunnelCard
+  funnel={{
+    name: 'Series A Investor Qualification',
+    status: 'active',
+    stages: [/* ... */],
+    // ...
+  }}
+  latestRun={{
+    total_input: 83061,
+    total_matched: 235,
+    total_excluded: 82826,
+    // ...
+  }}
+/>
+```
+
+### Recipe Funnel
+```tsx
+<FunnelCard
+  funnel={{
+    name: 'Quick Easy Dinner Recommendations',
+    status: 'active',
+    stages: [/* ... */],
+    // ...
+  }}
+  latestRun={{
+    total_input: 5420,
+    total_matched: 87,
+    total_excluded: 5333,
+    // ...
+  }}
+/>
+```
+
+### Lead Scoring Funnel
+```tsx
+<FunnelCard
+  funnel={{
+    name: 'Enterprise Lead Scoring',
+    status: 'active',
+    stages: [/* ... */],
+    // ...
+  }}
+  latestRun={{
+    total_input: 12500,
+    total_matched: 342,
+    total_excluded: 12158,
+    // ...
+  }}
+/>
+```
+
+## Testing
+
+Run tests:
+```bash
+npm test src/components/FunnelCard/FunnelCard.test.tsx
+```
+
+View stories:
+```bash
+npm run storybook
+```
+
+## Dependencies
+
+- React (peer dependency)
+- Tailwind CSS (styling)
+- TypeScript (type safety)
+
+## Browser Support
+
+- Chrome/Edge: Latest 2 versions
+- Firefox: Latest 2 versions
+- Safari: Latest 2 versions
+- Mobile Safari: Latest 2 versions
+- Chrome Android: Latest 2 versions

package/src/components/FunnelCard/StageIndicator.tsx

@@ -0,0 +1,62 @@
+/**
+ * StageIndicator Component
+ *
+ * Displays a numbered circle badge for funnel stages with connecting vertical line.
+ *
+ * Design Rationale:
+ * - Numbered circles (①②③) provide clear sequential ordering
+ * - Vertical connecting line shows flow/progression
+ * - Compact layout conserves vertical space
+ * - Gray text for rule count de-emphasizes secondary info
+ *
+ * Accessibility:
+ * - Sufficient color contrast (4.5:1 minimum)
+ * - Semantic HTML structure
+ */
+
+interface StageIndicatorProps {
+  order: number;
+  name: string;
+  ruleCount: number;
+  isLast?: boolean;
+  className?: string;
+}
+
+export function StageIndicator({
+  order,
+  name,
+  ruleCount,
+  isLast = false,
+  className = ''
+}: StageIndicatorProps) {
+  // Format order as circled number (1-20 supported by Unicode)
+  const circledNumber = order < 20
+    ? String.fromCharCode(9312 + order)  // ① = U+2460
+    : `(${order + 1})`;
+
+  return (
+    <div className={`flex items-start gap-2 ${className}`}>
+      {/* Stage number circle with connecting line */}
+      <div className="flex flex-col items-center">
+        <div className="flex-shrink-0 w-6 h-6 rounded-full bg-blue-100 text-blue-800 flex items-center justify-center text-sm font-medium">
+          {circledNumber}
+        </div>
+        {!isLast && (
+          <div className="w-0.5 h-6 bg-gray-200 mt-1" />
+        )}
+      </div>
+
+      {/* Stage name and rule count */}
+      <div className="flex-1 pt-0.5 min-w-0">
+        <div className="flex items-baseline justify-between gap-2">
+          <span className="text-sm font-medium text-gray-900 truncate">
+            {name}
+          </span>
+          <span className="text-xs text-gray-500 whitespace-nowrap">
+            {ruleCount} {ruleCount === 1 ? 'rule' : 'rules'}
+          </span>
+        </div>
+      </div>
+    </div>
+  );
+}