@fleetbase/ember-core 0.3.10 → 0.3.12

package/UNIVERSE_REFACTOR_MIGRATION_GUIDE.md

@@ -1,318 +0,0 @@
-# UniverseService Refactor Migration Guide
-
-## Overview
-
-The UniverseService has been completely refactored to improve performance, maintainability, and developer experience. This guide will help you migrate your extensions to the new architecture.
-
-## What Changed?
-
-### 1. Service Decomposition
-
-The monolithic `UniverseService` has been split into specialized services:
-
-- **ExtensionManager**: Manages lazy loading of engines
-- **RegistryService**: Manages all registries using Ember's container
-- **MenuService**: Manages menu items and panels
-- **WidgetService**: Manages dashboard widgets
-- **HookService**: Manages application hooks
-
-The original `UniverseService` now acts as a facade, delegating to these services while maintaining backward compatibility.
-
-### 2. Contract System
-
-New contract classes provide a fluent, type-safe API:
-
-- `ExtensionComponent`: Lazy-loadable component definitions
-- `MenuItem`: Menu item definitions
-- `MenuPanel`: Menu panel definitions
-- `Hook`: Hook definitions
-- `Widget`: Widget definitions
-- `Registry`: Registry namespace definitions
-
-### 3. Lazy Loading Architecture
-
-The old `bootEngines` mechanism has been replaced with on-demand lazy loading:
-
-- Engines are no longer loaded at boot time
-- Components are loaded only when needed
-- The `<LazyEngineComponent>` wrapper handles lazy loading automatically
-
-## Migration Steps
-
-### Step 1: Create `extension.js` File
-
-Each engine should create a new `addon/extension.js` file to replace the `setupExtension` method in `engine.js`.
-
-**Before (`addon/engine.js`):**
-
-```javascript
-import NavigatorAppComponent from './components/admin/navigator-app';
-
-export default class FleetOpsEngine extends Engine {
-    setupExtension = function (app, engine, universe) {
-        universe.registerHeaderMenuItem('Fleet-Ops', 'console.fleet-ops', {
-            icon: 'route',
-            priority: 0
-        });
-
-        universe.registerAdminMenuPanel('Fleet-Ops Config', [
-            {
-                title: 'Navigator App',
-                component: NavigatorAppComponent
-            }
-        ]);
-    };
-}
-```
-
-**After (`addon/extension.js`):**
-
-```javascript
-import { MenuItem, MenuPanel, ExtensionComponent } from '@fleetbase/ember-core/contracts';
-
-export default function (app, universe) {
-    // Register header menu item
-    universe.registerHeaderMenuItem(
-        new MenuItem('Fleet-Ops', 'console.fleet-ops')
-            .withIcon('route')
-            .withPriority(0)
-    );
-
-    // Register admin panel with lazy component
-    universe.registerAdminMenuPanel(
-        new MenuPanel('Fleet-Ops Config')
-            .addItem(
-                new MenuItem('Navigator App')
-                    .withIcon('location-arrow')
-                    .withComponent(
-                        new ExtensionComponent('@fleetbase/fleetops-engine', 'components/admin/navigator-app')
-                    )
-            )
-    );
-}
-```
-
-**After (`addon/engine.js`):**
-
-```javascript
-// Remove the setupExtension method entirely
-export default class FleetOpsEngine extends Engine {
-    // ... other engine configuration
-}
-```
-
-### Step 2: Use Contract Classes
-
-Instead of plain objects, use the new contract classes for better type safety and developer experience.
-
-**Before:**
-
-```javascript
-universe.registerWidget({
-    widgetId: 'fleet-ops-metrics',
-    name: 'Fleet-Ops Metrics',
-    icon: 'truck',
-    component: WidgetComponent,
-    grid_options: { w: 12, h: 12 }
-});
-```
-
-**After:**
-
-```javascript
-import { Widget, ExtensionComponent } from '@fleetbase/ember-core/contracts';
-
-universe.registerDashboardWidgets([
-    new Widget('fleet-ops-metrics')
-        .withName('Fleet-Ops Metrics')
-        .withIcon('truck')
-        .withComponent(
-            new ExtensionComponent('@fleetbase/fleetops-engine', 'components/widget/fleet-ops-key-metrics')
-        )
-        .withGridOptions({ w: 12, h: 12 })
-]);
-```
-
-### Step 3: Update Component References
-
-Replace direct component imports with lazy component definitions.
-
-**Before:**
-
-```javascript
-import MyComponent from './components/my-component';
-
-universe.registerMenuItem('my-registry', 'My Item', {
-    component: MyComponent
-});
-```
-
-**After:**
-
-```javascript
-import { MenuItem, ExtensionComponent } from '@fleetbase/ember-core/contracts';
-
-universe.registerMenuItem(
-    'my-registry',
-    new MenuItem('My Item')
-        .withComponent(
-            new ExtensionComponent('@fleetbase/my-engine', 'components/my-component')
-        )
-);
-```
-
-### Step 4: Update Templates Using Registry Components
-
-Templates that render components from registries need to use the `<LazyEngineComponent>` wrapper.
-
-**Before:**
-
-```handlebars
-{{#each this.menuItems as |item|}}
-    {{component item.component model=@model}}
-{{/each}}
-```
-
-**After:**
-
-```handlebars
-{{#each this.menuItems as |item|}}
-    <LazyEngineComponent @componentDef={{item.component}} @model={{@model}} />
-{{/each}}
-```
-
-### Step 5: Update Hook Registrations
-
-Use the new `Hook` contract for better hook management.
-
-**Before:**
-
-```javascript
-universe.registerHook('application:before-model', (session, router) => {
-    if (session.isCustomer) {
-        router.transitionTo('customer-portal');
-    }
-});
-```
-
-**After:**
-
-```javascript
-import { Hook } from '@fleetbase/ember-core/contracts';
-
-universe.registerHook(
-    new Hook('application:before-model', (session, router) => {
-        if (session.isCustomer) {
-            router.transitionTo('customer-portal');
-        }
-    })
-        .withPriority(10)
-        .withId('customer-redirect')
-);
-```
-
-## Backward Compatibility
-
-The refactored `UniverseService` maintains backward compatibility with the old API. You can continue using the old syntax while migrating:
-
-```javascript
-// Old syntax still works
-universe.registerHeaderMenuItem('My Item', 'my.route', { icon: 'star' });
-
-// New syntax is preferred
-universe.registerHeaderMenuItem(
-    new MenuItem('My Item', 'my.route').withIcon('star')
-);
-```
-
-## Benefits of Migration
-
-1. **Performance**: Sub-second boot times with lazy loading
-2. **Type Safety**: Contract classes provide validation and IDE support
-3. **Maintainability**: Specialized services are easier to understand and modify
-4. **Developer Experience**: Fluent API with method chaining
-5. **Extensibility**: Easy to add new features without breaking changes
-
-## Common Patterns
-
-### Menu Item with Click Handler
-
-```javascript
-new MenuItem('Track Order')
-    .withIcon('barcode')
-    .withType('link')
-    .withWrapperClass('btn-block py-1 border')
-    .withComponent(
-        new ExtensionComponent('@fleetbase/fleetops-engine', 'components/order-tracking-lookup')
-    )
-    .onClick((menuItem) => {
-        universe.transitionMenuItem('virtual', menuItem);
-    })
-```
-
-### Widget with Refresh Interval
-
-```javascript
-new Widget('live-metrics')
-    .withName('Live Metrics')
-    .withComponent(
-        new ExtensionComponent('@fleetbase/my-engine', 'components/widget/live-metrics')
-            .withLoadingComponent('skeletons/widget')
-    )
-    .withRefreshInterval(5000)
-    .asDefault()
-```
-
-### Hook with Priority and Once
-
-```javascript
-new Hook('order:before-save')
-    .withPriority(10)
-    .once()
-    .execute(async (order) => {
-        await validateOrder(order);
-    })
-```
-
-## Troubleshooting
-
-### Component Not Found Error
-
-If you see "Component not found in engine" errors:
-
-1. Check that the component path is correct
-2. Ensure the engine name matches exactly
-3. Verify the component exists in the engine
-
-### Loading Spinner Not Showing
-
-If the loading spinner doesn't appear:
-
-1. Check that you're using `<LazyEngineComponent>` in templates
-2. Verify the `componentDef` is a lazy definition object
-3. Ensure the loading component exists
-
-### Hooks Not Executing
-
-If hooks aren't running:
-
-1. Check the hook name matches exactly
-2. Verify the hook is registered before it's needed
-3. Use `universe.hookService.getHooks(hookName)` to debug
-
-## Support
-
-For questions or issues with the migration, please:
-
-1. Check the contract class documentation in `addon/contracts/`
-2. Review the service documentation in `addon/services/universe/`
-3. Open an issue on GitHub with details about your migration challenge
-
-## Timeline
-
-- **Phase 1**: Refactored services are available, old API still works
-- **Phase 2**: Extensions migrate to new `extension.js` pattern
-- **Phase 3**: Deprecation warnings for old patterns
-- **Phase 4**: Old `setupExtension` pattern removed (future release)
-
-You can migrate at your own pace. The new architecture is fully backward compatible.

