ezfw-core 1.0.0

package/core/state.ts

@@ -0,0 +1,142 @@
+import { deepSignal } from 'deepsignal';
+import { EzError } from './EzError.js';
+
+export interface ControllerDefinition {
+    state?: Record<string, unknown>;
+    getState?: (key?: string) => unknown;
+    [key: string]: unknown;
+}
+
+export interface GridControllerDefinition {
+    onInit?: () => void | Promise<void>;
+    beforeDataRender?: () => void | Promise<void>;
+    afterDataRender?: () => void | Promise<void>;
+    [key: string]: unknown;
+}
+
+export interface GridBehaviorDefinition {
+    onInit?: () => void | Promise<void>;
+    [key: string]: unknown;
+}
+
+interface EzInstance {
+    _controllers: Record<string, ControllerDefinition>;
+    _gridControllerDefinitions: Record<string, GridControllerDefinition>;
+    _gridBehaviors: Record<string, GridBehaviorDefinition>;
+    _loader: {
+        resolveController: (name: string) => Promise<void>;
+        resolveGridBehavior: (name: string) => Promise<void>;
+    };
+    _context: {
+        route?: string;
+        view?: string;
+    };
+}
+
+export class EzState {
+    private ez: EzInstance;
+
+    constructor(ez: EzInstance) {
+        this.ez = ez;
+    }
+
+    defineController(name: string, definition: ControllerDefinition): void {
+        definition.state = deepSignal(definition.state || {});
+
+        definition.getState = (key: string = '') => {
+            if (!key) return definition.state;
+            return (definition.state as Record<string, unknown>)[key];
+        };
+
+        this.ez._controllers[name] = definition;
+    }
+
+    getController(name: string): ControllerDefinition | Promise<ControllerDefinition> {
+        if (this.ez._controllers[name]) return this.ez._controllers[name];
+
+        return (async () => {
+            await this.ez._loader.resolveController(name);
+            return this.ez._controllers[name];
+        })();
+    }
+
+    getControllerSync(name: string): ControllerDefinition {
+        const ctrl = this.ez._controllers[name];
+        if (!ctrl) {
+            throw new EzError({
+                code: 'EZ_CONTROLLER_002',
+                source: 'controller',
+                message: `Controller "${name}" accessed before being resolved`,
+                route: this.ez._context.route,
+                view: this.ez._context.view
+            });
+        }
+        return ctrl;
+    }
+
+    defineGridController(name: string, definition: GridControllerDefinition): void {
+        if (!name) {
+            throw new EzError({
+                code: 'EZ_GRID_CTRL_001',
+                message: 'defineGridController requires a "gridController" name'
+            });
+        }
+
+        if (this.ez._gridControllerDefinitions[name]) {
+            throw new EzError({
+                code: 'EZ_GRID_CTRL_002',
+                message: `GridController "${name}" already defined`
+            });
+        }
+
+        this.ez._gridControllerDefinitions[name] = definition;
+    }
+
+    defineGridBehavior(name: string, definition: GridBehaviorDefinition): void {
+        if (!name) return;
+
+        this.ez._gridBehaviors[name] = definition;
+    }
+
+    async getGridBehavior(name: string): Promise<GridBehaviorDefinition | null> {
+        if (!name) return null;
+
+        if (this.ez._gridBehaviors[name]) {
+            return this.ez._gridBehaviors[name];
+        }
+
+        await this.ez._loader.resolveGridBehavior(name);
+
+        const behavior = this.ez._gridBehaviors[name];
+
+        if (!behavior) {
+            throw new EzError({
+                code: 'EZ_GRID_BEHAVIOR_INVALID',
+                source: 'grid',
+                message: `GridBehavior "${name}" was loaded but did not register itself`,
+                route: this.ez._context?.route,
+                view: this.ez._context?.view
+            });
+        }
+
+        return behavior;
+    }
+
+    getDeepValue(obj: Record<string, unknown>, pathArray: string[]): unknown {
+        return pathArray.reduce((acc: unknown, key: string) => {
+            if (acc && typeof acc === 'object') {
+                return (acc as Record<string, unknown>)[key];
+            }
+            return undefined;
+        }, obj);
+    }
+
+    setDeepValue(obj: Record<string, unknown>, props: string[], value: unknown): void {
+        let target: Record<string, unknown> = obj;
+        for (let i = 0; i < props.length - 1; i++) {
+            const key = props[i];
+            target = target[key] as Record<string, unknown>;
+        }
+        target[props[props.length - 1]] = value;
+    }
+}

