Render UI templates through wrapper divs

Author: linkdata

.agents/skills/jaws/SKILL.md

@@ -79,6 +79,7 @@ These are the two usual building blocks for widget handlers passed to `$.Button`
 ## Template-dot and tag rules
 
 - `ui.Template` expands `Dot` into tags via `tag.TagExpand` (package `github.com/linkdata/jaws/lib/tag`, imported as `tag`); the root dot is part of identity/tag behavior.
+- `ui.Template` is for partial templates only; full document/page templates should be rendered through `ui.Handler`.
 - Prefer comparable root dots (pointers or small comparable structs).
 - If root dot is non-comparable, implement `JawsGetTag(tag.Context) any` and return a comparable tag.
 - Do not use plain `string`, numeric, `bool`, `template.HTML`, or `template.HTMLAttr` as tags; `tag.TagExpand` rejects them.
@@ -94,7 +95,8 @@ JaWS parses template params as:
 Implications:
 - Non-comparable handlers are not auto-tagged unless they implement `tag.TagGetter`.
 - Pass explicit tags when dirty targeting depends on them.
-- Include wrapper markup attributes via `{{$.Attrs}}`.
+- HTML attributes passed to `$.Template(...)` are applied to the generated template wrapper.
+- Template bodies used with `$.Template(...)` must be partials, not full documents.
 - For dynamic button text, avoid passing plain static strings if the value must change after render; use getter-based values so updates reflect new state.
 
 ## Event handling model
@@ -110,13 +112,14 @@ The handler candidate is asked via `JawsClick` / `JawsContextMenu` / `JawsInput`
 For clickable content rendering:
 - Prefer a template dot with `JawsClick` over passing redundant explicit click handlers.
 - Use explicit click handler params only when dot-owned handling is not viable.
-- Wrapper template root should include `id="{{$.Jid}}" {{$.Attrs}}`.
-- Add interaction semantics where needed, for example `role="button" tabindex="0"`.
+- `ui.Template` creates the outer JaWS wrapper; template roots should not declare the JaWS ID or carry forwarded wrapper attributes.
+- Add interaction semantics where needed through Template params, for example `role="button"` and `tabindex="0"`.
 - Keep body partials presentational; attach behavior at wrapper/dot level.
 
 ## Rendering and update rules
 
 - Keep HTML structure in templates; avoid manual HTML string assembly in Go.
+- `ui.Template.JawsUpdate` re-renders the template data into the generated wrapper; custom `Dot.JawsUpdate` methods are not called by Template.
 - HTML getter paths must not mutate domain state, but they may call element update methods (`SetClass`, `RemoveClass`, `SetAttr`, `RemoveAttr`, etc.) on the passed-in `*Element` to co-ordinate wrapper class/attribute changes with the inner-HTML refresh. No custom `JawsUpdate` is needed for that case — the queued wrapper updates flush alongside the `SetInner` from `HTMLInner.JawsUpdate`.
 - Use a custom `JawsUpdate` only when the widget's update logic diverges from "render the getter again" — e.g. to compare against a stored last-value and skip the update (as the input widgets do).
 - `Element.SetAttr/RemoveAttr/SetClass/RemoveClass/SetInner/SetValue/Append/Order/Remove/Replace` are update-time operations; call them only from render/update processing.

jaws_test.go

@@ -875,7 +875,7 @@ func TestJaws_Session(t *testing.T) {
 	}
 
 	h.ServeHTTP(&rr, r)
