kmcom-nuxt-layers 2.7.5 → 4.0.0

package/layers/structure/grid/app/composables/useGridTracks.ts

@@ -0,0 +1,74 @@
+import type { GridPreset, TrackConfig } from '../types/tracks'
+
+type GridLayerAppConfig = {
+  gridLayer?: {
+    presets?: Record<string, GridPreset>
+  }
+}
+
+function normalizeNames(names: string | string[] | undefined): string[] {
+  if (!names) return []
+  return Array.isArray(names) ? names : [names]
+}
+
+function toBracket(names: string[]): string {
+  return names.length > 0 ? `[${names.join(' ')}]` : ''
+}
+
+/**
+ * Builds a `grid-template-columns` value from a TrackConfig. Each segment becomes a
+ * `minmax(floor, Nfr)` track; adjacent lineEnd/lineStart names merge into one bracket,
+ * per standard named-grid-line syntax. Unlike `repeat(auto-fill, ...)`, an explicit track
+ * list cannot drop columns to fit a narrow viewport — it only overflows. Wrap the grid in
+ * a scrollable container (e.g. `overflow-x: auto` on a wrapper element, not on
+ * `.grid-tracks` itself) if segments may overflow the target viewport, or pass a smaller
+ * `minTrackWidth`/fewer segments to avoid overflow entirely.
+ */
+export function toColumnsCss(config: TrackConfig): string {
+  const minWidth = config.minTrackWidth ?? 'var(--measure-min)'
+  const segments = config.columns
+
+  const parts: string[] = []
+
+  segments.forEach((segment, index) => {
+    const previous = index > 0 ? segments[index - 1] : undefined
+    const leadNames = [...normalizeNames(previous?.lineEnd), ...normalizeNames(segment.lineStart)]
+    const leadBracket = toBracket(leadNames)
+    if (leadBracket) parts.push(leadBracket)
+    parts.push(`minmax(${minWidth}, ${segment.size}fr)`)
+  })
+
+  const lastSegment = segments[segments.length - 1]
+  const trailBracket = toBracket(normalizeNames(lastSegment?.lineEnd))
+  if (trailBracket) parts.push(trailBracket)
+
+  return parts.join(' ')
+}
+
+/**
+ * Resolves a preset name against a registry, or passes a TrackConfig object through
+ * unchanged. Exported standalone so it's testable without Nuxt's useAppConfig context.
+ */
+export function resolve(
+  input: string | TrackConfig,
+  presets?: Record<string, GridPreset>
+): TrackConfig {
+  if (typeof input === 'string') {
+    const found = presets?.[input]
+    if (!found) {
+      throw new Error(`Unknown grid preset: "${input}"`)
+    }
+    return found
+  }
+  return input
+}
+
+export function useGridTracks() {
+  const appConfig = useAppConfig() as GridLayerAppConfig
+  const presets = computed(() => appConfig.gridLayer?.presets)
+
+  return {
+    resolve: (input: string | TrackConfig) => resolve(input, presets.value),
+    toColumnsCss,
+  }
+}

package/layers/structure/grid/app/types/tracks.test.ts

@@ -0,0 +1,32 @@
+import { describe, expect, it } from 'vitest'
+
+import type { GridPreset, TrackConfig, TrackSegment } from './tracks'
+
+describe('track types', () => {
+  it('accepts a minimal equal-width segment', () => {
+    const segment: TrackSegment = { size: 1 }
+    expect(segment.size).toBe(1)
+  })
+
+  it('accepts a segment with named lines', () => {
+    const segment: TrackSegment = {
+      size: 2,
+      lineStart: 'feature-start',
+      lineEnd: ['feature-end', 'aside-start'],
+    }
+    expect(segment.lineEnd).toEqual(['feature-end', 'aside-start'])
+  })
+
+  it('accepts a TrackConfig with optional minTrackWidth', () => {
+    const config: TrackConfig = {
+      columns: [{ size: 1 }, { size: 2 }],
+      minTrackWidth: '20rem',
+    }
+    expect(config.columns).toHaveLength(2)
+  })
+
+  it('a GridPreset is a named TrackConfig', () => {
+    const preset: GridPreset = { name: 'swiss', columns: [{ size: 1 }] }
+    expect(preset.name).toBe('swiss')
+  })
+})

package/layers/structure/grid/app/types/tracks.ts

