srcdev-nuxt-components 9.1.7 → 9.1.9

package/.claude/skills/components/page-hero-highlights.md

@@ -17,8 +17,8 @@ The layout uses a 4-row CSS Grid with `subgrid` — no `translate`, negative mar
 | `tag`                   | `"div" \| "section" \| "main"`                                      | `"div"`     | Root element tag                                                                                                                |
 | `highlightsEqualWidths` | `boolean`                                                           | `false`     | Equal-width grid columns for highlight items                                                                                    |
 | `highlightsJustify`     | `"start" \| "center" \| "end" \| "space-between" \| "space-around"` | `"start"`   | Alignment of highlight items along the main axis                                                                                |
-| `maxWidth`              | `string`                                                            | `undefined` | Cap the central content column (e.g. `"1064px"`). Gutters grow to enforce the constraint; below this width they hold at `16px`. |
-| `contentAlign`          | `"start" \| "center"`                                               | `"center"`  | When `maxWidth` is set: `"center"` grows gutters equally; `"start"` pins content to the left with a fixed `16px` left gutter.   |
+| `widthConstrained`              | `boolean`                                                           | `false`     | When `true`, caps the central column at `--width-constrained` (default `1064px`). Gutters grow responsively to enforce the constraint. |
+| `contentAlign`          | `"start" \| "center"`                                               | `"center"`  | When `widthConstrained` is `true`: `"center"` grows gutters equally; `"start"` pins content to the left with a fixed left gutter.      |
 | `contentPanel`          | `boolean`                                                           | `true`      | When `true`, renders a decorative panel behind the content slot and offsets the highlights strip. Set to `false` for a flat layout with no backdrop. |
 | `highlightTitleBaseline`| `boolean`                                                           | `false`     | When `true`, fixes the highlight title row to a set height so titles align at a common baseline. Override `--highlight-title-height` to tune. |
 | `styleClassPassthrough` | `string \| string[]`                                                | `[]`        | Extra classes on the root element                                                                                               |
@@ -66,7 +66,7 @@ Each slot accepts any content, but these library components are natural fits:
 Example with `HeroText` in the header slot:
 
 ```vue
-<PageHeroHighlights tag="section" max-width="1064px">
+<PageHeroHighlights tag="section" :width-constrained="true">
   <template #header="{ headingId }">
     <HeroText :heading-id="headingId" text="Welcome back" accent-text="Simon" />
   </template>
@@ -106,11 +106,13 @@ Located at: `app/components/04.templates/page-hero-highlights/PageHeroHighlights
 
 ### CSS tokens
 
-| Token              | Default  | Description                              |
-| ------------------ | -------- | ---------------------------------------- |
-| `--phh-padding-block` | `1.6rem` | Block padding on the header              |
-| `--phh-gap`        | `1.6rem` | Gap between `#start` and `#end` areas    |
-| `--phh-end-gap`    | `0.8rem` | Gap between items within `#end`          |
+| Token                      | Default          | Description                                          |
+| -------------------------- | ---------------- | ---------------------------------------------------- |
+| `--phh-padding-block-mobile`  | `1.6rem 3.2rem`  | Block padding (start end) at mobile widths           |
+| `--phh-padding-block-tablet`  | `2.4rem 4.8rem`  | Block padding (start end) at ≥768px                  |
+| `--phh-padding-block-desktop` | `3.2rem 6.4rem`  | Block padding (start end) at ≥1024px                 |
+| `--phh-gap`                   | `1.6rem`         | Gap between `#start` and `#end` areas                |
+| `--phh-end-gap`               | `0.8rem`         | Gap between items within `#end`                      |
 
 ### Usage
 
@@ -170,17 +172,26 @@ By default, highlight items size to their content (`flex-wrap`). Pass `:highligh
 
 ## Constraining the central column width
 
-Pass `max-width` to cap the content column. The gutters grow to enforce it — full-bleed backgrounds are unaffected and `subgrid` continues to work. Use `content-align` to pin to the left or centre:
+Pass `:width-constrained="true"` to cap the content column at `--width-constrained` (default `1064px`). The gutters grow responsively to enforce it — full-bleed backgrounds are unaffected and `subgrid` continues to work. Use `content-align` to pin to the left or centre:
 
 ```vue
