@quazardous/qdadm 2.4.3 → 2.4.5

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@quazardous/qdadm",
-  "version": "2.4.3",
+  "version": "2.4.5",
   "description": "Vue 3 framework for admin dashboards with PrimeVue",
   "author": "quazardous",
   "license": "MIT",

package/src/composables/useDirtyState.ts

@@ -54,9 +54,28 @@ export function useDirtyState<T extends FormState = FormState>(
   const dirty = ref(false)
   const dirtyFields = ref<string[]>([])
   const initialSnapshot = ref<string | null>(null)
-  const initialState = ref<T | null>(null)
+  // Per-key snapshot strings, precomputed once at takeSnapshot() (#1194):
+  // checkDirty runs on every keystroke (deep watch) — re-stringifying the
+  // initial side each time doubled the per-key work, and the old
+  // JSON.parse(JSON.stringify(state)) deep clone tripled the snapshot cost.
+  let initialFieldSnapshots: Map<string, string> | null = null
   const ready = ref(false)
 
+  /** Resolve the form object inside the state (common 'form'/'formData' patterns). */
+  function resolveForm(state: T): Record<string, unknown> {
+    return (
+      (state.form as Record<string, unknown>) ||
+      (state.formData as Record<string, unknown>) ||
+      (state as Record<string, unknown>)
+    )
+  }
+
+  /** Stable stringify — JSON.stringify(undefined) is undefined, normalize it. */
+  function stringifyField(value: unknown): string {
+    const s = JSON.stringify(value)
+    return s === undefined ? 'undefined' : s
+  }
+
   function getFormSnapshot(): string {
     return JSON.stringify(getState())
   }
@@ -71,8 +90,12 @@ export function useDirtyState<T extends FormState = FormState>(
     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
+      const form = resolveForm(state)
+      const fieldSnapshots = new Map<string, string>()
+      for (const key in form) {
+        fieldSnapshots.set(key, stringifyField(form[key]))
+      }
+      initialFieldSnapshots = fieldSnapshots
       ready.value = true
     })
   }
