Description

@cmmv/ui is a modern UI component library built on Vue 3 and Tailwind CSS. It provides a comprehensive collection of pre-designed, fully customizable components that help you build beautiful, responsive, and accessible web applications faster.

Designed to integrate seamlessly with the CMMV architecture pattern, this library offers both flexibility and structure, allowing developers to create consistent user interfaces while maintaining the freedom to customize every aspect of their application's appearance.

Philosophy

The @cmmv/ui library is built on three core principles:

1. Contract-First Development

Following the CMMV pattern, our components are designed with clear contracts that define their behavior, props, events, and slots. This approach ensures consistency and predictability across your application.

2. Simplicity with Flexibility

We provide components that are simple to use out of the box, yet highly customizable for specific needs. Our goal is to reduce boilerplate while giving you complete control over your UI.

3. Performance and Accessibility

Every component is optimized for performance and follows accessibility best practices, ensuring your applications are fast and usable by everyone.

Key Benefits

• Seamless Integration: Works perfectly with Vue 3 and Tailwind CSS
• Dark Mode Support: Built-in dark mode for all components
• Responsive Design: Components are designed to work on all screen sizes
• Type Safety: Full TypeScript support with comprehensive types
• Consistent API: All components follow the same patterns and conventions
• Customizable: Easily override styles and behaviors to match your brand

Components

@cmmv/ui includes a growing collection of components:

Layout

• Cards, Containers, Grids
• Responsive navigation and menus

Form Elements

• Buttons, Inputs, Selects, Checkboxes
• Date pickers, Time pickers
• Form validation

Data Display

• Tables, Lists
• Badges, Tags, Progress indicators

Feedback

• Alerts, Notifications
• Modals, Dialogs
• Loaders, Skeletons

Navigation

• Tabs, Pagination
• Breadcrumbs, Steppers

Quick Start

Installation

# With pnpm
pnpm add @cmmv/ui vue@latest tailwindcss

# With npm
npm install @cmmv/ui vue@latest tailwindcss

# With yarn
yarn add @cmmv/ui vue@latest tailwindcss

Setup

1. Configure Tailwind CSS

# Install Tailwind CSS dependencies
pnpm install -D tailwindcss postcss autoprefixer
npx tailwindcss init -p

Update your tailwind.config.js:

/** @type {import('tailwindcss').Config} */
export default {
  content: [
    "./index.html",
    "./src/**/*.{vue,js,ts,jsx,tsx}",
    "./node_modules/@cmmv/ui/**/*.{vue,js,ts,jsx,tsx}" // Include @cmmv/ui components
  ],
  theme: {
    extend: {},
  },
  plugins: [],
}

Add Tailwind directives to your CSS file:

@tailwind base;
@tailwind components;
@tailwind utilities;

2. Configure Vue Plugin

// main.js or main.ts
import { createApp } from 'vue'
import UI from '@cmmv/ui'
import App from './App.vue'

const app = createApp(App)
app.use(UI)
app.mount('#app')

Usage Examples

Basic Button

<template>
  <c-button variant="primary" @click="handleClick">
    Click Me
  </c-button>
</template>

<script setup>
function handleClick() {
  console.log('Button clicked')
}
</script>

Form Input with Floating Label

<template>
  <c-input 
    v-model="username" 
    label="Username" 
    placeholder="Enter your username"
    :floatingLabel="true"
  />
</template>

<script setup>
import { ref } from 'vue'

const username = ref('')
</script>

Notifications

<template>
  <c-button @click="showNotification">
    Show Notification
  </c-button>
  
  <c-notification ref="notification" />
</template>

<script setup>
import { ref } from 'vue'

const notification = ref(null)

function showNotification() {
  notification.value.showNotification({
    newTitle: 'Success',
    newContent: 'Operation completed successfully!',
    newDuration: 3000
  })
}
</script>

Understanding CMMV Architecture

CMMV (Contract-Model-Model-View) is an architectural pattern designed to create highly modular, maintainable, and scalable frontend applications. The pattern separates concerns into four distinct layers:

1. Contract: Defines interfaces and data structures that connect different parts of the application
2. Domain Model: Manages business logic and validation rules independent of UI concerns
3. View Model: Transforms domain model data into a format suitable for presentation
4. View: Handles presentation logic and user interactions without containing business logic

The @cmmv/ui library primarily serves the View layer of CMMV applications, providing pre-built components that can be easily integrated with your View Models.

To learn more about CMMV architecture, check out the CMMV documentation.

Complete Documentation

For comprehensive documentation of all components, including:

• Detailed API references
• Interactive examples
• Theming guides
• Best practices

Visit our documentation site.

Contributing

We welcome contributions from the community! Whether it's adding new features, fixing bugs, or improving documentation, your help is appreciated.

1. Fork the repository
2. Create your feature branch: git checkout -b feature/amazing-feature
3. Commit your changes: git commit -m 'Add amazing feature'
4. Push to the branch: git push origin feature/amazing-feature
5. Open a Pull Request

Please read our Contributing Guide for more details.

Support

• 📚 Documentation
• 🐛 Report bugs