Filter Builder

The Filter Builder component provides a visual interface for creating filter queries: a flat list of conditions combined with AND or OR, over multiple operators.

Schema

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'; // 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 (optional)
  logic: 'and' | 'or';                  // Logic operator (AND/OR)
  conditions: FilterCondition[];         // Flat condition rows (no 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
  
  // Events
  // RUNTIME SLOT (objectui#6124): a React host supplies it; JSON refuses it
  // by name. Author behaviour as a node type, e.g. an action:button node.
  onChange?: (filter: FilterGroup) => void;  // Change handler
  
  // Styling
  className?: string;                    // Tailwind CSS classes
  wrapperClass?: string;                 // Wrapper container classes
  
  // Base properties
  id?: string;
  visible?: boolean | string | { dialect?: string; source: string };
  testId?: string;
}

Retired: nested groups, `allowGroups` and `maxDepth`

A filter group is one level deep. Every entry of conditions is one field / operator / value row, and the group's logic combines all of them. The builder never drew a nested group: it showed a sub-group as a row with blank field and operator selects and did not show the sub-group's own conditions. Nested sub-groups and the two keys that configured them, allowGroups and maxDepth, are therefore retired (objectui#9306). Validation now refuses each of them by name. Write the rows into the one group and remove the two keys.