From a925142e4e0335cabacbf722722765ebaddaf5e8 Mon Sep 17 00:00:00 2001
From: Virgil <virgil@lethean.io>
Date: Fri, 3 Apr 2026 18:18:30 +0000
Subject: [PATCH] feat(html): add aria-controls helper

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

diff --git a/docs/architecture.md b/docs/architecture.md
index 201b430..edea62b 100644
--- a/docs/architecture.md
+++ b/docs/architecture.md
@@ -37,6 +37,7 @@ Accessibility-oriented helpers are also provided for common attribute patterns:
 - `AriaLabel(node, label)`
 - `AriaDescribedBy(node, ids...)`
 - `AriaLabelledBy(node, ids...)`
+- `AriaControls(node, ids...)`
 - `Role(node, role)`
 - `Lang(node, locale)`
 - `Dir(node, direction)`
diff --git a/docs/index.md b/docs/index.md
index 989e0e7..3ffc138 100644
--- a/docs/index.md
+++ b/docs/index.md
@@ -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`).
+**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 helpers such as `AriaLabel()`, `AriaControls()`, `AriaHidden()`, 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`.
 
diff --git a/node.go b/node.go
index 64534bc..31a9047 100644
--- a/node.go
+++ b/node.go
@@ -197,6 +197,13 @@ func AriaLabelledBy(n Node, ids ...string) Node {
 	return Attr(n, "aria-labelledby", strings.Join(ids, " "))
 }
 
+// node.go: AriaControls sets the aria-controls attribute on an element node.
+// Example: AriaControls(El("button"), "menu-panel").
+// Multiple IDs are joined with spaces, matching the HTML attribute format.
+func AriaControls(n Node, ids ...string) Node {
+	return Attr(n, "aria-controls", strings.Join(ids, " "))
+}
+
 // node.go: Role sets the role attribute on an element node.
 // Example: Role(El("aside"), "complementary").
 func Role(n Node, role string) Node {
diff --git a/node_test.go b/node_test.go
index 3d2296c..df28f39 100644
--- a/node_test.go
+++ b/node_test.go
@@ -275,6 +275,16 @@ func TestAriaLabelledByHelper(t *testing.T) {
 	}
 }
 
+func TestAriaControlsHelper(t *testing.T) {
+	ctx := NewContext()
+	node := AriaControls(El("button", Raw("menu")), "menu-panel", "shortcut-hints")
+	got := node.Render(ctx)
+	want := `<button aria-controls="menu-panel shortcut-hints">menu</button>`
+	if got != want {
+		t.Errorf("AriaControls() = %q, want %q", got, want)
+	}
+}
+
 func TestRoleHelper(t *testing.T) {
 	ctx := NewContext()
 	node := Role(El("button", Raw("menu")), "navigation")