@koehler8/cms 1.0.0-beta.28 → 1.0.0-beta.29

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@koehler8/cms",
-  "version": "1.0.0-beta.28",
+  "version": "1.0.0-beta.29",
   "description": "Vertex CMS — lightweight, config-driven Vue 3 framework with theming, extensions, and SSG support",
   "license": "MIT",
   "type": "module",

package/src/components/Hero.vue

@@ -273,10 +273,19 @@ function getHeaderOffset() {
 .promo-surface {
   position: relative;
   min-height: var(--promo-surface-min-height, calc(100vh + 75px));
-  background: var(
+  background-color: var(
     --promo-surface-bg,
     var(--hero-surface-bg, var(--theme-body-background, #060212))
   );
+  /* Two background-image declarations form a CSS-cascade fallback chain.
+     The first sets a basic url(); the second, if the browser parses
+     image-set() (and the type() argument), overrides with format
+     negotiation. Browsers that can't parse image-set fall back to the
+     url() above. Custom properties are populated by usePromoBackgroundStyles
+     via Vue's :style object binding — see that composable for why this
+     pattern is needed instead of a single background-image string. */
+  background-image: var(--promo-bg-fallback);
+  background-image: var(--promo-bg-set, var(--promo-bg-fallback));
   background-repeat: no-repeat;
   background-size: cover;
   background-position: center;

package/src/composables/usePromoBackgroundStyles.js

@@ -23,14 +23,34 @@ function selectLargestEntry(srcset = '') {
 }
 
 /**
- * Build a CSS background-image declaration that respects the neon backdrop toggle
- * and reuses the responsive image metadata returned by `useResponsiveImage`.
+ * Build a hero-background style binding that pairs a `url()` fallback with an
+ * `image-set()` upgrade. Returns an OBJECT with two CSS custom properties.
+ *
+ * Why an object with custom properties instead of a single `background-image`
+ * string: Vue 3's `:style` parses a string into a normalized object keyed by
+ * property name. A string with two `background-image` declarations
+ * (`background-image: url(...); background-image: image-set(...)`) collapses
+ * to a single entry — only the last value survives. This loses the
+ * progressive-enhancement chain that's the whole point of pairing a `url()`
+ * fallback with an `image-set()` upgrade. By emitting two custom properties,
+ * Vue keeps both, and the consuming CSS rule chains them as two real
+ * declarations of `background-image` so browsers walk the cascade naturally.
+ *
+ * Consumed by Hero.vue's `.promo-surface` rule, which declares:
+ *
+ *   background-image: var(--promo-bg-fallback);
+ *   background-image: var(--promo-bg-set, var(--promo-bg-fallback));
+ *
+ * Browsers that can parse `image-set()` (and its `type()` argument) use the
+ * second declaration; browsers that can't fall through to the first.
+ *
  * @param {object} options
  * @param {{
  *   sources: import('vue').MaybeRefOrGetter<Array<{ type: string, srcset: string }>>,
  *   fallbackSrc: import('vue').MaybeRefOrGetter<string>,
  *   fallbackFormat: import('vue').MaybeRefOrGetter<string>
  * }} options.imageSet
+ * @returns {import('vue').ComputedRef<Record<string, string> | null>}
  */
 export function usePromoBackgroundStyles({ imageSet }) {
   return computed(() => {
@@ -38,30 +58,26 @@ export function usePromoBackgroundStyles({ imageSet }) {
     const fallbackFormat = (unref(imageSet?.fallbackFormat) || 'jpg').toLowerCase();
     const sources = unref(imageSet?.sources) || [];
 
-    const formatEntries = [];
+    if (!fallbackSrc) return null;
 
+    const formatEntries = [];
     sources.forEach((source) => {
       const largest = selectLargestEntry(source?.srcset);
       if (largest) {
         formatEntries.push(`url("${largest}") type("${source?.type}") 1x`);
       }
     });
-
     if (fallbackSrc) {
       const fallbackMime = fallbackFormat === 'jpg' ? 'jpeg' : fallbackFormat;
       formatEntries.push(`url("${fallbackSrc}") type("image/${fallbackMime}") 1x`);
     }
 
-    const cssImageSet = formatEntries.length ? `image-set(${formatEntries.join(', ')})` : '';
-    let style = '';
-
-    if (fallbackSrc) {
-      style += `background-image: url("${fallbackSrc}");`;
-    }
-    if (cssImageSet) {
-      style += `background-image: ${cssImageSet};`;
+    const result = {
+      '--promo-bg-fallback': `url("${fallbackSrc}")`,
+    };
+    if (formatEntries.length) {
+      result['--promo-bg-set'] = `image-set(${formatEntries.join(', ')})`;
     }
-
-    return style;
+    return result;
   });
 }