srcdev-nuxt-components 9.5.5 → 9.5.7

package/app/components/02.molecules/select-menu/CONSUMER-STYLING.md

@@ -37,6 +37,7 @@ global token so it matches the rest of the design system out of the box.
 | `--select-menu-popover-min-width` | `18rem` | Minimum popover width |
 | `--select-menu-popover-max-height` | `32rem` | Maximum popover height before scrolling |
 | `--select-menu-popover-shadow` | `0 0.4rem 1.6rem rgb(0 0 0 / 12%)` | Popover drop shadow |
+| `--select-menu-popover-z-index` | `999999` | Stacking order in browsers without CSS anchor positioning (see Notes). Ignored where the popover renders in the top layer |
 | `--select-menu-transition-duration` | `200ms` | Open/close fade and chevron-rotate duration |
 
 ### Options
@@ -69,7 +70,13 @@ global token so it matches the rest of the design system out of the box.
 | Hook | Where | Meaning |
 |---|---|---|
 | `.normal` / `.underlined` | `.select-menu` root | The `inputVariant` prop. `underlined` removes the trigger's top and side borders and its corner radius, matching `InputSelect`'s underlined variant. |
-| `:has(.select-menu-popover:popover-open)` | `.select-menu` root | Menu open (rotates the chevron). |
+| `.select-menu-trigger[aria-expanded="true"]` | trigger | Menu open (rotates the chevron). Works with and without the Popover API. |
+| `.select-menu-popover:popover-open` | popover | Menu open, Popover API browsers. |
+| `.select-menu-popover-open` | popover | Menu open, browsers without the Popover API (Safari 16 and older). Style both open hooks in **separate rules**: a selector list containing `:popover-open` is dropped whole where it's unsupported. |
+| `[data-placement="top"]` | popover | Flipped above the trigger, browsers without CSS anchor positioning only. |
+
+> Changed 2026-10-05: the chevron hook moved from `:has(.select-menu-popover:popover-open)` on the
+> root to the trigger's `aria-expanded`, so it also works without the Popover API.
 
 ---
 
@@ -186,10 +193,15 @@ story.
 
 ## Notes
 
-- **Popover API + CSS anchor positioning** — same mechanism as `ActionMenu`. Broadly supported
-  (Chrome 114+, Firefox 125+, Safari 17+). No polyfill is included.
+- **Popover API + CSS anchor positioning, with fallbacks** — same mechanism as `ActionMenu`, via the
+  shared `useAnchoredPopover` composable. Without anchor positioning (e.g. Safari 17–18), the
+  popover is placed with `position: fixed` from the trigger's measured position, re-measured on
+  scroll and resize. Without the Popover API (Safari 16 and older), the menu also opens and
+  closes in JS, with outside-click and Escape dismissal. In that mode it isn't in the top layer, so
+  `--select-menu-popover-z-index` matters, and an ancestor with `transform`, `filter` or
+  `contain` becomes its containing block and can misplace it.
 - **Popover left-aligns with the trigger** by default (`left: anchor(left)`), unlike `ActionMenu`
   which right-aligns — matches native `<select>` dropdown behaviour. Flips above the trigger near
   the bottom of the viewport (`position-try-fallbacks: flip-block`).
-- **Chevron rotation** is pure CSS via `:has(.select-menu-popover:popover-open)` — no JS state
-  needed for the visual, though `isOpen` is still tracked internally to drive `aria-expanded`.
+- **Chevron rotation** is driven by the trigger's `aria-expanded`, which tracks the open state in
+  every browser.

package/app/components/02.molecules/select-menu/SelectMenu.vue

@@ -1,5 +1,10 @@
 <template>
-  <div class="select-menu" :class="[inputVariant, elementClasses]" :style="`--_anchor-name: ${anchorName}`">
+  <div
+    ref="rootRef"
+    class="select-menu"
+    :class="[inputVariant, elementClasses]"
+    :style="`--_anchor-name: ${anchorName}`"
+  >
     <button
       ref="triggerRef"
       :popovertarget="menuId"
