@umbra.ui/core 0.1.18 → 0.1.20

package/dist/components/indicators/ProgressBar/README.md

@@ -0,0 +1,744 @@
+# ProgressBar
+
+A flexible progress bar component built with Vue 3 Composition API and TypeScript. The ProgressBar component provides visual feedback for loading states, completion percentages, and progress tracking with customizable styles, colors, and dimensions.
+
+## Installation/Import
+
+```typescript
+import { ProgressBar } from "@umbra-ui/core";
+```
+
+**Dependencies:**
+
+- Vue 3.x
+
+## Basic Usage
+
+```vue
+<script setup lang="ts">
+import { ref } from "vue";
+import { ProgressBar } from "@umbra-ui/core";
+
+const progress = ref(45);
+
+const updateProgress = (newProgress: number) => {
+  progress.value = newProgress;
+};
+</script>
+
+<template>
+  <div>
+    <ProgressBar :progress="progress" @update:progress="updateProgress" />
+
+    <button @click="updateProgress(75)">Set to 75%</button>
+  </div>
+</template>
+```
+
+## Props
+
+| Prop Name       | Type                                  | Required | Default                                         | Description                                       |
+| --------------- | ------------------------------------- | -------- | ----------------------------------------------- | ------------------------------------------------- |
+| `progress`      | `number`                              | No       | `0`                                             | Progress percentage (0-100)                       |
+| `barType`       | `"default" \| "capsule" \| "capline"` | No       | `"default"`                                     | Visual style variant of the progress bar          |
+| `trackColor`    | `string`                              | No       | `"var(--progressbar-track-default)"`            | Background color of the progress track            |
+| `progressColor` | `string`                              | No       | `"var(--progressbar-progress-default)"`         | Color of the progress fill                        |
+| `height`        | `string`                              | No       | `"6px"` (default) or `"12px"` (capsule/capline) | Height of the progress bar in pixels or CSS units |
+
+## Events
+
+| Event Name        | Payload Type | Description                                                    |
+| ----------------- | ------------ | -------------------------------------------------------------- |
+| `update:progress` | `number`     | Emitted when the progress value changes, returns the new value |
+
+## Slots
+
+This component does not use slots.
+
+## Exposed Methods/Refs
+
+This component does not expose any methods or refs.
+
+## CSS Customization
+
+The ProgressBar component uses CSS custom properties for easy theming and customization:
+
+```css
+/* ProgressBar track colors */
+--progressbar-track-default: #f0f2f4;
+--progressbar-track-capline: transparent;
+
+/* ProgressBar progress colors */
+--progressbar-progress-default: #0090ff;
+
+/* ProgressBar border colors */
+--progressbar-border-capline: #0090ff;
+--progressbar-border-progress: white;
+
+/* ProgressBar text colors */
+--progressbar-text-default: #1a1d23;
+--progressbar-text-capline: #1a1d23;
+```
+
+## Examples
+
+### Different Bar Types
+
+```vue
+<script setup lang="ts">
+import { ref } from "vue";
+import { ProgressBar } from "@umbra-ui/core";
+
+const progress = ref(60);
+</script>
+
+<template>
+  <div class="progress-examples">
+    <div class="progress-group">
+      <label>Default Style</label>
+      <ProgressBar barType="default" :progress="progress" />
+    </div>
+
+    <div class="progress-group">
+      <label>Capsule Style</label>
+      <ProgressBar barType="capsule" :progress="progress" />
+    </div>
+
+    <div class="progress-group">
+      <label>Capline Style</label>
+      <ProgressBar barType="capline" :progress="progress" />
+    </div>
+  </div>
+</template>
+
+<style module>
+.progress-examples {
+  display: flex;
+  flex-direction: column;
+  gap: 1rem;
+}
+
+.progress-group {
+  display: flex;
+  flex-direction: column;
+  gap: 0.5rem;
+}
+
+label {
+  font-weight: 500;
+  color: #333;
+}
+</style>
+```
+
+### Custom Colors
+
+```vue
+<script setup lang="ts">
+import { ref } from "vue";
+import { ProgressBar } from "@umbra-ui/core";
+
+const progress = ref(75);
+</script>
+
+<template>
+  <div class="color-examples">
+    <div class="progress-group">
+      <label>Red Progress</label>
+      <ProgressBar
+        :progress="progress"
+        progressColor="#ff4444"
+        trackColor="#ffe6e6"
+      />
+    </div>
+
+    <div class="progress-group">
+      <label>Green Progress</label>
+      <ProgressBar
+        :progress="progress"
+        progressColor="#44ff44"
+        trackColor="#e6ffe6"
+      />
+    </div>
+
+    <div class="progress-group">
+      <label>Purple Progress</label>
+      <ProgressBar
+        :progress="progress"
+        progressColor="#8844ff"
+        trackColor="#f0e6ff"
+      />
+    </div>
+  </div>
+</template>
+
+<style module>
+.color-examples {
+  display: flex;
+  flex-direction: column;
+  gap: 1rem;
+}
+
+.progress-group {
+  display: flex;
+  flex-direction: column;
+  gap: 0.5rem;
+}
+
+label {
+  font-weight: 500;
+  color: #333;
+}
+</style>
+```
+
+### Different Heights
+
+```vue
+<script setup lang="ts">
+import { ref } from "vue";
+import { ProgressBar } from "@umbra-ui/core";
+
+const progress = ref(50);
+</script>
+
+<template>
+  <div class="height-examples">
+    <div class="progress-group">
+      <label>Thin (4px)</label>
+      <ProgressBar :progress="progress" height="4px" />
+    </div>
+
+    <div class="progress-group">
+      <label>Default (6px)</label>
+      <ProgressBar :progress="progress" height="6px" />
+    </div>
+
+    <div class="progress-group">
+      <label>Medium (12px)</label>
+      <ProgressBar :progress="progress" height="12px" />
+    </div>
+
+    <div class="progress-group">
+      <label>Large (20px)</label>
+      <ProgressBar :progress="progress" height="20px" />
+    </div>
+  </div>
+</template>
+
+<style module>
+.height-examples {
+  display: flex;
+  flex-direction: column;
+  gap: 1rem;
+}
+
+.progress-group {
+  display: flex;
+  flex-direction: column;
+  gap: 0.5rem;
+}
+
+label {
+  font-weight: 500;
+  color: #333;
+}
+</style>
+```
+
+### File Upload Progress
+
+```vue
+<script setup lang="ts">
+import { ref } from "vue";
+import { ProgressBar } from "@umbra-ui/core";
+
+const uploadProgress = ref(0);
+const isUploading = ref(false);
+
+const simulateUpload = async () => {
+  isUploading.value = true;
+  uploadProgress.value = 0;
+
+  for (let i = 0; i <= 100; i += 10) {
+    await new Promise((resolve) => setTimeout(resolve, 200));
+    uploadProgress.value = i;
+  }
+
+  isUploading.value = false;
+};
+</script>
+
+<template>
+  <div class="upload-example">
+    <h3>File Upload</h3>
+
+    <div class="upload-area">
+      <p>Click to upload a file</p>
+      <button @click="simulateUpload" :disabled="isUploading">
+        {{ isUploading ? "Uploading..." : "Upload File" }}
+      </button>
+    </div>
+
+    <div v-if="isUploading || uploadProgress > 0" class="progress-section">
+      <div class="progress-info">
+        <span>Upload Progress</span>
+        <span>{{ uploadProgress }}%</span>
+      </div>
+      <ProgressBar
+        :progress="uploadProgress"
+        barType="capsule"
+        progressColor="#30a46c"
+        trackColor="#e6f7e6"
+        height="8px"
+      />
+    </div>
+  </div>
+</template>
+
+<style module>
+.upload-example {
+  max-width: 400px;
+  padding: 1.5rem;
+  border: 1px solid #e0e0e0;
+  border-radius: 8px;
+}
+
+.upload-area {
+  text-align: center;
+  padding: 2rem;
+  border: 2px dashed #ccc;
+  border-radius: 8px;
+  margin-bottom: 1rem;
+}
+
+.progress-section {
+  margin-top: 1rem;
+}
+
+.progress-info {
+  display: flex;
+  justify-content: space-between;
+  margin-bottom: 0.5rem;
+  font-size: 0.9rem;
+  color: #666;
+}
+
+button {
+  padding: 0.5rem 1rem;
+  background-color: #007bff;
+  color: white;
+  border: none;
+  border-radius: 4px;
+  cursor: pointer;
+}
+
+button:disabled {
+  background-color: #ccc;
+  cursor: not-allowed;
+}
+</style>
+```
+
+### Loading States
+
+```vue
+<script setup lang="ts">
+import { ref } from "vue";
+import { ProgressBar } from "@umbra-ui/core";
+
+const loadingProgress = ref(0);
+const isLoading = ref(false);
+
+const startLoading = () => {
+  isLoading.value = true;
+  loadingProgress.value = 0;
+
+  const interval = setInterval(() => {
+    if (loadingProgress.value < 90) {
+      loadingProgress.value += Math.random() * 10;
+    }
+  }, 200);
+
+  // Simulate completion
+  setTimeout(() => {
+    clearInterval(interval);
+    loadingProgress.value = 100;
+    setTimeout(() => {
+      isLoading.value = false;
+      loadingProgress.value = 0;
+    }, 500);
+  }, 3000);
+};
+</script>
+
+<template>
+  <div class="loading-example">
+    <h3>Loading States</h3>
+
+    <button @click="startLoading" :disabled="isLoading">
+      {{ isLoading ? "Loading..." : "Start Loading" }}
+    </button>
+
+    <div v-if="isLoading" class="loading-section">
+      <div class="loading-info">
+        <span>Loading data...</span>
+        <span>{{ Math.round(loadingProgress) }}%</span>
+      </div>
+      <ProgressBar
+        :progress="loadingProgress"
+        barType="default"
+        progressColor="#5b5bd6"
+        trackColor="#f0f0ff"
+        height="6px"
+      />
+    </div>
+  </div>
+</template>
+
+<style module>
+.loading-example {
+  max-width: 400px;
+  padding: 1.5rem;
+  border: 1px solid #e0e0e0;
+  border-radius: 8px;
+}
+
+.loading-section {
+  margin-top: 1rem;
+}
+
+.loading-info {
+  display: flex;
+  justify-content: space-between;
+  margin-bottom: 0.5rem;
+  font-size: 0.9rem;
+  color: #666;
+}
+
+button {
+  padding: 0.5rem 1rem;
+  background-color: #5b5bd6;
+  color: white;
+  border: none;
+  border-radius: 4px;
+  cursor: pointer;
+}
+
+button:disabled {
+  background-color: #ccc;
+  cursor: not-allowed;
+}
+</style>
+```
+
+### Form Completion
+
+```vue
+<script setup lang="ts">
+import { ref, computed } from "vue";
+import { ProgressBar } from "@umbra-ui/core";
+
+const formData = ref({
+  name: "",
+  email: "",
+  phone: "",
+  address: "",
+  preferences: "",
+});
+
+const completionPercentage = computed(() => {
+  const fields = Object.keys(formData.value);
+  const completedFields = fields.filter(
+    (field) =>
+      formData.value[field as keyof typeof formData.value].trim() !== ""
+  );
+  return Math.round((completedFields.length / fields.length) * 100);
+});
+</script>
+
+<template>
+  <div class="form-example">
+    <h3>Form Completion</h3>
+
+    <div class="completion-section">
+      <div class="completion-info">
+        <span>Form Progress</span>
+        <span>{{ completionPercentage }}%</span>
+      </div>
+      <ProgressBar
+        :progress="completionPercentage"
+        barType="capsule"
+        progressColor="#30a46c"
+        trackColor="#e6f7e6"
+        height="8px"
+      />
+    </div>
+
+    <form class="form">
+      <div class="form-group">
+        <label>Name</label>
+        <input
+          v-model="formData.name"
+          type="text"
+          placeholder="Enter your name"
+        />
+      </div>
+
+      <div class="form-group">
+        <label>Email</label>
+        <input
+          v-model="formData.email"
+          type="email"
+          placeholder="Enter your email"
+        />
+      </div>
+
+      <div class="form-group">
+        <label>Phone</label>
+        <input
+          v-model="formData.phone"
+          type="tel"
+          placeholder="Enter your phone"
+        />
+      </div>
+
+      <div class="form-group">
+        <label>Address</label>
+        <input
+          v-model="formData.address"
+          type="text"
+          placeholder="Enter your address"
+        />
+      </div>
+
+      <div class="form-group">
+        <label>Preferences</label>
+        <textarea
+          v-model="formData.preferences"
+          placeholder="Enter your preferences"
+        ></textarea>
+      </div>
+    </form>
+  </div>
+</template>
+
+<style module>
+.form-example {
+  max-width: 500px;
+  padding: 1.5rem;
+  border: 1px solid #e0e0e0;
+  border-radius: 8px;
+}
+
+.completion-section {
+  margin-bottom: 1.5rem;
+  padding: 1rem;
+  background-color: #f8f9fa;
+  border-radius: 6px;
+}
+
+.completion-info {
+  display: flex;
+  justify-content: space-between;
+  margin-bottom: 0.5rem;
+  font-weight: 500;
+  color: #333;
+}
+
+.form {
+  display: flex;
+  flex-direction: column;
+  gap: 1rem;
+}
+
+.form-group {
+  display: flex;
+  flex-direction: column;
+  gap: 0.5rem;
+}
+
+label {
+  font-weight: 500;
+  color: #333;
+}
+
+input,
+textarea {
+  padding: 0.5rem;
+  border: 1px solid #ddd;
+  border-radius: 4px;
+  font-size: 1rem;
+}
+
+textarea {
+  min-height: 80px;
+  resize: vertical;
+}
+</style>
+```
+
+### Multi-Step Progress
+
+```vue
+<script setup lang="ts">
+import { ref, computed } from "vue";
+import { ProgressBar } from "@umbra-ui/core";
+
+const currentStep = ref(1);
+const totalSteps = 5;
+
+const stepProgress = computed(() => {
+  return (currentStep.value / totalSteps) * 100;
+});
+
+const nextStep = () => {
+  if (currentStep.value < totalSteps) {
+    currentStep.value++;
+  }
+};
+
+const prevStep = () => {
+  if (currentStep.value > 1) {
+    currentStep.value--;
+  }
+};
+
+const resetSteps = () => {
+  currentStep.value = 1;
+};
+</script>
+
+<template>
+  <div class="multistep-example">
+    <h3>Multi-Step Process</h3>
+
+    <div class="step-progress">
+      <div class="step-info">
+        <span>Step {{ currentStep }} of {{ totalSteps }}</span>
+        <span>{{ Math.round(stepProgress) }}%</span>
+      </div>
+      <ProgressBar
+        :progress="stepProgress"
+        barType="capline"
+        progressColor="#0090ff"
+        trackColor="transparent"
+        height="12px"
+      />
+    </div>
+
+    <div class="step-content">
+      <h4>Step {{ currentStep }}: {{ getStepTitle(currentStep) }}</h4>
+      <p>{{ getStepDescription(currentStep) }}</p>
+    </div>
+
+    <div class="step-controls">
+      <button @click="prevStep" :disabled="currentStep === 1">Previous</button>
+      <button @click="nextStep" :disabled="currentStep === totalSteps">
+        Next
+      </button>
+      <button @click="resetSteps">Reset</button>
+    </div>
+  </div>
+</template>
+
+<script setup lang="ts">
+const getStepTitle = (step: number) => {
+  const titles = [
+    "Welcome",
+    "Personal Information",
+    "Preferences",
+    "Review",
+    "Complete",
+  ];
+  return titles[step - 1] || "Unknown Step";
+};
+
+const getStepDescription = (step: number) => {
+  const descriptions = [
+    "Welcome to our setup process. Let's get started!",
+    "Please provide your personal information.",
+    "Configure your preferences and settings.",
+    "Review all the information you've provided.",
+    "Congratulations! You've completed the setup.",
+  ];
+  return descriptions[step - 1] || "No description available.";
+};
+</script>
+
+<style module>
+.multistep-example {
+  max-width: 500px;
+  padding: 1.5rem;
+  border: 1px solid #e0e0e0;
+  border-radius: 8px;
+}
+
+.step-progress {
+  margin-bottom: 1.5rem;
+  padding: 1rem;
+  background-color: #f8f9fa;
+  border-radius: 6px;
+}
+
+.step-info {
+  display: flex;
+  justify-content: space-between;
+  margin-bottom: 0.5rem;
+  font-weight: 500;
+  color: #333;
+}
+
+.step-content {
+  margin-bottom: 1.5rem;
+  padding: 1rem;
+  background-color: #f8f9fa;
+  border-radius: 6px;
+}
+
+.step-content h4 {
+  margin: 0 0 0.5rem 0;
+  color: #333;
+}
+
+.step-content p {
+  margin: 0;
+  color: #666;
+}
+
+.step-controls {
+  display: flex;
+  gap: 0.5rem;
+  justify-content: center;
+}
+
+button {
+  padding: 0.5rem 1rem;
+  background-color: #007bff;
+  color: white;
+  border: none;
+  border-radius: 4px;
+  cursor: pointer;
+}
+
+button:disabled {
+  background-color: #ccc;
+  cursor: not-allowed;
+}
+
+button:not(:disabled):hover {
+  background-color: #0056b3;
+}
+</style>
+```
+
+## Notes
+
+- The component automatically clamps progress values between 0 and 100
+- Progress text is only displayed when the height is 20px or greater
+- The component includes smooth transitions for progress changes
+- Different bar types have different default heights and styling
+- The component supports both light and dark themes through CSS custom properties
+- The progress bar is fully accessible and supports screen readers
+- Custom colors can be applied to both the track and progress fill
+- The component uses CSS custom properties for easy theming and customization