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

```javascript
// 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)
```javascript
// Not in UI, but works in code
localStorage.setItem('uml-dagre-direction', 'BT');
location.reload();
// Hierarchy flows upward (inverted)
```

### Right-to-Left (RL)
```javascript
// 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)
```typescript
// 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 ▾" 🚀