diff --git a/dev-docs/reference/LEARNINGS.md b/dev-docs/reference/LEARNINGS.md index f31173a..2b17c32 100644 --- a/dev-docs/reference/LEARNINGS.md +++ b/dev-docs/reference/LEARNINGS.md @@ -4,6 +4,91 @@ This document captures important discoveries and gotchas encountered during Open --- +## 🎨 Node Color Scheme Must Match Defined Colors (Jan 11, 2026) + +### The Undefined Colors Crash: When Node Picker Can't Find Color Scheme + +**Context**: TASK-012 Blockly Integration - Logic Builder node caused EditorNode component to crash with "Cannot read properties of undefined (reading 'text')" when trying to render in the node picker. + +**The Problem**: Node definition used `color: 'purple'` which doesn't exist in Noodl's color scheme system. The EditorNode component expected a valid color scheme object but received `undefined`, causing the crash. + +**Root Cause**: Noodl has a fixed set of color schemes defined in `nodelibraryexport.js`. Using a non-existent color name causes the node picker to pass `undefined` for the colors prop, breaking the UI. + +**The Broken Pattern**: + +```javascript +// ❌ WRONG - 'purple' is not a defined color scheme +const LogicBuilderNode = { + name: 'Logic Builder', + category: 'Logic', + color: 'purple' // ☠️ Doesn't exist! Causes crash + // ... +}; +``` + +**The Correct Pattern**: + +```javascript +// ✅ RIGHT - Use defined color schemes +const LogicBuilderNode = { + name: 'Logic Builder', + category: 'CustomCode', + color: 'javascript' // ✓ Exists and works + // ... +}; +``` + +**Available Color Schemes** (from `nodelibraryexport.js`): + +| Color Name | Visual Color | Use Case | +| ------------ | ------------ | ----------------------- | +| `visual` | Blue | Visual/UI nodes | +| `data` | Green | Data nodes | +| `javascript` | Pink/Magenta | Custom code nodes | +| `component` | Purple | Component utility nodes | +| `default` | Gray | Generic/utility nodes | + +**Critical Rules**: + +1. **Always use an existing color scheme name** - Check nodelibraryexport.js for valid values +2. **Match similar node categories** - Look at Expression/Function nodes for custom code +3. **Test in node picker immediately** - Color crashes prevent the picker from opening + +**How to Verify**: + +```bash +# Find color definitions +grep -A 20 "colors: {" packages/noodl-runtime/src/nodelibraryexport.js + +# Search for similar nodes' color usage +grep "color:" packages/noodl-runtime/src/nodes/std-library/*.js +``` + +**Common Mistakes**: + +- Using descriptive names like `'purple'`, `'red'`, `'custom'` - these don't exist +- Assuming color names match visual appearance - `'javascript'` is pink, not beige +- Forgetting that `category` and `color` serve different purposes + +**Symptoms**: + +- EditorNode crash: "Cannot read properties of undefined" +- Node picker fails to open +- Console shows errors about colors.text, colors.headerHighlighted +- SVG icon errors (side effect of missing color scheme) + +**Time Lost**: 30 minutes debugging what appeared to be an unrelated React component issue + +**Location**: + +- Fixed in: `packages/noodl-runtime/src/nodes/std-library/logic-builder.js` +- Color definitions: `packages/noodl-runtime/src/nodelibraryexport.js` (lines 165-225) +- Task: Phase 3 TASK-012 Blockly Integration + +**Keywords**: color scheme, node picker, EditorNode crash, undefined colors, nodelibraryexport, color validation, node registration, custom nodes + +--- + ## ⚙️ Runtime Node Method Structure (Jan 11, 2026) ### The Invisible Method: Why prototypeExtensions Methods Aren't Accessible from Inputs diff --git a/dev-docs/tasks/phase-3-editor-ux-overhaul/TASK-012-blockly-integration/CHANGELOG.md b/dev-docs/tasks/phase-3-editor-ux-overhaul/TASK-012-blockly-integration/CHANGELOG.md index 0228193..0a9917e 100644 --- a/dev-docs/tasks/phase-3-editor-ux-overhaul/TASK-012-blockly-integration/CHANGELOG.md +++ b/dev-docs/tasks/phase-3-editor-ux-overhaul/TASK-012-blockly-integration/CHANGELOG.md @@ -80,12 +80,23 @@ Track all changes made during implementation. - Code generation implemented for basic Noodl API access - Ready to proceed with Phase B (Logic Builder Node) +**Testing Result:** ✅ Node successfully tested + +- Node appears in Custom Code category +- Node can be added to canvas +- No errors or crashes +- Proper color scheme (pink/magenta) + +**Bugfix Applied:** Fixed color scheme crash + +- Changed `color: 'purple'` to `color: 'javascript'` +- Changed `category: 'Logic'` to `category: 'CustomCode'` +- Matches Expression node pattern + **Next Steps:** -- Test Blockly rendering in the editor -- Create Logic Builder runtime node definition -- Implement I/O detection from workspace -- Build modal editor integration +- ✅ Phase B1 complete and tested +- 🚀 Moving to Phase C: Tab System Prototype --- @@ -95,16 +106,10 @@ Track all changes made during implementation. **Changes:** -- +- **Files Modified:** -**Files Modified:** +- **Notes:** -- - -**Notes:** - -- - ---- +- *** (Continue adding sessions as work progresses) diff --git a/dev-docs/tasks/phase-3-editor-ux-overhaul/TASK-012-blockly-integration/PHASE-B1-COMPLETE.md b/dev-docs/tasks/phase-3-editor-ux-overhaul/TASK-012-blockly-integration/PHASE-B1-COMPLETE.md index 26efadc..cabc77b 100644 --- a/dev-docs/tasks/phase-3-editor-ux-overhaul/TASK-012-blockly-integration/PHASE-B1-COMPLETE.md +++ b/dev-docs/tasks/phase-3-editor-ux-overhaul/TASK-012-blockly-integration/PHASE-B1-COMPLETE.md @@ -1,6 +1,6 @@ # Phase B1 Complete: Logic Builder Node Registration -**Status:** ✅ Complete - Ready for Manual Testing +**Status:** ✅ Complete - Tested and Working! **Date:** 2026-01-11 @@ -52,7 +52,7 @@ ## Manual Testing Checkpoint -### Test 1: Node Appears in Picker ✅ READY +### Test 1: Node Appears in Picker ✅ PASSED **Steps:** @@ -69,7 +69,7 @@ - Node description: "Build logic visually with blocks" - Search tags work: "blockly", "visual", "logic", "blocks", "nocode" -### Test 2: Node Can Be Added to Canvas ✅ READY +### Test 2: Node Can Be Added to Canvas ✅ PASSED **Steps:** @@ -206,4 +206,21 @@ Please provide feedback before we proceed to Phase C! --- -**Next Step:** Run `npm run dev` and verify the node appears in the picker. +**Testing Result:** ✅ All tests passed! Node works correctly. + +--- + +## 🐛 Bugfix Applied + +**Issue Found:** EditorNode crash with "Cannot read properties of undefined (reading 'text')" + +**Root Cause:** Used `color: 'purple'` which doesn't exist in Noodl's color scheme system. + +**Fix Applied:** Changed to `color: 'javascript'` to match Expression node pattern. + +**Git Commit:** `8039791` - fix(blockly): Fix Logic Builder node color scheme crash + +--- + +**Phase B1 Status:** ✅ COMPLETE AND TESTED +**Next Phase:** Phase C - Tab System Prototype