@wishbone-media/spark 0.29.0 → 0.30.0

package/src/composables/useSubNavigation.js

@@ -0,0 +1,225 @@
+import { ref, computed, watch, markRaw } from 'vue'
+import { useRouter, useRoute } from 'vue-router'
+import { sparkModalService } from './sparkModalService.js'
+import { sparkOverlayService } from './sparkOverlayService.js'
+
+/**
+ * Composable for managing sub-navigation state with support for routes, overlays, modals, and custom actions.
+ *
+ * @param {Object} options - Configuration options
+ * @param {Array} options.items - Navigation items array
+ * @param {string} [options.defaultId] - Default active item ID (falls back to first visible item)
+ * @returns {Object} Sub-navigation utilities
+ *
+ * @example
+ * const subNav = useSubNavigation({
+ *   items: [
+ *     { id: 'general', label: 'General', route: { name: 'brands.general' } },
+ *     { id: 'templates', label: 'Templates', route: { name: 'brands.templates' } },
+ *     { id: 'preview', label: 'Preview', overlay: { component: PreviewPanel, position: 'right' } },
+ *     { id: 'delete', label: 'Delete', action: () => confirmDelete(), icon: 'farTrash' },
+ *   ]
+ * })
+ *
+ * // Item structure:
+ * // {
+ * //   id: 'general',           // Unique identifier (required)
+ * //   label: 'General',        // Display text (required)
+ * //   icon: 'farGear',         // Optional FontAwesome icon key
+ * //   badge: 3,                // Optional badge (number or string)
+ * //   badgeVariant: 'primary', // Badge color variant (default: 'primary')
+ * //
+ * //   // Navigation type (choose one):
+ * //   route: { name: 'brands.general', params: { id } },  // Vue Router navigation
+ * //   overlay: { component, props, position, size },       // sparkOverlayService
+ * //   modal: { component, props },                         // sparkModalService
+ * //   action: () => {},                                    // Custom callback
+ * //
+ * //   // State (can be boolean or function returning boolean):
+ * //   disabled: false,
+ * //   hidden: false,
+ * // }
+ */
+export function useSubNavigation(options = {}) {
+  const { items: initialItems = [], defaultId = null } = options
+
+  const router = useRouter()
+  const route = useRoute()
+
+  // Reactive items list
+  const items = ref(initialItems.map(normalizeItem))
+
+  /**
+   * Normalize item to ensure consistent structure
+   */
+  function normalizeItem(item) {
+    return {
+      id: item.id,
+      label: item.label,
+      icon: item.icon || null,
+      badge: item.badge ?? null,
+      badgeVariant: item.badgeVariant || 'primary',
+      route: item.route || null,
+      overlay: item.overlay || null,
+      modal: item.modal || null,
+      action: item.action || null,
+      disabled: item.disabled ?? false,
+      hidden: item.hidden ?? false,
+    }
+  }
+
+  /**
+   * Evaluate a value that might be a function
+   */
+  function evaluate(value) {
+    return typeof value === 'function' ? value() : value
+  }
+
+  /**
+   * Get visible items (not hidden)
+   */
+  const visibleItems = computed(() => {
+    return items.value.filter(item => !evaluate(item.hidden))
+  })
+
+  /**
+   * Check if an item is disabled
+   */
+  function isDisabled(item) {
+    const itemObj = typeof item === 'string' ? items.value.find(i => i.id === item) : item
+    return itemObj ? evaluate(itemObj.disabled) : false
+  }
+
+  /**
+   * Check if an item is the currently active one (for route-based items)
+   */
+  function isActive(item) {
+    const itemObj = typeof item === 'string' ? items.value.find(i => i.id === item) : item
+    if (!itemObj || !itemObj.route) return false
+
+    // Handle route as string (route name) or object
+    const itemRoute = typeof itemObj.route === 'string'
+      ? { name: itemObj.route }
+      : itemObj.route
+
+    // Match by route name
+    if (itemRoute.name && route.name === itemRoute.name) {
+      return true
+    }
+
+    // Match by path if provided
+    if (itemRoute.path) {
+      const resolved = router.resolve(itemRoute)
+      return route.path === resolved.path
+    }
+
+    return false
+  }
+
+  /**
+   * Get the currently active item based on route matching
+   */
+  const activeItem = computed(() => {
+    // Find item matching current route
+    const matchedItem = visibleItems.value.find(item => isActive(item))
+    if (matchedItem) return matchedItem
+
+    // Fall back to default or first visible item
+    if (defaultId) {
+      return visibleItems.value.find(item => item.id === defaultId) || visibleItems.value[0]
+    }
+
+    return visibleItems.value[0] || null
+  })
+
+  /**
+   * Get the active item's ID
+   */
+  const activeId = computed(() => activeItem.value?.id || null)
+
+  /**
+   * Navigate to an item (route, overlay, modal, or action)
+   * @param {string|Object} item - Item ID or item object
+   * @returns {Promise<boolean>} - Whether navigation/action was executed
+   */
+  async function navigateTo(item) {
+    const itemObj = typeof item === 'string' ? items.value.find(i => i.id === item) : item
+
+    if (!itemObj) {
+      console.warn(`[useSubNavigation] Item not found: ${item}`)
+      return false
+    }
+
+    if (isDisabled(itemObj)) {
+      return false
+    }
+
+    // Handle route navigation
+    if (itemObj.route) {
+      const routeConfig = typeof itemObj.route === 'string'
+        ? { name: itemObj.route }
+        : itemObj.route
+      await router.push(routeConfig)
+      return true
+    }
+
+    // Handle overlay
+    if (itemObj.overlay) {
+      const { component, props = {}, eventHandlers = {}, position = 'right', size } = itemObj.overlay
+      const showMethod = position === 'left' ? 'showLeft' : 'showRight'
+      sparkOverlayService[showMethod](markRaw(component), props, eventHandlers, { size })
+      return true
+    }
+
+    // Handle modal
+    if (itemObj.modal) {
+      const { component, props = {}, eventHandlers = {} } = itemObj.modal
+      sparkModalService.show(markRaw(component), props, eventHandlers)
+      return true
+    }
+
+    // Handle custom action
+    if (itemObj.action) {
+      const result = itemObj.action(itemObj)
+      // Support async actions
+      if (result instanceof Promise) {
+        await result
+      }
+      return true
+    }
+
+    return false
+  }
+
+  /**
+   * Update items list
+   * @param {Array} newItems - New items array
+   */
+  function setItems(newItems) {
+    items.value = newItems.map(normalizeItem)
+  }
+
+  /**
+   * Update a single item
+   * @param {string} id - Item ID
+   * @param {Object} updates - Properties to update
+   */
+  function updateItem(id, updates) {
+    const index = items.value.findIndex(item => item.id === id)
+    if (index !== -1) {
+      items.value[index] = normalizeItem({ ...items.value[index], ...updates })
+    }
+  }
+
+  return {
+    items,
+    visibleItems,
+    activeItem,
+    activeId,
+    navigateTo,
+    isActive,
+    isDisabled,
+    setItems,
+    updateItem,
+  }
+}

