kmcom-nuxt-layers 1.6.38 → 1.6.40

package/docs/UPAGE-GRID-INTEGRATION.md

@@ -0,0 +1,186 @@
+# UPage + Swiss Grid Integration
+
+## The Problem
+
+`<LayoutMain>` renders `<main class="mastmain">` which sets:
+
+```css
+.mastmain {
+  grid-auto-rows: calc((100vh - 11 * gap) / 12); /* ≈ 8.5vh per row */
+}
+```
+
+Every direct child that doesn't explicitly span rows becomes ~8.5vh tall. `<UPage>` and Nuxt UI's page components (`UPageSection`, `UPageHero`, etc.) don't span rows — so they collapse.
+
+`.basesection` fixes this for `<LayoutSection>` by spanning 12 rows:
+
+```css
+.basesection {
+  grid-row: span 12; /* 12 × 8.5vh ≈ 100vh */
+}
+```
+
+`<UPage>` has no equivalent. It's designed for document flow, not a fixed-row grid.
+
+---
+
+## Approaches
+
+### Option A — `minmax` on `grid-auto-rows` (Recommended)
+
+**Change in `grids.css`:**
+
+```css
+.mastmain {
+  /* Before */
+  grid-auto-rows: var(--grid-row-height);
+
+  /* After — allow rows to grow beyond their minimum */
+  grid-auto-rows: minmax(var(--grid-row-height), auto);
+}
+```
+
+The mobile breakpoint already uses this. Apply it at all breakpoints.
+
+**What changes:**
+- `<LayoutSection>` spanning 12 rows = at least `12 × 8.5vh ≈ 100vh` (min preserved)
+- `<UPage>` in a single row = auto-sized to its content height
+- Column alignment is fully preserved
+
+**Trade-off:** `rowStart` placement in `<LayoutGridItem>` becomes less predictable when rows above it grow beyond their minimum. `rowSpan` presets are unaffected.
+
+**Implementation:** One-line CSS change in the layout layer source.
+
+---
+
+### Option B — `display: contents` on UPage
+
+Configure `<UPage>` to be transparent to the grid so its children participate directly:
+
+```ts
+// In frontend app.config.ts, override the layout layer's UPage config:
+ui: {
+  page: {
+    root: 'col-span-full [display:contents]',
+  },
+}
+```
+
+With `display: contents`, `<UPage>` generates no box — its children (`UPageHero`, `UPageSection`, etc.) become direct grid items in `mastmain`.
+
+**What changes:**
+- `<UPage>` styling is effectively gone (use with care)
+- Each child component becomes a grid item and needs its own column/row spanning
+- Requires configuring `UPageSection`, `UPageHero`, etc. similarly
+
+**Trade-off:** You lose `<UPage>`'s layout structure. Works best when you're using it purely as a semantic grouping with no visual styling.
+
+---
+
+### Option C — `<LayoutPage>` component (Hybrid mode)
+
+A new component that gives pages an explicit choice between Swiss Grid and normal document flow:
+
+```vue
+<!-- layers/layout/app/components/Layout/Page/index.vue -->
+<script setup lang="ts">
+interface Props {
+  mode?: 'swiss' | 'flow'
+}
+const { mode = 'swiss' } = defineProps<Props>()
+</script>
+
+<template>
+  <!-- Swiss: children participate directly in mastmain grid (use LayoutSection) -->
+  <template v-if="mode === 'swiss'">
+    <slot />
+  </template>
+
+  <!-- Flow: UPage mode — auto-height row that fills content -->
+  <div
+    v-else
+    class="col-span-full"
+    style="grid-row: auto / span 999; height: max-content; min-height: 0"
+  >
+    <UPage>
+      <slot />
+    </UPage>
+  </div>
+</template>
+```
+
+Usage:
+
+```vue
+<!-- Swiss Grid page -->
+<template>
+  <LayoutPage>
+    <LayoutSection full-height>
+      <LayoutGridItem preset="centered">
+        <h1>Title</h1>
+      </LayoutGridItem>
+    </LayoutSection>
+  </LayoutPage>
+</template>
+
+<!-- UPage page inside LayoutMain -->
+<template>
+  <LayoutPage mode="flow">
+    <UPageHero title="About" />
+    <UPageSection>...</UPageSection>
+  </LayoutPage>
+</template>
+```
+
+**Trade-off:** `span 999` is an escape hatch — it works because CSS Grid clamps spans to the available track count. It's pragmatic but not semantically clean. Requires the component to live in the layout layer source.
+
+---
+
+### Option D — Per-page `<LayoutMain tag="div">` opt-in
+
+Don't apply `<LayoutMain>` in the layouts at all. Let pages that want the Swiss Grid add it themselves inside their template:
+
+```vue
+<!-- A Swiss Grid page — no UPage -->
+<template>
+  <LayoutMain tag="div">
+    <LayoutSection full-height>
+      <LayoutGridItem preset="hero">
+        <h1>Home</h1>
+      </LayoutGridItem>
+    </LayoutSection>
+  </LayoutMain>
+</template>
+
+<!-- A normal page — uses UMain from the layout, no grid involvement -->
+<template>
+  <UPage>
+    <UPageHero title="About" />
+  </UPage>
+</template>
+```
+
+**This is the current approach after the revert.** The layout layer is available everywhere but not globally applied. The `mastmain` CSS class exists — any element can opt in via `class="mastmain"` or `<LayoutMain tag="div">`.
+
+**Trade-off:** No automatic column alignment across pages. Pages must explicitly adopt the grid.
+
+---
+
+## Recommendation
+
+**Short-term (no code changes required):** Option D — current approach. Build new sections using `<LayoutSection>` / `<LayoutGridItem>` inside pages that want the Swiss Grid. Existing `<UPage>` pages are untouched.
+
+**Medium-term (one CSS change):** Option A — change `grid-auto-rows` to `minmax(var(--grid-row-height), auto)` in `grids.css`. This makes `<LayoutMain>` compatible with both Swiss Grid sections and UPage content at the same time, unlocking global application in the layouts with zero page changes.
+
+**Long-term:** Migrate pages to the Swiss Grid pattern (no `<UPage>`) to take full advantage of precise row placement and the full 18-column subgrid system.
+
+---
+
+## CSS Grid Behaviour Reference
+
+| Scenario | `grid-auto-rows: 8.5vh` | `grid-auto-rows: minmax(8.5vh, auto)` |
+|---|---|---|
+| `<LayoutSection>` (spans 12 rows) | ✅ Exactly 100vh | ✅ At least 100vh, grows with content |
+| `<UPage>` (1 auto row) | ❌ Collapsed to 8.5vh | ✅ Grows to content height |
+| `<LayoutGridItem rowStart="3">` | ✅ Predictable position | ⚠️ Position shifts if rows above grew |
+| `<LayoutGridItem rowSpan="6">` | ✅ 6 × 8.5vh = 51vh | ✅ At least 6 × 8.5vh |

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

