@umbra.ui/core 0.1.0

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

@@ -0,0 +1,1275 @@
+# SlideoverController
+
+A sophisticated slideover navigation component built with Vue 3 Composition API and TypeScript. The SlideoverController provides smooth, animated transitions between different views using GSAP's FLIP (First, Last, Invert, Play) animation technique, creating an intuitive slideover interface perfect for tablet and desktop applications.
+
+## Installation/Import
+
+```typescript
+import { SlideoverController, useSlideoverController } from "@umbra-ui/core";
+import type { Pane } from "@umbra-ui/core";
+```
+
+**Dependencies:**
+
+- Vue 3.x
+- gsap (for animations)
+- gsap/Flip (for FLIP animations)
+- @umbra-ui/icons (for ChevronLeftIcon)
+
+## Basic Usage
+
+```vue
+<script setup lang="ts">
+import { ref } from "vue";
+import { SlideoverController } from "@umbra-ui/core";
+import HomeView from "./HomeView.vue";
+import ProfileView from "./ProfileView.vue";
+import SettingsView from "./SettingsView.vue";
+
+// Define your slideover 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 slideoverRef = ref();
+
+// Navigate to specific pane
+const goToPane = (index: number) => {
+  slideoverRef.value?.navigate(index);
+};
+
+// Show all panes
+const showAllPanes = () => {
+  slideoverRef.value?.showAll();
+};
+
+// Hide all panes
+const hideAllPanes = () => {
+  slideoverRef.value?.hideAll();
+};
+</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="showAllPanes">Show All</button>
+      <button @click="hideAllPanes">Hide All</button>
+    </div>
+
+    <SlideoverController
+      ref="slideoverRef"
+      :panes="panes"
+      component-id="main-slideover"
+      :show-breadcrumb="true"
+    />
+  </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                                  |
+| ---------------- | ------------------------------------------- | -------- | -------------- | -------------------------------------------- |
+| `panes`          | `Pane[]`                                    | Yes      | -              | Array of panes to display in the slideover   |
+| `controller`     | `ReturnType<typeof useSlideoverController>` | No       | -              | External controller instance                 |
+| `componentId`    | `string`                                    | No       | Auto-generated | Unique identifier for the component instance |
+| `showBreadcrumb` | `boolean`                                   | No       | `true`         | Whether to show breadcrumb navigation        |
+
+## Pane Interface
+
+```typescript
+interface Pane {
+  name: string;
+  background: string;
+  foreground: string;
+  component: any;
+  props: Record<string, any>;
+}
+```
+
+### Pane Properties
+
+| Property     | Type                  | Description                                     |
+| ------------ | --------------------- | ----------------------------------------------- |
+| `name`       | `string`              | Display name for the pane (used in breadcrumbs) |
+| `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 SlideoverController 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         |
+| `showPane`   | `(index: number)`                     | Show a specific pane and all panes after it  |
+| `hidePane`   | `(index: number)`                     | Hide a specific pane and all panes before it |
+| `togglePane` | `(index: number)`                     | Toggle a pane at a specific index            |
+| `showAll`    | `()`                                  | Show all secondary panes                     |
+| `hideAll`    | `()`                                  | Hide all secondary panes                     |
+
+## useSlideoverController Composable
+
+The `useSlideoverController` composable provides the core slideover logic and can be used independently:
+
+```typescript
+import { useSlideoverController } from "@umbra-ui/core";
+
+const {
+  visiblePanes,
+  currentPaneIndex,
+  showPane,
+  hidePane,
+  togglePane,
+  showAll,
+  hideAll,
+  navigate,
+} = useSlideoverController(panes, componentId);
+```
+
+### Composable Returns
+
+| Property           | Type                                          | Description                                       |
+| ------------------ | --------------------------------------------- | ------------------------------------------------- |
+| `visiblePanes`     | `Ref<boolean[]>`                              | Reactive array indicating which panes are visible |
+| `currentPaneIndex` | `ComputedRef<number>`                         | Current active pane index                         |
+| `showPane`         | `(index: number) => void`                     | Show specific pane and all after it               |
+| `hidePane`         | `(index: number) => void`                     | Hide specific pane and all before it              |
+| `togglePane`       | `(index: number) => void`                     | Toggle pane at specific index                     |
+| `showAll`          | `() => void`                                  | Show all secondary panes                          |
+| `hideAll`          | `() => void`                                  | Hide all secondary panes                          |
+| `navigate`         | `(index: number, animated?: boolean) => void` | Navigate to specific pane                         |
+
+## CSS Customization
+
+### Layout Variables
+
+```css
+.slideover-controller {
+  --slideover-darken-bg: rgba(0, 0, 0, 0.5);
+  --slideover-breadcrumb-default-opacity: 0.6;
+  --slideover-breadcrumb-hover-opacity: 1;
+  --slideover-handle-default-width: 4px;
+  --slideover-handle-default-height: 24px;
+  --slideover-handle-default-opacity: 0.3;
+  --slideover-handle-bg: #666;
+  --slideover-handle-hover-width: 6px;
+  --slideover-handle-hover-height: 32px;
+  --slideover-handle-hover-opacity: 0.6;
+}
+```
+
+### Container Styling
+
+```css
+.slideover-controller {
+  position: relative;
+  height: 100%;
+  width: 100%;
+  overflow: hidden;
+}
+
+.slideover-controller .darken {
+  position: absolute;
+  top: 0;
+  left: 0;
+  right: 0;
+  bottom: 0;
+  background-color: var(--slideover-darken-bg);
+  opacity: 0;
+  pointer-events: none;
+  z-index: 5;
+}
+```
+
+### Pane Styling
+
+```css
+.slideover-controller .pane {
+  display: grid;
+  grid-template-columns: 1fr;
+  grid-template-areas: "content";
+  height: 100%;
+}
+
+.slideover-controller .pane_full {
+  display: flex;
+  flex-direction: column;
+  flex-grow: 1;
+  height: 100%;
+}
+```
+
+## Examples
+
+### File Explorer Interface
+
+```vue
+<script setup lang="ts">
+import { ref } from "vue";
+import { SlideoverController } from "@umbra-ui/core";
+import FileTree from "./FileTree.vue";
+import FileList from "./FileList.vue";
+import FilePreview from "./FilePreview.vue";
+
+const panes = ref([
+  {
+    name: "Folders",
+    background: "#ffffff",
+    foreground: "#1a202c",
+    component: FileTree,
+    props: { rootPath: "/" },
+  },
+  {
+    name: "Files",
+    background: "#f7fafc",
+    foreground: "#2d3748",
+    component: FileList,
+    props: { currentPath: "/documents" },
+  },
+  {
+    name: "Preview",
+    background: "#edf2f7",
+    foreground: "#4a5568",
+    component: FilePreview,
+    props: { selectedFile: null },
+  },
+]);
+
+const slideoverRef = ref();
+
+const handleFileSelect = (file: any) => {
+  // Navigate to preview pane
+  slideoverRef.value?.navigate(2);
+};
+
+const handleFolderSelect = (folder: any) => {
+  // Navigate to file list pane
+  slideoverRef.value?.navigate(1);
+};
+</script>
+
+<template>
+  <div class="file-explorer">
+    <!-- Toolbar -->
+    <div class="explorer-toolbar">
+      <div class="toolbar-section">
+        <button @click="slideoverRef?.showAll()" class="toolbar-btn">
+          Show All Panes
+        </button>
+        <button @click="slideoverRef?.hideAll()" class="toolbar-btn">
+          Hide All Panes
+        </button>
+      </div>
+
+      <div class="toolbar-section">
+        <button @click="slideoverRef?.navigate(0)" class="toolbar-btn">
+          Folders
+        </button>
+        <button @click="slideoverRef?.navigate(1)" class="toolbar-btn">
+          Files
+        </button>
+        <button @click="slideoverRef?.navigate(2)" class="toolbar-btn">
+          Preview
+        </button>
+      </div>
+    </div>
+
+    <!-- Slideover Controller -->
+    <SlideoverController
+      ref="slideoverRef"
+      :panes="panes"
+      component-id="file-explorer"
+      :show-breadcrumb="true"
+    />
+  </div>
+</template>
+
+<style module>
+.file-explorer {
+  height: 100vh;
+  display: flex;
+  flex-direction: column;
+  background: #f8f9fa;
+}
+
+.explorer-toolbar {
+  display: flex;
+  justify-content: space-between;
+  align-items: center;
+  padding: 12px 16px;
+  background: white;
+  border-bottom: 1px solid #e9ecef;
+  box-shadow: 0 1px 3px rgba(0, 0, 0, 0.1);
+}
+
+.toolbar-section {
+  display: flex;
+  gap: 8px;
+}
+
+.toolbar-btn {
+  padding: 6px 12px;
+  border: 1px solid #dee2e6;
+  background: white;
+  color: #495057;
+  border-radius: 4px;
+  cursor: pointer;
+  font-size: 14px;
+  transition: all 0.2s ease;
+}
+
+.toolbar-btn:hover {
+  background: #f8f9fa;
+  border-color: #adb5bd;
+}
+
+.toolbar-btn:active {
+  background: #e9ecef;
+}
+</style>
+```
+
+### Settings Panel Interface
+
+```vue
+<script setup lang="ts">
+import { ref } from "vue";
+import { SlideoverController } 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 panes = ref([
+  {
+    name: "General",
+    background: "#ffffff",
+    foreground: "#1a202c",
+    component: GeneralSettings,
+    props: { section: "general" },
+  },
+  {
+    name: "Appearance",
+    background: "#f7fafc",
+    foreground: "#2d3748",
+    component: AppearanceSettings,
+    props: { section: "appearance" },
+  },
+  {
+    name: "Privacy",
+    background: "#edf2f7",
+    foreground: "#4a5568",
+    component: PrivacySettings,
+    props: { section: "privacy" },
+  },
+  {
+    name: "Advanced",
+    background: "#e2e8f0",
+    foreground: "#718096",
+    component: AdvancedSettings,
+    props: { section: "advanced" },
+  },
+]);
+
+const slideoverRef = ref();
+const currentSection = ref("General");
+
+const navigateToSection = (index: number) => {
+  currentSection.value = panes.value[index].name;
+  slideoverRef.value?.navigate(index);
+};
+
+const resetToGeneral = () => {
+  slideoverRef.value?.navigate(0);
+  currentSection.value = "General";
+};
+</script>
+
+<template>
+  <div class="settings-interface">
+    <!-- Settings Header -->
+    <header class="settings-header">
+      <h1 class="settings-title">Settings</h1>
+      <p class="settings-subtitle">Configure your application preferences</p>
+    </header>
+
+    <!-- Settings Navigation -->
+    <nav class="settings-nav">
+      <button
+        v-for="(pane, index) in panes"
+        :key="pane.name"
+        @click="navigateToSection(index)"
+        :class="['nav-item', { active: currentSection === pane.name }]"
+      >
+        <span class="nav-icon">{{ getSectionIcon(pane.name) }}</span>
+        <span class="nav-label">{{ pane.name }}</span>
+      </button>
+
+      <div class="nav-actions">
+        <button @click="resetToGeneral" class="action-btn secondary">
+          Reset
+        </button>
+        <button @click="slideoverRef?.showAll()" class="action-btn primary">
+          Show All
+        </button>
+      </div>
+    </nav>
+
+    <!-- Settings Content -->
+    <SlideoverController
+      ref="slideoverRef"
+      :panes="panes"
+      component-id="settings-panel"
+      :show-breadcrumb="true"
+    />
+  </div>
+</template>
+
+<script setup lang="ts">
+const getSectionIcon = (section: string) => {
+  const icons = {
+    General: "⚙️",
+    Appearance: "🎨",
+    Privacy: "🔒",
+    Advanced: "🔧",
+  };
+  return icons[section] || "📋";
+};
+</script>
+
+<style module>
+.settings-interface {
+  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-nav {
+  display: flex;
+  align-items: center;
+  gap: 16px;
+  padding: 16px 24px;
+  background: white;
+  border-bottom: 1px solid #e9ecef;
+  box-shadow: 0 1px 3px rgba(0, 0, 0, 0.1);
+}
+
+.nav-item {
+  display: flex;
+  align-items: center;
+  gap: 8px;
+  padding: 8px 16px;
+  background: transparent;
+  border: 1px solid transparent;
+  color: #718096;
+  cursor: pointer;
+  border-radius: 6px;
+  transition: all 0.2s ease;
+  font-weight: 500;
+}
+
+.nav-item:hover {
+  background: #f7fafc;
+  color: #4a5568;
+}
+
+.nav-item.active {
+  background: #edf2f7;
+  color: #2d3748;
+  border-color: #cbd5e0;
+}
+
+.nav-icon {
+  font-size: 16px;
+}
+
+.nav-label {
+  font-size: 14px;
+}
+
+.nav-actions {
+  margin-left: auto;
+  display: flex;
+  gap: 8px;
+}
+
+.action-btn {
+  padding: 8px 16px;
+  border: 1px solid;
+  border-radius: 6px;
+  cursor: pointer;
+  font-weight: 500;
+  transition: all 0.2s ease;
+}
+
+.action-btn.primary {
+  background: #3182ce;
+  color: white;
+  border-color: #3182ce;
+}
+
+.action-btn.primary:hover {
+  background: #2c5aa0;
+  border-color: #2c5aa0;
+}
+
+.action-btn.secondary {
+  background: white;
+  color: #718096;
+  border-color: #e2e8f0;
+}
+
+.action-btn.secondary:hover {
+  background: #f7fafc;
+  color: #4a5568;
+  border-color: #cbd5e0;
+}
+</style>
+```
+
+### Multi-Step Form Interface
+
+```vue
+<script setup lang="ts">
+import { ref } from "vue";
+import { SlideoverController } from "@umbra-ui/core";
+import PersonalInfoStep from "./PersonalInfoStep.vue";
+import ContactInfoStep from "./ContactInfoStep.vue";
+import PreferencesStep from "./PreferencesStep.vue";
+import ReviewStep from "./ReviewStep.vue";
+
+const panes = ref([
+  {
+    name: "Personal Info",
+    background: "linear-gradient(135deg, #667eea 0%, #764ba2 100%)",
+    foreground: "#ffffff",
+    component: PersonalInfoStep,
+    props: { step: 1 },
+  },
+  {
+    name: "Contact Info",
+    background: "linear-gradient(135deg, #f093fb 0%, #f5576c 100%)",
+    foreground: "#ffffff",
+    component: ContactInfoStep,
+    props: { step: 2 },
+  },
+  {
+    name: "Preferences",
+    background: "linear-gradient(135deg, #4facfe 0%, #00f2fe 100%)",
+    foreground: "#ffffff",
+    component: PreferencesStep,
+    props: { step: 3 },
+  },
+  {
+    name: "Review",
+    background: "linear-gradient(135deg, #43e97b 0%, #38f9d7 100%)",
+    foreground: "#ffffff",
+    component: ReviewStep,
+    props: { step: 4 },
+  },
+]);
+
+const slideoverRef = ref();
+const currentStep = ref(0);
+const totalSteps = panes.value.length;
+const formData = ref({});
+
+const nextStep = () => {
+  if (currentStep.value < totalSteps - 1) {
+    currentStep.value++;
+    slideoverRef.value?.navigate(currentStep.value);
+  }
+};
+
+const prevStep = () => {
+  if (currentStep.value > 0) {
+    currentStep.value--;
+    slideoverRef.value?.navigate(currentStep.value);
+  }
+};
+
+const completeForm = () => {
+  console.log("Form completed:", formData.value);
+  // Handle form submission
+};
+
+const updateFormData = (stepData: any) => {
+  formData.value = { ...formData.value, ...stepData };
+};
+</script>
+
+<template>
+  <div class="multi-step-form">
+    <!-- Progress Header -->
+    <div class="form-header">
+      <div class="progress-container">
+        <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>
+
+      <h1 class="form-title">Complete Your Profile</h1>
+    </div>
+
+    <!-- Form Navigation -->
+    <div class="form-navigation">
+      <button
+        @click="prevStep"
+        :disabled="currentStep === 0"
+        class="nav-button prev"
+      >
+        ← Previous
+      </button>
+
+      <div class="step-indicators">
+        <button
+          v-for="(pane, index) in panes"
+          :key="pane.name"
+          @click="slideoverRef?.navigate(index)"
+          :class="[
+            'step-indicator',
+            {
+              active: currentStep === index,
+              completed: currentStep > index,
+            },
+          ]"
+        >
+          {{ index + 1 }}
+        </button>
+      </div>
+
+      <button
+        v-if="currentStep < totalSteps - 1"
+        @click="nextStep"
+        class="nav-button next"
+      >
+        Next →
+      </button>
+
+      <button v-else @click="completeForm" class="nav-button complete">
+        Complete
+      </button>
+    </div>
+
+    <!-- Form Content -->
+    <SlideoverController
+      ref="slideoverRef"
+      :panes="panes"
+      component-id="multi-step-form"
+      :show-breadcrumb="false"
+    />
+  </div>
+</template>
+
+<style module>
+.multi-step-form {
+  height: 100vh;
+  display: flex;
+  flex-direction: column;
+  background: #f8f9fa;
+}
+
+.form-header {
+  padding: 24px;
+  background: white;
+  border-bottom: 1px solid #e9ecef;
+}
+
+.progress-container {
+  display: flex;
+  align-items: center;
+  gap: 16px;
+  margin-bottom: 16px;
+}
+
+.progress-bar {
+  flex: 1;
+  height: 6px;
+  background: #e9ecef;
+  border-radius: 3px;
+  overflow: hidden;
+}
+
+.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;
+  white-space: nowrap;
+}
+
+.form-title {
+  font-size: 24px;
+  font-weight: 700;
+  color: #1a202c;
+  margin: 0;
+}
+
+.form-navigation {
+  display: flex;
+  align-items: center;
+  justify-content: space-between;
+  padding: 16px 24px;
+  background: white;
+  border-bottom: 1px solid #e9ecef;
+}
+
+.nav-button {
+  padding: 10px 20px;
+  border: none;
+  border-radius: 8px;
+  font-weight: 600;
+  cursor: pointer;
+  transition: all 0.2s ease;
+  min-width: 100px;
+}
+
+.nav-button.prev {
+  background: #f8f9fa;
+  color: #6c757d;
+  border: 1px solid #dee2e6;
+}
+
+.nav-button.prev:hover:not(:disabled) {
+  background: #e9ecef;
+  border-color: #adb5bd;
+}
+
+.nav-button.next {
+  background: linear-gradient(135deg, #667eea 0%, #764ba2 100%);
+  color: white;
+}
+
+.nav-button.next:hover {
+  transform: translateY(-1px);
+  box-shadow: 0 4px 12px rgba(102, 126, 234, 0.4);
+}
+
+.nav-button.complete {
+  background: linear-gradient(135deg, #43e97b 0%, #38f9d7 100%);
+  color: white;
+}
+
+.nav-button.complete:hover {
+  transform: translateY(-1px);
+  box-shadow: 0 4px 12px rgba(67, 233, 123, 0.4);
+}
+
+.nav-button:disabled {
+  opacity: 0.5;
+  cursor: not-allowed;
+}
+
+.step-indicators {
+  display: flex;
+  gap: 8px;
+}
+
+.step-indicator {
+  width: 32px;
+  height: 32px;
+  border: 2px solid #e9ecef;
+  background: white;
+  color: #6c757d;
+  border-radius: 50%;
+  cursor: pointer;
+  font-weight: 600;
+  transition: all 0.2s ease;
+}
+
+.step-indicator:hover {
+  border-color: #adb5bd;
+  color: #495057;
+}
+
+.step-indicator.active {
+  background: linear-gradient(135deg, #667eea 0%, #764ba2 100%);
+  border-color: #667eea;
+  color: white;
+}
+
+.step-indicator.completed {
+  background: #28a745;
+  border-color: #28a745;
+  color: white;
+}
+</style>
+```
+
+### Dashboard with Sidebar
+
+```vue
+<script setup lang="ts">
+import { ref } from "vue";
+import { SlideoverController } from "@umbra-ui/core";
+import DashboardMain from "./DashboardMain.vue";
+import AnalyticsPanel from "./AnalyticsPanel.vue";
+import NotificationsPanel from "./NotificationsPanel.vue";
+import UserProfilePanel from "./UserProfilePanel.vue";
+
+const panes = ref([
+  {
+    name: "Dashboard",
+    background: "#ffffff",
+    foreground: "#1a202c",
+    component: DashboardMain,
+    props: { title: "Main Dashboard" },
+  },
+  {
+    name: "Analytics",
+    background: "#f7fafc",
+    foreground: "#2d3748",
+    component: AnalyticsPanel,
+    props: { period: "30d" },
+  },
+  {
+    name: "Notifications",
+    background: "#edf2f7",
+    foreground: "#4a5568",
+    component: NotificationsPanel,
+    props: { unread: 5 },
+  },
+  {
+    name: "Profile",
+    background: "#e2e8f0",
+    foreground: "#718096",
+    component: UserProfilePanel,
+    props: { userId: "current" },
+  },
+]);
+
+const slideoverRef = ref();
+const sidebarOpen = ref(false);
+
+const toggleSidebar = () => {
+  sidebarOpen.value = !sidebarOpen.value;
+  if (sidebarOpen.value) {
+    slideoverRef.value?.showAll();
+  } else {
+    slideoverRef.value?.hideAll();
+  }
+};
+
+const navigateToPanel = (index: number) => {
+  slideoverRef.value?.navigate(index);
+  sidebarOpen.value = true;
+};
+</script>
+
+<template>
+  <div class="dashboard-layout">
+    <!-- Top Navigation -->
+    <header class="dashboard-header">
+      <div class="header-left">
+        <button @click="toggleSidebar" class="menu-toggle">
+          <span class="hamburger"></span>
+          <span class="hamburger"></span>
+          <span class="hamburger"></span>
+        </button>
+        <h1 class="dashboard-title">Dashboard</h1>
+      </div>
+
+      <div class="header-right">
+        <button @click="navigateToPanel(2)" class="notification-btn">
+          🔔
+          <span class="notification-badge">5</span>
+        </button>
+        <button @click="navigateToPanel(3)" class="profile-btn">👤</button>
+      </div>
+    </header>
+
+    <!-- Quick Actions -->
+    <div class="quick-actions">
+      <button @click="navigateToPanel(0)" class="action-card">
+        <span class="action-icon">📊</span>
+        <span class="action-label">Dashboard</span>
+      </button>
+      <button @click="navigateToPanel(1)" class="action-card">
+        <span class="action-icon">📈</span>
+        <span class="action-label">Analytics</span>
+      </button>
+      <button @click="navigateToPanel(2)" class="action-card">
+        <span class="action-icon">🔔</span>
+        <span class="action-label">Notifications</span>
+      </button>
+      <button @click="navigateToPanel(3)" class="action-card">
+        <span class="action-icon">👤</span>
+        <span class="action-label">Profile</span>
+      </button>
+    </div>
+
+    <!-- Main Content -->
+    <SlideoverController
+      ref="slideoverRef"
+      :panes="panes"
+      component-id="dashboard-slideover"
+      :show-breadcrumb="true"
+    />
+  </div>
+</template>
+
+<style module>
+.dashboard-layout {
+  height: 100vh;
+  display: flex;
+  flex-direction: column;
+  background: #f8f9fa;
+}
+
+.dashboard-header {
+  display: flex;
+  justify-content: space-between;
+  align-items: center;
+  padding: 16px 24px;
+  background: white;
+  border-bottom: 1px solid #e9ecef;
+  box-shadow: 0 1px 3px rgba(0, 0, 0, 0.1);
+}
+
+.header-left {
+  display: flex;
+  align-items: center;
+  gap: 16px;
+}
+
+.menu-toggle {
+  display: flex;
+  flex-direction: column;
+  gap: 3px;
+  background: none;
+  border: none;
+  cursor: pointer;
+  padding: 8px;
+  border-radius: 4px;
+  transition: background 0.2s ease;
+}
+
+.menu-toggle:hover {
+  background: #f8f9fa;
+}
+
+.hamburger {
+  width: 18px;
+  height: 2px;
+  background: #495057;
+  border-radius: 1px;
+  transition: all 0.2s ease;
+}
+
+.dashboard-title {
+  font-size: 24px;
+  font-weight: 700;
+  color: #1a202c;
+  margin: 0;
+}
+
+.header-right {
+  display: flex;
+  align-items: center;
+  gap: 12px;
+}
+
+.notification-btn,
+.profile-btn {
+  position: relative;
+  width: 40px;
+  height: 40px;
+  border: none;
+  background: #f8f9fa;
+  border-radius: 50%;
+  cursor: pointer;
+  font-size: 18px;
+  transition: all 0.2s ease;
+}
+
+.notification-btn:hover,
+.profile-btn:hover {
+  background: #e9ecef;
+  transform: scale(1.05);
+}
+
+.notification-badge {
+  position: absolute;
+  top: -2px;
+  right: -2px;
+  width: 18px;
+  height: 18px;
+  background: #dc3545;
+  color: white;
+  border-radius: 50%;
+  font-size: 10px;
+  font-weight: 600;
+  display: flex;
+  align-items: center;
+  justify-content: center;
+}
+
+.quick-actions {
+  display: flex;
+  gap: 16px;
+  padding: 20px 24px;
+  background: white;
+  border-bottom: 1px solid #e9ecef;
+}
+
+.action-card {
+  display: flex;
+  flex-direction: column;
+  align-items: center;
+  gap: 8px;
+  padding: 16px;
+  background: #f8f9fa;
+  border: 1px solid #e9ecef;
+  border-radius: 8px;
+  cursor: pointer;
+  transition: all 0.2s ease;
+  min-width: 80px;
+}
+
+.action-card:hover {
+  background: #e9ecef;
+  border-color: #adb5bd;
+  transform: translateY(-2px);
+  box-shadow: 0 4px 8px rgba(0, 0, 0, 0.1);
+}
+
+.action-icon {
+  font-size: 24px;
+}
+
+.action-label {
+  font-size: 12px;
+  font-weight: 500;
+  color: #495057;
+}
+</style>
+```
+
+## Advanced Usage
+
+### Custom Controller Integration
+
+```vue
+<script setup lang="ts">
+import { ref } from "vue";
+import { SlideoverController, useSlideoverController } from "@umbra-ui/core";
+
+const panes = ref([
+  // ... your panes
+]);
+
+// Create custom controller
+const customController = useSlideoverController(
+  panes.value,
+  "custom-slideover"
+);
+
+// Override methods with custom logic
+const customNavigate = (index: number, animated: boolean = true) => {
+  console.log(`Navigating to pane ${index}`);
+  customController.navigate(index, animated);
+};
+
+const customShowAll = () => {
+  console.log("Showing all panes");
+  customController.showAll();
+};
+</script>
+
+<template>
+  <SlideoverController
+    :panes="panes"
+    :controller="customController"
+    component-id="custom-slideover"
+  />
+</template>
+```
+
+### Integration with Router
+
+```vue
+<script setup lang="ts">
+import { ref, watch } from "vue";
+import { useRoute, useRouter } from "vue-router";
+import { SlideoverController } from "@umbra-ui/core";
+
+const route = useRoute();
+const router = useRouter();
+const slideoverRef = ref();
+
+const panes = ref([
+  // ... your panes
+]);
+
+// Sync with router
+watch(
+  () => route.params.panel,
+  (newPanel) => {
+    const index = panes.value.findIndex((pane) => pane.name === newPanel);
+    if (index !== -1) {
+      slideoverRef.value?.navigate(index);
+    }
+  }
+);
+
+const handleNavigation = (index: number) => {
+  const pane = panes.value[index];
+  router.push(`/dashboard/${pane.name.toLowerCase()}`);
+};
+</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 controller
+- **DOM Manipulation**: Efficient DOM manipulation using GSAP for optimal performance
+
+## 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 `componentId` 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 { SlideoverController } from "@umbra-ui/core";
+
+const slideoverRef = ref();
+
+// Watch for navigation changes
+watch(
+  () => slideoverRef.value?.currentPaneIndex,
+  (newIndex) => {
+    console.log("Current pane index:", newIndex);
+  }
+);
+</script>
+```
+
+## Migration Guide
+
+### From v1 to v2
+
+- `componentId` prop is now optional with auto-generation
+- 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