トピックホバーカード

[denvergeeks]

	概要	トピックリンクにマウスを合わせたときに、高度にカスタマイズ可能なトピックカードをホバーツールチップとして表示します
	プレビュー	Github Readme
	リポジトリ	https://github.com/denvergeeks/discourse-topic-hover-cards
	インストールガイド	テーマまたはテーマコンポーネントのインストール方法
	Discourse テーマが初めての方へ	Discourse テーマの利用に関する初心者向けガイド

このテーマコンポーネントをインストール

トピック、返信、トピック一覧、カテゴリのホームページ、Doc Categories、カンバンボード、および推奨トピック全体にわたる内部トピックリンクのためのリッチなホバープレビューカード。

ユーザーがトピックリンクにマウスを合わせたとき（モバイルではタップしたとき）、トピックのサムネイル、タイトル、抜粋、カテゴリ、タグ、および主要な統計情報が表示されたカードが表示されます。

機能

• 以下の場所の内部トピックリンク用のホバーカード:
  • トピック本文（最初の投稿）
  • 返信
  • 標準的なトピック一覧（/latest、/top、/tags、カテゴリのトピック一覧など）
  • カテゴリのホームページのトピック一覧（カテゴリ＋最新、カテゴリのみ、関連レイアウトなど）
  • Doc Categories の表示
  • カンバンスタイルのボード表示
  • 推奨トピック
• レスポンシブレイアウト:
  • デスクトップ用カード（設定可能な密度とサムネイル配置）
  • モバイル用ボトムシートプレビュー（タップで開く）
• カスタマイズ可能なコンテンツ:
  • サムネイル画像
  • カテゴリバッジ
  • タグ
  • タイトル
  • 抜粋（画像やライトボックスを除去）
  • 投稿者
  • 公開日
  • 閲覧数、返信数、いいね数、最終アクティビティ
• カスタムユーザーフィールドを使用したユーザーごとのオプトアウト
• 安全なトラブルシューティングのための管理者専用デバッグモード

設定

レイアウトとタイミング

• card_width
  デスクトップ用の任意の CSS 幅値。例：32rem、420px、40vw、clamp(20rem, 40vw, 36rem)。

• card_max_height
  任意の CSS 最大高さ値。例：10rem、480px、50vh、min(60vh, 32rem)。

• card_delay_ms
  ホバーカードを表示するまでの遅延時間（ミリ秒単位）。デフォルト: 300。

• enable_on_mobile
  有効にすると、サポートされている内部トピックリンクをタップするとモバイルプレビューシートが表示されます。

• mobile_width_percent
  モバイルのボトムシートプレビューの幅（ビューポート幅のパーセンテージ）。デフォルト: 100。

• mobile_thumbnail_height
  モバイルプレビューのサムネイルの高さ（ピクセル単位）。

密度

• density
  デスクトップの密度: default、cozy、または compact。

• density_mobile
  モバイルの密度: default、cozy、または compact。

これらは Discourse の「Density」パターンに準拠しており、パディングと行間隔を調整します。

サムネイルと配置

• show_thumbnail / show_thumbnail_mobile
  デスクトップおよびモバイルでのトピック画像（該当する場合）の表示/非表示。

• thumbnail_placement
  デスクトップでのサムネイルの配置方法:

  • top
  • left
  • right
  • bottom
    モバイルでは、サムネイルは常にカードの上部にレンダリングされます。

• image_size_percent
  デスクトップの left および right レイアウトの場合、ホバーカード幅に対するサムネイルの幅をパーセンテージで制御します。

ビューポートごとのフィールド

以下の各ブロックについて、デスクトップとモバイルの両方の切り替えオプションがあります:

• 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
  抜粋の行数（CSS line-clamp）。

• show_op / show_op_mobile
  投稿者のアバターとユーザー名を表示。

• 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

ホバーカードが表示される場所

• enable_on_topics
  最初の投稿内のトピックリンク。

• enable_on_replies
  返信内のトピックリンク。

• enable_on_topic_lists
  標準的なトピック一覧（例：/latest、/top、カテゴリのトピック一覧）内のトピックリンク。

• enable_on_category_homepage_topic_lists
  カテゴリのホームページの「最新トピック」または同等の一覧内のトピックリンク:

  • カテゴリ＋最新トピック
  • カテゴリのみ
  • ホームページの構成に応じて / または /categories でレンダリングされる関連バリエーション。

• enable_on_doc_categories
  Doc Categories 表示内のトピックリンク（該当する場合）。

• enable_on_kanban_boards
  カンバンスタイルのボードレイアウトでレンダリングされるトピックリンク（該当する場合）。

• enable_on_suggested_topic_links
  「推奨トピック」セクション内のリンク。

---

ユーザーごとのオプトアウト

カスタムユーザーフィールドを使用して、個別のユーザーがホバーカードを無効化できるように設定できます。これは、開発者ガイドで説明されている標準的なテーマ設定メカニズムと現在のユーザーデータアクセスを使用します。

• user_preference_field_name
  現在のユーザーのオプトアウトを検出するために使用されるキー。以下のいずれかを使用できます:
  • 直接のカスタムフィールドキー（例：disable_topic_hover_cards）
  • 数値 ID（例：1）
  • user_field_X キー（例：user_field_1）

マッチングの仕組み

1. コンポーネントは、まず現在のユーザーの custom_fields と user_fields を以下についてチェックします:
   • 設定された user_preference_field_name
   • 適切な場合、1 と user_field_1 の間で変換された同じ値
2. マッチが見つからず、現在のユーザーがスタッフ（管理者/モデレーター）で、かつ resolve_user_field_id_for_admins が有効な場合、コンポーネントは以下を呼び出します:
   • /admin/config/user-fields.json
     設定された値（フィールド名または user_field_X）を数値 ID にマッピングします。
3. 数値 ID を使用して、以下をチェックします:
   • user_fields[id]
   • user_fields['user_field_' + id]
   • custom_fields[id]
   • custom_fields['user_field_' + id]

これらの位置のいずれかに真値（例：1、true、yes、on、checked）がある場合、そのユーザーに対してホバーカードが無効化されます。

この動作に関する設定

• resolve_user_field_id_for_admins
  有効にすると（推奨）、管理者はフィールドを名前または user_field_X のいずれかで設定でき、コンポーネントは自動的に数値 ID を解決してマッチングします。

• debug_mode
  有効にすると、スタッフ向けにブラウザコンソールに詳細な検出情報をログ出力します。これには以下が含まれます:

  • チェックされたキー
  • マッチが見つかった場所（現在のユーザー vs 完全なユーザーレコード）
  • 解決された数値ユーザーフィールド ID（該当する場合）

---

デバッグ

ホバーカードが期待通りに表示されない場合は、組み込みのデバッグモードを使用してください:

1. このコンポーネントの設定で debug_mode を有効にします。
2. ブラウザの開発者コンソールを開きます。
3. 関連するトピックリンクにマウスを合わせたりタップしたりします。

以下に似たメッセージが表示されます:

• Hover cards initialized – 初期化と有効な場所の確認。
• Resolved admin user-field mapping – 設定されたユーザーフィールド名/キーから数値 ID へのマッピングの確認（スタッフ向け）。
• No disable field match found anywhere – 現在のユーザーに対してホバーカードが抑制されていないことの確認。

カードが表示される場所をデバッグするには、以下を確認してください:

• ターゲットリンクが topicIdFromHref() で解析可能な内部トピックリンク（/t/...）であること
• 関連する場所フラグが有効であること:
  • 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]

動作するプレビューリンクや、実際の様子がわかるスクリーンショットを追加していただけますか？