@wishbone-media/spark 0.28.0 → 0.30.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@wishbone-media/spark",
-  "version": "0.28.0",
+  "version": "0.30.0",
   "type": "module",
   "main": "./dist/index.js",
   "module": "./dist/index.js",

package/src/components/SparkNotificationOutlet.vue

@@ -30,7 +30,8 @@
 </template>
 
 <script setup>
-import { computed, ref, watch } from 'vue'
+import { computed, ref, watch, onMounted } from 'vue'
+import { useRoute } from 'vue-router'
 import { sparkNotificationService } from '@/composables/sparkNotificationService'
 import SparkAlert from '@/components/SparkAlert.vue'
 
@@ -39,8 +40,13 @@ const props = defineProps({
     type: String,
     default: 'default',
   },
+  clearOnRouteChange: {
+    type: Boolean,
+    default: true,
+  },
 })
 
+const route = useRoute()
 const outlet = computed(() => sparkNotificationService.getOutlet(props.name))
 
 // Generate unique key for each notification to trigger transition on content change
@@ -54,6 +60,43 @@ watch(
   },
 )
 
+// Track which path the notification was shown on
+watch(
+  () => outlet.value.state.isVisible,
+  (isVisible) => {
+    if (isVisible && !outlet.value.state.shownOnPath) {
+      outlet.value.state.shownOnPath = route.path
+    }
+  },
+  { immediate: true },
+)
+
+// On mount, check if notification was shown on a different route
+onMounted(() => {
+  if (!props.clearOnRouteChange) return
+  if (route.meta.preserveNotifications) return
+  if (!outlet.value.state.isVisible) return
+  if (outlet.value.state.persistent) return
+
+  // If notification was shown on a different path, hide it
+  if (outlet.value.state.shownOnPath && outlet.value.state.shownOnPath !== route.path) {
+    outlet.value.hide()
+  }
+})
+
+// Auto-clear notification on route change (while mounted)
+watch(
+  () => route.path,
+  () => {
+    if (!props.clearOnRouteChange) return
+    if (route.meta.preserveNotifications) return
+    if (!outlet.value.state.isVisible) return
+    if (outlet.value.state.persistent) return
+
+    outlet.value.hide()
+  },
+)
+
 const handleClose = () => {
   sparkNotificationService.hide(props.name)
 }

package/src/components/SparkSubNav.vue

