ObsiViewer/docs/GRAPH/GRAPH_SETTINGS_INSTALLATION.md

# Graph Settings Installation Guide

## 🚀 Getting Started

This guide helps you verify and test the Graph Settings feature.

## ✅ Pre-Installation Checklist

Before testing, ensure you have:

- [x] Node.js installed (v16+)
- [x] npm or yarn
- [x] ObsiViewer source code
- [x] A test vault with some markdown files

## 📦 Files Verification

Ensure these files exist in your project:

### Core Files
```
src/app/graph/
├── graph-settings.types.ts
├── graph-settings.service.ts
├── graph-runtime-adapter.ts
└── ui/
    ├── settings-button.component.ts
    ├── settings-panel.component.ts
    └── sections/
        ├── filters-section.component.ts
        ├── groups-section.component.ts
        ├── display-section.component.ts
        └── forces-section.component.ts
```

### Updated Files
```
src/components/graph-view-container/graph-view-container.component.ts
src/components/graph-view/graph-view.component.ts
server/index.mjs
```

### Documentation
```
docs/
├── GRAPH_SETTINGS.md
├── GRAPH_SETTINGS_QUICK_START.md
└── GRAPH_SETTINGS_INSTALLATION.md
GRAPH_SETTINGS_IMPLEMENTATION.md
```

## 🏗️ Installation Steps

### 1. Install Dependencies

No new dependencies needed! The feature uses existing Angular and D3 libraries.

```bash
# If starting fresh
npm install
```

### 2. Build the Application

```bash
npm run build
```

### 3. Start the Server

```bash
npm start
```

The server will start on `http://localhost:4000` (or your configured port).

### 4. Open in Browser

Navigate to `http://localhost:4000` and open the graph view.

## 🧪 Testing the Feature

### Quick Smoke Test (5 minutes)

1. **Open Graph View**
   - Navigate to the graph view in ObsiViewer
   - You should see a gear icon (⚙️) in the top-right corner

2. **Open Settings Panel**
   - Click the gear icon
   - Panel should slide in from the right
   - Four sections should be visible: Filters, Groups, Display, Forces

3. **Test Filters**
   - Type in the search box → graph should filter
   - Toggle "Tags" → tag nodes should disappear/appear
   - Toggle "Orphans" → orphan nodes should disappear/appear

4. **Test Groups**
   - Click "New group"
   - Change the color
   - Enter query: `tag:#yourtag` (use a tag from your vault)
   - Nodes with that tag should change color

5. **Test Display**
   - Toggle "Arrows" → arrows should appear/disappear on links
   - Move "Node size" slider → nodes should grow/shrink
   - Move "Link thickness" slider → links should thicken/thin
   - Click "Animate" → graph should restart simulation

6. **Test Forces**
   - Move any force slider → graph layout should change
   - Nodes should move to new positions

7. **Test Persistence**
   - Make some changes
   - Reload the page
   - Settings should be preserved

8. **Test File Creation**
   - Check your vault directory
   - Confirm `.obsidian/graph.json` exists
   - Open it → should contain your settings

### Detailed Testing (30 minutes)

#### Test Filters Section

```typescript
// Expected behavior for each filter:

// Search
1. Type "test" → only nodes with "test" in title appear
2. Clear search → all nodes reappear

// Tags
1. Uncheck "Tags" → nodes starting with # disappear
2. Check "Tags" → tag nodes reappear

// Attachments
1. Uncheck "Attachments" → .pdf, .png, etc. disappear
2. Check "Attachments" → attachments reappear

// Existing files only
1. Check "Existing files only" → broken links (unresolved) disappear
2. Uncheck → unresolved links reappear

// Orphans
1. Uncheck "Orphans" → nodes with no connections disappear
2. Check "Orphans" → orphan nodes reappear
```

#### Test Groups Section

```typescript
// Color group testing:

1. Add 3 groups with different colors
2. Set queries:
   - Group 1: "tag:#work" → red
   - Group 2: "tag:#personal" → blue
   - Group 3: "file:test" → green
3. Verify nodes match colors
4. Duplicate a group → should create copy
5. Delete a group → nodes should revert to default color
6. Change query → matching nodes should update color immediately
```

#### Test Display Section

```typescript
// Display testing:

1. Arrows:
   - Toggle OFF → no arrows on links
   - Toggle ON → arrows point in link direction

2. Text fade threshold:
   - Move to -3 → text fades earlier
   - Move to 0 → default fade
   - Move to 3 → text fades later

3. Node size:
   - Move to 0.25 → tiny nodes
   - Move to 1.0 → default size
   - Move to 3.0 → large nodes

4. Link thickness:
   - Move to 0.25 → thin links
   - Move to 1.0 → default thickness
   - Move to 3.0 → thick links

5. Animate:
   - Click → simulation should restart
   - Nodes should rearrange
```

#### Test Forces Section

```typescript
// Forces testing:

1. Center force (0-2):
   - 0 → nodes spread out
   - 1 → moderate centering
   - 2 → strong pull to center

2. Repel force (0-20):
   - 0 → nodes can overlap
   - 10 → default repulsion
   - 20 → strong push apart

3. Link force (0-2):
   - 0 → links don't constrain
   - 1 → default spring force
   - 2 → strong pull together

4. Link distance (20-300):
   - 20 → very tight spacing
   - 250 → default distance
   - 300 → wide spacing
```

#### Test Persistence

