kmcom-nuxt-layers 2.7.5 → 4.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

@@ -3,6 +3,20 @@
    and the resulting HMR layout shift on first load. */
 @custom-variant dark (&:where([data-theme-mode="dark"], [data-theme-mode="dark"] *));
 
+/* Explicit cascade-layer priority (low -> high). Tailwind's own
+   `@import 'tailwindcss'` and `@nuxt/ui` already register into this same
+   `theme`/`base`/`components`/`utilities` order internally — this statement
+   pins that order explicitly rather than relying on Tailwind/Nuxt UI's own
+   internal default, so a future re-ordering of the @import statements below,
+   or a change to how Tailwind/Nuxt UI register their layers, can't silently
+   change which of these four layers wins over another.
+   This only fixes ordering BETWEEN the four named layers — it does NOT
+   control precedence WITHIN a layer. base.css registers into `base` and
+   layout.css into `components`, the same layers Nuxt UI's own CSS uses;
+   between project rules and Nuxt UI rules inside the same layer, plain
+   source/import order still decides the winner. */
+@layer theme, base, components, utilities;
+
 @import 'tailwindcss';
 @import '@nuxt/ui';
 
@@ -16,10 +30,25 @@
 
 @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 '../../../../typography/app/assets/css/typography.css';
+@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';

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

@@ -1,9 +1,4 @@
 @layer components {
-  table {
-    border-color: inherit;
-    border-collapse: collapse;
-  }
-
   th {
     vertical-align: top;
     padding: 0;
@@ -20,8 +15,6 @@
     margin: 1rem 0;
     border: 0;
     border-top: 1px solid #ccc;
-    height: 0;
-    color: inherit;
   }
 
   img,

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>