B-073 実施計画: 検索結果マッチハイライト

1. 目的と価値

誰のための作業か

サイト内検索を利用する全ての訪問者。検索結果一覧で「なぜこの結果が表示されたのか」を視覚的に把握できるようにする。

提供する価値

• 検索クエリとの一致箇所がハイライト表示されることで、検索結果の関連性を素早く判断できる
• 目的のコンテンツに到達するまでの時間を短縮し、検索体験の満足度を向上させる
• 一般的な検索UIで期待される機能を実装することで、サイトの完成度を上げる

2. 変更対象ファイルと作業内容

ステップ1: Fuse.jsオプションの変更 (src/components/search/useSearch.ts)

変更箇所: FUSE_OPTIONS (35-45行目)

includeMatches: true をオプションに追加する。これにより FuseResult<T> の matches フィールドが有効になる。

変更前:
  threshold: 0.3,
  includeScore: true,
  minMatchCharLength: 1,

変更後:
  threshold: 0.3,
  includeScore: true,
  includeMatches: true,
  minMatchCharLength: 1,

ステップ2: SearchResultItem 型の拡張 (src/components/search/useSearch.ts)

変更箇所: SearchResultItem 型 (12-15行目)

FuseResultMatch 型を fuse.js からインポートし、matches フィールドを追加する。

変更前:
export type SearchResultItem = {
  document: SearchDocument;
  score: number;
};

変更後:
export type SearchResultItem = {
  document: SearchDocument;
  score: number;
  matches: ReadonlyArray<FuseResultMatch>;
};

変更箇所: import文 (4行目)

FuseResultMatch を追加でインポートする。

変更前:
import Fuse, { type IFuseOptions, type FuseResult } from "fuse.js";

変更後:
import Fuse, { type IFuseOptions, type FuseResult, type FuseResultMatch } from "fuse.js";

また、FuseResultMatch を re-export する (SearchResults.tsx から利用するため)。

変更箇所: groupResults 関数内 (59-62行目)

matches 情報を渡す。

変更前:
items.push({
  document: result.item,
  score: result.score ?? 1,
});

変更後:
items.push({
  document: result.item,
  score: result.score ?? 1,
  matches: result.matches ?? [],
});

ステップ3: ハイライトユーティリティの新規作成

新規ファイル: src/components/search/highlightMatches.tsx

以下の2つをエクスポートする:

1. splitByIndices(text: string, indices: ReadonlyArray<RangeTuple>): HighlightSegment[]

   • Fuse.js の indices（[start, end] のペア配列。end は包含）をもとに、テキストをハイライト/非ハイライトのセグメントに分割する純粋関数
   • HighlightSegment は { text: string; highlighted: boolean } 型

2. HighlightedText コンポーネント

   • Props: { text: string; indices: ReadonlyArray<RangeTuple>; className?: string }
   • splitByIndices を使ってセグメントを生成し、ハイライト部分を <mark> 要素でラップする
   • indices が空または未指定の場合はプレーンテキストを返す
   • <mark> を使う理由: HTML5 の意味的に正しい要素であり、スクリーンリーダーでも適切に扱われる

型のインポートは fuse.js から RangeTuple を使用する（エクスポートされていることを確認済み）。

ステップ4: SearchResults.tsx でのハイライト適用

変更箇所: src/components/search/SearchResults.tsx (119-124行目)

HighlightedText コンポーネントと FuseResultMatch 型をインポートし、title と description にハイライトを適用する。

具体的な変更:

• ファイル先頭に import { HighlightedText } from "./highlightMatches" を追加
• fuse.js から type RangeTuple をインポート (または FuseResultMatch を useSearch から re-export して使用)
• ヘルパー関数 getMatchIndices(matches, key) を作成して、特定のキーに対応する indices を取得する
• 120行目の {item.document.title} を <HighlightedText> に置換
• 121-123行目の {item.document.description} を <HighlightedText> に置換
• 124行目の url 表示はハイライト対象外（Fuse.js の検索対象フィールドに含まれていないため）

変更前:
<span className={styles.itemTitle}>{item.document.title}</span>
<span className={styles.itemDescription}>
  {item.document.description}
</span>

変更後:
<span className={styles.itemTitle}>
  <HighlightedText
    text={item.document.title}
    indices={getMatchIndices(item.matches, "title")}
    className={styles.highlight}
  />
</span>
<span className={styles.itemDescription}>
  <HighlightedText
    text={item.document.description}
    indices={getMatchIndices(item.matches, "description")}
    className={styles.highlight}
  />
</span>

getMatchIndices 関数は同ファイル内にヘルパーとして定義する:

function getMatchIndices(
  matches: ReadonlyArray<FuseResultMatch>,
  key: string,
): ReadonlyArray<RangeTuple> {
  const match = matches.find((m) => m.key === key);
  return match?.indices ?? [];
}