@@ -9,6 +14,7 @@
       :aria-label="label"
       aria-haspopup="listbox"
       :aria-expanded="isOpen"
+      @click="handleTriggerClick"
     >
       <Icon
         v-if="showIcon && !multiple && selectedOption?.icon"
@@ -30,6 +36,10 @@
       ref="popoverRef"
       popover
       class="select-menu-popover"
+      :class="{ 'select-menu-popover-open': usesFallbackPopover && isOpen }"
+      :style="positionStyle"
+      :data-placement="popoverPlacement"
+      @beforetoggle="handleBeforeToggle"
       @toggle="handleToggle"
       @keydown="handleKeydown"
     >
@@ -103,9 +113,9 @@ const id = useId();
 const menuId = `select-menu-${id}`;
 const anchorName = `--select-menu-anchor-${id}`;
 
+const rootRef = ref<HTMLDivElement | null>(null);
 const triggerRef = ref<HTMLButtonElement | null>(null);
 const popoverRef = ref<HTMLDivElement | null>(null);
-const isOpen = ref(false);
 
 const selectedValues = computed(() => (props.multiple && Array.isArray(modelValue.value) ? modelValue.value : []));
 const selectedOption = computed(() =>
@@ -137,6 +147,23 @@ const isSelected = (option: SelectMenuOption): boolean =>
 const getMenuItems = (): HTMLElement[] =>
   Array.from(popoverRef.value?.querySelectorAll<HTMLElement>('[role="option"]') ?? []);
 
+const focusInitialItem = () => {
+  const items = getMenuItems();
+  const selectedIndex = items.findIndex((el) => el.getAttribute("aria-selected") === "true");
+  items[selectedIndex === -1 ? 0 : selectedIndex]?.focus();
+};
+
+const {
+  isOpen,
+  usesFallbackPopover,
+  positionStyle,
+  popoverPlacement,
+  hide,
+  handleTriggerClick,
+  handleBeforeToggle,
+  handleToggle,
+} = useAnchoredPopover({ rootRef, triggerRef, popoverRef, onOpen: focusInitialItem });
+
 const selectOption = (option: SelectMenuOption) => {
   if (props.multiple) {
     const next = selectedValues.value.includes(option.value)
@@ -146,20 +173,10 @@ const selectOption = (option: SelectMenuOption) => {
     return;
   }
   modelValue.value = option.value;
-  popoverRef.value?.hidePopover();
+  hide();
   triggerRef.value?.focus();
 };
 
-const handleToggle = (event: Event) => {
-  const toggleEvent = event as ToggleEvent;
-  isOpen.value = toggleEvent.newState === "open";
-  if (isOpen.value) {
-    const items = getMenuItems();
-    const selectedIndex = items.findIndex((el) => el.getAttribute("aria-selected") === "true");
-    items[selectedIndex === -1 ? 0 : selectedIndex]?.focus();
-  }
-};
-
 /**
  * Keyboard navigation following the WAI-ARIA listbox pattern.
  *
@@ -168,7 +185,7 @@ const handleToggle = (event: Event) => {
  * Enter / Space        — select the focused option. Closes the menu in single-select mode;
  *                        toggles the checkbox and keeps the menu open in multi-select mode.
  * Tab                  — close the menu; let the browser Tab naturally.
- * Escape               — handled natively by the Popover API.
+ * Escape               — native light dismiss, or the fallback listener without the Popover API.
  */
 const handleKeydown = (event: KeyboardEvent) => {
   const items = getMenuItems();
@@ -201,7 +218,7 @@ const handleKeydown = (event: KeyboardEvent) => {
       break;
     }
     case "Tab":
-      popoverRef.value?.hidePopover();
+      hide();
       break;
   }
 };
@@ -288,7 +305,7 @@ watch(
       border-radius: 0;
     }
 
-    &:has(.select-menu-popover:popover-open) .select-menu-trigger-chevron {
+    .select-menu-trigger[aria-expanded="true"] .select-menu-trigger-chevron {
       transform: rotate(180deg);
     }
 
@@ -329,6 +346,24 @@ watch(
         }
       }
 
+      /* Kept apart from :popover-open, which would invalidate a shared selector list where unsupported. */
+      &.select-menu-popover-open {
+        display: block;
+        opacity: 1;
+      }
+
+      @supports not (anchor-name: --a) {
+        position: fixed;
+        top: calc(var(--_anchor-bottom, 0px) + var(--select-menu-block-distance, 0.4rem));
+        left: var(--_anchor-left, 0px);
+        z-index: var(--select-menu-popover-z-index, 999999);
+
+        &[data-placement="top"] {
+          top: auto;
+          bottom: calc(var(--_anchor-top-inverse, 0px) + var(--select-menu-block-distance, 0.4rem));
+        }
+      }
+
       .select-menu-list {
         display: grid;
         grid-template-columns: auto auto 1fr;

package/app/components/02.molecules/select-menu/tests/SelectMenu.spec.ts

@@ -482,4 +482,40 @@ describe("SelectMenu", () => {
       expect(wrapper.classes()).toContain("select-menu");
     });
   });