@@ -0,0 +1,18 @@
+export type TrackSegment = {
+  /** Relative size, same unit as CSS `fr`. 1 = one equal column. */
+  size: number
+  /** Optional named line(s) at the start of this segment, e.g. 'feature-start'. */
+  lineStart?: string | string[]
+  /** Optional named line(s) at the end of this segment. */
+  lineEnd?: string | string[]
+}
+
+export type TrackConfig = {
+  columns: TrackSegment[]
+  /** Track floor — reuses --measure-min unless overridden. */
+  minTrackWidth?: string
+}
+
+export type GridPreset = TrackConfig & {
+  name: string
+}

package/layers/structure/grid/app/utils/placement.test.ts

@@ -0,0 +1,19 @@
+import { describe, expect, it } from 'vitest'
+
+import { placementFromIndex, placementFromLines } from './placement'
+
+describe('placementFromLines', () => {
+  it('joins two named lines with a slash', () => {
+    expect(placementFromLines('feature-start', 'aside-end')).toBe('feature-start / aside-end')
+  })
+})
+
+describe('placementFromIndex', () => {
+  it('builds a numeric span from colStart and colSpan', () => {
+    expect(placementFromIndex(2, 3)).toBe('2 / span 3')
+  })
+
+  it('spans to the last line when colSpan is "full"', () => {
+    expect(placementFromIndex(4, 'full')).toBe('4 / -1')
+  })
+})

package/layers/structure/grid/app/utils/placement.ts

@@ -0,0 +1,15 @@
+/** Grid-column value addressing a named-line range. Primary placement method — named
+ * lines survive CSS subgrid boundaries, unlike grid-template-areas. */
+export function placementFromLines(startLine: string, endLine: string): string {
+  return `${startLine} / ${endLine}`
+}
+
+/** Numeric fallback for auto-flowing content with no named slot to target. `'full'`
+ * spans to the grid's last line (-1), matching the shape of layout's current
+ * GridItem colSpan prop for an additive future migration. */
+export function placementFromIndex(colStart: number, colSpan: number | 'full'): string {
+  if (colSpan === 'full') {
+    return `${colStart} / -1`
+  }
+  return `${colStart} / span ${colSpan}`
+}

package/layers/structure/grid/nuxt.config.ts

@@ -0,0 +1,22 @@
+// https://nuxt.com/docs/api/configuration/nuxt-config
+export default defineNuxtConfig({
+  $meta: {
+    name: 'grid',
+  },
+
+  extends: ['../../core'],
+
+  alias: {
+    '#layers/grid': import.meta.dirname,
+    '#layers/grid/types': `${import.meta.dirname}/app/types`,
+  },
+
+  css: ['#layers/grid/app/assets/css/grid.css'],
+
+  compatibilityDate: '2026-01-20',
+
+  typescript: {
+    typeCheck: false,
+    strict: true,
+  },
+})

package/layers/{theme → structure/grid}/package.json

@@ -1,10 +1,10 @@
 {
-  "name": "kmcom-layer-theme",
-  "version": "0.0.1",
+  "name": "kmcom-layer-grid",
   "type": "module",
+  "version": "0.0.1",
   "main": "./nuxt.config.ts",
   "scripts": {
-    "typecheck": "vue-tsc --noEmit -p ../../tsconfig.typecheck.json",
+    "typecheck": "vue-tsc --noEmit -p ../../../tsconfig.typecheck.json",
     "dev": "nuxi dev .playground",
     "dev:prepare": "nuxt prepare .playground",
     "build": "nuxt build .playground",

package/layers/structure/layout/app/app.config.ts

@@ -0,0 +1,116 @@
+import type { GridConfig } from './types/layouts'
+
+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 grid-root 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: {
+      slots: {
+        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: {
+      slots: {
+        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)
+         * - 'disabled' — Falls back to standard Nuxt UI 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,
+        rhythm: '0.25rem',
+
+        // 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: {
+          // Full-viewport hero: full width, all 12 rows
+          hero: { colSpan: 'full', rowSpan: 12 },
+
+          // Full-width content area within the grid's own padding.
+          // grid-root already applies padding-inline (clamp-based gutters),
+          // so col-start:1 / col-end:-1 is already visually centred.
+          centered: {
+            colSpan: 'full',
+            rowSpan: 12,
+          },
+        },
+      },
+    },
+  },
+})
+
+declare module '@nuxt/schema' {
+  interface AppConfigInput {
+    layoutLayer?: {
+      name?: string
+      ui?: {
+        grid?: GridConfig
+      }
+    }
+  }
+}