ステップ5: CSSスタイルの追加

変更箇所: src/components/search/SearchResults.module.css

ファイル末尾に .highlight クラスを追加する。

.highlight {
  background-color: rgba(37, 99, 235, 0.15);
  color: inherit;
  border-radius: 2px;
  padding: 0 1px;
}

:root.dark .highlight {
  background-color: rgba(96, 165, 250, 0.2);
}

設計判断:

• var(--color-primary) をそのまま背景色にすると視認性が悪いため、半透明のrgbaを使用する
• color: inherit でテキスト色は親要素から継承する（title は白/黒、description は muted を維持）
• ダークモードではやや明るい半透明にする

注意: CSS Modulesを使用しているため、:root.dark .highlight がモジュールスコープ内で機能するか確認が必要。もし機能しない場合は、:global(:root.dark) .highlight の記法を使うか、代替として @media (prefers-color-scheme: dark) を検討する。ただし、このプロジェクトはクラスベースのダークモード切替 (:root.dark) を使っている。CSS Modules内でグローバルセレクタと組み合わせる場合は :global(:root.dark) .highlight と記述する必要がある。

ステップ6: テストの作成と更新

新規ファイル: src/components/search/__tests__/highlightMatches.test.tsx

splitByIndices 関数と HighlightedText コンポーネントの単体テスト:

• splitByIndices のテスト:

  • 空の indices で元のテキスト全体が非ハイライトセグメントになること
  • 先頭にマッチした場合のセグメント分割
  • 末尾にマッチした場合のセグメント分割
  • 中間にマッチした場合のセグメント分割
  • 複数箇所にマッチした場合のセグメント分割
  • テキスト全体がマッチした場合
  • 日本語テキストでの動作確認

• HighlightedText のテスト:

  • indices が空の場合にプレーンテキストが返ること
  • マッチ箇所に <mark> 要素が生成されること
  • className が <mark> に適用されること
  • 非マッチ部分がテキストノードとして残ること

変更ファイル: src/components/search/__tests__/useSearch.test.ts

• 既存テスト「search returns relevant results after index is loaded」(83-108行目) に、matches フィールドが存在することを検証するアサーションを追加する
• 具体的には allItems の各要素に matches プロパティが配列として存在し、少なくとも1つはマッチ情報を持つことを検証する

変更ファイル: src/components/search/__tests__/SearchModal.test.tsx

• 統合テストとして、検索結果にハイライト（<mark> 要素）が表示されることを検証するテストを追加する
• 具体的には setupWithResults の後に document.querySelectorAll('mark') または screen.getAllByRole 等で <mark> 要素の存在を確認する

3. 注意事項

型安全性

• FuseResultMatch と RangeTuple は fuse.js から正式にエクスポートされている型を使用する（確認済み）
• any は使用しない

パフォーマンス

• includeMatches: true の影響は検索速度の1-3%程度であり、実用上問題なし（調査メモより）
• HighlightedText コンポーネントは軽量で、不要な再レンダリングは発生しない
• 追加の外部依存なし

アクセシビリティ

• <mark> 要素は HTML5 で意味的にハイライトを表現する正しい要素
• スクリーンリーダーでも適切に読み上げられる
• color: inherit により、既存のテキストコントラスト比を維持する

ダークモード対応

• ライトモード: rgba(37, 99, 235, 0.15) (primary #2563eb の15%透過)
• ダークモード: rgba(96, 165, 250, 0.2) (primary #60a5fa の20%透過)
• 両方のモードで背景色とのコントラストが十分であることを確認する必要がある

テキスト切り詰めとの共存

• description は text-overflow: ellipsis で切り詰め表示されている（SearchResults.module.css 92-94行目）
• <mark> 要素はインライン要素であるため、ellipsis と共存できる
• ハイライト部分が切り詰めにより見えなくなる場合があるが、これは許容範囲内

4. 完了条件

1. 検索クエリを入力すると、結果一覧の title と description のマッチ箇所がハイライト表示される
2. ライトモード・ダークモードの両方でハイライトが視認できる
3. ハイライトなしの検索結果（matches が空の場合）もこれまで通り正常に表示される
4. 全ての既存テストが引き続きパスする
5. 新規テスト（highlightMatches の単体テスト、useSearch の matches 検証、SearchModal の統合テスト）がパスする
6. npm run lint && npm run format:check && npm run test && npm run build が全て成功する
7. キーボードナビゲーション（ArrowUp/Down、Enter）がこれまで通り動作する

5. 作業の順序

1. highlightMatches.tsx の新規作成とテスト作成 (独立して作業可能)
2. useSearch.ts の型変更とオプション追加
3. useSearch.test.ts の更新
4. SearchResults.tsx のハイライト適用
5. SearchResults.module.css のスタイル追加
6. SearchModal.test.tsx の統合テスト追加
7. 全テスト実行と lint/build 確認