# Custom Types

Plushie's type system validates, coerces, and encodes widget field
values. Types generate guards for setter function heads, typespecs
for documentation, and cast functions for runtime validation. Every
widget field declaration references a type, either a primitive
shortcut or a module implementing `Plushie.Type`.

For the behaviour API and macro details, see `Plushie.Type`.

## Built-in types

### Primitive shortcuts

| Shortcut | Module | Guard | Accepts |
|----------|--------|-------|---------|
| `:integer` | `Plushie.Type.Integer` | `is_integer(v)` | Integers only |
| `:float` | `Plushie.Type.Float` | `is_number(v)` | Integers and floats (GUI-friendly) |
| `:string` | `Plushie.Type.String` | `is_binary(v) or is_atom(v)` | Strings and atoms (coerced to string) |
| `:boolean` | `Plushie.Type.Boolean` | `is_boolean(v)` | `true` or `false` |
| `:atom` | `Plushie.Type.Atom` | `is_atom(v)` | Any atom |
| `:any` | `Plushie.Type.Any` | (none) | Any term |
| `:map` | `Plushie.Type.Map` | `is_map(v)` | Any map |

`:float` accepts integers at the API boundary because GUI dimensions
like `size: 14` should work without requiring `14.0`. The guard is
`is_number` and the value is stored as-is.

`:string` accepts atoms and coerces them to strings via
`Atom.to_string/1`. This is common for enum-like string props
(cursor names, mode strings) where atoms are more ergonomic.

### Domain types

These are full modules referenced by name in field declarations:

| Module | Purpose |
|--------|---------|
| `Plushie.Type.Color` | CSS named colors, hex strings, RGB maps |
| `Plushie.Type.Length` | `:fill`, `:shrink`, `{:fill_portion, n}`, or numeric |
| `Plushie.Type.Font` | `:default`, `:monospace`, string, or Font struct |
| `Plushie.Type.Padding` | Uniform number, `{v, h}` tuple, or per-side map |
| `Plushie.Type.Style` | Preset atoms (`:primary`, etc.) or `StyleMap` struct |
| `Plushie.Type.Range` | `{min, max}` numeric tuple |
| `Plushie.Type.Border` | Border struct (color, width, radius) |
| `Plushie.Type.Shadow` | Shadow struct (color, offset, blur) |
| `Plushie.Type.A11y` | Accessibility annotations (role, label, etc.) |
| `Plushie.Type.Alignment` | `:left`, `:center`, `:right`, `:top`, `:bottom` |
| `Plushie.Type.LineHeight` | Relative multiplier, `%{relative: n}`, or `%{absolute: n}` |
| `Plushie.Type.Shaping` | `:basic`, `:advanced`, `:auto` |
| `Plushie.Type.Wrapping` | `:none`, `:word`, `:glyph`, `:word_or_glyph` |

## The Plushie.Type behaviour

### Required callbacks

| Callback | Signature | Purpose |
|----------|-----------|---------|
| `cast/1` | `term() -> {:ok, term()} \| :error` | Validate and coerce input to canonical form |
| `typespec/0` | `-> Macro.t()` | Quoted typespec for `@type` and `@spec` generation |

### Optional callbacks

| Callback | Signature | Purpose |
|----------|-----------|---------|
| `castable/0` | `-> Macro.t()` | Quoted typespec for values `cast/1` accepts (defaults to `typespec/0`) |
| `constrain_guard/2` | `(Macro.t(), keyword()) -> [Macro.t()]` | Additional guard clauses from field constraints |
| `decode/1` | `term() -> {:ok, term()} \| :error` | Wire decoding (JSON values to canonical form, defaults to `cast/1`) |
| `encode/1` | `term() -> term()` | Wire encoding (Elixir value to JSON-safe value) |
| `field_options/0` | `-> [atom()]` | Valid constraint names for this type |
| `fields/0` | `-> [{atom(), term()}] \| nil` | Sub-field definitions for DSL block support |
| `guard/1` | `Macro.t() -> Macro.t() \| nil` | Quoted guard clause for setter function heads |
| `merge/2` | `(term(), term()) -> term()` | Merge default with override (defaults to replacement) |
| `resolve/2` | `(term(), map()) -> term()` | Derive value from sibling widget props (defaults to identity) |

