@jskit-ai/http-web 0.1.1

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/internal/crudListParentTitleSupport.js

@@ -0,0 +1,171 @@
+import {
+  normalizeCrudLookupContainerKey,
+  resolveCrudLookupApiPathFromNamespace,
+  resolveCrudLookupFieldKeyFromRouteParam
+} from "@jskit-ai/resource-crud-core/shared/crudLookup";
+import { buildCrudFieldContractMap } from "@jskit-ai/resource-crud-core/shared/crudFieldContract";
+import { normalizeText } from "@jskit-ai/kernel/shared/support/normalize";
+import { resolveLookupFieldDisplayValue, resolveRecordTitle } from "../crud/crudLookupFieldLabelSupport.js";
+import { resolveRouteParamNamesInOrder, toRouteParamValue } from "../support/routeTemplateHelpers.js";
+
+function singularizeLabel(value = "") {
+  const normalizedValue = normalizeText(value);
+  if (!normalizedValue) {
+    return "";
+  }
+  if (normalizedValue.endsWith("ies")) {
+    return `${normalizedValue.slice(0, -3)}y`;
+  }
+  if (normalizedValue.endsWith("s") && !normalizedValue.endsWith("ss")) {
+    return normalizedValue.slice(0, -1);
+  }
+  return normalizedValue;
+}
+
+function toTitleLabel(value = "") {
+  const normalizedValue = normalizeText(value)
+    .replace(/Id$/u, "")
+    .replace(/[_-]+/gu, " ")
+    .replace(/([a-z0-9])([A-Z])/gu, "$1 $2")
+    .trim();
+  if (!normalizedValue) {
+    return "";
+  }
+
+  return normalizedValue
+    .split(/\s+/u)
+    .filter(Boolean)
+    .map((entry) => entry.charAt(0).toUpperCase() + entry.slice(1))
+    .join(" ");
+}
+
+function resolveEntityLabel(routeParamKey = "", relationNamespace = "") {
+  const routeLabel = singularizeLabel(toTitleLabel(routeParamKey));
+  if (routeLabel) {
+    return routeLabel;
+  }
+
+  const namespaceLabel = singularizeLabel(toTitleLabel(relationNamespace));
+  if (namespaceLabel) {
+    return namespaceLabel;
+  }
+
+  return "Record";
+}
+
+function resolveLookupFieldMeta(resource = {}, fieldKey = "") {
+  const normalizedFieldKey = normalizeText(fieldKey);
+  if (!normalizedFieldKey) {
+    return null;
+  }
+
+  const entry = buildCrudFieldContractMap(resource, {
+    context: "crud list parent title resource field contract"
+  })[normalizedFieldKey];
+  if (!entry) {
+    return null;
+  }
+
+  const relation = entry?.relation;
+  if (!relation || normalizeText(relation.kind).toLowerCase() !== "lookup") {
+    return null;
+  }
+
+  return entry;
+}
+
+function resolveCrudListParentDescriptor({ resource = {}, route = null, recordIdParam = "recordId" } = {}) {
+  const orderedRouteParamNames = resolveRouteParamNamesInOrder(route);
+  if (orderedRouteParamNames.length < 1) {
+    return null;
+  }
+
+  const normalizedRecordIdParam = normalizeText(recordIdParam) || "recordId";
+  for (const routeParamKey of [...orderedRouteParamNames].reverse()) {
+    if (routeParamKey === normalizedRecordIdParam) {
+      continue;
+    }
+
+    const fieldKey = resolveCrudLookupFieldKeyFromRouteParam(resource, routeParamKey);
+    if (!fieldKey) {
+      continue;
+    }
+
+    const fieldContractEntry = resolveLookupFieldMeta(resource, fieldKey);
+    if (!fieldContractEntry) {
+      continue;
+    }
+
+    const relation = fieldContractEntry.relation || {};
+    const relationNamespace = normalizeText(relation.namespace);
+    const containerKey = normalizeCrudLookupContainerKey(relation.containerKey, {
+      defaultValue: resource?.contract?.lookup?.containerKey || "lookups"
+    });
+
+    return Object.freeze({
+      fieldKey,
+      routeParamKey,
+      relationNamespace,
+      entityLabel: resolveEntityLabel(routeParamKey, relationNamespace),
+      labelKey: normalizeText(relation.labelKey),
+      fieldDescriptor: Object.freeze({
+        key: fieldKey,
+        relation: Object.freeze({
+          kind: "lookup",
+          valueKey: normalizeText(relation.valueKey) || "id",
+          labelKey: normalizeText(relation.labelKey),
+          containerKey
+        })
+      }),
+      apiUrlTemplate: relationNamespace
+        ? `${resolveCrudLookupApiPathFromNamespace(relationNamespace)}/:${routeParamKey}`
+        : ""
+    });
+  }
+
+  return null;
+}
+
+function resolveCrudListParentTitleFromItems(items = [], descriptor = null) {
+  const sourceItems = Array.isArray(items) ? items : [];
+  if (!descriptor?.fieldDescriptor) {
+    return "";
+  }
+
+  for (const item of sourceItems) {
+    const rawParentValue = toRouteParamValue(item?.[descriptor.fieldKey]);
+    const resolvedTitle = normalizeText(resolveLookupFieldDisplayValue(item, descriptor.fieldDescriptor));
+    if (resolvedTitle && rawParentValue && resolvedTitle === rawParentValue) {
+      continue;
+    }
+    if (resolvedTitle) {
+      return resolvedTitle;
+    }
+  }
+
+  return "";
+}
+
+function resolveCrudListParentRecordTitle(record = {}, descriptor = null) {
+  const resolvedTitle = resolveRecordTitle(record, {
+    fallbackKey: normalizeText(descriptor?.labelKey),
+    defaultValue: ""
+  });
+  if (resolvedTitle && resolvedTitle !== "-") {
+    return resolvedTitle;
+  }
+
+  const entityLabel = normalizeText(descriptor?.entityLabel) || "Record";
+  const recordId = toRouteParamValue(record?.id);
+  if (recordId) {
+    return `${entityLabel} #${recordId}`;
+  }
+
+  return "";
+}
+
+export {
+  resolveCrudListParentDescriptor,
+  resolveCrudListParentRecordTitle,
+  resolveCrudListParentTitleFromItems
+};

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