@@ -0,0 +1,266 @@
+<template>
+  <nav :class="containerClasses">
+    <!-- Custom layout slot -->
+    <slot
+      v-if="props.layout === 'custom'"
+      :items="computedItems"
+      :active-id="computedActiveId"
+      :is-active="isItemActive"
+      :is-disabled="isItemDisabled"
+      :navigate="handleNavigate"
+    />
+
+    <!-- Horizontal: SparkButtonGroup -->
+    <SparkButtonGroup v-else-if="props.layout === 'horizontal'" class="isolate">
+      <SparkButton
+        v-for="item in computedItems"
+        :key="item.id"
+        size="xl"
+        :variant="isItemActive(item) ? 'primary' : 'secondary'"
+        :disabled="isItemDisabled(item)"
+        @click="handleNavigate(item)"
+      >
+        <FontAwesomeIcon
+          v-if="item.icon"
+          :icon="Icons[item.icon]"
+          class="mr-1.5 size-4"
+        />
+        {{ item.label }}
+        <span
+          v-if="item.badge != null"
+          :class="getBadgeClasses(item)"
+        >
+          {{ item.badge }}
+        </span>
+      </SparkButton>
+    </SparkButtonGroup>
+
+    <!-- Tabs/Vertical: button-based -->
+    <template v-else>
+      <button
+        v-for="item in computedItems"
+        :key="item.id"
+        :class="getItemClasses(item)"
+        :disabled="isItemDisabled(item) || undefined"
+        @click="handleNavigate(item)"
+      >
+        <!-- Active checkmark icon for vertical layout -->
+        <FontAwesomeIcon
+          v-if="isItemActive(item) && props.layout === 'vertical'"
+          :icon="Icons.farCircleCheck"
+          class="mr-2 size-4"
+        />
+        <!-- Item icon (not for vertical active state) -->
+        <FontAwesomeIcon
+          v-if="item.icon && !(isItemActive(item) && props.layout === 'vertical')"
+          :icon="Icons[item.icon]"
+          class="mr-2"
+          :class="iconClasses"
+        />
+        <span>{{ item.label }}</span>
+        <span
+          v-if="item.badge != null"
+          :class="getBadgeClasses(item)"
+        >
+          {{ item.badge }}
+        </span>
+      </button>
+    </template>
+  </nav>
+</template>
+
+<script setup>
+import { computed } from 'vue'
+import { FontAwesomeIcon } from '@fortawesome/vue-fontawesome'
+import { Icons } from '../plugins/fontawesome.js'
+import SparkButton from './SparkButton.vue'
+import SparkButtonGroup from './SparkButtonGroup.vue'
+
+const props = defineProps({
+  /**
+   * Navigation instance from useSubNavigation composable.
+   * If provided, items and active state come from the instance.
+   */
+  navInstance: {
+    type: Object,
+    default: null,
+  },
+
+  /**
+   * Static items array (used when navInstance is not provided)
+   */
+  items: {
+    type: Array,
+    default: () => [],
+  },
+
+  /**
+   * Layout style
+   * - 'tabs': Underline-style tabs (for card body)
+   * - 'vertical': Vertical sidebar links
+   * - 'horizontal': SparkButtonGroup with buttons
+   * - 'custom': Use scoped slot for full control
+   */
+  layout: {
+    type: String,
+    default: 'tabs',
+    validator: (v) => ['tabs', 'vertical', 'horizontal', 'custom'].includes(v),
+  },
+
+  /**
+   * Currently active item ID (for controlled mode without navInstance)
+   */
+  activeId: {
+    type: String,
+    default: null,
+  },
+
+  /**
+   * Compact mode (smaller padding/text)
+   */
+  compact: {
+    type: Boolean,
+    default: false,
+  },
+})
+
+const emit = defineEmits(['navigate', 'update:activeId'])
+
+// Compute items from navInstance or props
+const computedItems = computed(() => {
+  if (props.navInstance) {
+    return props.navInstance.visibleItems.value
+  }
+  return props.items.filter((item) => {
+    const hidden = typeof item.hidden === 'function' ? item.hidden() : item.hidden
+    return !hidden
+  })
+})
+
+// Compute active ID from navInstance or props
+const computedActiveId = computed(() => {
+  if (props.navInstance) {
+    return props.navInstance.activeId.value
+  }
+  return props.activeId
+})
+
+// Check if item is active
+function isItemActive(item) {
+  if (props.navInstance) {
+    return props.navInstance.isActive(item)
+  }
+  return item.id === props.activeId
+}
+
+// Check if item is disabled
+function isItemDisabled(item) {
+  if (props.navInstance) {
+    return props.navInstance.isDisabled(item)
+  }
+  const disabled = typeof item.disabled === 'function' ? item.disabled() : item.disabled
+  return disabled
+}
+
+// Handle navigation
+async function handleNavigate(item) {
+  if (isItemDisabled(item)) return
+
+  if (props.navInstance) {
+    await props.navInstance.navigateTo(item)
+  }
+
+  emit('navigate', item)
+  emit('update:activeId', item.id)
+}
+
+// Container classes based on layout
+const containerClasses = computed(() => {
+  const base = 'spark-sub-nav'
+  const layoutClasses = {
+    tabs: 'flex items-center gap-1 -mb-px',
+    vertical: 'flex flex-col gap-1',
+    horizontal: '', // SparkButtonGroup handles its own styling
+    custom: '',
+  }
+  return [base, layoutClasses[props.layout]]
+})
+
+// Icon classes
+const iconClasses = computed(() => {
+  return props.compact ? 'text-sm' : ''
+})
+
+// Get classes for nav item (tabs and vertical only)
+function getItemClasses(item) {
+  const isActive = isItemActive(item)
+  const isDisabled = isItemDisabled(item)
+
+  const base = [
+    'inline-flex items-center transition-colors cursor-pointer',
+    'focus:outline-none focus-visible:ring-2 focus-visible:ring-primary-500 focus-visible:ring-offset-1',
+  ]
+
+  // Disabled state
+  if (isDisabled) {
+    base.push('opacity-50 cursor-not-allowed')
+  }
+
+  // Layout-specific styles
+  if (props.layout === 'tabs') {
+    base.push(...getTabsClasses(isActive, isDisabled))
+  } else if (props.layout === 'vertical') {
+    base.push(...getVerticalClasses(isActive, isDisabled))
+  }
+
+  return base
+}
+
+// Tabs layout (underline style)
+function getTabsClasses(isActive, isDisabled) {
+  const classes = ['border-b-2 -mb-px rounded-t font-medium']
+
+  // Size classes
+  const sizeClasses = props.compact ? 'text-sm px-3 py-1.5' : 'text-sm px-8 py-4'
+  classes.push(sizeClasses)
+
+  if (isActive) {
+    classes.push('border-primary-600 text-primary-600')
+  } else if (!isDisabled) {
+    classes.push('border-transparent text-gray-600 hover:text-gray-900 hover:border-gray-300')
+  } else {
+    classes.push('border-transparent text-gray-400')
+  }
+
+  return classes
+}
+
+// Vertical layout (simplified with checkmark)
+function getVerticalClasses(isActive, isDisabled) {
+  const classes = ['font-medium text-sm py-1']
+
+  if (isActive) {
+    classes.push('text-primary-600')
+  } else if (!isDisabled) {
+    classes.push('text-gray-600 hover:text-gray-900')
+  } else {
+    classes.push('text-gray-400')
+  }
+
+  return classes
+}
+
+// Badge classes
+function getBadgeClasses(item) {
+  const variant = item.badgeVariant || 'primary'
+  const variants = {
+    primary: 'bg-primary-100 text-primary-700',
+    secondary: 'bg-gray-100 text-gray-700',
+    success: 'bg-green-100 text-green-700',
+    warning: 'bg-yellow-100 text-yellow-700',
+    danger: 'bg-red-100 text-red-700',
+  }
+
+  return ['ml-2 px-2 py-0.5 text-xs font-medium rounded-full', variants[variant] || variants.primary]
+}
+</script>

