@jskit-ai/http-web 0.1.1

package/src/client/composables/runtime/addEditUiRuntime.js

@@ -0,0 +1,130 @@
+import { computed, unref } from "vue";
+import { asPlainObject } from "../support/scopeHelpers.js";
+import {
+  normalizeRouteParamName,
+  resolveRouteParamsSource,
+  resolveScopedRoutePathname,
+  resolveRouteTemplateLocation,
+  toRouteParamValue
+} from "../support/routeTemplateHelpers.js";
+
+function toResolvedRecordId({ routeParams, recordIdParam, routeRecordId }) {
+  const explicitRecordId = toRouteParamValue(
+    typeof routeRecordId === "function" ? routeRecordId() : unref(routeRecordId)
+  );
+  if (explicitRecordId) {
+    return explicitRecordId;
+  }
+
+  return toRouteParamValue(routeParams[recordIdParam]);
+}
+
+function resolveSavedRecordId(payload, saveRecordIdSelector) {
+  const sourcePayload = asPlainObject(payload);
+  if (typeof saveRecordIdSelector === "function") {
+    return toRouteParamValue(saveRecordIdSelector(sourcePayload));
+  }
+
+  return toRouteParamValue(sourcePayload.id);
+}
+
+function createAddEditUiRuntime({
+  recordIdParam = "recordId",
+  routeParams = null,
+  routeParamNames = null,
+  routePath = "",
+  routeRecordId = null,
+  apiUrlTemplate = "",
+  viewUrlTemplate = "",
+  listUrlTemplate = "",
+  saveRecordIdSelector = null
+} = {}) {
+  const normalizedRecordIdParam = normalizeRouteParamName(recordIdParam, {
+    context: "useAddEdit recordIdParam"
+  });
+  const normalizedApiUrlTemplate = String(apiUrlTemplate || "").trim();
+  const normalizedViewUrlTemplate = String(viewUrlTemplate || "").trim();
+  const normalizedListUrlTemplate = String(listUrlTemplate || "").trim();
+
+  function resolveTemplatePath(urlTemplate = "", extraParams = {}) {
+    const normalizedTemplate = String(urlTemplate || "").trim();
+    if (!normalizedTemplate) {
+      return "";
+    }
+
+    const currentRouteParams = resolveRouteParamsSource(routeParams);
+    const sourceParams = {
+      ...currentRouteParams,
+      ...asPlainObject(extraParams)
+    };
+    const currentRouteRecordId = toResolvedRecordId({
+      routeParams: currentRouteParams,
+      recordIdParam: normalizedRecordIdParam,
+      routeRecordId
+    });
+    const resolvedRecordId = toRouteParamValue(sourceParams[normalizedRecordIdParam]) ||
+      currentRouteRecordId;
+    sourceParams[normalizedRecordIdParam] = resolvedRecordId;
+    const currentPathname = resolveScopedRoutePathname({
+      currentPathname: routePath,
+      params: currentRouteParams,
+      orderedParamNames: routeParamNames,
+      anchorParamName: normalizedRecordIdParam,
+      anchorParamValue: currentRouteRecordId,
+      anchorMode: "after"
+    });
+
+    return resolveRouteTemplateLocation(normalizedTemplate, {
+      params: sourceParams,
+      currentPathname
+    });
+  }
+
+  const recordId = computed(() =>
+    toResolvedRecordId({
+      routeParams: resolveRouteParamsSource(routeParams),
+      recordIdParam: normalizedRecordIdParam,
+      routeRecordId
+    })
+  );
+
+  const apiSuffix = computed(() => resolveTemplatePath(normalizedApiUrlTemplate));
+  const listUrl = computed(() => resolveTemplatePath(normalizedListUrlTemplate));
+  const cancelUrl = computed(() => resolveTemplatePath(normalizedViewUrlTemplate) || listUrl.value);
+
+  function resolveParams(urlTemplate = "", extraParams = {}) {
+    return resolveTemplatePath(urlTemplate, extraParams);
+  }
+
+  function resolveViewUrl(recordIdLike = "") {
+    const targetRecordId = toRouteParamValue(recordIdLike);
+    if (!targetRecordId) {
+      return "";
+    }
+
+    return resolveTemplatePath(normalizedViewUrlTemplate, {
+      [normalizedRecordIdParam]: targetRecordId
+    });
+  }
+
+  function resolveSavedViewUrl(payload = {}) {
+    const targetRecordId = resolveSavedRecordId(payload, saveRecordIdSelector);
+    if (!targetRecordId) {
+      return "";
+    }
+
+    return resolveViewUrl(targetRecordId);
+  }
+
+  return Object.freeze({
+    recordId,
+    apiSuffix,
+    listUrl,
+    cancelUrl,
+    resolveParams,
+    resolveViewUrl,
+    resolveSavedViewUrl
+  });
+}
+
+export { createAddEditUiRuntime };

