# 画面設計書 2-Try CoffeeScript

## 概要

本ドキュメントは、CoffeeScriptをブラウザ上でリアルタイムに試せるインタラクティブエディタ画面（documentation/site/try.html）の画面設計書です。ユーザーがCoffeeScriptコードを入力すると、即座にJavaScriptにコンパイルした結果を表示し、実行することができます。

### 本画面の処理概要

**業務上の目的・背景**：
CoffeeScriptを学習・試用したい開発者が、環境構築なしにブラウザ上で即座にコードを試すことができる機能を提供します。これにより、CoffeeScript言語への参入障壁を下げ、言語の特徴や利点を実際に体験できます。コンパイル結果がリアルタイムで表示されるため、CoffeeScriptとJavaScriptの対応関係を視覚的に学習できます。

**画面へのアクセス方法**：
トップページのナビゲーションバーにある「Try CoffeeScript」リンクをクリック、またはサイドバーの「Try CoffeeScript」リンクをクリックすることでアクセスします。モバイル端末ではハンバーガーメニューからアクセスできます。

**主要な操作・処理内容**：
1. 左側のテキストエリアにCoffeeScriptコードを入力
2. 入力に応じてリアルタイムでJavaScriptにコンパイル
3. コンパイル結果を右側のテキストエリアに表示
4. 実行ボタンをクリックしてコンパイル済みJavaScriptを実行
5. 実行結果をブラウザのコンソールまたはalertで確認

**画面遷移**：
- このパネルはトップページ上のオーバーレイとして表示される
- 遷移元: トップページのナビゲーションバー、サイドバー
- 遷移先: なし（パネルを閉じてトップページに戻る）

**権限による表示制御**：
特になし。全ユーザーがアクセス可能です。

## 関連機能

| 機能No | 機能名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| 1 | CoffeeScript コンパイル | 主機能 | ユーザー入力のCoffeeScriptコードをJavaScriptにコンパイル（bare: yes, inlineMap: true） |
| 51 | ブラウザコンパイラ | 主機能 | ブラウザ環境でのコンパイル機能を提供 |
| 5 | ソースマップ生成 | 補助機能 | デバッグ用のインラインソースマップを生成 |
| 47 | run関数 | 遷移先機能 | 実行ボタン押下時にコンパイル済みJavaScriptをeval実行 |

## 画面種別

インタラクティブエディタ / ツール画面

## URL/ルーティング

- パス: `/#try`（トップページ上のパネルとして表示）
- テンプレートファイル: `documentation/site/try.html`
- 表示制御: `data-toggle="try"` 属性によりパネルの開閉を制御

## 入出力項目

| 項目名 | 種別 | データ型 | 必須 | 説明 |
|--------|------|---------|------|------|
| CoffeeScript コード | 入力 | テキスト | - | ユーザーが入力するCoffeeScriptコード |
| JavaScript 出力 | 出力 | テキスト | - | コンパイル済みJavaScriptコードまたはエラーメッセージ |

## 表示項目

| 表示項目 | データソース | 表示形式 | 説明 |
|---------|-------------|---------|------|
| CoffeeScript入力エリア | ユーザー入力 | テキストエリア（#try-coffeescript-coffee） | 左カラム、ID: try-coffeescript-coffee |
| JavaScript出力エリア | コンパイル結果 | テキストエリア（#try-coffeescript-js） | 右カラム、ID: try-coffeescript-js |
| 実行ボタン | 固定 | ボタン（btn-primary） | 右下に配置、play.svgアイコン付き |

## イベント仕様

### 1-CoffeeScriptコード入力

CoffeeScriptテキストエリアに入力があると、リアルタイムでJavaScriptにコンパイルします。

- トリガー: `#try-coffeescript-coffee` テキストエリアへの入力
- 処理:
  1. 入力されたCoffeeScriptコードを取得
  2. CoffeeScript.compile() を `{ bare: yes, inlineMap: true }` オプションで呼び出し
  3. コンパイル成功時: 結果を `#try-coffeescript-js` に表示
  4. コンパイル失敗時: エラーメッセージを表示
- 備考: デバウンス処理によりパフォーマンスを最適化

### 2-実行ボタンクリック

実行ボタンをクリックすると、コンパイル済みJavaScriptコードを実行します。

- トリガー: `data-action="run-code-example"` ボタンのクリック
- 関連属性:
  - `data-example="try-coffeescript"`: 対象のコード例ID
  - `data-run="true"`: 実行対象フラグ
- 処理:
  1. `#try-coffeescript-js` からJavaScriptコードを取得
  2. CoffeeScript.run() またはeval()で実行
  3. 実行結果をコンソールまたはalertで表示
- エラー時: 実行時エラーをコンソールに出力

### 3-パネル開閉

Try CoffeeScriptパネルの表示/非表示を切り替えます。

- トリガー:
  - `data-toggle="try"` リンクのクリック（開く）
  - `data-close="try"` 要素のクリック（閉じる）
  - ナビゲーションバーのロゴクリック（閉じる）
- 処理: `#try` 要素のCSS表示状態を切り替え
- 備考: URLハッシュも `#try` に更新される

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

本画面はクライアントサイドのみで動作するため、データベースへの更新処理はありません。

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

該当なし

## メッセージ仕様

