# 帳票設計書 5-list-themes

## 概要

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

### 本帳票の処理概要

`list-themes` コマンドは、利用可能なテーマをリスト形式またはインタラクティブなTUIプレビューで表示するCLIリストです。TTY出力時はテーマプレビューUI、パイプ時はプレーンテキスト出力となります。

**業務上の目的・背景**：ユーザーがGhosttyで利用可能なカラーテーマを確認し、好みのテーマを選択できるようにします。TUIプレビューでは実際の配色を確認しながらテーマを選べるため、設定変更前にビジュアル確認が可能です。

**帳票の利用シーン**：
- 利用可能なテーマの一覧確認
- テーマのプレビュー（TTY時）
- テーマ名のクリップボードコピー
- 設定ファイルへのテーマ適用

**主要な出力内容**：
1. テーマ名
2. テーマの所在（user/bundled）
3. テーマのフルパス（--path指定時）
4. カラーパレットプレビュー（TUI時）
5. シンタックスハイライトプレビュー（TUI時）

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

**帳票の利用者**：エンドユーザー、デザイナー

## 帳票種別

CLIリスト（テキスト形式 / TUIプレビュー対応）

## 利用画面

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

## 出力形式

### 基本仕様

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

### 端末出力固有設定

| 項目 | 内容 |
|-----|------|
| ハイパーリンク | 有（TUI時、テーマファイルへのfile://リンク） |
| カラー出力 | 有（TUI時、テーマのカラーパレット表示） |
| インタラクティブ | 有（TUI時） |

### TUIモード機能

| 機能 | 説明 | キー操作 |
|------|------|---------|
| テーマ選択 | 上下キーでテーマ選択 | j/k, Up/Down |
| プレビュー | 選択テーマのプレビュー表示 | 自動 |
| 検索 | テーマ名のフィルタリング | / |
| ヘルプ | 操作説明表示 | F1, ? |
| コピー | テーマ名をクリップボードにコピー | c |
| パスコピー | テーマパスをクリップボードにコピー | C |
| 保存 | テーマをauto設定に書き込み | w |
| フィルタ | dark/light/allフィルタ切替 | f |
| 終了 | TUIを終了 | q, Esc |

## 帳票レイアウト

### レイアウト概要

#### プレーン出力モード
```
┌─────────────────────────────────────┐
│  テーマ名 (location)                 │
│  テーマ名 (location)                 │
│  ...                                │
└─────────────────────────────────────┘
```

#### TUIモード
```
┌─────────────────────────────────────────────────────────┐
│ テーマリスト     │           プレビュー領域              │
│ ❯ テーマ1   ❮   │  テーマ名（中央表示）                  │
│   テーマ2       │  パス（中央表示）                      │
│   テーマ3       │  16色パレット表示                      │
│   ...          │  コードプレビュー                       │
│                │  Lorem ipsum...                        │
└─────────────────────────────────────────────────────────┘
```

### ヘッダー部

ヘッダーはありません。

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

| No | 項目名 | 説明 | データ取得元 | 表示形式 |
|----|-------|------|-------------|---------|
| 1 | テーマ名 | テーマファイル名 | entry.name | "{s}" |
| 2 | 所在 | user/bundled | loc.location | "({t})" |
| 3 | パス | ファイルパス | theme.path | " {s}" (--path時) |

### 明細部（TUI）

| No | 項目名 | 説明 | データ取得元 |
|----|-------|------|-------------|
| 1 | テーマリスト | 選択可能なテーマ一覧 | themes配列 |
| 2 | 選択マーカー | 現在選択中のテーマ | self.current |
| 3 | プレビュータイトル | テーマ名 | theme.theme |
| 4 | プレビューパス | テーマファイルパス | theme.path |
| 5 | カラーパレット | 16色表示 | config.palette |
| 6 | コードプレビュー | Zigコードのシンタックスハイライト | 固定テキスト |
| 7 | Lorem ipsum | テキストスタイルプレビュー | 固定テキスト |

### フッター部

フッターはありません。

## 出力条件

### 抽出条件

| 条件名 | 説明 | 必須 |
|-------|------|-----|
| --path | フルパスを表示 | No |
| --plain | プレーン出力を強制 | No |
| --color | dark/light/allでフィルタ | No（デフォルト: all） |

### ソート順

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

### 改ページ条件

TUIモード時はスクロールで対応

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

### 参照テーブル一覧

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

### データ取得元詳細

| 取得元 | 用途 | 取得方法 |
|-------|------|---------|
| themepkg.LocationIterator | テーマディレクトリ検索 | ファイルシステム走査 |
| Config.loadFile | テーマ設定読み込み | 設定ファイルパース |
| global_state.resources_dir | リソースディレクトリ | 環境変数/デフォルトパス |

### テーマ検索ディレクトリ

1. `$XDG_CONFIG_HOME/ghostty/themes` または `~/.config/ghostty/themes`（ユーザーテーマ）
2. `Ghostty.app/Contents/Resources/ghostty/themes`（macOS、バンドルテーマ）
3. `share/ghostty/themes`（Linux、バンドルテーマ）

## 計算仕様

### 計算項目一覧

| 項目名 | 計算式 | 端数処理 | 備考 |
|-------|-------|---------|------|
| luminance | 0.2126*R + 0.7152*G + 0.0722*B | - | dark/light判定用 |
| is_dark | luminance < 0.5 | - | テーマフィルタ用 |

