@quazardous/qdadm 2.19.0 → 2.20.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@quazardous/qdadm",
-  "version": "2.19.0",
+  "version": "2.20.0",
   "description": "Vue 3 framework for admin dashboards with PrimeVue",
   "author": "quazardous",
   "license": "MIT",
@@ -19,7 +19,7 @@
     "test": "vitest run",
     "test:watch": "vitest",
     "gen:i18n-defaults": "node scripts/gen-i18n-defaults.mjs",
-    "type-check": "vue-tsc --noEmit",
+    "type-check": "vue-tsc --noEmit && vue-tsc --noEmit -p tsconfig.typetest.json",
     "lint": "eslint src/",
     "lint:fix": "eslint src/ --fix",
     "format": "prettier --write src/",

package/src/components/lists/ListPage.vue

@@ -104,6 +104,12 @@ const props = defineProps({
   rows: { type: Number, default: 10 },
   rowsPerPageOptions: { type: Array as PropType<number[]>, default: () => [10, 50, 100] },
   totalRecords: { type: Number, default: 0 },
+  /**
+   * Row offset of the page being shown — what positions the paginator (#2145).
+   * Required in lazy mode: the table is handed one page of rows and cannot
+   * infer which page they are.
+   */
+  first: { type: Number, default: 0 },
   lazy: { type: Boolean, default: false },
 
   // Sorting
@@ -438,6 +444,7 @@ function getFilterClass(filter: FilterConfig): Record<string, boolean> {
         :rows="rows"
         :rowsPerPageOptions="rowsPerPageOptions"
         :totalRecords="totalRecords"
+        :first="first"
         :lazy="lazy"
         :sortField="sortField ?? undefined"
         :sortOrder="sortOrder"

package/src/composables/index.ts

@@ -30,10 +30,13 @@ export * from './useJsonSyntax'
 export {
   useListPage,
   PAGE_SIZE_OPTIONS,
+  FILTER_TYPES,
   type UseListPageOptions,
   type UseListPageReturn,
   type ColumnConfig,
   type FilterConfig,
+  type FilterOptions,
+  type FilterType,
   type ActionConfig as ListActionConfig,
   type ResolvedAction,
   type HeaderActionConfig,

package/src/composables/useListPage.filters.ts

@@ -7,9 +7,10 @@
  * 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 { FILTER_TYPES } from './useListPage.types'
+import type { FilterConfig, FilterOptions, SearchConfig } from './useListPage.types'
+import type { RouteStatePersister } from '../routeState'
 import {
   SMART_FILTER_THRESHOLD,
   clearSessionFilters,
@@ -29,14 +30,38 @@ export interface UseListFiltersDeps {
   items: Ref<unknown[]>
   /** Current page ref — filter changes reset it to 1. */
   page: Ref<number>
+  /** Rows per page — persisted alongside the rest (#2146). */
+  pageSize: Ref<number>
+  /** Active sort field, persisted alongside the rest (#2146). */
+  sortField: Ref<string | null>
+  /** Active sort direction. */
+  sortOrder: Ref<number>
+  /**
+   * Whether the sort is remembered at all.
+   *
+   * Its own flag rather than folded into `routeStateWrites`, because it has
+   * always been separately switchable and a seam refactor must not quietly
+   * take an option away.
+   */
+  persistSort: boolean
   /** 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
+  /** Where this list's state is remembered (#2146). */
+  persister: RouteStatePersister | null
+  /** This list's namespace, so two lists on one route stop colliding. */
+  routeStateScope: string
+  /**
+   * Whether this list may WRITE its state back.
+   *
+   * Separate from having a persister because reading and writing were always
+   * separate here: `syncUrlParams: false` stopped the query string being
+   * written and never stopped it being read, so a hand-typed deep link still
+   * restored. Collapsing the two would have changed that quietly.
+   */
+  routeStateWrites: boolean
   autoLoadFilters: boolean
   filterSessionKey: string
   /** Entity filters registry (injected by the consuming app). */
@@ -51,7 +76,7 @@ export interface UseListFiltersReturn {
   filterValues: Ref<Record<string, unknown>>
   filters: ComputedRef<FilterConfig[]>
   hasActiveFilters: ComputedRef<boolean>
-  addFilter: (name: string, filterConfig: Omit<FilterConfig, 'name'>) => void
+  addFilter: (name: string, filterConfig: FilterOptions) => void
   removeFilter: (name: string) => void
   setFilterValue: (name: string, value: unknown) => void
   updateFilters: (newValues: Record<string, unknown>) => void
@@ -74,11 +99,15 @@ export function useListFilters(deps: UseListFiltersDeps): UseListFiltersReturn {
     items,
     page,
     searchQuery,
-    route,
-    router,
     savedFilters,
     persistFilters,
-    syncUrlParams,
+    persister,
+    routeStateScope,
+    routeStateWrites,
+    pageSize,
+    sortField,
+    sortOrder,
+    persistSort,
     autoLoadFilters,
     filterSessionKey,
     entityFilters,
@@ -89,16 +118,21 @@ export function useListFilters(deps: UseListFiltersDeps): UseListFiltersReturn {
   const filtersMap = ref<Map<string, FilterConfig>>(new Map())
   const filterValues = ref<Record<string, unknown>>(savedFilters || {})
 
-  /** Names the URL sync already owns — a filter cannot have them (#2113). */
+  /** Names the route state already owns — a filter cannot have them (#2113). */
   const RESERVED_QUERY_KEYS = new Set(['page', 'search'])
   const warnedReserved = new Set<string>()
 
   /**
-   * A filter named `page` or `search` silently overwrites the query key of
+   * A filter named `page` or `search` silently overwrites the stored key of
    * the same name, and is overwritten back on restore. `search` has behaved
    * this way since the URL sync existed and nobody ever reported it, which
-   * says how quiet the failure is; `page` joins the reserved set now that the
-   * page number lives in the URL too.
+   * says how quiet the failure is; `page` joined it once the page number
+   * started being remembered too.
+   *
+   * SCOPING DID NOT FIX THIS. Prefixing keys by entity separates this list
+   * from other lists; it does not separate the list from qdadm's own two
+   * keys, which live in the same scope it does — `offers.page` is written by
+   * the pager whatever a filter called `page` wants.
    *
    * We name what happens INSTEAD of what was asked, rather than dropping the
    * filter — renaming someone's filter behind their back would be a worse
@@ -106,20 +140,53 @@ export function useListFilters(deps: UseListFiltersDeps): UseListFiltersReturn {
    */
   function warnIfReservedName(name: string): void {
     if (!RESERVED_QUERY_KEYS.has(name)) return
-    if (!syncUrlParams) return
+    // Gated on writing, not on the URL specifically: the collision is with
+    // whatever medium this list persists to.
+    if (!routeStateWrites) return
     if (warnedReserved.has(name)) return
     warnedReserved.add(name)
     console.warn(
-      `[qdadm] Filter "${name}" on "${entityName}" collides with the URL ` +
-        `parameter of the same name. With syncUrlParams on, the list's own ` +
+      `[qdadm] Filter "${name}" on "${entityName}" collides with the key of ` +
+        `the same name in this list's persisted route state. The list's own ` +
         `${name === 'page' ? 'page number' : 'search query'} wins and this ` +
-        `filter will not survive a reload. Rename the filter, or set ` +
-        `syncUrlParams: false on this list.`
+        `filter will not survive a reload. Rename the filter, or turn the ` +
+        `persistence off on this list with syncUrlParams: false.`
+    )
+  }
+
+  const warnedTypes = new Set<string>()
+
+  /**
+   * A filter type qdadm cannot render (#2147).
+   *
+   * `ListPage` is binary — an autocomplete, or a `Select` for everything
+   * else, unknown types included. So an invented type does not fail; it
+   * renders as a dropdown with no options, reading "No available options",
+   * and the user concludes there is nothing to choose. Reported by a consumer
+   * whose two `type: 'text'` filters had never filtered anything.
+   *
+   * Warned HERE because this is the last place the filter's NAME is known.
+   * Three screens later there is only an empty control and no way back to
+   * the declaration that caused it.
+   */
+  function warnIfUnknownType(name: string, type: unknown): void {
+    if (type === undefined || type === null) return
+    if (FILTER_TYPES.includes(type as (typeof FILTER_TYPES)[number])) return
+    const key = `${name}:${String(type)}`
+    if (warnedTypes.has(key)) return
+    warnedTypes.add(key)
+    console.warn(
+      `[qdadm] Filter "${name}" on "${entityName}" has type "${String(type)}", ` +
+        `which qdadm cannot render. It will fall back to a dropdown, and ` +
+        `unless you also give it options that dropdown will be empty — ` +
+        `"No available options" — rather than the control you asked for. ` +
+        `Known types: ${FILTER_TYPES.join(', ')}.`
     )
   }
 
-  function addFilter(name: string, filterConfig: Omit<FilterConfig, 'name'>): void {
+  function addFilter(name: string, filterConfig: FilterOptions): void {
     warnIfReservedName(name)
+    warnIfUnknownType(name, filterConfig?.type)
     filtersMap.value.set(name, {
       name,
       type: 'select',
@@ -155,34 +222,37 @@ export function useListFilters(deps: UseListFiltersDeps): UseListFiltersReturn {
    * for a detail view, so that coming back restores it.
    */
   function writeStateToUrl(): void {
-    if (!syncUrlParams) return
-
-    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
-    }
-
-    // Page 1 is the default and stays implicit. Reserved keys are written
-    // last so the list's own state wins a collision — the warning in
-    // addFilter() names that consequence at declaration time.
-    if (page.value > 1) {
-      query.page = String(page.value)
-    } else {
-      delete query.page
-    }
-
-    router.replace({ query })
+    if (!persister || !routeStateWrites) return
+
+    // Page 1 is the default and stays implicit, exactly like an unset filter:
+    // the persister drops null/undefined/'' rather than storing them empty,
+    // so a pristine list leaves a clean link.
+    //
+    // `search` and `page` still share the namespace with the filter names —
+    // the scope separates this list from OTHER lists, not from qdadm's own
+    // keys — which is why addFilter() still warns about a filter called
+    // `page` or `search`.
+    persister.write(routeStateScope, {
+      ...filterValues.value,
+      search: searchQuery.value || null,
+      page: page.value > 1 ? page.value : null,
+      // Always written, never conditional on a default: rows-per-page is a
+      // choice somebody made, and the default is not "unset" — it is what
+      // they get back if we forget. The default composition routes it to a
+      // cookie, so it does not land in a shareable link.
+      pageSize: pageSize.value,
+      // Sort goes to the session under the default composition, so it does
+      // not reach a link either. `persistSort: false` writes null, which the
+      // persister removes — the option has always been able to turn this off
+      // and still can.
+      //
+      // The DIRECTION is stored only when there is a field to apply it to.
+      // An order on its own is not partial state, it is meaningless state,
+      // and storing it would leave `sortOrder: -1` sitting in every unsorted
+      // list's namespace.
+      sort: persistSort ? sortField.value : null,
+      sortOrder: persistSort && sortField.value ? sortOrder.value : null,
+    })
   }
 
   function onFiltersChanged(): void {
@@ -220,15 +290,7 @@ export function useListFilters(deps: UseListFiltersDeps): UseListFiltersReturn {
       clearSessionFilters(filterSessionKey)
     }
     page.value = 1
-    if (syncUrlParams) {
-      const query = { ...route.query } as Record<string, string>
-      for (const key of filtersMap.value.keys()) {
-        delete query[key]
-      }
-      delete query.search
-      delete query.page
-      router.replace({ query })
-    }
+    if (routeStateWrites) persister?.clear(routeStateScope)
     loadItems()
   }
 
@@ -472,23 +534,31 @@ export function useListFilters(deps: UseListFiltersDeps): UseListFiltersReturn {
   }
 
   function restoreFilters(): void {
+    const stored = persister?.read(routeStateScope)
+    if (!stored) return
+
+    // Only keys this list declares as filters: the scope keeps other lists
+    // out, but a persister may still hand back something the app put there.
     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 (stored[key] !== undefined) filterValues.value[key] = stored[key]
     }
-    if (route.query.search) {
-      searchQuery.value = route.query.search as string
+
+    // NOT `typeof === 'string'` (#2147). A term that survives a numeric round
+    // trip — an order id, an invoice, a reference — comes back from the URL
+    // as a number, and a string-only guard dropped it: the box came back
+    // empty and the list unfiltered, so a shared link showed the recipient
+    // something other than what the sender searched for.
+    //
+    // Safe to stringify because the persister no longer coerces lossily: a
+    // value that could not be written back as the same text was left as text.
+    if (stored.search !== null && stored.search !== undefined && stored.search !== '') {
+      searchQuery.value = String(stored.search)
     }
+
     // The page must be restored HERE, before the first loadItems(): restoring
     // it later would mean a first request for page 1 and a second for the
     // real one (#2113).
-    const restoredPage = Number(route.query.page)
+    const restoredPage = Number(stored.page)
     if (Number.isInteger(restoredPage) && restoredPage > 0) {
       page.value = restoredPage
     }

package/src/composables/useListPage.ts

@@ -29,6 +29,12 @@ import {
   type Ref,
 } from 'vue'
 import { useRouter, useRoute, type RouteLocationRaw } from 'vue-router'
+import {
+  createDefaultRouteStatePersister,
+  resolveRouteStatePersister,
+  createRouteStatePersisterFactory,
+  type RouteStatePersister,
+} from '../routeState'
 import { useConfirm } from 'primevue/useconfirm'
 import { useHooks } from './useHooks.js'
 import { useEntityItemPage, type ParentConfig, type UseEntityItemPageReturn } from './useEntityItemPage.js'
@@ -68,6 +74,8 @@ import type {
 export type {
   ColumnConfig,
   FilterConfig,
+  FilterOptions,
+  FilterType,
   ActionConfig,
   ResolvedAction,
   HeaderActionConfig,
@@ -86,11 +94,11 @@ export type {
 // Stateless utilities (cookies, session storage, formatters, constants).
 import {
   PAGE_SIZE_OPTIONS,
-  getSavedPageSize,
+  restorePageSize,
   getSessionFilters,
-  getSessionSort,
-  setSessionSort,
-  persistPageSize,
+  restoreSort,
+  clearSessionSort,
+  retireLegacyPageSizeCookie,
 } from './useListPage.utils'
 import { useActionRegistry } from './useActionRegistry'
 import { useListFilters } from './useListPage.filters'
@@ -101,6 +109,9 @@ import { createOrchestratorToast } from './useOrchestratorToast'
 // Re-export PAGE_SIZE_OPTIONS so existing consumers (qdadm/index.ts,
 // composables/index.ts) keep their import path.
 export { PAGE_SIZE_OPTIONS } from './useListPage.utils'
+// A VALUE, not only a type: a consumer guard should read this list rather
+// than copy it, so adding a type here never turns correct code red (#2147).
+export { FILTER_TYPES } from './useListPage.types'
 
 
 /**
@@ -120,6 +131,7 @@ export function useListPage<T = unknown>(config: UseListPageOptions<T>): UseList
     persistFilters = true,
     persistSort = true,
     syncUrlParams = true,
+    routeState = null,
     autoLoadFilters = true,
     onBeforeLoad = null,
     onAfterLoad = null,
@@ -215,6 +227,41 @@ export function useListPage<T = unknown>(config: UseListPageOptions<T>): UseList
   // Session key for filter persistence (based on entity name)
   const filterSessionKey = entity || entityName
 
+  // App-wide route-state default (#2146). Null when the kernel said nothing,
+  // or when there is no kernel at all — which is the case in tests.
+  const kernelRouteState = inject<string | RouteStatePersister | null>('qdadmRouteState', null)
+
+  // Where this list remembers what it is showing (#2146).
+  //
+  // WHO DECIDES, most specific first: this list, then the entity (so every
+  // screen showing it agrees), then the kernel, then the default composition.
+  // Each level exists because somebody has to be able to say it at that level
+  // — a list is a screen's decision, an entity's medium is a modelling one,
+  // and the app-wide floor belongs in the bootstrap.
+  //
+  // Built HERE, before the state refs, because `pageSize` is restored from it
+  // and the table needs a row count from its very first render.
+  const routeStateScope = entity || entityName
+  const chosenRouteState = routeState ?? manager.routeState ?? kernelRouteState
+  const persister: RouteStatePersister = chosenRouteState
+    ? resolveRouteStatePersister(
+        chosenRouteState,
+        createRouteStatePersisterFactory({ router, route })
+      )
+    : createDefaultRouteStatePersister({ router, route })
+
+  // `syncUrlParams` governs WRITING, and only ever has: a list configured
+  // with `false` still restored from a query string typed by hand. Kept
+  // exactly, because moving this behind a seam must not change what any
+  // existing app does.
+  //
+  // Naming a persister is a deliberate choice about a medium, so it answers
+  // the URL flag rather than obeying it: `routeState` set means read AND
+  // write, whatever `syncUrlParams` says about the query string.
+  const routeStateWrites = chosenRouteState ? true : syncUrlParams
+
+  const storedRouteState = persister.read(routeStateScope)
+
   // Entity filters registry (optional, provided by consuming app)
   const entityFilters = inject<Record<string, { search?: SearchConfig; filters?: FilterConfig[] }>>(
     'qdadmEntityFilters',
@@ -238,15 +285,29 @@ export function useListPage<T = unknown>(config: UseListPageOptions<T>): UseList
 
   // Pagination
   const page = ref(1)
-  const pageSize = ref(getSavedPageSize(defaultPageSize))
+  // Rows per page comes through the seam now (#2146) — by default routed to
+  // the same cookie it has always used, because it is a comfort setting
+  // somebody chose once, not something a link should impose on its reader.
+  //
+  // The legacy bare-number cookie is read when the seam has nothing, so an
+  // existing user's choice survives the move; the first change retires it.
+  const pageSize = ref(restorePageSize(storedRouteState?.pageSize, defaultPageSize))
   const totalRecords = ref(0)
   const rowsPerPageOptions = PAGE_SIZE_OPTIONS
 
-  // Sorting — restored from the per-entity session (#1218), defaultSort as
-  // fallback; same persistence discipline as filters/pageSize.
-  const savedSort = persistSort ? getSessionSort(filterSessionKey) : null
-  const sortField = ref<string | null>(savedSort ? savedSort.field : defaultSort)
-  const sortOrder = ref(savedSort ? savedSort.order : defaultSortOrder)
+  // Sorting — through the seam now (#2146), and still landing in the session
+  // by default: the composition routes `sort` back to `sessionStorage` on
+  // purpose, so an ordering keeps surviving a clean `/offers` the way it
+  // always has. Only the key changed, which is why the legacy entry is read
+  // when the seam has nothing.
+  const savedSort = persistSort
+    ? restoreSort(storedRouteState, filterSessionKey, {
+        field: defaultSort,
+        order: defaultSortOrder as 1 | -1,
+      })
+    : { field: defaultSort, order: defaultSortOrder as 1 | -1 }
+  const sortField = ref<string | null>(savedSort.field)
+  const sortOrder = ref<number>(savedSort.order)
 
   // Search
   const searchQuery = ref(savedSearch)
@@ -588,18 +649,38 @@ export function useListPage<T = unknown>(config: UseListPageOptions<T>): UseList
   // ============ FILTERS (#1195 — extracted subsystem) ============
   // loadItems and setSearch are passed as thunks: both are declared further
   // down and only ever run post-setup.
+  // Where this list remembers what it is showing (#2146).
+  //
+  // The scope is the entity, so two lists on one route stop colliding — the
+  // case page-compositions.md currently tells people to dodge by turning
+  // persistence off entirely.
+  //
+  // `syncUrlParams` governs WRITING, and only ever has: a list configured
+  // with `false` still restored from a query string typed by hand. Kept
+  // exactly, because moving this behind a seam must not change what any
+  // existing app does — the asymmetry is arguable, but arguing it belongs in
+  // its own change with its own changelog line.
+  //
+  // Naming a persister is a deliberate choice about a medium, so it answers
+  // the URL flag rather than obeying it: `routeState` set means read AND
+  // write, whatever `syncUrlParams` says about the query string.
+
   const listFilters = useListFilters({
     entityName,
+    persister,
+    routeStateScope,
+    routeStateWrites,
+    pageSize,
+    sortField,
+    sortOrder,
+    persistSort,
     manager,
     orchestrator,
     items: items as Ref<unknown[]>,
     page,
     searchQuery,
-    route,
-    router,
     savedFilters,
     persistFilters,
-    syncUrlParams,
     autoLoadFilters,
     filterSessionKey,
     entityFilters,
@@ -798,7 +879,9 @@ export function useListPage<T = unknown>(config: UseListPageOptions<T>): UseList
   function onPage(event: { page: number; rows: number }): void {
     page.value = event.page + 1
     pageSize.value = event.rows
-    persistPageSize(event.rows)
+    // Written by writeStateToUrl() below, through the persister, rather than
+    // straight to a cookie from here (#2146).
+    retireLegacyPageSizeCookie()
     // The page joins the URL (#2113) — it was the only piece of list state
     // that survived nothing, so leaving a list for a detail view and coming
     // back dropped the user on page 1.
@@ -818,11 +901,12 @@ export function useListPage<T = unknown>(config: UseListPageOptions<T>): UseList
       sortField.value = event.sortField
       sortOrder.value = event.sortOrder as 1 | -1
     }
+    // Written through the persister by writeStateToUrl(), not straight to
+    // the session from here (#2146). The legacy entry is retired at the same
+    // time, so it cannot shadow the seam on a later read.
     if (persistSort) {
-      setSessionSort(filterSessionKey, {
-        field: sortField.value,
-        order: sortOrder.value as 1 | -1,
-      })
+      writeStateToUrl()
+      clearSessionSort(filterSessionKey)
     }
     loadItems()
   }
@@ -1201,6 +1285,10 @@ export function useListPage<T = unknown>(config: UseListPageOptions<T>): UseList
     lazy: true,
     totalRecords: totalRecords.value,
     rows: pageSize.value,
+    // Where the paginator sits (#2145). Derived from `page` rather than held
+    // separately, so the highlighted page and the rows on screen cannot
+    // disagree — which is exactly what they did while this was unbound.
+    first: (page.value - 1) * pageSize.value,
     rowsPerPageOptions,
     sortField: sortField.value,
     sortOrder: sortOrder.value,