# 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