feat: implement unified DocumentNavigator with lazy loading for all modes
- 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>
This commit is contained in:
81
GUARDRAILS.md
Normal file
81
GUARDRAILS.md
Normal file
@@ -0,0 +1,81 @@
|
||||
# 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.
|
||||
Reference in New Issue
Block a user