@umbra.ui/core 0.1.0

package/src/components/navigation/tabcontroller/README.md

@@ -0,0 +1,919 @@
+# TabController
+
+A flexible and feature-rich tab navigation component built with Vue 3 Composition API and TypeScript. The TabController provides an intuitive tabbed interface with support for icons, badges, keyboard navigation, and customizable layouts, perfect for organizing content into distinct sections.
+
+## Installation/Import
+
+```typescript
+import { TabController, TabItem, useTabController } from "@umbra-ui/core";
+import type { Tab, TabPosition, TabControllerContext } from "@umbra-ui/core";
+```
+
+**Dependencies:**
+
+- Vue 3.x
+- @umbra-ui/icons (for icon support)
+
+## Basic Usage
+
+```vue
+<script setup lang="ts">
+import { ref } from "vue";
+import { TabController, TabItem } from "@umbra-ui/core";
+import HomeView from "./HomeView.vue";
+import ProfileView from "./ProfileView.vue";
+import SettingsView from "./SettingsView.vue";
+
+const activeTab = ref("home");
+
+const handleTabChange = (tabId: string) => {
+  console.log("Tab changed to:", tabId);
+};
+</script>
+
+<template>
+  <div class="app">
+    <TabController
+      v-model="activeTab"
+      position="top"
+      layout="row"
+      @change="handleTabChange"
+    >
+      <TabItem id="home" label="Home" icon="home">
+        <HomeView />
+      </TabItem>
+
+      <TabItem id="profile" label="Profile" icon="user">
+        <ProfileView />
+      </TabItem>
+
+      <TabItem id="settings" label="Settings" icon="settings">
+        <SettingsView />
+      </TabItem>
+    </TabController>
+  </div>
+</template>
+
+<style module>
+.app {
+  height: 100vh;
+  display: flex;
+  flex-direction: column;
+}
+</style>
+```
+
+## Components
+
+### TabController
+
+The main container component that manages tab state and provides the tab bar interface.
+
+#### Props
+
+| Prop Name            | Type                | Required | Default     | Description                                |
+| -------------------- | ------------------- | -------- | ----------- | ------------------------------------------ |
+| `modelValue`         | `string`            | No       | `""`        | The ID of the currently active tab         |
+| `position`           | `TabPosition`       | No       | `"bottom"`  | Position of the tab bar: "top" or "bottom" |
+| `layout`             | `"row" \| "column"` | No       | `"column"`  | Layout direction for tab items             |
+| `barColor`           | `string`            | No       | `"#111111"` | Background color for the tab bar           |
+| `tabItemActiveColor` | `string`            | No       | `"#0090ff"` | Active tab item color                      |
+
+#### Events
+
+| Event Name          | Payload Type | Description                         |
+| ------------------- | ------------ | ----------------------------------- |
+| `update:modelValue` | `string`     | Emitted when the active tab changes |
+| `change`            | `string`     | Emitted when a tab is selected      |
+
+#### Slots
+
+| Slot Name | Description        |
+| --------- | ------------------ |
+| `default` | TabItem components |
+
+### TabItem
+
+Individual tab component that represents a single tab and its content.
+
+#### Props
+
+| Prop Name  | Type               | Required | Default | Description                     |
+| ---------- | ------------------ | -------- | ------- | ------------------------------- |
+| `id`       | `string`           | Yes      | -       | Unique identifier for the tab   |
+| `label`    | `string`           | Yes      | -       | Display text for the tab        |
+| `icon`     | `string`           | No       | -       | Icon name from @umbra-ui/icons  |
+| `badge`    | `string \| number` | No       | -       | Badge text or number to display |
+| `disabled` | `boolean`          | No       | `false` | Whether the tab is disabled     |
+
+#### Slots
+
+| Slot Name | Description                               |
+| --------- | ----------------------------------------- |
+| `default` | Content to display when the tab is active |
+
+## Types
+
+### Tab Interface
+
+```typescript
+interface Tab {
+  id: string;
+  label: string;
+  icon?: string;
+  badge?: string | number;
+  disabled?: boolean;
+}
+```
+
+### TabPosition Type
+
+```typescript
+type TabPosition = "top" | "bottom";
+```
+
+### TabControllerContext Interface
+
+```typescript
+interface TabControllerContext {
+  tabs: Ref<Tab[]>;
+  activeTab: Ref<string>;
+  registerTab: (tab: Tab) => void;
+  unregisterTab: (id: string) => void;
+  setActiveTab: (id: string) => void;
+  goToTab: (index: number) => void;
+  nextTab: () => void;
+  previousTab: () => void;
+  animated: boolean;
+}
+```
+
+## useTabController Composable
+
+The `useTabController` composable provides access to the tab controller context and can be used within TabItem components or child components.
+
+```typescript
+import { useTabController } from "@umbra-ui/core";
+
+const {
+  tabs,
+  activeTab,
+  registerTab,
+  unregisterTab,
+  setActiveTab,
+  goToTab,
+  nextTab,
+  previousTab,
+  animated,
+} = useTabController();
+```
+
+### Composable Returns
+
+| Property        | Type                      | Description                           |
+| --------------- | ------------------------- | ------------------------------------- |
+| `tabs`          | `Ref<Tab[]>`              | Reactive array of all registered tabs |
+| `activeTab`     | `Ref<string>`             | ID of the currently active tab        |
+| `registerTab`   | `(tab: Tab) => void`      | Register a new tab                    |
+| `unregisterTab` | `(id: string) => void`    | Unregister a tab                      |
+| `setActiveTab`  | `(id: string) => void`    | Set the active tab                    |
+| `goToTab`       | `(index: number) => void` | Navigate to tab by index              |
+| `nextTab`       | `() => void`              | Navigate to the next tab              |
+| `previousTab`   | `() => void`              | Navigate to the previous tab          |
+| `animated`      | `boolean`                 | Whether animations are enabled        |
+
+## CSS Customization
+
+### Layout Variables
+
+```css
+.tab-controller {
+  --tabcontroller-container-bg: #ffffff;
+  --tabcontroller-bar-bg: #f8f9fa;
+  --tabcontroller-bar-border: #e9ecef;
+  --tabcontroller-tab-text: #495057;
+  --tabcontroller-tab-active-text: #007bff;
+  --tabcontroller-tab-hover-bg: #e9ecef;
+  --tabcontroller-tab-disabled-opacity: 0.5;
+  --tabcontroller-badge-bg: #dc3545;
+  --tabcontroller-badge-text: #ffffff;
+}
+```
+
+### Container Styling
+
+```css
+.tab-controller {
+  display: flex;
+  flex-direction: column;
+  height: 100%;
+  background: var(--tabcontroller-container-bg);
+  overflow: hidden;
+}
+```
+
+### Tab Bar Styling
+
+```css
+.tab-controller .tabBar {
+  display: flex;
+  background: var(--tabcontroller-bar-bg);
+  border-top: 1px solid var(--tabcontroller-bar-border);
+  padding: 0.353rem;
+}
+
+.tab-controller .tabBar--column {
+  gap: 0.353rem;
+}
+
+.tab-controller .tabBar--row {
+  gap: 0.5rem;
+}
+```
+
+### Tab Item Styling
+
+```css
+.tab-controller .tabItem {
+  flex: 1;
+  display: flex;
+  align-items: center;
+  justify-content: center;
+  padding: 8px 4px;
+  background: none;
+  border: none;
+  cursor: pointer;
+  transition: all 0.2s ease;
+  color: var(--tabcontroller-tab-text);
+  border-radius: 0.353rem;
+  font-size: 12px;
+}
+
+.tab-controller .tabItem--active {
+  color: var(--tabcontroller-tab-active-text);
+}
+
+.tab-controller .tabItem--disabled {
+  opacity: var(--tabcontroller-tab-disabled-opacity);
+  cursor: not-allowed;
+}
+```
+
+## Examples
+
+### Mobile App Navigation
+
+```vue
+<script setup lang="ts">
+import { ref } from "vue";
+import { TabController, TabItem } from "@umbra-ui/core";
+import HomeScreen from "./HomeScreen.vue";
+import SearchScreen from "./SearchScreen.vue";
+import ProfileScreen from "./ProfileScreen.vue";
+import NotificationsScreen from "./NotificationsScreen.vue";
+
+const activeTab = ref("home");
+
+const handleTabChange = (tabId: string) => {
+  console.log("Navigated to:", tabId);
+};
+</script>
+
+<template>
+  <div class="mobile-app">
+    <TabController
+      v-model="activeTab"
+      position="bottom"
+      layout="column"
+      @change="handleTabChange"
+    >
+      <TabItem id="home" label="Home" icon="home">
+        <HomeScreen />
+      </TabItem>
+
+      <TabItem id="search" label="Search" icon="search">
+        <SearchScreen />
+      </TabItem>
+
+      <TabItem id="notifications" label="Notifications" icon="bell" :badge="5">
+        <NotificationsScreen />
+      </TabItem>
+
+      <TabItem id="profile" label="Profile" icon="user">
+        <ProfileScreen />
+      </TabItem>
+    </TabController>
+  </div>
+</template>
+
+<style module>
+.mobile-app {
+  height: 100vh;
+  display: flex;
+  flex-direction: column;
+  background: #f8f9fa;
+}
+</style>
+```
+
+### Desktop Application Tabs
+
+```vue
+<script setup lang="ts">
+import { ref } from "vue";
+import { TabController, TabItem } from "@umbra-ui/core";
+import DashboardView from "./DashboardView.vue";
+import AnalyticsView from "./AnalyticsView.vue";
+import ReportsView from "./ReportsView.vue";
+import SettingsView from "./SettingsView.vue";
+
+const activeTab = ref("dashboard");
+
+const handleTabChange = (tabId: string) => {
+  console.log("Tab changed to:", tabId);
+};
+</script>
+
+<template>
+  <div class="desktop-app">
+    <header class="app-header">
+      <h1 class="app-title">My Application</h1>
+    </header>
+
+    <TabController
+      v-model="activeTab"
+      position="top"
+      layout="row"
+      @change="handleTabChange"
+    >
+      <TabItem id="dashboard" label="Dashboard" icon="dashboard">
+        <DashboardView />
+      </TabItem>
+
+      <TabItem id="analytics" label="Analytics" icon="chart">
+        <AnalyticsView />
+      </TabItem>
+
+      <TabItem id="reports" label="Reports" icon="file">
+        <ReportsView />
+      </TabItem>
+
+      <TabItem id="settings" label="Settings" icon="settings">
+        <SettingsView />
+      </TabItem>
+    </TabController>
+  </div>
+</template>
+
+<style module>
+.desktop-app {
+  height: 100vh;
+  display: flex;
+  flex-direction: column;
+  background: #ffffff;
+}
+
+.app-header {
+  padding: 16px 24px;
+  background: #f8f9fa;
+  border-bottom: 1px solid #e9ecef;
+}
+
+.app-title {
+  font-size: 24px;
+  font-weight: 600;
+  color: #212529;
+  margin: 0;
+}
+</style>
+```
+
+### Settings Panel with Disabled Tabs
+
+```vue
+<script setup lang="ts">
+import { ref } from "vue";
+import { TabController, TabItem } from "@umbra-ui/core";
+import GeneralSettings from "./GeneralSettings.vue";
+import AppearanceSettings from "./AppearanceSettings.vue";
+import PrivacySettings from "./PrivacySettings.vue";
+import AdvancedSettings from "./AdvancedSettings.vue";
+
+const activeTab = ref("general");
+const isProUser = ref(false);
+
+const handleTabChange = (tabId: string) => {
+  console.log("Settings tab changed to:", tabId);
+};
+</script>
+
+<template>
+  <div class="settings-panel">
+    <div class="settings-header">
+      <h2 class="settings-title">Settings</h2>
+      <p class="settings-subtitle">Configure your application preferences</p>
+    </div>
+
+    <TabController
+      v-model="activeTab"
+      position="top"
+      layout="row"
+      @change="handleTabChange"
+    >
+      <TabItem id="general" label="General" icon="settings">
+        <GeneralSettings />
+      </TabItem>
+
+      <TabItem id="appearance" label="Appearance" icon="palette">
+        <AppearanceSettings />
+      </TabItem>
+
+      <TabItem
+        id="privacy"
+        label="Privacy"
+        icon="shield"
+        :disabled="!isProUser"
+        :badge="!isProUser ? 'Pro' : undefined"
+      >
+        <PrivacySettings />
+      </TabItem>
+
+      <TabItem
+        id="advanced"
+        label="Advanced"
+        icon="gear"
+        :disabled="!isProUser"
+        :badge="!isProUser ? 'Pro' : undefined"
+      >
+        <AdvancedSettings />
+      </TabItem>
+    </TabController>
+
+    <div class="settings-footer">
+      <button v-if="!isProUser" @click="isProUser = true" class="upgrade-btn">
+        Upgrade to Pro
+      </button>
+    </div>
+  </div>
+</template>
+
+<style module>
+.settings-panel {
+  height: 100vh;
+  display: flex;
+  flex-direction: column;
+  background: #f8f9fa;
+}
+
+.settings-header {
+  padding: 24px;
+  background: white;
+  border-bottom: 1px solid #e9ecef;
+}
+
+.settings-title {
+  font-size: 28px;
+  font-weight: 700;
+  color: #1a202c;
+  margin: 0 0 8px 0;
+}
+
+.settings-subtitle {
+  font-size: 16px;
+  color: #718096;
+  margin: 0;
+}
+
+.settings-footer {
+  padding: 16px 24px;
+  background: white;
+  border-top: 1px solid #e9ecef;
+}
+
+.upgrade-btn {
+  padding: 12px 24px;
+  background: linear-gradient(135deg, #667eea 0%, #764ba2 100%);
+  color: white;
+  border: none;
+  border-radius: 8px;
+  font-weight: 600;
+  cursor: pointer;
+  transition: all 0.2s ease;
+}
+
+.upgrade-btn:hover {
+  transform: translateY(-1px);
+  box-shadow: 0 4px 12px rgba(102, 126, 234, 0.4);
+}
+</style>
+```
+
+### Dynamic Tab Management
+
+```vue
+<script setup lang="ts">
+import { ref } from "vue";
+import { TabController, TabItem, useTabController } from "@umbra-ui/core";
+import DynamicView from "./DynamicView.vue";
+
+const activeTab = ref("tab1");
+const tabCounter = ref(2);
+
+const tabs = ref([
+  { id: "tab1", label: "Tab 1", icon: "home" },
+  { id: "tab2", label: "Tab 2", icon: "user" },
+]);
+
+const addTab = () => {
+  const newTab = {
+    id: `tab${tabCounter.value}`,
+    label: `Tab ${tabCounter.value}`,
+    icon: "plus",
+  };
+  tabs.value.push(newTab);
+  activeTab.value = newTab.id;
+  tabCounter.value++;
+};
+
+const removeTab = (tabId: string) => {
+  if (tabs.value.length > 1) {
+    const index = tabs.value.findIndex((tab) => tab.id === tabId);
+    if (index > -1) {
+      tabs.value.splice(index, 1);
+      if (activeTab.value === tabId) {
+        activeTab.value = tabs.value[Math.max(0, index - 1)].id;
+      }
+    }
+  }
+};
+
+const handleTabChange = (tabId: string) => {
+  console.log("Tab changed to:", tabId);
+};
+</script>
+
+<template>
+  <div class="dynamic-tabs">
+    <div class="tab-controls">
+      <button @click="addTab" class="control-btn add">Add Tab</button>
+      <button
+        v-for="tab in tabs"
+        :key="tab.id"
+        @click="removeTab(tab.id)"
+        :disabled="tabs.length <= 1"
+        class="control-btn remove"
+      >
+        Remove {{ tab.label }}
+      </button>
+    </div>
+
+    <TabController
+      v-model="activeTab"
+      position="top"
+      layout="row"
+      @change="handleTabChange"
+    >
+      <TabItem
+        v-for="tab in tabs"
+        :key="tab.id"
+        :id="tab.id"
+        :label="tab.label"
+        :icon="tab.icon"
+      >
+        <DynamicView :tab-id="tab.id" />
+      </TabItem>
+    </TabController>
+  </div>
+</template>
+
+<style module>
+.dynamic-tabs {
+  height: 100vh;
+  display: flex;
+  flex-direction: column;
+  background: #f8f9fa;
+}
+
+.tab-controls {
+  display: flex;
+  gap: 8px;
+  padding: 16px;
+  background: white;
+  border-bottom: 1px solid #e9ecef;
+  flex-wrap: wrap;
+}
+
+.control-btn {
+  padding: 8px 16px;
+  border: 1px solid #dee2e6;
+  border-radius: 6px;
+  cursor: pointer;
+  font-size: 14px;
+  transition: all 0.2s ease;
+}
+
+.control-btn.add {
+  background: #28a745;
+  color: white;
+  border-color: #28a745;
+}
+
+.control-btn.add:hover {
+  background: #218838;
+  border-color: #1e7e34;
+}
+
+.control-btn.remove {
+  background: #dc3545;
+  color: white;
+  border-color: #dc3545;
+}
+
+.control-btn.remove:hover:not(:disabled) {
+  background: #c82333;
+  border-color: #bd2130;
+}
+
+.control-btn:disabled {
+  opacity: 0.5;
+  cursor: not-allowed;
+}
+</style>
+```
+
+### Custom Tab Content with Navigation
+
+```vue
+<script setup lang="ts">
+import { ref } from "vue";
+import { TabController, TabItem, useTabController } from "@umbra-ui/core";
+import CustomView from "./CustomView.vue";
+
+const activeTab = ref("view1");
+
+const handleTabChange = (tabId: string) => {
+  console.log("Tab changed to:", tabId);
+};
+</script>
+
+<template>
+  <div class="custom-tabs">
+    <TabController
+      v-model="activeTab"
+      position="top"
+      layout="row"
+      @change="handleTabChange"
+    >
+      <TabItem id="view1" label="View 1" icon="eye">
+        <CustomView
+          title="First View"
+          :can-navigate="true"
+          @navigate="activeTab = 'view2'"
+        />
+      </TabItem>
+
+      <TabItem id="view2" label="View 2" icon="eye">
+        <CustomView
+          title="Second View"
+          :can-navigate="true"
+          @navigate="activeTab = 'view3'"
+        />
+      </TabItem>
+
+      <TabItem id="view3" label="View 3" icon="eye">
+        <CustomView title="Third View" :can-navigate="false" />
+      </TabItem>
+    </TabController>
+  </div>
+</template>
+
+<style module>
+.custom-tabs {
+  height: 100vh;
+  display: flex;
+  flex-direction: column;
+  background: #ffffff;
+}
+</style>
+```
+
+## Advanced Usage
+
+### Programmatic Tab Control
+
+```vue
+<script setup lang="ts">
+import { ref } from "vue";
+import { TabController, TabItem, useTabController } from "@umbra-ui/core";
+
+const activeTab = ref("tab1");
+const tabControllerRef = ref();
+
+// Access tab controller methods
+const nextTab = () => {
+  // This would need to be implemented in the TabController component
+  console.log("Navigate to next tab");
+};
+
+const previousTab = () => {
+  console.log("Navigate to previous tab");
+};
+
+const goToTab = (index: number) => {
+  console.log("Go to tab index:", index);
+};
+</script>
+
+<template>
+  <div class="programmatic-tabs">
+    <div class="tab-navigation">
+      <button @click="nextTab" class="nav-btn">Next Tab</button>
+      <button @click="previousTab" class="nav-btn">Previous Tab</button>
+      <button @click="goToTab(0)" class="nav-btn">Go to Tab 1</button>
+      <button @click="goToTab(1)" class="nav-btn">Go to Tab 2</button>
+    </div>
+
+    <TabController
+      ref="tabControllerRef"
+      v-model="activeTab"
+      position="top"
+      layout="row"
+    >
+      <TabItem id="tab1" label="Tab 1" icon="home">
+        <div class="tab-content">Content for Tab 1</div>
+      </TabItem>
+
+      <TabItem id="tab2" label="Tab 2" icon="user">
+        <div class="tab-content">Content for Tab 2</div>
+      </TabItem>
+    </TabController>
+  </div>
+</template>
+
+<style module>
+.programmatic-tabs {
+  height: 100vh;
+  display: flex;
+  flex-direction: column;
+}
+
+.tab-navigation {
+  display: flex;
+  gap: 8px;
+  padding: 16px;
+  background: #f8f9fa;
+  border-bottom: 1px solid #e9ecef;
+}
+
+.nav-btn {
+  padding: 8px 16px;
+  background: #007bff;
+  color: white;
+  border: none;
+  border-radius: 6px;
+  cursor: pointer;
+  font-size: 14px;
+  transition: all 0.2s ease;
+}
+
+.nav-btn:hover {
+  background: #0056b3;
+}
+
+.tab-content {
+  padding: 24px;
+  font-size: 16px;
+  color: #495057;
+}
+</style>
+```
+
+### Integration with Router
+
+```vue
+<script setup lang="ts">
+import { ref, watch } from "vue";
+import { useRoute, useRouter } from "vue-router";
+import { TabController, TabItem } from "@umbra-ui/core";
+
+const route = useRoute();
+const router = useRouter();
+const activeTab = ref("home");
+
+const tabs = [
+  { id: "home", label: "Home", icon: "home", route: "/" },
+  { id: "about", label: "About", icon: "info", route: "/about" },
+  { id: "contact", label: "Contact", icon: "mail", route: "/contact" },
+];
+
+// Sync with router
+watch(
+  () => route.path,
+  (newPath) => {
+    const tab = tabs.find((t) => t.route === newPath);
+    if (tab) {
+      activeTab.value = tab.id;
+    }
+  },
+  { immediate: true }
+);
+
+const handleTabChange = (tabId: string) => {
+  const tab = tabs.find((t) => t.id === tabId);
+  if (tab) {
+    router.push(tab.route);
+  }
+};
+</script>
+
+<template>
+  <div class="routed-tabs">
+    <TabController
+      v-model="activeTab"
+      position="top"
+      layout="row"
+      @change="handleTabChange"
+    >
+      <TabItem
+        v-for="tab in tabs"
+        :key="tab.id"
+        :id="tab.id"
+        :label="tab.label"
+        :icon="tab.icon"
+      >
+        <router-view />
+      </TabItem>
+    </TabController>
+  </div>
+</template>
+
+<style module>
+.routed-tabs {
+  height: 100vh;
+  display: flex;
+  flex-direction: column;
+}
+</style>
+```
+
+## Performance Considerations
+
+- **Component Registration**: Tabs are automatically registered and unregistered when mounted/unmounted
+- **Reactive Updates**: Tab properties are watched and updated reactively
+- **Memory Management**: Proper cleanup when tabs are removed
+- **Icon Loading**: Icons are loaded on-demand from the @umbra-ui/icons package
+
+## Accessibility
+
+- **Keyboard Navigation**: Support for arrow keys and tab navigation
+- **Screen Reader Support**: Proper ARIA labels and roles
+- **Focus Management**: Focus is maintained during tab changes
+- **Disabled State**: Proper handling of disabled tabs
+
+## Browser Support
+
+- **Modern Browsers**: Chrome 88+, Firefox 85+, Safari 14+, Edge 88+
+- **Mobile Browsers**: iOS Safari 14+, Chrome Mobile 88+
+- **CSS Features**: Uses CSS Grid and modern layout features
+- **JavaScript**: Requires ES2020+ support
+
+## Troubleshooting
+
+### Common Issues
+
+1. **Tabs not displaying**: Ensure TabItem components are properly nested within TabController
+2. **Icons not showing**: Verify icon names match those available in @umbra-ui/icons
+3. **Active tab not updating**: Check that the modelValue prop is properly bound
+4. **Content not showing**: Ensure TabItem components have content in their default slot
+
+### Debug Mode
+
+```vue
+<script setup lang="ts">
+import { ref, watch } from "vue";
+import { TabController, TabItem, useTabController } from "@umbra-ui/core";
+
+const activeTab = ref("tab1");
+
+// Watch for tab changes
+watch(activeTab, (newTab) => {
+  console.log("Active tab changed to:", newTab);
+});
+</script>
+```
+
+## Migration Guide
+
+### From v1 to v2
+
+- `v-model` prop is now `modelValue`
+- `position` prop now supports "top" and "bottom" values
+- `layout` prop now supports "row" and "column" values
+- Icon system has been updated to use @umbra-ui/icons
+
+### Breaking Changes
+
+- Removed `activeTab` prop in favor of `modelValue`
+- Changed event names from `tab-change` to `change`
+- Updated CSS class naming convention
+- Modified icon prop to use string names instead of components