@jskit-ai/shell-web 0.1.4

package/src/client/navigation/linkResolver.js

@@ -0,0 +1,117 @@
+import { unref } from "vue";
+import { resolveLinkPath, normalizePathname } from "@jskit-ai/kernel/shared";
+import { normalizeSurfaceId } from "@jskit-ai/kernel/shared/surface/registry";
+import { useWebPlacementContext } from "../placement/inject.js";
+import {
+  resolveSurfaceDefinitionFromPlacementContext,
+  resolveSurfaceRootPathFromPlacementContext
+} from "../placement/surfaceContext.js";
+
+function normalizeParamsMap(params = null) {
+  if (!params || typeof params !== "object" || Array.isArray(params)) {
+    return {};
+  }
+  return params;
+}
+
+function materializeSurfaceRouteBase(routeBaseTemplate = "/", { params = {}, strictParams = true, surface = "" } = {}) {
+  const normalizedParams = normalizeParamsMap(params);
+  const missingParams = new Set();
+  const outputPath = String(routeBaseTemplate || "/").replace(/:([A-Za-z0-9_]+)/g, (_full, rawName) => {
+    const paramName = String(rawName || "").trim();
+    const paramValue = normalizedParams[paramName];
+    const normalizedValue = String(paramValue ?? "").trim();
+    if (!normalizedValue) {
+      missingParams.add(paramName);
+      return `:${paramName}`;
+    }
+    return encodeURIComponent(normalizedValue);
+  });
+
+  if (strictParams && missingParams.size > 0) {
+    const surfaceLabel = String(surface || "").trim() || "(default)";
+    const missing = [...missingParams].sort().join(", ");
+    throw new Error(`Missing required surface route params for "${surfaceLabel}": ${missing}.`);
+  }
+
+  return outputPath;
+}
+
+function resolveSurfaceBasePath(context = null, surface = "", { params = {}, strictParams = true } = {}) {
+  const normalizedSurface = normalizeSurfaceId(surface);
+  if (normalizedSurface && resolveSurfaceDefinitionFromPlacementContext(context, normalizedSurface)) {
+    const routeBaseTemplate = resolveSurfaceRootPathFromPlacementContext(context, normalizedSurface);
+    return materializeSurfaceRouteBase(routeBaseTemplate, {
+      params,
+      strictParams,
+      surface: normalizedSurface
+    });
+  }
+
+  if (!normalizedSurface) {
+    return "/";
+  }
+
+  return normalizePathname(`/${normalizedSurface}`);
+}
+
+function resolveShellLinkPath({
+  context = null,
+  surface = "",
+  explicitTo = "",
+  relativePath = "/",
+  surfaceRelativePath = "",
+  params = {},
+  strictParams = true
+} = {}) {
+  const explicitTarget = String(explicitTo || "").trim();
+  if (explicitTarget) {
+    return explicitTarget;
+  }
+
+  const normalizedSurface = normalizeSurfaceId(surface);
+  const nextRelativePath = String(surfaceRelativePath || "").trim() || String(relativePath || "").trim() || "/";
+  const nextSurfaceBasePath = resolveSurfaceBasePath(context, normalizedSurface, {
+    params,
+    strictParams
+  });
+
+  return resolveLinkPath(nextSurfaceBasePath, nextRelativePath);
+}
+
+function useShellLinkResolver({ surface = "" } = {}) {
+  const { context: placementContext } = useWebPlacementContext();
+
+  function resolve(relativePath = "/", options = {}) {
+    return resolveShellLinkPath({
+      context: placementContext.value,
+      surface: String(unref(options.surface ?? surface) || ""),
+      explicitTo: options.explicitTo,
+      relativePath,
+      surfaceRelativePath: options.surfaceRelativePath,
+      params: options.params,
+      strictParams: options.strictParams !== false
+    });
+  }
+
+  function toSurface(relativePath = "/", options = {}) {
+    return resolve(relativePath, options);
+  }
+
+  function toWorkspace(relativePath = "/", options = {}) {
+    return resolve(relativePath, options);
+  }
+
+  function toAuto(relativePath = "/", options = {}) {
+    return resolve(relativePath, options);
+  }
+
+  return Object.freeze({
+    resolve,
+    toSurface,
+    toWorkspace,
+    toAuto
+  });
+}
+
+export { resolveShellLinkPath, useShellLinkResolver };

package/src/client/placement/debug.js

@@ -0,0 +1,52 @@
+const DEFAULT_DEBUG_DEPTH = 4;
+
+function describeFunction(fn) {
+  return `[Function ${fn?.name || "anonymous"}]`;
+}
+
+function describeSymbol(value) {
+  return value?.toString ? value.toString() : "[Symbol]";
+}
+
+function explodePayload(value, depth = DEFAULT_DEBUG_DEPTH) {
+  const visited = new WeakSet();
+
+  function walk(node, remaining) {
+    if (node === null || typeof node !== "object") {
+      if (typeof node === "function") {
+        return describeFunction(node);
+      }
+      if (typeof node === "symbol") {
+        return describeSymbol(node);
+      }
+      return node;
+    }
+
+    if (visited.has(node)) {
+      return "[Circular]";
+    }
+    visited.add(node);
+
+    if (remaining <= 0) {
+      return Array.isArray(node) ? "[Array]" : "[Object]";
+    }
+
+    if (Array.isArray(node)) {
+      return node.map((entry) => walk(entry, remaining - 1));
+    }
+
+    if (node instanceof Date) {
+      return node.toISOString();
+    }
+
+    const next = {};
+    for (const [key, child] of Object.entries(node)) {
+      next[key] = walk(child, remaining - 1);
+    }
+    return next;
+  }
+
+  return walk(value, depth);
+}
+
+export { DEFAULT_DEBUG_DEPTH, explodePayload };

