# 画面設計書 1-トップページ

## 概要

本ドキュメントは、CoffeeScript公式ドキュメントサイトのトップページ（documentation/site/index.html）の画面設計書です。CoffeeScriptの全ドキュメントセクションを含むシングルページアプリケーション（SPA）形式のメインページであり、言語リファレンス、インストール方法、使用方法などの包括的な情報を提供します。

### 本画面の処理概要

**業務上の目的・背景**：
CoffeeScriptはJavaScriptにコンパイルされるプログラミング言語であり、開発者がその機能と使い方を学ぶための中央ハブとしてこのトップページが機能します。ユーザーはCoffeeScriptの構文、コンパイル方法、各種機能について理解を深めることができ、インタラクティブなコード例を通じて実際の動作を確認できます。このページは言語の学習、リファレンス参照、バージョン間の違いの確認など、開発者の多様なニーズに対応します。

**画面へのアクセス方法**：
ブラウザで https://coffeescript.org/ または直接 index.html にアクセスすることで表示されます。サイドバーやナビゲーションバーからも各セクションへ直接アクセス可能です。

**主要な操作・処理内容**：
1. ナビゲーションバーからTry CoffeeScript、Language Reference、Integrations、Resources、GitHubへのアクセス
2. サイドバーを使用した各セクションへのスムーズスクロール遷移
3. ページ内のコード例（code-example）をリアルタイムでCoffeeScriptからJavaScriptにコンパイルして表示
4. 実行可能なコード例の「Run」ボタンによるJavaScriptコードの実行
5. バージョン情報、インストール手順、言語機能の参照
6. 変更履歴（Changelog）の確認

**画面遷移**：
- このページから遷移できる画面: Try CoffeeScript（try.html）、テストスイート（test.html）、v1ドキュメント（/v1/）、外部のGitHubリポジトリ
- このページに遷移してくる画面: 外部リンク、検索エンジン、他の関連サイト

**権限による表示制御**：
特になし。全コンテンツは公開されており、認証なしでアクセス可能です。

## 関連機能

| 機能No | 機能名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| 1 | CoffeeScript コンパイル | 主機能 | ページ内のコード例をリアルタイムでCoffeeScriptからJavaScriptにコンパイルして表示 |
| 51 | ブラウザコンパイラ | 主機能 | ブラウザ上でCoffeeScriptコードをJavaScriptにコンパイルするコア機能 |
| 5 | ソースマップ生成 | 補助機能 | コンパイル時にインラインソースマップを生成してデバッグを支援 |
| 49 | スタックトレース変換 | 補助機能 | patchStackTrace関数によるエラー時のスタックトレース行番号変換 |

## 画面種別

ドキュメント / 一覧（シングルページアプリケーション形式）

## URL/ルーティング

- パス: `/` または `/index.html`
- ビルド元テンプレート: `documentation/site/index.html`
- セクション内アンカー: `#introduction`, `#overview`, `#coffeescript-2`, `#installation`, `#usage`, `#language`, `#type-annotations`, `#literate`, `#source-maps`, `#cake`, `#scripts`, `#integrations`, `#resources`, `#unsupported`, `#breaking-changes`, `#changelog`

## 入出力項目

| 項目名 | 種別 | データ型 | 必須 | 説明 |
|--------|------|---------|------|------|
| CoffeeScript コード入力 | 入力 | テキスト | - | コード例の編集可能なテキストエリア |
| JavaScript 出力 | 出力 | テキスト | - | コンパイル済みJavaScriptコードの表示エリア |

## 表示項目

