@jskit-ai/users-web 0.1.36 → 0.1.37

package/src/client/composables/crudSchemaFormHelpers.js

@@ -2,6 +2,24 @@ import { validateOperationSection } from "@jskit-ai/http-runtime/shared/validato
 import { asPlainObject } from "./scopeHelpers.js";
 import { toRouteParamValue } from "./routeTemplateHelpers.js";
 
+const EMPTY_FIELD_ERROR_LIST = Object.freeze([]);
+const fieldErrorListCache = new Map();
+
+function resolveStableFieldErrorList(fieldKey, message) {
+  if (!message) {
+    return EMPTY_FIELD_ERROR_LIST;
+  }
+
+  const cacheKey = `${fieldKey}::${message}`;
+  if (fieldErrorListCache.has(cacheKey)) {
+    return fieldErrorListCache.get(cacheKey);
+  }
+
+  const nextValue = Object.freeze([message]);
+  fieldErrorListCache.set(cacheKey, nextValue);
+  return nextValue;
+}
+
 function normalizeCrudFormFields(fields = []) {
   const normalizedFields = [];
   const seenKeys = new Set();
@@ -150,11 +168,12 @@ function resolveCrudFieldErrors(fieldErrors = {}, fieldKey = "") {
 
   const source = asPlainObject(fieldErrors);
   const message = String(source[key] || "").trim();
+
   if (!message) {
-    return [];
+    return resolveStableFieldErrorList(key, "");
   }
 
-  return [message];
+  return resolveStableFieldErrorList(key, message);
 }
 
 function parseCrudResourceOperationInput({
@@ -167,12 +186,13 @@ function parseCrudResourceOperationInput({
   const operations = asPlainObject(asPlainObject(resource).operations);
   const operation = asPlainObject(operations[normalizedOperationName]);
 
-  return validateOperationSection({
+  const parsed = validateOperationSection({
     operation,
     section: "bodyValidator",
     value: rawPayload,
     context
   });
+  return parsed;
 }
 
 export {

package/src/client/composables/listQueryParamSupport.js

@@ -0,0 +1,459 @@
+import { isRef, unref } from "vue";
+import {
+  normalizeBoolean,
+  normalizeText,
+  normalizeUniqueTextList
+} from "@jskit-ai/kernel/shared/support/normalize";
+import { asPlainObject } from "./scopeHelpers.js";
+
+const QUERY_PARAM_BINDING_TYPE_TEXT = "text";
+const QUERY_PARAM_BINDING_TYPE_BOOLEAN = "boolean";
+const QUERY_PARAM_BINDING_TYPE_NUMBER = "number";
+const QUERY_PARAM_BINDING_TYPE_ARRAY = "array";
+const QUERY_PARAM_BINDING_TYPE_DATE = "date";
+
+function normalizeListSyncToRouteConfig(syncToRoute = false, { defaultSearchParam = "q" } = {}) {
+  const source = syncToRoute === true ? {} : asPlainObject(syncToRoute);
+  const requested = syncToRoute === true || Object.keys(source).length > 0;
+  const queryParamBlacklist = Object.freeze(normalizeUniqueTextList(source.queryParamBlacklist));
+  if (!requested || source.enabled === false) {
+    return Object.freeze({
+      enabled: false,
+      mode: "replace",
+      syncSearch: false,
+      syncQueryParams: false,
+      hydrateFromRoute: false,
+      searchParam: normalizeText(defaultSearchParam) || "q",
+      queryParamBlacklist
+    });
+  }
+
+  const mode = normalizeText(source.mode).toLowerCase() === "push" ? "push" : "replace";
+  const searchParam = normalizeText(source.searchParam) || normalizeText(defaultSearchParam) || "q";
+
+  return Object.freeze({
+    enabled: true,
+    mode,
+    syncSearch: source.search !== false,
+    syncQueryParams: source.queryParams !== false,
+    hydrateFromRoute: source.hydrateFromRoute !== false,
+    searchParam,
+    queryParamBlacklist
+  });
+}
+
+function normalizeQueryParamKey(value) {
+  return normalizeText(value);
+}
+
+function normalizeQueryParamValues(value) {
+  const list = Array.isArray(value) ? value : [value];
+  const normalizedValues = [];
+
+  for (const entry of list) {
+    const resolvedEntry = unref(entry);
+    if (resolvedEntry == null) {
+      continue;
+    }
+
+    if (typeof resolvedEntry === "boolean") {
+      if (resolvedEntry) {
+        normalizedValues.push("1");
+      }
+      continue;
+    }
+
+    if (typeof resolvedEntry === "number") {
+      if (Number.isFinite(resolvedEntry)) {
+        normalizedValues.push(String(resolvedEntry));
+      }
+      continue;
+    }
+
+    if (resolvedEntry instanceof Date) {
+      if (!Number.isNaN(resolvedEntry.getTime())) {
+        normalizedValues.push(resolvedEntry.toISOString());
+      }
+      continue;
+    }
+
+    const normalizedText = normalizeText(resolvedEntry);
+    if (normalizedText) {
+      normalizedValues.push(normalizedText);
+    }
+  }
+
+  return normalizedValues;
+}
+
+function resolveQueryParamsInput(queryParams, context = {}) {
+  if (typeof queryParams === "function") {
+    return asPlainObject(queryParams(context));
+  }
+  return asPlainObject(unref(queryParams));
+}
+
+function resolveQueryParamBindingType(value) {
+  if (Array.isArray(value)) {
+    return QUERY_PARAM_BINDING_TYPE_ARRAY;
+  }
+  if (typeof value === "boolean") {
+    return QUERY_PARAM_BINDING_TYPE_BOOLEAN;
+  }
+  if (typeof value === "number") {
+    return QUERY_PARAM_BINDING_TYPE_NUMBER;
+  }
+  if (value instanceof Date) {
+    return QUERY_PARAM_BINDING_TYPE_DATE;
+  }
+
+  return QUERY_PARAM_BINDING_TYPE_TEXT;
+}
+
+function resolveArrayQueryParamItemType(values = []) {
+  const list = Array.isArray(values) ? values : [];
+  for (const entry of list) {
+    if (entry == null) {
+      continue;
+    }
+
+    if (typeof entry === "boolean") {
+      return QUERY_PARAM_BINDING_TYPE_BOOLEAN;
+    }
+    if (typeof entry === "number") {
+      return QUERY_PARAM_BINDING_TYPE_NUMBER;
+    }
+    if (entry instanceof Date) {
+      return QUERY_PARAM_BINDING_TYPE_DATE;
+    }
+
+    return QUERY_PARAM_BINDING_TYPE_TEXT;
+  }
+
+  return QUERY_PARAM_BINDING_TYPE_TEXT;
+}
+
+function createWritableQueryParamBinding({
+  source = {},
+  rawKey = "",
+  rawValue = null,
+  key = ""
+} = {}) {
+  const valueSourceIsRef = isRef(rawValue);
+  const read = valueSourceIsRef
+    ? () => rawValue.value
+    : () => source[rawKey];
+  const write = valueSourceIsRef
+    ? (nextValue) => {
+        rawValue.value = nextValue;
+      }
+    : (nextValue) => {
+        source[rawKey] = nextValue;
+      };
+
+  const currentValue = read();
+  const valueType = resolveQueryParamBindingType(currentValue);
+  return {
+    key,
+    valueType,
+    arrayItemType: valueType === QUERY_PARAM_BINDING_TYPE_ARRAY
+      ? resolveArrayQueryParamItemType(currentValue)
+      : QUERY_PARAM_BINDING_TYPE_TEXT,
+    get: read,
+    set: write
+  };
+}
+
+function resolveQueryParamDescriptors(queryParams, context = {}) {
+  const source = resolveQueryParamsInput(queryParams, context);
+  const descriptorsByKey = new Map();
+  const canWriteToSource = typeof queryParams !== "function";
+
+  for (const [rawKey, rawValue] of Object.entries(source)) {
+    const key = normalizeQueryParamKey(rawKey);
+    if (!key) {
+      continue;
+    }
+
+    const values = normalizeQueryParamValues(rawValue);
+    const current = descriptorsByKey.get(key) || {
+      key,
+      values: [],
+      binding: null
+    };
+    if (values.length > 0) {
+      current.values.push(...values);
+    }
+    if (!current.binding && canWriteToSource) {
+      current.binding = createWritableQueryParamBinding({
+        source,
+        rawKey,
+        rawValue,
+        key
+      });
+    }
+
+    descriptorsByKey.set(key, current);
+  }
+
+  return [...descriptorsByKey.values()].sort((left, right) => left.key.localeCompare(right.key));
+}
+
+function resolveActiveQueryParamEntries(descriptors = []) {
+  const source = Array.isArray(descriptors) ? descriptors : [];
+  return source
+    .filter((descriptor) => Array.isArray(descriptor?.values) && descriptor.values.length > 0)
+    .map((descriptor) => ({
+      key: descriptor.key,
+      values: [...descriptor.values]
+    }));
+}
+
+function resolveWritableQueryParamBindings(descriptors = []) {
+  const source = Array.isArray(descriptors) ? descriptors : [];
+  return source
+    .map((descriptor) => descriptor?.binding || null)
+    .filter(Boolean);
+}
+
+function buildQueryParamEntriesToken(entries = []) {
+  const normalizedEntries = Array.isArray(entries) ? entries : [];
+  if (normalizedEntries.length < 1) {
+    return "";
+  }
+
+  return normalizedEntries
+    .map((entry) => {
+      const key = normalizeQueryParamKey(entry?.key);
+      const values = Array.isArray(entry?.values)
+        ? entry.values.map((value) => normalizeText(value)).filter(Boolean)
+        : [];
+      if (!key || values.length < 1) {
+        return "";
+      }
+      return `${key}=${values.join(",")}`;
+    })
+    .filter(Boolean)
+    .join("&");
+}
+
+function firstRouteQueryValue(value) {
+  if (Array.isArray(value)) {
+    return value[0];
+  }
+  return value;
+}
+
+function normalizeRouteQueryValues(value) {
+  const values = Array.isArray(value) ? value : [value];
+  return values
+    .map((entry) => normalizeText(entry))
+    .filter(Boolean);
+}
+
+function parseRouteBooleanValue(value, fallback = false) {
+  if (value === undefined) {
+    return fallback;
+  }
+  if (value === null || value === "") {
+    return true;
+  }
+
+  try {
+    return normalizeBoolean(firstRouteQueryValue(value));
+  } catch {
+    return fallback;
+  }
+}
+
+function parseRouteNumberValue(value, fallback = null) {
+  if (value === undefined) {
+    return null;
+  }
+
+  const normalized = normalizeText(firstRouteQueryValue(value));
+  if (!normalized) {
+    return null;
+  }
+
+  const parsed = Number(normalized);
+  if (!Number.isFinite(parsed)) {
+    return fallback;
+  }
+
+  return parsed;
+}
+
+function parseRouteDateValue(value, fallback = null) {
+  if (value === undefined) {
+    return null;
+  }
+
+  const normalized = normalizeText(firstRouteQueryValue(value));
+  if (!normalized) {
+    return null;
+  }
+
+  const parsed = new Date(normalized);
+  if (Number.isNaN(parsed.getTime())) {
+    return fallback;
+  }
+
+  return parsed;
+}
+
+function parseRouteQueryItemValue(value, itemType = QUERY_PARAM_BINDING_TYPE_TEXT, fallback = null) {
+  if (itemType === QUERY_PARAM_BINDING_TYPE_BOOLEAN) {
+    try {
+      return normalizeBoolean(value);
+    } catch {
+      return fallback;
+    }
+  }
+  if (itemType === QUERY_PARAM_BINDING_TYPE_NUMBER) {
+    const numeric = Number(value);
+    return Number.isFinite(numeric) ? numeric : fallback;
+  }
+  if (itemType === QUERY_PARAM_BINDING_TYPE_DATE) {
+    const date = new Date(value);
+    return Number.isNaN(date.getTime()) ? fallback : date;
+  }
+
+  const normalized = normalizeText(value);
+  return normalized || fallback;
+}
+
+function parseRouteBindingValue(binding, routeQueryValue) {
+  const valueType = normalizeText(binding?.valueType).toLowerCase();
+  if (valueType === QUERY_PARAM_BINDING_TYPE_BOOLEAN) {
+    return parseRouteBooleanValue(routeQueryValue, false);
+  }
+  if (valueType === QUERY_PARAM_BINDING_TYPE_NUMBER) {
+    const fallback = typeof binding?.get === "function" ? binding.get() : null;
+    return parseRouteNumberValue(routeQueryValue, fallback);
+  }
+  if (valueType === QUERY_PARAM_BINDING_TYPE_DATE) {
+    const fallback = typeof binding?.get === "function" ? binding.get() : null;
+    return parseRouteDateValue(routeQueryValue, fallback);
+  }
+  if (valueType === QUERY_PARAM_BINDING_TYPE_ARRAY) {
+    const itemType = normalizeText(binding?.arrayItemType).toLowerCase() || QUERY_PARAM_BINDING_TYPE_TEXT;
+    return normalizeRouteQueryValues(routeQueryValue)
+      .map((value) => parseRouteQueryItemValue(value, itemType, null))
+      .filter((value) => value != null && !(typeof value === "string" && !value));
+  }
+
+  return normalizeText(firstRouteQueryValue(routeQueryValue));
+}
+
+function areQueryParamBindingItemsEqual(left, right) {
+  if (left === right) {
+    return true;
+  }
+  if (left instanceof Date && right instanceof Date) {
+    return left.getTime() === right.getTime();
+  }
+
+  return Object.is(left, right);
+}
+
+function areQueryParamBindingValuesEqual(left, right) {
+  if (left === right) {
+    return true;
+  }
+  if (left instanceof Date && right instanceof Date) {
+    return left.getTime() === right.getTime();
+  }
+  if (!Array.isArray(left) || !Array.isArray(right)) {
+    return Object.is(left, right);
+  }
+  if (left.length !== right.length) {
+    return false;
+  }
+
+  for (let index = 0; index < left.length; index += 1) {
+    if (!areQueryParamBindingItemsEqual(left[index], right[index])) {
+      return false;
+    }
+  }
+
+  return true;
+}
+
+function buildRouteQueryCompareToken(query = {}) {
+  const source = asPlainObject(query);
+  const keys = Object.keys(source).sort();
+  const parts = [];
+  for (const key of keys) {
+    const normalizedKey = normalizeQueryParamKey(key);
+    if (!normalizedKey) {
+      continue;
+    }
+
+    const normalizedValues = normalizeRouteQueryValues(source[key]);
+    if (normalizedValues.length < 1) {
+      continue;
+    }
+
+    parts.push(`${normalizedKey}=${normalizedValues.join(",")}`);
+  }
+
+  return parts.join("&");
+}
+
+function mergeManagedQueryParamKeyHistory(history = [], keys = []) {
+  const merged = new Set();
+  for (const key of Array.isArray(history) ? history : []) {
+    const normalized = normalizeQueryParamKey(key);
+    if (normalized) {
+      merged.add(normalized);
+    }
+  }
+  for (const key of Array.isArray(keys) ? keys : []) {
+    const normalized = normalizeQueryParamKey(key);
+    if (normalized) {
+      merged.add(normalized);
+    }
+  }
+
+  return [...merged].sort((left, right) => left.localeCompare(right));
+}
+
+function resolveRouteSyncManagedKeys({
+  searchEnabled = false,
+  searchParam = "q",
+  syncSearch = false,
+  syncQueryParams = false,
+  declaredKeys = [],
+  keyHistory = []
+} = {}) {
+  const managed = new Set();
+
+  if (syncSearch === true && searchEnabled === true) {
+    const normalizedSearchParam = normalizeQueryParamKey(searchParam);
+    if (normalizedSearchParam) {
+      managed.add(normalizedSearchParam);
+    }
+  }
+
+  if (syncQueryParams === true) {
+    for (const key of mergeManagedQueryParamKeyHistory(keyHistory, declaredKeys)) {
+      managed.add(key);
+    }
+  }
+
+  return [...managed].sort((left, right) => left.localeCompare(right));
+}
+
+export {
+  normalizeListSyncToRouteConfig,
+  resolveQueryParamDescriptors,
+  resolveActiveQueryParamEntries,
+  resolveWritableQueryParamBindings,
+  buildQueryParamEntriesToken,
+  parseRouteBindingValue,
+  areQueryParamBindingValuesEqual,
+  buildRouteQueryCompareToken,
+  mergeManagedQueryParamKeyHistory,
+  resolveRouteSyncManagedKeys
+};

package/src/client/composables/listUiRuntime.js

@@ -4,7 +4,7 @@ import {
   normalizeRouteParamName,
   toRouteParamValue,
   resolveRouteParamsSource,
-  resolveRoutePathnameSource,
+  resolveScopedRoutePathname,
   resolveRouteTemplateLocation
 } from "./routeTemplateHelpers.js";
 
@@ -23,6 +23,7 @@ function createListUiRuntime({
   recordIdParam = "recordId",
   recordIdSelector = null,
   routeParams = null,
+  routeParamNames = null,
   routePath = "",
   viewUrlTemplate = "",
   editUrlTemplate = ""
@@ -44,12 +45,23 @@ function createListUiRuntime({
       return "";
     }
 
+    const currentRouteParams = resolveRouteParamsSource(routeParams);
+    const sourceParams = {
+      ...currentRouteParams,
+      ...asPlainObject(extraParams)
+    };
+    const currentPathname = resolveScopedRoutePathname({
+      currentPathname: routePath,
+      params: currentRouteParams,
+      orderedParamNames: routeParamNames,
+      anchorParamName: normalizedRecordIdParam,
+      anchorParamValue: currentRouteParams[normalizedRecordIdParam],
+      anchorMode: "before"
+    });
+
     return resolveRouteTemplateLocation(normalizedTemplate, {
-      params: {
-        ...resolveRouteParamsSource(routeParams),
-        ...asPlainObject(extraParams)
-      },
-      currentPathname: resolveRoutePathnameSource(routePath)
+      params: sourceParams,
+      currentPathname
     });
   }
 

package/src/client/composables/routeTemplateHelpers.js

@@ -40,6 +40,17 @@ function resolveRouteParamsSource(source = null) {
   return asPlainObject(resolveRouteSourceValue(source));
 }
 
+function normalizeRouteParamNameList(value = []) {
+  const source = Array.isArray(value) ? value : [];
+  return source
+    .map((entry) => String(entry || "").trim())
+    .filter(Boolean);
+}
+
+function resolveRouteParamNamesSource(source = []) {
+  return normalizeRouteParamNameList(resolveRouteSourceValue(source));
+}
+
 function normalizeRoutePathname(value = "") {
   const rawPathname = String(value || "").trim();
   const sanitizedPathname = rawPathname.split(/[?#]/u, 1)[0] || "";
@@ -54,6 +65,115 @@ function resolveRoutePathnameSource(source = "") {
   return normalizeRoutePathname(resolveRouteSourceValue(source));
 }
 
+function segmentMatchesParamValue(segment = "", paramValue = "") {
+  const normalizedSegment = String(segment || "").trim();
+  const normalizedParamValue = toRouteParamValue(paramValue);
+  if (!normalizedSegment || !normalizedParamValue) {
+    return false;
+  }
+
+  const encodedParamValue = encodeURIComponent(normalizedParamValue);
+  if (normalizedSegment === encodedParamValue) {
+    return true;
+  }
+
+  try {
+    return decodeURIComponent(normalizedSegment) === normalizedParamValue;
+  } catch {
+    return false;
+  }
+}
+
+function findRouteParamSegmentIndex(segments = [], paramValue = "", fromIndex = 0) {
+  const source = Array.isArray(segments) ? segments : [];
+  const cursor = Number.isInteger(fromIndex) && fromIndex > 0 ? fromIndex : 0;
+  for (let index = cursor; index < source.length; index += 1) {
+    if (segmentMatchesParamValue(source[index], paramValue)) {
+      return index;
+    }
+  }
+  return -1;
+}
+
+function normalizePathPrefix(segments = [], endIndex = -1) {
+  const source = Array.isArray(segments) ? segments : [];
+  if (!Number.isInteger(endIndex) || endIndex < 0) {
+    return "/";
+  }
+  return `/${source.slice(0, endIndex + 1).join("/")}`;
+}
+
+function resolveAnchorEndIndex(segmentIndex = -1, totalSegments = 0, anchorMode = "at") {
+  const normalizedSegmentIndex = Number.isInteger(segmentIndex) ? segmentIndex : -1;
+  if (normalizedSegmentIndex < 0) {
+    return -1;
+  }
+
+  const normalizedTotalSegments = Number.isInteger(totalSegments) && totalSegments > 0 ? totalSegments : 0;
+  const normalizedMode = String(anchorMode || "at").trim().toLowerCase();
+  if (normalizedMode === "before") {
+    return normalizedSegmentIndex - 1;
+  }
+  if (normalizedMode === "after") {
+    return normalizedTotalSegments > 0
+      ? Math.min(normalizedSegmentIndex + 1, normalizedTotalSegments - 1)
+      : normalizedSegmentIndex + 1;
+  }
+
+  return normalizedSegmentIndex;
+}
+
+function resolveScopedRoutePathname({
+  currentPathname = "/",
+  params = {},
+  orderedParamNames = [],
+  anchorParamName = "",
+  anchorParamValue = "",
+  anchorMode = "at"
+} = {}) {
+  const normalizedCurrentPathname = resolveRoutePathnameSource(currentPathname);
+  const normalizedAnchorParamName = String(anchorParamName || "").trim();
+  if (!normalizedAnchorParamName) {
+    return normalizedCurrentPathname;
+  }
+
+  const sourceParams = asPlainObject(params);
+  const segments = normalizedCurrentPathname.split("/").filter(Boolean);
+  if (segments.length < 1) {
+    return normalizedCurrentPathname;
+  }
+
+  const paramNames = resolveRouteParamNamesSource(orderedParamNames);
+  let cursor = 0;
+  for (const paramName of paramNames) {
+    const segmentIndex = findRouteParamSegmentIndex(segments, sourceParams[paramName], cursor);
+    if (segmentIndex < 0) {
+      continue;
+    }
+
+    if (paramName === normalizedAnchorParamName) {
+      const endIndex = resolveAnchorEndIndex(segmentIndex, segments.length, anchorMode);
+      return normalizePathPrefix(segments, endIndex);
+    }
+
+    cursor = segmentIndex + 1;
+  }
+
+  const fallbackAnchorValue = toRouteParamValue(anchorParamValue) ||
+    toRouteParamValue(sourceParams[normalizedAnchorParamName]);
+  if (!fallbackAnchorValue) {
+    return normalizedCurrentPathname;
+  }
+
+  const fallbackSegmentIndex = findRouteParamSegmentIndex(segments, fallbackAnchorValue, 0);
+  if (fallbackSegmentIndex < 0) {
+    return normalizedCurrentPathname;
+  }
+
+  const fallbackEndIndex = resolveAnchorEndIndex(fallbackSegmentIndex, segments.length, anchorMode);
+  return normalizePathPrefix(segments, fallbackEndIndex);
+}
+
 function resolveRouteTemplatePath(routeTemplate = "", params = {}) {
   const normalizedTemplate = String(routeTemplate || "").trim();
   if (!normalizedTemplate) {
@@ -155,7 +275,9 @@ export {
   normalizeRouteParamName,
   toRouteParamValue,
   resolveRouteParamsSource,
+  resolveRouteParamNamesSource,
   resolveRoutePathnameSource,
+  resolveScopedRoutePathname,
   resolveRouteTemplatePath,
   resolveRouteTemplateLocation,
   extractRouteParamNames,