@ceed/cds 1.24.1-next.3 → 1.26.0

package/dist/components/inputs/Slider.md

@@ -0,0 +1,334 @@
+# Slider
+
+## Introduction
+
+The Slider component allows users to select a value or a range of values along a track. It is based on Joy UI's Slider and is useful for settings that require selecting from a continuous or discrete range, such as volume, brightness, price ranges, or percentage values.
+
+```tsx
+<Slider
+  defaultValue={40}
+  sx={{
+  width: 300
+}}
+/>
+```
+
+| Field             | Description | Default |
+| ----------------- | ----------- | ------- |
+| size              | —           | —       |
+| color             | —           | —       |
+| variant           | —           | —       |
+| disabled          | —           | —       |
+| orientation       | —           | —       |
+| valueLabelDisplay | —           | —       |
+| min               | —           | —       |
+| max               | —           | —       |
+| step              | —           | —       |
+
+## Usage
+
+```tsx
+import { Slider } from '@ceed/cds';
+
+function MyComponent() {
+  return <Slider defaultValue={40} />;
+}
+```
+
+## Sizes
+
+Slider supports three sizes: `sm`, `md` (default), and `lg`.
+
+```tsx
+<Stack gap={3} sx={{
+  width: 300
+}}>
+<Box>
+  <Typography level="body-sm" sx={{
+    mb: 1
+  }}>Small</Typography>
+  <Slider size="sm" defaultValue={30} />
+</Box>
+<Box>
+  <Typography level="body-sm" sx={{
+    mb: 1
+  }}>Medium</Typography>
+  <Slider size="md" defaultValue={50} />
+</Box>
+<Box>
+  <Typography level="body-sm" sx={{
+    mb: 1
+  }}>Large</Typography>
+  <Slider size="lg" defaultValue={70} />
+</Box>
+</Stack>
+```
+
+```tsx
+<Slider size="sm" defaultValue={30} />
+<Slider size="md" defaultValue={50} />
+<Slider size="lg" defaultValue={70} />
+```
+
+## Colors
+
+Five semantic colors are available via the `color` prop.
+
+```tsx
+<Stack gap={3} sx={{
+  width: 300
+}}>
+<Slider color="primary" defaultValue={40} />
+<Slider color="neutral" defaultValue={40} />
+<Slider color="danger" defaultValue={40} />
+<Slider color="success" defaultValue={40} />
+<Slider color="warning" defaultValue={40} />
+</Stack>
+```
+
+## Variants
+
+Four visual variants are supported: `solid`, `soft` (default), `outlined`, and `plain`.
+
+```tsx
+<Stack gap={3} sx={{
+  width: 300
+}}>
+<Slider variant="solid" defaultValue={40} />
+<Slider variant="soft" defaultValue={40} />
+<Slider variant="outlined" defaultValue={40} />
+<Slider variant="plain" defaultValue={40} />
+</Stack>
+```
+
+## Range Slider
+
+Pass an array of two values to `defaultValue` (or `value`) to create a range slider with two thumbs.
+
+```tsx
+<Box sx={{
+  width: 300
+}}>
+<Slider defaultValue={[20, 60]} />
+</Box>
+```
+
+```tsx
+<Slider defaultValue={[20, 60]} />
+```
+
+## With Marks
+
+Use the `marks` prop to display labeled marks along the track.
+
+```tsx
+<Box sx={{
+  width: 300
+}}>
+<Slider defaultValue={50} marks={[{
+  value: 0,
+  label: '0'
+}, {
+  value: 25,
+  label: '25'
+}, {
+  value: 50,
+  label: '50'
+}, {
+  value: 75,
+  label: '75'
+}, {
+  value: 100,
+  label: '100'
+}]} />
+</Box>
+```
+
+```tsx
+<Slider
+  defaultValue={50}
+  marks={[
+    { value: 0, label: '0' },
+    { value: 25, label: '25' },
+    { value: 50, label: '50' },
+    { value: 75, label: '75' },
+    { value: 100, label: '100' },
+  ]}
+/>
+```
+
+## Steps
+
+Set the `step` prop to control the increment between values. Use `marks={true}` to show a mark at each step.
+
+```tsx
+<Box sx={{
+  width: 300
+}}>
+<Slider defaultValue={30} step={10} marks min={0} max={100} />
+</Box>
+```
+
+```tsx
+<Slider defaultValue={30} step={10} marks min={0} max={100} />
+```
+
+## Vertical Orientation
+
+Set `orientation="vertical"` to render a vertical slider. Ensure the container has a defined height.
+
+```tsx
+<Box sx={{
+  height: 200
+}}>
+<Slider orientation="vertical" defaultValue={40} />
+</Box>
+```
+
+```tsx
+<Box sx={{ height: 200 }}>
+  <Slider orientation="vertical" defaultValue={40} />
+</Box>
+```
+
+## Value Label
+
+Control the value label tooltip display with `valueLabelDisplay`. Options: `on` (always visible), `auto` (on hover/focus), and `off` (hidden).
+
+```tsx
+<Stack gap={4} sx={{
+  width: 300,
+  pt: 4
+}}>
+<Box>
+  <Typography level="body-sm" sx={{
+    mb: 2
+  }}>Always on</Typography>
+  <Slider defaultValue={40} valueLabelDisplay="on" />
+</Box>
+<Box>
+  <Typography level="body-sm" sx={{
+    mb: 1
+  }}>Auto (on hover)</Typography>
+  <Slider defaultValue={60} valueLabelDisplay="auto" />
+</Box>
+</Stack>
+```
+
+```tsx
+<Slider defaultValue={40} valueLabelDisplay="on" />
+<Slider defaultValue={60} valueLabelDisplay="auto" />
+```
+
+## Disabled
+
+Set `disabled` to prevent user interaction.
+
+```tsx
+<Box sx={{
+  width: 300
+}}>
+<Slider defaultValue={40} disabled />
+</Box>
+```
+
+## Common Use Cases
+
+### Controlled Slider
+
+```tsx
+function VolumeControl() {
+  const [volume, setVolume] = React.useState(50);
+
+  return (
+    <Stack gap={1}>
+      <Typography level="body-sm">Volume: {volume}%</Typography>
+      <Slider
+        value={volume}
+        onChange={(_, newValue) => setVolume(newValue as number)}
+        min={0}
+        max={100}
+      />
+    </Stack>
+  );
+}
+```
+
+### Price Range Filter
+
+```tsx
+function PriceRangeFilter() {
+  const [range, setRange] = React.useState([20, 80]);
+
+  return (
+    <Stack gap={1}>
+      <Typography level="body-sm">
+        Price: ${range[0]} — ${range[1]}
+      </Typography>
+      <Slider
+        value={range}
+        onChange={(_, newValue) => setRange(newValue as number[])}
+        min={0}
+        max={200}
+        valueLabelDisplay="auto"
+        valueLabelFormat={(value) => `$${value}`}
+      />
+    </Stack>
+  );
+}
+```
+
+### Temperature Setting
+
+```tsx
+function TemperatureSetting() {
+  return (
+    <Slider
+      defaultValue={22}
+      min={16}
+      max={30}
+      step={0.5}
+      marks={[
+        { value: 16, label: '16°C' },
+        { value: 22, label: '22°C' },
+        { value: 30, label: '30°C' },
+      ]}
+      valueLabelDisplay="auto"
+      valueLabelFormat={(value) => `${value}°C`}
+    />
+  );
+}
+```
+
+## Best Practices
+
+1. **Always set `min` and `max`**: Provide explicit bounds so users understand the valid range.
+
+2. **Use marks for discrete values**: When the slider has meaningful steps, display marks with labels.
+
+```tsx
+// ✅ Clear discrete steps
+<Slider step={25} marks={[
+  { value: 0, label: 'Off' },
+  { value: 25, label: 'Low' },
+  { value: 50, label: 'Mid' },
+  { value: 75, label: 'High' },
+  { value: 100, label: 'Max' },
+]} />
+
+// ❌ Unlabeled discrete steps — user cannot tell what values mean
+<Slider step={25} />
+```
+
+3. **Show the current value**: For precise selections, use `valueLabelDisplay="on"` or display the value in nearby text.
+
+4. **Use range sliders for bounds**: When users need to define a range (min–max), pass an array value instead of two separate sliders.
+
+5. **Set a reasonable `step`**: For large ranges (0–1000), use a step > 1 to prevent overwhelming precision. For small ranges (0–1), use decimal steps.
+
+## Accessibility
+
+- Slider renders with `role="slider"` and appropriate `aria-valuemin`, `aria-valuemax`, and `aria-valuenow` attributes.
+- Keyboard support: Arrow keys increment/decrement by one step; Home/End jump to min/max.
+- Add an `aria-label` or visible label to describe what the slider controls (e.g., `aria-label="Volume"`).
+- For range sliders, each thumb has independent ARIA attributes for screen reader navigation.