Types for widget fields and events.

Widget field declarations like field :name, :string or field :color, Plushie.Type.Color each name a type. The type determines what values a field accepts, how they appear in typespecs, and how they encode for the renderer.

The SDK includes types for common values; when your application needs something more specific, you can define your own by implementing the Plushie.Type behaviour.

Primitive types

Types for basic values like numbers, strings, and booleans, represented as atoms in field declarations:

• :integer - Plushie.Type.Integer
• :float - Plushie.Type.Float
• :string - Plushie.Type.String
• :boolean - Plushie.Type.Boolean
• :atom - Plushie.Type.Atom
• :any - Plushie.Type.Any
• :map - Plushie.Type.Map

Example in a field declaration:

field :label, :string
field :count, :integer, default: 0

Domain types

The SDK includes additional types beyond the primitives, referenced by module name. Some examples:

• Plushie.Type.Color - CSS colors (named atoms, hex strings, RGBA maps)
• Plushie.Type.Padding - uniform number, {v, h} tuple, or per-side map
• Plushie.Type.Font - font family, weight, style, and stretch
• Plushie.Type.Border - color, width, and radius
• Plushie.Type.A11y - accessibility annotations

Example in a field declaration:

field :color, Plushie.Type.Color
field :padding, Plushie.Type.Padding, default: 8

Composite types

When you need a list of values, a set of specific atoms, or a choice between types, you can express that directly in the field declaration:

• {:enum, [:a, :b, :c]} - one of a fixed set of atoms
• {:list, :string} - list where every element matches the inner type
• {:map, {:string, :integer}} - map with typed keys and values
• {:map, [name: :string, age: :integer]} - map with specific named fields
• {:tuple, [:float, :float]} - fixed-size tuple with typed positions
• {:union, [Plushie.Type.Color, Plushie.Type.StyleMap]} - tries each type in order, first successful cast wins

Example in a field declaration:

field :tags, {:list, :string}
field :mode, {:enum, [:read, :write]}
field :scores, {:map, {:string, :integer}}

Building your own type

If the built-in types and composite types don't quite fit, you can define your own. All custom types start with use Plushie.Type. From there, you can either compose existing types using the DSL macros, or implement callbacks directly for more control.

Composing with the DSL

The DSL macros let you build types from existing ones. All callbacks are generated automatically.

Enum for a fixed set of atom values:

defmodule MyApp.Type.Priority do
  use Plushie.Type
  enum [:low, :medium, :high, :critical]
end

Struct for grouping related fields into a single value:

defmodule MyApp.Type.Dimensions do
  use Plushie.Type

  struct do
    field :width, :float
    field :height, :float
  end
end

Union when a field accepts multiple forms (first match wins):

defmodule MyApp.Type.Size do
  use Plushie.Type

  union do
    enum [:small, :medium, :large]
    type MyApp.Type.Dimensions
  end
end

Use them in widget field declarations by module name:

field :priority, MyApp.Type.Priority, default: :medium
field :size, MyApp.Type.Size

Custom callbacks

When you need custom validation, coercion from multiple input forms, or encoding logic that the DSL can't express, you can implement the callbacks directly. You still start with use Plushie.Type.

A type needs at least cast/1 and typespec/0. Adding guard/1 enables pattern matching in generated setters, and encode/1 handles cases where the wire representation differs from the Elixir value:

defmodule MyApp.Type.Percentage do
  use Plushie.Type

  # Accept integers 0..100 or floats 0.0..1.0, normalize to float
  @impl Plushie.Type
  def cast(v) when is_integer(v) and v >= 0 and v <= 100, do: {:ok, v / 100}
  def cast(v) when is_float(v) and v >= 0.0 and v <= 1.0, do: {:ok, v}
  def cast(_), do: :error

  @impl Plushie.Type
  def typespec, do: quote(do: float())

  @impl Plushie.Type
  def guard(var), do: quote(do: is_float(unquote(var)))

  # encode/1 not needed: floats are already wire-safe
end

You can also delegate to other types within your callbacks. This is useful when your type wraps or combines existing types with custom logic:

def cast(%{fg: fg, bg: bg}) do
  with {:ok, fg} <- Plushie.Type.Color.cast(fg),
       {:ok, bg} <- Plushie.Type.Color.cast(bg) do
    {:ok, %{fg: fg, bg: bg}}
  else
    _ -> :error
  end
end

Plushie.Type.Integer serves as a minimal reference. Plushie.Type.Color shows how to handle many input forms.

Callbacks

Required:

• cast/1 - validates input, returns {:ok, normalized} or :error. Defines what values are accepted and what canonical form they take.
• typespec/0 - returns a quoted typespec (e.g. quote(do: float())). Used in generated @type and @spec attributes.

Optional:

• castable/0 - returns a quoted typespec for the values cast/1 accepts. Default: same as typespec/0. Implement when the input forms are broader than the canonical type (e.g., Color accepts atoms, strings, and maps but stores a hex string).
• decode/1 - decodes a wire-format value (JSON-decoded strings, numbers, maps with string keys) into the canonical type. Default: delegates to cast/1. Implement when wire and Elixir representations differ (e.g., enums receive strings but store atoms).
• encode/1 - converts to wire-safe form (atoms to strings, structs to maps). Only needed when the Elixir value isn't directly serializable.
• guard/1 - returns a quoted guard expression. Enables pattern matching in generated setter functions.
• fields/0 - for struct types, returns [{name, type}, ...].
• field_options/0 - declares constraint keys (e.g. [:min, :max]). Validated at compile time.
• constrain_guard/2 - generates guards from field constraints (e.g. range checks from :min/:max options).
• merge/2 - controls how a field default combines with a user override. Default: full replacement. Implement for struct types where partial updates should preserve unset fields.
• resolve/2 - derives the final value from sibling widget props at render time. Default: identity. Implement when your type needs to read other props to compute its value.