Provides utility functions for LiveView components in Aurora UIX.
This module includes functions for managing navigation stacks, assigning values to sockets, handling entity relationships, and managing section/tab assignments within the Aurora UIX framework.
:auix map:auix keyAction.action_groups()Returns a keyword list suitable for spreading as component props with the configured actor assign, or an empty list if no actor is configured.
Adds an action to the specified actions group in the map.
Stores the configured actor value inside socket.assigns.auix so it travels through the
rendering chain to descendant live components (e.g. EmbedsManyComponent).
Assigns a value to the auix assigns map in the socket.
Extracts and assigns the current path out of the current url, to the auix map.
Sets the index new link value. Relies on the existence of auix.uri_path key.
Assigns a value to the auix assigns map in the socket only if it does not exist.
Assigns a layout option to the socket's assigns using the LayoutOptions module.
Sets a layout option to the auix entry in the socket's assigns.
Assigns routing stack to the socket. Decodes stack from params or uses default route.
Assigns section configuration to auix assigns map.
Sets a temporary to the auix entry in the socket's assigns.
Sets the global uri path, relies on auix_current_path.
Precomputes the initial expanded state for every embeds_many field and stores it in
auix.embeds_expanded as a %{field_key => boolean} map.
Assigns the index of the current entity in the primary keys list.
Assigns a new entity to the socket based on related parameters.
Assigns parsed options to the auix assigns map in the socket.
Precomputes the download-button visibility for every upload field and stores it in
auix.upload_downloadable as a %{field_key => boolean} map.
Handles backward navigation by popping the last route from the stack.
Handles forward navigation by updating the routing stack and navigating to the new path.
Resolves backend-specific per-call options from a LiveView socket for a connector.
Handles the auix_download_upload event by dispatching to the field's :download callback.
Returns true when the field is an embeds_many field.
Returns the list of embeds_many field structs for the current resource in an auix map.
Extracts association fields from preload configuration grouped by association type.
Flattens a nested structure of elements into a list of paths.
A helper that transforms Ash errors into a list of messages.
A helper that transforms changeset errors into a map of messages.
Retrieves the configuration for a specific resource from the assigns or auix map.
Retrieves and processes field configuration from the resource configurations.
Retrieves the layout tree for a specific resource and layout type.
Retrieves a specific resource configuration key from the assigns or auix map.
Gets select field options and multiple selection flag.
Inserts an action at the beginning of the specified actions group in the assigns map.
Assigns the configured actor from auix into the socket so that backend_socket_opts/2
can resolve it for descendant CRUD calls.
Gets the value of an entity's primary key.
Removes an action by name from the specified actions group in the assigns map.
Replaces an action by name in the specified actions group in the map.
Converts data to a named Phoenix.HTML.Form.
Returns true iff the field carries a data.upload map (i.e., it is an upload field).
Returns the list of upload field structs for the current resource in an auix map.
Returns a keyword list suitable for spreading as component props with the configured actor assign, or an empty list if no actor is configured.
Reads the actor key from the auix connector configuration and the actor value from assigns.
Safe to use in HEEx with {actor_assign_prop(@auix, assigns)} — returns [] when the
backend is Ctx or no actor key is configured.
auix (map()) - The Aurora UIX context map, used to determine the configured actor key.assigns (map()) - The map to read the actor value from (use assigns in the IndexRenderer,
or @auix in the EmbedsManyRenderer where the actor is stored in auix).keyword() - [{key, value}] when configured, [] otherwise.
iex> actor_assign_prop(%{create_function: %Connector{crud_spec: %AshCrudSpec{actor_assign: :current_user}}},
...> %{current_user: %User{}})
[current_user: %User{}]
iex> actor_assign_prop(%{create_function: %Connector{crud_spec: %CtxCrudSpec{}}}, %{current_user: %User{}})
[]@spec add_auix_action( Phoenix.LiveView.Socket.t() | map(), atom(), Aurora.Uix.Action.t() ) :: Phoenix.LiveView.Socket.t() | map()
Adds an action to the specified actions group in the map.
assigns_or_socket (Phoenix.LiveView.Socket.t() | map()) - The map containing the :auix key.
actions_group (atom()) - The group to which the action will be added.action (Action.t()) - The action to add.Phoenix.LiveView.Socket.t() | map() - The updated map with the action added to the group.
@spec assign_actor_to_auix(Phoenix.LiveView.Socket.t()) :: Phoenix.LiveView.Socket.t()
Stores the configured actor value inside socket.assigns.auix so it travels through the
rendering chain to descendant live components (e.g. EmbedsManyComponent).
Reads the actor key from the auix connector configuration, then reads the actor value from
socket.assigns, and stores it in socket.assigns.auix under the same key. No-op when no
actor key is configured.
Must be called AFTER assign_parsed_opts/2 (so that connectors are available on the auix
map) and AFTER the initial assign(assigns) (so that the actor value is in socket.assigns).
socket (Phoenix.LiveView.Socket.t()) - The LiveView socket.Phoenix.LiveView.Socket.t() - Socket with actor value stored in auix (unchanged if not configured).
@spec assign_auix(Phoenix.LiveView.Socket.t() | map(), atom(), term()) :: Phoenix.LiveView.Socket.t() | map()
Assigns a value to the auix assigns map in the socket.
socket (Phoenix.LiveView.Socket.t()) - The LiveView socket.key (atom()) - Key for storing in auix map.value (term()) - Value to store.Phoenix.LiveView.Socket.t() - Socket with updated auix assigns.
@spec assign_auix_current_path(Phoenix.LiveView.Socket.t(), binary() | URI.t() | nil) :: Phoenix.LiveView.Socket.t()
Extracts and assigns the current path out of the current url, to the auix map.
socket (Phoenix.LiveView.Socket.t()) - The LiveView socket.url (binary() | URI.t() | nil) - Actual url.
Phoenix.LiveView.Socket.t() - Socket with updated auix assigns.
@spec assign_auix_index_new_link(Phoenix.LiveView.Socket.t()) :: Phoenix.LiveView.Socket.t()
Sets the index new link value. Relies on the existence of auix.uri_path key.
socket (Phoenix.LiveView.Socket.t()) - The LiveView socket.Phoenix.LiveView.Socket.t() - Socket with updated auix assigns.
@spec assign_auix_new(Phoenix.LiveView.Socket.t(), atom(), any()) :: Phoenix.LiveView.Socket.t()
Assigns a value to the auix assigns map in the socket only if it does not exist.
socket (Phoenix.LiveView.Socket.t()) - The LiveView socket.key (atom()) - Key for storing in auix map.value (term()) - Value to store.Phoenix.LiveView.Socket.t() - Socket with updated auix assigns.
@spec assign_auix_option(Phoenix.LiveView.Socket.t() | map(), atom()) :: Phoenix.LiveView.Socket.t() | map()
Assigns a layout option to the socket's assigns using the LayoutOptions module.
Retrieves the option value using LayoutOptions.get/2. If the option is not found, assigns the
socket unchanged. Otherwise, stores the value in the :layout_options key within the auix map.
socket (Phoenix.LiveView.Socket.t()) - The LiveView socket.option (atom()) - The option key to retrieve and assign.Phoenix.LiveView.Socket.t() - The socket with the option assigned in auix.layout_options.
@spec assign_auix_option(Phoenix.LiveView.Socket.t(), atom(), term() | nil) :: Phoenix.LiveView.Socket.t()
Sets a layout option to the auix entry in the socket's assigns.
socket (Phoenix.LiveView.Socket.t()) - The LiveView socket.option (atom()) - The option key to retrieve and assign.option_value (term() | nil) - The value to put on the option.
Phoenix.LiveView.Socket.t() - Socket with updated auix assigns.
@spec assign_auix_routing_stack(Phoenix.LiveView.Socket.t(), map(), map() | nil) :: Phoenix.LiveView.Socket.t()
Assigns routing stack to the socket. Decodes stack from params or uses default route.
socket (Phoenix.LiveView.Socket.t()) - The LiveView socket.params (map()) - Parameters, may contain "routing_stack" as a key.default_route (map() | nil) - Optional default route to use if no stack is present.
Phoenix.LiveView.Socket.t() - The socket with updated routing stack.
iex> params = %{"routing_stack" => encoded_stack}
iex> assign_auix_routing_stack(socket, params, nil)
%Phoenix.LiveView.Socket{assigns: %{routing_stack: %Stack{...}}}
iex> assign_auix_routing_stack(socket, %{}, nil)
%Phoenix.LiveView.Socket{assigns: %{routing_stack: %Stack{}}}
iex> assign_auix_routing_stack(socket, %{}, %{path: "/default"})
%Phoenix.LiveView.Socket{assigns: %{routing_stack: %Stack{...}}}@spec assign_auix_sections(Phoenix.LiveView.Socket.t(), binary(), binary()) :: Phoenix.LiveView.Socket.t()
Assigns section configuration to auix assigns map.
socket (Phoenix.LiveView.Socket.t()) - The LiveView socket.sections_id (binary()) - Identifier for the sections group.tab_id (binary()) - Identifier for the active tab.Phoenix.LiveView.Socket.t() - Socket with updated auix assigns.
@spec assign_auix_temp(Phoenix.LiveView.Socket.t(), atom(), any()) :: any()
Sets a temporary to the auix entry in the socket's assigns.
There is no guarantee that the elements here will remain in the socket.
socket (Phoenix.LiveView.Socket.t()) - The LiveView socket.key (atom()) - The key to assign.value (term()) - The value to put on the temp space.Phoenix.LiveView.Socket.t() - Socket with updated auix assigns.
@spec assign_auix_uri_path(Phoenix.LiveView.Socket.t()) :: Phoenix.LiveView.Socket.t()
Sets the global uri path, relies on auix_current_path.
socket (Phoenix.LiveView.Socket.t()) - The LiveView socket.Phoenix.LiveView.Socket.t() - Socket with updated auix assigns.
@spec assign_embeds_expanded(Phoenix.LiveView.Socket.t()) :: Phoenix.LiveView.Socket.t()
Precomputes the initial expanded state for every embeds_many field and stores it in
auix.embeds_expanded as a %{field_key => boolean} map.
Must be called in auix_update/2 (form and show impls) where the rich assigns (form,
entity, actor) are available. The renderer reads the precomputed boolean so no
user-provided gate runs inside the pure render path.
A field's :expanded data option may be a boolean or a function of arity 1 that
receives the current assigns and returns a boolean. When absent, the default is false
(collapsed).
socket (Phoenix.LiveView.Socket.t()) - The current LiveView socket.Phoenix.LiveView.Socket.t() - Socket with auix.embeds_expanded assigned.
@spec assign_item_index(Phoenix.LiveView.Socket.t()) :: Phoenix.LiveView.Socket.t()
Assigns the index of the current entity in the primary keys list.
Determines the index position of the current entity by matching its primary key values against the list of primary keys stored in the socket assigns. Returns -1 if no entity is assigned or if no matching primary key is found.
socket (Phoenix.LiveView.Socket.t()) - The LiveView socket containing entity and
primary key data.Phoenix.LiveView.Socket.t() - Socket with :item_index assigned in auix map.
iex> socket = %Socket{assigns: %{auix: %{entity: nil}}}
iex> assign_item_index(socket)
%Socket{assigns: %{auix: %{item_index: -1}}}
iex> entity = %User{id: 1}
iex> socket = %Socket{assigns: %{auix: %{
...> entity: entity,
...> primary_key: [:id],
...> primary_keys: [{0, [id: 1]}, {1, [id: 2]}]
...> }}}
iex> assign_item_index(socket)
%Socket{assigns: %{auix: %{item_index: 0}}}@spec assign_new_entity(Phoenix.LiveView.Socket.t(), map(), struct()) :: Phoenix.LiveView.Socket.t()
Assigns a new entity to the socket based on related parameters.
socket (Phoenix.LiveView.Socket.t()) - The LiveView socket.params (map()) - Map containing optional related_key and parent_id for relationships.default (struct()) - Default entity struct for new record.Phoenix.LiveView.Socket.t() - Socket with entity assigned to :auix.entity.
@spec assign_parsed_opts(Phoenix.LiveView.Socket.t(), map()) :: Phoenix.LiveView.Socket.t()
Assigns parsed options to the auix assigns map in the socket.
socket (Phoenix.LiveView.Socket.t()) - The LiveView socket.parsed_opts (map()) - Options to merge with existing auix assigns.Phoenix.LiveView.Socket.t() - Socket with updated auix assigns.
@spec assign_upload_downloadable(Phoenix.LiveView.Socket.t()) :: Phoenix.LiveView.Socket.t()
Precomputes the download-button visibility for every upload field and stores it in
auix.upload_downloadable as a %{field_key => boolean} map.
Must be called in auix_update/2 after the entity is assigned. The renderer reads
the precomputed boolean so no user-provided code runs inside the pure function component.
A field's button is false (hidden) unless it has a :download producer function
configured — that is the opt-in master switch. When :downloadable? is absent, the
default gate is not is_nil(value).
socket (Phoenix.LiveView.Socket.t()) - The current LiveView socket.Phoenix.LiveView.Socket.t() - Socket with auix.upload_downloadable assigned.
@spec auix_route_back(Phoenix.LiveView.Socket.t()) :: Phoenix.LiveView.Socket.t()
Handles backward navigation by popping the last route from the stack.
socket (Phoenix.LiveView.Socket.t()) - The LiveView socket.Phoenix.LiveView.Socket.t() - Socket with updated routing stack.
@spec auix_route_forward( Phoenix.LiveView.Socket.t(), keyword() ) :: Phoenix.LiveView.Socket.t()
Handles forward navigation by updating the routing stack and navigating to the new path.
socket (Phoenix.LiveView.Socket.t()) - The LiveView socket.navigation (keyword()) - Navigation options with :navigate or :patch key.Phoenix.LiveView.Socket.t() - Socket with updated routing stack.
@spec backend_socket_opts( Phoenix.LiveView.Socket.t() | map(), Aurora.Uix.Integration.Connector.t() | nil ) :: keyword()
Resolves backend-specific per-call options from a LiveView socket for a connector.
Thin wrapper over Aurora.Uix.Integration.Crud.apply_socket_opts/2 that lets
handlers stay backend-agnostic. The Ash backend uses this to pull an actor from
socket.assigns when crud_spec.actor_assign is set; the Ctx backend always
returns [].
Accepts a nil connector (returns []) so handlers can call it unconditionally
for sites where the connector may be absent.
socket_or_assigns (Phoenix.LiveView.Socket.t() | map()) - A LiveView socket or a
bare assigns map (will be wrapped as %{assigns: assigns} internally).
connector (Connector.t() | nil) - The CRUD connector to extract opts for.
keyword() - Options to merge into the next CRUD call, e.g. [actor: %User{}].
Always a keyword, safe to merge via ++.
iex> backend_socket_opts(socket, auix.get_function)
[actor: %User{id: 1}]
iex> backend_socket_opts(socket, nil)
[]Merge the result into your own opts so policy-protected CRUD calls receive the configured actor:
socket_opts = backend_socket_opts(socket, socket.assigns.auix.list_function)
results = apply_list_function(
socket.assigns.auix.list_function,
socket_opts ++ [filter: [title: query]]
)See the Ash integration guide — Authorization & policies for the end-to-end flow.
@spec download_upload(Phoenix.LiveView.Socket.t(), binary()) :: Phoenix.LiveView.Socket.t()
Handles the auix_download_upload event by dispatching to the field's :download callback.
Looks up the upload field by key, reads the stored value from the entity, and invokes
the :download producer with the same arity-dispatch pattern as :consume. On success,
pushes the auix_download event to the client. On :no_download, returns the socket
unchanged. On {:error, reason}, puts an error flash.
socket (Phoenix.LiveView.Socket.t()) - The current LiveView socket.field_str (binary()) - The stringified field key from the event params.Phoenix.LiveView.Socket.t() - Updated socket.
@spec embeds_many_field?(Aurora.Uix.Field.t()) :: boolean()
Returns true when the field is an embeds_many field.
field (Aurora.Uix.Field.t()) - The field struct to inspect.boolean() - true when field.type is :embeds_many, false otherwise.
@spec embeds_many_fields(map()) :: [Aurora.Uix.Field.t()]
Returns the list of embeds_many field structs for the current resource in an auix map.
Traverses auix.configurations[auix.resource_name].resource_config.fields and returns
only those fields whose type is :embeds_many.
auix (map()) - The Aurora UIX context map containing configurations and resource_name.list(Aurora.Uix.Field.t()) - Embeds_many fields, or [] when none are configured.
Extracts association fields from preload configuration grouped by association type.
parsed_opts (map()) - Configuration map containing preload and resource settings.map() - Map with association field types (:one_to_many, :many_to_one) as keys and lists of
field names as values.
Flattens a nested structure of elements into a list of paths.
elements (map() | list()) - Nested structure containing inner_elements and tags.
result (list()) - Accumulated result, defaults to empty list.list() - Flattened list of maps containing tag and name information.
@spec format_ash_error(Exception.t()) :: list()
A helper that transforms Ash errors into a list of messages.
error (Exception.t()) - The Ash error struct.list() - List of formatted error messages.
@spec format_changeset_errors(Ecto.Changeset.t()) :: list()
A helper that transforms changeset errors into a map of messages.
changeset (Ecto.Changeset.t()) - The changeset containing errors.list() - List of formatted error messages.
iex> assert {:error, changeset} = Accounts.create_user(%{password: "short"})
iex> assert "password is too short" in errors_on(changeset).password
iex> assert %{password: ["password is too short"]} = errors_on(changeset)Retrieves the configuration for a specific resource from the assigns or auix map.
assigns_or_auix (map()) - The assigns map or auix map containing configurations.resource_name (atom()) - The name of the resource to retrieve configuration for.map() - The configuration map for the specified resource, or an empty map if not found.
@spec get_field(map(), map(), atom()) :: Aurora.Uix.Field.t()
Retrieves and processes field configuration from the resource configurations.
field (%{name: atom()}) - Map containing the field name and options.configurations (map()) - Global configurations for all resources.resource_name (atom()) - The name of the resource the field belongs to.Field.t() - A Field struct containing the processed field configuration.
Retrieves the layout tree for a specific resource and layout type.
assigns_or_auix (map()) - The assigns map or auix map containing configurations.resource_name (atom()) - The name of the resource to retrieve layout for.layout_type (atom()) - The type of layout to retrieve (e.g., :form, :index).map() - The layout tree map for the specified resource and layout type, or an empty map if not found.
Retrieves a specific resource configuration key from the assigns or auix map.
assigns_or_auix (map()) - The assigns map or auix map containing configurations.resource_name (atom()) - The name of the resource to retrieve configuration for.key (atom() | list()) - The specific key to retrieve from the resource configuration.
term() - The value for the specified key in the resource configuration, or an empty map if not found.
Gets select field options and multiple selection flag.
Processes field configuration to generate options for select inputs. Handles different data sources including related resources and hardcoded options.
assigns (map()) - Assigns map containing field and configuration data.map() - Map with :options (list of {label, value} tuples) and :multiple (boolean()).
@spec insert_auix_action( Phoenix.LiveView.Socket.t() | map(), atom(), Aurora.Uix.Action.t() ) :: Phoenix.LiveView.Socket.t() | map()
Inserts an action at the beginning of the specified actions group in the assigns map.
assigns_or_socket (Phoenix.LiveView.Socket.t() | map()) - The assigns map containing the
:auix key.
actions_group (atom()) - The group to which the action will be added.action (Action.t()) - The action to insert.Phoenix.LiveView.Socket.t() | map() - The updated map with the action inserted at the beginning of the group.
@spec maybe_assign_actor(Phoenix.LiveView.Socket.t(), map()) :: Phoenix.LiveView.Socket.t()
Assigns the configured actor from auix into the socket so that backend_socket_opts/2
can resolve it for descendant CRUD calls.
Used in live component update/2 callbacks (e.g. EmbedsManyComponent) where the actor
value was stored in auix by the parent FormComponent via assign_actor_to_auix/1.
socket (Phoenix.LiveView.Socket.t()) - The LiveView socket.auix (map()) - The Aurora UIX context containing the stored actor value.Phoenix.LiveView.Socket.t() - Socket with actor assigned, or unchanged if not configured.
Gets the value of an entity's primary key.
entity (term() | nil) - The entity that will be primary key value.
primary_key (atom() | list()) - The field (or fields) to be gather from the entity.
term() | list() | nil - Return a single value if the primary key is an atom() or a single
element list. Otherwise returns a list of values, each corresponding to each of the primary key
list of fields.
Removes an action by name from the specified actions group in the assigns map.
assigns_or_socket (Phoenix.LiveView.Socket.t() | map()) - The assigns map containing the
:auix key.
actions_group (atom()) - The group from which the action will be removed.action_name (atom()) - The name of the action to remove.Phoenix.LiveView.Socket.t() | map() - The updated assigns map with the action removed from the group.
@spec replace_auix_action( Phoenix.LiveView.Socket.t() | map(), atom(), Aurora.Uix.Action.t() ) :: map()
Replaces an action by name in the specified actions group in the map.
assigns_or_socket (Phoenix.LiveView.Socket.t() | map()) - The map containing the :auix key.
actions_group (atom()) - The group in which the action will be replaced.action (Action.t()) - The action to replace, must include a :name key.Phoenix.LiveView.Socket.t() | map() - The updated map with the action replaced.
Converts data to a named Phoenix.HTML.Form.
Creates a form struct from the given data and assigns it a specific name and id. Useful for nested forms or when you need explicit form naming.
data (map()) - The form data source.form_name (atom() | binary()) - The name to assign to the form.
opts (keyword()) - Options passed to Phoenix.Component.to_form/2. Defaults to [].Phoenix.HTML.Form.t() - A form struct with the specified name and id.
@spec upload_field?(Aurora.Uix.Field.t()) :: boolean()
Returns true iff the field carries a data.upload map (i.e., it is an upload field).
field (Aurora.Uix.Field.t()) - The field struct to inspect.boolean() - true when field.data[:upload] is a map, false otherwise.
@spec upload_fields(map()) :: [Aurora.Uix.Field.t()]
Returns the list of upload field structs for the current resource in an auix map.
Traverses auix.configurations[auix.resource_name].resource_config.fields and returns
only those fields for which the data field contains a upload key.
auix (map()) - The Aurora UIX context map containing configurations and resource_name.list(Aurora.Uix.Field.t()) - Upload fields, or [] when none are configured.