@jskit-ai/shell-web 0.1.249 → 0.1.251

package/fixtures/adaptive-shell/src/App.vue

@@ -3,9 +3,11 @@ import { computed, watchEffect } from "vue";
 import { RouterView, useRoute } from "vue-router";
 import { useTheme } from "vuetify";
 import ShellLayout from "@jskit-ai/shell-web/client/components/ShellLayout";
+import ShellErrorHost from "@jskit-ai/shell-web/client/components/ShellErrorHost";
 
 const route = useRoute();
 const theme = useTheme();
+const bare = computed(() => route.meta.bare === true);
 const surface = computed(() => route.path.startsWith("/w/") ? "admin" : "home");
 const surfaceLabel = computed(() => surface.value === "admin" ? "Admin" : "Home");
 const themeMode = computed(() => route.query.theme === "dark" ? "dark" : "light");
@@ -22,7 +24,9 @@ watchEffect(function applyFixtureTheme() {
 
 <template>
   <v-app>
+    <RouterView v-if="bare" />
     <ShellLayout
+      v-else
       :surface="surface"
       :surface-label="surfaceLabel"
       :rail-width="railWidth"
@@ -30,5 +34,6 @@ watchEffect(function applyFixtureTheme() {
     >
       <RouterView />
     </ShellLayout>
+    <ShellErrorHost />
   </v-app>
 </template>

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

@@ -13,6 +13,10 @@ import ShellSurfaceAwareMenuLinkItem from "@jskit-ai/shell-web/client/components
 import ShellTabLinkItem from "@jskit-ai/shell-web/client/components/ShellTabLinkItem";
 import { useShellLayoutStore } from "../../../src/client/stores/useShellLayoutStore.js";
 import { createWebPlacementRuntime } from "../../../src/client/placement/runtime.js";
+import { createErrorRuntime } from "../../../src/client/error/runtime.js";
+import { createDefaultMaterialErrorPresenters } from "../../../src/client/error/presenters.js";
+import { createErrorPresentationStore } from "../../../src/client/error/store.js";
+import { useShellErrorPresentationStore } from "../../../src/client/stores/useShellErrorPresentationStore.js";
 
 const COMPONENTS = new Map([
   ["fixture.menu-link", ShellMenuLinkItem],
@@ -111,7 +115,8 @@ const routes = [
   { 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" } }
+  { path: "/help", component: ScreenPage, meta: { title: "Help and support" } },
+  { path: "/sign-in", component: ScreenPage, meta: { title: "Sign in", bare: true } }
 ];
 const router = createRouter({ history: createWebHistory(), routes });
 const pinia = createPinia();
@@ -179,6 +184,19 @@ app.use(pinia);
 app.use(router);
 app.use(vuetify);
 app.provide("jskit.shell-web.runtime.web-placement.client", placementRuntime);
+const errorStore = createErrorPresentationStore();
+const errorRuntime = createErrorRuntime({
+  presenters: createDefaultMaterialErrorPresenters({ store: errorStore }),
+  defaultPresenterId: "material.snackbar"
+});
+useShellErrorPresentationStore(pinia).attachRuntimeStore(errorStore);
+app.provide("jskit.shell-web.runtime.web-error.client", errorRuntime);
+window.__shellFixtureReportBanner = (message) => errorRuntime.report({
+  source: "shell-web.fixture",
+  message,
+  severity: "error",
+  channel: "banner"
+});
 app.provide("jskit.shell-web.runtime.web-refresh.client", {
   async refresh() {
     await fetch("/api/bootstrap?reason=pull-to-refresh");

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jskit-ai/shell-web",
-  "version": "0.1.249",
+  "version": "0.1.251",
   "type": "module",
   "scripts": {
     "test": "node --test --test-concurrency=1"
@@ -34,7 +34,7 @@
     "@vue/compiler-sfc": "3.5.44"
   },
   "peerDependencies": {
-    "@jskit-ai/kernel": "0.1.244",
+    "@jskit-ai/kernel": "0.1.245",
     "pinia": "^4.0.3",
     "vue": "^3.5.44",
     "vue-router": "^5.3.1",

package/patterns/application-shell/PATTERN.md

@@ -38,6 +38,29 @@ placement registry, topology, and adaptive smoke helper exported by
 - Cached route/resource state hydrates writable UI state synchronously or with
   immediate watchers.
 - Loading uses stable skeletons, not spinners or shifting status banners.
+- `ShellErrorHost` stays directly inside `v-app`. Its banners float below a top
+  app bar; on a surface without one (such as sign-in) they join the page flow
+  above the content so they never cover it. A full-viewport fixed screen on
+  such a surface starts at `var(--shell-error-banners-inline-height, 0px)`, as
+  `@jskit-ai/auth-web`'s login and reset views do.
+- Restyle shell chrome through its custom properties, not by overriding
+  Vuetify internals: `--shell-chrome-border-width` and
+  `--shell-chrome-border-color` for the shared dividers,
+  `--shell-app-bar-border-width`, `--shell-navigation-border-width` and
+  `--shell-bottom-navigation-border-width` per edge, and
+  `--shell-app-bar-background`, `--shell-navigation-background` and
+  `--shell-bottom-navigation-background` for the surfaces. The defaults keep
+  one thin divider on each separating edge, because Vuetify's default themes
+  define no Material 3 surface-container roles. A Material 3 restyle sets the
+  border widths to `0` and gives navigation a tonal surface, for example
+  `rgb(var(--v-theme-surface-container-low))` when the theme defines it.
+- `createShellRouter()` from `@jskit-ai/kernel/client` installs
+  `shellScrollBehavior`: a new screen opens at the top (or its hash target),
+  Back/Forward restore the saved position, and query, hash, tab or sub-view
+  changes within the same page keep it. A tab or sub-view is the same page when
+  both locations share a parent page record below the surface root. Pass
+  `scrollBehavior` to replace it, or `scrollBehavior: false` to disable it; do
+  not wrap the router or reset scroll in page components.
 - The adaptive browser check closes navigation through its public close control.
 
 ## Example files

package/src/client/components/ShellErrorHost.vue

@@ -1,5 +1,7 @@
 <script setup>
-import { computed, ref, watch } from "vue";
+import { computed, onBeforeUnmount, ref, watch } from "vue";
+import { useLayout } from "vuetify";
+import { mdiAlertOutline, mdiCheckCircleOutline, mdiInformationOutline } from "@mdi/js";
 import {
   useShellWebErrorRuntime
 } from "../error/inject.js";
@@ -12,6 +14,75 @@ const snackbarEntries = computed(() => store.channels.snackbar || []);
 const bannerEntries = computed(() => store.channels.banner || []);
 const dialogEntry = computed(() => store.channels.dialog[0] || null);
 const displayedSnackbarEntry = ref(null);
+const layoutRect = readLayoutRect();
+
+function readLayoutRect() {
+  try {
+    return useLayout().mainRect;
+  } catch {
+    return null;
+  }
+}
+
+// Banners float just below a top app bar. A surface without one (sign-in pages)
+// has nothing to float under, so the banners join the page flow above the
+// content instead of covering it, and publish their height so full-viewport
+// surfaces can start below them.
+const BANNER_INLINE_HEIGHT_PROPERTY = "--shell-error-banners-inline-height";
+const bannersElement = ref(null);
+const bannerPlacement = computed(() => {
+  const rect = layoutRect?.value || {};
+  const top = Number(rect.top) || 0;
+  if (top <= 0) {
+    return { inline: true, style: undefined };
+  }
+
+  return {
+    inline: false,
+    style: {
+      top: `calc(env(safe-area-inset-top, 0px) + ${top}px)`,
+      left: `${Number(rect.left) || 0}px`,
+      right: `${Number(rect.right) || 0}px`
+    }
+  };
+});
+let bannerResizeObserver = null;
+
+function publishInlineBannerHeight(height = 0) {
+  const rootStyle = globalThis.document?.documentElement?.style;
+  if (!rootStyle) {
+    return;
+  }
+  if (height > 0) {
+    rootStyle.setProperty(BANNER_INLINE_HEIGHT_PROPERTY, `${Math.ceil(height)}px`);
+  } else {
+    rootStyle.removeProperty(BANNER_INLINE_HEIGHT_PROPERTY);
+  }
+}
+
+function stopObservingBanners() {
+  bannerResizeObserver?.disconnect();
+  bannerResizeObserver = null;
+  publishInlineBannerHeight(0);
+}
+
+watch(
+  [bannersElement, () => bannerPlacement.value.inline],
+  ([element, inline]) => {
+    stopObservingBanners();
+    if (!element || !inline || typeof globalThis.ResizeObserver !== "function") {
+      return;
+    }
+    bannerResizeObserver = new globalThis.ResizeObserver(() => {
+      publishInlineBannerHeight(element.getBoundingClientRect().height);
+    });
+    bannerResizeObserver.observe(element);
+    publishInlineBannerHeight(element.getBoundingClientRect().height);
+  },
+  { flush: "post" }
+);
+
+onBeforeUnmount(stopObservingBanners);
 const snackbarOpen = ref(false);
 
 function isSameSnackbarEntry(left = null, right = null) {
@@ -77,15 +148,12 @@ function resolveSeverityColor(severity = "error") {
 function resolveSeverityIcon(severity = "error") {
   const normalized = String(severity || "error").trim().toLowerCase();
   if (normalized === "info") {
-    return "mdi-information-outline";
+    return mdiInformationOutline;
   }
   if (normalized === "success") {
-    return "mdi-check-circle-outline";
+    return mdiCheckCircleOutline;
   }
-  if (normalized === "warning") {
-    return "mdi-alert-outline";
-  }
-  return "mdi-alert-outline";
+  return mdiAlertOutline;
 }
 
 function resolveTimeout(entry) {
@@ -155,8 +223,19 @@ function onSnackbarAfterLeave() {
 </script>
 
 <template>
-  <div class="shell-error-host" aria-live="polite">
-    <div v-if="bannerEntries.length > 0" class="shell-error-host__banners">
+  <div
+    class="shell-error-host"
+    :class="{ 'shell-error-host--inline-banners': bannerPlacement.inline }"
+    aria-live="polite"
+  >
+    <div
+      v-if="bannerEntries.length > 0"
+      ref="bannersElement"
+      class="shell-error-host__banners"
+      :class="{ 'shell-error-host__banners--inline': bannerPlacement.inline }"
+      :style="bannerPlacement.style"
+      data-testid="shell-error-host-banners"
+    >
       <div class="shell-error-host__banner-stack">
         <v-alert
           v-for="entry in bannerEntries"
@@ -254,16 +333,23 @@ function onSnackbarAfterLeave() {
 </template>
 
 <style scoped>
+.shell-error-host--inline-banners {
+  order: -1;
+}
+
 .shell-error-host__banners {
   position: fixed;
-  top: calc(env(safe-area-inset-top, 0px) + var(--shell-error-banner-offset, 64px));
-  left: 0;
-  right: 0;
   z-index: 2600;
   pointer-events: none;
   padding: 10px 12px;
 }
 
+.shell-error-host__banners--inline {
+  position: relative;
+  z-index: auto;
+  padding-top: calc(env(safe-area-inset-top, 0px) + 10px);
+}
+
 .shell-error-host__banner-stack {
   margin: 0 auto;
   width: min(1120px, 100%);
@@ -277,10 +363,28 @@ function onSnackbarAfterLeave() {
   box-shadow: var(--v-shadow-4);
 }
 
+/*
+ * The close button always uses the banner's own on-color (the message colour) on
+ * a tonal disc of that colour, so a themed button default can never turn it into
+ * a low-contrast red-on-red mark, in light or dark themes.
+ */
+.shell-error-host__banner :deep(.v-alert__close .v-btn) {
+  color: inherit !important;
+  opacity: 1;
+  background-color: color-mix(in srgb, currentColor 18%, transparent);
+}
+
+.shell-error-host__banner :deep(.v-alert__close .v-btn .v-icon) {
+  font-size: 20px;
+}
+
 @media (max-width: 600px) {
   .shell-error-host__banners {
-    top: calc(env(safe-area-inset-top, 0px) + var(--shell-error-banner-offset-mobile, 56px));
     padding: 8px;
   }
+
+  .shell-error-host__banners--inline {
+    padding-top: calc(env(safe-area-inset-top, 0px) + 8px);
+  }
 }
 </style>

package/src/client/components/ShellLayout.vue

@@ -563,10 +563,9 @@ function touchListIncludesActiveTouch(touchList) {
 
 <template>
   <v-app-bar
-    border
     :density="isCompactLayout ? 'compact' : 'comfortable'"
     elevation="0"
-    class="shell-layout__app-bar bg-surface"
+    class="shell-layout__app-bar"
     data-testid="jskit-shell-app-bar"
   >
     <v-app-bar-nav-icon
@@ -619,8 +618,7 @@ function touchListIncludesActiveTouch(touchList) {
     ref="navigationDrawer"
     id="jskit-shell-drawer"
     :model-value="drawerPresentation.visible"
-    border
-    class="shell-layout__drawer bg-surface"
+    class="shell-layout__drawer"
     data-testid="jskit-shell-drawer"
     :data-layout="layoutClass"
     :data-presentation="drawerPresentation.kind"
@@ -670,7 +668,6 @@ function touchListIncludesActiveTouch(touchList) {
     v-if="isCompactLayout"
     class="shell-layout__bottom-nav"
     data-testid="jskit-shell-bottom-nav"
-    bg-color="surface"
     color="primary"
     density="comfortable"
     grow
@@ -716,6 +713,33 @@ function touchListIncludesActiveTouch(touchList) {
 </template>
 
 <style scoped>
+/*
+ * Shell chrome follows the app's Vuetify theme and is restyled through these
+ * custom properties (set them on :root or any ancestor):
+ *   --shell-chrome-border-width / --shell-chrome-border-color   shared dividers
+ *   --shell-app-bar-border-width, --shell-navigation-border-width,
+ *   --shell-bottom-navigation-border-width                       per-edge overrides
+ *   --shell-app-bar-background, --shell-navigation-background,
+ *   --shell-bottom-navigation-background                         surfaces
+ * A Material 3 restyle sets the border widths to 0 and separates surfaces
+ * tonally, e.g. --shell-navigation-background: rgb(var(--v-theme-surface-container-low)).
+ */
+.shell-layout__app-bar {
+  border-style: solid;
+  border-color: var(--shell-chrome-border-color, rgba(var(--v-border-color), var(--v-border-opacity)));
+  border-width: 0 0 var(--shell-app-bar-border-width, var(--shell-chrome-border-width, thin));
+  background: var(--shell-app-bar-background, rgb(var(--v-theme-surface)));
+  color: rgb(var(--v-theme-on-surface));
+}
+
+.shell-layout__drawer {
+  border-style: solid;
+  border-color: var(--shell-chrome-border-color, rgba(var(--v-border-color), var(--v-border-opacity)));
+  border-width: 0;
+  border-inline-end-width: var(--shell-navigation-border-width, var(--shell-chrome-border-width, thin));
+  background: var(--shell-navigation-background, rgb(var(--v-theme-surface)));
+}
+
 .shell-layout__content {
   padding: 0.75rem 1rem calc(1rem + env(safe-area-inset-bottom, 0px));
 }
@@ -824,7 +848,9 @@ function touchListIncludesActiveTouch(touchList) {
 }
 
 .shell-layout__bottom-nav {
-  border-top: 1px solid rgba(var(--v-border-color), var(--v-border-opacity));
+  border-top: var(--shell-bottom-navigation-border-width, var(--shell-chrome-border-width, thin)) solid
+    var(--shell-chrome-border-color, rgba(var(--v-border-color), var(--v-border-opacity)));
+  background: var(--shell-bottom-navigation-background, rgb(var(--v-theme-surface)));
   padding-bottom: env(safe-area-inset-bottom, 0px);
 }
 

package/test/adaptiveShell.browser.test.js

@@ -361,3 +361,118 @@ test("shell-web preserves the active form across responsive changes", {
     await stopProcess(vite);
   }
 });
+
+function overlaps(first, second) {
+  return first.bottom > second.top && first.top < second.bottom &&
+    first.right > second.left && first.left < second.right;
+}
+
+async function reportBannerAndMeasure(page) {
+  await page.evaluate(() => window.__shellFixtureReportBanner("Invalid email or password."));
+  const banner = page.locator(".shell-error-host__banner").first();
+  await expect(banner).toBeVisible();
+  await page.evaluate(() => new Promise((resolve) => requestAnimationFrame(() => requestAnimationFrame(resolve))));
+  return banner.evaluate((element) => {
+    const box = (node) => {
+      const rect = node.getBoundingClientRect();
+      return { top: rect.top, bottom: rect.bottom, left: rect.left, right: rect.right };
+    };
+    const close = element.querySelector(".v-alert__close .v-btn");
+    const closeColor = window.getComputedStyle(close).color;
+    // A themed button default must not recolour the close mark into the banner colour.
+    close.classList.add("text-error");
+    const closeColorWithThemedDefault = window.getComputedStyle(close).color;
+    close.classList.remove("text-error");
+    const appBar = document.querySelector("[data-testid='jskit-shell-app-bar']");
+    return {
+      banner: box(element),
+      background: window.getComputedStyle(element).backgroundColor,
+      closeColor,
+      closeColorWithThemedDefault,
+      appBar: appBar ? box(appBar) : null,
+      content: Array.from(document.querySelectorAll("main h1, main input, main button"))
+        .map((node) => ({ name: node.textContent.trim() || node.name, rect: box(node) }))
+    };
+  });
+}
+
+test("shell-web error banners never cover content and keep a readable close button", {
+  skip: RUN_BROWSER_TEST ? false : "set JSKIT_SHELL_WEB_BROWSER_INTEGRATION=1",
+  timeout: 120_000
+}, async () => {
+  const vite = await startViteFixture({ fixtureRoot: FIXTURE_ROOT });
+  let browser;
+  try {
+    browser = await chromium.launch(createChromiumLaunchOptions());
+    for (const viewport of [{ width: 1440, height: 900 }, { width: 390, height: 844 }]) {
+      for (const theme of ["light", "dark"]) {
+        const page = await browser.newPage({ baseURL: vite.baseURL, viewport });
+        await page.goto(`/sign-in?theme=${theme}`);
+        await expect(page.getByRole("heading", { level: 1, name: "Sign in" })).toBeVisible();
+        await expect(page.getByTestId("jskit-shell-app-bar")).toHaveCount(0);
+        const bare = await reportBannerAndMeasure(page);
+        for (const item of bare.content) {
+          assert.equal(
+            overlaps(bare.banner, item.rect),
+            false,
+            `${viewport.width}px ${theme}: the banner covers "${item.name}" on a surface without an app bar.`
+          );
+        }
+        const background = parseRgb(bare.background);
+        for (const color of [bare.closeColor, bare.closeColorWithThemedDefault]) {
+          const ratio = contrastRatio(parseRgb(color), background);
+          assert.ok(ratio >= 3, `${viewport.width}px ${theme}: banner close contrast was ${ratio.toFixed(2)}:1.`);
+        }
+
+        await page.goto(`/home?theme=${theme}`);
+        await expect(page.getByTestId("jskit-shell-app-bar")).toBeVisible();
+        const shell = await reportBannerAndMeasure(page);
+        assert.ok(
+          shell.banner.top >= shell.appBar.bottom - 1,
+          `${viewport.width}px ${theme}: the banner overlaps the top app bar.`
+        );
+        await page.close();
+      }
+    }
+  } finally {
+    await browser?.close();
+    await stopProcess(vite);
+  }
+});
+
+test("shell-web chrome borders and surfaces follow app-supplied tokens", {
+  skip: RUN_BROWSER_TEST ? false : "set JSKIT_SHELL_WEB_BROWSER_INTEGRATION=1",
+  timeout: 90_000
+}, async () => {
+  const vite = await startViteFixture({ fixtureRoot: FIXTURE_ROOT });
+  let browser;
+  try {
+    browser = await chromium.launch(createChromiumLaunchOptions());
+    const page = await browser.newPage({ baseURL: vite.baseURL, viewport: { width: 1280, height: 900 } });
+    await page.goto("/home?theme=light");
+    await expect(page.getByTestId("jskit-shell-drawer")).toBeVisible();
+    const read = () => page.evaluate(() => {
+      const edges = (testId) => {
+        const style = window.getComputedStyle(document.querySelector(`[data-testid='${testId}']`));
+        return [style.borderTopWidth, style.borderRightWidth, style.borderBottomWidth, style.borderLeftWidth,
+          style.backgroundColor];
+      };
+      return { appBar: edges("jskit-shell-app-bar"), drawer: edges("jskit-shell-drawer") };
+    });
+    const defaults = await read();
+    // Only the separating edges carry a divider by default.
+    assert.deepEqual(defaults.appBar.slice(0, 4), ["0px", "0px", "1px", "0px"]);
+    assert.deepEqual(defaults.drawer.slice(0, 4), ["0px", "1px", "0px", "0px"]);
+
+    await page.addStyleTag({
+      content: ":root { --shell-chrome-border-width: 0; --shell-app-bar-background: rgb(1, 2, 3); --shell-navigation-background: rgb(4, 5, 6); }"
+    });
+    const restyled = await read();
+    assert.deepEqual(restyled.appBar, ["0px", "0px", "0px", "0px", "rgb(1, 2, 3)"]);
+    assert.deepEqual(restyled.drawer, ["0px", "0px", "0px", "0px", "rgb(4, 5, 6)"]);
+    await page.close();
+  } finally {
+    await browser?.close();
+    await stopProcess(vite);
+  }
+});

package/test/settingsPlacementContract.test.js

@@ -142,7 +142,7 @@ test("shell-web error host uses one explicit close affordance for banner errors"
   const source = await readFile(path.join(PACKAGE_DIR, "src", "client", "components", "ShellErrorHost.vue"), "utf8");
 
   assert.match(source, /function resolveSeverityIcon/);
-  assert.match(source, /mdi-alert-outline/);
+  assert.match(source, /mdiAlertOutline/);
   assert.match(source, /:icon="resolveSeverityIcon\(entry\.severity\)"/);
   assert.match(source, /closable[\s\S]*@click:close="dismiss\(entry\)"/);
   assert.doesNotMatch(source, /mdi-close/);