Composição

Helpers só existem para o que está instalado

Cada componente instala o próprio módulo de helper: button grava app/helpers/ui/button_helper.rb, que define Ui::ButtonHelper#ui_button. O Rails inclui automaticamente tudo que está em app/helpers/, então um helper instalado está disponível em todas as views, sem include.

O helper de um componente que não está instalado não existe, e chamá-lo levanta NoMethodError quando a página renderiza. Confira installed[].helpers antes de escrever a view.

bin/shadwire status --json
bin/shadwire add carousel --yes

Subcomponentes são helpers aninhados

Estes componentes não usam slots do ViewComponent nem recebem o conteúdo como argumento. Você os monta aninhando chamadas.

<%# Wrong: these props do not exist %>
<%= ui_card(header: "Time", footer: "Save") %>

<%# Right %>
<%= ui_card do %>
  <%= ui_card_header do %>
    <%= ui_card_title { "Team" } %>
    <%= ui_card_description { "Manage who has access." } %>
  <% end %>
  <%= ui_card_content { "Body" } %>
  <%= ui_card_footer { ui_button { "Save" } } %>

<%# Right %>
<%= ui_card do %>
  <%= ui_card_header do %>
    <%= ui_card_title { "Team" } %>
    <%= ui_card_description { "Manage who has access." } %>
  <% end %>
  <%= ui_card_content { "Body" } %>
  <%= ui_card_footer { ui_button { "Save" } } %>
<% end %>

bin/shadwire info <nome> lista o helper de cada parte. Consulte em vez de chutar: o helper é ui_card_content, e não ui_card_body.

Use a composição inteira

Não coloque tudo numa parte só. Header, title e description renderizam cada um a sua própria marcação, e jogar tudo dentro do content perde isso.

<%# Wrong: everything dumped into the content %>
<%= ui_card do %>
  <%= ui_card_content do %>
    <h3>Team</h3>
    <p>Manage who has access.</p>
  <% end %>
<% end %>

Itens ficam dentro do grupo

<%# Wrong: item rendered straight at the root %>
<%= ui_select do %>
  <%= ui_select_item(value: "a") { "A" } %>
<% end %>

<%# Right %>
<%= ui_select(name: "role", placeholder: "Select a role") do %>
  <%= ui_select_trigger { ui_select_value } %>
  <%= ui_select_content do %>
    <%= ui_select_item(value: "admin") { "Admin" } %>
  <% end %>
<% end %>

O mesmo vale para ui_tabs_trigger dentro de ui_tabs_list, ui_breadcrumb_item dentro de ui_breadcrumb_list e ui_pagination_item dentro de ui_pagination_content.

Overlays sempre precisam de título

dialog, alert-dialog, sheet e drawer precisam do componente de título para que leitores de tela consigam anunciá-los, mesmo quando o layout não mostra um título visível.

<%# Wrong: the dialog has no accessible name %>
<%= ui_dialog_content do %>
  <p>Are you sure?</p>
<% end %>

<%# Right: visually hidden, but announced %>
<%= ui_dialog_content do %>
  <%= ui_dialog_header do %>
    <%= ui_dialog_title(class: "sr-only") { "Confirm deletion" } %>
  <% end %>
  <p>Are you sure?</p>
<% end %>

Componentes interativos precisam de Stimulus

29 dos 57 componentes trazem um controller. O bin/shadwire info <nome> indica quais pelo campo requiresStimulus, e status.stack diz se o app tem importmap e stimulus-rails.

Os controllers são instalados em app/javascript/controllers/ e se registram pelo eagerLoadControllersFrom("controllers", application) do controllers/index.js. Se o seu app registra controllers explicitamente, registre os novos lá também.

Renderizando a classe diretamente

O helper só embrulha a classe, então as duas formas renderizam a mesma coisa:

<%= ui_button(variant: :outline) { "Save" } %>
<%= render Ui::ButtonComponent.new(variant: :outline) do %>Save<% end %>

Nas views, use o helper. Use a classe quando precisar do próprio objeto do componente, ou dentro de outro ViewComponent. ViewComponents não recebem helpers automaticamente, então inclua o módulo para chamar ui_button no template do componente:

class DashboardCardComponent < ViewComponent::Base
  # Components do not get helpers automatically.
  include Ui::ButtonHelper
end