package/layers/{layout → structure/layout}/app/assets/css/layout/grids.css

@@ -5,22 +5,28 @@
  * Uses CSS subgrid for precise alignment across layout hierarchy.
  *
  * Hierarchy:
- *   MastMain (.mastmain)
+ *   LayoutMain (.grid-root)
  *   └── BaseSection (.basesection, uses subgrid)
  *       └── BaseGridItem (positioned via inline grid-column/grid-row)
  */
 
 /**
- * .mastmain - Root grid container with responsive density
+ * .grid-root - Root grid container with responsive density
  *
  * Creates responsive grid:
  * - Mobile: 6 columns (default)
- * - Tablet: 12 columns (≥ 48rem / 768px)
- * - Desktop: 18 columns (≥ 80rem / 1280px)
+ * - Tablet: 12 columns (≥ 48rem / 768px — matches core's --breakpoint-md)
+ * - Desktop: 18 columns (≥ 80rem / 1280px — matches core's --breakpoint-xl)
  *
  * Each row height is calculated to fit 12 rows per viewport.
+ *
+ * The 48rem/80rem literals below can't reference core's --breakpoint-* vars
+ * directly — CSS custom properties aren't valid inside @media conditions.
+ * layers/core/app/assets/css/tokens/breakpoints.css is still the canonical
+ * source; keep these in sync with it by convention (see
+ * nuxt-declarative-layout-system-spec.md §14/Phase 3).
  */
-.mastmain {
+.grid-root {
   --grid-cols: 6;
   --grid-rows-per-section: 12;
   --grid-gap: clamp(0.75rem, 1.5vw, 1.5rem);
@@ -82,7 +88,6 @@
     min-width: 0;
     max-width: 100%;
     overflow-wrap: break-word;
-    overflow-wrap: break-word;
   }
 
   /* On mobile, allow sections to grow beyond 12 rows if needed */

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

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

package/layers/structure/layout/app/components/HStack.vue

@@ -0,0 +1,41 @@
+<script setup lang="ts">
+  /**
+   * HStack — horizontal, one-dimensional layout (Flexbox row).
+   * See nuxt-declarative-layout-system-spec.md §6.
+   */
+
+  import type { Align, Justify } from '#layers/core/app/composables/useLayoutAttrs'
+  import type { ResponsiveValue } from '#layers/core/types/responsive'
+  import type { Spacing } from '#layers/core/types/tokens'
+
+  const {
+    gap = undefined,
+    align = undefined,
+    justify = undefined,
+    wrap = false,
+  } = defineProps<{
+    gap?: ResponsiveValue<Spacing> | Spacing
+    align?: ResponsiveValue<Align> | Align
+    justify?: ResponsiveValue<Justify> | Justify
+    wrap?: boolean
+  }>()
+
+  const { style } = useLayoutAttrs(() => ({ gap, align, justify }))
+</script>
+
+<template>
+  <div class="h-stack" :class="{ 'h-stack-wrap': wrap }" :style>
+    <slot />
+  </div>
+</template>
+
+<style scoped>
+  .h-stack {
+    display: flex;
+    flex-direction: row;
+  }
+
+  .h-stack-wrap {
+    flex-wrap: wrap;
+  }
+</style>

package/layers/{layout → structure/layout}/app/components/Layout/Grid/Debug.vue

@@ -13,6 +13,8 @@
    * <GridDebug color="rgba(0, 100, 255, 0.15)" />
    */
 
+  import { BREAKPOINT_PX } from '#layers/core/types/tokens'
+
   interface Props {
     gap?: string
     color?: string
@@ -35,12 +37,12 @@
   }
 
   // Track column count in JS so v-for renders the correct number of divs.
-  // Mirrors the same breakpoints as mastmain (48rem = 768px, 80rem = 1280px).
+  // Mirrors the same breakpoints as .grid-root (BREAKPOINT_PX.md = 768px, .xl = 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
+    if (window.matchMedia(`(min-width: ${BREAKPOINT_PX.xl}px)`).matches) cols.value = 18
+    else if (window.matchMedia(`(min-width: ${BREAKPOINT_PX.md}px)`).matches) cols.value = 12
     else cols.value = 6
   }
 

package/layers/{layout → structure/layout}/app/components/Layout/Grid/Item.vue