-<!-- Centred, capped at 1064px -->
-<PageHeroHighlights max-width="1064px" content-align="center">...</PageHeroHighlights>
+<!-- Centred, capped at --width-constrained (1064px) -->
+<PageHeroHighlights :width-constrained="true" content-align="center">...</PageHeroHighlights>
 
-<!-- Left-pinned, capped at 1064px (right side takes remaining space) -->
-<PageHeroHighlights max-width="1064px" content-align="start">...</PageHeroHighlights>
+<!-- Left-pinned (right side takes remaining space) -->
+<PageHeroHighlights :width-constrained="true" content-align="start">...</PageHeroHighlights>
 ```
 
-See [css-grid-max-width-gutters.md](../css-grid-max-width-gutters.md) for the full pattern explanation.
+The maximum width value and gutter sizes are all CSS tokens — override them via `styleClassPassthrough` if you need different values:
+
+```css
+.my-page-hero {
+  --width-constrained: 1200px;
+  --page-hero-highlights-gutter-desktop: 48px;
+}
+```
+
+See [css-grid-width-constrained-gutters.md](../css-grid-width-constrained-gutters.md) for the underlying pattern explanation.
 
 ## Local style override scaffold
 
@@ -199,6 +210,12 @@ See [component-local-style-override.md](../component-local-style-override.md) fo
    ─────────────────────────────────────────────────────────────────── */
 .page-hero-highlights {
   &.my-page-hero {
+    /* Grid layout */
+    /* --width-constrained: 1064px; */
+    /* --page-hero-highlights-gutter-mobile: 16px; */
+    /* --page-hero-highlights-gutter-tablet: 40px; */
+    /* --page-hero-highlights-gutter-desktop: 32px; */
+
     /* Header zone */
     /* --header-row-background-colour: darkblue; */
 
@@ -239,8 +256,6 @@ See [component-local-style-override.md](../component-local-style-override.md) fo
 </style>
 ```
 
