Introducing a new way to review your PRs.

Read the announcement

opencut-app / opencut

The open-source CapCut alternative

View on GitHub

12 documents · Updated Nov 16, 2026

docs / desktop-ui-components


covers:

  • apps/desktop/src/components/**

Desktop UI Components

Overview

The reusable desktop UI component module lives under apps/desktop/src/components/** and is exposed through apps/…/mod.rs. That module keeps the concrete component files private and re-exports only the primitives other desktop views are expected to compose: Badge, Button, ContextMenu, ContextMenuItem, Label, ResizablePanelGroup, Separator, and their public variant/orientation enums.

All primitives are GPUI elements or views styled from the active application theme. The single-use display primitives (Badge in apps/…/badge.rs, Button in apps/…/button.rs, Label in apps/…/label.rs, and Separator in apps/…/separator.rs) implement RenderOnce and are intended to be built fluently at the call site. Their constructors take the required content first, then optional builder methods adjust variants, sizing, disabled state, or layout. None of these components owns application state; they read colors, radius, and interaction colors through window.theme() via crate::theme::ActiveTheme while rendering.

Button in apps/…/button.rs is the main interactive primitive. Callers create it with a stable ElementId and label, choose a ButtonVariant (Default, Outline, Secondary, Ghost, Destructive, or Link) and ButtonSize, and attach behavior with .on_click(...). Icon sizes collapse horizontal padding and set width equal to height; text sizes add horizontal padding. Enabled buttons prevent default left mouse down behavior, stop propagation before invoking the click handler, and apply hover/active colors. Disabled buttons only render with reduced opacity and a not-allowed cursor, so no click handler is wired when disabled is true.

Badge in apps/…/badge.rs renders compact non-interactive status text with theme-colored filled, secondary, outline, or destructive styling. Label in apps/…/label.rs renders medium-weight extra-small text and can be muted or visually disabled. Separator in apps/…/separator.rs shares the Orientation enum with resizable panels and renders a 1px horizontal or vertical border-colored rule.

ContextMenu in apps/…/context_menu.rs is a stateful GPUI entity rather than a RenderOnce value. Construct it with a list of ContextMenuItems, store it as an Entity<ContextMenu>, render the entity somewhere in the owning view, and wrap the right-click target with context_menu_trigger(id, child, menu). The trigger intercepts right mouse down, prevents default behavior, stops propagation, and updates the menu entity with the mouse position. While open, the menu renders as a deferred anchored popover snapped inside the window with an 8px margin and closes on outside mouse down. Entry items can carry a shortcut label, checked state, disabled state, destructive styling, and an on_select callback; activation closes the menu before running the callback. Label and separator menu items are display-only.

ResizablePanelGroup in apps/…/resizable.rs is the layout primitive for two resizable GPUI views. It stores AnyView handles for a first and second child, an Orientation, an initial split fraction, the current split fraction, and a minimum fraction. Horizontal groups size the first child by relative width; vertical groups size it by relative height. The second child fills the remaining space. Dragging the handle recomputes the fraction from the cursor position inside the group bounds, clamps it between minimum_fraction and 1.0 - minimum_fraction, and notifies GPUI to rerender. Double-clicking the handle resets the split to the initial fraction. minimum_fraction(...) itself is clamped to 0.0..=0.49, which preserves visible room for both panels.

Coupling

  • If theme tokens change, verify every component under apps/desktop/src/components/**: badge.rs, button.rs, context_menu.rs, label.rs, resizable.rs, and separator.rs all read concrete color names through crate::theme::ActiveTheme, and missing or semantic color changes will alter component contrast and interaction feedback.
  • If Orientation in apps/…/resizable.rs changes, also update apps/…/separator.rs; Separator imports crate::components::Orientation instead of defining its own orientation, so adding or renaming variants affects both resizable panel layout and standalone separators.
  • If context_menu_trigger in apps/…/context_menu.rs is wrapped by another mouse handler, verify right-click propagation and default prevention. The trigger relies on both window.prevent_default() and cx.stop_propagation() before opening the menu entity at the event position.
  • If a new button variant or size is added in apps/…/button.rs, update all three variant-dependent render branches together: background/foreground/border colors, hover/active behavior, and size-derived height/padding/icon-width logic. Missing one branch can compile only if the enum match is updated, but inconsistent interaction styling will be visible at runtime.

Risks

  • apps/…/resizable.rs computes split fractions by dividing by (bounds.right() - bounds.left()) or (bounds.bottom() - bounds.top()) during drag. If a panel group is ever rendered with zero width or height while dragging, the fraction can become non-finite before clamping, which can break layout sizing for the child views.
  • apps/…/context_menu.rs identifies every rendered item as ("context-menu-item", index). If multiple context menu entities are open or mounted in overlapping scopes, duplicate element IDs can make GPUI event targeting/debugging ambiguous; keep menus closed on outside click and avoid rendering multiple active menus for the same surface.