@jskit-ai/shell-web 0.1.149 → 0.1.150

package/test/adaptiveShell.browser.test.js

@@ -0,0 +1,290 @@
+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");
+  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?.();
+      return {
+        clientHeight: label.clientHeight,
+        clientWidth: label.clientWidth,
+        rect,
+        scrollHeight: label.scrollHeight,
+        scrollWidth: label.scrollWidth
+      };
+    });
+    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,
+      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(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();
+    await context.close();
+  } finally {
+    await browser?.close();
+    await stopVite(vite);
+  }
+});

package/test/drawerWidth.test.js

@@ -0,0 +1,48 @@
+import assert from "node:assert/strict";
+import test from "node:test";
+import {
+  DEFAULT_SHELL_DRAWER_WIDTH,
+  DEFAULT_SHELL_RAIL_WIDTH,
+  normalizeShellDrawerWidth,
+  normalizeShellRailWidth,
+  resolveContentAwareDrawerWidth
+} from "../src/client/support/drawerWidth.js";
+
+test("content-aware drawer width includes the rendered label start, width, and 10px end gap", () => {
+  assert.equal(
+    resolveContentAwareDrawerWidth([
+      { logicalStart: 72, textWidth: 40 },
+      { logicalStart: 72, textWidth: 78 }
+    ]),
+    160
+  );
+  assert.equal(
+    resolveContentAwareDrawerWidth([
+      { logicalStart: 72, textWidth: 99.015625 }
+    ]),
+    182
+  );
+});
+
+test("drawer and rail widths have stable defaults and bounded overrides", () => {
+  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("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", () => {

package/test/navigationLinkKeyboard.test.js

@@ -0,0 +1,36 @@
+import assert from "node:assert/strict";
+import test from "node:test";
+import { activateShellNavigationLinkOnSpace } from "../src/client/support/navigationLinkKeyboard.js";
+
+test("Space activates a shell navigation link once and suppresses page scrolling", () => {
+  const calls = [];
+  activateShellNavigationLinkOnSpace({
+    key: " ",
+    currentTarget: {
+      click() {
+        calls.push("click");
+      }
+    },
+    preventDefault() {
+      calls.push("preventDefault");
+    },
+    stopPropagation() {
+      calls.push("stopPropagation");
+    }
+  });
+
+  assert.deepEqual(calls, ["preventDefault", "stopPropagation", "click"]);
+});
+
+test("other keys retain native link behavior", () => {
+  let clicked = false;
+  activateShellNavigationLinkOnSpace({
+    key: "Enter",
+    currentTarget: {
+      click() {
+        clicked = true;
+      }
+    }
+  });
+  assert.equal(clicked, false);
+});

package/test/playwrightContract.test.js

@@ -24,3 +24,18 @@ test("adaptive shell smoke navigates through Playwright baseURL", async () => {
   assert.doesNotMatch(source, /PLAYWRIGHT_BASE_URL/u);
   assert.doesNotMatch(source, /http:\/\/127\.0\.0\.1/u);
 });
+
+test("adaptive shell smoke follows rendered layout state and waits for drawer transitions", async () => {
+  const source = await readFile(path.join(PACKAGE_ROOT, "src/test/adaptiveShellSmoke.js"), "utf8");
+
+  assert.match(source, /data-layout/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.doesNotMatch(source, /viewport\.name === "compact"/u);
+  assert.doesNotMatch(source, /await new Promise.*setTimeout|waitForTimeout/u);
+});

package/test/settingsPlacementContract.test.js

@@ -98,7 +98,17 @@ test("shell-web shell layout registers navigation at the app layout level", asyn
   assert.match(source, /desktopDrawerClosedMode/);
   assert.match(source, /default: "rail"/);
   assert.match(source, /:rail="drawerPresentation\.rail"/);
-  assert.match(source, /:rail-width="80"/);
+  assert.match(source, /drawerWidth/);
+  assert.match(source, /railWidth/);
+  assert.match(source, /:width="resolvedDrawerWidth"/);
+  assert.match(source, /:rail-width="resolvedRailWidth"/);
+  assert.match(source, /data-drawer-width="resolvedDrawerWidth"/);
+  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.doesNotMatch(source, /:width="248"/);
+  assert.doesNotMatch(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"/);
@@ -107,6 +117,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, /h\(PackageShellLayout, attrs, slots\)/);
   assert.doesNotMatch(template, /ShellOutlet|ShellRouteTransition|useShellLayoutState|pointerdown|v-navigation-drawer|v-bottom-navigation/);
 });
@@ -154,7 +165,7 @@ test("shell-web installs generated adaptive shell Playwright smoke coverage", as
   assert.match(source, /@jskit-ai\/shell-web\/test\/adaptiveShellSmoke/);
   assert.match(helperSource, /generated adaptive shell smoke/);
   assert.match(helperSource, /390/);
-  assert.match(helperSource, /768/);
+  assert.match(helperSource, /1024/);
   assert.match(helperSource, /1280/);
   assert.match(helperSource, /jskit-shell-bottom-nav/);
   assert.match(helperSource, /jskit-shell-drawer/);