@quazardous/qdadm 1.19.3

package/src/composables/useSemanticBreadcrumb.ts

@@ -0,0 +1,222 @@
+import { computed, type ComputedRef } from 'vue'
+import { useRoute, useRouter, type RouteRecordNormalized, type RouteLocationNormalized } from 'vue-router'
+
+/**
+ * Semantic breadcrumb item kinds
+ */
+export type SemanticBreadcrumbKind =
+  | 'route'
+  | 'entity-list'
+  | 'entity-show'
+  | 'entity-edit'
+  | 'entity-create'
+  | 'entity-delete'
+
+/**
+ * Semantic breadcrumb item
+ */
+export interface SemanticBreadcrumbItem {
+  kind: SemanticBreadcrumbKind
+  entity?: string
+  id?: string
+  route?: string
+  label?: string
+}
+
+/**
+ * Action segments mapping to entity kinds
+ */
+const ACTION_MAP: Record<string, SemanticBreadcrumbKind> = {
+  edit: 'entity-edit',
+  create: 'entity-create',
+  new: 'entity-create',
+  show: 'entity-show',
+  view: 'entity-show',
+  delete: 'entity-delete',
+}
+
+/**
+ * Compute semantic breadcrumb from route path and routes list
+ *
+ * Pure function that can be used both in Vue composables and outside components.
+ *
+ * If the matched route has `meta.breadcrumb`, that array is used directly.
+ * This allows routes to define a custom breadcrumb structure.
+ *
+ * @param path - Current route path (e.g., '/books/1/edit')
+ * @param routes - List of all registered routes from router.getRoutes()
+ * @param currentRoute - Current route object (optional, for meta.breadcrumb support)
+ * @returns Semantic breadcrumb items
+ */
+export function computeSemanticBreadcrumb(
+  path: string,
+  routes: RouteRecordNormalized[],
+  currentRoute: RouteLocationNormalized | null = null
+): SemanticBreadcrumbItem[] {
+  if (!path) return []
+
+  // Check if route defines a custom breadcrumb
+  if (currentRoute?.meta?.breadcrumb) {
+    return currentRoute.meta.breadcrumb as SemanticBreadcrumbItem[]
+  }
+
+  const items: SemanticBreadcrumbItem[] = []
+
+  // Filter out catch-all and not-found routes
+  const validRoutes = routes.filter(
+    (r) => r.name !== 'not-found' && !r.path.includes('*') && !r.path.includes(':pathMatch')
+  )
+
+  // Note: Home is NOT included in semantic breadcrumb
+  // It's a display concern - add it in useBreadcrumb if needed
+
+  const segments = path.split('/').filter(Boolean)
+  let currentPath = ''
+  let lastEntity: string | null = null
+  let pendingId: string | null = null // Track unmatched segments that could be IDs
+
+  for (let i = 0; i < segments.length; i++) {
+    const segment = segments[i]
+    const nextSegment = segments[i + 1]
+    if (!segment) continue
+    currentPath += `/${segment}`
+
+    // Check if this is an action segment
+    const actionKind = ACTION_MAP[segment.toLowerCase()]
+    if (actionKind && lastEntity) {
+      // If we have a pending ID, add a new entity item with action kind
+      if (pendingId) {
+        items.push({ kind: actionKind, entity: lastEntity, id: pendingId })
+        pendingId = null
+      } else {
+        // No pending ID - update last item's kind (e.g., /books/create)
+        const lastItem = items[items.length - 1]
+        if (lastItem && lastItem.kind.startsWith('entity-') && !lastItem.id) {
+          lastItem.kind = actionKind
+        }
+      }
+      continue
+    }
+
+    // Find matching route
+    const matchedRoute = validRoutes.find((r) => {
+      if (r.path === currentPath) return true
+      const routeSegs = r.path.split('/').filter(Boolean)
+      const pathSegs = currentPath.split('/').filter(Boolean)
+      if (routeSegs.length !== pathSegs.length) return false
+      return routeSegs.every((rs, idx) => rs.startsWith(':') || rs === pathSegs[idx])
+    })
+
+    if (!matchedRoute) {
+      // No route found - this segment could be an ID (e.g., /books/1 when route is /books/:id/edit)
+      if (lastEntity && segment) {
+        pendingId = segment
+      }
+      continue
+    }
+
+    const entity = matchedRoute.meta?.entity as string | null
+    const isParam = matchedRoute.path
+      .split('/')
+      .filter(Boolean)
+      .some((s, idx) => {
+        const pathSegs = currentPath.split('/').filter(Boolean)
+        return s.startsWith(':') && idx === pathSegs.length - 1
+      })
+
+    if (entity) {
+      lastEntity = entity
+      pendingId = null // Clear pending ID when we match a route
+      if (isParam) {
+        // Entity instance - get param value (the ID)
+        const paramValue = segment
+        // Determine kind based on next segment or route name
+        let kind: SemanticBreadcrumbKind = 'entity-show'
+        const nextAction = nextSegment ? ACTION_MAP[nextSegment.toLowerCase()] : undefined
+        if (nextAction) {
+          kind = nextAction
+        } else if ((matchedRoute.name as string)?.includes('edit')) {
+          kind = 'entity-edit'
+        }
+        items.push({ kind, entity, id: paramValue, route: matchedRoute.name as string })
+      } else {
+        // Entity list - include route name for child routes (e.g., 'bot-command' vs 'commands')
+        items.push({ kind: 'entity-list', entity, route: matchedRoute.name as string })
+      }
+    } else {
+      // Flush pending ID as entity-show before generic route
+      if (pendingId && lastEntity) {
+        items.push({ kind: 'entity-show', entity: lastEntity, id: pendingId })
+        pendingId = null
+      }
+      // Generic route
+      items.push({ kind: 'route', route: (matchedRoute.name as string) || segment })
+    }
+  }
+
+  return items
+}
+
+/**
+ * Return type for useSemanticBreadcrumb
+ */
+export interface UseSemanticBreadcrumbReturn {
+  breadcrumb: ComputedRef<SemanticBreadcrumbItem[]>
+  isEntityActive: (entity: string) => boolean
+  activeEntity: ComputedRef<string | null>
+}
+
+/**
+ * useSemanticBreadcrumb - Vue composable for semantic breadcrumb
+ *
+ * Returns semantic objects per level - adapters resolve labels/paths for display.
+ *
+ * Kinds:
+ * - route: Generic route (e.g., home, dashboard)
+ * - entity-list: Entity collection (e.g., /books)
+ * - entity-show: Entity instance view (e.g., /books/1)
+ * - entity-edit: Entity instance edit (e.g., /books/1/edit)
+ * - entity-create: Entity creation (e.g., /books/create)
+ *
+ * @example
+ * const { breadcrumb } = useSemanticBreadcrumb()
+ * // For /books/1/edit returns:
+ * // [
+ * //   { kind: 'route', route: 'home' },
+ * //   { kind: 'entity-list', entity: 'books' },
+ * //   { kind: 'entity-edit', entity: 'books', id: '1' }
+ * // ]
+ */
+export function useSemanticBreadcrumb(): UseSemanticBreadcrumbReturn {
+  const route = useRoute()
+  const router = useRouter()
+
+  const breadcrumb = computed(() => {
+    return computeSemanticBreadcrumb(route.path, router.getRoutes(), route)
+  })
+
+  /**
+   * Check if an entity is active (present in current breadcrumb)
+   * Useful for menu highlighting
+   *
+   * @param entity - Entity name to check
+   * @returns True if entity is in breadcrumb
+   */
+  function isEntityActive(entity: string): boolean {
+    return breadcrumb.value.some((item) => item.kind.startsWith('entity-') && item.entity === entity)
+  }
+
+  /**
+   * Get the active entity from breadcrumb (first entity found)
+   */
+  const activeEntity = computed(() => {
+    const entityItem = breadcrumb.value.find((item) => item.kind.startsWith('entity-'))
+    return entityItem?.entity || null
+  })
+
+  return {
+    breadcrumb,
+    isEntityActive,
+    activeEntity,
+  }
+}

