@spec completions(
  [String.t()],
  keyword()
) :: [completion()]

Every completion available to an expression field: the declared paths first, then the grammar.

candidates is the declared datamodel path list - what StatifierBlocks.Datamodel.candidates/3 returns, arriving through the expression_component seam as :candidates. Paths lead because they are the ones an author cannot look up.

opts is passed through to Predicator.Vocabulary.functions/1, so a host with its own Predicator.FunctionProvider modules offers exactly the functions its own contexts will accept.

Examples

iex> StatifierUI.Expression.completions() |> Enum.any?(&(&1.insert == ">="))
true

iex> StatifierUI.Expression.completions([], builtins: false)
...> |> Enum.any?(&(&1.kind == "function"))
false

@spec datalist([completion()]) :: [completion()]

The subset a native <datalist> can usefully offer: the word-shaped completions.

A <datalist> filters its options against the whole field value, and it cannot insert at a caret. Offering "::" or "(" through one is noise, so the no-JavaScript affordance carries paths, keywords, and function names and leaves the symbol operators to the hook.

Examples

iex> StatifierUI.Expression.completions() |> StatifierUI.Expression.datalist()
...> |> Enum.any?(&(&1.insert == "::"))
false

@spec operators(value_kind()) :: [operator()]

The operators a picklist offers beside a value of the given kind, read from Predicator.Simple.operators/1.

Eligibility is the grammar's answer, not this module's: which operators are worth offering beside a date as opposed to a number is decided by the :value_kinds predicator stamps on its own operator entries, so an operator the lexer would reject - or one the grammar does not admit for this kind of value - cannot be offered here. Until px-84i landed that function there was a table here instead, and ADR-0007's 2026-09-04 amendment - accepted 2026-09-05 - named it as the one local exception; delegating closes it.

:op builds the clause, :lexeme is the spelling the expression will carry, :label is the display phrase, and :detail is the grammar's one-line description, or nil when Predicator.Vocabulary is not resolvable.

Empty when simple_available?/0 is false, for the same reason simple/2 answers :outside: there is nothing truthful to offer. An atom the @spec does not admit is handed to upstream unchanged rather than rejected here, so one that happens to name a Predicator.Vocabulary kind - :number, :list - gets the grammar's answer for that kind, and any other atom raises there. The raise is upstream's own stance and the right one: an empty list would say "no operators here" about a kind that does not exist.

Examples

iex> StatifierUI.Expression.operators(:boolean) |> Enum.map(& &1.op)
[:equal_equal, :strict_eq, :ne, :strict_ne, :contains]

iex> StatifierUI.Expression.operators({:list, :string}) |> Enum.map(& &1.lexeme)
["IN"]

iex> StatifierUI.Expression.operators(:integer) |> Enum.find(&(&1.op == :gte))
%{op: :gte, lexeme: ">=", label: "is at least", detail: "Greater than or equal to"}

@spec relative_date_candidates() :: [candidate()]

The relative dates offered beside a path a host declared :date or :datetime.

A date declaration carries no value list of its own the way {:one_of, _} does, and a date field with only a free-text control asks an author to spell a grammar they should not have to know. So a small fixed set is offered instead. Which dates those are is presentation, which ADR-0007's picklist amendment leaves to the component rather than to the record; the set lives here rather than in the component so it is testable without a browser, and a host wanting different ones supplies :value_candidates for the path, which wins.

Every entry is checked against Predicator.Simple.duration_units/0 before it is offered, so a unit the resolved grammar does not know is dropped rather than written into a source string the writer would refuse.

Empty when simple_available?/0 is false, and empty when the resolved module predates duration_units/0 - that function is deliberately not added to simple_available?/0's four-export guard, because a predicator that can classify and write should lose the offered dates, not the whole picklist.

Examples

iex> StatifierUI.Expression.relative_date_candidates() |> Enum.map(& &1.label)
["1d ago", "7d ago", "30d ago", "90d ago", "7d from now", "30d from now"]

