kmcom-nuxt-layers 6.2.0 → 6.3.0

package/layers/motion/animations/app/components/Motion/Staggered.vue

@@ -1,5 +1,8 @@
 <script setup lang="ts">
-  // Props
+  // Explicit import so Staggered mounts under vitest's 'vue' project (no Nuxt auto-imports)
+  // — same exemption as ElementTw.vue (eslint.config.mjs).
+  import { onBeforeUnmount, onMounted, useTemplateRef } from 'vue'
+
   const {
     staggerDelay = 100,
     initialDelay = 0,
@@ -13,61 +16,53 @@
     animation?: string
   }>()
 
-  // State
-  const items = ref<HTMLElement[]>([])
-  const animatedItems = ref<boolean[]>([])
-
-  // Slots
-  const slots = useSlots()
+  // Stagger the rendered DOM children, not slot vnodes: a `ref`/`class` on `<slot>` becomes a
+  // slot prop and never reaches an element, which left every item hidden for good.
+  const reduced = useReducedMotion()
+  const root = useTemplateRef<HTMLElement>('root')
+  const timers: ReturnType<typeof setTimeout>[] = []
 
-  // Methods
-  const setItemRef = (el: HTMLElement | null, index: number) => {
-    if (el) {
-      items.value[index] = el
-      animatedItems.value[index] = false
-    }
-  }
-
-  // Lifecycle
   onMounted(() => {
-    // Animate items with staggered delay
-    setTimeout(() => {
-      items.value.forEach((item, index) => {
-        if (item) {
-          setTimeout(
-            () => {
-              animatedItems.value[index] = true
-              item.classList.add(`animate-${animation}`, 'animated')
-            },
-            initialDelay + index * staggerDelay
-          )
-        }
-      })
-    }, 100)
+    const items = [...(root.value?.children ?? [])]
+    if (reduced.value) {
+      root.value?.setAttribute('data-reduced', '')
+      return items.forEach((item) => item.classList.add('animated'))
+    }
+    items.forEach((item, index) => {
+      timers.push(
+        setTimeout(
+          () => item.classList.add(`animate-${animation}`, 'animated'),
+          initialDelay + index * staggerDelay
+        )
+      )
+    })
   })
+
+  onBeforeUnmount(() => timers.forEach(clearTimeout))
 </script>
 
 <template>
-  <div class="motion-staggered">
-    <slot
-      v-for="(_, index) in slots.default?.()"
-      :key="index"
-      :ref="(el: HTMLElement | null) => setItemRef(el, index)"
-      :class="{ animated: animatedItems[index] }"
-    />
+  <div ref="root" class="motion-staggered">
+    <slot />
   </div>
 </template>
 
 <style scoped>
   /* stylelint-disable selector-pseudo-class-no-unknown */
