@jskit-ai/shell-web 0.1.31 → 0.1.33

package/src/client/components/ShellTabLinkItem.vue

@@ -0,0 +1,128 @@
+<script setup>
+import { computed } from "vue";
+import { useRoute } from "vue-router";
+import { resolveShellLinkPath } from "../navigation/linkResolver.js";
+import {
+  resolveSurfaceIdFromPlacementPathname,
+  resolveSurfaceNavigationTargetFromPlacementContext,
+  useWebPlacementContext
+} from "../placement/index.js";
+import {
+  normalizeMenuLinkPathname,
+  resolveMenuLinkTarget
+} from "../support/menuLinkTarget.js";
+
+const props = defineProps({
+  label: {
+    type: String,
+    default: ""
+  },
+  to: {
+    type: String,
+    default: ""
+  },
+  surface: {
+    type: String,
+    default: ""
+  },
+  workspaceSuffix: {
+    type: String,
+    default: "/"
+  },
+  nonWorkspaceSuffix: {
+    type: String,
+    default: "/"
+  },
+  disabled: {
+    type: Boolean,
+    default: false
+  }
+});
+
+const route = useRoute();
+const { context: placementContext } = useWebPlacementContext();
+
+const currentSurfaceId = computed(() => {
+  return resolveSurfaceIdFromPlacementPathname(
+    placementContext.value,
+    String(route?.path || route?.fullPath || "").trim()
+  );
+});
+
+const resolvedTo = computed(() => {
+  return resolveMenuLinkTarget({
+    to: props.to,
+    surface: props.surface,
+    currentSurfaceId: currentSurfaceId.value,
+    placementContext: placementContext.value,
+    workspaceSuffix: props.workspaceSuffix,
+    nonWorkspaceSuffix: props.nonWorkspaceSuffix,
+    routeParams: route.params || {},
+    resolvePagePath(relativePath, options = {}) {
+      return resolveShellLinkPath({
+        context: placementContext.value,
+        surface: options.surface,
+        relativePath,
+        params: route.params || {},
+        strictParams: options.strictParams !== false
+      });
+    }
+  });
+});
+
+const resolvedTarget = computed(() => {
+  const target = String(resolvedTo.value || "").trim();
+  if (!target) {
+    return {
+      href: "",
+      sameOrigin: true
+    };
+  }
+
+  const navigationTarget = resolveSurfaceNavigationTargetFromPlacementContext(placementContext.value, {
+    path: target
+  });
+  return {
+    href: navigationTarget.href,
+    sameOrigin: navigationTarget.sameOrigin
+  };
+});
+
+const isActive = computed(() => {
+  if (!resolvedTarget.value.sameOrigin) {
+    return false;
+  }
+
+  const targetPath = normalizeMenuLinkPathname(resolvedTarget.value.href);
+  const currentPath = normalizeMenuLinkPathname(route.fullPath || route.path || "");
+  if (!targetPath || !currentPath) {
+    return false;
+  }
+
+  return currentPath === targetPath || currentPath.startsWith(`${targetPath}/`);
+});
+</script>
+
+<template>
+  <v-btn
+    v-if="resolvedTarget.href"
+    class="tab-link-item"
+    variant="text"
+    size="small"
+    :to="resolvedTarget.sameOrigin ? resolvedTarget.href : undefined"
+    :href="resolvedTarget.sameOrigin ? undefined : resolvedTarget.href"
+    :active="isActive"
+    :disabled="disabled"
+    color="primary"
+  >
+    {{ label || "Tab" }}
+  </v-btn>
+</template>
+
+<style scoped>
+.tab-link-item {
+  text-transform: none;
+  font-weight: 600;
+  border-radius: 999px;
+}
+</style>

package/src/client/index.js

