@jskit-ai/http-web 0.1.1

package/src/client/composables/usePagedCollection.js

@@ -0,0 +1,181 @@
+import { computed, unref } from "vue";
+import { useInfiniteQuery, useQueryClient } from "@tanstack/vue-query";
+import { asPlainObject } from "./support/scopeHelpers.js";
+import { resolveEnabledRef } from "./support/refValueHelpers.js";
+import { toQueryErrorMessage } from "./support/errorMessageHelpers.js";
+import { mergeQueryMeta } from "./support/resourceLoadStateHelpers.js";
+
+function defaultSelectItems(page) {
+  return Array.isArray(page?.items) ? page.items : [];
+}
+
+function defaultGetNextPageParam(lastPage) {
+  return lastPage?.nextCursor ?? null;
+}
+
+function normalizeQueryKeyValue(queryKey = null) {
+  const resolved = unref(queryKey);
+  if (Array.isArray(resolved)) {
+    return resolved;
+  }
+  if (resolved === null || resolved === undefined || resolved === "") {
+    return [];
+  }
+
+  return [resolved];
+}
+
+function trimInfinitePagesToFirst(data = null) {
+  if (!data || typeof data !== "object" || Array.isArray(data)) {
+    return data;
+  }
+
+  const sourcePages = Array.isArray(data.pages) ? data.pages : [];
+  const sourcePageParams = Array.isArray(data.pageParams) ? data.pageParams : [];
+  if (sourcePages.length < 2 && sourcePageParams.length < 2) {
+    return data;
+  }
+  const pages = sourcePages.slice(0, 1);
+  const pageParams = sourcePageParams.length > 0
+    ? sourcePageParams.slice(0, 1)
+    : pages.length > 0
+      ? [null]
+      : [];
+
+  return {
+    ...data,
+    pages,
+    pageParams
+  };
+}
+
+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 queryClient = useQueryClient();
+  const queryEnabled = computed(() => resolveEnabledRef(enabled));
+  const normalizedQueryKey = computed(() => normalizeQueryKeyValue(queryKey));
+
+  const query = useInfiniteQuery({
+    queryKey,
+    initialPageParam,
+    enabled: queryEnabled,
+    queryFn,
+    getNextPageParam: (lastPage, allPages, lastPageParam, allPageParams) =>
+      getNextPageParam(lastPage, allPages, lastPageParam, allPageParams),
+    ...mergeQueryMeta(asPlainObject(queryOptions), {
+      jskit: {
+        refreshOnPull: true
+      }
+    })
+  });
+
+  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();
+  }
+
+  function trimToFirstPage() {
+    const key = normalizedQueryKey.value;
+    if (key.length < 1) {
+      return;
+    }
+
+    queryClient.setQueryData(key, (data) => trimInfinitePagesToFirst(data));
+  }
+
+  return Object.freeze({
+    query,
+    pages,
+    items,
+    isInitialLoading,
+    isFetching,
+    isRefetching,
+    isLoading,
+    isLoadingMore,
+    hasMore,
+    loadError,
+    reload,
+    loadMore,
+    trimToFirstPage
+  });
+}
+
+export {
+  usePagedCollection,
+  trimInfinitePagesToFirst
+};

package/src/client/composables/useRealtimeQueryInvalidation.js

@@ -0,0 +1,156 @@
+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 hasRealtimeEventConfig(value = {}) {
+  const source = normalizeRealtimeOptions(value);
+  return Object.hasOwn(source, "event") || Object.hasOwn(source, "events");
+}
+
+function resolveOperationRealtimeOptions({
+  realtime = undefined,
+  fallbackRealtime = null
+} = {}) {
+  if (realtime === false) {
+    return null;
+  }
+
+  const fallback = normalizeRealtimeOptions(fallbackRealtime);
+  const explicit = realtime == null ? {} : normalizeRealtimeOptions(realtime);
+  if (hasRealtimeEventConfig(explicit) || !hasRealtimeEventConfig(fallback)) {
+    return Object.keys(explicit).length > 0 ? explicit : null;
+  }
+
+  return Object.freeze({
+    ...fallback,
+    ...explicit
+  });
+}
+
+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);
+  const eventList = [];
+  if (Object.hasOwn(source, "event")) {
+    const normalizedEvent = normalizeText(source.event);
+    if (normalizedEvent) {
+      eventList.push(normalizedEvent);
+    }
+  }
+  if (Object.hasOwn(source, "events")) {
+    if (!Array.isArray(source.events)) {
+      throw new TypeError("realtime.events must be an array when configured.");
+    }
+    for (const entry of source.events) {
+      const normalizedEvent = normalizeText(entry);
+      if (!normalizedEvent || eventList.includes(normalizedEvent)) {
+        continue;
+      }
+      eventList.push(normalizedEvent);
+    }
+  }
+
+  if (eventList.length < 1) {
+    return null;
+  }
+
+  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);
+  });
+
+  const bindings = eventList.map((event) =>
+    useRealtimeQueryInvalidation({
+      event,
+      enabled: active,
+      matches,
+      queryKey: resolvedQueryKey,
+      onEvent
+    })
+  );
+
+  return Object.freeze({
+    active: computed(() => bindings.some((binding) => Boolean(binding?.active?.value)))
+  });
+}
+
+export {
+  resolveOperationRealtimeOptions,
+  useRealtimeQueryInvalidation,
+  useOperationRealtime
+};

