20 KiB
LCD Builder - Phase 1 Implementation Guide (Critical Fixes)
Objective: Fix 7 critical bugs to make builder functional
Estimated Time: 12-16 hours
Success Criteria: All items on testing checklist pass
Bug #1: Fix Properties Panel Form Apply
File: data/js/builder.js
Lines: 650-820 (buildPropertyForm & applyPropertiesFromForm)
Issue: Form doesn't properly apply changes to widget
Current Code Problem
// Line 768-770 - Problem: If getValue returns null, uses 0 as default
// instead of keeping original value
const getValue = (id) => form.querySelector(`#${id}`);
widget.x = Number(getValue('prop-x')?.value) || 0;
widget.y = Number(getValue('prop-y')?.value) || 0;
Solution
Replace the applyPropertiesFromForm() function with:
function applyPropertiesFromForm(form, widget) {
// Helper to safely get input value
const getInputValue = (id) => {
const input = form.querySelector(`#${id}`);
return input instanceof HTMLInputElement ? input.value : null;
};
// Position - validate bounds
const xVal = parseFloat(getInputValue('prop-x'));
const yVal = parseFloat(getInputValue('prop-y'));
if (!isNaN(xVal)) widget.x = Math.max(0, Math.min(xVal, LCD_WIDTH - 50));
if (!isNaN(yVal)) widget.y = Math.max(0, Math.min(yVal, LCD_HEIGHT - 30));
// Size - validate positive values
const wVal = parseFloat(getInputValue('prop-w'));
const hVal = parseFloat(getInputValue('prop-h'));
if (!isNaN(wVal) && wVal > 0) {
widget.w = wVal;
if ('width' in widget) widget.width = wVal;
}
if (!isNaN(hVal) && hVal > 0) {
widget.h = hVal;
if ('height' in widget) widget.height = hVal;
}
// Text properties
const textVal = getInputValue('prop-text');
if (textVal !== null) widget.text = textVal;
const fontVal = parseFloat(getInputValue('prop-font'));
if (!isNaN(fontVal) && fontVal > 0) widget.fontSize = fontVal;
// Colors
const colorVal = getInputValue('prop-color');
if (colorVal) widget.color = colorVal;
const textColorVal = getInputValue('prop-text-color');
if (textColorVal) widget.textColor = textColorVal;
// Icon
const iconVal = getInputValue('prop-icon');
if (iconVal !== null) widget.icon = iconVal;
// Radius (for buttons)
const radiusVal = parseFloat(getInputValue('prop-radius'));
if (!isNaN(radiusVal) && radiusVal >= 0) widget.radius = radiusVal;
// Binding
const bindingVal = getInputValue('prop-binding');
widget.binding = bindingVal || null;
// Update UI and notify user
redrawCanvas();
renderPreview();
updatePropertiesPanel({ silent: true }); // Update form with actual values
showToast('Widget properties updated', 'success');
}
Testing
- Select a widget
- Change X position in properties
- Click "Apply Changes"
- Verify widget moved on canvas
- Repeat for other properties (Y, Width, Height, Text, Color)
Bug #2: Implement Custom Page Persistence
File: data/js/builder.js
Lines: 312-328 (Create page from button)
Issue: Custom pages not saved to backend
Current Code Problem
// Lines 314-322 - Page added to memory but never saved to device
document.getElementById('page-add')?.addEventListener('click', () => {
const name = prompt('New custom page name?');
if (!name) return;
if (!pagesCache) pagesCache = { pages: [] };
pagesCache.pages = pagesCache.pages || [];
pagesCache.pages.push({ name, widgets: [] });
loadPagesIntoUi();
// MISSING: Save to backend!
showToast(`Created custom page "${name}"`, 'success');
});
Solution
Add this function (add after the page loading functions, around line 190):
// Save custom pages to backend
async function saveCustomPages() {
try {
if (!pagesCache) return;
// Show saving indicator
const status = document.getElementById('save-status');
if (status) status.textContent = 'Saving...';
// POST to backend
const response = await fetch('/api/pages', {
method: 'POST',
headers: { 'Content-Type': 'application/json' },
body: JSON.stringify(pagesCache)
});
if (!response.ok) {
throw new Error(`Save failed: ${response.statusText}`);
}
// Update UI to show unsaved changes
updateSaveStatus();
showToast('Custom pages saved to device', 'success');
} catch (error) {
console.error('Save failed', error);
showToast(`Failed to save pages: ${error.message}`, 'error');
}
}
// Update save status display
function updateSaveStatus() {
const status = document.getElementById('save-status');
if (!status) return;
const count = state.builder.overlayElements?.length ?? 0;
if (count === 0) {
status.textContent = 'Empty';
} else {
status.textContent = `${count} widgets`;
}
}
Replace the page-add button handler (lines 314-322) with:
document.getElementById('page-add')?.addEventListener('click', async () => {
const name = prompt('New custom page name?');
if (!name) return;
// Validate name
if (name.length > 50) {
showToast('Page name too long (max 50 chars)', 'error');
return;
}
if (!pagesCache) pagesCache = { pages: [] };
pagesCache.pages = pagesCache.pages || [];
// Check for duplicate names
if (pagesCache.pages.some(p => p.name === name)) {
showToast('A page with that name already exists', 'error');
return;
}
// Add page to cache
pagesCache.pages.push({ name, widgets: [] });
// Update UI immediately
loadPagesIntoUi();
showToast(`Created page "${name}"`, 'info');
// Save to backend
await saveCustomPages();
});
Testing
- Click "Add Page"
- Enter page name "TestPage"
- Page appears in list
- Refresh page in browser
- Verify "TestPage" still exists
- Reboot ESP32
- Verify page persists on device
Bug #3: Implement Palette Drag-Drop to Canvas
File: data/js/builder.js
Lines: 197-230 (bindCanvasEvents function)
Issue: No drop handler on canvas for palette drag-drop
Current Code Problem
// Lines 308-312 - Drag handlers set pendingWidgetType but nothing uses it
item.addEventListener('dragstart', () => {
state.builder.drag.pendingWidgetType = type;
});
item.addEventListener('dragend', () => {
state.builder.drag.pendingWidgetType = null;
});
// Canvas never has dragover/drop handlers!
Solution
Find the bindCanvasEvents() function and add these handlers after the mousemove handler (around line 230):
function bindCanvasEvents() {
const builder = state.builder;
const canvas = builder.canvas;
if (!canvas) return;
canvas.addEventListener('mousedown', (event) => {
const point = canvasPoint(event);
const idx = findElementAtPoint(point.x, point.y, state.builder.overlayElements);
if (idx !== null) {
builder.selectedIndex = idx;
builder.drag.active = true;
builder.drag.offsetX = point.x - (state.builder.overlayElements[idx].x ?? 0);
builder.drag.offsetY = point.y - (state.builder.overlayElements[idx].y ?? 0);
updatePropertiesPanel();
redrawCanvas();
return;
}
builder.selectedIndex = null;
updatePropertiesPanel();
redrawCanvas();
});
canvas.addEventListener('mousemove', (event) => {
if (!builder.drag.active) return;
const widget = selectedWidget();
if (!widget) return;
const point = canvasPoint(event);
widget.x = Math.max(0, Math.min(point.x - builder.drag.offsetX, LCD_WIDTH - 50));
widget.y = Math.max(0, Math.min(point.y - builder.drag.offsetY, LCD_HEIGHT - 30));
updatePropertiesPanel({ silent: true });
redrawCanvas();
renderPreview();
});
canvas.addEventListener('mouseup', () => {
builder.drag.active = false;
renderPreview();
});
canvas.addEventListener('mouseleave', () => {
builder.drag.active = false;
});
// ADD THESE NEW HANDLERS FOR DRAG-DROP FROM PALETTE:
canvas.addEventListener('dragover', (event) => {
if (!state.builder.drag.pendingWidgetType) return;
event.preventDefault();
event.stopPropagation();
canvas.style.backgroundColor = '#f0fdf4'; // Light green feedback
});
canvas.addEventListener('dragleave', (event) => {
if (event.target !== canvas) return;
canvas.style.backgroundColor = ''; // Reset background
});
canvas.addEventListener('drop', (event) => {
if (!state.builder.drag.pendingWidgetType) return;
event.preventDefault();
event.stopPropagation();
canvas.style.backgroundColor = ''; // Reset background
// Get drop position
const rect = canvas.getBoundingClientRect();
const x = (event.clientX - rect.left) / builder.zoom;
const y = (event.clientY - rect.top) / builder.zoom;
// Add widget at drop position
addWidgetToOverlay(state.builder.drag.pendingWidgetType, x, y);
showToast(`Widget added to canvas`, 'success');
});
// ... rest of existing bindCanvasEvents code ...
}
Testing
- Open builder
- Load a builtin page
- Drag "Label" widget from palette to canvas
- Verify widget appears at drop location
- Repeat with other widget types (Icon, Button, Shape, Value)
- Try dragging to different positions
Bug #4: Implement Delete/Copy/Paste
File: data/js/builder.js
Lines: 240-280 (Toolbar button bindings)
Issue: Button handlers are empty
Current Code Problem
// Lines 258-268 - Event listeners but empty callbacks
document.getElementById('btn-delete')?.addEventListener('click', () => {
// EMPTY!
});
document.getElementById('btn-copy')?.addEventListener('click', () => {
// EMPTY!
});
document.getElementById('btn-paste')?.addEventListener('click', () => {
// EMPTY!
});
Solution
Replace the toolbar bindings (lines 240-280) with:
function bindToolbarActions() {
// Delete button
document.getElementById('btn-delete')?.addEventListener('click', () => {
const widget = selectedWidget();
if (!widget) {
showToast('Select a widget to delete', 'error');
return;
}
const confirmed = confirm('Delete selected widget?');
if (!confirmed) return;
state.builder.overlayElements.splice(state.builder.selectedIndex, 1);
state.builder.selectedIndex = null;
updatePropertiesPanel();
redrawCanvas();
renderPreview();
showToast('Widget deleted', 'success');
});
// Copy button
document.getElementById('btn-copy')?.addEventListener('click', () => {
const widget = selectedWidget();
if (!widget) {
showToast('Select a widget to copy', 'error');
return;
}
// Deep clone the widget
state.builder.clipboard = cloneWidget(widget);
showToast('Widget copied to clipboard', 'info');
});
// Paste button
document.getElementById('btn-paste')?.addEventListener('click', () => {
if (!state.builder.clipboard) {
showToast('Nothing in clipboard to paste', 'error');
return;
}
// Clone from clipboard and offset position
const clone = cloneWidget(state.builder.clipboard);
clone.x = (clone.x ?? 0) + 10; // Offset by 10px so not exactly on top
clone.y = (clone.y ?? 0) + 10;
// Keep within bounds
const w = clone.w ?? clone.width ?? 100;
const h = clone.h ?? clone.height ?? 30;
if (clone.x + w > LCD_WIDTH) clone.x = LCD_WIDTH - w;
if (clone.y + h > LCD_HEIGHT) clone.y = LCD_HEIGHT - h;
state.builder.overlayElements.push(clone);
state.builder.selectedIndex = state.builder.overlayElements.length - 1;
updatePropertiesPanel();
redrawCanvas();
renderPreview();
showToast('Widget pasted', 'success');
});
// Undo button
document.getElementById('btn-undo')?.addEventListener('click', () => {
if (!state.builder.undoStack || state.builder.undoStack.length === 0) {
showToast('Nothing to undo', 'info');
return;
}
// Pop from undo stack
const previous = state.builder.undoStack.pop();
// Push current to redo stack
if (!state.builder.redoStack) state.builder.redoStack = [];
state.builder.redoStack.push(cloneWidgets(state.builder.overlayElements));
// Restore previous state
state.builder.overlayElements = cloneWidgets(previous);
state.builder.selectedIndex = null;
redrawCanvas();
renderPreview();
updatePropertiesPanel();
showToast('Undo', 'info');
});
// Redo button
document.getElementById('btn-redo')?.addEventListener('click', () => {
if (!state.builder.redoStack || state.builder.redoStack.length === 0) {
showToast('Nothing to redo', 'info');
return;
}
// Pop from redo stack
const next = state.builder.redoStack.pop();
// Push current to undo stack
if (!state.builder.undoStack) state.builder.undoStack = [];
state.builder.undoStack.push(cloneWidgets(state.builder.overlayElements));
// Restore next state
state.builder.overlayElements = cloneWidgets(next);
state.builder.selectedIndex = null;
redrawCanvas();
renderPreview();
updatePropertiesPanel();
showToast('Redo', 'info');
});
// Existing toolbar actions continue...
// (Align buttons, Zoom controls, etc.)
// ...
}
Testing
- Add a widget to canvas
- Select it
- Click Copy
- Verify "Widget copied" message
- Click Paste
- Verify cloned widget appears offset
- Click Delete
- Verify confirmation dialog
- Confirm delete
- Verify widget removed
Bug #5: Implement Undo/Redo with History Tracking
File: data/js/builder.js
Lines: 25-40 (initBuilder) and throughout
Issue: No state snapshot recording
Current Code Problem
Undo/Redo stacks exist but are never populated with state snapshots.
Solution
Modify initBuilder() to initialize undo/redo:
// Add this in the state initialization section (around line 25)
if (!state.builder.undoStack) state.builder.undoStack = [];
if (!state.builder.redoStack) state.builder.redoStack = [];
if (!state.builder.clipboard) state.builder.clipboard = null;
Add this helper function (around line 45, before bindCanvasEvents):
// Record current state for undo/redo
function recordUndoState() {
if (!state.builder.undoStack) state.builder.undoStack = [];
if (!state.builder.redoStack) state.builder.redoStack = [];
// Add current state to undo stack (max 20 states)
state.builder.undoStack.push(cloneWidgets(state.builder.overlayElements));
if (state.builder.undoStack.length > 20) {
state.builder.undoStack.shift(); // Remove oldest if over limit
}
// Clear redo stack when new action happens
state.builder.redoStack = [];
}
Call recordUndoState() before modifications:
- In
addWidgetToOverlay()- add line after line 378:recordUndoState(); - In
applyPropertiesFromForm()- add line before modifications - In delete handler - add line before splice
- In paste handler - add line before push
Testing
- Add widget 1
- Add widget 2
- Move widget 1
- Click Undo
- Verify move reversed
- Click Undo again
- Verify widget 2 removed
- Click Redo
- Verify widget 2 reappears
Bug #6: Fix Canvas Drag-Drop Position Tracking
File: data/js/builder.js
Lines: 197-280 (bindCanvasEvents - mousemove handler)
Issue: Widget doesn't follow cursor during drag
Solution
See Bug #3 above - the mousemove handler was added as part of the comprehensive bindCanvasEvents fix. It includes:
canvas.addEventListener('mousemove', (event) => {
if (!builder.drag.active) return;
const widget = selectedWidget();
if (!widget) return;
const point = canvasPoint(event);
widget.x = Math.max(0, Math.min(point.x - builder.drag.offsetX, LCD_WIDTH - 50));
widget.y = Math.max(0, Math.min(point.y - builder.drag.offsetY, LCD_HEIGHT - 30));
updatePropertiesPanel({ silent: true });
redrawCanvas();
renderPreview();
});
This handles:
- ✓ Tracking mouse movement during drag
- ✓ Updating widget position in real-time
- ✓ Keeping widget within canvas bounds
- ✓ Live updating properties panel
- ✓ Redrawing canvas during drag
- ✓ Updating preview
Bug #7: Implement Deploy Verification
File: data/js/builder.js
Lines: 414-430 (deployOverlay function)
Issue: No verification that deploy succeeded
Current Code Problem
// Lines 414-430 - Assumes success after API call
async function deployOverlay() {
// ...
try {
const base = Number(idRaw);
await saveOverlay(base, state.builder.overlayElements);
showToast('Overlay deployed to LCD', 'success');
await triggerRedraw();
// MISSING: Verify data actually made it to device!
} catch (error) {
// ...
}
}
Solution
Replace deployOverlay() function with:
async function deployOverlay() {
const selector = document.getElementById('current-page-selector');
if (!(selector instanceof HTMLSelectElement) || !selector.value) {
showToast('Select a page before deploying', 'error');
return;
}
const [type, idRaw] = selector.value.split(':');
if (type !== 'builtin') {
showToast('Deploy only supports built-in pages', 'error');
return;
}
try {
const base = Number(idRaw);
// Show progress
showToast('Sending overlay to device...', 'info');
// Step 1: Send overlay widgets
await saveOverlay(base, state.builder.overlayElements);
// Step 2: Verify by reading back
showToast('Verifying deployment...', 'info');
const verification = await fetchOverlay(base);
if (!verification?.widgets) {
throw new Error('Verification failed: no data returned from device');
}
// Step 3: Basic consistency check
if (verification.widgets.length !== state.builder.overlayElements.length) {
console.warn('Widget count mismatch - device may have older data');
}
// Step 4: Trigger redraw on device
await triggerRedraw();
// Success!
showToast('✓ Overlay deployed and verified on LCD', 'success');
} catch (error) {
console.error('Deploy failed', error);
showToast(`Deploy failed: ${error.message}`, 'error');
}
}
Testing
- Open builder
- Load a builtin page
- Add some widgets
- Click "Deploy to LCD"
- Verify "Sending..." toast appears
- Verify "Verifying..." toast appears
- Verify success message appears
- Look at actual LCD display
- Verify widgets appear on LCD
Implementation Checklist
Use this checklist to track progress:
-
Bug #1: Properties form apply
- Replace applyPropertiesFromForm() with validation version
- Test editing each property type
- Verify changes persist in canvas
-
Bug #2: Custom page persistence
- Add saveCustomPages() function
- Modify page-add handler to call save
- Test page persists after refresh
- Test page persists after reboot
-
Bug #3: Palette drag-drop
- Add dragover/drop/dragleave handlers to canvas
- Test dragging each widget type to canvas
- Test drop at various positions
-
Bug #4: Delete/Copy/Paste
- Implement delete handler with confirmation
- Implement copy to clipboard
- Implement paste with offset
- Test each operation
-
Bug #5: Undo/Redo
- Initialize undo/redo stacks
- Add recordUndoState() calls
- Implement undo handler (already done in #4)
- Implement redo handler (already done in #4)
- Test undo/redo chain
-
Bug #6: Canvas drag tracking
- Verify mousemove handler from #3 is in place
- Test dragging widget on canvas
- Verify position updates live
- Verify stays within bounds
-
Bug #7: Deploy verification
- Replace deployOverlay() with verification version
- Test deploy to LCD
- Verify success message
- Check widgets appear on LCD
Testing After Each Bug Fix
After implementing each bug fix, test:
- No JavaScript errors in browser console
- Feature works as intended for that bug
- No regression - previously working features still work
- UI feedback appears (toasts, messages)
- Canvas updates correctly
When all 7 bugs are fixed, run the full testing checklist in LCD_BUILDER_BUG_SUMMARY.md
Next Steps
- Implement bugs in order (1-7)
- Test each fix
- After all 7 bugs fixed, run full testing checklist
- Move to Phase 2 (Major bugs & robustness)
- Then Phase 3 (Polish & features)