mirror of
https://github.com/The-Low-Code-Foundation/OpenNoodl.git
synced 2026-01-11 06:42:57 +01:00
feat(topology): shelve Topology Map panel due to visual quality issues
- Disable Topology Map panel in router.setup.ts - Comment out panel registration (line ~85) - Add comprehensive SHELVED.md documentation explaining: * Why feature was shelved (SVG text layout complexity, visual quality) * What was implemented (graph analysis, folder aggregation, etc.) * Lessons learned and better approaches for future * Alternative enhancement suggestions - Code remains in codebase for potential future revival - Recommend React Flow or HTML/CSS approach instead of SVG
This commit is contained in:
Richard Osborne
@@ -0,0 +1,186 @@
|
||||
# Topology Map Panel - SHELVED
|
||||
|
||||
**Date Shelved:** April 1, 2026
|
||||
**Status:** ⏸️ Disabled / Shelved for Future Development
|
||||
**Reason:** Visual quality issues and complex layout problems
|
||||
|
||||
---
|
||||
|
||||
## Why This Feature Was Shelved
|
||||
|
||||
The Topology Map Panel was an ambitious attempt to visualize project structure at the folder/component level with automatic layout, color-coded grouping, and interactive features. After multiple iterations attempting to fix visual bugs, the feature was shelved due to:
|
||||
|
||||
### Primary Issues
|
||||
|
||||
1. **SVG Text Layout Complexity**
|
||||
|
||||
- SVG doesn't support automatic text wrapping or flow layout like HTML
|
||||
- Attempts to use `<foreignObject>` for text wrapping created more problems than it solved
|
||||
- Dynamic card heights based on content proved difficult to coordinate across multiple elements
|
||||
- Text positioning calculations were fragile and broke easily
|
||||
|
||||
2. **Visual Quality Problems**
|
||||
|
||||
- Text overlapping despite multiple fix attempts
|
||||
- Inconsistent spacing and padding across cards
|
||||
- Poor readability of folder/component information
|
||||
- Layout looked "worse than before" after attempted improvements
|
||||
|
||||
3. **Fundamental Design Challenges**
|
||||
- Mixing SVG rendering with HTML-like text layout expectations
|
||||
- Complex coordinate calculations for dynamic content
|
||||
- Difficulty achieving consistent visual polish
|
||||
|
||||
---
|
||||
|
||||
## What Was Implemented
|
||||
|
||||
Despite being shelved, significant work was completed:
|
||||
|
||||
### Working Features
|
||||
|
||||
- ✅ **Component-level dependency graph analysis** (`utils/graphAnalysis/`)
|
||||
- ✅ **Folder aggregation logic** to group components by directory
|
||||
- ✅ **Semantic tier assignment** (pages → features → integrations → UI → utilities)
|
||||
- ✅ **Folder type detection** with color-coded styling
|
||||
- ✅ **Component X-Ray integration** for detailed component stats
|
||||
- ✅ **Pan/zoom canvas** with mouse wheel and drag controls
|
||||
- ✅ **Folder drilldown** (double-click to see components inside)
|
||||
- ✅ **Trigger Chain Debugger** integration
|
||||
|
||||
### Partially Working
|
||||
|
||||
- ⚠️ **Card rendering** - Basic structure works, but visuals are poor
|
||||
- ⚠️ **Text layout** - Titles wrap, but other text doesn't properly adjust
|
||||
- ⚠️ **Dynamic heights** - Attempted but caused more issues
|
||||
|
||||
### Not Implemented
|
||||
|
||||
- ❌ **Draggable cards** with position persistence (infrastructure exists, not integrated)
|
||||
- ❌ **Sticky notes** for annotations
|
||||
- ❌ **Drilldown with back navigation** (UI pattern not designed)
|
||||
- ❌ **Top-level component expansion** (attempted but made things worse)
|
||||
|
||||
---
|
||||
|
||||
## Code Location
|
||||
|
||||
The complete implementation exists in:
|
||||
|
||||
```
|
||||
packages/noodl-editor/src/editor/src/views/panels/TopologyMapPanel/
|
||||
├── TopologyMapPanel.tsx # Main panel container
|
||||
├── components/
|
||||
│ ├── TopologyMapView.tsx # SVG canvas with pan/zoom
|
||||
│ ├── FolderNode.tsx # Folder card rendering
|
||||
│ ├── ComponentNode.tsx # Component card rendering
|
||||
│ ├── FolderEdge.tsx # Connections between folders
|
||||
│ └── *.module.scss # Styling (color-coded)
|
||||
├── hooks/
|
||||
│ ├── useFolderGraph.ts # Builds folder graph from project
|
||||
│ ├── useFolderLayout.ts # Positions folders in tiers
|
||||
│ ├── useTopologyGraph.ts # Component-level graph (legacy)
|
||||
│ └── useDraggable.ts # Drag-and-drop (not integrated)
|
||||
└── utils/
|
||||
├── graphAnalysis/ # Dependency analysis (✅ solid)
|
||||
├── folderAggregation.ts # Group components into folders
|
||||
├── folderTypeDetection.ts # Classify folder types
|
||||
├── tierAssignment.ts # Semantic layout tiers
|
||||
├── folderColors.ts # Color schemes per type
|
||||
├── componentStats.ts # Extract component metadata
|
||||
├── folderCardHeight.ts # Dynamic height calculation
|
||||
├── topologyPersistence.ts # Save custom positions
|
||||
└── snapToGrid.ts # Grid snapping utility
|
||||
```
|
||||
|
||||
**Registration:** Commented out in `router.setup.ts` (line ~85)
|
||||
|
||||
---
|
||||
|
||||
## Lessons Learned
|
||||
|
||||
### What Worked Well
|
||||
|
||||
1. **Graph analysis utilities** - The dependency analysis code is solid and reusable
|
||||
2. **Semantic tier system** - Automatically categorizing folders by purpose works well
|
||||
3. **Color-coded folder types** - Visual distinction by folder purpose is effective
|
||||
4. **Component X-Ray** - Detailed component stats were valuable
|
||||
|
||||
### What Didn't Work
|
||||
|
||||
1. **SVG for complex UI** - SVG is great for diagrams, poor for rich text and layout
|
||||
2. **Attempting HTML-like layout in SVG** - Fighting against SVG's strengths
|
||||
3. **Dynamic card heights** - Too many interdependent calculations, too fragile
|
||||
4. **Scope creep** - Feature kept growing in complexity
|
||||
|
||||
### Better Approaches for Future Attempts
|
||||
|
||||
1. **Use HTML/CSS for cards** - Render cards as HTML `<div>`s absolutely positioned on a canvas
|
||||
2. **Canvas API for connections** - Use Canvas 2D API for drawing edges between cards
|
||||
3. **React Flow or similar library** - Don't reinvent node graph visualization
|
||||
4. **Start with minimal viable version** - Fixed-size cards, no fancy features
|
||||
5. **Focus on clarity over features** - One clear view mode, not multiple view modes
|
||||
|
||||
---
|
||||
|
||||
## Related Successful Features
|
||||
|
||||
These features from the same phase ARE working and enabled:
|
||||
|
||||
- ✅ **Component X-Ray Panel** (`VIEW-002`) - Shows detailed component information
|
||||
- ✅ **Trigger Chain Debugger** (`VIEW-003`) - Visualizes event chains
|
||||
|
||||
Both use simpler rendering approaches (HTML/CSS) and focused scopes.
|
||||
|
||||
---
|
||||
|
||||
## If You Want to Revive This Feature
|
||||
|
||||
### Recommended Approach
|
||||
|
||||
1. **Start from scratch with React Flow**
|
||||
|
||||
- Use `reactflow` library (or similar) for node graph visualization
|
||||
- Let the library handle layout, pan/zoom, connections
|
||||
- Focus on data preparation, not rendering
|
||||
|
||||
2. **Simplify the UI**
|
||||
|
||||
- Fixed-height cards with consistent layout
|
||||
- Simple text labels (no fancy wrapping)
|
||||
- Clear, minimal styling
|
||||
|
||||
3. **One view mode only**
|
||||
|
||||
- Either folder-level OR component-level, not both
|
||||
- No drilldown - just switch between two separate panels
|
||||
|
||||
4. **Incremental delivery**
|
||||
- Phase 1: Basic graph visualization (read-only)
|
||||
- Phase 2: Interaction (click to navigate)
|
||||
- Phase 3: Customization (drag, notes, etc.)
|
||||
|
||||
### Alternative: Enhance Existing Tools
|
||||
|
||||
Instead of building a new visualization, enhance existing panels:
|
||||
|
||||
- **Components Panel** - Add folder tree view with stats
|
||||
- **Component X-Ray** - Add visual dependency graph
|
||||
- **Search Panel** - Add "show all uses" graph view
|
||||
|
||||
---
|
||||
|
||||
## Status Summary
|
||||
|
||||
**Disabled:** April 1, 2026
|
||||
**Reason:** Visual quality issues after multiple fix attempts
|
||||
**Decision:** Shelve feature, code remains in codebase but not accessible in UI
|
||||
**Next Steps:** Consider alternative approaches or simpler enhancements to existing panels
|
||||
|
||||
---
|
||||
|
||||
**See Also:**
|
||||
|
||||
- `REMAINING-WORK-INDEX.md` - What was planned but not completed
|
||||
- `CRITICAL-BUGS.md` - The visual bugs that led to shelving
|
||||
- `BUGFIX-CHANGELOG.md` - Fix attempts that didn't resolve the issues
|
||||
@@ -22,7 +22,7 @@ import { NodeReferencesPanel } from './views/panels/NodeReferencesPanel/NodeRefe
|
||||
import { ProjectSettingsPanel } from './views/panels/ProjectSettingsPanel/ProjectSettingsPanel';
|
||||
import { PropertyEditor } from './views/panels/propertyeditor';
|
||||
import { SearchPanel } from './views/panels/search-panel/search-panel';
|
||||
import { TopologyMapPanel } from './views/panels/TopologyMapPanel';
|
||||
// import { TopologyMapPanel } from './views/panels/TopologyMapPanel'; // Disabled - shelved feature
|
||||
import { TriggerChainDebuggerPanel } from './views/panels/TriggerChainDebuggerPanel';
|
||||
import { UndoQueuePanel } from './views/panels/UndoQueuePanel/UndoQueuePanel';
|
||||
import { VersionControlPanel_ID } from './views/panels/VersionControlPanel';
|
||||
@@ -79,14 +79,16 @@ export function installSidePanel({ isLesson }: SetupEditorOptions) {
|
||||
panel: SearchPanel
|
||||
});
|
||||
|
||||
SidebarModel.instance.register({
|
||||
experimental: true,
|
||||
id: 'topology',
|
||||
name: 'Topology',
|
||||
order: 3,
|
||||
icon: IconName.Navigate,
|
||||
panel: TopologyMapPanel
|
||||
});
|
||||
// Topology Map Panel - Disabled (shelved for future development)
|
||||
// See: dev-docs/tasks/phase-4-canvas-visualisation-views/VIEW-001-topology-map/SHELVED.md
|
||||
// SidebarModel.instance.register({
|
||||
// experimental: true,
|
||||
// id: 'topology',
|
||||
// name: 'Topology',
|
||||
// order: 3,
|
||||
// icon: IconName.StructureCircle,
|
||||
// panel: TopologyMapPanel
|
||||
// });
|
||||
|
||||
SidebarModel.instance.register({
|
||||
experimental: true,
|
||||
|
||||
Reference in New Issue
Block a user