slicejs-web-framework 1.0.9 → 1.0.12

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "slicejs-web-framework",
-  "version": "1.0.9",
+  "version": "1.0.12",
   "description": "",
   "engines": {
     "node": "20.x"

package/src/Components/AppComponents/DocumentationPage/DocumentationPage.js

@@ -48,8 +48,8 @@ export default class DocumentationPage extends HTMLElement {
                      },
                      {
                         title: 'Services',
-                        path: '/Documentation/Services',
-                        component: 'ServicesDocumentation'
+                        path: '/Documentation/Service',
+                        component: 'ServiceDocumentation'
                      },
                      {
                         title: 'Lifecycle methods',

package/src/Components/AppComponents/ServiceDocumentation/ServiceDocumentation.css

@@ -0,0 +1,82 @@
+slice-servicedocumentation {
+  color: var(--font-primary-color);
+  font-family: var(--font-family);
+}
+
+slice-servicedocumentation h1,
+slice-servicedocumentation h2,
+slice-servicedocumentation h3 {
+  margin-top: 1.5em;
+  margin-bottom: 0.5em;
+}
+
+slice-servicedocumentation p {
+  line-height: 1.6;
+  margin: 1em 0;
+}
+
+slice-servicedocumentation ul,
+slice-servicedocumentation ol {
+  margin: 1em 0;
+  padding-left: 2em;
+}
+
+slice-servicedocumentation li {
+  margin-bottom: 0.5em;
+}
+
+slice-servicedocumentation code {
+  font-family: monospace;
+  background-color: var(--secondary-background-color);
+  padding: 0.2em 0.4em;
+  border-radius: 3px;
+  font-size: 0.9em;
+}
+
+slice-servicedocumentation .service-example,
+slice-servicedocumentation .service-usage-example,
+slice-servicedocumentation .fetch-manager-example,
+slice-servicedocumentation .local-storage-example,
+slice-servicedocumentation .indexed-db-example,
+slice-servicedocumentation .translator-example,
+slice-servicedocumentation .custom-service-example {
+  margin: 1.5em 0;
+}
+
+slice-servicedocumentation strong {
+  color: var(--primary-color);
+}
+
+slice-servicedocumentation .faq-section {
+  margin: 2em 0;
+}
+
+slice-servicedocumentation .faq-section slice-details {
+  margin-bottom: 1em;
+}
+
+slice-servicedocumentation table {
+  width: 100%;
+  border-collapse: collapse;
+  margin: 1.5em 0;
+}
+
+slice-servicedocumentation th,
+slice-servicedocumentation td {
+  padding: 0.75em;
+  text-align: left;
+  border-bottom: 1px solid var(--primary-color-shade);
+}
+
+slice-servicedocumentation th {
+  background-color: var(--primary-color);
+  color: var(--primary-color-contrast);
+}
+
+slice-servicedocumentation .service-section {
+  padding: 1em;
+  margin: 1em 0;
+  border-left: 3px solid var(--primary-color);
+  background-color: var(--secondary-background-color);
+  border-radius: 0 var(--border-radius-slice) var(--border-radius-slice) 0;
+}

package/src/Components/AppComponents/ServiceDocumentation/ServiceDocumentation.html

@@ -0,0 +1,74 @@
+<h1 id="serviceComponents">Service Components</h1>
+
+<p>
+  Service components in Slice.js handle business logic and data operations without a visual representation. They provide reusable functionality that can be shared across visual components, serving as the backbone of your application's data layer and business logic.
+</p>
+
+<h2 id="serviceComponentOverview">What are Service Components?</h2>
+<p>
+  Service components in Slice.js:
+</p>
+<ul>
+  <li>Handle data operations, API communication, and business logic</li>
+  <li>Don't have visual representation or DOM elements</li>
+  <li>Can be shared across multiple visual components</li>
+  <li>Often follow the singleton pattern (one instance shared throughout the application)</li>
+  <li>Provide a clean separation between UI and business logic</li>
+</ul>
+
+<h2 id="buildingServiceComponents">Creating Service Components</h2>
+<p>
+  Here's a basic example of a service component that fetches and caches data from an API:
+</p>
+<div class="service-example"></div>
+
+<h2 id="usingServiceComponents">Using Service Components</h2>
+<p>
+  Services are built using <code>slice.build()</code> just like visual components, but they interact differently with the application:
+</p>
+<div class="service-usage-example"></div>
+
+<h2 id="builtInServices">Built-in Service Components</h2>
+
+<h3 id="fetchManager">FetchManager</h3>
+<p>
+  The FetchManager service simplifies API communication with features like automatic loading indicators, timeout handling, error management, and response caching:
+</p>
+<div class="fetch-manager-example"></div>
+
+<h3 id="localStorageManager">LocalStorageManager</h3>
+<p>
+  The LocalStorageManager service provides a simplified interface for working with browser localStorage, including automatic JSON serialization and error handling:
+</p>
+<div class="local-storage-example"></div>
+
+<h3 id="indexedDbManager">IndexedDbManager</h3>
+<p>
+  The IndexedDbManager service offers a simplified API for working with IndexedDB, providing methods for CRUD operations on object stores:
+</p>
+<div class="indexed-db-example"></div>
+
+<h3 id="translator">Translator</h3>
+<p>
+  The Translator service enables internationalization in your application, allowing you to support multiple languages:
+</p>
+<div class="translator-example"></div>
+
+<h2 id="customServices">Creating Custom Service Components</h2>
+<p>
+  You can create custom service components for specific application needs. Here's an example of a custom authentication service:
+</p>
+<div class="custom-service-example"></div>
+
+<h2 id="serviceComponentBestPractices">Best Practices</h2>
+<ul>
+  <li><strong>Single Responsibility</strong>: Each service should focus on a specific domain or functionality</li>
+  <li><strong>Error Handling</strong>: Implement robust error handling and logging within services</li>
+  <li><strong>Caching Strategy</strong>: Use appropriate caching strategies to improve performance</li>
+  <li><strong>Service Composition</strong>: Compose complex services by combining simpler services</li>
+  <li><strong>Dependency Injection</strong>: Pass dependencies to services through their constructors</li>
+  <li><strong>Consistent API</strong>: Design service APIs with consistent naming and behavior patterns</li>
+</ul>
+
+<h2 id="serviceComponentsFaq">Frequently Asked Questions</h2>
+<div class="faq-section"></div>

package/src/Components/AppComponents/ServiceDocumentation/ServiceDocumentation.js

@@ -0,0 +1,416 @@
+export default class ServiceDocumentation extends HTMLElement {
+   constructor(props) {
+      super();
+      slice.attachTemplate(this);
+
+      slice.controller.setComponentProps(this, props);
+      this.debuggerProps = [];
+   }
+
+   async init() {
+      // Create simple service example
+      const serviceExample = await slice.build('CodeVisualizer', {
+         value: `// Example: Basic Service Component
+export default class DataService {
+   constructor(props = {}) {
+      // Initialize state and config
+      this.baseUrl = props.baseUrl || 'https://api.example.com';
+      this.cache = new Map();
+      
+      // Register with controller if needed
+      if (props.sliceId) {
+         slice.controller.registerComponent(this);
+      }
+   }
+
+   async fetchData(endpoint) {
+      // Check cache first
+      if (this.cache.has(endpoint)) {
+         return this.cache.get(endpoint);
+      }
+      
+      // Show loading indicator
+      slice.loading.start();
+      
+      try {
+         // Fetch data from API
+         const response = await fetch(\`\${this.baseUrl}/\${endpoint}\`);
+         const data = await response.json();
+         
+         // Cache the response
+         this.cache.set(endpoint, data);
+         return data;
+      } catch (error) {
+         // Log error
+         slice.logger.logError('DataService', \`Error fetching \${endpoint}\`, error);
+         throw error;
+      } finally {
+         // Hide loading indicator
+         slice.loading.stop();
+      }
+   }
+   
+   clearCache() {
+      this.cache.clear();
+   }
+}`,
+         language: 'javascript'
+      });
+      
+      this.querySelector('.service-example').appendChild(serviceExample);
+
+      // Create service usage example
+      const serviceUsageExample = await slice.build('CodeVisualizer', {
+         value: `// Building and using a service component
+const dataService = await slice.build('DataService', {
+   baseUrl: 'https://api.myapp.com/v1',
+   sliceId: 'data-service'
+});
+
+// Using the service in a visual component
+export default class ProductList extends HTMLElement {
+   constructor(props) {
+      super();
+      slice.attachTemplate(this);
+      this.$productList = this.querySelector('.product-list');
+      
+      slice.controller.setComponentProps(this, props);
+   }
+   
+   async init() {
+      // Get a reference to our service
+      this.dataService = slice.controller.getComponent('data-service');
+      
+      // Load initial data
+      await this.loadProducts();
+   }
+   
+   async loadProducts() {
+      try {
+         // Use the service to fetch data
+         const products = await this.dataService.fetchData('products');
+         
+         // Render the products
+         this.renderProducts(products);
+      } catch (error) {
+         // Handle error
+         this.showError("Failed to load products");
+      }
+   }
+   
+   renderProducts(products) {
+      // Clear existing content
+      this.$productList.innerHTML = '';
+      
+      // Create product items
+      products.forEach(async product => {
+         const productItem = await slice.build('ProductItem', { product });
+         this.$productList.appendChild(productItem);
+      });
+   }
+}`,
+         language: 'javascript'
+      });
+      
+      this.querySelector('.service-usage-example').appendChild(serviceUsageExample);
+
+      // Create FetchManager example
+      const fetchManagerExample = await slice.build('CodeVisualizer', {
+         value: `// Using the built-in FetchManager service
+const fetchManager = await slice.build('FetchManager', {
+   baseUrl: 'https://api.example.com',
+   timeout: 5000,
+   sliceId: 'api-manager'
+});
+
+// Making API requests with FetchManager
+const userData = await fetchManager.request(
+   'GET',                       // HTTP Method
+   null,                        // Request body (for POST/PUT)
+   'users/profile',             // Endpoint
+   (data, response) => {        // onRequestSuccess callback
+      console.log('Success!', data);
+   },
+   (data, response) => {        // onRequestError callback
+      console.error('Error:', response.status);
+   },
+   true,                        // refetchOnError
+   {                            // requestOptions
+      headers: {
+         'Authorization': 'Bearer token123'
+      }
+   }
+);
+
+// Enabling caching
+fetchManager.enableCache();
+
+// Setting default headers for all requests
+fetchManager.setDefaultHeaders({
+   'Content-Type': 'application/json',
+   'X-API-Key': 'your-api-key'
+});`,
+         language: 'javascript'
+      });
+      
+      this.querySelector('.fetch-manager-example').appendChild(fetchManagerExample);
+
+      // Create LocalStorageManager example
+      const localStorageExample = await slice.build('CodeVisualizer', {
+         value: `// Using the LocalStorageManager service
+const storageManager = await slice.build('LocalStorageManager', {
+   sliceId: 'storage-manager'
+});
+
+// Storing data
+storageManager.setItem('user-preferences', {
+   theme: 'dark',
+   language: 'en',
+   notifications: true
+});
+
+// Retrieving data
+const preferences = storageManager.getItem('user-preferences');
+console.log(preferences.theme); // 'dark'
+
+// Removing data
+storageManager.removeItem('temporary-data');
+
+// Clearing all data
+storageManager.clear();`,
+         language: 'javascript'
+      });
+      
+      this.querySelector('.local-storage-example').appendChild(localStorageExample);
+
+      // Create IndexedDbManager example
+      const indexedDbExample = await slice.build('CodeVisualizer', {
+         value: `// Using the IndexedDbManager service
+const dbManager = await slice.build('IndexedDbManager', {
+   databaseName: 'app-database',
+   storeName: 'tasks',
+   sliceId: 'db-manager'
+});
+
+// Opening the database
+await dbManager.openDatabase();
+
+// Adding an item
+const newTask = {
+   title: 'Complete documentation',
+   priority: 'high',
+   completed: false,
+   dueDate: new Date()
+};
+const taskId = await dbManager.addItem(newTask);
+
+// Getting an item
+const task = await dbManager.getItem(taskId);
+
+// Updating an item
+task.completed = true;
+await dbManager.updateItem(task);
+
+// Getting all items
+const allTasks = await dbManager.getAllItems();
+
+// Deleting an item
+await dbManager.deleteItem(taskId);
+
+// Close the database when done
+dbManager.closeDatabase();`,
+         language: 'javascript'
+      });
+      
+      this.querySelector('.indexed-db-example').appendChild(indexedDbExample);
+
+      // Create translator example
+      const translatorExample = await slice.build('CodeVisualizer', {
+         value: `// Configuring the Translator service in sliceConfig.json
+{
+   "translator": {
+      "enabled": true
+   }
+}
+
+// messages.json structure
+{
+   "en": {
+      "button": {
+         "value": "Submit"
+      },
+      "header": {
+         "title": "Welcome to our application"
+      }
+   },
+   "es": {
+      "button": {
+         "value": "Enviar"
+      },
+      "header": {
+         "title": "Bienvenido a nuestra aplicación"
+      }
+   }
+}
+
+// Using translation in components
+export default class Header extends HTMLElement {
+   constructor(props) {
+      super();
+      slice.attachTemplate(this);
+      this.$title = this.querySelector('.title');
+      
+      slice.controller.setComponentProps(this, props);
+   }
+   
+   init() {
+      // Properties will be automatically translated
+      // based on the current language
+   }
+}
+
+// Changing the language
+slice.translator.changeLanguage('es');`,
+         language: 'javascript'
+      });
+      
+      this.querySelector('.translator-example').appendChild(translatorExample);
+
+      // Create custom service example
+      const customServiceExample = await slice.build('CodeVisualizer', {
+         value: `// Creating a custom service component
+export default class AuthService {
+   constructor(props = {}) {
+      this.apiUrl = props.apiUrl || '/api/auth';
+      this.tokenKey = 'auth_token';
+      this.user = null;
+      
+      // Register with controller
+      if (props.sliceId) {
+         slice.controller.registerComponent(this);
+      }
+      
+      // Create storage manager for token persistence
+      this.storageManager = new (slice.controller.classes.get('LocalStorageManager'))();
+      
+      // Initialize fetch manager for API calls
+      this.fetchManager = new (slice.controller.classes.get('FetchManager'))({
+         baseUrl: this.apiUrl
+      });
+   }
+   
+   async init() {
+      // Check for existing token on initialization
+      const token = this.storageManager.getItem(this.tokenKey);
+      if (token) {
+         try {
+            // Validate the token and get user info
+            await this.validateToken(token);
+         } catch (error) {
+            // Clear invalid token
+            this.logout();
+         }
+      }
+   }
+   
+   async login(username, password) {
+      try {
+         const response = await this.fetchManager.request(
+            'POST',
+            { username, password },
+            'login'
+         );
+         
+         if (response && response.token) {
+            this.storageManager.setItem(this.tokenKey, response.token);
+            this.user = response.user;
+            return this.user;
+         }
+      } catch (error) {
+         slice.logger.logError('AuthService', 'Login failed', error);
+         throw error;
+      }
+   }
+   
+   async validateToken(token) {
+      try {
+         const response = await this.fetchManager.request(
+            'GET',
+            null,
+            'validate',
+            null,
+            null,
+            false,
+            {
+               headers: {
+                  'Authorization': \`Bearer \${token}\`
+               }
+            }
+         );
+         
+         if (response && response.valid) {
+            this.user = response.user;
+            return true;
+         }
+         return false;
+      } catch (error) {
+         return false;
+      }
+   }
+   
+   isAuthenticated() {
+      return !!this.user;
+   }
+   
+   logout() {
+      this.user = null;
+      this.storageManager.removeItem(this.tokenKey);
+   }
+   
+   getUser() {
+      return this.user;
+   }
+}`,
+         language: 'javascript'
+      });
+      
+      this.querySelector('.custom-service-example').appendChild(customServiceExample);
+
+      // Create FAQ section
+      const faqQuestions = [
+         {
+            title: "How do services differ from visual components?",
+            text: "Service components focus on business logic and data management without any visual representation. They don't extend HTMLElement or use templates. Instead, they provide methods and properties that other components can use to perform operations like API calls, data storage, or other application services."
+         },
+         {
+            title: "Should I register service components with the controller?",
+            text: "Yes, registering service components with the controller allows them to be accessed globally via slice.controller.getComponent(). This makes it easy to share a single instance of a service across multiple components, following the singleton pattern for services like API clients or authentication managers."
+         },
+         {
+            title: "How can I handle authentication in Slice.js?",
+            text: "Create a dedicated AuthService component that handles login, logout, token management, and user information. Store authentication tokens using LocalStorageManager or IndexedDbManager, and add methods to check if the user is authenticated. Other components can then use this service to secure routes or display user-specific content."
+         },
+         {
+            title: "Can services communicate with each other?",
+            text: "Yes, services can communicate with each other by accessing other service instances through slice.controller.getComponent() or by dependency injection in the constructor. For example, an AuthService might use a FetchManager for API calls and a LocalStorageManager for token persistence."
+         },
+         {
+            title: "How do I handle offline functionality?",
+            text: "Implement a SyncService that works with IndexedDbManager to store data locally when offline. This service should track changes made offline and synchronize them when the connection is restored. You can use the FetchManager with a custom queue system to manage pending requests."
+         }
+      ];
+
+      const faqContainer = this.querySelector('.faq-section');
+      
+      for (const question of faqQuestions) {
+         const detailsComponent = await slice.build('Details', {
+            title: question.title,
+            text: question.text
+         });
+         
+         faqContainer.appendChild(detailsComponent);
+      }
+   }
+}
+
+customElements.define('slice-servicedocumentation', ServiceDocumentation);

package/src/Components/AppComponents/SliceStylesDocumentation/SliceStylesDocumentation.css

@@ -0,0 +1,56 @@
+slice-slicestylesdocumentation {
+  color: var(--font-primary-color);
+}
+
+slice-slicestylesdocumentation .style-section {
+  margin-bottom: 30px;
+}
+
+slice-slicestylesdocumentation .style-preview {
+  background-color: var(--secondary-background-color);
+  padding: 15px;
+  border-radius: var(--border-radius-slice);
+  margin: 10px 0;
+}
+
+slice-slicestylesdocumentation .scrollbar-demo {
+  max-height: 100px;
+  overflow-y: scroll;
+  padding: 15px;
+  background-color: var(--secondary-background-color);
+  border-radius: var(--border-radius-slice);
+}
+
+slice-slicestylesdocumentation .caret-demo {
+  display: flex;
+  align-items: center;
+  gap: 20px;
+  margin: 20px 0;
+}
+
+slice-slicestylesdocumentation .color-variable {
+  display: inline-block;
+  width: 20px;
+  height: 20px;
+  border-radius: 50%;
+  margin-right: 10px;
+  vertical-align: middle;
+}
+
+slice-slicestylesdocumentation .variables-table {
+  width: 100%;
+  border-collapse: collapse;
+  margin: 20px 0;
+}
+
+slice-slicestylesdocumentation .variables-table th,
+slice-slicestylesdocumentation .variables-table td {
+  padding: 10px;
+  text-align: left;
+  border-bottom: 1px solid var(--primary-color-shade);
+}
+
+slice-slicestylesdocumentation .variables-table th {
+  background-color: var(--primary-color);
+  color: var(--primary-color-contrast);
+}

package/src/Components/AppComponents/SliceStylesDocumentation/SliceStylesDocumentation.html

@@ -0,0 +1,28 @@
+<h1 id="sliceStyles">Slice Styles</h1>
+<p>
+  Slice.js provides global styles through the <code>sliceStyles.css</code> file, which establishes consistent base styling across your application. These styles include CSS variables, resets, and utility classes.
+</p>
+
+<h2 id="cssVariables">CSS Variables</h2>
+<p>
+  Core CSS variables are defined in the <code>:root</code> element and are available throughout your application.
+</p>
+<div class="css-variables"></div>
+
+<h2 id="bodyStyles">Base Body Styles</h2>
+<p>
+  The framework applies minimal base styling to the <code>body</code> element.
+</p>
+<div class="body-styles"></div>
+
+<h2 id="caretStyles">Caret/Dropdown Styles</h2>
+<p>
+  The framework provides styles for dropdown carets used in various components.
+</p>
+<div class="caret-styles"></div>
+
+<h2 id="scrollbarStyles">Custom Scrollbar</h2>
+<p>
+  Slice.js includes global custom scrollbar styling for all elements.
+</p>
+<div class="scrollbar-styles"></div>