LedgerUI (LedgerUI v0.2.0)

Copy Markdown View Source

Phoenix LiveView components with the Ledger UI design.

Usage

defmodule MyAppWeb do
  defp html_helpers do
    quote do
      use LedgerUI
    end
  end
end

use LedgerUI imports the function components (and the documented JS/socket helpers such as show_toast/2) of every module listed in LedgerUI.Components.__modules__/0, so <.button>, <.icon>, etc. are available in HEEx templates. Implementation helpers stay in their modules and are not imported.

Choosing what is imported

use LedgerUI imports every component, so a name that your own modules (Phoenix's generated CoreComponents: button, input, table, header, icon, modal, label, error...) also define is ambiguous where it is called. Leave the colliding ones out, or take only the ones you want (a name is every arity, {name, arity} one of them):

use LedgerUI, except: [:button, :input, :table, :header, :icon, :modal]
use LedgerUI, only: [:card, :badge, :progress, :sidebar]

The left-out ones stay available by their module, <LedgerUI.Components.Button.button>, or import them under a prefix of your own. A name that is not a component raises at compile time.

Mode and palette

Two independent switches on <html>: data-theme="light|dark" (the mode, theme_switch/1) and data-palette="ledger|crepusculo" (the palette, theme_picker/1). Every palette defines its own light and dark token sets in ledger.css; components never change. Both choices are kept in localStorage (theme, ledger-palette) and applied before the first paint by theme_script/1:

<html data-theme="dark" data-palette="crepusculo">
<.theme_switch id="mode" />
<.theme_picker id="palette" themes={~w(ledger crepusculo)} />

Opening and closing elements

Overlays (modal, drawer, popover, menus...) are shown by the CSS class open. These helpers toggle it:

  • open/2, close/2, toggle/2 on a Phoenix.LiveView.JS struct: client-side, no round trip. They add/remove/toggle the class open on #id and update aria-expanded on the triggers that point at it with aria-controls="id".

    <button phx-click={LedgerUI.open("my-drawer")} aria-controls="my-drawer">Open</button>
  • open/2 and close/2 on a socket: push the "ledger:open" / "ledger:close" events with %{id: id}; the glue in ledger_ui.js adds/removes the class open.

    def handle_event("save", _, socket), do: {:noreply, LedgerUI.close(socket, "my-drawer")}

Summary

Functions

Removes the class open from #id (and sets aria-expanded="false" on its triggers).

Adds the class open to #id (and sets aria-expanded="true" on its triggers).

Toggles the class open on #id (and flips aria-expanded on its triggers). Client-side only.

Functions

close(js_or_socket \\ %JS{}, id)

Removes the class open from #id (and sets aria-expanded="false" on its triggers).

With a socket, pushes the "ledger:close" event instead.

open(js_or_socket \\ %JS{}, id)

Adds the class open to #id (and sets aria-expanded="true" on its triggers).

With a socket, pushes the "ledger:open" event instead.

toggle(js \\ %JS{}, id)

Toggles the class open on #id (and flips aria-expanded on its triggers). Client-side only.