Filtering System

+-----------------------------+
|         BeepFilter          |  UI only: takes EntityStructure,
|       (UI Builder)          |  shows filter widgets (TagPills, etc.)
|                             |  Raises FilterApplied event -----+
+-----------------------------+                                  |
                                                                 | FilterConfiguration
                                              +------------------v-----------+
                                              |    BeepGridPro / BeepListBox |
                                              |  (Consumer)                  |
                                              |  Uses FilterEngine<T>        |
                                              +------------------------------+

BeepFilter()
  : base()
    |- InitializeComponent()          // Size=600x45, DoubleBuffered, ApplyThemeToChilds=false
    +- InitializeFilterControl()
         |- UpdatePainter()            // Creates TagPillsFilterPainter (default)
         |- _activeFilter = new FilterConfiguration { Criteria = [] }
         |- InitializePhase1Components()
         |     |- _keyboardHandler = new FilterKeyboardHandler(this)
         |     |- _suggestionProvider = new FilterSuggestionProvider()
         |     +- _validationHelper  = new FilterValidationHelper()
         +- RecalculateLayout()

// Painter is hot-swapped; existing ActiveFilter is preserved
beepFilter.FilterStyle = FilterStyle.GroupedRows;

// Get description from factory
string desc = FilterPainterFactory.GetStyleDescription(FilterStyle.QuickSearch);
// "Single search bar with instant filtering - quick and easy"

bool ready = FilterPainterFactory.IsFullyImplemented(FilterStyle.AdvancedDialog); // true

// Simple
var c1 = new FilterCriteria("Country", FilterOperator.Equals, "Germany");

// Range
var c2 = new FilterCriteria("Price", FilterOperator.Between, 10.0, 50.0);

// Case-sensitive text
var c3 = new FilterCriteria("Code", FilterOperator.StartsWith, "ABC", caseSensitive: true);

// Disabled (remembered but not evaluated)
c3.IsEnabled = false;

var config = new FilterConfiguration("Q1 EU Customers")
{
    Logic = FilterLogic.And
};
config.AddCriteria(new FilterCriteria("Region",  FilterOperator.Equals,      "EU"));
config.AddCriteria(new FilterCriteria("Revenue", FilterOperator.GreaterThan, 50000));

// Serialize / deserialize (System.Text.Json compatible)
string json   = JsonSerializer.Serialize(config);
var    loaded = JsonSerializer.Deserialize<FilterConfiguration>(json);

// Works with any typed collection
var engine = new FilterEngine<Customer>(customers);

// Works with ExpandoObject (BeepGridPro uses this internally)
var engine = new FilterEngine<ExpandoObject>(gridRows);

// Option A: get filtered rows
var visible = engine.ApplyFilter(config).ToList();

// Option B: get matching indices (faster for large virtual grids)
var indices = engine.ApplyFilterGetIndices(config);
HideRowsNotIn(indices);

// Quick search across all properties
var results = engine.ApplyQuickFilter("Smith", propertyName: null);

var provider = new FilterSuggestionProvider();
provider.SetDataSource(myList);  // invalidates cache

var suggestions = provider.GetSuggestions(
    columnName: "Country", partialValue: "Ge", maxResults: 10);
// Returns: Recent (star), Frequent (fire), Partial-match
// Each item: Value, DisplayText, MatchCount, Relevance, Type

var helper = new FilterValidationHelper();
var result = helper.Validate(criteria, DbFieldCategory.Numeric);
if (!result.IsValid)
    ShowError(result.ErrorMessage);
// Guards: null column, operator/type mismatch,
//         missing Value2 for Between, type incompatibility

var filter = new BeepFilter
{
    EntityStructure = myEntityStructure,
    FilterStyle     = FilterStyle.TagPills,
    DataSource      = myList,         // optional: enables suggestions
    Dock            = DockStyle.Top
};

filter.FilterApplied += (s, e) =>
{
    var engine  = new FilterEngine<Product>(allProducts);
    var results = engine.ApplyFilter(filter.ActiveFilter);
    listBox1.DataSource = results.ToList();
};

panel.Controls.Add(filter);

var beepFilter = new BeepFilter
{
    EntityStructure = grid.EntityStructure,
    FilterStyle     = FilterStyle.GroupedRows,
    Dock            = DockStyle.Top
};

beepFilter.FilterApplied += (s, e) =>
{
    // Grid's ActiveFilter setter calls FilterEngine<ExpandoObject> internally
    grid.ActiveFilter = beepFilter.ActiveFilter;
};

// Or use the grid's built-in integration:
grid.ShowAdvancedFilterDialog();   // opens AdvancedDialog style
grid.ApplyQuickFilter("Smith");    // internal QuickSearch

var config = new FilterConfiguration();
config.AddCriteria(new FilterCriteria("Status", FilterOperator.Equals,            "Active"));
config.AddCriteria(new FilterCriteria("Score",  FilterOperator.GreaterThanOrEqual, 80));
config.Logic = FilterLogic.And;

var engine  = new FilterEngine<Employee>(employees);
var visible = engine.ApplyFilter(config).ToList();

// Get just the indices (faster for large virtual lists)
var indices = engine.ApplyFilterGetIndices(config);

// Save
beepFilter.ConfigurationSaveRequested += (s, e) =>
{
    var config = beepFilter.ActiveFilter;
    config.Name = "EU High-Value Q1";
    File.WriteAllText("filters/eu-q1.json", JsonSerializer.Serialize(config));
};

// Load
beepFilter.ConfigurationLoadRequested += (s, e) =>
{
    var json   = File.ReadAllText("filters/eu-q1.json");
    var config = JsonSerializer.Deserialize<FilterConfiguration>(json)!;
    beepFilter.ActiveFilter = config;
    beepFilter.Invalidate();
};