@jskit-ai/shell-web 0.1.64 → 0.1.66

package/templates/src/placementTopology.js

@@ -0,0 +1,149 @@
+const placements = [];
+
+function addPlacementTopology(value = {}) {
+  placements.push(value);
+}
+
+export { addPlacementTopology };
+export default { placements };
+
+const menuLinkRenderers = Object.freeze({
+  link: "local.main.ui.surface-aware-menu-link-item"
+});
+
+const bottomNavLinkRenderers = Object.freeze({
+  link: "local.main.ui.tab-link-item"
+});
+
+addPlacementTopology({
+  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: bottomNavLinkRenderers
+    },
+    medium: {
+      outlet: "shell-layout:primary-menu",
+      renderers: menuLinkRenderers
+    },
+    expanded: {
+      outlet: "shell-layout:primary-menu",
+      renderers: menuLinkRenderers
+    }
+  }
+});
+
+addPlacementTopology({
+  id: "shell.secondary-nav",
+  description: "Secondary navigation for the current surface.",
+  surfaces: ["*"],
+  variants: {
+    compact: {
+      outlet: "shell-layout:secondary-menu",
+      renderers: menuLinkRenderers
+    },
+    medium: {
+      outlet: "shell-layout:secondary-menu",
+      renderers: menuLinkRenderers
+    },
+    expanded: {
+      outlet: "shell-layout:secondary-menu",
+      renderers: menuLinkRenderers
+    }
+  }
+});
+
+addPlacementTopology({
+  id: "shell.identity",
+  description: "Current surface identity and switcher controls.",
+  surfaces: ["*"],
+  variants: {
+    compact: {
+      outlet: "shell-layout:top-left"
+    },
+    medium: {
+      outlet: "shell-layout:top-left"
+    },
+    expanded: {
+      outlet: "shell-layout:top-left"
+    }
+  }
+});
+
+addPlacementTopology({
+  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"
+    }
+  }
+});
+
+addPlacementTopology({
+  id: "shell.global-actions",
+  description: "Global surface actions that should stay outside primary navigation.",
+  surfaces: ["*"],
+  variants: {
+    compact: {
+      outlet: "shell-layout:top-right",
+      renderers: menuLinkRenderers
+    },
+    medium: {
+      outlet: "shell-layout:top-right",
+      renderers: menuLinkRenderers
+    },
+    expanded: {
+      outlet: "shell-layout:top-right",
+      renderers: menuLinkRenderers
+    }
+  }
+});
+
+addPlacementTopology({
+  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"
+    }
+  }
+});
+
+addPlacementTopology({
+  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: menuLinkRenderers
+    },
+    medium: {
+      outlet: "home-settings:primary-menu",
+      renderers: menuLinkRenderers
+    },
+    expanded: {
+      outlet: "home-settings:primary-menu",
+      renderers: menuLinkRenderers
+    }
+  }
+});

package/templates/tests/e2e/adaptive-shell.spec.ts

@@ -0,0 +1,4 @@
+import { expect, test } from "@playwright/test";
+import { runAdaptiveShellSmoke } from "@jskit-ai/shell-web/test/adaptiveShellSmoke";
+
+runAdaptiveShellSmoke({ test, expect });

package/test/errorRuntime.test.js

@@ -1,5 +1,6 @@
 import assert from "node:assert/strict";
 import test from "node:test";
