gpui-component

# gpui-component Best Practices Comprehensive guide for building UI components with [gpui-component](https://github.com/longbridge/gpui-component), a component library for GPUI applications. ## When to Apply Reference these guidelines when: - Creating reusable UI components - Implementing theme-aware styling - Building dialogs, popovers, or sheets - Creating form components (Input, Checkbox, etc.) - Implementing component animations - Following Longbridge component patterns ## Rule Categories by Priority | Priority | Category | Impact | Prefix | |----------|----------|--------|--------| | 1 | Component Architecture | CRITICAL | `comp-` | | 2 | Trait System | CRITICAL | `trait-` | | 3 | Theme System | HIGH | `theme-` | | 4 | Dialog & Popover | HIGH | `dialog-` | | 5 | Form Components | MEDIUM | `form-` | | 6 | Animation | MEDIUM | `anim-` | ## Quick Reference ### 1. Component Architecture (CRITICAL) - `comp-renderonce` - Use RenderOnce with #[derive(IntoElement)] - `comp-structure` - Standard component structure template - `comp-builder` - Fluent builder pattern for components - `comp-stateful` - Entity + RenderOnce for stateful components - `comp-callbacks` - Use Rc<dyn Fn> for event callbacks ### 2. Trait System (CRITICAL) - `trait-styled` - Implement Styled for style customization - `trait-disableable` - Implement Disableable for disabled state - `trait-selectable` - Implement Selectable for selection state - `trait-sizable` - Implement Sizable with Size enum - `trait-parent-element` - Implement ParentElement for children - `trait-interactive` - Implement InteractiveElement for events ### 3. Theme System (HIGH) - `theme-colors` - Use ThemeColor for consistent colors - `theme-active` - Use ActiveTheme trait for theme access - `theme-variants` - Implement variant enums (ButtonVariant, etc.) - `theme-size-system` - Use StyleSized for size-based styling ### 4. Dialog & Popover (HIGH) - `dialog-root` - Use Root component as window root - `dialog-window-ext` - Use WindowExt for dialog management - `dialog-confirm` - Implement confirm/alert dialogs - `dialog-form` - Build form dialogs with input state - `popover-pattern` - Popover vs PopupMenu vs Sheet selection ### 5. Form Components (MEDIUM) - `form-input-state` - Entity-based input state management - `form-focus` - Focus management with keyed state - `form-validation` - Input validation patterns ### 6. Animation (MEDIUM) - `anim-with-animation` - Use with_animation for transitions - `anim-keyed-state` - Persist animation state with use_keyed_state - `anim-easing` - Use cubic_bezier for smooth animations ## Component Structure Template ```rust #[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)>>, } ``` ## Architecture Overview ``` ┌─────────────────────────────────────────────────────────────┐ │ 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 │ └─────────────────────────────────────────────────────────────┘ ``` ## Popup Component Comparison | Feature | Dialog | Popover | PopupMenu | Sheet | |---------|--------|---------|-----------|-------| | Position | Centered | Anchored | Anchored | Side | | Overlay | Yes | No | No | Yes | | State | Root | keyed_state | Entity | Root | | Stacking | Multiple | Single | Submenus | Single | | Close | ESC/Click/Button | ESC/Outside | ESC/Select | ESC/Overlay | ## How to Use Read individual rule files for detailed explanations and code examples: ``` rules/comp-renderonce.md rules/trait-styled.md rules/dialog-root.md ``` Each rule file contains: - Brief explanation of why it matters - Code examples with correct patterns - Common mistakes to avoid