# 帳票設計書 6-list-colors

## 概要

本ドキュメントは、Ghosttyターミナルエミュレータの `list-colors` コマンドが出力するカラー一覧の設計書です。

### 本帳票の処理概要

`list-colors` コマンドは、X11名前付きRGBカラーの一覧を標準出力に表示するCLIリストです。TTY出力時はカラー付きの整形出力、パイプ時はプレーンテキスト出力となります。

**業務上の目的・背景**：ユーザーがGhosttyの設定で使用できる名前付きカラーを確認できるようにします。`foreground`、`background`などの色設定で名前指定が可能な色を一覧表示することで、設定ファイル作成の参考となります。

**帳票の利用シーン**：
- 設定ファイルで使用可能な色名の確認
- 色名とRGB値の対応確認
- テーマ作成時の色選択参考
- X11カラー名の参照

**主要な出力内容**：
1. 色名（アルファベット順）
2. RGB値（16進数形式）
3. 色見本（TTY時）

**帳票の出力タイミング**：`ghostty +list-colors` コマンド実行時

**帳票の利用者**：エンドユーザー、テーマ作成者、開発者

## 帳票種別

CLIリスト（テキスト形式 / カラー整形出力対応）

## 利用画面

| 画面No | 画面名 | URL/ルーティング | 出力操作 |
|--------|--------|-----------------|---------|
| - | CLI | `ghostty +list-colors` | コマンド実行 |
| - | CLI | `ghostty +list-colors --plain` | プレーン出力 |

## 出力形式

### 基本仕様

| 項目 | 内容 |
|-----|------|
| ファイル形式 | テキスト（stdout） |
| 用紙サイズ | N/A |
| 向き | N/A |
| ファイル名 | N/A（標準出力） |
| 出力方法 | 標準出力への表示 |
| 文字コード | UTF-8 |

### 端末出力固有設定

| 項目 | 内容 |
|-----|------|
| ハイパーリンク | 無 |
| カラー出力 | 有（TTY時、各色のRGBカラー表示） |
| インタラクティブ | 無 |

## 帳票レイアウト

### レイアウト概要

#### プレーン出力モード
```
┌─────────────────────────────────────┐
│  色名 = #RRGGBB                      │
│  色名 = #RRGGBB                      │
│  ...                                │
└─────────────────────────────────────┘
```

#### カラー出力モード（TTY）
```
┌─────────────────────────────────────────────────────────┐
│ 色名    = #RRGGBB ██  色名    = #RRGGBB ██  ...       │
│ 色名    = #RRGGBB ██  色名    = #RRGGBB ██  ...       │
│ ...                                                    │
└─────────────────────────────────────────────────────────┘
```

### ヘッダー部

ヘッダーはありません。

### 明細部（プレーン出力）

| No | 項目名 | 説明 | データ取得元 | 表示形式 |
|----|-------|------|-------------|---------|
| 1 | 色名 | X11カラー名 | x11_color.map.keys() | "{s}" |
| 2 | RGB値 | 16進数RGB | x11_color.map.get(name) | "#RRGGBB" |

### 明細部（カラー出力）

| No | 項目名 | 説明 | データ取得元 | 表示形式 |
|----|-------|------|-------------|---------|
| 1 | 色名 | X11カラー名 | x11_color.map.keys() | "{s}" (パディング付き) |
| 2 | 区切り | 等号記号 | 固定 | " = " |
| 3 | RGB値 | 16進数RGB（カラー付き） | x11_color.map.get(name) | "#RRGGBB" (fg=色) |
| 4 | 色見本 | カラーブロック | rgb値 | "  " (bg=色) |

### フッター部

フッターはありません。

## 出力条件

### 抽出条件

| 条件名 | 説明 | 必須 |
|-------|------|-----|
| --plain | プレーン出力を強制 | No |

### ソート順

| 優先度 | 項目 | 昇順/降順 |
|-------|------|---------|
| 1 | 色名 | 昇順（大文字小文字無視） |

### 改ページ条件

改ページなし（連続出力）

## データベース参照仕様

### 参照テーブル一覧

データベース参照はありません。

### データ取得元詳細

| 取得元 | 用途 | 取得方法 |
|-------|------|---------|
| x11_color.map | X11カラーマップ | コンパイル時定数マップ |

## 計算仕様

### 計算項目一覧

