@jskit-ai/users-web 0.1.4

package/src/client/composables/useListCore.js

@@ -0,0 +1,65 @@
+import { computed } from "vue";
+import { appendQueryString } from "@jskit-ai/kernel/shared/support";
+import { usersWebHttpClient } from "../lib/httpClient.js";
+import { asPlainObject } from "./scopeHelpers.js";
+import { resolveEnabledRef, resolveTextRef } from "./refValueHelpers.js";
+import { usePagedCollection } from "./usePagedCollection.js";
+
+function appendPageParam(path, pageParam) {
+  const normalizedPath = String(path || "").trim();
+  if (!normalizedPath) {
+    return "";
+  }
+  if (pageParam === null || pageParam === undefined || pageParam === "") {
+    return normalizedPath;
+  }
+
+  const query = new URLSearchParams();
+  query.set("cursor", String(pageParam));
+  return appendQueryString(normalizedPath, query.toString());
+}
+
+function useListCore({
+  queryKey,
+  path = "",
+  enabled = true,
+  client = usersWebHttpClient,
+  initialPageParam = null,
+  getNextPageParam,
+  selectItems,
+  requestOptions = null,
+  queryOptions = null,
+  fallbackLoadError = "Unable to load list."
+} = {}) {
+  if (!client || typeof client.request !== "function") {
+    throw new TypeError("useListCore requires a client with request().");
+  }
+
+  const normalizedPath = computed(() => resolveTextRef(path));
+  const queryEnabled = computed(() => resolveEnabledRef(enabled) && Boolean(normalizedPath.value));
+
+  const collection = usePagedCollection({
+    queryKey,
+    initialPageParam,
+    enabled: queryEnabled,
+    queryFn: async ({ pageParam }) => {
+      const requestPath = appendPageParam(normalizedPath.value, pageParam);
+      if (!requestPath) {
+        throw new Error("List path is required.");
+      }
+
+      return client.request(requestPath, {
+        method: "GET",
+        ...(asPlainObject(requestOptions))
+      });
+    },
+    getNextPageParam,
+    selectItems,
+    queryOptions,
+    fallbackLoadError
+  });
+
+  return collection;
+}
+
+export { useListCore };

package/src/client/composables/usePagedCollection.js

@@ -0,0 +1,125 @@
+import { computed } from "vue";
+import { useInfiniteQuery } from "@tanstack/vue-query";
+import { asPlainObject } from "./scopeHelpers.js";
+import { resolveEnabledRef } from "./refValueHelpers.js";
+import { toQueryErrorMessage } from "./errorMessageHelpers.js";
+
+function defaultSelectItems(page) {
+  return Array.isArray(page?.items) ? page.items : [];
+}
+
+function defaultGetNextPageParam(lastPage) {
+  return lastPage?.nextCursor ?? null;
+}
+
+function usePagedCollection({
+  queryKey,
+  enabled = true,
+  initialPageParam = null,
+  queryFn,
+  getNextPageParam = defaultGetNextPageParam,
+  selectItems = defaultSelectItems,
+  dedupeBy = null,
+  queryOptions = null,
+  fallbackLoadError = "Unable to load list."
+} = {}) {
+  if (typeof queryFn !== "function") {
+    throw new TypeError("usePagedCollection requires queryFn().");
+  }
+  if (typeof getNextPageParam !== "function") {
+    throw new TypeError("usePagedCollection requires getNextPageParam().");
+  }
+  if (typeof selectItems !== "function") {
+    throw new TypeError("usePagedCollection requires selectItems().");
+  }
+  if (dedupeBy != null && typeof dedupeBy !== "function") {
+    throw new TypeError("usePagedCollection dedupeBy must be a function when provided.");
+  }
+
+  const queryEnabled = computed(() => resolveEnabledRef(enabled));
+
+  const query = useInfiniteQuery({
+    queryKey,
+    initialPageParam,
+    enabled: queryEnabled,
+    queryFn,
+    getNextPageParam: (lastPage, allPages, lastPageParam, allPageParams) =>
+      getNextPageParam(lastPage, allPages, lastPageParam, allPageParams),
+    ...(asPlainObject(queryOptions))
+  });
+
+  const pages = computed(() => {
+    const pageList = query.data.value?.pages;
+    return Array.isArray(pageList) ? pageList : [];
+  });
+
+  const items = computed(() => {
+    const result = [];
+    const seen = dedupeBy ? new Set() : null;
+
+    for (const page of pages.value) {
+      const pageItems = selectItems(page);
+      if (!Array.isArray(pageItems)) {
+        continue;
+      }
+
+      if (!seen) {
+        result.push(...pageItems);
+        continue;
+      }
+
+      for (const item of pageItems) {
+        const key = dedupeBy(item);
+        const normalizedKey = String(key ?? "").trim();
+        if (!normalizedKey) {
+          result.push(item);
+          continue;
+        }
+        if (seen.has(normalizedKey)) {
+          continue;
+        }
+        seen.add(normalizedKey);
+        result.push(item);
+      }
+    }
+
+    return result;
+  });
+
+  const isInitialLoading = computed(() => Boolean(query.isPending.value));
+  const isFetching = computed(() => Boolean(query.isFetching.value));
+  const isRefetching = computed(() => Boolean(isFetching.value && !isInitialLoading.value));
+  const isLoading = computed(() => Boolean(isInitialLoading.value || isFetching.value));
+  const isLoadingMore = computed(() => Boolean(query.isFetchingNextPage.value));
+  const hasMore = computed(() => Boolean(query.hasNextPage.value));
+  const loadError = computed(() => toQueryErrorMessage(query.error.value, fallbackLoadError, "Unable to load list."));
+
+  async function reload() {
+    return query.refetch();
+  }
+
+  async function loadMore() {
+    if (!hasMore.value || isLoadingMore.value) {
+      return null;
+    }
+
+    return query.fetchNextPage();
+  }
+
+  return Object.freeze({
+    query,
+    pages,
+    items,
+    isInitialLoading,
+    isFetching,
+    isRefetching,
+    isLoading,
+    isLoadingMore,
+    hasMore,
+    loadError,
+    reload,
+    loadMore
+  });
+}
+
+export { usePagedCollection };

