Bubbletea TUI開発

GoとBubbletea、Lipglossで美しいターミナルユーザーインターフェースを構築するための本番対応スキルです。

このスキルを使用する場合

このスキルは以下の場合に使用します：

• Goで新しいTUIアプリケーションを作成する
• 既存アプリにBubbleteatコンポーネントを追加する
• レイアウト/レンダリングの問題を修正する（境界線、配置、オーバーフロー）
• マウス/キーボード操作を実装する
• デュアルペインまたはマルチパネルレイアウトを構築する
• ビジュアルエフェクト（メタボール、波、虹色テキスト）を追加する
• TUIレンダリングの問題をトラブルシューティングする

コア原則

重要: レイアウト実装前にreferences/golden-rules.mdの4つのゴールデンルールを必ず確認してください。これらのルールはTUIレイアウトで最も一般的で煩雑なバグを防ぎます。

4つのゴールデンルール（概要）

1. 常に境界線を考慮する - パネルレンダリング前に高さ計算から2を差し引く
2. 境界線付きパネルで自動折り返しを使用しない - 常にテキストを明示的に切り詰める
3. マウス検出をレイアウトに合わせる - 水平方向はX座標、垂直方向はY座標を使用
4. ピクセルではなくウェイトを使用する - 比例レイアウトは完璧にスケーリングする

詳細と例はreferences/golden-rules.mdを参照してください。

新しいプロジェクトの作成

このプロジェクトには本番対応のテンプレートシステムが含まれています。このスキルが新しいプロジェクトにバンドルされる場合（new_project.sh経由）、既存のテンプレート構造を出発点として使用してください。

プロジェクト構造

すべての新しいプロジェクトは以下のアーキテクチャに従います：

your-app/
├── main.go              # エントリーポイント（最小限、~21行）
├── types.go             # 型定義、構造体、列挙型
├── model.go             # モデル初期化とレイアウト計算
├── update.go            # メッセージディスパッチャー
├── update_keyboard.go   # キーボード操作
├── update_mouse.go      # マウス操作
├── view.go              # ビューレンダリングとレイアウト
├── styles.go            # Lipglossスタイル定義
├── config.go            # 設定管理
└── .claude/skills/bubbletea/  # このスキル（バンドル）

アーキテクチャガイドライン

• main.goは最小限にしてください（エントリーポイントのみ、~21行）
• すべての型をtypes.goに記載します（構造体、列挙型、定数）
• キーボードとマウス操作を専用ファイルに分ける
• 1ファイル、1つの責務
• 最大ファイルサイズ: 800行（理想は500行以下）
• YAMLで設定し、ホットリロード対応

利用可能なコンポーネント

references/components.mdの再利用可能なコンポーネント完全カタログを参照してください：

• パネルシステム: シングル、デュアルペイン、マルチパネル、タブレイアウト
• リスト: シンプルリスト、フィルター付きリスト、ツリービュー
• 入力: テキスト入力、複数行、フォーム、オートコンプリート
• ダイアログ: 確認、入力、進捗、モーダル
• メニュー: コンテキストメニュー、コマンドパレット、メニューバー
• ステータス: ステータスバー、タイトルバー、パンくず
• プレビュー: テキスト、Markdown、シンタックスハイライト、画像、16進数
• テーブル: シンプルテーブルとインタラクティブテーブル

エフェクトライブラリ

テンプレートで利用可能な物理ベースのアニメーション：

• 🔮 メタボール - ラバランプ風の浮遊ブロブ
• 🌊 波エフェクト - サイン波歪み
• 🌈 虹色サイクリング - アニメーション色グラデーション
• 🎭 レイヤーコンポジター - ANSI対応マルチレイヤーレンダリング

使用例と統合パターンについてはreferences/effects.mdを参照してください。

レイアウト実装パターン

レイアウト実装時は以下の順序に従ってください：

1. 利用可能なスペースを計算する

func (m model) calculateLayout() (int, int) {
    contentWidth := m.width
    contentHeight := m.height

    // UI要素を差し引く
    if m.config.UI.ShowTitle {
        contentHeight -= 3  // タイトルバー（3行）
    }
    if m.config.UI.ShowStatus {
        contentHeight -= 1  // ステータスバー
    }

    // 重要: パネル境界線を考慮する
    contentHeight -= 2  // 上+下の境界線

    return contentWidth, contentHeight
}

2. ウェイトベースのパネルサイジングを使用する

// フォーカス/アコーディオンモードに基づいてウェイトを計算
leftWeight, rightWeight := 1, 1
if m.accordionMode && m.focusedPanel == "left" {
    leftWeight = 2  // フォーカスされたパネルは2倍のウェイト
}

// ウェイトから実際の幅を計算
totalWeight := leftWeight + rightWeight
leftWidth := (availableWidth * leftWeight) / totalWeight
rightWidth := availableWidth - leftWidth