@spec segments(String.t()) :: {:ok, [tuple()]} | :error

The path segments a declared datamodel path parses to.

A picklist's field dropdown offers the paths a host declared, as strings. Swapping a clause onto one of them needs that path in the structural form a clause carries, and the only honest way to get there is predicator's own parser - a path split on dots here would read account['tags'] wrong and would be a second parser besides.

:error for a string that is not a path, and for every string when Predicator.Simple is not resolvable.

Examples

iex> StatifierUI.Expression.segments("card.brand")
{:ok, [root: "card", property: "brand"]}

iex> StatifierUI.Expression.segments("amount >= 500")
:error

@spec simple(
  String.t(),
  keyword()
) :: {:ok, [row()], connective()} | :outside | {:error, term()}

Classifies a source string against the picklist-renderable subset.

Three answers, and they are three different questions:

• {:ok, rows, connective} - inside the subset. rows is one row/0 per clause and connective is nil for a single row, :and or :or for two or more.
• :outside - a valid expression a picklist cannot draw. Offer the text editor; this is not an error.
• {:error, error} - the source does not parse, carrying predicator's own parse error with the position of the failure.

opts takes :value_candidates - a map from a clause's :path to the values a host offers for it, as candidate/0 maps or bare strings. Only the host knows its own value sets, so nothing is inferred here; a path with no entry gets an empty list and the renderer falls back to a free-text value control.

opts also takes :path_types - a map from a clause's :path to the declared_kind/0 the host declares for it. A declaration decides which operators the row offers, asked of the grammar exactly as an observed kind is; it fills the candidate list for a {:one_of, _} path that :value_candidates says nothing about, and offers relative_date_candidates/0 for a :date or :datetime one. It never decides a control whose shape the source does not have, and it never rewrites, coerces, or refuses anything: a declaration the source disagrees with lands in :advisories. A path with no entry behaves exactly as it did before there was a map at all.

Only the host knows its own datamodel, so nothing is read from one here. The caller builds the map - statifier_blocks, or any host with a datamodel document to read - which is why this package takes no dependency on one.

When simple_available?/0 is false - the resolved predicator has no Predicator.Simple, or the module the :predicator_simple key points at does not export all four of from_source/1, to_source/1, operators/1 and value_kind/1 - every source string answers :outside. That is a degraded answer rather than a wrong one: the component renders the text input it would render for an unsupported expression.

Examples

iex> {:ok, [row], nil} = StatifierUI.Expression.simple("plan == 'pro'")
iex> {row.path, row.op, row.value_source}
{"plan", :equal_equal, "'pro'"}

iex> {:ok, rows, connective} = StatifierUI.Expression.simple("status == 'active' AND amount >= 500")
iex> {length(rows), connective}
{2, :and}

iex> StatifierUI.Expression.simple("status == 'active' AND (amount >= 500 OR plan == 'pro')")
:outside

iex> {:error, error} = StatifierUI.Expression.simple("amount >= >=")
iex> error.position
{1, 11}

iex> {:ok, [row], nil} =
...>   StatifierUI.Expression.simple("step in ['payment', 'review']",
...>     value_candidates: %{"step" => ["payment", "review", "confirmation"]}
...>   )
iex> {row.value_kind, Enum.map(row.candidates, & &1.value)}
{{:list, :string}, ["payment", "review", "confirmation"]}

iex> {:ok, [row], nil} =
...>   StatifierUI.Expression.simple("plan == 'pro'", path_types: %{"plan" => :boolean})
iex> {row.control_kind, Enum.map(row.operators, & &1.lexeme)}
{:boolean, ["==", "===", "!=", "!==", "CONTAINS"]}

iex> {:ok, [row], nil} =
...>   StatifierUI.Expression.simple("amount >= 500", path_types: %{"amount" => :string})
iex> Enum.map(row.advisories, & &1.reason)
[:value_kind]

@spec simple_available?() :: boolean()

Whether the resolved predicator exposes a usable Predicator.Simple.

