node

type Attribute ¶

type Attribute struct {
	// Key is the attribute name as it appears in the rendered HTML
	// (for example "class", "data-id", or "hx-get"). It is written
	// verbatim - callers are expected to pass a valid attribute name.
	Key string

	// Value is the attribute value as it appears in the rendered HTML.
	// It is written verbatim and is not HTML-escaped, so callers that
	// accept untrusted input must escape before storing.
	Value string
}

Attribute is a single HTML attribute pair held in an element's generic attribute slice. Typed attributes live in dedicated struct fields; this type backs the catch-all storage that [Element.SetAttribute], SetAria, and SetData write into.

type ConditionalBuilder ¶

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

ConditionalBuilder provides a fluent API for conditional rendering. It allows you to specify different content based on a boolean condition.

Nil nodes are safely ignored - if a nil node is provided to True() or False(), it will not be stored and nothing will be rendered for that path.

Chain .Dynamic("key") to enable diff engine tracking. Without a key, the differ cannot produce targeted patches for conditional content.

Usage:

node.Condition(user.IsLoggedIn).
    True(p.Text("Welcome back!")).
    False(p.Text("Please log in")).
    Dynamic("auth-message")

func Condition(condition bool) *ConditionalBuilder

func Unless(condition bool, node Node) *ConditionalBuilder

Unless(user.IsLoggedIn, a.New().Href("/login").Text("Sign in"))

func When(condition bool, node Node) *ConditionalBuilder

When(user.IsAdmin, span.Static("Admin"))

func (c *ConditionalBuilder) Dynamic(key string) *ConditionalBuilder

func (c *ConditionalBuilder) DynamicKey() string

func (c *ConditionalBuilder) False(node Node) *ConditionalBuilder

func (c *ConditionalBuilder) IsDynamic() bool

func (c *ConditionalBuilder) Nodes() []Node

func (c *ConditionalBuilder) Render(w ...io.Writer) []byte

func (c *ConditionalBuilder) RenderBuilder(buf *bytes.Buffer)

func (c *ConditionalBuilder) True(node Node) *ConditionalBuilder

type Dynamic ¶

type Dynamic interface {
	IsDynamic() bool
	DynamicKey() string
}

Dynamic represents nodes that contain dynamic content requiring re-evaluation on each render. The fluent-jit diff engine and Tether's reactive UI use this interface to identify trackable nodes in the render tree.

IsDynamic reports whether the node produces different output across renders. DynamicKey returns the developer-assigned key used by the diff engine to track changes. Nodes without a key return an empty string and are not individually tracked.

HTML elements, FunctionComponent, FuncsComponent, and ConditionalBuilder all satisfy this interface. Call .Dynamic(key) on any of them to assign a tracking key.

type Element ¶

type Element interface {
	Node

	// SetAttribute is the escape hatch for attributes that Fluent's typed
	// API does not cover - framework directives like Alpine.js (x-on:click)
	// or HTMX (hx-get), and any other custom or non-standard attribute.
	//
	// For everything else, prefer the typed methods on each element
	// (.Class, .Href, .Checked, ...). They produce the right escaping,
	// validate enumerated values at compile time, and chain. SetAttribute
	// returns nothing on purpose - it cannot be chained, which keeps the
	// Fluent API the obvious default.
	//
	// For ARIA attributes use SetAria(name, value); for data-* attributes
	// use SetData(name, value). Both return the element for chaining.
	SetAttribute(key string, value string)

	// RenderOpen writes the opening tag, including the element name and
	// every attribute, into buf. JIT compilation caches this output
	// separately from the children so static wrappers can be pre-rendered
	// while dynamic content re-evaluates each render. For <div class="x">
	// it writes the entire opening fragment.
	RenderOpen(buf *bytes.Buffer)

	// RenderClose writes the closing tag (or the self-closing terminator
	// for void elements) into buf. Paired with RenderOpen so the JIT can
	// cache the open and close fragments independently of the children
	// rendered between them.
	RenderClose(buf *bytes.Buffer)
}

Element extends Node for HTML elements that have attributes and an open/close tag structure. Not all nodes are elements - text nodes, function components, and conditionals are not. This separation allows extensions (htmx, turbo, shoelace) to accept only types that genuinely support attributes, and allows JIT compilation to pre-render static wrapper tags independently of dynamic content.

type FuncsComponent ¶ added in v0.2.0

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

FuncsComponent enables dynamic content generation of multiple nodes. The function is called during rendering to generate the actual node content. This is useful for generating lists of items, e.g. from a loop.

Nil nodes are safely ignored - any nil nodes in the returned slice will be skipped.

