# 画面設計書 24-メールボタン

## 概要

本ドキュメントは、LaravelフレームワークのHTMLメールテンプレートにおけるボタンコンポーネント（button.blade.php）の設計仕様を定義するものである。

### 本画面の処理概要

本コンポーネントは、HTMLメール内でクリック可能なアクションボタンを表示するための部品である。パスワードリセット、メール確認、注文確認などのCTA（Call To Action）ボタンとして使用される。

**業務上の目的・背景**：メールマーケティングやトランザクションメールにおいて、ユーザーにアクションを促すボタンは最も重要な要素の一つである。目立つデザインのボタンを提供することで、クリック率を向上させ、ユーザーを目的のアクションに導く。カラーバリエーションにより、アクションの種類（確認、警告、成功など）を視覚的に区別することも可能。

**画面へのアクセス方法**：本コンポーネントは直接アクセスするものではなく、Markdownメール内で`@component('mail::button', ['url' => $url])`として使用される。または、Bladeコンポーネント構文で`<x-mail::button :url="$url">`として呼び出す。

**主要な操作・処理内容**：
1. @propsディレクティブでurl、color、align属性を受け取る
2. colorのデフォルト値は'primary'、alignのデフォルト値は'center'
3. 3段階にネストしたテーブル構造でボタンを構成
4. アンカータグにbutton-{color}クラスを適用してスタイリング
5. $slotの内容をボタンテキストとして表示

**画面遷移**：ボタンをクリックすると、$urlで指定されたURLに新しいタブで遷移する（target="_blank"）。

**権限による表示制御**：ボタンコンポーネント自体には権限制御はない。表示するURL自体のアクセス制御はアプリケーション側で行う。

## 関連機能

| 機能No | 機能名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| 28 | メール管理 | 主機能 | HTMLメールのアクションボタン表示 |
| 17 | URL生成 | 補助機能 | ボタンリンクURLの生成処理 |

## 画面種別

コンポーネント（メールテンプレート部品）

## URL/ルーティング

該当なし（Bladeコンポーネントとして使用）

コンポーネント名: `mail::button`

## 入出力項目

| 項目名 | 型 | 必須 | デフォルト値 | 説明 |
|--------|------|------|------------|------|
| $url | string | Yes | - | ボタンクリック時の遷移先URL |
| $color | string | No | 'primary' | ボタンの色（primary/success/error等） |
| $align | string | No | 'center' | ボタンの配置（left/center/right） |
| $slot | string | Yes | - | ボタンのテキスト |

## 表示項目

| 要素 | 表示内容 | 備考 |
|------|---------|------|
| ボタン | $slotの内容 | クリック可能なリンクボタン |

## イベント仕様

### 1-ボタンクリック

ボタンをクリックすると、指定されたURLに新しいタブで遷移する。

**処理フロー**:
1. ユーザーがボタンをクリック
2. target="_blank"により新しいタブが開く
3. rel="noopener"によりセキュアな遷移を実行
4. $urlで指定されたページが表示される

**セキュリティ属性**:
- `target="_blank"`: 新しいタブで開く
- `rel="noopener"`: 遷移先からwindow.openerへのアクセスを防止

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

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

該当なし（表示専用コンポーネント）

## メッセージ仕様

該当なし

## 例外処理

| 状態 | 処理内容 |
|------|---------|
| $url未指定 | コンパイルエラー（必須プロパティ） |
| $slot未指定 | 空のボタンとして出力 |
| 不正なcolor値 | 未定義のCSSクラスが適用される |

## 備考

- 3段階のテーブルネストはメールクライアント互換性のため
- `{!! $slot !!}`でエスケープなし出力（HTMLボタンテキスト対応）
- CSSクラス`action`、`button`、`button-{color}`はテーマファイルで定義
- 一般的なcolor値: primary（青）、success（緑）、error（赤）

---

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

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

### 推奨読解順序

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

まず、コンポーネントで受け取るプロパティとデフォルト値を理解する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | button.blade.php | `src/Illuminate/Mail/resources/views/html/button.blade.php` | @propsディレクティブで3つのプロパティを定義（行1-5） |

**読解のコツ**: `@props(['url', 'color' => 'primary', 'align' => 'center'])`は配列形式でプロパティとデフォルト値を同時に定義できる。

#### Step 2: テンプレート構造を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | button.blade.php | `src/Illuminate/Mail/resources/views/html/button.blade.php` | 3段階のテーブルネスト構造（行6-24） |

**主要処理フロー**:
- **行6-8**: 外側テーブル（actionクラス、alignで配置制御）
- **行9-11**: 中間テーブル（幅100%、セルパディングなし）
- **行12-17**: 内側テーブル（実際のボタン構造）
- **行15**: `<a href="{{ $url }}" class="button button-{{ $color }}" ...>`でリンク生成

#### Step 3: スタイル定義を確認する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | default.css（テーマ） | `resources/views/vendor/mail/html/themes/default.css` | buttonクラスのスタイル定義（アプリ側） |

**読解のコツ**: ボタンのスタイルはテーマファイルで定義される。フレームワーク内のデフォルトテーマは`mail::themes.default`として参照される。

#### Step 4: 使用パターンを理解する

典型的な使用例（Markdownメール内）:
```blade
@component('mail::button', ['url' => $actionUrl, 'color' => 'primary'])
{{ $actionText }}
@endcomponent
```

または:
```blade
<x-mail::button :url="$actionUrl" color="primary">
    {{ $actionText }}
</x-mail::button>
```

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

```
Markdownメールテンプレート
    │
    └─ @component('mail::button') または <x-mail::button>
           │
           └─ button.blade.php
                  │
                  ├─ @props(['url', 'color', 'align'])
                  │
                  └─ 3段階ネストテーブル
                         │
                         └─ <a href="{{ $url }}"
                               class="button button-{{ $color }}"
                               target="_blank"
                               rel="noopener">
                                  {!! $slot !!}
                            </a>
```

### データフロー図

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

$url ─────────────▶ href属性 ─────────────▶ リンクURL
                                              │
$color ───────────▶ class="button-{color}" ─▶ スタイル適用
(default: primary)                            │
                                              │
$align ───────────▶ align="{align}" ────────▶ 配置制御
(default: center)                             │
                                              │
$slot ────────────▶ {!! $slot !!} ──────────▶ ボタンテキスト
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| button.blade.php | `src/Illuminate/Mail/resources/views/html/button.blade.php` | テンプレート | ボタン部品本体 |
| text/button.blade.php | `src/Illuminate/Mail/resources/views/text/button.blade.php` | テンプレート | テキストメール用ボタン |
| Markdown.php | `src/Illuminate/Mail/Markdown.php` | ソース | コンポーネント解決 |
| Mailable.php | `src/Illuminate/Mail/Mailable.php` | ソース | メール送信の基底クラス |
