# 画面設計書 42-フレームコンポーネント

## 概要

本ドキュメントは、Laravelフレームワークの例外レンダラーにおけるフレームコンポーネント（frame.blade.php）の画面設計書である。スタックトレースの個別フレーム（呼び出し履歴の1行）を表示し、展開時にはソースコードを表示するBladeコンポーネントについて定義する。

### 本画面の処理概要

**業務上の目的・背景**：例外発生時のスタックトレースにおいて、各フレーム（関数呼び出しの1段階）の詳細情報を提供することは、デバッグ作業の効率化に不可欠である。このコンポーネントは、フレームごとにクラス名、メソッド名、ファイルパス、行番号を表示し、展開することでエラー発生箇所周辺のソースコードを確認できる。特にアプリケーションコード（非ベンダーコード）のフレームについて、開発者が素早くエラー原因を特定できるよう設計されている。

**画面へのアクセス方法**：trace.blade.phpコンポーネントからループ処理で呼び出される。非ベンダーフレームごとに1つのframeコンポーネントがインスタンス化される。直接アクセスするものではなく、例外表示画面の一部として自動的にレンダリングされる。

**主要な操作・処理内容**：
1. フレームのクラス名、メソッド名、引数情報をformatted-sourceコンポーネントで整形表示
2. ファイルパスと行番号をfile-with-lineコンポーネントで表示
3. フレームをクリックすると展開/折りたたみが切り替わる
4. 展開時はframe-codeコンポーネントでソースコードスニペットを表示
5. メインフレーム（最初の非ベンダーフレーム）は初期状態で展開

**画面遷移**：trace.blade.phpの子コンポーネントとして表示。展開時にframe-codeコンポーネントを表示。

**権限による表示制御**：APP_DEBUGがtrueの場合のみ表示される。本番環境では例外詳細画面自体が表示されない。

## 関連機能

| 機能No | 機能名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| 36 | ビューファクトリ | 主機能 | 個別スタックフレームの描画 |

## 画面種別

詳細 / コンポーネント

## URL/ルーティング

直接のURLはなし（親コンポーネントから呼び出されるサブコンポーネント）

## 入出力項目

| 項目名 | 属性名 | 型 | 必須 | 説明 |
|--------|--------|-----|------|------|
| frame | $frame | Frame | 必須 | スタックトレースの1フレーム情報を保持するFrameオブジェクト |

## 表示項目

| 項目名 | 説明 | 表示形式 |
|--------|------|----------|
| ドットインジケーター | フレームの展開状態を示す色付きドット | 円形アイコン（展開時：rose-500、折りたたみ時：rose-200） |
| フォーマットソース | クラス名::メソッド名(引数) の形式 | コード形式テキスト |
| ファイルパス・行番号 | ソースファイルの場所と行番号 | テキスト（クリック可能リンク） |
| 展開/折りたたみボタン | 上下矢印アイコンボタン | SVGアイコン |
| ソースコードスニペット | 展開時に表示されるコード | シンタックスハイライト付きコード |

## イベント仕様

### 1-フレームクリック（展開/折りたたみ）

フレームのヘッダー部分をクリックすると、Alpine.jsで管理されたexpanded状態が切り替わる。ソースコードスニペットが存在する場合のみクリック可能となる。

```javascript
@click="hasCode && (expanded = !expanded)"
```

### 2-エディタリンククリック

ファイルパス部分がエディタリンクとして設定されている場合、クリックするとローカルエディタでファイルを開く（app.editor設定に依存）。

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

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

| 操作（イベント） | 対象テーブル | 操作種別 | 概要 |
|----------------|-------------|---------|------|
| - | - | - | データベース操作なし |

本コンポーネントは表示専用であり、データベースへの更新処理は行わない。

## メッセージ仕様

| 種別 | メッセージ | 表示条件 |
|------|----------|----------|
| - | - | メッセージ表示なし |

## 例外処理

| 例外状況 | 処理内容 |
|----------|----------|
| ソースファイルが読み取り不可 | hasCode=false となり、展開ボタンが非活性化 |
| snippet()が空文字を返す | フレームコードセクションが表示されない |

## 備考

- Alpine.jsのx-dataでexpandedとhasCode状態を管理
- Tailwind CSSでダークモード対応のスタイリング
- メインフレーム（isMain()がtrue）は初期状態でexpanded=true
- Tippyツールチップでソース情報の詳細を表示