package/src/client/composables/useScopeRuntime.js

@@ -0,0 +1,135 @@
+import { computed } from "vue";
+import { normalizeSurfaceId, resolveScopedRouteBase } from "@jskit-ai/kernel/shared/surface";
+import {
+  ROUTE_VISIBILITY_WORKSPACE
+} from "@jskit-ai/kernel/shared/support/visibility";
+import { useAccess } from "./useAccess.js";
+import { usePaths } from "@jskit-ai/shell-web/client/navigation/usePaths";
+import { useSurfaceRouteContext } from "@jskit-ai/shell-web/client/navigation/useSurfaceRouteContext";
+import { resolveSurfaceDefinitionFromPlacementContext } from "@jskit-ai/shell-web/client/placement";
+import {
+  asPlainObject,
+  ensureAccessModeCompatibility,
+  resolveAccessModeEnabled,
+  normalizeOwnershipFilter,
+  resolveApiSuffix
+} from "./support/scopeHelpers.js";
+import { extractRouteParamNames, toRouteParamValue } from "./support/routeTemplateHelpers.js";
+
+function resolveScopedRouteParamNames(placementContext = null, surfaceId = "") {
+  const routeBase = resolveSurfaceDefinitionFromPlacementContext(placementContext, surfaceId)?.routeBase || "/";
+  return extractRouteParamNames(resolveScopedRouteBase(routeBase));
+}
+
+function useScopeRuntime({
+  ownershipFilter = ROUTE_VISIBILITY_WORKSPACE,
+  surfaceId = "",
+  accessMode = "auto",
+  hasPermissionRequirements = false,
+  placementSource = "http-web.scope-runtime"
+} = {}) {
+  const normalizedOwnershipFilter = normalizeOwnershipFilter(ownershipFilter);
+  const normalizedAccessMode = ensureAccessModeCompatibility({
+    accessMode,
+    hasPermissionRequirements,
+    caller: "useScopeRuntime"
+  });
+  const accessRequired = resolveAccessModeEnabled(normalizedAccessMode, {
+    hasPermissionRequirements
+  });
+  const routeContext = useSurfaceRouteContext();
+  const paths = usePaths({
+    routeContext
+  });
+
+  const resolvedSurfaceId = computed(() => {
+    const explicitSurfaceId = normalizeSurfaceId(surfaceId);
+    if (explicitSurfaceId) {
+      return explicitSurfaceId;
+    }
+
+    return normalizeSurfaceId(routeContext.currentSurfaceId.value);
+  });
+  const scopedRouteParamNames = computed(() =>
+    resolveScopedRouteParamNames(routeContext.placementContext.value, resolvedSurfaceId.value)
+  );
+  const routeScopeParams = computed(() => {
+    const source = paths.routeParams.value;
+    const next = {};
+    for (const paramName of scopedRouteParamNames.value) {
+      const paramValue = toRouteParamValue(source[paramName]);
+      if (paramValue) {
+        next[paramName] = paramValue;
+      }
+    }
+    return Object.freeze(next);
+  });
+  const missingScopedRouteParamNames = computed(() =>
+    scopedRouteParamNames.value.filter((paramName) => !routeScopeParams.value[paramName])
+  );
+  const requiresScopedRouteParams = computed(() => scopedRouteParamNames.value.length > 0);
+  const hasRequiredRouteScope = computed(() => missingScopedRouteParamNames.value.length < 1);
+  const scopeParamValue = computed(() => {
+    const [primaryScopeParamName = ""] = scopedRouteParamNames.value;
+    return primaryScopeParamName ? routeScopeParams.value[primaryScopeParamName] || "" : "";
+  });
+  const routeScopeError = computed(() => {
+    if (!requiresScopedRouteParams.value || hasRequiredRouteScope.value) {
+      return "";
+    }
+
+    const missingParams = missingScopedRouteParamNames.value.join(", ");
+    return `Route parameters ${missingParams} are required for surface "${resolvedSurfaceId.value || "<unknown>"}".`;
+  });
+
+  const accessRuntime = useAccess({
+    scopeParamValue,
+    enabled: computed(() => accessRequired && hasRequiredRouteScope.value),
+    access: normalizedAccessMode,
+    hasPermissionRequirements,
+    placementSource: String(placementSource || "http-web.scope-runtime")
+  });
+
+  function resolveApiPath(apiSuffix = "", context = {}) {
+    if (routeScopeError.value) {
+      return "";
+    }
+
+    const suffix = resolveApiSuffix(apiSuffix, {
+      surfaceId: routeContext.currentSurfaceId.value,
+      scopeParamValue: scopeParamValue.value,
+      ownershipFilter: normalizedOwnershipFilter,
+      ...asPlainObject(context)
+    });
+
+    return paths.api(suffix, {
+      surface: resolvedSurfaceId.value,
+      params: routeScopeParams.value
+    });
+  }
+
+  function requireRouteScope(caller = "useScopeRuntime") {
+    if (routeScopeError.value) {
+      throw new Error(`${caller}: ${routeScopeError.value}`);
+    }
+  }
+
+  return Object.freeze({
+    normalizedOwnershipFilter,
+    requiresScopedRouteParams: requiresScopedRouteParams.value,
+    resolvedSurfaceId,
+    accessMode: normalizedAccessMode,
+    accessRequired,
+    routeContext,
+    scopedRouteParamNames,
+    routeScopeParams,
+    scopeParamValue,
+    hasRequiredRouteScope,
+    routeScopeError,
+    access: accessRuntime,
+    resolveApiPath,
+    requireRouteScope
+  });
+}
+
+export { useScopeRuntime };

