@commercetools/nimbus-mcp 0.1.0 → 2.11.0

package/data/docs/routes/patterns-fields-text-input-field.json

@@ -0,0 +1,404 @@
+{
+  "meta": {
+    "id": "Patterns-TextInputField",
+    "title": "Text input field",
+    "exportName": "TextInputField",
+    "description": "This pattern component integrates the TextInput within a FormField using a simple, consistent, and opinionated API.",
+    "order": 999,
+    "repoPath": "packages/nimbus/src/patterns/fields/text-input-field/text-input-field.mdx",
+    "menu": [
+      "Patterns",
+      "Fields",
+      "Text input field"
+    ],
+    "route": "patterns/fields/text-input-field",
+    "tags": [
+      "component",
+      "pattern",
+      "field",
+      "TextInput",
+      "TextInputField"
+    ],
+    "toc": [
+      {
+        "value": "Overview",
+        "href": "#overview",
+        "depth": 2,
+        "numbering": [
+          1,
+          1
+        ],
+        "parent": "root"
+      },
+      {
+        "value": "Resources",
+        "href": "#resources",
+        "depth": 3,
+        "numbering": [
+          1,
+          1,
+          1
+        ],
+        "parent": "root"
+      }
+    ],
+    "layout": "app-frame",
+    "tabs": [
+      {
+        "key": "overview",
+        "title": "Overview",
+        "order": 0
+      },
+      {
+        "key": "dev",
+        "title": "Implementation",
+        "order": 3
+      }
+    ]
+  },
+  "mdx": "\n## Overview\n\nTextInputField is a pattern component that combines the FormField wrapper with the TextInput component. This integration provides a complete form field experience including accessible labels, helper text descriptions, info popovers for supplementary information, and comprehensive validation and error handling, all through a simplified, opinionated API.\n\n### Resources\n\nFor detailed guidance on the individual components that make up this pattern, consult the component guidelines:\n\n- [TextInput Guidelines](/components/inputs/textinput) - Text input patterns, interaction guidelines, and accessibility standards\n- [FormField Guidelines](/components/inputs/formfield) - Label options, helper text, validation patterns, and form field accessibility\n- [Storybook](https://nimbus-storybook.vercel.app/?path=/docs/patterns-fields-textinputfield--docs)\n",
+  "views": {
+    "overview": {
+      "mdx": "\n## Overview\n\nTextInputField is a pattern component that combines the FormField wrapper with the TextInput component. This integration provides a complete form field experience including accessible labels, helper text descriptions, info popovers for supplementary information, and comprehensive validation and error handling, all through a simplified, opinionated API.\n\n### Resources\n\nFor detailed guidance on the individual components that make up this pattern, consult the component guidelines:\n\n- [TextInput Guidelines](/components/inputs/textinput) - Text input patterns, interaction guidelines, and accessibility standards\n- [FormField Guidelines](/components/inputs/formfield) - Label options, helper text, validation patterns, and form field accessibility\n- [Storybook](https://nimbus-storybook.vercel.app/?path=/docs/patterns-fields-textinputfield--docs)\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"
+        }
+      ]
+    },
+    "dev": {
+      "mdx": "\n## Comparison: field pattern vs manual composition\n\n**With TextInputField:**\n```tsx\n<TextInputField\n  label=\"Project name\"\n  description=\"Enter a descriptive name\"\n  value={value}\n  onChange={setValue}\n  errors={errors}\n  touched={touched}\n  isRequired\n/>\n```\n\n**Manual composition:**\n```tsx\n<FormField.Root isInvalid={!!(errors && touched)} isRequired>\n  <FormField.Label>Project name</FormField.Label>\n  <FormField.Input>\n    <TextInput\n      value={value}\n      onChange={setValue}\n      width=\"full\"\n    />\n  </FormField.Input>\n  <FormField.Description>\n    Enter a descriptive name\n  </FormField.Description>\n  {touched && errors && (\n    <FormField.Error>\n      <FieldErrors errors={errors} />\n    </FormField.Error>\n  )}\n</FormField.Root>\n```\n\n### When to use which\n\n**Use TextInputField when:**\n- Building standard forms with typical field layouts\n- You want consistent field patterns across your app\n- You need built-in error handling with FieldErrors\n- You want to minimize boilerplate code\n\n**Use TextInput with manual FormField composition when:**\n- You need custom field layouts\n- You're building complex, non-standard forms\n- You need granular control over FormField sub-components\n- You require a different error handling implementation\n\n## Getting started\n\n### Import\n\n```tsx\nimport { TextInputField, type TextInputFieldProps } from '@commercetools/nimbus';\n```\n\n### Basic usage\n\nThe simplest implementation with a label and controlled state:\n\n```jsx live-dev\nconst App = () => {\n  const [value, setValue] = useState<string>('');\n\n  return (\n    <TextInputField\n      label=\"Username\"\n      value={value}\n      onChange={setValue}\n    />\n  );\n}\n```\n\n## Usage examples\n\n### Size options\n\nThe `sm` and `md` size variants are available to match your interface density:\n\n```jsx live-dev\nconst App = () => {\n  const [valueSmall, setValueSmall] = useState<string>('');\n  const [valueMedium, setValueMedium] = useState<string>('');\n\n  return (\n    <Stack direction=\"column\" gap=\"400\">\n      <TextInputField\n        size=\"sm\"\n        label=\"Small input\"\n        value={valueSmall}\n        onChange={setValueSmall}\n        placeholder=\"Small size\"\n      />\n      <TextInputField\n        size=\"md\"\n        label=\"Medium input\"\n        value={valueMedium}\n        onChange={setValueMedium}\n        placeholder=\"Medium size (default)\"\n      />\n    </Stack>\n  );\n}\n```\n\n### Visual variants\n\nChoose between `solid` and `ghost` variants to match your design context:\n\n```jsx live-dev\nconst App = () => {\n  const [valueSolid, setValueSolid] = useState<string>('');\n  const [valueGhost, setValueGhost] = useState<string>('');\n\n  return (\n    <Stack direction=\"column\" gap=\"400\">\n      <TextInputField\n        variant=\"solid\"\n        label=\"Solid variant\"\n        value={valueSolid}\n        onChange={setValueSolid}\n        placeholder=\"Solid variant (default)\"\n      />\n      <TextInputField\n        variant=\"ghost\"\n        label=\"Ghost variant\"\n        value={valueGhost}\n        onChange={setValueGhost}\n        placeholder=\"Ghost variant\"\n      />\n    </Stack>\n  );\n}\n```\n\n### With description\n\nAdd helper text below the input to provide context:\n\n```jsx live-dev\nconst App = () => {\n  const [value, setValue] = useState<string>('');\n\n  return (\n    <TextInputField\n      label=\"Project name\"\n      description=\"Choose a unique name that describes your project\"\n      value={value}\n      onChange={setValue}\n      placeholder=\"My Awesome Project\"\n    />\n  );\n}\n```\n\n### With validation errors\n\nShow error messages when the field is touched and has validation errors:\n\n```jsx live-dev\nconst App = () => {\n  const [value, setValue] = useState<string>('');\n  const [touched, setTouched] = useState<boolean>(false);\n\n  // Simulate validation: require at least 3 characters\n  const errors = touched && value.length < 3 ? { missing: true } : undefined;\n\n  return (\n    <TextInputField\n      label=\"Username\"\n      description=\"Enter at least 3 characters\"\n      value={value}\n      onChange={setValue}\n      onBlur={() => setTouched(true)}\n      errors={errors}\n      touched={touched}\n      isRequired\n      placeholder=\"johndoe\"\n    />\n  );\n}\n```\n\n**Note**: Errors only display when both `touched={true}` and `errors` exist. This prevents showing errors before the user interacts with the field.\n\n### With info popover\n\nProvide additional context through an info button and popover:\n\n```jsx live-dev\nconst App = () => {\n  const [value, setValue] = useState<string>('');\n\n  return (\n    <TextInputField\n      label=\"API Key\"\n      description=\"Enter your API key for authentication\"\n      info=\"Your API key can be found in your account settings under 'Developers'. Keep this key secure and do not share it publicly.\"\n      value={value}\n      onChange={setValue}\n      type=\"password\"\n    />\n  );\n}\n```\n\n### Required field\n\nMark fields as required with the `isRequired` prop:\n\n```jsx live-dev\nconst App = () => {\n  const [value, setValue] = useState<string>('');\n\n  return (\n    <TextInputField\n      label=\"Email address\"\n      description=\"We'll use this to contact you\"\n      value={value}\n      onChange={setValue}\n      isRequired\n      placeholder=\"user@example.com\"\n    />\n  );\n}\n```\n\n### Disabled state\n\nPrevent user interaction with the `isDisabled` prop:\n\n```jsx live-dev\nconst App = () => {\n  const [value, setValue] = useState<string>('Cannot edit this');\n\n  return (\n    <TextInputField\n      label=\"Account ID\"\n      description=\"This field cannot be modified\"\n      value={value}\n      onChange={setValue}\n      isDisabled\n    />\n  );\n}\n```\n\n### Read-only state\n\nDisplay a non-editable value with the `isReadOnly` prop:\n\n```jsx live-dev\nconst App = () => {\n  const [value, setValue] = useState<string>('Read-only value');\n\n  return (\n    <TextInputField\n      label=\"System-generated ID\"\n      description=\"This value is automatically generated\"\n      value={value}\n      onChange={setValue}\n      isReadOnly\n    />\n  );\n}\n```\n\n### Different input types\n\nUse the `type` prop to specify the HTML input type:\n\n```jsx live-dev\nconst App = () => {\n  const [email, setEmail] = useState<string>('');\n  const [password, setPassword] = useState<string>('');\n  const [search, setSearch] = useState<string>('');\n\n  return (\n    <Stack direction=\"column\" gap=\"400\">\n      <TextInputField\n        type=\"email\"\n        label=\"Email\"\n        value={email}\n        onChange={setEmail}\n        placeholder=\"user@example.com\"\n      />\n      <TextInputField\n        type=\"password\"\n        label=\"Password\"\n        value={password}\n        onChange={setPassword}\n        placeholder=\"Enter your password\"\n      />\n      <TextInputField\n        type=\"search\"\n        label=\"Search\"\n        value={search}\n        onChange={setSearch}\n        placeholder=\"Search...\"\n      />\n    </Stack>\n  );\n}\n```\n\n### With leading and trailing elements\n\nAdd icons or other elements to the input using `leadingElement` and `trailingElement`:\n\n```jsx live-dev\nconst App = () => {\n  const [search, setSearch] = useState<string>('');\n  const [url, setUrl] = useState<string>('');\n\n  return (\n    <Stack direction=\"column\" gap=\"400\">\n      <TextInputField\n        label=\"Search\"\n        value={search}\n        onChange={setSearch}\n        placeholder=\"Search...\"\n        leadingElement={<Icons.Search />}\n      />\n      <TextInputField\n        label=\"Website URL\"\n        value={url}\n        onChange={setUrl}\n        placeholder=\"example.com\"\n        leadingElement={<Text fontSize=\"sm\" color=\"neutral.11\">https://</Text>}\n      />\n    </Stack>\n  );\n}\n```\n\n## Component requirements\n\n### Error handling\n\nTextInputField uses the `FieldErrors` component to display validation errors with built-in localized messages. For custom error messages, use the `renderError` prop (see [Custom error rendering](#custom-error-rendering) below).\n\n**Error object format** (`FieldErrorsData`):\n```tsx\ntype FieldErrorsData = {\n  [key: string]: boolean | string | ReactNode;\n};\n\n// Examples:\nconst errors = {\n  missing: true,              // Built-in message: \"This field is required\"\n  invalidFormat: true,        // Built-in message: \"Please enter a valid format\"\n  custom: \"Custom error text\" // Custom message\n};\n```\n\n## Accessibility\n\nTextInputField provides comprehensive accessibility through [FormField](components/inputs/formfield):\n\n**Automatic ARIA relationships:**\n- Labels connected via `aria-labelledby`\n- Descriptions connected via `aria-describedby`\n- Error messages connected via `aria-describedby`\n- Required fields indicated with `aria-required`\n- Invalid state indicated with `aria-invalid`\n\nIf your use case requires tracking and analytics for this component, add a **persistent**, **unique** id:\n\n```tsx\nconst PERSISTENT_ID = \"example-text-input\";\n\nexport const Example = () => (\n  <TextInputField\n    id={PERSISTENT_ID}\n    label=\"Username\"\n    value={value}\n    onChange={setValue}\n  />\n);\n```\n\n#### Keyboard navigation\n\nThe component supports standard text input keyboard interaction:\n- `Tab` / `Shift+Tab`: Move focus to/from the input\n- `Arrow keys`: Navigate within the text\n- `Home` / `End`: Move to start/end of text\n- `Ctrl+A` / `Cmd+A`: Select all text\n\n## Form integration\n\nTextInputField integrates seamlessly with Formik:\n\n```tsx\nimport { useFormik } from 'formik';\nimport { TextInputField, Button, Stack } from '@commercetools/nimbus';\n\nconst MyForm = () => {\n  const formik = useFormik({\n    initialValues: {\n      username: '',\n      email: '',\n    },\n    validate: (values) => {\n      const errors = {};\n\n      if (!values.username) {\n        errors.username = { missing: true };\n      } else if (values.username.length < 3) {\n        errors.username = { tooShort: true };\n      }\n\n      if (!values.email) {\n        errors.email = { missing: true };\n      } else if (!/^[^\\s@]+@[^\\s@]+\\.[^\\s@]+$/.test(values.email)) {\n        errors.email = { invalidFormat: true };\n      }\n\n      return errors;\n    },\n    onSubmit: (values) => {\n      console.log('Submitted:', values);\n    },\n  });\n\n  return (\n    <form onSubmit={formik.handleSubmit}>\n      <Stack direction=\"column\" gap=\"400\">\n        <TextInputField\n          name=\"username\"\n          label=\"Username\"\n          description=\"Choose a unique username\"\n          value={formik.values.username}\n          onChange={(value) => formik.setFieldValue('username', value)}\n          onBlur={() => formik.setFieldTouched('username', true)}\n          errors={formik.errors.username}\n          touched={formik.touched.username}\n          isRequired\n        />\n        <TextInputField\n          name=\"email\"\n          type=\"email\"\n          label=\"Email address\"\n          description=\"We'll use this to contact you\"\n          value={formik.values.email}\n          onChange={(value) => formik.setFieldValue('email', value)}\n          onBlur={() => formik.setFieldTouched('email', true)}\n          errors={formik.errors.email}\n          touched={formik.touched.email}\n          isRequired\n        />\n        <Button type=\"submit\">Submit</Button>\n      </Stack>\n    </form>\n  );\n};\n```\n\n**Key integration points:**\n- **Value/OnChange**: Connect Formik values with `value` and `setFieldValue`\n- **OnBlur**: Mark field as touched on blur\n- **Errors**: Pass `errors.fieldName` (supports `FieldErrorsData` format or strings)\n- **Touched**: Pass `touched.fieldName` to control error visibility\n\n## API reference\n\n<PropsTable id=\"TextInputField\" />\n\n### Custom error rendering\n\nUse the `renderError` prop to customize how specific error keys are displayed:\n\n```tsx\n<TextInputField\n  label=\"Email address\"\n  value={value}\n  onChange={setValue}\n  errors={{ invalidEmail: true, tooShort: true }}\n  touched={true}\n  renderError={(key) => {\n    switch (key) {\n      case 'invalidEmail':\n        return 'Please enter a valid email address (e.g., user@example.com)';\n      case 'tooShort':\n        return 'Email must be at least 5 characters long';\n      default:\n        return null; // Fall back to FieldErrors built-in messages\n    }\n  }}\n/>\n```\n\n## Testing your implementation\n\nThese examples demonstrate how to test your implementation when using TextInputField 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 elements:\n\n```tsx\nimport { render, screen } from '@testing-library/react';\nimport { TextInputField } from '@commercetools/nimbus';\n\ndescribe('TextInputField', () => {\n  it('renders label and input', () => {\n    render(\n      <TextInputField\n        label=\"Username\"\n        value=\"\"\n        onChange={() => {}}\n      />\n    );\n\n    // Verify label is rendered\n    expect(screen.getByText('Username')).toBeInTheDocument();\n\n    // Verify input is rendered\n    expect(screen.getByRole('textbox', { name: /username/i })).toBeInTheDocument();\n  });\n\n  it('renders description text', () => {\n    render(\n      <TextInputField\n        label=\"Email\"\n        description=\"Enter your email address\"\n        value=\"\"\n        onChange={() => {}}\n      />\n    );\n\n    expect(screen.getByText('Enter your email address')).toBeInTheDocument();\n  });\n\n  it('shows required indicator', () => {\n    render(\n      <TextInputField\n        label=\"Required field\"\n        value=\"\"\n        onChange={() => {}}\n        isRequired\n      />\n    );\n\n    // Check for required indicator (typically an asterisk or aria-required)\n    const input = screen.getByRole('textbox');\n    expect(input).toHaveAttribute('aria-required', 'true');\n  });\n});\n```\n\n### Interaction tests\n\nTest user interactions with the component:\n\n```tsx\nimport { render, screen, waitFor } from '@testing-library/react';\nimport userEvent from '@testing-library/user-event';\nimport { TextInputField } from '@commercetools/nimbus';\n\ndescribe('TextInputField interactions', () => {\n  it('calls onChange when user types', async () => {\n    const user = userEvent.setup();\n    const handleChange = jest.fn();\n\n    render(\n      <TextInputField\n        label=\"Username\"\n        value=\"\"\n        onChange={handleChange}\n      />\n    );\n\n    const input = screen.getByRole('textbox', { name: /username/i });\n    await user.type(input, 'johndoe');\n\n    expect(handleChange).toHaveBeenCalledTimes(7); // Once per character\n    expect(handleChange).toHaveBeenLastCalledWith('johndoe');\n  });\n\n  it('calls onBlur when input loses focus', async () => {\n    const user = userEvent.setup();\n    const handleBlur = jest.fn();\n\n    render(\n      <TextInputField\n        label=\"Email\"\n        value=\"\"\n        onChange={() => {}}\n        onBlur={handleBlur}\n      />\n    );\n\n    const input = screen.getByRole('textbox');\n    await user.click(input);\n    await user.tab(); // Move focus away\n\n    expect(handleBlur).toHaveBeenCalledTimes(1);\n  });\n\n  it('does not call onChange when disabled', async () => {\n    const user = userEvent.setup();\n    const handleChange = jest.fn();\n\n    render(\n      <TextInputField\n        label=\"Username\"\n        value=\"\"\n        onChange={handleChange}\n        isDisabled\n      />\n    );\n\n    const input = screen.getByRole('textbox');\n    expect(input).toBeDisabled();\n\n    // Attempt to type (should not work)\n    await user.type(input, 'test');\n    expect(handleChange).not.toHaveBeenCalled();\n  });\n});\n```\n\n### Testing validation and errors\n\nTest error handling and validation behavior:\n\n```tsx\nimport { render, screen } from '@testing-library/react';\nimport userEvent from '@testing-library/user-event';\nimport { TextInputField } from '@commercetools/nimbus';\n\ndescribe('TextInputField validation', () => {\n  it('does not show errors when untouched', () => {\n    render(\n      <TextInputField\n        label=\"Username\"\n        value=\"\"\n        onChange={() => {}}\n        errors={{ missing: true }}\n        touched={false}\n      />\n    );\n\n    // Error should not be visible\n    expect(screen.queryByText(/required/i)).not.toBeInTheDocument();\n  });\n\n  it('shows errors when touched', () => {\n    render(\n      <TextInputField\n        label=\"Username\"\n        value=\"\"\n        onChange={() => {}}\n        errors={{ missing: true }}\n        touched={true}\n      />\n    );\n\n    // Error should be visible\n    expect(screen.getByText(/required/i)).toBeInTheDocument();\n  });\n\n  it('shows custom error messages', () => {\n    render(\n      <TextInputField\n        label=\"Email\"\n        value=\"\"\n        onChange={() => {}}\n        errors={{ invalidFormat: true }}\n        touched={true}\n        renderError={(key) => {\n          if (key === 'invalidFormat') return 'Please enter a valid email';\n          return null;\n        }}\n      />\n    );\n\n    expect(screen.getByText('Please enter a valid email')).toBeInTheDocument();\n  });\n\n  it('applies invalid styling when isInvalid is true', () => {\n    render(\n      <TextInputField\n        label=\"Username\"\n        value=\"\"\n        onChange={() => {}}\n        isInvalid\n      />\n    );\n\n    const input = screen.getByRole('textbox');\n    expect(input).toHaveAttribute('aria-invalid', 'true');\n  });\n});\n```\n\n### Testing with different input types\n\nTest specific input type behavior:\n\n```tsx\nimport { render, screen } from '@testing-library/react';\nimport { TextInputField } from '@commercetools/nimbus';\n\ndescribe('TextInputField input types', () => {\n  it('renders email input type', () => {\n    render(\n      <TextInputField\n        type=\"email\"\n        label=\"Email\"\n        value=\"\"\n        onChange={() => {}}\n      />\n    );\n\n    const input = screen.getByRole('textbox');\n    expect(input).toHaveAttribute('type', 'email');\n  });\n\n  it('renders password input type', () => {\n    render(\n      <TextInputField\n        type=\"password\"\n        label=\"Password\"\n        value=\"\"\n        onChange={() => {}}\n      />\n    );\n\n    const input = screen.getByLabelText(/password/i);\n    expect(input).toHaveAttribute('type', 'password');\n  });\n\n  it('renders search input type', () => {\n    render(\n      <TextInputField\n        type=\"search\"\n        label=\"Search\"\n        value=\"\"\n        onChange={() => {}}\n      />\n    );\n\n    const input = screen.getByRole('searchbox');\n    expect(input).toHaveAttribute('type', 'search');\n  });\n});\n```\n\n## Resources\n\n- [Storybook](https://nimbus-storybook.vercel.app/?path=/docs/patterns-fields-textinputfield--docs)\n- [TextInput Component](/components/inputs/textinput)\n- [FormField Component](/components/inputs/formfield)\n- [FieldErrors Component](/components/forms/fielderrors)\n- [React Aria TextField](https://react-spectrum.adobe.com/react-aria/TextField.html)\n- [ARIA Textbox Pattern](https://www.w3.org/WAI/ARIA/apg/patterns/textbox/)\n",
+      "toc": [
+        {
+          "value": "Comparison: field pattern vs manual composition",
+          "href": "#comparison-field-pattern-vs-manual-composition",
+          "depth": 2,
+          "numbering": [
+            1,
+            1
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "When to use which",
+          "href": "#when-to-use-which",
+          "depth": 3,
+          "numbering": [
+            1,
+            1,
+            1
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Getting started",
+          "href": "#getting-started",
+          "depth": 2,
+          "numbering": [
+            1,
+            2
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Import",
+          "href": "#import",
+          "depth": 3,
+          "numbering": [
+            1,
+            2,
+            1
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Basic usage",
+          "href": "#basic-usage",
+          "depth": 3,
+          "numbering": [
+            1,
+            2,
+            2
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Usage examples",
+          "href": "#usage-examples",
+          "depth": 2,
+          "numbering": [
+            1,
+            3
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Size options",
+          "href": "#size-options",
+          "depth": 3,
+          "numbering": [
+            1,
+            3,
+            1
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Visual variants",
+          "href": "#visual-variants",
+          "depth": 3,
+          "numbering": [
+            1,
+            3,
+            2
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "With description",
+          "href": "#with-description",
+          "depth": 3,
+          "numbering": [
+            1,
+            3,
+            3
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "With validation errors",
+          "href": "#with-validation-errors",
+          "depth": 3,
+          "numbering": [
+            1,
+            3,
+            4
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "With info popover",
+          "href": "#with-info-popover",
+          "depth": 3,
+          "numbering": [
+            1,
+            3,
+            5
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Required field",
+          "href": "#required-field",
+          "depth": 3,
+          "numbering": [
+            1,
+            3,
+            6
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Disabled state",
+          "href": "#disabled-state",
+          "depth": 3,
+          "numbering": [
+            1,
+            3,
+            7
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Read-only state",
+          "href": "#read-only-state",
+          "depth": 3,
+          "numbering": [
+            1,
+            3,
+            8
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Different input types",
+          "href": "#different-input-types",
+          "depth": 3,
+          "numbering": [
+            1,
+            3,
+            9
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "With leading and trailing elements",
+          "href": "#with-leading-and-trailing-elements",
+          "depth": 3,
+          "numbering": [
+            1,
+            3,
+            10
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Component requirements",
+          "href": "#component-requirements",
+          "depth": 2,
+          "numbering": [
+            1,
+            4
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Error handling",
+          "href": "#error-handling",
+          "depth": 3,
+          "numbering": [
+            1,
+            4,
+            1
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Accessibility",
+          "href": "#accessibility",
+          "depth": 2,
+          "numbering": [
+            1,
+            5
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Keyboard navigation",
+          "href": "#keyboard-navigation",
+          "depth": 4,
+          "numbering": [
+            1,
+            5,
+            1,
+            1
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Form integration",
+          "href": "#form-integration",
+          "depth": 2,
+          "numbering": [
+            1,
+            6
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "API reference",
+          "href": "#api-reference",
+          "depth": 2,
+          "numbering": [
+            1,
+            7
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Custom error rendering",
+          "href": "#custom-error-rendering",
+          "depth": 3,
+          "numbering": [
+            1,
+            7,
+            1
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Testing your implementation",
+          "href": "#testing-your-implementation",
+          "depth": 2,
+          "numbering": [
+            1,
+            8
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Basic rendering tests",
+          "href": "#basic-rendering-tests",
+          "depth": 3,
+          "numbering": [
+            1,
+            8,
+            1
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Interaction tests",
+          "href": "#interaction-tests",
+          "depth": 3,
+          "numbering": [
+            1,
+            8,
+            2
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Testing validation and errors",
+          "href": "#testing-validation-and-errors",
+          "depth": 3,
+          "numbering": [
+            1,
+            8,
+            3
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Testing with different input types",
+          "href": "#testing-with-different-input-types",
+          "depth": 3,
+          "numbering": [
+            1,
+            8,
+            4
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Resources",
+          "href": "#resources",
+          "depth": 2,
+          "numbering": [
+            1,
+            9
+          ],
+          "parent": "root"
+        }
+      ]
+    }
+  }
+}

package/data/docs/routes/patterns-fields.json

@@ -0,0 +1,78 @@
+{
+  "meta": {
+    "id": "Patterns-Fields",
+    "title": "Fields",
+    "description": "Field pattern components that integrate inputs within FormField for consistent form layouts",
+    "order": 1,
+    "repoPath": "packages/nimbus/src/docs/fields.mdx",
+    "menu": [
+      "Patterns",
+      "Fields"
+    ],
+    "route": "patterns/fields",
+    "tags": [
+      "patterns",
+      "fields",
+      "forms"
+    ],
+    "toc": [
+      {
+        "value": "When to use field patterns",
+        "href": "#when-to-use-field-patterns",
+        "depth": 2,
+        "numbering": [
+          1,
+          1
+        ],
+        "parent": "root"
+      },
+      {
+        "value": "Available field patterns",
+        "href": "#available-field-patterns",
+        "depth": 2,
+        "numbering": [
+          1,
+          2
+        ],
+        "parent": "root"
+      }
+    ],
+    "icon": "Input",
+    "layout": "app-frame",
+    "tabs": [
+      {
+        "key": "overview",
+        "title": "Overview",
+        "order": 0
+      }
+    ]
+  },
+  "mdx": "\n# Fields\n\nField pattern components provide a consistent way to integrate input components within FormField wrappers. These patterns simplify form building by combining labels, descriptions, validation, and error handling into a single, opinionated API.\n\n## When to use field patterns\n\nField patterns are ideal for:\n- Building standard forms with consistent field layouts\n- Reducing boilerplate in form code\n- Ensuring accessibility best practices across all form fields\n- Integrating with form libraries like Formik\n\n## Available field patterns\n\n<CategoryOverview variant=\"list\" />\n",
+  "views": {
+    "overview": {
+      "mdx": "\n# Fields\n\nField pattern components provide a consistent way to integrate input components within FormField wrappers. These patterns simplify form building by combining labels, descriptions, validation, and error handling into a single, opinionated API.\n\n## When to use field patterns\n\nField patterns are ideal for:\n- Building standard forms with consistent field layouts\n- Reducing boilerplate in form code\n- Ensuring accessibility best practices across all form fields\n- Integrating with form libraries like Formik\n\n## Available field patterns\n\n<CategoryOverview variant=\"list\" />\n",
+      "toc": [
+        {
+          "value": "When to use field patterns",
+          "href": "#when-to-use-field-patterns",
+          "depth": 2,
+          "numbering": [
+            1,
+            1
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Available field patterns",
+          "href": "#available-field-patterns",
+          "depth": 2,
+          "numbering": [
+            1,
+            2
+          ],
+          "parent": "root"
+        }
+      ]
+    }
+  }
+}

package/data/docs/routes/patterns.json

@@ -0,0 +1,34 @@
+{
+  "meta": {
+    "id": "Patterns",
+    "title": "Patterns",
+    "description": "Reusable component patterns and compositions for common use cases",
+    "order": 4,
+    "repoPath": "packages/nimbus/src/docs/patterns.mdx",
+    "menu": [
+      "Patterns"
+    ],
+    "route": "patterns",
+    "tags": [
+      "patterns",
+      "compositions",
+      "recipes"
+    ],
+    "toc": [],
+    "layout": "app-frame",
+    "tabs": [
+      {
+        "key": "overview",
+        "title": "Overview",
+        "order": 0
+      }
+    ]
+  },
+  "mdx": "\n# Patterns\n\nA collection of reusable component patterns and compositions that combine multiple components to solve common UI challenges.\n\n<CategoryOverview variant=\"list\" />\n",
+  "views": {
+    "overview": {
+      "mdx": "\n# Patterns\n\nA collection of reusable component patterns and compositions that combine multiple components to solve common UI challenges.\n\n<CategoryOverview variant=\"list\" />\n",
+      "toc": []
+    }
+  }
+}