@commercetools/nimbus-mcp 0.1.0 → 2.10.0

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

@@ -0,0 +1,319 @@
+{
+  "meta": {
+    "id": "Patterns-PasswordInputField",
+    "title": "Password input field",
+    "exportName": "PasswordInputField",
+    "description": "This pattern component integrates the PasswordInput within a FormField using a simple, consistent, and opinionated API.",
+    "order": 999,
+    "repoPath": "packages/nimbus/src/patterns/fields/password-input-field/password-input-field.mdx",
+    "menu": [
+      "Patterns",
+      "Fields",
+      "Password input field"
+    ],
+    "route": "patterns/fields/password-input-field",
+    "tags": [
+      "component",
+      "pattern",
+      "field",
+      "PasswordInput",
+      "PasswordInputField"
+    ],
+    "toc": [
+      {
+        "value": "Overview",
+        "href": "#overview",
+        "depth": 2,
+        "numbering": [
+          1,
+          1
+        ],
+        "parent": "root"
+      },
+      {
+        "value": "Resources",
+        "href": "#resources",
+        "depth": 3,
+        "numbering": [
+          1,
+          1,
+          1
+        ],
+        "parent": "root"
+      }
+    ],
+    "layout": "app-frame",
+    "tabs": [
+      {
+        "key": "overview",
+        "title": "Overview",
+        "order": 0
+      },
+      {
+        "key": "dev",
+        "title": "Implementation",
+        "order": 3
+      }
+    ]
+  },
+  "mdx": "\n## Overview\n\nPasswordInputField is a pattern component that combines the FormField wrapper with the PasswordInput component. This integration provides a complete form field experience including accessible labels, helper text descriptions, info popovers for supplementary information, and comprehensive validation and error handling, all through a simplified, opinionated API.\n\nIt maintains all functionality of the underlying PasswordInput, including the visibility toggle.\n\n### Resources\n\nFor detailed guidance on the individual components that make up this pattern, consult the component guidelines:\n\n- [PasswordInput Guidelines](/components/inputs/passwordinput) - Password input patterns, interaction guidelines, and accessibility standards\n- [FormField Guidelines](/components/inputs/formfield) - Label options, helper text, validation patterns, and form field accessibility\n- [Storybook](https://nimbus-storybook.vercel.app/?path=/docs/patterns-fields-passwordinputfield--docs)\n\n",
+  "views": {
+    "overview": {
+      "mdx": "\n## Overview\n\nPasswordInputField is a pattern component that combines the FormField wrapper with the PasswordInput component. This integration provides a complete form field experience including accessible labels, helper text descriptions, info popovers for supplementary information, and comprehensive validation and error handling, all through a simplified, opinionated API.\n\nIt maintains all functionality of the underlying PasswordInput, including the visibility toggle.\n\n### Resources\n\nFor detailed guidance on the individual components that make up this pattern, consult the component guidelines:\n\n- [PasswordInput Guidelines](/components/inputs/passwordinput) - Password input patterns, interaction guidelines, and accessibility standards\n- [FormField Guidelines](/components/inputs/formfield) - Label options, helper text, validation patterns, and form field accessibility\n- [Storybook](https://nimbus-storybook.vercel.app/?path=/docs/patterns-fields-passwordinputfield--docs)\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"
+        }
+      ]
+    },
+    "dev": {
+      "mdx": "\n## Comparison: field pattern vs manual composition\n\n**With PasswordInputField:**\n```tsx\n<PasswordInputField\n  label=\"Password\"\n  description=\"Enter a secure password\"\n  value={value}\n  onChange={setValue}\n  errors={errors}\n  touched={touched}\n  isRequired\n/>\n```\n\n**Manual composition:**\n```tsx\n<FormField.Root isInvalid={!!(errors && touched)} isRequired>\n  <FormField.Label>Password</FormField.Label>\n  <FormField.Input>\n    <PasswordInput\n      value={value}\n      onChange={setValue}\n      width=\"full\"\n    />\n  </FormField.Input>\n  <FormField.Description>\n    Enter a secure password\n  </FormField.Description>\n  {touched && errors && (\n    <FormField.Error>\n      <FieldErrors errors={errors} />\n    </FormField.Error>\n  )}\n</FormField.Root>\n```\n\n### When to use which\n\n**Use PasswordInputField when:**\n- Building standard authentication forms (login, signup, password change)\n- You want consistent field patterns across your app\n- You need built-in error handling with FieldErrors\n- You want to minimize boilerplate code\n\n**Use PasswordInput with manual FormField composition when:**\n- You need custom field layouts\n- You're building complex, non-standard forms\n- You need granular control over FormField sub-components\n- You require a different error handling implementation\n\n## Getting started\n\n### Import\n\n```tsx\nimport { PasswordInputField, type PasswordInputFieldProps } from '@commercetools/nimbus';\n```\n\n### Basic usage\n\nThe simplest implementation with a label and controlled state:\n\n```jsx live-dev\nconst App = () => {\n  const [value, setValue] = useState<string>('');\n\n  return (\n    <PasswordInputField\n      label=\"Password\"\n      value={value}\n      onChange={setValue}\n    />\n  );\n}\n```\n\n## Usage examples\n\n### With description\n\nAdd helper text below the input to provide context:\n\n```jsx live-dev\nconst App = () => {\n  const [value, setValue] = useState<string>('');\n\n  return (\n    <PasswordInputField\n      label=\"New Password\"\n      description=\"Password must be at least 8 characters long\"\n      value={value}\n      onChange={setValue}\n      placeholder=\"Enter password\"\n    />\n  );\n}\n```\n\n### With validation errors\n\nShow error messages when the field is touched and has validation errors:\n\n```jsx live-dev\nconst App = () => {\n  const [value, setValue] = useState<string>('');\n  const [touched, setTouched] = useState<boolean>(false);\n\n  // Simulate validation: require at least 8 characters\n  const errors = touched && value.length < 8 ? { tooShort: true } : undefined;\n\n  return (\n    <PasswordInputField\n      label=\"Password\"\n      description=\"Enter at least 8 characters\"\n      value={value}\n      onChange={setValue}\n      onBlur={() => setTouched(true)}\n      errors={errors}\n      touched={touched}\n      isRequired\n      renderError={(key) => key === 'tooShort' ? 'Password must be at least 8 characters' : null}\n    />\n  );\n}\n```\n\n**Note**: Errors only display when both `touched={true}` and `errors` exist. This prevents showing errors before the user interacts with the field.\n\n### With info popover\n\nProvide additional context through an info button and popover:\n\n```jsx live-dev\nconst App = () => {\n  const [value, setValue] = useState<string>('');\n\n  return (\n    <PasswordInputField\n      label=\"Secret Key\"\n      info=\"This key is used to encrypt your data locally. Do not lose it.\"\n      value={value}\n      onChange={setValue}\n    />\n  );\n}\n```\n\n### Required field\n\nMark fields as required with the `isRequired` prop:\n\n```jsx live-dev\nconst App = () => {\n  const [value, setValue] = useState<string>('');\n\n  return (\n    <PasswordInputField\n      label=\"Current Password\"\n      value={value}\n      onChange={setValue}\n      isRequired\n    />\n  );\n}\n```\n\n### Disabled state\n\nPrevent user interaction with the `isDisabled` prop:\n\n```jsx live-dev\nconst App = () => {\n  const [value, setValue] = useState<string>('Sup3rS3cr3t');\n\n  return (\n    <PasswordInputField\n      label=\"Password\"\n      value={value}\n      onChange={setValue}\n      isDisabled\n    />\n  );\n}\n```\n\n### Read-only state\n\nDisplay a non-editable value with the `isReadOnly` prop:\n\n```jsx live-dev\nconst App = () => {\n  const [value, setValue] = useState<string>('Sup3rS3cr3t');\n\n  return (\n    <PasswordInputField\n      label=\"Generated Password\"\n      description=\"Copy this password now, it won't be shown again\"\n      value={value}\n      onChange={setValue}\n      isReadOnly\n    />\n  );\n}\n```\n\n## Component requirements\n\n### Error handling\n\nPasswordInputField uses the `FieldErrors` component to display validation errors with built-in localized messages. For custom error messages, use the `renderError` prop.\n\n## Accessibility\n\nPasswordInputField provides comprehensive accessibility through [FormField](components/inputs/formfield):\n\n**Automatic ARIA relationships:**\n- Labels connected via `aria-labelledby`\n- Descriptions connected via `aria-describedby`\n- Error messages connected via `aria-describedby`\n- Required fields indicated with `aria-required`\n- Invalid state indicated with `aria-invalid`\n\n#### Password Visibility\nThe underlying `PasswordInput` component handles the \"Show/Hide Password\" toggle accessibly, ensuring the button has an appropriate label (aria-label) and state updates.\n\n#### Keyboard navigation\nThe component supports standard text input keyboard interaction:\n- `Tab` / `Shift+Tab`: Move focus to/from the input and the visibility toggle\n- `Enter` / `Space`: Toggle visibility when focused on the toggle button\n\n## Form integration\n\nPasswordInputField integrates seamlessly with Formik:\n\n```tsx\nimport { useFormik } from 'formik';\nimport { PasswordInputField, Button, Stack } from '@commercetools/nimbus';\n\nconst MyForm = () => {\n  const formik = useFormik({\n    initialValues: {\n      password: '',\n      confirmPassword: '',\n    },\n    validate: (values) => {\n      const errors = {};\n      if (!values.password) {\n        errors.password = { missing: true };\n      }\n      if (values.password !== values.confirmPassword) {\n        errors.confirmPassword = { custom: \"Passwords do not match\" };\n      }\n      return errors;\n    },\n    onSubmit: (values) => {\n      console.log('Submitted:', values);\n    },\n  });\n\n  return (\n    <form onSubmit={formik.handleSubmit}>\n      <Stack direction=\"column\" gap=\"400\">\n        <PasswordInputField\n          name=\"password\"\n          label=\"Password\"\n          value={formik.values.password}\n          onChange={(value) => formik.setFieldValue('password', value)}\n          onBlur={() => formik.setFieldTouched('password', true)}\n          errors={formik.errors.password}\n          touched={formik.touched.password}\n          isRequired\n        />\n        <PasswordInputField\n          name=\"confirmPassword\"\n          label=\"Confirm Password\"\n          value={formik.values.confirmPassword}\n          onChange={(value) => formik.setFieldValue('confirmPassword', value)}\n          onBlur={() => formik.setFieldTouched('confirmPassword', true)}\n          errors={formik.errors.confirmPassword}\n          touched={formik.touched.confirmPassword}\n          isRequired\n          renderError={(key) => key === 'custom' ? 'Passwords do not match' : null}\n        />\n        <Button type=\"submit\">Submit</Button>\n      </Stack>\n    </form>\n  );\n};\n```\n\n## Testing your implementation\n\n### Basic rendering tests\n\nVerify the component renders with expected elements:\n\n```tsx\nimport { render, screen } from '@testing-library/react';\nimport { PasswordInputField } from '@commercetools/nimbus';\n\ndescribe('PasswordInputField', () => {\n  it('renders label and input', () => {\n    render(\n      <PasswordInputField\n        label=\"Password\"\n        value=\"\"\n        onChange={() => {}}\n      />\n    );\n\n    // Verify label is rendered\n    expect(screen.getByText('Password')).toBeInTheDocument();\n\n    // Verify input is rendered (usually type=\"password\")\n    expect(screen.getByLabelText('Password')).toHaveAttribute('type', 'password');\n  });\n});\n```\n\n### Interaction tests\n\nTest user interactions with the component:\n\n```tsx\nimport { render, screen } from '@testing-library/react';\nimport userEvent from '@testing-library/user-event';\nimport { PasswordInputField } from '@commercetools/nimbus';\n\ndescribe('PasswordInputField interactions', () => {\n  it('calls onChange when user types', async () => {\n    const user = userEvent.setup();\n    const handleChange = jest.fn();\n\n    render(\n      <PasswordInputField\n        label=\"Password\"\n        value=\"\"\n        onChange={handleChange}\n      />\n    );\n\n    const input = screen.getByLabelText('Password');\n    await user.type(input, 'secure123');\n\n    expect(handleChange).toHaveBeenCalledTimes(9);\n    expect(handleChange).toHaveBeenLastCalledWith('secure123');\n  });\n});\n```\n\n",
+      "toc": [
+        {
+          "value": "Comparison: field pattern vs manual composition",
+          "href": "#comparison-field-pattern-vs-manual-composition",
+          "depth": 2,
+          "numbering": [
+            1,
+            1
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "When to use which",
+          "href": "#when-to-use-which",
+          "depth": 3,
+          "numbering": [
+            1,
+            1,
+            1
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Getting started",
+          "href": "#getting-started",
+          "depth": 2,
+          "numbering": [
+            1,
+            2
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Import",
+          "href": "#import",
+          "depth": 3,
+          "numbering": [
+            1,
+            2,
+            1
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Basic usage",
+          "href": "#basic-usage",
+          "depth": 3,
+          "numbering": [
+            1,
+            2,
+            2
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Usage examples",
+          "href": "#usage-examples",
+          "depth": 2,
+          "numbering": [
+            1,
+            3
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "With description",
+          "href": "#with-description",
+          "depth": 3,
+          "numbering": [
+            1,
+            3,
+            1
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "With validation errors",
+          "href": "#with-validation-errors",
+          "depth": 3,
+          "numbering": [
+            1,
+            3,
+            2
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "With info popover",
+          "href": "#with-info-popover",
+          "depth": 3,
+          "numbering": [
+            1,
+            3,
+            3
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Required field",
+          "href": "#required-field",
+          "depth": 3,
+          "numbering": [
+            1,
+            3,
+            4
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Disabled state",
+          "href": "#disabled-state",
+          "depth": 3,
+          "numbering": [
+            1,
+            3,
+            5
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Read-only state",
+          "href": "#read-only-state",
+          "depth": 3,
+          "numbering": [
+            1,
+            3,
+            6
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Component requirements",
+          "href": "#component-requirements",
+          "depth": 2,
+          "numbering": [
+            1,
+            4
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Error handling",
+          "href": "#error-handling",
+          "depth": 3,
+          "numbering": [
+            1,
+            4,
+            1
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Accessibility",
+          "href": "#accessibility",
+          "depth": 2,
+          "numbering": [
+            1,
+            5
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Password Visibility",
+          "href": "#password-visibility",
+          "depth": 4,
+          "numbering": [
+            1,
+            5,
+            1,
+            1
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Keyboard navigation",
+          "href": "#keyboard-navigation",
+          "depth": 4,
+          "numbering": [
+            1,
+            5,
+            1,
+            2
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Form integration",
+          "href": "#form-integration",
+          "depth": 2,
+          "numbering": [
+            1,
+            6
+          ],
+          "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"
+        }
+      ]
+    }
+  }
+}