package/src/client/composables/usePaths.js

@@ -0,0 +1,108 @@
+import { computed, unref } from "vue";
+import { normalizeText } from "@jskit-ai/kernel/shared/support/normalize";
+import { resolveApiBasePath } from "@jskit-ai/users-core/shared/support/usersApiPaths";
+import { useWorkspaceRouteContext } from "./useWorkspaceRouteContext.js";
+import { useWorkspaceLinkResolver } from "../lib/workspaceLinkResolver.js";
+import { surfaceRequiresWorkspaceFromPlacementContext } from "../lib/workspaceSurfaceContext.js";
+
+function normalizePathSuffix(value = "") {
+  const raw = normalizeText(unref(value));
+  if (!raw) {
+    return "";
+  }
+
+  return raw.startsWith("/") ? raw : `/${raw}`;
+}
+
+function resolveSurfaceId(value, fallback = "") {
+  const normalized = normalizeText(unref(value)).toLowerCase();
+  if (normalized && normalized !== "*") {
+    return normalized;
+  }
+
+  const normalizedFallback = normalizeText(unref(fallback)).toLowerCase();
+  if (normalizedFallback && normalizedFallback !== "*") {
+    return normalizedFallback;
+  }
+
+  return "";
+}
+
+function resolveWorkspaceSlug(value, fallback = "") {
+  const normalized = normalizeText(unref(value));
+  if (normalized) {
+    return normalized;
+  }
+
+  return normalizeText(unref(fallback));
+}
+
+function resolveDefaultSurfaceIdFromPlacementContext(placementContext = null) {
+  return resolveSurfaceId(placementContext?.surfaceConfig?.defaultSurfaceId, "");
+}
+
+function usePaths({ routeContext: sourceRouteContext = null } = {}) {
+  const routeContext = sourceRouteContext || useWorkspaceRouteContext();
+  const workspaceLinkResolver = useWorkspaceLinkResolver();
+  const workspaceSlug = computed(() => String(routeContext.workspaceSlugFromRoute.value || "").trim());
+
+  function page(relativePath = "/", options = {}) {
+    const source = options && typeof options === "object" && !Array.isArray(options) ? options : {};
+    const surface =
+      resolveSurfaceId(source.surface, routeContext.currentSurfaceId.value) ||
+      resolveDefaultSurfaceIdFromPlacementContext(routeContext.placementContext.value);
+    if (!surface) {
+      return "";
+    }
+    const nextWorkspaceSlug = resolveWorkspaceSlug(source.workspaceSlug, workspaceSlug.value);
+    const mode = normalizeText(source.mode).toLowerCase() || "auto";
+
+    return workspaceLinkResolver.resolve(relativePath, {
+      surface,
+      workspaceSlug: nextWorkspaceSlug,
+      mode
+    });
+  }
+
+  function api(relativePath = "", options = {}) {
+    const source = options && typeof options === "object" && !Array.isArray(options) ? options : {};
+    const surface =
+      resolveSurfaceId(source.surface, routeContext.currentSurfaceId.value) ||
+      resolveDefaultSurfaceIdFromPlacementContext(routeContext.placementContext.value);
+    const suffix = normalizePathSuffix(relativePath);
+    const workspaceScoped = surfaceRequiresWorkspaceFromPlacementContext(routeContext.placementContext.value, surface);
+
+    if (!suffix) {
+      throw new TypeError("usePaths().api(relativePath) requires a non-empty relativePath.");
+    }
+
+    const templatePath = resolveApiBasePath({
+      surfaceRequiresWorkspace: workspaceScoped,
+      relativePath: suffix
+    });
+
+    if (workspaceScoped) {
+      const nextWorkspaceSlug = resolveWorkspaceSlug(source.workspaceSlug, workspaceSlug.value);
+      if (!nextWorkspaceSlug) {
+        throw new Error(
+          `usePaths().api(${suffix}) requires workspace slug for workspace surface "${surface || "<unknown>"}".`
+        );
+      }
+
+      return templatePath.replace(":workspaceSlug", nextWorkspaceSlug);
+    }
+
+    return templatePath;
+  }
+
+  return Object.freeze({
+    route: routeContext.route,
+    placementContext: routeContext.placementContext,
+    currentSurfaceId: routeContext.currentSurfaceId,
+    workspaceSlug,
+    page,
+    api
+  });
+}
+
+export { usePaths };

