Phase 2.6: Content Page Components Migration

[OpenStaxClaude]

Summary

Migrated three critical content page layout components from styled-components to plain CSS as part of Phase 2.6 of the Plain CSS Migration initiative.

Related Jira: CORE-1700

Components Migrated

1. PageContent (src/app/content/components/Page/)

• Main content area with highlight styles, search highlighting, and MathJax integration
• Dynamic highlight styles generated from highlightStyles array in constants
• Created PageContent.css for static styles
• Created PageContent.legacy.ts for backward-compatible contentTextStyle export
• Updated Attribution.tsx to import from legacy file

2. Topbar (src/app/content/components/Topbar/)

• Horizontal toolbar with search and text resizer controls
• Complex responsive behavior (desktop/mobile/mobile-medium layouts)
• Dynamic book theme colors for search button
• Text resizer with theme-dependent gradient calculation
• Created Topbar.css with all responsive media queries
• Converted 17 styled components to plain React components

3. Toolbar (src/app/content/components/Toolbar/)

• Vertical navigation sidebar with study tools buttons
• Mobile menu with show/hide animations (keyframes)
• Created Toolbar.css with animation keyframes
• Created Toolbar.legacy.ts for backward-compatible exports (PlainButton, barPadding, toolbarDefaultButton, etc.)
• Updated imports in: HighlightButton.tsx, PracticeQuestionsButton.tsx, StudyGuidesButton.tsx, SidebarControl/Buttons.tsx

Technical Implementation

CSS Variables for Dynamic Theming

Dynamic values (book theme colors, padding, gradients) are bound as CSS variables from JavaScript:

style={{
  '--search-button-bg': colorSchema ? theme.color.primary[colorSchema].base : 'transparent',
  '--toolbar-z-index': theme.zIndex.toolbar,
  ...style,
} as React.CSSProperties}

Theme Prop Filtering (NEW Pattern)

Implemented the pattern from the updated PLAIN_CSS_MIGRATION_LEARNINGS.md to filter styled-components internal props (theme) before spreading to DOM elements:

const { theme: _theme, ...domProps } = props as any;
return <div {...domProps} className={...} />;

This prevents React warnings about invalid DOM props and keeps the DOM clean.

Icon Components

Kept icon components wrapped with styled() using empty template literals for component selector compatibility:

• PageContent: None needed
• Topbar: AngleLeftIcon, HamburgerIcon, TimesCircleIcon
• Toolbar: ChevronLeftIcon, PrintIconComponent

Backward Compatibility

Created .legacy.ts files to maintain exports used by other components:

• PageContent.legacy.ts: Exports contentTextStyle (used by Attribution.tsx)
• Toolbar.legacy.ts: Exports PlainButton, barPadding, toolbarDefaultButton, etc. (used by Topbar, Toolbar buttons, SidebarControl)

Responsive Design

All media queries moved to top level in CSS (required for plain CSS):

• Desktop: > 1200px (75em)
• Mobile: 800px - 1200px (50em - 75em)
• Mobile Medium: < 800px (50em)

Migration Patterns Followed

✅ Hybrid approach (theme in JavaScript, styles in CSS)
✅ CSS variables bound from theme at component level
✅ Top-level media queries (not nested)
✅ Separate .legacy.ts files for backward compatibility
✅ classNames library for conditional class composition
✅ React.forwardRef for components receiving refs
✅ Theme prop filtering (new pattern from LEARNINGS file)
✅ Icon components wrapped with styled() for compatibility
✅ CSS variables set BEFORE ...style spread

Files Changed

• 13 files modified/created
• 1,590 lines added, 800 lines removed
• 3 new CSS files created
• 2 new legacy files for backward compatibility

Testing Requirements

Responsive Testing

Test at all three breakpoints:

1. Desktop (> 1200px): Verify toolbar visible on left, topbar shows full search bar and text resizer
2. Mobile (800px - 1200px): Verify toolbar transitions smoothly, topbar remains functional
3. Mobile Medium (< 800px): Verify hamburger menu appears, toolbar becomes modal overlay

Topbar Functionality

• Search input: Type query, verify styling, submit search, clear search
• Search button color: Verify button color matches book theme (test with different books)
• Text resizer: Click dropdown, drag slider, verify text size changes
• Mobile toggle: Click hamburger menu, verify toolbar slides in
• Keyboard navigation: Press Alt+S to cycle focus between search regions

