B-073 調査レポート: 検索結果マッチハイライトの実装方法

1. 検索コンポーネントの場所と構造

検索機能は以下のファイルで構成されている。

コンポーネント一覧

ファイル	役割	重要な行番号
`src/components/search/SearchTrigger.tsx`	検索ボタン (Cmd+K) とモーダル開閉制御	全89行
`src/components/search/SearchModal.tsx`	モーダル本体、キーボードナビ	全141行
`src/components/search/SearchInput.tsx`	検索入力フィールド (combobox)	全77行
`src/components/search/SearchResults.tsx`	検索結果の表示 (グループ別)	全132行
`src/components/search/useSearch.ts`	Fuse.jsラッパーhook (インデックス読込、検索実行、デバウンス)	全164行
`src/lib/search/types.ts`	SearchDocument型、ContentType、定数定義	全48行

CSSモジュール

ファイル	対象コンポーネント
`src/components/search/SearchModal.module.css`	SearchModal
`src/components/search/SearchInput.module.css`	SearchInput
`src/components/search/SearchResults.module.css`	SearchResults
`src/components/search/SearchTrigger.module.css`	SearchTrigger

テストファイル

ファイル	テスト対象
`src/components/search/__tests__/SearchModal.test.tsx`	モーダル表示、キーボードナビ (291行)
`src/components/search/__tests__/useSearch.test.ts`	useSearchフック (193行)

データフロー

SearchTrigger (開閉制御)
  -> SearchModal (モーダル本体)
    -> useSearch() hook (Fuse.jsの管理)
    -> SearchInput (入力)
    -> SearchResults (結果表示)

2. Fuse.jsの現在の設定

バージョン

fuse.js v7.1.0 (package.json: "fuse.js": "^7.1.0")

現在のFuse.jsオプション (`useSearch.ts` 35-45行)

const FUSE_OPTIONS: IFuseOptions<SearchDocument> = {
  keys: [
    { name: "title", weight: 2.0 },
    { name: "keywords", weight: 1.5 },
    { name: "description", weight: 1.0 },
    { name: "extra", weight: 0.5 },
  ],
  threshold: 0.3,
  includeScore: true,
  minMatchCharLength: 1,
};

重要な点

includeMatches は未設定 (デフォルト: false) -- これを true にする必要がある
findAllMatches も未設定 (デフォルト: false) -- 完全マッチ後もパターン末尾まで検索を続行させたい場合は true にする

現在の結果型 (`useSearch.ts` 12-15行)

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

matches情報は現在保持されていない

3. Fuse.jsのmatches情報の構造

型定義 (`node_modules/fuse.js/dist/fuse.d.ts` 344-362行)

type RangeTuple = [number, number]; // [startIndex, endIndex] (endは包含)

type FuseResultMatch = {
  indices: ReadonlyArray<RangeTuple>; // マッチした文字範囲の配列
  key?: string;      // マッチしたフィールド名 ("title", "description"等)
  refIndex?: number;  // 配列フィールドの場合のインデックス
  value?: string;     // マッチした元のテキスト全体
};

type FuseResult<T> = {
  item: T;
  refIndex: number;
  score?: number;
  matches?: ReadonlyArray<FuseResultMatch>; // includeMatches: true で有効
};

具体的なmatches構造例

クエリ「漢字」で title: "漢字カナール" がマッチした場合:

{
  "item": { "id": "game:kanji-kanaru", "title": "漢字カナール", ... },
  "score": 0.01,
  "matches": [
    {
      "indices": [[0, 1]],
      "key": "title",
      "value": "漢字カナール"
    },
    {
      "indices": [[0, 1]],
      "key": "keywords",
      "value": "漢字",
      "refIndex": 0
    }
  ]
}

indices の各要素は [start, end] で、endは包含 (inclusive)
複数箇所にマッチする場合は indices 配列に複数のタプルが入る
keywords のような配列フィールドでは refIndex で何番目の要素かを示す

4. Reactでのハイライト表示の実装パターン

選択肢の比較

アプローチ	メリット	デメリット
A. 自前実装 (推奨)	依存ゼロ、完全なコントロール、軽量、型安全	自分で書く必要がある (ただし50行程度)
B. react-fuzzy-highlighter	既存ライブラリ	3年以上更新なし、React 19との互換性不明、余計な依存
C. dangerouslySetInnerHTML	実装が単純	XSSリスク、Reactアンチパターン

