@commercetools/nimbus-mcp 0.1.0 → 2.11.0

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

@@ -0,0 +1,721 @@
+{
+  "meta": {
+    "id": "Components-MoneyInput",
+    "title": "Money input",
+    "exportName": "MoneyInput",
+    "description": "A controlled input for money values that combines currency selection with amount input, supporting both standard and high-precision monetary values.",
+    "lifecycleState": "Stable",
+    "order": 999,
+    "repoPath": "packages/nimbus/src/components/money-input/money-input.mdx",
+    "menu": [
+      "Components",
+      "Inputs",
+      "Money input"
+    ],
+    "route": "components/inputs/money-input",
+    "tags": [
+      "component",
+      "input",
+      "currency",
+      "money"
+    ],
+    "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": "Anatomy",
+        "href": "#anatomy",
+        "depth": 3,
+        "numbering": [
+          1,
+          2,
+          1
+        ],
+        "parent": "root"
+      },
+      {
+        "value": "Multi-part functions",
+        "href": "#multi-part-functions",
+        "depth": 4,
+        "numbering": [
+          1,
+          2,
+          1,
+          1
+        ],
+        "parent": "root"
+      },
+      {
+        "value": "High-precision pricing",
+        "href": "#high-precision-pricing",
+        "depth": 4,
+        "numbering": [
+          1,
+          2,
+          1,
+          2
+        ],
+        "parent": "root"
+      },
+      {
+        "value": "Size",
+        "href": "#size",
+        "depth": 3,
+        "numbering": [
+          1,
+          2,
+          2
+        ],
+        "parent": "root"
+      },
+      {
+        "value": "Medium",
+        "href": "#medium",
+        "depth": 4,
+        "numbering": [
+          1,
+          2,
+          2,
+          1
+        ],
+        "parent": "root"
+      },
+      {
+        "value": "Small",
+        "href": "#small",
+        "depth": 4,
+        "numbering": [
+          1,
+          2,
+          2,
+          2
+        ],
+        "parent": "root"
+      }
+    ],
+    "figmaLink": "https://www.figma.com/design/AvtPX6g7OGGCRvNlatGOIY/NIMBUS-design-system?node-id=8463-23501&m=dev",
+    "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\nThe money input component combines a currency selector (a dropdown menu) and a\nnumerical input field into a single, cohesive unit, offering robust states like\ndefault, invalid, and disabled, alongside specialized handling for focused and\nhovered interactions.\n\n### Resources\n\nDeep dive into implementation details and access the Nimbus design library.\n\n[React Aria Docs](https://react-spectrum.adobe.com/react-aria/NumberField.html)\n[Figma library](https://www.figma.com/design/AvtPX6g7OGGCRvNlatGOIY/NIMBUS-design-system?node-id=8463-23501&m=dev)\n\n## Variables\n\nGet familiar with the features.\n\n### Anatomy\n\n#### Multi-part functions\n\nIn each localized money input, there is a dropdown to select the correct\ncurrency, a field that lets a user type in directly, and a stepper to allow for\nincremental numerical changes to the price shown within.\n\n```jsx live\nconst App = () => {\n  const [value, setValue] = React.useState({\n    amount: \"20.00\",\n    currencyCode: \"EUR\"\n  });\n\n  return (\n    <MoneyInput\n      value={value}\n      onValueChange={setValue}\n      currencies={[\"EUR\", \"USD\", \"GBP\", \"JPY\"]}\n    />\n  );\n}\n```\n\n#### High-precision pricing\n\nThis mode is essential for maintaining financial accuracy in large-scale or\ncomplex commercial systems.\n\n```jsx live\nconst App = () => {\n  const [value, setValue] = React.useState({\n    amount: \"20.12345\",\n    currencyCode: \"EUR\"\n  });\n\n  return (\n    <MoneyInput\n      value={value}\n      onValueChange={setValue}\n      currencies={[\"EUR\", \"USD\", \"GBP\"]}\n      hasHighPrecisionBadge\n    />\n  );\n}\n```\n\n### Size\n\n#### Medium\n\nDefault size common with other inputs.\n\n```jsx live\nconst App = () => {\n  const [value, setValue] = React.useState({\n    amount: \"20.00\",\n    currencyCode: \"EUR\"\n  });\n\n  return (\n    <MoneyInput\n      value={value}\n      onValueChange={setValue}\n      currencies={[\"EUR\", \"USD\", \"GBP\"]}\n      size=\"md\"\n    />\n  );\n}\n```\n\n#### Small\n\nCompact size for more condensed areas.\n\n```jsx live\nconst App = () => {\n  const [value, setValue] = React.useState({\n    amount: \"20.00\",\n    currencyCode: \"EUR\"\n  });\n\n  return (\n    <MoneyInput\n      value={value}\n      onValueChange={setValue}\n      currencies={[\"EUR\", \"USD\", \"GBP\"]}\n      size=\"sm\"\n    />\n  );\n}\n```\n",
+  "views": {
+    "overview": {
+      "mdx": "\n## Overview\n\nThe money input component combines a currency selector (a dropdown menu) and a\nnumerical input field into a single, cohesive unit, offering robust states like\ndefault, invalid, and disabled, alongside specialized handling for focused and\nhovered interactions.\n\n### Resources\n\nDeep dive into implementation details and access the Nimbus design library.\n\n[React Aria Docs](https://react-spectrum.adobe.com/react-aria/NumberField.html)\n[Figma library](https://www.figma.com/design/AvtPX6g7OGGCRvNlatGOIY/NIMBUS-design-system?node-id=8463-23501&m=dev)\n\n## Variables\n\nGet familiar with the features.\n\n### Anatomy\n\n#### Multi-part functions\n\nIn each localized money input, there is a dropdown to select the correct\ncurrency, a field that lets a user type in directly, and a stepper to allow for\nincremental numerical changes to the price shown within.\n\n```jsx live\nconst App = () => {\n  const [value, setValue] = React.useState({\n    amount: \"20.00\",\n    currencyCode: \"EUR\"\n  });\n\n  return (\n    <MoneyInput\n      value={value}\n      onValueChange={setValue}\n      currencies={[\"EUR\", \"USD\", \"GBP\", \"JPY\"]}\n    />\n  );\n}\n```\n\n#### High-precision pricing\n\nThis mode is essential for maintaining financial accuracy in large-scale or\ncomplex commercial systems.\n\n```jsx live\nconst App = () => {\n  const [value, setValue] = React.useState({\n    amount: \"20.12345\",\n    currencyCode: \"EUR\"\n  });\n\n  return (\n    <MoneyInput\n      value={value}\n      onValueChange={setValue}\n      currencies={[\"EUR\", \"USD\", \"GBP\"]}\n      hasHighPrecisionBadge\n    />\n  );\n}\n```\n\n### Size\n\n#### Medium\n\nDefault size common with other inputs.\n\n```jsx live\nconst App = () => {\n  const [value, setValue] = React.useState({\n    amount: \"20.00\",\n    currencyCode: \"EUR\"\n  });\n\n  return (\n    <MoneyInput\n      value={value}\n      onValueChange={setValue}\n      currencies={[\"EUR\", \"USD\", \"GBP\"]}\n      size=\"md\"\n    />\n  );\n}\n```\n\n#### Small\n\nCompact size for more condensed areas.\n\n```jsx live\nconst App = () => {\n  const [value, setValue] = React.useState({\n    amount: \"20.00\",\n    currencyCode: \"EUR\"\n  });\n\n  return (\n    <MoneyInput\n      value={value}\n      onValueChange={setValue}\n      currencies={[\"EUR\", \"USD\", \"GBP\"]}\n      size=\"sm\"\n    />\n  );\n}\n```\n",
+      "toc": [
+        {
+          "value": "Overview",
+          "href": "#overview",
+          "depth": 2,
+          "numbering": [
+            1,
+            1
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Resources",
+          "href": "#resources",
+          "depth": 3,
+          "numbering": [
+            1,
+            1,
+            1
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Variables",
+          "href": "#variables",
+          "depth": 2,
+          "numbering": [
+            1,
+            2
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Anatomy",
+          "href": "#anatomy",
+          "depth": 3,
+          "numbering": [
+            1,
+            2,
+            1
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Multi-part functions",
+          "href": "#multi-part-functions",
+          "depth": 4,
+          "numbering": [
+            1,
+            2,
+            1,
+            1
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "High-precision pricing",
+          "href": "#high-precision-pricing",
+          "depth": 4,
+          "numbering": [
+            1,
+            2,
+            1,
+            2
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Size",
+          "href": "#size",
+          "depth": 3,
+          "numbering": [
+            1,
+            2,
+            2
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Medium",
+          "href": "#medium",
+          "depth": 4,
+          "numbering": [
+            1,
+            2,
+            2,
+            1
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Small",
+          "href": "#small",
+          "depth": 4,
+          "numbering": [
+            1,
+            2,
+            2,
+            2
+          ],
+          "parent": "root"
+        }
+      ]
+    },
+    "a11y": {
+      "mdx": "\n## Accessibility\n\nAccessibility ensures that digital content and functionality are usable by\neveryone, including people with disabilities, by addressing visual, auditory,\ncognitive, and physical limitations.\n\n```jsx live\nconst App = () => {\n  const [value, setValue] = React.useState({\n    amount: \"20.00\",\n    currencyCode: \"EUR\"\n  });\n\n  return (\n    <MoneyInput\n      value={value}\n      onValueChange={setValue}\n      currencies={[\"EUR\", \"USD\", \"GBP\"]}\n    />\n  );\n}\n```\n\n### Accessibility standards\n\n- **Keyboard operability:** Ensure the user can navigate seamlessly between the\n  currency selector and the number input using the tab key.\n- **ARIA roles:** The currency selector should function as an accessible\n  dropdown/select menu, while the number input should use the appropriate number\n  input type.\n- **Error communication:** Validation errors must be announced to screen\n  readers. The invalid state should use `aria-invalid=\"true\"` on the input field\n  and link to the error message via `aria-describedby`.\n- **Contrast:** Ensure sufficient color contrast for all text, borders, and\n  icons, especially in the `invalid` and `disabled` states.\n- **Focus indication:** Maintain a strong, clear focus ring around both the\n  currency menu and the number input when active.\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 { MoneyInput, type MoneyInputProps, type MoneyInputValue } from '@commercetools/nimbus';\n```\n\n### Basic usage\n\nThe `MoneyInput` is a controlled component that manages both an amount and a currency code. It requires a `value` object and an `onValueChange` handler.\n\n```jsx live-dev\nconst App = () => {\n  const [value, setValue] = useState<MoneyInputValue>({\n    amount: \"\",\n    currencyCode: \"USD\"\n  });\n\n  return (\n    <Stack direction=\"column\" gap=\"400\">\n      <MoneyInput\n        value={value}\n        currencies={[\"USD\", \"EUR\", \"GBP\"]}\n        onValueChange={setValue}\n      />\n      <Text fontSize=\"sm\">\n        Value: {value.amount} {value.currencyCode}\n      </Text>\n    </Stack>\n  );\n}\n```\n\n## Usage examples\n\n### Size options\n\nThe `sm` and `md` size variants are available to match your interface density:\n\n```jsx live-dev\nconst App = () => {\n  const [value, setValue] = useState<MoneyInputValue>({\n    amount: \"123.45\",\n    currencyCode: \"USD\"\n  });\n\n  return (\n    <Stack direction=\"column\" gap=\"400\">\n      <MoneyInput\n        size=\"sm\"\n        value={value}\n        currencies={[\"USD\", \"EUR\"]}\n        onValueChange={setValue}\n      />\n      <MoneyInput\n        size=\"md\"\n        value={value}\n        currencies={[\"USD\", \"EUR\"]}\n        onValueChange={setValue}\n      />\n    </Stack>\n  );\n}\n```\n\n### Currency configuration\n\nThe `currencies` prop controls the available options in the dropdown. If no currencies are provided (or an empty array is passed), the component renders a static label for the currency code instead of a dropdown.\n\n```jsx live-dev\nconst App = () => {\n  const [value1, setValue1] = useState<MoneyInputValue>({\n    amount: \"100.00\",\n    currencyCode: \"USD\"\n  });\n\n  const [value2, setValue2] = useState<MoneyInputValue>({\n    amount: \"50.00\",\n    currencyCode: \"EUR\"\n  });\n\n  return (\n    <Stack direction=\"column\" gap=\"400\">\n      <Text fontWeight=\"bold\">Multiple currencies (Dropdown)</Text>\n      <MoneyInput\n        value={value1}\n        currencies={[\"USD\", \"EUR\", \"GBP\", \"JPY\"]}\n        onValueChange={setValue1}\n      />\n\n      <Text fontWeight=\"bold\">No currencies list (Static Label)</Text>\n      <MoneyInput\n        value={value2}\n        currencies={[]}\n        onValueChange={setValue2}\n      />\n    </Stack>\n  );\n}\n```\n\n### High precision support\n\nThe `MoneyInput` automatically detects high precision values (more decimal places than standard for the currency) and displays a \"High Precision\" badge. This feature can be toggled with `hasHighPrecisionBadge`.\n\n```jsx live-dev\nconst App = () => {\n  const [value, setValue] = useState<MoneyInputValue>({\n    amount: \"123.4567\",\n    currencyCode: \"USD\"\n  });\n\n  return (\n    <Stack direction=\"column\" gap=\"400\">\n      <Text fontSize=\"sm\">\n        Try entering more than 2 decimal places for USD (e.g., 123.4567)\n      </Text>\n      <MoneyInput\n        value={value}\n        currencies={[\"USD\", \"EUR\"]}\n        onValueChange={setValue}\n        hasHighPrecisionBadge={true}\n      />\n    </Stack>\n  );\n}\n```\n\n### State variations\n\nThe component supports standard interactive states including disabled, read-only, and invalid.\n\n```jsx live-dev\nconst App = () => {\n  const value = { amount: \"123.45\", currencyCode: \"USD\" };\n\n  return (\n    <Stack direction=\"column\" gap=\"400\">\n      <MoneyInput\n        aria-label=\"Disabled\"\n        value={value}\n        currencies={[\"USD\"]}\n        isDisabled\n      />\n      <MoneyInput\n        aria-label=\"Read-only\"\n        value={value}\n        currencies={[\"USD\"]}\n        isReadOnly\n      />\n      <MoneyInput\n        aria-label=\"Invalid\"\n        value={value}\n        currencies={[\"USD\"]}\n        isInvalid\n      />\n    </Stack>\n  );\n}\n```\n\n### Currency input control\n\nUse `isCurrencyInputDisabled` to disable only the currency selector while keeping the amount input editable. This is useful when the currency is predetermined but the amount should still be modifiable.\n\n```jsx live-dev\nconst App = () => {\n  const [value, setValue] = useState<MoneyInputValue>({\n    amount: \"123.45\",\n    currencyCode: \"USD\"\n  });\n\n  return (\n    <Stack direction=\"column\" gap=\"400\">\n      <Text fontWeight=\"bold\">Currency selector enabled</Text>\n      <MoneyInput\n        aria-label=\"Price with currency selection\"\n        value={value}\n        currencies={[\"USD\", \"EUR\", \"GBP\"]}\n        onValueChange={setValue}\n      />\n\n      <Text fontWeight=\"bold\">Currency selector disabled</Text>\n      <MoneyInput\n        aria-label=\"Price with fixed currency\"\n        value={value}\n        currencies={[\"USD\", \"EUR\", \"GBP\"]}\n        onValueChange={setValue}\n        isCurrencyInputDisabled\n      />\n\n      <Text fontSize=\"sm\">\n        Current value: {value.amount} {value.currencyCode}\n      </Text>\n    </Stack>\n  );\n}\n```\n\n### Event handlers\n\nThe component provides granular event handlers for modern integration patterns:\n- `onValueChange`: Called when either amount or currency changes (recommended)\n- `onAmountChange`: Called when only the amount changes\n- `onCurrencyChange`: Called when only the currency changes\n\n```jsx live-dev\nconst App = () => {\n  const [value, setValue] = useState<MoneyInputValue>({\n    amount: \"\",\n    currencyCode: \"USD\"\n  });\n  const [lastAmountChange, setLastAmountChange] = useState<string>(\"-\");\n  const [lastCurrencyChange, setLastCurrencyChange] = useState<string>(\"-\");\n\n  return (\n    <Stack direction=\"column\" gap=\"400\">\n      <MoneyInput\n        value={value}\n        currencies={[\"USD\", \"EUR\", \"GBP\"]}\n        onValueChange={(newValue) => {\n          setValue(newValue);\n        }}\n        onAmountChange={(amount) => setLastAmountChange(amount || \"(empty)\")}\n        onCurrencyChange={(code) => setLastCurrencyChange(code)}\n      />\n      <Stack direction=\"column\" gap=\"200\">\n        <Text fontSize=\"sm\">Current value: {value.amount} {value.currencyCode}</Text>\n        <Text fontSize=\"sm\">Last amount change: {lastAmountChange}</Text>\n        <Text fontSize=\"sm\">Last currency change: {lastCurrencyChange}</Text>\n      </Stack>\n    </Stack>\n  );\n}\n```\n\n## Component requirements\n\n### Value type requirements\n\nThe `value` prop must be an object matching the `MoneyInputValue` interface:\n\n```tsx\ntype MoneyInputValue = {\n  amount: string;\n  currencyCode: string;\n};\n```\n\nNote that `amount` is a string to preserve precision and avoid floating-point errors.\n\n## Accessibility\n\nThe `MoneyInput` handles accessibility requirements for its internal input and select components. However, you must always associate a label with the component.\n\nUsing `aria-label`:\n\n```tsx\n<MoneyInput\n  aria-label=\"Product Price\"\n  value={value}\n  // ...\n/>\n```\n\nUsing `aria-labelledby`:\n\n```tsx\n<label id=\"price-label\">Product Price</label>\n<MoneyInput\n  aria-labelledby=\"price-label\"\n  value={value}\n  // ...\n/>\n```\n\nIf your use case requires tracking and analytics for this component, it is good practice to add a **persistent**, **unique** id to the component:\n\n```tsx\nconst PERSISTENT_ID = \"product-price-input\";\n\nexport const Example = () => (\n  <MoneyInput id={PERSISTENT_ID} value={value} />\n);\n```\n\n#### Keyboard navigation\n\nThe component supports full keyboard interaction:\n- `Tab`: Moves focus between the currency dropdown and the amount input.\n- `Arrow Keys` (in Dropdown): Navigates between currency options.\n- `Enter` / `Space` (in Dropdown): Selects the currency.\n- `Arrow Keys` (in Input): Adjusts the cursor position.\n\n## API reference\n\n<PropsTable id=\"MoneyInput\" />\n\n## Common patterns\n\n### Working with locales\n\nThe `MoneyInput` uses the application's locale (via `NimbusI18nProvider`) to format numbers appropriately (e.g., using commas for decimals in German).\n\n```jsx live-dev\nconst App = () => {\n  // Note: In a real app, NimbusI18nProvider would wrap the entire app\n  // This example simulates different locales\n  return (\n    <Stack direction=\"column\" gap=\"400\">\n      <Text fontWeight=\"bold\">German Locale (de-DE)</Text>\n      <NimbusI18nProvider locale=\"de-DE\">\n        <MoneyInput\n          value={{ amount: \"1234.56\", currencyCode: \"EUR\" }}\n          currencies={[\"EUR\"]}\n          isReadOnly\n        />\n      </NimbusI18nProvider>\n\n      <Text fontWeight=\"bold\">US Locale (en-US)</Text>\n      <NimbusI18nProvider locale=\"en-US\">\n        <MoneyInput\n          value={{ amount: \"1234.56\", currencyCode: \"USD\" }}\n          currencies={[\"USD\"]}\n          isReadOnly\n        />\n      </NimbusI18nProvider>\n    </Stack>\n  );\n}\n```\n\n## Static utility methods\n\nThe MoneyInput component provides static utility methods for advanced use cases like testing, API integration, and form validation. These methods are particularly useful for compatibility and working with backend data formats.\n\n### ID helper methods\n\nThese methods generate element IDs for DOM access and testing:\n\n#### getAmountInputId\n\nReturns the ID of the amount input element within a MoneyInput.\n\n```tsx\n// Usage in testing or DOM manipulation\nconst amountInputId = MoneyInput.getAmountInputId(\"product-price\");\n// Returns: \"product-price.amount\"\n\n// Example: Focus the amount input programmatically\nconst amountInput = document.getElementById(amountInputId);\namountInput?.focus();\n```\n\n#### getCurrencyDropdownId\n\nReturns the ID of the currency dropdown element within a MoneyInput.\n\n```tsx\n// Usage in testing or DOM manipulation\nconst currencyDropdownId = MoneyInput.getCurrencyDropdownId(\"product-price\");\n// Returns: \"product-price.currencyCode\"\n\n// Example: Access the currency dropdown in tests\nconst currencyDropdown = document.getElementById(currencyDropdownId);\n```\n\n**Use case:** These methods are helpful when writing integration tests or when you need to programmatically interact with specific parts of the MoneyInput component.\n\n### Data transformation methods\n\nThese methods convert between UI format (`MoneyInputValue`) and API format (`MoneyValue`):\n\n#### convertToMoneyValue\n\nConverts a MoneyInputValue (UI format with string amount) to MoneyValue (API format with centAmount).\n\n```tsx\nimport { MoneyInput, type MoneyInputValue, type MoneyValue } from '@commercetools/nimbus';\n\n// Convert UI value to API format before submission\nconst uiValue: MoneyInputValue = {\n  amount: \"123.45\",\n  currencyCode: \"USD\"\n};\n\nconst apiValue: MoneyValue = MoneyInput.convertToMoneyValue(uiValue, \"en-US\");\n// Returns: {\n//   type: \"centPrecision\",\n//   currencyCode: \"USD\",\n//   centAmount: 12345,\n//   fractionDigits: 2\n// }\n\n// For high precision values\nconst highPrecisionValue: MoneyInputValue = {\n  amount: \"123.4567\",\n  currencyCode: \"USD\"\n};\n\nconst apiHighPrecision: MoneyValue = MoneyInput.convertToMoneyValue(\n  highPrecisionValue,\n  \"en-US\"\n);\n// Returns: {\n//   type: \"highPrecision\",\n//   currencyCode: \"USD\",\n//   centAmount: 12346, // Rounded to standard precision\n//   preciseAmount: 1234567,\n//   fractionDigits: 4\n// }\n```\n\n#### parseMoneyValue\n\nConverts a MoneyValue (API format) to MoneyInputValue (UI format) for display in the component.\n\n```tsx\nimport { MoneyInput, type MoneyValue, type MoneyInputValue } from '@commercetools/nimbus';\n\n// Convert API data to UI format when loading\nconst apiValue: MoneyValue = {\n  type: \"centPrecision\",\n  currencyCode: \"EUR\",\n  centAmount: 9999,\n  fractionDigits: 2\n};\n\nconst uiValue: MoneyInputValue = MoneyInput.parseMoneyValue(apiValue, \"en-US\");\n// Returns: {\n//   amount: \"99.99\",\n//   currencyCode: \"EUR\"\n// }\n\n// Example: Loading data from API\nconst ProductPriceEditor = ({ productId }: { productId: string }) => {\n  const [value, setValue] = useState<MoneyInputValue>({ amount: \"\", currencyCode: \"USD\" });\n\n  useEffect(() => {\n    async function loadProduct() {\n      const product = await fetchProduct(productId);\n      // Convert API MoneyValue to UI format\n      const uiValue = MoneyInput.parseMoneyValue(product.price, navigator.language);\n      setValue(uiValue);\n    }\n    loadProduct();\n  }, [productId]);\n\n  return (\n    <MoneyInput\n      value={value}\n      currencies={[\"USD\", \"EUR\", \"GBP\"]}\n      onValueChange={setValue}\n      aria-label=\"Product Price\"\n    />\n  );\n};\n```\n\n**Use case:** These methods enable seamless integration with commercetools APIs and other backends that use the MoneyValue format with `centAmount` and `preciseAmount` fields.\n\n### Validation methods\n\nThese methods validate MoneyInputValue data:\n\n#### isEmpty\n\nChecks if a MoneyInputValue is empty (missing amount or currency).\n\n```tsx\nimport { MoneyInput, type MoneyInputValue } from '@commercetools/nimbus';\n\n// Check before form submission\nconst handleSubmit = (value: MoneyInputValue) => {\n  if (MoneyInput.isEmpty(value)) {\n    alert(\"Please enter a price\");\n    return;\n  }\n\n  // Proceed with submission\n  submitPrice(value);\n};\n\n// Example values\nMoneyInput.isEmpty({ amount: \"\", currencyCode: \"USD\" }); // true\nMoneyInput.isEmpty({ amount: \"100\", currencyCode: \"\" }); // true\nMoneyInput.isEmpty({ amount: \"100\", currencyCode: \"USD\" }); // false\n```\n\n#### isHighPrecision\n\nChecks if a MoneyInputValue exceeds the standard precision for its currency.\n\n```tsx\nimport { MoneyInput, type MoneyInputValue } from '@commercetools/nimbus';\n\n// Check if value needs high precision handling\nconst value: MoneyInputValue = {\n  amount: \"123.4567\",\n  currencyCode: \"USD\" // USD standard precision is 2\n};\n\nconst needsHighPrecision = MoneyInput.isHighPrecision(value, \"en-US\");\n// Returns: true (4 decimals > 2 standard for USD)\n\n// Example: Warn users about precision\nconst PriceInput = () => {\n  const [value, setValue] = useState<MoneyInputValue>({\n    amount: \"\",\n    currencyCode: \"USD\"\n  });\n\n  const showPrecisionWarning = MoneyInput.isHighPrecision(value, navigator.language);\n\n  return (\n    <Stack direction=\"column\" gap=\"200\">\n      <MoneyInput\n        value={value}\n        currencies={[\"USD\", \"EUR\"]}\n        onValueChange={setValue}\n        aria-label=\"Price\"\n      />\n      {showPrecisionWarning && (\n        <Text color=\"warning\" fontSize=\"sm\">\n          This price uses high precision formatting\n        </Text>\n      )}\n    </Stack>\n  );\n};\n```\n\n**Use case:** These methods help validate form data before submission and provide appropriate user feedback.\n\n### Type definitions\n\nWhen using static methods, you'll need these type imports:\n\n```tsx\nimport {\n  MoneyInput,\n  type MoneyInputValue,  // UI format: { amount: string, currencyCode: string }\n  type MoneyValue,       // API format: { centAmount: number, currencyCode, ... }\n  type CurrencyCode,     // Valid currency codes\n} from '@commercetools/nimbus';\n```\n\n## Testing your implementation\n\nThese examples demonstrate how to test your implementation when using MoneyInput 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, waitFor, within } from \"@testing-library/react\";\nimport userEvent from \"@testing-library/user-event\";\nimport { MoneyInput, NimbusProvider } from \"@commercetools/nimbus\";\nimport type { MoneyInputValue } from \"./money-input.types\";\n\ndescribe(\"MoneyInput - Basic rendering\", () => {\n  it(\"renders with initial value\", () => {\n    const value: MoneyInputValue = { amount: \"100.00\", currencyCode: \"USD\" };\n    render(\n      <NimbusProvider>\n        <MoneyInput\n          value={value}\n          currencies={[\"USD\", \"EUR\"]}\n          aria-label=\"Price\"\n        />\n      </NimbusProvider>\n    );\n\n    // NumberInput displays formatted numeric values\n    const input = screen.getByRole(\"textbox\");\n    expect(input).toHaveValue(\"100.00\");\n\n    // Currency button should be visible\n    expect(\n      screen.getByRole(\"button\", { name: /USD.*Currency/i })\n    ).toBeInTheDocument();\n  });\n\n  it(\"renders with multiple currencies in dropdown\", () => {\n    const value: MoneyInputValue = { amount: \"50.00\", currencyCode: \"EUR\" };\n    render(\n      <NimbusProvider>\n        <MoneyInput\n          value={value}\n          currencies={[\"USD\", \"EUR\", \"GBP\"]}\n          aria-label=\"Price\"\n        />\n      </NimbusProvider>\n    );\n\n    // Currency button should be visible\n    expect(\n      screen.getByRole(\"button\", { name: /EUR.*Currency/i })\n    ).toBeInTheDocument();\n\n    // Amount input should be present\n    const input = screen.getByRole(\"textbox\");\n    expect(input).toBeInTheDocument();\n  });\n\n  it(\"renders static currency label when no currencies provided\", () => {\n    const value: MoneyInputValue = { amount: \"100.00\", currencyCode: \"USD\" };\n    render(\n      <NimbusProvider>\n        <MoneyInput value={value} currencies={[]} aria-label=\"Price\" />\n      </NimbusProvider>\n    );\n\n    // Should show static label text\n    expect(screen.getByText(\"USD\")).toBeInTheDocument();\n\n    // No currency button should exist\n    expect(\n      screen.queryByRole(\"button\", { name: /Currency/i })\n    ).not.toBeInTheDocument();\n\n    // Amount input should be present\n    const input = screen.getByRole(\"textbox\");\n    expect(input).toBeInTheDocument();\n  });\n});\n```\n\n### Interaction Tests\n\nTest user interactions with amount input and currency selector\n\n```tsx\nimport { describe, it, expect, vi } from \"vitest\";\nimport { render, screen, waitFor, within } from \"@testing-library/react\";\nimport userEvent from \"@testing-library/user-event\";\nimport { MoneyInput, NimbusProvider } from \"@commercetools/nimbus\";\nimport type { MoneyInputValue } from \"./money-input.types\";\n\ndescribe(\"MoneyInput - Interactions\", () => {\n  it(\"updates amount when user types\", async () => {\n    const user = userEvent.setup();\n    const handleChange = vi.fn();\n    const value: MoneyInputValue = { amount: \"\", currencyCode: \"USD\" };\n\n    render(\n      <NimbusProvider>\n        <MoneyInput\n          value={value}\n          currencies={[\"USD\"]}\n          onValueChange={handleChange}\n          aria-label=\"Price\"\n        />\n      </NimbusProvider>\n    );\n\n    const input = screen.getByRole(\"textbox\");\n    await user.clear(input);\n    await user.type(input, \"50.00\");\n    await user.tab(); // Blur the input to trigger final change\n\n    // onValueChange should be called with updated amount\n    expect(handleChange).toHaveBeenCalled();\n    expect(handleChange).toHaveBeenCalledWith(\n      expect.objectContaining({\n        amount: expect.stringContaining(\"50\"),\n        currencyCode: \"USD\",\n      })\n    );\n  });\n\n  it(\"updates currency when user selects from dropdown\", async () => {\n    const user = userEvent.setup();\n    const handleChange = vi.fn();\n    const value: MoneyInputValue = { amount: \"100\", currencyCode: \"USD\" };\n\n    render(\n      <NimbusProvider>\n        <MoneyInput\n          value={value}\n          currencies={[\"USD\", \"EUR\", \"GBP\"]}\n          onValueChange={handleChange}\n          aria-label=\"Price\"\n        />\n      </NimbusProvider>\n    );\n\n    // Click on the currency button to open dropdown\n    const trigger = screen.getByRole(\"button\", { name: /USD.*Currency/i });\n    await user.click(trigger);\n\n    // Wait for dropdown to appear and select EUR\n    await waitFor(() => {\n      const listbox = within(document.body).getByRole(\"listbox\");\n      expect(listbox).toBeInTheDocument();\n    });\n\n    const eurOption = within(document.body).getByRole(\"option\", {\n      name: \"EUR\",\n    });\n    await user.click(eurOption);\n\n    // Verify currency change handler was called\n    expect(handleChange).toHaveBeenCalledWith(\n      expect.objectContaining({\n        amount: \"100\",\n        currencyCode: \"EUR\",\n      })\n    );\n  });\n\n  it(\"calls onAmountChange when amount changes\", async () => {\n    const user = userEvent.setup();\n    const handleAmountChange = vi.fn();\n    const value: MoneyInputValue = { amount: \"\", currencyCode: \"USD\" };\n\n    render(\n      <NimbusProvider>\n        <MoneyInput\n          value={value}\n          currencies={[\"USD\"]}\n          onAmountChange={handleAmountChange}\n          aria-label=\"Price\"\n        />\n      </NimbusProvider>\n    );\n\n    const input = screen.getByRole(\"textbox\");\n    await user.clear(input);\n    await user.type(input, \"123\");\n    await user.tab(); // Blur the input to trigger change\n\n    expect(handleAmountChange).toHaveBeenCalled();\n  });\n\n  it(\"calls onCurrencyChange when currency changes\", async () => {\n    const user = userEvent.setup();\n    const handleCurrencyChange = vi.fn();\n    const value: MoneyInputValue = { amount: \"100\", currencyCode: \"USD\" };\n\n    render(\n      <NimbusProvider>\n        <MoneyInput\n          value={value}\n          currencies={[\"USD\", \"EUR\"]}\n          onCurrencyChange={handleCurrencyChange}\n          aria-label=\"Price\"\n        />\n      </NimbusProvider>\n    );\n\n    // Open dropdown and select EUR\n    await user.click(screen.getByRole(\"button\", { name: /USD.*Currency/i }));\n\n    await waitFor(() => {\n      const listbox = within(document.body).getByRole(\"listbox\");\n      expect(listbox).toBeInTheDocument();\n    });\n\n    const eurOption = within(document.body).getByRole(\"option\", {\n      name: \"EUR\",\n    });\n    await user.click(eurOption);\n\n    expect(handleCurrencyChange).toHaveBeenCalledWith(\"EUR\");\n  });\n});\n```\n\n### Testing High Precision Support\n\nTest high precision badge display and behavior\n\n```tsx\nimport { describe, it, expect, vi } from \"vitest\";\nimport { render, screen, waitFor, within } from \"@testing-library/react\";\nimport userEvent from \"@testing-library/user-event\";\nimport { MoneyInput, NimbusProvider } from \"@commercetools/nimbus\";\nimport type { MoneyInputValue } from \"./money-input.types\";\n\ndescribe(\"MoneyInput - High precision\", () => {\n  it(\"shows high precision badge for values exceeding standard precision\", () => {\n    // USD typically has 2 decimal places, 4 decimals is high precision\n    const value: MoneyInputValue = {\n      amount: \"100.1234\",\n      currencyCode: \"USD\",\n    };\n\n    render(\n      <NimbusProvider>\n        <MoneyInput\n          value={value}\n          currencies={[\"USD\"]}\n          hasHighPrecisionBadge={true}\n          aria-label=\"Price\"\n        />\n      </NimbusProvider>\n    );\n\n    const badge = screen.getByLabelText(/High precision/i);\n    expect(badge).toBeInTheDocument();\n  });\n\n  it(\"does not show badge for standard precision\", () => {\n    // USD with standard 2 decimal places\n    const value: MoneyInputValue = { amount: \"100.12\", currencyCode: \"USD\" };\n\n    render(\n      <NimbusProvider>\n        <MoneyInput\n          value={value}\n          currencies={[\"USD\"]}\n          hasHighPrecisionBadge={true}\n          aria-label=\"Price\"\n        />\n      </NimbusProvider>\n    );\n\n    const badge = screen.queryByLabelText(/High precision/i);\n    expect(badge).not.toBeInTheDocument();\n  });\n\n  it(\"hides badge when hasHighPrecisionBadge is false\", () => {\n    const value: MoneyInputValue = {\n      amount: \"100.1234\",\n      currencyCode: \"USD\",\n    };\n\n    render(\n      <NimbusProvider>\n        <MoneyInput\n          value={value}\n          currencies={[\"USD\"]}\n          hasHighPrecisionBadge={false}\n          aria-label=\"Price\"\n        />\n      </NimbusProvider>\n    );\n\n    const badge = screen.queryByLabelText(/High precision/i);\n    expect(badge).not.toBeInTheDocument();\n  });\n});\n```\n\n### Testing Validation States\n\nTest disabled, read-only, invalid, and required states\n\n```tsx\nimport { describe, it, expect, vi } from \"vitest\";\nimport { render, screen, waitFor, within } from \"@testing-library/react\";\nimport userEvent from \"@testing-library/user-event\";\nimport { MoneyInput, NimbusProvider } from \"@commercetools/nimbus\";\nimport type { MoneyInputValue } from \"./money-input.types\";\n\ndescribe(\"MoneyInput - Validation states\", () => {\n  it(\"renders disabled state\", () => {\n    const value: MoneyInputValue = { amount: \"100\", currencyCode: \"USD\" };\n\n    render(\n      <NimbusProvider>\n        <MoneyInput\n          value={value}\n          currencies={[\"USD\", \"EUR\"]}\n          isDisabled\n          aria-label=\"Price\"\n        />\n      </NimbusProvider>\n    );\n\n    const input = screen.getByRole(\"textbox\");\n    expect(input).toBeDisabled();\n\n    // Currency button should also be disabled\n    const currencyButton = screen.getByRole(\"button\", {\n      name: /USD.*Currency/i,\n    });\n    expect(currencyButton).toBeDisabled();\n  });\n\n  it(\"renders read-only state\", () => {\n    const value: MoneyInputValue = { amount: \"100\", currencyCode: \"USD\" };\n\n    render(\n      <NimbusProvider>\n        <MoneyInput\n          value={value}\n          currencies={[\"USD\", \"EUR\"]}\n          isReadOnly\n          aria-label=\"Price\"\n        />\n      </NimbusProvider>\n    );\n\n    const input = screen.getByRole(\"textbox\");\n    expect(input).toHaveAttribute(\"readonly\");\n  });\n\n  it(\"renders invalid state\", () => {\n    const value: MoneyInputValue = { amount: \"invalid\", currencyCode: \"USD\" };\n\n    render(\n      <NimbusProvider>\n        <MoneyInput\n          value={value}\n          currencies={[\"USD\"]}\n          isInvalid\n          aria-label=\"Price\"\n        />\n      </NimbusProvider>\n    );\n\n    const input = screen.getByRole(\"textbox\");\n    expect(input).toHaveAttribute(\"aria-invalid\", \"true\");\n  });\n\n  it(\"renders required state\", () => {\n    const value: MoneyInputValue = { amount: \"\", currencyCode: \"USD\" };\n\n    render(\n      <NimbusProvider>\n        <MoneyInput\n          value={value}\n          currencies={[\"USD\"]}\n          isRequired\n          aria-label=\"Price\"\n        />\n      </NimbusProvider>\n    );\n\n    const input = screen.getByRole(\"textbox\");\n    expect(input).toHaveAttribute(\"aria-required\", \"true\");\n  });\n\n  it(\"disables only currency selector with isCurrencyInputDisabled\", () => {\n    const value: MoneyInputValue = { amount: \"100\", currencyCode: \"USD\" };\n\n    render(\n      <NimbusProvider>\n        <MoneyInput\n          value={value}\n          currencies={[\"USD\", \"EUR\"]}\n          isCurrencyInputDisabled\n          aria-label=\"Price\"\n        />\n      </NimbusProvider>\n    );\n\n    // Amount input should be enabled\n    const input = screen.getByRole(\"textbox\");\n    expect(input).not.toBeDisabled();\n\n    // Currency button should be disabled\n    const currencyButton = screen.getByRole(\"button\", {\n      name: /USD.*Currency/i,\n    });\n    expect(currencyButton).toBeDisabled();\n  });\n});\n```\n\n### Testing Currency Configuration\n\nTest different currency list configurations\n\n```tsx\nimport { describe, it, expect, vi } from \"vitest\";\nimport { render, screen, waitFor, within } from \"@testing-library/react\";\nimport userEvent from \"@testing-library/user-event\";\nimport { MoneyInput, NimbusProvider } from \"@commercetools/nimbus\";\nimport type { MoneyInputValue } from \"./money-input.types\";\n\ndescribe(\"MoneyInput - Currency configuration\", () => {\n  it(\"renders dropdown when multiple currencies provided\", () => {\n    const value: MoneyInputValue = { amount: \"100\", currencyCode: \"USD\" };\n\n    render(\n      <NimbusProvider>\n        <MoneyInput\n          value={value}\n          currencies={[\"USD\", \"EUR\", \"GBP\"]}\n          aria-label=\"Price\"\n        />\n      </NimbusProvider>\n    );\n\n    // Verify currency button is displayed\n    expect(\n      screen.getByRole(\"button\", { name: /USD.*Currency/i })\n    ).toBeInTheDocument();\n  });\n\n  it(\"renders static label when empty currencies array\", () => {\n    const value: MoneyInputValue = { amount: \"100\", currencyCode: \"EUR\" };\n\n    render(\n      <NimbusProvider>\n        <MoneyInput value={value} currencies={[]} aria-label=\"Price\" />\n      </NimbusProvider>\n    );\n\n    // Static label present\n    expect(screen.getByText(\"EUR\")).toBeInTheDocument();\n  });\n\n  it(\"renders static label when currencies prop omitted\", () => {\n    const value: MoneyInputValue = { amount: \"100\", currencyCode: \"JPY\" };\n\n    render(\n      <NimbusProvider>\n        <MoneyInput value={value} aria-label=\"Price\" />\n      </NimbusProvider>\n    );\n\n    expect(screen.getByText(\"JPY\")).toBeInTheDocument();\n  });\n});\n```\n\n\n## Resources\n\n- [Storybook](https://nimbus-storybook.vercel.app/?path=/docs/components-moneyinput--docs)\n- [React Aria NumberField](https://react-spectrum.adobe.com/react-aria/NumberField.html)\n- [React Aria Select](https://react-spectrum.adobe.com/react-aria/Select.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": "Currency configuration",
+          "href": "#currency-configuration",
+          "depth": 3,
+          "numbering": [
+            1,
+            2,
+            2
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "High precision support",
+          "href": "#high-precision-support",
+          "depth": 3,
+          "numbering": [
+            1,
+            2,
+            3
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "State variations",
+          "href": "#state-variations",
+          "depth": 3,
+          "numbering": [
+            1,
+            2,
+            4
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Currency input control",
+          "href": "#currency-input-control",
+          "depth": 3,
+          "numbering": [
+            1,
+            2,
+            5
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Event handlers",
+          "href": "#event-handlers",
+          "depth": 3,
+          "numbering": [
+            1,
+            2,
+            6
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Component requirements",
+          "href": "#component-requirements",
+          "depth": 2,
+          "numbering": [
+            1,
+            3
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Value type requirements",
+          "href": "#value-type-requirements",
+          "depth": 3,
+          "numbering": [
+            1,
+            3,
+            1
+          ],
+          "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": "Working with locales",
+          "href": "#working-with-locales",
+          "depth": 3,
+          "numbering": [
+            1,
+            6,
+            1
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Static utility methods",
+          "href": "#static-utility-methods",
+          "depth": 2,
+          "numbering": [
+            1,
+            7
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "ID helper methods",
+          "href": "#id-helper-methods",
+          "depth": 3,
+          "numbering": [
+            1,
+            7,
+            1
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "getAmountInputId",
+          "href": "#getamountinputid",
+          "depth": 4,
+          "numbering": [
+            1,
+            7,
+            1,
+            1
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "getCurrencyDropdownId",
+          "href": "#getcurrencydropdownid",
+          "depth": 4,
+          "numbering": [
+            1,
+            7,
+            1,
+            2
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Data transformation methods",
+          "href": "#data-transformation-methods",
+          "depth": 3,
+          "numbering": [
+            1,
+            7,
+            2
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "convertToMoneyValue",
+          "href": "#converttomoneyvalue",
+          "depth": 4,
+          "numbering": [
+            1,
+            7,
+            2,
+            1
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "parseMoneyValue",
+          "href": "#parsemoneyvalue",
+          "depth": 4,
+          "numbering": [
+            1,
+            7,
+            2,
+            2
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Validation methods",
+          "href": "#validation-methods",
+          "depth": 3,
+          "numbering": [
+            1,
+            7,
+            3
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "isEmpty",
+          "href": "#isempty",
+          "depth": 4,
+          "numbering": [
+            1,
+            7,
+            3,
+            1
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "isHighPrecision",
+          "href": "#ishighprecision",
+          "depth": 4,
+          "numbering": [
+            1,
+            7,
+            3,
+            2
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Type definitions",
+          "href": "#type-definitions",
+          "depth": 3,
+          "numbering": [
+            1,
+            7,
+            4
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Testing your implementation",
+          "href": "#testing-your-implementation",
+          "depth": 2,
+          "numbering": [
+            1,
+            8
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Basic Rendering Tests",
+          "href": "#basic-rendering-tests",
+          "depth": 3,
+          "numbering": [
+            1,
+            8,
+            1
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Interaction Tests",
+          "href": "#interaction-tests",
+          "depth": 3,
+          "numbering": [
+            1,
+            8,
+            2
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Testing High Precision Support",
+          "href": "#testing-high-precision-support",
+          "depth": 3,
+          "numbering": [
+            1,
+            8,
+            3
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Testing Validation States",
+          "href": "#testing-validation-states",
+          "depth": 3,
+          "numbering": [
+            1,
+            8,
+            4
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Testing Currency Configuration",
+          "href": "#testing-currency-configuration",
+          "depth": 3,
+          "numbering": [
+            1,
+            8,
+            5
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Resources",
+          "href": "#resources",
+          "depth": 2,
+          "numbering": [
+            1,
+            9
+          ],
+          "parent": "root"
+        }
+      ]
+    },
+    "guidelines": {
+      "mdx": "\n## Guidelines\n\nMoney input guidelines offer best practice and usage guides to keep user\nexperience accessible and familiar, ensuring consistency and high ease of use.\n\n### Best practices\n\n- **Default currency:** Pre-select the most common or local currency for the\n  user based on location or historical data to minimize input effort.\n- **Clear labeling:** Always use a persistent, descriptive label (e.g., \"Product\n  price,\" \"Shipping cost\") and ensure the currency field and numerical input are\n  visually grouped as one component.\n- **Validation feedback:** Provide immediate, clear, and action-oriented error\n  messages and visual cues when validation fails (e.g., input is non-numeric, or\n  violates range constraints).\n- **Precision guidance:** Utilize the \"High precision price\" tooltip or similar\n  mechanisms to explain special input requirements for decimal places or\n  specific pricing rules.\n- **Logical currency ordering:** Order the currency dropdown options logically,\n  typically placing the most common currencies first, followed by an\n  alphabetical list.\n\n### Usage\n\nUtilizing money input should be consistent, and relevant for the data needed.\n\n> [!TIP]\\\n> When to use\n\n- **Currency flexibility:** When the user must select the currency alongside the\n  value. Recording multiple prices that are specific to currency.\n- **Price configuration:** For setting product prices, discounts, taxes, or\n  inventory costs in a back-office system.\n- **Transactional input:** When capturing any customer-facing input that\n  involves currency and payment (e.g., donation amount).\n\n> [!CAUTION]\\\n> When not to use\n\n- **Simple currency display:** Do not use the full input component just to\n  display a currency value. Use formatted text instead.\n- **Pure numerical data:** If the input is only a number and does not involve\n  money, use a standard number input.\n- **Fixed currency:** If the currency is guaranteed to be fixed (e.g., always\n  USD) and selection is not required, use a standard text input with a fixed\n  currency symbol/label appended.\n\n### Money input in use\n\n> [!TIP]\\\n> **Do**\n>\n> - Do make both the currency selector and the number input easily accessible.\n> - Do provide helper text or tooltips (like the \"High precision price\" tooltip)\n>   for complex constraints.\n\n```jsx live\nconst App = () => {\n  const [value, setValue] = React.useState({\n    amount: \"20.12345\",\n    currencyCode: \"EUR\"\n  });\n\n  return (\n    <FormField.Root>\n      <FormField.Label>Product Price</FormField.Label>\n      <FormField.Input>\n        <MoneyInput\n          value={value}\n          onValueChange={setValue}\n          currencies={[\"EUR\", \"USD\", \"GBP\"]}\n          hasHighPrecisionBadge\n        />\n      </FormField.Input>\n      <FormField.Description>\n        High precision pricing available for detailed financial accuracy\n      </FormField.Description>\n    </FormField.Root>\n  );\n}\n```\n\n> [!CAUTION]\\\n> **Don't**\n>\n> - Don't hide the currency selector if the currency is not fixed.\n> - Don't use a money input if there is a default single currency or if the\n>   number does not represent a currency.\n> - Don't allow users to submit the form with an invalid or incorrectly\n>   formatted currency or number.\n> - Don't use lengthy error messages; keep them concise and focus on the\n>   solution.\n\n```jsx live\nconst App = () => {\n  const [value, setValue] = React.useState({\n    amount: \"20\",\n    currencyCode: \"EUR\"\n  });\n\n  return (\n    <FormField.Root isInvalid>\n      <FormField.Label>Product Price</FormField.Label>\n      <FormField.Input>\n        <MoneyInput\n          value={value}\n          onValueChange={setValue}\n          currencies={[\"EUR\"]}\n          isInvalid\n          width=\"100%\"\n        />\n      </FormField.Input>\n      <FormField.Error>\n        FATAL CLIENT-SIDE VALIDATION FAILURE: The input string for the Product Price field did not pass the REGEX matching criteria for the accepted numeric float and currency locale object structure. Data integrity requires a value greater than the currently defined minimum threshold, which is configured for 30.00 base units, and must contain two trailing decimal places, regardless of whether the final calculated value is a whole integer.\n      </FormField.Error>\n    </FormField.Root>\n  );\n}\n```\n",
+      "toc": [
+        {
+          "value": "Guidelines",
+          "href": "#guidelines",
+          "depth": 2,
+          "numbering": [
+            1,
+            1
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Best practices",
+          "href": "#best-practices",
+          "depth": 3,
+          "numbering": [
+            1,
+            1,
+            1
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Usage",
+          "href": "#usage",
+          "depth": 3,
+          "numbering": [
+            1,
+            1,
+            2
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Money input in use",
+          "href": "#money-input-in-use",
+          "depth": 3,
+          "numbering": [
+            1,
+            1,
+            3
+          ],
+          "parent": "root"
+        }
+      ]
+    }
+  }
+}