npm package: @sena-services/vue-left-sidebar
Description: Prop-driven Left Sidebar for Vue 3, registry-friendly.
Latest version: 1.0.0

# @sena-services/vue-left-sidebar

A highly customizable, prop-driven left sidebar component for Vue 3 applications. Features collapsible sections, hover expansion, custom icons, and full theming support.

## ✨ Features

- 🎨 **Fully Customizable** - Colors, fonts, spacing, and branding via props
- 📱 **Responsive Design** - Works on desktop and mobile
- 🔄 **Multiple Modes** - Auto, collapsed, or expanded states
- 🎯 **Icon Integration** - Support for custom icon components
- 📊 **Navigation Groups** - Organized sections with collapsible items
- ⚡ **Vue 3 Composition API** - Modern Vue.js architecture
- 🎭 **Hover Effects** - Smooth animations and transitions
- 📦 **Tree Shakable** - Import only what you need

## 📦 Installation

```bash
npm install @sena-services/vue-left-sidebar
# or
yarn add @sena-services/vue-left-sidebar
```

## 🚀 Quick Start

### Basic Usage

```vue
<template>
  <LeftSidebar
    :navigation-groups="navigationGroups"
    :top-logo-image="'/path/to/logo.png'"
    :brand-name="'Your App'"
    :brand-subtitle="'Dashboard'"
    @component-event="handleNavigation"
  />
</template>

<script setup>
import { ref } from 'vue'
import { LeftSidebar } from '@sena-services/vue-left-sidebar'

const navigationGroups = ref([
  {
    groupId: 'main',
    groupLabel: 'MAIN',
    items: [
      { label: 'Dashboard', to: '/dashboard', icon: 'dashboard' },
      { label: 'Settings', to: '/settings', icon: 'cog' }
    ]
  }
])

const handleNavigation = (event) => {
  console.log('Navigation:', event)
  // Handle navigation logic
}
</script>
```

### With Custom Styling

```vue
<template>
  <LeftSidebar
    :navigation-groups="navigationGroups"
    :top-logo-image="logoUrl"
    :brand-name="'Sentra'"
    :brand-subtitle="'Administrator'"
    :primary-color="'#3b82f6'"
    :hover-color="'#efe7dc'"
    :sidebar-background-color="'#ffffff'"
    :font-family="'Inter, sans-serif'"
    :sidebar-mode="'auto'"
    @component-event="handleNavigation"
  />
</template>
```

## 📋 Props

### Required Props

| Prop | Type | Description |
|------|------|-------------|
| `navigationGroups` | `Array` | Array of navigation group objects |
| `topLogoImage` | `String` | URL/path to the logo image |

### Optional Props

| Prop | Type | Default | Description |
|------|------|---------|-------------|
| `brandName` | `String` | `'Sentra'` | Brand name displayed next to logo |
| `brandSubtitle` | `String` | `'Administrator'` | Subtitle displayed below brand name |
| `primaryColor` | `String` | `'#3b82f6'` | Primary color for active states and accents |
| `defaultTextColor` | `String` | `'#6c757d'` | Default text color |
| `activeTextColor` | `String` | `'#ffffff'` | Text color for active/selected items |
| `brandNameColor` | `String` | `'#212529'` | Color for the brand name |
| `sidebarBackgroundColor` | `String` | `'#ffffff'` | Background color of the sidebar |
| `hoverColor` | `String` | `'#efe7dc'` | Background color on hover |
| `fontFamily` | `String` | `'Inter, system-ui, sans-serif'` | Font family |
| `fontSize` | `String` | `'14px'` | Base font size |
| `fontWeight` | `String` | `'400'` | Base font weight |
| `sidebarMode` | `String` | `'auto'` | Sidebar behavior: `'auto'`, `'collapsed'`, `'expanded'` |
| `initialCollapsed` | `Boolean` | `true` | Initial collapsed state for auto mode |
| `autoExpandDelay` | `Number` | `200` | Delay before auto-expansion on hover (ms) |

### UCC Standard Props

| Prop | Type | Default | Description |
|------|------|---------|-------------|
| `children` | `Array` | `[]` | Child components (UCC standard) |
| `uid` | `String` | `null` | Unique identifier |
| `path` | `String` | `null` | Component path |
| `addStyles` | `String` | `''` | Additional CSS classes |
| `overrideStyles` | `Object` | `{}` | Inline style overrides |

## 📊 Navigation Groups Structure

```javascript
const navigationGroups = [
  {
    groupId: 'general',        // Unique identifier
    groupLabel: 'GENERAL',     // Display name
    items: [
      {
        label: 'Dashboard',     // Display text
        to: '/dashboard',       // Route path
        icon: 'dashboard'       // Icon identifier
      },
      // ... more items
    ]
  },
  // ... more groups
]
```

## 🎨 Sidebar Modes

### Auto Mode (Default)
- Collapsed by default
- Expands on hover
- Auto-collapses when mouse leaves

### Collapsed Mode
- Always collapsed
- Shows only icons
- No hover expansion

### Expanded Mode
- Always expanded
- Shows icons and text
- Fixed width

## 🎭 Events

### `component-event`

Emitted when navigation items are clicked or sidebar state changes.

```javascript
// Event structure
{
  eventName: 'navigationLinkClick',
  payload: {
    link: { label: 'Dashboard', to: '/dashboard', icon: 'dashboard' },
    groupId: 'general',
    index: 0,
    timestamp: 1640995200000
  },
  sourcePath: 'sidebar.navigation'
}
```

## 🎨 Styling

The component uses CSS custom properties (v-bind) for dynamic styling. All colors and fonts can be customized via props.

### Custom CSS Classes

You can add custom styles using the `addStyles` prop:

```vue
<LeftSidebar
  :navigation-groups="groups"
  add-styles="custom-sidebar shadow-lg"
/>
```

## 🔧 Advanced Usage

### With Vue Router

```vue
<script setup>
import { useRouter } from 'vue-router'

const router = useRouter()

const handleNavigation = (event) => {
  if (event.eventName === 'navigationLinkClick') {
    router.push(event.payload.link.to)
  }
}
</script>
```

### With Custom Icons

The component supports custom icon components. Map your icon names in the navigation groups:

```javascript
const navigationGroups = [
  {
    groupId: 'main',
    groupLabel: 'MAIN',
    items: [
      { label: 'Dashboard', to: '/dashboard', icon: 'custom-dashboard-icon' },
      { label: 'Users', to: '/users', icon: 'custom-users-icon' }
    ]
  }
]
```

## 📱 Responsive Design

The sidebar automatically adapts to different screen sizes:

- **Desktop**: Full functionality with hover effects
- **Mobile**: Optimized spacing and touch-friendly interactions

## 🛠️ Development

```bash
# Clone the repository
git clone https://github.com/your-org/vue-left-sidebar.git

# Install dependencies
npm install

# Start development server
npm run dev

# Build for production
npm run build
```

## 📄 License

MIT License - see [LICENSE](LICENSE) file for details.

## 🤝 Contributing

Contributions are welcome! Please read our contributing guidelines and submit pull requests.

## 📞 Support

For issues and questions, please use the [GitHub Issues](https://github.com/your-org/vue-left-sidebar/issues) page.

---

Made with ❤️ by [Sena Services](https://sena-services.com)