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
|
||||
Loading…
Add table
Add a link
Reference in a new issue