Componentes Phoenix LiveView com o design Ledger UI.
Instalação
def deps do
[{:ledger_ui, "~> 0.1.0"}]
endUso
# em MyAppWeb.html_helpers/0 (ou onde importa componentes)
use LedgerUI<.icon name="download" />Junto com o CoreComponents do Phoenix
O use LedgerUI importa todos os componentes. Os nomes que o CoreComponents gerado pelo Phoenix 1.8 também define
(button, input, table, header, icon, modal, label, error...) ficam ambíguos onde são chamados: o
compilador recusa <.button> se dois módulos importados têm button/1. Escolha de quem é cada nome com except:
(todos menos estes) ou only: (só estes); o nome vale para qualquer aridade, nome: 1 para uma só:
# em MyAppWeb.html_helpers/0
import MyAppWeb.CoreComponents
use LedgerUI, except: [:button, :input, :table, :header, :icon, :modal, :label, :error]
# ou só o que interessa
use LedgerUI, only: [:card, :badge, :progress, :sidebar, :tabs]O que ficou de fora continua à mão pelo módulo (<LedgerUI.Components.Button.button>), ou por um import seu com
prefixo. Um nome que não é componente do Ledger UI derruba a compilação.
Nomes da vitrine: onde o README de um componente usa um nome (progress, number_input, range, radio_group,
cover, drawer, menu_list, text, datetime_picker, empty_state, text_editor, main_sidebar) a vitrine usa
outro; os dois existem (progress_bar, number_stepper, range_slider, radio/radio_choice, cover_card,
sheet, menu, typography, date_time_picker, empty_state_card/inline_empty, rich_text_editor/
comment_editor, icon_rail, sub_nav, shell_floating, container, tree). Não existe list/1: é o nome do
list do CoreComponents (use description_list, cujo <:item title="..."> tem o mesmo formato).
Stylesheet e JS
CSS: ledger.css (tokens e classes lu-*, o CSS do design, não editar) e ledger_ui.css (complemento, carregado DEPOIS: [hidden], controles reais dentro dos wrappers do kit, estados de overlay, --ledger-z-* e as classes que os componentes/hooks adicionam). JS: módulo ES priv/static/ledger_ui.esm.js que exporta {Hooks, DOM}
(as chaves de Hooks são "LedgerUI.<Nome>").
Com esbuild (o package.json do pacote aponta para o módulo; adicione deps ao NODE_PATH):
import {Hooks as LedgerHooks, DOM as LedgerDOM} from "ledger_ui"
new LiveSocket("/live", Socket, {
hooks: {...LedgerHooks},
dom: {onBeforeElUpdated(from, to) { LedgerDOM.onBeforeElUpdated(from, to) }},
params: {_csrf_token: csrfToken}
})@import "ledger_ui/css/ledger.css"; /* exports "./css" e "./css/ledger.css" */
@import "ledger_ui/css/ledger_ui.css"; /* depois do ledger.css */
/* ou <link> para /ledger_ui/ledger.css e depois /ledger_ui/ledger_ui.css */Sem bundler, sirva priv/static (ex.: Plug.Static at: "/ledger_ui", from: {:ledger_ui, "priv/static"}) e use
<script type="module"> com import {Hooks, DOM} from "/ledger_ui/ledger_ui.esm.js".
ledger.js é só a biblioteca de gráficos/runtime (window.LedgerUI); os ícones são renderizados no servidor.
LedgerUI.open/2, close/2 e toggle/2 abrem/fecham elementos (classe open) via Phoenix.LiveView.JS;
no servidor use LedgerUI.open(socket, id).
Ícones
<.icon> desenha no servidor os 141 ícones do dicionário embutido (LedgerUI.Components.Icon.names/0).
Qualquer outro ícone do Hugeicons Stroke Rounded (set gratuito, MIT)
vem para a sua app com mix ledger_ui.icons, sem dependência extra:
# config/config.exs (numa release: {:minha_app, "priv/hugeicons"})
config :ledger_ui, :icons_path, "priv/hugeicons"mix ledger_ui.icons get search-01 tick-02 # baixa esses (aceita huge-search-01)
mix ledger_ui.icons sync # baixa o que <.icon name="huge-..."> usa em lib/, assets/js e priv/templates
mix ledger_ui.icons sync --prune # ...e remove os que ninguém usa
mix ledger_ui.icons search invoice # procura nomes no repositório
mix ledger_ui.icons update # sobe para o commit mais novo de main (ou --ref TAG)
<.icon name="huge-invoice-01" size="sm" />Os SVGs são convertidos para o formato do kit (traço currentColor, 1.5, pontas redondas vêm da regra .lu-i;
sem cor fixa) e gravados em priv/hugeicons/ junto com .hugeicons.json (commit, nomes) e LICENSE.md. A pasta é
lida uma vez para o :persistent_term; o markup é o mesmo dos embutidos (svg.lu-i ... data-icon). Ordem de busca:
nome embutido exato, arquivo vendorizado, nome embutido sem o sufixo -NN; nome desconhecido não renderiza e avisa
no log. Ícones baixados depois do boot são achados sem reiniciar. O download usa o commit fixado na task (ou o do manifesto).
Skill do Claude Code
Gera .claude/skills/ledger-ui/ na sua app a partir do pacote instalado (atributos, valores, slots e docs de cada
function component), para um agente escrever HEEx certo sem adivinhar:
mix ledger_ui.install # escreve a skill, aponta AGENTS.md/CLAUDE.md para ela e imprime as linhas de setup
mix ledger_ui.gen.skill # só (re)gera a skill; --path muda a pasta
.claude/skills/ledger-ui/
SKILL.md # nome, versão, regras e a tabela de componentes
references/<componente>.mdPara renovar a cada atualização do pacote, ligue o compilador no mix.exs da app:
def project do
[compilers: [:ledger_ui_skill] ++ Mix.compilers(), ...]
endEle regenera a skill quando a versão do ledger_ui instalada difere da registrada no SKILL.md; não faz nada se a
skill ainda não existe, se já está na versão e em :prod.
Showcase
cd showcase
mix deps.get
mix phx.server # http://localhost:4100
Veja CONVENTIONS.md para contribuir com componentes.
Templates
A página "16 · Templates" do canvas virou dez telas inteiras no showcase (as de design/vitrine/t/index.json, na mesma ordem e com os mesmos títulos), montadas só com
componentes da biblioteca e funcionando de verdade (cada uma é uma LiveView, em tela cheia, sem o
chrome do showcase; ?theme=dark escolhe o tema e o botão da lua alterna, com a mesma chave
lu-theme do localStorage; ?palette=crepusculo escolhe a paleta, chave lu-palette). O índice é /templates.
| Rota | Tela | Comportamento |
|---|---|---|
/templates/auth-login | Entrar | e-mail e senha validam no phx-change; senha errada mostra as tentativas que restam e bloqueia na terceira; ana@bompreco.com.br / demo123456 entra |
/templates/auth-login-erro | Entrar com erro | o mesmo login, já com o aviso de credencial incorreta |
/templates/auth-cadastro | Criar conta | três passos; no passo 2 o CNPJ é consultado numa tabela de mentira (12.345.678/0001-90 é encontrado e preenche a empresa) |
/templates/auth-codigo | Código por e-mail | otp_input de seis dígitos (482915 confirma), reenvio com contagem |
/templates/auth-senha | Recuperar a senha | envia o link e mostra o aviso |
/templates/dashboard | Painel | meta, KPIs, faturamento (linha, com Dia/Mês/Ano), vendas por canal (rosca), pedidos e atividade |
/templates/tabela | Pedidos | busca e abas filtram; a seleção das linhas comanda a barra flutuante bulk_bar variant="float" |
/templates/tabela-gaveta | Pedidos · gaveta | a tabela com o detalhe do pedido em drawer layout="page" (/templates/tabela?pedido=2491) |
/templates/tabela-modal | Pedidos · novo pedido | a tabela com o formulário em modal layout="page" (/templates/tabela?novo=1) |
/templates/tabela-app | Pedidos · interativa | a tabela sem seleção: a linha abre o detalhe, as caixas levantam a barra, "Novo pedido" abre o modal e "Emitir NF-e" mostra a transmissão e a autorização (comparada com t/tabela-app.html) |
/templates/auth-login?palette=crepusculo, /templates/dashboard?palette=crepusculo | Crepúsculo | as mesmas telas na paleta Crepúsculo (quadros TCrepAuthLogin, TCrepDashboard) |
/templates/paleta | Paleta Crepúsculo | os tokens por papel, os gradientes e os componentes na paleta (quadro TCrepPaleta) |
Cada tela abre no estado do seu quadro do canvas. O teste test/templates_parity_test.exs compara
o HTML renderizado de cada uma com o quadro Claro e com a página da vitrine (design/vitrine/t/<slug>.html) e confere que o quadro Escuro é o mesmo HTML com
data-theme="dark"; as exceções (controles reais no lugar dos mocks do quadro) estão documentadas
em showcase/test/support/template_parity.ex. O comportamento está em test/templates_live_test.exs.
Novidades de biblioteca que as telas usam: auth_page/1 e auth_art/1 (a tela lu-auth),
bulk_bar variant="float" (lu-bulkfloat), drawer e modal com layout="page" (lu-overlay,
estado no LiveView) e a linha de rótulo + ação (label_aside) dos campos.