mms-component-lib/README.md

A professional, production-ready Vue 3 component library built with modern web standards.

# 🎯 MMS Component Library

A professional, production-ready Vue 3 component library built with modern web standards.

## 🏆 **Key Highlights**
- **🎨 Beautiful UI Components** - Button, DataTable, Carousel, Sidebar + 9 more components
- **🔧 Developer Experience** - Full TypeScript, auto-imports, comprehensive Storybook docs  
- **⚡ Performance Focused** - Tree-shaking, CSS variables, optimized bundle size
- **🎭 Professional Design System** - Built on shadcn/ui with Tailwind CSS v4
- **� Production Ready** - Responsive, accessible, and battle-tested patterns

## 🎪 **Live Demo**
- **[Storybook Documentation](http://localhost:6006)** - Interactive component playground
- **[Demo App](http://localhost:5173)** - Live examples in action

✨ **What Makes It Special:**
- 🔄 Smart auto-import system for seamless development
- 🎨 Consistent design system with CSS custom properties  
- 📖 Interactive documentation with copy-paste code examples
- 🛡️ Full TypeScript support with perfect IntelliSense
- ⚡ Tree-shaking friendly - import only what you need
- 🧪 Accessibility-first approach with ARIA support

## 🧩 **Component Showcase**

| Component | Description | Key Features |
|-----------|-------------|--------------|
| **Button** | Versatile action component | 5 variants × 5 colors = 25 combinations |
| **DataTable** | Powerful data display | Sorting, filtering, pagination ready |
| **Carousel** | Image/content slider | Touch-friendly, responsive, auto-play |
| **Sidebar** | Navigation component | Collapsible, floating, keyboard shortcuts |
| **+ 9 More** | Input, Sheet, Tooltip, etc. | Complete UI foundation |

## 📦 Installation

```bash
npm install mms-component-lib
```

## 🚀 Usage

### Global Import (Recommended)
```javascript
import { createApp } from 'vue'
import MMSComponentLib from 'mms-component-lib'
import 'mms-component-lib/style.css'  // or 'mms-component-lib/dist/style.css'

const app = createApp(App)
app.use(MMSComponentLib)
```

### Tree-shaking Import
```javascript
import { BaseButton, BaseCard } from 'mms-component-lib'
import 'mms-component-lib/style.css'

// In your component
export default {
  components: { BaseButton, BaseCard }
}
```

### TypeScript Support
```typescript
import { BaseButton, type ButtonProps } from 'mms-component-lib'

// Full IntelliSense support for props
const buttonProps: ButtonProps = {
  variant: 'primary',  // IntelliSense will show available options
  size: 'md',
  disabled: false
}
```

### Individual Import
```vue
<template>
  <BaseButton variant="primary" @click="handleClick">
    Click me!
  </BaseButton>
</template>

<script setup lang="ts">
import { BaseButton } from 'mms-component-lib'
import 'mms-component-lib/dist/style.css'
</script>
```

### Using with Tailwind CSS v3 apps (isolation)

This library ships Tailwind CSS v4-based styles, but they are fully isolated under a wrapper to avoid conflicts with host apps using Tailwind v3.

Minimal setup in your app:

```vue
<template>
  <!-- Wrap any area that uses MMS components -->
  <MmsProvider>
    <YourFeatureUsingMmsComponents />
  </MmsProvider>
  
  <!-- Rest of your app (Tailwind v3) remains unaffected -->
  <OtherAppParts />
  
</template>

<script setup lang="ts">
import { MmsProvider } from 'mms-component-lib'
// If your bundler doesn't auto-inject CSS side-effects from the package, import it explicitly:
import 'mms-component-lib/style.css'
</script>
```

Notes:
- All MMS styles are scoped to the `.mms-ui` wrapper inside `<MmsProvider>` so Tailwind v3 and v4 classes won't clash.
- For dark mode, prefer `<MmsProvider class="dark">` to ensure dark styles are applied within the isolated scope.
- If you prefer not to use the component wrapper, you can add a plain wrapper element with `class="mms-ui"` yourself.

## 🧩 Available Components

- **BaseButton** - Flexible button with multiple variants (primary, secondary, outline, ghost)

## 🛠️ Development

```bash
# Development
npm run dev        # Start dev server
npm run storybook  # Component documentation

# Build
npm run build      # Build for production
```

### Component Management
```bash
npm run generate:component <ComponentName>   # Create new component
npm run delete:component <ComponentName>     # Delete component (with confirmation)  
npm run delete:component <ComponentName> -f  # Force delete (no confirmation)
npm run list:components                      # List all components with status
```

```

## 🛠️ Development

### Creating New Components
```bash
# Auto-generates Vue component, CSS, and Storybook story
npm run generate:component MyNewComponent

# Example: Create BaseAlert component
npm run generate:component BaseAlert
```

### Development with Auto-Import
```bash
# Run dev server with auto-import watching
npm run dev:watch

# Or run separately
npm run dev           # Start Vite dev server
npm run watch:imports # Watch for component changes
```

## 📁 Project Structure

```
src/components/
├── BaseButton/
│   ├── BaseButton.vue      # Vue component with TypeScript
│   ├── BaseButton.css      # Component-specific Tailwind styles
│   └── BaseButton.stories.ts # Storybook documentation
├── BaseCard/
│   ├── BaseCard.vue
│   ├── BaseCard.css
│   └── BaseCard.stories.ts
└── index.ts               # Auto-generated imports and exports
```

Each component lives in its own directory with all related files grouped together. The `index.ts` file is automatically maintained by the build scripts.

## 🔄 Release Process

This project uses [Changeset](https://github.com/changesets/changesets) with **development** and **production** versioning:

### 🚀 **Quick Release (Interactive)**
```bash
npm run workflow          # Interactive workflow selector
npm run workflow:dev      # Development release (beta)
npm run workflow:prod     # Production release (stable)
```

### 📋 **Manual Workflows**

**Development Release (Pre-release)**
```bash
npm run changeset                    # Create changeset
npm run changeset:pre:enter beta     # Enter pre-release mode
npm run changeset:version            # Version to beta (e.g., 1.0.0-beta.1)
npm run release:beta                 # Publish with @beta tag
```

**Production Release (Stable)**
```bash
npm run changeset                    # Create changeset
npm run changeset:pre:exit           # Exit pre-release mode (if active)
npm run changeset:version            # Version to stable (e.g., 1.0.0)
npm run release:prod                 # Publish with @latest tag
```

### 📦 **Version Types**
- **Development**: `1.0.0-beta.1`, `1.0.0-alpha.1` (install with `@beta` or `@alpha`)
- **Production**: `1.0.0`, `1.0.1`, `1.1.0` (install with `@latest` or no tag)

## 📚 **Documentation**

- **[DEVELOPMENT-GUIDE.md](DEVELOPMENT-GUIDE.md)** - Complete development, versioning, and collaboration guide
- **[CHANGELOG.md](CHANGELOG.md)** - Auto-generated changelog

## 📄 License

MIT License - see [LICENSE](LICENSE) file for details.