vue-toast-kit 1.0.0

package/src/nuxt/composables.ts

@@ -0,0 +1,13 @@
+// Nuxt-compatible re-exports for auto-import and manual import
+// Usage: import { useToast } from 'vue-toast-kit/nuxt/composables'
+
+export { useToast, toast } from '../composables/useToast'
+export type { ToastApi } from '../composables/useToast'
+
+export { useToastState } from '../composables/useToastState'
+
+export {
+  useToastContext,
+  createToastContext,
+  getOrCreateGlobalContext,
+} from '../composables/useToastContext'

package/src/nuxt/module.ts

@@ -0,0 +1,52 @@
+import { defineNuxtModule, addPlugin, createResolver, addImports, addComponent } from '@nuxt/kit'
+import type { GlobalToastOptions } from '../core/types'
+
+export interface ModuleOptions extends GlobalToastOptions {
+  registerComponent?: boolean
+}
+
+export default defineNuxtModule<ModuleOptions>({
+  meta: {
+    name: 'vue-toast-kit',
+    configKey: 'vueToastKit',
+    compatibility: { nuxt: '>=3.0.0' },
+  },
+  defaults: {
+    position: 'bottom-right',
+    maxVisible: 5,
+    duration: 4000,
+    theme: 'system',
+    closable: true,
+    pauseOnHover: true,
+    pauseOnFocusLoss: true,
+    registerComponent: true,
+  },
+  setup(options, nuxt) {
+    const resolver = createResolver(import.meta.url)
+
+    // Pass module options to runtimeConfig
+    nuxt.options.runtimeConfig.public.vueToastKit = options as Record<string, unknown>
+
+    // Register Nuxt plugin
+    addPlugin(resolver.resolve('./plugin'))
+
+    // Auto-imports composables
+    addImports([
+      { name: 'useToast', from: resolver.resolve('../composables/useToast') },
+      { name: 'useToastState', from: resolver.resolve('../composables/useToastState') },
+      { name: 'createToastContext', from: resolver.resolve('../composables/useToastContext') },
+      { name: 'toast', from: resolver.resolve('../composables/useToast') },
+    ])
+
+    // Auto-import components
+    if (options.registerComponent !== false) {
+      addComponent({
+        name: 'ToastContainer',
+        filePath: resolver.resolve('../components/ToastContainer.vue'),
+      })
+    }
+
+    // Inject CSS
+    nuxt.options.css.push('vue-toast-kit/style.css')
+  },
+})

package/src/nuxt/plugin.ts

@@ -0,0 +1,8 @@
+import { defineNuxtPlugin } from '#app'
+import { VueToastPlugin } from '../plugin'
+import type { VueToastPluginOptions } from '../plugin'
+
+export default defineNuxtPlugin<{ toastOptions: VueToastPluginOptions }>((nuxtApp) => {
+  const options = (nuxtApp.$config?.public?.vueToastKit ?? {}) as VueToastPluginOptions
+  nuxtApp.vueApp.use(VueToastPlugin, options)
+})

package/src/plugin.ts

@@ -0,0 +1,18 @@
+import type { App, Plugin } from 'vue'
+import { installContext } from './composables/useToastContext'
+import ToastContainer from './components/ToastContainer.vue'
+import type { GlobalToastOptions } from './core/types'
+
+export interface VueToastPluginOptions extends GlobalToastOptions {
+  registerComponent?: boolean
+}
+
+export const VueToastPlugin: Plugin<VueToastPluginOptions | void> = {
+  install(app: App, options?: VueToastPluginOptions) {
+    installContext(app, options ?? {})
+
+    if (options?.registerComponent !== false) {
+      app.component('ToastContainer', ToastContainer)
+    }
+  },
+}

package/src/styles/animations.css

