tegwick
2d516b205a
- Add DocumentNavigator UI element for document navigation across viewing and editing modes - Implement lazy loading approach where control appears immediately but navigation content builds on-demand - Position controls on left side following UI convention for consistent navigation experience - Add scroll spy functionality for current section detection - Include responsive design with mobile auto-hide - Create comprehensive development guardrails to prevent JavaScript corruption - Add JavaScript validation tool for syntax error detection 🤖 Generated with [Claude Code](https://claude.ai/code) Co-Authored-By: Claude <noreply@anthropic.com>
81 lines
2.2 KiB
Markdown
81 lines
2.2 KiB
Markdown
# Development Guardrails
|
|
|
|
## JavaScript Code Principles
|
|
|
|
### 1. No Inline JavaScript in Python
|
|
**NEVER write JavaScript code directly from Python code**
|
|
|
|
❌ **Wrong:**
|
|
```python
|
|
script = f"""
|
|
function myFunction() {{
|
|
console.log("Hello {name}");
|
|
}}
|
|
"""
|
|
```
|
|
|
|
✅ **Correct:**
|
|
```python
|
|
# Load from external files only
|
|
components = [
|
|
'js/core/section-manager.js',
|
|
'js/components/debug-panel.js',
|
|
'js/components/document-controls.js'
|
|
]
|
|
```
|
|
|
|
### 2. Why This Rule Exists
|
|
- **Quoting Problems**: String escaping in Python corrupts JavaScript
|
|
- **Syntax Errors**: Template literals and complex JS break when embedded
|
|
- **Maintainability**: JS code should be in .js files for proper tooling
|
|
- **Architecture**: Follows the established modular component system
|
|
|
|
### 3. Proper Approach
|
|
1. Create separate `.js` files in `markitect/static/js/components/`
|
|
2. Load them via `_get_clean_editor_scripts()`
|
|
3. Wire up components in the initialization script only
|
|
|
|
## Testing and Validation
|
|
|
|
### 1. Always Validate Generated HTML
|
|
- Check that HTML files actually render content
|
|
- Validate JavaScript syntax before deployment
|
|
- Test both viewing and editing modes
|
|
|
|
### 2. Detect JavaScript Errors Programmatically
|
|
- Run syntax validation on generated JS
|
|
- Check for common error patterns
|
|
- Fail fast when JS is malformed
|
|
|
|
### 3. Manual Testing Backup
|
|
- If automated checks pass but functionality fails
|
|
- Open generated HTML in browser
|
|
- Check console for runtime errors
|
|
- Report specific error messages
|
|
|
|
## Architecture Principles
|
|
|
|
### 1. Separation of Concerns
|
|
- Python: File generation, template management
|
|
- JavaScript: UI components, interaction logic
|
|
- HTML: Structure and content only
|
|
|
|
### 2. Modular Component System
|
|
- Each UI component in separate file
|
|
- Lazy loading where appropriate
|
|
- Clear dependency management
|
|
|
|
### 3. Error Handling
|
|
- Graceful degradation when components fail
|
|
- Clear error messages for debugging
|
|
- Fallback modes when possible
|
|
|
|
## Breaking These Rules
|
|
|
|
If you find yourself writing JavaScript in Python strings:
|
|
1. **STOP** - Step back and reconsider
|
|
2. Create a proper component file instead
|
|
3. Use the existing component loading system
|
|
4. Add validation to catch the issue early
|
|
|
|
These guardrails exist because we've seen the problems when they're violated. |