@startsimpli/funnels 0.1.4 → 0.1.6

package/src/components/FilterRuleEditor/ARCHITECTURE.md

@@ -0,0 +1,354 @@
+# FilterRuleEditor Architecture
+
+## Component Hierarchy
+
+```
+FilterRuleEditor
+├─ LogicToggle (AND/OR switch)
+├─ Empty State (when no rules)
+│  └─ Add First Rule button
+└─ Rule List (when rules exist)
+   ├─ RuleRow (for each rule)
+   │  ├─ FieldSelector (grouped dropdown)
+   │  ├─ OperatorSelector (filtered by field type)
+   │  └─ ValueInput (dynamic based on field + operator)
+   │     ├─ TextValueInput
+   │     ├─ NumberValueInput
+   │     ├─ DateValueInput
+   │     ├─ BooleanValueInput
+   │     ├─ ChoiceValueInput
+   │     └─ MultiChoiceValueInput
+   │  └─ Delete button
+   ├─ Logic Connector (AND/OR pill between rules)
+   └─ Validation Errors (per rule)
+   └─ Add Rule button
+   └─ Rule Summary (count + logic description)
+```
+
+## Data Flow
+
+```
+┌─────────────────────────────────────────────────────────────────┐
+│                      FilterRuleEditor                           │
+│                                                                 │
+│  State:                                                         │
+│  - rules: FilterRule[]                                          │
+│  - logic: 'AND' | 'OR'                                          │
+│                                                                 │
+│  Props:                                                         │
+│  - fieldRegistry: FieldDefinition[]  ← Defines available fields │
+│  - onChange: (rules) => void         ← Parent updates state     │
+│  - onLogicChange: (logic) => void    ← Parent updates logic     │
+└─────────────────────────────────────────────────────────────────┘
+                            │
+                            │ passes fieldRegistry + rule
+                            ▼
+┌─────────────────────────────────────────────────────────────────┐
+│                         RuleRow                                 │
+│                                                                 │
+│  Responsibilities:                                              │
+│  - Render field selector                                        │
+│  - Filter operators by field type                               │
+│  - Select appropriate value input                               │
+│  - Handle rule updates                                          │
+│  - Handle rule deletion                                         │
+└─────────────────────────────────────────────────────────────────┘
+         │                    │                    │
+         │                    │                    │
+         ▼                    ▼                    ▼
+┌─────────────────┐  ┌─────────────────┐  ┌─────────────────┐
+│ FieldSelector   │  │OperatorSelector │  │  ValueInput     │
+│                 │  │                 │  │   (Factory)     │
+│ Groups fields   │  │ Filters ops by  │  │                 │
+│ by category     │  │ field type      │  │ Selects input   │
+│                 │  │                 │  │ based on:       │
+│                 │  │                 │  │ - Field type    │
+│                 │  │                 │  │ - Operator      │
+│                 │  │                 │  │ - Constraints   │
+└─────────────────┘  └─────────────────┘  └─────────────────┘
+```
+
+## Value Input Selection Logic
+
+```
+┌─────────────────────────────────────────────────────────┐
+│              RuleRow.renderValueInput()                 │
+│                                                         │
+│  1. Check if operator needs value                       │
+│     ├─ isnull, isnotnull, is_true, is_false → null     │
+│     └─ All others → continue                            │
+│                                                         │
+│  2. Check if multi-value operator                       │
+│     ├─ in, not_in, has_any, has_all → MultiChoiceValue │
+│     └─ Single value → continue                          │
+│                                                         │
+│  3. Switch on field type                                │
+│     ├─ string                                           │
+│     │  ├─ Has choices + operator=eq → ChoiceValue      │
+│     │  └─ No choices → TextValue                        │
+│     ├─ number → NumberValue                             │
+│     ├─ date → DateValue                                 │
+│     ├─ boolean → BooleanValue                           │
+│     ├─ tag → TextValue (for tag name)                   │
+│     └─ default → TextValue                              │
+└─────────────────────────────────────────────────────────┘
+```
+
+## State Management
+
+```
+Parent Component (e.g., FunnelStageBuilder)
+│
+├─ useState: rules = []
+├─ useState: logic = 'AND'
+│
+└─ <FilterRuleEditor
+     rules={rules}
+     onChange={setRules}
+     logic={logic}
+     onLogicChange={setLogic}
+     fieldRegistry={investorFields}
+   />
+
+User Actions:
+├─ Add Rule → onChange([...rules, newRule])
+├─ Update Rule → onChange(rules.map((r, i) => i === index ? updated : r))
+├─ Remove Rule → onChange(rules.filter((r, i) => i !== index))
+└─ Change Logic → onLogicChange('AND' | 'OR')
+```
+
+## Field Registry Structure
+
+```
+FieldRegistry = FieldDefinition[]
+
+FieldDefinition {
+  name: 'firm.stage'           ← Dot-notation path
+  label: 'Firm Stage'          ← Display label
+  type: 'string'               ← Data type
+  category: 'Investment'       ← Grouping
+  operators: ['eq', 'in']      ← Valid operators
+  constraints: {               ← Optional constraints
+    choices: ['Seed', 'A', 'B']  ← For dropdowns
+    min_value: 0                 ← For number inputs
+    max_value: 100               ← For number inputs
+  }
+}
+
+┌─────────────────────────────────────────────────┐
+│  Field Registry → FieldSelector                 │
+│                                                 │
+│  Groups by category:                            │
+│  ┌─────────────────────────┐                   │
+│  │ Profile              ▶  │                   │
+│  │   - Name                │                   │
+│  │   - Email               │                   │
+│  │ Investment           ▶  │                   │
+│  │   - Firm Stage          │  ← field.category │
+│  │   - Check Size          │                   │
+│  │ Metrics              ▶  │                   │
+│  │   - ICP Score           │                   │
+│  └─────────────────────────┘                   │
+└─────────────────────────────────────────────────┘
+
+┌─────────────────────────────────────────────────┐
+│  Field Type → OperatorSelector                  │
+│                                                 │
+│  Filters operators:                             │
+│  string → [eq, ne, contains, in]                │
+│  number → [eq, gt, lt, gte, lte]                │
+│  boolean → [eq, is_true, is_false]              │
+│  date → [eq, gt, lt, gte, lte]                  │
+│  tag → [has_tag, not_has_tag]                   │
+└─────────────────────────────────────────────────┘
+
+┌─────────────────────────────────────────────────┐
+│  Constraints → ValueInput                       │
+│                                                 │
+│  constraints.choices → ChoiceValue dropdown     │
+│  constraints.min_value → NumberValue min prop   │
+│  constraints.max_value → NumberValue max prop   │
+└─────────────────────────────────────────────────┘
+```
+
+## Validation Flow
+
+```
+FilterRuleEditor
+│
+├─ For each rule:
+│  │
+│  ├─ validateFilterRule(rule)
+│  │  ├─ Check field_path exists
+│  │  ├─ Check operator exists
+│  │  └─ Check value (if required for operator)
+│  │
+│  └─ Collect errors[]
+│
+└─ Display errors below each rule
+```
+
+## Example: User Creates Investor Filter
+
+```
+1. User clicks "Add Rule"
+   → onChange([...rules, { field_path: '', operator: 'eq', value: null }])
+
+2. User selects field: "Firm Stage"
+   → rule.field_path = 'firm.stage'
+   → FieldSelector finds field definition
+   → OperatorSelector shows ['eq', 'ne', 'in']
+   → Auto-select first operator: 'eq'
+   → ValueInput sees: type='string', constraints.choices=['Seed','A','B']
+   → Renders: ChoiceValueInput
+
+3. User selects operator: "is one of"
+   → rule.operator = 'in'
+   → ValueInput detects multi-value operator
+   → Switches to: MultiChoiceValueInput
+
+4. User selects values: ['Series A', 'Series B']
+   → rule.value = ['Series A', 'Series B']
+   → MultiChoiceValueInput shows tags
+   → onChange(updatedRules)
+
+5. Parent receives updated rules:
+   [{
+     field_path: 'firm.stage',
+     operator: 'in',
+     value: ['Series A', 'Series B']
+   }]
+```
+
+## Performance Considerations
+
+### Memoization
+- Field grouping is computed once per field registry change
+- Operator filtering happens per field selection (not every render)
+- Value input selection is pure function (no side effects)
+
+### Re-render Optimization
+- Each RuleRow is independent (updating one doesn't re-render others)
+- LogicToggle is separate component (doesn't re-render with rule changes)
+- Value inputs are lazy-loaded (only rendered when needed)
+
+### Bundle Size
+- Zero external dependencies (beyond React)
+- Lightweight Tailwind classes (purged in production)
+- Tree-shakeable exports
+
+## Testing Strategy
+
+### Unit Tests (FilterRuleEditor.test.tsx)
+- Rule validation
+- Field registry grouping
+- Operator filtering
+- Value constraints
+- Multi-domain testing (investors, recipes)
+
+### Integration Tests
+- Rule CRUD operations
+- Logic toggle behavior
+- Field → Operator → Value cascade
+- Error display
+
+### Visual Tests (Storybook)
+- Empty state
+- Single rule
+- Multiple rules
+- Complex filters
+- Different domains
+
+## Accessibility
+
+### Keyboard Navigation
+```
+Tab Order:
+1. Logic Toggle (radio buttons)
+2. Rule 1 Field Selector (select)
+3. Rule 1 Operator Selector (select)
+4. Rule 1 Value Input (varies)
+5. Rule 1 Delete Button
+6. [Logic Connector - not focusable]
+7. Rule 2 Field Selector
+8. ...
+9. Add Rule Button
+```
+
+### Screen Reader
+- Field labels announced
+- Selected values announced
+- Error messages announced
+- Rule count announced
+- Logic mode announced
+
+### Focus Management
+- Adding rule → focus new field selector
+- Removing rule → focus previous rule or add button
+- Submitting → focus first error
+
+## Extension Points
+
+### Custom Value Inputs
+```tsx
+// Add new value input type
+const CustomValueInput = ({ value, onChange }) => {
+  // Your custom input logic
+};
+
+// Use in RuleRow
+if (fieldType === 'custom') {
+  return <CustomValueInput value={rule.value} onChange={handleValueChange} />;
+}
+```
+
+### Custom Operators
+```typescript
+// Add to types/index.ts
+export type Operator =
+  | 'eq'
+  | 'custom_op'; // Your custom operator
+
+// Add to constants.ts
+export const OPERATOR_LABELS: Record<Operator, string> = {
+  eq: 'equals',
+  custom_op: 'my custom operator',
+};
+
+// Implement in core/operators.ts
+export function applyOperator(operator: Operator, actual: any, expected: any): boolean {
+  if (operator === 'custom_op') {
+    return customLogic(actual, expected);
+  }
+  // ...
+}
+```
+
+### Custom Field Types
+```typescript
+// Add to types/index.ts
+export type FieldType =
+  | 'string'
+  | 'custom_type'; // Your custom type
+
+// Add to getValidOperators()
+export function getValidOperators(fieldType: FieldType): ValidOperators {
+  if (fieldType === 'custom_type') {
+    return ['custom_op'];
+  }
+  // ...
+}
+
+// Handle in RuleRow.renderValueInput()
+if (type === 'custom_type') {
+  return <CustomValueInput />;
+}
+```
+
+## Related Documentation
+
+- [Main Package README](../../README.md)
+- [Type System](../../types/index.ts)
+- [Funnel Engine](../../core/engine.ts)
+- [Field Resolution](../../core/field-resolver.ts)
+- [Rule Evaluation](../../core/evaluator.ts)

package/src/components/FilterRuleEditor/FieldSelector.tsx

@@ -0,0 +1,91 @@
+/**
+ * FieldSelector Component
+ *
+ * Dropdown for selecting a field from the field registry, grouped by category.
+ *
+ * Design Goal:
+ * Users need to select from potentially dozens of fields. Grouping by category
+ * (Profile, Investment, Metrics, etc.) makes fields easier to find.
+ *
+ * Visual Hierarchy Rationale:
+ * - Categories shown with indentation for visual hierarchy
+ * - Field names indented under categories
+ * - Selected field shown in dropdown button
+ * - Full-width for consistency with other inputs
+ *
+ * Interaction Notes:
+ * - Click to open dropdown
+ * - Category labels are not selectable (disabled options)
+ * - Field selection updates the rule
+ * - Keyboard navigation supported
+ *
+ * Responsive Behavior:
+ * - Full width on all screen sizes
+ * - Dropdown scrolls if too many options
+ *
+ * Accessibility Considerations:
+ * - Proper label association
+ * - Category grouping preserved in select
+ * - Focus visible on keyboard navigation
+ */
+
+import { FieldDefinition } from '../../types';
+
+interface FieldSelectorProps {
+  fields: FieldDefinition[];
+  value: string;
+  onChange: (fieldName: string) => void;
+  error?: string;
+  className?: string;
+}
+
+export function FieldSelector({
+  fields,
+  value,
+  onChange,
+  error,
+  className = '',
+}: FieldSelectorProps) {
+  // Group fields by category
+  const grouped = fields.reduce((acc, field) => {
+    const category = field.category || 'Other';
+    if (!acc[category]) {
+      acc[category] = [];
+    }
+    acc[category].push(field);
+    return acc;
+  }, {} as Record<string, FieldDefinition[]>);
+
+  const categories = Object.keys(grouped).sort();
+
+  return (
+    <div className={`flex flex-col gap-1 ${className}`}>
+      <label htmlFor="field-selector" className="text-xs font-medium text-gray-700">
+        Field
+      </label>
+      <select
+        id="field-selector"
+        value={value}
+        onChange={(e) => onChange(e.target.value)}
+        className={`
+          w-full px-3 py-2 text-sm border rounded-md
+          bg-white
+          focus:outline-none focus:ring-2 focus:ring-blue-500 focus:border-transparent
+          ${error ? 'border-red-500' : 'border-gray-300'}
+        `}
+      >
+        <option value="">Select a field...</option>
+        {categories.map((category) => (
+          <optgroup key={category} label={category}>
+            {grouped[category].map((field) => (
+              <option key={field.name} value={field.name}>
+                {field.label}
+              </option>
+            ))}
+          </optgroup>
+        ))}
+      </select>
+      {error && <span className="text-xs text-red-600">{error}</span>}
+    </div>
+  );
+}