Filter Builder

interface FilterField {
  value: string;                         // Field identifier
  label: string;                         // Display label
  type?:
    | 'text' | 'number' | 'currency' | 'percent' | 'rating'
    | 'date' | 'datetime' | 'time'
    | 'boolean'
    | 'select' | 'status'
    | 'lookup' | 'master_detail' | 'user' | 'owner'; // Field type
  options?: Array<{ value: string; label: string }>;  // Static options (select-like)
  // Lookup-like fields without `options` render a remote-search picker that
  // queries the configured DataSource. The metadata below describes how to
  // resolve and display referenced records:
  referenceTo?: string;                  // Referenced object name (e.g. "user")
  displayField?: string;                 // Display field on referenced object (default "name")
  idField?: string;                      // Id field on referenced object (default "id")
}

interface FilterCondition {
  id: string;                            // Condition identifier
  field: string;                         // Field to filter on
  operator: string;                      // Comparison operator
  value: any;                            // Filter value
}

interface FilterGroup {
  id: string;                            // Group identifier
  logic: 'and' | 'or';                  // Logic operator (AND/OR)
  conditions: (FilterCondition | FilterGroup)[];  // Conditions or nested groups
}

interface FilterBuilderSchema {
  type: 'filter-builder';
  
  // Required
  name: string;                          // Field name for form submission
  fields: FilterField[];                 // Available fields for filtering
  
  // Configuration
  label?: string;                        // Component label
  value?: FilterGroup;                   // Initial/controlled filter value
  allowGroups?: boolean;                 // Allow nested groups (default: true)
  maxDepth?: number;                     // Maximum nesting depth (default: 3)
  
  // Events
  onChange?: (filter: FilterGroup) => void;  // Change handler
  
  // Styling
  className?: string;                    // Tailwind CSS classes
  wrapperClass?: string;                 // Wrapper container classes
  
  // Base properties
  id?: string;
  visible?: boolean | string;
  testId?: string;
}