@agentero/design-system 0.29.1 → 0.31.0

package/mcp/manifests/components.html

@@ -588,13 +588,13 @@
 <header>
   <div class="wrap">
     <h1>Manifest Debugger</h1>
-    <div class="summary"><a class="filter-pill all" data-k="all" href="#filter-all">All</a><span class="filter-pill ok" aria-disabled="true">31 components ok</span><span class="filter-pill ok" aria-disabled="true">250 stories ok</span></div>
+    <div class="summary"><a class="filter-pill all" data-k="all" href="#filter-all">All</a><span class="filter-pill ok" aria-disabled="true">33 components ok</span><span class="filter-pill ok" aria-disabled="true">263 stories ok</span></div>
   </div>
 </header>
 <main>
   <div class="wrap">
     <div class="note ok" style="margin-bottom: 16px;">
-              Using <code>react-component-meta</code>. Generation took <strong>4.3s</strong>.
+              Using <code>react-component-meta</code>. Generation took <strong>3.4s</strong>.
             </div>
     <h2 class="section-title">Components</h2>
     <div class="grid" role="list">
@@ -2811,6 +2811,492 @@ import { CheckList } from &#39;@agentero/design-system/check-list&#39;;
         </div>
     
     
+  </div>
+</article>
+<article
+  class="card 
+  no-error 
+  no-info 
+  no-story-error
+  no-doc-error"
+  role="listitem"
+  aria-label="Combobox.Root">
+  <div class="head">
+    <div class="title">
+      <h2><span class="status-dot dot-ok"></span> Combobox.Root</h2>
+      <div class="badges">
+        <label for="c-7-components-combobox-props" class="badge ok as-toggle">38 prop types</label>
+        
+        <label for="c-7-components-combobox-stories" class="badge ok as-toggle">7 stories</label>
+        
+        
+      </div>
+    </div>
+    <div class="meta" title="./src/combobox/combobox.stories.tsx">components-combobox · ./src/combobox/combobox.stories.tsx</div>
+    <div>Root provider for an input-triggered filterable list</div>
+    <div class="hint">Combobox is a text input that filters a list and writes the chosen option back
+into itself. Focusing the input or typing opens the list; picking a row fills the
+input and closes it. Built on Base UI, whose Combobox primitive owns the
+filtering, the keyboard navigation and the `role=&quot;combobox&quot;` wiring.</div>
+    <div class="kv"><span class="chip">summary: Root provider for an input-triggered filterable list</span><span class="chip">see: {@link https://base-ui.com/react/components/combobox Base UI Combobox}</span><span class="chip">example: ```tsx
+import { Combobox } from &#39;@agentero/design-system/combobox&#39;;
+
+&lt;Combobox.Root items={states}&gt;
+  &lt;Combobox.Input placeholder=&quot;Search states&quot; /&gt;
+  &lt;Combobox.Content&gt;
+    &lt;Combobox.Empty&gt;No matches found&lt;/Combobox.Empty&gt;
+    &lt;Combobox.List&gt;
+      {(state: string) =&gt; &lt;Combobox.Item key={state} value={state}&gt;{state}&lt;/Combobox.Item&gt;}
+    &lt;/Combobox.List&gt;
+  &lt;/Combobox.Content&gt;
+&lt;/Combobox.Root&gt;
+```</span></div>
+  </div>
+
+  <!-- ⬇️ Hidden toggles must be siblings BEFORE .panels -->
+  
+  
+  <input id="c-7-components-combobox-stories" class="tg tg-stories" type="checkbox" hidden />
+  
+  
+  <input id="c-7-components-combobox-props" class="tg tg-props" type="checkbox" hidden />
+
+  <div class="panels">
+    
+    
+    
+        <div class="panel panel-props">
+          <div class="note ok">
+            <div class="row">
+              <span class="ex-name">Prop types <small>(react-component-meta)</small></span>
+              <span class="badge ok">38 prop types</span>
+            </div>
+            <pre><code>Component: src/combobox/index.ts::Combobox</code></pre>
+            <pre><code>Props:</code></pre>
+            <pre><code>/**
+ * A ref to imperative actions.
+ * - `unmount`: Manually unmounts the combobox.
+ * Call this after any externally controlled closing animation finishes.
+ */
+actionsRef?: RefObject&lt;Actions | null&gt;
+
+/**
+ * Provides a hint to the browser for autofill.
+ */
+autoComplete?: string
+
+/**
+ * Whether the first matching item is highlighted automatically while filtering.
+ */
+autoHighlight?: boolean = false
+
+children?: ReactNode
+
+/**
+ * The uncontrolled input value when initially rendered.
+ * 
+ * To render a controlled input, use the `inputValue` prop instead.
+ */
+defaultInputValue?: string | number | readonly string[] | undefined
+
+/**
+ * Whether the popup is initially open.
+ * 
+ * To render a controlled popup, use the `open` prop instead.
+ */
+defaultOpen?: boolean = false
+
+/**
+ * The uncontrolled selected value of the combobox when it&#39;s initially rendered.
+ * 
+ * To render a controlled combobox, use the `value` prop instead.
+ */
+defaultValue?: unknown
+
+/**
+ * Whether the component should ignore user interaction.
+ */
+disabled?: boolean = false
+
+/**
+ * Filter function used to match items vs input query.
+ * Receives the source item, which is the derived value&#39;s item when `items` is a `createItems()`
+ * collection, and the item itself otherwise.
+ */
+filter?: ((item: unknown, query: string, itemToString?: ((item: unknown) =&gt; string) | undefined) =&gt; boolean) | null | undefined
+
+/**
+ * Filtered items to display in the list.
+ * When provided, the list uses these items instead of filtering the `items` prop internally.
+ * When `items` is also provided, this array must preserve its flat or grouped structure.
+ * With a `createItems()` collection, pass source items rather than derived values.
+ * Nullish entries are not supported, as in `items`.
+ * Use when you want to control filtering logic externally with the `useFilter()` hook.
+ */
+filteredItems?: readonly unknown[] | readonly Group&lt;unknown&gt;[] | undefined
+
+/**
+ * Identifies the form that owns the internal input.
+ * Useful when the combobox is rendered outside the form.
+ */
+form?: string
+
+/**
+ * Whether list items are presented in a grid layout.
+ * When enabled, arrow keys navigate across rows and columns inferred from DOM rows.
+ */
+grid?: boolean = false
+
+/**
+ * Whether moving the pointer over items should highlight them.
+ * Disabling this prop allows CSS `:hover` to be differentiated from the `:focus` (`data-highlighted`) state.
+ */
+highlightItemOnHover?: boolean = true
+
+/**
+ * The id of the component.
+ */
+id?: string
+
+/**
+ * Whether the list is rendered inline without using the component&#39;s own popup.
+ * 
+ * Specify `open` unconditionally in conjunction with this prop so the list is considered
+ * visible: `&lt;Combobox.Root inline open&gt;`
+ * 
+ * In a `Combobox.Root` &gt; `Dialog.Root` composition, bind the Combobox&#39;s `open` and
+ * `onOpenChange` props to the `Dialog`&#39;s `open` and `onOpenChange` state instead so the
+ * component resets its transient state (filter query, highlighted item, and input value) when
+ * the dialog closes.
+ */
+inline?: boolean = false
+
+/**
+ * A ref to the hidden input element.
+ */
+inputRef?: Ref&lt;HTMLInputElement&gt; | undefined
+
+/**
+ * The input value of the combobox. Use when controlled.
+ */
+inputValue?: string | number | readonly string[] | undefined
+
+/**
+ * Custom comparison logic used to determine if a combobox item value matches the current selected value. Useful when item values are objects without matching referentially.
+ * With a `createItems()` collection, both arguments are derived values.
+ * Defaults to `Object.is` comparison.
+ */
+isItemEqualToValue?: (itemValue: unknown, value: unknown) =&gt; boolean
+
+/**
+ * The items to be displayed in the list.
+ * Can be a flat array of items, an array of groups with items, or a collection created by
+ * the `createItems()` function, which derives each item&#39;s selection value and label.
+ * Nullish entries are not supported: remove them from the data before passing it.
+ */
+items?: readonly any[] | readonly Group&lt;any&gt;[] | ComboboxItemCollection&lt;unknown, unknown&gt; | undefined
+
+/**
+ * When the item values are objects (`&lt;Combobox.Item value={object}&gt;`), this function converts the object value to a string representation for display in the input.
+ * If the shape of the object is `{ value, label }`, the label will be used automatically without needing to specify this prop.
+ * With a `createItems()` collection, this receives the derived value, and the collection&#39;s
+ * `getLabel` takes precedence for values it can resolve.
+ */
+itemToStringLabel?: (itemValue: unknown) =&gt; string
+
+/**
+ * When the item values are objects (`&lt;Combobox.Item value={object}&gt;`), this function converts the object value to a string representation for form submission.
+ * If the shape of the object is `{ value, label }`, the value will be used automatically without needing to specify this prop.
+ * With a `createItems()` collection, this receives the derived value.
+ */
+itemToStringValue?: (itemValue: unknown) =&gt; string
+
+/**
+ * The maximum number of items to display in the list.
+ */
+limit?: number = -1
+
+/**
+ * The locale to use for string comparison.
+ * Defaults to the user&#39;s runtime locale.
+ */
+locale?: LocalesArgument
+
+/**
+ * Whether to loop keyboard focus back to the input when the end of the list is reached while using the arrow keys. The first item can then be reached by pressing &lt;kbd&gt;ArrowDown&lt;/kbd&gt; again from the input, or the last item can be reached by pressing &lt;kbd&gt;ArrowUp&lt;/kbd&gt; from the input.
+ * The input is always included in the focus loop per [ARIA Authoring Practices](https://www.w3.org/WAI/ARIA/apg/patterns/combobox/).
+ * When disabled, focus does not move when on the last element and the user presses &lt;kbd&gt;ArrowDown&lt;/kbd&gt;, or when on the first element and the user presses &lt;kbd&gt;ArrowUp&lt;/kbd&gt;.
+ */
+loopFocus?: boolean = true
+
+/**
+ * Determines if the popup enters a modal state when open.
+ * - `true`: user interaction is limited to the popup: document page scroll is locked and pointer interactions on outside elements are disabled.
+ * - `false`: user interaction with the rest of the document is allowed.
+ * 
+ * On touch devices, a `true` modal blocks outside taps but leaves the page scrollable unless the popup spans nearly the full viewport width, matching native iOS behavior.
+ */
+modal?: boolean = false
+
+/**
+ * Whether multiple items can be selected.
+ */
+multiple?: false = false
+
+/**
+ * Identifies the field when a form is submitted.
+ */
+name?: string
+
+/**
+ * Event handler called when the input value changes.
+ */
+onInputValueChange?: (inputValue: string, eventDetails: ChangeEventDetails) =&gt; void
+
+/**
+ * Callback fired when an item is highlighted or unhighlighted.
+ * Receives the highlighted item value (or `undefined` if no item is highlighted) and event details with a `reason` property describing why the highlight changed.
+ * The `reason` can be:
+ * - `&#39;keyboard&#39;`: the highlight changed due to keyboard navigation.
+ * - `&#39;pointer&#39;`: the highlight changed due to pointer hovering.
+ * - `&#39;none&#39;`: the highlight changed programmatically.
+ */
+onItemHighlighted?: (highlightedValue: unknown, eventDetails: HighlightEventDetails) =&gt; void
+
+/**
+ * Event handler called when the popup is opened or closed.
+ */
+onOpenChange?: (open: boolean, eventDetails: ChangeEventDetails) =&gt; void
+
+/**
+ * Event handler called after any animations complete when the popup is opened or closed.
+ */
+onOpenChangeComplete?: (open: boolean) =&gt; void
+
+/**
+ * Event handler called when the selected value of the combobox changes.
+ */
+onValueChange?: (value: unknown, eventDetails: ChangeEventDetails) =&gt; void
+
+/**
+ * Whether the popup is currently open. Use when controlled.
+ */
+open?: boolean
+
+/**
+ * Whether the popup opens when clicking the input.
+ */
+openOnInputClick?: boolean = true
+
+/**
+ * Whether the user should be unable to choose a different option from the popup.
+ */
+readOnly?: boolean = false
+
+/**
+ * Whether the user must choose a value before submitting a form.
+ */
+required?: boolean = false
+
+/**
+ * The selected value of the combobox. Use when controlled.
+ */
+value?: unknown
+
+/**
+ * Whether the items are being externally virtualized.
+ */
+virtualized?: boolean = false</code></pre>
+          </div>
+        </div>
+    
+        <div class="panel panel-stories">
+          
+          
+          
+          <div class="note ok">
+                <div class="row">
+                  <span class="ex-name">Imports</span>
+                </div>
+                <pre><code>import { Button, Combobox, Field, FieldText, IconSearch, Label, Modal, Skeleton } from "@agentero/design-system";
+import { Suspense } from "react";</code></pre>
+              </div>
+          
+          
+            <div class="note ok">
+              <div class="row">
+                <span class="ex-name">Default</span>
+                <span class="badge ok">story ok</span>
+              </div>
+              
+              <div class="hint">The common case: options are already in memory and Base UI filters them against
+what you type. Selecting a row fills the input and closes the list.</div>
+              <pre><code>const Default = () =&gt; (
+    &lt;Combobox.Root items={STATES}&gt;
+        &lt;Combobox.Input placeholder=&quot;Search states&quot; aria-label=&quot;Search states&quot; /&gt;
+        &lt;Combobox.Content&gt;
+            &lt;Combobox.Empty&gt;No matches found&lt;/Combobox.Empty&gt;
+            &lt;Combobox.List&gt;
+                {(state: string) =&gt; (
+                    &lt;Combobox.Item key={state} value={state}&gt;
+                        {state}
+                    &lt;/Combobox.Item&gt;
+                )}
+            &lt;/Combobox.List&gt;
+        &lt;/Combobox.Content&gt;
+    &lt;/Combobox.Root&gt;
+);</code></pre>
+            </div>
+            <div class="note ok">
+              <div class="row">
+                <span class="ex-name">No Matches</span>
+                <span class="badge ok">story ok</span>
+              </div>
+              
+              <div class="hint">`Empty` stays mounted so screen readers announce the change; it renders its
+children only while nothing matches. It needs `items` on `Root` to know that.</div>
+              <pre><code>const NoMatches = () =&gt; (
+    &lt;Combobox.Root items={STATES}&gt;
+        &lt;Combobox.Input placeholder=&quot;Search states&quot; aria-label=&quot;Search states&quot; /&gt;
+        &lt;Combobox.Content&gt;
+            &lt;Combobox.Empty&gt;No matches found&lt;/Combobox.Empty&gt;
+            &lt;Combobox.List&gt;
+                {(state: string) =&gt; (
+                    &lt;Combobox.Item key={state} value={state}&gt;
+                        {state}
+                    &lt;/Combobox.Item&gt;
+                )}
+            &lt;/Combobox.List&gt;
+        &lt;/Combobox.Content&gt;
+    &lt;/Combobox.Root&gt;
+);</code></pre>
+            </div>
+            <div class="note ok">
+              <div class="row">
+                <span class="ex-name">Async Search</span>
+                <span class="badge ok">story ok</span>
+              </div>
+              
+              <div class="hint">Options fetched as you type, the way the apps load data: the rows are a component
+that suspends on the request, so a `Suspense` boundary inside `Content` shows
+placeholder rows until they land. Nothing tracks `loading` by hand and no stale
+list lingers under the wait: the data is read by query, which is also what makes
+out-of-order responses harmless. Drop a `useSuspenseQuery` where `use()` is.</div>
+              <pre><code>const AsyncSearch = () =&gt; &lt;SuspenseSearch /&gt;;</code></pre>
+            </div>
+            <div class="note ok">
+              <div class="row">
+                <span class="ex-name">Async Search With Status</span>
+                <span class="badge ok">story ok</span>
+              </div>
+              
+              <div class="hint">The same search without Suspense, for a consumer that gets a `loading` flag from
+its data layer instead: `filter={null}`, the rows arrive through `filteredItems`,
+`Content` is marked busy and `Status` announces the wait. The list is cleared
+before each request and a request that is no longer the latest is dropped.</div>
+              <pre><code>const AsyncSearchWithStatus = () =&gt; &lt;StatusSearch /&gt;;</code></pre>
+            </div>
+            <div class="note ok">
+              <div class="row">
+                <span class="ex-name">Inside Field Text</span>
+                <span class="badge ok">story ok</span>
+              </div>
+              
+              <div class="hint">Dropped into a `FieldText`, the input takes the label, the description and
+the error from the field with nothing wired by hand: `Combobox.Input` reads the
+same `InputContext` the plain `Input` does.</div>
+              <pre><code>const InsideFieldText = () =&gt; (
+    &lt;FieldText invalid required&gt;
+        &lt;Label&gt;Agency&lt;/Label&gt;
+        &lt;Combobox.Root items={STATES}&gt;
+            &lt;Combobox.Input placeholder=&quot;Search agencies&quot; /&gt;
+            &lt;Combobox.Content&gt;
+                &lt;Combobox.Empty&gt;No matches found&lt;/Combobox.Empty&gt;
+                &lt;Combobox.List&gt;
+                    {(state: string) =&gt; (
+                        &lt;Combobox.Item key={state} value={state}&gt;
+                            {state}
+                        &lt;/Combobox.Item&gt;
+                    )}
+                &lt;/Combobox.List&gt;
+            &lt;/Combobox.Content&gt;
+        &lt;/Combobox.Root&gt;
+        &lt;Field.Description&gt;The agency this agent will be added to.&lt;/Field.Description&gt;
+        &lt;Field.Error errors={[{ message: &#39;Pick an agency from the list&#39; }]} /&gt;
+    &lt;/FieldText&gt;
+);</code></pre>
+            </div>
+            <div class="note ok">
+              <div class="row">
+                <span class="ex-name">With Leading Icon</span>
+                <span class="badge ok">story ok</span>
+              </div>
+              
+              <div class="hint">A leading icon is composed around the input, not baked in: not every combobox
+is a search (a FEIN lookup or a template picker are not), so the component
+ships no icon of its own. Until `InputGroup` lands in the design system, the
+marketplace search fields get theirs like this — the icon overlaid, the input
+padded past it.</div>
+              <pre><code>const WithLeadingIcon = () =&gt; (
+    &lt;Combobox.Root items={STATES}&gt;
+        &lt;div className=&quot;relative&quot;&gt;
+            &lt;IconSearch
+                aria-hidden
+                className=&quot;pointer-events-none absolute top-1/2 left-3 z-1 size-6 -translate-y-1/2 [&amp;&gt;path]:fill-icon-default-base-tertiary&quot;
+            /&gt;
+            &lt;Combobox.Input className=&quot;pl-11&quot; placeholder=&quot;Search states&quot; aria-label=&quot;Search states&quot; /&gt;
+        &lt;/div&gt;
+        &lt;Combobox.Content&gt;
+            &lt;Combobox.Empty&gt;No matches found&lt;/Combobox.Empty&gt;
+            &lt;Combobox.List&gt;
+                {(state: string) =&gt; (
+                    &lt;Combobox.Item key={state} value={state}&gt;
+                        {state}
+                    &lt;/Combobox.Item&gt;
+                )}
+            &lt;/Combobox.List&gt;
+        &lt;/Combobox.Content&gt;
+    &lt;/Combobox.Root&gt;
+);</code></pre>
+            </div>
+            <div class="note ok">
+              <div class="row">
+                <span class="ex-name">Inside Modal</span>
+                <span class="badge ok">story ok</span>
+              </div>
+              
+              <div class="hint">Inside a `Modal`, which is a Radix Dialog. The surface portals to the body, so
+this checks that the dialog&#39;s modal layer neither blocks pointer events on the
+list nor treats a click in it as a click outside and closes.</div>
+              <pre><code>const InsideModal = () =&gt; (
+    &lt;Modal.Root&gt;
+        &lt;Modal.Trigger asChild&gt;
+            &lt;Button variant=&quot;secondary&quot;&gt;Assign agency&lt;/Button&gt;
+        &lt;/Modal.Trigger&gt;
+        &lt;Modal.Content&gt;
+            &lt;Modal.Title&gt;Assign agency&lt;/Modal.Title&gt;
+            &lt;Modal.Body&gt;
+                &lt;Combobox.Root items={STATES}&gt;
+                    &lt;Combobox.Input placeholder=&quot;Search states&quot; aria-label=&quot;Search states&quot; /&gt;
+                    &lt;Combobox.Content&gt;
+                        &lt;Combobox.Empty&gt;No matches found&lt;/Combobox.Empty&gt;
+                        &lt;Combobox.List&gt;
+                            {(state: string) =&gt; (
+                                &lt;Combobox.Item key={state} value={state}&gt;
+                                    {state}
+                                &lt;/Combobox.Item&gt;
+                            )}
+                        &lt;/Combobox.List&gt;
+                    &lt;/Combobox.Content&gt;
+                &lt;/Combobox.Root&gt;
+            &lt;/Modal.Body&gt;
+        &lt;/Modal.Content&gt;
+    &lt;/Modal.Root&gt;
+);</code></pre>
+            </div>
+        </div>
+    
+    
   </div>
 </article>
 <article
@@ -2825,9 +3311,9 @@ import { CheckList } from &#39;@agentero/design-system/check-list&#39;;
     <div class="title">
       <h2><span class="status-dot dot-ok"></span> Command.Root</h2>
       <div class="badges">
-        <label for="c-7-components-command-props" class="badge ok as-toggle">10 prop types</label>
+        <label for="c-8-components-command-props" class="badge ok as-toggle">10 prop types</label>
         
-        <label for="c-7-components-command-stories" class="badge ok as-toggle">6 stories</label>
+        <label for="c-8-components-command-stories" class="badge ok as-toggle">6 stories</label>
         
         
       </div>
@@ -2860,10 +3346,10 @@ import { Command } from &#39;@agentero/design-system/command&#39;;
   <!-- ⬇️ Hidden toggles must be siblings BEFORE .panels -->
   
   
-  <input id="c-7-components-command-stories" class="tg tg-stories" type="checkbox" hidden />
+  <input id="c-8-components-command-stories" class="tg tg-stories" type="checkbox" hidden />
   
   
-  <input id="c-7-components-command-props" class="tg tg-props" type="checkbox" hidden />
+  <input id="c-8-components-command-props" class="tg tg-props" type="checkbox" hidden />
 
   <div class="panels">
     
@@ -3077,9 +3563,9 @@ list does not invite the pointer.</div>
     <div class="title">
       <h2><span class="status-dot dot-ok"></span> DataTable.Root</h2>
       <div class="badges">
-        <label for="c-8-components-datatable-props" class="badge ok as-toggle">88 prop types</label>
+        <label for="c-9-components-datatable-props" class="badge ok as-toggle">88 prop types</label>
         
-        <label for="c-8-components-datatable-stories" class="badge ok as-toggle">4 stories</label>
+        <label for="c-9-components-datatable-stories" class="badge ok as-toggle">4 stories</label>
         
         
       </div>
@@ -3122,10 +3608,10 @@ const columns = [
   <!-- ⬇️ Hidden toggles must be siblings BEFORE .panels -->
   
   
-  <input id="c-8-components-datatable-stories" class="tg tg-stories" type="checkbox" hidden />
+  <input id="c-9-components-datatable-stories" class="tg tg-stories" type="checkbox" hidden />
   
   
-  <input id="c-8-components-datatable-props" class="tg tg-props" type="checkbox" hidden />
+  <input id="c-9-components-datatable-props" class="tg tg-props" type="checkbox" hidden />
 
   <div class="panels">
     
@@ -3703,9 +4189,9 @@ in flight.</div>
     <div class="title">
       <h2><span class="status-dot dot-ok"></span> Divider</h2>
       <div class="badges">
-        <label for="c-9-components-divider-props" class="badge ok as-toggle">4 prop types</label>
+        <label for="c-10-components-divider-props" class="badge ok as-toggle">4 prop types</label>
         
-        <label for="c-9-components-divider-stories" class="badge ok as-toggle">10 stories</label>
+        <label for="c-10-components-divider-stories" class="badge ok as-toggle">10 stories</label>
         
         
       </div>
@@ -3728,10 +4214,10 @@ When omitted, Divider renders a single line.</span><span class="chip">example: &
   <!-- ⬇️ Hidden toggles must be siblings BEFORE .panels -->
   
   
-  <input id="c-9-components-divider-stories" class="tg tg-stories" type="checkbox" hidden />
+  <input id="c-10-components-divider-stories" class="tg tg-stories" type="checkbox" hidden />
   
   
-  <input id="c-9-components-divider-props" class="tg tg-props" type="checkbox" hidden />
+  <input id="c-10-components-divider-props" class="tg tg-props" type="checkbox" hidden />
 
   <div class="panels">
     
@@ -4034,9 +4520,9 @@ related controls or inline links without visual weight.</div>
     <div class="title">
       <h2><span class="status-dot dot-ok"></span> DropdownMenu.Root</h2>
       <div class="badges">
-        <label for="c-10-components-dropdownmenu-props" class="badge ok as-toggle">6 prop types</label>
+        <label for="c-11-components-dropdownmenu-props" class="badge ok as-toggle">6 prop types</label>
         
-        <label for="c-10-components-dropdownmenu-stories" class="badge ok as-toggle">7 stories</label>
+        <label for="c-11-components-dropdownmenu-stories" class="badge ok as-toggle">7 stories</label>
         
         
       </div>
@@ -4095,10 +4581,10 @@ import { DropdownMenu } from &#39;@agentero/design-system/dropdown-menu&#39;;
   <!-- ⬇️ Hidden toggles must be siblings BEFORE .panels -->
   
   
-  <input id="c-10-components-dropdownmenu-stories" class="tg tg-stories" type="checkbox" hidden />
+  <input id="c-11-components-dropdownmenu-stories" class="tg tg-stories" type="checkbox" hidden />
   
   
-  <input id="c-10-components-dropdownmenu-props" class="tg tg-props" type="checkbox" hidden />
+  <input id="c-11-components-dropdownmenu-props" class="tg tg-props" type="checkbox" hidden />
 
   <div class="panels">
     
@@ -4501,9 +4987,9 @@ actions outright unless the user needs to see them and understand why.</div>
     <div class="title">
       <h2><span class="status-dot dot-ok"></span> Field.Root</h2>
       <div class="badges">
-        <label for="c-11-components-field-props" class="badge ok as-toggle">6 prop types</label>
+        <label for="c-12-components-field-props" class="badge ok as-toggle">6 prop types</label>
         
-        <label for="c-11-components-field-stories" class="badge ok as-toggle">16 stories</label>
+        <label for="c-12-components-field-stories" class="badge ok as-toggle">16 stories</label>
         
         
       </div>
@@ -4535,10 +5021,10 @@ absent when there is none.</div>
   <!-- ⬇️ Hidden toggles must be siblings BEFORE .panels -->
   
   
-  <input id="c-11-components-field-stories" class="tg tg-stories" type="checkbox" hidden />
+  <input id="c-12-components-field-stories" class="tg tg-stories" type="checkbox" hidden />
   
   
-  <input id="c-11-components-field-props" class="tg tg-props" type="checkbox" hidden />
+  <input id="c-12-components-field-props" class="tg tg-props" type="checkbox" hidden />
 
   <div class="panels">
     
@@ -4988,9 +5474,9 @@ form library. `InputContext` extends the same way with `value`, `onChange`,
     <div class="title">
       <h2><span class="status-dot dot-ok"></span> FieldText</h2>
       <div class="badges">
-        <label for="c-12-components-fieldtext-props" class="badge ok as-toggle">6 prop types</label>
+        <label for="c-13-components-fieldtext-props" class="badge ok as-toggle">6 prop types</label>
         
-        <label for="c-12-components-fieldtext-stories" class="badge ok as-toggle">7 stories</label>
+        <label for="c-13-components-fieldtext-stories" class="badge ok as-toggle">7 stories</label>
         
         
       </div>
@@ -5017,10 +5503,10 @@ and `name`, and `FieldContext` with the errors, as the last story shows.</div>
   <!-- ⬇️ Hidden toggles must be siblings BEFORE .panels -->
   
   
-  <input id="c-12-components-fieldtext-stories" class="tg tg-stories" type="checkbox" hidden />
+  <input id="c-13-components-fieldtext-stories" class="tg tg-stories" type="checkbox" hidden />
   
   
-  <input id="c-12-components-fieldtext-props" class="tg tg-props" type="checkbox" hidden />
+  <input id="c-13-components-fieldtext-props" class="tg tg-props" type="checkbox" hidden />
 
   <div class="panels">
     
@@ -5236,9 +5722,9 @@ The input&#39;s own `onChange` still runs, chained after the provider&#39;s.</di
     <div class="title">
       <h2><span class="status-dot dot-ok"></span> Form.Root</h2>
       <div class="badges">
-        <label for="c-13-components-form-props" class="badge ok as-toggle">3 prop types</label>
+        <label for="c-14-components-form-props" class="badge ok as-toggle">3 prop types</label>
         
-        <label for="c-13-components-form-stories" class="badge ok as-toggle">2 stories</label>
+        <label for="c-14-components-form-stories" class="badge ok as-toggle">2 stories</label>
         
         
       </div>
@@ -5267,10 +5753,10 @@ keep a single copy, since the provider and the fields share one context.</div>
   <!-- ⬇️ Hidden toggles must be siblings BEFORE .panels -->
   
   
-  <input id="c-13-components-form-stories" class="tg tg-stories" type="checkbox" hidden />
+  <input id="c-14-components-form-stories" class="tg tg-stories" type="checkbox" hidden />
   
   
-  <input id="c-13-components-form-props" class="tg tg-props" type="checkbox" hidden />
+  <input id="c-14-components-form-props" class="tg tg-props" type="checkbox" hidden />
 
   <div class="panels">
     
@@ -5365,9 +5851,9 @@ Validation is react-hook-form&#39;s alone.</div>
     <div class="title">
       <h2><span class="status-dot dot-ok"></span> FormText</h2>
       <div class="badges">
-        <label for="c-14-components-formtext-props" class="badge ok as-toggle">15 prop types</label>
+        <label for="c-15-components-formtext-props" class="badge ok as-toggle">15 prop types</label>
         
-        <label for="c-14-components-formtext-stories" class="badge ok as-toggle">9 stories</label>
+        <label for="c-15-components-formtext-stories" class="badge ok as-toggle">9 stories</label>
         
         
       </div>
@@ -5397,10 +5883,10 @@ with the `FieldText`, `Label`, `Input` and `Field.*` primitives directly.</div>
   <!-- ⬇️ Hidden toggles must be siblings BEFORE .panels -->
   
   
-  <input id="c-14-components-formtext-stories" class="tg tg-stories" type="checkbox" hidden />
+  <input id="c-15-components-formtext-stories" class="tg tg-stories" type="checkbox" hidden />
   
   
-  <input id="c-14-components-formtext-props" class="tg tg-props" type="checkbox" hidden />
+  <input id="c-15-components-formtext-props" class="tg tg-props" type="checkbox" hidden />
 
   <div class="panels">
     
@@ -5522,7 +6008,7 @@ tooltip?: ReactNode
 /**
  * Preferred side of the tooltip. Defaults to `&#39;top&#39;`.
  */
-tooltipSide?: &quot;right&quot; | &quot;top&quot; | &quot;bottom&quot; | &quot;left&quot;</code></pre>
+tooltipSide?: &quot;top&quot; | &quot;bottom&quot; | &quot;left&quot; | &quot;right&quot;</code></pre>
           </div>
         </div>
     
@@ -5665,9 +6151,9 @@ hand.</div>
     <div class="title">
       <h2><span class="status-dot dot-ok"></span> HoverCard.Root</h2>
       <div class="badges">
-        <label for="c-15-components-hovercard-props" class="badge ok as-toggle">6 prop types</label>
+        <label for="c-16-components-hovercard-props" class="badge ok as-toggle">6 prop types</label>
         
-        <label for="c-15-components-hovercard-stories" class="badge ok as-toggle">7 stories</label>
+        <label for="c-16-components-hovercard-stories" class="badge ok as-toggle">7 stories</label>
         
         
       </div>
@@ -5699,10 +6185,10 @@ import { HoverCard } from &#39;@agentero/design-system/hover-card&#39;;
   <!-- ⬇️ Hidden toggles must be siblings BEFORE .panels -->
   
   
-  <input id="c-15-components-hovercard-stories" class="tg tg-stories" type="checkbox" hidden />
+  <input id="c-16-components-hovercard-stories" class="tg tg-stories" type="checkbox" hidden />
   
   
-  <input id="c-15-components-hovercard-props" class="tg tg-props" type="checkbox" hidden />
+  <input id="c-16-components-hovercard-props" class="tg tg-props" type="checkbox" hidden />
 
   <div class="panels">
     
@@ -5949,9 +6435,9 @@ trigger-dense UIs where an instant preview reads as more responsive.</div>
     <div class="title">
       <h2><span class="status-dot dot-ok"></span> Input</h2>
       <div class="badges">
-        <label for="c-16-components-input-props" class="badge ok as-toggle">7 prop types</label>
+        <label for="c-17-components-input-props" class="badge ok as-toggle">7 prop types</label>
         
-        <label for="c-16-components-input-stories" class="badge ok as-toggle">9 stories</label>
+        <label for="c-17-components-input-stories" class="badge ok as-toggle">9 stories</label>
         
         
       </div>
@@ -5974,10 +6460,10 @@ assistive technology announces.</div>
   <!-- ⬇️ Hidden toggles must be siblings BEFORE .panels -->
   
   
-  <input id="c-16-components-input-stories" class="tg tg-stories" type="checkbox" hidden />
+  <input id="c-17-components-input-stories" class="tg tg-stories" type="checkbox" hidden />
   
   
-  <input id="c-16-components-input-props" class="tg tg-props" type="checkbox" hidden />
+  <input id="c-17-components-input-props" class="tg tg-props" type="checkbox" hidden />
 
   <div class="panels">
     
@@ -6189,9 +6675,9 @@ they cannot change.</div>
     <div class="title">
       <h2><span class="status-dot dot-ok"></span> Label</h2>
       <div class="badges">
-        <label for="c-17-components-label-props" class="badge ok as-toggle">3 prop types</label>
+        <label for="c-18-components-label-props" class="badge ok as-toggle">3 prop types</label>
         
-        <label for="c-17-components-label-stories" class="badge ok as-toggle">5 stories</label>
+        <label for="c-18-components-label-stories" class="badge ok as-toggle">5 stories</label>
         
         
       </div>
@@ -6211,10 +6697,10 @@ still has to carry `required` / `aria-required`.</div>
   <!-- ⬇️ Hidden toggles must be siblings BEFORE .panels -->
   
   
-  <input id="c-17-components-label-stories" class="tg tg-stories" type="checkbox" hidden />
+  <input id="c-18-components-label-stories" class="tg tg-stories" type="checkbox" hidden />
   
   
-  <input id="c-17-components-label-props" class="tg tg-props" type="checkbox" hidden />
+  <input id="c-18-components-label-props" class="tg tg-props" type="checkbox" hidden />
 
   <div class="panels">
     
@@ -6334,9 +6820,9 @@ field&#39;s control with no `htmlFor`. An explicit `htmlFor` still wins.</div>
     <div class="title">
       <h2><span class="status-dot dot-ok"></span> Loading</h2>
       <div class="badges">
-        <label for="c-18-components-loading-props" class="badge ok as-toggle">1 prop type</label>
+        <label for="c-19-components-loading-props" class="badge ok as-toggle">1 prop type</label>
         
-        <label for="c-18-components-loading-stories" class="badge ok as-toggle">7 stories</label>
+        <label for="c-19-components-loading-stories" class="badge ok as-toggle">7 stories</label>
         
         
       </div>
@@ -6353,10 +6839,10 @@ parent font size via `em`-based size variants (`sm`, `md`, `lg`).</div>
   <!-- ⬇️ Hidden toggles must be siblings BEFORE .panels -->
   
   
-  <input id="c-18-components-loading-stories" class="tg tg-stories" type="checkbox" hidden />
+  <input id="c-19-components-loading-stories" class="tg tg-stories" type="checkbox" hidden />
   
   
-  <input id="c-18-components-loading-props" class="tg tg-props" type="checkbox" hidden />
+  <input id="c-19-components-loading-props" class="tg tg-props" type="checkbox" hidden />
 
   <div class="panels">
     
@@ -6507,9 +6993,9 @@ against the dark background.</div>
     <div class="title">
       <h2><span class="status-dot dot-ok"></span> Modal.Root</h2>
       <div class="badges">
-        <label for="c-19-components-modal-props" class="badge ok as-toggle">5 prop types</label>
+        <label for="c-20-components-modal-props" class="badge ok as-toggle">5 prop types</label>
         
-        <label for="c-19-components-modal-stories" class="badge ok as-toggle">6 stories</label>
+        <label for="c-20-components-modal-stories" class="badge ok as-toggle">6 stories</label>
         
         
       </div>
@@ -6555,10 +7041,10 @@ import { Modal } from &#39;@agentero/design-system/modal&#39;;
   <!-- ⬇️ Hidden toggles must be siblings BEFORE .panels -->
   
   
-  <input id="c-19-components-modal-stories" class="tg tg-stories" type="checkbox" hidden />
+  <input id="c-20-components-modal-stories" class="tg tg-stories" type="checkbox" hidden />
   
   
-  <input id="c-19-components-modal-props" class="tg tg-props" type="checkbox" hidden />
+  <input id="c-20-components-modal-props" class="tg tg-props" type="checkbox" hidden />
 
   <div class="panels">
     
@@ -6755,9 +7241,9 @@ announced as an `alertdialog`. Only the footer actions close it.</div>
     <div class="title">
       <h2><span class="status-dot dot-ok"></span> Pagination</h2>
       <div class="badges">
-        <label for="c-20-components-pagination-props" class="badge ok as-toggle">5 prop types</label>
+        <label for="c-21-components-pagination-props" class="badge ok as-toggle">5 prop types</label>
         
-        <label for="c-20-components-pagination-stories" class="badge ok as-toggle">7 stories</label>
+        <label for="c-21-components-pagination-stories" class="badge ok as-toggle">7 stories</label>
         
         
       </div>
@@ -6787,10 +7273,10 @@ const [page, setPage] = useState(1);
   <!-- ⬇️ Hidden toggles must be siblings BEFORE .panels -->
   
   
-  <input id="c-20-components-pagination-stories" class="tg tg-stories" type="checkbox" hidden />
+  <input id="c-21-components-pagination-stories" class="tg tg-stories" type="checkbox" hidden />
   
   
-  <input id="c-20-components-pagination-props" class="tg tg-props" type="checkbox" hidden />
+  <input id="c-21-components-pagination-props" class="tg tg-props" type="checkbox" hidden />
 
   <div class="panels">
     
@@ -6945,9 +7431,9 @@ entries summary follow along.</div>
     <div class="title">
       <h2><span class="status-dot dot-ok"></span> Popover.Root</h2>
       <div class="badges">
-        <label for="c-21-components-popover-props" class="badge ok as-toggle">5 prop types</label>
+        <label for="c-22-components-popover-props" class="badge ok as-toggle">5 prop types</label>
         
-        <label for="c-21-components-popover-stories" class="badge ok as-toggle">5 stories</label>
+        <label for="c-22-components-popover-stories" class="badge ok as-toggle">5 stories</label>
         
         
       </div>
@@ -6976,10 +7462,10 @@ import { Popover } from &#39;@agentero/design-system/popover&#39;;
   <!-- ⬇️ Hidden toggles must be siblings BEFORE .panels -->
   
   
-  <input id="c-21-components-popover-stories" class="tg tg-stories" type="checkbox" hidden />
+  <input id="c-22-components-popover-stories" class="tg tg-stories" type="checkbox" hidden />
   
   
-  <input id="c-21-components-popover-props" class="tg tg-props" type="checkbox" hidden />
+  <input id="c-22-components-popover-props" class="tg tg-props" type="checkbox" hidden />
 
   <div class="panels">
     
@@ -7178,9 +7664,9 @@ focus returning to its trigger once the modal closes.</div>
     <div class="title">
       <h2><span class="status-dot dot-ok"></span> Progress</h2>
       <div class="badges">
-        <label for="c-22-components-progress-props" class="badge ok as-toggle">4 prop types</label>
+        <label for="c-23-components-progress-props" class="badge ok as-toggle">4 prop types</label>
         
-        <label for="c-22-components-progress-stories" class="badge ok as-toggle">4 stories</label>
+        <label for="c-23-components-progress-stories" class="badge ok as-toggle">4 stories</label>
         
         
       </div>
@@ -7199,10 +7685,10 @@ with `currentColor`, so recolor it with a plain text class — e.g.
   <!-- ⬇️ Hidden toggles must be siblings BEFORE .panels -->
   
   
-  <input id="c-22-components-progress-stories" class="tg tg-stories" type="checkbox" hidden />
+  <input id="c-23-components-progress-stories" class="tg tg-stories" type="checkbox" hidden />
   
   
-  <input id="c-22-components-progress-props" class="tg tg-props" type="checkbox" hidden />
+  <input id="c-23-components-progress-props" class="tg tg-props" type="checkbox" hidden />
 
   <div class="panels">
     
@@ -7321,7 +7807,7 @@ percentage: number</code></pre>
       <div class="badges">
         
         
-        <label for="c-23-components-skeleton-stories" class="badge ok as-toggle">4 stories</label>
+        <label for="c-24-components-skeleton-stories" class="badge ok as-toggle">4 stories</label>
         
         
       </div>
@@ -7338,7 +7824,7 @@ shape it with Tailwind classes to mirror the content it stands in for.</div>
   <!-- ⬇️ Hidden toggles must be siblings BEFORE .panels -->
   
   
-  <input id="c-23-components-skeleton-stories" class="tg tg-stories" type="checkbox" hidden />
+  <input id="c-24-components-skeleton-stories" class="tg tg-stories" type="checkbox" hidden />
   
   
   
@@ -7434,9 +7920,9 @@ shape it with Tailwind classes to mirror the content it stands in for.</div>
     <div class="title">
       <h2><span class="status-dot dot-ok"></span> Switch</h2>
       <div class="badges">
-        <label for="c-24-components-switch-props" class="badge ok as-toggle">8 prop types</label>
+        <label for="c-25-components-switch-props" class="badge ok as-toggle">8 prop types</label>
         
-        <label for="c-24-components-switch-stories" class="badge ok as-toggle">7 stories</label>
+        <label for="c-25-components-switch-stories" class="badge ok as-toggle">7 stories</label>
         
         
       </div>
@@ -7452,10 +7938,10 @@ a Checkbox for a single boolean that applies instantly, and pair it with a
   <!-- ⬇️ Hidden toggles must be siblings BEFORE .panels -->
   
   
-  <input id="c-24-components-switch-stories" class="tg tg-stories" type="checkbox" hidden />
+  <input id="c-25-components-switch-stories" class="tg tg-stories" type="checkbox" hidden />
   
   
-  <input id="c-24-components-switch-props" class="tg tg-props" type="checkbox" hidden />
+  <input id="c-25-components-switch-props" class="tg tg-props" type="checkbox" hidden />
 
   <div class="panels">
     
@@ -7636,9 +8122,9 @@ size?: &quot;sm&quot; | &quot;md&quot;</code></pre>
     <div class="title">
       <h2><span class="status-dot dot-ok"></span> Table.Root</h2>
       <div class="badges">
-        <label for="c-25-components-table-props" class="badge ok as-toggle">6 prop types</label>
+        <label for="c-26-components-table-props" class="badge ok as-toggle">6 prop types</label>
         
-        <label for="c-25-components-table-stories" class="badge ok as-toggle">9 stories</label>
+        <label for="c-26-components-table-stories" class="badge ok as-toggle">9 stories</label>
         
         
       </div>
@@ -7669,10 +8155,10 @@ import { Table } from &#39;@agentero/design-system/table&#39;;
   <!-- ⬇️ Hidden toggles must be siblings BEFORE .panels -->
   
   
-  <input id="c-25-components-table-stories" class="tg tg-stories" type="checkbox" hidden />
+  <input id="c-26-components-table-stories" class="tg tg-stories" type="checkbox" hidden />
   
   
-  <input id="c-25-components-table-props" class="tg tg-props" type="checkbox" hidden />
+  <input id="c-26-components-table-props" class="tg tg-props" type="checkbox" hidden />
 
   <div class="panels">
     
@@ -7867,9 +8353,9 @@ import { Fragment } from "react";</code></pre>
     <div class="title">
       <h2><span class="status-dot dot-ok"></span> Tabs.Root</h2>
       <div class="badges">
-        <label for="c-26-components-tabs-props" class="badge ok as-toggle">9 prop types</label>
+        <label for="c-27-components-tabs-props" class="badge ok as-toggle">9 prop types</label>
         
-        <label for="c-26-components-tabs-stories" class="badge ok as-toggle">8 stories</label>
+        <label for="c-27-components-tabs-stories" class="badge ok as-toggle">8 stories</label>
         
         
       </div>
@@ -7900,10 +8386,10 @@ import { Tabs } from &#39;@agentero/design-system/tabs&#39;;
   <!-- ⬇️ Hidden toggles must be siblings BEFORE .panels -->
   
   
-  <input id="c-26-components-tabs-stories" class="tg tg-stories" type="checkbox" hidden />
+  <input id="c-27-components-tabs-stories" class="tg tg-stories" type="checkbox" hidden />
   
   
-  <input id="c-26-components-tabs-props" class="tg tg-props" type="checkbox" hidden />
+  <input id="c-27-components-tabs-props" class="tg tg-props" type="checkbox" hidden />
 
   <div class="panels">
     
@@ -8124,9 +8610,9 @@ tablist role is announced.</div>
     <div class="title">
       <h2><span class="status-dot dot-ok"></span> Tag</h2>
       <div class="badges">
-        <label for="c-27-components-tag-props" class="badge ok as-toggle">8 prop types</label>
+        <label for="c-28-components-tag-props" class="badge ok as-toggle">8 prop types</label>
         
-        <label for="c-27-components-tag-stories" class="badge ok as-toggle">12 stories</label>
+        <label for="c-28-components-tag-stories" class="badge ok as-toggle">12 stories</label>
         
         
       </div>
@@ -8145,10 +8631,10 @@ it an interactive link or button, which adds the pointer cursor and hover fill.<
   <!-- ⬇️ Hidden toggles must be siblings BEFORE .panels -->
   
   
-  <input id="c-27-components-tag-stories" class="tg tg-stories" type="checkbox" hidden />
+  <input id="c-28-components-tag-stories" class="tg tg-stories" type="checkbox" hidden />
   
   
-  <input id="c-27-components-tag-props" class="tg tg-props" type="checkbox" hidden />
+  <input id="c-28-components-tag-props" class="tg tg-props" type="checkbox" hidden />
 
   <div class="panels">
     
@@ -8559,6 +9045,197 @@ leading + trailing icons, and icon-only.</div>
         </div>
     
     
+  </div>
+</article>
+<article
+  class="card 
+  no-error 
+  no-info 
+  no-story-error
+  no-doc-error"
+  role="listitem"
+  aria-label="TextArea">
+  <div class="head">
+    <div class="title">
+      <h2><span class="status-dot dot-ok"></span> TextArea</h2>
+      <div class="badges">
+        <label for="c-29-components-textarea-props" class="badge ok as-toggle">8 prop types</label>
+        
+        <label for="c-29-components-textarea-stories" class="badge ok as-toggle">6 stories</label>
+        
+        
+      </div>
+    </div>
+    <div class="meta" title="./src/textarea/textarea.stories.tsx">components-textarea · ./src/textarea/textarea.stories.tsx</div>
+    <div>Base multi-line text control sharing Input&#39;s skin, states and sizes</div>
+    <div class="hint">TextArea is the base multi-line text control, with Input&#39;s skin, sizes and
+states. It wires nothing on its own: `id`, `aria-invalid` and
+`aria-describedby` are plain props, set by whoever owns the field.</div>
+    <div class="kv"><span class="chip">summary: Base multi-line text control sharing Input&#39;s skin, states and sizes</span><span class="chip">example: &lt;Label htmlFor=&quot;notes&quot;&gt;Notes&lt;/Label&gt;
+&lt;TextArea id=&quot;notes&quot; placeholder=&quot;Anything the underwriter should know&quot; /&gt;</span></div>
+  </div>
+
+  <!-- ⬇️ Hidden toggles must be siblings BEFORE .panels -->
+  
+  
+  <input id="c-29-components-textarea-stories" class="tg tg-stories" type="checkbox" hidden />
+  
+  
+  <input id="c-29-components-textarea-props" class="tg tg-props" type="checkbox" hidden />
+
+  <div class="panels">
+    
+    
+    
+        <div class="panel panel-props">
+          <div class="note ok">
+            <div class="row">
+              <span class="ex-name">Prop types <small>(react-component-meta)</small></span>
+              <span class="badge ok">8 prop types</span>
+            </div>
+            <pre><code>Component: src/textarea/textarea.tsx::TextArea</code></pre>
+            <pre><code>Props:</code></pre>
+            <pre><code>/**
+ * Indicates the entered value does not conform to the format expected by the application.
+ * Drives the destructive border and is what assistive technology announces.
+ */
+aria-invalid?: boolean | &quot;true&quot; | &quot;false&quot; | &quot;grammar&quot; | &quot;spelling&quot; | undefined
+
+/**
+ * Blocks interaction and drops the value from the submission. Use `readOnly`
+ * when the user still needs to read or copy it.
+ */
+disabled?: boolean
+
+/**
+ * Caps the value in UTF-16 code units: typing stops there and a paste is cut.
+ */
+maxLength?: number
+
+/**
+ * Hint shown while empty; never a substitute for a label.
+ */
+placeholder?: string
+
+/**
+ * Focusable, copyable and submitted, but not editable.
+ */
+readOnly?: boolean
+
+/**
+ * Marks the control required for both the browser and assistive technology.
+ */
+required?: boolean
+
+/**
+ * Rows visible at rest when three are not enough.
+ */
+rows?: number
+
+/**
+ * Defaults to `&#39;md&#39;`. The first row measures one Input of the same size and
+ * three rows show at rest: `sm` 76px, `md` 84px, `lg` 96px (`lg` also raises
+ * the text to `base` and the radius to `lg`).
+ */
+size?: &quot;sm&quot; | &quot;md&quot; | &quot;lg&quot;</code></pre>
+          </div>
+        </div>
+    
+        <div class="panel panel-stories">
+          
+          
+          
+          <div class="note ok">
+                <div class="row">
+                  <span class="ex-name">Imports</span>
+                </div>
+                <pre><code>import { TextArea } from "@agentero/design-system";</code></pre>
+              </div>
+          
+          
+            <div class="note ok">
+              <div class="row">
+                <span class="ex-name">Default</span>
+                <span class="badge ok">story ok</span>
+              </div>
+              <div>Default standalone text area</div>
+              <div class="hint">The default control at `md`: three rows at rest and a vertical resize handle
+the user can drag to make it taller.</div>
+              <pre><code>const Default = () =&gt; &lt;TextArea placeholder=&quot;Anything the underwriter should know&quot; aria-label=&quot;Notes&quot; /&gt;;</code></pre>
+            </div>
+            <div class="note ok">
+              <div class="row">
+                <span class="ex-name">All Sizes</span>
+                <span class="badge ok">story ok</span>
+              </div>
+              <div>The three sizes, three rows tall at rest</div>
+              <div class="hint">The three sizes mirror Input&#39;s: the first row measures one Input of the same
+size and the minimum height shows three rows.</div>
+              <pre><code>const AllSizes = () =&gt; &lt;div style={{ display: &#39;grid&#39;, gap: &#39;1rem&#39; }}&gt;
+    &lt;TextArea size=&quot;sm&quot; aria-label=&quot;Small&quot; placeholder=&quot;sm — 76px, three rows&quot; /&gt;
+    &lt;TextArea size=&quot;md&quot; aria-label=&quot;Medium&quot; placeholder=&quot;md — 84px, three rows&quot; /&gt;
+    &lt;TextArea size=&quot;lg&quot; aria-label=&quot;Large&quot; placeholder=&quot;lg — 96px, three rows&quot; /&gt;
+&lt;/div&gt;;</code></pre>
+            </div>
+            <div class="note ok">
+              <div class="row">
+                <span class="ex-name">Rows</span>
+                <span class="badge ok">story ok</span>
+              </div>
+              <div>Taller initial height through the native rows attribute</div>
+              <div class="hint">`rows` sets a taller initial height when three rows are not enough.</div>
+              <pre><code>const Rows = () =&gt; &lt;TextArea
+    placeholder=&quot;Six rows visible before scrolling&quot;
+    aria-label=&quot;Notes&quot;
+    rows={6} /&gt;;</code></pre>
+            </div>
+            <div class="note ok">
+              <div class="row">
+                <span class="ex-name">Invalid</span>
+                <span class="badge ok">story ok</span>
+              </div>
+              <div>Invalid state driven by aria-invalid</div>
+              <div class="hint">The invalid treatment comes purely from `aria-invalid`; point
+`aria-describedby` at the message so it is read with the control.</div>
+              <pre><code>const Invalid = () =&gt; &lt;div style={{ display: &#39;grid&#39;, gap: &#39;0.25rem&#39; }}&gt;
+    &lt;TextArea
+        placeholder=&quot;Anything the underwriter should know&quot;
+        aria-label=&quot;Reason&quot;
+        aria-invalid
+        aria-describedby=&quot;reason-error&quot;
+        defaultValue=&quot;n/a&quot; /&gt;
+    &lt;span id=&quot;reason-error&quot;&gt;Tell us why you are cancelling.&lt;/span&gt;
+&lt;/div&gt;;</code></pre>
+            </div>
+            <div class="note ok">
+              <div class="row">
+                <span class="ex-name">Disabled</span>
+                <span class="badge ok">story ok</span>
+              </div>
+              <div>Disabled state</div>
+              
+              <pre><code>const Disabled = () =&gt; &lt;TextArea
+    placeholder=&quot;Anything the underwriter should know&quot;
+    aria-label=&quot;Notes&quot;
+    disabled
+    defaultValue=&quot;Cannot be edited&quot; /&gt;;</code></pre>
+            </div>
+            <div class="note ok">
+              <div class="row">
+                <span class="ex-name">Read Only</span>
+                <span class="badge ok">story ok</span>
+              </div>
+              <div>Read-only value that stays focusable and copyable</div>
+              
+              <pre><code>const ReadOnly = () =&gt; &lt;TextArea
+    placeholder=&quot;Anything the underwriter should know&quot;
+    aria-label=&quot;Notes&quot;
+    readOnly
+    defaultValue=&quot;Copy me, but do not change me&quot; /&gt;;</code></pre>
+            </div>
+        </div>
+    
+    
   </div>
 </article>
 <article
@@ -8573,9 +9250,9 @@ leading + trailing icons, and icon-only.</div>
     <div class="title">
       <h2><span class="status-dot dot-ok"></span> Toast</h2>
       <div class="badges">
-        <label for="c-28-components-toast-props" class="badge ok as-toggle">11 prop types</label>
+        <label for="c-30-components-toast-props" class="badge ok as-toggle">11 prop types</label>
         
-        <label for="c-28-components-toast-stories" class="badge ok as-toggle">11 stories</label>
+        <label for="c-30-components-toast-stories" class="badge ok as-toggle">11 stories</label>
         
         
       </div>
@@ -8594,10 +9271,10 @@ common feedback patterns.</div>
   <!-- ⬇️ Hidden toggles must be siblings BEFORE .panels -->
   
   
-  <input id="c-28-components-toast-stories" class="tg tg-stories" type="checkbox" hidden />
+  <input id="c-30-components-toast-stories" class="tg tg-stories" type="checkbox" hidden />
   
   
-  <input id="c-28-components-toast-props" class="tg tg-props" type="checkbox" hidden />
+  <input id="c-30-components-toast-props" class="tg tg-props" type="checkbox" hidden />
 
   <div class="panels">
     
@@ -9026,9 +9703,9 @@ action (e.g., a sync icon for a sync-in-progress toast).</div>
     <div class="title">
       <h2><span class="status-dot dot-ok"></span> Tooltip</h2>
       <div class="badges">
-        <label for="c-29-components-tooltip-props" class="badge ok as-toggle">12 prop types</label>
+        <label for="c-31-components-tooltip-props" class="badge ok as-toggle">12 prop types</label>
         
-        <label for="c-29-components-tooltip-stories" class="badge ok as-toggle">5 stories</label>
+        <label for="c-31-components-tooltip-stories" class="badge ok as-toggle">5 stories</label>
         
         
       </div>
@@ -9047,10 +9724,10 @@ on hover or focus.</div>
   <!-- ⬇️ Hidden toggles must be siblings BEFORE .panels -->
   
   
-  <input id="c-29-components-tooltip-stories" class="tg tg-stories" type="checkbox" hidden />
+  <input id="c-31-components-tooltip-stories" class="tg tg-stories" type="checkbox" hidden />
   
   
-  <input id="c-29-components-tooltip-props" class="tg tg-props" type="checkbox" hidden />
+  <input id="c-31-components-tooltip-props" class="tg tg-props" type="checkbox" hidden />
 
   <div class="panels">
     
@@ -9108,7 +9785,7 @@ open?: boolean
 /**
  * Preferred side of the trigger; flips on collision. Defaults to `&#39;top&#39;`.
  */
-side?: &quot;right&quot; | &quot;top&quot; | &quot;bottom&quot; | &quot;left&quot; = &#39;top&#39;
+side?: &quot;top&quot; | &quot;bottom&quot; | &quot;left&quot; | &quot;right&quot; = &#39;top&#39;
 
 /**
  * Distance in pixels between the tooltip and its trigger. Defaults to `4`.
@@ -9222,9 +9899,9 @@ sideOffset?: number = 4</code></pre>
     <div class="title">
       <h2><span class="status-dot dot-ok"></span> ValidationList</h2>
       <div class="badges">
-        <label for="c-30-components-validationlist-props" class="badge ok as-toggle">2 prop types</label>
+        <label for="c-32-components-validationlist-props" class="badge ok as-toggle">2 prop types</label>
         
-        <label for="c-30-components-validationlist-stories" class="badge ok as-toggle">4 stories</label>
+        <label for="c-32-components-validationlist-stories" class="badge ok as-toggle">4 stories</label>
         
         
       </div>
@@ -9245,10 +9922,10 @@ your form validation; it does not own the input or block submission.</div>
   <!-- ⬇️ Hidden toggles must be siblings BEFORE .panels -->
   
   
-  <input id="c-30-components-validationlist-stories" class="tg tg-stories" type="checkbox" hidden />
+  <input id="c-32-components-validationlist-stories" class="tg tg-stories" type="checkbox" hidden />
   
   
-  <input id="c-30-components-validationlist-props" class="tg tg-props" type="checkbox" hidden />
+  <input id="c-32-components-validationlist-props" class="tg tg-props" type="checkbox" hidden />
 
   <div class="panels">