# Edge Directionality - Quick User Guide

## 🎯 **What's New?**

The UML Viewer now has **clear, interactive edges** with visible directionality!

---

## 🖱️ **How to Use**

### **Hover Over Any Edge**
- Edge **highlights** (thicker, brighter)
- Arrow becomes **larger and bolder**
- Label **appears** with relationship details
- For bidirectional edges: Tooltip shows **"Click to reverse direction"**

### **Click on Bidirectional Edges** 
*(Association and Aggregation types)*

- Edge **flashes** to confirm the action
- Source and target **swap positions**
- Arrow points in **opposite direction**
- Layout **adjusts** automatically

### **Which Edges are Reversible?**

| Edge Type | Arrow Shape | Reversible? | Use Case |
|-----------|-------------|-------------|----------|
| **Association** | Filled triangle → | ✅ YES | General relationships (click to reverse) |
| **Aggregation** | Hollow diamond ◇→ | ✅ YES | Part-of relationships (click to reverse) |
| **Composition** | Filled diamond ♦→ | ❌ NO | Strong ownership (fixed direction) |
| **Inheritance** | Hollow triangle ▷→ | ❌ NO | Parent-child hierarchy (fixed direction) |

---

## 💡 **Quick Tips**

1. **Can't see edge direction?** → Hover over it!
2. **Need to reverse a relationship?** → Click on association or aggregation edges
3. **Want to see labels clearly?** → Hover over edges (labels auto-show)
4. **Edge looks wrong after reversing?** → Click again to toggle back

---

## 🎨 **Visual Guide**

### **Normal State** (70% opacity)
```
NodeA --------→ NodeB
       (faint)
```

### **Hover State** (100% opacity, bold arrow)
```
NodeA ========⇒ NodeB
    "relationship [1..*]"
```

### **Click Effect** (flash animation)
```
NodeA ⚡======⚡⇒ NodeB
    "relationship [1..*]" (bold)
        ↓ (500ms animation)
NodeA ←-------- NodeB
       (reversed!)
```

---

## 🔍 **Examples**

### **Example 1: Ontology Diagram**
```
Organization ─has─> Department
              ↑
           (click)
              ↓
Organization <─is part of─ Department
```

### **Example 2: Database Schema**
```
Author ◇─writes─> Book
        ↑
     (click)
        ↓
Author <─written by─◇ Book
```

---

## ❓ **FAQ**

**Q: Why can't I click on inheritance edges?**  
A: Inheritance represents a strict hierarchy (parent-child), so direction is fixed.

**Q: Do my changes persist?**  
A: Currently, reversals are session-only. Reload resets to original schema.

**Q: Can I make other edge types bidirectional?**  
A: Yes! In your schema definition, add `bidirectional: true` to any link.

**Q: What happens if I click while zoomed?**  
A: Reversal works at any zoom level - click away!

**Q: Do labels always show?**  
A: No - they're semi-transparent by default, fully visible on hover (less clutter!).

---

## 🐛 **Troubleshooting**

| Problem | Solution |
|---------|----------|
| Edge not highlighting on hover | Zoom out - edge might be off-screen |
| Click doesn't reverse | Check if edge type is association/aggregation |
| Arrow pointing wrong way | Click to toggle back to original direction |
| Label not showing | Ensure edge has `label` or `cardinality` property |
| Performance slow with many edges | Use Dagre layout (instant) instead of Force (animated) |

---

## 🚀 **Advanced Usage**

### **Custom Bidirectional Edges**

In your schema file (e.g., `.mmd`, `.yaml`):

```yaml
links:
  - source: CustodianObservation
    target: CustodianName
    type: association
    label: standardizedTo
    cardinality: "1..*"
    bidirectional: true  # ← Makes edge reversible
```

### **Keyboard Shortcuts** (Coming Soon)

- `R` - Reverse selected edge
- `Shift+Click` - Select multiple edges
- `Ctrl+R` - Reverse all selected edges

---

## 📖 **Related Documentation**

- **Full Technical Docs**: `EDGE_DIRECTIONALITY_IMPLEMENTATION.md`
- **Layout Options Guide**: `LAYOUT_OPTIONS_QUICK_REFERENCE.md`
- **UML Viewer Manual**: `ADVANCED_LAYOUT_OPTIONS_COMPLETE.md`

---

## ✨ **Pro Tips**

1. **Exploring Complex Schemas**: Hover over edges systematically to understand relationships
2. **Debugging Ontologies**: Reverse edges to test semantic correctness
3. **Teaching/Presenting**: Use reversals to show relationship reciprocity
4. **Schema Design**: Click to test if relationships make sense both ways

---

**Feature Version**: v1.0.0  
**Last Updated**: November 24, 2025  
**Status**: ✅ Production-Ready