The optional Level 2 adapter from Spec 009: removes the Flicker.search/1 + Cinder.collection/1 boilerplate Level 1 leaves to the host, and coordinates URL state between the two libraries.

This module only compiles when both ash and cinder are present (Code.ensure_loaded?/1, the same ADR-006 pattern Flicker.Providers.AshResource and Flicker.AshPhoenixForm use): it's inert, not merely undocumented, in a build without cinder in its deps — the core suite passes with no changes required.

Query composition

query/2 is Level 1's base_query/1 recipe, generalised: given a base Ash.Resource.t() or Ash.Query.t() and the filter half of Flicker.search/1's on_change payload, it returns the composed Ash.Query.t() for Cinder.collection's query attr.

alias Flicker.Integrations.Cinder, as: FlickerCinder

def handle_info({:artist_query_changed, query, filter}, socket) do
  socket =
    socket
    |> assign(:filtered_query, FlickerCinder.query(Artist, filter))
    |> FlickerCinder.push_patch("/artists", query)

  {:noreply, socket}
end

URL state

Both libraries want query params: Cinder's own Cinder.UrlSync owns page, sort, page_size, search, after, before, plus one param per filterable column field name (verified against cinder ~> 0.15's Cinder.UrlSync.build_url/3 — see that module's known_collection_keys and its _filter_fields metadata key). A bare ?q= risks colliding with a column literally named q; this adapter reserves "flicker_q" (url_param/0) — prefixed distinctly enough that no realistic column name collides with it, and disjoint from Cinder's own reserved names — as the one param it ever reads or writes. This resolves Spec 009's open question on namespacing convention; see that spec's Open Questions section for the decision record.

Serialisation round-trips Flicker.Query.t()'s :input field — the verbatim string the user typed — never :text or a reconstruction of :facets (both are lossy: facet tokens are stripped from :text, and :facets' cast values can't reproduce the original literal, e.g. TRUE vs. true, or 7d vs. the date it resolved to). Restoring a shared URL re-Flicker.Query.parse/2s that exact string, the same way the host's own Flicker.search/1 instance would have.

alias Flicker.Integrations.Cinder, as: FlickerCinder

def handle_params(params, uri, socket) do
  facets = FlickerCinder.facets(%{resource: Artist, facets: [:status, :tier]})
  {text, _query, filter} = FlickerCinder.restore(params, facets)

  socket =
    params
    |> Cinder.UrlSync.handle_params(uri, socket)
    |> assign(:search_text, text)
    |> assign(:filtered_query, FlickerCinder.query(Artist, filter))

  {:noreply, socket}
end

# render/1
# <Flicker.search id="artist-search" text={@search_text} resource={Artist} ... />

text (a new optional attr on Flicker.search/1) is adopted once, on the component's first mount only — it pre-populates the input from the restored string without fighting the component's own ownership of what the user types next.

Double-filter UX

Flicker's facets and Cinder's own column filters (filter/filter_fn on a <:col>, or show_filters) can both narrow the same collection. The convention: a field is filtered in one place, not both — pick whichever owns it. When Flicker owns filtering for the whole collection (the common case: one search bar above the table), pass show_filters={false} to Cinder.collection so its own filter UI doesn't render at all (see the playground page and guide). When a column needs filtering that no Flicker facet covers, let Cinder's own column filter own that one field instead — never configure a Flicker facet and a Cinder column filter over the same field at once, since the two would apply independently (an unsatisfiable AND, not visible to either component) and confuse users who cleared one filter and still see narrowed results.

overlapping_fields/2 is a drift guard for that convention: given the facet keys configured on a Flicker.search/1 and the field names a Cinder.collection's columns declare filter on, it returns the fields governed by both — empty when the convention holds. A test asserting this list stays empty catches a column filter and a facet quietly drifting onto the same field as either configuration changes.