package/core/utils.ts

@@ -0,0 +1,81 @@
+export type FormatType = 'currency' | 'percentage' | 'number' | 'compact';
+
+export interface FormatOptions {
+    locale?: string;
+    currency?: string;
+    decimals?: number;
+}
+
+export function format(value: unknown, type?: FormatType, options: FormatOptions = {}): string {
+    const { locale = 'en-US', currency = 'USD', decimals } = options;
+
+    if (value === null || value === undefined) return '';
+    if (typeof value !== 'number') return String(value);
+
+    switch (type) {
+        case 'currency':
+            return new Intl.NumberFormat(locale, {
+                style: 'currency',
+                currency,
+                minimumFractionDigits: decimals ?? 2,
+                maximumFractionDigits: decimals ?? 2
+            }).format(value);
+
+        case 'percentage':
+            return new Intl.NumberFormat(locale, {
+                style: 'percent',
+                minimumFractionDigits: decimals ?? 0,
+                maximumFractionDigits: decimals ?? 2
+            }).format(value / 100);
+
+        case 'compact':
+            return new Intl.NumberFormat(locale, {
+                notation: 'compact',
+                compactDisplay: 'short'
+            }).format(value);
+
+        case 'number':
+        default:
+            return value.toLocaleString(locale, {
+                minimumFractionDigits: decimals,
+                maximumFractionDigits: decimals
+            });
+    }
+}
+
+export function capitalize(str: string): string {
+    if (!str) return '';
+    return str.charAt(0).toUpperCase() + str.slice(1);
+}
+
+export function capitalizeWords(str: string): string {
+    if (!str) return '';
+    return str.split(' ').map(word => capitalize(word)).join(' ');
+}
+
+export function camelToKebab(str: string): string {
+    return str.replace(/([a-z])([A-Z])/g, '$1-$2').toLowerCase();
+}
+
+export function kebabToCamel(str: string): string {
+    return str.replace(/-([a-z])/g, (_, letter) => letter.toUpperCase());
+}
+
+export function truncate(str: string, length: number, suffix = '...'): string {
+    if (!str || str.length <= length) return str;
+    return str.slice(0, length - suffix.length) + suffix;
+}
+
+export function pluralize(count: number, singular: string, plural?: string): string {
+    return count === 1 ? singular : (plural || singular + 's');
+}
+
+export const EzUtils = {
+    format,
+    capitalize,
+    capitalizeWords,
+    camelToKebab,
+    kebabToCamel,
+    truncate,
+    pluralize
+};

package/package.json

@@ -0,0 +1,51 @@
+{
+  "name": "ezfw-core",
+  "version": "1.0.0",
+  "description": "Ez Framework - A declarative component framework for building modern web applications",
+  "type": "module",
+  "main": "./core/ez.ts",
+  "module": "./core/ez.ts",
+  "types": "./core/ez.ts",
+  "exports": {
+    ".": {
+      "import": "./core/ez.ts",
+      "types": "./core/ez.ts"
+    },
+    "./*": "./*"
+  },
+  "files": [
+    "core",
+    "components",
+    "services",
+    "template",
+    "themes",
+    "types",
+    "utils"
+  ],
+  "keywords": [
+    "ez",
+    "framework",
+    "component",
+    "declarative",
+    "vite",
+    "typescript"
+  ],
+  "author": "Ez Hard Soft",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://bitbucket.org/ez-hard-soft/ez.git"
+  },
+  "dependencies": {
+    "@preact/signals": "^2.5.1",
+    "deepsignal": "^1.6.0",
+    "moment": "^2.30.1"
+  },
+  "peerDependencies": {
+    "vite": ">=5.0.0",
+    "sass": ">=1.69.0"
+  },
+  "engines": {
+    "node": ">=18.0.0"
+  }
+}