推奨: 自前実装 (アプローチA)

プロジェクトの設計方針 (シンプルで依存が少ない) に最も合致する。実装量も少なく、型安全に作れる。

ハイライトユーティリティ関数の設計案

// src/components/search/highlightMatches.tsx
import type { ReactNode } from "react";
import type { RangeTuple } from "fuse.js";

type HighlightSegment = {
  text: string;
  highlighted: boolean;
};

/**
 * Fuse.jsのindices情報からテキストをハイライト/非ハイライトの
 * セグメントに分割する
 */
export function splitByIndices(
  text: string,
  indices: ReadonlyArray<RangeTuple>,
): HighlightSegment[] {
  const segments: HighlightSegment[] = [];
  let lastEnd = 0;

  // indicesはソート済みであることが前提
  for (const [start, end] of indices) {
    // マッチ前の非ハイライト部分
    if (start > lastEnd) {
      segments.push({ text: text.slice(lastEnd, start), highlighted: false });
    }
    // マッチ部分 (endは包含なので+1)
    segments.push({ text: text.slice(start, end + 1), highlighted: true });
    lastEnd = end + 1;
  }

  // 残りの非ハイライト部分
  if (lastEnd < text.length) {
    segments.push({ text: text.slice(lastEnd), highlighted: false });
  }

  return segments;
}

/**
 * テキストのハイライトセグメントをReact要素に変換する
 */
export function HighlightedText({
  text,
  indices,
  className,
}: {
  text: string;
  indices: ReadonlyArray<RangeTuple>;
  className?: string;
}): ReactNode {
  if (!indices || indices.length === 0) {
    return text;
  }

  const segments = splitByIndices(text, indices);
  return (
    <>
      {segments.map((seg, i) =>
        seg.highlighted ? (
          <mark key={i} className={className}>
            {seg.text}
          </mark>
        ) : (
          seg.text
        ),
      )}
    </>
  );
}

SearchResultItemに matches情報を追加する設計案

// useSearch.ts の変更箇所

// 型にmatches情報を追加
export type SearchResultItem = {
  document: SearchDocument;
  score: number;
  matches: ReadonlyArray<FuseResultMatch>; // 追加
};

// FUSE_OPTIONSに追加
const FUSE_OPTIONS: IFuseOptions<SearchDocument> = {
  // ...既存の設定
  includeMatches: true,  // 追加
};

// groupResults内でmatchesを保持
items.push({
  document: result.item,
  score: result.score ?? 1,
  matches: result.matches ?? [],  // 追加
});

SearchResults.tsxでのハイライト適用案

// SearchResults.tsx の変更箇所

import { HighlightedText } from "./highlightMatches";

// 特定のキーに対するmatchesからindicesを取得するヘルパー
function getMatchIndices(
  matches: ReadonlyArray<FuseResultMatch>,
  key: string,
): ReadonlyArray<RangeTuple> | null {
  const match = matches.find((m) => m.key === key);
  return match?.indices ?? null;
}

// 結果表示部分の変更
<span className={styles.itemTitle}>
  {titleIndices ? (
    <HighlightedText
      text={item.document.title}
      indices={titleIndices}
      className={styles.highlight}
    />
  ) : (
    item.document.title
  )}
</span>
<span className={styles.itemDescription}>
  {descIndices ? (
    <HighlightedText
      text={item.document.description}
      indices={descIndices}
      className={styles.highlight}
    />
  ) : (
    item.document.description
  )}
</span>

ハイライトのCSS

/* SearchResults.module.css に追加 */
.highlight {
  background-color: var(--color-primary);
  color: var(--color-bg);
  border-radius: 2px;
  padding: 0 1px;
}

5. 既存の検索結果表示ロジックの概要

現在の表示フロー

useSearch hookがFuse.jsで検索し、FuseResult<SearchDocument>[] を取得
groupResults() 関数で結果をContentType別にグルーピング
各グループは CONTENT_TYPE_ORDER の順番で並べられる
各グループ内は最大 MAX_ITEMS_PER_GROUP (5件) まで表示
SearchResults コンポーネントが各グループを描画
各アイテムは title, description, url の3行で表示 (SearchResults.tsx 119-124行)
現在は全てプレーンテキストとして表示されている (ハイライトなし)

キーボードナビゲーション

