gpui-kit

# GPUI Kit Applications depend on one crate, `gpui-kit`. GPUI is `use gpui_kit::*;`, and each layer is reachable by name: `gpui_kit::component` (styled components), `gpui_kit::base` (unstyled behavior), `gpui_kit::assets` (default icons), `gpui_kit::platform`. Start with [component-family conventions](references/conventions.md) to choose the constructor, state owner, event, and layout contract for the task. Learn the family once, then verify the specific component supports the capability. For a complete compiled view with retained state, subscriptions, and overlay layers, read [the tested application recipe](references/recipes.md). ## Read the Guides First Two guides hold the rules this skill assumes. They are requirements, not inspiration. Read the guide file itself; do not answer from this page, from a similar file in the codebase, or from training data. | Guide | Read before | | ------------------------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------- | | Design Guides, skill `gpui-kit-design-guides` | Choosing components, layout, spacing, hierarchy, color, density, interaction states, overlays, motion, interface copy | | [Coding Guides](references/coding-guides.md) | Crate layering, `RenderOnce` vs `Entity<T>`, state ownership, `ElementId`, events, focus, async, public API, naming, testing | Read the Design Guides first when the change has a visible surface: code structure preserves product intent, it does not replace it. If the design skill is not installed, fetch `https://gpui-kit.com/docs/design-guides.md`. The coding guide is a verbatim copy of `https://gpui-kit.com/docs/coding-guides.md`, so its links to `./design-guides.md` and `./getting-started.md` mean the design skill and `https://gpui-kit.com/docs/getting-started.md`. ### Coding Guides section map Read the whole guide for a new crate, module, or feature. For a narrow change, read "Architecture at a glance" and "Rules for coding agents" first, then the section for the change (`grep -n '^## ' references/coding-guides.md`). | Section | Read when | | ------------------------------------ | ---------------------------------------------------------------------- | | Architecture at a glance | Always; crate layering, ownership boundary | | Bootstrap and root ownership | `main`, `init`, `Root`, window creation, app-level state | | Understand GPUI's phases and contexts | Anything touching `App`, `Window`, `Context<T>`, render vs update | | Choose the right unit | Deciding `RenderOnce` vs `Entity<T>` vs custom `Element` | | State ownership | Where a piece of state lives, who mutates it, `Entity<State>` handles | | Stable identity | `ElementId`, lists, repeated elements, keyed state | | Rendering and composition | `render`, builder chains, `when`/`map`, child composition | | Behavior and presentation boundary | `gpui-base` vs `gpui-component` vs application code | | Theme and styling | `cx.theme()`, tokens, `Styled`, sizes, variants | | Events, actions, and focus | `cx.emit`, `subscribe`, `actions!`, keybindings, `FocusHandle` | | Async work and side effects | `cx.spawn`, `background_spawn`, `Task`, I/O, timers | | Layout, measurement, and scrolling | Flex layout, sizing, `overflow`, scroll handles, measuring | | Lists, tables, and large data | `VirtualList`, `List`, `DataTable`, delegates, large collections | | Public API design | Anything `pub`: builders, private fields, setter and reader naming | | Platform and capability boundaries | macOS/Windows/Linux/wasm differences, feature gates | | File and naming conventions | New files, modules, type and method names, `Kind` suffix, `Context` | | Testing strategy | What to test, `#[gpui_kit::test]`, `TestAppContext` | | Performance rules | Render cost, allocation, re-render triggers | | Common failure modes | Before finishing; invented APIs, state in render, index ids | | Rules for coding agents | Always when an agent writes code | | Implementation checklist | Before finishing; run every item against the work | ### Non-negotiables A floor, not a substitute for the guides. - **Never invent an API.** Search the current source for the real signature. Do not translate a React, CSS, or older-GPUI example by analogy; a plausible-looking method that does not exist is the most common failure. - **One dependency.** Applications depend on `gpui-kit` alone. GPUI is `use gpui_kit::*;`; the layers are `gpui_kit::component`, `gpui_kit::base`, `gpui_kit::assets`, `gpui_kit::platform`. - **Framework owns behavior, application owns presentation.** Do not put colors, sizing, or layout in `gpui-base`; do not put interaction behavior in application styling code. - **Stable identity.** Repeated elements need domain-derived `ElementId`s, not list indexes. - **No `pub` fields across the seam.** Public data types use builders and reader methods. - **Spell `Context` out.** `cx` is GPUI's; name anything else after what it holds. ## Documentation - **Find a task/component page**: use `https://gpui-kit.com/llms.txt`, then load its Markdown page. - **Full reference**: `https://gpui-kit.com/llms-full.txt` is available when broad reference is actually needed - **Per-component API**: fetch `https://gpui-kit.com/component/{name}.md`, e.g. `button.md`, `input.md`, `select.md`, `dialog.md`, `data-table.md` - **Any site page** can be fetched as Markdown by appending `.md` to the URL ## Quick Reference Setup and examples: [references/usage.md](references/usage.md). ```rust use gpui_kit::*; use gpui_kit::component::Root; gpui_kit::application() .with_assets(gpui_kit::assets::Assets) .run(|cx| { gpui_kit::init(cx); // first, before anything else // ... open_window(..., |window, cx| cx.new(|cx| Root::new(view, window, cx))) }); ``` - **Stateless** (`RenderOnce`): build in `render`: `Button::new("save").primary().label("Save").on_click(|_, _, _| {})` - **Stateful**: hold `Entity<State>` in the view, pass a reference in `render`: `let input = cx.new(|cx| InputState::new(window, cx));` then `Input::new(&self.input)` - **Sizes**: `.xsmall()` `.small()` `.medium()` (default) `.large()` - **Theme**: `cx.theme().primary` · `.background` · `.foreground` · `.border` · `.muted` - **Overlays**: `window.open_dialog(...)`, `open_sheet(...)`, `push_notification(...)` via `gpui_kit::component::WindowExt` ## Component Catalog Import paths are relative to `gpui_kit::component::`, so `input::{Input, InputState}` means `use gpui_kit::component::input::{Input, InputState};`. For the full API fetch the component's `.md` doc. ### Input & Form | Component | Import | Notes | | ------------- | ----------------------------------------------- | -------------------------------------------- | | `Input` | `input::{Input, InputState}` | Stateful. Text, password, mask, validation | | `Textarea` | `input::{Textarea, TextareaState}` | Stateful. Multi-line text | | `Editor` | `input::{Editor, EditorState}` | Stateful. Code editor, `tree-sitter` feature | | `NumberInput` | `input::{NumberInput, NumberInputEvent}` | Stateful. Numeric with step | | `OtpInput` | `input::OtpInput` | Stateful. One-time password | | `Select` | `select::{Select, SelectState}` | Stateful. Dropdown picker | | `Combobox` | `combobox::{Combobox, ComboboxState}` | Stateful. Searchable select | | `Checkbox` | `checkbox::Checkbox` | Stateless. `on_click` receives `&bool` | | `Switch` | `switch::Switch` | Stateless. Toggle | | `Radio` | `radio::{Radio, RadioGroup}` | Stateless. | | `Slider` | `slider::{Slider, SliderState}` | Stateful. | | `Toggle` | `button::Toggle` | Stateless. | | `Rating` | `rating::Rating` | Stateless. | | `Stepper` | `stepper::Stepper` | Stateless. Multi-step progress | | `ColorPicker` | `color_picker::{ColorPicker, ColorPickerState}` | Stateful. | | `DatePicker` | `date_picker::{DatePicker, DatePickerState}` | Stateful. | | `Calendar` | `calendar::{Calendar, CalendarState}` | Stateful. Inline month view | | `Form` | `form::{v_form, h_form, field}` | Layout container for form fields | ### Display & Feedback | Component | Import | Notes | | ----------- | ----------------------------------------- | ------------------------------------- | | `Button` | `button::{Button, ButtonGroup}` | Stateless. Primary UI action | | `Icon` | `{Icon, IconName}` | Stateless. Lucide icons | | `Badge` | `badge::Badge` | Stateless. | | `Tag` | `tag::Tag` | Stateless. Closable tags | | `Avatar` | `avatar::Avatar` | Stateless. | | `Label` | `label::Label` | Stateless. Form label | | `Kbd` | `kbd::Kbd` | Stateless. Keyboard key display | | `Alert` | `alert::Alert` | Stateless. Info/success/warning/error | | `Spinner` | `spinner::Spinner` | Stateless. Loading indicator | | `Skeleton` | `skeleton::Skeleton` | Stateless. Loading placeholder | | `Shimmer` | `shimmer::{ShimmerText, ShimmerStyle}` | Stateless. Streaming-text shimmer | | `Marker` | `marker::{Marker, MarkerVariant}` | Stateless. Inline status marker | | `Progress` | `progress::{Progress, ProgressCircle}` | Stateless. |