package/src/composables/useSidebarState.ts

@@ -0,0 +1,24 @@
+/**
+ * useSidebarState - Access sidebar collapsed state from any component
+ *
+ * The sidebar collapsed ref is provided by AppLayout via Vue's provide/inject.
+ * This composable gives blocks rendered inside the sidebar (including zone blocks)
+ * programmatic access to the collapsed state.
+ *
+ * @example
+ * ```ts
+ * import { useSidebarState } from '@quazardous/qdadm'
+ *
+ * const { collapsed } = useSidebarState()
+ * // collapsed.value === true when sidebar is in icon-only mode
+ * ```
+ */
+
+import { inject, ref, type Ref } from 'vue'
+
+export const SIDEBAR_COLLAPSED_KEY = Symbol('qdadm-sidebar-collapsed') as symbol & { __type: Ref<boolean> }
+
+export function useSidebarState(): { collapsed: Ref<boolean> } {
+  const collapsed = inject<Ref<boolean>>(SIDEBAR_COLLAPSED_KEY, ref(false))
+  return { collapsed }
+}

package/src/composables/useSignals.ts

@@ -0,0 +1,52 @@
+/**
+ * useSignals - Access the signal bus for event-driven communication
+ *
+ * Provides access to the SignalBus created by Kernel during bootstrap.
+ * Components can subscribe to signals without direct imports.
+ *
+ * @returns The signal bus instance or null if not available
+ *
+ * @example
+ * // Basic usage
+ * const signals = useSignals()
+ * signals.on('entity:created', (payload) => {
+ *   console.log('Entity created:', payload.entity, payload.data)
+ * })
+ *
+ * @example
+ * // Subscribe to specific entity
+ * const signals = useSignals()
+ * signals.on('books:updated', ({ data }) => {
+ *   refreshBookList()
+ * })
+ *
+ * @example
+ * // Wildcard subscription
+ * const signals = useSignals()
+ * signals.on('*:deleted', ({ entity, data }) => {
+ *   showDeletedNotification(entity)
+ * })
+ *
+ * @example
+ * // Auto-cleanup on unmount
+ * import { onUnmounted } from 'vue'
+ *
+ * const signals = useSignals()
+ * const unbind = signals.on('entity:created', handler)
+ * onUnmounted(() => unbind())
+ */
+import { inject } from 'vue'
+import type { SignalBus } from '../kernel/SignalBus'
+
+export function useSignals(): SignalBus | null {
+  const signals = inject<SignalBus | null>('qdadmSignals', null)
+
+  if (!signals) {
+    console.warn(
+      '[qdadm] useSignals: signal bus not available. Ensure Kernel is initialized.'
+    )
+    return null
+  }
+
+  return signals
+}

