glam/LAYOUT_OPTIONS_QUICK_REFERENCE.md

Quick Reference: 5 Layout Options

When to Use Which Layout

🌀 Force Layout

Use When: Exploring relationships, non-hierarchical data
Avoid When: Need clean documentation or fixed positions
Speed: Slow (5s animation)
Example: "Let me see how these entities group naturally"

---

📊 Hierarchical (Top→Bottom)

Use When: UML class diagrams, standard documentation
Avoid When: Screen is wider than tall
Speed: Instant
Example: "Standard inheritance hierarchy for API docs"

---

➡️ Hierarchical (Left→Right)

Use When: Process flows, wide monitors, sequential steps
Avoid When: Deep hierarchies (runs off screen)
Speed: Instant
Example: "State machine diagram on ultrawide monitor"

---

📦 Adaptive (Tight Tree)

Use When: Large diagrams, printing, small screens
Avoid When: Need generous whitespace
Speed: Instant
Example: "Fit 50 classes on one page for printout"

---

📏 Adaptive (Longest Path)

Use When: Dependency analysis, critical paths
Avoid When: Need balanced horizontal distribution
Speed: Instant
Example: "Show longest inheritance chain depth"

---

Quick Decision Tree

START: What's your goal?
  ↓
Need documentation? → YES → Screen orientation?
  │                          ↓
  │                        Wide → Hierarchical LR
  │                          ↓
  │                        Tall → Hierarchical TB
  ↓
Exploring data? → YES → Force Layout
  ↓
Large diagram (30+ nodes)? → YES → Tight Tree
  ↓
Deep hierarchy? → YES → Longest Path
  ↓
DEFAULT → Hierarchical TB

---

Keyboard Shortcuts (Future)

Not yet implemented, but planned:

• Ctrl+1 - Force Layout
• Ctrl+2 - Hierarchical TB
• Ctrl+3 - Hierarchical LR
• Ctrl+4 - Tight Tree
• Ctrl+5 - Longest Path

---

localStorage Keys

// Check current settings in console
localStorage.getItem('uml-layout-type')      // 'force' or 'dagre'
localStorage.getItem('uml-dagre-direction')  // 'TB', 'BT', 'LR', 'RL'
localStorage.getItem('uml-dagre-ranker')     // 'network-simplex', 'tight-tree', 'longest-path'

// Reset to defaults
localStorage.setItem('uml-layout-type', 'force');
localStorage.setItem('uml-dagre-direction', 'TB');
localStorage.setItem('uml-dagre-ranker', 'network-simplex');
location.reload();

---

Testing All Layouts (60 Seconds)

1. Open http://localhost:5173/uml-viewer
2. Select "Custodian Multi-Aspect (Mermaid Class)"
3. Click Layout ▾ button
4. Try each option:
   • Force → Wait 5 seconds for settling
   • Hierarchical TB → Instant grid
   • Hierarchical LR → Rotated 90°
   • Tight Tree → Compact version
   • Longest Path → Depth-optimized
5. Switch back to Hierarchical TB
6. Refresh page → Should remember your choice

---

Visual Comparison

Small Diagram (5 nodes)

Force:          Hierarchical TB:    Hierarchical LR:
  A   B            A                 A → B → C
   \ /             ↓                     ↓   ↓
    C          ┌───┴───┐                D → E
   / \         B       C
  D   E        ↓       ↓
               D       E

Large Diagram (20 nodes)

Force:                 Hierarchical TB:        Tight Tree:
[scattered chaos]      [neat grid, 4 ranks]    [compact grid, 6 ranks]
- Hard to follow       - Easy to read          - Very compact
- Needs zoom           - Clear hierarchy       - Fits on screen
- Organic              - Professional          - Dense

---

Common Issues

"Layout dropdown won't open"

• Check console for errors
• Verify lucide-react installed: npm list lucide-react
• Try clicking the "Layout" text, not just the icon

"Hierarchical LR runs off screen"

• Use Fit to Screen button (toolbar left side)
• Or switch to Hierarchical TB for tall diagrams
• Or reduce zoom level

"Tight Tree looks messy"

• Not all graphs benefit from compactness
• Try Hierarchical TB for clearer spacing
• Tight Tree is for quantity over clarity

"Longest Path creates uneven columns"

• This is expected behavior
• Algorithm prioritizes depth over balance
• Use Network Simplex (Hierarchical TB/LR) for balance

---

Bonus: Hidden Features

Bottom-to-Top (BT)

// Not in UI, but works in code
localStorage.setItem('uml-dagre-direction', 'BT');
location.reload();
// Hierarchy flows upward (inverted)

Right-to-Left (RL)

// Not in UI, but works in code
localStorage.setItem('uml-dagre-direction', 'RL');
location.reload();
// Hierarchy flows right-to-left (RTL languages)

Alignment (UL/UR/DL/DR)

// Requires code change in UMLVisualization.tsx
dagreAlignment='UL'  // Upper-left align

---

Performance Tips

1. Use Dagre for production (10-100x faster than force)
2. Use Force for exploration (organic, reveals patterns)
3. Tight Tree for 50+ nodes (compact without sacrificing clarity)
4. LR for wide screens (utilize horizontal space)
5. Longest Path for dependencies (critical path analysis)

---

Report Issues

When reporting layout bugs, include:

1. Layout type (Force, Hierarchical TB, etc.)
2. Diagram name
3. Number of nodes
4. Screenshot showing the issue
5. Browser console errors (if any)

---

Documentation: See ADVANCED_LAYOUT_OPTIONS_COMPLETE.md for full details

Test Now: http://localhost:5173/uml-viewer → Click "Layout ▾" 🚀