From 1d114721365517fcacacf09e40c79588121e3060 Mon Sep 17 00:00:00 2001
From: Virgil <virgil@lethean.io>
Date: Tue, 31 Mar 2026 20:51:01 +0000
Subject: [PATCH] feat(html): add role accessibility helper

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

diff --git a/docs/architecture.md b/docs/architecture.md
index 2fd2751..169dc36 100644
--- a/docs/architecture.md
+++ b/docs/architecture.md
@@ -27,6 +27,7 @@ All concrete node types are unexported structs with exported constructor functio
 | `AltText(Node, text)` | Convenience helper that sets `alt` on an element node. |
 | `TabIndex(Node, index)` | Convenience helper that sets `tabindex` on an element node. |
 | `AutoFocus(Node)` | Convenience helper that sets `autofocus` on an element node. |
+| `Role(Node, role)` | Convenience helper that sets `role` on an element node. |
 | `Text(key, ...any)` | Translated text via the active context translator. Server builds fall back to global `go-i18n`; JS builds fall back to the key. Output is always HTML-escaped. |
 | `Raw(content)` | Unescaped trusted content. Explicit escape hatch. |
 | `If(cond, Node)` | Renders the child only when the condition function returns true. |
diff --git a/docs/index.md b/docs/index.md
index 24e8a67..2d3385f 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`, `AltText`, `TabIndex`, and `AutoFocus` helpers |
+| `node.go` | `Node` interface and all node types: `El`, `Text`, `Raw`, `If`, `Unless`, `Each`, `EachSeq`, `Switch`, `Entitled`, plus `AriaLabel`, `AltText`, `TabIndex`, `AutoFocus`, and `Role` helpers |
 | `layout.go` | HLCRF compositor with semantic HTML elements and ARIA roles |
 | `responsive.go` | Multi-variant breakpoint wrapper (`data-variant` containers) and CSS selector helper |
 | `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, control-flow constructors (`If`, `Unless`, `Each`, `Switch`, `Entitled`), and accessibility helpers (`AriaLabel`, `AltText`, `TabIndex`, `AutoFocus`).
+**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, control-flow constructors (`If`, `Unless`, `Each`, `Switch`, `Entitled`), and accessibility helpers (`AriaLabel`, `AltText`, `TabIndex`, `AutoFocus`, `Role`).
 
 **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/node.go b/node.go
index 9fd9aed..6b2f720 100644
--- a/node.go
+++ b/node.go
@@ -140,6 +140,12 @@ func AutoFocus(n Node) Node {
 	return Attr(n, "autofocus", "autofocus")
 }
 
+// Role sets a role attribute on an element node.
+// Usage example: Role(El("nav", Text("links")), "navigation")
+func Role(n Node, role string) Node {
+	return Attr(n, "role", role)
+}
+
 func (n *elNode) Render(ctx *Context) string {
 	if n == nil {
 		return ""
diff --git a/node_test.go b/node_test.go
index e527c4e..a26cdcd 100644
--- a/node_test.go
+++ b/node_test.go
@@ -240,6 +240,15 @@ func TestAutoFocus_Good(t *testing.T) {
 	}
 }
 
+func TestRole_Good(t *testing.T) {
+	node := Role(El("nav", Raw("links")), "navigation")
+	got := node.Render(NewContext())
+	want := `<nav role="navigation">links</nav>`
+	if got != want {
+		t.Errorf("Role() = %q, want %q", got, want)
+	}
+}
+
 func TestElNode_MultipleAttrs_Good(t *testing.T) {
 	ctx := NewContext()
 	node := Attr(Attr(El("a", Raw("link")), "href", "/home"), "class", "nav")