@commercetools/nimbus-mcp 3.2.0 → 3.4.0

package/data/docs/routes/components-inputs-range-slider.json

@@ -0,0 +1,633 @@
+{
+  "meta": {
+    "id": "Components-RangeSlider",
+    "title": "Range Slider",
+    "exportName": "RangeSlider",
+    "description": "A range slider lets users select a numeric range — a lower and an upper bound — by dragging two handles along a shared track.",
+    "lifecycleState": "Beta",
+    "order": 999,
+    "repoPath": "packages/nimbus/src/components/slider/derivatives/range-slider/range-slider.mdx",
+    "menu": [
+      "Components",
+      "Inputs",
+      "Range Slider"
+    ],
+    "route": "components/inputs/range-slider",
+    "tags": [
+      "component",
+      "range slider",
+      "slider",
+      "input",
+      "numeric",
+      "range"
+    ],
+    "toc": [
+      {
+        "value": "Overview",
+        "href": "#overview",
+        "depth": 2,
+        "numbering": [
+          1,
+          1
+        ],
+        "parent": "root"
+      },
+      {
+        "value": "Key features",
+        "href": "#key-features",
+        "depth": 3,
+        "numbering": [
+          1,
+          1,
+          1
+        ],
+        "parent": "root"
+      },
+      {
+        "value": "Resources",
+        "href": "#resources",
+        "depth": 3,
+        "numbering": [
+          1,
+          1,
+          2
+        ],
+        "parent": "root"
+      },
+      {
+        "value": "Variables",
+        "href": "#variables",
+        "depth": 2,
+        "numbering": [
+          1,
+          2
+        ],
+        "parent": "root"
+      },
+      {
+        "value": "Thumb labels",
+        "href": "#thumb-labels",
+        "depth": 3,
+        "numbering": [
+          1,
+          2,
+          1
+        ],
+        "parent": "root"
+      },
+      {
+        "value": "Size",
+        "href": "#size",
+        "depth": 3,
+        "numbering": [
+          1,
+          2,
+          2
+        ],
+        "parent": "root"
+      },
+      {
+        "value": "Variants",
+        "href": "#variants",
+        "depth": 3,
+        "numbering": [
+          1,
+          2,
+          3
+        ],
+        "parent": "root"
+      },
+      {
+        "value": "Orientation",
+        "href": "#orientation",
+        "depth": 3,
+        "numbering": [
+          1,
+          2,
+          4
+        ],
+        "parent": "root"
+      },
+      {
+        "value": "Ticks",
+        "href": "#ticks",
+        "depth": 3,
+        "numbering": [
+          1,
+          2,
+          5
+        ],
+        "parent": "root"
+      }
+    ],
+    "layout": "app-frame",
+    "tabs": [
+      {
+        "key": "overview",
+        "title": "Overview",
+        "order": 0
+      },
+      {
+        "key": "guidelines",
+        "title": "Guidelines",
+        "order": 2
+      },
+      {
+        "key": "dev",
+        "title": "Implementation",
+        "order": 3
+      },
+      {
+        "key": "a11y",
+        "title": "Accessibility",
+        "order": 4
+      }
+    ]
+  },
+  "mdx": "\n## Overview\n\nA range slider lets people choose a range — a lower and an upper bound — by\ndragging two handles along a shared track, instead of typing two numbers. It's a\ngood fit whenever the exact numbers matter less than their position relative to\nthe whole scale, such as a price, distance, or rating filter.\n\n`RangeSlider` selects a `[min, max]` pair with two handles that can't cross each\nother, so the lower value never exceeds the upper one. For selecting a single\nvalue, use [`Slider`](/components/inputs/slider) instead — the two share the\nsame track, handle, and tick styling, so a page that mixes single and range\nsliders still looks consistent.\n\nLike `Slider`, `RangeSlider` draws no label or static \"current value\" readout of\nits own. Each handle's value appears in a small tooltip above it while it's\nhovered, focused, or being dragged — the track stays visually quiet the rest of\nthe time. The control's label comes from the surrounding `FormField`, or from an\n`aria-label` when it's used on its own, and each handle takes its own name from\n`thumbLabels`.\n\n### Key features\n\n- **Two non-crossing handles:** the lower handle can't be dragged past the upper\n  one, so the selection is always a valid `[min, max]` range.\n- **Tooltip value display:** each handle's value shows above it on hover, focus,\n  or drag — there's no permanent number next to the track.\n- **Per-handle names:** `thumbLabels` gives each handle its own accessible name;\n  when omitted, the handles fall back to localized \"Minimum\" / \"Maximum\" labels.\n- **Shared styling with Slider:** the same size, variant, orientation, and tick\n  options apply, so range and single sliders stay visually consistent.\n\n### Resources\n\n- [Slider](/components/inputs/slider) — the single-value counterpart\n- [W3C ARIA Authoring Practices: Slider (Multi-Thumb) pattern](https://www.w3.org/WAI/ARIA/apg/patterns/slider-multithumb/)\n\n## Variables\n\n### Thumb labels\n\n`RangeSlider` uses two handles, so each one needs its own accessible name. Pass\n`thumbLabels` as a `[lower, upper]` pair (for example\n`[\"Minimum price\", \"Maximum price\"]`); when omitted, the handles fall back to\nlocalized \"Minimum\" / \"Maximum\" labels rather than being left anonymous.\n\n```jsx live\nconst App = () => (\n  <RangeSlider\n    aria-label=\"Price range\"\n    thumbLabels={[\"Minimum price\", \"Maximum price\"]}\n    defaultValue={[20, 60]}\n    minValue={0}\n    maxValue={100}\n  />\n);\n```\n\n### Size\n\n`md` is the default size. `sm` is available for denser layouts.\n\n```jsx live\nconst App = () => (\n  <Stack direction=\"horizontal\" gap=\"600\" alignItems=\"center\">\n    <RangeSlider aria-label=\"Small\" size=\"sm\" defaultValue={[20, 60]} />\n    <RangeSlider\n      aria-label=\"Medium (default)\"\n      size=\"md\"\n      defaultValue={[20, 60]}\n    />\n  </Stack>\n);\n```\n\n### Variants\n\n`filled` is the default. Two additional variants are available for contexts that\ncall for a different visual weight:\n\n- **Filled** (default) — a standard thin track with a colored progress fill\n  between the two handles. The safest choice for most forms and filters.\n- **Minimal** — a thin neutral track with single-color handles and a colored\n  range segment between them; the track and range grow to full width on hover or\n  focus. For low-emphasis controls where a full colored bar would over-emphasize\n  the range.\n- **Enclosed** — a thick, contained bar with the handles inset inside it (an\n  iOS-style control). Good for touch-first contexts or standalone controls that\n  benefit from larger, more tactile targets.\n\n```jsx live\nconst App = () => (\n  <Stack direction=\"horizontal\" gap=\"600\" alignItems=\"center\">\n    <RangeSlider\n      aria-label=\"Filled (default)\"\n      variant=\"filled\"\n      defaultValue={[20, 60]}\n    />\n    <RangeSlider aria-label=\"Minimal\" variant=\"minimal\" defaultValue={[20, 60]} />\n    <RangeSlider\n      aria-label=\"Enclosed\"\n      variant=\"enclosed\"\n      defaultValue={[25, 75]}\n    />\n  </Stack>\n);\n```\n\n### Orientation\n\n`horizontal` is the default. `vertical` is useful when horizontal space is\nlimited. The vertical track has a built-in default length, so no explicit\n`height` is required.\n\n```jsx live\nconst App = () => (\n  <Stack direction=\"horizontal\" gap=\"600\" alignItems=\"flex-start\">\n    <RangeSlider aria-label=\"Horizontal\" defaultValue={[20, 60]} />\n    <RangeSlider\n      aria-label=\"Vertical\"\n      defaultValue={[20, 60]}\n      orientation=\"vertical\"\n    />\n  </Stack>\n);\n```\n\n### Ticks\n\nTurn on `showTicks` to mark discrete steps along the track. `tickStep` (or\n`step`, if `tickStep` is omitted) controls how far apart the ticks are. Ticks\nare purely visual — they don't constrain where the handles can land.\n\n```jsx live\nconst App = () => (\n  <RangeSlider\n    aria-label=\"Rating range\"\n    defaultValue={[25, 75]}\n    minValue={0}\n    maxValue={100}\n    step={25}\n    showTicks\n  />\n);\n```\n",
+  "views": {
+    "overview": {
+      "mdx": "\n## Overview\n\nA range slider lets people choose a range — a lower and an upper bound — by\ndragging two handles along a shared track, instead of typing two numbers. It's a\ngood fit whenever the exact numbers matter less than their position relative to\nthe whole scale, such as a price, distance, or rating filter.\n\n`RangeSlider` selects a `[min, max]` pair with two handles that can't cross each\nother, so the lower value never exceeds the upper one. For selecting a single\nvalue, use [`Slider`](/components/inputs/slider) instead — the two share the\nsame track, handle, and tick styling, so a page that mixes single and range\nsliders still looks consistent.\n\nLike `Slider`, `RangeSlider` draws no label or static \"current value\" readout of\nits own. Each handle's value appears in a small tooltip above it while it's\nhovered, focused, or being dragged — the track stays visually quiet the rest of\nthe time. The control's label comes from the surrounding `FormField`, or from an\n`aria-label` when it's used on its own, and each handle takes its own name from\n`thumbLabels`.\n\n### Key features\n\n- **Two non-crossing handles:** the lower handle can't be dragged past the upper\n  one, so the selection is always a valid `[min, max]` range.\n- **Tooltip value display:** each handle's value shows above it on hover, focus,\n  or drag — there's no permanent number next to the track.\n- **Per-handle names:** `thumbLabels` gives each handle its own accessible name;\n  when omitted, the handles fall back to localized \"Minimum\" / \"Maximum\" labels.\n- **Shared styling with Slider:** the same size, variant, orientation, and tick\n  options apply, so range and single sliders stay visually consistent.\n\n### Resources\n\n- [Slider](/components/inputs/slider) — the single-value counterpart\n- [W3C ARIA Authoring Practices: Slider (Multi-Thumb) pattern](https://www.w3.org/WAI/ARIA/apg/patterns/slider-multithumb/)\n\n## Variables\n\n### Thumb labels\n\n`RangeSlider` uses two handles, so each one needs its own accessible name. Pass\n`thumbLabels` as a `[lower, upper]` pair (for example\n`[\"Minimum price\", \"Maximum price\"]`); when omitted, the handles fall back to\nlocalized \"Minimum\" / \"Maximum\" labels rather than being left anonymous.\n\n```jsx live\nconst App = () => (\n  <RangeSlider\n    aria-label=\"Price range\"\n    thumbLabels={[\"Minimum price\", \"Maximum price\"]}\n    defaultValue={[20, 60]}\n    minValue={0}\n    maxValue={100}\n  />\n);\n```\n\n### Size\n\n`md` is the default size. `sm` is available for denser layouts.\n\n```jsx live\nconst App = () => (\n  <Stack direction=\"horizontal\" gap=\"600\" alignItems=\"center\">\n    <RangeSlider aria-label=\"Small\" size=\"sm\" defaultValue={[20, 60]} />\n    <RangeSlider\n      aria-label=\"Medium (default)\"\n      size=\"md\"\n      defaultValue={[20, 60]}\n    />\n  </Stack>\n);\n```\n\n### Variants\n\n`filled` is the default. Two additional variants are available for contexts that\ncall for a different visual weight:\n\n- **Filled** (default) — a standard thin track with a colored progress fill\n  between the two handles. The safest choice for most forms and filters.\n- **Minimal** — a thin neutral track with single-color handles and a colored\n  range segment between them; the track and range grow to full width on hover or\n  focus. For low-emphasis controls where a full colored bar would over-emphasize\n  the range.\n- **Enclosed** — a thick, contained bar with the handles inset inside it (an\n  iOS-style control). Good for touch-first contexts or standalone controls that\n  benefit from larger, more tactile targets.\n\n```jsx live\nconst App = () => (\n  <Stack direction=\"horizontal\" gap=\"600\" alignItems=\"center\">\n    <RangeSlider\n      aria-label=\"Filled (default)\"\n      variant=\"filled\"\n      defaultValue={[20, 60]}\n    />\n    <RangeSlider aria-label=\"Minimal\" variant=\"minimal\" defaultValue={[20, 60]} />\n    <RangeSlider\n      aria-label=\"Enclosed\"\n      variant=\"enclosed\"\n      defaultValue={[25, 75]}\n    />\n  </Stack>\n);\n```\n\n### Orientation\n\n`horizontal` is the default. `vertical` is useful when horizontal space is\nlimited. The vertical track has a built-in default length, so no explicit\n`height` is required.\n\n```jsx live\nconst App = () => (\n  <Stack direction=\"horizontal\" gap=\"600\" alignItems=\"flex-start\">\n    <RangeSlider aria-label=\"Horizontal\" defaultValue={[20, 60]} />\n    <RangeSlider\n      aria-label=\"Vertical\"\n      defaultValue={[20, 60]}\n      orientation=\"vertical\"\n    />\n  </Stack>\n);\n```\n\n### Ticks\n\nTurn on `showTicks` to mark discrete steps along the track. `tickStep` (or\n`step`, if `tickStep` is omitted) controls how far apart the ticks are. Ticks\nare purely visual — they don't constrain where the handles can land.\n\n```jsx live\nconst App = () => (\n  <RangeSlider\n    aria-label=\"Rating range\"\n    defaultValue={[25, 75]}\n    minValue={0}\n    maxValue={100}\n    step={25}\n    showTicks\n  />\n);\n```\n",
+      "toc": [
+        {
+          "value": "Overview",
+          "href": "#overview",
+          "depth": 2,
+          "numbering": [
+            1,
+            1
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Key features",
+          "href": "#key-features",
+          "depth": 3,
+          "numbering": [
+            1,
+            1,
+            1
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Resources",
+          "href": "#resources",
+          "depth": 3,
+          "numbering": [
+            1,
+            1,
+            2
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Variables",
+          "href": "#variables",
+          "depth": 2,
+          "numbering": [
+            1,
+            2
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Thumb labels",
+          "href": "#thumb-labels",
+          "depth": 3,
+          "numbering": [
+            1,
+            2,
+            1
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Size",
+          "href": "#size",
+          "depth": 3,
+          "numbering": [
+            1,
+            2,
+            2
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Variants",
+          "href": "#variants",
+          "depth": 3,
+          "numbering": [
+            1,
+            2,
+            3
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Orientation",
+          "href": "#orientation",
+          "depth": 3,
+          "numbering": [
+            1,
+            2,
+            4
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Ticks",
+          "href": "#ticks",
+          "depth": 3,
+          "numbering": [
+            1,
+            2,
+            5
+          ],
+          "parent": "root"
+        }
+      ]
+    },
+    "a11y": {
+      "mdx": "\n## Accessibility\n\nAccessibility ensures digital content and functionality are usable by everyone,\nincluding people with disabilities, by addressing visual, auditory, cognitive,\nand physical limitations.\n\n`RangeSlider` renders no visible label of its own, so the control's accessible\nname must always come from somewhere — either `FormField.Label` composed inside\na form field, or an `aria-label` / `aria-labelledby` when used standalone. On top\nof that, each of the two handles needs its own name via `thumbLabels`.\n\n```jsx live\nconst App = () => (\n  <RangeSlider\n    aria-label=\"Price range\"\n    thumbLabels={[\"Minimum price\", \"Maximum price\"]}\n    defaultValue={[20, 60]}\n    minValue={0}\n    maxValue={100}\n  />\n);\n```\n\n### Accessibility standards\n\n- Always give the range slider an accessible name: `aria-label` (or\n  `aria-labelledby`) when standalone, or `FormField.Label` when composed inside\n  `FormField.Root`. A slider with no accessible name is unusable with a screen\n  reader.\n- Give each handle its own name via `thumbLabels` (e.g.\n  `[\"Minimum price\", \"Maximum price\"]`); when omitted, the handles fall back to\n  localized \"Minimum\" / \"Maximum\" labels so they're never anonymous.\n- Each handle's current value is exposed to assistive technology through its\n  native range value, not just the visual tooltip — screen readers announce it\n  without needing the tooltip open.\n- Support full keyboard interaction: `Tab` moves focus between the two handles,\n  `Arrow` keys adjust the focused handle by `step`, and `Home` / `End` jump it to\n  its currently allowed minimum / maximum.\n- Ensure sufficient color contrast for the track, fill, and handles in every\n  state (default, hover, focus, dragging, disabled, invalid).\n- Communicate an invalid state with both a visual cue and a `FormField.Error`\n  message — never color alone.\n- The invalid visual cue comes from `data-invalid` on the root element, not\n  `aria-invalid` on the underlying range inputs — React Aria's `Slider` has no\n  validation-state concept of its own (unlike text-style inputs). Assistive\n  technology instead picks up the `FormField.Error` message.\n\n### Keyboard interactions\n\n`RangeSlider` has two independently focusable handles.\n\n| Key                                | Action                                                            |\n| ---------------------------------- | ----------------------------------------------------------------- |\n| `Tab` / `Shift+Tab`                | Move focus to / between / away from the two handles.              |\n| `Arrow Left` / `Arrow Right`       | Decrement / increment the focused handle by `step` (horizontal).  |\n| `Arrow Down` / `Arrow Up`          | Decrement / increment the focused handle by `step` (vertical).    |\n| `Page Down` / `Page Up`            | Decrement / increment the focused handle by a larger amount.      |\n| `Home`                             | Jump the focused handle to its currently allowed minimum.         |\n| `End`                              | Jump the focused handle to its currently allowed maximum.         |\n\nA handle is never moved past the other one — the effective range is clamped to\n`[minValue, upperValue]` for the lower handle and `[lowerValue, maxValue]` for\nthe upper handle.\n\n### Resources\n\n- [React Aria Slider](https://react-spectrum.adobe.com/react-aria/Slider.html)\n- [W3C ARIA Authoring Practices Guide (APG): Slider (Multi-Thumb) pattern](https://www.w3.org/WAI/ARIA/apg/patterns/slider-multithumb/)\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": "Keyboard interactions",
+          "href": "#keyboard-interactions",
+          "depth": 3,
+          "numbering": [
+            1,
+            1,
+            2
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Resources",
+          "href": "#resources",
+          "depth": 3,
+          "numbering": [
+            1,
+            1,
+            3
+          ],
+          "parent": "root"
+        }
+      ]
+    },
+    "dev": {
+      "mdx": "\n## Getting started\n\n### Import\n\n```tsx\nimport { RangeSlider, type RangeSliderProps } from \"@commercetools/nimbus\";\n```\n\n### Basic usage\n\n`RangeSlider` selects a `[number, number]` tuple using two handles that can't be\ndragged past each other — the lower value never exceeds the upper one. It renders\nno visible label and no static value readout — each handle's current value\nappears in a tooltip above it while it's hovered, focused, or dragged, so an\naccessible name must be supplied separately (see [Accessibility](#accessibility)\nbelow).\n\nUse `thumbLabels` to give each handle its own accessible name; when omitted, the\nhandles fall back to localized \"Minimum\" / \"Maximum\" labels.\n\n```jsx live-dev\nconst App = () => (\n  <RangeSlider\n    aria-label=\"Price range\"\n    thumbLabels={[\"Minimum\", \"Maximum\"]}\n    defaultValue={[20, 60]}\n    minValue={0}\n    maxValue={100}\n  />\n);\n```\n\n> For selecting a single value rather than a range, use the\n> [`Slider`](/components/inputs/slider) component. The two share the same track,\n> handle, and tick styling.\n\n## Usage examples\n\n### Thumb labels\n\n`thumbLabels` is a `[lower, upper]` array that names each handle individually.\nPrefer domain-specific labels over the generic fallbacks.\n\n```jsx live-dev\nconst App = () => (\n  <RangeSlider\n    aria-label=\"Price range\"\n    thumbLabels={[\"Minimum price\", \"Maximum price\"]}\n    defaultValue={[20, 60]}\n    minValue={0}\n    maxValue={100}\n  />\n);\n```\n\n### Size options\n\n`sm` and `md` size variants are available to match the surrounding density.\n\n```jsx live-dev\nconst App = () => (\n  <Stack direction=\"column\" gap=\"600\">\n    <RangeSlider aria-label=\"Small\" size=\"sm\" defaultValue={[20, 60]} />\n    <RangeSlider\n      aria-label=\"Medium (default)\"\n      size=\"md\"\n      defaultValue={[20, 60]}\n    />\n  </Stack>\n);\n```\n\n### Visual variants\n\n`variant` changes the track/progress/thumb treatment. `filled` (the default) is a\nstandard thin track with a colored progress fill; `minimal` is a thin neutral\ntrack with single-color thumbs and a colored range segment that grow to full\nwidth on hover/focus, for low-emphasis controls such as a thumbnail-size picker;\n`enclosed` is a thick, contained bar with the\nthumbs inset inside it. This applies to both `RangeSlider` and `Slider` since\nthey share the same recipe.\n\n```jsx live-dev\nconst App = () => (\n  <Stack direction=\"column\" gap=\"600\">\n    <RangeSlider aria-label=\"Filled\" variant=\"filled\" defaultValue={[20, 60]} />\n    <RangeSlider aria-label=\"Minimal\" variant=\"minimal\" defaultValue={[20, 60]} />\n    <RangeSlider\n      aria-label=\"Enclosed\"\n      variant=\"enclosed\"\n      defaultValue={[25, 75]}\n    />\n  </Stack>\n);\n```\n\n### Orientation\n\nSet `orientation=\"vertical\"` for a vertical track. The vertical track has a\nbuilt-in default length, so no explicit `height` is required.\n\n```jsx live-dev\nconst App = () => (\n  <RangeSlider\n    aria-label=\"Volume range\"\n    defaultValue={[20, 60]}\n    orientation=\"vertical\"\n  />\n);\n```\n\n### Ticks\n\nTurn on `showTicks` to render tick marks at every `tickStep` interval (falling\nback to `step` when `tickStep` is omitted). Useful for scales where the discrete\nstops themselves are meaningful.\n\n```jsx live-dev\nconst App = () => (\n  <RangeSlider\n    aria-label=\"Rating range\"\n    defaultValue={[25, 75]}\n    minValue={0}\n    maxValue={100}\n    step={25}\n    showTicks\n  />\n);\n```\n\n**Behavioral notes:**\n\n- `tickStep` controls the spacing of ticks; it defaults to `step` when\n  `showTicks` is set and `tickStep` is omitted.\n- Ticks are purely visual — they don't constrain the values a handle can land\n  on. Use `step` for that.\n- Ticks are spaced evenly starting at `minValue`. When `(maxValue - minValue)`\n  isn't evenly divisible by the tick step, the last tick lands on the final full\n  step short of `maxValue`, not on `maxValue` itself.\n\n### Value formatting\n\n`formatOptions` (an `Intl.NumberFormatOptions` object) formats the value shown in\neach handle's tooltip, without changing the underlying numeric values.\n\n```jsx live-dev\nconst App = () => (\n  <RangeSlider\n    aria-label=\"Price range\"\n    thumbLabels={[\"Minimum price\", \"Maximum price\"]}\n    defaultValue={[20, 120]}\n    minValue={0}\n    maxValue={200}\n    formatOptions={{ style: \"currency\", currency: \"USD\" }}\n  />\n);\n```\n\n### Disabled state\n\nDisable interaction with `isDisabled`.\n\n```jsx live-dev\nconst App = () => (\n  <RangeSlider\n    aria-label=\"Price range\"\n    defaultValue={[20, 60]}\n    minValue={0}\n    maxValue={100}\n    isDisabled\n  />\n);\n```\n\n### Uncontrolled mode\n\nFor simpler use cases, use uncontrolled mode with `defaultValue` and `onChange`.\nThe `Text` element below stands in for **your own** application code reacting to\nthe live range (e.g. updating a preview elsewhere on the page) — it's a demo of\nwhat `onChange` gives you, not the recommended \"value readout beside the track\"\npattern; each handle's own tooltip already shows its value on hover, focus, and\ndrag (see the Guidelines tab).\n\n```jsx live-dev\nconst App = () => {\n  const [range, setRange] = useState([20, 60]);\n\n  return (\n    <Stack direction=\"column\" gap=\"400\">\n      <RangeSlider\n        aria-label=\"Price range\"\n        thumbLabels={[\"Minimum\", \"Maximum\"]}\n        defaultValue={[20, 60]}\n        minValue={0}\n        maxValue={100}\n        onChange={setRange}\n      />\n      <Text fontSize=\"sm\">\n        Current range (for demo purposes): {range[0]} – {range[1]}\n      </Text>\n    </Stack>\n  );\n};\n```\n\n### Controlled mode\n\nFor scenarios requiring programmatic control, use controlled mode. The value is a\n`[number, number]` tuple; `onChange` receives the updated tuple.\n\n```jsx live-dev\nconst App = () => {\n  const [range, setRange] = useState([20, 60]);\n\n  return (\n    <Stack direction=\"column\" gap=\"400\">\n      <RangeSlider\n        aria-label=\"Price range\"\n        thumbLabels={[\"Minimum\", \"Maximum\"]}\n        value={range}\n        onChange={setRange}\n        minValue={0}\n        maxValue={100}\n      />\n      <Stack direction=\"row\" gap=\"300\">\n        <Button onPress={() => setRange([0, 100])}>Reset</Button>\n        <Button onPress={() => setRange([40, 60])}>Narrow</Button>\n      </Stack>\n    </Stack>\n  );\n};\n```\n\n## Component requirements\n\n### Accessibility\n\n`RangeSlider` handles keyboard, pointer, touch, and RTL behavior internally via\nReact Aria. However, unlike most Nimbus inputs, **it renders no visible label and\nno static value readout** — each handle's current value is only ever shown in a\ntooltip above it while it's hovered, focused, or dragged. You must always supply\nan accessible name for the control through one of the following:\n\n- Composing inside `FormField.Root` with `FormField.Label` (recommended in\n  forms):\n\n```tsx\n<FormField.Root>\n  <FormField.Label>Price range</FormField.Label>\n  <FormField.Input>\n    <RangeSlider\n      thumbLabels={[\"Minimum price\", \"Maximum price\"]}\n      defaultValue={[20, 120]}\n      minValue={0}\n      maxValue={200}\n    />\n  </FormField.Input>\n</FormField.Root>\n```\n\n- Passing `aria-label` directly, for standalone use where no visible label is\n  part of the design:\n\n```tsx\n<RangeSlider\n  aria-label=\"Price range\"\n  thumbLabels={[\"Minimum price\", \"Maximum price\"]}\n  defaultValue={[20, 120]}\n  minValue={0}\n  maxValue={200}\n/>\n```\n\n- Associating an existing `<label>` element via `aria-labelledby`:\n\n```tsx\n<label id=\"price-label\">Price range</label>\n<RangeSlider\n  aria-labelledby=\"price-label\"\n  thumbLabels={[\"Minimum price\", \"Maximum price\"]}\n  defaultValue={[20, 120]}\n  minValue={0}\n  maxValue={200}\n/>\n```\n\nOn top of the control's name, use `thumbLabels` to name each handle\nindividually (e.g. `[\"Minimum price\", \"Maximum price\"]`); if omitted, the handles\nfall back to localized \"Minimum\" / \"Maximum\" labels rather than being left\nanonymous.\n\n#### Keyboard navigation\n\nThe component supports full keyboard interaction, with two independently\nfocusable handles:\n\n- `Tab` / `Shift+Tab`: move focus to, between, and away from the two handles.\n- `Arrow Left` / `Arrow Right` (or `Arrow Down` / `Arrow Up` when\n  `orientation=\"vertical\"`): decrement/increment the focused handle's value by\n  `step`.\n- `Page Down` / `Page Up`: decrement/increment the focused handle by a larger\n  amount.\n- `Home`: jump the focused handle to its currently allowed minimum.\n- `End`: jump the focused handle to its currently allowed maximum.\n\nA handle is never moved past the other one — the effective range is clamped to\n`[minValue, upperValue]` for the lower handle and `[lowerValue, maxValue]` for\nthe upper handle.\n\n## API reference\n\n<PropsTable id=\"RangeSlider\" />\n\n## Common patterns\n\n### Price range filter\n\nA typical use of `RangeSlider` pairs it with a `FormField.Description` that\nsummarizes the current selection. Unlike a bare value readout placed directly\nbeside the track (see Guidelines), the description is a permanent part of the\nform field's own text stack, below the control — useful context for anyone who\nisn't actively hovering or focusing a handle, rather than a duplicate of the\ntooltip.\n\n```jsx live-dev\nconst App = () => {\n  const [range, setRange] = useState([20, 80]);\n\n  return (\n    <Stack direction=\"column\" gap=\"300\">\n      <FormField.Root>\n        <FormField.Label>Price range</FormField.Label>\n        <FormField.Input>\n          <RangeSlider\n            thumbLabels={[\"Minimum price\", \"Maximum price\"]}\n            value={range}\n            onChange={setRange}\n            minValue={0}\n            maxValue={200}\n            formatOptions={{ style: \"currency\", currency: \"USD\" }}\n          />\n        </FormField.Input>\n        <FormField.Description>\n          ${range[0]} – ${range[1]}\n        </FormField.Description>\n      </FormField.Root>\n    </Stack>\n  );\n};\n```\n\n### RangeSlider inside a form field with validation\n\n`FormField.Input` clones its React-Aria-named props (`aria-labelledby`,\n`aria-describedby`, `isInvalid`, `isDisabled`, `isRequired`, `isReadOnly`) onto\nthe slider, so the label, description, and error state all associate\nautomatically.\n\n```jsx live-dev\nconst App = () => (\n  <FormField.Root isInvalid>\n    <FormField.Label>Price range</FormField.Label>\n    <FormField.Input>\n      <RangeSlider\n        thumbLabels={[\"Minimum price\", \"Maximum price\"]}\n        defaultValue={[20, 120]}\n        minValue={0}\n        maxValue={200}\n      />\n    </FormField.Input>\n    <FormField.Description>Set the price bounds to filter by</FormField.Description>\n    <FormField.Error>Range is out of bounds</FormField.Error>\n  </FormField.Root>\n);\n```\n\n## Testing your implementation\n\nThese examples demonstrate how to test your implementation when using\n`RangeSlider` within your application. As the component's internal functionality\nis already tested by Nimbus, these patterns help you verify your integration and\napplication-specific logic.\n\n### Basic Rendering Tests\n\nVerify the range slider renders two handles with the expected labels and values\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 { RangeSlider, FormField, NimbusProvider } from \"@commercetools/nimbus\";\n\ndescribe(\"RangeSlider - Basic rendering\", () => {\n  it(\"renders two handles with localized default labels when thumbLabels is omitted\", () => {\n    render(\n      <NimbusProvider>\n        <RangeSlider\n          aria-label=\"Price range\"\n          defaultValue={[20, 60]}\n          minValue={0}\n          maxValue={100}\n        />\n      </NimbusProvider>\n    );\n\n    const thumbs = screen.getAllByRole(\"slider\");\n    expect(thumbs).toHaveLength(2);\n    expect(thumbs[0]).toHaveValue(\"20\");\n    expect(thumbs[1]).toHaveValue(\"60\");\n    expect(thumbs[0]).toHaveAttribute(\"aria-label\", \"Minimum\");\n    expect(thumbs[1]).toHaveAttribute(\"aria-label\", \"Maximum\");\n  });\n\n  it(\"uses custom thumbLabels when provided\", () => {\n    render(\n      <NimbusProvider>\n        <RangeSlider\n          aria-label=\"Price range\"\n          thumbLabels={[\"Minimum price\", \"Maximum price\"]}\n          defaultValue={[20, 60]}\n          minValue={0}\n          maxValue={100}\n        />\n      </NimbusProvider>\n    );\n\n    const thumbs = screen.getAllByRole(\"slider\");\n    expect(thumbs[0]).toHaveAttribute(\"aria-label\", \"Minimum price\");\n    expect(thumbs[1]).toHaveAttribute(\"aria-label\", \"Maximum price\");\n  });\n});\n```\n\n### Interaction Tests\n\nTest keyboard interactions, the [number, number] onChange payload, and the non-crossing constraint\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 { RangeSlider, FormField, NimbusProvider } from \"@commercetools/nimbus\";\n\ndescribe(\"RangeSlider - Interactions\", () => {\n  it(\"calls onChange with a [number, number] tuple\", async () => {\n    const user = userEvent.setup();\n    const handleChange = vi.fn();\n    render(\n      <NimbusProvider>\n        <RangeSlider\n          aria-label=\"Price range\"\n          defaultValue={[20, 60]}\n          minValue={0}\n          maxValue={100}\n          onChange={handleChange}\n        />\n      </NimbusProvider>\n    );\n\n    const thumbs = screen.getAllByRole(\"slider\");\n    thumbs[0].focus();\n    await user.keyboard(\"{ArrowRight}\");\n\n    expect(handleChange).toHaveBeenCalledWith([21, 60]);\n  });\n\n  it(\"keeps the lower handle from crossing the upper handle\", async () => {\n    const user = userEvent.setup();\n    render(\n      <NimbusProvider>\n        <RangeSlider\n          aria-label=\"Price range\"\n          defaultValue={[20, 60]}\n          minValue={0}\n          maxValue={100}\n        />\n      </NimbusProvider>\n    );\n\n    const thumbs = screen.getAllByRole(\"slider\");\n    thumbs[0].focus();\n    await user.keyboard(\"{End}\");\n\n    const lower = Number((thumbs[0] as HTMLInputElement).value);\n    const upper = Number((thumbs[1] as HTMLInputElement).value);\n    expect(lower).toBeLessThanOrEqual(upper);\n  });\n});\n```\n\n### Testing States\n\nVerify disabled and invalid states render correctly\n\n```tsx\nimport { describe, it, expect, vi } from \"vitest\";\nimport { render, screen } from \"@testing-library/react\";\nimport userEvent from \"@testing-library/user-event\";\nimport { RangeSlider, FormField, NimbusProvider } from \"@commercetools/nimbus\";\n\ndescribe(\"RangeSlider - States\", () => {\n  it(\"handles disabled state on both handles\", () => {\n    render(\n      <NimbusProvider>\n        <RangeSlider\n          aria-label=\"Price range\"\n          defaultValue={[20, 60]}\n          minValue={0}\n          maxValue={100}\n          isDisabled\n        />\n      </NimbusProvider>\n    );\n\n    const thumbs = screen.getAllByRole(\"slider\");\n    expect(thumbs).toHaveLength(2);\n    thumbs.forEach((thumb) => expect(thumb).toBeDisabled());\n  });\n\n  it(\"surfaces the invalid state on the root element\", () => {\n    const { container } = render(\n      <NimbusProvider>\n        <RangeSlider\n          aria-label=\"Price range\"\n          defaultValue={[20, 60]}\n          minValue={0}\n          maxValue={100}\n          isInvalid\n        />\n      </NimbusProvider>\n    );\n\n    const root = container.querySelector('[data-slot=\"root\"]');\n    expect(root).toHaveAttribute(\"data-invalid\", \"true\");\n  });\n});\n```\n\n### FormField Integration Tests\n\nVerify the range slider composes correctly inside FormField\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 { RangeSlider, FormField, NimbusProvider } from \"@commercetools/nimbus\";\n\ndescribe(\"RangeSlider - FormField integration\", () => {\n  it(\"surfaces the invalid state from FormField.Root\", () => {\n    const { container } = render(\n      <NimbusProvider>\n        <FormField.Root isInvalid>\n          <FormField.Label>Price range</FormField.Label>\n          <FormField.Input>\n            <RangeSlider\n              thumbLabels={[\"Minimum price\", \"Maximum price\"]}\n              defaultValue={[20, 60]}\n              minValue={0}\n              maxValue={100}\n            />\n          </FormField.Input>\n          <FormField.Error>Range is out of bounds</FormField.Error>\n        </FormField.Root>\n      </NimbusProvider>\n    );\n\n    const root = container.querySelector('[data-slot=\"root\"]');\n    expect(root).toHaveAttribute(\"data-invalid\", \"true\");\n  });\n});\n```\n\n\n## Resources\n\n- [Storybook: RangeSlider](https://nimbus-storybook.vercel.app/?path=/docs/components-rangeslider--docs)\n- [Slider](/components/inputs/slider) — the single-value counterpart\n- [React Aria Slider](https://react-spectrum.adobe.com/react-aria/Slider.html)\n- [W3C ARIA Authoring Practices Guide (APG): Slider (Multi-Thumb) pattern](https://www.w3.org/WAI/ARIA/apg/patterns/slider-multithumb/)\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": "Thumb labels",
+          "href": "#thumb-labels",
+          "depth": 3,
+          "numbering": [
+            1,
+            2,
+            1
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Size options",
+          "href": "#size-options",
+          "depth": 3,
+          "numbering": [
+            1,
+            2,
+            2
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Visual variants",
+          "href": "#visual-variants",
+          "depth": 3,
+          "numbering": [
+            1,
+            2,
+            3
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Orientation",
+          "href": "#orientation",
+          "depth": 3,
+          "numbering": [
+            1,
+            2,
+            4
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Ticks",
+          "href": "#ticks",
+          "depth": 3,
+          "numbering": [
+            1,
+            2,
+            5
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Value formatting",
+          "href": "#value-formatting",
+          "depth": 3,
+          "numbering": [
+            1,
+            2,
+            6
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Disabled state",
+          "href": "#disabled-state",
+          "depth": 3,
+          "numbering": [
+            1,
+            2,
+            7
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Uncontrolled mode",
+          "href": "#uncontrolled-mode",
+          "depth": 3,
+          "numbering": [
+            1,
+            2,
+            8
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Controlled mode",
+          "href": "#controlled-mode",
+          "depth": 3,
+          "numbering": [
+            1,
+            2,
+            9
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Component requirements",
+          "href": "#component-requirements",
+          "depth": 2,
+          "numbering": [
+            1,
+            3
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Accessibility",
+          "href": "#accessibility",
+          "depth": 3,
+          "numbering": [
+            1,
+            3,
+            1
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Keyboard navigation",
+          "href": "#keyboard-navigation",
+          "depth": 4,
+          "numbering": [
+            1,
+            3,
+            1,
+            1
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "API reference",
+          "href": "#api-reference",
+          "depth": 2,
+          "numbering": [
+            1,
+            4
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Common patterns",
+          "href": "#common-patterns",
+          "depth": 2,
+          "numbering": [
+            1,
+            5
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Price range filter",
+          "href": "#price-range-filter",
+          "depth": 3,
+          "numbering": [
+            1,
+            5,
+            1
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "RangeSlider inside a form field with validation",
+          "href": "#rangeslider-inside-a-form-field-with-validation",
+          "depth": 3,
+          "numbering": [
+            1,
+            5,
+            2
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Testing your implementation",
+          "href": "#testing-your-implementation",
+          "depth": 2,
+          "numbering": [
+            1,
+            6
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Basic Rendering Tests",
+          "href": "#basic-rendering-tests",
+          "depth": 3,
+          "numbering": [
+            1,
+            6,
+            1
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Interaction Tests",
+          "href": "#interaction-tests",
+          "depth": 3,
+          "numbering": [
+            1,
+            6,
+            2
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Testing States",
+          "href": "#testing-states",
+          "depth": 3,
+          "numbering": [
+            1,
+            6,
+            3
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "FormField Integration Tests",
+          "href": "#formfield-integration-tests",
+          "depth": 3,
+          "numbering": [
+            1,
+            6,
+            4
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Resources",
+          "href": "#resources",
+          "depth": 2,
+          "numbering": [
+            1,
+            7
+          ],
+          "parent": "root"
+        }
+      ]
+    },
+    "guidelines": {
+      "mdx": "\n## Guidelines\n\nRange slider guidelines focus on picking a scale users can reason about, naming\nboth handles clearly, and keeping each value visible while it's being changed,\neven though the control draws no visible label of its own.\n\n### Best practices\n\n- **Name both handles.** Pass `thumbLabels` as a `[lower, upper]` pair (for\n  example `[\"Minimum price\", \"Maximum price\"]`) so each handle has a distinct\n  accessible name. When omitted, the handles fall back to localized\n  \"Minimum\" / \"Maximum\" — usable, but less specific than a domain label.\n- **Give the control an accessible name too.** A range slider renders no visible\n  label — place it inside `FormField.Root` with `FormField.Label`, or pass an\n  `aria-label` (or `aria-labelledby`) when there's no surrounding form field.\n  This names the group; `thumbLabels` names the individual handles.\n- **Choose a scale people can reason about.** Range sliders work best when the\n  exact numbers matter less than their position relative to the whole range —\n  pick `minValue`, `maxValue`, and `step` so most handle positions feel\n  meaningful.\n- **Summarize the selected range with `FormField.Description`, not a duplicate\n  readout.** Each handle's value already appears in its tooltip on hover, focus,\n  or drag. A `FormField.Description` that states the current bounds (e.g. a price\n  range) is a separate, permanent piece of context and is fine to keep — don't\n  add a second number readout right beside the track that just repeats the\n  tooltip.\n- **Reach for `RangeSlider` when both bounds are set together by feel.** Its two\n  handles can't cross, so it guarantees the lower value never exceeds the upper\n  one — useful for filters like price, distance, or rating ranges.\n- **Disable, don't hide.** When the range is temporarily not applicable, disable\n  it with `isDisabled` rather than removing it from the layout, so surrounding\n  controls don't shift.\n\n### Usage\n\nA range slider lets users choose a lower and an upper bound by dragging two\nhandles along a shared track, best for ranges that are set by feel rather than\ntyped precisely.\n\n> [!TIP]\\\n> When to use\n>\n> - Filtering by a numeric range set by feel, such as price, distance, or\n>   rating.\n> - Both a lower and an upper bound need to be chosen together, and the pair\n>   must stay valid (lower ≤ upper).\n> - The exact numbers matter less than their position relative to the minimum\n>   and maximum.\n\n> [!CAUTION]\\\n> When not to use\n>\n> - Only a single value is needed — use [`Slider`](/components/inputs/slider)\n>   instead.\n> - The bounds must be typed precisely, or fall outside a small, well-known\n>   range — pair two `NumberInput`s instead.\n> - Users need to see the min/max bounds labeled directly on the track — that\n>   isn't supported yet; consider pairing the slider with your own labels.\n\n### Keeping interactions simple\n\nSimple, predictable interactions matter because a range slider is operated by\nfeel — unexpected jumps or hidden values erode trust in the control.\n\n> [!TIP]\\\n> **Do**\n>\n> - Give the control a clear accessible name via `FormField.Label` or\n>   `aria-label`, and name each handle with `thumbLabels`.\n> - Set `minValue`, `maxValue`, and a `step` that make sense for the data.\n> - Summarize the current bounds in a `FormField.Description` when a permanent\n>   readout adds context.\n> - Let the disabled state show when the range can't currently be changed.\n\n```jsx live\nconst App = () => {\n  const [range, setRange] = useState([20, 80]);\n\n  return (\n    <Stack gap=\"200\" alignItems=\"start\">\n      <FormField.Root>\n        <FormField.Label>Price range</FormField.Label>\n        <FormField.Input>\n          <RangeSlider\n            thumbLabels={[\"Minimum price\", \"Maximum price\"]}\n            value={range}\n            onChange={setRange}\n            minValue={0}\n            maxValue={200}\n            formatOptions={{ style: \"currency\", currency: \"USD\" }}\n          />\n        </FormField.Input>\n        <FormField.Description>\n          ${range[0]} – ${range[1]}\n        </FormField.Description>\n      </FormField.Root>\n    </Stack>\n  );\n};\n```\n\n> [!CAUTION]\\\n> **Don't**\n>\n> - Leave the control without any accessible name — a bare `<RangeSlider />`\n>   with no `aria-label` and no `FormField.Label` is unusable with a screen\n>   reader.\n> - Duplicate the tooltip's job by placing a bare numeric readout directly\n>   beside the track — the tooltips already cover that on hover, focus, and\n>   drag.\n> - Use a range slider for bounds that require exact, typed precision.\n\n```tsx\n// Missing an accessible name — screen reader users have no way to know what\n// this control is for, and the handles are unnamed.\n<RangeSlider defaultValue={[20, 60]} minValue={0} maxValue={100} />\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": "Keeping interactions simple",
+          "href": "#keeping-interactions-simple",
+          "depth": 3,
+          "numbering": [
+            1,
+            1,
+            3
+          ],
+          "parent": "root"
+        }
+      ]
+    }
+  }
+}