ui

package
v0.0.5 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Nov 11, 2026 License: Apache-2.0 Imports: 10 Imported by: 0

README

Persistent GPUI node graph

github.com/moriyoshi/gpui-go/ui binds the reactive graph to the existing GPUI client. Components construct nodes once. Reactive bindings change their properties, and a document publishes one complete protobuf snapshot after a settled batch when the snapshot differs.

Inside a host.Run application callback, with app *client.Client:

graph := reactive.NewGraph()
defer graph.Dispose()
document := ui.New(graph.Root(), app)
owner := document.Scope()
count := reactive.NewSignal(owner, 0)
label := document.BindText(owner, func() string {
    return fmt.Sprintf("Count: %d", count.Get())
}).Name("count")
button := document.Div(owner, document.Text(owner, "Increment"))
button.Accessible("Increment", &scene.Accessibility{
    Role: scene.RoleButton,
}).Focusable(0).OnClick(func(ctx context.Context, event *client.Event) error {
    return count.Update(func(value int) int { return value + 1 })
})
root := document.Div(owner, label, button)
mount, err := document.OpenWindow(ctx, client.WindowOptions{
    Title: "Reactive counter", Width: 500, Height: 300,
}, root)
if err != nil { return err }
defer mount.Close(context.Background())
return app.DispatchEvents(ctx)

Div, Text, BindText, Input, Image/BindImage, Canvas/BindCanvas and UniformList create nodes. A uniform list takes children like a Div, and each serialized child, including the rows of a For or Show range, becomes one virtualized row. Fragment is a transparent range without an additional native layout container. SetChildren validates document ownership, cycles, duplicate children and existing parents before modifying a node; omitted children are disposed. Node IDs remain stable across property updates. Name registers an application selector retrievable through Document.Element, including for uitest/gpui.Application.

Style/BindStyle, Hover, TWClass/BindTWClass, Accessible/BindAccessibility, Focusable and OnClick configure concrete elements. TWClass takes a Tailwind-style utility list compiled by tw with the theme set by Document.UseTheme; Style and Hover refine the compiled style and hover refinement field by field, and also win over breakpoint and dark: utilities. Document.WindowSize and Document.ColorScheme return the mounted window's size and color scheme; each is tracked like a separate signal read, so a binding follows only the one it reads. Fragment nodes only manage children. Use scene.Style, scene.Accessibility, concise scene enum constants and client.Event callbacks. These public aliases retain wire identity and require no generated-binding imports. Handlers execute later in Go event dispatch and are automatically batched; no Go closure is called during Rust rendering. Node disposal removes owned computations, descendants, names and registered handlers.

After mounting, group imperative node operations (such as SetChildren, Style or Dispose) in graph.Batch, or call graph.Flush afterward. These methods mark the document dirty; reactive signal propagation and event handlers already provide a flush boundary. Owners must belong to the document's graph. Use Document.Scope for normal construction; disposing the document also releases its nodes created with other owners in that graph.

Inputs and structural control

Document.Input(owner, stringSignal, InputOptions) binds a persistent native single-line input to a string signal. Native edits acknowledge their edit revision without resetting selection or composition. Authoritative signal replacements advance the input epoch. InputOptions.Disabled can read reactive state. This uses the existing generic input behavior and limits; it does not introduce multiline editing or the GPL editor backend.

Document.Show(owner, condition, yes, no) owns a transparent range. The selected factory runs when the condition changes; the old branch's scope, nodes and handlers are disposed. Factory reads are untracked. Put reactive calculations inside bindings or memos owned by the supplied branch scope.

ui.For(document, owner, items, key, render) retains rows by comparable application key. The renderer receives a row scope, an item signal and an index signal. Read them inside bindings to observe immutable item replacement and reordering. Row factories run once for each inserted key. Reordering preserves native entities; deletion disposes the row's ownership. Duplicate keys fail before reconciliation publishes any change. Keys must be stable for an item's lifetime.

Mounting and limits

