1// Package nefergui provides a pure-Go immediate-mode GUI for Wayland, rendered with
2// Vulkan and styled with a bounded CSS dialect (see docs/css.md).
3//
4// Run opens a window and calls the view function to build each frame. The view
5// receives a Frame; Frame and its Node handles are valid only during that call.
6// Key identifies a child among its siblings across frames; without a key,
7// position and type determine identity. ID is CSS metadata, not frame identity.
8// Options such as Title, Size, Styles and Transparent configure the window.
9//
10// The frame tree, controls, editors and input routing are implemented in
11// internal/ui; this package is the public facade and re-exports those types.
12//
13// Builds support CGO_ENABLED=0. At runtime, NeferGUI requires libvulkan.so.1,
14// libxkbcommon.so.0 and a Wayland compositor supporting linux-dmabuf and
15// linux-drm-syncobj. See docs/runtime.md and docs/troubleshooting.md.
16package nefergui
17
18import (
19 "context"
20
21 "github.com/bnema/nefergui/internal/ui"
22)
23
24// Frame is valid only during one call to the view function. Root builds the
25// application element; Diagnostics reports identity problems in debug builds.
26// Alias methods are listed by go doc github.com/bnema/nefergui/internal/ui.Frame.
27type Frame = ui.Frame
28
29// Node is an ephemeral handle into the current frame. Do not retain it between
30// frames. Container methods (Box, Row, Column, Stack, Scroll, Header, Nav,
31// Main, Section, Aside, Footer, Element) return child nodes; control methods
32// (Button, Checkbox, Radio, Slider, Input, Textarea, Text, Heading, Image,
33// Icon, Separator, Spacer) declare controls. Interactive controls return event
34// snapshots.
35// Alias methods are listed by go doc github.com/bnema/nefergui/internal/ui.Node.
36type Node = ui.Node
37
38// ButtonEvent is an immutable snapshot queried with Activated.
39// Alias methods are listed by go doc github.com/bnema/nefergui/internal/ui.ButtonEvent.
40type ButtonEvent = ui.ButtonEvent
41
42// EditEvent is an immutable snapshot queried with Changed and Submitted.
43// Alias methods are listed by go doc github.com/bnema/nefergui/internal/ui.EditEvent.
44type EditEvent = ui.EditEvent
45
46// ChangeEvent is an immutable snapshot queried with Changed.
47// Alias methods are listed by go doc github.com/bnema/nefergui/internal/ui.ChangeEvent.
48type ChangeEvent = ui.ChangeEvent
49
50// Option families are sealed: ContainerOption, ButtonOption, EditOption,
51// ValueOption and HeadingOption accept the common CSS options (Key, ID,
52// Class, Inline) plus the control-specific options listed on each function.
53type (
54 ContainerOption = ui.ContainerOption
55 ButtonOption = ui.ButtonOption
56 EditOption = ui.EditOption
57 ValueOption = ui.ValueOption
58 HeadingOption = ui.HeadingOption
59 WindowOption = ui.WindowOption
60)
61
62// commonOption belongs to every option family; disabledOption to every
63// interactive control family. Both are concrete internal types, aliased so
64// the constructors below can return them without a second implementation.
65type (
66 commonOption = ui.CommonOption
67 disabledOption = ui.DisabledOption
68)
69
70// Key identifies an element among its siblings across frames.
71func Key(key string) commonOption { return ui.Key(key) }
72
73// ID sets the CSS ID; it does not affect frame identity.
74func ID(id string) commonOption { return ui.ID(id) }
75
76// Class adds a CSS class.
77func Class(class string) commonOption { return ui.Class(class) }
78
79// Inline applies inline CSS declarations.
80func Inline(src string) commonOption { return ui.Inline(src) }
81
82// Disabled blocks focus and interaction on an interactive control.
83func Disabled(v bool) disabledOption { return ui.Disabled(v) }
84
85// Level sets the accessibility heading level (1 through 6).
86func Level(level int) HeadingOption { return ui.Level(level) }
87
88// Placeholder sets the text shown in an empty editor.
89func Placeholder(v string) EditOption { return ui.Placeholder(v) }
90
91// Password masks displayed editor text and blocks copy and cut.
92func Password(v bool) EditOption { return ui.Password(v) }
93
94// Title sets the window title.
95func Title(s string) WindowOption { return ui.Title(s) }
96
97// Size sets the initial logical window size.
98func Size(w, h int) WindowOption { return ui.Size(w, h) }
99
100// Styles loads an author stylesheet from a file path.
101func Styles(s string) WindowOption { return ui.Styles(s) }
102
103// Transparent requests an alpha-capable Wayland surface (opaque by default).
104func Transparent() WindowOption { return ui.Transparent() }
105
106// Run builds and presents an immediate view on the Wayland session owner loop.
107func Run[T any](ctx context.Context, model *T, view func(*Frame, *T), options ...WindowOption) error {
108 return ui.Run(ctx, model, view, options...)
109}
110
111// RunFrames is a deterministic harness entry: each commit requests a redraw
112// and the loop stops after the given number of committed frames.
113func RunFrames[T any](ctx context.Context, frames int, model *T, view func(*Frame, *T), committed func(uint64) error, options ...WindowOption) error {
114 return ui.RunFrames(ctx, frames, model, view, committed, options...)
115}