@jskit-ai/shell-web 0.1.149 → 0.1.150

package/src/client/components/ShellMenuLinkItem.vue

@@ -5,6 +5,8 @@ import {
   useWebPlacementContext
 } from "../placement/index.js";
 import { resolveMenuLinkIcon } from "../lib/menuIcons.js";
+import { activateShellNavigationLinkOnSpace } from "../support/navigationLinkKeyboard.js";
+import ShellNavigationTooltip from "./ShellNavigationTooltip.vue";
 
 const props = defineProps({
   label: {
@@ -59,18 +61,22 @@ const resolvedIcon = computed(() =>
 </script>
 
 <template>
-  <v-list-item
-    v-if="resolvedTarget.href"
-    class="shell-menu-link-item"
-    :title="props.label"
-    :to="resolvedTarget.sameOrigin ? resolvedTarget.href : undefined"
-    :href="resolvedTarget.sameOrigin ? undefined : resolvedTarget.href"
-    :prepend-icon="resolvedIcon || undefined"
-    :disabled="props.disabled"
-    :exact="props.exact"
-    :aria-label="props.label"
-    v-tooltip="props.label"
-  />
+  <ShellNavigationTooltip v-if="resolvedTarget.href" :label="props.label">
+    <template #default="{ activatorProps }">
+      <v-list-item
+        v-bind="activatorProps"
+        class="shell-menu-link-item"
+        :title="props.label"
+        :to="resolvedTarget.sameOrigin ? resolvedTarget.href : undefined"
+        :href="resolvedTarget.sameOrigin ? undefined : resolvedTarget.href"
+        :prepend-icon="resolvedIcon || undefined"
+        :disabled="props.disabled"
+        :exact="props.exact"
+        :aria-label="props.label"
+        @keydown.space="activateShellNavigationLinkOnSpace"
+      />
+    </template>
+  </ShellNavigationTooltip>
 </template>
 
 <style scoped>

package/src/client/components/ShellNavigationTooltip.vue

@@ -0,0 +1,37 @@
+<script setup>
+import { useTheme } from "vuetify";
+
+const props = defineProps({
+  label: {
+    type: String,
+    default: ""
+  }
+});
+
+const theme = useTheme();
+</script>
+
+<template>
+  <v-tooltip
+    :text="props.label"
+    :theme="theme.name.value"
+    location="end"
+    content-class="shell-navigation-tooltip"
+    :open-on-focus="true"
+    :open-on-hover="true"
+  >
+    <template #activator="{ props: activatorProps }">
+      <slot :activator-props="activatorProps" />
+    </template>
+  </v-tooltip>
+</template>
+
+<style>
+.shell-navigation-tooltip {
+  background-color:
+    rgb(var(--v-theme-inverse-surface, var(--v-theme-on-surface))) !important;
+  color:
+    rgb(var(--v-theme-inverse-on-surface, var(--v-theme-surface))) !important;
+  opacity: 1 !important;
+}
+</style>

package/src/client/components/ShellSurfaceAwareMenuLinkItem.vue

@@ -9,6 +9,8 @@ import {
 } from "../placement/index.js";
 import { resolveMenuLinkIcon } from "../lib/menuIcons.js";
 import { resolveMenuLinkTarget } from "../support/menuLinkTarget.js";
+import { activateShellNavigationLinkOnSpace } from "../support/navigationLinkKeyboard.js";
+import ShellNavigationTooltip from "./ShellNavigationTooltip.vue";
 
 const props = defineProps({
   label: {
@@ -104,18 +106,22 @@ const resolvedIcon = computed(() =>
 </script>
 
 <template>
-  <v-list-item
-    v-if="resolvedTarget.href"
-    class="shell-menu-link-item"
-    :title="props.label"
-    :to="resolvedTarget.sameOrigin ? resolvedTarget.href : undefined"
-    :href="resolvedTarget.sameOrigin ? undefined : resolvedTarget.href"
-    :prepend-icon="resolvedIcon || undefined"
-    :disabled="props.disabled"
-    :exact="props.exact"
-    :aria-label="props.label"
-    v-tooltip="props.label"
-  />
+  <ShellNavigationTooltip v-if="resolvedTarget.href" :label="props.label">
+    <template #default="{ activatorProps }">
+      <v-list-item
+        v-bind="activatorProps"
+        class="shell-menu-link-item"
+        :title="props.label"
+        :to="resolvedTarget.sameOrigin ? resolvedTarget.href : undefined"
+        :href="resolvedTarget.sameOrigin ? undefined : resolvedTarget.href"
+        :prepend-icon="resolvedIcon || undefined"
+        :disabled="props.disabled"
+        :exact="props.exact"
+        :aria-label="props.label"
+        @keydown.space="activateShellNavigationLinkOnSpace"
+      />
+    </template>
+  </ShellNavigationTooltip>
 </template>
 
 <style scoped>

package/src/client/support/drawerWidth.js

@@ -0,0 +1,74 @@
+const DEFAULT_SHELL_DRAWER_WIDTH = 248;
+const DEFAULT_SHELL_RAIL_WIDTH = 80;
+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;
+
+function clampNumber(value, minimum, maximum) {
+  return Math.min(maximum, Math.max(minimum, value));
+}
+
+function normalizeShellDrawerWidth(value, fallback = DEFAULT_SHELL_DRAWER_WIDTH) {
+  const parsed = Number(value);
+  if (!Number.isFinite(parsed) || parsed <= 0) {
+    return fallback;
+  }
+  return clampNumber(
+    parsed,
+    MINIMUM_SHELL_DRAWER_WIDTH,
+    MAXIMUM_SHELL_DRAWER_WIDTH
+  );
+}
+
+function normalizeShellRailWidth(value, fallback = DEFAULT_SHELL_RAIL_WIDTH) {
+  const parsed = Number(value);
+  if (!Number.isFinite(parsed) || parsed <= 0) {
+    return fallback;
+  }
+  return clampNumber(
+    Math.round(parsed),
+    MINIMUM_SHELL_RAIL_WIDTH,
+    MAXIMUM_SHELL_RAIL_WIDTH
+  );
+}
+
+function resolveContentAwareDrawerWidth(
+  measurements = [],
+  {
+    endGap = SHELL_DRAWER_LABEL_END_GAP,
+    minimum = MINIMUM_SHELL_DRAWER_WIDTH,
+    maximum = MAXIMUM_SHELL_DRAWER_WIDTH,
+    fallback = DEFAULT_SHELL_DRAWER_WIDTH
+  } = {}
+) {
+  let requiredWidth = 0;
+  for (const measurement of measurements) {
+    const logicalStart = Number(measurement?.logicalStart);
+    const textWidth = Number(measurement?.textWidth);
+    if (!Number.isFinite(logicalStart) || logicalStart < 0 || !Number.isFinite(textWidth) || textWidth <= 0) {
+      continue;
+    }
+    requiredWidth = Math.max(requiredWidth, logicalStart + textWidth + Number(endGap || 0));
+  }
+
+  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);
+}
+
+export {
+  DEFAULT_SHELL_DRAWER_WIDTH,
+  DEFAULT_SHELL_RAIL_WIDTH,
+  MAXIMUM_SHELL_DRAWER_WIDTH,
+  MINIMUM_SHELL_DRAWER_WIDTH,
+  SHELL_DRAWER_LABEL_END_GAP,
+  normalizeShellDrawerWidth,
+  normalizeShellRailWidth,
+  resolveContentAwareDrawerWidth
+};

package/src/client/support/navigationLinkKeyboard.js

@@ -0,0 +1,10 @@
+function activateShellNavigationLinkOnSpace(event) {
+  if (event?.key !== " " || typeof event.currentTarget?.click !== "function") {
+    return;
+  }
+  event.preventDefault();
+  event.stopPropagation();
+  event.currentTarget.click();
+}
+
+export { activateShellNavigationLinkOnSpace };

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,152 @@ 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 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?.();
+        return {
+          clipped: (
+            label.scrollWidth > label.clientWidth ||
+            label.scrollHeight > label.clientHeight ||
+            (rightToLeft
+              ? textRect.left < innerEnd - 1
+              : textRect.right > innerEnd + 1)
+          ),
+          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
+    };
+  });
+
+  expect(fit).not.toBeNull();
+  expect(fit.clipped).toBe(false);
+  expect(fit.endGap).toBeGreaterThanOrEqual(9);
+  expect(fit.endGap).toBeLessThanOrEqual(11);
+}
+
+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 +229,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 +242,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 +268,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, and future shell props package-owned.
     return () => h(PackageShellLayout, attrs, slots);
   }
 };