kmcom-nuxt-layers 1.1.9 → 1.3.0

package/layers/layout/app/composables/useGridConfig.ts

@@ -1,4 +1,4 @@
-import type { GridConfig, GridPresetsItem } from '#layers/layout/app/types/layouts'
+import type { GridConfig, GridLayers, GridMode, GridPresetsItem } from '#layers/layout/app/types/layouts'
 
 interface LayoutLayerConfig {
   layoutLayer?: {
@@ -13,15 +13,42 @@ export function useGridConfig() {
   const appConfig = useAppConfig() as LayoutLayerConfig
   const gridConfig = computed(() => appConfig.layoutLayer?.ui?.grid)
 
+  /**
+   * Resolved layout mode. Derives from `mode` field first, then falls back to
+   * the legacy `enabled` boolean for backwards compatibility.
+   */
+  const mode = computed<GridMode>(() => {
+    const cfg = gridConfig.value
+    if (!cfg) return 'swiss'
+    if (cfg.mode) return cfg.mode
+    return cfg.enabled === false ? 'disabled' : 'swiss'
+  })
+
+  /** True when the Swiss Grid system is active. */
+  const isEnabled = computed(() => mode.value !== 'disabled')
+
   const getPreset = (name: string): GridPresetsItem | undefined => {
     const presets = gridConfig.value?.presets
     if (!presets) return undefined
     return presets[name as keyof typeof presets]
   }
 
+  /**
+   * Returns the z-index value for a named stacking layer.
+   *
+   * @example
+   * const zModal = useZIndex('modal') // → 400
+   */
+  const useZIndex = (layer: keyof GridLayers): number => {
+    return gridConfig.value?.layers?.[layer] ?? 0
+  }
+
   return {
     config: gridConfig,
     getPreset,
     layers: computed(() => gridConfig.value?.layers),
+    isEnabled,
+    mode,
+    useZIndex,
   }
 }

package/layers/layout/app/types/layouts.ts

@@ -7,28 +7,61 @@ export interface ResponsiveValue<T> {
 }
 
 export interface GridLayers {
+  /** Component/content at rest — z-index 0 */
   back: number
+  /** Standard interactive content — z-index 10 */
   mid: number
+  /** Elevated content, sticky elements — z-index 20 */
   front: number
+  /** Page-level overlays — z-index 30 */
   top: number
+  /** Site header / navigation bar — z-index 100 */
+  header: number
+  /** Dropdown menus, popovers — z-index 200 */
+  dropdown: number
+  /** Overlay backdrops — z-index 300 */
+  overlay: number
+  /** Modal dialogs — z-index 400 */
+  modal: number
+  /** Toast notifications — z-index 500 */
+  toast: number
 }
 
+export type GridContainerSize = 'content' | 'wide' | 'fluid' | 'full'
+export type GridDensity = 'compact' | 'normal' | 'relaxed'
+export type GridMode = 'swiss' | 'fluid' | 'disabled'
+
 export interface GridPresetsItem {
-  colStart: number | ResponsiveValue<number>
-  colSpan: number | ResponsiveValue<number>
+  colStart?: number | ResponsiveValue<number>
+  colSpan: number | 'full' | ResponsiveValue<number>
   rowStart?: number | ResponsiveValue<number>
   rowSpan?: number
+  /** Container size applied to the item's content */
+  container?: GridContainerSize
+  /** Gap override for this preset */
+  gap?: string
+  /** Vertical rhythm density for this preset */
+  density?: GridDensity
+  /** Vertical alignment (align-self) */
+  align?: 'start' | 'center' | 'end' | 'stretch'
+  /** Horizontal alignment (justify-self) */
+  justify?: 'start' | 'center' | 'end' | 'stretch'
 }
 
-export interface GridPresets {
-  hero: GridPresetsItem
-  centered: GridPresetsItem
-  fullWidth: GridPresetsItem
-  sidebar: GridPresetsItem
-  content: GridPresetsItem
-}
+export type GridPresets = Record<string, GridPresetsItem>
 
 export interface GridConfig {
+  /**
+   * Layout mode.
+   * - `'swiss'`    — Swiss Grid System (default)
+   * - `'fluid'`    — Container-query based auto-fit grid
+   * - `'disabled'` — Falls back to standard Nuxt UI layout
+   *
+   * Setting `enabled: false` is equivalent to `mode: 'disabled'` (backwards compat).
+   */
+  mode?: GridMode
+  /** @deprecated Use `mode: 'disabled'` instead. Kept for backwards compatibility. */
+  enabled?: boolean
   columns: ResponsiveValue<number>
   rowsPerSection: number
   rhythm: string

package/layers/layout/app.config.ts

@@ -1,8 +1,66 @@
 export default defineAppConfig({
+  /**
+   * Nuxt UI component theming — aligned to the Swiss Grid System.
+   *
+   * UHeader: removes the default max-width container so it spans the full
+   * viewport width, using clamp-based gutters that match the grid padding.
+   *
+   * UPage / UPage* components: participate as subgrid members so their
+   * columns align to the inherited mastmain grid lines.
+   *
+   * These overrides are additive and safe when the swiss grid is disabled —
+   * col-span-full / grid-cols-subgrid have no effect outside a grid context.
+   * The consuming app can override any of these via its own app.config.ts.
+   */
+  ui: {
+    header: {
+      container: 'max-w-full px-[clamp(1rem,2.5vw,2rem)]',
+    },
+
+    // UPage: transparent subgrid participant; left/center/right slots map
+    // to named column ranges on the 18-column grid (sidebar 4, content 10,
+    // right sidebar 4; all col-start values are explicit to avoid overlap)
+    page: {
+      root: 'col-span-full grid grid-cols-subgrid',
+      left: 'col-span-4',
+      center: 'col-start-5 col-span-10',
+      right: 'col-start-15 col-span-4',
+    },
+
+    // UPageBody: no opinionated padding — the grid and sections own spacing
+    pageBody: {
+      base: '',
+    },
+
+    // UPageGrid: inherits subgrid column lines; gap matches grid gap clamp
+    pageGrid: {
+      base: 'col-span-full grid grid-cols-subgrid gap-[clamp(0.75rem,1.5vw,1.5rem)]',
+    },
+
+    // UPageColumns: inherits subgrid column lines
+    pageColumns: {
+      base: 'col-span-full grid grid-cols-subgrid',
+    },
+  },
+
   layoutLayer: {
     ui: {
       // Swiss Grid System Configuration
       grid: {
+        /**
+         * Layout mode.
+         * - 'swiss'    — Swiss Grid System (default)
+         * - 'fluid'    — Container-query based auto-fit grid
+         * - 'disabled' — Falls back to standard UMain > UPage layout
+         */
+        mode: 'swiss',
+
+        /**
+         * @deprecated Use mode: 'disabled' instead. Kept for backwards compatibility.
+         * When false, acts as mode: 'disabled'.
+         */
+        enabled: true,
+
         // Core settings
         columns: { default: 6, md: 12, lg: 18 },
         rowsPerSection: 12,
@@ -10,28 +68,51 @@ export default defineAppConfig({
 
         // Z-index layers
         layers: {
+          // Base layers (swiss grid stacking)
           back: 0,
           mid: 10,
           front: 20,
           top: 30,
+          // UI stacking layers
+          header: 100,
+          dropdown: 200,
+          overlay: 300,
+          modal: 400,
+          toast: 500,
         },
 
         // Preset layouts for common patterns
         presets: {
-          hero: {
+          // Full-viewport hero: full width, all 12 rows
+          hero: { colSpan: 'full', rowSpan: 12 },
+
+          // Centered content column (equal margins both sides)
+          // lg: 3 + 12 + 3 = 18 ✓  |  md: 1 + 10 + 1 = 12 ✓
+          centered: {
             colStart: { default: 1, md: 2, lg: 4 },
             colSpan: { default: 6, md: 10, lg: 12 },
             rowSpan: 12,
           },
-          centered: {
-            colStart: { default: 1, md: 2, lg: 5 },
-            colSpan: { default: 6, md: 10, lg: 10 },
-            rowSpan: 12,
+
+          // Full width (all columns, no bleed)
+          fullWidth: { colSpan: 'full' },
+
+          // Narrow prose column (tighter reading width)
+          // lg: 4 + 10 + 4 = 18 ✓  |  md: 2 + 8 + 2 = 12 ✓
+          prose: {
+            colStart: { default: 1, md: 3, lg: 5 },
+            colSpan: { default: 6, md: 8, lg: 10 },
           },
-          fullWidth: {
-            colStart: 1,
-            colSpan: { default: 6, md: 12, lg: 18 },
+
+          // Wide content (generous width, minimal margins)
+          // lg: 1 + 16 + 1 = 18 ✓  |  md: 1 + 10 + 1 = 12 ✓
+          wide: {
+            colStart: { default: 1, md: 2, lg: 2 },
+            colSpan: { default: 6, md: 10, lg: 16 },
           },
+
+          // Sidebar + content pair (use together)
+          // sidebar: cols 1-4 (lg) | content: cols 5-18 (14 cols) → 4+14=18 ✓
           sidebar: {
             colStart: { default: 1, md: 1, lg: 1 },
             colSpan: { default: 6, md: 4, lg: 4 },
@@ -41,7 +122,8 @@ export default defineAppConfig({
             colSpan: { default: 6, md: 8, lg: 14 },
           },
 
-          // 50/50 vertical split (stacks on mobile)
+          // 50/50 vertical splits (stack on mobile)
+          // lg: 9+9=18 ✓  |  md: 6+6=12 ✓
           splitLeft: {
             colStart: 1,
             colSpan: { default: 6, md: 6, lg: 9 },
@@ -53,7 +135,8 @@ export default defineAppConfig({
             rowSpan: 12,
           },
 
-          // 25/75 split (stacks on mobile)
+          // 25/75 vertical splits (stack on mobile)
+          // lg: 5+13=18 ✓  |  md: 3+9=12 ✓
           quarterLeft: {
             colStart: 1,
             colSpan: { default: 6, md: 3, lg: 5 },
@@ -65,18 +148,29 @@ export default defineAppConfig({
             rowSpan: 12,
           },
 
-          // Horizontal 50/50 split (100vw × 50vh each)
-          halfTop: {
+          // 75/25 vertical splits (stack on mobile)
+          // lg: 13+5=18 ✓  |  md: 9+3=12 ✓
+          threeQuarterLeft: {
             colStart: 1,
-            colSpan: { default: 6, md: 12, lg: 18 },
-            rowStart: 1,
-            rowSpan: 6,
+            colSpan: { default: 6, md: 9, lg: 13 },
+            rowSpan: 12,
           },
-          halfBottom: {
-            colStart: 1,
-            colSpan: { default: 6, md: 12, lg: 18 },
-            rowStart: 7,
-            rowSpan: 6,
+          quarterRight: {
+            colStart: { default: 1, md: 10, lg: 14 },
+            colSpan: { default: 6, md: 3, lg: 5 },
+            rowSpan: 12,
+          },
+
+          // Horizontal 50/50 stacks (100vw × 50vh each)
+          halfTop: { colSpan: 'full', rowStart: 1, rowSpan: 6 },
+          halfBottom: { colSpan: 'full', rowStart: 7, rowSpan: 6 },
+
+          // Super centered: full-width, full-height, content perfectly centered
+          superCentered: {
+            colSpan: 'full',
+            rowSpan: 12,
+            align: 'center',
+            justify: 'center',
           },
         },
       },

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

@@ -10,7 +10,6 @@ export interface ScrollState {
 }
 
 export default defineNuxtPlugin(() => {
-  // Reactive scroll state that will be updated via scrollCallback
   const scrollState = reactive<ScrollState>({
     scroll: 0,
     limit: 0,
@@ -19,30 +18,51 @@ export default defineNuxtPlugin(() => {
     progress: 0,
   })
 
-  // Create Locomotive Scroll instance
-  const locomotiveScroll = new LocomotiveScroll({
-    // Lenis options passthrough (LS5 is built on Lenis)
-    lenisOptions: {
-      lerp: 0.1,
-      smoothWheel: true,
-      wheelMultiplier: 1,
-    },
-    // Scroll callback for reactive state updates and GSAP sync
-    scrollCallback: ({ scroll, limit, velocity, direction, progress }) => {
-      scrollState.scroll = scroll
-      scrollState.limit = limit
-      scrollState.velocity = velocity
-      scrollState.direction = direction
-      scrollState.progress = progress
-
-      // Sync ScrollTrigger with Locomotive Scroll
-      ScrollTrigger.update()
-    },
+  let instance: LocomotiveScroll | null = null
+
+  function init() {
+    if (instance) return
+    instance = new LocomotiveScroll({
+      lenisOptions: {
+        lerp: 0.1,
+        smoothWheel: true,
+        wheelMultiplier: 1,
+      },
+      scrollCallback: ({ scroll, limit, velocity, direction, progress }) => {
+        scrollState.scroll = scroll
+        scrollState.limit = limit
+        scrollState.velocity = velocity
+        scrollState.direction = direction
+        scrollState.progress = progress
+        ScrollTrigger.update()
+      },
+    })
+  }
+
+  function destroy() {
+    instance?.destroy()
+    instance = null
+  }
+
+  const router = useRouter()
+
+  const SMOOTH_SCROLL_ROUTES = ['/locomotive-scroll', '/layout-stacking', '/layout-blind-reveal']
+
+  addRouteMiddleware((to, from) => {
+    if (SMOOTH_SCROLL_ROUTES.includes(to.path)) {
+      nextTick(init)
+    } else if (from?.path && SMOOTH_SCROLL_ROUTES.includes(from.path)) {
+      destroy()
+    }
   })
 
+  if (SMOOTH_SCROLL_ROUTES.includes(router.currentRoute.value.path)) {
+    init()
+  }
+
   return {
     provide: {
-      locomotiveScroll,
+      locomotiveScroll: readonly(instance),
       scrollState,
     },
   }

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "kmcom-nuxt-layers",
   "private": false,
-  "version": "1.1.9",
+  "version": "1.3.0",
   "description": "Composable Nuxt 4 layers for building scalable Vue applications",
   "files": [
     "layers/*/nuxt.config.ts",