# 画面設計書 7-TableOfContents画面

## 概要

本ドキュメントは、Wikipedia iOSアプリのTableOfContents画面（目次画面）の設計仕様を記載したものである。

### 本画面の処理概要

TableOfContents画面は、記事の目次を表示し、セクションへのナビゲーションを提供する画面である。インラインモード（サイドパネル）とモーダルモードの2つの表示形式に対応。

**業務上の目的・背景**：ユーザーが長い記事内を効率的にナビゲートできるようにする。目次を通じて記事の構造を把握し、目的のセクションへ素早くジャンプできる。iPad/横向き表示ではインラインで常時表示し、コンパクト表示ではモーダルで表示。

**画面へのアクセス方法**：Article画面のツールバーにある目次ボタン（目次アイコン）をタップ。iPad横向きでは自動的にインライン表示。

**主要な操作・処理内容**：
1. 目次項目の一覧表示
2. 目次項目タップによるセクションへのスクロール
3. 現在表示中セクションのハイライト表示
4. スワイプジェスチャーによる目次閉じる操作
5. 背景タップによる目次閉じる操作（モーダル時）

**画面遷移**：
- 遷移元：Article画面
- 遷移先：なし（セクションスクロールのみ）

**権限による表示制御**：なし

## 関連機能

| 機能No | 機能名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| 2 | 目次ナビゲーション | 主機能 | 目次の表示とセクションへのジャンプ |
| 1 | 記事閲覧 | 親機能 | Article画面との連携 |

## 画面種別

一覧（サイドパネル/モーダル）

## URL/ルーティング

- エントリーポイント：`ArticleTableOfContentsDisplayController`経由
- Storyboard ID：`TableOfContentsViewController`

## 入出力項目

| 項目名 | 入力/出力 | データ型 | 説明 |
|--------|----------|----------|------|
| 目次項目 | 入力 | [TableOfContentsItem] | delegate?.tableOfContentsItems |
| 表示モード | 入力 | TableOfContentsDisplayMode | .inline / .modal |
| 表示サイド | 入力 | TableOfContentsDisplaySide | .left / .right |
| 選択項目インデックス | 入出力 | Int | indexOfSelectedItem |

## 表示項目

| 項目名 | データソース | 表示条件 | 備考 |
|--------|-------------|----------|------|
| 目次ヘッダー | TableOfContentsHeader | 常時 | 「Contents」ラベル |
| 目次項目セル | TableOfContentsCell | 常時 | 階層インデント付き |
| セクションタイトル | TableOfContentsItem.titleHTML | 常時 | HTMLフォーマット対応 |
| 選択インジケータ | - | 選択中項目 | ハイライト表示 |

## イベント仕様

### 1-目次項目タップ

UITableViewDelegateの`tableView(_:didSelectRowAt:)`で処理。`selectItem(at:)`で選択状態を更新し、`delegate?.tableOfContentsController(_:didSelectItem:)`でArticleViewControllerに選択を通知。

**ソースコード参照**: TableOfContentsViewController.swift 行281-286（didSelectRowAt）

### 2-スワイプ閉じる

`closeGestureRecognizer`（UISwipeGestureRecognizer）でスワイプを検出。displaySideに応じて左/右スワイプで閉じる。`handleTableOfContentsCloseGesture`で`delegate?.tableOfContentsControllerDidCancel`を呼び出し。

**ソースコード参照**: TableOfContentsViewController.swift 行62-67（handleTableOfContentsCloseGesture）

### 3-背景タップ閉じる

モーダル表示時、`TableOfContentsAnimator`が背景タップを検出し`tableOfContentsAnimatorDidTapBackground`デリゲートメソッドを呼び出し。

**ソースコード参照**: TableOfContentsViewController.swift 行296-298

### 4-選択項目更新

`selectItem(at:)`で選択インデックスを更新。関連項目（親セクション）も同時にハイライト対象に追加。`indiciesOfHighlightedItems`セットで管理し、該当行のみ再描画。

**ソースコード参照**: TableOfContentsViewController.swift 行120-152（selectItem関数）

### 5-スクロール同期

`scrollToItem(at:)`で選択項目がTableView内で表示されるようスクロール。既に表示されている場合はスクロールしない。インラインモードではアニメーション付き。

**ソースコード参照**: TableOfContentsViewController.swift 行154-168（scrollToItem関数）

## データベース更新仕様

