kmcom-nuxt-layers 1.3.0 → 1.4.0

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

@@ -0,0 +1,61 @@
+<script setup lang="ts">
+const { scrub = 1 } = defineProps<{
+  /**
+   * Scrub smoothness (1 = default, higher = smoother/slower)
+   */
+  scrub?: number
+}>()
+
+const emit = defineEmits<{
+  'panel-change': [index: number]
+}>()
+
+const { gsap } = useGsap()
+
+const sectionRef = ref<HTMLElement | null>(null)
+const trackRef = ref<HTMLElement | null>(null)
+
+let cleanup: (() => void) | null = null
+
+onMounted(() => {
+  if (!sectionRef.value || !trackRef.value) return
+
+  const track = trackRef.value
+  const trackWidth = track.scrollWidth - window.innerWidth
+
+  const tween = gsap.to(track, {
+    scrollTrigger: {
+      trigger: sectionRef.value,
+      start: 'top top',
+      end: `+=${trackWidth}`,
+      pin: true,
+      scrub,
+      anticipatePin: 1,
+      onUpdate: (self) => {
+        const panels = track.querySelectorAll(':scope > *')
+        if (panels.length > 0) {
+          const index = Math.round(self.progress * (panels.length - 1))
+          emit('panel-change', index)
+        }
+      },
+    },
+    x: -trackWidth,
+    ease: 'none',
+  })
+
+  cleanup = () => tween.kill()
+})
+
+onUnmounted(() => {
+  cleanup?.()
+  cleanup = null
+})
+</script>
+
+<template>
+  <section ref="sectionRef" class="motion-horizontal-scroll h-screen overflow-hidden">
+    <div ref="trackRef" class="h-full flex items-center will-change-transform">
+      <slot />
+    </div>
+  </section>
+</template>

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

@@ -0,0 +1,77 @@
+<script setup lang="ts">
+const { duration = 200, scrub = 0.5 } = defineProps<{
+  /**
+   * Pin duration as a percentage of viewport height (200 = 2× viewport height)
+   */
+  duration?: number
+  /**
+   * Scrub smoothness for card reveals
+   */
+  scrub?: number
+}>()
+
+const { gsap, ScrollTrigger } = useGsap()
+
+const sectionRef = ref<HTMLElement | null>(null)
+const contentRef = ref<HTMLElement | null>(null)
+
+const cleanups: Array<() => void> = []
+
+onMounted(() => {
+  if (!sectionRef.value || !contentRef.value) return
+
+  const endOffset = (duration * window.innerHeight) / 100
+  const endValue = `+=${endOffset}`
+
+  // Pin the section
+  const pinSt = ScrollTrigger.create({
+    trigger: sectionRef.value,
+    start: 'top top',
+    end: endValue,
+    pin: true,
+    pinSpacing: true,
+  })
+  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 })
+
+    const startProgress = i / total
+    const endProgress = (i + 0.5) / total
+
+    const tween = gsap.to(item, {
+      scrollTrigger: {
+        trigger: sectionRef.value,
+        start: 'top top',
+        end: endValue,
+        scrub,
+      },
+      keyframes: [
+        { opacity: 0, y: 60, scale: 0.9, duration: startProgress },
+        { opacity: 1, y: 0, scale: 1, duration: endProgress - startProgress },
+        { opacity: 1, y: 0, scale: 1, duration: 1 - endProgress },
+      ],
+      ease: 'none',
+    })
+    cleanups.push(() => tween.kill())
+  })
+})
+
+onUnmounted(() => {
+  cleanups.forEach((fn) => fn())
+  cleanups.length = 0
+})
+</script>
+
+<template>
+  <section ref="sectionRef" class="motion-pinned-section h-screen relative">
+    <div ref="contentRef" class="h-full flex items-center justify-center">
+      <slot />
+    </div>
+  </section>
+</template>

package/layers/motion/app/components/Motion/ScrollProgress.vue

