@jskit-ai/http-web 0.1.1

package/src/client/composables/support/scopeHelpers.js

@@ -0,0 +1,145 @@
+import { resolveEnabledRef, resolveTextRef } from "./refValueHelpers.js";
+import {
+  ROUTE_VISIBILITY_TOKENS,
+  ROUTE_VISIBILITY_WORKSPACE,
+  ROUTE_VISIBILITY_WORKSPACE_USER
+} from "@jskit-ai/kernel/shared/support/visibility";
+
+const OWNERSHIP_FILTER_VALUES = ROUTE_VISIBILITY_TOKENS;
+const SCOPED_OWNERSHIP_FILTER_SET = new Set([
+  ROUTE_VISIBILITY_WORKSPACE,
+  ROUTE_VISIBILITY_WORKSPACE_USER
+]);
+const ACCESS_MODE_VALUES = Object.freeze(["auto", "always", "never"]);
+
+function asPlainObject(value) {
+  if (!value || typeof value !== "object" || Array.isArray(value)) {
+    return {};
+  }
+
+  return value;
+}
+
+function normalizePermissions(value) {
+  if (Array.isArray(value)) {
+    return value.map((entry) => String(entry || "").trim()).filter(Boolean);
+  }
+
+  const one = String(value || "").trim();
+  return one ? [one] : [];
+}
+
+function resolvePermissionAccess(access, normalizedPermissions = []) {
+  if (normalizedPermissions.length < 1) {
+    return true;
+  }
+
+  return access.canAny(normalizedPermissions);
+}
+
+function normalizeAccessMode(value = "auto") {
+  const normalized = String(value || "auto").trim().toLowerCase();
+  if (ACCESS_MODE_VALUES.includes(normalized)) {
+    return normalized;
+  }
+
+  throw new TypeError(
+    `access must be one of: ${ACCESS_MODE_VALUES.join(", ")}. Received: ${String(value || "") || "(empty)"}`
+  );
+}
+
+function resolveAccessModeEnabled(accessMode = "auto", { hasPermissionRequirements = false } = {}) {
+  const normalizedMode = normalizeAccessMode(accessMode);
+  if (normalizedMode === "always") {
+    return true;
+  }
+  if (normalizedMode === "never") {
+    return false;
+  }
+
+  return hasPermissionRequirements === true;
+}
+
+function ensureAccessModeCompatibility({
+  accessMode = "auto",
+  hasPermissionRequirements = false,
+  caller = "http-web"
+} = {}) {
+  const normalizedMode = normalizeAccessMode(accessMode);
+  if (normalizedMode === "never" && hasPermissionRequirements) {
+    throw new TypeError(`${caller} cannot use access:\"never\" when permission requirements are configured.`);
+  }
+
+  return normalizedMode;
+}
+
+function resolveApiSuffix(apiSuffix, context = {}) {
+  if (typeof apiSuffix === "function") {
+    return resolveTextRef(apiSuffix(context));
+  }
+
+  return resolveTextRef(apiSuffix);
+}
+
+function resolveEnabled(value, context = {}) {
+  if (typeof value === "function") {
+    return Boolean(value(context));
+  }
+
+  return resolveEnabledRef(value);
+}
+
+function normalizeOwnershipFilter(value = ROUTE_VISIBILITY_WORKSPACE) {
+  const normalized = String(value || ROUTE_VISIBILITY_WORKSPACE).trim().toLowerCase();
+  if (OWNERSHIP_FILTER_VALUES.includes(normalized)) {
+    return normalized;
+  }
+
+  throw new TypeError(
+    `ownershipFilter must be one of: ${OWNERSHIP_FILTER_VALUES.join(", ")}. Received: ${String(value || "") || "(empty)"}`
+  );
+}
+
+function isScopedOwnershipFilter(ownershipFilter) {
+  return SCOPED_OWNERSHIP_FILTER_SET.has(ownershipFilter);
+}
+
+function resolveQueryKey(
+  queryKeyFactory,
+  { surfaceId = "", scopeParamValue = "", ownershipFilter = ROUTE_VISIBILITY_WORKSPACE } = {}
+) {
+  if (typeof queryKeyFactory !== "function") {
+    throw new TypeError("queryKeyFactory is required.");
+  }
+
+  if (isScopedOwnershipFilter(ownershipFilter)) {
+    return queryKeyFactory(surfaceId, scopeParamValue, ownershipFilter);
+  }
+
+  return queryKeyFactory(surfaceId, ownershipFilter);
+}
+
+function resolveResourceMessages(resource, defaults = {}) {
+  const defaultMessages = asPlainObject(defaults);
+  const resourceMessages = asPlainObject(asPlainObject(resource).messages);
+
+  return {
+    ...defaultMessages,
+    ...resourceMessages
+  };
+}
+
+export {
+  asPlainObject,
+  normalizePermissions,
+  resolvePermissionAccess,
+  normalizeAccessMode,
+  resolveAccessModeEnabled,
+  ensureAccessModeCompatibility,
+  resolveApiSuffix,
+  resolveEnabled,
+  normalizeOwnershipFilter,
+  isScopedOwnershipFilter,
+  resolveQueryKey,
+  resolveResourceMessages
+};