-  .motion-staggered :deep(.animated) {
+  .motion-staggered > :deep(*) {
+    transform: translateY(20px);
+    opacity: 0;
+    transition:
+      opacity 0.3s ease-out,
+      transform 0.3s ease-out;
+  }
+
+  .motion-staggered > :deep(.animated) {
     transform: translateY(0);
     opacity: 1;
   }
 
-  .motion-staggered :deep(*) {
-    transform: translateY(20px);
-    opacity: 0;
-    transition: all 0.3s ease-out;
+  .motion-staggered[data-reduced] > :deep(*) {
+    transition: none;
   }
 </style>

package/layers/motion/animations/app/components/Motion/TextReveal.vue

@@ -27,6 +27,12 @@
     start?: string
   }>()
 
+  // Swapped to a plain span after mount: the server can't know the preference, so deciding in
+  // render would mismatch on hydration.
+  const reduced = useReducedMotion()
+  const isStatic = ref(false)
+  onMounted(() => (isStatic.value = reduced.value))
+
   const animBinding = computed(() => ({
     y: 40,
     opacity: 0,
@@ -39,8 +45,9 @@
 </script>
 
 <template>
+  <span v-if="isStatic" class="motion-text-reveal">{{ text }}</span>
   <span
-    v-if="type === 'chars'"
+    v-else-if="type === 'chars'"
     v-gsap.whenVisible.once.splitText.chars.from="animBinding"
     class="motion-text-reveal"
     >{{ text }}</span

package/layers/motion/animations/app/components/Motion/VelocityEffect.vue

@@ -25,11 +25,17 @@
 
   const { gsap } = useGsap()
   const { velocity } = useSmoothScroll()
+  const reduced = useReducedMotion()
 
   const smoothVelocity = ref(0)
   const smoothAbsVelocity = ref(0)
 
   function tick() {
+    if (reduced.value) {
+      smoothVelocity.value = 0
+      smoothAbsVelocity.value = 0
+      return
+    }
     const d = damping / 1000
     const s = stiffness / 1000
 

package/layers/motion/animations/app/composables/useCountUp.ts

@@ -15,6 +15,7 @@ export function useCountUp(
   opts: UseCountUpOptions
 ) {
   const { gsap, ScrollTrigger } = useGsap()
+  const reduced = useReducedMotion()
 
   const displayValue = ref(String(opts.from ?? 0))
   const isComplete = ref(false)
@@ -26,6 +27,11 @@ export function useCountUp(
   let tween: gsap.core.Tween | null = null
 
   function startCount() {
+    if (reduced.value) {
+      displayValue.value = format(opts.to)
+      isComplete.value = true
+      return
+    }
     tween = gsap.to(counter, {
       value: opts.to,
       duration: opts.duration ?? 2,

package/layers/motion/animations/app/composables/useCursorFollower.ts

@@ -4,11 +4,14 @@ export function useCursorFollower(opts: { smoothing?: MaybeRef<number> } = {}) {
   const { gsap } = useGsap()
   const { x: mouseX, y: mouseY } = useMouse({ type: 'client' })
 
+  const reduced = useReducedMotion()
+
   const x = ref(0)
   const y = ref(0)
 
   function tick() {
-    const factor = unref(opts.smoothing) ?? 0.15
+    // Reduced motion: track the pointer exactly instead of trailing it
+    const factor = reduced.value ? 1 : (unref(opts.smoothing) ?? 0.15)
     x.value += (mouseX.value - x.value) * factor
     y.value += (mouseY.value - y.value) * factor
   }

package/layers/motion/animations/app/utils/pointerMotion.ts

@@ -14,13 +14,18 @@ export function resolvePointerSpring(
 
 export function usePointerMotionFrame(update: () => void, cleanup?: () => void) {
   const { gsap } = useGsap()
+  const reduced = useReducedMotion()
+
+  // Checked per frame so a reduced-motion toggle applies live; reduced holds the element at rest.
+  // ponytail: cleanup re-runs every frame while reduced — cheap gsap.set, gate it if it ever shows up in a profile
+  const frame = () => (reduced.value ? cleanup?.() : update())
 
   onMounted(() => {
-    gsap.ticker.add(update)
+    gsap.ticker.add(frame)
   })
 
   onUnmounted(() => {
-    gsap.ticker.remove(update)
+    gsap.ticker.remove(frame)
     cleanup?.()
   })
 

package/layers/motion/scroll/app/components/Motion/HorizontalScroll.vue

@@ -11,6 +11,7 @@
   }>()
 
   const { gsap } = useGsap()
+  const reduced = useReducedMotion()
 
   const sectionRef = useTemplateRef<HTMLElement>('sectionRef')
   const trackRef = useTemplateRef<HTMLElement>('trackRef')
@@ -21,6 +22,14 @@
     if (!sectionRef.value || !trackRef.value) return
 
     const track = trackRef.value
+
+    // Reduced motion: no pinned scrub — panels scroll natively sideways instead.
+    // ponytail: checked once at mount — a later reduced-motion toggle applies on next mount/reload; re-run set-up in a watch if live toggling matters
+    if (reduced.value) {
+      sectionRef.value.style.overflowX = 'auto'
+      return
+    }
+
     const trackWidth = track.scrollWidth - window.innerWidth
 
     const tween = gsap.to(track, {

package/layers/motion/scroll/app/components/Motion/Parallax.vue

@@ -34,32 +34,33 @@
   }>()
 
   const { gsap } = useGsap()
+  const reduced = useReducedMotion()
 
   const containerRef = useTemplateRef<HTMLElement | null>('containerRef')
   const contentRef = useTemplateRef<HTMLElement | null>('contentRef')
 
+  let tween: gsap.core.Tween | null = null
+
   onMounted(() => {
     if (!containerRef.value || !contentRef.value) return
+    // ponytail: checked once at mount — a later reduced-motion toggle applies on next mount/reload; re-run set-up in a watch if live toggling matters
+    if (reduced.value) return
 
-    const yAmount = direction === 'vertical' ? speed * -200 : 0
-    const xAmount = direction === 'horizontal' ? speed * 200 : 0
-
-    const animationProps: gsap.TweenVars = {
+    tween = gsap.to(contentRef.value, {
       scrollTrigger: {
         trigger: containerRef.value,
         start: 'top bottom',
         end: 'bottom top',
-        scrub: scrub,
+        scrub,
       },
       ease: 'none',
-    }
-
-    if (yAmount !== 0) animationProps.y = yAmount
-    if (xAmount !== 0) animationProps.x = xAmount
-    if (rotate !== 0) animationProps.rotation = rotate
-    if (scale !== 0) animationProps.scale = 1 + scale
+      ...parallaxMotionVars({ speed, direction, rotate, scale }),
+    })
+  })
 
-    gsap.to(contentRef.value, animationProps)
+  onUnmounted(() => {
+    tween?.scrollTrigger?.kill()
+    tween?.kill()
   })
 </script>
 

package/layers/motion/scroll/app/components/Motion/PinnedSection.vue

@@ -11,21 +11,31 @@
   }>()
 
   const { gsap, ScrollTrigger } = useGsap()
+  const reduced = useReducedMotion()
 
   const sectionRef = useTemplateRef<HTMLElement>('sectionRef')
   const contentRef = useTemplateRef<HTMLElement>('contentRef')
 
   const cleanups: Array<() => void> = []
 
+  // Reduced motion: no pin, no reveal — show every child at rest (inline style beats the
+  // first-paint hide rule below).
+  // ponytail: checked once at mount — a later reduced-motion toggle applies on next mount/reload
   onMounted(() => {
-    if (!sectionRef.value || !contentRef.value) return
+    const section = sectionRef.value
+    const content = contentRef.value
+    if (!section || !content) return
+    const items = Array.from(content.querySelectorAll(':scope > *'))
+    if (reduced.value) return void gsap.set(items, { opacity: 1, y: 0, scale: 1 })
+    pinAndReveal(section, items)
+  })
 
-    const endOffset = (duration * window.innerHeight) / 100
-    const endValue = `+=${endOffset}`
+  function pinAndReveal(section: HTMLElement, items: Element[]) {
+    const endValue = `+=${(duration * window.innerHeight) / 100}`
 
     // Pin the section
     const pinSt = ScrollTrigger.create({
-      trigger: sectionRef.value,
+      trigger: section,
       start: 'top top',
       end: endValue,
       pin: true,
@@ -34,10 +44,7 @@
     cleanups.push(() => pinSt.kill())
 
     // Animate each direct child
-    const items = Array.from(contentRef.value.querySelectorAll(':scope > *'))
     const total = items.length
-    if (total === 0) return
-
     items.forEach((item, i) => {
       gsap.set(item, { opacity: 0, y: 60, scale: 0.9 })
 
@@ -46,7 +53,7 @@
 
       const tween = gsap.to(item, {
         scrollTrigger: {
-          trigger: sectionRef.value,
+          trigger: section,
           start: 'top top',
           end: endValue,
           scrub,
@@ -63,7 +70,7 @@
         tween.kill()
       })
     })
-  })
+  }
 
   onUnmounted(() => {
     cleanups.forEach((fn) => fn())

package/layers/motion/scroll/app/composables/useReducedMotion.test.ts

@@ -0,0 +1,23 @@
+import { computed, ref } from 'vue'
+import { describe, expect, it, vi } from 'vite-plus/test'
+
+const system = ref<'reduce' | 'no-preference'>('no-preference')
+vi.mock('@vueuse/core', () => ({ usePreferredReducedMotion: () => system }))
+const state = ref<'on' | 'off' | 'system'>('system')
+vi.stubGlobal('useState', () => state)
+vi.stubGlobal('computed', computed)
+
+const { useReducedMotion } = await import('./useReducedMotion')
+
+describe('useReducedMotion', () => {
+  it.each([
+    ['system', 'no-preference', false],
+    ['system', 'reduce', true],
+    ['on', 'no-preference', true],
+    ['off', 'reduce', false],
+  ] as const)('override %s + OS %s → %s', (override, os, expected) => {
+    state.value = override
+    system.value = os
+    expect(useReducedMotion().value).toBe(expected)
+  })
+})

package/layers/motion/scroll/app/composables/useReducedMotion.ts

@@ -0,0 +1,14 @@
+import { usePreferredReducedMotion } from '@vueuse/core'
+
+/**
+ * True when motion should be reduced. Honours the ThemePicker override when the theming layer
+ * is loaded — it keeps it in `useState('theme-motion')`, read here by key so scroll doesn't
+ * depend on theming — and falls back to the OS `prefers-reduced-motion` setting.
+ */
+export function useReducedMotion() {
+  const override = useState<'on' | 'off' | 'system'>('theme-motion', () => 'system')
+  const system = usePreferredReducedMotion()
+  return computed(
+    () => override.value === 'on' || (override.value === 'system' && system.value === 'reduce')
+  )
+}

package/layers/motion/scroll/app/plugins/locomotive-scroll.client.ts

@@ -18,6 +18,12 @@ export default defineNuxtPlugin({
     const instance = shallowRef<LocomotiveScroll | null>(null)
     const { screen } = useLoading()
 
+    // Under the loading screen Lenis must be stopped, not just left un-started: an unstopped
+    // Lenis still takes wheel/touch input and replays it as a jump once it starts
+    function holdForLoadingScreen(scroll: LocomotiveScroll) {
+      if (screen.value === 'visible') scroll.lenisInstance?.stop()
+    }
+
     function init() {
       if (instance.value) return
       instance.value = new LocomotiveScroll({
@@ -37,6 +43,7 @@ export default defineNuxtPlugin({
           ScrollTrigger.update()
         },
       })
+      holdForLoadingScreen(instance.value)
 
       // ScrollTriggers created before Lenis exists (page:finish can fire first)
       // refresh against a null instance — remeasure once real layout settles.
@@ -51,6 +58,7 @@ export default defineNuxtPlugin({
 
     // Hold motion until core's boot loading screen reveals the page: GSAP stays paused while the
     // screen is up, so entrance animations play once it's gone; scrolling unlocks as it exits.
+    // Without a mounted screen the state stays 'hidden' and GSAP is never touched.
     watch(
       screen,
       (state) => {
@@ -64,7 +72,7 @@ export default defineNuxtPlugin({
           ScrollTrigger.refresh()
         })
       },
-      { immediate: true }
+      { immediate: screen.value !== 'hidden' }
     )
 
     const router = useRouter()

package/layers/motion/scroll/app/utils/parallax.test.ts

@@ -0,0 +1,24 @@
+import { describe, expect, it } from 'vite-plus/test'
+
+import { parallaxMotionVars } from './parallax'
+
+const base = { speed: 0.5, direction: 'vertical', rotate: 0, scale: 0 } as const
+
+describe('parallaxMotionVars', () => {
+  it('moves up on y for vertical, right on x for horizontal', () => {
+    expect(parallaxMotionVars(base)).toEqual({ y: -100 })
+    expect(parallaxMotionVars({ ...base, direction: 'horizontal' })).toEqual({ x: 100 })
+  })
+
+  it('adds rotation and scale only when set', () => {
+    expect(parallaxMotionVars({ ...base, rotate: 15, scale: 0.2 })).toEqual({
+      y: -100,
+      rotation: 15,
+      scale: 1.2,
+    })
+  })
+
+  it('returns nothing to animate at zero speed', () => {
+    expect(parallaxMotionVars({ ...base, speed: 0 })).toEqual({})
+  })
+})

package/layers/motion/scroll/app/utils/parallax.ts

@@ -0,0 +1,16 @@
+type ParallaxMotion = {
+  speed: number
+  direction: 'vertical' | 'horizontal'
+  rotate: number
+  scale: number
+}
+
+/** MotionParallax tween vars — only the properties that actually move, so GSAP leaves the rest. */
+export function parallaxMotionVars({ speed, direction, rotate, scale }: ParallaxMotion) {
+  const vars: { x?: number; y?: number; rotation?: number; scale?: number } = {}
+  const travel = direction === 'vertical' ? speed * -200 : speed * 200
+  if (travel !== 0) vars[direction === 'vertical' ? 'y' : 'x'] = travel
+  if (rotate !== 0) vars.rotation = rotate
+  if (scale !== 0) vars.scale = 1 + scale
+  return vars
+}

package/layers/motion/scroll/nuxt.config.ts

@@ -1,7 +1,7 @@
 export default defineNuxtConfig({
   $meta: { name: 'scroll' },
 
-  extends: ['../../core'],
+  extends: ['../../core', '../../design-system/visual'],
 
   alias: {
     '#layers/scroll': import.meta.dirname,

package/layers/structure/layout/app/components/Layout/Grid/Debug.vue

@@ -72,7 +72,7 @@
 
 <template>
   <Teleport to="body">
-    <div v-if="visible" :style class="grid-debug fixed inset-0 z-9999" aria-hidden="true">
+    <div v-if="visible" :style class="grid-debug fixed inset-0 z-(--z-debug)" aria-hidden="true">
       <div v-for="i in cols" :key="i" :style="{ backgroundColor: color }" class="h-full" />
     </div>
   </Teleport>

package/layers/structure/layout/app/components/Layout/Page/index.vue

@@ -10,7 +10,7 @@
    * <Transition> and Nuxt's page-root check (NUXT_E4004) require.
    *
    * Responsibilities:
-   *   - SEO via useHead()
+   *   - title/description meta via useSeoMeta() (pages may override)
    *   - provides 'pageTitle' to child components
    *   - optional visible header (LayoutSection + LayoutPageHeader)
    *
@@ -45,15 +45,14 @@
 
   const { title, description = undefined, showHeader = false } = defineProps<Props>()
 
-  useHead({
-    title,
-    meta: description
-      ? [
-          { name: 'description', content: description },
-          { property: 'og:title', content: title },
-          { property: 'og:description', content: description },
-        ]
-      : undefined,
+  // Deliberately a "connected" template: pages (and consumers such as KMCOMv5) set their title
+  // and description through these props. useSeoMeta rather than hand-written useHead tags, so a
+  // page that also calls useSeoMeta overrides these keys instead of adding duplicates.
+  useSeoMeta({
+    title: () => title,
+    ogTitle: () => title,
+    description: () => description,
+    ogDescription: () => description,
   })
 
   provide('pageTitle', title)

package/layers/structure/navigation/app/components/Links/Group.vue

@@ -1,46 +1,20 @@
 <script lang="ts">
-  import { cloneVNode, defineComponent, Fragment, h, ref, type VNode } from 'vue'
+  import { defineComponent, h } from 'vue'
 
+  import HoverDimGroup from '#layers/visual/app/components/HoverDimGroup.vue'
+
+  /**
+   * @deprecated Renamed to `HoverDimGroup` (visual layer) — it dims any children, not just
+   * links. Kept for one release so consumers can migrate; remove after that.
+   */
   export default defineComponent({
     name: 'LinksGroup',
     inheritAttrs: false,
-    props: {
-      tag: { type: String, default: 'div' },
-      dimOpacity: { type: Number, default: 0.3 },
-      duration: { type: Number, default: 200 },
-    },
-    setup(props, { slots, attrs }) {
-      const hoveredIndex = ref<number | null>(null)
-
-      return () => {
-        const children = (slots.default?.() ?? [])
-          .flatMap((node) => (node.type === Fragment ? (node.children as VNode[]) : [node]))
-          .filter((node) => typeof node.type === 'string' || typeof node.type === 'object')
-
-        const styledChildren = children.map((vnode, index) =>
-          cloneVNode(vnode, {
-            onMouseenter: () => {
-              hoveredIndex.value = index
-            },
-            style: {
-              opacity:
-                hoveredIndex.value !== null && hoveredIndex.value !== index ? props.dimOpacity : 1,
-              transition: `opacity ${props.duration}ms ease-out`,
-            },
-          })
-        )
-
-        return h(
-          props.tag,
-          {
-            ...attrs,
-            onMouseleave: () => {
-              hoveredIndex.value = null
-            },
-          },
-          styledChildren
-        )
-      }
+    setup(_, { attrs, slots }) {
+      if (import.meta.dev)
+        // eslint-disable-next-line no-console -- one-time deprecation notice, dev only
+        console.warn('[navigation] <LinksGroup> is deprecated — use <HoverDimGroup>.')
+      return () => h(HoverDimGroup, attrs, slots)
     },
   })
 </script>

package/layers/structure/navigation/app/components/Links/Named.vue

@@ -17,6 +17,15 @@
     variant?: string
     color?: UiColors
   }>()
+
+  /**
+   * @deprecated Thin wrapper over `ULink` — use `<ULink :to="{ name, params, query }">`.
+   * Unused in this repo and KMCOMv5; remove in the next major.
+   */
+  if (import.meta.dev)
+    // eslint-disable-next-line no-console -- one-time deprecation notice, dev only
+    console.warn('[navigation] <LinksNamed> is deprecated — use <ULink :to="{ name }">.')
+
   const colorClass = useColor(() => color, 'text')
   // `name` is a plain string here, not one of the app's typed route names
   const to = computed(

package/layers/structure/navigation/app/components/Mast/Footer.vue

@@ -6,7 +6,7 @@
   <UFooter>
     <template #bottom>
       <div class="pt-10">
-        <p class="text-center text-sm text-neutral-300">Copyright © {{ year }}</p>
+        <p class="text-muted text-center text-sm">Copyright © {{ year }}</p>
       </div>
     </template>
   </UFooter>

package/layers/structure/navigation/app/components/Mast/Nav.vue

@@ -1,4 +1,6 @@
 <script setup lang="ts">
+  // Positioning is the parent's call (e.g. `<MastNav class="fixed top-0 right-0" />`); the
+  // z-index stays here so the trigger always sits on the dropdown layer.
   const { open } = useMastNav()
   const z = useGridConfig().useZIndex('dropdown')
 </script>
@@ -6,7 +8,7 @@
 <template>
   <button
     aria-label="Open navigation menu"
-    class="fixed top-0 right-0 flex cursor-pointer items-center justify-center border-0 bg-transparent p-4"
+    class="flex cursor-pointer items-center justify-center border-0 bg-transparent p-4"
     :style="{ zIndex: z }"
     @click="() => open()"
   >