srcdev-nuxt-components 9.1.48 → 9.1.49

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

@@ -20,7 +20,8 @@ Auto-imported by Nuxt — **do not create a local copy**.
 
 | 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. |
+| `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
 
@@ -28,17 +29,69 @@ Auto-imported by Nuxt — **do not create a local copy**.
 |---|---|---|
 | `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 anchor links (no extra code needed)
+### 1. TabNavigation with a sticky site header
 
-`TabNavigation` has `useAnchorScroll` wired up internally. Pass anchor hrefs in
-`navItemData.main` and smooth scrolling works automatically.
+`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" },
@@ -49,39 +102,55 @@ const navItemData = {
 };
 ```
 
-```vue
-<TabNavigation :nav-item-data="navItemData" />
+**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);
+}
 ```
 
-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.
+```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
+### 2. Sticky section nav with dynamic offset (using offsetElement)
 
-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).
+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 } = useAnchorScroll({
-  offset: () => stickyNavRef.value?.offsetHeight ?? 0,
+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 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>
+  <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 id="overview">…</section>
-<section id="pricing">…</section>
-<section id="contact">…</section>
+<section v-for="section in sections" :key="section.id" :id="section.id">…</section>
 ```
 
 CSS to make the nav sticky:
@@ -102,7 +171,7 @@ Same pattern as above — useful for terms, privacy policy, or documentation pag
 sidebar links to in-document sections.
 
 ```ts
-const { handleNavClick } = useAnchorScroll({ offset: 24 }); // fixed header height
+const { handleNavClick, activeHash } = useAnchorScroll({ offset: 24 }); // fixed header height
 ```
 
 ```vue
@@ -110,6 +179,7 @@ const { handleNavClick } = useAnchorScroll({ offset: 24 }); // fixed header heig
   <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>
@@ -156,10 +226,10 @@ onMounted(() => {
 
 ## How offset works
 
-Without `offset`, the composable calls `el.scrollIntoView({ behavior, block: "start" })` —
+Without `offset` or `offsetElement`, 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:
+With an offset, it uses `window.scrollTo` with a calculated position:
 
 ```
 top = el.getBoundingClientRect().top + window.scrollY - offset
@@ -168,16 +238,19 @@ 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:**
+**`offsetElement` vs `offset` getter:**
 
 ```ts
-// ✅ Read height at click time
-const { handleNavClick } = useAnchorScroll({
+// ✅ 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,
 });
 
-// ✗ Captured at init — stale if the bar changes height later
-const { handleNavClick } = useAnchorScroll({
+// ✗ Static offset — stale if the bar changes height later
+const { handleNavClick, activeHash } = useAnchorScroll({
   offset: navRef.value?.offsetHeight ?? 0,
 });
 ```
@@ -195,10 +268,19 @@ When `window.matchMedia("(prefers-reduced-motion: reduce)").matches` is `true`:
 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.

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

@@ -19,10 +19,22 @@
         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"
@@ -74,7 +86,17 @@
       <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"
@@ -97,17 +119,26 @@ 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 } = useAnchorScroll();
+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

package/app/composables/useAnchorScroll.ts

@@ -1,16 +1,20 @@
 interface UseAnchorScrollOptions {
   offset?: number | (() => number);
+  offsetElement?: Ref<HTMLElement | null>;
 }
 
 export const useAnchorScroll = (options: UseAnchorScrollOptions = {}) => {
-  const { offset = 0 } = options;
+  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 => (typeof offset === "function" ? offset() : offset);
+  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;
@@ -29,6 +33,14 @@ export const useAnchorScroll = (options: UseAnchorScrollOptions = {}) => {
     }
   };
 
+  // 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
@@ -38,9 +50,10 @@ export const useAnchorScroll = (options: UseAnchorScrollOptions = {}) => {
     if (prefersReducedMotion()) return;
 
     event.preventDefault();
+    activeHash.value = href;
     history.pushState(null, "", href);
     scrollToAnchor(href);
   };
 
-  return { handleNavClick, scrollToAnchor };
+  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

@@ -92,6 +92,7 @@ const responsiveNavLinks = {
         { 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

@@ -26,6 +26,7 @@
                   <a
                     :href="`#${section.id}`"
                     class="anchor-nav-link"
+                    :class="{ 'is-active': `#${section.id}` === activeHash }"
                     @click="(e) => handleNavClick(e, `#${section.id}`)"
                   >{{ section.label }}</a>
                 </li>
@@ -216,9 +217,13 @@ const sections = [
   { id: "motion", label: "Reduced Motion" },
 ];
 
-const { handleNavClick } = useAnchorScroll({
+const { handleNavClick, activeHash } = useAnchorScroll({
   offset: () => stickyNavRef.value?.offsetHeight ?? 0,
 });
+
+onMounted(() => {
+  if (!activeHash.value && sections[0]) activeHash.value = `#${sections[0].id}`;
+});
 </script>
 
 <style lang="css">
@@ -255,6 +260,11 @@ const { handleNavClick } = useAnchorScroll({
     border-block-end-color: currentColor;
     outline: none;
   }
+
+  &.is-active {
+    color: var(--slate-00, currentColor);
+    border-block-end-color: currentColor;
+  }
 }
 
 .anchor-demo-section {

package/package.json

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