| 項目名 | 計算式 | 端数処理 | 備考 |
|-------|-------|---------|------|
| max_name_len | 最長色名の文字数 | - | 列幅計算用 |
| column_size | max_name_len + 15 | - | 1列の幅 |
| columns | (win.width + 2) / column_size | 切り捨て | 列数計算 |

## 処理フロー

### 出力フロー

```mermaid
flowchart TD
    A[コマンド実行] --> B[オプション解析]
    B --> C[x11_color.mapからキー取得]
    C --> D[色名でソート]
    D --> E{TTYかつ--plain未指定?}
    E -->|Yes| F[prettyPrint処理]
    E -->|No| G[プレーン出力]
    F --> H[vaxis初期化]
    H --> I[最長色名計算]
    I --> J[列数計算]
    J --> K[行ごとにカラー出力]
    G --> L[各色を出力]
    K --> M[バッファフラッシュ]
    L --> M
    M --> N[終了コード0を返却]
```

## エラー処理

### エラーケース一覧

| エラー種別 | 発生条件 | 表示メッセージ | 対処方法 |
|----------|---------|--------------|---------|
| 出力失敗 | stdoutへの書き込みエラー | なし（エラー返却） | プロセス終了 |

## パフォーマンス要件

| 項目 | 内容 |
|-----|------|
| 想定データ件数 | X11カラー定義数（約750色） |
| 目標出力時間 | 即時（1秒未満） |
| 同時出力数上限 | N/A |

## セキュリティ考慮事項

- 静的なカラーマップのみを参照
- ファイルシステムアクセスなし
- ユーザー入力は--plainオプションのみ

## 備考

- X11カラーはターミナルで広く使用される標準的な名前付きカラー
- vaxisライブラリでカラー出力とウィンドウサイズ取得
- Unicode mode 2027を有効化

---

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

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

### 推奨読解順序

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

X11カラーマップの構造を理解します。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | list_colors.zig | `src/cli/list_colors.zig` | Options構造体（10-23行目） |
| 1-2 | color.zig | `src/terminal/color.zig` | x11_color.map定義 |

**読解のコツ**: x11_color.mapはコンパイル時に生成される静的なHashMapです。

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | list_colors.zig | `src/cli/list_colors.zig` | run関数（32-74行目）がエントリーポイント |

**主要処理フロー**:
1. **33-40行目**: オプション解析
2. **42-44行目**: x11_color.mapからキー取得
3. **46-50行目**: アルファベット順ソート
4. **54-71行目**: TTY判定と出力分岐

#### Step 3: カラー出力処理を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | list_colors.zig | `src/cli/list_colors.zig` | prettyPrint関数（76-209行目） |

**主要処理フロー**:
1. **78-102行目**: vaxis初期化
2. **106-109行目**: 最長色名計算
3. **112-114行目**: 列サイズと列数計算
4. **116-206行目**: 各色の出力ループ

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

```
ghostty (main)
    │
    └─ Action.run (ghostty.zig:99)
           │
           └─ list_colors.run (list_colors.zig:32)
                  │
                  ├─ args.parse (オプション解析)
                  │
                  ├─ x11_color.map.keys() (色名取得)
                  │
                  ├─ std.mem.sortUnstable (ソート)
                  │
                  └─ prettyPrint / プレーン出力
                         │
                         ├─ vaxis.init (TTY時)
                         │
                         ├─ x11_color.map.get (RGB取得)
                         │
                         └─ win.printSegment (出力)
```

### データフロー図

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

x11_color.map ───▶ keys()取得
                      │
                      ▼
                   ソート
                      │
            ┌─────────┴─────────┐
            ▼                   ▼
       prettyPrint          プレーン出力
            │                   │
            ▼                   ▼
    ┌───────────────┐    名前 = #RRGGBB
    │ 名前 = #RGB ██│
    │ (複数列)      │
    └───────────────┘
            │                   │
            └─────────┬─────────┘
                      │
                      ▼
                  stdout
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| list_colors.zig | `src/cli/list_colors.zig` | ソース | メイン処理 |
| ghostty.zig | `src/cli/ghostty.zig` | ソース | Actionディスパッチャー |
| args.zig | `src/cli/args.zig` | ソース | 引数解析ユーティリティ |
| tui.zig | `src/cli/tui.zig` | ソース | TUI共通機能 |
| color.zig | `src/terminal/color.zig` | ソース | X11カラーマップ定義 |
