srcdev-nuxt-components 9.3.0 → 9.3.1

package/app/components/03.organisms/site-header/SiteHeader.vue

@@ -0,0 +1,96 @@
+<template>
+  <PageRow tag="div" :variant="pageRowVariant" :style-class-passthrough="styleClassPassthrough">
+    <template #default>
+      <header class="site-header">
+        <nav class="home-navigation" aria-label="Home Navigation">
+          <SkipLinks>
+            <template #homeLink>
+              <slot name="branding"></slot>
+            </template>
+          </SkipLinks>
+        </nav>
+        <ResponsiveHeader
+          :responsive-nav-links="responsiveNavLinks"
+          :gap-between-first-and-second-nav="gapBetweenFirstAndSecondNav"
+          :overflow-details-summary-icons="overflowDetailsSummaryIcons"
+          :collapse-breakpoint="collapseBreakpoint"
+          :collapse-at-main-nav-intersection="collapseAtMainNavIntersection"
+          :allow-expand-on-gesture="allowExpandOnGesture"
+          :style-class-passthrough="navStyleClassPassthrough"
+        >
+          <template v-if="slots.secondaryNavigation" #secondaryNavigation>
+            <slot name="secondaryNavigation"></slot>
+          </template>
+        </ResponsiveHeader>
+      </header>
+    </template>
+  </PageRow>
+</template>
+
+<script setup lang="ts">
+import type { ResponsiveHeaderProp } from "../../../types/components";
+import PageRow from "../../01.atoms/page-row/PageRow.vue";
+import SkipLinks from "../../skip-links/SkipLinks.vue";
+import ResponsiveHeader from "../responsive-header/ResponsiveHeader.vue";
+
+interface Props {
+  responsiveNavLinks?: ResponsiveHeaderProp;
+  gapBetweenFirstAndSecondNav?: number;
+  overflowDetailsSummaryIcons?: Record<string, string>;
+  collapseBreakpoint?: number | null;
+  collapseAtMainNavIntersection?: boolean;
+  allowExpandOnGesture?: boolean;
+  pageRowVariant?: "full" | "popout" | "content" | "inset-content";
+  styleClassPassthrough?: string | string[];
+  navStyleClassPassthrough?: string | string[];
+}
+
+withDefaults(defineProps<Props>(), {
+  responsiveNavLinks: () => ({}),
+  gapBetweenFirstAndSecondNav: 12,
+  overflowDetailsSummaryIcons: () => ({
+    more: "gravity-ui:ellipsis",
+    burger: "gravity-ui:bars",
+  }),
+  collapseBreakpoint: null,
+  collapseAtMainNavIntersection: false,
+  allowExpandOnGesture: true,
+  pageRowVariant: "content",
+  styleClassPassthrough: () => [],
+  navStyleClassPassthrough: () => [],
+});
+
+const slots = useSlots();
+</script>
+
+<style lang="css">
+@layer components {
+  /* ─── Public CSS tokens ─────────────────────────────────────────────────
+     Override on the consumer's scope class (via styleClassPassthrough).
+     Nested --responsive-header-* / --overflow-nav-* tokens still apply —
+     forward a scope class via navStyleClassPassthrough to reach them.
+
+     --site-header-gap             (default: 2.4rem)
+     --site-header-padding-inline  (default: 2.4rem)
+     --site-header-padding-block   (default: 0px)
+     --site-header-bg              (default: transparent)
+     --site-header-position        (default: static)
+     --site-header-sticky-offset   (default: 0px)
+     --site-header-z-index         (default: 9)
+  ──────────────────────────────────────────────────────────────────────── */
+
+  .site-header {
+    display: grid;
+    grid-template-columns: auto 1fr;
+    align-items: center;
+    gap: var(--site-header-gap, 2.4rem);
+    padding-block: var(--site-header-padding-block, 0px);
+    padding-inline: var(--site-header-padding-inline, 2.4rem);
+    background-color: var(--site-header-bg, transparent);
+    position: var(--site-header-position, static);
+    top: var(--site-header-sticky-offset, 0px);
+    z-index: var(--site-header-z-index, 9);
+    width: 100%;
+  }
+}
+</style>

