@nuasite/cms 0.7.3 → 0.8.2

package/src/editor/constants.ts

@@ -87,6 +87,7 @@ export const STORAGE_KEYS = {
 	PENDING_IMAGE_EDITS: 'cms-pending-image-edits',
 	PENDING_COLOR_EDITS: 'cms-pending-color-edits',
 	PENDING_ATTRIBUTE_EDITS: 'cms-pending-attribute-edits',
+	PENDING_BG_IMAGE_EDITS: 'cms-pending-bg-image-edits',
 	SETTINGS: 'cms-settings',
 	PENDING_ENTRY_NAVIGATION: 'cms-pending-entry-navigation',
 	IS_EDITING: 'cms-is-editing',
@@ -104,4 +105,6 @@ export const CSS = {
 	COMPONENT_ID_ATTRIBUTE: 'data-cms-component-id',
 	/** Custom element tag for highlight overlay */
 	HIGHLIGHT_ELEMENT: 'cms-highlight-overlay',
+	/** Data attribute for background image elements */
+	BG_IMAGE_ATTRIBUTE: 'data-cms-bg-img',
 } as const

package/src/editor/editor.ts

@@ -20,11 +20,13 @@ import * as signals from './signals'
 import {
 	clearAllEditsFromStorage,
 	loadAttributeEditsFromStorage,
+	loadBgImageEditsFromStorage,
 	loadColorEditsFromStorage,
 	loadEditsFromStorage,
 	loadImageEditsFromStorage,
 	loadPendingEntryNavigation,
 	saveAttributeEditsToStorage,
+	saveBgImageEditsToStorage,
 	saveColorEditsToStorage,
 	saveEditingState,
 	saveEditsToStorage,
@@ -37,6 +39,8 @@ import type { AttributeChangePayload, ChangePayload, CmsConfig, DeploymentStatus
 const MARKDOWN_ATTRIBUTE = 'data-cms-markdown'
 // CSS attribute for image elements
 const IMAGE_ATTRIBUTE = 'data-cms-img'
+// CSS attribute for background image elements
+const BG_IMAGE_ATTRIBUTE = 'data-cms-bg-img'
 
 /**
  * Inline HTML elements that indicate styled/formatted content.
@@ -112,6 +116,7 @@ export async function startEditMode(
 	const savedImageEdits = loadImageEditsFromStorage()
 	const savedColorEdits = loadColorEditsFromStorage()
 	const savedAttributeEdits = loadAttributeEditsFromStorage()
+	const savedBgImageEdits = loadBgImageEditsFromStorage()
 	const currentManifest = signals.manifest.value
 
 	getAllCmsElements().forEach(el => {
@@ -151,6 +156,15 @@ export async function startEditMode(
 			return
 		}
 
+		// Check if this is a background image element
+		// Background image elements are edited via the bg image overlay panel
+		if (el.hasAttribute(BG_IMAGE_ATTRIBUTE)) {
+			logDebug(config.debug, 'Background image element detected:', cmsId)
+			makeElementNonEditable(el)
+			setupBgImageTracking(config, el, cmsId, savedBgImageEdits[cmsId])
+			return
+		}
+
 		makeElementEditable(el)
 
 		// Suppress browser native contentEditable undo/redo (we handle it ourselves)
@@ -502,11 +516,42 @@ export function discardAllChanges(onStateChange?: () => void): void {
 		applyAttributesToElement(element, originalAttributes)
 	})
 
+	// Restore original background image classes
+	signals.pendingBgImageChanges.value.forEach((change) => {
+		const {
+			element,
+			originalBgImageClass,
+			newBgImageClass,
+			originalBgSize,
+			newBgSize,
+			originalBgPosition,
+			newBgPosition,
+			originalBgRepeat,
+			newBgRepeat,
+		} = change
+		const classes = element.className.split(/\s+/).filter(Boolean)
+		const newClassValues = new Set([newBgImageClass, newBgSize, newBgPosition, newBgRepeat].filter(Boolean))
+		const originalClassValues = [originalBgImageClass, originalBgSize, originalBgPosition, originalBgRepeat].filter(Boolean)
+
+		const filtered = classes.filter(c => !newClassValues.has(c))
+		for (const c of originalClassValues) {
+			if (!filtered.includes(c)) {
+				filtered.push(c)
+			}
+		}
+		element.className = filtered.join(' ')
+
+		// Clear inline bg style overrides
+		element.style.backgroundImage = ''
+		element.style.backgroundSize = ''
+		element.style.backgroundPosition = ''
+		element.style.backgroundRepeat = ''
+	})
+
 	cleanupHighlightSystem()
-	signals.clearPendingChanges()
-	signals.clearPendingImageChanges()
-	signals.clearPendingColorChanges()
-	signals.clearPendingAttributeChanges()
+	for (const entry of Object.values(signals.changeRegistry)) {
+		entry.mapSignal.value = new Map()
+	}
 	clearAllEditsFromStorage()
 	clearHistory()
 	stopEditMode(onStateChange)
@@ -550,12 +595,13 @@ export async function saveAllChanges(
 	const dirtyChanges = signals.dirtyChanges.value
 	const dirtyImageChanges = signals.dirtyImageChanges.value
 	const dirtyColorChanges = signals.dirtyColorChanges.value
+	const dirtyBgImageChanges = signals.dirtyBgImageChanges.value
 	const dirtyAttributeChanges = signals.dirtyAttributeChanges.value
 	const dirtySeoChanges = signals.dirtySeoChanges.value
 
 	if (
-		dirtyChanges.length === 0 && dirtyImageChanges.length === 0 && dirtyColorChanges.length === 0 && dirtyAttributeChanges.length === 0
-		&& dirtySeoChanges.length === 0
+		dirtyChanges.length === 0 && dirtyImageChanges.length === 0 && dirtyColorChanges.length === 0 && dirtyBgImageChanges.length === 0
+		&& dirtyAttributeChanges.length === 0 && dirtySeoChanges.length === 0
 	) {
 		return { success: true, updated: 0 }
 	}
@@ -653,7 +699,7 @@ export async function saveAllChanges(
 						sourcePath: bestSourcePath ?? entry?.sourcePath ?? '',
 						sourceLine: bestSourceLine ?? entry?.sourceLine ?? 0,
 						sourceSnippet: bestSourceSnippet ?? entry?.sourceSnippet ?? '',
-						colorChange: {
+						styleChange: {
 							oldClass: origAttr?.value || '',
 							newClass: newAttr.value,
 							type: classType,
@@ -666,6 +712,44 @@ export async function saveAllChanges(
 			}
 		})
 
+		// Add background image changes to the payload
+		dirtyBgImageChanges.forEach(([cmsId, change]) => {
+			const entry = manifest.entries[cmsId]
+			const bgChanges: Array<{ oldClass: string; newClass: string; type: 'bgImage' | 'bgSize' | 'bgPosition' | 'bgRepeat' }> = []
+
+			if (change.newBgImageClass !== change.originalBgImageClass) {
+				bgChanges.push({ oldClass: change.originalBgImageClass, newClass: change.newBgImageClass, type: 'bgImage' })
+			}
+			if (change.newBgSize !== change.originalBgSize) {
+				bgChanges.push({ oldClass: change.originalBgSize, newClass: change.newBgSize, type: 'bgSize' })
+			}
+			if (change.newBgPosition !== change.originalBgPosition) {
+				bgChanges.push({ oldClass: change.originalBgPosition, newClass: change.newBgPosition, type: 'bgPosition' })
+			}
+			if (change.newBgRepeat !== change.originalBgRepeat) {
+				bgChanges.push({ oldClass: change.originalBgRepeat, newClass: change.newBgRepeat, type: 'bgRepeat' })
+			}
+
+			for (const bgChange of bgChanges) {
+				changes.push({
+					cmsId,
+					newValue: '',
+					originalValue: '',
+					sourcePath: entry?.sourcePath ?? '',
+					sourceLine: entry?.sourceLine ?? 0,
+					sourceSnippet: entry?.sourceSnippet ?? '',
+					styleChange: {
+						oldClass: bgChange.oldClass,
+						newClass: bgChange.newClass,
+						type: bgChange.type,
+						sourcePath: entry?.sourcePath,
+						sourceLine: entry?.sourceLine,
+						sourceSnippet: entry?.sourceSnippet,
+					},
+				})
+			}
+		})
+
 		// Add attribute changes to the payload
 		dirtyAttributeChanges.forEach(([cmsId, change]) => {
 			const { originalAttributes, newAttributes } = change
@@ -740,6 +824,18 @@ export async function saveAllChanges(
 				}))
 			})
 
+			// Update all dirty bg image changes to mark as saved
+			dirtyBgImageChanges.forEach(([cmsId, change]) => {
+				signals.updatePendingBgImageChange(cmsId, (c) => ({
+					...c,
+					originalBgImageClass: c.newBgImageClass,
+					originalBgSize: c.newBgSize,
+					originalBgPosition: c.newBgPosition,
+					originalBgRepeat: c.newBgRepeat,
+					isDirty: false,
+				}))
+			})
+
 			// Update all dirty attribute changes to mark as saved
 			dirtyAttributeChanges.forEach(([cmsId, change]) => {
 				signals.updatePendingAttributeChange(cmsId, (c) => ({
@@ -786,6 +882,7 @@ export async function saveAllChanges(
 		saveEditsToStorage(signals.pendingChanges.value)
 		saveImageEditsToStorage(signals.pendingImageChanges.value)
 		saveColorEditsToStorage(signals.pendingColorChanges.value)
+		saveBgImageEditsToStorage(signals.pendingBgImageChanges.value)
 		saveAttributeEditsToStorage(signals.pendingAttributeChanges.value)
 		throw err
 	} finally {
@@ -1026,6 +1123,75 @@ function setupColorTracking(
 	}
 }
 
+/**
+ * Initialize background image change tracking for elements with bg-[url()] classes.
+ * Background image editing is triggered via the bg image overlay panel.
+ */
+function setupBgImageTracking(
+	config: CmsConfig,
+	el: HTMLElement,
+	cmsId: string,
+	savedEdit: import('./types').SavedBackgroundImageEdit | undefined,
+): void {
+	const manifest = signals.manifest.value
+	const entry = manifest.entries[cmsId]
+
+	if (!entry?.backgroundImage) {
+		return
+	}
+
+	logDebug(config.debug, 'Setting up bg image tracking for:', cmsId, entry.backgroundImage)
+
+	if (!signals.pendingBgImageChanges.value.has(cmsId)) {
+		if (savedEdit) {
+			// Restore saved bg image classes on the element
+			const classes = el.className.split(/\s+/).filter(Boolean)
+			const originals = [savedEdit.originalBgImageClass, savedEdit.originalBgSize, savedEdit.originalBgPosition, savedEdit.originalBgRepeat].filter(
+				Boolean,
+			)
+			const news = [savedEdit.newBgImageClass, savedEdit.newBgSize, savedEdit.newBgPosition, savedEdit.newBgRepeat].filter(Boolean)
+
+			const filtered = classes.filter(c => !originals.includes(c))
+			for (const c of news) {
+				if (!filtered.includes(c)) {
+					filtered.push(c)
+				}
+			}
+			el.className = filtered.join(' ')
+
+			signals.setPendingBgImageChange(cmsId, {
+				element: el,
+				cmsId,
+				originalBgImageClass: savedEdit.originalBgImageClass,
+				newBgImageClass: savedEdit.newBgImageClass,
+				originalBgSize: savedEdit.originalBgSize,
+				newBgSize: savedEdit.newBgSize,
+				originalBgPosition: savedEdit.originalBgPosition,
+				newBgPosition: savedEdit.newBgPosition,
+				originalBgRepeat: savedEdit.originalBgRepeat,
+				newBgRepeat: savedEdit.newBgRepeat,
+				isDirty: true,
+			})
+			logDebug(config.debug, 'Restored saved bg image edit:', cmsId, savedEdit)
+		} else {
+			const bg = entry.backgroundImage
+			signals.setPendingBgImageChange(cmsId, {
+				element: el,
+				cmsId,
+				originalBgImageClass: bg.bgImageClass,
+				newBgImageClass: bg.bgImageClass,
+				originalBgSize: bg.bgSize ?? '',
+				newBgSize: bg.bgSize ?? '',
+				originalBgPosition: bg.bgPosition ?? '',
+				newBgPosition: bg.bgPosition ?? '',
+				originalBgRepeat: bg.bgRepeat ?? '',
+				newBgRepeat: bg.bgRepeat ?? '',
+				isDirty: false,
+			})
+		}
+	}
+}
+
 /**
  * Handle color change from the color toolbar.
  * Called when user selects a new color.

package/src/editor/history.ts

@@ -1,6 +1,12 @@
 import { computed, signal } from '@preact/signals'
 import * as signals from './signals'
-import { saveAttributeEditsToStorage, saveColorEditsToStorage, saveEditsToStorage, saveImageEditsToStorage } from './storage'
+import {
+	saveAttributeEditsToStorage,
+	saveBgImageEditsToStorage,
+	saveColorEditsToStorage,
+	saveEditsToStorage,
+	saveImageEditsToStorage,
+} from './storage'
 import type { Attribute, UndoAction, UndoTextAction } from './types'
 
 // ============================================================================
@@ -159,52 +165,104 @@ function scrollToElement(element: HTMLElement): void {
 	}
 }
 
-function applyReverse(action: UndoAction): void {
-	switch (action.type) {
-		case 'text':
+/** Registry of undo/redo handlers keyed by action type.
+ *  Adding a new UndoAction variant forces a TypeScript error until its handlers are added here. */
+type UndoHandlers = {
+	[K in UndoAction['type']]: {
+		applyReverse: (action: Extract<UndoAction, { type: K }>) => void
+		applyForward: (action: Extract<UndoAction, { type: K }>) => void
+	}
+}
+
+const undoRegistry: UndoHandlers = {
+	text: {
+		applyReverse: (action) => {
 			scrollToElement(action.element)
 			applyTextState(action.cmsId, action.element, action.previousHTML, action.previousText, action.wasDirty)
-			break
-		case 'image':
+		},
+		applyForward: (action) => {
+			scrollToElement(action.element)
+			applyTextState(action.cmsId, action.element, action.currentHTML, action.currentText, true)
+		},
+	},
+	image: {
+		applyReverse: (action) => {
 			scrollToElement(action.element)
 			applyImageState(action.cmsId, action.element, action.previousSrc, action.previousAlt, action.wasDirty)
-			break
-		case 'color':
+		},
+		applyForward: (action) => {
+			scrollToElement(action.element)
+			applyImageState(action.cmsId, action.element, action.currentSrc, action.currentAlt, true)
+		},
+	},
+	color: {
+		applyReverse: (action) => {
 			scrollToElement(action.element)
 			applyColorState(action.cmsId, action.element, action.previousClassName, action.previousStyleCssText, action.previousClasses, action.wasDirty)
-			break
-		case 'attribute':
+		},
+		applyForward: (action) => {
 			scrollToElement(action.element)
-			applyAttributeState(action.cmsId, action.element, action.previousAttributes, action.wasDirty)
-			break
-		case 'seo':
-			applySeoState(action.cmsId, action.previousValue, action.originalValue, action.wasDirty)
-			break
-	}
-}
-
-function applyForward(action: UndoAction): void {
-	switch (action.type) {
-		case 'text':
+			applyColorState(action.cmsId, action.element, action.currentClassName, action.currentStyleCssText, action.currentClasses, true)
+		},
+	},
+	bgImage: {
+		applyReverse: (action) => {
 			scrollToElement(action.element)
-			applyTextState(action.cmsId, action.element, action.currentHTML, action.currentText, true)
-			break
-		case 'image':
+			applyBgImageState(
+				action.cmsId,
+				action.element,
+				action.previousClassName,
+				action.previousStyleCssText,
+				action.previousBgImageClass,
+				action.previousBgSize,
+				action.previousBgPosition,
+				action.previousBgRepeat,
+				action.wasDirty,
+			)
+		},
+		applyForward: (action) => {
 			scrollToElement(action.element)
-			applyImageState(action.cmsId, action.element, action.currentSrc, action.currentAlt, true)
-			break
-		case 'color':
+			applyBgImageState(
+				action.cmsId,
+				action.element,
+				action.currentClassName,
+				action.currentStyleCssText,
+				action.currentBgImageClass,
+				action.currentBgSize,
+				action.currentBgPosition,
+				action.currentBgRepeat,
+				true,
+			)
+		},
+	},
+	attribute: {
+		applyReverse: (action) => {
 			scrollToElement(action.element)
-			applyColorState(action.cmsId, action.element, action.currentClassName, action.currentStyleCssText, action.currentClasses, true)
-			break
-		case 'attribute':
+			applyAttributeState(action.cmsId, action.element, action.previousAttributes, action.wasDirty)
+		},
+		applyForward: (action) => {
 			scrollToElement(action.element)
 			applyAttributeState(action.cmsId, action.element, action.currentAttributes, true)
-			break
-		case 'seo':
+		},
+	},
+	seo: {
+		applyReverse: (action) => {
+			applySeoState(action.cmsId, action.previousValue, action.originalValue, action.wasDirty)
+		},
+		applyForward: (action) => {
 			applySeoState(action.cmsId, action.currentValue, action.originalValue, true)
-			break
-	}
+		},
+	},
+}
+
+function applyReverse(action: UndoAction): void {
+	const handlers = undoRegistry[action.type] as UndoHandlers[typeof action.type]
+	handlers.applyReverse(action as any)
+}
+
+function applyForward(action: UndoAction): void {
+	const handlers = undoRegistry[action.type] as UndoHandlers[typeof action.type]
+	handlers.applyForward(action as any)
 }
 
 // ============================================================================
@@ -323,6 +381,34 @@ function applySeoState(
 	})
 }
 
