@jskit-ai/shell-web 0.1.154 → 0.1.156

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jskit-ai/shell-web",
-  "version": "0.1.154",
+  "version": "0.1.156",
   "type": "module",
   "scripts": {
     "test": "node --test"
@@ -14,6 +14,8 @@
     "./client/bootstrap": "./src/client/bootstrap/index.js",
     "./server/support/localLinkItemScaffolds": "./src/server/support/localLinkItemScaffolds.js",
     "./client/navigation/linkResolver": "./src/client/navigation/linkResolver.js",
+    "./client/navigation/usePaths": "./src/client/navigation/usePaths.js",
+    "./client/navigation/useSurfaceRouteContext": "./src/client/navigation/useSurfaceRouteContext.js",
     "./client/components/ShellLayout": "./src/client/components/ShellLayout.vue",
     "./client/components/ShellOutlet": "./src/client/components/ShellOutlet.vue",
     "./client/components/ShellOutletMenuWidget": "./src/client/components/ShellOutletMenuWidget.vue",
@@ -28,7 +30,7 @@
   },
   "dependencies": {
     "@mdi/js": "^7.4.47",
-    "@jskit-ai/kernel": "0.1.150"
+    "@jskit-ai/kernel": "0.1.152"
   },
   "peerDependencies": {
     "pinia": "^3.0.4",
@@ -83,6 +85,14 @@
             "subpath": "./client/placement",
             "summary": "Exports placement registry, placement context access, runtime token, and surface path helpers."
           },
+          {
+            "subpath": "./client/navigation/usePaths",
+            "summary": "Exports surface-aware page and API path resolution."
+          },
+          {
+            "subpath": "./client/navigation/useSurfaceRouteContext",
+            "summary": "Exports the current route, placement context, and resolved surface id."
+          },
           {
             "subpath": "./client/error",
             "summary": "Exports default error policy and runtime error reporter hook."
@@ -381,7 +391,7 @@
       "dependencies": {
         "runtime": {
           "@mdi/js": "^7.4.47",
-          "@jskit-ai/kernel": "0.1.150"
+          "@jskit-ai/kernel": "0.1.152"
         },
         "dev": {
           "@playwright/test": "1.61.1"

package/src/client/navigation/usePaths.js

@@ -0,0 +1,119 @@
+import { computed, unref } from "vue";
+import { normalizeText } from "@jskit-ai/kernel/shared/support/normalize";
+import { resolveScopedApiBasePath } from "@jskit-ai/kernel/shared/surface";
+import { resolveSurfaceDefinitionFromPlacementContext } from "../placement/index.js";
+import { useShellLinkResolver } from "./linkResolver.js";
+import { useSurfaceRouteContext } from "./useSurfaceRouteContext.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 resolveDefaultSurfaceIdFromPlacementContext(placementContext = null) {
+  return resolveSurfaceId(placementContext?.surfaceConfig?.defaultSurfaceId, "");
+}
+
+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;
+}
+
+function resolveRouteParams(baseParams = {}, overrideParams = null) {
+  return {
+    ...normalizeRouteParams(baseParams),
+    ...normalizeRouteParams(overrideParams)
+  };
+}
+
+function usePaths({ routeContext: sourceRouteContext = null } = {}) {
+  const routeContext = sourceRouteContext || useSurfaceRouteContext();
+  const shellLinkResolver = useShellLinkResolver();
+  const routeParams = computed(() => normalizeRouteParams(routeContext.route?.params));
+
+  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 "";
+    }
+    return shellLinkResolver.resolve(relativePath, {
+      surface,
+      explicitTo: source.explicitTo,
+      surfaceRelativePath: source.surfaceRelativePath,
+      params: resolveRouteParams(routeParams.value, source.params),
+      strictParams: source.strictParams !== false
+    });
+  }
+
+  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);
+
+    if (!suffix) {
+      throw new TypeError("usePaths().api(relativePath) requires a non-empty relativePath.");
+    }
+
+    const routeBase = resolveSurfaceDefinitionFromPlacementContext(
+      routeContext.placementContext.value,
+      surface
+    )?.routeBase || "/";
+
+    return resolveScopedApiBasePath({
+      routeBase,
+      relativePath: suffix,
+      params: resolveRouteParams(routeParams.value, source.params),
+      strictParams: source.strictParams !== false
+    });
+  }
+
+  return Object.freeze({
+    route: routeContext.route,
+    placementContext: routeContext.placementContext,
+    currentSurfaceId: routeContext.currentSurfaceId,
+    routeParams,
+    page,
+    api
+  });
+}
+
+export { usePaths };

package/src/client/navigation/useSurfaceRouteContext.js

