@commercetools/nimbus-mcp 0.1.0 → 2.11.0

package/data/docs/routes/components-forms-field-errors.json

@@ -0,0 +1,557 @@
+{
+  "meta": {
+    "id": "Components-FieldErrors",
+    "title": "Field errors",
+    "exportName": "FieldErrors",
+    "description": "Context specific, localized error messages for individual form fields.",
+    "lifecycleState": "Stable",
+    "order": 999,
+    "repoPath": "packages/nimbus/src/components/field-errors/field-errors.mdx",
+    "menu": [
+      "Components",
+      "Forms",
+      "Field errors"
+    ],
+    "route": "components/forms/field-errors",
+    "tags": [
+      "component",
+      "form",
+      "validation",
+      "errors"
+    ],
+    "toc": [
+      {
+        "value": "Overview",
+        "href": "#overview",
+        "depth": 2,
+        "numbering": [
+          1,
+          1
+        ],
+        "parent": "root"
+      },
+      {
+        "value": "Resources",
+        "href": "#resources",
+        "depth": 3,
+        "numbering": [
+          1,
+          1,
+          1
+        ],
+        "parent": "root"
+      },
+      {
+        "value": "Variables",
+        "href": "#variables",
+        "depth": 2,
+        "numbering": [
+          1,
+          2
+        ],
+        "parent": "root"
+      },
+      {
+        "value": "Visual elements",
+        "href": "#visual-elements",
+        "depth": 3,
+        "numbering": [
+          1,
+          2,
+          1
+        ],
+        "parent": "root"
+      },
+      {
+        "value": "Built-in error types",
+        "href": "#built-in-error-types",
+        "depth": 2,
+        "numbering": [
+          1,
+          3
+        ],
+        "parent": "root"
+      },
+      {
+        "value": "With custom errors",
+        "href": "#with-custom-errors",
+        "depth": 3,
+        "numbering": [
+          1,
+          3,
+          1
+        ],
+        "parent": "root"
+      }
+    ],
+    "layout": "app-frame",
+    "tabs": [
+      {
+        "key": "overview",
+        "title": "Overview",
+        "order": 0
+      },
+      {
+        "key": "guidelines",
+        "title": "Guidelines",
+        "order": 2
+      },
+      {
+        "key": "dev",
+        "title": "Implementation",
+        "order": 3
+      },
+      {
+        "key": "a11y",
+        "title": "Accessibility",
+        "order": 4
+      }
+    ]
+  },
+  "mdx": "\n## Overview\n\nThe field errors component is a vital utility for user-friendly form validation,\nresponsible for displaying context-specific, localized error messages for\nindividual form fields. It ensures users receive clear, immediate feedback on\nvalidation issues, maintaining a consistent and accessible experience.\n\n### Resources\n\nDeep dive into implementation details and access the Nimbus design library.\n\n[Figma library](https://www.figma.com/design/AvtPX6g7OGGCRvNlatGOIY/NIMBUS-design-system?m=auto&node-id=5818-15877)\n[Storybook](https://nimbus-storybook.vercel.app/?path=/docs/components-fielderrors--docs)\n\n## Variables\n\nGet familiar with the features.\n\n### Visual elements\n\n**Color:** Default critical red color is typical for field errors, and a yellow\nwarning color for issues that are less critical. Custom colors can be added, but\nmake sure that there is a reason to use something different from known error\nbest practices.\n\n**Placement:** Field errors are located below the field that it is associated\nwith.\n\n```jsx live\nconst App = () => (\n    <Stack direction=\"column\" gap=\"200\">\n      <FieldErrors\n        errors={{ critical: true }}\n        isVisible={true}\n        renderError={(key) => {\n          if (key === \"critical\") {\n            return \"This is an error with a critical color.\";\n          }\n          return null;\n        }}\n      />\n      <FieldErrors\n        errors={{ warning: true }}\n        isVisible={true}\n        colorPalette=\"warning\"\n        renderError={(key) => {\n          if (key === \"warning\") {\n            return \"This is an error with a warning color.\";\n          }\n          return null;\n        }}\n      />\n    </Stack>\n);\n```\n\n## Built-in error types\n\nThese error types are included for `aboveMax`, `belowMin`, `blocked`,\n`duplicate`, `empty`, `format`, `fractions`, `invalid`, `invalidFromServer`,\n`max`, `min`, `missing`, `negative`, `notFound`, `outOfRange`.\n\n```jsx live\nconst App = () => (\n  <FieldErrors\n    errors={{\n      missing: true,\n      invalid: true,\n      empty: true,\n      min: true,\n      max: true,\n      format: true,\n      duplicate: true,\n      negative: true,\n      fractions: true,\n      belowMin: true,\n      aboveMax: true,\n      outOfRange: true,\n      invalidFromServer: true,\n      notFound: true,\n      blocked: true,\n    }}\n    isVisible={true}\n  />\n);\n```\n\n### With custom errors\n\nYou may use custom error text, read best practices with custom text\nrecommendations within the guideline section.\n\n```jsx live\nconst App = () => (\n  <Box>\n    <FieldErrors\n      errors={{\n        customError: true,\n        lengthError: true,\n        formatError: true,\n        duplicateError: true,\n        positiveError: true,\n        serverError: true,\n      }}\n      isVisible={true}\n      renderError={(key) => {\n        let message;\n        let icon;\n        switch (key) {\n          case \"customError\":\n            message = \"Hey! You forgot something important!\";\n            icon = <Icons.Whatshot/>;\n            break;\n          case \"lengthError\":\n            message = \"This needs to be longer!\";\n            icon = <Icons.Straighten />;\n            break;\n          case \"formatError\":\n            message = \"Please use the correct format!\";\n            icon = <Icons.TheaterComedy />;\n            break;\n          case \"duplicateError\":\n            message = \"This value is already taken!\";\n            icon = <Icons.RepeatOn />;\n            break;\n          case \"positiveError\":\n            message = \"Only positive numbers allowed!\";\n            icon = <Icons.BarChart />;\n            break;\n          case \"serverError\":\n            message = \"Server says no-no!\";\n            icon = <Icons.Announcement />;\n            break;\n          default:\n            return null; // Return null to fall back to built-in error handling\n        }\n        return (\n          <Flex gap=\"100\" alignItems=\"center\">\n            <Icon color=\"critical.11\">\n              {icon}\n            </Icon>\n            {message}\n          </Flex>\n        );\n      }}\n    />\n  </Box>\n);\n```\n",
+  "views": {
+    "overview": {
+      "mdx": "\n## Overview\n\nThe field errors component is a vital utility for user-friendly form validation,\nresponsible for displaying context-specific, localized error messages for\nindividual form fields. It ensures users receive clear, immediate feedback on\nvalidation issues, maintaining a consistent and accessible experience.\n\n### Resources\n\nDeep dive into implementation details and access the Nimbus design library.\n\n[Figma library](https://www.figma.com/design/AvtPX6g7OGGCRvNlatGOIY/NIMBUS-design-system?m=auto&node-id=5818-15877)\n[Storybook](https://nimbus-storybook.vercel.app/?path=/docs/components-fielderrors--docs)\n\n## Variables\n\nGet familiar with the features.\n\n### Visual elements\n\n**Color:** Default critical red color is typical for field errors, and a yellow\nwarning color for issues that are less critical. Custom colors can be added, but\nmake sure that there is a reason to use something different from known error\nbest practices.\n\n**Placement:** Field errors are located below the field that it is associated\nwith.\n\n```jsx live\nconst App = () => (\n    <Stack direction=\"column\" gap=\"200\">\n      <FieldErrors\n        errors={{ critical: true }}\n        isVisible={true}\n        renderError={(key) => {\n          if (key === \"critical\") {\n            return \"This is an error with a critical color.\";\n          }\n          return null;\n        }}\n      />\n      <FieldErrors\n        errors={{ warning: true }}\n        isVisible={true}\n        colorPalette=\"warning\"\n        renderError={(key) => {\n          if (key === \"warning\") {\n            return \"This is an error with a warning color.\";\n          }\n          return null;\n        }}\n      />\n    </Stack>\n);\n```\n\n## Built-in error types\n\nThese error types are included for `aboveMax`, `belowMin`, `blocked`,\n`duplicate`, `empty`, `format`, `fractions`, `invalid`, `invalidFromServer`,\n`max`, `min`, `missing`, `negative`, `notFound`, `outOfRange`.\n\n```jsx live\nconst App = () => (\n  <FieldErrors\n    errors={{\n      missing: true,\n      invalid: true,\n      empty: true,\n      min: true,\n      max: true,\n      format: true,\n      duplicate: true,\n      negative: true,\n      fractions: true,\n      belowMin: true,\n      aboveMax: true,\n      outOfRange: true,\n      invalidFromServer: true,\n      notFound: true,\n      blocked: true,\n    }}\n    isVisible={true}\n  />\n);\n```\n\n### With custom errors\n\nYou may use custom error text, read best practices with custom text\nrecommendations within the guideline section.\n\n```jsx live\nconst App = () => (\n  <Box>\n    <FieldErrors\n      errors={{\n        customError: true,\n        lengthError: true,\n        formatError: true,\n        duplicateError: true,\n        positiveError: true,\n        serverError: true,\n      }}\n      isVisible={true}\n      renderError={(key) => {\n        let message;\n        let icon;\n        switch (key) {\n          case \"customError\":\n            message = \"Hey! You forgot something important!\";\n            icon = <Icons.Whatshot/>;\n            break;\n          case \"lengthError\":\n            message = \"This needs to be longer!\";\n            icon = <Icons.Straighten />;\n            break;\n          case \"formatError\":\n            message = \"Please use the correct format!\";\n            icon = <Icons.TheaterComedy />;\n            break;\n          case \"duplicateError\":\n            message = \"This value is already taken!\";\n            icon = <Icons.RepeatOn />;\n            break;\n          case \"positiveError\":\n            message = \"Only positive numbers allowed!\";\n            icon = <Icons.BarChart />;\n            break;\n          case \"serverError\":\n            message = \"Server says no-no!\";\n            icon = <Icons.Announcement />;\n            break;\n          default:\n            return null; // Return null to fall back to built-in error handling\n        }\n        return (\n          <Flex gap=\"100\" alignItems=\"center\">\n            <Icon color=\"critical.11\">\n              {icon}\n            </Icon>\n            {message}\n          </Flex>\n        );\n      }}\n    />\n  </Box>\n);\n```\n",
+      "toc": [
+        {
+          "value": "Overview",
+          "href": "#overview",
+          "depth": 2,
+          "numbering": [
+            1,
+            1
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Resources",
+          "href": "#resources",
+          "depth": 3,
+          "numbering": [
+            1,
+            1,
+            1
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Variables",
+          "href": "#variables",
+          "depth": 2,
+          "numbering": [
+            1,
+            2
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Visual elements",
+          "href": "#visual-elements",
+          "depth": 3,
+          "numbering": [
+            1,
+            2,
+            1
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Built-in error types",
+          "href": "#built-in-error-types",
+          "depth": 2,
+          "numbering": [
+            1,
+            3
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "With custom errors",
+          "href": "#with-custom-errors",
+          "depth": 3,
+          "numbering": [
+            1,
+            3,
+            1
+          ],
+          "parent": "root"
+        }
+      ]
+    },
+    "a11y": {
+      "mdx": "\n## Accessibility\n\nAccessibility ensures that digital content and functionality are usable by\neveryone, including people with disabilities, by addressing visual, auditory,\ncognitive, and physical limitations.\n\n```jsx live\nconst App = () => (\n  <FieldErrors\n    errors={{ critical: true }}\n    isVisible={true}\n    renderError={(key) => {\n      if (key === \"critical\") {\n        return \"Provide your name to continue.\";\n      }\n      return null;\n    }}\n  />\n);\n```\n\n### Accessibility standards\n\n- **Instant announcement:** The root container uses `role=\"alert\"` to trigger\n  screen readers to immediately announce error messages when they become\n  visible, providing critical, instant feedback to the user.\n- **WCAG contrast:** The default critical color palette provides sufficient\n  contrast for the error text to meet WCAG AA standards. This must be maintained\n  when using custom colors.\n- **Actionable messaging:** Error messages should use clear, plain language that\n  focuses on what the user needs to do to fix the problem, not just what went\n  wrong (e.g., \"Password must be at least 8 characters\" instead of \"Length\n  validation failed\").\n- **Association:** When integrated with the FormField component, errors are\n  automatically associated with their input fields via ARIA, helping screen\n  readers clearly link the error message to the field that caused it.\n- **Color is supplemental:** Color (red tones) is used as a supplemental\n  indicator; the text content itself provides the error information, meeting\n  WCAG requirements for users with color vision deficiencies.\n- **Visibility control:** Always tie `isVisible` to the field's interaction\n  state (touched or blurred) to prevent users from hearing confusing\n  announcements before they've had a chance to input data.\n",
+      "toc": [
+        {
+          "value": "Accessibility",
+          "href": "#accessibility",
+          "depth": 2,
+          "numbering": [
+            1,
+            1
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Accessibility standards",
+          "href": "#accessibility-standards",
+          "depth": 3,
+          "numbering": [
+            1,
+            1,
+            1
+          ],
+          "parent": "root"
+        }
+      ]
+    },
+    "dev": {
+      "mdx": "\n## Getting started\n\n### Import\n\n```tsx\nimport { FieldErrors, type FieldErrorsProps } from '@commercetools/nimbus';\n```\n\n### Basic usage\n\nThe simplest implementation shows a single error message:\n\n```jsx live-dev\nconst App = () => (\n  <FieldErrors\n    errors={{ missing: true }}\n  />\n)\n```\n\n## Usage examples\n\n### Built-in error types\n\nFieldErrors provides localized messages for common validation scenarios. Errors are organized by category:\n\n#### Basic validation\n\n```jsx live-dev\nconst App = () => (\n  <Stack direction=\"column\" gap=\"400\">\n    <FieldErrors\n      errors={{ missing: true }}\n    />\n    <FieldErrors\n      errors={{ invalid: true }}\n    />\n    <FieldErrors\n      errors={{ empty: true }}\n    />\n  </Stack>\n)\n```\n\n#### Length validation\n\n```jsx live-dev\nconst App = () => (\n  <Stack direction=\"column\" gap=\"400\">\n    <FieldErrors\n      errors={{ min: true }}\n    />\n    <FieldErrors\n      errors={{ max: true }}\n    />\n  </Stack>\n)\n```\n\n#### Format validation\n\n```jsx live-dev\nconst App = () => (\n  <Stack direction=\"column\" gap=\"400\">\n    <FieldErrors\n      errors={{ format: true }}\n    />\n    <FieldErrors\n      errors={{ duplicate: true }}\n    />\n  </Stack>\n)\n```\n\n#### Numeric validation\n\n```jsx live-dev\nconst App = () => (\n  <Stack direction=\"column\" gap=\"400\">\n    <FieldErrors\n      errors={{ negative: true }}\n    />\n    <FieldErrors\n      errors={{ fractions: true }}\n    />\n    <FieldErrors\n      errors={{ belowMin: true }}\n    />\n    <FieldErrors\n      errors={{ aboveMax: true }}\n    />\n    <FieldErrors\n      errors={{ outOfRange: true }}\n    />\n  </Stack>\n)\n```\n\n#### Server validation\n\n```jsx live-dev\nconst App = () => (\n  <Stack direction=\"column\" gap=\"400\">\n    <FieldErrors\n      errors={{ invalidFromServer: true }}\n    />\n    <FieldErrors\n      errors={{ notFound: true }}\n    />\n    <FieldErrors\n      errors={{ blocked: true }}\n    />\n  </Stack>\n)\n```\n\n### Custom error messages\n\nOverride built-in messages for specific error types using `customMessages`:\n\n```jsx live-dev\nconst App = () => (\n  <Stack direction=\"column\" gap=\"400\">\n    <FieldErrors\n      errors={{ missing: true, min: true, format: true }}\n      customMessages={{\n        missing: \"🔥 Hey! You forgot something important!\",\n        min: \"📏 Password must be at least 8 characters\",\n        format: \"📧 Please enter a valid email address\"\n      }}\n    />\n  </Stack>\n)\n```\n\n### Custom error rendering\n\nUse `renderError` for complete control over specific error messages:\n\n```jsx live-dev\nconst App = () => (\n  <FieldErrors\n    errors={{\n      duplicate: true,\n      customValidation: true,\n      missing: true\n    }}\n    renderError={(key) => {\n      switch (key) {\n        case 'duplicate':\n          return 'This email is already registered. Please use a different email.';\n        case 'customValidation':\n          return 'This is a custom validation error.';\n        default:\n          return null; // Falls back to built-in messages\n      }\n    }}\n  />\n)\n```\n\n### Default error renderer\n\nUse `renderDefaultError` as a fallback when `renderError` returns null:\n\n```jsx live-dev\nconst App = () => (\n  <FieldErrors\n    errors={{\n      priority: true,\n      fallback: true,\n      missing: true\n    }}\n    renderError={(key) => {\n      if (key === 'priority') {\n        return 'High priority custom error!';\n      }\n      return null; // Falls through to renderDefaultError\n    }}\n    renderDefaultError={(key) => {\n      if (key === 'fallback') {\n        return 'Fallback error handled by renderDefaultError';\n      }\n      return null; // Falls through to built-in messages\n    }}\n  />\n)\n```\n\n**Error resolution priority:**\n1. `renderError` - Highest priority custom rendering\n2. `renderDefaultError` - Fallback custom rendering\n3. `customMessages` - Custom text for built-in error types\n4. Built-in messages - Localized default messages\n\n### Visibility control\n\nControl when errors are displayed using the `isVisible` prop:\n\n```jsx live-dev\nconst App = () => {\n  const [showErrors, setShowErrors] = useState(false);\n\n  return (\n    <Stack direction=\"column\" gap=\"400\">\n      <Button onPress={() => setShowErrors(!showErrors)}>\n        {showErrors ? 'Hide Errors' : 'Show Errors'}\n      </Button>\n      <FieldErrors\n        errors={{ missing: true, invalid: true }}\n        isVisible={showErrors}\n      />\n    </Stack>\n  );\n}\n```\n\n### Integration with FormField\n\nFieldErrors integrates seamlessly with FormField for form validation:\n\n```jsx live-dev\nconst App = () => {\n  const [email, setEmail] = useState('');\n  const [age, setAge] = useState('');\n  const [touched, setTouched] = useState({ email: false, age: false });\n\n  const validateEmail = (value) => {\n    const errors = {};\n    if (!value) {\n      errors.missing = true;\n    } else if (!/\\S+@\\S+\\.\\S+/.test(value)) {\n      errors.format = true;\n    } else if (value === 'admin@test.com') {\n      errors.duplicate = true;\n    }\n    return errors;\n  };\n\n  const validateAge = (value) => {\n    const errors = {};\n    if (!value) {\n      errors.missing = true;\n    } else if (Number(value) < 0) {\n      errors.negative = true;\n    } else if (Number(value) < 18) {\n      errors.belowMin = true;\n    }\n    return errors;\n  };\n\n  const emailErrors = validateEmail(email);\n  const ageErrors = validateAge(age);\n  const hasEmailErrors = Object.values(emailErrors).some(Boolean);\n  const hasAgeErrors = Object.values(ageErrors).some(Boolean);\n\n  return (\n    <Stack direction=\"column\" gap=\"400\" maxWidth=\"400px\">\n      <FormField.Root isInvalid={hasEmailErrors && touched.email}>\n        <FormField.Label>Email Address *</FormField.Label>\n        <FormField.Input>\n          <TextInput\n            type=\"email\"\n            value={email}\n            onChange={setEmail}\n            onBlur={() => setTouched({ ...touched, email: true })}\n          />\n        </FormField.Input>\n        <FormField.Error>\n          <FieldErrors\n            errors={emailErrors}\n            isVisible={touched.email}\n            renderError={(key) => {\n              if (key === 'format') {\n                return 'Please enter a valid email address.';\n              }\n              if (key === 'duplicate') {\n                return 'This email is already registered.';\n              }\n              return null;\n            }}\n          />\n        </FormField.Error>\n      </FormField.Root>\n\n      <FormField.Root isInvalid={hasAgeErrors && touched.age}>\n        <FormField.Label>Age *</FormField.Label>\n        <FormField.Input>\n          <TextInput\n            type=\"number\"\n            value={age}\n            onChange={setAge}\n            onBlur={() => setTouched({ ...touched, age: true })}\n          />\n        </FormField.Input>\n        <FormField.Error>\n          <FieldErrors\n            errors={ageErrors}\n            isVisible={touched.age}\n            customMessages={{\n              belowMin: 'You must be at least 18 years old.'\n            }}\n          />\n        </FormField.Error>\n      </FormField.Root>\n    </Stack>\n  );\n}\n```\n\n## Component requirements\n\n### Error object format\n\nThe `errors` prop accepts an object mapping error keys to boolean values:\n\n```tsx\ntype FieldErrorsData = Record<string, boolean>;\n\n// Example\nconst errors = {\n  missing: true,      // Show \"missing\" error\n  duplicate: false,   // Hide \"duplicate\" error\n  format: true        // Show \"format\" error\n};\n```\n\n**Built-in error types:**\n\nUse the `FieldErrorTypes` constants for type-safe error keys:\n\n```tsx\nimport { FieldErrors } from '@commercetools/nimbus';\n\nconst { errorTypes } = FieldErrors;\n\n// Access built-in error type constants\nerrorTypes.MISSING;              // \"missing\"\nerrorTypes.INVALID;              // \"invalid\"\nerrorTypes.EMPTY;                // \"empty\"\nerrorTypes.MIN_LENGTH;           // \"min\"\nerrorTypes.MAX_LENGTH;           // \"max\"\nerrorTypes.FORMAT;               // \"format\"\nerrorTypes.DUPLICATE;            // \"duplicate\"\nerrorTypes.NEGATIVE;             // \"negative\"\nerrorTypes.FRACTIONS;            // \"fractions\"\nerrorTypes.BELOW_MIN;            // \"belowMin\"\nerrorTypes.ABOVE_MAX;            // \"aboveMax\"\nerrorTypes.OUT_OF_RANGE;         // \"outOfRange\"\nerrorTypes.INVALID_FROM_SERVER;  // \"invalidFromServer\"\nerrorTypes.NOT_FOUND;            // \"notFound\"\nerrorTypes.BLOCKED;              // \"blocked\"\n```\n\n## Accessibility\n\nThe FieldErrors component includes `role=\"alert\"` by default to announce errors to screen readers. When integrating with form fields:\n\n**Visibility timing:**\n- Only show errors after user interaction (blur/submit)\n- Use the `touched` state pattern to control `isVisible`\n- Don't show errors on initial render or while typing\n\n**ARIA relationships:**\n\nAssociate error messages with form fields using `aria-describedby`:\n\n```tsx\n<FormField.Root isInvalid={hasErrors && touched}>\n  <FormField.Label>Field Label</FormField.Label>\n  <FormField.Input>\n    <TextInput\n      aria-describedby=\"field-errors\"\n    />\n  </FormField.Input>\n  <FormField.Error>\n    <FieldErrors\n      id=\"field-errors\"\n      errors={errors}\n      isVisible={touched}\n    />\n  </FormField.Error>\n</FormField.Root>\n```\n\nIf your use case requires tracking and analytics for this component, it is good practice to add a **persistent**, **unique** id to the component:\n\n```tsx\nconst PERSISTENT_ID = \"example-field-errors\";\n\nexport const Example = () => (\n  <FieldErrors\n    id={PERSISTENT_ID}\n    errors={errors}\n  />\n);\n```\n\n#### Keyboard navigation\n\nFieldErrors is a static display component with no keyboard interactions. Users navigate to form fields using standard keyboard controls:\n- `Tab` / `Shift+Tab`: Move focus between form fields\n- Error messages are announced by screen readers when fields receive focus or when errors change\n\n## API reference\n\n<PropsTable id=\"FieldErrors\" />\n\n## Testing your implementation\n\nThese examples demonstrate how to test your implementation when using FieldErrors within your application. As the component's internal functionality is already tested by Nimbus, these patterns help you verify your integration and application-specific logic.\n\n### Basic Rendering Tests\n\nVerify the component renders with expected error messages\n\n```tsx\nimport { describe, it, expect } from \"vitest\";\nimport { render, screen } from \"@testing-library/react\";\nimport { FieldErrors, FormField, NimbusProvider } from \"@commercetools/nimbus\";\n\ndescribe(\"FieldErrors - Basic rendering\", () => {\n  it(\"renders built-in error message\", () => {\n    render(\n      <NimbusProvider>\n        <FieldErrors errors={{ missing: true }} isVisible={true} />\n      </NimbusProvider>\n    );\n\n    expect(screen.getByRole(\"alert\")).toBeInTheDocument();\n    expect(\n      screen.getByText(\"This field is required. Provide a value.\")\n    ).toBeInTheDocument();\n  });\n\n  it(\"does not render when isVisible is false\", () => {\n    render(\n      <NimbusProvider>\n        <FieldErrors errors={{ missing: true }} isVisible={false} />\n      </NimbusProvider>\n    );\n\n    expect(screen.queryByRole(\"alert\")).not.toBeInTheDocument();\n  });\n\n  it(\"does not render when all errors are false\", () => {\n    render(\n      <NimbusProvider>\n        <FieldErrors\n          errors={{ missing: false, invalid: false }}\n          isVisible={true}\n        />\n      </NimbusProvider>\n    );\n\n    expect(screen.queryByRole(\"alert\")).not.toBeInTheDocument();\n  });\n});\n```\n\n### Custom Error Rendering Tests\n\nTest custom error message rendering\n\n```tsx\nimport { describe, it, expect } from \"vitest\";\nimport { render, screen } from \"@testing-library/react\";\nimport { FieldErrors, FormField, NimbusProvider } from \"@commercetools/nimbus\";\n\ndescribe(\"FieldErrors - Custom rendering\", () => {\n  it(\"renders custom error messages via renderError\", () => {\n    render(\n      <NimbusProvider>\n        <FieldErrors\n          errors={{ duplicate: true }}\n          isVisible={true}\n          renderError={(key) => {\n            if (key === \"duplicate\") {\n              return \"This email is already registered.\";\n            }\n            return null;\n          }}\n        />\n      </NimbusProvider>\n    );\n\n    expect(\n      screen.getByText(\"This email is already registered.\")\n    ).toBeInTheDocument();\n  });\n\n  it(\"renders custom messages via customMessages prop\", () => {\n    render(\n      <NimbusProvider>\n        <FieldErrors\n          errors={{ missing: true, min: true }}\n          isVisible={true}\n          customMessages={{\n            missing: \"Please fill out this field!\",\n            min: \"Must be at least 8 characters long.\",\n          }}\n        />\n      </NimbusProvider>\n    );\n\n    expect(screen.getByText(\"Please fill out this field!\")).toBeInTheDocument();\n    expect(\n      screen.getByText(\"Must be at least 8 characters long.\")\n    ).toBeInTheDocument();\n  });\n\n  it(\"falls back to built-in messages when renderError returns null\", () => {\n    render(\n      <NimbusProvider>\n        <FieldErrors\n          errors={{ missing: true, duplicate: true }}\n          isVisible={true}\n          renderError={(key) => {\n            if (key === \"duplicate\") {\n              return \"Custom duplicate message\";\n            }\n            return null; // Falls back to built-in for 'missing'\n          }}\n        />\n      </NimbusProvider>\n    );\n\n    expect(screen.getByText(\"Custom duplicate message\")).toBeInTheDocument();\n    expect(\n      screen.getByText(\"This field is required. Provide a value.\")\n    ).toBeInTheDocument();\n  });\n});\n```\n\n### FormField Integration Tests\n\nTest FieldErrors within FormField contexts\n\n```tsx\nimport { describe, it, expect } from \"vitest\";\nimport { render, screen } from \"@testing-library/react\";\nimport { FieldErrors, FormField, NimbusProvider } from \"@commercetools/nimbus\";\n\ndescribe(\"FieldErrors - FormField integration\", () => {\n  it(\"shows errors when isVisible is true\", () => {\n    const errors = { missing: true };\n\n    render(\n      <NimbusProvider>\n        <FormField.Root isInvalid={true}>\n          <FormField.Label>Email</FormField.Label>\n          <FormField.Error>\n            <FieldErrors errors={errors} isVisible={true} />\n          </FormField.Error>\n        </FormField.Root>\n      </NimbusProvider>\n    );\n\n    expect(screen.getByRole(\"alert\")).toBeInTheDocument();\n    expect(\n      screen.getByText(\"This field is required. Provide a value.\")\n    ).toBeInTheDocument();\n  });\n\n  it(\"hides errors when isVisible is false\", () => {\n    const errors = { missing: true };\n\n    render(\n      <NimbusProvider>\n        <FormField.Root isInvalid={true}>\n          <FormField.Label>Email</FormField.Label>\n          <FormField.Error>\n            <FieldErrors errors={errors} isVisible={false} />\n          </FormField.Error>\n        </FormField.Root>\n      </NimbusProvider>\n    );\n\n    expect(screen.queryByRole(\"alert\")).not.toBeInTheDocument();\n  });\n});\n```\n\n### Testing Error Priority\n\nTest the error resolution cascade\n\n```tsx\nimport { describe, it, expect } from \"vitest\";\nimport { render, screen } from \"@testing-library/react\";\nimport { FieldErrors, FormField, NimbusProvider } from \"@commercetools/nimbus\";\n\ndescribe(\"FieldErrors - Error priority\", () => {\n  it(\"prioritizes renderError over renderDefaultError\", () => {\n    render(\n      <NimbusProvider>\n        <FieldErrors\n          errors={{ missing: true }}\n          isVisible={true}\n          renderError={() => \"Priority error\"}\n          renderDefaultError={() => \"Fallback error\"}\n        />\n      </NimbusProvider>\n    );\n\n    expect(screen.getByText(\"Priority error\")).toBeInTheDocument();\n    expect(screen.queryByText(\"Fallback error\")).not.toBeInTheDocument();\n  });\n\n  it(\"prioritizes customMessages over built-in messages\", () => {\n    render(\n      <NimbusProvider>\n        <FieldErrors\n          errors={{ missing: true }}\n          isVisible={true}\n          customMessages={{\n            missing: \"Custom missing message\",\n          }}\n        />\n      </NimbusProvider>\n    );\n\n    expect(screen.getByText(\"Custom missing message\")).toBeInTheDocument();\n    expect(\n      screen.queryByText(\"This field is required. Provide a value.\")\n    ).not.toBeInTheDocument();\n  });\n\n  it(\"uses built-in messages as final fallback\", () => {\n    render(\n      <NimbusProvider>\n        <FieldErrors\n          errors={{ missing: true }}\n          isVisible={true}\n          renderError={() => null}\n          renderDefaultError={() => null}\n        />\n      </NimbusProvider>\n    );\n\n    expect(\n      screen.getByText(\"This field is required. Provide a value.\")\n    ).toBeInTheDocument();\n  });\n});\n```\n\n\n## Resources\n\n- [Storybook](https://nimbus-storybook.vercel.app/?path=/docs/components-fielderrors--docs)\n- [FormField Component](components/inputs/formfield)\n",
+      "toc": [
+        {
+          "value": "Getting started",
+          "href": "#getting-started",
+          "depth": 2,
+          "numbering": [
+            1,
+            1
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Import",
+          "href": "#import",
+          "depth": 3,
+          "numbering": [
+            1,
+            1,
+            1
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Basic usage",
+          "href": "#basic-usage",
+          "depth": 3,
+          "numbering": [
+            1,
+            1,
+            2
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Usage examples",
+          "href": "#usage-examples",
+          "depth": 2,
+          "numbering": [
+            1,
+            2
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Built-in error types",
+          "href": "#built-in-error-types",
+          "depth": 3,
+          "numbering": [
+            1,
+            2,
+            1
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Basic validation",
+          "href": "#basic-validation",
+          "depth": 4,
+          "numbering": [
+            1,
+            2,
+            1,
+            1
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Length validation",
+          "href": "#length-validation",
+          "depth": 4,
+          "numbering": [
+            1,
+            2,
+            1,
+            2
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Format validation",
+          "href": "#format-validation",
+          "depth": 4,
+          "numbering": [
+            1,
+            2,
+            1,
+            3
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Numeric validation",
+          "href": "#numeric-validation",
+          "depth": 4,
+          "numbering": [
+            1,
+            2,
+            1,
+            4
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Server validation",
+          "href": "#server-validation",
+          "depth": 4,
+          "numbering": [
+            1,
+            2,
+            1,
+            5
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Custom error messages",
+          "href": "#custom-error-messages",
+          "depth": 3,
+          "numbering": [
+            1,
+            2,
+            2
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Custom error rendering",
+          "href": "#custom-error-rendering",
+          "depth": 3,
+          "numbering": [
+            1,
+            2,
+            3
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Default error renderer",
+          "href": "#default-error-renderer",
+          "depth": 3,
+          "numbering": [
+            1,
+            2,
+            4
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Visibility control",
+          "href": "#visibility-control",
+          "depth": 3,
+          "numbering": [
+            1,
+            2,
+            5
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Integration with FormField",
+          "href": "#integration-with-formfield",
+          "depth": 3,
+          "numbering": [
+            1,
+            2,
+            6
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Component requirements",
+          "href": "#component-requirements",
+          "depth": 2,
+          "numbering": [
+            1,
+            3
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Error object format",
+          "href": "#error-object-format",
+          "depth": 3,
+          "numbering": [
+            1,
+            3,
+            1
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Accessibility",
+          "href": "#accessibility",
+          "depth": 2,
+          "numbering": [
+            1,
+            4
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Keyboard navigation",
+          "href": "#keyboard-navigation",
+          "depth": 4,
+          "numbering": [
+            1,
+            4,
+            1,
+            1
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "API reference",
+          "href": "#api-reference",
+          "depth": 2,
+          "numbering": [
+            1,
+            5
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Testing your implementation",
+          "href": "#testing-your-implementation",
+          "depth": 2,
+          "numbering": [
+            1,
+            6
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Basic Rendering Tests",
+          "href": "#basic-rendering-tests",
+          "depth": 3,
+          "numbering": [
+            1,
+            6,
+            1
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Custom Error Rendering Tests",
+          "href": "#custom-error-rendering-tests",
+          "depth": 3,
+          "numbering": [
+            1,
+            6,
+            2
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "FormField Integration Tests",
+          "href": "#formfield-integration-tests",
+          "depth": 3,
+          "numbering": [
+            1,
+            6,
+            3
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Testing Error Priority",
+          "href": "#testing-error-priority",
+          "depth": 3,
+          "numbering": [
+            1,
+            6,
+            4
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Resources",
+          "href": "#resources",
+          "depth": 2,
+          "numbering": [
+            1,
+            7
+          ],
+          "parent": "root"
+        }
+      ]
+    },
+    "guidelines": {
+      "mdx": "\n## Guidelines\n\nField error guidelines establish how validation issues are communicated to the\nuser, ensuring messages are clear, concise, actionable, and visually presented\nwith appropriate urgency and accessibility features.\n\n### Best practices\n\n- **Validate inline and on blur:** Only show error messages after the user has\n  finished interacting with the field (i.e., when they click or tab out).\n  Showing errors while the user is typing is highly distracting.\n- **Be specific and actionable:** Tell the user what went wrong and how to fix\n  it, not just that the input is invalid.\n- **Be concise:** Keep error messages short and easy to read quickly. If the fix\n  is simple, the message should be too.\n- **Avoid technical jargon:** Use plain, user-friendly language. Avoid\n  referencing internal system terms or validation rules (like \"Regex failure\" or\n  \"API 404\").\n- **Group and prioritize:** When showing multiple errors, group them logically\n  and ensure the most critical or blocking error is listed first.\n- **Use clear visual cues:** Use the critical/red color palette for the border,\n  text, and an accompanying error icon to draw immediate attention.\n- **Place errors contextually:** Position the error message directly below the\n  input field it refers to. This maintains a strong visual association and\n  reading flow.\n- **Minimize layout shift:** Design the error message container so that when the\n  message appears, it doesn't cause the rest of the form elements below it to\n  jump or shift excessively.\n- **Distinguish severity:** Use Warning/Orange tones for non-blocking issues or\n  cautionary alerts, reserving Critical/Red for errors that truly prevent\n  submission.\n\n### Tone of voice\n\n- **Avoid using \"please\":** When the UI is requesting information (e.g., \"Enter\n  your password\") or enforcing a rule (e.g., \"Password must be 8 characters\n  long\"), the language should be direct and authoritative. Using \"please\" can\n  sometimes weaken the instructional tone, making the requirement seem optional\n  or negotiable.\n  - **Localization formality:** If you use \"please\" inconsistently, it can\n    confuse users. Furthermore, translating polite phrases across languages can\n    be complex and sometimes lead to awkward or overly formal phrasing in the\n    localized UI.\n- **Stay neutral:** Maintain a helpful, professional, and consistent tone across\n  all error types. Avoid attempting to be overly clever or humorous, as this can\n  be misunderstood during a stressful moment.\n- **Avoid blame:** Never use accusatory language (e.g., \"You failed,\" \"You\n  must\"). Use neutral, system-focused language.\n- **Use softening words (sparingly):** Use words like \"sorry\" appropriately to\n  soften the message, especially for critical errors. Example: \"Sorry, that rank\n  order is already taken. Please try another.\" Do not overuse softening\n  language. A direct, informative tone is typically perceived as more\n  professional and helpful than an overly conversational one in task-focused\n  areas.\n\n### Usage\n\nField error messages are used to communicate validation failures immediately\nafter a user's unsuccessful input attempt, providing specific, actionable\nguidance on how to correct the mistake.\n\n\n> [!TIP]\\\n> When to use\n\n- **Validation fails on blur/touch:** Use an error message immediately after the\n  user attempts to interact with the field (clicks in and clicks out) and the\n  input fails validation (e.g., they leave a required field empty).\n- **Preventing form submission:** Use an error message to clearly indicate which\n  fields must be corrected before the form can be successfully submitted.\n- **Providing actionable correction:** Use the message to tell the user exactly\n  how to fix the problem (e.g., \"Password must contain one number\" or \"Please\n  enter 8 or more characters\").\n- **After server rejection:** Use an error message to display a concise message\n  from the server indicating why the submitted value was rejected (e.g., \"That\n  email address is already registered\").\n\n> [!CAUTION]\\\n> When not to use\n\n- **When the form first loads:** Do not show \"This field is required\" error\n  messages on empty fields when the form initially loads. This is highly\n  distracting and premature.\n- **While the user is typing:** Avoid showing a hard error message (like a red\n  border and critical text) while the user is actively typing; it is\n  interruptive. Use subtle positive feedback (like a green checkmark) for\n  successful input instead.\n- **For simple hints:** Do not use an error message container for basic\n  formatting hints or guidelines; use neutral helper text for these non-critical\n  purposes.\n- **For non-blocking issues:** Avoid using the critical (red) error visual\n  treatment for issues that won't actually prevent the form from submitting. Use\n  a softer warning or info tone instead.\n- **When using a different component:** Do not attach field errors to components\n  that don't accept direct user text input (like a toggle switch or a button\n  group), as the interaction models are different.\n\n### Do’s and dont’s for error state messages\n\n> [!TIP]\\\n> **Do**\n>\n> - Write concisely in plain language, avoiding technical jargon, error codes,\n>   or ambiguous terms.\n> - Position the error message directly next to the field it pertains to, and\n>   highlight the source of the problem.\n> - Show the error message immediately after the user interacts with the field\n>   or attempts to submit the form.\n> - Clearing the error message and the visual cues as soon as the user corrects\n>   the input.\n> - If known, provide suggestions or links to helpful resources (e.g., a \"Forgot\n>   Password?\" link).\n\n```jsx live\nconst App = () => (\n  <FormField.Root isInvalid >\n    <FormField.Label>Name</FormField.Label>\n    <FormField.Input>\n      <TextInput />\n    </FormField.Input>\n    <FormField.Error>\n      <FieldErrors\n        errors={{ missing: true }}\n        isVisible={true}\n      />\n    </FormField.Error>\n  </FormField.Root>\n);\n```\n\n> [!CAUTION]\\\n> **Don't**\n>\n> - Avoid harsh, accusatory, or negative language.\n> - Never use technical terms or obscure codes.\n> - Avoid generic messages like \"Something went wrong\" or \"Error.\"\n> - Don't display \"Required\" field errors when the form first loads, as this\n>   creates user fatigue.\n> - Keep the error message inline and contextual.\n> - Avoid giving away hints that could aid malicious users (e.g., don't confirm\n>   if a username or email is not registered).\n\n```jsx live\nconst App = () => (\n  <Stack direction=\"column\" gap=\"200\">\n    <FormField.Root isInvalid>\n      <FormField.Label>Name</FormField.Label>\n      <FormField.Input>\n        <TextInput width=\"9600\" />\n      </FormField.Input>\n    </FormField.Root>\n    <FieldErrors\n      errors={{ missing: true }}\n      isVisible={true}\n      renderError={(key) => {\n        if (key === \"missing\") {\n          return (\n            <Flex gap=\"100\" alignItems=\"center\">\n              <Icon color=\"critical.11\" boxSize=\"600\">\n                <Icons.ErrorOutline />\n              </Icon>\n              You put in the wrong details. Correct without invalidating this form to continue. We are very disappointed in your interactions here and one more mistake we will send a message automatically to your admin.\n            </Flex>\n          );\n        }\n        return null;\n      }}\n    />\n  </Stack>\n);\n```\n",
+      "toc": [
+        {
+          "value": "Guidelines",
+          "href": "#guidelines",
+          "depth": 2,
+          "numbering": [
+            1,
+            1
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Best practices",
+          "href": "#best-practices",
+          "depth": 3,
+          "numbering": [
+            1,
+            1,
+            1
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Tone of voice",
+          "href": "#tone-of-voice",
+          "depth": 3,
+          "numbering": [
+            1,
+            1,
+            2
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Usage",
+          "href": "#usage",
+          "depth": 3,
+          "numbering": [
+            1,
+            1,
+            3
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Do’s and dont’s for error state messages",
+          "href": "#dos-and-donts-for-error-state-messages",
+          "depth": 3,
+          "numbering": [
+            1,
+            1,
+            4
+          ],
+          "parent": "root"
+        }
+      ]
+    }
+  }
+}