@@ -15,10 +15,8 @@
    * @prop {string} container - Content width constraint: content (65ch), wide (90rem), fluid, full
    * @prop {string} gap - Override --grid-gap for nested content (e.g. '1rem', '2rem')
    * @prop {string} density - Vertical rhythm: compact (2px), normal (4px), relaxed (8px)
-   * @prop {number} z - Explicit z-index value
    * @prop {LayerName} layer - Semantic layer: back, mid, front, top
    * @prop {BleedDirection} bleed - Edge bleed: left, right, both
-   * @prop {AspectRatio} aspect - Aspect ratio: 1/1, 4/3, 3/4, 16/9, 9/16, 2/1, 1/2
    *
    * @example
    * <BaseGridItem
@@ -41,7 +39,6 @@
   type Alignment = 'start' | 'center' | 'end' | 'stretch'
   type LayerName = 'back' | 'mid' | 'front' | 'top'
   type BleedDirection = 'left' | 'right' | 'both'
-  type AspectRatio = '1/1' | '4/3' | '3/4' | '16/9' | '9/16' | '2/1' | '1/2'
 
   interface ResponsiveValue<T> {
     default: T
@@ -64,10 +61,8 @@
     container?: ContainerSize
     gap?: string
     density?: Density
-    z?: number
     layer?: LayerName
     bleed?: BleedDirection
-    aspect?: AspectRatio
   }
 
   const {
@@ -82,10 +77,8 @@
     container: containerProp = undefined,
     gap: gapProp = undefined,
     density: densityProp = undefined,
-    z = undefined,
     layer = undefined,
     bleed = undefined,
-    aspect = undefined,
   } = defineProps<Props>()
 
   // Get preset configuration if preset prop is provided
@@ -116,16 +109,13 @@
       container: container.value,
       gap: gap.value,
       density: density.value,
-      z,
       layer,
       bleed,
-      aspect,
     })
   )
 
   const classes = computed(() =>
     buildGridPlacementClasses({
-      aspect,
       container: container.value,
     })
   )
@@ -139,6 +129,10 @@
 
 <style>
   /* stylelint-disable custom-property-pattern */
