@quazardous/qdadm 1.19.3

package/src/composables/useChildPage.ts

@@ -0,0 +1,113 @@
+/**
+ * useChildPage - Composable for non-entity child pages on entity items
+ *
+ * Provides parent entity context for custom child pages registered via ctx.childPage().
+ * The parent data is loaded automatically via the StackHydrator (triggered by the
+ * Kernel's activeStack rebuild from route.meta.parent).
+ *
+ * @example
+ * // In a child page component (e.g., BookInfo.vue)
+ * const { parentData, parentLoading, parentManager } = useChildPage()
+ *
+ * // parentData is reactive - null while loading, then the parent entity record
+ * // parentManager gives access to the parent EntityManager (labels, fields, etc.)
+ */
+import { computed, inject, type ComputedRef } from 'vue'
+import { useRoute } from 'vue-router'
+import { useStackHydrator, type StackHydratorReturn } from '../chain/useStackHydrator'
+
+/**
+ * Parent config from route meta
+ */
+interface ParentConfig {
+  entity: string
+  param: string
+  foreignKey?: string
+}
+
+/**
+ * Entity manager interface (subset used by child pages)
+ */
+interface EntityManager {
+  idField: string
+  label?: string
+  labelPlural?: string
+  routePrefix?: string
+  getEntityLabel: (data: unknown) => string
+  getEntityBadges?: (data: unknown) => Array<{ label: string; severity?: string }>
+}
+
+/**
+ * Orchestrator interface
+ */
+interface Orchestrator {
+  get: (entityName: string) => EntityManager | null
+}
+
+/**
+ * Return type for useChildPage
+ */
+export interface UseChildPageReturn {
+  /** Parent config from route.meta.parent */
+  parentConfig: ComputedRef<ParentConfig | null>
+  /** Parent entity name */
+  parentEntity: ComputedRef<string | null>
+  /** Parent entity ID from route params */
+  parentId: ComputedRef<string | null>
+  /** Hydrated parent entity data (null while loading) */
+  parentData: ComputedRef<unknown | null>
+  /** Whether parent data is still loading */
+  parentLoading: ComputedRef<boolean>
+  /** Parent entity manager */
+  parentManager: ComputedRef<EntityManager | null>
+  /** Stack hydrator for advanced usage */
+  hydrator: StackHydratorReturn
+}
+
+export function useChildPage(): UseChildPageReturn {
+  const route = useRoute()
+  const hydrator = useStackHydrator()
+  const orchestrator = inject<Orchestrator | null>('qdadmOrchestrator', null)
+
+  const parentConfig = computed<ParentConfig | null>(
+    () => (route.meta?.parent as ParentConfig) || null
+  )
+
+  const parentEntity = computed(() => parentConfig.value?.entity || null)
+
+  const parentId = computed(() => {
+    if (!parentConfig.value) return null
+    return (route.params[parentConfig.value.param] as string) || null
+  })
+
+  const parentData = computed(() => {
+    if (!parentEntity.value || !parentId.value) return null
+    const level = hydrator.levels.value.find(
+      (l) => l.entity === parentEntity.value && String(l.id) === String(parentId.value)
+    )
+    return level?.data || null
+  })
+
+  const parentLoading = computed(() => {
+    if (!parentEntity.value || !parentId.value) return false
+    const level = hydrator.levels.value.find(
+      (l) => l.entity === parentEntity.value && String(l.id) === String(parentId.value)
+    )
+    return level ? !level.hydrated : true
+  })
+
+  const parentManager = computed(() => {
+    if (!parentEntity.value) return null
+    return orchestrator?.get(parentEntity.value) || null
+  })
+
+  return {
+    parentConfig,
+    parentEntity,
+    parentId,
+    parentData,
+    parentLoading,
+    parentManager,
+    hydrator,
+  }
+}

package/src/composables/useCurrentEntity.ts

@@ -0,0 +1,60 @@
+/**
+ * @deprecated Use useStackHydrator() instead
+ *
+ * Legacy composable for setting breadcrumb entity data.
+ * This has been replaced by the activeStack + stackHydrator system.
+ *
+ * Migration:
+ * ```ts
+ * // Before (deprecated)
+ * const { setBreadcrumbEntity } = useCurrentEntity()
+ * setBreadcrumbEntity(data)
+ *
+ * // After
+ * const hydrator = useStackHydrator()
+ * hydrator.setCurrentData(data)
+ * ```
+ */
+import { useStackHydrator } from '../chain/useStackHydrator'
+
+/**
+ * Return type for useCurrentEntity
+ */
+export interface UseCurrentEntityReturn {
+  /** @deprecated Use hydrator.setCurrentData() instead */
+  setBreadcrumbEntity: (data: unknown, level?: number) => void
+  /** @deprecated Use hydrator.setCurrentData() instead */
+  setCurrentEntity: (data: unknown) => void
+}
+
+/**
+ * @deprecated Use useStackHydrator() instead
+ */
+export function useCurrentEntity(): UseCurrentEntityReturn {
+  console.warn(
+    '[qdadm] useCurrentEntity is deprecated. Use useStackHydrator() instead.'
+  )
+
+  const hydrator = useStackHydrator()
+
+  /**
+   * @deprecated Use hydrator.setCurrentData() instead
+   */
+  function setBreadcrumbEntity(data: unknown, level = 1): void {
+    if (level === 1) {
+      hydrator.setCurrentData(data)
+    } else {
+      // For parent levels, use setEntityData with entity name
+      // But we don't have entity name here - just set current
+      hydrator.setCurrentData(data)
+    }
+  }
+
+  // Backwards compat alias
+  const setCurrentEntity = (data: unknown): void => setBreadcrumbEntity(data, 1)
+
+  return {
+    setBreadcrumbEntity,
+    setCurrentEntity,
+  }
+}

