gpui-component

gpui-component のベストプラクティス

GPUI アプリケーション向けコンポーネントライブラリである gpui-component を使って UI コンポーネントを構築するための包括的なガイドです。

適用する場面

以下の場合は、これらのガイドラインを参照してください。

• 再利用可能な UI コンポーネントを作成するとき
• テーマに対応したスタイルを実装するとき
• ダイアログ、ポップオーバー、シートを構築するとき
• フォームコンポーネント（Input、Checkbox など）を作成するとき
• コンポーネントのアニメーションを実装するとき
• Longbridge のコンポーネントパターンに従うとき

優先度別のルールカテゴリ

優先度	カテゴリ	影響度	接頭辞
1	コンポーネントアーキテクチャ	CRITICAL	comp-
2	トレイトシステム	CRITICAL	trait-
3	テーマシステム	HIGH	theme-
4	ダイアログとポップオーバー	HIGH	dialog-
5	フォームコンポーネント	MEDIUM	form-
6	アニメーション	MEDIUM	anim-

クイックリファレンス

1. コンポーネントアーキテクチャ（CRITICAL）

• comp-renderonce - #[derive(IntoElement)] を使って RenderOnce を使用する
• comp-structure - 標準的なコンポーネント構造のテンプレート
• comp-builder - コンポーネントに流れるようなビルダーパターンを使用する
• comp-stateful - 状態を持つコンポーネントには Entity と RenderOnce を使用する
• comp-callbacks - イベントコールバックには Rc を使用する

2. トレイトシステム（CRITICAL）

• trait-styled - スタイルをカスタマイズできるよう Styled を実装する
• trait-disableable - 無効状態に対応するため Disableable を実装する
• trait-selectable - 選択状態に対応するため Selectable を実装する
• trait-sizable - Size enum とともに Sizable を実装する
• trait-parent-element - 子要素に対応するため ParentElement を実装する
• trait-interactive - イベントに対応するため InteractiveElement を実装する

3. テーマシステム（HIGH）

• theme-colors - 一貫した色使いのために ThemeColor を使用する
• theme-active - テーマにアクセスするには ActiveTheme トレイトを使用する
• theme-variants - バリアント enum（ButtonVariant など）を実装する
• theme-size-system - サイズに基づくスタイル設定には StyleSized を使用する

4. ダイアログとポップオーバー（HIGH）

• dialog-root - ウィンドウのルートとして Root コンポーネントを使用する
• dialog-window-ext - ダイアログの管理には WindowExt を使用する
• dialog-confirm - 確認／アラートダイアログを実装する
• dialog-form - 入力状態を持つフォームダイアログを構築する
• popover-pattern - Popover、PopupMenu、Sheet の使い分け

5. フォームコンポーネント（MEDIUM）

• form-input-state - Entity ベースの入力状態管理
• form-focus - キー付き状態によるフォーカス管理
• form-validation - 入力検証のパターン

6. アニメーション（MEDIUM）

• anim-with-animation - トランジションには with_animation を使用する
• anim-keyed-state - use_keyed_state でアニメーション状態を保持する
• anim-easing - 滑らかなアニメーションには cubic_bezier を使用する

コンポーネント構造のテンプレート

#[derive(IntoElement)]
pub struct MyComponent {
    // 1. Identifier
    id: ElementId,

    // 2. Base element (for event delegation)
    base: Div,

    // 3. Style override
    style: StyleRefinement,

    // 4. Content
    label: Option<SharedString>,
    children: Vec<AnyElement>,

    // 5. State configuration
    disabled: bool,
    selected: bool,
    size: Size,

    // 6. Callbacks
    on_click: Option<Rc<dyn Fn(&ClickEvent, &mut Window, &mut App)>>,
}

アーキテクチャの概要

┌─────────────────────────────────────────────────────────────┐
│  Window                                                      │
│  ├── Root (Entity, manages overlay state)                   │
│  │   ├── view: AnyView (user's main view)                   │
│  │   ├── active_dialogs: Vec<ActiveDialog>                  │
│  │   ├── active_sheet: Option<ActiveSheet>                  │
│  │   └── notification: Entity<NotificationList>             │
│  │                                                          │
│  └── Render Layers                                          │
│      ├── Layer 0: Root.view (main content)                  │
│      ├── Layer 1: Sheet (side drawer)                       │
│      ├── Layer 2: Dialogs (stackable)                       │
│      └── Layer 3: Notifications                             │
└─────────────────────────────────────────────────────────────┘

ポップアップコンポーネントの比較

機能	Dialog	Popover	PopupMenu	Sheet
位置	中央	アンカー基準	アンカー基準	側面
オーバーレイ	あり	なし	なし	あり
状態	Root	keyed_state	Entity	Root
重ね合わせ	複数	1 つ	サブメニュー	1 つ
閉じ方	ESC／クリック／ボタン	ESC／外側をクリック	ESC／選択	ESC／オーバーレイ

使用方法

詳しい説明とコード例については、各ルールファイルを参照してください。

rules/comp-renderonce.md
rules/trait-styled.md
rules/dialog-root.md

各ルールファイルには以下が含まれています。

• 重要である理由の簡単な説明
• 正しいパターンを示すコード例
• 避けるべきよくある間違い