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 — callback invoked with the consumed binaries. Arity is detected automatically via Function.info/1:

    Arity	Call shape	When to use
    1	consume.(binaries)	Pure transform; no socket context needed.
    2	consume.(socket, binaries)	Needs socket assigns (e.g. current_user).
    3	consume.(socket, binaries, key)	One callback handles multiple upload fields.

    All arities must return one of:

    • {: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.

    The socket is never returned by :consume; use handle_event("save", …) override for socket mutations on save.

  • :download — optional producer callback invoked when the user clicks the Download button. Its presence is the opt-in master switch: no :download key means no button is rendered. Arity is detected the same way as :consume, with the stored field value as the primary argument:

    Arity	Call shape	When to use
    1	download.(value)	Pure retrieval; no socket context needed.
    2	download.(socket, value)	Needs socket assigns (e.g. current_user).
    3	download.(socket, value, key)	One callback handles multiple upload fields.

    All arities must return one of:

    • {:ok, %{name: filename, content: binary}} — triggers a client-side file download. An optional :content_type key may be included in the map.
    • :no_download — does nothing.
    • {:error, reason} — reason is shown as an error flash.

    Actor-based visibility should be enforced here (return {:error, …} or :no_download), since the socket (and thus current_user) is available to arity-2 and arity-3 callbacks.

  • :downloadable? — optional gate callback evaluated when the component mounts or updates. Controls whether the Download button is visible. Only evaluated when :download is also configured. Follows the same arity-dispatch pattern, with the stored field value as the primary argument:

    Arity	Call shape
    1	downloadable?.(value)
    2	downloadable?.(socket, value)
    3	downloadable?.(socket, value, key)

    Must return a boolean. When absent, defaults to not is_nil(value).

• 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.