package/src/client/composables/runtime/listUiRuntime.js

@@ -0,0 +1,123 @@
+import { computed } from "vue";
+import { asPlainObject } from "../support/scopeHelpers.js";
+import {
+  normalizeRouteParamName,
+  toRouteParamValue,
+  resolveRouteParamsSource,
+  resolveScopedRoutePathname,
+  resolveRouteTemplateLocation
+} from "../support/routeTemplateHelpers.js";
+
+function resolveRecordId(record, recordIdSelector) {
+  const item = asPlainObject(record);
+  if (typeof recordIdSelector === "function") {
+    return toRouteParamValue(recordIdSelector(item));
+  }
+
+  return toRouteParamValue(item.id);
+}
+
+function createListUiRuntime({
+  items,
+  isInitialLoading,
+  recordIdParam = "recordId",
+  recordIdSelector = null,
+  routeParams = null,
+  routeParamNames = null,
+  routePath = "",
+  viewUrlTemplate = "",
+  editUrlTemplate = ""
+} = {}) {
+  const normalizedRecordIdParam = normalizeRouteParamName(recordIdParam, {
+    context: "useList recordIdParam"
+  });
+  const normalizedViewUrlTemplate = String(viewUrlTemplate || "").trim();
+  const normalizedEditUrlTemplate = String(editUrlTemplate || "").trim();
+  const hasViewUrl = Boolean(normalizedViewUrlTemplate);
+  const hasEditUrl = Boolean(normalizedEditUrlTemplate);
+  const actionColumnCount = (hasViewUrl ? 1 : 0) + (hasEditUrl ? 1 : 0);
+  const normalizedItems = computed(() => (Array.isArray(items?.value) ? items.value : []));
+  const showListSkeleton = computed(() => Boolean(isInitialLoading?.value && normalizedItems.value.length < 1));
+
+  function resolveTemplatePath(urlTemplate = "", extraParams = {}) {
+    const normalizedTemplate = String(urlTemplate || "").trim();
+    if (!normalizedTemplate) {
+      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: sourceParams,
+      currentPathname
+    });
+  }
+
+  function resolveParams(urlTemplate = "", extraParams = {}) {
+    return resolveTemplatePath(urlTemplate, extraParams);
+  }
+
+  function resolveRowKey(record, index) {
+    const recordId = resolveRecordId(record, recordIdSelector);
+    if (recordId) {
+      return recordId;
+    }
+
+    return `row-${index}`;
+  }
+
+  function resolveViewUrl(record) {
+    if (!hasViewUrl) {
+      return "";
+    }
+
+    const recordId = resolveRecordId(record, recordIdSelector);
+    if (!recordId) {
+      return "";
+    }
+
+    return resolveTemplatePath(normalizedViewUrlTemplate, {
+      [normalizedRecordIdParam]: recordId
+    });
+  }
+
+  function resolveEditUrl(record) {
+    if (!hasEditUrl) {
+      return "";
+    }
+
+    const recordId = resolveRecordId(record, recordIdSelector);
+    if (!recordId) {
+      return "";
+    }
+
+    return resolveTemplatePath(normalizedEditUrlTemplate, {
+      [normalizedRecordIdParam]: recordId
+    });
+  }
+
+  return Object.freeze({
+    hasViewUrl,
+    hasEditUrl,
+    actionColumnCount,
+    showListSkeleton,
+    resolveParams,
+    resolveRowKey,
+    resolveViewUrl,
+    resolveEditUrl
+  });
+}
+
+export { createListUiRuntime };

