# 画面設計書 17-Usage-Browser

## 概要

本ドキュメントは、Prettierドキュメントサイトの「Usage - Browser」画面の設計書です。この画面はPrettierをブラウザ環境で使用するためのstandalone版の使用方法を説明するドキュメントページです。

### 本画面の処理概要

この画面はNode.jsに依存しないPrettier standalone版の使用方法を説明する静的ドキュメントページです。Global、ES Modules、AMD、CommonJS、Workerの各環境での読み込み方法と、プラグインの明示的な指定方法を解説しています。

**業務上の目的・背景**：オンラインコードエディタ、ブラウザ拡張機能、Webアプリケーション内でのコードフォーマットなど、ブラウザ環境でPrettierを使用するニーズがあります。この画面は、Node.js環境なしでPrettierを活用するための具体的な実装方法を開発者に提供します。

**画面へのアクセス方法**：ユーザーはメインサイトのナビゲーションバーから「Docs」セクションに入り、サイドバーの「Usage」カテゴリ内の「Browser」リンクをクリックしてアクセスします。URLは `/docs/browser` です。

**主要な操作・処理内容**：
1. standalone版の特徴（Node.js非依存、設定ファイル/Ignoreファイル非対応）の理解
2. Global読み込み（`<script>`タグ）での使用方法の理解
3. ES Modules読み込みでの使用方法の理解
4. AMD/CommonJS/Worker環境での使用方法の理解
5. プラグイン明示指定の必要性の理解
6. 埋め込みコード用の追加プラグイン読み込みの理解

**画面遷移**：この画面からはオプションドキュメント、APIドキュメント、プラグインドキュメントへのリンクが設定されています。

**権限による表示制御**：なし。全ユーザーが同一のコンテンツを閲覧可能。

## 関連機能

| 機能No | 機能名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| 1 | コードフォーマット（format） | 主機能 | ブラウザ環境でのformat関数の使い方を説明 |
| 31 | プラグインローダー | 補助機能 | ブラウザ環境でのプラグイン読み込みを説明 |

## 画面種別

ドキュメント / 参照

## URL/ルーティング

- **URL**: `/docs/browser`
- **ソースファイル**: `docs/browser.md`
- **生成方式**: Docusaurus docs機能によるMarkdownからの静的HTML生成

## 入出力項目

本画面は静的ドキュメントページのため、ユーザー入力フィールドはありません。

## 表示項目

| セクション | 表示内容 | 説明 |
|-----------|---------|------|
| 導入説明 | standalone版の概要 | Node.js非依存、設定ファイル非対応等の特徴 |
| 配布形式 | ES modules / UMD | standalone.mjs (v3.0+), standalone.js (v1.13+) |
| prettier.format | 必須オプション | parser/filepath, pluginsオプションの説明 |
| Global | script タグ読み込み | UMDバンドルの使用方法 |
| ES Modules | import文 | ESM形式での読み込み |
| AMD | define関数 | RequireJS等での読み込み |
| CommonJS | require文 | バンドラー使用時の読み込み |
| Worker | Module/Classic worker | Web Worker内での使用 |
| 埋め込みコード用プラグイン | 追加プラグイン | HTML埋め込みコード等の処理 |

## イベント仕様

### 1-タブ切り替え

Docusaurusの`<Tabs>`コンポーネントにより、Worker種別（Module worker/Classic worker）のコード表示を切り替えます。

### 2-内部リンククリック

- `options.md#parser` → パーサーオプション説明
- `options.md#file-path` → ファイルパスオプション説明
- `api.md` → APIドキュメント
- `plugins.md` → プラグインドキュメント
- `options.md#embedded-language-formatting` → 埋め込み言語オプション

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

本画面は静的ドキュメントページのため、データベース更新は発生しません。

## メッセージ仕様

本画面は静的ドキュメントページのため、動的メッセージはありません。

## 例外処理

| 状態 | 説明 |
|------|------|
| ページ未発見（404） | URLが誤っている場合、Docusaurus標準の404ページを表示 |

## 備考

- unpkg.comからのCDN読み込み例が多数記載されている
- JavaScript/TypeScript/Flow/JSONのフォーマットには`estree`プラグインも必要
- `%PRETTIER_VERSION%`プレースホルダーはビルド時に実際のバージョンに置換される
- `browser`フィールドがpackage.jsonで`standalone.js`を指定しているため、バンドラー使用時は自動でstandalone版が選択される

---

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

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

### 推奨読解順序

#### Step 1: ドキュメントコンテンツを理解する

本画面のコンテンツはMarkdownファイルで管理されています。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | browser.md | `docs/browser.md` | ブラウザ版使用方法全体像を理解 |

**読解のコツ**: Docusaurusの`import Tabs from "@theme/Tabs"`でタブコンポーネントをインポートし、Worker種別のコマンドを表示しています。

#### Step 2: standalone版のビルド構成を理解する

Prettier standalone版のビルド構成を確認します。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | package.json | `package.json` | browserフィールドの設定 |
| 2-2 | standalone.mjs | `standalone.mjs` | ESM版エントリーポイント |

**主要処理フロー**:
1. package.jsonの`browser`フィールドで`standalone.js`を指定
2. `unpkg`フィールドで`standalone.js`を指定
3. バンドラーやCDNが適切なファイルを選択

#### Step 3: プラグインの読み込み方式を理解する

ブラウザ版でのプラグイン読み込みを確認します。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | plugins/ | `plugins/` | 各言語用プラグインファイル |

**主要処理フロー**:
- 各プラグインは個別ファイルとして提供
- ユーザーが必要なプラグインを明示的に読み込む
- format関数の`plugins`オプションで渡す

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

```
Browser Environment
    │
    ├─ standalone.js (UMD) or standalone.mjs (ESM)
    │      │
    │      └─ prettier.format(code, options)
    │
    └─ plugins/*.js or plugins/*.mjs
           │
           ├─ babel (JavaScript)
           ├─ typescript
           ├─ html
           ├─ css
           ├─ graphql
           ├─ markdown
           ├─ yaml
           └─ estree (AST printing)
```

### データフロー図

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

<script> タグ
  or
import文 ─────────────────▶ standalone.js/mjs
                                   │
プラグイン ───────────────────────▶│
(babel, html, etc.)                │
                                   ▼
ソースコード ────────────▶ prettier.format(code, {
                             parser: "...",
                             plugins: [...]
                           })
                                   │
                                   ▼
                           フォーマット済みコード
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| browser.md | `docs/browser.md` | ドキュメント | ブラウザ版ガイド |
| package.json | `package.json` | 設定 | browserフィールド定義 |
| standalone.mjs | `standalone.mjs` | ソース | ESM版エントリーポイント |
| standalone.js | `standalone.js` | ソース | UMD版エントリーポイント |
| plugins/ | `plugins/` | ソース | 各言語用プラグイン |
| options.md | `docs/options.md` | ドキュメント | オプションドキュメント（関連参照） |
| api.md | `docs/api.md` | ドキュメント | APIドキュメント（関連参照） |
| plugins.md | `docs/plugins.md` | ドキュメント | プラグインドキュメント（関連参照） |
