feather-toast-vue 1.0.0

package/.vscode/extensions.json

@@ -0,0 +1,3 @@
+{
+  "recommendations": ["Vue.volar"]
+}

package/README.md

@@ -0,0 +1,286 @@
+# 🪶 Feather Toast
+
+A lightweight, smooth Vue 3 toast notification plugin with minimalist design and buttery animations.
+
+---
+
+## ✨ Features
+
+| Feature | Description |
+|---------|-------------|
+| 🎨 **6 Variants** | `default` · `success` · `error` · `warning` · `info` · `loading` |
+| 📍 **6 Positions** | `top-right` · `top-left` · `top-center` · `bottom-right` · `bottom-left` · `bottom-center` |
+| 🌊 **Smooth Animations** | Spring-based slide + fade + scale with `cubic-bezier(0.16, 1, 0.3, 1)` |
+| 👆 **Swipe to Dismiss** | Horizontal swipe gesture with snap-back |
+| ⏸️ **Hover Pause** | Auto-dismiss timer pauses accurately on hover |
+| 🔄 **Promise API** | `toast.promise()` — loading → success / error |
+| ⚡ **Action Button** | Optional inline action on any toast |
+| 🧩 **Vue Plugin** | One-line install with `app.use(ToastPlugin)` |
+| 📦 **Zero Dependencies** | Only Vue 3 — no Tailwind, no UI library |
+| 🔒 **TypeScript** | Fully typed API |
+| ♿ **Accessible** | `aria-live`, `role="alert"`, `prefers-reduced-motion` support |
+
+---
+
+## 📦 Installation
+
+```bash
+npm install feather-toast
+```
+
+### Setup
+
+```ts
+// main.ts
+import { createApp } from 'vue'
+import App from './App.vue'
+import { ToastPlugin } from 'feather-toast/plugins/toast'
+import 'feather-toast/assets/toast.css'
+
+const app = createApp(App)
+app.use(ToastPlugin)
+app.mount('#app')
+```
+
+Add `<ToastContainer />` once to your root layout:
+
+```vue
+<!-- App.vue -->
+<template>
+  <router-view />
+  <ToastContainer />
+</template>
+```
+
+---
+
+## 🚀 Usage
+
+### Basic
+
+```ts
+import { useToast } from 'feather-toast/composables/useToast'
+
+const { toast } = useToast()
+
+toast({
+  title: 'Event Created',
+  description: 'Your event has been scheduled.',
+})
+```
+
+### Variants
+
+```ts
+toast.success({ title: 'Saved',    description: 'Changes applied.' })
+toast.error({   title: 'Error',    description: 'Something went wrong.' })
+toast.warning({ title: 'Warning',  description: 'Disk space is low.' })
+toast.info({    title: 'Info',     description: 'Version 2.4 is available.' })
+toast.loading({ title: 'Uploading...', description: 'Please wait.' })
+```
+
+### Custom Position
+
+```ts
+toast.success({
+  title: 'Saved',
+  position: 'top-center', // default: 'bottom-right'
+})
+```
+
+### Promise API
+
+Automatically transitions `loading → success` or `loading → error`:
+
+```ts
+toast.promise(
+  fetch('/api/projects', { method: 'POST' }),
+  {
+    loading: {
+      title: 'Creating project...',
+      description: 'Setting up your workspace.',
+    },
+    success: (data) => ({
+      title: `"${data.name}" created`,
+      description: 'Your project is ready.',
+    }),
+    error: (err) => ({
+      title: 'Failed to create project',
+      description: err instanceof Error ? err.message : 'Unknown error.',
+    }),
+  }
+)
+```
+
+### Action Button
+
+```ts
+toast({
+  title: 'Message archived',
+  description: 'Moved to archive.',
+  action: {
+    label: 'Undo',
+    onClick: () => {
+      toast.success({ title: 'Restored', description: 'Message moved back to inbox.' })
+    },
+  },
+})
+```
+
+### Dismiss
+
+```ts
+// Dismiss by ID
+const id = toast.loading({ title: 'Working...' })
+toast.dismiss(id)
+
+// Dismiss all
+toast.dismissAll()
+```
+
+---
+
+## 📐 API Reference
+
+### `useToast()`
+
+```ts
+const { toast, toasts, dismiss, dismissAll } = useToast()
+```
+
+| Property | Type | Description |
+|----------|------|-------------|
+| `toast(options)` | `(options: ToastOptions) => string` | Show a default toast, returns its ID |
+| `toast.success(options)` | `Function` | Success variant |
+| `toast.error(options)` | `Function` | Error variant |
+| `toast.warning(options)` | `Function` | Warning variant |
+| `toast.info(options)` | `Function` | Info variant |
+| `toast.loading(options)` | `Function` | Loading variant — no auto-dismiss |
+| `toast.promise(promise, opts)` | `Function` | Promise-based toast flow |
+| `toast.dismiss(id)` | `Function` | Dismiss a specific toast by ID |
+| `toast.dismissAll()` | `Function` | Dismiss all active toasts |
+| `toasts` | `Ref<Toast[]>` | Reactive list of all active toasts |
+
+---
+
+### `ToastOptions`
+
+```ts
+interface ToastOptions {
+  title?:       string
+  description?: string
+  variant?:     'default' | 'success' | 'error' | 'warning' | 'info' | 'loading'
+  position?:    'top-right' | 'top-left' | 'top-center'
+                | 'bottom-right' | 'bottom-left' | 'bottom-center'
+  duration?:    number      // ms · default: 5000 · loading: Infinity
+  dismissible?: boolean     // default: true (false for loading)
+  action?: {
+    label:   string
+    onClick: () => void
+  }
+}
+```
+
+---
+
+### Positions
+
+```
+┌──────────┬────────────┬───────────┐
+│ top-left │ top-center │ top-right │
+│          │            │           │
+│          │            │           │
+│ bot-left │ bot-center │ bot-right │
+└──────────┴────────────┴───────────┘
+```
+
+---
+
+## 🎨 Design System
+
+### Color Tokens
+
+| Token | Value | Usage |
+|-------|-------|-------|
+| `--toast-bg` | `#ffffff` | Card background |
+| `--toast-border` | `#e4e4e7` | Card border |
+| `--toast-text` | `#18181b` | Title text |
+| `--toast-text-muted` | `#71717a` | Description text |
+| `--toast-shadow` | `0 2px 8px rgba(0,0,0,0.06)` | Card elevation |
+| `--toast-radius` | `10px` | Card border radius |
+| `--toast-width` | `360px` | Card width |
+
+### Icon Accent Colors
+
+| Variant | Color | Hex |
+|---------|-------|-----|
+| Success | 🟢 Green | `#16a34a` |
+| Error | 🔴 Red | `#dc2626` |
+| Warning | 🟡 Amber | `#d97706` |
+| Info | 🔵 Blue | `#2563eb` |
+| Loading | ⚫ Gray | `#71717a` |
+
+### Customization via CSS Variables
+
+```css
+/* Override in your global CSS */
+:root {
+  --toast-bg:          #ffffff;
+  --toast-border:      #e4e4e7;
+  --toast-text:        #18181b;
+  --toast-text-muted:  #71717a;
+  --toast-radius:      10px;
+  --toast-width:       360px;
+  --toast-gap:         8px;
+  --toast-shadow:      0 2px 8px rgba(0, 0, 0, 0.06), 0 1px 2px rgba(0, 0, 0, 0.04);
+}
+```
+
+---
+
+## 🎬 Animation Spec
+
+| Phase | Duration | Easing |
+|-------|----------|--------|
+| **Enter** | 400ms | `cubic-bezier(0.16, 1, 0.3, 1)` — spring |
+| **Exit** | 220ms | `cubic-bezier(0.4, 0, 1, 1)` — snappy |
+| **Sibling reflow** | 350ms | `cubic-bezier(0.16, 1, 0.3, 1)` — spring |
+| **Swipe snap-back** | 360ms | `cubic-bezier(0.16, 1, 0.3, 1)` — spring |
+
+---
+
+## 📁 File Structure
+
+```
+src/
+├── assets/
+│   └── toast.css              # All styles & animations
+├── components/
+│   ├── Toast.vue              # Individual toast card
+│   └── ToastContainer.vue     # Positional viewport manager
+├── composables/
+│   └── useToast.ts            # Reactive toast API
+├── plugins/
+│   └── toast.ts               # Vue plugin (app.use)
+├── types/
+│   └── toast.ts               # TypeScript interfaces
+└── main.ts                    # App entry point
+```
+
+---
+
+## 📊 Bundle Size
+
+| File | Raw | Gzipped |
+|------|-----|---------|
+| JS (all files) | ~12 KB | ~4 KB |
+| CSS | ~6 KB | ~2 KB |
+| **Total** | **~18 KB** | **~6 KB** |
+
+Zero external dependencies beyond Vue 3.
+
+---
+
+## 📄 License
+
+MIT © feather-toast

