@jskit-ai/shell-web 0.1.152 → 0.1.153

package/fixtures/adaptive-shell/src/main.js

@@ -52,7 +52,9 @@ function createSurfacePlacement(surface, order, label, suffix) {
 function createSurfacePlacements(surface) {
   return [
     createSurfacePlacement(surface, 10, "Home", "/"),
-    createSurfacePlacement(surface, 20, "Assistant", "/assistant"),
+    surface === "home"
+      ? createSurfacePlacement(surface, 20, "Settings", "/settings")
+      : createSurfacePlacement(surface, 20, "Assistant", "/assistant"),
     createSurfacePlacement(surface, 30, "Contacts", "/contacts"),
     createSurfacePlacement(surface, 40, "Bookings", "/bookings"),
     createSurfacePlacement(surface, 50, "Rostering", "/rostering")
@@ -117,6 +119,8 @@ placementRuntime.setContext({
 
 const routes = [
   { path: "/", redirect: "/home" },
+  { path: "/home/settings", redirect: "/home/settings/general" },
+  { path: "/home/settings/general", component: ScreenPage, meta: { title: "General settings" } },
   { path: "/home/:section?", component: ScreenPage, meta: { title: "Home surface" } },
   { path: "/w/:workspaceSlug/admin/:section?", component: ScreenPage, meta: { title: "Admin surface" } },
   { path: "/help", component: ScreenPage, meta: { title: "Help and support" } }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jskit-ai/shell-web",
-  "version": "0.1.152",
+  "version": "0.1.153",
   "type": "module",
   "scripts": {
     "test": "node --test"
@@ -28,12 +28,583 @@
   },
   "dependencies": {
     "@mdi/js": "^7.4.47",
-    "@jskit-ai/kernel": "0.1.148"
+    "@jskit-ai/kernel": "0.1.149"
   },
   "peerDependencies": {
     "pinia": "^3.0.4",
     "vue": "^3.5.13",
     "vue-router": "^5.0.4",
     "vuetify": "^4.0.0"
+  },
+  "description": "Web shell layout runtime with outlet-based placement contributions.",
+  "jskit": {
+    "kind": "runtime",
+    "capabilities": {
+      "provides": [
+        "runtime.web-placement",
+        "runtime.web-error",
+        "runtime.web-async-module-recovery",
+        "runtime.web-request-recovery"
+      ],
+      "requires": []
+    },
+    "runtime": {
+      "server": {
+        "providers": []
+      },
+      "client": {
+        "providers": [
+          {
+            "entrypoint": "src/client/providers/ShellWebClientProvider.js",
+            "export": "ShellWebClientProvider"
+          }
+        ]
+      }
+    },
+    "metadata": {
+      "client": {
+        "optimizeDeps": {
+          "include": [
+            "@jskit-ai/shell-web/client/placement",
+            "@jskit-ai/shell-web/client/error"
+          ],
+          "exclude": [
+            "@jskit-ai/shell-web/client"
+          ]
+        }
+      },
+      "apiSummary": {
+        "surfaces": [
+          {
+            "subpath": "./client",
+            "summary": "Exports shell layout/outlet/outlet-menu/route-transition/error-host components and ShellWebClientProvider."
+          },
+          {
+            "subpath": "./client/placement",
+            "summary": "Exports placement registry, placement context access, runtime token, and surface path helpers."
+          },
+          {
+            "subpath": "./client/error",
+            "summary": "Exports default error policy and runtime error reporter hook."
+          },
+          {
+            "subpath": "./client/requestRecovery",
+            "summary": "Exports request connectivity recovery classification and runtime access for app-caught request failures."
+          },
+          {
+            "subpath": "./client/bootstrap",
+            "summary": "Exports the shared client bootstrap handler registry used to extend /api/bootstrap handling."
+          },
+          {
+            "subpath": "./test/adaptiveShellSmoke",
+            "summary": "Exports reusable Playwright smoke coverage for generated adaptive shell layouts."
+          }
+        ],
+        "containerTokens": {
+          "server": [],
+          "client": [
+            "runtime.web-placement.client",
+            "runtime.web-bootstrap.client",
+            "runtime.web-refresh.client",
+            "runtime.web-async-module-recovery.client",
+            "runtime.web-request-recovery.client",
+            "runtime.web-error.client",
+            "runtime.web-error.presentation-store.client"
+          ]
+        }
+      },
+      "ui": {
+        "placements": {
+          "outlets": [
+            {
+              "target": "shell-layout:top-left",
+              "surfaces": [
+                "*"
+              ],
+              "source": "src/client/components/ShellLayout.vue"
+            },
+            {
+              "target": "shell-layout:top-right",
+              "surfaces": [
+                "*"
+              ],
+              "source": "src/client/components/ShellLayout.vue"
+            },
+            {
+              "target": "shell-layout:primary-menu",
+              "surfaces": [
+                "*"
+              ],
+              "source": "src/client/components/ShellLayout.vue"
+            },
+            {
+              "target": "shell-layout:primary-bottom-nav",
+              "surfaces": [
+                "*"
+              ],
+              "source": "src/client/components/ShellLayout.vue"
+            },
+            {
+              "target": "shell-layout:secondary-menu",
+              "surfaces": [
+                "*"
+              ],
+              "source": "src/client/components/ShellLayout.vue"
+            },
+            {
+              "target": "shell-layout:supporting-bottom-sheet",
+              "surfaces": [
+                "*"
+              ],
+              "source": "src/client/components/ShellLayout.vue"
+            },
+            {
+              "target": "shell-layout:supporting-side-panel",
+              "surfaces": [
+                "*"
+              ],
+              "source": "src/client/components/ShellLayout.vue"
+            },
+            {
+              "target": "home-settings:primary-menu",
+              "surfaces": [
+                "home"
+              ],
+              "source": "templates/src/pages/home/settings.vue"
+            }
+          ],
+          "topology": {
+            "placements": [
+              {
+                "id": "shell.primary-nav",
+                "description": "Primary top-level navigation for the current surface.",
+                "surfaces": [
+                  "*"
+                ],
+                "default": true,
+                "variants": {
+                  "compact": {
+                    "outlet": "shell-layout:primary-bottom-nav",
+                    "renderers": {
+                      "link": "local.main.ui.tab-link-item"
+                    }
+                  },
+                  "medium": {
+                    "outlet": "shell-layout:primary-menu",
+                    "renderers": {
+                      "link": "local.main.ui.surface-aware-menu-link-item"
+                    }
+                  },
+                  "expanded": {
+                    "outlet": "shell-layout:primary-menu",
+                    "renderers": {
+                      "link": "local.main.ui.surface-aware-menu-link-item"
+                    }
+                  }
+                }
+              },
+              {
+                "id": "shell.status",
+                "description": "Surface status, connection, and utility indicators.",
+                "surfaces": [
+                  "*"
+                ],
+                "variants": {
+                  "compact": {
+                    "outlet": "shell-layout:top-right"
+                  },
+                  "medium": {
+                    "outlet": "shell-layout:top-right"
+                  },
+                  "expanded": {
+                    "outlet": "shell-layout:top-right"
+                  }
+                }
+              },
+              {
+                "id": "shell.secondary-nav",
+                "description": "Secondary navigation for lower-priority shell links.",
+                "surfaces": [
+                  "*"
+                ],
+                "variants": {
+                  "compact": {
+                    "outlet": "shell-layout:secondary-menu",
+                    "renderers": {
+                      "link": "local.main.ui.surface-aware-menu-link-item"
+                    }
+                  },
+                  "medium": {
+                    "outlet": "shell-layout:secondary-menu",
+                    "renderers": {
+                      "link": "local.main.ui.surface-aware-menu-link-item"
+                    }
+                  },
+                  "expanded": {
+                    "outlet": "shell-layout:secondary-menu",
+                    "renderers": {
+                      "link": "local.main.ui.surface-aware-menu-link-item"
+                    }
+                  }
+                }
+              },
+              {
+                "id": "shell.identity",
+                "description": "Current user, workspace, and surface identity controls.",
+                "surfaces": [
+                  "*"
+                ],
+                "variants": {
+                  "compact": {
+                    "outlet": "shell-layout:top-left"
+                  },
+                  "medium": {
+                    "outlet": "shell-layout:top-left"
+                  },
+                  "expanded": {
+                    "outlet": "shell-layout:top-left"
+                  }
+                }
+              },
+              {
+                "id": "shell.global-actions",
+                "description": "Global surface actions that should stay outside primary navigation.",
+                "surfaces": [
+                  "*"
+                ],
+                "variants": {
+                  "compact": {
+                    "outlet": "shell-layout:top-right",
+                    "renderers": {
+                      "link": "local.main.ui.surface-aware-menu-link-item"
+                    }
+                  },
+                  "medium": {
+                    "outlet": "shell-layout:top-right",
+                    "renderers": {
+                      "link": "local.main.ui.surface-aware-menu-link-item"
+                    }
+                  },
+                  "expanded": {
+                    "outlet": "shell-layout:top-right",
+                    "renderers": {
+                      "link": "local.main.ui.surface-aware-menu-link-item"
+                    }
+                  }
+                }
+              },
+              {
+                "id": "page.supporting-content",
+                "description": "Supporting page content that opens as a bottom sheet on compact layouts and a side panel on wider layouts.",
+                "surfaces": [
+                  "*"
+                ],
+                "variants": {
+                  "compact": {
+                    "outlet": "shell-layout:supporting-bottom-sheet"
+                  },
+                  "medium": {
+                    "outlet": "shell-layout:supporting-side-panel"
+                  },
+                  "expanded": {
+                    "outlet": "shell-layout:supporting-side-panel"
+                  }
+                }
+              },
+              {
+                "id": "page.section-nav",
+                "owner": "home-settings",
+                "description": "Navigation between child pages in the home settings section.",
+                "surfaces": [
+                  "home"
+                ],
+                "variants": {
+                  "compact": {
+                    "outlet": "home-settings:primary-menu",
+                    "renderers": {
+                      "link": "local.main.ui.surface-aware-menu-link-item"
+                    }
+                  },
+                  "medium": {
+                    "outlet": "home-settings:primary-menu",
+                    "renderers": {
+                      "link": "local.main.ui.surface-aware-menu-link-item"
+                    }
+                  },
+                  "expanded": {
+                    "outlet": "home-settings:primary-menu",
+                    "renderers": {
+                      "link": "local.main.ui.surface-aware-menu-link-item"
+                    }
+                  }
+                }
+              }
+            ]
+          },
+          "contributions": [
+            {
+              "id": "shell-web.home.menu.home",
+              "target": "shell.primary-nav",
+              "kind": "link",
+              "surfaces": [
+                "home"
+              ],
+              "order": 50,
+              "source": "templates/src/placement.js"
+            },
+            {
+              "id": "shell-web.home.menu.settings",
+              "target": "shell.primary-nav",
+              "kind": "link",
+              "surfaces": [
+                "home"
+              ],
+              "order": 100,
+              "source": "templates/src/placement.js"
+            },
+            {
+              "id": "shell-web.home.settings.general",
+              "target": "page.section-nav",
+              "owner": "home-settings",
+              "kind": "link",
+              "surfaces": [
+                "home"
+              ],
+              "order": 100,
+              "source": "templates/src/placement.js"
+            }
+          ]
+        }
+      }
+    },
+    "mutations": {
+      "dependencies": {
+        "runtime": {
+          "@mdi/js": "^7.4.47",
+          "@jskit-ai/kernel": "0.1.149"
+        },
+        "dev": {
+          "@playwright/test": "1.61.1"
+        }
+      },
+      "packageJson": {
+        "scripts": {
+          "dev:all": "vite",
+          "dev:home": "VITE_SURFACE=home vite"
+        }
+      },
+      "procfile": {},
+      "text": [],
+      "source": [
+        {
+          "op": "ensure-import",
+          "file": "packages/main/src/client/providers/MainClientProvider.js",
+          "defaultImport": "MenuLinkItem",
+          "from": "/src/components/menus/MenuLinkItem.vue",
+          "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": "ensure-import",
+          "file": "packages/main/src/client/providers/MainClientProvider.js",
+          "defaultImport": "SurfaceAwareMenuLinkItem",
+          "from": "/src/components/menus/SurfaceAwareMenuLinkItem.vue",
+          "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": "ensure-import",
+          "file": "packages/main/src/client/providers/MainClientProvider.js",
+          "defaultImport": "TabLinkItem",
+          "from": "/src/components/menus/TabLinkItem.vue",
+          "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": "ensure-call",
+          "file": "packages/main/src/client/providers/MainClientProvider.js",
+          "callee": "registerMainClientComponent",
+          "args": [
+            "\"local.main.ui.menu-link-item\"",
+            "() => MenuLinkItem"
+          ],
+          "beforeClass": "MainClientProvider",
+          "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": "ensure-call",
+          "file": "packages/main/src/client/providers/MainClientProvider.js",
+          "callee": "registerMainClientComponent",
+          "args": [
+            "\"local.main.ui.surface-aware-menu-link-item\"",
+            "() => SurfaceAwareMenuLinkItem"
+          ],
+          "beforeClass": "MainClientProvider",
+          "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": "ensure-call",
+          "file": "packages/main/src/client/providers/MainClientProvider.js",
+          "callee": "registerMainClientComponent",
+          "args": [
+            "\"local.main.ui.tab-link-item\"",
+            "() => TabLinkItem"
+          ],
+          "beforeClass": "MainClientProvider",
+          "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"
+        },
+        {
+          "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"
+        },
+        {
+          "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"
+        },
+        {
+          "from": "templates/src/placementTopology.js",
+          "to": "src/placementTopology.js",
+          "ownership": "app",
+          "reason": "Install app-owned semantic placement topology used by shell-web placement runtime.",
+          "category": "shell-web",
+          "id": "shell-web-placement-topology"
+        },
+        {
+          "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",
+          "when": {
+            "config": "surfaceDefinitions.home.enabled",
+            "equals": "true"
+          }
+        },
+        {
+          "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",
+          "when": {
+            "config": "surfaceDefinitions.home.enabled",
+            "equals": "true"
+          }
+        },
+        {
+          "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",
+          "when": {
+            "config": "surfaceDefinitions.home.enabled",
+            "equals": "true"
+          }
+        },
+        {
+          "from": "templates/src/pages/home/settings/index.vue",
+          "toSurface": "home",
+          "toSurfacePath": "settings/index.vue",
+          "ownership": "app",
+          "reason": "Install shell-driven home settings redirect so the starter settings shell lands on a real child page.",
+          "category": "shell-web",
+          "id": "shell-web-page-home-settings",
+          "when": {
+            "config": "surfaceDefinitions.home.enabled",
+            "equals": "true"
+          }
+        },
+        {
+          "from": "templates/src/pages/home/settings/general/index.vue",
+          "toSurface": "home",
+          "toSurfacePath": "settings/general/index.vue",
+          "ownership": "app",
+          "reason": "Install shell-driven general settings child page with a tiny browser-local shell preference example.",
+          "category": "shell-web",
+          "id": "shell-web-page-home-settings-general",
+          "when": {
+            "config": "surfaceDefinitions.home.enabled",
+            "equals": "true"
+          }
+        },
+        {
+          "from": "templates/tests/e2e/adaptive-shell.spec.ts",
+          "to": "tests/e2e/adaptive-shell.spec.ts",
+          "ownership": "app",
+          "reason": "Install compact/medium/expanded Playwright smoke coverage for the adaptive shell.",
+          "category": "shell-web",
+          "id": "shell-web-test-adaptive-shell-smoke"
+        }
+      ]
+    }
   }
 }

package/src/test/adaptiveShellSmoke.js

@@ -192,6 +192,20 @@ async function readNavigationIconCenters(drawer) {
   return centers;
 }
 
+function isRequestedOrDescendantLocation(actualUrl, targetUrl) {
+  const normalizePathname = (value) => {
+    const pathname = String(value || "/");
+    return pathname === "/" ? pathname : pathname.replace(/\/+$/u, "");
+  };
+  const actualPathname = normalizePathname(actualUrl.pathname);
+  const targetPathname = normalizePathname(targetUrl.pathname);
+  const pathMatches = actualPathname === targetPathname || (
+    targetPathname !== "/" && actualPathname.startsWith(`${targetPathname}/`)
+  );
+
+  return pathMatches && actualUrl.search === targetUrl.search;
+}
+
 async function expectCentredRailNavigation(page, drawer, expect, expandedIconCenters) {
   const links = drawer.locator("a.shell-menu-link-item[href]");
   await expect(links.first()).toBeVisible();
@@ -236,8 +250,14 @@ async function expectCentredRailNavigation(page, drawer, expect, expandedIconCen
   await navigationLink.locator(".v-icon").first().click();
   await expect.poll(() => {
     const actual = new URL(page.url());
-    return `${actual.pathname}${actual.search}`;
-  }).toBe(`${targetUrl.pathname}${targetUrl.search}`);
+    const leftOriginalLocation = (
+      actual.pathname !== currentUrl.pathname ||
+      actual.search !== currentUrl.search
+    );
+    return leftOriginalLocation && isRequestedOrDescendantLocation(actual, targetUrl);
+  }, {
+    message: "Shell navigation did not reach the requested route or its canonical descendant."
+  }).toBe(true);
 }
 
 async function openCompactDrawer(page, expect) {
@@ -339,4 +359,9 @@ function runAdaptiveShellSmoke({
   });
 }
 
-export { DEFAULT_VIEWPORTS, runAdaptiveShellSmoke, runAdaptiveShellSmokeCase };
+export {
+  DEFAULT_VIEWPORTS,
+  isRequestedOrDescendantLocation,
+  runAdaptiveShellSmoke,
+  runAdaptiveShellSmokeCase
+};