# 画面設計書 3-外部スクリプトタグデモ

## 概要

本ドキュメントは、babel-standaloneパッケージに含まれる「外部スクリプトタグデモ」画面の設計仕様を定義する。この画面は外部JSファイル（src属性）を `text/babel` タイプで読み込み、Babelによって変換・実行するデモページである。

### 本画面の処理概要

この画面では、`type="text/babel"` かつ `src` 属性を持つscriptタグが使用される。Babel standaloneは外部JavaScriptファイルをXMLHttpRequest（XHR）を使用して読み込み、その内容をBabelで変換した後に実行する。これにより、ES2015+構文を含む外部JSファイルをブラウザ上で直接利用できることを実演する。

**業務上の目的・背景**：この画面は、インラインスクリプトではなく外部ファイルとしてES2015+コードを管理したいケースでのBabel standaloneの使用方法を示すために提供されている。コードの分離・再利用性を保ちながら、ブラウザ上でのトランスパイルを実現する。開発環境やプロトタイピングでの利用を想定しており、複数のHTMLファイルから共通のJSファイルを参照するシナリオをカバーする。

**画面へのアクセス方法**：ローカルサーバー経由で `packages/babel-standalone/examples/scriptTag-src.htm` にアクセスする。注意：外部ファイル読み込みにはXHRを使用するため、CORSの関係でファイルシステムから直接開いた場合は動作しない可能性がある。

**主要な操作・処理内容**：
1. ページ読み込み時にbabel.jsライブラリが読み込まれる
2. DOMContentLoadedイベント発火時に `transformScriptTags()` が自動的に呼び出される
3. `type="text/babel"` かつ `src="example.js"` のscriptタグが検出される
4. XMLHttpRequestを使用して `example.js` ファイルの内容を非同期で取得する
5. 取得したコード内容がBabel.transformで変換される
6. 変換後のコードが新しいscript要素として `<head>` に追加・実行される
7. 実行結果として"Hello world"メッセージとBabelバージョンが画面に表示される

**画面遷移**：本画面は独立したデモページであり、他の画面への遷移機能は存在しない。ユーザーは直接URLを指定してアクセスする。

**権限による表示制御**：認証・認可機能は実装されておらず、すべてのユーザーが同一の機能を利用できる。

## 関連機能

| 機能No | 機能名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| 14 | @babel/standalone | 主機能 | 外部JSファイル（src属性）をXHRで読み込みBabel変換を実行 |
| 1 | @babel/core | API連携 | transformScriptTags経由でBabel.transformを呼び出しコード変換 |
| 16 | @babel/preset-react | 補助機能 | デフォルトプリセットとしてJSX構文をサポート |
| 15 | @babel/preset-env | 補助機能 | デフォルトプリセットとしてES2015+構文を変換 |

## 画面種別

デモ / 外部ファイル読み込みサンプル

## URL/ルーティング

ファイルパス: `packages/babel-standalone/examples/scriptTag-src.htm`

※Webサーバー経由でアクセスすることを推奨（XHRによるファイル読み込みのため）

## 入出力項目

| 項目名 | 項目ID | 入力/出力 | データ型 | 必須 | 説明 |
|--------|--------|----------|----------|------|------|
| 結果表示エリア | output | 出力 | string | - | 変換・実行後のメッセージを表示するpre要素 |
| Babelバージョン | version | 出力 | string | - | 使用中のBabelバージョンを表示するstrong要素 |

## 表示項目

| 項目名 | 表示形式 | 説明 |
|--------|----------|------|
| Using Babel ラベル | テキスト | バージョン表示のラベル |
| Babelバージョン | strong要素内テキスト | Babel.versionの値 |
| 結果表示 | pre要素内テキスト | 初期表示は"Loading..."、実行後は"Hello world" |

## イベント仕様

### 1-ページ読み込み（DOMContentLoaded）

1. babel.jsスクリプトが読み込まれ、グローバルBabelオブジェクトが初期化される
2. Babel standaloneの初期化処理でDOMContentLoadedイベントリスナーが登録される
3. DOMContentLoadedイベント発火時に `transformScriptTags()` が呼び出される
4. `runScripts()` が実行され、`type="text/babel"` のscriptタグが検出される
5. src属性が存在するため、`load()` 関数が呼び出される

