From 99856600c0643b23e7f982f6e2751dd4ab939a32 Mon Sep 17 00:00:00 2001 From: Russell Ballestrini Date: Wed, 9 Jul 2025 18:34:12 -0400 Subject: [PATCH] docs: rewrite journal entry for modal CSS overhaul with complete solution --- journal.rst | 151 +++++++++++++++++++++++----------------------------- 1 file changed, 66 insertions(+), 85 deletions(-) diff --git a/journal.rst b/journal.rst index 9c46f9c..1cfde3c 100644 --- a/journal.rst +++ b/journal.rst @@ -123,82 +123,38 @@ This system supports the full user journey from language detection to dynamic in July 9, 2025 ============ -Modal CSS Architecture Overhaul & Translation Page Fix -------------------------------------------------------- +Modal CSS Architecture Overhaul +------------------------------- **The Problem** -User feedback revealed that the PicoCSS version of the UncloseAI modal was filling the entire screen on large laptop displays, which users found jarring. Additionally, translated pages opened in new windows had broken CSS styling, making them unusable. +Users reported multiple issues with the UncloseAI modal experience: + +1. **Desktop Issue**: PicoCSS-powered sites displayed full-screen modals on large laptop displays instead of centered dialogs +2. **Translation Pages**: Broken CSS in translated pages opened in new windows made them unusable +3. **Mobile Experience**: After initial fixes, mobile devices lost their full-screen modal experience **Root Cause Analysis** -Two critical issues were identified: +Three interconnected issues created these problems: -1. **Inconsistent CSS Loading Logic**: Different modal files used different approaches: - - Some used ``window.UNCLOSEAI_CUSTOM_STYLING`` flag (fragile) - - Others used actual PicoCSS detection via ``document.querySelector('link[href*="pico"]')`` (robust) - - Mix of relative paths (``./src/``) and absolute URLs (``https://uncloseai.com/src/``) +1. **Inconsistent CSS Loading**: Different modal files used different detection methods and URL patterns +2. **PicoCSS Overrides**: The framework's aggressive dialog styling required careful specificity management +3. **Breakpoint Mismatch**: Mobile detection used 480px while many tablets needed full-screen at 768px -2. **Modal Sizing Override Issues**: PicoCSS dialog defaults were overriding our modal sizing with ``!important`` declarations +**Solution: Complete CSS Architecture Refactoring** -**Solution Implementation** +**Step 1: Dedicated CSS Files** -**Phase 1: CSS Architecture Refactoring** +Created two purpose-built stylesheets to replace all inline styles: -Moved all inline styles from JavaScript files into two dedicated CSS files: +- ``uncloseai-modal-builtin.css`` - Clean styles for standard blog sites +- ``uncloseai-modal-pico.css`` - Override styles with ``!important`` for PicoCSS sites -- ``src/uncloseai-modal-builtin.css`` - Clean styles for blog versions without PicoCSS -- ``src/uncloseai-modal-pico.css`` - Override styles with ``!important`` declarations for PicoCSS sites +**Step 2: Unified CSS Loading Pattern** -**Consolidated Modal Styles:** -- Hermes AI modal (main chat interface) -- Translation modal (text & page translation) -- TTS modal (text-to-speech interface) -- Widget library components (chat widgets, dropdowns) +Standardized all modal components to use the same detection and loading logic: -**Phase 2: PicoCSS Override Strategy** - -Used CSS specificity and ``!important`` declarations to override PicoCSS dialog defaults: - -```css -/* Override PicoCSS positioning that sets top:0, left:0, right:0, bottom:0 */ -dialog#uncloseai-embedded-modal[data-theme] { - position: fixed !important; - top: 50% !important; - left: 50% !important; - transform: translate(-50%, -50%) !important; - width: 70vw !important; - max-width: 800px !important; - height: 90vh !important; -} -``` - -**Phase 3: Consistent CSS Loading Pattern** - -Standardized all modal files to use: - -1. **PicoCSS Detection**: ``document.querySelector('link[href*="pico"]') !== null`` -2. **Absolute URLs**: ``https://uncloseai.com/src/${cssFile}`` -3. **Proper Mobile Handling**: 480px breakpoint instead of 768px - -**Phase 4: Translation Page CSS Fix** - -Fixed broken CSS in translated pages by: - -1. **Base Tag Approach**: Added ```` to resolve relative URLs -2. **Consistent Loading**: Updated translate-modal.js to use the same CSS loading pattern -3. **Cross-Window Compatibility**: Ensured CSS loads properly in new window contexts - -**Technical Details** - -**Files Modified:** -- ``src/uncloseai-embed-modal.js`` - Main modal CSS loading -- ``src/translate-modal.js`` - Translation modal CSS loading -- ``src/tts-modal.js`` - TTS modal CSS loading -- ``src/widget-library.js`` - Widget CSS loading -- ``src/translation.js`` - Base tag injection for new windows - -**CSS Detection Logic:** ```javascript // Detect if PicoCSS is actually present on the page const hasPicoCSS = document.querySelector('link[href*="pico"]') !== null; @@ -206,37 +162,62 @@ const hasPicoCSS = document.querySelector('link[href*="pico"]') !== null; // Load appropriate CSS based on actual PicoCSS presence const cssFile = hasPicoCSS ? 'uncloseai-modal-pico.css' : 'uncloseai-modal-builtin.css'; -if (!document.querySelector(`link[href*="${cssFile}"]`)) { - const link = document.createElement('link'); - link.rel = 'stylesheet'; - link.href = `https://uncloseai.com/src/${cssFile}`; - document.head.appendChild(link); +// Use absolute URLs for cross-domain compatibility +link.href = `https://uncloseai.com/src/${cssFile}`; +``` + +**Step 3: PicoCSS Override Strategy** + +```css +/* Override PicoCSS dialog defaults with high specificity */ +dialog#uncloseai-embedded-modal[data-theme] { + position: fixed !important; + top: 50% !important; + left: 50% !important; + transform: translate(-50%, -50%) !important; + width: 70vw !important; + max-width: 800px !important; +} + +/* Mobile/tablet full-screen experience */ +@media (max-width: 768px) { + dialog#uncloseai-embedded-modal[data-theme] { + top: 0 !important; + left: 0 !important; + width: 100vw !important; + height: 100vh !important; + } } ``` -**Mobile Responsiveness:** -- Desktop: Centered modal with 70vw width, 800px max-width -- Mobile (≤480px): Full-screen modal for touch interfaces +**Step 4: Translation Page CSS Fix** -**Phase 5: Mobile Experience Restoration** +- Added ```` tag to resolve relative URLs in new windows +- Ensured all modal CSS uses absolute URLs for cross-window compatibility +- Maintained original page styling while adding AI functionality -After initial deployment, discovered the mobile experience was broken - modals weren't filling the full screen on mobile devices. Fixed by: +**Technical Implementation** -1. **Added `!important` declarations** to mobile media query overrides in PicoCSS stylesheet -2. **Increased mobile breakpoint** from 480px to 768px to properly cover tablets and larger phones -3. **Updated JavaScript detection** to match CSS breakpoint (768px) for consistency +**Files Modified:** +- ``uncloseai-embed-modal.js`` - Main modal with PicoCSS detection +- ``translate-modal.js`` - Translation modal with absolute URLs +- ``tts-modal.js`` - TTS modal with consistent loading +- ``widget-library.js`` - Widget components with proper CSS +- ``translation.js`` - Base tag injection for new windows +- ``uncloseai-modal-builtin.css`` - Standard site styles +- ``uncloseai-modal-pico.css`` - PicoCSS override styles -**Final Mobile Responsiveness:** -- Desktop (>768px): Centered modal with 70vw width, 800px max-width -- Mobile/Tablet (≤768px): Full-screen modal (100vw × 100vh) for optimal touch experience +**Responsive Breakpoints:** +- **Desktop (>768px)**: Centered modal (70vw × 90vh, max 800px width) +- **Mobile/Tablet (≤768px)**: Full-screen modal (100vw × 100vh) **Results** -✅ **Modal Sizing Fixed**: No more full-screen modals on large displays -✅ **CSS Architecture Clean**: All inline styles moved to dedicated CSS files -✅ **Cross-Site Compatibility**: Consistent behavior on blog sites and PicoCSS sites -✅ **Translation Pages Fixed**: Proper CSS loading in new window contexts -✅ **Mobile Experience Restored**: Full-screen modals on phones and tablets -✅ **Developer Experience**: Maintainable CSS architecture with clear separation of concerns +✅ **Desktop Experience**: Properly centered modals on large displays +✅ **Mobile Experience**: Full-screen modals on phones and tablets +✅ **Translation Pages**: Functional CSS in new window contexts +✅ **Code Architecture**: Clean separation between JS logic and CSS styling +✅ **Cross-Site Compatibility**: Consistent behavior across all site types +✅ **Maintainability**: Single source of truth for modal styling -This refactoring resolved the immediate user experience issues while establishing a robust, maintainable CSS architecture that prevents similar problems in the future. \ No newline at end of file +This comprehensive refactoring established a robust CSS architecture that handles all edge cases while providing an optimal user experience across all devices and contexts. \ No newline at end of file