documentation-hub 5.7.2

package/docs/implementation/List_Framework_Refactor_Plan.md

@@ -0,0 +1,336 @@
+# List Implementation Framework Refactoring Plan
+
+**Goal:** Replace custom XML injection with docxmlater framework methods
+**Benefit:** Simpler, more maintainable code using framework best practices
+**Status:** Planning Phase
+
+---
+
+## Executive Summary
+
+Replace ~180 lines of custom XML manipulation code with framework's built-in `standardizeBulletSymbols()` and `standardizeNumberedListPrefixes()` methods. This simplifies the codebase while maintaining all current functionality.
+
+**Note:** Font will remain Verdana for list symbols (not Calibri) - this is intentional for proper bullet character rendering in Word.
+
+---
+
+## Framework Methods to Use
+
+### 1. `doc.standardizeBulletSymbols(options)`
+
+**Purpose:** Standardize bullet list formatting across document
+**API:** `Document.d.ts:268-276`
+
+```typescript
+doc.standardizeBulletSymbols({
+  font: 'Verdana',
+  fontSize: 12,
+  color: '000000',
+  bold: true,
+});
+```
+
+### 2. `doc.standardizeNumberedListPrefixes(options)`
+
+**Purpose:** Standardize numbered list formatting across document
+**API:** `Document.d.ts:278-285`
+
+```typescript
+doc.standardizeNumberedListPrefixes({
+  font: 'Verdana',
+  fontSize: 12,
+  color: '000000',
+  bold: true,
+});
+```
+
+---
+
+## Files to Modify
+
+### WordDocumentProcessor.ts
+
+**Methods to DELETE:**
+
+1. `injectCompleteRunPropertiesToNumbering()` (lines 3133-3209) - 77 lines
+2. Calls to this method in:
+   - `applyBulletUniformity()` (line 2979)
+   - `applyNumberedUniformity()` (line 3071)
+
+**Methods to KEEP (but modify):**
+
+1. `injectIndentationToNumbering()` - Still needed for custom indentation from UI
+2. `applyBulletUniformity()` - Replace XML injection call with framework method
+3. `applyNumberedUniformity()` - Replace XML injection call with framework method
+4. `standardizeListPrefixFormatting()` - Can be simplified to use framework methods
+
+**Methods to REFACTOR:**
+
+1. `standardizeNumberingColors()` (lines 3343-3358) - Use framework methods instead of custom injection
+
+---
+
+## Refactoring Steps
+
+### Step 1: Update applyBulletUniformity()
+
+**Current (line 2979):**
+
+```typescript
+const injectionSuccess = await this.injectCompleteRunPropertiesToNumbering(doc, numId);
+if (injectionSuccess) {
+  this.log.debug('Applied 12pt bold black formatting to bullet list symbols');
+}
+```
+
+**Replace with:**
+
+```typescript
+const result = doc.standardizeBulletSymbols({
+  font: 'Verdana',
+  fontSize: 12,
+  color: '000000',
+  bold: true,
+});
+this.log.debug(`Standardized ${result.listsUpdated} bullet lists, ${result.levelsModified} levels`);
+```
+
+### Step 2: Update applyNumberedUniformity()
+
+**Current (line 3071):**
+
+```typescript
+const injectionSuccess = await this.injectCompleteRunPropertiesToNumbering(doc, numId);
+```
+
+**Replace with:**
+
+```typescript
+const result = doc.standardizeNumberedListPrefixes({
+  font: 'Verdana',
+  fontSize: 12,
+  color: '000000',
+  bold: true,
+});
+this.log.debug(
+  `Standardized ${result.listsUpdated} numbered lists, ${result.levelsModified} levels`
+);
+```
+
+### Step 3: Update standardizeNumberingColors()
+
+**Current (lines 3343-3358):**
+
+```typescript
+private async standardizeNumberingColors(doc: Document): Promise<boolean> {
+  try {
+    const success = await this.injectCompleteRunPropertiesToNumbering(doc);
+    if (success) {
+      this.log.debug('Standardized all numbering colors to black...');
+      return true;
+    }
+    return false;
+  } catch (error) {
+    this.log.warn('Unable to standardize numbering colors:', error);
+    return false;
+  }
+}
+```
+
+**Replace with:**
+
+```typescript
+private async standardizeNumberingColors(doc: Document): Promise<boolean> {
+  try {
+    const bulletResult = doc.standardizeBulletSymbols({ color: '000000', bold: true });
+    const numberedResult = doc.standardizeNumberedListPrefixes({ color: '000000', bold: true });
+
+    if (bulletResult.listsUpdated > 0 || numberedResult.listsUpdated > 0) {
+      this.log.debug('Standardized all numbering colors to black using framework methods');
+      return true;
+    }
+    return false;
+  } catch (error) {
+    this.log.warn('Unable to standardize numbering colors:', error);
+    return false;
+  }
+}
+```
+
+### Step 4: Delete injectCompleteRunPropertiesToNumbering()
+
+**Action:** Remove entire method (lines 3133-3209)
+**Verification:** Search codebase to ensure no other call sites exist
+
+### Step 5: Update standardizeListPrefixFormatting() (Optional Improvement)
+
+**Current:** Uses custom XML regex (lines 1916-2041)
+**Optional:** Replace with framework methods for cleaner code
+
+---
+
+## Testing Checklist
+
+### Pre-Testing
+
+- [ ] Create feature branch: `refactor/list-framework-methods`
+- [ ] Build project successfully
+- [ ] Run existing tests to establish baseline
+
+### Bullet List Testing
+
+- [ ] Create document with bullet lists
+- [ ] Verify custom bullet symbols from UI are preserved
+- [ ] Verify formatting: Verdana 12pt bold black
+- [ ] Verify indentation works correctly (UI-configured values)
+- [ ] Test multi-level lists (levels 0-8)
+
+### Numbered List Testing
+
+- [ ] Create document with numbered lists
+- [ ] Verify different formats work (1., a., i., I., A.)
+- [ ] Verify formatting: Verdana 12pt bold black
+- [ ] Verify indentation works correctly
+- [ ] Test multi-level lists
+
+### Edge Cases
+
+- [ ] Empty lists
+- [ ] Mixed bullet/numbered lists in same document
+- [ ] Lists in table cells
+- [ ] Lists with custom colors (should be standardized to black)
+- [ ] Documents without any lists
+
+### Regression Testing
+
+- [ ] Process existing test documents
+- [ ] Compare output with baseline (before refactoring)
+- [ ] Verify no unexpected changes to non-list content
+- [ ] Performance: Ensure no slowdown
+
+---
+
+## Expected Benefits
+
+### Code Reduction
+
+- **Before:** ~77 lines (injectCompleteRunPropertiesToNumbering)
+- **After:** ~3-5 lines per call site
+- **Total Savings:** ~65-70 lines of complex XML manipulation code
+
+### Maintainability
+
+- ✅ Framework handles OOXML compliance
+- ✅ No regex parsing of XML
+- ✅ Type-safe with TypeScript definitions
+- ✅ Future framework updates automatically improve functionality
+
+### Risk Mitigation
+
+- ✅ Less custom code = fewer bugs
+- ✅ Framework is well-tested
+- ✅ Easier to understand for new developers
+
+---
+
+## Migration Checklist
+
+### Phase 1: Preparation
+
+- [x] Analyze current implementation
+- [x] Identify framework methods to use
+- [x] Create refactoring plan
+- [ ] Review plan with team
+- [ ] Create feature branch
+
+### Phase 2: Implementation
+
+- [ ] Modify `applyBulletUniformity()`
+- [ ] Modify `applyNumberedUniformity()`
+- [ ] Modify `standardizeNumberingColors()`
+- [ ] Delete `injectCompleteRunPropertiesToNumbering()`
+- [ ] Build and fix any compilation errors
+
+### Phase 3: Testing
+
+- [ ] Run unit tests
+- [ ] Manual testing with sample documents
+- [ ] Edge case testing
+- [ ] Performance testing
+- [ ] Regression testing
+
+### Phase 4: Documentation
+
+- [ ] Update code comments
+- [ ] Update List_Implementation.md (mark framework methods as "USED")
+- [ ] Add migration notes to commit message
+- [ ] Update CHANGELOG if applicable
+
+### Phase 5: Deployment
+
+- [ ] Code review
+- [ ] Merge to development
+- [ ] Monitor for issues
+- [ ] Document any framework limitations discovered
+
+---
+
+## Rollback Plan
+
+If issues are discovered after deployment:
+
+1. **Immediate:** Revert commit via Git
+2. **Investigation:** Analyze what framework method didn't handle
+3. **Options:**
+   - Fix by adjusting framework method parameters
+   - Add supplementary code for edge cases
+   - Keep framework methods + minimal custom code
+4. **Never:** Go back to 100% custom XML - use hybrid approach if needed
+
+---
+
+## Questions & Answers
+
+**Q: Will Verdana font work correctly for all bullet characters?**
+A: Yes - Verdana is specifically chosen for proper Unicode bullet rendering in Word. Calibri/Arial are mentioned in documentation but Verdana is the actual implementation choice.
+
+**Q: What about custom indentation from UI settings?**
+A: Keep `injectIndentationToNumbering()` - framework doesn't expose per-level indentation customization via API.
+
+**Q: Can we use `getBulletSymbolWithFont()` for predefined styles?**
+A: Not in this refactor - current implementation uses user-configured bullets. This could be a future enhancement.
+
+**Q: Will this affect existing documents?**
+A: No - documents are processed fresh each time. Old documents remain unchanged until reprocessed.
+
+---
+
+## Success Criteria
+
+- ✅ All tests pass
+- ✅ No regression in list formatting
+- ✅ Code reduction of >60 lines
+- ✅ No performance degradation
+- ✅ Team approves changes
+
+---
+
+## Next Actions
+
+1. **Review this plan** - Get team approval
+2. **Create feature branch** - Start implementation
+3. **Implement Step 1** - Bullet list refactoring
+4. **Test thoroughly** - Before proceeding
+5. **Continue with Steps 2-4** - Complete refactoring
+6. **Final testing** - Full regression suite
+7. **Documentation** - Update all relevant docs
+8. **Merge** - Deploy to development
+
+---
+
+## References
+
+- **Accuracy Report:** [`List_Implementation_Accuracy_Report.md`](List_Implementation_Accuracy_Report.md)
+- **Current Code:** [`WordDocumentProcessor.ts`](../src/services/document/WordDocumentProcessor.ts)
+- **Framework API:** [`Document.d.ts`](../node_modules/docxmlater/dist/core/Document.d.ts)
+- **Original Docs:** [`List_Implementation.md`](../../List_Implementation.md)

