npm package: @rosadorito/vue-toast
Description: A lightweight, customizable toast notification library for Vue 3
Latest version: 0.0.6

# Vue Toast

A lightweight, customizable toast notification library for Vue 3.

## Features

- 🎨 **Multiple toast types**: Success, Error, Warning, Info, and Default
- 📍 **Flexible positioning**: 6 different positions (top/bottom-left/center/right)
- ⏱️ **Auto-dismiss**: Configurable duration with auto-removal
- 🎯 **Programmatic API**: Use via composable or global plugin
- ♿ **Accessible**: ARIA labels and proper semantic markup
- 📱 **Responsive**: Works on mobile and desktop
- 🎨 **Customizable**: Style with CSS custom properties
- 🧪 **TypeScript**: Full TypeScript support
- 🌳 **Tree-shakable**: Only import what you need

## Installation

```bash
npm install @rosadorito/vue-toast
# or
yarn add @rosadorito/vue-toast
# or
pnpm add @rosadorito/vue-toast
```

## Quick Start

### 1. Install the Plugin

```javascript
import { createApp } from 'vue'
import App from './App.vue'
import VueToast from '@rosadorito/vue-toast'

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

### 2. Add VueToast Component Once

Add `<VueToast />` once in your main app component:

```vue
<!-- App.vue -->
<template>
  <div id="app">
    <VueToast /> <!-- Add this once -->
    <router-view />
    <!-- or your main content -->
  </div>
</template>
```

### 3. Use Toasts Anywhere

Now you can use toasts anywhere in your app:

**Using Composables (Recommended):**
```vue
<template>
  <button @click="showToast">Show Toast</button>
</template>

<script setup>
import { useToast } from '@rosadorito/vue-toast'

const toast = useToast()

const showToast = () => {
  toast.success('Operation completed successfully!')
  
  // With options
  toast.error('Something went wrong!', {
    duration: 3000,
    position: 'top-center',
  })
}
</script>
```

**Using Global $toast (Options API):**
```vue
<template>
  <button @click="showToast">Show Toast</button>
</template>

<script>
export default {
  methods: {
    showToast() {
      this.$toast.success('Operation completed!')
    }
  }
}
</script>
```

That's it! No manual rendering, no template logic, no event handling required.

## API Reference

### Toast Options

| Option | Type | Default | Description |
|--------|------|---------|-------------|
| `message` | `string` | **Required** | The message to display |
| `type` | `'success' \| 'error' \| 'warning' \| 'info' \| 'default'` | `'default'` | Toast type |
| `duration` | `number` | `5000` | Duration in milliseconds (0 for no auto-dismiss) |
| `position` | `ToastPosition` | `'top-right'` | Position on screen |
| `dismissible` | `boolean` | `true` | Whether to show close button |
| `id` | `string` | Auto-generated | Unique identifier |
| `onClose` | `() => void` | - | Callback when toast closes |
| `onClick` | `() => void` | - | Callback when toast is clicked |

### Toast Positions

```typescript
type ToastPosition =
  | 'top-left'
  | 'top-center'
  | 'top-right'
  | 'bottom-left'
  | 'bottom-center'
  | 'bottom-right'
```

### useToast() Composables

```typescript
const {
  // State
  toasts,           // Array of all toasts
  groupedToasts,    // Toasts grouped by position
  
  // Methods
  addToast,         // Add a toast with custom options
  removeToast,      // Remove a toast by id
  clearToasts,      // Remove all toasts
  
  // Convenience methods
  success,          // Add success toast
  error,            // Add error toast
  warning,          // Add warning toast
  info,             // Add info toast
} = useToast(defaultPosition?: ToastPosition)
```

### Global Plugin API

When installed as a plugin, `$toast` is available on Vue instances:

```typescript
// In Options API
this.$toast.success('Message')

// In Composition API setup()
import { getCurrentInstance } from 'vue'

const instance = getCurrentInstance()
instance?.proxy?.$toast.success('Message')
```

Methods available on `$toast`:
- `success(message, options?)`
- `error(message, options?)`
- `warning(message, options?)`
- `info(message, options?)`
- `add(options)`

## Styling

### CSS Custom Properties

You can customize the appearance using CSS custom properties:

```css
:root {
  --vue-toast-border-radius: 6px;
  --vue-toast-padding: 12px 16px;
  --vue-toast-font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, sans-serif;
  --vue-toast-font-size: 14px;
  --vue-toast-line-height: 1.4;
  --vue-toast-box-shadow: 0 4px 12px rgba(0, 0, 0, 0.15);
}

/* Type-specific colors */
.vue-toast--success {
  --vue-toast-border-color: #10b981;
  --vue-toast-bg-color: #f0fdf4;
  --vue-toast-text-color: #065f46;
}

.vue-toast--error {
  --vue-toast-border-color: #ef4444;
  --vue-toast-bg-color: #fef2f2;
  --vue-toast-text-color: #991b1b;
}
```

### Overriding Styles

You can override the default styles by targeting the component classes:

```css
.vue-toast {
  /* Your custom styles */
}

.vue-toast__close {
  /* Custom close button styles */
}
```

## TypeScript

Full TypeScript support is included. Import types as needed:

```typescript
import type { ToastOptions, ToastPosition, ToastType } from '@rosadorito/vue-toast'
```

## Examples

### Multiple Toasts with Different Positions

```vue
<template>
  <div>
    <button @click="addTopLeft">Top Left</button>
    <button @click="addBottomCenter">Bottom Center</button>
    
    <div v-for="(toasts, position) in groupedToasts" :key="position">
      <VueToast
        v-for="(toast, index) in toasts"
        :key="toast.id"
        :toast="toast"
        :index="index"
        :total="toasts.length"
        @close="removeToast(toast.id)"
      />
    </div>
  </div>
</template>

<script setup>
import { useToast } from '@rosadorito/vue-toast'

const { addToast, removeToast, groupedToasts } = useToast()

const addTopLeft = () => {
  addToast({
    message: 'Top left notification',
    type: 'info',
    position: 'top-left',
    duration: 3000,
  })
}

const addBottomCenter = () => {
  addToast({
    message: 'Bottom center warning',
    type: 'warning',
    position: 'bottom-center',
    duration: 5000,
  })
}
</script>
```

### Toast with Callbacks

```javascript
const showToastWithCallback = () => {
  addToast({
    message: 'Click me!',
    type: 'success',
    onClick: () => {
      console.log('Toast clicked!')
      // Navigate or perform action
    },
    onClose: () => {
      console.log('Toast closed')
      // Cleanup or tracking
    },
  })
}
```

## Browser Support

- Chrome 60+
- Firefox 60+
- Safari 12+
- Edge 79+

## License

MIT