package/src/client/placement/index.js

@@ -0,0 +1,26 @@
+export {
+  WEB_PLACEMENT_RUNTIME_CLIENT_TOKEN
+} from "./tokens.js";
+
+export {
+  createPlacementRegistry
+} from "./registry.js";
+
+export {
+  useWebPlacementContext
+} from "./inject.js";
+
+export {
+  resolveRuntimePathname
+} from "./pathname.js";
+
+export {
+  readPlacementSurfaceConfig,
+  resolveSurfaceDefinitionFromPlacementContext,
+  joinSurfacePath,
+  resolveSurfaceIdFromPlacementPathname,
+  resolveSurfaceRootPathFromPlacementContext,
+  resolveSurfacePathFromPlacementContext,
+  normalizeSurfaceOrigin,
+  resolveSurfaceNavigationTargetFromPlacementContext
+} from "./surfaceContext.js";

package/src/client/placement/inject.js

@@ -0,0 +1,104 @@
+import {
+  inject,
+  onBeforeUnmount,
+  onMounted,
+  shallowRef
+} from "vue";
+import { WEB_PLACEMENT_RUNTIME_INJECTION_KEY } from "./tokens.js";
+
+const EMPTY_WEB_PLACEMENT_RUNTIME = Object.freeze({
+  getContext() {
+    return Object.freeze({});
+  },
+  getPlacements() {
+    return Object.freeze([]);
+  },
+  setContext() {
+    return Object.freeze({});
+  },
+  subscribe() {
+    return () => {};
+  },
+  getRevision() {
+    return 0;
+  }
+});
+
+const EMPTY_WEB_PLACEMENT_CONTEXT_REF = shallowRef(Object.freeze({}));
+
+const EMPTY_WEB_PLACEMENT_CONTEXT = Object.freeze({
+  context: EMPTY_WEB_PLACEMENT_CONTEXT_REF,
+  mergeContext() {
+    return EMPTY_WEB_PLACEMENT_CONTEXT_REF.value;
+  },
+  replaceContext() {
+    return EMPTY_WEB_PLACEMENT_CONTEXT_REF.value;
+  }
+});
+
+function useWebPlacementRuntime({ required = false } = {}) {
+  const runtime = inject(WEB_PLACEMENT_RUNTIME_INJECTION_KEY, null);
+  if (runtime && typeof runtime.getPlacements === "function") {
+    return runtime;
+  }
+
+  if (required) {
+    throw new Error("Web placement runtime is not available in Vue injection context.");
+  }
+
+  return EMPTY_WEB_PLACEMENT_RUNTIME;
+}
+
+function useWebPlacementContext({ required = false } = {}) {
+  const runtime = useWebPlacementRuntime({ required });
+  if (runtime === EMPTY_WEB_PLACEMENT_RUNTIME) {
+    return EMPTY_WEB_PLACEMENT_CONTEXT;
+  }
+
+  const context = shallowRef(runtime.getContext());
+  let unsubscribe = null;
+
+  onMounted(() => {
+    if (typeof runtime.subscribe !== "function") {
+      return;
+    }
+    unsubscribe = runtime.subscribe(() => {
+      context.value = runtime.getContext();
+    });
+  });
+
+  onBeforeUnmount(() => {
+    if (typeof unsubscribe === "function") {
+      unsubscribe();
+      unsubscribe = null;
+    }
+  });
+
+  function mergeContext(value = {}, source = "component") {
+    context.value = runtime.setContext(value, {
+      source
+    });
+    return context.value;
+  }
+
+  function replaceContext(value = {}, source = "component") {
+    context.value = runtime.setContext(value, {
+      replace: true,
+      source
+    });
+    return context.value;
+  }
+
+  return Object.freeze({
+    context,
+    mergeContext,
+    replaceContext
+  });
+}
+
+export {
+  EMPTY_WEB_PLACEMENT_RUNTIME,
+  EMPTY_WEB_PLACEMENT_CONTEXT,
+  useWebPlacementRuntime,
+  useWebPlacementContext
+};

package/src/client/placement/pathname.js

@@ -0,0 +1,14 @@
+function resolveRuntimePathname(candidate = "") {
+  const explicitPathname = String(candidate || "").trim();
+  if (explicitPathname) {
+    return explicitPathname;
+  }
+
+  if (typeof window === "object" && window?.location?.pathname) {
+    return String(window.location.pathname || "").trim() || "/";
+  }
+
+  return "/";
+}
+
+export { resolveRuntimePathname };

package/src/client/placement/registry.js

@@ -0,0 +1,41 @@
+import {
+  definePlacement
+} from "./validators.js";
+
+function createPlacementRegistry({ entries = [] } = {}) {
+  const placements = [];
+  const ids = new Set();
+
+  function addPlacement(value = {}) {
+    const placement = definePlacement(value);
+    if (ids.has(placement.id)) {
+      return false;
+    }
+
+    ids.add(placement.id);
+    placements.push(placement);
+    return true;
+  }
+
+  for (const entry of Array.isArray(entries) ? entries : []) {
+    addPlacement(entry);
+  }
+
+  function hasPlacement(id) {
+    return ids.has(String(id || "").trim());
+  }
+
+  function build() {
+    return Object.freeze([...placements]);
+  }
+
+  return Object.freeze({
+    addPlacement,
+    hasPlacement,
+    build
+  });
+}
+
+export {
+  createPlacementRegistry
+};