@@ -44,16 +44,6 @@ const props = withDefaults(
 const { progress } = useSmoothScroll()
 
 const percentage = computed(() => Math.round(progress.value * 100))
-
-// For circular progress
-const radius = computed(() => (props.size - props.strokeWidth) / 2)
-const circumference = computed(() => 2 * Math.PI * radius.value)
-const strokeDasharray = computed(
-  () => `${progress.value * circumference.value} ${circumference.value}`
-)
-
-// Generate gradient ID
-const gradientId = `scroll-progress-gradient-${Math.random().toString(36).slice(2, 9)}`
 </script>
 
 <template>
@@ -77,51 +67,13 @@ const gradientId = `scroll-progress-gradient-${Math.random().toString(36).slice(
   </div>
 
   <!-- Circular Progress -->
-  <div
+  <ProgressCircular
     v-else
-    class="motion-scroll-progress-circular relative inline-flex items-center justify-center"
-  >
-    <svg :width="size" :height="size" class="-rotate-90" :viewBox="`0 0 ${size} ${size}`">
-      <!-- Background circle -->
-      <circle
-        :cx="size / 2"
-        :cy="size / 2"
-        :r="radius"
-        fill="none"
-        :stroke="bgColor"
-        :stroke-width
-      />
-      <!-- Progress circle -->
-      <circle
-        :cx="size / 2"
-        :cy="size / 2"
-        :r="radius"
-        fill="none"
-        :stroke="`url(#${gradientId})`"
-        :stroke-width
-        stroke-linecap="round"
-        :stroke-dasharray
-        class="transition-[stroke-dasharray] duration-100"
-      />
-      <defs>
-        <linearGradient :id="gradientId" x1="0%" y1="0%" x2="100%" y2="0%">
-          <stop offset="0%" :style="`stop-color: ${colors[0]}`" />
-          <stop offset="50%" :style="`stop-color: ${colors[1]}`" />
-          <stop offset="100%" :style="`stop-color: ${colors[2]}`" />
-        </linearGradient>
-      </defs>
-    </svg>
-    <span
-      v-if="showPercentage"
-      class="absolute inset-0 flex items-center justify-center text-2xl font-bold tabular-nums"
-    >
-      {{ percentage }}%
-    </span>
-  </div>
+    :progress="progress"
+    :size
+    :stroke-width="strokeWidth"
+    :show-percentage="showPercentage"
+    :colors
+    :bg-color="bgColor"
+  />
 </template>
-
-<style scoped>
-.tabular-nums {
-  font-variant-numeric: tabular-nums;
-}
-</style>

package/layers/motion/app/components/Motion/ScrollScene.vue

@@ -0,0 +1,121 @@
+<script setup lang="ts">
+import type { ScrollSceneContext } from '../../composables/useScrollSteps'
+import { SCROLL_SCENE_KEY } from '../../composables/useScrollSteps'
+
+const {
+  name,
+  start = 'top top',
+  end = '+=200%',
+  pin = true,
+  scrub = 1,
+  markers = false,
+} = defineProps<{
+  /**
+   * Unique name for this scene (for debugging)
+   */
+  name: string
+  /**
+   * ScrollTrigger start position
+   */
+  start?: string
+  /**
+   * ScrollTrigger end position (e.g. '+=200%' = 2 viewport heights past start)
+   */
+  end?: string
+  /**
+   * Pin the section while scroll advances
+   */
+  pin?: boolean
+  /**
+   * Scrub smoothness: true | number | false
+   */
+  scrub?: boolean | number
+  /**
+   * Show GSAP ScrollTrigger markers (debug)
+   */
+  markers?: boolean
+}>()
+
+const emit = defineEmits<{
+  enter: []
+  leave: []
+  progress: [value: number]
+}>()
+
+const { ScrollTrigger } = useGsap()
+
+const containerRef = ref<HTMLElement | null>(null)
+const progress = ref(0)
+const active = ref(false)
+
+// Step registration
+const registeredSteps = ref(new Set<number>())
+const stepCount = computed(() =>
+  registeredSteps.value.size > 0 ? Math.max(...registeredSteps.value) + 1 : 0
+)
+
+function registerStep(index: number) {
+  registeredSteps.value = new Set([...registeredSteps.value, index])
+}
+
+function unregisterStep(index: number) {
+  const next = new Set(registeredSteps.value)
+  next.delete(index)
+  registeredSteps.value = next
+}
+
+provide<ScrollSceneContext>(SCROLL_SCENE_KEY, {
+  progress,
+  active,
+  name,
+  stepCount,
+  registerStep,
+  unregisterStep,
+})
+
+let st: { kill: () => void } | null = null
+
+onMounted(() => {
+  if (!containerRef.value) return
+
+  st = ScrollTrigger.create({
+    trigger: containerRef.value,
+    start,
+    end,
+    pin,
+    scrub,
+    markers,
+    onUpdate: (self) => {
+      progress.value = self.progress
+      emit('progress', self.progress)
+    },
+    onEnter: () => {
+      active.value = true
+      emit('enter')
+    },
+    onLeave: () => {
+      active.value = false
+      emit('leave')
+    },
+    onEnterBack: () => {
+      active.value = true
+      emit('enter')
+    },
+    onLeaveBack: () => {
+      active.value = false
+      emit('leave')
+    },
+  })
+})
+
+onUnmounted(() => {
+  st?.kill()
+  st = null
+})
+</script>
+
+<template>
+  <div ref="containerRef" class="motion-scroll-scene">
+    <slot :progress="progress" :active="active" />
+  </div>
+</template>

package/layers/motion/app/components/Motion/ScrollStep.vue

@@ -0,0 +1,45 @@
+<script setup lang="ts">
+import type { ScrollSceneContext } from '../../composables/useScrollSteps'
+import { SCROLL_SCENE_KEY } from '../../composables/useScrollSteps'
+
+const { index } = defineProps<{
+  /**
+   * Zero-based step index within the parent MotionScrollScene
+   */
+  index: number
+}>()
+
+const emit = defineEmits<{
+  enter: []
+  leave: []
+}>()
+
+const scene = inject<ScrollSceneContext>(SCROLL_SCENE_KEY)
+
+onMounted(() => scene?.registerStep(index))
+onUnmounted(() => scene?.unregisterStep(index))
+
+const isActive = computed(() => {
+  if (!scene) return index === 0
+  const total = scene.stepCount.value
+  if (total === 0) return false
+  const stepSize = 1 / total
+  const start = index * stepSize
+  const end = (index + 1) * stepSize
+  // Last step stays active at progress === 1
+  return scene.progress.value >= start && (index === total - 1 || scene.progress.value < end)
+})
+
+const wasActive = ref(false)
+watch(isActive, (active) => {
+  if (active && !wasActive.value) emit('enter')
+  else if (!active && wasActive.value) emit('leave')
+  wasActive.value = active
+})
+</script>
+
+<template>
+  <div class="motion-scroll-step" :class="{ 'is-active': isActive }" :data-step="index">
+    <slot :is-active="isActive" />
+  </div>
+</template>

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

@@ -17,73 +17,44 @@ const props = withDefaults(
      * Animation duration
      */
     duration?: number
-    /**
-     * Trigger on scroll
-     */
-    scrollTrigger?: boolean
     /**
      * Start position for scroll trigger
      */
     start?: string
   }>(),
-  {
-    type: 'chars',
-    stagger: 0.03,
-    duration: 0.8,
-    scrollTrigger: true,
-    start: 'top 80%',
-  }
+  { type: 'chars', stagger: 0.03, duration: 0.8, start: 'top 80%' }
 )
 
-const { gsap } = useGsap()
-const containerRef = ref<HTMLElement | null>(null)
-
-const splitContent = computed(() => {
-  if (props.type === 'chars') {
-    return props.text.split('').map((char) => (char === ' ' ? '\u00A0' : char))
-  } else if (props.type === 'words') {
-    return props.text.split(' ')
-  }
-  return [props.text]
-})
-
-onMounted(() => {
-  if (!containerRef.value) return
-
-  const elements = containerRef.value.querySelectorAll('.reveal-item')
-
-  const animationConfig: gsap.TweenVars = {
-    y: 40,
-    opacity: 0,
-    rotateX: -90,
-    duration: props.duration,
-    stagger: props.stagger,
-    ease: 'power3.out',
-  }
-
-  if (props.scrollTrigger) {
-    animationConfig.scrollTrigger = {
-      trigger: containerRef.value,
-      start: props.start,
-      toggleActions: 'play none none none',
-    }
-  }
-
-  gsap.from(elements, animationConfig)
-})
+const animBinding = computed(() => ({
+  y: 40,
+  opacity: 0,
+  rotateX: -90,
+  stagger: props.stagger,
+  duration: props.duration,
+  ease: 'power3.out',
+  start: props.start,
+}))
 </script>
 
 <template>
-  <span ref="containerRef" class="motion-text-reveal">
-    <span
-      v-for="(item, index) in splitContent"
-      :key="index"
-      class="reveal-item"
-      :class="{ 'mr-[0.25em]': type === 'words' && index < splitContent.length - 1 }"
-    >
-      {{ item }}
-    </span>
-  </span>
+  <span
+    v-if="type === 'chars'"
+    v-gsap.whenVisible.once.splitText.chars.from="animBinding"
+    class="motion-text-reveal"
+    >{{ text }}</span
+  >
+  <span
+    v-else-if="type === 'words'"
+    v-gsap.whenVisible.once.splitText.words.from="animBinding"
+    class="motion-text-reveal"
+    >{{ text }}</span
+  >
+  <span
+    v-else
+    v-gsap.whenVisible.once.splitText.lines.from="animBinding"
+    class="motion-text-reveal"
+    >{{ text }}</span
+  >
 </template>
 
 <style scoped>
@@ -92,10 +63,4 @@ onMounted(() => {
   flex-wrap: wrap;
   perspective: 1000px;
 }
-
-.reveal-item {
-  display: inline-block;
-  transform-origin: center bottom;
-  will-change: transform, opacity;
-}
 </style>

package/layers/motion/app/composables/useScrollSteps.ts

@@ -0,0 +1,41 @@
+import type { ComputedRef, Ref } from 'vue'
+
+export const SCROLL_SCENE_KEY = Symbol('motionScrollScene')
+
+export interface ScrollSceneContext {
+  progress: Ref<number>
+  active: Ref<boolean>
+  name: string
+  stepCount: ComputedRef<number>
+  registerStep: (index: number) => void
+  unregisterStep: (index: number) => void
+}
+
+/**
+ * Step/waypoint state tracking — must be used inside a MotionScrollScene.
+ *
+ * @example
+ * const { currentStep, isActive, stepProgress } = useScrollSteps(3)
+ * // currentStep: 0 | 1 | 2 based on scene progress
+ */
+export function useScrollSteps(total: number) {
+  const scene = inject<ScrollSceneContext>(SCROLL_SCENE_KEY)
+
+  const sceneProgress = computed(() => scene?.progress.value ?? 0)
+
+  const currentStep = computed(() =>
+    Math.min(Math.floor(sceneProgress.value * total), total - 1)
+  )
+
+  function isActive(index: number): boolean {
+    return currentStep.value === index
+  }
+
+  function stepProgress(index: number): number {
+    const stepSize = 1 / total
+    const start = index * stepSize
+    return Math.max(0, Math.min(1, (sceneProgress.value - start) / stepSize))
+  }
+
+  return { currentStep, isActive, stepProgress }
+}

package/layers/motion/app/composables/useSectionProgress.ts

@@ -0,0 +1,58 @@
+import type { MaybeRef } from 'vue'
+
+interface SectionProgressOptions {
+  start?: string
+  end?: string
+  markers?: boolean
+}
+
+/**
+ * Section-local scroll progress (0–1) scoped to a given element.
+ *
+ * @example
+ * const sectionRef = ref<HTMLElement | null>(null)
+ * const { progress, active, entering, leaving } = useSectionProgress(sectionRef, {
+ *   start: 'top top',
+ *   end: '+=200%',
+ * })
+ */
+export function useSectionProgress(
+  trigger: MaybeRef<HTMLElement | null>,
+  options: SectionProgressOptions = {}
+) {
+  const { ScrollTrigger } = useGsap()
+  const { direction } = useSmoothScroll()
+
+  const progress = ref(0)
+  const active = ref(false)
+  const entering = computed(() => active.value && direction.value > 0)
+  const leaving = computed(() => active.value && direction.value < 0)
+
+  let st: { kill: () => void } | null = null
+
+  onMounted(() => {
+    const el = unref(trigger)
+    if (!el) return
+
+    st = ScrollTrigger.create({
+      trigger: el,
+      start: options.start ?? 'top top',
+      end: options.end ?? '+=100%',
+      markers: options.markers ?? false,
+      onUpdate: (self) => {
+        progress.value = self.progress
+      },
+      onEnter: () => { active.value = true },
+      onLeave: () => { active.value = false },
+      onEnterBack: () => { active.value = true },
+      onLeaveBack: () => { active.value = false },
+    })
+  })
+
+  onUnmounted(() => {
+    st?.kill()
+    st = null
+  })
+
+  return { progress, active, entering, leaving }
+}

package/layers/motion/app/composables/useSmoothScroll.ts

@@ -1,3 +1,4 @@
+import type { Ref } from 'vue'
 import type LocomotiveScroll from 'locomotive-scroll'
 
 interface ScrollToOptions {
@@ -23,9 +24,9 @@ interface ScrollToOptions {
 export function useSmoothScroll() {
   const nuxtApp = useNuxtApp()
 
-  // Get the Locomotive Scroll instance and reactive state from the plugin
+  // Get the Locomotive Scroll instance from the reactive ref provided by the plugin
   const locomotiveScroll = computed<LocomotiveScroll | undefined>(
-    () => nuxtApp.$locomotiveScroll as LocomotiveScroll | undefined
+    () => (nuxtApp.$locomotiveScroll as Ref<LocomotiveScroll | null>)?.value ?? undefined
   )
 
   // Reactive scroll state from the plugin

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

@@ -18,11 +18,11 @@ export default defineNuxtPlugin(() => {
     progress: 0,
   })
 
-  let instance: LocomotiveScroll | null = null
+  const instance = shallowRef<LocomotiveScroll | null>(null)
 
   function init() {
-    if (instance) return
-    instance = new LocomotiveScroll({
+    if (instance.value) return
+    instance.value = new LocomotiveScroll({
       lenisOptions: {
         lerp: 0.1,
         smoothWheel: true,
@@ -40,8 +40,8 @@ export default defineNuxtPlugin(() => {
   }
 
   function destroy() {
-    instance?.destroy()
-    instance = null
+    instance.value?.destroy()
+    instance.value = null
   }
 
   const router = useRouter()
@@ -62,7 +62,7 @@ export default defineNuxtPlugin(() => {
 
   return {
     provide: {
-      locomotiveScroll: readonly(instance),
+      locomotiveScroll: instance,
       scrollState,
     },
   }

package/layers/motion/nuxt.config.ts

@@ -8,6 +8,12 @@ export default defineNuxtConfig({
     '#layers/motion': import.meta.dirname,
   },
 
+  modules: ['v-gsap-nuxt'],
+
+  vgsap: {
+    composable: true,
+  },
+
   css: ['#layers/motion/app/assets/css/main.css'],
 
   compatibilityDate: '2026-01-30',

package/layers/motion/package.json

@@ -11,6 +11,7 @@
   },
   "dependencies": {
     "gsap": "^3.12.7",
-    "locomotive-scroll": "^5.0.0"
+    "locomotive-scroll": "^5.0.0",
+    "v-gsap-nuxt": "latest"
   }
 }