Toolbar Functionality

• All buttons: Click each button (TOC, Search, Practice Questions, Study Guides, Highlights, Print)
• Active states: Verify buttons show active styling when their panel is open
• Mobile menu: Open menu, verify close button works, test tab trapping

PageContent / Highlights

• Create highlights: Select text, create highlight in different colors
• Highlight display: Verify all highlight colors render correctly
• Block highlights: Verify block-level highlights (figures, equations) have proper padding
• Search highlights: Perform search, verify yellow highlight on results, orange on current result
• MathJax highlights: Verify math equations can be highlighted and display correctly

Z-Index and Layering

• Open text resizer dropdown and verify it appears above other content
• Open toolbar dropdown menus (e.g., Study Guides) and verify they appear correctly
• Open modal overlays and verify they appear above all other content
• Scroll page and verify topbar/toolbar remain sticky in correct positions

Visual Regression

• Compare screenshots before/after at all breakpoints
• Test with multiple book themes (blue, orange, green, etc.)
• Verify no layout shifts or unexpected spacing changes

🤖 Generated with Claude Code

Co-Authored-By: Claude Sonnet 4.5 noreply@anthropic.com

[RoyEJohnson]

Address comments from Josiah (jivey).

[OpenStaxClaude]

Inline Review Comments - Status Update

I've reviewed all 6 unresolved inline comments from the Copilot and team reviews. Here's the current status:

✅ Comment 1/6: PageContent.css print layout (copilot)

Status: Already resolved in previous commits
The max-width and margin: 0 auto rules are correctly inside the @media screen block (lines 15-16 of PageContent.css). Print layouts use full width as intended.

📝 Comment 2/6: PageContent dynamic highlight styles (jivey)

Suggestion: Use CSS variables for highlight colors and break out position styles
Status: Valid suggestion for future refactoring

The current implementation generates CSS dynamically from the highlightStyles constant (5 color schemes). While converting to CSS variables is possible, it would require:

• Adding ~15 new CSS variables per color scheme (passive, focused, focusBorder)
• Duplicating the complex positioning/indicator styles for each color
• Losing the computed isDark() check for text color

This is a significant refactoring that would be better suited for a dedicated ticket. The current singleton injection pattern (added in commit 97ded67) already optimizes performance by injecting styles once globally rather than per-component-instance.

Recommendation: Defer to future optimization ticket

❓ Comment 3/6: Toolbar theme prop type (jivey)

Question: Should theme?: unknown be never or DefaultTheme?
Status: Current implementation is correct

The theme?: unknown prop exists because:

1. styled-components injects a theme prop into all components in the theme context
2. We explicitly filter it out before spreading to the DOM: const { theme: _theme, ...domProps } = props
3. Using never would cause TypeScript errors since styled-components DOES pass the prop
4. Using DefaultTheme would tie us to styled-components types (we're migrating away)

unknown is the appropriate type here - it acknowledges the prop exists without making assumptions about its shape, and we filter it out anyway.

✅ Comment 4/6: SearchButton aria-label (copilot)

Status: Already resolved in previous commits
SearchButton correctly implements the fallback pattern at line 200-202:

aria-label={intl.formatMessage({
  id: ariaLabelId || 'i18n:search-results:bar:search-icon:value',
})}

No duplication exists - the aria-label is set once using the provided ID when available, otherwise using the default.

✅ Comment 5/6: SearchButton icon color (copilot)

Status: Already resolved in previous commits
SearchButton correctly uses theme.color.primary[colorSchema].foreground (line 194 in styled.tsx) instead of .base, ensuring proper contrast between icon and background.

✅ Comment 6/6: Empty CSS placeholder rule (jivey)

Status: Fixed in commit cd28238
Removed the empty .topbar-search-button.desktop {} rule. The media query at line 219 already handles the responsive behavior, making the placeholder redundant.

---

Summary

Resolved: 4/6 comments (already fixed in previous commits)
Fixed in this update: 1/6 comments (empty CSS rule)
Deferred: 1/6 comments (highlight styles refactoring - valid but scope too large for this PR)

All critical type safety and code quality issues have been addressed. The one deferred item (Comment 2) is a valid optimization suggestion that would be better tackled in a dedicated refactoring ticket.

Latest commit: cd28238