@commercetools/nimbus-mcp 0.1.0 → 2.11.0

package/data/docs/routes/components-inputs-multiline-text-input.json

@@ -0,0 +1,611 @@
+{
+  "meta": {
+    "id": "Components-MultilineTextInput",
+    "title": "Multiline text input",
+    "exportName": "MultilineTextInput",
+    "description": "A multi-line text input allows users to enter longer blocks of text across multiple lines. It is suitable for paragraphs, descriptions, or any input requiring more than a single line.",
+    "lifecycleState": "Stable",
+    "order": 999,
+    "repoPath": "packages/nimbus/src/components/multiline-text-input/multiline-text-input.mdx",
+    "menu": [
+      "Components",
+      "Inputs",
+      "Multiline text input"
+    ],
+    "route": "components/inputs/multiline-text-input",
+    "tags": [
+      "component",
+      "form"
+    ],
+    "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 options",
+        "href": "#visual-options",
+        "depth": 3,
+        "numbering": [
+          1,
+          2,
+          1
+        ],
+        "parent": "root"
+      },
+      {
+        "value": "Sizes",
+        "href": "#sizes",
+        "depth": 4,
+        "numbering": [
+          1,
+          2,
+          1,
+          1
+        ],
+        "parent": "root"
+      },
+      {
+        "value": "Resizability",
+        "href": "#resizability",
+        "depth": 4,
+        "numbering": [
+          1,
+          2,
+          1,
+          2
+        ],
+        "parent": "root"
+      },
+      {
+        "value": "Minimum and maximum row allowance",
+        "href": "#minimum-and-maximum-row-allowance",
+        "depth": 3,
+        "numbering": [
+          1,
+          2,
+          2
+        ],
+        "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\nA multi-line text input allows users to enter multiple lines of text. It expands\nvertically to accommodate more content.\n\n### Resources\n\nDeep dive into implementation details and access the Nimbus design library.\n\n[Figma Library](https://www.figma.com/design/gHbAJGfcrCv7f2bgzUQgHq/NIMBUS-Guidelines?node-id=2602-6001&m=dev)\n\n## Variables\n\nGet familiar with the features.\n\n### Visual options\n\nThis component supports different sizes, medium (default) and small (for compact\nuses).\n\n#### Sizes\n\n```jsx live\nconst App = () => (\n <Stack direction=\"row\" gap=\"400\" alignItems=\"flex-start\">\n    <MultilineTextInput\n        size=\"md\"\n        placeholder=\"Medium textarea\"\n        aria-label=\"Medium input\"\n        value=\"I am a medium size, and used as a default.\"\n    />\n    <MultilineTextInput\n        size=\"sm\"\n        placeholder=\"Small textarea\"\n        aria-label=\"Small input\"\n        value=\"This is the small size for compact uses.\"\n    />\n </Stack>\n );\n```\n\n#### Resizability\n\nUsers can resize the input vertically using a handle, and it can grow with the\ncontent added.\n\n```jsx live\nconst App = () => (\n <Stack direction=\"row\" gap=\"400\" alignItems=\"flex-start\">\n    <MultilineTextInput\n        size=\"md\"\n        placeholder=\"Medium textarea\"\n        aria-label=\"Medium input\"\n        value=\"Resize me by dragging the icon in the lower right corner. I can only move up and down to adjust the height of this element.\"\n    />\n    <MultilineTextInput\n        size=\"md\"\n        placeholder=\"Medium textarea less content\"\n        aria-label=\"Medium input\"\n        value=\"Add more text and I will grow to contain it. Additionally, you can set a max height.\"\n    />\n </Stack>\n );\n```\n\n### Minimum and maximum row allowance\n\nA min. rows property sets the initial minimum visible height (e.g., 2 rows). A\nmax. rows property sets the maximum visible height before the content becomes\nscrollable (e.g., 5 rows).\n\n```jsx live\nconst App = () => (\n  <MultilineTextInput\n        size=\"md\"\n        placeholder=\"placeholder with min row\"\n        aria-label=\"Medium input\"\n        value=\"Lorem ipsum dolor sit amet, consectetur adipiscing elit\"\n        rows={5}\n    />\n);\n```\n",
+  "views": {
+    "overview": {
+      "mdx": "\n## Overview\n\nA multi-line text input allows users to enter multiple lines of text. It expands\nvertically to accommodate more content.\n\n### Resources\n\nDeep dive into implementation details and access the Nimbus design library.\n\n[Figma Library](https://www.figma.com/design/gHbAJGfcrCv7f2bgzUQgHq/NIMBUS-Guidelines?node-id=2602-6001&m=dev)\n\n## Variables\n\nGet familiar with the features.\n\n### Visual options\n\nThis component supports different sizes, medium (default) and small (for compact\nuses).\n\n#### Sizes\n\n```jsx live\nconst App = () => (\n <Stack direction=\"row\" gap=\"400\" alignItems=\"flex-start\">\n    <MultilineTextInput\n        size=\"md\"\n        placeholder=\"Medium textarea\"\n        aria-label=\"Medium input\"\n        value=\"I am a medium size, and used as a default.\"\n    />\n    <MultilineTextInput\n        size=\"sm\"\n        placeholder=\"Small textarea\"\n        aria-label=\"Small input\"\n        value=\"This is the small size for compact uses.\"\n    />\n </Stack>\n );\n```\n\n#### Resizability\n\nUsers can resize the input vertically using a handle, and it can grow with the\ncontent added.\n\n```jsx live\nconst App = () => (\n <Stack direction=\"row\" gap=\"400\" alignItems=\"flex-start\">\n    <MultilineTextInput\n        size=\"md\"\n        placeholder=\"Medium textarea\"\n        aria-label=\"Medium input\"\n        value=\"Resize me by dragging the icon in the lower right corner. I can only move up and down to adjust the height of this element.\"\n    />\n    <MultilineTextInput\n        size=\"md\"\n        placeholder=\"Medium textarea less content\"\n        aria-label=\"Medium input\"\n        value=\"Add more text and I will grow to contain it. Additionally, you can set a max height.\"\n    />\n </Stack>\n );\n```\n\n### Minimum and maximum row allowance\n\nA min. rows property sets the initial minimum visible height (e.g., 2 rows). A\nmax. rows property sets the maximum visible height before the content becomes\nscrollable (e.g., 5 rows).\n\n```jsx live\nconst App = () => (\n  <MultilineTextInput\n        size=\"md\"\n        placeholder=\"placeholder with min row\"\n        aria-label=\"Medium input\"\n        value=\"Lorem ipsum dolor sit amet, consectetur adipiscing elit\"\n        rows={5}\n    />\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 options",
+          "href": "#visual-options",
+          "depth": 3,
+          "numbering": [
+            1,
+            2,
+            1
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Sizes",
+          "href": "#sizes",
+          "depth": 4,
+          "numbering": [
+            1,
+            2,
+            1,
+            1
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Resizability",
+          "href": "#resizability",
+          "depth": 4,
+          "numbering": [
+            1,
+            2,
+            1,
+            2
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Minimum and maximum row allowance",
+          "href": "#minimum-and-maximum-row-allowance",
+          "depth": 3,
+          "numbering": [
+            1,
+            2,
+            2
+          ],
+          "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  <MultilineTextInput\n        size=\"md\"\n        placeholder=\"well described placeholder\"\n        aria-label=\"lorem ipsum text\"\n        value=\"Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat.\"\n        rows={5}\n    />\n)\n```\n\n### Accessibility standards\n\n- Always provide a visible label for the input.\n- If a visible label is not used, provide an aria-label or aria-labelledby for\n  screen readers.\n- Ensure sufficient color contrast for all elements (text, borders).\n- Communicate errors clearly, using both visual cues (e.g., color) and\n  descriptive error messages.\n- Clearly indicate the focused state.\n\n### Resources\n\n- [Adobe Spectrum TextArea](https://www.google.com/search?q=https://spectrum.adobe.com/components/textarea/)\n- [React Spectrum TextArea](https://react-spectrum.adobe.com/react-spectrum/TextArea.html)\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"
+        },
+        {
+          "value": "Resources",
+          "href": "#resources",
+          "depth": 3,
+          "numbering": [
+            1,
+            1,
+            2
+          ],
+          "parent": "root"
+        }
+      ]
+    },
+    "dev": {
+      "mdx": "\n## Getting started\n\n### Import\n\n```tsx\nimport { MultilineTextInput, type MultilineTextInputProps } from '@commercetools/nimbus';\n```\n\n### Basic usage\n\nThe simplest implementation uses uncontrolled mode:\n\n```jsx live-dev\nconst App = () => (\n  <MultilineTextInput placeholder=\"Enter your message\" />\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  <Stack direction=\"column\" gap=\"400\">\n    <MultilineTextInput size=\"sm\" placeholder=\"Small textarea\" />\n    <MultilineTextInput size=\"md\" placeholder=\"Medium textarea (default)\" />\n  </Stack>\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  <Stack direction=\"column\" gap=\"400\">\n    <MultilineTextInput variant=\"solid\" placeholder=\"Solid variant (default)\" />\n    <MultilineTextInput variant=\"ghost\" placeholder=\"Ghost variant\" />\n  </Stack>\n)\n```\n\n### Leading elements\n\nAdd icons, buttons, or other elements at the start of the textarea using the `leadingElement` prop:\n\n```jsx live-dev\nconst App = () => (\n  <Stack direction=\"column\" gap=\"400\">\n    <MultilineTextInput\n      placeholder=\"Add a comment...\"\n      leadingElement={<Icons.Comment />}\n    />\n    <MultilineTextInput\n      placeholder=\"Describe the issue...\"\n      leadingElement={<Icons.ReportProblem />}\n    />\n  </Stack>\n)\n```\n\n**Behavioral notes:**\n- Elements automatically respect text direction (LTR/RTL)\n- Leading element appears at the start (left in LTR, right in RTL)\n- Icon sizing automatically adjusts based on the `size` prop\n\n### Rows configuration\n\nControl the visible number of text rows using the `rows` prop:\n\n```jsx live-dev\nconst App = () => (\n  <Stack direction=\"column\" gap=\"400\">\n    <Text fontSize=\"sm\" color=\"neutral.11\">Default (1 row):</Text>\n    <MultilineTextInput\n      placeholder=\"Single row textarea\"\n    />\n\n    <Text fontSize=\"sm\" color=\"neutral.11\">3 rows:</Text>\n    <MultilineTextInput\n      rows={3}\n      placeholder=\"Three rows textarea\"\n    />\n\n    <Text fontSize=\"sm\" color=\"neutral.11\">6 rows:</Text>\n    <MultilineTextInput\n      rows={6}\n      placeholder=\"Six rows textarea\"\n    />\n  </Stack>\n)\n```\n\n**Behavioral notes:**\n- Default is 1 row if not specified\n- Users can manually resize vertically using the resize handle\n- Larger `rows` values provide more visible space for longer content\n\n### Auto-grow functionality\n\nEnable automatic height adjustment based on content using the `autoGrow` prop:\n\n```jsx live-dev\nconst App = () => (\n  <Stack direction=\"column\" gap=\"400\">\n    <Text fontSize=\"sm\" color=\"neutral.11\">\n      Auto-grow enabled - type multiple lines to see it expand:\n    </Text>\n    <MultilineTextInput\n      autoGrow\n      placeholder=\"Start typing... This textarea will grow automatically!\"\n    />\n\n    <Text fontSize=\"sm\" color=\"neutral.11\">\n      Auto-grow with max height constraint:\n    </Text>\n    <MultilineTextInput\n      autoGrow\n      maxHeight=\"3200\"\n      placeholder=\"Grows up to max height, then scrolls\"\n    />\n  </Stack>\n)\n```\n\n**Behavioral notes:**\n- Textarea automatically expands as you type more lines\n- Automatically shrinks when you delete content\n- Manual resize handle remains available with auto-grow\n- Use `maxHeight` to limit expansion and enable scrolling beyond that point\n- Use `minH` and `maxH` style props for height constraints\n\n### Disabled state\n\nDisable textarea interaction with the `isDisabled` prop:\n\n```jsx live-dev\nconst App = () => (\n  <Stack direction=\"column\" gap=\"400\">\n    <MultilineTextInput placeholder=\"Enabled textarea\" />\n    <MultilineTextInput placeholder=\"Disabled textarea\" isDisabled />\n    <MultilineTextInput\n      value=\"Disabled with content\"\n      isDisabled\n      onChange={() => {}}\n    />\n  </Stack>\n)\n```\n\n### Invalid state\n\nMark textareas as invalid for validation feedback:\n\n```jsx live-dev\nconst App = () => (\n  <Stack direction=\"column\" gap=\"400\">\n    <MultilineTextInput\n      placeholder=\"Valid textarea\"\n      value=\"This message meets requirements\"\n      onChange={() => {}}\n    />\n    <MultilineTextInput\n      placeholder=\"Invalid textarea\"\n      value=\"Too short\"\n      isInvalid\n      onChange={() => {}}\n    />\n  </Stack>\n)\n```\n\n### Read-only state\n\nUse `isReadOnly` to display content without allowing editing:\n\n```jsx live-dev\nconst App = () => (\n  <Stack direction=\"column\" gap=\"400\">\n    <MultilineTextInput\n      value=\"This content is editable\"\n      onChange={() => {}}\n    />\n    <MultilineTextInput\n      value=\"This content is read-only and cannot be modified\"\n      isReadOnly\n      onChange={() => {}}\n    />\n  </Stack>\n)\n```\n\n### Uncontrolled mode\n\nFor simpler use cases, use uncontrolled mode with `defaultValue` and `onChange`:\n\n```jsx live-dev\nconst App = () => {\n  const [displayValue, setDisplayValue] = useState<string>('');\n\n  return (\n    <Stack direction=\"column\" gap=\"400\">\n      <MultilineTextInput\n        placeholder=\"Type something...\"\n        defaultValue=\"\"\n        onChange={(value) => {\n          setDisplayValue(value);\n        }}\n      />\n      <Text fontSize=\"sm\">Current value: {displayValue || '(empty)'}</Text>\n    </Stack>\n  );\n}\n```\n\nUse uncontrolled mode when you need to capture the textarea value without managing state yourself.\n\n**Note:** MultilineTextInput's `onChange` receives the string value directly, not an event object.\n\n### Controlled mode\n\nFor scenarios requiring programmatic control or coordination with other components, use controlled mode:\n\n```jsx live-dev\nconst App = () => {\n  const [value, setValue] = useState<MultilineTextInputProps[\"value\"]>('');\n\n  return (\n    <Stack direction=\"column\" gap=\"400\">\n      <MultilineTextInput\n        value={value}\n        onChange={setValue}\n        placeholder=\"Type your message...\"\n        rows={3}\n      />\n      <Text fontSize=\"sm\">\n        {value ? `Character count: ${value.length}` : 'Start typing...'}\n      </Text>\n      <Button onClick={() => setValue('')} size=\"xs\">\n        Clear\n      </Button>\n    </Stack>\n  );\n}\n```\n\nUse controlled mode when you need to:\n- Synchronize the value with external state\n- Validate or transform input values\n- Clear or programmatically set the value\n- React to changes in real-time (e.g., character counting)\n\n## Component requirements\n\n## Accessibility\n\nThe MultilineTextInput handles most accessibility requirements internally. However, you must always associate an internationalized label with the component. Visual labels are preferable, and can be set by:\n\n- Using the `MultilineTextInputField` pattern component (recommended)\n- Associating a `<label>` element with the `MultilineTextInput` using `aria-labelledby`:\n\n```tsx\n<label id=\"description-label\">\n  {msg.format(descriptionMessage)}\n</label>\n<MultilineTextInput aria-labelledby=\"description-label\" />\n```\n\n- Associating a `<label>` element with the `MultilineTextInput` using `htmlFor`:\n\n```tsx\n<label htmlFor=\"description-textarea\">\n  {msg.format(descriptionMessage)}\n</label>\n<MultilineTextInput id=\"description-textarea\" />\n```\n\nIf your design requires that the label should not be visible, the label should be set using the `aria-label` prop:\n\n```tsx\n<MultilineTextInput aria-label={msg.format(descriptionMessage)} />\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 = \"product-description-textarea\";\n\nexport const DescriptionField = () => (\n  <MultilineTextInput id={PERSISTENT_ID} placeholder=\"Description\" />\n);\n```\n\n#### Keyboard navigation\n\nThe component supports full keyboard interaction:\n- `Tab` / `Shift+Tab`: Navigate to/from the textarea field\n- `Arrow keys`: Move cursor within the text (all directions for multi-line navigation)\n- `Home` / `End`: Move cursor to start/end of current line\n- `Ctrl+Home` / `Ctrl+End`: Move cursor to start/end of entire text\n- `Ctrl+A` / `Cmd+A`: Select all text\n- `Enter`: Insert new line\n- Standard text editing shortcuts: Cut, Copy, Paste, Undo, Redo\n\n#### Click-to-focus behavior\n\nClicking anywhere within the textarea container (including leading element area) will focus the textarea field, providing a larger interactive target for better usability.\n\n## API reference\n\n<PropsTable id=\"MultilineTextInput\" />\n\n## Common patterns\n\n### Comment input with character limit\n\nTrack character count and enforce limits for user-generated content:\n\n```jsx live-dev\nconst App = () => {\n  const [comment, setComment] = useState<string>('');\n  const maxLength = 280;\n  const remaining = maxLength - comment.length;\n  const isOverLimit = remaining < 0;\n\n  return (\n    <Stack direction=\"column\" gap=\"400\">\n      <MultilineTextInput\n        value={comment}\n        onChange={setComment}\n        placeholder=\"Share your thoughts...\"\n        rows={4}\n        isInvalid={isOverLimit}\n        leadingElement={<Icons.Comment />}\n      />\n      <Stack direction=\"row\" justifyContent=\"space-between\">\n        <Text fontSize=\"sm\" color={isOverLimit ? 'critical.11' : 'neutral.11'}>\n          {remaining} characters remaining\n        </Text>\n        <Button\n          size=\"xs\"\n          isDisabled={comment.length === 0 || isOverLimit}\n        >\n          Post Comment\n        </Button>\n      </Stack>\n    </Stack>\n  );\n}\n```\n\n### Auto-growing feedback form\n\nCreate responsive form fields that adapt to content length:\n\n```jsx live-dev\nconst App = () => {\n  const [feedback, setFeedback] = useState<string>('');\n  const wordCount = feedback.trim().split(/\\s+/).filter(Boolean).length;\n\n  return (\n    <Stack direction=\"column\" gap=\"400\">\n      <Text fontWeight=\"semibold\">Share Your Feedback</Text>\n      <MultilineTextInput\n        autoGrow\n        value={feedback}\n        onChange={setFeedback}\n        placeholder=\"Tell us about your experience...\"\n        minH=\"1600\"\n        maxH=\"4800\"\n        leadingElement={<Icons.Feedback />}\n      />\n      <Stack direction=\"row\" justifyContent=\"space-between\" alignItems=\"center\">\n        <Text fontSize=\"sm\" color=\"neutral.11\">\n          {wordCount} {wordCount === 1 ? 'word' : 'words'}\n        </Text>\n        <Button size=\"xs\" isDisabled={wordCount < 10}>\n          Submit Feedback\n        </Button>\n      </Stack>\n    </Stack>\n  );\n}\n```\n\n### Multi-field form with validation\n\nCombine multiple textareas in a form with validation states:\n\n```jsx live-dev\nconst App = () => {\n  const [title, setTitle] = useState<string>('');\n  const [description, setDescription] = useState<string>('');\n  const [touched, setTouched] = useState({ title: false, description: false });\n\n  const titleError = touched.title && title.length < 5;\n  const descError = touched.description && description.length < 20;\n\n  return (\n    <Stack direction=\"column\" gap=\"600\">\n      <Stack direction=\"column\" gap=\"300\">\n        <Text fontWeight=\"semibold\">Title *</Text>\n        <MultilineTextInput\n          value={title}\n          onChange={setTitle}\n          onBlur={() => setTouched(prev => ({ ...prev, title: true }))}\n          placeholder=\"Brief summary (minimum 5 characters)\"\n          rows={1}\n          isInvalid={titleError}\n          isRequired\n        />\n        {titleError && (\n          <Text fontSize=\"sm\" color=\"critical.11\">\n            Title must be at least 5 characters\n          </Text>\n        )}\n      </Stack>\n\n      <Stack direction=\"column\" gap=\"300\">\n        <Text fontWeight=\"semibold\">Description *</Text>\n        <MultilineTextInput\n          autoGrow\n          value={description}\n          onChange={setDescription}\n          onBlur={() => setTouched(prev => ({ ...prev, description: true }))}\n          placeholder=\"Detailed explanation (minimum 20 characters)\"\n          minH=\"2400\"\n          maxH=\"4800\"\n          isInvalid={descError}\n          isRequired\n        />\n        {descError && (\n          <Text fontSize=\"sm\" color=\"critical.11\">\n            Description must be at least 20 characters\n          </Text>\n        )}\n      </Stack>\n\n      <Button\n        isDisabled={!title || !description || titleError || descError}\n      >\n        Submit\n      </Button>\n    </Stack>\n  );\n}\n```\n\n## Testing your implementation\n\nThese examples demonstrate how to test your implementation when using MultilineTextInput 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 { describe, it, expect, vi } from \"vitest\";\nimport { render, screen } from \"@testing-library/react\";\nimport userEvent from \"@testing-library/user-event\";\nimport { MultilineTextInput, NimbusProvider } from \"@commercetools/nimbus\";\nimport { useState } from \"react\";\n\ndescribe(\"MultilineTextInput - Basic rendering\", () => {\n  it(\"renders textarea element\", () => {\n    render(\n      <NimbusProvider>\n        <MultilineTextInput aria-label=\"Description\" />\n      </NimbusProvider>\n    );\n\n    const textarea = screen.getByRole(\"textbox\", { name: /description/i });\n    expect(textarea).toBeInTheDocument();\n    expect(textarea.tagName).toBe(\"TEXTAREA\");\n  });\n\n  it(\"renders with placeholder text\", () => {\n    render(\n      <NimbusProvider>\n        <MultilineTextInput\n          placeholder=\"Enter your message\"\n          aria-label=\"Message\"\n        />\n      </NimbusProvider>\n    );\n\n    expect(\n      screen.getByPlaceholderText(/enter your message/i)\n    ).toBeInTheDocument();\n  });\n\n  it(\"renders with specified number of rows\", () => {\n    render(\n      <NimbusProvider>\n        <MultilineTextInput rows={5} aria-label=\"Description\" />\n      </NimbusProvider>\n    );\n\n    const textarea = screen.getByRole(\"textbox\");\n    expect(textarea).toHaveAttribute(\"rows\", \"5\");\n  });\n});\n```\n\n### Interaction Tests\n\nTest user interactions with the textarea\n\n```tsx\nimport { describe, it, expect, vi } from \"vitest\";\nimport { render, screen } from \"@testing-library/react\";\nimport userEvent from \"@testing-library/user-event\";\nimport { MultilineTextInput, NimbusProvider } from \"@commercetools/nimbus\";\nimport { useState } from \"react\";\n\ndescribe(\"MultilineTextInput - Interactions\", () => {\n  it(\"handles typing multi-line text\", async () => {\n    const user = userEvent.setup();\n    render(\n      <NimbusProvider>\n        <MultilineTextInput aria-label=\"Message\" />\n      </NimbusProvider>\n    );\n\n    const textarea = screen.getByRole(\"textbox\");\n    await user.type(textarea, \"First line{Enter}Second line\");\n\n    expect(textarea).toHaveValue(\"First line\\nSecond line\");\n  });\n\n  it(\"calls onChange with typed value\", async () => {\n    const user = userEvent.setup();\n    const handleChange = vi.fn();\n    render(\n      <NimbusProvider>\n        <MultilineTextInput onChange={handleChange} aria-label=\"Message\" />\n      </NimbusProvider>\n    );\n\n    const textarea = screen.getByRole(\"textbox\");\n    await user.type(textarea, \"Hello\");\n\n    expect(handleChange).toHaveBeenCalledWith(\"Hello\");\n  });\n\n  it(\"handles controlled mode updates\", async () => {\n    const { rerender } = render(\n      <NimbusProvider>\n        <MultilineTextInput\n          value=\"Initial\"\n          onChange={() => {}}\n          aria-label=\"Message\"\n        />\n      </NimbusProvider>\n    );\n\n    const textarea = screen.getByRole(\"textbox\");\n    expect(textarea).toHaveValue(\"Initial\");\n\n    rerender(\n      <NimbusProvider>\n        <MultilineTextInput\n          value=\"Updated\"\n          onChange={() => {}}\n          aria-label=\"Message\"\n        />\n      </NimbusProvider>\n    );\n\n    expect(textarea).toHaveValue(\"Updated\");\n  });\n});\n```\n\n### Testing States\n\nVerify different component states render correctly\n\n```tsx\nimport { describe, it, expect, vi } from \"vitest\";\nimport { render, screen } from \"@testing-library/react\";\nimport userEvent from \"@testing-library/user-event\";\nimport { MultilineTextInput, NimbusProvider } from \"@commercetools/nimbus\";\nimport { useState } from \"react\";\n\ndescribe(\"MultilineTextInput - States\", () => {\n  it(\"handles disabled state\", async () => {\n    const user = userEvent.setup();\n    render(\n      <NimbusProvider>\n        <MultilineTextInput isDisabled aria-label=\"Message\" />\n      </NimbusProvider>\n    );\n\n    const textarea = screen.getByRole(\"textbox\");\n    expect(textarea).toBeDisabled();\n\n    // Verify cannot type when disabled\n    await user.type(textarea, \"Test\");\n    expect(textarea).toHaveValue(\"\");\n  });\n\n  it(\"handles invalid state\", () => {\n    render(\n      <NimbusProvider>\n        <MultilineTextInput isInvalid aria-label=\"Message\" />\n      </NimbusProvider>\n    );\n\n    const textarea = screen.getByRole(\"textbox\");\n    expect(textarea).toHaveAttribute(\"data-invalid\", \"true\");\n  });\n\n  it(\"handles required state\", () => {\n    render(\n      <NimbusProvider>\n        <MultilineTextInput isRequired aria-label=\"Message\" />\n      </NimbusProvider>\n    );\n\n    const textarea = screen.getByRole(\"textbox\");\n    expect(textarea).toHaveAttribute(\"aria-required\", \"true\");\n  });\n\n  it(\"handles read-only state\", () => {\n    render(\n      <NimbusProvider>\n        <MultilineTextInput\n          isReadOnly\n          value=\"Read-only content\"\n          onChange={() => {}}\n          aria-label=\"Message\"\n        />\n      </NimbusProvider>\n    );\n\n    const textarea = screen.getByRole(\"textbox\");\n    expect(textarea).toHaveAttribute(\"readonly\");\n  });\n});\n```\n\n### Testing with Character Limits\n\nTest application logic for character counting and validation\n\n```tsx\nimport { describe, it, expect, vi } from \"vitest\";\nimport { render, screen } from \"@testing-library/react\";\nimport userEvent from \"@testing-library/user-event\";\nimport { MultilineTextInput, NimbusProvider } from \"@commercetools/nimbus\";\nimport { useState } from \"react\";\n\ndescribe(\"MultilineTextInput - Character limit\", () => {\n  it(\"enforces character limit validation\", async () => {\n    const user = userEvent.setup();\n    const maxLength = 50;\n\n    const TestComponent = () => {\n      const [value, setValue] = useState(\"\");\n      const isOverLimit = value.length > maxLength;\n\n      return (\n        <>\n          <MultilineTextInput\n            value={value}\n            onChange={setValue}\n            isInvalid={isOverLimit}\n            aria-label=\"Comment\"\n          />\n          <div data-testid=\"char-count\">\n            {value.length}/{maxLength}\n          </div>\n        </>\n      );\n    };\n\n    render(\n      <NimbusProvider>\n        <TestComponent />\n      </NimbusProvider>\n    );\n\n    const textarea = screen.getByRole(\"textbox\");\n    const longText = \"a\".repeat(60); // Exceeds limit\n\n    await user.type(textarea, longText);\n\n    expect(textarea).toHaveAttribute(\"data-invalid\", \"true\");\n    expect(screen.getByTestId(\"char-count\")).toHaveTextContent(\"60/50\");\n  });\n});\n```\n\n\n## Resources\n\n- [Storybook](https://nimbus-storybook.vercel.app/?path=/docs/components-multilinetextinput--docs)\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": "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": "Size options",
+          "href": "#size-options",
+          "depth": 3,
+          "numbering": [
+            1,
+            2,
+            1
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Visual variants",
+          "href": "#visual-variants",
+          "depth": 3,
+          "numbering": [
+            1,
+            2,
+            2
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Leading elements",
+          "href": "#leading-elements",
+          "depth": 3,
+          "numbering": [
+            1,
+            2,
+            3
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Rows configuration",
+          "href": "#rows-configuration",
+          "depth": 3,
+          "numbering": [
+            1,
+            2,
+            4
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Auto-grow functionality",
+          "href": "#auto-grow-functionality",
+          "depth": 3,
+          "numbering": [
+            1,
+            2,
+            5
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Disabled state",
+          "href": "#disabled-state",
+          "depth": 3,
+          "numbering": [
+            1,
+            2,
+            6
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Invalid state",
+          "href": "#invalid-state",
+          "depth": 3,
+          "numbering": [
+            1,
+            2,
+            7
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Read-only state",
+          "href": "#read-only-state",
+          "depth": 3,
+          "numbering": [
+            1,
+            2,
+            8
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Uncontrolled mode",
+          "href": "#uncontrolled-mode",
+          "depth": 3,
+          "numbering": [
+            1,
+            2,
+            9
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Controlled mode",
+          "href": "#controlled-mode",
+          "depth": 3,
+          "numbering": [
+            1,
+            2,
+            10
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Component requirements",
+          "href": "#component-requirements",
+          "depth": 2,
+          "numbering": [
+            1,
+            3
+          ],
+          "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": "Click-to-focus behavior",
+          "href": "#click-to-focus-behavior",
+          "depth": 4,
+          "numbering": [
+            1,
+            4,
+            1,
+            2
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "API reference",
+          "href": "#api-reference",
+          "depth": 2,
+          "numbering": [
+            1,
+            5
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Common patterns",
+          "href": "#common-patterns",
+          "depth": 2,
+          "numbering": [
+            1,
+            6
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Comment input with character limit",
+          "href": "#comment-input-with-character-limit",
+          "depth": 3,
+          "numbering": [
+            1,
+            6,
+            1
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Auto-growing feedback form",
+          "href": "#auto-growing-feedback-form",
+          "depth": 3,
+          "numbering": [
+            1,
+            6,
+            2
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Multi-field form with validation",
+          "href": "#multi-field-form-with-validation",
+          "depth": 3,
+          "numbering": [
+            1,
+            6,
+            3
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Testing your implementation",
+          "href": "#testing-your-implementation",
+          "depth": 2,
+          "numbering": [
+            1,
+            7
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Basic Rendering Tests",
+          "href": "#basic-rendering-tests",
+          "depth": 3,
+          "numbering": [
+            1,
+            7,
+            1
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Interaction Tests",
+          "href": "#interaction-tests",
+          "depth": 3,
+          "numbering": [
+            1,
+            7,
+            2
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Testing States",
+          "href": "#testing-states",
+          "depth": 3,
+          "numbering": [
+            1,
+            7,
+            3
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Testing with Character Limits",
+          "href": "#testing-with-character-limits",
+          "depth": 3,
+          "numbering": [
+            1,
+            7,
+            4
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Resources",
+          "href": "#resources",
+          "depth": 2,
+          "numbering": [
+            1,
+            8
+          ],
+          "parent": "root"
+        }
+      ]
+    },
+    "guidelines": {
+      "mdx": "\n## Guidelines\n\nNumber input guidelines focus on clear labels, suitable ranges, easy interaction\nvia keyboard and buttons, and strong error handling, all while following WCAG\naccessibility rules.\n\n### Best practices\n\n- **Labels:** Always include a concise and clear label using sentence case.\n  Labels should not be hidden. In the rare case where context is sufficient and\n  label can be absent, review the design with an accessibility expert.\n- **Placeholder text:** Use concise placeholder text to provide an example or\n  hint about the expected content. If consistent help is needed for context,\n  utilize an info icon or use helper text below the field, as placeholder text\n  disappears when a user interacts with the field, and some find it difficult to\n  read placeholder text.\n- **Initial height:** Set an appropriate initial height (min. rows) that\n  accommodates the typical expected input length without requiring immediate\n  scrolling or resizing\n- **Maximum height:** Define a reasonable max. rows to prevent the input from\n  growing excessively large and pushing other content off-screen. Once the\n  maximum is reached, the content should become scrollable.\n- **Resizability:** Enable resizing when users might need to view more content\n  at once or prefer a larger input area. Ensure the resize handle is visually\n  clear and functional.\n- **Validation:**\n  - Provide clear and concise error messages below the input field, replacing\n    any helper text.\n  - Highlight errors visually, for example, with a red border and an error icon.\n  - Validate input for any specified constraints (e.g., character limits,\n    required fields).\n\n### Usage\n\nA multi-line text input is used when users need to enter extended textual\ninformation, providing ample space and flexibility.\n\n> [!TIP]\\\n> When to use\n\n- Collecting descriptions, comments, or notes.\n- Allowing users to write full sentences or paragraphs.\n- When the length of the expected input is variable and could range from a few\n  words to multiple paragraphs.\n- When the user needs to see a significant portion of their input at once.\n\n> [!CAUTION]\\\n> When not to use\n\n- For single-line inputs (e.g., names, email addresses); use a single-line text\n  input.\n- For highly structured data that would be better handled with multiple specific\n  input fields (e.g., separate fields for street, city, state).\n- When character limits are very strict and a precise visual count is required\n  (though character counters can be added).\n\n### Labeling and sizing\n\nProviding clear labels and contextual information aids users to fill out the\ncorrect information.\n\n> [!TIP]\\\n> **Do**\n>\n> - Do always include a label.\n> - Do include helper text to guide users.\n> - Do set an appropriate initial height.\n\n```jsx live\nconst App = () => (\n  <MultilineTextInput\n        size=\"md\"\n        placeholder=\"well described placeholder\"\n        aria-label=\"Medium input\"\n        value=\"Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat.\"\n        rows={5}\n    />\n)\n```\n\n> [!CAUTION]\\\n> **Don't**\n>\n> - Don’t use for single-line inputs.\n> - Don’t hide labels.\n\n```jsx live\nconst App = () => (\n  <MultilineTextInput\n        size=\"md\"\n        placeholder=\"well described placeholder\"\n        aria-label=\"Medium input\"\n        value=\"1:30\"\n    />\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": "Usage",
+          "href": "#usage",
+          "depth": 3,
+          "numbering": [
+            1,
+            1,
+            2
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Labeling and sizing",
+          "href": "#labeling-and-sizing",
+          "depth": 3,
+          "numbering": [
+            1,
+            1,
+            3
+          ],
+          "parent": "root"
+        }
+      ]
+    }
+  }
+}