Init Repo

2026-02-28 03:22:04 +08:00
commit de59b57ee7
883 changed files with 156857 additions and 0 deletions
@@ -0,0 +1,95 @@
+# Collapsible Sidebar Usage
+
+The VFX Project Management System features a collapsible sidebar that can be toggled between expanded and icon-only modes.
+
+## Features
+
+### 1. Toggle Methods
+- **Header Button**: Click the hamburger menu button (☰) in the top-left corner
+- **Keyboard Shortcut**: Press `Ctrl+B` (Windows/Linux) or `Cmd+B` (Mac)
+
+### 2. Collapsed State
+When collapsed, the sidebar:
+- Shows only icons for navigation items
+- Displays tooltips on hover to show full item names
+- Maintains all functionality while saving screen space
+- Automatically adjusts width to icon size (3rem)
+
+### 3. Expanded State
+When expanded, the sidebar:
+- Shows full navigation labels and descriptions
+- Displays project names and user information
+- Uses full width (16rem) for better readability
+
+### 4. Responsive Behavior
+- **Desktop**: Sidebar can be collapsed to icons or fully expanded
+- **Mobile**: Sidebar becomes an overlay sheet that can be opened/closed
+- **State Persistence**: The sidebar remembers its state using cookies
+
+## Implementation Details
+
+### CSS Classes Used
+- `group-data-[collapsible=icon]:hidden` - Hides text when collapsed
+- Tooltips are conditionally shown only when sidebar is collapsed
+- Smooth transitions with `duration-200` for width changes
+
+### Components Involved
+- `SidebarProvider` - Manages global sidebar state
+- `SidebarTrigger` - Toggle button in header
+- `AppSidebar` - Main sidebar component with collapse-aware styling
+- `useSidebar()` - Composable for accessing sidebar state
+
+### State Management
+- Uses `useSidebar()` composable to access collapse state
+- State is persisted in cookies with 7-day expiration
+- Mobile detection automatically switches to overlay mode
+
+## User Experience
+
+### Visual Feedback
+- Icons remain visible when collapsed for easy recognition
+- Tooltips provide context without cluttering the interface
+- Smooth animations make transitions feel natural
+- Active route highlighting works in both states
+
+### Accessibility
+- Keyboard shortcut for power users
+- Screen reader support with proper ARIA labels
+- Focus management maintained during state changes
+- Tooltips provide alternative text access
+
+## Customization
+
+### Adding New Navigation Items
+```typescript
+const navigationItems = computed(() => [
+  { 
+    title: 'New Feature', 
+    url: '/new-feature', 
+    icon: NewIcon 
+  }
+])
+```
+
+### Modifying Collapse Behavior
+The sidebar uses the `collapsible="icon"` prop by default. Other options:
+- `collapsible="offcanvas"` - Slides completely off-screen
+- `collapsible="none"` - Disables collapse functionality
+
+### Styling Collapsed State
+Use the `group-data-[collapsible=icon]:` prefix for collapse-specific styles:
+```css
+.my-element {
+  @apply group-data-[collapsible=icon]:hidden;
+}
+```
+
+## Best Practices
+
+1. **Icon Selection**: Use clear, recognizable icons for navigation items
+2. **Tooltip Content**: Keep tooltip text concise but descriptive
+3. **State Awareness**: Check `isCollapsed` computed property for conditional rendering
+4. **Performance**: Tooltips are only rendered when needed (collapsed state)
+5. **Consistency**: All sidebar items should follow the same collapse pattern
+
+The collapsible sidebar provides an optimal balance between functionality and screen real estate, adapting to user preferences while maintaining full feature access.