kmcom-nuxt-layers 5.0.7 → 6.0.0

package/docs/adr/0001-grid-replaces-layout-swiss-grid.md

@@ -0,0 +1,30 @@
+# 0001 — `grid` replaces `layout`'s Swiss grid; don't merge them piecemeal
+
+Status: accepted (2026-10-20)
+
+## Context
+
+Tier 2 has two grid systems:
+
+- `layout` — fixed 6/12/18 columns by breakpoint (`LayoutGridItem`, `useGridConfig`,
+  `layoutLayer.ui.grid`). Seven `content` components and `Hero`/`Split`/`Gallery` assume 18
+  numbered columns.
+- `grid` — data-driven tracks (`useGridTracks`), named presets, rhythm derived from `--fs`,
+  named-line placement. No layer consumes it yet; only two playground pages do.
+
+`docs/superpowers/specs/2026-09-04-grid-layer-design.md` created `grid` as the replacement and
+put `layout`'s grid components out of scope, deferring their migration.
+
+## Decision
+
+Treat the overlap as an in-flight migration, not accidental duplication. Do not fold either
+system into the other, share a preset registry, or rename config namespaces in isolation.
+Migrating `layout` to consume `grid` is its own brainstormed pass, covering `LayoutGridItem`,
+the `content` components, and the 18-column assumptions.
+
+## Consequences
+
+- `layoutLayer.ui.grid` (including the z-index `layers` that `navigation` reads through
+  `useGridConfig().useZIndex`) is consumer-facing app config and stays as is until that pass.
+- Architecture reviews should not re-suggest merging `layout` and `grid` or picking a single
+  "owner" for the `swiss` preset.

package/docs/adr/0002-content-config-is-app-owned.md

@@ -0,0 +1,27 @@
+# 0002 — Each app owns its `content.config.ts`; don't hoist collections into the layer
+
+Status: accepted (2026-10-20)
+
+## Context
+
+`apps/playground/content.config.ts` redeclares the four collections that
+`layers/content/content.config.ts` also defines, which looks like duplication.
+
+`@nuxt/content` 3.15.2 (`loadContentConfig`) loads `content.config.ts` from every layer in
+`nuxt.options._layers` and merges collections by name, with the app last. Each collection is
+tagged `__rootDir` = the config's own layer directory, and source scanning is rooted there. A
+collection defined only in the layer therefore reads `layers/content/content/**`, never the
+app's `content/` folder.
+
+## Decision
+
+Each consumer app declares its own collections. The layer's `content.config.ts` serves standalone
+runs only, and it is not in the published package `files`. Do not try to remove the playground
+copy, wrap `defineCollection` in layer-exported factories, or point `source` at the app from the
+layer.
+
+## Consequences
+
+- Drift risk is limited to four glob strings per app; `layers/content/CLAUDE.md` holds the
+  copy-paste config.
+- Schemas must still never be passed to `defineCollection` (c12/jiti validator issue).

package/layers/core/app/components/Element.vue

@@ -2,73 +2,9 @@
   import { useElementStyle } from '../composables/useElementStyle'
   import type { ElementProps } from '../types/element'
 
-  const {
-    as = 'div',
-    componentProps,
-    block,
-    flex,
-    grid: gridMode,
-    hidden,
-    cols,
-    rows,
-    gap,
-    align,
-    justify,
-    p,
-    px,
-    py,
-    m,
-    mx,
-    my,
-    w,
-    h,
-    minW,
-    maxW,
-    minH,
-    maxH,
-    aspect,
-    bg,
-    color,
-    border,
-    radius,
-    shadow,
-    cursor,
-    select,
-    pointer,
-  } = defineProps<ElementProps>()
+  const { as = 'div', componentProps, ...styleProps } = defineProps<ElementProps>()
 
