gogpu/ui

About gogpu/ui

This large README is shown as a plain-text preview. Read the full README at the source

<p align="center">
  <img src="https://raw.githubusercontent.com/gogpu/.github/main/assets/logo.png" alt="GoGPU Logo" width="120" />
</p>

<h1 align="center">gogpu/ui</h1>

<p align="center">
  <strong>Enterprise-Grade GUI Toolkit for Go</strong><br>
  Modern widgets, reactive state, GPU-accelerated rendering — zero CGO
</p>

<p align="center">
  <a href="https://github.com/gogpu/ui/actions"><img src="https://github.com/gogpu/ui/actions/workflows/ci.yml/badge.svg" alt="CI"></a>
  <a href="https://app.codecov.io/gh/gogpu/ui"><img src="https://codecov.io/gh/gogpu/ui/branch/main/graph/badge.svg" alt="Coverage"></a>
  <a href="https://goreportcard.com/report/github.com/gogpu/ui"><img src="https://goreportcard.com/badge/github.com/gogpu/ui" alt="Go Report Card"></a>
  <a href="https://pkg.go.dev/github.com/gogpu/ui"><img src="https://pkg.go.dev/badge/github.com/gogpu/ui.svg" alt="Go Reference"></a>
  <a href="https://github.com/gogpu/ui/releases/latest"><img src="https://img.shields.io/github/v/release/gogpu/ui?style=flat&label=version" alt="Version"></a>
  <a href="https://go.dev/"><img src="https://img.shields.io/badge/Go-1.25+-00ADD8?logo=go" alt="Go Version"></a>
  <a href="https://opensource.org/licenses/MIT"><img src="https://img.shields.io/badge/License-MIT-yellow.svg" alt="License"></a>
  <a href="https://github.com/gogpu/ui/stargazers"><img src="https://img.shields.io/github/stars/gogpu/ui?style=flat&labelColor=555&color=yellow" alt="Stars"></a>
  <a href="https://github.com/orgs/gogpu/discussions"><img src="https://img.shields.io/badge/Discussions-join-blue" alt="Discussions"></a>
</p>

---