package/src/client/composables/useAccess.js

@@ -0,0 +1,109 @@
+import { computed } from "vue";
+import { hasPermission, normalizePermissionList } from "../lib/permissions.js";
+import { resolveEnabledRef, resolveTextRef } from "./support/refValueHelpers.js";
+import {
+  normalizeAccessMode,
+  resolveAccessModeEnabled
+} from "./support/scopeHelpers.js";
+import { useWebPlacementContext } from "@jskit-ai/shell-web/client/placement";
+
+function asPermissionList(value) {
+  if (Array.isArray(value)) {
+    return value;
+  }
+
+  if (value === undefined || value === null || value === "") {
+    return [];
+  }
+
+  return [value];
+}
+
+function useAccess({
+  scopeParamValue = "",
+  enabled = true,
+  access = "always",
+  hasPermissionRequirements = false
+} = {}) {
+  const normalizedAccessMode = normalizeAccessMode(access);
+  const accessRequired = resolveAccessModeEnabled(normalizedAccessMode, {
+    hasPermissionRequirements: hasPermissionRequirements === true
+  });
+  const { context: placementContext } = useWebPlacementContext();
+  const normalizedScopeParamValue = computed(() => resolveTextRef(scopeParamValue));
+  const queryEnabled = computed(() => resolveEnabledRef(enabled) && accessRequired);
+  const hasPlacementBootstrapPermissions = computed(() => {
+    const source = placementContext.value;
+    if (!source || typeof source !== "object") {
+      return false;
+    }
+    return Object.hasOwn(source, "permissions");
+  });
+  const placementPermissions = computed(() => normalizePermissionList(placementContext.value?.permissions));
+  const permissions = computed(() => {
+    if (!queryEnabled.value || !hasPlacementBootstrapPermissions.value) {
+      return [];
+    }
+    return placementPermissions.value;
+  });
+  const bootstrapError = computed(() => {
+    if (!queryEnabled.value || hasPlacementBootstrapPermissions.value) {
+      return "";
+    }
+    return "Permissions are unavailable in placement context.";
+  });
+  const isBootstrapping = computed(() => queryEnabled.value && !hasPlacementBootstrapPermissions.value);
+
+  function can(permission) {
+    return hasPermission(permissions.value, permission);
+  }
+
+  function canAny(requiredPermissions) {
+    const list = asPermissionList(requiredPermissions);
+    if (list.length < 1) {
+      return true;
+    }
+
+    for (const entry of list) {
+      if (can(entry)) {
+        return true;
+      }
+    }
+
+    return false;
+  }
+
+  function canAll(requiredPermissions) {
+    const list = asPermissionList(requiredPermissions);
+    if (list.length < 1) {
+      return true;
+    }
+
+    for (const entry of list) {
+      if (!can(entry)) {
+        return false;
+      }
+    }
+
+    return true;
+  }
+
+  async function refreshBootstrap() {
+    return null;
+  }
+
+  return Object.freeze({
+    accessMode: normalizedAccessMode,
+    accessRequired,
+    scopeParamValue: normalizedScopeParamValue,
+    permissions,
+    bootstrapError,
+    isBootstrapping,
+    can,
+    canAny,
+    canAll,
+    refreshBootstrap
+  });
+}
+
+export { useAccess };

