Cartões de Hover de Tópicos

[denvergeeks]

	Resumo	Fornece popups estilo dica de ferramenta ao passar o mouse (ou tocar no celular) sobre links internos de tópicos, mostrando uma prévia rápida do conteúdo do tópico vinculado.
	Prévia	Leia-me do GitHub
	Repositório	https://github.com/denvergeeks/discourse-topic-hover-cards
	Guia de Instalação	Como instalar um tema ou componente de tema
	Novo em Temas do Discourse?	Guia para iniciantes sobre o uso de Temas do Discourse

Instale este componente de tema

Cartões de prévia ricos ao passar o mouse para links internos de tópicos em tópicos, respostas, listas de tópicos, páginas iniciais de categorias, categorias de documentação, quadros Kanban e tópicos sugeridos. Para Desktop e/ou Celular. Em todo o site e altamente configurável.

Funcionalidades

• Pode ser ativado em todo o site para todos os links internos de tópicos, ou apenas aqueles que aparecem em uma ou mais áreas, incluindo:
  • Corpo do tópico (post original)
  • Respostas
  • Listas padrão de tópicos (/latest, /top, /tags, listas de tópicos de categoria, etc.)
  • Listas de tópicos na página inicial de categorias (Categorias + Últimos, Apenas Categorias e layouts relacionados)
  • Visualizações de Categorias de Documentação
  • Visualizações de quadros no estilo Kanban
  • Tópicos sugeridos
• Layout responsivo:
  • Cartão para Desktop com densidade configurável e posicionamento de miniatura
  • Prévia em folha inferior para celular com toque para abrir
• Conteúdo configurável:
  • Imagem de miniatura
  • Insígnia da categoria
  • Etiquetas (tags)
  • Título
  • Trecho (limpo de imagens/lightboxes)
  • Postador original
  • Data de publicação
  • Visualizações, respostas, curtidas, última atividade
• Exclusão opcional por usuário usando um campo de usuário personalizado
• Modo de depuração apenas para administradores para solução de problemas segura

Configurações

Layout e tempo

• card_width
  Qualquer valor de largura CSS (para desktop), por exemplo, 32rem, 420px, 40vw, clamp(20rem, 40vw, 36rem).

• card_max_height
  Qualquer valor de altura máxima CSS, por exemplo, 10rem, 480px, 50vh, min(60vh, 32rem).

• card_delay_ms
  Atraso antes de mostrar o cartão ao passar o mouse, em milissegundos (padrão: 300).

• enable_on_mobile
  Quando ativado, tocar em um link interno de tópico compatível exibe uma folha de prévia móvel fixada na parte inferior da tela.

• mobile_width_percent
  Largura da prévia em folha inferior móvel como porcentagem da largura da viewport (padrão: 100).

• mobile_thumbnail_height
  Altura da miniatura em pixels para a prévia móvel.

Densidade

• density
  Densidade para Desktop: default, cozy ou compact.

• density_mobile
  Densidade para Celular: default, cozy ou compact.

Estas são paralelas aos padrões de “Densidade” do Discourse e apenas ajustam o espaçamento e as alturas das linhas.

Miniatura e posicionamento

• show_thumbnail / show_thumbnail_mobile
  Mostrar/ocultar a imagem do tópico (se houver) no desktop e no celular.

• thumbnail_placement
  Como a miniatura é posicionada no desktop:

  • top
  • left
  • right
  • bottom
    No celular, a miniatura é sempre renderizada no topo do cartão.

• image_size_percent
  Controla o tamanho da miniatura como uma porcentagem do tamanho renderizado do cartão ao passar o mouse.

Campos por viewport

Para cada bloco abaixo, você tem alternadores tanto para desktop quanto para celular:

• show_category / show_category_mobile

• show_tags / show_tags_mobile

• show_title / show_title_mobile

• show_excerpt / show_excerpt_mobile

• excerpt_length / excerpt_length_mobile
  Número de linhas para o trecho (usa line-clamp do CSS).

• show_op / show_op_mobile
  Mostra avatar e nome de usuário do postador original.

• show_publish_date / show_publish_date_mobile

• show_views / show_views_mobile

• show_reply_count / show_reply_count_mobile

• show_likes / show_likes_mobile

• show_activity / show_activity_mobile

Onde os cartões ao passar o mouse aparecem

