@jskit-ai/users-web 0.1.4

package/src/client/composables/useAddEditCore.js

@@ -0,0 +1,137 @@
+import { watch } from "vue";
+import { useQueryClient } from "@tanstack/vue-query";
+import { resolveFieldErrors } from "@jskit-ai/http-runtime/client";
+import { validateOperationInput } from "./operationValidationHelpers.js";
+import { captureModelSnapshot, restoreModelSnapshot } from "./modelStateHelpers.js";
+
+function useAddEditCore({
+  model,
+  resource,
+  queryKey,
+  canSave,
+  fieldBag,
+  feedback,
+  parseInput,
+  mapLoadedToModel,
+  buildRawPayload,
+  buildSavePayload,
+  onSaveSuccess,
+  messages = {}
+} = {}) {
+  const queryClient = useQueryClient();
+  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;
+      }
+      mapLoadedToModel(model, payload, {
+        queryClient,
+        resource
+      });
+    },
+    {
+      immediate: true
+    }
+  );
+
+  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({
+      parseInput,
+      rawPayload,
+      context: {
+        queryClient,
+        resource
+      },
+      fieldBag,
+      feedback,
+      validationMessage: String(messages.validation || "Validation failed.")
+    });
+    if (!validationResult.ok) {
+      return;
+    }
+
+    const { parseResult, parsedInput } = validationResult;
+    const savePayload = typeof buildSavePayload === "function"
+      ? buildSavePayload(parsedInput, {
+          rawPayload,
+          queryClient,
+          resource
+        })
+      : parsedInput;
+
+    try {
+      const payload = await resource.save(savePayload);
+
+      if (typeof mapLoadedToModel === "function") {
+        mapLoadedToModel(model, payload, {
+          queryClient,
+          resource
+        });
+      }
+
+      if (queryKey?.value !== undefined) {
+        queryClient.setQueryData(queryKey.value, payload);
+      }
+
+      if (typeof onSaveSuccess === "function") {
+        await onSaveSuccess(payload, {
+          queryClient,
+          parsed: parsedInput,
+          parseResult,
+          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 };

package/src/client/composables/useBootstrapQuery.js

@@ -0,0 +1,52 @@
+import {
+  computed
+} from "vue";
+import { useQuery } from "@tanstack/vue-query";
+import { normalizeQueryToken } from "@jskit-ai/kernel/shared/support/normalize";
+import { usersWebHttpClient } from "../lib/httpClient.js";
+import { buildBootstrapApiPath } from "../lib/bootstrap.js";
+import { resolveEnabledRef, resolveTextRef } from "./refValueHelpers.js";
+
+const DEFAULT_BOOTSTRAP_STALE_TIME_MS = 60_000;
+
+function normalizeStaleTime(value, fallback = DEFAULT_BOOTSTRAP_STALE_TIME_MS) {
+  const parsed = Number(value);
+  if (!Number.isFinite(parsed) || parsed < 0) {
+    return fallback;
+  }
+  return parsed;
+}
+
+function useBootstrapQuery({
+  workspaceSlug = "",
+  enabled = true,
+  staleTime = DEFAULT_BOOTSTRAP_STALE_TIME_MS,
+  refetchOnMount = false,
+  refetchOnWindowFocus = false
+} = {}) {
+  const normalizedWorkspaceSlug = computed(() => resolveTextRef(workspaceSlug));
+  const queryKey = computed(() => ["users-web", "bootstrap", normalizeQueryToken(normalizedWorkspaceSlug.value)]);
+  const bootstrapPath = computed(() => buildBootstrapApiPath(normalizedWorkspaceSlug.value));
+  const queryEnabled = computed(() => resolveEnabledRef(enabled));
+  const queryStaleTime = normalizeStaleTime(staleTime, DEFAULT_BOOTSTRAP_STALE_TIME_MS);
+
+  const query = useQuery({
+    queryKey,
+    queryFn: () =>
+      usersWebHttpClient.request(bootstrapPath.value, {
+        method: "GET"
+      }),
+    enabled: queryEnabled,
+    staleTime: queryStaleTime,
+    refetchOnMount,
+    refetchOnWindowFocus
+  });
+
+  return Object.freeze({
+    query,
+    queryKey,
+    workspaceSlug: normalizedWorkspaceSlug
+  });
+}
+
+export { useBootstrapQuery };

package/src/client/composables/useCommand.js

@@ -0,0 +1,112 @@
+import { proxyRefs } from "vue";
+import { USERS_ROUTE_VISIBILITY_WORKSPACE } from "@jskit-ai/users-core/shared/support/usersVisibility";
+import { useCommandCore } from "./useCommandCore.js";
+import { useEndpointResource } from "./useEndpointResource.js";
+import { useOperationScope } from "./internal/useOperationScope.js";
+import { useUiFeedback } from "./useUiFeedback.js";
+import { useFieldErrorBag } from "./useFieldErrorBag.js";
+import {
+  setupRouteChangeCleanup,
+  setupOperationErrorReporting
+} from "./operationUiHelpers.js";
+
+function useCommand({
+  ownershipFilter = USERS_ROUTE_VISIBILITY_WORKSPACE,
+  surfaceId = "",
+  access = "auto",
+  apiSuffix = "",
+  runPermissions = [],
+  writeMethod = "POST",
+  placementSource = "users-web.command",
+  fallbackRunError = "Unable to complete action.",
+  fieldErrorKeys = [],
+  clearOnRouteChange = true,
+  model,
+  parseInput,
+  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 resource = useEndpointResource({
+    path: operationScope.apiPath,
+    enabled: false,
+    writeMethod,
+    fallbackSaveError: fallbackRunError
+  });
+
+  const feedback = useUiFeedback({
+    source: `${placementSource}.feedback`
+  });
+  const fieldBag = useFieldErrorBag(fieldErrorKeys);
+
+  const command = useCommandCore({
+    model,
+    resource,
+    writeMethod,
+    canRun,
+    fieldBag,
+    feedback,
+    parseInput,
+    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
+  });
+}
+
+export { useCommand };

package/src/client/composables/useCommandCore.js

@@ -0,0 +1,130 @@
+import { useQueryClient } from "@tanstack/vue-query";
+import { resolveFieldErrors } from "@jskit-ai/http-runtime/client";
+import { validateOperationInput } from "./operationValidationHelpers.js";
+
+function useCommandCore({
+  model,
+  resource,
+  writeMethod = "POST",
+  canRun,
+  fieldBag,
+  feedback,
+  parseInput,
+  buildRawPayload,
+  buildCommandPayload,
+  buildCommandOptions,
+  onRunSuccess,
+  onRunError,
+  suppressSuccessMessage = false,
+  messages = {}
+} = {}) {
+  const queryClient = useQueryClient();
+  const normalizedWriteMethod = String(writeMethod || "POST").trim().toUpperCase();
+
+  const running = resource?.isSaving;
+  const fieldErrors = fieldBag?.errors;
+  const message = feedback?.message;
+  const messageType = feedback?.messageType;
+
+  async function run(context = {}) {
+    if (!canRun?.value || running?.value) {
+      return null;
+    }
+
+    feedback?.clear?.();
+    fieldBag?.clear?.();
+
+    const rawPayload = typeof buildRawPayload === "function"
+      ? buildRawPayload(model, {
+          queryClient,
+          resource,
+          context
+        })
+      : {};
+
+    const validationResult = validateOperationInput({
+      parseInput,
+      rawPayload,
+      context: {
+        queryClient,
+        resource,
+        context
+      },
+      fieldBag,
+      feedback,
+      validationMessage: String(messages.validation || "Validation failed.")
+    });
+    if (!validationResult.ok) {
+      return null;
+    }
+
+    const { parseResult, parsedInput } = validationResult;
+    const payload = typeof buildCommandPayload === "function"
+      ? buildCommandPayload(parsedInput, {
+          rawPayload,
+          queryClient,
+          resource,
+          context
+        })
+      : (normalizedWriteMethod === "DELETE" ? undefined : parsedInput);
+
+    const options = typeof buildCommandOptions === "function"
+      ? buildCommandOptions(parsedInput, {
+          rawPayload,
+          queryClient,
+          resource,
+          context
+        })
+      : {};
+
+    try {
+      const response = await resource.save(payload, options);
+
+      if (typeof onRunSuccess === "function") {
+        await onRunSuccess(response, {
+          parsed: parsedInput,
+          parseResult,
+          rawPayload,
+          payload,
+          options,
+          queryClient,
+          resource,
+          context
+        });
+      }
+
+      if (!suppressSuccessMessage) {
+        feedback?.success?.(String(messages.success || "Completed."));
+      }
+      return response;
+    } catch (error) {
+      fieldBag?.apply?.(resolveFieldErrors(error));
+
+      if (typeof onRunError === "function") {
+        await onRunError(error, {
+          parsed: parsedInput,
+          parseResult,
+          rawPayload,
+          payload,
+          options,
+          queryClient,
+          resource,
+          context
+        });
+      }
+
+      feedback?.error?.(error, String(messages.error || "Unable to complete action."));
+      throw error;
+    }
+  }
+
+  return Object.freeze({
+    running,
+    fieldErrors,
+    message,
+    messageType,
+    run
+  });
+}
+
+export { useCommandCore };

package/src/client/composables/useEndpointResource.js

@@ -0,0 +1,104 @@
+import { computed } from "vue";
+import { useMutation, useQuery } from "@tanstack/vue-query";
+import { usersWebHttpClient } from "../lib/httpClient.js";
+import { asPlainObject } from "./scopeHelpers.js";
+import { resolveEnabledRef, resolveTextRef } from "./refValueHelpers.js";
+import { toQueryErrorMessage } from "./errorMessageHelpers.js";
+
+function useEndpointResource({
+  queryKey,
+  path = "",
+  enabled = true,
+  client = usersWebHttpClient,
+  readMethod = "GET",
+  writeMethod = "PATCH",
+  queryOptions = null,
+  mutationOptions = null,
+  fallbackLoadError = "Unable to load resource.",
+  fallbackSaveError = "Unable to save resource."
+} = {}) {
+  if (!client || typeof client.request !== "function") {
+    throw new TypeError("useEndpointResource requires a client with request().");
+  }
+
+  const normalizedPath = computed(() => resolveTextRef(path));
+  const queryEnabled = computed(() => resolveEnabledRef(enabled) && Boolean(normalizedPath.value));
+
+  const query = useQuery({
+    queryKey,
+    queryFn: () => {
+      const requestPath = normalizedPath.value;
+      if (!requestPath) {
+        throw new Error("Resource path is required.");
+      }
+
+      return client.request(requestPath, {
+        method: String(readMethod || "GET").toUpperCase()
+      });
+    },
+    enabled: queryEnabled,
+    ...(asPlainObject(queryOptions))
+  });
+
+  const mutation = useMutation({
+    mutationFn: async (request = {}) => {
+      const options = asPlainObject(request);
+      const requestPath = resolveTextRef(options.path || normalizedPath.value);
+      if (!requestPath) {
+        throw new Error("Resource path is required.");
+      }
+
+      const method = String(options.method || writeMethod || "PATCH").toUpperCase();
+      const hasBody = Object.prototype.hasOwnProperty.call(options, "body");
+      const body = hasBody ? options.body : options.payload;
+      const requestOptions = {
+        method,
+        ...(asPlainObject(options.options))
+      };
+
+      if (body !== undefined) {
+        requestOptions.body = body;
+      }
+
+      return client.request(requestPath, requestOptions);
+    },
+    ...(asPlainObject(mutationOptions))
+  });
+
+  const data = computed(() => query.data.value);
+  const isInitialLoading = computed(() => Boolean(queryEnabled.value && query.isPending.value));
+  const isFetching = computed(() => Boolean(queryEnabled.value && query.isFetching.value));
+  const isRefetching = computed(() => Boolean(isFetching.value && !isInitialLoading.value));
+  const isLoading = computed(() => Boolean(isInitialLoading.value || isFetching.value));
+  const isSaving = computed(() => Boolean(mutation.isPending.value));
+  const loadError = computed(() => toQueryErrorMessage(query.error.value, fallbackLoadError, "Request failed."));
+  const saveError = computed(() => toQueryErrorMessage(mutation.error.value, fallbackSaveError, "Request failed."));
+
+  async function reload() {
+    return query.refetch();
+  }
+
+  async function save(payload, options = {}) {
+    return mutation.mutateAsync({
+      ...asPlainObject(options),
+      payload
+    });
+  }
+
+  return Object.freeze({
+    query,
+    mutation,
+    data,
+    isInitialLoading,
+    isFetching,
+    isRefetching,
+    isLoading,
+    isSaving,
+    loadError,
+    saveError,
+    reload,
+    save
+  });
+}
+
+export { useEndpointResource };

package/src/client/composables/useFieldErrorBag.js

@@ -0,0 +1,61 @@
+import { reactive } from "vue";
+
+function normalizeKeys(keys) {
+  return Array.isArray(keys)
+    ? keys.map((entry) => String(entry || "").trim()).filter(Boolean)
+    : [];
+}
+
+function useFieldErrorBag(keys = []) {
+  const normalizedKeys = normalizeKeys(keys);
+  const hasFixedKeys = normalizedKeys.length > 0;
+  const errors = reactive(
+    Object.fromEntries(normalizedKeys.map((key) => [key, ""]))
+  );
+
+  function clear() {
+    const keysToClear = hasFixedKeys ? normalizedKeys : Object.keys(errors);
+    for (const key of keysToClear) {
+      errors[key] = "";
+    }
+  }
+
+  function apply(source = {}) {
+    const fieldErrorMap = source && typeof source === "object" ? source : {};
+    if (hasFixedKeys) {
+      for (const key of normalizedKeys) {
+        errors[key] = String(fieldErrorMap[key] || "");
+      }
+      return;
+    }
+
+    clear();
+    for (const [field, message] of Object.entries(fieldErrorMap)) {
+      const key = String(field || "").trim();
+      if (!key) {
+        continue;
+      }
+      errors[key] = String(message || "");
+    }
+  }
+
+  function set(field, message) {
+    const key = String(field || "").trim();
+    if (!key) {
+      return;
+    }
+    if (hasFixedKeys && !(key in errors)) {
+      return;
+    }
+    errors[key] = String(message || "");
+  }
+
+  return Object.freeze({
+    errors,
+    clear,
+    apply,
+    set
+  });
+}
+
+export { useFieldErrorBag };

package/src/client/composables/useList.js

@@ -0,0 +1,85 @@
+import { computed } from "vue";
+import { USERS_ROUTE_VISIBILITY_WORKSPACE } from "@jskit-ai/users-core/shared/support/usersVisibility";
+import { useListCore } from "./useListCore.js";
+import { useOperationScope } from "./internal/useOperationScope.js";
+import { setupOperationErrorReporting } from "./operationUiHelpers.js";
+
+function useList({
+  ownershipFilter = USERS_ROUTE_VISIBILITY_WORKSPACE,
+  surfaceId = "",
+  access = "auto",
+  apiSuffix = "",
+  queryKeyFactory = null,
+  viewPermissions = [],
+  readEnabled = true,
+  placementSource = "users-web.list",
+  fallbackLoadError = "Unable to load list.",
+  initialPageParam = null,
+  getNextPageParam,
+  selectItems,
+  requestOptions,
+  queryOptions,
+  realtime = null
+} = {}) {
+  const operationScope = useOperationScope({
+    ownershipFilter,
+    surfaceId,
+    access,
+    placementSource,
+    apiSuffix,
+    readEnabled,
+    queryKeyFactory,
+    permissionSets: {
+      view: viewPermissions
+    },
+    realtime
+  });
+  const canView = operationScope.permissionGate("view");
+
+  const list = useListCore({
+    queryKey: operationScope.queryKey,
+    path: operationScope.apiPath,
+    enabled: operationScope.queryCanRun(canView),
+    initialPageParam,
+    getNextPageParam,
+    selectItems,
+    requestOptions,
+    queryOptions,
+    fallbackLoadError
+  });
+
+  const isInitialLoading = operationScope.isLoading(list.isInitialLoading);
+  const isFetching = operationScope.isLoading(list.isFetching);
+  const isRefetching = computed(() => Boolean(isFetching.value && !isInitialLoading.value));
+  const loadError = operationScope.loadError(list.loadError);
+  const isLoading = operationScope.isLoading(list.isLoading);
+  setupOperationErrorReporting({
+    source: `${placementSource}.load`,
+    loadError,
+    dedupeWindowMs: 0,
+    loadActionFactory: () => ({
+      label: "Retry",
+      dismissOnRun: true,
+      handler() {
+        void list.reload();
+      }
+    })
+  });
+
+  return Object.freeze({
+    canView,
+    isInitialLoading,
+    isFetching,
+    isRefetching,
+    isLoading,
+    isLoadingMore: list.isLoadingMore,
+    hasMore: list.hasMore,
+    loadError,
+    pages: list.pages,
+    items: list.items,
+    reload: list.reload,
+    loadMore: list.loadMore
+  });
+}
+
+export { useList };