> **Join the Discussion:** Help shape the future of Go GUI! Share your ideas, report issues, and discuss features at our [GitHub Discussions](https://github.com/orgs/gogpu/discussions/18).

---

## Overview

**gogpu/ui** is an enterprise-grade GUI toolkit for Go, designed for building:

- **IDEs** (GoLand, VS Code class)
- **Design Tools** (Photoshop, Figma class)
- **CAD Applications**
- **Professional Dashboards**
- **Chrome/Electron Replacement Apps**

### Key Differentiators

| Feature | gogpu/ui | Fyne | Gio |
|---------|----------|------|-----|
| **CGO-free** | Yes | No | Yes |
| **WebGPU rendering** | Yes (Vulkan/DX12/Metal/GLES/Software) | OpenGL | Direct GPU |
| **Reactive state** | Signals (push-pull, zero glitch) | Binding | Events |
| **Gesture recognition** | Arena-based (Flutter pattern) | No | No |
| **Layout engine** | Flexbox + Grid + per-widget cache | Custom | Flex |
| **Accessibility** | Day 1 (35+ ARIA roles) | Limited | Limited |
| **Design systems** | 4 (M3, DevTools, Fluent, Cupertino) | 1 | 1 |
| **Widgets** | 27 interactive + primitives | ~20 | ~15 |
| **Plugin system** | Yes (deps, assets, fonts) | No | No |
| **Android** | In review ([wgpu#268](https://github.com/gogpu/wgpu/pull/268)) | Yes | Yes |

---

## Screenshot

<p align="center">
  <img src="https://github.com/user-attachments/assets/f67636bc-7426-4865-9269-11e2a81124ad" alt="gogpu/ui Widget Demo" width="600" />
</p>

<p align="center"><em>examples/hello — Checkboxes, Radio Buttons, ListView (1000 items), Material Design 3</em></p>

---

## Quick Start

> **Important:** The gogpu ecosystem is **pure Go with zero CGO**. You must set `CGO_ENABLED=0` (the Go default) — do **not** enable CGO.

The fastest way to get started is to clone and run one of the included examples:

```bash
git clone https://github.com/gogpu/ui.git
cd ui/examples/hello
go run .
```

Here is a minimal example using `desktop.Run` (recommended):

```go
package main

import (
    "log"

    _ "github.com/gogpu/gg/gpu"
    "github.com/gogpu/gogpu"
    "github.com/gogpu/ui/app"
    "github.com/gogpu/ui/desktop"
    "github.com/gogpu/ui/primitives"
    "github.com/gogpu/ui/widget"
)

func main() {
    gogpuApp := gogpu.NewApp(gogpu.DefaultConfig().
        WithTitle("My App").
        WithSize(800, 600))

    uiApp := app.New(
        app.WithWindowProvider(gogpuApp),
        app.WithPlatformProvider(gogpuApp),
        app.WithEventSource(gogpuApp.EventSource()),
    )

    uiApp.SetRoot(
        primitives.Box(
            primitives.Text("Hello gogpu/ui!").
                FontSize(24).Bold().
                Color(widget.RGBA8(33, 33, 33, 255)),
            primitives.Text("Enterprise-grade GUI for Go").
                FontSize(16).
                Color(widget.RGBA8(100, 100, 100, 255)),
        ).Padding(24).Gap(12).Background(widget.RGBA8(255, 255, 255, 255)),
    )

    if err := desktop.Run(gogpuApp, uiApp); err != nil {
        log.Fatal(err)
    }
}
```

---

## Packages

### Core (Phase 0)

| Package | Description | Coverage |
|---------|-------------|----------|
| `geometry` | Point, Size, Rect, Constraints, Insets | 98.8% |
| `event` | MouseEvent, KeyEvent, WheelEvent, FocusEvent, Modifiers | 100% |
| `widget` | Widget, WidgetBase, Context, Canvas, Lifecycle (mount/unmount), SchedulerRef | 100% |
| `internal/render` | Canvas, SceneCanvas, IconCache (2-level LRU), DPI-aware SVG | 96.5% |
| `internal/layout` | Flex, Stack, Grid layout engines | 89.9% |

### MVP (Phase 1)

| Package | Description | Coverage |
|---------|-------------|----------|
| `a11y` | Accessibility: 35+ ARIA roles, Accessible interface, Tree, Announcer | 99.1% |
| `state` | Reactive signals, Binding, Scheduler with push-based invalidation | 100% |
| `primitives` | Box, Text, Image widgets with fluent builder API | 94.4% |
| `app` | Window integration via gpucontext interfaces (dependency inversion) | 98.6% |

### Extensibility (Phase 1.5)

| Package | Description | Coverage |
|---------|-------------|----------|
| `layout` | Public layout API with custom algorithms | 89.5% |
| `registry` | Widget factory registration for third-party widgets | 100% |
| `theme` | Theme system with Extensions and Registry | 100% |
| `plugin` | Plugin bundling with dependency resolution | 99.4% |

### Interactive Widgets (Phase 2 — Complete)

| Package | Description | Coverage |
|---------|-------------|----------|
| `cdk` | Component Development Kit — Content[C] polymorphic pattern | 100% |
| `core/button` | Generic button with pluggable Painter, 4 variants, 3 sizes, signal bindings | 96%+ |
| `core/checkbox` | Toggleable checkbox with checked/unchecked/indeterminate states, signal bindings | 96%+ |
| `core/radio` | Mutually exclusive radio group with vertical/horizontal layout, signal bindings | 96%+ |
| `core/textfield` | Text input with cursor, selection, clipboard, validation, signal bindings | 96%+ |
| `core/slider` | Slider: continuous/discrete, horizontal/vertical, drag+keyboard, signal bindings | 94.6% |
| `core/dialog` | Modal dialog: backdrop overlay, action buttons, focus trapping, Alert/Confirm | 96.9% |
| `core/dropdown` | Dropdown/select with overlay menu, keyboard navigation, signal bindings | 96%+ |
| `overlay` | Overlay/popup stack, container, position helper | 95%+ |
| `primitives` | Box, Text, Image, RepaintBoundary (GPU texture caching via Layer Tree compositor) | 94.4% |
| `theme/material3` | Material Design 3 — theme (HCT color science) + 24 component painters | 97%+ |
| `focus` | Keyboard focus management with Tab/Shift+Tab navigation | 95.2% |
| `internal/focus` | Internal focus manager implementation | 15.2% |

### Phase 3 (Complete)

| Package | Description | Coverage |
|---------|-------------|----------|
| `animation` | Animation engine: tween, spring, M3 presets, orchestration (Stagger/Chain/Repeat/Reverse) | 92.3% |
| `transition` | Widget enter/exit animations: Fade, Slide, Scale effects, Show/Hide wrapper | 98.7% |
| `core/scrollview` | Scrollable container: vertical/horizontal/both, wheel+keyboard+drag, PushClip/PushTransform, signal bindings | 96.5% |
| `core/tabview` | Tabbed navigation: lazy content switching, closeable tabs, keyboard nav, Top/Bottom position, signal bindings | 92.1% |
| `core/listview` | Virtualized list: fixed-height items, recycling, single/multi selection, keyboard nav, M3 painter | 96%+ |
| `core/gridview` | Virtualized 2D grid: fixed cell size, auto-fit columns, cell recycling, selection, keyboard nav | 92.1% |
| `core/linechart` | Real-time line chart: multiple series, rolling window, grid, Y-axis labels, thread-safe PushValue | 98.8% |
| `core/progressbar` | Linear progress bar: 0-100%, rounded corners, label, signal binding, PushClipRoundRect | 99.3% |
| `core/collapsible` | Expandable section: animated expand/collapse, keyboard focus, arrow indicator, Tween animation | 98.2% |
| `primitives` | Box (HBox/VBox direction), Text, Image, ThemeScope, RepaintBoundary | 94%+ |

### Phase 4 (In Progress)

| Package | Description | Coverage |
|---------|-------------|----------|
| `core/progress` | Circular progress: determinate arc + indeterminate spinner, polyline approximation | 97.4% |
| `core/popover` | Popover (click) + Tooltip (hover): 12 placements, auto-flip, overlay integration | 97.1% |
| `core/splitview` | Resizable split panels: draggable divider, min constraints, collapse, handle dots | 96.8% |
| `core/treeview` | Hierarchical tree: expand/collapse, virtualized rendering, connector lines, keyboard nav | 96%+ |
| `core/datatable` | Sortable column table: fixed header, virtualized rows, zebra striping, sort indicators | 96%+ |
| `core/toolbar` | Horizontal action bar: icon buttons, separators, spacers, custom widget items | 96%+ |
| `core/menu` | MenuBar + ContextMenu: submenus, separators, disabled items, shortcut display | 96%+ |
| `core/docking` | IDE-style dockable panels: border layout, tabbed groups, Dock/Undock API | 95.3% |
| `core/badge` | Notification badge: count mode (pill, "99+" overflow), dot mode, signal bindings with dedup | 99.3% |
| `core/chip` | Action/filter chip (M3 spec): toggleable selection, two-way signal write-back, state layers | 99.0% |
| `theme/material3` | 24 component painters (all widgets covered) | 97%+ |
| `theme/devtools` | **JetBrains DevTools**: 24 painters, Int UI gray scale, dark/light, IDE-style | 96%+ |
| `theme/fluent` | Microsoft Fluent Design: 11 painters, accent colors, inner focus ring, light/dark | 96%+ |
| `theme/cupertino` | Apple HIG: 11 painters, iOS toggle switch, segmented control, pill buttons | 96%+ |
| `theme/font` | Font Registry: CSS weight matching (W3C spec), Weight 100-900, Style, Family/Face | 97.7% |
| `icon` | SVG icons (JetBrains expui), 2-level cache, DPI-aware rasterization, gg/svg renderer | 97%+ |
| `i18n` | Internationalization: Locale, Bundle, Translator, CLDR plural rules, RTL, LocaleSignal | 97.9% |
| `dnd` | Drag and drop: DragSource/DropTarget interfaces, Manager, 5px threshold, Escape cancel | 99.3% |
| `offscreen` | Headless widget rendering: CPU-only `*image.RGBA` output, no GPU/window/app required | 100% |
| `uitest` | Testing utilities: MockCanvas, MockContext, event factories, widget helpers, assertions | 93.1% |
| `internal/dirty` | Dirty region tracking: Collector, Tracker, merge algorithm, partial repaints | 100% |

| `core/stripe` | Vertical sidebar strip: tool window buttons, top/bottom items, icon buttons | 96%+ |
| `core/titlebar` | Window title bar: CSD, drag, minimize/maximize/close, WindowChrome interface | 96%+ |
| `gesture` | Gesture recognition: Arena, ClickRecognizer, DragRecognizer, LongPressRecognizer, TapAndDragRecognizer, VelocityTracker, Team | 96.0% |
| `compositor` | Layer Tree compositor: OffsetLayer, PictureLayer, ClipRectLayer, OpacityLayer — production render pipeline | 95%+ |
| `desktop` | Production render loop: Layer Tree → GPU textures → damage-aware blit | — |

**Total: ~220,000+ lines of code | 70 packages | ~7,800+ tests | 97%+ average coverage**

### Backend Selection

gogpu/ui renders through any GPU backend via the gogpu ecosystem — no code changes needed:

```bash
GOGPU_GRAPHICS_API=vulkan   go run ./examples/hello/   # Vulkan (default on Linux)
GOGPU_GRAPHICS_API=dx12     go run ./examples/hello/   # DirectX 12 (Windows)
GOGPU_GRAPHICS_API=metal    go run ./examples/hello/   # Metal (macOS)
GOGPU_GRAPHICS_API=gles     go run ./examples/hello/   # OpenGL ES
GOGPU_GRAPHICS_API=software go run ./examples/hello/   # CPU software renderer
```

The **software backend** runs on any machine without GPU drivers. It uses the same unified render pipeline (Layer Tree compositor, offscreen boundary textures, damage-aware blit) as GPU backends. Performance is significantly slower than GPU — optimization via naga Go+SIMD backend ([NAGA-FEAT-004](https://github.com/gogpu/naga)) is planned.

**Android support** is in review ([wgpu#268](https://github.com/gogpu/wgpu/pull/268)) — Vulkan on arm64, contributed by [@besmpl](https://github.com/besmpl) for [Hearth](https://github.com/besmpl/hearth) game engine.

---

## Architecture

```
┌─────────────────────────────────────────────────────────────┐
│                    User Application                         │
├─────────────────────────────────────────────────────────────┤
│  theme/material3/  │  theme/devtools/ │  theme/fluent/      │
│  24 Painters       │  24 Painters     │  11 Painters        │
│  theme/cupertino/  │                  │                     │
│  11 Painters       │  70 painters total across 4 systems   │
├─────────────────────────────────────────────────────────────┤
│  27 Interactive Widgets (core/)                             │
│  button, checkbox, radio, textfield, dropdown, slider,      │
│  dialog, scrollview, tabview, listview, gridview, linechart,│
│  progressbar, progress, collapsible, popover, splitview,    │
│  treeview, datatable, toolbar, menu, docking, badge, chip,  │
│  stripe, titlebar, gpuview                                  │
├──────────────┬──────────────────────────────────────────────┤
│  cdk/        │  Content[C] polymorphic pattern              │
├──────────────┴──────────────────────────────────────────────┤
│  primitives/       │  animation/     │  transition/         │
│  Box (HBox/VBox),  │  Tween, Spring  │  Fade, Slide, Scale  │
│  Text, Image,      │  M3 Presets,    │  Enter/Exit          │
│  RepaintBoundary   │  Orchestration  │                      │
├─────────────────────────────────────────────────────────────┤
│  icon/  │  i18n/  │  dnd/   │  uitest/ │  theme/font/       │
├─────────────────────────────────────────────────────────────┤
│  gesture/          (Arena, Click, Drag, LongPress, Team)   │
├─────────────────────────────────────────────────────────────┤
│  app/ + FocusManager │  focus/ │  overlay/ │  render/       │
├─────────────────────────────────────────────────────────────┤
│  desktop/            (Layer Tree Compositor + Damage-Aware Blit)    │
│  compositor/         (Production: OffsetLayer, PictureLayer, Opacity)│
│  offscreen/          (headless widget → *image.RGBA)        │
├─────────────────────────────────────────────────────────────┤
│  layout/           │  state/         │  a11y/               │
│  Flex, Stack, Grid │  Signals, Bind  │  ARIA Roles, Tree    │
├─────────────────────────────────────────────────────────────┤
│  registry/         │  plugin/        │  theme/              │
├─────────────────────────────────────────────────────────────┤
│  widget/           │  event/         │  geometry/           │
│  Widget, Context   │  Mouse, Key     │  Point, Rect         │
│  Canvas, Lifecycle │  Wheel, Focus   │  Constraints         │
├─────────────────────────────────────────────────────────────┤
│  internal/render   │  internal/layout│  internal/focus      │
│  Canvas, Scene,    │  Flex, Grid     │  Manager, Ring       │
│  IconCache (LRU)   │  internal/dirty │  Tracker, Collector  │
├─────────────────────────────────────────────────────────────┤
│  gogpu/gg          │  gpucontext     │  coregx/signals      │
│  2D Graphics       │  Shared Ifaces  │  State Management    │
└─────────────────────────────────────────────────────────────┘
```

### Dependency Principle

```
ui → gpucontext (interfaces)       ← dependency inversion
ui → gg (2D rendering)
ui → coregx/signals (reactive)

gogpu → gpucontext (implements)    ← concrete implementation
gg → wgpu → naga                   ← internal to gg
```

**ui never imports gogpu, wgpu, or naga directly.**

### Render Pipeline

Enterprise-grade retained-mode rendering (ADR-007) with unified draw queue (ADR-051/052):

1. **O(1) frame skip** — flat dirty boundary set, no tree walks when idle (0% GPU)
2. **Layer Tree composition** — OffsetLayer, PictureLayer, OpacityLayer, ClipRectLayer
3. **Per-boundary GPU textures** — dirty boundaries re-render to MSAA offscreen texture, clean reuse cached
4. **Damage-aware blit** — LoadOpLoad + multi-rect scissor, only dirty pixels touch the GPU
5. **Persistent tree** — layer objects reused across frames (97.9% fewer allocations)
6. **Unified draw queue** — backend-agnostic command dispatch (shapes, text, GPU textures through single pipeline). GPU backends batch into render passes; software dispatches through CPU rasterizer.

Validated by enterprise research: Flutter, Chrome, Qt6, Android, Skia patterns.
Works on all backends: Vulkan, DX12, Metal, GLES, Software, Browser (WASM).

---

## Examples

| Example | Description |
|---------|-------------|
| [`examples/hello`](examples/hello) | Widget demo: checkbox, radio, ListView (1000 items), M3 theme, event-driven GPU rendering |
| [`examples/signals`](examples/signals) | Reactive signals: TextSignal, ContentSignal, CheckedSignal, SelectedSignal, DisabledSignal |
| [`examples/taskmanager`](examples/taskmanager) | Full task manager: charts, tables, animations, real-time data |
| [`examples/gallery`](examples/gallery) | Widget gallery: all 26 widgets, 4 design systems (M3/DevTools/Fluent/Cupertino), theme switching |
| [`examples/ide`](examples/ide) | GoLand-inspired IDE layout: DevTools theme, toolbar, tree, tabs, terminal, SVG icons |
| [`examples/filedrop`](examples/filedrop) | OS file drag-and-drop: drop files from file manager, reactive path display |
| [`examples/gpuview`](examples/gpuview) | GPU view widget: offscreen texture compositing (Flutter Texture pattern) |
| [`examples/modular-compositor`](examples/modular-compositor) | Multi-module offscreen rendering: clock + notification compositor ([#75](https://github.com/gogpu/ui/issues/75)) |

Run any example:

```bash
cd examples/gallery
go run .
```

---

## API Examples

### Primitives

```go
// Box — universal container
primitives.Box(children...).
    Padding(16).
    PaddingXY(24, 8).
    Background(theme.Surface).
    Rounded(8).
    BorderStyle(1, theme.Outline).
    ShadowLevel(2).
    Gap(8)

// Text — static
primitives.Text("Hello World").
    FontSize(24).
    Bold().
    Color(theme.OnSurface).
    Align(primitives.TextAlignCenter).
    MaxLines(2).
    Ellipsis()

// Text — reactive (auto-updates when signal changes)
primitives.TextFn(func() string {
    return fmt.Sprintf("Count: %d", count.Get())
}).FontSize(18)

// Text — signal binding (auto-updates when signal changes)
title := state.NewSignal("Hello World")
primitives.NewText("").ContentSignal(title).FontSize(24)

// Image
primitives.Image(mySource).
    Size(48, 48).
    Cover().
    Rounded(24).
    Alt("User avatar")
```

### Slider

```go
// Basic slider
s := slider.New(
    slider.Min(0),
    slider.Max(100),
    slider.Value(50),
    slider.OnChange(func(v float32) { fmt.Println("Value:", v) }),
)

// Discrete slider with step snapping and marks
s := slider.New(
    slider.Min(0), slider.Max(100), slider.Step(10),
    slider.Marks([]slider.Mark{{Value: 0}, {Value: 50}, {Value: 100}}),
    slider.PainterOpt(material3.SliderPainter{Theme: m3}),
)

// Two-way signal binding
volume := state.NewSignal[float32](75)
s := slider.New(
    slider.Min(0), slider.Max(100),
    slider.ValueSignal(volume),  // reads AND writes back on drag
)
```

### Dialog

```go
// Simple alert dialog
d := dialog.Alert("Error", "File not found.", func() { log.Println("dismissed") })
d.Show(ctx)

// Confirmation dialog
d := dialog.Confirm("Delete?", "This cannot be undone.",

Frequently Asked Questions