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<boolean> 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**:
```javascript
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.