### 2-外部ファイル読み込み（XHR）

1. `load()` 関数内でXMLHttpRequestオブジェクトが作成される
2. GETリクエストで `example.js` ファイルを非同期読み込み
3. `overrideMimeType("text/plain")` でMIMEタイプを上書き
4. `onreadystatechange` ハンドラでレスポンスを監視
5. `readyState === 4` かつ `status === 0 または 200` で成功判定
6. 成功時：`successCallback` に `responseText` が渡される
7. 失敗時：`errorCallback` が呼び出され、エラーがスローされる

### 3-スクリプト変換と実行

1. 読み込み成功後、`CompilationResult.loaded` が `true` に設定される
2. `check()` 関数で実行順序が管理される
3. `run()` 関数が呼び出され、`transformCode()` で変換が実行される
4. 変換後のコードが新しいscript要素として `<head>` に追加される
5. ブラウザによってスクリプトが実行される

### 4-スクリプト実行（doStuff関数 - example.js内）

1. `example.js` 内の `doStuff()` 関数が呼び出される
2. `name` 変数に "world" が代入される
3. テンプレートリテラルを使用して `Hello ${name}` 文字列が生成される
4. `#output` 要素のinnerHTMLに "Hello world" が設定される
5. `#version` 要素のinnerHTMLに Babel.version が設定される

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

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

本画面はフロントエンドのみで動作するデモ画面であり、データベースへのアクセスは発生しない。

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

## メッセージ仕様

| メッセージID | 種別 | メッセージ内容 | 表示条件 |
|-------------|------|---------------|----------|
| MSG001 | 初期表示 | Loading... | ページ読み込み直後、外部ファイル読み込み・変換前 |
| MSG002 | 成功 | Hello world | スクリプト変換・実行成功後 |
| MSG003 | 警告（コンソール） | You are using the in-browser Babel transformer... | text/babelスクリプト検出時（開発警告） |
| MSG004 | エラー | Could not load {url} | XHRでファイル読み込み失敗時（コンソール＋例外） |

## 例外処理

| 例外ケース | 対応 | ユーザーへの表示 |
|-----------|------|-----------------|
| babel.js読み込み失敗 | ブラウザエラー | Babelオブジェクトが未定義となり、スクリプトが変換・実行されない |
| 外部JSファイル読み込み失敗 | errorCallbackでエラースロー | "Could not load {url}" エラーがスローされ、コンソールに出力 |
| CORS制限 | XHR失敗 | 外部ファイルを読み込めず、スクリプトが実行されない |
| 構文エラー | Babel変換時エラー | コンソールにエラーが出力される |
| DOM要素が見つからない | JavaScript実行時エラー | コンソールにエラーが出力される |

## 備考

- 本画面は開発者向けのデモンストレーション目的であり、本番環境での利用は推奨されていない
- 外部ファイル読み込みにはXMLHttpRequestを使用するため、CORS制限の影響を受ける
- ファイルシステムから直接開いた場合（file://プロトコル）、XHRが失敗する可能性がある
- 複数の外部スクリプトがある場合、DOM順序で順次読み込み・実行される（非同期だが実行は順序保証）
- async属性を明示的に指定しない限り、スクリプトは順序通りに実行される

---

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

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

### 推奨読解順序

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

外部ファイル読み込み時のデータ構造を理解することが重要である。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | transformScriptTags.ts | `packages/babel-standalone/src/transformScriptTags.ts` | CompilationResult型（19-33行目）、特に`url`と`loaded`プロパティ |

**読解のコツ**: `CompilationResult` の `url` プロパティは外部ファイルのパスを、`loaded` は読み込み完了状態を保持する。`async` プロパティで非同期実行の制御を行う。

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

HTMLファイルと外部JSファイルの構造を理解する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | scriptTag-src.htm | `packages/babel-standalone/examples/scriptTag-src.htm` | HTML構造とsrc属性付きtext/babelスクリプト（1-14行目） |
| 2-2 | example.js | `packages/babel-standalone/examples/example.js` | 読み込まれる外部JSファイルの内容（1-9行目） |

**主要処理フロー**:
1. **11行目（HTML）**: babel.jsスクリプトの読み込み
2. **12行目（HTML）**: `type="text/babel" src="example.js"` スクリプトの定義
3. **3-8行目（example.js）**: doStuff関数の定義とDOM操作