The counterpart to vocabulary_available?/0, and the same distinction: a component stamps it so a host can tell "this expression is outside the subset" from "this predicator cannot answer the question".

Usable is four exports, not one loaded module: from_source/1, to_source/1, operators/1 and value_kind/1 all have to be there. Under the ~> 9.4 requirement that is inert, since every admitted predicator carries all four; it is a host overriding :predicator_simple that the condition measures, and a stub exporting three of the four reads as unavailable - which is why the fourth joined the guard when this module started asking upstream what kind a value is. Every function this guard gates then degrades together: simple/2 to :outside, operators/1 to [], and source/2, value_source/2 and segments/1 to :error. A picklist is lost silently, so a host stubbing this module is stubbing the whole surface.

Examples

iex> is_boolean(StatifierUI.Expression.simple_available?())
true

@spec source([row() | {[tuple()], atom(), term()}], connective()) ::
  {:ok, String.t()} | :error

Writes a source string back from the rows simple/2 returned.

The write half of the same round trip: simple/2 reads source into rows and this reads rows back into source, both through Predicator.Simple, so a picklist never has to spell an operator, a quote, or a connective itself. That is what makes the rendered dropdowns a view of the source text rather than a second representation of the condition - a renderer edits a row's :segments, :op, or :value, asks for the source, and stores the string it gets back.

:error when Predicator.Simple is not resolvable, or when rows is empty: there is no source string to write, and inventing one would be the duplication this module exists to avoid.

Examples

iex> {:ok, rows, connective} =
...>   StatifierUI.Expression.simple("status == 'active' AND amount >= 500")
iex> StatifierUI.Expression.source(rows, connective)
{:ok, "status == 'active' AND amount >= 500"}

iex> {:ok, [row], nil} = StatifierUI.Expression.simple("plan == 'pro'")
iex> StatifierUI.Expression.source([%{row | value: {:string, "free", :single}}], nil)
{:ok, "plan == 'free'"}

iex> StatifierUI.Expression.source([], nil)
:error

@spec value_candidates(
  %{optional(String.t()) => [candidate() | String.t()]},
  String.t()
) :: [
  candidate()
]

The values a host offers for one clause path, normalized.

candidates is simple/2's :value_candidates map. An entry may be a candidate/0 map or a bare string, because a declared path list is usually already a list of strings and making a caller wrap each one buys nothing.

simple/2 folds this into every row it returns. It is public because a renderer adding a new row has a path with no clause behind it yet, and still needs its value list.

Examples

iex> StatifierUI.Expression.value_candidates(%{"step" => ["payment", "review"]}, "step")
[%{label: "payment", value: "payment"}, %{label: "review", value: "review"}]

iex> StatifierUI.Expression.value_candidates(%{}, "plan")
[]

@spec value_source(atom(), term()) :: {:ok, String.t()} | :error

The source text one clause value is written as, on its own.

source/2 covers every edit a renderer makes to a whole expression. This covers the one case it cannot: a control that has to compose a value - a free-text field that types into a quoted string, a multi-select that builds a list - needs the spellings of the pieces, and asking for them here keeps them coming from Predicator.Simple.to_source/1 rather than from a quoting rule written a second time in JavaScript.

op is the operator the value sits beside, because :in is the one operator whose right-hand side is a list.

Examples

iex> StatifierUI.Expression.value_source(:equal_equal, {:string, "pro", :single})
{:ok, "'pro'"}

iex> StatifierUI.Expression.value_source(:gte, {:integer, 500})
{:ok, "500"}

iex> StatifierUI.Expression.value_source(:in, {:list, [{:string, "payment", :single}]})
{:ok, "['payment']"}

@spec vocabulary_available?() :: boolean()

Whether the resolved predicator exposes Predicator.Vocabulary.

The component stamps this on the rendered input so a host - or a test - can tell "no grammar completions offered" from "grammar completions offered and none matched".

Examples

iex> is_boolean(StatifierUI.Expression.vocabulary_available?())
true