package/src/components/index.js

@@ -10,6 +10,7 @@ export { default as SparkImageUpload } from './SparkImageUpload.vue'
 export { default as SparkModalContainer } from './SparkModalContainer.vue'
 export { default as SparkModalDialog } from './SparkModalDialog.vue'
 export { default as SparkOverlay } from './SparkOverlay.vue'
+export { default as SparkSubNav } from './SparkSubNav.vue'
 export { default as SparkTable } from './SparkTable.vue'
 export { default as SparkTablePaginationPaging } from './SparkTablePaginationPaging.vue'
 export { default as SparkTablePaginationPerPage } from './SparkTablePaginationPerPage.vue'

package/src/composables/index.js

@@ -3,4 +3,11 @@ export { sparkNotificationService } from './sparkNotificationService.js'
 export { sparkOverlayService } from './sparkOverlayService.js'
 export { useSparkOverlay } from './useSparkOverlay.js'
 export { useSparkTableRouteSync } from './useSparkTableRouteSync.js'
-export { useFormSubmission } from './useFormSubmission.js'
+export { useFormSubmission } from './useFormSubmission.js'
+export { useSubNavigation } from './useSubNavigation.js'
+export {
+  useFormDirtyGuard,
+  hasAnyDirtyForm,
+  getDirtyFormMessage,
+  clearAllDirtyForms,
+} from './useFormDirtyGuard.js'