@@ -84,25 +107,15 @@ export function useDirtyState<T extends FormState = FormState>(
     const currentSnapshot = getFormSnapshot()
     dirty.value = currentSnapshot !== initialSnapshot.value
 
-    // Calculate dirty fields
-    if (dirty.value && initialState.value) {
-      const current = getState()
+    // Calculate dirty fields — current side only is stringified; the
+    // initial side comes from the cached per-key snapshots (#1194).
+    if (dirty.value && initialFieldSnapshots) {
+      const currentForm = resolveForm(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) {
+        const currentVal = stringifyField(currentForm[key])
+        if (initialFieldSnapshots.get(key) !== currentVal) {
           changed.push(key)
         }
       }
@@ -120,7 +133,7 @@ export function useDirtyState<T extends FormState = FormState>(
     dirty.value = false
     dirtyFields.value = []
     initialSnapshot.value = null
-    initialState.value = null
+    initialFieldSnapshots = null
     ready.value = false
   }
 

package/src/composables/useListPage.alterHooks.ts

@@ -0,0 +1,153 @@
+/**
+ * useListAlterHooks — the list:alter / filter:alter hook wiring of
+ * useListPage (#1195, KPI-8).
+ *
+ * Mechanical extraction: snapshots the list config, runs the global and
+ * entity-scoped alter hooks, and applies the altered config back onto the
+ * live state (columns, filters, actions via the shared registry, header
+ * actions). useListPage composes it back in; behavior is unchanged.
+ */
+import type { Ref } from 'vue'
+import type {
+  ActionConfig,
+  ColumnConfig,
+  FilterConfig,
+  HeaderActionConfig,
+  ResolvedAction,
+} from './useListPage.types'
+import type { UseActionRegistryReturn } from './useActionRegistry'
+
+/** Minimal HookRegistry view (what the alter flow actually uses). */
+export interface AlterHooksLike {
+  alter: (name: string, value: unknown) => Promise<unknown>
+  hasHook: (name: string) => boolean
+}
+
+/** Dependencies injected by useListPage. */
+export interface UseListAlterHooksDeps {
+  hooks: AlterHooksLike | null | undefined
+  entity: string
+  manager: unknown
+  columnsMap: Ref<Map<string, ColumnConfig>>
+  filtersMap: Ref<Map<string, FilterConfig>>
+  filterValues: Ref<Record<string, unknown>>
+  headerActionsMap: Ref<Map<string, HeaderActionConfig>>
+  actionRegistry: UseActionRegistryReturn<ActionConfig, unknown, ResolvedAction>
+}
+
+export interface UseListAlterHooksReturn {
+  invokeListAlterHook: () => Promise<void>
+  invokeFilterAlterHook: () => Promise<void>
+}
+
+export function useListAlterHooks(deps: UseListAlterHooksDeps): UseListAlterHooksReturn {
+  const {
+    hooks,
+    entity,
+    manager,
+    columnsMap,
+    filtersMap,
+    filterValues,
+    headerActionsMap,
+    actionRegistry,
+  } = deps
+  const actionsMap = actionRegistry.actionsMap
+
+  async function invokeListAlterHook(): Promise<void> {
+    if (!hooks) return
+
+    const configSnapshot = {
+      entity,
+      columns: Array.from(columnsMap.value.values()),
+      filters: Array.from(filtersMap.value.values()),
+      actions: Array.from(actionsMap.value.values()),
+      headerActions: Array.from(headerActionsMap.value.values()),
+    }
+
+    // Include entity context in the snapshot for hooks
+    const configWithContext = { ...configSnapshot, entity, manager }
+
+    let alteredConfig = await hooks.alter('list:alter', configWithContext)
+
+    const entityHookName = `${entity}:list:alter`
+    if (hooks.hasHook(entityHookName)) {
+      alteredConfig = await hooks.alter(entityHookName, alteredConfig)
+    }
+
+    applyAlteredConfig(
+      alteredConfig as {
+        columns?: ColumnConfig[]
+        filters?: FilterConfig[]
+        actions?: ActionConfig[]
+        headerActions?: HeaderActionConfig[]
+      }
+    )
+  }
+
+  async function invokeFilterAlterHook(): Promise<void> {
+    if (!hooks) return
+
+    const filterSnapshot = {
+      entity,
+      filters: Array.from(filtersMap.value.values()),
+    }
+
+    let alteredFilters = (await hooks.alter('filter:alter', filterSnapshot)) as typeof filterSnapshot
+
+    const entityHookName = `${entity}:filter:alter`
+    if (hooks.hasHook(entityHookName)) {
+      alteredFilters = (await hooks.alter(entityHookName, alteredFilters)) as typeof filterSnapshot
+    }
+
+    if (alteredFilters.filters) {
+      filtersMap.value.clear()
+      for (const filter of alteredFilters.filters) {
+        filtersMap.value.set(filter.name, filter)
+        if (filterValues.value[filter.name] === undefined) {
+          filterValues.value[filter.name] = filter.default ?? null
+        }
+      }
+    }
+  }
+
+  function applyAlteredConfig(alteredConfig: {
+    columns?: ColumnConfig[]
+    filters?: FilterConfig[]
+    actions?: ActionConfig[]
+    headerActions?: HeaderActionConfig[]
+  }): void {
+    if (alteredConfig.columns) {
+      columnsMap.value.clear()
+      for (const col of alteredConfig.columns) {
+        columnsMap.value.set(col.field, col)
+      }
+    }
+
+    if (alteredConfig.filters) {
+      filtersMap.value.clear()
+      for (const filter of alteredConfig.filters) {
+        filtersMap.value.set(filter.name, filter)
+        if (filterValues.value[filter.name] === undefined) {
+          filterValues.value[filter.name] = filter.default ?? null
+        }
+      }
+    }
+
+    if (alteredConfig.actions) {
+      // Route through the registry so the order list stays in sync (#1193)
+      actionRegistry.clear()
+      for (const action of alteredConfig.actions) {
+        actionRegistry.add(action)
+      }
+    }
+
+    if (alteredConfig.headerActions) {
+      headerActionsMap.value.clear()
+      for (const action of alteredConfig.headerActions) {
+        headerActionsMap.value.set(action.name, action)
+      }
+    }
+  }
+
+  return { invokeListAlterHook, invokeFilterAlterHook }
+}

package/src/composables/useListPage.filters.ts

@@ -0,0 +1,421 @@
+/**
+ * useListFilters — the filter subsystem of useListPage (#1195, KPI-8).
+ *
+ * Mechanical extraction: owns the filter state (filtersMap/filterValues),
+ * the three option-source modes (optionsEntity / optionsEndpoint /
+ * optionsFromCache), session persistence, URL sync and registry auto-load.
+ * useListPage composes it back in; behavior is unchanged.
+ */
+import { ref, computed, type Ref, type ComputedRef } from 'vue'
+import type { RouteLocationNormalizedLoaded, Router } from 'vue-router'
+import { FilterQuery, type QueryOrchestratorLike } from '../query/FilterQuery'
+import type { FilterConfig, SearchConfig } from './useListPage.types'
+import {
+  SMART_FILTER_THRESHOLD,
+  clearSessionFilters,
+  setSessionFilters,
+  snakeToTitle,
+} from './useListPage.utils'
+
+/** Dependencies injected by useListPage. */
+export interface UseListFiltersDeps {
+  /** Entity name used for the registry lookup. */
+  entityName: string
+  /** EntityManager (needs .request for optionsEndpoint mode). */
+  manager: { request: (method: string, endpoint: string) => Promise<unknown> }
+  /** Orchestrator, forwarded to FilterQuery for optionsEntity mode. */
+  orchestrator: QueryOrchestratorLike | null | undefined
+  /** Loaded list items (source for optionsFromCache mode). */
+  items: Ref<unknown[]>
+  /** Current page ref — filter changes reset it to 1. */
+  page: Ref<number>
+  /** Search query ref (shared with the search subsystem). */
+  searchQuery: Ref<string>
+  route: RouteLocationNormalizedLoaded
+  router: Router
+  /** Session-restored filter values (already stripped of _search). */
+  savedFilters: Record<string, unknown> | null
+  persistFilters: boolean
+  syncUrlParams: boolean
+  autoLoadFilters: boolean
+  filterSessionKey: string
+  /** Entity filters registry (injected by the consuming app). */
+  entityFilters: Record<string, { search?: SearchConfig; filters?: FilterConfig[] }>
+  /** Thunks — resolved lazily, the targets are declared later in useListPage. */
+  loadItems: () => void
+  setSearch: (searchCfg: Partial<SearchConfig>) => void
+  invokeFilterAlterHook: () => Promise<void>
+}
+
+export interface UseListFiltersReturn {
+  filtersMap: Ref<Map<string, FilterConfig>>
+  filterValues: Ref<Record<string, unknown>>
+  filters: ComputedRef<FilterConfig[]>
+  hasActiveFilters: ComputedRef<boolean>
+  addFilter: (name: string, filterConfig: Omit<FilterConfig, 'name'>) => void
+  removeFilter: (name: string) => void
+  setFilterValue: (name: string, value: unknown) => void
+  updateFilters: (newValues: Record<string, unknown>) => void
+  onFiltersChanged: () => void
+  clearFilters: () => void
+  isFilterAtDefault: (name: string) => boolean
+  initFromRegistry: () => void
+  loadFilterOptions: () => Promise<void>
+  updateCacheBasedFilters: () => Promise<void>
+  restoreFilters: () => void
+}
+
+export function useListFilters(deps: UseListFiltersDeps): UseListFiltersReturn {
+  const {
+    entityName,
+    manager,
+    orchestrator,
+    items,
+    page,
+    searchQuery,
+    route,
+    router,
+    savedFilters,
+    persistFilters,
+    syncUrlParams,
+    autoLoadFilters,
+    filterSessionKey,
+    entityFilters,
+    loadItems,
+    setSearch,
+    invokeFilterAlterHook,
+  } = deps
+
+  const filtersMap = ref<Map<string, FilterConfig>>(new Map())
+  const filterValues = ref<Record<string, unknown>>(savedFilters || {})
+
+  function addFilter(name: string, filterConfig: Omit<FilterConfig, 'name'>): void {
+    filtersMap.value.set(name, {
+      name,
+      type: 'select',
+      placeholder: name,
+      ...filterConfig,
+    })
+    if (filterValues.value[name] === undefined) {
+      filterValues.value[name] = filterConfig.default ?? null
+    }
+  }
+
+  function removeFilter(name: string): void {
+    filtersMap.value.delete(name)
+    delete filterValues.value[name]
+  }
+
+  function setFilterValue(name: string, value: unknown): void {
+    filterValues.value = { ...filterValues.value, [name]: value }
+  }
+
+  function updateFilters(newValues: Record<string, unknown>): void {
+    filterValues.value = { ...filterValues.value, ...newValues }
+    onFiltersChanged()
+  }
+
+  function onFiltersChanged(): void {
+    page.value = 1
+    loadItems()
+    if (persistFilters) {
+      const toPersist: Record<string, unknown> = {}
+      for (const [name, value] of Object.entries(filterValues.value)) {
+        const filterDef = filtersMap.value.get(name)
+        if (
+          filterDef?.persist !== false &&
+          value !== null &&
+          value !== undefined &&
+          value !== ''
+        ) {
+          toPersist[name] = value
+        }
+      }
+      if (searchQuery.value) {
+        toPersist._search = searchQuery.value
+      }
+      setSessionFilters(filterSessionKey, toPersist)
+    }
+    if (syncUrlParams) {
+      const query = { ...route.query } as Record<string, string>
+      for (const [name, value] of Object.entries(filterValues.value)) {
+        if (value !== null && value !== undefined && value !== '') {
+          query[name] = String(value)
+        } else {
+          delete query[name]
+        }
+      }
+      if (searchQuery.value) {
+        query.search = searchQuery.value
+      } else {
+        delete query.search
+      }
+      router.replace({ query })
+    }
+  }
+
+  function clearFilters(): void {
+    const cleared: Record<string, unknown> = {}
+    for (const [key, filterDef] of filtersMap.value.entries()) {
+      cleared[key] = filterDef.default ?? null
+    }
+    filterValues.value = cleared
+    searchQuery.value = ''
+    if (persistFilters) {
+      clearSessionFilters(filterSessionKey)
+    }
+    if (syncUrlParams) {
+      const query = { ...route.query } as Record<string, string>
+      for (const key of filtersMap.value.keys()) {
+        delete query[key]
+      }
+      delete query.search
+      router.replace({ query })
+    }
+    page.value = 1
+    loadItems()
+  }
+
+  const filters = computed(() => Array.from(filtersMap.value.values()))
+
+  /**
+   * Check if a filter is at its default value
+   * Used for styling: default = blue (info), modified = orange (warning)
+   */
+  function isFilterAtDefault(name: string): boolean {
+    const filterDef = filtersMap.value.get(name)
+    if (!filterDef) return true
+    const currentValue = filterValues.value[name]
+    const defaultValue = filterDef.default ?? null
+    return currentValue === defaultValue
+  }
+
+  /**
+   * Check if any filter is NOT at its default value (or search is active)
+   * Useful to show a "clear filters" button only when needed
+   */
+  const hasActiveFilters = computed(() => {
+    if (searchQuery.value) return true
+    for (const [name, filterDef] of filtersMap.value.entries()) {
+      const currentValue = filterValues.value[name]
+      const defaultValue = filterDef.default ?? null
+      if (currentValue !== defaultValue) return true
+    }
+    return false
+  })
+
+  function initFromRegistry(): void {
+    if (!autoLoadFilters) return
+
+    const entityConfig = entityFilters[entityName]
+    if (!entityConfig) return
+
+    if (entityConfig.search) {
+      setSearch(entityConfig.search)
+    }
+
+    if (entityConfig.filters) {
+      for (const filterDef of entityConfig.filters) {
+        addFilter(filterDef.name, filterDef)
+      }
+    }
+  }
+
+  async function loadFilterOptions(): Promise<void> {
+    // Process filters configured directly via addFilter() (smart filter modes)
+    for (const [filterName, filterDef] of filtersMap.value) {
+      if (filterDef.options && filterDef.options.length > 1) continue
+      if (filterDef.optionsFromCache) continue
+
+      try {
+        let rawOptions: Array<{ label: string; value: unknown }> | null = null
+
+        // Mode 1: optionsEntity - fetch from related EntityManager via FilterQuery
+        if (filterDef.optionsEntity) {
+          const filterQuery = new FilterQuery({
+            source: 'entity',
+            entity: filterDef.optionsEntity,
+            label: filterDef.optionLabel || 'name',
+            value: filterDef.optionValue || 'id',
+          })
+
+          rawOptions = (await filterQuery.getOptions(orchestrator)) as Array<{
+            label: string
+            value: unknown
+          }>
+          filterDef._filterQuery = filterQuery
+        }
+        // Mode 2: optionsEndpoint - fetch from API endpoint
+        else if (filterDef.optionsEndpoint) {
+          const endpoint =
+            filterDef.optionsEndpoint === true
+              ? `distinct/${filterName}`
+              : filterDef.optionsEndpoint
+          const response = await manager.request('GET', endpoint as string)
+          const data = Array.isArray(response)
+            ? response
+            : ((response as Record<string, unknown>)?.items as unknown[]) || []
+          rawOptions = data.map((opt) => {
+            if (typeof opt === 'object' && opt !== null) {
+              const o = opt as Record<string, unknown>
+              return {
+                label: (o.label || o.name || String(o.value ?? o.id)) as string,
+                value: o.value ?? o.id,
+              }
+            }
+            return { label: snakeToTitle(String(opt)), value: opt }
+          })
+        }
+
+        if (rawOptions !== null) {
+          const cacheOptions = filterDef.cacheOptions ?? 'auto'
+          let shouldCache = cacheOptions === true
+
+          if (cacheOptions === 'auto') {
+            shouldCache = rawOptions.length <= SMART_FILTER_THRESHOLD
+          }
+
+          const componentType =
+            filterDef.component || (shouldCache ? 'dropdown' : 'autocomplete')
+          const allLabel =
+            filterDef.allLabel || filterDef.placeholder || `All ${snakeToTitle(filterName)}`
+          let finalOptions = [{ label: allLabel, value: null as unknown }, ...rawOptions]
+
+          if (typeof filterDef.processor === 'function') {
+            finalOptions = filterDef.processor(finalOptions)
+          }
+
+          const updatedFilter: FilterConfig = {
+            ...filterDef,
+            options: finalOptions,
+            type: componentType,
+            _cacheOptions: shouldCache,
+            _optionsLoaded: shouldCache,
+          }
+          delete updatedFilter.optionLabel
+          delete updatedFilter.optionValue
+          filtersMap.value.set(filterName, updatedFilter)
+        }
+      } catch (error) {
+        console.warn(`[qdadm] Failed to load options for filter "${filterName}":`, error)
+      }
+    }
+
+    // Invoke filter:alter hooks after all options are loaded
+    await invokeFilterAlterHook()
+
+    // Trigger Vue reactivity
+    filtersMap.value = new Map(filtersMap.value)
+  }
+
+  async function updateCacheBasedFilters(): Promise<void> {
+    if (items.value.length === 0) return
+
+    let hasChanges = false
+
+    for (const [filterName, filterDef] of filtersMap.value) {
+      if (!filterDef.optionsFromCache) continue
+      if (filterDef._optionsLoaded) continue
+      // Skip if filter has an explicit query property (advanced usage)
+      if (filterDef.query) continue
+
+      const currentValue = filterValues.value[filterName]
+      if (currentValue !== null && currentValue !== undefined && currentValue !== '') {
+        continue
+      }
+
+      const fieldName =
+        typeof filterDef.optionsFromCache === 'string' ? filterDef.optionsFromCache : filterName
+
+      const filterQuery = new FilterQuery({
+        source: 'field',
+        field: fieldName,
+      })
+
+      // Provide a minimal mock manager with cached data for field-based filtering
+      filterQuery.setParentManager({
+        _cache: items.value,
+        list: async () => ({ items: items.value }),
+      })
+
+      const rawOptions = (await filterQuery.getOptions()) as Array<{ label: string; value: unknown }>
+
+      const cacheOptions = filterDef.cacheOptions ?? 'auto'
+      let shouldCache = true
+
+      if (cacheOptions === 'auto') {
+        shouldCache = rawOptions.length <= SMART_FILTER_THRESHOLD
+      } else if (cacheOptions === false) {
+        shouldCache = false
+      }
+
+      const componentType =
+        filterDef.component ||
+        (rawOptions.length <= SMART_FILTER_THRESHOLD ? 'dropdown' : 'autocomplete')
+
+      const allLabel =
+        filterDef.allLabel || filterDef.placeholder || `All ${snakeToTitle(filterName)}`
+      let finalOptions = [
+        { label: allLabel, value: null as unknown },
+        ...rawOptions.map((opt) => ({
+          label: snakeToTitle(String(opt.label)),
+          value: opt.value,
+        })),
+      ]
+
+      if (typeof filterDef.processor === 'function') {
+        finalOptions = filterDef.processor(finalOptions)
+      }
+
+      const updatedFilter: FilterConfig = {
+        ...filterDef,
+        options: finalOptions,
+        type: componentType,
+        _cacheOptions: shouldCache,
+        _optionsLoaded: true,
+        _filterQuery: filterQuery,
+      }
+
+      filtersMap.value.set(filterName, updatedFilter)
+      hasChanges = true
+    }
+
+    if (hasChanges) {
+      filtersMap.value = new Map(filtersMap.value)
+    }
+  }
+
+  function restoreFilters(): void {
+    for (const key of filtersMap.value.keys()) {
+      if (route.query[key] !== undefined) {
+        let value: unknown = route.query[key]
+        if (value === 'true') value = true
+        else if (value === 'false') value = false
+        else if (value === 'null') value = null
+        else if (!isNaN(Number(value)) && value !== '') value = Number(value)
+        filterValues.value[key] = value
+      }
+    }
+    if (route.query.search) {
+      searchQuery.value = route.query.search as string
+    }
+  }
+
+  return {
+    filtersMap,
+    filterValues,
+    filters,
+    hasActiveFilters,
+    addFilter,
+    removeFilter,
+    setFilterValue,
+    updateFilters,
+    onFiltersChanged,
+    clearFilters,
+    isFilterAtDefault,
+    initFromRegistry,
+    loadFilterOptions,
+    updateCacheBasedFilters,
+    restoreFilters,
+  }
+}