feat: complete clean editor implementation with comprehensive UI framework

Major architectural improvements and feature enhancements: ## Core Features Added - ✨ Custom status modal system replacing browser alerts with theme-consistent branding - ✨ HTML generation dogtag with timestamp and username linking - ✨ All document links now open in new tabs without triggering edit mode - ✨ Comprehensive UI framework documentation (UserInterfaceFramework.md) ## Architecture Improvements - 🔧 Complete cleanup of document_manager.py - removed 2000+ lines of legacy code - 🔧 Clean wrapper implementation maintaining backward compatibility - 🔧 Enhanced database integration with proper front matter parsing - 🔧 Improved AST processing and cache file generation ## UI/UX Enhancements - 🎨 Theme-aware modal dialogs with proper CSS styling and accessibility - 🎨 Consistent CSS class naming conventions across all UI components - 🎨 Enhanced link behavior for better document navigation - 🎨 Professional status information display ## Developer Experience - 📝 Comprehensive UI component documentation for future development - 🧪 Updated test suite to work with clean implementation - 🧪 Fixed multiple test compatibility issues - 🧪 Enhanced error handling and validation ## Technical Details - Added store_document method to CleanDocumentManager - Enhanced ingest_file method with proper title extraction - Implemented theme-consistent modal overlay patterns - Added --nodogtag CLI option for clean output when needed - Fixed CSS escape sequences and JavaScript syntax issues This release establishes a solid foundation for the clean editor architecture while maintaining full backward compatibility with existing functionality. 🤖 Generated with [Claude Code](https://claude.ai/code) Co-Authored-By: Claude <noreply@anthropic.com>
2025-10-28 03:50:21 +01:00
parent 3e16793615
commit 86689c451c
9 changed files with 879 additions and 2300 deletions
--- a/UserInterfaceFramework.md
+++ b/UserInterfaceFramework.md
@@ -0,0 +1,338 @@
+# User Interface Framework Documentation
+
+## Overview
+
+This document defines the canonical terminology and specifications for all UI components in the Markitect markdown editor interface. This framework establishes a common vocabulary for interface evolution discussions and future development.
+
+## Component Architecture
+
+The editor interface consists of 6 main components organized in layers:
+
+### Layer Priority (Z-Index)
+1. **Toast Notifications** (z-index: 10001) - Highest priority
+2. **Editor Floating Action Panel** (z-index: 1000) - High priority
+3. **Modal Dialogs** (z-index: 999) - Modal layer
+4. **Inline Section Editors** (z-index: 100) - Contextual editing
+5. **Document Canvas** (z-index: 1) - Content layer
+6. **Background** (z-index: 0) - Base layer
+
+---
+
+## 1. Editor Floating Action Panel
+
+**Component Name**: `Editor`
+**Type**: Floating action panel with status indicator
+**Location**: Top-right corner (fixed positioning)
+
+### Description
+A persistent control hub providing document-level actions and real-time status feedback. Always visible and contextually aware of editing state.
+
+### Technical Specifications
+- **Container ID**: `ui-edit-floater`
+- **CSS Classes**: `ui-edit-floater-panel`
+- **Position**: `position: fixed; top: 20px; right: 20px;`
+- **Z-Index**: 1000
+- **Update Frequency**: Status refreshes every 2 seconds via `setInterval`
+
+### Components
+1. **Header Section**
+   - **Title**: "📝 Editor" (emoji + text)
+   - **Status Display**: Dynamic text showing current state
+
+2. **Action Buttons**
+   - **💾 Save Document** (green accept style)
+   - **🔄 Reset All** (orange reset style)
+   - **📊 Show Status** (grey secondary style)
+
+### Status States
+- `"Ready"` - Default idle state
+- `"Editing [N] section(s)"` - Active editing in progress
+- `"[N] section(s) modified"` - Unsaved changes exist
+- `"All sections saved ✓"` - All work is saved (with checkmark)
+
+### Theme Integration
+- Colors and styling adapt to selected UI theme (standard, greyscale, electric, psychedelic)
+- Header text color matches theme text color
+- Panel background follows theme panel styling
+
+---
+
+## 2. Toast Notification System
+
+**Component Name**: `Toast`
+**Type**: Auto-dismissing temporary status messages
+**Location**: Top-center (horizontally centered)
+
+### Description
+Provides immediate visual feedback for user actions through temporary, non-blocking messages that appear and automatically disappear.
+
+### Technical Specifications
+- **Position**: `position: fixed; top: 20px; left: 50%; transform: translateX(-50%);`
+- **Z-Index**: 10001 (highest priority)
+- **Auto-Dismiss**: 3 seconds
+- **Max Width**: 400px
+- **Animation**: Smooth appear/disappear
+
+### Message Types
+1. **Success Toast** (green `#28a745`)
+   - "Document saved as: [filename]"
+   - "✂️ Section split into [N] sections!"
+
+2. **Info Toast** (blue `#007acc`)
+   - "Document reset to original structure"
+
+3. **Error Toast** (red `#dc3545`)
+   - Error condition messages
+
+### Visual Styling
+- **Shape**: Rounded corners (4px border-radius)
+- **Typography**: White text, 14px font size, center aligned
+- **Shadow**: `0 2px 8px rgba(0,0,0,0.2)`
+- **Padding**: `12px 20px`
+
+---
+
+## 3. Document Canvas
+
+**Component Name**: `Document` or `Canvas`
+**Type**: Main content rendering area
+**Location**: Central content area
+
+### Description
+The primary workspace where markdown content is rendered and made interactive for editing. Displays content as formatted HTML while providing editing affordances.
+
+### Technical Specifications
+- **Container ID**: `markdown-content`
+- **CSS Classes**: Content uses semantic classes (`ui-edit-section`)
+- **Layout**: Responsive, centered with max-width constraints
+- **Interaction**: Click-to-edit paradigm
+
+### Section Elements
+Each content section is individually interactive:
+- **Hover Effect**: Subtle background (`rgba(0, 0, 0, 0.02)`) and border hint
+- **Click Target**: Entire section area is clickable
+- **Visual Feedback**: Smooth transitions (0.2s ease)
+- **Section Types**: Headings, paragraphs, lists, code blocks, blockquotes
+
+### Content Rendering
+- **Primary**: Uses `marked.js` for markdown parsing
+- **Fallback**: Basic HTML conversion if library fails
+- **Graceful Degradation**: Always displays content, even with errors
+
+---
+
+## 4. Inline Section Editor
+
+**Component Name**: `Section Editor` or `Inline Editor`
+**Type**: Contextual editing widget
+**Location**: Replaces section content during editing
+
+### Description
+A contextual editing interface that appears when a section is activated for editing. Provides textarea input and action controls for section-level operations.
+
+### Technical Specifications
+- **Container CSS**: `ui-edit-inline-panel`
+- **Layout**: Horizontal flex layout (textarea + button column)
+- **Theme Integration**: Inherits floating panel styling from active UI theme
+- **Focus Management**: Auto-focus on textarea when activated
+
+### Components
+1. **Textarea**
+   - **CSS Classes**: `ui-edit-textarea ui-edit-textarea-main`
+   - **Font**: Monospace font family for code editing
+   - **Features**: Vertical resize, focus styling, theme-aware colors
+
+2. **Action Buttons** (vertical column)
+   - **✓ Accept** (`ui-edit-button-accept`) - Save changes
+   - **✗ Cancel** (`ui-edit-button-cancel`) - Discard changes
+   - **🔄 Reset** (`ui-edit-button-reset`) - Restore original content
+
+### Behavior
+- **Multi-Section**: Supports multiple concurrent section editing
+- **State Persistence**: Maintains editing state until explicitly resolved
+- **Keyboard Support**: Planned for future enhancement
+- **Auto-Split**: Automatically splits sections when new headings are added
+
+---
+
+## 5. Status Information Modal
+
+**Component Name**: `Status Modal` or `Info Dialog`
+**Type**: Modal dialog for comprehensive status display
+**Location**: Center screen (modal overlay)
+
+### Description
+Provides detailed information about the current editing session, including version info, document statistics, file details, and help documentation.
+
+### Current Implementation
+- **Method**: Browser native `alert()` (temporary solution)
+- **Trigger**: "📊 Show Status" button in floating action panel
+- **Content**: Multi-section formatted text
+
+### Information Sections
+1. **Application Header**
+   - Application name and version
+   - Git commit info and development status
+
+2. **File Information**
+   - Generated save filename
+   - Source filename
+   - Current URL
+
+3. **Document Statistics**
+   - Total sections count
+   - Modified sections count
+   - Currently editing sections count
+   - Unsaved changes indicator
+
+4. **Help Documentation**
+   - Section behavior explanation
+   - Editing controls reference
+   - Keyboard shortcuts (future)
+
+### Future Enhancement Plan
+**Target**: Replace browser alert with custom modal dialog
+- **Styling**: Theme-aware modal with proper typography
+- **Interaction**: Close button, better formatting
+- **Features**: Copy-to-clipboard, expandable sections
+- **Accessibility**: Proper ARIA labels, keyboard navigation
+
+---
+
+## 6. Confirmation Dialog
+
+**Component Name**: `Confirmation Dialog`
+**Type**: Modal confirmation for destructive actions
+**Location**: Center screen (modal overlay)
+
+### Description
+Provides user confirmation for potentially destructive operations that cannot be easily undone.
+
+### Current Implementation
+- **Method**: Browser native `confirm()` (temporary solution)
+- **Trigger**: "🔄 Reset All" button in floating action panel
+- **Message**: "Reset all content to original markdown? This will lose all edits and remove split sections."
+
+### Use Cases
+- **Reset All Sections**: Complete document reset to original state
+- **Future**: Delete operations, bulk changes, file operations
+
+### Future Enhancement Plan
+**Target**: Replace browser confirm with custom modal dialog
+- **Styling**: Theme-aware modal with clear action buttons
+- **Features**:
+  - Clear primary/secondary action buttons
+  - Detailed consequence explanation
+  - Optional "Don't ask again" for non-critical confirmations
+- **Accessibility**: Proper focus management, keyboard support
+
+---
+
+## Design Principles
+
+### 1. **Theme Consistency**
+All components must adapt to the selected UI theme:
+- **Standard**: Light grey palette with blue accents
+- **Greyscale**: Monochromatic grey scale
+- **Electric**: Dark blue with cyan/yellow accents and glow effects
+- **Psychedelic**: Vibrant gradient backgrounds with white text
+
+### 2. **Non-Blocking Interactions**
+- **Toast notifications**: Auto-dismiss, don't require user action
+- **Floating action panel**: Always accessible, doesn't block content
+- **Inline editors**: Contextual, don't interfere with other sections
+
+### 3. **Graceful Degradation**
+- **Content always visible**: Even if JavaScript fails
+- **Progressive enhancement**: Core functionality works without advanced features
+- **Fallback implementations**: Basic browser dialogs until custom implementations ready
+
+### 4. **Responsive Design**
+- **Mobile-first**: Components adapt to smaller screens
+- **Touch-friendly**: Appropriate touch targets and gestures
+- **Scalable**: Works across different zoom levels and resolutions
+
+### 5. **Accessibility**
+- **Keyboard navigation**: All interactive elements accessible via keyboard
+- **Screen reader support**: Proper ARIA labels and semantic markup
+- **High contrast**: Sufficient color contrast ratios in all themes
+- **Focus management**: Clear focus indicators and logical tab order
+
+---
+
+## Development Conventions
+
+### CSS Class Naming
+**Pattern**: `{scope}-{component}-{element}-{modifier}`
+
+**Scopes**:
+- `ui` - User interface elements
+- `md` - Mode (light/dark)
+- `dc` - Document content
+- `br` - Branding
+
+**Examples**:
+- `ui-edit-floater-panel`
+- `ui-edit-button-accept`
+- `ui-edit-textarea-main`
+- `ui-edit-section-frame`
+
+### JavaScript Event Naming
+**Pattern**: `{action}-{target}`
+
+**Examples**:
+- `edit-started`
+- `changes-accepted`
+- `section-split`
+- `content-updated`
+
+### Component State Management
+- **Centralized**: Section state managed by `SectionManager`
+- **Event-driven**: Components communicate via events
+- **Immutable updates**: State changes create new state objects
+- **Consistent**: Same patterns across all components
+
+---
+
+## Future Enhancement Roadmap
+
+### Phase 1: Modal System Replacement
+- Replace browser `alert()` and `confirm()` with custom implementations
+- Add proper theme integration and accessibility features
+- Implement keyboard navigation and focus management
+
+### Phase 2: Enhanced Interactions
+- Add keyboard shortcuts for common operations
+- Implement drag-and-drop section reordering
+- Add section templates and quick-insert functionality
+
+### Phase 3: Advanced Features
+- Multi-document editing with tabs
+- Real-time collaboration indicators
+- Advanced search and replace within sections
+- Export options beyond basic markdown
+
+### Phase 4: Performance Optimization
+- Virtual scrolling for large documents
+- Lazy loading of section editors
+- Optimized rendering for mobile devices
+- Advanced caching strategies
+
+---
+
+## Component Integration Matrix
+
+| Component | Theme Aware | Mobile Ready | Keyboard Nav | Touch Friendly | Accessible |
+|-----------|-------------|--------------|--------------|----------------|------------|
+| Editor Panel | ✅ Yes | ⚠️ Partial | ❌ Planned | ⚠️ Basic | ⚠️ Partial |
+| Toast System | ❌ No | ✅ Yes | ❌ N/A | ✅ Yes | ⚠️ Basic |
+| Document Canvas | ✅ Yes | ✅ Yes | ⚠️ Partial | ✅ Yes | ✅ Yes |
+| Section Editor | ✅ Yes | ⚠️ Partial | ⚠️ Basic | ⚠️ Basic | ⚠️ Partial |
+| Status Modal | ❌ No | ❌ No | ❌ No | ❌ No | ❌ No |
+| Confirmation | ❌ No | ❌ No | ❌ No | ❌ No | ❌ No |
+
+**Legend**: ✅ Full Support | ⚠️ Partial/Needs Work | ❌ Not Implemented
+
+---
+
+This framework provides the foundation for consistent UI development and evolution. All future interface changes should reference these component definitions and maintain the established patterns and conventions.