srcdev-nuxt-components 9.3.0 → 9.3.2

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

@@ -0,0 +1,155 @@
+import { describe, it, expect } from "vitest";
+import { mountSuspended } from "@nuxt/test-utils/runtime";
+import { nextTick } from "vue";
+import NavigationItems from "../NavigationItems.vue";
+import type { ResponsiveHeaderState } from "../../../../types/components";
+
+// NavigationItems renders the *complement* of what's visible in ResponsiveHeader's
+// top bar: an item shows here only when its `config.visible` is false there. Mixing
+// visible/hidden items (rather than the all-hidden case ResponsiveHeader's own tests
+// exercise under jsdom's zero-size layout) verifies that complement logic directly.
+const mainNavigationState: ResponsiveHeaderState = {
+  hasSecondNav: true,
+  navListVisibility: { firstNav: false, secondNav: true },
+  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: "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: true } }],
+  },
+};
+
+describe("NavigationItems", () => {
+  it("mounts without error", async () => {
+    const wrapper = await mountSuspended(NavigationItems, {
+      props: { mainNavigationState },
+    });
+    expect(wrapper.vm).toBeTruthy();
+  });
+
+  it("only shows the group whose navListVisibility flag is false", async () => {
+    const wrapper = await mountSuspended(NavigationItems, {
+      props: { mainNavigationState },
+    });
+    const lists = wrapper.findAll(".overflow-navigation-list");
+    // firstNav (navListVisibility: false) is shown; secondNav (true) is not.
+    expect(lists[0]?.classes()).toContain("visible");
+    expect(lists[1]?.classes()).not.toContain("visible");
+  });
+
+  it("only marks items with config.visible === false as visible in the overflow list", async () => {
+    const wrapper = await mountSuspended(NavigationItems, {
+      props: { mainNavigationState },
+    });
+    const items = wrapper.findAll('[data-group-key="firstNav"].overflow-navigation-item');
+    // Home (visible: true in main nav) should NOT be flagged visible here.
+    const homeItem = items.find((item) => item.text().includes("Home"));
+    expect(homeItem?.classes()).not.toContain("visible");
+    // About (visible: false in main nav) should be flagged visible here.
+    const aboutItem = items.find((item) => item.text().includes("About"));
+    expect(aboutItem?.classes()).toContain("visible");
+  });
+
+  it("renders a plain link for items with a path", async () => {
+    const wrapper = await mountSuspended(NavigationItems, {
+      props: { mainNavigationState },
+    });
+    const link = wrapper.find('a[href="/about"].overflow-navigation-link');
+    expect(link.exists()).toBe(true);
+    expect(link.text()).toBe("About");
+  });
+
+  it("renders an ExpandingPanel dropdown for items with childLinks", async () => {
+    const wrapper = await mountSuspended(NavigationItems, {
+      props: { mainNavigationState },
+    });
+    expect(wrapper.find(".overflow-navigation-details").exists()).toBe(true);
+    expect(wrapper.text()).toContain("UI Components");
+    const subLinks = wrapper.findAll(".overflow-navigation-sub-nav-link");
+    expect(subLinks).toHaveLength(2);
+    expect(subLinks[0]?.text()).toBe("Buttons");
+    expect(subLinks[1]?.text()).toBe("Tabs");
+  });
+
+  it("marks the item matching the current route as active", async () => {
+    const wrapper = await mountSuspended(NavigationItems, {
+      props: { mainNavigationState },
+      route: "/about",
+    });
+    const items = wrapper.findAll(".overflow-navigation-item");
+    const activeItem = items.find((item) => item.find('a[href="/about"]').exists());
+    expect(activeItem?.classes()).toContain("is-active");
+  });
+
+  it("marks a dropdown item active when one of its childLinks matches the current route", async () => {
+    const wrapper = await mountSuspended(NavigationItems, {
+      props: { mainNavigationState },
+      route: "/ui/tabs",
+    });
+    const dropdownItem = wrapper.find(".overflow-navigation-details").element.closest(".overflow-navigation-item");
+    expect(dropdownItem?.className).toContain("is-active");
+  });
+
+  it("sets is-hovered on a plain item on mouseenter", async () => {
+    const wrapper = await mountSuspended(NavigationItems, {
+      props: { mainNavigationState },
+    });
+    const item = wrapper.find('[data-group-key="firstNav"][data-local-index="1"]');
+    await item.trigger("mouseenter");
+    expect(item.classes()).toContain("is-hovered");
+  });
+
+  it("clears is-hovered on wrapper mouseleave", async () => {
+    const wrapper = await mountSuspended(NavigationItems, {
+      props: { mainNavigationState },
+    });
+    const item = wrapper.find('[data-group-key="firstNav"][data-local-index="1"]');
+    await item.trigger("mouseenter");
+    expect(item.classes()).toContain("is-hovered");
+
+    await wrapper.find(".overflow-navigation-wrapper").trigger("mouseleave");
+    expect(item.classes()).not.toContain("is-hovered");
+  });
+
+  it("applies styleClassPassthrough to the root element", async () => {
+    const wrapper = await mountSuspended(NavigationItems, {
+      props: { mainNavigationState, styleClassPassthrough: ["overflow-nav-scope"] },
+    });
+    expect(wrapper.find(".overflow-navigation-wrapper.overflow-nav-scope").exists()).toBe(true);
+  });
+
+  it("falls back to an empty state without throwing when mainNavigationState is omitted", async () => {
+    const wrapper = await mountSuspended(NavigationItems);
+    expect(wrapper.vm).toBeTruthy();
+    expect(wrapper.findAll(".overflow-navigation-item")).toHaveLength(0);
+  });
+
+  it("toggles a dropdown panel open on summary click", async () => {
+    const wrapper = await mountSuspended(NavigationItems, {
+      props: { mainNavigationState },
+    });
+    const details = wrapper.find(".expanding-panel-details");
+    expect(details.attributes("open")).toBeUndefined();
+
+    await wrapper.find(".expanding-panel-summary").trigger("click");
+    await nextTick();
+    expect(details.attributes("open")).toBe("");
+  });
+
+  it("renders correct HTML structure with default props", async () => {
+    const wrapper = await mountSuspended(NavigationItems, {
+      props: { mainNavigationState },
+    });
+    expect(wrapper.html()).toMatchSnapshot();
+  });
+});

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