| メッセージID | 種別 | メッセージ内容 | 表示条件 |
|-------------|------|---------------|---------|
| COMPILE_ERROR | エラー | SyntaxError: 詳細メッセージ | CoffeeScriptコードに構文エラーがある場合 |
| RUNTIME_ERROR | エラー | 実行時エラーの詳細 | JavaScript実行時にエラーが発生した場合 |

## 例外処理

| 例外状況 | 処理内容 |
|---------|---------|
| CoffeeScriptコンパイルエラー | JavaScript出力エリアにエラーメッセージを表示 |
| JavaScript実行時エラー | コンソールにエラーを出力、必要に応じてalert表示 |
| ブラウザ非対応 | nomodule属性によりレガシーコンパイラにフォールバック |

## 備考

- 初期表示時のサンプルコードは `alert 'Hello CoffeeScript!'`
- 2カラムレイアウト（Bootstrap Grid: col-md-6）
- 背景色は `bg-ribbed-dark` クラスで暗いリブパターン
- レスポンシブ対応でモバイルでも使用可能
- コンパイルオプション `bare: yes` により、外側の関数ラッパーなしでコンパイル

---

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

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

### 推奨読解順序

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

コンパイルオプションとその効果を理解することが重要です。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | coffeescript.coffee | `src/coffeescript.coffee` | compile関数のオプション（bare, inlineMap）を確認 |

**読解のコツ**: `bare: yes`は即時実行関数ラッパー(IIFE)を省略、`inlineMap: true`はソースマップをBase64でJSに埋め込みます。

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

Try CoffeeScriptパネルのHTMLテンプレートを理解します。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | try.html | `documentation/site/try.html` | パネルのHTML構造とdata属性 |

**主要処理フロー**:
1. **行1**: `<aside id="try">` - Try CoffeeScriptパネルのルート要素
2. **行2-8**: 2カラムレイアウト（CoffeeScript入力、JavaScript出力）
3. **行4**: `#try-coffeescript-coffee` - CoffeeScript入力テキストエリア
4. **行7**: `#try-coffeescript-js` - JavaScript出力テキストエリア
5. **行10-13**: 実行ボタン（data-action="run-code-example"）

#### Step 3: コンパイル処理を理解する

ブラウザコンパイラの実装を理解します。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | browser.coffee | `src/browser.coffee` | CoffeeScript.run()、CoffeeScript.eval()の実装 |

**主要処理フロー**:
- **行13-16**: CoffeeScript.eval() - グローバルスコープでの評価
- **行19-22**: CoffeeScript.run() - bareモード、shiftLineでのコード実行
- **行34-37**: compile関数のオーバーライド（inlineMap: true追加）

#### Step 4: ナビゲーション連携を理解する

パネルの開閉制御を理解します。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 4-1 | navbar.html | `documentation/site/navbar.html` | Try CoffeeScriptリンク（data-toggle="try"） |
| 4-2 | sidebar.html | `documentation/site/sidebar.html` | サイドバーからのアクセス |

**主要処理フロー**:
- **navbar.html 行9**: `<a href="#try" data-toggle="try">Try CoffeeScript</a>`

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

```
ユーザー操作
    |
    +-- [Try CoffeeScriptリンククリック]
    |       |
    |       +-- data-toggle="try" イベント
    |               |
    |               +-- #try パネル表示
    |
    +-- [CoffeeScriptコード入力]
    |       |
    |       +-- #try-coffeescript-coffee 入力イベント
    |               |
    |               +-- CoffeeScript.compile(code, {bare: yes, inlineMap: true})
    |                       |
    |                       +-- lexer.tokenize()
    |                       +-- parser.parse()
    |                       +-- nodes.compileToFragments()
    |                       |
    |                       +-- #try-coffeescript-js に結果表示
    |
    +-- [実行ボタンクリック]
            |
            +-- data-action="run-code-example"
                    |
                    +-- CoffeeScript.run() または eval()
                            |
                            +-- 実行結果（alert/console）
```

### データフロー図

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

ユーザー入力              リアルタイム                    JavaScriptコード
(CoffeeScript) ------->   コンパイル       ------------>  (#try-coffeescript-js)
                              |
                              |  CoffeeScript.compile()
                              |  options: {bare: yes, inlineMap: true}
                              v
                         エラー時 --------------------------> エラーメッセージ表示

実行ボタン               CoffeeScript                    alert/console
クリック      -------->  .run()           ------------>  実行結果表示
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| try.html | `documentation/site/try.html` | テンプレート | Try CoffeeScriptパネルのHTML構造 |
| browser.coffee | `src/browser.coffee` | ソース | ブラウザ向けCoffeeScript拡張（eval, run関数） |
| coffeescript.coffee | `src/coffeescript.coffee` | ソース | コンパイラ本体のcompile関数 |
| navbar.html | `documentation/site/navbar.html` | テンプレート | パネル開閉リンク |
| sidebar.html | `documentation/site/sidebar.html` | テンプレート | サイドバーからのアクセスリンク |
| play.svg | `documentation/site/play.svg` | アセット | 実行ボタンのアイコン |
| lexer.coffee | `src/lexer.coffee` | ソース | 字句解析器 |
| parser.js | `lib/coffeescript/parser.js` | 生成コード | Jison生成のパーサー |
| nodes.coffee | `src/nodes.coffee` | ソース | ASTノードとコード生成 |