package/src/client/composables/runtime/modelStateHelpers.js

@@ -0,0 +1,90 @@
+import { watch } from "vue";
+
+function isObjectLike(value) {
+  return value !== null && typeof value === "object";
+}
+
+function deepClone(value) {
+  try {
+    return JSON.parse(JSON.stringify(value));
+  } catch {
+    return null;
+  }
+}
+
+function captureModelSnapshot(model) {
+  if (!isObjectLike(model)) {
+    return null;
+  }
+
+  return deepClone(model);
+}
+
+function restoreModelSnapshot(model, snapshot) {
+  if (!isObjectLike(model) || !isObjectLike(snapshot)) {
+    return;
+  }
+
+  if (Array.isArray(model) && Array.isArray(snapshot)) {
+    model.splice(0, model.length, ...snapshot);
+    return;
+  }
+
+  if (Array.isArray(model) || Array.isArray(snapshot)) {
+    return;
+  }
+
+  for (const key of Object.keys(model)) {
+    if (!Object.prototype.hasOwnProperty.call(snapshot, key)) {
+      delete model[key];
+    }
+  }
+
+  for (const [key, value] of Object.entries(snapshot)) {
+    model[key] = value;
+  }
+}
+
+function watchResourceModelState({
+  resource,
+  model,
+  mapLoadedToModel,
+  resolveMapContext = null
+} = {}) {
+  const modelSnapshot = captureModelSnapshot(model);
+
+  watch(
+    () => resource?.query?.isPending?.value,
+    (isPending) => {
+      if (!isPending || !modelSnapshot) {
+        return;
+      }
+
+      restoreModelSnapshot(model, modelSnapshot);
+    },
+    {
+      immediate: true
+    }
+  );
+
+  watch(
+    () => resource?.data?.value,
+    (payload) => {
+      if (!payload || typeof mapLoadedToModel !== "function") {
+        return;
+      }
+
+      const context = typeof resolveMapContext === "function" ? resolveMapContext() : {};
+      mapLoadedToModel(model, payload, context);
+    },
+    {
+      immediate: true
+    }
+  );
+}
+
+export {
+  captureModelSnapshot,
+  restoreModelSnapshot,
+  watchResourceModelState
+};

package/src/client/composables/runtime/operationAdapters.js

@@ -0,0 +1,34 @@
+import { useOperationScope } from "../internal/useOperationScope.js";
+
+const WEB_OPERATION_ADAPTER_ID = "http-web-default";
+
+function createWebOperationAdapter() {
+  return Object.freeze({
+    id: WEB_OPERATION_ADAPTER_ID,
+    useOperationScope(options = {}) {
+      return useOperationScope(options);
+    }
+  });
+}
+
+const defaultWebOperationAdapter = createWebOperationAdapter();
+
+function resolveOperationAdapter(adapter, { context = "http-web operation adapter" } = {}) {
+  if (adapter == null) {
+    return defaultWebOperationAdapter;
+  }
+
+  if (!adapter || typeof adapter !== "object" || Array.isArray(adapter)) {
+    throw new TypeError(`${context} must be an object when provided.`);
+  }
+  if (typeof adapter.useOperationScope !== "function") {
+    throw new TypeError(`${context} must expose useOperationScope(options).`);
+  }
+
+  return adapter;
+}
+
+export {
+  createWebOperationAdapter,
+  resolveOperationAdapter
+};