#### Step 3: 外部ファイル読み込み処理を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | transformScriptTags.ts | `packages/babel-standalone/src/transformScriptTags.ts` | load関数（120-144行目） |
| 3-2 | transformScriptTags.ts | `packages/babel-standalone/src/transformScriptTags.ts` | loadScripts関数内のsrc属性処理（211-225行目） |

**主要処理フロー**:
- **211-212行目**: `script.src` が存在する場合の分岐
- **213行目**: `result.url = script.src` でURLを保存
- **215-225行目**: `load()` 関数呼び出しと成功/失敗コールバック
- **125行目（load関数）**: XMLHttpRequestオブジェクト作成
- **129行目**: GETリクエストを非同期で開く
- **130-132行目**: MIMEタイプをtext/plainに上書き
- **133-142行目**: onreadystatechangeハンドラでレスポンス処理

#### Step 4: 実行順序管理を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 4-1 | transformScriptTags.ts | `packages/babel-standalone/src/transformScriptTags.ts` | check関数（180-191行目） |

**主要処理フロー**:
- **180-191行目**: `check()` 関数でスクリプトの実行順序を管理
- **184-186行目**: `loaded && !executed` の場合に `run()` を呼び出し
- **187-189行目**: 非asyncスクリプトの場合、前のスクリプトが完了するまで待機

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

```
ブラウザ
    │
    ├─ <script src="../babel.js">  ... babel-standaloneライブラリ読み込み
    │
    └─ DOMContentLoaded イベント発火
           │
           └─ transformScriptTags()  ... index.ts:274
                  │
                  └─ runScripts(transform, scriptTags)  ... transformScriptTags.ts:240
                         │
                         └─ loadScripts(transformFn, jsxScripts)  ... :173
                                │
                                ├─ script.src 検出  ... :211
                                │      │
                                │      └─ load(script.src, successCallback, errorCallback)  ... :120
                                │             │
                                │             ├─ new XMLHttpRequest()  ... :125
                                │             │
                                │             ├─ xhr.open("GET", url, true)  ... :129
                                │             │
                                │             └─ xhr.onreadystatechange  ... :133
                                │                    │
                                │                    └─ successCallback(xhr.responseText)
                                │
                                └─ check() ループ  ... :180
                                       │
                                       └─ run(transformFn, result)  ... :105
                                              │
                                              ├─ transformCode()  ... :38
                                              │      │
                                              │      └─ Babel.transform()
                                              │
                                              └─ headEl.appendChild(scriptEl)  ... :114
                                                     │
                                                     └─ example.js の doStuff() 実行
```

### データフロー図

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

scriptTag-src.htm           ──▶    Babel standalone                ──▶   <head>に新規script追加
    │                                    │                                    │
    │ src="example.js"                   │ runScripts()                       │ 変換後コード
    │                                    │   └─ loadScripts()                 │
    ▼                                    │       └─ load()                    ▼
example.js (外部)           ──────▶     │           └─ XHR GET          ブラウザ実行
    │                                    │               │                    │
    │ ES2015+コード                      │               ▼                    │
    │ (アロー関数,                       │       responseText            #output: "Hello world"
    │  テンプレートリテラル)            │               │               #version: Babel.version
    │                                    │               ▼                    │
    └────────────────────────────────▶  │       transformCode()  ─────────▶ │
                                         │           │                        │
                                         │           └─ Babel.transform()     │
                                         │                                    │
                                         └────────────────────────────────────┘
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| scriptTag-src.htm | `packages/babel-standalone/examples/scriptTag-src.htm` | テンプレート | デモ画面のHTML構造、外部スクリプト参照 |
| example.js | `packages/babel-standalone/examples/example.js` | ソース | 読み込まれる外部ES2015+スクリプト |
| babel.js | `packages/babel-standalone/babel.js` | ライブラリ | ビルド済みBabel standaloneライブラリ |
| index.ts | `packages/babel-standalone/src/index.ts` | ソース | エントリーポイント、transformScriptTags関数 |
| transformScriptTags.ts | `packages/babel-standalone/src/transformScriptTags.ts` | ソース | scriptタグ検出・XHR読み込み・変換・実行のコア処理 |
