@quazardous/qdadm 1.19.3

package/src/composables/useAuth.ts

@@ -0,0 +1,98 @@
+/**
+ * useAuth - Access authentication state (component-only)
+ *
+ * Provides access to authAdapter set via createQdadm bootstrap.
+ * Returns neutral values if auth is disabled.
+ *
+ * IMPORTANT: Must be called within component setup() function.
+ * For route guards or services, use authAdapter directly.
+ *
+ * Reactivity:
+ * - Kernel.invalidateApp() remounts entire app on auth changes
+ * - Composable is re-initialized with fresh state
+ * - No signal listeners needed
+ *
+ * Note: Permission checking (canRead/canWrite) is handled by EntityManager,
+ * not by useAuth. This keeps auth simple and delegates permission logic
+ * to where it belongs (the entity layer).
+ *
+ * Usage:
+ *   const { isAuthenticated, user, logout } = useAuth()
+ */
+
+import { inject, computed, ref, getCurrentInstance, type ComputedRef, type Ref } from 'vue'
+
+/**
+ * Features configuration interface
+ */
+interface FeaturesConfig {
+  auth?: boolean
+  [key: string]: unknown
+}
+
+/**
+ * Auth adapter interface
+ */
+interface AuthAdapter {
+  login: (credentials?: unknown) => Promise<{ token: string | null; user: unknown }>
+  logout: () => void
+  getCurrentUser: () => Promise<unknown>
+  isAuthenticated: () => boolean
+  getUser?: () => unknown
+  user?: unknown
+}
+
+/**
+ * Return type for useAuth
+ */
+export interface UseAuthReturn {
+  login: (credentials?: unknown) => Promise<{ token: string | null; user: unknown }>
+  logout: () => void
+  getCurrentUser: () => Promise<unknown>
+  isAuthenticated: ComputedRef<boolean>
+  user: ComputedRef<unknown> | Ref<null>
+  authEnabled: boolean
+}
+
+export function useAuth(): UseAuthReturn {
+  // Strict context check - must be called in component setup()
+  const instance = getCurrentInstance()
+  if (!instance) {
+    throw new Error('[qdadm] useAuth() must be called within component setup()')
+  }
+
+  const auth = inject<AuthAdapter | null>('authAdapter')
+  const features = inject<FeaturesConfig | null>('qdadmFeatures')
+
+  // If auth disabled or not provided, return neutral values
+  if (!features?.auth || !auth) {
+    return {
+      login: () => Promise.resolve({ token: null, user: null }),
+      logout: () => {},
+      getCurrentUser: () => Promise.resolve(null),
+      isAuthenticated: computed(() => true), // Always "authenticated"
+      user: ref(null),
+      authEnabled: false,
+    }
+  }
+
+  // Note: Auth signal listeners removed - Kernel.invalidateApp() remounts entire app
+  // on auth changes, so composable is re-initialized with fresh state
+
+  // User state - reads current value from authAdapter
+  const user = computed(() => {
+    if (typeof auth.getUser === 'function') {
+      return auth.getUser()
+    }
+    return auth.user || null
+  })
+
+  return {
+    login: auth.login,
+    logout: auth.logout,
+    getCurrentUser: auth.getCurrentUser,
+    isAuthenticated: computed(() => auth.isAuthenticated()),
+    user,
+    authEnabled: true,
+  }
+}

package/src/composables/useBareForm.ts

