From bb9f4dfcc83a8e7af820501994af211f6a29a6e0 Mon Sep 17 00:00:00 2001 From: Richard Osborne Date: Sun, 4 Jan 2026 20:07:25 +0100 Subject: [PATCH] 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 --- .../VIEW-001-topology-map/SHELVED.md | 186 ++++++++++++++++++ .../src/editor/src/router.setup.ts | 20 +- 2 files changed, 197 insertions(+), 9 deletions(-) create mode 100644 dev-docs/tasks/phase-4-canvas-visualisation-views/VIEW-001-topology-map/SHELVED.md diff --git a/dev-docs/tasks/phase-4-canvas-visualisation-views/VIEW-001-topology-map/SHELVED.md b/dev-docs/tasks/phase-4-canvas-visualisation-views/VIEW-001-topology-map/SHELVED.md new file mode 100644 index 0000000..8a4395c --- /dev/null +++ b/dev-docs/tasks/phase-4-canvas-visualisation-views/VIEW-001-topology-map/SHELVED.md @@ -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 `` 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 `
`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 diff --git a/packages/noodl-editor/src/editor/src/router.setup.ts b/packages/noodl-editor/src/editor/src/router.setup.ts index df2aae9..2728e18 100644 --- a/packages/noodl-editor/src/editor/src/router.setup.ts +++ b/packages/noodl-editor/src/editor/src/router.setup.ts @@ -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,