package/src/client/composables/useCommand.js

@@ -0,0 +1,118 @@
+import { proxyRefs } from "vue";
+import { ROUTE_VISIBILITY_WORKSPACE } from "@jskit-ai/kernel/shared/support/visibility";
+import { useCommandCore } from "./runtime/useCommandCore.js";
+import { useEndpointResource } from "./runtime/useEndpointResource.js";
+import { useOperationScope } from "./internal/useOperationScope.js";
+import { useUiFeedback } from "./runtime/useUiFeedback.js";
+import { useFieldErrorBag } from "./runtime/useFieldErrorBag.js";
+import {
+  setupRouteChangeCleanup,
+  setupOperationErrorReporting
+} from "./runtime/operationUiHelpers.js";
+import { resolveCrudHttpClient } from "./crud/crudHttpClientSupport.js";
+
+function useCommand({
+  ownershipFilter = ROUTE_VISIBILITY_WORKSPACE,
+  surfaceId = "",
+  access = "auto",
+  apiSuffix = "",
+  runPermissions = [],
+  writeMethod = "POST",
+  client = null,
+  resource: commandResource = null,
+  transport = null,
+  placementSource = "http-web.command",
+  fallbackRunError = "Unable to complete action.",
+  fieldErrorKeys = [],
+  clearOnRouteChange = true,
+  model,
+  input,
+  buildRawPayload,
+  buildCommandPayload,
+  buildCommandOptions,
+  onRunSuccess,
+  onRunError,
+  suppressSuccessMessage = false,
+  messages = {},
+  realtime = null
+} = {}) {
+  const operationScope = useOperationScope({
+    ownershipFilter,
+    surfaceId,
+    access,
+    placementSource,
+    apiSuffix,
+    model,
+    readEnabled: false,
+    permissionSets: {
+      run: runPermissions
+    },
+    realtime
+  });
+  const routeContext = operationScope.routeContext;
+  const canRun = operationScope.permissionGate("run");
+
+  const endpointResource = useEndpointResource({
+    path: operationScope.apiPath,
+    enabled: false,
+    client: resolveCrudHttpClient(commandResource, { client }),
+    writeMethod,
+    transport,
+    fallbackSaveError: fallbackRunError
+  });
+
+  const feedback = useUiFeedback({
+    source: `${placementSource}.feedback`
+  });
+  const fieldBag = useFieldErrorBag(fieldErrorKeys);
+
+  const command = useCommandCore({
+    model,
+    resource: endpointResource,
+    writeMethod,
+    canRun,
+    fieldBag,
+    feedback,
+    input,
+    buildRawPayload,
+    buildCommandPayload,
+    buildCommandOptions,
+    onRunSuccess,
+    onRunError,
+    suppressSuccessMessage: Boolean(suppressSuccessMessage),
+    messages: {
+      validation: "Fix invalid values and try again.",
+      success: "Completed.",
+      error: String(fallbackRunError || "Unable to complete action."),
+      ...(messages && typeof messages === "object" ? messages : {})
+    }
+  });
+
+  setupRouteChangeCleanup({
+    enabled: clearOnRouteChange,
+    route: routeContext.route,
+    feedback,
+    fieldBag
+  });
+
+  const loadError = operationScope.loadError();
+  const isLoading = operationScope.isLoading();
+  setupOperationErrorReporting({
+    source: `${placementSource}.load`,
+    loadError
+  });
+
+  return proxyRefs({
+    canRun,
+    isLoading,
+    loadError,
+    isRunning: command.running,
+    fieldErrors: command.fieldErrors,
+    message: command.message,
+    messageType: command.messageType,
+    run: command.run,
+    resource: endpointResource
+  });
+}
+
+export { useCommand };

