@commercetools/nimbus-mcp 3.3.0 → 3.5.0

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

@@ -0,0 +1,611 @@
+{
+  "meta": {
+    "id": "Components-Slider",
+    "title": "Slider",
+    "exportName": "Slider",
+    "description": "A slider lets users select a numeric value, or a numeric range, by dragging a handle along a track.",
+    "lifecycleState": "Beta",
+    "order": 999,
+    "repoPath": "packages/nimbus/src/components/slider/slider.mdx",
+    "menu": [
+      "Components",
+      "Inputs",
+      "Slider"
+    ],
+    "route": "components/inputs/slider",
+    "tags": [
+      "component",
+      "slider",
+      "range 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": "Size",
+        "href": "#size",
+        "depth": 3,
+        "numbering": [
+          1,
+          2,
+          1
+        ],
+        "parent": "root"
+      },
+      {
+        "value": "Variants",
+        "href": "#variants",
+        "depth": 3,
+        "numbering": [
+          1,
+          2,
+          2
+        ],
+        "parent": "root"
+      },
+      {
+        "value": "Orientation",
+        "href": "#orientation",
+        "depth": 3,
+        "numbering": [
+          1,
+          2,
+          3
+        ],
+        "parent": "root"
+      },
+      {
+        "value": "Ticks",
+        "href": "#ticks",
+        "depth": 3,
+        "numbering": [
+          1,
+          2,
+          4
+        ],
+        "parent": "root"
+      },
+      {
+        "value": "Range",
+        "href": "#range",
+        "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 slider lets people choose a value by dragging a handle along a track, instead\nof typing a number. It's a good fit whenever the exact number matters less than\nits position relative to the whole scale, such as volume, zoom, opacity, or\nbrightness.\n\n`Slider` selects a single value. To select a range — a lower and an upper bound\nat once — use the [Range Slider](/components/inputs/range-slider), which shares\nthe same track, handle, and tick styling, so a page that mixes single and range\nsliders still looks consistent.\n\nThe slider draws no label or static \"current value\" readout of its own. The\ncurrent value appears in a small tooltip above the handle while it's hovered,\nfocused, or being dragged — the track stays visually quiet the rest of the time.\nThe label comes from the surrounding `FormField`, or from an `aria-label` when\nthe slider is used on its own.\n\n### Key features\n\n- **Tooltip value display:** the current value shows above the handle on hover,\n  focus, or drag — there's no permanent number next to the track.\n- **Range selection:** the [Range Slider](/components/inputs/range-slider) uses\n  two handles that can't be dragged past each other, for choosing a min–max\n  range.\n- **Tick marks:** an optional row of marks along the track for scales where the\n  discrete steps matter (e.g. star ratings, quality levels).\n- **Horizontal and vertical:** either orientation is available for layouts where\n  a vertical control reads more naturally (e.g. a mixing-desk-style fader).\n\n### Resources\n\n- [W3C ARIA Authoring Practices: Slider pattern](https://www.w3.org/WAI/ARIA/apg/patterns/slider/)\n\n## Variables\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    <Slider aria-label=\"Small\" size=\"sm\" defaultValue={30} />\n    <Slider aria-label=\"Medium (default)\" size=\"md\" defaultValue={30} />\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. The\n  safest choice for most forms and settings panels.\n- **Minimal** — a thin neutral track carrying a single-color handle; the track\n  grows to full width on hover or focus. For low-emphasis controls where a full\n  colored progress bar would over-emphasize the value, such as a thumbnail-size\n  picker.\n- **Enclosed** — a thick, contained bar with the handle inset inside it (an\n  iOS-style control). Good for touch-first contexts or standalone controls that\n  benefit from a larger, more tactile target.\n\n```jsx live\nconst App = () => (\n  <Stack direction=\"horizontal\" gap=\"600\" alignItems=\"center\">\n    <Slider aria-label=\"Filled (default)\" variant=\"filled\" defaultValue={60} />\n    <Slider aria-label=\"Minimal\" variant=\"minimal\" defaultValue={60} />\n    <Slider aria-label=\"Enclosed\" variant=\"enclosed\" defaultValue={75} />\n  </Stack>\n);\n```\n\n### Orientation\n\n`horizontal` is the default. `vertical` is useful for fader-style controls or\nwhen horizontal space is limited.\n\n```jsx live\nconst App = () => (\n  <Stack direction=\"horizontal\" gap=\"600\" alignItems=\"flex-start\">\n    <Slider aria-label=\"Horizontal\" defaultValue={40} />\n    <Slider aria-label=\"Vertical\" defaultValue={40} orientation=\"vertical\" />\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.\n\n```jsx live\nconst App = () => (\n  <Slider\n    aria-label=\"Rating\"\n    defaultValue={50}\n    minValue={0}\n    maxValue={100}\n    step={25}\n    showTicks\n  />\n);\n```\n\n### Range\n\nTo select a range — a lower and an upper bound — with two handles, use the\n[Range Slider](/components/inputs/range-slider). It shares the same size,\nvariant, orientation, and tick options shown above.\n",
+  "views": {
+    "overview": {
+      "mdx": "\n## Overview\n\nA slider lets people choose a value by dragging a handle along a track, instead\nof typing a number. It's a good fit whenever the exact number matters less than\nits position relative to the whole scale, such as volume, zoom, opacity, or\nbrightness.\n\n`Slider` selects a single value. To select a range — a lower and an upper bound\nat once — use the [Range Slider](/components/inputs/range-slider), which shares\nthe same track, handle, and tick styling, so a page that mixes single and range\nsliders still looks consistent.\n\nThe slider draws no label or static \"current value\" readout of its own. The\ncurrent value appears in a small tooltip above the handle while it's hovered,\nfocused, or being dragged — the track stays visually quiet the rest of the time.\nThe label comes from the surrounding `FormField`, or from an `aria-label` when\nthe slider is used on its own.\n\n### Key features\n\n- **Tooltip value display:** the current value shows above the handle on hover,\n  focus, or drag — there's no permanent number next to the track.\n- **Range selection:** the [Range Slider](/components/inputs/range-slider) uses\n  two handles that can't be dragged past each other, for choosing a min–max\n  range.\n- **Tick marks:** an optional row of marks along the track for scales where the\n  discrete steps matter (e.g. star ratings, quality levels).\n- **Horizontal and vertical:** either orientation is available for layouts where\n  a vertical control reads more naturally (e.g. a mixing-desk-style fader).\n\n### Resources\n\n- [W3C ARIA Authoring Practices: Slider pattern](https://www.w3.org/WAI/ARIA/apg/patterns/slider/)\n\n## Variables\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    <Slider aria-label=\"Small\" size=\"sm\" defaultValue={30} />\n    <Slider aria-label=\"Medium (default)\" size=\"md\" defaultValue={30} />\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. The\n  safest choice for most forms and settings panels.\n- **Minimal** — a thin neutral track carrying a single-color handle; the track\n  grows to full width on hover or focus. For low-emphasis controls where a full\n  colored progress bar would over-emphasize the value, such as a thumbnail-size\n  picker.\n- **Enclosed** — a thick, contained bar with the handle inset inside it (an\n  iOS-style control). Good for touch-first contexts or standalone controls that\n  benefit from a larger, more tactile target.\n\n```jsx live\nconst App = () => (\n  <Stack direction=\"horizontal\" gap=\"600\" alignItems=\"center\">\n    <Slider aria-label=\"Filled (default)\" variant=\"filled\" defaultValue={60} />\n    <Slider aria-label=\"Minimal\" variant=\"minimal\" defaultValue={60} />\n    <Slider aria-label=\"Enclosed\" variant=\"enclosed\" defaultValue={75} />\n  </Stack>\n);\n```\n\n### Orientation\n\n`horizontal` is the default. `vertical` is useful for fader-style controls or\nwhen horizontal space is limited.\n\n```jsx live\nconst App = () => (\n  <Stack direction=\"horizontal\" gap=\"600\" alignItems=\"flex-start\">\n    <Slider aria-label=\"Horizontal\" defaultValue={40} />\n    <Slider aria-label=\"Vertical\" defaultValue={40} orientation=\"vertical\" />\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.\n\n```jsx live\nconst App = () => (\n  <Slider\n    aria-label=\"Rating\"\n    defaultValue={50}\n    minValue={0}\n    maxValue={100}\n    step={25}\n    showTicks\n  />\n);\n```\n\n### Range\n\nTo select a range — a lower and an upper bound — with two handles, use the\n[Range Slider](/components/inputs/range-slider). It shares the same size,\nvariant, orientation, and tick options shown above.\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": "Size",
+          "href": "#size",
+          "depth": 3,
+          "numbering": [
+            1,
+            2,
+            1
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Variants",
+          "href": "#variants",
+          "depth": 3,
+          "numbering": [
+            1,
+            2,
+            2
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Orientation",
+          "href": "#orientation",
+          "depth": 3,
+          "numbering": [
+            1,
+            2,
+            3
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Ticks",
+          "href": "#ticks",
+          "depth": 3,
+          "numbering": [
+            1,
+            2,
+            4
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Range",
+          "href": "#range",
+          "depth": 3,
+          "numbering": [
+            1,
+            2,
+            5
+          ],
+          "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`Slider` renders no visible label of its own, so an accessible name must always\ncome from somewhere — either `FormField.Label` when composed inside a form\nfield, or an `aria-label` / `aria-labelledby` when used standalone.\n\n```jsx live\nconst App = () => (\n  <Slider aria-label=\"Volume\" defaultValue={30} minValue={0} maxValue={100} />\n);\n```\n\n### Accessibility standards\n\n- Always give the slider an accessible name: `aria-label` (or\n  `aria-labelledby`) standalone, or `FormField.Label` when composed inside\n  `FormField.Root`. A slider with no accessible name is unusable with a screen\n  reader.\n- For selecting a range with two handles, see the\n  [Range Slider](/components/inputs/range-slider), which has its own per-handle\n  labeling requirements (`thumbLabels`).\n- The current value is exposed to assistive technology through the handle's\n  native value, not just the visual tooltip — screen readers announce it\n  without needing the tooltip to be open.\n- Support full keyboard interaction: `Tab` to focus a handle, `Arrow` keys to\n  adjust by `step`, and `Home` / `End` to jump to the minimum / maximum.\n- Ensure sufficient color contrast for the track, fill, and handle in every\n  state (default, hover, focus, dragging, disabled, invalid).\n- Communicate the invalid state with both a visual cue and a\n  `FormField.Error` message — never color alone.\n- The invalid visual cue comes from `data-invalid` on the root element, not\n  from `aria-invalid` on the underlying range input — React Aria's `Slider`\n  has no validation-state concept of its own (unlike text-style inputs).\n  Assistive technology instead picks up the invalid state through the\n  associated `FormField.Error` text, which the slider's group references via\n  `aria-describedby`.\n- Clearly indicate the focused handle with a visible focus ring.\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 pattern](https://www.w3.org/WAI/ARIA/apg/patterns/slider/)\n",
+      "toc": [
+        {
+          "value": "Accessibility",
+          "href": "#accessibility",
+          "depth": 2,
+          "numbering": [
+            1,
+            1
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Accessibility standards",
+          "href": "#accessibility-standards",
+          "depth": 3,
+          "numbering": [
+            1,
+            1,
+            1
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Resources",
+          "href": "#resources",
+          "depth": 3,
+          "numbering": [
+            1,
+            1,
+            2
+          ],
+          "parent": "root"
+        }
+      ]
+    },
+    "dev": {
+      "mdx": "\n## Getting started\n\n### Import\n\n```tsx\nimport { Slider, type SliderProps } from \"@commercetools/nimbus\";\n```\n\n### Basic usage\n\n`Slider` selects a single `number`. It renders no visible label and no static\nvalue readout — the current value appears in a tooltip above the handle while\nit's hovered, focused, or dragged, so an accessible name must be supplied\nseparately (see [Accessibility](#accessibility) below).\n\n```jsx live-dev\nconst App = () => (\n  <Slider aria-label=\"Volume\" defaultValue={30} minValue={0} maxValue={100} />\n);\n```\n\n> Need to select a range with two handles instead of a single value? See the\n> [Range Slider](/components/inputs/range-slider) component — it shares the same\n> track, handle, and tick styling.\n\n## Usage examples\n\n### Size options\n\n`sm` and `md` size variants are available to match surrounding density.\n\n```jsx live-dev\nconst App = () => (\n  <Stack direction=\"column\" gap=\"600\">\n    <Slider aria-label=\"Small\" size=\"sm\" defaultValue={30} />\n    <Slider aria-label=\"Medium (default)\" size=\"md\" defaultValue={30} />\n  </Stack>\n);\n```\n\n### Visual variants\n\n`variant` changes the track/progress/thumb treatment. `filled` (the default) is\nthe standard thin track with a colored progress fill; `minimal` is a thin\nneutral track with a single-color handle that grows to full width on hover/focus\n(a single slider shows no progress fill), for low-emphasis controls such as a\nthumbnail-size picker; `enclosed` is a thick, contained bar\nwith the thumb inset inside it. The same variants apply to the\n[Range Slider](/components/inputs/range-slider), since they share the same\nrecipe.\n\n```jsx live-dev\nconst App = () => (\n  <Stack direction=\"column\" gap=\"600\">\n    <Slider aria-label=\"Filled\" variant=\"filled\" defaultValue={60} />\n    <Slider aria-label=\"Minimal\" variant=\"minimal\" defaultValue={60} />\n    <Slider aria-label=\"Enclosed\" variant=\"enclosed\" defaultValue={75} />\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  <Stack direction=\"row\" gap=\"600\" alignItems=\"flex-start\">\n    <Slider aria-label=\"Horizontal\" defaultValue={40} />\n    <Slider aria-label=\"Vertical\" defaultValue={40} orientation=\"vertical\" />\n  </Stack>\n);\n```\n\n### Tick marks\n\nSet `showTicks` to render a mark at every `tickStep` interval (falling back to\n`step` when `tickStep` is omitted). Useful for scales where the discrete stops\nthemselves are meaningful, such as ratings.\n\n```jsx live-dev\nconst App = () => (\n  <Slider\n    aria-label=\"Rating\"\n    defaultValue={50}\n    minValue={0}\n    maxValue={100}\n    step={25}\n    showTicks\n  />\n);\n```\n\n**Behavioral notes:**\n\n- `tickStep` controls the spacing between ticks; it defaults to `step` when\n  `showTicks` is set and `tickStep` is omitted.\n- Ticks are purely visual — they don't constrain which values the handle can\n  land on. Use `step` for that.\n- Ticks are spaced evenly starting from `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\nin the handle's tooltip, without changing the underlying numeric value.\n\n```jsx live-dev\nconst App = () => (\n  <Stack direction=\"column\" gap=\"600\">\n    <Slider\n      aria-label=\"Discount\"\n      defaultValue={0.2}\n      minValue={0}\n      maxValue={1}\n      step={0.01}\n      formatOptions={{ style: \"percent\" }}\n    />\n    <Slider\n      aria-label=\"Price\"\n      defaultValue={49}\n      minValue={0}\n      maxValue={200}\n      formatOptions={{ style: \"currency\", currency: \"USD\" }}\n    />\n  </Stack>\n);\n```\n\n### Disabled state\n\nDisable interaction with `isDisabled`.\n\n```jsx live-dev\nconst App = () => (\n  <Slider\n    aria-label=\"Volume\"\n    defaultValue={30}\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 is a stand-in for **your own** application code\nreacting to the live value (e.g. updating a preview elsewhere on the page) —\nit's a demo of what `onChange` gives you, not a recommended \"value readout\nbeside the track\" pattern; the slider's own tooltip already shows the value on\nhover, focus, and drag (see the Guidelines tab).\n\n```jsx live-dev\nconst App = () => {\n  const [value, setValue] = useState(30);\n\n  return (\n    <Stack direction=\"column\" gap=\"400\">\n      <Slider\n        aria-label=\"Volume\"\n        defaultValue={30}\n        minValue={0}\n        maxValue={100}\n        onChange={setValue}\n      />\n      <Text fontSize=\"sm\">Current value (for demo purposes): {value}</Text>\n    </Stack>\n  );\n};\n```\n\n**Note:** `Slider`'s `onChange` receives the numeric value directly, not an\nevent object. `onChangeEnd` fires once when the interaction (drag or key press)\nsettles, rather than on every intermediate change.\n\n### Controlled mode\n\nFor scenarios requiring programmatic control, use controlled mode:\n\n```jsx live-dev\nconst App = () => {\n  const [value, setValue] = useState(50);\n\n  return (\n    <Stack direction=\"column\" gap=\"400\">\n      <Slider\n        aria-label=\"Zoom\"\n        value={value}\n        onChange={setValue}\n        minValue={0}\n        maxValue={100}\n      />\n      <Stack direction=\"row\" gap=\"300\">\n        <Button onPress={() => setValue(0)}>Reset</Button>\n        <Button onPress={() => setValue(50)}>Set to 50</Button>\n        <Button onPress={() => setValue(100)}>Set to 100</Button>\n      </Stack>\n    </Stack>\n  );\n};\n```\n\n## Component requirements\n\n### Accessibility\n\n`Slider` handles keyboard, pointer, touch, and RTL behavior internally via React\nAria. However, unlike most Nimbus inputs, **it renders no visible label or a\nstatic value readout** — the current value is only ever shown in a tooltip above\nthe handle while it's hovered, focused, or dragged. You must always supply an\naccessible name through one of the following:\n\n- Composing inside `FormField.Root` with `FormField.Label` (recommended for\n  forms):\n\n```tsx\n<FormField.Root>\n  <FormField.Label>Opacity</FormField.Label>\n  <FormField.Input>\n    <Slider defaultValue={80} minValue={0} maxValue={100} />\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<Slider aria-label=\"Opacity\" defaultValue={80} minValue={0} maxValue={100} />\n```\n\n- Associating an existing `<label>` element via `aria-labelledby`:\n\n```tsx\n<label id=\"opacity-label\">Opacity</label>\n<Slider aria-labelledby=\"opacity-label\" defaultValue={80} minValue={0} maxValue={100} />\n```\n\nIf your use case requires tracking and analytics for this component, it is good\npractice to add a **persistent**, **unique** id:\n\n```tsx\nconst PERSISTENT_ID = \"settings-opacity-slider\";\n\nexport const OpacitySlider = () => (\n  <Slider id={PERSISTENT_ID} minValue={0} maxValue={100} />\n);\n```\n\n#### Keyboard navigation\n\nThe component supports full keyboard interaction:\n\n- `Tab` / `Shift+Tab`: move focus to/from the handle.\n- `Arrow Left` / `Arrow Right` (or `Arrow Down` / `Arrow Up` when\n  `orientation=\"vertical\"`): decrement/increment the handle's value by `step`.\n- `Page Down` / `Page Up`: decrement/increment by a larger amount.\n- `Home`: jump the handle to `minValue`.\n- `End`: jump the handle to `maxValue`.\n\n## API reference\n\n<PropsTable id=\"Slider\" />\n\nThe [Range Slider](/components/inputs/range-slider) has its own API reference on\nits Implementation tab.\n\n## Common patterns\n\n### Slider 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>Opacity</FormField.Label>\n    <FormField.Input>\n      <Slider defaultValue={50} minValue={0} maxValue={100} />\n    </FormField.Input>\n    <FormField.Description>Adjust layer opacity</FormField.Description>\n    <FormField.Error>Value is out of range</FormField.Error>\n  </FormField.Root>\n);\n```\n\n## Testing your implementation\n\nThese examples demonstrate how to test your implementation when using Slider\nwithin your application. As the component's internal functionality is already\ntested by Nimbus, these patterns help you verify your integration and\napplication-specific logic.\n\n### Basic Rendering Tests\n\nVerify the slider renders with expected elements and no visible label\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 { Slider, FormField, NimbusProvider } from \"@commercetools/nimbus\";\n\ndescribe(\"Slider - Basic rendering\", () => {\n  it(\"renders a slider handle with the given accessible name and initial value\", () => {\n    render(\n      <NimbusProvider>\n        <Slider\n          aria-label=\"Volume\"\n          defaultValue={30}\n          minValue={0}\n          maxValue={100}\n        />\n      </NimbusProvider>\n    );\n\n    const thumb = screen.getByRole(\"slider\", { name: /volume/i });\n    expect(thumb).toBeInTheDocument();\n    expect(thumb).toHaveValue(\"30\");\n  });\n\n  it(\"renders no visible label or static value output\", () => {\n    render(\n      <NimbusProvider>\n        <Slider\n          aria-label=\"Volume\"\n          defaultValue={30}\n          minValue={0}\n          maxValue={100}\n        />\n      </NimbusProvider>\n    );\n\n    // The accessible name comes from aria-label; no visible \"Volume\" text\n    // or standalone \"30\" readout is rendered next to the track.\n    expect(screen.queryByText(\"Volume\")).not.toBeInTheDocument();\n  });\n});\n```\n\n### Interaction Tests\n\nTest keyboard interactions and onChange behavior\n\n```tsx\nimport { describe, it, expect, vi } from \"vitest\";\nimport { render, screen } from \"@testing-library/react\";\nimport userEvent from \"@testing-library/user-event\";\nimport { Slider, FormField, NimbusProvider } from \"@commercetools/nimbus\";\n\ndescribe(\"Slider - Interactions\", () => {\n  it(\"calls onChange with the updated value on keyboard interaction\", async () => {\n    const user = userEvent.setup();\n    const handleChange = vi.fn();\n    render(\n      <NimbusProvider>\n        <Slider\n          aria-label=\"Volume\"\n          defaultValue={30}\n          minValue={0}\n          maxValue={100}\n          onChange={handleChange}\n        />\n      </NimbusProvider>\n    );\n\n    const thumb = screen.getByRole(\"slider\");\n    thumb.focus();\n    await user.keyboard(\"{ArrowRight}\");\n\n    expect(thumb).toHaveValue(\"31\");\n    expect(handleChange).toHaveBeenCalledWith(31);\n  });\n\n  it(\"jumps to minValue/maxValue with Home/End\", async () => {\n    const user = userEvent.setup();\n    render(\n      <NimbusProvider>\n        <Slider\n          aria-label=\"Volume\"\n          defaultValue={30}\n          minValue={0}\n          maxValue={100}\n        />\n      </NimbusProvider>\n    );\n\n    const thumb = screen.getByRole(\"slider\");\n    thumb.focus();\n\n    await user.keyboard(\"{End}\");\n    expect(thumb).toHaveValue(\"100\");\n\n    await user.keyboard(\"{Home}\");\n    expect(thumb).toHaveValue(\"0\");\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 { Slider, FormField, NimbusProvider } from \"@commercetools/nimbus\";\n\ndescribe(\"Slider - States\", () => {\n  it(\"handles disabled state\", () => {\n    render(\n      <NimbusProvider>\n        <Slider\n          aria-label=\"Volume\"\n          defaultValue={30}\n          minValue={0}\n          maxValue={100}\n          isDisabled\n        />\n      </NimbusProvider>\n    );\n\n    expect(screen.getByRole(\"slider\")).toBeDisabled();\n  });\n\n  it(\"surfaces the invalid state on the root element\", () => {\n    const { container } = render(\n      <NimbusProvider>\n        <Slider\n          aria-label=\"Volume\"\n          defaultValue={30}\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 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 { Slider, FormField, NimbusProvider } from \"@commercetools/nimbus\";\n\ndescribe(\"Slider - FormField integration\", () => {\n  it(\"resolves an accessible name from FormField.Label\", () => {\n    render(\n      <NimbusProvider>\n        <FormField.Root>\n          <FormField.Label>Opacity</FormField.Label>\n          <FormField.Input>\n            <Slider defaultValue={50} minValue={0} maxValue={100} />\n          </FormField.Input>\n          <FormField.Description>Adjust layer opacity</FormField.Description>\n        </FormField.Root>\n      </NimbusProvider>\n    );\n\n    const thumb = screen.getByRole(\"slider\");\n    // aria-labelledby is not transitive per WAI-ARIA, so React Aria composes\n    // the thumb's name from the group's content-based fallback name, which\n    // includes the thumb's own live value — match by substring rather than\n    // an exact string.\n    expect(thumb).toHaveAccessibleName(/Opacity/);\n  });\n\n  it(\"surfaces the invalid state from FormField.Root\", () => {\n    const { container } = render(\n      <NimbusProvider>\n        <FormField.Root isInvalid>\n          <FormField.Label>Opacity</FormField.Label>\n          <FormField.Input>\n            <Slider defaultValue={50} minValue={0} maxValue={100} />\n          </FormField.Input>\n          <FormField.Error>Value is out of range</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### Visual Variants Tests\n\nEach visual variant renders an operable slider.\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 { Slider, FormField, NimbusProvider } from \"@commercetools/nimbus\";\n\ndescribe(\"Slider - Visual variants\", () => {\n  it.each([\"filled\", \"minimal\", \"enclosed\"] as const)(\n    \"renders an operable %s variant slider\",\n    (variant) => {\n      render(\n        <NimbusProvider>\n          <Slider\n            aria-label={`${variant} slider`}\n            variant={variant}\n            defaultValue={50}\n          />\n        </NimbusProvider>\n      );\n\n      expect(screen.getByRole(\"slider\")).toHaveValue(\"50\");\n    }\n  );\n});\n```\n\n\n## Resources\n\n- [Storybook: Slider](https://nimbus-storybook.vercel.app/?path=/docs/components-slider--docs)\n- [Range Slider](/components/inputs/range-slider) — the two-handle range counterpart\n- [React Aria Slider](https://react-spectrum.adobe.com/react-aria/Slider.html)\n- [W3C ARIA Authoring Practices Guide (APG): Slider pattern](https://www.w3.org/WAI/ARIA/apg/patterns/slider/)\n",
+      "toc": [
+        {
+          "value": "Getting started",
+          "href": "#getting-started",
+          "depth": 2,
+          "numbering": [
+            1,
+            1
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Import",
+          "href": "#import",
+          "depth": 3,
+          "numbering": [
+            1,
+            1,
+            1
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Basic usage",
+          "href": "#basic-usage",
+          "depth": 3,
+          "numbering": [
+            1,
+            1,
+            2
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Usage examples",
+          "href": "#usage-examples",
+          "depth": 2,
+          "numbering": [
+            1,
+            2
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Size options",
+          "href": "#size-options",
+          "depth": 3,
+          "numbering": [
+            1,
+            2,
+            1
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Visual variants",
+          "href": "#visual-variants",
+          "depth": 3,
+          "numbering": [
+            1,
+            2,
+            2
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Orientation",
+          "href": "#orientation",
+          "depth": 3,
+          "numbering": [
+            1,
+            2,
+            3
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Tick marks",
+          "href": "#tick-marks",
+          "depth": 3,
+          "numbering": [
+            1,
+            2,
+            4
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Value formatting",
+          "href": "#value-formatting",
+          "depth": 3,
+          "numbering": [
+            1,
+            2,
+            5
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Disabled state",
+          "href": "#disabled-state",
+          "depth": 3,
+          "numbering": [
+            1,
+            2,
+            6
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Uncontrolled mode",
+          "href": "#uncontrolled-mode",
+          "depth": 3,
+          "numbering": [
+            1,
+            2,
+            7
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Controlled mode",
+          "href": "#controlled-mode",
+          "depth": 3,
+          "numbering": [
+            1,
+            2,
+            8
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Component requirements",
+          "href": "#component-requirements",
+          "depth": 2,
+          "numbering": [
+            1,
+            3
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Accessibility",
+          "href": "#accessibility",
+          "depth": 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": "Slider inside a form field with validation",
+          "href": "#slider-inside-a-form-field-with-validation",
+          "depth": 3,
+          "numbering": [
+            1,
+            5,
+            1
+          ],
+          "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": "Visual Variants Tests",
+          "href": "#visual-variants-tests",
+          "depth": 3,
+          "numbering": [
+            1,
+            6,
+            5
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Resources",
+          "href": "#resources",
+          "depth": 2,
+          "numbering": [
+            1,
+            7
+          ],
+          "parent": "root"
+        }
+      ]
+    },
+    "guidelines": {
+      "mdx": "\n## Guidelines\n\nSlider guidelines focus on picking a scale users can reason about, keeping the\nvalue visible while it's being changed, and always giving the control an\naccessible name, even though it draws no visible label of its own.\n\n### Best practices\n\n- **Always provide an accessible name.** A slider renders no visible label —\n  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- **Choose a scale people can reason about.** Sliders work best when the exact\n  number matters less than its position relative to the whole range — pick\n  `minValue`, `maxValue`, and `step` so most handle positions feel meaningful.\n- **Show ticks only when the steps matter.** Turn on `showTicks` for scales\n  with a handful of meaningful stops (star ratings, quality levels); leave it\n  off for continuous-feeling values like volume or opacity, where ticks would\n  just add visual noise.\n- **Rely on the value tooltip at the track, not a duplicate readout.** The\n  current value already appears above the handle on hover, focus, or drag —\n  don't add a second number readout right next to the slider that just\n  repeats it. A `FormField.Description` summarizing the selection elsewhere\n  in the form (e.g. a range's bounds) is a separate, permanent piece of\n  context and is fine to keep.\n- **Reach for the [Range Slider](/components/inputs/range-slider) for bounded\n  ranges.** Its two handles can't cross, so it guarantees the lower value never\n  exceeds the upper one — useful for filters like price or distance ranges.\n- **Disable, don't hide.** When a slider's value is temporarily not\n  applicable, disable it with `isDisabled` rather than removing it from the\n  layout, so surrounding controls don't shift.\n\n### Usage\n\nA slider lets users choose a value by dragging a handle along a track, best for\nvalues that are set by feel rather than typed precisely. To choose a range\ninstead, use the [Range Slider](/components/inputs/range-slider).\n\n> [!TIP]\\\n> When to use\n>\n> - Selecting a value from a continuous or stepped numeric scale by feel, such\n>   as volume, zoom, opacity, or brightness.\n> - The exact number matters less than its position relative to the minimum\n>   and maximum.\n\n> [!CAUTION]\\\n> When not to use\n>\n> - The value must be typed precisely, or falls outside a small, well-known\n>   range — use `NumberInput` instead.\n> - The input isn't really a position on a scale (e.g. a multi-step wizard or\n>   a list of unrelated options) — a slider implies a continuum, not a\n>   sequence of unrelated choices.\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 slider is operated by feel —\nunexpected jumps or hidden values erode trust in the control.\n\n> [!TIP]\\\n> **Do**\n>\n> - Give the slider a clear accessible name via `FormField.Label` or\n>   `aria-label`.\n> - Set `minValue`, `maxValue`, and a `step` that make sense for the data.\n> - Use `showTicks` when the discrete stops themselves are meaningful.\n> - Reach for the [Range Slider](/components/inputs/range-slider) when both a\n>   lower and upper bound need to be set together.\n> - Let the disabled state show when the value can't currently be changed.\n\n```jsx live\nconst App = () => (\n  <Stack gap=\"200\" alignItems=\"start\">\n    <FormField.Root>\n      <FormField.Label>Opacity</FormField.Label>\n      <FormField.Input>\n        <Slider defaultValue={80} minValue={0} maxValue={100} />\n      </FormField.Input>\n      <FormField.Description>\n        Adjust how transparent the layer appears.\n      </FormField.Description>\n    </FormField.Root>\n  </Stack>\n);\n```\n\n> [!CAUTION]\\\n> **Don't**\n>\n> - Leave the slider without any accessible name — a bare `<Slider />` with no\n>   `aria-label` and no `FormField.Label` is unusable with a screen reader.\n> - Duplicate the tooltip's job by placing a bare numeric readout directly\n>   beside the track — the tooltip already covers that on hover, focus, and\n>   drag. A `FormField.Description` that summarizes the selection for context\n>   (e.g. a price range below the control) is a different thing: it's a\n>   permanent summary for users who aren't actively interacting with the\n>   slider, not a redundant echo of the tooltip.\n> - Use a slider for values that require exact, typed precision.\n\n```tsx\n// Missing an accessible name — screen reader users have no way to know\n// what this control is for.\n<Slider defaultValue={30} 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"
+        }
+      ]
+    }
+  }
+}