Guide System V2 - Quick Summary

What Changed?

Before (V1): Guides automatically generated sections—confusing and over-complicated.

Now (V2): Guides only control track sizing (row/column widths in Grid, flex-basis in Flexbox). Section count is managed separately via "Add Section" button.

Key Features

1. Guides = Rulers, Not Generators

• Horizontal guides → adjust row heights (Grid) or flex proportions (Flexbox)
• Vertical guides → adjust column widths (Grid only)
• Does NOT add/remove sections—you control that separately

2. Live Updates

• Drag a guide, see instant layout changes (debounced at 60ms)
• No "confirm" step—changes apply immediately
• "Done" to keep, "Restore & Exit" to undo all

3. Modern, Beautiful UI

• Gradient guide lines (pink → purple when dragging)
• Glowing handles with position labels
• Smooth cubic-bezier transitions (0.3s)

4. Flexbox + Grid Parity

• Flexbox: Horizontal guides split vertical space
• Grid: Both horizontal and vertical guides define tracks
• Sections remain intact when switching modes

User Workflow

1. Add Sections: Click "Add Section" to create content areas (e.g., 4 sections)
2. Enter Divide Mode: Click "Divide" in toolbar
3. Add Guides: Click "Add Horizontal" or "Add Vertical"
4. Drag to Adjust: Move guide handles to resize tracks
5. Remove Guides: Click × on handle to delete
6. Done: Click green "Done" to save, or red "Restore & Exit" to cancel

Technical Changes

Files Modified

1. grid-canvas.component.ts:

   • New methods: applyGridTracksFromGuides(), applyFlexboxFromGuides(), getDividerStops(), convertPixelListToFractions()
   • Removed: mergeSectionsWithGenerated(), createSectionFromGenerated()
   • Added: divideModeSnapshot for snapshot/restore

2. grid-canvas.component.html:

   • Updated hint: "Guides control track sizing only – add/remove sections separately"
   • Changed buttons: "Done" (instead of "Confirm"), "Restore & Exit" (instead of "Cancel")

3. divider-tool.component.scss:

   • Enhanced line styling: gradients, glows, 3px → 4px on drag
   • Modern handle design: gradient backgrounds, backdrop blur, cursor: grab/grabbing

4. grid-canvas.component.scss:

   • Added smooth transitions for grid-template-rows/columns

5. grid-section.component.scss:

   • Added smooth transitions for width/height/grid-row/grid-column

6. grid-section.component.ts:

   • Fixed type: actionClick now uses 'up' | 'down' instead of string

Code Highlights

Applying Grid Tracks (No Section Creation)

private applyGridTracksFromGuides(
  state: DividerState,
  config: LayoutConfiguration,
  canvasSize: { width: number; height: number }
): void {
  const rowStops = this.getDividerStops(state.horizontal, canvasSize.height);
  const colStops = this.getDividerStops(state.vertical, canvasSize.width);

  const rows: string[] = [];
  for (let i = 0; i < rowStops.length - 1; i++) {
    rows.push(`${rowStops[i + 1] - rowStops[i]}px`);
  }

  const columns: string[] = [];
  for (let i = 0; i < colStops.length - 1; i++) {
    columns.push(`${colStops[i + 1] - colStops[i]}px`);
  }

  config.grid = {
    ...(config.grid ?? {}),
    rows: this.convertPixelListToFractions(rows),
    columns: this.convertPixelListToFractions(columns),
    gap: config.grid?.gap ?? '16px'
  };

  // Ensure existing sections have grid placement (if missing)
  config.sections.forEach((section, index) => {
    if (!section.grid) {
      const numCols = columns.length;
      section.grid = {
        row: Math.floor(index / numCols) + 1,
        col: (index % numCols) + 1,
        rowSpan: 1,
        colSpan: 1
      };
    }
    section.flexbox = undefined;
    section.updatedAt = new Date();
  });
}

Key Point: config.sections.forEach() only updates existing sections, never adds new ones.

Visual Design

Guide Line

• Color: Pink gradient (rgba(236, 72, 153))
• Thickness: 3px normal, 4px when dragging
• Shadow: 0 0 12px rgba(236, 72, 153, 0.6)

Guide Handle

• Background: Pink gradient with white border
• Drag State: Changes to purple gradient (rgba(139, 92, 246))
• Cursor: grab → grabbing on drag
• Position Label: White text showing {position}px ({percent}%)

Testing Scenarios

✅ Grid Mode with 2 Horizontal, 1 Vertical Guide

• Expected: 3 rows × 2 columns = 6 grid cells
• Sections: If you have 4 sections, they occupy first 4 cells (auto-placement)
• Result: No extra sections created

✅ Flexbox Mode with 3 Horizontal Guides

• Expected: 4 vertical segments (3 guides create 4 spaces)
• Sections: If you have 2 sections, first uses segment 1's height, second uses segment 2's height
• Result: Sections do NOT multiply

✅ Switch Grid → Flexbox

• Expected: Vertical guides ignored, horizontal guides define flex-basis
• Sections: All existing sections preserved
• Result: No sections lost or added

✅ Remove All Guides

• Expected: Layout reverts to snapshot (state when entering divide mode)
• Sections: Remain unchanged
• Result: Safe undo mechanism

Comparison Table

Files to Review

• Spec: GUIDE-SYSTEM-V2-SPEC.md (full technical details)
• Component: libs/libs-structural/modular-universe/src/lib/components/grid-canvas/
• Divider Tool: libs/libs-structural/modular-universe/src/lib/components/divider-tool/
• Models: libs/libs-structural/modular-universe/src/lib/models/divider.types.ts

Next Steps for Users

1. Test it: Add 3-4 sections, then enter Divide mode and add guides
2. Experiment: Drag guides around to see live updates
3. Compare: Switch between Flexbox and Grid to see how guides adapt
4. Cancel: Try "Restore & Exit" to verify snapshot restore works

Next Steps for Developers

1. Add snap-to-edges: Guides could snap to section boundaries
2. Keyboard shortcuts: Arrow keys for precise guide adjustment
3. Visual grid overlay: Show faint grid lines at guide intersections
4. Guide presets: Save/load common layouts (e.g., "3-column hero")

✅ All Done! The guide system is now intuitive, modern, and flexible.