+import { createDefaultErrorPolicy } from "../src/client/error/policy.js";
 import { createErrorRuntime } from "../src/client/error/runtime.js";
 
 function createPresenter(id, {
@@ -25,6 +26,47 @@ function createPresenter(id, {
   });
 }
 
+test("default error policy maps intent to presentation instead of status alone", () => {
+  const policy = createDefaultErrorPolicy();
+
+  assert.equal(policy({ intent: "resource-load", message: "Load failed" }).channel, "silent");
+  assert.equal(policy({ intent: "action-feedback", message: "Save failed" }).channel, "snackbar");
+  assert.equal(policy({ intent: "app-recoverable", message: "Offline" }).channel, "banner");
+  assert.equal(policy({ intent: "blocking", message: "Fatal" }).channel, "dialog");
+  assert.equal(policy({ blocking: true, message: "Fatal" }).channel, "dialog");
+  assert.equal(policy({ status: 500, message: "Server failed" }).channel, "snackbar");
+  assert.equal(
+    policy({ intent: "resource-load", channel: "banner", message: "Load failed" }).channel,
+    "banner"
+  );
+});
+
+test("error runtime treats resource load errors as silent by default", () => {
+  const calls = [];
+  const runtime = createErrorRuntime({
+    presenters: [
+      createPresenter("module.presenter", { calls })
+    ],
+    moduleDefaultPresenterId: "module.presenter"
+  });
+
+  const result = runtime.report({
+    kind: "resource-load",
+    message: "Unable to load records.",
+    status: 500,
+    action: {
+      label: "Retry",
+      handler() {}
+    }
+  });
+
+  assert.equal(result.skipped, true);
+  assert.equal(result.reason, "silent");
+  assert.equal(result.event.intent, "resource-load");
+  assert.equal(result.decision.channel, "silent");
+  assert.equal(calls.length, 0);
+});
+
 test("error runtime prefers policy presenter over app and module defaults", () => {
   const calls = [];
   const runtime = createErrorRuntime({

package/test/linkItemScaffoldContract.test.js

@@ -32,8 +32,13 @@ test("shell-web exports generic link-item components for app-owned shell wrapper
   assert.match(clientIndexSource, /ShellMenuLinkItem/);
   assert.match(clientIndexSource, /ShellSurfaceAwareMenuLinkItem/);
   assert.match(clientIndexSource, /ShellTabLinkItem/);
+  assert.match(clientIndexSource, /ShellRouteTransition/);
 
   const packageJson = JSON.parse(await readFile(path.join(PACKAGE_DIR, "package.json"), "utf8"));
+  assert.equal(
+    packageJson?.exports?.["./client/components/ShellRouteTransition"],
+    "./src/client/components/ShellRouteTransition.vue"
+  );
   assert.equal(
     packageJson?.exports?.["./client/components/ShellMenuLinkItem"],
     "./src/client/components/ShellMenuLinkItem.vue"
@@ -150,8 +155,10 @@ test("shell-web generic link items support the expected shared route and icon be
   assert.match(shellSurfaceAwareSource, /:exact="props\.exact"/);
   assert.match(shellTabSource, /icon:\s*\{/);
   assert.match(shellTabSource, /resolveMenuLinkIcon/);
-  assert.match(shellTabSource, /<v-list-item/);
-  assert.match(shellTabSource, /:prepend-icon="resolvedIcon \|\| undefined"/);
+  assert.match(shellTabSource, /<v-btn/);
+  assert.match(shellTabSource, /stacked/);
+  assert.match(shellTabSource, /min-height:\s*48px/);
+  assert.match(shellTabSource, /<v-icon v-if="resolvedIcon" :icon="resolvedIcon" \/>/);
 });
 
 test("shell-web binds the local link-item wrapper tokens into MainClientProvider", () => {

package/test/outletMenuWidgetContract.test.js

@@ -14,9 +14,9 @@ test("shell-web outlet menu widget exposes a configurable nested outlet", async
   );
 
   assert.match(source, /import \{ mdiCogOutline \} from "@mdi\/js";/);
-  assert.match(source, /defaultLinkComponentToken: \{/);
   assert.match(source, /:target="props\.target"/);
-  assert.match(source, /:default-link-component-token="props\.defaultLinkComponentToken"/);
+  assert.doesNotMatch(source, /defaultLinkComponentToken/);
+  assert.doesNotMatch(source, /default-link-component-token/);
   assert.match(source, /default: mdiCogOutline/);
   assert.doesNotMatch(source, /mdi-[a-z0-9-]+/);
 });

package/test/placementRegistry.test.js

@@ -7,13 +7,13 @@ test("placement registry stores unique entries and builds immutable array", () =
 
   const firstAdded = registry.addPlacement({
     id: "example.profile",
-    target: "shell-layout:top-right",
+    target: "shell.status",
     surfaces: ["*"],
     componentToken: "example.profile.component"
   });
   const duplicateAdded = registry.addPlacement({
     id: "example.profile",
-    target: "shell-layout:top-right",
+    target: "shell.status",
     surfaces: ["*"],
     componentToken: "example.profile.component.duplicate"
   });
@@ -33,7 +33,7 @@ test("placement registry accepts explicit non-global surface ids", () => {
 
   const added = registry.addPlacement({
     id: "example.admin",
-    target: "shell-layout:top-right",
+    target: "shell.status",
     surfaces: ["admin"],
     componentToken: "example.admin.component"
   });

package/test/placementRuntime.test.js

@@ -32,6 +32,119 @@ function createPlacementContext() {
   };
 }
 
+function semanticTopologyEntry({
+  id = "shell.primary-nav",
+  owner = "",
+  surfaces = ["*"],
+  compact = "shell-layout:primary-menu",
+  medium = "shell-layout:primary-menu",
+  expanded = "shell-layout:primary-menu",
+  compactRenderer = "component.menu",
+  mediumRenderer = "component.menu",
+  expandedRenderer = "component.menu"
+} = {}) {
+  const createVariant = (outlet, renderer) => ({
+    outlet,
+    renderers: renderer ? { link: renderer } : {}
+  });
+  return {
+    id,
+    owner,
+    surfaces,
+    variants: {
+      compact: createVariant(compact, compactRenderer),
+      medium: createVariant(medium, mediumRenderer),
+      expanded: createVariant(expanded, expandedRenderer)
+    }
+  };
+}
+
+test("web placement runtime resolves semantic targets through topology variants", () => {
+  const app = createAppStub({
+    tokens: {
+      "component.bottom": () => null,
+      "component.menu": () => null
+    }
+  });
+
+  const runtime = createWebPlacementRuntime({ app });
+  runtime.replacePlacementTopology([
+    semanticTopologyEntry({
+      id: "shell.primary-nav",
+      compact: "shell-layout:bottom-nav",
+      medium: "shell-layout:primary-menu",
+      expanded: "shell-layout:primary-menu",
+      compactRenderer: "component.bottom",
+      mediumRenderer: "component.menu",
+      expandedRenderer: "component.menu"
+    })
+  ]);
+  runtime.replacePlacements([
+    definePlacement({
+      id: "test.home",
+      target: "shell.primary-nav",
+      kind: "link",
+      surfaces: ["app"],
+      order: 10
+    })
+  ]);
+  runtime.setContext(createPlacementContext());
+
+  const compactEntries = runtime.getPlacements({
+    surface: "app",
+    target: "shell-layout:bottom-nav",
+    layoutClass: "compact"
+  });
+  assert.deepEqual(compactEntries.map((entry) => entry.id), ["test.home"]);
+  assert.equal(compactEntries[0].semanticTarget, "shell.primary-nav");
+  assert.equal(compactEntries[0].componentToken, "component.bottom");
+
+  const mediumEntries = runtime.getPlacements({
+    surface: "app",
+    target: "shell-layout:primary-menu",
+    layoutClass: "medium"
+  });
+  assert.deepEqual(mediumEntries.map((entry) => entry.id), ["test.home"]);
+  assert.equal(mediumEntries[0].componentToken, "component.menu");
+});
+
+test("web placement runtime accepts append-only topology objects", () => {
+  const app = createAppStub({
+    tokens: {
+      "component.menu": () => null
+    }
+  });
+
+  const runtime = createWebPlacementRuntime({ app });
+  runtime.replacePlacementTopology({
+    placements: [
+      semanticTopologyEntry({
+        id: "shell.primary-nav",
+        compactRenderer: "component.menu",
+        mediumRenderer: "component.menu",
+        expandedRenderer: "component.menu"
+      })
+    ]
+  });
+  runtime.replacePlacements([
+    definePlacement({
+      id: "test.home",
+      target: "shell.primary-nav",
+      kind: "link",
+      surfaces: ["app"],
+      order: 10
+    })
+  ]);
+  runtime.setContext(createPlacementContext());
+
+  const entries = runtime.getPlacements({
+    surface: "app",
+    target: "shell-layout:primary-menu",
+    layoutClass: "expanded"
+  });
+  assert.deepEqual(entries.map((entry) => entry.id), ["test.home"]);
+});
+
 test("web placement runtime filters by surface/host/position, resolves component tokens, and sorts by order", () => {
   const app = createAppStub({
     tokens: {
@@ -48,21 +161,24 @@ test("web placement runtime filters by surface/host/position, resolves component
       target: "shell-layout:primary-menu",
       surfaces: ["app"],
       order: 30,
-      componentToken: "component.menu"
+      componentToken: "component.menu",
+      internal: true
     }),
     definePlacement({
       id: "test.profile",
       target: "shell-layout:top-right",
       surfaces: ["*"],
       order: 20,
-      componentToken: "component.profile"
+      componentToken: "component.profile",
+      internal: true
     }),
     definePlacement({
       id: "test.alerts",
       target: "shell-layout:top-right",
       surfaces: ["app"],
       order: 10,
-      componentToken: "component.alerts"
+      componentToken: "component.alerts",
+      internal: true
     })
   ]);
   runtime.setContext(createPlacementContext());
@@ -93,14 +209,16 @@ test("web placement runtime preserves source order when placements share the sam
       target: "home-settings:primary-menu",
       surfaces: ["app"],
       order: 155,
-      componentToken: "component.beta"
+      componentToken: "component.beta",
+      internal: true
     }),
     definePlacement({
       id: "test.alpha",
       target: "home-settings:primary-menu",
       surfaces: ["app"],
       order: 155,
-      componentToken: "component.alpha"
+      componentToken: "component.alpha",
+      internal: true
     })
   ]);
   runtime.setContext(createPlacementContext());
@@ -129,6 +247,7 @@ test("web placement runtime applies context contributors and placement when() pr
       target: "auth-profile-menu:primary-menu",
       surfaces: ["*"],
       componentToken: "component.guest",
+      internal: true,
       when: ({ auth }) => !Boolean(auth?.authenticated)
     }),
     definePlacement({
@@ -136,6 +255,7 @@ test("web placement runtime applies context contributors and placement when() pr
       target: "auth-profile-menu:primary-menu",
       surfaces: ["*"],
       componentToken: "component.authenticated",
+      internal: true,
       when: ({ auth }) => Boolean(auth?.authenticated)
     })
   ]);
@@ -165,6 +285,7 @@ test("web placement runtime uses runtime context and local context overrides con
       target: "auth-profile-menu:primary-menu",
       surfaces: ["*"],
       componentToken: "component.allowed",
+      internal: true,
       when: ({ auth }) => Boolean(auth?.authenticated)
     })
   ]);
@@ -224,13 +345,15 @@ test("web placement runtime rejects duplicate placement ids", () => {
         id: "dup.entry",
         target: "shell-layout:top-right",
         surfaces: ["*"],
-        componentToken: "component.a"
+        componentToken: "component.a",
+        internal: true
       }),
       definePlacement({
         id: "dup.entry",
         target: "shell-layout:primary-menu",
         surfaces: ["*"],
-        componentToken: "component.b"
+        componentToken: "component.b",
+        internal: true
       })
     ]);
   }, /Duplicate placement id/);
