slicejs-web-framework 2.2.13 → 2.3.1

package/README.md

@@ -1,156 +1,155 @@
-<!-- Improved compatibility of back to top link: See: https://github.com/VKneider/slice.js/pull/73 -->
-<a name="readme-top"></a>
-<!--
-*** Thanks for checking out the slice.js. If you have a suggestion
-*** that would make this better, please fork the repo and create a pull request
-*** or simply open an issue with the tag "enhancement".
-*** Don't forget to give the project a star!
-*** Thanks again! Now go create something AMAZING! :D
--->
-
-
-
-<!-- PROJECT SHIELDS -->
-<!--
-*** I'm using markdown "reference style" links for readability.
-*** Reference links are enclosed in brackets [ ] instead of parentheses ( ).
-*** See the bottom of this document for the declaration of the reference variables
-*** for contributors-url, forks-url, etc. This is an optional, concise syntax you may use.
-*** https://www.markdownguide.org/basic-syntax/#reference-style-links
--->
-[![Contributors][contributors-shield]][contributors-url]
-[![Forks][forks-shield]][forks-url]
-[![Stargazers][stars-shield]][stars-url]
-[![Issues][issues-shield]][issues-url]
-[![MIT License][license-shield]][license-url]
-
-
-
-<!-- PROJECT LOGO -->
-<br />
-<div align="center">
-  <a href="https://github.com/VKneider/slice.js">
-    <img src="readme_images/Slice.js-logo.svg" alt="Logo" width="150" height="150">
-  </a>
-
-  <h3 align="center">Slice.js</h3>
-
-  <p align="center">
-    Component-Based Web Development Framework
-    <br />
-    <a href="https://slice-js-docs.vercel.app/Documentation"><strong>Explore the docs »</strong></a>
-    <br />
-    <br />
-    <a href="https://slice-js-docs.vercel.app/">View Demo</a>
-    ·
-    <a href="https://github.com/VKneider/slice.js/issues/new?labels=bug&template=bug-report---.md">Report Bug</a>
-    ·
-    <a href="https://github.com/VKneider/slice.js/issues/new?labels=enhancement&template=feature-request---.md">Request Feature</a>
-  </p>
-</div>
-
-
-
-<!-- TABLE OF CONTENTS -->
-<details>
-  <summary>Table of Contents</summary>
-  <ol>
-    <li>
-      <a href="#about-the-project">About The Project</a>
-    </li>
-    <li>
-      <a href="#getting-started">Getting Started</a>
-      <ul>
-        <li><a href="#prerequisites">Prerequisites</a></li>
-        <li><a href="#installation">Installation</a></li>
-      </ul>
-    </li>
-    <li><a href="#roadmap">Roadmap</a></li>
-    <li><a href="#contributing">Contributing</a></li>
-    <li><a href="#license">License</a></li>
-    <li><a href="#contact">Contact</a></li>
-  </ol>
-</details>
-
-
-
-<!-- ABOUT THE PROJECT -->
-## About The Project
-
-[![Product Name Screen Shot][product-screenshot]](https://slice-js-docs.vercel.app/)
-
-<p align="right">(<a href="#readme-top">back to top</a>)</p>
-
-<!-- GETTING STARTED -->
-## Getting Started
-
-This is an example of how you may give instructions on setting up your project locally.
-To get a local copy up and running follow these simple example steps.
-
-### Installation
-
-_Below is an example of how you can instruct your audience on installing and setting up your app. This template doesn't rely on any external dependencies or services._
-
-1. Install slicejs cli dependencies
-   ```sh
-   npm i slicejs-cli
-   ```
-2. Initialize slice project
-   ```sh
-   npm run slice:init
-   ```
-3. Start web server
-   ```sh
-   npm run slice:start
-   ```
-
-<p align="right">(<a href="#readme-top">back to top</a>)</p>
-
-
-
-<!-- ROADMAP -->
-## Roadmap
-
-- [x] Add Changelog
-- [ ] Add Image visual component
-- [ ] Modify Slice Card Visual Component
-- [ ] Create internationalization Translator Service component.
-
-See the [open issues](https://github.com/VKneider/slice.js/issues) for a full list of proposed features (and known issues).
-
-<p align="right">(<a href="#readme-top">back to top</a>)</p>
-
-
-
-<!-- CONTRIBUTING -->
-## Contributing
-
-We welcome contributions to the project! Please make sure to review the guidelines in the [CONTRIBUTING.md](docs/CONTRIBUTING.md) file before submitting any changes.
-
-<p align="right">(<a href="#readme-top">back to top</a>)</p>
-
-
-
-<!-- LICENSE -->
-## License
-
-Distributed under the MIT License. See `LICENSE` for more information.
-
-<p align="right">(<a href="#readme-top">back to top</a>)</p>
-
-<!-- MARKDOWN LINKS & IMAGES -->
-<!-- https://www.markdownguide.org/basic-syntax/#reference-style-links -->
-[contributors-shield]: https://img.shields.io/github/contributors/VKneider/slice.js.svg?style=for-the-badge
-[contributors-url]: https://github.com/VKneider/slice.js/graphs/contributors
-[forks-shield]: https://img.shields.io/github/forks/VKneider/slice.js.svg?style=for-the-badge
-[forks-url]: https://github.com/VKneider/slice.js/network/members
-[stars-shield]: https://img.shields.io/github/stars/VKneider/slice.js.svg?style=for-the-badge
-[stars-url]: https://github.com/VKneider/slice.js/stargazers
-[issues-shield]: https://img.shields.io/github/issues/VKneider/slice.js.svg?style=for-the-badge
-[issues-url]: https://github.com/VKneider/slice.js/issues
-[license-shield]: https://img.shields.io/github/license/VKneider/slice.js.svg?style=for-the-badge
-[license-url]: https://github.com/VKneider/slice.js/blob/master/LICENSE.txt
-[linkedin-shield]: https://img.shields.io/badge/-LinkedIn-black.svg?style=for-the-badge&logo=linkedin&colorB=555
-[linkedin-url]: https://linkedin.com/in/VKneider
-[product-screenshot]: readme_images/screenshot.JPG
-
+<!-- Improved compatibility of back to top link: See: https://github.com/VKneider/slice.js/pull/73 -->
+<a name="readme-top"></a>
+<!--
+*** Thanks for checking out the slice.js. If you have a suggestion
+*** that would make this better, please fork the repo and create a pull request
+*** or simply open an issue with the tag "enhancement".
+*** Don't forget to give the project a star!
+*** Thanks again! Now go create something AMAZING! :D
+-->
+
+
+
+<!-- PROJECT SHIELDS -->
+<!--
+*** I'm using markdown "reference style" links for readability.
+*** Reference links are enclosed in brackets [ ] instead of parentheses ( ).
+*** See the bottom of this document for the declaration of the reference variables
+*** for contributors-url, forks-url, etc. This is an optional, concise syntax you may use.
+*** https://www.markdownguide.org/basic-syntax/#reference-style-links
+-->
+[![Contributors][contributors-shield]][contributors-url]
+[![Forks][forks-shield]][forks-url]
+[![Stargazers][stars-shield]][stars-url]
+[![Issues][issues-shield]][issues-url]
+[![MIT License][license-shield]][license-url]
+
+
+
+<!-- PROJECT LOGO -->
+<br />
+<div align="center">
+  <a href="https://github.com/VKneider/slice.js">
+    <img src="readme_images/Slice.js-logo.svg" alt="Logo" width="150" height="150">
+  </a>
+
+  <h3 align="center">Slice.js</h3>
+
+  <p align="center">
+    Component-Based Web Development Framework
+    <br />
+    <a href="https://slice-js-docs.vercel.app/Documentation"><strong>Explore the docs »</strong></a>
+    <br />
+    <br />
+    <a href="https://slice-js-docs.vercel.app/">View Demo</a>
+    ·
+    <a href="https://github.com/VKneider/slice.js/issues/new?labels=bug&template=bug-report---.md">Report Bug</a>
+    ·
+    <a href="https://github.com/VKneider/slice.js/issues/new?labels=enhancement&template=feature-request---.md">Request Feature</a>
+  </p>
+</div>
+
+
+
+<!-- TABLE OF CONTENTS -->
+<details>
+  <summary>Table of Contents</summary>
+  <ol>
+    <li>
+      <a href="#about-the-project">About The Project</a>
+    </li>
+    <li>
+      <a href="#getting-started">Getting Started</a>
+      <ul>
+        <li><a href="#prerequisites">Prerequisites</a></li>
+        <li><a href="#installation">Installation</a></li>
+      </ul>
+    </li>
+    <li><a href="#roadmap">Roadmap</a></li>
+    <li><a href="#contributing">Contributing</a></li>
+    <li><a href="#license">License</a></li>
+    <li><a href="#contact">Contact</a></li>
+  </ol>
+</details>
+
+
+
+<!-- ABOUT THE PROJECT -->
+## About The Project
+
+[![Product Name Screen Shot][product-screenshot]](https://slice-js-docs.vercel.app/)
+
+<p align="right">(<a href="#readme-top">back to top</a>)</p>
+
+<!-- GETTING STARTED -->
+## Getting Started
+
+This is an example of how you may give instructions on setting up your project locally.
+To get a local copy up and running follow these simple example steps.
+
+### Installation
+
+_Below is an example of how you can instruct your audience on installing and setting up your app. This template doesn't rely on any external dependencies or services._
+
+1. Install slicejs cli dependencies
+   ```sh
+   npm i slicejs-cli
+   ```
+2. Initialize slice project
+   ```sh
+   npm run slice:init
+   ```
+3. Start web server
+   ```sh
+   npm run slice:start
+   ```
+
+<p align="right">(<a href="#readme-top">back to top</a>)</p>
+
+
+
+<!-- ROADMAP -->
+## Roadmap
+
+- [x] Add Changelog
+- [ ] Add Image visual component
+- [ ] Modify Slice Card Visual Component
+
+See the [open issues](https://github.com/VKneider/slice.js/issues) for a full list of proposed features (and known issues).
+
+<p align="right">(<a href="#readme-top">back to top</a>)</p>
+
+
+
+<!-- CONTRIBUTING -->
+## Contributing
+
+We welcome contributions to the project! Please make sure to review the guidelines in the [CONTRIBUTING.md](docs/CONTRIBUTING.md) file before submitting any changes.
+
+<p align="right">(<a href="#readme-top">back to top</a>)</p>
+
+
+
+<!-- LICENSE -->
+## License
+
+Distributed under the MIT License. See `LICENSE` for more information.
+
+<p align="right">(<a href="#readme-top">back to top</a>)</p>
+
+<!-- MARKDOWN LINKS & IMAGES -->
+<!-- https://www.markdownguide.org/basic-syntax/#reference-style-links -->
+[contributors-shield]: https://img.shields.io/github/contributors/VKneider/slice.js.svg?style=for-the-badge
+[contributors-url]: https://github.com/VKneider/slice.js/graphs/contributors
+[forks-shield]: https://img.shields.io/github/forks/VKneider/slice.js.svg?style=for-the-badge
+[forks-url]: https://github.com/VKneider/slice.js/network/members
+[stars-shield]: https://img.shields.io/github/stars/VKneider/slice.js.svg?style=for-the-badge
+[stars-url]: https://github.com/VKneider/slice.js/stargazers
+[issues-shield]: https://img.shields.io/github/issues/VKneider/slice.js.svg?style=for-the-badge
+[issues-url]: https://github.com/VKneider/slice.js/issues
+[license-shield]: https://img.shields.io/github/license/VKneider/slice.js.svg?style=for-the-badge
+[license-url]: https://github.com/VKneider/slice.js/blob/master/LICENSE.txt
+[linkedin-shield]: https://img.shields.io/badge/-LinkedIn-black.svg?style=for-the-badge&logo=linkedin&colorB=555
+[linkedin-url]: https://linkedin.com/in/VKneider
+[product-screenshot]: readme_images/screenshot.JPG
+

package/Slice/Components/Structural/ContextManager/ContextManager.js

@@ -0,0 +1,361 @@
+/**
+ * ContextManager - Sistema de contextos compartidos para Slice.js
+ * Ubicación: /Slice/Components/Structural/ContextManager/ContextManager.js
+ *
+ * Características:
+ * - Estado compartido entre componentes
+ * - Usa EventManager internamente para notificaciones
+ * - Selectores para observar campos específicos
+ * - Auto-limpieza cuando componentes se destruyen
+ * - Persistencia opcional en localStorage
+ */
+export default class ContextManager {
+   constructor() {
+      // Map<contextName, { state, options }>
+      this.contexts = new Map();
+   }
+
+   init() {
+      return true;
+   }
+
+   // ============================================
+   // CREAR CONTEXTO
+   // ============================================
+
+   /**
+    * Crear un nuevo contexto
+    * @param {string} name - Nombre único del contexto
+    * @param {Object} initialState - Estado inicial
+    * @param {Object} options - Opciones: { persist: boolean }
+    *
+    * @example
+    * slice.context.create('auth', {
+    *    isLoggedIn: false,
+    *    user: null
+    * });
+    *
+    * // Con persistencia en localStorage
+    * slice.context.create('preferences', {
+    *    theme: 'light',
+    *    language: 'es'
+    * }, { persist: true });
+    */
+   create(name, initialState = {}, options = {}) {
+      if (this.contexts.has(name)) {
+         slice.logger.logWarning('ContextManager', `El contexto "${name}" ya existe`);
+         return false;
+      }
+
+      // Cargar estado persistido si existe
+      let state = initialState;
+      if (options.persist) {
+         const persisted = this._loadFromStorage(name);
+         if (persisted !== null) {
+            state = persisted;
+         }
+      }
+
+      this.contexts.set(name, {
+         state,
+         options: {
+            persist: options.persist || false,
+            storageKey: options.storageKey || `slice_context_${name}`,
+         },
+      });
+
+      slice.logger.logInfo('ContextManager', `Contexto "${name}" creado`);
+
+      return true;
+   }
+
+   // ============================================
+   // LEER ESTADO
+   // ============================================
+
+   /**
+    * Obtener el estado actual de un contexto
+    * @param {string} name - Nombre del contexto
+    * @returns {*} Estado actual o null si no existe
+    *
+    * @example
+    * const auth = slice.context.getState('auth');
+    * console.log(auth.user.name);
+    */
+   getState(name) {
+      if (!this.contexts.has(name)) {
+         slice.logger.logError('ContextManager', `El contexto "${name}" no existe`);
+         return null;
+      }
+
+      return this.contexts.get(name).state;
+   }
+
+   // ============================================
+   // ACTUALIZAR ESTADO
+   // ============================================
+
+   /**
+    * Actualizar el estado de un contexto
+    * @param {string} name - Nombre del contexto
+    * @param {Object|Function} updater - Nuevo estado o función (prevState) => newState
+    *
+    * @example
+    * // Reemplazar con objeto
+    * slice.context.setState('auth', {
+    *    isLoggedIn: true,
+    *    user: { name: 'Juan' }
+    * });
+    *
+    * // Usar función para acceder al estado anterior
+    * slice.context.setState('cart', (prev) => ({
+    *    ...prev,
+    *    items: [...prev.items, nuevoProducto],
+    *    total: prev.total + nuevoProducto.price
+    * }));
+    */
+   setState(name, updater) {
+      if (!this.contexts.has(name)) {
+         slice.logger.logError('ContextManager', `El contexto "${name}" no existe`);
+         return;
+      }
+
+      const context = this.contexts.get(name);
+      const prevState = context.state;
+
+      // Calcular nuevo estado
+      let newState;
+      if (typeof updater === 'function') {
+         newState = updater(prevState);
+      } else {
+         newState = updater;
+      }
+
+      // Guardar nuevo estado
+      context.state = newState;
+
+      // Persistir si está habilitado
+      if (context.options.persist) {
+         this._saveToStorage(name, newState, context.options.storageKey);
+      }
+
+      // Emitir evento para notificar a los watchers
+      slice.events.emit(`context:${name}`, newState, prevState);
+
+      slice.logger.logInfo('ContextManager', `Contexto "${name}" actualizado`);
+   }
+
+   // ============================================
+   // WATCH (OBSERVAR CAMBIOS)
+   // ============================================
+
+   /**
+    * Observar cambios en un contexto
+    * @param {string} name - Nombre del contexto
+    * @param {HTMLElement} component - Componente Slice para auto-cleanup
+    * @param {Function} callback - Función a ejecutar cuando cambia
+    * @param {Function} selector - Opcional. Función para seleccionar campos específicos
+    * @returns {string} subscriptionId
+    *
+    * @example
+    * // Observar todo el estado
+    * slice.context.watch('auth', this, (state) => {
+    *    this.render(state);
+    * });
+    *
+    * // Observar un campo específico
+    * slice.context.watch('auth', this, (name) => {
+    *    this.$name.textContent = name;
+    * }, state => state.user.name);
+    *
+    * // Observar múltiples campos
+    * slice.context.watch('auth', this, (data) => {
+    *    this.$name.textContent = data.name;
+    *    this.$avatar.src = data.avatar;
+    * }, state => ({
+    *    name: state.user.name,
+    *    avatar: state.user.avatar
+    * }));
+    *
+    * // Valores computados
+    * slice.context.watch('cart', this, (total) => {
+    *    this.$total.textContent = `$${total}`;
+    * }, state => state.items.reduce((sum, i) => sum + i.price, 0));
+    */
+   watch(name, component, callback, selector = null) {
+      if (!this.contexts.has(name)) {
+         slice.logger.logError('ContextManager', `El contexto "${name}" no existe`);
+         return null;
+      }
+
+      if (!component?.sliceId) {
+         slice.logger.logError('ContextManager', 'watch() requiere un componente Slice válido');
+         return null;
+      }
+
+      if (typeof callback !== 'function') {
+         slice.logger.logError('ContextManager', 'El callback debe ser una función');
+         return null;
+      }
+
+      // Guardar el valor anterior del selector para comparar
+      let lastSelectedValue = selector ? this._getSelectedValue(name, selector) : this.getState(name);
+
+      // Crear wrapper que aplica el selector y compara
+      const wrappedCallback = (newState, prevState) => {
+         if (selector) {
+            const newSelectedValue = this._applySelector(newState, selector);
+            const prevSelectedValue = this._applySelector(prevState, selector);
+
+            // Solo ejecutar si el valor seleccionado cambió
+            if (!this._isEqual(newSelectedValue, prevSelectedValue)) {
+               lastSelectedValue = newSelectedValue;
+               callback(newSelectedValue);
+            }
+         } else {
+            // Sin selector, siempre ejecutar
+            callback(newState);
+         }
+      };
+
+      // Suscribirse al evento del contexto
+      const subscriptionId = slice.events.subscribe(`context:${name}`, wrappedCallback, { component });
+
+      slice.logger.logInfo('ContextManager', `Watch registrado en "${name}" para ${component.sliceId}`);
+
+      return subscriptionId;
+   }
+
+   // ============================================
+   // UTILIDADES
+   // ============================================
+
+   /**
+    * Verificar si un contexto existe
+    * @param {string} name - Nombre del contexto
+    * @returns {boolean}
+    */
+   has(name) {
+      return this.contexts.has(name);
+   }
+
+   /**
+    * Eliminar un contexto
+    * @param {string} name - Nombre del contexto
+    * @returns {boolean}
+    */
+   destroy(name) {
+      if (!this.contexts.has(name)) {
+         return false;
+      }
+
+      const context = this.contexts.get(name);
+
+      // Limpiar storage si existe
+      if (context.options.persist) {
+         this._removeFromStorage(context.options.storageKey);
+      }
+
+      this.contexts.delete(name);
+
+      slice.logger.logInfo('ContextManager', `Contexto "${name}" eliminado`);
+
+      return true;
+   }
+
+   /**
+    * Obtener lista de todos los contextos
+    * @returns {Array<string>}
+    */
+   list() {
+      return Array.from(this.contexts.keys());
+   }
+
+   // ============================================
+   // MÉTODOS PRIVADOS
+   // ============================================
+
+   /**
+    * Aplicar selector al estado
+    */
+   _applySelector(state, selector) {
+      try {
+         return selector(state);
+      } catch (error) {
+         slice.logger.logWarning('ContextManager', 'Error al aplicar selector', error);
+         return undefined;
+      }
+   }
+
+   /**
+    * Obtener valor seleccionado del estado actual
+    */
+   _getSelectedValue(name, selector) {
+      const state = this.getState(name);
+      return this._applySelector(state, selector);
+   }
+
+   /**
+    * Comparar dos valores (shallow)
+    */
+   _isEqual(a, b) {
+      // Mismo valor primitivo o referencia
+      if (a === b) return true;
+
+      // Si alguno es null/undefined
+      if (a == null || b == null) return false;
+
+      // Si no son objetos, ya sabemos que son diferentes
+      if (typeof a !== 'object' || typeof b !== 'object') return false;
+
+      // Comparación shallow de objetos
+      const keysA = Object.keys(a);
+      const keysB = Object.keys(b);
+
+      if (keysA.length !== keysB.length) return false;
+
+      for (const key of keysA) {
+         if (a[key] !== b[key]) return false;
+      }
+
+      return true;
+   }
+
+   /**
+    * Cargar estado desde localStorage
+    */
+   _loadFromStorage(name) {
+      try {
+         const key = `slice_context_${name}`;
+         const data = localStorage.getItem(key);
+         if (data) {
+            return JSON.parse(data);
+         }
+      } catch (error) {
+         slice.logger.logWarning('ContextManager', `Error cargando "${name}" de localStorage`, error);
+      }
+      return null;
+   }
+
+   /**
+    * Guardar estado en localStorage
+    */
+   _saveToStorage(name, state, storageKey) {
+      try {
+         localStorage.setItem(storageKey, JSON.stringify(state));
+      } catch (error) {
+         slice.logger.logWarning('ContextManager', `Error guardando "${name}" en localStorage`, error);
+      }
+   }
+
+   /**
+    * Eliminar estado de localStorage
+    */
+   _removeFromStorage(storageKey) {
+      try {
+         localStorage.removeItem(storageKey);
+      } catch (error) {
+         // Ignorar errores al eliminar
+      }
+   }
+}