package/src/client/composables/runtime/operationUiHelpers.js

@@ -0,0 +1,125 @@
+import { watch } from "vue";
+import { useShellWebErrorRuntime } from "@jskit-ai/shell-web/client/error";
+
+function normalizeMessage(value) {
+  return String(value || "").trim();
+}
+
+function setupOperationErrorReporting({
+  enabled = true,
+  source = "http-web.operation",
+  loadError = null,
+  notFoundError = null,
+  loadActionFactory = null,
+  notFoundActionFactory = null,
+  loadChannel = "",
+  notFoundChannel = "",
+  loadSeverity = "error",
+  notFoundSeverity = "warning",
+  dedupeWindowMs = 2000
+} = {}) {
+  if (!enabled) {
+    return;
+  }
+
+  const runtime = useShellWebErrorRuntime();
+  const normalizedSource = normalizeMessage(source) || "http-web.operation";
+
+  function watchMessage(value, {
+    kind = "load",
+    channel = "",
+    intent = "resource-load",
+    severity = "error",
+    actionFactory = null
+  } = {}) {
+    let lastMessage = "";
+    let lastPresentationId = "";
+
+    watch(
+      () => normalizeMessage(value?.value),
+      (nextMessage) => {
+        if (!nextMessage) {
+          lastMessage = "";
+          if (lastPresentationId) {
+            runtime.dismiss(lastPresentationId);
+            lastPresentationId = "";
+          }
+          return;
+        }
+
+        if (nextMessage === lastMessage) {
+          return;
+        }
+
+        lastMessage = nextMessage;
+        const action = typeof actionFactory === "function"
+          ? actionFactory({
+              message: nextMessage,
+              kind
+            })
+          : null;
+        const reportResult = runtime.report({
+          source: normalizedSource,
+          message: nextMessage,
+          intent,
+          severity,
+          channel,
+          action,
+          dedupeKey: `${normalizedSource}:${kind}:${nextMessage}`,
+          dedupeWindowMs
+        });
+
+        const nextPresentationId = String(reportResult?.presentationId || "").trim();
+        if (nextPresentationId) {
+          if (lastPresentationId && lastPresentationId !== nextPresentationId) {
+            runtime.dismiss(lastPresentationId);
+          }
+          lastPresentationId = nextPresentationId;
+        }
+      },
+      { immediate: true }
+    );
+  }
+
+  if (loadError) {
+    watchMessage(loadError, {
+      kind: "load",
+      channel: loadChannel,
+      intent: "resource-load",
+      severity: loadSeverity,
+      actionFactory: loadActionFactory
+    });
+  }
+
+  if (notFoundError) {
+    watchMessage(notFoundError, {
+      kind: "not-found",
+      channel: notFoundChannel,
+      intent: "resource-load",
+      severity: notFoundSeverity,
+      actionFactory: notFoundActionFactory
+    });
+  }
+}
+
+function setupRouteChangeCleanup({
+  enabled = true,
+  route = null,
+  feedback = null,
+  fieldBag = null
+} = {}) {
+  if (!enabled) {
+    return;
+  }
+
+  watch(
+    () => route?.fullPath,
+    () => {
+      feedback?.clear?.();
+      fieldBag?.clear?.();
+    }
+  );
+}
+
+export { setupRouteChangeCleanup };
+export { setupOperationErrorReporting };

package/src/client/composables/runtime/operationValidationHelpers.js

