@jskit-ai/users-web 0.1.59 → 0.1.61

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.61",
   kind: "runtime",
   description: "Users web module: account/profile UI plus shared users web widgets.",
   dependsOn: [
@@ -66,6 +66,14 @@ export default Object.freeze({
           subpath: "./client/composables/useCommand",
           summary: "Exports command operation composable."
         },
+        {
+          subpath: "./client/composables/useEndpointResource",
+          summary: "Exports low-level endpoint resource composable for custom client requests."
+        },
+        {
+          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."
@@ -78,6 +86,10 @@ export default Object.freeze({
           subpath: "./client/composables/usePaths",
           summary: "Exports surface route path resolver composable."
         },
+        {
+          subpath: "./client/lib/httpClient",
+          summary: "Exports the shared users-web HTTP client with credentials and CSRF behavior."
+        },
         {
           subpath: "./client/composables/useAccountSettingsRuntime",
           summary: "Exports account settings runtime composable for app-owned settings UI."
@@ -142,12 +154,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.45",
+        "@jskit-ai/realtime": "0.1.45",
+        "@jskit-ai/kernel": "0.1.46",
+        "@jskit-ai/shell-web": "0.1.45",
+        "@jskit-ai/uploads-image-web": "0.1.24",
+        "@jskit-ai/users-core": "0.1.56",
         vuetify: "^4.0.0"
       },
       dev: {}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jskit-ai/users-web",
-  "version": "0.1.59",
+  "version": "0.1.61",
   "type": "module",
   "scripts": {
     "test": "node --test"
@@ -13,6 +13,9 @@
     "./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/useEndpointResource": "./src/client/composables/runtime/useEndpointResource.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",
@@ -24,6 +27,7 @@
     "./client/composables/useAccountSettingsRuntime": "./src/client/composables/useAccountSettingsRuntime.js",
     "./client/composables/usePaths": "./src/client/composables/usePaths.js",
     "./client/composables/runtime/useUiFeedback": "./src/client/composables/runtime/useUiFeedback.js",
+    "./client/lib/httpClient": "./src/client/lib/httpClient.js",
     "./client/lib/bootstrap": "./src/client/lib/bootstrap.js",
     "./client/lib/permissions": "./src/client/lib/permissions.js",
     "./client/support/contractGuards": "./src/client/support/contractGuards.js"
@@ -31,12 +35,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.45",
+    "@jskit-ai/kernel": "0.1.46",
+    "@jskit-ai/realtime": "0.1.45",
+    "@jskit-ai/shell-web": "0.1.45",
+    "@jskit-ai/uploads-image-web": "0.1.24",
+    "@jskit-ai/users-core": "0.1.56",
     "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 };