The list or map an attribute is holding, read out of a document and written back into one.
Why this is not a text box
chelekom-filterable-gallery keeps its whole content in two list attributes — the filter
buttons and the pictures behind them — and thirty-nine attributes across the shipped kit are
shaped the same way. The panel drew a one-line box for every one of them and wrote what was typed
as a STRING, so a component that maps over its own attribute raised the moment anything was
entered. The report reads "we cannot add any image and it's not clear how it works".
So the panel needs a control that knows it is holding a collection, and that control needs to read the list, change one item, and write the whole thing back as one edit. That is this module.
What counts as readable
MishkaCmsCore.Builder.Literal decides, and it decides by walking the quoted form rather than
evaluating it: a list of strings, a list of maps, a keyword list. Anything else — a binding, a
function call, an interpolation — answers :error, and a caller holding :error must leave the
attribute alone rather than overwrite what it could not read. An author who has written
media={@photos} means it.
And what is written back
inspect/1, which is the exact shape the editor can read again. One set_attr per change, so one
undo step per add, per removal and per edit.
Summary
Functions
What an empty row of this collection looks like, read off the ones already there.
Whether an item is one side of a map or a keyword list rather than a value on its own.
One item changed, added or dropped, and the whole collection back.
One field of one item changed. The key is the field's name, as an atom or as the text the browser sent: a name the item has no field for leaves the collection as it was, and no atom is made of it.
One side of a pair changed, the other left as it was.
The collection an attribute holds on this node, or the declared default when it holds nothing.
The source text for a collection, ready to be written as an expression attribute.
Functions
What an empty row of this collection looks like, read off the ones already there.
A list of maps gets a map with the same keys blank, so the new card carries the same fields as its
neighbours; a list of anything else gets an empty string. An empty list has nothing to read, and
the caller's own sample is the answer — MishkaCmsCore.Runtime.PageBuilder.Starter has one for
the shapes it knows.
Whether an item is one side of a map or a keyword list rather than a value on its own.
A map attribute is read out as its pairs — chelekom-flash holds %{"info" => "…"} and
chelekom-pagination a map of query parameters — and a pair is edited as a pair, one field for
each side.
@spec put(list(), non_neg_integer(), term()) :: list()
One item changed, added or dropped, and the whole collection back.
Out-of-range indexes are left alone rather than raising: the panel and the document can disagree for one render after an undo, and a stale click must not take the editor down.
One field of one item changed. The key is the field's name, as an atom or as the text the browser sent: a name the item has no field for leaves the collection as it was, and no atom is made of it.
@spec put_side(list(), non_neg_integer(), :key | :value, term()) :: list()
One side of a pair changed, the other left as it was.
@spec read( MishkaCmsCore.Runtime.PageBuilder.Tree.Node.t() | term(), String.t(), term() ) :: {:ok, list()} | :error
The collection an attribute holds on this node, or the declared default when it holds nothing.
:error when the attribute is there and is not data — a binding rather than a list.
@spec remove(list(), non_neg_integer()) :: list()
The source text for a collection, ready to be written as an expression attribute.