Tooltip

Um balão que exibe informação relacionada a um elemento ao receber hover ou foco.

Instalação

O Shadwire segue o modelo open-code do shadcn/ui: o código-fonte do componente é copiado para a sua aplicação e passa a ser seu. Instale com a CLI:

shadwire add tooltip --yes

O item tooltip do registry instala estes arquivos:

app/components/ui_component.rb
app/components/ui/tooltip_component.rb
app/components/ui/tooltip/trigger_component.rb
app/components/ui/tooltip/content_component.rb
app/components/ui/button_component.rb
app/helpers/ui/tooltip_helper.rb
app/helpers/ui/button_helper.rb
app/javascript/controllers/ui_tooltip_controller.js
vendor/shadwire/shadwire.css

Este componente usa Stimulus: a aplicação precisa de importmap-rails e stimulus-rails com carregamento automático de controllers.

Ainda não instalou a CLI? gem install shadwire e depois shadwire init.

Uso

O controller ui-tooltip abre no hover/foco com atraso, liga o gatilho ao balão via aria-describedby e fecha com Esc sem mover o foco (WCAG 1.4.13). O conteúdo vive dentro da raiz, então o ponteiro pode passar por cima dele sem fechar.

<%= ui_tooltip do %>
  <%= ui_tooltip_trigger(variant: :outline) { "Passe o mouse" } %>
  <%= ui_tooltip_content { "Adicionar à biblioteca" } %>
<% end %>

Ou renderize os componentes diretamente:

<%= render Ui::TooltipComponent.new(open_delay: 150) do %>
  <%= render Ui::Tooltip::TriggerComponent.new do %>
    Ajuda
  <% end %>
  <%= render Ui::Tooltip::ContentComponent.new(side: :right) do %>
    Mais detalhes
  <% end %>
<% end %>

Composição

Tooltip (data-controller="ui-tooltip", relative)
|-- Tooltip::Trigger (Button descrito via aria-describedby)
`-- Tooltip::Content (role="tooltip", absolute, side:)

Exemplos

Padrão

Abre no hover e no foco depois de um pequeno atraso; Esc fecha sem mover o foco.

<%= ui_tooltip do %>
  <%= ui_tooltip_trigger(variant: :outline) { "Passe o mouse" } %>
  <%= ui_tooltip_content { "Adicionar à biblioteca" } %>
<% end %>

Lados

side: :top, :right, :bottom ou :left posiciona o balão.

<% { top: "Topo", right: "Direita", bottom: "Base", left: "Esquerda" }.each do |side, label| %>
  <%= ui_tooltip do %>
    <%= ui_tooltip_trigger(variant: :outline) { label } %>
    <%= ui_tooltip_content(side: side) { "Lado #{side}" } %>
  <% end %>
<% end %>

Referência da API

Todas as partes aceitam class / class_name e **attrs.

Componente	Argumento	Padrão	Descrição
`Tooltip`	`open_delay`	`300`	Atraso em milissegundos antes de abrir no hover.
`Tooltip::Trigger`	`variant`, `size`	`:outline`	Encapsula `Ui::ButtonComponent`; ganha `aria-describedby` ao conectar.
`Tooltip::Content`	`side`	`:top`	`:top`, `:right`, `:bottom`, `:left`.