@quazardous/qdadm 2.18.0 → 2.20.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@quazardous/qdadm",
-  "version": "2.18.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/",
@@ -54,7 +54,7 @@
     "dist/node"
   ],
   "dependencies": {
-    "@quazardous/qdcore": "^1.1.2",
+    "@quazardous/qdcore": "^1.2.0",
     "@quazardous/qddebug": "^1.2.0",
     "@quazardous/quarkernel": "^2.1.0",
     "yaml": "^2.8.4"
@@ -63,6 +63,7 @@
     "pinia": "^2.0.0 || ^3.0.0 || ^4.0.0",
     "primevue": "^4.0.0",
     "sass-embedded": "^1.0.0",
+    "vanilla-jsoneditor": "^3.13.0",
     "vite": "^5.0.0 || ^6.0.0 || ^7.0.0 || ^8.0.0",
     "vue": "^3.3.0",
     "vue-router": "^4.0.0 || ^5.0.0"
@@ -78,12 +79,9 @@
       "optional": true
     },
     "sass-embedded": {
-      "optional": "true"
+      "optional": true
     }
   },
-  "optionalDependencies": {
-    "vanilla-jsoneditor": "^0.23.0"
-  },
   "keywords": [
     "vue",
     "vue3",

package/src/components/editors/VanillaJsonEditor.vue

@@ -15,7 +15,17 @@
  */
 
 import { ref, watch, onMounted, onUnmounted, nextTick } from 'vue'
-import { JSONEditor, type Content, type ContentErrors, type OnChangeStatus, type Mode } from 'vanilla-jsoneditor'
+// vanilla-jsoneditor 3.x (#1901): the `new JSONEditor(...)` constructor is
+// deprecated — `JSONEditor` is now the Svelte component itself, and the
+// instance type is exported as `JsonEditor`.
+import {
+  createJSONEditor,
+  type JsonEditor,
+  type Content,
+  type ContentErrors,
+  type OnChangeStatus,
+  type Mode,
+} from 'vanilla-jsoneditor'
 import { buildJsonValidator, type Validator, type JSONSchema, type JsonValidatorOptions } from './jsonValidator'
 
 type JsonValue = Record<string, unknown> | unknown[] | string | null
@@ -74,8 +84,8 @@ const emit = defineEmits<{
   'error': [errors: ContentErrors]
 }>()
 
-const containerRef = ref<HTMLElement | null>(null)
-let editor: JSONEditor | null = null
+const containerRef = ref<HTMLDivElement | null>(null)
+let editor: JsonEditor | null = null
 // Flag to prevent onChange from firing during programmatic updates (instance-specific)
 const updatingFromProp = ref<boolean>(false)
 
@@ -102,7 +112,7 @@ onMounted(() => {
     json: parseValue(props.modelValue)
   }
 
-  editor = new JSONEditor({
+  editor = createJSONEditor({
     target: containerRef.value,
     props: {
       content,

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/useLayoutResolver.ts

@@ -34,6 +34,10 @@ import { useRoute } from 'vue-router'
 export const LAYOUT_TYPES = {
   LIST: 'list',
   FORM: 'form',
+  // `show` was emitted by crud({ show }) long before it existed here (#1922).
+  // The resolver returned it, found no component under that key, and fell
+  // back to `base` — gracefully, which is exactly what made it invisible.
+  SHOW: 'show',
   DASHBOARD: 'dashboard',
   BASE: 'base',
 } as const
@@ -46,6 +50,7 @@ export type LayoutType = (typeof LAYOUT_TYPES)[keyof typeof LAYOUT_TYPES]
 export interface LayoutComponentsMap {
   list?: Component | null
   form?: Component | null
+  show?: Component | null
   dashboard?: Component | null
   base?: Component | null
   [key: string]: Component | null | undefined
@@ -63,6 +68,7 @@ interface PageNamePattern {
 const PAGE_NAME_PATTERNS: PageNamePattern[] = [
   { pattern: /List(Page)?$/i, layout: LAYOUT_TYPES.LIST },
   { pattern: /(Edit|Create|Form)(Page)?$/i, layout: LAYOUT_TYPES.FORM },
+  { pattern: /Show(Page)?$/i, layout: LAYOUT_TYPES.SHOW },
   { pattern: /Dashboard(Page)?$/i, layout: LAYOUT_TYPES.DASHBOARD },
 ]
 
@@ -70,6 +76,10 @@ const PAGE_NAME_PATTERNS: PageNamePattern[] = [
 const ROUTE_NAME_PATTERNS: PageNamePattern[] = [
   { pattern: /-list$/i, layout: LAYOUT_TYPES.LIST },
   { pattern: /-(edit|create)$/i, layout: LAYOUT_TYPES.FORM },
+  // Load-bearing, not decoration: an app that declares its detail route by
+  // hand rather than through crud({ show }) has no meta.layout to go on, and
+  // this is the only path that can reach `show` for it (#1922).
+  { pattern: /-show$/i, layout: LAYOUT_TYPES.SHOW },
   { pattern: /-dashboard$/i, layout: LAYOUT_TYPES.DASHBOARD },
   // Common patterns without suffix
   { pattern: /^dashboard$/i, layout: LAYOUT_TYPES.DASHBOARD },

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
     }