srcdev-nuxt-components 9.3.0 → 9.3.2

package/app/components/{responsive-header → 03.organisms/responsive-header}/NavigationItems.vue

@@ -60,7 +60,6 @@
             v-model="panelOpenStates[`${String(groupKey)}-${localIndex}`]"
             name="overflow-navigation-group"
             :animation-duration="DETAILS_ANIMATION_DURATION"
-            icon-size="medium"
             :style-class-passthrough="['overflow-navigation-details']"
           >
             <template #summary>
@@ -107,7 +106,7 @@
 </template>
 
 <script setup lang="ts">
-import type { ResponsiveHeaderState, ResponsiveHeaderNavItem } from "../../types/components";
+import type { ResponsiveHeaderState, ResponsiveHeaderNavItem } from "../../../types/components";
 
 interface Props {
   mainNavigationState?: ResponsiveHeaderState;
@@ -259,10 +258,8 @@ watch(
                 }
                 + .expanding-panel-content {
                   border-bottom: 0.1rem solid var(--overflow-nav-link-border-color, #efefef75);
-                  .inner {
-                    .overflow-navigation-sub-nav-inner {
-                      margin-top: var(--overflow-nav-items-gap, 0px);
-                    }
+                  .overflow-navigation-sub-nav-inner {
+                    margin-top: var(--overflow-nav-items-gap, 0px);
                   }
                 }
               }
@@ -271,29 +268,25 @@ watch(
             .expanding-panel-content {
               border-bottom: 0.1rem solid transparent;
 
-              .inner {
+              .overflow-navigation-sub-nav-inner {
                 margin-top: 0;
-
-                .overflow-navigation-sub-nav-inner {
-                  margin-top: 0;
-                  position: relative;
-
-                  .overflow-navigation-sub-nav-list {
-                    display: flex;
-                    flex-direction: column;
-                    gap: 2px;
-
-                    .overflow-navigation-sub-nav-item {
-                      padding-block: var(--overflow-nav-items-padding-block, 0.8rem);
-                      padding-inline: var(--overflow-nav-padding-inline, 0.8rem);
-                      font-size: var(--overflow-nav-sub-item-font-size, inherit);
-                      color: var(--overflow-nav-sub-item-color, inherit);
-
-                      .overflow-navigation-sub-nav-link {
-                        display: block;
-                        text-decoration: none;
-                        color: inherit;
-                      }
+                position: relative;
+
+                .overflow-navigation-sub-nav-list {
+                  display: flex;
+                  flex-direction: column;
+                  gap: 2px;
+
+                  .overflow-navigation-sub-nav-item {
+                    padding-block: var(--overflow-nav-items-padding-block, 0.8rem);
+                    padding-inline: var(--overflow-nav-padding-inline, 0.8rem);
+                    font-size: var(--overflow-nav-sub-item-font-size, inherit);
+                    color: var(--overflow-nav-sub-item-color, inherit);
+
+                    .overflow-navigation-sub-nav-link {
+                      display: block;
+                      text-decoration: none;
+                      color: inherit;
                     }
                   }
                 }

package/app/components/{responsive-header → 03.organisms/responsive-header}/ResponsiveHeader.vue

@@ -63,7 +63,7 @@
 
               {{ link.childLinksTitle }}
             </summary>
-            <div class="main-navigation-sub-nav" role="menu">
+            <div class="main-navigation-sub-nav" role="menu" @mouseenter="handleSubNavHover">
               <ul class="main-navigation-sub-nav-list">
                 <li v-for="childLink in link.childLinks" :key="childLink.name" class="main-navigation-sub-nav-item">
                   <NuxtLink :to="childLink.path" class="main-navigation-sub-nav-link" role="menuitem">
@@ -114,7 +114,7 @@ import type {
   ResponsiveHeaderState,
   IFlooredRect,
   ResponsiveHeaderNavItem,
-} from "../../types/components";
+} from "../../../types/components";
 import { useResizeObserver, onClickOutside } from "@vueuse/core";
 
 interface Props {
@@ -164,6 +164,51 @@ const closeAllNavigationDetails = () => {
   overflowDetailsRef.value?.removeAttribute("open");
 };
 
+// ─── Hover-intent delay for the "safe triangle" problem ───────────────────
+// handleNavigationItemHover() used to call closeAllNavigationDetails() the
+// instant the mouse entered ANY .main-navigation-item — including a sibling
+// crossed only in transit while moving diagonally from an open dropdown's
+// summary down into its own .main-navigation-sub-nav panel, closing it
+// before the user got there.
+//
+// A pure-CSS "safe triangle" bridge was tried first and reverted: for the
+// bridge to escape .main-navigation-item's overflow:hidden the same way
+// .main-navigation-sub-nav does, its containing block must resolve to
+// .navigation (the only positioned ancestor above the clipping box) — but
+// any element it's attached to that's already positioned (the summary)
+// terminates that search at itself, landing the bridge back inside the
+// clipped box; anything not already positioned falls back to the CSS
+// static-position algorithm, which doesn't reliably land a generated
+// pseudo-element where the visible content is. Neither is fixable without
+// restructuring the panel's positioning, which the collapse-measurement
+// pipeline depends on (see the measurement-pipeline note above).
+//
+// This delay sidesteps that entirely: closing is scheduled, not immediate,
+// and cancelled if the cursor reaches the summary or the sub-nav panel
+// before it fires — so a brief diagonal dip through a sibling's hit area
+// survives, while genuinely moving elsewhere still closes promptly.
+const HOVER_CLOSE_DELAY = 200;
+let closeAllTimer: ReturnType<typeof setTimeout> | null = null;
+
+const cancelScheduledClose = () => {
+  if (closeAllTimer) {
+    clearTimeout(closeAllTimer);
+    closeAllTimer = null;
+  }
+};
+
+const scheduleCloseAllNavigationDetails = () => {
+  cancelScheduledClose();
+  closeAllTimer = setTimeout(() => {
+    closeAllNavigationDetails();
+    closeAllTimer = null;
+  }, HOVER_CLOSE_DELAY);
+};
+
+onUnmounted(() => {
+  cancelScheduledClose();
+});
+
 const toggleDetailsElement = (event: Event) => {
   const summaryElement = event.currentTarget as HTMLElement;
   const parentDetailsElement = summaryElement.closest("details");
@@ -182,6 +227,10 @@ const handleSummaryHover = (event: MouseEvent | FocusEvent) => {
     return;
   }
 
+  // The cursor reached a summary — any close scheduled while it was in
+  // transit (see handleNavigationItemHover) no longer applies.
+  cancelScheduledClose();
+
   // Close all other open navigation details first
   const summaryElement = event.currentTarget as HTMLElement;
   const parentDetailsElement = summaryElement.closest("details");
@@ -193,8 +242,16 @@ const handleSummaryHover = (event: MouseEvent | FocusEvent) => {
   });
   overflowDetailsRef.value?.removeAttribute("open");
 
-  // Then toggle the current one
-  toggleDetailsElement(event);
+  // Ensure THIS one is open — never toggle it closed here. A real mouse click
+  // moves focus to the summary before the click event fires, so a single
+  // click on an already-(hover-)open item fires focusin (this handler) AND
+  // click (handleSummaryAction, which does its own toggle) in quick
+  // succession. If this handler also toggled, an already-open item would
+  // flip closed here and then flip back open in handleSummaryAction — a
+  // visible open→closed→open (or the reverse) flicker on every click.
+  // Hover/focus only ever guarantees "this one is open"; only an explicit
+  // click is allowed to close it.
+  parentDetailsElement?.setAttribute("open", "");
 };
 
 const handleNavigationItemHover = (key: string) => {
@@ -202,7 +259,13 @@ const handleNavigationItemHover = (key: string) => {
   if (!props.allowExpandOnGesture) {
     return;
   }
-  closeAllNavigationDetails();
+  scheduleCloseAllNavigationDetails();
+};
+
+// Reaching the actual destination panel cancels the scheduled close from
+// handleNavigationItemHover — same reasoning as handleSummaryHover above.
+const handleSubNavHover = () => {
+  cancelScheduledClose();
 };
 
 const handleNavFocusout = (event: FocusEvent) => {
@@ -455,42 +518,21 @@ const setupClickOutsideListeners = () => {
   }
 };
 
-onMounted(async () => {
-  // Always reset on every mount — this is a local ref so it naturally resets,
-  // but being explicit here makes the intent clear: geometry must be re-verified
-  // on every route change before the overflow button appears or transitions play.
-  isGeometryReady.value = false;
-
-  // Always (re-)populate the local nav refs — firstNavRef / secondNavRef are local
-  // refs that reset on unmount, so they must be re-assigned on every mount even
-  // when the useState flags say we're already initialized.
-  await initTemplateRefs();
-
-  if (!navigationInitialized.value || !navLoaded.value) {
-    navLoaded.value = true;
-    navigationInitialized.value = true;
-  }
-
-  // Geometry recalculation is handled by useResizeObserver which fires when the
-  // element first becomes observed. isGeometryReady is set there after the pass.
-  setupClickOutsideListeners();
-});
-
-// ─── Re-entrancy guard for the ResizeObserver callback ────────────────────
-// The observer fires an async callback that awaits multiple ticks and toggles
-// layout-affecting state. If the observer fires again while the first pass is
-// still in flight, two concurrent passes would race on isOverflowVisibleForMeasurement
-// and mainNavigationState.
+// ─── Re-entrancy guard for the geometry pass ──────────────────────────────
+// The pass is async and awaits multiple ticks while toggling layout-affecting
+// state. If it's triggered again (resize, or the post-fonts-ready recheck
+// below) while a pass is still in flight, two concurrent passes would race on
+// isOverflowVisibleForMeasurement and mainNavigationState.
 //
 // Pattern: "run-latest" queue.
-//   • isMeasuring gates entry — any new observer call while a pass is running
+//   • isMeasuring gates entry — any new trigger while a pass is running
 //     sets pendingMeasure = true and returns immediately.
-//   • The do/while re-runs once after the pass completes if a new resize arrived,
-//     so we never silently drop the final geometry update.
+//   • The do/while re-runs once after the pass completes if a new trigger
+//     arrived, so we never silently drop the final geometry update.
 let isMeasuring = false;
 let pendingMeasure = false;
 
-useResizeObserver(navigationWrapperRef, async () => {
+const runGeometryPass = async () => {
   if (isMeasuring) {
     pendingMeasure = true;
     return;
@@ -538,15 +580,51 @@ useResizeObserver(navigationWrapperRef, async () => {
         // ─── Normal resize after geometry is settled ───────────────────────────
         // The button's state is already correct (driven by showOverflowDetails),
         // so a single-pass measurement gives accurate secondaryNavRects.
-        await updateNavigationConfig("useResizeObserver");
+        await updateNavigationConfig("resize-or-fonts-ready");
         initMainNavigationState();
       }
     } while (pendingMeasure);
   } finally {
     isMeasuring = false;
   }
+};
+
+onMounted(async () => {
+  // Always reset on every mount — this is a local ref so it naturally resets,
+  // but being explicit here makes the intent clear: geometry must be re-verified
+  // on every route change before the overflow button appears or transitions play.
+  isGeometryReady.value = false;
+
+  // Always (re-)populate the local nav refs — firstNavRef / secondNavRef are local
+  // refs that reset on unmount, so they must be re-assigned on every mount even
+  // when the useState flags say we're already initialized.
+  await initTemplateRefs();
+
+  if (!navigationInitialized.value || !navLoaded.value) {
+    navLoaded.value = true;
+    navigationInitialized.value = true;
+  }
+
+  // Geometry recalculation is handled by useResizeObserver which fires when the
+  // element first becomes observed. isGeometryReady is set there after the pass.
+  setupClickOutsideListeners();
+
+  // ─── Re-verify geometry once webfonts have settled ────────────────────────
+  // The initial ResizeObserver-driven pass can run before self-hosted fonts
+  // (see nuxt.config.ts `fonts.families`) have swapped in, measuring nav-item
+  // widths against fallback-font metrics. That undercounts item width, letting
+  // one extra item fit that shouldn't — the wrapper's own size hasn't changed,
+  // so the ResizeObserver never refires on its own to correct it. document.fonts
+  // isn't available in SSR/non-browser test environments, so this is a no-op there.
+  if (typeof document !== "undefined" && document.fonts) {
+    document.fonts.ready.then(() => {
+      if (isGeometryReady.value) runGeometryPass();
+    });
+  }
 });
 
+useResizeObserver(navigationWrapperRef, runGeometryPass);
+
 const { elementClasses, resetElementClasses } = useStyleClassPassthrough(props.styleClassPassthrough);
 
 watch(
@@ -611,8 +689,17 @@ watch(
        --responsive-nav-decorator-indicator-color         (default: currentColor)
        --responsive-nav-decorator-hovered-indicator-color (default: inherits --responsive-nav-decorator-indicator-color)
        --responsive-nav-decorator-hovered-bg              (default: oklch(100% 0 0 / 8%))
+
+       --responsive-header-link-font-size       (default: inherit)
     ──────────────────────────────────────────────────────────────────────── */
 
+    /* `inherit` means a viewport-relative (vw/clamp) ancestor font-size silently
+       flows into the overflow-collapse width measurement — the ResizeObserver
+       only watches this element's own box size, so a scrollbar-driven vw shift
+       can change nav-item text width without ever re-triggering a re-measurement.
+       Set this token to a fixed value (or a small set of breakpoint-based values)
+       to avoid it. */
+
     --_link-visibility-transition: none;
     position: relative;
     color: var(--responsive-header-color, inherit);
@@ -682,6 +769,7 @@ watch(
             display: flex;
             gap: 6px;
             text-wrap-mode: nowrap;
+            font-size: var(--responsive-header-link-font-size, inherit);
             color: var(--responsive-header-link-color, inherit);
             text-decoration: none;
             cursor: pointer;
@@ -696,6 +784,17 @@ watch(
             border-bottom: var(--_link-border-default);
           }
 
+          /* Reserved so the icon's async-loaded SVG (Icon component) can't widen
+             the item after the initial geometry-measurement pass has already run —
+             an unsized icon measures at ~0 width until its content arrives, which
+             the overflow-collapse ResizeObserver has no way to detect afterwards
+             (the wrapper's own box doesn't necessarily change size when it happens). */
+          .decorator-icon {
+            flex-shrink: 0;
+            width: 1.35em;
+            height: 1.35em;
+          }
+
           .main-navigation-details {
             --_icon-transform: scaleY(1);
 
@@ -711,8 +810,13 @@ watch(
               gap: 6px;
               text-wrap-mode: nowrap;
 
+              /* Reserved for the same reason as .decorator-icon above — an
+                 unsized chevron would widen the summary once its SVG loads. */
               .icon {
                 display: block;
+                flex-shrink: 0;
+                width: 1.35em;
+                height: 1.35em;
                 transform: var(--_icon-transform);
                 transition: transform 0.2s ease-in-out;
               }
@@ -728,6 +832,7 @@ watch(
               cursor: pointer;
               position: relative;
               z-index: 4;
+              font-size: var(--responsive-header-link-font-size, inherit);
               color: var(--responsive-header-link-color, inherit);
 
               &::-webkit-details-marker,
@@ -836,13 +941,6 @@ watch(
         }
       }
 
-      .main-navigation-link {
-        .icon {
-          height: 1.35em;
-          width: 1.35em;
-        }
-      }
-
       .overflow-details {
         list-style: none;
         padding: 0;

package/app/components/03.organisms/responsive-header/stories/NavigationItems.stories.ts

@@ -0,0 +1,80 @@
+import NavigationItems from "../NavigationItems.vue";
+import type { Meta, StoryObj } from "@nuxtjs/storybook";
+import type { ResponsiveHeaderState } from "../../../../types/components";
+
+const mainNavigationState: ResponsiveHeaderState = {
+  hasSecondNav: true,
+  navListVisibility: { firstNav: false, secondNav: false },
+  clonedNavLinks: {
+    firstNav: [
+      { name: "Home", path: "/", config: { left: 0, right: 0, width: 0, visible: false } },
+      { name: "About", path: "/about", config: { left: 0, right: 0, width: 0, visible: false } },
+      {
+        name: "Components",
+        childLinksTitle: "UI Components",
+        childLinks: [
+          { name: "Buttons", path: "/forms/examples/buttons" },
+          { name: "Tabs", path: "/ui/tabs" },
+        ],
+        config: { left: 0, right: 0, width: 0, visible: false },
+      },
+    ],
+    secondNav: [{ name: "Contact", path: "/contact", config: { left: 0, right: 0, width: 0, visible: false } }],
+  },
+};
+
+const meta: Meta<typeof NavigationItems> = {
+  title: "Organisms/Responsive Header/Navigation Items",
+  component: NavigationItems,
+  parameters: {
+    docs: {
+      description: {
+        component:
+          "Internal panel rendered inside ResponsiveHeader's overflow burger menu — not typically used standalone. " +
+          "Shows the *complement* of ResponsiveHeader's main nav: an item appears here only when its `config.visible` " +
+          "is `false` in the main bar.",
+      },
+    },
+  },
+  argTypes: {
+    mainNavigationState: {
+      control: "object",
+      description: "Shared geometry/visibility state, normally supplied by the parent ResponsiveHeader",
+    },
+    styleClassPassthrough: {
+      control: "object",
+      description: "Extra CSS classes applied to the root element",
+    },
+  },
+  args: {
+    mainNavigationState,
+    styleClassPassthrough: [],
+  },
+};
+
+export default meta;
+type Story = StoryObj<typeof NavigationItems>;
+
+export const Default: Story = {};
+
+export const MixedVisibility: Story = {
+  name: "Mixed Visibility (only hidden items shown)",
+  args: {
+    mainNavigationState: {
+      hasSecondNav: false,
+      navListVisibility: { firstNav: false },
+      clonedNavLinks: {
+        firstNav: [
+          { name: "Home", path: "/", config: { left: 0, right: 0, width: 0, visible: true } },
+          { name: "About", path: "/about", config: { left: 0, right: 0, width: 0, visible: false } },
+          { name: "Contact", path: "/contact", config: { left: 0, right: 0, width: 0, visible: false } },
+        ],
+      },
+    },
+  },
+};
+
+export const Empty: Story = {
+  name: "Empty (nothing collapsed)",
+  args: { mainNavigationState: { hasSecondNav: false, navListVisibility: {}, clonedNavLinks: {} } },
+};

package/app/components/03.organisms/responsive-header/stories/ResponsiveHeader.stories.ts

@@ -0,0 +1,122 @@
+import ResponsiveHeader from "../ResponsiveHeader.vue";
+import type { Meta, StoryObj } from "@nuxtjs/storybook";
+
+const meta: Meta<typeof ResponsiveHeader> = {
+  title: "Organisms/Responsive Header",
+  component: ResponsiveHeader,
+  argTypes: {
+    responsiveNavLinks: {
+      control: "object",
+      description: "Nav groups keyed by name — each item is either a link (`path`) or a dropdown (`childLinks`)",
+    },
+    gapBetweenFirstAndSecondNav: {
+      control: { type: "number", min: 0, step: 4 },
+      description: "Gap in pixels reserved between the first and second nav groups",
+    },
+    overflowDetailsSummaryIcons: {
+      control: "object",
+      description: "Icon names for the overflow button's two states: `more` (some items collapsed) and `burger`",
+    },
+    collapseBreakpoint: {
+      control: { type: "number" },
+      description: "Fixed pixel width below which the whole main nav collapses into the overflow burger menu",
+    },
+    collapseAtMainNavIntersection: {
+      control: "boolean",
+      description: "Collapse the whole main nav into the overflow burger menu once it no longer fits its container",
+    },
+    allowExpandOnGesture: {
+      control: "boolean",
+      description: "Allow a dropdown to open on hover/focus, not just click",
+    },
+    styleClassPassthrough: {
+      control: "object",
+      description: "Extra CSS classes applied to the root element",
+    },
+  },
+  args: {
+    gapBetweenFirstAndSecondNav: 12,
+    collapseBreakpoint: null,
+    collapseAtMainNavIntersection: false,
+    allowExpandOnGesture: true,
+    styleClassPassthrough: [],
+  },
+};
+
+export default meta;
+type Story = StoryObj<typeof ResponsiveHeader>;
+
+const responsiveNavLinks = {
+  firstNav: [
+    { name: "Home", path: "/" },
+    {
+      name: "Components",
+      iconName: "material-symbols:widgets",
+      childLinksTitle: "UI Components",
+      childLinks: [
+        { name: "Buttons", path: "/forms/examples/buttons" },
+        { name: "Tabs", path: "/ui/tabs" },
+        { name: "Carousels", path: "/ui/carousel-basic" },
+      ],
+    },
+    { name: "Typography", path: "/typography/page-heading" },
+  ],
+  secondNav: [{ name: "Contact", path: "#" }],
+};
+
+export const Default: Story = {
+  args: { responsiveNavLinks },
+};
+
+/** Constrains the canvas so some items must collapse into the overflow burger menu —
+ * the same behaviour a narrow viewport triggers in a real page, not a bug. */
+export const ConstrainedWidth: Story = {
+  name: "Constrained Width (items overflow)",
+  args: { responsiveNavLinks },
+  render: (args) => ({
+    components: { ResponsiveHeader },
+    setup() {
+      return { args };
+    },
+    template: `<div style="max-width: 420px"><ResponsiveHeader v-bind="args" /></div>`,
+  }),
+};
+
+export const CustomOverflowIcons: Story = {
+  args: {
+    responsiveNavLinks,
+    overflowDetailsSummaryIcons: { more: "mdi:dots-horizontal", burger: "mdi:menu" },
+  },
+};
+
+export const WithSecondaryNavigationSlot: Story = {
+  name: "With secondaryNavigation slot",
+  args: { responsiveNavLinks },
+  render: (args) => ({
+    components: { ResponsiveHeader },
+    setup() {
+      return { args };
+    },
+    template: `
+      <ResponsiveHeader v-bind="args">
+        <template #secondaryNavigation>
+          <a href="/settings" aria-label="Settings">⚙</a>
+        </template>
+      </ResponsiveHeader>
+    `,
+  }),
+};
+
+export const SingleFlatGroup: Story = {
+  name: "Single Flat Group (no dropdowns)",
+  args: {
+    responsiveNavLinks: {
+      main: [
+        { name: "Home", path: "/" },
+        { name: "About", path: "/about" },
+        { name: "Services", path: "/services" },
+        { name: "Contact", path: "/contact" },
+      ],
+    },
+  },
+};