ui

Documentation

Overview

Purpose: This file implements the Tempose Ahead-of-Time (AOT) component compilation engine.

Philosophy: GoStack treats frontend components (HTML, CSS, JS) as first-class Go citizens. Rather than parsing template files at runtime (which introduces disk I/O latency and defers syntax errors to production), the compiler transforms all component assets into static Go source code during the build step.

This means the generated file (gostack_components_gen.go) is a standard Go file that is compiled directly into the application binary. The result is:

• Zero disk I/O on every HTTP request for view rendering.
• Compile-time guarantees that all registered components exist.
• A single, portable binary with all assets embedded.

COMPONENT STRUCTURE: Each component lives in its own subdirectory under the components path:

components/
  counter/
    counter.html   ← markup template (supports {{ .Field }} bindings)
    counter.css    ← component-scoped styles
    counter.js     ← component-specific client scripts

The compiler scans this directory structure, processes each asset type, and emits a single Go registration file containing all compiled outputs.

Purpose: This file contains the Glide client-side reactive directive engine, embedded as a Go string constant so the entire runtime ships inside the binary — zero HTTP round-trips to load a JS file.

Philosophy: Glide is GoStack's browser-side reactivity layer. Like Alpine.js, it works directly on existing HTML via data attributes. Unlike Alpine, it is purpose-built for GoStack components and carries zero third-party footprint.

Package ui (Tempose + Glide) coordinates AOT component compilation, scoped asset collection, and the Glide client-side reactive directive engine runtime injection.

Index

• Constants
• func ApplyFilter(val any, filterName string, args ...string) string
• func Escape(val any) string
• func Evaluate(data any, field string) any
• func EvaluateBool(data any, field string) bool
• func EvaluateSlice(data any, field string) []any
• func FilterDate(val any, args ...string) string
• func FilterLower(val any, _ ...string) string
• func FilterPlural(val any, args ...string) string
• func FilterSlugify(val any, _ ...string) string
• func FilterTruncate(val any, args ...string) string
• func FilterUpper(val any, _ ...string) string
• func RegisterComponentScript(name, js string)
• func RegisterComponentStyle(name, prefixedCSS string)
• func RegisterFilter(name string, fn any)
• func WriteMasterAssetBlock(w io.Writer)
• type AssetCompiler
  • func NewAssetCompiler(componentsPath, outputPath string) *AssetCompiler
  • func (c *AssetCompiler) Run() error
• type HotReloadWatcher
  • func NewHotReloadWatcher(compiler *AssetCompiler, interval time.Duration) *HotReloadWatcher
  • func (w *HotReloadWatcher) ServeSSE(writer interface{ ... }, req interface{ ... })
  • func (w *HotReloadWatcher) Start(ctx interface{ ... })
• type SafeHTML

Constants

const GlideJS = `` /* 56795-byte string literal not displayed */

GlideJS is the Glide reactive directive engine runtime, injected into every GoStack page via WriteMasterAssetBlock. It is written as a pure JavaScript IIFE with zero external dependencies and works in any modern browser.

const GoStackCoreCSS = `` /* 472513-byte string literal not displayed */

GoStackCoreCSS provides the global semantic styles for elements opting-in via [gs-css].

Functions

func ApplyFilter

func ApplyFilter(val any, filterName string, args ...string) string

ApplyFilter invokes a named filter on the given value with optional string arguments. It returns the filtered string, or the original fmt.Sprint value if the filter is not found.

func Escape

func Escape(val any) string

Escape sanitizes template output to prevent XSS, unless the value is marked as SafeHTML or template.HTML.

func Evaluate

func Evaluate(data any, field string) any

Evaluate performs a safe runtime reflection lookup of a field name on a given data object. It supports nested dot-notation paths (e.g. "User.Profile.Name").

func EvaluateBool

func EvaluateBool(data any, field string) bool

EvaluateBool inspects the resolved value of a field path and returns its truthiness.

func EvaluateSlice

func EvaluateSlice(data any, field string) []any

EvaluateSlice inspects the field path and returns a slice of interfaces.

func FilterDate

func FilterDate(val any, args ...string) string

FilterDate formats a time.Time or parseable string using Go reference time layout. Format defaults to "2006-01-02" if empty.

func FilterLower

