@jskit-ai/shell-web 0.1.35 → 0.1.36

package/package.descriptor.mjs

@@ -1,7 +1,7 @@
 export default Object.freeze({
   packageVersion: 1,
   packageId: "@jskit-ai/shell-web",
-  version: "0.1.35",
+  version: "0.1.36",
   kind: "runtime",
   description: "Web shell layout runtime with outlet-based placement contributions.",
   dependsOn: [],
@@ -83,7 +83,24 @@ export default Object.freeze({
             source: "templates/src/pages/home/settings.vue"
           }
         ],
-        contributions: []
+        contributions: [
+          {
+            id: "shell-web.home.menu.home",
+            target: "shell-layout:primary-menu",
+            surfaces: ["*"],
+            order: 50,
+            componentToken: "local.main.ui.surface-aware-menu-link-item",
+            source: "templates/src/placement.js"
+          },
+          {
+            id: "shell-web.home.menu.settings",
+            target: "shell-layout:primary-menu",
+            surfaces: ["home"],
+            order: 100,
+            componentToken: "local.main.ui.surface-aware-menu-link-item",
+            source: "templates/src/placement.js"
+          }
+        ]
       }
     }
   },
@@ -92,7 +109,7 @@ export default Object.freeze({
       runtime: {
         "@mdi/js": "^7.4.47",
         "@tanstack/vue-query": "^5.90.5",
-        "@jskit-ai/kernel": "0.1.36",
+        "@jskit-ai/kernel": "0.1.37",
         "vuetify": "^4.0.0"
       },
       dev: {}
@@ -258,7 +275,7 @@ export default Object.freeze({
         toSurface: "home",
         toSurfacePath: "settings/index.vue",
         ownership: "app",
-        reason: "Install shell-driven home settings index stub scaffold for app-owned landing or redirect behavior.",
+        reason: "Install shell-driven home settings landing page with a tiny browser-local shell preference example.",
         category: "shell-web",
         id: "shell-web-page-home-settings"
       }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jskit-ai/shell-web",
-  "version": "0.1.35",
+  "version": "0.1.36",
   "type": "module",
   "scripts": {
     "test": "node --test"
@@ -24,7 +24,7 @@
   "dependencies": {
     "@mdi/js": "^7.4.47",
     "@tanstack/vue-query": "^5.90.5",
-    "@jskit-ai/kernel": "0.1.36",
+    "@jskit-ai/kernel": "0.1.37",
     "vuetify": "^4.0.0"
   }
 }

package/src/client/composables/shellLayoutDrawerPreference.js

@@ -0,0 +1,43 @@
+const SHELL_LAYOUT_DRAWER_DEFAULT_OPEN_STORAGE_KEY = "jskit.shell-web.drawer-default-open";
+
+function readDrawerDefaultOpenPreference({
+  storage = typeof window === "object" ? window?.localStorage : null
+} = {}) {
+  if (!storage || typeof storage.getItem !== "function") {
+    return true;
+  }
+
+  try {
+    const storedValue = String(storage.getItem(SHELL_LAYOUT_DRAWER_DEFAULT_OPEN_STORAGE_KEY) || "").trim().toLowerCase();
+    if (storedValue === "false") {
+      return false;
+    }
+    if (storedValue === "true") {
+      return true;
+    }
+  } catch {
+    return true;
+  }
+
+  return true;
+}
+
+function writeDrawerDefaultOpenPreference(open, {
+  storage = typeof window === "object" ? window?.localStorage : null
+} = {}) {
+  if (!storage || typeof storage.setItem !== "function") {
+    return;
+  }
+
+  try {
+    storage.setItem(SHELL_LAYOUT_DRAWER_DEFAULT_OPEN_STORAGE_KEY, open ? "true" : "false");
+  } catch {
+    // Ignore localStorage write failures in unsupported or locked-down environments.
+  }
+}
+
+export {
+  SHELL_LAYOUT_DRAWER_DEFAULT_OPEN_STORAGE_KEY,
+  readDrawerDefaultOpenPreference,
+  writeDrawerDefaultOpenPreference
+};

package/src/client/composables/useShellLayoutState.js

@@ -7,6 +7,10 @@ import {
   resolveSurfaceDefinitionFromPlacementContext,
   resolveSurfaceIdFromPlacementPathname
 } from "../placement/surfaceContext.js";
+import {
+  readDrawerDefaultOpenPreference,
+  writeDrawerDefaultOpenPreference
+} from "./shellLayoutDrawerPreference.js";
 
 function toSurfaceLabel(surfaceId = "") {
   const normalizedSurfaceId = String(surfaceId || "").trim().toLowerCase();
@@ -21,6 +25,16 @@ function toSurfaceLabel(surfaceId = "") {
     .join(" ");
 }
 
+const drawerDefaultOpen = ref(readDrawerDefaultOpenPreference());
+const drawerOpen = ref(drawerDefaultOpen.value);
+
+function setDrawerDefaultOpen(open) {
+  const normalized = Boolean(open);
+  drawerDefaultOpen.value = normalized;
+  drawerOpen.value = normalized;
+  writeDrawerDefaultOpenPreference(normalized);
+}
+
 function useShellLayoutState(props = {}) {
   let route = null;
   try {
@@ -30,7 +44,6 @@ function useShellLayoutState(props = {}) {
   }
 
   const { context: placementContext } = useWebPlacementContext();
-  const drawerOpen = ref(true);
 
   function toggleDrawer() {
     drawerOpen.value = !drawerOpen.value;
@@ -78,7 +91,9 @@ function useShellLayoutState(props = {}) {
   });
 
   return Object.freeze({
+    drawerDefaultOpen,
     drawerOpen,
+    setDrawerDefaultOpen,
     toggleDrawer,
     resolvedSurface,
     resolvedSurfaceLabel

package/templates/src/components/ShellLayout.vue

@@ -48,7 +48,7 @@ const { drawerOpen, toggleDrawer, resolvedSurface, resolvedSurfaceLabel } = useS
     <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">{{ resolvedSurfaceLabel }}</v-list-subheader>
+          <v-list-subheader class="text-uppercase text-caption">Navigation</v-list-subheader>
           <ShellOutlet
             target="shell-layout:primary-menu"
             default

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

@@ -45,11 +45,7 @@ const health = computed(() => {
       <p class="text-medium-emphasis mb-0">
         This is your primary landing page. Replace this content with your actual product home.
       </p>
-      <div class="d-flex flex-wrap ga-3">
-        <v-btn color="primary" variant="flat" to="/home/settings">Open settings</v-btn>
-        <v-btn color="primary" variant="flat" to="/console">Open console surface</v-btn>
-        <v-btn color="secondary" variant="outlined" to="/auth/signout">Sign out</v-btn>
-      </div>
+      <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>
 </template>

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

@@ -1,8 +1,37 @@
 <script setup>
-// To redirect this settings shell to a child page, uncomment and edit the example below.
-// definePage({
-//   redirect: (to) => `${to.path}/your_child_segment`
-// });
+import { computed } from "vue";
+import { useShellLayoutState } from "@jskit-ai/shell-web/client/composables/useShellLayoutState";
+
+const { drawerDefaultOpen, setDrawerDefaultOpen } = useShellLayoutState();
+
+const drawerDefaultOpenModel = computed({
+  get() {
+    return drawerDefaultOpen.value;
+  },
+  set(value) {
+    setDrawerDefaultOpen(Boolean(value));
+  }
+});
 </script>
 
-<template />
+<template>
+  <section class="d-flex flex-column ga-4">
+    <div>
+      <h2 class="text-h6 mb-2">Shell settings</h2>
+      <p class="text-body-2 text-medium-emphasis mb-0">These starter settings live in this browser only.</p>
+    </div>
+
+    <v-switch
+      v-model="drawerDefaultOpenModel"
+      color="primary"
+      inset
+      hide-details="auto"
+      label="Open navigation drawer by default"
+    />
+
+    <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>

package/templates/src/placement.js

@@ -10,3 +10,32 @@ export { addPlacement };
 export default function getPlacements() {
   return registry.build();
 }
+
+addPlacement({
+  id: "shell-web.home.menu.home",
+  target: "shell-layout:primary-menu",
+  surfaces: ["*"],
+  order: 50,
+  componentToken: "local.main.ui.surface-aware-menu-link-item",
+  props: {
+    label: "Home",
+    surface: "home",
+    workspaceSuffix: "/",
+    nonWorkspaceSuffix: "/",
+    exact: true
+  }
+});
+
+addPlacement({
+  id: "shell-web.home.menu.settings",
+  target: "shell-layout:primary-menu",
+  surfaces: ["home"],
+  order: 100,
+  componentToken: "local.main.ui.surface-aware-menu-link-item",
+  props: {
+    label: "Settings",
+    surface: "home",
+    workspaceSuffix: "/settings",
+    nonWorkspaceSuffix: "/settings"
+  }
+});

package/test/settingsPlacementContract.test.js

@@ -8,10 +8,19 @@ import descriptor from "../package.descriptor.mjs";
 const TEST_DIRECTORY = path.dirname(fileURLToPath(import.meta.url));
 const PACKAGE_DIR = path.resolve(TEST_DIRECTORY, "..");
 
-function readSettingsOutlets() {
+function readOutlets(target = "") {
   const outlets = descriptor?.metadata?.ui?.placements?.outlets;
+  const normalizedTarget = String(target || "").trim();
   return Array.isArray(outlets)
-    ? outlets.filter((entry) => String(entry?.target || "").trim() === "home-settings:primary-menu")
+    ? outlets.filter((entry) => String(entry?.target || "").trim() === normalizedTarget)
+    : [];
+}
+
+function readContributions(target = "") {
+  const contributions = descriptor?.metadata?.ui?.placements?.contributions;
+  const normalizedTarget = String(target || "").trim();
+  return Array.isArray(contributions)
+    ? contributions.filter((entry) => String(entry?.target || "").trim() === normalizedTarget)
     : [];
 }
 
@@ -30,16 +39,31 @@ test("shell-web home settings template exposes surface-derived settings outlets"
   assert.match(source, /<RouterView \/>/);
 });
 
-test("shell-web home settings index template is a simple developer-owned stub", async () => {
+test("shell-web settings landing page exposes a tiny browser-local drawer preference", async () => {
   const source = await readFile(path.join(PACKAGE_DIR, "templates", "src", "pages", "home", "settings", "index.vue"), "utf8");
 
-  assert.match(source, /definePage/);
-  assert.match(source, /your_child_segment/);
+  assert.match(source, /useShellLayoutState/);
+  assert.match(source, /drawerDefaultOpen/);
+  assert.match(source, /setDrawerDefaultOpen/);
+  assert.match(source, /Open navigation drawer by default/);
+  assert.match(source, /live in this browser only/);
+});
+
+test("shell-web placement template seeds default Home and Settings drawer navigation", async () => {
+  const source = await readFile(path.join(PACKAGE_DIR, "templates", "src", "placement.js"), "utf8");
+
+  assert.match(source, /id: "shell-web\.home\.menu\.home"/);
+  assert.match(source, /target: "shell-layout:primary-menu"/);
+  assert.match(source, /label: "Home"/);
+  assert.match(source, /nonWorkspaceSuffix: "\/"/);
+  assert.match(source, /id: "shell-web\.home\.menu\.settings"/);
+  assert.match(source, /label: "Settings"/);
+  assert.match(source, /nonWorkspaceSuffix: "\/settings"/);
 });
 
-test("shell-web descriptor metadata advertises home settings outlets and installs the scaffold page", () => {
+test("shell-web descriptor metadata advertises home settings outlets, default drawer links, and installs the scaffold page", () => {
   assert.deepEqual(
-    readSettingsOutlets(),
+    readOutlets("home-settings:primary-menu"),
     [
       {
         target: "home-settings:primary-menu",
@@ -50,6 +74,28 @@ test("shell-web descriptor metadata advertises home settings outlets and install
     ]
   );
 
+  assert.deepEqual(
+    readContributions("shell-layout:primary-menu"),
+    [
+      {
+        id: "shell-web.home.menu.home",
+        target: "shell-layout:primary-menu",
+        surfaces: ["*"],
+        order: 50,
+        componentToken: "local.main.ui.surface-aware-menu-link-item",
+        source: "templates/src/placement.js"
+      },
+      {
+        id: "shell-web.home.menu.settings",
+        target: "shell-layout:primary-menu",
+        surfaces: ["home"],
+        order: 100,
+        componentToken: "local.main.ui.surface-aware-menu-link-item",
+        source: "templates/src/placement.js"
+      }
+    ]
+  );
+
   assert.deepEqual(findFileMutation("shell-web-page-home-settings-shell"), {
     from: "templates/src/pages/home/settings.vue",
     toSurface: "home",
@@ -65,14 +111,17 @@ test("shell-web descriptor metadata advertises home settings outlets and install
     toSurface: "home",
     toSurfacePath: "settings/index.vue",
     ownership: "app",
-    reason: "Install shell-driven home settings index stub scaffold for app-owned landing or redirect behavior.",
+    reason: "Install shell-driven home settings landing page with a tiny browser-local shell preference example.",
     category: "shell-web",
     id: "shell-web-page-home-settings"
   });
 });
 
-test("shell-web home starter page links to the home settings scaffold", async () => {
+test("shell-web home starter page relies on drawer navigation instead of dead feature buttons", async () => {
   const source = await readFile(path.join(PACKAGE_DIR, "templates", "src", "pages", "home", "index.vue"), "utf8");
 
-  assert.match(source, /to="\/home\/settings"/);
+  assert.match(source, /Use the navigation drawer to move around the shell\./);
+  assert.doesNotMatch(source, /\/home\/settings/);
+  assert.doesNotMatch(source, /\/console/);
+  assert.doesNotMatch(source, /\/auth\/signout/);
 });

package/test/useShellLayoutState.test.js

@@ -0,0 +1,50 @@
+import assert from "node:assert/strict";
+import test from "node:test";
+import {
+  SHELL_LAYOUT_DRAWER_DEFAULT_OPEN_STORAGE_KEY,
+  readDrawerDefaultOpenPreference,
+  writeDrawerDefaultOpenPreference
+} from "../src/client/composables/shellLayoutDrawerPreference.js";
+
+function createStorage(initial = {}) {
+  const values = new Map(Object.entries(initial));
+  return {
+    getItem(key) {
+      return values.has(key) ? values.get(key) : null;
+    },
+    setItem(key, value) {
+      values.set(key, String(value));
+    }
+  };
+}
+
+test("readDrawerDefaultOpenPreference defaults to true when storage is missing or empty", () => {
+  assert.equal(readDrawerDefaultOpenPreference({ storage: null }), true);
+  assert.equal(readDrawerDefaultOpenPreference({ storage: createStorage() }), true);
+});
+
+test("readDrawerDefaultOpenPreference reads explicit stored booleans", () => {
+  assert.equal(
+    readDrawerDefaultOpenPreference({
+      storage: createStorage({ [SHELL_LAYOUT_DRAWER_DEFAULT_OPEN_STORAGE_KEY]: "false" })
+    }),
+    false
+  );
+
+  assert.equal(
+    readDrawerDefaultOpenPreference({
+      storage: createStorage({ [SHELL_LAYOUT_DRAWER_DEFAULT_OPEN_STORAGE_KEY]: "true" })
+    }),
+    true
+  );
+});
+
+test("writeDrawerDefaultOpenPreference persists normalized boolean strings", () => {
+  const storage = createStorage();
+
+  writeDrawerDefaultOpenPreference(false, { storage });
+  assert.equal(storage.getItem(SHELL_LAYOUT_DRAWER_DEFAULT_OPEN_STORAGE_KEY), "false");
+
+  writeDrawerDefaultOpenPreference(true, { storage });
+  assert.equal(storage.getItem(SHELL_LAYOUT_DRAWER_DEFAULT_OPEN_STORAGE_KEY), "true");
+});