package/app/components/03.organisms/site-header/stories/SiteHeader.stories.ts

@@ -0,0 +1,135 @@
+import SiteHeader from "../SiteHeader.vue";
+import type { Meta, StoryObj } from "@nuxtjs/storybook";
+
+const meta: Meta<typeof SiteHeader> = {
+  title: "Organisms/Site Header",
+  component: SiteHeader,
+  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 between the first and second nav groups",
+    },
+    collapseAtMainNavIntersection: {
+      control: "boolean",
+      description: "Collapse the main nav into the overflow burger menu once it no longer fits",
+    },
+    allowExpandOnGesture: {
+      control: "boolean",
+      description: "Allow the collapsed nav to expand on touch/gesture",
+    },
+    pageRowVariant: {
+      control: { type: "radio" },
+      options: ["full", "popout", "content", "inset-content"],
+      description: "Variant forwarded to the root PageRow",
+    },
+    styleClassPassthrough: {
+      control: "object",
+      description: "Extra CSS classes applied to the root PageRow (targets --site-header-* tokens)",
+    },
+    navStyleClassPassthrough: {
+      control: "object",
+      description: "Extra CSS classes applied to the nested ResponsiveHeader (targets its own token API)",
+    },
+  },
+  args: {
+    pageRowVariant: "content",
+    gapBetweenFirstAndSecondNav: 12,
+    collapseAtMainNavIntersection: false,
+    allowExpandOnGesture: true,
+    styleClassPassthrough: [],
+    navStyleClassPassthrough: [],
+  },
+};
+
+export default meta;
+type Story = StoryObj<typeof SiteHeader>;
+
+export const Default: Story = {
+  args: {
+    responsiveNavLinks: {
+      firstNav: [
+        {
+          name: "Components",
+          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: "#" }],
+    },
+  },
+  render: (args) => ({
+    components: { SiteHeader },
+    setup() {
+      return { args };
+    },
+    template: `
+      <SiteHeader v-bind="args">
+        <template #branding>
+          <a href="/" style="color:inherit;text-decoration:none;font-weight:600">Brand</a>
+        </template>
+      </SiteHeader>
+    `,
+  }),
+};
+
+/** A single flat nav group with no dropdowns — the shape a lighter, few-page site would use. */
+export const SimpleFlatNav: Story = {
+  name: "Simple Flat Nav (no dropdowns)",
+  args: {
+    responsiveNavLinks: {
+      main: [
+        { name: "Home", path: "/" },
+        { name: "About", path: "/about" },
+        { name: "Services", path: "/services" },
+        { name: "Contact", path: "/contact" },
+      ],
+    },
+  },
+  render: (args) => ({
+    components: { SiteHeader },
+    setup() {
+      return { args };
+    },
+    template: `
+      <SiteHeader v-bind="args">
+        <template #branding>
+          <a href="/" style="color:inherit;text-decoration:none;font-weight:600">Brand</a>
+        </template>
+      </SiteHeader>
+    `,
+  }),
+};
+
+export const WithSecondaryNavigationSlot: Story = {
+  name: "With secondaryNavigation slot",
+  args: {
+    responsiveNavLinks: {
+      firstNav: [{ name: "Home", path: "/" }],
+    },
+  },
+  render: (args) => ({
+    components: { SiteHeader },
+    setup() {
+      return { args };
+    },
+    template: `
+      <SiteHeader v-bind="args">
+        <template #branding>
+          <a href="/" style="color:inherit;text-decoration:none;font-weight:600">Brand</a>
+        </template>
+        <template #secondaryNavigation>
+          <a href="/settings" aria-label="Settings">⚙</a>
+        </template>
+      </SiteHeader>
+    `,
+  }),
+};