@@ -0,0 +1,106 @@
+/* === Enter/Leave анимации по позиции === */
+
+/* top-right */
+.vtk-slide-top-right-enter-active,
+.vtk-slide-top-right-leave-active {
+  transition:
+    transform var(--vtk-transition-duration) var(--vtk-transition-easing),
+    opacity var(--vtk-transition-duration) var(--vtk-transition-easing);
+}
+.vtk-slide-top-right-enter-from { transform: translateX(calc(100% + var(--vtk-container-offset-x))); opacity: 0; }
+.vtk-slide-top-right-leave-to   { transform: translateX(calc(100% + var(--vtk-container-offset-x))); opacity: 0; }
+
+/* top-left */
+.vtk-slide-top-left-enter-active,
+.vtk-slide-top-left-leave-active {
+  transition:
+    transform var(--vtk-transition-duration) var(--vtk-transition-easing),
+    opacity var(--vtk-transition-duration) var(--vtk-transition-easing);
+}
+.vtk-slide-top-left-enter-from { transform: translateX(calc(-100% - var(--vtk-container-offset-x))); opacity: 0; }
+.vtk-slide-top-left-leave-to   { transform: translateX(calc(-100% - var(--vtk-container-offset-x))); opacity: 0; }
+
+/* top-center */
+.vtk-slide-top-center-enter-active,
+.vtk-slide-top-center-leave-active {
+  transition:
+    transform var(--vtk-transition-duration) var(--vtk-transition-easing),
+    opacity var(--vtk-transition-duration) var(--vtk-transition-easing);
+}
+.vtk-slide-top-center-enter-from { transform: translateY(calc(-100% - var(--vtk-container-offset-y))) scale(0.85); opacity: 0; }
+.vtk-slide-top-center-leave-to   { transform: translateY(calc(-100% - var(--vtk-container-offset-y))) scale(0.85); opacity: 0; }
+
+/* bottom-right */
+.vtk-slide-bottom-right-enter-active,
+.vtk-slide-bottom-right-leave-active {
+  transition:
+    transform var(--vtk-transition-duration) var(--vtk-transition-easing),
+    opacity var(--vtk-transition-duration) var(--vtk-transition-easing);
+}
+.vtk-slide-bottom-right-enter-from { transform: translateX(calc(100% + var(--vtk-container-offset-x))); opacity: 0; }
+.vtk-slide-bottom-right-leave-to   { transform: translateX(calc(100% + var(--vtk-container-offset-x))); opacity: 0; }
+
+/* bottom-left */
+.vtk-slide-bottom-left-enter-active,
+.vtk-slide-bottom-left-leave-active {
+  transition:
+    transform var(--vtk-transition-duration) var(--vtk-transition-easing),
+    opacity var(--vtk-transition-duration) var(--vtk-transition-easing);
+}
+.vtk-slide-bottom-left-enter-from { transform: translateX(calc(-100% - var(--vtk-container-offset-x))); opacity: 0; }
+.vtk-slide-bottom-left-leave-to   { transform: translateX(calc(-100% - var(--vtk-container-offset-x))); opacity: 0; }
+
+/* bottom-center */
+.vtk-slide-bottom-center-enter-active,
+.vtk-slide-bottom-center-leave-active {
+  transition:
+    transform var(--vtk-transition-duration) var(--vtk-transition-easing),
+    opacity var(--vtk-transition-duration) var(--vtk-transition-easing);
+}
+.vtk-slide-bottom-center-enter-from { transform: translateY(calc(100% + var(--vtk-container-offset-y))) scale(0.85); opacity: 0; }
+.vtk-slide-bottom-center-leave-to   { transform: translateY(calc(100% + var(--vtk-container-offset-y))) scale(0.85); opacity: 0; }
+
+/* === prefers-reduced-motion — только fade === */
+@media (prefers-reduced-motion: reduce) {
+  .vtk-slide-top-right-enter-from,
+  .vtk-slide-top-left-enter-from,
+  .vtk-slide-top-center-enter-from,
+  .vtk-slide-bottom-right-enter-from,
+  .vtk-slide-bottom-left-enter-from,
+  .vtk-slide-bottom-center-enter-from,
+  .vtk-slide-top-right-leave-to,
+  .vtk-slide-top-left-leave-to,
+  .vtk-slide-top-center-leave-to,
+  .vtk-slide-bottom-right-leave-to,
+  .vtk-slide-bottom-left-leave-to,
+  .vtk-slide-bottom-center-leave-to {
+    transform: none !important;
+    opacity: 0;
+  }
+
+  .vtk-slide-top-right-enter-active,
+  .vtk-slide-top-left-enter-active,
+  .vtk-slide-top-center-enter-active,
+  .vtk-slide-bottom-right-enter-active,
+  .vtk-slide-bottom-left-enter-active,
+  .vtk-slide-bottom-center-enter-active,
+  .vtk-slide-top-right-leave-active,
+  .vtk-slide-top-left-leave-active,
+  .vtk-slide-top-center-leave-active,
+  .vtk-slide-bottom-right-leave-active,
+  .vtk-slide-bottom-left-leave-active,
+  .vtk-slide-bottom-center-leave-active {
+    transition-duration: 150ms !important;
+  }
+}
+
+/* === Spinner для loading === */
+@keyframes vtk-spin {
+  to { transform: rotate(360deg); }
+}
+
+/* === Progress bar === */
+@keyframes vtk-progress {
+  from { transform: scaleX(1); }
+  to   { transform: scaleX(0); }
+}

