npm package: @jotnar/m-card
Description: A reusable Vue 3 card component with Tailwind CSS support
Author: Jotnar
Latest version: 0.1.0

# @jotnar/m-card

A versatile Vue 3 card component with Tailwind CSS 4 styling and Font Awesome support. Create customizable cards with images, avatars, icons, buttons, and flexible content layouts effortlessly!

## 📦 Installation

Install the package via npm:

```bash

npm  i  @jotnar/m-card@latest

```

**Prerequisites:** Ensure your project has Vue 3 (version 3.4.0 or higher), Tailwind CSS 4, and Font Awesome set up, as this component relies on Tailwind CSS classes for styling, Vue 3 for functionality, and Font Awesome for icons.

## 🧑‍💻 Usage

You can use the **m-card** component in your Vue 3 application either by registering it globally or locally in specific components.

### 🌐 Global Registration

Register the **m-card** component globally in your Vue app:

1.  Import the component in your main JavaScript file (e.g., main.js):

```javascript
import { createApp } from 'vue'
import App from './App.vue'
import { MCard } from '@jotnar/m-card'

const app = createApp(App)
app.component('m-card', MCard)
app.mount('#app')
```

2.  Import the styles in your main JavaScript file (since the component includes styles in <script setup>):

```javascript
import '@jotnar/m-card/style'
import 'tailwindcss'
```

Once these steps are complete, you can use the <m-card> component anywhere in your app.

### 📦 Local Registration

Import and use the component in specific components:

```html
<template>
  <m-card title="Welcome" description="This is a card!" primary-btn="Get Started" />
</template>

<script setup>
  import { MCard } from '@jotnar/m-card'
</script>
```

## 🎛️ Props

The **m-card** component offers a range of props to customize its appearance and behavior:

| Prop         | Type    | Default             | Description                                                                        |
| ------------ | ------- | ------------------- | ---------------------------------------------------------------------------------- |
| elevation    | String  | 'shadow'            | Elevation style: shadow, shadow-md, shadow-lg, shadow-none.                        |
| rounded      | String  | 'rounded-lg'        | Rounding style: rounded, rounded-lg, rounded-xl, rounded-none.                     |
| bordered     | Boolean | false               | Adds a border to the card.                                                         |
| title        | String  | ''                  | The main title displayed in the card header.                                       |
| subtitle     | String  | ''                  | A smaller subtitle displayed below the title.                                      |
| description  | String  | ''                  | The main content text of the card.                                                 |
| primaryBtn   | String  | ''                  | Label for the primary button (uses @jotnar/m-btn).                                 |
| secondaryBtn | String  | ''                  | Label for the secondary button (uses @jotnar/m-btn, text variant).                 |
| image        | String  | ''                  | URL for the card’s top image.                                                      |
| avatar       | String  | ''                  | Name or URL for the avatar (uses @jotnar/m-avatar).                                |
| icon         | String  | ''                  | Font Awesome icon class (e.g., fa-solid fa-star).                                  |
| imageSize    | String  | 'h-48'              | Image height: h-32, h-48, h-64, h-auto.                                            |
| avatarImg    | String  | ''                  | URL for the avatar image (overrides avatar name).                                  |
| iconClass    | String  | 'card-icon-default' | CSS class for the icon (default: text-4xl p-2 text-primary-400).                   |
| avatarColor  | String  | 'primary'           | Avatar color: primary, secondary, tertiary, accent, info, success, warning, error. |
| avatarStatus | String  | 'online'            | Avatar status: online, offline, away, busy, no disturb, null.                      |

## 🎉 Events

| Event           | Description                                   |
| --------------- | --------------------------------------------- |
| click:primary   | Emitted when the primary button is clicked.   |
| click:secondary | Emitted when the secondary button is clicked. |

## ✨ Examples

```html
<template>
  <div class="flex gap-4 flex-wrap">
    <!-- Basic Card -->
    <m-card
      title="Welcome"
      subtitle="Introduction"
      description="This is a basic card with buttons."
      primary-btn="Get Started"
      secondary-btn="Learn More"
      @click:primary="onPrimaryClick"
      @click:secondary="onSecondaryClick"
    />

    <!-- Card with Image -->
    <m-card
      title="Featured"
      image="https://example.com/image.jpg"
      image-size="h-32"
      description="A card with a top image."
      primary-btn="View Details"
    />

    <!-- Card with Avatar and Icon -->
    <m-card
      title="User Profile"
      avatar="John Doe"
      avatar-color="success"
      avatar-status="online"
      icon="fa-solid fa-user"
      description="A card with an avatar and icon."
    />

    <!-- Card with Slots -->
    <m-card elevation="shadow-lg" rounded="rounded-xl">
      <template #header>
        <h2 class="text-2xl font-bold">Custom Header</h2>
      </template>
      <template #body>
        <p>This is a custom body content.</p>
      </template>
      <template #footer>
        <button class="px-4 py-2 bg-blue-600 text-white rounded">Custom Action</button>
      </template>
    </m-card>
  </div>
</template>

<script setup>
  import { MCard } from '@jotnar/m-card'

  const onPrimaryClick = () => console.log('Primary button clicked')
  const onSecondaryClick = () => console.log('Secondary button clicked')
</script>
```

## ℹ️ Notes

- **Custom Classes**:  
  If a custom class prop is provided (e.g., class="bg-blue-500 text-white"), it will override default styles, allowing full customization.
- **Icon Support**:  
  Icons require **Font Awesome** to be set up in your project. Use the format fa-solid fa-icon-name (e.g., fa-solid fa-star).
- **Accessibility**:  
  The card includes aria-label attributes for the container, avatar, icon, and buttons to ensure accessibility for screen readers. Buttons are keyboard-accessible.
- **Dependencies**:  
  The component uses @jotnar/m-avatar for avatars and @jotnar/m-btn for buttons. Ensure these are installed if using avatar, primaryBtn, or secondaryBtn props.
- **Styling**:  
  Styles are imported via @jotnar/m-card/style in the component’s <script setup>, aligning with the library’s conventions.

## 🔨 Under Construction

The homepage for this project is currently under construction. In the meantime, you can find the source code and report issues on GitHub:

- GitHub Repository
- Report Issues

## ⚖️ License

MIT

## 👤 Author

Jotnar