LiveFilter.FieldRegistry (LiveFilter v0.1.0)

View Source

Standardized field configuration for LiveFilter.

The FieldRegistry provides a way to define and manage field configurations in a centralized way. It's completely optional - you can use LiveFilter without ever creating a registry.

Benefits

  • Centralized field definitions
  • Type safety and validation
  • Consistent operator defaults
  • UI component hints
  • Support for custom field types via the Field protocol

Example

defmodule MyApp.FilterFields do
  def registry do
    LiveFilter.FieldRegistry.new()
    |> LiveFilter.FieldRegistry.add_field(:title, :string,
      label: "Title",
      operators: [:contains, :equals, :starts_with],
      placeholder: "Search titles..."
    )
    |> LiveFilter.FieldRegistry.add_field(:status, :enum,
      label: "Status",
      options: [
        {"Pending", :pending},
        {"In Progress", :in_progress},
        {"Completed", :completed}
      ],
      default_operator: :in,
      multiple: true
    )
    |> LiveFilter.FieldRegistry.add_field(:priority, MyApp.PriorityField.new(),
      label: "Priority",
      icon: "hero-flag"
    )
  end
end

Summary

Functions

Add a field to the registry.

Helper to create a boolean field configuration.

Helper to create a date field configuration.

Helper to create an enum field configuration.

Create a registry from a list of field definitions.

Get the default operator for a field.

Get field configuration by name.

Get all fields in a group.

Get available operators for a field.

Get the UI component suggestion for a field.

List all fields in the registry.

Create a new empty field registry.

Helper to create a string field configuration.

Convert UI value to filter value for a field.

Convert filter value to UI value for a field.

Validate a value for a field.

Types

field_config()

@type field_config() :: %{
  name: atom(),
  type: atom() | struct(),
  label: String.t(),
  operators: [atom()] | nil,
  default_operator: atom() | nil,
  required: boolean(),
  options: keyword() | map()
}

t()

@type t() :: %LiveFilter.FieldRegistry{
  fields: %{required(atom()) => field_config()},
  groups: [atom()],
  metadata: map()
}

Functions

add_field(registry, name, type, opts \\ [])

Add a field to the registry.

Parameters

  • registry - The registry to add to
  • name - The field name (atom)
  • type - Either an atom (:string, :integer, etc.) or a struct implementing Field protocol
  • opts - Field configuration options

Options

  • :label - Human-readable label
  • :operators - List of allowed operators (nil means use type defaults)
  • :default_operator - Default operator (nil means use type default)
  • :required - Whether the field is required
  • :placeholder - UI placeholder text
  • :help_text - Help text for users
  • :icon - Icon identifier for UI
  • :group - Group name for organizing fields
  • :options - For enum/select fields, the available options
  • :multiple - For enum fields, whether multiple selection is allowed
  • :validate - Custom validation function
  • Any other options are stored as-is

Examples

# Simple field
registry
|> add_field(:title, :string, label: "Title")

# Enum field with options
registry
|> add_field(:status, :enum,
  label: "Status",
  options: [{"Active", :active}, {"Inactive", :inactive}],
  default_operator: :in,
  multiple: true
)

# Custom field type
registry
|> add_field(:priority, MyApp.PriorityField.new(), label: "Priority")

boolean_field(name, label, opts \\ [])

Helper to create a boolean field configuration.

date_field(name, label, opts \\ [])

Helper to create a date field configuration.

enum_field(name, label, options, opts \\ [])

Helper to create an enum field configuration.

from_fields(field_definitions)

Create a registry from a list of field definitions.

Example

fields = [
  LiveFilter.FieldRegistry.string_field(:title, "Title"),
  LiveFilter.FieldRegistry.enum_field(:status, "Status", [
    {"Active", :active},
    {"Inactive", :inactive}
  ]),
  {:custom, MyCustomField.new(), label: "Custom Field"}
]

registry = LiveFilter.FieldRegistry.from_fields(fields)

get_default_operator(registry, field_name)

Get the default operator for a field.

Uses field config if specified, otherwise delegates to the Field protocol.

get_field(field_registry, name)

Get field configuration by name.

Returns nil if field not found.

get_fields_in_group(registry, group_name)

Get all fields in a group.

get_operators(registry, field_name)

Get available operators for a field.

Uses field config if specified, otherwise delegates to the Field protocol.

get_ui_component(registry, field_name)

Get the UI component suggestion for a field.

list_fields(field_registry)

List all fields in the registry.

Returns a list of {name, config} tuples.

new(opts \\ [])

Create a new empty field registry.

Options

  • :metadata - Any metadata to attach to the registry

string_field(name, label, opts \\ [])

Helper to create a string field configuration.

to_filter_value(registry, field_name, ui_value)

Convert UI value to filter value for a field.

to_ui_value(registry, field_name, filter_value)

Convert filter value to UI value for a field.

validate(registry, field_name, value)

Validate a value for a field.

Uses custom validator if provided, otherwise delegates to Field protocol.