package/src/client/composables/useCrudAddEditScreen.js

@@ -0,0 +1,88 @@
+import { computed, unref } from "vue";
+import { useRoute } from "vue-router";
+import { useCrudAddEdit } from "./records/useCrudAddEdit.js";
+
+function normalizeProvidedScreen(screen = null) {
+  return screen && typeof screen === "object" && !Array.isArray(screen)
+    ? screen
+    : null;
+}
+
+function useCrudAddEditScreen({
+  screen = null,
+  mode = "new",
+  title = "",
+  subtitle = "",
+  saveLabel = "Save",
+  cancelTo = "",
+  resource = null,
+  operationName = "",
+  formFields = [],
+  addEditOptions = {},
+  saveSuccess = {},
+  fieldBinding = null,
+  createModel = null,
+  buildPayload = null,
+  mapPayloadToModel = null,
+  input = null,
+  preserveCancelQuery = false
+} = {}) {
+  const providedScreen = normalizeProvidedScreen(screen);
+  if (providedScreen) {
+    return providedScreen;
+  }
+
+  const route = useRoute();
+  const formRuntime = useCrudAddEdit({
+    resource,
+    operationName,
+    formFields,
+    addEditOptions,
+    saveSuccess,
+    fieldBinding,
+    createModel,
+    buildPayload,
+    mapPayloadToModel,
+    input
+  });
+  const resolvedMode = computed(() => String(unref(mode) || "new").trim() || "new");
+  const resolvedTitle = computed(() => String(unref(title) || "").trim());
+  const resolvedSubtitle = computed(() => String(unref(subtitle) || "").trim());
+  const resolvedSaveLabel = computed(() => String(unref(saveLabel) || "Save").trim() || "Save");
+  const resolvedCancelTo = computed(() => unref(cancelTo));
+
+  function resolveCancelTo(target = resolvedCancelTo.value) {
+    const resolvedTarget = unref(target);
+    if (!resolvedTarget) {
+      return "";
+    }
+
+    if (typeof resolvedTarget === "string") {
+      const resolvedPath = formRuntime.addEdit.resolveParams(resolvedTarget);
+      if (!preserveCancelQuery || !resolvedPath) {
+        return resolvedPath;
+      }
+      return {
+        path: resolvedPath,
+        query: route.query
+      };
+    }
+
+    return resolvedTarget;
+  }
+
+  return Object.freeze({
+    mode: resolvedMode,
+    title: resolvedTitle,
+    subtitle: resolvedSubtitle,
+    saveLabel: resolvedSaveLabel,
+    cancelTo: resolvedCancelTo,
+    formRuntime,
+    addEdit: formRuntime.addEdit,
+    formState: formRuntime.form,
+    resolveFieldErrors: formRuntime.resolveFieldErrors,
+    resolveCancelTo
+  });
+}
+
+export { useCrudAddEditScreen };

package/src/client/composables/useCrudDeleteAction.js