+  /* 48rem/80rem below match core's --breakpoint-md/--breakpoint-xl (see
+     layers/core/app/assets/css/tokens/breakpoints.css) — can't reference the
+     custom properties directly, @media conditions don't accept var(). Keep
+     in sync by convention (nuxt-declarative-layout-system-spec.md §14/Phase 3). */
   .gi-placed {
     grid-row: var(--_rs, auto) / span var(--_re, 1);
     grid-column: var(--_cs, auto) / span var(--_ce, 1);

package/layers/{layout → structure/layout}/app/components/Layout/Main.vue

@@ -1,10 +1,10 @@
 <script setup lang="ts">
   /**
-   * LayoutMain — grid root container applying the `mastmain` utility.
+   * LayoutMain — grid root container applying the `grid-root` 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">`.
+   * raw `<main class="grid-root">`.
    *
    * When `mode` is `'disabled'`, falls back to a plain semantic `<main>` so the
    * page renders correctly without grid dependencies.
@@ -29,7 +29,7 @@
 <template>
   <component
     :is="tag"
-    :class="mode !== 'disabled' ? 'mastmain' : undefined"
+    :class="mode !== 'disabled' ? 'grid-root' : undefined"
     :style="
       mode !== 'disabled'
         ? { paddingInline: 'var(--grid-padding, clamp(1rem, 2.5vw, 2rem))' }

package/layers/{layout → structure/layout}/app/components/Layout/Page/Header.vue

@@ -3,7 +3,7 @@
    * PageHeader - Standard page header component
    *
    * Displays a centered page title and optional description with consistent spacing.
-   * Used by PageContainer for visible page headers.
+   * Used by LayoutPage for visible page headers.
    *
    * @prop {string} title - Page title (displays as h1)
    * @prop {string} description - Optional page description

package/layers/{layout → structure/layout}/app/components/Layout/Page/index.vue

@@ -3,8 +3,8 @@
    * 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.
+   * provided by LayoutMain at the layout level via <main class="grid-root">.
+   * Adding another grid-root wrapper here would nest grids and misalign everything.
    *
    * Responsibilities:
    *   - SEO via useHead()
@@ -64,6 +64,6 @@
     </LayoutGridItem>
   </LayoutSection>
 
-  <!-- Page content — direct children of mastmain (via MastMain in the layout) -->
+  <!-- Page content — direct children of grid-root (via LayoutMain in the layout) -->
   <slot />
 </template>

package/layers/{layout → structure/layout}/app/components/Layout/Section/index.vue

@@ -2,7 +2,7 @@
   /**
    * BaseSection - Full-viewport section using subgrid
    *
-   * Inherits the parent MastMain's 18-column grid lines using CSS subgrid.
+   * Inherits the parent LayoutMain's 18-column grid lines using CSS subgrid.
    * Spans 12 rows (1 viewport height) for full-screen sections.
    * Child GridItem elements position themselves on these inherited grid lines.
    *

package/layers/structure/layout/app/components/Spacer.vue

@@ -0,0 +1,21 @@
+<script setup lang="ts">
+  /**
+   * Spacer — flexible remaining space inside HStack/VStack.
+   * See nuxt-declarative-layout-system-spec.md §9.
+   */
+
+  const { size = undefined } = defineProps<{
+    /** Fixed size instead of flexible — rare; only when a concrete need arises. */
+    size?: string
+  }>()
+</script>
+
+<template>
+  <div class="spacer" :style="size ? { flex: `0 0 ${size}` } : undefined" />
+</template>
+
+<style scoped>
+  .spacer {
+    flex: 1 1 auto;
+  }
+</style>

package/layers/structure/layout/app/components/VStack.vue

@@ -0,0 +1,37 @@
+<script setup lang="ts">
+  /**
+   * VStack — vertical, one-dimensional layout (Flexbox column).
+   * See nuxt-declarative-layout-system-spec.md §7.
+   */
+
+  import type { Justify } from '#layers/core/app/composables/useLayoutAttrs'
+  import type { ResponsiveValue } from '#layers/core/types/responsive'
+  import type { Spacing } from '#layers/core/types/tokens'
+
+  type VStackAlign = 'start' | 'center' | 'end' | 'stretch'
+
+  const {
+    gap = undefined,
+    align = undefined,
+    justify = undefined,
+  } = defineProps<{
+    gap?: ResponsiveValue<Spacing> | Spacing
+    align?: ResponsiveValue<VStackAlign> | VStackAlign
+    justify?: ResponsiveValue<Justify> | Justify
+  }>()
+
+  const { style } = useLayoutAttrs(() => ({ gap, align, justify }))
+</script>
+
+<template>
+  <div class="v-stack" :style>
+    <slot />
+  </div>
+</template>
+
+<style scoped>
+  .v-stack {
+    display: flex;
+    flex-direction: column;
+  }
+</style>

package/layers/structure/layout/app/components/ZStack.vue

@@ -0,0 +1,28 @@
+<script setup lang="ts">
+  /**
+   * ZStack — layered content. A single-area CSS grid; direct slot children
+   * all share that one grid area, stacking by source order (later = on top).
+   * See nuxt-declarative-layout-system-spec.md §8.
+   *
+   * ponytail: no placement prop yet (start/center/end vocabulary is deferred
+   * until a concrete need arises — the shared grid area already fills the
+   * stack for the common case).
+   */
+</script>
+
+<template>
+  <div class="z-stack">
+    <slot />
+  </div>
+</template>
+
+<style scoped>
+  .z-stack {
+    display: grid;
+    grid-template-areas: 'stack';
+  }
+
+  :slotted(*) {
+    grid-area: stack;
+  }
+</style>

package/layers/structure/layout/app/layouts/default.vue

@@ -0,0 +1,5 @@
+<template>
+  <LayoutMain>
+    <slot />
+  </LayoutMain>
+</template>

package/layers/{layout → structure/layout}/app/types/layouts.ts

@@ -29,7 +29,7 @@ export type GridLayers = {
 
 export type GridContainerSize = 'content' | 'wide' | 'fluid' | 'full'
 export type GridDensity = 'compact' | 'normal' | 'relaxed' // relaxed = 0.5rem --rhythm base
-export type GridMode = 'swiss' | 'fluid' | 'disabled'
+export type GridMode = 'swiss' | 'disabled'
 
 export type GridPresetsItem = {
   colStart?: number | ResponsiveValue<number>
@@ -54,8 +54,7 @@ export type GridConfig = {
   /**
    * Layout mode.
    * - `'swiss'`    — Swiss Grid System (default)
-   * - `'fluid'`    — Container-query based auto-fit grid
-   * - `'disabled'` — Falls back to standard Nuxt UI layout
+   * - `'disabled'` — Falls back to a plain, ungridded `<main>`
    *
    * Setting `enabled: false` is equivalent to `mode: 'disabled'` (backwards compat).
    */