@commercetools/nimbus-mcp 0.1.0 → 2.11.0

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

@@ -0,0 +1,576 @@
+{
+  "meta": {
+    "id": "Components-PasswordInput",
+    "title": "Password input",
+    "exportName": "PasswordInput",
+    "description": "A password input is a text field that hides entered characters for secure password entry.",
+    "lifecycleState": "Stable",
+    "order": 999,
+    "repoPath": "packages/nimbus/src/components/password-input/password-input.mdx",
+    "menu": [
+      "Components",
+      "Inputs",
+      "Password input"
+    ],
+    "route": "components/inputs/password-input",
+    "tags": [
+      "component",
+      "forms",
+      "password",
+      "input",
+      "secure"
+    ],
+    "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": "Medium",
+        "href": "#medium",
+        "depth": 4,
+        "numbering": [
+          1,
+          2,
+          1,
+          1
+        ],
+        "parent": "root"
+      },
+      {
+        "value": "Small",
+        "href": "#small",
+        "depth": 4,
+        "numbering": [
+          1,
+          2,
+          1,
+          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\nPassword input guidelines focus on creating secure and user-friendly fields for\nentering sensitive credentials, emphasizing visual obscuring of input, clear\nlabeling and validation, accessibility considerations, and best practices for\npassword visibility toggles and error handling.\n\n### Resources\n\nDeep dive into implementation details and access the Nimbus design library.\n\n[Figma library](https://www.figma.com/design/AvtPX6g7OGGCRvNlatGOIY/NIMBUS-design-system?node-id=3982-23613&m=dev)\n\n## Variables\n\nGet familiar with the features.\n\n### Visual options\n\n#### Medium\n\n```jsx live\nconst App = () => <PasswordInput placeholder=\"Enter a password\" />\n```\n\n#### Small\n\n```jsx live\nconst App = () => <PasswordInput placeholder=\"Enter a password\" size=\"sm\" />\n```\n",
+  "views": {
+    "overview": {
+      "mdx": "\n## Overview\n\nPassword input guidelines focus on creating secure and user-friendly fields for\nentering sensitive credentials, emphasizing visual obscuring of input, clear\nlabeling and validation, accessibility considerations, and best practices for\npassword visibility toggles and error handling.\n\n### Resources\n\nDeep dive into implementation details and access the Nimbus design library.\n\n[Figma library](https://www.figma.com/design/AvtPX6g7OGGCRvNlatGOIY/NIMBUS-design-system?node-id=3982-23613&m=dev)\n\n## Variables\n\nGet familiar with the features.\n\n### Visual options\n\n#### Medium\n\n```jsx live\nconst App = () => <PasswordInput placeholder=\"Enter a password\" />\n```\n\n#### Small\n\n```jsx live\nconst App = () => <PasswordInput placeholder=\"Enter a password\" size=\"sm\" />\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": "Medium",
+          "href": "#medium",
+          "depth": 4,
+          "numbering": [
+            1,
+            2,
+            1,
+            1
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Small",
+          "href": "#small",
+          "depth": 4,
+          "numbering": [
+            1,
+            2,
+            1,
+            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  <PasswordInput\n    placeholder=\"Enter a password\"\n    autoComplete=\"current-password\"\n    aria-label=\"Password\"\n  />\n);\n```\n\n### Accessibility standards\n\n- Always provide a visible label for the input.\n- Clearly associate the label with the input using the for attribute on the\n  `<label>` and a matching id on the `<input type=\"password\">`.\n- Ensure sufficient color contrast for all elements (text, borders, icons, focus\n  indicators).\n- Clearly indicate the focused state.\n- Support keyboard navigation:\n  - Use Tab to navigate to and from the input.\n  - Allow users to copy, cut, and paste using standard keyboard shortcuts\n    (Ctrl/Cmd + C, Ctrl/Cmd + X, Ctrl/Cmd + V).\n- Communicate errors clearly, using both visual cues (e.g., color) and\n  descriptive error messages.\n- Provide a toggle to show/hide password characters. Ensure this toggle is\n  keyboard accessible and clearly labeled (e.g., \"Show password\" / \"Hide\n  password\").\n- Use autocomplete=\"current-password\" or autocomplete=\"new-password\" as\n  appropriate to allow browsers and password managers to offer autofill.\n- Avoid automatically masking pasted content.\n- Do not disable the paste functionality.\n\n## Resources\n\n- [Adobe Spectrum Design System](https://spectrum.adobe.com/page/text-field/)\n- [React Spectrum](https://react-spectrum.adobe.com/react-spectrum/TextField.html)\n- [W3C ARIA Authoring Practices Guide (APG)](https://www.w3.org/WAI/ARIA/apg/)\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": 2,
+          "numbering": [
+            1,
+            2
+          ],
+          "parent": "root"
+        }
+      ]
+    },
+    "dev": {
+      "mdx": "\n## Getting started\n\n### Import\n\n```tsx\nimport { PasswordInput, type PasswordInputProps } from '@commercetools/nimbus';\n```\n\n### Basic usage\n\nThe simplest implementation uses uncontrolled mode:\n\n```jsx live-dev\nconst App = () => (\n  <PasswordInput placeholder=\"Enter your password\" />\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    <PasswordInput size=\"sm\" placeholder=\"Small password input\" />\n    <PasswordInput size=\"md\" placeholder=\"Medium password 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    <PasswordInput variant=\"solid\" placeholder=\"Solid variant (default)\" />\n    <PasswordInput variant=\"ghost\" placeholder=\"Ghost variant\" />\n  </Stack>\n)\n```\n\n### With leading element\n\nAdd an icon or other element at the start of the input:\n\n```jsx live-dev\nconst App = () => {\n  const { Lock } = Icons;\n\n  return (\n    <Stack direction=\"column\" gap=\"400\">\n      <PasswordInput\n        size=\"sm\"\n        leadingElement={<Icon as={Lock} />}\n        placeholder=\"Small with icon\"\n      />\n      <PasswordInput\n        size=\"md\"\n        leadingElement={<Icon as={Lock} />}\n        placeholder=\"Medium with icon\"\n      />\n    </Stack>\n  );\n}\n```\n\n**Behavioral notes:**\n- Leading element automatically respects text direction (LTR/RTL)\n- Icon sizing automatically adjusts based on the `size` prop\n- The visibility toggle button always appears at the end of the input\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    <PasswordInput placeholder=\"Enabled input\" />\n    <PasswordInput placeholder=\"Disabled input\" isDisabled />\n    <PasswordInput\n      value=\"SecretPassword123\"\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    <PasswordInput\n      placeholder=\"Valid password\"\n      value=\"StrongPass123!\"\n      onChange={() => {}}\n    />\n    <PasswordInput\n      placeholder=\"Invalid password\"\n      value=\"weak\"\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    <PasswordInput\n      value=\"EditablePassword123\"\n      onChange={() => {}}\n      placeholder=\"Editable password\"\n    />\n    <PasswordInput\n      value=\"ReadOnlyPassword456\"\n      isReadOnly\n      onChange={() => {}}\n      placeholder=\"Read-only password\"\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      <PasswordInput\n        placeholder=\"Type your password...\"\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 password value without managing state yourself.\n\n**Note:** PasswordInput's `onChange` receives the string value directly, not an event object.\n\n### Controlled mode\n\nFor scenarios requiring programmatic control or validation, 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      <PasswordInput\n        value={value}\n        onChange={(value) => setValue(value)}\n        placeholder=\"Controlled password\"\n      />\n      <Text fontSize=\"sm\">\n        {value ? `You typed: ${value}` : '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 password strength in real-time\n- Clear or programmatically set the value\n- Coordinate with other form fields\n\n## Component requirements\n\n## Accessibility\n\nThe PasswordInput handles most accessibility requirements internally, including the show/hide password button with internationalized labels. However, you must always associate an internationalized label with the component. Visual labels are preferable, and can be set by using the [`PasswordInputField`](patterns/fields/passwordinputfield) pattern component.\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<PasswordInput aria-label={msg.format(passwordMessage)} />\n```\n\nIf your use case requires tracking and analytics for this component, it is good practice to add a **persistent**, **unique** id to the component:\n\n```tsx\nconst PERSISTENT_ID = \"example-password-input\";\n\nexport const Example = () => (\n  <PasswordInput id={PERSISTENT_ID} aria-label=\"Password\" />\n);\n```\n\n#### Keyboard navigation\n\nThe component supports full keyboard interaction:\n- `Tab` / `Shift+Tab`: Move focus to/from the input field and visibility toggle button\n- `Enter` / `Space`: When the visibility toggle button is focused, toggles password visibility\n- Standard text input editing: All standard keyboard shortcuts for text editing work in the input field\n\n## API reference\n\n<PropsTable id=\"PasswordInput\" />\n\n## Common patterns\n\n### Password confirmation\n\nA common pattern for password entry with confirmation:\n\n```jsx live-dev\nconst App = () => {\n  const [password, setPassword] = useState<string>('');\n  const [confirmPassword, setConfirmPassword] = useState<string>('');\n\n  const passwordsMatch = password === confirmPassword && password !== \"\";\n  const showMismatch = confirmPassword !== \"\" && !passwordsMatch;\n\n  return (\n    <Stack direction=\"column\" gap=\"400\">\n      <PasswordInput\n        value={password}\n        onChange={setPassword}\n        placeholder=\"Enter password\"\n      />\n      <PasswordInput\n        value={confirmPassword}\n        onChange={setConfirmPassword}\n        isInvalid={showMismatch}\n        placeholder=\"Confirm password\"\n      />\n      {showMismatch && (\n        <Text fontSize=\"sm\" color=\"critical.11\">\n          Passwords do not match\n        </Text>\n      )}\n      {passwordsMatch && (\n        <Text fontSize=\"sm\" color=\"positive.11\">\n          Passwords match\n        </Text>\n      )}\n    </Stack>\n  );\n}\n```\n\n### Password strength indicator\n\nIntegrate with password strength validation:\n\n```jsx live-dev\nconst App = () => {\n  const [password, setPassword] = useState<string>('');\n\n  const getStrength = (pass: string) => {\n    if (!pass) return { label: \"No password\", color: \"neutral.11\" };\n    if (pass.length < 6) return { label: \"Weak\", color: \"critical.11\" };\n    if (pass.length < 10) return { label: \"Medium\", color: \"warning.11\" };\n    return { label: \"Strong\", color: \"positive.11\" };\n  };\n\n  const strength = getStrength(password);\n\n  return (\n    <Stack direction=\"column\" gap=\"400\">\n      <PasswordInput\n        value={password}\n        onChange={setPassword}\n        placeholder=\"Enter password\"\n      />\n      <Text fontSize=\"sm\" color={strength.color}>\n        Strength: {strength.label}\n      </Text>\n      <Text fontSize=\"xs\" color=\"neutral.11\">\n        Use at least 10 characters for a strong password\n      </Text>\n    </Stack>\n  );\n}\n```\n\n## Testing your implementation\n\nThese examples demonstrate how to test your implementation when using PasswordInput 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 { PasswordInput, NimbusProvider } from \"@commercetools/nimbus\";\n\ndescribe(\"PasswordInput - Basic rendering\", () => {\n  it(\"renders password input field\", () => {\n    render(\n      <NimbusProvider>\n        <PasswordInput aria-label=\"Password\" />\n      </NimbusProvider>\n    );\n\n    // Verify input is present with password type\n    const input = screen.getByLabelText(\"Password\");\n    expect(input).toBeInTheDocument();\n    expect(input).toHaveAttribute(\"type\", \"password\");\n  });\n\n  it(\"renders visibility toggle button\", () => {\n    render(\n      <NimbusProvider>\n        <PasswordInput aria-label=\"Password\" />\n      </NimbusProvider>\n    );\n\n    // Verify toggle button is present\n    const toggleButton = screen.getByRole(\"button\");\n    expect(toggleButton).toBeInTheDocument();\n  });\n\n  it(\"renders with placeholder text\", () => {\n    render(\n      <NimbusProvider>\n        <PasswordInput\n          aria-label=\"Password\"\n          placeholder=\"Enter your password\"\n        />\n      </NimbusProvider>\n    );\n\n    expect(\n      screen.getByPlaceholderText(\"Enter your password\")\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 { PasswordInput, NimbusProvider } from \"@commercetools/nimbus\";\n\ndescribe(\"PasswordInput - Interactions\", () => {\n  it(\"toggles password visibility when button is clicked\", async () => {\n    const user = userEvent.setup();\n    render(\n      <NimbusProvider>\n        <PasswordInput aria-label=\"Password\" />\n      </NimbusProvider>\n    );\n\n    const input = screen.getByLabelText(\"Password\");\n    const toggleButton = screen.getByRole(\"button\");\n\n    // Initially type is password\n    expect(input).toHaveAttribute(\"type\", \"password\");\n\n    // Click to show password\n    await user.click(toggleButton);\n    expect(input).toHaveAttribute(\"type\", \"text\");\n\n    // Click again to hide password\n    await user.click(toggleButton);\n    expect(input).toHaveAttribute(\"type\", \"password\");\n  });\n\n  it(\"calls onChange with entered value\", async () => {\n    const user = userEvent.setup();\n    const handleChange = vi.fn();\n    render(\n      <NimbusProvider>\n        <PasswordInput aria-label=\"Password\" onChange={handleChange} />\n      </NimbusProvider>\n    );\n\n    const input = screen.getByLabelText(\"Password\");\n    await user.type(input, \"Secret123\");\n\n    expect(handleChange).toHaveBeenCalled();\n    expect(input).toHaveValue(\"Secret123\");\n  });\n\n  it(\"updates value when user types\", async () => {\n    const user = userEvent.setup();\n    render(\n      <NimbusProvider>\n        <PasswordInput placeholder=\"Type password\" aria-label=\"Password\" />\n      </NimbusProvider>\n    );\n\n    const input = screen.getByLabelText(\"Password\");\n    await user.type(input, \"MyPassword123\");\n\n    expect(input).toHaveValue(\"MyPassword123\");\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 { PasswordInput, NimbusProvider } from \"@commercetools/nimbus\";\n\ndescribe(\"PasswordInput - Controlled mode\", () => {\n  it(\"displays controlled value\", () => {\n    render(\n      <NimbusProvider>\n        <PasswordInput\n          value=\"controlled value\"\n          onChange={() => {}}\n          aria-label=\"Password\"\n        />\n      </NimbusProvider>\n    );\n\n    const input = screen.getByLabelText(\"Password\");\n    expect(input).toHaveValue(\"controlled value\");\n  });\n\n  it(\"updates when controlled value changes\", () => {\n    const { rerender } = render(\n      <NimbusProvider>\n        <PasswordInput\n          value=\"first value\"\n          onChange={() => {}}\n          aria-label=\"Password\"\n        />\n      </NimbusProvider>\n    );\n\n    expect(screen.getByLabelText(\"Password\")).toHaveValue(\"first value\");\n\n    rerender(\n      <NimbusProvider>\n        <PasswordInput\n          value=\"second value\"\n          onChange={() => {}}\n          aria-label=\"Password\"\n        />\n      </NimbusProvider>\n    );\n\n    expect(screen.getByLabelText(\"Password\")).toHaveValue(\"second value\");\n  });\n\n  it(\"clears controlled value\", async () => {\n    const user = userEvent.setup();\n    let currentValue = \"Test\";\n\n    const { rerender } = render(\n      <NimbusProvider>\n        <PasswordInput\n          value={currentValue}\n          onChange={(value: string) => {\n            currentValue = value;\n          }}\n          aria-label=\"Password\"\n        />\n      </NimbusProvider>\n    );\n\n    const input = screen.getByLabelText(\"Password\");\n    expect(input).toHaveValue(\"Test\");\n\n    await user.clear(input);\n\n    // Rerender with cleared value\n    rerender(\n      <NimbusProvider>\n        <PasswordInput\n          value=\"\"\n          onChange={(value: string) => {\n            currentValue = value;\n          }}\n          aria-label=\"Password\"\n        />\n      </NimbusProvider>\n    );\n\n    expect(input).toHaveValue(\"\");\n  });\n});\n```\n\n### Testing Leading Element\n\nTest custom leading element rendering\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 { PasswordInput, NimbusProvider } from \"@commercetools/nimbus\";\n\ndescribe(\"PasswordInput - Leading element\", () => {\n  it(\"renders leading element\", () => {\n    render(\n      <NimbusProvider>\n        <PasswordInput\n          aria-label=\"Password\"\n          leadingElement={<span data-testid=\"lock-icon\">🔒</span>}\n          placeholder=\"Password\"\n        />\n      </NimbusProvider>\n    );\n\n    expect(screen.getByTestId(\"lock-icon\")).toBeInTheDocument();\n  });\n\n  it(\"renders input with leading element\", () => {\n    render(\n      <NimbusProvider>\n        <PasswordInput\n          leadingElement={<span data-testid=\"icon\">Icon</span>}\n          aria-label=\"Password with icon\"\n        />\n      </NimbusProvider>\n    );\n\n    expect(screen.getByTestId(\"icon\")).toBeInTheDocument();\n    expect(screen.getByLabelText(/password with icon/i)).toBeInTheDocument();\n  });\n});\n```\n\n### Testing Keyboard Navigation\n\nTest keyboard interactions\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 { PasswordInput, NimbusProvider } from \"@commercetools/nimbus\";\n\ndescribe(\"PasswordInput - Keyboard navigation\", () => {\n  it(\"toggles visibility with Enter key\", async () => {\n    const user = userEvent.setup();\n    render(\n      <NimbusProvider>\n        <PasswordInput aria-label=\"Password\" />\n      </NimbusProvider>\n    );\n\n    const input = screen.getByLabelText(\"Password\");\n    const toggleButton = screen.getByRole(\"button\");\n\n    // Use userEvent.tab() to focus elements (avoids act() warnings)\n    // First tab focuses the input, second tab focuses the toggle button\n    await user.tab();\n    await user.tab();\n    expect(toggleButton).toHaveFocus();\n\n    // Press Enter to toggle\n    await user.keyboard(\"{Enter}\");\n    expect(input).toHaveAttribute(\"type\", \"text\");\n\n    // Press Space to toggle back\n    await user.keyboard(\" \");\n    expect(input).toHaveAttribute(\"type\", \"password\");\n  });\n\n  it(\"moves focus between input and button with Tab\", async () => {\n    const user = userEvent.setup();\n    render(\n      <NimbusProvider>\n        <PasswordInput aria-label=\"Password\" />\n      </NimbusProvider>\n    );\n\n    const input = screen.getByLabelText(\"Password\");\n    const toggleButton = screen.getByRole(\"button\");\n\n    // Tab to input\n    await user.tab();\n    expect(input).toHaveFocus();\n\n    // Tab to toggle button\n    await user.tab();\n    expect(toggleButton).toHaveFocus();\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 { PasswordInput, NimbusProvider } from \"@commercetools/nimbus\";\n\ndescribe(\"PasswordInput - Validation states\", () => {\n  it(\"renders disabled state\", () => {\n    render(\n      <NimbusProvider>\n        <PasswordInput\n          isDisabled\n          placeholder=\"Disabled\"\n          aria-label=\"Password\"\n        />\n      </NimbusProvider>\n    );\n\n    const input = screen.getByLabelText(\"Password\");\n    expect(input).toBeDisabled();\n  });\n\n  it(\"renders invalid state\", () => {\n    render(\n      <NimbusProvider>\n        <PasswordInput isInvalid placeholder=\"Invalid\" aria-label=\"Password\" />\n      </NimbusProvider>\n    );\n\n    const input = screen.getByLabelText(\"Password\");\n    expect(input).toHaveAttribute(\"aria-invalid\", \"true\");\n  });\n\n  it(\"renders read-only state\", () => {\n    render(\n      <NimbusProvider>\n        <PasswordInput\n          isReadOnly\n          value=\"Read-only password\"\n          onChange={() => {}}\n          aria-label=\"Password\"\n        />\n      </NimbusProvider>\n    );\n\n    const input = screen.getByLabelText(\"Password\");\n    expect(input).toHaveAttribute(\"readonly\");\n  });\n\n  it(\"renders required state\", () => {\n    render(\n      <NimbusProvider>\n        <PasswordInput\n          isRequired\n          placeholder=\"Required\"\n          aria-label=\"Password\"\n        />\n      </NimbusProvider>\n    );\n\n    const input = screen.getByLabelText(\"Password\");\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-passwordinput--docs)\n- [PasswordInputField Pattern](/patterns/fields/passwordinputfield)\n- [TextInput Component](/components/inputs/textinput)\n- [React Aria TextField](https://react-spectrum.adobe.com/react-aria/TextField.html)\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": "With leading element",
+          "href": "#with-leading-element",
+          "depth": 3,
+          "numbering": [
+            1,
+            2,
+            3
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Disabled state",
+          "href": "#disabled-state",
+          "depth": 3,
+          "numbering": [
+            1,
+            2,
+            4
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Invalid state",
+          "href": "#invalid-state",
+          "depth": 3,
+          "numbering": [
+            1,
+            2,
+            5
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Read-only state",
+          "href": "#read-only-state",
+          "depth": 3,
+          "numbering": [
+            1,
+            2,
+            6
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Uncontrolled mode",
+          "href": "#uncontrolled-mode",
+          "depth": 3,
+          "numbering": [
+            1,
+            2,
+            7
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Controlled mode",
+          "href": "#controlled-mode",
+          "depth": 3,
+          "numbering": [
+            1,
+            2,
+            8
+          ],
+          "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": "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": "Password confirmation",
+          "href": "#password-confirmation",
+          "depth": 3,
+          "numbering": [
+            1,
+            6,
+            1
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Password strength indicator",
+          "href": "#password-strength-indicator",
+          "depth": 3,
+          "numbering": [
+            1,
+            6,
+            2
+          ],
+          "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 Element",
+          "href": "#testing-leading-element",
+          "depth": 3,
+          "numbering": [
+            1,
+            7,
+            4
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Testing Keyboard Navigation",
+          "href": "#testing-keyboard-navigation",
+          "depth": 3,
+          "numbering": [
+            1,
+            7,
+            5
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Testing Validation States",
+          "href": "#testing-validation-states",
+          "depth": 3,
+          "numbering": [
+            1,
+            7,
+            6
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Resources",
+          "href": "#resources",
+          "depth": 2,
+          "numbering": [
+            1,
+            8
+          ],
+          "parent": "root"
+        }
+      ]
+    },
+    "guidelines": {
+      "mdx": "\n## Guidelines\n\nPassword field guidelines provide designers with best practices for creating\nsecure and usable password entry, covering visual obscuring, clear labeling and\nvalidation, accessibility, and optional features like password visibility\ntoggles.\n\n### Best practices\n\n- **Clear labeling:** Always use a visible and descriptive label (e.g.,\n  \"Password\") placed outside the input field. Avoid using placeholder text as\n  the sole label.\n- **Visual obscuring:** Ensure entered characters are masked by default for\n  security.\n- **Password visibility toggle:** Provide a clear and easily accessible button\n  to allow users to temporarily view the password they've typed. This helps\n  prevent errors.\n- **Contextual help:** Display this requirement clearly upfront if there are\n  particular details that users need to be mindful of such as length or\n  inclusion of special characters.\n- **Inline validation:** When applicable, offer real-time feedback as users\n  type, indicating whether they meet the password requirements.\n- **Clear error handling:** If the entered password is incorrect, provide a\n  clear and helpful error message that doesn't reveal too much information about\n  why it's wrong.\n- **Password reset link:** Make the \"Forgot Password\" link easily discoverable\n  near the password input field.\n- **Allow pasting:** Generally, allow users to paste passwords from password\n  managers.\n- **Accessibility:** Ensure the password field and its associated elements\n  (label, toggle, error messages) are accessible to users with disabilities,\n  including screen reader compatibility and keyboard navigation.\n\n## Usage\n\nA password field provides a secure text input for users to enter confidential\ncredentials, visually obscuring the typed characters to protect them from being\nseen by others.\n\n> [!TIP]\\\n> When to use\n\n- **Authentication:** For securely entering credentials when logging into\n  accounts or accessing protected information.\n- **Account creation:** When users are setting up new accounts and need to\n  define a secret password.\n- **Sensitive data entry:** In situations where users need to input confidential\n  information that should not be visible to others.\n- **Confirmation of sensitive actions:** Occasionally used to re-authenticate\n  users before performing critical actions.\n\n> [!CAUTION]\\\n> When not to use\n\n- **Non-sensitive text entry:** For regular text input where privacy is not a\n  concern (e.g., usernames, search queries, messages). Use a standard text input\n  field instead.\n- **Displaying existing passwords:** Never use a password input to show a user\n  their currently saved password by default (unless using the \"Show password\"\n  toggle).\n- **Forced complexity rules without explanation:** Avoid requiring complex\n  passwords in a password input without clearly explaining the rules before the\n  user types.\n\n## Password labeling and messaging\n\nBest practices for password input labeling involve using clear, persistent\nlabels and providing concise, helpful error messages that guide users to meet\npassword requirements without revealing security vulnerabilities.\n\n> [!TIP]\\\n> **Do**\n>\n> - Do use clear and visible labels outside the input field.\n> - Do use inline validation to give immediate feedback.\n> - Do make the \"Forgot Password\" link easily accessible.\n\n```jsx live\nconst App = () => (\n  <FormField.Root>\n    <FormField.Label>Password</FormField.Label>\n    <FormField.Input>\n      <PasswordInput placeholder=\"P@33w0rd\" />\n    </FormField.Input>\n    <FormField.Description>Use at least 8 characters, including a number and a symbol.</FormField.Description>\n  </FormField.Root>\n);\n```\n\n> [!CAUTION]\\\n> **Don't**\n>\n> - Don't use placeholder text as the sole label.\n> - Don't provide overly specific error messages that could reveal security\n>   information (e.g., \"Your password needs a special character\").\n\n```jsx live\nconst App = () => (\n  <FormField.Root isInvalid w=\"1/2\">\n    <FormField.Input>\n      <PasswordInput value=\"password123\" />\n    </FormField.Input>\n    <FormField.Error>\n      You are missing a capital letter in your password\n    </FormField.Error>\n  </FormField.Root>\n);\n```\n\n## Password requirements and view\n\nPassword requirements clearly communicate the rules for creating a secure\npassword, while password viewing provides a temporary way for users to check\ntheir input for accuracy.\n\n> [!TIP]\\\n> **Do**\n>\n> - Do enforce a reasonable minimum password length.\n> - Do provide clear, upfront feedback on password requirements.\n> - If possible include real time validation for the requirements for password\n>   creation.\n> - Do mask the entered characters by default (e.g., with asterisks or dots).\n> - Do provide a \"Show Password\" toggle for users to verify their input.\n\n```jsx live\nconst App = () => (\n  <FormField.Root w=\"1/2\">\n    <FormField.Label>Password</FormField.Label>\n    <FormField.Input>\n      <PasswordInput />\n    </FormField.Input>\n    <FormField.Description>\n      Include 8-15 characters, at least one special character, and one uppercase\n      and lowercase letter.\n    </FormField.Description>\n  </FormField.Root>\n);\n```\n\n> [!CAUTION]\\\n> **Don't**\n>\n> - Don't enforce overly complex password rules without clear explanation.\n> - Don't use password fields for non-sensitive information.\n> - Don't auto-submit the form when the password field is filled.\n> - Don't reveal the password by default.\n> - Don't make the \"Show Password\" toggle difficult to find or use.\n\n![](/images/password-input/password-input-requirements-dont.png)\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": 2,
+          "numbering": [
+            1,
+            2
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Password labeling and messaging",
+          "href": "#password-labeling-and-messaging",
+          "depth": 2,
+          "numbering": [
+            1,
+            3
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Password requirements and view",
+          "href": "#password-requirements-and-view",
+          "depth": 2,
+          "numbering": [
+            1,
+            4
+          ],
+          "parent": "root"
+        }
+      ]
+    }
+  }
+}