package/src/plugins/fontawesome.js

@@ -43,6 +43,7 @@ import {
   faBolt,
   faCloudDownload,
   faInbox,
+  faCircleCheck,
   // Additional icons for FormKit genesis replacement
   faPlus,
   faArrowDown,
@@ -106,6 +107,7 @@ export const Icons = {
   farBolt: faBolt,
   farCloudDownload: faCloudDownload,
   farInbox: faInbox,
+  farCircleCheck: faCircleCheck,
 
   fadSort: faSortDuotone,
   fadSortDown: faSortDownDuotone,

package/src/plugins/index.js

@@ -1,4 +1,4 @@
 export { Icons, addIcons, setupFontAwesome, formKitIcons, formKitIconLoader, formKitGenesisOverride } from './fontawesome.js'
-export { createAuthRoutes, setupAuthGuards, create403Route, create404Route, setupBootstrapGuard } from './router.js'
+export { createAuthRoutes, setupAuthGuards, create403Route, create404Route, setupBootstrapGuard, setupDirtyFormGuard } from './router.js'
 export { createAxiosInstance, setupAxios, getAxiosInstance } from './axios.js'
 export { createBootstrapService } from './app-bootstrap.js'

package/src/plugins/router.js

@@ -1,4 +1,6 @@
 import { useSparkAuthStore } from '../stores/auth.js'
+import { hasAnyDirtyForm, getDirtyFormMessage, clearAllDirtyForms } from '../composables/useFormDirtyGuard.js'
+import { sparkModalService } from '../composables/sparkModalService.js'
 import {
   SparkLoginView,
   SparkLogoutView,
@@ -212,3 +214,64 @@ export function setupBootstrapGuard(router, bootstrapFn) {
     }
   })
 }
+
+/**
+ * Setup global dirty form guard to warn users before navigating away from unsaved changes.
+ *
+ * This guard checks a global registry of dirty forms and shows a confirmation dialog
+ * using sparkModalService when attempting to navigate away with unsaved changes.
+ *
+ * IMPORTANT: This should be called AFTER setupAuthGuards() and setupBootstrapGuard()
+ *
+ * @param {Router} router - Vue router instance
+ * @param {Object} [options] - Configuration options
+ * @param {string} [options.title='Unsaved Changes'] - Dialog title
+ * @param {string} [options.message='You have unsaved changes. Leave anyway?'] - Default message (can be overridden per-form)
+ * @param {string} [options.confirmText='Leave'] - Confirm button text
+ * @param {string} [options.cancelText='Stay'] - Cancel button text
+ *
+ * @example
+ * import { setupAuthGuards, setupBootstrapGuard, setupDirtyFormGuard } from '@wishbone-media/spark'
+ *
+ * // Setup guards in order
+ * setupAuthGuards(router)
+ * setupBootstrapGuard(router, bootstrapApp)
+ * setupDirtyFormGuard(router)
+ */
+export function setupDirtyFormGuard(router, options = {}) {
+  const {
+    title = 'Unsaved Changes',
+    message = 'You have unsaved changes. Leave anyway?',
+    confirmText = 'Leave',
+    cancelText = 'Stay',
+  } = options
+
+  router.beforeEach(async (_to, _from, next) => {
+    // Check if any form has unsaved changes
+    if (!hasAnyDirtyForm()) {
+      next()
+      return
+    }
+
+    // Get the message from the first dirty form, or use default
+    const displayMessage = getDirtyFormMessage() || message
+
+    // Show confirmation dialog
+    const confirmed = await sparkModalService.confirm({
+      title,
+      message: displayMessage,
+      confirmText,
+      cancelText,
+      type: 'warning',
+    })
+
+    if (confirmed) {
+      // User chose to leave, clear all dirty states and proceed
+      clearAllDirtyForms()
+      next()
+    } else {
+      // User chose to stay, cancel navigation
+      next(false)
+    }
+  })
+}