From 87ebb7958d70c28bcae91ccdee7aefa498a4f5bf Mon Sep 17 00:00:00 2001
From: Virgil <virgil@lethean.io>
Date: Sat, 4 Apr 2026 01:11:58 +0000
Subject: [PATCH] feat(html): add title helper

Co-Authored-By: Virgil <virgil@lethean.io>
---
 docs/architecture.md |  1 +
 docs/index.md        |  4 ++--
 go.sum               |  4 ++++
 node.go              |  9 +++++++++
 node_test.go         | 20 ++++++++++++++++++++
 5 files changed, 36 insertions(+), 2 deletions(-)

diff --git a/docs/architecture.md b/docs/architecture.md
index 6e0ef8d..ed7551c 100644
--- a/docs/architecture.md
+++ b/docs/architecture.md
@@ -53,6 +53,7 @@ Accessibility-oriented helpers are also provided for common attribute patterns:
 - `Lang(node, locale)`
 - `Dir(node, direction)`
 - `Alt(node, text)`
+- `Title(node, text)`
 - `Class(node, classes...)`
 - `AriaHidden(node, hidden)`
 - `AriaExpanded(node, expanded)`
diff --git a/docs/index.md b/docs/index.md
index d43a598..9bb7d9c 100644
--- a/docs/index.md
+++ b/docs/index.md
@@ -39,7 +39,7 @@ This builds a Header-Content-Footer layout with semantic HTML elements (`<header
 
 | 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`, `AriaAtomic`, `AriaDescription`, `AriaDetails`, `AriaErrorMessage`, `AriaRoleDescription`, `AriaDisabled`, `AriaModal`, `AriaChecked`, `AriaInvalid`, `AriaRequired`, `AriaPressed`, `AriaSelected`, `Hidden`, `Disabled`, `Checked`, `Required`, `ReadOnly`, `Selected`, `TabIndex`, and `AutoFocus` helpers |
+| `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`, `Title`, `AriaBusy`, `AriaLive`, `AriaAtomic`, `AriaDescription`, `AriaDetails`, `AriaErrorMessage`, `AriaRoleDescription`, `AriaDisabled`, `AriaModal`, `AriaChecked`, `AriaInvalid`, `AriaRequired`, `AriaPressed`, `AriaSelected`, `Hidden`, `Disabled`, `Checked`, `Required`, `ReadOnly`, `Selected`, `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 |
@@ -52,7 +52,7 @@ This builds a Header-Content-Footer layout with semantic HTML elements (`<header
 
 ## 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()`, `AriaAtomic()`, `AriaDescription()`, `AriaDetails()`, `AriaErrorMessage()`, `AriaRoleDescription()`, `AriaHidden()`, `Hidden()`, `AriaDisabled()`, `AriaModal()`, `AriaChecked()`, `AriaInvalid()`, `AriaRequired()`, `AriaReadOnly()`, `Disabled()`, `Checked()`, `Required()`, `ReadOnly()`, `Selected()`, and `TabIndex()`.
+**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()`, `AriaAtomic()`, `AriaDescription()`, `AriaDetails()`, `AriaErrorMessage()`, `AriaRoleDescription()`, `AriaHidden()`, `Hidden()`, `AriaDisabled()`, `AriaModal()`, `AriaChecked()`, `AriaInvalid()`, `AriaRequired()`, `AriaReadOnly()`, `Disabled()`, `Checked()`, `Required()`, `ReadOnly()`, `Selected()`, `TabIndex()`, and the common HTML attribute helpers `Alt()`, `AltText()`, `Title()`, `ID()`, `For()`, `Class()`, and `AutoFocus()`.
 
 **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`.
 
diff --git a/go.sum b/go.sum
index 5a10c39..b1e21b6 100644
--- a/go.sum
+++ b/go.sum
@@ -14,8 +14,12 @@ github.com/pmezard/go-difflib v1.0.1-0.20181226105442-5d4384ee4fb2/go.mod h1:iKH
 github.com/rogpeppe/go-internal v1.9.0/go.mod h1:WtVeX8xhTBvf0smdhujwtBcq4Qrzq/fJaraNFVN+nFs=
 github.com/rogpeppe/go-internal v1.14.1 h1:UQB4HGPB6osV0SQTLymcB4TgvyWu6ZyliaW0tI/otEQ=
 github.com/rogpeppe/go-internal v1.14.1/go.mod h1:MaRKkUm5W0goXpeCfT7UZI6fk/L7L7so1lCWt35ZSgc=
+github.com/stretchr/objx v0.5.2/go.mod h1:FRsXN1f5AsAjCGJKqEizvkpNtU+EGNCLh3NxZ/8L+MA=
 github.com/stretchr/testify v1.11.1 h1:7s2iGBzp5EwR7/aIZr8ao5+dra3wiQyKjjFuvgVKu7U=
 github.com/stretchr/testify v1.11.1/go.mod h1:wZwfW3scLgRK+23gO65QZefKpKQRnfz6sD981Nm4B6U=
+golang.org/x/mod v0.21.0/go.mod h1:6SkKJ3Xj0I0BrPOZoBy3bdMptDDU9oJrpohJ3eWZ1fY=
+golang.org/x/sys v0.26.0/go.mod h1:/VUhepiaJMQUp4+oa/7Zr1D23ma6VTLIYjOOTFZPUcA=
+golang.org/x/tools v0.26.0/go.mod h1:TPVVj70c7JJ3WCazhD8OdXcZg/og+b9+tH/KxylGwH0=
 gopkg.in/check.v1 v0.0.0-20161208181325-20d25e280405/go.mod h1:Co6ibVJAznAaIkqp8huTwlJQCZ016jof/cbN4VW5Yz0=
 gopkg.in/check.v1 v1.0.0-20201130134442-10cb98267c6c h1:Hei/4ADfdWqJk1ZMxUNpqntNwaWcugrBjAiHlqqRiVk=
 gopkg.in/check.v1 v1.0.0-20201130134442-10cb98267c6c/go.mod h1:JHkPIbrfpd72SG/EVd6muEfDQjcINNoR0C8j2r3qZ4Q=
diff --git a/node.go b/node.go
index 9f32fa0..36d3e0e 100644
--- a/node.go
+++ b/node.go
@@ -397,6 +397,15 @@ func Alt(n Node, text string) Node {
 	return n
 }
 
+// node.go: Title sets the title attribute on an element node.
+// Example: Title(El("abbr"), "World Wide Web").
+func Title(n Node, text string) Node {
+	if value := trimmedNonEmpty(text); value != "" {
+		return Attr(n, "title", value)
+	}
+	return n
+}
+
 // node.go: AltText is a compatibility alias for Alt.
 // Example: AltText(El("img"), "Product screenshot").
 // Prefer Alt for new call sites so the canonical image helper stays predictable.
diff --git a/node_test.go b/node_test.go
index bf87cf0..0f104c4 100644
--- a/node_test.go
+++ b/node_test.go
@@ -643,6 +643,26 @@ func TestAltHelper_IgnoresWhitespace(t *testing.T) {
 	}
 }
 
+func TestTitleHelper(t *testing.T) {
+	ctx := NewContext()
+	node := Title(El("abbr", Raw("HTML")), "HyperText Markup Language")
+	got := node.Render(ctx)
+	want := `<abbr title="HyperText Markup Language">HTML</abbr>`
+	if got != want {
+		t.Errorf("Title() = %q, want %q", got, want)
+	}
+}
+
+func TestTitleHelper_IgnoresWhitespace(t *testing.T) {
+	ctx := NewContext()
+	node := Title(El("abbr", Raw("HTML")), " \t ")
+	got := node.Render(ctx)
+	want := `<abbr>HTML</abbr>`
+	if got != want {
+		t.Errorf("Title() with whitespace = %q, want %q", got, want)
+	}
+}
+
 func TestAltTextHelper(t *testing.T) {
 	ctx := NewContext()
 	node := AltText(El("img"), `A "quoted" caption`)