Cartões de Hover do Tópico

[denvergeeks]

	Resumo	Exibe cartões de tópico altamente personalizáveis como dicas de ferramentas ao passar o mouse sobre links de tópicos
	Pré-visualização	Github Readme
	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é-visualização ricos ao passar o mouse para links internos de tópicos em tópicos, respostas, listas de tópicos, página inicial de categorias, Categorias de Documentos, quadros Kanban e tópicos sugeridos.

Quando os usuários passam o mouse sobre um link de tópico (ou tocam no celular), um cartão aparece com a miniatura do tópico, título, resumo, categoria, tags e estatísticas principais.

Recursos

• Cartões ao passar o mouse para links internos de tópicos em:
  • Corpo do tópico (post original)
  • Respostas
  • Listas padrão de tópicos (/latest, /top, /tags, listas de tópicos por categoria, etc.)
  • Listas de tópicos na página inicial de categorias (Categorias + Mais recentes, Apenas Categorias e layouts relacionados)
  • Visualizações de Categorias de Documentos
  • Visualizações de quadros no estilo Kanban
  • Tópicos sugeridos
• Layout responsivo:
  • Cartão para desktop com densidade configurável e posicionamento da miniatura
  • Pré-visualização em folha inferior para celular com abertura ao tocar
• Conteúdo configurável:
  • Imagem de miniatura
  • Distintivo de categoria
  • Tags
  • Título
  • Resumo (limpo de imagens/lightboxes)
  • Autor original
  • Data de publicação
  • Visualizações, respostas, curtidas, última atividade
• Opção de exclusão 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é-visualização móvel.

• mobile_width_percent
  Largura da folha de pré-visualização inferior móvel como porcentagem da largura da viewport (padrão: 100).

• mobile_thumbnail_height
  Altura da miniatura em pixels para a pré-visualização 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 simplesmente ajustam o preenchimento 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
  Para layouts left e right no desktop, controla a largura da miniatura como porcentagem da largura 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 resumo (CSS line-clamp).

• show_op / show_op_mobile
  Mostra avatar e nome de usuário do autor 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 por categoria.

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

  • Categorias + Mais recentes
  • 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 em visualizações de Categorias de Documentos (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”.

---

Opção de exclusão 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 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 a correspondência funciona

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 membro da equipe (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 membros da equipe, 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 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 membros da equipe).
• 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

[chapoi]

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