package/UNIVERSE_REFACTOR_README.md

@@ -1,220 +0,0 @@
-# UniverseService Refactor
-
-## Overview
-
-This refactor addresses critical performance and architectural issues in the UniverseService by decomposing it into specialized services, introducing a contract system, and implementing true lazy loading for engines.
-
-## Problems Solved
-
-### 1. Performance Bottleneck
-
-**Before**: 10-40 second initial load time due to sequential `bootEngines` process loading all extensions upfront.
-
-**After**: <1 second initial load time with on-demand lazy loading.
-
-### 2. Monolithic Design
-
-**Before**: 1,978 lines handling 7+ distinct responsibilities in a single service.
-
-**After**: Specialized services with clear separation of concerns:
-- `ExtensionManager`: Engine lifecycle and lazy loading
-- `RegistryService`: Registry management using Ember's container
-- `MenuService`: Menu items and panels
-- `WidgetService`: Dashboard widgets
-- `HookService`: Application hooks
-
-### 3. Inefficient Registry
-
-**Before**: Custom object-based registry with O(n) lookups.
-
-**After**: Ember container-based registry with O(1) lookups.
-
-### 4. Broken Lazy Loading
-
-**Before**: `bootEngines` manually boots and initializes every engine, breaking lazy loading.
-
-**After**: Engines load on-demand when their components are actually needed.
-
-## Architecture
-
-```
-┌─────────────────────────────────────────────────────────────┐
-│                    UniverseService (Facade)                  │
-│  Maintains backward compatibility while delegating to:      │
-└─────────────────────────────────────────────────────────────┘
-                            │
-        ┌───────────────────┼───────────────────┐
-        │                   │                   │
-        ▼                   ▼                   ▼
-┌──────────────┐    ┌──────────────┐    ┌──────────────┐
-│  Extension   │    │   Registry   │    │     Menu     │
-│   Manager    │    │   Service    │    │   Service    │
-└──────────────┘    └──────────────┘    └──────────────┘
-        │                   │                   │
-        ▼                   ▼                   ▼
-┌──────────────┐    ┌──────────────┐    ┌──────────────┐
-│    Widget    │    │     Hook     │    │   Contract   │
-│   Service    │    │   Service    │    │    System    │
-└──────────────┘    └──────────────┘    └──────────────┘
-```
-
-## Contract System
-
-New classes provide a fluent, type-safe API for extension definitions:
-
-```javascript
-import { MenuItem, ExtensionComponent, Widget, Hook } from '@fleetbase/ember-core/contracts';
-
-// Menu item with lazy component
-new MenuItem('Fleet-Ops', 'console.fleet-ops')
-    .withIcon('route')
-    .withPriority(0)
-    .withComponent(
-        new ExtensionComponent('@fleetbase/fleetops-engine', 'components/admin/navigator-app')
-    );
-
-// Widget with grid options
-new Widget('fleet-ops-metrics')
-    .withName('Fleet-Ops Metrics')
-    .withIcon('truck')
-    .withComponent(
-        new ExtensionComponent('@fleetbase/fleetops-engine', 'components/widget/metrics')
-    )
-    .withGridOptions({ w: 12, h: 12 })
-    .asDefault();
-
-// Hook with priority
-new Hook('application:before-model', (session, router) => {
-    if (session.isCustomer) {
-        router.transitionTo('customer-portal');
-    }
-})
-    .withPriority(10)
-    .once();
-```
-
-## Lazy Loading Flow
-
-1. **Boot Time**: Only `extension.js` files are loaded (no engine code)
-2. **Registration**: Metadata is registered (menus, widgets, hooks)
-3. **Runtime**: When a component needs to render:
-   - `<LazyEngineComponent>` triggers `extensionManager.ensureEngineLoaded()`
-   - Engine bundle is fetched and loaded
-   - Component is looked up from the engine
-   - Component is rendered
-
-## Extension Pattern
-
-### Old Pattern (engine.js)
-
-```javascript
-import MyComponent from './components/my-component';
-
-export default class MyEngine extends Engine {
-    setupExtension = function (app, engine, universe) {
-        universe.registerMenuItem('my-registry', 'My Item', {
-            component: MyComponent  // Loads entire engine!
-        });
-    };
-}
-```
-
-### New Pattern (extension.js)
-
-```javascript
-import { MenuItem, ExtensionComponent } from '@fleetbase/ember-core/contracts';
-
-export default function (app, universe) {
-    universe.registerMenuItem(
-        'my-registry',
-        new MenuItem('My Item')
-            .withComponent(
-                new ExtensionComponent('@fleetbase/my-engine', 'components/my-component')
-            )
-    );
-}
-```
-
-**Key Difference**: No component imports = no engine loading at boot time.
-
-## Performance Improvements
-
-| Metric | Before | After | Improvement |
-|--------|--------|-------|-------------|
-| Initial Load Time | 10-40s | <1s | ~90% faster |
-| Bundle Size (initial) | Full app + all engines | Core app only | ~60% reduction |
-| Lookup Performance | O(n) | O(1) | 100x faster |
-| Timeout Errors | Frequent | None | 100% reduction |
-
-## Backward Compatibility
-
-The refactor is **100% backward compatible**. The old API still works:
-
-```javascript
-// Old syntax (still works)
-universe.registerHeaderMenuItem('My Item', 'my.route', { icon: 'star' });
-
-// New syntax (preferred)
-universe.registerHeaderMenuItem(
-    new MenuItem('My Item', 'my.route').withIcon('star')
-);
-```
-
-## Migration
-
-See [UNIVERSE_REFACTOR_MIGRATION_GUIDE.md](./UNIVERSE_REFACTOR_MIGRATION_GUIDE.md) for detailed migration instructions.
-
-## Files Changed
-
-### New Files
-
-- `addon/contracts/` - Contract system classes
-  - `base-contract.js`
-  - `extension-component.js`
-  - `menu-item.js`
-  - `menu-panel.js`
-  - `hook.js`
-  - `widget.js`
-  - `registry.js`
-  - `index.js`
-
-- `addon/services/universe/` - Specialized services
-  - `extension-manager.js`
-  - `registry-service.js`
-  - `menu-service.js`
-  - `widget-service.js`
-  - `hook-service.js`
-
-- `addon/components/` - Lazy loading component
-  - `lazy-engine-component.js`
-  - `lazy-engine-component.hbs`
-
-### Modified Files
-
-- `addon/services/universe.js` - Refactored as facade
-- `addon/services/legacy-universe.js` - Original service (for reference)
-
-## Testing
-
-The refactor includes:
-
-1. **Unit tests** for each contract class
-2. **Integration tests** for each service
-3. **Acceptance tests** for lazy loading behavior
-4. **Performance benchmarks** comparing old vs new
-
-## Future Enhancements
-
-1. **TypeScript definitions** for contract classes
-2. **Extension manifest validation** at build time
-3. **Preloading strategies** for critical engines
-4. **Memory management** for long-running applications
-5. **Developer tools** for debugging extension loading
-
-## Credits
-
-Designed and implemented based on collaborative analysis with Ronald A Richardson, CTO of Fleetbase.
-
-## License
-
-MIT License - Copyright (c) 2025 Fleetbase