119 lines
4.2 KiB
Markdown
119 lines
4.2 KiB
Markdown
|
# 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
|