@@ -8,7 +8,11 @@ export {
 
 export { default as ShellLayout } from "./components/ShellLayout.vue";
 export { default as ShellOutlet } from "./components/ShellOutlet.vue";
+export { default as ShellOutletMenuWidget } from "./components/ShellOutletMenuWidget.vue";
 export { default as ShellErrorHost } from "./components/ShellErrorHost.vue";
+export { default as ShellMenuLinkItem } from "./components/ShellMenuLinkItem.vue";
+export { default as ShellSurfaceAwareMenuLinkItem } from "./components/ShellSurfaceAwareMenuLinkItem.vue";
+export { default as ShellTabLinkItem } from "./components/ShellTabLinkItem.vue";
 export { useShellLayoutState } from "./composables/useShellLayoutState.js";
 
 const clientProviders = Object.freeze([ShellWebClientProvider]);

package/src/client/lib/menuIcons.js

@@ -0,0 +1,210 @@
+import * as mdiIcons from "@mdi/js";
+import {
+  mdiAccountCircleOutline,
+  mdiAccountCogOutline,
+  mdiAccountGroupOutline,
+  mdiArrowRightCircleOutline,
+  mdiClipboardListOutline,
+  mdiCogOutline,
+  mdiConsoleNetworkOutline,
+  mdiFolderOutline,
+  mdiHomeVariantOutline,
+  mdiLogin,
+  mdiLogout,
+  mdiRobotOutline,
+  mdiShieldCrownOutline,
+  mdiViewDashboardOutline,
+  mdiViewListOutline
+} from "@mdi/js";
+import { isExternalLinkTarget, splitPathQueryHash } from "@jskit-ai/kernel/shared/support/linkPath";
+import { normalizeText } from "@jskit-ai/kernel/shared/support/normalize";
+import { normalizePathname as normalizeKernelPathname } from "@jskit-ai/kernel/shared/surface/paths";
+
+const SURFACE_SWITCH_ICON_BY_ID = Object.freeze({
+  home: mdiHomeVariantOutline,
+  app: mdiViewDashboardOutline,
+  admin: mdiShieldCrownOutline,
+  console: mdiConsoleNetworkOutline
+});
+
+function resolveExplicitIconValue(explicitIcon = "") {
+  const normalizedExplicitIcon = normalizeText(explicitIcon);
+  if (!normalizedExplicitIcon) {
+    return "";
+  }
+
+  if (!normalizedExplicitIcon.startsWith("mdi-")) {
+    return normalizedExplicitIcon;
+  }
+
+  const iconKey = normalizedExplicitIcon
+    .slice("mdi-".length)
+    .split("-")
+    .map((segment) => segment.charAt(0).toUpperCase() + segment.slice(1))
+    .join("");
+  const exportName = `mdi${iconKey}`;
+  const resolvedIcon = mdiIcons[exportName];
+  return typeof resolvedIcon === "string" && resolvedIcon ? resolvedIcon : normalizedExplicitIcon;
+}
+
+function normalizePathname(value = "") {
+  const normalizedValue = normalizeText(value);
+  if (!normalizedValue) {
+    return "";
+  }
+
+  if (isExternalLinkTarget(normalizedValue)) {
+    const isHttpTarget = normalizedValue.startsWith("http://") || normalizedValue.startsWith("https://");
+    if (!isHttpTarget) {
+      return "";
+    }
+
+    let parsedPathname = "";
+    try {
+      parsedPathname = String(new URL(normalizedValue).pathname || "");
+    } catch {
+      return "";
+    }
+
+    const normalizedPathname = normalizeText(parsedPathname);
+    if (!normalizedPathname) {
+      return "";
+    }
+    return normalizeKernelPathname(normalizedPathname).toLowerCase();
+  }
+
+  const { pathname } = splitPathQueryHash(normalizedValue);
+  const normalizedPathname = normalizeText(pathname);
+  if (!normalizedPathname) {
+    return "";
+  }
+
+  return normalizeKernelPathname(normalizedPathname).toLowerCase();
+}
+
+function resolveSurfaceSwitchIdFromLabel(label = "") {
+  const normalizedLabel = normalizeText(label).toLowerCase();
+  if (!normalizedLabel.startsWith("go to ")) {
+    return "";
+  }
+  return normalizeText(normalizedLabel.slice("go to ".length));
+}
+
+function resolveSurfaceSwitchIcon(surfaceId = "", explicitIcon = "") {
+  const resolvedExplicitIcon = resolveExplicitIconValue(explicitIcon);
+  if (resolvedExplicitIcon) {
+    return resolvedExplicitIcon;
+  }
+
+  const normalizedSurfaceId = normalizeText(surfaceId).toLowerCase();
+  return SURFACE_SWITCH_ICON_BY_ID[normalizedSurfaceId] || mdiArrowRightCircleOutline;
+}
+
+function resolveMenuLinkIcon({ icon = "", label = "", to = "" } = {}) {
+  const resolvedExplicitIcon = resolveExplicitIconValue(icon);
+  if (resolvedExplicitIcon) {
+    return resolvedExplicitIcon;
+  }
+
+  const normalizedLabel = normalizeText(label).toLowerCase();
+  const normalizedPathname = normalizePathname(to);
+  if (!normalizedLabel && !normalizedPathname) {
+    return "";
+  }
+
+  const surfaceSwitchSurfaceId = resolveSurfaceSwitchIdFromLabel(normalizedLabel);
+  if (surfaceSwitchSurfaceId) {
+    return resolveSurfaceSwitchIcon(surfaceSwitchSurfaceId);
+  }
+
+  if (
+    normalizedLabel.includes("sign in") ||
+    normalizedPathname.includes("/auth/login")
+  ) {
+    return mdiLogin;
+  }
+
+  if (
+    normalizedLabel.includes("sign out") ||
+    normalizedPathname.includes("/auth/signout")
+  ) {
+    return mdiLogout;
+  }
+
+  if (
+    normalizedLabel.includes("account") ||
+    normalizedPathname.includes("/account")
+  ) {
+    if (
+      normalizedLabel.includes("settings") ||
+      normalizedPathname.includes("/settings") ||
+      normalizedPathname === "/account"
+    ) {
+      return mdiAccountCogOutline;
+    }
+    return mdiAccountCircleOutline;
+  }
+
+  if (
+    normalizedLabel.includes("members") ||
+    normalizedLabel.includes("team") ||
+    normalizedPathname.includes("/members")
+  ) {
+    return mdiAccountGroupOutline;
+  }
+
+  if (normalizedLabel.includes("assistant") || normalizedPathname.includes("/assistant")) {
+    return mdiRobotOutline;
+  }
+
+  if (
+    normalizedLabel.includes("console") ||
+    normalizedPathname.startsWith("/console")
+  ) {
+    return mdiConsoleNetworkOutline;
+  }
+
+  if (
+    normalizedLabel.includes("admin") ||
+    normalizedPathname.includes("/admin")
+  ) {
+    return mdiShieldCrownOutline;
+  }
+
+  if (normalizedLabel.includes("settings") || normalizedPathname.includes("/settings")) {
+    return mdiCogOutline;
+  }
+
+  if (
+    normalizedLabel.includes("home") ||
+    normalizedPathname === "/"
+  ) {
+    return mdiHomeVariantOutline;
+  }
+
+  if (
+    normalizedLabel.includes("workspace") ||
+    normalizedLabel.includes("dashboard") ||
+    normalizedPathname.includes("/w/")
+  ) {
+    return mdiViewDashboardOutline;
+  }
+
+  if (normalizedPathname) {
+    const segments = normalizedPathname.split("/").filter(Boolean);
+    if (segments.length === 1) {
+      return mdiFolderOutline;
+    }
+  }
+
+  if (normalizedLabel.includes("list")) {
+    return mdiClipboardListOutline;
+  }
+
+  return mdiViewListOutline;
+}
+
+export {
+  resolveMenuLinkIcon,
+  resolveSurfaceSwitchIcon
+};

package/src/client/placement/runtime.js

@@ -4,8 +4,7 @@ import { isRecord } from "@jskit-ai/kernel/shared/support/normalize";
 import {
   isRenderableComponent,
   normalizePlacementDefinition,
-  normalizePlacementHost,
-  normalizePlacementPosition,
+  normalizePlacementTarget,
   normalizeSurface
 } from "./validators.js";
 
@@ -86,13 +85,19 @@ function normalizePlacementList(placements, context = {}) {
     byId.set(placement.id, placement);
   }
 
-  return [...byId.values()].sort((left, right) => {
-    const orderCompare = left.order - right.order;
-    if (orderCompare !== 0) {
-      return orderCompare;
-    }
-    return left.id.localeCompare(right.id);
-  });
+  return [...byId.values()]
+    .map((placement, index) => ({
+      placement,
+      index
+    }))
+    .sort((left, right) => {
+      const orderCompare = left.placement.order - right.placement.order;
+      if (orderCompare !== 0) {
+        return orderCompare;
+      }
+      return left.index - right.index;
+    })
+    .map((entry) => entry.placement);
 }
 
 function matchesSurface(placementSurfaces, requestedSurface) {
@@ -303,10 +308,9 @@ function createWebPlacementRuntime({ app, logger = null } = {}) {
     return revision;
   }
 
-  function getPlacements({ surface = WEB_PLACEMENT_SURFACE_ANY, host = "", position = "", context = {} } = {}) {
-    const normalizedHost = normalizePlacementHost(host, { strict: false });
-    const normalizedPosition = normalizePlacementPosition(position, { strict: false });
-    if (!normalizedHost || !normalizedPosition) {
+  function getPlacements({ surface = WEB_PLACEMENT_SURFACE_ANY, target = "", context = {} } = {}) {
+    const normalizedTarget = normalizePlacementTarget(target, { strict: false });
+    if (!normalizedTarget) {
       return Object.freeze([]);
     }
 
@@ -318,8 +322,7 @@ function createWebPlacementRuntime({ app, logger = null } = {}) {
       {
         app,
         surface: normalizedSurface,
-        host: normalizedHost,
-        position: normalizedPosition,
+        target: normalizedTarget,
         context: {
           ...contextFromRuntime,
           ...baseContext
@@ -333,14 +336,12 @@ function createWebPlacementRuntime({ app, logger = null } = {}) {
       ...baseContext,
       app,
       surface: normalizedSurface,
-      host: normalizedHost,
-      position: normalizedPosition
+      target: normalizedTarget
     };
 
     debugLog("getPlacements:start", {
       surface: normalizedSurface,
-      host: normalizedHost,
-      position: normalizedPosition,
+      target: normalizedTarget,
       contextKeys: Object.keys(baseContext),
       sharedContextKeys: Object.keys(contextFromRuntime),
       placementCount: placementDefinitions.length
@@ -348,7 +349,7 @@ function createWebPlacementRuntime({ app, logger = null } = {}) {
 
     const matches = [];
     for (const placement of placementDefinitions) {
-      if (placement.host !== normalizedHost || placement.position !== normalizedPosition) {
+      if (placement.target !== normalizedTarget) {
         continue;
       }
       const placementSurfaces = Array.isArray(placement.surfaces)
@@ -403,8 +404,7 @@ function createWebPlacementRuntime({ app, logger = null } = {}) {
 
     debugLog("getPlacements:done", {
       surface: normalizedSurface,
-      host: normalizedHost,
-      position: normalizedPosition,
+      target: normalizedTarget,
       resultIds: matches.map((entry) => entry.id)
     });
 

package/src/client/placement/validators.js

@@ -1,4 +1,5 @@
 import { isRecord, normalizeText } from "@jskit-ai/kernel/shared/support/normalize";
+import { normalizeShellOutletTargetId } from "@jskit-ai/kernel/shared/support/shellLayoutTargets";
 
 const WEB_PLACEMENT_SURFACE_ANY = "*";
 
@@ -24,10 +25,6 @@ function isValidSurfaceIdToken(value = "") {
   return /^[a-z0-9]+(?:[._-][a-z0-9]+)*$/.test(value);
 }
 
-function isValidPlacementHostOrPositionToken(value = "") {
-  return /^[a-z0-9]+(?:[._-][a-z0-9]+)*$/.test(value);
-}
-
 function normalizePlacementSurface(value, { strict = false, source = "placement" } = {}) {
   const normalized = normalizeText(value).toLowerCase();
   if (!normalized) {
@@ -59,40 +56,16 @@ function toInteger(value, fallback = 1000) {
   return Math.trunc(numeric);
 }
 
-function normalizePlacementHost(value, { strict = false, source = "placement" } = {}) {
-  const normalized = normalizeText(value).toLowerCase();
-  if (!normalized) {
-    if (strict) {
-      throw new TypeError(`${source} requires host.`);
-    }
-    return "";
-  }
-
-  if (!isValidPlacementHostOrPositionToken(normalized)) {
-    if (strict) {
-      throw new TypeError(`${source} host "${normalized}" is invalid.`);
-    }
-    return "";
-  }
-  return normalized;
-}
-
-function normalizePlacementPosition(value, { strict = false, source = "placement" } = {}) {
-  const normalized = normalizeText(value).toLowerCase();
-  if (!normalized) {
-    if (strict) {
-      throw new TypeError(`${source} requires position.`);
-    }
-    return "";
+function normalizePlacementTarget(value, { strict = false, source = "placement" } = {}) {
+  const normalized = normalizeShellOutletTargetId(String(value || "").toLowerCase());
+  if (normalized) {
+    return normalized;
   }
 
-  if (!isValidPlacementHostOrPositionToken(normalized)) {
-    if (strict) {
-      throw new TypeError(`${source} position "${normalized}" is invalid.`);
-    }
-    return "";
+  if (strict) {
+    throw new TypeError(`${source} requires target in "host:position" format.`);
   }
-  return normalized;
+  return "";
 }
 
 function normalizePlacementSurfaces(value, { strict = false, source = "placement" } = {}) {
@@ -136,27 +109,26 @@ function normalizePlacementDefinition(value, { strict = false, source = "placeme
     return null;
   }
 
-  const id = normalizeText(value.id);
-  if (!id) {
+  if (Object.hasOwn(value, "host") || Object.hasOwn(value, "position")) {
     if (strict) {
-      throw new TypeError(`${source} requires id.`);
+      throw new TypeError(`${source} must use "target" only. Legacy "host" and "position" fields are not supported.`);
     }
     return null;
   }
 
-  const host = normalizePlacementHost(value.host, {
-    strict,
-    source: `${source} "${id}"`
-  });
-  if (!host) {
+  const id = normalizeText(value.id);
+  if (!id) {
+    if (strict) {
+      throw new TypeError(`${source} requires id.`);
+    }
     return null;
   }
 
-  const position = normalizePlacementPosition(value.position, {
+  const target = normalizePlacementTarget(value.target, {
     strict,
     source: `${source} "${id}"`
   });
-  if (!position) {
+  if (!target) {
     return null;
   }
 
@@ -177,8 +149,7 @@ function normalizePlacementDefinition(value, { strict = false, source = "placeme
 
   return Object.freeze({
     id,
-    host,
-    position,
+    target,
     surfaces,
     order: toInteger(value.order, 1000),
     componentToken,
@@ -200,8 +171,7 @@ export {
   isRenderableComponent,
   normalizeSurface,
   normalizePlacementSurface,
-  normalizePlacementHost,
-  normalizePlacementPosition,
+  normalizePlacementTarget,
   normalizePlacementSurfaces,
   normalizePlacementDefinition,
   definePlacement

package/src/client/support/menuLinkTarget.js

@@ -0,0 +1,97 @@
+import { normalizeText } from "@jskit-ai/kernel/shared/support/normalize";
+import { resolveSurfaceDefinitionFromPlacementContext } from "../placement/surfaceContext.js";
+
+function normalizeMenuLinkPathname(pathname = "") {
+  const source = String(pathname || "").trim();
+  if (!source) {
+    return "";
+  }
+
+  const queryIndex = source.indexOf("?");
+  const hashIndex = source.indexOf("#");
+  const cutoff =
+    queryIndex < 0
+      ? hashIndex
+      : hashIndex < 0
+        ? queryIndex
+        : Math.min(queryIndex, hashIndex);
+
+  return cutoff < 0 ? source : source.slice(0, cutoff);
+}
+
+function resolveMenuLinkSurfaceId(surface = "", fallbackSurfaceId = "") {
+  const explicitSurface = normalizeText(surface).toLowerCase();
+  if (explicitSurface && explicitSurface !== "*") {
+    return explicitSurface;
+  }
+
+  return normalizeText(fallbackSurfaceId).toLowerCase();
+}
+
+function interpolateBracketParams(pathTemplate = "", params = {}) {
+  const source = String(pathTemplate || "").trim();
+  if (!source) {
+    return "";
+  }
+
+  return source.replace(/\[([^\]]+)\]/g, (_match, rawKey) => {
+    const key = String(rawKey || "").trim();
+    if (!key) {
+      return "";
+    }
+
+    const value = params?.[key];
+    return value == null ? `[${key}]` : encodeURIComponent(String(value));
+  });
+}
+
+function isRelativeMenuLinkTarget(target = "") {
+  const normalizedTarget = normalizeText(target);
+  return normalizedTarget.startsWith("./") || normalizedTarget.startsWith("../");
+}
+
+function surfaceRequiresWorkspaceFromPlacementContext(contextValue = null, surfaceId = "") {
+  return Boolean(resolveSurfaceDefinitionFromPlacementContext(contextValue, surfaceId)?.requiresWorkspace);
+}
+
+function resolveMenuLinkTarget({
+  to = "",
+  surface = "",
+  currentSurfaceId = "",
+  placementContext = null,
+  workspaceSuffix = "/",
+  nonWorkspaceSuffix = "/",
+  routeParams = {},
+  resolvePagePath = null
+} = {}) {
+  const explicitTarget = normalizeText(to);
+  const targetSurfaceId = resolveMenuLinkSurfaceId(surface, currentSurfaceId);
+  const workspaceRequired = surfaceRequiresWorkspaceFromPlacementContext(placementContext, targetSurfaceId);
+  const suffixTemplate = normalizeText(workspaceRequired ? workspaceSuffix : nonWorkspaceSuffix) || "/";
+  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 (isRelativeMenuLinkTarget(explicitTarget)) {
+    return resolvedSuffixTarget;
+  }
+
+  return explicitTarget;
+}
+
+export {
+  normalizeMenuLinkPathname,
+  resolveMenuLinkTarget
+};