@agentero/design-system 0.33.0 → 0.33.1

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">35 components ok</span><span class="filter-pill ok" aria-disabled="true">286 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">35 components ok</span><span class="filter-pill ok" aria-disabled="true">288 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.7s</strong>.
+              Using <code>react-component-meta</code>. Generation took <strong>3.9s</strong>.
             </div>
     <h2 class="section-title">Components</h2>
     <div class="grid" role="list">
@@ -3463,8 +3463,8 @@ rest of the page from assistive technology, label included, and a
                 &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;Field.Description&gt;The agency this agent will be added to.&lt;/Field.Description&gt;
     &lt;/FieldText&gt;
 );</code></pre>
             </div>
@@ -5217,7 +5217,7 @@ actions outright unless the user needs to see them and understand why.</div>
       <div class="badges">
         <label for="c-12-components-field-props" class="badge ok as-toggle">6 prop types</label>
         
-        <label for="c-12-components-field-stories" class="badge ok as-toggle">16 stories</label>
+        <label for="c-12-components-field-stories" class="badge ok as-toggle">17 stories</label>
         
         
       </div>
@@ -5241,8 +5241,8 @@ absent when there is none.</div>
     <div class="kv"><span class="chip">summary: Wraps a label, control, description and error into one field</span><span class="chip">example: &lt;Field.Root invalid={!!error} required&gt;
   &lt;Field.Label&gt;Email&lt;/Field.Label&gt;
   &lt;Input type=&quot;email&quot; /&gt;
-  &lt;Field.Description&gt;We only use this for policy documents.&lt;/Field.Description&gt;
   &lt;Field.Error errors={[error]} /&gt;
+  &lt;Field.Description&gt;We only use this for policy documents.&lt;/Field.Description&gt;
 &lt;/Field.Root&gt;</span></div>
   </div>
 
@@ -5492,6 +5492,37 @@ either, the control carries no `aria-describedby` at all.</div>
     &lt;DemoInput type=&quot;email&quot; /&gt;
     &lt;Field.Error errors={[undefined]} /&gt;
 &lt;/Field.Root&gt;;</code></pre>