package/desktop.ini

@@ -0,0 +1,2 @@
+[.ShellClassInfo]
+LocalizedResourceName=@vue-toast,0

package/env.d.ts

@@ -0,0 +1 @@
+/// <reference types="vite/client" />

package/index.html

@@ -0,0 +1,15 @@
+<!DOCTYPE html>
+<html lang="">
+
+<head>
+  <meta charset="UTF-8">
+  <link rel="icon" href="data:image/svg+xml,<svg xmlns='http://www.w3.org/2000/svg' viewBox='0 0 100 100'><text y='.9em' font-size='90'>🪶</text></svg>">
+  <meta name="viewport" content="width=device-width, initial-scale=1.0">
+  <title>feather-toast demo</title>
+</head>
+
+<body>
+  <div id="app"></div>
+  <script type="module" src="/src/main.ts"></script>
+</body>
+</html>

package/package.json

@@ -0,0 +1,33 @@
+{
+  "name": "feather-toast-vue",
+  "version": "1.0.0",
+  "description": "A lightweight, smooth Vue 3 toast notification plugin",
+  "homepage": "https://zin-ix.github.io/feather-toast/",
+  "type": "module",
+  "scripts": {
+    "dev": "vite",
+    "build": "npm-run-all type-check build-only",
+    "build-only": "vite build",
+    "preview": "vite preview",
+    "type-check": "vue-tsc --build",
+    "deploy": "npm run build && gh-pages -d dist"
+  },
+  "dependencies": {
+    "vue": "^3.5.32"
+  },
+  "devDependencies": {
+    "@tsconfig/node24": "^24.0.4",
+    "@types/node": "^24.12.2",
+    "@vitejs/plugin-vue": "^6.0.6",
+    "@vue/tsconfig": "^0.9.1",
+    "gh-pages": "^6.3.0",
+    "npm-run-all2": "^8.0.4",
+    "typescript": "~6.0.0",
+    "vite": "^8.0.8",
+    "vite-plugin-vue-devtools": "^8.1.1",
+    "vue-tsc": "^3.2.6"
+  },
+  "engines": {
+    "node": "^20.19.0 || >=22.12.0"
+  }
+}