func FilterLower(val any, _ ...string) string

FilterLower converts the value to lowercase.

func FilterPlural

func FilterPlural(val any, args ...string) string

FilterPlural returns the singular or plural form based on the "count" string arg. Usage in template: {{ count | plural("apple", "apples") }}

func FilterSlugify

func FilterSlugify(val any, _ ...string) string

FilterSlugify converts a string to a URL-safe, dash-separated slug.

func FilterTruncate

func FilterTruncate(val any, args ...string) string

FilterTruncate shortens a string to the given character length, appending "…" if cut.

func FilterUpper

func FilterUpper(val any, _ ...string) string

FilterUpper converts the value to uppercase.

func RegisterComponentScript

func RegisterComponentScript(name, js string)

RegisterComponentScript registers component-scoped JS scripts during system boot passes.

func RegisterComponentStyle

func RegisterComponentStyle(name, prefixedCSS string)

RegisterComponentStyle saves isolated, prefixed component CSS configurations during system boot passes.

func RegisterFilter

func RegisterFilter(name string, fn any)

RegisterFilter adds or overrides a named template filter. The fn value must be a function with signature func(val any, args ...string) string.

func WriteMasterAssetBlock

func WriteMasterAssetBlock(w io.Writer)

WriteMasterAssetBlock streams the GoStack core styles, the Glide reactive runtime, and all registered component-scoped styles and scripts into the HTTP response writer. It is called once per page render, typically just before the closing </head> tag. No arguments are required — the Glide engine is embedded directly from GlideJS.

Types

type AssetCompiler

type AssetCompiler struct {
	ComponentsPath string
	OutputPath     string
}

AssetCompiler orchestrates the full component compilation pipeline. It scans the components source directory, processes all assets (HTML, CSS, JS), and writes a fully compiled, Go-formatted registration file to the output path.

Fields:

• ComponentsPath: Absolute or relative path to the components source directory.
• OutputPath: Absolute or relative path where the generated Go file will be written.

func NewAssetCompiler

func NewAssetCompiler(componentsPath, outputPath string) *AssetCompiler

NewAssetCompiler returns a pointer to an initialized AssetCompiler.

func (*AssetCompiler) Run

func (c *AssetCompiler) Run() error

Run executes the full compilation sequence.

type HotReloadWatcher

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

HotReloadWatcher polls a components directory for file changes and re-runs the AssetCompiler automatically. On each rebuild it broadcasts a reload signal to all connected SSE clients so the browser refreshes instantly — with zero external dependencies (no inotify, no fsnotify, no CGO).

Usage in your dev server entrypoint:

watcher := ui.NewHotReloadWatcher(compiler, 500*time.Millisecond)
go watcher.Start(ctx)
// Register the SSE endpoint with your router:
router.Get("/__gostack_reload", func(ctx *http.Context) {
    watcher.ServeSSE(ctx.Writer, ctx.Request)
})

In your base layout HTML add:

<script>
  if (location.hostname === 'localhost') {
    const es = new EventSource('/__gostack_reload');
    es.onmessage = () => location.reload();
  }
</script>

func NewHotReloadWatcher

func NewHotReloadWatcher(compiler *AssetCompiler, interval time.Duration) *HotReloadWatcher

NewHotReloadWatcher creates a watcher that polls the compiler's ComponentsPath. interval controls how often the directory is scanned for changes.

func (*HotReloadWatcher) ServeSSE

func (w *HotReloadWatcher) ServeSSE(writer interface {
	Header() interface{ Set(string, string) }
	WriteHeader(int)
	Write([]byte) (int, error)
	Flush()
}, req interface {
	Context() interface{ Done() <-chan struct{} }
})

ServeSSE writes an HTTP/SSE stream that sends a "reload" event whenever the compiler detects a component change. Connect a browser EventSource to this endpoint to get automatic page refreshes during development.

func (*HotReloadWatcher) Start

func (w *HotReloadWatcher) Start(ctx interface{ Done() <-chan struct{} })

Start begins the polling loop. It blocks until ctx.Done() is closed. Run this in a goroutine: go watcher.Start(ctx)

type SafeHTML

type SafeHTML string

SafeHTML represents a string value that has already been sanitized and can be safely rendered as raw HTML.