Skip to content

CLAUDE.md

Latest commit

 

History

History
222 lines (157 loc) · 6.73 KB

CLAUDE.md

File metadata and controls

222 lines (157 loc) · 6.73 KB

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Project Overview

GPUI Component is a UI component library for building desktop applications using GPUI. It provides 60+ cross-platform desktop UI components, inspired by macOS/Windows controls and combined with shadcn/ui design.

This is a Rust workspace project with the following main crates:

  • crates/ui - Core UI component library (published as gpui-component)
  • crates/story - Gallery application for showcasing and testing components
  • crates/story-web - Web version of the story gallery (using WebAssembly)
  • crates/macros - Procedural macros (IntoPlot derive)
  • crates/assets - Static assets
  • crates/webview - WebView component support
  • examples/ - Various example applications

Common Commands

Development and Testing

# Run Story Gallery (component showcase application)
cargo run

# Run individual examples
cargo run --example hello_world
cargo run --example table

# Build the project
cargo build

# Lint check
cargo clippy -- --deny warnings

# Format check
cargo fmt --check

# Spell check
typos

# Check for unused dependencies
cargo machete

Testing

Note: Per user configuration, tests do not need to be run.

# Run all tests
cargo test --all

# Run tests for a specific crate
cargo test -p gpui-component

# Run doc tests
cargo test -p gpui-component --doc

Performance Profiling

# View FPS on macOS (using Metal HUD)
MTL_HUD_ENABLED=1 cargo run

# Profile performance using samply
samply record cargo run

Core Architecture

Component Initialization

Critical requirement: You must call gpui_component::init(cx) at your application's entry point before using any GPUI Component features.

fn main() {
    let app = Application::new();
    app.run(move |cx| {
        // This must be called first
        gpui_component::init(cx);

        cx.spawn(async move |cx| {
            cx.open_window(WindowOptions::default(), |window, cx| {
                let view = cx.new(|_| MyView);
                // The first level view in a window must be a Root
                cx.new(|cx| Root::new(view, window, cx))
            })
            .expect("Failed to open window");
        }).detach();
    });
}

Root View System

Root is the top-level view for a window and manages:

  • Sheet (side panels)
  • Dialog (dialogs)
  • Notification (notifications)
  • Keyboard navigation (Tab/Shift-Tab)

The first view of every window must be a Root.

Theme System

  • Uses Theme global singleton for theme configuration
  • Supports light/dark mode switching
  • Access theme via ActiveTheme trait: cx.theme()
  • Theme configuration includes:
    • Colors (ThemeColor)
    • Syntax highlighting theme (HighlightTheme)
    • Font configuration (system font and monospace font)
    • UI parameters like border radius, shadows
    • Scrollbar display mode

Dock System

A complex panel layout system supporting:

  • DockArea: Main container managing center area and left/bottom/right docks
  • DockItem: Tree-based layout structure
    • Split: Split layout (horizontal/vertical)
    • Tabs: Tab layout
    • Panel: Individual panel
  • Panel: Defined via PanelView trait
  • PanelRegistry: Global panel registry for serializing/deserializing layouts
  • StackPanel: Resizable split panel container
  • TabPanel: Tab panel container

The Dock system supports:

  • Panel drag-and-drop reordering
  • Panel zoom
  • Layout locking
  • Layout serialization/restoration

Input System

Text input system based on Rope data structure:

  • InputState: Input state management
  • Rope: Efficient text storage (from ropey crate)
  • LSP integration support (diagnostics, completion, hover)
  • Syntax highlighting support (Tree-sitter)
  • Multiple input modes:
    • Regular input (Input)
    • Number input (NumberInput)
    • OTP input (OtpInput)

Component Design Principles

  1. Stateless design: Use RenderOnce trait, components should be stateless when possible
  2. Size system: Supports xs, sm, md (default), lg sizes via Sizable trait.
  3. Mouse cursor: Buttons use default cursor not pointer (desktop app convention), unless it's a link button
  4. Style system: Provides CSS-like styling API via Styled trait and ElementExt extensions

Code Style

  • Follow naming and organization patterns from existing code
  • Reference macOS/Windows control API design for naming
  • AI-generated code must be refactored to match project style
  • Mark AI-generated portions when submitting PRs

Icon System

The Icon element does not include SVG files by default. You need to:

  • Use Lucide or other icon libraries
  • Name SVG files according to the IconName enum definition (located in crates/ui/src/icon.rs)

Dependencies

  • GPUI: Git version from Zed repository
  • Tree-sitter: For syntax highlighting
  • Ropey: Rope data structure for text, and RopeExt trait with more features.
  • Markdown rendering: markdown crate
  • HTML rendering: html5ever (basic support)
  • Charts: Built-in chart components
  • LSP: lsp-types crate

Internationalization

Uses rust-i18n crate.

  • Localization files are located in crates/ui/locales/.
  • Only add en, zh-CN, zh-HK by default.

Documentation

  • Documentation source files are in docs/.
  • Docs have two locales: English (docs/docs/) and Chinese (docs/zh-CN/docs/).
  • When modifying any documentation file, always sync changes to both en and zh-CN versions.

Platform Support

  • macOS (aarch64, x86_64)
  • Linux (x86_64)
  • Windows (x86_64)

CI runs full test suite on each platform.

Skills Reference

This project has custom Claude Code skills to assist with common development tasks:

  • gpui (skills/) - GPUI framework knowledge: actions/keybindings, async, context, custom elements, entity state, events, focus, global state, layout/styling, testing
  • gpui-component (skills/) - How to use gpui-component: setup, stateless/stateful patterns, common component APIs, theming
  • gpui-component-dev (.claude/skills/) - Contributing to gpui-component: creating new components, writing stories, writing documentation, writing PR descriptions

When working on tasks related to these areas, Claude Code will automatically use the appropriate skill to provide specialized guidance and patterns.

Testing Guidelines

See .claude/COMPONENT_TEST_RULES.md for detailed testing principles:

  • Simplicity First: Focus on complex logic and core functionality, avoid excessive simple tests
  • Builder Pattern Testing: Every component should have a test_*_builder test covering the builder pattern
  • Complex Logic Testing: Test conditional branching, state transitions, and edge cases