Checks if a filter group is visible and accessible for the current state.

Checks if a row action is visible for a given record and state.

Used by templates to filter visible row actions.

@spec build_active_filter_chips(map(), map()) :: {[map()], boolean()}

Builds active filter chip data for custom templates.

Returns {visible_chips, has_any_active_filters} where:

• visible_chips excludes visible: false filters (hidden from UI but still active in state)
• has_any_active_filters is true if any filter has a value (including hidden ones)

Use has_any_active_filters for the "Clear all" button visibility so users can always clear hidden filters (e.g., id filter from URL).

@spec check_all_gallery(Phoenix.LiveView.JS.t()) :: Phoenix.LiveView.JS.t()

Checks all media gallery checkboxes.

@spec check_all_table(Phoenix.LiveView.JS.t()) :: Phoenix.LiveView.JS.t()

Checks all table row checkboxes and adds selection highlighting.

@spec format_chip_value(term()) :: String.t()

Format a filter value for display in a chip.

Returns the Tailwind grid-cols class for a given column count.

@spec group_columns(map()) :: pos_integer() | nil

Returns the column count from a filter group's UI config, or nil if not set. Pass the result to grid_cols/1 for the Tailwind class.

@spec group_icon(map()) :: String.t()

Returns the icon name for a filter group, falling back to "hero-funnel". Useful for custom templates rendering their own filter group UI.

@spec group_label(map()) :: String.t()

Returns the resolved label for a filter group, falling back to humanized group name. Useful for custom templates rendering their own filter group UI.

@spec group_panel_class(map()) :: String.t()

Returns the CSS class for a collapsible filter group panel wrapper. Falls back to a default rounded panel style if not set in DSL.

@spec has_chip_value?(term()) :: boolean()

Check if a filter value is meaningful (non-nil, non-empty).

@spec has_user_visible_actions?(list(), list() | nil, map()) :: boolean()

Checks if any row actions or dropdowns are potentially visible for the current user.

Used by templates to decide whether to render the Actions column header. Does not evaluate per-record visibility functions — only checks restricted and boolean/atom visible values.

@spec has_visible_bulk_actions?(list() | term(), atom()) :: boolean()

Check if any bulk actions are visible for the given archive status.

Returns true if there is at least one bulk action that should be shown for the current mode (active or archived).

@spec inline_filter_class(map()) :: String.t()

Returns a CSS class for inline (non-collapsible) filters based on filter type. Text filters get a flexible width, relation filters a minimum width, others a smaller minimum. Only used when the group has no custom class (i.e., wrapper is "contents"). Custom templates can override this if they need different sizing.

@spec inline_group_class(map()) :: String.t()

Returns the CSS class for an inline (non-collapsible) group wrapper. If the group has ui do class "..." end, uses that. Otherwise defaults to "contents" which makes the wrapper transparent so filters participate directly in the parent flex layout.

@spec merge_relation_filter_state(list(), map()) :: list()

Merges dynamic relation filter state (options, loading, etc.) into filter configs.

@spec prepare_filter_groups(list(), list(), map()) :: map()

Prepares all filter groups for rendering by custom templates.

Resolves accessible filters, splits them into visible groups (sorted by position), and identifies ungrouped filters. Each group entry includes the resolved filter structs (not just names).

Returns a map:

%{
  all_filters: [filter_struct],
  visible_groups: [%{group | resolved_filters: [filter_struct]}],
  ungrouped_filters: [filter_struct],
  inline_groups: [group],      # non-collapsible
  collapsible_groups: [group]   # collapsible
}

@spec render_empty_state(map()) :: Phoenix.LiveView.Rendered.t()

Renders the empty state with configurable message, icon, and action.

@spec render_error_state(map()) :: Phoenix.LiveView.Rendered.t()

Renders the error state with configurable message, icon, and retry button.

@spec render_loading(map()) :: Phoenix.LiveView.Rendered.t()

Renders the loading state with spinner and configurable text.

@spec resolve_chip_value(atom(), term(), map()) :: String.t()

Resolve a filter chip's display value, using relation labels when available.

Sorts filter groups by their position attribute.

@spec uncheck_all(Phoenix.LiveView.JS.t()) :: Phoenix.LiveView.JS.t()

Unchecks all selection checkboxes and removes selection highlighting.