+            </div>
+            <div class="note ok">
+              <div class="row">
+                <span class="ex-name">Error Before Description</span>
+                <span class="badge ok">story ok</span>
+              </div>
+              <div>Error announced before the description, whenever it appears</div>
+              <div class="hint">The error sits right under the control and is announced before the
+description, even when it appears after the description is on screen and
+carries an `id` of its own.</div>
+              <pre><code>const ErrorBeforeDescription = () =&gt; {
+    const [error, setError] = useState&lt;string&gt;();
+
+    return (
+        &lt;div className=&quot;flex flex-col items-start gap-4&quot;&gt;
+            &lt;Field.Root
+                orientation=&quot;vertical&quot;
+                disabled={false}
+                readOnly={false}
+                required={false}
+                invalid={!!error}&gt;
+                &lt;Label&gt;Tax ID&lt;/Label&gt;
+                &lt;DemoInput inputMode=&quot;numeric&quot; /&gt;
+                &lt;Field.Error id=&quot;tax-id-error&quot;&gt;{error}&lt;/Field.Error&gt;
+                &lt;Field.Description&gt;Nine digits, with or without the dash.&lt;/Field.Description&gt;
+            &lt;/Field.Root&gt;
+            &lt;button type=&quot;button&quot; onClick={() =&gt; setError(&#39;Enter the tax ID.&#39;)}&gt;Validate
+                                &lt;/button&gt;
+        &lt;/div&gt;
+    );
+};</code></pre>
             </div>
             <div class="note ok">
               <div class="row">
@@ -5743,8 +5774,8 @@ and `name`, and `FieldContext` with the errors, as the last story shows.</div>
     <div class="kv"><span class="chip">summary: Field for a single-line text control, wiring the Input inside it</span><span class="chip">example: &lt;FieldText invalid={!!error} required&gt;
   &lt;Label&gt;Email&lt;/Label&gt;
   &lt;Input type=&quot;email&quot; /&gt;
-  &lt;Field.Description&gt;We only use this for policy documents.&lt;/Field.Description&gt;
   &lt;Field.Error errors={[error]} /&gt;
+  &lt;Field.Description&gt;We only use this for policy documents.&lt;/Field.Description&gt;
 &lt;/FieldText&gt;</span></div>
   </div>
 
@@ -6163,7 +6194,7 @@ Validation is react-hook-form&#39;s alone.</div>
       <div class="badges">
         <label for="c-15-components-formtext-props" class="badge ok as-toggle">15 prop types</label>
         
-        <label for="c-15-components-formtext-stories" class="badge ok as-toggle">9 stories</label>
+        <label for="c-15-components-formtext-stories" class="badge ok as-toggle">10 stories</label>
         
         
       </div>
@@ -6226,9 +6257,9 @@ control?: Control&lt;FieldValues, any, unknown&gt;
 controlId?: string
 
 /**
- * Helper text shown under the control and announced through its
- * `aria-describedby`. Use it for guidance the user needs before typing; put
- * details worth a click in `tooltip` instead.
+ * Helper text shown under the control, below the error when there is one,
+ * and announced through its `aria-describedby`. Use it for guidance the
+ * user needs before typing; put details worth a click in `tooltip` instead.
  */
 description?: ReactNode
 
@@ -6442,6 +6473,36 @@ not mark the field required: that stays an explicit `required` prop.</div>
             &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">
+                <span class="ex-name">Error And Description</span>
+                <span class="badge ok">story ok</span>
+              </div>
+              <div>Error under the input, above the helper text</div>
+              <div class="hint">The error sits right under the input and the description stays below it, so
+the message lands next to the value it is about. Screen readers announce
+them in the same order.</div>
+              <pre><code>const ErrorAndDescription = () =&gt; {
+    const methods = useForm&lt;TaxValues&gt;({ defaultValues: { taxId: &#39;&#39; } });
+
+    return (
+        &lt;Form.Root
+            methods={methods}
+            onSubmit={onSubmit}
+            aria-label=&quot;Tax details&quot;
+            className=&quot;flex flex-col items-start gap-7&quot;&gt;
+            &lt;FormText
+                name=&quot;taxId&quot;
+                label=&quot;Tax ID&quot;
+                description=&quot;Nine digits, with or without the dash.&quot;
+                rules={{ required: &#39;Enter the tax ID.&#39; }}
+                inputProps={{ inputMode: &#39;numeric&#39;, autoComplete: &#39;off&#39; }}
+            /&gt;
+            &lt;Button type=&quot;submit&quot;&gt;Save&lt;/Button&gt;
+        &lt;/Form.Root&gt;
+    );
 };</code></pre>
             </div>
             <div class="note ok">

package/mcp/manifests/components.json

@@ -2850,7 +2850,7 @@
         {
           "id": "components-combobox--inside-field-text",
           "name": "Inside Field Text",
-          "snippet": "const InsideFieldText = () => (\n    <FieldText invalid required>\n        <Label>Agency</Label>\n        <Combobox.Root items={STATES}>\n            <Combobox.Input placeholder=\"Search agencies\" />\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        <Field.Description>The agency this agent will be added to.</Field.Description>\n        <Field.Error errors={[{ message: 'Pick an agency from the list' }]} />\n    </FieldText>\n);",
+          "snippet": "const InsideFieldText = () => (\n    <FieldText invalid required>\n        <Label>Agency</Label>\n        <Combobox.Root items={STATES}>\n            <Combobox.Input placeholder=\"Search agencies\" />\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        <Field.Error errors={[{ message: 'Pick an agency from the list' }]} />\n        <Field.Description>The agency this agent will be added to.</Field.Description>\n    </FieldText>\n);",
           "description": "Dropped into a `FieldText`, the input takes the label, the description and\nthe error from the field with nothing wired by hand: `Combobox.Input` reads the\nsame `InputContext` the plain `Input` does. It also points `aria-labelledby`\nat the label, so the name survives the list opening: Base UI then hides the\nrest of the page from assistive technology, label included, and a\n`<label for>` alone would stop naming the input."
         },
         {
@@ -5295,7 +5295,7 @@
           "Field for a single-line text control, wiring the Input inside it"
         ],
         "example": [
-          "<FieldText invalid={!!error} required>\n  <Label>Email</Label>\n  <Input type=\"email\" />\n  <Field.Description>We only use this for policy documents.</Field.Description>\n  <Field.Error errors={[error]} />\n</FieldText>"
+          "<FieldText invalid={!!error} required>\n  <Label>Email</Label>\n  <Input type=\"email\" />\n  <Field.Error errors={[error]} />\n  <Field.Description>We only use this for policy documents.</Field.Description>\n</FieldText>"
         ]
       },
       "description": "FieldText is a `Field.Root` for a single-line text control. It provides\n`InputContext`, so the `Input` inside associates itself with the label and\nthe messages and takes `invalid`, `required`, `disabled` and `readOnly` from\nthe field — no `id`, `htmlFor`, `aria-describedby` or `aria-invalid` written\nby hand.\n\nIt knows nothing about form libraries, and its contexts compose: a provider\nnested inside it can extend `InputContext` with `value`, `onChange`, `onBlur`\nand `name`, and `FieldContext` with the errors, as the last story shows.",
@@ -5310,7 +5310,7 @@
             "Field for a single-line text control, wiring the Input inside it"
           ],
           "example": [
-            "<FieldText invalid={!!error} required>\n  <Label>Email</Label>\n  <Input type=\"email\" />\n  <Field.Description>We only use this for policy documents.</Field.Description>\n  <Field.Error errors={[error]} />\n</FieldText>"
+            "<FieldText invalid={!!error} required>\n  <Label>Email</Label>\n  <Input type=\"email\" />\n  <Field.Error errors={[error]} />\n  <Field.Description>We only use this for policy documents.</Field.Description>\n</FieldText>"
           ]
         },
         "props": {
@@ -5504,7 +5504,7 @@
           "Wraps a label, control, description and error into one field"
         ],
         "example": [
-          "<Field.Root invalid={!!error} required>\n  <Field.Label>Email</Field.Label>\n  <Input type=\"email\" />\n  <Field.Description>We only use this for policy documents.</Field.Description>\n  <Field.Error errors={[error]} />\n</Field.Root>"
+          "<Field.Root invalid={!!error} required>\n  <Field.Label>Email</Field.Label>\n  <Input type=\"email\" />\n  <Field.Error errors={[error]} />\n  <Field.Description>We only use this for policy documents.</Field.Description>\n</Field.Root>"
         ]
       },
       "description": "Field lays out a single form field — label, control, helper text and error —\nand wires the accessibility relationships between them. `Field.Root`\ngenerates the ids and shares them through context: `Label` reads\n`LabelContext`, `Field.Description` and `Field.Error` read `FieldContext`,\nand a `Field<X>` such as `FieldText` provides the control's context. Nobody\npasses an `id` by hand.\n\nPresentational and form-library agnostic: pass `invalid` and the error\nmessages from whatever validates the form. Spacing between fields belongs to\n`Field.Group`, never to a margin on the field itself.\n\n`Field.Description` and `Field.Error` register themselves with the root, so\nthe control's `aria-describedby` lists exactly the messages on screen and is\nabsent when there is none.",
@@ -5519,7 +5519,7 @@
             "Wraps a label, control, description and error into one field"
           ],
           "example": [
-            "<Field.Root invalid={!!error} required>\n  <Field.Label>Email</Field.Label>\n  <Input type=\"email\" />\n  <Field.Description>We only use this for policy documents.</Field.Description>\n  <Field.Error errors={[error]} />\n</Field.Root>"
+            "<Field.Root invalid={!!error} required>\n  <Field.Label>Email</Field.Label>\n  <Input type=\"email\" />\n  <Field.Error errors={[error]} />\n  <Field.Description>We only use this for policy documents.</Field.Description>\n</Field.Root>"
           ]
         },
         "props": {
@@ -5718,6 +5718,13 @@
           "description": "`Field.Error` renders nothing without a message, so it can stay mounted and\nreceive `undefined` entries while the field is valid. With no description\neither, the control carries no `aria-describedby` at all.",
           "summary": "Error stays mounted and renders nothing while valid"
         },
+        {
+          "id": "components-field--error-before-description",
+          "name": "Error Before Description",
+          "snippet": "const ErrorBeforeDescription = () => {\n    const [error, setError] = useState<string>();\n\n    return (\n        <div className=\"flex flex-col items-start gap-4\">\n            <Field.Root\n                orientation=\"vertical\"\n                disabled={false}\n                readOnly={false}\n                required={false}\n                invalid={!!error}>\n                <Label>Tax ID</Label>\n                <DemoInput inputMode=\"numeric\" />\n                <Field.Error id=\"tax-id-error\">{error}</Field.Error>\n                <Field.Description>Nine digits, with or without the dash.</Field.Description>\n            </Field.Root>\n            <button type=\"button\" onClick={() => setError('Enter the tax ID.')}>Validate\n                                </button>\n        </div>\n    );\n};",
+          "description": "The error sits right under the control and is announced before the\ndescription, even when it appears after the description is on screen and\ncarries an `id` of its own.",
+          "summary": "Error announced before the description, whenever it appears"
+        },
         {
           "id": "components-field--disabled",
           "name": "Disabled",
@@ -5795,7 +5802,7 @@
         "displayName": "FormText",
         "exportName": "FormText",
         "filePath": "/home/runner/work/design-system/design-system/src/form-text/index.ts",
-        "description": "A complete text field bound to one react-hook-form value: label, `Input`,\nhelper text and validation error, laid out in the standard order and wired\nthrough `useController`. It renders inside a `Form.Root`, which provides the\nform, and needs only a `name`, which on a typed form must point at a string\n(`FormTextPath`). The `required`, `invalid` and error states\nreach the label, the input's `aria-*` attributes and the message with no\nids written by hand.\n\nUse it for the common case: a labelled single-line input in a form. When\nthe layout is different — an input with addons, another control, a\nmessage rendered elsewhere — compose the primitives yourself:\n`useController` with [FieldText](?path=/docs/components-fieldtext--docs),\n`Label`, `Input`, `Field.Description` and `Field.Error`. `FormText` adds no\nbehaviour of its own over that composition.\n\nErrors come from `useController`'s per-field state, never from\n`formState.errors`, so the message stays fresh under the React Compiler.\nWith `criteriaMode: 'all'` on the form the error carries every rule that\nfailed and `Field.Error` lists them all. An error on an array or object path\n(`error.root`) is not this field's: render a `Field.Error` for it where the\ngroup lives.",
+        "description": "A complete text field bound to one react-hook-form value: label, `Input`,\nvalidation error and helper text, laid out in the standard order and wired\nthrough `useController`. It renders inside a `Form.Root`, which provides the\nform, and needs only a `name`, which on a typed form must point at a string\n(`FormTextPath`). The `required`, `invalid` and error states\nreach the label, the input's `aria-*` attributes and the message with no\nids written by hand.\n\nUse it for the common case: a labelled single-line input in a form. When\nthe layout is different — an input with addons, another control, a\nmessage rendered elsewhere — compose the primitives yourself:\n`useController` with [FieldText](?path=/docs/components-fieldtext--docs),\n`Label`, `Input`, `Field.Description` and `Field.Error`. `FormText` adds no\nbehaviour of its own over that composition.\n\nErrors come from `useController`'s per-field state, never from\n`formState.errors`, so the message stays fresh under the React Compiler.\nWith `criteriaMode: 'all'` on the form the error carries every rule that\nfailed and `Field.Error` lists them all. An error on an array or object path\n(`error.root`) is not this field's: render a `Field.Error` for it where the\ngroup lives.",
         "jsDocTags": {
           "summary": [
             "Label, Input, description and error bound to one react-hook-form field"
@@ -6021,7 +6028,7 @@
             "type": {
               "name": "ReactNode"
             },
-            "description": "Helper text shown under the control and announced through its\n`aria-describedby`. Use it for guidance the user needs before typing; put\ndetails worth a click in `tooltip` instead.",
+            "description": "Helper text shown under the control, below the error when there is one,\nand announced through its `aria-describedby`. Use it for guidance the\nuser needs before typing; put details worth a click in `tooltip` instead.",
             "defaultValue": null,
             "parent": {
               "name": "FormTextProps",
@@ -6156,6 +6163,13 @@
           "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--error-and-description",
+          "name": "Error And Description",
+          "snippet": "const ErrorAndDescription = () => {\n    const methods = useForm<TaxValues>({ defaultValues: { taxId: '' } });\n\n    return (\n        <Form.Root\n            methods={methods}\n            onSubmit={onSubmit}\n            aria-label=\"Tax details\"\n            className=\"flex flex-col items-start gap-7\">\n            <FormText\n                name=\"taxId\"\n                label=\"Tax ID\"\n                description=\"Nine digits, with or without the dash.\"\n                rules={{ required: 'Enter the tax ID.' }}\n                inputProps={{ inputMode: 'numeric', autoComplete: 'off' }}\n            />\n            <Button type=\"submit\">Save</Button>\n        </Form.Root>\n    );\n};",
+          "description": "The error sits right under the input and the description stays below it, so\nthe message lands next to the value it is about. Screen readers announce\nthem in the same order.",
+          "summary": "Error under the input, above the helper text"
+        },
         {
           "id": "components-formtext--all-errors",
           "name": "All Errors",
@@ -9696,6 +9710,6 @@
   },
   "meta": {
     "docgen": "react-component-meta",
-    "durationMs": 4742
+    "durationMs": 3879
   }
 }

package/package.json

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

package/src/field/context.d.ts

@@ -11,6 +11,8 @@ export type FieldErrorLike = {
      */
     types?: Record<string, string | string[] | boolean | undefined>;
 } | undefined;
+/** What a registered message is, which sets its place in `aria-describedby`. */
+export type FieldMessageKind = 'error' | 'description';
 /**
  * State of the surrounding `Field.Root`, shared with the Field family
  * (`Field.Description`, `Field.Error`) and with controls that have no context
@@ -39,9 +41,11 @@ export type FieldContextValue = {
     /**
      * Adds a message element to `describedBy` and returns the function that
      * removes it. `Field.Description` and `Field.Error` call it from a layout
-     * effect; a custom message element can do the same.
+     * effect; a custom message element can do the same. Errors are listed first,
+     * then descriptions, then messages registered without a `kind`, each in the
+     * order they registered.
      */
-    registerMessage: (id: string) => () => void;
+    registerMessage: (id: string, kind?: FieldMessageKind) => () => void;
     invalid: boolean;
     disabled: boolean;
     readOnly: boolean;

package/src/field/field.d.ts

@@ -141,8 +141,8 @@ export type FieldRootProps = ComponentPropsWithRef<'div'> & {
  * <Field.Root invalid={!!error} required>
  *   <Field.Label>Email</Field.Label>
  *   <Input type="email" />
- *   <Field.Description>We only use this for policy documents.</Field.Description>
  *   <Field.Error errors={[error]} />
+ *   <Field.Description>We only use this for policy documents.</Field.Description>
  * </Field.Root>
  */
 export declare const Root: {
@@ -201,7 +201,9 @@ export declare const Description: {
 };
 /**
  * Validation feedback for the field, announced as an alert when it appears.
- * Renders nothing without a message, so it can stay mounted unconditionally;
+ * Place it right after the control, before `Field.Description`: the control's
+ * `aria-describedby` reads the error first as well. Renders nothing without a
+ * message, so it can stay mounted unconditionally;
  * set `invalid` on `Field.Root` alongside it. Takes `children` or an `errors`
  * array, and a form adapter can supply `errors` through `FieldContext` so a
  * bare `<Field.Error />` renders them. One per field: it takes the field's

package/src/field/field.js

@@ -38,31 +38,34 @@ var m = s({
 		] }
 	} },
 	defaultVariants: { orientation: "vertical" }
-}), h = m(), g = ({ className: t, ...n }) => /* @__PURE__ */ f("div", {
+}), h = m(), g = (e) => e === "error" ? 0 : e === "description" ? 1 : 2, _ = ({ className: t, ...n }) => /* @__PURE__ */ f("div", {
 	"data-slot": "field-group",
 	className: e(h.group(), t),
 	...n
 });
-g.displayName = "Field.Group";
-var _ = ({ className: n, orientation: r = "vertical", invalid: a = !1, disabled: o = !1, readOnly: s = !1, required: u = !1, controlId: p, ...m }) => {
-	let g = l(), _ = p ?? `${g}-control`, v = `${g}-label`, y = `${g}-description`, b = `${g}-error`, [x, S] = d([]), C = c((e) => (S((t) => t.includes(e) ? t : [...t, e]), () => S((t) => t.filter((t) => t !== e))), []), w = {
-		controlId: _,
-		labelId: v,
-		descriptionId: y,
-		errorId: b,
-		describedBy: [...[y, b].filter((e) => x.includes(e)), ...x.filter((e) => e !== y && e !== b)].join(" ") || void 0,
-		registerMessage: C,
+_.displayName = "Field.Group";
+var v = ({ className: n, orientation: r = "vertical", invalid: a = !1, disabled: o = !1, readOnly: s = !1, required: u = !1, controlId: p, ...m }) => {
+	let _ = l(), v = p ?? `${_}-control`, y = `${_}-label`, b = `${_}-description`, x = `${_}-error`, [S, C] = d([]), w = c((e, t) => (C((n) => n.some((t) => t.id === e) ? n : [...n, {
+		id: e,
+		kind: t
+	}]), () => C((t) => t.filter((t) => t.id !== e))), []), T = {
+		controlId: v,
+		labelId: y,
+		descriptionId: b,
+		errorId: x,
+		describedBy: [...S].sort((e, t) => g(e.kind) - g(t.kind)).map((e) => e.id).join(" ") || void 0,
+		registerMessage: w,
 		invalid: a,
 		disabled: o,
 		readOnly: s,
 		required: u
 	};
 	return /* @__PURE__ */ f(i, {
-		value: w,
+		value: T,
 		children: /* @__PURE__ */ f(t, {
 			value: {
-				id: v,
-				htmlFor: _,
+				id: y,
+				htmlFor: v,
 				required: u || void 0
 			},
 			children: /* @__PURE__ */ f("div", {
@@ -77,14 +80,14 @@ var _ = ({ className: n, orientation: r = "vertical", invalid: a = !1, disabled:
 		})
 	});
 };
-_.displayName = "Field.Root";
-var v = ({ className: t, ...n }) => /* @__PURE__ */ f("div", {
+v.displayName = "Field.Root";
+var y = ({ className: t, ...n }) => /* @__PURE__ */ f("div", {
 	"data-slot": "field-content",
 	className: e(h.content(), t),
 	...n
 });
-v.displayName = "Field.Content";
-var y = ({ tooltip: e, tooltipSide: t, ...i }) => /* @__PURE__ */ p("div", {
+y.displayName = "Field.Content";
+var b = ({ tooltip: e, tooltipSide: t, ...i }) => /* @__PURE__ */ p("div", {
 	"data-slot": "field-label",
 	className: h.label(),
 	children: [/* @__PURE__ */ f(n, { ...i }), e && /* @__PURE__ */ f(r, {
@@ -100,23 +103,23 @@ var y = ({ tooltip: e, tooltipSide: t, ...i }) => /* @__PURE__ */ p("div", {
 		})
 	})]
 });
-y.displayName = "Field.Label";
-var b = ({ className: t, id: n, ...r }) => {
+b.displayName = "Field.Label";
+var x = ({ className: t, id: n, ...r }) => {
 	let i = a(), o = n ?? i?.descriptionId, s = i?.registerMessage;
-	return u(() => o ? s?.(o) : void 0, [s, o]), /* @__PURE__ */ f("p", {
+	return u(() => o ? s?.(o, "description") : void 0, [s, o]), /* @__PURE__ */ f("p", {
 		"data-slot": "field-description",
 		id: o,
 		className: e(h.description(), t),
 		...r
 	});
 };
-b.displayName = "Field.Description";
-var x = (e) => {
+x.displayName = "Field.Description";
+var S = (e) => {
 	let t = Object.values(e?.types ?? {}).flat().filter((e) => typeof e == "string" && e.length > 0);
 	return t.length ? t : e?.message ? [e.message] : [];
-}, S = ({ className: t, children: n, errors: r, id: i, ...o }) => {
-	let s = a(), c = i ?? s?.errorId, l = r ?? s?.errors, d = s?.registerMessage, p = [...new Set(l?.flatMap(x))], m = n ?? (p.length > 1 ? /* @__PURE__ */ f("ul", { children: p.map((e) => /* @__PURE__ */ f("li", { children: e }, e)) }) : p[0]), g = !!m;
-	return u(() => g && c ? d?.(c) : void 0, [
+}, C = ({ className: t, children: n, errors: r, id: i, ...o }) => {
+	let s = a(), c = i ?? s?.errorId, l = r ?? s?.errors, d = s?.registerMessage, p = [...new Set(l?.flatMap(S))], m = n ?? (p.length > 1 ? /* @__PURE__ */ f("ul", { children: p.map((e) => /* @__PURE__ */ f("li", { children: e }, e)) }) : p[0]), g = !!m;
+	return u(() => g && c ? d?.(c, "error") : void 0, [
 		d,
 		g,
 		c
@@ -129,6 +132,6 @@ var x = (e) => {
 		children: m
 	}) : null;
 };
-S.displayName = "Field.Error";
+C.displayName = "Field.Error";
 //#endregion
-export { v as Content, b as Description, S as Error, g as Group, y as Label, _ as Root, m as fieldRecipe };
+export { y as Content, x as Description, C as Error, _ as Group, b as Label, v as Root, m as fieldRecipe };

package/src/field/index.d.ts

@@ -1,7 +1,7 @@
 export { fieldRecipe } from './field';
 export { FieldContext, useFieldContext } from './context';
 export type { FieldContentProps, FieldGroupProps, FieldLabelProps, FieldRootProps, FieldVariants } from './field';
-export type { FieldContextValue, FieldDescriptionProps, FieldErrorLike, FieldErrorProps } from './context';
+export type { FieldContextValue, FieldDescriptionProps, FieldErrorLike, FieldErrorProps, FieldMessageKind } from './context';
 export declare const Field: {
     Root: {
         ({ className, orientation, invalid, disabled, readOnly, required, controlId: controlIdProp, ...props }: import('./field').FieldRootProps): import("react/jsx-runtime").JSX.Element;

package/src/field-text/field-text.d.ts

@@ -18,8 +18,8 @@ export type FieldTextProps = FieldRootProps;
  * <FieldText invalid={!!error} required>
  *   <Label>Email</Label>
  *   <Input type="email" />
- *   <Field.Description>We only use this for policy documents.</Field.Description>
  *   <Field.Error errors={[error]} />
+ *   <Field.Description>We only use this for policy documents.</Field.Description>
  * </FieldText>
  */
 export declare const FieldText: {

package/src/form-text/form-text.d.ts

@@ -55,9 +55,9 @@ export type FormTextProps<TFieldValues extends FieldValues = FieldValues, TName
     /** The caption, rendered as the field's label. Text in almost every case. */
     label: ReactNode;
     /**
-     * Helper text shown under the control and announced through its
-     * `aria-describedby`. Use it for guidance the user needs before typing; put
-     * details worth a click in `tooltip` instead.
+     * Helper text shown under the control, below the error when there is one,
+     * and announced through its `aria-describedby`. Use it for guidance the
+     * user needs before typing; put details worth a click in `tooltip` instead.
      */
     description?: ReactNode;
     /**
@@ -96,7 +96,7 @@ export type FormTextProps<TFieldValues extends FieldValues = FieldValues, TName
 };
 /**
  * A complete text field bound to one react-hook-form value: label, `Input`,
- * helper text and validation error, laid out in the standard order and wired
+ * validation error and helper text, laid out in the standard order and wired
  * through `useController`. It renders inside a `Form.Root`, which provides the
  * form, and needs only a `name`, which on a typed form must point at a string
  * (`FormTextPath`). The `required`, `invalid` and error states

package/src/form-text/form-text.js

@@ -30,8 +30,8 @@ var s = ({ name: s, control: c, rules: l, shouldUnregister: u, disabled: d, labe
 			children: f
 		}), /* @__PURE__ */ a(t.Content, { children: [
 			/* @__PURE__ */ i(n, { ...e(x, _ ?? {}) }),
-			p && /* @__PURE__ */ i(t.Description, { children: p }),
-			/* @__PURE__ */ i(t.Error, { errors: b.error ? [b.error] : void 0 })
+			/* @__PURE__ */ i(t.Error, { errors: b.error ? [b.error] : void 0 }),
+			p && /* @__PURE__ */ i(t.Description, { children: p })
 		] })]
 	});
 };