@@ -0,0 +1,319 @@
+import { describe, it, expect, vi, beforeEach } from "vitest";
+import { mountSuspended } from "@nuxt/test-utils/runtime";
+import { nextTick } from "vue";
+import ResponsiveHeader from "../ResponsiveHeader.vue";
+import type { ResponsiveHeaderProp } from "../../../../types/components";
+
+// ─── ResizeObserver mock ────────────────────────────────────────────────────
+// useResizeObserver (vueuse) only constructs `new ResizeObserver(callback)` and
+// calls `.observe()` — it never invokes the callback itself (that's the native
+// browser's job). This mock captures the callback so tests can trigger the
+// geometry pass manually and deterministically, rather than relying on real
+// layout (jsdom always reports zero-size rects, which is itself a valid,
+// deterministic case exercised below).
+let resizeObserverCallback: ResizeObserverCallback | null = null;
+
+class MockResizeObserver {
+  constructor(cb: ResizeObserverCallback) {
+    resizeObserverCallback = cb;
+  }
+  observe = vi.fn();
+  unobserve = vi.fn();
+  disconnect = vi.fn();
+}
+
+// runGeometryPass's internal chain is pure microtask/Promise-based (updateNavigationConfig
+// resolves immediately; the only real waits are `await nextTick()`) — no real timers
+// involved, so plain nextTick() cycles settle it. Do NOT use @vue/test-utils'
+// flushPromises() here: it schedules its resolve via a real timer internally, which
+// never fires under this repo's global vi.useFakeTimers() and hangs the test.
+const triggerGeometryPass = async () => {
+  resizeObserverCallback?.([] as unknown as ResizeObserverEntry[], {} as ResizeObserver);
+  for (let i = 0; i < 8; i++) {
+    await nextTick();
+  }
+};
+
+const navLinks: ResponsiveHeaderProp = {
+  firstNav: [
+    { name: "Home", path: "/" },
+    { name: "About", path: "/about", iconName: "mdi:home" },
+    {
+      name: "Components",
+      childLinksTitle: "UI Components",
+      childLinks: [
+        { name: "Buttons", path: "/forms/examples/buttons" },
+        { name: "Tabs", path: "/ui/tabs" },
+      ],
+    },
+  ],
+  secondNav: [{ name: "Contact", path: "/contact" }],
+};
+
+describe("ResponsiveHeader", () => {
+  beforeEach(() => {
+    resizeObserverCallback = null;
+    vi.stubGlobal("ResizeObserver", MockResizeObserver);
+  });
+
+  it("mounts without error", async () => {
+    const wrapper = await mountSuspended(ResponsiveHeader, {
+      props: { responsiveNavLinks: navLinks },
+    });
+    expect(wrapper.vm).toBeTruthy();
+  });
+
+  it("renders a plain NuxtLink for items with a path", async () => {
+    const wrapper = await mountSuspended(ResponsiveHeader, {
+      props: { responsiveNavLinks: navLinks },
+    });
+    const link = wrapper.find('a[href="/"]');
+    expect(link.exists()).toBe(true);
+    expect(link.classes()).toContain("main-navigation-link");
+  });
+
+  it("renders a details/summary dropdown for items with childLinks", async () => {
+    const wrapper = await mountSuspended(ResponsiveHeader, {
+      props: { responsiveNavLinks: navLinks },
+    });
+    const summary = wrapper.find(".main-navigation-details-summary");
+    expect(summary.exists()).toBe(true);
+    expect(summary.text()).toContain("UI Components");
+    expect(wrapper.findAll(".main-navigation-sub-nav-link")).toHaveLength(2);
+  });
+
+  it("renders a decorator icon only for items with iconName", async () => {
+    const wrapper = await mountSuspended(ResponsiveHeader, {
+      props: { responsiveNavLinks: navLinks },
+    });
+    const homeLink = wrapper.find('a[href="/"]');
+    const aboutLink = wrapper.find('a[href="/about"]');
+    expect(homeLink.find(".decorator-icon").exists()).toBe(false);
+    expect(aboutLink.find(".decorator-icon").exists()).toBe(true);
+  });
+
+  it("marks the item matching the current route as active", async () => {
+    const wrapper = await mountSuspended(ResponsiveHeader, {
+      props: { responsiveNavLinks: navLinks },
+      route: "/about",
+    });
+    const items = wrapper.findAll(".main-navigation-item");
+    const activeItem = items.find((item) => item.find('a[href="/about"]').exists());
+    expect(activeItem?.classes()).toContain("is-active");
+  });
+
+  it("marks a dropdown item active when one of its childLinks matches the current route", async () => {
+    const wrapper = await mountSuspended(ResponsiveHeader, {
+      props: { responsiveNavLinks: navLinks },
+      route: "/ui/tabs",
+    });
+    const items = wrapper.findAll(".main-navigation-item");
+    const activeItem = items.find((item) => item.find(".main-navigation-details-summary").exists());
+    expect(activeItem?.classes()).toContain("is-active");
+  });
+
+  it("uses default overflow summary icons when not provided", async () => {
+    const wrapper = await mountSuspended(ResponsiveHeader, {
+      props: { responsiveNavLinks: navLinks },
+    });
+    const icons = wrapper.findAll(".overflow-details-summary .icon");
+    expect(icons[0]?.attributes("name") ?? icons[0]?.html()).toBeTruthy();
+    expect(wrapper.html()).toContain("gravity-ui:ellipsis");
+    expect(wrapper.html()).toContain("gravity-ui:bars");
+  });
+
+  it("uses custom overflow summary icons when provided", async () => {
+    const wrapper = await mountSuspended(ResponsiveHeader, {
+      props: {
+        responsiveNavLinks: navLinks,
+        overflowDetailsSummaryIcons: { more: "mdi:dots-horizontal", burger: "mdi:menu" },
+      },
+    });
+    expect(wrapper.html()).toContain("mdi:dots-horizontal");
+    expect(wrapper.html()).toContain("mdi:menu");
+  });
+
+  it("does not render the secondaryNavigation slot when not provided", async () => {
+    const wrapper = await mountSuspended(ResponsiveHeader, {
+      props: { responsiveNavLinks: navLinks },
+    });
+    expect(wrapper.text()).not.toContain("Settings link");
+  });
+
+  it("renders the secondaryNavigation slot when provided", async () => {
+    const wrapper = await mountSuspended(ResponsiveHeader, {
+      props: { responsiveNavLinks: navLinks },
+      slots: { secondaryNavigation: "<span>Settings link</span>" },
+    });
+    expect(wrapper.text()).toContain("Settings link");
+  });
+
+  it("applies styleClassPassthrough to the root element", async () => {
+    const wrapper = await mountSuspended(ResponsiveHeader, {
+      props: { responsiveNavLinks: navLinks, styleClassPassthrough: ["site-header-nav"] },
+    });
+    expect(wrapper.find(".navigation.site-header-nav").exists()).toBe(true);
+  });
+
+  it("toggles a dropdown's open attribute on summary click", async () => {
+    const wrapper = await mountSuspended(ResponsiveHeader, {
+      props: { responsiveNavLinks: navLinks },
+    });
+    const details = wrapper.find(".main-navigation-details");
+    const summary = wrapper.find(".main-navigation-details-summary");
+    expect(details.attributes("open")).toBeUndefined();
+
+    await summary.trigger("click");
+    expect(details.attributes("open")).toBe("");
+
+    await summary.trigger("click");
+    expect(details.attributes("open")).toBeUndefined();
+  });
+
+  it("does not close an open dropdown instantly when a sibling item is only briefly hovered in transit", async () => {
+    const wrapper = await mountSuspended(ResponsiveHeader, {
+      props: { responsiveNavLinks: navLinks },
+    });
+    const details = wrapper.find(".main-navigation-details");
+    await wrapper.find(".main-navigation-details-summary").trigger("click");
+    expect(details.attributes("open")).toBe("");
+
+    const siblingItem = wrapper.find('[data-group-key="firstNav"][data-local-index="0"]');
+    await siblingItem.trigger("mouseenter");
+    // Close is scheduled, not immediate — still open right after the hover.
+    expect(details.attributes("open")).toBe("");
+  });
+
+  it("closes an open dropdown after the hover-intent delay once the cursor moved on", async () => {
+    const wrapper = await mountSuspended(ResponsiveHeader, {
+      props: { responsiveNavLinks: navLinks },
+    });
+    const details = wrapper.find(".main-navigation-details");
+    await wrapper.find(".main-navigation-details-summary").trigger("click");
+    expect(details.attributes("open")).toBe("");
+
+    const siblingItem = wrapper.find('[data-group-key="firstNav"][data-local-index="0"]');
+    await siblingItem.trigger("mouseenter");
+    vi.advanceTimersByTime(200);
+    await nextTick();
+    expect(details.attributes("open")).toBeUndefined();
+  });
+
+  it("cancels the scheduled close when the sub-nav panel itself is reached", async () => {
+    const wrapper = await mountSuspended(ResponsiveHeader, {
+      props: { responsiveNavLinks: navLinks },
+    });
+    const details = wrapper.find(".main-navigation-details");
+    await wrapper.find(".main-navigation-details-summary").trigger("click");
+    expect(details.attributes("open")).toBe("");
+
+    const siblingItem = wrapper.find('[data-group-key="firstNav"][data-local-index="0"]');
+    await siblingItem.trigger("mouseenter");
+    await wrapper.find(".main-navigation-sub-nav").trigger("mouseenter");
+
+    vi.advanceTimersByTime(200);
+    await nextTick();
+    expect(details.attributes("open")).toBe("");
+  });
+
+  // A real mouse click moves focus to the clicked element before the click event
+  // fires — so a click on a summary the mouse already hover-opened dispatches
+  // BOTH a `focusin` (handleSummaryHover) and a `click` (handleSummaryAction) in
+  // quick succession. vue-test-utils' `.trigger("click")` doesn't synthesize that
+  // implicit focus side effect on its own, so these tests fire both events
+  // explicitly to reproduce what a real click actually does.
+  it("closes cleanly (no reopen) when clicking a summary the mouse had just hover-opened", async () => {
+    const wrapper = await mountSuspended(ResponsiveHeader, {
+      props: { responsiveNavLinks: navLinks },
+    });
+    const summary = wrapper.find(".main-navigation-details-summary");
+    const details = wrapper.find(".main-navigation-details");
+
+    await summary.trigger("mouseenter");
+    expect(details.attributes("open")).toBe("");
+
+    // Simulate the real browser sequence a click produces: focus moves first,
+    // then the click event itself fires.
+    await summary.trigger("focusin");
+    await summary.trigger("click");
+
+    expect(details.attributes("open")).toBeUndefined();
+  });
+
+  it("closes cleanly (no reopen) when clicking to close a dropdown switched-to via hovering away from another", async () => {
+    const responsiveNavLinksTwoDropdowns: ResponsiveHeaderProp = {
+      firstNav: [
+        {
+          name: "Components",
+          childLinksTitle: "UI Components",
+          childLinks: [{ name: "Buttons", path: "/forms/examples/buttons" }],
+        },
+        {
+          name: "Layouts",
+          childLinksTitle: "UI Layouts",
+          childLinks: [{ name: "Page Row", path: "/ui/page-row" }],
+        },
+      ],
+    };
+    const wrapper = await mountSuspended(ResponsiveHeader, {
+      props: { responsiveNavLinks: responsiveNavLinksTwoDropdowns },
+    });
+    const summaries = wrapper.findAll(".main-navigation-details-summary");
+    const detailsElements = wrapper.findAll(".main-navigation-details");
+
+    await summaries[0]!.trigger("mouseenter");
+    expect(detailsElements[0]!.attributes("open")).toBe("");
+
+    // Hover away to the second dropdown — closes the first, opens the second.
+    await summaries[1]!.trigger("mouseenter");
+    expect(detailsElements[0]!.attributes("open")).toBeUndefined();
+    expect(detailsElements[1]!.attributes("open")).toBe("");
+
+    await summaries[1]!.trigger("focusin");
+    await summaries[1]!.trigger("click");
+
+    expect(detailsElements[1]!.attributes("open")).toBeUndefined();
+  });
+
+  it("does not auto-open a dropdown on hover when allowExpandOnGesture is false", async () => {
+    const wrapper = await mountSuspended(ResponsiveHeader, {
+      props: { responsiveNavLinks: navLinks, allowExpandOnGesture: false },
+    });
+    const details = wrapper.find(".main-navigation-details");
+    const summary = wrapper.find(".main-navigation-details-summary");
+
+    await summary.trigger("mouseenter");
+    expect(details.attributes("open")).toBeUndefined();
+  });
+
+  it("passes mainNavigationState through to NavigationItems in the overflow panel", async () => {
+    const wrapper = await mountSuspended(ResponsiveHeader, {
+      props: { responsiveNavLinks: navLinks },
+    });
+    const overflowNav = wrapper.find(".overflow-details-nav");
+    expect(overflowNav.exists()).toBe(true);
+    expect(overflowNav.text()).toContain("Home");
+    expect(overflowNav.text()).toContain("UI Components");
+  });
+
+  it("completes the geometry pass and marks all items visually-hidden under jsdom's zero-size layout", async () => {
+    const wrapper = await mountSuspended(ResponsiveHeader, {
+      props: { responsiveNavLinks: navLinks },
+    });
+    await triggerGeometryPass();
+
+    // jsdom reports every rect as 0×0, so `rect.right + margin + gap < wrapperRect.right`
+    // (0 + 0 + 12 < 0) is always false — every item correctly collapses into overflow.
+    expect(wrapper.find(".navigation").classes()).toContain("geometry-ready");
+    const items = wrapper.findAll(".main-navigation-item");
+    expect(items.length).toBeGreaterThan(0);
+    items.forEach((item) => expect(item.classes()).toContain("visually-hidden"));
+  });
+
+  it("renders correct HTML structure with default props", async () => {
+    const wrapper = await mountSuspended(ResponsiveHeader, {
+      props: { responsiveNavLinks: navLinks },
+    });
+    expect(wrapper.html()).toMatchSnapshot();
+  });
+});