package/src/styles/base.css

@@ -0,0 +1,201 @@
+/* === Контейнер === */
+.vtk-container {
+  position: fixed;
+  z-index: var(--vtk-z-index);
+  display: flex;
+  flex-direction: column;
+  gap: var(--vtk-gap);
+  pointer-events: none;
+  max-width: var(--vtk-max-width);
+  width: 100%;
+  box-sizing: border-box;
+}
+
+.vtk-container--top-left    { top: var(--vtk-container-offset-y); left: var(--vtk-container-offset-x); align-items: flex-start; }
+.vtk-container--top-center  { top: var(--vtk-container-offset-y); left: 50%; transform: translateX(-50%); align-items: center; }
+.vtk-container--top-right   { top: var(--vtk-container-offset-y); right: var(--vtk-container-offset-x); align-items: flex-end; }
+.vtk-container--bottom-left { bottom: var(--vtk-container-offset-y); left: var(--vtk-container-offset-x); align-items: flex-start; flex-direction: column-reverse; }
+.vtk-container--bottom-center { bottom: var(--vtk-container-offset-y); left: 50%; transform: translateX(-50%); align-items: center; flex-direction: column-reverse; }
+.vtk-container--bottom-right { bottom: var(--vtk-container-offset-y); right: var(--vtk-container-offset-x); align-items: flex-end; flex-direction: column-reverse; }
+
+/* === Тост === */
+.vtk-toast {
+  position: relative;
+  display: flex;
+  align-items: flex-start;
+  gap: 0.625rem;
+  padding: var(--vtk-padding-y) var(--vtk-padding-x);
+  background: var(--vtk-color-bg);
+  border: var(--vtk-border-width) solid var(--vtk-color-border);
+  border-radius: var(--vtk-border-radius);
+  box-shadow: var(--vtk-shadow);
+  font-family: var(--vtk-font-family);
+  font-size: var(--vtk-font-size);
+  font-weight: var(--vtk-font-weight-normal);
+  line-height: var(--vtk-line-height);
+  color: var(--vtk-color-text);
+  pointer-events: all;
+  overflow: hidden;
+  max-width: 100%;
+  min-width: var(--vtk-min-width);
+  box-sizing: border-box;
+  cursor: default;
+  user-select: none;
+}
+
+.vtk-toast--success { border-color: var(--vtk-color-success-border); background: var(--vtk-color-success-bg); }
+.vtk-toast--error   { border-color: var(--vtk-color-error-border);   background: var(--vtk-color-error-bg);   }
+.vtk-toast--warning { border-color: var(--vtk-color-warning-border); background: var(--vtk-color-warning-bg); }
+.vtk-toast--info    { border-color: var(--vtk-color-info-border);    background: var(--vtk-color-info-bg);    }
+.vtk-toast--loading { border-color: var(--vtk-color-loading-border); background: var(--vtk-color-loading-bg); }
+
+/* === Иконка === */
+.vtk-icon {
+  flex-shrink: 0;
+  width: var(--vtk-icon-size);
+  height: var(--vtk-icon-size);
+  display: flex;
+  align-items: center;
+  justify-content: center;
+}
+
+.vtk-icon--success { color: var(--vtk-color-success); }
+.vtk-icon--error   { color: var(--vtk-color-error);   }
+.vtk-icon--warning { color: var(--vtk-color-warning); }
+.vtk-icon--info    { color: var(--vtk-color-info);    }
+.vtk-icon--loading { color: var(--vtk-color-loading); }
+
+.vtk-icon svg {
+  width: 100%;
+  height: 100%;
+}
+
+/* CSS spinner */
+.vtk-spinner {
+  width: var(--vtk-icon-size);
+  height: var(--vtk-icon-size);
+  border: 2px solid transparent;
+  border-top-color: var(--vtk-color-loading);
+  border-right-color: var(--vtk-color-loading);
+  border-radius: 50%;
+  animation: vtk-spin 0.7s linear infinite;
+  flex-shrink: 0;
+}
+
+/* === Контент === */
+.vtk-content {
+  flex: 1;
+  min-width: 0;
+  display: flex;
+  flex-direction: column;
+  gap: 0.25rem;
+}
+
+.vtk-message {
+  font-size: var(--vtk-font-size);
+  line-height: var(--vtk-line-height);
+  color: var(--vtk-color-text);
+  word-break: break-word;
+}
+
+/* === Действия === */
+.vtk-actions {
+  display: flex;
+  align-items: center;
+  gap: 0.375rem;
+  margin-top: 0.25rem;
+  flex-wrap: wrap;
+}
+
+.vtk-btn {
+  display: inline-flex;
+  align-items: center;
+  gap: 0.25rem;
+  padding: var(--vtk-btn-padding);
+  font-family: var(--vtk-font-family);
+  font-size: var(--vtk-btn-font-size);
+  font-weight: var(--vtk-btn-font-weight);
+  color: var(--vtk-btn-color);
+  background: var(--vtk-btn-bg);
+  border: none;
+  border-radius: var(--vtk-btn-radius);
+  cursor: pointer;
+  transition: background var(--vtk-transition-duration) var(--vtk-transition-easing);
+  line-height: 1;
+}
+
+.vtk-btn:hover { background: var(--vtk-btn-hover-bg); }
+.vtk-btn:focus-visible { outline: 2px solid currentColor; outline-offset: 1px; }
+
+.vtk-btn--action { color: var(--vtk-color-info); font-weight: 600; }
+.vtk-btn--undo   { color: var(--vtk-color-warning); font-weight: 600; }
+.vtk-btn--close  { color: var(--vtk-color-text-muted); padding: 0.25rem; margin-inline-start: auto; flex-shrink: 0; }
+
+/* === Счётчик группы === */
+.vtk-group-count {
+  display: inline-flex;
+  align-items: center;
+  justify-content: center;
+  min-width: 1.25rem;
+  height: 1.25rem;
+  padding: 0 0.3rem;
+  font-size: 0.6875rem;
+  font-weight: 700;
+  background: rgba(0, 0, 0, 0.10);
+  border-radius: 999px;
+  cursor: pointer;
+  flex-shrink: 0;
+}
+
+/* === Прогресс-бар === */
+.vtk-progress {
+  position: absolute;
+  bottom: 0;
+  left: 0;
+  right: 0;
+  height: var(--vtk-progress-height);
+  overflow: hidden;
+  border-radius: 0 0 var(--vtk-border-radius) var(--vtk-border-radius);
+}
+
+.vtk-progress__bar {
+  height: 100%;
+  width: 100%;
+  transform-origin: left center;
+  background: var(--vtk-progress-color);
+  opacity: var(--vtk-progress-opacity);
+  transition: transform 100ms linear;
+}
+
+.vtk-toast--success .vtk-progress__bar { background: var(--vtk-color-success); opacity: 0.4; }
+.vtk-toast--error   .vtk-progress__bar { background: var(--vtk-color-error);   opacity: 0.4; }
+.vtk-toast--warning .vtk-progress__bar { background: var(--vtk-color-warning); opacity: 0.4; }
+.vtk-toast--info    .vtk-progress__bar { background: var(--vtk-color-info);    opacity: 0.4; }
+.vtk-toast--loading .vtk-progress__bar { background: var(--vtk-color-loading); opacity: 0.4; }
+
+/* === RTL === */
+[dir="rtl"] .vtk-btn--close { margin-inline-start: auto; }
+
+/* === Mobile === */
+@media (max-width: 480px) {
+  .vtk-container {
+    --vtk-container-offset-x: 0.75rem;
+    --vtk-container-offset-y: 0.75rem;
+    --vtk-max-width: calc(100vw - 1.5rem);
+    --vtk-min-width: 0;
+  }
+
+  .vtk-container--top-center,
+  .vtk-container--bottom-center {
+    left: var(--vtk-container-offset-x);
+    right: var(--vtk-container-offset-x);
+    transform: none;
+    width: auto;
+  }
+}
+
+/* === Reduced motion === */
+@media (prefers-reduced-motion: reduce) {
+  .vtk-progress__bar { transition: none; }
+  .vtk-spinner       { animation-duration: 1.5s; }
+}