@@ -0,0 +1,26 @@
+import { computed } from "vue";
+import { useRoute } from "vue-router";
+import {
+  resolveRuntimePathname,
+  resolveSurfaceIdFromPlacementPathname,
+  useWebPlacementContext
+} from "../placement/index.js";
+
+function useSurfaceRouteContext() {
+  const route = useRoute();
+  const { context: placementContext, mergeContext: mergePlacementContext } = useWebPlacementContext();
+  const routePath = computed(() => resolveRuntimePathname(route?.path));
+  const currentSurfaceId = computed(() =>
+    resolveSurfaceIdFromPlacementPathname(placementContext.value, routePath.value)
+  );
+
+  return Object.freeze({
+    route,
+    routePath,
+    placementContext,
+    mergePlacementContext,
+    currentSurfaceId
+  });
+}
+
+export { useSurfaceRouteContext };

package/src/client/placement/validators.js

@@ -114,13 +114,6 @@ function normalizePlacementDefinition(value, { strict = false, source = "placeme
     return null;
   }
 
-  if (Object.hasOwn(value, "host") || Object.hasOwn(value, "position")) {
-    if (strict) {
-      throw new TypeError(`${source} must use "target" only. Legacy "host" and "position" fields are not supported.`);
-    }
-    return null;
-  }
-
   const id = normalizeText(value.id);
   if (!id) {
     if (strict) {

package/src/client/requestRecovery/runtime.js

@@ -125,10 +125,6 @@ function resolveQueryMeta(query = null) {
 
 function isRequestRecoveryDisabled(query = null) {
   const meta = resolveQueryMeta(query);
-  if (meta.jskitRequestRecovery === false || meta.requestRecovery === false) {
-    return true;
-  }
-
   const jskitMeta = isRecord(meta.jskit) ? meta.jskit : {};
   return jskitMeta.requestRecovery === false;
 }
@@ -138,11 +134,7 @@ function resolveQueryRecoveryLabel(query = null) {
   const jskitMeta = isRecord(meta.jskit) ? meta.jskit : {};
 
   return normalizeText(
-    jskitMeta.requestRecoveryLabel ||
-      jskitMeta.label ||
-      meta.jskitRequestRecoveryLabel ||
-      meta.requestRecoveryLabel ||
-      meta.label,
+    jskitMeta.requestRecoveryLabel,
     "Request"
   );
 }
@@ -152,9 +144,7 @@ function resolveQueryRecoverySource(query = null) {
   const jskitMeta = isRecord(meta.jskit) ? meta.jskit : {};
 
   return normalizeText(
-    jskitMeta.requestRecoverySource ||
-      meta.jskitRequestRecoverySource ||
-      meta.requestRecoverySource,
+    jskitMeta.requestRecoverySource,
     "shell-web.request-recovery.query"
   );
 }
@@ -164,9 +154,7 @@ function resolveQueryRecoveryDedupeKey(query = null, fallback = "") {
   const jskitMeta = isRecord(meta.jskit) ? meta.jskit : {};
 
   return normalizeText(
-    jskitMeta.requestRecoveryDedupeKey ||
-      meta.jskitRequestRecoveryDedupeKey ||
-      meta.requestRecoveryDedupeKey,
+    jskitMeta.requestRecoveryDedupeKey,
     fallback
   );
 }
@@ -174,10 +162,7 @@ function resolveQueryRecoveryDedupeKey(query = null, fallback = "") {
 function resolveQueryRecoveryDedupeWindowMs(query = null) {
   const meta = resolveQueryMeta(query);
   const jskitMeta = isRecord(meta.jskit) ? meta.jskit : {};
-  const value =
-    jskitMeta.requestRecoveryDedupeWindowMs ??
-      meta.jskitRequestRecoveryDedupeWindowMs ??
-      meta.requestRecoveryDedupeWindowMs;
+  const value = jskitMeta.requestRecoveryDedupeWindowMs;
 
   return Number.isFinite(Number(value)) ? Math.max(0, Number(value)) : null;
 }
@@ -186,11 +171,7 @@ function resolveQueryRecoveryMethod(query = null) {
   const meta = resolveQueryMeta(query);
   const jskitMeta = isRecord(meta.jskit) ? meta.jskit : {};
 
-  return normalizeText(
-    jskitMeta.requestRecoveryMethod ||
-      meta.jskitRequestRecoveryMethod ||
-      meta.requestRecoveryMethod
-  ).toUpperCase();
+  return normalizeText(jskitMeta.requestRecoveryMethod).toUpperCase();
 }
 
 function isSafeQueryRecoveryMethod(query = null) {

package/test/placementRegistry.test.js

@@ -41,7 +41,7 @@ test("placement registry accepts explicit non-global surface ids", () => {
   assert.equal(added, true);
 });
 
-test("placement registry rejects split target fields", () => {
+test("placement registry requires target", () => {
   const registry = createPlacementRegistry();
 
   assert.throws(
@@ -51,6 +51,6 @@ test("placement registry rejects split target fields", () => {
       position: "top-right",
       componentToken: "example.split.component"
     }),
-    /must use "target" only/
+    /requires semantic target/
   );
 });