package/src/client/composables/useRealtimeQueryInvalidation.js

@@ -0,0 +1,105 @@
+import { computed, unref } from "vue";
+import { useQueryClient } from "@tanstack/vue-query";
+import { normalizeText } from "@jskit-ai/kernel/shared/support/normalize";
+import { useRealtimeEvent } from "@jskit-ai/realtime/client/composables/useRealtimeEvent";
+
+function normalizeRealtimeOptions(value = {}) {
+  if (value === null || value === undefined || value === false) {
+    return {};
+  }
+  if (typeof value !== "object" || Array.isArray(value)) {
+    throw new TypeError("realtime must be an object when configured.");
+  }
+
+  return value;
+}
+
+function resolveEnabled(value) {
+  if (typeof value === "undefined") {
+    return true;
+  }
+
+  return Boolean(unref(value));
+}
+
+function toQueryKeyList(value) {
+  const resolved = typeof value === "function" ? value() : unref(value);
+  if (!Array.isArray(resolved) || resolved.length < 1) {
+    return [];
+  }
+
+  if (Array.isArray(resolved[0])) {
+    return resolved
+      .filter((entry) => Array.isArray(entry) && entry.length > 0)
+      .map((entry) => Object.freeze([...entry]));
+  }
+
+  return [Object.freeze([...resolved])];
+}
+
+function useRealtimeQueryInvalidation({
+  event = "",
+  enabled = true,
+  matches = null,
+  queryKey = null,
+  onEvent = null
+} = {}) {
+  const queryClient = useQueryClient();
+  const normalizedEvent = computed(() => normalizeText(unref(event)));
+  const active = computed(() => resolveEnabled(enabled) && Boolean(normalizedEvent.value));
+
+  const listener = useRealtimeEvent({
+    event: normalizedEvent,
+    enabled: active,
+    matches,
+    onEvent: async (context) => {
+      if (typeof onEvent === "function") {
+        await onEvent(context);
+      }
+
+      const keys = toQueryKeyList(queryKey);
+      for (const key of keys) {
+        await queryClient.invalidateQueries({
+          queryKey: key
+        });
+      }
+    }
+  });
+
+  return Object.freeze({
+    active: listener.active
+  });
+}
+
+function useOperationRealtime({
+  realtime = null,
+  queryKey = null,
+  enabled = true
+} = {}) {
+  const source = normalizeRealtimeOptions(realtime);
+  if (!source.event) {
+    return null;
+  }
+
+  const event = source.event;
+  const matches = typeof source.matches === "function" ? source.matches : null;
+  const onEvent = typeof source.onEvent === "function" ? source.onEvent : null;
+  const resolvedQueryKey = Object.hasOwn(source, "queryKey") ? source.queryKey : queryKey;
+  const active = computed(() => {
+    const sourceEnabled = Object.hasOwn(source, "enabled") ? source.enabled : true;
+    return resolveEnabled(enabled) && resolveEnabled(sourceEnabled);
+  });
+
+  return useRealtimeQueryInvalidation({
+    event,
+    enabled: active,
+    matches,
+    queryKey: resolvedQueryKey,
+    onEvent
+  });
+}
+
+export {
+  useRealtimeQueryInvalidation,
+  useOperationRealtime
+};