package/src/styles/themes/dark.css

@@ -0,0 +1,30 @@
+.vtk-theme-dark,
+[data-vtk-theme="dark"] {
+  --vtk-color-bg: #1c1c1e;
+  --vtk-color-text: #f5f5f7;
+  --vtk-color-text-muted: #98989f;
+  --vtk-color-border: rgba(255, 255, 255, 0.10);
+  --vtk-shadow: 0 4px 20px rgba(0, 0, 0, 0.40), 0 1px 6px rgba(0, 0, 0, 0.20);
+
+  --vtk-color-success: #34d399;
+  --vtk-color-success-bg: #052e16;
+  --vtk-color-success-border: rgba(52, 211, 153, 0.20);
+
+  --vtk-color-error: #f87171;
+  --vtk-color-error-bg: #2d0a0a;
+  --vtk-color-error-border: rgba(248, 113, 113, 0.20);
+
+  --vtk-color-warning: #fbbf24;
+  --vtk-color-warning-bg: #2d1a00;
+  --vtk-color-warning-border: rgba(251, 191, 36, 0.20);
+
+  --vtk-color-info: #60a5fa;
+  --vtk-color-info-bg: #0c1a2e;
+  --vtk-color-info-border: rgba(96, 165, 250, 0.20);
+
+  --vtk-color-loading: #a78bfa;
+  --vtk-color-loading-bg: #1a0a2e;
+  --vtk-color-loading-border: rgba(167, 139, 250, 0.20);
+
+  --vtk-btn-hover-bg: rgba(255, 255, 255, 0.08);
+}

