@quazardous/qdadm 2.4.2 → 2.4.4

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@quazardous/qdadm",
-  "version": "2.4.2",
+  "version": "2.4.4",
   "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,
+  }
+}

package/src/composables/useListPage.ts

@@ -33,7 +33,6 @@ import { useConfirm } from 'primevue/useconfirm'
 import { useHooks } from './useHooks.js'
 import { useEntityItemPage, type ParentConfig, type UseEntityItemPageReturn } from './useEntityItemPage.js'
 import { useActiveStack } from '../chain/useActiveStack.js'
-import { FilterQuery } from '../query/FilterQuery'
 import { useI18n } from '../i18n/useI18n'
 import { formatDateOnly } from '../utils/formatters'
 
@@ -85,17 +84,15 @@ export type {
 // Stateless utilities (cookies, session storage, formatters, constants).
 import {
   PAGE_SIZE_OPTIONS,
-  SMART_FILTER_THRESHOLD,
-  clearSessionFilters,
   getSavedPageSize,
   getSessionFilters,
   getSessionSort,
   setSessionSort,
   persistPageSize,
-  setSessionFilters,
-  snakeToTitle,
 } from './useListPage.utils'
 import { useActionRegistry } from './useActionRegistry'
+import { useListFilters } from './useListPage.filters'
+import { useListAlterHooks } from './useListPage.alterHooks'
 import { useOrchestrator } from '../orchestrator/useOrchestrator.js'
 import { createOrchestratorToast } from './useOrchestratorToast'
 
@@ -514,323 +511,45 @@ export function useListPage<T = unknown>(config: UseListPageOptions<T>): UseList
 
   const cards = computed(() => Array.from(cardsMap.value.values()))
 
-  // ============ FILTERS ============
-  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
+  // ============ FILTERS (#1195 — extracted subsystem) ============
+  // invokeFilterAlterHook is a thunk: alterHooks is declared after the
+  // actions section (it needs the action registry) and only runs post-setup.
+  const listFilters = useListFilters({
+    entityName,
+    manager,
+    orchestrator,
+    items: items as Ref<unknown[]>,
+    page,
+    searchQuery,
+    route,
+    router,
+    savedFilters,
+    persistFilters,
+    syncUrlParams,
+    autoLoadFilters,
+    filterSessionKey,
+    entityFilters,
+    loadItems: () => loadItems(),
+    setSearch: (searchCfg) => setSearch(searchCfg),
+    invokeFilterAlterHook: () => alterHooks.invokeFilterAlterHook(),
   })
-
-  // ============ AUTO-LOAD FROM REGISTRY ============
-
-  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
-    }
-  }
+  const {
+    filtersMap,
+    filterValues,
+    filters,
+    hasActiveFilters,
+    addFilter,
+    removeFilter,
+    setFilterValue,
+    updateFilters,
+    onFiltersChanged,
+    clearFilters,
+    isFilterAtDefault,
+    initFromRegistry,
+    loadFilterOptions,
+    updateCacheBasedFilters,
+    restoreFilters,
+  } = listFilters
 
   // ============ ACTIONS ============
   function resolveValue<T>(value: T | ((row: unknown) => T), row: unknown): T {
@@ -852,7 +571,6 @@ export function useListPage<T = unknown>(config: UseListPageOptions<T>): UseList
       }
     },
   })
-  const actionsMap = actionRegistry.actionsMap
 
   function addAction(name: string, actionConfig: Omit<ActionConfig, 'name'>): void {
     actionRegistry.add({ name, ...actionConfig } as ActionConfig)
@@ -1215,96 +933,18 @@ export function useListPage<T = unknown>(config: UseListPageOptions<T>): UseList
     }
   })
 
-  // ============ HOOKS ============
-
-  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)
-  }
-
-  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)
-      }
-    }
-  }
+  // ============ HOOKS (#1195 — extracted subsystem) ============
+  const alterHooks = useListAlterHooks({
+    hooks,
+    entity,
+    manager,
+    columnsMap,
+    filtersMap,
+    filterValues,
+    headerActionsMap,
+    actionRegistry,
+  })
+  const { invokeListAlterHook } = alterHooks
 
   // ============ LIFECYCLE ============
   initFromRegistry()

