kmcom-nuxt-layers 2.7.4 → 3.0.0

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

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

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

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

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

@@ -8,8 +8,20 @@
     collection?: keyof Collections
   }>()
 
-  const { useItems } = createPortfolioComposables(collection)
-  const { data: items, status } = await useItems(options)
+  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,
+  })
+
+  function fieldFeatured(item: unknown): boolean {
+    return typeof item === 'object' && item !== null && 'featured' in item
+      ? Boolean((item as { featured?: boolean }).featured)
+      : false
+  }
 
   // Items may come from any collection — normalize the portfolio-style
   // metadata so the template works on a single shape

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

@@ -1,5 +1,8 @@
 <script setup lang="ts">
-  const { contentLayer } = useAppConfig()
+  import type { ContentLayerConfig } from '#layers/content/app/types/content'
+
+  const appConfig = useAppConfig()
+  const contentLayer = appConfig.contentLayer as ContentLayerConfig | undefined
   if (contentLayer?.sections?.portfolio === false) {
     throw createError({ statusCode: 404, statusMessage: 'Not Found' })
   }

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

@@ -3,24 +3,11 @@ import type { BlogQueryOptions } from '../types/content'
 export function useBlogPosts(options: BlogQueryOptions = {}) {
   const { excludeDrafts = true, tags, limit } = options
 
-  const key = `blog-posts:${excludeDrafts}:${(tags ?? []).slice().sort().join(',')}:${limit ?? ''}`
-  return useContentData(key, async () => {
-    let posts = (await queryCollection('blog').all()).sort((a, b) =>
-      (b.date ?? '').localeCompare(a.date ?? '')
-    )
-
-    if (excludeDrafts) {
-      posts = posts.filter((post) => !post.draft)
-    }
-
-    if (tags?.length) {
-      posts = posts.filter((post) => post.tags?.some((tag: string) => tags.includes(tag)))
-    }
-
-    if (limit) {
-      posts = posts.slice(0, limit)
-    }
-
-    return posts
+  return useCollectionItems('blog', {
+    tags,
+    limit,
+    sortKey: 'date',
+    sortDirection: 'desc',
+    filter: excludeDrafts ? (post) => !('draft' in post && post.draft) : undefined,
   })
 }

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

@@ -0,0 +1,63 @@
+import type { Collections } from '@nuxt/content'
+
+type AnyCollectionItem = Collections[keyof Collections]
+
+export type CollectionItemsOptions = {
+  tags?: string[] | undefined
+  limit?: number | undefined
+  /** Frontmatter field to sort by (e.g. 'date', 'year'). Duck-typed — missing on an item sorts last. */
+  sortKey?: string | undefined
+  sortDirection?: 'asc' | 'desc' | undefined
+  /** Extra domain-specific predicate (e.g. exclude drafts, require featured). */
+  filter?: ((item: AnyCollectionItem) => boolean) | undefined
+}
+
+function fieldValue(item: AnyCollectionItem, key: string): unknown {
+  return key in item ? (item as unknown as Record<string, unknown>)[key] : undefined
+}
+
+function itemTags(item: AnyCollectionItem): string[] {
+  return 'tags' in item ? ((item.tags as string[] | undefined) ?? []) : []
+}
+
+/**
+ * Generic collection list query — sort, filter, limit — shared by
+ * `useBlogPosts`, `useGalleryItems`, and `Portfolio/List.vue`'s arbitrary
+ * `collection` prop. Single implementation, thin per-domain wrappers.
+ */
+export function useCollectionItems<K extends keyof Collections>(
+  collectionName: K,
+  options: CollectionItemsOptions = {}
+) {
+  const { tags, limit, sortKey, sortDirection = 'desc', filter } = options
+  const cacheKey = `${collectionName}-items:${sortKey ?? ''}:${(tags ?? []).slice().sort().join(',')}:${limit ?? ''}`
+
+  // fallow-ignore-next-line complexity
+  return useContentData(cacheKey, async () => {
+    let items = (await queryCollection(collectionName).all()) as AnyCollectionItem[]
+
+    if (sortKey) {
+      // fallow-ignore-next-line complexity
+      items = items.slice().sort((a, b) => {
+        const av = fieldValue(a, sortKey)
+        const bv = fieldValue(b, sortKey)
+        if (av === bv) return 0
+        const cmp = (av ?? '') > (bv ?? '') ? 1 : -1
+        return sortDirection === 'desc' ? -cmp : cmp
+      })
+    }
+
+    if (filter) items = items.filter(filter)
+
+    if (tags?.length) {
+      items = items.filter((item) => itemTags(item).some((tag) => tags.includes(tag)))
+    }
+
+    if (limit) items = items.slice(0, limit)
+
+    // Cast back to the specific collection's item type — the sort/filter/tag
+    // machinery above is generic across all collections, but callers always
+    // know their own `K` and expect e.g. BlogCollectionItem[], not the union.
+    return items as unknown as Array<Collections[K]>
+  })
+}

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

@@ -2,21 +2,6 @@ import type { GalleryQueryOptions } from '../types/content'
 
 export function useGalleryItems(options: GalleryQueryOptions = {}) {
   const { tags, limit } = options
-  const key = `gallery-items:${(tags ?? []).slice().sort().join(',')}:${limit ?? ''}`
 
-  return useContentData(key, async () => {
-    let items = (await queryCollection('gallery').all()).sort((a, b) =>
-      (b.date ?? '').localeCompare(a.date ?? '')
-    )
-
-    if (tags?.length) {
-      items = items.filter((item) => Boolean(item.tags?.some((tag: string) => tags.includes(tag))))
-    }
-
-    if (limit !== undefined) {
-      items = items.slice(0, limit)
-    }
-
-    return items
-  })
+  return useCollectionItems('gallery', { tags, limit, sortKey: 'date', sortDirection: 'desc' })
 }

package/layers/content/app/types/content.ts

@@ -4,6 +4,15 @@ export type ContentAuthor = {
   avatar?: string
 } & Author
 
+export type ContentLayerConfig = {
+  name?: string
+  sections?: {
+    blog?: boolean
+    portfolio?: boolean
+    gallery?: boolean
+  }
+}
+
 export type GalleryImage = {
   src: string
   alt: string

package/layers/content/package.json

@@ -20,5 +20,8 @@
     "better-sqlite3": "catalog:",
     "zod": "catalog:conflicts_zod_h4_3_6",
     "zod-to-json-schema": "catalog:conflicts_zod-to-json-schema_h3_25_1"
+  },
+  "optionalDependencies": {
+    "nuxt-studio": "^1.7.0"
   }
 }

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

@@ -1,4 +1,7 @@
-export default {
+import type { NotFoundConfig } from './types/notFound'
+import type { SiteConfig } from './types/site'
+
+export default defineAppConfig({
   coreLayer: {
     // 404 Page defaults (all optional)
     notFound: {
@@ -53,21 +56,35 @@ export default {
       // External error service token/key
       externalToken: '',
     },
-
-    // Horizontal scroll guard configuration
-    scrollGuard: {
-      // Master toggle - set to false to disable completely
-      enabled: false,
-      // CSS selectors for elements allowed to overflow intentionally
-      excludeSelectors: ['.carousel', '.overflow-intent'],
-      // Enable automatic clamping of overflowing elements
-      strict: true,
-      // Duration (ms) for element width clamp animations
-      transitionDuration: 200,
-      // Debounce delay (ms) for resize re-scans
-      resizeDebounce: 150,
-      // Temporarily highlight overflowing elements with a red outline
-      debug: false,
-    },
   },
+})
+
+declare module '@nuxt/schema' {
+  interface AppConfigInput {
+    /** Shared site metadata — consumed by feeds, SEO, and any layer needing canonical site info. */
+    site?: SiteConfig
+    coreLayer?: {
+      /** Project name */
+      name?: string
+
+      /** 404 Not Found page configuration */
+      notFound?: NotFoundConfig
+
+      loading?: {
+        enabled?: boolean
+        minDuration?: number
+        maxDuration?: number
+        background?: string
+        textColor?: string
+        zIndex?: number
+      }
+
+      errors?: {
+        logToConsole?: boolean
+        logToExternal?: boolean
+        externalUrl?: string
+        externalToken?: string
+      }
+    }
+  }
 }

package/layers/core/app/app.vue

@@ -1,5 +1,6 @@
 <template>
   <UApp>
+    <NuxtLoadingIndicator />
     <NuxtLayout>
       <NuxtPage />
     </NuxtLayout>

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

@@ -16,3 +16,13 @@
 
 @import '#layers/core/app/assets/css/layout.css';
 @import '#layers/core/app/assets/css/base.css';
+@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';
+
+/* 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
+   import (needed so Tailwind treats it as part of this one build root, see
+   typography.css's header comment), and must resolve even for consumers that
+   only extend core, since it lives in the same single published package. */
+@import '../../../../design-system/typography/app/assets/css/typography.css';

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

@@ -0,0 +1,13 @@
+/**
+ * Single source of truth for breakpoint values — matches Tailwind's defaults
+ * and layers/visual's BREAKPOINT_VALUES. layers/layout's grid density
+ * breakpoints (48rem/80rem, its own tablet/desktop thresholds) are a
+ * separate, structural concept and are not repointed here — see
+ * nuxt-declarative-layout-system-spec.md §14/§20.
+ */
+:root {
+  --breakpoint-sm: 40rem; /* 640px */
+  --breakpoint-md: 48rem; /* 768px */
+  --breakpoint-lg: 64rem; /* 1024px */
+  --breakpoint-xl: 80rem; /* 1280px */
+}

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

@@ -0,0 +1,36 @@
+/**
+ * Container size utilities — used by the shared <AppContainer> component
+ * (layers/core/app/components/AppContainer.vue).
+ */
+.container-content {
+  box-sizing: border-box;
+  container-type: inline-size;
+  margin-inline: auto;
+  width: 100%;
+  max-width: 65ch;
+}
+
+.container-wide {
+  box-sizing: border-box;
+  container-type: inline-size;
+  margin-inline: auto;
+  width: 100%;
+  max-width: clamp(var(--breakpoint-lg), 85vw, 90rem);
+}
+
+.container-fluid {
+  box-sizing: border-box;
+  container-type: inline-size;
+  width: 100%;
+  max-width: 100%;
+}
+
+.container-full {
+  box-sizing: border-box;
+  container-type: inline-size;
+  margin-inline: calc(var(--grid-padding, clamp(1rem, 2.5vw, 2rem)) * -1);
+
+  /* Escape parent padding to reach the viewport edge */
+  width: 100vw;
+  max-width: 100vw;
+}

package/layers/core/app/assets/css/tokens/spacing-fluid.css

@@ -0,0 +1,25 @@
+/**
+ * Fluid spacing scale — clamp() + cqi container-relative variant, same
+ * pattern as layers/typography's fluid type scale (see typography.css).
+ * Backs the `Spacing` token (layers/core/app/types/tokens.ts) consumed by
+ * useLayoutAttrs(). --fluid-space-none is 0, not clamp() — no scaling needed.
+ */
+:root {
+  --fluid-space-none: 0px;
+  --fluid-space-xs: clamp(0.5rem, 0.46rem + 0.2vi, 0.625rem);
+  --fluid-space-sm: clamp(0.75rem, 0.7rem + 0.25vi, 1rem);
+  --fluid-space-md: clamp(1rem, 0.9rem + 0.5vi, 1.5rem);
+  --fluid-space-lg: clamp(1.5rem, 1.3rem + 1vi, 2.5rem);
+  --fluid-space-xl: clamp(2rem, 1.7rem + 1.5vi, 3.5rem);
+  --fluid-space-2xl: clamp(3rem, 2.4rem + 3vi, 5rem);
+  --fluid-space-3xl: clamp(4rem, 3rem + 5vi, 7rem);
+
+  /* Container-relative counterparts (cqi) — opt-in inside a `container-type` ancestor. */
+  --fluid-space-xs-cq: clamp(0.5rem, 0.46rem + 2cqi, 0.625rem);
+  --fluid-space-sm-cq: clamp(0.75rem, 0.65rem + 2.5cqi, 1rem);
+  --fluid-space-md-cq: clamp(1rem, 0.8rem + 5cqi, 1.5rem);
+  --fluid-space-lg-cq: clamp(1.5rem, 1.1rem + 10cqi, 2.5rem);
+  --fluid-space-xl-cq: clamp(2rem, 1.4rem + 15cqi, 3.5rem);
+  --fluid-space-2xl-cq: clamp(3rem, 2rem + 25cqi, 5rem);
+  --fluid-space-3xl-cq: clamp(4rem, 2.5rem + 37.5cqi, 7rem);
+}

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

@@ -0,0 +1,32 @@
+<script setup lang="ts">
+  /**
+   * AppContainer — constrained content width wrapper.
+   *
+   * | size    | max-width | use case                          |
+   * |---------|-----------|------------------------------------|
+   * | content | 65ch      | Long-form prose, articles          |
+   * | wide    | clamp(64rem, 85vw, 90rem) | Cards, media-rich sections |
+   * | fluid   | 100%      | Full bleed within grid padding      |
+   * | full    | 100vw     | True full-bleed (escapes padding)   |
+   */
+
+  import type { ContainerSize } from '#layers/core/types/tokens'
+
+  const { size = 'wide', tag = 'div' } = defineProps<{
+    size?: ContainerSize
+    tag?: string
+  }>()
+
+  const sizeClass: Record<ContainerSize, string> = {
+    content: 'container-content',
+    wide: 'container-wide',
+    fluid: 'container-fluid',
+    full: 'container-full',
+  }
+</script>
+
+<template>
+  <component :is="tag" :class="sizeClass[size]">
+    <slot />
+  </component>
+</template>

package/layers/core/app/components/Element.test.ts

@@ -0,0 +1,90 @@
+import { defineComponent, h } from 'vue'
+import { mount } from '@vue/test-utils'
+import { describe, expect, it } from 'vitest'
+
+import Element from './Element.vue'
+
+// Stands in for a real component (e.g. UBadge) whose own `color` prop is
+// semantic, not a raw CSS value — the same name Element uses for its own
+// raw-CSS text colour passthrough.
+const ColorPropStub = defineComponent({
+  props: { color: { type: String, default: undefined } },
+  setup(props) {
+    return () => h('div', { 'data-received-color': props.color }, 'stub')
+  },
+})
+
+describe('Element', () => {
+  it('renders as a div by default', () => {
+    const wrapper = mount(Element)
+    expect(wrapper.element.tagName).toBe('DIV')
+  })
+
+  it('renders as the tag passed via the as prop', () => {
+    const wrapper = mount(Element, { props: { as: 'section' } })
+    expect(wrapper.element.tagName).toBe('SECTION')
+  })
+
+  it('renders slot content', () => {
+    const wrapper = mount(Element, { slots: { default: 'hello' } })
+    expect(wrapper.text()).toBe('hello')
+  })
+
+  it('merges layout, sizing, and surface styles into one style attribute', () => {
+    const wrapper = mount(Element, {
+      props: {
+        flex: true,
+        w: '80px',
+        bg: 'var(--ui-bg-elevated)',
+      },
+    })
+    const style = wrapper.attributes('style') ?? ''
+    expect(style).toContain('display: flex')
+    expect(style).toContain('width: 80px')
+    expect(style).toContain('background: var(--ui-bg-elevated)')
+  })
+
+  it('applies container-axis grid styles', () => {
+    const wrapper = mount(Element, {
+      props: { grid: true, cols: 12 },
+    })
+    const style = wrapper.attributes('style') ?? ''
+    expect(style).toContain('display: grid')
+    expect(style).toContain('grid-template-columns: repeat(12, 1fr)')
+    expect(style).not.toContain('grid-column')
+    expect(style).not.toContain('grid-row')
+  })
+
+  it('gives hidden priority over grid so display: none is not overwritten', () => {
+    const wrapper = mount(Element, {
+      props: { grid: true, hidden: true },
+    })
+    const style = wrapper.attributes('style') ?? ''
+    expect(style).toContain('display: none')
+    expect(style).not.toContain('display: grid')
+  })
+
+  it('reaches margin and padding through useLayoutAttrs', () => {
+    const wrapper = mount(Element, {
+      props: { m: 'md', p: 'lg' },
+    })
+    const style = wrapper.attributes('style') ?? ''
+    expect(style).toContain('margin: var(--fluid-space-md)')
+    expect(style).toContain('padding: var(--fluid-space-lg)')
+  })
+
+  it('passes componentProps to the resolved component, past a colliding prop name', () => {
+    const wrapper = mount(Element, {
+      props: {
+        as: ColorPropStub,
+        color: 'crimson',
+        componentProps: { color: 'error' },
+      },
+    })
+    // Element's own `color` still resolves to raw CSS text colour...
+    expect(wrapper.attributes('style') ?? '').toContain('color: crimson')
+    // ...while the stub's semantic `color` prop comes from componentProps, not
+    // from Element's own `color`.
+    expect(wrapper.attributes('data-received-color')).toBe('error')
+  })
+})

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

@@ -0,0 +1,78 @@
+<script setup lang="ts">
+  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 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,
+  }))
+</script>
+
+<template>
+  <component :is="as" v-bind="componentProps" :style>
+    <slot />
+  </component>
+</template>

