LedgerUI.Components.Toast (LedgerUI v0.2.0)

Copy Markdown View Source

Notifications: the toaster, toasts pushed by the server, and the cards drawn in the page.

Mount the toaster once, in the layout every LiveView renders (it reads the flash):

<.toaster flash={@flash} />

Then, from the server:

conn |> put_toast("Saved", color: "success") |> redirect(to: ~p"/orders")
socket |> put_toast("Saved", color: "success") |> push_navigate(to: ~p"/orders")
socket |> send_toast("Copied", color: "info", position: "center-top")
socket |> send_toast("Sending…", id: "nfe-42", kind: :loading)
socket |> update_toast("nfe-42", kind: :success, title: "Sent")
socket |> dismiss_toast("nfe-42")
socket |> clear_toasts()

put_toast/3 goes through the flash (it survives a redirect and the standard :info/:error flash messages are drawn too); send_toast/3 pushes to the page at once. From the browser, with no round trip (both go through a ledger:toast event the toaster hook listens to):

<button phx-click={show_toast("Copied", color: "info")}>Copy</button>
<button phx-click={dismiss_toast("nfe-42")}>Hide</button>

Options: id (the same id updates a toast in place), title, description, kind (neutral info success warning error loading), status (run queue ok err, the compact dark card), color, position, duration (ms; 0 or :infinity keeps it until closed), close, timer, template (id of a <template> whose first element is shown), actions ([label:, event:, value:, target:, href:, js:, dismiss:, variant:, color:]), aura (true :dual :glow, with aura_size/aura_color), value (0..100 progress, bar: true), steps/step and invert.

The client side is the LedgerUI.Toaster hook (priv/static/ledger_ui/hooks/toaster.js).

toast_card/1 and status_toast/1 draw the same cards where they are written.

Summary

Functions

Removes every toast of the page.

JS command that removes the toast id in the browser.

Removes a toast. On a socket it pushes to the page; on a %JS{} (or alone) it is the browser command (see dismiss_toast/1).

Leaves a toast in the flash (survives a redirect). Works on a Plug.Conn and on a socket.

Pushes a toast to the page at once. The message is the title, or pass title: in the options.

JS command that shows a toast in the browser, with no round trip.

Changes only the given options of the toast id, keeping the rest.

Functions

clear_toasts(socket)

Removes every toast of the page.

dismiss_toast(id)

JS command that removes the toast id in the browser.

dismiss_toast(socket, id)

Removes a toast. On a socket it pushes to the page; on a %JS{} (or alone) it is the browser command (see dismiss_toast/1).

put_toast(conn_or_socket, message, opts \\ [])

Leaves a toast in the flash (survives a redirect). Works on a Plug.Conn and on a socket.

conn |> put_toast("Saved", color: "success") |> redirect(to: "/")

send_toast(socket, message_or_opts, opts \\ [])

Pushes a toast to the page at once. The message is the title, or pass title: in the options.

send_toast(socket, "Copied", color: "info")
send_toast(socket, id: "x", kind: :loading, title: "Working…")

show_toast(message, opts \\ [])

JS command that shows a toast in the browser, with no round trip.

<button phx-click={show_toast("Copied", color: "info")}>Copy</button>

Takes the options of send_toast/3 plus to: (the toaster selector, "#ledger-toaster").

show_toast(js, message, opts)

status_toast(assigns)

Attributes

  • state (:string) - Defaults to "run". Must be one of "run", "queue", "ok", or "err".
  • status (:string) - The same as state; it wins when given. Defaults to nil. Must be one of nil, "run", "queue", "ok", or "err".
  • percent (:integer) - Defaults to nil.
  • class (:any) - Defaults to nil.
  • Global attributes are accepted. title="..." is the message when there is no inner block; action="Cancel" is a text button after it (the :action slot takes real ones). Supports all globals plus: ["action"].

Slots

  • action - Accepts attributes:
    • ghost (:boolean)
    • on_click (:any)
    • id (:string)
    • href (:string)
    • navigate (:string)
    • patch (:string)
  • inner_block

toast_card(assigns)

Attributes

  • id (:string) - Defaults to nil.
  • tone (:string) - Defaults to "light". Must be one of "light", or "dark".
  • kind (:string) - Defaults to "neutral". Must be one of "neutral", "primary", "success", "warning", "error", or "info".
  • icon (:string) - Defaults to nil.
  • title (:string) (required)
  • description (:string) - Defaults to nil.
  • dismissible (:boolean) - Defaults to true.
  • close_label (:string) - Defaults to "Close".
  • on_dismiss (:any) - Defaults to nil.
  • busy (:boolean) - Defaults to false.
  • busy_label (:string) - Accessible name of the spinner (none when nil). Defaults to nil.
  • progress (:integer) - Defaults to nil.
  • progress_state (:string) - Defaults to "run". Must be one of "run", "done", or "fail".
  • aura (:string) - Defaults to nil.Must be one of nil, "", "spin", "dual", or "glow".
  • aura_tone (:string) - Defaults to "accent". Must be one of "accent", "ai", "info", "pos", "warn", "neg", or "violet".
  • aura_width (:string) - Defaults to "default". Must be one of "xs", "sm", "default", or "lg".
  • aura_shadow (:boolean) - Defaults to true.
  • aura_style (:string) - Inline style of the aura wrapper (its width, the card's corner --r). Defaults to "width:100%;--r:15px".
  • class (:any) - Defaults to nil.
  • Global attributes are accepted.

Slots

  • action - Buttons between the text and the close button.
  • icon_tile - Replaces the icon inside the tile.

toaster(assigns)

Attributes

  • id (:string) - Defaults to "ledger-toaster".
  • flash (:map) - The @flash, where put_toast/3 leaves its toasts. Defaults to %{}.
  • position (:string) - Defaults to "center-bottom". Must be one of "left-top", "left-bottom", "center-top", "center-bottom", "right-top", or "right-bottom".
  • duration (:integer) - Defaults to 5000.
  • stack (:boolean) - Defaults to true.
  • persist_errors (:boolean) - Defaults to false.
  • timer (:boolean) - Defaults to true.
  • invert (:boolean) - Defaults to false.
  • close_label (:string) - Defaults to "Close".
  • loading_label (:string) - Defaults to "Loading".
  • contained (:boolean) - Draw the toaster inside its parent (a demo panel) instead of over the page. Defaults to false.
  • Global attributes are accepted.

Slots

  • inner_block - Toasts already on screen at render time (a static preview), in the stack.

update_toast(socket, id, opts)

Changes only the given options of the toast id, keeping the rest.