@spec cast_value(t(), String.t(), operator(), keyword()) ::
  {:ok, operator(), term()} | {:error, {atom(), map()}}

Casts raw for this facet — delegates to Flicker.Facet.Cast.cast/4.

Returns {:ok, operator, value} with the operator resolved: casting can refine it, so : on a range facet comes back as :between and a comma-separated list on a multiple?: true facet as :in.

Examples

iex> facet = Flicker.Facet.new(key: :created, type: :date_range)
...> Flicker.Facet.cast_value(facet, "2026-06-01..2026-06-30", :between)
{:ok, :between, %Flicker.Facet.Range{from: ~D[2026-06-01], to: ~D[2026-06-30]}}

@spec new(keyword() | map()) :: t()

Builds a facet, filling in the defaults implied by its :type for any field the caller didn't set.

Prefer this to a bare struct literal for the range types: a %Flicker.Facet{type: :date_range} literal keeps the struct's own operators: [:eq] default, which no range value can satisfy, so created:2026-06-01..2026-06-30 would degrade to free text. new/1 gives it [:between] instead.

Only absent keys are defaulted — an explicit operators: always wins, including an explicit [:eq].

Examples

iex> Flicker.Facet.new(key: :created, type: :date_range).operators
[:between]

iex> Flicker.Facet.new(key: :created, type: :date_range).scalar
:date

iex> Flicker.Facet.new(key: :price, type: :number_range).scalar
:integer

iex> Flicker.Facet.new(key: :status, type: :enum, operators: [:eq]).operators
[:eq]

iex> Flicker.Facet.new(key: :name).type
:string

@spec range?(t()) :: boolean()

Whether this facet's cast value is a Flicker.Facet.Range.

Examples

iex> Flicker.Facet.range?(%Flicker.Facet{key: :created, type: :date_range})
true

iex> Flicker.Facet.range?(%Flicker.Facet{key: :created, type: :date})
false

@spec scalar(t()) :: type() | nil

The type each endpoint of a range facet casts as — :scalar when set, otherwise the one implied by the range type. For a non-range facet this is just its own type, so callers can use it unconditionally.

Examples

iex> Flicker.Facet.scalar(%Flicker.Facet{key: :created, type: :date_range})
:date

iex> Flicker.Facet.scalar(%Flicker.Facet{key: :price, type: :number_range, scalar: :float})
:float

iex> Flicker.Facet.scalar(%Flicker.Facet{key: :name, type: :string})
:string

@spec target(t()) :: [atom()]

The Ash filter path this facet resolves to: facet.target, or [facet.key] when :target is nil.

Examples

iex> Flicker.Facet.target(%Flicker.Facet{key: :status})
[:status]

iex> Flicker.Facet.target(%Flicker.Facet{key: :worker, target: [:worker, :full_name]})
[:worker, :full_name]

@spec validate_value(t(), String.t(), operator(), keyword()) ::
  :ok | {:error, {atom(), map()}}

Validates raw for this facet without keeping the value — :ok, or {:error, {reason, params}} naming what was wrong (ADR-012).

Examples

iex> facet = Flicker.Facet.new(key: :status, type: :enum, values: [:active, :inactive])
...> Flicker.Facet.validate_value(facet, "activ", :eq)
{:error, {:not_in_values, %{value: "activ", values: [:active, :inactive]}}}

iex> facet = Flicker.Facet.new(key: :status, type: :enum, values: [:active])
...> Flicker.Facet.validate_value(facet, "active", :eq)
:ok

@spec value_label(t(), term()) :: String.t()

A single value's display label — :value_labels when it has an entry, otherwise the value as a string.

Examples

iex> facet = %Flicker.Facet{key: :status, value_labels: %{active: "Currently active"}}
...> Flicker.Facet.value_label(facet, :active)
"Currently active"

iex> Flicker.Facet.value_label(%Flicker.Facet{key: :status}, :active)
"active"

@spec value_source(t()) :: {module(), keyword()} | nil

This facet's value candidates, as a Flicker.Provider source — or nil for a facet whose values aren't drawn from a set.

Per ADR-011, a set-valued facet is edited by a nested Flicker.select, and the only thing that differs between an enum facet and a relationship facet is the provider behind it. This is the accessor that erases that difference: one editor module, one counting path, one suggestion path.

:enum and :boolean resolve to a Flicker.Providers.Static over their own closed set, with display labels from :value_labels, so an enum editor shows Established rather than established and Spec 017's :value_colors key off the same value atoms. A relationship facet resolves to the same Flicker.Providers.AshResource source Flicker.FacetSuggest.related_search/3 already builds — that clause only exists when ash is present (ADR-006), so an enum facet's Static source keeps working without it.

This is about candidate values, not about controls. Which editor opens for a type is a separate mapping (Spec 019): :boolean appears here because its true/false pair is genuinely a closed set worth suggesting, but it is edited by a switch and never opens a select.

Examples

iex> facet =
...>   Flicker.Facet.new(
...>     key: :status,
...>     type: :enum,
...>     values: [:active],
...>     value_labels: %{active: "Active"}
...>   )
...>
...> {Flicker.Providers.Static, results: [result]} = Flicker.Facet.value_source(facet)
...> {result.value, result.label}
{:active, "Active"}

iex> facet = Flicker.Facet.new(key: :verified?, type: :boolean)
...> {Flicker.Providers.Static, results: results} = Flicker.Facet.value_source(facet)
...> Enum.map(results, & &1.value)
[true, false]

iex> Flicker.Facet.value_source(Flicker.Facet.new(key: :created, type: :date_range))
nil