@umbra.ui/core 0.1.0

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

@@ -0,0 +1,1115 @@
+# SplitViewController
+
+A powerful split-view navigation component built with Vue 3 Composition API and TypeScript. The SplitViewController provides smooth, animated transitions between different views using GSAP's FLIP (First, Last, Invert, Play) animation technique, creating an intuitive side-by-side interface perfect for desktop applications and complex layouts.
+
+## Installation/Import
+
+```typescript
+import { SplitViewController, useSplitViewController } 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 { SplitViewController } from "@umbra-ui/core";
+import SidebarView from "./SidebarView.vue";
+import ContentView from "./ContentView.vue";
+import DetailsView from "./DetailsView.vue";
+
+// Define your split-view panes
+const panes = ref([
+  {
+    name: "Sidebar",
+    background: "#ffffff",
+    foreground: "#000000",
+    component: SidebarView,
+    props: { title: "Navigation" },
+  },
+  {
+    name: "Content",
+    background: "#f8f9fa",
+    foreground: "#212529",
+    component: ContentView,
+    props: { section: "main" },
+  },
+  {
+    name: "Details",
+    background: "#e9ecef",
+    foreground: "#495057",
+    component: DetailsView,
+    props: { item: null },
+  },
+]);
+
+const splitviewRef = ref();
+
+// Navigate to specific pane
+const goToPane = (index: number) => {
+  splitviewRef.value?.navigate(index);
+};
+
+// Show all panes
+const showAllPanes = () => {
+  splitviewRef.value?.showAll();
+};
+
+// Hide all panes except the last one
+const hideAllPanes = () => {
+  splitviewRef.value?.hideAll();
+};
+
+// Toggle specific pane
+const togglePane = (index: number) => {
+  splitviewRef.value?.togglePane(index);
+};
+</script>
+
+<template>
+  <div class="app">
+    <div class="navigation-controls">
+      <button @click="goToPane(0)">Sidebar</button>
+      <button @click="goToPane(1)">Content</button>
+      <button @click="goToPane(2)">Details</button>
+      <button @click="showAllPanes">Show All</button>
+      <button @click="hideAllPanes">Hide All</button>
+    </div>
+
+    <SplitViewController
+      ref="splitviewRef"
+      :panes="panes"
+      component-id="main-splitview"
+    />
+  </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 split-view  |
+| `controller`  | `ReturnType<typeof useSplitViewController>` | No       | -              | External controller instance                 |
+| `componentId` | `string`                                    | No       | Auto-generated | Unique identifier for the component instance |
+
+## 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               |
+| `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 SplitViewController 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 show only a specific pane |
+| `showPane`   | `(index: number)`                     | Show a specific pane                  |
+| `hidePane`   | `(index: number)`                     | Hide a specific pane                  |
+| `togglePane` | `(index: number)`                     | Toggle a pane at a specific index     |
+| `showAll`    | `()`                                  | Show all panes                        |
+| `hideAll`    | `()`                                  | Hide all panes except the last one    |
+
+## useSplitViewController Composable
+
+The `useSplitViewController` composable provides the core split-view logic and can be used independently:
+
+```typescript
+import { useSplitViewController } from "@umbra-ui/core";
+
+const {
+  visiblePanes,
+  currentPaneIndex,
+  lastVisibilityEvent,
+  showPane,
+  hidePane,
+  togglePane,
+  showAll,
+  hideAll,
+  navigate,
+} = useSplitViewController(panes, componentId);
+```
+
+### Composable Returns
+
+| Property              | Type                                                   | Description                                       |
+| --------------------- | ------------------------------------------------------ | ------------------------------------------------- |
+| `visiblePanes`        | `Ref<boolean[]>`                                       | Reactive array indicating which panes are visible |
+| `currentPaneIndex`    | `ComputedRef<number>`                                  | Current active pane index                         |
+| `lastVisibilityEvent` | `Ref<{type: "show" \| "hide", index: number} \| null>` | Last visibility change event                      |
+| `showPane`            | `(index: number) => void`                              | Show specific pane                                |
+| `hidePane`            | `(index: number) => void`                              | Hide specific pane                                |
+| `togglePane`          | `(index: number) => void`                              | Toggle pane at specific index                     |
+| `showAll`             | `() => void`                                           | Show all panes                                    |
+| `hideAll`             | `() => void`                                           | Hide all panes except the last one                |
+| `navigate`            | `(index: number, animated?: boolean) => void`          | Navigate to specific pane                         |
+
+## CSS Customization
+
+### Layout Variables
+
+```css
+.splitview-controller {
+  --splitview-handle-default-width: 4px;
+  --splitview-handle-default-height: 24px;
+  --splitview-handle-default-opacity: 0.3;
+  --splitview-handle-bg: #666;
+  --splitview-handle-hover-width: 6px;
+  --splitview-handle-hover-height: 32px;
+  --splitview-handle-hover-opacity: 0.6;
+}
+```
+
+### Container Styling
+
+```css
+.splitview-controller {
+  position: relative;
+  display: grid;
+  grid-template-areas: "content";
+  height: 100%;
+  width: 100%;
+  overflow: hidden;
+}
+
+.splitview-controller .onscreen {
+  grid-area: content;
+  display: flex;
+  height: 100%;
+}
+```
+
+### Pane Styling
+
+```css
+.splitview-controller .pane {
+  display: grid;
+  grid-template-columns: 1fr;
+  grid-template-areas: "content";
+  height: 100%;
+  flex: 0 0 auto;
+}
+
+.splitview-controller .pane_full {
+  flex: 1 1 auto;
+  min-width: 0;
+}
+```
+
+## Examples
+
+### File Manager Interface
+
+```vue
+<script setup lang="ts">
+import { ref } from "vue";
+import { SplitViewController } from "@umbra-ui/core";
+import FileTree from "./FileTree.vue";
+import FileList from "./FileList.vue";
+import FilePreview from "./FilePreview.vue";
+
+const panes = ref([
+  {
+    name: "Tree",
+    background: "#ffffff",
+    foreground: "#1a202c",
+    component: FileTree,
+    props: { rootPath: "/" },
+  },
+  {
+    name: "List",
+    background: "#f7fafc",
+    foreground: "#2d3748",
+    component: FileList,
+    props: { currentPath: "/documents" },
+  },
+  {
+    name: "Preview",
+    background: "#edf2f7",
+    foreground: "#4a5568",
+    component: FilePreview,
+    props: { selectedFile: null },
+  },
+]);
+
+const splitviewRef = ref();
+
+const handleFileSelect = (file: any) => {
+  // Navigate to preview pane
+  splitviewRef.value?.navigate(2);
+};
+
+const handleFolderSelect = (folder: any) => {
+  // Navigate to file list pane
+  splitviewRef.value?.navigate(1);
+};
+
+const toggleTree = () => {
+  splitviewRef.value?.togglePane(0);
+};
+
+const toggleList = () => {
+  splitviewRef.value?.togglePane(1);
+};
+</script>
+
+<template>
+  <div class="file-manager">
+    <!-- Toolbar -->
+    <div class="file-toolbar">
+      <div class="toolbar-section">
+        <button @click="splitviewRef?.showAll()" class="toolbar-btn">
+          Show All Panes
+        </button>
+        <button @click="splitviewRef?.hideAll()" class="toolbar-btn">
+          Hide All Panes
+        </button>
+      </div>
+
+      <div class="toolbar-section">
+        <button @click="toggleTree" class="toolbar-btn">Toggle Tree</button>
+        <button @click="toggleList" class="toolbar-btn">Toggle List</button>
+        <button @click="splitviewRef?.navigate(2)" class="toolbar-btn">
+          Preview Only
+        </button>
+      </div>
+    </div>
+
+    <!-- Split View Controller -->
+    <SplitViewController
+      ref="splitviewRef"
+      :panes="panes"
+      component-id="file-manager"
+    />
+  </div>
+</template>
+
+<style module>
+.file-manager {
+  height: 100vh;
+  display: flex;
+  flex-direction: column;
+  background: #f8f9fa;
+}
+
+.file-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;
+}
+</style>
+```
+
+### Code Editor Interface
+
+```vue
+<script setup lang="ts">
+import { ref } from "vue";
+import { SplitViewController } from "@umbra-ui/core";
+import FileExplorer from "./FileExplorer.vue";
+import CodeEditor from "./CodeEditor.vue";
+import Terminal from "./Terminal.vue";
+
+const panes = ref([
+  {
+    name: "Explorer",
+    background: "#1e1e1e",
+    foreground: "#cccccc",
+    component: FileExplorer,
+    props: { theme: "dark" },
+  },
+  {
+    name: "Editor",
+    background: "#2d2d30",
+    foreground: "#cccccc",
+    component: CodeEditor,
+    props: { language: "typescript" },
+  },
+  {
+    name: "Terminal",
+    background: "#0c0c0c",
+    foreground: "#00ff00",
+    component: Terminal,
+    props: { shell: "bash" },
+  },
+]);
+
+const splitviewRef = ref();
+const currentFile = ref(null);
+
+const openFile = (file: any) => {
+  currentFile.value = file;
+  // Ensure editor is visible
+  splitviewRef.value?.navigate(1);
+};
+
+const toggleExplorer = () => {
+  splitviewRef.value?.togglePane(0);
+};
+
+const toggleTerminal = () => {
+  splitviewRef.value?.togglePane(2);
+};
+
+const focusEditor = () => {
+  splitviewRef.value?.navigate(1);
+};
+
+const showAllPanels = () => {
+  splitviewRef.value?.showAll();
+};
+</script>
+
+<template>
+  <div class="code-editor">
+    <!-- Editor Header -->
+    <header class="editor-header">
+      <div class="header-left">
+        <button @click="toggleExplorer" class="header-btn">📁 Explorer</button>
+        <button @click="focusEditor" class="header-btn">✏️ Editor</button>
+        <button @click="toggleTerminal" class="header-btn">💻 Terminal</button>
+      </div>
+
+      <div class="header-right">
+        <button @click="showAllPanels" class="header-btn">Show All</button>
+        <span v-if="currentFile" class="current-file">
+          {{ currentFile.name }}
+        </span>
+      </div>
+    </header>
+
+    <!-- Split View Controller -->
+    <SplitViewController
+      ref="splitviewRef"
+      :panes="panes"
+      component-id="code-editor"
+    />
+  </div>
+</template>
+
+<style module>
+.code-editor {
+  height: 100vh;
+  display: flex;
+  flex-direction: column;
+  background: #1e1e1e;
+  color: #cccccc;
+}
+
+.editor-header {
+  display: flex;
+  justify-content: space-between;
+  align-items: center;
+  padding: 8px 16px;
+  background: #2d2d30;
+  border-bottom: 1px solid #3e3e42;
+}
+
+.header-left {
+  display: flex;
+  gap: 8px;
+}
+
+.header-right {
+  display: flex;
+  align-items: center;
+  gap: 12px;
+}
+
+.header-btn {
+  padding: 6px 12px;
+  background: transparent;
+  border: 1px solid #3e3e42;
+  color: #cccccc;
+  border-radius: 4px;
+  cursor: pointer;
+  font-size: 14px;
+  transition: all 0.2s ease;
+}
+
+.header-btn:hover {
+  background: #3e3e42;
+  border-color: #007acc;
+}
+
+.current-file {
+  font-size: 14px;
+  color: #007acc;
+  font-weight: 500;
+}
+</style>
+```
+
+### Dashboard Layout
+
+```vue
+<script setup lang="ts">
+import { ref } from "vue";
+import { SplitViewController } from "@umbra-ui/core";
+import Sidebar from "./Sidebar.vue";
+import MainContent from "./MainContent.vue";
+import RightPanel from "./RightPanel.vue";
+
+const panes = ref([
+  {
+    name: "Sidebar",
+    background: "#f8f9fa",
+    foreground: "#495057",
+    component: Sidebar,
+    props: { collapsed: false },
+  },
+  {
+    name: "Content",
+    background: "#ffffff",
+    foreground: "#212529",
+    component: MainContent,
+    props: { section: "dashboard" },
+  },
+  {
+    name: "Panel",
+    background: "#e9ecef",
+    foreground: "#495057",
+    component: RightPanel,
+    props: { type: "info" },
+  },
+]);
+
+const splitviewRef = ref();
+const sidebarCollapsed = ref(false);
+
+const toggleSidebar = () => {
+  sidebarCollapsed.value = !sidebarCollapsed.value;
+  if (sidebarCollapsed.value) {
+    splitviewRef.value?.hidePane(0);
+  } else {
+    splitviewRef.value?.showPane(0);
+  }
+};
+
+const toggleRightPanel = () => {
+  splitviewRef.value?.togglePane(2);
+};
+
+const showAllPanels = () => {
+  splitviewRef.value?.showAll();
+};
+
+const focusContent = () => {
+  splitviewRef.value?.navigate(1);
+};
+</script>
+
+<template>
+  <div class="dashboard-layout">
+    <!-- Top Navigation -->
+    <nav class="top-nav">
+      <div class="nav-left">
+        <button @click="toggleSidebar" class="nav-btn">
+          {{ sidebarCollapsed ? "☰" : "✕" }}
+        </button>
+        <h1 class="nav-title">Dashboard</h1>
+      </div>
+
+      <div class="nav-center">
+        <button @click="focusContent" class="nav-btn">Home</button>
+        <button @click="splitviewRef?.navigate(1)" class="nav-btn">
+          Analytics
+        </button>
+        <button @click="splitviewRef?.navigate(1)" class="nav-btn">
+          Reports
+        </button>
+      </div>
+
+      <div class="nav-right">
+        <button @click="toggleRightPanel" class="nav-btn">Panel</button>
+        <button @click="showAllPanels" class="nav-btn">Show All</button>
+      </div>
+    </nav>
+
+    <!-- Split View Controller -->
+    <SplitViewController
+      ref="splitviewRef"
+      :panes="panes"
+      component-id="dashboard-splitview"
+    />
+  </div>
+</template>
+
+<style module>
+.dashboard-layout {
+  height: 100vh;
+  display: flex;
+  flex-direction: column;
+  background: #f8f9fa;
+}
+
+.top-nav {
+  display: flex;
+  justify-content: space-between;
+  align-items: center;
+  padding: 12px 20px;
+  background: white;
+  border-bottom: 1px solid #dee2e6;
+  box-shadow: 0 2px 4px rgba(0, 0, 0, 0.1);
+}
+
+.nav-left {
+  display: flex;
+  align-items: center;
+  gap: 16px;
+}
+
+.nav-center {
+  display: flex;
+  gap: 8px;
+}
+
+.nav-right {
+  display: flex;
+  gap: 8px;
+}
+
+.nav-btn {
+  padding: 8px 16px;
+  background: transparent;
+  border: 1px solid #dee2e6;
+  color: #495057;
+  border-radius: 6px;
+  cursor: pointer;
+  font-size: 14px;
+  transition: all 0.2s ease;
+}
+
+.nav-btn:hover {
+  background: #f8f9fa;
+  border-color: #adb5bd;
+}
+
+.nav-title {
+  font-size: 20px;
+  font-weight: 600;
+  color: #212529;
+  margin: 0;
+}
+</style>
+```
+
+### Settings Interface
+
+```vue
+<script setup lang="ts">
+import { ref } from "vue";
+import { SplitViewController } from "@umbra-ui/core";
+import SettingsNav from "./SettingsNav.vue";
+import SettingsContent from "./SettingsContent.vue";
+import SettingsPreview from "./SettingsPreview.vue";
+
+const panes = ref([
+  {
+    name: "Navigation",
+    background: "#ffffff",
+    foreground: "#1a202c",
+    component: SettingsNav,
+    props: { currentSection: "general" },
+  },
+  {
+    name: "Content",
+    background: "#f7fafc",
+    foreground: "#2d3748",
+    component: SettingsContent,
+    props: { section: "general" },
+  },
+  {
+    name: "Preview",
+    background: "#edf2f7",
+    foreground: "#4a5568",
+    component: SettingsPreview,
+    props: { theme: "light" },
+  },
+]);
+
+const splitviewRef = ref();
+const currentSection = ref("general");
+
+const navigateToSection = (section: string) => {
+  currentSection.value = section;
+  // Update props for content pane
+  panes.value[1].props.section = section;
+  panes.value[0].props.currentSection = section;
+
+  // Ensure content is visible
+  splitviewRef.value?.navigate(1);
+};
+
+const togglePreview = () => {
+  splitviewRef.value?.togglePane(2);
+};
+
+const showAllSections = () => {
+  splitviewRef.value?.showAll();
+};
+
+const hideNavigation = () => {
+  splitviewRef.value?.hidePane(0);
+};
+</script>
+
+<template>
+  <div class="settings-interface">
+    <!-- Settings Header -->
+    <header class="settings-header">
+      <h1 class="settings-title">Settings</h1>
+      <div class="settings-actions">
+        <button @click="showAllSections" class="action-btn">Show All</button>
+        <button @click="hideNavigation" class="action-btn">Hide Nav</button>
+        <button @click="togglePreview" class="action-btn">
+          Toggle Preview
+        </button>
+      </div>
+    </header>
+
+    <!-- Quick Navigation -->
+    <div class="quick-nav">
+      <button
+        v-for="section in ['general', 'appearance', 'privacy', 'advanced']"
+        :key="section"
+        @click="navigateToSection(section)"
+        :class="['quick-nav-btn', { active: currentSection === section }]"
+      >
+        {{ section.charAt(0).toUpperCase() + section.slice(1) }}
+      </button>
+    </div>
+
+    <!-- Split View Controller -->
+    <SplitViewController
+      ref="splitviewRef"
+      :panes="panes"
+      component-id="settings-splitview"
+    />
+  </div>
+</template>
+
+<style module>
+.settings-interface {
+  height: 100vh;
+  display: flex;
+  flex-direction: column;
+  background: #f8f9fa;
+}
+
+.settings-header {
+  display: flex;
+  justify-content: space-between;
+  align-items: center;
+  padding: 20px 24px;
+  background: white;
+  border-bottom: 1px solid #e9ecef;
+}
+
+.settings-title {
+  font-size: 28px;
+  font-weight: 700;
+  color: #1a202c;
+  margin: 0;
+}
+
+.settings-actions {
+  display: flex;
+  gap: 8px;
+}
+
+.action-btn {
+  padding: 8px 16px;
+  background: #f8f9fa;
+  border: 1px solid #dee2e6;
+  color: #495057;
+  border-radius: 6px;
+  cursor: pointer;
+  font-size: 14px;
+  transition: all 0.2s ease;
+}
+
+.action-btn:hover {
+  background: #e9ecef;
+  border-color: #adb5bd;
+}
+
+.quick-nav {
+  display: flex;
+  gap: 4px;
+  padding: 12px 24px;
+  background: white;
+  border-bottom: 1px solid #e9ecef;
+}
+
+.quick-nav-btn {
+  padding: 8px 16px;
+  background: transparent;
+  border: 1px solid transparent;
+  color: #6c757d;
+  border-radius: 6px;
+  cursor: pointer;
+  font-size: 14px;
+  font-weight: 500;
+  transition: all 0.2s ease;
+  text-transform: capitalize;
+}
+
+.quick-nav-btn:hover {
+  background: #f8f9fa;
+  color: #495057;
+}
+
+.quick-nav-btn.active {
+  background: #e3f2fd;
+  color: #1976d2;
+  border-color: #bbdefb;
+}
+</style>
+```
+
+## Advanced Usage
+
+### Custom Controller Integration
+
+```vue
+<script setup lang="ts">
+import { ref } from "vue";
+import { SplitViewController, useSplitViewController } from "@umbra-ui/core";
+
+const panes = ref([
+  // ... your panes
+]);
+
+// Create custom controller
+const customController = useSplitViewController(
+  panes.value,
+  "custom-splitview"
+);
+
+// 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>
+  <SplitViewController
+    :panes="panes"
+    :controller="customController"
+    component-id="custom-splitview"
+  />
+</template>
+```
+
+### Integration with Router
+
+```vue
+<script setup lang="ts">
+import { ref, watch } from "vue";
+import { useRoute, useRouter } from "vue-router";
+import { SplitViewController } from "@umbra-ui/core";
+
+const route = useRoute();
+const router = useRouter();
+const splitviewRef = 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) {
+      splitviewRef.value?.navigate(index);
+    }
+  }
+);
+
+const handleNavigation = (index: number) => {
+  const pane = panes.value[index];
+  router.push(`/dashboard/${pane.name.toLowerCase()}`);
+};
+</script>
+```
+
+### Dynamic Pane Management
+
+```vue
+<script setup lang="ts">
+import { ref } from "vue";
+import { SplitViewController } from "@umbra-ui/core";
+import DynamicPane from "./DynamicPane.vue";
+
+const panes = ref([
+  {
+    name: "Main",
+    background: "#ffffff",
+    foreground: "#000000",
+    component: DynamicPane,
+    props: { content: "Main Content" },
+  },
+]);
+
+const splitviewRef = ref();
+const paneCounter = ref(1);
+
+const addPane = () => {
+  const newPane = {
+    name: `Pane ${paneCounter.value}`,
+    background: `hsl(${Math.random() * 360}, 70%, 90%)`,
+    foreground: "#000000",
+    component: DynamicPane,
+    props: { content: `Dynamic Content ${paneCounter.value}` },
+  };
+
+  panes.value.push(newPane);
+  paneCounter.value++;
+};
+
+const removePane = (index: number) => {
+  if (panes.value.length > 1) {
+    panes.value.splice(index, 1);
+  }
+};
+
+const resetPanes = () => {
+  panes.value = [
+    {
+      name: "Main",
+      background: "#ffffff",
+      foreground: "#000000",
+      component: DynamicPane,
+      props: { content: "Main Content" },
+    },
+  ];
+};
+</script>
+
+<template>
+  <div class="dynamic-splitview">
+    <!-- Controls -->
+    <div class="controls">
+      <button @click="addPane" class="control-btn add">Add Pane</button>
+      <button @click="resetPanes" class="control-btn reset">Reset</button>
+    </div>
+
+    <!-- Split View Controller -->
+    <SplitViewController
+      ref="splitviewRef"
+      :panes="panes"
+      component-id="dynamic-splitview"
+    />
+  </div>
+</template>
+
+<style module>
+.dynamic-splitview {
+  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: #28a745;
+  color: white;
+}
+
+.control-btn.add:hover {
+  background: #218838;
+}
+
+.control-btn.reset {
+  background: #6c757d;
+  color: white;
+}
+
+.control-btn.reset:hover {
+  background: #5a6268;
+}
+</style>
+```
+
+## 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 { SplitViewController } from "@umbra-ui/core";
+
+const splitviewRef = ref();
+
+// Watch for navigation changes
+watch(
+  () => splitviewRef.value?.currentPaneIndex,
+  (newIndex) => {
+    console.log("Current pane index:", newIndex);
+  }
+);
+
+// Watch for visibility events
+watch(
+  () => splitviewRef.value?.lastVisibilityEvent,
+  (event) => {
+    if (event) {
+      console.log("Visibility event:", event);
+    }
+  }
+);
+</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