package/src/client/filters.js

@@ -0,0 +1,15 @@
+export {
+  CRUD_LIST_FILTER_TYPE_FLAG,
+  CRUD_LIST_FILTER_TYPE_ENUM,
+  CRUD_LIST_FILTER_TYPE_ENUM_MANY,
+  CRUD_LIST_FILTER_TYPE_RECORD_ID,
+  CRUD_LIST_FILTER_TYPE_RECORD_ID_MANY,
+  CRUD_LIST_FILTER_TYPE_DATE,
+  CRUD_LIST_FILTER_TYPE_DATE_RANGE,
+  CRUD_LIST_FILTER_TYPE_NUMBER_RANGE,
+  CRUD_LIST_FILTER_TYPE_PRESENCE,
+  CRUD_LIST_FILTER_PRESENCE_PRESENT,
+  CRUD_LIST_FILTER_PRESENCE_MISSING,
+  CRUD_LIST_FILTER_PRESENCE_OPTIONS,
+  defineCrudListFilters
+} from "@jskit-ai/resource-crud-core/shared/crudListFilters";

package/src/client/index.js

@@ -0,0 +1,24 @@
+export { default as CrudAddEditScreen } from "./components/CrudAddEditScreen.vue";
+export { default as CrudDeleteAction } from "./components/CrudDeleteAction.vue";
+export { default as CrudListBulkActionSurface } from "./components/CrudListBulkActionSurface.vue";
+export { default as CrudListFilterSurface } from "./components/CrudListFilterSurface.vue";
+export { default as CrudListScreen } from "./components/CrudListScreen.vue";
+export { default as CrudViewScreen } from "./components/CrudViewScreen.vue";
+export { defineCrudListBulkActions } from "./bulkActions.js";
+export { defineCrudListFilters } from "./filters.js";
+export { defineCrudListRowActions } from "./rowActions.js";
+export { useAddEdit } from "./composables/records/useAddEdit.js";
+export { useAccess } from "./composables/useAccess.js";
+export { useCommand } from "./composables/useCommand.js";
+export { useEndpointResource } from "./composables/runtime/useEndpointResource.js";
+export { useList } from "./composables/records/useList.js";
+export { usePagedCollection } from "./composables/usePagedCollection.js";
+export { useRealtimeQueryInvalidation } from "./composables/useRealtimeQueryInvalidation.js";
+export { useUiFeedback } from "./composables/runtime/useUiFeedback.js";
+export { useView } from "./composables/records/useView.js";
+export {
+  configureHttpWebClient,
+  createHttpWebClient,
+  getHttpWebClient,
+  httpWebClient
+} from "./lib/httpClient.js";

package/src/client/lib/httpClient.js

