# Word Count-Based Logbook Progress Tracking

## Overview
The logbook progress tracking system has been updated to count only entries that meet the minimum word count requirement. Entries are stored in HTML format, so word counting properly strips HTML tags before counting.

## Changes Made

### 1. Controller Updates (`app/Http/Controllers/HomeController.php`)

**Modified Method:** `supervisorDashboard()`

#### Key Changes:
- Added `$minWordsPerReport` variable from `batch_offers.min_words_per_report` (defaults to 100 words)
- Created `$countWords` closure function that:
  - Strips HTML tags using `strip_tags()`
  - Removes extra whitespace with `preg_replace()`
  - Counts words using `str_word_count()`
- Updated entry filtering for both IDP1 and IDP2 to only count entries where:
  - Entry date falls within the week range
  - Word count >= minimum word requirement
- Added `minWordsPerReport` to the returned data array

#### Word Counting Logic:
```php
$countWords = function ($htmlContent) {
    // Strip HTML tags
    $text = strip_tags($htmlContent);
    // Remove extra whitespace
    $text = preg_replace('/\s+/', ' ', trim($text));
    // Count words
    return str_word_count($text);
};
```

#### Entry Validation:
```php
$validEntries = $student->logbookEntries->filter(function ($entry) use ($weekStart, $weekEnd, $countWords, $minWordsPerReport) {
    $entryDate = \Carbon\Carbon::parse($entry->entry_date);
    if (!$entryDate->between($weekStart, $weekEnd)) {
        return false;
    }
    
    // Count words in the description (HTML content)
    $wordCount = $countWords($entry->description ?? '');
    return $wordCount >= $minWordsPerReport;
});
```

### 2. View Updates (`resources/views/dashboard/supervisor.blade.php`)

#### Tooltip Updates:
- Changed tooltip text from: `"Week X: Y entries | Minimum: Z"`
- To: `"Week X: Y valid entries (≥100 words) | Minimum: Z"`
- Dynamically shows the minimum word requirement from batch offer settings

#### Legend Enhancement:
- Added informational text: "Only entries with minimum word count are counted"
- Includes file icon for visual clarity

## How It Works

### Progress Calculation:
1. **Week Range Calculation**: System divides IDP1 and IDP2 periods into weeks
2. **Entry Filtering**: For each week:
   - Fetches all logbook entries within date range
   - Strips HTML tags from `description` field
   - Counts words in plain text
   - Only includes entries with word count >= minimum requirement
3. **Badge Display**: 
   - Green (IDP1) or Blue (IDP2): Meets minimum number of reports
   - Red: Below minimum number of reports
4. **Count Display**: Shows only valid entries (those meeting word count)

### Visual Feedback:
- Hover over any week badge to see:
  - Number of valid entries
  - Minimum word requirement
  - Minimum number of reports needed

### Database Schema:
- Word count minimum is stored in `batch_offers.min_words_per_report`
- Defaults to 100 words if not set
- Can be configured per batch offer

## Example Scenarios

### Scenario 1: Student with short entries
- Student has 5 entries in Week 1
- 2 entries have 150+ words (valid)
- 3 entries have <100 words (invalid)
- **Display**: Badge shows "2" (only valid entries counted)

### Scenario 2: Minimum requirement check
- Minimum reports per week: 3
- Student has 2 valid entries (≥100 words)
- **Display**: Red badge showing "2" (below threshold)

### Scenario 3: Meeting requirements
- Minimum reports per week: 3
- Student has 4 valid entries (≥100 words)
- **Display**: Green/Blue badge showing "4" (meets threshold)

## Benefits

1. **Quality Control**: Ensures students write substantial content
2. **Accurate Progress**: Only meaningful entries count toward completion
3. **Transparency**: Tooltips clearly show requirements
4. **Flexibility**: Word count can be adjusted per batch offer
5. **HTML-Safe**: Properly handles rich text content

## Technical Notes

- HTML content is stripped using PHP's `strip_tags()` function
- Word counting uses `str_word_count()` which handles various text formats
- Whitespace normalization prevents inflated word counts
- All existing entries are retroactively validated against word count
- No database migration required (uses existing `description` field)

## Future Enhancements

Consider adding:
- Word count display in individual logbook entry views
- Real-time word counter in the entry editor
- Weekly word count statistics
- Export reports showing word count compliance