@jskit-ai/shell-web 0.1.64 → 0.1.66

package/src/client/stores/useShellLayoutStore.js

@@ -8,6 +8,8 @@ import {
 export const useShellLayoutStore = defineStore("jskit.shell-web.layout", () => {
   const drawerDefaultOpen = ref(readDrawerDefaultOpenPreference());
   const drawerOpen = ref(drawerDefaultOpen.value);
+  const supportingContentOpen = ref(false);
+  const supportingContentTitle = ref("");
 
   function setDrawerDefaultOpen(open) {
     const normalized = Boolean(open);
@@ -24,11 +26,29 @@ export const useShellLayoutStore = defineStore("jskit.shell-web.layout", () => {
     drawerOpen.value = !drawerOpen.value;
   }
 
+  function openSupportingContent({ title = "" } = {}) {
+    supportingContentTitle.value = String(title || "").trim();
+    supportingContentOpen.value = true;
+  }
+
+  function closeSupportingContent() {
+    supportingContentOpen.value = false;
+  }
+
+  function setSupportingContentOpen(open) {
+    supportingContentOpen.value = Boolean(open);
+  }
+
   return {
     drawerDefaultOpen,
     drawerOpen,
+    supportingContentOpen,
+    supportingContentTitle,
     setDrawerDefaultOpen,
     setDrawerOpen,
-    toggleDrawer
+    toggleDrawer,
+    openSupportingContent,
+    closeSupportingContent,
+    setSupportingContentOpen
   };
 });

package/src/test/adaptiveShellSmoke.js

@@ -0,0 +1,121 @@
+const DEFAULT_BASE_URL = String(process.env.PLAYWRIGHT_BASE_URL || "http://127.0.0.1:5173").replace(/\/+$/u, "");
+const DEFAULT_SMOKE_PATH = String(process.env.JSKIT_PLAYWRIGHT_SMOKE_PATH || "/home");
+const DEFAULT_VIEWPORTS = Object.freeze([
+  Object.freeze({ name: "compact", width: 390, height: 844 }),
+  Object.freeze({ name: "medium", width: 768, height: 1024 }),
+  Object.freeze({ name: "expanded", width: 1280, height: 900 })
+]);
+
+async function expectNoHorizontalOverflow(page, expect) {
+  const metrics = await page.evaluate(() => ({
+    clientWidth: document.documentElement.clientWidth,
+    scrollWidth: document.documentElement.scrollWidth
+  }));
+
+  expect(metrics.scrollWidth).toBeLessThanOrEqual(metrics.clientWidth + 1);
+}
+
+async function expectGeneratedScreenContract(page, expect) {
+  const screen = page.locator(".generated-ui-screen").first();
+
+  await expect(screen).toBeVisible();
+}
+
+async function pullToRefresh(page, expect) {
+  await page.evaluate(() => {
+    window.scrollTo(0, 0);
+  });
+  await page.dispatchEvent("body", "pointerdown", {
+    pointerId: 41,
+    pointerType: "touch",
+    isPrimary: true,
+    button: 0,
+    clientX: 180,
+    clientY: 90
+  });
+  await page.dispatchEvent("body", "pointermove", {
+    pointerId: 41,
+    pointerType: "touch",
+    isPrimary: true,
+    button: 0,
+    clientX: 184,
+    clientY: 250
+  });
+  await expect(page.getByTestId("jskit-shell-pull-refresh")).toBeVisible();
+  await page.dispatchEvent("body", "pointerup", {
+    pointerId: 41,
+    pointerType: "touch",
+    isPrimary: true,
+    button: 0,
+    clientX: 184,
+    clientY: 250
+  });
+}
+
+async function isElementVisibleInViewport(page, testId) {
+  return page.getByTestId(testId).evaluate((element) => {
+    const rect = element.getBoundingClientRect();
+    const style = window.getComputedStyle(element);
+    return (
+      style.display !== "none" &&
+      style.visibility !== "hidden" &&
+      rect.width > 0 &&
+      rect.height > 0 &&
+      rect.right > 0 &&
+      rect.left < window.innerWidth &&
+      rect.bottom > 0 &&
+      rect.top < window.innerHeight
+    );
+  });
+}
+
+function runAdaptiveShellSmoke({
+  test,
+  expect,
+  baseUrl = DEFAULT_BASE_URL,
+  smokePath = DEFAULT_SMOKE_PATH,
+  viewports = DEFAULT_VIEWPORTS
+} = {}) {
+  if (!test || !expect) {
+    throw new Error("runAdaptiveShellSmoke requires Playwright test and expect.");
+  }
+
+  test.describe("generated adaptive shell smoke", () => {
+    for (const viewport of viewports) {
+      test(`${viewport.name} layout has reachable navigation and no horizontal overflow`, async ({ page }) => {
+        await page.setViewportSize({ width: viewport.width, height: viewport.height });
+        await page.goto(`${baseUrl}${smokePath}`);
+        await expect(page.locator("body")).toBeVisible();
+        await expectGeneratedScreenContract(page, expect);
+        await expectNoHorizontalOverflow(page, expect);
+
+        if (viewport.name === "compact") {
+          let bootstrapRequests = 0;
+          await page.route("**/api/bootstrap**", async (route) => {
+            bootstrapRequests += 1;
+            await route.continue();
+          });
+          const bootstrapRequestsBeforePull = bootstrapRequests;
+
+          await expect(page.getByTestId("jskit-shell-bottom-nav")).toBeVisible();
+          expect(await isElementVisibleInViewport(page, "jskit-shell-drawer")).toBe(false);
+
+          const navButtonHeights = await page.getByTestId("jskit-shell-bottom-nav").locator(".v-btn").evaluateAll((buttons) =>
+            buttons.map((button) => button.getBoundingClientRect().height)
+          );
+          expect(navButtonHeights.length).toBeGreaterThan(0);
+          for (const height of navButtonHeights) {
+            expect(height).toBeGreaterThanOrEqual(48);
+          }
+
+          await pullToRefresh(page, expect);
+          await expect.poll(() => bootstrapRequests).toBeGreaterThan(bootstrapRequestsBeforePull);
+        } else {
+          await expect(page.getByTestId("jskit-shell-drawer")).toBeVisible();
+        }
+      });
+    }
+  });
+}
+
+export { DEFAULT_VIEWPORTS, runAdaptiveShellSmoke };

package/templates/expected-existing/src/pages/home/index.vue

@@ -1,12 +1,42 @@
 <template>
-  <v-card class="mx-auto" max-width="960" rounded="xl" border elevation="1">
-    <v-card-item class="px-6 py-5 px-md-8 py-md-7">
-      <v-card-title class="text-h4">welcome</v-card-title>
-      <v-card-subtitle class="text-subtitle-1 mt-2">starter app</v-card-subtitle>
-    </v-card-item>
-    <v-divider />
-    <v-card-text class="px-6 py-5 px-md-8 py-md-7 text-body-1 text-medium-emphasis">
-      Start by adding packages and pages to this app.
-    </v-card-text>
-  </v-card>
+  <section class="generated-ui-screen generated-ui-screen--app home-start-screen d-flex flex-column ga-4">
+    <header>
+      <p class="text-overline text-medium-emphasis mb-1">Home</p>
+      <h1 class="home-start-screen__title">Home base</h1>
+      <p class="text-body-2 text-medium-emphasis mb-0">
+        The app runtime is online and ready for the first real workflow.
+      </p>
+    </header>
+
+    <v-sheet rounded="lg" border class="home-start-screen__panel">
+      <h2 class="text-h6 mb-2">No activity yet</h2>
+      <p class="text-body-2 text-medium-emphasis mb-0">
+        Recent work, saved records, and next actions will appear here once this app has data.
+      </p>
+    </v-sheet>
+  </section>
 </template>
+
+<style scoped>
+.generated-ui-screen {
+  --generated-ui-screen-title-size: clamp(1.5rem, 3vw, 2.5rem);
+  --generated-ui-screen-panel-padding: 1rem;
+}
+
+.home-start-screen {
+  margin-inline: auto;
+  max-width: 48rem;
+}
+
+.home-start-screen__title {
+  font-size: var(--generated-ui-screen-title-size);
+  font-weight: 700;
+  letter-spacing: -0.03em;
+  line-height: 1.08;
+  margin: 0 0 0.45rem;
+}
+
+.home-start-screen__panel {
+  padding: var(--generated-ui-screen-panel-padding);
+}
+</style>

package/templates/src/components/ShellLayout.vue

@@ -1,92 +1,12 @@
-<script setup>
-import { useShellLayoutState } from "@jskit-ai/shell-web/client/composables/useShellLayoutState";
-import ShellOutlet from "@jskit-ai/shell-web/client/components/ShellOutlet";
-
-const props = defineProps({
-  surface: {
-    type: String,
-    default: ""
-  },
-  surfaceLabel: {
-    type: String,
-    default: ""
-  },
-  title: {
-    type: String,
-    default: ""
-  },
-  subtitle: {
-    type: String,
-    default: ""
+<script>
+import { h } from "vue";
+import PackageShellLayout from "@jskit-ai/shell-web/client/components/ShellLayout";
+
+export default {
+  name: "ShellLayout",
+  inheritAttrs: false,
+  setup(_, { attrs, slots }) {
+    return () => h(PackageShellLayout, attrs, slots);
   }
-});
-
-const { drawerOpen, toggleDrawer, resolvedSurface, resolvedSurfaceLabel } = useShellLayoutState(props);
+};
 </script>
-
-<template>
-  <v-layout class="shell-layout border rounded-lg overflow-hidden">
-    <v-app-bar border density="comfortable" elevation="0" class="bg-surface">
-      <v-app-bar-nav-icon aria-label="Toggle navigation menu" @click="toggleDrawer" />
-
-      <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 target="shell-layout:top-left" />
-        </div>
-      </slot>
-
-      <v-spacer />
-
-      <slot name="top-right" :surface="resolvedSurface">
-        <div class="d-flex align-center ga-2">
-          <ShellOutlet target="shell-layout:top-right" />
-        </div>
-      </slot>
-    </v-app-bar>
-
-    <v-navigation-drawer v-model="drawerOpen" border class="bg-surface" :width="248">
-      <slot name="menu" :surface="resolvedSurface">
-        <v-list nav density="comfortable" class="pt-2">
-          <v-list-subheader class="text-uppercase text-caption">Navigation</v-list-subheader>
-          <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
-            target="shell-layout:secondary-menu"
-            default-link-component-token="local.main.ui.surface-aware-menu-link-item"
-          />
-        </v-list>
-      </slot>
-    </v-navigation-drawer>
-
-    <v-main class="bg-background">
-      <v-container fluid class="shell-layout__content">
-        <h1 v-if="title" class="shell-layout__title text-h5">{{ title }}</h1>
-        <p v-if="subtitle" class="shell-layout__subtitle text-body-2 text-medium-emphasis">{{ subtitle }}</p>
-        <slot />
-      </v-container>
-    </v-main>
-  </v-layout>
-</template>
-
-<style scoped>
-.shell-layout {
-  min-height: 72vh;
-}
-
-.shell-layout__content {
-  padding: 0.75rem 1rem 1rem;
-}
-
-.shell-layout__title {
-  margin-bottom: 0.25rem;
-}
-
-.shell-layout__subtitle {
-  margin-bottom: 0.75rem;
-}
-</style>

package/templates/src/components/menus/TabLinkItem.vue

@@ -29,6 +29,10 @@ const props = defineProps({
   disabled: {
     type: Boolean,
     default: false
+  },
+  exact: {
+    type: Boolean,
+    default: false
   }
 });
 </script>

package/templates/src/error.js

@@ -2,12 +2,18 @@ import { createDefaultErrorPolicy } from "@jskit-ai/shell-web/client/error";
 
 /**
  * App-owned error handling contract.
+ * - intent chooses default presentation: resource-load, action-feedback, app-recoverable, blocking.
  * - policy(event, ctx): decide channel + presenter + message.
  * - defaultPresenterId: used when policy does not set presenterId.
  * - presenters: optional custom presenters registered at boot.
  */
 export default Object.freeze({
   defaultPresenterId: "material.snackbar",
-  policy: createDefaultErrorPolicy(),
+  policy: createDefaultErrorPolicy({
+    resourceLoadChannel: "silent",
+    actionFeedbackChannel: "snackbar",
+    appRecoverableChannel: "banner",
+    blockingChannel: "dialog"
+  }),
   presenters: []
 });

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,29 +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"
-                default-link-component-token="local.main.ui.surface-aware-menu-link-item"
-              />
-            </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/placement.js

@@ -13,10 +13,10 @@ export default function getPlacements() {
 
 addPlacement({
   id: "shell-web.home.menu.home",
-  target: "shell-layout:primary-menu",
+  target: "shell.primary-nav",
+  kind: "link",
   surfaces: ["home"],
   order: 50,
-  componentToken: "local.main.ui.surface-aware-menu-link-item",
   props: {
     label: "Home",
     surface: "home",
@@ -28,10 +28,10 @@ addPlacement({
 
 addPlacement({
   id: "shell-web.home.menu.settings",
-  target: "shell-layout:primary-menu",
+  target: "shell.primary-nav",
+  kind: "link",
   surfaces: ["home"],
   order: 100,
-  componentToken: "local.main.ui.surface-aware-menu-link-item",
   props: {
     label: "Settings",
     surface: "home",
@@ -42,10 +42,11 @@ addPlacement({
 
 addPlacement({
   id: "shell-web.home.settings.general",
-  target: "home-settings:primary-menu",
+  target: "page.section-nav",
+  owner: "home-settings",
+  kind: "link",
   surfaces: ["home"],
   order: 100,
-  componentToken: "local.main.ui.surface-aware-menu-link-item",
   props: {
     label: "General",
     surface: "home",