kmcom-nuxt-layers 6.2.1 → 6.4.0

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/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/app.config.ts

@@ -1,5 +1,7 @@
 import type { SiteConfig } from '#layers/core/app/types/site'
 
+import type { MastNavLink, MastNavTrigger, MastNavUi, SiteLogoConfig } from './types/nav'
+
 export default defineAppConfig({
   site: {
     title: '',
@@ -7,29 +9,50 @@ export default defineAppConfig({
     description: '',
   } satisfies SiteConfig,
   mastNav: {
-    links: [] as Array<{
-      id: string
-      label: string
-      to:
-        | string
-        | { name: string; params?: Record<string, unknown>; query?: Record<string, unknown> }
-    }>,
+    links: [] as MastNavLink[],
     scrollBehaviour: 'router' as 'smooth-scroll' | 'router',
+    // UButton props for <MastNav>; attrs on the component win
+    trigger: {
+      icon: 'lucide:menu',
+      color: 'neutral',
+      variant: 'ghost',
+      size: 'xl',
+    } as MastNavTrigger,
+    ui: {
+      content: 'bg-default text-default',
+      close: 'absolute top-4 right-4',
+      nav: 'flex flex-col items-center gap-2',
+      // Weight keys off aria-current so active and inactive never carry two font-* classes
+      link: 'cursor-pointer border-0 bg-transparent px-4 py-3 text-3xl tracking-widest uppercase transition-all font-light aria-[current=page]:font-normal',
+      linkActive: '',
+    } satisfies MastNavUi,
   },
+  siteLogo: {
+    stacked: true,
+    ui: { root: 'font-display leading-none tracking-tight', word: '' },
+    sizes: {
+      sm: 'text-step-1',
+      md: 'text-step-4',
+      lg: 'text-step-6',
+      display: 'text-step-display',
+    },
+  } satisfies SiteLogoConfig,
 })
 
 declare module '@nuxt/schema' {
   interface AppConfigInput {
     // `site` is already typed by core's own AppConfigInput augmentation — no need to redeclare it.
     mastNav?: {
-      links?: Array<{
-        id: string
-        label: string
-        to:
-          | string
-          | { name: string; params?: Record<string, unknown>; query?: Record<string, unknown> }
-      }>
+      links?: MastNavLink[]
       scrollBehaviour?: 'smooth-scroll' | 'router'
+      trigger?: MastNavTrigger
+      ui?: Partial<MastNavUi>
+    }
+    siteLogo?: {
+      stacked?: boolean
+      ui?: Partial<SiteLogoConfig['ui']>
+      /** Merged per key, so a site can retune one size without restating the others. */
+      sizes?: Partial<SiteLogoConfig['sizes']>
     }
   }
 }

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,17 +1,20 @@
 <script setup lang="ts">
+  import type { ButtonProps } from '@nuxt/ui'
+
+  // A UButton styled by `mastNav.trigger` in app.config; attrs (class, label, icon…) win.
+  // Positioning is the parent's call, e.g. `<MastNav class="fixed top-0 right-0" />`.
+  defineOptions({ inheritAttrs: false })
+
   const { open } = useMastNav()
-  const z = useGridConfig().useZIndex('dropdown')
+  // app.config types the trigger loosely (see MastNavTrigger); UButton validates the values
+  const trigger = ((useAppConfig().mastNav as { trigger?: unknown } | undefined)?.trigger ??
+    {}) as ButtonProps
 </script>
 
 <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"
-    :style="{ zIndex: z }"
-    @click="() => open()"
-  >
-    <slot name="icon">
-      <UIcon name="lucide:menu" class="size-7" />
-    </slot>
-  </button>
+  <UButton aria-label="Open navigation menu" v-bind="{ ...trigger, ...$attrs }" @click="open">
+    <template v-if="$slots.default" #default>
+      <slot />
+    </template>
+  </UButton>
 </template>

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

@@ -1,20 +1,61 @@
 <script setup lang="ts">
-  import type { MastNavLink } from '../../types/nav'
+  import type { MastNavLink, MastNavUi } from '../../types/nav'
 
-  const { open } = defineProps<{ open?: boolean }>()
+  // Render once, in the layout. Behaviour lives here (dialog, scroll lock via useMastNav,
+  // smooth-scroll vs router, active link); the look comes from `mastNav.ui`, `ui` and slots.
+  const {
+    open = undefined,
+    links = undefined,
+    ui = undefined,
+  } = defineProps<{
+    /** Manual control; omit to follow useMastNav().isOpen. */
+    open?: boolean
+    /** Replaces `mastNav.links`, e.g. filtered by the site's own page flags. */
+    links?: MastNavLink[]
+    /** Per-key override of `mastNav.ui` (strings replace, no class merging). */
+    ui?: Partial<MastNavUi>
+  }>()
   const emit = defineEmits<{
     'update:open': [value: boolean]
     close: []
   }>()
 
-  const { links, scrollBehaviour } = useAppConfig().mastNav as {
+  const config = useAppConfig().mastNav as {
     links: MastNavLink[]
-    scrollBehaviour: string
+    scrollBehaviour: 'smooth-scroll' | 'router'
+    ui: MastNavUi
   }
+  const classes = computed(() => ({ ...config.ui, ...ui }))
+  const visibleLinks = computed(() => (links ?? config.links).filter((link) => !link.hidden))
+
   const activeSection = useState<string>('activeSection', () => '')
   const route = useRoute()
-  const { close: closeNav } = useMastNav()
-  const { useZIndex } = useGridConfig()
+  const router = useRouter()
+  const { isOpen, close: closeNav } = useMastNav()
+  // On the smooth-scroll index every link routes to index, so only the section counts there
+  const smoothOnIndex = computed(
+    () => config.scrollBehaviour === 'smooth-scroll' && route.name === 'index'
+  )
+
+  function matchesRoute(link: MastNavLink) {
+    try {
+      return router.resolve(link.to).path === route.path
+    } catch {
+      return false // a named route that doesn't exist
+    }
+  }
+
+  const activeIds = computed(
+    () =>
+      new Set(
+        visibleLinks.value
+          .filter(
+            (link) =>
+              activeSection.value === link.id || (!smoothOnIndex.value && matchesRoute(link))
+          )
+          .map((link) => link.id)
+      )
+  )
 
   function dismiss() {
     emit('update:open', false)
@@ -22,8 +63,8 @@
     closeNav()
   }
 
-  function handleNav(link: MastNavLink) {
-    if (scrollBehaviour === 'smooth-scroll' && route.name === 'index') {
+  function navigate(link: MastNavLink) {
+    if (smoothOnIndex.value) {
       try {
         useSmoothScroll().scrollTo(`#${link.id}`)
       } catch {}
@@ -35,43 +76,52 @@
 </script>
 
 <template>
-  <Transition name="nav-modal">
-    <div
-      v-if="open"
-      class="bg-default text-default fixed inset-0 flex flex-col items-center justify-center"
-      :style="{ zIndex: useZIndex('modal') }"
-    >
-      <button
-        class="absolute top-[3vh] right-[5vw] cursor-pointer border-0 bg-transparent p-2"
-        aria-label="Close navigation"
-        @click="dismiss"
-      >
-        <UIcon name="lucide:x" class="size-7" />
-      </button>
+  <!-- UModal supplies the dialog role, focus trap, Escape and portal; the title stays
+       visually hidden because the content slot replaces the header. -->
+  <UModal
+    :open="open ?? isOpen"
+    fullscreen
+    title="Site navigation"
+    :ui="{ overlay: 'z-(--z-modal)', content: `${classes.content} z-(--z-modal)` }"
+    @update:open="(value) => !value && dismiss()"
+  >
+    <template #content>
+      <div class="relative flex h-full flex-col items-center justify-center">
+        <slot name="close" :close="dismiss">
+          <UButton
+            icon="lucide:x"
+            color="neutral"
+            variant="ghost"
+            size="xl"
+            aria-label="Close navigation"
+            :class="classes.close"
+            @click="dismiss"
+          />
+        </slot>
 
-      <LinksGroup tag="nav" class="flex flex-col items-center gap-2">
-        <button
-          v-for="link in links"
-          :key="link.id"
-          class="cursor-pointer border-0 bg-transparent px-4 py-3 text-3xl tracking-widest uppercase transition-all"
-          :class="activeSection === link.id ? 'font-normal' : 'font-light'"
-          @click="() => handleNav(link)"
-        >
-          {{ link.label }}
-        </button>
-      </LinksGroup>
-    </div>
-  </Transition>
-</template>
+        <slot name="header" />
 
-<style scoped>
-  .nav-modal-enter-active,
-  .nav-modal-leave-active {
-    transition: opacity 300ms ease;
-  }
+        <HoverDimGroup tag="nav" :class="classes.nav">
+          <template v-for="link in visibleLinks" :key="link.id">
+            <slot
+              name="link"
+              :link
+              :active="activeIds.has(link.id)"
+              :navigate="() => navigate(link)"
+            >
+              <button
+                :class="[classes.link, activeIds.has(link.id) && classes.linkActive]"
+                :aria-current="activeIds.has(link.id) ? 'page' : undefined"
+                @click="() => navigate(link)"
+              >
+                {{ link.label }}
+              </button>
+            </slot>
+          </template>
+        </HoverDimGroup>
 
-  .nav-modal-enter-from,
-  .nav-modal-leave-to {
-    opacity: 0;
-  }
-</style>
+        <slot name="footer" />
+      </div>
+    </template>
+  </UModal>
+</template>

package/layers/structure/navigation/app/components/Site/Logo.vue

@@ -0,0 +1,35 @@
+<script setup lang="ts">
+  import type { SiteLogoConfig, SiteLogoSize } from '../../types/nav'
+
+  // The site wordmark from `site.title`, sized on the step scale. Look comes from `siteLogo` in
+  // app.config; `ui` overrides per instance. Replaces the deprecated SiteTitle/SiteSubtitle.
+  const {
+    as = 'span',
+    size = 'sm',
+    stacked = undefined,
+    ui = undefined,
+  } = defineProps<{
+    as?: string
+    size?: SiteLogoSize
+    /** One word per line. Defaults to `siteLogo.stacked`. */
+    stacked?: boolean
+    ui?: Partial<SiteLogoConfig['ui']>
+  }>()
+
+  const config = useAppConfig().siteLogo as SiteLogoConfig
+  const site = useSite()
+  const isStacked = computed(() => stacked ?? config.stacked)
+</script>
+
+<template>
+  <component :is="as" :class="[ui?.root ?? config.ui.root, config.sizes[size]]">
+    <slot :words="site.titleWords" :title="site.title">
+      <span
+        v-for="(word, i) in site.titleWords"
+        :key="i"
+        :class="[isStacked && 'block', ui?.word ?? config.ui.word]"
+        >{{ word }}{{ !isStacked && i < site.titleWords.length - 1 ? ' ' : '' }}</span
+      >
+    </slot>
+  </component>
+</template>

package/layers/structure/navigation/app/components/Site/Subtitle.vue

@@ -1,4 +1,14 @@
 <script setup lang="ts">
+  /**
+   * @deprecated Render `useSite().subtitleWords` directly. 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] <SiteSubtitle> is deprecated — render useSite().subtitleWords directly.'
+    )
+
   const site = useSite()
 </script>
 

package/layers/structure/navigation/app/components/Site/Title.vue

@@ -1,4 +1,12 @@
 <script setup lang="ts">
+  /**
+   * @deprecated Use `<SiteLogo :stacked="false">` (or `useSite().titleWords`). Remove in the
+   * next major.
+   */
+  if (import.meta.dev)
+    // eslint-disable-next-line no-console -- one-time deprecation notice, dev only
+    console.warn('[navigation] <SiteTitle> is deprecated — use <SiteLogo>.')
+
   const site = useSite()
 </script>