oxjs/ES_MODULE_MIGRATION_PLAN.md

OxJS ES Modules Migration Plan

Phase 1: Test Suite Creation

Existing Test Infrastructure

OxJS has an innovative inline test system built into its documentation format:

• Tests are embedded in documentation comments using > statement followed by expected result
• The Ox.test() function extracts and runs these tests from the source
• Tests can be synchronous or asynchronous
• Tests are human-readable and serve as documentation examples

Test Migration Strategy

1. Extract and modernize existing inline tests

   • Use Ox.doc() to parse all inline tests from source files
   • Convert inline tests to Jest/Vitest test suites
   • Maintain inline tests for documentation purposes
   • Ensure all existing inline tests pass before migration

2. Create additional test coverage

   • Integration tests for module loading patterns
   • Verify that ES module imports/exports work correctly
   • Test the compatibility layer (Ox.load to ES modules bridge)
   • Simple validation that existing examples still function

3. Set up test infrastructure

   • Add Jest or Vitest for running extracted tests
   • Create test helpers for legacy Ox.load patterns
   • Build a test runner that can execute both inline and external tests
   • Focus on verifying functionality, not UI testing initially

Phase 2: Build Infrastructure Setup

1. Initialize npm project

   • Create package.json with proper metadata
   • Add development dependencies (Vite, TypeScript, PostCSS, etc.)
   • Set up ESLint and Prettier for code quality

2. Configure Vite build system

   • Development server with ES modules
   • Production builds (ES modules + UMD)
   • Asset handling for themes, SVGs, and images
   • CSS processing with PostCSS for theme variables

Phase 3: Core Module Conversion

1. Convert Ox core files to ES modules

   • Start with leaf modules (no dependencies)
   • Add explicit imports/exports
   • Create index.js barrel exports
   • Maintain careful load order for circular dependencies

2. Create compatibility layer

   • Global Ox object for backward compatibility
   • Polyfill for Ox.load() using dynamic imports
   • Bridge between ES modules and legacy code

Phase 4: UI Module Migration

1. Convert UI components to ES modules

   • Refactor each component as separate ES module
   • Extract theme system to CSS variables
   • Modernize SVG and image handling

2. Update theme processing

   • Use CSS custom properties instead of build-time substitution
   • Implement theme switching via CSS classes
   • Bundle theme assets with Vite

Phase 5: Testing and Validation

1. Verify all functionality

   • Run test suite
   • Test all examples with new build
   • Validate both dev and production builds
   • Check browser compatibility

2. Performance testing

   • Compare bundle sizes
   • Measure load times
   • Profile runtime performance

Phase 6: Documentation and Release

1. Update documentation

   • Migration guide for existing users
   • New ES modules usage examples
   • API documentation updates

2. NPM package release

   • Publish to npm registry
   • Support multiple entry points (ES modules, UMD, legacy)
   • Maintain backward compatibility

Key Implementation Tasks

• Convert ~50+ JavaScript files to ES modules
• Replace Python build script with Vite/npm scripts
• Modernize theme and asset processing
• Create basic test suite for functionality verification
• Ensure all existing examples continue working
• Support both modern ES imports and legacy script tags

Testing Strategy Details

Unit Tests (Phase 1)

Focus on core functionality:

• Test Ox.Array methods (unique, sort, etc.)
• Test Ox.String utilities (capitalize, format, etc.)
• Test Ox.Math functions
• Test Ox.Type checking utilities
• Verify module export/import structure

Integration Tests (Phase 1)

Verify module loading:

• Test dynamic import() for lazy loading
• Test circular dependency resolution
• Test module initialization order
• Test compatibility layer (Ox.load to ES modules)
• Basic smoke tests for UI component initialization

Advanced Testing (Future)

• E2E testing with Playwright
• Visual regression testing
• Performance benchmarking
• Cross-browser testing