diff options
Diffstat (limited to 'js/baba-yaga/web/editor/README.md')
| -rw-r--r-- | js/baba-yaga/web/editor/README.md | 210 |
1 files changed, 210 insertions, 0 deletions
diff --git a/js/baba-yaga/web/editor/README.md b/js/baba-yaga/web/editor/README.md new file mode 100644 index 0000000..3cf7c5c --- /dev/null +++ b/js/baba-yaga/web/editor/README.md @@ -0,0 +1,210 @@ +# Baba Yaga Inline AST Editor + +A web-based structural editor for the Baba Yaga programming language, featuring real-time AST visualization and **inline tree editing** capabilities. + +## **Core Concept** + +This editor allows you to edit code structure directly through the Abstract Syntax Tree (AST) view. Instead of traditional forms, you can **double-click any element** in the tree to edit it inline, making structural editing intuitive and powerful. + +## **Key Features** + +### **Inline AST Editing** +- **Double-click to Edit**: Any node type, name, value, or parameter +- **Real-time Updates**: Changes sync immediately between AST and code editor +- **Action Buttons**: + (add child) and × (delete) for each node +- **Smart Scaffolding**: Add Function, When, or With expressions with one click + +### **Layout & UX** +- **Side-by-side Layout**: Code editor (50%) + AST tree editor (50%) +- **Output Panel**: Below both panels for execution results +- **Mobile Responsive**: Stacks vertically on smaller screens +- **Auto-parsing**: Code updates in real-time as you edit + +### **Bidirectional Synchronization** +- **AST ↔ Code Editor**: Always in sync +- **Real-time Parsing**: 500ms debounced parsing as you type +- **Visual Feedback**: Parse status indicators and error highlighting + +## **Architecture** + +The editor consists of several key components: + +- **Code Editor**: Text-based input for Baba Yaga code +- **AST Tree Editor**: Interactive tree view with inline editing +- **AST Synchronizer**: Manages bidirectional synchronization +- **Baba Yaga Parser**: Real language parser integration +- **Code Generator**: Converts modified AST back to code + +## **How to Use** + +### **Basic Workflow** +1. **Type Code** → See AST tree automatically generated +2. **Double-click** any node element to edit inline +3. **Click +** to add child nodes +4. **Click ×** to delete nodes +5. **Use + Function/When/With** buttons for quick scaffolding + +### **Inline Editing** +- **Node Types**: Double-click the type (e.g., "FunctionDeclaration") +- **Names & Values**: Double-click any name or value field +- **Parameters**: Double-click parameter names or types +- **Keyboard**: Enter to save, Escape to cancel + +### **Quick Add Elements** +- **+ Function**: Creates `newFunction : -> expression` +- **+ When**: Creates empty when expression structure +- **+ With**: Creates empty with header structure + +## **Development** + +### **Setup** +1. Ensure you have a web server running (e.g., `python3 -m http.server 8000`) +2. Open `index.html` in your browser +3. The editor will automatically load and parse any existing code + +### **Key Components** +- `editor.js`: Main editor class with inline editing logic +- `ast-synchronizer.js`: AST synchronization and code generation +- `main.js`: Application initialization and global utilities + +### **Adding New Features** +To extend the inline editing capabilities: + +1. **New Node Types**: Add to `createDefaultChildNode()` method +2. **Custom Editors**: Extend the inline editing methods +3. **Validation**: Add input validation in `finishEdit*` methods +4. **Code Generation**: Update the code generation logic + +## **Future Enhancements** + +- **Syntax Highlighting**: ✅ Baba Yaga language support (implemented!) +- **Advanced Pattern Matching**: Enhanced when expression editing +- **Type System Integration**: Better type inference and validation +- **Code Suggestions**: Intelligent autocomplete and suggestions +- **Refactoring Tools**: Automated code restructuring +- **Export/Import**: Save and load AST structures +- **Undo/Redo**: Track editing history +- **Drag & Drop**: Visual AST manipulation + +## **Technical Details** + +### **Inline Editing Implementation** +- **Event Delegation**: Handles all editing through centralized methods +- **Dynamic Input Fields**: Replace text with input boxes on interaction +- **AST Manipulation**: Direct tree structure modification +- **Real-time Sync**: Immediate updates between views + +### **Performance Optimizations** +- **Debounced Parsing**: 500ms delay to avoid excessive parsing +- **Selective Updates**: Only re-render changed sections +- **Memory Management**: Efficient AST node tracking + +### **Syntax Highlighting Features** +- **Custom Language Mode**: Full Baba Yaga syntax support +- **Token Recognition**: Keywords, types, functions, operators, numbers, strings +- **Smart Indentation**: Auto-indent for function bodies, when expressions, with headers +- **Theme Integration**: Monokai dark theme with custom Baba Yaga colors +- **Code Folding**: Collapsible code blocks for better organization + +## 🌟 **Why Inline Editing?** + +Traditional structural editors require switching between different forms and panels, which can be cumbersome. This inline approach: + +- **Reduces Context Switching**: Edit directly where you see the structure +- **Improves Workflow**: Faster iteration and experimentation +- **Enhances Understanding**: Visual connection between structure and code +- **Increases Productivity**: More intuitive editing experience + +## 📁 **File Structure** + +``` +web/editor/ +├── index.html # Main HTML with inline editor layout +├── styles.css # CSS with inline editing styles +├── js/ +│ ├── editor.js # Main editor with inline editing logic +│ ├── ast-synchronizer.js # AST sync and code generation +│ ├── baba-yaga-mode.js # Custom CodeMirror language mode +│ ├── main.js # Application initialization +│ └── tree-sitter-baba-yaga.js # Future grammar integration +└── README.md # This documentation +``` + +## 🎨 **Syntax Highlighting Colors** + +The editor provides rich syntax highlighting with a carefully chosen color scheme: + +- **Keywords** (`when`, `with`, `rec`, `in`): Purple (#c586c0) +- **Types** (`Int`, `String`, `Result`): Teal (#4ec9b0) +- **Functions** (function names): Yellow (#dcdcaa) +- **Builtins** (`map`, `filter`, `reduce`): Orange (#d7ba7d) +- **Operators** (`->`, `:`, `+`, `*`): White (#d4d4d4) +- **Numbers**: Green (#b5cea8) +- **Strings**: Red (#ce9178) +- **Comments**: Green (#6a9955) +- **Variables**: Blue (#9cdcfe) + +## **Development Commands** + +The editor provides several console commands for development: + +```javascript +// Get current AST +window.babaYagaEditorCommands.getAST() + +// Get current code +window.babaYagaEditorCommands.getCode() + +// Parse current code +window.babaYagaEditorCommands.parse() + +// Format current code +window.babaYagaEditorCommands.format() + +// Show AST in console +window.babaYagaEditorCommands.showAST() + +// Show code in console +window.babaYagaEditorCommands.showCode() +``` + +## 🔧 **Baba Yaga Language Support** + +### **Supported Constructs** +- **Function Declarations**: `name : params -> body` +- **Variable Declarations**: `name : value` +- **Basic Expressions**: Arithmetic, comparison, logical operators +- **Pattern Matching**: `when` expressions (basic support) +- **Local Bindings**: `with` headers (basic support) + +### **Language Features** +- **Currying**: Multiple arrow functions +- **Type Annotations**: Optional type declarations +- **Pattern Matching**: `when` expressions with multiple cases +- **Recursion**: `with rec` for mutually recursive functions +- **Immutability**: All data structures are immutable + +## 🚀 **Getting Started** + +1. **Clone the repository** and navigate to `web/editor/` +2. **Start a web server**: `python3 -m http.server 8000` +3. **Open in browser**: Navigate to `http://localhost:8000/web/editor/` +4. **Start editing**: Type Baba Yaga code or use the inline AST editor + +## 🤝 **Contributing** + +1. Fork the repository +2. Create a feature branch +3. Make your changes +4. Test thoroughly +5. Submit a pull request + +## 📄 **License** + +This project is part of the Baba Yaga language implementation. See the main project license for details. + +## 🙏 **Acknowledgments** + +- Inspired by functional programming language editors +- Built on modern web technologies +- Designed for educational and development use |