package/app/components/03.organisms/responsive-header/tests/__snapshots__/NavigationItems.spec.ts.snap

@@ -0,0 +1,34 @@
+// Vitest Snapshot v1, https://vitest.dev/guide/snapshot.html
+
+exports[`NavigationItems > renders correct HTML structure with default props 1`] = `
+"<div class="overflow-navigation-wrapper" role="menu" aria-label="Overflow navigation menu">
+  <ul class="overflow-navigation-list visible" style="--_overflow-navigation-list-min-width: 0px;" role="none">
+    <li class="overflow-navigation-item is-active" style="--_main-navigation-item-width: 0px;" data-group-key="firstNav" data-local-index="0" role="none"><a href="/" class="overflow-navigation-link" role="menuitem"><span class="overflow-navigation-text">Home</span></a></li>
+    <li class="overflow-navigation-item visible" style="--_main-navigation-item-width: 0px;" data-group-key="firstNav" data-local-index="1" role="none"><a href="/about" class="overflow-navigation-link" role="menuitem"><span class="overflow-navigation-text">About</span></a></li>
+    <li class="overflow-navigation-item visible" style="--_main-navigation-item-width: 0px;" data-group-key="firstNav" data-local-index="2" role="none">
+      <div class="expanding-panel overflow-navigation-details">
+        <details class="expanding-panel-details" name="overflow-navigation-group">
+          <summary id="id-overflow-navigation-group-trigger" class="expanding-panel-summary" aria-controls="id-overflow-navigation-group-content" aria-expanded="false">
+            <div class="label-wrapper"><span class="overflow-navigation-text" aria-label="UI Components submenu" role="menuitem" aria-haspopup="true">UI Components</span></div>
+            <div class="icon-wrapper"><span class="iconify i-mdi:chevron-down icon" aria-hidden="true"></span></div>
+          </summary>
+          <div id="id-overflow-navigation-group-content" class="expanding-panel-content" aria-labelledby="id-overflow-navigation-group-trigger" role="region">
+            <div class="overflow-navigation-sub-nav-inner">
+              <ul class="overflow-navigation-sub-nav-list">
+                <li class="overflow-navigation-sub-nav-item"><a href="/forms/examples/buttons" class="overflow-navigation-sub-nav-link" role="menuitem"><span class="overflow-navigation-sub-nav-text">Buttons</span></a></li>
+                <li class="overflow-navigation-sub-nav-item"><a href="/ui/tabs" class="overflow-navigation-sub-nav-link" role="menuitem"><span class="overflow-navigation-sub-nav-text">Tabs</span></a></li>
+              </ul>
+              <div aria-hidden="true" class="overflow-sub-nav-indicator-hovered"></div>
+            </div>
+          </div>
+        </details>
+      </div>
+    </li>
+  </ul>
+  <ul class="overflow-navigation-list" style="--_overflow-navigation-list-min-width: 0px;" role="none">
+    <li class="overflow-navigation-item" style="--_main-navigation-item-width: 0px;" data-group-key="secondNav" data-local-index="0" role="none"><a href="/contact" class="overflow-navigation-link" role="menuitem"><span class="overflow-navigation-text">Contact</span></a></li>
+  </ul>
+  <div aria-hidden="true" class="overflow-nav-indicator-hovered"></div>
+  <div aria-hidden="true" class="overflow-nav-indicator-active"></div>
+</div>"
+`;