## How types are used

When you declare `field :size, :float, min: 0`, the widget macro
resolves `:float` to `Plushie.Type.Float` at compile time and:

1. **Typespec**: calls `Float.typespec()` to generate the field's
   `@type` entry
2. **Castable**: calls `Float.castable()` to generate the setter's
   `@spec` (what the setter accepts as input)
3. **Guard**: calls `Float.guard(var)` to generate the setter's
   `when is_number(value)` clause
4. **Constraints**: calls `Float.constrain_guard(var, [min: 0])` to
   add `and value >= 0` to the guard
5. **Cast**: calls `Float.cast(value)` in the setter body to
   validate and coerce user input
6. **Encode**: calls `Float.encode(value)` during tree normalization
   to produce the wire-safe representation sent to the renderer
7. **Decode**: calls `Float.decode(value)` when event data arrives
   from the renderer, coercing wire-format values back to Elixir
8. **Doc generation**: uses the typespec string in the auto-generated
   Props table in the widget's `@moduledoc`

If cast returns `:error`, the setter raises `ArgumentError` with the
field name and the invalid value.

## Declaring custom types

There are four ways to declare a type: enum, struct, union, and
manual implementation. The first three use the `use Plushie.Type`
macro which generates callbacks from declarations. Manual
implementation gives full control.

### Enum types

For types with a fixed set of atom values:

```elixir
defmodule MyApp.Type.Priority do
  use Plushie.Type

  enum [:low, :medium, :high, :critical]
end
```

The macro generates:
- `cast/1`: returns `{:ok, value}` if the atom is in the list,
  `:error` otherwise
- `guard/1`: `value in [:low, :medium, :high, :critical]`
- `typespec/0`: `:low | :medium | :high | :critical`
- `encode/1`: `Atom.to_string(value)`

Use it in a widget. The `:doc` option provides the description that
appears in the auto-generated Props table and the setter's `@doc`:

```elixir
widget :task_card do
  field :priority, MyApp.Type.Priority, doc: "Task priority level."
end
```

