@jskit-ai/users-web 0.1.4

package/src/client/composables/modelStateHelpers.js

@@ -0,0 +1,49 @@
+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;
+  }
+}
+
+export {
+  captureModelSnapshot,
+  restoreModelSnapshot
+};

package/src/client/composables/operationUiHelpers.js

@@ -0,0 +1,121 @@
+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 = "users-web.operation",
+  loadError = null,
+  notFoundError = null,
+  loadActionFactory = null,
+  notFoundActionFactory = null,
+  loadChannel = "banner",
+  notFoundChannel = "banner",
+  loadSeverity = "error",
+  notFoundSeverity = "warning",
+  dedupeWindowMs = 2000
+} = {}) {
+  if (!enabled) {
+    return;
+  }
+
+  const runtime = useShellWebErrorRuntime();
+  const normalizedSource = normalizeMessage(source) || "users-web.operation";
+
+  function watchMessage(value, {
+    kind = "load",
+    channel = "banner",
+    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,
+          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,
+      severity: loadSeverity,
+      actionFactory: loadActionFactory
+    });
+  }
+
+  if (notFoundError) {
+    watchMessage(notFoundError, {
+      kind: "not-found",
+      channel: notFoundChannel,
+      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/operationValidationHelpers.js

@@ -0,0 +1,52 @@
+import {
+  createValidationFailure,
+  resolveFieldErrors
+} from "@jskit-ai/http-runtime/client";
+
+function validateOperationInput({
+  parseInput,
+  rawPayload = {},
+  context = {},
+  fieldBag = null,
+  feedback = null,
+  validationMessage = "Validation failed."
+} = {}) {
+  if (typeof parseInput !== "function") {
+    return {
+      ok: true,
+      parseResult: null,
+      parsedInput: rawPayload
+    };
+  }
+
+  const parseResult = parseInput(rawPayload, context);
+  if (!parseResult || typeof parseResult !== "object" || typeof parseResult.ok !== "boolean") {
+    throw new TypeError(
+      "parseInput(rawPayload, context) must return validateOperationSection-compatible result with boolean ok."
+    );
+  }
+
+  if (!parseResult.ok) {
+    const failure = createValidationFailure({
+      error: String(validationMessage || "Validation failed."),
+      code: "validation_failed",
+      fieldErrors: parseResult.fieldErrors
+    });
+    fieldBag?.apply?.(resolveFieldErrors(failure));
+    feedback?.error?.(failure, failure.error);
+    return {
+      ok: false,
+      failure,
+      parseResult,
+      parsedInput: null
+    };
+  }
+
+  return {
+    ok: true,
+    parseResult,
+    parsedInput: parseResult.value
+  };
+}
+
+export { validateOperationInput };

package/src/client/composables/refValueHelpers.js

@@ -0,0 +1,19 @@
+import { unref } from "vue";
+
+function resolveEnabledRef(value) {
+  if (value === undefined) {
+    return true;
+  }
+
+  if (typeof value === "function") {
+    return Boolean(value());
+  }
+
+  return Boolean(unref(value));
+}
+
+function resolveTextRef(value) {
+  return String(unref(value) || "").trim();
+}
+
+export { resolveEnabledRef, resolveTextRef };

package/src/client/composables/scopeHelpers.js

@@ -0,0 +1,145 @@
+import { resolveEnabledRef, resolveTextRef } from "./refValueHelpers.js";
+import {
+  USERS_ROUTE_VISIBILITY_LEVELS,
+  USERS_ROUTE_VISIBILITY_WORKSPACE,
+  USERS_ROUTE_VISIBILITY_WORKSPACE_USER
+} from "@jskit-ai/users-core/shared/support/usersVisibility";
+
+const USERS_OWNERSHIP_FILTER_VALUES = USERS_ROUTE_VISIBILITY_LEVELS;
+const WORKSPACE_OWNERSHIP_FILTER_SET = new Set([
+  USERS_ROUTE_VISIBILITY_WORKSPACE,
+  USERS_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 = "users-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 = USERS_ROUTE_VISIBILITY_WORKSPACE) {
+  const normalized = String(value || USERS_ROUTE_VISIBILITY_WORKSPACE).trim().toLowerCase();
+  if (USERS_OWNERSHIP_FILTER_VALUES.includes(normalized)) {
+    return normalized;
+  }
+
+  throw new TypeError(
+    `ownershipFilter must be one of: ${USERS_OWNERSHIP_FILTER_VALUES.join(", ")}. Received: ${String(value || "") || "(empty)"}`
+  );
+}
+
+function isWorkspaceOwnershipFilter(ownershipFilter) {
+  return WORKSPACE_OWNERSHIP_FILTER_SET.has(ownershipFilter);
+}
+
+function resolveQueryKey(
+  queryKeyFactory,
+  { surfaceId = "", workspaceSlug = "", ownershipFilter = USERS_ROUTE_VISIBILITY_WORKSPACE } = {}
+) {
+  if (typeof queryKeyFactory !== "function") {
+    throw new TypeError("queryKeyFactory is required.");
+  }
+
+  if (isWorkspaceOwnershipFilter(ownershipFilter)) {
+    return queryKeyFactory(surfaceId, workspaceSlug, 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,
+  isWorkspaceOwnershipFilter,
+  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 "./refValueHelpers.js";
+import {
+  normalizeAccessMode,
+  resolveAccessModeEnabled
+} from "./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({
+  workspaceSlug = "",
+  enabled = true,
+  access = "always",
+  hasPermissionRequirements = false
+} = {}) {
+  const normalizedAccessMode = normalizeAccessMode(access);
+  const accessRequired = resolveAccessModeEnabled(normalizedAccessMode, {
+    hasPermissionRequirements: hasPermissionRequirements === true
+  });
+  const { context: placementContext } = useWebPlacementContext();
+  const normalizedWorkspaceSlug = computed(() => resolveTextRef(workspaceSlug));
+  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,
+    workspaceSlug: normalizedWorkspaceSlug,
+    permissions,
+    bootstrapError,
+    isBootstrapping,
+    can,
+    canAny,
+    canAll,
+    refreshBootstrap
+  });
+}
+
+export { useAccess };