@@ -0,0 +1,160 @@
+import { computed, proxyRefs, ref, unref } from "vue";
+import { useRouter } from "vue-router";
+import { normalizeText } from "@jskit-ai/kernel/shared/support/normalize";
+import { resolveCrudJsonApiTransport } from "./crud/crudJsonApiTransportSupport.js";
+import { toQueryErrorMessage } from "./support/errorMessageHelpers.js";
+import { useCommand } from "./useCommand.js";
+
+function requireCrudDeleteOperation(resource = null) {
+  const operation = resource?.operations?.delete;
+  if (!operation || typeof operation !== "object" || Array.isArray(operation)) {
+    throw new TypeError("useCrudDeleteAction requires resource.operations.delete.");
+  }
+  if (normalizeText(operation.method).toUpperCase() !== "DELETE") {
+    throw new TypeError("useCrudDeleteAction requires resource.operations.delete.method to be DELETE.");
+  }
+  return operation;
+}
+
+function requireCrudViewScreen(screen = null) {
+  if (!screen || typeof screen !== "object" || typeof screen?.view?.resolveParams !== "function") {
+    throw new TypeError("useCrudDeleteAction requires a useCrudViewScreen() result.");
+  }
+  return screen;
+}
+
+function resolveDeleteApiSuffix(screen, apiUrlTemplate = "") {
+  const template = normalizeText(unref(apiUrlTemplate));
+  return template ? normalizeText(screen.view.resolveParams(template)) : "";
+}
+
+function resolveListLocation(screen) {
+  return unref(screen?.listLocation) || null;
+}
+
+function useCrudDeleteAction({
+  screen = null,
+  resource = null,
+  resourceNamespace = "",
+  apiUrlTemplate = "",
+  access = "auto",
+  client = null,
+  router: routerOverride = null,
+  fallbackDeleteError = "Unable to delete record."
+} = {}) {
+  const resolvedScreen = requireCrudViewScreen(screen);
+  const deleteOperation = requireCrudDeleteOperation(resource);
+  const namespace = normalizeText(resourceNamespace, {
+    fallback: resource?.namespace
+  });
+  if (!namespace) {
+    throw new TypeError("useCrudDeleteAction requires resourceNamespace or resource.namespace.");
+  }
+
+  const activeRouter = routerOverride || useRouter();
+  if (!activeRouter || typeof activeRouter.push !== "function") {
+    throw new TypeError("useCrudDeleteAction requires an installed Vue Router.");
+  }
+
+  const isOpen = ref(false);
+  const error = ref("");
+  const deleteApiSuffix = computed(() => resolveDeleteApiSuffix(resolvedScreen, apiUrlTemplate));
+
+  async function handleDeleteSuccess(_response, context = {}) {
+    await context?.queryClient?.invalidateQueries?.({
+      queryKey: ["ui-generator", namespace]
+    });
+
+    const listLocation = resolveListLocation(resolvedScreen);
+    if (!listLocation) {
+      throw new Error("Deleted the record, but the generated list route is unavailable.");
+    }
+
+    isOpen.value = false;
+    await activeRouter.push(listLocation);
+  }
+
+  function handleDeleteError(cause) {
+    error.value = toQueryErrorMessage(
+      cause,
+      fallbackDeleteError,
+      "Unable to delete record."
+    );
+  }
+
+  const command = useCommand({
+    access,
+    apiSuffix: deleteApiSuffix,
+    writeMethod: deleteOperation.method,
+    client,
+    transport: resolveCrudJsonApiTransport(undefined, resource, {
+      mode: "delete"
+    }),
+    placementSource: `ui-generator.${namespace}.view.delete`,
+    fallbackRunError: fallbackDeleteError,
+    onRunSuccess: handleDeleteSuccess,
+    onRunError: handleDeleteError,
+    suppressSuccessMessage: true
+  });
+
+  const isDeleting = computed(() => Boolean(command.isRunning));
+  const canDelete = computed(() => {
+    const view = resolvedScreen.view;
+    return Boolean(
+      command.canRun &&
+      deleteApiSuffix.value &&
+      resolveListLocation(resolvedScreen) &&
+      unref(view.recordId) &&
+      unref(view.record) &&
+      !unref(view.isLoading) &&
+      !unref(view.isNotFound)
+    );
+  });
+
+  function request() {
+    if (!canDelete.value) {
+      return false;
+    }
+    error.value = "";
+    isOpen.value = true;
+    return true;
+  }
+
+  function cancel() {
+    if (isDeleting.value) {
+      return false;
+    }
+    error.value = "";
+    isOpen.value = false;
+    return true;
+  }
+
+  async function confirm() {
+    if (!isOpen.value || !canDelete.value || isDeleting.value) {
+      return null;
+    }
+
+    error.value = "";
+    try {
+      return await command.run();
+    } catch {
+      return null;
+    }
+  }
+
+  return proxyRefs({
+    isOpen,
+    isDeleting,
+    canDelete,
+    error,
+    request,
+    cancel,
+    confirm
+  });
+}
+
+export {
+  requireCrudDeleteOperation,
+  resolveDeleteApiSuffix,
+  useCrudDeleteAction
+};