package/app/components/03.organisms/site-header/tests/SiteHeader.spec.ts

@@ -0,0 +1,103 @@
+import { describe, it, expect } from "vitest";
+import { mountSuspended } from "@nuxt/test-utils/runtime";
+import SiteHeader from "../SiteHeader.vue";
+import type { ResponsiveHeaderProp } from "../../../../types/components";
+
+const navLinks: ResponsiveHeaderProp = {
+  firstNav: [{ name: "Home", path: "/" }],
+};
+
+const responsiveHeaderStub = {
+  name: "ResponsiveHeader",
+  props: [
+    "responsiveNavLinks",
+    "gapBetweenFirstAndSecondNav",
+    "overflowDetailsSummaryIcons",
+    "collapseBreakpoint",
+    "collapseAtMainNavIntersection",
+    "allowExpandOnGesture",
+    "styleClassPassthrough",
+  ],
+  template: `<div class="responsive-header-stub"><slot name="secondaryNavigation"></slot></div>`,
+};
+
+describe("SiteHeader", () => {
+  it("mounts without error", async () => {
+    const wrapper = await mountSuspended(SiteHeader, {
+      global: { stubs: { ResponsiveHeader: responsiveHeaderStub } },
+    });
+    expect(wrapper.vm).toBeTruthy();
+  });
+
+  it("renders the branding slot inside SkipLinks' homeLink slot", async () => {
+    const wrapper = await mountSuspended(SiteHeader, {
+      slots: { branding: "<a href='/' class='brand-link'>Brand</a>" },
+      global: { stubs: { ResponsiveHeader: responsiveHeaderStub } },
+    });
+    expect(wrapper.find(".home-link .brand-link").exists()).toBe(true);
+  });
+
+  it("does not render the secondaryNavigation slot when not provided", async () => {
+    const wrapper = await mountSuspended(SiteHeader, {
+      global: { stubs: { ResponsiveHeader: responsiveHeaderStub } },
+    });
+    expect(wrapper.text()).not.toContain("Extra nav");
+  });
+
+  it("forwards the secondaryNavigation slot through to ResponsiveHeader", async () => {
+    const wrapper = await mountSuspended(SiteHeader, {
+      slots: { secondaryNavigation: "<span>Extra nav</span>" },
+      global: { stubs: { ResponsiveHeader: responsiveHeaderStub } },
+    });
+    expect(wrapper.text()).toContain("Extra nav");
+  });
+
+  it("forwards responsiveNavLinks and other nav props to ResponsiveHeader", async () => {
+    const wrapper = await mountSuspended(SiteHeader, {
+      props: {
+        responsiveNavLinks: navLinks,
+        gapBetweenFirstAndSecondNav: 24,
+        collapseAtMainNavIntersection: true,
+        allowExpandOnGesture: false,
+        navStyleClassPassthrough: ["site-header-nav"],
+      },
+      global: { stubs: { ResponsiveHeader: responsiveHeaderStub } },
+    });
+    const responsiveHeader = wrapper.findComponent(responsiveHeaderStub);
+    expect(responsiveHeader.props("responsiveNavLinks")).toEqual(navLinks);
+    expect(responsiveHeader.props("gapBetweenFirstAndSecondNav")).toBe(24);
+    expect(responsiveHeader.props("collapseAtMainNavIntersection")).toBe(true);
+    expect(responsiveHeader.props("allowExpandOnGesture")).toBe(false);
+    expect(responsiveHeader.props("styleClassPassthrough")).toEqual(["site-header-nav"]);
+  });
+
+  it("passes pageRowVariant through to the root PageRow", async () => {
+    const wrapper = await mountSuspended(SiteHeader, {
+      props: { pageRowVariant: "full" },
+      global: { stubs: { ResponsiveHeader: responsiveHeaderStub } },
+    });
+    expect(wrapper.find(".page-row.full").exists()).toBe(true);
+  });
+
+  it("defaults pageRowVariant to content", async () => {
+    const wrapper = await mountSuspended(SiteHeader, {
+      global: { stubs: { ResponsiveHeader: responsiveHeaderStub } },
+    });
+    expect(wrapper.find(".page-row.content").exists()).toBe(true);
+  });
+
+  it("applies styleClassPassthrough to the root PageRow", async () => {
+    const wrapper = await mountSuspended(SiteHeader, {
+      props: { styleClassPassthrough: ["header"] },
+      global: { stubs: { ResponsiveHeader: responsiveHeaderStub } },
+    });
+    expect(wrapper.find(".page-row.header").exists()).toBe(true);
+  });
+
+  it("renders correct HTML structure with default props", async () => {
+    const wrapper = await mountSuspended(SiteHeader, {
+      global: { stubs: { ResponsiveHeader: responsiveHeaderStub } },
+    });
+    expect(wrapper.html()).toMatchSnapshot();
+  });
+});

