@duffcloudservices/cms 0.3.15 → 0.3.17

package/README.md

@@ -61,11 +61,15 @@ export default defineConfig({
 
 ```bash
 # .env
-VITE_SITE_SLUG=your-site-slug
-
-# Optional: for runtime overrides (premium tier)
+# For runtime overrides (premium tier): the API base URL only.
 VITE_API_BASE_URL=https://portal.duffcloudservices.com
 VITE_TEXT_OVERRIDE_MODE=commit  # 'commit' (default) or 'runtime'
+
+# Deprecated: the site is now resolved server-side from the request Host
+# (or the dedicated Container App's DCS_SITE_SLUG). VITE_SITE_SLUG is no
+# longer placed in request URLs; it is optional and used only as a local
+# cache-key hint. Safe to omit.
+# VITE_SITE_SLUG=your-site-slug
 ```
 
 ### 3. Use Composables
@@ -310,6 +314,41 @@ For DCS-managed sites, `src/editor/editorBridge.ts` is the shared
 discovery/runtime layer that turns site DOM markers into portal editing
 entry points.
 
+### Managed background images
+
+For customer-site hero, CTA, footer, card, staff, and gallery images that need editor image replacement, prefer the exported `ManagedImage` component over CSS-only `background-image` or hardcoded image arrays.
+
+```vue
+<script setup lang="ts">
+import ManagedImage from '@duffcloudservices/cms/managed-image'
+</script>
+
+<template>
+  <ManagedImage
+    page-slug="home"
+    image-key="hero.image.url"
+    alt-key="hero.image.alt"
+    fallback-src="/images/hero.jpg"
+    fallback-alt="Clinic hero"
+    context="hero"
+    class="h-full w-full object-cover"
+  />
+</template>
+```
+
+Add the URL and alt keys to `.dcs/content.yaml` using CDN URLs for committed content:
+
+```yaml
+pages:
+  home:
+    hero.image.url: https://files.duffcloudservices.com/content/site-slug/assets/example.jpg
+    hero.image.alt: Clinic hero
+```
+
+`ManagedImage` resolves build-time/runtime content with `useTextContent`, renders a real `<picture>/<img>` target, applies responsive CDN variants through `useResponsiveImage`, and emits `data-dcs-image-key`, `data-dcs-image-url`, and `data-dcs-image-alt` on the actual `<img>`. This lets the visual editor open image management for the asset and lets snapshot capture wait on an actual image before `full-page.png`.
+
+For repeated galleries or cards, use indexed keys such as `gallery.item-0.image.url` and `gallery.item-0.image.alt`, then pass those keys through the rendered item. Do not make editable images CSS-only backgrounds; if a design needs background behavior, render a real managed image layer behind the content.
+
 Current first-party surfaces:
 
 - **Managed forms** — discovers `[data-form-key]`, reports

package/dist/editor/editorBridge.js

@@ -660,6 +660,9 @@ function createImageEditIcon(label) {
   });
   return icon;
 }
+function getManagedImageKey(img) {
+  return img.dataset.dcsImageKey || img.closest("[data-dcs-image-key]")?.dataset.dcsImageKey || null;
+}
 function showImageEditIcons(images) {
   if (!editingEnabled) return;
   if (imageEditIconTargets.length === images.length && images.every((img, i) => imageEditIconTargets[i] === img)) return;
@@ -685,6 +688,7 @@ function showImageEditIcons(images) {
         imageAlt: img.alt ?? null,
         imageWidth: img.naturalWidth,
         imageHeight: img.naturalHeight,
+        imageKey: getManagedImageKey(img),
         sectionId: sectionEl?.dataset.section ?? null,
         sectionLabel: sectionEl?.dataset.sectionLabel ?? null
       });
@@ -1130,12 +1134,14 @@ function initEditorBridge() {
         imageAlt: topImage?.alt ?? null,
         imageWidth: topImage?.naturalWidth ?? null,
         imageHeight: topImage?.naturalHeight ?? null,
+        imageKey: topImage ? getManagedImageKey(topImage) : null,
         // All images at click point (for overlapping image scenarios like before/after sliders)
         images: allImages.length > 1 ? allImages.map((img) => ({
           imageUrl: img.currentSrc ?? img.src,
           imageAlt: img.alt ?? null,
           imageWidth: img.naturalWidth,
-          imageHeight: img.naturalHeight
+          imageHeight: img.naturalHeight,
+          imageKey: getManagedImageKey(img)
         })) : null
       });
     }, true);