---

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

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

### 推奨読解順序

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

フレームオブジェクトの構造とメソッドを理解する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | Frame.php | `src/Illuminate/Foundation/Exceptions/Renderer/Frame.php` | snippet(), isMain(), line(), file(), class(), callable()等のメソッドを理解 |

**読解のコツ**: Frame クラスは Symfony の FlattenException からトレース情報を抽出し、テンプレートで使いやすい形式でデータを提供する。特に snippet() メソッドはエラー行の前後17行を取得する。

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

フレームコンポーネントのテンプレート構造を確認する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | frame.blade.php | `src/Illuminate/Foundation/resources/exceptions/renderer/components/frame.blade.php` | x-dataの初期化、展開ロジック、子コンポーネント呼び出しを理解 |

**主要処理フロー**:
1. **4-7行目**: Alpine.jsのx-dataで状態を初期化（expanded, hasCode）
2. **5行目**: `$frame->isMain()` でメインフレームを判定し、初期展開状態を設定
3. **6行目**: `$frame->snippet()` の有無でコード表示可否を判定
4. **18行目**: クリックイベントで展開状態を切り替え
5. **32行目**: formatted-sourceコンポーネントでソース情報を表示
6. **33行目**: file-with-lineコンポーネントでファイル情報を表示
7. **52-54行目**: 展開時にframe-codeコンポーネントを表示

#### Step 3: 子コンポーネントを理解する

フレームコンポーネントから呼び出される各子コンポーネントの役割を理解する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | formatted-source.blade.php | `src/Illuminate/Foundation/resources/exceptions/renderer/components/formatted-source.blade.php` | クラス名::メソッド名(引数) の整形ロジック |
| 3-2 | file-with-line.blade.php | `src/Illuminate/Foundation/resources/exceptions/renderer/components/file-with-line.blade.php` | ファイルパスと行番号の表示、エディタリンク |
| 3-3 | frame-code.blade.php | `src/Illuminate/Foundation/resources/exceptions/renderer/components/frame-code.blade.php` | ソースコードスニペットの表示 |

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

```
trace.blade.php
    │
    └─ frame.blade.php
           │
           ├─ formatted-source.blade.php
           │      └─ syntax-highlight.blade.php
           │
           ├─ file-with-line.blade.php
           │
           ├─ icons/chevrons-down-up.blade.php
           ├─ icons/chevrons-up-down.blade.php
           │
           └─ frame-code.blade.php (展開時のみ)
                  └─ syntax-highlight.blade.php
```

### データフロー図

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

Frame                     frame.blade.php               HTML出力
(フレームオブジェクト) ───▶ (フレーム情報描画)
    │
    ├─ isMain()       ───▶ expanded初期値
    ├─ snippet()      ───▶ hasCode判定、frame-code表示
    ├─ class()        ─┐
    ├─ callable()      ├──▶ formatted-source表示
    ├─ args()         ─┘
    ├─ file()         ─┐
    └─ line()         ─┴──▶ file-with-line表示
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| frame.blade.php | `src/Illuminate/Foundation/resources/exceptions/renderer/components/frame.blade.php` | テンプレート | 個別フレームのメインコンポーネント |
| Frame.php | `src/Illuminate/Foundation/Exceptions/Renderer/Frame.php` | ソース | フレームデータのラッパークラス |
| formatted-source.blade.php | `src/Illuminate/Foundation/resources/exceptions/renderer/components/formatted-source.blade.php` | テンプレート | ソース情報の整形表示 |
| file-with-line.blade.php | `src/Illuminate/Foundation/resources/exceptions/renderer/components/file-with-line.blade.php` | テンプレート | ファイルパス・行番号表示 |
| frame-code.blade.php | `src/Illuminate/Foundation/resources/exceptions/renderer/components/frame-code.blade.php` | テンプレート | ソースコードスニペット表示 |
| chevrons-down-up.blade.php | `src/Illuminate/Foundation/resources/exceptions/renderer/components/icons/chevrons-down-up.blade.php` | テンプレート | 折りたたみアイコン |
| chevrons-up-down.blade.php | `src/Illuminate/Foundation/resources/exceptions/renderer/components/icons/chevrons-up-down.blade.php` | テンプレート | 展開アイコン |
