The component contract (spec/01): the behavior every Macaw component implements, and the dispatch functions a host reaches a component through.
defmodule MyApp.Cards do
use Macaw.Component, name: "my_app.cards", kinds: [:content]
@impl true
def declarations(_settings), do: {:ok, reading: :scan}
@impl true
def render(:content, _assigns), do: {:safe, ~s(<ul class="cards"></ul>)}
endStatic declarations are use's options (name:, kinds:, hooks:, assets:)
and parameters/0; configured declarations are declarations/1's answer, built by
Macaw.Component.Declarations.new/2. The dispatch functions answer values: a
component's bad answer is an error, never a raise. A component's own raise in render/2
or a transition is its host's process's to take (spec/02 §6).
The contract is unstable until two implementers pass its kit (spec/00 §3).
Summary
Types
A fault: the path to the value, and why.
A kind a component renders as (spec/01 §2).
A contained component's value (spec/02 §7).
Functions
A contained component's bound/3 (spec/02 §7).
A slot's row budget at a size: {:ok, nil} for a component without budget/3, else
{:ok, rows} for a positive integer or nil, and {:error, {:bad_budget, answer}}
otherwise (spec/01 §1.4).
Whether a module is loaded and uses Macaw.Component.
Whether a module exports every contained transition.
The component's configured declarations for given settings: the settings validated, then
declarations/1 called with every bindable parameter at its default (spec/01 §1.1), and
its answer built by Macaw.Component.Declarations.new/2.
A contained component's delivery/3 (spec/02 §7).
A fault as a line a person reads.
A component's static declarations, %{name, kinds, hooks, assets}, or :error for a
module that is not a component.
A contained component's init/2 (spec/02 §7).
The kinds a component may render as, in order.
The closed observation vocabulary, in order (spec/01 §1.6).
A component's parameters, each checked by Macaw.Data.Parameter.check/1, named by a
non-empty string, and, when bindable, with a default (spec/01 §1.1). Every fault at once,
its path from the parameter's name.
Given settings checked against the component's parameters, defaults filled in
(Macaw.Data.Parameter.validate/2).
A contained component's size/2 (spec/02 §7).
A contained component's four transitions, as {name, arity}.
Types
Callbacks
@callback budget(slot :: String.t(), settings :: map(), size :: {number(), number()}) :: pos_integer() | nil
@callback delivery(value(), slot :: String.t(), Macaw.Data.Delivery.t()) :: value()
@callback init(settings :: map(), Macaw.Component.Context.t()) :: value()
@callback parameters() :: %{required(String.t()) => Macaw.Data.Parameter.t()}
@callback render(kind(), assigns :: map()) :: Phoenix.HTML.Safe.t()
Functions
A contained component's bound/3 (spec/02 §7).
@spec budget(module(), String.t(), map(), {number(), number()}) :: {:ok, pos_integer() | nil} | {:error, {:bad_budget, term()}}
A slot's row budget at a size: {:ok, nil} for a component without budget/3, else
{:ok, rows} for a positive integer or nil, and {:error, {:bad_budget, answer}}
otherwise (spec/01 §1.4).
Whether a module is loaded and uses Macaw.Component.
Whether a module exports every contained transition.
@spec declarations(module(), map()) :: {:ok, Macaw.Component.Declarations.t()} | {:error, [fault(), ...]}
The component's configured declarations for given settings: the settings validated, then
declarations/1 called with every bindable parameter at its default (spec/01 §1.1), and
its answer built by Macaw.Component.Declarations.new/2.
@spec delivery(module(), value(), String.t(), Macaw.Data.Delivery.t()) :: value()
A contained component's delivery/3 (spec/02 §7).
A fault as a line a person reads.
A component's static declarations, %{name, kinds, hooks, assets}, or :error for a
module that is not a component.
@spec init(module(), map(), Macaw.Component.Context.t()) :: value()
A contained component's init/2 (spec/02 §7).
@spec kinds() :: [kind(), ...]
The kinds a component may render as, in order.
@spec observations() :: [atom(), ...]
The closed observation vocabulary, in order (spec/01 §1.6).
A component's parameters, each checked by Macaw.Data.Parameter.check/1, named by a
non-empty string, and, when bindable, with a default (spec/01 §1.1). Every fault at once,
its path from the parameter's name.
Given settings checked against the component's parameters, defaults filled in
(Macaw.Data.Parameter.validate/2).
A contained component's size/2 (spec/02 §7).
@spec transitions() :: keyword(non_neg_integer())
A contained component's four transitions, as {name, arity}.