@jskit-ai/shell-web 0.1.149 → 0.1.151

package/src/test/adaptiveShellSmoke.js

@@ -1,7 +1,7 @@
 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: "medium", width: 1024, height: 1024 }),
   Object.freeze({ name: "expanded", width: 1280, height: 900 })
 ]);
 
@@ -68,6 +68,165 @@ async function isElementVisibleInViewport(page, testId) {
   });
 }
 
+async function expectElementVisibility(page, expect, testId, visible) {
+  await expect.poll(
+    () => isElementVisibleInViewport(page, testId),
+    { message: `${testId} did not reach its expected visibility.` }
+  ).toBe(visible);
+}
+
+async function readShellLayoutClass(drawer) {
+  const layoutClass = String(await drawer.getAttribute("data-layout") || "");
+  if (!["compact", "medium", "expanded"].includes(layoutClass)) {
+    throw new Error(`Shell drawer exposed an invalid data-layout value: ${layoutClass || "(empty)"}.`);
+  }
+  return layoutClass;
+}
+
+async function readConfiguredWidth(drawer, attribute) {
+  const width = Number(await drawer.getAttribute(attribute));
+  if (!Number.isFinite(width) || width <= 0) {
+    throw new Error(`Shell drawer exposed an invalid ${attribute} value.`);
+  }
+  return width;
+}
+
+async function expectDrawerWidth(drawer, expect, expectedWidth) {
+  await expect.poll(async () => {
+    const box = await drawer.boundingBox();
+    return box ? Math.abs(box.width - expectedWidth) : Number.POSITIVE_INFINITY;
+  }, {
+    message: `Shell drawer did not settle at ${expectedWidth}px.`
+  }).toBeLessThanOrEqual(1);
+}
+
+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();
+    const drawerStyle = window.getComputedStyle(element);
+    const rightToLeft = drawerStyle.direction === "rtl";
+    const endBorderWidth = Number.parseFloat(
+      rightToLeft ? drawerStyle.borderLeftWidth : drawerStyle.borderRightWidth
+    ) || 0;
+    const innerEnd = rightToLeft
+      ? drawerRect.left + endBorderWidth
+      : drawerRect.right - endBorderWidth;
+    const labels = Array.from(element.querySelectorAll(".v-list-item-title"))
+      .filter((label) => {
+        const style = window.getComputedStyle(label);
+        return style.display !== "none" && style.visibility !== "hidden";
+      })
+      .map((label) => {
+        const range = document.createRange();
+        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 ||
+            label.scrollHeight > label.clientHeight ||
+            (rightToLeft
+              ? 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
+        };
+      })
+      .filter((label) => label.width > 0);
+
+    if (labels.length === 0) {
+      return null;
+    }
+    const furthestLabel = labels.reduce((furthest, label) => {
+      if (!furthest) {
+        return label;
+      }
+      return rightToLeft
+        ? label.logicalEnd < furthest.logicalEnd ? label : furthest
+        : label.logicalEnd > furthest.logicalEnd ? label : furthest;
+    }, null);
+    return {
+      clipped: labels.some((label) => label.clipped),
+      endGap: rightToLeft
+        ? furthestLabel.logicalEnd - innerEnd
+        : innerEnd - furthestLabel.logicalEnd,
+      iconLabelGaps: labels
+        .map((label) => label.iconLabelGap)
+        .filter((gap) => Number.isFinite(gap))
+    };
+  });
+
+  expect(fit).not.toBeNull();
+  expect(fit.clipped).toBe(false);
+  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) {
+  const links = drawer.locator("a.shell-menu-link-item[href]");
+  await expect(links.first()).toBeVisible();
+  const firstLink = links.first();
+  const firstIcon = firstLink.locator(".v-icon").first();
+  const geometry = await Promise.all([drawer.boundingBox(), firstLink.boundingBox(), firstIcon.boundingBox()]);
+  const [drawerBox, linkBox, iconBox] = geometry;
+
+  expect(drawerBox).not.toBeNull();
+  expect(linkBox).not.toBeNull();
+  expect(iconBox).not.toBeNull();
+  expect(linkBox.width).toBeGreaterThanOrEqual(48);
+  expect(linkBox.height).toBeGreaterThanOrEqual(48);
+  expect(Math.abs(
+    iconBox.x + iconBox.width / 2 - (drawerBox.x + drawerBox.width / 2)
+  )).toBeLessThanOrEqual(1);
+
+  const currentUrl = new URL(page.url());
+  const linkCount = await links.count();
+  let navigationLink = null;
+  let targetUrl = null;
+  for (let index = 0; index < linkCount; index += 1) {
+    const candidate = links.nth(index);
+    const href = await candidate.getAttribute("href");
+    if (!href) {
+      continue;
+    }
+    const resolved = new URL(href, currentUrl);
+    if (resolved.pathname !== currentUrl.pathname || resolved.search !== currentUrl.search) {
+      navigationLink = candidate;
+      targetUrl = resolved;
+      break;
+    }
+  }
+
+  expect(navigationLink).not.toBeNull();
+  await navigationLink.locator(".v-icon").first().click();
+  await expect.poll(() => {
+    const actual = new URL(page.url());
+    return `${actual.pathname}${actual.search}`;
+  }).toBe(`${targetUrl.pathname}${targetUrl.search}`);
+}
+
+async function openCompactDrawer(page, expect) {
+  const drawer = page.getByTestId("jskit-shell-drawer");
+  await page.getByTestId("jskit-shell-nav-toggle").click();
+  await expect(drawer).toHaveAttribute("data-presentation", "modal");
+  await expectElementVisibility(page, expect, "jskit-shell-drawer", true);
+}
+
 async function runAdaptiveShellSmokeCase({
   page,
   expect,
@@ -83,8 +242,11 @@ async function runAdaptiveShellSmokeCase({
   await expect(page.locator("body")).toBeVisible();
   await expectGeneratedScreenContract(page, expect);
   await expectNoHorizontalOverflow(page, expect);
+  const drawer = page.getByTestId("jskit-shell-drawer");
+  const toggle = page.getByTestId("jskit-shell-nav-toggle");
+  const layoutClass = await readShellLayoutClass(drawer);
 
-  if (viewport.name === "compact") {
+  if (layoutClass === "compact") {
     let bootstrapRequests = 0;
     await page.route("**/api/bootstrap**", async (route) => {
       bootstrapRequests += 1;
@@ -93,12 +255,20 @@ async function runAdaptiveShellSmokeCase({
     const bootstrapRequestsBeforePull = bootstrapRequests;
 
     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 expectElementVisibility(page, expect, "jskit-shell-drawer", false);
+
+    await openCompactDrawer(page, expect);
+    await toggle.click();
+    await expectElementVisibility(page, expect, "jskit-shell-drawer", false);
+
+    await openCompactDrawer(page, expect);
+    await page.locator(".v-navigation-drawer__scrim").click();
+    await expectElementVisibility(page, expect, "jskit-shell-drawer", false);
+
+    await openCompactDrawer(page, expect);
     await page.keyboard.press("Escape");
-    expect(await isElementVisibleInViewport(page, "jskit-shell-drawer")).toBe(false);
+    await expectElementVisibility(page, expect, "jskit-shell-drawer", false);
+    await expect(toggle).toBeFocused();
 
     const navButtonHeights = await page.getByTestId("jskit-shell-bottom-nav").locator(".v-btn").evaluateAll((buttons) =>
       buttons.map((button) => button.getBoundingClientRect().height)
@@ -111,15 +281,21 @@ async function runAdaptiveShellSmokeCase({
     await pullToRefresh(page, expect);
     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);
+    await expect(drawer).toBeVisible();
+    if (await drawer.getAttribute("data-presentation") === "rail") {
+      await toggle.click();
+    }
+    await expect(drawer).toHaveAttribute("data-presentation", "drawer");
+    await expectDrawerWidth(drawer, expect, await readConfiguredWidth(drawer, "data-drawer-width"));
+    await expectContentAwareDrawerFit(drawer, expect);
+    await page.keyboard.press("Escape");
+    await expect(drawer).toHaveAttribute("data-presentation", "drawer");
+
+    await toggle.click();
+    await expect(drawer).toHaveAttribute("data-presentation", "rail");
+    await expectDrawerWidth(drawer, expect, await readConfiguredWidth(drawer, "data-rail-width"));
+    await expectCentredRailNavigation(page, drawer, expect);
+    await expectNoHorizontalOverflow(page, expect);
   }
 }
 

package/templates/src/components/ShellLayout.vue

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

package/test/adaptiveShell.browser.test.js

@@ -0,0 +1,324 @@
+import assert from "node:assert/strict";
+import { spawn } from "node:child_process";
+import net from "node:net";
+import path from "node:path";
+import process from "node:process";
+import test from "node:test";
+import { fileURLToPath } from "node:url";
+import { chromium, expect } from "@playwright/test";
+import {
+  DEFAULT_VIEWPORTS,
+  runAdaptiveShellSmokeCase
+} from "../src/test/adaptiveShellSmoke.js";
+
+const TEST_DIRECTORY = path.dirname(fileURLToPath(import.meta.url));
+const REPOSITORY_ROOT = path.resolve(TEST_DIRECTORY, "../../..");
+const FIXTURE_ROOT = path.resolve(TEST_DIRECTORY, "../fixtures/adaptive-shell");
+const VITE_CLI = path.join(REPOSITORY_ROOT, "node_modules", "vite", "bin", "vite.js");
+const RUN_BROWSER_TEST = process.env.JSKIT_SHELL_WEB_BROWSER_INTEGRATION === "1";
+
+function startVite(port) {
+  const child = spawn(process.execPath, [
+    VITE_CLI,
+    "--config",
+    path.join(FIXTURE_ROOT, "vite.config.mjs"),
+    "--port",
+    String(port),
+    "--clearScreen",
+    "false"
+  ], {
+    cwd: FIXTURE_ROOT,
+    stdio: ["ignore", "pipe", "pipe"],
+    env: {
+      ...process.env,
+      NO_COLOR: "1",
+      FORCE_COLOR: "0"
+    }
+  });
+  let output = "";
+  child.stdout.on("data", collectOutput);
+  child.stderr.on("data", collectOutput);
+
+  function collectOutput(chunk) {
+    output += chunk.toString("utf8");
+  }
+
+  async function waitUntilReady() {
+    await new Promise((resolve, reject) => {
+      const startedAt = Date.now();
+      const timer = setInterval(checkReadiness, 50);
+
+      function checkReadiness() {
+        if (new RegExp(`http://127\\.0\\.0\\.1:${port}/`, "u").test(output)) {
+          clearInterval(timer);
+          resolve();
+          return;
+        }
+        if (child.exitCode !== null) {
+          clearInterval(timer);
+          reject(new Error(`Vite exited before becoming ready.\n${output}`));
+          return;
+        }
+        if (Date.now() - startedAt >= 30_000) {
+          clearInterval(timer);
+          reject(new Error(`Timed out waiting for Vite.\n${output}`));
+        }
+      }
+    });
+  }
+
+  return Object.freeze({ child, waitUntilReady });
+}
+
+async function stopVite(runtime) {
+  const child = runtime?.child;
+  if (!child || child.exitCode !== null || child.signalCode !== null) {
+    return;
+  }
+  await new Promise((resolve) => {
+    const forceTimer = setTimeout(forceStop, 5_000);
+    child.once("exit", finishStop);
+    child.kill("SIGTERM");
+
+    function forceStop() {
+      child.kill("SIGKILL");
+    }
+
+    function finishStop() {
+      clearTimeout(forceTimer);
+      resolve();
+    }
+  });
+}
+
+async function reservePort() {
+  const server = net.createServer();
+  await new Promise((resolve, reject) => {
+    server.once("error", reject);
+    server.listen(0, "127.0.0.1", resolve);
+  });
+  const address = server.address();
+  assert.ok(address && typeof address === "object");
+  await new Promise((resolve, reject) => {
+    server.close((error) => error ? reject(error) : resolve());
+  });
+  return address.port;
+}
+
+function parseRgb(color) {
+  const channels = String(color || "").match(/[\d.]+/gu)?.map(Number) || [];
+  return {
+    red: channels[0] || 0,
+    green: channels[1] || 0,
+    blue: channels[2] || 0,
+    alpha: channels.length > 3 ? channels[3] : 1
+  };
+}
+
+function relativeLuminance(color) {
+  const channels = [color.red, color.green, color.blue].map(normalizeChannel);
+  return channels[0] * 0.2126 + channels[1] * 0.7152 + channels[2] * 0.0722;
+}
+
+function normalizeChannel(channel) {
+  const normalized = channel / 255;
+  return normalized <= 0.03928
+    ? normalized / 12.92
+    : ((normalized + 0.055) / 1.055) ** 2.4;
+}
+
+function contrastRatio(foreground, background) {
+  const foregroundLuminance = relativeLuminance(foreground);
+  const backgroundLuminance = relativeLuminance(background);
+  const lighter = Math.max(foregroundLuminance, backgroundLuminance);
+  const darker = Math.min(foregroundLuminance, backgroundLuminance);
+  return (lighter + 0.05) / (darker + 0.05);
+}
+
+async function assertTooltipContrast(page, linkName, interaction) {
+  const link = page.getByRole("link", { name: linkName, exact: true });
+  if (interaction === "focus") {
+    await link.focus();
+  } else {
+    await link.hover();
+  }
+  const tooltip = page.locator(".shell-navigation-tooltip").filter({ hasText: linkName }).last();
+  await expect(tooltip).toBeVisible();
+  const colors = await tooltip.evaluate((element) => {
+    const style = window.getComputedStyle(element);
+    return {
+      background: style.backgroundColor,
+      color: style.color,
+      opacity: Number(style.opacity)
+    };
+  });
+  const background = parseRgb(colors.background);
+  const foreground = parseRgb(colors.color);
+  assert.equal(colors.opacity, 1);
+  assert.equal(background.alpha, 1);
+  assert.ok(
+    contrastRatio(foreground, background) >= 4.5,
+    `${linkName} tooltip contrast was ${contrastRatio(foreground, background).toFixed(2)}:1.`
+  );
+  await page.keyboard.press("Escape");
+}
+
+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();
+    return box ? Math.abs(box.width - configured) : Number.POSITIVE_INFINITY;
+  }).toBeLessThanOrEqual(1);
+  const result = await drawer.evaluate((element) => {
+    const drawerRect = element.getBoundingClientRect();
+    const border = Number.parseFloat(window.getComputedStyle(element).borderRightWidth) || 0;
+    const innerEnd = drawerRect.right - border;
+    const labels = Array.from(element.querySelectorAll(".v-list-item-title")).map((label) => {
+      const range = document.createRange();
+      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,
+        iconLabelGap: iconRect ? rect.left - iconRect.right : null
+      };
+    });
+    const furthestEnd = Math.max(...labels.map((label) => label.rect.right));
+    return {
+      clipped: labels.some((label) => (
+        label.scrollWidth > label.clientWidth ||
+        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(
+    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.`);
+}
+
+async function assertRailKeyboardAndSelection(page) {
+  const drawer = page.getByTestId("jskit-shell-drawer");
+  await page.getByTestId("jskit-shell-nav-toggle").click();
+  await expect(drawer).toHaveAttribute("data-presentation", "rail");
+  const configuredRailWidth = Number(await drawer.getAttribute("data-rail-width"));
+  await expect.poll(async () => {
+    const box = await drawer.boundingBox();
+    return box ? Math.abs(box.width - configuredRailWidth) : Number.POSITIVE_INFINITY;
+  }).toBeLessThanOrEqual(1);
+
+  const activeLink = page.getByRole("link", { name: "Bookings", exact: true });
+  const activeBackground = await activeLink.locator(".v-list-item__overlay").evaluate(
+    (element) => window.getComputedStyle(element).backgroundColor
+  );
+  assert.notEqual(activeBackground, "rgba(0, 0, 0, 0)");
+
+  const contacts = page.getByRole("link", { name: "Contacts", exact: true });
+  await contacts.focus();
+  await contacts.press("Enter");
+  await expect(page).toHaveURL(/\/contacts(?:\?|$)/u);
+
+  const assistant = page.getByRole("link", { name: "Assistant", exact: true });
+  await assistant.focus();
+  const scrollBeforeSpace = await page.evaluate(() => window.scrollY);
+  await assistant.press("Space");
+  await expect(page).toHaveURL(/\/assistant(?:\?|$)/u);
+  assert.equal(await page.evaluate(() => window.scrollY), scrollBeforeSpace);
+}
+
+test("shell-web adaptive navigation passes package-owned browser contracts", {
+  skip: RUN_BROWSER_TEST
+    ? false
+    : "set JSKIT_SHELL_WEB_BROWSER_INTEGRATION=1 to run shell-web browser integration",
+  timeout: 180_000
+}, async () => {
+  const port = await reservePort();
+  const vite = startVite(port);
+  let browser = null;
+
+  try {
+    await vite.waitUntilReady();
+    const executablePath = String(process.env.PLAYWRIGHT_CHROMIUM_EXECUTABLE_PATH || "").trim();
+    browser = await chromium.launch({
+      headless: true,
+      ...(executablePath ? { executablePath } : {})
+    });
+    const context = await browser.newContext({
+      baseURL: `http://127.0.0.1:${port}`,
+      locale: "en-US"
+    });
+
+    for (const viewport of DEFAULT_VIEWPORTS) {
+      const page = await context.newPage();
+      await runAdaptiveShellSmokeCase({ page, expect, viewport });
+      await page.close();
+    }
+
+    for (const pathAndTheme of [
+      "/home?theme=light",
+      "/home?theme=dark",
+      "/w/acme/admin/bookings?theme=light",
+      "/w/acme/admin/bookings?theme=dark"
+    ]) {
+      const page = await context.newPage();
+      await page.setViewportSize({ width: 1280, height: 900 });
+      await page.goto(pathAndTheme);
+      await expect(page.getByTestId("jskit-shell-drawer")).toBeVisible();
+      await assertDrawerFit(page);
+      await assertTooltipContrast(page, "Bookings", "focus");
+      await assertTooltipContrast(page, "Help and support", "hover");
+      await page.close();
+    }
+
+    const railPage = await context.newPage();
+    await railPage.setViewportSize({ width: 1280, height: 900 });
+    await railPage.goto("/w/acme/admin/bookings?theme=light");
+    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();
+    await stopVite(vite);
+  }
+});

package/test/drawerWidth.test.js

@@ -0,0 +1,59 @@
+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 balanced end spacing", () => {
+  assert.equal(
+    resolveContentAwareDrawerWidth([
+      { logicalStart: 72, textWidth: 40 },
+      { logicalStart: 72, textWidth: 78 }
+    ]),
+    162
+  );
+  assert.equal(
+    resolveContentAwareDrawerWidth([
+      { logicalStart: 72, textWidth: 99.015625 }
+    ]),
+    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);
+  assert.equal(normalizeShellRailWidth(null), DEFAULT_SHELL_RAIL_WIDTH);
+  assert.equal(normalizeShellRailWidth(96), 96);
+  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([
+      { logicalStart: -1, textWidth: 20 },
+      { logicalStart: 40, textWidth: Number.NaN }
+    ]),
+    DEFAULT_SHELL_DRAWER_WIDTH
+  );
+  assert.equal(
+    resolveContentAwareDrawerWidth([{ logicalStart: 72, textWidth: 900 }]),
+    360
+  );
+});

package/test/linkItemScaffoldContract.test.js

@@ -152,13 +152,17 @@ 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, /ShellNavigationTooltip/);
+  assert.match(shellMenuSource, /@keydown\.space="activateShellNavigationLinkOnSpace"/);
+  assert.doesNotMatch(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, /ShellNavigationTooltip/);
+  assert.match(shellSurfaceAwareSource, /@keydown\.space="activateShellNavigationLinkOnSpace"/);
+  assert.doesNotMatch(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*\{/);
@@ -167,6 +171,18 @@ test("shell-web generic link items support the expected shared route and icon be
   assert.match(shellTabSource, /stacked/);
   assert.match(shellTabSource, /min-height:\s*48px/);
   assert.match(shellTabSource, /<v-icon v-if="resolvedIcon" :icon="resolvedIcon" \/>/);
+
+  const tooltipSource = await readFile(
+    path.join(PACKAGE_DIR, "src", "client", "components", "ShellNavigationTooltip.vue"),
+    "utf8"
+  );
+  assert.match(tooltipSource, /:theme="theme\.name\.value"/);
+  assert.match(tooltipSource, /location="end"/);
+  assert.match(tooltipSource, /:open-on-focus="true"/);
+  assert.match(tooltipSource, /:open-on-hover="true"/);
+  assert.match(tooltipSource, /--v-theme-inverse-surface, var\(--v-theme-on-surface\)/);
+  assert.match(tooltipSource, /--v-theme-inverse-on-surface, var\(--v-theme-surface\)/);
+  assert.match(tooltipSource, /opacity:\s*1\s*!important/);
 });
 
 test("shell-web binds the local link-item wrapper tokens into MainClientProvider", () => {