### 操作別データベース影響一覧

| 操作（イベント） | 対象テーブル | 操作種別 | 概要 |
|----------------|-------------|---------|------|
| なし | - | - | この画面ではデータベース更新なし |

## メッセージ仕様

| メッセージID | メッセージ内容 | 表示条件 | 種別 |
|-------------|---------------|----------|------|
| なし | - | - | この画面固有のメッセージなし |

## 例外処理

- **アイテム範囲外アクセス**：`selectItem`、`scrollToItem`でインデックスが範囲外の場合assertionFailureで開発時検出
- **デリゲート未設定**：delegateがnilの場合、操作を無視して安全に処理

## 備考

- TableOfContentsViewControllerはUIViewController、UITableViewDelegate、UITableViewDataSource、Themeableを実装
- TableOfContentsAnimatorでカスタムトランジションを実装
- UITableView.Style.groupedを使用してヘッダーのスクロール追従を実現
- VoiceOver対応で選択セルにaccessibilityTraits.selectedを設定
- semanticContentAttributeでRTL言語対応

---

## コードリーディングガイド

本画面を理解するために参照すべきファイルと、推奨する読み解き順序を以下に示す。

### 推奨読解順序

#### Step 1: データ構造を理解する

目次項目のデータモデルを理解。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | TableOfContentsItem.swift | `Wikipedia/Code/TableOfContentsItem.swift` | id, titleHTML, indentationLevel, itemType |
| 1-2 | TableOfContentsDisplayMode enum | `TableOfContentsViewController.swift 行4-7` | .inline / .modal |

**読解のコツ**: TableOfContentsItemのindentationLevelがセクション階層を表す。

#### Step 2: エントリーポイントを理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | TableOfContentsViewController.swift | `Wikipedia/Code/TableOfContentsViewController.swift` | 全体325行 |

**主要処理フロー**:
1. **行95-102 init**: delegate、theme、displaySideを初期化、modalPresentationStyle設定
2. **行178-215 viewDidLoad**: UITableView設定、closeGestureRecognizer設定
3. **行217-220 viewWillAppear**: delegate?.tableOfContentsControllerWillDisplay呼び出し

#### Step 3: 表示制御層を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | ArticleTableOfContentsDisplayController.swift | `Wikipedia/Code/` | 親VCからの表示制御 |
| 3-2 | TableOfContentsAnimator.swift | `Wikipedia/Code/` | カスタムトランジション |

#### Step 4: UIコンポーネントを理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 4-1 | TableOfContentsCell.swift | `Wikipedia/Code/` | 目次セルのカスタムUI |
| 4-2 | TableOfContentsHeader.swift | `Wikipedia/Code/` | 目次ヘッダービュー |

### プログラム呼び出し階層図

```
ArticleViewController
    │
    └─ ArticleTableOfContentsDisplayController
           │
           └─ TableOfContentsViewController
                  │
                  ├─ UITableView
                  │      ├─ TableOfContentsHeader (section header)
                  │      └─ TableOfContentsCell (rows)
                  │
                  ├─ TableOfContentsAnimator (modal transition)
                  │
                  └─ UISwipeGestureRecognizer (close gesture)
```

### データフロー図

```
[入力]               [処理]                    [出力]

Article Sections ───▶ TableOfContentsItem[] ───▶ UITableView
                           │
Scroll Position ───────▶ selectItem(at:) ───▶ Cell Highlight
                           │
Cell Tap ─────────────▶ didSelectRowAt ───▶ Delegate.didSelectItem
                           │
                           ▼
                    ArticleViewController.scroll(to:)
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| TableOfContentsViewController.swift | `Wikipedia/Code/` | ソース | メインViewController（325行） |
| TableOfContentsItem.swift | `Wikipedia/Code/` | ソース | 目次項目モデル |
| TableOfContentsCell.swift | `Wikipedia/Code/` | ソース | 目次セル |
| TableOfContentsHeader.swift | `Wikipedia/Code/` | ソース | 目次ヘッダー |
| TableOfContentsAnimator.swift | `Wikipedia/Code/` | ソース | トランジションアニメーター |
| ArticleTableOfContentsDisplayController.swift | `Wikipedia/Code/` | ソース | 表示制御コントローラ |
| TableOfContentsViewControllerDelegate.swift | `Wikipedia/Code/` | ソース | デリゲートプロトコル（同ファイル内） |