-  const style = useElementStyle(() => ({
-    block,
-    flex,
-    grid: gridMode,
-    hidden,
-    cols,
-    rows,
-    gap,
-    align,
-    justify,
-    p,
-    px,
-    py,
-    m,
-    mx,
-    my,
-    w,
-    h,
-    minW,
-    maxW,
-    minH,
-    maxH,
-    aspect,
-    bg,
-    color,
-    border,
-    radius,
-    shadow,
-    cursor,
-    select,
-    pointer,
-  }))
+  const style = useElementStyle(() => styleProps)
 </script>
 
 <template>

package/layers/core/app/components/ElementTw.vue

@@ -8,73 +8,9 @@
   import type { ElementProps } from '../types/element'
   import { styleToTailwindClasses } from '../utils/styleToTailwindClasses'
 
-  const {
-    as = 'div',
-    componentProps,
-    block,
-    flex,
-    grid: gridMode,
-    hidden,
-    cols,
-    rows,
-    gap,
-    align,
-    justify,
-    p,
-    px,
-    py,
-    m,
-    mx,
-    my,
-    w,
-    h,
-    minW,
-    maxW,
-    minH,
-    maxH,
-    aspect,
-    bg,
-    color,
-    border,
-    radius,
-    shadow,
-    cursor,
-    select,
-    pointer,
-  } = defineProps<ElementProps>()
+  const { as = 'div', componentProps, ...styleProps } = defineProps<ElementProps>()
 
-  const style = useElementStyle(() => ({
-    block,
-    flex,
-    grid: gridMode,
-    hidden,
-    cols,
-    rows,
-    gap,
-    align,
-    justify,
-    p,
-    px,
-    py,
-    m,
-    mx,
-    my,
-    w,
-    h,
-    minW,
-    maxW,
-    minH,
-    maxH,
-    aspect,
-    bg,
-    color,
-    border,
-    radius,
-    shadow,
-    cursor,
-    select,
-    pointer,
-  }))
+  const style = useElementStyle(() => styleProps)
 
   const twClasses = computed(() => styleToTailwindClasses(style.value))
 </script>

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

@@ -1,65 +1,11 @@
 import { computed, type ComputedRef, type CSSProperties } from 'vue'
 
-import type { ElementProps } from '../types/element'
-import { useElementGrid } from './useElementGrid'
-import { useElementInteraction } from './useElementInteraction'
-import { useElementLayout } from './useElementLayout'
-import { useElementSizing } from './useElementSizing'
-import { useElementSurface } from './useElementSurface'
-import { useLayoutAttrs } from './useLayoutAttrs'
+import { resolveElementStyle, type ElementStyleInput } from '../utils/resolveElementStyle'
 
 /**
- * Merges the 5 element composables + core's useLayoutAttrs into one style
- * object — the vocabulary shared by both Element (inline :style) and
- * ElementTw (Tailwind arbitrary-property classes). Takes a getter (not the
- * values directly) so callers can pass their own destructured defineProps
- * bindings and keep reactivity, same as useLayoutAttrs's own getter param.
+ * Reactive wrapper over resolveElementStyle. Takes a getter so callers can pass their
+ * `defineProps` result directly (`useElementStyle(() => props)`) and keep reactivity.
  */