@@ -271,13 +394,15 @@ test("web placement runtime skips throwing component tokens and logs resolution
       id: "bad",
       target: "shell-layout:top-right",
       surfaces: ["*"],
-      componentToken: "component.bad"
+      componentToken: "component.bad",
+      internal: true
     }),
     definePlacement({
       id: "good",
       target: "shell-layout:top-right",
       surfaces: ["*"],
-      componentToken: "component.good"
+      componentToken: "component.good",
+      internal: true
     })
   ]);
 
@@ -323,7 +448,8 @@ test("web placement runtime clears failed token cache when placements are replac
       id: "toggle",
       target: "shell-layout:top-right",
       surfaces: ["*"],
-      componentToken: "component.toggle"
+      componentToken: "component.toggle",
+      internal: true
     })
   ]);
 
@@ -339,7 +465,8 @@ test("web placement runtime clears failed token cache when placements are replac
       id: "toggle",
       target: "shell-layout:top-right",
       surfaces: ["*"],
-      componentToken: "component.toggle"
+      componentToken: "component.toggle",
+      internal: true
     })
   ]);
 
@@ -362,21 +489,24 @@ test("web placement runtime follows explicit surface targeting without role indi
       target: "shell-layout:top-right",
       surfaces: ["*"],
       order: 10,
-      componentToken: "component.global"
+      componentToken: "component.global",
+      internal: true
     }),
     definePlacement({
       id: "app.link",
       target: "shell-layout:top-right",
       surfaces: ["app"],
       order: 20,
-      componentToken: "component.app"
+      componentToken: "component.app",
+      internal: true
     }),
     definePlacement({
       id: "admin.link",
       target: "shell-layout:top-right",
       surfaces: ["admin"],
       order: 30,
-      componentToken: "component.admin"
+      componentToken: "component.admin",
+      internal: true
     })
   ]);
   runtime.setContext(createPlacementContext());