package/src/styles/themes/light.css

@@ -0,0 +1,30 @@
+.vtk-theme-light,
+[data-vtk-theme="light"] {
+  --vtk-color-bg: #ffffff;
+  --vtk-color-text: #1a1a1a;
+  --vtk-color-text-muted: #6b7280;
+  --vtk-color-border: rgba(0, 0, 0, 0.08);
+  --vtk-shadow: 0 4px 16px rgba(0, 0, 0, 0.10), 0 1px 4px rgba(0, 0, 0, 0.06);
+
+  --vtk-color-success: #16a34a;
+  --vtk-color-success-bg: #f0fdf4;
+  --vtk-color-success-border: #bbf7d0;
+
+  --vtk-color-error: #dc2626;
+  --vtk-color-error-bg: #fef2f2;
+  --vtk-color-error-border: #fecaca;
+
+  --vtk-color-warning: #d97706;
+  --vtk-color-warning-bg: #fffbeb;
+  --vtk-color-warning-border: #fde68a;
+
+  --vtk-color-info: #2563eb;
+  --vtk-color-info-bg: #eff6ff;
+  --vtk-color-info-border: #bfdbfe;
+
+  --vtk-color-loading: #7c3aed;
+  --vtk-color-loading-bg: #f5f3ff;
+  --vtk-color-loading-border: #ddd6fe;
+
+  --vtk-btn-hover-bg: rgba(0, 0, 0, 0.06);
+}

