# 画面設計書 69-LaravelASCIIアイコン

## 概要

本ドキュメントは、Laravelフレームワークの例外レンダラーで使用されるLaravel ASCIIアイコンコンポーネントの設計仕様を記述したものである。

### 本画面の処理概要

Laravel ASCIIアイコンは、例外レンダラー画面のフッター部分に表示されるLaravelのロゴをASCIIアート風に表現したSVGコンポーネントである。SVGのパス定義とJavaScriptによる動的なグリッド生成を組み合わせて、「LARAVEL」の文字をドットマトリクス形式で描画する。スポットライトエフェクトと組み合わせて使用され、マウスカーソルに追従するインタラクティブなビジュアル効果を提供する。

**業務上の目的・背景**：例外レンダラー画面は開発者向けのデバッグツールであるが、同時にLaravelフレームワークのブランディング要素も含んでいる。Laravel ASCIIアイコンは、画面下部でLaravelのブランドを視覚的に表現しつつ、スポットライトエフェクトによるインタラクティブな体験を提供する。これにより、デバッグ中の開発者に対してフレームワークの存在感を示しながら、視覚的な楽しさも提供する。

**画面へのアクセス方法**：このアイコンは単独で表示されるものではなく、例外レンダラー画面（show.blade.php）内のLaravelアスキースポットライトコンポーネント（laravel-ascii-spotlight.blade.php）で使用される。通常のユニットテストやコンソール実行時には表示されない。

**主要な操作・処理内容**：
1. SVGエレメントの初期描画（defsセクションとスクリプト）
2. JavaScriptによるASCIIアートグリッドの動的生成
3. SVGのuse要素を利用したキャラクター配置
4. `currentColor`を使用した親要素の文字色継承

**画面遷移**：本コンポーネントは独立した画面ではなく、例外レンダラーのスポットライトコンポーネント内で部品として使用される。2つのインスタンスが重ねて配置され、マウスカーソル位置に応じてマスク効果が適用される。

**権限による表示制御**：本コンポーネント自体に権限制御は存在しない。ただし、親画面である例外レンダラーは通常、開発環境（APP_DEBUG=true）でのみ表示される。また、ユニットテスト実行時やコンソール実行時は非表示となる条件がある。

## 関連機能

| 機能No | 機能名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| 36 | ビューファクトリ | 主機能 | Laravel ASCIIロゴの描画処理 |

## 画面種別

部品（コンポーネント）

## URL/ルーティング

本コンポーネントは単独のルーティングを持たない。例外レンダラーの一部として以下の条件で呼び出される：
- 例外発生時に自動的に表示される例外画面内で使用
- Bladeコンポーネントとして `<x-laravel-exceptions-renderer::icons.laravel-ascii />` の形式で呼び出し

## 入出力項目

| 項目名 | 入出力 | 型 | 必須 | 説明 |
|--------|--------|-----|------|------|
| - | - | - | - | このコンポーネントはpropsを受け取らない |

## 表示項目

| 項目 | 説明 |
|------|------|
| SVGアイコン | 1268x308ピクセルのLaravel ASCIIロゴを描画 |

### SVG仕様詳細

| 属性 | 値 | 説明 |
|------|-----|------|
| viewBox | 0 0 1268 308 | SVGのビューボックス設定 |
| fill | currentColor | 親要素の文字色を継承 |

### 構造

Laravel ASCIIアイコンは以下の要素で構成される：
1. **defs要素**：再利用可能なシンボル定義
   - `#a`：数字「1」を表現するパス
   - `#b`：数字「0」を表現するパス
2. **script要素**：動的グリッド生成ロジック
   - エンコードされたグリッドデータ（d変数）
   - 行ごとのループ処理
   - use要素の動的生成と配置

### グリッドデータ構造

グリッドデータは圧縮形式で格納されており、以下の規則で解釈される：
- `|`：行の区切り
- `.`：空白スペース
- `A`：シンボル`#a`（「1」）を配置
- `B`：シンボル`#b`（「0」）を配置
- 数字：続く文字の繰り返し回数

## イベント仕様

### 1-描画イベント

本コンポーネントはSVGテンプレートとJavaScriptの組み合わせでレンダリングされる。

**処理フロー**：
1. SVG要素とdefs（シンボル定義）がレンダリングされる
2. スクリプト要素内のJavaScriptが実行される
3. エンコードされたグリッドデータがパースされる
4. 行ごとにグループ（g要素）が生成される
5. 各行内でuse要素が動的に生成され、適切な位置に配置される
6. 「LARAVEL」の文字がASCIIアート形式で表示される

### 2-スポットライトイベント

親コンポーネント（laravel-ascii-spotlight.blade.php）により、以下のインタラクションが提供される：

| トリガー | 条件 | 動作 |
|---------|------|------|
| マウス移動 | ユーザーがスポットライト領域内でマウスを動かす | マスク位置がマウスに追従 |

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

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

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

本コンポーネントはUIの描画のみを行い、データベースへのアクセスは行わない。

## メッセージ仕様

本コンポーネントはメッセージを表示しない。視覚的なブランディング要素としてのみ機能する。

## 例外処理

| 例外状況 | 動作 |
|---------|------|
| JavaScriptエラー | グリッドが生成されず、空のSVGが表示される |
| テンプレートファイル未検出 | ViewNotFoundExceptionが発生 |

## 備考

- アイコンは`currentColor`を使用しているため、親要素の`color`プロパティを継承する
- 2つのインスタンスが重ねて使用され、1つは通常色、1つはハイライト色で表示される
- マスク効果により、マウスカーソル周辺のみハイライト色が表示されるスポットライト効果が実現される
- ユニットテスト実行時（`app()->runningUnitTests()`）やコンソール実行時（`app()->runningInConsole()`）は表示されない
- JavaScriptで動的にSVG要素を生成するため、初期HTMLには最小限の構造のみが含まれる

