@jskit-ai/shell-web 0.1.31 → 0.1.33

package/package.descriptor.mjs

@@ -1,7 +1,7 @@
 export default Object.freeze({
   packageVersion: 1,
   packageId: "@jskit-ai/shell-web",
-  version: "0.1.31",
+  version: "0.1.33",
   kind: "runtime",
   description: "Web shell layout runtime with outlet-based placement contributions.",
   dependsOn: [],
@@ -30,7 +30,7 @@ export default Object.freeze({
       surfaces: [
         {
           subpath: "./client",
-          summary: "Exports shell layout/outlet/error-host components and ShellWebClientProvider."
+          summary: "Exports shell layout/outlet/outlet-menu/error-host components and ShellWebClientProvider."
         },
         {
           subpath: "./client/placement",
@@ -55,32 +55,30 @@ export default Object.freeze({
       placements: {
         outlets: [
           {
-            host: "shell-layout",
-            position: "top-left",
+            target: "shell-layout:top-left",
             surfaces: ["*"],
             source: "src/client/components/ShellLayout.vue"
           },
           {
-            host: "shell-layout",
-            position: "top-right",
+            target: "shell-layout:top-right",
             surfaces: ["*"],
             source: "src/client/components/ShellLayout.vue"
           },
           {
-            host: "shell-layout",
-            position: "primary-menu",
+            target: "shell-layout:primary-menu",
+            defaultLinkComponentToken: "local.main.ui.surface-aware-menu-link-item",
             surfaces: ["*"],
             source: "src/client/components/ShellLayout.vue"
           },
           {
-            host: "shell-layout",
-            position: "secondary-menu",
+            target: "shell-layout:secondary-menu",
+            defaultLinkComponentToken: "local.main.ui.surface-aware-menu-link-item",
             surfaces: ["*"],
             source: "src/client/components/ShellLayout.vue"
           },
           {
-            host: "home-settings",
-            position: "primary-menu",
+            target: "home-settings:primary-menu",
+            defaultLinkComponentToken: "local.main.ui.surface-aware-menu-link-item",
             surfaces: ["home"],
             source: "templates/src/pages/home/settings.vue"
           }
@@ -92,8 +90,9 @@ export default Object.freeze({
   mutations: {
     dependencies: {
       runtime: {
+        "@mdi/js": "^7.4.47",
         "@tanstack/vue-query": "^5.90.5",
-        "@jskit-ai/kernel": "0.1.32",
+        "@jskit-ai/kernel": "0.1.34",
         "vuetify": "^4.0.0"
       },
       dev: {}
@@ -106,11 +105,74 @@ export default Object.freeze({
       }
     },
     procfile: {},
-    text: [],
+    text: [
+      {
+        op: "append-text",
+        file: "packages/main/src/client/providers/MainClientProvider.js",
+        position: "top",
+        skipIfContains: "import MenuLinkItem from \"/src/components/menus/MenuLinkItem.vue\";",
+        value: "import MenuLinkItem from \"/src/components/menus/MenuLinkItem.vue\";\n",
+        reason: "Bind app-owned shell menu link-item scaffold into local main client provider imports.",
+        category: "shell-web",
+        id: "shell-web-main-client-provider-menu-link-item-import"
+      },
+      {
+        op: "append-text",
+        file: "packages/main/src/client/providers/MainClientProvider.js",
+        position: "top",
+        skipIfContains: "import SurfaceAwareMenuLinkItem from \"/src/components/menus/SurfaceAwareMenuLinkItem.vue\";",
+        value: "import SurfaceAwareMenuLinkItem from \"/src/components/menus/SurfaceAwareMenuLinkItem.vue\";\n",
+        reason: "Bind app-owned shell surface-aware menu link-item scaffold into local main client provider imports.",
+        category: "shell-web",
+        id: "shell-web-main-client-provider-surface-aware-menu-link-item-import"
+      },
+      {
+        op: "append-text",
+        file: "packages/main/src/client/providers/MainClientProvider.js",
+        position: "top",
+        skipIfContains: "import TabLinkItem from \"/src/components/menus/TabLinkItem.vue\";",
+        value: "import TabLinkItem from \"/src/components/menus/TabLinkItem.vue\";\n",
+        reason: "Bind app-owned shell tab link-item scaffold into local main client provider imports.",
+        category: "shell-web",
+        id: "shell-web-main-client-provider-tab-link-item-import"
+      },
+      {
+        op: "append-text",
+        file: "packages/main/src/client/providers/MainClientProvider.js",
+        position: "bottom",
+        skipIfContains: "registerMainClientComponent(\"local.main.ui.menu-link-item\", () => MenuLinkItem);",
+        value: "\nregisterMainClientComponent(\"local.main.ui.menu-link-item\", () => MenuLinkItem);\n",
+        reason: "Bind app-owned shell menu link-item token into local main client provider registry.",
+        category: "shell-web",
+        id: "shell-web-main-client-provider-menu-link-item-register"
+      },
+      {
+        op: "append-text",
+        file: "packages/main/src/client/providers/MainClientProvider.js",
+        position: "bottom",
+        skipIfContains: "registerMainClientComponent(\"local.main.ui.surface-aware-menu-link-item\", () => SurfaceAwareMenuLinkItem);",
+        value: "\nregisterMainClientComponent(\"local.main.ui.surface-aware-menu-link-item\", () => SurfaceAwareMenuLinkItem);\n",
+        reason: "Bind app-owned shell surface-aware menu link-item token into local main client provider registry.",
+        category: "shell-web",
+        id: "shell-web-main-client-provider-surface-aware-menu-link-item-register"
+      },
+      {
+        op: "append-text",
+        file: "packages/main/src/client/providers/MainClientProvider.js",
+        position: "bottom",
+        skipIfContains: "registerMainClientComponent(\"local.main.ui.tab-link-item\", () => TabLinkItem);",
+        value: "\nregisterMainClientComponent(\"local.main.ui.tab-link-item\", () => TabLinkItem);\n",
+        reason: "Bind app-owned shell tab link-item token into local main client provider registry.",
+        category: "shell-web",
+        id: "shell-web-main-client-provider-tab-link-item-register"
+      }
+    ],
     files: [
       {
         from: "templates/src/App.vue",
         to: "src/App.vue",
+        ownership: "app",
+        expectedExistingFrom: "templates/expected-existing/src/App.vue",
         reason: "Install full-width shell app root with shell-web error host and edge-to-edge layout.",
         category: "shell-web",
         id: "shell-web-app-root"
@@ -118,13 +180,39 @@ export default Object.freeze({
       {
         from: "templates/src/components/ShellLayout.vue",
         to: "src/components/ShellLayout.vue",
+        ownership: "app",
         reason: "Install app-owned shell layout component so apps can customize structure and slots.",
         category: "shell-web",
         id: "shell-web-component-shell-layout"
       },
+      {
+        from: "templates/src/components/menus/MenuLinkItem.vue",
+        to: "src/components/menus/MenuLinkItem.vue",
+        ownership: "app",
+        reason: "Install app-owned shell menu link-item scaffold for local placement customization.",
+        category: "shell-web",
+        id: "shell-web-component-menu-link-item"
+      },
+      {
+        from: "templates/src/components/menus/SurfaceAwareMenuLinkItem.vue",
+        to: "src/components/menus/SurfaceAwareMenuLinkItem.vue",
+        ownership: "app",
+        reason: "Install app-owned surface-aware shell menu link-item scaffold for local placement customization.",
+        category: "shell-web",
+        id: "shell-web-component-surface-aware-menu-link-item"
+      },
+      {
+        from: "templates/src/components/menus/TabLinkItem.vue",
+        to: "src/components/menus/TabLinkItem.vue",
+        ownership: "app",
+        reason: "Install app-owned shell tab link-item scaffold for local placement customization.",
+        category: "shell-web",
+        id: "shell-web-component-tab-link-item"
+      },
       {
         from: "templates/src/error.js",
         to: "src/error.js",
+        ownership: "app",
         reason: "Install app-owned error runtime policy and presenter config scaffold.",
         category: "shell-web",
         id: "shell-web-error-config"
@@ -132,6 +220,7 @@ export default Object.freeze({
       {
         from: "templates/src/placement.js",
         to: "src/placement.js",
+        ownership: "app",
         reason: "Install app-owned placement registry scaffold used by shell-web placement runtime.",
         category: "shell-web",
         id: "shell-web-placement-registry"
@@ -140,6 +229,8 @@ export default Object.freeze({
         from: "templates/src/pages/home.vue",
         toSurface: "home",
         toSurfaceRoot: true,
+        ownership: "app",
+        expectedExistingFrom: "templates/expected-existing/src/pages/home.vue",
         reason: "Install shell-driven home wrapper page.",
         category: "shell-web",
         id: "shell-web-page-home-wrapper"
@@ -148,6 +239,8 @@ export default Object.freeze({
         from: "templates/src/pages/home/index.vue",
         toSurface: "home",
         toSurfacePath: "index.vue",
+        ownership: "app",
+        expectedExistingFrom: "templates/expected-existing/src/pages/home/index.vue",
         reason: "Install shell-driven home surface starter page.",
         category: "shell-web",
         id: "shell-web-page-home"
@@ -156,6 +249,7 @@ export default Object.freeze({
         from: "templates/src/pages/home/settings.vue",
         toSurface: "home",
         toSurfacePath: "settings.vue",
+        ownership: "app",
         reason: "Install shell-driven home settings shell route with section navigation.",
         category: "shell-web",
         id: "shell-web-page-home-settings-shell"
@@ -164,7 +258,8 @@ export default Object.freeze({
         from: "templates/src/pages/home/settings/index.vue",
         toSurface: "home",
         toSurfacePath: "settings/index.vue",
-        reason: "Install shell-driven home settings landing page scaffold.",
+        ownership: "app",
+        reason: "Install shell-driven home settings index stub scaffold for app-owned landing or redirect behavior.",
         category: "shell-web",
         id: "shell-web-page-home-settings"
       },
@@ -172,6 +267,8 @@ export default Object.freeze({
         from: "templates/src/pages/console.vue",
         toSurface: "console",
         toSurfaceRoot: true,
+        ownership: "app",
+        expectedExistingFrom: "templates/expected-existing/src/pages/console.vue",
         reason: "Install shell-driven console wrapper page.",
         category: "shell-web",
         id: "shell-web-page-console-wrapper"
@@ -180,6 +277,8 @@ export default Object.freeze({
         from: "templates/src/pages/console/index.vue",
         toSurface: "console",
         toSurfacePath: "index.vue",
+        ownership: "app",
+        expectedExistingFrom: "templates/expected-existing/src/pages/console/index.vue",
         reason: "Install shell-driven console page starter.",
         category: "shell-web",
         id: "shell-web-page-console"

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jskit-ai/shell-web",
-  "version": "0.1.31",
+  "version": "0.1.33",
   "type": "module",
   "scripts": {
     "test": "node --test"
@@ -9,16 +9,22 @@
     "./client": "./src/client/index.js",
     "./client/error": "./src/client/error/index.js",
     "./client/placement": "./src/client/placement/index.js",
+    "./server/support/localLinkItemScaffolds": "./src/server/support/localLinkItemScaffolds.js",
     "./client/navigation/linkResolver": "./src/client/navigation/linkResolver.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",
     "./client/components/ShellErrorHost": "./src/client/components/ShellErrorHost.vue",
+    "./client/components/ShellMenuLinkItem": "./src/client/components/ShellMenuLinkItem.vue",
+    "./client/components/ShellSurfaceAwareMenuLinkItem": "./src/client/components/ShellSurfaceAwareMenuLinkItem.vue",
+    "./client/components/ShellTabLinkItem": "./src/client/components/ShellTabLinkItem.vue",
     "./client/composables/useShellLayoutState": "./src/client/composables/useShellLayoutState.js",
     "./client/providers/ShellWebClientProvider": "./src/client/providers/ShellWebClientProvider.js"
   },
   "dependencies": {
+    "@mdi/js": "^7.4.47",
     "@tanstack/vue-query": "^5.90.5",
-    "@jskit-ai/kernel": "0.1.32",
+    "@jskit-ai/kernel": "0.1.34",
     "vuetify": "^4.0.0"
   }
 }

package/src/client/components/ShellLayout.vue

@@ -32,7 +32,7 @@ const { drawerOpen, toggleDrawer, resolvedSurface, resolvedSurfaceLabel } = useS
       <slot name="top-left" :surface="resolvedSurface">
         <div class="d-flex align-center ga-2">
           <v-chip color="primary" size="small" label>{{ resolvedSurfaceLabel }}</v-chip>
-          <ShellOutlet host="shell-layout" position="top-left" />
+          <ShellOutlet target="shell-layout:top-left" />
         </div>
       </slot>
 
@@ -40,7 +40,7 @@ const { drawerOpen, toggleDrawer, resolvedSurface, resolvedSurfaceLabel } = useS
 
       <slot name="top-right" :surface="resolvedSurface">
         <div class="d-flex align-center ga-2">
-          <ShellOutlet host="shell-layout" position="top-right" />
+          <ShellOutlet target="shell-layout:top-right" />
         </div>
       </slot>
     </v-app-bar>
@@ -49,9 +49,16 @@ const { drawerOpen, toggleDrawer, resolvedSurface, resolvedSurfaceLabel } = useS
       <slot name="menu" :surface="resolvedSurface">
         <v-list nav density="comfortable" class="pt-2">
           <v-list-subheader class="text-uppercase text-caption">{{ resolvedSurfaceLabel }}</v-list-subheader>
-          <ShellOutlet host="shell-layout" position="primary-menu" default />
+          <ShellOutlet
+            target="shell-layout:primary-menu"
+            default
+            default-link-component-token="local.main.ui.surface-aware-menu-link-item"
+          />
           <v-divider class="my-2" />
-          <ShellOutlet host="shell-layout" position="secondary-menu" />
+          <ShellOutlet
+            target="shell-layout:secondary-menu"
+            default-link-component-token="local.main.ui.surface-aware-menu-link-item"
+          />
         </v-list>
       </slot>
     </v-navigation-drawer>

package/src/client/components/ShellMenuLinkItem.vue

@@ -0,0 +1,71 @@
+<script setup>
+import { computed } from "vue";
+import {
+  resolveSurfaceNavigationTargetFromPlacementContext,
+  useWebPlacementContext
+} from "../placement/index.js";
+import { resolveMenuLinkIcon } from "../lib/menuIcons.js";
+
+const props = defineProps({
+  label: {
+    type: String,
+    default: ""
+  },
+  to: {
+    type: String,
+    default: ""
+  },
+  icon: {
+    type: String,
+    default: ""
+  },
+  disabled: {
+    type: Boolean,
+    default: false
+  },
+  exact: {
+    type: Boolean,
+    default: false
+  }
+});
+
+const { context: placementContext } = useWebPlacementContext();
+
+const resolvedTarget = computed(() => {
+  const target = String(props.to || "").trim();
+  if (!target) {
+    return {
+      href: "",
+      sameOrigin: true
+    };
+  }
+
+  const navigationTarget = resolveSurfaceNavigationTargetFromPlacementContext(placementContext.value, {
+    path: target
+  });
+  return {
+    href: navigationTarget.href,
+    sameOrigin: navigationTarget.sameOrigin
+  };
+});
+
+const resolvedIcon = computed(() =>
+  resolveMenuLinkIcon({
+    icon: props.icon,
+    label: props.label,
+    to: resolvedTarget.value.href || props.to
+  })
+);
+</script>
+
+<template>
+  <v-list-item
+    v-if="resolvedTarget.href"
+    :title="props.label"
+    :to="resolvedTarget.sameOrigin ? resolvedTarget.href : undefined"
+    :href="resolvedTarget.sameOrigin ? undefined : resolvedTarget.href"
+    :prepend-icon="resolvedIcon || undefined"
+    :disabled="props.disabled"
+    :exact="props.exact"
+  />
+</template>

package/src/client/components/ShellOutlet.vue

@@ -14,11 +14,7 @@ import {
 } from "../placement/surfaceContext.js";
 
 const props = defineProps({
-  host: {
-    type: String,
-    default: ""
-  },
-  position: {
+  target: {
     type: String,
     default: ""
   },
@@ -29,6 +25,10 @@ const props = defineProps({
   context: {
     type: Object,
     default: () => ({})
+  },
+  defaultLinkComponentToken: {
+    type: String,
+    default: ""
   }
 });
 
@@ -78,12 +78,15 @@ const resolvedSurface = computed(() => {
   return "*";
 });
 
+const resolvedTargetId = computed(() => {
+  return String(props.target || "").trim();
+});
+
 const placements = computed(() => {
   void revision.value;
   return placementRuntime.getPlacements({
     surface: resolvedSurface.value,
-    host: props.host,
-    position: props.position,
+    target: resolvedTargetId.value,
     context: props.context
   });
 });

package/src/client/components/ShellOutletMenuWidget.vue

@@ -0,0 +1,57 @@
+<script setup>
+import { mdiCogOutline } from "@mdi/js";
+import ShellOutlet from "./ShellOutlet.vue";
+
+const props = defineProps({
+  target: {
+    type: String,
+    required: true
+  },
+  defaultLinkComponentToken: {
+    type: String,
+    default: ""
+  },
+  icon: {
+    type: String,
+    default: mdiCogOutline
+  },
+  ariaLabel: {
+    type: String,
+    default: "Tools"
+  },
+  location: {
+    type: String,
+    default: "bottom end"
+  },
+  offset: {
+    type: [Number, String],
+    default: 10
+  },
+  minWidth: {
+    type: [Number, String],
+    default: 220
+  }
+});
+</script>
+
+<template>
+  <v-menu :location="props.location" :offset="props.offset" eager>
+    <template #activator="{ props: activatorProps }">
+      <v-btn
+        v-bind="activatorProps"
+        icon
+        variant="text"
+        :aria-label="props.ariaLabel"
+      >
+        <v-icon :icon="props.icon" />
+      </v-btn>
+    </template>
+
+    <v-list :min-width="props.minWidth" density="comfortable" class="py-1">
+      <ShellOutlet
+        :target="props.target"
+        :default-link-component-token="props.defaultLinkComponentToken"
+      />
+    </v-list>
+  </v-menu>
+</template>

package/src/client/components/ShellSurfaceAwareMenuLinkItem.vue

@@ -0,0 +1,116 @@
+<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 { resolveMenuLinkIcon } from "../lib/menuIcons.js";
+import { resolveMenuLinkTarget } from "../support/menuLinkTarget.js";
+
+const props = defineProps({
+  label: {
+    type: String,
+    default: ""
+  },
+  to: {
+    type: String,
+    default: ""
+  },
+  icon: {
+    type: String,
+    default: ""
+  },
+  surface: {
+    type: String,
+    default: ""
+  },
+  workspaceSuffix: {
+    type: String,
+    default: "/"
+  },
+  nonWorkspaceSuffix: {
+    type: String,
+    default: "/"
+  },
+  disabled: {
+    type: Boolean,
+    default: false
+  },
+  exact: {
+    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 resolvedIcon = computed(() =>
+  resolveMenuLinkIcon({
+    icon: props.icon,
+    label: props.label,
+    to: resolvedTarget.value.href || resolvedTo.value
+  })
+);
+</script>
+
+<template>
+  <v-list-item
+    v-if="resolvedTarget.href"
+    :title="props.label"
+    :to="resolvedTarget.sameOrigin ? resolvedTarget.href : undefined"
+    :href="resolvedTarget.sameOrigin ? undefined : resolvedTarget.href"
+    :prepend-icon="resolvedIcon || undefined"
+    :disabled="props.disabled"
+    :exact="props.exact"
+  />
+</template>