markitect-main/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

• 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.