Helper functions for integrating SaladUI components with Phoenix LiveView.

SaladUI components communicate with LiveView in two directions:

Component events (client → server)

Interactive components expose on-* attributes such as on-open, on-close, on-value-changed, and on-select. These attributes map component lifecycle or interaction events to LiveView handlers.

Event attributes accept either:

• a server event name string, pushed with pushEventTo/3
• a %Phoenix.LiveView.JS{} command, executed on the component root

<.sheet
  id="profile-sheet"
  on-open="sheet_opened"
  on-close={JS.push("sheet_closed")}
>
  ...
</.sheet>

def handle_event("sheet_opened", params, socket) do
  # params include component metadata such as componentId and component
  {:noreply, socket}
end

def handle_event("sheet_closed", _params, socket) do
  {:noreply, socket}
end

Components emit their documented client events when state changes or user interactions occur. Common dialog-like events are open and close.

Server commands (server → client)

Use send_command/4 inside LiveView callbacks to control a component by id. Commands map to component state-machine transitions or component-specific commands. Common commands are "open", "close", and "toggle".

def handle_event("open_profile", _params, socket) do
  socket = SaladUI.LiveView.send_command(socket, "profile-sheet", "open")
  {:noreply, socket}
end

def handle_event("close_profile", _params, socket) do
  socket = SaladUI.LiveView.send_command(socket, "profile-sheet", "close")
  {:noreply, socket}
end

send_command/4 pushes the LiveView event "saladui:command" to the browser. SaladUI's hook receives it, matches target against the component root id, and calls the component's handleCommand(command, params).

Client-side commands

Use SaladUI.JS.dispatch_command/3 when a LiveView JS command should control a component directly in the browser.

<.button phx-click={%JS{} |> SaladUI.JS.dispatch_command("open", to: "#profile-sheet")}>
  Open
</.button>

This dispatches a DOM event named "salad_ui:command" on the target element.