+
+  // -------------------------
+  // Without the Popover API (Safari 16 and older)
+  // -------------------------
+  describe("Without the Popover API", () => {
+    beforeEach(() => {
+      Object.defineProperty(HTMLElement.prototype, "showPopover", { value: undefined, writable: true, configurable: true });
+    });
+
+    it("opens from the trigger with the fallback open class and aria-expanded", async () => {
+      wrapper = await createWrapper();
+      const popover = wrapper.find(".select-menu-popover");
+      expect(popover.classes()).not.toContain("select-menu-popover-open");
+
+      await wrapper.find(".select-menu-trigger").trigger("click");
+      expect(popover.classes()).toContain("select-menu-popover-open");
+      expect(wrapper.find(".select-menu-trigger").attributes("aria-expanded")).toBe("true");
+    });
+
+    it("closes when a single-select option is chosen", async () => {
+      wrapper = await createWrapper();
+      await wrapper.find(".select-menu-trigger").trigger("click");
+      await wrapper.findAll('[role="option"]')[1]!.trigger("click");
+
+      expect(wrapper.emitted("update:modelValue")?.[0]).toEqual(["fr"]);
+      expect(wrapper.find(".select-menu-popover").classes()).not.toContain("select-menu-popover-open");
+    });
+
+    it("stays open while toggling options in multiple mode", async () => {
+      wrapper = await createWrapper({ multiple: true, modelValue: [] });
+      await wrapper.find(".select-menu-trigger").trigger("click");
+      await wrapper.findAll('[role="option"]')[1]!.trigger("click");
+
+      expect(wrapper.find(".select-menu-popover").classes()).toContain("select-menu-popover-open");
+    });
+  });
 });

package/app/components/03.organisms/google-reviews/stories/GoogleReviews.stories.ts