+function applyBgImageState(
+	cmsId: string,
+	element: HTMLElement,
+	className: string,
+	styleCssText: string,
+	bgImageClass: string,
+	bgSize: string,
+	bgPosition: string,
+	bgRepeat: string,
+	isDirty: boolean,
+): void {
+	if (element.isConnected) {
+		element.className = className
+		element.style.cssText = styleCssText
+	}
+
+	signals.updatePendingBgImageChange(cmsId, (c) => ({
+		...c,
+		newBgImageClass: bgImageClass,
+		newBgSize: bgSize,
+		newBgPosition: bgPosition,
+		newBgRepeat: bgRepeat,
+		isDirty,
+	}))
+
+	saveBgImageEditsToStorage(signals.pendingBgImageChanges.value)
+}
+
 // ============================================================================
 // Clear History
 // ============================================================================

package/src/editor/hooks/index.ts

@@ -17,3 +17,6 @@ export type { TextSelectionState } from './useTextSelection'
 
 export { useImageHoverDetection } from './useImageHoverDetection'
 export type { ImageHoverState } from './useImageHoverDetection'
+
+export { useBgImageHoverDetection } from './useBgImageHoverDetection'
+export type { BgImageHoverState } from './useBgImageHoverDetection'

package/src/editor/hooks/useBgImageHoverDetection.ts

