@spec advice(String.t() | nil) :: String.t() | nil

What is worth telling an author about CSS that is valid and probably not what they meant.

nil when there is nothing to say. This never refuses anything: a nested selector is real CSS and a descendant rule is a thing people write on purpose.

The one it catches is the mistake this box invites. The pane is titled with the element — main — this element's own — so an author writes what looks like the rule for it:

main { color: red }

Wrapped, that is .pb-xxxxxxxx { main { color: red } }: a main INSIDE the element, which for a main is nothing at all. It saves, it is announced as applied, and the page does not change. The author has no way to tell that from a feature that is broken.

@spec all(map() | nil, String.t() | nil, String.t()) :: %{
  required(String.t()) => String.t()
}

Every rule this document holds, as %{scope => body}.

Read back out of the compiled row rather than kept anywhere else: the stylesheet IS the record, so a rule edited by hand on the Stylesheets page is still the rule here.

@spec css(%{required(String.t()) => String.t()}) :: String.t()

The CSS for a set of rules. Public because it is the whole contract with the compiler.

@spec declarations(String.t() | nil) :: [declaration()]

Every declaration a body applies to the element itself, in the order they were written.

Read with a scanner rather than a regular expression for the reason parse/1 is: the body nests, and a pattern that stops at the first } would read &:hover { color: red } as a top-level declaration of color. Nested selectors that are not one of @pseudo_buckets — & > .badge, a media query — are skipped entirely: they style something else, or at a width the panel cannot name.

@spec live_rules(MishkaCmsCore.Runtime.PageBuilder.Tree.t(), %{
  required(String.t()) => String.t()
}) ::
  %{required(String.t()) => String.t()}

The rules a tree still refers to. Anything else in the row belongs to an element that is gone.

@spec merge(
  %{required(String.t()) => String.t()},
  %{required(String.t()) => String.t()} | nil
) :: %{
  required(String.t()) => String.t()
}

Edits laid over the rules as they stand, a blank body clearing the rule it names.

Per element rather than as one map, and that is the whole point: the publish that folds a draft's held CSS into the row is told which elements the author touched, so everything else in the row — the four statuses they were not looking at, the rule a second editor wrote a minute ago — is left exactly as it is.

@spec parse(String.t() | nil) :: %{required(String.t()) => String.t()}

Reads a row back into %{scope => body}.

Brace-counted rather than matched with a regular expression, because a body nests — &:hover { … } and @media (…) { … } are the point of the feature — and a pattern that stops at the first } would truncate every rule that used them. Counted by the same scanner the declarations are read with, so a brace inside a string or a comment is text: content: "}" ends nothing.

@spec place(%{required(String.t()) => String.t()}, String.t() | nil, String.t() | nil) ::
  {:ok, %{required(String.t()) => String.t()}} | {:error, term()}

One element's CSS placed in a set of rules, checked but not written anywhere.

The builder's draft stage holds its rules in the editing session instead of writing them — the row is the live site — and it has to refuse exactly what put/5 refuses, or the box takes CSS in one stage that the publish then throws out.

@spec put(map() | nil, String.t() | nil, String.t(), String.t(), String.t()) ::
  {:ok, %{required(String.t()) => String.t()}} | {:error, term()}

Writes one element's CSS, or clears it when the body is blank.

Returns the whole map so a caller can hold the current state without reading again.

@spec reaching_selectors(String.t() | nil) :: [String.t()]

The nested selectors in a body that reach past the element itself — & > .badge, & .title.

On a plain tag that is ordinary CSS about the author's own markup. On a COMPONENT it is a rule aimed at markup the kit owns and the author did not write, which the next version of the kit is free to rename; the panel says so rather than refusing it, because reaching in is sometimes the only way to style something and an author who is told can decide for themselves.

A pseudo bucket is not one of these: &:hover is still this element.

@spec row_name(String.t()) :: String.t()

The reserved row a document's element CSS lives in.

@spec sync(map() | nil, String.t() | nil, String.t(), %{
  required(String.t()) => String.t()
}) ::
  {:ok, %{required(String.t()) => String.t()}} | {:error, term()}

Rewrites the row to hold exactly rules, which is what prunes a deleted element's CSS.

@spec without(String.t() | nil, non_neg_integer()) :: String.t()

The body with one declaration taken out — what Move to controls leaves behind.

index is a position in declarations/1. Out of range, the body is returned untouched, because a stale click from a panel rendered against an older body must not delete a different rule.