Documentation
¶
Overview ¶
Package dom provides a live DOM renderer for the gui library that runs in WebAssembly. It mounts a gui.Node tree into a browser DOM element, wires up event listeners for handler props (onclick, oninput, etc.), and supports incremental updates via the gui.Diff engine.
Index ¶
- func Route(path string, handler func(gui.Params) gui.Node, children ...gui.RouteConfig) gui.RouteConfig
- func RouteWithGuards(path string, handler func(gui.Params) gui.Node, guards []gui.RouteGuard, ...) gui.RouteConfig
- func RouteWithLayout(path string, layout func(outlet gui.Node) gui.Node, ...) gui.RouteConfig
- type App
- type Renderer
- type Router
- type RouterMode
- type RouterOption
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func Route ¶
func Route(path string, handler func(gui.Params) gui.Node, children ...gui.RouteConfig) gui.RouteConfig
Route creates a RouteConfig for use with WithRoutes.
func RouteWithGuards ¶
func RouteWithGuards(path string, handler func(gui.Params) gui.Node, guards []gui.RouteGuard, children ...gui.RouteConfig) gui.RouteConfig
RouteWithGuards creates a RouteConfig with guards.
func RouteWithLayout ¶
func RouteWithLayout(path string, layout func(outlet gui.Node) gui.Node, children ...gui.RouteConfig) gui.RouteConfig
RouteWithLayout creates a RouteConfig with a layout wrapper.
Types ¶
type App ¶
type App struct {
// contains filtered or unexported fields
}
App manages the lifecycle of a DOM application. It resolves the component tree, auto-wires SetOnChange on stateful components so that state changes trigger re-renders, and calls DidUnmount when components are removed from the tree.
Usage:
app := dom.NewApp(container, func() gui.Node {
return buildApp(store.Get())
})
defer app.Release()
app.Run()
func NewApp ¶
NewApp creates an App that renders into the given container element. The root function is called on every render to produce the node tree.
func (*App) Release ¶
func (a *App) Release()
Release unwires all mounted components (SetOnChange(nil) + DidUnmount) and releases the underlying renderer and the rAF callback.
func (*App) Render ¶
func (a *App) Render()
Render schedules a render on the next animation frame. Multiple calls between frames are coalesced into a single render pass, preventing high-frequency state updates (e.g. streaming WebSocket tokens) from blocking the JS event loop and dropping keyboard input.
type Renderer ¶
type Renderer struct {
// contains filtered or unexported fields
}
Renderer renders gui.Node trees into live browser DOM elements. It resolves components, builds DOM nodes, and wires event listeners for handler props. Use New to create a renderer mounted on a container element.
func New ¶
New creates a DOM Renderer that mounts into the given container element. Typically called with document.getElementById("app"). Panics if the container is null or undefined — this usually means the element does not exist yet (e.g. WASM started before DOMContentLoaded).
func (*Renderer) Release ¶
func (r *Renderer) Release()
Release frees all JavaScript callback functions and revokes any tracked object URLs. Call this when the renderer is no longer needed to prevent memory leaks.
func (*Renderer) Render ¶
Render resolves components in node and writes an HTML string representation to w. This satisfies gui.Renderer but for DOM usage prefer [Update] which creates live DOM nodes with event handlers.
func (*Renderer) RenderString ¶
RenderString returns the node tree as an HTML string. For live DOM rendering with events, use [Update] instead.
func (*Renderer) Update ¶
Update re-resolves the root function, diffs against the previous tree, and applies patches to the live DOM. On the first call it replaces the container's content entirely.
func (*Renderer) UpdateTree ¶
UpdateTree diffs newTree (which must already be resolved) against the previous tree and applies patches to the live DOM. On the first call it replaces the container's content entirely.
Use this when you need to resolve the tree yourself (e.g. via gui.ResolveTracked) and want to avoid double-resolving.
type Router ¶
type Router struct {
// contains filtered or unexported fields
}
Router provides hash-based or history-based routing for single-page WASM applications. It listens for URL changes and exposes the current route through a gui.Store. It supports declarative route configuration with pattern matching, named parameters, nested routes, layouts, and guards.
Basic usage (manual matching):
router := dom.NewRouter()
defer router.Release()
router.Navigate("/about")
Declarative usage:
router := dom.NewRouter(
dom.WithRoutes(
dom.Route("/", homePage),
dom.Route("/user/:id", userPage),
),
)
defer router.Release()
page := router.Render() // returns matched page Node
func NewRouter ¶
func NewRouter(opts ...RouterOption) *Router
NewRouter creates a Router, reads the initial URL, and begins listening for navigation events. Options configure the routing mode, route table, and global guards.
func (*Router) Match ¶
func (r *Router) Match() *gui.RouteMatch
Match returns the full RouteMatch for the current path, or nil if no routes are configured or nothing matches.
func (*Router) Navigate ¶
Navigate changes the route. This triggers navigation events which update the store and notify subscribers. Guards are checked before the navigation is committed.
func (*Router) Params ¶
Params returns the named parameters extracted from the current route. Returns nil if no routes are configured or the current path doesn't match.
func (*Router) Release ¶
func (r *Router) Release()
Release removes the navigation event listener and frees the JS callback. Call this when the router is no longer needed.
func (*Router) Render ¶
Render matches the current path against the route configuration and returns the resulting Node (with layouts applied). Returns nil if no routes are configured or no route matches.
type RouterMode ¶
type RouterMode int
RouterMode controls whether the router uses hash fragments or the History API.
const ( // HashMode uses location.hash and hashchange events (default). // URLs look like: http://example.com/#/about HashMode RouterMode = iota // HistoryMode uses the History API (pushState/popstate). // URLs look like: http://example.com/about // Requires server-side configuration to serve index.html for all routes. HistoryMode )
type RouterOption ¶
type RouterOption func(*routerConfig)
RouterOption configures a Router.
func BeforeEach ¶
func BeforeEach(guard gui.RouteGuard) RouterOption
BeforeEach registers a global navigation guard. Guards are checked in order before every navigation. If any guard returns false, navigation is cancelled.
func WithHistoryMode ¶
func WithHistoryMode() RouterOption
WithHistoryMode sets the router to use the History API instead of hash fragments.
func WithRoutes ¶
func WithRoutes(routes ...gui.RouteConfig) RouterOption
WithRoutes sets the declarative route configuration for the router. When routes are configured, use router.Render() to get the matched page Node.
Source Files