Virgil 5b69aec575

Security Scan / security (push) Waiting to run

Details

Test / test (push) Waiting to run

Details

Co-Authored-By: Virgil <virgil@lethean.io>

2026-04-04 00:13:10 +00:00

5.3 KiB

Raw Blame History

title	description
go-html	HLCRF DOM compositor with grammar pipeline integration for type-safe server-side HTML generation and optional WASM client rendering.

go-html

go-html is a pure-Go library for building HTML documents as type-safe node trees and rendering them to string output. It provides a five-slot layout compositor (Header, Left, Content, Right, Footer -- abbreviated HLCRF), a responsive multi-variant wrapper, a server-side grammar analysis pipeline, a Web Component code generator, and an optional WASM module for client-side rendering.

Module path: forge.lthn.ai/core/go-html Go version: 1.26 Licence: EUPL-1.2

Quick Start

package main

import html "forge.lthn.ai/core/go-html"

func main() {
    page := html.NewLayout("HCF").
        H(html.El("nav", html.Text("nav.label"))).
        C(html.El("article",
            html.El("h1", html.Text("page.title")),
            html.Each(items, func(item Item) html.Node {
                return html.El("li", html.Text(item.Name))
            }),
        )).
        F(html.El("footer", html.Text("footer.copyright")))

    output := page.Render(html.NewContext())
}

This builds a Header-Content-Footer layout with semantic HTML elements (<header>, <main>, <footer>), ARIA roles, and deterministic data-block path identifiers. Text nodes pass through the go-i18n translation layer and are HTML-escaped by default.

Package Layout

Path	Purpose
`node.go`	`Node` interface and all node types: `El`, `Text`, `Raw`, `If`, `Unless`, `Each`, `EachSeq`, `Switch`, `Entitled`, plus `AriaLabel`, `AriaControls`, `AriaHasPopup`, `AriaOwns`, `AriaKeyShortcuts`, `Alt`/`AltText`, `AriaBusy`, `AriaLive`, `AriaDescription`, `AriaDetails`, `AriaErrorMessage`, `AriaRoleDescription`, `AriaDisabled`, `AriaModal`, `AriaChecked`, `AriaInvalid`, `AriaRequired`, `AriaPressed`, `AriaSelected`, `Hidden`, `TabIndex`, and `AutoFocus` helpers
`layout.go`	HLCRF compositor with semantic HTML elements and ARIA roles
`responsive.go`	Multi-variant breakpoint wrapper (`data-variant` containers, CSS scoping helpers)
`context.go`	Rendering context: identity, locale, entitlements, i18n service
`render.go`	`Render()` convenience function
`path.go`	`ParseBlockID()` for decoding `data-block` path attributes
`pipeline.go`	`StripTags`, `Imprint`, `CompareVariants` (server-side only, `!js` build tag)
`codegen/codegen.go`	Web Component class generation and TypeScript declarations (closed Shadow DOM)
`cmd/codegen/main.go`	Build-time CLI: JSON slot map on stdin, JS bundle on stdout, `-dts` for `.d.ts` output, `-watch` for file polling
`cmd/wasm/main.go`	WASM entry point exporting `renderToString()` and `registerComponents()` to JavaScript

Key Concepts

Node tree -- All renderable units implement Node, a single-method interface: Render(ctx *Context) string. The library composes nodes into trees using El() for elements, Text() for translated text, and control-flow constructors (If, Unless, Each, Switch, Entitled), plus accessibility and visibility helpers such as AriaLabel(), AriaControls(), AriaHasPopup(), AriaOwns(), AriaKeyShortcuts(), AriaCurrent(), AriaBusy(), AriaLive(), AriaDescription(), AriaDetails(), AriaErrorMessage(), AriaRoleDescription(), AriaHidden(), Hidden(), AriaDisabled(), AriaModal(), AriaChecked(), AriaInvalid(), AriaRequired(), AriaReadOnly(), and TabIndex().

HLCRF Layout -- A five-slot compositor that maps to semantic HTML: <header> (H), <aside> (L/R), <main> (C), <footer> (F). The variant string controls which slots render: "HLCRF" for all five, "HCF" for three, "C" for content only. Layouts nest: placing a Layout inside another layout's slot produces hierarchical data-block paths like L-0-C-0.

Responsive variants -- Responsive wraps multiple Layout instances with named breakpoints (e.g. "desktop", "mobile"). Each variant renders inside a <div data-variant="name"> container for CSS or JavaScript targeting.

Grammar pipeline -- Server-side only. Imprint() renders a node tree to HTML, strips tags, tokenises the plain text via go-i18n/reversal, and returns a GrammarImprint for semantic analysis. CompareVariants() computes pairwise similarity scores across responsive variants.

Web Component codegen -- cmd/codegen/ generates ES2022 Web Component classes with closed Shadow DOM from a JSON slot-to-tag mapping. This is a build-time tool, not used at runtime. It also supports -watch for polling an input JSON file and rewriting an output bundle in place.

Dependencies

forge.lthn.ai/core/go-html
  forge.lthn.ai/core/go-i18n          (direct, all builds)
    forge.lthn.ai/core/go-inference    (indirect, via go-i18n)
  forge.lthn.ai/core/go-i18n/reversal (server builds only, !js)
  github.com/stretchr/testify          (test only)

Both go-i18n and go-inference must be present on the local filesystem. The go.mod uses replace directives pointing to sibling directories (../go-i18n, ../go-inference).

5.3 KiB Raw Blame History