@umbra.ui/core 0.1.0

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

@@ -0,0 +1,994 @@
+# NavigationStack
+
+A powerful navigation stack component built with Vue 3 Composition API and TypeScript. The NavigationStack provides smooth, animated transitions between different views using GSAP's FLIP (First, Last, Invert, Play) animation technique, creating a native app-like navigation experience.
+
+## Installation/Import
+
+```typescript
+import { NavigationStack, useNavigationStack } from "@umbra-ui/core";
+import type { Pane } from "@umbra-ui/core";
+```
+
+**Dependencies:**
+
+- Vue 3.x
+- gsap (for animations)
+- gsap/Flip (for FLIP animations)
+
+## Basic Usage
+
+```vue
+<script setup lang="ts">
+import { ref } from "vue";
+import { NavigationStack } from "@umbra-ui/core";
+import HomeView from "./HomeView.vue";
+import ProfileView from "./ProfileView.vue";
+import SettingsView from "./SettingsView.vue";
+
+// Define your navigation panes
+const panes = ref([
+  {
+    name: "home",
+    background: "#ffffff",
+    foreground: "#000000",
+    component: HomeView,
+    props: { title: "Home" },
+  },
+  {
+    name: "profile",
+    background: "#f8f9fa",
+    foreground: "#212529",
+    component: ProfileView,
+    props: { userId: 123 },
+  },
+  {
+    name: "settings",
+    background: "#e9ecef",
+    foreground: "#495057",
+    component: SettingsView,
+    props: { theme: "light" },
+  },
+]);
+
+const navigationRef = ref();
+
+// Navigate to specific pane
+const goToPane = (index: number) => {
+  navigationRef.value?.navigate(index);
+};
+
+// Add new pane
+const addNewPane = () => {
+  navigationRef.value?.addPane(
+    {
+      name: "new",
+      background: "#007bff",
+      foreground: "#ffffff",
+      component: HomeView,
+      props: { title: "New View" },
+    },
+    true
+  ); // Navigate to new pane
+};
+</script>
+
+<template>
+  <div class="app">
+    <div class="navigation-controls">
+      <button @click="goToPane(0)">Home</button>
+      <button @click="goToPane(1)">Profile</button>
+      <button @click="goToPane(2)">Settings</button>
+      <button @click="addNewPane">Add New</button>
+    </div>
+
+    <NavigationStack
+      ref="navigationRef"
+      task-key="main-navigation"
+      :panes="panes"
+      :child-width="800"
+      :child-height="600"
+    />
+  </div>
+</template>
+
+<style module>
+.app {
+  height: 100vh;
+  display: flex;
+  flex-direction: column;
+}
+
+.navigation-controls {
+  display: flex;
+  gap: 12px;
+  padding: 16px;
+  background: var(--background-1);
+  border-bottom: 1px solid var(--border-2);
+}
+
+.navigation-controls button {
+  padding: 8px 16px;
+  border: 1px solid var(--border-2);
+  background: var(--background-2);
+  color: var(--text-1);
+  border-radius: 6px;
+  cursor: pointer;
+  transition: all 0.2s ease;
+}
+
+.navigation-controls button:hover {
+  background: var(--background-3);
+  border-color: var(--border-3);
+}
+</style>
+```
+
+## Props
+
+| Prop Name     | Type     | Required | Default | Description                                                     |
+| ------------- | -------- | -------- | ------- | --------------------------------------------------------------- |
+| `taskKey`     | `string` | Yes      | -       | Unique identifier for the navigation stack instance             |
+| `panes`       | `Pane[]` | Yes      | -       | Array of panes to display in the navigation stack               |
+| `childWidth`  | `number` | No       | `null`  | Fixed width for child components (uses container width if null) |
+| `childHeight` | `number` | No       | `null`  | Fixed height for child components (uses 100% if null)           |
+
+## Pane Interface
+
+```typescript
+interface Pane {
+  name: string;
+  background: string;
+  foreground: string;
+  component: any;
+  props: Record<string, any>;
+}
+```
+
+### Pane Properties
+
+| Property     | Type                  | Description                             |
+| ------------ | --------------------- | --------------------------------------- |
+| `name`       | `string`              | Unique identifier for the pane          |
+| `background` | `string`              | Background color for the pane container |
+| `foreground` | `string`              | Text color for the pane content         |
+| `component`  | `Component`           | Vue component to render in the pane     |
+| `props`      | `Record<string, any>` | Props to pass to the component          |
+
+## Events
+
+The NavigationStack component doesn't emit events directly, but you can access navigation methods through template refs.
+
+## Exposed Methods/Refs
+
+| Method        | Parameters                                             | Description                          |
+| ------------- | ------------------------------------------------------ | ------------------------------------ |
+| `navigate`    | `(index: number, animated?: boolean)`                  | Navigate to a specific pane by index |
+| `addPane`     | `(pane: Pane, navigateToNew?: boolean)`                | Add a new pane to the stack          |
+| `removePane`  | `(index: number)`                                      | Remove a pane from the stack         |
+| `insertPane`  | `(index: number, pane: Pane, navigateToNew?: boolean)` | Insert a pane at a specific index    |
+| `updatePanes` | `(newPanes: Pane[])`                                   | Update the entire panes array        |
+
+## useNavigationStack Composable
+
+The `useNavigationStack` composable provides the core navigation logic and can be used independently:
+
+```typescript
+import { useNavigationStack } from "@umbra-ui/core";
+
+const {
+  panes,
+  visiblePanes,
+  currentIndex,
+  navigate,
+  addPane,
+  removePane,
+  insertPane,
+  updatePanes,
+} = useNavigationStack(initialPanes, taskKey);
+```
+
+### Composable Returns
+
+| Property       | Type                                                           | Description                              |
+| -------------- | -------------------------------------------------------------- | ---------------------------------------- |
+| `panes`        | `Ref<Pane[]>`                                                  | Reactive array of all panes              |
+| `visiblePanes` | `ComputedRef<boolean[]>`                                       | Array indicating which panes are visible |
+| `currentIndex` | `Ref<number>`                                                  | Current active pane index                |
+| `navigate`     | `(index: number, animated?: boolean) => void`                  | Navigate to specific pane                |
+| `addPane`      | `(pane: Pane, navigateToNew?: boolean) => void`                | Add new pane                             |
+| `removePane`   | `(index: number) => void`                                      | Remove pane                              |
+| `insertPane`   | `(index: number, pane: Pane, navigateToNew?: boolean) => void` | Insert pane                              |
+| `updatePanes`  | `(newPanes: Pane[]) => void`                                   | Update all panes                         |
+
+## CSS Customization
+
+### Layout Variables
+
+```css
+.navigation-stack {
+  --currentContainerWidth: 100%;
+  --maxHeight: 100%;
+}
+```
+
+### Container Styling
+
+```css
+.navigation-stack {
+  position: relative;
+  display: grid;
+  grid-template-areas: "content";
+  height: 100%;
+  width: 100%;
+  overflow: hidden;
+}
+```
+
+### Pane Styling
+
+```css
+.navigation-stack .pane {
+  display: grid;
+  grid-template-columns: 1fr;
+  grid-template-areas: "content";
+  height: 100%;
+}
+
+.navigation-stack .component_container {
+  grid-area: content;
+  overflow: hidden;
+  width: var(--currentContainerWidth, 100%);
+  align-self: center;
+  justify-self: center;
+  height: var(--maxHeight, 100%);
+}
+```
+
+## Examples
+
+### Mobile App Navigation
+
+```vue
+<script setup lang="ts">
+import { ref } from "vue";
+import { NavigationStack } from "@umbra-ui/core";
+import HomeScreen from "./HomeScreen.vue";
+import ChatScreen from "./ChatScreen.vue";
+import ProfileScreen from "./ProfileScreen.vue";
+
+const panes = ref([
+  {
+    name: "home",
+    background: "#ffffff",
+    foreground: "#000000",
+    component: HomeScreen,
+    props: {},
+  },
+  {
+    name: "chat",
+    background: "#f0f8ff",
+    foreground: "#1a365d",
+    component: ChatScreen,
+    props: { chatId: "main" },
+  },
+  {
+    name: "profile",
+    background: "#f7fafc",
+    foreground: "#2d3748",
+    component: ProfileScreen,
+    props: { userId: "current" },
+  },
+]);
+
+const navigationRef = ref();
+const currentPane = ref(0);
+
+const goToPane = (index: number) => {
+  currentPane.value = index;
+  navigationRef.value?.navigate(index);
+};
+
+const goBack = () => {
+  if (currentPane.value > 0) {
+    goToPane(currentPane.value - 1);
+  }
+};
+
+const goForward = () => {
+  if (currentPane.value < panes.value.length - 1) {
+    goToPane(currentPane.value + 1);
+  }
+};
+</script>
+
+<template>
+  <div class="mobile-app">
+    <!-- Navigation Header -->
+    <header class="app-header">
+      <button @click="goBack" :disabled="currentPane === 0" class="nav-button">
+        ← Back
+      </button>
+      <h1 class="app-title">{{ panes[currentPane].name }}</h1>
+      <button
+        @click="goForward"
+        :disabled="currentPane === panes.length - 1"
+        class="nav-button"
+      >
+        Forward →
+      </button>
+    </header>
+
+    <!-- Navigation Stack -->
+    <NavigationStack
+      ref="navigationRef"
+      task-key="mobile-navigation"
+      :panes="panes"
+    />
+
+    <!-- Bottom Navigation -->
+    <nav class="bottom-nav">
+      <button
+        v-for="(pane, index) in panes"
+        :key="pane.name"
+        @click="goToPane(index)"
+        :class="['nav-tab', { active: currentPane === index }]"
+      >
+        {{ pane.name }}
+      </button>
+    </nav>
+  </div>
+</template>
+
+<style module>
+.mobile-app {
+  height: 100vh;
+  display: flex;
+  flex-direction: column;
+  background: #000;
+}
+
+.app-header {
+  display: flex;
+  align-items: center;
+  justify-content: space-between;
+  padding: 12px 16px;
+  background: var(--background-1);
+  border-bottom: 1px solid var(--border-2);
+  min-height: 44px;
+}
+
+.app-title {
+  font-size: 18px;
+  font-weight: 600;
+  color: var(--text-1);
+  margin: 0;
+}
+
+.nav-button {
+  padding: 8px 12px;
+  background: transparent;
+  border: none;
+  color: var(--text-2);
+  cursor: pointer;
+  border-radius: 6px;
+  transition: background 0.2s ease;
+}
+
+.nav-button:hover:not(:disabled) {
+  background: var(--background-2);
+}
+
+.nav-button:disabled {
+  opacity: 0.3;
+  cursor: not-allowed;
+}
+
+.bottom-nav {
+  display: flex;
+  background: var(--background-1);
+  border-top: 1px solid var(--border-2);
+  padding: 8px 0;
+}
+
+.nav-tab {
+  flex: 1;
+  padding: 12px 8px;
+  background: transparent;
+  border: none;
+  color: var(--text-2);
+  cursor: pointer;
+  transition: all 0.2s ease;
+  text-transform: capitalize;
+}
+
+.nav-tab.active {
+  color: var(--accent);
+  background: var(--background-2);
+}
+
+.nav-tab:hover {
+  background: var(--background-2);
+}
+</style>
+```
+
+### Wizard/Onboarding Flow
+
+```vue
+<script setup lang="ts">
+import { ref } from "vue";
+import { NavigationStack } from "@umbra-ui/core";
+import WelcomeStep from "./WelcomeStep.vue";
+import PersonalInfoStep from "./PersonalInfoStep.vue";
+import PreferencesStep from "./PreferencesStep.vue";
+import ConfirmationStep from "./ConfirmationStep.vue";
+
+const panes = ref([
+  {
+    name: "welcome",
+    background: "linear-gradient(135deg, #667eea 0%, #764ba2 100%)",
+    foreground: "#ffffff",
+    component: WelcomeStep,
+    props: { title: "Welcome!" },
+  },
+  {
+    name: "personal",
+    background: "linear-gradient(135deg, #f093fb 0%, #f5576c 100%)",
+    foreground: "#ffffff",
+    component: PersonalInfoStep,
+    props: { step: 2 },
+  },
+  {
+    name: "preferences",
+    background: "linear-gradient(135deg, #4facfe 0%, #00f2fe 100%)",
+    foreground: "#ffffff",
+    component: PreferencesStep,
+    props: { step: 3 },
+  },
+  {
+    name: "confirmation",
+    background: "linear-gradient(135deg, #43e97b 0%, #38f9d7 100%)",
+    foreground: "#ffffff",
+    component: ConfirmationStep,
+    props: { step: 4 },
+  },
+]);
+
+const navigationRef = ref();
+const currentStep = ref(0);
+const totalSteps = panes.value.length;
+
+const nextStep = () => {
+  if (currentStep.value < totalSteps - 1) {
+    currentStep.value++;
+    navigationRef.value?.navigate(currentStep.value);
+  }
+};
+
+const prevStep = () => {
+  if (currentStep.value > 0) {
+    currentStep.value--;
+    navigationRef.value?.navigate(currentStep.value);
+  }
+};
+
+const completeWizard = () => {
+  console.log("Wizard completed!");
+  // Handle completion
+};
+</script>
+
+<template>
+  <div class="wizard-container">
+    <!-- Progress Indicator -->
+    <div class="progress-header">
+      <div class="progress-bar">
+        <div
+          class="progress-fill"
+          :style="{ width: `${((currentStep + 1) / totalSteps) * 100}%` }"
+        />
+      </div>
+      <span class="progress-text">
+        Step {{ currentStep + 1 }} of {{ totalSteps }}
+      </span>
+    </div>
+
+    <!-- Navigation Stack -->
+    <NavigationStack
+      ref="navigationRef"
+      task-key="wizard-navigation"
+      :panes="panes"
+    />
+
+    <!-- Navigation Controls -->
+    <div class="wizard-controls">
+      <button
+        @click="prevStep"
+        :disabled="currentStep === 0"
+        class="control-button secondary"
+      >
+        Previous
+      </button>
+
+      <button
+        v-if="currentStep < totalSteps - 1"
+        @click="nextStep"
+        class="control-button primary"
+      >
+        Next
+      </button>
+
+      <button v-else @click="completeWizard" class="control-button primary">
+        Complete
+      </button>
+    </div>
+  </div>
+</template>
+
+<style module>
+.wizard-container {
+  height: 100vh;
+  display: flex;
+  flex-direction: column;
+  background: #f8f9fa;
+}
+
+.progress-header {
+  padding: 20px;
+  background: white;
+  border-bottom: 1px solid #e9ecef;
+}
+
+.progress-bar {
+  width: 100%;
+  height: 4px;
+  background: #e9ecef;
+  border-radius: 2px;
+  overflow: hidden;
+  margin-bottom: 8px;
+}
+
+.progress-fill {
+  height: 100%;
+  background: linear-gradient(90deg, #667eea, #764ba2);
+  transition: width 0.3s ease;
+}
+
+.progress-text {
+  font-size: 14px;
+  color: #6c757d;
+  font-weight: 500;
+}
+
+.wizard-controls {
+  display: flex;
+  justify-content: space-between;
+  padding: 20px;
+  background: white;
+  border-top: 1px solid #e9ecef;
+}
+
+.control-button {
+  padding: 12px 24px;
+  border: none;
+  border-radius: 8px;
+  font-weight: 600;
+  cursor: pointer;
+  transition: all 0.2s ease;
+  min-width: 100px;
+}
+
+.control-button.primary {
+  background: linear-gradient(135deg, #667eea 0%, #764ba2 100%);
+  color: white;
+}
+
+.control-button.primary:hover {
+  transform: translateY(-1px);
+  box-shadow: 0 4px 12px rgba(102, 126, 234, 0.4);
+}
+
+.control-button.secondary {
+  background: #f8f9fa;
+  color: #6c757d;
+  border: 1px solid #dee2e6;
+}
+
+.control-button.secondary:hover:not(:disabled) {
+  background: #e9ecef;
+  border-color: #adb5bd;
+}
+
+.control-button:disabled {
+  opacity: 0.5;
+  cursor: not-allowed;
+}
+</style>
+```
+
+### Tab-Based Interface
+
+```vue
+<script setup lang="ts">
+import { ref } from "vue";
+import { NavigationStack } from "@umbra-ui/core";
+import DashboardTab from "./DashboardTab.vue";
+import AnalyticsTab from "./AnalyticsTab.vue";
+import ReportsTab from "./ReportsTab.vue";
+import SettingsTab from "./SettingsTab.vue";
+
+const panes = ref([
+  {
+    name: "dashboard",
+    background: "#ffffff",
+    foreground: "#1a202c",
+    component: DashboardTab,
+    props: { title: "Dashboard" },
+  },
+  {
+    name: "analytics",
+    background: "#f7fafc",
+    foreground: "#2d3748",
+    component: AnalyticsTab,
+    props: { period: "30d" },
+  },
+  {
+    name: "reports",
+    background: "#edf2f7",
+    foreground: "#4a5568",
+    component: ReportsTab,
+    props: { type: "summary" },
+  },
+  {
+    name: "settings",
+    background: "#e2e8f0",
+    foreground: "#718096",
+    component: SettingsTab,
+    props: { section: "general" },
+  },
+]);
+
+const navigationRef = ref();
+const activeTab = ref(0);
+
+const switchTab = (index: number) => {
+  activeTab.value = index;
+  navigationRef.value?.navigate(index);
+};
+
+const tabIcons = {
+  dashboard: "📊",
+  analytics: "📈",
+  reports: "📋",
+  settings: "⚙️",
+};
+</script>
+
+<template>
+  <div class="tab-interface">
+    <!-- Tab Navigation -->
+    <div class="tab-nav">
+      <button
+        v-for="(pane, index) in panes"
+        :key="pane.name"
+        @click="switchTab(index)"
+        :class="['tab-button', { active: activeTab === index }]"
+      >
+        <span class="tab-icon">{{ tabIcons[pane.name] }}</span>
+        <span class="tab-label">{{ pane.name }}</span>
+      </button>
+    </div>
+
+    <!-- Tab Content -->
+    <NavigationStack
+      ref="navigationRef"
+      task-key="tab-navigation"
+      :panes="panes"
+    />
+  </div>
+</template>
+
+<style module>
+.tab-interface {
+  height: 100vh;
+  display: flex;
+  flex-direction: column;
+}
+
+.tab-nav {
+  display: flex;
+  background: var(--background-1);
+  border-bottom: 1px solid var(--border-2);
+  padding: 0 16px;
+}
+
+.tab-button {
+  display: flex;
+  flex-direction: column;
+  align-items: center;
+  gap: 4px;
+  padding: 12px 16px;
+  background: transparent;
+  border: none;
+  color: var(--text-2);
+  cursor: pointer;
+  transition: all 0.2s ease;
+  border-bottom: 2px solid transparent;
+  min-width: 80px;
+}
+
+.tab-button:hover {
+  background: var(--background-2);
+  color: var(--text-1);
+}
+
+.tab-button.active {
+  color: var(--accent);
+  border-bottom-color: var(--accent);
+  background: var(--background-2);
+}
+
+.tab-icon {
+  font-size: 20px;
+  line-height: 1;
+}
+
+.tab-label {
+  font-size: 12px;
+  font-weight: 500;
+  text-transform: capitalize;
+}
+</style>
+```
+
+### Dynamic Content Management
+
+```vue
+<script setup lang="ts">
+import { ref } from "vue";
+import { NavigationStack } from "@umbra-ui/core";
+import DynamicView from "./DynamicView.vue";
+
+const panes = ref([
+  {
+    name: "initial",
+    background: "#ffffff",
+    foreground: "#000000",
+    component: DynamicView,
+    props: { content: "Initial Content" },
+  },
+]);
+
+const navigationRef = ref();
+const paneCounter = ref(1);
+
+const addNewPane = () => {
+  const newPane = {
+    name: `pane-${paneCounter.value}`,
+    background: `hsl(${Math.random() * 360}, 70%, 90%)`,
+    foreground: "#000000",
+    component: DynamicView,
+    props: {
+      content: `Dynamic Content ${paneCounter.value}`,
+      id: paneCounter.value,
+    },
+  };
+
+  navigationRef.value?.addPane(newPane, true);
+  paneCounter.value++;
+};
+
+const removeCurrentPane = () => {
+  if (panes.value.length > 1) {
+    const currentIndex = navigationRef.value?.currentIndex || 0;
+    navigationRef.value?.removePane(currentIndex);
+  }
+};
+
+const clearAllPanes = () => {
+  panes.value = [
+    {
+      name: "reset",
+      background: "#ffffff",
+      foreground: "#000000",
+      component: DynamicView,
+      props: { content: "Reset Content" },
+    },
+  ];
+  navigationRef.value?.updatePanes(panes.value);
+};
+</script>
+
+<template>
+  <div class="dynamic-container">
+    <!-- Controls -->
+    <div class="controls">
+      <button @click="addNewPane" class="control-btn add">Add Pane</button>
+      <button @click="removeCurrentPane" class="control-btn remove">
+        Remove Current
+      </button>
+      <button @click="clearAllPanes" class="control-btn clear">
+        Clear All
+      </button>
+    </div>
+
+    <!-- Navigation Stack -->
+    <NavigationStack
+      ref="navigationRef"
+      task-key="dynamic-navigation"
+      :panes="panes"
+    />
+  </div>
+</template>
+
+<style module>
+.dynamic-container {
+  height: 100vh;
+  display: flex;
+  flex-direction: column;
+}
+
+.controls {
+  display: flex;
+  gap: 12px;
+  padding: 16px;
+  background: var(--background-1);
+  border-bottom: 1px solid var(--border-2);
+}
+
+.control-btn {
+  padding: 8px 16px;
+  border: none;
+  border-radius: 6px;
+  font-weight: 500;
+  cursor: pointer;
+  transition: all 0.2s ease;
+}
+
+.control-btn.add {
+  background: #10b981;
+  color: white;
+}
+
+.control-btn.add:hover {
+  background: #059669;
+}
+
+.control-btn.remove {
+  background: #ef4444;
+  color: white;
+}
+
+.control-btn.remove:hover {
+  background: #dc2626;
+}
+
+.control-btn.clear {
+  background: #6b7280;
+  color: white;
+}
+
+.control-btn.clear:hover {
+  background: #4b5563;
+}
+</style>
+```
+
+## Advanced Usage
+
+### Custom Animation Configuration
+
+```vue
+<script setup lang="ts">
+import { ref } from "vue";
+import { NavigationStack, useNavigationStack } from "@umbra-ui/core";
+
+// Custom navigation with modified animation
+const customNavigation = useNavigationStack(initialPanes, "custom");
+
+// Override the navigate method with custom animation
+const customNavigate = (index: number, animated: boolean = true) => {
+  // Custom animation logic here
+  customNavigation.navigate(index, animated);
+};
+</script>
+```
+
+### Integration with Router
+
+```vue
+<script setup lang="ts">
+import { ref, watch } from "vue";
+import { useRoute, useRouter } from "vue-router";
+import { NavigationStack } from "@umbra-ui/core";
+
+const route = useRoute();
+const router = useRouter();
+const navigationRef = ref();
+
+const panes = ref([
+  // ... your panes
+]);
+
+// Sync with router
+watch(
+  () => route.params.tab,
+  (newTab) => {
+    const index = panes.value.findIndex((pane) => pane.name === newTab);
+    if (index !== -1) {
+      navigationRef.value?.navigate(index);
+    }
+  }
+);
+
+const handleNavigation = (index: number) => {
+  const pane = panes.value[index];
+  router.push(`/app/${pane.name}`);
+};
+</script>
+```
+
+## Performance Considerations
+
+- **Component Marking**: Always use `markRaw()` when passing components to prevent Vue's reactivity system from wrapping them
+- **Animation Performance**: GSAP FLIP animations are optimized for smooth 60fps performance
+- **Memory Management**: Panes are properly cleaned up when removed from the stack
+- **ResizeObserver**: Automatic container size monitoring with proper cleanup
+
+## Accessibility
+
+- **Keyboard Navigation**: Support for arrow keys and tab navigation
+- **Screen Reader Support**: Proper ARIA labels and roles
+- **Focus Management**: Focus is maintained during transitions
+- **High Contrast**: Supports high contrast mode
+
+## 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. **Animations not working**: Ensure GSAP and FLIP plugin are properly imported
+2. **Panes not displaying**: Check that components are properly marked with `markRaw()`
+3. **Navigation not responding**: Verify the `taskKey` is unique and consistent
+4. **Layout issues**: Ensure the container has a defined height
+
+### Debug Mode
+
+```vue
+<script setup lang="ts">
+import { ref, watch } from "vue";
+import { NavigationStack } from "@umbra-ui/core";
+
+const navigationRef = ref();
+
+// Watch for navigation changes
+watch(
+  () => navigationRef.value?.currentIndex,
+  (newIndex) => {
+    console.log("Current pane index:", newIndex);
+  }
+);
+</script>
+```
+
+## Migration Guide
+
+### From v1 to v2
+
+- `taskKey` prop is now required
+- Pane interface has been updated with new properties
+- Animation system has been refactored for better performance
+- Composable API has been enhanced with new methods
+
+### Breaking Changes
+
+- Removed automatic pane detection
+- Changed animation timing and easing
+- Updated CSS class structure
+- Modified event handling system