What an element can be made to do when it is clicked — one declared thing, so a package can add one.

The contract

An action is a descriptor in the builder:interactions registry (ADR-14, see MishkaCmsCore.Builder.Events) whose run names a module implementing this behaviour. Core seeds seven; a plugin appends its own the way it appends an audit check:

use MishkaInstaller.Event.Hook, event: "builder:interactions", initial: %{priority: 50}

def call(%{actions: actions} = payload) do
  {:reply, %{payload | actions: actions ++ [MyPkg.Actions.Toast.descriptor()]}}
end

The descriptor is a plain map because it travels through a hook payload, and run is a module rather than a closure for the same reason — the rule MishkaCmsCore.Builder.Descriptor already keeps for every other registry.

Client or server, and nothing in between

An action says where it runs, and the two are not alike:

• :client writes a Phoenix.LiveView.JS command. It runs in the browser with no round trip and survives patches because it is part of what the server rendered. Six of core's seven are this, and anything that only moves classes or visibility around belongs here.
• :server writes JS.push/2 and names a handler. Use it only when something the server owns has to change — a flash lives on the socket, so "Show a message" has no client-side answer.

A server action also names the module the compiled page calls, as {module, function}. That module must be runtime code: it is named inside every published page that uses the action, and a visitor's page has no business naming anything under MishkaCmsCore.Builder.* or MishkaCmsCore.Runtime.PageBuilder.*. Core's own points at MishkaCmsCore.Runtime.PageMessage.

What the panel draws

needs/1 returns the boxes this action wants, and the Inspector renders them. A package never touches panel code and never ships markup for a form: it says it wants a line of text called message and gets a labelled input, remembered and read back.

Both directions are terms

write/3 answers a MishkaCmsCore.Builder.Command.t/0 — the command's name, its arguments and its options — and read/2 is handed one back. Neither side spells Elixir. What is written is escaped and printed by the code formatter, and what is read was parsed and unwrapped, so a class name containing a double quote is a class name containing a double quote in both directions and there is no place for a quoting mistake to live.

It is also what makes an option free: Phoenix.LiveView.JS validates the keys of whatever it is given, so transition:, time:, display: and blocking: work on the commands that take them without core holding a list of which those are.

Reading it back

read/2 is what lets the panel re-open an action the author already saved, with its boxes filled. The default answers :no, which is honest rather than clever: the panel then shows the expression as hand-written and refuses to rewrite something it does not understand. Implement it — a function head is usually enough — if you want yours to round-trip.

A whole action

defmodule MyPkg.Actions.Scroll do
  use MishkaCmsCore.Builder.Action

  alias MishkaCmsCore.Builder.Action

  def descriptor,
    do: action(key: "scroll", label: "Scroll to it", priority: 60)

  @impl true
  def needs(_action), do: [text("offset", "Offset", placeholder: "80")]

  @impl true
  def write(_action, context, values),
    do: {:dispatch, ["scroll-to"], [to: Action.aim(context), detail: values]}

  @impl true
  def read(_action, {:dispatch, ["scroll-to"], opts}), do: {:ok, opts[:detail]}
  def read(_action, _other), do: :no
end