testdrive-jsui/docs/features/status-control.md

Status Control

Real-time document statistics and change tracking 📊

The Status Control provides comprehensive document analytics including word count, character count, reading time estimation, document structure analysis, and change tracking. Monitor your document metrics in real-time as you write and edit. Positioned in the east by default.

---

Overview

The Status Control continuously monitors your document and provides detailed statistics about content, structure, and reading metrics. Perfect for writers, editors, and content creators who need to track document metrics.

Position

• Default: East (e) - middle-right side
• Appearance: 📊 icon when collapsed
• Title: "Status"

Key Features

• 📊 Real-time statistics - Word/character count, reading time
• 📈 Change tracking - Visual indicators for increases/decreases
• 📐 Document structure - Paragraphs, headings, lists, images, links
• 🔄 Auto-refresh - Updates every 10 seconds automatically
• 📤 Export functionality - Download statistics as JSON

---

Configuration

Enable/Disable

new TestDriveJSUI({
    container: '#editor',
    controls: {
        statusControl: true  // Enable (default: true)
    }
});

Custom Position

new TestDriveJSUI({
    container: '#editor',
    controlPositions: {
        statusControl: 'e'  // East (default), or: nw, ne, se, s, sw, w
    }
});

---

Features

1. Content Statistics

Word Count

Shows total words in the document, calculated by splitting text on whitespace and filtering empty strings.

Display: Large, blue-colored number with change indicator

Example: 1,247 (+23) - Document has 1,247 words, increased by 23 since last update

Character Count

Total characters including spaces.

Display: Formatted with thousand separators

Also tracks: Characters without spaces (internal metric)

Reading Time

Estimated reading time in minutes based on average reading speed.

Calculation: Total words ÷ 200 words per minute (configurable)

Display: 5 min (+1) - Takes 5 minutes to read, increased by 1 minute

Tip: Useful for blog posts, articles, and documentation to estimate reader time investment

Sentence Count

Approximate sentence count based on punctuation (., !, ?).

Use case: Track writing complexity and paragraph length

---

2. Document Structure

The Status Control analyzes your document structure and counts:

Paragraphs

Total <p> elements in the rendered HTML.

Use case: Ensure proper document segmentation

Headings

Total headings (h1-h6) in the document.

Use case: Verify document outline and hierarchy

Tip: Good documents typically have 1 h1 and logical heading progression

Lists

Total lists (ordered and unordered).

Use case: Track enumeration and structured content

Images

Total images in the document.

Use case: Monitor visual content distribution

Links

Total hyperlinks in the document.

Use case: Track references and external resources

---

3. Change Tracking

Visual Indicators

Changes since last update are shown with:

Positive changes (increases):

• Green color: #28a745
• Plus sign: (+5)
• Indicates growth in that metric

Negative changes (decreases):

• Red color: #dc3545
• Minus sign: (-3)
• Indicates reduction in that metric

No change: No indicator shown

Example Display

Words: 1,247 (+23)
Characters: 6,543 (+145)
Reading Time: 6 min
Sentences: 89 (+2)

The green numbers show the document grew by 23 words, 145 characters, and 2 sentences.

---

4. Actions

🔄 Refresh

Manually refresh statistics immediately.

Usage:

• Click "🔄 Refresh" button
• Shows "✅ Updated" confirmation for 1 second

When to use:

• After making significant edits
• When you want immediate feedback
• To see updated change indicators

Note: Statistics auto-refresh every 10 seconds, so manual refresh is optional

📊 Export

Export statistics to JSON file for external analysis.

Usage:

• Click "📊 Export" button
• Downloads: document-stats-YYYY-MM-DD.json

File contents:

{
  "timestamp": "2025-12-16T14:30:52.123Z",
  "document": {
    "title": "My Document",
    "url": "http://localhost:8080/editor.html"
  },
  "statistics": {
    "characters": 6543,
    "charactersNoSpaces": 5421,
    "words": 1247,
    "sentences": 89,
    "paragraphs": 34,
    "headings": 12,
    "lists": 5,
    "images": 3,
    "links": 18,
    "readingTimeMinutes": 6
  },
  "metadata": {
    "wordsPerMinute": 200,
    "analysisDate": "2025-12-16T14:30:52.123Z"
  }
}

Use cases:

• Track document evolution over time
• Compare statistics across multiple documents
• Generate reports for clients or stakeholders
• Integrate with external analytics tools

---

5. Auto-Refresh

The Status Control automatically refreshes every 10 seconds to keep statistics current.

Behavior:

• Silent background updates
• Preserves change tracking between updates
• Minimal performance impact
• Continues while control is expanded or collapsed