package/services/RouteUI.js

@@ -0,0 +1,17 @@
+export class RouteUIService {
+    buildBreadcrumbs({ chain, fullPath }) {
+        return chain.map(node => {
+            const meta = node.routeDef?.meta || {};
+
+            const label =
+                typeof meta.breadcrumb === 'function'
+                    ? meta.breadcrumb(node.params)
+                    : meta.title || node.view;
+
+            return {
+                label,
+                route: fullPath
+            };
+        });
+    }
+}

package/services/crypto.js

@@ -0,0 +1,64 @@
+let _ready = false;
+let _key = null;
+let _sodium = null;
+
+export const CryptoService = {
+    async init(secret) {
+        if (_ready) return;
+
+        // Dynamic import - libsodium only loads when init() is called
+        const { default: sodium } = await import('libsodium-wrappers');
+        _sodium = sodium;
+
+        await _sodium.ready;
+
+        if (!secret) {
+            throw new Error('[CryptoService] secret is required');
+        }
+
+        // 🔑 SAME KDF AS SERVER
+        _key = _sodium.crypto_generichash(
+            _sodium.crypto_secretbox_KEYBYTES,
+            secret
+        );
+
+        _ready = true;
+    },
+
+    encode(value) {
+        if (!_ready) {
+            throw new Error('[CryptoService] not initialized');
+        }
+
+        const nonce = _sodium.randombytes_buf(
+            _sodium.crypto_secretbox_NONCEBYTES
+        );
+
+        const cipher = _sodium.crypto_secretbox_easy(
+            _sodium.from_string(JSON.stringify(value)),
+            nonce,
+            _key
+        );
+
+        return JSON.stringify({
+            nonce: _sodium.to_base64(nonce),
+            cipher: _sodium.to_base64(cipher)
+        });
+    },
+
+    decode(payload) {
+        if (!_ready) {
+            throw new Error('[CryptoService] not initialized');
+        }
+
+        const { nonce, cipher } = JSON.parse(payload);
+
+        const decrypted = _sodium.crypto_secretbox_open_easy(
+            _sodium.from_base64(cipher),
+            _sodium.from_base64(nonce),
+            _key
+        );
+
+        return JSON.parse(_sodium.to_string(decrypted));
+    }
+};

package/services/dialog.js

