kmcom-nuxt-layers 1.1.8 → 1.2.0

package/docs/LAYOUT.md

@@ -0,0 +1,517 @@
+# Layout Layer
+
+Swiss Grid System for Nuxt 4 applications. Provides a responsive 6/12/18-column CSS subgrid, page structure components, a mode system, and fluid layout utilities.
+
+---
+
+## Contents
+
+- [How it works](#how-it-works)
+- [Playground setup](#playground-setup)
+- [Mode system](#mode-system)
+- [Components](#components)
+- [Composables](#composables)
+- [CSS utilities](#css-utilities)
+- [Z-index system](#z-index-system)
+- [Config reference](#config-reference)
+- [Known pitfalls](#known-pitfalls)
+
+---
+
+## How it works
+
+The grid is a single CSS `display: grid` on `<main>` (the `.mastmain` class). Everything else — sections, items — participates via CSS `subgrid`, meaning they inherit the parent's column and row lines rather than defining their own. No JS is involved in the grid itself.
+
+```
+<main class="mastmain">          ← defines the grid (6/12/18 cols, row height)
+  <section class="basesection">  ← subgrid: inherits cols + rows, spans 12 rows (= 100vh)
+    <div style="grid-column: ..."> ← positioned within the subgrid
+```
+
+`LayoutMain` renders the `<main class="mastmain">`. `LayoutSection` renders `<section class="basesection">`. `LayoutGridItem` handles grid positioning via inline style or presets.
+
+---
+
+## Playground setup
+
+The layout layer requires a dedicated Nuxt layout file and page-level layout declaration. Without these, content appears edge-to-edge and the grid CSS never applies.
+
+**1. Create `layouts/grid.vue`** in your app:
+
+```vue
+<template>
+  <LayoutMain>
+    <slot />
+    <LayoutGridDebug />
+  </LayoutMain>
+</template>
+```
+
+**2. Declare the layout in each page that uses the grid:**
+
+```vue
+<script setup lang="ts">
+definePageMeta({ layout: 'grid' })
+</script>
+```
+
+> `LayoutPage` is a fragment component — it intentionally provides no wrapper element. The `mastmain` grid lives on `LayoutMain` in the layout file, not in `LayoutPage` itself. Do not add a second `LayoutMain` inside `LayoutPage`.
+
+**Grid debug overlay** (`Cmd+G` to toggle) is rendered by `LayoutGridDebug` inside the layout file, not per-page.
+
+---
+
+## Mode system
+
+The grid has three modes controlled via `app.config.ts`:
+
+| Mode | Behaviour |
+|---|---|
+| `'swiss'` | Default. Full Swiss grid with `mastmain`/`basesection` CSS subgrid. |
+| `'fluid'` | Container-query-based auto-fit grid. `basesection` still gets `container-type`. |
+| `'disabled'` | `LayoutMain` renders a plain `<main>` without grid CSS. |
+
+Set in your `app.config.ts`:
+
+```ts
+export default defineAppConfig({
+  layoutLayer: {
+    ui: {
+      grid: {
+        mode: 'swiss',  // 'swiss' | 'fluid' | 'disabled'
+      },
+    },
+  },
+})
+```
+
+The old `enabled: boolean` flag is still supported (mapped to `'disabled'` / `'swiss'`) but `mode` takes precedence.
+
+Read in code:
+
+```ts
+const { mode, isEnabled } = useGridConfig()
+// mode.value === 'swiss' | 'fluid' | 'disabled'
+// isEnabled.value === mode !== 'disabled'
+```
+
+---
+
+## Components
+
+### `LayoutMain`
+
+Renders `<main class="mastmain">`. When `mode === 'disabled'` it renders a plain `<main>` with no grid classes.
+
+```vue
+<LayoutMain>           <!-- default: <main> -->
+<LayoutMain tag="div"> <!-- custom tag -->
+```
+
+**Props:**
+
+| Prop | Type | Default |
+|---|---|---|
+| `tag` | `string` | `'main'` |
+
+Place this in your layout file (`layouts/grid.vue`), not in individual pages.
+
+---
+
+### `LayoutContainer`
+
+Constrains content width and centres it. Use inside sections or anywhere you need a contained block.
+
+```vue
+<LayoutContainer>                    <!-- default: wide (90rem) -->
+<LayoutContainer size="content">     <!-- 65ch prose width -->
+<LayoutContainer size="wide">        <!-- 90rem -->
+<LayoutContainer size="fluid">       <!-- 100% of parent -->
+<LayoutContainer size="full">        <!-- 100vw, escapes grid padding -->
+```
+
+**Props:**
+
+| Prop | Type | Default |
+|---|---|---|
+| `size` | `'content' \| 'wide' \| 'fluid' \| 'full'` | `'wide'` |
+| `tag` | `string` | `'div'` |
+
+The `full` size uses negative `margin-inline` to escape the grid's `--grid-padding`, reaching the true viewport edge.
+
+---
+
+### `LayoutPage`
+
+Fragment component (no wrapper element). Handles `useHead()` SEO and optionally renders a `LayoutPageHeader` section.
+
+```vue
+<template>
+  <LayoutPage title="About" description="About us">
+    <LayoutSection>
+      <LayoutGridItem preset="centered">
+        <!-- content -->
+      </LayoutGridItem>
+    </LayoutSection>
+  </LayoutPage>
+</template>
+```
+
+**Props:**
+
+| Prop | Type | Default |
+|---|---|---|
+| `title` | `string` | — (required) |
+| `description` | `string` | `''` |
+| `showHeader` | `boolean` | `false` |
+
+---
+
+### `LayoutSection`
+
+Full-viewport subgrid section. Spans 12 rows (= 100vh). Inherits the parent `.mastmain` grid columns via `subgrid`.
+
+```vue
+<LayoutSection>
+<LayoutSection full-height>   <!-- always 100vh, even on mobile -->
+<LayoutSection tag="article">
+```
+
+**Props:**
+
+| Prop | Type | Default |
+|---|---|---|
+| `fullHeight` | `boolean` | `false` |
+| `fullWidth` | `boolean` | `false` |
+| `tag` | `string` | `'section'` |
+
+---
+
+### `LayoutGridItem`
+
+Positioned child within a subgrid section. Use `preset` for common layouts or set column/row values directly.
+
+```vue
+<LayoutGridItem preset="centered" />
+<LayoutGridItem col-start="3" col-span="12" row-start="2" row-span="8" />
+<!-- Responsive values -->
+<LayoutGridItem :col-span="{ default: 6, md: 10, lg: 12 }" />
+```
+
+**Props:**
+
+| Prop | Type | Notes |
+|---|---|---|
+| `preset` | `string` | Named preset from config |
+| `colStart` | `number \| ResponsiveValue` | Grid column start |
+| `colSpan` | `number \| ResponsiveValue` | Column span |
+| `rowStart` | `number \| ResponsiveValue` | Grid row start |
+| `rowSpan` | `number \| ResponsiveValue` | Row span |
+| `layer` | `keyof GridLayers` | Z-index layer: `back`, `mid`, `front`, `top` |
+| `align` | `string` | `align-self` value |
+| `justify` | `string` | `justify-self` value |
+| `bleed` | `boolean` | Negative margin to reach viewport edge |
+| `as` | `string` | Tag override |
+
+**Built-in presets:**
+
+| Preset | Columns | Rows |
+|---|---|---|
+| `hero` | full width | full height |
+| `centered` | centre 10 cols | rows 2–10 |
+| `fullWidth` | full width | auto |
+| `sidebar` | cols 1–4 | full height |
+| `content` | cols 5–14 | rows 2–10 |
+| `splitLeft` | left half | full |
+| `splitRight` | right half | full |
+| `quarterLeft` | first quarter | full |
+| `threeQuarterRight` | right 3/4 | full |
+| `halfTop` | full width | top half |
+| `halfBottom` | full width | bottom half |
+
+---
+
+### `LayoutSectionHero`
+
+Section with `background`, `default`, and `footer` slot layers.
+
+```vue
+<LayoutSectionHero>
+  <template #background><img ... /></template>
+  <h1>Title</h1>
+  <template #footer><p>Subtitle</p></template>
+</LayoutSectionHero>
+```
+
+---
+
+### `LayoutSectionSplit`
+
+Two-column 50/50 layout.
+
+```vue
+<LayoutSectionSplit>
+  <template #left>Left content</template>
+  <template #right>Right content</template>
+</LayoutSectionSplit>
+
+<LayoutSectionSplit reverse /> <!-- right renders first visually -->
+```
+
+---
+
+### `LayoutSectionGallery`
+
+Auto-placing collection grid.
+
+```vue
+<LayoutSectionGallery :items="items" :columns="3" :item-row-span="4">
+  <template #item="{ item, index }">
+    <img :src="item.src" />
+  </template>
+</LayoutSectionGallery>
+```
+
+**Props:** `items` (required), `columns` (2/3/4/6, default 3), `itemRowSpan` (default 4)
+
+---
+
+### `LayoutGridDebug`
+
+Column overlay toggled with `Cmd+G`. Place once in your grid layout file, not in pages.
+
+---
+
+## Composables
+
+### `useGridConfig()`
+
+```ts
+const { config, getPreset, isEnabled, mode, layers, useZIndex } = useGridConfig()
+```
+
+| Return | Type | Description |
+|---|---|---|
+| `config` | `Ref<GridConfig>` | Raw config from `app.config` |
+| `isEnabled` | `ComputedRef<boolean>` | `true` when `mode !== 'disabled'` |
+| `mode` | `ComputedRef<GridMode>` | `'swiss' \| 'fluid' \| 'disabled'` |
+| `layers` | `ComputedRef<GridLayers>` | All z-index values |
+| `getPreset(name)` | `GridPresetsItem \| undefined` | Look up a preset by name |
+| `useZIndex(layer)` | `number` | Get a z-index value by layer name |
+
+**`useZIndex` example:**
+
+```ts
+const { useZIndex } = useGridConfig()
+const zModal = useZIndex('modal')   // 400
+const zHeader = useZIndex('header') // 100
+```
+
+---
+
+## CSS utilities
+
+All grid CSS is in `layers/layout/app/assets/css/layout/`.
+
+> **Important:** All classes are plain CSS (not `@utility` directives). Do not convert them to `@utility` — they are loaded via Nuxt's `css: []` array which bypasses the Tailwind CSS 4 pipeline, so `@utility` would produce no output.
+
+### `grids.css` — Core grid classes
+
+**`.mastmain`** — Root grid container on `<main>`.
+
+```css
+/* Responsive column counts */
+/* Mobile:  6 columns  (< 768px) */
+/* Tablet:  12 columns (≥ 768px) */
+/* Desktop: 18 columns (≥ 1280px) */
+```
+
+CSS custom properties exposed:
+
+| Variable | Value | Purpose |
+|---|---|---|
+| `--grid-cols` | 6 / 12 / 18 | Active column count |
+| `--grid-gap` | `clamp(0.75rem, 1.5vw, 1.5rem)` | Gap between columns and rows |
+| `--grid-padding` | `clamp(1rem, 2.5vw, 2rem)` | Outer left/right gutters |
+| `--section-height` | `100vh` | Height of one section |
+| `--grid-row-height` | computed | Height of one grid row |
+
+**`.basesection`** — Subgrid section (12 rows = 100vh).
+
+**Vertical rhythm utilities** (`.leading-rhythm-*`, `.space-rhythm-*`, `.prose-rhythm`)
+
+### `modes/fluid.css` — Fluid grid classes
+
+Container-query-based auto-fit grids for components that should respond to their container width rather than the viewport.
+
+```vue
+<div class="fluid-grid">          <!-- auto-fit, min col 16rem -->
+<div class="fluid-grid-2">        <!-- 2-column at container ≥ 30rem -->
+<div class="fluid-grid-3">        <!-- 3-column at container ≥ 44rem -->
+<div class="fluid-grid-4">        <!-- 4-column at container ≥ 52rem -->
+```
+
+Tune minimum column width per-instance:
+
+```vue
+<div class="fluid-grid" style="--fluid-col-min: 20rem">
+```
+
+**Container size classes** (used by `LayoutContainer`):
+
+| Class | Effect |
+|---|---|
+| `.layout-container-content` | `max-width: 65ch`, centred |
+| `.layout-container-wide` | `max-width: 90rem`, centred |
+| `.layout-container-fluid` | `max-width: 100%` |
+| `.layout-container-full` | `width: 100vw`, escapes grid padding |
+
+---
+
+## Z-index system
+
+The grid manages z-index through named layers. Use `useZIndex()` or the `layer` prop on `LayoutGridItem` — never raw numbers.
+
+| Layer | Value | Use |
+|---|---|---|
+| `back` | 0 | Background elements |
+| `mid` | 10 | Content |
+| `front` | 20 | Floating content |
+| `top` | 30 | Pinned / sticky |
+| `header` | 100 | Site header / nav |
+| `dropdown` | 200 | Dropdown menus, popups |
+| `overlay` | 300 | Drawers, sidebars |
+| `modal` | 400 | Modal dialogs |
+| `toast` | 500 | Toasts, notifications |
+
+```ts
+// In a component
+const { useZIndex } = useGridConfig()
+</script>
+<template>
+  <div :style="{ zIndex: useZIndex('modal') }">
+```
+
+```vue
+<!-- On a grid item -->
+<LayoutGridItem layer="front">
+```
+
+Override values in `app.config.ts`:
+
+```ts
+layoutLayer: {
+  ui: {
+    grid: {
+      layers: {
+        toast: 9999,  // override individual values
+      },
+    },
+  },
+},
+```
+
+---
+
+## Config reference
+
+Full type from `layers/layout/app/types/layouts.ts`:
+
+```ts
+interface GridConfig {
+  mode?: 'swiss' | 'fluid' | 'disabled'
+  /** @deprecated use mode: 'disabled' */
+  enabled?: boolean
+  layers?: Partial<GridLayers>
+  presets?: Record<string, GridPresetsItem>
+}
+
+interface GridPresetsItem {
+  colStart?: number | ResponsiveValue
+  colSpan?: number | ResponsiveValue
+  rowStart?: number | ResponsiveValue
+  rowSpan?: number | ResponsiveValue
+  container?: 'content' | 'wide' | 'fluid' | 'full'
+  gap?: string
+  density?: 'compact' | 'normal' | 'spacious'
+}
+```
+
+App config namespace: `layoutLayer.ui.grid`.
+
+**Custom preset example:**
+
+```ts
+export default defineAppConfig({
+  layoutLayer: {
+    ui: {
+      grid: {
+        presets: {
+          spotlight: {
+            colStart: 4,
+            colSpan: 12,
+            rowStart: 3,
+            rowSpan: 6,
+          },
+        },
+      },
+    },
+  },
+})
+```
+
+---
+
+## Known pitfalls
+
+### `@utility` doesn't work in layer CSS files
+
+`@utility` is a Tailwind CSS 4 directive that only works inside files processed by TW4's own pipeline (files containing `@import "tailwindcss"`). CSS loaded via Nuxt's `css: []` array bypasses this pipeline — `@utility` blocks are silently ignored and the class is never generated.
+
+**Rule: always use plain CSS class selectors in layer CSS files.**
+
+```css
+/* Wrong — class will not exist in output */
+@utility mastmain {
+  display: grid;
+}
+
+/* Correct */
+.mastmain {
+  display: grid;
+}
+```
+
+### `overflow-x: hidden` creates unintended scroll containers
+
+The CSS overflow interaction rule: setting `overflow-x: hidden` on any element forces `overflow-y` from `visible` to `auto`, turning that element into a scroll container. When the element is `html` or `body`, `window.scrollY` stays 0 even when content overflows the viewport.
+
+**Use `overflow-x: clip` instead.** `clip` cuts off overflow without creating a scroll container and is not subject to the forced `overflow-y` conversion. This is why `.mastmain`, `html`, and `body` all use `overflow-x: clip` in this layer.
+
+```css
+/* Wrong */
+.mastmain { overflow-x: hidden; } /* becomes a scroll container */
+
+/* Correct */
+.mastmain { overflow-x: clip; }   /* clips without scroll container */
+```
+
+### Locomotive Scroll intercepts wheel events globally
+
+Locomotive Scroll v5 (Lenis-based) with `smoothWheel: true` calls `preventDefault()` on every `wheel` event. If initialised globally in a Nuxt plugin, it intercepts scrolling on every page — even pages where the window has no scroll height, silently swallowing events.
+
+**Scope Locomotive Scroll to the specific route** using `addRouteMiddleware`:
+
+```ts
+// plugins/locomotive-scroll.client.ts
+addRouteMiddleware((to, from) => {
+  if (to.path === '/the-route') nextTick(init)
+  else if (from?.path === '/the-route') destroy()
+})
+```
+
+### `LayoutPage` is a fragment — it provides no grid wrapper
+
+`LayoutPage` renders no element of its own. The `mastmain` grid lives on `LayoutMain` inside a layout file. If you use `<LayoutPage>` on a page that uses the `default` layout (which doesn't include `LayoutMain`), the grid CSS never applies.
+
+Always pair `LayoutPage` usage with `definePageMeta({ layout: 'grid' })` and ensure `layouts/grid.vue` exists with `<LayoutMain>`.

package/layers/core/app/composables/useScrollGuard.ts

@@ -96,8 +96,8 @@ function guard() {
   const html = document.documentElement
   const body = document.body
 
-  html.style.overflowX = 'hidden'
-  body.style.overflowX = 'hidden'
+  html.style.overflowX = 'clip'
+  body.style.overflowX = 'clip'
   body.style.maxWidth = '100vw'
 
   if (!opts.strict) return

package/layers/layout/app/assets/css/layout/grids.css

@@ -5,13 +5,13 @@
  * Uses CSS subgrid for precise alignment across layout hierarchy.
  *
  * Hierarchy:
- *   MastMain (mastmain utility)
- *   └── BaseSection (basesection utility, uses subgrid)
+ *   MastMain (.mastmain)
+ *   └── BaseSection (.basesection, uses subgrid)
  *       └── BaseGridItem (positioned via inline grid-column/grid-row)
  */
 
 /**
- * mastmain - Root grid container with responsive density
+ * .mastmain - Root grid container with responsive density
  *
  * Creates responsive grid:
  * - Mobile: 6 columns (default)
@@ -20,7 +20,7 @@
  *
  * Each row height is calculated to fit 12 rows per viewport.
  */
-@utility mastmain {
+.mastmain {
   --grid-cols: 6;
   --grid-rows-per-section: 12;
   --grid-gap: clamp(0.75rem, 1.5vw, 1.5rem);
@@ -36,7 +36,7 @@
   grid-auto-rows: var(--grid-row-height);
   gap: var(--grid-gap);
   padding-inline: var(--grid-padding); /* Outer gutters on left/right */
-  overflow-x: hidden;
+  overflow-x: clip; /* clip without creating a scroll container (overflow-x:hidden would force overflow-y:auto) */
   width: 100%;
   max-width: 100%;
   box-sizing: border-box;
@@ -58,12 +58,12 @@
 }
 
 /**
- * basesection - Full-viewport section using subgrid
+ * .basesection - Full-viewport section using subgrid
  *
  * Inherits parent's grid lines via subgrid.
  * Spans 12 rows (1 viewport height).
  */
-@utility basesection {
+.basesection {
   container-type: inline-size;
   container-name: section;
   grid-column: 1 / -1;
@@ -100,59 +100,59 @@
  */
 
 /* Line height utilities */
-@utility leading-rhythm-4 {
+.leading-rhythm-4 {
   --rhythm: 0.25rem;
   line-height: calc(var(--rhythm) * 4); /* 1rem */
 }
 
-@utility leading-rhythm-5 {
+.leading-rhythm-5 {
   --rhythm: 0.25rem;
   line-height: calc(var(--rhythm) * 5); /* 1.25rem */
 }
 
-@utility leading-rhythm-6 {
+.leading-rhythm-6 {
   --rhythm: 0.25rem;
   line-height: calc(var(--rhythm) * 6); /* 1.5rem */
 }
 
-@utility leading-rhythm-7 {
+.leading-rhythm-7 {
   --rhythm: 0.25rem;
   line-height: calc(var(--rhythm) * 7); /* 1.75rem */
 }
 
-@utility leading-rhythm-8 {
+.leading-rhythm-8 {
   --rhythm: 0.25rem;
   line-height: calc(var(--rhythm) * 8); /* 2rem */
 }
 
 /* Vertical spacing utilities */
-@utility space-rhythm-1 {
+.space-rhythm-1 {
   --rhythm: 0.25rem;
   margin-block: var(--rhythm); /* 0.25rem */
 }
 
-@utility space-rhythm-2 {
+.space-rhythm-2 {
   --rhythm: 0.25rem;
   margin-block: calc(var(--rhythm) * 2); /* 0.5rem */
 }
 
-@utility space-rhythm-4 {
+.space-rhythm-4 {
   --rhythm: 0.25rem;
   margin-block: calc(var(--rhythm) * 4); /* 1rem */
 }
 
-@utility space-rhythm-6 {
+.space-rhythm-6 {
   --rhythm: 0.25rem;
   margin-block: calc(var(--rhythm) * 6); /* 1.5rem */
 }
 
-@utility space-rhythm-8 {
+.space-rhythm-8 {
   --rhythm: 0.25rem;
   margin-block: calc(var(--rhythm) * 8); /* 2rem */
 }
 
 /* Prose container - auto-applies rhythm to children */
-@utility prose-rhythm {
+.prose-rhythm {
   --rhythm: 0.25rem;
 
   & > * + * {

package/layers/layout/app/assets/css/layout/modes/fluid.css

@@ -0,0 +1,100 @@
+/**
+ * Fluid Mode — Container-Query Based Grid Utilities
+ *
+ * These utilities complement .mastmain/.basesection and are safe to use
+ * alongside them — they only take effect when their class is applied.
+ *
+ * Design goals:
+ * - Auto-fit columns that respond to their *container* width, not the viewport
+ * - No fixed breakpoints — layout adapts continuously
+ * - Consistent gap matching the base grid gap custom property
+ */
+
+/**
+ * .fluid-grid — auto-fit grid that fills its container.
+ *
+ * Columns shrink no smaller than --fluid-col-min (default 16rem / 256px).
+ * Use `--fluid-col-min` to tune the minimum column width per-instance.
+ *
+ * @example
+ * <div class="fluid-grid" style="--fluid-col-min: 20rem">…</div>
+ */
+.fluid-grid {
+  --fluid-col-min: 16rem;
+  display: grid;
+  grid-template-columns: repeat(auto-fit, minmax(var(--fluid-col-min), 1fr));
+  gap: var(--grid-gap, clamp(0.75rem, 1.5vw, 1.5rem));
+}
+
+/**
+ * .fluid-grid-2 through .fluid-grid-4 — named column-count variants.
+ *
+ * These use container queries so the number of columns degrades gracefully
+ * when the container is too narrow.
+ */
+.fluid-grid-2 {
+  --fluid-col-min: 14rem;
+  display: grid;
+  grid-template-columns: repeat(auto-fit, minmax(var(--fluid-col-min), 1fr));
+  gap: var(--grid-gap, clamp(0.75rem, 1.5vw, 1.5rem));
+
+  @container (width >= 30rem) {
+    grid-template-columns: repeat(2, 1fr);
+  }
+}
+
+.fluid-grid-3 {
+  --fluid-col-min: 14rem;
+  display: grid;
+  grid-template-columns: repeat(auto-fit, minmax(var(--fluid-col-min), 1fr));
+  gap: var(--grid-gap, clamp(0.75rem, 1.5vw, 1.5rem));
+
+  @container (width >= 44rem) {
+    grid-template-columns: repeat(3, 1fr);
+  }
+}
+
+.fluid-grid-4 {
+  --fluid-col-min: 12rem;
+  display: grid;
+  grid-template-columns: repeat(auto-fit, minmax(var(--fluid-col-min), 1fr));
+  gap: var(--grid-gap, clamp(0.75rem, 1.5vw, 1.5rem));
+
+  @container (width >= 52rem) {
+    grid-template-columns: repeat(4, 1fr);
+  }
+}
+
+/**
+ * LayoutContainer size utilities
+ *
+ * Used by the <LayoutContainer> component. Each class constrains the element
+ * width and centres it within its parent.
+ */
+.layout-container-content {
+  max-width: 65ch;
+  width: 100%;
+  margin-inline: auto;
+  box-sizing: border-box;
+}
+
+.layout-container-wide {
+  max-width: 90rem;
+  width: 100%;
+  margin-inline: auto;
+  box-sizing: border-box;
+}
+
+.layout-container-fluid {
+  max-width: 100%;
+  width: 100%;
+  box-sizing: border-box;
+}
+
+.layout-container-full {
+  /* Escape parent padding to reach the viewport edge */
+  width: 100vw;
+  max-width: 100vw;
+  margin-inline: calc(var(--grid-padding, clamp(1rem, 2.5vw, 2rem)) * -1);
+  box-sizing: border-box;
+}

package/layers/layout/app/assets/css/main.css

@@ -1 +1,2 @@
 @import '#layers/layout/app/assets/css/layout/grids.css';
+@import '#layers/layout/app/assets/css/layout/modes/fluid.css';

package/layers/layout/app/components/Layout/Container.vue

@@ -0,0 +1,49 @@
+<script setup lang="ts">
+/**
+ * LayoutContainer — constrained content width wrapper.
+ *
+ * Provides four standard container widths that sit within the grid:
+ *
+ * | size    | max-width | use case                        |
+ * |---------|-----------|----------------------------------|
+ * | content | 65ch      | Long-form prose, articles        |
+ * | wide    | 90rem     | Cards, media-rich sections       |
+ * | fluid   | 100%      | Full bleed within grid padding   |
+ * | full    | 100vw     | True full-bleed (escapes padding)|
+ *
+ * The container is centred with `margin-inline: auto` for `content` and `wide`.
+ *
+ * @prop {GridContainerSize} size — Container width variant (default: 'wide')
+ * @prop {string}            tag  — HTML element to render (default: 'div')
+ *
+ * @example
+ * <LayoutContainer size="content">
+ *   <p>Readable prose constrained to ~65 characters wide.</p>
+ * </LayoutContainer>
+ */
+
+import type { GridContainerSize } from '#layers/layout/app/types/layouts'
+
+interface Props {
+  size?: GridContainerSize
+  tag?: string
+}
+
+const { size = 'wide', tag = 'div' } = defineProps<Props>()
+
+const sizeClass: Record<GridContainerSize, string> = {
+  content: 'layout-container-content',
+  wide: 'layout-container-wide',
+  fluid: 'layout-container-fluid',
+  full: 'layout-container-full',
+}
+</script>
+
+<template>
+  <component
+    :is="tag"
+    :class="sizeClass[size]"
+  >
+    <slot />
+  </component>
+</template>

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

@@ -34,22 +34,35 @@ const handleKeydown = (event: KeyboardEvent) => {
   }
 }
 
+// Track column count in JS so v-for renders the correct number of divs.
+// Mirrors the same breakpoints as mastmain (48rem = 768px, 80rem = 1280px).
+const cols = ref(6)
+
+const updateCols = () => {
+  if (window.matchMedia('(min-width: 80rem)').matches) cols.value = 18
+  else if (window.matchMedia('(min-width: 48rem)').matches) cols.value = 12
+  else cols.value = 6
+}
+
 onMounted(() => {
+  updateCols()
+  window.addEventListener('resize', updateCols)
   window.addEventListener('keydown', handleKeydown)
 })
 
 onUnmounted(() => {
+  window.removeEventListener('resize', updateCols)
   window.removeEventListener('keydown', handleKeydown)
 })
 
-// Use CSS variables to match the responsive grid
+// Do NOT set --grid-cols here as an inline style — that would override the
+// CSS media queries in <style scoped> below. Let CSS own the variable.
 const style = computed(() => ({
   display: 'grid',
-  gridTemplateColumns: 'repeat(var(--grid-cols, 6), 1fr)',
+  gridTemplateColumns: `repeat(${cols.value}, 1fr)`,
   gap,
-  paddingInline: 'var(--grid-padding, clamp(1rem, 2.5vw, 2rem))',
+  paddingInline: 'clamp(1rem, 2.5vw, 2rem)',
   pointerEvents: 'none' as const,
-  '--grid-cols': '6',
 }))
 
 defineExpose({ toggle })
@@ -58,22 +71,8 @@ defineExpose({ toggle })
 <template>
   <Teleport to="body">
     <div v-if="visible" :style class="grid-debug z-9999 fixed inset-0" aria-hidden="true">
-      <div v-for="i in 18" :key="i" :style="{ backgroundColor: color }" class="h-full" />
+      <div v-for="i in cols" :key="i" :style="{ backgroundColor: color }" class="h-full" />
     </div>
   </Teleport>
 </template>
 
-<style scoped>
-/* Match responsive breakpoints from mastmain */
-@media (width >= 48rem) {
-  .grid-debug {
-    --grid-cols: 12;
-  }
-}
-
-@media (width >= 80rem) {
-  .grid-debug {
-    --grid-cols: 18;
-  }
-}
-</style>

package/layers/layout/app/components/Layout/Main.vue

@@ -0,0 +1,36 @@
+<script setup lang="ts">
+/**
+ * LayoutMain — grid root container applying the `mastmain` utility.
+ *
+ * Use this component when you need an explicit wrapper element that owns the
+ * Swiss Grid stacking context. The default layout can use it in place of a
+ * raw `<main class="mastmain">`.
+ *
+ * When `mode` is `'disabled'`, falls back to a plain semantic `<main>` so the
+ * page renders correctly without grid dependencies.
+ *
+ * @prop {string} tag — HTML element to render (default: 'main')
+ *
+ * @example
+ * <LayoutMain>
+ *   <LayoutSection>…</LayoutSection>
+ * </LayoutMain>
+ */
+
+interface Props {
+  tag?: string
+}
+
+const { tag = 'main' } = defineProps<Props>()
+
+const { mode } = useGridConfig()
+</script>
+
+<template>
+  <component
+    :is="tag"
+    :class="mode !== 'disabled' ? 'mastmain' : undefined"
+  >
+    <slot />
+  </component>
+</template>

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

@@ -0,0 +1,69 @@
+<script setup lang="ts">
+/**
+ * LayoutPage — canonical page wrapper for the Swiss Grid System.
+ *
+ * This is a fragment component (no wrapper element). The grid root is already
+ * provided by MastMain at the layout level via <div class="mastmain">.
+ * Adding another mastmain wrapper here would nest grids and misalign everything.
+ *
+ * Responsibilities:
+ *   - SEO via useHead()
+ *   - provides 'pageTitle' to child components
+ *   - optional visible header (LayoutSection + LayoutPageHeader)
+ *
+ * LayoutGridDebug is owned by the default layout — do NOT add it here.
+ *
+ * @prop {string}  title       — Page title: sets <title> and optional visible heading
+ * @prop {string}  description — Optional meta description for SEO
+ * @prop {boolean} showHeader  — Render a LayoutPageHeader block (default: false)
+ *
+ * @example
+ * <LayoutPage title="Home">
+ *   <LayoutSectionHero>
+ *     <h1>Welcome</h1>
+ *   </LayoutSectionHero>
+ * </LayoutPage>
+ *
+ * @example
+ * <LayoutPage title="About" description="Learn more." :show-header="true">
+ *   <LayoutSection>
+ *     <LayoutGridItem preset="centered">
+ *       <p>Content here.</p>
+ *     </LayoutGridItem>
+ *   </LayoutSection>
+ * </LayoutPage>
+ */
+
+interface Props {
+  title: string
+  description?: string
+  showHeader?: boolean
+}
+
+const { title, description, showHeader = false } = defineProps<Props>()
+
+useHead({
+  title,
+  meta: description
+    ? [
+        { name: 'description', content: description },
+        { property: 'og:title', content: title },
+        { property: 'og:description', content: description },
+      ]
+    : undefined,
+})
+
+provide('pageTitle', title)
+</script>
+
+<template>
+  <!-- Optional visible page header — rendered as a grid section -->
+  <LayoutSection v-if="showHeader">
+    <LayoutGridItem preset="centered">
+      <LayoutPageHeader :title :description />
+    </LayoutGridItem>
+  </LayoutSection>
+
+  <!-- Page content — direct children of mastmain (via MastMain in the layout) -->
+  <slot />
+</template>

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,17 +7,41 @@ 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>
   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
 }
 
 export interface GridPresets {
@@ -29,6 +53,17 @@ export interface GridPresets {
 }
 
 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,10 +68,17 @@ 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

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()
+
+  // Only active on the locomotive-scroll route
+  addRouteMiddleware((to, from) => {
+    if (to.path === '/locomotive-scroll') {
+      nextTick(init)
+    } else if (from?.path === '/locomotive-scroll') {
+      destroy()
+    }
   })
 
+  // Activate immediately if already on that route (e.g. hard refresh)
+  if (router.currentRoute.value.path === '/locomotive-scroll') {
+    init()
+  }
+
   return {
     provide: {
-      locomotiveScroll,
+      locomotiveScroll: readonly(instance),
       scrollState,
     },
   }

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "kmcom-nuxt-layers",
   "private": false,
-  "version": "1.1.8",
+  "version": "1.2.0",
   "description": "Composable Nuxt 4 layers for building scalable Vue applications",
   "files": [
     "layers/*/nuxt.config.ts",
@@ -35,7 +35,7 @@
     "better-sqlite3": "^12.0.0",
     "gsap": "^3.12.0",
     "locomotive-scroll": "^5.0.0",
-    "nuxt": "^4.0.0",
+    "nuxt": "^4.3.1",
     "nuxt-studio": "^1.0.0",
     "pinia": "^3.0.0",
     "tailwindcss": "^4.2.1",