@spec add([StatifierBlocks.Document.DatamodelEntry.t()]) :: [
  StatifierBlocks.Document.DatamodelEntry.t()
]

Appends a freshly named entry: root_1, or the first root_N no entry already holds.

expr and description are nil, which is the absent spelling ADR-0001 11b gives both and the one 11d omits from the canonical bytes. The new root therefore reads as undefined until something assigns it, which is what an author who has just named a root has said about it.

iex> StatifierBlocks.Declarations.add([])
[%StatifierBlocks.Document.DatamodelEntry{id: "root_1", expr: nil, description: nil}]

iex> entry = %StatifierBlocks.Document.DatamodelEntry{id: "root_1"}
iex> [_kept, minted] = StatifierBlocks.Declarations.add([entry])
iex> minted.id
"root_2"

@spec change([StatifierBlocks.Document.DatamodelEntry.t()], term(), map()) :: [
  StatifierBlocks.Document.DatamodelEntry.t()
]

The entry list a phx-change payload asks for: every field the form carries, written onto the entry at index.

Keys the form did not send are left alone, so a panel that grows a field later does not silently blank the ones beside it, and a key outside 11b's three is ignored rather than written - the payload is untrusted input and this is the only place it becomes an entry.

The id field arrives under the name "name". That is not a rename of 11b's field, which is still id on the struct and in the bytes; it is the one spelling LiveView leaves alone. An <input name="id"> inside a form overrides the form element's own DOM id, which LiveView refuses at compile time, so the wire name and the struct key differ here and this table is where they are reconciled.

iex> entries = [%StatifierBlocks.Document.DatamodelEntry{id: "a"}]
iex> params = %{"name" => "signup", "description" => "the wizard", "nope" => "x"}
iex> [entry] = StatifierBlocks.Declarations.change(entries, 0, params)
iex> {entry.id, entry.description}
{"signup", "the wizard"}

@spec count(term()) :: non_neg_integer()

How many declarations the document carries - the drawer strip's count for the Declarations tab.

iex> StatifierBlocks.Declarations.count([%StatifierBlocks.Document.DatamodelEntry{id: "a"}])
1
iex> StatifierBlocks.Declarations.count(nil)
0

@spec move([StatifierBlocks.Document.DatamodelEntry.t()], term(), term()) :: [
  StatifierBlocks.Document.DatamodelEntry.t()
]

Swaps the entry at index with its neighbour in direction.

Order is the emission order of the document's <data> elements (ADR-0001 11a), so this is an authoring act with a visible meaning in the compiled chart rather than a display preference - which is why it is a document edit and not editor state.

A move off either end is a no-op, so the first row's "up" and the last row's "down" are inert rather than wrapping. Wrapping would make one press of a repeated gesture do the opposite of the press before it.

iex> a = %StatifierBlocks.Document.DatamodelEntry{id: "a"}
iex> b = %StatifierBlocks.Document.DatamodelEntry{id: "b"}
iex> StatifierBlocks.Declarations.move([a, b], 1, :up) |> Enum.map(& &1.id)
["b", "a"]
iex> StatifierBlocks.Declarations.move([a, b], 0, :up) |> Enum.map(& &1.id)
["a", "b"]

@spec put([StatifierBlocks.Document.DatamodelEntry.t()], term(), field(), term()) :: [
  StatifierBlocks.Document.DatamodelEntry.t()
]

Writes one field of the entry at index.

expr and description are optional in ADR-0001 11b and absent is spelled nil on the struct, so a cleared text input - the empty string a browser sends for a field the author emptied - becomes nil here rather than "". The alternative is a value 11b refuses and 11d would never encode, reached by the ordinary act of clearing a box.

id is written through verbatim, blank included. It is required, so there is nothing for a blank to mean, and the refusal the command answers with is the panel's message to the author (2l) rather than something to paper over here.

iex> entries = [%StatifierBlocks.Document.DatamodelEntry{id: "a", expr: "1"}]
iex> StatifierBlocks.Declarations.put(entries, 0, :expr, "") |> hd() |> Map.get(:expr)
nil
iex> StatifierBlocks.Declarations.put(entries, 0, :id, "signup") |> hd() |> Map.get(:id)
"signup"

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

A refusal from {:set_datamodel, entries}, as one sentence for the panel.

ADR-0005 decision 11's anchors name a block, a slot or a config key, and none of them can name a declaration entry, so a refusal here is not a %StatifierBlocks.Finding{} and does not enter the findings pipeline (2l). It is rendered in the panel that produced it, which is the only place it is about.

Anything this function does not recognize gets the generic sentence rather than an inspected tuple: the panel is read by an author, and a term it cannot phrase is a term the author cannot act on either.

iex> StatifierBlocks.Declarations.refusal(
...>   {:malformed_envelope, {:datamodel, {:duplicate_id, "signup"}}}
...> )
~s(Two declarations are named "signup". Every id must be unique.)

iex> StatifierBlocks.Declarations.refusal(:something_else)
"That change was refused."

@spec remove([StatifierBlocks.Document.DatamodelEntry.t()], term()) :: [
  StatifierBlocks.Document.DatamodelEntry.t()
]

Drops the entry at index, or returns entries unchanged when no entry sits there.

iex> entries = [%StatifierBlocks.Document.DatamodelEntry{id: "signup"}]
iex> StatifierBlocks.Declarations.remove(entries, 0)
[]
iex> StatifierBlocks.Declarations.remove(entries, 4) == entries
true