# 画面設計書 1-Babelトランスフォームデモ

## 概要

本ドキュメントは、babel-standaloneパッケージに含まれる「Babelトランスフォームデモ」画面の設計仕様を定義する。この画面はBabel APIを使用したJavaScriptコードのリアルタイム変換機能を実演するためのデモページである。

### 本画面の処理概要

この画面では、ユーザーがES2015/JSX構文を含むJavaScriptコードを入力すると、Babel.transform() APIを使用してリアルタイムに変換処理が行われ、変換後のES5互換コードが即座に表示される。開発者がBabel standaloneの基本的なAPI使用方法を理解するためのインタラクティブなサンプルとして機能する。

**業務上の目的・背景**：この画面は、Babelコンパイラの機能をブラウザ上で直接体験できるようにするためのデモンストレーション用途で提供されている。開発者がビルドツールを設定することなく、Babelの変換機能を即座に試すことができる。プロトタイピングや学習目的での利用を想定しており、Babel APIの理解促進と採用検討の支援を目的としている。

**画面へのアクセス方法**：ローカルサーバーまたはファイルシステムから直接 `packages/babel-standalone/examples/example.htm` にアクセスする。ブラウザでHTMLファイルを開くことで画面が表示される。

**主要な操作・処理内容**：
1. ページ読み込み時にbabel.jsライブラリが読み込まれ、グローバルオブジェクト `Babel` が利用可能になる
2. 初期表示時にtextarea内のサンプルコードが自動的に変換され、結果がpre要素に表示される
3. ユーザーがtextareaにコードを入力・編集するたびに `keyup` イベントが発火し、transform関数が呼び出される
4. Babel.transform()メソッドが入力コードを変換し、結果を出力エリアに表示する
5. 変換エラーが発生した場合はエラーメッセージが表示される

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

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

## 関連機能

| 機能No | 機能名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| 14 | @babel/standalone | 主機能 | Babel APIを直接呼び出し、入力欄のES2015/JSXコードをリアルタイム変換する |
| 1 | @babel/core | API連携 | Babel.transformメソッドを通じてコード変換を実行 |
| 16 | @babel/preset-react | 補助機能 | JSX構文の変換に使用（presetsに"react"を指定） |
| 15 | @babel/preset-env | 補助機能 | ES2015構文の変換に使用（presetsに"es2015"を指定） |

## 画面種別

デモ / インタラクティブツール

## URL/ルーティング

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

※ローカルファイルとして直接開くか、Webサーバー経由でアクセスする

## 入出力項目

| 項目名 | 項目ID | 入力/出力 | データ型 | 必須 | 説明 |
|--------|--------|----------|----------|------|------|
| コード入力エリア | input | 入力 | string | 任意 | ES2015/JSX構文を含むJavaScriptコードを入力するtextarea |
| 変換結果エリア | output | 出力 | string | - | 変換後のES5コードまたはエラーメッセージを表示するpre要素 |
| Babelバージョン | version | 出力 | string | - | 使用中のBabelバージョンを表示するstrong要素 |

## 表示項目

| 項目名 | 表示形式 | 説明 |
|--------|----------|------|
| Input: ラベル | テキスト | 入力エリアのラベル |
| コード入力エリア | textarea（幅100%、10行） | 初期値としてサンプルコードが表示される |
| Transformed code using Babel | テキスト | 出力エリアのラベル |
| Babelバージョン | strong要素内テキスト | Babel.versionの値 |
| 変換結果 | pre要素内テキスト | 初期表示は"Loading..."、変換後はコードを表示 |

## イベント仕様

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

1. babel.jsスクリプトが読み込まれ、グローバルBabelオブジェクトが初期化される
2. インラインスクリプトが実行され、以下の処理が行われる：
   - `Babel.version` の値が `#version` 要素に表示される
   - `#input` と `#output` 要素への参照が取得される
   - `keyup` イベントリスナーが登録される
   - 初回の `transform()` 関数が呼び出され、初期コードが変換される

### 2-コード入力（keyupイベント）

1. ユーザーがtextarea内でキーを押すたびに `keyup` イベントが発火
2. `transform()` 関数が呼び出される
3. `Babel.transform()` メソッドが以下のオプションで実行される：
   - presets: ["es2015", "react", ["stage-0", { decoratorsBeforeExport: false }]]
4. 変換成功時：変換後のコード（`.code`プロパティ）が `#output` 要素に表示される
5. 変換失敗時：`ERROR: ` プレフィックス付きでエラーメッセージが表示される

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

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

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

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

## メッセージ仕様

| メッセージID | 種別 | メッセージ内容 | 表示条件 |
|-------------|------|---------------|----------|
| MSG001 | 初期表示 | Loading... | ページ読み込み直後、変換処理完了前 |
| MSG002 | エラー | ERROR: {ex.message} | Babel.transform()でエラー発生時 |