Snapshot exports a cloned root through scene.Node; Attach supplies a custom snapshot sink for tests or another host. A sink must not mutate the document or graph. Each document supports one active sink. Its returned stop function is idempotent and permits reattachment. OpenWindow owns one native window; close its Mount explicitly before shutting down the client. Disposing a graph/document unsubscribes computations but does not itself close native windows.

Construction errors from fluent methods are available through Document.Err and prevent mounting. Computation failures propagate through the graph and suppress publication until recovery. A sink error remains visible and stops automatic publication to that sink: cancellation can race a committed native update, so blind mutation retries are unsafe.

Fine-grained updates currently apply to Go calculations and cached properties. The wire still sends complete snapshots, with the existing 4 MiB message, depth-32 and 10,000-element limits. Stable IDs let Rust preserve input/focus entities. This is a native node graph, without browser layout or DOM/CSS compatibility. The low-level GPUI snapshot API remains available for primitives outside this initial node API.

Run make reactive for the example, which combines batched counters, a memo-backed conditional branch and keyed editable rows. The GoX adapter builds this graph from typed template jobs. The native scenario checks dependency isolation, branch disposal and retained input identity/focus/selection after reordering.

Documentation

Overview

Package ui binds a persistent Go node graph to GPUI protobuf snapshots. Reactive calculations run in Go; painting and native input stay in Rust.

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

This section is empty.

Types

type Document

type Document struct {
	// contains filtered or unexported fields
}

func New

func New(owner *reactive.Scope, client *clientlib.Client) *Document

func (*Document) Attach

func (d *Document) Attach(root *Node, sink func(*scene.Node) error) (func(), error)

Attach installs a generic snapshot sink. Bindings update selectively, while the current wire contract still sends one complete snapshot per settled batch.

func (*Document) BindCanvas added in v0.0.2

func (d *Document) BindCanvas(owner *reactive.Scope, read func() []*scene.DrawCommand) *Node

BindCanvas repaints with the commands the accessor returns when its dependencies change. The commands are copied; unchanged commands publish nothing.

func (*Document) BindImage added in v0.0.2

func (d *Document) BindImage(owner *reactive.Scope, read func() *clientlib.Resource) *Node

BindImage displays the resource the accessor returns, switching when its dependencies change. A nil resource fails the computation.

func (*Document) BindText

func (d *Document) BindText(owner *reactive.Scope, read func() string) *Node

func (*Document) Canvas added in v0.0.2

func (d *Document) Canvas(owner *reactive.Scope, commands ...*scene.DrawCommand) *Node

Canvas paints drawing commands in local coordinates. Give it a size: it fills its box and has no children.

func (*Document) ColorScheme added in v0.0.2

func (d *Document) ColorScheme() scene.ColorScheme

ColorScheme returns whether the mounted window is drawn light or dark. It is tracked separately from WindowSize, so a binding that reads only the color scheme does not rerun on resizes. It is scene.ColorSchemeUnspecified before OpenWindow and on backends without the window-color-scheme capability.

func (*Document) Dispose

func (d *Document) Dispose()

func (*Document) Div

func (d *Document) Div(owner *reactive.Scope, children ...*Node) *Node

func (*Document) Element

func (d *Document) Element(name string) (uint64, bool)

func (*Document) Err

func (d *Document) Err() error

func (*Document) Fragment

func (d *Document) Fragment(owner *reactive.Scope, children ...*Node) *Node

func (*Document) Image added in v0.0.2

func (d *Document) Image(owner *reactive.Scope, resource *clientlib.Resource) *Node

Image displays an uploaded image or SVG resource. The resource must stay uploaded while any mounted snapshot references it.

func (*Document) Input

func (d *Document) Input(owner *reactive.Scope, value *reactive.Signal[string], options InputOptions) *Node

Input mirrors a signal through the bridge's epoch/edit-revision protocol. Native edits echo their acknowledgement; authoritative signal replacements advance the epoch. The persistent node/entity is never replaced per keystroke.

func (*Document) OpenWindow

func (d *Document) OpenWindow(ctx context.Context, options clientlib.WindowOptions, root *Node) (*Mount, error)

func (*Document) Scope

func (d *Document) Scope() *reactive.Scope

func (*Document) Show

func (d *Document) Show(owner *reactive.Scope, condition func() bool, yes, no func(*reactive.Scope) *Node) *Node

