Implement complete API routes and mock authentication for full CMS functionality

- Add comprehensive nested route structure with proper authentication layers - Implement UpdateContent and ReorderCollectionItems handlers with repository pattern - Add automatic mock JWT token fetching for seamless development workflow - Restore content editing and collection reordering functionality broken after database refactoring - Provide production-ready authentication architecture with development convenience - Enable full CMS operations in browser with proper CRUD and bulk transaction support
2025-10-16 21:23:17 +02:00
parent bbf728d110
commit 87b78a4a69
11 changed files with 1095 additions and 218 deletions
--- a/INSERTR-CONTENT-FEATURE.md
+++ b/INSERTR-CONTENT-FEATURE.md
@@ -0,0 +1,397 @@
+# .insertr-content Feature Specification
+
+**Status**: Design Phase  
+**Version**: 0.1.0  
+**Last Updated**: October 16, 2025
+
+## Executive Summary
+
+The `.insertr-content` feature extends Insertr's CMS capabilities to handle long-form, complex content like blog posts and articles. While `.insertr` handles individual elements and `.insertr-add` manages collections, `.insertr-content` provides a rich text editing experience for larger content blocks that require sophisticated formatting, structure, and content management workflows.
+
+## Current State Analysis
+
+### Existing Insertr Architecture
+- **StyleAwareEditor**: Rich text editing with automatic style detection
+- **HTML Preservation Engine**: Perfect fidelity editing maintaining all attributes  
+- **Style Detection Engine**: Converts nested elements to formatting options
+- **Collection Management**: `.insertr-add` for dynamic content collections
+- **Static Site Enhancement**: Build-time content injection and file processing
+
+### Gaps for Blog/Article Content
+- No unified interface for long-form content editing
+- Limited content structure management (headings, sections, media)
+- No publishing workflow (drafts, scheduling, SEO)
+- Missing blog-specific features (excerpts, metadata, relationships)
+
+## Feature Requirements
+
+### Core Functionality
+
+#### 1. Rich Content Editor
+```html
+<!-- Developer Implementation -->
+<article class="insertr-content blog-post">
+  <h1>Existing Title</h1>
+  <p>Content with <strong class="brand-highlight">custom styling</strong></p>
+  <blockquote class="testimonial">Styled quotes</blockquote>
+</article>
+```
+
+**Capabilities:**
+- Inline editing mode with contextual toolbar
+- Style detection and preservation of developer CSS classes
+- Block-based content management (headings, paragraphs, lists, quotes)
+- Media insertion and management
+- Markdown shortcuts for power users
+
+#### 2. Content Structure Management
+- Automatic heading hierarchy detection and validation
+- Drag & drop block reordering
+- Content outline/table of contents generation
+- Block templates for common patterns
+- Live content structure preview
+
+#### 3. Enhanced Writing Experience
+- Distraction-free full-screen mode
+- Auto-save with conflict resolution
+- Word count and reading time estimation
+- Typography optimization for readability
+- Smart formatting (quotes, dashes, spacing)
+
+### Static Site Integration
+
+#### 1. Enhanced File Processing
+```bash
+# Enhance existing pages
+insertr enhance blog-post.html --output dist/blog-post.html
+
+# Generate content-driven pages
+insertr enhance templates/ --output dist/ --generate-content
+```
+
+#### 2. Template-Based Generation
+```yaml
+# insertr.yaml
+content_types:
+  blog_posts:
+    template: "templates/blog-post.html"
+    output_pattern: "blog/{slug}.html"
+    fields:
+      title: text
+      content: insertr-content
+      excerpt: text
+      published_date: date
+      author: text
+```
+
+#### 3. Content Storage Strategy
+```go
+type BlogPost struct {
+    ID           string    `json:"id"`
+    Slug         string    `json:"slug"`
+    Title        string    `json:"title"`
+    Content      string    `json:"content"`      // Rich HTML from .insertr-content
+    Excerpt      string    `json:"excerpt"`
+    Author       string    `json:"author"`
+    PublishedAt  time.Time `json:"published_at"`
+    Status       string    `json:"status"`       // draft, published, archived
+    Template     string    `json:"template"`
+    Metadata     JSON      `json:"metadata"`     // SEO, social media, etc.
+}
+```
+
+### Blog Management Features
+
+#### 1. Publishing Workflow
+- Draft → Review → Published status management
+- Content scheduling for future publication
+- Version history with rollback capabilities
+- Content approval workflow for teams
+
+#### 2. SEO and Metadata
+- Meta title and description management
+- Open Graph and Twitter Card optimization
+- Structured data (JSON-LD) generation
+- Reading time and content analysis
+- Heading structure validation
+
+#### 3. Content Organization
+- Categories and tags management
+- Related content suggestions
+- Content series/collections
+- Author management and attribution
+
+## Technical Architecture
+
+### Frontend Components
+
+#### 1. ContentEditor Class
+```javascript
+class ContentEditor extends StyleAwareEditor {
+  constructor(element, options) {
+    super(element, {
+      mode: 'content',
+      showOutline: true,
+      enableMarkdownShortcuts: true,
+      autoSave: true,
+      ...options
+    });
+  }
+  
+  // Content-specific methods
+  insertBlock(type) { /* Insert heading, quote, code block */ }
+  reorderBlocks() { /* Drag & drop reordering */ }
+  generateOutline() { /* TOC generation */ }
+  validateStructure() { /* SEO and accessibility checks */ }
+}
+```
+
+#### 2. Enhanced UI Components
+- **Block Selector**: Visual insertion of headings, quotes, media
+- **Outline Panel**: Collapsible content structure navigator
+- **Style Panel**: Context-aware formatting options
+- **Media Browser**: Integrated asset management
+- **Metadata Editor**: SEO and social media optimization
+
+#### 3. Content Structure Engine
+```javascript
+class ContentStructureEngine extends StyleDetectionEngine {
+  analyzeContentBlocks(element) {
+    // Detect semantic structure (headings, sections, articles)
+    // Generate content outline and navigation
+    // Identify reusable content patterns
+  }
+  
+  validateContentStructure(structure) {
+    // SEO heading hierarchy validation
+    // Accessibility compliance checks
+    // Content readability analysis
+  }
+}
+```
+
+### Backend Enhancements
+
+#### 1. Content Generation Pipeline
+```go
+func (e *Enhancer) EnhanceWithContentGeneration(inputDir, outputDir string) error {
+    // 1. Enhance existing HTML files (current behavior)
+    err := e.EnhanceDirectory(inputDir, outputDir)
+    if err != nil {
+        return err
+    }
+    
+    // 2. Generate content-driven pages
+    return e.generateContentPages(outputDir)
+}
+```
+
+#### 2. Template Processing
+- Mustache/Handlebars template engine integration
+- Content type-specific template routing
+- Dynamic page generation from database content
+- Static asset optimization and copying
+
+#### 3. Content API Extensions
+- Blog post CRUD operations
+- Content publishing workflow endpoints
+- SEO metadata management
+- Media upload and optimization
+- Version control and history tracking
+
+## Implementation Phases
+
+### Phase 1: Core Rich Text Editor (4-6 weeks)
+**Deliverables:**
+- Basic `.insertr-content` class recognition
+- Inline editing with floating toolbar
+- Style detection and preservation
+- Auto-save functionality
+- Block-based content management
+
+**Success Criteria:**
+- Edit long-form content in-place
+- Preserve all existing CSS styling
+- Support basic rich text formatting
+- Maintain HTML structure integrity
+
+### Phase 2: Content Structure & Management (4-6 weeks)
+**Deliverables:**
+- Content outline generation
+- Drag & drop block reordering
+- Media insertion and management
+- Heading hierarchy validation
+- SEO metadata editing
+
+**Success Criteria:**
+- Navigate content via outline
+- Reorder content blocks visually
+- Insert and manage images/media
+- Validate content structure
+- Edit meta descriptions and titles
+
+### Phase 3: Static Site Integration (6-8 weeks)
+**Deliverables:**
+- Template-based page generation
+- Content type configuration
+- Publishing workflow
+- Build process integration
+- Documentation and examples
+
+**Success Criteria:**
+- Generate blog pages from templates
+- Publish/unpublish content
+- Integrate with existing build tools
+- Complete documentation
+- Demo implementations
+
+### Phase 4: Advanced Features (6-8 weeks)
+**Deliverables:**
+- Collaborative editing
+- Advanced SEO tools
+- Content relationships
+- Performance optimizations
+- Third-party integrations
+
+**Success Criteria:**
+- Multiple editors simultaneously
+- Comprehensive SEO analysis
+- Related content suggestions
+- Sub-second editor load times
+- Hugo/Jekyll/Gatsby examples
+
+## Potential Challenges & Mitigation Strategies
+
+### Technical Challenges
+
+#### 1. **Complex Content Structure Preservation**
+**Challenge**: Maintaining perfect HTML fidelity while providing rich editing
+**Mitigation**: 
+- Extend existing HTMLPreservationEngine
+- Comprehensive test suite for edge cases
+- Gradual rollout with fallback mechanisms
+
+#### 2. **Performance with Large Content**
+**Challenge**: Editor performance degrades with very long articles
+**Mitigation**:
+- Virtual scrolling for large documents
+- Lazy loading of editor features
+- Incremental parsing and rendering
+- Memory management optimizations
+
+#### 3. **Style Detection Complexity**
+**Challenge**: Complex CSS styling may not map well to editing interfaces
+**Mitigation**:
+- Configurable style mapping rules
+- Developer override mechanisms
+- Graceful degradation to basic formatting
+- Comprehensive style detection testing
+
+### User Experience Challenges
+
+#### 4. **Editor Complexity vs Simplicity**
+**Challenge**: Power users need advanced features, casual users need simplicity
+**Mitigation**:
+- Progressive disclosure of features
+- Configurable interface complexity
+- Role-based feature availability
+- Contextual help and onboarding
+
+#### 5. **Content Migration**
+**Challenge**: Moving existing blog content into Insertr system
+**Mitigation**:
+- Import tools for common formats (Markdown, HTML, WordPress)
+- Bulk migration utilities
+- Content validation and cleanup tools
+- Migration documentation and tutorials
+
+### Integration Challenges
+
+#### 6. **Static Site Generator Compatibility**
+**Challenge**: Different SSGs have different content conventions
+**Mitigation**:
+- Plugin architecture for SSG-specific adaptations
+- Standard export formats (Markdown, JSON, HTML)
+- Configuration templates for popular SSGs
+- Community-driven integration examples
+
+#### 7. **Build Process Integration**
+**Challenge**: Fitting into existing development workflows
+**Mitigation**:
+- CLI-first approach matching existing tools
+- CI/CD pipeline integration guides
+- Watch mode for development
+- Incremental build optimizations
+
+### Content Management Challenges
+
+#### 8. **Version Control and Conflicts**
+**Challenge**: Managing content changes across multiple editors and builds
+**Mitigation**:
+- Operational transformation for real-time collaboration
+- Clear conflict resolution interfaces
+- Audit trail for all content changes
+- Backup and recovery mechanisms
+
+#### 9. **SEO and Performance Balance**
+**Challenge**: Rich editing features may impact site performance
+**Mitigation**:
+- Minimal runtime overhead for visitors
+- Conditional loading of editing features
+- Static generation maintains performance
+- Performance monitoring and optimization
+
+## Success Metrics
+
+### User Adoption
+- Number of sites using `.insertr-content`
+- Content creation frequency
+- User retention and engagement
+- Community feedback and contributions
+
+### Technical Performance
+- Editor load time (target: <2 seconds)
+- Content save latency (target: <500ms)
+- Static site build impact (target: <10% increase)
+- Memory usage optimization
+
+### Content Quality
+- Content structure validation pass rate
+- SEO score improvements
+- Accessibility compliance metrics
+- User-reported content issues
+
+## Open Questions & Decisions Needed
+
+### Design Decisions
+1. **Block vs. Inline Editing**: Should we prioritize block-based editing (like Gutenberg) or seamless inline editing?
+2. **Markdown Support**: How much markdown compatibility should we maintain vs. pure HTML?
+3. **Template Engine**: Which template engine should we standardize on for content generation?
+
+### Technical Decisions
+1. **Database Schema**: How should we structure content types and metadata in the database?
+2. **API Design**: Should we extend existing APIs or create new content-specific endpoints?
+3. **Caching Strategy**: How do we handle content caching across the editing and static generation pipeline?
+
+### Integration Decisions
+1. **SSG Priority**: Which static site generators should we prioritize for integration?
+2. **Media Handling**: Should we build media management or integrate with existing solutions?
+3. **Deployment**: How do we handle automated deployments when content is published?
+
+## Next Steps
+
+1. **Technical Spike** (1 week): Prototype core editing interface with existing StyleAwareEditor
+2. **Design Review** (1 week): Validate UI/UX approach with user research
+3. **Architecture Review** (1 week): Finalize technical architecture and database schema
+4. **Phase 1 Kickoff**: Begin implementation of core rich text editor
+
+## References
+
+- [CLASSES.md](./CLASSES.md) - Current class system documentation
+- [StyleAwareEditor](./lib/src/ui/style-aware-editor.js) - Existing editor implementation
+- [HTMLPreservationEngine](./lib/src/utils/html-preservation.js) - Current preservation approach
+- [Content Enhancement Pipeline](./internal/content/enhancer.go) - Static site processing
+
+---
+
+*This document is a living specification that will evolve as we learn more about user needs and technical constraints. All stakeholders should contribute to its refinement.*