go-html/specs/root.md

html

Import: dappco.re/go/core/html Files: 13

Types

Context

type Context struct

Context carries rendering state through the node tree. Usage example: ctx := NewContext()

Fields:

• Identity string
• Locale string
• Entitlements func(feature string) bool
• Data map[string]any
• Unexported fields are present.

Methods: None.

Layout

type Layout struct

Layout is an HLCRF compositor. Arranges nodes into semantic HTML regions with deterministic path-based IDs. Usage example: page := NewLayout("HCF").H(Text("title")).C(Text("body"))

Fields:

• No exported fields.
• Unexported fields are present.

Methods:

• func (l *Layout) C(nodes ...Node) *Layout C appends nodes to the Content (main) slot. Usage example: NewLayout("C").C(Text("body"))
• func (l *Layout) F(nodes ...Node) *Layout F appends nodes to the Footer slot. Usage example: NewLayout("CF").F(Text("footer"))
• func (l *Layout) H(nodes ...Node) *Layout H appends nodes to the Header slot. Usage example: NewLayout("HCF").H(Text("title"))
• func (l *Layout) L(nodes ...Node) *Layout L appends nodes to the Left aside slot. Usage example: NewLayout("LC").L(Text("nav"))
• func (l *Layout) R(nodes ...Node) *Layout R appends nodes to the Right aside slot. Usage example: NewLayout("CR").R(Text("ads"))
• func (l *Layout) Render(ctx *Context) string Render produces the semantic HTML for this layout. Usage example: html := NewLayout("C").C(Text("body")).Render(NewContext()) Only slots present in the variant string are rendered.

Node

type Node interface

Node is anything renderable. Usage example: var n Node = El("div", Text("welcome"))

Members:

• Render(ctx *Context) string

Methods: None.

Responsive

type Responsive struct

Responsive wraps multiple Layout variants for breakpoint-aware rendering. Usage example: r := NewResponsive().Variant("mobile", NewLayout("C")) Each variant is rendered inside a container with data-variant for CSS targeting.

Fields:

• No exported fields.
• Unexported fields are present.

Methods:

• func (r *Responsive) Render(ctx *Context) string Render produces HTML with each variant in a data-variant container. Usage example: html := NewResponsive().Variant("mobile", NewLayout("C")).Render(NewContext())
• func (r *Responsive) Variant(name string, layout *Layout) *Responsive Variant adds a named layout variant (e.g., "desktop", "tablet", "mobile"). Usage example: NewResponsive().Variant("desktop", NewLayout("HLCRF")) Variants render in insertion order.

Translator

type Translator interface

Translator provides Text() lookups for a rendering context. Usage example: ctx := NewContextWithService(myTranslator)

The default server build uses go-i18n. Alternate builds, including WASM, can provide any implementation with the same T() method.

Members:

• T(key string, args ...any) string

Methods: None.

Functions

Attr

func Attr(n Node, key, value string) Node

Attr sets an attribute on an El node. Returns the node for chaining. Usage example: Attr(El("a", Text("docs")), "href", "/docs") It recursively traverses through wrappers like If, Unless, and Entitled.

CompareVariants

func CompareVariants(r *Responsive, ctx *Context) map[string]float64

CompareVariants runs the imprint pipeline on each responsive variant independently and returns pairwise similarity scores. Key format: "name1:name2". Usage example: scores := CompareVariants(NewResponsive(), NewContext())

Each

func Each[T any](items []T, fn func(T) Node) Node

Each iterates items and renders each via fn. Usage example: Each([]string{"a", "b"}, func(v string) Node { return Text(v) })

EachSeq

func EachSeq[T any](items iter.Seq[T], fn func(T) Node) Node

EachSeq iterates an iter.Seq and renders each via fn. Usage example: EachSeq(slices.Values([]string{"a", "b"}), func(v string) Node { return Text(v) })

El

func El(tag string, children ...Node) Node

El creates an HTML element node with children. Usage example: El("section", Text("welcome"))

Entitled

func Entitled(feature string, node Node) Node

Entitled renders child only when entitlement is granted. Absent, not hidden. Usage example: Entitled("beta", Text("preview")) If no entitlement function is set on the context, access is denied by default.

If

func If(cond func(*Context) bool, node Node) Node

If renders child only when condition is true. Usage example: If(func(ctx *Context) bool { return ctx.Identity != "" }, Text("hi"))

Imprint

func Imprint(node Node, ctx *Context) reversal.GrammarImprint

Imprint renders a node tree to HTML, strips tags, tokenises the text, and returns a GrammarImprint — the full render-reverse pipeline. Usage example: imp := Imprint(Text("welcome"), NewContext())

NewContext

func NewContext() *Context

NewContext creates a new rendering context with sensible defaults. Usage example: html := Render(Text("welcome"), NewContext())

NewContextWithService

func NewContextWithService(svc Translator) *Context

NewContextWithService creates a rendering context backed by a specific translator. Usage example: ctx := NewContextWithService(myTranslator)

NewLayout

func NewLayout(variant string) *Layout

NewLayout creates a new Layout with the given variant string. Usage example: page := NewLayout("HLCRF") The variant determines which slots are rendered (e.g., "HLCRF", "HCF", "C").

NewResponsive

func NewResponsive() *Responsive

NewResponsive creates a new multi-variant responsive compositor. Usage example: r := NewResponsive()

ParseBlockID

func ParseBlockID(id string) []byte

ParseBlockID extracts the slot sequence from a data-block ID. Usage example: slots := ParseBlockID("L-0-C-0") "L-0-C-0" → ['L', 'C']

Raw

func Raw(content string) Node

Raw creates a node that renders without escaping (escape hatch for trusted content). Usage example: Raw("trusted")

Render

func Render(node Node, ctx *Context) string

Render is a convenience function that renders a node tree to HTML. Usage example: html := Render(El("main", Text("welcome")), NewContext())

StripTags

func StripTags(html string) string

StripTags removes HTML tags from rendered output, returning plain text. Usage example: text := StripTags("

Hello world") Tag boundaries are collapsed into single spaces; result is trimmed. Does not handle script/style element content (go-html does not generate these).

Switch

func Switch(selector func(*Context) string, cases map[string]Node) Node

Switch renders based on runtime selector value. Usage example: Switch(func(ctx *Context) string { return ctx.Locale }, map[string]Node{"en": Text("hello")})

Text

func Text(key string, args ...any) Node

Text creates a node that renders through the go-i18n grammar pipeline. Usage example: Text("welcome", "Ada") Output is HTML-escaped by default. Safe-by-default path.

Unless

func Unless(cond func(*Context) bool, node Node) Node

Unless renders child only when condition is false. Usage example: Unless(func(ctx *Context) bool { return ctx.Identity == "" }, Text("welcome"))