@@ -0,0 +1,319 @@
+/**
+ * useBareForm - Base form composable providing common form functionality
+ *
+ * Usage:
+ *   const {
+ *     // State
+ *     loading, saving, dirty, isEdit, entityId,
+ *     // Dirty tracking
+ *     isFieldDirty, takeSnapshot, checkDirty,
+ *     // Helpers
+ *     router, route, toast, cancel
+ *   } = useBareForm({
+ *     getState: () => ({ form: form.value }),
+ *     routePrefix: 'agents',    // for cancel() navigation
+ *     entityName: 'Agent',      // for auto-title (optional, or use 'entity' for auto-lookup)
+ *     labelField: 'name',       // field to use as entity label (optional)
+ *     entity: 'agents',         // EntityManager name for auto metadata (optional)
+ *     guard: true,              // enable unsaved changes modal
+ *     onGuardSave: () => save() // optional save callback for guard modal
+ *   })
+ *
+ * This composable provides:
+ * - Dirty state tracking (form-level and field-level)
+ * - isFieldDirty for child FormField components via inject
+ * - Unsaved changes guard modal
+ * - Common state refs (loading, saving)
+ * - Common computed (isEdit, entityId)
+ * - Navigation helpers (cancel)
+ * - Access to router, route, toast
+ * - Auto page title via provide (for PageHeader)
+ */
+import { ref, computed, provide, inject, onUnmounted, type Ref, type ComputedRef } from 'vue'
+import { useRoute, useRouter, type Router, type RouteLocationNormalizedLoaded } from 'vue-router'
+import { useDirtyState } from './useDirtyState'
+import { useUnsavedChangesGuard, type GuardDialogState } from './useUnsavedChangesGuard'
+import { useBreadcrumb, type BreadcrumbDisplayItem } from './useBreadcrumb'
+import { registerGuardDialog, unregisterGuardDialog } from './useGuardStore'
+
+/**
+ * Entity manager interface (minimal for this composable)
+ */
+interface EntityManager {
+  label?: string
+  labelField?: string
+  getEntityLabel: (data: unknown) => string
+}
+
+/**
+ * Orchestrator interface
+ */
+interface Orchestrator {
+  get: (entityName: string) => EntityManager
+  toast: {
+    success: (summary: string, detail?: string, emitter?: unknown) => void
+    error: (summary: string, detail?: string, emitter?: unknown) => void
+    warn: (summary: string, detail?: string, emitter?: unknown) => void
+    info: (summary: string, detail?: string, emitter?: unknown) => void
+  }
+}
+
+/**
+ * Toast helper interface
+ */
+interface ToastHelper {
+  add: (options: {
+    severity: 'success' | 'error' | 'warn' | 'info'
+    summary: string
+    detail?: string
+    emitter?: unknown
+  }) => void
+}
+
+/**
+ * Page title parts for PageHeader
+ */
+interface PageTitleParts {
+  action: string
+  entityName: string | null
+  entityLabel: string | null
+}
+
+/**
+ * Options for useBareForm
+ */
+export interface UseBareFormOptions {
+  /** Function returning current form state for comparison */
+  getState: () => Record<string, unknown>
+  /** Route name for cancel navigation (default: '') */
+  routePrefix?: string
+  /** Display name for entity (default: from manager or derived from routePrefix) */
+  entityName?: string | null
+  /** Field name or function to extract entity label (default: from manager or 'name') */
+  labelField?: string | ((data: unknown) => string) | null
+  /** EntityManager name (string) for auto metadata, OR entity data (Ref/Object) for breadcrumb */
+  entity?: string | Ref<unknown> | Record<string, unknown> | null
+  /** Enable unsaved changes guard (default: true) */
+  guard?: boolean
+  /** Callback for save button in guard modal */
+  onGuardSave?: (() => Promise<void>) | null
+  /** Custom function to extract entity ID from route (optional) */
+  getId?: (() => string | number | null) | null
+  /** Callback (entity) => string for custom breadcrumb label (optional) */
+  breadcrumbLabel?: ((entity: unknown) => string) | null
+}
+
+/**
+ * Return type for useBareForm
+ */
+export interface UseBareFormReturn {
+  // Dependencies (for custom logic in form)
+  router: Router
+  route: RouteLocationNormalizedLoaded
+  toast: ToastHelper
+
+  // Manager (if resolved from entity string)
+  manager: EntityManager | null
+
+  // State
+  loading: Ref<boolean>
+  saving: Ref<boolean>
+  dirty: Ref<boolean>
+  dirtyFields: Ref<string[]>
+  isEdit: ComputedRef<boolean>
+  entityId: ComputedRef<string | number | null>
+
+  // Dirty tracking
+  isFieldDirty: (fieldPath: string) => boolean
+  takeSnapshot: () => void
+  checkDirty: () => void
+  reset: () => void
+
+  // Helpers
+  cancel: () => void
+
+  // Breadcrumb
+  breadcrumb: ComputedRef<BreadcrumbDisplayItem[]>
+
+  // Guard dialog (for UnsavedChangesDialog component)
+  guardDialog: GuardDialogState | null
+
+  // Title helpers
+  pageTitleParts: ComputedRef<PageTitleParts>
+}
+
+/**
+ * Base form composable providing common form functionality
+ *
+ * @param options - Configuration options
+ * @returns Form utilities and state
+ */
+export function useBareForm(options: UseBareFormOptions): UseBareFormReturn {
+  const {
+    getState,
+    routePrefix = '',
+    entityName = null,
+    labelField = null,
+    guard = true,
+    onGuardSave = null,
+    getId = null,
+    entity = null,
+    breadcrumbLabel = null,
+  } = options
+
+  if (!getState || typeof getState !== 'function') {
+    throw new Error('useBareForm requires a getState function')
+  }
+
+  // Try to get EntityManager metadata if entity is a string
+  let manager: EntityManager | null = null
+  if (typeof entity === 'string') {
+    const orchestrator = inject<Orchestrator | null>('qdadmOrchestrator', null)
+    if (orchestrator) {
+      try {
+        manager = orchestrator.get(entity)
+      } catch {
+        // Manager not found, continue without it
+      }
+    }
+  }
+
+  // Router, route, toast - common dependencies
+  const router = useRouter()
+  const route = useRoute()
+  const orchestrator = inject<Orchestrator | null>('qdadmOrchestrator', null)
+
+  // Toast helper - wraps orchestrator.toast for legacy compatibility
+  const toast: ToastHelper = {
+    add({ severity, summary, detail, emitter }) {
+      orchestrator?.toast[severity]?.(summary, detail, emitter)
+    },
+  }
+
+  // Common state
+  const loading = ref(false)
+  const saving = ref(false)
+
+  // Common computed
+  const entityId = computed(() => {
+    if (getId) return getId()
+    return (route.params.id as string | number) || (route.params.key as string | number) || null
+  })
+
+  const isEdit = computed(() => !!entityId.value)
+
+  // Dirty state tracking
+  const { dirty, dirtyFields, isFieldDirty, takeSnapshot, checkDirty, reset } =
+    useDirtyState(getState)
+
+  // Provide isFieldDirty and dirtyFields for child components (FormField)
+  provide('isFieldDirty', isFieldDirty)
+  provide('dirtyFields', dirtyFields)
+
+  // Resolve entityName: explicit > manager > derived from routePrefix
+  const derivedEntityName = routePrefix
+    ? routePrefix.charAt(0).toUpperCase() + routePrefix.slice(1).replace(/s$/, '')
+    : null
+  const effectiveEntityName = entityName || manager?.label || derivedEntityName
+
+  // Resolve labelField: explicit > manager > default 'name'
+  const effectiveLabelField = labelField || manager?.labelField || 'name'
+
+  // Provide entity context for child components (e.g., SeverityTag auto-discovery)
+  if (routePrefix) {
+    const entityNameForProvider = routePrefix.endsWith('s') ? routePrefix : routePrefix + 's'
+    provide('mainEntity', entityNameForProvider)
+  } else if (typeof entity === 'string') {
+    provide('mainEntity', entity)
+  }
+
+  // Auto page title parts for PageHeader
+  const getEntityLabel = (): string | null => {
+    const state = getState()
+    const formData = (state.form as Record<string, unknown>) || state
+    if (!formData) return null
+    // Use manager.getEntityLabel if available, otherwise use effectiveLabelField
+    if (manager) {
+      return manager.getEntityLabel(formData)
+    }
+    if (typeof effectiveLabelField === 'function') {
+      return effectiveLabelField(formData)
+    }
+    return (formData[effectiveLabelField as string] as string) || null
+  }
+
+  const pageTitleParts = computed<PageTitleParts>(() => ({
+    action: isEdit.value ? 'Edit' : 'Create',
+    entityName: effectiveEntityName,
+    entityLabel: isEdit.value ? getEntityLabel() : null,
+  }))
+
+  // Provide title parts for automatic PageHeader consumption
+  if (effectiveEntityName) {
+    provide('qdadmPageTitleParts', pageTitleParts)
+  }
+
+  // Breadcrumb (auto-generated from route path, with optional entity for dynamic labels)
+  // Only pass entity to breadcrumb if it's actual entity data (not a string manager name)
+  const breadcrumbEntity = typeof entity === 'string' ? null : entity
+  const { breadcrumbItems } = useBreadcrumb({
+    entity: breadcrumbEntity as unknown | Ref<unknown> | undefined,
+    getEntityLabel: breadcrumbLabel || undefined,
+  })
+
+  // Unsaved changes guard
+  let guardDialog: GuardDialogState | null = null
+  if (guard) {
+    const guardOptions = onGuardSave ? { onSave: onGuardSave } : {}
+    const guardResult = useUnsavedChangesGuard(dirty, guardOptions)
+    guardDialog = guardResult.guardDialog
+    // Register guardDialog in shared store so AppLayout can render it
+    registerGuardDialog(guardDialog)
+    onUnmounted(() => unregisterGuardDialog(guardDialog!))
+  }
+
+  // Navigation helper
+  function cancel(): void {
+    if (routePrefix) {
+      router.push({ name: routePrefix })
+    } else {
+      router.back()
+    }
+  }
+
+  return {
+    // Dependencies (for custom logic in form)
+    router,
+    route,
+    toast,
+
+    // Manager (if resolved from entity string)
+    manager,
+
+    // State
+    loading,
+    saving,
+    dirty,
+    dirtyFields,
+    isEdit,
+    entityId,
+
+    // Dirty tracking
+    isFieldDirty,
+    takeSnapshot,
+    checkDirty,
+    reset,
+
+    // Helpers
+    cancel,
+
+    // Breadcrumb
+    breadcrumb: breadcrumbItems,
+
+    // Guard dialog (for UnsavedChangesDialog component)
+    guardDialog,
+
+    // Title helpers
+    pageTitleParts,
+  }
+}

