qdadm 0.13.0

package/src/composables/useBareForm.js

@@ -0,0 +1,143 @@
+import { ref, computed, provide, onUnmounted } from 'vue'
+import { useRoute, useRouter } from 'vue-router'
+import { useToast } from 'primevue/usetoast'
+import { useDirtyState } from './useDirtyState'
+import { useUnsavedChangesGuard } from './useUnsavedChangesGuard'
+import { useBreadcrumb } from './useBreadcrumb'
+import { registerGuardDialog, unregisterGuardDialog } from './useGuardStore'
+
+/**
+ * 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
+ *     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
+ *
+ * @param {Object} options
+ * @param {Function} options.getState - Function returning current form state for comparison
+ * @param {string} options.routePrefix - Route name for cancel navigation (default: '')
+ * @param {boolean} options.guard - Enable unsaved changes guard (default: true)
+ * @param {Function} options.onGuardSave - Callback for save button in guard modal
+ * @param {Function} options.getId - Custom function to extract entity ID from route (optional)
+ * @param {Ref|Object} options.entity - Entity data for dynamic breadcrumb labels (optional)
+ * @param {Function} options.breadcrumbLabel - Callback (entity) => string for custom breadcrumb label (optional)
+ */
+export function useBareForm(options = {}) {
+  const {
+    getState,
+    routePrefix = '',
+    guard = true,
+    onGuardSave = null,
+    getId = null,
+    entity = null,
+    breadcrumbLabel = null
+  } = options
+
+  if (!getState || typeof getState !== 'function') {
+    throw new Error('useBareForm requires a getState function')
+  }
+
+  // Router, route, toast - common dependencies
+  const router = useRouter()
+  const route = useRoute()
+  const toast = useToast()
+
+  // Common state
+  const loading = ref(false)
+  const saving = ref(false)
+
+  // Common computed
+  const entityId = computed(() => {
+    if (getId) return getId()
+    return route.params.id || route.params.key || 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)
+
+  // Breadcrumb (auto-generated from route path, with optional entity for dynamic labels)
+  const { breadcrumbItems } = useBreadcrumb({ entity, getEntityLabel: breadcrumbLabel })
+
+  // Unsaved changes guard
+  let guardDialog = 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() {
+    if (routePrefix) {
+      router.push({ name: routePrefix })
+    } else {
+      router.back()
+    }
+  }
+
+  return {
+    // Dependencies (for custom logic in form)
+    router,
+    route,
+    toast,
+
+    // State
+    loading,
+    saving,
+    dirty,
+    dirtyFields,
+    isEdit,
+    entityId,
+
+    // Dirty tracking
+    isFieldDirty,
+    takeSnapshot,
+    checkDirty,
+    reset,
+
+    // Helpers
+    cancel,
+
+    // Breadcrumb
+    breadcrumb: breadcrumbItems,
+
+    // Guard dialog (for UnsavedChangesDialog component)
+    guardDialog
+  }
+}

package/src/composables/useBreadcrumb.js

@@ -0,0 +1,221 @@
+import { computed } from 'vue'
+import { useRoute, useRouter } from 'vue-router'
+
+/**
+ * useBreadcrumb - Auto-generate breadcrumb from route hierarchy
+ *
+ * Generates breadcrumb items automatically from:
+ * 1. route.meta.breadcrumb if defined (manual override)
+ * 2. Route path segments with smart label generation
+ *
+ * Usage:
+ * const { breadcrumbItems } = useBreadcrumb()
+ *
+ * // Or with entity data for dynamic labels
+ * const { breadcrumbItems } = useBreadcrumb({ entity: agentData })
+ *
+ * // Or with custom label callback
+ * const { breadcrumbItems } = useBreadcrumb({
+ *   entity: newsroomData,
+ *   getEntityLabel: (entity) => entity.name || entity.slug
+ * })
+ *
+ * Route meta example:
+ * {
+ *   path: 'agents/:id/edit',
+ *   name: 'agent-edit',
+ *   meta: {
+ *     breadcrumb: [
+ *       { label: 'Agents', to: { name: 'agents' } },
+ *       { label: ':name', dynamic: true }  // Resolved from entity.name
+ *     ]
+ *   }
+ * }
+ */
+export function useBreadcrumb(options = {}) {
+  const route = useRoute()
+  const router = useRouter()
+
+  // Label mapping for common route names
+  const labelMap = {
+    dashboard: 'Dashboard',
+    users: 'Users',
+    roles: 'Roles',
+    apikeys: 'API Keys',
+    newsrooms: 'Newsrooms',
+    agents: 'Agents',
+    events: 'Events',
+    taxonomy: 'Taxonomy',
+    domains: 'Domains',
+    nexus: 'Nexus',
+    queue: 'Queue',
+    create: 'Create',
+    edit: 'Edit',
+    show: 'View'
+  }
+
+  // Icon mapping for root sections
+  const iconMap = {
+    users: 'pi pi-users',
+    roles: 'pi pi-shield',
+    apikeys: 'pi pi-key',
+    newsrooms: 'pi pi-building',
+    agents: 'pi pi-user',
+    events: 'pi pi-calendar',
+    taxonomy: 'pi pi-tags',
+    domains: 'pi pi-globe',
+    nexus: 'pi pi-sitemap',
+    queue: 'pi pi-server'
+  }
+
+  /**
+   * Capitalize first letter
+   */
+  function capitalize(str) {
+    return str.charAt(0).toUpperCase() + str.slice(1)
+  }
+
+  /**
+   * Get human-readable label from path segment
+   */
+  function getLabel(segment) {
+    // Check labelMap first
+    if (labelMap[segment]) return labelMap[segment]
+    // Capitalize and replace hyphens
+    return capitalize(segment.replace(/-/g, ' '))
+  }
+
+  /**
+   * Resolve dynamic label from entity data
+   */
+  function resolveDynamicLabel(label, entity) {
+    if (!label.startsWith(':')) return label
+    const field = label.slice(1) // Remove ':'
+    return entity?.[field] || label
+  }
+
+  /**
+   * Check if a route exists
+   */
+  function routeExists(name) {
+    return router.getRoutes().some(r => r.name === name)
+  }
+
+  /**
+   * Get home breadcrumb item (dashboard if exists, otherwise null)
+   */
+  function getHomeItem() {
+    if (routeExists('dashboard')) {
+      return { label: 'Dashboard', to: { name: 'dashboard' }, icon: 'pi pi-home' }
+    }
+    return null
+  }
+
+  /**
+   * Build breadcrumb from route.meta.breadcrumb (manual)
+   */
+  function buildFromMeta(metaBreadcrumb, entity) {
+    const items = []
+    const home = getHomeItem()
+    if (home) items.push(home)
+
+    for (const item of metaBreadcrumb) {
+      const resolved = {
+        label: item.dynamic ? resolveDynamicLabel(item.label, entity) : item.label,
+        to: item.to || null,
+        icon: item.icon || null
+      }
+      items.push(resolved)
+    }
+
+    return items
+  }
+
+  /**
+   * Build breadcrumb automatically from route path
+   */
+  function buildFromPath(entity, getEntityLabel) {
+    const items = []
+    const home = getHomeItem()
+    if (home) items.push(home)
+
+    // Get path segments, filter empty and params
+    const segments = route.path.split('/').filter(s => s && !s.startsWith(':'))
+
+    let currentPath = ''
+    for (let i = 0; i < segments.length; i++) {
+      const segment = segments[i]
+      currentPath += `/${segment}`
+
+      // Handle IDs: numeric, UUID, ULID, or any alphanumeric string > 10 chars - use entity label instead
+      const isId = /^\d+$/.test(segment) ||  // numeric
+        segment.match(/^[0-9a-f-]{36}$/i) ||  // UUID
+        segment.match(/^[0-7][0-9a-hjkmnp-tv-z]{25}$/i) ||  // ULID
+        (segment.match(/^[a-z0-9]+$/i) && segment.length > 10)  // Generated ID (like LocalStorage)
+      if (isId) {
+        // If we have entity data, show its label instead of the ID
+        if (entity && getEntityLabel) {
+          const entityLabel = getEntityLabel(entity)
+          if (entityLabel) {
+            items.push({ label: entityLabel, to: null, icon: null })
+          }
+        }
+        continue
+      }
+
+      // Get label for this segment
+      const label = getLabel(segment)
+
+      // Find matching route for this path
+      const matchedRoute = router.getRoutes().find(r => {
+        const routePath = r.path.replace(/:\w+/g, '[^/]+')
+        const regex = new RegExp(`^${routePath}$`)
+        return regex.test(currentPath)
+      })
+
+      const item = {
+        label,
+        to: matchedRoute ? { name: matchedRoute.name } : null,
+        icon: i === 0 ? iconMap[segment] : null
+      }
+
+      // Last item has no link
+      if (i === segments.length - 1) {
+        item.to = null
+      }
+
+      items.push(item)
+    }
+
+    return items
+  }
+
+  /**
+   * Computed breadcrumb items
+   */
+  const breadcrumbItems = computed(() => {
+    const entity = options.entity?.value || options.entity
+    const getEntityLabel = options.getEntityLabel || null
+
+    // Use meta.breadcrumb if defined
+    if (route.meta?.breadcrumb) {
+      return buildFromMeta(route.meta.breadcrumb, entity)
+    }
+
+    // Auto-generate from path
+    return buildFromPath(entity, getEntityLabel)
+  })
+
+  /**
+   * Manual override - set custom breadcrumb items
+   */
+  function setBreadcrumb(items) {
+    const home = getHomeItem()
+    return home ? [home, ...items] : items
+  }
+
+  return {
+    breadcrumbItems,
+    setBreadcrumb
+  }
+}

package/src/composables/useDirtyState.js

@@ -0,0 +1,103 @@
+/**
+ * Composable for tracking form dirty state
+ *
+ * Usage:
+ * const { dirty, dirtyFields, isFieldDirty, takeSnapshot, checkDirty } = useDirtyState(() => ({
+ *   form: formData.value
+ * }))
+ *
+ * // Take snapshot after loading data
+ * takeSnapshot()
+ *
+ * // Watch for changes
+ * watch(formData, checkDirty, { deep: true })
+ *
+ * // Check if specific field is dirty
+ * isFieldDirty('username')  // true/false
+ *
+ * // Get all dirty field names
+ * dirtyFields.value  // ['username', 'email']
+ */
+
+import { ref, nextTick } from 'vue'
+
+export function useDirtyState(getState) {
+  const dirty = ref(false)
+  const dirtyFields = ref([])
+  const initialSnapshot = ref(null)
+  const initialState = ref(null)
+  const ready = ref(false)
+
+  function getFormSnapshot() {
+    return JSON.stringify(getState())
+  }
+
+  function takeSnapshot() {
+    // Disable dirty checking temporarily to prevent watchers from re-setting dirty
+    ready.value = false
+    dirty.value = false
+    dirtyFields.value = []
+
+    // Use nextTick to ensure all reactive updates have settled for snapshot
+    nextTick(() => {
+      const state = getState()
+      initialSnapshot.value = JSON.stringify(state)
+      // Store raw state for field-level comparison
+      initialState.value = JSON.parse(JSON.stringify(state))
+      ready.value = true
+    })
+  }
+
+  function checkDirty() {
+    // Don't check until snapshot is taken and ready
+    if (!ready.value || !initialSnapshot.value) return
+
+    const currentSnapshot = getFormSnapshot()
+    dirty.value = currentSnapshot !== initialSnapshot.value
+
+    // Calculate dirty fields
+    if (dirty.value && initialState.value) {
+      const current = getState()
+      const changed = []
+
+      // Compare form fields if state has a 'form' or 'formData' key (common patterns)
+      const initial = initialState.value.form || initialState.value.formData || initialState.value
+      const currentForm = current.form || current.formData || current
+
+      for (const key in currentForm) {
+        const initialVal = JSON.stringify(initial[key])
+        const currentVal = JSON.stringify(currentForm[key])
+        if (initialVal !== currentVal) {
+          changed.push(key)
+        }
+      }
+      dirtyFields.value = changed
+    } else {
+      dirtyFields.value = []
+    }
+  }
+
+  function isFieldDirty(fieldName) {
+    return dirtyFields.value.includes(fieldName)
+  }
+
+  function reset() {
+    dirty.value = false
+    dirtyFields.value = []
+    initialSnapshot.value = null
+    initialState.value = null
+    ready.value = false
+  }
+
+  return {
+    dirty,
+    dirtyFields,
+    ready,
+    takeSnapshot,
+    checkDirty,
+    isFieldDirty,
+    reset
+  }
+}
+
+export default useDirtyState

package/src/composables/useEntityTitle.js

@@ -0,0 +1,121 @@
+/**
+ * Composable for generating display titles for entities
+ *
+ * Usage:
+ * const { displayTitle, pageTitle } = useEntityTitle(entity, {
+ *   type: 'Agent',
+ *   nameField: 'name',  // default
+ *   fallbackField: 'id'  // default
+ * })
+ *
+ * // In template:
+ * <h1>{{ pageTitle }}</h1>  // "Edit Agent John Doe" or "Create Agent"
+ */
+
+import { computed } from 'vue'
+
+/**
+ * Field priority for display title (first match wins)
+ */
+const DEFAULT_NAME_FIELDS = ['name', 'title', 'label', 'username', 'slug']
+
+/**
+ * Get display title from an entity object
+ *
+ * @param {Object} entity - Entity object
+ * @param {Object} options - Options
+ * @param {string|string[]} options.nameField - Field(s) to use for display name
+ * @param {string} options.fallbackField - Fallback field (usually 'id')
+ * @param {number} options.maxLength - Max length before truncation (default: 50)
+ * @returns {string} Display title
+ */
+export function getEntityDisplayTitle(entity, options = {}) {
+  if (!entity) return ''
+
+  const {
+    nameField = DEFAULT_NAME_FIELDS,
+    fallbackField = 'id',
+    maxLength = 50
+  } = options
+
+  // Try name fields in order
+  const fields = Array.isArray(nameField) ? nameField : [nameField]
+  for (const field of fields) {
+    const value = entity[field]
+    if (value && typeof value === 'string' && value.trim()) {
+      const title = value.trim()
+      if (title.length > maxLength) {
+        return title.slice(0, maxLength - 3) + '...'
+      }
+      return title
+    }
+  }
+
+  // Fallback to ID (truncated)
+  const fallback = entity[fallbackField]
+  if (fallback) {
+    const id = String(fallback)
+    if (id.length > 12) {
+      return id.slice(0, 8) + '...'
+    }
+    return id
+  }
+
+  return ''
+}
+
+/**
+ * Composable for entity display titles
+ *
+ * @param {Ref<Object>} entityRef - Reactive entity reference
+ * @param {Object} options - Options
+ * @param {string} options.type - Entity type name (e.g., 'Agent', 'Newsroom')
+ * @param {string|string[]} options.nameField - Field(s) to use for display name
+ * @param {string} options.fallbackField - Fallback field (usually 'id')
+ * @param {Ref<boolean>} options.isEdit - Reactive boolean for edit mode
+ */
+export function useEntityTitle(entityRef, options = {}) {
+  const {
+    type = 'Entity',
+    nameField = DEFAULT_NAME_FIELDS,
+    fallbackField = 'id',
+    isEdit = null
+  } = options
+
+  /**
+   * Display title for the entity (just the name/id part)
+   */
+  const displayTitle = computed(() => {
+    return getEntityDisplayTitle(entityRef.value, { nameField, fallbackField })
+  })
+
+  /**
+   * Full page title (e.g., "Edit Agent John Doe" or "Create Agent")
+   */
+  const pageTitle = computed(() => {
+    if (isEdit?.value) {
+      const title = displayTitle.value
+      return title ? `Edit ${type}: ${title}` : `Edit ${type}`
+    }
+    return `Create ${type}`
+  })
+
+  /**
+   * Browser document title
+   */
+  const documentTitle = computed(() => {
+    if (isEdit?.value) {
+      const title = displayTitle.value
+      return title ? `${title} - ${type}` : `Edit ${type}`
+    }
+    return `New ${type}`
+  })
+
+  return {
+    displayTitle,
+    pageTitle,
+    documentTitle
+  }
+}
+
+export default useEntityTitle