package/docs/implementation/PRIMARY_TEXT_COLOR_FEATURE.md

@@ -0,0 +1,217 @@
+# Luminance-Based Primary Text Color Feature
+
+## Overview
+
+Automatically calculates optimal text color (black or white) for primary-colored elements based on the luminance of the custom primary color. This ensures text remains readable on buttons, badges, and other primary-colored UI elements regardless of the custom color chosen.
+
+## How It Works
+
+### 1. Color Calculation (ThemeContext.tsx)
+
+When custom colors are enabled, the system:
+
+- Reads the user's custom primary color (e.g., `#3b82f6`)
+- Calculates its luminance using WCAG 2.1 formula
+- Determines optimal contrast text color:
+  - **Light backgrounds** (luminance > 0.5) → Black text (`#000000`)
+  - **Dark backgrounds** (luminance ≤ 0.5) → White text (`#FFFFFF`)
+
+```typescript
+// ThemeContext.tsx line 216
+const primaryTextColor = getContrastTextColor(customPrimaryColor);
+root.style.setProperty('--custom-primary-text', hexToHSL(primaryTextColor));
+```
+
+### 2. CSS Variable Application (global.css)
+
+The calculated text color is applied through CSS variables:
+
+```css
+/* Line 275-276: Override the CSS variable */
+[data-custom-colors='true'] {
+  --color-primary-foreground: hsl(var(--custom-primary-text)) !important;
+}
+
+/* Lines 279-285: Apply to all primary elements */
+[data-custom-colors='true'] .bg-primary,
+[data-custom-colors='true'] .bg-primary *,
+[data-custom-colors='true'] button.bg-primary,
+[data-custom-colors='true'] button.bg-primary * {
+  color: hsl(var(--custom-primary-text)) !important;
+}
+```
+
+### 3. Automatic Mode Detection
+
+The system intelligently switches between modes:
+
+**Standard Mode (Light/Dark themes):**
+
+- Uses preset `--color-primary-foreground` from theme
+- Light mode: `hsl(210 40% 98%)` (near white)
+- Dark mode: `hsl(210 40% 98%)` (near white)
+
+**Custom Color Mode:**
+
+- Activates when: Settings → Appearance → "Custom Theme Colors" is enabled
+- Calculates text color dynamically based on chosen primary color
+- Updates automatically when primary color changes
+
+## User Experience
+
+### Enabling Custom Colors
+
+1. Open **Settings** → **Appearance**
+2. Toggle **"Custom Theme Colors"** ON
+3. Click the primary color picker
+4. Choose any color - text will automatically adjust
+
+### Visual Examples
+
+#### Example 1: Light Primary Color
+
+- **Primary Color:** `#FFD700` (Gold - luminance 0.78)
+- **Calculated Text:** Black (`#000000`)
+- **Result:** Dark text on light gold background ✓ Readable
+
+#### Example 2: Dark Primary Color
+
+- **Primary Color:** `#1a1a2e` (Dark Navy - luminance 0.05)
+- **Calculated Text:** White (`#FFFFFF`)
+- **Result:** White text on dark navy background ✓ Readable
+
+#### Example 3: Medium Primary Color
+
+- **Primary Color:** `#3b82f6` (Blue - luminance 0.32)
+- **Calculated Text:** White (`#FFFFFF`)
+- **Result:** White text on blue background ✓ Readable
+
+## Technical Details
+
+### Luminance Calculation
+
+Uses WCAG 2.1 relative luminance formula:
+
+```text
+L = 0.2126 * R + 0.7152 * G + 0.0722 * B
+```
+
+With gamma correction for sRGB color space.
+
+### Affected Elements
+
+All elements using these classes:
+
+- `.bg-primary` - Primary background color
+- `.text-primary-foreground` - Primary foreground text
+- `button.bg-primary` - Primary buttons (like "Process Documents")
+- Badges, checkboxes, toggles with primary color
+
+### File Changes
+
+1. **src/styles/global.css** (lines 271-290)
+   - Added `--color-primary-foreground` override
+   - Added `.bg-primary` text color rules
+   - Added `.text-primary-foreground` rules
+
+2. **src/contexts/ThemeContext.tsx** (existing, line 216)
+   - Already calculates `primaryTextColor`
+   - Already sets `--custom-primary-text` variable
+
+## Testing Guide
+
+### Manual Test Scenarios
+
+#### Test 1: Very Light Primary Color
+
+1. Enable Custom Theme Colors
+2. Set primary color to: `#FFEB3B` (bright yellow)
+3. **Expected:** All primary buttons show **BLACK** text
+4. **Verify:** Text is clearly readable
+
+#### Test 2: Very Dark Primary Color
+
+1. Enable Custom Theme Colors
+2. Set primary color to: `#212121` (very dark gray)
+3. **Expected:** All primary buttons show **WHITE** text
+4. **Verify:** Text is clearly readable
+
+#### Test 3: Medium Brightness Colors
+
+1. Test colors around the threshold (luminance ~0.5):
+   - `#808080` (medium gray) → White text
+   - `#00AA00` (medium green) → White text
+   - `#FFA500` (orange) → Black text
+   - `#4169E1` (royal blue) → White text
+
+#### Test 4: Mode Switching
+
+1. Enable Custom Theme Colors with light primary color
+2. **Verify:** Black text appears
+3. Disable Custom Theme Colors
+4. **Verify:** Returns to standard theme text color
+5. Re-enable Custom Theme Colors
+6. **Verify:** Black text reappears correctly
+
+### Visual Testing Checklist
+
+- [ ] Process Documents button (CurrentSession page)
+- [ ] Active session indicators (Sidebar)
+- [ ] Primary action buttons (SessionManager)
+- [ ] Update notification button (UpdateNotification)
+- [ ] Save buttons in Settings
+- [ ] Active tab indicators
+
+## Troubleshooting
+
+### Text Color Not Updating
+
+**Symptom:** Text remains default color after changing primary color
+
+**Solutions:**
+
+1. Ensure "Custom Theme Colors" toggle is ON
+2. Hard refresh browser (Ctrl+Shift+R)
+3. Check browser console for errors
+4. Verify `data-custom-colors="true"` attribute on `<html>` element
+
+### Poor Contrast
+
+**Symptom:** Text is barely visible on primary color
+
+**Root Cause:** The threshold (0.5) works for most colors but edge cases may need adjustment
+
+**Solution:** Adjust threshold in `colorConvert.ts`:
+
+```typescript
+// Line 165 - Current threshold
+return luminance > 0.5 ? '#000000' : '#FFFFFF';
+
+// If needed, adjust to 0.45 or 0.55 for better results
+```
+
+### Text Color in Standard Mode
+
+**Symptom:** Custom text colors appear when custom mode is disabled
+
+**Solution:** This should not happen - CSS rules only apply when `[data-custom-colors='true']`. Check that the attribute is being removed when disabling custom colors.
+
+## Browser Compatibility
+
+- ✅ Chrome/Edge 88+ (CSS `color-mix`, `hsl()` variables)
+- ✅ Firefox 88+
+- ✅ Safari 15.4+
+- ❌ IE 11 (not supported)
+
+## Performance Impact
+
+- **Negligible** - Color calculation happens once on theme change
+- CSS variables update instantly without re-render
+- No JavaScript running during normal usage
+
+## Future Enhancements
+
+1. **Contrast Ratio Display:** Show WCAG contrast ratio in color picker
+2. **Accessibility Warnings:** Alert when contrast is below AA standard
+3. **Preview Mode:** Show text samples before applying color
+4. **Smart Suggestions:** Recommend primary colors with good contrast