Disable auto-refresh: Not currently supported via config (always enabled)

---

Examples

Basic Usage

const editor = new TestDriveJSUI({
    container: '#editor',
    markdown: '# My Document\\n\\nThis is a sample paragraph.',
    controls: {
        statusControl: true
    }
});

Custom Position (Top-Right)

// Move status control to northeast (top-right)
const editor = new TestDriveJSUI({
    container: '#editor',
    controlPositions: {
        statusControl: 'ne'  // Top-right corner
    }
});

Blog Post Writer Setup

// Emphasize word count for blog writing
const editor = new TestDriveJSUI({
    container: '#editor',
    controls: {
        editControl: true,     // Save and export
        statusControl: true,   // Track word count goal
        contentsControl: false,
        debugControl: false
    }
});

// Monitor word count for target goal
setInterval(() => {
    const stats = editor.statusControl.stats;
    const targetWords = 1500;

    if (stats.words >= targetWords) {
        console.log(`🎉 Goal reached! ${stats.words} words written.`);
    } else {
        const remaining = targetWords - stats.words;
        console.log(`✍️ Keep writing! ${remaining} words to go.`);
    }
}, 5000);

Export Statistics for Reporting

const editor = new TestDriveJSUI({ container: '#editor' });

// Programmatically export stats
document.getElementById('report-btn').addEventListener('click', () => {
    // Refresh to get latest stats
    editor.statusControl.refreshStats();

    // Export to JSON
    setTimeout(() => {
        editor.statusControl.exportStats();
    }, 100);
});

---

API Reference

Properties

Access via editor.statusControl:

const statusCtrl = editor.statusControl;

// Current statistics object
statusCtrl.stats = {
    characters: 6543,
    charactersNoSpaces: 5421,
    words: 1247,
    sentences: 89,
    paragraphs: 34,
    headings: 12,
    lists: 5,
    images: 3,
    links: 18,
    readingTimeMinutes: 6
};

// Previous statistics (for change tracking)
statusCtrl.previousStats = { /* ... */ };

// Last update timestamp
statusCtrl.lastUpdateTime = 1702742452123;

// Reading speed setting (words per minute)
statusCtrl.wordsPerMinute = 200;  // Adjustable

// Auto-refresh interval ID
statusCtrl.updateInterval = 12345;

Methods

const statusCtrl = editor.statusControl;

// Analyze document and update statistics
statusCtrl.analyzeDocument();
// Returns: stats object

// Calculate changes since last update
const changes = statusCtrl.calculateChanges();
// Returns: { words: { current, previous, change, hasChanged }, ... }

// Format statistics as HTML
const html = statusCtrl.formatStatistics();
// Returns: HTML string

// Refresh stats and update display
statusCtrl.refreshStats();

// Export statistics to JSON file
statusCtrl.exportStats();

// Calculate readability score (Flesch Reading Ease)
const readability = statusCtrl.calculateReadabilityScore();
// Returns: { score: 65, level: 'Standard' }

// Configuration
statusCtrl.config.position = 'e';   // Compass position
statusCtrl.config.icon = '📊';      // Panel icon
statusCtrl.config.title = 'Status'; // Panel title
statusCtrl.isExpanded;              // true if expanded

Readability Levels

The calculateReadabilityScore() method returns:

Score Range	Level	Description
90-100	Very Easy	5th grade level
80-89	Easy	6th grade level
70-79	Fairly Easy	7th grade level
60-69	Standard	8th-9th grade level
50-59	Fairly Difficult	10th-12th grade level
30-49	Difficult	College level
0-29	Very Difficult	College graduate level

Note: Readability scoring uses simplified Flesch Reading Ease formula with approximated syllable counts.

---

Advanced Usage

Custom Reading Speed

const editor = new TestDriveJSUI({ container: '#editor' });

// Adjust for faster readers (250 words per minute)
editor.statusControl.wordsPerMinute = 250;
editor.statusControl.refreshStats();

// Or slower readers (150 words per minute)
editor.statusControl.wordsPerMinute = 150;
editor.statusControl.refreshStats();

Programmatic Access

const editor = new TestDriveJSUI({ container: '#editor' });

// Get current word count
const wordCount = editor.statusControl.stats.words;
console.log(`Current word count: ${wordCount}`);

// Get reading time
const readingTime = editor.statusControl.stats.readingTimeMinutes;
console.log(`Estimated reading time: ${readingTime} minutes`);

// Check if document structure is balanced
const stats = editor.statusControl.stats;
const avgParasPerHeading = stats.paragraphs / stats.headings;
console.log(`Average paragraphs per section: ${avgParasPerHeading.toFixed(1)}`);

