@umbra.ui/core 0.1.0

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

@@ -0,0 +1,627 @@
+# Slider
+
+A single-thumb slider component built with Vue 3 Composition API and TypeScript. The Slider component provides an intuitive interface for selecting a single value with customizable styles, interactive HUDs, and smooth animations.
+
+## Installation/Import
+
+```typescript
+import { Slider } from "@umbra-ui/core";
+```
+
+**Dependencies:**
+
+- Vue 3.x
+
+## Basic Usage
+
+```vue
+<script setup lang="ts">
+import { ref } from "vue";
+import { Slider } from "@umbra-ui/core";
+
+const sliderValue = ref(50);
+
+const handleValueChange = (value: number) => {
+  console.log("Slider value changed:", value);
+  sliderValue.value = value;
+};
+</script>
+
+<template>
+  <Slider
+    :min="0"
+    :max="100"
+    :value="sliderValue"
+    @update:value="handleValueChange"
+  />
+</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  |
+| `value`       | `number`                              | Yes      | `50`        | Current value of the slider        |
+
+### Slider Styles
+
+- **`default`**: Standard slider with circular thumb and filled progress track
+- **`capline`**: Capsule-style slider with pill-shaped thumb
+- **`capsule`**: Full capsule design with bordered track and rounded thumb
+
+## Events
+
+| Event Name     | Payload Type | Description                           |
+| -------------- | ------------ | ------------------------------------- |
+| `update:value` | `number`     | Emitted when the slider value changes |
+
+### Event Examples
+
+```vue
+<script setup lang="ts">
+import { ref } from "vue";
+import { Slider } from "@umbra-ui/core";
+
+const sliderValue = ref(75);
+
+const handleValueChange = (value: number) => {
+  console.log("Slider value updated:", value);
+  sliderValue.value = value;
+};
+</script>
+
+<template>
+  <Slider
+    :min="0"
+    :max="100"
+    :value="sliderValue"
+    @update:value="handleValueChange"
+  />
+</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 Slider component uses CSS custom properties that can be overridden to customize the appearance:
+
+### Color Variables
+
+```css
+/* Slider label colors */
+--slider-label-color: #1a1d23;
+
+/* Slider track colors */
+--slider-track-default-bg: #cecece;
+--slider-track-capsule-border: #0090ff;
+--slider-track-capline-bg: #e3e5e8;
+
+/* Slider thumb colors */
+--slider-thumb-default-bg: white;
+--slider-thumb-capsule-bg: #0090ff;
+--slider-thumb-capline-bg: white;
+
+/* Slider thumb border colors */
+--slider-thumb-default-border: 1px solid #cecece;
+--slider-thumb-capsule-border: 0.12rem solid white;
+--slider-thumb-capline-border: 1px solid #cecece;
+
+/* Slider progress colors */
+--slider-progress-default-bg: #0090ff;
+--slider-progress-capsule-bg: #acd8fc;
+--slider-progress-capsule-border-top: white;
+--slider-progress-capsule-border-bottom: white;
+--slider-progress-capsule-border-left: white;
+--slider-progress-capline-bg: #0090ff;
+
+/* Slider HUD colors */
+--slider-hud-default-bg: #8b8d98;
+--slider-hud-default-text: #ffffff;
+--slider-hud-capsule-bg: #0090ff;
+--slider-hud-capsule-text: #ffffff;
+--slider-hud-capline-bg: #8b8d98;
+--slider-hud-capline-text: #ffffff;
+```
+
+### Custom Styling Example
+
+```vue
+<template>
+  <Slider :min="0" :max="100" :value="sliderValue" class="custom-slider" />
+</template>
+
+<style>
+.custom-slider {
+  --slider-progress-default-bg: #ff6b6b;
+  --slider-thumb-default-bg: #ff5252;
+  --slider-hud-default-bg: #ff6b6b;
+}
+</style>
+```
+
+## Examples
+
+### Basic Slider
+
+```vue
+<script setup lang="ts">
+import { ref } from "vue";
+import { Slider } from "@umbra-ui/core";
+
+const sliderValue = ref(50);
+</script>
+
+<template>
+  <Slider
+    :min="0"
+    :max="100"
+    :value="sliderValue"
+    @update:value="(value) => (sliderValue = value)"
+  />
+</template>
+```
+
+### Different Slider Styles
+
+```vue
+<script setup lang="ts">
+import { ref } from "vue";
+import { Slider } from "@umbra-ui/core";
+
+const defaultValue = ref(50);
+const caplineValue = ref(60);
+const capsuleValue = ref(70);
+</script>
+
+<template>
+  <div class="style-examples">
+    <div class="example">
+      <h3>Default Style</h3>
+      <Slider
+        :min="0"
+        :max="100"
+        :value="defaultValue"
+        slider-style="default"
+        @update:value="(value) => (defaultValue = value)"
+      />
+    </div>
+
+    <div class="example">
+      <h3>Capline Style</h3>
+      <Slider
+        :min="0"
+        :max="100"
+        :value="caplineValue"
+        slider-style="capline"
+        @update:value="(value) => (caplineValue = value)"
+      />
+    </div>
+
+    <div class="example">
+      <h3>Capsule Style</h3>
+      <Slider
+        :min="0"
+        :max="100"
+        :value="capsuleValue"
+        slider-style="capsule"
+        @update:value="(value) => (capsuleValue = value)"
+      />
+    </div>
+  </div>
+</template>
+
+<style module>
+.style-examples {
+  display: flex;
+  flex-direction: column;
+  gap: 2rem;
+}
+
+.example {
+  display: flex;
+  flex-direction: column;
+  gap: 1rem;
+}
+</style>
+```
+
+### Volume Control
+
+```vue
+<script setup lang="ts">
+import { ref } from "vue";
+import { Slider } from "@umbra-ui/core";
+
+const volume = ref(75);
+
+const formatVolume = (value: number) => {
+  return `${value}%`;
+};
+</script>
+
+<template>
+  <div class="volume-control">
+    <h3>Volume Control</h3>
+    <div class="volume-display">
+      {{ formatVolume(volume) }}
+    </div>
+
+    <Slider
+      :min="0"
+      :max="100"
+      :value="volume"
+      slider-style="capline"
+      @update:value="(value) => (volume = value)"
+    />
+  </div>
+</template>
+
+<style module>
+.volume-control {
+  display: flex;
+  flex-direction: column;
+  gap: 1rem;
+  max-width: 300px;
+}
+
+.volume-display {
+  text-align: center;
+  font-weight: 500;
+  font-size: 1.2rem;
+}
+</style>
+```
+
+### Brightness Control
+
+```vue
+<script setup lang="ts">
+import { ref } from "vue";
+import { Slider } from "@umbra-ui/core";
+
+const brightness = ref(80);
+
+const formatBrightness = (value: number) => {
+  return `${value}%`;
+};
+</script>
+
+<template>
+  <div class="brightness-control">
+    <h3>Screen Brightness</h3>
+    <div class="brightness-display">
+      {{ formatBrightness(brightness) }}
+    </div>
+
+    <Slider
+      :min="10"
+      :max="100"
+      :value="brightness"
+      slider-style="capsule"
+      @update:value="(value) => (brightness = value)"
+    />
+  </div>
+</template>
+
+<style module>
+.brightness-control {
+  display: flex;
+  flex-direction: column;
+  gap: 1rem;
+  max-width: 300px;
+}
+
+.brightness-display {
+  text-align: center;
+  font-weight: 500;
+  font-size: 1.2rem;
+}
+</style>
+```
+
+### Form Integration
+
+```vue
+<script setup lang="ts">
+import { ref } from "vue";
+import { Slider } from "@umbra-ui/core";
+
+interface FormData {
+  satisfaction: number;
+  difficulty: number;
+  recommendation: number;
+}
+
+const formData = ref<FormData>({
+  satisfaction: 75,
+  difficulty: 50,
+  recommendation: 80,
+});
+
+const submitForm = () => {
+  console.log("Form submitted:", formData.value);
+};
+</script>
+
+<template>
+  <form class="feedback-form" @submit.prevent="submitForm">
+    <div class="form-group">
+      <label>Satisfaction Level</label>
+      <div class="slider-value">{{ formData.satisfaction }}%</div>
+      <Slider
+        :min="0"
+        :max="100"
+        :value="formData.satisfaction"
+        @update:value="(value) => (formData.satisfaction = value)"
+      />
+    </div>
+
+    <div class="form-group">
+      <label>Difficulty Level</label>
+      <div class="slider-value">{{ formData.difficulty }}%</div>
+      <Slider
+        :min="0"
+        :max="100"
+        :value="formData.difficulty"
+        @update:value="(value) => (formData.difficulty = value)"
+      />
+    </div>
+
+    <div class="form-group">
+      <label>Recommendation Score</label>
+      <div class="slider-value">{{ formData.recommendation }}%</div>
+      <Slider
+        :min="0"
+        :max="100"
+        :value="formData.recommendation"
+        @update:value="(value) => (formData.recommendation = value)"
+      />
+    </div>
+
+    <button type="submit">Submit Feedback</button>
+  </form>
+</template>
+
+<style module>
+.feedback-form {
+  display: flex;
+  flex-direction: column;
+  gap: 2rem;
+  max-width: 400px;
+}
+
+.form-group {
+  display: flex;
+  flex-direction: column;
+  gap: 0.5rem;
+}
+
+.slider-value {
+  font-weight: 500;
+  color: #666;
+  text-align: center;
+}
+</style>
+```
+
+### Settings Panel
+
+```vue
+<script setup lang="ts">
+import { ref } from "vue";
+import { Slider } from "@umbra-ui/core";
+
+const fontSize = ref(16);
+const lineHeight = ref(1.5);
+const opacity = ref(100);
+
+const saveSettings = () => {
+  const settings = {
+    fontSize: fontSize.value,
+    lineHeight: lineHeight.value,
+    opacity: opacity.value,
+  };
+  console.log("Settings saved:", settings);
+};
+</script>
+
+<template>
+  <div class="settings-panel">
+    <h2>Display Settings</h2>
+
+    <div class="setting-group">
+      <label>Font Size: {{ fontSize }}px</label>
+      <Slider
+        :min="12"
+        :max="24"
+        :value="fontSize"
+        @update:value="(value) => (fontSize = value)"
+      />
+    </div>
+
+    <div class="setting-group">
+      <label>Line Height: {{ lineHeight }}</label>
+      <Slider
+        :min="1"
+        :max="2"
+        :value="lineHeight"
+        @update:value="(value) => (lineHeight = value)"
+      />
+    </div>
+
+    <div class="setting-group">
+      <label>Opacity: {{ opacity }}%</label>
+      <Slider
+        :min="50"
+        :max="100"
+        :value="opacity"
+        slider-style="capline"
+        @update:value="(value) => (opacity = value)"
+      />
+    </div>
+
+    <button @click="saveSettings">Save Settings</button>
+  </div>
+</template>
+
+<style module>
+.settings-panel {
+  display: flex;
+  flex-direction: column;
+  gap: 2rem;
+  max-width: 400px;
+  padding: 2rem;
+  background-color: #f5f5f5;
+  border-radius: 0.5rem;
+}
+
+.setting-group {
+  display: flex;
+  flex-direction: column;
+  gap: 1rem;
+}
+</style>
+```
+
+### Audio Equalizer
+
+```vue
+<script setup lang="ts">
+import { ref } from "vue";
+import { Slider } from "@umbra-ui/core";
+
+const frequencies = ref({
+  bass: 50,
+  mid: 60,
+  treble: 70,
+  presence: 55,
+});
+
+const resetEqualizer = () => {
+  frequencies.value = {
+    bass: 50,
+    mid: 50,
+    treble: 50,
+    presence: 50,
+  };
+};
+</script>
+
+<template>
+  <div class="equalizer">
+    <h3>Audio Equalizer</h3>
+
+    <div class="frequency-controls">
+      <div class="frequency-group">
+        <label>Bass</label>
+        <Slider
+          :min="0"
+          :max="100"
+          :value="frequencies.bass"
+          slider-style="capsule"
+          @update:value="(value) => (frequencies.bass = value)"
+        />
+      </div>
+
+      <div class="frequency-group">
+        <label>Mid</label>
+        <Slider
+          :min="0"
+          :max="100"
+          :value="frequencies.mid"
+          slider-style="capsule"
+          @update:value="(value) => (frequencies.mid = value)"
+        />
+      </div>
+
+      <div class="frequency-group">
+        <label>Treble</label>
+        <Slider
+          :min="0"
+          :max="100"
+          :value="frequencies.treble"
+          slider-style="capsule"
+          @update:value="(value) => (frequencies.treble = value)"
+        />
+      </div>
+
+      <div class="frequency-group">
+        <label>Presence</label>
+        <Slider
+          :min="0"
+          :max="100"
+          :value="frequencies.presence"
+          slider-style="capsule"
+          @update:value="(value) => (frequencies.presence = value)"
+        />
+      </div>
+    </div>
+
+    <button @click="resetEqualizer">Reset</button>
+  </div>
+</template>
+
+<style module>
+.equalizer {
+  display: flex;
+  flex-direction: column;
+  gap: 2rem;
+  max-width: 500px;
+}
+
+.frequency-controls {
+  display: grid;
+  grid-template-columns: repeat(2, 1fr);
+  gap: 2rem;
+}
+
+.frequency-group {
+  display: flex;
+  flex-direction: column;
+  gap: 1rem;
+}
+</style>
+```
+
+## Interactive Features
+
+### HUD (Heads-Up Display)
+
+- Value tooltip appears above the thumb when dragging
+- Automatically hides after 500ms when interaction ends
+- Shows current rounded value for easy reading
+
+### Touch Support
+
+- Full touch device support with proper event handling
+- Smooth dragging experience on mobile devices
+- Prevents default touch behaviors for better control
+
+### Progress Visualization
+
+- Visual progress bar shows current value position
+- Different styles for different slider variants
+- Smooth animations during value changes
+
+## Notes
+
+- The component includes smooth animations and transitions
+- HUD tooltip shows rounded values for better readability
+- 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
+- Different slider styles provide various visual appearances for different use cases
+- The component supports both light and dark themes
+- All interactions are fully accessible with proper event handling
+- The slider provides immediate visual feedback during dragging
+- The component is optimized for performance with efficient event handling