@@ -54,14 +54,19 @@ const meta: Meta<StoryArgs> = {
     authorLineClamp: {
       control: "select",
       options: lineClampOptions,
-      description: "Story control for --google-reviews-author-line-clamp (1 = single-line ellipsis)",
-      table: { category: "CSS tokens" },
+      description:
+        "**Story control, not a prop.** Sets the `--google-reviews-author-line-clamp` CSS token on a wrapper. " +
+        "To use it in an app, set the token in your own CSS, e.g. `.reviews { --google-reviews-author-line-clamp: 1; }`. " +
+        "`1` is single-line ellipsis.",
+      table: { category: "CSS tokens (story only, set in your CSS)" },
     },
     textLineClamp: {
       control: "select",
       options: lineClampOptions,
-      description: "Story control for --google-reviews-text-line-clamp",
-      table: { category: "CSS tokens" },
+      description:
+        "**Story control, not a prop.** Sets the `--google-reviews-text-line-clamp` CSS token on a wrapper. " +
+        "To use it in an app, set the token in your own CSS, e.g. `.reviews { --google-reviews-text-line-clamp: 3; }`.",
+      table: { category: "CSS tokens (story only, set in your CSS)" },
     },
     data: { control: "object", description: "GoogleReviewsData, usually from useGoogleReviews()" },
     minRating: { control: { type: "range", min: 0, max: 5, step: 1 }, description: "Hide reviews below this rating; shows the filter notice" },

package/app/components/03.organisms/responsive-header/CONSUMER-STYLING.md

@@ -11,6 +11,7 @@ are documented alongside it since that's where they're consumed.
 |---|---|---|
 | `--responsive-header-link-font-size` | `inherit` | Nav-link font-size. **Always set this to a fixed value.** Leaving it `inherit` means a fluid ancestor font-size (`clamp()`/`vw`) can drift nav-item text width without ever re-triggering the overflow-collapse measurement — see the component skill doc's "measurement pipeline" section for the full mechanism. |
 | `--responsive-header-link-color` | `inherit` | Link/summary text colour. |
+| `--responsive-header-main-nav-justify-content` | `space-between` | How the main nav's groups are spread along the bar. Use `flex-start`, `safe center` or `safe end`; plain `center`/`end` let items that don't fit spill off the start edge, where they're clipped. (Safari 16 ignores `safe` values and falls back to start alignment.) |
 | `--responsive-header-color` | `inherit` | Root element text colour. |
 | `--responsive-header-margin` | `0` | Root element margin. |
 | `--responsive-header-bg` | `transparent` | Root element background. |
@@ -20,8 +21,21 @@ are documented alongside it since that's where they're consumed.
 | `--responsive-header-max-height` | `none` | Root element max-height. |
 | `--responsive-header-inline-size` | `100%` | Root element inline-size. |
 | `--responsive-header-sub-nav-bg` / `-border` / `-border-radius` / `-padding` | `Canvas` / `1px solid #efefef75` / `8px` / `12px` | Top-bar dropdown panel (`.main-navigation-sub-nav`). |
+| `--responsive-header-sub-nav-max-inline-size` | `min(48rem, calc(100vw - 3.2rem))` | Widest the top-bar dropdown panel gets; long child names wrap inside it. |
+| `--responsive-header-sub-nav-max-block-size` | `70vh` | Tallest the top-bar dropdown panel gets before it scrolls, so a long child list stays reachable under a sticky header. |
 | `--responsive-header-overflow-btn-bg` / `-size` / `-border` / `-outline` / `-icon-color` / `-hover-outline` | `Canvas` / `20px` / `1px solid #ffffff90` / `1px solid #ffffff10` / `inherit` / `1px solid #ffffff` | Overflow burger button. |
 | `--responsive-header-overflow-nav-bg` / `-border` / `-border-radius` / `-padding-block` | `Canvas` / `1px solid #ffffff90` / `8px` / `12px` | Overflow panel container. |
+| `--responsive-header-overflow-nav-max-block-size` | `70vh` | Tallest the overflow panel gets before it scrolls. |
+| `--overflow-nav-max-inline-size` | `calc(100vw - 3.2rem)` | Widest the overflow panel's content gets (set on `NavigationItems`); long names wrap inside it. |
+
+Link and dropdown text is never line-clamped: it names where the link goes. Long unbroken names
+wrap inside the dropdown and overflow panels; in the top bar, an item too wide to fit moves to the
+overflow menu.
+
+> **Changed 2026-10-05**: the dropdown and overflow panels had no maximum size, so a long child
+> name or a long child list ran off-screen. They are now capped by the four tokens above.
+> `--_overflow-drop-down-width`, a private token nothing ever set, is gone (`min-width: fit-content`
+> directly).
 | `--responsive-nav-decorator-indicator-color` | `currentColor` | Active-item indicator bar/underline. |
 | `--responsive-nav-decorator-hovered-indicator-color` | inherits the above | Indicator colour while hovering. |
 | `--responsive-nav-decorator-hovered-bg` | `oklch(100% 0 0 / 8%)` | Hover highlight background behind the hovered item. |

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

@@ -27,8 +27,7 @@
             'is-active': isActiveNavItem(link),
           }"
           :style="{