@@ -0,0 +1,47 @@
+import { createTransientRetryHttpClient } from "@jskit-ai/http-runtime/client";
+
+function normalizeOptions(value = null) {
+  return value && typeof value === "object" && !Array.isArray(value) ? value : {};
+}
+
+function createHttpWebClient(options = {}) {
+  const source = normalizeOptions(options);
+  const sourceCsrf = normalizeOptions(source.csrf);
+
+  return createTransientRetryHttpClient({
+    ...source,
+    credentials: source.credentials ?? "include",
+    csrf: {
+      sessionPath: "/api/session",
+      ...sourceCsrf
+    }
+  });
+}
+
+let httpWebClient = createHttpWebClient();
+
+function configureHttpWebClient(optionsOrClient = {}) {
+  const source = normalizeOptions(optionsOrClient);
+  httpWebClient =
+    typeof source.request === "function"
+      ? source
+      : createHttpWebClient(source);
+  return httpWebClient;
+}
+
+function getHttpWebClient() {
+  return httpWebClient;
+}
+
+function resetHttpWebClientForTests() {
+  httpWebClient = createHttpWebClient();
+  return httpWebClient;
+}
+
+export {
+  configureHttpWebClient,
+  createHttpWebClient,
+  getHttpWebClient,
+  resetHttpWebClientForTests,
+  httpWebClient
+};

package/src/client/lib/permissions.js

@@ -0,0 +1,34 @@
+import {
+  hasPermission,
+  normalizePermissionList
+} from "@jskit-ai/kernel/shared/support";
+
+function toPermissionSet(values) {
+  const normalized = normalizePermissionList(values);
+  if (normalized.length < 1) {
+    return new Set();
+  }
+  return new Set(normalized);
+}
+
+function arePermissionListsEqual(left, right) {
+  const leftSet = toPermissionSet(left);
+  const rightSet = toPermissionSet(right);
+  if (leftSet.size !== rightSet.size) {
+    return false;
+  }
+
+  for (const permission of leftSet) {
+    if (!rightSet.has(permission)) {
+      return false;
+    }
+  }
+
+  return true;
+}
+
+export {
+  normalizePermissionList,
+  arePermissionListsEqual,
+  hasPermission
+};

package/src/client/rowActions.js

@@ -0,0 +1,47 @@
+import { normalizeText } from "@jskit-ai/kernel/shared/support/normalize";
+
+function normalizeCrudListRowAction(rawAction = {}, index = 0) {
+  if (!rawAction || typeof rawAction !== "object" || Array.isArray(rawAction)) {
+    return null;
+  }
+
+  const key = normalizeText(rawAction.key || rawAction.id || `action-${index + 1}`);
+  const label = normalizeText(rawAction.label || rawAction.title);
+  if (!key || !label) {
+    return null;
+  }
+
+  return Object.freeze({
+    key,
+    label,
+    icon: normalizeText(rawAction.icon),
+    color: normalizeText(rawAction.color, { fallback: "primary" }),
+    run: typeof rawAction.run === "function" ? rawAction.run : null,
+    visible: rawAction.visible,
+    disabled: rawAction.disabled,
+    loading: rawAction.loading
+  });
+}
+
+function defineCrudListRowActions(actions = []) {
+  if (!Array.isArray(actions)) {
+    throw new TypeError("defineCrudListRowActions requires an array.");
+  }
+
+  const normalizedActions = [];
+  const seenKeys = new Set();
+
+  actions.forEach((rawAction, index) => {
+    const action = normalizeCrudListRowAction(rawAction, index);
+    if (!action || seenKeys.has(action.key)) {
+      return;
+    }
+
+    seenKeys.add(action.key);
+    normalizedActions.push(action);
+  });
+
+  return Object.freeze(normalizedActions);
+}
+
+export { defineCrudListRowActions };

package/src/client/support/contractGuards.js

@@ -0,0 +1,34 @@
+import { unref } from "vue";
+
+function requireRecord(value, label = "value", owner = "Contract") {
+  const resolved = unref(value);
+  if (!resolved || typeof resolved !== "object" || Array.isArray(resolved)) {
+    throw new TypeError(`${owner} expects ${label} to be an object.`);
+  }
+
+  return resolved;
+}
+
+function requireBoolean(value, label = "value", owner = "Contract") {
+  const resolved = unref(value);
+  if (typeof resolved !== "boolean") {
+    throw new TypeError(`${owner} expects ${label} to be a boolean.`);
+  }
+
+  return resolved;
+}
+
+function requireFunction(value, label = "value", owner = "Contract") {
+  const resolved = unref(value);
+  if (typeof resolved !== "function") {
+    throw new TypeError(`${owner} expects ${label} to be a function.`);
+  }
+
+  return resolved;
+}
+
+export {
+  requireRecord,
+  requireBoolean,
+  requireFunction
+};