package/app/components/03.organisms/responsive-header/tests/__snapshots__/ResponsiveHeader.spec.ts.snap

@@ -0,0 +1,72 @@
+// Vitest Snapshot v1, https://vitest.dev/guide/snapshot.html
+
+exports[`ResponsiveHeader > renders correct HTML structure with default props 1`] = `
+"<div class="navigation loaded" role="banner">
+  <nav class="main-navigation is-animated" aria-label="Main navigation">
+    <ul class="main-navigation-list">
+      <li class="main-navigation-item visually-hidden is-active" style="--_main-navigation-item-width: 0px;" data-group-key="firstNav" data-local-index="0"><a href="/" class="main-navigation-link">
+          <!--v-if--> Home
+        </a></li>
+      <li class="main-navigation-item visually-hidden" style="--_main-navigation-item-width: 0px;" data-group-key="firstNav" data-local-index="1"><a href="/about" class="main-navigation-link has-icon"><span class="iconify i-mdi:home decorator-icon" aria-hidden="true"></span> About</a></li>
+      <li class="main-navigation-item visually-hidden" style="--_main-navigation-item-width: 0px;" data-group-key="firstNav" data-local-index="2">
+        <details class="main-navigation-details" name="navigation-group">
+          <summary class="main-navigation-details-summary has-toggle-icon" aria-label="UI Components submenu"><span class="iconify i-mdi:chevron-down icon" aria-hidden="true"></span>
+            <!--v-if--> UI Components
+          </summary>
+          <div class="main-navigation-sub-nav" role="menu">
+            <ul class="main-navigation-sub-nav-list">
+              <li class="main-navigation-sub-nav-item"><a href="/forms/examples/buttons" class="main-navigation-sub-nav-link" role="menuitem">Buttons</a></li>
+              <li class="main-navigation-sub-nav-item"><a href="/ui/tabs" class="main-navigation-sub-nav-link" role="menuitem">Tabs</a></li>
+            </ul>
+          </div>
+        </details>
+      </li>
+    </ul>
+    <ul class="main-navigation-list">
+      <li class="main-navigation-item visually-hidden" style="--_main-navigation-item-width: 0px;" data-group-key="secondNav" data-local-index="0"><a href="/contact" class="main-navigation-link">
+          <!--v-if--> Contact
+        </a></li>
+    </ul>
+    <div aria-hidden="true" class="nav-indicator-hovered"></div>
+    <div aria-hidden="true" class="nav-indicator-active"></div>
+  </nav>
+  <nav class="secondary-navigation" aria-label="Secondary navigation">
+    <details class="overflow-details visually-hidden" name="overflow-group">
+      <summary class="overflow-details-summary has-toggle-icon"><span class="iconify i-gravity-ui:ellipsis icon show" aria-hidden="true"></span><span class="iconify i-gravity-ui:bars icon" aria-hidden="true"></span></summary>
+      <div class="overflow-details-nav" role="menu">
+        <div class="overflow-navigation-wrapper" role="menu" aria-label="Overflow navigation menu">
+          <ul class="overflow-navigation-list visible" style="--_overflow-navigation-list-min-width: 0px;" role="none">
+            <li class="overflow-navigation-item visible is-active" style="--_main-navigation-item-width: 0px;" data-group-key="firstNav" data-local-index="0" role="none"><a href="/" class="overflow-navigation-link" role="menuitem"><span class="overflow-navigation-text">Home</span></a></li>
+            <li class="overflow-navigation-item visible" style="--_main-navigation-item-width: 0px;" data-group-key="firstNav" data-local-index="1" role="none"><a href="/about" class="overflow-navigation-link" role="menuitem"><span class="overflow-navigation-text">About</span></a></li>
+            <li class="overflow-navigation-item visible" style="--_main-navigation-item-width: 0px;" data-group-key="firstNav" data-local-index="2" role="none">
+              <div class="expanding-panel overflow-navigation-details">
+                <details class="expanding-panel-details" name="overflow-navigation-group">
+                  <summary id="id-overflow-navigation-group-trigger" class="expanding-panel-summary" aria-controls="id-overflow-navigation-group-content" aria-expanded="false">
+                    <div class="label-wrapper"><span class="overflow-navigation-text" aria-label="UI Components submenu" role="menuitem" aria-haspopup="true">UI Components</span></div>
+                    <div class="icon-wrapper"><span class="iconify i-mdi:chevron-down icon" aria-hidden="true"></span></div>
+                  </summary>
+                  <div id="id-overflow-navigation-group-content" class="expanding-panel-content" aria-labelledby="id-overflow-navigation-group-trigger" role="region">
+                    <div class="overflow-navigation-sub-nav-inner">
+                      <ul class="overflow-navigation-sub-nav-list">
+                        <li class="overflow-navigation-sub-nav-item"><a href="/forms/examples/buttons" class="overflow-navigation-sub-nav-link" role="menuitem"><span class="overflow-navigation-sub-nav-text">Buttons</span></a></li>
+                        <li class="overflow-navigation-sub-nav-item"><a href="/ui/tabs" class="overflow-navigation-sub-nav-link" role="menuitem"><span class="overflow-navigation-sub-nav-text">Tabs</span></a></li>
+                      </ul>
+                      <div aria-hidden="true" class="overflow-sub-nav-indicator-hovered"></div>
+                    </div>
+                  </div>
+                </details>
+              </div>
+            </li>
+          </ul>
+          <ul class="overflow-navigation-list visible" style="--_overflow-navigation-list-min-width: 0px;" role="none">
+            <li class="overflow-navigation-item visible" style="--_main-navigation-item-width: 0px;" data-group-key="secondNav" data-local-index="0" role="none"><a href="/contact" class="overflow-navigation-link" role="menuitem"><span class="overflow-navigation-text">Contact</span></a></li>
+          </ul>
+          <div aria-hidden="true" class="overflow-nav-indicator-hovered"></div>
+          <div aria-hidden="true" class="overflow-nav-indicator-active"></div>
+        </div>
+      </div>
+    </details>
+    <!--v-if-->
+  </nav>
+</div>"
+`;

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

