# `LedgerUI`
[🔗](https://github.com/devaction-labs/ledger_ui/blob/v0.2.0/lib/ledger_ui.ex#L1)

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")}

# `close`

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

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

# `open`

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

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

# `toggle`

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

---

*Consult [api-reference.md](api-reference.md) for complete listing*
