@jskit-ai/shell-web 0.1.250 → 0.1.252

package/src/client/requestRecovery/runtime.js

@@ -1,8 +1,8 @@
 import { guardedReloadApp } from "@jskit-ai/kernel/client/asyncModuleRecovery";
-import { isRecord } from "@jskit-ai/kernel/shared/support";
+import { isRecord, normalizeText } from "@jskit-ai/kernel/shared/support/normalize";
 import { createProviderLogger as createSharedProviderLogger } from "@jskit-ai/kernel/shared/support/providerLogger";
 
-const REQUEST_RECOVERY_RELOAD_FAILURE_MESSAGE =
+const APP_RELOAD_FAILURE_MESSAGE =
   "The app cannot reload because the app server is not reachable. Restart the server, then click Reload.";
 
 const RECOVERABLE_REQUEST_ERROR_MESSAGES = Object.freeze([
@@ -36,11 +36,6 @@ const SAFE_REQUEST_RECOVERY_METHODS = Object.freeze(new Set([
   "HEAD"
 ]));
 
-function normalizeText(value, fallback = "") {
-  const normalized = String(value || "").trim();
-  return normalized || String(fallback || "").trim();
-}
-
 function errorMessage(error = null) {
   return normalizeText(error?.message || error?.cause?.message || error);
 }
@@ -106,7 +101,7 @@ function requestRecoveryMessage(error = null, {
     return explicitMessage;
   }
 
-  const requestLabel = normalizeText(label, "Request");
+  const requestLabel = normalizeText(label, { fallback: "Request" });
   if (requestLabel === "Request") {
     return "The app could not reach the server or network. Check the connection and try again.";
   }
@@ -123,59 +118,19 @@ function resolveQueryMeta(query = null) {
   return {};
 }
 
-function isRequestRecoveryDisabled(query = null) {
-  const meta = resolveQueryMeta(query);
-  const jskitMeta = isRecord(meta.jskit) ? meta.jskit : {};
-  return jskitMeta.requestRecovery === false;
-}
-
-function resolveQueryRecoveryLabel(query = null) {
-  const meta = resolveQueryMeta(query);
-  const jskitMeta = isRecord(meta.jskit) ? meta.jskit : {};
-
-  return normalizeText(
-    jskitMeta.requestRecoveryLabel,
-    "Request"
-  );
-}
-
-function resolveQueryRecoverySource(query = null) {
-  const meta = resolveQueryMeta(query);
-  const jskitMeta = isRecord(meta.jskit) ? meta.jskit : {};
-
-  return normalizeText(
-    jskitMeta.requestRecoverySource,
-    "shell-web.request-recovery.query"
-  );
-}
-
-function resolveQueryRecoveryDedupeKey(query = null, fallback = "") {
+function readQueryRecoveryMeta(query = null) {
   const meta = resolveQueryMeta(query);
   const jskitMeta = isRecord(meta.jskit) ? meta.jskit : {};
+  const dedupeWindowMs = jskitMeta.requestRecoveryDedupeWindowMs;
 
-  return normalizeText(
-    jskitMeta.requestRecoveryDedupeKey,
-    fallback
-  );
-}
-
-function resolveQueryRecoveryDedupeWindowMs(query = null) {
-  const meta = resolveQueryMeta(query);
-  const jskitMeta = isRecord(meta.jskit) ? meta.jskit : {};
-  const value = jskitMeta.requestRecoveryDedupeWindowMs;
-
-  return Number.isFinite(Number(value)) ? Math.max(0, Number(value)) : null;
-}
-
-function resolveQueryRecoveryMethod(query = null) {
-  const meta = resolveQueryMeta(query);
-  const jskitMeta = isRecord(meta.jskit) ? meta.jskit : {};
-
-  return normalizeText(jskitMeta.requestRecoveryMethod).toUpperCase();
-}
-
-function isSafeQueryRecoveryMethod(query = null) {
-  return SAFE_REQUEST_RECOVERY_METHODS.has(resolveQueryRecoveryMethod(query));
+  return Object.freeze({
+    disabled: jskitMeta.requestRecovery === false,
+    label: normalizeText(jskitMeta.requestRecoveryLabel, { fallback: "Request" }),
+    source: normalizeText(jskitMeta.requestRecoverySource, { fallback: "shell-web.request-recovery.query" }),
+    dedupeKey: normalizeText(jskitMeta.requestRecoveryDedupeKey),
+    dedupeWindowMs: Number.isFinite(Number(dedupeWindowMs)) ? Math.max(0, Number(dedupeWindowMs)) : null,
+    method: normalizeText(jskitMeta.requestRecoveryMethod).toUpperCase()
+  });
 }
 
 function isActiveQuery(query = null) {
@@ -273,10 +228,11 @@ function installRecoverableQueryObserver({
 
   function inspectQuery(query = null) {
     const queryHash = resolveQueryHash(query);
+    const recoveryMeta = readQueryRecoveryMeta(query);
     if (
       !query ||
-      isRequestRecoveryDisabled(query) ||
-      !isSafeQueryRecoveryMethod(query) ||
+      recoveryMeta.disabled ||
+      !SAFE_REQUEST_RECOVERY_METHODS.has(recoveryMeta.method) ||
       !isActiveQuery(query)
     ) {
       if (queryHash) {
@@ -300,18 +256,13 @@ function installRecoverableQueryObserver({
       return;
     }
 
-    const source = resolveQueryRecoverySource(query);
-    const dedupeKey = resolveQueryRecoveryDedupeKey(
-      query,
-      `shell-web.request-recovery.query.${queryHash}.${errorUpdateCount}`
-    );
-    const dedupeWindowMs = resolveQueryRecoveryDedupeWindowMs(query);
+    const { dedupeWindowMs } = recoveryMeta;
     const result = runtime.report(error, {
-      label: resolveQueryRecoveryLabel(query),
+      label: recoveryMeta.label,
       retry: createQueryRetry(queryClient, query),
-      source,
+      source: recoveryMeta.source,
       stale: query?.state?.data !== undefined,
-      dedupeKey,
+      dedupeKey: recoveryMeta.dedupeKey || `shell-web.request-recovery.query.${queryHash}.${errorUpdateCount}`,
       ...(dedupeWindowMs !== null ? { dedupeWindowMs } : {})
     });
 
@@ -376,7 +327,7 @@ function createShellRequestRecoveryRuntime({
 
   async function reload({
     label = "App",
-    message = REQUEST_RECOVERY_RELOAD_FAILURE_MESSAGE
+    message = APP_RELOAD_FAILURE_MESSAGE
   } = {}) {
     const reloaded = await guardedReloadApp({
       label,
@@ -396,9 +347,9 @@ function createShellRequestRecoveryRuntime({
     return reloaded;
   }
 
-  function retryAction(error, options, retry) {
+  function retryAction(options, retry) {
     return {
-      label: normalizeText(options.actionLabel, "Retry"),
+      label: normalizeText(options.actionLabel, { fallback: "Retry" }),
       dismissOnRun: true,
       async handler() {
         try {
@@ -415,12 +366,12 @@ function createShellRequestRecoveryRuntime({
 
   function reloadAction(options) {
     return {
-      label: normalizeText(options.actionLabel, "Reload"),
+      label: normalizeText(options.actionLabel, { fallback: "Reload" }),
       dismissOnRun: true,
       handler() {
         return reload({
           label: options.label,
-          message: options.reloadFailureMessage || REQUEST_RECOVERY_RELOAD_FAILURE_MESSAGE
+          message: options.reloadFailureMessage || APP_RELOAD_FAILURE_MESSAGE
         });
       }
     };
@@ -438,7 +389,7 @@ function createShellRequestRecoveryRuntime({
       return null;
     }
 
-    const source = normalizeText(options.source, "shell-web.request-recovery");
+    const source = normalizeText(options.source, { fallback: "shell-web.request-recovery" });
     if (!errorRuntime || typeof errorRuntime.report !== "function") {
       runtimeLogger.warn(
         {
@@ -452,7 +403,7 @@ function createShellRequestRecoveryRuntime({
 
     const retry = typeof options.retry === "function" ? options.retry : null;
     const action = retry
-      ? retryAction(error, options, retry)
+      ? retryAction(options, retry)
       : options.reload === true
         ? reloadAction(options)
         : null;
@@ -463,7 +414,7 @@ function createShellRequestRecoveryRuntime({
         message: requestRecoveryMessage(error, options),
         cause: error || null,
         intent: "app-recoverable",
-        severity: normalizeText(options.severity, options.stale ? "warning" : "error"),
+        severity: normalizeText(options.severity, { fallback: options.stale ? "warning" : "error" }),
         dedupeKey: normalizeText(options.dedupeKey),
         dedupeWindowMs: Number.isFinite(Number(options.dedupeWindowMs))
           ? Math.max(0, Number(options.dedupeWindowMs))
@@ -513,6 +464,7 @@ function createShellRequestRecoveryRuntime({
 }
 
 export {
+  APP_RELOAD_FAILURE_MESSAGE,
   createShellRequestRecoveryRuntime,
   isRecoverableRequestError,
   requestRecoveryMessage

package/src/client/runtime/bootstrapRuntime.js

@@ -139,10 +139,11 @@ function createShellBootstrapRuntime({
       throw new Error("Bootstrap payload fetch requires a fetch implementation.");
     }
 
-    const request = await resolveBootstrapRequest(reason);
-    const url = buildBootstrapUrl(request);
+    let request = Object.freeze({ path: bootstrapPath, query: Object.freeze({}), meta: Object.freeze({}) });
 
     try {
+      request = await resolveBootstrapRequest(reason);
+      const url = buildBootstrapUrl(request);
       const response = await fetchImplementation(url, {
         method: "GET",
         credentials: "include",
@@ -156,7 +157,7 @@ function createShellBootstrapRuntime({
       }
 
       const payload = await response.json();
-      return applyBootstrapPayload(payload, reason, request);
+      return await applyBootstrapPayload(payload, reason, request);
     } catch (error) {
       await applyBootstrapError(error, reason, request);
       requestRecoveryRuntime?.report?.(error, {
@@ -177,7 +178,7 @@ function createShellBootstrapRuntime({
   }
 
   function refresh(reason = "manual") {
-    refreshQueue = refreshQueue.then(() => performRefresh(reason));
+    refreshQueue = refreshQueue.catch(() => null).then(() => performRefresh(reason));
     return refreshQueue;
   }
 

package/src/client/runtime/refreshRuntime.js

@@ -0,0 +1,122 @@
+import { isRecord } from "@jskit-ai/kernel/shared/support";
+import { createProviderLogger as createSharedProviderLogger } from "@jskit-ai/kernel/shared/support/providerLogger";
+
+const SHELL_WEB_REFRESH_RUNTIME_KEY = "jskit.shell-web.runtime.web-refresh.client";
+
+function isPullRefreshQuery(query = null) {
+  const meta = isRecord(query?.meta) ? query.meta : {};
+  if (meta.jskitRefresh === "pull") {
+    return true;
+  }
+  if (meta.jskitRefresh === false) {
+    return false;
+  }
+
+  const jskitMeta = isRecord(meta.jskit) ? meta.jskit : {};
+  return jskitMeta.refreshOnPull !== false;
+}
+
+function createShellRefreshRuntime({
+  bootstrapRuntime = null,
+  queryClient = null,
+  errorRuntime = null,
+  logger = null
+} = {}) {
+  const runtimeLogger = createSharedProviderLogger(logger);
+  let refreshQueue = Promise.resolve(null);
+
+  async function refreshBootstrap(reason) {
+    if (!bootstrapRuntime || typeof bootstrapRuntime.refresh !== "function") {
+      return false;
+    }
+
+    await bootstrapRuntime.refresh(reason);
+    return true;
+  }
+
+  async function refetchPullQueries() {
+    if (!queryClient || typeof queryClient.refetchQueries !== "function") {
+      return false;
+    }
+
+    await queryClient.refetchQueries(
+      {
+        type: "active",
+        predicate: isPullRefreshQuery
+      },
+      {
+        throwOnError: false
+      }
+    );
+    return true;
+  }
+
+  function reportRefreshFailure(error) {
+    runtimeLogger.warn(
+      {
+        error: String(error?.message || error || "unknown error")
+      },
+      "Shell refresh failed."
+    );
+
+    if (!errorRuntime || typeof errorRuntime.report !== "function") {
+      return;
+    }
+
+    errorRuntime.report({
+      source: "shell-web.refresh",
+      message: "Unable to refresh. Check the connection and try again.",
+      intent: "app-recoverable",
+      severity: "error",
+      dedupeKey: "shell-web.refresh.failed",
+      dedupeWindowMs: 2000,
+      action: {
+        label: "Retry",
+        dismissOnRun: true,
+        handler() {
+          void refresh("retry");
+        }
+      }
+    });
+  }
+
+  async function performRefresh(reason = "manual") {
+    const normalizedReason = String(reason || "manual").trim() || "manual";
+    try {
+      const [bootstrapRefreshed, queriesRefetched] = await Promise.all([
+        refreshBootstrap(normalizedReason),
+        refetchPullQueries()
+      ]);
+
+      return Object.freeze({
+        reason: normalizedReason,
+        bootstrapRefreshed,
+        queriesRefetched
+      });
+    } catch (error) {
+      reportRefreshFailure(error);
+      return Object.freeze({
+        reason: normalizedReason,
+        bootstrapRefreshed: false,
+        queriesRefetched: false,
+        error
+      });
+    }
+  }
+
+  function refresh(reason = "manual") {
+    refreshQueue = refreshQueue
+      .catch(() => null)
+      .then(() => performRefresh(reason));
+    return refreshQueue;
+  }
+
+  return Object.freeze({
+    refresh
+  });
+}
+
+export {
+  SHELL_WEB_REFRESH_RUNTIME_KEY,
+  createShellRefreshRuntime
+};

package/src/client/support/gestureTargets.js

@@ -0,0 +1,26 @@
+const SHELL_GESTURE_IGNORED_SELECTORS = Object.freeze([
+  "a",
+  "button",
+  "input",
+  "select",
+  "textarea",
+  "summary",
+  "[role='button']",
+  "[role='link']",
+  "[role='slider']",
+  "[contenteditable='true']",
+  "[data-shell-swipe-ignore]"
+]);
+
+// Shell gestures follow touch and pen contact, never a mouse drag.
+function isPrimaryTouchPointer(event) {
+  return event?.isPrimary !== false && event?.button === 0 && event?.pointerType !== "mouse";
+}
+
+// Interactive controls keep their own gestures; the shell does not start one on them.
+function isShellGestureIgnoredTarget(target, { extraSelectors = [] } = {}) {
+  const selectors = [...SHELL_GESTURE_IGNORED_SELECTORS, ...extraSelectors].join(",");
+  return Boolean(target?.closest?.(selectors));
+}
+
+export { isPrimaryTouchPointer, isShellGestureIgnoredTarget };

package/src/client/support/menuLinkTarget.js

@@ -1,5 +1,9 @@
 import { normalizeText } from "@jskit-ai/kernel/shared/support/normalize";
-import { resolveSurfaceDefinitionFromPlacementContext } from "../placement/surfaceContext.js";
+import { resolveShellLinkPath } from "../navigation/linkResolver.js";
+import {
+  resolveSurfaceDefinitionFromPlacementContext,
+  resolveSurfaceNavigationTargetFromPlacementContext
+} from "../placement/surfaceContext.js";
 
 function normalizeMenuLinkPathname(pathname = "") {
   const source = String(pathname || "").trim();
@@ -61,37 +65,49 @@ function resolveMenuLinkTarget({
   placementContext = null,
   scopedSuffix = "/",
   unscopedSuffix = "/",
-  routeParams = {},
-  resolvePagePath = null
+  routeParams = {}
 } = {}) {
   const explicitTarget = normalizeText(to);
+  if (explicitTarget && !isRelativeMenuLinkTarget(explicitTarget)) {
+    return explicitTarget;
+  }
+
   const targetSurfaceId = resolveMenuLinkSurfaceId(surface, currentSurfaceId);
   const scopedRouteRequired = surfaceRequiresWorkspaceFromPlacementContext(placementContext, targetSurfaceId);
   const suffixTemplate = normalizeText(scopedRouteRequired ? scopedSuffix : unscopedSuffix) || "/";
   const interpolatedSuffix = interpolateBracketParams(suffixTemplate, routeParams);
-  const resolvedSuffixTarget =
-    typeof resolvePagePath === "function" &&
-    targetSurfaceId &&
-    interpolatedSuffix &&
-    !interpolatedSuffix.includes("[")
-      ? normalizeText(resolvePagePath(interpolatedSuffix, {
-          surface: targetSurfaceId,
-          mode: "auto"
-        }))
-      : "";
-
-  if (!explicitTarget) {
-    return resolvedSuffixTarget;
+  if (!targetSurfaceId || !interpolatedSuffix || interpolatedSuffix.includes("[")) {
+    return "";
   }
 
-  if (isRelativeMenuLinkTarget(explicitTarget)) {
-    return resolvedSuffixTarget;
+  return normalizeText(resolveShellLinkPath({
+    context: placementContext,
+    surface: targetSurfaceId,
+    relativePath: interpolatedSuffix,
+    params: routeParams,
+    strictParams: true
+  }));
+}
+
+// Menu and tab links render nothing for an empty target.
+function resolveMenuLinkHref(placementContext = null, target = "") {
+  const path = String(target || "").trim();
+  if (!path) {
+    return {
+      href: "",
+      sameOrigin: true
+    };
   }
 
-  return explicitTarget;
+  const navigationTarget = resolveSurfaceNavigationTargetFromPlacementContext(placementContext, { path });
+  return {
+    href: navigationTarget.href,
+    sameOrigin: navigationTarget.sameOrigin
+  };
 }
 
 export {
   normalizeMenuLinkPathname,
+  resolveMenuLinkHref,
   resolveMenuLinkTarget
 };

package/src/client/support/routeParams.js

@@ -0,0 +1,26 @@
+import { normalizeText } from "@jskit-ai/kernel/shared/support/normalize";
+
+// Route params as path builders consume them: trimmed keys, the first value of a
+// repeated param, and no empty values.
+function normalizeRouteParams(params = null) {
+  if (!params || typeof params !== "object" || Array.isArray(params)) {
+    return {};
+  }
+
+  const output = {};
+  for (const [rawKey, rawValue] of Object.entries(params)) {
+    const key = normalizeText(rawKey);
+    if (!key) {
+      continue;
+    }
+
+    const value = Array.isArray(rawValue) ? rawValue[0] : rawValue;
+    const normalizedValue = normalizeText(value);
+    if (normalizedValue) {
+      output[key] = normalizedValue;
+    }
+  }
+  return output;
+}
+
+export { normalizeRouteParams };

package/src/client/support/routeSwipeGesture.js

@@ -0,0 +1,88 @@
+const SWIPE_MIN_DISTANCE = 36;
+const SWIPE_MAX_VERTICAL_DRIFT = 120;
+const SWIPE_MIN_VELOCITY = 0.08;
+const SWIPE_CLAIM_DISTANCE = 10;
+const NO_SWIPE = Object.freeze({ claim: false, offset: 0 });
+
+function isAcceptedSwipe({ deltaX = 0, deltaY = 0, elapsed = 1 } = {}) {
+  const absX = Math.abs(deltaX);
+  const absY = Math.abs(deltaY);
+  const velocity = absX / Math.max(elapsed, 1);
+  return absX >= SWIPE_MIN_DISTANCE && absY <= SWIPE_MAX_VERTICAL_DRIFT && absX > absY && velocity >= SWIPE_MIN_VELOCITY;
+}
+
+function isVerticalDrift(absX, absY) {
+  return absY > SWIPE_MAX_VERTICAL_DRIFT || (absY > 28 && absY > absX * 1.3);
+}
+
+// Tracks one horizontal swipe between primary navigation destinations. A swipe
+// that drifts vertically is dropped for good: the gesture became a scroll.
+function createRouteSwipeGesture({ now = () => performance.now() } = {}) {
+  let active = null;
+
+  function tracks(pointerId) {
+    return Boolean(active) && pointerId === active.pointerId;
+  }
+
+  function start({ pointerId, clientX, clientY }) {
+    active = { pointerId, startX: clientX, startY: clientY, startTime: now() };
+  }
+
+  function reset() {
+    active = null;
+  }
+
+  function measure({ clientX, clientY }) {
+    return {
+      deltaX: clientX - active.startX,
+      deltaY: clientY - active.startY,
+      elapsed: Math.max(now() - active.startTime, 1)
+    };
+  }
+
+  function offsetFor(deltaX) {
+    return deltaX < 0 ? 1 : -1;
+  }
+
+  function move(event) {
+    if (!tracks(event.pointerId)) {
+      return NO_SWIPE;
+    }
+
+    const swipe = measure(event);
+    const absX = Math.abs(swipe.deltaX);
+    const absY = Math.abs(swipe.deltaY);
+    if (isVerticalDrift(absX, absY)) {
+      active = null;
+      return NO_SWIPE;
+    }
+
+    const claim = absX > SWIPE_CLAIM_DISTANCE && absX > absY;
+    if (!isAcceptedSwipe(swipe)) {
+      return { claim, offset: 0 };
+    }
+
+    active = null;
+    return { claim, offset: offsetFor(swipe.deltaX) };
+  }
+
+  function end(event) {
+    if (!tracks(event.pointerId)) {
+      return 0;
+    }
+
+    const swipe = measure(event);
+    active = null;
+    return isAcceptedSwipe(swipe) ? offsetFor(swipe.deltaX) : 0;
+  }
+
+  function cancel(event) {
+    if (tracks(event.pointerId)) {
+      active = null;
+    }
+  }
+
+  return Object.freeze({ start, reset, move, end, cancel });
+}
+
+export { createRouteSwipeGesture };

package/src/client/support/routeTransitionKey.js

@@ -1,6 +1,4 @@
-function normalizeText(value = "") {
-  return String(value || "").trim();
-}
+import { normalizeText } from "@jskit-ai/kernel/shared/support/normalize";
 
 function resolveShellRouteTransitionKey({
   routePathKey = "",

package/src/client/support/shellLayoutClass.js

@@ -0,0 +1,32 @@
+const COMPACT_MAX_WIDTH = 600;
+const MEDIUM_MAX_WIDTH = 1280;
+
+// Maps the Vuetify display breakpoint name to the shell layout class. Without
+// a known breakpoint the viewport width decides.
+function resolveShellLayoutClass(displayName = "", viewportWidth = 0) {
+  const name = String(displayName || "").trim().toLowerCase();
+  if (name === "xs" || name === "sm") {
+    return "compact";
+  }
+  if (name === "md") {
+    return "medium";
+  }
+  if (name === "lg" || name === "xl" || name === "xxl") {
+    return "expanded";
+  }
+
+  const width = Number(viewportWidth) || 0;
+  if (width > 0 && width < COMPACT_MAX_WIDTH) {
+    return "compact";
+  }
+  if (width > 0 && width < MEDIUM_MAX_WIDTH) {
+    return "medium";
+  }
+  return "expanded";
+}
+
+function readViewportWidth() {
+  return typeof window === "object" ? Number(window.innerWidth || 0) : 0;
+}
+
+export { readViewportWidth, resolveShellLayoutClass };