From 24565df459e5c661ae923372df3bbe7eb790d4bc Mon Sep 17 00:00:00 2001
From: Virgil <virgil@lethean.io>
Date: Fri, 3 Apr 2026 19:44:46 +0000
Subject: [PATCH] docs(html): add AX usage examples

Co-Authored-By: Virgil <virgil@lethean.io>
---
 context.go |  6 +++++-
 layout.go  | 10 ++++++++++
 2 files changed, 15 insertions(+), 1 deletion(-)

diff --git a/context.go b/context.go
index 16242f4..ab15973 100644
--- a/context.go
+++ b/context.go
@@ -1,7 +1,11 @@
 package html
 
 // context.go: Translator provides Text() lookups for a rendering context.
-// Example: a locale-aware service can satisfy T(key, args...).
+// Example: type service struct{}
+//
+//	func (service) T(key string, args ...any) string { return key }
+//
+//	ctx := NewContextWithService(service{}, "en-GB")
 type Translator interface {
 	T(key string, args ...any) string
 }
diff --git a/layout.go b/layout.go
index 6d6e25c..452f71e 100644
--- a/layout.go
+++ b/layout.go
@@ -13,6 +13,7 @@ var _ Node = (*Layout)(nil)
 
 // ErrInvalidLayoutVariant reports that a layout variant string contains at
 // least one unrecognised slot character.
+// Example: errors.Is(ValidateLayoutVariant("HXC"), ErrInvalidLayoutVariant).
 var ErrInvalidLayoutVariant = errors.New("html: invalid layout variant")
 
 // slotMeta holds the semantic HTML mapping for each HLCRF slot.
@@ -215,6 +216,13 @@ func (l *Layout) Render(ctx *Context) string {
 	return b.String()
 }
 
+// LayoutVariantError describes the invalid characters found in a layout
+// variant string.
+// Example: var variantErr *LayoutVariantError
+//
+//	if errors.As(err, &variantErr) {
+//		_ = variantErr.InvalidSlots()
+//	}
 type LayoutVariantError struct {
 	variant          string
 	invalidSlots     []byte
@@ -258,6 +266,7 @@ func (e *LayoutVariantError) Unwrap() error {
 
 // InvalidSlots returns a copy of the invalid slot characters that were present
 // in the original variant string.
+// Example: string(variantErr.InvalidSlots()) // "1X?"
 func (e *LayoutVariantError) InvalidSlots() []byte {
 	if e == nil || len(e.invalidSlots) == 0 {
 		return nil
@@ -267,6 +276,7 @@ func (e *LayoutVariantError) InvalidSlots() []byte {
 
 // InvalidPositions returns a copy of the 1-based positions of the invalid slot
 // characters in the original variant string.
+// Example: variantErr.InvalidPositions() // []int{2, 3, 4}
 func (e *LayoutVariantError) InvalidPositions() []int {
 	if e == nil || len(e.invalidPositions) == 0 {
 		return nil