package/src/entity/EntityManager.query.ts

@@ -1,6 +1,7 @@
 import { QueryExecutor, type QueryObject } from '../query/QueryExecutor'
 import type { ListParams, ListResult } from '../types'
 import type { EntityManagerInternal, OperationStats, QueryOptions } from './EntityManager.types'
+import { nullSortRank, type NullSortMode } from '../query/clientFilter'
 
 type Self = EntityManagerInternal<any>
 
@@ -172,17 +173,22 @@ export function applyQueryMethods(EntityManagerClass: { prototype: any }): void
     // may still BE cache.items — an in-place sort would mutate the cache,
     // making later unsorted reads return whatever order the last sort left.
     if (sort_by) {
+      // Resolve null placement: field config > manager option > 'last'
+      const fieldCfg = this.getFieldConfig?.(sort_by) as { nullSort?: NullSortMode } | null
+      const nullMode: NullSortMode = fieldCfg?.nullSort ?? this.nullSort ?? 'last'
+      const nullCmp = nullSortRank(nullMode, sort_order === 'asc' ? 'asc' : 'desc')
       result = [...result]
       result.sort((a: any, b: any) => {
         const aVal = a[sort_by]
         const bVal = b[sort_by]
 
-        // Nulls always sort LAST, both directions (#1221) — matches the
-        // storage adapters' shared comparator; direction-aware placement
-        // put "never seen" rows on top of every desc date sort.
+        // Null placement is configurable per field/manager (#1222 —
+        // depends on the API and the field semantics). Default 'last'
+        // keeps the #1221 behavior; e.g. nullSort: 'low' makes "Never"
+        // sort beyond the oldest period on a last-seen date column.
         if (aVal == null && bVal == null) return 0
-        if (aVal == null) return 1
-        if (bVal == null) return -1
+        if (aVal == null) return nullCmp
+        if (bVal == null) return -nullCmp
 
         // Compare
         if (typeof aVal === 'string' && typeof bVal === 'string') {

package/src/entity/EntityManager.ts

@@ -30,6 +30,7 @@ import type {
   StorageResolution,
   Orchestrator,
 } from './EntityManager.types'
+import type { NullSortMode } from '../query/clientFilter'
 
 // Re-export public types from types file
 export type {
@@ -83,6 +84,8 @@ export class EntityManager<T extends EntityRecord = EntityRecord> {
   protected _fields: Record<string, FieldConfig>
 
   localFilterThreshold: number | null
+  /** Default null placement for local sorts (#1222); field-level nullSort wins. */
+  nullSort?: NullSortMode
   protected _cacheTtlMs: number | null
   protected _asymmetric: boolean
   protected _detailCache: DetailCacheState<T> = { items: new Map() }
@@ -153,6 +156,7 @@ export class EntityManager<T extends EntityRecord = EntityRecord> {
       badges = null,
       fields = {},
       localFilterThreshold = null,
+      nullSort,
       cacheTtlMs = null,
       asymmetric = false,
       detailCacheTtlMs = 0,
@@ -183,6 +187,7 @@ export class EntityManager<T extends EntityRecord = EntityRecord> {
     this._fields = fields
 
     this.localFilterThreshold = localFilterThreshold
+    this.nullSort = nullSort
     this._cacheTtlMs = cacheTtlMs
     this._asymmetric = asymmetric
     this._detailCacheTtlMs = detailCacheTtlMs

package/src/entity/EntityManager.types.ts

@@ -11,6 +11,7 @@ import type {
 } from '../types'
 import type { AuthUser, EntityAuthAdapter as IEntityAuthAdapter } from './auth/EntityAuthAdapter'
 import type { SignalBus } from '../kernel/SignalBus'
+import type { NullSortMode } from '../query/clientFilter'
 import type { HookRegistry } from '../hooks/HookRegistry'
 
 // Circular type import — safe because `import type` is erased at runtime
@@ -214,6 +215,8 @@ export interface EntityManagerOptions<T extends EntityRecord = EntityRecord> {
   badges?: (entity: T) => EntityBadge[]
   fields?: Record<string, FieldConfig>
   localFilterThreshold?: number | null
+  /** Default null placement for local sorts: 'first' | 'last' | 'low' | 'high' (default 'last', #1222). Field-level nullSort wins. */
+  nullSort?: NullSortMode
   /** Cache TTL in milliseconds (0=disabled, -1=infinite, >0=TTL). Overrides global, overridden by storage. */
   cacheTtlMs?: number | null
   /** Asymmetric mode: list() and get() return different structures. get() skips list cache. */

package/src/index.ts

@@ -305,8 +305,11 @@ export {
   searchItems,
   paginate,
   defaultGenerateId,
+  nullSortRank,
   type SortOrder,
   type FilterItemsOptions,
+  type NullSortMode,
+  type SortItemsOptions,
 } from './query/clientFilter'
 export { useChildPage, type UseChildPageReturn } from './composables/useChildPage'
 export { useSidebarState, SIDEBAR_COLLAPSED_KEY } from './composables/useSidebarState'

package/src/query/FilterQuery.ts

@@ -73,7 +73,7 @@ interface QueryManagerLike {
 /**
  * Minimal interface for Orchestrator (to avoid circular deps)
  */
-interface QueryOrchestratorLike {
+export interface QueryOrchestratorLike {
   get(name: string): QueryManagerLike | null | undefined
 }
 

package/src/query/clientFilter.ts

@@ -15,14 +15,55 @@
 
 export type SortOrder = 'asc' | 'desc'
 
-/** Sort by a field, nulls/undefined last — the canonical adapter comparator. */
-export function sortItems<T>(items: T[], sortBy?: string | null, sortOrder: SortOrder = 'asc'): T[] {
+/**
+ * Null placement when sorting (#1222 — configurable, it depends on the
+ * API and the field semantics):
+ * - 'last'  (default): nulls at the end, both directions — the historical
+ *   adapter behavior, keeps empty rows out of the way.
+ * - 'first': nulls at the top, both directions.
+ * - 'low':   null behaves as the lowest value — first in asc, last in
+ *   desc. Right for "last seen" dates ("Never" sorts beyond the oldest
+ *   period); equals PrimeVue nullSortOrder: -1.
+ * - 'high':  null behaves as the highest value — last in asc, first in desc.
+ */
+export type NullSortMode = 'first' | 'last' | 'low' | 'high'
+
+export interface SortItemsOptions {
+  nulls?: NullSortMode
+}
+
+export function nullSortRank(mode: NullSortMode, sortOrder: SortOrder): number {
+  // Return the comparator result for "a is null, b is not"
+  switch (mode) {
+    case 'first':
+      return -1
+    case 'low':
+      return sortOrder === 'asc' ? -1 : 1
+    case 'high':
+      return sortOrder === 'asc' ? 1 : -1
+    case 'last':
+    default:
+      return 1
+  }
+}
+
+/** Sort by a field — the canonical comparator (null placement configurable). */
+export function sortItems<T>(
+  items: T[],
+  sortBy?: string | null,
+  sortOrder: SortOrder = 'asc',
+  options: SortItemsOptions = {}
+): T[] {
   if (!sortBy) return items
+  const { nulls = 'last' } = options
   return items.sort((a, b) => {
     const aVal = a[sortBy as keyof T]
     const bVal = b[sortBy as keyof T]
-    if (aVal === undefined || aVal === null) return 1
-    if (bVal === undefined || bVal === null) return -1
+    const aNull = aVal === undefined || aVal === null
+    const bNull = bVal === undefined || bVal === null
+    if (aNull && bNull) return 0
+    if (aNull) return nullSortRank(nulls, sortOrder)
+    if (bNull) return -nullSortRank(nulls, sortOrder)
     if (aVal < bVal) return sortOrder === 'asc' ? -1 : 1
     if (aVal > bVal) return sortOrder === 'asc' ? 1 : -1
     return 0

package/src/types/index.ts

@@ -79,6 +79,8 @@ export type FieldType =
  * Field configuration
  */
 export interface FieldConfig {
+  /** Null placement when this field is locally sorted: 'first' | 'last' | 'low' | 'high' (#1222). */
+  nullSort?: 'first' | 'last' | 'low' | 'high'
   type: FieldType
   label?: string
   required?: boolean