@jskit-ai/shell-web 0.1.147 → 0.1.149

package/package.descriptor.mjs

@@ -1,7 +1,7 @@
 export default Object.freeze({
   packageVersion: 1,
   packageId: "@jskit-ai/shell-web",
-  version: "0.1.147",
+  version: "0.1.149",
   kind: "runtime",
   description: "Web shell layout runtime with outlet-based placement contributions.",
   dependsOn: [],
@@ -311,7 +311,7 @@ export default Object.freeze({
     dependencies: {
       runtime: {
         "@mdi/js": "^7.4.47",
-        "@jskit-ai/kernel": "0.1.146"
+        "@jskit-ai/kernel": "0.1.147"
       },
       dev: {
         "@playwright/test": "1.61.1"

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jskit-ai/shell-web",
-  "version": "0.1.147",
+  "version": "0.1.149",
   "type": "module",
   "scripts": {
     "test": "node --test"
@@ -28,7 +28,7 @@
   },
   "dependencies": {
     "@mdi/js": "^7.4.47",
-    "@jskit-ai/kernel": "0.1.146"
+    "@jskit-ai/kernel": "0.1.147"
   },
   "peerDependencies": {
     "pinia": "^3.0.4",

package/src/client/components/ShellLayout.vue

@@ -9,6 +9,10 @@ import {
 } from "vue";
 import { useDisplay } from "vuetify";
 import { useShellLayoutState } from "../composables/useShellLayoutState.js";
+import {
+  resolveShellDrawerPresentation,
+  resolveShellDrawerToggleLabel
+} from "../support/drawerPresentation.js";
 import ShellOutlet from "./ShellOutlet.vue";
 import ShellRouteTransition from "./ShellRouteTransition.vue";
 
@@ -28,6 +32,10 @@ const props = defineProps({
   subtitle: {
     type: String,
     default: ""
+  },
+  desktopDrawerClosedMode: {
+    type: String,
+    default: "rail"
   }
 });
 
@@ -47,6 +55,7 @@ const display = useDisplay();
 const refreshRuntime = inject("jskit.shell-web.runtime.web-refresh.client", null);
 const pullDistance = ref(0);
 const pullRefreshing = ref(false);
+const wideDrawerOpen = ref(Boolean(drawerDefaultOpen.value));
 let activePull = null;
 
 const PULL_REFRESH_TRIGGER_DISTANCE = 72;
@@ -63,6 +72,15 @@ const layoutClass = computed(() => {
   return "expanded";
 });
 const isCompactLayout = computed(() => layoutClass.value === "compact");
+const drawerPresentation = computed(() => resolveShellDrawerPresentation({
+  compact: isCompactLayout.value,
+  open: drawerOpen.value,
+  desktopClosedMode: props.desktopDrawerClosedMode
+}));
+const drawerToggleLabel = computed(() => resolveShellDrawerToggleLabel({
+  compact: isCompactLayout.value,
+  open: drawerOpen.value
+}));
 const pullProgress = computed(() =>
   Math.min(100, Math.round((pullDistance.value / PULL_REFRESH_TRIGGER_DISTANCE) * 100))
 );
@@ -79,10 +97,19 @@ const pullRefreshStyle = computed(() => ({
   "--shell-pull-refresh-distance": `${Math.round(Math.min(pullDistance.value, PULL_REFRESH_MAX_DISTANCE))}px`
 }));
 
+watch(
+  drawerOpen,
+  (open) => {
+    if (!isCompactLayout.value) {
+      wideDrawerOpen.value = Boolean(open);
+    }
+  }
+);
+
 watch(
   isCompactLayout,
   (compact) => {
-    setDrawerOpen(compact ? false : drawerDefaultOpen.value);
+    setDrawerOpen(compact ? false : wideDrawerOpen.value);
   },
   { immediate: true }
 );
@@ -132,6 +159,12 @@ function handlePullPointerDown(event) {
   };
 }
 
+function handleDrawerVisibilityChange(open) {
+  if (isCompactLayout.value || drawerPresentation.value.closedMode === "hidden" || open === false) {
+    setDrawerOpen(open);
+  }
+}
+
 function handlePullPointerMove(event) {
   if (!activePull || event.pointerId !== activePull.pointerId) {
     return;
@@ -359,7 +392,10 @@ function touchListIncludesActiveTouch(touchList) {
   >
     <v-app-bar-nav-icon
       class="shell-layout__nav-toggle"
-      aria-label="Toggle navigation menu"
+      data-testid="jskit-shell-nav-toggle"
+      :aria-label="drawerToggleLabel"
+      :aria-expanded="drawerOpen"
+      aria-controls="jskit-shell-drawer"
       @click="toggleDrawer"
     />
 
@@ -400,17 +436,24 @@ function touchListIncludesActiveTouch(touchList) {
   </div>
 
   <v-navigation-drawer
-    v-model="drawerOpen"
+    id="jskit-shell-drawer"
+    :model-value="drawerPresentation.visible"
     border
     class="bg-surface"
     data-testid="jskit-shell-drawer"
+    :data-presentation="drawerPresentation.kind"
     :temporary="isCompactLayout"
     :permanent="!isCompactLayout"
     :width="248"
+    :rail="drawerPresentation.rail"
+    :rail-width="80"
+    @update:model-value="handleDrawerVisibilityChange"
   >
-    <slot name="menu" :surface="resolvedSurface">
+    <slot name="menu" :surface="resolvedSurface" :rail="drawerPresentation.rail">
       <v-list nav density="comfortable" class="pt-2">
-        <v-list-subheader class="text-uppercase text-caption">{{ resolvedSurfaceLabel }}</v-list-subheader>
+        <v-list-subheader v-if="!drawerPresentation.rail" class="text-uppercase text-caption">
+          {{ resolvedSurfaceLabel }}
+        </v-list-subheader>
         <ShellOutlet
           target="shell-layout:primary-menu"
           default

package/src/client/components/ShellMenuLinkItem.vue

@@ -68,6 +68,8 @@ const resolvedIcon = computed(() =>
     :prepend-icon="resolvedIcon || undefined"
     :disabled="props.disabled"
     :exact="props.exact"
+    :aria-label="props.label"
+    v-tooltip="props.label"
   />
 </template>
 

package/src/client/components/ShellSurfaceAwareMenuLinkItem.vue

@@ -113,6 +113,8 @@ const resolvedIcon = computed(() =>
     :prepend-icon="resolvedIcon || undefined"
     :disabled="props.disabled"
     :exact="props.exact"
+    :aria-label="props.label"
+    v-tooltip="props.label"
   />
 </template>
 

package/src/client/support/drawerPresentation.js

@@ -0,0 +1,58 @@
+const DESKTOP_DRAWER_CLOSED_MODES = Object.freeze(["rail", "hidden"]);
+
+function normalizeDesktopDrawerClosedMode(value = "rail") {
+  const normalized = String(value || "rail").trim().toLowerCase();
+  return DESKTOP_DRAWER_CLOSED_MODES.includes(normalized) ? normalized : "rail";
+}
+
+function resolveShellDrawerPresentation({
+  compact = false,
+  open = false,
+  desktopClosedMode = "rail"
+} = {}) {
+  const closedMode = normalizeDesktopDrawerClosedMode(desktopClosedMode);
+  if (compact) {
+    return Object.freeze({
+      visible: Boolean(open),
+      rail: false,
+      kind: "modal",
+      closedMode
+    });
+  }
+  if (open) {
+    return Object.freeze({
+      visible: true,
+      rail: false,
+      kind: "drawer",
+      closedMode
+    });
+  }
+  if (closedMode === "hidden") {
+    return Object.freeze({
+      visible: false,
+      rail: false,
+      kind: "hidden",
+      closedMode
+    });
+  }
+  return Object.freeze({
+    visible: true,
+    rail: true,
+    kind: "rail",
+    closedMode
+  });
+}
+
+function resolveShellDrawerToggleLabel({ compact = false, open = false } = {}) {
+  if (compact) {
+    return open ? "Close navigation menu" : "Open navigation menu";
+  }
+  return open ? "Collapse navigation drawer" : "Expand navigation drawer";
+}
+
+export {
+  DESKTOP_DRAWER_CLOSED_MODES,
+  normalizeDesktopDrawerClosedMode,
+  resolveShellDrawerPresentation,
+  resolveShellDrawerToggleLabel
+};

package/src/test/adaptiveShellSmoke.js

@@ -94,6 +94,11 @@ async function runAdaptiveShellSmokeCase({
 
     await expect(page.getByTestId("jskit-shell-bottom-nav")).toBeVisible();
     expect(await isElementVisibleInViewport(page, "jskit-shell-drawer")).toBe(false);
+    await page.getByTestId("jskit-shell-nav-toggle").click();
+    await expect(page.getByTestId("jskit-shell-drawer")).toBeVisible();
+    await expect(page.getByTestId("jskit-shell-drawer")).toHaveAttribute("data-presentation", "modal");
+    await page.keyboard.press("Escape");
+    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)
@@ -107,6 +112,14 @@ async function runAdaptiveShellSmokeCase({
     await expect.poll(() => bootstrapRequests).toBeGreaterThan(bootstrapRequestsBeforePull);
   } else {
     await expect(page.getByTestId("jskit-shell-drawer")).toBeVisible();
+    await page.getByTestId("jskit-shell-nav-toggle").click();
+    await expect(page.getByTestId("jskit-shell-drawer")).toBeVisible();
+    await expect(page.getByTestId("jskit-shell-drawer")).toHaveAttribute("data-presentation", "rail");
+    const railWidth = await page.getByTestId("jskit-shell-drawer").evaluate(
+      (element) => element.getBoundingClientRect().width
+    );
+    expect(railWidth).toBeGreaterThanOrEqual(79);
+    expect(railWidth).toBeLessThanOrEqual(81);
   }
 }
 

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

@@ -19,7 +19,7 @@ const drawerDefaultOpenModel = computed({
     <div>
       <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.
+        On wider screens, collapsed navigation remains available as a rail. Phone layouts close the drawer and keep primary navigation in the bottom bar.
       </p>
     </div>
 
@@ -28,7 +28,7 @@ const drawerDefaultOpenModel = computed({
       color="primary"
       inset
       hide-details="auto"
-      label="Open drawer by default on wider screens"
+      label="Start with expanded navigation on wider screens"
     />
   </section>
 </template>

package/test/drawerPresentation.test.js

@@ -0,0 +1,68 @@
+import assert from "node:assert/strict";
+import test from "node:test";
+import {
+  normalizeDesktopDrawerClosedMode,
+  resolveShellDrawerPresentation,
+  resolveShellDrawerToggleLabel
+} from "../src/client/support/drawerPresentation.js";
+
+test("wide closed navigation defaults to a visible Material navigation rail", () => {
+  assert.deepEqual(
+    resolveShellDrawerPresentation({ compact: false, open: false }),
+    {
+      visible: true,
+      rail: true,
+      kind: "rail",
+      closedMode: "rail"
+    }
+  );
+});
+
+test("compact closed navigation dismisses instead of retaining a rail", () => {
+  assert.deepEqual(
+    resolveShellDrawerPresentation({ compact: true, open: false }),
+    {
+      visible: false,
+      rail: false,
+      kind: "modal",
+      closedMode: "rail"
+    }
+  );
+});
+
+test("desktopDrawerClosedMode hidden preserves an explicitly hidden wide drawer", () => {
+  assert.equal(normalizeDesktopDrawerClosedMode("hidden"), "hidden");
+  assert.deepEqual(
+    resolveShellDrawerPresentation({
+      compact: false,
+      open: false,
+      desktopClosedMode: "hidden"
+    }),
+    {
+      visible: false,
+      rail: false,
+      kind: "hidden",
+      closedMode: "hidden"
+    }
+  );
+});
+
+test("open navigation renders as a full drawer and labels its toggle responsively", () => {
+  assert.deepEqual(
+    resolveShellDrawerPresentation({ compact: false, open: true }),
+    {
+      visible: true,
+      rail: false,
+      kind: "drawer",
+      closedMode: "rail"
+    }
+  );
+  assert.equal(
+    resolveShellDrawerToggleLabel({ compact: false, open: true }),
+    "Collapse navigation drawer"
+  );
+  assert.equal(
+    resolveShellDrawerToggleLabel({ compact: true, open: false }),
+    "Open navigation menu"
+  );
+});

package/test/linkItemScaffoldContract.test.js

@@ -151,10 +151,14 @@ test("shell-web generic link items support the expected shared route and icon be
 
   assert.match(shellMenuSource, /exact:\s*\{/);
   assert.match(shellMenuSource, /:exact="props\.exact"/);
+  assert.match(shellMenuSource, /:aria-label="props\.label"/);
+  assert.match(shellMenuSource, /v-tooltip="props\.label"/);
   assert.match(shellMenuSource, /class="shell-menu-link-item"/);
   assert.match(shellMenuSource, /min-height:\s*48px/);
   assert.match(shellSurfaceAwareSource, /exact:\s*\{/);
   assert.match(shellSurfaceAwareSource, /:exact="props\.exact"/);
+  assert.match(shellSurfaceAwareSource, /:aria-label="props\.label"/);
+  assert.match(shellSurfaceAwareSource, /v-tooltip="props\.label"/);
   assert.match(shellSurfaceAwareSource, /class="shell-menu-link-item"/);
   assert.match(shellSurfaceAwareSource, /min-height:\s*48px/);
   assert.match(shellTabSource, /icon:\s*\{/);

package/test/settingsPlacementContract.test.js

@@ -95,6 +95,12 @@ test("shell-web shell layout registers navigation at the app layout level", asyn
   assert.match(source, /target="shell-layout:primary-menu"[\s\S]*default/);
   assert.doesNotMatch(source, /target="shell-layout:primary-bottom-nav"[\s\S]*default/);
   assert.match(source, /data-testid="jskit-shell-drawer"/);
+  assert.match(source, /desktopDrawerClosedMode/);
+  assert.match(source, /default: "rail"/);
+  assert.match(source, /:rail="drawerPresentation\.rail"/);
+  assert.match(source, /:rail-width="80"/);
+  assert.match(source, /:model-value="drawerPresentation\.visible"/);
+  assert.match(source, /data-testid="jskit-shell-nav-toggle"/);
   assert.match(source, /data-testid="jskit-shell-bottom-nav"/);
   assert.match(source, /padding:\s*0\.75rem 1rem calc\(1rem \+ env\(safe-area-inset-bottom, 0px\)\)/);
 
@@ -288,8 +294,9 @@ test("shell-web settings general child page exposes an adaptive drawer preferenc
   assert.match(source, /generated-ui-screen generated-ui-screen--settings settings-general-screen/);
   assert.match(source, /drawerDefaultOpen/);
   assert.match(source, /setDrawerDefaultOpen/);
-  assert.match(source, /Phone layouts keep primary navigation in the bottom bar/);
-  assert.match(source, /Open drawer by default on wider screens/);
+  assert.match(source, /collapsed navigation remains available as a rail/);
+  assert.match(source, /Phone layouts close the drawer/);
+  assert.match(source, /Start with expanded navigation on wider screens/);
   assert.match(source, /min-height:\s*48px/);
   assert.doesNotMatch(source, /live in this browser only|tiny example|starter settings/);
 });