@@ -0,0 +1,101 @@
+import { useCallback, useEffect, useRef, useState } from 'preact/hooks'
+import { CSS, TIMING } from '../constants'
+import * as signals from '../signals'
+import { isEventOnCmsUI, usePositionTracking } from './utils'
+
+export interface BgImageHoverState {
+	visible: boolean
+	rect: DOMRect | null
+	element: HTMLElement | null
+	cmsId: string | null
+}
+
+const INITIAL_STATE: BgImageHoverState = {
+	visible: false,
+	rect: null,
+	element: null,
+	cmsId: null,
+}
+
+/**
+ * Hook for detecting and tracking hovered CMS background image elements.
+ * Shows a visual overlay when hovering over elements marked with data-cms-bg-img.
+ */
+export function useBgImageHoverDetection(): BgImageHoverState {
+	const [bgImageHoverState, setBgImageHoverState] = useState<BgImageHoverState>(INITIAL_STATE)
+
+	// Throttle ref for element detection
+	const lastDetectionTime = useRef<number>(0)
+
+	// Handle position updates on scroll/resize
+	const handlePositionChange = useCallback((rect: DOMRect | null) => {
+		if (rect) {
+			setBgImageHoverState(prev => ({ ...prev, rect }))
+		} else {
+			setBgImageHoverState(INITIAL_STATE)
+		}
+	}, [])
+
+	// Track element position on scroll/resize
+	usePositionTracking(
+		bgImageHoverState.element,
+		handlePositionChange,
+		bgImageHoverState.visible,
+	)
+
+	// Setup hover detection for background image elements
+	useEffect(() => {
+		const handleMouseMove = (ev: MouseEvent) => {
+			const isEditing = signals.isEditing.value
+
+			if (!isEditing) {
+				setBgImageHoverState(prev => prev.visible ? INITIAL_STATE : prev)
+				return
+			}
+
+			// Check if hovering over CMS UI - keep current state
+			if (isEventOnCmsUI(ev)) {
+				return
+			}
+
+			// Throttle detection for performance
+			const now = Date.now()
+			if (now - lastDetectionTime.current < TIMING.ELEMENT_DETECTION_THROTTLE_MS) {
+				return
+			}
+			lastDetectionTime.current = now
+
+			// Check if hovering over an element with data-cms-bg-img attribute
+			const elements = document.elementsFromPoint(ev.clientX, ev.clientY)
+
+			for (const el of elements) {
+				// If there's a contentEditable element above, don't show overlay
+				if (el instanceof HTMLElement && el.contentEditable === 'true') {
+					setBgImageHoverState(INITIAL_STATE)
+					return
+				}
+
+				if (el instanceof HTMLElement && el.hasAttribute(CSS.BG_IMAGE_ATTRIBUTE)) {
+					const cmsId = el.getAttribute(CSS.ID_ATTRIBUTE)
+					const rect = el.getBoundingClientRect()
+
+					setBgImageHoverState({
+						visible: true,
+						rect,
+						element: el,
+						cmsId,
+					})
+					return
+				}
+			}
+
+			// No bg image element found, hide overlay
+			setBgImageHoverState(INITIAL_STATE)
+		}
+
+		document.addEventListener('mousemove', handleMouseMove, true)
+		return () => document.removeEventListener('mousemove', handleMouseMove, true)
+	}, [])
+
+	return bgImageHoverState
+}

