# 画面設計書 40-トップバーコンポーネント

## 概要

本ドキュメントは、Laravelフレームワークの例外レンダラートップバーコンポーネント（topbar.blade.php）の画面設計書である。例外表示画面の最上部に配置され、タイトルとMarkdownコピー機能を提供するコンポーネントについて記述する。

### 本画面の処理概要

トップバーコンポーネントは、例外表示画面の最上部に配置され、エラータイトルの表示と「Copy as Markdown」ボタンによるクリップボードコピー機能を提供するコンポーネントである。

**業務上の目的・背景**：例外発生時、開発者がエラー情報をGitHub Issue、Slack、またはその他のコミュニケーションツールで共有する際、構造化されたMarkdown形式でコピーできることが重要である。本コンポーネントは、ワンクリックで例外情報をMarkdown形式でクリップボードにコピーする機能を提供し、バグ報告の効率化を図る。

**画面へのアクセス方法**：この部品は直接アクセスされるものではなく、show.blade.phpから`<x-laravel-exceptions-renderer::topbar>`コンポーネントとして呼び出される。

**主要な操作・処理内容**：
1. エラータイトル（HTTPステータステキスト）の表示
2. エラーインジケーター（赤い丸にエクスクラメーションマーク）の表示
3. 「Copy as Markdown」ボタンの表示
4. ボタンクリック時にJavaScriptでクリップボードにコピー
5. コピー成功時に「Copied to clipboard」に表示を切り替え

**画面遷移**：本部品は画面遷移の概念を持たない。例外表示画面の一部として表示される。

**権限による表示制御**：特になし。例外表示画面で使用される。

## 関連機能

| 機能No | 機能名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| 36 | ビューファクトリ | 主機能 | 例外画面ナビゲーションの描画 |

## 画面種別

部品（トップバーコンポーネント）

## URL/ルーティング

N/A（コンポーネントのため、URLルーティングは存在しない）

## 入出力項目

| 項目名 | 種別 | データ型 | 必須 | 説明 |
|--------|------|----------|------|------|
| $title | 入力 | string | Yes | エラータイトル（HTTPステータステキスト） |
| $markdown | 入力 | string | Yes | クリップボードにコピーするMarkdown文字列 |

## 表示項目

| 項目名 | 説明 | 表示形式 |
|--------|------|----------|
| エラーインジケーター | 赤い丸にエクスクラメーションマーク | インラインSVG |
| エラータイトル | HTTPステータステキスト | テキスト |
| コピーボタン | Copy as Markdown / Copied to clipboard | ボタン |
| コピーアイコン | クリップボードアイコン | SVGアイコン |
| チェックアイコン | コピー成功時のチェックマーク | SVGアイコン |

## イベント仕様

### 1-Copy as Markdownボタンクリック

ボタンクリック時にAlpine.jsでクリップボードにコピーする。

**処理フロー**:
1. `copyToClipboard()`メソッドが呼び出される
2. `window.copyToClipboard(markdown)`でクリップボードAPIを使用
3. コピー成功時、`copied`フラグをtrueに設定
4. ボタン表示が「Copied to clipboard」に切り替わる
5. 3秒後に`copied`フラグをfalseに戻し、元の表示に戻る
6. コピー失敗時はコンソールにエラーを出力

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

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

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

## メッセージ仕様

| メッセージ | 種別 | 条件 |
|-----------|------|------|
| Copy as Markdown | ボタンラベル | 初期状態・コピー後3秒経過 |
| Copied to clipboard | ボタンラベル | コピー成功後3秒間 |
| Failed to copy the markdown: | コンソールエラー | コピー失敗時 |

## 例外処理

| 例外 | 条件 | 対応 |
|------|------|------|
| クリップボードAPIエラー | ブラウザがAPIをサポートしていない場合 | コンソールにエラー出力 |
| テンプレート未発見 | 部品ファイルが存在しない場合 | Bladeエンジンが例外をスロー |

## 備考

- `@props`ディレクティブで`$title`と`$markdown`を受け取る
- `<script>`タグでmarkdown変数をJavaScriptに渡す（`Illuminate\Support\Js::from()`使用）
- Alpine.jsの`x-data`でコンポーネント状態を管理
- `x-cloak`でAlpine.js初期化前の表示を防止
- `x-show`で状態に応じたアイコン切り替え
- `@class`ディレクティブで動的CSSクラスを適用

