Aurora.Uix.Field (Aurora UIX v0.1.4-rc.5)

A module representing a configurable field in the Aurora.Uix system.

This module defines a struct to represent field properties for UI components, such as:

key (atom) - The field reference in the schema.
name (binary) - The key's name as a binary.
type (atom) - The type of the field, it is read from the source and SHOULDN'T be change.
html_type (binary) - The HTML type of the field (e.g., :text, :number, :date).
html_id (binary) - A unique html id for the field.
renderer (function) - A custom rendering function for the field.
data (any) - A general purpose field. Template parser expect specific format for this data, according to any of the field value. Refer to the template documentation to learn special fields data structure.
Upload fields — a field is treated as a file-upload field when data contains an :upload key whose value is a map with the following structure:
```
  field :uploaded_blob_ref,
    data: %{
      upload: %{
        allow:   [accept: ~w(.xlsx), max_entries: 1, max_file_size: 5_000_000],
        consume: &MyApp.Templates.store_xlsx/1
      }
    }
```
- :allow — keyword list forwarded to Phoenix.LiveView.allow_upload/3 (:accept, :max_entries, :max_file_size, :auto_upload?, …).
- :consume — arity-1 callback. Receives a list of consumed binaries ([binary()]) and must return:
  - {:ok, value} — value is written onto the entity params under the field key.
  - :no_change — the field is left untouched; no-file-selected is also short-circuited to :no_change so the callback need not handle an empty list.
  - {:error, reason} — save aborts and reason is shown as an error flash.
resource (atom) - Used for associations, indicate the resource_config defining the meta data of the related element.
label (binary) - A display label for the field.
placeholder (binary) - Placeholder text for input fields.
length (non_neg_integer) - Maximum allowed length of input (used for validations).
precision (non_neg_integer) - Number of digits for numeric fields.
scale (non_neg_integer) - Number of digits to the right of the decimal separator, for numeric fields.
hidden (boolean) - If true the field should be included, but not visible. However, it is up to the implementation whether to include the field in the generated artifact or not.
readonly (boolean) - If true the field should not accept changes.
required (boolean) - Indicates that the field should not be empty or unused.
disabled (boolean) - If true, the field should not participate in form interaction.
omitted (boolean) - If true, the field won't be display nor interact with. It is equivalent to not having the field at all.
filterable? (boolean) - If true, it is expected that the field can be filterable by the UI.

Key Features

Encapsulates field properties for UI rendering and configuration.
Supports metadata for validation, display, and interaction in forms and tables.

Key Constraints

Field struct is used by template and resource modules for dynamic UI generation.
Some fields (e.g., data) may require special structure as expected by template parsers.
Not intended for direct use outside Aurora.Uix internals.

Summary

Types

t()

Functions

change(field, attrs)

Updates an existing Aurora.Uix.Field struct with new attributes.

delete(struct, key)

get(struct, key, default \\ nil)

new(attrs \\ %{})

Creates a new Aurora.Uix.Field struct with the given attributes.

put(struct, key, val)

Types

t()

@type t() :: %Aurora.Uix.Field{
  data: any() | nil,
  disabled: boolean(),
  filterable?: boolean(),
  hidden: boolean(),
  html_id: binary(),
  html_type: atom() | binary() | nil,
  key: atom() | nil,
  label: binary(),
  length: non_neg_integer(),
  name: binary(),
  omitted: boolean(),
  placeholder: binary(),
  precision: non_neg_integer(),
  readonly: boolean(),
  renderer: function() | nil,
  required: boolean(),
  resource: module() | nil,
  scale: non_neg_integer(),
  type: atom() | nil
}

Functions

change(field, attrs)

@spec change(t(), map() | keyword()) :: t()

Updates an existing Aurora.Uix.Field struct with new attributes.

Parameters

field (Aurora.Uix.Field.t()) - The existing field struct.
attrs (map() | keyword()) - Attributes to update in the struct.

Returns

Aurora.Uix.Field.t() - Updated field struct with new name/html_id if field changes.

Examples

field = Aurora.Uix.Field.new(%{field: :email})
Aurora.Uix.Field.change(field, %{label: "Email Address"})
# => %Aurora.Uix.Field{field: :email, label: "Email Address", ...}