From 7146991032ff5588dc804af089182339297562d5 Mon Sep 17 00:00:00 2001
From: Josh Bruce <josh@8fold.pro>
Date: Wed, 14 Oct 2026 17:16:55 -0400
Subject: [PATCH 1/9] BC: Wrap TextInput, add wrapper props, id, and content

---
 src/Forms/TextInput.php       | 80 ++++++++++++++++++++---------------
 tests/Forms/TextInputTest.php | 26 ++++++++++--
 2 files changed, 69 insertions(+), 37 deletions(-)

diff --git a/src/Forms/TextInput.php b/src/Forms/TextInput.php
index d533770..e312851 100644
--- a/src/Forms/TextInput.php
+++ b/src/Forms/TextInput.php
@@ -10,11 +10,12 @@
 
 class TextInput implements Stringable
 {
-    // phpcs:disable
-    private string $warningId {
-        get => $this->name . '-warning';
-    }
-    // phpcs:enable
+    private string $id;
+
+    /**
+     * @var string[]
+     */
+    private array $wrapperProperties = [];
 
     /**
      * @var string[]
@@ -26,6 +27,11 @@ class TextInput implements Stringable
      */
     private array $inputProperties = [];
 
+    /**
+     * @var array<string|Stringable>
+     */
+    private array $content = [];
+
     public static function create(
         string|Stringable $label,
         string|Stringable $name,
@@ -41,6 +47,19 @@ final private function __construct(
         private readonly string $value,
         private readonly string|PropertyInterface $warningMessage = ''
     ) {
+        $this->id = $name;
+    }
+
+    public function id(string $id): self
+    {
+        $this->id = $id;
+        return $this;
+    }
+
+    public function wrapperProps(string ...$properties): self
+    {
+        $this->wrapperProperties = $properties;
+        return $this;
     }
 
     public function labelProps(string ...$properties): self
@@ -55,49 +74,42 @@ public function inputProps(string ...$properties): self
         return $this;
     }
 
-    private function warningMessage(): string|PropertyInterface
+    public function content(string|Stringable ...$content): self
     {
-        if ($this->warningMessage === '') {
-            return '';
-        }
-
-        if (is_string($this->warningMessage)) {
-            return Element::p($this->warningMessage)->props(
-                'id ' . $this->warningId
-            );
-        }
-
-        return $this->warningMessage->prop('id ' . $this->warningId);
+        $this->content = $content;
+        return $this;
     }
 
     public function __toString(): string
     {
-        $elements = [];
-        $elements[] = Element::label($this->label)->props(
-            'for ' . $this->name,
-            ...$this->labelProperties
-        );
-
         $input = Element::input()->omitEndTag()->props(
             'type text',
-            'id ' . $this->name,
+            'id ' . $this->id,
             'name ' . $this->name,
             'value ' . $this->value,
             ...$this->inputProperties
         );
 
-        $warningMessage = self::warningMessage();
-        $hasWarningMessage = ($warningMessage !== '');
-        if ($hasWarningMessage) {
-            $input = $input->prop('aria-invalid true');
-            $input = $input->prop('aria-describedby ' . $this->warningId);
-        }
-        $elements[] = $input;
+        $warning = '';
+        if ($this->warningMessage !== '') {
+            $warningId = $this->id . '-warning';
 
-        if ($hasWarningMessage) {
-            $elements[] = $warningMessage;
+            $input = $input->prop('aria-invalid true')->prop(
+                'aria-describedby ' . $warningId
+            );
+
+            $warning = Element::p($this->warningMessage)->props(
+                'id ' . $warningId
+            );
         }
 
-        return implode('', array_map('strval', $elements));
+        return (string) Element::div(
+            Element::label($this->label)->props(
+                'for ' . $this->id,
+                ...$this->labelProperties
+            ),
+            $input,
+            ...[...$this->content, $warning]
+        )->props(...$this->wrapperProperties);
     }
 }
diff --git a/tests/Forms/TextInputTest.php b/tests/Forms/TextInputTest.php
index e7b0579..6f8fba6 100644
--- a/tests/Forms/TextInputTest.php
+++ b/tests/Forms/TextInputTest.php
@@ -8,13 +8,33 @@
 
 use Eightfold\HtmlBuilder\Forms\TextInput;
 
+use Eightfold\HtmlBuilder\Element;
+
 class TextInputTest extends TestCase
 {
+    #[Test]
+    public function can_set_custom_id(): void // phpcs:ignore
+    {
+        $expected = <<<html
+        <div is="form-control"><label for="text-input-id">Text</label><input id="text-input-id" name="text" type="text" aria-describedby="text-input-id-warning" aria-invalid="true"><p id="text-input-id-help">Helpful text</p><p id="text-input-id-warning">Invalid value</p></div>
+        html;
+
+        $result = (string) TextInput::create(
+            label: 'Text',
+            name: 'text',
+            warningMessage: 'Invalid value'
+        )->id('text-input-id')->content(
+            Element::p('Helpful text')->props('id text-input-id-help')
+        )->wrapperProps('is form-control');
+
+        parent::assertSame($expected, $result);
+    }
+
     #[Test]
     public function can_set_value(): void // phpcs:ignore
     {
         $expected = <<<html
-        <label for="text">Text</label><input id="text" name="text" type="text" value="Posted value">
+        <div><label for="text">Text</label><input id="text" name="text" type="text" value="Posted value"></div>
         html;
 
         $result = (string) TextInput::create(
@@ -30,7 +50,7 @@ public function can_set_value(): void // phpcs:ignore
     public function can_set_warning_message(): void // phpcs:ignore
     {
         $expected = <<<html
-        <label for="text">Text</label><input id="text" name="text" type="text" aria-describedby="text-warning" aria-invalid="true"><p id="text-warning">Invalid value</p>
+        <div><label for="text">Text</label><input id="text" name="text" type="text" aria-describedby="text-warning" aria-invalid="true"><p id="text-warning">Invalid value</p></div>
         html;
 
         $result = (string) TextInput::create(
@@ -46,7 +66,7 @@ public function can_set_warning_message(): void // phpcs:ignore
     public function is_expected_base(): void // phpcs:ignore
     {
         $expected = <<<html
-        <label for="text">Text</label><input id="text" name="text" type="text">
+        <div><label for="text">Text</label><input id="text" name="text" type="text"></div>
         html;
 
         $result = (string) TextInput::create(

From 263e060070faee6a49714cc56b4f8189ee8f57c9 Mon Sep 17 00:00:00 2001
From: Josh Bruce <josh@8fold.pro>
Date: Wed, 14 Oct 2026 18:12:50 -0400
Subject: [PATCH 2/9] BC: Email input updates

---
 src/Forms/EmailInput.php       | 79 +++++++++++++++++++++++-----------
 src/Forms/TextInput.php        | 21 +++++++--
 tests/Forms/EmailInputTest.php | 26 +++++++++--
 3 files changed, 94 insertions(+), 32 deletions(-)

diff --git a/src/Forms/EmailInput.php b/src/Forms/EmailInput.php
index 9fde9d3..e6bf195 100644
--- a/src/Forms/EmailInput.php
+++ b/src/Forms/EmailInput.php
@@ -10,11 +10,12 @@
 
 class EmailInput implements Stringable
 {
-    // phpcs:disable
-    private string $warningId {
-        get => $this->name . '-warning';
-    }
-    // phpcs:enable
+    private string $id;
+
+    /**
+     * @var string[]
+     */
+    private array $wrapperProperties = [];
 
     /**
      * @var string[]
@@ -26,6 +27,11 @@ class EmailInput implements Stringable
      */
     private array $inputProperties = [];
 
+    /**
+     * @var array<string|Stringable>
+     */
+    private array $content = [];
+
     public static function create(
         string|Stringable $label,
         string|Stringable $name,
@@ -41,6 +47,19 @@ final private function __construct(
         private readonly string $value,
         private readonly string|PropertyInterface $warningMessage = ''
     ) {
+        $this->id = $name;
+    }
+
+    public function id(string $id): self
+    {
+        $this->id = $id;
+        return $this;
+    }
+
+    public function wrapperProps(string ...$properties): self
+    {
+        $this->wrapperProperties = $properties;
+        return $this;
     }
 
     public function labelProps(string ...$properties): self
@@ -55,7 +74,13 @@ public function inputProps(string ...$properties): self
         return $this;
     }
 
-    private function warningMessage(): string|PropertyInterface
+    public function content(string|Stringable ...$content): self
+    {
+        $this->content = $content;
+        return $this;
+    }
+
+    private function warningMessage(string $warningId): string|PropertyInterface
     {
         if ($this->warningMessage === '') {
             return '';
@@ -63,43 +88,45 @@ private function warningMessage(): string|PropertyInterface
 
         if (is_string($this->warningMessage)) {
             return Element::p($this->warningMessage)->props(
-                'id ' . $this->warningId
+                'id ' . $warningId
             );
         }
 
-        return $this->warningMessage->prop('id ' . $this->warningId);
+        $warning = clone $this->warningMessage;
+
+        return $warning->prop('id ' . $warningId);
     }
 
     public function __toString(): string
     {
-        $elements = [];
-        $elements[] = Element::label($this->label)->props(
-            'for ' . $this->name,
-            ...$this->labelProperties
-        );
-
         $input = Element::input()->omitEndTag()->props(
             'type email',
-            'id ' . $this->name,
+            'id ' . $this->id,
             'name ' . $this->name,
             'value ' . $this->value,
-            'autocorrect off',
             'autocapitalize off',
+            'autocorrect off',
             ...$this->inputProperties
         );
 
-        $warningMessage = self::warningMessage();
-        $hasWarningMessage = ($warningMessage !== '');
-        if ($hasWarningMessage) {
-            $input = $input->prop('aria-invalid true');
-            $input = $input->prop('aria-describedby ' . $this->warningId);
-        }
-        $elements[] = $input;
+        $warning = '';
+        if ($this->warningMessage !== '') {
+            $warningId = $this->id . '-warning';
+
+            $input = $input->prop('aria-invalid true')->prop(
+                'aria-describedby ' . $warningId
+            );
 
-        if ($hasWarningMessage) {
-            $elements[] = $warningMessage;
+            $warning = (string) self::warningMessage($warningId);
         }
 
-        return implode('', array_map('strval', $elements));
+        return (string) Element::div(
+            Element::label($this->label)->props(
+                'for ' . $this->id,
+                ...$this->labelProperties
+            ),
+            $input,
+            ...[...$this->content, $warning]
+        )->props(...$this->wrapperProperties);
     }
 }
diff --git a/src/Forms/TextInput.php b/src/Forms/TextInput.php
index e312851..9895b13 100644
--- a/src/Forms/TextInput.php
+++ b/src/Forms/TextInput.php
@@ -80,6 +80,23 @@ public function content(string|Stringable ...$content): self
         return $this;
     }
 
+    private function warningMessage(string $warningId): string|PropertyInterface
+    {
+        if ($this->warningMessage === '') {
+            return '';
+        }
+
+        if (is_string($this->warningMessage)) {
+            return Element::p($this->warningMessage)->props(
+                'id ' . $warningId
+            );
+        }
+
+        $warning = clone $this->warningMessage;
+
+        return $warning->prop('id ' . $warningId);
+    }
+
     public function __toString(): string
     {
         $input = Element::input()->omitEndTag()->props(
@@ -98,9 +115,7 @@ public function __toString(): string
                 'aria-describedby ' . $warningId
             );
 
-            $warning = Element::p($this->warningMessage)->props(
-                'id ' . $warningId
-            );
+            $warning = (string) self::warningMessage($warningId);
         }
 
         return (string) Element::div(
diff --git a/tests/Forms/EmailInputTest.php b/tests/Forms/EmailInputTest.php
index b11cb40..e37d1fc 100644
--- a/tests/Forms/EmailInputTest.php
+++ b/tests/Forms/EmailInputTest.php
@@ -8,13 +8,33 @@
 
 use Eightfold\HtmlBuilder\Forms\EmailInput;
 
+use Eightfold\HtmlBuilder\Element;
+
 class EmailInputTest extends TestCase
 {
+    #[Test]
+    public function can_set_custom_id(): void // phpcs:ignore
+    {
+        $expected = <<<html
+        <div is="form-control"><label for="email-input-id">Email</label><input id="email-input-id" name="email" type="email" aria-describedby="email-input-id-warning" aria-invalid="true" autocapitalize="off" autocorrect="off"><p id="email-input-id-help">Helpful text</p><p id="email-input-id-warning">Invalid value</p></div>
+        html;
+
+        $result = (string) EmailInput::create(
+            label: 'Email',
+            name: 'email',
+            warningMessage: 'Invalid value'
+        )->id('email-input-id')->content(
+            Element::p('Helpful text')->props('id email-input-id-help')
+        )->wrapperProps('is form-control');
+
+        parent::assertSame($expected, $result);
+    }
+
     #[Test]
     public function can_set_value(): void // phpcs:ignore
     {
         $expected = <<<html
-        <label for="email">Email</label><input id="email" name="email" type="email" value="support@8fold.pro" autocapitalize="off" autocorrect="off">
+        <div><label for="email">Email</label><input id="email" name="email" type="email" value="support@8fold.pro" autocapitalize="off" autocorrect="off"></div>
         html;
 
         $result = (string) EmailInput::create(
@@ -30,7 +50,7 @@ public function can_set_value(): void // phpcs:ignore
     public function can_set_warning_message(): void // phpcs:ignore
     {
         $expected = <<<html
-        <label for="email">Email</label><input id="email" name="email" type="email" aria-describedby="email-warning" aria-invalid="true" autocapitalize="off" autocorrect="off"><p id="email-warning">Invalid value</p>
+        <div><label for="email">Email</label><input id="email" name="email" type="email" aria-describedby="email-warning" aria-invalid="true" autocapitalize="off" autocorrect="off"><p id="email-warning">Invalid value</p></div>
         html;
 
         $result = (string) EmailInput::create(
@@ -46,7 +66,7 @@ public function can_set_warning_message(): void // phpcs:ignore
     public function is_expected_base(): void // phpcs:ignore
     {
         $expected = <<<html
-        <label for="email">Email</label><input id="email" name="email" type="email" autocapitalize="off" autocorrect="off">
+        <div><label for="email">Email</label><input id="email" name="email" type="email" autocapitalize="off" autocorrect="off"></div>
         html;
 
         $result = (string) EmailInput::create(

From afc7882d80df81870bcc43edf400a70aafea8a3a Mon Sep 17 00:00:00 2001
From: Josh Bruce <josh@8fold.pro>
Date: Wed, 14 Oct 2026 21:37:15 -0400
Subject: [PATCH 3/9] BC: Select input with multiple

---
 src/Forms/Select.php       | 305 +++++++++++++++++++++++++++++--------
 src/Forms/SelectType.php   |   1 +
 tests/Forms/SelectTest.php |  34 ++++-
 3 files changed, 271 insertions(+), 69 deletions(-)

diff --git a/src/Forms/Select.php b/src/Forms/Select.php
index bd92adb..e2d91c5 100644
--- a/src/Forms/Select.php
+++ b/src/Forms/Select.php
@@ -13,11 +13,7 @@
 
 class Select implements Stringable
 {
-    // phpcs:disable
-    private string $warningId {
-        get => $this->name . '-warning';
-    }
-    // phpcs:enable
+    private string $id;
 
     /**
      * @var string[]
@@ -29,6 +25,16 @@ class Select implements Stringable
      */
     private array $labelProperties = [];
 
+    /**
+     * @var string[]
+     */
+    private array $inputProperties = [];
+
+    /**
+     * @var array<string|Stringable>
+     */
+    private array $content = [];
+
     private SelectType $type = SelectType::Dropdown;
 
     /**
@@ -56,6 +62,13 @@ final private function __construct(
         private readonly string|array $selected = [],
         private readonly string|PropertyInterface $warningMessage = ''
     ) {
+        $this->id = $name;
+    }
+
+    public function id(string $id): self
+    {
+        $this->id = $id;
+        return $this;
     }
 
     public function wrapperProps(string ...$properties): self
@@ -70,12 +83,47 @@ public function labelProps(string ...$properties): self
         return $this;
     }
 
+    public function inputProps(string ...$properties): self
+    {
+        $this->inputProperties = $properties;
+        return $this;
+    }
+
+    public function content(string|Stringable ...$content): self
+    {
+        $this->content = $content;
+        return $this;
+    }
+
+    private function warningMessage(string $warningId): string|PropertyInterface
+    {
+        if ($this->warningMessage === '') {
+            return '';
+        }
+
+        if (is_string($this->warningMessage)) {
+            return Element::p($this->warningMessage)->props(
+                'id ' . $warningId
+            );
+        }
+
+        $warning = clone $this->warningMessage;
+
+        return $warning->prop('id ' . $warningId);
+    }
+
     public function dropdown(): self
     {
         $this->type = SelectType::Dropdown;
         return $this;
     }
 
+    public function multiple(): self
+    {
+        $this->type = SelectType::Multiple;
+        return $this;
+    }
+
     public function radio(): self
     {
         $this->type = SelectType::Radio;
@@ -91,10 +139,10 @@ public function checkbox(): self
     private function hasSelected(): bool
     {
         $selected = self::selected();
-        if (is_string($selected) and strlen($selected) > 0) {
+        if (is_string($selected) and $selected !== '') {
             return true;
 
-        } elseif (is_array($selected) and count($selected) > 0) {
+        } elseif (is_array($selected) and $selected !== 0) {
             return true;
 
         }
@@ -106,84 +154,178 @@ private function hasSelected(): bool
      */
     private function selected(): string|array
     {
-        if ($this->type === SelectType::Checkbox) {
-            if (is_array($this->selected)) {
-                return $this->selected;
-            }
-            return [$this->selected];
-        }
+        return self::selectedValues();
+        // if ($this->type === SelectType::Checkbox) {
+        //     if (is_array($this->selected)) {
+        //         return $this->selected;
+        //     }
+        //     return [$this->selected];
+        // }
+
+        // if (is_array($this->selected) and count($this->selected) > 0) {
+        //     return $this->selected[0];
+        // }
+        // return $this->selected;
+    }
 
-        if (is_array($this->selected) and count($this->selected) > 0) {
-            return $this->selected[0];
-        }
-        return $this->selected;
+    /**
+     * @return list<string>
+     */
+    private function selectedValues(): array
+    {
+        $values = is_array($this->selected)
+            ? array_values($this->selected)
+            : [$this->selected];
+
+        return match ($this->type) {
+            SelectType::Multiple, SelectType::Checkbox => $values,
+            SelectType::Dropdown, SelectType::Radio => array_slice($values, 0, 1)
+        };
     }
 
     private function isSelected(string $value): bool
     {
-        if (self::hasSelected() === false) {
-            return false;
-        }
-
-        if (is_array(self::selected())) {
-            return in_array($value, self::selected());
-        }
-        return $value === self::selected();
+        return in_array($value, self::selectedValues(), true);
+        // if (self::hasSelected() === false) {
+        //     return false;
+        // }
+
+        // if (is_array(self::selected())) {
+        //     return in_array($value, self::selected());
+        // }
+        // return $value === self::selected();
     }
 
-    private function warningMessage(): string|PropertyInterface
+    public function __toString(): string
     {
-        if ($this->warningMessage === '') {
-            return '';
+        $warning  = self::warningMessage($this->id . '-warning');
+        $selected = self::selectedValues();
+
+        return (string) match ($this->type) {
+            SelectType::Dropdown,
+            SelectType::Multiple => self::selectDropdown($warning, $selected),
+            SelectType::Radio,
+            SelectType::Checkbox => Self::selectGroup($warning, $selected)
+        };
+        // if ($this->type === SelectType::Dropdown) {
+        //     return (string) self::selectDropdown();
+        // }
+        // return (string) self::selectOther();
+    }
+
+    private function selectDropdown(
+        string|PropertyInterface $warning,
+        array $selected
+    ): Element {
+        $options = [];
+
+        foreach ($this->options as $value => $label) {
+            $value = (string) $value;
+            $option = Element::option($label)->props('value ' . $value);
+
+            if (in_array($value, $selected, true)) {
+                $option = $option->prop('selected selected');
+            }
+
+            $options[] = $option;
         }
 
-        if (is_string($this->warningMessage)) {
-            return Element::p($this->warningMessage)->props(
-                'id ' . $this->warningId
-            );
+        $inputProperties = self::controlProperties($warning);
+
+        $select = Element::select(...$options)->props(...[
+            ...$inputProperties,
+            'id ' . $this->id,
+            'name ' . $this->name
+        ]);
+
+        if ($this->type === SelectType::Multiple) {
+            $select = $select->prop('multiple multiple');
         }
 
-        return $this->warningMessage->prop('id ' . $this->warningId);
+        return Element::div(
+            Element::label($this->label)->props(...[
+                ...$this->labelProperties,
+                'for ' . $this->id
+            ]),
+            $select,
+            ...[...$this->content, $warning]
+        )->props(...$this->wrapperProperties);
+        // $elements = [];
+
+        // $warningMessage = self::warningMessage();
+        // $hasWarningMessage = ($warningMessage !== '');
+
+        // foreach ($this->options as $value => $content) {
+        //     $value  = (string) $value;
+        //     $option = Element::option($content)->props('value ' . $value);
+        //     if (self::isSelected($value)) {
+        //         $option = $option->prop('selected selected');
+        //     }
+        //     $elements[] = $option;
+        // }
+
+        // $input = Element::select(
+        //     ...$elements
+        // )->props('id ' . $this->name, 'name ' . $this->name);
+        // if ($hasWarningMessage) {
+        //     $input = $input->prop('aria-invalid true');
+        //     $input = $input->prop('aria-describedby ' . $this->warningId);
+        // }
+
+        // return Element::div(
+        //     Element::label(
+        //         $this->label
+        //     )->props('for ' . $this->name, ...$this->labelProperties),
+        //     $input,
+        //     $warningMessage
+        // )->props(...$this->wrapperProperties);
     }
 
-    public function __toString(): string
-    {
-        if ($this->type === SelectType::Dropdown) {
-            return (string) self::selectDropdown();
+    /**
+     * @param list<string> $selected
+     */
+    private function selectGroup(
+        string|PropertyInterface $warning,
+        array $selected
+    ): Element {
+        $members = [];
+        $isCheckbox = $this->type === SelectType::Checkbox;
+        $type = $isCheckbox ? 'checkbox' : 'radio';
+        $name = (string) $this->name;
+
+        // Retains existing checkbox-group naming without adding [] twice.
+        if ($isCheckbox && str_ends_with($name, '[]') === false) {
+            $name .= '[]';
         }
-        return (string) self::selectOther();
-    }
 
-    private function selectDropdown(): Element
-    {
-        $elements = [];
+        $inputProperties = self::controlProperties($warning);
+        $index = 0;
 
-        $warningMessage = self::warningMessage();
-        $hasWarningMessage = ($warningMessage !== '');
+        foreach ($this->options as $value => $label) {
+            $value = (string) $value;
+            $memberId = $this->id . '-option-' . $index++;
 
-        foreach ($this->options as $value => $content) {
-            $value  = (string) $value;
-            $option = Element::option($content)->props('value ' . $value);
-            if (self::isSelected($value)) {
-                $option = $option->prop('selected selected');
+            $input = Element::input()->omitEndTag()->props(...[
+                ...$inputProperties,
+                'id ' . $memberId,
+                'name ' . $name,
+                'type ' . $type,
+                'value ' . $value
+            ]);
+
+            if (in_array($value, $selected, true)) {
+                $input = $input->prop('checked checked');
             }
-            $elements[] = $option;
-        }
 
-        $input = Element::select(
-            ...$elements
-        )->props('id ' . $this->name, 'name ' . $this->name);
-        if ($hasWarningMessage) {
-            $input = $input->prop('aria-invalid true');
-            $input = $input->prop('aria-describedby ' . $this->warningId);
+            $members[] = Element::div(
+                $input,
+                Element::label($label)->props('for ' . $memberId)
+            );
         }
 
-        return Element::div(
-            Element::label(
-                $this->label
-            )->props('for ' . $this->name, ...$this->labelProperties),
-            $input,
-            $warningMessage
+        return Element::fieldset(
+            Element::legend($this->label)->props(...$this->labelProperties),
+            ...[...$members, ...$this->content, $warning]
         )->props(...$this->wrapperProperties);
     }
 
@@ -230,4 +372,41 @@ private function selectOther(): Fieldset
         //     ...$elements
         // );
     }
+
+    /** @return list<string> */
+    private function controlProperties(
+        string|PropertyInterface $warning
+    ): array {
+        $properties = [];
+        $descriptionIds = [];
+
+        foreach ($this->inputProperties as $property) {
+            if (str_starts_with($property, 'aria-describedby ')) {
+                $ids = preg_split(
+                    '/\s+/',
+                    trim(substr($property, strlen('aria-describedby ')))
+                );
+
+                foreach ($ids === false ? [] : $ids as $id) {
+                    if ($id !== '') {
+                        $descriptionIds[] = $id;
+                    }
+                }
+            } else {
+                $properties[] = $property;
+            }
+        }
+
+        if ($warning !== '') {
+            $descriptionIds[] = $this->id . '-warning';
+            $properties[] = 'aria-invalid true';
+        }
+
+        if ($descriptionIds !== []) {
+            $properties[] = 'aria-describedby '
+                . implode(' ', array_unique($descriptionIds));
+        }
+
+        return $properties;
+    }
 }
diff --git a/src/Forms/SelectType.php b/src/Forms/SelectType.php
index 7547dc0..976bc80 100644
--- a/src/Forms/SelectType.php
+++ b/src/Forms/SelectType.php
@@ -4,6 +4,7 @@
 enum SelectType
 {
     case Dropdown;
+    case Multiple;
     case Radio;
     case Checkbox;
 }
diff --git a/tests/Forms/SelectTest.php b/tests/Forms/SelectTest.php
index ce6a798..19d7faa 100644
--- a/tests/Forms/SelectTest.php
+++ b/tests/Forms/SelectTest.php
@@ -16,7 +16,7 @@ class SelectTest extends TestCase
     public function ticket_36(): void // phpcs: ignore
     {
         $expected = <<<html
-        <fieldset><legend>Toppings</legend><div><input id="toppings-mushroom" name="toppings[]" type="checkbox" value="mushroom" aria-describedby="toppings-warning" aria-invalid="true"><label for="toppings-mushroom">Mushroom</label></div><div><input id="toppings-olive" name="toppings[]" type="checkbox" value="olive" aria-describedby="toppings-warning" aria-invalid="true"><label for="toppings-olive">Olive</label></div><p id="toppings-warning">Choose at least one topping.</p></fieldset>
+        <fieldset><legend>Toppings</legend><div><input id="toppings-option-0" name="toppings[]" type="checkbox" value="mushroom" aria-describedby="toppings-warning" aria-invalid="true"><label for="toppings-option-0">Mushroom</label></div><div><input id="toppings-option-1" name="toppings[]" type="checkbox" value="olive" aria-describedby="toppings-warning" aria-invalid="true"><label for="toppings-option-1">Olive</label></div><p id="toppings-warning">Choose at least one topping.</p></fieldset>
         html;
 
         $result = (string) Select::create(
@@ -30,6 +30,28 @@ public function ticket_36(): void // phpcs: ignore
         parent::assertSame($expected, $result);
     }
 
+    #[Test]
+    public function can_be_multiple(): void // phpcs: ignore
+    {
+        $expected = <<<html
+        <div><label for="select">Select</label><select id="select" name="select" aria-describedby="select-warning" aria-invalid="true" multiple><option value="value">display</option><option value="value2">display2</option></select><ul id="select-warning"><li>Invalid value</li></ul></div>
+        html;
+
+        $result = (string) Select::create(
+            name: 'select',
+            options: [
+                'value'  => 'display',
+                'value2' => 'display2'
+            ],
+            warningMessage: Element::ul(
+                Element::li('Invalid value')
+            ),
+            label: 'Select'
+        )->multiple();
+
+        parent::assertSame($expected, $result);
+    }
+
     #[Test]
     public function warning_message_can_be_property_interface(): void // phpcs: ignore
     {
@@ -91,7 +113,7 @@ public function can_add_props_to_label(): void // phpcs: ignore
         parent::assertSame($expected, $result);
 
         $expected = <<<html
-        <fieldset><legend is="checkbox">Select</legend><div><input id="select-value" name="select[]" type="checkbox" value="value"><label for="select-value">display</label></div><div><input id="select-value2" name="select[]" type="checkbox" value="value2"><label for="select-value2">display2</label></div></fieldset>
+        <fieldset><legend is="checkbox">Select</legend><div><input id="select-option-0" name="select[]" type="checkbox" value="value"><label for="select-option-0">display</label></div><div><input id="select-option-1" name="select[]" type="checkbox" value="value2"><label for="select-option-1">display2</label></div></fieldset>
         html;
 
         $result = (string) Select::create(
@@ -106,7 +128,7 @@ public function can_add_props_to_label(): void // phpcs: ignore
         parent::assertSame($expected, $result);
 
         $expected = <<<html
-        <fieldset><legend is="radio">Select</legend><div><input id="select-value" name="select" type="radio" value="value"><label for="select-value">display</label></div><div><input id="select-value2" name="select" type="radio" value="value2"><label for="select-value2">display2</label></div></fieldset>
+        <fieldset><legend is="radio">Select</legend><div><input id="select-option-0" name="select" type="radio" value="value"><label for="select-option-0">display</label></div><div><input id="select-option-1" name="select" type="radio" value="value2"><label for="select-option-1">display2</label></div></fieldset>
         html;
 
         $result = (string) Select::create(
@@ -125,7 +147,7 @@ public function can_add_props_to_label(): void // phpcs: ignore
     public function can_be_checkboxes(): void // phpcs: ignore
     {
         $expected = <<<html
-        <fieldset><legend>Select your option</legend><div><input id="select-value" name="select[]" type="checkbox" value="value" checked><label for="select-value">display</label></div><div><input id="select-value2" name="select[]" type="checkbox" value="value2" checked><label for="select-value2">display2</label></div></fieldset>
+        <fieldset><legend>Select your option</legend><div><input id="select-option-0" name="select[]" type="checkbox" value="value" checked><label for="select-option-0">display</label></div><div><input id="select-option-1" name="select[]" type="checkbox" value="value2" checked><label for="select-option-1">display2</label></div></fieldset>
         html;
 
         $result = (string) Select::create(
@@ -145,7 +167,7 @@ public function can_be_checkboxes(): void // phpcs: ignore
     public function can_be_radio_buttons(): void // phpcs: ignore
     {
         $expected = <<<html
-        <fieldset><legend>Select your option</legend><div><input id="select-value" name="select" type="radio" value="value" checked><label for="select-value">display</label></div></fieldset>
+        <fieldset><legend>Select your option</legend><div><input id="select-option-0" name="select" type="radio" value="value" checked><label for="select-option-0">display</label></div></fieldset>
         html;
 
         $result = (string) Select::create(
@@ -182,7 +204,7 @@ public function dropdown_mode_is_explicit(): void // phpcs: ignore
     public function checkbox_mode_is_explicit(): void // phpcs: ignore
     {
         $expected = <<<html
-        <fieldset><legend>Select your option</legend><div><input id="select-value" name="select[]" type="checkbox" value="value" checked><label for="select-value">display</label></div></fieldset>
+        <fieldset><legend>Select your option</legend><div><input id="select-option-0" name="select[]" type="checkbox" value="value" checked><label for="select-option-0">display</label></div></fieldset>
         html;
 
         $result = (string) Select::create(

From 957d78633378fb33a679428fd579ed64110ca576 Mon Sep 17 00:00:00 2001
From: Josh Bruce <josh@8fold.pro>
Date: Wed, 14 Oct 2026 21:40:34 -0400
Subject: [PATCH 4/9] deprecate: selected

---
 src/Forms/Select.php | 97 +-------------------------------------------
 1 file changed, 1 insertion(+), 96 deletions(-)

diff --git a/src/Forms/Select.php b/src/Forms/Select.php
index e2d91c5..5ea81e5 100644
--- a/src/Forms/Select.php
+++ b/src/Forms/Select.php
@@ -152,20 +152,10 @@ private function hasSelected(): bool
     /**
      * @return string|string[]
      */
+    #[Deprecated(message: 'Use selectedValues() instead.', since: '5.0')]
     private function selected(): string|array
     {
         return self::selectedValues();
-        // if ($this->type === SelectType::Checkbox) {
-        //     if (is_array($this->selected)) {
-        //         return $this->selected;
-        //     }
-        //     return [$this->selected];
-        // }
-
-        // if (is_array($this->selected) and count($this->selected) > 0) {
-        //     return $this->selected[0];
-        // }
-        // return $this->selected;
     }
 
     /**
@@ -186,14 +176,6 @@ private function selectedValues(): array
     private function isSelected(string $value): bool
     {
         return in_array($value, self::selectedValues(), true);
-        // if (self::hasSelected() === false) {
-        //     return false;
-        // }
-
-        // if (is_array(self::selected())) {
-        //     return in_array($value, self::selected());
-        // }
-        // return $value === self::selected();
     }
 
     public function __toString(): string
@@ -207,10 +189,6 @@ public function __toString(): string
             SelectType::Radio,
             SelectType::Checkbox => Self::selectGroup($warning, $selected)
         };
-        // if ($this->type === SelectType::Dropdown) {
-        //     return (string) self::selectDropdown();
-        // }
-        // return (string) self::selectOther();
     }
 
     private function selectDropdown(
@@ -250,35 +228,6 @@ private function selectDropdown(
             $select,
             ...[...$this->content, $warning]
         )->props(...$this->wrapperProperties);
-        // $elements = [];
-
-        // $warningMessage = self::warningMessage();
-        // $hasWarningMessage = ($warningMessage !== '');
-
-        // foreach ($this->options as $value => $content) {
-        //     $value  = (string) $value;
-        //     $option = Element::option($content)->props('value ' . $value);
-        //     if (self::isSelected($value)) {
-        //         $option = $option->prop('selected selected');
-        //     }
-        //     $elements[] = $option;
-        // }
-
-        // $input = Element::select(
-        //     ...$elements
-        // )->props('id ' . $this->name, 'name ' . $this->name);
-        // if ($hasWarningMessage) {
-        //     $input = $input->prop('aria-invalid true');
-        //     $input = $input->prop('aria-describedby ' . $this->warningId);
-        // }
-
-        // return Element::div(
-        //     Element::label(
-        //         $this->label
-        //     )->props('for ' . $this->name, ...$this->labelProperties),
-        //     $input,
-        //     $warningMessage
-        // )->props(...$this->wrapperProperties);
     }
 
     /**
@@ -329,50 +278,6 @@ private function selectGroup(
         )->props(...$this->wrapperProperties);
     }
 
-    private function selectOther(): Fieldset
-    {
-        $elements = [];
-        $type = $this->type === SelectType::Checkbox ? 'checkbox' : 'radio';
-
-        $warningMessage = self::warningMessage();
-        $hasWarningMessage = ($warningMessage !== '');
-
-        foreach ($this->options as $value => $content) {
-            $value = (string) $value;
-            $id    = $this->name . '-' . $value;
-            $label = Element::label($content)->props('for ' . $id);
-            $input = Element::input()->omitEndTag()->props(
-                'id ' . $id,
-                ($this->type === SelectType::Checkbox)
-                    ? 'name ' . $this->name . '[]'
-                    : 'name ' . $this->name,
-                'type ' . $type,
-                'value ' . $value
-            );
-
-            if (self::isSelected($value)) {
-                $input = $input->prop('checked checked');
-            }
-
-            if ($hasWarningMessage) {
-                $input = $input->prop('aria-invalid true');
-                $input = $input->prop('aria-describedby ' . $this->warningId);
-            }
-            $elements[] = Element::div($input, $label);
-        }
-
-        return Fieldset::create(
-            $this->label,
-            $this->name,
-            $warningMessage
-        )->elements(...$elements)->labelProps(...$this->labelProperties);
-
-        // return Element::fieldset(
-        //     Element::legend($this->label)->props(...$this->labelProperties),
-        //     ...$elements
-        // );
-    }
-
     /** @return list<string> */
     private function controlProperties(
         string|PropertyInterface $warning

From 1ca67289a9f540343ff4c6accb4c8fea18e03c76 Mon Sep 17 00:00:00 2001
From: Josh Bruce <josh@8fold.pro>
Date: Wed, 14 Oct 2026 22:53:04 -0400
Subject: [PATCH 5/9] BC: PropertyInterface extends Stringable

---
 src/Element.php           | 4 +---
 src/PropertyInterface.php | 4 +++-
 2 files changed, 4 insertions(+), 4 deletions(-)

diff --git a/src/Element.php b/src/Element.php
index 2fa8678..0970443 100644
--- a/src/Element.php
+++ b/src/Element.php
@@ -3,11 +3,9 @@
 
 namespace Eightfold\HtmlBuilder;
 
-use Stringable;
-
 use Eightfold\HtmlBuilder\PropertyInterface;
 
-class Element implements Stringable, PropertyInterface
+class Element implements PropertyInterface
 {
     /**
      * The following attributes will be placed in this order if used in an
diff --git a/src/PropertyInterface.php b/src/PropertyInterface.php
index 1818e83..6410e39 100644
--- a/src/PropertyInterface.php
+++ b/src/PropertyInterface.php
@@ -3,7 +3,9 @@
 
 namespace Eightfold\HtmlBuilder;
 
-interface PropertyInterface
+use Stringable;
+
+interface PropertyInterface extends Stringable
 {
     public function props(string ...$properties): static;
 

From 0231ff31a92cbe402ddc903e527ce6b7db601fa4 Mon Sep 17 00:00:00 2001
From: Josh Bruce <josh@8fold.pro>
Date: Wed, 14 Oct 2026 23:39:57 -0400
Subject: [PATCH 6/9] performance: Needed to increase to 1ms

---
 tests/PerformanceTest.php | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/tests/PerformanceTest.php b/tests/PerformanceTest.php
index cd9291a..d2124ee 100644
--- a/tests/PerformanceTest.php
+++ b/tests/PerformanceTest.php
@@ -56,7 +56,7 @@ public function document_is_speedy(): void // phpcs:ignore
         $elapsed = $end - $start;
         $ms      = $elapsed/1e+6;
 
-        $this->assertLessThan(0.75, $ms);
+        $this->assertLessThan(1, $ms);
     }
 
     #[Test]

From f1f4560f3a78cd1b46695dc9aabef4ad86c200ac Mon Sep 17 00:00:00 2001
From: Josh Bruce <josh@8fold.pro>
Date: Wed, 14 Oct 2026 23:52:10 -0400
Subject: [PATCH 7/9] feature: Select allows multiple arie-describedby IDs

---
 src/Forms/ControlProperties.php |  44 +++++++++
 src/Forms/Select.php            | 155 ++++++++++++--------------------
 2 files changed, 103 insertions(+), 96 deletions(-)
 create mode 100644 src/Forms/ControlProperties.php

diff --git a/src/Forms/ControlProperties.php b/src/Forms/ControlProperties.php
new file mode 100644
index 0000000..73900ec
--- /dev/null
+++ b/src/Forms/ControlProperties.php
@@ -0,0 +1,44 @@
+<?php
+declare(strict_types=1);
+
+namespace Eightfold\HtmlBuilder\Forms;
+
+final class ControlProperties
+{
+    /**
+     * @param list<string> $inputProperties
+     * @return list<string>
+     */
+    public static function withWarning(
+        array $inputProperties,
+        string $warningId
+    ): array {
+        $properties = [];
+        $descriptionIds = [];
+
+        $ariaProperty = 'aria-describedby ';
+        foreach ($inputProperties as $property) {
+            if (str_starts_with($property, $ariaProperty)) {
+                $ids = preg_split(
+                    '/\s+/',
+                    trim(substr($property, strlen($ariaProperty)))
+                );
+
+                foreach ($ids === false ? [] : $ids as $id) {
+                    if ($id !== '') {
+                        $descriptionIds[] = $id;
+                    }
+                }
+            } else {
+                $properties[] = $property;
+            }
+        }
+
+        $descriptionIds[] = $warningId;
+
+        $properties[] = 'aria-invalid true';
+        $properties[] = $ariaProperty . implode(' ', array_unique($descriptionIds));
+
+        return $properties;
+    }
+}
diff --git a/src/Forms/Select.php b/src/Forms/Select.php
index 5ea81e5..ec2bab4 100644
--- a/src/Forms/Select.php
+++ b/src/Forms/Select.php
@@ -8,6 +8,7 @@
 use Eightfold\HtmlBuilder\Element;
 use Eightfold\HtmlBuilder\PropertyInterface;
 
+use Eightfold\HtmlBuilder\Forms\ControlProperties;
 use Eightfold\HtmlBuilder\Forms\SelectType;
 use Eightfold\HtmlBuilder\Forms\Fieldset;
 
@@ -16,22 +17,22 @@ class Select implements Stringable
     private string $id;
 
     /**
-     * @var string[]
+     * @var list<string>
      */
     private array $wrapperProperties = [];
 
     /**
-     * @var string[]
+     * @var list<string>
      */
     private array $labelProperties = [];
 
     /**
-     * @var string[]
+     * @var list<string>
      */
     private array $inputProperties = [];
 
     /**
-     * @var array<string|Stringable>
+     * @var list<string|Stringable>
      */
     private array $content = [];
 
@@ -62,7 +63,7 @@ final private function __construct(
         private readonly string|array $selected = [],
         private readonly string|PropertyInterface $warningMessage = ''
     ) {
-        $this->id = $name;
+        $this->id = (string) $name;
     }
 
     public function id(string $id): self
@@ -73,45 +74,28 @@ public function id(string $id): self
 
     public function wrapperProps(string ...$properties): self
     {
-        $this->wrapperProperties = $properties;
+        $this->wrapperProperties = array_values($properties);
         return $this;
     }
 
     public function labelProps(string ...$properties): self
     {
-        $this->labelProperties = $properties;
+        $this->labelProperties = array_values($properties);
         return $this;
     }
 
     public function inputProps(string ...$properties): self
     {
-        $this->inputProperties = $properties;
+        $this->inputProperties = array_values($properties);
         return $this;
     }
 
     public function content(string|Stringable ...$content): self
     {
-        $this->content = $content;
+        $this->content = array_values($content);
         return $this;
     }
 
-    private function warningMessage(string $warningId): string|PropertyInterface
-    {
-        if ($this->warningMessage === '') {
-            return '';
-        }
-
-        if (is_string($this->warningMessage)) {
-            return Element::p($this->warningMessage)->props(
-                'id ' . $warningId
-            );
-        }
-
-        $warning = clone $this->warningMessage;
-
-        return $warning->prop('id ' . $warningId);
-    }
-
     public function dropdown(): self
     {
         $this->type = SelectType::Dropdown;
@@ -136,28 +120,6 @@ public function checkbox(): self
         return $this;
     }
 
-    private function hasSelected(): bool
-    {
-        $selected = self::selected();
-        if (is_string($selected) and $selected !== '') {
-            return true;
-
-        } elseif (is_array($selected) and $selected !== 0) {
-            return true;
-
-        }
-        return false;
-    }
-
-    /**
-     * @return string|string[]
-     */
-    #[Deprecated(message: 'Use selectedValues() instead.', since: '5.0')]
-    private function selected(): string|array
-    {
-        return self::selectedValues();
-    }
-
     /**
      * @return list<string>
      */
@@ -173,26 +135,65 @@ private function selectedValues(): array
         };
     }
 
-    private function isSelected(string $value): bool
+    private function warningMessage(): string
+    {
+        if ($this->warningMessage === '') {
+            return '';
+        }
+
+        if (is_string($this->warningMessage)) {
+            return (string) Element::p($this->warningMessage)->props(
+                'id ' . $this->id . '-warning'
+            );
+        }
+
+        $warning = clone $this->warningMessage;
+
+        return (string) $warning->prop('id ' . $this->id . '-warning');
+    }
+
+    /**
+     * @return list<string>
+     */
+    private function inputProperties(bool $noWarning): array
     {
-        return in_array($value, self::selectedValues(), true);
+        return ($noWarning)
+            ? $this->inputProperties
+            : ControlProperties::withWarning(
+                $this->inputProperties,
+                $this->id . '-warning'
+            );
     }
 
     public function __toString(): string
     {
-        $warning  = self::warningMessage($this->id . '-warning');
-        $selected = self::selectedValues();
+        $warning         = self::warningMessage();
+        $inputProperties = self::inputProperties($warning === '');
+        $selected        = self::selectedValues();
 
         return (string) match ($this->type) {
             SelectType::Dropdown,
-            SelectType::Multiple => self::selectDropdown($warning, $selected),
+            SelectType::Multiple => self::selectDropdown(
+                $warning,
+                $inputProperties,
+                $selected
+            ),
             SelectType::Radio,
-            SelectType::Checkbox => Self::selectGroup($warning, $selected)
+            SelectType::Checkbox => self::selectGroup(
+                $warning,
+                $inputProperties,
+                $selected
+            )
         };
     }
 
+    /**
+     * @param list<string> $inputProperties
+     * @param list<string> $selected
+     */
     private function selectDropdown(
-        string|PropertyInterface $warning,
+        string $warning,
+        array $inputProperties,
         array $selected
     ): Element {
         $options = [];
@@ -208,8 +209,6 @@ private function selectDropdown(
             $options[] = $option;
         }
 
-        $inputProperties = self::controlProperties($warning);
-
         $select = Element::select(...$options)->props(...[
             ...$inputProperties,
             'id ' . $this->id,
@@ -231,10 +230,12 @@ private function selectDropdown(
     }
 
     /**
+     * @param list<string> $inputProperties
      * @param list<string> $selected
      */
     private function selectGroup(
-        string|PropertyInterface $warning,
+        string $warning,
+        array $inputProperties,
         array $selected
     ): Element {
         $members = [];
@@ -247,7 +248,6 @@ private function selectGroup(
             $name .= '[]';
         }
 
-        $inputProperties = self::controlProperties($warning);
         $index = 0;
 
         foreach ($this->options as $value => $label) {
@@ -277,41 +277,4 @@ private function selectGroup(
             ...[...$members, ...$this->content, $warning]
         )->props(...$this->wrapperProperties);
     }
-
-    /** @return list<string> */
-    private function controlProperties(
-        string|PropertyInterface $warning
-    ): array {
-        $properties = [];
-        $descriptionIds = [];
-
-        foreach ($this->inputProperties as $property) {
-            if (str_starts_with($property, 'aria-describedby ')) {
-                $ids = preg_split(
-                    '/\s+/',
-                    trim(substr($property, strlen('aria-describedby ')))
-                );
-
-                foreach ($ids === false ? [] : $ids as $id) {
-                    if ($id !== '') {
-                        $descriptionIds[] = $id;
-                    }
-                }
-            } else {
-                $properties[] = $property;
-            }
-        }
-
-        if ($warning !== '') {
-            $descriptionIds[] = $this->id . '-warning';
-            $properties[] = 'aria-invalid true';
-        }
-
-        if ($descriptionIds !== []) {
-            $properties[] = 'aria-describedby '
-                . implode(' ', array_unique($descriptionIds));
-        }
-
-        return $properties;
-    }
 }

From dba2132e035cc371526ea3320881e0afafe191c6 Mon Sep 17 00:00:00 2001
From: Josh Bruce <josh@8fold.pro>
Date: Thu, 15 Oct 2026 11:15:24 -0400
Subject: [PATCH 8/9] add: ControlGuidanceTest

---
 src/Element.php               |   2 +
 src/Forms/EmailInput.php      |  10 +-
 src/Forms/TextArea.php        | 130 ++++++++++++++++++++
 src/Forms/TextInput.php       |  18 +--
 tests/ControlGuidanceTest.php | 221 ++++++++++++++++++++++++++++++++++
 5 files changed, 367 insertions(+), 14 deletions(-)
 create mode 100644 src/Forms/TextArea.php
 create mode 100644 tests/ControlGuidanceTest.php

diff --git a/src/Element.php b/src/Element.php
index 0970443..5d2512f 100644
--- a/src/Element.php
+++ b/src/Element.php
@@ -5,6 +5,8 @@
 
 use Eightfold\HtmlBuilder\PropertyInterface;
 
+use Stringable;
+
 class Element implements PropertyInterface
 {
     /**
diff --git a/src/Forms/EmailInput.php b/src/Forms/EmailInput.php
index e6bf195..dc3325c 100644
--- a/src/Forms/EmailInput.php
+++ b/src/Forms/EmailInput.php
@@ -47,7 +47,7 @@ final private function __construct(
         private readonly string $value,
         private readonly string|PropertyInterface $warningMessage = ''
     ) {
-        $this->id = $name;
+        $this->id = (string) $name;
     }
 
     public function id(string $id): self
@@ -99,15 +99,15 @@ private function warningMessage(string $warningId): string|PropertyInterface
 
     public function __toString(): string
     {
-        $input = Element::input()->omitEndTag()->props(
+        $input = Element::input()->omitEndTag()->props(...[
+            ...$this->inputProperties,
             'type email',
             'id ' . $this->id,
             'name ' . $this->name,
             'value ' . $this->value,
             'autocapitalize off',
-            'autocorrect off',
-            ...$this->inputProperties
-        );
+            'autocorrect off'
+        ]);
 
         $warning = '';
         if ($this->warningMessage !== '') {
diff --git a/src/Forms/TextArea.php b/src/Forms/TextArea.php
new file mode 100644
index 0000000..655afef
--- /dev/null
+++ b/src/Forms/TextArea.php
@@ -0,0 +1,130 @@
+<?php
+declare(strict_types=1);
+
+namespace Eightfold\HtmlBuilder\Forms;
+
+use Stringable;
+
+use Eightfold\HtmlBuilder\Element;
+use Eightfold\HtmlBuilder\PropertyInterface;
+
+class TextArea implements Stringable
+{
+    private string $id;
+
+    /**
+     * @var string[]
+     */
+    private array $wrapperProperties = [];
+
+    /**
+     * @var string[]
+     */
+    private array $labelProperties = [];
+
+    /**
+     * @var string[]
+     */
+    private array $inputProperties = [];
+
+    /**
+     * @var array<string|Stringable>
+     */
+    private array $content = [];
+
+    public static function create(
+        string|Stringable $label,
+        string|Stringable $name,
+        string $value = '',
+        string|PropertyInterface $warningMessage = ''
+    ): self {
+        return new self($label, $name, $value, $warningMessage);
+    }
+
+    final private function __construct(
+        private readonly string|Stringable $label,
+        private readonly string|Stringable $name,
+        private readonly string $value,
+        private readonly string|PropertyInterface $warningMessage = ''
+    ) {
+        $this->id = (string) $name;
+    }
+
+    public function id(string $id): self
+    {
+        $this->id = $id;
+        return $this;
+    }
+
+    public function wrapperProps(string ...$properties): self
+    {
+        $this->wrapperProperties = $properties;
+        return $this;
+    }
+
+    public function labelProps(string ...$properties): self
+    {
+        $this->labelProperties = $properties;
+        return $this;
+    }
+
+    public function inputProps(string ...$properties): self
+    {
+        $this->inputProperties = $properties;
+        return $this;
+    }
+
+    public function content(string|Stringable ...$content): self
+    {
+        $this->content = $content;
+        return $this;
+    }
+
+    private function warningMessage(string $warningId): string|PropertyInterface
+    {
+        if ($this->warningMessage === '') {
+            return '';
+        }
+
+        if (is_string($this->warningMessage)) {
+            return Element::p($this->warningMessage)->props(
+                'id ' . $warningId
+            );
+        }
+
+        $warning = clone $this->warningMessage;
+
+        return $warning->prop('id ' . $warningId);
+    }
+
+    public function __toString(): string
+    {
+        $textarea = Element::textarea(
+            "\n" . $this->value
+        )->props(...[
+            ...$this->inputProperties,
+            'id ' . $this->id,
+            'name ' . $this->name
+        ]);
+
+        $warning = '';
+        if ($this->warningMessage !== '') {
+            $warningId = $this->id . '-warning';
+
+            $textarea = $textarea->prop('aria-invalid true')->prop(
+                'aria-describedby ' . $warningId
+            );
+
+            $warning = (string) self::warningMessage($warningId);
+        }
+
+        return (string) Element::div(
+            Element::label($this->label)->props(...[
+                ...$this->labelProperties,
+                'for ' . $this->id
+            ]),
+            $textarea,
+            ...[...$this->content, $warning]
+        )->props(...$this->wrapperProperties);
+    }
+}
diff --git a/src/Forms/TextInput.php b/src/Forms/TextInput.php
index 9895b13..99c3af6 100644
--- a/src/Forms/TextInput.php
+++ b/src/Forms/TextInput.php
@@ -47,7 +47,7 @@ final private function __construct(
         private readonly string $value,
         private readonly string|PropertyInterface $warningMessage = ''
     ) {
-        $this->id = $name;
+        $this->id = (string) $name;
     }
 
     public function id(string $id): self
@@ -99,13 +99,13 @@ private function warningMessage(string $warningId): string|PropertyInterface
 
     public function __toString(): string
     {
-        $input = Element::input()->omitEndTag()->props(
+        $input = Element::input()->omitEndTag()->props(...[
+            ...$this->inputProperties,
             'type text',
             'id ' . $this->id,
             'name ' . $this->name,
-            'value ' . $this->value,
-            ...$this->inputProperties
-        );
+            'value ' . $this->value
+        ]);
 
         $warning = '';
         if ($this->warningMessage !== '') {
@@ -119,10 +119,10 @@ public function __toString(): string
         }
 
         return (string) Element::div(
-            Element::label($this->label)->props(
-                'for ' . $this->id,
-                ...$this->labelProperties
-            ),
+            Element::label($this->label)->props(...[
+                ...$this->labelProperties,
+                'for ' . $this->id
+            ]),
             $input,
             ...[...$this->content, $warning]
         )->props(...$this->wrapperProperties);
diff --git a/tests/ControlGuidanceTest.php b/tests/ControlGuidanceTest.php
new file mode 100644
index 0000000..785c736
--- /dev/null
+++ b/tests/ControlGuidanceTest.php
@@ -0,0 +1,221 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Eightfold\HtmlBuilder\Tests;
+
+use PHPUnit\Framework\Attributes\DataProvider;
+use PHPUnit\Framework\Attributes\Test;
+use PHPUnit\Framework\TestCase;
+
+use Dom\Element as DomElement;
+use Dom\HTMLDocument;
+use Dom\XPath;
+use Eightfold\HtmlBuilder\Element;
+use Eightfold\HtmlBuilder\Forms\EmailInput;
+use Eightfold\HtmlBuilder\Forms\Select;
+use Eightfold\HtmlBuilder\Forms\TextArea;
+use Eightfold\HtmlBuilder\Forms\TextInput;
+use Eightfold\HtmlBuilder\PropertyInterface;
+
+final class ControlGuidanceTest extends TestCase
+{
+    /** @return iterable<string, array{string}> */
+    public static function controls(): iterable
+    {
+        foreach (['text', 'email', 'textarea', 'dropdown', 'multiple', 'radio', 'checkbox'] as $mode) {
+            yield $mode => [$mode];
+        }
+    }
+
+    /**
+     * @return iterable<string, array{string, list<string>, string, list<string>}>
+     */
+    public static function guidanceCases(): iterable
+    {
+        $cases = [
+            'neither' => [[], '', []],
+            'help only' => [['aria-describedby field-help'], '', ['field-help']],
+            'warning only' => [[], 'Check the value.', ['field-warning']],
+            'help and warning' => [
+                ['aria-describedby field-help'],
+                'Check the value.',
+                ['field-help', 'field-warning']
+            ],
+            'multiple help IDs' => [
+                ['aria-describedby field-help field-format'],
+                'Check the value.',
+                ['field-help', 'field-format', 'field-warning']
+            ],
+            'irregular whitespace' => [
+                ["aria-describedby \tfield-help  \nfield-format\t"],
+                'Check the value.',
+                ['field-help', 'field-format', 'field-warning']
+            ],
+            'duplicate references' => [
+                ['aria-describedby field-help field-warning field-help'],
+                'Check the value.',
+                ['field-help', 'field-warning']
+            ],
+            'repeated properties' => [
+                ['aria-describedby field-help', 'aria-describedby field-format field-help'],
+                'Check the value.',
+                ['field-help', 'field-format', 'field-warning']
+            ],
+            'warning overrides valid state' => [
+                ['aria-invalid false', 'aria-describedby field-help'],
+                'Check the value.',
+                ['field-help', 'field-warning']
+            ]
+        ];
+
+        foreach (self::controls() as [$mode]) {
+            foreach ($cases as $case => [$properties, $warning, $ids]) {
+                yield $mode . ': ' . $case => [$mode, $properties, $warning, $ids];
+            }
+        }
+    }
+
+    /**
+     * @param list<string> $properties
+     * @param list<string> $expectedIds
+     */
+    #[Test]
+    #[DataProvider('guidanceCases')]
+    public function every_control_preserves_guidance_relationships(
+        string $mode,
+        array $properties,
+        string $warning,
+        array $expectedIds
+    ): void {
+        $html = self::render($mode, $warning, $properties);
+        self::assertGuidance($html, $mode, $expectedIds, $warning !== '');
+    }
+
+    #[Test]
+    #[DataProvider('controls')]
+    public function object_warnings_preserve_markup_and_are_rendered_once(string $mode): void
+    {
+        $warning = Element::div(
+            Element::a('Review guidance')->props('href /guidance/')
+        )->props('class custom-warning');
+
+        $html = self::render($mode, $warning, ['aria-describedby field-help']);
+        self::assertGuidance($html, $mode, ['field-help', 'field-warning'], true);
+        $xpath = self::xpath($html);
+        $warnings = $xpath->query(
+            '//*[local-name()="div" and @id="field-warning" and @class="custom-warning"]'
+        );
+        parent::assertNotFalse($warnings);
+        parent::assertCount(1, $warnings);
+        $links = $xpath->query(
+            './/*[local-name()="a" and @href="/guidance/"]',
+            $warnings->item(0)
+        );
+        parent::assertNotFalse($links);
+        parent::assertCount(1, $links);
+    }
+
+    #[Test]
+    #[DataProvider('controls')]
+    public function overridden_identity_drives_warning_associations(string $mode): void
+    {
+        $html = self::render($mode, 'Check the value.', ['aria-describedby field-help'], 'custom');
+        self::assertGuidance($html, $mode, ['field-help', 'custom-warning'], true, 'custom');
+    }
+
+    /**
+     * @param list<string> $properties
+     */
+    private static function render(
+        string $mode,
+        string|PropertyInterface $warning,
+        array $properties,
+        string $id = 'field'
+    ): string {
+        $control = match ($mode) {
+            'text' => TextInput::create('Field', 'field', '', $warning),
+            'email' => EmailInput::create('Field', 'field', '', $warning),
+            'textarea' => TextArea::create('Field', 'field', '', $warning),
+            'dropdown' => Select::create('Field', 'field', ['a' => 'A', 'b' => 'B'], [], $warning),
+            'multiple' => Select::create(
+                'Field', 'field', ['a' => 'A', 'b' => 'B'], [], $warning
+            )->multiple(),
+            'radio' => Select::create(
+                'Field', 'field', ['a' => 'A', 'b' => 'B'], [], $warning
+            )->radio(),
+            'checkbox' => Select::create(
+                'Field', 'field', ['a' => 'A', 'b' => 'B'], [], $warning
+            )->checkbox()
+        };
+
+        return (string) $control->id($id)
+            ->inputProps(...[...$properties, 'data-example preserved'])
+            ->content(
+                Element::p('Help')->props('id field-help'),
+                Element::p('Format')->props('id field-format')
+            );
+    }
+
+    /** @param list<string> $expectedIds */
+    private static function assertGuidance(
+        string $html,
+        string $mode,
+        array $expectedIds,
+        bool $hasWarning,
+        string $id = 'field'
+    ): void {
+        $xpath = self::xpath($html);
+        $controls = $xpath->query(
+            '//*[local-name()="input" or local-name()="select" or local-name()="textarea"]'
+        );
+        parent::assertNotFalse($controls);
+        parent::assertCount(in_array($mode, ['radio', 'checkbox'], true) ? 2 : 1, $controls);
+
+        $controlIds = [];
+        foreach ($controls as $control) {
+            parent::assertInstanceOf(DomElement::class, $control);
+            parent::assertSame('preserved', $control->getAttribute('data-example'));
+            if ($expectedIds === []) {
+                parent::assertFalse($control->hasAttribute('aria-describedby'));
+            } else {
+                parent::assertSame(
+                    $expectedIds,
+                    preg_split('/\s+/', trim($control->getAttribute('aria-describedby')))
+                );
+            }
+            if ($hasWarning) {
+                parent::assertSame('true', $control->getAttribute('aria-invalid'));
+            } else {
+                parent::assertFalse($control->hasAttribute('aria-invalid'));
+            }
+
+            $controlId = $control->getAttribute('id');
+            parent::assertNotSame('', $controlId);
+            $controlIds[] = $controlId;
+            $labels = $xpath->query(
+                '//*[local-name()="label" and @for="' . $controlId . '"]'
+            );
+            parent::assertNotFalse($labels);
+            parent::assertCount(1, $labels);
+        }
+        parent::assertCount(count($controlIds), array_unique($controlIds));
+
+        foreach ($expectedIds as $reference) {
+            $targets = $xpath->query('//*[@id="' . $reference . '"]');
+            parent::assertNotFalse($targets);
+            parent::assertCount(1, $targets);
+        }
+        $warnings = $xpath->query('//*[@id="' . $id . '-warning"]');
+        parent::assertNotFalse($warnings);
+        parent::assertCount($hasWarning ? 1 : 0, $warnings);
+    }
+
+    private static function xpath(string $html): XPath
+    {
+        return new XPath(HTMLDocument::createFromString(
+            '<!doctype html><html><head><title>Test</title></head><body>'
+                . $html . '</body></html>'
+        ));
+    }
+}

From acd681adbaf1bc6a98ac9a25b33891c038f48550 Mon Sep 17 00:00:00 2001
From: Josh Bruce <josh@8fold.pro>
Date: Thu, 15 Oct 2026 11:24:38 -0400
Subject: [PATCH 9/9] Fix control guidance references and clarify test failures

Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
---
 README.md                     | 13 +++++
 src/Forms/EmailInput.php      | 13 +++--
 src/Forms/TextArea.php        | 13 +++--
 src/Forms/TextInput.php       | 13 +++--
 tests/ControlGuidanceTest.php | 94 +++++++++++++++++++++++++++--------
 5 files changed, 110 insertions(+), 36 deletions(-)

diff --git a/README.md b/README.md
index 6217001..ced67e8 100644
--- a/README.md
+++ b/README.md
@@ -75,6 +75,19 @@ Output:
 <input required>
 ```
 
+## Form control guidance
+
+`TextInput`, `EmailInput`, `TextArea`, and all `Select` modes preserve help IDs
+supplied through `inputProps('aria-describedby help-id')` when adding a warning.
+With a warning, the control sets `aria-invalid="true"` and appends
+`<control-id>-warning` to `aria-describedby`, removing duplicate references while
+preserving their order. Use `content()` to supply the referenced help elements.
+Overriding the control's `id()` also changes its generated warning ID.
+
+`tests/ControlGuidanceTest.php` checks these relationships across control types.
+Assertion failures identify the relationship, control type and ID, and rendered
+HTML, alongside PHPUnit's named case and expected/actual diff.
+
 ## Performance
 
 The `/comparisons` folder can be used to run performance tests locally to compare the same output using:
diff --git a/src/Forms/EmailInput.php b/src/Forms/EmailInput.php
index dc3325c..4e3b4ee 100644
--- a/src/Forms/EmailInput.php
+++ b/src/Forms/EmailInput.php
@@ -99,8 +99,15 @@ private function warningMessage(string $warningId): string|PropertyInterface
 
     public function __toString(): string
     {
+        $inputProperties = $this->warningMessage === ''
+            ? $this->inputProperties
+            : ControlProperties::withWarning(
+                array_values($this->inputProperties),
+                $this->id . '-warning'
+            );
+
         $input = Element::input()->omitEndTag()->props(...[
-            ...$this->inputProperties,
+            ...$inputProperties,
             'type email',
             'id ' . $this->id,
             'name ' . $this->name,
@@ -113,10 +120,6 @@ public function __toString(): string
         if ($this->warningMessage !== '') {
             $warningId = $this->id . '-warning';
 
-            $input = $input->prop('aria-invalid true')->prop(
-                'aria-describedby ' . $warningId
-            );
-
             $warning = (string) self::warningMessage($warningId);
         }
 
diff --git a/src/Forms/TextArea.php b/src/Forms/TextArea.php
index 655afef..7f31420 100644
--- a/src/Forms/TextArea.php
+++ b/src/Forms/TextArea.php
@@ -99,10 +99,17 @@ private function warningMessage(string $warningId): string|PropertyInterface
 
     public function __toString(): string
     {
+        $inputProperties = $this->warningMessage === ''
+            ? $this->inputProperties
+            : ControlProperties::withWarning(
+                array_values($this->inputProperties),
+                $this->id . '-warning'
+            );
+
         $textarea = Element::textarea(
             "\n" . $this->value
         )->props(...[
-            ...$this->inputProperties,
+            ...$inputProperties,
             'id ' . $this->id,
             'name ' . $this->name
         ]);
@@ -111,10 +118,6 @@ public function __toString(): string
         if ($this->warningMessage !== '') {
             $warningId = $this->id . '-warning';
 
-            $textarea = $textarea->prop('aria-invalid true')->prop(
-                'aria-describedby ' . $warningId
-            );
-
             $warning = (string) self::warningMessage($warningId);
         }
 
diff --git a/src/Forms/TextInput.php b/src/Forms/TextInput.php
index 99c3af6..fb473dd 100644
--- a/src/Forms/TextInput.php
+++ b/src/Forms/TextInput.php
@@ -99,8 +99,15 @@ private function warningMessage(string $warningId): string|PropertyInterface
 
     public function __toString(): string
     {
+        $inputProperties = $this->warningMessage === ''
+            ? $this->inputProperties
+            : ControlProperties::withWarning(
+                array_values($this->inputProperties),
+                $this->id . '-warning'
+            );
+
         $input = Element::input()->omitEndTag()->props(...[
-            ...$this->inputProperties,
+            ...$inputProperties,
             'type text',
             'id ' . $this->id,
             'name ' . $this->name,
@@ -111,10 +118,6 @@ public function __toString(): string
         if ($this->warningMessage !== '') {
             $warningId = $this->id . '-warning';
 
-            $input = $input->prop('aria-invalid true')->prop(
-                'aria-describedby ' . $warningId
-            );
-
             $warning = (string) self::warningMessage($warningId);
         }
 
diff --git a/tests/ControlGuidanceTest.php b/tests/ControlGuidanceTest.php
index 785c736..8bf5c6c 100644
--- a/tests/ControlGuidanceTest.php
+++ b/tests/ControlGuidanceTest.php
@@ -106,14 +106,23 @@ public function object_warnings_preserve_markup_and_are_rendered_once(string $mo
         $warnings = $xpath->query(
             '//*[local-name()="div" and @id="field-warning" and @class="custom-warning"]'
         );
-        parent::assertNotFalse($warnings);
-        parent::assertCount(1, $warnings);
+        $context = $mode . " control.\nRendered HTML:\n" . $html;
+        parent::assertNotFalse($warnings, 'Could not query object warnings for ' . $context);
+        parent::assertCount(
+            1,
+            $warnings,
+            'Expected exactly one warning div preserving class="custom-warning" for ' . $context
+        );
         $links = $xpath->query(
             './/*[local-name()="a" and @href="/guidance/"]',
             $warnings->item(0)
         );
-        parent::assertNotFalse($links);
-        parent::assertCount(1, $links);
+        parent::assertNotFalse($links, 'Could not query warning links for ' . $context);
+        parent::assertCount(
+            1,
+            $links,
+            'Expected the warning to preserve its link to /guidance/ for ' . $context
+        );
     }
 
     #[Test]
@@ -165,50 +174,93 @@ private static function assertGuidance(
         bool $hasWarning,
         string $id = 'field'
     ): void {
+        $context = $mode . " control.\nRendered HTML:\n" . $html;
         $xpath = self::xpath($html);
         $controls = $xpath->query(
             '//*[local-name()="input" or local-name()="select" or local-name()="textarea"]'
         );
-        parent::assertNotFalse($controls);
-        parent::assertCount(in_array($mode, ['radio', 'checkbox'], true) ? 2 : 1, $controls);
+        parent::assertNotFalse($controls, 'Could not query controls for ' . $context);
+        parent::assertCount(
+            in_array($mode, ['radio', 'checkbox'], true) ? 2 : 1,
+            $controls,
+            'Expected one control, or two option inputs for radio/checkbox groups, for ' . $context
+        );
 
         $controlIds = [];
-        foreach ($controls as $control) {
-            parent::assertInstanceOf(DomElement::class, $control);
-            parent::assertSame('preserved', $control->getAttribute('data-example'));
+        foreach ($controls as $index => $control) {
+            parent::assertInstanceOf(DomElement::class, $control, 'Expected a DOM element for ' . $context);
+            $controlContext = sprintf(
+                'Option/control %d (id="%s") in %s',
+                $index + 1,
+                $control->getAttribute('id'),
+                $context
+            );
+            parent::assertSame(
+                'preserved',
+                $control->getAttribute('data-example'),
+                'inputProps() must preserve unrelated attributes. ' . $controlContext
+            );
             if ($expectedIds === []) {
-                parent::assertFalse($control->hasAttribute('aria-describedby'));
+                parent::assertFalse(
+                    $control->hasAttribute('aria-describedby'),
+                    'Without help references or a warning, aria-describedby must be absent. ' . $controlContext
+                );
             } else {
                 parent::assertSame(
                     $expectedIds,
-                    preg_split('/\s+/', trim($control->getAttribute('aria-describedby')))
+                    preg_split('/\s+/', trim($control->getAttribute('aria-describedby'))),
+                    'aria-describedby must preserve help IDs and append the warning ID once, in order. '
+                        . $controlContext
                 );
             }
             if ($hasWarning) {
-                parent::assertSame('true', $control->getAttribute('aria-invalid'));
+                parent::assertSame(
+                    'true',
+                    $control->getAttribute('aria-invalid'),
+                    'A warning must set aria-invalid="true", overriding any supplied valid state. ' . $controlContext
+                );
             } else {
-                parent::assertFalse($control->hasAttribute('aria-invalid'));
+                parent::assertFalse(
+                    $control->hasAttribute('aria-invalid'),
+                    'Without a warning or explicit invalid state, aria-invalid must be absent. ' . $controlContext
+                );
             }
 
             $controlId = $control->getAttribute('id');
-            parent::assertNotSame('', $controlId);
+            parent::assertNotSame('', $controlId, 'Each control needs a nonempty ID. ' . $controlContext);
             $controlIds[] = $controlId;
             $labels = $xpath->query(
                 '//*[local-name()="label" and @for="' . $controlId . '"]'
             );
-            parent::assertNotFalse($labels);
-            parent::assertCount(1, $labels);
+            parent::assertNotFalse($labels, 'Could not query associated labels. ' . $controlContext);
+            parent::assertCount(
+                1,
+                $labels,
+                'Expected exactly one label with for="' . $controlId . '". ' . $controlContext
+            );
         }
-        parent::assertCount(count($controlIds), array_unique($controlIds));
+        parent::assertCount(
+            count($controlIds),
+            array_unique($controlIds),
+            'Controls must have unique IDs so labels target the correct input. ' . $context
+        );
 
         foreach ($expectedIds as $reference) {
             $targets = $xpath->query('//*[@id="' . $reference . '"]');
-            parent::assertNotFalse($targets);
-            parent::assertCount(1, $targets);
+            parent::assertNotFalse($targets, 'Could not query guidance target "' . $reference . '" for ' . $context);
+            parent::assertCount(
+                1,
+                $targets,
+                'aria-describedby reference "' . $reference . '" must resolve to exactly one element for ' . $context
+            );
         }
         $warnings = $xpath->query('//*[@id="' . $id . '-warning"]');
-        parent::assertNotFalse($warnings);
-        parent::assertCount($hasWarning ? 1 : 0, $warnings);
+        parent::assertNotFalse($warnings, 'Could not query warning target "' . $id . '-warning" for ' . $context);
+        parent::assertCount(
+            $hasWarning ? 1 : 0,
+            $warnings,
+            'Expected ' . ($hasWarning ? 'exactly one' : 'no') . ' warning with id="' . $id . '-warning" for ' . $context
+        );
     }
 
     private static function xpath(string $html): XPath