-> **Note:** The minimum gutter width (`16px`) and layout behaviour are not overridable via CSS custom properties. Use the `max-width` and `content-align` props to control column constraints.
-
 ## Grid structure (reference)
 
 ```text
@@ -254,6 +269,8 @@ row4: page content (never underflows highlights)
 `.header-row` spans cols 1–3, rows 1–2 (edge-to-edge bg). `.header-slot` is placed in row 1 only.
 `.content-row` spans cols 1–3, rows 3–4 (bg fills behind highlights; `.content-slot` is placed in row 4 only). The decorative border behind `.content-slot` is rendered via `.content-row:before` — there is no separate DOM element for it.
 
+Grid columns are determined entirely by CSS — no `v-bind`. The `widthConstrained` and `contentAlign` props add CSS classes (`width-constrained`, `start`, `center`) which select the appropriate `grid-template-columns` rule.
+
 ## Layout pitfall: do not use `grid-template-rows: subgrid` inside `.highlights-row`
 
 The `.highlights-row` element spans rows 2–3 of the parent grid (the "straddle"). If you add an inner grid to `.highlights-row` (e.g. to extend `equal-widths` behaviour) and include `grid-template-rows: subgrid`, auto-placed items will only occupy row 1 of the subgrid (= parent row 2). Parent row 3 collapses to 0-height, destroying the straddle effect — `.content-row` appears immediately below the highlights instead of overlapping it.
@@ -280,5 +297,5 @@ The `.highlights-row` element spans rows 2–3 of the parent grid (the "straddle
 - Component is auto-imported in Nuxt — no import needed.
 - Lives in `app/components/04.templates/page-hero-highlights/`.
 - Storybook title: `"Templates/PageHeroHighlights"`.
-- **Minimum gutter is fixed at `16px`** — it is baked into the `gridColumns` computed and cannot be overridden by a CSS custom property. If a consumer needs a different minimum (e.g. `24px`), it requires a prop or a fork of the component.
-- **`contentAlign` has no effect without `maxWidth`** — both sides always hold `16px` when `maxWidth` is not set.
+- **`contentAlign` has no effect when `widthConstrained` is `false`** — both gutters hold their responsive default.
+- **Gutter sizes are CSS tokens** — `--page-hero-highlights-gutter-mobile/tablet/desktop` are all overridable. The responsive switching between them (via `@container`) is handled internally and cannot be overridden.

package/.claude/skills/css-grid-max-width-gutters.md

@@ -31,10 +31,47 @@ Left gutter stays fixed, content column is capped at `MAX_WIDTH`, remaining spac
 
 ## In Vue with a prop
 
+### Option A — CSS tokens + class selectors (preferred when max-width is a fixed design value)
+
+When the max-width and gutter values are fixed design tokens (not arbitrary consumer strings), express the logic entirely in CSS using a boolean `maxWidth` prop that adds a class:
+
+```ts
+interface Props {
+  maxWidth?: boolean;
+  contentAlign?: "start" | "center";
+}
+```
+
+```css
+.component {
+  --max-width: 1064px;
+  --gutter: 16px;
+
+  display: grid;
+
+  &.max-width {
+    grid-template-columns: var(--gutter) 1fr var(--gutter);
+  }
+
+  &:not(.max-width) {
+    &.start {
+      grid-template-columns: var(--gutter) minmax(0, var(--max-width)) minmax(var(--gutter), 1fr);
+    }
+    &.center {
+      grid-template-columns: max(var(--gutter), (100% - var(--max-width)) / 2) 1fr
+        max(var(--gutter), (100% - var(--max-width)) / 2);
+    }
+  }
+}
+```
+
+Consumers can override `--max-width` and `--gutter` via `styleClassPassthrough` without touching the prop. This is the approach used by `PageHeroHighlights`.
+
+### Option B — computed string with `v-bind` (use when max-width is a dynamic consumer prop)
+
 Because `v-bind()` in `<style>` can't be nested inside CSS functions like `max()`, build the column string as a computed and bind the whole value:
 
 ```ts
