srcdev-nuxt-components 9.1.47 → 9.1.49

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

@@ -0,0 +1,293 @@
+# 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. |
+| `offsetElement` | `Ref<HTMLElement &#124; null>` | — | Convenience alternative to `offset`. Reads `element.offsetHeight` at scroll time. Takes priority over `offset` when both are supplied. |
+
+### 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. |
+| `activeHash` | `Ref<string>` | Reactive ref tracking the currently active hash. Starts `""` on server and after hydration is set from `window.location.hash`. Updated on every `handleNavClick` call. Use this to drive `is-active` classes — **do not use `route.hash`**, which is not updated by `history.pushState`. |
+
+---
+
+## Active state
+
+`activeHash` is the correct way to drive active-state styling on anchor nav links.
+
+**Why not `route.hash`?** `handleNavClick` calls `history.pushState` directly (to avoid triggering Vue Router's scroll behaviour). `pushState` does not update Vue Router's reactive `route.hash`, so `route.hash` stays stale after clicks.
+
+**Hydration safety:** `activeHash` is initialised to `""` on both server and client so the SSR-rendered HTML always matches the pre-mount client vdom. The real hash is applied in `onMounted`, after hydration, to avoid mismatches.
+
+**Default active item:** `activeHash` is empty until `onMounted` fires. If no hash is in the URL, set a default in the component's own `onMounted` (which runs after the composable's `onMounted`):
+
+```ts
+const { handleNavClick, activeHash } = useAnchorScroll({ offset: 64 });
+
+onMounted(() => {
+  // Default to first section when no hash is in the URL
+  if (!activeHash.value && sections[0]) activeHash.value = `#${sections[0].id}`;
+});
+```
+
+### Binding active state in a template
+
+```vue
+<a
+  v-for="section in sections"
+  :key="section.id"
+  :href="`#${section.id}`"
+  :class="{ 'is-active': `#${section.id}` === activeHash }"
+  @click="(e) => handleNavClick(e, `#${section.id}`)"
+>{{ section.label }}</a>
+```
+
+### Active state in TabNavigation
+
+`TabNavigation` handles `activeHash` internally for hash nav items. No extra work needed —
+just pass anchor hrefs in `navItemData` and the active indicator moves automatically on click
+and on initial load (defaulting to the first hash item when the URL has no hash).
+
+---
+
+## Usage patterns
+
+### 1. TabNavigation with a sticky site header
+
+`TabNavigation` accepts an `anchorScrollOffset` prop that is passed directly to `useAnchorScroll`.
+Pass a getter so the live header height is read at scroll time — this stays correct if the
+header resizes on different viewports.
+
+```vue
+<header ref="headerRef">
+  <TabNavigation
+    :nav-item-data="navItemData"
+    :anchor-scroll-offset="() => headerRef?.offsetHeight ?? 0"
+  />
+</header>
+```
+
+```ts
+const headerRef = ref<HTMLElement | null>(null);
+
+const navItemData = {
+  main: [
+    { text: "About",    href: "#about" },
+    { text: "Services", href: "#services" },
+    { text: "Contact",  href: "#contact" },
+    { text: "Blog",     href: "/blog" },  // route — NuxtLink handles as normal
+  ],
+};
+```
+
+**CSS alternative** — if you want all anchor links site-wide to respect the sticky header
+(not just the ones inside `TabNavigation`), add `scroll-padding-top` to `html` instead and
+skip the prop:
+
+```css
+/* ─ app/assets/styles/setup/01.config/_head.css ─ */
+html {
+  scroll-padding-top: var(--sticky-header-height, 64px);
+}
+```
+
+```css
+/* ─ app/assets/styles/main.css ─ */
+:root {
+  --sticky-header-height: 64px; /* adjust to match actual header height */
+}
+```
+
+`scrollIntoView` respects `scroll-padding-top`, so this works with the no-offset code path.
+
+---
+
+### 2. Sticky section nav with dynamic offset (using offsetElement)
+
+The `offsetElement` option is the clearest way to derive an offset from an element ref.
+It reads `offsetHeight` at scroll time, so resize changes are always captured.
+
+```ts
+const stickyNavRef = ref<HTMLElement | null>(null);
+
+const { handleNavClick, activeHash } = useAnchorScroll({ offsetElement: stickyNavRef });
+
+onMounted(() => {
+  if (!activeHash.value && sections[0]) activeHash.value = `#${sections[0].id}`;
+});
+```
+
+```vue
+<nav ref="stickyNavRef" class="sticky-section-nav">
+  <a
+    v-for="section in sections"
+    :key="section.id"
+    :href="`#${section.id}`"
+    :class="{ 'is-active': `#${section.id}` === activeHash }"
+    @click="(e) => handleNavClick(e, `#${section.id}`)"
+  >{{ section.label }}</a>
+</nav>
+
+<section v-for="section in sections" :key="section.id" :id="section.id">…</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, activeHash } = useAnchorScroll({ offset: 24 }); // fixed header height
+```
+
+```vue
+<aside class="terms-sidebar">
+  <nav>
+    <a v-for="section in termsSections" :key="section.id"
+       :href="`#${section.id}`"
+       :class="{ 'is-active': `#${section.id}` === activeHash }"
+       @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` or `offsetElement`, the composable calls `el.scrollIntoView({ behavior, block: "start" })` —
+the element's top edge aligns with the viewport top.
+
+With an 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.
+
+**`offsetElement` vs `offset` getter:**
+
+```ts
+// ✅ offsetElement — reads offsetHeight at click time, no boilerplate
+const { handleNavClick, activeHash } = useAnchorScroll({ offsetElement: navRef });
+
+// ✅ offset getter — equivalent, useful when the offset is derived from more than one element
+const { handleNavClick, activeHash } = useAnchorScroll({
+  offset: () => navRef.value?.offsetHeight ?? 0,
+});
+
+// ✗ Static offset — stale if the bar changes height later
+const { handleNavClick, activeHash } = 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.
+
+> **Debugging tip:** If clicks produce an instant jump instead of smooth scroll, check whether
+> "Reduce Motion" is enabled in your OS accessibility settings (macOS: System Preferences →
+> Accessibility → Display → Reduce Motion). This is intentional behaviour, not a bug.
+
+---
+
+## Notes
+
+- **`activeHash` vs `route.hash`** — always use `activeHash` for active-state classes. `route.hash`
+  is not updated by `history.pushState` and will be stale after clicks.
+- **Hydration mismatches** — `activeHash` is always `""` at render time; the real value is set in
+  `onMounted`. Never initialise it from `window.location.hash` in setup — that causes a server/client
+  class mismatch.
+- **`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/02.molecules/navigation/tab-navigation/TabNavigation.vue

@@ -19,14 +19,27 @@
         v-for="item in navItemData.main"
         :key="item.href"
         :data-href="item.href"
-        :class="[item.cssName, { 'is-active': isActiveItem(item.href), 'is-hovered': hoveredItemHref === item.href }]"
+        :class="[item.cssName, { 'is-active': item.href?.startsWith('#') ? item.href === activeHash : isActiveItem(item.href), 'is-hovered': hoveredItemHref === item.href }]"
         @mouseenter="hoveredItemHref = item.href ?? null"
       >
+        <!-- Plain <a> for hash links — keeps Vue Router out of the smooth-scroll path -->
+        <a
+          v-if="item.href?.startsWith('#')"
+          :href="item.href"
+          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 }}
+        </a>
         <NuxtLink
+          v-else
           :href="item.href"
           :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 }}
@@ -73,11 +86,21 @@
       <div class="tab-nav-panel-inner">
         <ul class="tab-nav-panel-list">
           <li v-for="item in navItemData.main" :key="item.href" :class="item.cssName">
+            <a
+              v-if="item.href?.startsWith('#')"
+              :href="item.href"
+              class="tab-nav-panel-link"
+              @click="(e) => { item.href && handleNavClick(e, item.href); closeMenu(); }"
+            >
+              <Icon v-if="item.iconName" :name="item.iconName" aria-hidden="true" />
+              {{ item.text }}
+            </a>
             <NuxtLink
+              v-else
               :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 }}
@@ -96,16 +119,27 @@ interface Props {
   navItemData: NavItemData;
   navAlign?: "left" | "center" | "right";
   styleClassPassthrough?: string | string[];
+  anchorScrollOffset?: number | (() => number);
 }
 
 const props = withDefaults(defineProps<Props>(), {
   navAlign: "left",
   styleClassPassthrough: () => [],
+  anchorScrollOffset: undefined,
 });
 
 const { navRef, navListRef, isCollapsed, isLoaded, isMenuOpen, isActiveItem, toggleMenu, closeMenu } =
   useNavCollapse("tab-nav-loaded");
 
+const { handleNavClick, activeHash } = useAnchorScroll({ offset: props.anchorScrollOffset });
+
+onMounted(() => {
+  if (!activeHash.value) {
+    const firstHashItem = props.navItemData.main?.find((item) => item.href?.startsWith("#"));
+    if (firstHashItem?.href) activeHash.value = firstHashItem.href;
+  }
+});
+
 // ─── 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/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,59 @@
+interface UseAnchorScrollOptions {
+  offset?: number | (() => number);
+  offsetElement?: Ref<HTMLElement | null>;
+}
+
+export const useAnchorScroll = (options: UseAnchorScrollOptions = {}) => {
+  const { offset = 0, offsetElement } = options;
+
+  const prefersReducedMotion = (): boolean => {
+    if (import.meta.server) return false;
+    return window.matchMedia("(prefers-reduced-motion: reduce)").matches;
+  };
+
+  const resolveOffset = (): number => {
+    if (offsetElement) return offsetElement.value?.offsetHeight ?? 0;
+    return 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" });
+    }
+  };
+
+  // Starts empty so server and client render identically (no hydration mismatch).
+  // onMounted sets the real value after hydration, client-only.
+  const activeHash = ref("");
+
+  onMounted(() => {
+    activeHash.value = window.location.hash;
+  });
+
+  // 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();
+    activeHash.value = href;
+    history.pushState(null, "", href);
+    scrollToAnchor(href);
+  };
+
+  return { handleNavClick, scrollToAnchor, activeHash };
+};

package/app/composables/useNavCollapse.ts

@@ -38,7 +38,11 @@ export const useNavCollapse = (stateKey: string, options: NavCollapseOptions = {
   const route = useRoute();
 
   const activeHref = computed(() => route.path);
-  const isActiveItem = (href?: string) => href === route.path;
+  const isActiveItem = (href?: string) => {
+    if (!href) return false;
+    if (href.startsWith("#")) return href === route.hash;
+    return href === route.path;
+  };
 
   watch(
     () => route.path,

package/app/layouts/default.vue

@@ -91,6 +91,8 @@ 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" },
+        { name: "Anchor Scroll (TabNavigation)", path: "/ui/anchor-scroll-tab-navigation" },
       ],
     },
     {

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

@@ -0,0 +1,180 @@
+<template>
+  <div>
+    <NuxtLayout name="default">
+      <template #layout-content>
+        <LayoutRow tag="div" variant="content" :style-class-passthrough="['mbe-4']">
+          <h1 class="page-heading-1">Anchor Scroll — TabNavigation</h1>
+          <p class="page-body-medium">
+            Tests <code class="inline-code">TabNavigation</code> with anchor hrefs. The nav uses
+            plain <code class="inline-code">&lt;a&gt;</code> tags for hash links (not
+            <code class="inline-code">NuxtLink</code>) to keep Vue Router out of the
+            smooth-scroll path. The <code class="inline-code">:anchor-scroll-offset</code> prop
+            passes a getter so the sticky bar height is read at scroll time.
+          </p>
+        </LayoutRow>
+
+        <div ref="stickyNavRef" class="anchor-tab-nav-sticky">
+          <LayoutRow tag="div" variant="content">
+            <TabNavigation
+              :nav-item-data="anchorNavData"
+              :anchor-scroll-offset="() => stickyNavRef?.offsetHeight ?? 0"
+            />
+          </LayoutRow>
+        </div>
+
+        <section id="overview" class="anchor-tab-section">
+          <LayoutRow tag="div" variant="content">
+            <h2 class="page-heading-2">Overview</h2>
+            <p class="page-body-medium">
+              This section verifies that clicking the <strong>Overview</strong> link above scrolls
+              here smoothly, with the heading landing below the sticky nav bar rather than behind it.
+            </p>
+            <p class="page-body-medium">
+              The sticky nav's height is resolved at click time via the getter passed to
+              <code class="inline-code">:anchor-scroll-offset</code>. Resize the viewport — the
+              offset adjusts automatically.
+            </p>
+            <p class="page-body-medium">
+              Hash links in <code class="inline-code">TabNavigation</code> render as plain
+              <code class="inline-code">&lt;a&gt;</code> elements (not
+              <code class="inline-code">NuxtLink</code>), which prevents Vue Router from
+              intercepting the click and triggering its own scroll behaviour.
+            </p>
+          </LayoutRow>
+        </section>
+
+        <section id="api" class="anchor-tab-section">
+          <LayoutRow tag="div" variant="content">
+            <h2 class="page-heading-2">API</h2>
+            <p class="page-body-medium">
+              This section verifies the <strong>API</strong> link. Confirm the heading lands
+              below the sticky nav after scrolling.
+            </p>
+            <p class="page-body-medium">
+              The <code class="inline-code">anchorScrollOffset</code> prop on
+              <code class="inline-code">TabNavigation</code> accepts
+              <code class="inline-code">number | (() => number)</code> — the same type as the
+              <code class="inline-code">offset</code> option on <code class="inline-code">useAnchorScroll</code>
+              directly. It is forwarded verbatim to the composable.
+            </p>
+            <div class="demo-code">const navItemData = {
+  main: [
+    { text: "Overview", href: "#overview" },
+    { text: "API",      href: "#api" },
+    { text: "Usage",    href: "#usage" },
+    { text: "Motion",   href: "#motion" },
+  ],
+};</div>
+            <div class="demo-code">&lt;div ref="stickyNavRef"&gt;
+  &lt;TabNavigation
+    :nav-item-data="navItemData"
+    :anchor-scroll-offset="() => stickyNavRef?.offsetHeight ?? 0"
+  /&gt;
+&lt;/div&gt;</div>
+          </LayoutRow>
+        </section>
+
+        <section id="usage" class="anchor-tab-section">
+          <LayoutRow tag="div" variant="content">
+            <h2 class="page-heading-2">Usage</h2>
+            <p class="page-body-medium">
+              This section verifies the <strong>Usage</strong> link. Confirm the heading lands
+              below the sticky nav after scrolling.
+            </p>
+            <p class="page-body-medium">
+              Mixed navigation — routes and anchor hrefs in the same
+              <code class="inline-code">navItemData</code> — is supported. Route items render
+              as <code class="inline-code">NuxtLink</code>; anchor items render as plain
+              <code class="inline-code">&lt;a&gt;</code>. The handler is a no-op for routes
+              so both types can share the same click binding.
+            </p>
+            <div class="demo-code">const navItemData = {
+  main: [
+    { text: "About",    href: "#about" },    // anchor — plain &lt;a&gt;
+    { text: "Services", href: "#services" }, // anchor — plain &lt;a&gt;
+    { text: "Blog",     href: "/blog" },     // route  — NuxtLink
+    { text: "Contact",  href: "#contact" },  // anchor — plain &lt;a&gt;
+  ],
+};</div>
+          </LayoutRow>
+        </section>
+
+        <section id="motion" class="anchor-tab-section">
+          <LayoutRow tag="div" variant="content">
+            <h2 class="page-heading-2">Reduced Motion</h2>
+            <p class="page-body-medium">
+              This section verifies the <strong>Reduced Motion</strong> link. With
+              <em>Reduce Motion</em> enabled in OS accessibility settings, clicks should
+              produce an instant jump rather than a smooth scroll — and the offset should still
+              be respected.
+            </p>
+            <p class="page-body-medium">
+              To test on macOS: <strong>System Settings → Accessibility → Display → Reduce
+              Motion</strong>. Refresh the page after toggling, then click any section link
+              above.
+            </p>
+          </LayoutRow>
+        </section>
+      </template>
+    </NuxtLayout>
+  </div>
+</template>
+
+<script setup lang="ts">
+import type { NavItemData } from "~/types/components";
+
+definePageMeta({ layout: false });
+
+const stickyNavRef = ref<HTMLElement | null>(null);
+
+const anchorNavData: NavItemData = {
+  main: [
+    { text: "Overview", href: "#overview" },
+    { text: "API", href: "#api" },
+    { text: "Usage", href: "#usage" },
+    { text: "Reduced Motion", href: "#motion" },
+  ],
+};
+</script>
+
+<style lang="css">
+.anchor-tab-nav-sticky {
+  position: sticky;
+  top: 0;
+  z-index: 5;
+  background-color: var(--page-bg, #000);
+  border-block-end: 1px solid oklch(100% 0 0 / 10%);
+}
+
+.anchor-tab-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-body-medium {
+    margin-block-end: 1.6rem;
+  }
+}
+
+.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);
+}
+</style>

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

@@ -0,0 +1,343 @@
+<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"
+                    :class="{ 'is-active': `#${section.id}` === activeHash }"
+                    @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, activeHash } = useAnchorScroll({
+  offset: () => stickyNavRef.value?.offsetHeight ?? 0,
+});
+
+onMounted(() => {
+  if (!activeHash.value && sections[0]) activeHash.value = `#${sections[0].id}`;
+});
+</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;
+  }
+
+  &.is-active {
+    color: var(--slate-00, currentColor);
+    border-block-end-color: currentColor;
+  }
+}
+
+.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.47",
+  "version": "9.1.49",
   "main": "nuxt.config.ts",
   "types": "types.d.ts",
   "license": "MIT",