Glance/TESTING_SNAP.md

Testing Grid Snapping

How to Test

1. Start the development server:

   npm run dev
   

2. Open the browser console (F12) to see debug logs

3. Select a grid template:

   • Click on one of the grid templates (e.g., "Simple 2x2 Grid" or "Dashboard Layout")
   • You should see the grid boxes appear with dashed borders

4. Add a widget:

   • Choose a widget type (Clock, Weather, etc.)
   • Click "Add Widget"
   • A widget will appear on the dashboard

5. Test snapping:

   • Drag the widget over one of the dashed grid boxes

   • Watch the console for debug output like:

     [Snap Debug] Finding target: { widgetRect, widgetCenter, cellsCount, threshold }
     [Snap Debug] Checking cell: { cellId, distance, withinThreshold }
     [Snap Debug] Best cell: "cell-1"
     

   • Look for visual feedback:

     • Grid cell should highlight when widget is near
     • Cell border should become solid and glow
     • "Drop to snap" indicator should appear

6. Release the widget:

   • Widget should snap to the cell position
   • Widget should resize to fit the cell

What to Look For in Console

If snapping is working:

[Snap Debug] Finding target: { cellsCount: 4, threshold: 30 }
[Snap Debug] Checking cell: { cellId: "cell-1", distance: 15.2, withinThreshold: true }
[Snap Debug] Cell is candidate: { cellId: "cell-1", overlap: 0.45, score: -7.3 }
[Snap Debug] Best cell: "cell-1"
[Snap Debug] Drag: { snapped: true, targetCellId: "cell-1" }

If snapping is NOT working:

[Snap Debug] Finding target: { cellsCount: 4, threshold: 30 }
[Snap Debug] Checking cell: { cellId: "cell-1", distance: 450.8, withinThreshold: false }
[Snap Debug] Best cell: none
[Snap Debug] Drag: { snapped: false, targetCellId: null }

Common Issues

Issue 1: Distance is too large

Symptom: Console shows distance: 450.8, withinThreshold: false

Cause: Coordinate space mismatch - widget and cells are in different coordinate systems

Solution: Check that:

• Grid cells use absolute coordinates (e.g., x: 10, y: 10)
• Widget positions are in the same coordinate space
• Scale transform is correctly applied

Issue 2: No cells found

Symptom: Console shows cellsCount: 0

Cause: Grid cells not being passed to WidgetRenderer

Solution: Verify grid template is selected and cells are defined

Issue 3: Cells never within threshold

Symptom: All cells show withinThreshold: false

Cause: Threshold too small OR coordinates are scaled incorrectly

Solution:

• Increase threshold in SNAP_CONFIG
• Check coordinate transformation in screenToGrid()

Debug Commands

Open browser console and run:

// Check grid configuration
JSON.parse(localStorage.getItem('dashboard-grid-config'))

// Check widget positions
JSON.parse(localStorage.getItem('dashboard-config'))

// Clear saved data and start fresh
localStorage.clear()
location.reload()

Expected Behavior

Action	Expected Result
Drag widget near cell (< 30px)	Cell highlights with blue glow
Drag widget over cell center	Cell shows "Drop to snap" indicator
Release widget over cell	Widget snaps to cell position and size
Drag widget far from cells	No highlighting, free placement
Drag while no grid selected	No snapping, free placement

Next Steps

Based on console output, we can diagnose:

1. If cells are detected but distance is wrong: Coordinate transformation bug
2. If cells show cellsCount: 0: Grid cells not passing through props
3. If snapping works but visual feedback doesn't: Dashboard component issue
4. If nothing happens: Check if gridCells prop is empty array

Please run the test and share the console output!