@agentero/design-system 0.31.4 → 0.31.5

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">33 components ok</span><span class="filter-pill ok" aria-disabled="true">264 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">265 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>2.7s</strong>.
+              Using <code>react-component-meta</code>. Generation took <strong>4.8s</strong>.
             </div>
     <h2 class="section-title">Components</h2>
     <div class="grid" role="list">
@@ -720,7 +720,12 @@ value?: string | string[] | undefined</code></pre>
               
               <div class="hint">Exclusive accordion: one item open at a time, `collapsible` lets it close.</div>
               <pre><code>const Default = () =&gt; &lt;Accordion.Root type=&quot;single&quot; collapsible enclosed={false} disabled={false}&gt;
-    &lt;FaqItems /&gt;
+    {FAQS.map(({ value, question, answer }) =&gt; (
+        &lt;Accordion.Item key={value} value={value}&gt;
+            &lt;Accordion.Trigger&gt;{question}&lt;/Accordion.Trigger&gt;
+            &lt;Accordion.Content&gt;{answer}&lt;/Accordion.Content&gt;
+        &lt;/Accordion.Item&gt;
+    ))}
 &lt;/Accordion.Root&gt;;</code></pre>
             </div>
             <div class="note ok">
@@ -732,7 +737,12 @@ value?: string | string[] | undefined</code></pre>
               <div class="hint">`type=&quot;multiple&quot;` lets several sections stay open at once.</div>
               <pre><code>const Multiple = () =&gt; (
     &lt;Accordion.Root type=&quot;multiple&quot; defaultValue={[&#39;covered&#39;, &#39;payment&#39;]}&gt;
-        &lt;FaqItems /&gt;
+        {FAQS.map(({ value, question, answer }) =&gt; (
+            &lt;Accordion.Item key={value} value={value}&gt;
+                &lt;Accordion.Trigger&gt;{question}&lt;/Accordion.Trigger&gt;
+                &lt;Accordion.Content&gt;{answer}&lt;/Accordion.Content&gt;
+            &lt;/Accordion.Item&gt;
+        ))}
     &lt;/Accordion.Root&gt;
 );</code></pre>
             </div>
@@ -746,10 +756,20 @@ value?: string | string[] | undefined</code></pre>
               <pre><code>const Enclosed = () =&gt; (
     &lt;div className=&quot;flex flex-col gap-8&quot;&gt;
         &lt;Accordion.Root type=&quot;multiple&quot; defaultValue={[&#39;covered&#39;]}&gt;
-            &lt;FaqItems /&gt;
+            {FAQS.map(({ value, question, answer }) =&gt; (
+                &lt;Accordion.Item key={value} value={value}&gt;
+                    &lt;Accordion.Trigger&gt;{question}&lt;/Accordion.Trigger&gt;
+                    &lt;Accordion.Content&gt;{answer}&lt;/Accordion.Content&gt;
+                &lt;/Accordion.Item&gt;
+            ))}
         &lt;/Accordion.Root&gt;
         &lt;Accordion.Root type=&quot;multiple&quot; enclosed defaultValue={[&#39;claim&#39;]}&gt;
-            &lt;FaqItems /&gt;
+            {FAQS.map(({ value, question, answer }) =&gt; (
+                &lt;Accordion.Item key={value} value={value}&gt;
+                    &lt;Accordion.Trigger&gt;{question}&lt;/Accordion.Trigger&gt;
+                    &lt;Accordion.Content&gt;{answer}&lt;/Accordion.Content&gt;
+                &lt;/Accordion.Item&gt;
+            ))}
         &lt;/Accordion.Root&gt;
     &lt;/div&gt;
 );</code></pre>
@@ -801,7 +821,12 @@ value?: string | string[] | undefined</code></pre>
               
               <div class="hint">`collapsible` lets clicking the open item close it (reach an all-closed state).</div>
               <pre><code>const ExpandCollapse = () =&gt; &lt;Accordion.Root type=&quot;single&quot; collapsible&gt;
-    &lt;FaqItems /&gt;
+    {FAQS.map(({ value, question, answer }) =&gt; (
+        &lt;Accordion.Item key={value} value={value}&gt;
+            &lt;Accordion.Trigger&gt;{question}&lt;/Accordion.Trigger&gt;
+            &lt;Accordion.Content&gt;{answer}&lt;/Accordion.Content&gt;
+        &lt;/Accordion.Item&gt;
+    ))}
 &lt;/Accordion.Root&gt;;</code></pre>
             </div>
             <div class="note ok">
@@ -812,7 +837,12 @@ value?: string | string[] | undefined</code></pre>
               
               <div class="hint">Without `collapsible`, clicking the already-open item keeps it open.</div>
               <pre><code>const NonCollapsible = () =&gt; &lt;Accordion.Root type=&quot;single&quot; collapsible={false} defaultValue=&quot;covered&quot;&gt;
-    &lt;FaqItems /&gt;
+    {FAQS.map(({ value, question, answer }) =&gt; (
+        &lt;Accordion.Item key={value} value={value}&gt;
+            &lt;Accordion.Trigger&gt;{question}&lt;/Accordion.Trigger&gt;
+            &lt;Accordion.Content&gt;{answer}&lt;/Accordion.Content&gt;
+        &lt;/Accordion.Item&gt;
+    ))}
 &lt;/Accordion.Root&gt;;</code></pre>
             </div>
         </div>
@@ -3182,7 +3212,29 @@ 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>
+              <pre><code>const AsyncSearch = () =&gt; {
+    const [query, setQuery] = useState(&#39;&#39;);
+
+    return (
+        // No `items` and `filter={null}`: the server did the filtering, the child renders what came
+        // back, and `isItemEqualToValue` keeps a re-fetched copy counting as the selected one.
+        &lt;Combobox.Root
+            filter={null}
+            itemToStringLabel={(agency: Agency) =&gt; agency.name}
+            isItemEqualToValue={(a: Agency, b: Agency) =&gt; a.id === b.id}
+            onInputValueChange={(value, { reason }) =&gt; {
+                // Picking a row writes its label into the input; that is not a new search.
+                if (reason !== &#39;item-press&#39;) setQuery(value);
+            }}&gt;
+            &lt;Combobox.Input placeholder=&quot;Search agencies&quot; aria-label=&quot;Search agencies&quot; /&gt;
+            &lt;Combobox.Content&gt;
+                &lt;Suspense fallback={&lt;SkeletonRows /&gt;}&gt;
+                    &lt;AgencyItems query={query} /&gt;
+                &lt;/Suspense&gt;
+            &lt;/Combobox.Content&gt;
+        &lt;/Combobox.Root&gt;
+    );
+};</code></pre>
             </div>
             <div class="note ok">
               <div class="row">
@@ -3194,7 +3246,54 @@ out-of-order responses harmless. Drop a `useSuspenseQuery` where `use()` is.</di
 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>
+              <pre><code>const AsyncSearchWithStatus = () =&gt; {
+    const [results, setResults] = useState&lt;Agency[]&gt;([]);
+    const [isLoading, setIsLoading] = useState(false);
+    // Only the latest request may land; fast typing returns responses out of order.
+    const latestRequest = useRef(0);
+
+    const onInputValueChange = async (query: string) =&gt; {
+        const request = ++latestRequest.current;
+
+        // The previous rows go before the wait starts: a list that no longer matches what is typed
+        // must not sit under the loading state.
+        setResults([]);
+        setIsLoading(true);
+        const agencies = await searchAgencies(query);
+        if (request !== latestRequest.current) return;
+
+        setResults(agencies);
+        setIsLoading(false);
+    };
+
+    return (
+        // `filter={null}` hands filtering to the server; `filteredItems` is what came back.
+        &lt;Combobox.Root
+            items={results}
+            filteredItems={results}
+            filter={null}
+            itemToStringLabel={(agency: Agency) =&gt; agency.name}
+            isItemEqualToValue={(a: Agency, b: Agency) =&gt; a.id === b.id}
+            onInputValueChange={onInputValueChange}&gt;
+            &lt;Combobox.Input placeholder=&quot;Search agencies&quot; aria-label=&quot;Search agencies&quot; /&gt;
+            &lt;Combobox.Content aria-busy={isLoading || undefined}&gt;
+                {/* The rows show the wait; `Status` only announces it. */}
+                &lt;Combobox.Status className=&quot;sr-only&quot;&gt;
+                    {isLoading ? &#39;Searching…&#39; : undefined}
+                &lt;/Combobox.Status&gt;
+                {isLoading &amp;&amp; &lt;SkeletonRows /&gt;}
+                &lt;Combobox.Empty&gt;{isLoading ? undefined : &#39;No agencies found&#39;}&lt;/Combobox.Empty&gt;
+                &lt;Combobox.List&gt;
+                    {(agency: Agency) =&gt; (
+                        &lt;Combobox.Item key={agency.id} value={agency}&gt;
+                            {agency.name}
+                        &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">
@@ -3242,7 +3341,7 @@ padded past it.</div>
         &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;
+                className=&quot;pointer-events-none absolute top-1/2 left-3 -z-hide 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;
@@ -3313,7 +3412,7 @@ list nor treats a click in it as a click outside and closes.</div>
       <div class="badges">
         <label for="c-8-components-command-props" class="badge ok as-toggle">10 prop types</label>
         
-        <label for="c-8-components-command-stories" class="badge ok as-toggle">6 stories</label>
+        <label for="c-8-components-command-stories" class="badge ok as-toggle">7 stories</label>
         
         
       </div>
@@ -3322,7 +3421,9 @@ list nor treats a click in it as a click outside and closes.</div>
     <div>Filterable command palette container</div>
     <div class="hint">Command is a filterable list built on `cmdk`. Type to narrow the options,
 navigate with the arrow keys, select with Enter. It carries its own panel
-chrome, so dropping it inside a `Popover.Content` yields a combobox.</div>
+chrome, so dropping it inside a `Popover.Content` yields a combobox.
+`useCommandState` reads the search text and results of the surrounding
+`Command.Root` from any component rendered inside it.</div>
     <div class="kv"><span class="chip">summary: Filterable command palette container</span><span class="chip">see: {@link https://github.com/pacocoursey/cmdk cmdk}</span><span class="chip">example: ```tsx
 import { Command } from &#39;@agentero/design-system/command&#39;;
 
@@ -3544,6 +3645,23 @@ list does not invite the pointer.</div>
                             &lt;/Command.Item&gt;
     &lt;/Command.List&gt;
     &lt;Command.Empty&gt;No results found.&lt;/Command.Empty&gt;
+&lt;/Command.Root&gt;;</code></pre>
+            </div>
+            <div class="note ok">
+              <div class="row">
+                <span class="ex-name">Reading State</span>
+                <span class="badge ok">story ok</span>
+              </div>
+              
+              <div class="hint">`useCommandState` reads the surrounding `Root` from a component inside it. Here the row
+offering to create an agency appears only when the search text matches no existing one.</div>
+              <pre><code>const ReadingState = () =&gt; &lt;Command.Root label=&quot;Search agencies&quot;&gt;
+    &lt;Command.Input placeholder=&quot;Search agencies...&quot; /&gt;
+    &lt;Command.List&gt;
+        &lt;Command.Item&gt;Pinnacle Shield Insurance&lt;/Command.Item&gt;
+        &lt;Command.Item&gt;Horizon Risk Solutions&lt;/Command.Item&gt;
+        &lt;CreateItem /&gt;
+    &lt;/Command.List&gt;
 &lt;/Command.Root&gt;;</code></pre>
             </div>
         </div>
@@ -5317,7 +5435,7 @@ label with its description, or a control with its messages, in
 `Field.Content`. A control sets its own width: `Input` is `w-full`, so it
 gets one here.</div>
               <pre><code>const Horizontal = () =&gt; (
-    &lt;Field.Group className=&quot;w-[40rem]&quot;&gt;
+    &lt;Field.Group className=&quot;w-160&quot;&gt;
         &lt;Field.Root orientation=&quot;horizontal&quot; data-testid=&quot;short&quot;&gt;
             &lt;Label&gt;Full name&lt;/Label&gt;
             &lt;DemoInput defaultValue=&quot;Rafa Moro&quot; className=&quot;w-72&quot; /&gt;
@@ -5360,7 +5478,7 @@ measures the field itself, so it needs no particular wrapper. A width that
 should only apply once horizontal goes behind `@md/field:`.</div>
               <pre><code>const Responsive = () =&gt; (
     &lt;div className=&quot;flex flex-col gap-8&quot;&gt;
-        &lt;div className=&quot;w-full max-w-[40rem]&quot; data-testid=&quot;wide&quot;&gt;
+        &lt;div className=&quot;w-full max-w-160&quot; data-testid=&quot;wide&quot;&gt;
             &lt;Field.Root orientation=&quot;responsive&quot;&gt;
                 &lt;Label&gt;Email&lt;/Label&gt;
                 &lt;Field.Content className=&quot;@md/field:w-72&quot;&gt;
@@ -5455,7 +5573,27 @@ part wins over what `Field.Root` provides.</div>
 errors, a bare `&lt;Field.Error /&gt;` renders them — here with `useState` and no
 form library. `InputContext` extends the same way with `value`, `onChange`,
 `onBlur` and `name`; see `FieldText`.</div>
-              <pre><code>const ErrorsFromContext = () =&gt; &lt;FieldWithSuppliedErrors /&gt;;</code></pre>
+              <pre><code>const ErrorsFromContext = () =&gt; {
+    const [value, setValue] = useState(&#39;&#39;);
+    const [touched, setTouched] = useState(false);
+
+    const errors = touched &amp;&amp; !value ? [{ message: &#39;Required&#39; }] : undefined;
+
+    return (
+        &lt;Field.Root invalid={!!errors} required&gt;
+            &lt;Label&gt;Email&lt;/Label&gt;
+            &lt;DemoInput
+                type=&quot;email&quot;
+                value={value}
+                onChange={event =&gt; setValue(event.target.value)}
+                onBlur={() =&gt; setTouched(true)}
+            /&gt;
+            &lt;ErrorProvider errors={errors}&gt;
+                &lt;Field.Error /&gt;
+            &lt;/ErrorProvider&gt;
+        &lt;/Field.Root&gt;
+    );
+};</code></pre>
             </div>
         </div>
     
@@ -5703,7 +5841,29 @@ through untouched.</div>
 `&lt;Input /&gt;` becomes controlled, and the errors to `FieldContext`, so a bare
 `&lt;Field.Error /&gt;` renders them — here with `useState` and no form library.
 The input&#39;s own `onChange` still runs, chained after the provider&#39;s.</div>
-              <pre><code>const ControlledFromContext = () =&gt; &lt;ControlledField /&gt;;</code></pre>
+              <pre><code>const ControlledFromContext = () =&gt; {
+    const [value, setValue] = useState(&#39;&#39;);
+    const [touched, setTouched] = useState(false);
+
+    const errors = touched &amp;&amp; !value ? [{ message: &#39;Required&#39; }] : undefined;
+
+    return (
+        &lt;FieldText invalid={!!errors} required&gt;
+            &lt;ContextExtension
+                inputProps={{
+                    name: &#39;email&#39;,
+                    value,
+                    onChange: event =&gt; setValue(event.target.value),
+                    onBlur: () =&gt; setTouched(true)
+                }}
+                errors={errors}&gt;
+                &lt;Label&gt;Email&lt;/Label&gt;
+                &lt;Input type=&quot;email&quot; onChange={onOwnChange} /&gt;
+                &lt;Field.Error /&gt;
+            &lt;/ContextExtension&gt;
+        &lt;/FieldText&gt;
+    );
+};</code></pre>
             </div>
         </div>
     
@@ -5820,7 +5980,34 @@ onSubmit?: SubmitHandler&lt;AgencyValues&gt;</code></pre>
 both errors, marks both inputs invalid and focuses the first one — proof that
 react-hook-form&#39;s `ref` reached the inputs. Once filled in, `onSubmit`
 receives the typed values.</div>
-              <pre><code>const Default = () =&gt; &lt;AgencyForm /&gt;;</code></pre>
+              <pre><code>const Default = () =&gt; {
+    const methods = useForm&lt;AgencyValues&gt;({ defaultValues: { agencyName: &#39;&#39;, email: &#39;&#39; } });
+
+    return (
+        &lt;Form.Root
+            methods={methods}
+            onSubmit={onSubmit}
+            aria-label=&quot;Agency profile&quot;
+            className=&quot;flex flex-col items-start gap-7&quot;&gt;
+            &lt;Field.Group&gt;
+                &lt;FormText
+                    name=&quot;agencyName&quot;
+                    label=&quot;Agency name&quot;
+                    required
+                    rules={{ required: &#39;Enter the agency name.&#39; }}
+                /&gt;
+                &lt;FormText
+                    name=&quot;email&quot;
+                    label=&quot;Email&quot;
+                    required
+                    rules={{ required: &#39;Enter the agency email.&#39; }}
+                    inputProps={{ type: &#39;email&#39;, autoComplete: &#39;email&#39; }}
+                /&gt;
+            &lt;/Field.Group&gt;
+            &lt;Button type=&quot;submit&quot;&gt;Save&lt;/Button&gt;
+        &lt;/Form.Root&gt;
+    );
+};</code></pre>
             </div>
             <div class="note ok">
               <div class="row">
@@ -5832,7 +6019,20 @@ receives the typed values.</div>
 announces it, but the form renders `noValidate`: without `rules`, submitting
 the field empty is not blocked by the browser and `onSubmit` still runs.
 Validation is react-hook-form&#39;s alone.</div>
-              <pre><code>const NoValidate = () =&gt; &lt;NicknameForm /&gt;;</code></pre>
+              <pre><code>const NoValidate = () =&gt; {
+    const methods = useForm&lt;NicknameValues&gt;({ defaultValues: { nickname: &#39;&#39; } });
+
+    return (
+        &lt;Form.Root
+            methods={methods}
+            onSubmit={onSubmit}
+            aria-label=&quot;Display name&quot;
+            className=&quot;flex flex-col items-start gap-7&quot;&gt;
+            &lt;FormText name=&quot;nickname&quot; label=&quot;Display name&quot; required /&gt;
+            &lt;Button type=&quot;submit&quot;&gt;Save&lt;/Button&gt;
+        &lt;/Form.Root&gt;
+    );
+};</code></pre>
             </div>
         </div>
     
@@ -5907,7 +6107,7 @@ with the `FieldText`, `Label`, `Input` and `Field.*` primitives directly.</div>
  * a `Form.Root`. A `control` whose resolver transforms the values is
  * accepted as is.
  */
-control?: Control&lt;FieldValues, any, FieldValues&gt;
+control?: Control&lt;FieldValues, any, unknown&gt;
 
 /**
  * `id` for the control. Generated when omitted. Set it here, not on the
@@ -6033,14 +6233,29 @@ tooltipSide?: &quot;top&quot; | &quot;bottom&quot; | &quot;left&quot; | &quot;ri
               <div class="hint">The field consumers write: a `name`, a `label` and the validation rule.
 Submitting empty renders the error and marks the input invalid; typing
 clears both and the value reaches `onSubmit`.</div>
-              <pre><code>const Default = () =&gt; &lt;AgencyNameForm
-    name=&quot;agencyName&quot;
-    label=&quot;Agency name&quot;
-    orientation=&quot;vertical&quot;
-    required
-    optional={false}
-    disabled={false}
-    readOnly={false} /&gt;;</code></pre>
+              <pre><code>const Default = () =&gt; {
+    const methods = useForm&lt;AgencyValues&gt;({ defaultValues: { agencyName: &#39;&#39; } });
+
+    return (
+        &lt;Form.Root
+            methods={methods}
+            onSubmit={onSubmit}
+            aria-label=&quot;Agency&quot;
+            className=&quot;flex flex-col items-start gap-7&quot;&gt;
+            &lt;FormText
+                rules={{ required: &#39;Enter the agency name.&#39; }}
+                inputProps={{ placeholder: &#39;Acme Insurance&#39; }}
+                label=&quot;Agency name&quot;
+                orientation=&quot;vertical&quot;
+                required
+                optional={false}
+                disabled={false}
+                readOnly={false}
+                name=&quot;agencyName&quot; /&gt;
+            &lt;Button type=&quot;submit&quot;&gt;Save&lt;/Button&gt;
+        &lt;/Form.Root&gt;
+    );
+};</code></pre>
             </div>
             <div class="note ok">
               <div class="row">
@@ -6052,7 +6267,21 @@ clears both and the value reaches `onSubmit`.</div>
 `aria-describedby`. `tooltip` is an info button beside the label for details
 worth a click; it is a sibling of the `&lt;label&gt;`, so the field&#39;s accessible
 name stays the label text.</div>
-              <pre><code>const WithDescriptionAndTooltip = () =&gt; &lt;TaxIdForm /&gt;;</code></pre>
+              <pre><code>const WithDescriptionAndTooltip = () =&gt; {
+    const methods = useForm&lt;TaxValues&gt;({ defaultValues: { taxId: &#39;&#39; } });
+
+    return (
+        &lt;Form.Root methods={methods} aria-label=&quot;Tax details&quot;&gt;
+            &lt;FormText
+                name=&quot;taxId&quot;
+                label=&quot;Tax ID&quot;
+                tooltip=&quot;The EIN the IRS issued to the agency.&quot;
+                description=&quot;Nine digits, with or without the dash.&quot;
+                inputProps={{ inputMode: &#39;numeric&#39;, autoComplete: &#39;off&#39; }}
+            /&gt;
+        &lt;/Form.Root&gt;
+    );
+};</code></pre>
             </div>
             <div class="note ok">
               <div class="row">
@@ -6063,7 +6292,15 @@ name stays the label text.</div>
               <div class="hint">The forms mark optional fields rather than required ones: `optional`
 appends a muted suffix to the label and leaves the input without the
 `required` attribute.</div>
-              <pre><code>const Optional = () =&gt; &lt;PhoneForm /&gt;;</code></pre>
+              <pre><code>const Optional = () =&gt; {
+    const methods = useForm&lt;PhoneValues&gt;({ defaultValues: { phone: &#39;&#39; } });
+
+    return (
+        &lt;Form.Root methods={methods} aria-label=&quot;Contact&quot;&gt;
+            &lt;FormText name=&quot;phone&quot; label=&quot;Phone number&quot; optional inputProps={{ type: &#39;tel&#39; }} /&gt;
+        &lt;/Form.Root&gt;
+    );
+};</code></pre>
             </div>
             <div class="note ok">
               <div class="row">
@@ -6074,7 +6311,28 @@ appends a muted suffix to the label and leaves the input without the
               <div class="hint">`rules` are react-hook-form&#39;s, and `name` accepts nested paths typed against
 the form&#39;s values through the generic. `rules.required` validates but does
 not mark the field required: that stays an explicit `required` prop.</div>
-              <pre><code>const WithRules = () =&gt; &lt;NpnForm /&gt;;</code></pre>
+              <pre><code>const WithRules = () =&gt; {
+    const methods = useForm&lt;LicenseValues&gt;({ defaultValues: { agency: { npn: &#39;&#39; } } });
+
+    return (
+        &lt;Form.Root
+            methods={methods}
+            onSubmit={onSubmit}
+            aria-label=&quot;License&quot;
+            className=&quot;flex flex-col items-start gap-7&quot;&gt;
+            &lt;FormText&lt;LicenseValues&gt;
+                name=&quot;agency.npn&quot;
+                label=&quot;NPN&quot;
+                rules={{
+                    required: &#39;Enter your NPN.&#39;,
+                    pattern: { value: /^\d{6,10}$/, message: &#39;An NPN is 6 to 10 digits.&#39; }
+                }}
+                inputProps={{ inputMode: &#39;numeric&#39; }}
+            /&gt;
+            &lt;Button type=&quot;submit&quot;&gt;Save&lt;/Button&gt;
+        &lt;/Form.Root&gt;
+    );
+};</code></pre>
             </div>
             <div class="note ok">
               <div class="row">
@@ -6086,7 +6344,36 @@ not mark the field required: that stays an explicit `required` prop.</div>
 that failed instead of stopping at the first, and the field lists them all.
 With the default `&#39;firstError&#39;` a single message is rendered, as in the other
 stories.</div>
-              <pre><code>const AllErrors = () =&gt; &lt;PasswordRulesForm /&gt;;</code></pre>
+              <pre><code>const AllErrors = () =&gt; {
+    const methods = useForm&lt;PasswordValues&gt;({
+        defaultValues: { password: &#39;&#39; },
+        criteriaMode: &#39;all&#39;
+    });
+
+    return (
+        &lt;Form.Root
+            methods={methods}
+            onSubmit={onSubmit}
+            aria-label=&quot;Account security&quot;
+            className=&quot;flex flex-col items-start gap-7&quot;&gt;
+            &lt;FormText
+                name=&quot;password&quot;
+                label=&quot;Password&quot;
+                required
+                inputProps={{ type: &#39;password&#39; }}
+                rules={{
+                    required: &#39;Enter a password.&#39;,
+                    validate: {
+                        uppercase: value =&gt; /[A-Z]/.test(value) || &#39;At least one uppercase letter.&#39;,
+                        number: value =&gt; /[0-9]/.test(value) || &#39;At least one number.&#39;,
+                        length: value =&gt; value.length &gt;= 10 || &#39;At least 10 characters.&#39;
+                    }
+                }}
+            /&gt;
+            &lt;Button type=&quot;submit&quot;&gt;Save&lt;/Button&gt;
+        &lt;/Form.Root&gt;
+    );
+};</code></pre>
             </div>
             <div class="note ok">
               <div class="row">
@@ -6098,7 +6385,25 @@ stories.</div>
 `maxLength`, `size`… — and its handlers. A consumer `onChange` runs after
 react-hook-form&#39;s: by the time it fires, `getValues` already returns the new
 value.</div>
-              <pre><code>const InputPropsChaining = () =&gt; &lt;MobileForm /&gt;;</code></pre>
+              <pre><code>const InputPropsChaining = () =&gt; {
+    const methods = useForm&lt;PhoneValues&gt;({ defaultValues: { phone: &#39;&#39; } });
+
+    return (
+        &lt;Form.Root methods={methods} aria-label=&quot;Mobile&quot;&gt;
+            &lt;FormText
+                name=&quot;phone&quot;
+                label=&quot;Mobile&quot;
+                inputProps={{
+                    type: &#39;tel&#39;,
+                    placeholder: &#39;5550000000&#39;,
+                    maxLength: 10,
+                    size: &#39;lg&#39;,
+                    onChange: event =&gt; onOwnChange(methods.getValues(&#39;phone&#39;), event.target.value)
+                }}
+            /&gt;
+        &lt;/Form.Root&gt;
+    );
+};</code></pre>
             </div>
             <div class="note ok">
               <div class="row">
@@ -6110,7 +6415,33 @@ value.</div>
 control in a row, and `className` on the root or in `inputProps` sizes them.
 The `Input` is full-width by default, so a settings row gives it a width.
 `responsive` stacks the field below 28rem and rows it from there.</div>
-              <pre><code>const Horizontal = () =&gt; &lt;ProfileForm /&gt;;</code></pre>
+              <pre><code>const Horizontal = () =&gt; {
+    const methods = useForm&lt;ProfileValues&gt;({
+        defaultValues: { fullName: &#39;Rafa Moro&#39;, title: &#39;&#39; }
+    });
+
+    return (
+        &lt;Form.Root methods={methods} aria-label=&quot;Profile&quot; className=&quot;w-[40rem]&quot;&gt;
+            &lt;Field.Group&gt;
+                &lt;FormText
+                    name=&quot;fullName&quot;
+                    label=&quot;Full name&quot;
+                    orientation=&quot;horizontal&quot;
+                    inputProps={{ className: &#39;w-72&#39; }}
+                    data-testid=&quot;short&quot;
+                /&gt;
+                &lt;FormText
+                    name=&quot;title&quot;
+                    label=&quot;Title&quot;
+                    description=&quot;Shown on your public profile.&quot;
+                    orientation=&quot;horizontal&quot;
+                    inputProps={{ className: &#39;w-72&#39;, placeholder: &#39;Software engineer&#39; }}
+                    data-testid=&quot;long&quot;
+                /&gt;
+            &lt;/Field.Group&gt;
+        &lt;/Form.Root&gt;
+    );
+};</code></pre>
             </div>
             <div class="note ok">
               <div class="row">
@@ -6121,7 +6452,25 @@ The `Input` is full-width by default, so a settings row gives it a width.
               <div class="hint">`disabled` disables the input and marks the field, and the value still
 reaches `onSubmit` — unlike react-hook-form&#39;s own `disabled` option, which
 drops it. Use `readOnly` for a value the user can copy but not edit.</div>
-              <pre><code>const Disabled = () =&gt; &lt;AccountForm /&gt;;</code></pre>
+              <pre><code>const Disabled = () =&gt; {
+    const methods = useForm&lt;AccountValues&gt;({
+        defaultValues: { agencyId: &#39;AG-48213&#39;, email: &#39;ops@acme-insurance.com&#39; }
+    });
+
+    return (
+        &lt;Form.Root
+            methods={methods}
+            onSubmit={onSubmit}
+            aria-label=&quot;Account&quot;
+            className=&quot;flex flex-col items-start gap-7&quot;&gt;
+            &lt;Field.Group&gt;
+                &lt;FormText name=&quot;agencyId&quot; label=&quot;Agency ID&quot; disabled /&gt;
+                &lt;FormText name=&quot;email&quot; label=&quot;Email&quot; inputProps={{ type: &#39;email&#39; }} /&gt;
+            &lt;/Field.Group&gt;
+            &lt;Button type=&quot;submit&quot;&gt;Save&lt;/Button&gt;
+        &lt;/Form.Root&gt;
+    );
+};</code></pre>
             </div>
             <div class="note ok">
               <div class="row">
@@ -6132,7 +6481,26 @@ drops it. Use `readOnly` for a value the user can copy but not edit.</div>
               <div class="hint">react-hook-form&#39;s `ref` reaches the `&lt;input&gt;`, so `setFocus` and the focus
 on the first invalid field after submit both work with no ref written by
 hand.</div>
-              <pre><code>const SetFocus = () =&gt; &lt;SetFocusForm /&gt;;</code></pre>
+              <pre><code>const SetFocus = () =&gt; {
+    const methods = useForm&lt;AgencyValues &amp; PhoneValues&gt;({
+        defaultValues: { agencyName: &#39;&#39;, phone: &#39;&#39; }
+    });
+
+    return (
+        &lt;Form.Root
+            methods={methods}
+            aria-label=&quot;Agency contact&quot;
+            className=&quot;flex flex-col items-start gap-7&quot;&gt;
+            &lt;Field.Group&gt;
+                &lt;FormText name=&quot;agencyName&quot; label=&quot;Agency name&quot; /&gt;
+                &lt;FormText name=&quot;phone&quot; label=&quot;Phone number&quot; inputProps={{ type: &#39;tel&#39; }} /&gt;
+            &lt;/Field.Group&gt;
+            &lt;Button type=&quot;button&quot; variant=&quot;secondary&quot; onClick={() =&gt; methods.setFocus(&#39;phone&#39;)}&gt;
+                Focus phone
+            &lt;/Button&gt;
+        &lt;/Form.Root&gt;
+    );
+};</code></pre>
             </div>
         </div>
     
@@ -7101,7 +7469,30 @@ open?: boolean</code></pre>
               </div>
               
               <div class="hint">Controlled with `open`/`onOpenChange` — the dominant pattern in both apps. Also closes on `Escape`.</div>
-              <pre><code>const Controlled = () =&gt; &lt;ControlledExample /&gt;;</code></pre>
+              <pre><code>const Controlled = () =&gt; {
+    const [isOpen, setIsOpen] = useState(false);
+
+    return (
+        &lt;&gt;
+            &lt;Button variant=&quot;secondary&quot; onClick={() =&gt; setIsOpen(true)}&gt;
+                Open controlled
+            &lt;/Button&gt;
+            &lt;Modal.Root open={isOpen} onOpenChange={setIsOpen}&gt;
+                &lt;Modal.Content&gt;
+                    &lt;Modal.Title&gt;Controlled modal&lt;/Modal.Title&gt;
+                    &lt;Modal.Body&gt;
+                        &lt;p&gt;The open state lives in the consumer.&lt;/p&gt;
+                    &lt;/Modal.Body&gt;
+                    &lt;Modal.Footer&gt;
+                        &lt;Button variant=&quot;primary&quot; onClick={() =&gt; setIsOpen(false)}&gt;
+                            Done
+                        &lt;/Button&gt;
+                    &lt;/Modal.Footer&gt;
+                &lt;/Modal.Content&gt;
+            &lt;/Modal.Root&gt;
+        &lt;/&gt;
+    );
+};</code></pre>
             </div>
             <div class="note ok">
               <div class="row">
@@ -8273,52 +8664,50 @@ keeps its padding.</div>
               </div>
               <div>Expandable rows with a detail panel</div>
               <div class="hint">`Table.ExpandButton` toggles a `Table.ExpandedRow` detail panel under its row.</div>
-              <pre><code>const ExpandableRows = args =&gt; {
-    const Demo = () =&gt; {
-        const [openId, setOpenId] = useState&lt;string | null&gt;(ROWS[0]!.id);
-        return (
-            &lt;Table.Root {...args}&gt;
-                &lt;Table.Head&gt;
-                    &lt;Table.Row&gt;
-                        &lt;Table.Header&gt;
-                            &lt;span className=&quot;sr-only&quot;&gt;Expand&lt;/span&gt;
-                        &lt;/Table.Header&gt;
-                        &lt;Table.Header&gt;Name&lt;/Table.Header&gt;
-                        &lt;Table.Header&gt;Email&lt;/Table.Header&gt;
-                        &lt;Table.Header&gt;Role&lt;/Table.Header&gt;
-                    &lt;/Table.Row&gt;
-                &lt;/Table.Head&gt;
-                &lt;Table.Body&gt;
-                    {ROWS.slice(0, 4).map(row =&gt; (
-                        &lt;Fragment key={row.id}&gt;
-                            &lt;Table.Row&gt;
-                                &lt;Table.Cell&gt;
-                                    &lt;Table.ExpandButton
-                                        isExpanded={openId === row.id}
-                                        toggleExpanded={() =&gt; setOpenId(openId === row.id ? null : row.id)}
-                                        aria-label={`Toggle ${row.name}`}
-                                    /&gt;
+              <pre><code>const ExpandableRows = () =&gt; {
+    const [openId, setOpenId] = useState&lt;string | null&gt;(ROWS[0]!.id);
+
+    return (
+        &lt;Table.Root size=&quot;md&quot; embed={false}&gt;
+            &lt;Table.Head&gt;
+                &lt;Table.Row&gt;
+                    &lt;Table.Header&gt;
+                        &lt;span className=&quot;sr-only&quot;&gt;Expand&lt;/span&gt;
+                    &lt;/Table.Header&gt;
+                    &lt;Table.Header&gt;Name&lt;/Table.Header&gt;
+                    &lt;Table.Header&gt;Email&lt;/Table.Header&gt;
+                    &lt;Table.Header&gt;Role&lt;/Table.Header&gt;
+                &lt;/Table.Row&gt;
+            &lt;/Table.Head&gt;
+            &lt;Table.Body&gt;
+                {ROWS.slice(0, 4).map(row =&gt; (
+                    &lt;Fragment key={row.id}&gt;
+                        &lt;Table.Row&gt;
+                            &lt;Table.Cell&gt;
+                                &lt;Table.ExpandButton
+                                    isExpanded={openId === row.id}
+                                    toggleExpanded={() =&gt; setOpenId(openId === row.id ? null : row.id)}
+                                    aria-label={`Toggle ${row.name}`}
+                                /&gt;
+                            &lt;/Table.Cell&gt;
+                            &lt;Table.Cell className=&quot;font-bold&quot;&gt;{row.name}&lt;/Table.Cell&gt;
+                            &lt;Table.Cell className=&quot;text-text-default-base-secondary&quot;&gt;{row.email}&lt;/Table.Cell&gt;
+                            &lt;Table.Cell&gt;{row.role}&lt;/Table.Cell&gt;
+                        &lt;/Table.Row&gt;
+                        {openId === row.id &amp;&amp; (
+                            &lt;Table.ExpandedRow&gt;
+                                &lt;Table.Cell colSpan={4}&gt;
+                                    &lt;div className=&quot;py-2 text-text-default-base-secondary&quot;&gt;
+                                        Extended details for {row.name} — {row.amount} lifetime value.
+                                    &lt;/div&gt;
                                 &lt;/Table.Cell&gt;
-                                &lt;Table.Cell className=&quot;font-bold&quot;&gt;{row.name}&lt;/Table.Cell&gt;
-                                &lt;Table.Cell className=&quot;text-text-default-base-secondary&quot;&gt;{row.email}&lt;/Table.Cell&gt;
-                                &lt;Table.Cell&gt;{row.role}&lt;/Table.Cell&gt;
-                            &lt;/Table.Row&gt;
-                            {openId === row.id &amp;&amp; (
-                                &lt;Table.ExpandedRow&gt;
-                                    &lt;Table.Cell colSpan={4}&gt;
-                                        &lt;div className=&quot;py-2 text-text-default-base-secondary&quot;&gt;
-                                            Extended details for {row.name} — {row.amount} lifetime value.
-                                        &lt;/div&gt;
-                                    &lt;/Table.Cell&gt;
-                                &lt;/Table.ExpandedRow&gt;
-                            )}
-                        &lt;/Fragment&gt;
-                    ))}
-                &lt;/Table.Body&gt;
-            &lt;/Table.Root&gt;
-        );
-    };
-    return &lt;Demo /&gt;;
+                            &lt;/Table.ExpandedRow&gt;
+                        )}
+                    &lt;/Fragment&gt;
+                ))}
+            &lt;/Table.Body&gt;
+        &lt;/Table.Root&gt;
+    );
 };</code></pre>
             </div>
         </div>

package/mcp/manifests/components.json

@@ -248,19 +248,19 @@
         {
           "id": "components-accordion--default",
           "name": "Default",
-          "snippet": "const Default = () => <Accordion.Root type=\"single\" collapsible enclosed={false} disabled={false}>\n    <FaqItems />\n</Accordion.Root>;",
+          "snippet": "const Default = () => <Accordion.Root type=\"single\" collapsible enclosed={false} disabled={false}>\n    {FAQS.map(({ value, question, answer }) => (\n        <Accordion.Item key={value} value={value}>\n            <Accordion.Trigger>{question}</Accordion.Trigger>\n            <Accordion.Content>{answer}</Accordion.Content>\n        </Accordion.Item>\n    ))}\n</Accordion.Root>;",
           "description": "Exclusive accordion: one item open at a time, `collapsible` lets it close."
         },
         {
           "id": "components-accordion--multiple",
           "name": "Multiple",
-          "snippet": "const Multiple = () => (\n    <Accordion.Root type=\"multiple\" defaultValue={['covered', 'payment']}>\n        <FaqItems />\n    </Accordion.Root>\n);",
+          "snippet": "const Multiple = () => (\n    <Accordion.Root type=\"multiple\" defaultValue={['covered', 'payment']}>\n        {FAQS.map(({ value, question, answer }) => (\n            <Accordion.Item key={value} value={value}>\n                <Accordion.Trigger>{question}</Accordion.Trigger>\n                <Accordion.Content>{answer}</Accordion.Content>\n            </Accordion.Item>\n        ))}\n    </Accordion.Root>\n);",
           "description": "`type=\"multiple\"` lets several sections stay open at once."
         },
         {
           "id": "components-accordion--enclosed",
           "name": "Enclosed",
-          "snippet": "const Enclosed = () => (\n    <div className=\"flex flex-col gap-8\">\n        <Accordion.Root type=\"multiple\" defaultValue={['covered']}>\n            <FaqItems />\n        </Accordion.Root>\n        <Accordion.Root type=\"multiple\" enclosed defaultValue={['claim']}>\n            <FaqItems />\n        </Accordion.Root>\n    </div>\n);",
+          "snippet": "const Enclosed = () => (\n    <div className=\"flex flex-col gap-8\">\n        <Accordion.Root type=\"multiple\" defaultValue={['covered']}>\n            {FAQS.map(({ value, question, answer }) => (\n                <Accordion.Item key={value} value={value}>\n                    <Accordion.Trigger>{question}</Accordion.Trigger>\n                    <Accordion.Content>{answer}</Accordion.Content>\n                </Accordion.Item>\n            ))}\n        </Accordion.Root>\n        <Accordion.Root type=\"multiple\" enclosed defaultValue={['claim']}>\n            {FAQS.map(({ value, question, answer }) => (\n                <Accordion.Item key={value} value={value}>\n                    <Accordion.Trigger>{question}</Accordion.Trigger>\n                    <Accordion.Content>{answer}</Accordion.Content>\n                </Accordion.Item>\n            ))}\n        </Accordion.Root>\n    </div>\n);",
           "description": "`enclosed` wraps the group in a bordered card (default borderless on top)."
         },
         {
@@ -278,13 +278,13 @@
         {
           "id": "components-accordion--expand-collapse",
           "name": "Expand Collapse",
-          "snippet": "const ExpandCollapse = () => <Accordion.Root type=\"single\" collapsible>\n    <FaqItems />\n</Accordion.Root>;",
+          "snippet": "const ExpandCollapse = () => <Accordion.Root type=\"single\" collapsible>\n    {FAQS.map(({ value, question, answer }) => (\n        <Accordion.Item key={value} value={value}>\n            <Accordion.Trigger>{question}</Accordion.Trigger>\n            <Accordion.Content>{answer}</Accordion.Content>\n        </Accordion.Item>\n    ))}\n</Accordion.Root>;",
           "description": "`collapsible` lets clicking the open item close it (reach an all-closed state)."
         },
         {
           "id": "components-accordion--non-collapsible",
           "name": "Non Collapsible",
-          "snippet": "const NonCollapsible = () => <Accordion.Root type=\"single\" collapsible={false} defaultValue=\"covered\">\n    <FaqItems />\n</Accordion.Root>;",
+          "snippet": "const NonCollapsible = () => <Accordion.Root type=\"single\" collapsible={false} defaultValue=\"covered\">\n    {FAQS.map(({ value, question, answer }) => (\n        <Accordion.Item key={value} value={value}>\n            <Accordion.Trigger>{question}</Accordion.Trigger>\n            <Accordion.Content>{answer}</Accordion.Content>\n        </Accordion.Item>\n    ))}\n</Accordion.Root>;",
           "description": "Without `collapsible`, clicking the already-open item keeps it open."
         }
       ],
@@ -2788,13 +2788,13 @@
         {
           "id": "components-combobox--async-search",
           "name": "Async Search",
-          "snippet": "const AsyncSearch = () => <SuspenseSearch />;",
+          "snippet": "const AsyncSearch = () => {\n    const [query, setQuery] = useState('');\n\n    return (\n        // No `items` and `filter={null}`: the server did the filtering, the child renders what came\n        // back, and `isItemEqualToValue` keeps a re-fetched copy counting as the selected one.\n        <Combobox.Root\n            filter={null}\n            itemToStringLabel={(agency: Agency) => agency.name}\n            isItemEqualToValue={(a: Agency, b: Agency) => a.id === b.id}\n            onInputValueChange={(value, { reason }) => {\n                // Picking a row writes its label into the input; that is not a new search.\n                if (reason !== 'item-press') setQuery(value);\n            }}>\n            <Combobox.Input placeholder=\"Search agencies\" aria-label=\"Search agencies\" />\n            <Combobox.Content>\n                <Suspense fallback={<SkeletonRows />}>\n                    <AgencyItems query={query} />\n                </Suspense>\n            </Combobox.Content>\n        </Combobox.Root>\n    );\n};",
           "description": "Options fetched as you type, the way the apps load data: the rows are a component\nthat suspends on the request, so a `Suspense` boundary inside `Content` shows\nplaceholder rows until they land. Nothing tracks `loading` by hand and no stale\nlist lingers under the wait: the data is read by query, which is also what makes\nout-of-order responses harmless. Drop a `useSuspenseQuery` where `use()` is."
         },
         {
           "id": "components-combobox--async-search-with-status",
           "name": "Async Search With Status",
-          "snippet": "const AsyncSearchWithStatus = () => <StatusSearch />;",
+          "snippet": "const AsyncSearchWithStatus = () => {\n    const [results, setResults] = useState<Agency[]>([]);\n    const [isLoading, setIsLoading] = useState(false);\n    // Only the latest request may land; fast typing returns responses out of order.\n    const latestRequest = useRef(0);\n\n    const onInputValueChange = async (query: string) => {\n        const request = ++latestRequest.current;\n\n        // The previous rows go before the wait starts: a list that no longer matches what is typed\n        // must not sit under the loading state.\n        setResults([]);\n        setIsLoading(true);\n        const agencies = await searchAgencies(query);\n        if (request !== latestRequest.current) return;\n\n        setResults(agencies);\n        setIsLoading(false);\n    };\n\n    return (\n        // `filter={null}` hands filtering to the server; `filteredItems` is what came back.\n        <Combobox.Root\n            items={results}\n            filteredItems={results}\n            filter={null}\n            itemToStringLabel={(agency: Agency) => agency.name}\n            isItemEqualToValue={(a: Agency, b: Agency) => a.id === b.id}\n            onInputValueChange={onInputValueChange}>\n            <Combobox.Input placeholder=\"Search agencies\" aria-label=\"Search agencies\" />\n            <Combobox.Content aria-busy={isLoading || undefined}>\n                {/* The rows show the wait; `Status` only announces it. */}\n                <Combobox.Status className=\"sr-only\">\n                    {isLoading ? 'Searching…' : undefined}\n                </Combobox.Status>\n                {isLoading && <SkeletonRows />}\n                <Combobox.Empty>{isLoading ? undefined : 'No agencies found'}</Combobox.Empty>\n                <Combobox.List>\n                    {(agency: Agency) => (\n                        <Combobox.Item key={agency.id} value={agency}>\n                            {agency.name}\n                        </Combobox.Item>\n                    )}\n                </Combobox.List>\n            </Combobox.Content>\n        </Combobox.Root>\n    );\n};",
           "description": "The same search without Suspense, for a consumer that gets a `loading` flag from\nits data layer instead: `filter={null}`, the rows arrive through `filteredItems`,\n`Content` is marked busy and `Status` announces the wait. The list is cleared\nbefore each request and a request that is no longer the latest is dropped."
         },
         {
@@ -2806,7 +2806,7 @@
         {
           "id": "components-combobox--with-leading-icon",
           "name": "With Leading Icon",
-          "snippet": "const WithLeadingIcon = () => (\n    <Combobox.Root items={STATES}>\n        <div className=\"relative\">\n            <IconSearch\n                aria-hidden\n                className=\"pointer-events-none absolute top-1/2 left-3 z-1 size-6 -translate-y-1/2 [&>path]:fill-icon-default-base-tertiary\"\n            />\n            <Combobox.Input className=\"pl-11\" placeholder=\"Search states\" aria-label=\"Search states\" />\n        </div>\n        <Combobox.Content>\n            <Combobox.Empty>No matches found</Combobox.Empty>\n            <Combobox.List>\n                {(state: string) => (\n                    <Combobox.Item key={state} value={state}>\n                        {state}\n                    </Combobox.Item>\n                )}\n            </Combobox.List>\n        </Combobox.Content>\n    </Combobox.Root>\n);",
+          "snippet": "const WithLeadingIcon = () => (\n    <Combobox.Root items={STATES}>\n        <div className=\"relative\">\n            <IconSearch\n                aria-hidden\n                className=\"pointer-events-none absolute top-1/2 left-3 -z-hide size-6 -translate-y-1/2 [&>path]:fill-icon-default-base-tertiary\"\n            />\n            <Combobox.Input className=\"pl-11\" placeholder=\"Search states\" aria-label=\"Search states\" />\n        </div>\n        <Combobox.Content>\n            <Combobox.Empty>No matches found</Combobox.Empty>\n            <Combobox.List>\n                {(state: string) => (\n                    <Combobox.Item key={state} value={state}>\n                        {state}\n                    </Combobox.Item>\n                )}\n            </Combobox.List>\n        </Combobox.Content>\n    </Combobox.Root>\n);",
           "description": "A leading icon is composed around the input, not baked in: not every combobox\nis a search (a FEIN lookup or a template picker are not), so the component\nships no icon of its own. Until `InputGroup` lands in the design system, the\nmarketplace search fields get theirs like this — the icon overlaid, the input\npadded past it."
         },
         {
@@ -2834,13 +2834,13 @@
           "```tsx\n// Filtering handled upstream (async search): let every item through.\n<Command.Root label=\"Search options\" shouldFilter={false}>\n  <Command.Input placeholder=\"Search...\" />\n  <Command.List>...</Command.List>\n</Command.Root>\n```"
         ]
       },
-      "description": "Command is a filterable list built on `cmdk`. Type to narrow the options,\nnavigate with the arrow keys, select with Enter. It carries its own panel\nchrome, so dropping it inside a `Popover.Content` yields a combobox.",
+      "description": "Command is a filterable list built on `cmdk`. Type to narrow the options,\nnavigate with the arrow keys, select with Enter. It carries its own panel\nchrome, so dropping it inside a `Popover.Content` yields a combobox.\n`useCommandState` reads the search text and results of the surrounding\n`Command.Root` from any component rendered inside it.",
       "summary": "Filterable command palette container",
       "reactComponentMeta": {
         "displayName": "Command.Root",
         "exportName": "Command",
         "filePath": "/home/runner/work/design-system/design-system/src/command/index.ts",
-        "description": "Surface of a filterable list built on `cmdk`: type to narrow the options,\nnavigate with the arrow keys, select with Enter. Compose `Root` with `Input` /\n`List` / `Empty` / `Item`, plus `Group` when the options need sections.\n\n`Root` owns the search state, the filtering and the keyboard navigation, and\ncarries the panel chrome (border, radius, shadow), so it can be dropped\nstraight into a `Popover.Content` without extra wrapping to yield a combobox.\nReach for `DropdownMenu` instead when the options are actions and there is\nnothing to search.\n\n`label` names the search input — it is the only prop that can, see `Input`.",
+        "description": "Surface of a filterable list built on `cmdk`: type to narrow the options,\nnavigate with the arrow keys, select with Enter. Compose `Root` with `Input` /\n`List` / `Empty` / `Item`, plus `Group` when the options need sections.\n\n`Root` owns the search state, the filtering and the keyboard navigation, and\ncarries the panel chrome (border, radius, shadow), so it can be dropped\nstraight into a `Popover.Content` without extra wrapping to yield a combobox.\nReach for `DropdownMenu` instead when the options are actions and there is\nnothing to search.\n\n`label` names the search input — it is the only prop that can, see `Input`.\nA component rendered inside `Root` reads its search text and results with\n`useCommandState`, exported next to `Command`.",
         "jsDocTags": {
           "summary": [
             "Filterable command palette container"
@@ -3049,6 +3049,12 @@
           "name": "Disabled Item",
           "snippet": "const DisabledItem = () => <Command.Root label=\"Search agencies\">\n    <Command.Input placeholder=\"Search...\" />\n    <Command.List>\n        <Command.Item value=\"pinnacle\" onSelect={handleDisabledSelect}>Pinnacle Shield Insurance\n                            </Command.Item>\n        <Command.Item value=\"horizon\" disabled onSelect={handleDisabledSelect}>Horizon Risk Solutions\n                            </Command.Item>\n    </Command.List>\n    <Command.Empty>No results found.</Command.Empty>\n</Command.Root>;",
           "description": "A `disabled` row stays visible and searchable but cannot be chosen. cmdk skips it with the\narrow keys and swallows the click, and the row drops its hover and active styling so the\nlist does not invite the pointer."
+        },
+        {
+          "id": "components-command--reading-state",
+          "name": "Reading State",
+          "snippet": "const ReadingState = () => <Command.Root label=\"Search agencies\">\n    <Command.Input placeholder=\"Search agencies...\" />\n    <Command.List>\n        <Command.Item>Pinnacle Shield Insurance</Command.Item>\n        <Command.Item>Horizon Risk Solutions</Command.Item>\n        <CreateItem />\n    </Command.List>\n</Command.Root>;",
+          "description": "`useCommandState` reads the surrounding `Root` from a component inside it. Here the row\noffering to create an agency appears only when the search text matches no existing one."
         }
       ],
       "import": "import { Command } from \"@agentero/design-system\";"
@@ -5438,7 +5444,7 @@
         {
           "id": "components-fieldtext--controlled-from-context",
           "name": "Controlled From Context",
-          "snippet": "const ControlledFromContext = () => <ControlledField />;",
+          "snippet": "const ControlledFromContext = () => {\n    const [value, setValue] = useState('');\n    const [touched, setTouched] = useState(false);\n\n    const errors = touched && !value ? [{ message: 'Required' }] : undefined;\n\n    return (\n        <FieldText invalid={!!errors} required>\n            <ContextExtension\n                inputProps={{\n                    name: 'email',\n                    value,\n                    onChange: event => setValue(event.target.value),\n                    onBlur: () => setTouched(true)\n                }}\n                errors={errors}>\n                <Label>Email</Label>\n                <Input type=\"email\" onChange={onOwnChange} />\n                <Field.Error />\n            </ContextExtension>\n        </FieldText>\n    );\n};",
           "description": "The contexts are an extension point: a provider nested in the field adds\n`name`, `value`, `onChange` and `onBlur` to `InputContext`, so a bare\n`<Input />` becomes controlled, and the errors to `FieldContext`, so a bare\n`<Field.Error />` renders them — here with `useState` and no form library.\nThe input's own `onChange` still runs, chained after the provider's.",
           "summary": "Input controlled and errors supplied from outside the field"
         }
@@ -5685,14 +5691,14 @@
         {
           "id": "components-field--horizontal",
           "name": "Horizontal",
-          "snippet": "const Horizontal = () => (\n    <Field.Group className=\"w-[40rem]\">\n        <Field.Root orientation=\"horizontal\" data-testid=\"short\">\n            <Label>Full name</Label>\n            <DemoInput defaultValue=\"Rafa Moro\" className=\"w-72\" />\n        </Field.Root>\n\n        <Field.Root orientation=\"horizontal\" data-testid=\"long\">\n            <Label>Title</Label>\n            <Field.Content className=\"w-72\">\n                <DemoInput placeholder=\"Software engineer\" />\n                <Field.Description>Shown on your public profile.</Field.Description>\n            </Field.Content>\n        </Field.Root>\n\n        <Field.Root orientation=\"horizontal\" data-testid=\"switch\">\n            <Field.Content>\n                <Label>Auto-renew</Label>\n                <Field.Description>Renews the policy automatically before it expires.</Field.Description>\n            </Field.Content>\n            <DemoInput type=\"checkbox\" className=\"size-5\" />\n        </Field.Root>\n\n        <div className=\"w-[20rem]\" data-testid=\"narrow\">\n            <Field.Root orientation=\"horizontal\">\n                <Label>Email</Label>\n                <DemoInput type=\"email\" placeholder=\"you@example.com\" className=\"w-40\" />\n            </Field.Root>\n        </div>\n    </Field.Group>\n);",
+          "snippet": "const Horizontal = () => (\n    <Field.Group className=\"w-160\">\n        <Field.Root orientation=\"horizontal\" data-testid=\"short\">\n            <Label>Full name</Label>\n            <DemoInput defaultValue=\"Rafa Moro\" className=\"w-72\" />\n        </Field.Root>\n\n        <Field.Root orientation=\"horizontal\" data-testid=\"long\">\n            <Label>Title</Label>\n            <Field.Content className=\"w-72\">\n                <DemoInput placeholder=\"Software engineer\" />\n                <Field.Description>Shown on your public profile.</Field.Description>\n            </Field.Content>\n        </Field.Root>\n\n        <Field.Root orientation=\"horizontal\" data-testid=\"switch\">\n            <Field.Content>\n                <Label>Auto-renew</Label>\n                <Field.Description>Renews the policy automatically before it expires.</Field.Description>\n            </Field.Content>\n            <DemoInput type=\"checkbox\" className=\"size-5\" />\n        </Field.Root>\n\n        <div className=\"w-[20rem]\" data-testid=\"narrow\">\n            <Field.Root orientation=\"horizontal\">\n                <Label>Email</Label>\n                <DemoInput type=\"email\" placeholder=\"you@example.com\" className=\"w-40\" />\n            </Field.Root>\n        </div>\n    </Field.Group>\n);",
           "description": "`horizontal` is one row at every width. The first child fills the row and\neverything after it keeps its natural width, aligned to the right edge, so\nthe controls of stacked fields line up whatever their labels measure. Wrap a\nlabel with its description, or a control with its messages, in\n`Field.Content`. A control sets its own width: `Input` is `w-full`, so it\ngets one here.",
           "summary": "Horizontal field, one row at every width, controls right-aligned"
         },
         {
           "id": "components-field--responsive",
           "name": "Responsive",
-          "snippet": "const Responsive = () => (\n    <div className=\"flex flex-col gap-8\">\n        <div className=\"w-full max-w-[40rem]\" data-testid=\"wide\">\n            <Field.Root orientation=\"responsive\">\n                <Label>Email</Label>\n                <Field.Content className=\"@md/field:w-72\">\n                    <DemoInput type=\"email\" placeholder=\"you@example.com\" />\n                    <Field.Description>\n                        We only use this to send policy documents, and never to contact you about anything\n                        else.\n                    </Field.Description>\n                </Field.Content>\n            </Field.Root>\n        </div>\n\n        <div className=\"w-full max-w-[20rem]\" data-testid=\"narrow\">\n            <Field.Root orientation=\"responsive\">\n                <Label>Email</Label>\n                <Field.Content>\n                    <DemoInput type=\"email\" placeholder=\"you@example.com\" />\n                    <Field.Description>We only use this to send policy documents.</Field.Description>\n                </Field.Content>\n            </Field.Root>\n        </div>\n    </div>\n);",
+          "snippet": "const Responsive = () => (\n    <div className=\"flex flex-col gap-8\">\n        <div className=\"w-full max-w-160\" data-testid=\"wide\">\n            <Field.Root orientation=\"responsive\">\n                <Label>Email</Label>\n                <Field.Content className=\"@md/field:w-72\">\n                    <DemoInput type=\"email\" placeholder=\"you@example.com\" />\n                    <Field.Description>\n                        We only use this to send policy documents, and never to contact you about anything\n                        else.\n                    </Field.Description>\n                </Field.Content>\n            </Field.Root>\n        </div>\n\n        <div className=\"w-full max-w-[20rem]\" data-testid=\"narrow\">\n            <Field.Root orientation=\"responsive\">\n                <Label>Email</Label>\n                <Field.Content>\n                    <DemoInput type=\"email\" placeholder=\"you@example.com\" />\n                    <Field.Description>We only use this to send policy documents.</Field.Description>\n                </Field.Content>\n            </Field.Root>\n        </div>\n    </div>\n);",
           "description": "`responsive` stacks the parts below `28rem` and behaves like `horizontal`\nfrom there: first child fills, the rest keep their width on the right. It\nmeasures the field itself, so it needs no particular wrapper. A width that\nshould only apply once horizontal goes behind `@md/field:`.",
           "summary": "Responsive field that stacks when narrow"
         },
@@ -5720,7 +5726,7 @@
         {
           "id": "components-field--errors-from-context",
           "name": "Errors From Context",
-          "snippet": "const ErrorsFromContext = () => <FieldWithSuppliedErrors />;",
+          "snippet": "const ErrorsFromContext = () => {\n    const [value, setValue] = useState('');\n    const [touched, setTouched] = useState(false);\n\n    const errors = touched && !value ? [{ message: 'Required' }] : undefined;\n\n    return (\n        <Field.Root invalid={!!errors} required>\n            <Label>Email</Label>\n            <DemoInput\n                type=\"email\"\n                value={value}\n                onChange={event => setValue(event.target.value)}\n                onBlur={() => setTouched(true)}\n            />\n            <ErrorProvider errors={errors}>\n                <Field.Error />\n            </ErrorProvider>\n        </Field.Root>\n    );\n};",
           "description": "`FieldContext` is an extension point: re-provided under the root with the\nerrors, a bare `<Field.Error />` renders them — here with `useState` and no\nform library. `InputContext` extends the same way with `value`, `onChange`,\n`onBlur` and `name`; see `FieldText`.",
           "summary": "Errors supplied to a bare Field.Error through context"
         }
@@ -5893,7 +5899,7 @@
             "name": "control",
             "required": false,
             "type": {
-              "name": "Control<FieldValues, any, FieldValues>"
+              "name": "Control<FieldValues, any, unknown>"
             },
             "description": "The form's `control`, from `useForm()`. Defaults to the one the\nsurrounding `Form.Root` provides; pass it explicitly to get `name`\ninference without writing the generic, or when the field renders outside\na `Form.Root`. A `control` whose resolver transforms the values is\naccepted as is.",
             "defaultValue": null,
@@ -6081,63 +6087,63 @@
         {
           "id": "components-formtext--default",
           "name": "Default",
-          "snippet": "const Default = () => <AgencyNameForm\n    name=\"agencyName\"\n    label=\"Agency name\"\n    orientation=\"vertical\"\n    required\n    optional={false}\n    disabled={false}\n    readOnly={false} />;",
+          "snippet": "const Default = () => {\n    const methods = useForm<AgencyValues>({ defaultValues: { agencyName: '' } });\n\n    return (\n        <Form.Root\n            methods={methods}\n            onSubmit={onSubmit}\n            aria-label=\"Agency\"\n            className=\"flex flex-col items-start gap-7\">\n            <FormText\n                rules={{ required: 'Enter the agency name.' }}\n                inputProps={{ placeholder: 'Acme Insurance' }}\n                label=\"Agency name\"\n                orientation=\"vertical\"\n                required\n                optional={false}\n                disabled={false}\n                readOnly={false}\n                name=\"agencyName\" />\n            <Button type=\"submit\">Save</Button>\n        </Form.Root>\n    );\n};",
           "description": "The field consumers write: a `name`, a `label` and the validation rule.\nSubmitting empty renders the error and marks the input invalid; typing\nclears both and the value reaches `onSubmit`.",
           "summary": "Required text field validating on submit"
         },
         {
           "id": "components-formtext--with-description-and-tooltip",
           "name": "With Description And Tooltip",
-          "snippet": "const WithDescriptionAndTooltip = () => <TaxIdForm />;",
+          "snippet": "const WithDescriptionAndTooltip = () => {\n    const methods = useForm<TaxValues>({ defaultValues: { taxId: '' } });\n\n    return (\n        <Form.Root methods={methods} aria-label=\"Tax details\">\n            <FormText\n                name=\"taxId\"\n                label=\"Tax ID\"\n                tooltip=\"The EIN the IRS issued to the agency.\"\n                description=\"Nine digits, with or without the dash.\"\n                inputProps={{ inputMode: 'numeric', autoComplete: 'off' }}\n            />\n        </Form.Root>\n    );\n};",
           "description": "`description` is helper text under the input, announced through\n`aria-describedby`. `tooltip` is an info button beside the label for details\nworth a click; it is a sibling of the `<label>`, so the field's accessible\nname stays the label text.",
           "summary": "Helper text under the input and an info tooltip beside the label"
         },
         {
           "id": "components-formtext--optional",
           "name": "Optional",
-          "snippet": "const Optional = () => <PhoneForm />;",
+          "snippet": "const Optional = () => {\n    const methods = useForm<PhoneValues>({ defaultValues: { phone: '' } });\n\n    return (\n        <Form.Root methods={methods} aria-label=\"Contact\">\n            <FormText name=\"phone\" label=\"Phone number\" optional inputProps={{ type: 'tel' }} />\n        </Form.Root>\n    );\n};",
           "description": "The forms mark optional fields rather than required ones: `optional`\nappends a muted suffix to the label and leaves the input without the\n`required` attribute.",
           "summary": "Optional field with the \" (optional)\" label suffix"
         },
         {
           "id": "components-formtext--with-rules",
           "name": "With Rules",
-          "snippet": "const WithRules = () => <NpnForm />;",
+          "snippet": "const WithRules = () => {\n    const methods = useForm<LicenseValues>({ defaultValues: { agency: { npn: '' } } });\n\n    return (\n        <Form.Root\n            methods={methods}\n            onSubmit={onSubmit}\n            aria-label=\"License\"\n            className=\"flex flex-col items-start gap-7\">\n            <FormText<LicenseValues>\n                name=\"agency.npn\"\n                label=\"NPN\"\n                rules={{\n                    required: 'Enter your NPN.',\n                    pattern: { value: /^\\d{6,10}$/, message: 'An NPN is 6 to 10 digits.' }\n                }}\n                inputProps={{ inputMode: 'numeric' }}\n            />\n            <Button type=\"submit\">Save</Button>\n        </Form.Root>\n    );\n};",
           "description": "`rules` are react-hook-form's, and `name` accepts nested paths typed against\nthe form's values through the generic. `rules.required` validates but does\nnot mark the field required: that stays an explicit `required` prop.",
           "summary": "Nested path with validation rules, typed through the generic"
         },
         {
           "id": "components-formtext--all-errors",
           "name": "All Errors",
-          "snippet": "const AllErrors = () => <PasswordRulesForm />;",
+          "snippet": "const AllErrors = () => {\n    const methods = useForm<PasswordValues>({\n        defaultValues: { password: '' },\n        criteriaMode: 'all'\n    });\n\n    return (\n        <Form.Root\n            methods={methods}\n            onSubmit={onSubmit}\n            aria-label=\"Account security\"\n            className=\"flex flex-col items-start gap-7\">\n            <FormText\n                name=\"password\"\n                label=\"Password\"\n                required\n                inputProps={{ type: 'password' }}\n                rules={{\n                    required: 'Enter a password.',\n                    validate: {\n                        uppercase: value => /[A-Z]/.test(value) || 'At least one uppercase letter.',\n                        number: value => /[0-9]/.test(value) || 'At least one number.',\n                        length: value => value.length >= 10 || 'At least 10 characters.'\n                    }\n                }}\n            />\n            <Button type=\"submit\">Save</Button>\n        </Form.Root>\n    );\n};",
           "description": "A form set to react-hook-form's `criteriaMode: 'all'` collects every rule\nthat failed instead of stopping at the first, and the field lists them all.\nWith the default `'firstError'` a single message is rendered, as in the other\nstories.",
           "summary": "Every failed rule listed under criteriaMode 'all'"
         },
         {
           "id": "components-formtext--input-props-chaining",
           "name": "Input Props Chaining",
-          "snippet": "const InputPropsChaining = () => <MobileForm />;",
+          "snippet": "const InputPropsChaining = () => {\n    const methods = useForm<PhoneValues>({ defaultValues: { phone: '' } });\n\n    return (\n        <Form.Root methods={methods} aria-label=\"Mobile\">\n            <FormText\n                name=\"phone\"\n                label=\"Mobile\"\n                inputProps={{\n                    type: 'tel',\n                    placeholder: '5550000000',\n                    maxLength: 10,\n                    size: 'lg',\n                    onChange: event => onOwnChange(methods.getValues('phone'), event.target.value)\n                }}\n            />\n        </Form.Root>\n    );\n};",
           "description": "`inputProps` carries the input's own attributes — `type`, `placeholder`,\n`maxLength`, `size`… — and its handlers. A consumer `onChange` runs after\nreact-hook-form's: by the time it fires, `getValues` already returns the new\nvalue.",
           "summary": "Input attributes and a consumer onChange chained after the form's"
         },
         {
           "id": "components-formtext--horizontal",
           "name": "Horizontal",
-          "snippet": "const Horizontal = () => <ProfileForm />;",
+          "snippet": "const Horizontal = () => {\n    const methods = useForm<ProfileValues>({\n        defaultValues: { fullName: 'Rafa Moro', title: '' }\n    });\n\n    return (\n        <Form.Root methods={methods} aria-label=\"Profile\" className=\"w-[40rem]\">\n            <Field.Group>\n                <FormText\n                    name=\"fullName\"\n                    label=\"Full name\"\n                    orientation=\"horizontal\"\n                    inputProps={{ className: 'w-72' }}\n                    data-testid=\"short\"\n                />\n                <FormText\n                    name=\"title\"\n                    label=\"Title\"\n                    description=\"Shown on your public profile.\"\n                    orientation=\"horizontal\"\n                    inputProps={{ className: 'w-72', placeholder: 'Software engineer' }}\n                    data-testid=\"long\"\n                />\n            </Field.Group>\n        </Form.Root>\n    );\n};",
           "description": "Root props pass through: `orientation=\"horizontal\"` lays the label and the\ncontrol in a row, and `className` on the root or in `inputProps` sizes them.\nThe `Input` is full-width by default, so a settings row gives it a width.\n`responsive` stacks the field below 28rem and rows it from there.",
           "summary": "Horizontal orientation and class names through the root props"
         },
         {
           "id": "components-formtext--disabled",
           "name": "Disabled",
-          "snippet": "const Disabled = () => <AccountForm />;",
+          "snippet": "const Disabled = () => {\n    const methods = useForm<AccountValues>({\n        defaultValues: { agencyId: 'AG-48213', email: 'ops@acme-insurance.com' }\n    });\n\n    return (\n        <Form.Root\n            methods={methods}\n            onSubmit={onSubmit}\n            aria-label=\"Account\"\n            className=\"flex flex-col items-start gap-7\">\n            <Field.Group>\n                <FormText name=\"agencyId\" label=\"Agency ID\" disabled />\n                <FormText name=\"email\" label=\"Email\" inputProps={{ type: 'email' }} />\n            </Field.Group>\n            <Button type=\"submit\">Save</Button>\n        </Form.Root>\n    );\n};",
           "description": "`disabled` disables the input and marks the field, and the value still\nreaches `onSubmit` — unlike react-hook-form's own `disabled` option, which\ndrops it. Use `readOnly` for a value the user can copy but not edit.",
           "summary": "Disabled field whose value is still submitted"
         },
         {
           "id": "components-formtext--set-focus",
           "name": "Set Focus",
-          "snippet": "const SetFocus = () => <SetFocusForm />;",
+          "snippet": "const SetFocus = () => {\n    const methods = useForm<AgencyValues & PhoneValues>({\n        defaultValues: { agencyName: '', phone: '' }\n    });\n\n    return (\n        <Form.Root\n            methods={methods}\n            aria-label=\"Agency contact\"\n            className=\"flex flex-col items-start gap-7\">\n            <Field.Group>\n                <FormText name=\"agencyName\" label=\"Agency name\" />\n                <FormText name=\"phone\" label=\"Phone number\" inputProps={{ type: 'tel' }} />\n            </Field.Group>\n            <Button type=\"button\" variant=\"secondary\" onClick={() => methods.setFocus('phone')}>\n                Focus phone\n            </Button>\n        </Form.Root>\n    );\n};",
           "description": "react-hook-form's `ref` reaches the `<input>`, so `setFocus` and the focus\non the first invalid field after submit both work with no ref written by\nhand.",
           "summary": "setFocus reaches the input through the merged ref"
         }
@@ -6239,14 +6245,14 @@
         {
           "id": "components-form--default",
           "name": "Default",
-          "snippet": "const Default = () => <AgencyForm />;",
+          "snippet": "const Default = () => {\n    const methods = useForm<AgencyValues>({ defaultValues: { agencyName: '', email: '' } });\n\n    return (\n        <Form.Root\n            methods={methods}\n            onSubmit={onSubmit}\n            aria-label=\"Agency profile\"\n            className=\"flex flex-col items-start gap-7\">\n            <Field.Group>\n                <FormText\n                    name=\"agencyName\"\n                    label=\"Agency name\"\n                    required\n                    rules={{ required: 'Enter the agency name.' }}\n                />\n                <FormText\n                    name=\"email\"\n                    label=\"Email\"\n                    required\n                    rules={{ required: 'Enter the agency email.' }}\n                    inputProps={{ type: 'email', autoComplete: 'email' }}\n                />\n            </Field.Group>\n            <Button type=\"submit\">Save</Button>\n        </Form.Root>\n    );\n};",
           "description": "A form with two required fields and a submit button. Submitting empty shows\nboth errors, marks both inputs invalid and focuses the first one — proof that\nreact-hook-form's `ref` reached the inputs. Once filled in, `onSubmit`\nreceives the typed values.",
           "summary": "Form.Root with FormText fields validating on submit"
         },
         {
           "id": "components-form--no-validate",
           "name": "No Validate",
-          "snippet": "const NoValidate = () => <NicknameForm />;",
+          "snippet": "const NoValidate = () => {\n    const methods = useForm<NicknameValues>({ defaultValues: { nickname: '' } });\n\n    return (\n        <Form.Root\n            methods={methods}\n            onSubmit={onSubmit}\n            aria-label=\"Display name\"\n            className=\"flex flex-col items-start gap-7\">\n            <FormText name=\"nickname\" label=\"Display name\" required />\n            <Button type=\"submit\">Save</Button>\n        </Form.Root>\n    );\n};",
           "description": "`required` on a field reaches the native attribute, so assistive technology\nannounces it, but the form renders `noValidate`: without `rules`, submitting\nthe field empty is not blocked by the browser and `onSubmit` still runs.\nValidation is react-hook-form's alone.",
           "summary": "Native required never triggers the browser's validation bubble"
         }
@@ -6967,7 +6973,7 @@
         {
           "id": "components-modal--controlled",
           "name": "Controlled",
-          "snippet": "const Controlled = () => <ControlledExample />;",
+          "snippet": "const Controlled = () => {\n    const [isOpen, setIsOpen] = useState(false);\n\n    return (\n        <>\n            <Button variant=\"secondary\" onClick={() => setIsOpen(true)}>\n                Open controlled\n            </Button>\n            <Modal.Root open={isOpen} onOpenChange={setIsOpen}>\n                <Modal.Content>\n                    <Modal.Title>Controlled modal</Modal.Title>\n                    <Modal.Body>\n                        <p>The open state lives in the consumer.</p>\n                    </Modal.Body>\n                    <Modal.Footer>\n                        <Button variant=\"primary\" onClick={() => setIsOpen(false)}>\n                            Done\n                        </Button>\n                    </Modal.Footer>\n                </Modal.Content>\n            </Modal.Root>\n        </>\n    );\n};",
           "description": "Controlled with `open`/`onOpenChange` — the dominant pattern in both apps. Also closes on `Escape`."
         },
         {
@@ -7940,7 +7946,7 @@
         {
           "id": "components-table--expandable-rows",
           "name": "Expandable Rows",
-          "snippet": "const ExpandableRows = args => {\n    const Demo = () => {\n        const [openId, setOpenId] = useState<string | null>(ROWS[0]!.id);\n        return (\n            <Table.Root {...args}>\n                <Table.Head>\n                    <Table.Row>\n                        <Table.Header>\n                            <span className=\"sr-only\">Expand</span>\n                        </Table.Header>\n                        <Table.Header>Name</Table.Header>\n                        <Table.Header>Email</Table.Header>\n                        <Table.Header>Role</Table.Header>\n                    </Table.Row>\n                </Table.Head>\n                <Table.Body>\n                    {ROWS.slice(0, 4).map(row => (\n                        <Fragment key={row.id}>\n                            <Table.Row>\n                                <Table.Cell>\n                                    <Table.ExpandButton\n                                        isExpanded={openId === row.id}\n                                        toggleExpanded={() => setOpenId(openId === row.id ? null : row.id)}\n                                        aria-label={`Toggle ${row.name}`}\n                                    />\n                                </Table.Cell>\n                                <Table.Cell className=\"font-bold\">{row.name}</Table.Cell>\n                                <Table.Cell className=\"text-text-default-base-secondary\">{row.email}</Table.Cell>\n                                <Table.Cell>{row.role}</Table.Cell>\n                            </Table.Row>\n                            {openId === row.id && (\n                                <Table.ExpandedRow>\n                                    <Table.Cell colSpan={4}>\n                                        <div className=\"py-2 text-text-default-base-secondary\">\n                                            Extended details for {row.name} — {row.amount} lifetime value.\n                                        </div>\n                                    </Table.Cell>\n                                </Table.ExpandedRow>\n                            )}\n                        </Fragment>\n                    ))}\n                </Table.Body>\n            </Table.Root>\n        );\n    };\n    return <Demo />;\n};",
+          "snippet": "const ExpandableRows = () => {\n    const [openId, setOpenId] = useState<string | null>(ROWS[0]!.id);\n\n    return (\n        <Table.Root size=\"md\" embed={false}>\n            <Table.Head>\n                <Table.Row>\n                    <Table.Header>\n                        <span className=\"sr-only\">Expand</span>\n                    </Table.Header>\n                    <Table.Header>Name</Table.Header>\n                    <Table.Header>Email</Table.Header>\n                    <Table.Header>Role</Table.Header>\n                </Table.Row>\n            </Table.Head>\n            <Table.Body>\n                {ROWS.slice(0, 4).map(row => (\n                    <Fragment key={row.id}>\n                        <Table.Row>\n                            <Table.Cell>\n                                <Table.ExpandButton\n                                    isExpanded={openId === row.id}\n                                    toggleExpanded={() => setOpenId(openId === row.id ? null : row.id)}\n                                    aria-label={`Toggle ${row.name}`}\n                                />\n                            </Table.Cell>\n                            <Table.Cell className=\"font-bold\">{row.name}</Table.Cell>\n                            <Table.Cell className=\"text-text-default-base-secondary\">{row.email}</Table.Cell>\n                            <Table.Cell>{row.role}</Table.Cell>\n                        </Table.Row>\n                        {openId === row.id && (\n                            <Table.ExpandedRow>\n                                <Table.Cell colSpan={4}>\n                                    <div className=\"py-2 text-text-default-base-secondary\">\n                                        Extended details for {row.name} — {row.amount} lifetime value.\n                                    </div>\n                                </Table.Cell>\n                            </Table.ExpandedRow>\n                        )}\n                    </Fragment>\n                ))}\n            </Table.Body>\n        </Table.Root>\n    );\n};",
           "description": "`Table.ExpandButton` toggles a `Table.ExpandedRow` detail panel under its row.",
           "summary": "Expandable rows with a detail panel"
         }
@@ -9414,6 +9420,6 @@
   },
   "meta": {
     "docgen": "react-component-meta",
-    "durationMs": 2741
+    "durationMs": 4808
   }
 }

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@agentero/design-system",
-	"version": "0.31.4",
+	"version": "0.31.5",
 	"description": "A React component library built with Tailwind CSS v4 and Radix UI primitives",
 	"type": "module",
 	"license": "Apache-2.0",

package/src/command/command.d.ts

@@ -1,5 +1,5 @@
 import { ComponentProps } from 'react';
-import { Command as CommandPrimitive } from 'cmdk';
+import { Command as CommandPrimitive, useCommandState as useCommandStatePrimitive } from 'cmdk';
 export declare const commandRecipe: import('tailwind-variants').TVReturnType<{
     [key: string]: {
         [key: string]: import('tailwind-merge').ClassNameValue | {
@@ -85,6 +85,8 @@ type RootProps = ComponentProps<typeof CommandPrimitive>;
  * nothing to search.
  *
  * `label` names the search input — it is the only prop that can, see `Input`.
+ * A component rendered inside `Root` reads its search text and results with
+ * `useCommandState`, exported next to `Command`.
  *
  * @summary Filterable command palette container
  * @see {@link https://github.com/pacocoursey/cmdk|cmdk}
@@ -242,4 +244,38 @@ export declare const Item: {
     ({ className, ...props }: ItemProps): import("react/jsx-runtime").JSX.Element;
     displayName: string;
 };
+/**
+ * Snapshot of the surrounding `Root` that `useCommandState` selects from.
+ *
+ * @property {string} search - Current text in `Input`.
+ * @property {string} value - Value of the active item.
+ * @property {string} [selectedItemId] - DOM id of the active item.
+ * @property {{ count: number; items: Map<string, number>; groups: Set<string> }} filtered -
+ *   Result of the current search: how many items match, each matching item's score keyed by
+ *   value, and the values of the groups that still hold a match.
+ */
+export type CommandState = Parameters<Parameters<typeof useCommandStatePrimitive>[0]>[0];
+/**
+ * Reads the state of the nearest `Command.Root`: the search text, the active
+ * value and the filtered results. The selector picks the slice a component
+ * needs, and the component re-renders only when that slice changes.
+ *
+ * Call it from a component rendered inside `Command.Root`. Import it from here,
+ * not from `cmdk`: this hook and `Root` resolve the same copy of `cmdk`, so it
+ * always finds the state, even when the app installs a different `cmdk` version.
+ *
+ * @summary Hook that reads the search text and results of the surrounding Command
+ *
+ * @example
+ * ```tsx
+ * import { Command, useCommandState } from '@agentero/design-system/command';
+ *
+ * const CreateItem = ({ onCreate }: { onCreate: (name: string) => void }) => {
+ * 	const search = useCommandState(state => state.search);
+ * 	if (!search) return null;
+ * 	return <Command.Item onSelect={() => onCreate(search)}>Create "{search}"</Command.Item>;
+ * };
+ * ```
+ */
+export declare const useCommandState: <T>(selector: (state: CommandState) => T) => T;
 export {};

package/src/command/command.js

@@ -2,9 +2,9 @@
 import { IconSearch as e } from "./icons.js";
 import { tv as t } from "tailwind-variants";
 import { jsx as n, jsxs as r } from "react/jsx-runtime";
-import { Command as i } from "cmdk";
+import { Command as i, useCommandState as a } from "cmdk";
 //#region src/command/command.tsx
-var a = t({ slots: {
+var o = t({ slots: {
 	root: ["overflow-hidden rounded-md bg-bg-default-base-primary shadow-xl", "border border-border-default-base-primary"],
 	search: ["flex items-center gap-2 px-4 py-3", "border-b border-border-default-base-primary"],
 	searchIcon: "shrink-0 pointer-events-none [&>path]:fill-icon-default-base-tertiary",
@@ -18,48 +18,49 @@ var a = t({ slots: {
 		"data-[disabled=true]:cursor-default data-[disabled=true]:text-text-default-disable-primary",
 		"data-[disabled=true]:hover:bg-transparent data-[disabled=true]:data-[selected=true]:bg-transparent"
 	]
-} }), o = a(), s = ({ className: e, ...t }) => /* @__PURE__ */ n(i, {
+} }), s = o(), c = ({ className: e, ...t }) => /* @__PURE__ */ n(i, {
 	"data-slot": "command-root",
-	className: o.root({ className: e }),
+	className: s.root({ className: e }),
 	...t
 });
-s.displayName = "Command.Root";
-var c = ({ className: t, ...a }) => /* @__PURE__ */ r("div", {
+c.displayName = "Command.Root";
+var l = ({ className: t, ...a }) => /* @__PURE__ */ r("div", {
 	"data-slot": "command-search",
-	className: o.search({ className: t }),
+	className: s.search({ className: t }),
 	children: [/* @__PURE__ */ n(e, {
 		"data-slot": "command-search-icon",
-		className: o.searchIcon(),
+		className: s.searchIcon(),
 		"aria-hidden": !0
 	}), /* @__PURE__ */ n(i.Input, {
 		"data-slot": "command-input",
-		className: o.input(),
+		className: s.input(),
 		...a
 	})]
 });
-c.displayName = "Command.Input";
-var l = ({ className: e, ...t }) => /* @__PURE__ */ n(i.List, {
+l.displayName = "Command.Input";
+var u = ({ className: e, ...t }) => /* @__PURE__ */ n(i.List, {
 	"data-slot": "command-list",
-	className: o.list({ className: e }),
+	className: s.list({ className: e }),
 	...t
 });
-l.displayName = "Command.List";
-var u = ({ className: e, ...t }) => /* @__PURE__ */ n(i.Empty, {
+u.displayName = "Command.List";
+var d = ({ className: e, ...t }) => /* @__PURE__ */ n(i.Empty, {
 	"data-slot": "command-empty",
-	className: o.empty({ className: e }),
+	className: s.empty({ className: e }),
 	...t
 });
-u.displayName = "Command.Empty";
-var d = (e) => /* @__PURE__ */ n(i.Group, {
+d.displayName = "Command.Empty";
+var f = (e) => /* @__PURE__ */ n(i.Group, {
 	"data-slot": "command-group",
 	...e
 });
-d.displayName = "Command.Group";
-var f = ({ className: e, ...t }) => /* @__PURE__ */ n(i.Item, {
+f.displayName = "Command.Group";
+var p = ({ className: e, ...t }) => /* @__PURE__ */ n(i.Item, {
 	"data-slot": "command-item",
-	className: o.item({ className: e }),
+	className: s.item({ className: e }),
 	...t
 });
-f.displayName = "Command.Item";
+p.displayName = "Command.Item";
+var m = (e) => a(e);
 //#endregion
-export { u as Empty, d as Group, c as Input, f as Item, l as List, s as Root, a as commandRecipe };
+export { d as Empty, f as Group, l as Input, p as Item, u as List, c as Root, o as commandRecipe, m as useCommandState };

package/src/command/index.d.ts

@@ -1,4 +1,5 @@
-export { commandRecipe } from './command';
+export { commandRecipe, useCommandState } from './command';
+export type { CommandState } from './command';
 export declare const Command: {
     Root: {
         ({ className, ...props }: {

package/src/command/index.js

@@ -1,6 +1,6 @@
-import { Empty as e, Group as t, Input as n, Item as r, List as i, Root as a, commandRecipe as o } from "./command.js";
+import { Empty as e, Group as t, Input as n, Item as r, List as i, Root as a, commandRecipe as o, useCommandState as s } from "./command.js";
 //#region src/command/index.ts
-var s = {
+var c = {
 	Root: a,
 	Input: n,
 	List: i,
@@ -9,4 +9,4 @@ var s = {
 	Item: r
 };
 //#endregion
-export { s as Command, o as commandRecipe };
+export { c as Command, o as commandRecipe, s as useCommandState };