package/app/components/03.organisms/site-header/tests/__snapshots__/SiteHeader.spec.ts.snap

@@ -0,0 +1,15 @@
+// Vitest Snapshot v1, https://vitest.dev/guide/snapshot.html
+
+exports[`SiteHeader > renders correct HTML structure with default props 1`] = `
+"<div class="page-row content">
+  <header class="site-header">
+    <nav class="home-navigation" aria-label="Home Navigation">
+      <div class="home-link-navigation">
+        <div class="home-link"></div>
+        <nav class="skip-links-nav" aria-label="Skip navigation"><a href="#main-content" class="skip-link">Skip to main content</a><a href="#footer-content" class="skip-link">Skip to footer</a></nav>
+      </div>
+    </nav>
+    <div class="responsive-header-stub"></div>
+  </header>
+</div>"
+`;

package/app/layouts/default.vue

@@ -1,43 +1,35 @@
 <template>
   <div class="page-layout">
-    <PageRow tag="div" variant="full" :style-class-passthrough="['header']">
-      <template #default>
-        <header class="responsive-header">
-          <nav class="home-navigation" aria-label="Home Navigation">
-            <SkipLinks>
-              <template #homeLink>
-                <NuxtLink to="/" class="home-link">
-                  SRCDEV
-                  <span>components</span>
-                </NuxtLink>
-              </template>
-            </SkipLinks>
-          </nav>
-          <ResponsiveHeader
-            :responsive-nav-links
-            :gap-between-first-and-second-nav="12"
-            :style-class-passthrough="['site-header-nav']"
-            :overflow-details-summary-icons="{
-              more: 'gravity-ui:ellipsis',
-              burger: 'gravity-ui:bars',
-            }"
-            :collapse-at-main-nav-intersection="false"
-            :allow-expand-on-gesture="false"
-          >
-            <template #secondaryNavigation>
-              <ul class="secondary-navigation-list">
-                <li class="secondary-navigation-item">
-                  <NuxtLink class="secondary-navigation-link" to="/">
-                    <Icon name="material-symbols:settings-outline-rounded" class="icon" aria-hidden="true" />
-                    <span class="sr-only">Settings</span>
-                  </NuxtLink>
-                </li>
-              </ul>
-            </template>
-          </ResponsiveHeader>
-        </header>
+    <SiteHeader
+      :responsive-nav-links
+      :gap-between-first-and-second-nav="12"
+      page-row-variant="full"
+      :style-class-passthrough="['header']"
+      :nav-style-class-passthrough="['site-header-nav']"
+      :overflow-details-summary-icons="{
+        more: 'gravity-ui:ellipsis',
+        burger: 'gravity-ui:bars',
+      }"
+      :collapse-at-main-nav-intersection="false"
+      :allow-expand-on-gesture="false"
+    >
+      <template #branding>
+        <NuxtLink to="/" class="home-link">
+          SRCDEV
+          <span>components</span>
+        </NuxtLink>
       </template>
