@jskit-ai/shell-web 0.1.150 → 0.1.151

package/CHANGELOG.md

@@ -1,5 +1,10 @@
 # Changelog
 
+## 0.1.151 - 2026-08-13
+
+- Replace Vuetify's oversized default drawer icon spacer with one public `navigationItemSpacing` value, defaulting to 12px for both icon-to-label and widest-label-to-edge spacing.
+- Keep the Material 3 80px default rail while documenting `railWidth` as the supported product-density override.
+
 ## 0.1.150 - 2026-08-13
 
 - Give shell navigation tooltips one opaque, theme-owned Material color pair on hover and keyboard focus.

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

@@ -9,6 +9,8 @@ const theme = useTheme();
 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");
+const railWidth = computed(() => Number(route.query.railWidth) || undefined);
+const navigationItemSpacing = computed(() => Number(route.query.navigationItemSpacing) || undefined);
 
 watchEffect(function applyFixtureTheme() {
   const themeName = `${surface.value}-${themeMode.value}`;
@@ -20,7 +22,12 @@ watchEffect(function applyFixtureTheme() {
 
 <template>
   <v-app>
-    <ShellLayout :surface="surface" :surface-label="surfaceLabel">
+    <ShellLayout
+      :surface="surface"
+      :surface-label="surfaceLabel"
+      :rail-width="railWidth"
+      :navigation-item-spacing="navigationItemSpacing"
+    >
       <RouterView />
     </ShellLayout>
   </v-app>

package/package.descriptor.mjs

@@ -1,7 +1,7 @@
 export default Object.freeze({
   packageVersion: 1,
   packageId: "@jskit-ai/shell-web",
-  version: "0.1.150",
+  version: "0.1.151",
   kind: "runtime",
   description: "Web shell layout runtime with outlet-based placement contributions.",
   dependsOn: [],

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jskit-ai/shell-web",
-  "version": "0.1.150",
+  "version": "0.1.151",
   "type": "module",
   "scripts": {
     "test": "node --test"

package/src/client/components/ShellLayout.vue

@@ -16,9 +16,10 @@ import {
 } from "../support/drawerPresentation.js";
 import {
   DEFAULT_SHELL_DRAWER_WIDTH,
+  DEFAULT_SHELL_NAVIGATION_ITEM_SPACING,
   DEFAULT_SHELL_RAIL_WIDTH,
-  SHELL_DRAWER_LABEL_END_GAP,
   normalizeShellDrawerWidth,
+  normalizeShellNavigationItemSpacing,
   normalizeShellRailWidth,
   resolveContentAwareDrawerWidth
 } from "../support/drawerWidth.js";
@@ -53,6 +54,10 @@ const props = defineProps({
   railWidth: {
     type: Number,
     default: DEFAULT_SHELL_RAIL_WIDTH
+  },
+  navigationItemSpacing: {
+    type: Number,
+    default: DEFAULT_SHELL_NAVIGATION_ITEM_SPACING
   }
 });
 
@@ -111,6 +116,9 @@ const resolvedDrawerWidth = computed(() => {
   return normalizeShellDrawerWidth(measuredDrawerWidth.value);
 });
 const resolvedRailWidth = computed(() => normalizeShellRailWidth(props.railWidth));
+const resolvedNavigationItemSpacing = computed(() =>
+  normalizeShellNavigationItemSpacing(props.navigationItemSpacing)
+);
 const pullProgress = computed(() =>
   Math.min(100, Math.round((pullDistance.value / PULL_REFRESH_TRIGGER_DISTANCE) * 100))
 );
@@ -140,6 +148,7 @@ watch(
 
 watch(drawerPresentation, scheduleDrawerWidthMeasurement, { flush: "post" });
 watch(resolvedSurface, scheduleDrawerWidthMeasurement, { flush: "post" });
+watch(resolvedNavigationItemSpacing, scheduleDrawerWidthMeasurement, { flush: "post" });
 
 onMounted(attachShellListeners);
 onBeforeUnmount(detachShellListeners);
@@ -299,7 +308,7 @@ function measureDrawerContentWidth() {
   }
 
   const nextWidth = resolveContentAwareDrawerWidth(measurements, {
-    endGap: SHELL_DRAWER_LABEL_END_GAP + endBorderWidth
+    endGap: resolvedNavigationItemSpacing.value + endBorderWidth
   });
   if (Math.abs(nextWidth - measuredDrawerWidth.value) >= 0.25) {
     measuredDrawerWidth.value = nextWidth;
@@ -617,8 +626,9 @@ function touchListIncludesActiveTouch(touchList) {
     :data-presentation="drawerPresentation.kind"
     :data-drawer-width-mode="props.drawerWidth === null || props.drawerWidth === undefined ? 'content' : 'fixed'"
     :data-drawer-width="resolvedDrawerWidth"
+    :data-navigation-item-spacing="resolvedNavigationItemSpacing"
     :data-rail-width="resolvedRailWidth"
-    :style="{ '--shell-drawer-label-end-gap': `${SHELL_DRAWER_LABEL_END_GAP}px` }"
+    :style="{ '--shell-navigation-item-spacing': `${resolvedNavigationItemSpacing}px` }"
     :temporary="isCompactLayout"
     :permanent="!isCompactLayout"
     :width="resolvedDrawerWidth"
@@ -627,7 +637,12 @@ function touchListIncludesActiveTouch(touchList) {
     @update:model-value="handleDrawerVisibilityChange"
   >
     <slot name="menu" :surface="resolvedSurface" :rail="drawerPresentation.rail">
-      <v-list nav density="comfortable" class="pt-2">
+      <v-list
+        nav
+        density="comfortable"
+        class="pt-2"
+        :prepend-gap="resolvedNavigationItemSpacing"
+      >
         <v-list-subheader v-if="!drawerPresentation.rail" class="text-uppercase text-caption">
           {{ resolvedSurfaceLabel }}
         </v-list-subheader>
@@ -721,7 +736,7 @@ function touchListIncludesActiveTouch(touchList) {
 
 .shell-layout__drawer[data-presentation="drawer"] :deep(.v-list--nav),
 .shell-layout__drawer[data-presentation="drawer"] :deep(.v-list-item) {
-  padding-inline-end: calc(var(--shell-drawer-label-end-gap) / 2);
+  padding-inline-end: calc(var(--shell-navigation-item-spacing) / 2);
 }
 
 .shell-layout__drawer[data-presentation="rail"] :deep(.v-list-item) {

package/src/client/support/drawerWidth.js

@@ -4,7 +4,9 @@ const MINIMUM_SHELL_DRAWER_WIDTH = 120;
 const MAXIMUM_SHELL_DRAWER_WIDTH = 360;
 const MINIMUM_SHELL_RAIL_WIDTH = 48;
 const MAXIMUM_SHELL_RAIL_WIDTH = 160;
-const SHELL_DRAWER_LABEL_END_GAP = 10;
+const DEFAULT_SHELL_NAVIGATION_ITEM_SPACING = 12;
+const MINIMUM_SHELL_NAVIGATION_ITEM_SPACING = 8;
+const MAXIMUM_SHELL_NAVIGATION_ITEM_SPACING = 24;
 
 function clampNumber(value, minimum, maximum) {
   return Math.min(maximum, Math.max(minimum, value));
@@ -34,10 +36,25 @@ function normalizeShellRailWidth(value, fallback = DEFAULT_SHELL_RAIL_WIDTH) {
   );
 }
 
+function normalizeShellNavigationItemSpacing(
+  value,
+  fallback = DEFAULT_SHELL_NAVIGATION_ITEM_SPACING
+) {
+  const parsed = Number(value);
+  if (!Number.isFinite(parsed) || parsed <= 0) {
+    return fallback;
+  }
+  return clampNumber(
+    Math.round(parsed),
+    MINIMUM_SHELL_NAVIGATION_ITEM_SPACING,
+    MAXIMUM_SHELL_NAVIGATION_ITEM_SPACING
+  );
+}
+
 function resolveContentAwareDrawerWidth(
   measurements = [],
   {
-    endGap = SHELL_DRAWER_LABEL_END_GAP,
+    endGap = DEFAULT_SHELL_NAVIGATION_ITEM_SPACING,
     minimum = MINIMUM_SHELL_DRAWER_WIDTH,
     maximum = MAXIMUM_SHELL_DRAWER_WIDTH,
     fallback = DEFAULT_SHELL_DRAWER_WIDTH
@@ -56,19 +73,19 @@ function resolveContentAwareDrawerWidth(
   if (requiredWidth <= 0) {
     return normalizeShellDrawerWidth(fallback);
   }
-  // Layout boxes expose integer client widths even when the rendered glyph
-  // range is fractional. Round outward so the final glyph is never ellipsized
-  // at the exact end-gap boundary.
-  return clampNumber(Math.ceil(requiredWidth), minimum, maximum);
+  // Preserve subpixel font metrics while rounding outward enough to avoid
+  // clipping the final glyph at the exact spacing boundary.
+  return clampNumber(Math.ceil(requiredWidth * 4) / 4, minimum, maximum);
 }
 
 export {
   DEFAULT_SHELL_DRAWER_WIDTH,
+  DEFAULT_SHELL_NAVIGATION_ITEM_SPACING,
   DEFAULT_SHELL_RAIL_WIDTH,
   MAXIMUM_SHELL_DRAWER_WIDTH,
   MINIMUM_SHELL_DRAWER_WIDTH,
-  SHELL_DRAWER_LABEL_END_GAP,
   normalizeShellDrawerWidth,
+  normalizeShellNavigationItemSpacing,
   normalizeShellRailWidth,
   resolveContentAwareDrawerWidth
 };

package/src/test/adaptiveShellSmoke.js

@@ -104,6 +104,8 @@ async function expectContentAwareDrawerFit(drawer, expect) {
   if (await drawer.getAttribute("data-drawer-width-mode") !== "content") {
     return;
   }
+  const configuredSpacing = Number(await drawer.getAttribute("data-navigation-item-spacing"));
+  expect(Number.isFinite(configuredSpacing)).toBe(true);
 
   const fit = await drawer.evaluate((element) => {
     const drawerRect = element.getBoundingClientRect();
@@ -125,6 +127,8 @@ async function expectContentAwareDrawerFit(drawer, expect) {
         range.selectNodeContents(label);
         const textRect = range.getBoundingClientRect();
         range.detach?.();
+        const icon = label.closest(".v-list-item")?.querySelector(".v-icon");
+        const iconRect = icon?.getBoundingClientRect();
         return {
           clipped: (
             label.scrollWidth > label.clientWidth ||
@@ -133,6 +137,9 @@ async function expectContentAwareDrawerFit(drawer, expect) {
               ? textRect.left < innerEnd - 1
               : textRect.right > innerEnd + 1)
           ),
+          iconLabelGap: iconRect
+            ? rightToLeft ? iconRect.left - textRect.right : textRect.left - iconRect.right
+            : null,
           logicalEnd: rightToLeft ? textRect.left : textRect.right,
           width: textRect.width
         };
@@ -154,14 +161,20 @@ async function expectContentAwareDrawerFit(drawer, expect) {
       clipped: labels.some((label) => label.clipped),
       endGap: rightToLeft
         ? furthestLabel.logicalEnd - innerEnd
-        : innerEnd - furthestLabel.logicalEnd
+        : innerEnd - furthestLabel.logicalEnd,
+      iconLabelGaps: labels
+        .map((label) => label.iconLabelGap)
+        .filter((gap) => Number.isFinite(gap))
     };
   });
 
   expect(fit).not.toBeNull();
   expect(fit.clipped).toBe(false);
-  expect(fit.endGap).toBeGreaterThanOrEqual(9);
-  expect(fit.endGap).toBeLessThanOrEqual(11);
+  expect(Math.abs(fit.endGap - configuredSpacing)).toBeLessThanOrEqual(1.1);
+  expect(fit.iconLabelGaps.length).toBeGreaterThan(0);
+  for (const gap of fit.iconLabelGaps) {
+    expect(Math.abs(gap - configuredSpacing)).toBeLessThanOrEqual(1);
+  }
 }
 
 async function expectCentredRailNavigation(page, drawer, expect) {

package/templates/src/components/ShellLayout.vue

@@ -6,7 +6,7 @@ export default {
   name: "ShellLayout",
   inheritAttrs: false,
   setup(_, { attrs, slots }) {
-    // Keep drawerWidth, railWidth, and future shell props package-owned.
+    // Keep drawerWidth, railWidth, navigationItemSpacing, and future shell props package-owned.
     return () => h(PackageShellLayout, attrs, slots);
   }
 };

package/test/adaptiveShell.browser.test.js

@@ -166,6 +166,8 @@ async function assertTooltipContrast(page, linkName, interaction) {
 async function assertDrawerFit(page) {
   const drawer = page.getByTestId("jskit-shell-drawer");
   await expect(drawer).toHaveAttribute("data-presentation", "drawer");
+  const configuredSpacing = Number(await drawer.getAttribute("data-navigation-item-spacing"));
+  assert.ok(Number.isFinite(configuredSpacing));
   await expect.poll(async () => {
     const configured = Number(await drawer.getAttribute("data-drawer-width"));
     const box = await drawer.boundingBox();
@@ -180,12 +182,14 @@ async function assertDrawerFit(page) {
       range.selectNodeContents(label);
       const rect = range.getBoundingClientRect();
       range.detach?.();
+      const iconRect = label.closest(".v-list-item")?.querySelector(".v-icon")?.getBoundingClientRect();
       return {
         clientHeight: label.clientHeight,
         clientWidth: label.clientWidth,
         rect,
         scrollHeight: label.scrollHeight,
-        scrollWidth: label.scrollWidth
+        scrollWidth: label.scrollWidth,
+        iconLabelGap: iconRect ? rect.left - iconRect.right : null
       };
     });
     const furthestEnd = Math.max(...labels.map((label) => label.rect.right));
@@ -195,11 +199,24 @@ async function assertDrawerFit(page) {
         label.scrollHeight > label.clientHeight
       )),
       endGap: innerEnd - furthestEnd,
+      iconLabelGaps: labels
+        .map((label) => label.iconLabelGap)
+        .filter((gap) => Number.isFinite(gap)),
       overflow: document.documentElement.scrollWidth - document.documentElement.clientWidth
     };
   });
   assert.equal(result.clipped, false, "A drawer label was clipped or ellipsized.");
-  assert.ok(result.endGap >= 9 && result.endGap <= 11, `Drawer label end gap was ${result.endGap}px.`);
+  assert.ok(
+    Math.abs(result.endGap - configuredSpacing) <= 1.1,
+    `Drawer label end gap was ${result.endGap}px; expected ${configuredSpacing}px.`
+  );
+  assert.ok(result.iconLabelGaps.length > 0, "Drawer links exposed no measurable icon/label gap.");
+  for (const gap of result.iconLabelGaps) {
+    assert.ok(
+      Math.abs(gap - configuredSpacing) <= 1,
+      `Drawer icon/label gap was ${gap}px; expected ${configuredSpacing}px.`
+    );
+  }
   assert.ok(result.overflow <= 1, `Page overflowed horizontally by ${result.overflow}px.`);
 }
 
@@ -282,6 +299,23 @@ test("shell-web adaptive navigation passes package-owned browser contracts", {
     await assertDrawerFit(railPage);
     await assertRailKeyboardAndSelection(railPage);
     await railPage.close();
+
+    const configuredPage = await context.newPage();
+    await configuredPage.setViewportSize({ width: 1280, height: 900 });
+    await configuredPage.goto(
+      "/w/acme/admin/bookings?theme=light&railWidth=64&navigationItemSpacing=8"
+    );
+    const configuredDrawer = configuredPage.getByTestId("jskit-shell-drawer");
+    await expect(configuredDrawer).toHaveAttribute("data-navigation-item-spacing", "8");
+    await assertDrawerFit(configuredPage);
+    await configuredPage.getByTestId("jskit-shell-nav-toggle").click();
+    await expect(configuredDrawer).toHaveAttribute("data-presentation", "rail");
+    await expect(configuredDrawer).toHaveAttribute("data-rail-width", "64");
+    await expect.poll(async () => {
+      const box = await configuredDrawer.boundingBox();
+      return box ? Math.abs(box.width - 64) : Number.POSITIVE_INFINITY;
+    }).toBeLessThanOrEqual(1);
+    await configuredPage.close();
     await context.close();
   } finally {
     await browser?.close();

package/test/drawerWidth.test.js

@@ -2,29 +2,32 @@ import assert from "node:assert/strict";
 import test from "node:test";
 import {
   DEFAULT_SHELL_DRAWER_WIDTH,
+  DEFAULT_SHELL_NAVIGATION_ITEM_SPACING,
   DEFAULT_SHELL_RAIL_WIDTH,
   normalizeShellDrawerWidth,
+  normalizeShellNavigationItemSpacing,
   normalizeShellRailWidth,
   resolveContentAwareDrawerWidth
 } from "../src/client/support/drawerWidth.js";
 
-test("content-aware drawer width includes the rendered label start, width, and 10px end gap", () => {
+test("content-aware drawer width includes the rendered label start, width, and balanced end spacing", () => {
   assert.equal(
     resolveContentAwareDrawerWidth([
       { logicalStart: 72, textWidth: 40 },
       { logicalStart: 72, textWidth: 78 }
     ]),
-    160
+    162
   );
   assert.equal(
     resolveContentAwareDrawerWidth([
       { logicalStart: 72, textWidth: 99.015625 }
     ]),
-    182
+    183.25
   );
 });
 
 test("drawer and rail widths have stable defaults and bounded overrides", () => {
+  assert.equal(DEFAULT_SHELL_RAIL_WIDTH, 80);
   assert.equal(normalizeShellDrawerWidth(null), DEFAULT_SHELL_DRAWER_WIDTH);
   assert.equal(normalizeShellDrawerWidth(180), 180);
   assert.equal(normalizeShellDrawerWidth(1000), 360);
@@ -33,6 +36,14 @@ test("drawer and rail widths have stable defaults and bounded overrides", () =>
   assert.equal(normalizeShellRailWidth(20), 48);
 });
 
+test("navigation item spacing has a Material-aligned default and bounded overrides", () => {
+  assert.equal(DEFAULT_SHELL_NAVIGATION_ITEM_SPACING, 12);
+  assert.equal(normalizeShellNavigationItemSpacing(null), DEFAULT_SHELL_NAVIGATION_ITEM_SPACING);
+  assert.equal(normalizeShellNavigationItemSpacing(14), 14);
+  assert.equal(normalizeShellNavigationItemSpacing(2), 8);
+  assert.equal(normalizeShellNavigationItemSpacing(100), 24);
+});
+
 test("content-aware width ignores invalid measurements and uses a bounded fallback", () => {
   assert.equal(
     resolveContentAwareDrawerWidth([

package/test/playwrightContract.test.js

@@ -29,13 +29,15 @@ test("adaptive shell smoke follows rendered layout state and waits for drawer tr
   const source = await readFile(path.join(PACKAGE_ROOT, "src/test/adaptiveShellSmoke.js"), "utf8");
 
   assert.match(source, /data-layout/u);
+  assert.match(source, /data-navigation-item-spacing/u);
   assert.match(source, /data-rail-width/u);
   assert.match(source, /expect\.poll/u);
   assert.match(source, /toBeFocused/u);
   assert.match(source, /v-navigation-drawer__scrim/u);
   assert.match(source, /page\.keyboard\.press\("Escape"\)[\s\S]*data-presentation", "drawer"/u);
   assert.match(source, /iconBox\.x \+ iconBox\.width \/ 2/u);
-  assert.match(source, /endGap\)\.toBeGreaterThanOrEqual\(9\)/u);
+  assert.match(source, /fit\.endGap - configuredSpacing/u);
+  assert.match(source, /fit\.iconLabelGaps/u);
   assert.doesNotMatch(source, /viewport\.name === "compact"/u);
   assert.doesNotMatch(source, /await new Promise.*setTimeout|waitForTimeout/u);
 });

package/test/settingsPlacementContract.test.js

@@ -100,13 +100,16 @@ test("shell-web shell layout registers navigation at the app layout level", asyn
   assert.match(source, /:rail="drawerPresentation\.rail"/);
   assert.match(source, /drawerWidth/);
   assert.match(source, /railWidth/);
+  assert.match(source, /navigationItemSpacing/);
   assert.match(source, /:width="resolvedDrawerWidth"/);
   assert.match(source, /:rail-width="resolvedRailWidth"/);
   assert.match(source, /data-drawer-width="resolvedDrawerWidth"/);
+  assert.match(source, /data-navigation-item-spacing="resolvedNavigationItemSpacing"/);
   assert.match(source, /data-rail-width="resolvedRailWidth"/);
   assert.match(source, /data-layout="layoutClass"/);
   assert.match(source, /measureDrawerContentWidth/);
-  assert.match(source, /SHELL_DRAWER_LABEL_END_GAP/);
+  assert.match(source, /DEFAULT_SHELL_NAVIGATION_ITEM_SPACING/);
+  assert.match(source, /:prepend-gap="resolvedNavigationItemSpacing"/);
   assert.doesNotMatch(source, /:width="248"/);
   assert.doesNotMatch(source, /:rail-width="80"/);
   assert.match(source, /:model-value="drawerPresentation\.visible"/);
@@ -117,7 +120,7 @@ test("shell-web shell layout registers navigation at the app layout level", asyn
   const template = await readFile(path.join(PACKAGE_DIR, "templates", "src", "components", "ShellLayout.vue"), "utf8");
 
   assert.match(template, /PackageShellLayout from "@jskit-ai\/shell-web\/client\/components\/ShellLayout"/);
-  assert.match(template, /drawerWidth, railWidth, and future shell props package-owned/);
+  assert.match(template, /drawerWidth, railWidth, navigationItemSpacing, and future shell props package-owned/);
   assert.match(template, /h\(PackageShellLayout, attrs, slots\)/);
   assert.doesNotMatch(template, /ShellOutlet|ShellRouteTransition|useShellLayoutState|pointerdown|v-navigation-drawer|v-bottom-navigation/);
 });