kmcom-nuxt-layers 6.2.0 → 6.3.0

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/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;
+}

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

@@ -31,7 +31,7 @@
         <div class="space-y-8">
           <div class="text-center">
             <h1 class="mb-2 text-4xl font-bold">Core Layer Diagnostics</h1>
-            <p class="text-gray-500 dark:text-gray-400">Feature detection and system information</p>
+            <p class="text-muted">Feature detection and system information</p>
           </div>
 
           <UCard>
@@ -40,33 +40,33 @@
             </template>
             <div class="diag-grid-9 gap-3">
               <div class="flex items-center gap-2">
-                <span v-if="grid" class="text-green-500">✓</span>
-                <span v-else class="text-red-500">✗</span>
+                <span v-if="grid" class="text-success">✓</span>
+                <span v-else class="text-error">✗</span>
                 <span>CSS Grid</span>
               </div>
               <div class="flex items-center gap-2">
-                <span v-if="subgrid" class="text-green-500">✓</span>
-                <span v-else class="text-red-500">✗</span>
+                <span v-if="subgrid" class="text-success">✓</span>
+                <span v-else class="text-error">✗</span>
                 <span>Subgrid</span>
               </div>
               <div class="flex items-center gap-2">
-                <span v-if="containerQueries" class="text-green-500">✓</span>
-                <span v-else class="text-red-500">✗</span>
+                <span v-if="containerQueries" class="text-success">✓</span>
+                <span v-else class="text-error">✗</span>
                 <span>Container Queries</span>
               </div>
               <div class="flex items-center gap-2">
-                <span v-if="has" class="text-green-500">✓</span>
-                <span v-else class="text-red-500">✗</span>
+                <span v-if="has" class="text-success">✓</span>
+                <span v-else class="text-error">✗</span>
                 <span>:has() Selector</span>
               </div>
               <div class="flex items-center gap-2">
-                <span v-if="aspectRatio" class="text-green-500">✓</span>
-                <span v-else class="text-red-500">✗</span>
+                <span v-if="aspectRatio" class="text-success">✓</span>
+                <span v-else class="text-error">✗</span>
                 <span>Aspect Ratio</span>
               </div>
               <div class="flex items-center gap-2">
-                <span v-if="backdropFilter" class="text-green-500">✓</span>
-                <span v-else class="text-red-500">✗</span>
+                <span v-if="backdropFilter" class="text-success">✓</span>
+                <span v-else class="text-error">✗</span>
                 <span>Backdrop Filter</span>
               </div>
             </div>
@@ -78,13 +78,13 @@
             </template>
             <div class="diag-grid-8 gap-3">
               <div class="flex items-center gap-2">
-                <span v-if="webp" class="text-green-500">✓</span>
-                <span v-else class="text-red-500">✗</span>
+                <span v-if="webp" class="text-success">✓</span>
+                <span v-else class="text-error">✗</span>
                 <span>WebP</span>
               </div>
               <div class="flex items-center gap-2">
-                <span v-if="avif" class="text-green-500">✓</span>
-                <span v-else class="text-red-500">✗</span>
+                <span v-if="avif" class="text-success">✓</span>
+                <span v-else class="text-error">✗</span>
                 <span>AVIF</span>
               </div>
             </div>
@@ -96,23 +96,23 @@
             </template>
             <div class="diag-grid-9 gap-3">
               <div class="flex items-center gap-2">
-                <span v-if="intersectionObserver" class="text-green-500">✓</span>
-                <span v-else class="text-red-500">✗</span>
+                <span v-if="intersectionObserver" class="text-success">✓</span>
+                <span v-else class="text-error">✗</span>
                 <span>IntersectionObserver</span>
               </div>
               <div class="flex items-center gap-2">
-                <span v-if="resizeObserver" class="text-green-500">✓</span>
-                <span v-else class="text-red-500">✗</span>
+                <span v-if="resizeObserver" class="text-success">✓</span>
+                <span v-else class="text-error">✗</span>
                 <span>ResizeObserver</span>
               </div>
               <div class="flex items-center gap-2">
-                <span v-if="serviceWorker" class="text-green-500">✓</span>
-                <span v-else class="text-red-500">✗</span>
+                <span v-if="serviceWorker" class="text-success">✓</span>
+                <span v-else class="text-error">✗</span>
                 <span>Service Worker</span>
               </div>
               <div class="flex items-center gap-2">