-export function useElementStyle(
-  getProps: () => Omit<ElementProps, 'as' | 'componentProps'>
-): ComputedRef<CSSProperties> {
-  return computed(() => {
-    const props = getProps()
-    return {
-      ...useElementLayout({
-        block: props.block,
-        flex: props.flex,
-        grid: props.grid,
-        hidden: props.hidden,
-      }),
-      ...useLayoutAttrs(() => ({
-        gap: props.gap,
-        align: props.align,
-        justify: props.justify,
-        p: props.p,
-        px: props.px,
-        py: props.py,
-        m: props.m,
-        mx: props.mx,
-        my: props.my,
-      })).style.value,
-      ...useElementGrid({ grid: props.grid, cols: props.cols, rows: props.rows }),
-      ...useElementSizing({
-        w: props.w,
-        h: props.h,
-        minW: props.minW,
-        maxW: props.maxW,
-        minH: props.minH,
-        maxH: props.maxH,
-        aspect: props.aspect,
-      }),
-      ...useElementSurface({
-        bg: props.bg,
-        color: props.color,
-        border: props.border,
-        radius: props.radius,
-        shadow: props.shadow,
-      }),
-      ...useElementInteraction({
-        cursor: props.cursor,
-        select: props.select,
-        pointer: props.pointer,
-      }),
-    }
-  })
+export function useElementStyle(getProps: () => ElementStyleInput): ComputedRef<CSSProperties> {
+  return computed(() => resolveElementStyle(getProps()))
 }

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

@@ -66,29 +66,29 @@ function applySpacing(
   if (resolved) result[cssProp] = spacingVar(resolved)
 }
 
-export function useLayoutAttrs(input: MaybeRefOrGetter<LayoutAttrsInput>): {
-  style: ComputedRef<CSSProperties>
-} {
-  const style = computed((): CSSProperties => {
-    const { gap, align, justify, p, px, py, m, mx, my } = toValue(input)
-    const result: CSSProperties = {}
+export function resolveLayoutAttrsStyle(input: LayoutAttrsInput): CSSProperties {
+  const { gap, align, justify, p, px, py, m, mx, my } = input
+  const result: CSSProperties = {}
 
-    applySpacing(result, 'gap', gap)
-    applySpacing(result, 'padding', p)
-    applySpacing(result, 'paddingInline', px)
-    applySpacing(result, 'paddingBlock', py)
-    applySpacing(result, 'margin', m)
-    applySpacing(result, 'marginInline', mx)
-    applySpacing(result, 'marginBlock', my)
+  applySpacing(result, 'gap', gap)
+  applySpacing(result, 'padding', p)
+  applySpacing(result, 'paddingInline', px)
+  applySpacing(result, 'paddingBlock', py)
+  applySpacing(result, 'margin', m)
+  applySpacing(result, 'marginInline', mx)
+  applySpacing(result, 'marginBlock', my)
 
-    const resolvedAlign = resolveDefault(align)
-    if (resolvedAlign) result.alignItems = ALIGN_MAP[resolvedAlign]
+  const resolvedAlign = resolveDefault(align)
+  if (resolvedAlign) result.alignItems = ALIGN_MAP[resolvedAlign]
 
-    const resolvedJustify = resolveDefault(justify)
-    if (resolvedJustify) result.justifyContent = JUSTIFY_MAP[resolvedJustify]
+  const resolvedJustify = resolveDefault(justify)
+  if (resolvedJustify) result.justifyContent = JUSTIFY_MAP[resolvedJustify]
 
-    return result
-  })
+  return result
+}
 
-  return { style }
+export function useLayoutAttrs(input: MaybeRefOrGetter<LayoutAttrsInput>): {
+  style: ComputedRef<CSSProperties>
+} {
+  return { style: computed(() => resolveLayoutAttrsStyle(toValue(input))) }
 }

package/layers/core/app/types/element.ts

@@ -1,25 +1,48 @@
-import type { Component } from 'vue'
+import type { Component, CSSProperties } from 'vue'
 
-import type { ElementGridProps } from '../composables/useElementGrid'
-import type { ElementInteractionProps } from '../composables/useElementInteraction'
-import type { ElementLayoutProps } from '../composables/useElementLayout'
-import type { ElementSizingProps } from '../composables/useElementSizing'
-import type { ElementSurfaceProps } from '../composables/useElementSurface'
 // Relative, not the '#layers/core' alias: the SFC compiler's macro type
 // resolution (defineProps<ElementProps>() in Element.vue) walks tsconfig
 // "paths" directly and doesn't see Nuxt's generated layer aliases outside
 // a running Nuxt instance — a plain relative import resolves everywhere.
 import type { LayoutAttrsInput } from '../composables/useLayoutAttrs'
 
-export type ElementProps = ElementLayoutProps &
-  ElementGridProps &
-  LayoutAttrsInput &
-  ElementSizingProps &
-  ElementSurfaceProps &
-  ElementInteractionProps & {
-    as?: string | Component
-    // Escape hatch for prop names that collide with Element's own (e.g. `color`
-    // is Element's raw-CSS text colour, but also UBadge's semantic colour prop).
-    // Non-colliding component props still reach `as` for free via attrs fallthrough.
-    componentProps?: Record<string, unknown>
-  }
+// `| undefined` on each is explicit (not just `?`) so component prop objects
+// — which have it too, under exactOptionalPropertyTypes — are assignable here.
+export type ElementProps = LayoutAttrsInput & {
+  as?: string | Component
+  // Escape hatch for prop names that collide with Element's own (e.g. `color`
+  // is Element's raw-CSS text colour, but also UBadge's semantic colour prop).
+  // Non-colliding component props still reach `as` for free via attrs fallthrough.
+  componentProps?: Record<string, unknown>
+
+  // Display mode — priority hidden > grid > flex > block
+  block?: boolean | undefined
+  flex?: boolean | undefined
+  grid?: boolean | undefined
+  hidden?: boolean | undefined
+
+  // Grid container tracks (numbers become `repeat(n, 1fr)`; only applied when `grid` is set)
+  cols?: number | string | undefined
+  rows?: number | string | undefined
+
+  // Sizing
+  w?: CSSProperties['width'] | undefined
+  h?: CSSProperties['height'] | undefined
+  minW?: CSSProperties['minWidth'] | undefined
+  maxW?: CSSProperties['maxWidth'] | undefined
+  minH?: CSSProperties['minHeight'] | undefined
+  maxH?: CSSProperties['maxHeight'] | undefined
+  aspect?: CSSProperties['aspectRatio'] | undefined
+
+  // Surface
+  bg?: CSSProperties['background'] | undefined
+  color?: CSSProperties['color'] | undefined
+  border?: CSSProperties['border'] | undefined
+  radius?: CSSProperties['borderRadius'] | undefined
+  shadow?: CSSProperties['boxShadow'] | undefined
+
+  // Interaction
+  cursor?: CSSProperties['cursor'] | undefined
+  select?: CSSProperties['userSelect'] | undefined
+  pointer?: CSSProperties['pointerEvents'] | undefined
+}

package/layers/core/app/utils/resolveElementStyle.test.ts

@@ -0,0 +1,99 @@
+import { describe, expect, it } from 'vite-plus/test'
+
+import { resolveElementStyle } from './resolveElementStyle'
+
+describe('resolveElementStyle display mode', () => {
+  it('returns no display when no mode prop is set', () => {
+    expect(resolveElementStyle({}).display).toBeUndefined()
+  })
+
+  it.each([
+    ['block', 'block'],
+    ['flex', 'flex'],
+    ['grid', 'grid'],
+    ['hidden', 'none'],
+  ] as const)('resolves %s to display: %s', (prop, display) => {
+    expect(resolveElementStyle({ [prop]: true }).display).toBe(display)
+  })
+
+  it('prioritizes hidden > grid > flex > block', () => {
+    expect(resolveElementStyle({ hidden: true, grid: true, flex: true, block: true }).display).toBe(
+      'none'
+    )
+    expect(resolveElementStyle({ grid: true, flex: true, block: true }).display).toBe('grid')
+    expect(resolveElementStyle({ flex: true, block: true }).display).toBe('flex')
+  })
+})
+
+describe('resolveElementStyle grid container axis', () => {
+  it('returns no grid-template properties when grid is not set', () => {
+    const style = resolveElementStyle({ cols: 12 })
+    expect(style.gridTemplateColumns).toBeUndefined()
+    expect(style.gridTemplateRows).toBeUndefined()
+  })
+
+  it('converts numeric cols/rows to repeat() tracks when grid is set', () => {
+    const style = resolveElementStyle({ grid: true, cols: 12, rows: 4 })
+    expect(style.gridTemplateColumns).toBe('repeat(12, 1fr)')
+    expect(style.gridTemplateRows).toBe('repeat(4, 1fr)')
+  })
+
+  it('passes a string track through unchanged', () => {
+    expect(resolveElementStyle({ grid: true, cols: '1fr 2fr 1fr' }).gridTemplateColumns).toBe(
+      '1fr 2fr 1fr'
+    )
+  })
+})
+
+describe('resolveElementStyle prop mapping', () => {
+  it('maps sizing, surface and interaction props to their CSS properties 1:1', () => {
+    expect(
+      resolveElementStyle({
+        w: '10px',
+        h: '20px',
+        minW: '1px',
+        maxW: '2px',
+        minH: '3px',
+        maxH: '4px',
+        aspect: '16 / 9',
+        bg: 'red',
+        color: 'blue',
+        border: '1px solid',
+        radius: '4px',
+        shadow: '0 0 1px black',
+        cursor: 'pointer',
+        select: 'none',
+        pointer: 'none',
+      })
+    ).toMatchObject({
+      width: '10px',
+      height: '20px',
+      minWidth: '1px',
+      maxWidth: '2px',
+      minHeight: '3px',
+      maxHeight: '4px',
+      aspectRatio: '16 / 9',
+      background: 'red',
+      color: 'blue',
+      border: '1px solid',
+      borderRadius: '4px',
+      boxShadow: '0 0 1px black',
+      cursor: 'pointer',
+      userSelect: 'none',
+      pointerEvents: 'none',
+    })
+  })
+
+  it('merges layout attrs (gap/align/padding) into the same object', () => {
+    expect(resolveElementStyle({ flex: true, gap: 'md', align: 'center', p: 'sm' })).toMatchObject({
+      display: 'flex',
+      gap: 'var(--fluid-space-md)',
+      alignItems: 'center',
+      padding: 'var(--fluid-space-sm)',
+    })
+  })
+
+  it('leaves every property undefined when no props are set', () => {
+    expect(Object.values(resolveElementStyle({})).every((v) => v === undefined)).toBe(true)
+  })
+})

package/layers/core/app/utils/resolveElementStyle.ts

@@ -0,0 +1,52 @@
+import type { CSSProperties } from 'vue'
+
+import { resolveLayoutAttrsStyle } from '../composables/useLayoutAttrs'
+import type { ElementProps } from '../types/element'
+
+export type ElementStyleInput = Omit<ElementProps, 'as' | 'componentProps'>
+
+const DISPLAY_FOR = {
+  hidden: 'none',
+  grid: 'grid',
+  flex: 'flex',
+  block: 'block',
+} as const
+
+function track(value: number | string | undefined): string | undefined {
+  return typeof value === 'number' ? `repeat(${value}, 1fr)` : value
+}
+
+/**
+ * Element's whole prop vocabulary → one CSSProperties object. Pure: shared by Element
+ * (inline :style) and ElementTw (Tailwind arbitrary-property classes).
+ *
+ * Grid is container axis only ("I am a grid"). Item placement lives in the layout layer
+ * (buildGridPlacementStyle); Element is in core and can't depend on layout.
+ */
+export function resolveElementStyle(props: ElementStyleInput): CSSProperties {
+  // hidden > grid > flex > block
+  const mode = (['hidden', 'grid', 'flex', 'block'] as const).find((m) => props[m])
+  return {
+    display: mode && DISPLAY_FOR[mode],
+    ...resolveLayoutAttrsStyle(props),
+    ...(props.grid && {
+      gridTemplateColumns: track(props.cols),
+      gridTemplateRows: track(props.rows),
+    }),
+    width: props.w,
+    height: props.h,
+    minWidth: props.minW,
+    maxWidth: props.maxW,
+    minHeight: props.minH,
+    maxHeight: props.maxH,
+    aspectRatio: props.aspect,
+    background: props.bg,
+    color: props.color,
+    border: props.border,
+    borderRadius: props.radius,
+    boxShadow: props.shadow,
+    cursor: props.cursor,
+    userSelect: props.select,
+    pointerEvents: props.pointer,
+  }
+}

package/layers/data/metadata/providers/comicvine/server/utils/metadata-comicvine/client.ts

@@ -1,3 +1,4 @@
+import { MetadataProviderError } from '#layers/metadata/server/utils/metadata/errors'
 import { useRuntimeConfig } from 'nitropack/runtime'
 import type { ComicVineApiResponse, ComicVineIssue, ComicVineVolume } from './types'
 

package/layers/data/metadata/providers/comicvine/server/utils/metadata-comicvine/provider.ts

@@ -58,14 +58,4 @@ export const comicVineProvider: MetadataProvider = {
     const res = await fetchComicVineIssue(providerId)
     return normaliseComicVineIssue(res.results as ComicVineIssue)
   },
-
-  async sync({ providerId, resourceType = 'issue' }) {
-    const record = await comicVineProvider.lookup({
-      provider: 'comicvine',
-      providerId,
-      resourceType,
-    })
-    if (!record) throw new MetadataProviderError('comicvine', `No record found for ${providerId}`)
-    return record
-  },
 }

package/layers/data/metadata/providers/google-books/server/utils/metadata-google-books/client.ts

@@ -1,3 +1,4 @@
+import { providerFetch } from '#layers/metadata/server/utils/metadata/provider-fetch'
 import { useRuntimeConfig } from 'nitropack/runtime'
 import type { MetadataMediaType } from '#layers/metadata/shared/types'
 
@@ -29,15 +30,17 @@ export async function searchGoogleBooks(
   query: string,
   limit = 10
 ): Promise<GoogleBooksSearchResponse> {
-  const params: Record<string, string> = { q: query, maxResults: String(limit), langRestrict: 'en' }
+  const params: Record<string, string> = {
+    q: query,
+    maxResults: String(limit),
+    langRestrict: 'en',
+  }
   const apiKey = getApiKey()
   if (apiKey) params.key = apiKey
 
-  try {
-    return await $fetch<GoogleBooksSearchResponse>(`${BASE}/volumes`, { query: params })
-  } catch (err) {
-    throw new MetadataProviderError('google-books', `API error: ${String(err)}`)
-  }
+  return providerFetch<GoogleBooksSearchResponse>('google-books', `${BASE}/volumes`, {
+    query: params,
+  })
 }
 
 export async function fetchGoogleBooksVolume(id: string): Promise<GoogleBooksVolume> {
@@ -45,9 +48,7 @@ export async function fetchGoogleBooksVolume(id: string): Promise<GoogleBooksVol
   const apiKey = getApiKey()
   if (apiKey) params.key = apiKey
 
-  try {
-    return await $fetch<GoogleBooksVolume>(`${BASE}/volumes/${id}`, { query: params })
-  } catch (err) {
-    throw new MetadataProviderError('google-books', `API error: ${String(err)}`)
-  }
+  return providerFetch<GoogleBooksVolume>('google-books', `${BASE}/volumes/${id}`, {
+    query: params,
+  })
 }

package/layers/data/metadata/providers/google-books/server/utils/metadata-google-books/provider.ts

@@ -23,11 +23,4 @@ export const googleBooksProvider: MetadataProvider = {
     const volume = await fetchGoogleBooksVolume(providerId)
     return normaliseGoogleBooksVolume(volume)
   },
-
-  async sync({ providerId }) {
-    const record = await googleBooksProvider.lookup({ provider: 'google-books', providerId })
-    if (!record)
-      throw new MetadataProviderError('google-books', `No record found for ${providerId}`)
-    return record
-  },
 }