add CLAUDE.md with overall structure and plan to migrate to ES modules
This commit is contained in:
Sanjay Bhangar
parent
ec5b050496
commit
91b6deaf7f
2 changed files with 304 additions and 0 deletions
185
CLAUDE.md
Normal file
185
CLAUDE.md
Normal file
|
|
@ -0,0 +1,185 @@
|
||||||
|
# OxJS Codebase Analysis
|
||||||
|
|
||||||
|
## Overview
|
||||||
|
OxJS is a JavaScript UI framework created around 2008, predating modern JavaScript build tools and module systems. It uses a custom build system and loading mechanism that was innovative for its time but needs modernization.
|
||||||
|
|
||||||
|
## Current Architecture
|
||||||
|
|
||||||
|
### 1. Module Structure
|
||||||
|
The codebase is organized into distinct modules:
|
||||||
|
- **Ox**: Core library with utilities (Array, String, Math, Type, etc.)
|
||||||
|
- **UI**: User interface components and themes
|
||||||
|
- **Geo**: Geographic utilities
|
||||||
|
- **Image**: Image manipulation utilities
|
||||||
|
- **Unicode**: Unicode utilities
|
||||||
|
|
||||||
|
Each module follows the pattern:
|
||||||
|
```
|
||||||
|
source/
|
||||||
|
├── ModuleName/
|
||||||
|
│ ├── ModuleName.js (module loader)
|
||||||
|
│ ├── js/ (JavaScript files)
|
||||||
|
│ └── json/ (locale and config files)
|
||||||
|
```
|
||||||
|
|
||||||
|
### 2. Custom Import/Loading System
|
||||||
|
|
||||||
|
#### Core Loader (`source/Ox.js`)
|
||||||
|
- The framework uses a custom `Ox.load()` function instead of ES modules
|
||||||
|
- Loading process:
|
||||||
|
1. Detects script path from `<script>` tag
|
||||||
|
2. Loads `Ox/json/Ox.json` manifest file
|
||||||
|
3. Sequentially loads script groups in dependency order
|
||||||
|
4. Supports dev (individual files) and min (bundled) modes
|
||||||
|
|
||||||
|
#### Module Loading Pattern
|
||||||
|
```javascript
|
||||||
|
// Usage in applications
|
||||||
|
Ox.load('UI', function() {
|
||||||
|
// Module is loaded, can use Ox.UI
|
||||||
|
});
|
||||||
|
|
||||||
|
// Module definition pattern
|
||||||
|
Ox.load.ModuleName = function(options, callback) {
|
||||||
|
// Module initialization code
|
||||||
|
callback(true); // success
|
||||||
|
};
|
||||||
|
```
|
||||||
|
|
||||||
|
### 3. Build System (`tools/build/build.py`)
|
||||||
|
|
||||||
|
The Python build script performs several tasks:
|
||||||
|
|
||||||
|
#### Core Processing (`Ox` module)
|
||||||
|
1. **Dependency ordering**: Files are loaded in specific groups to handle dependencies
|
||||||
|
- Group 1: `Core.js` (defines Ox object)
|
||||||
|
- Group 2: `Function.js`, `Polyfill.js`
|
||||||
|
- Group 3: `Array.js`, `String.js`, `Type.js`
|
||||||
|
- Group 4: `Collection.js`, `Math.js`
|
||||||
|
- Remaining files loaded alphabetically
|
||||||
|
|
||||||
|
2. **Version injection**: Replaces `Ox.VERSION` placeholder
|
||||||
|
3. **Locale aggregation**: Collects all locale files into `Ox.LOCALES`
|
||||||
|
4. **Minification**: Uses `ox.js.minify()` to create compressed version
|
||||||
|
|
||||||
|
#### UI Module Processing
|
||||||
|
1. **Theme handling**:
|
||||||
|
- Reads theme data from `themes/*/json/theme.jsonc`
|
||||||
|
- Generates theme-specific CSS by replacing variables
|
||||||
|
- Creates theme-specific SVG files
|
||||||
|
|
||||||
|
2. **Asset management**:
|
||||||
|
- SVG files are embedded as strings in `ui_images`
|
||||||
|
- PNG files are copied to build directories
|
||||||
|
- CSS imports are dynamically generated
|
||||||
|
|
||||||
|
3. **File bundling**:
|
||||||
|
- All UI JavaScript files are concatenated into `UI/js/UI.js`
|
||||||
|
- Creates `UI/json/UI.json` manifest with file lists
|
||||||
|
|
||||||
|
#### Output Structure
|
||||||
|
Creates two build directories:
|
||||||
|
- `dev/`: Development version with symlinks to source files
|
||||||
|
- `min/`: Minified production version with concatenated files
|
||||||
|
|
||||||
|
### 4. Key Patterns and Conventions
|
||||||
|
|
||||||
|
#### No External Dependencies
|
||||||
|
- jQuery is bundled but loaded separately
|
||||||
|
- No npm packages or node_modules
|
||||||
|
- All dependencies are included in source
|
||||||
|
|
||||||
|
#### Global Namespace
|
||||||
|
- Everything hangs off the global `Ox` object
|
||||||
|
- No module-level scope isolation
|
||||||
|
- Methods are attached directly to `Ox` or `Ox.ModuleName`
|
||||||
|
|
||||||
|
#### Custom JSON with Comments (JSONC)
|
||||||
|
- Uses `.jsonc` files that support comments
|
||||||
|
- Custom parser in build process
|
||||||
|
|
||||||
|
#### Dynamic Loading
|
||||||
|
- Modules can be loaded on-demand
|
||||||
|
- Supports conditional loading based on options
|
||||||
|
- Locale files loaded lazily
|
||||||
|
|
||||||
|
## Challenges for ES Module Migration
|
||||||
|
|
||||||
|
### 1. Circular Dependencies
|
||||||
|
The current load order suggests potential circular dependencies that need careful handling.
|
||||||
|
|
||||||
|
### 2. Global State
|
||||||
|
Heavy reliance on global `Ox` object and sequential initialization.
|
||||||
|
|
||||||
|
### 3. Dynamic Module Loading
|
||||||
|
The `Ox.load()` pattern allows runtime module loading which differs from ES module static imports.
|
||||||
|
|
||||||
|
### 4. Build Process Integration
|
||||||
|
The Python build script handles many transformations that would need webpack/rollup equivalents.
|
||||||
|
|
||||||
|
### 5. Theme and Asset Processing
|
||||||
|
Complex CSS variable substitution and SVG processing needs modern build tool equivalents.
|
||||||
|
|
||||||
|
### 6. Browser Compatibility
|
||||||
|
Current system supports very old browsers; ES modules require modern browser support.
|
||||||
|
|
||||||
|
## Migration Strategy Considerations
|
||||||
|
|
||||||
|
### Phase 1: Preparation
|
||||||
|
- Add package.json and npm infrastructure
|
||||||
|
- Set up modern build tooling (webpack/rollup/vite)
|
||||||
|
- Create comprehensive test suite
|
||||||
|
|
||||||
|
### Phase 2: Module Conversion
|
||||||
|
- Convert individual files to ES modules
|
||||||
|
- Maintain backward compatibility layer
|
||||||
|
- Create barrel exports for each module
|
||||||
|
|
||||||
|
### Phase 3: Build System
|
||||||
|
- Replace Python build with npm scripts
|
||||||
|
- Implement CSS/SVG processing with PostCSS/webpack
|
||||||
|
- Set up development and production builds
|
||||||
|
|
||||||
|
### Phase 4: Distribution
|
||||||
|
- Publish to npm
|
||||||
|
- Support both ES modules and UMD builds
|
||||||
|
- Maintain script tag compatibility
|
||||||
|
|
||||||
|
## Inline Test System
|
||||||
|
|
||||||
|
OxJS has a unique inline test system integrated with its documentation:
|
||||||
|
|
||||||
|
### Test Format
|
||||||
|
Tests are embedded directly in documentation comments:
|
||||||
|
```javascript
|
||||||
|
/*@
|
||||||
|
My.foo <f> Returns an item's bar per baz
|
||||||
|
(item) -> <n> Bar per baz, or NaN
|
||||||
|
item <o> Any item
|
||||||
|
> My.foo({bar: 1, baz: 10})
|
||||||
|
0.1
|
||||||
|
> My.foo({})
|
||||||
|
NaN
|
||||||
|
@*/
|
||||||
|
```
|
||||||
|
|
||||||
|
### Test Execution
|
||||||
|
- `Ox.doc()` parses documentation and extracts test statements
|
||||||
|
- `Ox.test()` runs the tests and compares actual vs expected results
|
||||||
|
- Tests can be synchronous or asynchronous (using callbacks)
|
||||||
|
- Test results include pass/fail status and actual values
|
||||||
|
|
||||||
|
### Benefits
|
||||||
|
- Tests serve as executable documentation
|
||||||
|
- Examples are guaranteed to be accurate
|
||||||
|
- No separate test files needed for basic unit tests
|
||||||
|
- Human-readable format
|
||||||
|
|
||||||
|
## Key Files to Study
|
||||||
|
1. `source/Ox.js` - Core loader implementation
|
||||||
|
2. `source/Ox/js/Core.js` - Module loading logic
|
||||||
|
3. `source/Ox/js/JavaScript.js` - Documentation parser and test runner
|
||||||
|
4. `tools/build/build.py` - Build process details
|
||||||
|
5. `source/UI/UI.js` - Module initialization pattern
|
||||||
|
6. `examples/documentation/oxdoc_tutorial/js/example.js` - Documentation format examples
|
||||||
|
7. `index.js` - Main entry point usage
|
||||||
119
ES_MODULE_MIGRATION_PLAN.md
Normal file
119
ES_MODULE_MIGRATION_PLAN.md
Normal file
|
|
@ -0,0 +1,119 @@
|
||||||
|
# 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
|
||||||
Loading…
Add table
Add a link
Reference in a new issue