-            '--_main-navigation-item-width':
-              mainNavigationState.clonedNavLinks?.[groupKey]?.[localIndex]?.config?.width + 'px',
+            '--_main-navigation-item-width': itemWidth(mainNavigationState.clonedNavLinks?.[groupKey]?.[localIndex]),
           }"
           :data-group-key="groupKey"
           :data-local-index="localIndex"
@@ -48,8 +47,7 @@
             'is-active': isActiveNavItem(link),
           }"
           :style="{
-            '--_main-navigation-item-width':
-              mainNavigationState.clonedNavLinks?.[groupKey]?.[localIndex]?.config?.width + 'px',
+            '--_main-navigation-item-width': itemWidth(mainNavigationState.clonedNavLinks?.[groupKey]?.[localIndex]),
           }"
           :data-group-key="groupKey"
           :data-local-index="localIndex"
@@ -66,11 +64,11 @@
             <template #summary>
               <span
                 class="overflow-navigation-text"
-                :aria-label="`${link.childLinksTitle} submenu`"
+                :aria-label="submenuLabel(link)"
                 role="menuitem"
                 :aria-haspopup="true"
               >
-                {{ link.childLinksTitle }}
+                {{ link.childLinksTitle ?? link.name }}
               </span>
             </template>
             <template #icon>
@@ -81,7 +79,7 @@
                 <ul class="overflow-navigation-sub-nav-list" @mouseleave="hoveredChildKey = null">
                   <li
                     v-for="(childLink, childIndex) in link.childLinks"
-                    :key="childLink.name"
+                    :key="childIndex"
                     class="overflow-navigation-sub-nav-item"
                     :class="{
                       'is-hovered': hoveredChildKey === `${String(groupKey)}-${localIndex}-${childIndex}`,
@@ -117,6 +115,8 @@ interface Props {
   styleClassPassthrough?: string | string[];
   /** aria-label on the overflow menu — override for localisation. */
   ariaLabel?: string;
+  /** aria-label on each submenu summary; {title} is replaced with the item's title. */
+  submenuAriaLabel?: string;
 }
 
 const props = withDefaults(defineProps<Props>(), {
@@ -127,8 +127,12 @@ const props = withDefaults(defineProps<Props>(), {
   panelVariant: "classic",
   styleClassPassthrough: () => [],
   ariaLabel: "Overflow navigation menu",
+  submenuAriaLabel: "{title} submenu",
 });
 
+const submenuLabel = (link: ResponsiveHeaderNavItem) =>
+  props.submenuAriaLabel.replace("{title}", link.childLinksTitle ?? link.name);
+
 const panelComponent = computed(() => (props.panelVariant === "modern" ? ExpandingPanel : ExpandingPanelClassic));
 
 const hoveredItemKey = ref<string | null>(null);
@@ -178,6 +182,9 @@ const widestNavLinkWidthInMainNavigationState = computed(() => {
   }, 0);
 });
 
+const itemWidth = (link?: ResponsiveHeaderNavItem) =>
+  link?.config?.width === undefined ? undefined : `${link.config.width}px`;
+
 const { elementClasses, resetElementClasses } = useStyleClassPassthrough(props.styleClassPassthrough);
 
 // Performance: Use immediate flag and more efficient watching