package/src/styles/themes/system.css

@@ -0,0 +1,32 @@
+@media (prefers-color-scheme: dark) {
+  .vtk-theme-system,
+  [data-vtk-theme="system"] {
+    --vtk-color-bg: #1c1c1e;
+    --vtk-color-text: #f5f5f7;
+    --vtk-color-text-muted: #98989f;
+    --vtk-color-border: rgba(255, 255, 255, 0.10);
+    --vtk-shadow: 0 4px 20px rgba(0, 0, 0, 0.40), 0 1px 6px rgba(0, 0, 0, 0.20);
+
+    --vtk-color-success: #34d399;
+    --vtk-color-success-bg: #052e16;
+    --vtk-color-success-border: rgba(52, 211, 153, 0.20);
+
+    --vtk-color-error: #f87171;
+    --vtk-color-error-bg: #2d0a0a;
+    --vtk-color-error-border: rgba(248, 113, 113, 0.20);
+
+    --vtk-color-warning: #fbbf24;
+    --vtk-color-warning-bg: #2d1a00;
+    --vtk-color-warning-border: rgba(251, 191, 36, 0.20);
+
+    --vtk-color-info: #60a5fa;
+    --vtk-color-info-bg: #0c1a2e;
+    --vtk-color-info-border: rgba(96, 165, 250, 0.20);
+
+    --vtk-color-loading: #a78bfa;
+    --vtk-color-loading-bg: #1a0a2e;
+    --vtk-color-loading-border: rgba(167, 139, 250, 0.20);
+
+    --vtk-btn-hover-bg: rgba(255, 255, 255, 0.08);
+  }
+}

package/src/styles/tokens.css

@@ -0,0 +1,74 @@
+:root {
+  /* === Цвета фона и текста === */
+  --vtk-color-bg: #ffffff;
+  --vtk-color-text: #1a1a1a;
+  --vtk-color-text-muted: #6b7280;
+  --vtk-color-border: rgba(0, 0, 0, 0.08);
+
+  /* === Цвета типов === */
+  --vtk-color-success: #16a34a;
+  --vtk-color-success-bg: #f0fdf4;
+  --vtk-color-success-border: #bbf7d0;
+
+  --vtk-color-error: #dc2626;
+  --vtk-color-error-bg: #fef2f2;
+  --vtk-color-error-border: #fecaca;
+
+  --vtk-color-warning: #d97706;
+  --vtk-color-warning-bg: #fffbeb;
+  --vtk-color-warning-border: #fde68a;
+
+  --vtk-color-info: #2563eb;
+  --vtk-color-info-bg: #eff6ff;
+  --vtk-color-info-border: #bfdbfe;
+
+  --vtk-color-loading: #7c3aed;
+  --vtk-color-loading-bg: #f5f3ff;
+  --vtk-color-loading-border: #ddd6fe;
+
+  /* === Прогресс-бар === */
+  --vtk-progress-color: currentColor;
+  --vtk-progress-opacity: 0.25;
+
+  /* === Типографика === */
+  --vtk-font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, sans-serif;
+  --vtk-font-size: 0.875rem;
+  --vtk-font-size-sm: 0.75rem;
+  --vtk-font-weight: 500;
+  --vtk-font-weight-normal: 400;
+  --vtk-line-height: 1.5;
+
+  /* === Форма === */
+  --vtk-border-radius: 10px;
+  --vtk-border-width: 1px;
+  --vtk-shadow: 0 4px 16px rgba(0, 0, 0, 0.10), 0 1px 4px rgba(0, 0, 0, 0.06);
+
+  /* === Размеры === */
+  --vtk-padding-x: 1rem;
+  --vtk-padding-y: 0.75rem;
+  --vtk-icon-size: 1.25rem;
+  --vtk-progress-height: 3px;
+  --vtk-max-width: 400px;
+  --vtk-min-width: 280px;
+  --vtk-gap: 0.5rem;
+
+  /* === Кнопки === */
+  --vtk-btn-color: inherit;
+  --vtk-btn-bg: transparent;
+  --vtk-btn-hover-bg: rgba(0, 0, 0, 0.06);
+  --vtk-btn-radius: 6px;
+  --vtk-btn-font-size: 0.8125rem;
+  --vtk-btn-font-weight: 600;
+  --vtk-btn-padding: 0.25rem 0.625rem;
+
+  /* === Анимации === */
+  --vtk-transition-duration: 300ms;
+  --vtk-transition-easing: cubic-bezier(0.4, 0, 0.2, 1);
+
+  /* === Z-index === */
+  --vtk-z-index: 9999;
+
+  /* === Контейнер === */
+  --vtk-container-offset-x: 1rem;
+  --vtk-container-offset-y: 1rem;
+}