@@ -1,142 +1,142 @@
 <script setup lang="ts">
-const props = withDefaults(
-  defineProps<{
-    /**
-     * Base animation speed in pixels per second
-     */
-    speed?: number
-    /**
-     * Direction of scroll
-     */
-    direction?: 'left' | 'right'
-    /**
-     * Pause animation on hover
-     */
-    pauseOnHover?: boolean
-    /**
-     * Gap between repeated items
-     */
-    gap?: string
-    /**
-     * Enable velocity-based speed (scroll velocity affects marquee speed)
-     */
-    velocityBased?: boolean
-    /**
-     * How much scroll velocity affects speed (0-1)
-     * 0 = no effect, 1 = velocity fully controls speed
-     */
-    velocitySensitivity?: number
-    /**
-     * Reverse direction based on scroll direction
-     */
-    velocityDirection?: boolean
-    /**
-     * Minimum speed multiplier when using velocity
-     */
-    minSpeed?: number
-    /**
-     * Maximum speed multiplier when using velocity
-     */
-    maxSpeed?: number
-  }>(),
-  {
-    speed: 50,
-    direction: 'left',
-    pauseOnHover: true,
-    gap: '2rem',
-    velocityBased: false,
-    velocitySensitivity: 0.5,
-    velocityDirection: false,
-    minSpeed: 0.2,
-    maxSpeed: 5,
-  }
-)
-
-const { gsap } = useGsap()
-const { velocity: scrollVelocity, direction: scrollDirection } = useSmoothScroll()
-
-const containerRef = ref<HTMLElement | null>(null)
-const contentRef = ref<HTMLElement | null>(null)
-const tweenRef = ref<gsap.core.Tween | null>(null)
-
-const isPaused = ref(false)
-const currentTimeScale = ref(1)
-
-onMounted(() => {
-  if (!containerRef.value || !contentRef.value) return
-
-  const content = contentRef.value
-  const contentWidth = content.offsetWidth
-
-  // Set up the infinite scroll animation
-  tweenRef.value = gsap.to(content, {
-    x: props.direction === 'left' ? -contentWidth / 2 : contentWidth / 2,
-    duration: contentWidth / props.speed,
-    ease: 'none',
-    repeat: -1,
-    modifiers: {
-      x: gsap.utils.unitize((x) => {
-        const mod = contentWidth / 2
-        return props.direction === 'left' ? parseFloat(x) % mod : -Math.abs(parseFloat(x) % mod)
-      }),
-    },
+  const props = withDefaults(
+    defineProps<{
+      /**
+       * Base animation speed in pixels per second
+       */
+      speed?: number
+      /**
+       * Direction of scroll
+       */
+      direction?: 'left' | 'right'
+      /**
+       * Pause animation on hover
+       */
+      pauseOnHover?: boolean
+      /**
+       * Gap between repeated items
+       */
+      gap?: string
+      /**
+       * Enable velocity-based speed (scroll velocity affects marquee speed)
+       */
+      velocityBased?: boolean
+      /**
+       * How much scroll velocity affects speed (0-1)
+       * 0 = no effect, 1 = velocity fully controls speed
+       */
+      velocitySensitivity?: number
+      /**
+       * Reverse direction based on scroll direction
+       */
+      velocityDirection?: boolean
+      /**
+       * Minimum speed multiplier when using velocity
+       */
+      minSpeed?: number
+      /**
+       * Maximum speed multiplier when using velocity
+       */
+      maxSpeed?: number
+    }>(),
+    {
+      speed: 50,
+      direction: 'left',
+      pauseOnHover: true,
+      gap: '2rem',
+      velocityBased: false,
+      velocitySensitivity: 0.5,
+      velocityDirection: false,
+      minSpeed: 0.2,
+      maxSpeed: 5,
+    }
+  )
+
+  const { gsap } = useGsap()
+  const { velocity: scrollVelocity, direction: scrollDirection } = useSmoothScroll()
+
+  const containerRef = ref<HTMLElement | null>(null)
+  const contentRef = ref<HTMLElement | null>(null)
+  const tweenRef = ref<gsap.core.Tween | null>(null)
+
+  const isPaused = ref(false)
+  const currentTimeScale = ref(1)
+
+  onMounted(() => {
+    if (!containerRef.value || !contentRef.value) return
+
+    const content = contentRef.value
+    const contentWidth = content.offsetWidth
+
+    // Set up the infinite scroll animation
+    tweenRef.value = gsap.to(content, {
+      x: props.direction === 'left' ? -contentWidth / 2 : contentWidth / 2,
+      duration: contentWidth / props.speed,
+      ease: 'none',
+      repeat: -1,
+      modifiers: {
+        x: gsap.utils.unitize((x) => {
+          const mod = contentWidth / 2
+          return props.direction === 'left' ? parseFloat(x) % mod : Math.abs(parseFloat(x) % mod)
+        }),
+      },
+    })
   })
-})
-
-// Watch velocity changes for velocity-based animation
-watch(
-  [scrollVelocity, scrollDirection],
-  ([vel, dir]) => {
-    if (!props.velocityBased || !tweenRef.value || isPaused.value) return
-
-    // Calculate velocity multiplier
-    const absVelocity = Math.abs(vel)
-    const velocityEffect = absVelocity * props.velocitySensitivity * 0.02
 
-    // Base multiplier from velocity magnitude
-    let multiplier = 1 + velocityEffect
+  // Watch velocity changes for velocity-based animation
+  watch(
+    [scrollVelocity, scrollDirection],
+    ([vel, dir]) => {
+      if (!props.velocityBased || !tweenRef.value || isPaused.value) return
+
+      // Calculate velocity multiplier
+      const absVelocity = Math.abs(vel)
+      const velocityEffect = absVelocity * props.velocitySensitivity * 0.02
+
+      // Base multiplier from velocity magnitude
+      let multiplier = 1 + velocityEffect
+
+      // Clamp to min/max
+      multiplier = Math.max(props.minSpeed, Math.min(props.maxSpeed, multiplier))
+
+      // Optionally reverse direction based on scroll direction
+      if (props.velocityDirection && dir !== 0) {
+        const baseDirection = props.direction === 'left' ? 1 : -1
+        multiplier *= dir * baseDirection
+      }
+
+      // Smoothly interpolate to target
+      gsap.to(currentTimeScale, {
+        value: multiplier,
+        duration: 0.3,
+        ease: 'power2.out',
+        onUpdate: () => {
+          if (tweenRef.value) {
+            tweenRef.value.timeScale(currentTimeScale.value)
+          }
+        },
+      })
+    },
+    { immediate: false }
+  )
 
-    // Clamp to min/max
-    multiplier = Math.max(props.minSpeed, Math.min(props.maxSpeed, multiplier))
+  onUnmounted(() => {
+    tweenRef.value?.kill()
+  })
 
-    // Optionally reverse direction based on scroll direction
-    if (props.velocityDirection && dir !== 0) {
-      const baseDirection = props.direction === 'left' ? 1 : -1
-      multiplier *= dir * baseDirection
+  function handleMouseEnter() {
+    if (props.pauseOnHover && tweenRef.value) {
+      gsap.to(tweenRef.value, { timeScale: 0, duration: 0.5 })
+      isPaused.value = true
     }
-
-    // Smoothly interpolate to target
-    gsap.to(currentTimeScale, {
-      value: multiplier,
-      duration: 0.3,
-      ease: 'power2.out',
-      onUpdate: () => {
-        if (tweenRef.value) {
-          tweenRef.value.timeScale(currentTimeScale.value)
-        }
-      },
-    })
-  },
-  { immediate: false }
-)
-
-onUnmounted(() => {
-  tweenRef.value?.kill()
-})
-
-function handleMouseEnter() {
-  if (props.pauseOnHover && tweenRef.value) {
-    gsap.to(tweenRef.value, { timeScale: 0, duration: 0.5 })
-    isPaused.value = true
   }
-}
 
-function handleMouseLeave() {
-  if (props.pauseOnHover && tweenRef.value) {
-    gsap.to(tweenRef.value, { timeScale: currentTimeScale.value, duration: 0.5 })
-    isPaused.value = false
+  function handleMouseLeave() {
+    if (props.pauseOnHover && tweenRef.value) {
+      gsap.to(tweenRef.value, { timeScale: currentTimeScale.value, duration: 0.5 })
+      isPaused.value = false
+    }
   }
-}
 </script>
 
 <template>

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

@@ -0,0 +1,147 @@
+<script setup lang="ts">
+  import type { ScrollTrigger as GSAPScrollTrigger } from 'gsap/ScrollTrigger'
+
+  interface VelocityMapping {
+    input: [number, number]
+    output: [number, number]
+  }
+
+  const {
+    texts = [],
+    velocity = 100,
+    className = '',
+    damping = 50,
+    stiffness = 400,
+    velocityMapping = { input: [0, 1000] as [number, number], output: [0, 5] as [number, number] },
+    pauseOnHover = false,
+    parallaxClassName = '',
+    scrollerClassName = '',
+    parallaxStyle = {},
+    scrollerStyle = {},
+  } = defineProps<{
+    texts?: string[]
+    velocity?: number
+    className?: string
+    damping?: number
+    stiffness?: number
+    velocityMapping?: VelocityMapping
+    pauseOnHover?: boolean
+    parallaxClassName?: string
+    scrollerClassName?: string
+    parallaxStyle?: Record<string, string | number>
+    scrollerStyle?: Record<string, string | number>
+  }>()
+
+  const { gsap, ScrollTrigger } = useGsap()
+  const { velocityFactor } = useMarqueeVelocity({ damping, stiffness, velocityMapping })
+
+  const containerRef = ref<HTMLElement[]>([])
+  const copyRefs = ref<HTMLSpanElement[]>([])
+
+  const { copyWidths, calculatedCopies } = useMarqueeCopies(
+    containerRef,
+    copyRefs,
+    computed(() => texts.length)
+  )
+
+  const baseX = ref<number[]>([])
+  const directionFactors = ref<number[]>([])
+  const isPaused = ref(false)
+
+  let scrollTriggerInstance: GSAPScrollTrigger | null = null
+  let animLastTime = 0
+
+  const wrap = (min: number, max: number, v: number): number => {
+    const range = max - min
+    if (range === 0) return min
+    return ((((v - min) % range) + range) % range) + min
+  }
+
+  const scrollTransforms = computed(() =>
+    texts.map((_, index) => {
+      const singleWidth = copyWidths.value[index]
+      if (!singleWidth) return '0px'
+      return `${wrap(-singleWidth, 0, baseX.value[index] ?? 0)}px`
+    })
+  )
+
+  const setCopyRef = (el: Element | ComponentPublicInstance | null, index: number) => {
+    if (el instanceof HTMLSpanElement) copyRefs.value[index] = el
+  }
+
+  function animate() {
+    if (isPaused.value) return
+
+    const now = performance.now()
+    const delta = animLastTime ? now - animLastTime : 16
+    animLastTime = now
+
+    texts.forEach((_, index) => {
+      const baseVelocity = index % 2 !== 0 ? -velocity : velocity
+      let moveBy = (directionFactors.value[index] ?? 1) * baseVelocity * (delta / 1000)
+
+      if (velocityFactor.value < 0) {
+        directionFactors.value[index] = -1
+      } else if (velocityFactor.value > 0) {
+        directionFactors.value[index] = 1
+      }
+
+      moveBy += (directionFactors.value[index] ?? 1) * moveBy * velocityFactor.value
+      baseX.value[index] = (baseX.value[index] ?? 0) + moveBy
+    })
+  }
+
+  onMounted(async () => {
+    await nextTick()
+
+    baseX.value = new Array(texts.length).fill(0)
+    directionFactors.value = new Array(texts.length).fill(1)
+    animLastTime = performance.now()
+
+    const firstContainer = containerRef.value[0]
+    if (firstContainer) {
+      scrollTriggerInstance = ScrollTrigger.create({
+        trigger: firstContainer,
+        start: 'top bottom',
+        end: 'bottom top',
+      })
+    }
+
+    gsap.ticker.add(animate)
+  })
+
+  onUnmounted(() => {
+    gsap.ticker.remove(animate)
+    scrollTriggerInstance?.kill()
+  })
+</script>
+
+<template>
+  <section
+    class="w-full overflow-x-hidden"
+    @mouseenter="isPaused = pauseOnHover"
+    @mouseleave="isPaused = false"
+  >
+    <div
+      v-for="(text, index) in texts"
+      :key="index"
+      ref="containerRef"
+      :class="`${parallaxClassName} relative w-full overflow-x-hidden overflow-y-visible`"
+      :style="parallaxStyle"
+    >
+      <div
+        :class="`${scrollerClassName} font-styles-logo flex py-2 text-center font-sans text-4xl font-medium tracking-[-0.02em] whitespace-nowrap text-neutral drop-shadow md:text-[5rem] md:leading-[5rem]`"
+        :style="{ transform: `translateX(${scrollTransforms[index] ?? '0px'})`, ...scrollerStyle }"
+      >
+        <span
+          v-for="spanIndex in calculatedCopies[index] ?? 15"
+          :key="spanIndex"
+          :ref="spanIndex === 1 ? (el) => setCopyRef(el, index) : undefined"
+          :class="`shrink-0 ${className} text-primary-500`"
+        >
+          {{ text }}&nbsp;
+        </span>
+      </div>
+    </div>
+  </section>
+</template>

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

@@ -0,0 +1,50 @@
+import type { MaybeRef } from 'vue'
+
+export function useMarqueeCopies(
+  containerRefs: Ref<HTMLElement[]>,
+  copyRefs: Ref<HTMLSpanElement[]>,
+  rowCount: MaybeRef<number>,
+) {
+  const copyWidths = ref<number[]>([])
+  const calculatedCopies = ref<number[]>([])
+
+  let debounceTimer: ReturnType<typeof setTimeout> | null = null
+
+  function calculate() {
+    const n = unref(rowCount)
+    for (let i = 0; i < n; i++) {
+      const copy = copyRefs.value[i]
+      const container = containerRefs.value[i]
+      if (!copy || !container) continue
+      const singleWidth = copy.offsetWidth
+      if (singleWidth === 0) continue
+      const effectiveWidth = Math.max(container.offsetWidth, window.innerWidth)
+      const minCopies = Math.ceil((effectiveWidth * 2.5) / singleWidth)
+      copyWidths.value[i] = singleWidth
+      calculatedCopies.value[i] = Math.max(minCopies, 8)
+    }
+  }
+
+  function debouncedCalculate() {
+    if (debounceTimer) clearTimeout(debounceTimer)
+    debounceTimer = setTimeout(() => {
+      calculate()
+      debounceTimer = null
+    }, 150)
+  }
+
+  onMounted(() => {
+    nextTick(() => {
+      calculate()
+      setTimeout(calculate, 100)
+    })
+    window.addEventListener('resize', debouncedCalculate, { passive: true })
+  })
+
+  onUnmounted(() => {
+    if (debounceTimer) clearTimeout(debounceTimer)
+    window.removeEventListener('resize', debouncedCalculate)
+  })
+
+  return { copyWidths, calculatedCopies }
+}

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

@@ -0,0 +1,44 @@
+import type { MaybeRef } from 'vue'
+
+interface VelocityMapping {
+  input: [number, number]
+  output: [number, number]
+}
+
+interface UseMarqueeVelocityOptions {
+  damping?: MaybeRef<number>
+  stiffness?: MaybeRef<number>
+  velocityMapping?: MaybeRef<VelocityMapping>
+}
+
+export function useMarqueeVelocity(opts: UseMarqueeVelocityOptions = {}) {
+  const { velocity: rawVelocity } = useSmoothScroll()
+  const { gsap } = useGsap()
+
+  const smoothVelocity = ref(0)
+  const velocityFactor = ref(0)
+
+  function tick() {
+    const damping = (unref(opts.damping) ?? 50) / 1000
+    const stiffness = (unref(opts.stiffness) ?? 400) / 1000
+    const mapping: VelocityMapping = unref(opts.velocityMapping) ?? {
+      input: [0, 1000],
+      output: [0, 5],
+    }
+
+    smoothVelocity.value += (rawVelocity.value - smoothVelocity.value) * stiffness
+    smoothVelocity.value *= 1 - damping
+
+    const inputRange = mapping.input[1] - mapping.input[0]
+    const outputRange = mapping.output[1] - mapping.output[0]
+    let t = (Math.abs(smoothVelocity.value) - mapping.input[0]) / inputRange
+    t = Math.max(0, Math.min(1, t))
+    velocityFactor.value = mapping.output[0] + t * outputRange
+    if (smoothVelocity.value < 0) velocityFactor.value *= -1
+  }
+
+  onMounted(() => gsap.ticker.add(tick))
+  onUnmounted(() => gsap.ticker.remove(tick))
+
+  return { velocityFactor }
+}

package/layers/motion/tsconfig.json

@@ -1,5 +1,6 @@
 {
   "extends": "../../apps/playground/tsconfig.json",
+
   "compilerOptions": {
     "strict": true
   },

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "kmcom-nuxt-layers",
   "private": false,
-  "version": "1.6.38",
+  "version": "1.6.40",
   "description": "Composable Nuxt 4 layers for building scalable Vue applications",
   "exports": {
     "./layers/core": "./layers/core/nuxt.config.ts",