LiveFilter.UIState (LiveFilter v0.1.0)

View Source

Optional UI state management for LiveFilter.

Provides helpers for managing UI state that maps to FilterGroup structures. All functions can be overridden or ignored entirely - this module is purely optional and designed to reduce boilerplate for common patterns.

Usage

# Use default converter
filters = LiveFilter.UIState.ui_to_filters(ui_state)

# Use custom converter
filters = LiveFilter.UIState.ui_to_filters(ui_state,
  converter: &MyApp.custom_converter/2,
  fields: MyApp.field_config()
)

# Extract values from filters back to UI
search_query = LiveFilter.UIState.extract_filter_value(filters, :_search)
selected_statuses = LiveFilter.UIState.extract_filter_value(filters, :status,
  operator: :in,
  default: []
)

Summary

Functions

Suggested UI state structure. Users can use any map structure they prefer.

Extract a filter value from a list of filters or FilterGroup.

Extract all UI-relevant values from filters at once. Returns a map with common UI state fields populated.

Convert a FilterGroup with UI state to filters. Helper for when you have both a FilterGroup and separate UI state.

Convert UI state to a list of filters.

Types

converter_fun()

@type converter_fun() :: (ui_state(), keyword() -> [LiveFilter.Filter.t()])

extractor_fun()

@type extractor_fun() :: ([LiveFilter.Filter.t()], atom(), keyword() -> any())

ui_state()

@type ui_state() :: map()

Functions

%LiveFilter.UIState{}

(struct)

Suggested UI state structure. Users can use any map structure they prefer.

extract_filter_value(filters_or_group, field, opts \\ [])

Extract a filter value from a list of filters or FilterGroup.

Options

  • :extractor - Custom extractor function
  • :operator - Match specific operator (default: any)
  • :default - Default value if not found
  • :transform - Function to transform the extracted value

Examples

# Extract search query
query = extract_filter_value(filters, :_search)

# Extract multi-select with specific operator
statuses = extract_filter_value(filters, :status,
  operator: :in,
  default: []
)

# Transform extracted value
assignee_names = extract_filter_value(filters, :assigned_to,
  transform: fn ids -> Enum.map(ids, &Users.get_name/1) end
)

filters_to_ui_state(filters_or_group, opts \\ [])

Extract all UI-relevant values from filters at once. Returns a map with common UI state fields populated.

Options

  • :search_field - Field name for search (default: :_search)
  • :fields - List of {field, type} tuples to extract
  • :transform - Map of field -> transform function

merge_ui_with_filters(filter_group, ui_state, opts \\ [])

Convert a FilterGroup with UI state to filters. Helper for when you have both a FilterGroup and separate UI state.

ui_to_filters(ui_state, opts \\ [])

Convert UI state to a list of filters.

Options

  • :converter - Custom converter function (default: default_converter/2)
  • :fields - Field configuration for the converter
  • Any other options are passed to the converter

Examples

# Using default converter
ui_state = %{
  search_query: "urgent",
  selected_values: %{status: [:pending, :in_progress]},
  date_ranges: %{due_date: {~D[2025-01-01], ~D[2025-01-31]}}
}

filters = LiveFilter.UIState.ui_to_filters(ui_state,
  fields: [
    {:status, :enum, default_op: :in},
    {:due_date, :date, default_op: :between}
  ]
)