package/src/client/composables/useScopeRuntime.js

@@ -0,0 +1,107 @@
+import { computed } from "vue";
+import { normalizeSurfaceId } from "@jskit-ai/kernel/shared/surface/registry";
+import { USERS_ROUTE_VISIBILITY_WORKSPACE } from "@jskit-ai/users-core/shared/support/usersVisibility";
+import { useAccess } from "./useAccess.js";
+import { useWorkspaceRouteContext } from "./useWorkspaceRouteContext.js";
+import { usePaths } from "./usePaths.js";
+import { surfaceRequiresWorkspaceFromPlacementContext } from "../lib/workspaceSurfaceContext.js";
+import {
+  asPlainObject,
+  ensureAccessModeCompatibility,
+  resolveAccessModeEnabled,
+  normalizeOwnershipFilter,
+  resolveApiSuffix
+} from "./scopeHelpers.js";
+
+function useScopeRuntime({
+  ownershipFilter = USERS_ROUTE_VISIBILITY_WORKSPACE,
+  surfaceId = "",
+  accessMode = "auto",
+  hasPermissionRequirements = false,
+  placementSource = "users-web.scope-runtime"
+} = {}) {
+  const normalizedOwnershipFilter = normalizeOwnershipFilter(ownershipFilter);
+  const normalizedAccessMode = ensureAccessModeCompatibility({
+    accessMode,
+    hasPermissionRequirements,
+    caller: "useScopeRuntime"
+  });
+  const accessRequired = resolveAccessModeEnabled(normalizedAccessMode, {
+    hasPermissionRequirements
+  });
+  const routeContext = useWorkspaceRouteContext();
+  const paths = usePaths({
+    routeContext
+  });
+
+  const workspaceSlugFromRoute = routeContext.workspaceSlugFromRoute;
+  const resolvedSurfaceId = computed(() => {
+    const explicitSurfaceId = normalizeSurfaceId(surfaceId);
+    if (explicitSurfaceId) {
+      return explicitSurfaceId;
+    }
+
+    return normalizeSurfaceId(routeContext.currentSurfaceId.value);
+  });
+  const workspaceScoped = computed(() =>
+    surfaceRequiresWorkspaceFromPlacementContext(routeContext.placementContext.value, resolvedSurfaceId.value)
+  );
+  const hasRouteWorkspaceSlug = computed(() => (workspaceScoped.value ? Boolean(workspaceSlugFromRoute.value) : true));
+  const workspaceRouteError = computed(() => {
+    if (!workspaceScoped.value || hasRouteWorkspaceSlug.value) {
+      return "";
+    }
+
+    return `Route parameter workspaceSlug is required for surface "${resolvedSurfaceId.value || "<unknown>"}".`;
+  });
+
+  const accessRuntime = useAccess({
+    workspaceSlug: computed(() => (workspaceScoped.value ? workspaceSlugFromRoute.value : "")),
+    enabled: computed(() => accessRequired && hasRouteWorkspaceSlug.value),
+    access: normalizedAccessMode,
+    hasPermissionRequirements,
+    mergePlacementContext: accessRequired ? routeContext.mergePlacementContext : null,
+    placementSource: String(placementSource || "users-web.scope-runtime")
+  });
+
+  function resolveApiPath(apiSuffix = "", context = {}) {
+    if (workspaceRouteError.value) {
+      return "";
+    }
+
+    const suffix = resolveApiSuffix(apiSuffix, {
+      surfaceId: routeContext.currentSurfaceId.value,
+      workspaceSlug: workspaceSlugFromRoute.value,
+      ownershipFilter: normalizedOwnershipFilter,
+      ...asPlainObject(context)
+    });
+
+    return paths.api(suffix, {
+      surface: resolvedSurfaceId.value,
+      workspaceSlug: workspaceSlugFromRoute.value
+    });
+  }
+
+  function requireWorkspaceRouteParam(caller = "useScopeRuntime") {
+    if (workspaceRouteError.value) {
+      throw new Error(`${caller}: ${workspaceRouteError.value}`);
+    }
+  }
+
+  return Object.freeze({
+    normalizedOwnershipFilter,
+    workspaceScoped: workspaceScoped.value,
+    resolvedSurfaceId,
+    accessMode: normalizedAccessMode,
+    accessRequired,
+    routeContext,
+    workspaceSlugFromRoute,
+    hasRouteWorkspaceSlug,
+    workspaceRouteError,
+    access: accessRuntime,
+    resolveApiPath,
+    requireWorkspaceRouteParam
+  });
+}
+
+export { useScopeRuntime };

