ezfw-core 1.0.0

package/core/ez.ts

@@ -0,0 +1,617 @@
+import { EzError } from './EzError.js';
+import { EzRouter, RouteDefinition, MiddlewareFunction, RouteInfo } from './router.js';
+import { EzLoader } from './loader.js';
+import { EzRenderer, ComponentConfig } from './renderer.js';
+import { EzState, ControllerDefinition, GridControllerDefinition, GridBehaviorDefinition } from './state.js';
+import { EzModel, ModelDefinition, Model } from './EzModel.js';
+import { EzServices } from './services.js';
+import { EzEventBus, EventHandler } from './eventBus.js';
+import * as EzGridQuery from '../components/grid/query/EzGridQuery.js';
+import moment from 'moment';
+import { createEzStore } from '../components/store/EzStore.js';
+import { EzUtils, format, capitalize, capitalizeWords, truncate, pluralize, FormatType, FormatOptions } from './utils.js';
+import { ComponentDefinition, ControllerDef } from './EzTypes.js';
+
+declare global {
+    interface Window {
+        ez: EzFramework;
+    }
+}
+
+interface StoreEntry {
+    config: Record<string, unknown>;
+    instance: unknown | null;
+}
+
+interface RegistryMeta {
+    definedIn?: string;
+}
+
+interface EzContext {
+    route: string | null;
+    view: string | null;
+    controller: string | null;
+}
+
+export interface EzFramework {
+    _registry: Record<string, unknown>;
+    _controllers: Record<string, ControllerDefinition>;
+    _models: Record<string, Model>;
+    _stores: Record<string, StoreEntry>;
+    _refs: Record<string, unknown>;
+    _registryMeta: Record<string, RegistryMeta>;
+    _context: EzContext;
+    _gridControllerDefinitions: Record<string, GridControllerDefinition>;
+    _gridStateRegistry: Record<string, unknown>;
+    _gridBehaviorDefinitions: Record<string, GridBehaviorDefinition>;
+    _gridBehaviors: Record<string, GridBehaviorDefinition>;
+    _styles: Record<string, () => Promise<unknown>>;
+    _stylesCache: Record<string, Record<string, string>>;
+    _theme: string;
+    _availableThemes: string[];
+    _router: EzRouter | null;
+    _loader: EzLoader | null;
+    _renderer: EzRenderer | null;
+    _state: EzState | null;
+    _model: EzModel | null;
+    _services: EzServices | null;
+    _eventBus: EzEventBus | null;
+    grid?: { query: typeof EzGridQuery };
+    moment: typeof moment;
+
+    _initModules(): Promise<void>;
+    /**
+     * Define a component in the Ez framework
+     * @param name - Unique component name (used as eztype)
+     * @param definition - Component configuration:
+     * ```
+     * {
+     *   eztype?: string        // Base component to extend
+     *   css?: string           // CSS module name (auto-loads .module.scss)
+     *   controller?: string    // Controller name for state
+     *   cls?: string | string[] // CSS classes
+     *   layout?: 'hbox'|'vbox' // Flex direction
+     *   style?: object         // Inline styles
+     *   items?: ItemConfig[]   // Static children
+     *   template?: (props) => ItemConfig  // Dynamic render function
+     *   bind?: BindConfig      // Data bindings
+     *   itemRender?: (item, index) => ItemConfig  // List item renderer
+     *   onLoad?: string        // Async load method (controller)
+     *   fallback?: ItemConfig  // Loading placeholder
+     *   ref?: string           // Reference name for ez._refs
+     * }
+     * ```
+     */
+    define(name: string, definition: ComponentDefinition): void;
+    /**
+     * Define a controller for state management
+     * @param name - Controller name (referenced by component's controller property)
+     * @param definition - Controller configuration:
+     * ```
+     * {
+     *   state?: object              // Reactive state (auto-wrapped with deepSignal)
+     *   onInit?: () => void         // Called when controller initializes
+     *   onRouteChange?: (params) => void  // Called on route changes
+     *   onDestroy?: () => void      // Called when controller is destroyed
+     *   [methodName]: Function      // Custom methods (access state via this.state)
+     * }
+     * ```
+     */
+    defineController(name: string, definition: ControllerDefinition): void;
+    /**
+     * Define a grid-specific controller for EzGrid lifecycle hooks
+     * @param name - Grid controller name (referenced by grid's gridController property)
+     * @param definition - Grid controller configuration:
+     * ```
+     * {
+     *   onInit?: () => void              // Called when grid initializes
+     *   beforeDataRender?: () => void    // Called before rendering data
+     *   afterDataRender?: () => void     // Called after rendering data
+     *   onSelectionChange?: (rows) => void  // Called when selection changes
+     *   onRowClick?: (row, e) => void    // Called on row click
+     *   onCellClick?: (cell, row, e) => void  // Called on cell click
+     * }
+     * ```
+     */
+    defineGridController(name: string, definition: GridControllerDefinition): void;
+    /**
+     * Define a data model for type coercion and validation
+     * @param name - Model name (referenced by component's model property)
+     * @param definition - Model configuration:
+     * ```
+     * {
+     *   fields: [
+     *     { name: 'id', type: 'int', primaryKey: true },
+     *     { name: 'email', type: 'string' },
+     *     { name: 'age', type: 'int', default: 0 },
+     *     { name: 'active', type: 'bool', nullable: true },
+     *     { name: 'fullName', compute: (r) => r.first + ' ' + r.last }
+     *   ]
+     * }
+     * ```
+     * Types: 'int' | 'float' | 'string' | 'bool' | 'date' | 'array' | 'object'
+     */
+    defineModel(name: string, definition: ModelDefinition): void;
+    getModel(name: string): Model | null;
+    getModelSync(name: string): Model;
+    /**
+     * Define a global store for shared state across components
+     * @param name - Store name
+     * @param config - Store configuration:
+     * ```
+     * {
+     *   state: { ... },            // Initial state
+     *   getters: { ... },          // Computed values
+     *   actions: { ... }           // Methods to modify state
+     * }
+     * ```
+     */
+    defineStore(name: string, config: Record<string, unknown>): void;
+    getStore(name: string): unknown;
+    registerComponent(eztype: string, cls: unknown): void;
+    installModules(mods: Record<string, () => Promise<unknown>>): void;
+    installStyles(styles: Record<string, () => Promise<unknown>>): void;
+    hasStyles(name: string): boolean;
+    resolveStyles(name: string): Promise<Record<string, string> | null>;
+    get(name: string): unknown;
+    getController(name: string): Promise<ControllerDefinition> | ControllerDefinition;
+    getControllerSync(name: string): ControllerDefinition;
+    _createElement(config: ComponentConfig, controllerName?: string | null, inheritedState?: unknown): Promise<Node>;
+    _createChildElements(items: ComponentConfig[], controllerName: string | null, inheritedState: unknown, parentCss?: string | null): Promise<Node[]>;
+    routes(routeDefs: RouteDefinition[]): void;
+    go(path: string): void;
+    navigate(viewName: string, route?: RouteInfo | null): Promise<void>;
+    installPopStateListener(): void;
+    prefetch(path: string): Promise<void>;
+    enableLinkPrefetch(): void;
+    beforeEach(fn: MiddlewareFunction): () => void;
+    afterEach(fn: MiddlewareFunction): () => void;
+    onNavigationError(fn: (error: Error, context: unknown) => void): () => void;
+    setNetworkAware(enabled?: boolean): void;
+    getNetworkInfo(): { strategy: string; online: boolean; effectiveType: string | null; saveData: boolean };
+    addPreloadHint(eztype: string): boolean;
+    addPreloadHintsForRoute(routePath: string): Promise<number>;
+    addPreloadHintsForAdjacentRoutes(): Promise<number>;
+    _onLocationChange(): Promise<void>;
+    on(event: string, fn: EventHandler['fn'], context?: object | null): () => boolean;
+    once(event: string, fn: EventHandler['fn'], context?: object | null): () => boolean;
+    off(event: string, fn?: EventHandler['fn']): boolean;
+    emit(event: string, data?: unknown): boolean;
+    emitAsync(event: string, data?: unknown): Promise<boolean>;
+    eventNamespace(namespace: string): unknown;
+    /**
+     * Define a reusable grid behavior (plugin pattern)
+     * @param name - Behavior name (referenced by grid's behaviors array)
+     * @param definition - Behavior configuration:
+     * ```
+     * {
+     *   onInit?: (grid) => void           // Called when behavior attaches
+     *   onDestroy?: (grid) => void        // Called when behavior detaches
+     *   onDataChange?: (data, grid) => void  // Called when data changes
+     *   [hookName]: Function              // Custom hooks
+     * }
+     * ```
+     */
+    defineGridBehavior(name: string, definition: GridBehaviorDefinition): void;
+    getGridBehavior(name: string): Promise<GridBehaviorDefinition | null>;
+    getDeepValue(obj: Record<string, unknown>, pathArray: string[]): unknown;
+    setDeepValue(obj: Record<string, unknown>, props: string[], value: unknown): void;
+    handleFrameworkError(error: Error | EzError): void;
+    _api: unknown;
+    _fb: unknown;
+    crypto: unknown;
+    routeUI: unknown;
+    dialog: unknown;
+    toast: unknown;
+    setTheme(themeName: string): void;
+    getTheme(): string;
+    getAvailableThemes(): string[];
+    toggleDarkMode(): string;
+    isDarkMode(): boolean;
+    _initTheme(): void;
+    format(value: unknown, type?: FormatType, options?: FormatOptions): string;
+    capitalize(str: string): string;
+    capitalizeWords(str: string): string;
+    truncate(str: string, length: number, suffix?: string): string;
+    pluralize(count: number, singular: string, plural?: string): string;
+    utils: typeof EzUtils;
+}
+
+const ez: EzFramework = {
+    _registry: {},
+    _controllers: {},
+    _models: {},
+    _stores: {},
+    _refs: {},
+    _registryMeta: {},
+    _context: {
+        route: null,
+        view: null,
+        controller: null
+    },
+    _gridControllerDefinitions: {},
+    _gridStateRegistry: {},
+    _gridBehaviorDefinitions: {},
+    _gridBehaviors: {},
+    _styles: {},
+    _stylesCache: {},
+    _theme: 'ocean-depths',
+    _availableThemes: [
+        'ocean-depths',
+        'ocean-depths-dark',
+        'nature-fresh',
+        'nature-fresh-dark'
+    ],
+    _router: null,
+    _loader: null,
+    _renderer: null,
+    _state: null,
+    _model: null,
+    _services: null,
+    _eventBus: null,
+    moment: moment,
+
+    async _initModules(): Promise<void> {
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any
+        const ezInstance = this as any;
+        this._loader = new EzLoader(ezInstance);
+        this._router = new EzRouter(ezInstance);
+        this._renderer = new EzRenderer(ezInstance);
+        this._state = new EzState(ezInstance);
+        this._model = new EzModel(ezInstance);
+        this._services = new EzServices(ezInstance);
+        this._eventBus = new EzEventBus();
+        await this._services.init();
+    },
+
+    define(name: string, definition: ComponentDefinition): void {
+        if (this._registry[name]) {
+            throw new EzError({
+                code: 'EZ_DEFINE_DUPLICATE',
+                message: `Component "${name}" is already defined`,
+                details: {
+                    eztype: name,
+                    definedIn: this._registryMeta[name]?.definedIn,
+                    redefinedIn: this._loader?.getCurrentModulePath()
+                }
+            });
+        }
+
+        this._registry[name] = definition;
+
+        this._registryMeta[name] = {
+            definedIn: this._loader?.getCurrentModulePath() || undefined
+        };
+    },
+
+    defineController(name: string, definition: ControllerDefinition): void {
+        this._state!.defineController(name, definition);
+    },
+
+    defineGridController(name: string, definition: GridControllerDefinition): void {
+        this._state!.defineGridController(name, definition);
+    },
+
+    defineModel(name: string, definition: ModelDefinition): void {
+        this._model!.defineModel(name, definition);
+    },
+
+    getModel(name: string): Model | null {
+        return this._model!.getModel(name);
+    },
+
+    getModelSync(name: string): Model {
+        return this._model!.getModelSync(name);
+    },
+
+    defineStore(name: string, config: Record<string, unknown>): void {
+        if (this._stores[name]) {
+            console.warn(`[Ez] Store "${name}" already defined, overwriting.`);
+        }
+        this._stores[name] = { config, instance: null };
+    },
+
+    getStore(name: string): unknown {
+        const entry = this._stores[name];
+        if (!entry) {
+            console.warn(`[Ez] Store "${name}" not found.`);
+            return null;
+        }
+        if (!entry.instance) {
+            entry.instance = createEzStore(entry.config as Parameters<typeof createEzStore>[0]);
+        }
+        return entry.instance;
+    },
+
+    registerComponent(eztype: string, cls: unknown): void {
+        this._registry[eztype] = cls;
+    },
+
+    installModules(mods: Record<string, () => Promise<unknown>>): void {
+        this._loader!.installModules(mods);
+    },
+
+    installStyles(styles: Record<string, () => Promise<unknown>>): void {
+        this._styles = styles;
+    },
+
+    hasStyles(name: string): boolean {
+        if (!name || !this._styles) return false;
+        const lowerName = name.toLowerCase();
+        return Object.keys(this._styles).some(p => {
+            const fileName = p.split('/').pop()?.toLowerCase();
+            return fileName === `${lowerName}.module.scss`;
+        });
+    },
+
+    async resolveStyles(name: string): Promise<Record<string, string> | null> {
+        if (this._stylesCache[name]) {
+            return this._stylesCache[name];
+        }
+
+        const lowerName = name.toLowerCase();
+        const path = Object.keys(this._styles).find(p => {
+            const fileName = p.split('/').pop()?.toLowerCase();
+            return fileName === `${lowerName}.module.scss`;
+        });
+
+        if (!path) {
+            const env = (import.meta as unknown as { env?: { DEV?: boolean } }).env;
+            if (env?.DEV) {
+                console.warn(`[Ez] CSS module "${name}" not found`);
+            }
+            return null;
+        }
+
+        const module = await this._styles[path]();
+        const styles = (module as { default?: Record<string, string> }).default || module;
+
+        this._stylesCache[name] = styles as Record<string, string>;
+
+        return styles as Record<string, string>;
+    },
+
+    get(name: string): unknown {
+        return this._registry[name];
+    },
+
+    getController(name: string): Promise<ControllerDefinition> | ControllerDefinition {
+        return this._state!.getController(name);
+    },
+
+    getControllerSync(name: string): ControllerDefinition {
+        return this._state!.getControllerSync(name);
+    },
+
+    async _createElement(config: ComponentConfig, controllerName: string | null = null, inheritedState: unknown = null): Promise<Node> {
+        return this._renderer!.createElement(config, controllerName, inheritedState);
+    },
+
+    async _createChildElements(items: ComponentConfig[], controllerName: string | null, inheritedState: unknown, parentCss: string | null = null): Promise<Node[]> {
+        return this._renderer!.createChildElements(items, controllerName || '', inheritedState, parentCss);
+    },
+
+    routes(routeDefs: RouteDefinition[]): void {
+        this._router!.routes(routeDefs);
+    },
+
+    go(path: string): void {
+        this._router!.go(path);
+    },
+
+    async navigate(viewName: string, route: RouteInfo | null = null): Promise<void> {
+        return this._router!.navigate(viewName, route);
+    },
+
+    installPopStateListener(): void {
+        this._router!.installPopStateListener();
+    },
+
+    async prefetch(path: string): Promise<void> {
+        return this._router!.prefetch(path);
+    },
+
+    enableLinkPrefetch(): void {
+        this._router!.enableLinkPrefetch();
+    },
+
+    beforeEach(fn: MiddlewareFunction): () => void {
+        return this._router!.beforeEach(fn);
+    },
+
+    afterEach(fn: MiddlewareFunction): () => void {
+        return this._router!.afterEach(fn);
+    },
+
+    onNavigationError(fn: (error: Error, context: unknown) => void): () => void {
+        return this._router!.onError(fn as Parameters<EzRouter['onError']>[0]);
+    },
+
+    setNetworkAware(enabled: boolean = true): void {
+        this._loader!.setNetworkAware(enabled);
+    },
+
+    getNetworkInfo(): { strategy: string; online: boolean; effectiveType: string | null; saveData: boolean } {
+        return this._loader!.getNetworkInfo();
+    },
+
+    addPreloadHint(eztype: string): boolean {
+        return this._loader!.addPreloadHint(eztype);
+    },
+
+    async addPreloadHintsForRoute(routePath: string): Promise<number> {
+        return this._loader!.addPreloadHintsForRoute(routePath);
+    },
+
+    async addPreloadHintsForAdjacentRoutes(): Promise<number> {
+        return this._loader!.addPreloadHintsForAdjacentRoutes();
+    },
+
+    async _onLocationChange(): Promise<void> {
+        return (this._router as unknown as { _onLocationChange(): Promise<void> })._onLocationChange();
+    },
+
+    on(event: string, fn: EventHandler['fn'], context?: object | null): () => boolean {
+        return this._eventBus!.on(event, fn, context);
+    },
+
+    once(event: string, fn: EventHandler['fn'], context?: object | null): () => boolean {
+        return this._eventBus!.once(event, fn, context);
+    },
+
+    off(event: string, fn?: EventHandler['fn']): boolean {
+        return this._eventBus!.off(event, fn);
+    },
+
+    emit(event: string, data?: unknown): boolean {
+        return this._eventBus!.emit(event, data);
+    },
+
+    async emitAsync(event: string, data?: unknown): Promise<boolean> {
+        return this._eventBus!.emitAsync(event, data);
+    },
+
+    eventNamespace(namespace: string): unknown {
+        return this._eventBus!.namespace(namespace);
+    },
+
+    defineGridBehavior(name: string, definition: GridBehaviorDefinition): void {
+        this._state!.defineGridBehavior(name, definition);
+    },
+
+    async getGridBehavior(name: string): Promise<GridBehaviorDefinition | null> {
+        return this._state!.getGridBehavior(name);
+    },
+
+    getDeepValue(obj: Record<string, unknown>, pathArray: string[]): unknown {
+        return this._state!.getDeepValue(obj, pathArray);
+    },
+
+    setDeepValue(obj: Record<string, unknown>, props: string[], value: unknown): void {
+        this._state!.setDeepValue(obj, props, value);
+    },
+
+    handleFrameworkError(error: Error | EzError): void {
+        if (error instanceof EzError) {
+            console.group(`EZ Framework Error — ${error.code}`);
+            console.error(error.message);
+            console.info('Source:', error.source);
+            console.info('Route:', error.route);
+            console.info('View:', error.view);
+            if (error.details) {
+                console.info('Details:', error.details);
+            }
+            if (error.cause) {
+                console.error('Cause:', error.cause);
+            }
+            console.groupEnd();
+        } else {
+            console.error('[EZ] Unhandled error:', error);
+        }
+    },
+
+    get _api(): unknown {
+        return this._services?.api;
+    },
+
+    get _fb(): unknown {
+        return this._services?.firebase;
+    },
+
+    get crypto(): unknown {
+        return this._services?.crypto;
+    },
+
+    get routeUI(): unknown {
+        return this._services?.routeUI;
+    },
+
+    get dialog(): unknown {
+        return this._services?.dialog;
+    },
+
+    get toast(): unknown {
+        return this._services?.toast;
+    },
+
+    setTheme(themeName: string): void {
+        if (!this._availableThemes.includes(themeName)) {
+            console.warn(`[ez] Theme "${themeName}" not found. Available: ${this._availableThemes.join(', ')}`);
+            return;
+        }
+
+        this._theme = themeName;
+        document.documentElement.setAttribute('data-ez-theme', themeName);
+
+        try {
+            localStorage.setItem('ez-theme', themeName);
+        } catch {
+            // localStorage not available
+        }
+
+        this._eventBus?.emit('theme:change', { theme: themeName });
+    },
+
+    getTheme(): string {
+        return this._theme;
+    },
+
+    getAvailableThemes(): string[] {
+        return [...this._availableThemes];
+    },
+
+    toggleDarkMode(): string {
+        const current = this._theme;
+        let newTheme: string;
+
+        if (current.endsWith('-dark')) {
+            newTheme = current.replace('-dark', '');
+        } else {
+            newTheme = current + '-dark';
+        }
+
+        if (this._availableThemes.includes(newTheme)) {
+            this.setTheme(newTheme);
+        }
+
+        return this._theme;
+    },
+
+    isDarkMode(): boolean {
+        return this._theme.endsWith('-dark');
+    },
+
+    _initTheme(): void {
+        try {
+            const saved = localStorage.getItem('ez-theme');
+            if (saved && this._availableThemes.includes(saved)) {
+                this.setTheme(saved);
+                return;
+            }
+        } catch {
+            // localStorage not available
+        }
+
+        document.documentElement.setAttribute('data-ez-theme', this._theme);
+    },
+
+    format,
+    capitalize,
+    capitalizeWords,
+    truncate,
+    pluralize,
+    utils: EzUtils
+};
+
+await ez._initModules();
+ez._initTheme();
+
+window.ez = ez;
+
+ez.grid ??= { query: EzGridQuery };
+ez.grid.query = EzGridQuery;
+
+export { ez };
+export default ez;
+export type { ComponentDefinition, ControllerDef, ItemConfig, BindConfig } from './EzTypes.js';
+export type { EzItemConfig } from './EzComponentTypes.js';