@wishbone-media/spark 0.20.0 → 0.21.0

package/src/composables/sparkNotificationService.js

@@ -0,0 +1,459 @@
+import { markRaw, reactive } from 'vue'
+
+// Default durations by type (in ms)
+const DEFAULT_DURATIONS = {
+  success: 5000,
+  info: 5000,
+  warning: 5000,
+  danger: 0, // sticky by default
+}
+
+// Valid toast positions
+const TOAST_POSITIONS = ['top-left', 'top-right', 'center', 'bottom-left', 'bottom-right']
+
+/**
+ * Creates a notification outlet state manager (for banner notifications)
+ * @private
+ */
+function createNotificationOutlet() {
+  const state = reactive({
+    isVisible: false,
+    type: 'info',
+    message: null,
+    component: null,
+    props: {},
+    closeable: true,
+    duration: null,
+  })
+
+  // Timer state (not reactive, internal only)
+  let dismissTimeout = null
+  let remainingTime = 0
+  let isPaused = false
+  let timerStartedAt = null
+
+  const clearDismissTimeout = () => {
+    if (dismissTimeout) {
+      clearTimeout(dismissTimeout)
+      dismissTimeout = null
+    }
+    remainingTime = 0
+    isPaused = false
+    timerStartedAt = null
+  }
+
+  const hide = () => {
+    clearDismissTimeout()
+    state.isVisible = false
+  }
+
+  const startDismissTimer = (duration) => {
+    if (duration <= 0) return
+
+    remainingTime = duration
+    timerStartedAt = Date.now()
+
+    dismissTimeout = setTimeout(() => {
+      hide()
+    }, duration)
+  }
+
+  const pause = () => {
+    if (!dismissTimeout || isPaused) return
+
+    clearTimeout(dismissTimeout)
+    dismissTimeout = null
+
+    const elapsed = Date.now() - timerStartedAt
+    remainingTime = Math.max(0, remainingTime - elapsed)
+    isPaused = true
+  }
+
+  const resume = () => {
+    if (!isPaused || remainingTime <= 0) return
+
+    isPaused = false
+    timerStartedAt = Date.now()
+
+    dismissTimeout = setTimeout(() => {
+      hide()
+    }, remainingTime)
+  }
+
+  const show = (options = {}) => {
+    clearDismissTimeout()
+
+    const {
+      type = 'info',
+      message = null,
+      component = null,
+      props = {},
+      closeable = true,
+      duration = null,
+    } = options
+
+    state.type = type
+    state.message = message
+    state.component = component ? markRaw(component) : null
+    state.props = props
+    state.closeable = closeable
+    state.isVisible = true
+
+    // Determine duration: explicit > default for type
+    const effectiveDuration = duration !== null ? duration : DEFAULT_DURATIONS[type]
+    state.duration = effectiveDuration
+
+    if (effectiveDuration > 0) {
+      startDismissTimer(effectiveDuration)
+    }
+  }
+
+  const reset = () => {
+    hide()
+    state.type = 'info'
+    state.message = null
+    state.component = null
+    state.props = {}
+    state.closeable = true
+    state.duration = null
+  }
+
+  return {
+    state,
+    show,
+    hide,
+    reset,
+    pause,
+    resume,
+  }
+}
+
+/**
+ * Service for managing notifications (both banner and toast)
+ *
+ * Banner Usage:
+ *   sparkNotificationService.show({ type: 'success', message: 'Saved!' })
+ *   sparkNotificationService.show({ type: 'error', message: 'Failed' }, 'form-errors')
+ *   sparkNotificationService.hide()
+ *
+ * Toast Usage:
+ *   sparkNotificationService.toast({ type: 'success', message: 'Saved!' })
+ *   sparkNotificationService.toast({ type: 'error', message: 'Failed', position: 'top-right' })
+ *   sparkNotificationService.hideToast(toastId)
+ *   sparkNotificationService.hideAllToasts()
+ */
+class SparkNotificationService {
+  constructor() {
+    // Banner outlets
+    this.outlets = new Map()
+
+    // Toast state
+    this.toastState = reactive({
+      toasts: [],
+      maxToasts: 3,
+      defaultPosition: 'bottom-right',
+      newestOnTop: true,
+    })
+
+    // Toast timers (keyed by toast id)
+    this._toastTimers = new Map()
+
+    // Counter for unique toast IDs
+    this._toastIdCounter = 0
+  }
+
+  // ============================================
+  // Banner Notification Methods
+  // ============================================
+
+  /**
+   * Get or create a notification outlet by name
+   * @param {string} name - Outlet name (default: 'default')
+   * @returns {Object} Notification outlet instance
+   */
+  getOutlet(name = 'default') {
+    if (!this.outlets.has(name)) {
+      this.outlets.set(name, createNotificationOutlet())
+    }
+    return this.outlets.get(name)
+  }
+
+  /**
+   * Show a banner notification in the specified outlet
+   * @param {Object} options - Notification options
+   * @param {string} options.type - Alert type: 'success' | 'warning' | 'danger' | 'info'
+   * @param {string} options.message - Simple text message (mutually exclusive with component)
+   * @param {Component} options.component - Vue component to render (mutually exclusive with message)
+   * @param {Object} options.props - Props to pass to the component
+   * @param {boolean} options.closeable - Whether to show close button (default: true)
+   * @param {number} options.duration - Auto-dismiss duration in ms (0 = sticky, null = use default)
+   * @param {string} outletName - Target outlet name (default: 'default')
+   */
+  show(options = {}, outletName = 'default') {
+    const outlet = this.getOutlet(outletName)
+    outlet.show(options)
+  }
+
+  /**
+   * Hide banner notification in the specified outlet
+   * @param {string} outletName - Target outlet name (default: 'default')
+   */
+  hide(outletName = 'default') {
+    const outlet = this.getOutlet(outletName)
+    outlet.hide()
+  }
+
+  /**
+   * Hide all banner notifications in all outlets
+   */
+  hideAll() {
+    for (const outlet of this.outlets.values()) {
+      outlet.hide()
+    }
+  }
+
+  /**
+   * Pause auto-dismiss timer for the specified banner outlet
+   * @param {string} outletName - Target outlet name (default: 'default')
+   */
+  pause(outletName = 'default') {
+    const outlet = this.getOutlet(outletName)
+    outlet.pause()
+  }
+
+  /**
+   * Resume auto-dismiss timer for the specified banner outlet
+   * @param {string} outletName - Target outlet name (default: 'default')
+   */
+  resume(outletName = 'default') {
+    const outlet = this.getOutlet(outletName)
+    outlet.resume()
+  }
+
+  /**
+   * Reset and remove a banner outlet
+   * @param {string} outletName - Target outlet name (default: 'default')
+   */
+  reset(outletName = 'default') {
+    const outlet = this.outlets.get(outletName)
+    if (outlet) {
+      outlet.reset()
+      this.outlets.delete(outletName)
+    }
+  }
+
+  /**
+   * Reset all banner outlets
+   */
+  resetAll() {
+    for (const outlet of this.outlets.values()) {
+      outlet.reset()
+    }
+    this.outlets.clear()
+  }
+
+  // ============================================
+  // Toast Notification Methods
+  // ============================================
+
+  /**
+   * Configure toast defaults
+   * @param {Object} options - Configuration options
+   * @param {number} options.maxToasts - Maximum visible toasts (default: 3)
+   * @param {string} options.defaultPosition - Default position (default: 'bottom-right')
+   * @param {boolean} options.newestOnTop - Whether newest toasts appear on top (default: true)
+   */
+  configureToasts(options = {}) {
+    if (options.maxToasts !== undefined) {
+      this.toastState.maxToasts = options.maxToasts
+    }
+    if (options.defaultPosition !== undefined && TOAST_POSITIONS.includes(options.defaultPosition)) {
+      this.toastState.defaultPosition = options.defaultPosition
+    }
+    if (options.newestOnTop !== undefined) {
+      this.toastState.newestOnTop = options.newestOnTop
+    }
+  }
+
+  /**
+   * Show a toast notification
+   * @param {Object} options - Toast options
+   * @param {string} options.type - Alert type: 'success' | 'warning' | 'danger' | 'info'
+   * @param {string} options.message - Simple text message (mutually exclusive with component)
+   * @param {Component} options.component - Vue component to render (mutually exclusive with message)
+   * @param {Object} options.props - Props to pass to the component
+   * @param {boolean} options.closeable - Whether to show close button (default: true)
+   * @param {number} options.duration - Auto-dismiss duration in ms (0 = sticky, null = use default)
+   * @param {string} options.position - Position: 'top-left' | 'top-right' | 'top-center' | 'bottom-left' | 'bottom-right' | 'bottom-center'
+   * @returns {number} Toast ID for programmatic dismissal
+   */
+  toast(options = {}) {
+    const {
+      type = 'info',
+      message = null,
+      component = null,
+      props = {},
+      closeable = true,
+      duration = null,
+      position = null,
+    } = options
+
+    // Generate unique ID
+    const id = ++this._toastIdCounter
+
+    // Determine effective values
+    const effectivePosition = (position && TOAST_POSITIONS.includes(position))
+      ? position
+      : this.toastState.defaultPosition
+    const effectiveDuration = duration !== null ? duration : DEFAULT_DURATIONS[type]
+
+    // Create toast object
+    const toast = {
+      id,
+      type,
+      message,
+      component: component ? markRaw(component) : null,
+      props,
+      closeable,
+      duration: effectiveDuration,
+      position: effectivePosition,
+      createdAt: Date.now(),
+    }
+
+    // Remove oldest toasts if at capacity (per position)
+    const positionToasts = this.toastState.toasts.filter(t => t.position === effectivePosition)
+    if (positionToasts.length >= this.toastState.maxToasts) {
+      // Remove oldest: when newestOnTop, oldest is at end; otherwise at beginning
+      const oldest = this.toastState.newestOnTop
+        ? positionToasts[positionToasts.length - 1]
+        : positionToasts[0]
+      this.hideToast(oldest.id)
+    }
+
+    // Add toast to array
+    if (this.toastState.newestOnTop) {
+      // Find insertion point: after all toasts of same position
+      const insertIndex = this.toastState.toasts.findIndex(t => t.position === effectivePosition)
+      if (insertIndex === -1) {
+        this.toastState.toasts.push(toast)
+      } else {
+        this.toastState.toasts.splice(insertIndex, 0, toast)
+      }
+    } else {
+      this.toastState.toasts.push(toast)
+    }
+
+    // Start auto-dismiss timer if duration > 0
+    if (effectiveDuration > 0) {
+      this._startToastTimer(id, effectiveDuration)
+    }
+
+    return id
+  }
+
+  /**
+   * Hide a specific toast by ID
+   * @param {number} toastId - Toast ID to hide
+   */
+  hideToast(toastId) {
+    // Clear timer
+    this._clearToastTimer(toastId)
+
+    // Remove from array
+    const index = this.toastState.toasts.findIndex(t => t.id === toastId)
+    if (index !== -1) {
+      this.toastState.toasts.splice(index, 1)
+    }
+  }
+
+  /**
+   * Hide all toasts
+   */
+  hideAllToasts() {
+    // Clear all timers
+    for (const id of this._toastTimers.keys()) {
+      this._clearToastTimer(id)
+    }
+
+    // Clear array
+    this.toastState.toasts.splice(0, this.toastState.toasts.length)
+  }
+
+  /**
+   * Pause auto-dismiss timer for a specific toast
+   * @param {number} toastId - Toast ID
+   */
+  pauseToast(toastId) {
+    const timer = this._toastTimers.get(toastId)
+    if (!timer || timer.isPaused) return
+
+    clearTimeout(timer.timeout)
+    timer.timeout = null
+
+    const elapsed = Date.now() - timer.startedAt
+    timer.remainingTime = Math.max(0, timer.remainingTime - elapsed)
+    timer.isPaused = true
+  }
+
+  /**
+   * Resume auto-dismiss timer for a specific toast
+   * @param {number} toastId - Toast ID
+   */
+  resumeToast(toastId) {
+    const timer = this._toastTimers.get(toastId)
+    if (!timer || !timer.isPaused || timer.remainingTime <= 0) return
+
+    timer.isPaused = false
+    timer.startedAt = Date.now()
+
+    timer.timeout = setTimeout(() => {
+      this.hideToast(toastId)
+    }, timer.remainingTime)
+  }
+
+  /**
+   * Get toasts for a specific position
+   * @param {string} position - Position to filter by
+   * @returns {Array} Toasts at that position
+   */
+  getToastsByPosition(position) {
+    return this.toastState.toasts.filter(t => t.position === position)
+  }
+
+  // ============================================
+  // Private Toast Timer Methods
+  // ============================================
+
+  /**
+   * @private
+   */
+  _startToastTimer(toastId, duration) {
+    const timer = {
+      timeout: null,
+      remainingTime: duration,
+      startedAt: Date.now(),
+      isPaused: false,
+    }
+
+    timer.timeout = setTimeout(() => {
+      this.hideToast(toastId)
+    }, duration)
+
+    this._toastTimers.set(toastId, timer)
+  }
+
+  /**
+   * @private
+   */
+  _clearToastTimer(toastId) {
+    const timer = this._toastTimers.get(toastId)
+    if (timer) {
+      if (timer.timeout) {
+        clearTimeout(timer.timeout)
+      }
+      this._toastTimers.delete(toastId)
+    }
+  }
+}
+
+export const sparkNotificationService = new SparkNotificationService()

