@umbra.ui/core 0.1.0

package/src/components/models/Sidebar/README.md

@@ -0,0 +1,1228 @@
+# Sidebar
+
+A flexible and animated sidebar component built with Vue 3 Composition API and TypeScript. The Sidebar component provides a powerful interface for displaying navigation panels, menus, and contextual content with smooth slide animations and comprehensive positioning options.
+
+## Installation/Import
+
+```typescript
+import { Sidebar } from "@umbra-ui/core";
+import type { SidebarProps } from "@umbra-ui/core";
+```
+
+**Dependencies:**
+
+- Vue 3.x
+- gsap (for animations)
+
+## Basic Usage
+
+```vue
+<script setup lang="ts">
+import { ref } from "vue";
+import { Sidebar, Button } from "@umbra-ui/core";
+
+const isSidebarOpen = ref(false);
+
+const handleOpen = () => {
+  console.log("Sidebar opened");
+};
+
+const handleClose = () => {
+  console.log("Sidebar closed");
+};
+
+const handleBackdropClick = () => {
+  console.log("Backdrop clicked");
+};
+</script>
+
+<template>
+  <div>
+    <Button @click="isSidebarOpen = true">Open Sidebar</Button>
+
+    <Sidebar
+      v-model="isSidebarOpen"
+      side="left"
+      :dismiss-on-backdrop="true"
+      @open="handleOpen"
+      @close="handleClose"
+      @backdrop-click="handleBackdropClick"
+    >
+      <div class="sidebar-content">
+        <h2>Sidebar Title</h2>
+        <p>This is the sidebar content. It can contain any HTML elements.</p>
+        <Button @click="isSidebarOpen = false">Close</Button>
+      </div>
+    </Sidebar>
+  </div>
+</template>
+
+<style>
+.sidebar-content {
+  padding: 2rem;
+  min-height: 200px;
+}
+</style>
+```
+
+## Props
+
+| Prop Name           | Type                                     | Required | Default   | Description                                      |
+| ------------------- | ---------------------------------------- | -------- | --------- | ------------------------------------------------ |
+| `modelValue`        | `boolean`                                | Yes      | -         | Controls the open/closed state of the sidebar    |
+| `side`              | `"top" \| "bottom" \| "left" \| "right"` | No       | `"left"`  | The side where the sidebar appears               |
+| `dismissOnBackdrop` | `boolean`                                | No       | `true`    | Whether clicking the backdrop closes the sidebar |
+| `width`             | `string`                                 | No       | `"280px"` | Width of the sidebar (for left/right)            |
+| `height`            | `string`                                 | No       | `"280px"` | Height of the sidebar (for top/bottom)           |
+| `minWidth`          | `string`                                 | No       | `"280px"` | Minimum width of the sidebar                     |
+| `minHeight`         | `string`                                 | No       | `"280px"` | Minimum height of the sidebar                    |
+| `maxWidth`          | `string`                                 | No       | `"90vw"`  | Maximum width of the sidebar                     |
+| `maxHeight`         | `string`                                 | No       | `"90vh"`  | Maximum height of the sidebar                    |
+| `animationDuration` | `number`                                 | No       | `0.4`     | Animation duration in seconds                    |
+| `backdropStyle`     | `"blur" \| "dim"`                        | No       | `"blur"`  | Backdrop style: blur or dim                      |
+| `zIndex`            | `number`                                 | No       | `1000`    | Z-index for the sidebar                          |
+| `teleportTo`        | `string \| HTMLElement`                  | No       | `"body"`  | Teleport target element                          |
+
+## Events
+
+| Event Name          | Payload Type | Description                                 |
+| ------------------- | ------------ | ------------------------------------------- |
+| `update:modelValue` | `boolean`    | Emitted when the sidebar open state changes |
+| `backdrop-click`    | `void`       | Emitted when the backdrop is clicked        |
+| `open`              | `void`       | Emitted when the sidebar opens              |
+| `close`             | `void`       | Emitted when the sidebar closes             |
+| `after-enter`       | `void`       | Emitted after the open animation completes  |
+| `after-leave`       | `void`       | Emitted after the close animation completes |
+
+## Slots
+
+| Slot Name | Description                              |
+| --------- | ---------------------------------------- |
+| `default` | The content displayed inside the sidebar |
+
+## Exposed Methods/Refs
+
+The Sidebar component exposes the following methods and properties via template refs:
+
+| Method/Property | Type           | Description                            |
+| --------------- | -------------- | -------------------------------------- |
+| `open`          | `() => void`   | Opens the sidebar programmatically     |
+| `close`         | `() => void`   | Closes the sidebar programmatically    |
+| `isVisible`     | `Ref<boolean>` | Reactive reference to visibility state |
+| `isAnimating`   | `Ref<boolean>` | Reactive reference to animation state  |
+
+### Example Usage
+
+```vue
+<script setup lang="ts">
+import { ref } from "vue";
+import { Sidebar } from "@umbra-ui/core";
+
+const sidebarRef = ref<InstanceType<typeof Sidebar> | null>(null);
+
+const openSidebar = () => {
+  sidebarRef.value?.open();
+};
+
+const closeSidebar = () => {
+  sidebarRef.value?.close();
+};
+</script>
+
+<template>
+  <Sidebar ref="sidebarRef" :model-value="false">
+    <div class="content">
+      <p>Sidebar content</p>
+      <button @click="closeSidebar">Close</button>
+    </div>
+  </Sidebar>
+</template>
+```
+
+## Positioning Options
+
+### Left Sidebar
+
+- **Default position**
+- Slides in from the left edge
+- Full height with configurable width
+- Best for navigation menus and main content panels
+
+### Right Sidebar
+
+- Slides in from the right edge
+- Full height with configurable width
+- Good for secondary actions and settings panels
+
+### Top Sidebar
+
+- Slides in from the top edge
+- Full width with configurable height
+- Useful for notification bars and top navigation
+
+### Bottom Sidebar
+
+- Slides in from the bottom edge
+- Full width with configurable height
+- Good for mobile navigation and action sheets
+
+## Backdrop Styles
+
+### Blur Backdrop
+
+- **Default backdrop style**
+- Semi-transparent with blur effect
+- Modern, iOS-like appearance
+- Uses `backdrop-filter: blur(10px)`
+
+### Dim Backdrop
+
+- Simple semi-transparent overlay
+- No blur effect
+- More traditional modal appearance
+- Better performance on older devices
+
+## CSS Customization
+
+The Sidebar component uses CSS custom properties for theming and customization:
+
+### Light Theme Variables
+
+```css
+/* Sidebar colors */
+--sidebar-bg: #ffffff;
+
+/* Sidebar backdrop colors */
+--sidebar-backdrop-blur-bg: rgba(0, 0, 0, 0.3);
+--sidebar-backdrop-dim-bg: rgba(0, 0, 0, 0.7);
+
+/* Sidebar shadow colors */
+--sidebar-shadow-left: rgba(0, 0, 0, 0.15);
+--sidebar-shadow-right: rgba(0, 0, 0, 0.15);
+--sidebar-shadow-top: rgba(0, 0, 0, 0.15);
+--sidebar-shadow-bottom: rgba(0, 0, 0, 0.15);
+
+/* Sidebar scrollbar colors */
+--sidebar-scrollbar-thumb: rgba(0, 0, 0, 0.2);
+--sidebar-scrollbar-thumb-hover: rgba(0, 0, 0, 0.3);
+```
+
+### Dark Theme Variables
+
+```css
+/* Sidebar colors */
+--sidebar-bg: #111111;
+
+/* Sidebar backdrop colors */
+--sidebar-backdrop-blur-bg: rgba(0, 0, 0, 0.3);
+--sidebar-backdrop-dim-bg: rgba(0, 0, 0, 0.85);
+
+/* Sidebar shadow colors */
+--sidebar-shadow-left: rgba(0, 0, 0, 0.5);
+--sidebar-shadow-right: rgba(0, 0, 0, 0.5);
+--sidebar-shadow-top: rgba(0, 0, 0, 0.5);
+--sidebar-shadow-bottom: rgba(0, 0, 0, 0.5);
+
+/* Sidebar scrollbar colors */
+--sidebar-scrollbar-thumb: rgba(255, 255, 255, 0.2);
+--sidebar-scrollbar-thumb-hover: rgba(255, 255, 255, 0.3);
+```
+
+## Key Features
+
+### Smart Positioning
+
+- **Four Directions**: Slide in from top, bottom, left, or right
+- **Responsive Sizing**: Configurable width, height, and constraints
+- **Viewport Awareness**: Automatically respects viewport boundaries
+- **Safe Area Support**: Handles mobile device safe areas
+
+### Animation System
+
+- **GSAP Animations**: Smooth, performant animations using GSAP
+- **Slide Animations**: Directional slide-in/out effects
+- **GPU Acceleration**: Hardware-accelerated transforms
+- **Customizable Duration**: Configurable animation timing
+
+### User Experience
+
+- **Backdrop Interaction**: Click backdrop to dismiss (configurable)
+- **Keyboard Support**: Escape key closes sidebar
+- **Body Scroll Lock**: Prevents background scrolling when open
+- **Teleport Support**: Renders outside component tree
+
+### Visual Features
+
+- **Directional Shadows**: Shadows adapt to sidebar position
+- **Custom Scrollbars**: Styled scrollbars for better UX
+- **Backdrop Effects**: Blur or dim backdrop options
+- **Safe Area Handling**: Proper mobile device support
+
+## Examples
+
+### Basic Sidebar
+
+```vue
+<script setup lang="ts">
+import { ref } from "vue";
+import { Sidebar, Button } from "@umbra-ui/core";
+
+const isOpen = ref(false);
+
+const handleOpen = () => {
+  console.log("Sidebar opened");
+};
+
+const handleClose = () => {
+  console.log("Sidebar closed");
+};
+</script>
+
+<template>
+  <div class="basic-sidebar">
+    <h3>Basic Sidebar</h3>
+
+    <Button @click="isOpen = true">Open Sidebar</Button>
+
+    <Sidebar
+      v-model="isOpen"
+      side="left"
+      :dismiss-on-backdrop="true"
+      @open="handleOpen"
+      @close="handleClose"
+    >
+      <div class="sidebar-content">
+        <h2>Sidebar Title</h2>
+        <p>This is a basic sidebar with default settings.</p>
+        <p>
+          It slides in from the left and can be dismissed by clicking the
+          backdrop.
+        </p>
+        <div class="actions">
+          <Button @click="isOpen = false">Close</Button>
+        </div>
+      </div>
+    </Sidebar>
+
+    <p class="status">Sidebar is {{ isOpen ? "open" : "closed" }}</p>
+  </div>
+</template>
+
+<style module>
+.basic-sidebar {
+  padding: 2rem;
+  border: 1px solid #e0e0e0;
+  border-radius: 0.5rem;
+  max-width: 400px;
+}
+
+.sidebar-content {
+  padding: 2rem;
+  min-height: 200px;
+}
+
+.sidebar-content h2 {
+  margin: 0 0 1rem 0;
+  color: #333;
+}
+
+.sidebar-content p {
+  margin: 0 0 1rem 0;
+  color: #666;
+  line-height: 1.5;
+}
+
+.actions {
+  display: flex;
+  gap: 0.75rem;
+  justify-content: flex-end;
+  margin-top: 1.5rem;
+}
+
+.status {
+  margin-top: 1rem;
+  color: #666;
+  font-size: 0.875rem;
+}
+</style>
+```
+
+### Different Sides
+
+```vue
+<script setup lang="ts">
+import { ref } from "vue";
+import { Sidebar, Button } from "@umbra-ui/core";
+
+const sides = ["left", "right", "top", "bottom"];
+const openSidebars = ref<Record<string, boolean>>({});
+
+const toggleSidebar = (side: string) => {
+  openSidebars.value[side] = !openSidebars.value[side];
+};
+</script>
+
+<template>
+  <div class="sides-demo">
+    <h3>Sidebar Sides</h3>
+    <p>Click the buttons to see different slide directions:</p>
+
+    <div class="sides-grid">
+      <div v-for="side in sides" :key="side" class="side-item">
+        <Button @click="toggleSidebar(side)" size="small">
+          {{ side }}
+        </Button>
+
+        <Sidebar
+          v-model="openSidebars[side]"
+          :side="side"
+          :dismiss-on-backdrop="true"
+        >
+          <div class="side-content">
+            <h4>{{ side }} Sidebar</h4>
+            <p>This sidebar slides in from the {{ side }}.</p>
+            <Button @click="openSidebars[side] = false" size="small">
+              Close
+            </Button>
+          </div>
+        </Sidebar>
+      </div>
+    </div>
+  </div>
+</template>
+
+<style module>
+.sides-demo {
+  padding: 2rem;
+  border: 1px solid #e0e0e0;
+  border-radius: 0.5rem;
+  max-width: 600px;
+}
+
+.sides-grid {
+  display: grid;
+  grid-template-columns: repeat(auto-fit, minmax(120px, 1fr));
+  gap: 1rem;
+  margin-top: 1rem;
+}
+
+.side-item {
+  display: flex;
+  justify-content: center;
+  align-items: center;
+  min-height: 60px;
+}
+
+.side-content {
+  padding: 1.5rem;
+  min-height: 150px;
+  text-align: center;
+}
+
+.side-content h4 {
+  margin: 0 0 1rem 0;
+  color: #333;
+  text-transform: capitalize;
+}
+
+.side-content p {
+  margin: 0 0 1rem 0;
+  color: #666;
+}
+</style>
+```
+
+### Navigation Sidebar
+
+```vue
+<script setup lang="ts">
+import { ref } from "vue";
+import { Sidebar, Button } from "@umbra-ui/core";
+
+const isNavOpen = ref(false);
+const activeItem = ref("dashboard");
+
+const navItems = [
+  { id: "dashboard", label: "Dashboard", icon: "🏠" },
+  { id: "projects", label: "Projects", icon: "📁" },
+  { id: "tasks", label: "Tasks", icon: "✅" },
+  { id: "calendar", label: "Calendar", icon: "📅" },
+  { id: "messages", label: "Messages", icon: "💬" },
+  { id: "settings", label: "Settings", icon: "⚙️" },
+];
+
+const handleNavClick = (itemId: string) => {
+  activeItem.value = itemId;
+  console.log("Navigated to:", itemId);
+};
+</script>
+
+<template>
+  <div class="nav-sidebar">
+    <h3>Navigation Sidebar</h3>
+
+    <Button @click="isNavOpen = true">Open Navigation</Button>
+
+    <Sidebar
+      v-model="isNavOpen"
+      side="left"
+      width="280px"
+      :dismiss-on-backdrop="true"
+    >
+      <div class="nav-content">
+        <div class="nav-header">
+          <h2>Navigation</h2>
+          <button @click="isNavOpen = false" class="close-btn">×</button>
+        </div>
+
+        <nav class="nav-menu">
+          <div
+            v-for="item in navItems"
+            :key="item.id"
+            :class="[
+              'nav-item',
+              { 'nav-item--active': activeItem === item.id },
+            ]"
+            @click="handleNavClick(item.id)"
+          >
+            <span class="nav-icon">{{ item.icon }}</span>
+            <span class="nav-label">{{ item.label }}</span>
+          </div>
+        </nav>
+
+        <div class="nav-footer">
+          <div class="user-info">
+            <div class="user-avatar">👤</div>
+            <div class="user-details">
+              <div class="user-name">John Doe</div>
+              <div class="user-email">john@example.com</div>
+            </div>
+          </div>
+        </div>
+      </div>
+    </Sidebar>
+  </div>
+</template>
+
+<style module>
+.nav-sidebar {
+  padding: 2rem;
+  border: 1px solid #e0e0e0;
+  border-radius: 0.5rem;
+  max-width: 400px;
+}
+
+.nav-content {
+  height: 100vh;
+  display: flex;
+  flex-direction: column;
+}
+
+.nav-header {
+  display: flex;
+  justify-content: space-between;
+  align-items: center;
+  padding: 1.5rem 2rem 1rem;
+  border-bottom: 1px solid #e0e0e0;
+}
+
+.nav-header h2 {
+  margin: 0;
+  color: #333;
+}
+
+.close-btn {
+  background: none;
+  border: none;
+  font-size: 1.5rem;
+  cursor: pointer;
+  padding: 0;
+  width: 32px;
+  height: 32px;
+  display: flex;
+  align-items: center;
+  justify-content: center;
+  border-radius: 50%;
+  color: #666;
+  transition: background-color 0.2s;
+}
+
+.close-btn:hover {
+  background-color: #f0f0f0;
+}
+
+.nav-menu {
+  flex: 1;
+  padding: 1rem 0;
+}
+
+.nav-item {
+  display: flex;
+  align-items: center;
+  gap: 1rem;
+  padding: 0.75rem 2rem;
+  cursor: pointer;
+  transition: background-color 0.2s;
+  color: #666;
+}
+
+.nav-item:hover {
+  background-color: #f8f9fa;
+}
+
+.nav-item--active {
+  background-color: #e3f2fd;
+  color: #1976d2;
+  border-right: 3px solid #1976d2;
+}
+
+.nav-icon {
+  font-size: 1.25rem;
+  width: 1.5rem;
+  text-align: center;
+}
+
+.nav-label {
+  font-weight: 500;
+}
+
+.nav-footer {
+  padding: 1.5rem 2rem;
+  border-top: 1px solid #e0e0e0;
+}
+
+.user-info {
+  display: flex;
+  align-items: center;
+  gap: 0.75rem;
+}
+
+.user-avatar {
+  width: 40px;
+  height: 40px;
+  background-color: #e0e0e0;
+  border-radius: 50%;
+  display: flex;
+  align-items: center;
+  justify-content: center;
+  font-size: 1.25rem;
+}
+
+.user-name {
+  font-weight: 600;
+  color: #333;
+  margin-bottom: 0.25rem;
+}
+
+.user-email {
+  font-size: 0.875rem;
+  color: #666;
+}
+</style>
+```
+
+### Settings Panel
+
+```vue
+<script setup lang="ts">
+import { ref } from "vue";
+import { Sidebar, Button } from "@umbra-ui/core";
+
+const isSettingsOpen = ref(false);
+const settings = ref({
+  notifications: true,
+  darkMode: false,
+  autoSave: true,
+  language: "en",
+});
+
+const handleSave = () => {
+  console.log("Settings saved:", settings.value);
+  isSettingsOpen.value = false;
+};
+</script>
+
+<template>
+  <div class="settings-sidebar">
+    <h3>Settings Panel</h3>
+
+    <Button @click="isSettingsOpen = true">Open Settings</Button>
+
+    <Sidebar
+      v-model="isSettingsOpen"
+      side="right"
+      width="350px"
+      :dismiss-on-backdrop="false"
+    >
+      <div class="settings-content">
+        <div class="settings-header">
+          <h2>Settings</h2>
+          <button @click="isSettingsOpen = false" class="close-btn">×</button>
+        </div>
+
+        <div class="settings-body">
+          <div class="setting-group">
+            <h3>Preferences</h3>
+
+            <div class="setting-item">
+              <div class="setting-info">
+                <h4>Notifications</h4>
+                <p>Receive push notifications</p>
+              </div>
+              <label class="toggle">
+                <input v-model="settings.notifications" type="checkbox" />
+                <span class="slider"></span>
+              </label>
+            </div>
+
+            <div class="setting-item">
+              <div class="setting-info">
+                <h4>Dark Mode</h4>
+                <p>Use dark theme</p>
+              </div>
+              <label class="toggle">
+                <input v-model="settings.darkMode" type="checkbox" />
+                <span class="slider"></span>
+              </label>
+            </div>
+
+            <div class="setting-item">
+              <div class="setting-info">
+                <h4>Auto Save</h4>
+                <p>Automatically save changes</p>
+              </div>
+              <label class="toggle">
+                <input v-model="settings.autoSave" type="checkbox" />
+                <span class="slider"></span>
+              </label>
+            </div>
+          </div>
+
+          <div class="setting-group">
+            <h3>Language</h3>
+
+            <div class="setting-item">
+              <div class="setting-info">
+                <h4>Language</h4>
+                <p>Select your preferred language</p>
+              </div>
+              <select v-model="settings.language" class="select">
+                <option value="en">English</option>
+                <option value="es">Spanish</option>
+                <option value="fr">French</option>
+                <option value="de">German</option>
+              </select>
+            </div>
+          </div>
+        </div>
+
+        <div class="settings-footer">
+          <Button @click="isSettingsOpen = false" variant="secondary">
+            Cancel
+          </Button>
+          <Button @click="handleSave">Save Changes</Button>
+        </div>
+      </div>
+    </Sidebar>
+  </div>
+</template>
+
+<style module>
+.settings-sidebar {
+  padding: 2rem;
+  border: 1px solid #e0e0e0;
+  border-radius: 0.5rem;
+  max-width: 400px;
+}
+
+.settings-content {
+  height: 100vh;
+  display: flex;
+  flex-direction: column;
+}
+
+.settings-header {
+  display: flex;
+  justify-content: space-between;
+  align-items: center;
+  padding: 1.5rem 2rem 1rem;
+  border-bottom: 1px solid #e0e0e0;
+}
+
+.settings-header h2 {
+  margin: 0;
+  color: #333;
+}
+
+.close-btn {
+  background: none;
+  border: none;
+  font-size: 1.5rem;
+  cursor: pointer;
+  padding: 0;
+  width: 32px;
+  height: 32px;
+  display: flex;
+  align-items: center;
+  justify-content: center;
+  border-radius: 50%;
+  color: #666;
+  transition: background-color 0.2s;
+}
+
+.close-btn:hover {
+  background-color: #f0f0f0;
+}
+
+.settings-body {
+  flex: 1;
+  padding: 2rem;
+  overflow-y: auto;
+}
+
+.setting-group {
+  margin-bottom: 2rem;
+}
+
+.setting-group h3 {
+  margin: 0 0 1rem 0;
+  color: #333;
+  font-size: 1.125rem;
+}
+
+.setting-item {
+  display: flex;
+  justify-content: space-between;
+  align-items: center;
+  padding: 1rem 0;
+  border-bottom: 1px solid #f0f0f0;
+}
+
+.setting-info h4 {
+  margin: 0 0 0.25rem 0;
+  color: #333;
+  font-size: 1rem;
+}
+
+.setting-info p {
+  margin: 0;
+  color: #666;
+  font-size: 0.875rem;
+}
+
+.toggle {
+  position: relative;
+  display: inline-block;
+  width: 50px;
+  height: 24px;
+}
+
+.toggle input {
+  opacity: 0;
+  width: 0;
+  height: 0;
+}
+
+.slider {
+  position: absolute;
+  cursor: pointer;
+  top: 0;
+  left: 0;
+  right: 0;
+  bottom: 0;
+  background-color: #ccc;
+  transition: 0.2s;
+  border-radius: 24px;
+}
+
+.slider:before {
+  position: absolute;
+  content: "";
+  height: 18px;
+  width: 18px;
+  left: 3px;
+  bottom: 3px;
+  background-color: white;
+  transition: 0.2s;
+  border-radius: 50%;
+}
+
+input:checked + .slider {
+  background-color: #007bff;
+}
+
+input:checked + .slider:before {
+  transform: translateX(26px);
+}
+
+.select {
+  padding: 0.5rem;
+  border: 1px solid #ddd;
+  border-radius: 0.25rem;
+  background-color: white;
+  color: #333;
+}
+
+.settings-footer {
+  display: flex;
+  gap: 0.75rem;
+  justify-content: flex-end;
+  padding: 1.5rem 2rem;
+  border-top: 1px solid #e0e0e0;
+}
+</style>
+```
+
+### Custom Styled Sidebar
+
+```vue
+<script setup lang="ts">
+import { ref } from "vue";
+import { Sidebar, Button } from "@umbra-ui/core";
+
+const isCustomOpen = ref(false);
+</script>
+
+<template>
+  <div class="custom-sidebar">
+    <h3>Custom Styled Sidebar</h3>
+
+    <Button @click="isCustomOpen = true" class="custom-trigger">
+      Open Custom Sidebar
+    </Button>
+
+    <Sidebar
+      v-model="isCustomOpen"
+      side="right"
+      width="400px"
+      :animation-duration="0.6"
+      backdrop-style="dim"
+    >
+      <div class="custom-content">
+        <div class="custom-header">
+          <h2>Custom Sidebar</h2>
+          <p>This sidebar has custom styling and positioning.</p>
+        </div>
+
+        <div class="custom-body">
+          <div class="feature-list">
+            <div class="feature-item">
+              <div class="feature-icon">🎨</div>
+              <div class="feature-text">
+                <h4>Custom Colors</h4>
+                <p>Gradient backgrounds and custom styling</p>
+              </div>
+            </div>
+
+            <div class="feature-item">
+              <div class="feature-icon">⚡</div>
+              <div class="feature-text">
+                <h4>Right Side</h4>
+                <p>Slides in from the right side</p>
+              </div>
+            </div>
+
+            <div class="feature-item">
+              <div class="feature-icon">🔧</div>
+              <div class="feature-text">
+                <h4>Custom Size</h4>
+                <p>Fixed width and custom dimensions</p>
+              </div>
+            </div>
+          </div>
+        </div>
+
+        <div class="custom-footer">
+          <Button @click="isCustomOpen = false" class="custom-close">
+            Close
+          </Button>
+        </div>
+      </div>
+    </Sidebar>
+  </div>
+</template>
+
+<style module>
+.custom-sidebar {
+  padding: 2rem;
+  border: 1px solid #e0e0e0;
+  border-radius: 0.5rem;
+  max-width: 400px;
+}
+
+.custom-trigger {
+  background: linear-gradient(135deg, #667eea 0%, #764ba2 100%);
+  color: white;
+  border: none;
+  padding: 0.75rem 1.5rem;
+  border-radius: 0.5rem;
+  font-weight: 600;
+  transition: transform 0.2s;
+}
+
+.custom-trigger:hover {
+  transform: translateY(-2px);
+  box-shadow: 0 4px 12px rgba(102, 126, 234, 0.4);
+}
+
+.custom-content {
+  height: 100vh;
+  display: flex;
+  flex-direction: column;
+  background: linear-gradient(135deg, #f093fb 0%, #f5576c 100%);
+  color: white;
+}
+
+.custom-header {
+  padding: 2rem;
+  text-align: center;
+  background: rgba(255, 255, 255, 0.1);
+  backdrop-filter: blur(10px);
+}
+
+.custom-header h2 {
+  margin: 0 0 0.5rem 0;
+  font-size: 1.5rem;
+}
+
+.custom-header p {
+  margin: 0;
+  opacity: 0.9;
+}
+
+.custom-body {
+  flex: 1;
+  padding: 2rem;
+  overflow-y: auto;
+}
+
+.feature-list {
+  display: flex;
+  flex-direction: column;
+  gap: 1.5rem;
+}
+
+.feature-item {
+  display: flex;
+  align-items: flex-start;
+  gap: 1rem;
+  padding: 1rem;
+  background: rgba(255, 255, 255, 0.1);
+  border-radius: 0.5rem;
+  backdrop-filter: blur(5px);
+}
+
+.feature-icon {
+  font-size: 1.5rem;
+  width: 2rem;
+  text-align: center;
+}
+
+.feature-text h4 {
+  margin: 0 0 0.25rem 0;
+  font-size: 1rem;
+}
+
+.feature-text p {
+  margin: 0;
+  font-size: 0.875rem;
+  opacity: 0.8;
+}
+
+.custom-footer {
+  padding: 2rem;
+  background: rgba(255, 255, 255, 0.1);
+  backdrop-filter: blur(10px);
+  display: flex;
+  justify-content: center;
+}
+
+.custom-close {
+  background: rgba(255, 255, 255, 0.2);
+  color: white;
+  border: 1px solid rgba(255, 255, 255, 0.3);
+  padding: 0.75rem 2rem;
+  border-radius: 0.5rem;
+  font-weight: 600;
+  transition: all 0.2s;
+}
+
+.custom-close:hover {
+  background: rgba(255, 255, 255, 0.3);
+  transform: translateY(-1px);
+}
+
+/* Override sidebar CSS variables */
+:global(.custom-sidebar) {
+  --sidebar-bg: transparent;
+  --sidebar-backdrop-dim-bg: rgba(0, 0, 0, 0.8);
+}
+</style>
+```
+
+### Mobile Action Sheet
+
+```vue
+<script setup lang="ts">
+import { ref } from "vue";
+import { Sidebar, Button } from "@umbra-ui/core";
+
+const isActionSheetOpen = ref(false);
+
+const actions = [
+  { id: "edit", label: "Edit", icon: "✏️", color: "#007bff" },
+  { id: "share", label: "Share", icon: "📤", color: "#28a745" },
+  { id: "download", label: "Download", icon: "⬇️", color: "#6c757d" },
+  { id: "delete", label: "Delete", icon: "🗑️", color: "#dc3545" },
+];
+
+const handleAction = (actionId: string) => {
+  console.log("Action selected:", actionId);
+  isActionSheetOpen.value = false;
+};
+</script>
+
+<template>
+  <div class="action-sheet">
+    <h3>Mobile Action Sheet</h3>
+    <p>
+      This example shows a mobile-style action sheet using the bottom sidebar:
+    </p>
+
+    <Button @click="isActionSheetOpen = true">Show Actions</Button>
+
+    <Sidebar
+      v-model="isActionSheetOpen"
+      side="bottom"
+      height="auto"
+      min-height="200px"
+      max-height="400px"
+      :dismiss-on-backdrop="true"
+    >
+      <div class="action-sheet-content">
+        <div class="action-sheet-header">
+          <h3>Choose an Action</h3>
+          <p>Select what you'd like to do with this item</p>
+        </div>
+
+        <div class="action-list">
+          <button
+            v-for="action in actions"
+            :key="action.id"
+            class="action-item"
+            :style="{ '--action-color': action.color }"
+            @click="handleAction(action.id)"
+          >
+            <span class="action-icon">{{ action.icon }}</span>
+            <span class="action-label">{{ action.label }}</span>
+          </button>
+        </div>
+
+        <div class="action-sheet-footer">
+          <Button
+            @click="isActionSheetOpen = false"
+            variant="secondary"
+            class="cancel-btn"
+          >
+            Cancel
+          </Button>
+        </div>
+      </div>
+    </Sidebar>
+  </div>
+</template>
+
+<style module>
+.action-sheet {
+  padding: 2rem;
+  border: 1px solid #e0e0e0;
+  border-radius: 0.5rem;
+  max-width: 400px;
+}
+
+.action-sheet-content {
+  padding: 1rem;
+}
+
+.action-sheet-header {
+  text-align: center;
+  padding: 1rem 0 2rem;
+  border-bottom: 1px solid #e0e0e0;
+}
+
+.action-sheet-header h3 {
+  margin: 0 0 0.5rem 0;
+  color: #333;
+}
+
+.action-sheet-header p {
+  margin: 0;
+  color: #666;
+  font-size: 0.875rem;
+}
+
+.action-list {
+  padding: 1rem 0;
+}
+
+.action-item {
+  display: flex;
+  align-items: center;
+  gap: 1rem;
+  width: 100%;
+  padding: 1rem;
+  border: none;
+  background: none;
+  text-align: left;
+  cursor: pointer;
+  transition: background-color 0.2s;
+  border-radius: 0.5rem;
+  margin-bottom: 0.5rem;
+}
+
+.action-item:hover {
+  background-color: #f8f9fa;
+}
+
+.action-item:last-child {
+  margin-bottom: 0;
+}
+
+.action-icon {
+  font-size: 1.25rem;
+  width: 2rem;
+  text-align: center;
+}
+
+.action-label {
+  font-weight: 500;
+  color: var(--action-color, #333);
+}
+
+.action-sheet-footer {
+  padding: 1rem 0 0;
+  border-top: 1px solid #e0e0e0;
+  text-align: center;
+}
+
+.cancel-btn {
+  width: 100%;
+}
+</style>
+```
+
+## Technical Notes
+
+- Sidebar provides a comprehensive overlay system with smooth animations and flexible positioning
+- GSAP animations ensure smooth, performant transitions with hardware acceleration
+- Teleport usage ensures proper z-index layering and positioning outside component tree
+- Body scroll locking prevents background scrolling when sidebar is open
+- Safe area support handles mobile device notches and home indicators
+- Directional shadows adapt to sidebar position for better visual depth
+- Custom scrollbar styling provides better visual consistency
+- Backdrop blur effects create modern, iOS-like appearance
+- Keyboard navigation includes Escape key support for accessibility
+- TypeScript interfaces ensure type safety for all props and events
+- CSS custom properties enable easy theming and customization
+- Responsive design adapts to different screen sizes and orientations
+- Animation cleanup prevents memory leaks and ensures smooth performance