@@ -0,0 +1,144 @@
+import { computed, unref } from "vue";
+import { ROUTE_VISIBILITY_WORKSPACE } from "@jskit-ai/kernel/shared/support/visibility";
+import { useScopeRuntime } from "../useScopeRuntime.js";
+import { useOperationRealtime } from "../useRealtimeQueryInvalidation.js";
+import {
+  normalizePermissions,
+  resolvePermissionAccess,
+  resolveEnabled,
+  resolveQueryKey
+} from "../support/scopeHelpers.js";
+
+function normalizePermissionSets(permissionSets = {}) {
+  const source = permissionSets && typeof permissionSets === "object" && !Array.isArray(permissionSets)
+    ? permissionSets
+    : {};
+  const normalized = {};
+
+  for (const [key, value] of Object.entries(source)) {
+    normalized[key] = normalizePermissions(value);
+  }
+
+  return normalized;
+}
+
+function hasAnyPermissions(permissionSets = {}) {
+  for (const list of Object.values(permissionSets)) {
+    if (Array.isArray(list) && list.length > 0) {
+      return true;
+    }
+  }
+
+  return false;
+}
+
+function useOperationScope({
+  ownershipFilter = ROUTE_VISIBILITY_WORKSPACE,
+  surfaceId = "",
+  access = "auto",
+  placementSource = "http-web.operation",
+  apiSuffix = "",
+  model,
+  readEnabled = true,
+  queryKeyFactory = null,
+  permissionSets = {},
+  realtime = null
+} = {}) {
+  const normalizedPermissionSets = normalizePermissionSets(permissionSets);
+  const scopeRuntime = useScopeRuntime({
+    ownershipFilter,
+    surfaceId,
+    accessMode: access,
+    hasPermissionRequirements: hasAnyPermissions(normalizedPermissionSets),
+    placementSource
+  });
+  const normalizedOwnershipFilter = scopeRuntime.normalizedOwnershipFilter;
+  const routeContext = scopeRuntime.routeContext;
+  const scopeParamValue = scopeRuntime.scopeParamValue;
+  const hasRequiredRouteScope = scopeRuntime.hasRequiredRouteScope;
+  const accessRuntime = scopeRuntime.access;
+
+  const apiPath = computed(() =>
+    scopeRuntime.resolveApiPath(apiSuffix, {
+      model
+    })
+  );
+
+  const queryEnabled = computed(() =>
+    resolveEnabled(readEnabled, {
+      surfaceId: routeContext.currentSurfaceId.value,
+      scopeParamValue: scopeParamValue.value,
+      ownershipFilter: normalizedOwnershipFilter,
+      model
+    })
+  );
+
+  const queryKey = computed(() =>
+    resolveQueryKey(queryKeyFactory, {
+      surfaceId: routeContext.currentSurfaceId.value,
+      scopeParamValue: scopeParamValue.value,
+      ownershipFilter: normalizedOwnershipFilter
+    })
+  );
+  const realtimeBinding = useOperationRealtime({
+    realtime,
+    queryKey: typeof queryKeyFactory === "function" ? queryKey : null,
+    enabled: computed(() => hasRequiredRouteScope.value && Boolean(apiPath.value))
+  });
+
+  function queryCanRun(accessGate = true) {
+    return computed(() =>
+      queryEnabled.value &&
+      hasRequiredRouteScope.value &&
+      Boolean(apiPath.value) &&
+      Boolean(unref(accessGate))
+    );
+  }
+
+  function permissionGate(key = "") {
+    const list = normalizedPermissionSets[String(key || "")] || [];
+    return computed(() => resolvePermissionAccess(accessRuntime, list));
+  }
+
+  function loadError(baseError = "") {
+    return computed(() => {
+      if (scopeRuntime.routeScopeError.value) {
+        return scopeRuntime.routeScopeError.value;
+      }
+
+      const bootstrapError = String(accessRuntime.bootstrapError.value || "").trim();
+      if (bootstrapError) {
+        return bootstrapError;
+      }
+
+      if (baseError === undefined || baseError === null || baseError === "") {
+        return "";
+      }
+
+      return String(unref(baseError) || "").trim();
+    });
+  }
+
+  function isLoading(baseLoading = false) {
+    return computed(() => Boolean(unref(baseLoading)) || accessRuntime.isBootstrapping.value);
+  }
+
+  return Object.freeze({
+    scopeRuntime,
+    routeContext,
+    normalizedOwnershipFilter,
+    scopeParamValue,
+    hasRequiredRouteScope,
+    access: accessRuntime,
+    apiPath,
+    queryEnabled,
+    queryKey,
+    queryCanRun,
+    realtime: realtimeBinding,
+    permissionGate,
+    loadError,
+    isLoading
+  });
+}
+
+export { useOperationScope };

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