package/src/composables/useBreadcrumb.ts

@@ -0,0 +1,252 @@
+import { computed, inject, type ComputedRef, type Ref } from 'vue'
+import { useRouter } from 'vue-router'
+import { useSemanticBreadcrumb, type SemanticBreadcrumbItem } from './useSemanticBreadcrumb'
+import { useStackHydrator, type HydratedLevel } from '../chain/useStackHydrator'
+
+/**
+ * Breadcrumb display item
+ */
+export interface BreadcrumbDisplayItem {
+  label: string
+  to: { name: string; params?: Record<string, unknown> } | null
+  icon: string | null
+}
+
+/**
+ * Options for useBreadcrumb
+ */
+export interface UseBreadcrumbOptions {
+  /** Current entity data for dynamic labels */
+  entity?: unknown | Ref<unknown>
+  /** Custom label resolver for entities */
+  getEntityLabel?: (entity: unknown) => string
+  /** Custom label mappings */
+  labelMap?: Record<string, string>
+  /** Custom icon mappings */
+  iconMap?: Record<string, string>
+}
+
+/**
+ * Return type for useBreadcrumb
+ */
+export interface UseBreadcrumbReturn {
+  breadcrumbItems: ComputedRef<BreadcrumbDisplayItem[]>
+  semanticBreadcrumb: ComputedRef<SemanticBreadcrumbItem[]>
+  setBreadcrumb: (items: BreadcrumbDisplayItem[]) => BreadcrumbDisplayItem[]
+}
+
+/**
+ * useBreadcrumb - Generate display-ready breadcrumb from semantic breadcrumb
+ *
+ * Uses useSemanticBreadcrumb for the semantic model, then applies adapters
+ * to resolve labels, paths, and icons for display.
+ *
+ * @param options - Options
+ *
+ * @example
+ * const { breadcrumbItems, semanticBreadcrumb } = useBreadcrumb()
+ *
+ * // With entity data for dynamic labels
+ * const { breadcrumbItems } = useBreadcrumb({ entity: bookData })
+ */
+export function useBreadcrumb(options: UseBreadcrumbOptions = {}): UseBreadcrumbReturn {
+  const router = useRouter()
+  const homeRouteName = inject<string | null>('qdadmHomeRoute', null)
+
+  // Get semantic breadcrumb
+  const { breadcrumb: semanticBreadcrumb } = useSemanticBreadcrumb()
+
+  // Get hydrator for parent entity labels
+  const hydrator = useStackHydrator()
+
+  // Default label mapping
+  const defaultLabelMap: Record<string, string> = {
+    home: 'Home',
+    dashboard: 'Dashboard',
+    create: 'Create',
+    edit: 'Edit',
+    show: 'View',
+    delete: 'Delete',
+  }
+
+  // Default icon mapping for entities
+  const defaultIconMap: Record<string, string> = {
+    users: 'pi pi-users',
+    roles: 'pi pi-shield',
+    books: 'pi pi-book',
+    genres: 'pi pi-tags',
+    loans: 'pi pi-exchange',
+    settings: 'pi pi-cog',
+  }
+
+  // Merge with custom mappings
+  const labelMap = { ...defaultLabelMap, ...options.labelMap }
+  const iconMap = { ...defaultIconMap, ...options.iconMap }
+
+  /**
+   * Capitalize first letter
+   */
+  function capitalize(str: string): string {
+    if (!str) return ''
+    return str.charAt(0).toUpperCase() + str.slice(1)
+  }
+
+  /**
+   * Get route name for entity
+   */
+  function getEntityRouteName(entity: string, kind: string): string {
+    // Convention: entity-list -> 'book', entity-edit -> 'book-edit'
+    const singular = entity.endsWith('s') ? entity.slice(0, -1) : entity
+    if (kind === 'entity-list') return singular
+    if (kind === 'entity-show') return `${singular}-show`
+    if (kind === 'entity-edit') return `${singular}-edit`
+    if (kind === 'entity-create') return `${singular}-create`
+    return singular
+  }
+
+  /**
+   * Check if a route exists
+   */
+  function routeExists(name: string): boolean {
+    return router.getRoutes().some((r) => r.name === name)
+  }
+
+  /**
+   * Resolve semantic item to display item
+   * @param item - Semantic breadcrumb item
+   * @param index - Index in the breadcrumb array
+   * @param entity - Current entity data (for labels)
+   * @param isLast - Whether this is the last item (no link)
+   */
+  function resolveItem(
+    item: SemanticBreadcrumbItem,
+    index: number,
+    entity: unknown,
+    isLast: boolean
+  ): BreadcrumbDisplayItem {
+    const displayItem: BreadcrumbDisplayItem = {
+      label: '',
+      to: null,
+      icon: null,
+    }
+
+    if (item.kind === 'route') {
+      // Generic route
+      const routeName = item.route!
+      displayItem.label = item.label || labelMap[routeName] || capitalize(routeName)
+      displayItem.to = isLast ? null : routeExists(routeName) ? { name: routeName } : null
+      if (routeName === 'home') {
+        displayItem.icon = 'pi pi-home'
+      }
+    } else if (item.kind.startsWith('entity-')) {
+      // Entity-related item
+      const entityName = item.entity!
+
+      if (item.kind === 'entity-list') {
+        // Entity list - use plural label
+        displayItem.label = labelMap[entityName] || capitalize(entityName)
+        displayItem.icon = index === 1 ? iconMap[entityName] || null : null
+        const routeName = getEntityRouteName(entityName, item.kind)
+        displayItem.to = isLast ? null : routeExists(routeName) ? { name: routeName } : null
+      } else if (item.id) {
+        // Entity instance (show/edit/delete)
+        // Try to get label from hydrator first (works for all levels)
+        const hydratedLevel = hydrator.getLevelByEntity(entityName)
+        if (hydratedLevel?.label) {
+          displayItem.label = hydratedLevel.label
+        } else if (entity && options.getEntityLabel) {
+          displayItem.label = options.getEntityLabel(entity)
+        } else if (entity && typeof entity === 'object' && (entity as Record<string, unknown>).name) {
+          displayItem.label = String((entity as Record<string, unknown>).name)
+        } else if (
+          entity &&
+          typeof entity === 'object' &&
+          (entity as Record<string, unknown>).title
+        ) {
+          displayItem.label = String((entity as Record<string, unknown>).title)
+        } else {
+          displayItem.label = `#${item.id}`
+        }
+
+        // Last item = no link. Otherwise link to show page if exists
+        if (!isLast && (item.kind === 'entity-edit' || item.kind === 'entity-delete')) {
+          const showRouteName = getEntityRouteName(entityName, 'entity-show')
+          if (routeExists(showRouteName)) {
+            displayItem.to = { name: showRouteName, params: { id: item.id } }
+          }
+        }
+      } else if (item.kind === 'entity-create') {
+        // Create page - label as action
+        displayItem.label = labelMap.create || 'Create'
+      }
+    }
+
+    return displayItem
+  }
+
+  /**
+   * Get home breadcrumb item
+   */
+  function getHomeItem(): BreadcrumbDisplayItem | null {
+    if (!homeRouteName || !routeExists(homeRouteName)) return null
+    return {
+      label: labelMap.home || 'Home',
+      to: { name: homeRouteName },
+      icon: 'pi pi-home',
+    }
+  }
+
+  /**
+   * Computed display-ready breadcrumb items
+   */
+  const breadcrumbItems = computed(() => {
+    const entity =
+      (options.entity as Ref<unknown>)?.value !== undefined
+        ? (options.entity as Ref<unknown>).value
+        : options.entity
+    const items: BreadcrumbDisplayItem[] = []
+
+    // Access hydrator levels deeply to create Vue dependencies
+    // This ensures breadcrumb recomputes when hydration completes
+    // We need to touch each level's label to track changes
+    const _hydratorLevels = hydrator.levels.value
+    // Touch labels to track changes (result intentionally unused for reactivity)
+    _hydratorLevels.map((l: HydratedLevel) => l.label).join()
+
+    // Add home first (display concern, not in semantic breadcrumb)
+    const homeItem = getHomeItem()
+    if (homeItem) {
+      items.push(homeItem)
+    }
+
+    // Resolve semantic items to display items
+    const semanticItems = semanticBreadcrumb.value
+    for (let i = 0; i < semanticItems.length; i++) {
+      const semanticItem = semanticItems[i]
+      if (!semanticItem) continue
+      const isLast = i === semanticItems.length - 1
+      const displayItem = resolveItem(semanticItem, i, entity, isLast)
+      items.push(displayItem)
+    }
+
+    return items
+  })
+
+  /**
+   * Manual override - set custom breadcrumb items
+   */
+  function setBreadcrumb(items: BreadcrumbDisplayItem[]): BreadcrumbDisplayItem[] {
+    const homeItem: BreadcrumbDisplayItem = {
+      label: labelMap.home || 'Home',
+      to: { name: homeRouteName! },
+      icon: 'pi pi-home',
+    }
+    return homeRouteName && routeExists(homeRouteName) ? [homeItem, ...items] : items
+  }
+
+  return {
+    breadcrumbItems,
+    semanticBreadcrumb,
+    setBreadcrumb,
+  }
+}