package/src/composables/useDeferred.ts

@@ -0,0 +1,94 @@
+/**
+ * useDeferred - Access the DeferredRegistry from components
+ *
+ * Provides loose async coupling between services and components.
+ * Components can await dependencies without knowing when they're loaded.
+ *
+ * @example
+ * ```ts
+ * import { useDeferred } from '@quazardous/qdadm/composables'
+ *
+ * // In a component
+ * const deferred = useDeferred()
+ *
+ * // Await a single dependency
+ * const config = await deferred.await('config')
+ *
+ * // Await multiple dependencies
+ * const [users, settings] = await Promise.all([
+ *   deferred.await('users-service'),
+ *   deferred.await('settings')
+ * ])
+ *
+ * // Check status without waiting
+ * if (deferred.isSettled('config')) {
+ *   const config = deferred.value('config')
+ * }
+ * ```
+ */
+
+import { inject, ref, type Ref } from 'vue'
+import type { DeferredRegistry } from '../deferred/DeferredRegistry'
+
+/**
+ * Injection key for DeferredRegistry
+ */
+export const DEFERRED_INJECTION_KEY = 'qdadmDeferred'
+
+/**
+ * Get the DeferredRegistry instance
+ * @returns The DeferredRegistry instance
+ */
+export function useDeferred(): DeferredRegistry {
+  const deferred = inject<DeferredRegistry | null>(DEFERRED_INJECTION_KEY)
+
+  if (!deferred) {
+    throw new Error(
+      '[useDeferred] DeferredRegistry not found. ' +
+        'Make sure you are using the Kernel to bootstrap your app.'
+    )
+  }
+
+  return deferred
+}
+
+/**
+ * Return type for useDeferredValue
+ */
+export interface UseDeferredValueReturn<T> {
+  data: Ref<T | null>
+  loading: Ref<boolean>
+  error: Ref<Error | null>
+}
+
+/**
+ * Helper: await a deferred value in setup
+ * Returns a ref that updates when the deferred resolves
+ *
+ * @example
+ * ```ts
+ * const { data: config, loading, error } = useDeferredValue('config')
+ * ```
+ *
+ * @param key - Deferred key
+ * @returns Object with data, loading, and error refs
+ */
+export function useDeferredValue<T = unknown>(key: string): UseDeferredValueReturn<T> {
+  const deferred = useDeferred()
+  const data = ref<T | null>(null) as Ref<T | null>
+  const loading = ref(true)
+  const error = ref<Error | null>(null)
+
+  deferred
+    .await<T>(key)
+    .then((value) => {
+      data.value = value
+      loading.value = false
+    })
+    .catch((err: Error) => {
+      error.value = err
+      loading.value = false
+    })
+
+  return { data, loading, error }
+}

package/src/composables/useDirtyState.ts

@@ -0,0 +1,138 @@
+/**
+ * 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, type Ref } from 'vue'
+
+/**
+ * State getter function type
+ */
+export type StateGetter<T = Record<string, unknown>> = () => T
+
+/**
+ * Form state type with optional form/formData keys
+ */
+export interface FormState {
+  form?: Record<string, unknown>
+  formData?: Record<string, unknown>
+  [key: string]: unknown
+}
+
+/**
+ * Return type for useDirtyState
+ */
+export interface UseDirtyStateReturn {
+  dirty: Ref<boolean>
+  dirtyFields: Ref<string[]>
+  ready: Ref<boolean>
+  takeSnapshot: () => void
+  checkDirty: () => void
+  isFieldDirty: (fieldName: string) => boolean
+  reset: () => void
+}
+
+export function useDirtyState<T extends FormState = FormState>(
+  getState: StateGetter<T>
+): UseDirtyStateReturn {
+  const dirty = ref(false)
+  const dirtyFields = ref<string[]>([])
+  const initialSnapshot = ref<string | null>(null)
+  const initialState = ref<T | null>(null)
+  const ready = ref(false)
+
+  function getFormSnapshot(): string {
+    return JSON.stringify(getState())
+  }
+
+  function takeSnapshot(): void {
+    // 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)) as T
+      ready.value = true
+    })
+  }
+
+  function checkDirty(): void {
+    // 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: string[] = []
+
+      // Compare form fields if state has a 'form' or 'formData' key (common patterns)
+      const initial =
+        (initialState.value.form as Record<string, unknown>) ||
+        (initialState.value.formData as Record<string, unknown>) ||
+        (initialState.value as Record<string, unknown>)
+      const currentForm =
+        (current.form as Record<string, unknown>) ||
+        (current.formData as Record<string, unknown>) ||
+        (current as Record<string, unknown>)
+
+      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: string): boolean {
+    return dirtyFields.value.includes(fieldName)
+  }
+
+  function reset(): void {
+    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