markitect-main/docs/development/UserInterfaceFramework.md

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 ✅ COMPLETED

• Method: Custom theme-aware modal dialog
• Trigger: "🔄 Reset All" button in floating action panel
• Message: "Reset all content to original markdown?"
• Warning: "This will permanently lose all edits and remove any split sections. This action cannot be undone."

Features Implemented

• Theme-Aware Styling: Adapts to all UI themes (standard, greyscale, electric, psychedelic)
• Clear Action Buttons:
  • Primary action: "Reset Document" (red danger button)
  • Secondary action: "Keep Changes" (grey cancel button)
• Enhanced UX:
  • Detailed consequence explanation with warning styling
  • Professional modal overlay with smooth animations
  • Proper focus management and accessibility
• Keyboard Support:
  • ESC key to cancel
  • Enter key to confirm
  • Tab navigation between buttons

Use Cases

• Reset All Sections: Complete document reset to original state
• Future: Extensible for delete operations, bulk changes, file operations

Technical Implementation

CSS Classes:

• .ui-edit-confirmation-modal - Modal container
• .ui-edit-confirmation-content - Main message
• .ui-edit-confirmation-warning - Warning section
• .ui-edit-confirmation-buttons - Button container
• .ui-edit-button-confirm - Danger action button
• .ui-edit-button-cancel - Cancel action button

JavaScript Method: showConfirmation(message, confirmText, cancelText, warningText)

• Returns Promise for async/await support
• Theme-consistent styling via layered theme system
• Proper event cleanup and accessibility features

---

7. Insert Mode Editor

Component Name: Insert Mode Editor Type: Structured editing mode with heading protection Location: Replaces section content during editing (contextual)

Description ✅ COMPLETED

A specialized editing mode that duplicates edit mode functionality while enforcing document structure integrity. Provides content editing with selective heading protection for levels 1-3, maintaining document outline consistency.

Current Implementation ✅ COMPLETED

• CLI Activation: markitect md-render document.md --insert
• Mode Detection: Uses MARKITECT_INSERT_MODE JavaScript flag
• Heading Protection: Levels 1-3 are read-only, displayed above content editor
• Content Editing: Full editing capability for content following protected headings

Features Implemented

• Structured Editing Interface:
  • Protected heading display (read-only) for levels 1-3
  • Content-only textarea for body text editing
  • Level 4+ headings remain fully editable
• Heading Protection Logic:
  • Visual distinction with warning-styled heading display
  • Prevents modification of heading text in protected sections
  • Server-side validation ensures heading integrity
• Section Management:
  • Automatic section splitting on new heading introduction
  • New heading sections inherit protection based on level
  • Maintains document structure during complex edits
• Theme Integration:
  • Adapts to all UI themes (standard, greyscale, electric, psychedelic)
  • Consistent styling with edit mode components
  • Special styling for protected heading display

Use Cases

• Document Structure Preservation: Maintain established outline while allowing content updates
• Collaborative Editing: Prevent accidental heading modifications in shared documents
• Template-Based Content: Edit content within predefined structural frameworks
• Controlled Authoring: Allow content contributions without structural changes

Technical Implementation

CLI Integration:

• --insert flag added to md-render command
• Mutually exclusive with --edit flag
• Validation prevents simultaneous mode activation

CSS Classes:

• .markitect-insert-mode - Body class for insert mode
• .ui-insert-protected-panel - Container for protected heading sections
• .ui-insert-heading-display - Read-only heading display component
• .ui-insert-content-editor - Content-only editing textarea

JavaScript Configuration:

const MARKITECT_INSERT_MODE = true;
const MARKITECT_EDITOR_CONFIG = {
    mode: 'insert',
    restrictedHeadingLevels: [1, 2, 3],
    // ... standard editor config
};

Section Enhancement:

• Section.detectHeadingLevel() - Identify heading levels 1-6
• Section.isProtectedHeading() - Check if heading is protected in current mode
• Section.getHeadingText() - Extract heading text for display
• Section.getHeadingContent() - Extract content after heading for editing

Validation Logic:

• Pre-acceptance validation ensures protected headings remain unchanged
• Error handling for attempted heading modifications
• Content reconstruction maintains heading + content structure

Behavioral Differences from Edit Mode

Feature	Edit Mode	Insert Mode
Heading Levels 1-3	✏️ Fully Editable	🔒 Read-Only Display
Heading Levels 4-6	✏️ Fully Editable	✏️ Fully Editable
Content Editing	✏️ Full Section	✏️ Content Only (for protected)
Section Splitting	✅ All Headings	✅ All Headings
New Heading Creation	✅ Unlimited	✅ With Level-Based Protection
Theme Support	✅ All Themes	✅ All Themes

Future Enhancements

• Configurable Protection Levels: Allow customization of which heading levels are protected
• Conditional Protection: Enable/disable protection based on section content or metadata
• Protection Indicators: Visual badges showing protection status in section list
• Bulk Mode Switching: Convert between edit and insert modes for existing documents

---

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
Insert Mode Editor	✅ Yes	⚠️ Partial	⚠️ Basic	⚠️ Basic	⚠️ Partial
Status Modal	❌ No	❌ No	❌ No	❌ No	❌ No
Confirmation	✅ Yes	✅ Yes	✅ Yes	✅ Yes	✅ Yes

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.