Chain .Dynamic("key") to enable diff engine tracking. Without a key, the differ cannot produce targeted patches for content generated by the function.

Usage:

node.Funcs(func() []Node {
    nodes := []Node{}
    for _, item := range items {
        nodes = append(nodes, li.Text(item.Name))
    }
    return nodes
}).Dynamic("item-list")

func Funcs(fn func() []Node) *FuncsComponent

func Map[T any](items []T, fn func(T) Node) *FuncsComponent

node.Map(categories, func(c domain.Category) node.Node {
    return label.New(
        input.New().Type(inputtype.Checkbox).Value(strconv.Itoa(c.ID)).
            Checked(slices.Contains(selected, c.ID)),
        text.Text(c.Name),
    )
})

func (f *FuncsComponent) Dynamic(key string) *FuncsComponent

func (f *FuncsComponent) DynamicKey() string

func (f *FuncsComponent) IsDynamic() bool

func (f *FuncsComponent) Nodes() []Node

func (f *FuncsComponent) Render(w ...io.Writer) []byte

func (f *FuncsComponent) RenderBuilder(buf *bytes.Buffer)

type FunctionComponent ¶

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

FunctionComponent enables dynamic content generation through function calls. The function is called during rendering to generate the actual node content. This is useful for complex conditional logic, loops, and data transformations.

Nil nodes are safely ignored - if the function returns nil, nothing will be rendered.

Chain .Dynamic("key") to enable diff engine tracking. Without a key, the differ cannot produce targeted patches for content generated by the function.

Usage:

node.Func(func() Node {
    if user.IsLoggedIn {
        return div.Text("Welcome back!")
    }
    return div.Text("Please log in")
}).Dynamic("greeting")

func Func(fn func() Node) *FunctionComponent

func (f *FunctionComponent) Dynamic(key string) *FunctionComponent

func (f *FunctionComponent) DynamicKey() string

func (f *FunctionComponent) IsDynamic() bool

func (f *FunctionComponent) Nodes() []Node

func (f *FunctionComponent) Render(w ...io.Writer) []byte

func (f *FunctionComponent) RenderBuilder(buf *bytes.Buffer)

type MemoisedNode ¶ added in v0.2.2

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

MemoisedNode wraps a lazy closure with a cache key. It satisfies Node so it slots into any position in a render tree, and Memoiser so the diff engine's memoisation layer can inspect the key.

func Memoise(key any, fn func() Node) *MemoisedNode

node.Memoise(s.ItemsVersion, func() node.Node {
    return renderTable(s.Items)
})

func (m *MemoisedNode) MemoiseKey() any

func (m *MemoisedNode) MemoiseRender() Node

func (m *MemoisedNode) Nodes() []Node

func (m *MemoisedNode) Render(w ...io.Writer) []byte

func (m *MemoisedNode) RenderBuilder(buf *bytes.Buffer)

type Memoiser ¶ added in v0.2.2

type Memoiser interface {
	MemoiseKey() any
	MemoiseRender() Node
}

Memoiser is satisfied by nodes that carry a cache key for the diff engine's memoisation layer. When the key matches the previous render at the same tree position, the subtree is skipped entirely - the closure never runs and no diff is computed for that region.

Regular Diff does not check for this interface. Only fluent-jit's [jit.Memoiser] struct inspects it. When Diff encounters a memoised node, it calls Render/RenderBuilder/Nodes like any other node (the closure executes unconditionally). This makes memoised nodes transparent to code that does not use memoisation.

type Node ¶

type Node interface {
	// Render returns the HTML as a byte slice, or writes it to the provided writer.
	// Use this for top-level rendering where you need the final output.
	//
	// Write errors are deliberately discarded rather than returned. A write
	// failure during rendering is almost always a disconnected client or a
	// closed stream - a condition the render tree cannot act on. The real
	// error path lives with the writer's owner (the HTTP handler, the buffer
	// consumer), not inside rendering. Returning an error here would force
	// every node in the tree to handle a failure that isn't its to handle.
	// Implementations silently drop write errors on purpose.
	Render(w ...io.Writer) []byte

	// RenderBuilder writes HTML into a shared buffer to avoid allocations
	// when composing a tree of nodes. Parent nodes call this on their children.
	RenderBuilder(*bytes.Buffer)

	// Nodes returns the children that will be rendered. For conditionals
	// this is the active branch only; for function components this is the
	// evaluated output. Tree walkers rely on this matching Render output.
	Nodes() []Node
}

Node represents any renderable item in an HTML document tree. This is the base contract that all renderable types satisfy - text, elements, function components, and conditionals alike.