```typescript
// Persistence testing:

1. Make changes in UI
2. Wait 300ms (debounce)
3. Check vault/.obsidian/graph.json → changes saved
4. Edit file manually → UI updates in ~2 seconds
5. Reload page → settings preserved
6. Check .obsidian/graph.json.bak → backup exists
```

## 🔍 Verification Checklist

### UI Verification
- [ ] Gear icon visible in graph view
- [ ] Gear icon rotates on hover
- [ ] Panel slides in smoothly
- [ ] All sections visible and collapsible
- [ ] All controls functional
- [ ] Close button works
- [ ] Esc key closes panel
- [ ] Backdrop click closes (mobile)

### Functionality Verification
- [ ] Search filters nodes
- [ ] All toggles work
- [ ] Color groups apply colors
- [ ] Sliders update in real-time
- [ ] Animate restarts simulation
- [ ] Force sliders affect layout
- [ ] Reset section works
- [ ] Reset all works

### Persistence Verification
- [ ] graph.json created in .obsidian/
- [ ] Settings save within 250ms
- [ ] Settings persist after reload
- [ ] External edits reload in UI
- [ ] Backup file (.bak) created
- [ ] Invalid JSON handled gracefully

### Integration Verification
- [ ] GET /api/vault/graph returns config
- [ ] PUT /api/vault/graph saves config
- [ ] Conflict detection works (409)
- [ ] Atomic writes prevent corruption
- [ ] Server logs no errors

### Responsive Verification
- [ ] Desktop: 400px panel width
- [ ] Mobile: full-screen panel
- [ ] Panel scrolls if content overflows
- [ ] Touch events work on mobile
- [ ] Keyboard navigation works

### Accessibility Verification
- [ ] Tab navigation works
- [ ] Enter/Space activate controls
- [ ] Esc closes panel
- [ ] ARIA labels present
- [ ] Focus visible on controls
- [ ] Screen reader friendly

## 🐛 Common Issues & Solutions

### Issue: Gear Icon Not Appearing

**Solution:**
```typescript
// Check if components are imported in graph-view-container
import { GraphSettingsButtonComponent } from '../../app/graph/ui/settings-button.component';

// Verify it's in imports array
imports: [
  // ...
  GraphSettingsButtonComponent
]
```

### Issue: Settings Not Saving

**Solution:**
1. Check browser console for errors
2. Verify `.obsidian` directory exists
3. Check file permissions
4. Verify server is running
5. Check server logs for errors

### Issue: Panel Not Opening

**Solution:**
```typescript
// Check if panel component is imported
import { GraphSettingsPanelComponent } from '../../app/graph/ui/settings-panel.component';

// Check signal is defined
settingsPanelOpen = signal(false);

// Check template has panel
<app-graph-settings-panel
  [isOpen]="settingsPanelOpen()"
  (close)="closeSettingsPanel()">
</app-graph-settings-panel>
```

### Issue: Colors Not Applying

**Solution:**
1. Check GraphRuntimeAdapter is imported
2. Verify nodeColors is passed to GraphDisplayOptions
3. Check getNodeColor() method exists in graph-view component
4. Verify SVG uses [attr.fill]="getNodeColor(node)"

### Issue: External Changes Not Detected

**Solution:**
1. Check polling interval (default 2 seconds)
2. Verify server is watching vault directory
3. Check file watcher is enabled
4. Review server logs for file system events

## 📝 Development Tips

### Debugging

```typescript
// Enable service logging
constructor() {
  this.saveQueue.pipe(
    tap(patch => console.log('Saving:', patch)),
    debounceTime(250)
  ).subscribe(/* ... */);
}

// Log config changes
effect(() => {
  console.log('Config updated:', this.config());
});

// Log API calls
console.log('Loading config from API...');
```

### Testing Locally

```bash
# Start with watch mode
npm run dev

# View server logs
npm start 2>&1 | tee server.log

# Test API directly
curl http://localhost:4000/api/vault/graph

# Test write
curl -X PUT http://localhost:4000/api/vault/graph \
  -H "Content-Type: application/json" \
  -d '{"showArrow": true}'
```

### Performance Monitoring

```typescript
// Monitor debounce
console.time('save-debounce');
this.settingsService.save({ showArrow: true });
// Wait 250ms
console.timeEnd('save-debounce'); // Should show ~250ms

// Monitor render
effect(() => {
  console.time('graph-render');
  const data = this.filteredGraphData();
  console.timeEnd('graph-render');
  console.log('Nodes:', data.nodes.length);
});
```

## 🎯 Next Steps

After verifying everything works:

1. **Test with Real Data**: Use your actual vault
2. **Customize**: Adjust colors, filters, forces to your liking
3. **Share**: Create presets for your team
4. **Extend**: Add new features (see Future Enhancements in main docs)

## 📚 Additional Resources

- [Full Documentation](./GRAPH_SETTINGS.md)
- [Quick Start Guide](./GRAPH_SETTINGS_QUICK_START.md)
- [Implementation Summary](../GRAPH_SETTINGS_IMPLEMENTATION.md)

## 💬 Support

If you encounter issues:

1. Check browser console for errors
2. Check server logs
3. Review this installation guide
4. Check the troubleshooting section in main docs
5. Create an issue with:
   - Browser version
   - Node version
   - Error messages
   - Steps to reproduce

## ✅ Installation Complete!

Once all tests pass, you're ready to use the Graph Settings feature! 🎉

Enjoy customizing your graph view! 📊🎨