srcdev-nuxt-components 9.1.46 → 9.1.48

package/.claude/skills/components/scroll-reveal-image.md

@@ -24,6 +24,7 @@ For arbitrary slot content — a grid of images, video, markup — use `ScrollRe
 | `parallaxOffset` | `string` | `"36rem"` | Distance the image travels vertically across the full scroll range. Larger = more dramatic reveal. |
 | `focalX` | `string` | `"50%"` | Horizontal focal point — CSS `object-position` x-axis value. Controls which horizontal slice stays in view. |
 | `radius` | `string` | `"0px"` | `border-radius` applied to the clipping frame. |
+| `loading` | `"lazy" \| "eager"` | `"lazy"` | Image loading strategy. Use `"eager"` if this is the LCP image (e.g. partially in view on load). |
 | `styleClassPassthrough` | `string \| string[]` | `[]` | Extra classes applied to the root `<figure>`. |
 
 ## Basic usage
@@ -157,7 +158,7 @@ See `scroll-reveal-frame.md` for the full guide. For portrait images the default
 ## Notes
 
 - The root `<figure>` has `margin: 0` set in the component — browser default `<figure>` margins are neutralised at source.
-- `loading="lazy"` and `decoding="async"` are hardcoded on the `<img>`. If this component is the LCP image, override with `loading="eager"` via a CSS-only approach is not possible — use `ScrollRevealFrame` with a manual `NuxtImg` instead and set `:loading="'eager'"`.
+- `decoding="async"` is always set on the `<img>`. Use `:loading="'eager'"` if this component is the LCP image (e.g. a hero partially in view on load) — the default `"lazy"` is correct for below-fold usage.
 - Do not place inside a container with `overflow: hidden` or `overflow: clip` — breaks the `view-timeline` scroll detection inherited from `ScrollRevealFrame`.
 - Reduced-motion: animation is disabled and the image falls back to a static crop centred at `object-position: <focalX> 50%`.
 - Storybook: the `"none"` image provider is active (`nuxt.config.ts`), so `src` paths pass through unchanged. Always provide explicit `img-width` and `img-height` props to avoid the `w=1536` fallback in deployed Storybook.

package/.claude/skills/composable-anchor-scroll.md

@@ -0,0 +1,211 @@
+# useAnchorScroll Composable
+
+## Overview
+
+`useAnchorScroll` intercepts `#hash` link clicks and smooth-scrolls to the target element.
+Routes and external links pass through untouched, so the same handler is safe to attach to
+every navigation link without conditional logic in the template.
+
+Respects `prefers-reduced-motion` — when the user opts out of motion, `handleNavClick` returns
+early without calling `preventDefault`, leaving the browser's native anchor jump intact.
+
+**Ships inside the `srcdev-nuxt-components` layer** (`app/composables/useAnchorScroll.ts`).
+Auto-imported by Nuxt — **do not create a local copy**.
+
+---
+
+## API reference
+
+### Options
+
+| Option | Type | Default | Description |
+|---|---|---|---|
+| `offset` | `number \| (() => number)` | `0` | Pixels subtracted from the final scroll position. Pass a getter function to read a sticky element's height at scroll time rather than at composable init. |
+
+### Returns
+
+| Name | Type | Description |
+|---|---|---|
+| `handleNavClick` | `(event: MouseEvent, href: string) => void` | Attach to click handlers. No-ops silently for non-`#` hrefs — safe on all links. |
+| `scrollToAnchor` | `(hash: string) => void` | Scroll programmatically. Accepts `"#section"` or `"section"`. Respects motion preference and offset. |
+
+---
+
+## Usage patterns
+
+### 1. TabNavigation with anchor links (no extra code needed)
+
+`TabNavigation` has `useAnchorScroll` wired up internally. Pass anchor hrefs in
+`navItemData.main` and smooth scrolling works automatically.
+
+```ts
+const navItemData = {
+  main: [
+    { text: "About",    href: "#about" },
+    { text: "Services", href: "#services" },
+    { text: "Contact",  href: "#contact" },
+    { text: "Blog",     href: "/blog" },  // route — NuxtLink handles as normal
+  ],
+};
+```
+
+```vue
+<TabNavigation :nav-item-data="navItemData" />
+```
+
+No offset is applied here. If your site header is fixed/sticky and obscures section headings,
+use pattern 2 below to build a custom nav with an explicit offset.
+
+---
+
+### 2. Sticky section nav with dynamic offset
+
+The most common single-page pattern: a sticky bar at the top of the content area, where
+each link scrolls to a section below it. Pass a getter for `offset` so the bar's live height
+is read at scroll time — this stays correct if the bar resizes (e.g. on viewport changes).
+
+```ts
+const stickyNavRef = ref<HTMLElement | null>(null);
+
+const { handleNavClick } = useAnchorScroll({
+  offset: () => stickyNavRef.value?.offsetHeight ?? 0,
+});
+```
+
+```vue
+<nav ref="stickyNavRef" class="sticky-section-nav">
+  <a href="#overview" @click="(e) => handleNavClick(e, '#overview')">Overview</a>
+  <a href="#pricing"  @click="(e) => handleNavClick(e, '#pricing')">Pricing</a>
+  <a href="#contact"  @click="(e) => handleNavClick(e, '#contact')">Contact</a>
+</nav>
+
+<section id="overview">…</section>
+<section id="pricing">…</section>
+<section id="contact">…</section>
+```
+
+CSS to make the nav sticky:
+
+```css
+.sticky-section-nav {
+  position: sticky;
+  top: 0;
+  z-index: 5;
+}
+```
+
+---
+
+### 3. Terms / long-form page with sidebar nav
+
+Same pattern as above — useful for terms, privacy policy, or documentation pages where a
+sidebar links to in-document sections.
+
+```ts
+const { handleNavClick } = useAnchorScroll({ offset: 24 }); // fixed header height
+```
+
+```vue
+<aside class="terms-sidebar">
+  <nav>
+    <a v-for="section in termsSections" :key="section.id"
+       :href="`#${section.id}`"
+       @click="(e) => handleNavClick(e, `#${section.id}`)">
+      {{ section.title }}
+    </a>
+  </nav>
+</aside>
+
+<article>
+  <section v-for="section in termsSections" :key="section.id" :id="section.id">
+    <h2>{{ section.title }}</h2>
+    <p>{{ section.body }}</p>
+  </section>
+</article>
+```
+
+---
+
+### 4. Programmatic scroll (no click event)
+
+Use `scrollToAnchor` to scroll without a click — after a form submission, on route entry, or
+from any imperative call.
+
+```ts
+const { scrollToAnchor } = useAnchorScroll({ offset: 64 });
+```
+
+```ts
+// Scroll to a section after successful form submit
+const handleSubmit = async () => {
+  await submitForm();
+  scrollToAnchor("#confirmation");
+};
+```
+
+```ts
+// Scroll to the current URL hash on mount
+const route = useRoute();
+
+onMounted(() => {
+  if (route.hash) scrollToAnchor(route.hash);
+});
+```
+
+---
+
+## How offset works
+
+Without `offset`, the composable calls `el.scrollIntoView({ behavior, block: "start" })` —
+the element's top edge aligns with the viewport top.
+
+With `offset`, it uses `window.scrollTo` with a calculated position:
+
+```
+top = el.getBoundingClientRect().top + window.scrollY - offset
+```
+
+This shifts the final resting position downward by `offset` pixels, so a sticky bar of that
+height does not overlap the section heading.
+
+**Use a getter when the bar can resize:**
+
+```ts
+// ✅ Read height at click time
+const { handleNavClick } = useAnchorScroll({
+  offset: () => navRef.value?.offsetHeight ?? 0,
+});
+
+// ✗ Captured at init — stale if the bar changes height later
+const { handleNavClick } = useAnchorScroll({
+  offset: navRef.value?.offsetHeight ?? 0,
+});
+```
+
+---
+
+## Reduced motion behaviour
+
+When `window.matchMedia("(prefers-reduced-motion: reduce)").matches` is `true`:
+
+- **`handleNavClick`** — returns early without calling `preventDefault`. The browser or Vue
+  Router handles the anchor jump natively (instant, no scroll animation).
+- **`scrollToAnchor`** — uses `behavior: "instant"` instead of `"smooth"`.
+
+No configuration needed — the check happens at call time, so toggling the OS preference mid-session
+takes effect immediately on the next click.
+
+---
+
+## Notes
+
+- **`history.pushState`** — `handleNavClick` pushes the hash into the URL so the back button and
+  deep links work correctly. This runs after `preventDefault` stops Vue Router from navigating,
+  so the URL stays in sync without triggering a router scroll.
+- **Non-existent targets** — if no element matches the hash, `scrollToAnchor` silently returns.
+  No error is thrown, so attaching the handler to all links is safe even when some are routes or
+  the target section isn't on the current page.
+- **SSR** — both `handleNavClick` and `scrollToAnchor` guard with `import.meta.server` and return
+  early. No special SSR setup is needed.
+- **Multiple instances** — each call to `useAnchorScroll` is independent. You can run a sticky
+  section nav alongside a `TabNavigation` on the same page with different offsets.

package/.claude/skills/index.md

@@ -49,6 +49,7 @@ Each skill is a single markdown file named `<area>-<task>.md`.
 ├── composable-zod-validation.md      — useZodValidation: schema-driven form validation, error binding, submit flow, API error push
 ├── composable-colour-scheme.md       — useColourScheme: reactive light/dark/auto switching, localStorage persistence, runtime config
 ├── composable-dialog-controls.md     — useDialogControls: named dialog open/close state with confirm/cancel callbacks
+├── composable-anchor-scroll.md       — useAnchorScroll: smooth anchor scrolling with reduced-motion support, dynamic offset, and TabNavigation integration
 ├── composable-tooltips-guide.md      — useTooltipsGuide: sequential popover guide with auto-start, dismiss-to-advance, manual controls
 └── components/
     ├── accordian-core.md       — AccordianCore indexed dynamic slots (accordian-{n}-summary/icon/content), exclusive-open grouping

package/app/components/01.atoms/animations/scroll-reveal-image/ScrollRevealImage.vue

@@ -12,7 +12,7 @@
       :alt="alt"
       :width="imgWidth"
       :height="imgHeight"
-      loading="lazy"
+      :loading="loading"
       decoding="async"
     />
   </ScrollRevealFrame>
@@ -51,6 +51,7 @@ interface Props {
   focalX?: string;
   /** Optional rounded corners on the frame. */
   radius?: string;
+  loading?: "lazy" | "eager";
   styleClassPassthrough?: string | string[];
 }
 
@@ -62,6 +63,7 @@ withDefaults(defineProps<Props>(), {
   parallaxOffset: "36rem",
   focalX: "50%",
   radius: "0px",
+  loading: "lazy",
   styleClassPassthrough: () => [],
 });
 </script>

package/app/components/01.atoms/animations/scroll-reveal-image/tests/ScrollRevealImage.spec.ts

@@ -32,6 +32,7 @@ describe("ScrollRevealImage", () => {
         parallaxOffset: "20rem",
         focalX: "30%",
         radius: "1.6rem",
+        loading: "eager",
         styleClassPassthrough: ["custom-class"],
       },
     });
@@ -179,13 +180,20 @@ describe("ScrollRevealImage", () => {
     expect(img.attributes("height")).toBe("1920");
   });
 
-  it("sets loading=lazy on the image element", async () => {
+  it("sets loading=lazy on the image element by default", async () => {
     const wrapper = await mountSuspended(ScrollRevealImage, {
       props: { src: "/images/test.jpg" },
     });
     expect(wrapper.find("img[data-nuxt-img]").attributes("loading")).toBe("lazy");
   });
 
+  it("passes loading=eager to the image element when set", async () => {
+    const wrapper = await mountSuspended(ScrollRevealImage, {
+      props: { src: "/images/test.jpg", loading: "eager" },
+    });
+    expect(wrapper.find("img[data-nuxt-img]").attributes("loading")).toBe("eager");
+  });
+
   it("sets decoding=async on the image element", async () => {
     const wrapper = await mountSuspended(ScrollRevealImage, {
       props: { src: "/images/test.jpg" },

package/app/components/01.atoms/animations/scroll-reveal-image/tests/__snapshots__/ScrollRevealImage.spec.ts.snap

@@ -2,7 +2,7 @@
 
 exports[`ScrollRevealImage > renders correct HTML structure (all props set) 1`] = `
 "<figure class="reveal-frame custom-class" style="--_frame-height: 400px; --_parallax-offset: 20rem; --_radius: 1.6rem; --_focal-x: 30%;">
