@commercetools/nimbus-mcp 0.1.0 → 2.10.0

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

@@ -0,0 +1,566 @@
+{
+  "meta": {
+    "id": "Components-TextInput",
+    "title": "Text input",
+    "exportName": "TextInput",
+    "description": "Allows users to enter information like names, addresses, emails, passwords, search queries, or any other text-based data.",
+    "lifecycleState": "Stable",
+    "order": 999,
+    "repoPath": "packages/nimbus/src/components/text-input/text-input.mdx",
+    "menu": [
+      "Components",
+      "Inputs",
+      "Text input"
+    ],
+    "route": "components/inputs/text-input",
+    "tags": [
+      "component",
+      "text",
+      "input",
+      "field",
+      "string"
+    ],
+    "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": "Size",
+        "href": "#size",
+        "depth": 3,
+        "numbering": [
+          1,
+          2,
+          1
+        ],
+        "parent": "root"
+      },
+      {
+        "value": "Variant",
+        "href": "#variant",
+        "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\nUsers can type, delete, copy, and paste text within the box. Sometimes, there\ncan be additional features like autocomplete or validation to help users enter\ninformation correctly.\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=1696-48973&m=dev)\n\n## Variables\n\nGet familiar with the features.\n\n**Placeholder**\n\nThis is the styling for placeholder text. It is a shade lighter than active\ntext.\n\n```jsx live\nconst App = () => <TextInput placeholder=\"input value\"/>\n```\n\n### Size\n\n**Medium**\n\nThis is the default size for text inputs.\n\n```jsx live\nconst App = () => <TextInput size=\"md\" value=\"input value\"/>\n```\n\n**Small**\n\nAvailable for the times a more condensed text input is needed.\n\n```jsx live\nconst App = () => <TextInput size=\"sm\" value=\"input value\"/>\n```\n\n### Variant\n\n**Solid**\n\nThis is the default variant styling for inputs.\n\n```jsx live\nconst App = () => <TextInput variant=\"solid\" value=\"input value\"/>\n```\n\n**Ghost**\n\nThis variant removes the outer border around the input, but preserves hover\nstyling.\n\n```jsx live\nconst App = () => <TextInput variant=\"ghost\" value=\"input value\"/>\n```\n",
+  "views": {
+    "overview": {
+      "mdx": "\n## Overview\n\nUsers can type, delete, copy, and paste text within the box. Sometimes, there\ncan be additional features like autocomplete or validation to help users enter\ninformation correctly.\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=1696-48973&m=dev)\n\n## Variables\n\nGet familiar with the features.\n\n**Placeholder**\n\nThis is the styling for placeholder text. It is a shade lighter than active\ntext.\n\n```jsx live\nconst App = () => <TextInput placeholder=\"input value\"/>\n```\n\n### Size\n\n**Medium**\n\nThis is the default size for text inputs.\n\n```jsx live\nconst App = () => <TextInput size=\"md\" value=\"input value\"/>\n```\n\n**Small**\n\nAvailable for the times a more condensed text input is needed.\n\n```jsx live\nconst App = () => <TextInput size=\"sm\" value=\"input value\"/>\n```\n\n### Variant\n\n**Solid**\n\nThis is the default variant styling for inputs.\n\n```jsx live\nconst App = () => <TextInput variant=\"solid\" value=\"input value\"/>\n```\n\n**Ghost**\n\nThis variant removes the outer border around the input, but preserves hover\nstyling.\n\n```jsx live\nconst App = () => <TextInput variant=\"ghost\" value=\"input value\"/>\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": "Size",
+          "href": "#size",
+          "depth": 3,
+          "numbering": [
+            1,
+            2,
+            1
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Variant",
+          "href": "#variant",
+          "depth": 3,
+          "numbering": [
+            1,
+            2,
+            2
+          ],
+          "parent": "root"
+        }
+      ]
+    },
+    "a11y": {
+      "mdx": "\n## Accessibility\n\nThe component uses onPress\\* props to handle all user interactions—mouse clicks,\ntouch taps, and keyboard presses—consistently. These props (onPress,\nonPressStart, onPressEnd, etc.) ensure a smooth and accessible experience\nregardless of the user's input method or device.\n\n```jsx live\nconst App = () => <TextInput placeholder=\"XX/XX/XXXX\" />\n```\n\n### Accessibility standards\n\n- **Info and relationships:** Use proper HTML (`<label>`, `aria-labelledby`,\n  etc.) to connect labels with their inputs. This helps assistive technologies\n  (like screen readers) understand the connection and convey the information\n  correctly.\n- **Color contrast:** Ensure sufficient color contrast between the input field,\n  its label, and the surrounding background. This makes it easier to read for\n  people with low vision. The minimum contrast ratio is 4.5:1 for normal text\n  and 3:1 for large text.\n- **Keyboard accessibility:** Text inputs must be fully operable using only a\n  keyboard (no mouse required). This includes navigating to the input,\n  interacting with it, and submitting the form.\n- **Headings and labels:** Labels should be clear, concise, and descriptive,\n  accurately reflecting the purpose of the input field.\n- **Labels or instructions:** Provide clear labels or instructions to help users\n  understand what type of information is expected in the input field.\n- **Name, role, value:** Ensure the input field's name (label), role (type of\n  input), and current value are programmatically available to assistive\n  technologies.\n- **Error messages:** When input errors occur, provide clear and specific error\n  messages that are easy to understand and locate. Use ARIA attributes\n  (`aria-invalid`, `aria-describedby`) to associate error messages with the\n  input field.\n- **Placeholder text:** While placeholder text can be helpful, it can also\n  create accessibility issues. Avoid using it as a replacement for labels, and\n  ensure sufficient color contrast if you do use it.\n- **Autocomplete:** Autocomplete can improve usability, but make sure it doesn't\n  interfere with accessibility. Users should be able to easily review and\n  override suggestions.\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 { TextInput, type TextInputProps } from '@commercetools/nimbus';\n```\n\n### Basic usage\n\nThe simplest implementation uses uncontrolled mode:\n\n```jsx live-dev\nconst App = () => (\n  <TextInput placeholder=\"Enter your name\" />\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    <TextInput size=\"sm\" placeholder=\"Small input\" />\n    <TextInput size=\"md\" placeholder=\"Medium input (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    <TextInput variant=\"solid\" placeholder=\"Solid variant (default)\" />\n    <TextInput variant=\"ghost\" placeholder=\"Ghost variant\" />\n  </Stack>\n)\n```\n\n### Leading and trailing elements\n\nAdd icons, buttons, or other elements before or after the input using `leadingElement` and `trailingElement` props:\n\n```jsx live-dev\nconst App = () => (\n  <Stack direction=\"column\" gap=\"400\">\n    <TextInput\n      placeholder=\"Search...\"\n      leadingElement={<Icons.Search />}\n    />\n    <TextInput\n      placeholder=\"Email address\"\n      leadingElement={<Icons.Email />}\n      trailingElement={<Icons.CheckCircle />}\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- Trailing element appears at the end (right in LTR, left in RTL)\n- Icon sizing automatically adjusts based on the `size` prop\n\n### Placeholder text\n\nUse placeholder text to provide hints about expected input format:\n\n```jsx live-dev\nconst App = () => (\n  <Stack direction=\"column\" gap=\"400\">\n    <TextInput placeholder=\"Enter your email\" />\n    <TextInput placeholder=\"john.doe@example.com\" />\n    <TextInput placeholder=\"Search products...\" />\n  </Stack>\n)\n```\n\n### Disabled state\n\nDisable input interaction with the `isDisabled` prop:\n\n```jsx live-dev\nconst App = () => (\n  <Stack direction=\"column\" gap=\"400\">\n    <TextInput placeholder=\"Enabled input\" />\n    <TextInput placeholder=\"Disabled input\" isDisabled />\n    <TextInput\n      value=\"Disabled with value\"\n      isDisabled\n      onChange={() => {}}\n    />\n  </Stack>\n)\n```\n\n### Invalid state\n\nMark inputs as invalid for validation feedback:\n\n```jsx live-dev\nconst App = () => (\n  <Stack direction=\"column\" gap=\"400\">\n    <TextInput\n      placeholder=\"Valid input\"\n      value=\"valid@example.com\"\n      onChange={() => {}}\n    />\n    <TextInput\n      placeholder=\"Invalid input\"\n      value=\"invalid-email\"\n      isInvalid\n      onChange={() => {}}\n    />\n  </Stack>\n)\n```\n\n### Read-only state\n\nUse `isReadOnly` to display values without allowing editing:\n\n```jsx live-dev\nconst App = () => (\n  <Stack direction=\"column\" gap=\"400\">\n    <TextInput\n      value=\"Editable value\"\n      onChange={() => {}}\n    />\n    <TextInput\n      value=\"Read-only value\"\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      <TextInput\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 input value without managing state yourself.\n\n**Note:** TextInput'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<string>('');\n\n  return (\n    <Stack direction=\"column\" gap=\"400\">\n      <TextInput\n        value={value}\n        onChange={(value) => setValue(value)}\n        placeholder=\"Controlled input\"\n      />\n      <Text fontSize=\"sm\">\n        {value ? `You typed: ${value}` : 'Start typing...'}\n      </Text>\n      <Button onClick={() => setValue('')} size=\"sm\">\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\n\n### Required field\n\nMark inputs as required using the `isRequired` prop:\n\n```jsx live-dev\nconst App = () => (\n  <Stack direction=\"column\" gap=\"400\">\n    <TextInput\n      placeholder=\"Optional field\"\n    />\n    <TextInput\n      placeholder=\"Required field\"\n      isRequired\n    />\n  </Stack>\n)\n```\n\n## Component requirements\n\n## Accessibility\n\nThe TextInput 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 `TextInputField` pattern component (recommended)\n- Associating a `<label>` element with the `TextInput` using `aria-labelledby`:\n\n```tsx\n<label id=\"email-label\">\n  {msg.format(emailMessage)}\n</label>\n<TextInput aria-labelledby=\"email-label\" />\n```\n\n- Associating a `<label>` element with the `TextInput` using `htmlFor`:\n\n```tsx\n<label htmlFor=\"email-input\">\n  {msg.format(emailMessage)}\n</label>\n<TextInput id=\"email-input\" />\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<TextInput aria-label={msg.format(emailMessage)} />\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 = \"user-email-input\";\n\nexport const EmailField = () => (\n  <TextInput id={PERSISTENT_ID} placeholder=\"Email\" />\n);\n```\n\n#### Keyboard navigation\n\nThe component supports full keyboard interaction:\n- `Tab` / `Shift+Tab`: Navigate to/from the input field\n- `Arrow keys`: Move cursor within the text (Left/Right), no vertical navigation\n- `Home` / `End`: Move cursor to start/end of text\n- `Ctrl+A` / `Cmd+A`: Select all text\n- Standard text editing shortcuts: Cut, Copy, Paste, Undo, Redo\n\n#### Click-to-focus behavior\n\nClicking anywhere within the input container (including leading/trailing elements area) will focus the input field, providing a larger interactive target for better usability.\n\n## API reference\n\n<PropsTable id=\"TextInput\" />\n\n## Common patterns\n\n### Input with icon\n\nDisplay an icon to indicate the input's purpose:\n\n```jsx live-dev\nconst App = () => {\n  const [email, setEmail] = useState<string>('');\n  const [password, setPassword] = useState<string>('');\n\n  return (\n    <Stack direction=\"column\" gap=\"400\">\n      <TextInput\n        value={email}\n        onChange={(value) => setEmail(value)}\n        placeholder=\"Email address\"\n        leadingElement={<Icons.Email />}\n      />\n      <TextInput\n        value={password}\n        onChange={(value) => setPassword(value)}\n        placeholder=\"Password\"\n        type=\"password\"\n        leadingElement={<Icons.Lock />}\n      />\n    </Stack>\n  );\n}\n```\n\n### Search input pattern\n\nCreate a search input with appropriate icons:\n\n```jsx live-dev\nconst App = () => {\n  const [searchQuery, setSearchQuery] = useState<string>('');\n\n  return (\n    <Stack direction=\"column\" gap=\"400\">\n      <TextInput\n        value={searchQuery}\n        onChange={(value) => setSearchQuery(value)}\n        placeholder=\"Search products...\"\n        leadingElement={<Icons.Search />}\n      />\n      {searchQuery && (\n        <Text fontSize=\"sm\">Searching for: {searchQuery}</Text>\n      )}\n    </Stack>\n  );\n}\n```\n\n### Input with clear button\n\nAdd a button to quickly clear the input value:\n\n```jsx live-dev\nconst App = () => {\n  const [value, setValue] = useState<string>('');\n\n  return (\n    <TextInput\n      value={value}\n      onChange={(value) => setValue(value)}\n      placeholder=\"Type something...\"\n      leadingElement={<Icons.Search />}\n      trailingElement={\n        value ? (\n          <IconButton\n            onClick={() => setValue('')}\n            size=\"sm\"\n            variant=\"ghost\"\n            aria-label=\"Clear input\"\n          >\n            <Icons.Close />\n          </IconButton>\n        ) : null\n      }\n    />\n  );\n}\n```\n\n## Testing your implementation\n\nThese examples demonstrate how to test your implementation when using TextInput 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 { TextInput, NimbusProvider } from \"@commercetools/nimbus\";\n\ndescribe(\"TextInput - Basic rendering\", () => {\n  it(\"renders input element\", () => {\n    render(\n      <NimbusProvider>\n        <TextInput aria-label=\"Text input\" placeholder=\"Enter text\" />\n      </NimbusProvider>\n    );\n\n    // Verify input is present\n    expect(screen.getByRole(\"textbox\")).toBeInTheDocument();\n  });\n\n  it(\"renders with placeholder text\", () => {\n    render(\n      <NimbusProvider>\n        <TextInput aria-label=\"Email\" placeholder=\"Email address\" />\n      </NimbusProvider>\n    );\n\n    expect(screen.getByPlaceholderText(\"Email address\")).toBeInTheDocument();\n  });\n\n  it(\"renders with aria-label\", () => {\n    render(\n      <NimbusProvider>\n        <TextInput aria-label=\"User email\" />\n      </NimbusProvider>\n    );\n\n    expect(\n      screen.getByRole(\"textbox\", { name: /user email/i })\n    ).toBeInTheDocument();\n  });\n});\n```\n\n### Interaction Tests\n\nTest user interactions with the component\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 { TextInput, NimbusProvider } from \"@commercetools/nimbus\";\n\ndescribe(\"TextInput - Interactions\", () => {\n  it(\"updates value when user types\", async () => {\n    const user = userEvent.setup();\n    render(\n      <NimbusProvider>\n        <TextInput aria-label=\"Text input\" placeholder=\"Type here\" />\n      </NimbusProvider>\n    );\n\n    const input = screen.getByRole(\"textbox\");\n    await user.type(input, \"Hello World\");\n\n    expect(input).toHaveValue(\"Hello World\");\n  });\n\n  it(\"calls onChange callback with string value\", async () => {\n    const user = userEvent.setup();\n    const handleChange = vi.fn();\n    render(\n      <NimbusProvider>\n        <TextInput aria-label=\"Text input\" onChange={handleChange} />\n      </NimbusProvider>\n    );\n\n    const input = screen.getByRole(\"textbox\");\n    await user.type(input, \"test\");\n\n    expect(handleChange).toHaveBeenCalled();\n    expect(typeof handleChange.mock.calls[0][0]).toBe(\"string\");\n  });\n});\n```\n\n### Testing Controlled Mode\n\nTest controlled component behavior\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 { TextInput, NimbusProvider } from \"@commercetools/nimbus\";\n\ndescribe(\"TextInput - Controlled mode\", () => {\n  it(\"displays controlled value\", () => {\n    render(\n      <NimbusProvider>\n        <TextInput\n          aria-label=\"Text input\"\n          value=\"controlled value\"\n          onChange={() => {}}\n        />\n      </NimbusProvider>\n    );\n\n    const input = screen.getByRole(\"textbox\");\n    expect(input).toHaveValue(\"controlled value\");\n  });\n\n  it(\"updates when controlled value changes\", () => {\n    const { rerender } = render(\n      <NimbusProvider>\n        <TextInput\n          aria-label=\"Text input\"\n          value=\"first value\"\n          onChange={() => {}}\n        />\n      </NimbusProvider>\n    );\n\n    expect(screen.getByRole(\"textbox\")).toHaveValue(\"first value\");\n\n    rerender(\n      <NimbusProvider>\n        <TextInput\n          aria-label=\"Text input\"\n          value=\"second value\"\n          onChange={() => {}}\n        />\n      </NimbusProvider>\n    );\n\n    expect(screen.getByRole(\"textbox\")).toHaveValue(\"second value\");\n  });\n});\n```\n\n### Testing Leading and Trailing Elements\n\nTest custom elements within the input\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 { TextInput, NimbusProvider } from \"@commercetools/nimbus\";\n\ndescribe(\"TextInput - Elements\", () => {\n  it(\"renders leading element\", () => {\n    render(\n      <NimbusProvider>\n        <TextInput\n          aria-label=\"Search input\"\n          leadingElement={<span data-testid=\"icon\">🔍</span>}\n          placeholder=\"Search\"\n        />\n      </NimbusProvider>\n    );\n\n    expect(screen.getByTestId(\"icon\")).toBeInTheDocument();\n  });\n\n  it(\"renders trailing element\", () => {\n    render(\n      <NimbusProvider>\n        <TextInput\n          aria-label=\"Text input\"\n          trailingElement={<button data-testid=\"clear\">Clear</button>}\n          placeholder=\"Input\"\n        />\n      </NimbusProvider>\n    );\n\n    expect(screen.getByTestId(\"clear\")).toBeInTheDocument();\n  });\n\n  it(\"trailing button is interactive\", async () => {\n    const user = userEvent.setup();\n    const handleClick = vi.fn();\n\n    render(\n      <NimbusProvider>\n        <TextInput\n          aria-label=\"Text input\"\n          trailingElement={<button onClick={handleClick}>Action</button>}\n        />\n      </NimbusProvider>\n    );\n\n    await user.click(screen.getByText(\"Action\"));\n\n    expect(handleClick).toHaveBeenCalled();\n  });\n});\n```\n\n### Testing Validation States\n\nTest different validation states\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 { TextInput, NimbusProvider } from \"@commercetools/nimbus\";\n\ndescribe(\"TextInput - Validation states\", () => {\n  it(\"renders disabled state\", () => {\n    render(\n      <NimbusProvider>\n        <TextInput\n          aria-label=\"Disabled input\"\n          isDisabled\n          placeholder=\"Disabled\"\n        />\n      </NimbusProvider>\n    );\n\n    const input = screen.getByRole(\"textbox\");\n    expect(input).toBeDisabled();\n  });\n\n  it(\"renders invalid state\", () => {\n    render(\n      <NimbusProvider>\n        <TextInput aria-label=\"Invalid input\" isInvalid placeholder=\"Invalid\" />\n      </NimbusProvider>\n    );\n\n    const input = screen.getByRole(\"textbox\");\n    expect(input).toHaveAttribute(\"aria-invalid\", \"true\");\n  });\n\n  it(\"renders read-only state\", () => {\n    render(\n      <NimbusProvider>\n        <TextInput\n          aria-label=\"Read-only input\"\n          isReadOnly\n          value=\"Read-only\"\n          onChange={() => {}}\n        />\n      </NimbusProvider>\n    );\n\n    const input = screen.getByRole(\"textbox\");\n    expect(input).toHaveAttribute(\"readonly\");\n  });\n\n  it(\"renders required state\", () => {\n    render(\n      <NimbusProvider>\n        <TextInput\n          aria-label=\"Required input\"\n          isRequired\n          placeholder=\"Required\"\n        />\n      </NimbusProvider>\n    );\n\n    const input = screen.getByRole(\"textbox\");\n    expect(input).toHaveAttribute(\"aria-required\", \"true\");\n  });\n});\n```\n\n\n## Resources\n\n- [Storybook](https://nimbus-storybook.vercel.app/?path=/docs/components-textinput--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- [TextInputField Pattern](../patterns/fields/textinputfield)\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 and trailing elements",
+          "href": "#leading-and-trailing-elements",
+          "depth": 3,
+          "numbering": [
+            1,
+            2,
+            3
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Placeholder text",
+          "href": "#placeholder-text",
+          "depth": 3,
+          "numbering": [
+            1,
+            2,
+            4
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Disabled state",
+          "href": "#disabled-state",
+          "depth": 3,
+          "numbering": [
+            1,
+            2,
+            5
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Invalid state",
+          "href": "#invalid-state",
+          "depth": 3,
+          "numbering": [
+            1,
+            2,
+            6
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Read-only state",
+          "href": "#read-only-state",
+          "depth": 3,
+          "numbering": [
+            1,
+            2,
+            7
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Uncontrolled mode",
+          "href": "#uncontrolled-mode",
+          "depth": 3,
+          "numbering": [
+            1,
+            2,
+            8
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Controlled mode",
+          "href": "#controlled-mode",
+          "depth": 3,
+          "numbering": [
+            1,
+            2,
+            9
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Required field",
+          "href": "#required-field",
+          "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": "Input with icon",
+          "href": "#input-with-icon",
+          "depth": 3,
+          "numbering": [
+            1,
+            6,
+            1
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Search input pattern",
+          "href": "#search-input-pattern",
+          "depth": 3,
+          "numbering": [
+            1,
+            6,
+            2
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Input with clear button",
+          "href": "#input-with-clear-button",
+          "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 Controlled Mode",
+          "href": "#testing-controlled-mode",
+          "depth": 3,
+          "numbering": [
+            1,
+            7,
+            3
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Testing Leading and Trailing Elements",
+          "href": "#testing-leading-and-trailing-elements",
+          "depth": 3,
+          "numbering": [
+            1,
+            7,
+            4
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Testing Validation States",
+          "href": "#testing-validation-states",
+          "depth": 3,
+          "numbering": [
+            1,
+            7,
+            5
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Resources",
+          "href": "#resources",
+          "depth": 2,
+          "numbering": [
+            1,
+            8
+          ],
+          "parent": "root"
+        }
+      ]
+    },
+    "guidelines": {
+      "mdx": "\n## Guidelines\n\nText input guidelines focus on creating clear, accessible, and user-friendly\nfields for data entry by emphasizing proper labeling, providing helpful cues and\nvalidation, ensuring keyboard navigation, and offering clear feedback on input\nstatus.\n\n### Best practices\n\n- **Keyboard Navigation:**\n  - Ensure that text inputs are fully keyboard accessible (using the Tab key to\n    navigate).\n- **Error Handling:**\n  - Provide clear and specific error messages when invalid input is entered.\n  - Display error messages close to the input field.\n- **Placeholder text:**\n  - Avoid relying solely on placeholder text, as it disappears when the user\n    starts typing.\n  - Make use of clear labels and helper text if clarifying information is\n    needed.\n\n### Placeholder text\n\nGood placeholder text informs the user what to expect and can easily understand\nthe difference between placeholder and pre-filled content.\n\n> [!TIP]\\\n> When to use\n\n- **Provide hints:** Use placeholder text to give users a brief hint or example\n  of the expected input format.\n- **Keep it concise:** Placeholder text should be short and to the point. Avoid\n  long sentences or paragraphs.\n- **Use a subtle visual style:** Visually differentiate placeholder text from\n  actual input text by using the placeholder text styling. This helps users\n  understand that it's a suggestion, not a pre-filled value.  \n\n> [!CAUTION]\\\n> When not to use\n\n- **Don't use as labels:** Placeholder text should never replace proper labels.\n  Labels provide persistent context, while placeholder text disappears when the\n  user starts typing.  \n- **Don't include critical information:** Avoid putting essential instructions\n  or information solely in the placeholder, as it will be hidden once the user\n  interacts with the field.  \n- **Don't overuse:** Too much placeholder text can clutter the interface and\n  make it harder for users to focus.\n\n> [!TIP]\\\n> **Do**\n>\n> - Give the user a hint on what is expected, in a concise way.\n> - If this information is important to always keep visible, use helper text\n>   instead.\n\n```jsx live\nconst App = () => <TextInput placeholder=\"MM/DD/YYYY\"/>\n```\n\n> [!CAUTION]\\\n> **Don't**\n>\n> - This placeholder text looks like it has been prefilled for the user which is\n>   more likely to confuse the user.\n\n```jsx live\nconst App = () => <TextInput placeholder=\"01/21/1970\"/>\n```\n\n### Size\n\nAllow for enough width for the user to read and add in their information. Avoid\ntruncation if possible especially if the user will be referring back or needing\nto make sure there isn’t inaccurate information.\n\n> [!TIP]\\\n> When to use\n>\n> - There is enough space that the user can easily consume and correct this\n>   information if needed.\n\n```jsx live\nconst App = () => <TextInput placeholder=\"01/21/1970\" value=\"805 St Cloud Road\"/>\n```\n\n> [!CAUTION]\\\n> **Don't**\n>\n> - The user’s information is too long for this field to be able to read the\n>   details completely.\n\n```jsx live\nconst App = () => <TextInput value=\"805 St Cloud Road, Bel Air, Los Angeles, CA\" />\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": "Placeholder text",
+          "href": "#placeholder-text",
+          "depth": 3,
+          "numbering": [
+            1,
+            1,
+            2
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Size",
+          "href": "#size",
+          "depth": 3,
+          "numbering": [
+            1,
+            1,
+            3
+          ],
+          "parent": "root"
+        }
+      ]
+    }
+  }
+}