package/src/composables/useUnsavedChangesGuard.ts

@@ -0,0 +1,155 @@
+/**
+ * Composable for guarding against unsaved changes when leaving a page
+ *
+ * Usage:
+ * const { dirty, takeSnapshot, checkDirty } = useDirtyState(...)
+ * useUnsavedChangesGuard(dirty, {
+ *   onSave: () => handleSubmit(false),
+ *   message: 'You have unsaved changes.'
+ * })
+ */
+
+import { onBeforeUnmount, ref, type Ref } from 'vue'
+import { onBeforeRouteLeave, type NavigationGuardNext } from 'vue-router'
+
+/**
+ * Guard dialog state
+ */
+export interface GuardDialogState {
+  visible: Ref<boolean>
+  saving: Ref<boolean>
+  message: string
+  hasOnSave: boolean
+  onSaveAndLeave: () => Promise<void>
+  onLeave: () => void
+  onStay: () => void
+}
+
+/**
+ * Options for useUnsavedChangesGuard
+ */
+export interface UseUnsavedChangesGuardOptions {
+  /** Async function to save changes */
+  onSave?: (() => Promise<void>) | null
+  /** Custom message */
+  message?: string
+  /** Show native browser dialog on tab close (default: false) */
+  browserGuard?: boolean
+}
+
+/**
+ * Return type for useUnsavedChangesGuard
+ */
+export interface UseUnsavedChangesGuardReturn {
+  dirty: Ref<boolean>
+  guardDialog: GuardDialogState
+}
+
+/**
+ * Guard against leaving page with unsaved changes
+ *
+ * Shows a dialog with up to 3 options:
+ * - "Save & Leave" (if onSave provided) - saves then navigates
+ * - "Leave" - navigates without saving (discards changes)
+ * - "Stay" - cancels navigation
+ *
+ * @param dirty - Reactive dirty state
+ * @param options - Options
+ */
+export function useUnsavedChangesGuard(
+  dirty: Ref<boolean>,
+  options: UseUnsavedChangesGuardOptions = {}
+): UseUnsavedChangesGuardReturn {
+  const {
+    onSave = null,
+    message = 'You have unsaved changes that will be lost.',
+    browserGuard = false, // Disabled by default - use soft JS modal only
+  } = options
+
+  // State for custom dialog
+  const showDialog = ref(false)
+  const pendingNext = ref<NavigationGuardNext | null>(null)
+  const saving = ref(false)
+
+  // Browser beforeunload event (for closing tab/window) - optional
+  function handleBeforeUnload(e: BeforeUnloadEvent): string | void {
+    if (dirty.value) {
+      e.preventDefault()
+      e.returnValue = message
+      return message
+    }
+  }
+
+  // Add browser event listener only if browserGuard is enabled
+  if (browserGuard && typeof window !== 'undefined') {
+    window.addEventListener('beforeunload', handleBeforeUnload)
+  }
+
+  // Clean up on unmount
+  onBeforeUnmount(() => {
+    if (browserGuard && typeof window !== 'undefined') {
+      window.removeEventListener('beforeunload', handleBeforeUnload)
+    }
+  })
+
+  // Dialog actions
+  async function handleSaveAndLeave(): Promise<void> {
+    if (!onSave || !pendingNext.value) return
+
+    saving.value = true
+    try {
+      await onSave()
+      showDialog.value = false
+      pendingNext.value()
+      pendingNext.value = null
+    } catch (e) {
+      console.error('Save failed:', e)
+      // Stay on page - don't close dialog, let user retry or choose Leave
+    } finally {
+      saving.value = false
+    }
+  }
+
+  function handleLeave(): void {
+    if (!pendingNext.value) return
+    showDialog.value = false
+    pendingNext.value()
+    pendingNext.value = null
+  }
+
+  function handleStay(): void {
+    showDialog.value = false
+    if (pendingNext.value) {
+      pendingNext.value(false)
+      pendingNext.value = null
+    }
+  }
+
+  // Vue Router navigation guard
+  onBeforeRouteLeave((_to, _from, next) => {
+    if (!dirty.value) {
+      next()
+      return
+    }
+
+    // Store the next callback and show dialog
+    pendingNext.value = next
+    showDialog.value = true
+  })
+
+  return {
+    dirty,
+    // Dialog state and handlers for custom dialog component
+    guardDialog: {
+      visible: showDialog,
+      saving,
+      message,
+      hasOnSave: !!onSave,
+      onSaveAndLeave: handleSaveAndLeave,
+      onLeave: handleLeave,
+      onStay: handleStay,
+    },
+  }
+}
+
+export default useUnsavedChangesGuard