package/src/composables/sparkOverlayService.js

@@ -6,7 +6,7 @@ class SparkOverlayService {
         this.right = useSparkOverlay()
     }
 
-    showLeft = (component, props = {}, eventHandlers = {}) => {
+    showLeft = (component, props = {}, eventHandlers = {}, options = {}) => {
         const handlers = {
             close: () => {
                 // Call user's close handler if provided
@@ -16,10 +16,10 @@ class SparkOverlayService {
             },
             ...eventHandlers,
         }
-        this.left.show(component, props, handlers)
+        this.left.show(component, props, handlers, options)
     }
 
-    showRight = (component, props = {}, eventHandlers = {}) => {
+    showRight = (component, props = {}, eventHandlers = {}, options = {}) => {
         const handlers = {
             close: () => {
                 // Call user's close handler if provided
@@ -29,7 +29,7 @@ class SparkOverlayService {
             },
             ...eventHandlers,
         }
-        this.right.show(component, props, handlers)
+        this.right.show(component, props, handlers, options)
     }
 
     closeLeft = () => {

package/src/composables/useSparkOverlay.js

@@ -6,6 +6,7 @@ export function useSparkOverlay() {
     content: null,
     props: {},
     eventHandlers: {},
+    size: 'md',
   })
 
   const toggle = () => {
@@ -17,20 +18,22 @@ export function useSparkOverlay() {
     state.content = null
     state.props = {}
     state.eventHandlers = {}
+    state.size = 'md'
   }
 
   const open = () => {
     state.isVisible = true
   }
 
-  const setContent = (content, props = {}, eventHandlers = {}) => {
+  const setContent = (content, props = {}, eventHandlers = {}, options = {}) => {
     state.content = markRaw(content)
     state.props = props
     state.eventHandlers = eventHandlers
+    state.size = options.size || 'md'
   }
 
-  const show = (content, props = {}, eventHandlers = {}) => {
-    if (content) setContent(content, props, eventHandlers)
+  const show = (content, props = {}, eventHandlers = {}, options = {}) => {
+    if (content) setContent(content, props, eventHandlers, options)
     open()
   }