ObsiViewer/docs/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:

• Node.js installed (v16+)
• npm or yarn
• ObsiViewer source code
• 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.

# If starting fresh
npm install

2. Build the Application

npm run build

3. Start the Server

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

// 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

// 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

// 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

// 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

// 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:

// 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:

// 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

// 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

# 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

// 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
• Quick Start Guide
• Implementation Summary

💬 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! 📊🎨