@jskit-ai/users-web 0.1.59 → 0.1.60

package/package.descriptor.mjs

@@ -3,7 +3,7 @@ import { HOME_TOOLS_OUTLET } from "./src/shared/toolsOutletContracts.js";
 export default Object.freeze({
   packageVersion: 1,
   packageId: "@jskit-ai/users-web",
-  version: "0.1.59",
+  version: "0.1.60",
   kind: "runtime",
   description: "Users web module: account/profile UI plus shared users web widgets.",
   dependsOn: [
@@ -66,6 +66,10 @@ export default Object.freeze({
           subpath: "./client/composables/useCommand",
           summary: "Exports command operation composable."
         },
+        {
+          subpath: "./client/composables/useCrudListFilterLookups",
+          summary: "Exports lookup-backed CRUD list filter helper for remote autocomplete filters."
+        },
         {
           subpath: "./client/composables/useView",
           summary: "Exports read/view operation composable."
@@ -142,12 +146,12 @@ export default Object.freeze({
       runtime: {
         "@tanstack/vue-query": "5.92.12",
         "@mdi/js": "^7.4.47",
-        "@jskit-ai/http-runtime": "0.1.43",
-        "@jskit-ai/realtime": "0.1.43",
-        "@jskit-ai/kernel": "0.1.44",
-        "@jskit-ai/shell-web": "0.1.43",
-        "@jskit-ai/uploads-image-web": "0.1.22",
-        "@jskit-ai/users-core": "0.1.54",
+        "@jskit-ai/http-runtime": "0.1.44",
+        "@jskit-ai/realtime": "0.1.44",
+        "@jskit-ai/kernel": "0.1.45",
+        "@jskit-ai/shell-web": "0.1.44",
+        "@jskit-ai/uploads-image-web": "0.1.23",
+        "@jskit-ai/users-core": "0.1.55",
         vuetify: "^4.0.0"
       },
       dev: {}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jskit-ai/users-web",
-  "version": "0.1.59",
+  "version": "0.1.60",
   "type": "module",
   "scripts": {
     "test": "node --test"
@@ -13,6 +13,8 @@
     "./client/composables/useCommand": "./src/client/composables/useCommand.js",
     "./client/composables/useCrudAddEdit": "./src/client/composables/records/useCrudAddEdit.js",
     "./client/composables/crudLookupFieldRuntime": "./src/client/composables/crud/crudLookupFieldRuntime.js",
+    "./client/composables/useCrudListFilterLookups": "./src/client/composables/useCrudListFilterLookups.js",
+    "./client/composables/useCrudListFilters": "./src/client/composables/useCrudListFilters.js",
     "./client/composables/useList": "./src/client/composables/records/useList.js",
     "./client/composables/useCrudList": "./src/client/composables/records/useCrudList.js",
     "./client/composables/useCrudListParentTitle": "./src/client/composables/useCrudListParentTitle.js",
@@ -31,12 +33,12 @@
   "dependencies": {
     "@tanstack/vue-query": "5.92.12",
     "@mdi/js": "^7.4.47",
-    "@jskit-ai/http-runtime": "0.1.43",
-    "@jskit-ai/kernel": "0.1.44",
-    "@jskit-ai/realtime": "0.1.43",
-    "@jskit-ai/shell-web": "0.1.43",
-    "@jskit-ai/uploads-image-web": "0.1.22",
-    "@jskit-ai/users-core": "0.1.54",
+    "@jskit-ai/http-runtime": "0.1.44",
+    "@jskit-ai/kernel": "0.1.45",
+    "@jskit-ai/realtime": "0.1.44",
+    "@jskit-ai/shell-web": "0.1.44",
+    "@jskit-ai/uploads-image-web": "0.1.23",
+    "@jskit-ai/users-core": "0.1.55",
     "vuetify": "^4.0.0"
   }
 }

package/src/client/composables/crud/crudSchemaFormHelpers.js

@@ -48,6 +48,10 @@ function resolveFormFieldFormat(field = {}) {
   return String(field.format || "").trim().toLowerCase();
 }
 
+function isNullableFormField(field = {}) {
+  return field?.nullable === true;
+}
+
 function padDateTimePart(value) {
   return String(value).padStart(2, "0");
 }
@@ -132,7 +136,7 @@ function resolveFormFieldInitialValue(field = {}) {
 
   const fieldType = resolveFormFieldType(field);
   if (fieldType === "boolean") {
-    return false;
+    return isNullableFormField(field) ? null : false;
   }
 
   return "";
@@ -176,7 +180,9 @@ function buildCrudFormPayload(fields = [], model = {}) {
     const rawValue = sourceModel[fieldKey];
 
     if (fieldType === "boolean") {
-      payload[fieldKey] = Boolean(rawValue);
+      payload[fieldKey] = rawValue == null && isNullableFormField(field)
+        ? null
+        : Boolean(rawValue);
       continue;
     }
 
@@ -258,7 +264,9 @@ function applyCrudPayloadToForm(fields = [], model = {}, payload = {}) {
     const rawValue = sourcePayload[fieldKey];
 
     if (fieldType === "boolean") {
-      targetModel[fieldKey] = Boolean(rawValue);
+      targetModel[fieldKey] = rawValue == null && isNullableFormField(field)
+        ? null
+        : Boolean(rawValue);
       continue;
     }
 

package/src/client/composables/internal/crudListFilterLookupSupport.js

@@ -0,0 +1,161 @@
+import { normalizeText, normalizeUniqueTextList } from "@jskit-ai/kernel/shared/support/normalize";
+import { resolveLookupItemLabel } from "../crud/crudLookupFieldLabelSupport.js";
+import { asPlainObject } from "../support/scopeHelpers.js";
+
+function normalizeLookupQueryKeyPrefix(value = []) {
+  const source = Array.isArray(value) ? value : [];
+  return Object.freeze(
+    source
+      .map((entry) => normalizeText(entry))
+      .filter(Boolean)
+  );
+}
+
+function normalizeLookupLabelResolverMap(value = {}) {
+  const source = value && typeof value === "object" && !Array.isArray(value)
+    ? value
+    : {};
+  const normalized = {};
+
+  for (const [key, entry] of Object.entries(source)) {
+    const normalizedKey = normalizeText(key);
+    if (!normalizedKey || typeof entry !== "function") {
+      continue;
+    }
+
+    normalized[normalizedKey] = entry;
+  }
+
+  return Object.freeze(normalized);
+}
+
+function normalizeLookupRequestQueryParamsMap(value = {}) {
+  const source = value && typeof value === "object" && !Array.isArray(value)
+    ? value
+    : {};
+  const normalized = {};
+
+  for (const [key, entry] of Object.entries(source)) {
+    const normalizedKey = normalizeText(key);
+    if (!normalizedKey) {
+      continue;
+    }
+    if (entry == null) {
+      continue;
+    }
+    if (typeof entry === "function") {
+      normalized[normalizedKey] = entry;
+      continue;
+    }
+    if (typeof entry !== "object" || Array.isArray(entry)) {
+      continue;
+    }
+
+    normalized[normalizedKey] = asPlainObject(entry);
+  }
+
+  return Object.freeze(normalized);
+}
+
+function resolveLookupSelectedValues(filter = {}, rawValue = undefined) {
+  if (filter?.type === "recordIdMany") {
+    return normalizeUniqueTextList(rawValue, {
+      acceptSingle: true
+    });
+  }
+
+  const normalizedValue = normalizeText(rawValue);
+  return normalizedValue ? Object.freeze([normalizedValue]) : Object.freeze([]);
+}
+
+function createLookupOptionFromItem(item = {}, filter = {}, labelResolver = null) {
+  const sourceRecord = asPlainObject(item);
+  const valueKey = normalizeText(filter?.lookup?.valueKey) || "id";
+  const labelKey = normalizeText(filter?.lookup?.labelKey);
+  const value = normalizeText(sourceRecord[valueKey]);
+  if (!value) {
+    return null;
+  }
+
+  const customLabel = typeof labelResolver === "function"
+    ? normalizeText(labelResolver(sourceRecord, filter))
+    : "";
+  const fallbackLabel = resolveLookupItemLabel(sourceRecord, labelKey) || value;
+
+  return Object.freeze({
+    value,
+    label: customLabel || String(fallbackLabel || value),
+    record: sourceRecord
+  });
+}
+
+function createLookupOptionsFromItems(items = [], filter = {}, labelResolver = null) {
+  const optionMap = new Map();
+  for (const item of Array.isArray(items) ? items : []) {
+    const option = createLookupOptionFromItem(item, filter, labelResolver);
+    if (!option || optionMap.has(option.value)) {
+      continue;
+    }
+
+    optionMap.set(option.value, option);
+  }
+
+  return Object.freeze([...optionMap.values()]);
+}
+
+function mergeSelectedLookupOptions(options = [], selectedValues = [], cachedOptions = new Map()) {
+  const optionMap = new Map(
+    (Array.isArray(options) ? options : []).map((option) => [normalizeText(option?.value), option])
+  );
+  const normalizedCache = cachedOptions instanceof Map ? cachedOptions : new Map();
+
+  for (const value of Array.isArray(selectedValues) ? selectedValues : []) {
+    const normalizedValue = normalizeText(value);
+    if (!normalizedValue || optionMap.has(normalizedValue)) {
+      continue;
+    }
+
+    const cachedOption = normalizedCache.get(normalizedValue);
+    if (cachedOption) {
+      optionMap.set(normalizedValue, cachedOption);
+    }
+  }
+
+  return Object.freeze(
+    [...optionMap.values()].sort((left, right) => {
+      return String(left?.label || "").localeCompare(String(right?.label || ""));
+    })
+  );
+}
+
+function resolveLookupOptionLabel(options = [], cachedOptions = new Map(), value = "", fallback = "Option") {
+  const normalizedValue = normalizeText(value);
+  if (!normalizedValue) {
+    return normalizeText(fallback) || "Option";
+  }
+
+  const matchingOption = (Array.isArray(options) ? options : [])
+    .find((option) => normalizeText(option?.value) === normalizedValue);
+  if (matchingOption?.label) {
+    return String(matchingOption.label);
+  }
+
+  const normalizedCache = cachedOptions instanceof Map ? cachedOptions : new Map();
+  const cachedOption = normalizedCache.get(normalizedValue);
+  if (cachedOption?.label) {
+    return String(cachedOption.label);
+  }
+
+  const normalizedFallback = normalizeText(fallback) || "Option";
+  return `${normalizedFallback} ${normalizedValue}`;
+}
+
+export {
+  normalizeLookupQueryKeyPrefix,
+  normalizeLookupLabelResolverMap,
+  normalizeLookupRequestQueryParamsMap,
+  resolveLookupSelectedValues,
+  createLookupOptionsFromItems,
+  mergeSelectedLookupOptions,
+  resolveLookupOptionLabel
+};

package/src/client/composables/useCrudListFilterLookups.js

@@ -0,0 +1,141 @@
+import { computed, proxyRefs, ref, watch } from "vue";
+import { normalizeText } from "@jskit-ai/kernel/shared/support/normalize";
+import {
+  defineCrudListFilters,
+  CRUD_LIST_FILTER_TYPE_RECORD_ID,
+  CRUD_LIST_FILTER_TYPE_RECORD_ID_MANY
+} from "@jskit-ai/kernel/shared/support/crudListFilters";
+import { useList } from "./records/useList.js";
+import {
+  normalizeLookupQueryKeyPrefix,
+  normalizeLookupLabelResolverMap,
+  normalizeLookupRequestQueryParamsMap,
+  resolveLookupSelectedValues,
+  createLookupOptionsFromItems,
+  mergeSelectedLookupOptions,
+  resolveLookupOptionLabel
+} from "./internal/crudListFilterLookupSupport.js";
+
+function useCrudListFilterLookups(
+  definitions = {},
+  {
+    values = {},
+    adapter = null,
+    recordIdParam = "recordId",
+    queryKeyPrefix = [],
+    placementSourcePrefix = "",
+    requestQueryParams = {},
+    labelResolvers = {}
+  } = {}
+) {
+  const filters = defineCrudListFilters(definitions);
+  const filterEntries = Object.values(filters);
+  const normalizedQueryKeyPrefix = normalizeLookupQueryKeyPrefix(queryKeyPrefix);
+  const normalizedPlacementSourcePrefix = normalizeText(placementSourcePrefix);
+  const normalizedLabelResolvers = normalizeLookupLabelResolverMap(labelResolvers);
+  const normalizedRequestQueryParams = normalizeLookupRequestQueryParamsMap(requestQueryParams);
+  const lookups = {};
+
+  for (const filter of filterEntries) {
+    if (
+      filter.type !== CRUD_LIST_FILTER_TYPE_RECORD_ID &&
+      filter.type !== CRUD_LIST_FILTER_TYPE_RECORD_ID_MANY
+    ) {
+      continue;
+    }
+    if (!filter.lookup?.apiSuffix) {
+      continue;
+    }
+
+    const runtime = useList({
+      adapter: adapter || undefined,
+      apiSuffix: filter.lookup.apiSuffix,
+      queryKeyFactory: (surfaceId = "", scopeParamValue = "") => [
+        ...normalizedQueryKeyPrefix,
+        filter.key,
+        String(surfaceId || ""),
+        String(scopeParamValue || "")
+      ],
+      search: {
+        enabled: true,
+        mode: "query"
+      },
+      ...(Object.hasOwn(normalizedRequestQueryParams, filter.key)
+        ? { requestQueryParams: normalizedRequestQueryParams[filter.key] }
+        : {}),
+      placementSource: normalizedPlacementSourcePrefix
+        ? `${normalizedPlacementSourcePrefix}.${filter.key}`
+        : `crud.list-filter.lookup.${filter.key}`,
+      fallbackLoadError: `Unable to load filter options (${filter.lookup.apiSuffix}).`,
+      recordIdParam,
+      recordIdSelector: (item = {}) => item[filter.lookup.valueKey || "id"],
+      viewUrlTemplate: "",
+      editUrlTemplate: ""
+    });
+
+    const cachedOptions = ref(new Map());
+    const selectedValues = computed(() => resolveLookupSelectedValues(filter, values?.[filter.key]));
+    const currentOptions = computed(() => createLookupOptionsFromItems(
+      Array.isArray(runtime.items) ? runtime.items : [],
+      filter,
+      normalizedLabelResolvers[filter.key]
+    ));
+    const options = computed(() => {
+      return mergeSelectedLookupOptions(
+        currentOptions.value,
+        selectedValues.value,
+        cachedOptions.value
+      );
+    });
+
+    watch(currentOptions, (nextOptions) => {
+      const nextCache = new Map(cachedOptions.value);
+      for (const option of nextOptions) {
+        nextCache.set(option.value, option);
+      }
+      cachedOptions.value = nextCache;
+    }, { immediate: true });
+
+    lookups[filter.key] = proxyRefs({
+      filter,
+      options,
+      searchQuery: computed(() => String(runtime.searchQuery || "")),
+      isLoading: computed(() => {
+        return Boolean(runtime.isInitialLoading || runtime.isFetching || runtime.isRefetching || runtime.isSearchDebouncing);
+      }),
+      resolveLabel(value, fallback = filter.label || "Option") {
+        return resolveLookupOptionLabel(options.value, cachedOptions.value, value, fallback);
+      },
+      setSearch(value = "") {
+        runtime.searchQuery = normalizeText(value);
+      }
+    });
+  }
+
+  function resolveLookup(filterKey = "") {
+    return lookups[normalizeText(filterKey)] || null;
+  }
+
+  return Object.freeze({
+    lookups: Object.freeze(lookups),
+    resolveLookup,
+    resolveLookupItems(filterKey = "") {
+      return resolveLookup(filterKey)?.options || [];
+    },
+    resolveLookupLoading(filterKey = "") {
+      return Boolean(resolveLookup(filterKey)?.isLoading);
+    },
+    resolveLookupSearch(filterKey = "") {
+      return String(resolveLookup(filterKey)?.searchQuery || "");
+    },
+    setLookupSearch(filterKey = "", value = "") {
+      resolveLookup(filterKey)?.setSearch(value);
+    },
+    resolveLookupLabel(filterKey = "", value = "", fallback = "Option") {
+      return resolveLookup(filterKey)?.resolveLabel(value, fallback)
+        || resolveLookupOptionLabel([], new Map(), value, fallback);
+    }
+  });
+}
+
+export { useCrudListFilterLookups };

package/src/client/composables/useCrudListFilters.js

@@ -0,0 +1,503 @@
+import { computed, reactive, toRef } from "vue";
+import { normalizeText, normalizeUniqueTextList } from "@jskit-ai/kernel/shared/support/normalize";
+import {
+  defineCrudListFilters,
+  resolveCrudListFilterOptionLabel,
+  CRUD_LIST_FILTER_TYPE_FLAG,
+  CRUD_LIST_FILTER_TYPE_ENUM,
+  CRUD_LIST_FILTER_TYPE_ENUM_MANY,
+  CRUD_LIST_FILTER_TYPE_RECORD_ID,
+  CRUD_LIST_FILTER_TYPE_RECORD_ID_MANY,
+  CRUD_LIST_FILTER_TYPE_DATE,
+  CRUD_LIST_FILTER_TYPE_DATE_RANGE,
+  CRUD_LIST_FILTER_TYPE_NUMBER_RANGE,
+  CRUD_LIST_FILTER_TYPE_PRESENCE
+} from "@jskit-ai/kernel/shared/support/crudListFilters";
+
+function normalizeFunctionMap(value = {}) {
+  const source = value && typeof value === "object" && !Array.isArray(value)
+    ? value
+    : {};
+  const normalized = {};
+
+  for (const [key, entry] of Object.entries(source)) {
+    const normalizedKey = normalizeText(key);
+    if (!normalizedKey || typeof entry !== "function") {
+      continue;
+    }
+
+    normalized[normalizedKey] = entry;
+  }
+
+  return Object.freeze(normalized);
+}
+
+function createInitialFilterValue(filter = {}) {
+  if (filter.type === CRUD_LIST_FILTER_TYPE_FLAG) {
+    return false;
+  }
+  if (filter.type === CRUD_LIST_FILTER_TYPE_ENUM_MANY || filter.type === CRUD_LIST_FILTER_TYPE_RECORD_ID_MANY) {
+    return [];
+  }
+  if (filter.type === CRUD_LIST_FILTER_TYPE_DATE_RANGE) {
+    return reactive({
+      from: "",
+      to: ""
+    });
+  }
+  if (filter.type === CRUD_LIST_FILTER_TYPE_NUMBER_RANGE) {
+    return reactive({
+      min: "",
+      max: ""
+    });
+  }
+
+  return "";
+}
+
+function normalizePresetEntries(presets = []) {
+  const source = Array.isArray(presets) ? presets : [];
+  const normalized = [];
+  const seenKeys = new Set();
+
+  for (const rawPreset of source) {
+    if (!rawPreset || typeof rawPreset !== "object" || Array.isArray(rawPreset)) {
+      continue;
+    }
+
+    const key = normalizeText(rawPreset.key);
+    const label = normalizeText(rawPreset.label);
+    if (!key || !label || seenKeys.has(key)) {
+      continue;
+    }
+    seenKeys.add(key);
+
+    const values = rawPreset.values && typeof rawPreset.values === "object" && !Array.isArray(rawPreset.values)
+      ? rawPreset.values
+      : {};
+    const resolveValues = typeof rawPreset.resolveValues === "function"
+      ? rawPreset.resolveValues
+      : null;
+
+    normalized.push(Object.freeze({
+      key,
+      label,
+      values,
+      resolveValues
+    }));
+  }
+
+  return Object.freeze(normalized);
+}
+
+function resolvePresetValues(preset = {}, { values = {}, filters = {} } = {}) {
+  const rawValues = typeof preset.resolveValues === "function"
+    ? preset.resolveValues({
+        values,
+        filters,
+        presetKey: preset.key,
+        preset
+      })
+    : preset.values;
+
+  return rawValues && typeof rawValues === "object" && !Array.isArray(rawValues)
+    ? rawValues
+    : {};
+}
+
+function normalizePresetFilterValue(filter = {}, rawValue) {
+  if (filter.type === CRUD_LIST_FILTER_TYPE_FLAG) {
+    return rawValue === true;
+  }
+
+  if (filter.type === CRUD_LIST_FILTER_TYPE_ENUM_MANY || filter.type === CRUD_LIST_FILTER_TYPE_RECORD_ID_MANY) {
+    const allowedValues = filter.type === CRUD_LIST_FILTER_TYPE_ENUM_MANY
+      ? new Set((filter.options || []).map((entry) => entry.value))
+      : null;
+    const normalizedList = normalizeUniqueTextList(rawValue, {
+      acceptSingle: true
+    });
+    if (!allowedValues) {
+      return normalizedList;
+    }
+
+    return normalizedList.filter((entry) => allowedValues.has(entry));
+  }
+
+  if (filter.type === CRUD_LIST_FILTER_TYPE_DATE_RANGE) {
+    const source = rawValue && typeof rawValue === "object" && !Array.isArray(rawValue)
+      ? rawValue
+      : {};
+    return {
+      from: normalizeText(source.from),
+      to: normalizeText(source.to)
+    };
+  }
+
+  if (filter.type === CRUD_LIST_FILTER_TYPE_NUMBER_RANGE) {
+    const source = rawValue && typeof rawValue === "object" && !Array.isArray(rawValue)
+      ? rawValue
+      : {};
+    return {
+      min: normalizeText(source.min),
+      max: normalizeText(source.max)
+    };
+  }
+
+  const normalized = normalizeText(rawValue);
+  if (filter.type === CRUD_LIST_FILTER_TYPE_ENUM || filter.type === CRUD_LIST_FILTER_TYPE_PRESENCE) {
+    const allowedValues = new Set((filter.options || []).map((entry) => entry.value));
+    return allowedValues.has(normalized) ? normalized : "";
+  }
+
+  return normalized;
+}
+
+function normalizeCurrentManyFilterValues(value) {
+  const source = Array.isArray(value) ? value : [value];
+  return source
+    .map((entry) => normalizeText(entry))
+    .filter(Boolean);
+}
+
+function matchArrayValues(currentValue = [], expectedValue = []) {
+  const currentList = Array.isArray(currentValue) ? [...currentValue].sort() : [];
+  const expectedList = Array.isArray(expectedValue) ? [...expectedValue].sort() : [];
+  if (currentList.length !== expectedList.length) {
+    return false;
+  }
+
+  return currentList.every((entry, index) => entry === expectedList[index]);
+}
+
+function matchesPresetFilterValue(filter = {}, currentValue, rawExpectedValue) {
+  const expectedValue = normalizePresetFilterValue(filter, rawExpectedValue);
+
+  if (filter.type === CRUD_LIST_FILTER_TYPE_ENUM_MANY || filter.type === CRUD_LIST_FILTER_TYPE_RECORD_ID_MANY) {
+    return matchArrayValues(normalizeCurrentManyFilterValues(currentValue), expectedValue);
+  }
+
+  const normalizedCurrentValue = normalizePresetFilterValue(filter, currentValue);
+
+  if (filter.type === CRUD_LIST_FILTER_TYPE_DATE_RANGE) {
+    return (
+      normalizeText(normalizedCurrentValue?.from) === normalizeText(expectedValue?.from) &&
+      normalizeText(normalizedCurrentValue?.to) === normalizeText(expectedValue?.to)
+    );
+  }
+
+  if (filter.type === CRUD_LIST_FILTER_TYPE_NUMBER_RANGE) {
+    return (
+      normalizeText(normalizedCurrentValue?.min) === normalizeText(expectedValue?.min) &&
+      normalizeText(normalizedCurrentValue?.max) === normalizeText(expectedValue?.max)
+    );
+  }
+
+  return normalizedCurrentValue === expectedValue;
+}
+
+function resetFilterValue(values, filter = {}) {
+  if (filter.type === CRUD_LIST_FILTER_TYPE_FLAG) {
+    values[filter.key] = false;
+    return;
+  }
+
+  if (filter.type === CRUD_LIST_FILTER_TYPE_ENUM_MANY || filter.type === CRUD_LIST_FILTER_TYPE_RECORD_ID_MANY) {
+    values[filter.key] = [];
+    return;
+  }
+
+  if (filter.type === CRUD_LIST_FILTER_TYPE_DATE_RANGE) {
+    values[filter.key].from = "";
+    values[filter.key].to = "";
+    return;
+  }
+
+  if (filter.type === CRUD_LIST_FILTER_TYPE_NUMBER_RANGE) {
+    values[filter.key].min = "";
+    values[filter.key].max = "";
+    return;
+  }
+
+  values[filter.key] = "";
+}
+
+function applyPresetFilterValue(values, filter = {}, rawValue) {
+  if (filter.type === CRUD_LIST_FILTER_TYPE_DATE_RANGE || filter.type === CRUD_LIST_FILTER_TYPE_NUMBER_RANGE) {
+    const nextValue = normalizePresetFilterValue(filter, rawValue);
+    Object.assign(values[filter.key], nextValue);
+    return;
+  }
+
+  values[filter.key] = normalizePresetFilterValue(filter, rawValue);
+}
+
+function createQueryParams(values, filterEntries = []) {
+  const queryParams = {};
+
+  for (const filter of filterEntries) {
+    if (filter.type === CRUD_LIST_FILTER_TYPE_DATE_RANGE) {
+      queryParams[filter.fromKey] = toRef(values[filter.key], "from");
+      queryParams[filter.toKey] = toRef(values[filter.key], "to");
+      continue;
+    }
+
+    if (filter.type === CRUD_LIST_FILTER_TYPE_NUMBER_RANGE) {
+      queryParams[filter.minKey] = toRef(values[filter.key], "min");
+      queryParams[filter.maxKey] = toRef(values[filter.key], "max");
+      continue;
+    }
+
+    queryParams[filter.queryKey] = toRef(values, filter.key);
+  }
+
+  return Object.freeze(queryParams);
+}
+
+function resolveAtomicValueLabel(filter = {}, value = "", labelResolvers = {}) {
+  const customResolver = labelResolvers[filter.key];
+  if (typeof customResolver === "function") {
+    const customLabel = normalizeText(customResolver(value, filter));
+    if (customLabel) {
+      return customLabel;
+    }
+  }
+
+  return resolveCrudListFilterOptionLabel(filter, value, {
+    fallback: String(value || "")
+  });
+}
+
+function defaultChipLabel(filter = {}, value, labelResolvers = {}) {
+  if (filter.type === CRUD_LIST_FILTER_TYPE_FLAG) {
+    return filter.label;
+  }
+
+  if (
+    filter.type === CRUD_LIST_FILTER_TYPE_ENUM ||
+    filter.type === CRUD_LIST_FILTER_TYPE_PRESENCE ||
+    filter.type === CRUD_LIST_FILTER_TYPE_RECORD_ID
+  ) {
+    return `${filter.label}: ${resolveAtomicValueLabel(filter, value, labelResolvers)}`;
+  }
+
+  if (filter.type === CRUD_LIST_FILTER_TYPE_DATE) {
+    return `${filter.label}: ${value}`;
+  }
+
+  if (filter.type === CRUD_LIST_FILTER_TYPE_DATE_RANGE) {
+    if (value?.from && value?.to) {
+      return `${filter.label}: ${value.from} to ${value.to}`;
+    }
+    if (value?.from) {
+      return `${filter.label}: from ${value.from}`;
+    }
+    return `${filter.label}: to ${value?.to || ""}`;
+  }
+
+  if (filter.type === CRUD_LIST_FILTER_TYPE_NUMBER_RANGE) {
+    if (value?.min && value?.max) {
+      return `${filter.label}: ${value.min} to ${value.max}`;
+    }
+    if (value?.min) {
+      return `${filter.label}: min ${value.min}`;
+    }
+    return `${filter.label}: max ${value?.max || ""}`;
+  }
+
+  return filter.label;
+}
+
+function useCrudListFilters(definitions = {}, { labelResolvers = {}, chipLabels = {}, presets = [] } = {}) {
+  const filters = defineCrudListFilters(definitions);
+  const filterEntries = Object.values(filters);
+  const normalizedLabelResolvers = normalizeFunctionMap(labelResolvers);
+  const normalizedChipLabels = normalizeFunctionMap(chipLabels);
+  const normalizedPresets = normalizePresetEntries(presets);
+  const values = reactive({});
+  const options = {};
+
+  for (const filter of filterEntries) {
+    values[filter.key] = createInitialFilterValue(filter);
+    if (Array.isArray(filter.options) && filter.options.length > 0) {
+      options[filter.key] = filter.options;
+    }
+  }
+
+  const queryParams = createQueryParams(values, filterEntries);
+
+  const activeChips = computed(() => {
+    const chips = [];
+
+    for (const filter of filterEntries) {
+      const customChipLabel = normalizedChipLabels[filter.key];
+      const rawValue = values[filter.key];
+
+      if (filter.type === CRUD_LIST_FILTER_TYPE_FLAG) {
+        if (rawValue === true) {
+          chips.push({
+            id: filter.key,
+            filterKey: filter.key,
+            label: normalizeText(customChipLabel?.(rawValue, filter, values))
+              || normalizeText(filter.chipLabel?.(rawValue, filter, values))
+              || defaultChipLabel(filter, rawValue, normalizedLabelResolvers)
+          });
+        }
+        continue;
+      }
+
+      if (filter.type === CRUD_LIST_FILTER_TYPE_ENUM_MANY || filter.type === CRUD_LIST_FILTER_TYPE_RECORD_ID_MANY) {
+        for (const value of Array.isArray(rawValue) ? rawValue : []) {
+          chips.push({
+            id: `${filter.key}:${value}`,
+            filterKey: filter.key,
+            value,
+            label: normalizeText(customChipLabel?.(value, filter, values))
+              || normalizeText(filter.chipLabel?.(value, filter, values))
+              || `${filter.label}: ${resolveAtomicValueLabel(filter, value, normalizedLabelResolvers)}`
+          });
+        }
+        continue;
+      }
+
+      if (filter.type === CRUD_LIST_FILTER_TYPE_DATE_RANGE || filter.type === CRUD_LIST_FILTER_TYPE_NUMBER_RANGE) {
+        const hasValue = Boolean(rawValue?.from || rawValue?.to || rawValue?.min || rawValue?.max);
+        if (!hasValue) {
+          continue;
+        }
+
+        chips.push({
+          id: filter.key,
+          filterKey: filter.key,
+          label: normalizeText(customChipLabel?.(rawValue, filter, values))
+            || normalizeText(filter.chipLabel?.(rawValue, filter, values))
+            || defaultChipLabel(filter, rawValue, normalizedLabelResolvers)
+        });
+        continue;
+      }
+
+      if (!normalizeText(rawValue)) {
+        continue;
+      }
+
+      chips.push({
+        id: filter.key,
+        filterKey: filter.key,
+        label: normalizeText(customChipLabel?.(rawValue, filter, values))
+          || normalizeText(filter.chipLabel?.(rawValue, filter, values))
+          || defaultChipLabel(filter, rawValue, normalizedLabelResolvers)
+      });
+    }
+
+    return chips;
+  });
+
+  const hasActiveFilters = computed(() => activeChips.value.length > 0);
+
+  function clearFilter(filterKey = "") {
+    const filter = filters[normalizeText(filterKey)];
+    if (!filter) {
+      return;
+    }
+
+    resetFilterValue(values, filter);
+  }
+
+  function clearFilters() {
+    for (const filter of filterEntries) {
+      resetFilterValue(values, filter);
+    }
+  }
+
+  function clearChip(chip = {}) {
+    const filter = filters[normalizeText(chip.filterKey)];
+    if (!filter) {
+      return;
+    }
+
+    if (filter.type === CRUD_LIST_FILTER_TYPE_ENUM_MANY || filter.type === CRUD_LIST_FILTER_TYPE_RECORD_ID_MANY) {
+      values[filter.key] = (Array.isArray(values[filter.key]) ? values[filter.key] : [])
+        .filter((entry) => entry !== chip.value);
+      return;
+    }
+
+    resetFilterValue(values, filter);
+  }
+
+  function toggle(filterKey = "") {
+    const filter = filters[normalizeText(filterKey)];
+    if (!filter || filter.type !== CRUD_LIST_FILTER_TYPE_FLAG) {
+      return;
+    }
+
+    values[filter.key] = !values[filter.key];
+  }
+
+  function applyPreset(presetKey = "", { mode = "replace" } = {}) {
+    const preset = normalizedPresets.find((entry) => entry.key === normalizeText(presetKey));
+    if (!preset) {
+      return;
+    }
+
+    const presetValues = resolvePresetValues(preset, {
+      values,
+      filters
+    });
+
+    if (mode !== "merge") {
+      clearFilters();
+    }
+
+    for (const filter of filterEntries) {
+      if (!Object.hasOwn(presetValues, filter.key)) {
+        continue;
+      }
+
+      applyPresetFilterValue(values, filter, presetValues[filter.key]);
+    }
+  }
+
+  function matchesPreset(presetKey = "") {
+    const preset = normalizedPresets.find((entry) => entry.key === normalizeText(presetKey));
+    if (!preset) {
+      return false;
+    }
+
+    const presetValues = resolvePresetValues(preset, {
+      values,
+      filters
+    });
+    let matchedFilter = false;
+
+    for (const filter of filterEntries) {
+      if (!Object.hasOwn(presetValues, filter.key)) {
+        continue;
+      }
+
+      matchedFilter = true;
+      if (!matchesPresetFilterValue(filter, values[filter.key], presetValues[filter.key])) {
+        return false;
+      }
+    }
+
+    return matchedFilter;
+  }
+
+  return Object.freeze({
+    filters,
+    values,
+    queryParams,
+    options: Object.freeze(options),
+    presets: normalizedPresets,
+    activeChips,
+    hasActiveFilters,
+    clearFilter,
+    clearFilters,
+    clearChip,
+    toggle,
+    applyPreset,
+    matchesPreset
+  });
+}
+
+export { useCrudListFilters };

package/test/exportsContract.test.js

@@ -20,6 +20,8 @@ test("users-web exports are explicit and aligned with production/template usage"
       "./client/composables/useList",
       "./client/composables/useView",
       "./client/composables/useCrudAddEdit",
+      "./client/composables/useCrudListFilterLookups",
+      "./client/composables/useCrudListFilters",
       "./client/composables/useCrudList",
       "./client/composables/useCrudView"
     ]

package/test/useCrudAddEdit.test.js

@@ -29,16 +29,30 @@ test("createCrudFormModel resolves defaults and supports explicit initial values
   const model = createCrudFormModel([
     { key: "name", type: "string" },
     { key: "active", type: "boolean" },
+    { key: "reviewed", type: "boolean", nullable: true },
     { key: "role", type: "string", initialValue: "member" }
   ]);
 
   assert.deepEqual(model, {
     name: "",
     active: false,
+    reviewed: null,
     role: "member"
   });
 });
 
+test("createCrudFormModel preserves explicit boolean defaults for nullable fields", () => {
+  const model = createCrudFormModel([
+    { key: "reviewed", type: "boolean", nullable: true, initialValue: false },
+    { key: "approved", type: "boolean", nullable: true, defaultValue: true }
+  ]);
+
+  assert.deepEqual(model, {
+    reviewed: false,
+    approved: true
+  });
+});
+
 test("buildCrudFormPayload normalizes booleans and numbers while skipping empty numeric values", () => {
   const payload = buildCrudFormPayload(
     [
@@ -100,12 +114,14 @@ test("buildCrudFormPayload normalizes time fields to canonical HH:MM", () => {
 test("buildCrudFormPayload serializes cleared nullable typed fields as null", () => {
   const payload = buildCrudFormPayload(
     [
+      { key: "reviewed", type: "boolean", nullable: true },
       { key: "serviceId", type: "integer", nullable: true },
       { key: "fromDate", type: "string", format: "date", nullable: true },
       { key: "scheduledAt", type: "string", format: "date-time", nullable: true },
       { key: "fromTime", type: "string", format: "time", nullable: true }
     ],
     {
+      reviewed: null,
       serviceId: null,
       fromDate: "",
       scheduledAt: "",
@@ -114,6 +130,7 @@ test("buildCrudFormPayload serializes cleared nullable typed fields as null", ()
   );
 
   assert.deepEqual(payload, {
+    reviewed: null,
     serviceId: null,
     fromDate: null,
     scheduledAt: null,
@@ -121,6 +138,40 @@ test("buildCrudFormPayload serializes cleared nullable typed fields as null", ()
   });
 });
 
+test("buildCrudFormPayload preserves nullable booleans while keeping non-nullable booleans binary", () => {
+  const fields = [
+    { key: "active", type: "boolean" },
+    { key: "reviewed", type: "boolean", nullable: true },
+    { key: "approved", type: "boolean", nullable: true }
+  ];
+
+  assert.deepEqual(
+    buildCrudFormPayload(fields, {
+      active: null,
+      reviewed: null,
+      approved: true
+    }),
+    {
+      active: false,
+      reviewed: null,
+      approved: true
+    }
+  );
+
+  assert.deepEqual(
+    buildCrudFormPayload(fields, {
+      active: 1,
+      reviewed: 0,
+      approved: false
+    }),
+    {
+      active: true,
+      reviewed: false,
+      approved: false
+    }
+  );
+});
+
 test("applyCrudPayloadToForm normalizes time fields for form inputs", () => {
   const fields = [
     { key: "fromTime", type: "string", format: "time" },
@@ -146,18 +197,21 @@ test("applyCrudPayloadToForm maps payload values into reactive form model", () =
   const form = reactive({
     name: "",
     active: false,
+    reviewed: null,
     age: ""
   });
   applyCrudPayloadToForm(
     [
       { key: "name", type: "string" },
       { key: "active", type: "boolean" },
+      { key: "reviewed", type: "boolean", nullable: true },
       { key: "age", type: "integer" }
     ],
     form,
     {
       name: "Grace",
       active: 1,
+      reviewed: null,
       age: 33
     }
   );
@@ -165,10 +219,36 @@ test("applyCrudPayloadToForm maps payload values into reactive form model", () =
   assert.deepEqual(form, {
     name: "Grace",
     active: true,
+    reviewed: null,
     age: "33"
   });
 });
 
+test("applyCrudPayloadToForm preserves nullable boolean payload values", () => {
+  const fields = [
+    { key: "active", type: "boolean" },
+    { key: "reviewed", type: "boolean", nullable: true },
+    { key: "approved", type: "boolean", nullable: true }
+  ];
+  const form = reactive({
+    active: false,
+    reviewed: null,
+    approved: null
+  });
+
+  applyCrudPayloadToForm(fields, form, {
+    active: null,
+    reviewed: null,
+    approved: true
+  });
+
+  assert.deepEqual(form, {
+    active: false,
+    reviewed: null,
+    approved: true
+  });
+});
+
 test("resolveCrudRouteBoundFieldValues maps route params for route-bound form fields", () => {
   const values = resolveCrudRouteBoundFieldValues(
     [

package/test/useCrudListFilterLookups.test.js

@@ -0,0 +1,114 @@
+import assert from "node:assert/strict";
+import test from "node:test";
+import {
+  resolveLookupSelectedValues,
+  createLookupOptionsFromItems,
+  mergeSelectedLookupOptions,
+  resolveLookupOptionLabel
+} from "../src/client/composables/internal/crudListFilterLookupSupport.js";
+
+const supplierFilter = Object.freeze({
+  key: "supplierContactId",
+  type: "recordIdMany",
+  label: "Supplier",
+  lookup: Object.freeze({
+    apiSuffix: "/contacts",
+    valueKey: "id",
+    labelKey: "name"
+  })
+});
+
+test("lookup filter support normalizes selected record ids for single and many filters", () => {
+  assert.deepEqual(
+    resolveLookupSelectedValues(supplierFilter, ["7", "4", "7", ""]),
+    ["7", "4"]
+  );
+
+  assert.deepEqual(
+    resolveLookupSelectedValues(
+      {
+        ...supplierFilter,
+        type: "recordId"
+      },
+      12
+    ),
+    ["12"]
+  );
+});
+
+test("lookup filter support builds option labels from custom resolvers and fallback lookup labels", () => {
+  const options = createLookupOptionsFromItems(
+    [
+      {
+        id: 7,
+        firstName: "Pollen",
+        lastName: "Partners"
+      },
+      {
+        id: 4,
+        name: "Harbor Storage"
+      }
+    ],
+    supplierFilter,
+    (item = {}) => {
+      if (item.id === 7) {
+        return `${item.firstName} ${item.lastName}`;
+      }
+
+      return "";
+    }
+  );
+
+  assert.deepEqual(options, [
+    {
+      value: "7",
+      label: "Pollen Partners",
+      record: {
+        id: 7,
+        firstName: "Pollen",
+        lastName: "Partners"
+      }
+    },
+    {
+      value: "4",
+      label: "Harbor Storage",
+      record: {
+        id: 4,
+        name: "Harbor Storage"
+      }
+    }
+  ]);
+});
+
+test("lookup filter support merges cached selected labels and resolves fallback labels", () => {
+  const currentOptions = [
+    {
+      value: "7",
+      label: "Pollen Partners",
+      record: {
+        id: 7,
+        name: "Pollen Partners"
+      }
+    }
+  ];
+  const cachedOptions = new Map([
+    ["12", {
+      value: "12",
+      label: "North Shed",
+      record: {
+        id: 12,
+        name: "North Shed"
+      }
+    }]
+  ]);
+
+  const mergedOptions = mergeSelectedLookupOptions(
+    currentOptions,
+    ["12", "7"],
+    cachedOptions
+  );
+
+  assert.deepEqual(mergedOptions.map((option) => option.value), ["12", "7"]);
+  assert.equal(resolveLookupOptionLabel(mergedOptions, cachedOptions, "12", "Storage"), "North Shed");
+  assert.equal(resolveLookupOptionLabel(mergedOptions, cachedOptions, "55", "Storage"), "Storage 55");
+});

package/test/useCrudListFilters.test.js

@@ -0,0 +1,182 @@
+import test from "node:test";
+import assert from "node:assert/strict";
+
+test("useCrudListFilters manages values, query params, chips, and presets", async () => {
+  const { useCrudListFilters } = await import("@jskit-ai/users-web/client/composables/useCrudListFilters");
+
+  const filters = useCrudListFilters(
+    {
+      onlyStaff: {
+        type: "flag",
+        label: "Staff"
+      },
+      status: {
+        type: "enumMany",
+        label: "Status",
+        options: [
+          { value: "active", label: "Active" },
+          { value: "archived", label: "Archived" }
+        ]
+      },
+      supplierContactId: {
+        type: "recordIdMany",
+        label: "Supplier"
+      },
+      arrivalDate: {
+        type: "dateRange",
+        label: "Arrival Date"
+      }
+    },
+    {
+      labelResolvers: {
+        supplierContactId(value) {
+          return value === "7" ? "Pollen Partners" : "";
+        }
+      },
+      presets: [
+        {
+          key: "needs-staff-review",
+          label: "Needs Staff Review",
+          values: {
+            onlyStaff: true,
+            status: ["archived"]
+          }
+        }
+      ]
+    }
+  );
+
+  filters.values.onlyStaff = true;
+  filters.values.status = ["active"];
+  filters.values.supplierContactId = ["7"];
+  filters.values.arrivalDate.from = "2026-04-01";
+
+  assert.equal(filters.queryParams.onlyStaff.value, true);
+  assert.deepEqual(filters.queryParams.status.value, ["active"]);
+  assert.equal(filters.queryParams.arrivalDateFrom.value, "2026-04-01");
+  assert.equal(filters.hasActiveFilters.value, true);
+  assert.deepEqual(
+    filters.activeChips.value.map((chip) => chip.label),
+    [
+      "Staff",
+      "Status: Active",
+      "Supplier: Pollen Partners",
+      "Arrival Date: from 2026-04-01"
+    ]
+  );
+
+  filters.clearChip(filters.activeChips.value.find((chip) => chip.filterKey === "supplierContactId"));
+  assert.deepEqual(filters.values.supplierContactId, []);
+
+  filters.applyPreset("needs-staff-review");
+  assert.equal(filters.values.onlyStaff, true);
+  assert.deepEqual(filters.values.status, ["archived"]);
+  assert.equal(filters.values.arrivalDate.from, "");
+
+  filters.clearFilters();
+  assert.equal(filters.values.onlyStaff, false);
+  assert.deepEqual(filters.values.status, []);
+  assert.equal(filters.hasActiveFilters.value, false);
+});
+
+test("useCrudListFilters supports dynamic presets and preset matching", async () => {
+  const { useCrudListFilters } = await import("@jskit-ai/users-web/client/composables/useCrudListFilters");
+  let today = "2026-04-18";
+
+  const filters = useCrudListFilters(
+    {
+      status: {
+        type: "enumMany",
+        label: "Status",
+        options: [
+          { value: "active", label: "Active" },
+          { value: "archived", label: "Archived" }
+        ]
+      },
+      arrivalDate: {
+        type: "dateRange",
+        label: "Arrival Date"
+      }
+    },
+    {
+      presets: [
+        {
+          key: "today",
+          label: "Today",
+          resolveValues() {
+            return {
+              arrivalDate: {
+                from: today,
+                to: today
+              }
+            };
+          }
+        },
+        {
+          key: "all-dates",
+          label: "All Dates",
+          values: {
+            arrivalDate: {
+              from: "",
+              to: ""
+            }
+          }
+        }
+      ]
+    }
+  );
+
+  filters.values.status = ["archived"];
+  filters.applyPreset("today", { mode: "merge" });
+
+  assert.equal(filters.values.arrivalDate.from, "2026-04-18");
+  assert.equal(filters.values.arrivalDate.to, "2026-04-18");
+  assert.deepEqual(filters.values.status, ["archived"]);
+  assert.equal(filters.matchesPreset("today"), true);
+  assert.equal(filters.matchesPreset("all-dates"), false);
+
+  today = "2026-04-19";
+  assert.equal(filters.matchesPreset("today"), false);
+
+  filters.applyPreset("all-dates", { mode: "merge" });
+  assert.equal(filters.values.arrivalDate.from, "");
+  assert.equal(filters.values.arrivalDate.to, "");
+  assert.deepEqual(filters.values.status, ["archived"]);
+  assert.equal(filters.matchesPreset("all-dates"), true);
+});
+
+test("useCrudListFilters preset matching rejects extra enumMany values present in current state", async () => {
+  const { useCrudListFilters } = await import("@jskit-ai/users-web/client/composables/useCrudListFilters");
+
+  const filters = useCrudListFilters(
+    {
+      status: {
+        type: "enumMany",
+        label: "Status",
+        options: [
+          { value: "active", label: "Active" },
+          { value: "archived", label: "Archived" }
+        ]
+      }
+    },
+    {
+      presets: [
+        {
+          key: "archived-only",
+          label: "Archived Only",
+          values: {
+            status: ["archived"]
+          }
+        }
+      ]
+    }
+  );
+
+  filters.values.status = ["archived", "bogus"];
+
+  assert.equal(filters.matchesPreset("archived-only"), false);
+  assert.deepEqual(
+    filters.activeChips.value.map((chip) => chip.label),
+    ["Status: Archived", "Status: bogus"]
+  );
+});