From 5b69aec575cbdd874546f4e25de84f3e5bc104b3 Mon Sep 17 00:00:00 2001
From: Virgil <virgil@lethean.io>
Date: Sat, 4 Apr 2026 00:13:10 +0000
Subject: [PATCH] feat(html): add aria details helpers

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

diff --git a/docs/architecture.md b/docs/architecture.md
index 923b24c..e28d710 100644
--- a/docs/architecture.md
+++ b/docs/architecture.md
@@ -45,6 +45,8 @@ Accessibility-oriented helpers are also provided for common attribute patterns:
 - `AriaBusy(node, busy)`
 - `AriaLive(node, live)`
 - `AriaDescription(node, description)`
+- `AriaDetails(node, ids...)`
+- `AriaErrorMessage(node, ids...)`
 - `AriaRoleDescription(node, description)`
 - `Role(node, role)`
 - `Lang(node, locale)`
diff --git a/docs/index.md b/docs/index.md
index ca8693a..d7395dd 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`, `AriaDescription`, `AriaRoleDescription`, `AriaDisabled`, `AriaModal`, `AriaChecked`, `AriaInvalid`, `AriaRequired`, `AriaPressed`, `AriaSelected`, `Hidden`, `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`, `AriaBusy`, `AriaLive`, `AriaDescription`, `AriaDetails`, `AriaErrorMessage`, `AriaRoleDescription`, `AriaDisabled`, `AriaModal`, `AriaChecked`, `AriaInvalid`, `AriaRequired`, `AriaPressed`, `AriaSelected`, `Hidden`, `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()`, `AriaDescription()`, `AriaRoleDescription()`, `AriaHidden()`, `Hidden()`, `AriaDisabled()`, `AriaModal()`, `AriaChecked()`, `AriaInvalid()`, `AriaRequired()`, `AriaReadOnly()`, 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()`, `AriaDescription()`, `AriaDetails()`, `AriaErrorMessage()`, `AriaRoleDescription()`, `AriaHidden()`, `Hidden()`, `AriaDisabled()`, `AriaModal()`, `AriaChecked()`, `AriaInvalid()`, `AriaRequired()`, `AriaReadOnly()`, 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 c38f88b..27be9af 100644
--- a/node.go
+++ b/node.go
@@ -299,6 +299,26 @@ func AriaDescription(n Node, description string) Node {
 	return n
 }
 
+// node.go: AriaDetails sets the aria-details attribute on an element node.
+// Example: AriaDetails(El("input"), "field-help").
+// Multiple IDs are joined with spaces, matching the HTML attribute format.
+func AriaDetails(n Node, ids ...string) Node {
+	if value := joinNonEmpty(ids...); value != "" {
+		return Attr(n, "aria-details", value)
+	}
+	return n
+}
+
+// node.go: AriaErrorMessage sets the aria-errormessage attribute on an element node.
+// Example: AriaErrorMessage(El("input"), "field-error").
+// Multiple IDs are joined with spaces, matching the HTML attribute format.
+func AriaErrorMessage(n Node, ids ...string) Node {
+	if value := joinNonEmpty(ids...); value != "" {
+		return Attr(n, "aria-errormessage", value)
+	}
+	return n
+}
+
 // node.go: AriaRoleDescription sets the aria-roledescription attribute on an
 // element node.
 // Example: AriaRoleDescription(El("section"), "carousel").
diff --git a/node_test.go b/node_test.go
index 6bc1748..c8c3314 100644
--- a/node_test.go
+++ b/node_test.go
@@ -494,6 +494,46 @@ func TestAriaDescriptionHelper_IgnoresWhitespace(t *testing.T) {
 	}
 }
 
+func TestAriaDetailsHelper(t *testing.T) {
+	ctx := NewContext()
+	node := AriaDetails(El("input"), "field-help", "usage-help")
+	got := node.Render(ctx)
+	want := `<input aria-details="field-help usage-help">`
+	if got != want {
+		t.Errorf("AriaDetails() = %q, want %q", got, want)
+	}
+}
+
+func TestAriaDetailsHelper_IgnoresWhitespaceIDs(t *testing.T) {
+	ctx := NewContext()
+	node := AriaDetails(El("input"), "", "field-help", " ", "usage-help")
+	got := node.Render(ctx)
+	want := `<input aria-details="field-help usage-help">`
+	if got != want {
+		t.Errorf("AriaDetails() with whitespace IDs = %q, want %q", got, want)
+	}
+}
+
+func TestAriaErrorMessageHelper(t *testing.T) {
+	ctx := NewContext()
+	node := AriaErrorMessage(El("input"), "field-error")
+	got := node.Render(ctx)
+	want := `<input aria-errormessage="field-error">`
+	if got != want {
+		t.Errorf("AriaErrorMessage() = %q, want %q", got, want)
+	}
+}
+
+func TestAriaErrorMessageHelper_IgnoresWhitespaceIDs(t *testing.T) {
+	ctx := NewContext()
+	node := AriaErrorMessage(El("input"), " ", "field-error", "")
+	got := node.Render(ctx)
+	want := `<input aria-errormessage="field-error">`
+	if got != want {
+		t.Errorf("AriaErrorMessage() with whitespace IDs = %q, want %q", got, want)
+	}
+}
+
 func TestAriaRoleDescriptionHelper(t *testing.T) {
 	ctx := NewContext()
 	node := AriaRoleDescription(El("section", Raw("content")), "carousel")