@umbra.ui/core 0.1.0

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

@@ -0,0 +1,768 @@
+# Adaptive Layout
+
+A comprehensive adaptive navigation system built with Vue 3 Composition API and TypeScript. The Adaptive Layout system provides intelligent, responsive layouts that automatically adapt to different screen sizes and breakpoints, offering split-view, slideover, and navigation stack patterns.
+
+## Installation/Import
+
+```typescript
+import {
+  AdaptiveLayout,
+  AdaptiveLayoutBreadcrumbs,
+  AdaptiveLayoutMenuButton,
+} from "@umbra-ui/core";
+import type { View, ViewLayout, ViewLocation } from "@umbra-ui/core";
+```
+
+**Dependencies:**
+
+- Vue 3.x
+- @umbra-ui/core (for IconButton)
+- @umbra-ui/icons (for MenuIcon)
+
+## Basic Usage
+
+```vue
+<script setup lang="ts">
+import { ref } from "vue";
+import {
+  AdaptiveLayout,
+  AdaptiveLayoutBreadcrumbs,
+  AdaptiveLayoutMenuButton,
+} from "@umbra-ui/core";
+import MySidebar from "./MySidebar.vue";
+import MyContent from "./MyContent.vue";
+import MyDetails from "./MyDetails.vue";
+
+// Define your views
+const initialViews = [
+  {
+    id: "sidebar",
+    component: MySidebar,
+    label: "Navigation",
+    minWidth: 200,
+    maxWidth: 300,
+  },
+  {
+    id: "content",
+    component: MyContent,
+    label: "Content",
+    minWidth: 300,
+  },
+  {
+    id: "details",
+    component: MyDetails,
+    label: "Details",
+    minWidth: 250,
+    maxWidth: 400,
+  },
+];
+
+const layoutRef = ref();
+
+// Access layout methods
+const showView = (id: string) => {
+  layoutRef.value?.show(id);
+};
+
+const hideView = (id: string) => {
+  layoutRef.value?.hide(id);
+};
+</script>
+
+<template>
+  <div class="app-layout">
+    <!-- Navigation controls -->
+    <div class="layout-controls">
+      <AdaptiveLayoutMenuButton />
+      <AdaptiveLayoutBreadcrumbs />
+    </div>
+
+    <!-- Main layout -->
+    <AdaptiveLayout
+      ref="layoutRef"
+      :initial-views="initialViews"
+      layout="adaptive"
+      padding="16px"
+      gap="8px"
+      :can-hide-views="true"
+      :can-resize-views="true"
+    />
+  </div>
+</template>
+
+<style module>
+.app-layout {
+  height: 100vh;
+  display: flex;
+  flex-direction: column;
+}
+
+.layout-controls {
+  display: flex;
+  align-items: center;
+  gap: 16px;
+  padding: 12px 16px;
+  border-bottom: 1px solid var(--border-2);
+  background: var(--background-1);
+}
+</style>
+```
+
+## Components
+
+### AdaptiveLayout
+
+The main layout component that manages view positioning and responsive behavior.
+
+#### Props
+
+| Prop Name        | Type         | Required | Default             | Description                                                      |
+| ---------------- | ------------ | -------- | ------------------- | ---------------------------------------------------------------- |
+| `initialViews`   | `View[]`     | Yes      | -                   | Array of views to display in the layout                          |
+| `instanceKey`    | `string`     | No       | `"adaptive-layout"` | Unique key for shared state management                           |
+| `padding`        | `string`     | No       | `"0"`               | CSS padding value for the layout container                       |
+| `gap`            | `string`     | No       | `"0"`               | CSS gap value between views                                      |
+| `canHideViews`   | `boolean`    | No       | `true`              | Whether views can be hidden/shown                                |
+| `canResizeViews` | `boolean`    | No       | `true`              | Whether views can be resized                                     |
+| `layout`         | `ViewLayout` | No       | `"adaptive"`        | Layout mode: "adaptive", "splitview", "slideover", or "navstack" |
+
+#### View Interface
+
+```typescript
+interface View {
+  id: string;
+  component: Component | ReturnType<typeof markRaw<Component>>;
+  props?: Record<string, unknown>;
+  minWidth?: number;
+  maxWidth?: number;
+  currentWidth?: number;
+  label?: string;
+}
+```
+
+#### ViewLayout Types
+
+```typescript
+type ViewLayout = "splitview" | "slideover" | "navstack" | "adaptive";
+```
+
+#### Events
+
+| Event Name  | Payload Type     | Description                                |
+| ----------- | ---------------- | ------------------------------------------ |
+| `view-show` | `{ id: string }` | Emitted when a view is shown               |
+| `view-hide` | `{ id: string }` | Emitted when a view is hidden              |
+| `view-push` | `{ id: string }` | Emitted when a view is pushed to overlay   |
+| `view-pop`  | `{ id: string }` | Emitted when a view is popped from overlay |
+
+#### Exposed Methods/Refs
+
+| Method    | Parameters                                     | Description                      |
+| --------- | ---------------------------------------------- | -------------------------------- |
+| `show`    | `(id: string, animated?: boolean)`             | Show a specific view             |
+| `hide`    | `(id: string, animated?: boolean)`             | Hide a specific view             |
+| `push`    | `(id: string, animated?: boolean)`             | Push a view to overlay           |
+| `pop`     | `(id: string, animated?: boolean)`             | Pop a view from overlay          |
+| `toggle`  | `(id: string, animated?: boolean)`             | Toggle view visibility           |
+| `add`     | `(view: View, animated?: boolean)`             | Add a new view (not implemented) |
+| `remove`  | `(id: string, animated?: boolean)`             | Remove a view (not implemented)  |
+| `replace` | `(id: string, view: View, animated?: boolean)` | Replace a view (not implemented) |
+
+### AdaptiveLayoutBreadcrumbs
+
+Navigation breadcrumbs that show the current view hierarchy and allow navigation between views.
+
+#### Props
+
+| Prop Name        | Type               | Required | Default                     | Description                               |
+| ---------------- | ------------------ | -------- | --------------------------- | ----------------------------------------- |
+| `instanceKey`    | `string \| symbol` | No       | `Symbol("adaptive-layout")` | Key to match with AdaptiveLayout instance |
+| `separator`      | `string`           | No       | `"/"`                       | Separator character between breadcrumbs   |
+| `showTooltip`    | `boolean`          | No       | `true`                      | Whether to show tooltips on hover         |
+| `maxLabelLength` | `number`           | No       | `20`                        | Maximum length for breadcrumb labels      |
+
+#### Events
+
+| Event Name         | Payload Type                                       | Description                          |
+| ------------------ | -------------------------------------------------- | ------------------------------------ |
+| `breadcrumb-click` | `{ id: string, label: string, isActive: boolean }` | Emitted when a breadcrumb is clicked |
+
+### AdaptiveLayoutMenuButton
+
+A menu button that shows/hides offscreen views in an overlay, with an optional count badge.
+
+#### Props
+
+| Prop Name     | Type                                 | Required | Default                     | Description                               |
+| ------------- | ------------------------------------ | -------- | --------------------------- | ----------------------------------------- |
+| `instanceKey` | `string \| symbol`                   | No       | `Symbol("adaptive-layout")` | Key to match with AdaptiveLayout instance |
+| `isolated`    | `boolean`                            | No       | `false`                     | Use completely isolated instance          |
+| `showCount`   | `boolean`                            | No       | `true`                      | Whether to show the count badge           |
+| `customIcon`  | `{ open?: string, closed?: string }` | No       | -                           | Custom icons for open/closed states       |
+
+#### Events
+
+| Event Name       | Payload Type          | Description                     |
+| ---------------- | --------------------- | ------------------------------- |
+| `toggle-overlay` | `{ isOpen: boolean }` | Emitted when overlay is toggled |
+
+## Layout Modes
+
+### Adaptive Mode
+
+**Default mode** - Automatically switches between layout patterns based on screen size:
+
+- **Desktop**: Split-view layout with all views visible
+- **Tablet**: Slideover layout with overlay for hidden views
+- **Mobile**: Navigation stack with full-screen views
+
+### Split-View Mode
+
+- All views displayed side-by-side
+- Resizable panels with drag handles
+- Ideal for desktop applications
+- Supports minimum and maximum width constraints
+
+### Slideover Mode
+
+- Primary view always visible
+- Secondary views appear as overlays
+- Semi-transparent backdrop with blur effect
+- Touch-friendly for tablet interfaces
+
+### Navigation Stack Mode
+
+- Full-screen views with stack navigation
+- Push/pop navigation pattern
+- Mobile-optimized interface
+- Breadcrumb navigation support
+
+## Responsive Breakpoints
+
+The system automatically adapts based on container width:
+
+- **Mobile**: < 768px - Navigation stack layout
+- **Tablet**: 768px - 1024px - Slideover layout
+- **Desktop**: > 1024px - Split-view layout
+
+## CSS Customization
+
+### Layout Variables
+
+```css
+.adaptive-layout {
+  --padding: 16px;
+  --gap: 8px;
+  --width: 100%;
+}
+```
+
+### Handle Styling
+
+```css
+.adaptive-layout {
+  --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;
+}
+```
+
+### Breadcrumb Styling
+
+```css
+.adaptive-layout {
+  --slideover-breadcrumb-hover-opacity: 0.8;
+  --background-1: #ffffff;
+  --border-2: #e2e8f0;
+  --text-1: #1a202c;
+  --font-weight-regular: 400;
+  --font-weight-medium: 500;
+  --control-2: #f7fafc;
+  --border-1: #cbd5e0;
+}
+```
+
+## Examples
+
+### Basic Three-Panel Layout
+
+```vue
+<script setup lang="ts">
+import { ref } from "vue";
+import { AdaptiveLayout } from "@umbra-ui/core";
+import Sidebar from "./Sidebar.vue";
+import Content from "./Content.vue";
+import Details from "./Details.vue";
+
+const views = [
+  {
+    id: "sidebar",
+    component: Sidebar,
+    label: "Sidebar",
+    minWidth: 200,
+    maxWidth: 300,
+  },
+  {
+    id: "content",
+    component: Content,
+    label: "Content",
+    minWidth: 400,
+  },
+  {
+    id: "details",
+    component: Details,
+    label: "Details",
+    minWidth: 250,
+    maxWidth: 400,
+  },
+];
+</script>
+
+<template>
+  <AdaptiveLayout
+    :initial-views="views"
+    padding="16px"
+    gap="12px"
+    :can-hide-views="true"
+    :can-resize-views="true"
+  />
+</template>
+```
+
+### File Explorer Layout
+
+```vue
+<script setup lang="ts">
+import { ref } from "vue";
+import {
+  AdaptiveLayout,
+  AdaptiveLayoutBreadcrumbs,
+  AdaptiveLayoutMenuButton,
+} from "@umbra-ui/core";
+import FileTree from "./FileTree.vue";
+import FileList from "./FileList.vue";
+import FilePreview from "./FilePreview.vue";
+
+const views = [
+  {
+    id: "tree",
+    component: FileTree,
+    label: "Folders",
+    minWidth: 200,
+    maxWidth: 350,
+  },
+  {
+    id: "list",
+    component: FileList,
+    label: "Files",
+    minWidth: 300,
+  },
+  {
+    id: "preview",
+    component: FilePreview,
+    label: "Preview",
+    minWidth: 300,
+    maxWidth: 500,
+  },
+];
+
+const layoutRef = ref();
+
+const handleFileSelect = (file: any) => {
+  // Show preview when file is selected
+  layoutRef.value?.show("preview");
+};
+</script>
+
+<template>
+  <div class="file-explorer">
+    <header class="explorer-header">
+      <AdaptiveLayoutMenuButton />
+      <AdaptiveLayoutBreadcrumbs />
+    </header>
+
+    <AdaptiveLayout
+      ref="layoutRef"
+      :initial-views="views"
+      layout="adaptive"
+      padding="0"
+      gap="1px"
+      :can-hide-views="true"
+      :can-resize-views="true"
+    />
+  </div>
+</template>
+
+<style module>
+.file-explorer {
+  height: 100vh;
+  display: flex;
+  flex-direction: column;
+}
+
+.explorer-header {
+  display: flex;
+  align-items: center;
+  gap: 16px;
+  padding: 12px 16px;
+  background: var(--background-1);
+  border-bottom: 1px solid var(--border-2);
+}
+</style>
+```
+
+### Settings Panel Layout
+
+```vue
+<script setup lang="ts">
+import { ref } from "vue";
+import { AdaptiveLayout } from "@umbra-ui/core";
+import SettingsNav from "./SettingsNav.vue";
+import SettingsContent from "./SettingsContent.vue";
+
+const views = [
+  {
+    id: "nav",
+    component: SettingsNav,
+    label: "Categories",
+    minWidth: 200,
+    maxWidth: 250,
+  },
+  {
+    id: "content",
+    component: SettingsContent,
+    label: "Settings",
+    minWidth: 400,
+  },
+];
+
+const layoutRef = ref();
+
+const showCategory = (categoryId: string) => {
+  // Show specific settings category
+  layoutRef.value?.show("content");
+};
+</script>
+
+<template>
+  <div class="settings-layout">
+    <AdaptiveLayout
+      ref="layoutRef"
+      :initial-views="views"
+      layout="adaptive"
+      padding="24px"
+      gap="16px"
+      :can-hide-views="true"
+      :can-resize-views="false"
+    />
+  </div>
+</template>
+
+<style module>
+.settings-layout {
+  height: 100vh;
+  background: var(--background-1);
+}
+</style>
+```
+
+### Mobile-First Navigation
+
+```vue
+<script setup lang="ts">
+import { ref } from "vue";
+import { AdaptiveLayout, AdaptiveLayoutBreadcrumbs } from "@umbra-ui/core";
+import HomeView from "./HomeView.vue";
+import ProfileView from "./ProfileView.vue";
+import SettingsView from "./SettingsView.vue";
+
+const views = [
+  {
+    id: "home",
+    component: HomeView,
+    label: "Home",
+  },
+  {
+    id: "profile",
+    component: ProfileView,
+    label: "Profile",
+  },
+  {
+    id: "settings",
+    component: SettingsView,
+    label: "Settings",
+  },
+];
+
+const layoutRef = ref();
+
+const navigateTo = (viewId: string) => {
+  layoutRef.value?.show(viewId);
+};
+</script>
+
+<template>
+  <div class="mobile-app">
+    <nav class="app-nav">
+      <AdaptiveLayoutBreadcrumbs />
+    </nav>
+
+    <AdaptiveLayout
+      ref="layoutRef"
+      :initial-views="views"
+      layout="navstack"
+      padding="16px"
+      gap="0"
+      :can-hide-views="true"
+      :can-resize-views="false"
+    />
+  </div>
+</template>
+
+<style module>
+.mobile-app {
+  height: 100vh;
+  display: flex;
+  flex-direction: column;
+}
+
+.app-nav {
+  padding: 12px 16px;
+  background: var(--background-1);
+  border-bottom: 1px solid var(--border-2);
+}
+</style>
+```
+
+### Custom Layout with Resize Handles
+
+```vue
+<script setup lang="ts">
+import { ref } from "vue";
+import { AdaptiveLayout } from "@umbra-ui/core";
+import CodeEditor from "./CodeEditor.vue";
+import FileExplorer from "./FileExplorer.vue";
+import Terminal from "./Terminal.vue";
+
+const views = [
+  {
+    id: "explorer",
+    component: FileExplorer,
+    label: "Explorer",
+    minWidth: 200,
+    maxWidth: 400,
+    currentWidth: 250,
+  },
+  {
+    id: "editor",
+    component: CodeEditor,
+    label: "Editor",
+    minWidth: 300,
+  },
+  {
+    id: "terminal",
+    component: Terminal,
+    label: "Terminal",
+    minWidth: 200,
+    maxWidth: 500,
+    currentWidth: 300,
+  },
+];
+
+const layoutRef = ref();
+
+const handleResize = (viewId: string, newWidth: number) => {
+  console.log(`${viewId} resized to ${newWidth}px`);
+};
+</script>
+
+<template>
+  <div class="ide-layout">
+    <AdaptiveLayout
+      ref="layoutRef"
+      :initial-views="views"
+      layout="splitview"
+      padding="0"
+      gap="1px"
+      :can-hide-views="true"
+      :can-resize-views="true"
+    />
+  </div>
+</template>
+
+<style module>
+.ide-layout {
+  height: 100vh;
+  background: var(--background-1);
+}
+</style>
+```
+
+## Advanced Usage
+
+### Shared State Management
+
+```vue
+<script setup lang="ts">
+import { ref } from "vue";
+import {
+  AdaptiveLayout,
+  AdaptiveLayoutBreadcrumbs,
+  AdaptiveLayoutMenuButton,
+} from "@umbra-ui/core";
+
+// Use the same instance key for shared state
+const LAYOUT_KEY = "main-layout";
+
+const views = [
+  // ... your views
+];
+
+const layoutRef = ref();
+</script>
+
+<template>
+  <div class="app">
+    <!-- These components share the same layout state -->
+    <AdaptiveLayoutMenuButton :instance-key="LAYOUT_KEY" />
+    <AdaptiveLayoutBreadcrumbs :instance-key="LAYOUT_KEY" />
+
+    <AdaptiveLayout
+      ref="layoutRef"
+      :instance-key="LAYOUT_KEY"
+      :initial-views="views"
+    />
+  </div>
+</template>
+```
+
+### Dynamic View Management
+
+```vue
+<script setup lang="ts">
+import { ref, markRaw } from "vue";
+import { AdaptiveLayout } from "@umbra-ui/core";
+import DynamicView from "./DynamicView.vue";
+
+const views = ref([
+  {
+    id: "main",
+    component: markRaw(DynamicView),
+    label: "Main View",
+    minWidth: 300,
+  },
+]);
+
+const layoutRef = ref();
+
+const addView = (id: string, component: any, props: any = {}) => {
+  const newView = {
+    id,
+    component: markRaw(component),
+    label: id,
+    minWidth: 200,
+    props,
+  };
+
+  // Note: add method is not yet implemented
+  // layoutRef.value?.add(newView);
+  console.log("Add view:", newView);
+};
+
+const removeView = (id: string) => {
+  // Note: remove method is not yet implemented
+  // layoutRef.value?.remove(id);
+  console.log("Remove view:", id);
+};
+</script>
+
+<template>
+  <div class="dynamic-layout">
+    <div class="controls">
+      <button @click="addView('new', DynamicView)">Add View</button>
+      <button @click="removeView('new')">Remove View</button>
+    </div>
+
+    <AdaptiveLayout
+      ref="layoutRef"
+      :initial-views="views"
+      :can-hide-views="true"
+      :can-resize-views="true"
+    />
+  </div>
+</template>
+```
+
+## Performance Considerations
+
+- **Component Marking**: Always use `markRaw()` when passing components to prevent Vue's reactivity system from wrapping them
+- **View Limits**: Consider limiting the number of views to prevent performance issues
+- **Resize Debouncing**: Resize operations are automatically debounced for smooth performance
+- **Memory Management**: Views are properly cleaned up when removed from the layout
+
+## Accessibility
+
+- **Keyboard Navigation**: All interactive elements support keyboard navigation
+- **Screen Reader Support**: Proper ARIA labels and roles for screen readers
+- **Focus Management**: Focus is properly managed during view transitions
+- **High Contrast**: Supports high contrast mode and custom color schemes
+
+## 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, Flexbox, and modern CSS features
+- **JavaScript**: Requires ES2020+ support for optional chaining and nullish coalescing
+
+## Troubleshooting
+
+### Common Issues
+
+1. **Views not showing**: Ensure components are properly marked with `markRaw()`
+2. **Layout not responsive**: Check that the container has a defined height
+3. **Resize not working**: Verify `canResizeViews` is set to `true`
+4. **State not shared**: Ensure all components use the same `instanceKey`
+
+### Debug Mode
+
+```vue
+<script setup lang="ts">
+import { ref, watch } from "vue";
+import { AdaptiveLayout } from "@umbra-ui/core";
+
+const layoutRef = ref();
+const debugInfo = ref({});
+
+// Watch for layout changes
+watch(
+  () => layoutRef.value,
+  (layout) => {
+    if (layout) {
+      // Access internal state for debugging
+      console.log("Layout state:", layout);
+    }
+  },
+  { immediate: true }
+);
+</script>
+```
+
+## Migration Guide
+
+### From v1 to v2
+
+- `instanceKey` prop is now required for shared state
+- `layout` prop replaces individual layout components
+- View interface has been updated with new properties
+- Animation system has been refactored for better performance
+
+### Breaking Changes
+
+- Removed individual layout components (SplitView, Slideover, NavStack)
+- Changed view management API
+- Updated CSS class names and structure
+- Modified event payload structure