@umbra.ui/core 0.1.0

package/src/components/controls/RangeSlider/README.md

@@ -0,0 +1,608 @@
+# RangeSlider
+
+A dual-thumb range slider component built with Vue 3 Composition API and TypeScript. The RangeSlider component provides an intuitive interface for selecting a range of values with customizable styles, tick marks, and interactive HUDs.
+
+## Installation/Import
+
+```typescript
+import { RangeSlider } from "@umbra-ui/core";
+```
+
+**Dependencies:**
+
+- Vue 3.x
+
+## Basic Usage
+
+```vue
+<script setup lang="ts">
+import { ref } from "vue";
+import { RangeSlider } from "@umbra-ui/core";
+
+const minValue = ref(25);
+const maxValue = ref(75);
+
+const handleMinValueChange = (value: number) => {
+  console.log("Min value changed:", value);
+  minValue.value = value;
+};
+
+const handleMaxValueChange = (value: number) => {
+  console.log("Max value changed:", value);
+  maxValue.value = value;
+};
+</script>
+
+<template>
+  <RangeSlider
+    :min="0"
+    :max="100"
+    :min-value="minValue"
+    :max-value="maxValue"
+    @update:min-value="handleMinValueChange"
+    @update:max-value="handleMaxValueChange"
+  />
+</template>
+```
+
+## Props
+
+| Prop Name        | Type                                  | Required | Default     | Description                                |
+| ---------------- | ------------------------------------- | -------- | ----------- | ------------------------------------------ |
+| `sliderStyle`    | `"default" \| "capline" \| "capsule"` | No       | `"default"` | Visual style variant of the slider         |
+| `min`            | `number`                              | No       | `0`         | Minimum value of the slider range          |
+| `max`            | `number`                              | No       | `100`       | Maximum value of the slider range          |
+| `minValue`       | `number`                              | Yes      | `25`        | Current minimum selected value             |
+| `maxValue`       | `number`                              | Yes      | `75`        | Current maximum selected value             |
+| `tickInterval`   | `number`                              | No       | `10`        | Interval between tick marks (0 to disable) |
+| `showTickLabels` | `boolean`                             | No       | `false`     | Whether to show labels below tick marks    |
+
+### Slider Styles
+
+- **`default`**: Standard slider with circular thumbs and a filled track
+- **`capline`**: Capsule-style slider with pill-shaped thumbs
+- **`capsule`**: Full capsule design with bordered track and rounded thumbs
+
+## Events
+
+| Event Name        | Payload Type | Description                            |
+| ----------------- | ------------ | -------------------------------------- |
+| `update:minValue` | `number`     | Emitted when the minimum value changes |
+| `update:maxValue` | `number`     | Emitted when the maximum value changes |
+
+### Event Examples
+
+```vue
+<script setup lang="ts">
+import { ref } from "vue";
+import { RangeSlider } from "@umbra-ui/core";
+
+const minValue = ref(20);
+const maxValue = ref(80);
+
+const handleMinValueChange = (value: number) => {
+  console.log("Min value updated:", value);
+  minValue.value = value;
+};
+
+const handleMaxValueChange = (value: number) => {
+  console.log("Max value updated:", value);
+  maxValue.value = value;
+};
+</script>
+
+<template>
+  <RangeSlider
+    :min="0"
+    :max="100"
+    :min-value="minValue"
+    :max-value="maxValue"
+    @update:min-value="handleMinValueChange"
+    @update:max-value="handleMaxValueChange"
+  />
+</template>
+```
+
+## Slots
+
+This component does not use slots. All content is controlled via props.
+
+## Exposed Methods/Refs
+
+This component does not expose any methods or refs via `defineExpose`.
+
+## CSS Customization
+
+The RangeSlider component uses CSS custom properties that can be overridden to customize the appearance:
+
+### Color Variables
+
+```css
+/* RangeSlider label colors */
+--rangeslider-label-color: #1a1d23;
+
+/* RangeSlider track colors */
+--rangeslider-track-default-bg: #cecece;
+--rangeslider-track-capsule-border: #0090ff;
+--rangeslider-track-capline-bg: #e3e5e8;
+
+/* RangeSlider thumb colors */
+--rangeslider-thumb-default-bg: #838383;
+--rangeslider-thumb-capsule-bg: #838383;
+--rangeslider-thumb-capsule-border: white;
+--rangeslider-thumb-capline-bg: #838383;
+
+/* RangeSlider progress colors */
+--rangeslider-progress-default-bg: #0090ff;
+--rangeslider-progress-capsule-bg: #acd8fc;
+--rangeslider-progress-capsule-border-top: white;
+--rangeslider-progress-capsule-border-bottom: white;
+--rangeslider-progress-capline-bg: #0090ff;
+
+/* RangeSlider HUD colors */
+--rangeslider-hud-default-bg: #8b8d98;
+--rangeslider-hud-default-text: #ffffff;
+--rangeslider-hud-capsule-bg: #0090ff;
+--rangeslider-hud-capsule-text: #ffffff;
+--rangeslider-hud-capline-bg: #8b8d98;
+--rangeslider-hud-capline-text: #ffffff;
+
+/* RangeSlider tick colors */
+--rangeslider-tick-color: #bbbbbb;
+
+/* RangeSlider tick label colors */
+--rangeslider-tick-label-color: #8b8d98;
+--rangeslider-tick-label-opacity: 0.8;
+```
+
+### Custom Styling Example
+
+```vue
+<template>
+  <RangeSlider
+    :min="0"
+    :max="100"
+    :min-value="minValue"
+    :max-value="maxValue"
+    class="custom-range-slider"
+  />
+</template>
+
+<style>
+.custom-range-slider {
+  --rangeslider-progress-default-bg: #ff6b6b;
+  --rangeslider-thumb-default-bg: #ff5252;
+  --rangeslider-hud-default-bg: #ff6b6b;
+}
+</style>
+```
+
+## Examples
+
+### Basic Range Slider
+
+```vue
+<script setup lang="ts">
+import { ref } from "vue";
+import { RangeSlider } from "@umbra-ui/core";
+
+const minValue = ref(30);
+const maxValue = ref(70);
+</script>
+
+<template>
+  <RangeSlider
+    :min="0"
+    :max="100"
+    :min-value="minValue"
+    :max-value="maxValue"
+    @update:min-value="(value) => (minValue = value)"
+    @update:max-value="(value) => (maxValue = value)"
+  />
+</template>
+```
+
+### Different Slider Styles
+
+```vue
+<script setup lang="ts">
+import { ref } from "vue";
+import { RangeSlider } from "@umbra-ui/core";
+
+const defaultMin = ref(20);
+const defaultMax = ref(80);
+const caplineMin = ref(25);
+const caplineMax = ref(75);
+const capsuleMin = ref(30);
+const capsuleMax = ref(70);
+</script>
+
+<template>
+  <div class="style-examples">
+    <div class="example">
+      <h3>Default Style</h3>
+      <RangeSlider
+        :min="0"
+        :max="100"
+        :min-value="defaultMin"
+        :max-value="defaultMax"
+        slider-style="default"
+        @update:min-value="(value) => (defaultMin = value)"
+        @update:max-value="(value) => (defaultMax = value)"
+      />
+    </div>
+
+    <div class="example">
+      <h3>Capline Style</h3>
+      <RangeSlider
+        :min="0"
+        :max="100"
+        :min-value="caplineMin"
+        :max-value="caplineMax"
+        slider-style="capline"
+        @update:min-value="(value) => (caplineMin = value)"
+        @update:max-value="(value) => (caplineMax = value)"
+      />
+    </div>
+
+    <div class="example">
+      <h3>Capsule Style</h3>
+      <RangeSlider
+        :min="0"
+        :max="100"
+        :min-value="capsuleMin"
+        :max-value="capsuleMax"
+        slider-style="capsule"
+        @update:min-value="(value) => (capsuleMin = value)"
+        @update:max-value="(value) => (capsuleMax = value)"
+      />
+    </div>
+  </div>
+</template>
+
+<style module>
+.style-examples {
+  display: flex;
+  flex-direction: column;
+  gap: 2rem;
+}
+
+.example {
+  display: flex;
+  flex-direction: column;
+  gap: 1rem;
+}
+</style>
+```
+
+### With Tick Marks and Labels
+
+```vue
+<script setup lang="ts">
+import { ref } from "vue";
+import { RangeSlider } from "@umbra-ui/core";
+
+const minValue = ref(20);
+const maxValue = ref(80);
+</script>
+
+<template>
+  <div class="tick-examples">
+    <div class="example">
+      <h3>With Tick Marks</h3>
+      <RangeSlider
+        :min="0"
+        :max="100"
+        :min-value="minValue"
+        :max-value="maxValue"
+        :tick-interval="10"
+        @update:min-value="(value) => (minValue = value)"
+        @update:max-value="(value) => (maxValue = value)"
+      />
+    </div>
+
+    <div class="example">
+      <h3>With Tick Labels</h3>
+      <RangeSlider
+        :min="0"
+        :max="100"
+        :min-value="minValue"
+        :max-value="maxValue"
+        :tick-interval="20"
+        :show-tick-labels="true"
+        @update:min-value="(value) => (minValue = value)"
+        @update:max-value="(value) => (maxValue = value)"
+      />
+    </div>
+  </div>
+</template>
+
+<style module>
+.tick-examples {
+  display: flex;
+  flex-direction: column;
+  gap: 2rem;
+}
+
+.example {
+  display: flex;
+  flex-direction: column;
+  gap: 1rem;
+}
+</style>
+```
+
+### Price Range Selector
+
+```vue
+<script setup lang="ts">
+import { ref } from "vue";
+import { RangeSlider } from "@umbra-ui/core";
+
+const minPrice = ref(50);
+const maxPrice = ref(500);
+
+const formatPrice = (value: number) => {
+  return `$${value}`;
+};
+</script>
+
+<template>
+  <div class="price-range">
+    <h3>Price Range</h3>
+    <div class="price-display">
+      <span>{{ formatPrice(minPrice) }}</span>
+      <span>to</span>
+      <span>{{ formatPrice(maxPrice) }}</span>
+    </div>
+
+    <RangeSlider
+      :min="0"
+      :max="1000"
+      :min-value="minPrice"
+      :max-value="maxPrice"
+      :tick-interval="100"
+      :show-tick-labels="true"
+      @update:min-value="(value) => (minPrice = value)"
+      @update:max-value="(value) => (maxPrice = value)"
+    />
+  </div>
+</template>
+
+<style module>
+.price-range {
+  display: flex;
+  flex-direction: column;
+  gap: 1rem;
+  max-width: 400px;
+}
+
+.price-display {
+  display: flex;
+  align-items: center;
+  gap: 0.5rem;
+  font-weight: 500;
+}
+</style>
+```
+
+### Form Integration
+
+```vue
+<script setup lang="ts">
+import { ref } from "vue";
+import { RangeSlider } from "@umbra-ui/core";
+
+interface FilterData {
+  ageRange: { min: number; max: number };
+  salaryRange: { min: number; max: number };
+  experienceRange: { min: number; max: number };
+}
+
+const filters = ref<FilterData>({
+  ageRange: { min: 25, max: 65 },
+  salaryRange: { min: 30000, max: 150000 },
+  experienceRange: { min: 0, max: 20 },
+});
+
+const applyFilters = () => {
+  console.log("Applied filters:", filters.value);
+};
+</script>
+
+<template>
+  <form class="filter-form" @submit.prevent="applyFilters">
+    <div class="filter-group">
+      <label>Age Range</label>
+      <div class="range-display">
+        {{ filters.ageRange.min }} - {{ filters.ageRange.max }} years
+      </div>
+      <RangeSlider
+        :min="18"
+        :max="80"
+        :min-value="filters.ageRange.min"
+        :max-value="filters.ageRange.max"
+        :tick-interval="10"
+        @update:min-value="(value) => (filters.ageRange.min = value)"
+        @update:max-value="(value) => (filters.ageRange.max = value)"
+      />
+    </div>
+
+    <div class="filter-group">
+      <label>Salary Range</label>
+      <div class="range-display">
+        ${{ filters.salaryRange.min.toLocaleString() }} - ${{
+          filters.salaryRange.max.toLocaleString()
+        }}
+      </div>
+      <RangeSlider
+        :min="20000"
+        :max="200000"
+        :min-value="filters.salaryRange.min"
+        :max-value="filters.salaryRange.max"
+        :tick-interval="20000"
+        @update:min-value="(value) => (filters.salaryRange.min = value)"
+        @update:max-value="(value) => (filters.salaryRange.max = value)"
+      />
+    </div>
+
+    <div class="filter-group">
+      <label>Experience Range</label>
+      <div class="range-display">
+        {{ filters.experienceRange.min }} -
+        {{ filters.experienceRange.max }} years
+      </div>
+      <RangeSlider
+        :min="0"
+        :max="30"
+        :min-value="filters.experienceRange.min"
+        :max-value="filters.experienceRange.max"
+        :tick-interval="5"
+        @update:min-value="(value) => (filters.experienceRange.min = value)"
+        @update:max-value="(value) => (filters.experienceRange.max = value)"
+      />
+    </div>
+
+    <button type="submit">Apply Filters</button>
+  </form>
+</template>
+
+<style module>
+.filter-form {
+  display: flex;
+  flex-direction: column;
+  gap: 2rem;
+  max-width: 500px;
+}
+
+.filter-group {
+  display: flex;
+  flex-direction: column;
+  gap: 0.5rem;
+}
+
+.range-display {
+  font-weight: 500;
+  color: #666;
+}
+</style>
+```
+
+### Audio/Video Controls
+
+```vue
+<script setup lang="ts">
+import { ref } from "vue";
+import { RangeSlider } from "@umbra-ui/core";
+
+const volumeRange = ref({ min: 20, max: 80 });
+const frequencyRange = ref({ min: 100, max: 10000 });
+
+const formatVolume = (value: number) => {
+  return `${value}%`;
+};
+
+const formatFrequency = (value: number) => {
+  if (value >= 1000) {
+    return `${(value / 1000).toFixed(1)}kHz`;
+  }
+  return `${value}Hz`;
+};
+</script>
+
+<template>
+  <div class="audio-controls">
+    <h3>Audio Controls</h3>
+
+    <div class="control-group">
+      <label>Volume Range</label>
+      <div class="value-display">
+        {{ formatVolume(volumeRange.min) }} -
+        {{ formatVolume(volumeRange.max) }}
+      </div>
+      <RangeSlider
+        :min="0"
+        :max="100"
+        :min-value="volumeRange.min"
+        :max-value="volumeRange.max"
+        :tick-interval="10"
+        slider-style="capline"
+        @update:min-value="(value) => (volumeRange.min = value)"
+        @update:max-value="(value) => (volumeRange.max = value)"
+      />
+    </div>
+
+    <div class="control-group">
+      <label>Frequency Range</label>
+      <div class="value-display">
+        {{ formatFrequency(frequencyRange.min) }} -
+        {{ formatFrequency(frequencyRange.max) }}
+      </div>
+      <RangeSlider
+        :min="20"
+        :max="20000"
+        :min-value="frequencyRange.min"
+        :max-value="frequencyRange.max"
+        :tick-interval="1000"
+        :show-tick-labels="true"
+        slider-style="capsule"
+        @update:min-value="(value) => (frequencyRange.min = value)"
+        @update:max-value="(value) => (frequencyRange.max = value)"
+      />
+    </div>
+  </div>
+</template>
+
+<style module>
+.audio-controls {
+  display: flex;
+  flex-direction: column;
+  gap: 2rem;
+  max-width: 500px;
+}
+
+.control-group {
+  display: flex;
+  flex-direction: column;
+  gap: 0.5rem;
+}
+
+.value-display {
+  font-weight: 500;
+  color: #666;
+  font-family: monospace;
+}
+</style>
+```
+
+## Interactive Features
+
+### HUD (Heads-Up Display)
+
+- Value tooltips appear above thumbs when dragging
+- Automatically hide after 500ms when interaction ends
+- Show current rounded values for easy reading
+
+### Smart Thumb Selection
+
+- Automatically selects the closest thumb when clicking on the track
+- Handles overlapping thumbs intelligently
+- Prevents min value from exceeding max value and vice versa
+
+### Touch Support
+
+- Full touch device support with proper event handling
+- Smooth dragging experience on mobile devices
+- Prevents default touch behaviors for better control
+
+## Notes
+
+- The component includes smooth animations and transitions
+- HUD tooltips show rounded values for better readability
+- Active thumb is visually highlighted and appears on top
+- Tick marks are automatically generated based on the interval
+- The component supports both light and dark themes
+- All interactions are fully accessible with proper event handling
+- The slider automatically constrains values within the min/max range
+- Touch and mouse events are both supported for cross-platform compatibility
+- The component uses percentage-based positioning for smooth value interpolation