@@ -0,0 +1,222 @@
+export class EzDialogService {
+    constructor() {
+        this._stack = [];
+        this._idCounter = 0;
+    }
+
+    get stack() {
+        return this._stack;
+    }
+
+    async open(config) {
+        const dialogId = `ez-dialog-${++this._idCounter}`;
+        let resolvePromise;
+        let el;
+
+        // Create dialog instance with methods
+        const dialogInstance = {
+            _id: dialogId,
+            _el: null,
+            _isMaximized: config.maximized || false,
+            _isClosed: false,
+            _isHidden: false,
+
+            close: (result = null) => {
+                if (dialogInstance._isClosed) return;
+                dialogInstance._isClosed = true;
+
+                document.removeEventListener('keydown', onEscKey);
+
+                if (dialogInstance._el) {
+                    dialogInstance._el.classList.remove('visible');
+                    dialogInstance._el.classList.add('closing');
+
+                    setTimeout(() => {
+                        dialogInstance._el?.remove();
+                    }, 200);
+                }
+
+                this.pop(dialogInstance);
+
+                if (resolvePromise) {
+                    resolvePromise(result);
+                }
+
+                if (config.onClose) {
+                    config.onClose(result);
+                }
+            },
+
+            hide: () => {
+                if (dialogInstance._isHidden || dialogInstance._isClosed) return;
+                dialogInstance._isHidden = true;
+
+                if (dialogInstance._el) {
+                    dialogInstance._el.classList.remove('visible');
+                    dialogInstance._el.classList.add('hidden');
+                }
+            },
+
+            show: () => {
+                if (!dialogInstance._isHidden || dialogInstance._isClosed) return;
+                dialogInstance._isHidden = false;
+
+                if (dialogInstance._el) {
+                    dialogInstance._el.classList.remove('hidden');
+                    dialogInstance._el.classList.add('visible');
+                }
+            },
+
+            toggleMaximize: () => {
+                dialogInstance._isMaximized = !dialogInstance._isMaximized;
+                const dialogEl = dialogInstance._el?.querySelector('[class*="dialog"]');
+                if (dialogEl) {
+                    dialogEl.classList.toggle('maximized', dialogInstance._isMaximized);
+                }
+            },
+
+            isHidden: () => dialogInstance._isHidden
+        };
+
+        // ESC key handler
+        const onEscKey = (e) => {
+            if (e.key === 'Escape' && config.closeOnEsc !== false) {
+                if (this.getTopDialog() === dialogInstance) {
+                    dialogInstance.close();
+                }
+            }
+        };
+
+        // Overlay click handler
+        const onOverlayClick = (e) => {
+            if (config.closeOnOverlay !== false && e.target === el) {
+                dialogInstance.close();
+            }
+        };
+
+        // Build dialog config
+        const dialogConfig = {
+            eztype: 'EzDialog',
+            props: {
+                ...config,
+                _dialogId: dialogId,
+                _dialogInstance: dialogInstance
+            }
+        };
+
+        // Render through framework
+        el = await ez._createElement(dialogConfig);
+        dialogInstance._el = el;
+
+        // Set z-index based on stack
+        const level = this._stack.length;
+        const zIndex = 1000 + (level * 10);
+        el.style.zIndex = zIndex;
+
+        // Add event listeners
+        if (config.closeOnEsc !== false) {
+            document.addEventListener('keydown', onEscKey);
+        }
+        if (config.closeOnOverlay !== false) {
+            el.addEventListener('click', onOverlayClick);
+        }
+
+        // Push to stack and append to body
+        this.push(dialogInstance);
+        document.body.appendChild(el);
+
+        // Trigger animation
+        requestAnimationFrame(() => {
+            el.classList.add('visible');
+        });
+
+        // Return promise
+        return new Promise((resolve) => {
+            resolvePromise = resolve;
+        });
+    }
+
+    async alert(messageOrConfig, options = {}) {
+        const config = typeof messageOrConfig === 'string'
+            ? { message: messageOrConfig, ...options }
+            : messageOrConfig;
+
+        return this.open({
+            title: config.title || 'Alert',
+            message: config.message,
+            icon: config.icon || 'fa-solid fa-circle-info',
+            iconVariant: config.iconVariant || 'info',
+            size: config.size || 'sm',
+            closable: config.closable ?? true,
+            closeOnOverlay: config.closeOnOverlay ?? true,
+            buttons: [
+                {
+                    text: config.buttonText || 'OK',
+                    variant: 'primary',
+                    value: true
+                }
+            ]
+        });
+    }
+
+    async confirm(messageOrConfig, options = {}) {
+        const config = typeof messageOrConfig === 'string'
+            ? { message: messageOrConfig, ...options }
+            : messageOrConfig;
+
+        const result = await this.open({
+            title: config.title || 'Confirm',
+            message: config.message,
+            icon: config.icon || 'fa-solid fa-circle-question',
+            iconVariant: config.iconVariant || 'warning',
+            size: config.size || 'sm',
+            closable: config.closable ?? false,
+            closeOnOverlay: config.closeOnOverlay ?? false,
+            closeOnEsc: config.closeOnEsc ?? true,
+            buttons: [
+                {
+                    text: config.cancelText || 'Cancel',
+                    variant: 'secondary',
+                    value: false
+                },
+                {
+                    text: config.confirmText || 'Confirm',
+                    variant: config.confirmVariant || 'primary',
+                    value: true
+                }
+            ]
+        });
+
+        return result === true;
+    }
+
+    async danger(messageOrConfig, options = {}) {
+        const config = typeof messageOrConfig === 'string'
+            ? { message: messageOrConfig, ...options }
+            : messageOrConfig;
+
+        return this.confirm({
+            ...config,
+            title: config.title || 'Are you sure?',
+            icon: config.icon || 'fa-solid fa-triangle-exclamation',
+            iconVariant: 'danger',
+            confirmText: config.confirmText || 'Delete',
+            confirmVariant: 'danger'
+        });
+    }
+
+    push(dialog) {
+        this._stack.push(dialog);
+    }
+
+    pop(dialog) {
+        const index = this._stack.indexOf(dialog);
+        if (index > -1) {
+            this._stack.splice(index, 1);
+        }
+    }
+
+    getTopDialog() {
+        return this._stack.length > 0 ? this._stack[this._stack.length - 1] : null;
+    }
+}