3. テキストを切り詰めて折り返しを防ぐ

// 折り返しを防ぐための最大テキスト幅を計算
maxTextWidth := panelWidth - 4  // -2境界線、-2パディング

// レンダリング前にすべてのテキストを切り詰める
title = truncateString(title, maxTextWidth)
subtitle = truncateString(subtitle, maxTextWidth)

func truncateString(s string, maxLen int) string {
    if len(s) <= maxLen {
        return s
    }
    return s[:maxLen-1] + "…"
}

マウス操作パターン

マウスイベント処理前に常にレイアウトモードをチェックしてください：

func (m model) handleLeftClick(msg tea.MouseMsg) (tea.Model, tea.Cmd) {
    if m.shouldUseVerticalStack() {
        // 縦スタックモード: Y座標を使用
        topHeight, _ := m.calculateVerticalStackLayout()
        relY := msg.Y - contentStartY

        if relY < topHeight {
            m.focusedPanel = "left"  // 上のパネル
        } else {
            m.focusedPanel = "right" // 下のパネル
        }
    } else {
        // 横並びモード: X座標を使用
        leftWidth, _ := m.calculateDualPaneLayout()

        if msg.X < leftWidth {
            m.focusedPanel = "left"
        } else {
            m.focusedPanel = "right"
        }
    }

    return m, nil
}

避けるべき一般的な落とし穴

一般的な問題の詳細な解決策はreferences/troubleshooting.mdを参照してください：

❌ しない: 境界線付きパネルに明示的なHeight()を設定する

// 悪い例: 配置ずれの原因となる可能性がある
panelStyle := lipgloss.NewStyle().
    Border(border).
    Height(height)  // これはしないでください！

✅ する: コンテンツを正確な高さに埋める

// 良い例: コンテンツ行を正確な高さに埋める
for len(lines) < innerHeight {
    lines = append(lines, "")
}
panelStyle := lipgloss.NewStyle().Border(border)

テストとデバッグ

パネルが配置されていないか、正しくレンダリングされていない場合：

1. 高さのアカウンティングを確認 - contentHeight計算がすべてのUI要素+境界線を差し引いているか確認
2. テキストの折り返しを確認 - すべての文字列がmaxTextWidthに切り詰められているか確認
3. マウス検出を確認 - X/Y座標の使用がレイアウト方向と一致しているか確認
4. 境界線の一貫性を確認 - すべてのパネルで同じ境界線スタイルを使用しているか確認

完全なデバッグ決定木はreferences/troubleshooting.mdを参照してください。

設定システム

すべてのプロジェクトはYAMLの設定とホットリロードをサポートしています：

theme: "dark"
keybindings: "default"

layout:
  type: "dual_pane"
  split_ratio: 0.5
  accordion_mode: true

ui:
  show_title: true
  show_status: true
  mouse_enabled: true
  show_icons: true

設定ファイルは以下から読み込まれます：

1. ~/.config/your-app/config.yaml（ユーザー設定）
2. ./config.yaml（ローカルオーバーライド）

依存関係

必須:

github.com/charmbracelet/bubbletea
github.com/charmbracelet/lipgloss
github.com/charmbracelet/bubbles
gopkg.in/yaml.v3

オプション（必要に応じてgo.modのコメントを外す）:

github.com/charmbracelet/glamour       # Markdownレンダリング
github.com/charmbracelet/huh           # フォーム
github.com/alecthomas/chroma/v2        # シンタックスハイライト
github.com/evertras/bubble-table       # インタラクティブテーブル
github.com/koki-develop/go-fzf         # ファジーファインダー

リファレンスドキュメント

すべてのリファレンスファイルは必要に応じて段階的に読み込まれます：

• golden-rules.md - クリティカルなレイアウトパターンとアンチパターン
• components.md - 再利用可能なコンポーネント完全カタログ
• troubleshooting.md - 一般的な問題とデバッグ決定木
• emoji-width-fix.md - 複数のターミナル（xterm、WezTerm、Termux、Windows Terminal）間での絵文字配置のための実証済みソリューション

外部リソース

• Bubbletea ドキュメント
• Lipgloss ドキュメント
• Bubbles コンポーネント
• Charm エコシステム

ベストプラクティスの概要

1. 常にレイアウト実装前にgolden-rules.mdを確認する
2. 常に柔軟なレイアウトにウェイトベースのサイジングを使用する
3. 常にテキストを明示的に切り詰める（自動折り返しに頼らない）
4. 常にマウス検出をレイアウト方向に合わせる
5. 常に高さ計算で境界線を考慮する
6. 決して境界線付きLipglossスタイルに明示的なHeight()を設定しない
7. 決してマウスハンドラーでレイアウト方向を想定しない

これらのパターンに従えば、TUIレイアウトバグの90%を回避できます。