## 例外処理

| 例外ケース | 対応 | ユーザーへの表示 |
|-----------|------|-----------------|
| 構文エラー | try-catch文でキャッチ | `ERROR: ` プレフィックス付きでエラーメッセージを表示 |
| 不正なプリセット指定 | try-catch文でキャッチ | `ERROR: Invalid preset specified in Babel options` |
| babel.js読み込み失敗 | ブラウザエラー | Babelオブジェクトが未定義となり、スクリプトが動作しない |

## 備考

- 本画面は開発者向けのデモンストレーション目的であり、本番環境での利用は想定されていない
- コンソールに `Babel =` オブジェクトがログ出力される（デバッグ用途）
- stage-0プリセットには `decoratorsBeforeExport: false` オプションが設定されている
- リアルタイム変換のため、入力のたびに処理が発生する（デバウンス処理なし）

---

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

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

### 推奨読解順序

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

Babel.transform()のオプション構造と戻り値の構造を理解することが重要である。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | index.ts | `packages/babel-standalone/src/index.ts` | transform関数のシグネチャとInputOptionsの構造（178-180行目） |
| 1-2 | transformScriptTags.ts | `packages/babel-standalone/src/transformScriptTags.ts` | CompilationResult型の定義（19-33行目） |

**読解のコツ**: TypeScriptの型定義に注目し、`InputOptions`の`presets`と`plugins`プロパティがどのような形式で指定されるかを確認する。

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

この画面のエントリーポイントは2つある：HTMLファイル自体と、babel.jsライブラリである。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | example.htm | `packages/babel-standalone/examples/example.htm` | HTML構造と初期化スクリプト（1-50行目） |

**主要処理フロー**:
1. **19行目**: babel.jsスクリプトの読み込み
2. **21行目**: `console.log("Babel =", Babel)` でBabelオブジェクトの確認
3. **22行目**: Babel.versionをバージョン表示要素に設定
4. **26-43行目**: transform関数の定義（Babel.transformの呼び出しとエラーハンドリング）
5. **45行目**: keyupイベントリスナーの登録
6. **46行目**: 初回のtransform()呼び出し

#### Step 3: Babel standaloneのコア処理を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | index.ts | `packages/babel-standalone/src/index.ts` | transform関数の実装とprocessOptions（134-179行目） |
| 3-2 | index.ts | `packages/babel-standalone/src/index.ts` | availablePresetsの定義（60-87行目） |

**主要処理フロー**:
- **178-180行目**: transform関数がprocessOptionsを通じて@babel/coreのtransformSyncを呼び出す
- **134-176行目**: processOptionsでプリセットとプラグインの名前解決を行う
- **102-113行目**: loadBuiltinでプリセット/プラグイン名から実際のモジュールを取得

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

```
example.htm (ブラウザ)
    │
    ├─ <script src="../babel.js">  ... babel-standaloneライブラリ読み込み
    │
    └─ <script> (インラインスクリプト)
           │
           ├─ Babel.version  ... バージョン表示
           │
           └─ transform() (ローカル関数)
                  │
                  └─ Babel.transform(inputEl.value, options)
                         │
                         ├─ processOptions(options)  ... index.ts:134
                         │      │
                         │      ├─ loadBuiltin(availablePresets, ...)  ... index.ts:102
                         │      └─ loadBuiltin(availablePlugins, ...)  ... index.ts:102
                         │
                         └─ babelTransformSync(code, options)  ... @babel/core
                                │
                                └─ .code (変換結果)
```

### データフロー図

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

textarea#input ──────▶ Babel.transform() ──────▶ pre#output
   │                         │                        │
   │ value                   │ options:               │ innerHTML
   │ (ES2015/JSXコード)      │ - presets:             │ (ES5コード または
   │                         │   ["es2015","react",   │  エラーメッセージ)
   │                         │    ["stage-0", {...}]] │
   │                         │                        │
   └─ keyupイベント ─────────┴────────────────────────┘
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| example.htm | `packages/babel-standalone/examples/example.htm` | テンプレート | デモ画面のHTML構造とインラインスクリプト |
| babel.js | `packages/babel-standalone/babel.js` | ライブラリ | ビルド済みBabel standaloneライブラリ（実行時に読み込み） |
| index.ts | `packages/babel-standalone/src/index.ts` | ソース | Babel standaloneのエントリーポイントとAPI定義 |
| preset-es2015.ts | `packages/babel-standalone/src/preset-es2015.ts` | ソース | ES2015プリセットの定義 |
| preset-stage-0.ts | `packages/babel-standalone/src/preset-stage-0.ts` | ソース | Stage-0プリセットの定義 |
| plugins.ts | `packages/babel-standalone/src/generated/plugins.ts` | ソース | 利用可能なプラグインの一覧 |