Change Detection

const editor = new TestDriveJSUI({ container: '#editor' });

// Monitor specific changes
const original = editor.statusControl.stats.words;

// ... user edits document ...

editor.statusControl.refreshStats();
const current = editor.statusControl.stats.words;
const delta = current - original;

if (delta > 0) {
    console.log(`Added ${delta} words`);
} else if (delta < 0) {
    console.log(`Removed ${Math.abs(delta)} words`);
}

Custom Auto-Refresh Interval

const editor = new TestDriveJSUI({ container: '#editor' });

// Stop default 10-second refresh
clearInterval(editor.statusControl.updateInterval);

// Set custom 5-second refresh
editor.statusControl.updateInterval = setInterval(() => {
    editor.statusControl.refreshStats();
}, 5000);

---

Troubleshooting

Statistics Not Updating

Problem: Numbers don't change after editing

Solutions:

1. Click "🔄 Refresh" button manually
2. Check if auto-refresh is running: editor.statusControl.updateInterval
3. Verify StatusControl is loaded: typeof StatusControl !== 'undefined'
4. Check browser console for JavaScript errors

Incorrect Word Count

Problem: Word count seems wrong

Causes & Solutions:

1. Whitespace handling: Multiple spaces count as one separator (correct behavior)
2. HTML tags: Only text content is counted, not HTML markup
3. Code blocks: Code is included in word count
4. Special characters: Punctuation is included in words

Manual verification:

// Get exact text being counted
const contentArea = document.querySelector('#markitect-content');
const text = contentArea.textContent;
const words = text.trim().split(/\s+/).filter(w => w.length > 0);
console.log('Words:', words.length, words);

Export Button Not Working

Problem: Clicking export does nothing

Solutions:

1. Check browser's download settings
2. Verify pop-up/download permissions
3. Test programmatically: editor.statusControl.exportStats()
4. Check browser console for errors
5. Try different browser

Reading Time Seems Wrong

Problem: Estimated reading time is too short/long

Solution: Adjust reading speed

// For technical content (slower reading)
editor.statusControl.wordsPerMinute = 150;

// For light reading (faster)
editor.statusControl.wordsPerMinute = 250;

// Refresh to recalculate
editor.statusControl.refreshStats();

Factors affecting reading time:

• Technical complexity
• Reader expertise level
• Language proficiency
• Content density

---

Best Practices

For Writers

1. Set word count goals - Monitor progress toward target lengths
2. Track reading time - Ensure articles fit time budgets (e.g., 5-minute reads)
3. Balance structure - Use heading/paragraph ratios to check organization
4. Export regularly - Save statistics to track writing productivity over time

For Editors

1. Monitor changes - Use change indicators to track editing impact
2. Verify readability - Check calculateReadabilityScore() for target audience
3. Structure analysis - Ensure proper heading hierarchy and paragraph distribution
4. Compare versions - Export stats before/after editing to quantify improvements

For Developers

1. Integrate with backend - Send statistics to server for analytics
2. Custom thresholds - Set alerts for minimum/maximum word counts
3. Programmatic access - Use API for automated quality checks
4. Performance - Monitor update frequency if handling very large documents

Example integration:

const editor = new TestDriveJSUI({ container: '#editor' });

// Auto-save with statistics
editor.on('save', async (data) => {
    const stats = editor.statusControl.stats;

    await fetch('/api/documents', {
        method: 'POST',
        headers: { 'Content-Type': 'application/json' },
        body: JSON.stringify({
            markdown: data.markdown,
            statistics: stats,
            timestamp: new Date().toISOString()
        })
    });
});

---

Performance Considerations

For Large Documents (10,000+ words)

Impact: Auto-refresh every 10 seconds may cause lag

Solutions:

1. Increase refresh interval:

   clearInterval(editor.statusControl.updateInterval);
   editor.statusControl.updateInterval = setInterval(() => {
       editor.statusControl.refreshStats();
   }, 30000); // 30 seconds instead
   

2. Disable auto-refresh, use manual only:

   clearInterval(editor.statusControl.updateInterval);
   editor.statusControl.updateInterval = null;
   // User clicks Refresh button when needed
   

3. Lazy calculation - only analyze visible sections

Memory Usage

Statistics use minimal memory (< 1KB). Change tracking stores two copies of stats object. No memory leaks if control is properly destroyed via destroy().

---

Related Features

• Edit Control - Save/export document
• Contents Control - Navigate document structure
• Section Editing - Triggers statistics updates

---

See Also:

• API Reference
• Examples

---

Version: 1.0.0 Last Updated: 2025-12-16