@@ -0,0 +1,51 @@
+import {
+  createValidationFailure,
+  resolveFieldErrors
+} from "@jskit-ai/http-runtime/client";
+import { validateSchemaPayload } from "@jskit-ai/kernel/shared/validators";
+
+function validateOperationInput({
+  input,
+  rawPayload = {},
+  fieldBag = null,
+  feedback = null,
+  validationMessage = "Validation failed."
+} = {}) {
+  if (!input) {
+    return {
+      ok: true,
+      parsedInput: rawPayload
+    };
+  }
+
+  try {
+    const parsedInput = validateSchemaPayload(input, rawPayload, {
+      phase: "input",
+      context: "operation input"
+    });
+
+    return {
+      ok: true,
+      parsedInput
+    };
+  } catch (error) {
+    if (!error?.fieldErrors || typeof error.fieldErrors !== "object") {
+      throw error;
+    }
+
+    const failure = createValidationFailure({
+      error: String(validationMessage || "Validation failed."),
+      code: "validation_failed",
+      fieldErrors: error?.fieldErrors
+    });
+    fieldBag?.apply?.(resolveFieldErrors(failure));
+    feedback?.error?.(failure, failure.error);
+    return {
+      ok: false,
+      failure,
+      parsedInput: null
+    };
+  }
+}
+
+export { validateOperationInput };

package/src/client/composables/runtime/useAddEditCore.js

@@ -0,0 +1,112 @@
+import { useQueryClient } from "@tanstack/vue-query";
+import { resolveFieldErrors } from "@jskit-ai/http-runtime/client";
+import { validateOperationInput } from "./operationValidationHelpers.js";
+import { watchResourceModelState } from "./modelStateHelpers.js";
+
+function useAddEditCore({
+  model,
+  resource,
+  queryKey,
+  canSave,
+  fieldBag,
+  feedback,
+  input,
+  mapLoadedToModel,
+  buildRawPayload,
+  buildSavePayload,
+  onSaveSuccess,
+  messages = {}
+} = {}) {
+  const queryClient = useQueryClient();
+  watchResourceModelState({
+    resource,
+    model,
+    mapLoadedToModel,
+    resolveMapContext() {
+      return {
+        queryClient,
+        resource
+      };
+    }
+  });
+
+  const saving = resource?.isSaving;
+  const fieldErrors = fieldBag?.errors;
+  const message = feedback?.message;
+  const messageType = feedback?.messageType;
+
+  async function submit() {
+    if (!canSave?.value || saving?.value) {
+      return;
+    }
+
+    feedback?.clear?.();
+    fieldBag?.clear?.();
+
+    const rawPayload = typeof buildRawPayload === "function" ? buildRawPayload(model, {
+      queryClient,
+      resource
+    }) : {};
+
+    const validationResult = validateOperationInput({
+      input,
+      rawPayload,
+      fieldBag,
+      feedback,
+      validationMessage: String(messages.validation || "Validation failed.")
+    });
+    if (!validationResult.ok) {
+      return;
+    }
+
+    const { parsedInput } = validationResult;
+    const savePayload = typeof buildSavePayload === "function"
+      ? buildSavePayload(parsedInput, {
+          rawPayload,
+          queryClient,
+          resource
+        })
+      : parsedInput;
+
+    try {
+      const queryKeySnapshot = queryKey?.value;
+      const payload = await resource.save(savePayload);
+
+      if (typeof mapLoadedToModel === "function") {
+        mapLoadedToModel(model, payload, {
+          queryClient,
+          resource
+        });
+      }
+
+      if (queryKeySnapshot !== undefined) {
+        queryClient.setQueryData(queryKeySnapshot, payload);
+      }
+
+      if (typeof onSaveSuccess === "function") {
+        await onSaveSuccess(payload, {
+          queryClient,
+          parsed: parsedInput,
+          rawPayload,
+          savePayload,
+          resource
+        });
+      }
+
+      feedback?.success?.(String(messages.saveSuccess || "Saved."));
+    } catch (error) {
+      fieldBag?.apply?.(resolveFieldErrors(error));
+      feedback?.error?.(error, String(messages.saveError || "Unable to save."));
+    }
+  }
+
+  return Object.freeze({
+    saving,
+    fieldErrors,
+    message,
+    messageType,
+    submit
+  });
+}
+
+export { useAddEditCore };