---

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

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

### 推奨読解順序

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

Laravel ASCIIアイコンは、SVGのシンボル定義とJavaScriptによる動的生成の組み合わせで構成される。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | laravel-ascii.blade.php | `src/Illuminate/Foundation/resources/exceptions/renderer/components/icons/laravel-ascii.blade.php` | SVG構造とグリッドデータの形式を理解する |

**読解のコツ**:
- `defs`内の`#a`と`#b`パスが基本的なビルディングブロック
- 圧縮されたグリッドデータ（d変数）がASCIIアートのレイアウトを定義
- JavaScriptがグリッドデータを解釈してuse要素を動的生成

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

アイコンが使用される起点となる例外レンダラーの構造を把握する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | show.blade.php | `src/Illuminate/Foundation/resources/exceptions/renderer/show.blade.php` | 例外レンダラーのメインテンプレート。laravel-ascii-spotlightコンポーネントの配置を確認（34-37行目） |
| 2-2 | laravel-ascii-spotlight.blade.php | `src/Illuminate/Foundation/resources/exceptions/renderer/components/laravel-ascii-spotlight.blade.php` | スポットライトコンポーネント。Laravel ASCIIアイコンの使用箇所を確認（19行目、21行目） |

**主要処理フロー**:
1. **show.blade.php 34-37行目**: 条件付きでlaravel-ascii-spotlightコンポーネントを呼び出し
2. **laravel-ascii-spotlight.blade.php**: 2つのlaravel-asciiアイコンを重ねて配置

#### Step 3: スポットライト効果を理解する

スポットライト効果の実装を確認する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | laravel-ascii-spotlight.blade.php | `src/Illuminate/Foundation/resources/exceptions/renderer/components/laravel-ascii-spotlight.blade.php` | Alpine.jsとCSSマスクを使用したスポットライト効果の実装 |

**主要処理フロー**:
- **1-4行目**: Alpine.jsのx-dataでspotlight位置を管理、@mousemoveでマウス位置を追跡
- **5-17行目**: ハイライト版のアイコン（マスクで部分的に表示）
- **19行目**: ハイライト版のlaravel-asciiアイコン
- **21行目**: 背景版のlaravel-asciiアイコン

#### Step 4: アイコンコンポーネント本体を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 4-1 | laravel-ascii.blade.php | `src/Illuminate/Foundation/resources/exceptions/renderer/components/icons/laravel-ascii.blade.php` | アイコンの実装本体。SVG構造とJavaScript生成ロジックを確認 |

**主要処理フロー**:
- **1行目**: SVG要素の開始。fill="currentColor"、viewBox定義
- **2-5行目**: defs要素内にシンボル`#a`（「1」）と`#b`（「0」）を定義
- **7-14行目**: JavaScriptによる動的グリッド生成
  - **9行目**: エンコードされたグリッドデータ（d変数）
  - **10行目**: 親SVG要素の取得
  - **12行目**: 座標とサイズの定数定義
  - **13行目**: 行ごとのループとグループ生成
  - 各セルでuse要素を生成し、`#a`または`#b`を参照

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

```
例外発生
    │
    ├─ Renderer::render()
    │      │
    │      └─ show.blade.php
    │             │
    │             ├─ layout.blade.php（レイアウト）
    │             │
    │             └─ @if (!runningUnitTests && !runningInConsole)
    │                    │
    │                    └─ laravel-ascii-spotlight.blade.php
    │                           │
    │                           ├─ icons/laravel-ascii.blade.php ★（ハイライト版）
    │                           │      └─ JavaScript動的生成
    │                           │
    │                           └─ icons/laravel-ascii.blade.php ★（背景版）
    │                                  └─ JavaScript動的生成
```

### データフロー図

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

グリッドデータ（d変数）    laravel-ascii.blade.php       ブラウザ表示
  │                          │                            │
  │                    パース処理                         │
  │                          │                            │
  │                    行ループ ───────────────────────▶│
  │                          │                            │
  │                    各行でg要素生成                    │
  │                          │                            │
  │                    セルループ                         │
  │                          │                            │
  │                    A→use href="#a" ────────────────▶│── 「1」文字
  │                    B→use href="#b" ────────────────▶│── 「0」文字
  │                          │                            │
  │                    transform適用 ──────────────────▶│── 配置完了
  │                          │                            │
マウス位置                    │                            │
  │                    spotlight.blade.php               │
  │                          │                            │
  │                    mask-image計算 ─────────────────▶│── スポットライト効果
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| laravel-ascii.blade.php | `src/Illuminate/Foundation/resources/exceptions/renderer/components/icons/laravel-ascii.blade.php` | テンプレート | Laravel ASCIIロゴSVGの定義 |
| show.blade.php | `src/Illuminate/Foundation/resources/exceptions/renderer/show.blade.php` | テンプレート | 例外レンダラーのメインビュー |
| laravel-ascii-spotlight.blade.php | `src/Illuminate/Foundation/resources/exceptions/renderer/components/laravel-ascii-spotlight.blade.php` | テンプレート | スポットライト効果コンポーネント（Laravel ASCIIアイコン使用） |
| layout.blade.php | `src/Illuminate/Foundation/resources/exceptions/renderer/components/layout.blade.php` | テンプレート | 例外レンダラーの共通レイアウト |
| Renderer.php | `src/Illuminate/Foundation/Exceptions/Renderer/Renderer.php` | ソース | 例外レンダラーのメインクラス |
