# `ElementorexCms.Block.Prop`
[🔗](https://github.com/rocket4ce/elementorex_cms/blob/v0.1.0/lib/elementorex_cms/block/prop.ex#L1)

A property of a block: its type, default, label and editor control.

Props are declared with `ElementorexCms.Block.prop/3`. The type decides how a
value is cast and sanitized when it reaches the document (from the editor or
from stored JSON) and which control the inspector shows:

| Type        | Value                                   | Control                    |
| ----------- | --------------------------------------- | -------------------------- |
| `:string`   | one line of text                        | text input                 |
| `:text`     | multi-line plain text                   | textarea                   |
| `:richtext` | sanitized HTML (`:rich` policy)         | inline editing + textarea  |
| `:html`     | sanitized HTML (`:html` policy)         | code editor                |
| `:select`   | one of `:options`                       | select, segmented, swatches|
| `:boolean`  | `true` / `false`                        | toggle                     |
| `:integer`  | integer within `:min`..`:max`           | number or range            |
| `:number`   | number within `:min`..`:max`            | number or range            |
| `:url`      | sanitized link URL                      | URL input                  |
| `:image`    | sanitized image URL                     | image picker / upload      |
| `:icon`     | Heroicons name                          | icon picker                |
| `:color`    | CSS color or theme variable             | swatches + color input     |
| `:datetime` | `"2026-12-31T23:59"`                     | date and time input        |
| `:list`     | list of items, each with its `:fields`  | repeater                   |

## Options

  * `:default` - value for new blocks and for missing or invalid values
  * `:label`, `:help`, `:placeholder` - texts of the control (translated with
    `ElementorexCms.I18n`)
  * `:group` - heading of the inspector section the control goes in
  * `:control` - overrides the default control (`:textarea`, `:segmented`,
    `:swatches`, `:range`, `:code`...)
  * `:options` - for `:select`: `[{"Label", "value"}]` or a list of values
  * `:min`, `:max`, `:step`, `:unit` - for numbers
  * `:max_length` - for text types
  * `:policy` - for `:richtext`: `:rich` (default) or `:inline` (only
    formatting inside a line, see `ElementorexCms.HTML.Sanitizer`)
  * `:inline` - the prop can be edited by typing on the canvas
  * `:show_if` - only show the control when another prop matches:
    `{:icon, :present}`, `{:variant, "outline"}` or `{:size, ["lg", "xl"]}`
  * `:fields`, `:item_label`, `:max_items` - for `:list` (`fields` takes
    `{name, type, opts}` tuples)

# `t`

```elixir
@type t() :: %ElementorexCms.Block.Prop{
  control: term(),
  default: term(),
  fields: term(),
  group: term(),
  help: term(),
  inline: term(),
  item_label: term(),
  key: term(),
  label: term(),
  max: term(),
  max_items: term(),
  max_length: term(),
  min: term(),
  name: term(),
  options: term(),
  placeholder: term(),
  policy: term(),
  show_if: term(),
  step: term(),
  type: term(),
  unit: term()
}
```

# `cast`

```elixir
@spec cast(t(), term()) :: term()
```

Casts and sanitizes a value. Invalid values fall back to the default (or to an
empty value when the default would be misleading, like an unsafe URL).

# `default`

```elixir
@spec default(t()) :: term()
```

The default value, with fresh ids for the items of a `:list` (every item
carries an `"id"` so the editor can reorder it).

# `localized_default`

```elixir
@spec localized_default(t()) :: term()
```

The default value with its texts translated to the current locale (see
`ElementorexCms.I18n`): plain and rich text props, and the text fields of
list items. Other values are returned as they are.

# `new`

```elixir
@spec new(atom(), atom(), keyword()) :: t()
```

Builds a prop. Raises `ArgumentError` on an unknown type.

# `new_item`

```elixir
@spec new_item(t()) :: map()
```

A blank item for a `:list` prop, with the defaults of its fields (translated).

# `types`

```elixir
@spec types() :: [atom()]
```

Types a prop can have.

# `values`

```elixir
@spec values(t()) :: [String.t()]
```

Values allowed by a `:select` prop.

# `visible?`

```elixir
@spec visible?(t(), map()) :: boolean()
```

Whether the control of `prop` should be shown given the other values, per
its `:show_if` option.

---

*Consult [api-reference.md](api-reference.md) for complete listing*