@delightui/components 0.1.105 → 0.1.107

package/docs/components/atoms/Slider.md

@@ -0,0 +1,605 @@
+# Slider
+
+A versatile slider component that allows users to select numeric values within a specified range. It supports both single-value and range selection modes, with customizable min/max values, step sizes, and display options. The component integrates seamlessly with forms and provides visual feedback for the selected values.
+
+## Aliases
+
+- Slider
+- Range
+- RangeSlider
+
+## Props Breakdown
+
+**Extends:** `HTMLAttributes<HTMLDivElement>` and `ControlledFormComponentProps<number | [number, number]>`
+
+| Prop | Type | Default | Required | Description |
+|------|------|---------|----------|-------------|
+| `min` | `number` | `0` | No | The minimum value of the slider |
+| `max` | `number` | `100` | No | The maximum value of the slider |
+| `step` | `number` | `1` | No | The step size for the slider |
+| `showMin` | `boolean` | `false` | No | Whether to display the minimum value label |
+| `showMax` | `boolean` | `false` | No | Whether to display the maximum value label |
+| `showValueOnThumb` | `boolean` | `false` | No | Whether to show the current value on the slider thumb |
+| `enableRange` | `boolean` | `false` | No | Whether to enable range selection (two thumbs) |
+| `className` | `string` | `undefined` | No | Additional class for styling |
+| `initialValue` | `number \| [number, number]` | `undefined` | No | The initial value for the field |
+| `checked` | `boolean` | `undefined` | No | The initial value for the field |
+| `value` | `number \| [number, number]` | `undefined` | No | The current value of the form field |
+| `onValueChange` | `(value: number \| [number, number]) => void` | `undefined` | No | Callback function that is called when the field value changes |
+| `disabled` | `boolean` | `false` | No | Whether the form field is disabled and cannot be interacted with |
+| `required` | `boolean` | `false` | No | Whether the form field must have a value |
+| `invalid` | `boolean` | `false` | No | Whether the form field's current value is invalid |
+| `id` | `string` | `undefined` | No | Id for the form field |
+
+Plus all standard HTML div attributes (id, title, aria-*, data-*, etc.).
+
+## Examples
+
+### Basic Slider
+
+```tsx
+import { Slider } from '@delightui/components';
+
+function BasicSliderExample() {
+  const [value, setValue] = useState(50);
+
+  return (
+    <div>
+      <p>Value: {value}</p>
+      <Slider
+        value={value}
+        onValueChange={setValue}
+        min={0}
+        max={100}
+      />
+    </div>
+  );
+}
+```
+
+### Slider with Min/Max Labels
+
+```tsx
+import { Slider } from '@delightui/components';
+
+function SliderWithLabelsExample() {
+  const [value, setValue] = useState(25);
+
+  return (
+    <div>
+      <p>Selected Value: {value}</p>
+      <Slider
+        value={value}
+        onValueChange={setValue}
+        min={0}
+        max={100}
+        showMin
+        showMax
+      />
+    </div>
+  );
+}
+```
+
+### Slider with Value on Thumb
+
+```tsx
+import { Slider } from '@delightui/components';
+
+function SliderWithThumbValueExample() {
+  const [value, setValue] = useState(75);
+
+  return (
+    <Slider
+      value={value}
+      onValueChange={setValue}
+      min={0}
+      max={100}
+      showValueOnThumb
+      showMin
+      showMax
+    />
+  );
+}
+```
+
+### Range Slider
+
+```tsx
+import { Slider } from '@delightui/components';
+
+function RangeSliderExample() {
+  const [range, setRange] = useState<[number, number]>([20, 80]);
+
+  return (
+    <div>
+      <p>Range: {range[0]} - {range[1]}</p>
+      <Slider
+        value={range}
+        onValueChange={setRange}
+        min={0}
+        max={100}
+        enableRange
+        showMin
+        showMax
+      />
+    </div>
+  );
+}
+```
+
+### Custom Step Size
+
+```tsx
+import { Slider } from '@delightui/components';
+
+function CustomStepSliderExample() {
+  const [value, setValue] = useState(50);
+
+  return (
+    <div style={{ display: 'flex', flexDirection: 'column', gap: '20px' }}>
+      <div>
+        <p>Step 1: {value}</p>
+        <Slider
+          value={value}
+          onValueChange={setValue}
+          min={0}
+          max={100}
+          step={1}
+          showValueOnThumb
+        />
+      </div>
+
+      <div>
+        <p>Step 5: {Math.round(value / 5) * 5}</p>
+        <Slider
+          value={Math.round(value / 5) * 5}
+          onValueChange={(v) => setValue(v as number)}
+          min={0}
+          max={100}
+          step={5}
+          showValueOnThumb
+        />
+      </div>
+
+      <div>
+        <p>Step 10: {Math.round(value / 10) * 10}</p>
+        <Slider
+          value={Math.round(value / 10) * 10}
+          onValueChange={(v) => setValue(v as number)}
+          min={0}
+          max={100}
+          step={10}
+          showValueOnThumb
+        />
+      </div>
+    </div>
+  );
+}
+```
+
+### Form Integration
+
+```tsx
+import { Form, FormField, Slider, Button, Text } from '@delightui/components';
+
+function SliderFormExample() {
+  const handleSubmit = (data: any) => {
+    console.log('Form submitted:', data);
+  };
+
+  return (
+    <Form onSubmit={handleSubmit}>
+      <FormField
+        name="volume"
+        label="Volume Level"
+        required
+      >
+        <Slider
+          min={0}
+          max={100}
+          step={5}
+          showMin
+          showMax
+          showValueOnThumb
+          initialValue={50}
+        />
+      </FormField>
+
+      <FormField
+        name="priceRange"
+        label="Price Range"
+      >
+        <Slider
+          min={0}
+          max={1000}
+          step={10}
+          enableRange
+          initialValue={[100, 800]}
+          showMin
+          showMax
+        />
+      </FormField>
+
+      <FormField
+        name="difficulty"
+        label="Difficulty Level"
+      >
+        <Slider
+          min={1}
+          max={10}
+          step={1}
+          initialValue={5}
+          showValueOnThumb
+        />
+      </FormField>
+
+      <Button type="submit">
+        Save Settings
+      </Button>
+    </Form>
+  );
+}
+```
+
+### Price Range Filter
+
+```tsx
+import { Slider, Text } from '@delightui/components';
+
+function PriceRangeFilterExample() {
+  const [priceRange, setPriceRange] = useState<[number, number]>([50, 500]);
+
+  const formatPrice = (value: number) => `$${value}`;
+
+  return (
+    <div style={{ padding: '20px', border: '1px solid #ccc', borderRadius: '8px' }}>
+      <Text weight="bold" style={{ marginBottom: '16px' }}>
+        Filter by Price
+      </Text>
+      
+      <Text size="small" color="secondary" style={{ marginBottom: '12px' }}>
+        Price Range: {formatPrice(priceRange[0])} - {formatPrice(priceRange[1])}
+      </Text>
+      
+      <Slider
+        value={priceRange}
+        onValueChange={setPriceRange}
+        min={0}
+        max={1000}
+        step={10}
+        enableRange
+        showMin
+        showMax
+      />
+      
+      <div style={{ display: 'flex', justifyContent: 'space-between', marginTop: '8px' }}>
+        <Text size="small">Min: {formatPrice(priceRange[0])}</Text>
+        <Text size="small">Max: {formatPrice(priceRange[1])}</Text>
+      </div>
+    </div>
+  );
+}
+```
+
+### Temperature Control
+
+```tsx
+import { Slider, Text } from '@delightui/components';
+
+function TemperatureControlExample() {
+  const [temperature, setTemperature] = useState(72);
+
+  const getTemperatureColor = (temp: number) => {
+    if (temp < 60) return '#0066cc';
+    if (temp < 70) return '#00cc66';
+    if (temp < 80) return '#ffcc00';
+    return '#ff6600';
+  };
+
+  const getTemperatureLabel = (temp: number) => {
+    if (temp < 60) return 'Cool';
+    if (temp < 70) return 'Comfortable';
+    if (temp < 80) return 'Warm';
+    return 'Hot';
+  };
+
+  return (
+    <div style={{ 
+      padding: '20px', 
+      border: '1px solid #ccc', 
+      borderRadius: '8px',
+      backgroundColor: '#f8f9fa'
+    }}>
+      <Text weight="bold" style={{ marginBottom: '16px' }}>
+        Thermostat Control
+      </Text>
+      
+      <div style={{ textAlign: 'center', marginBottom: '20px' }}>
+        <Text 
+          size="xlarge" 
+          weight="bold" 
+          style={{ color: getTemperatureColor(temperature) }}
+        >
+          {temperature}°F
+        </Text>
+        <Text 
+          size="small" 
+          style={{ 
+            display: 'block', 
+            color: getTemperatureColor(temperature),
+            marginTop: '4px'
+          }}
+        >
+          {getTemperatureLabel(temperature)}
+        </Text>
+      </div>
+      
+      <Slider
+        value={temperature}
+        onValueChange={setTemperature}
+        min={50}
+        max={90}
+        step={1}
+        showMin
+        showMax
+        showValueOnThumb
+      />
+    </div>
+  );
+}
+```
+
+### Audio Equalizer
+
+```tsx
+import { Slider, Text } from '@delightui/components';
+
+function AudioEqualizerExample() {
+  const [frequencies, setFrequencies] = useState({
+    bass: 50,
+    midrange: 50,
+    treble: 50
+  });
+
+  const updateFrequency = (freq: string, value: number) => {
+    setFrequencies(prev => ({ ...prev, [freq]: value }));
+  };
+
+  return (
+    <div style={{ 
+      padding: '20px', 
+      border: '1px solid #ccc', 
+      borderRadius: '8px',
+      backgroundColor: '#1a1a1a',
+      color: 'white'
+    }}>
+      <Text weight="bold" style={{ marginBottom: '20px', color: 'white' }}>
+        Audio Equalizer
+      </Text>
+      
+      <div style={{ display: 'flex', gap: '24px' }}>
+        <div style={{ flex: 1 }}>
+          <Text size="small" weight="medium" style={{ marginBottom: '8px', color: 'white' }}>
+            Bass
+          </Text>
+          <div style={{ height: '150px', display: 'flex', alignItems: 'center' }}>
+            <Slider
+              value={frequencies.bass}
+              onValueChange={(value) => updateFrequency('bass', value as number)}
+              min={0}
+              max={100}
+              step={1}
+              style={{ transform: 'rotate(-90deg)', width: '120px' }}
+            />
+          </div>
+          <Text size="small" style={{ textAlign: 'center', color: '#ccc' }}>
+            {frequencies.bass}%
+          </Text>
+        </div>
+
+        <div style={{ flex: 1 }}>
+          <Text size="small" weight="medium" style={{ marginBottom: '8px', color: 'white' }}>
+            Midrange
+          </Text>
+          <div style={{ height: '150px', display: 'flex', alignItems: 'center' }}>
+            <Slider
+              value={frequencies.midrange}
+              onValueChange={(value) => updateFrequency('midrange', value as number)}
+              min={0}
+              max={100}
+              step={1}
+              style={{ transform: 'rotate(-90deg)', width: '120px' }}
+            />
+          </div>
+          <Text size="small" style={{ textAlign: 'center', color: '#ccc' }}>
+            {frequencies.midrange}%
+          </Text>
+        </div>
+
+        <div style={{ flex: 1 }}>
+          <Text size="small" weight="medium" style={{ marginBottom: '8px', color: 'white' }}>
+            Treble
+          </Text>
+          <div style={{ height: '150px', display: 'flex', alignItems: 'center' }}>
+            <Slider
+              value={frequencies.treble}
+              onValueChange={(value) => updateFrequency('treble', value as number)}
+              min={0}
+              max={100}
+              step={1}
+              style={{ transform: 'rotate(-90deg)', width: '120px' }}
+            />
+          </div>
+          <Text size="small" style={{ textAlign: 'center', color: '#ccc' }}>
+            {frequencies.treble}%
+          </Text>
+        </div>
+      </div>
+    </div>
+  );
+}
+```
+
+### Age Range Selector
+
+```tsx
+import { Slider, Text } from '@delightui/components';
+
+function AgeRangeSelectorExample() {
+  const [ageRange, setAgeRange] = useState<[number, number]>([18, 65]);
+
+  return (
+    <div style={{ padding: '20px', border: '1px solid #ccc', borderRadius: '8px' }}>
+      <Text weight="bold" style={{ marginBottom: '16px' }}>
+        Target Age Range
+      </Text>
+      
+      <Text style={{ marginBottom: '12px' }}>
+        Ages {ageRange[0]} to {ageRange[1]} years old
+      </Text>
+      
+      <Slider
+        value={ageRange}
+        onValueChange={setAgeRange}
+        min={13}
+        max={100}
+        step={1}
+        enableRange
+        showMin
+        showMax
+      />
+      
+      <div style={{ marginTop: '16px', display: 'flex', justifyContent: 'space-between' }}>
+        <div>
+          <Text size="small" color="secondary">Minimum Age</Text>
+          <Text weight="medium">{ageRange[0]}</Text>
+        </div>
+        <div style={{ textAlign: 'right' }}>
+          <Text size="small" color="secondary">Maximum Age</Text>
+          <Text weight="medium">{ageRange[1]}</Text>
+        </div>
+      </div>
+    </div>
+  );
+}
+```
+
+### Disabled Slider
+
+```tsx
+import { Slider, Text } from '@delightui/components';
+
+function DisabledSliderExample() {
+  return (
+    <div style={{ display: 'flex', flexDirection: 'column', gap: '20px' }}>
+      <div>
+        <Text weight="bold" style={{ marginBottom: '8px' }}>
+          Enabled Slider
+        </Text>
+        <Slider
+          value={75}
+          min={0}
+          max={100}
+          showMin
+          showMax
+          showValueOnThumb
+        />
+      </div>
+
+      <div>
+        <Text weight="bold" style={{ marginBottom: '8px' }}>
+          Disabled Slider
+        </Text>
+        <Slider
+          value={75}
+          min={0}
+          max={100}
+          disabled
+          showMin
+          showMax
+          showValueOnThumb
+        />
+      </div>
+
+      <div>
+        <Text weight="bold" style={{ marginBottom: '8px' }}>
+          Disabled Range Slider
+        </Text>
+        <Slider
+          value={[25, 75]}
+          min={0}
+          max={100}
+          enableRange
+          disabled
+          showMin
+          showMax
+        />
+      </div>
+    </div>
+  );
+}
+```
+
+### Custom Range Example
+
+```tsx
+import { Slider, Text } from '@delightui/components';
+
+function CustomRangeExample() {
+  const [value, setValue] = useState(2.5);
+
+  return (
+    <div style={{ display: 'flex', flexDirection: 'column', gap: '20px' }}>
+      <div>
+        <Text weight="bold" style={{ marginBottom: '8px' }}>
+          Decimal Values (0.0 - 5.0)
+        </Text>
+        <Text size="small" color="secondary" style={{ marginBottom: '8px' }}>
+          Current: {value.toFixed(1)}
+        </Text>
+        <Slider
+          value={value}
+          onValueChange={setValue}
+          min={0}
+          max={5}
+          step={0.1}
+          showMin
+          showMax
+          showValueOnThumb
+        />
+      </div>
+
+      <div>
+        <Text weight="bold" style={{ marginBottom: '8px' }}>
+          Large Range (0 - 10,000)
+        </Text>
+        <Slider
+          value={5000}
+          min={0}
+          max={10000}
+          step={100}
+          showMin
+          showMax
+          showValueOnThumb
+        />
+      </div>
+
+      <div>
+        <Text weight="bold" style={{ marginBottom: '8px' }}>
+          Negative Range (-100 to 100)
+        </Text>
+        <Slider
+          value={0}
+          min={-100}
+          max={100}
+          step={5}
+          showMin
+          showMax
+          showValueOnThumb
+        />
+      </div>
+    </div>
+  );
+}
+```