@umbra.ui/core 0.1.0

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

@@ -0,0 +1,587 @@
+# SegmentedControl
+
+A segmented control component built with Vue 3 Composition API and TypeScript. The SegmentedControl component provides a sleek, animated interface for selecting between multiple options with smooth transitions and visual feedback.
+
+## Installation/Import
+
+```typescript
+import { SegmentedControl } from "@umbra-ui/core";
+import type { ControlItem } from "@umbra-ui/core";
+```
+
+**Dependencies:**
+
+- Vue 3.x
+
+## Basic Usage
+
+```vue
+<script setup lang="ts">
+import { ref } from "vue";
+import { SegmentedControl } from "@umbra-ui/core";
+import type { ControlItem } from "@umbra-ui/core";
+
+const selectedIndex = ref(0);
+
+const segments: ControlItem[] = [
+  { title: "Option 1" },
+  { title: "Option 2" },
+  { title: "Option 3" },
+];
+
+const handleSegmentClick = (index: number, item: ControlItem) => {
+  console.log("Selected:", item.title, "at index:", index);
+  selectedIndex.value = index;
+};
+</script>
+
+<template>
+  <SegmentedControl
+    :items="segments"
+    :selected-index="selectedIndex"
+    @click="handleSegmentClick"
+  />
+</template>
+```
+
+## Props
+
+| Prop Name       | Type            | Required | Default                                                    | Description                             |
+| --------------- | --------------- | -------- | ---------------------------------------------------------- | --------------------------------------- |
+| `items`         | `ControlItem[]` | Yes      | `[{ title: "One" }, { title: "Two" }, { title: "Three" }]` | Array of segment options to display     |
+| `selectedIndex` | `number`        | No       | `0`                                                        | Index of the currently selected segment |
+
+### ControlItem Interface
+
+```typescript
+interface ControlItem {
+  title: string;
+  subtitle?: string;
+  disabled?: boolean;
+}
+```
+
+## Events
+
+| Event Name             | Payload Type                         | Description                              |
+| ---------------------- | ------------------------------------ | ---------------------------------------- |
+| `update:selectedIndex` | `number`                             | Emitted when selection changes (v-model) |
+| `click`                | `[index: number, item: ControlItem]` | Emitted when a segment is clicked        |
+
+### Event Examples
+
+```vue
+<script setup lang="ts">
+import { ref } from "vue";
+import { SegmentedControl } from "@umbra-ui/core";
+import type { ControlItem } from "@umbra-ui/core";
+
+const selectedIndex = ref(0);
+
+const handleSelectedIndexUpdate = (index: number) => {
+  console.log("Selected index updated:", index);
+  selectedIndex.value = index;
+};
+
+const handleSegmentClick = (index: number, item: ControlItem) => {
+  console.log("Segment clicked:", item.title);
+  console.log("Segment index:", index);
+};
+</script>
+
+<template>
+  <SegmentedControl
+    :items="segments"
+    :selected-index="selectedIndex"
+    @update:selected-index="handleSelectedIndexUpdate"
+    @click="handleSegmentClick"
+  />
+</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 SegmentedControl component uses CSS custom properties that can be overridden to customize the appearance:
+
+### Color Variables
+
+```css
+/* SegmentedControl colors */
+--segmentedcontrol-bg: #f0f0f0;
+--segmentedcontrol-selected-bg: white;
+--segmentedcontrol-text-color: #60646c;
+--segmentedcontrol-selected-text-color: #646464;
+--segmentedcontrol-hover-bg: rgba(0, 0, 0, 0.04);
+--segmentedcontrol-selected-hover-bg: white;
+
+/* Border and styling */
+--segmentedcontrol-border: 1px solid #d9d9d9;
+--segmentedcontrol-border-radius: 0.353rem;
+--segmentedcontrol-selected-border-radius: 0.353rem;
+--segmentedcontrol-selected-border: 1px solid white;
+
+/* Shadow */
+--segmentedcontrol-shadow-dark: transparent;
+--segmentedcontrol-shadow-light: transparent;
+--segmentedcontrol-box-shadow: 0px 1px 0px 0px var(--segmentedcontrol-shadow-dark),
+  inset 0px 1px 0px 0px var(--segmentedcontrol-shadow-light);
+```
+
+### Custom Styling Example
+
+```vue
+<template>
+  <SegmentedControl
+    :items="items"
+    :selected-index="selectedIndex"
+    class="custom-segmented-control"
+  />
+</template>
+
+<style>
+.custom-segmented-control {
+  --segmentedcontrol-bg: #f8f9fa;
+  --segmentedcontrol-selected-bg: #ff6b6b;
+  --segmentedcontrol-selected-text-color: #ffffff;
+  --segmentedcontrol-text-color: #666;
+}
+</style>
+```
+
+## Examples
+
+### Basic Segmented Control
+
+```vue
+<script setup lang="ts">
+import { ref } from "vue";
+import { SegmentedControl } from "@umbra-ui/core";
+import type { ControlItem } from "@umbra-ui/core";
+
+const selectedIndex = ref(0);
+
+const options: ControlItem[] = [
+  { title: "All" },
+  { title: "Active" },
+  { title: "Inactive" },
+];
+</script>
+
+<template>
+  <SegmentedControl
+    :items="options"
+    :selected-index="selectedIndex"
+    @click="(index) => (selectedIndex = index)"
+  />
+</template>
+```
+
+### View Mode Selector
+
+```vue
+<script setup lang="ts">
+import { ref } from "vue";
+import { SegmentedControl } from "@umbra-ui/core";
+import type { ControlItem } from "@umbra-ui/core";
+
+const viewMode = ref(0);
+
+const viewModes: ControlItem[] = [
+  { title: "Grid" },
+  { title: "List" },
+  { title: "Card" },
+];
+
+const handleViewModeChange = (index: number) => {
+  viewMode.value = index;
+  console.log("View mode changed to:", viewModes[index].title);
+};
+</script>
+
+<template>
+  <div class="view-selector">
+    <h3>View Mode</h3>
+    <SegmentedControl
+      :items="viewModes"
+      :selected-index="viewMode"
+      @click="handleViewModeChange"
+    />
+  </div>
+</template>
+
+<style module>
+.view-selector {
+  display: flex;
+  flex-direction: column;
+  gap: 1rem;
+  align-items: center;
+}
+</style>
+```
+
+### Filter Controls
+
+```vue
+<script setup lang="ts">
+import { ref } from "vue";
+import { SegmentedControl } from "@umbra-ui/core";
+import type { ControlItem } from "@umbra-ui/core";
+
+const statusFilter = ref(0);
+const categoryFilter = ref(0);
+
+const statusOptions: ControlItem[] = [
+  { title: "All" },
+  { title: "Published" },
+  { title: "Draft" },
+  { title: "Archived" },
+];
+
+const categoryOptions: ControlItem[] = [
+  { title: "All" },
+  { title: "Tech" },
+  { title: "Design" },
+  { title: "Business" },
+];
+
+const applyFilters = () => {
+  const filters = {
+    status: statusOptions[statusFilter.value].title,
+    category: categoryOptions[categoryFilter.value].title,
+  };
+  console.log("Applied filters:", filters);
+};
+</script>
+
+<template>
+  <div class="filter-controls">
+    <div class="filter-group">
+      <label>Status</label>
+      <SegmentedControl
+        :items="statusOptions"
+        :selected-index="statusFilter"
+        @click="(index) => (statusFilter = index)"
+      />
+    </div>
+
+    <div class="filter-group">
+      <label>Category</label>
+      <SegmentedControl
+        :items="categoryOptions"
+        :selected-index="categoryFilter"
+        @click="(index) => (categoryFilter = index)"
+      />
+    </div>
+
+    <button @click="applyFilters">Apply Filters</button>
+  </div>
+</template>
+
+<style module>
+.filter-controls {
+  display: flex;
+  flex-direction: column;
+  gap: 2rem;
+  max-width: 400px;
+}
+
+.filter-group {
+  display: flex;
+  flex-direction: column;
+  gap: 1rem;
+}
+</style>
+```
+
+### Settings Panel
+
+```vue
+<script setup lang="ts">
+import { ref } from "vue";
+import { SegmentedControl } from "@umbra-ui/core";
+import type { ControlItem } from "@umbra-ui/core";
+
+const themeMode = ref(0);
+const languageMode = ref(0);
+const notificationMode = ref(0);
+
+const themeOptions: ControlItem[] = [
+  { title: "Light" },
+  { title: "Dark" },
+  { title: "Auto" },
+];
+
+const languageOptions: ControlItem[] = [
+  { title: "EN" },
+  { title: "ES" },
+  { title: "FR" },
+  { title: "DE" },
+];
+
+const notificationOptions: ControlItem[] = [
+  { title: "All" },
+  { title: "Mentions" },
+  { title: "None" },
+];
+
+const saveSettings = () => {
+  const settings = {
+    theme: themeOptions[themeMode.value].title,
+    language: languageOptions[languageMode.value].title,
+    notifications: notificationOptions[notificationMode.value].title,
+  };
+  console.log("Settings saved:", settings);
+};
+</script>
+
+<template>
+  <div class="settings-panel">
+    <h2>Settings</h2>
+
+    <div class="setting-group">
+      <label>Theme</label>
+      <SegmentedControl
+        :items="themeOptions"
+        :selected-index="themeMode"
+        @click="(index) => (themeMode = index)"
+      />
+    </div>
+
+    <div class="setting-group">
+      <label>Language</label>
+      <SegmentedControl
+        :items="languageOptions"
+        :selected-index="languageMode"
+        @click="(index) => (languageMode = index)"
+      />
+    </div>
+
+    <div class="setting-group">
+      <label>Notifications</label>
+      <SegmentedControl
+        :items="notificationOptions"
+        :selected-index="notificationMode"
+        @click="(index) => (notificationMode = index)"
+      />
+    </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>
+```
+
+### Tab Navigation
+
+```vue
+<script setup lang="ts">
+import { ref } from "vue";
+import { SegmentedControl } from "@umbra-ui/core";
+import type { ControlItem } from "@umbra-ui/core";
+
+const activeTab = ref(0);
+
+const tabs: ControlItem[] = [
+  { title: "Overview" },
+  { title: "Analytics" },
+  { title: "Reports" },
+  { title: "Settings" },
+];
+
+const tabContent = ref([
+  "Overview content goes here...",
+  "Analytics content goes here...",
+  "Reports content goes here...",
+  "Settings content goes here...",
+]);
+
+const handleTabChange = (index: number) => {
+  activeTab.value = index;
+};
+</script>
+
+<template>
+  <div class="tab-navigation">
+    <SegmentedControl
+      :items="tabs"
+      :selected-index="activeTab"
+      @click="handleTabChange"
+    />
+
+    <div class="tab-content">
+      <h3>{{ tabs[activeTab].title }}</h3>
+      <p>{{ tabContent[activeTab] }}</p>
+    </div>
+  </div>
+</template>
+
+<style module>
+.tab-navigation {
+  display: flex;
+  flex-direction: column;
+  gap: 2rem;
+  max-width: 600px;
+}
+
+.tab-content {
+  padding: 2rem;
+  background-color: #f8f9fa;
+  border-radius: 0.5rem;
+  min-height: 200px;
+}
+</style>
+```
+
+### Dynamic Segments
+
+```vue
+<script setup lang="ts">
+import { ref, computed } from "vue";
+import { SegmentedControl } from "@umbra-ui/core";
+import type { ControlItem } from "@umbra-ui/core";
+
+const selectedTimeframe = ref(0);
+
+const timeframes: ControlItem[] = [
+  { title: "1D" },
+  { title: "1W" },
+  { title: "1M" },
+  { title: "3M" },
+  { title: "1Y" },
+  { title: "All" },
+];
+
+const selectedMetric = ref(0);
+
+const metrics = computed(() => {
+  const baseMetrics: ControlItem[] = [
+    { title: "Views" },
+    { title: "Clicks" },
+    { title: "Conversions" },
+  ];
+
+  // Add more metrics based on timeframe
+  if (selectedTimeframe.value >= 2) {
+    baseMetrics.push({ title: "Revenue" });
+  }
+
+  if (selectedTimeframe.value >= 3) {
+    baseMetrics.push({ title: "ROI" });
+  }
+
+  return baseMetrics;
+});
+
+const handleTimeframeChange = (index: number) => {
+  selectedTimeframe.value = index;
+  // Reset metric selection if it's no longer available
+  if (selectedMetric.value >= metrics.value.length) {
+    selectedMetric.value = 0;
+  }
+};
+</script>
+
+<template>
+  <div class="dynamic-controls">
+    <div class="control-group">
+      <label>Timeframe</label>
+      <SegmentedControl
+        :items="timeframes"
+        :selected-index="selectedTimeframe"
+        @click="handleTimeframeChange"
+      />
+    </div>
+
+    <div class="control-group">
+      <label>Metric</label>
+      <SegmentedControl
+        :items="metrics"
+        :selected-index="selectedMetric"
+        @click="(index) => (selectedMetric = index)"
+      />
+    </div>
+
+    <div class="selected-info">
+      <p>
+        Showing {{ metrics[selectedMetric].title }} for
+        {{ timeframes[selectedTimeframe].title }}
+      </p>
+    </div>
+  </div>
+</template>
+
+<style module>
+.dynamic-controls {
+  display: flex;
+  flex-direction: column;
+  gap: 2rem;
+  max-width: 500px;
+}
+
+.control-group {
+  display: flex;
+  flex-direction: column;
+  gap: 1rem;
+}
+
+.selected-info {
+  padding: 1rem;
+  background-color: #e3f2fd;
+  border-radius: 0.25rem;
+  text-align: center;
+}
+</style>
+```
+
+## Animation Features
+
+### Smooth Transitions
+
+- **Selection Indicator**: Animated background that smoothly slides between segments
+- **Width Animation**: The selection indicator dynamically adjusts its width to match the selected segment
+- **Position Animation**: Uses cubic-bezier easing for natural movement
+- **Color Transitions**: Smooth color changes for text and background
+
+### Interactive Feedback
+
+- **Hover Effects**: Subtle background color changes on hover
+- **Active States**: Visual feedback when segments are clicked
+- **Responsive Design**: Automatically adjusts to content width changes
+
+## Notes
+
+- The component includes smooth animations with cubic-bezier easing functions
+- The selection indicator automatically adjusts its width and position based on the selected segment
+- Hover effects provide visual feedback for better user experience
+- The component supports both light and dark themes
+- All interactions are fully accessible with proper click handling
+- The component automatically handles window resize events to maintain proper positioning
+- Segments are evenly distributed and the component adapts to different content lengths
+- The selection indicator uses absolute positioning with smooth transforms for optimal performance
+- Typography classes are properly overridden to ensure consistent styling
+- The component is designed to be flexible and work well in various layout contexts