kmcom-nuxt-layers 6.2.1 → 6.4.0

package/layers/content/app/components/Blog/List.vue

@@ -1,11 +1,18 @@
 <script setup lang="ts">
+  import type { BlogCollectionItem } from '@nuxt/content'
+
   import type { BlogQueryOptions } from '../../types/content'
 
-  const { options = {} } = defineProps<{
+  const { items = undefined, options = {} } = defineProps<{
+    items?: BlogCollectionItem[]
     options?: BlogQueryOptions
   }>()
 
-  const { data: posts, status } = await useBlogPosts(options)
+  // Fetch only when the parent didn't pass items (e.g. a related-items list it already has).
+  // ponytail: decided once at setup — toggling `items` after mount won't start or stop the fetch
+  const fetched = items ? undefined : await useBlogPosts(options)
+  const posts = computed(() => items ?? fetched?.data.value)
+  const status = computed(() => (items ? 'success' : (fetched?.status.value ?? 'idle')))
 </script>
 
 <template>

package/layers/content/app/components/Blog/Page.vue

@@ -1,25 +1,15 @@
 <script setup lang="ts">
-  import type { ContentLayerConfig } from '#layers/content/app/types/content'
+  const { title = 'Blog', description = 'Articles and posts' } = defineProps<{
+    title?: string
+    description?: string
+  }>()
 
-  const appConfig = useAppConfig()
-  const contentLayer = appConfig.contentLayer as ContentLayerConfig | undefined
-  if (contentLayer?.sections?.blog === false) {
-    throw createError({ statusCode: 404, statusMessage: 'Not Found' })
-  }
-
-  useSeoMeta({
-    title: 'Blog',
-    description: 'Articles and posts',
-  })
+  useContentSection('blog')
+  useSeoMeta({ title: () => title, description: () => description })
 </script>
 
 <template>
-  <LayoutSection>
-    <LayoutGridItem>
-      <UPageHeader title="Blog" description="Articles and posts" />
-      <UPageBody>
-        <BlogList />
-      </UPageBody>
-    </LayoutGridItem>
-  </LayoutSection>
+  <NuxtContentIndexTemplate :title :description>
+    <BlogList />
+  </NuxtContentIndexTemplate>
 </template>

package/layers/content/app/components/Gallery/Detail.vue

@@ -66,6 +66,7 @@
               </div>
             </NuxtLink>
             <button
+              :aria-label="`View ${img.alt || 'image'} larger`"
               class="absolute top-2 right-2 z-10 cursor-pointer rounded-full bg-black/50 p-1.5 text-white opacity-0 transition-opacity duration-300 group-hover:opacity-100 hover:bg-black/70"
               @click.stop="() => openLightbox(asGallery(item).images!, idx)"
             >

package/layers/content/app/components/Gallery/Grid.vue

@@ -1,11 +1,18 @@
 <script setup lang="ts">
+  import type { GalleryCollectionItem } from '@nuxt/content'
+
   import type { GalleryQueryOptions } from '../../types/content'
 
-  const { options = {} } = defineProps<{
+  const { items: passed = undefined, options = {} } = defineProps<{
+    items?: GalleryCollectionItem[]
     options?: GalleryQueryOptions
   }>()
 
-  const { data: items, status } = await useGalleryItems(options)
+  // Fetch only when the parent didn't pass items (e.g. a related-items list it already has).
+  // ponytail: decided once at setup — toggling `items` after mount won't start or stop the fetch
+  const fetched = passed ? undefined : await useGalleryItems(options)
+  const items = computed(() => passed ?? fetched?.data.value)
+  const status = computed(() => (passed ? 'success' : (fetched?.status.value ?? 'idle')))
 </script>
 
 <template>

package/layers/content/app/components/Gallery/ImageDetail.vue

@@ -13,12 +13,6 @@
   const totalImages = computed(() => item.value?.images?.length ?? 0)
   const hasPrevious = computed(() => index > 0)
   const hasNext = computed(() => index < totalImages.value - 1)
-
-  useSeoMeta({
-    title: () => image.value?.title || image.value?.alt || `Image ${index + 1}`,
-    description: () => image.value?.caption || item.value?.title,
-    ogImage: () => image.value?.src,
-  })
 </script>
 
 <template>

package/layers/content/app/components/Gallery/ImagePage.vue

@@ -1,16 +1,20 @@
 <script setup lang="ts">
-  import type { ContentLayerConfig } from '#layers/content/app/types/content'
+  import type { GalleryCollectionItem } from '@nuxt/content'
 
   const { slug, index } = defineProps<{
     slug: string
     index: number
   }>()
 
-  const appConfig = useAppConfig()
-  const contentLayer = appConfig.contentLayer as ContentLayerConfig | undefined
-  if (contentLayer?.sections?.gallery === false) {
-    throw createError({ statusCode: 404, statusMessage: 'Not Found' })
-  }
+  useContentSection('gallery')
+
+  const { data } = await useCollectionItem('gallery', slug)
+  const meta = computed(() => galleryImageMeta(data.value as GalleryCollectionItem | null, index))
+  useSeoMeta({
+    title: () => meta.value.title,
+    description: () => meta.value.description,
+    ogImage: () => meta.value.ogImage,
+  })
 </script>
 
 <template>

package/layers/content/app/components/Gallery/Page.vue

@@ -1,25 +1,15 @@
 <script setup lang="ts">
-  import type { ContentLayerConfig } from '#layers/content/app/types/content'
+  const { title = 'Gallery', description = 'Photo collections and visual work' } = defineProps<{
+    title?: string
+    description?: string
+  }>()
 
-  const appConfig = useAppConfig()
-  const contentLayer = appConfig.contentLayer as ContentLayerConfig | undefined
-  if (contentLayer?.sections?.gallery === false) {
-    throw createError({ statusCode: 404, statusMessage: 'Not Found' })
-  }
-
-  useSeoMeta({
-    title: 'Gallery',
-    description: 'Photo collections and visual work',
-  })
+  useContentSection('gallery')
+  useSeoMeta({ title: () => title, description: () => description })
 </script>
 
 <template>
-  <LayoutSection>
-    <LayoutGridItem>
-      <UPageHeader title="Gallery" description="Photo collections and visual work" />
-      <UPageBody>
-        <GalleryGrid />
-      </UPageBody>
-    </LayoutGridItem>
-  </LayoutSection>
+  <NuxtContentIndexTemplate :title :description>
+    <GalleryGrid />
+  </NuxtContentIndexTemplate>
 </template>

package/layers/content/app/components/Gallery/SlugPage.vue

@@ -1,15 +1,10 @@
 <script setup lang="ts">
-  import type { ContentLayerConfig } from '#layers/content/app/types/content'
-
   const { slug } = defineProps<{
     slug: string
   }>()
 
-  const appConfig = useAppConfig()
-  const contentLayer = appConfig.contentLayer as ContentLayerConfig | undefined
-  if (contentLayer?.sections?.gallery === false) {
-    throw createError({ statusCode: 404, statusMessage: 'Not Found' })
-  }
+  useContentSection('gallery')
+  await useContentItemSeo('gallery', slug)
 </script>
 
 <template>

package/layers/content/app/components/NuxtContent/Detail.vue

@@ -20,23 +20,32 @@
   const surroundLinks = computed<ContentSurroundLink[] | undefined>(
     () => surround.value ?? undefined
   )
-  const itemImage = computed(() => (item.value as { image?: string } | null)?.image)
 
-  useSeoMeta({
-    title: item.value?.title,
-    description: item.value?.description,
-    ogImage: itemImage,
+  // Optional props only bound when present (exactOptionalPropertyTypes rejects `undefined`)
+  const headerProps = computed(() =>
+    item.value?.description ? { description: item.value.description } : {}
+  )
+  const surroundProps = computed(() =>
+    surroundLinks.value?.length ? { surround: surroundLinks.value } : {}
+  )
+  const tocProps = computed(() => {
+    const links = item.value?.body?.toc?.links
+    return links ? { links } : {}
   })
 </script>
 
 <template>
   <div>
     <USkeleton v-if="status === 'pending'" class="h-96 w-full" />
+    <UAlert
+      v-else-if="status === 'error'"
+      color="error"
+      variant="subtle"
+      icon="lucide:circle-alert"
+      title="This page couldn't be loaded. Try again shortly."
+    />
     <UPage v-else-if="item">
-      <UPageHeader
-        :title="item.title"
-        v-bind="item.description ? { description: item.description } : {}"
-      >
+      <UPageHeader :title="item.title" v-bind="headerProps">
         <template v-if="$slots.headline" #headline>
           <slot name="headline" :item />
         </template>
@@ -51,11 +60,11 @@
         <slot name="after-content" :item />
 
         <USeparator class="my-8" />
-        <NuxtContentSurround v-bind="surroundLinks?.length ? { surround: surroundLinks } : {}" />
+        <NuxtContentSurround v-bind="surroundProps" />
       </UPageBody>
 
       <template v-if="!hideToc" #right>
-        <NuxtContentToc v-bind="item.body?.toc?.links ? { links: item.body.toc.links } : {}" />
+        <NuxtContentToc v-bind="tocProps" />
       </template>
     </UPage>
     <div v-else class="text-muted py-12 text-center">{{ notFoundMessage }}</div>

package/layers/content/app/components/NuxtContent/IndexTemplate.vue

@@ -0,0 +1,21 @@
+<script setup lang="ts">
+  /**
+   * Content index skeleton — a page header over a list. Props and slots only: fetching, meta
+   * and the section guard belong to the *Page component that fills it.
+   */
+  const { title, description = undefined } = defineProps<{
+    title: string
+    description?: string
+  }>()
+</script>
+
+<template>
+  <LayoutSection>
+    <LayoutGridItem>
+      <UPageHeader :title v-bind="description ? { description } : {}" />
+      <UPageBody>
+        <slot />
+      </UPageBody>
+    </LayoutGridItem>
+  </LayoutSection>
+</template>

package/layers/content/app/components/NuxtContent/List.vue

@@ -3,16 +3,21 @@
     status,
     hasItems = true,
     emptyMessage = 'No items found',
+    errorMessage = "These items couldn't be loaded. Try again shortly.",
   } = defineProps<{
-    status: string
+    status: 'idle' | 'pending' | 'success' | 'error'
     hasItems?: boolean
     emptyMessage?: string
+    errorMessage?: string
   }>()
 </script>
 
 <template>
   <div>
     <USkeleton v-if="status === 'pending'" class="h-64 w-full" />
+    <slot v-else-if="status === 'error'" name="error">
+      <UAlert color="error" variant="subtle" icon="lucide:circle-alert" :title="errorMessage" />
+    </slot>
     <template v-else-if="hasItems">
       <slot />
     </template>

package/layers/content/app/components/Portfolio/ColorPalette.vue

@@ -17,7 +17,7 @@
 <template>
   <div v-if="colors.length" class="space-y-6">
     <h3 class="text-highlighted text-2xl font-semibold tracking-tight">Palette</h3>
-    <LinksGroup class="palette-grid gap-3">
+    <HoverDimGroup class="palette-grid gap-3">
       <div v-for="color in colors" :key="color.value">
         <div
           class="border-default/20 flex aspect-2/3 cursor-default flex-col justify-between rounded-lg border p-4 shadow-lg"
@@ -30,7 +30,7 @@
           <p class="font-mono text-xs uppercase opacity-50">{{ color.value }}</p>
         </div>
       </div>
-    </LinksGroup>
+    </HoverDimGroup>
   </div>
 </template>
 

package/layers/content/app/components/Portfolio/ItemPage.vue

@@ -1,5 +1,4 @@
 <script setup lang="ts">
-  import type { ContentLayerConfig } from '#layers/content/app/types/content'
   import type { PageCollections } from '@nuxt/content'
 
   const { slug, collection = 'portfolio' } = defineProps<{
@@ -7,11 +6,8 @@
     collection?: keyof PageCollections
   }>()
 
-  const appConfig = useAppConfig()
-  const contentLayer = appConfig.contentLayer as ContentLayerConfig | undefined
-  if (contentLayer?.sections?.portfolio === false) {
-    throw createError({ statusCode: 404, statusMessage: 'Not Found' })
-  }
+  useContentSection('portfolio')
+  await useContentItemSeo(collection, slug)
 </script>
 
 <template>

package/layers/content/app/components/Portfolio/List.vue

@@ -3,19 +3,30 @@
 
   import type { PortfolioQueryOptions } from '../../types/content'
 
-  const { options = {}, collection = 'portfolio' } = defineProps<{
+  const {
+    items: passed = undefined,
+    options = {},
+    collection = 'portfolio',
+  } = defineProps<{
+    items?: Collections[keyof Collections][]
     options?: PortfolioQueryOptions
     collection?: keyof Collections
   }>()
 
   const { featured, tags, limit } = options
-  const { data: items, status } = await useCollectionItems(collection, {
-    tags,
-    limit,
-    sortKey: 'year',
-    sortDirection: 'desc',
-    filter: featured !== undefined ? (item) => fieldFeatured(item) === featured : undefined,
-  })
+  // Fetch only when the parent didn't pass items (e.g. a related-items list it already has).
+  // ponytail: decided once at setup — toggling `items` after mount won't start or stop the fetch
+  const fetched = passed
+    ? undefined
+    : await useCollectionItems(collection, {
+        tags,
+        limit,
+        sortKey: 'year',
+        sortDirection: 'desc',
+        filter: featured !== undefined ? (item) => fieldFeatured(item) === featured : undefined,
+      })
+  const items = computed(() => passed ?? fetched?.data.value)
+  const status = computed(() => (passed ? 'success' : (fetched?.status.value ?? 'idle')))
 
   function fieldFeatured(item: unknown): boolean {
     return typeof item === 'object' && item !== null && 'featured' in item

package/layers/content/app/components/Portfolio/Page.vue

@@ -1,25 +1,15 @@
 <script setup lang="ts">
-  import type { ContentLayerConfig } from '#layers/content/app/types/content'
+  const { title = 'Portfolio', description = 'Featured projects and work' } = defineProps<{
+    title?: string
+    description?: string
+  }>()
 
-  const appConfig = useAppConfig()
-  const contentLayer = appConfig.contentLayer as ContentLayerConfig | undefined
-  if (contentLayer?.sections?.portfolio === false) {
-    throw createError({ statusCode: 404, statusMessage: 'Not Found' })
-  }
-
-  useSeoMeta({
-    title: 'Portfolio',
-    description: 'Featured projects and work',
-  })
+  useContentSection('portfolio')
+  useSeoMeta({ title: () => title, description: () => description })
 </script>
 
 <template>
-  <LayoutSection>
-    <LayoutGridItem>
-      <UPageHeader title="Portfolio" description="Featured projects and work" />
-      <UPageBody>
-        <PortfolioList />
-      </UPageBody>
-    </LayoutGridItem>
-  </LayoutSection>
+  <NuxtContentIndexTemplate :title :description>
+    <PortfolioList />
+  </NuxtContentIndexTemplate>
 </template>

package/layers/content/app/composables/useContentItemSeo.ts

@@ -0,0 +1,19 @@
+import type { Collections } from '@nuxt/content'
+
+/**
+ * Page meta for a content item. Called by the *Page components rather than the detail
+ * organisms, so an organism never sets page meta. Shares useCollectionItem's cache key with
+ * the organism that renders the item.
+ *
+ * Meta is registered before anything is awaited — Nuxt's instance is gone after an `await`
+ * inside a plain composable. Returns the async data so the caller can `await` it.
+ */
+export function useContentItemSeo(collection: keyof Collections, slug: string) {
+  const result = useCollectionItem(collection, slug)
+  useSeoMeta({
+    title: () => result.data.value?.title,
+    description: () => result.data.value?.description,
+    ogImage: () => (result.data.value as { image?: string } | null)?.image,
+  })
+  return result
+}

package/layers/content/app/composables/useContentSection.ts

@@ -0,0 +1,9 @@
+import type { ContentLayerConfig } from '../types/content'
+
+/** 404s the current route when `contentLayer.sections.<section>` is switched off in app.config. */
+export function useContentSection(section: keyof NonNullable<ContentLayerConfig['sections']>) {
+  const contentLayer = useAppConfig().contentLayer as ContentLayerConfig | undefined
+  if (contentLayer?.sections?.[section] === false) {
+    throw createError({ statusCode: 404, statusMessage: 'Not Found' })
+  }
+}

package/layers/content/app/utils/galleryImageMeta.test.ts

@@ -0,0 +1,30 @@
+import type { GalleryCollectionItem } from '@nuxt/content'
+import { describe, expect, it } from 'vite-plus/test'
+
+import { galleryImageMeta } from './galleryImageMeta'
+
+const gallery = (images: Array<Record<string, string>>) =>
+  ({ title: 'Autumn', images }) as unknown as GalleryCollectionItem
+
+describe('galleryImageMeta', () => {
+  it("prefers the image's own title and caption", () => {
+    const item = gallery([{ src: '/a.jpg', alt: 'Leaf', title: 'Red leaf', caption: 'Oct' }])
+    expect(galleryImageMeta(item, 0)).toEqual({
+      title: 'Red leaf',
+      description: 'Oct',
+      ogImage: '/a.jpg',
+    })
+  })
+
+  it('falls back to alt text, then the gallery title', () => {
+    expect(galleryImageMeta(gallery([{ src: '/a.jpg', alt: 'Leaf' }]), 0)).toMatchObject({
+      title: 'Leaf',
+      description: 'Autumn',
+    })
+  })
+
+  it('names a missing image by its position', () => {
+    expect(galleryImageMeta(gallery([]), 2).title).toBe('Image 3')
+    expect(galleryImageMeta(null, 0).title).toBe('Image 1')
+  })
+})

package/layers/content/app/utils/galleryImageMeta.ts

@@ -0,0 +1,11 @@
+import type { GalleryCollectionItem } from '@nuxt/content'
+
+/** Page meta for one image of a gallery: its own title/caption, falling back to the gallery's. */
+export function galleryImageMeta(item: GalleryCollectionItem | null | undefined, index: number) {
+  const image = item?.images?.[index]
+  return {
+    title: image?.title || image?.alt || `Image ${index + 1}`,
+    description: image?.caption || item?.title,
+    ogImage: image?.src,
+  }
+}

package/layers/content/nuxt.config.ts

@@ -13,7 +13,7 @@ export default defineNuxtConfig({
     name: 'content',
   },
 
-  extends: ['../core'],
+  extends: ['../core', '../structure/layout', '../design-system/visual'],
 
   alias: {
     '#layers/content': import.meta.dirname,

package/layers/core/app/app.config.ts

@@ -31,8 +31,8 @@ export default defineAppConfig({
 
     // Loading screen configuration (initial app load only)
     loading: {
-      // Master toggle - set to false to disable completely
-      enabled: true,
+      // Opt in: app.vue renders LoadingScreen for every app, so it stays off unless enabled
+      enabled: false,
       // Minimum time (ms, from navigation start) the count runs before reaching 100 (prevents flash)
       minDuration: 1500,
       // Longest wait (ms, after mount) for fonts and images before finishing anyway

package/layers/core/app/app.vue

@@ -1,9 +1,10 @@
 <template>
+  <!-- UApp already renders UOverlayProvider; a second one rendered every overlay twice. -->
   <UApp>
+    <LoadingScreen />
     <NuxtLoadingIndicator />
     <NuxtLayout>
       <NuxtPage />
     </NuxtLayout>
-    <UOverlayProvider />
   </UApp>
 </template>

package/layers/core/app/assets/css/core.css

@@ -33,6 +33,7 @@
 @import '#layers/core/app/assets/css/tokens/breakpoints.css';
 @import '#layers/core/app/assets/css/tokens/spacing-fluid.css';
 @import '#layers/core/app/assets/css/tokens/container.css';
+@import '#layers/core/app/assets/css/tokens/z-index.css';
 
 /* Relative path, not the '#layers/typography' alias — that alias only exists
    when the typography layer is in a consumer's `extends`. This file is a CSS
@@ -41,14 +42,7 @@
    only extend core, since it lives in the same single published package. */
 @import '../../../../design-system/typography/app/assets/css/typography.css';
 
-/* Same relative-path requirement as typography.css above. tokens.css defines
-   an `@theme static` block (radius/shadow/duration) — per the CSS
-   single-build-root rule, that only merges into Tailwind's theme if Tailwind's
-   own PostCSS pipeline actually processes the file via @import from this one
-   root. It previously was NOT imported here — only registered as a standalone
-   stylesheet via theming/nuxt.config.ts's `css:` array — so its @theme block
-   was silently inert: the browser just ignores the unrecognized at-rule, and
-   every rounded-, shadow-, duration- utility fell back to Tailwind's stock
-   defaults instead of this file's values. Confirmed via compiled dev output:
-   the custom --shadow-sm value never appeared; Tailwind's built-in default did. */
-@import '../../../../design-system/theming/app/assets/css/tokens.css';
+/* Shadow/duration tokens. Lived in theming until the 2026-10 atomic audit — moved here because
+   sub-atomic tokens belong to the foundation, and an @theme block only merges into Tailwind's
+   theme when it's in this one build root's @import chain anyway. */
+@import '#layers/core/app/assets/css/tokens/elevation-motion.css';

package/layers/core/app/assets/css/tokens/z-index.css

@@ -0,0 +1,16 @@
+/**
+ * UI stacking scale, for layers that can't reach layout's useZIndex() (it reads
+ * layoutLayer.ui.grid.layers from app.config). The shared steps mirror that config —
+ * tests/vitest/z-index-scale.test.ts fails if they drift. Use as `z-(--z-modal)`, never a raw z-9999.
+ */
+:root {
+  --z-header: 100;
+  --z-dropdown: 200;
+  --z-overlay: 300;
+  --z-modal: 400;
+  --z-toast: 500;
+
+  /* Above everything interactive — not in layout's scale, only these consumers need them */
+  --z-cursor: 600;
+  --z-debug: 700;
+}