-  <div class="reveal-content"><img width="800" height="600" data-nuxt-img="" srcset="/_ipx/s_800x600/images/test.jpg 1x, /_ipx/s_1600x1200/images/test.jpg 2x" class="reveal-image" alt="All props" loading="lazy" decoding="async" src="/_ipx/s_800x600/images/test.jpg"></div>
+  <div class="reveal-content"><img width="800" height="600" data-nuxt-img="" srcset="/_ipx/s_800x600/images/test.jpg 1x, /_ipx/s_1600x1200/images/test.jpg 2x" class="reveal-image" alt="All props" loading="eager" decoding="async" src="/_ipx/s_800x600/images/test.jpg"></div>
 </figure>"
 `;
 

package/app/components/02.molecules/navigation/tab-navigation/TabNavigation.vue

@@ -27,6 +27,7 @@
           :external="item.isExternal || undefined"
           class="tab-nav-link"
           data-nav-item
+          @click="(e) => item.href && handleNavClick(e, item.href)"
         >
           <Icon v-if="item.iconName" :name="item.iconName" aria-hidden="true" />
           {{ item.text }}
@@ -77,7 +78,7 @@
               :href="item.href"
               :external="item.isExternal || undefined"
               class="tab-nav-panel-link"
-              @click="closeMenu"
+              @click="(e) => { item.href && handleNavClick(e, item.href); closeMenu(); }"
             >
               <Icon v-if="item.iconName" :name="item.iconName" aria-hidden="true" />
               {{ item.text }}
@@ -106,6 +107,8 @@ const props = withDefaults(defineProps<Props>(), {
 const { navRef, navListRef, isCollapsed, isLoaded, isMenuOpen, isActiveItem, toggleMenu, closeMenu } =
   useNavCollapse("tab-nav-loaded");
 
+const { handleNavClick } = useAnchorScroll();
+
 // ─── Animation gate — disables indicator transitions during route changes ────
 // Starts true: CSS anchor positioning resolves before first paint so there is
 // no previous position to animate from on initial render.

package/app/components/02.molecules/profile-section/ProfileSection.vue

@@ -100,11 +100,6 @@ watch(
       }
 
       .profile-info {
-        display: flex;
-        flex-direction: column;
-        gap: 1.5rem;
-        height: stretch;
-
         .profile-info-content {
           .profile-info-block {
             margin-block-end: 1.5rem;

package/app/composables/tests/useAnchorScroll.spec.ts

@@ -0,0 +1,216 @@
+import { describe, it, expect, vi, beforeEach, afterEach } from "vitest";
+import { useAnchorScroll } from "../useAnchorScroll";
+
+const stubMatchMedia = (prefersReducedMotion: boolean) => {
+  vi.stubGlobal("matchMedia", vi.fn().mockReturnValue({ matches: prefersReducedMotion }));
+};
+
+const makeEvent = (): MouseEvent => {
+  const e = new MouseEvent("click");
+  vi.spyOn(e, "preventDefault");
+  return e;
+};
+
+const appendEl = (id: string): HTMLElement => {
+  const el = document.createElement("div");
+  el.id = id;
+  document.body.appendChild(el);
+  return el;
+};
+
+describe("useAnchorScroll", () => {
+  beforeEach(() => {
+    document.body.innerHTML = "";
+    stubMatchMedia(false);
+    vi.stubGlobal("scrollTo", vi.fn());
+    vi.spyOn(history, "pushState").mockImplementation(() => {});
+  });
+
+  afterEach(() => {
+    vi.restoreAllMocks();
+  });
+
+  // ─── handleNavClick ───────────────────────────────────────────────────────
+
+  describe("handleNavClick", () => {
+    describe("non-anchor hrefs", () => {
+      it("does nothing for a route href", () => {
+        const { handleNavClick } = useAnchorScroll();
+        const e = makeEvent();
+        handleNavClick(e, "/about");
+        expect(e.preventDefault).not.toHaveBeenCalled();
+        expect(history.pushState).not.toHaveBeenCalled();
+      });
+
+      it("does nothing for an external URL", () => {
+        const { handleNavClick } = useAnchorScroll();
+        const e = makeEvent();
+        handleNavClick(e, "https://example.com");
+        expect(e.preventDefault).not.toHaveBeenCalled();
+      });
+
+      it("does nothing for an empty string", () => {
+        const { handleNavClick } = useAnchorScroll();
+        const e = makeEvent();
+        handleNavClick(e, "");
+        expect(e.preventDefault).not.toHaveBeenCalled();
+      });
+    });
+
+    describe("prefers-reduced-motion active", () => {
+      it("does not call preventDefault", () => {
+        stubMatchMedia(true);
+        appendEl("overview");
+        const { handleNavClick } = useAnchorScroll();
+        const e = makeEvent();
+        handleNavClick(e, "#overview");
+        expect(e.preventDefault).not.toHaveBeenCalled();
+      });
+
+      it("does not push state", () => {
+        stubMatchMedia(true);
+        appendEl("overview");
+        const { handleNavClick } = useAnchorScroll();
+        handleNavClick(makeEvent(), "#overview");
+        expect(history.pushState).not.toHaveBeenCalled();
+      });
+
+      it("does not scroll", () => {
+        stubMatchMedia(true);
+        const el = appendEl("overview");
+        el.scrollIntoView = vi.fn();
+        const { handleNavClick } = useAnchorScroll();
+        handleNavClick(makeEvent(), "#overview");
+        expect(el.scrollIntoView).not.toHaveBeenCalled();
+        expect(window.scrollTo).not.toHaveBeenCalled();
+      });
+    });
+
+    describe("anchor href, no reduced-motion", () => {
+      it("calls preventDefault", () => {
+        appendEl("overview");
+        const { handleNavClick } = useAnchorScroll();
+        const e = makeEvent();
+        handleNavClick(e, "#overview");
+        expect(e.preventDefault).toHaveBeenCalled();
+      });
+
+      it("pushes the hash into history", () => {
+        appendEl("overview");
+        const { handleNavClick } = useAnchorScroll();
+        handleNavClick(makeEvent(), "#overview");
+        expect(history.pushState).toHaveBeenCalledWith(null, "", "#overview");
+      });
+
+      it("does nothing when target element does not exist", () => {
+        const { handleNavClick } = useAnchorScroll();
+        expect(() => handleNavClick(makeEvent(), "#nonexistent")).not.toThrow();
+        expect(window.scrollTo).not.toHaveBeenCalled();
+      });
+
+      it("scrolls to the element", () => {
+        const el = appendEl("overview");
+        el.scrollIntoView = vi.fn();
+        const { handleNavClick } = useAnchorScroll();
+        handleNavClick(makeEvent(), "#overview");
+        expect(el.scrollIntoView).toHaveBeenCalledWith({ behavior: "smooth", block: "start" });
+      });
+    });
+  });
+
+  // ─── scrollToAnchor ───────────────────────────────────────────────────────
+
+  describe("scrollToAnchor", () => {
+    describe("element lookup", () => {
+      it("accepts a hash with leading #", () => {
+        const el = appendEl("section");
+        el.scrollIntoView = vi.fn();
+        const { scrollToAnchor } = useAnchorScroll();
+        scrollToAnchor("#section");
+        expect(el.scrollIntoView).toHaveBeenCalled();
+      });
+
+      it("accepts a hash without leading #", () => {
+        const el = appendEl("section");
+        el.scrollIntoView = vi.fn();
+        const { scrollToAnchor } = useAnchorScroll();
+        scrollToAnchor("section");
+        expect(el.scrollIntoView).toHaveBeenCalled();
+      });
+
+      it("does nothing when no element matches", () => {
+        const { scrollToAnchor } = useAnchorScroll();
+        expect(() => scrollToAnchor("#ghost")).not.toThrow();
+        expect(window.scrollTo).not.toHaveBeenCalled();
+      });
+    });
+
+    describe("no offset", () => {
+      it("uses scrollIntoView with smooth behavior", () => {
+        const el = appendEl("target");
+        el.scrollIntoView = vi.fn();
+        const { scrollToAnchor } = useAnchorScroll();
+        scrollToAnchor("#target");
+        expect(el.scrollIntoView).toHaveBeenCalledWith({ behavior: "smooth", block: "start" });
+      });
+
+      it("uses instant behavior when prefers-reduced-motion is active", () => {
+        stubMatchMedia(true);
+        const el = appendEl("target");
+        el.scrollIntoView = vi.fn();
+        const { scrollToAnchor } = useAnchorScroll();
+        scrollToAnchor("#target");
+        expect(el.scrollIntoView).toHaveBeenCalledWith({ behavior: "instant", block: "start" });
+      });
+    });
+
+    describe("numeric offset", () => {
+      it("uses window.scrollTo with the offset subtracted", () => {
+        const el = appendEl("target");
+        vi.spyOn(el, "getBoundingClientRect").mockReturnValue({ top: 300 } as DOMRect);
+        const { scrollToAnchor } = useAnchorScroll({ offset: 80 });
+        scrollToAnchor("#target");
+        // top: el.top + scrollY - offset = 300 + 0 - 80
+        expect(window.scrollTo).toHaveBeenCalledWith({ top: 220, behavior: "smooth" });
+      });
+
+      it("uses instant behavior when prefers-reduced-motion is active", () => {
+        stubMatchMedia(true);
+        const el = appendEl("target");
+        vi.spyOn(el, "getBoundingClientRect").mockReturnValue({ top: 300 } as DOMRect);
+        const { scrollToAnchor } = useAnchorScroll({ offset: 80 });
+        scrollToAnchor("#target");
+        expect(window.scrollTo).toHaveBeenCalledWith({ top: 220, behavior: "instant" });
+      });
+    });
+
+    describe("getter offset", () => {
+      it("calls the getter at scroll time, not at composable init", () => {
+        const el = appendEl("target");
+        vi.spyOn(el, "getBoundingClientRect").mockReturnValue({ top: 0 } as DOMRect);
+
+        let liveOffset = 0;
+        const { scrollToAnchor } = useAnchorScroll({ offset: () => liveOffset });
+
+        liveOffset = 60;
+        scrollToAnchor("#target");
+        expect(window.scrollTo).toHaveBeenCalledWith({ top: -60, behavior: "smooth" });
+      });
+
+      it("re-reads the getter on each call", () => {
+        const el = appendEl("target");
+        vi.spyOn(el, "getBoundingClientRect").mockReturnValue({ top: 100 } as DOMRect);
+
+        let liveOffset = 40;
+        const { scrollToAnchor } = useAnchorScroll({ offset: () => liveOffset });
+
+        scrollToAnchor("#target");
+        expect(window.scrollTo).toHaveBeenLastCalledWith({ top: 60, behavior: "smooth" });
+
+        liveOffset = 70;
+        scrollToAnchor("#target");
+        expect(window.scrollTo).toHaveBeenLastCalledWith({ top: 30, behavior: "smooth" });
+      });
+    });
+  });
+});

package/app/composables/useAnchorScroll.ts

@@ -0,0 +1,46 @@
+interface UseAnchorScrollOptions {
+  offset?: number | (() => number);
+}
+
+export const useAnchorScroll = (options: UseAnchorScrollOptions = {}) => {
+  const { offset = 0 } = options;
+
+  const prefersReducedMotion = (): boolean => {
+    if (import.meta.server) return false;
+    return window.matchMedia("(prefers-reduced-motion: reduce)").matches;
+  };
+
+  const resolveOffset = (): number => (typeof offset === "function" ? offset() : offset);
+
+  const scrollToAnchor = (hash: string): void => {
+    if (import.meta.server) return;
+    const id = hash.startsWith("#") ? hash.slice(1) : hash;
+    const el = document.getElementById(id);
+    if (!el) return;
+
+    const behavior: ScrollBehavior = prefersReducedMotion() ? "instant" : "smooth";
+    const px = resolveOffset();
+
+    if (px) {
+      const top = el.getBoundingClientRect().top + window.scrollY - px;
+      window.scrollTo({ top, behavior });
+    } else {
+      el.scrollIntoView({ behavior, block: "start" });
+    }
+  };
+
+  // Intercepts anchor (#hash) clicks only. Routes and external links are left
+  // to NuxtLink/router unchanged. When reduced motion is preferred, the default
+  // browser/router anchor jump is preserved; otherwise we prevent that default
+  // and smooth-scroll ourselves.
+  const handleNavClick = (event: MouseEvent, href: string): void => {
+    if (!href.startsWith("#")) return;
+    if (prefersReducedMotion()) return;
+
+    event.preventDefault();
+    history.pushState(null, "", href);
+    scrollToAnchor(href);
+  };
+
+  return { handleNavClick, scrollToAnchor };
+};

package/app/layouts/default.vue

@@ -91,6 +91,7 @@ const responsiveNavLinks = {
         { name: "Display Avatar", path: "/ui/display-avatar" },
         { name: "Display Pill", path: "/ui/display-pill" },
         { name: "Qr Codes", path: "/ui/qr-code/display" },
+        { name: "Anchor Scroll", path: "/ui/anchor-scroll" },
       ],
     },
     {

package/app/pages/ui/anchor-scroll.vue

@@ -0,0 +1,333 @@
+<template>
+  <div>
+    <NuxtLayout name="default">
+      <template #layout-content>
+        <LayoutRow tag="div" variant="content" :style-class-passthrough="['mbe-4']">
+          <h1 class="page-heading-1">useAnchorScroll</h1>
+          <p class="page-body-medium">
+            Intercepts <code class="inline-code">#hash</code> link clicks and smooth-scrolls to
+            the target element. Routes and external links pass through to NuxtLink unchanged.
+            Respects <code class="inline-code">prefers-reduced-motion</code> — when the user opts
+            out of motion, the default browser anchor jump is preserved with no custom scroll code
+            involved.
+          </p>
+          <p class="page-body-medium">
+            This page demonstrates the composable directly: the sticky bar below uses
+            <code class="inline-code">useAnchorScroll</code> with a dynamic offset so section
+            headings always land just below the bar after scrolling.
+          </p>
+        </LayoutRow>
+
+        <div ref="stickyNavRef" class="anchor-scroll-sticky-nav">
+          <LayoutRow tag="div" variant="content">
+            <nav aria-label="Page sections">
+              <ul class="anchor-nav-list">
+                <li v-for="section in sections" :key="section.id">
+                  <a
+                    :href="`#${section.id}`"
+                    class="anchor-nav-link"
+                    @click="(e) => handleNavClick(e, `#${section.id}`)"
+                  >{{ section.label }}</a>
+                </li>
+              </ul>
+            </nav>
+          </LayoutRow>
+        </div>
+
+        <section id="overview" class="anchor-demo-section">
+          <LayoutRow tag="div" variant="content">
+            <h2 class="page-heading-2">Overview</h2>
+            <p class="page-body-medium">
+              Single-page and anchor-linked layouts need a bridge between
+              <code class="inline-code">NuxtLink</code> (which handles routes) and the browser's
+              native anchor scrolling (which has no smooth-scroll guarantee).
+              <code class="inline-code">useAnchorScroll</code> fills that gap.
+            </p>
+            <p class="page-body-medium">
+              Pass any <code class="inline-code">#hash</code> href to
+              <code class="inline-code">handleNavClick</code> — it prevents the default jump,
+              pushes the hash into the URL, and scrolls to the matching element. Every other href
+              (routes, external URLs) is a no-op, so the same handler is safe to attach to all
+              navigation links without conditional logic in the template.
+            </p>
+            <p class="page-body-medium">
+              An optional <code class="inline-code">offset</code> shifts the final scroll position
+              upward — useful when a sticky bar would otherwise obscure the section heading. Pass a
+              number for a fixed bar height or a getter function to read the bar's live height at
+              scroll time.
+            </p>
+          </LayoutRow>
+        </section>
+
+        <section id="api" class="anchor-demo-section">
+          <LayoutRow tag="div" variant="content">
+            <h2 class="page-heading-2">API</h2>
+
+            <h3 class="page-heading-3">Options</h3>
+            <div class="api-table-wrapper">
+              <table class="api-table">
+                <thead>
+                  <tr>
+                    <th>Option</th>
+                    <th>Type</th>
+                    <th>Default</th>
+                    <th>Description</th>
+                  </tr>
+                </thead>
+                <tbody>
+                  <tr>
+                    <td><code class="inline-code">offset</code></td>
+                    <td><code class="inline-code">number | (() =&gt; number)</code></td>
+                    <td><code class="inline-code">0</code></td>
+                    <td>
+                      Pixels subtracted from the scroll-to position. Pass a getter to read a sticky
+                      element's height at scroll time rather than at composable init.
+                    </td>
+                  </tr>
+                </tbody>
+              </table>
+            </div>
+
+            <h3 class="page-heading-3">Returns</h3>
+            <div class="api-table-wrapper">
+              <table class="api-table">
+                <thead>
+                  <tr>
+                    <th>Name</th>
+                    <th>Type</th>
+                    <th>Description</th>
+                  </tr>
+                </thead>
+                <tbody>
+                  <tr>
+                    <td><code class="inline-code">handleNavClick</code></td>
+                    <td><code class="inline-code">(event: MouseEvent, href: string) =&gt; void</code></td>
+                    <td>
+                      Attach to click handlers. No-ops silently for non-anchor hrefs so it is safe
+                      on all links.
+                    </td>
+                  </tr>
+                  <tr>
+                    <td><code class="inline-code">scrollToAnchor</code></td>
+                    <td><code class="inline-code">(hash: string) =&gt; void</code></td>
+                    <td>
+                      Programmatically scroll to a hash string (with or without the leading
+                      <code class="inline-code">#</code>). Respects the same motion preference and
+                      offset.
+                    </td>
+                  </tr>
+                </tbody>
+              </table>
+            </div>
+          </LayoutRow>
+        </section>
+
+        <section id="usage" class="anchor-demo-section">
+          <LayoutRow tag="div" variant="content">
+            <h2 class="page-heading-2">Usage</h2>
+
+            <h3 class="page-heading-3">In TabNavigation</h3>
+            <p class="page-body-medium">
+              <code class="inline-code">TabNavigation</code> already has
+              <code class="inline-code">useAnchorScroll</code> wired up internally. Pass anchor
+              hrefs in <code class="inline-code">navItemData</code> and it works automatically.
+            </p>
+            <pre class="demo-code">const navItemData = {
+  main: [
+    { text: "About",    href: "#about" },
+    { text: "Services", href: "#services" },
+    { text: "Contact",  href: "#contact" },
+    { text: "Blog",     href: "/blog" },      // route — handled by NuxtLink as normal
+  ],
+};
+</pre>
+            <pre class="demo-code">&lt;TabNavigation :nav-item-data="navItemData" /&gt;
+</pre>
+
+            <h3 class="page-heading-3">Standalone (this page)</h3>
+            <p class="page-body-medium">
+              For custom anchor navs — like a sticky section bar or a terms-page sidebar — call
+              the composable directly. Pass a getter for
+              <code class="inline-code">offset</code> so it reads the element height at scroll
+              time rather than on mount.
+            </p>
+            <pre class="demo-code">const stickyNavRef = ref&lt;HTMLElement | null&gt;(null);
+
+const { handleNavClick } = useAnchorScroll({
+  offset: () =&gt; stickyNavRef.value?.offsetHeight ?? 0,
+});
+</pre>
+            <pre class="demo-code">&lt;div ref="stickyNavRef" class="sticky-nav"&gt;
+  &lt;a href="#overview" @click="(e) =&gt; handleNavClick(e, '#overview')"&gt;Overview&lt;/a&gt;
+  &lt;a href="#api"      @click="(e) =&gt; handleNavClick(e, '#api')"&gt;API&lt;/a&gt;
+&lt;/div&gt;
+</pre>
+
+            <h3 class="page-heading-3">Programmatic scroll</h3>
+            <p class="page-body-medium">
+              Use <code class="inline-code">scrollToAnchor</code> when you need to scroll without
+              a click event — for example, after a form submission or on route entry.
+            </p>
+            <pre class="demo-code">const { scrollToAnchor } = useAnchorScroll({ offset: 64 });
+
+onMounted(() =&gt; {
+  if (route.hash) scrollToAnchor(route.hash);
+});
+</pre>
+          </LayoutRow>
+        </section>
+
+        <section id="motion" class="anchor-demo-section">
+          <LayoutRow tag="div" variant="content">
+            <h2 class="page-heading-2">Reduced Motion</h2>
+            <p class="page-body-medium">
+              When <code class="inline-code">prefers-reduced-motion: reduce</code> is active,
+              <code class="inline-code">handleNavClick</code> returns early without calling
+              <code class="inline-code">preventDefault</code>. The browser or Vue Router handles
+              the anchor navigation natively — an instant jump with no custom scroll code
+              involved. No special configuration needed.
+            </p>
+            <p class="page-body-medium">
+              To test: open your OS accessibility settings, enable Reduce Motion, then click
+              a section link in the bar above. The page will jump immediately instead of
+              scrolling.
+            </p>
+            <p class="page-body-medium">
+              <code class="inline-code">scrollToAnchor</code> respects the same preference:
+              it uses <code class="inline-code">behavior: "instant"</code> when reduced motion
+              is detected, so programmatic scrolls are equally accessible.
+            </p>
+          </LayoutRow>
+        </section>
+      </template>
+    </NuxtLayout>
+  </div>
+</template>
+
+<script setup lang="ts">
+definePageMeta({ layout: false });
+
+const stickyNavRef = ref<HTMLElement | null>(null);
+
+const sections = [
+  { id: "overview", label: "Overview" },
+  { id: "api", label: "API" },
+  { id: "usage", label: "Usage" },
+  { id: "motion", label: "Reduced Motion" },
+];
+
+const { handleNavClick } = useAnchorScroll({
+  offset: () => stickyNavRef.value?.offsetHeight ?? 0,
+});
+</script>
+
+<style lang="css">
+.anchor-scroll-sticky-nav {
+  position: sticky;
+  top: 0;
+  z-index: 5;
+  background-color: var(--page-bg, #000);
+  border-block-end: 1px solid oklch(100% 0 0 / 10%);
+}
+
+.anchor-nav-list {
+  list-style: none;
+  margin: 0;
+  padding: 0;
+  display: flex;
+  flex-wrap: wrap;
+  gap: 0.4rem 2rem;
+  padding-block: 1.2rem;
+}
+
+.anchor-nav-link {
+  color: var(--slate-02, currentColor);
+  font-size: 1.4rem;
+  letter-spacing: 0.04em;
+  text-decoration: none;
+  padding-block: 0.4rem;
+  border-block-end: 1.5px solid transparent;
+  transition: color 200ms ease, border-color 200ms ease;
+
+  &:hover,
+  &:focus-visible {
+    color: var(--slate-00, currentColor);
+    border-block-end-color: currentColor;
+    outline: none;
+  }
+}
+
+.anchor-demo-section {
+  min-block-size: 60vh;
+  padding-block: 6rem 8rem;
+  border-block-end: 1px solid oklch(100% 0 0 / 8%);
+
+  &:last-child {
+    border-block-end: none;
+  }
+
+  .page-heading-2 {
+    margin-block-end: 2rem;
+  }
+
+  .page-heading-3 {
+    margin-block: 3.2rem 1.2rem;
+  }
+
+  .page-body-medium {
+    margin-block-end: 1.6rem;
+  }
+}
+
+.api-table-wrapper {
+  overflow-x: auto;
+  margin-block: 1.6rem 0;
+}
+
+.api-table {
+  width: 100%;
+  border-collapse: collapse;
+  font-size: 1.4rem;
+  line-height: 1.5;
+
+  th,
+  td {
+    text-align: left;
+    padding: 1rem 1.6rem;
+    border: 1px solid oklch(100% 0 0 / 12%);
+    vertical-align: top;
+  }
+
+  th {
+    background-color: oklch(100% 0 0 / 4%);
+    font-weight: 600;
+    color: var(--slate-01, currentColor);
+  }
+
+  td {
+    color: var(--slate-02, currentColor);
+  }
+}
+
+.demo-code {
+  background-color: oklch(100% 0 0 / 4%);
+  border: 1px solid oklch(100% 0 0 / 10%);
+  border-radius: 0.6rem;
+  padding: 1.8rem 2rem;
+  overflow-x: auto;
+  font-family: ui-monospace, "Cascadia Code", "Source Code Pro", Menlo, Consolas, monospace;
+  font-size: 1.3rem;
+  line-height: 1.65;
+  margin-block: 1.2rem 2rem;
+  white-space: pre;
+  color: var(--slate-01, currentColor);
+}
+
+.inline-code {
+  font-family: ui-monospace, "Cascadia Code", "Source Code Pro", Menlo, Consolas, monospace;
+  font-size: 0.875em;
+  background-color: oklch(100% 0 0 / 8%);
+  padding: 0.15em 0.4em;
+  border-radius: 0.3rem;
+}
+</style>

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "srcdev-nuxt-components",
   "type": "module",
-  "version": "9.1.46",
+  "version": "9.1.48",
   "main": "nuxt.config.ts",
   "types": "types.d.ts",
   "license": "MIT",