See [Custom Widgets: Field options](custom-widgets.md#field-options)
for all available field options (`:doc`, `:default`, `:wire_name`,
`:cast`, etc.) and
[reserved field names](custom-widgets.md#reserved-field-names).

The setter accepts only the declared atoms:

```elixir
TaskCard.priority(card, :high)      # OK
TaskCard.priority(card, :unknown)   # raises ArgumentError
```

### Struct types

For types with multiple named fields, wrap field declarations in
a `struct do ... end` block:

```elixir
defmodule MyApp.Type.Margin do
  use Plushie.Type

  struct do
    field :top, :float
    field :right, :float
    field :bottom, :float
    field :left, :float
  end
end
```

The macro generates a struct and:
- `cast/1`: accepts a map or keyword list, validates each field
  through its type, returns `{:ok, %Margin{...}}`
- `encode/1`: converts struct to plain map (strips `__struct__`
  and nil fields, encodes values recursively)
- `fields/0`: `[top: :float, right: :float, ...]` for DSL block
  resolution
- `typespec/0`: `%MyApp.Type.Margin{}`
- `guard/1`: `is_struct(value, MyApp.Type.Margin)`

Struct types support the DSL block form:

```elixir
container "panel" do
  margin do
    top 10
    bottom 20
  end
end
```

### Union types

For types that accept multiple forms. Order matters: cast tries
each variant top-to-bottom and returns the first success.

```elixir
defmodule MyApp.Type.Background do
  use Plushie.Type

  union do
    enum [:transparent, :inherit]
    type Plushie.Type.Color
    type Plushie.Type.Gradient
  end
end
```

Given `Background.cast(:transparent)`:
1. Tries enum cast: `:transparent` is in the list, returns
   `{:ok, :transparent}`

Given `Background.cast("#ff0000")`:
1. Tries enum cast: `"#ff0000"` is not an atom in the list, fails
2. Tries Color.cast: valid hex string, returns `{:ok, "#ff0000"}`

Given `Background.cast(42)`:
1. Tries enum: fails
2. Tries Color: fails
3. Tries Gradient: fails
4. Returns `:error`

The guard is the OR of each variant's guard. The typespec is the
union of each variant's typespec.

**Overlapping types**: if `:transparent` is both a valid enum atom
AND a valid Color name, the enum match wins because it's listed
first. Place more specific types before more general ones.

### Manual types

For types with complex validation logic, implement the callbacks
directly. You still start with `use Plushie.Type`:

```elixir
defmodule MyApp.Type.HexColor do
  use Plushie.Type

  @impl Plushie.Type
  def cast("#" <> hex = value) when byte_size(hex) in [6, 8] do
    if String.match?(hex, ~r/^[0-9a-fA-F]+$/) do
      {:ok, String.downcase(value)}
    else
      :error
    end
  end
  def cast(_), do: :error

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

  @impl Plushie.Type
  def guard(var), do: quote(do: is_binary(unquote(var)))
end
```

## Writing cast/1

`cast/1` is the heart of a type module. It defines what values are
accepted and how they're normalized.

### Contract

- Return `{:ok, canonical_value}` on valid input
- Return `:error` on invalid input
- Never raise (the framework converts `:error` to `ArgumentError`
  with context)
- Be idempotent: `cast(value) |> elem(1) |> cast()` must succeed

### Multiple input forms

Types often accept several input representations and normalize to a
canonical form. `Plushie.Type.Color` is a good example:

```elixir
defmodule Plushie.Type.Color do
  use Plushie.Type

  # Named atoms: :red, :blue, :cornflowerblue, ...
  def cast(name) when is_atom(name) do
    case Map.fetch(@named_colors, name) do
      {:ok, hex} -> {:ok, hex}
      :error -> :error
    end
  end

  # Hex strings: "#ff0000", "#ff000080"
  def cast("#" <> _ = hex), do: {:ok, String.downcase(hex)}

  # RGB maps: %{r: 255, g: 0, b: 0}
  def cast(%{r: r, g: g, b: b}) when is_integer(r) and is_integer(g) and is_integer(b) do
    {:ok, "#" <> hex(r) <> hex(g) <> hex(b)}
  end

  def cast(_), do: :error
end
```

All three forms normalize to a canonical hex string. The setter
accepts any of them:

```elixir
Button.background(btn, :red)           # OK, stored as "#ff0000"
Button.background(btn, "#FF0000")      # OK, stored as "#ff0000"
Button.background(btn, %{r: 255, g: 0, b: 0})  # OK, stored as "#ff0000"
Button.background(btn, 42)             # raises ArgumentError
```

### Delegating to other types

Types can compose internally by calling other types' `cast/1`:

```elixir
defmodule MyApp.Type.ColorPair do
  use Plushie.Type

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

## Writing guard/1

Guards run in setter function heads before cast. They reject
obviously wrong types at pattern match time (faster than calling
cast). Guards must use only guard-safe expressions (BIF calls like
`is_binary`, `is_number`, comparisons, boolean operators).

```elixir
@impl Plushie.Type
def guard(var) do
  quote(do: is_binary(unquote(var)) or is_atom(unquote(var)))
end
```

The `var` argument is a quoted variable reference. Return `nil` to
skip guard generation entirely (the setter accepts all values and
relies on cast for validation). This is appropriate when the type
accepts too many input forms to express in a guard.

**Note**: the guard protects the setter's main clause. A separate
nil clause (for optional fields) is generated automatically. Don't
include nil checking in your guard.

## Writing typespec/0

Return a quoted Elixir typespec AST. This appears in the widget's
`@type t` definition and setter `@spec`:

```elixir
# Simple: a known Elixir type
def typespec, do: quote(do: String.t())

# Union: multiple forms
def typespec, do: quote(do: atom() | String.t() | map())

# Module struct reference
def typespec, do: quote(do: %MyApp.Type.Margin{})
```

The typespec should describe the INPUT forms the type accepts (what
users write in code), not the internal canonical form (what cast
produces). This gives accurate `@spec` annotations on setters.

## Writing encode/1

`encode/1` converts the canonical Elixir value to a JSON-safe wire
representation. Called during tree normalization for every non-nil
prop value.

```elixir
@impl Plushie.Type
def encode(%__MODULE__{top: t, right: r, bottom: b, left: l}) do
  %{top: t, right: r, bottom: b, left: l}
end
```

**When to implement encode/1**:
- Your type stores structs (need to convert to plain maps)
- Your type stores atoms (need to convert to strings)
- Your type stores tuples (need to convert to lists)

**When to skip encode/1** (the default handles it):
- Your type stores strings, numbers, or booleans (already JSON-safe)
- Your type stores plain maps (recursively encoded by the framework)

The framework's default encoding (`Plushie.Type.encode_value/1`)
handles common cases: atoms become strings, tuples become lists,
maps are recursively encoded, structs delegate to their module's
`encode/1` if available.

For types with nested sub-values, call `Plushie.Type.encode_value/1`
on them:

```elixir
def encode(%__MODULE__{items: items, label: label}) do
  %{
    items: Enum.map(items, &Plushie.Type.encode_value/1),
    label: label
  }
end
```

## Composite types

Types can be composed inline in field declarations without a
dedicated module:

```elixir
widget :chart do
  field :data_points, {:list, MyApp.Type.DataPoint}
  field :range, {:tuple, [:float, :float]}
  field :mode, {:enum, [:line, :bar, :scatter]}
  field :scores, {:map, {:string, :integer}}
  field :dimensions, {:map, [width: :float, height: :float]}
  field :background, {:union, [Plushie.Type.Color, Plushie.Type.Gradient]}
end
```

### How composite validation works

| Constructor | Guard | Cast |
|-------------|-------|------|
| `{:enum, [atoms]}` | `v in [atoms]` | Checks membership. |
| `{:list, inner}` | `is_list(v)` | Maps `inner.cast/1` over each element. All must succeed. |
| `{:map, {K, V}}` | `is_map(v) or is_list(v)` | Casts every key through K and every value through V. |
| `{:map, [name: type]}` | `is_map(v) or is_list(v)` | Casts each named field through its type. Accepts maps and keyword lists. Missing fields become nil. |
| `{:tuple, [types]}` | `is_tuple(v) and tuple_size(v) == N` | Validates each position through its type. All must succeed. |
| `{:union, [types]}` | (none) | Tries each type's cast in order. First `{:ok, _}` wins. |

If any element fails to cast in a list or tuple, the entire setter
raises `ArgumentError`.

### Nested composites

Composites nest naturally:

```elixir
# List of coordinate tuples
field :path, {:list, {:tuple, [:float, :float]}}

# List of enum values
field :selected_tags, {:list, {:enum, [:bug, :feature, :docs]}}
```

The setter validates the outer list, then validates each element
through the inner composite.

### When to use a module vs inline composite

Use inline composites when the type is simple and used in one place:

```elixir
field :mode, {:enum, [:line, :bar, :scatter]}
```

Use a module when:
- The type has complex cast logic (multiple input forms)
- The type is reused across multiple widgets
- The type needs custom encoding
- The type has constraints (field_options/constrain_guard)

## Field constraints

Numeric and string types can declare constraint support. The widget
macro validates constraints at compile time and extends the setter
guard:

```elixir
field :opacity, :float, min: 0.0, max: 1.0
field :name, :string, min_length: 1
field :count, :integer, min: 0, max: 999
```

| Type | Constraints | Guard extension |
|------|-------------|----------------|
| `:integer` | `min`, `max` | `value >= min and value <= max` |
| `:float` | `min`, `max` | `value >= min and value <= max` |
| `:string` | `min_length`, `max_length` | `byte_size(value) >= n` |

### Custom constraints

Define your own constraints by implementing `field_options/0` and
`constrain_guard/2`:

```elixir
defmodule MyApp.Type.Port do
  use Plushie.Type

  @impl Plushie.Type
  def cast(v) when is_integer(v) and v > 0 and v <= 65535, do: {:ok, v}
  def cast(_), do: :error

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

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

  @impl Plushie.Type
  def field_options, do: [:exclude_reserved]

  @impl Plushie.Type
  def constrain_guard(var, opts) do
    if opts[:exclude_reserved] do
      [quote(do: unquote(var) > 1024)]
    else
      []
    end
  end
end
```

Usage:

```elixir
field :port, MyApp.Type.Port, exclude_reserved: true
```

The macro checks at compile time that `exclude_reserved` is in the
type's `field_options()` list. Unknown constraints raise a compile
error.

## Types in event declarations

The same types work in event field declarations:

```elixir
event :color_changed do
  field :hue, :float
  field :saturation, :float
end

event :item_selected, value: MyApp.Type.Priority
```

Event fields are decoded at the wire boundary when events arrive
from the renderer, using `Plushie.Type.decode_field/2`. This calls
the type's `decode/1` callback, which handles wire-format coercion
(e.g., converting JSON strings to atoms for enum types). Invalid
values are dropped with a protocol error.

## Nil handling

Types never receive `nil`. The framework handles nil before calling
cast:

- `required: true` fields (default for positional args): nil at
  construction time raises `ArgumentError`
- Optional fields: nil in a setter stores nil (unsets the field)
- Nil fields are skipped during wire encoding (renderer uses its
  default)

Your `cast/1` does not need a `cast(nil)` clause.

## Module organization

Place type modules under a `Type` namespace in your application:

```
lib/
  my_app/
    type/
      priority.ex       # MyApp.Type.Priority
      color_pair.ex     # MyApp.Type.ColorPair
      margin.ex         # MyApp.Type.Margin
```

Type modules are discovered by the widget macro at compile time via
`Code.ensure_compiled/1`. They must be compilable before the widget
module that references them.

## Testing

### Cast validation

Test your type's `cast/1` with valid inputs, invalid inputs, and
edge cases:

```elixir
describe "Priority" do
  test "accepts valid values" do
    assert {:ok, :high} = MyApp.Type.Priority.cast(:high)
    assert {:ok, :low} = MyApp.Type.Priority.cast(:low)
  end

  test "rejects invalid values" do
    assert :error = MyApp.Type.Priority.cast(:invalid)
    assert :error = MyApp.Type.Priority.cast("high")
    assert :error = MyApp.Type.Priority.cast(nil)
  end

  test "is idempotent" do
    {:ok, value} = MyApp.Type.Priority.cast(:high)
    assert {:ok, ^value} = MyApp.Type.Priority.cast(value)
  end
end
```

### Multi-form cast

For types accepting multiple input forms, test each form and verify
they produce the same canonical output:

```elixir
test "all color forms normalize to hex" do
  {:ok, from_atom} = Color.cast(:red)
  {:ok, from_hex} = Color.cast("#ff0000")
  {:ok, from_map} = Color.cast(%{r: 255, g: 0, b: 0})

  assert from_atom == from_hex
  assert from_hex == from_map
  assert from_atom == "#ff0000"
end
```

### Encode round-trip

Verify encoded output is JSON-safe and preserves information:

```elixir
test "encode produces JSON-safe output" do
  {:ok, value} = MyApp.Type.Margin.cast(%{top: 10, bottom: 20})
  encoded = MyApp.Type.Margin.encode(value)

  assert is_map(encoded)
  assert {:ok, _} = Jason.encode(encoded)
  assert encoded.top == 10
  assert encoded.bottom == 20
end
```

### Widget integration

Test that widgets using your type validate correctly:

```elixir
test "setter accepts valid values" do
  card = TaskCard.new("t1") |> TaskCard.priority(:high)
  assert card.priority == :high
end

test "setter rejects invalid values" do
  assert_raise ArgumentError, fn ->
    TaskCard.new("t1") |> TaskCard.priority(:invalid)
  end
end
```

## See also

- `Plushie.Type` - behaviour definition and `use Plushie.Type` macro
- [Custom Widgets reference](custom-widgets.md) - using types in widget
  field declarations
- [Built-in Widgets reference](built-in-widgets.md) - type usage in
  built-in widget props
