@jskit-ai/users-web 0.1.151 → 0.1.153

package/package.descriptor.mjs

@@ -3,7 +3,7 @@ import { HOME_COG_OUTLET } from "./src/shared/toolsOutletContracts.js";
 export default Object.freeze({
   packageVersion: 1,
   packageId: "@jskit-ai/users-web",
-  version: "0.1.151",
+  version: "0.1.153",
   kind: "runtime",
   description: "Users web module: account/profile UI plus shared users web widgets.",
   dependsOn: [
@@ -286,12 +286,12 @@ export default Object.freeze({
     dependencies: {
       runtime: {
         "@mdi/js": "^7.4.47",
-        "@jskit-ai/http-runtime": "0.1.132",
-        "@jskit-ai/realtime": "0.1.131",
-        "@jskit-ai/kernel": "0.1.134",
-        "@jskit-ai/shell-web": "0.1.135",
-        "@jskit-ai/uploads-image-web": "0.1.110",
-        "@jskit-ai/users-core": "0.1.145"
+        "@jskit-ai/http-runtime": "0.1.134",
+        "@jskit-ai/realtime": "0.1.133",
+        "@jskit-ai/kernel": "0.1.136",
+        "@jskit-ai/shell-web": "0.1.137",
+        "@jskit-ai/uploads-image-web": "0.1.112",
+        "@jskit-ai/users-core": "0.1.148"
       },
       dev: {}
     },

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jskit-ai/users-web",
-  "version": "0.1.151",
+  "version": "0.1.153",
   "type": "module",
   "scripts": {
     "test": "node --test"
@@ -46,12 +46,12 @@
   },
   "dependencies": {
     "@mdi/js": "^7.4.47",
-    "@jskit-ai/http-runtime": "0.1.132",
-    "@jskit-ai/kernel": "0.1.134",
-    "@jskit-ai/realtime": "0.1.131",
-    "@jskit-ai/shell-web": "0.1.135",
-    "@jskit-ai/uploads-image-web": "0.1.110",
-    "@jskit-ai/users-core": "0.1.145"
+    "@jskit-ai/http-runtime": "0.1.134",
+    "@jskit-ai/kernel": "0.1.136",
+    "@jskit-ai/realtime": "0.1.133",
+    "@jskit-ai/shell-web": "0.1.137",
+    "@jskit-ai/uploads-image-web": "0.1.112",
+    "@jskit-ai/users-core": "0.1.148"
   },
   "peerDependencies": {
     "@tanstack/vue-query": "^5.90.5",

package/src/client/composables/records/useList.js

@@ -7,7 +7,10 @@ import { resolveOperationAdapter } from "../runtime/operationAdapters.js";
 import { setupOperationErrorReporting } from "../runtime/operationUiHelpers.js";
 import { createListUiRuntime } from "../runtime/listUiRuntime.js";
 import { asPlainObject } from "../support/scopeHelpers.js";
-import { buildRequestQueryObject } from "../support/requestQueryRuntimeSupport.js";
+import {
+  buildRequestQueryObject,
+  createRequestQueryRuntime
+} from "../support/requestQueryRuntimeSupport.js";
 import {
   normalizeListSearchConfig,
   matchesLocalSearch
@@ -57,13 +60,18 @@ function useList({
   editUrlTemplate = "",
   search = null,
   queryParams = null,
+  routeQueryValueResolvers = null,
   requestQueryParams = null,
+  requestFieldsets = null,
   syncToRoute = false
 } = {}) {
   const searchConfig = normalizeListSearchConfig(search);
   const routeSyncConfig = normalizeListSyncToRouteConfig(syncToRoute, {
     defaultSearchParam: searchConfig.queryParam
   });
+  const routeSyncHydrated = ref(
+    routeSyncConfig.enabled !== true || routeSyncConfig.hydrateFromRoute !== true
+  );
   const router = routeSyncConfig.enabled === true ? useRouter() : null;
   const searchQuery = ref(searchConfig.initialQuery);
   const debouncedSearchQuery = ref(searchConfig.initialQuery);
@@ -140,24 +148,29 @@ function useList({
     });
   });
   const queryParamDescriptors = computed(() => {
-    return resolveQueryParamDescriptors(queryParams, queryParamsContext.value);
+    return resolveQueryParamDescriptors(queryParams, queryParamsContext.value, {
+      routeValueResolvers: routeQueryValueResolvers
+    });
   });
-  const requestQueryParamDescriptors = computed(() => {
-    return resolveQueryParamDescriptors(requestQueryParams, queryParamsContext.value);
+  const requestQueryRuntime = createRequestQueryRuntime({
+    requestQueryParams,
+    requestFieldsets,
+    context: queryParamsContext
   });
+  const {
+    activeRequestQueryParamEntries,
+    activeRequestQueryParamsToken,
+    activeRequestFieldsets,
+    activeRequestFieldsetsToken,
+    queryKeyParts: requestQueryKeyParts
+  } = requestQueryRuntime;
   const declaredQueryParamKeys = computed(() => {
     return queryParamDescriptors.value.map((descriptor) => descriptor.key);
   });
   const activeQueryParamEntries = computed(() => {
     return resolveActiveQueryParamEntries(queryParamDescriptors.value);
   });
-  const activeRequestQueryParamEntries = computed(() => {
-    return resolveActiveQueryParamEntries(requestQueryParamDescriptors.value);
-  });
   const activeQueryParamsToken = computed(() => buildQueryParamEntriesToken(activeQueryParamEntries.value));
-  const activeRequestQueryParamsToken = computed(() => {
-    return buildQueryParamEntriesToken(activeRequestQueryParamEntries.value);
-  });
   const writableQueryParamBindings = computed(() => {
     return resolveWritableQueryParamBindings(queryParamDescriptors.value);
   });
@@ -191,7 +204,9 @@ function useList({
     entries.push(...activeRequestQueryParamEntries.value);
     entries.push(...activeQueryParamEntries.value);
 
-    const query = buildRequestQueryObject(entries);
+    const query = buildRequestQueryObject(entries, {
+      fieldsets: activeRequestFieldsets.value
+    });
     const baseOptions = asPlainObject(requestOptions);
     if (Object.keys(query).length < 1) {
       return baseOptions;
@@ -209,9 +224,7 @@ function useList({
       : sourceQueryKey == null
         ? []
         : [sourceQueryKey];
-    if (activeRequestQueryParamsToken.value) {
-      baseQueryKey.push("__request_query__", activeRequestQueryParamsToken.value);
-    }
+    baseQueryKey.push(...requestQueryKeyParts.value);
     if (querySearchEnabled.value) {
       baseQueryKey.push("__search__", searchConfig.queryParam, activeSearchQuery.value);
     }
@@ -221,10 +234,11 @@ function useList({
     return baseQueryKey;
   });
 
+  const listReadEnabled = computed(() => canView.value && routeSyncHydrated.value);
   const list = useListCore({
     queryKey: listQueryKey,
     path: listPath,
-    enabled: operationScope.queryCanRun(canView),
+    enabled: operationScope.queryCanRun(listReadEnabled),
     client,
     transport,
     initialPageParam,
@@ -236,7 +250,6 @@ function useList({
     requestRecoveryLabel,
     fallbackLoadError
   });
-  const routeSyncHydrated = ref(routeSyncConfig.enabled !== true);
   const routeSyncApplying = ref(false);
   const routeSyncManagedKeyHistory = ref([]);
   const routeSyncQueryParamBlacklist = computed(() => {
@@ -306,6 +319,7 @@ function useList({
     watch(
       () => operationScope.routeContext.route?.query || {},
       (routeQuery) => {
+        const initialHydration = routeSyncHydrated.value !== true;
         if (routeSyncConfig.hydrateFromRoute !== true || routeSyncApplying.value === true) {
           routeSyncHydrated.value = true;
           return;
@@ -324,7 +338,9 @@ function useList({
             if (routeSyncQueryParamBlacklistSet.value.has(binding.key)) {
               continue;
             }
-            const nextValue = parseRouteBindingValue(binding, routeQuerySource[binding.key]);
+            const nextValue = parseRouteBindingValue(binding, routeQuerySource[binding.key], {
+              initial: initialHydration
+            });
             const currentValue = typeof binding.get === "function" ? binding.get() : undefined;
             if (areQueryParamBindingValuesEqual(currentValue, nextValue)) {
               continue;
@@ -397,20 +413,16 @@ function useList({
 
     list.trimToFirstPage();
   });
-  watch(activeQueryParamsToken, (nextValue, previousValue) => {
-    if (nextValue === previousValue) {
-      return;
-    }
-
-    list.trimToFirstPage();
-  });
-  watch(activeRequestQueryParamsToken, (nextValue, previousValue) => {
-    if (nextValue === previousValue) {
-      return;
+  watch(
+    [
+      activeQueryParamsToken,
+      activeRequestQueryParamsToken,
+      activeRequestFieldsetsToken
+    ],
+    () => {
+      list.trimToFirstPage();
     }
-
-    list.trimToFirstPage();
-  });
+  );
   const filteredItems = computed(() => {
     const sourceItems = Array.isArray(list.items.value) ? list.items.value : [];
     if (searchConfig.enabled !== true || searchConfig.mode !== "local") {

package/src/client/composables/records/useView.js

@@ -31,6 +31,7 @@ function useView({
   model,
   mapLoadedToModel,
   requestQueryParams = null,
+  requestFieldsets = null,
   recordIdParam = "recordId",
   routeParams = null,
   routeRecordId = null,
@@ -95,6 +96,7 @@ function useView({
   });
   const requestQueryRuntime = createRequestQueryRuntime({
     requestQueryParams,
+    requestFieldsets,
     context: queryParamsContext,
     sourceQueryKey: baseQueryKey
   });

package/src/client/composables/support/listQueryParamSupport.js

@@ -137,7 +137,8 @@ function createWritableQueryParamBinding({
   source = {},
   rawKey = "",
   rawValue = null,
-  key = ""
+  key = "",
+  resolveRouteValue = null
 } = {}) {
   const valueSourceIsRef = isRef(rawValue);
   const read = valueSourceIsRef
@@ -160,12 +161,18 @@ function createWritableQueryParamBinding({
       ? resolveArrayQueryParamItemType(currentValue)
       : QUERY_PARAM_BINDING_TYPE_TEXT,
     get: read,
-    set: write
+    set: write,
+    resolveRouteValue
   };
 }
 
-function resolveQueryParamDescriptors(queryParams, context = {}) {
+function resolveQueryParamDescriptors(
+  queryParams,
+  context = {},
+  { routeValueResolvers = null } = {}
+) {
   const source = resolveQueryParamsInput(queryParams, context);
+  const resolvers = asPlainObject(unref(routeValueResolvers));
   const descriptorsByKey = new Map();
   const canWriteToSource = typeof queryParams !== "function";
 
@@ -189,7 +196,10 @@ function resolveQueryParamDescriptors(queryParams, context = {}) {
         source,
         rawKey,
         rawValue,
-        key
+        key,
+        resolveRouteValue: typeof resolvers[key] === "function"
+          ? resolvers[key]
+          : null
       });
     }
 
@@ -323,7 +333,11 @@ function parseRouteQueryItemValue(value, itemType = QUERY_PARAM_BINDING_TYPE_TEX
   return normalized || fallback;
 }
 
-function parseRouteBindingValue(binding, routeQueryValue) {
+function parseRouteBindingValue(binding, routeQueryValue, context = {}) {
+  if (typeof binding?.resolveRouteValue === "function") {
+    return binding.resolveRouteValue(routeQueryValue, context);
+  }
+
   const valueType = normalizeText(binding?.valueType).toLowerCase();
   if (valueType === QUERY_PARAM_BINDING_TYPE_BOOLEAN) {
     return parseRouteBooleanValue(routeQueryValue, false);

package/src/client/composables/support/requestQueryRuntimeSupport.js

@@ -1,4 +1,8 @@
 import { computed, unref } from "vue";
+import {
+  buildJsonApiFieldsetsToken,
+  normalizeJsonApiFieldsets
+} from "@jskit-ai/kernel/shared/support/jsonApiFieldsets";
 import {
   resolveQueryParamDescriptors,
   resolveActiveQueryParamEntries,
@@ -21,6 +25,13 @@ function resolveRequestQueryBaseKey(sourceQueryKey = null) {
   return [source];
 }
 
+function resolveRequestFieldsets(requestFieldsets = null, context = {}) {
+  const source = typeof requestFieldsets === "function"
+    ? requestFieldsets(context)
+    : unref(requestFieldsets);
+  return normalizeJsonApiFieldsets(source);
+}
+
 function appendRequestQueryValue(target = {}, key = "", values = []) {
   const normalizedKey = String(key || "").trim();
   const normalizedValues = (Array.isArray(values) ? values : [])
@@ -40,7 +51,7 @@ function appendRequestQueryValue(target = {}, key = "", values = []) {
   target[normalizedKey] = [...currentValues, ...normalizedValues];
 }
 
-function buildRequestQueryObject(entries = []) {
+function buildRequestQueryObject(entries = [], { fieldsets = null } = {}) {
   const sourceEntries = Array.isArray(entries) ? entries : [];
   const query = {};
 
@@ -48,11 +59,18 @@ function buildRequestQueryObject(entries = []) {
     appendRequestQueryValue(query, entry?.key, entry?.values);
   }
 
-  return Object.freeze(query);
+  const normalizedFieldsets = normalizeJsonApiFieldsets(fieldsets);
+  return Object.freeze({
+    ...query,
+    ...(Object.keys(normalizedFieldsets).length > 0
+      ? { fields: normalizedFieldsets }
+      : {})
+  });
 }
 
 function createRequestQueryRuntime({
   requestQueryParams = null,
+  requestFieldsets = null,
   context = null,
   sourceQueryKey = null
 } = {}) {
@@ -65,36 +83,59 @@ function createRequestQueryRuntime({
   const activeRequestQueryParamsToken = computed(() => {
     return buildQueryParamEntriesToken(activeRequestQueryParamEntries.value);
   });
+  const activeRequestFieldsets = computed(() => {
+    return resolveRequestFieldsets(
+      requestFieldsets,
+      resolveRequestQueryContext(context)
+    );
+  });
+  const activeRequestFieldsetsToken = computed(() => {
+    return buildJsonApiFieldsetsToken(activeRequestFieldsets.value);
+  });
+  const queryKeyParts = computed(() => {
+    const parts = [];
+    if (activeRequestQueryParamsToken.value) {
+      parts.push("__request_query__", activeRequestQueryParamsToken.value);
+    }
+    if (activeRequestFieldsetsToken.value) {
+      parts.push("__request_fieldsets__", activeRequestFieldsetsToken.value);
+    }
+    return Object.freeze(parts);
+  });
   const queryKey = computed(() => {
-    if (!activeRequestQueryParamsToken.value) {
+    if (queryKeyParts.value.length < 1) {
       return unref(sourceQueryKey);
     }
 
-    const next = resolveRequestQueryBaseKey(sourceQueryKey);
-    next.push("__request_query__", activeRequestQueryParamsToken.value);
-    return next;
+    return [
+      ...resolveRequestQueryBaseKey(sourceQueryKey),
+      ...queryKeyParts.value
+    ];
   });
   const requestQuery = computed(() => {
-    if (activeRequestQueryParamEntries.value.length < 1) {
+    const query = buildRequestQueryObject(activeRequestQueryParamEntries.value, {
+      fieldsets: activeRequestFieldsets.value
+    });
+    if (Object.keys(query).length < 1) {
       return null;
     }
 
-    return buildRequestQueryObject(activeRequestQueryParamEntries.value);
+    return query;
   });
 
   return Object.freeze({
     requestQueryParamDescriptors,
     activeRequestQueryParamEntries,
     activeRequestQueryParamsToken,
+    activeRequestFieldsets,
+    activeRequestFieldsetsToken,
+    queryKeyParts,
     queryKey,
     requestQuery
   });
 }
 
 export {
-  appendRequestQueryValue,
   buildRequestQueryObject,
-  createRequestQueryRuntime,
-  resolveRequestQueryBaseKey,
-  resolveRequestQueryContext
+  createRequestQueryRuntime
 };

package/src/client/composables/useCrudListFilters.js

@@ -2,6 +2,7 @@ import { computed, reactive } from "vue";
 import { normalizeText } from "@jskit-ai/kernel/shared/support/normalize";
 import {
   defineCrudListFilters,
+  createCrudListFilterEmptyValue,
   createCrudListFilterInitialValue,
   isCrudListFilterMultiValue,
   isCrudListFilterStructuredValue,
@@ -10,7 +11,9 @@ import {
   listCrudListFilterChipValues,
   formatCrudListFilterDefaultChipLabel,
   formatCrudListFilterQueryValue,
+  parseCrudListFilterQueryValue,
   resolveCrudListFilterOptionLabel,
+  INVALID_CRUD_LIST_FILTER_QUERY_VALUE,
   CRUD_LIST_FILTER_TYPE_FLAG
 } from "@jskit-ai/kernel/shared/support/crudListFilters";
 import { formatCrudListDateFilterChipLabel } from "../support/crudListDateFilterSupport.js";
@@ -107,7 +110,7 @@ function assignFilterValue(values, filter = {}, rawValue) {
 }
 
 function resetFilterValue(values, filter = {}) {
-  assignFilterValue(values, filter, createCrudListFilterInitialValue(filter));
+  assignFilterValue(values, filter, createCrudListFilterEmptyValue(filter));
 }
 
 function applyPresetFilterValue(values, filter = {}, rawValue) {
@@ -134,6 +137,28 @@ function createQueryParams(values, filterEntries = []) {
   return Object.freeze(queryParams);
 }
 
+function resolveFilterRouteValue(filter, routeValue, { initial = false } = {}) {
+  if (routeValue === undefined) {
+    return initial
+      ? createCrudListFilterInitialValue(filter)
+      : createCrudListFilterEmptyValue(filter);
+  }
+
+  const parsedValue = parseCrudListFilterQueryValue(filter, routeValue);
+  return parsedValue === INVALID_CRUD_LIST_FILTER_QUERY_VALUE
+    ? createCrudListFilterInitialValue(filter)
+    : parsedValue;
+}
+
+function createRouteQueryValueResolvers(filterEntries = []) {
+  return Object.freeze(Object.fromEntries(
+    filterEntries.map((filter) => [
+      filter.queryKey,
+      (routeValue, context) => resolveFilterRouteValue(filter, routeValue, context)
+    ])
+  ));
+}
+
 function resolveAtomicValueLabel(filter = {}, value = "", labelResolvers = {}) {
   const customResolver = labelResolvers[filter.key];
   if (typeof customResolver === "function") {
@@ -174,6 +199,7 @@ function useCrudListFilters(definitions = {}, { labelResolvers = {}, chipLabels
   }
 
   const queryParams = createQueryParams(values, filterEntries);
+  const routeQueryValueResolvers = createRouteQueryValueResolvers(filterEntries);
 
   const activeChips = computed(() => {
     const chips = [];
@@ -296,6 +322,7 @@ function useCrudListFilters(definitions = {}, { labelResolvers = {}, chipLabels
     filters,
     values,
     queryParams,
+    routeQueryValueResolvers,
     options: Object.freeze(options),
     presets: normalizedPresets,
     activeChips,

package/src/client/composables/useCrudListScreen.js

@@ -118,6 +118,7 @@ function useCrudListScreen({
   syntheticRows = null,
   routeQueryBlacklist = Object.freeze(["include", "cursor", "limit"]),
   requestQueryParams = null,
+  requestFieldsets = null,
   readEnabled = true,
   requestRecoveryLabel = "Records",
   fallbackLoadError = "Unable to load records."
@@ -143,6 +144,7 @@ function useCrudListScreen({
       mode: "query"
     },
     queryParams: filterRuntime.queryParams,
+    routeQueryValueResolvers: filterRuntime.routeQueryValueResolvers,
     syncToRoute: {
       enabled: true,
       mode: "replace",
@@ -152,6 +154,7 @@ function useCrudListScreen({
     },
     placementSource: `ui-generator.${normalizedResourceNamespace}.list`,
     requestQueryParams,
+    requestFieldsets,
     readEnabled,
     requestRecoveryLabel,
     fallbackLoadError,

package/src/client/composables/useCrudViewScreen.js

@@ -13,6 +13,7 @@ function useCrudViewScreen({
   editUrlTemplate = "",
   recordChangedEvent = "",
   requestQueryParams = null,
+  requestFieldsets = null,
   readEnabled = true,
   queryKeyFactory = null,
   requestRecoveryLabel = "Record",
@@ -36,6 +37,7 @@ function useCrudViewScreen({
     includeRecordIdInQueryKey: true,
     queryKeyFactory: typeof queryKeyFactory === "function" ? queryKeyFactory : defaultQueryKeyFactory,
     requestQueryParams,
+    requestFieldsets,
     readEnabled,
     placementSource: `ui-generator.${normalizedResourceNamespace}.view`,
     requestRecoveryLabel,

package/test/listQueryParamSupport.test.js

@@ -151,6 +151,39 @@ test("parseRouteBindingValue handles boolean, number and array bindings", () =>
   );
 });
 
+test("route-aware query parameter bindings can distinguish initial hydration from later clearing", () => {
+  const currentness = ref("active");
+  const [binding] = resolveWritableQueryParamBindings(
+    resolveQueryParamDescriptors(
+      { currentness },
+      {},
+      {
+        routeValueResolvers: {
+          currentness(routeValue, { initial }) {
+            if (routeValue === undefined) {
+              return initial ? "active" : "";
+            }
+            return String(routeValue || "").trim() || "active";
+          }
+        }
+      }
+    )
+  );
+
+  assert.equal(
+    parseRouteBindingValue(binding, undefined, { initial: true }),
+    "active"
+  );
+  assert.equal(
+    parseRouteBindingValue(binding, "archived", { initial: true }),
+    "archived"
+  );
+  assert.equal(
+    parseRouteBindingValue(binding, undefined, { initial: false }),
+    ""
+  );
+});
+
 test("route sync key helpers preserve declared key history for cleanup", () => {
   const history = mergeManagedQueryParamKeyHistory(
     ["status"],

package/test/useAddEditRequestQueryParams.test.js

@@ -160,3 +160,31 @@ test("request query runtime preserves inactive scalar query keys", () => {
   assert.equal(runtime.queryKey.value, "products");
   assert.equal(runtime.requestQuery.value, null);
 });
+
+test("request query runtime carries typed fieldsets as a first-class query and cache-key dimension", () => {
+  const runtime = createRequestQueryRuntime({
+    requestQueryParams: {
+      include: "operator"
+    },
+    requestFieldsets: {
+      jobs: ["status", "id"],
+      contacts: ["displayName", "id"]
+    },
+    sourceQueryKey: ref(["jobs"])
+  });
+
+  assert.deepEqual(runtime.requestQuery.value, {
+    include: "operator",
+    fields: {
+      contacts: ["displayName", "id"],
+      jobs: ["id", "status"]
+    }
+  });
+  assert.deepEqual(runtime.queryKey.value, [
+    "jobs",
+    "__request_query__",
+    "include=operator",
+    "__request_fieldsets__",
+    '{"contacts":["displayName","id"],"jobs":["id","status"]}'
+  ]);
+});

package/test/useCrudListFilters.test.js

@@ -257,3 +257,37 @@ test("useCrudListFilters preserves scalar, complete, partial, and cleared date c
   assert.deepEqual(filters.values.arrivalDate, { from: "", to: "" });
   assert.equal(filters.hasActiveFilters.value, false);
 });
+
+test("useCrudListFilters applies declarative defaults once while clear remains an explicit empty state", async () => {
+  const { useCrudListFilters } = await import("@jskit-ai/users-web/client/composables/useCrudListFilters");
+
+  const filters = useCrudListFilters({
+    currentness: {
+      type: "enum",
+      label: "Currentness",
+      options: [
+        { value: "active", label: "Active" },
+        { value: "archived", label: "Archived" }
+      ],
+      defaultValue: "active"
+    },
+    onlyStaff: {
+      type: "flag",
+      label: "Staff",
+      defaultValue: true
+    }
+  });
+
+  assert.equal(filters.values.currentness, "active");
+  assert.equal(filters.values.onlyStaff, true);
+  assert.equal(filters.queryParams.currentness.value, "active");
+  assert.equal(filters.queryParams.onlyStaff.value, true);
+
+  filters.clearFilter("currentness");
+  filters.clearFilter("onlyStaff");
+
+  assert.equal(filters.values.currentness, "");
+  assert.equal(filters.values.onlyStaff, false);
+  assert.equal(filters.queryParams.currentness.value, "");
+  assert.equal(filters.queryParams.onlyStaff.value, false);
+});

package/test/useListRouteInitialization.test.js

@@ -0,0 +1,337 @@
+import assert from "node:assert/strict";
+import test from "node:test";
+import { QueryClient, VueQueryPlugin } from "@tanstack/vue-query";
+import {
+  computed,
+  createRenderer,
+  h,
+  unref
+} from "vue";
+import {
+  createMemoryHistory,
+  createRouter,
+  useRoute
+} from "vue-router";
+
+import { useList } from "../src/client/composables/records/useList.js";
+import { useCrudListFilters } from "../src/client/composables/useCrudListFilters.js";
+
+const CURRENTNESS_FILTERS = Object.freeze({
+  currentness: Object.freeze({
+    type: "enum",
+    defaultValue: "active",
+    options: Object.freeze([
+      Object.freeze({
+        label: "Active",
+        value: "active"
+      }),
+      Object.freeze({
+        label: "Archived",
+        value: "archived"
+      })
+    ])
+  })
+});
+
+async function waitFor(check, message = "Expected condition was not met.") {
+  for (let attempt = 0; attempt < 100; attempt += 1) {
+    if (check()) {
+      return;
+    }
+    await new Promise((resolve) => setTimeout(resolve, 0));
+  }
+
+  assert.fail(message);
+}
+
+function createTestRenderer() {
+  function insert(child, parent, anchor = null) {
+    const siblings = parent.children || (parent.children = []);
+    const index = anchor ? siblings.indexOf(anchor) : -1;
+    if (index < 0) {
+      siblings.push(child);
+    } else {
+      siblings.splice(index, 0, child);
+    }
+    child.parent = parent;
+  }
+
+  function remove(child) {
+    const parent = child?.parent;
+    const index = parent?.children?.indexOf(child) ?? -1;
+    if (index >= 0) {
+      parent.children.splice(index, 1);
+    }
+    child.parent = null;
+  }
+
+  return createRenderer({
+    patchProp(element, key, _previousValue, nextValue) {
+      element.properties[key] = nextValue;
+    },
+    insert,
+    remove,
+    createElement(type) {
+      return {
+        type,
+        properties: {},
+        children: [],
+        parent: null
+      };
+    },
+    createText(text) {
+      return {
+        type: "text",
+        text,
+        parent: null
+      };
+    },
+    createComment(text) {
+      return {
+        type: "comment",
+        text,
+        parent: null
+      };
+    },
+    setText(node, text) {
+      node.text = text;
+    },
+    setElementText(element, text) {
+      element.children = [{
+        type: "text",
+        text,
+        parent: element
+      }];
+    },
+    parentNode(node) {
+      return node?.parent || null;
+    },
+    nextSibling(node) {
+      const parent = node?.parent;
+      const index = parent?.children?.indexOf(node) ?? -1;
+      return index >= 0 ? parent.children[index + 1] || null : null;
+    },
+    querySelector() {
+      return null;
+    },
+    setScopeId() {},
+    cloneNode(node) {
+      return {
+        ...node,
+        properties: {
+          ...node.properties
+        },
+        children: [...(node.children || [])],
+        parent: null
+      };
+    },
+    insertStaticContent(content, parent, anchor) {
+      const node = {
+        type: "static",
+        text: content,
+        parent: null
+      };
+      insert(node, parent, anchor);
+      return [node, node];
+    }
+  });
+}
+
+function createListTestAdapter() {
+  return Object.freeze({
+    useOperationScope() {
+      const route = useRoute();
+
+      return Object.freeze({
+        routeContext: Object.freeze({
+          route,
+          currentSurfaceId: computed(() => "admin")
+        }),
+        scopeParamValue: computed(() => ""),
+        normalizedOwnershipFilter: "none",
+        apiPath: computed(() => "/contacts"),
+        queryKey: computed(() => ["contacts"]),
+        queryCanRun(gate = true) {
+          return computed(() => Boolean(unref(gate)));
+        },
+        permissionGate() {
+          return computed(() => true);
+        },
+        loadError(error = "") {
+          return computed(() => String(unref(error) || ""));
+        },
+        isLoading(loading = false) {
+          return computed(() => Boolean(unref(loading)));
+        }
+      });
+    }
+  });
+}
+
+async function mountRouteSynchronizedList(initialLocation) {
+  const calls = [];
+  const client = {
+    async request(path, options) {
+      calls.push({
+        path,
+        options
+      });
+      return {
+        items: [],
+        nextCursor: null
+      };
+    }
+  };
+  const queryClient = new QueryClient({
+    defaultOptions: {
+      queries: {
+        retry: false
+      }
+    }
+  });
+  const router = createRouter({
+    history: createMemoryHistory(),
+    routes: [{
+      path: "/contacts",
+      component: {
+        render() {
+          return h("div");
+        }
+      }
+    }]
+  });
+  const renderer = createTestRenderer();
+  let filterRuntime = null;
+  const app = renderer.createApp({
+    setup() {
+      filterRuntime = useCrudListFilters(CURRENTNESS_FILTERS);
+      useList({
+        adapter: createListTestAdapter(),
+        client,
+        queryKeyFactory: () => ["contacts"],
+        queryParams: filterRuntime.queryParams,
+        routeQueryValueResolvers: filterRuntime.routeQueryValueResolvers,
+        syncToRoute: {
+          enabled: true,
+          search: false,
+          queryParams: true
+        }
+      });
+
+      return () => h("div");
+    }
+  });
+  app.use(router);
+  app.use(VueQueryPlugin, {
+    queryClient
+  });
+
+  await router.push(initialLocation);
+  await router.isReady();
+  app.mount({
+    type: "root",
+    children: []
+  });
+  await waitFor(
+    () => calls.length > 0,
+    `Expected a list request for ${JSON.stringify(initialLocation)}.`
+  );
+  await new Promise((resolve) => setImmediate(resolve));
+
+  return {
+    app,
+    calls,
+    filterRuntime,
+    queryClient,
+    router
+  };
+}
+
+test("route-synchronized lists make one initial request with the hydrated route filter", async () => {
+  const runtime = await mountRouteSynchronizedList({
+    path: "/contacts",
+    query: {
+      currentness: "archived"
+    }
+  });
+
+  assert.equal(runtime.calls.length, 1);
+  assert.deepEqual(runtime.calls[0], {
+    path: "/contacts",
+    options: {
+      method: "GET",
+      query: {
+        currentness: "archived",
+        limit: 20
+      }
+    }
+  });
+  runtime.app.unmount();
+  runtime.queryClient.clear();
+});
+
+test("route-synchronized lists make one initial request with a declarative default", async () => {
+  const runtime = await mountRouteSynchronizedList("/contacts");
+
+  assert.equal(runtime.calls.length, 1);
+  assert.equal(runtime.calls[0].options.query.currentness, "active");
+  runtime.app.unmount();
+  runtime.queryClient.clear();
+});
+
+test("invalid initial route filters fall back before the first list request", async () => {
+  const runtime = await mountRouteSynchronizedList({
+    path: "/contacts",
+    query: {
+      currentness: "not-a-valid-option"
+    }
+  });
+
+  assert.equal(runtime.calls.length, 1);
+  assert.equal(runtime.calls[0].options.query.currentness, "active");
+  runtime.app.unmount();
+  runtime.queryClient.clear();
+});
+
+test("route navigation rehydrates filters and a later clear stays cleared", async () => {
+  const runtime = await mountRouteSynchronizedList({
+    path: "/contacts",
+    query: {
+      currentness: "archived"
+    }
+  });
+
+  await runtime.router.push({
+    path: "/contacts",
+    query: {
+      currentness: "active"
+    }
+  });
+  await waitFor(() => runtime.filterRuntime.values.currentness === "active");
+  await waitFor(() => runtime.calls.length === 2);
+
+  runtime.router.back();
+  await waitFor(() => runtime.router.currentRoute.value.query.currentness === "archived");
+  await waitFor(() => runtime.filterRuntime.values.currentness === "archived");
+  await waitFor(() => runtime.calls.length === 3);
+
+  runtime.router.forward();
+  await waitFor(() => runtime.router.currentRoute.value.query.currentness === "active");
+  await waitFor(() => runtime.filterRuntime.values.currentness === "active");
+  await waitFor(() => runtime.calls.length === 4);
+
+  runtime.filterRuntime.clearFilter("currentness");
+  await waitFor(() => !Object.hasOwn(runtime.router.currentRoute.value.query, "currentness"));
+  await waitFor(
+    () => runtime.calls.length >= 5,
+    `Expected one request after clearing the filter; received ${runtime.calls.length}.`
+  );
+
+  assert.equal(runtime.calls.length, 5, JSON.stringify(runtime.calls, null, 2));
+  assert.equal(runtime.filterRuntime.values.currentness, "");
+  assert.deepEqual(runtime.calls.at(-1).options.query, {
+    limit: 20
+  });
+  runtime.app.unmount();
+  runtime.queryClient.clear();
+});