@@ -0,0 +1,60 @@
+# SiteHeader — Consumer Styling Guide
+
+## Public token API
+
+All `--site-header-*` tokens style the outer `.site-header` grid row (branding column + nav
+column). They're the stable override surface — set them at any scope without touching the
+component itself.
+
+| Token | Default | Controls |
+|---|---|---|
+| `--site-header-gap` | `2.4rem` | Gap between the branding column and the nav column |
+| `--site-header-padding-inline` | `2.4rem` | Horizontal padding on `.site-header` |
+| `--site-header-padding-block` | `0px` | Vertical padding on `.site-header` |
+| `--site-header-bg` | `transparent` | Background colour of `.site-header` |
+| `--site-header-position` | `static` | Set to `sticky` to pin the header, paired with `--site-header-sticky-offset` |
+| `--site-header-sticky-offset` | `0px` | `top` offset when `--site-header-position: sticky` |
+| `--site-header-z-index` | `9` | Stacking order of `.site-header` |
+
+`SiteHeader` composes `PageRow` + `SkipLinks` + `ResponsiveHeader` internally. Two separate
+`styleClassPassthrough` props reach the two composed components independently:
+
+- `styleClassPassthrough` → forwarded to the root `PageRow` (targets `--site-header-*` tokens above)
+- `navStyleClassPassthrough` → forwarded to the nested `ResponsiveHeader` (targets its own
+  `--responsive-header-*` and `--overflow-nav-*` tokens — see
+  [../../responsive-header/CONSUMER-STYLING.md](../../responsive-header/CONSUMER-STYLING.md) if present,
+  or the `ResponsiveHeader` skill doc)
+
+---
+
+## Global theming — recommended approach
+
+Create `assets/styles/setup/07.components/site-header.css` in the consuming app and set tokens
+on a scope class matching the one passed via `styleClassPassthrough`:
+
+```css
+/* assets/styles/setup/07.components/site-header.css */
+.header {
+  --site-header-gap: 1.6rem;
+  --site-header-padding-inline: 1.2rem;
+  --site-header-position: sticky;
+  --site-header-bg: #00000095;
+}
+```
+
+```vue
+<SiteHeader :style-class-passthrough="['header']">
+  <template #branding>
+    <NuxtLink to="/" class="brand-link">Brand</NuxtLink>
+  </template>
+</SiteHeader>
+```
+
+---
+
+## Notes
+
+- The branding markup (logo image, wordmark, etc.) is entirely consumer-authored via the
+  `#branding` slot — `SiteHeader` has no opinion on brand styling.
+- `SkipLinks`' hardcoded anchors (`#main-content`, `#footer-content`) expect the consuming
+  layout's main/footer regions to carry those `id`s — unchanged from using `SkipLinks` directly.