package/src/composables/sparkNotificationService.js

@@ -24,6 +24,8 @@ function createNotificationOutlet() {
     props: {},
     closeable: true,
     duration: null,
+    persistent: false,
+    shownOnPath: null,
   })
 
   // Timer state (not reactive, internal only)
@@ -90,6 +92,7 @@ function createNotificationOutlet() {
       props = {},
       closeable = true,
       duration = null,
+      persistent = false,
     } = options
 
     state.type = type
@@ -97,6 +100,7 @@ function createNotificationOutlet() {
     state.component = component ? markRaw(component) : null
     state.props = props
     state.closeable = closeable
+    state.persistent = persistent
     state.isVisible = true
 
     // Determine duration: explicit > default for type
@@ -116,6 +120,8 @@ function createNotificationOutlet() {
     state.props = {}
     state.closeable = true
     state.duration = null
+    state.persistent = false
+    state.shownOnPath = null
   }
 
   return {
@@ -187,6 +193,7 @@ class SparkNotificationService {
    * @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 {boolean} options.persistent - Whether notification survives route changes (default: false)
    * @param {string} outletName - Target outlet name (default: 'default')
    */
   show(options = {}, outletName = 'default') {
@@ -212,6 +219,18 @@ class SparkNotificationService {
     }
   }
 
+  /**
+   * Hide all non-persistent banner notifications
+   * Called by setupNotificationGuard on route change
+   */
+  hideAllNonPersistent() {
+    for (const outlet of this.outlets.values()) {
+      if (!outlet.state.persistent) {
+        outlet.hide()
+      }
+    }
+  }
+
   /**
    * Pause auto-dismiss timer for the specified banner outlet
    * @param {string} outletName - Target outlet name (default: 'default')

package/src/composables/useFormDirtyGuard.js

@@ -0,0 +1,211 @@
+import { ref, onUnmounted } from 'vue'
+import { onBeforeRouteLeave } from 'vue-router'
+import { sparkModalService } from './sparkModalService.js'
+
+/**
+ * Global registry of dirty form instances.
+ * Each entry maps a unique ID to its dirty state and message.
+ */
+const dirtyFormRegistry = new Map()
+
+/**
+ * Counter for generating unique form IDs
+ */
+let formIdCounter = 0
+
+/**
+ * Check if any form in the registry is dirty
+ * @returns {boolean}
+ */
+export function hasAnyDirtyForm() {
+  for (const entry of dirtyFormRegistry.values()) {
+    if (entry.isDirty) {
+      return true
+    }
+  }
+  return false
+}
+
+/**
+ * Get the first dirty form's message (for display in confirmation dialog)
+ * @returns {string|null}
+ */
+export function getDirtyFormMessage() {
+  for (const entry of dirtyFormRegistry.values()) {
+    if (entry.isDirty && entry.message) {
+      return entry.message
+    }
+  }
+  return null
+}
+
+/**
+ * Clear all dirty states (useful for testing or forced navigation)
+ */
+export function clearAllDirtyForms() {
+  for (const entry of dirtyFormRegistry.values()) {
+    entry.isDirty = false
+  }
+}
+
+/**
+ * Composable for tracking dirty form state with route guard and browser warning support.
+ *
+ * This composable is completely independent of sub-navigation - use it on any page with forms.
+ *
+ * @param {Object} options - Configuration options
+ * @param {string} [options.message='You have unsaved changes. Leave anyway?'] - Confirmation message
+ * @param {string} [options.title='Unsaved Changes'] - Confirmation dialog title
+ * @param {string} [options.confirmText='Leave'] - Confirm button text
+ * @param {string} [options.cancelText='Stay'] - Cancel button text
+ * @param {boolean} [options.useRouteGuard=true] - Whether to use onBeforeRouteLeave guard
+ * @returns {Object} Form dirty guard utilities
+ *
+ * @example
+ * const {
+ *   isDirty,
+ *   setDirty,
+ *   setClean,
+ *   checkDirty,
+ *   enableBrowserWarning,
+ *   disableBrowserWarning
+ * } = useFormDirtyGuard({
+ *   message: 'You have unsaved changes. Leave anyway?'
+ * })
+ *
+ * // On form input change
+ * const handleChange = () => setDirty()
+ *
+ * // After successful save
+ * const handleSave = async () => {
+ *   await saveData()
+ *   setClean()
+ * }
+ *
+ * // Enable browser close/reload warning
+ * onMounted(() => enableBrowserWarning())
+ * onUnmounted(() => disableBrowserWarning())
+ */
+export function useFormDirtyGuard(options = {}) {
+  const {
+    message = 'You have unsaved changes. Leave anyway?',
+    title = 'Unsaved Changes',
+    confirmText = 'Leave',
+    cancelText = 'Stay',
+    useRouteGuard = true,
+  } = options
+
+  // Generate unique ID for this form instance
+  const formId = `form-${++formIdCounter}`
+
+  // Local reactive state
+  const isDirty = ref(false)
+
+  // Register in global registry
+  dirtyFormRegistry.set(formId, {
+    isDirty: false,
+    message,
+  })
+
+  /**
+   * Mark the form as dirty
+   * @param {boolean} [dirty=true] - Whether the form is dirty
+   */
+  const setDirty = (dirty = true) => {
+    isDirty.value = dirty
+    const entry = dirtyFormRegistry.get(formId)
+    if (entry) {
+      entry.isDirty = dirty
+    }
+  }
+
+  /**
+   * Mark the form as clean (no unsaved changes)
+   */
+  const setClean = () => {
+    setDirty(false)
+  }
+
+  /**
+   * Check if form is dirty and optionally show confirmation dialog
+   * @param {Object} [confirmOptions] - Override default confirmation options
+   * @returns {Promise<boolean>} - True if safe to proceed (clean or user confirmed), false if should stay
+   */
+  const checkDirty = async (confirmOptions = {}) => {
+    if (!isDirty.value) {
+      return true
+    }
+
+    const confirmed = await sparkModalService.confirm({
+      title: confirmOptions.title || title,
+      message: confirmOptions.message || message,
+      confirmText: confirmOptions.confirmText || confirmText,
+      cancelText: confirmOptions.cancelText || cancelText,
+      type: 'warning',
+    })
+
+    if (confirmed) {
+      // User chose to leave, clear dirty state
+      setClean()
+    }
+
+    return confirmed
+  }
+
+  // Browser beforeunload handler
+  let browserWarningEnabled = false
+  const handleBeforeUnload = (event) => {
+    if (isDirty.value) {
+      // Standard way to trigger browser's native "unsaved changes" dialog
+      event.preventDefault()
+      // Some browsers require returnValue to be set
+      event.returnValue = ''
+      return ''
+    }
+  }
+
+  /**
+   * Enable browser close/reload warning when form is dirty
+   */
+  const enableBrowserWarning = () => {
+    if (!browserWarningEnabled) {
+      window.addEventListener('beforeunload', handleBeforeUnload)
+      browserWarningEnabled = true
+    }
+  }
+
+  /**
+   * Disable browser close/reload warning
+   */
+  const disableBrowserWarning = () => {
+    if (browserWarningEnabled) {
+      window.removeEventListener('beforeunload', handleBeforeUnload)
+      browserWarningEnabled = false
+    }
+  }
+
+  // Setup route guard if enabled
+  if (useRouteGuard) {
+    onBeforeRouteLeave(async () => {
+      const canLeave = await checkDirty()
+      return canLeave
+    })
+  }
+
+  // Cleanup on unmount
+  onUnmounted(() => {
+    // Remove from registry
+    dirtyFormRegistry.delete(formId)
+    // Remove browser warning listener
+    disableBrowserWarning()
+  })
+
+  return {
+    isDirty,
+    setDirty,
+    setClean,
+    checkDirty,
+    enableBrowserWarning,
+    disableBrowserWarning,
+  }
+}