slicejs-web-framework 2.3.0 → 2.3.2

package/Slice/Components/Structural/Router/Router.js

@@ -1,4 +1,46 @@
+/**
+ * @typedef {Object} RouteConfig
+ * @property {string} path
+ * @property {string} component
+ * @property {RouteConfig[]} [children]
+ * @property {Object} [metadata]
+ * @property {string} [fullPath]
+ * @property {string|null} [parentPath]
+ * @property {RouteConfig|null} [parentRoute]
+ */
+
+/**
+ * @typedef {Object} RouteInfo
+ * @property {string} path
+ * @property {string} component
+ * @property {Object} params
+ * @property {Object} query
+ * @property {Object} metadata
+ */
+
+/**
+ * @typedef {Object} GuardRedirect
+ * @property {string} path
+ * @property {boolean} [replace]
+ */
+
+/**
+ * @typedef {Object} RouteMatch
+ * @property {RouteConfig|null} route
+ * @property {Object} params
+ * @property {RouteConfig} [childRoute]
+ */
+
+/**
+ * @callback RouterNext
+ * @param {void|false|string|{ path: string, replace?: boolean }} [arg]
+ * @returns {void}
+ */
+
 export default class Router {
+   /**
+    * @param {RouteConfig[]} routes
+    */
    constructor(routes) {
       this.routes = routes;
       this.activeRoute = null;
@@ -23,7 +65,8 @@ export default class Router {
 
    /**
     * Inicializa el router
-    * Si el usuario no llama start() manualmente, se auto-inicia después de un delay
+    * Si el usuario no llama start() manualmente, se auto-inicia despues de un delay
+    * @returns {void}
     */
    init() {
       window.addEventListener('popstate', this.onRouteChange.bind(this));
@@ -41,7 +84,8 @@ export default class Router {
    /**
     * Inicia el router y carga la ruta inicial
     * OPCIONAL: Solo necesario si usas guards (beforeEach/afterEach)
-    * Si no lo llamas, el router se auto-inicia después de 50ms
+    * Si no lo llamas, el router se auto-inicia despues de 50ms
+    * @returns {Promise<void>}
     */
    async start() {
       // Prevenir múltiples llamadas
@@ -65,9 +109,10 @@ export default class Router {
    // ============================================
 
    /**
-    * Registra un guard que se ejecuta ANTES de cada navegación
-    * Puede bloquear o redirigir la navegación
-    * @param {Function} guard - Función (to, from, next) => {}
+    * Registra un guard que se ejecuta ANTES de cada navegacion.
+    * Puede bloquear o redirigir la navegacion mediante next().
+    * @param {(to: RouteInfo, from: RouteInfo, next: RouterNext) => void|Promise<void>} guard
+    * @returns {void}
     */
    beforeEach(guard) {
       if (typeof guard !== 'function') {
@@ -78,9 +123,10 @@ export default class Router {
    }
 
    /**
-    * Registra un guard que se ejecuta DESPUÉS de cada navegación
-    * No puede bloquear la navegación
-    * @param {Function} guard - Función (to, from) => {}
+    * Registra un guard que se ejecuta DESPUES de cada navegacion.
+    * No puede bloquear la navegacion.
+    * @param {(to: RouteInfo, from: RouteInfo) => void} guard
+    * @returns {void}
     */
    afterEach(guard) {
       if (typeof guard !== 'function') {
@@ -97,6 +143,13 @@ export default class Router {
     * @param {String} requestedPath - Path original solicitado
     * @returns {Object} Objeto con path, component, params, query, metadata
     */
+   /**
+    * Build route info used by guards and events.
+    * @param {RouteConfig|null} route
+    * @param {Object} [params]
+    * @param {string|null} [requestedPath]
+    * @returns {RouteInfo}
+    */
    _createRouteInfo(route, params = {}, requestedPath = null) {
       if (!route) {
          return {
@@ -121,6 +174,10 @@ export default class Router {
     * Parsea los query parameters de la URL actual
     * @returns {Object} Objeto con los query params
     */
+   /**
+    * Parse query params from current URL.
+    * @returns {Object}
+    */
    _parseQueryParams() {
       const queryString = window.location.search;
       if (!queryString) return {};
@@ -141,6 +198,12 @@ export default class Router {
     * @param {Object} from - Información de ruta origen
     * @returns {Object|null} Objeto con redirectPath y options, o null si continúa
     */
+   /**
+    * Execute beforeEach guard if defined.
+    * @param {RouteInfo} to
+    * @param {RouteInfo} from
+    * @returns {Promise<{ path: string|false, options: { replace?: boolean } }|null>}
+    */
    async _executeBeforeEachGuard(to, from) {
       if (!this._beforeEachGuard) {
          return null;
@@ -212,6 +275,12 @@ export default class Router {
     * @param {Object} to - Información de ruta destino
     * @param {Object} from - Información de ruta origen
     */
+   /**
+    * Execute afterEach guard if defined.
+    * @param {RouteInfo} to
+    * @param {RouteInfo} from
+    * @returns {void}
+    */
    _executeAfterEachGuard(to, from) {
       if (!this._afterEachGuard) {
          return;
@@ -228,6 +297,13 @@ export default class Router {
    // ROUTING CORE (MODIFICADO CON GUARDS)
    // ============================================
 
+   /**
+    * Navigate to a route path with guards support. Add replace to do router.replace() instead of push.
+    * @param {string} path
+    * @param {string[]} [_redirectChain]
+    * @param {{ replace?: boolean }} [_options]
+    * @returns {Promise<void>}
+    */
    async navigate(path, _redirectChain = [], _options = {}) {
       const currentPath = window.location.pathname;
 
@@ -282,6 +358,12 @@ export default class Router {
     * @param {Object} to - Información de ruta destino
     * @param {Object} from - Información de ruta origen
     */
+   /**
+    * Perform navigation after guards.
+    * @param {RouteInfo} to
+    * @param {RouteInfo} from
+    * @returns {Promise<void>}
+    */
    async _performNavigation(to, from) {
       // Renderizar la nueva ruta
       await this.onRouteChange();
@@ -293,6 +375,10 @@ export default class Router {
       this._emitRouteChange(to, from);
    }
 
+   /**
+    * React to URL changes and render routes.
+    * @returns {Promise<void>}
+    */
    async onRouteChange() {
       // Cancelar el timeout anterior si existe
       if (this.routeChangeTimeout) {
@@ -315,6 +401,12 @@ export default class Router {
       }, 10);
    }
 
+   /**
+    * Build or update the active route component.
+    * @param {RouteConfig} route
+    * @param {Object} params
+    * @returns {Promise<void>}
+    */
    async handleRoute(route, params) {
       const targetElement = document.querySelector('#app');
 
@@ -357,6 +449,10 @@ export default class Router {
       slice.router.activeRoute = route;
    }
 
+   /**
+    * Load initial route and run guards.
+    * @returns {Promise<void>}
+    */
    async loadInitialRoute() {
       const path = window.location.pathname;
       const { route, params } = this.matchRoute(path);
@@ -392,6 +488,12 @@ export default class Router {
     * @param {Object} to
     * @param {Object} from
     */
+   /**
+    * Emit route change event.
+    * @param {RouteInfo} to
+    * @param {RouteInfo} from
+    * @returns {void}
+    */
    _emitRouteChange(to, from) {
       const payload = { to, from };
 
@@ -475,6 +577,11 @@ export default class Router {
       return pathToRouteMap;
    }
 
+   /**
+    * Render any Route/MultiRoute components in a container.
+    * @param {Document|HTMLElement} [searchContainer]
+    * @returns {Promise<boolean>}
+    */
    async renderRoutesComponentsInPage(searchContainer = document) {
       let routerContainersFlag = false;
       const routeContainers = this.getCachedRouteContainers(searchContainer);
@@ -534,6 +641,11 @@ export default class Router {
       return routeContainers;
    }
 
+   /**
+    * Render route containers inside a component.
+    * @param {HTMLElement} component
+    * @returns {Promise<boolean>}
+    */
    async renderRoutesInComponent(component) {
       if (!component) {
          slice.logger.logWarning('Router', 'No component provided for route rendering');
@@ -543,6 +655,11 @@ export default class Router {
       return await this.renderRoutesComponentsInPage(component);
    }
 
+   /**
+    * Match a path to a configured route.
+    * @param {string} path
+    * @returns {RouteMatch}
+    */
    matchRoute(path) {
       const exactMatch = this.pathToRouteMap.get(path);
       if (exactMatch) {
@@ -583,6 +700,11 @@ export default class Router {
       return { route: notFoundRoute, params: {} };
    }
 
+   /**
+    * Compile a path pattern with ${param} segments.
+    * @param {string} pattern
+    * @returns {{ regex: RegExp, paramNames: string[] }}
+    */
    compilePathPattern(pattern) {
       const paramNames = [];
       const regexPattern =

package/Slice/Components/Structural/StylesManager/StylesManager.js

@@ -1,49 +1,64 @@
-
-export default class StylesManager {
-   constructor() {
-      this.componentStyles = document.createElement('style');
-      this.componentStyles.id = 'slice-component-styles';
-      document.head.appendChild(this.componentStyles);
-
-   }
-
-   async init() {
-      for (let i = 0; i < slice.stylesConfig.requestedStyles.length; i++) {
-         const styles = await slice.controller.fetchText(slice.stylesConfig.requestedStyles[i], 'styles');
-         this.componentStyles.innerText += styles;
-         slice.logger.logInfo('StylesManager', `${slice.stylesConfig.requestedStyles[i]} styles loaded`);
-      }
-
-      if (slice.themeConfig.enabled) {
-         const module = await import(`${slice.paths.structuralComponentFolderPath}/StylesManager/ThemeManager/ThemeManager.js`);
-
-         this.themeManager = new module.default();
-         let theme;
-
-         if (slice.themeConfig.saveThemeLocally) {
-            theme = localStorage.getItem('sliceTheme');
-         }
-
-         if (!theme) {
-            theme = slice.themeConfig.defaultTheme;
-         }
-
-         if (slice.themeConfig.useBrowserTheme) {
-            const browserTheme = window.matchMedia('(prefers-color-scheme: dark)').matches ? 'Dark' : 'Light';
-            theme = browserTheme;
-         }
-
-         await this.themeManager.applyTheme(theme);
-      }
-   }
-
-   //add a method that will add css as text to the componentStyles element
-   appendComponentStyles(cssText) {
-      this.componentStyles.appendChild(document.createTextNode(cssText));
-   }
-
-   registerComponentStyles(componentName, cssText) {
-      slice.controller.requestedStyles.add(componentName);
-      this.appendComponentStyles(cssText);
-   }
-}
+
+export default class StylesManager {
+   constructor() {
+      this.componentStyles = document.createElement('style');
+      this.componentStyles.id = 'slice-component-styles';
+      document.head.appendChild(this.componentStyles);
+
+   }
+
+   /**
+    * Load global styles and initialize ThemeManager if enabled.
+    * @returns {Promise<void>}
+    */
+   async init() {
+      for (let i = 0; i < slice.stylesConfig.requestedStyles.length; i++) {
+         const styles = await slice.controller.fetchText(slice.stylesConfig.requestedStyles[i], 'styles');
+         this.componentStyles.innerText += styles;
+         slice.logger.logInfo('StylesManager', `${slice.stylesConfig.requestedStyles[i]} styles loaded`);
+      }
+
+      if (slice.themeConfig.enabled) {
+         const module = await import(`${slice.paths.structuralComponentFolderPath}/StylesManager/ThemeManager/ThemeManager.js`);
+
+         this.themeManager = new module.default();
+         let theme;
+
+         if (slice.themeConfig.saveThemeLocally) {
+            theme = localStorage.getItem('sliceTheme');
+         }
+
+         if (!theme) {
+            theme = slice.themeConfig.defaultTheme;
+         }
+
+         if (slice.themeConfig.useBrowserTheme) {
+            const browserTheme = window.matchMedia('(prefers-color-scheme: dark)').matches ? 'Dark' : 'Light';
+            theme = browserTheme;
+         }
+
+         await this.themeManager.applyTheme(theme);
+      }
+   }
+
+   //add a method that will add css as text to the componentStyles element
+   /**
+    * Append raw CSS to the global component style tag.
+    * @param {string} cssText
+    * @returns {void}
+    */
+   appendComponentStyles(cssText) {
+      this.componentStyles.appendChild(document.createTextNode(cssText));
+   }
+
+   /**
+    * Register CSS for a component.
+    * @param {string} componentName
+    * @param {string} cssText
+    * @returns {void}
+    */
+   registerComponentStyles(componentName, cssText) {
+      slice.controller.requestedStyles.add(componentName);
+      this.appendComponentStyles(cssText);
+   }
+}

package/Slice/Components/Structural/StylesManager/ThemeManager/ThemeManager.js

@@ -1,56 +1,84 @@
-export default class ThemeManager {
-   constructor() {
-      this.themeStyles = new Map();
-      this.currentTheme = null;
-      this.themeStyle = document.createElement('style');
-      document.head.appendChild(this.themeStyle);
-   }
-
-   async applyTheme(themeName) {
-      if (!themeName) {
-         slice.logger.logError('ThemeManager', 'Invalid theme name');
-         return;
-      }
-
-      if (!this.themeStyles.has(themeName)) {
-         await this.loadThemeCSS(themeName);
-      } else {
-         this.setThemeStyle(themeName);
-         this.saveThemeLocally(themeName, this.themeStyles.get(themeName));
-      }
-   }
-
-   async loadThemeCSS(themeName) {
-      let themeContent =
-         localStorage.getItem(`sliceTheme-${themeName}`) || (await slice.controller.fetchText(themeName, 'theme'));
-
-      if (!themeContent) {
-         slice.logger.logError('ThemeManager', `Failed to load theme: ${themeName}`);
-         return;
-      }
-
-      this.themeStyles.set(themeName, themeContent);
-      this.setThemeStyle(themeName);
-      this.saveThemeLocally(themeName, themeContent);
-   }
-
-   saveThemeLocally(themeName, themeContent) {
-      if (slice.themeConfig.saveThemeLocally) {
-         localStorage.setItem('sliceTheme', themeName);
-         localStorage.setItem(`sliceTheme-${themeName}`, themeContent);
-         slice.logger.logInfo('ThemeManager', `Theme ${themeName} saved locally`);
-      }
-   }
-
-   removeCurrentTheme() {
-      if (this.currentTheme) {
-         this.themeStyle.textContent = '';
-      }
-   }
-
-   setThemeStyle(themeName) {
-      this.themeStyle.textContent = this.themeStyles.get(themeName);
-      this.currentTheme = themeName;
-      slice.logger.logInfo('ThemeManager', `Theme ${themeName} applied`);
-   }
-}
+/**
+ * Manages theme CSS loading and persistence.
+ */
+export default class ThemeManager {
+   constructor() {
+      this.themeStyles = new Map();
+      this.currentTheme = null;
+      this.themeStyle = document.createElement('style');
+      document.head.appendChild(this.themeStyle);
+   }
+
+   /**
+    * Apply a theme by name.
+    * @param {string} themeName
+    * @returns {Promise<void>}
+    */
+   async applyTheme(themeName) {
+      if (!themeName) {
+         slice.logger.logError('ThemeManager', 'Invalid theme name');
+         return;
+      }
+
+      if (!this.themeStyles.has(themeName)) {
+         await this.loadThemeCSS(themeName);
+      } else {
+         this.setThemeStyle(themeName);
+         this.saveThemeLocally(themeName, this.themeStyles.get(themeName));
+      }
+   }
+
+   /**
+    * Load theme CSS and cache it.
+    * @param {string} themeName
+    * @returns {Promise<void>}
+    */
+   async loadThemeCSS(themeName) {
+      let themeContent =
+         localStorage.getItem(`sliceTheme-${themeName}`) || (await slice.controller.fetchText(themeName, 'theme'));
+
+      if (!themeContent) {
+         slice.logger.logError('ThemeManager', `Failed to load theme: ${themeName}`);
+         return;
+      }
+
+      this.themeStyles.set(themeName, themeContent);
+      this.setThemeStyle(themeName);
+      this.saveThemeLocally(themeName, themeContent);
+   }
+
+   /**
+    * Persist a theme in localStorage when enabled.
+    * @param {string} themeName
+    * @param {string} themeContent
+    * @returns {void}
+    */
+   saveThemeLocally(themeName, themeContent) {
+      if (slice.themeConfig.saveThemeLocally) {
+         localStorage.setItem('sliceTheme', themeName);
+         localStorage.setItem(`sliceTheme-${themeName}`, themeContent);
+         slice.logger.logInfo('ThemeManager', `Theme ${themeName} saved locally`);
+      }
+   }
+
+   /**
+    * Clear currently applied theme styles.
+    * @returns {void}
+    */
+   removeCurrentTheme() {
+      if (this.currentTheme) {
+         this.themeStyle.textContent = '';
+      }
+   }
+
+   /**
+    * Set theme style text and mark current theme.
+    * @param {string} themeName
+    * @returns {void}
+    */
+   setThemeStyle(themeName) {
+      this.themeStyle.textContent = this.themeStyles.get(themeName);
+      this.currentTheme = themeName;
+      slice.logger.logInfo('ThemeManager', `Theme ${themeName} applied`);
+   }
+}

package/Slice/Slice.js

@@ -1,7 +1,13 @@
 import Controller from './Components/Structural/Controller/Controller.js';
 import StylesManager from './Components/Structural/StylesManager/StylesManager.js';
 
+/**
+ * Main Slice.js runtime.
+ */
 export default class Slice {
+   /**
+    * @param {Object} sliceConfig
+    */
    constructor(sliceConfig) {
       this.controller = new Controller();
       this.stylesManager = new StylesManager();
@@ -16,6 +22,11 @@ export default class Slice {
       // 📦 Bundle system is initialized automatically via import in index.js
    }
 
+   /**
+    * Dynamically import a module and return its default export.
+    * @param {string} module
+    * @returns {Promise<any>}
+    */
    async getClass(module) {
       try {
          const { default: myClass } = await import(module);
@@ -25,14 +36,29 @@ export default class Slice {
       }
    }
 
+   /**
+    * Flag for production behavior (override in builds).
+    * @returns {boolean}
+    */
    isProduction() {
       return true;
    }
 
+   /**
+    * Get a component instance by sliceId.
+    * @param {string} componentSliceId
+    * @returns {HTMLElement|undefined}
+    */
    getComponent(componentSliceId) {
       return this.controller.activeComponents.get(componentSliceId);
    }
 
+   /**
+    * Build a component instance and run init.
+    * @param {string} componentName
+    * @param {Object} [props]
+    * @returns {Promise<HTMLElement|Object|null>}
+    */
    async build(componentName, props = {}) {
       if (!componentName) {
          this.logger.logError('Slice', null, `Component name is required to build a component`);
@@ -159,14 +185,28 @@ export default class Slice {
       }
    }
 
+   /**
+    * Apply a theme by name.
+    * @param {string} themeName
+    * @returns {Promise<void>}
+    */
    async setTheme(themeName) {
       await this.stylesManager.themeManager.applyTheme(themeName);
    }
 
+   /**
+    * Current theme name.
+    * @returns {string|null}
+    */
    get theme() {
       return this.stylesManager.themeManager.currentTheme;
    }
 
+   /**
+    * Attach HTML template to a component instance.
+    * @param {HTMLElement} componentInstance
+    * @returns {void}
+    */
    attachTemplate(componentInstance) {
       this.controller.loadTemplateToComponent(componentInstance);
    }
@@ -210,14 +250,32 @@ async function init() {
    }
 
    if (sliceConfig.debugger.enabled) {
-      const DebuggerModule = await window.slice.getClass(
-         `${slice.paths.structuralComponentFolderPath}/Debugger/Debugger.js`
-      );
-      window.slice.debugger = new DebuggerModule();
-      await window.slice.debugger.enableDebugMode();
-      document.body.appendChild(window.slice.debugger);
+       const DebuggerModule = await window.slice.getClass(
+          `${slice.paths.structuralComponentFolderPath}/Debugger/Debugger.js`
+       );
+       window.slice.debugger = new DebuggerModule();
+       await window.slice.debugger.enableDebugMode();
+       document.body.appendChild(window.slice.debugger);
    }
 
+    if (sliceConfig.events?.ui?.enabled) {
+       const EventsDebuggerModule = await window.slice.getClass(
+          `${slice.paths.structuralComponentFolderPath}/EventManager/EventManagerDebugger.js`
+       );
+       window.slice.eventsDebugger = new EventsDebuggerModule();
+       await window.slice.eventsDebugger.init();
+       document.body.appendChild(window.slice.eventsDebugger);
+    }
+
+    if (sliceConfig.context?.ui?.enabled) {
+       const ContextDebuggerModule = await window.slice.getClass(
+          `${slice.paths.structuralComponentFolderPath}/ContextManager/ContextManagerDebugger.js`
+       );
+       window.slice.contextDebugger = new ContextDebuggerModule();
+       await window.slice.contextDebugger.init();
+       document.body.appendChild(window.slice.contextDebugger);
+    }
+
    if (sliceConfig.events?.enabled) {
       const EventManagerModule = await window.slice.getClass(
          `${slice.paths.structuralComponentFolderPath}/EventManager/EventManager.js`
@@ -275,6 +333,34 @@ async function init() {
 
    await window.slice.stylesManager.init();
 
+   if (sliceConfig.events?.ui?.shortcut || sliceConfig.context?.ui?.shortcut) {
+      const normalize = (value) => (typeof value === 'string' ? value.toLowerCase() : '');
+      const toKey = (event) => {
+         const parts = [];
+         if (event.ctrlKey) parts.push('ctrl');
+         if (event.shiftKey) parts.push('shift');
+         if (event.altKey) parts.push('alt');
+         if (event.metaKey) parts.push('meta');
+         const key = event.key?.toLowerCase();
+         if (key && !['control', 'shift', 'alt', 'meta'].includes(key)) {
+            parts.push(key);
+         }
+         return parts.join('+');
+      };
+
+      const handlers = {
+         [normalize(sliceConfig.events?.ui?.shortcut)]: () => window.slice.eventsDebugger?.toggle?.(),
+         [normalize(sliceConfig.context?.ui?.shortcut)]: () => window.slice.contextDebugger?.toggle?.(),
+      };
+
+      document.addEventListener('keydown', (event) => {
+         const key = toKey(event);
+         if (!key || !handlers[key]) return;
+         event.preventDefault();
+         handlers[key]();
+      });
+   }
+
    const routesModule = await import(slice.paths.routesFile);
    const routes = routesModule.default;
    const RouterModule = await window.slice.getClass(`${slice.paths.structuralComponentFolderPath}/Router/Router.js`);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "slicejs-web-framework",
-  "version": "2.3.0",
+  "version": "2.3.2",
   "description": "",
   "engines": {
     "node": ">=20"