| 表示項目 | データソース | 表示形式 | 説明 |
|---------|-------------|---------|------|
| ナビゲーションバー | navbar.html | HTMLパーシャル | サイト上部の固定ナビゲーション |
| サイドバー | sidebar.html | HTMLパーシャル | 左側のセクションナビゲーション |
| ロゴ | logo.svg | SVG画像 | CoffeeScriptロゴ |
| Introduction セクション | introduction.md | HTML | 言語の紹介 |
| Overview セクション | overview.md | HTML | 概要説明 |
| CoffeeScript 2 セクション | coffeescript_2.md | HTML | バージョン2の説明 |
| Installation セクション | installation.md | HTML | インストール手順 |
| Usage セクション | usage.md | HTML | 使用方法 |
| Language Reference セクション | language.md等 | HTML | 言語仕様リファレンス |
| コード例 | code.html + 各.coffeeファイル | インタラクティブエディタ | CoffeeScript/JavaScript並列表示 |
| Changelog セクション | changelog/*.md | HTML | 変更履歴 |

## イベント仕様

### 1-サイドバーナビゲーションクリック

サイドバーのリンクをクリックすると、対応するセクションへスムーズスクロールします。

- トリガー: `data-action="sidebar-nav"` 属性を持つアンカー要素のクリック
- 処理: jQuery/JavaScript によるスムーズスクロール処理
- 遷移先: ページ内の対応するセクション（例: `#introduction`, `#language`）

### 2-Try CoffeeScript トグル

ナビゲーションバーの「Try CoffeeScript」をクリックすると、インタラクティブエディタを開閉します。

- トリガー: `data-toggle="try"` 属性を持つ要素のクリック
- 処理: Try CoffeeScriptパネルの表示/非表示切り替え
- 対象要素: `#try` 要素

### 3-コード例のリアルタイムコンパイル

コード例のCoffeeScriptテキストエリアの内容が変更されると、JavaScriptにリアルタイムコンパイルされます。

- トリガー: `.coffeescript-input` テキストエリアの入力変更
- 処理:
  1. CoffeeScript.compile() を呼び出し
  2. inlineMap: true オプションでソースマップを生成
  3. コンパイル結果を `.javascript-output` に表示
- エラー時: コンパイルエラーメッセージを表示

### 4-コード例の実行

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

- トリガー: `data-action="run-code-example"` ボタンのクリック
- 処理:
  1. コンパイル済みJavaScriptコードを取得
  2. eval() または Function() でコードを実行
  3. 実行結果をコンソールまたは画面に表示

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

本画面は静的ドキュメントページであり、データベースへの更新処理はありません。

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

該当なし

## メッセージ仕様

| メッセージID | 種別 | メッセージ内容 | 表示条件 |
|-------------|------|---------------|---------|
| COMPILE_ERROR | エラー | コンパイルエラーの詳細メッセージ | CoffeeScriptコードに構文エラーがある場合 |

## 例外処理

| 例外状況 | 処理内容 |
|---------|---------|
| コンパイルエラー | エラーメッセージを表示し、JavaScriptエリアにエラー内容を出力 |
| スクリプト読み込み失敗 | コンソールにエラーを出力 |
| ブラウザ非対応 | nomodule属性でレガシーブラウザ向けにフォールバック提供 |

## 備考

- シングルページアプリケーション形式で構成されており、1つのHTMLファイル内に全セクションが含まれる
- CodeMirrorエディタを使用してコード入力エリアを提供
- ブラウザコンパイラはES Module版（modern）とレガシー版の両方を提供
- Google Analytics（gtag）によるアクセス解析が組み込まれている
- ビルドプロセスでbody.html、navbar.html、sidebar.htmlなどのパーシャルが結合される

---

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

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

### 推奨読解順序

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

まず、CoffeeScriptコンパイラの基本的なデータ構造とオプションを理解することが重要です。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | coffeescript.coffee | `src/coffeescript.coffee` | compile関数の引数options（sourceMap, inlineMap, bare等）を確認 |
| 1-2 | helpers.coffee | `src/helpers.coffee` | ユーティリティ関数群、特にupdateSyntaxError等のエラーハンドリング |

**読解のコツ**: CoffeeScriptソースはクラスベースのオブジェクト指向で書かれており、exports経由で関数を公開しています。

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

処理の起点となるブラウザコンパイラの仕組みを理解します。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | browser.coffee | `src/browser.coffee` | ブラウザ環境でのCoffeeScript実行の起点 |
| 2-2 | scripts.html | `documentation/site/scripts.html` | ブラウザコンパイラの読み込みとdocs.coffeeの実行 |

**主要処理フロー**:
1. **行6-8**: CoffeeScript本体をrequireで読み込み
2. **行13-16**: CoffeeScript.eval()の定義（グローバルスコープでの評価）
3. **行19-22**: CoffeeScript.run()の定義（bareモードでのコード実行）
4. **行40-56**: CoffeeScript.load()でXHR経由のリモートスクリプト読み込み
5. **行61-96**: CoffeeScript.runScripts()でtext/coffeescript scriptタグの自動実行

#### Step 3: テンプレート構成を理解する

HTMLテンプレートの構成と組み立て方を理解します。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | index.html | `documentation/site/index.html` | メインテンプレート、include構文でパーシャルを結合 |
| 3-2 | body.html | `documentation/site/body.html` | ページ本体の構造、htmlFor()関数で各セクションを動的生成 |
| 3-3 | navbar.html | `documentation/site/navbar.html` | ナビゲーションバーの構造 |
| 3-4 | sidebar.html | `documentation/site/sidebar.html` | サイドバーナビゲーションの構造 |
| 3-5 | code.html | `documentation/site/code.html` | コード例コンポーネントのテンプレート |

**主要処理フロー**:
- **body.html 行16-18**: `htmlFor('introduction')`でMarkdownからHTMLを生成
- **code.html 行1-19**: コード例の双方向表示（CoffeeScript/JavaScript）

#### Step 4: コンパイル処理の流れを理解する

実際のコンパイル処理がどのように行われるかを理解します。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 4-1 | coffeescript.coffee | `src/coffeescript.coffee` | メインのcompile関数 |
| 4-2 | lexer.coffee | `src/lexer.coffee` | 字句解析処理 |
| 4-3 | parser.coffee | `lib/coffeescript/parser.js` | 構文解析（Jison生成） |
| 4-4 | nodes.coffee | `src/nodes.coffee` | ASTノードの定義とコード生成 |

**主要処理フロー**:
- **coffeescript.coffee 行62-180**: compile関数本体
- **行73**: lexer.tokenize()でトークン化
- **行88**: parser.parseでAST生成
- **行109**: nodes.compileToFragments()でJavaScript生成

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

```
documentation/site/index.html
    |
    +-- include('body.html')
    |       |
    |       +-- include('navbar.html')    ... ナビゲーションバー
    |       +-- include('try.html')       ... Try CoffeeScriptパネル
    |       +-- include('sidebar.html')   ... サイドバー
    |       +-- htmlFor('introduction')   ... 各セクションのMarkdown変換
    |       +-- include('code.html')      ... コード例コンポーネント
    |
    +-- include('scripts.html')
            |
            +-- browser-compiler-modern/coffeescript.js
            |       |
            |       +-- CoffeeScript.compile()
            |               |
            |               +-- lexer.tokenize()
            |               +-- parser.parse()
            |               +-- nodes.compileToFragments()
            |
            +-- docs.coffee (ページ初期化スクリプト)
```

### データフロー図

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

ユーザー入力              CoffeeScript                    JavaScriptコード
(CoffeeScript) ------->   .compile()       ------------>  (.javascript-output)
                              |
                              v
                         lexer.tokenize()
                              |
                              v
                         parser.parse()
                              |
                              v
                         nodes.compileToFragments()
                              |
                              v
                         ソースマップ生成
                         (inlineMap: true)
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| index.html | `documentation/site/index.html` | テンプレート | メインHTMLテンプレート |
| body.html | `documentation/site/body.html` | テンプレート | ページ本体の構造定義 |
| navbar.html | `documentation/site/navbar.html` | テンプレート | ナビゲーションバー |
| sidebar.html | `documentation/site/sidebar.html` | テンプレート | サイドバーナビゲーション |
| try.html | `documentation/site/try.html` | テンプレート | Try CoffeeScriptパネル |
| code.html | `documentation/site/code.html` | テンプレート | コード例コンポーネント |
| scripts.html | `documentation/site/scripts.html` | テンプレート | スクリプト読み込み定義 |
| styles.html | `documentation/site/styles.html` | テンプレート | CSS読み込み定義 |
| browser.coffee | `src/browser.coffee` | ソース | ブラウザ向けCoffeeScript拡張 |
| coffeescript.coffee | `src/coffeescript.coffee` | ソース | コンパイラ本体 |
| lexer.coffee | `src/lexer.coffee` | ソース | 字句解析器 |
| nodes.coffee | `src/nodes.coffee` | ソース | ASTノード定義 |
| introduction.md | `documentation/sections/introduction.md` | コンテンツ | Introductionセクション |
| overview.md | `documentation/sections/overview.md` | コンテンツ | Overviewセクション |
| language.md | `documentation/sections/language.md` | コンテンツ | Language Referenceセクション |