@@ -199,6 +206,7 @@ watch(
        on this element to avoid cascade conflicts with ancestor overrides.
 
        --overflow-nav-padding-inline         (default: 0.8rem)
+       --overflow-nav-max-inline-size        (default: calc(100vw - 3.2rem))
        --overflow-nav-items-gap              (default: 0px)
        --overflow-nav-items-padding-block    (default: 0.8rem)
 
@@ -212,10 +220,15 @@ watch(
        --overflow-nav-decorator-hovered-bg              (default: oklch(100% 0 0 / 6%))
     ──────────────────────────────────────────────────────────────────────── */
 
+    --_max-inline-size: var(--overflow-nav-max-inline-size, calc(100vw - 3.2rem));
+
     display: flex;
     flex-direction: column;
     gap: var(--overflow-nav-items-gap, 0px);
     position: relative;
+    inline-size: max-content;
+    max-inline-size: var(--_max-inline-size);
+    overflow-wrap: anywhere;
 
     .overflow-navigation-list {
       display: none;
@@ -224,7 +237,7 @@ watch(
         display: flex;
         flex-direction: column;
         gap: var(--overflow-nav-items-gap, 0px);
-        min-width: var(--_overflow-navigation-list-min-width, auto);
+        min-width: min(var(--_overflow-navigation-list-min-width, 0px), var(--_max-inline-size));
       }
 
       .overflow-navigation-item {
@@ -262,9 +275,7 @@ watch(
                 border-bottom: 0.1rem solid var(--overflow-nav-link-border-color, #efefef75);
 
                 .label-wrapper {
-                  .overflow-navigation-text {
-                    text-wrap: nowrap;
-                  }
+                  min-inline-size: 0;
                 }
                 .icon-wrapper {
                   padding: 0;
@@ -325,9 +336,7 @@ watch(
                 border-bottom: 0.1rem solid var(--overflow-nav-link-border-color, #efefef75);
 
                 .label-wrapper {
-                  .overflow-navigation-text {
-                    text-wrap: nowrap;
-                  }
+                  min-inline-size: 0;
                 }
                 .icon-wrapper {
                   padding: 0;

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

@@ -32,8 +32,7 @@
             'is-active': isActiveNavItem(link),
           }"
           :style="{
-            '--_main-navigation-item-width':
-              mainNavigationState.clonedNavLinks?.[groupKey]?.[localIndex]?.config?.width + 'px',
+            '--_main-navigation-item-width': itemWidth(mainNavigationState.clonedNavLinks?.[groupKey]?.[localIndex]),
           }"
           :data-group-key="groupKey"
           :data-local-index="localIndex"
@@ -52,7 +51,7 @@
           <details v-else ref="navigationDetails" class="main-navigation-details" name="navigation-group">
             <summary
               class="main-navigation-details-summary has-toggle-icon"
-              :aria-label="`${link.childLinksTitle} submenu`"
+              :aria-label="submenuLabel(link)"
               @mouseenter="handleSummaryHover($event)"
               @focusin="handleSummaryHover($event)"
               @click.prevent="handleSummaryAction($event)"
@@ -61,11 +60,15 @@
               <Icon name="mdi:chevron-down" class="icon" :aria-hidden="true" />
               <Icon v-if="link.iconName" :name="link.iconName" class="decorator-icon" aria-hidden="true" />
 
-              {{ link.childLinksTitle }}
+              {{ link.childLinksTitle ?? link.name }}
             </summary>
             <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">
+                <li
+                  v-for="(childLink, childIndex) in link.childLinks"
+                  :key="childIndex"
+                  class="main-navigation-sub-nav-item"
+                >
                   <NuxtLink :to="childLink.path" class="main-navigation-sub-nav-link" role="menuitem">
                     {{ childLink.name }}
                   </NuxtLink>
@@ -85,7 +88,7 @@
         :class="overflowDetailsClass ? [overflowDetailsClass] : []"
         name="overflow-group"
       >
-        <summary class="overflow-details-summary has-toggle-icon">
+        <summary class="overflow-details-summary has-toggle-icon" :aria-label="overflowButtonLabel">
           <Icon
             :name="overflowDetailsSummaryIcons.more ?? 'gravity-ui:ellipsis'"
             class="icon"
@@ -104,6 +107,7 @@
             :main-navigation-state="mainNavigationState"
             :panel-variant="panelVariant"
             :aria-label="overflowMenuAriaLabel"
+            :submenu-aria-label="submenuAriaLabel"
           />
         </div>
       </details>
@@ -136,6 +140,10 @@ interface Props {
   secondaryNavAriaLabel?: string;
   /** aria-label on the overflow menu itself (forwarded to NavigationItems) — override for localisation. */
   overflowMenuAriaLabel?: string;
+  /** Accessible name of the overflow/burger button, which shows only icons. */
+  overflowButtonLabel?: string;
+  /** aria-label on each dropdown summary; {title} is replaced with the item's title. Forwarded to NavigationItems. */
+  submenuAriaLabel?: string;
 }
 
 const props = withDefaults(defineProps<Props>(), {
@@ -155,8 +163,13 @@ const props = withDefaults(defineProps<Props>(), {
   mainNavAriaLabel: "Main navigation",
   secondaryNavAriaLabel: "Secondary navigation",
   overflowMenuAriaLabel: "Overflow navigation menu",
+  overflowButtonLabel: "More navigation",
+  submenuAriaLabel: "{title} submenu",
 });
 
+const submenuLabel = (link: ResponsiveHeaderNavItem) =>
+  props.submenuAriaLabel.replace("{title}", link.childLinksTitle ?? link.name);
+
 const collapseNavigationBelowWidth = computed(
   () => props.collapseBreakpoint !== null || props.collapseAtMainNavIntersection
 );
@@ -173,6 +186,7 @@ const {
 const slots = useSlots();
 
 const navigationWrapperRef = useTemplateRef<HTMLDivElement>("navigationWrapper");
+const mainNavRef = useTemplateRef<HTMLElement>("mainNav");
 
 const closeAllNavigationDetails = () => {
   navigationDetailsRefs.value?.forEach((element) => {
@@ -361,7 +375,10 @@ const mainNavigationState = ref<ResponsiveHeaderState>({
     firstNav: false,
     secondNav: false,
   },
-  clonedNavLinks: props.responsiveNavLinks,
+  // Copied so the geometry pass's config writes never land in the consumer's own nav data
+  clonedNavLinks: Object.fromEntries(
+    Object.entries(props.responsiveNavLinks).map(([groupKey, group]) => [groupKey, group.map((link) => ({ ...link }))])
+  ),
   hasSecondNav: Object.keys(props.responsiveNavLinks).length > 1,
 });
 
@@ -398,12 +415,13 @@ const navigationDetailsRefs = useTemplateRef<HTMLElement[]>("navigationDetails")
 
 const overflowDetailsRef = useTemplateRef<HTMLDetailsElement>("overflowDetails");
 
-const showOverflowDetails = computed(() => {
-  const hasHiddenNav =
-    !mainNavigationState.value.navListVisibility["firstNav"] ||
-    (!mainNavigationState.value.navListVisibility["secondNav"] && mainNavigationState.value.hasSecondNav);
-  return hasHiddenNav;
-});
+// Item-based rather than reading navListVisibility.firstNav/secondNav, so any group key works and
+// empty nav data never shows a burger with nothing in it
+const showOverflowDetails = computed(() =>
+  Object.values(mainNavigationState.value.clonedNavLinks ?? {}).some((group) =>
+    group.some((link) => link.config?.visible === false)
+  )
+);
 
 const mainNavigationMarginBlockEnd = computed(() => {
   return secondaryNavRects.value ? secondaryNavRects.value.width + props.gapBetweenFirstAndSecondNav : 0;
@@ -462,20 +480,18 @@ const determineNavigationItemVisibility = (rect: DOMRect) => {
     return false;
   }
 
-  // Use default responsive visibility logic if wrapper exists
-  if (navigationWrapperRects.value) {
-    return (
-      Math.floor(rect.right + mainNavigationMarginBlockEnd.value + props.gapBetweenFirstAndSecondNav) <
-      navigationWrapperRects.value.right
-    );
-  }
-
-  // Default to visible
-  return true;
+  // An item fits if it ends within the main nav, whose margin-inline-end already reserves the
+  // secondary nav plus the gap. Measured live with the item so both read the same layout.
+  const mainNavRect = mainNavRef.value?.getBoundingClientRect();
+  if (!mainNavRect) return true;
+  return Math.floor(rect.right) <= Math.floor(mainNavRect.right);
 };
 
 const initMainNavigationState = () => {
-  if (!mainNavigationItemsRefs.value) return;
+  if (!mainNavigationItemsRefs.value?.length) {
+    isGeometryReady.value = true;
+    return;
+  }
 
   mainNavigationItemsRefs.value.forEach(async (item) => {
     // await nextTick()
@@ -642,6 +658,9 @@ onMounted(async () => {
 
 useResizeObserver(navigationWrapperRef, runGeometryPass);
 
+const itemWidth = (link?: ResponsiveHeaderNavItem) =>
+  link?.config?.width === undefined ? undefined : `${link.config.width}px`;
+
 const { elementClasses, resetElementClasses } = useStyleClassPassthrough(props.styleClassPassthrough);
 
 watch(
@@ -690,6 +709,8 @@ watch(
        --responsive-header-sub-nav-border       (default: 1px solid #efefef75)
        --responsive-header-sub-nav-border-radius (default: 8px)
        --responsive-header-sub-nav-padding      (default: 12px)
+       --responsive-header-sub-nav-max-inline-size (default: min(48rem, calc(100vw - 3.2rem)))
+       --responsive-header-sub-nav-max-block-size  (default: 70vh)
 
        --responsive-header-overflow-btn-bg              (default: Canvas)
        --responsive-header-overflow-btn-size            (default: 20px)
@@ -702,12 +723,14 @@ watch(
        --responsive-header-overflow-nav-border          (default: 1px solid #ffffff90)
        --responsive-header-overflow-nav-border-radius   (default: 8px)
        --responsive-header-overflow-nav-padding-block   (default: 12px)
+       --responsive-header-overflow-nav-max-block-size  (default: 70vh)
 
        --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)
+       --responsive-header-main-nav-justify-content (default: space-between)
     ──────────────────────────────────────────────────────────────────────── */
 
     /* `inherit` means a viewport-relative (vw/clamp) ancestor font-size silently
@@ -749,7 +772,7 @@ watch(
       display: flex;
       flex-wrap: nowrap;
       flex-grow: 1;
-      justify-content: space-between;
+      justify-content: var(--responsive-header-main-nav-justify-content, space-between);
       gap: 60px;
       overflow-x: hidden;
       margin-inline-end: v-bind(mainNavigationMarginBlockEndStr);
@@ -782,7 +805,7 @@ watch(
           .main-navigation-link {
             display: flex;
             gap: 6px;
-            text-wrap-mode: nowrap;
+            white-space: nowrap;
             font-size: var(--responsive-header-link-font-size, inherit);
             color: var(--responsive-header-link-color, inherit);
             text-decoration: none;
@@ -821,7 +844,7 @@ watch(
             .has-toggle-icon {
               display: flex;
               gap: 6px;
-              text-wrap-mode: nowrap;
+              white-space: nowrap;
 
               /* Reserved for the same reason as .decorator-icon above — an
                  unsized chevron would widen the summary once its SVG loads. */
@@ -868,6 +891,9 @@ watch(
               translate: 0 12px;
 
               min-width: var(--_main-navigation-item-width);
+              max-inline-size: var(--responsive-header-sub-nav-max-inline-size, min(48rem, calc(100vw - 3.2rem)));
+              max-block-size: var(--responsive-header-sub-nav-max-block-size, 70vh);
+              overflow-y: auto;
 
               .main-navigation-sub-nav-list {
                 display: grid;
@@ -883,7 +909,7 @@ watch(
 
                   .main-navigation-sub-nav-link {
                     display: block;
-                    text-wrap-mode: nowrap;
+                    overflow-wrap: anywhere;
                     text-decoration: none;
                     color: var(--responsive-header-link-color, inherit);
                   }
@@ -994,7 +1020,7 @@ watch(
           align-items: center;
           justify-content: center;
           padding-inline: 5px;
-          text-wrap: nowrap;
+          white-space: nowrap;
 
           aspect-ratio: 1;
           border-radius: 4px;
@@ -1048,7 +1074,9 @@ watch(
           padding-block: var(--responsive-header-overflow-nav-padding-block, 12px);
           margin: 0;
           z-index: 999;
-          min-width: var(--_overflow-drop-down-width, fit-content);
+          min-width: fit-content;
+          max-block-size: var(--responsive-header-overflow-nav-max-block-size, 70vh);
+          overflow-y: auto;
 
           display: grid;
           grid-auto-flow: row;