## 処理フロー

### 出力フロー

```mermaid
flowchart TD
    A[コマンド実行] --> B[オプション解析]
    B --> C[テーマディレクトリ検索]
    C --> D[テーマファイル一覧取得]
    D --> E[テーマ名でソート]
    E --> F{TTYかつ--plain未指定?}
    F -->|Yes| G[TUIプレビュー起動]
    F -->|No| H[プレーン出力]
    G --> I[イベントループ開始]
    I --> J{終了イベント?}
    J -->|No| K[画面更新]
    K --> I
    J -->|Yes| L[TUI終了]
    H --> M[各テーマ出力]
    M --> N[バッファフラッシュ]
    L --> O[終了コード0を返却]
    N --> O
```

## エラー処理

### エラーケース一覧

| エラー種別 | 発生条件 | 表示メッセージ | 対処方法 |
|----------|---------|--------------|---------|
| テーマなし | テーマが見つからない | "No themes found..." | stderrに警告出力、終了コード1 |
| リソースディレクトリなし | リソースディレクトリが見つからない | "Could not find the Ghostty resources directory..." | stderrに警告出力 |
| テーマ読み込み失敗 | テーマファイル不正 | TUI内にエラー表示 | プレビューにエラー表示 |

## パフォーマンス要件

| 項目 | 内容 |
|-----|------|
| 想定データ件数 | 数百テーマ |
| 目標出力時間 | TUI起動: 1秒以内 |
| 同時出力数上限 | N/A |

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

- テーマファイルは設定ファイルとして読み込まれる
- ファイルシステムへの書き込みは`w`キーでのauto設定のみ
- ユーザー確認なしでの設定変更が可能

## 備考

- SMALL_LIST_THRESHOLD (10) 以下の検索結果時はスクロール位置リセット
- zfライブラリによるファジー検索をサポート
- vaxisライブラリでTUI描画

---

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

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

### 推奨読解順序

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

テーマ情報の構造を理解します。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | list_themes.zig | `src/cli/list_themes.zig` | Options構造体（21-40行目） |
| 1-2 | list_themes.zig | `src/cli/list_themes.zig` | ThemeListElement構造体（42-67行目） |
| 1-3 | list_themes.zig | `src/cli/list_themes.zig` | Preview構造体（232-290行目） |

**読解のコツ**: ThemeListElementはテーマのメタデータを保持し、Preview構造体はTUIの状態管理を担当します。

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

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

**主要処理フロー**:
1. **107-114行目**: オプション解析
2. **137-168行目**: テーマディレクトリ走査
3. **175行目**: テーマ名ソート
4. **177-180行目**: TUIプレビュー起動判定
5. **182-193行目**: プレーン出力処理

#### Step 3: TUIプレビューを理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | list_themes.zig | `src/cli/list_themes.zig` | Preview.run関数（292-323行目） |
| 3-2 | list_themes.zig | `src/cli/list_themes.zig` | Preview.update関数（432-526行目）でキーイベント処理 |
| 3-3 | list_themes.zig | `src/cli/list_themes.zig` | Preview.draw関数（598-868行目）で画面描画 |
| 3-4 | list_themes.zig | `src/cli/list_themes.zig` | Preview.drawPreview関数（870-1708行目）でプレビュー描画 |

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

```
ghostty (main)
    │
    └─ Action.run (ghostty.zig:99)
           │
           └─ list_themes.run (list_themes.zig:106)
                  │
                  ├─ args.parse (オプション解析)
                  │
                  ├─ themepkg.LocationIterator (テーマ検索)
                  │      │
                  │      └─ dir.iterate (ディレクトリ走査)
                  │
                  ├─ std.mem.sortUnstable (ソート)
                  │
                  └─ preview / プレーン出力
                         │
                         ├─ Preview.init (TUI初期化)
                         │
                         ├─ Preview.run (イベントループ)
                         │      │
                         │      ├─ loop.pollEvent
                         │      ├─ Preview.update
                         │      └─ Preview.draw
                         │
                         └─ vx.render (画面描画)
```

### データフロー図

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

テーマディレクトリ ───▶ LocationIterator
                           │
                           ▼
                    ファイル走査
                           │
    ┌──────────────────────┼──────────────────────┐
    ▼                      ▼                      ▼
user themes         bundled themes         ThemeListElement[]
    │                      │                      │
    └──────────────────────┼──────────────────────┘
                           │
                           ▼
                        ソート
                           │
            ┌──────────────┴──────────────┐
            ▼                             ▼
       TUIプレビュー                  プレーン出力
            │                             │
            ▼                             ▼
    ┌───────────────┐              stdout
    │ テーマリスト   │
    │ プレビュー    │
    │ 操作         │
    └───────────────┘
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| list_themes.zig | `src/cli/list_themes.zig` | ソース | メイン処理 |
| ghostty.zig | `src/cli/ghostty.zig` | ソース | Actionディスパッチャー |
| args.zig | `src/cli/args.zig` | ソース | 引数解析ユーティリティ |
| tui.zig | `src/cli/tui.zig` | ソース | TUI共通機能 |
| theme.zig | `src/config/theme.zig` | ソース | テーマ設定 |
| Config.zig | `src/config/Config.zig` | ソース | 設定管理 |
| lorem_ipsum.txt | `src/cli/lorem_ipsum.txt` | データ | プレビュー用テキスト |