---

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

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

### 推奨読解順序

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

トップバーコンポーネントに渡されるデータ構造を理解する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | show.blade.php | `src/Illuminate/Foundation/resources/exceptions/renderer/show.blade.php` | 3行目で`:title`と`:markdown`を渡している |

**読解のコツ**: `$exception->title()`でHTTPステータステキストを、`$exceptionAsMarkdown`でRenderer::render()で生成されたMarkdown文字列を渡している。

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

トップバーコンポーネントの使用箇所を特定する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | Renderer.php | `src/Illuminate/Foundation/Exceptions/Renderer/Renderer.php` | 93-100行目でMarkdown文字列を生成し、show.blade.phpに渡す |

**主要処理フロー**:
1. **93-95行目**: markdown.blade.phpでMarkdown文字列を生成
2. **97-100行目**: `$exceptionAsMarkdown`としてshow.blade.phpに渡す
3. **show.blade.php 3行目**: topbarコンポーネントに`:markdown="$exceptionAsMarkdown"`で渡す

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

topbar.blade.phpの構造を理解する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | topbar.blade.php | `src/Illuminate/Foundation/resources/exceptions/renderer/components/topbar.blade.php` | Alpine.jsによるコピー機能実装（47行） |

**主要処理フロー**:
- **1行目**: `@props(['title', 'markdown'])`でプロパティを受け取る
- **3-5行目**: `<script>`タグでmarkdown変数をJavaScript化
- **7-20行目**: Alpine.js `x-data`でコピー機能を定義
- **22-32行目**: タイトル表示部分（エラーインジケーター + タイトル）
- **34-45行目**: コピーボタン（状態に応じてアイコン・ラベル切り替え）

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

```
Renderer::render()
    │
    ├─ ViewFactory::make('markdown')
    │      └─ markdown.blade.php ───▶ $exceptionAsMarkdown
    │
    └─ ViewFactory::make('show')
           │
           └─ show.blade.php
                  │
                  └─ <x-laravel-exceptions-renderer::topbar>
                         │
                         └─ topbar.blade.php
                                │
                                ├─ <script> markdown = Js::from($markdown)
                                │
                                ├─ x-data="{ copied: false, copyToClipboard() }"
                                │
                                ├─ タイトル表示（$title）
                                │
                                └─ コピーボタン
                                       ├─ @click="copyToClipboard()"
                                       ├─ <x-icons.copy> (x-show="!copied")
                                       └─ <x-icons.check> (x-show="copied")
```

### データフロー図

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

markdown.blade.php ───▶ Renderer::render() ───▶ $exceptionAsMarkdown
        │                      │
        │                      ▼
        │               show.blade.php
        │                      │
        │                      ▼
        │               topbar.blade.php
        │                      │
        └──────────────────────┼─────────────────────────▶ JavaScript変数
                               │
                               ▼
                      [ユーザー操作]
                               │
                               ▼
                      copyToClipboard()
                               │
                               ▼
                      クリップボードAPI
                               │
                               ▼
                      [クリップボードにコピー]
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| topbar.blade.php | `src/Illuminate/Foundation/resources/exceptions/renderer/components/topbar.blade.php` | テンプレート | トップバーコンポーネント |
| Renderer.php | `src/Illuminate/Foundation/Exceptions/Renderer/Renderer.php` | ソース | Markdown生成・受け渡し |
| markdown.blade.php | `src/Illuminate/Foundation/resources/exceptions/renderer/markdown.blade.php` | テンプレート | Markdown形式出力 |
| show.blade.php | `src/Illuminate/Foundation/resources/exceptions/renderer/show.blade.php` | テンプレート | トップバー使用元 |
| copy.blade.php | `src/Illuminate/Foundation/resources/exceptions/renderer/components/icons/copy.blade.php` | テンプレート | コピーアイコン |
| check.blade.php | `src/Illuminate/Foundation/resources/exceptions/renderer/components/icons/check.blade.php` | テンプレート | チェックアイコン |
