@agentero/design-system 0.27.1 → 0.29.0

package/mcp/manifests/components.json

@@ -4404,6 +4404,1023 @@
       ],
       "import": "import { Button, DropdownMenu } from \"@agentero/design-system\";"
     },
+    "components-fieldtext": {
+      "id": "components-fieldtext",
+      "name": "FieldText",
+      "path": "./src/field-text/field-text.stories.tsx",
+      "jsDocTags": {
+        "summary": [
+          "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>"
+        ]
+      },
+      "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.",
+      "summary": "Field for a single-line text control, wiring the Input inside it",
+      "reactComponentMeta": {
+        "displayName": "FieldText",
+        "exportName": "FieldText",
+        "filePath": "/home/runner/work/design-system/design-system/src/field-text/index.ts",
+        "description": "A `Field.Root` for a single-line text control: it provides `InputContext`,\nso the `Input` inside associates itself with the label and the messages and\ntakes `invalid`, `required`, `disabled` and `readOnly` from the field. Every\nother part (`Label`, `Field.Description`, `Field.Error`) works as in any\nfield.\n\nForm-library agnostic, and its contexts compose: a provider nested inside it\ncan extend `InputContext` with `name`, `value`, `onChange`, `onBlur` and\n`ref` to control the `Input`, and `FieldContext` with the errors, on top of\nthe wiring `FieldText` already set.",
+        "jsDocTags": {
+          "summary": [
+            "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>"
+          ]
+        },
+        "props": {
+          "orientation": {
+            "name": "orientation",
+            "required": false,
+            "type": {
+              "name": "enum",
+              "raw": "\"horizontal\" | \"vertical\" | \"responsive\"",
+              "value": [
+                {
+                  "value": "\"horizontal\""
+                },
+                {
+                  "value": "\"vertical\""
+                },
+                {
+                  "value": "\"responsive\""
+                }
+              ]
+            },
+            "description": "Layout of the field. `vertical` (default) stacks label, control and\nmessages. `horizontal` is one row at every width: the first child fills it\nand the rest keep their natural width, aligned to the right, so the\ncontrols of stacked fields line up. `responsive` stacks below `28rem` and\nbehaves like `horizontal` from there, measured on the field itself, so it\nneeds no particular wrapper. In both, `Field.Content` groups a control with\nits messages, or a label with its description.",
+            "defaultValue": null,
+            "parent": {
+              "name": "FieldRootProps",
+              "fileName": "src/field/field.tsx"
+            },
+            "declarations": [
+              {
+                "name": "TypeLiteral",
+                "fileName": "src/field/field.tsx"
+              }
+            ]
+          },
+          "invalid": {
+            "name": "invalid",
+            "required": false,
+            "type": {
+              "name": "boolean"
+            },
+            "description": "Marks the field as failing validation: sets `data-invalid` on the root and\n`aria-invalid` on the control through its context, which drives the\ncontrol's destructive border. The label keeps its color by design.",
+            "defaultValue": null,
+            "parent": {
+              "name": "FieldRootProps",
+              "fileName": "src/field/field.tsx"
+            },
+            "declarations": [
+              {
+                "name": "TypeLiteral",
+                "fileName": "src/field/field.tsx"
+              }
+            ]
+          },
+          "disabled": {
+            "name": "disabled",
+            "required": false,
+            "type": {
+              "name": "boolean"
+            },
+            "description": "Disables the control through its context and sets `data-disabled` on the root.",
+            "defaultValue": null,
+            "parent": {
+              "name": "FieldRootProps",
+              "fileName": "src/field/field.tsx"
+            },
+            "declarations": [
+              {
+                "name": "TypeLiteral",
+                "fileName": "src/field/field.tsx"
+              }
+            ]
+          },
+          "readOnly": {
+            "name": "readOnly",
+            "required": false,
+            "type": {
+              "name": "boolean"
+            },
+            "description": "Makes the control read-only through its context (focusable and copyable,\nnot editable, still submitted) and sets `data-readonly` on the root.",
+            "defaultValue": null,
+            "parent": {
+              "name": "FieldRootProps",
+              "fileName": "src/field/field.tsx"
+            },
+            "declarations": [
+              {
+                "name": "TypeLiteral",
+                "fileName": "src/field/field.tsx"
+              }
+            ]
+          },
+          "required": {
+            "name": "required",
+            "required": false,
+            "type": {
+              "name": "boolean"
+            },
+            "description": "Single source of truth for a required field: the `Label` shows its\nasterisk and the control receives `required`, both through context.",
+            "defaultValue": null,
+            "parent": {
+              "name": "FieldRootProps",
+              "fileName": "src/field/field.tsx"
+            },
+            "declarations": [
+              {
+                "name": "TypeLiteral",
+                "fileName": "src/field/field.tsx"
+              }
+            ]
+          },
+          "controlId": {
+            "name": "controlId",
+            "required": false,
+            "type": {
+              "name": "string"
+            },
+            "description": "`id` for the control. Generated when omitted. Set it here, not on the\ncontrol, so the label and the messages keep pointing at the right element.",
+            "defaultValue": null,
+            "parent": {
+              "name": "FieldRootProps",
+              "fileName": "src/field/field.tsx"
+            },
+            "declarations": [
+              {
+                "name": "TypeLiteral",
+                "fileName": "src/field/field.tsx"
+              }
+            ]
+          }
+        }
+      },
+      "stories": [
+        {
+          "id": "components-fieldtext--default",
+          "name": "Default",
+          "snippet": "const Default = () => <FieldText\n    orientation=\"vertical\"\n    invalid={false}\n    disabled={false}\n    readOnly={false}\n    required={false}>\n    <Label>Email</Label>\n    <Input type=\"email\" placeholder=\"you@example.com\" />\n    <Field.Description>We only use this to send policy documents.</Field.Description>\n</FieldText>;",
+          "description": "The composition consumers write: a label, the design system's `Input` and\nhelper text. The label points at the input and the input is described by the\ntext, all through context.",
+          "summary": "Label, Input and description wired with no ids"
+        },
+        {
+          "id": "components-fieldtext--required",
+          "name": "Required",
+          "snippet": "const Required = () => <FieldText\n    orientation=\"vertical\"\n    invalid={false}\n    disabled={false}\n    readOnly={false}\n    required>\n    <Label>Full name</Label>\n    <Input placeholder=\"Jane Doe\" />\n</FieldText>;",
+          "description": "`required` on the field reaches both the label's asterisk and the input's\n`required` attribute.",
+          "summary": "Required field driven from the root alone"
+        },
+        {
+          "id": "components-fieldtext--invalid",
+          "name": "Invalid",
+          "snippet": "const Invalid = () => <FieldText\n    orientation=\"vertical\"\n    invalid\n    disabled={false}\n    readOnly={false}\n    required={false}>\n    <Label>Email</Label>\n    <Input type=\"email\" defaultValue=\"not-an-email\" />\n    <Field.Error errors={[{ message: 'Enter a valid email address.' }]} />\n</FieldText>;",
+          "description": "`invalid` on the field sets `aria-invalid` on the input, which drives its\ndestructive border, and the error is announced with the input.",
+          "summary": "Invalid field with the Input styled by aria-invalid"
+        },
+        {
+          "id": "components-fieldtext--disabled",
+          "name": "Disabled",
+          "snippet": "const Disabled = () => <FieldText\n    orientation=\"vertical\"\n    invalid={false}\n    disabled\n    readOnly={false}\n    required={false}>\n    <Label>Agency</Label>\n    <Input defaultValue=\"Acme Insurance\" />\n</FieldText>;",
+          "description": "`disabled` on the field disables the input through context.",
+          "summary": "Disabled field driven from the root"
+        },
+        {
+          "id": "components-fieldtext--read-only",
+          "name": "Read Only",
+          "snippet": "const ReadOnly = () => <FieldText\n    orientation=\"vertical\"\n    invalid={false}\n    disabled={false}\n    readOnly\n    required={false}>\n    <Label>Policy number</Label>\n    <Input defaultValue=\"POL-2049-118\" />\n    <Field.Description>Assigned by the carrier; contact support to change it.</Field.Description>\n</FieldText>;",
+          "description": "`readOnly` on the field reaches the input through context. The value stays\nfocusable, copyable and submitted, and the input looks like any other.",
+          "summary": "Read-only field driven from the root"
+        },
+        {
+          "id": "components-fieldtext--own-props-win",
+          "name": "Own Props Win",
+          "snippet": "const OwnPropsWin = () => <div className=\"flex flex-col gap-2\">\n    <FieldText\n        orientation=\"vertical\"\n        invalid={false}\n        disabled={false}\n        readOnly={false}\n        required={false}>\n        <Label>Website</Label>\n        <Input type=\"url\" size=\"lg\" className=\"max-w-xs\" aria-describedby=\"website-hint\" />\n        <Field.Description>Include the protocol.</Field.Description>\n    </FieldText>\n    <p id=\"website-hint\" className=\"text-sm\">Shown on your public profile.\n                    </p>\n</div>;",
+          "description": "The context is a default, never an override: an extra `aria-describedby` is\nconcatenated with the field's ids, `className` is merged and `size` passes\nthrough untouched.",
+          "summary": "Input's own props merge with, and win over, the field's context"
+        },
+        {
+          "id": "components-fieldtext--controlled-from-context",
+          "name": "Controlled From Context",
+          "snippet": "const ControlledFromContext = () => <ControlledField />;",
+          "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"
+        }
+      ],
+      "import": "import { Field, FieldContext, FieldText, Input, InputContext, Label } from \"@agentero/design-system\";"
+    },
+    "components-field": {
+      "id": "components-field",
+      "name": "Field.Root",
+      "path": "./src/field/field.stories.tsx",
+      "jsDocTags": {
+        "summary": [
+          "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>"
+        ]
+      },
+      "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.",
+      "summary": "Wraps a label, control, description and error into one field",
+      "reactComponentMeta": {
+        "displayName": "Field.Root",
+        "exportName": "Field",
+        "filePath": "/home/runner/work/design-system/design-system/src/field/index.ts",
+        "description": "Wraps one label, control, description and error into a single field and\nwires the accessibility relationships between them. It generates the ids\nand shares them through context: `Label` reads `LabelContext`,\n`Field.Description` and `Field.Error` read `FieldContext` and register\nthemselves so the control's `aria-describedby` lists exactly the messages on\nscreen, and a `Field<X>` such as `FieldText` provides the control's context so\nthe control associates itself too. Nobody passes an `id` by hand.\n\nPresentational and form-library agnostic: pass `invalid` and the error\nmessages from whatever validates the form. Deliberately not a `role=\"group\"`:\none field is not a set of related controls, and an unnamed group only adds\nscreen-reader verbosity. Real groupings belong to a fieldset with a legend.",
+        "jsDocTags": {
+          "summary": [
+            "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>"
+          ]
+        },
+        "props": {
+          "orientation": {
+            "name": "orientation",
+            "required": false,
+            "type": {
+              "name": "enum",
+              "raw": "\"horizontal\" | \"vertical\" | \"responsive\"",
+              "value": [
+                {
+                  "value": "\"horizontal\""
+                },
+                {
+                  "value": "\"vertical\""
+                },
+                {
+                  "value": "\"responsive\""
+                }
+              ]
+            },
+            "description": "Layout of the field. `vertical` (default) stacks label, control and\nmessages. `horizontal` is one row at every width: the first child fills it\nand the rest keep their natural width, aligned to the right, so the\ncontrols of stacked fields line up. `responsive` stacks below `28rem` and\nbehaves like `horizontal` from there, measured on the field itself, so it\nneeds no particular wrapper. In both, `Field.Content` groups a control with\nits messages, or a label with its description.",
+            "defaultValue": {
+              "value": "'vertical'"
+            },
+            "parent": {
+              "name": "FieldRootProps",
+              "fileName": "src/field/field.tsx"
+            },
+            "declarations": [
+              {
+                "name": "TypeLiteral",
+                "fileName": "src/field/field.tsx"
+              }
+            ]
+          },
+          "invalid": {
+            "name": "invalid",
+            "required": false,
+            "type": {
+              "name": "boolean"
+            },
+            "description": "Marks the field as failing validation: sets `data-invalid` on the root and\n`aria-invalid` on the control through its context, which drives the\ncontrol's destructive border. The label keeps its color by design.",
+            "defaultValue": {
+              "value": "false"
+            },
+            "parent": {
+              "name": "FieldRootProps",
+              "fileName": "src/field/field.tsx"
+            },
+            "declarations": [
+              {
+                "name": "TypeLiteral",
+                "fileName": "src/field/field.tsx"
+              }
+            ]
+          },
+          "disabled": {
+            "name": "disabled",
+            "required": false,
+            "type": {
+              "name": "boolean"
+            },
+            "description": "Disables the control through its context and sets `data-disabled` on the root.",
+            "defaultValue": {
+              "value": "false"
+            },
+            "parent": {
+              "name": "FieldRootProps",
+              "fileName": "src/field/field.tsx"
+            },
+            "declarations": [
+              {
+                "name": "TypeLiteral",
+                "fileName": "src/field/field.tsx"
+              }
+            ]
+          },
+          "readOnly": {
+            "name": "readOnly",
+            "required": false,
+            "type": {
+              "name": "boolean"
+            },
+            "description": "Makes the control read-only through its context (focusable and copyable,\nnot editable, still submitted) and sets `data-readonly` on the root.",
+            "defaultValue": {
+              "value": "false"
+            },
+            "parent": {
+              "name": "FieldRootProps",
+              "fileName": "src/field/field.tsx"
+            },
+            "declarations": [
+              {
+                "name": "TypeLiteral",
+                "fileName": "src/field/field.tsx"
+              }
+            ]
+          },
+          "required": {
+            "name": "required",
+            "required": false,
+            "type": {
+              "name": "boolean"
+            },
+            "description": "Single source of truth for a required field: the `Label` shows its\nasterisk and the control receives `required`, both through context.",
+            "defaultValue": {
+              "value": "false"
+            },
+            "parent": {
+              "name": "FieldRootProps",
+              "fileName": "src/field/field.tsx"
+            },
+            "declarations": [
+              {
+                "name": "TypeLiteral",
+                "fileName": "src/field/field.tsx"
+              }
+            ]
+          },
+          "controlId": {
+            "name": "controlId",
+            "required": false,
+            "type": {
+              "name": "string"
+            },
+            "description": "`id` for the control. Generated when omitted. Set it here, not on the\ncontrol, so the label and the messages keep pointing at the right element.",
+            "defaultValue": null,
+            "parent": {
+              "name": "FieldRootProps",
+              "fileName": "src/field/field.tsx"
+            },
+            "declarations": [
+              {
+                "name": "TypeLiteral",
+                "fileName": "src/field/field.tsx"
+              }
+            ]
+          }
+        }
+      },
+      "stories": [
+        {
+          "id": "components-field--default",
+          "name": "Default",
+          "snippet": "const Default = () => <Field.Root\n    orientation=\"vertical\"\n    invalid={false}\n    disabled={false}\n    readOnly={false}\n    required={false}>\n    <Label>Email</Label>\n    <DemoInput placeholder=\"you@example.com\" />\n    <Field.Description>We only use this to send policy documents.</Field.Description>\n</Field.Root>;",
+          "description": "A vertical field with a label, a control and helper text. The label points\nat the control and the description is referenced by it — neither needed an\nexplicit `id`.",
+          "summary": "Default vertical field with label, control and description"
+        },
+        {
+          "id": "components-field--required",
+          "name": "Required",
+          "snippet": "const Required = () => <Field.Root\n    orientation=\"vertical\"\n    invalid={false}\n    disabled={false}\n    readOnly={false}\n    required>\n    <Label>Full name</Label>\n    <DemoInput placeholder=\"Jane Doe\" />\n</Field.Root>;",
+          "description": "`required` on the root is the single source of truth: the label shows its\nasterisk and the control receives `required`, both through context.",
+          "summary": "Required field driven from the root alone"
+        },
+        {
+          "id": "components-field--optional",
+          "name": "Optional",
+          "snippet": "const Optional = () => <Field.Root\n    orientation=\"vertical\"\n    invalid={false}\n    disabled={false}\n    readOnly={false}\n    required={false}>\n    <Label optional>Phone number</Label>\n    <DemoInput type=\"tel\" placeholder=\"+1 (555) 000-0000\" />\n</Field.Root>;",
+          "description": "`optional` on the label appends the muted suffix; the control stays\nnon-required.",
+          "summary": "Optional field with the muted label suffix"
+        },
+        {
+          "id": "components-field--with-tooltip",
+          "name": "With Tooltip",
+          "snippet": "const WithTooltip = () => <Field.Root\n    orientation=\"vertical\"\n    invalid={false}\n    disabled={false}\n    readOnly={false}\n    required>\n    <Field.Label tooltip=\"Issued by the IRS to identify your business.\">Tax ID</Field.Label>\n    <DemoInput placeholder=\"XX-XXXXXXX\" />\n</Field.Root>;",
+          "description": "`Field.Label` puts an info button beside the caption. It is a sibling of the\n`<label>`, so it keeps its own accessible name, clicking it does not focus\nthe control, and the control's name stays clean. It opens on focus too.",
+          "summary": "Label with a tooltip trigger beside it"
+        },
+        {
+          "id": "components-field--invalid",
+          "name": "Invalid",
+          "snippet": "const Invalid = () => <Field.Root\n    orientation=\"vertical\"\n    invalid\n    disabled={false}\n    readOnly={false}\n    required={false}>\n    <Label>Email</Label>\n    <DemoInput type=\"email\" defaultValue=\"not-an-email\" />\n    <Field.Error errors={[{ message: 'Enter a valid email address.' }]} />\n</Field.Root>;",
+          "description": "`invalid` on the root sets `data-invalid` for styling and `aria-invalid` on\nthe control, which drives its destructive border; the label keeps its color\nby design. `Field.Error` takes the error objects as they come from a form\nlibrary.",
+          "summary": "Invalid field with a single error message"
+        },
+        {
+          "id": "components-field--multiple-errors",
+          "name": "Multiple Errors",
+          "snippet": "const MultipleErrors = () => <Field.Root\n    orientation=\"vertical\"\n    invalid\n    disabled={false}\n    readOnly={false}\n    required={false}>\n    <Label>Password</Label>\n    <DemoInput type=\"password\" defaultValue=\"abc\" />\n    <Field.Error\n        errors={[\n            { message: 'Use at least 8 characters.' },\n            { message: 'Include a number.' },\n            { message: 'Use at least 8 characters.' }\n        ]} />\n</Field.Root>;",
+          "description": "Several errors render as a list, de-duplicated by message.",
+          "summary": "Several errors rendered as a de-duplicated list"
+        },
+        {
+          "id": "components-field--error-with-types",
+          "name": "Error With Types",
+          "snippet": "const ErrorWithTypes = () => <Field.Root\n    orientation=\"vertical\"\n    invalid\n    disabled={false}\n    readOnly={false}\n    required={false}>\n    <Label>Password</Label>\n    <DemoInput type=\"password\" defaultValue=\"short\" />\n    <Field.Error\n        errors={[\n            {\n                message: 'At least one uppercase letter.',\n                types: {\n                    uppercase: 'At least one uppercase letter.',\n                    number: 'At least one number.',\n                    length: ['At least 10 characters.'],\n                    unnamed: true\n                }\n            }\n        ]} />\n</Field.Root>;",
+          "description": "One error whose `types` lists every rule that failed renders as that same\nlist. A form library fills it when it collects all the failures instead of\nstopping at the first (react-hook-form's `criteriaMode: 'all'`), leaving only\nthe first one in `message`, so the messages take precedence over it. A rule\nthat failed without a message of its own contributes nothing.",
+          "summary": "Every rule a single error collected, rendered as a list"
+        },
+        {
+          "id": "components-field--no-error",
+          "name": "No Error",
+          "snippet": "const NoError = () => <Field.Root\n    orientation=\"vertical\"\n    invalid={false}\n    disabled={false}\n    readOnly={false}\n    required={false}>\n    <Label>Email</Label>\n    <DemoInput type=\"email\" />\n    <Field.Error errors={[undefined]} />\n</Field.Root>;",
+          "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--disabled",
+          "name": "Disabled",
+          "snippet": "const Disabled = () => <Field.Root\n    orientation=\"vertical\"\n    invalid={false}\n    disabled\n    readOnly={false}\n    required={false}>\n    <Label>Agency</Label>\n    <DemoInput defaultValue=\"Acme Insurance\" />\n    <Field.Description>Managed by your administrator.</Field.Description>\n</Field.Root>;",
+          "description": "`disabled` on the root disables the control through context and sets\n`data-disabled` for styling.",
+          "summary": "Disabled field driven from the root"
+        },
+        {
+          "id": "components-field--read-only",
+          "name": "Read Only",
+          "snippet": "const ReadOnly = () => <Field.Root\n    orientation=\"vertical\"\n    invalid={false}\n    disabled={false}\n    readOnly\n    required={false}>\n    <Label>Policy number</Label>\n    <DemoInput defaultValue=\"POL-2049-118\" />\n    <Field.Description>Assigned by the carrier; contact support to change it.</Field.Description>\n</Field.Root>;",
+          "description": "`readOnly` on the root makes the control read-only through context and sets\n`data-readonly` for styling. Unlike `disabled`, the value stays focusable,\ncopyable and submitted.",
+          "summary": "Read-only field driven from the root"
+        },
+        {
+          "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);",
+          "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);",
+          "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"
+        },
+        {
+          "id": "components-field--group",
+          "name": "Group",
+          "snippet": "const Group = () => (\n    <Field.Group>\n        <Field.Root required>\n            <Label>Full name</Label>\n            <DemoInput placeholder=\"Jane Doe\" />\n        </Field.Root>\n\n        <Field.Root required invalid>\n            <Label>Email</Label>\n            <DemoInput type=\"email\" defaultValue=\"not-an-email\" />\n            <Field.Error>Enter a valid email address.</Field.Error>\n        </Field.Root>\n\n        <Field.Root>\n            <Label optional>Phone number</Label>\n            <DemoInput type=\"tel\" placeholder=\"+1 (555) 000-0000\" />\n        </Field.Root>\n    </Field.Group>\n);",
+          "description": "`Field.Group` stacks fields and owns the space between them. Each field gets\nits own ids, so several on one page never collide.",
+          "summary": "Several fields stacked in a group"
+        },
+        {
+          "id": "components-field--standalone-outside-field",
+          "name": "Standalone Outside Field",
+          "snippet": "const StandaloneOutsideField = () => (\n    <div className=\"flex flex-col gap-2\">\n        <Label htmlFor=\"standalone-email\">Email</Label>\n        <DemoInput id=\"standalone-email\" type=\"email\" aria-describedby=\"standalone-error\" />\n        <Field.Error id=\"standalone-error\">Something went wrong.</Field.Error>\n    </div>\n);",
+          "description": "Outside a `Field.Root` every part reads a `null` context and works on its own\nprops alone: `Label` needs its `htmlFor`, `Field.Error` its own `id`.",
+          "summary": "Label and Field.Error used without a Field.Root"
+        },
+        {
+          "id": "components-field--own-props-win",
+          "name": "Own Props Win",
+          "snippet": "const OwnPropsWin = () => (\n    <Field.Root>\n        <Label htmlFor=\"own-input\">Email</Label>\n        <input id=\"own-input\" type=\"email\" className={inputRecipe()} />\n        <Field.Description id=\"own-description\">Points wherever you say.</Field.Description>\n    </Field.Root>\n);",
+          "description": "A context is a default, never an override: an explicit `htmlFor` or `id` on a\npart wins over what `Field.Root` provides.",
+          "summary": "Explicit props on a part win over the field's context"
+        },
+        {
+          "id": "components-field--errors-from-context",
+          "name": "Errors From Context",
+          "snippet": "const ErrorsFromContext = () => <FieldWithSuppliedErrors />;",
+          "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"
+        }
+      ],
+      "import": "import { Field, FieldContext, Label } from \"@agentero/design-system\";"
+    },
+    "components-formtext": {
+      "id": "components-formtext",
+      "name": "FormText",
+      "path": "./src/form-text/form-text.stories.tsx",
+      "jsDocTags": {
+        "summary": [
+          "Label, Input, description and error bound to one react-hook-form field"
+        ],
+        "example": [
+          "<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  required\n  rules={{ required: 'Enter the tax ID.', pattern: { value: /^\\d{2}-?\\d{7}$/, message: 'Nine digits.' } }}\n  inputProps={{ inputMode: 'numeric', autoComplete: 'off' }}\n/>"
+        ]
+      },
+      "description": "FormText is a complete text field bound to one react-hook-form value: label,\n`Input`, helper text and validation error in the standard order, wired\nthrough `useController`. It renders inside a `Form.Root` and needs only a\n`name`; `required`, `invalid` and the error reach the label, the input's\n`aria-*` attributes and the message with no ids written by hand.\n\nIt covers the common case. For another layout — an input with addons, a\ndifferent control, a message rendered elsewhere — compose `useController`\nwith the `FieldText`, `Label`, `Input` and `Field.*` primitives directly.",
+      "summary": "Label, Input, description and error bound to one react-hook-form field",
+      "reactComponentMeta": {
+        "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.",
+        "jsDocTags": {
+          "summary": [
+            "Label, Input, description and error bound to one react-hook-form field"
+          ],
+          "example": [
+            "<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  required\n  rules={{ required: 'Enter the tax ID.', pattern: { value: /^\\d{2}-?\\d{7}$/, message: 'Nine digits.' } }}\n  inputProps={{ inputMode: 'numeric', autoComplete: 'off' }}\n/>"
+          ]
+        },
+        "props": {
+          "disabled": {
+            "name": "disabled",
+            "required": false,
+            "type": {
+              "name": "boolean"
+            },
+            "description": "Disables the control through its context and sets `data-disabled` on the root.\nDisables the input and marks the field. Unlike react-hook-form's own\n`disabled` option, the value stays in the submitted data: disabling a\nfield is a presentation decision, not a change to the form's values.",
+            "defaultValue": null,
+            "parent": {
+              "name": "FieldRootProps",
+              "fileName": "src/field/field.tsx"
+            },
+            "declarations": [
+              {
+                "name": "TypeLiteral",
+                "fileName": "src/field/field.tsx"
+              },
+              {
+                "name": "TypeLiteral",
+                "fileName": "src/form-text/form-text.tsx"
+              }
+            ]
+          },
+          "orientation": {
+            "name": "orientation",
+            "required": false,
+            "type": {
+              "name": "enum",
+              "raw": "\"horizontal\" | \"vertical\" | \"responsive\"",
+              "value": [
+                {
+                  "value": "\"horizontal\""
+                },
+                {
+                  "value": "\"vertical\""
+                },
+                {
+                  "value": "\"responsive\""
+                }
+              ]
+            },
+            "description": "Layout of the field. `vertical` (default) stacks label, control and\nmessages. `horizontal` is one row at every width: the first child fills it\nand the rest keep their natural width, aligned to the right, so the\ncontrols of stacked fields line up. `responsive` stacks below `28rem` and\nbehaves like `horizontal` from there, measured on the field itself, so it\nneeds no particular wrapper. In both, `Field.Content` groups a control with\nits messages, or a label with its description.",
+            "defaultValue": null,
+            "parent": {
+              "name": "FieldRootProps",
+              "fileName": "src/field/field.tsx"
+            },
+            "declarations": [
+              {
+                "name": "TypeLiteral",
+                "fileName": "src/field/field.tsx"
+              }
+            ]
+          },
+          "required": {
+            "name": "required",
+            "required": false,
+            "type": {
+              "name": "boolean"
+            },
+            "description": "Single source of truth for a required field: the `Label` shows its\nasterisk and the control receives `required`, both through context.\nMarks the field required: an asterisk on the label and the native\n`required` attribute on the input, which assistive technology announces.\nIt does not validate — pair it with `rules.required` or a resolver — and it\nnever triggers the browser bubble, since `Form.Root` renders `noValidate`.",
+            "defaultValue": null,
+            "parent": {
+              "name": "FieldRootProps",
+              "fileName": "src/field/field.tsx"
+            },
+            "declarations": [
+              {
+                "name": "TypeLiteral",
+                "fileName": "src/field/field.tsx"
+              },
+              {
+                "name": "TypeLiteral",
+                "fileName": "src/form-text/form-text.tsx"
+              }
+            ]
+          },
+          "readOnly": {
+            "name": "readOnly",
+            "required": false,
+            "type": {
+              "name": "boolean"
+            },
+            "description": "Makes the control read-only through its context (focusable and copyable,\nnot editable, still submitted) and sets `data-readonly` on the root.",
+            "defaultValue": null,
+            "parent": {
+              "name": "FieldRootProps",
+              "fileName": "src/field/field.tsx"
+            },
+            "declarations": [
+              {
+                "name": "TypeLiteral",
+                "fileName": "src/field/field.tsx"
+              }
+            ]
+          },
+          "controlId": {
+            "name": "controlId",
+            "required": false,
+            "type": {
+              "name": "string"
+            },
+            "description": "`id` for the control. Generated when omitted. Set it here, not on the\ncontrol, so the label and the messages keep pointing at the right element.",
+            "defaultValue": null,
+            "parent": {
+              "name": "FieldRootProps",
+              "fileName": "src/field/field.tsx"
+            },
+            "declarations": [
+              {
+                "name": "TypeLiteral",
+                "fileName": "src/field/field.tsx"
+              }
+            ]
+          },
+          "name": {
+            "name": "name",
+            "required": true,
+            "type": {
+              "name": "\"agencyName\""
+            },
+            "description": "Path of the value in the form, nested paths included (`'agency.npn'`).\nType it against the form's values with the generic\n(`<FormText<Values> name=\"agency.npn\" />`) or by passing `control`: the\npath must then exist and hold a string (`FormTextPath`).",
+            "defaultValue": null,
+            "parent": {
+              "name": "FormTextProps",
+              "fileName": "src/form-text/form-text.tsx"
+            },
+            "declarations": [
+              {
+                "name": "TypeLiteral",
+                "fileName": "src/form-text/form-text.tsx"
+              }
+            ]
+          },
+          "control": {
+            "name": "control",
+            "required": false,
+            "type": {
+              "name": "Control<FieldValues, any, FieldValues>"
+            },
+            "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,
+            "parent": {
+              "name": "FormTextProps",
+              "fileName": "src/form-text/form-text.tsx"
+            },
+            "declarations": [
+              {
+                "name": "TypeLiteral",
+                "fileName": "src/form-text/form-text.tsx"
+              }
+            ]
+          },
+          "rules": {
+            "name": "rules",
+            "required": false,
+            "type": {
+              "name": "Omit<RegisterOptions<FieldValues, \"agencyName\">, \"disabled\" | \"valueAsNumber\" | \"valueAsDate\" | \"setValueAs\">"
+            },
+            "description": "react-hook-form validation rules for this field (`required`, `pattern`,\n`validate`…), same as `register`'s. They only validate: `rules.required`\ndoes not mark the field `required` — that is a separate, visible decision.",
+            "defaultValue": null,
+            "parent": {
+              "name": "FormTextProps",
+              "fileName": "src/form-text/form-text.tsx"
+            },
+            "declarations": [
+              {
+                "name": "TypeLiteral",
+                "fileName": "src/form-text/form-text.tsx"
+              }
+            ]
+          },
+          "shouldUnregister": {
+            "name": "shouldUnregister",
+            "required": false,
+            "type": {
+              "name": "boolean"
+            },
+            "description": "Drops the value from the form when the field unmounts, react-hook-form's\n`shouldUnregister`. Defaults to `false`: a field revealed by another one\nkeeps its value while hidden.",
+            "defaultValue": null,
+            "parent": {
+              "name": "FormTextProps",
+              "fileName": "src/form-text/form-text.tsx"
+            },
+            "declarations": [
+              {
+                "name": "TypeLiteral",
+                "fileName": "src/form-text/form-text.tsx"
+              }
+            ]
+          },
+          "label": {
+            "name": "label",
+            "required": true,
+            "type": {
+              "name": "ReactNode"
+            },
+            "description": "The caption, rendered as the field's label. Text in almost every case.",
+            "defaultValue": null,
+            "parent": {
+              "name": "FormTextProps",
+              "fileName": "src/form-text/form-text.tsx"
+            },
+            "declarations": [
+              {
+                "name": "TypeLiteral",
+                "fileName": "src/form-text/form-text.tsx"
+              }
+            ]
+          },
+          "description": {
+            "name": "description",
+            "required": false,
+            "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.",
+            "defaultValue": null,
+            "parent": {
+              "name": "FormTextProps",
+              "fileName": "src/form-text/form-text.tsx"
+            },
+            "declarations": [
+              {
+                "name": "TypeLiteral",
+                "fileName": "src/form-text/form-text.tsx"
+              }
+            ]
+          },
+          "tooltip": {
+            "name": "tooltip",
+            "required": false,
+            "type": {
+              "name": "ReactNode"
+            },
+            "description": "Content of an info tooltip rendered beside the label, for details that\nwould clutter the description. The trigger is a sibling of the label, so\nthe field's accessible name stays the label text.",
+            "defaultValue": null,
+            "parent": {
+              "name": "FormTextProps",
+              "fileName": "src/form-text/form-text.tsx"
+            },
+            "declarations": [
+              {
+                "name": "TypeLiteral",
+                "fileName": "src/form-text/form-text.tsx"
+              }
+            ]
+          },
+          "tooltipSide": {
+            "name": "tooltipSide",
+            "required": false,
+            "type": {
+              "name": "enum",
+              "raw": "\"right\" | \"top\" | \"bottom\" | \"left\"",
+              "value": [
+                {
+                  "value": "\"right\""
+                },
+                {
+                  "value": "\"top\""
+                },
+                {
+                  "value": "\"bottom\""
+                },
+                {
+                  "value": "\"left\""
+                }
+              ]
+            },
+            "description": "Preferred side of the tooltip. Defaults to `'top'`.",
+            "defaultValue": null,
+            "parent": {
+              "name": "FormTextProps",
+              "fileName": "src/form-text/form-text.tsx"
+            },
+            "declarations": [
+              {
+                "name": "TypeLiteral",
+                "fileName": "src/form-text/form-text.tsx"
+              }
+            ]
+          },
+          "optional": {
+            "name": "optional",
+            "required": false,
+            "type": {
+              "name": "boolean"
+            },
+            "description": "Appends a muted \" (optional)\" to the label. The forms mark optional fields\nrather than required ones; ignored when `required` is set.",
+            "defaultValue": null,
+            "parent": {
+              "name": "FormTextProps",
+              "fileName": "src/form-text/form-text.tsx"
+            },
+            "declarations": [
+              {
+                "name": "TypeLiteral",
+                "fileName": "src/form-text/form-text.tsx"
+              }
+            ]
+          },
+          "inputProps": {
+            "name": "inputProps",
+            "required": false,
+            "type": {
+              "name": "FormTextInputProps"
+            },
+            "description": "Everything else the `Input` should receive: `type`, `placeholder`,\n`maxLength`, `autoComplete`, `size`, `className`… Handlers such as\n`onChange` and `onBlur` run after react-hook-form's, which are already\nwired.",
+            "defaultValue": null,
+            "parent": {
+              "name": "FormTextProps",
+              "fileName": "src/form-text/form-text.tsx"
+            },
+            "declarations": [
+              {
+                "name": "TypeLiteral",
+                "fileName": "src/form-text/form-text.tsx"
+              }
+            ]
+          }
+        }
+      },
+      "stories": [
+        {
+          "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} />;",
+          "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 />;",
+          "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 />;",
+          "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 />;",
+          "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 />;",
+          "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 />;",
+          "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 />;",
+          "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 />;",
+          "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 />;",
+          "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"
+        }
+      ],
+      "import": "import { Button, Field, Form, FormText } from \"@agentero/design-system\";"
+    },
+    "components-form": {
+      "id": "components-form",
+      "name": "Form.Root",
+      "path": "./src/form/form.stories.tsx",
+      "jsDocTags": {
+        "summary": [
+          "Form element bound to a react-hook-form instance, shared with its fields"
+        ],
+        "example": [
+          "const methods = useForm<Values>({ defaultValues: { agencyName: '', email: '' } });\n\n<Form.Root methods={methods} onSubmit={saveAgency} aria-label=\"Agency profile\">\n  <FormText name=\"agencyName\" label=\"Agency name\" required rules={{ required: 'Enter the agency name.' }} />\n  <FormText name=\"email\" label=\"Email\" inputProps={{ type: 'email' }} />\n  <Button type=\"submit\">Save</Button>\n</Form.Root>"
+        ]
+      },
+      "description": "Form is the react-hook-form binding of the design system. `Form.Root` renders\nthe `<form>` and provides the `useForm()` instance to the form fields inside\nit — `FormText` and the other `Form<X>` components — which bind themselves by\n`name`. The submit goes through `handleSubmit`, so `onSubmit` only runs with\nvalid, typed values, and the element is always `noValidate`: validation is\nreact-hook-form's, and the `required` a field sets is announced without the\nbrowser's own bubble.\n\n`react-hook-form` is an optional peer dependency: install it in the app and\nkeep a single copy, since the provider and the fields share one context.",
+      "summary": "Form element bound to a react-hook-form instance, shared with its fields",
+      "reactComponentMeta": {
+        "displayName": "Form.Root",
+        "exportName": "Form",
+        "filePath": "/home/runner/work/design-system/design-system/src/form/index.ts",
+        "description": "The `<form>` element of a react-hook-form form: it provides the `useForm()`\ninstance to the form fields inside it (`FormText` and the other `Form<X>`\ncomponents) and routes the submit through `handleSubmit`. It always renders\n`noValidate`, so the `required` attribute a field sets reaches assistive\ntechnology without the browser's own validation bubble getting in the way:\nvalidation is react-hook-form's, from `rules` or a resolver.\n\nUse it around any form built with the `Form<X>` fields. Without\nreact-hook-form, render a plain `<form>` with the presentational primitives\n([FieldText](?path=/docs/components-fieldtext--docs)) instead — this\ncomponent is only the binding.\n\n`react-hook-form` is an optional peer dependency: the design system never\nbundles its own copy, because `FormProvider` and the fields must share one\nReact context. Two copies in an app (a nested version under a workspace,\nsay) make every field throw from `useController`; `yarn why react-hook-form`\nshould list a single instance.",
+        "jsDocTags": {
+          "summary": [
+            "Form element bound to a react-hook-form instance, shared with its fields"
+          ],
+          "example": [
+            "const methods = useForm<Values>({ defaultValues: { agencyName: '', email: '' } });\n\n<Form.Root methods={methods} onSubmit={saveAgency} aria-label=\"Agency profile\">\n  <FormText name=\"agencyName\" label=\"Agency name\" required rules={{ required: 'Enter the agency name.' }} />\n  <FormText name=\"email\" label=\"Email\" inputProps={{ type: 'email' }} />\n  <Button type=\"submit\">Save</Button>\n</Form.Root>"
+          ]
+        },
+        "props": {
+          "aria-label": {
+            "name": "aria-label",
+            "required": true,
+            "type": {
+              "name": "string"
+            },
+            "description": "Defines a string value that labels the current element.\nAccessible name of the form. A `<form>` only becomes a landmark when it is\nnamed, and screen readers list landmarks by name, so it is required.",
+            "defaultValue": null,
+            "parent": {
+              "name": "AriaAttributes",
+              "fileName": "node_modules/@types/react/index.d.ts"
+            },
+            "declarations": [
+              {
+                "name": "AriaAttributes",
+                "fileName": "node_modules/@types/react/index.d.ts"
+              },
+              {
+                "name": "TypeLiteral",
+                "fileName": "src/form/form.tsx"
+              }
+            ]
+          },
+          "methods": {
+            "name": "methods",
+            "required": true,
+            "type": {
+              "name": "UseFormReturn<AgencyValues, any, AgencyValues>"
+            },
+            "description": "The object `useForm()` returns. `Form.Root` hands it to every form field\ninside through react-hook-form's `FormProvider`, so a `FormText` needs only\nits `name`. Create it in the component that owns the form and pass\n`defaultValues`: a field whose value is `undefined` on the first render\nstarts uncontrolled. A form whose resolver transforms the values\n(`useForm<Input, Context, Output>`) is accepted as is.",
+            "defaultValue": null,
+            "parent": {
+              "name": "FormRootProps",
+              "fileName": "src/form/form.tsx"
+            },
+            "declarations": [
+              {
+                "name": "TypeLiteral",
+                "fileName": "src/form/form.tsx"
+              }
+            ]
+          },
+          "onSubmit": {
+            "name": "onSubmit",
+            "required": false,
+            "type": {
+              "name": "SubmitHandler<AgencyValues>"
+            },
+            "description": "Called with the validated values once validation passes: the resolver's\noutput when it transforms them, the form's values otherwise. Wrapped in\n`methods.handleSubmit`, which prevents the native submit and focuses the\nfirst invalid field; when it is omitted the form validates and does nothing\nelse.",
+            "defaultValue": null,
+            "parent": {
+              "name": "FormRootProps",
+              "fileName": "src/form/form.tsx"
+            },
+            "declarations": [
+              {
+                "name": "TypeLiteral",
+                "fileName": "src/form/form.tsx"
+              }
+            ]
+          }
+        }
+      },
+      "stories": [
+        {
+          "id": "components-form--default",
+          "name": "Default",
+          "snippet": "const Default = () => <AgencyForm />;",
+          "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 />;",
+          "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"
+        }
+      ],
+      "import": "import { Button, Field, Form, FormText } from \"@agentero/design-system\";"
+    },
     "components-hovercard": {
       "id": "components-hovercard",
       "name": "HoverCard.Root",
@@ -4605,23 +5622,23 @@
       "path": "./src/input/input.stories.tsx",
       "jsDocTags": {
         "summary": [
-          "Base single-line text control, unaware of fields and form libraries"
+          "Base single-line text control that takes its wiring from InputContext"
         ],
         "example": [
           "<Label htmlFor=\"email\">Email</Label>\n<Input id=\"email\" type=\"email\" placeholder=\"you@example.com\" />",
           "<Input id=\"email\" aria-invalid aria-describedby=\"email-error\" />\n<span id=\"email-error\">Enter a valid email address.</span>"
         ]
       },
-      "description": "Input is the base single-line text control. It is intentionally unaware of\nform fields and form libraries: `id`, `aria-invalid` and `aria-describedby`\nare plain props, set by a field wrapper or by hand.\n\nThere is no `status` prop. Mark the control `aria-invalid` and the\ndestructive border follows, so the styling can never disagree with what\nassistive technology announces.",
-      "summary": "Base single-line text control, unaware of fields and form libraries",
+      "description": "Input is the base single-line text control. When a container such as\n`FieldText` provides `InputContext`, it picks up `id`, `aria-invalid` and\n`aria-describedby` on its own; standalone, as here, they are plain props set\nby hand.\n\nThere is no `status` prop. Mark the control `aria-invalid` and the\ndestructive border follows, so the styling can never disagree with what\nassistive technology announces.",
+      "summary": "Base single-line text control that takes its wiring from InputContext",
       "reactComponentMeta": {
         "displayName": "Input",
         "exportName": "Input",
         "filePath": "/home/runner/work/design-system/design-system/src/input/input.tsx",
-        "description": "Input is the design system's base single-line text control. Reach for it\nwhenever a form collects free text, and pair it with\n[Label](?path=/docs/components-label--docs) so the control has an accessible\nname.\n\nIt is deliberately self-contained: it renders the props it is given and\nknows nothing about form fields, form libraries, or surrounding layout.\nWiring (`id`, `aria-invalid`, `aria-describedby`) arrives as plain props, so\na field wrapper can inject them and standalone usage can set them by hand.\nThere is no `status` prop — mark the control `aria-invalid` and the\ndestructive border follows.\n\nDo not use Input for multi-line text; that is TextArea's job. It also has no\nslots for leading or trailing addons — an input with a currency prefix or a\nunit suffix belongs in an input group, not here.",
+        "description": "Input is the design system's base single-line text control. Reach for it\nwhenever a form collects free text, and pair it with\n[Label](?path=/docs/components-label--docs) so the control has an accessible\nname.\n\nWhen a container provides `InputContext`, the input takes its wiring (`id`,\n`aria-describedby`, `aria-invalid`, `required`, `disabled`, `readOnly`) from\nit with nothing passed by hand; `FieldText` is one such container. Standalone it\nrenders exactly the props it is given, and its own props always win over the\ncontext. There is no `status` prop — mark the control `aria-invalid` and the\ndestructive border follows.\n\nDo not use Input for multi-line text; that is TextArea's job. It also has no\nslots for leading or trailing addons — an input with a currency prefix or a\nunit suffix belongs in an input group, not here.",
         "jsDocTags": {
           "summary": [
-            "Base single-line text control, unaware of fields and form libraries"
+            "Base single-line text control that takes its wiring from InputContext"
           ],
           "example": [
             "<Label htmlFor=\"email\">Email</Label>\n<Input id=\"email\" type=\"email\" placeholder=\"you@example.com\" />",
@@ -4885,7 +5902,7 @@
         "displayName": "Label",
         "exportName": "Label",
         "filePath": "/home/runner/work/design-system/design-system/src/label/label.tsx",
-        "description": "Accessible caption for a form control, built on Radix's Label primitive so it\nassociates with the control via `htmlFor` and does not select text on\ndouble-click.\n\nKeep it text-only. Nesting an interactive element (a help tooltip trigger, a\nbutton) inside a `<label>` gives that element the label's accessible name and\nmakes a click focus the control — render it as a sibling instead.",
+        "description": "Accessible caption for a form control, built on Radix's Label primitive so it\nassociates with the control via `htmlFor` and does not select text on\ndouble-click.\n\nKeep it text-only. Nesting an interactive element (a help tooltip trigger, a\nbutton) inside a `<label>` gives that element the label's accessible name and\nmakes a click focus the control — render it as a sibling instead.\n\nWhen a container provides `LabelContext`, the label takes `htmlFor` and\n`required` from it and associates itself with the control without an explicit\n`htmlFor`; `Field.Root` is one such container. Standalone it behaves as a\nplain label. Its own props always win over the context.",
         "jsDocTags": {
           "summary": [
             "Accessible caption for a form control"
@@ -4962,7 +5979,7 @@
         {
           "id": "components-label--default",
           "name": "Default",
-          "snippet": "const Default = () => <>\n    <Label htmlFor=\"email\">Email</Label>\n    <input id=\"email\" placeholder=\"you@example.com\" />\n</>;",
+          "snippet": "const Default = () => <>\n    <Label htmlFor=\"email\">Email</Label>\n    <input id=\"email\" placeholder=\"you@example.com\" className={inputRecipe()} />\n</>;",
           "description": "A plain caption, associated with its control through `htmlFor`.",
           "summary": "Default label associated with a control"
         },
@@ -4986,9 +6003,16 @@
           "snippet": "const RequiredWinsOverOptional = () => <Label optional required>Agency name</Label>;",
           "description": "Contradictory props do not throw — `required` wins and the optional suffix is\ndropped, so a mistake never takes the page down.",
           "summary": "required takes precedence over optional"
+        },
+        {
+          "id": "components-label--inside-field",
+          "name": "Inside Field",
+          "snippet": "const InsideField = () => (\n    <div className=\"flex flex-col gap-6\">\n        <Field.Root>\n            <Label>Email</Label>\n            <FieldInput />\n        </Field.Root>\n\n        <Field.Root>\n            <Label htmlFor=\"explicit-control\">Phone</Label>\n            <input id=\"explicit-control\" className={inputRecipe()} />\n        </Field.Root>\n    </div>\n);",
+          "description": "Inside a `Field.Root` the label reads `LabelContext` and points at the\nfield's control with no `htmlFor`. An explicit `htmlFor` still wins.",
+          "summary": "Inside a Field the label associates itself; explicit htmlFor wins"
         }
       ],
-      "import": "import { Label } from \"@agentero/design-system\";"
+      "import": "import { Field, Label } from \"@agentero/design-system\";"
     },
     "components-loading": {
       "id": "components-loading",
@@ -7582,6 +8606,6 @@
   },
   "meta": {
     "docgen": "react-component-meta",
-    "durationMs": 4717
+    "durationMs": 4273
   }
 }