package/services/fetchApi.js

@@ -0,0 +1,63 @@
+import {EzError} from "../core/EzError.js";
+
+export class FetchApi {
+    constructor(config = {}) {
+        this.baseUrl = config.baseUrl || '';
+        this._headersResolver = null;
+        this._responseTransformers = [];
+        this._errorHandler = null;
+    }
+
+    setHeadersResolver(fn) {
+        this._headersResolver = fn;
+    }
+
+    addResponseTransformer(fn) {
+        this._responseTransformers.push(fn);
+    }
+
+    setErrorHandler(fn) {
+        this._errorHandler = fn;
+    }
+
+    async request(url, options = {}) {
+        const res = await fetch(this.baseUrl + url, {
+            method: options.method || 'GET',
+            headers: this._headersResolver?.() || {},
+            body: options.body
+                ? JSON.stringify(options.body)
+                : undefined
+        });
+
+        const payload = await res.json().catch(() => null);
+
+        // 🔴 ERROR PATH (TU CONTRATO REAL)
+        if (!res.ok || payload?.success === false) {
+            const error = {
+                status: payload?.status ?? res.status,
+                message: payload?.message ?? 'Unknown error',
+                field: payload?.field ?? null
+            };
+
+            if (typeof this._errorHandler === 'function') {
+                await this._errorHandler(error, res);
+            }
+
+            throw new EzError({
+                code: 'EZ_FETCH_001',
+                source: 'fetch',
+                message: 'Request failed before reaching server',
+                route: ez._context.route,
+                cause: error
+            });
+        }
+
+        // 🟢 SUCCESS PATH
+        let data = payload;
+        for (const transform of this._responseTransformers) {
+            data = await transform(data, res);
+        }
+
+        return data;
+    }
+}

package/services/firebase.js

@@ -0,0 +1,30 @@
+export class FirebaseService {
+    constructor(config) {
+        this.config = config;
+        this.app = null;
+        this.auth = null;
+        this.initialized = false;
+    }
+
+    async init() {
+        if (this.initialized) return;
+
+        const { initializeApp } = await import('firebase/app');
+        const { getAuth } = await import('firebase/auth');
+
+        this.app = initializeApp(this.config);
+        this.auth = getAuth(this.app);
+        this.initialized = true;
+
+        console.log('[ez] Firebase initialized');
+    }
+
+    async loginWithEmail(email, password) {
+        if (!this.initialized) {
+            await this.init();
+        }
+
+        const { signInWithEmailAndPassword } = await import('firebase/auth');
+        return signInWithEmailAndPassword(this.auth, email, password);
+    }
+}