-// Props
 interface Props {
   maxWidth?: string;        // e.g. "1064px"
   contentAlign?: "start" | "center";
@@ -45,7 +82,6 @@ const props = withDefaults(defineProps<Props>(), {
   contentAlign: "center",
 });
 
-// Computed column string
 const gridColumns = computed(() => {
   if (!props.maxWidth) return "16px 1fr 16px";
   if (props.contentAlign === "start") return `16px minmax(0, ${props.maxWidth}) 1fr`;

package/app/assets/styles/setup/01.config/_head.css

@@ -15,19 +15,31 @@ html {
   transition:
     background-color 0.4s ease,
     color 0.4s ease;
-  /* scrollbar-gutter: stable; */
+  scrollbar-gutter: stable;
 
   overflow-x: clip;
-}
-body {
-  background-color: var(--page-bg, lightgray);
-  color: var(--colour-text-default);
-  font-family: var(--font-family);
-  font-size: var(--step-4);
-  min-height: 100dvh;
-  transition:
-    background-color 0.4s ease,
-    color 0.4s ease;
 
-  overflow-x: clip;
+  body {
+    background-color: var(--page-bg, lightgray);
+    color: var(--colour-text-default);
+    font-family: var(--font-family);
+    font-size: var(--step-4);
+    /* min-height: 100dvh; */
+    transition:
+      background-color 0.4s ease,
+      color 0.4s ease;
+
+    overflow-x: clip;
+
+    #__nuxt {
+      height: 100%;
+      div {
+        .page-layout {
+          min-block-size: 100svh;
+          display: grid;
+          grid-template-rows: auto 1fr auto;
+        }
+      }
+    }
+  }
 }

package/app/components/02.molecules/navigation/site-navigation/SiteNavigation.vue

@@ -17,7 +17,7 @@
       @mouseleave="resetHoverNavToActive"
       @mouseover="handleNavHover"
     >
-      <li v-for="item in navItemData.main" :key="item.href" :class="item.cssName">
+      <li v-for="item in navItemData.main" :key="item.href" :class="[item.cssName, { 'is-active': activeHref === item.href }]">
         <NuxtLink :href="item.href" :external="item.isExternal || undefined" class="site-nav-link" data-nav-item>
           <Icon v-if="item.iconName" :name="item.iconName" aria-hidden="true" />
           {{ item.text }}
@@ -70,7 +70,7 @@
           @mouseover="handlePanelHover"
           @mouseleave="resetHoverPanelToActive"
         >
-          <li v-for="item in navItemData.main" :key="item.href" :class="item.cssName">
+          <li v-for="item in navItemData.main" :key="item.href" :class="[item.cssName, { 'is-active': activeHref === item.href }]">
             <NuxtLink
               :href="item.href"
               :external="item.isExternal || undefined"
@@ -231,9 +231,7 @@ const initNavDecorators = () => {
   }
 
   const activeLink =
-    links.find((el) => el.classList.contains("router-link-exact-active")) ??
-    links.find((el) => el.classList.contains("router-link-active")) ??
-    links[0];
+    links.find((el) => el.getAttribute("href") === activeHref.value) ?? links[0];
   if (!activeLink) return;
 
   currentActiveNavLink = activeLink;
@@ -337,9 +335,7 @@ const initPanelDecorators = () => {
   }
 
   const activeLink =
-    links.find((el) => el.classList.contains("router-link-exact-active")) ??
-    links.find((el) => el.classList.contains("router-link-active")) ??
-    links[0];
+    links.find((el) => el.getAttribute("href") === activeHref.value) ?? links[0];
   if (!activeLink) return;
 
   currentActivePanelLink = activeLink;
@@ -352,11 +348,20 @@ const initPanelDecorators = () => {
 
 // ─────────────────────────────────────────────────────────────────────────────
 
-// Close panel on navigation and re-init decorators.
-// flush: 'post' ensures router-link-active classes are applied.
-// requestAnimationFrame defers the measurement until after browser layout,
-// preventing stale offsetLeft reads and racing with hover setTimeouts.
+// Compute active href from route directly — avoids racing against Vue Router's
+// class application timing when reading router-link-exact-active from the DOM.
 const route = useRoute();
+
+const activeHref = computed(() => {
+  const items = props.navItemData.main ?? [];
+  const exact = items.find((item) => item.href && route.path === item.href);
+  if (exact) return exact.href ?? null;
+  return (
+    items
+      .filter((item) => item.href && route.path.startsWith(item.href + "/"))
+      .sort((a, b) => (b.href?.length ?? 0) - (a.href?.length ?? 0))[0]?.href ?? null
+  );
+});
 watch(
   () => route.path,
   () => {
@@ -379,12 +384,16 @@ useResizeObserver(navRef, () => {
 
 onClickOutside(navRef, closeMenu);
 
+const router = useRouter();
+
 onMounted(async () => {
   await nextTick();
   checkOverflow();
   isLoaded.value = true;
-  await nextTick();
-  initNavDecorators();
+  await router.isReady();
+  requestAnimationFrame(() => {
+    initNavDecorators();
+  });
 });
 
 watch(isCollapsed, async (collapsed) => {
@@ -580,9 +589,9 @@ watch(
           outline: none;
         }
 
-        &.router-link-exact-active {
-          color: var(--_link-active-color);
-        }
+      }
+      li.is-active .site-nav-link {
+        color: var(--_link-active-color);
       }
     }
 
@@ -773,9 +782,9 @@ watch(
             outline: none;
           }
 
-          &.router-link-exact-active {
-            color: var(--_panel-link-active-color);
-          }
+        }
+        li.is-active .site-nav-panel-link {
+          color: var(--_panel-link-active-color);
         }
       }
     }