package/src/client/composables/useSurfaceRouteContext.js

@@ -0,0 +1,31 @@
+import { computed } from "vue";
+import { useRoute } from "vue-router";
+import {
+  resolveRuntimePathname,
+  resolveSurfaceIdFromPlacementPathname,
+  useWebPlacementContext
+} from "@jskit-ai/shell-web/client/placement";
+import { resolveWorkspaceSurfaceIdFromPlacementPathname } from "../lib/workspaceSurfacePaths.js";
+
+function useSurfaceRouteContext() {
+  const route = useRoute();
+  const { context: placementContext, mergeContext: mergePlacementContext } = useWebPlacementContext();
+  const routePath = computed(() => resolveRuntimePathname(route?.path));
+
+  const currentSurfaceId = computed(() => {
+    return (
+      resolveWorkspaceSurfaceIdFromPlacementPathname(placementContext.value, routePath.value) ||
+      resolveSurfaceIdFromPlacementPathname(placementContext.value, routePath.value)
+    );
+  });
+
+  return Object.freeze({
+    route,
+    routePath,
+    placementContext,
+    mergePlacementContext,
+    currentSurfaceId
+  });
+}
+
+export { useSurfaceRouteContext };

package/src/client/composables/useUiFeedback.js

@@ -0,0 +1,96 @@
+import { ref } from "vue";
+import { useShellWebErrorRuntime } from "@jskit-ai/shell-web/client/error";
+import { toUiErrorMessage } from "./errorMessageHelpers.js";
+
+function useUiFeedback({
+  initialType = "success",
+  source = "users-web.ui-feedback",
+  successChannel = "snackbar",
+  errorChannel = "banner",
+  dedupeWindowMs = 2000
+} = {}) {
+  const message = ref("");
+  const messageType = ref(String(initialType || "success"));
+  const errorRuntime = useShellWebErrorRuntime();
+  const normalizedSource = String(source || "").trim() || "users-web.ui-feedback";
+  let lastErrorPresentation = null;
+
+  function rememberErrorPresentation(reportResult = null) {
+    const presentationId = String(reportResult?.presentationId || "").trim();
+    const presenterId = String(reportResult?.decision?.presenterId || "").trim();
+    if (!presentationId || !presenterId) {
+      return;
+    }
+
+    lastErrorPresentation = Object.freeze({
+      presentationId,
+      presenterId
+    });
+  }
+
+  function dismissLastErrorPresentation() {
+    if (!lastErrorPresentation) {
+      return;
+    }
+
+    errorRuntime.dismiss(lastErrorPresentation.presentationId, {
+      presenterId: lastErrorPresentation.presenterId
+    });
+    lastErrorPresentation = null;
+  }
+
+  function clear() {
+    message.value = "";
+  }
+
+  function success(nextMessage = "") {
+    messageType.value = "success";
+    const normalizedMessage = String(nextMessage || "").trim();
+    message.value = normalizedMessage;
+    dismissLastErrorPresentation();
+    if (!normalizedMessage) {
+      return;
+    }
+
+    errorRuntime.report({
+      source: normalizedSource,
+      message: normalizedMessage,
+      severity: "success",
+      channel: successChannel,
+      dedupeKey: `${normalizedSource}:success:${normalizedMessage}`,
+      dedupeWindowMs
+    });
+  }
+
+  function error(errorValue, fallbackMessage = "") {
+    messageType.value = "error";
+    message.value = toUiErrorMessage(errorValue, fallbackMessage, "Request failed.");
+    if (!message.value) {
+      return;
+    }
+
+    const reportResult = errorRuntime.report({
+      source: normalizedSource,
+      message: message.value,
+      cause: errorValue || null,
+      severity: "error",
+      channel: errorChannel,
+      dedupeKey: `${normalizedSource}:error:${message.value}`,
+      dedupeWindowMs
+    });
+
+    if (!reportResult?.skipped) {
+      rememberErrorPresentation(reportResult);
+    }
+  }
+
+  return Object.freeze({
+    message,
+    messageType,
+    clear,
+    success,
+    error
+  });
+}
+
+export { useUiFeedback };