-                <span v-if="webGL" class="text-green-500">✓</span>
-                <span v-else class="text-red-500">✗</span>
+                <span v-if="webGL" class="text-success">✓</span>
+                <span v-else class="text-error">✗</span>
                 <span>WebGL</span>
               </div>
             </div>
@@ -139,8 +139,8 @@
             <div class="space-y-2">
               <div class="flex items-center gap-2">
                 <span class="w-24 font-medium">Status:</span>
-                <span v-if="isOnline" class="text-green-500">Online</span>
-                <span v-else class="text-red-500">Offline</span>
+                <span v-if="isOnline" class="text-success">Online</span>
+                <span v-else class="text-error">Offline</span>
               </div>
               <div class="flex items-center gap-2">
                 <span class="w-24 font-medium">Type:</span>
@@ -150,10 +150,10 @@
                 <span class="w-24 font-medium">Quality:</span>
                 <span
                   :class="{
-                    'text-green-500': connectionQuality === 'excellent',
-                    'text-yellow-500': connectionQuality === 'good',
-                    'text-red-500': connectionQuality === 'poor',
-                    'text-gray-500': connectionQuality === 'offline',
+                    'text-success': connectionQuality === 'excellent',
+                    'text-warning': connectionQuality === 'good',
+                    'text-error': connectionQuality === 'poor',
+                    'text-muted': connectionQuality === 'offline',
                   }"
                 >
                   {{ connectionQuality }}
@@ -161,13 +161,13 @@
               </div>
               <div class="flex items-center gap-2">
                 <span class="w-24 font-medium">Speed:</span>
-                <span v-if="isFast" class="text-green-500">Fast</span>
-                <span v-else-if="isSlow" class="text-red-500">Slow</span>
+                <span v-if="isFast" class="text-success">Fast</span>
+                <span v-else-if="isSlow" class="text-error">Slow</span>
                 <span v-else>Normal</span>
               </div>
               <div v-if="saveData" class="flex items-center gap-2">
                 <span class="w-24 font-medium">Data Saver:</span>
-                <span class="text-yellow-500">Enabled</span>
+                <span class="text-warning">Enabled</span>
               </div>
             </div>
           </UCard>
@@ -188,8 +188,8 @@
               </div>
               <div class="flex items-center gap-2">
                 <span class="w-24 font-medium">Hydrated:</span>
-                <span v-if="isHydrated" class="text-green-500">Yes</span>
-                <span v-else class="text-yellow-500">No</span>
+                <span v-if="isHydrated" class="text-success">Yes</span>
+                <span v-else class="text-warning">No</span>
               </div>
             </div>
           </UCard>
@@ -201,17 +201,17 @@
             <div class="space-y-2">
               <div class="flex items-center gap-2">
                 <span class="w-24 font-medium">Installed:</span>
-                <span v-if="isInstalled" class="text-green-500">Yes</span>
-                <span v-else class="text-gray-500">No</span>
+                <span v-if="isInstalled" class="text-success">Yes</span>
+                <span v-else class="text-muted">No</span>
               </div>
               <div class="flex items-center gap-2">
                 <span class="w-24 font-medium">Installable:</span>
-                <span v-if="canInstall" class="text-green-500">Yes</span>
-                <span v-else class="text-gray-500">No</span>
+                <span v-if="canInstall" class="text-success">Yes</span>
+                <span v-else class="text-muted">No</span>
               </div>
               <div v-if="needRefresh" class="flex items-center gap-2">
                 <span class="w-24 font-medium">Update:</span>
-                <span class="text-yellow-500">Available</span>
+                <span class="text-warning">Available</span>
               </div>
             </div>
           </UCard>

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

@@ -92,6 +92,7 @@
       'Helvetica Neue',
       Arial,
       sans-serif;
+
     /* `backwards`, not `both` - a held end state would block the exit transition below */
     animation: loading-enter 0.9s cubic-bezier(0.16, 1, 0.3, 1) 0.1s backwards;
   }
@@ -110,6 +111,7 @@
     font-stretch: ultra-expanded;
     font-size: clamp(3rem, 35cqw + 1rem, 18rem);
     line-height: 0.8;
+
     /* Equal-width digits - the counter doesn't jitter as it ticks */
     font-variant-numeric: tabular-nums;
   }