flattenItems() で全アイテムを1次元配列に変換し、ArrowUp/Downでインデックス移動
アクティブなアイテムは styles.itemActive CSSクラスが適用される
Enterで選択して router.push() でナビゲーション

6. 推奨する実装アプローチ

ステップ1: Fuse.jsオプションに `includeMatches: true` を追加

場所: src/components/search/useSearch.ts の FUSE_OPTIONS (35-45行)
影響: FuseResult<T> に matches フィールドが含まれるようになる

ステップ2: `SearchResultItem` 型に `matches` を追加

場所: src/components/search/useSearch.ts の SearchResultItem 型 (12-15行)
場所: groupResults() 関数 (47-80行) でmatchesを渡す

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

新規ファイル: src/components/search/highlightMatches.tsx
関数: splitByIndices() と HighlightedText コンポーネント
テスト: src/components/search/__tests__/highlightMatches.test.tsx

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

場所: src/components/search/SearchResults.tsx (119-124行)
title と description の表示にハイライトを適用
url はハイライト対象外 (検索対象フィールドでないため)

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

場所: src/components/search/SearchResults.module.css
ダークモード/ライトモード両方での視認性を確認

ステップ6: テスト更新

useSearch.test.ts: matches情報が含まれることを検証
SearchModal.test.tsx: ハイライト表示の統合テスト
highlightMatches.test.tsx: ユーティリティの単体テスト

7. 注意点・リスク

低リスク

パフォーマンス: includeMatches: true はFuse.jsの検索速度にほとんど影響しない (ベンチマークによると1-3%程度の差)
バンドルサイズ: 自前実装のため追加の依存なし。HighlightedTextは50行程度

中リスク

配列フィールド (keywords) のハイライト: keywordsは画面に表示されていないためハイライト不要だが、将来表示する場合は refIndex の考慮が必要
既存テストへの影響: SearchResultItem 型の変更により、テスト内でmatchesフィールドのモックが必要になる可能性がある

要確認事項

ダークモード: <mark> 要素のデフォルトスタイルはブラウザ依存 (通常は黄色背景)。CSS Modulesでカスタムスタイルを必ず指定すること
アクセシビリティ: <mark> 要素は意味的に「ハイライト」を表すHTML5要素であり、スクリーンリーダーでも適切に読み上げられる。<span> より <mark> が推奨される
テキスト切り詰め: descriptionは text-overflow: ellipsis で切り詰め表示されている (SearchResults.module.css 92-94行)。ハイライト部分が切り詰められる可能性があるが、これは許容範囲内

参考情報源

Fuse.js公式ドキュメント: https://www.fusejs.io/api/options.html
Fuse.js型定義: node_modules/fuse.js/dist/fuse.d.ts (344-362行)
Fuse.jsハイライト実装パターン: https://gist.github.com/evenfrost/1ba123656ded32fb7a0cd4651efd4db0

B-073 調査レポート: 検索結果マッチハイライトの実装方法

1. 検索コンポーネントの場所と構造

コンポーネント一覧

CSSモジュール

テストファイル

データフロー

2. Fuse.jsの現在の設定

バージョン

現在のFuse.jsオプション (useSearch.ts 35-45行)

重要な点

現在の結果型 (useSearch.ts 12-15行)

3. Fuse.jsのmatches情報の構造

型定義 (node_modules/fuse.js/dist/fuse.d.ts 344-362行)

具体的なmatches構造例

4. Reactでのハイライト表示の実装パターン

選択肢の比較

推奨: 自前実装 (アプローチA)

ハイライトユーティリティ関数の設計案

SearchResultItemに matches情報を追加する設計案

SearchResults.tsxでのハイライト適用案

ハイライトのCSS

5. 既存の検索結果表示ロジックの概要

現在の表示フロー

キーボードナビゲーション

6. 推奨する実装アプローチ

ステップ1: Fuse.jsオプションに includeMatches: true を追加

ステップ2: SearchResultItem 型に matches を追加

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

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

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

ステップ6: テスト更新

7. 注意点・リスク

低リスク

中リスク

要確認事項

参考情報源

現在のFuse.jsオプション (`useSearch.ts` 35-45行)

現在の結果型 (`useSearch.ts` 12-15行)

型定義 (`node_modules/fuse.js/dist/fuse.d.ts` 344-362行)

ステップ1: Fuse.jsオプションに `includeMatches: true` を追加

ステップ2: `SearchResultItem` 型に `matches` を追加