-	if got := buf.String(); got != `<div id="Jid.1" >123</div>` {
+	if got := buf.String(); got != `<div id="Jid.1" data-jawstemplate>123</div>` {
 		t.Error(got)
 	}
 

lib/assets/jaws.css

@@ -1,3 +1,7 @@
+[data-jawstemplate]:not([hidden]) {
+    display: contents;
+}
+
 .jaws-lost {
     display: flex;
     position: relative;
@@ -13,4 +17,3 @@
     background-color: red;
     color: white;
 }
-

lib/ui/README.md

@@ -13,6 +13,11 @@ This package is the home of JaWS widget implementations.
 
 `ui.RequestWriter` exposes helper methods like `rw.Span(...)`,
 `rw.Text(...)`, and `rw.Select(...)` for concise template use.
+`rw.Template(...)` renders partial templates inside a generated JaWS wrapper,
+so template bodies should let that wrapper own JaWS identity and wrapper-level
+attributes. Attribute params passed to `rw.Template(...)` are applied to the
+generated wrapper. Template bodies used with `rw.Template(...)` must be
+partials; full page templates should be rendered through `ui.Handler`.
 
 You can also use explicit constructors through:
 

lib/ui/handler.go

@@ -1,31 +1,43 @@
 package ui
 
 import (
+	"io"
 	"net/http"
 
 	"github.com/linkdata/jaws"
 )
 
-// uiHandler is an http.uiHandler that renders a template for every request.
+// uiHandler is an http.Handler that renders a template for every request.
 //
 // It wires the incoming HTTP request through the JaWS rendering pipeline by
-// creating a Request, instantiating the configured Template and streaming the
-// resulting HTML to the caller. Applications typically construct handlers with
-// Handler.
+// creating a Request, instantiating the configured page template and streaming
+// the resulting HTML to the caller. Applications typically construct handlers
+// with Handler.
 type uiHandler struct {
 	*jaws.Jaws
+	Template pageTemplate
+}
+
+type pageTemplate struct {
 	Template
 }
 
+func (tmpl pageTemplate) JawsRender(elem *jaws.Element, w io.Writer, params []any) (err error) {
+	err = tmpl.Template.render(elem, w, params, false)
+	return
+}
+
+func (pageTemplate) JawsUpdate(*jaws.Element) {}
+
 func (h uiHandler) ServeHTTP(w http.ResponseWriter, r *http.Request) {
 	_ = h.Log(h.NewRequest(r).NewElement(h.Template).JawsRender(w, nil))
 }
 
 // Handler returns an http.Handler that renders the named template.
 //
 // The returned handler can be registered directly with a router. Each request
-// results in the template being looked up through the configured Template
-// lookupers and rendered with dot as the template data.
+// results in the template being looked up through the configured template
+// lookupers and rendered directly with dot as the template data.
 func Handler(jw *jaws.Jaws, name string, dot any) http.Handler {
-	return uiHandler{Jaws: jw, Template: Template{Name: name, Dot: dot}}
+	return uiHandler{Jaws: jw, Template: pageTemplate{Template: Template{Name: name, Dot: dot}}}
 }

lib/ui/template.go

@@ -1,14 +1,11 @@
 package ui
 
 import (
-	"bytes"
 	"fmt"
 	"html/template"
 	"io"
 	"strings"
-	"text/template/parse"
 
-	"github.com/linkdata/deadlock"
 	"github.com/linkdata/jaws"
 	"github.com/linkdata/jaws/lib/tag"
 )
@@ -17,8 +14,10 @@ import (
 //
 // The Name field identifies the template to execute and Dot contains the data
 // that will be exposed to the template through the [With] structure constructed
-// during rendering. Additional tag bindings and event handlers can be supplied
-// at render time through the [RequestWriter.Template] helper.
+// during rendering. Templates are rendered inside a generated wrapper element
+// that receives the JaWS ID and any HTML attributes supplied at render time
+// through the [RequestWriter.Template] helper. The referenced template must be
+// a partial template, not a full HTML document.
 type Template struct {
 	Name string // Template name to be looked up using Jaws.LookupTemplate.
 	Dot  any    // Dot value to place in With.
@@ -29,133 +28,98 @@ var _ jaws.ClickHandler = Template{}       // statically ensure interface is def
 var _ jaws.ContextMenuHandler = Template{} // statically ensure interface is defined
 var _ jaws.InputHandler = Template{}       // statically ensure interface is defined
 
+type templateRenderMode uint8
+
+const (
+	templateRenderWrapped templateRenderMode = iota
+	templateRenderDirect
+)
+
 // String returns a debug representation of t.
 func (tmpl Template) String() string {
 	return fmt.Sprintf("{%q, %s}", tmpl.Name, tag.TagString(tmpl.Dot))
 }
 
-func findJidOrJsOrHTMLNode(node parse.Node) (found bool) {
-	isJidOrJs := func(s string) bool {
-		return (s == "Jid") || (s == "JsFunc") || (s == "JsVar")
+func (tmpl Template) lookup(elem *jaws.Element) (lookedUp *template.Template, err error) {
+	err = errMissingTemplate(tmpl.Name)
+	if lookedUp = elem.Request.Jaws.LookupTemplate(tmpl.Name); lookedUp != nil {
+		err = nil
 	}
-	switch node := node.(type) {
-	case *parse.TextNode:
-		if node != nil {
-			found = found || bytes.Contains(node.Text, []byte("</html>"))
-		}
-	case *parse.ListNode:
-		if node != nil {
-			for _, n := range node.Nodes {
-				found = found || findJidOrJsOrHTMLNode(n)
-			}
-		}
-	case *parse.ActionNode:
-		if node != nil {
-			found = findJidOrJsOrHTMLNode(node.Pipe)
-		}
-	case *parse.WithNode:
-		if node != nil {
-			found = findJidOrJsOrHTMLNode(&node.BranchNode)
-		}
-	case *parse.BranchNode:
-		if node != nil {
-			found = findJidOrJsOrHTMLNode(node.Pipe)
-			found = found || findJidOrJsOrHTMLNode(node.List)
-			found = found || findJidOrJsOrHTMLNode(node.ElseList)
-		}
-	case *parse.IfNode:
-		if node != nil {
-			found = findJidOrJsOrHTMLNode(node.Pipe)
-			found = found || findJidOrJsOrHTMLNode(node.List)
-			found = found || findJidOrJsOrHTMLNode(node.ElseList)
-		}
-	case *parse.RangeNode:
-		if node != nil {
-			found = findJidOrJsOrHTMLNode(node.Pipe)
-			found = found || findJidOrJsOrHTMLNode(node.List)
-			found = found || findJidOrJsOrHTMLNode(node.ElseList)
-		}
-	case *parse.TemplateNode:
-		if node != nil {
-			found = findJidOrJsOrHTMLNode(node.Pipe)
-		}
-	case *parse.PipeNode:
-		if node != nil {
-			for _, n := range node.Cmds {
-				found = found || findJidOrJsOrHTMLNode(n)
-			}
-		}
-	case *parse.CommandNode:
-		if node != nil {
-			for _, n := range node.Args {
-				found = found || findJidOrJsOrHTMLNode(n)
-			}
-		}
-	case *parse.VariableNode:
-		if node != nil {
-			for _, s := range node.Ident {
-				found = found || isJidOrJs(s)
-			}
-		}
-	case *parse.FieldNode:
-		if node != nil {
-			for _, s := range node.Ident {
-				found = found || isJidOrJs(s)
-			}
-		}
-	case *parse.IdentifierNode:
-		if node != nil {
-			found = found || isJidOrJs(node.Ident)
-		}
-	case *parse.ChainNode:
-		if node != nil {
-			found = findJidOrJsOrHTMLNode(node.Node)
-			for _, s := range node.Field {
-				found = found || isJidOrJs(s)
-			}
+	return
+}
+
+func (tmpl Template) auth(elem *jaws.Element) (auth jaws.Auth) {
+	auth = jaws.DefaultAuth{}
+	if f := elem.Request.Jaws.MakeAuth; f != nil {
+		auth = f(elem.Request)
+	}
+	return
+}
+
+func (tmpl Template) execute(elem *jaws.Element, w io.Writer, lookedUp *template.Template) (err error) {
+	err = lookedUp.Execute(w, With{
+		Element:       elem,
+		RequestWriter: RequestWriter{Request: elem.Request, Writer: w},
+		Dot:           tmpl.Dot,
+		Auth:          tmpl.auth(elem),
+	})
+	return
+}
+
+func writeTemplateWrapperStart(elem *jaws.Element, w io.Writer, attrs []string) (err error) {
+	b := elem.Jid().AppendStartTagAttr(nil, "div")
+	b = append(b, " data-jawstemplate"...)
+	for _, attr := range attrs {
+		if attr != "" {
+			b = append(b, ' ')
+			b = append(b, attr...)
 		}
 	}
+	b = append(b, '>')
+	_, err = w.Write(b)
 	return
 }
 
-// JawsRender renders t through the request's configured template lookupers.
-func (tmpl Template) JawsRender(elem *jaws.Element, w io.Writer, params []any) (err error) {
+func (tmpl Template) render(elem *jaws.Element, w io.Writer, params []any, wrapped bool) (err error) {
 	var expandedTags []any
 	if expandedTags, err = tag.TagExpand(elem.Request, tmpl.Dot); err == nil {
 		elem.Request.TagExpanded(elem, expandedTags)
 		tags, handlers, attrs := jaws.ParseParams(params)
 		elem.Tag(tags...)
 		elem.AddHandlers(handlers...)
-		attrstr := template.HTMLAttr(strings.Join(attrs, " ")) // #nosec G203
-		var auth jaws.Auth
-		auth = jaws.DefaultAuth{}
-		if f := elem.Request.Jaws.MakeAuth; f != nil {
-			auth = f(elem.Request)
-		}
-		err = errMissingTemplate(tmpl.Name)
-		if lookedUp := elem.Request.Jaws.LookupTemplate(tmpl.Name); lookedUp != nil {
-			err = lookedUp.Execute(w, With{
-				Element:       elem,
-				RequestWriter: RequestWriter{Request: elem.Request, Writer: w},
-				Dot:           tmpl.Dot,
-				Attrs:         attrstr,
-				Auth:          auth,
-			})
-			if deadlock.Debug && elem.Jaws.Logger != nil {
-				if !findJidOrJsOrHTMLNode(lookedUp.Tree.Root) {
-					elem.Jaws.Logger.Warn("jaws: template has no Jid reference", "template", tmpl.Name)
+		var lookedUp *template.Template
+		if lookedUp, err = tmpl.lookup(elem); err == nil {
+			if wrapped {
+				err = writeTemplateWrapperStart(elem, w, attrs)
+			}
+			if err == nil {
+				if err = tmpl.execute(elem, w, lookedUp); err == nil {
+					if wrapped {
+						_, err = io.WriteString(w, "</div>")
+					}
 				}
 			}
 		}
 	}
 	return
 }
 
-// JawsUpdate delegates updates to t.Dot when it implements [jaws.Updater].
+// JawsRender renders t through the request's configured template lookupers.
+func (tmpl Template) JawsRender(elem *jaws.Element, w io.Writer, params []any) (err error) {
+	err = tmpl.render(elem, w, params, true)
+	return
+}
+
+// JawsUpdate re-renders t into the template wrapper.
 func (tmpl Template) JawsUpdate(elem *jaws.Element) {
-	if dot, ok := tmpl.Dot.(jaws.Updater); ok {
-		dot.JawsUpdate(elem)
+	lookedUp, err := tmpl.lookup(elem)
+	if err == nil {
+		var sb strings.Builder
+		if err = tmpl.execute(elem, &sb, lookedUp); err == nil {
+			elem.SetInner(template.HTML(sb.String())) // #nosec G203
+		}
 	}
+	elem.Request.MustLog(err)
 }
 
 // JawsClick delegates click events to t.Dot when it implements [jaws.ClickHandler].
@@ -197,7 +161,9 @@ func NewTemplate(name string, dot any) Template {
 // Template renders the given template using [With] as data.
 //
 // The Dot field in [With] is set to dot, and name is resolved to a
-// [template.Template] using [jaws.Jaws.LookupTemplate].
+// [template.Template] using [jaws.Jaws.LookupTemplate]. Template output is
+// wrapped in a generated div that owns the JaWS ID and any HTML attrs passed in
+// params. The template must be a partial, not a full HTML document.
 func (rw RequestWriter) Template(name string, dot any, params ...any) error {
 	return rw.UI(NewTemplate(name, dot), params...)
 }