package/layers/core/app/components/ElementTw.test.ts

@@ -0,0 +1,64 @@
+import { defineComponent, h } from 'vue'
+import { mount } from '@vue/test-utils'
+import { describe, expect, it } from 'vitest'
+
+import ElementTw from './ElementTw.vue'
+
+const ColorPropStub = defineComponent({
+  props: { color: { type: String, default: undefined } },
+  setup(props) {
+    return () => h('div', { 'data-received-color': props.color }, 'stub')
+  },
+})
+
+describe('ElementTw', () => {
+  it('renders as a div by default', () => {
+    const wrapper = mount(ElementTw)
+    expect(wrapper.element.tagName).toBe('DIV')
+  })
+
+  it('renders as the tag passed via the as prop', () => {
+    const wrapper = mount(ElementTw, { props: { as: 'section' } })
+    expect(wrapper.element.tagName).toBe('SECTION')
+  })
+
+  it('renders slot content', () => {
+    const wrapper = mount(ElementTw, { slots: { default: 'hello' } })
+    expect(wrapper.text()).toBe('hello')
+  })
+
+  it('emits merged layout, sizing, and surface styles as tailwind arbitrary-property classes', () => {
+    const wrapper = mount(ElementTw, {
+      props: {
+        flex: true,
+        w: '80px',
+        bg: 'var(--ui-bg-elevated)',
+      },
+    })
+    const classes = wrapper.classes()
+    expect(classes).toContain('[display:flex]')
+    expect(classes).toContain('[width:80px]')
+    expect(classes).toContain('[background:var(--ui-bg-elevated)]')
+  })
+
+  it('gives hidden priority over grid so display:none is not overwritten', () => {
+    const wrapper = mount(ElementTw, {
+      props: { grid: true, hidden: true },
+    })
+    const classes = wrapper.classes()
+    expect(classes).toContain('[display:none]')
+    expect(classes).not.toContain('[display:grid]')
+  })
+
+  it('passes componentProps to the resolved component, past a colliding prop name', () => {
+    const wrapper = mount(ElementTw, {
+      props: {
+        as: ColorPropStub,
+        color: 'crimson',
+        componentProps: { color: 'error' },
+      },
+    })
+    expect(wrapper.classes()).toContain('[color:crimson]')
+    expect(wrapper.attributes('data-received-color')).toBe('error')
+  })
+})