-    </PageRow>
+      <template #secondaryNavigation>
+        <ul class="secondary-navigation-list">
+          <li class="secondary-navigation-item">
+            <NuxtLink class="secondary-navigation-link" to="/">
+              <Icon name="material-symbols:settings-outline-rounded" class="icon" aria-hidden="true" />
+              <span class="sr-only">Settings</span>
+            </NuxtLink>
+          </li>
+        </ul>
+      </template>
+    </SiteHeader>
     <PageRow id="main-content" class="main-content" tag="main" variant="full" :is-landmark="true">
       <template #default>
         <slot name="layout-content">Page content goes here</slot>
@@ -231,39 +223,31 @@ onMounted(() => {
 
   width: 100%;
 
-  .responsive-header {
-    display: grid;
-    grid-template-columns: auto 1fr;
-    gap: 24px;
-    align-items: center;
-    padding-block: 0;
-    padding-inline: 24px;
-    background-color: #000;
+  /* SiteHeader token overrides — see .claude/skills/components/site-header.md */
+  --site-header-gap: 2.4rem;
+  --site-header-padding-inline: 2.4rem;
+  --site-header-bg: #000;
+  --site-header-position: relative;
+  --site-header-z-index: 9;
 
-    position: relative;
-    z-index: 9;
+  .home-link {
+    display: flex;
+    flex-direction: column;
+    text-wrap-mode: nowrap;
+    font-size: var(--step-5);
+    letter-spacing: 0.2em;
+    color: var(--slate-00);
+    text-decoration: none;
 
-    width: 100%;
-
-    .home-link {
-      display: flex;
-      flex-direction: column;
-      text-wrap-mode: nowrap;
-      font-size: var(--step-5);
-      letter-spacing: 0.2em;
-      color: var(--slate-00);
-      text-decoration: none;
-
-      span {
-        font-size: var(--step-3);
-        letter-spacing: initial;
-      }
+    span {
+      font-size: var(--step-3);
+      letter-spacing: initial;
+    }
 
-      &:hover {
-        border-radius: 0.4rem;
-        outline: 2px solid var(--green-08);
-        outline-offset: 0.4rem;
-      }
+    &:hover {
+      border-radius: 0.4rem;
+      outline: 2px solid var(--green-08);
+      outline-offset: 0.4rem;
     }
   }
 }
@@ -282,6 +266,19 @@ onMounted(() => {
   --responsive-header-color: var(--slate-00);
   --responsive-header-link-color: var(--slate-00);
 
+  /* Fixed (non-fluid) nav-link font-size — deliberately NOT var(--step-*).
+     A vw-based clamp() here drifts with the scrollbar (see
+     ResponsiveHeader.vue's token comment) without ever re-triggering the
+     overflow-collapse ResizeObserver, silently letting one extra item fit
+     that shouldn't. Values TBC after a visual pass. */
+  --responsive-header-link-font-size: 1.2rem;
+  @media (min-width: 768px) {
+    --responsive-header-link-font-size: 1.4rem;
+  }
+  @media (min-width: 1024px) {
+    --responsive-header-link-font-size: 1.5rem;
+  }
+
   --responsive-header-sub-nav-bg: #000;
   --responsive-header-sub-nav-border: 1px solid #efefef75;
 

package/package.json

@@ -1,10 +1,13 @@
 {
   "name": "srcdev-nuxt-components",
   "type": "module",
-  "version": "9.3.0",
+  "version": "9.3.1",
   "main": "nuxt.config.ts",
   "types": "types.d.ts",
   "license": "MIT",
+  "engines": {
+    "node": ">=24.0.0"
+  },
   "scripts": {
     "postinstall": "node scripts/copy-snippets.mjs",
     "clean": "rm -rf .nuxt && rm -rf .output",