# `Cinder.Controls`
[🔗](https://github.com/sevenseacat/cinder/blob/v0.12.1/lib/cinder/controls.ex#L1)

Data preparation and render helpers for custom filter/search control layouts.

When using the `:controls` slot on `Cinder.collection`, this module provides
helpers to render individual filters, search inputs, and headers while keeping
Cinder's state management, URL sync, and query building intact.

## Usage

The `:controls` slot receives a controls data map via `:let`. Shared context
(theme, target, filter values) is stored once at the top level — pass it
explicitly to render helpers:

    <Cinder.collection resource={MyApp.User}>
      <:col field="name" filter sort search />
      <:col field="status" filter={:select} />

      <:controls :let={controls}>
        <div class="flex items-center gap-4 mb-4">
          <Cinder.Controls.render_search
            search={controls.search}
            theme={controls.theme}
            target={controls.target}
          />
        </div>
        <div class="grid grid-cols-2 gap-4">
          <Cinder.Controls.render_filter
            :for={{_name, filter} <- controls.filters}
            filter={filter}
            theme={controls.theme}
            target={controls.target}
          />
        </div>
      </:controls>
    </Cinder.collection>

## Selective rendering

Filters is a keyword list keyed by field name, so you can access individual
filters directly:

    <:controls :let={controls}>
      <Cinder.Controls.render_header {controls} />
      <div class="flex gap-2">
        <Cinder.Controls.render_filter
          filter={controls.filters[:status]}
          theme={controls.theme}
          target={controls.target}
        />
        <Cinder.Controls.render_filter
          filter={controls.filters[:name]}
          theme={controls.theme}
          target={controls.target}
        />
      </div>
    </:controls>

# `build_controls_data`

Builds the controls data map from FilterManager assigns.

Returns a map with all the data needed to render custom filter controls:

- `:filters` — keyword list of filter data maps keyed by field atom, preserving column order.
    Access by name: `controls.filters[:status]`. Iterate: `for {_name, filter} <- controls.filters`.
- `:search` — search input data map (value, name, label, placeholder, id), or `nil` when disabled
- `:active_filter_count` — number of currently active filters
- `:target` — LiveComponent target for `phx-target`
- `:theme` — resolved theme map
- `:table_id` — table DOM ID prefix
- `:filters_label` — translated label for the filters section
- `:filter_mode` — current filter display mode
- `:filter_values` — shared filter values map (for render helpers)
- `:raw_filter_params` — raw form params (for autocomplete filters)

# `render_filter`

Renders a single filter (label + input + clear button).

Delegates to the existing `FilterManager.filter_label/1` and
`FilterManager.filter_input/1` components.

## Attributes

- `filter` — a filter data map from `build_controls_data/1`
- `theme` — theme map (required)
- `target` — LiveComponent target for `phx-target`
- `filter_values` — shared filter values map (for filters referencing other values)
- `raw_filter_params` — raw form params (for autocomplete filters)

## Attributes

* `filter` (`:map`) (required)
* `theme` (`:map`) (required)
* `target` (`:any`) - Defaults to `nil`.
* `filter_values` (`:map`) - Defaults to `%{}`.
* `raw_filter_params` (`:map`) - Defaults to `%{}`.

# `render_header`

Renders the default filter header (title, active count badge, clear all button, toggle).

Accepts either the full controls data map or individual attributes.

## Attributes

- `table_id` — DOM ID prefix
- `filters_label` — label text for the header
- `active_filter_count` — number of active filters
- `filter_mode` — display mode (true, :toggle, :toggle_open)
- `target` — LiveComponent target
- `theme` — theme map

## Attributes

* `table_id` (`:string`) (required)
* `filters_label` (`:string`) (required)
* `active_filter_count` (`:integer`) (required)
* `filter_mode` (`:any`) - Defaults to `true`.
* `target` (`:any`) - Defaults to `nil`.
* `theme` (`:map`) (required)
* `has_filters` (`:boolean`) - Defaults to `true`.

# `render_search`

Renders the default search input.

## Attributes

- `search` — the search data map from `build_controls_data/1`
- `theme` — theme map (required)
- `target` — LiveComponent target for `phx-target`

## Attributes

* `search` (`:map`) - Defaults to `nil`.
* `theme` (`:map`) (required)
* `target` (`:any`) - Defaults to `nil`.

---

*Consult [api-reference.md](api-reference.md) for complete listing*