package/src/testing.ts

@@ -0,0 +1,81 @@
+/**
+ * Testing utilities for vue-toast-kit.
+ * Compatible with Vitest and Jest.
+ *
+ * Usage:
+ *   import { createMockToast, mockUseToast } from 'vue-toast-kit/testing'
+ */
+import { ref } from 'vue'
+import type { ToastItem, ToastOptions, ToastType, ToastPriority } from './core/types'
+import type { ToastApi } from './composables/useToast'
+
+// ── createMockToast ───────────────────────────────────────────────────────────
+
+/** Create a minimal ToastItem stub for unit tests. */
+export function createMockToast(overrides: Partial<ToastItem> & { options?: Partial<ToastOptions> } = {}): ToastItem {
+  const defaultOptions = {
+    id: overrides.id ?? 'mock-id',
+    type: 'info' as ToastType,
+    priority: 'normal' as ToastPriority,
+    duration: 4000,
+    closable: true,
+    pauseOnHover: true,
+    pauseOnFocusLoss: true,
+    swipeToDismiss: true,
+    persist: false,
+    ...overrides.options,
+  }
+
+  const item: ToastItem = {
+    id: overrides.id ?? `mock-${Math.random().toString(36).slice(2)}`,
+    message: overrides.message ?? 'Test toast',
+    options: defaultOptions as ToastItem['options'],
+    createdAt: overrides.createdAt ?? Date.now(),
+    remaining: overrides.remaining ?? ref(1),
+    isPaused: overrides.isPaused ?? ref(false),
+    groupCount: overrides.groupCount ?? ref(1),
+    isGrouped: overrides.isGrouped ?? ref(false),
+    pause: overrides.pause ?? (() => {}),
+    resume: overrides.resume ?? (() => {}),
+    dismiss: overrides.dismiss ?? (() => {}),
+    update: overrides.update ?? (() => {}),
+  }
+
+  return item
+}
+
+// ── mockUseToast ──────────────────────────────────────────────────────────────
+
+/**
+ * Create a spy-friendly mock of the ToastApi.
+ * All methods are no-ops that return empty strings unless overridden.
+ *
+ * @example
+ * vi.mock('vue-toast-kit', () => ({ useToast: () => mockUseToast() }))
+ */
+export function mockUseToast(overrides: Partial<ToastApi> = {}): ToastApi {
+  const noop = () => ''
+  const noopVoid = () => {}
+
+  function toast(_message: string, _options?: ToastOptions): string {
+    return ''
+  }
+
+  toast.success = overrides.success ?? noop
+  toast.error = overrides.error ?? noop
+  toast.warning = overrides.warning ?? noop
+  toast.info = overrides.info ?? noop
+  toast.loading = overrides.loading ?? noop
+  toast.custom = overrides.custom ?? noop
+  toast.dismiss = overrides.dismiss ?? noopVoid
+  toast.update = overrides.update ?? noopVoid
+  toast.updateMessage = overrides.updateMessage ?? noopVoid
+  toast.isActive = overrides.isActive ?? (() => false)
+  toast.promise = overrides.promise ?? (<T>(p: Promise<T>) => p)
+  toast.undo = overrides.undo ?? noop
+  toast.dismissAll = overrides.dismissAll ?? noopVoid
+  toast.pauseAll = overrides.pauseAll ?? noopVoid
+  toast.resumeAll = overrides.resumeAll ?? noopVoid
+
+  return toast as unknown as ToastApi
+}