@@ -0,0 +1,224 @@
+import { computed, proxyRefs } from "vue";
+import { useRoute } from "vue-router";
+import { ROUTE_VISIBILITY_WORKSPACE } from "@jskit-ai/kernel/shared/support/visibility";
+import { useAddEditCore } from "../runtime/useAddEditCore.js";
+import { useEndpointResource } from "../runtime/useEndpointResource.js";
+import { resolveOperationAdapter } from "../runtime/operationAdapters.js";
+import { createAddEditUiRuntime } from "../runtime/addEditUiRuntime.js";
+import { useUiFeedback } from "../runtime/useUiFeedback.js";
+import { useFieldErrorBag } from "../runtime/useFieldErrorBag.js";
+import {
+  setupRouteChangeCleanup,
+  setupOperationErrorReporting
+} from "../runtime/operationUiHelpers.js";
+import {
+  resolveResourceMessages
+} from "../support/scopeHelpers.js";
+import { createRequestQueryRuntime } from "../support/requestQueryRuntimeSupport.js";
+import { resolveRouteParamNamesInOrder } from "../support/routeTemplateHelpers.js";
+
+function useAddEdit({
+  ownershipFilter = ROUTE_VISIBILITY_WORKSPACE,
+  surfaceId = "",
+  access = "auto",
+  resource = null,
+  apiSuffix = "",
+  queryKeyFactory = null,
+  viewPermissions = [],
+  savePermissions = [],
+  readMethod = "GET",
+  readEnabled = true,
+  writeMethod = "PATCH",
+  client = null,
+  transport = null,
+  requestRecovery = null,
+  requestRecoveryLabel = "Resource",
+  placementSource = "http-web.add-edit",
+  fallbackLoadError = "Unable to load resource.",
+  fallbackSaveError = "Unable to save resource.",
+  fieldErrorKeys = [],
+  clearOnRouteChange = true,
+  model,
+  input,
+  mapLoadedToModel,
+  buildRawPayload,
+  buildSavePayload,
+  onSaveSuccess,
+  requestQueryParams = null,
+  recordIdParam = "recordId",
+  routeParams = null,
+  routeRecordId = null,
+  apiUrlTemplate = "",
+  viewUrlTemplate = "",
+  listUrlTemplate = "",
+  saveRecordIdSelector = null,
+  messages = {},
+  realtime = null,
+  adapter = null
+} = {}) {
+  const route = useRoute();
+  const addEditUiRuntime = createAddEditUiRuntime({
+    recordIdParam,
+    routeParams: routeParams ?? computed(() => route?.params || {}),
+    routeParamNames: computed(() => resolveRouteParamNamesInOrder(route)),
+    routePath: computed(() => route?.path || ""),
+    routeRecordId,
+    apiUrlTemplate,
+    viewUrlTemplate,
+    listUrlTemplate,
+    saveRecordIdSelector
+  });
+  const normalizedApiUrlTemplate = String(apiUrlTemplate || "").trim();
+  const effectiveApiSuffix = normalizedApiUrlTemplate ? addEditUiRuntime.apiSuffix : apiSuffix;
+  const operationAdapter = resolveOperationAdapter(adapter, {
+    context: "useAddEdit adapter"
+  });
+  const operationScope = operationAdapter.useOperationScope({
+    ownershipFilter,
+    surfaceId,
+    access,
+    placementSource,
+    apiSuffix: effectiveApiSuffix,
+    model,
+    readEnabled,
+    queryKeyFactory,
+    permissionSets: {
+      view: viewPermissions,
+      save: savePermissions
+    },
+    realtime
+  });
+  const routeContext = operationScope.routeContext;
+  const effectiveMessages = {
+    ...resolveResourceMessages(resource, {
+      validation: "Fix invalid values and try again.",
+      saveSuccess: "Saved.",
+      saveError: "Unable to save."
+    }),
+    ...(messages && typeof messages === "object" ? messages : {})
+  };
+
+  const canView = operationScope.permissionGate("view");
+  const canSave = operationScope.permissionGate("save");
+  const queryCanRun = operationScope.queryCanRun(canView);
+  const queryParamsContext = computed(() => {
+    return Object.freeze({
+      surfaceId: operationScope.routeContext.currentSurfaceId.value,
+      scopeParamValue: operationScope.scopeParamValue.value,
+      ownershipFilter: operationScope.normalizedOwnershipFilter,
+      recordId: addEditUiRuntime.recordId.value,
+      model
+    });
+  });
+  const requestQueryRuntime = createRequestQueryRuntime({
+    requestQueryParams,
+    context: queryParamsContext,
+    sourceQueryKey: operationScope.queryKey
+  });
+
+  const endpointResource = useEndpointResource({
+    queryKey: requestQueryRuntime.queryKey,
+    path: operationScope.apiPath,
+    enabled: queryCanRun,
+    client,
+    readMethod,
+    writeMethod,
+    readQuery: requestQueryRuntime.requestQuery,
+    transport,
+    requestRecovery,
+    requestRecoveryLabel,
+    fallbackLoadError,
+    fallbackSaveError: String(fallbackSaveError || effectiveMessages.saveError || "Unable to save resource.")
+  });
+
+  const feedback = useUiFeedback({
+    source: `${placementSource}.feedback`
+  });
+  const fieldBag = useFieldErrorBag(fieldErrorKeys);
+
+  const addEdit = useAddEditCore({
+    model,
+    resource: endpointResource,
+    queryKey: requestQueryRuntime.queryKey,
+    canSave,
+    fieldBag,
+    feedback,
+    input,
+    mapLoadedToModel,
+    buildRawPayload,
+    buildSavePayload,
+    onSaveSuccess,
+    messages: effectiveMessages
+  });
+
+  setupRouteChangeCleanup({
+    enabled: clearOnRouteChange,
+    route: routeContext.route,
+    feedback,
+    fieldBag
+  });
+
+  const isInitialLoading = operationScope.isLoading(endpointResource.isInitialLoading);
+  const isFetching = operationScope.isLoading(endpointResource.isFetching);
+  const isRefetching = computed(() => Boolean(isFetching.value && !isInitialLoading.value));
+  const isFieldLocked = computed(() =>
+    Boolean(!canSave.value || addEdit.saving.value || isRefetching.value)
+  );
+  const isSubmitDisabled = computed(() =>
+    Boolean(isInitialLoading.value || isRefetching.value || !canSave.value)
+  );
+  const loadError = operationScope.loadError(endpointResource.loadError);
+  const isLoading = operationScope.isLoading(endpointResource.isLoading);
+  const canRetryLoad = computed(() => Boolean(readEnabled !== false && endpointResource?.reload));
+
+  async function refresh() {
+    if (!canRetryLoad.value) {
+      return null;
+    }
+
+    return endpointResource.reload();
+  }
+
+  setupOperationErrorReporting({
+    source: `${placementSource}.load`,
+    loadError,
+    dedupeWindowMs: 0,
+    loadActionFactory: () => canRetryLoad.value
+      ? {
+        label: "Retry",
+        dismissOnRun: true,
+        handler() {
+          void refresh();
+        }
+      }
+      : null
+  });
+
+  return proxyRefs({
+    canView,
+    canSave,
+    loadError,
+    isInitialLoading,
+    isFetching,
+    isRefetching,
+    isFieldLocked,
+    isSubmitDisabled,
+    canRetryLoad,
+    isLoading,
+    isSaving: addEdit.saving,
+    fieldErrors: addEdit.fieldErrors,
+    message: addEdit.message,
+    messageType: addEdit.messageType,
+    submit: addEdit.submit,
+    refresh,
+    resource: endpointResource,
+    recordId: addEditUiRuntime.recordId,
+    listUrl: addEditUiRuntime.listUrl,
+    cancelUrl: addEditUiRuntime.cancelUrl,
+    resolveParams: addEditUiRuntime.resolveParams,
+    resolveViewUrl: addEditUiRuntime.resolveViewUrl,
+    resolveSavedViewUrl: addEditUiRuntime.resolveSavedViewUrl
+  });
+}
+
+export { useAddEdit };