package/src/editor/index.tsx

@@ -4,6 +4,7 @@ import { fetchManifest } from './api'
 import { AIChat } from './components/ai-chat'
 import { AITooltip } from './components/ai-tooltip'
 import { AttributeEditor } from './components/attribute-editor'
+import { BgImageOverlay } from './components/bg-image-overlay'
 import { BlockEditor } from './components/block-editor'
 import { CollectionsBrowser } from './components/collections-browser'
 import { ColorToolbar } from './components/color-toolbar'
@@ -34,6 +35,7 @@ import {
 import { performRedo, performUndo } from './history'
 import {
 	useAIHandlers,
+	useBgImageHoverDetection,
 	useBlockEditorHandlers,
 	useComponentClickHandler,
 	useElementDetection,
@@ -79,6 +81,7 @@ const CmsUI = () => {
 	const config = signals.config.value
 	const outlineState = useElementDetection()
 	const imageHoverState = useImageHoverDetection()
+	const bgImageHoverState = useBgImageHoverDetection()
 	const textSelectionState = useTextSelection()
 	const { tooltipState, showTooltipForElement, hideTooltip } = useTooltipState()
 	const updateUI = useCallback(() => {
@@ -365,6 +368,15 @@ const CmsUI = () => {
 				/>
 			</ErrorBoundary>
 
+			<ErrorBoundary componentName="BgImageOverlay">
+				<BgImageOverlay
+					visible={bgImageHoverState.visible && isEditing}
+					rect={bgImageHoverState.rect}
+					element={bgImageHoverState.element}
+					cmsId={bgImageHoverState.cmsId}
+				/>
+			</ErrorBoundary>
+
 			<ErrorBoundary componentName="Toolbar">
 				<Toolbar
 					callbacks={{