From 632730c33a970c1952678b64fe05de510cd83956 Mon Sep 17 00:00:00 2001
From: Josh Bruce <josh@8fold.pro>
Date: Thu, 15 Oct 2026 12:21:23 -0400
Subject: [PATCH] Clarify form wrapper targets and Fieldset warning
 responsibilities

Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
---
 src/Forms/EmailInput.php | 3 +++
 src/Forms/Fieldset.php   | 7 +++++++
 src/Forms/Password.php   | 3 +++
 src/Forms/Select.php     | 4 ++++
 src/Forms/TextArea.php   | 3 +++
 src/Forms/TextInput.php  | 3 +++
 6 files changed, 23 insertions(+)

diff --git a/src/Forms/EmailInput.php b/src/Forms/EmailInput.php
index b4a8bd6..b501f6e 100644
--- a/src/Forms/EmailInput.php
+++ b/src/Forms/EmailInput.php
@@ -56,6 +56,9 @@ public function id(string $id): self
         return $this;
     }
 
+    /**
+     * Sets properties on this component's outermost div, not the input.
+     */
     public function wrapperProps(string ...$properties): self
     {
         $this->wrapperProperties = array_values($properties);
diff --git a/src/Forms/Fieldset.php b/src/Forms/Fieldset.php
index ffda5fe..aaf3238 100644
--- a/src/Forms/Fieldset.php
+++ b/src/Forms/Fieldset.php
@@ -33,6 +33,10 @@ class Fieldset implements Stringable
      */
     private array $elements = [];
 
+    /**
+     * Renders one group warning; callers must wire aria-invalid and
+     * aria-describedby on member controls (see Select's radio/checkbox modes).
+     */
     public static function create(
         string|Stringable $label,
         string|Stringable $name,
@@ -54,6 +58,9 @@ public function elements(string|Stringable ...$elements): self
         return $this;
     }
 
+    /**
+     * Sets properties on this component's outermost element: the fieldset.
+     */
     public function wrapperProps(string ...$properties): self
     {
         $this->wrapperProperties = $properties;
diff --git a/src/Forms/Password.php b/src/Forms/Password.php
index ad7e036..fe3f984 100644
--- a/src/Forms/Password.php
+++ b/src/Forms/Password.php
@@ -58,6 +58,9 @@ public function id(string $id): self
         return $this;
     }
 
+    /**
+     * Sets properties on this component's outermost div, not the input.
+     */
     public function wrapperProps(string ...$properties): self
     {
         $this->wrapperProperties = array_values($properties);
diff --git a/src/Forms/Select.php b/src/Forms/Select.php
index aa55909..fdba016 100644
--- a/src/Forms/Select.php
+++ b/src/Forms/Select.php
@@ -72,6 +72,10 @@ public function id(string $id): self
         return $this;
     }
 
+    /**
+     * Sets properties on the outermost div in dropdown/multiple modes,
+     * or the fieldset in radio/checkbox modes, not on member controls.
+     */
     public function wrapperProps(string ...$properties): self
     {
         $this->wrapperProperties = array_values($properties);
diff --git a/src/Forms/TextArea.php b/src/Forms/TextArea.php
index 3960048..a2d69e3 100644
--- a/src/Forms/TextArea.php
+++ b/src/Forms/TextArea.php
@@ -59,6 +59,9 @@ public function id(string $id): self
         return $this;
     }
 
+    /**
+     * Sets properties on this component's outermost div, not the textarea.
+     */
     public function wrapperProps(string ...$properties): self
     {
         $this->wrapperProperties = array_values($properties);
diff --git a/src/Forms/TextInput.php b/src/Forms/TextInput.php
index 73863d9..1d81ab0 100644
--- a/src/Forms/TextInput.php
+++ b/src/Forms/TextInput.php
@@ -56,6 +56,9 @@ public function id(string $id): self
         return $this;
     }
 
+    /**
+     * Sets properties on this component's outermost div, not the input.
+     */
     public function wrapperProps(string ...$properties): self
     {
         $this->wrapperProperties = array_values($properties);