@jskit-ai/shell-web 0.1.65 → 0.1.66

package/templates/src/pages/home/index.vue

@@ -28,34 +28,75 @@ const health = computed(() => {
 </script>
 
 <template>
-  <v-card rounded="lg" elevation="1" border>
-    <v-card-item class="home-surface-card__header">
-      <template #prepend>
-        <v-chip color="primary" size="small" label>Home</v-chip>
-      </template>
-      <v-card-title class="text-h5">welcome</v-card-title>
-      <v-card-subtitle>Main public surface</v-card-subtitle>
-    </v-card-item>
-    <v-divider />
-    <v-card-text class="home-surface-card__body d-flex flex-column ga-3">
-      <div class="d-flex flex-wrap ga-3">
-        <v-chip color="secondary" variant="tonal" label>Route: /home</v-chip>
-        <v-chip color="info" variant="tonal" label>Health: {{ health }}</v-chip>
+  <section class="generated-ui-screen generated-ui-screen--app home-surface-screen d-flex flex-column ga-4">
+    <header class="home-surface-screen__header">
+      <div>
+        <p class="text-overline text-medium-emphasis mb-1">Home</p>
+        <h1 class="home-surface-screen__title">Ready</h1>
+        <p class="text-body-2 text-medium-emphasis mb-0">
+          Core services are available.
+        </p>
       </div>
-      <p class="text-medium-emphasis mb-0">
-        This is your primary landing page. Replace this content with your actual product home.
-      </p>
-      <p class="text-body-2 text-medium-emphasis mb-0">Use the navigation drawer to move around the shell.</p>
-    </v-card-text>
-  </v-card>
+      <v-btn color="primary" variant="flat" to="/home/settings/general">Settings</v-btn>
+    </header>
+
+    <v-sheet rounded="lg" border class="home-surface-screen__panel">
+      <div class="home-surface-screen__status">
+        <span class="text-caption text-medium-emphasis">Service health</span>
+        <strong>{{ health }}</strong>
+      </div>
+      <v-divider vertical class="d-none d-sm-block" />
+      <div class="home-surface-screen__status">
+        <span class="text-caption text-medium-emphasis">Route</span>
+        <strong>/home</strong>
+      </div>
+    </v-sheet>
+  </section>
 </template>
 
 <style scoped>
-.home-surface-card__header {
-  padding: 0.875rem 1rem;
+.generated-ui-screen {
+  --generated-ui-screen-title-size: clamp(1.5rem, 2.5vw, 2.25rem);
+  --generated-ui-screen-panel-padding: 1rem;
+}
+
+.home-surface-screen__header {
+  align-items: flex-start;
+  display: flex;
+  gap: 1rem;
+  justify-content: space-between;
+}
+
+.home-surface-screen__title {
+  font-size: var(--generated-ui-screen-title-size);
+  font-weight: 700;
+  letter-spacing: -0.03em;
+  line-height: 1.1;
+  margin: 0 0 0.4rem;
 }
 
-.home-surface-card__body {
-  padding: 0.875rem 1rem 1rem;
+.home-surface-screen__panel {
+  align-items: stretch;
+  display: flex;
+  flex-wrap: wrap;
+  gap: 1rem;
+  padding: var(--generated-ui-screen-panel-padding);
+}
+
+.home-surface-screen__status {
+  display: grid;
+  gap: 0.15rem;
+  min-width: 9rem;
+}
+
+@media (max-width: 640px) {
+  .home-surface-screen__header {
+    flex-direction: column;
+  }
+
+  .home-surface-screen__header :deep(.v-btn) {
+    min-height: 48px;
+    width: 100%;
+  }
 }
 </style>

package/templates/src/pages/home/settings/general/index.vue

@@ -15,10 +15,12 @@ const drawerDefaultOpenModel = computed({
 </script>
 
 <template>
-  <section class="d-flex flex-column ga-4">
+  <section class="generated-ui-screen generated-ui-screen--settings settings-general-screen d-flex flex-column ga-4">
     <div>
-      <h2 class="text-h6 mb-2">General</h2>
-      <p class="text-body-2 text-medium-emphasis mb-0">These starter settings live in this browser only.</p>
+      <h2 class="text-h6 mb-2">Navigation</h2>
+      <p class="text-body-2 text-medium-emphasis mb-0">
+        Choose the default behavior for wider screens. Phone layouts keep primary navigation in the bottom bar.
+      </p>
     </div>
 
     <v-switch
@@ -26,12 +28,13 @@ const drawerDefaultOpenModel = computed({
       color="primary"
       inset
       hide-details="auto"
-      label="Open navigation drawer by default"
+      label="Open drawer by default on wider screens"
     />
-
-    <p class="text-body-2 text-medium-emphasis mb-0">
-      This tiny example exists to prove that shell-level settings can work without auth or a database. Real apps will
-      usually replace it.
-    </p>
   </section>
 </template>
+
+<style scoped>
+.settings-general-screen :deep(.v-switch) {
+  min-height: 48px;
+}
+</style>

package/templates/src/pages/home/settings.vue

@@ -4,26 +4,73 @@ import { RouterView } from "vue-router";
 </script>
 
 <template>
-  <section class="settings-shell d-flex flex-column ga-4">
-    <v-card rounded="lg" elevation="1" border>
-      <v-card-item>
-        <v-card-title>Home settings</v-card-title>
-        <v-card-subtitle>Manage settings pages for the home surface.</v-card-subtitle>
-      </v-card-item>
-      <v-divider />
-      <v-card-text class="pt-4">
-        <v-row no-gutters>
-          <v-col cols="12" md="3" lg="2" class="pr-md-4 mb-4 mb-md-0">
-            <v-list nav density="comfortable" rounded="lg" border>
-              <ShellOutlet target="home-settings:primary-menu" />
-            </v-list>
-          </v-col>
-
-          <v-col cols="12" md="9" lg="10">
-            <RouterView />
-          </v-col>
-        </v-row>
-      </v-card-text>
-    </v-card>
+  <section class="generated-ui-screen generated-ui-screen--settings settings-shell d-flex flex-column ga-4">
+    <header>
+      <p class="text-overline text-medium-emphasis mb-1">Settings</p>
+      <h1 class="settings-shell__title">Home settings</h1>
+      <p class="text-body-2 text-medium-emphasis mb-0">Configure shell behavior for this surface.</p>
+    </header>
+
+    <v-sheet rounded="lg" border class="settings-shell__panel">
+      <div class="settings-shell__body">
+        <nav class="settings-shell__nav" aria-label="Home settings sections">
+          <v-list nav density="comfortable" rounded="lg" border>
+            <ShellOutlet target="home-settings:primary-menu" />
+          </v-list>
+        </nav>
+
+        <main class="settings-shell__content">
+          <RouterView />
+        </main>
+      </div>
+    </v-sheet>
   </section>
 </template>
+
+<style scoped>
+.generated-ui-screen {
+  --generated-ui-screen-title-size: clamp(1.35rem, 2vw, 1.85rem);
+  --generated-ui-screen-panel-padding: 1rem;
+}
+
+.settings-shell__title {
+  font-size: var(--generated-ui-screen-title-size);
+  font-weight: 650;
+  letter-spacing: -0.02em;
+  line-height: 1.15;
+  margin: 0 0 0.35rem;
+}
+
+.settings-shell__panel {
+  overflow: hidden;
+}
+
+.settings-shell__body {
+  display: grid;
+  gap: 1rem;
+  grid-template-columns: minmax(12rem, 16rem) minmax(0, 1fr);
+  padding: var(--generated-ui-screen-panel-padding);
+}
+
+.settings-shell__content {
+  min-width: 0;
+}
+
+@media (max-width: 960px) {
+  .settings-shell__body {
+    grid-template-columns: 1fr;
+  }
+
+  .settings-shell__nav :deep(.v-list) {
+    display: flex;
+    gap: 0.25rem;
+    overflow-x: auto;
+    scrollbar-width: thin;
+  }
+
+  .settings-shell__nav :deep(.v-list-item) {
+    flex: 0 0 auto;
+    min-height: 48px;
+  }
+}
+</style>

package/templates/src/placementTopology.js

@@ -11,6 +11,10 @@ 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.",
@@ -18,8 +22,8 @@ addPlacementTopology({
   default: true,
   variants: {
     compact: {
-      outlet: "shell-layout:primary-menu",
-      renderers: menuLinkRenderers
+      outlet: "shell-layout:primary-bottom-nav",
+      renderers: bottomNavLinkRenderers
     },
     medium: {
       outlet: "shell-layout:primary-menu",
@@ -86,6 +90,43 @@ addPlacementTopology({
   }
 });
 
+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",

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/placementRuntime.test.js

@@ -108,6 +108,43 @@ test("web placement runtime resolves semantic targets through topology variants"
   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: {

package/test/provider.test.js

@@ -1,7 +1,10 @@
 import assert from "node:assert/strict";
 import test from "node:test";
 import { createPinia } from "pinia";
-import { ShellWebClientProvider } from "../src/client/providers/ShellWebClientProvider.js";
+import {
+  ShellWebClientProvider,
+  resolveAppPlacementTopologyExport
+} from "../src/client/providers/ShellWebClientProvider.js";
 import { useShellErrorPresentationStore } from "../src/client/stores/useShellErrorPresentationStore.js";
 const CLIENT_APP_CONFIG_GLOBAL_KEY = "__JSKIT_CLIENT_APP_CONFIG__";
 
@@ -14,7 +17,7 @@ function setClientAppConfig(source = {}) {
   return normalized;
 }
 
-function createAppDouble({ surfaceRuntime = null } = {}) {
+function createAppDouble({ surfaceRuntime = null, queryClient = null } = {}) {
   const singletons = new Map();
   const singletonInstances = new Map();
   const provided = [];
@@ -61,6 +64,9 @@ function createAppDouble({ surfaceRuntime = null } = {}) {
       if (token === "jskit.client.surface.runtime") {
         return Boolean(surfaceRuntime);
       }
+      if (token === "jskit.client.query-client") {
+        return Boolean(queryClient);
+      }
       return singletons.has(token) || singletonInstances.has(token);
     },
     make(token) {
@@ -73,6 +79,9 @@ function createAppDouble({ surfaceRuntime = null } = {}) {
       if (token === "jskit.client.surface.runtime" && surfaceRuntime) {
         return surfaceRuntime;
       }
+      if (token === "jskit.client.query-client" && queryClient) {
+        return queryClient;
+      }
       if (singletonInstances.has(token)) {
         return singletonInstances.get(token);
       }
@@ -125,6 +134,32 @@ async function withFetchImplementation(fetchImplementation, callback) {
   }
 }
 
+test("shell web client provider preserves append-only placement topology object exports", () => {
+  const warnings = [];
+  const topology = {
+    placements: [
+      {
+        id: "shell.primary-nav",
+        surfaces: ["*"],
+        variants: {
+          compact: { outlet: "shell-layout:primary-menu" },
+          medium: { outlet: "shell-layout:primary-menu" },
+          expanded: { outlet: "shell-layout:primary-menu" }
+        }
+      }
+    ]
+  };
+
+  const resolved = resolveAppPlacementTopologyExport(topology, {
+    warn(payload, message) {
+      warnings.push({ payload, message });
+    }
+  });
+
+  assert.equal(resolved, topology);
+  assert.deepEqual(warnings, []);
+});
+
 test("shell web client provider binds runtime and injects it into Vue app", async () => {
   await withFetchStub({ surfaceAccess: {} }, async () => {
     const app = createAppDouble();
@@ -134,15 +169,15 @@ test("shell web client provider binds runtime and injects it into Vue app", asyn
     assert.equal(app.singletons.has("runtime.web-placement.client"), true);
     assert.equal(app.singletons.has("runtime.web-error.client"), true);
     assert.equal(app.singletons.has("runtime.web-error.presentation-store.client"), true);
+    assert.equal(app.singletons.has("runtime.web-refresh.client"), true);
 
     await provider.boot(app);
-    assert.equal(app.plugins.length, 1);
-    assert.equal(typeof app.plugins[0].plugin.install, "function");
-    assert.equal(typeof app.plugins[0].options?.queryClient, "object");
+    assert.equal(app.plugins.length, 0);
 
     const providedByKey = new Map(app.provided.map((entry) => [entry.key, entry.value]));
 
     assert.equal(providedByKey.has("jskit.shell-web.runtime.web-placement.client"), true);
+    assert.equal(providedByKey.has("jskit.shell-web.runtime.web-refresh.client"), true);
     assert.equal(providedByKey.has("jskit.shell-web.runtime.web-error.client"), true);
     assert.equal(providedByKey.has("jskit.shell-web.runtime.web-error.presentation-store.client"), true);
 
@@ -156,6 +191,9 @@ test("shell web client provider binds runtime and injects it into Vue app", asyn
     assert.equal(typeof errorRuntime.report, "function");
     assert.equal(typeof errorRuntime.configure, "function");
 
+    const refreshRuntime = providedByKey.get("jskit.shell-web.runtime.web-refresh.client");
+    assert.equal(typeof refreshRuntime.refresh, "function");
+
     const errorStore = providedByKey.get("jskit.shell-web.runtime.web-error.presentation-store.client");
     assert.equal(typeof errorStore.getState, "function");
     assert.equal(typeof errorStore.present, "function");
@@ -168,6 +206,60 @@ test("shell web client provider binds runtime and injects it into Vue app", asyn
   });
 });
 
+test("shell refresh runtime refreshes bootstrap and active queries by default", async () => {
+  await withFetchStub({ surfaceAccess: { home: true } }, async () => {
+    const refetchCalls = [];
+    const queryClient = {
+      async refetchQueries(filters = {}, options = {}) {
+        refetchCalls.push({ filters, options });
+      }
+    };
+    const app = createAppDouble({ queryClient });
+    const provider = new ShellWebClientProvider();
+    provider.register(app);
+
+    const refreshRuntime = app.make("runtime.web-refresh.client");
+    const result = await refreshRuntime.refresh("test-refresh");
+
+    assert.equal(result.reason, "test-refresh");
+    assert.equal(result.bootstrapRefreshed, true);
+    assert.equal(result.queriesRefetched, true);
+    assert.equal(refetchCalls.length, 1);
+    assert.equal(refetchCalls[0].filters.type, "active");
+    assert.equal(refetchCalls[0].options.throwOnError, false);
+    assert.equal(refetchCalls[0].filters.predicate({}), true);
+    assert.equal(refetchCalls[0].filters.predicate({ meta: {} }), true);
+    assert.equal(refetchCalls[0].filters.predicate({ meta: { jskit: { refreshOnPull: true } } }), true);
+    assert.equal(refetchCalls[0].filters.predicate({ meta: { jskitRefresh: "pull" } }), true);
+    assert.equal(refetchCalls[0].filters.predicate({ meta: { jskit: { refreshOnPull: false } } }), false);
+    assert.equal(refetchCalls[0].filters.predicate({ meta: { jskitRefresh: false } }), false);
+  });
+});
+
+test("shell refresh runtime reports recoverable retry errors as banners", async () => {
+  await withFetchStub({ surfaceAccess: { home: true } }, async () => {
+    const queryClient = {
+      async refetchQueries() {
+        throw new Error("Network unavailable");
+      }
+    };
+    const app = createAppDouble({ queryClient });
+    const provider = new ShellWebClientProvider();
+    provider.register(app);
+
+    const refreshRuntime = app.make("runtime.web-refresh.client");
+    const result = await refreshRuntime.refresh("test-refresh");
+
+    assert.equal(result.error instanceof Error, true);
+
+    const errorStore = app.make("runtime.web-error.presentation-store.client");
+    const state = errorStore.getState();
+    assert.equal(state.channels.banner.length, 1);
+    assert.equal(state.channels.banner[0].message, "Unable to refresh. Check the connection and try again.");
+    assert.equal(state.channels.banner[0].action.label, "Retry");
+  });
+});
+
 test("shell web client provider resolves surface config from client app config", async () => {
   setClientAppConfig({
     tenancyMode: "workspaces",