• enable_on_topics
  Links de tópicos no post original.

• enable_on_replies
  Links de tópicos nas respostas.

• enable_on_topic_lists
  Links de tópicos em listas padrão de tópicos, por exemplo, /latest, /top, listas de tópicos de categoria.

• enable_on_category_homepage_topic_lists
  Links de tópicos nas listas de “últimos tópicos” ou equivalentes na página inicial de categorias:

  • Categorias + Últimos Tópicos
  • Apenas Categorias
  • Variantes relacionadas renderizadas em / ou /categorias, dependendo de como sua página inicial está configurada.

• enable_on_doc_categories
  Links de tópicos nas visualizações de Categorias de Documentação (quando aplicável).

• enable_on_kanban_boards
  Links de tópicos renderizados em layouts de quadros no estilo Kanban (quando aplicável).

• enable_on_suggested_topic_links
  Links na seção “Tópicos sugeridos”.

---

Exclusão opcional por usuário

Você pode permitir que usuários individuais desativem os cartões ao passar o mouse usando um campo de usuário personalizado. Isso usa o mecanismo padrão de configurações de tema e o acesso aos dados do usuário atual descritos nos guias de desenvolvedor.

• user_preference_field_name
  A chave usada para detectar a exclusão opcional no usuário atual. Isso pode ser:
  • uma chave de campo personalizado direta, por exemplo, disable_topic_hover_cards
  • um ID numérico, por exemplo, 1
  • uma chave user_field_X, por exemplo, user_field_1

Como funciona a correspondência

1. O componente primeiro verifica os custom_fields e user_fields do usuário atual para:
   • o user_preference_field_name configurado
   • o mesmo valor convertido entre 1 e user_field_1 quando apropriado
2. Se nenhuma correspondência for encontrada e o usuário atual for funcionário (administrador/moderador) e
   resolve_user_field_id_for_admins estiver ativado, o componente chama:
   • /admin/config/user-fields.json
     para mapear o valor configurado (nome do campo ou user_field_X) para seu ID numérico.
3. Com o ID numérico, ele verifica:
   • user_fields[id]
   • user_fields['user_field_' + id]
   • custom_fields[id]
   • custom_fields['user_field_' + id]

Qualquer valor verdadeiro nessas posições (por exemplo, 1, true, yes, on, checked) desativa os cartões ao passar o mouse para aquele usuário.

Configurações para este comportamento

• resolve_user_field_id_for_admins
  Quando ativado (recomendado), administradores podem configurar o campo por nome ou user_field_X, e o componente resolverá e corresponderá o ID numérico automaticamente.

• debug_mode
  Quando ativado, registra informações detalhadas de detecção no console do navegador para funcionários, incluindo:

  • quais chaves foram verificadas
  • onde uma correspondência foi encontrada (usuário atual vs registro completo do usuário)
  • o ID numérico do campo de usuário resolvido, se houver

---

Depuração

Se os cartões ao passar o mouse não aparecerem onde você espera, use o modo de depuração integrado:

1. Ative o debug_mode nas configurações deste componente.
2. Abra o console de desenvolvedor do navegador.
3. Passe o mouse ou toque em um link de tópico relevante.

Você verá mensagens semelhantes a:

• Hover cards initialized – confirma a inicialização e os locais ativados.
• Resolved admin user-field mapping – confirma o mapeamento do nome/chave do campo de usuário configurado para um ID numérico (para funcionários).
• No disable field match found anywhere – confirma que os cartões ao passar o mouse não estão sendo suprimidos para o usuário atual.

Para depurar onde o cartão deve aparecer, verifique se:

• seu link de destino é um link interno de tópico (/t/...) que topicIdFromHref() pode analisar
• a flag de localização relevante está ativada:
  • enable_on_topics
  • enable_on_replies
  • enable_on_topic_lists
  • enable_on_category_homepage_topic_lists
  • enable_on_doc_categories
  • enable_on_kanban_boards
  • enable_on_suggested_topic_links

Configurações Planejadas e Funcionalidades Ainda Não Adicionadas:

• Etiquetas Excluídas
• Etiquetas Incluídas
• Classes Excluídas
• Classes Incluídas
• Excluir OneBoxes e outros por padrão
• Sugestões??

[chapoi]

Você poderia adicionar um link de pré-visualização funcional ou algumas capturas de tela para mostrar como isso fica?