Show constructs a branch only when the condition changes and disposes the previous branch's owned effects/handlers. The range itself is transparent.

func (*Document) Snapshot

func (d *Document) Snapshot(root *Node) (*scene.Node, error)

func (*Document) Text

func (d *Document) Text(owner *reactive.Scope, value string) *Node

func (*Document) UniformList added in v0.0.2

func (d *Document) UniformList(owner *reactive.Scope, rowHeight float32, rows ...*Node) *Node

UniformList virtualizes its children as rows of one height, in logical pixels from 1 to 16384. Children are managed like a Div's, so For and Show ranges can supply rows; each serialized child is one row. Every row is still sent in every snapshot. Scroll with Mount.Window().ScrollTo and the list's ID.

func (*Document) UseTheme added in v0.0.2

func (d *Document) UseTheme(compiler *tw.Compiler)

UseTheme sets the compiler that Node.TWClass and BindTWClass use; the default is Tailwind's default theme. Set it before building nodes: classes already applied are not recompiled.

func (*Document) WindowSize added in v0.0.2

func (d *Document) WindowSize() clientlib.WindowSize

WindowSize returns the mounted window's drawable area. It is tracked like a signal read, so bindings and Show conditions follow resizes. It is zero before OpenWindow and on backends without the window-size capability.

type Handler

type Handler func(context.Context, *clientlib.Event) error

type InputOptions

type InputOptions struct {
	Placeholder string
	Disabled    func() bool
	Masked      func() bool
}

type Mount

type Mount struct {
	Window *clientlib.Window
	// contains filtered or unexported fields
}

func (*Mount) Close

func (m *Mount) Close(ctx context.Context) error

type Node

type Node struct {
	// contains filtered or unexported fields
}

Node keeps its ID across updates. Fragments are transparent ranges and do not add native layout containers. Nodes have one parent and one document.

func For

func For[T any, K comparable](d *Document, owner *reactive.Scope, items func() []T, key func(T) K, render func(*reactive.Scope, *reactive.Signal[T], *reactive.Signal[int]) *Node) *Node

For preserves rows by application key, including native input entities on reorder and immutable item replacement. Duplicate keys reject before mutation.

func (*Node) Accessible

func (n *Node) Accessible(label string, metadata *scene.Accessibility) *Node

func (*Node) Append

func (n *Node) Append(children ...*Node) error

func (*Node) BindAccessibility

func (n *Node) BindAccessibility(label string, read func() *scene.Accessibility) *Node

func (*Node) BindStyle

func (n *Node) BindStyle(read func() *scene.Style) *Node

func (*Node) BindTWClass added in v0.0.2

func (n *Node) BindTWClass(read func() string) *Node

BindTWClass recompiles the class list when the accessor's dependencies change. A class that cannot be compiled fails the computation.

func (*Node) Dispose

func (n *Node) Dispose()

func (*Node) Focusable

func (n *Node) Focusable(index int32) *Node

func (*Node) Hover added in v0.0.2

func (n *Node) Hover(style *scene.Style) *Node

Hover sets a partial style refinement GPUI applies while the pointer is over the element, without a Go event or another snapshot.

func (*Node) ID

func (n *Node) ID() uint64

func (*Node) Name

func (n *Node) Name(name string) *Node

func (*Node) OnClick

func (n *Node) OnClick(handler Handler) *Node

func (*Node) Scope

func (n *Node) Scope() *reactive.Scope

func (*Node) SetChildren

func (n *Node) SetChildren(children ...*Node) error

func (*Node) Style

func (n *Node) Style(style *scene.Style) *Node

func (*Node) TWClass added in v0.0.2

func (n *Node) TWClass(classes string) *Node

TWClass sets Tailwind-style utility classes, compiled with the document's theme; hover: classes become the hover refinement. Style and Hover refine the classes field by field. A class that cannot be compiled is a construction error reported by Document.Err.

Directories

Path Synopsis
Package gox adapts GoX's typed job stream into a persistent GPUI node graph.
Package gox adapts GoX's typed job stream into a persistent GPUI node graph.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL