turbo-web 4.2.6 → 4.2.8

package/README.md

@@ -0,0 +1,133 @@
+# TURBO-WEB FRAMEWORK
+
+## I. OVERVIEW
+
+---
+
+Lightweight JavaScript framework based on a book "Build a **Frontend Web Framework** (from scratch)" by **Angel Sola Orbaiceta** with additional features sprinkled on top.
+
+[//]: # (Installation instructions.)
+## II. INSTALLATION
+
+---
+There are 4 ways to utilize this framework: **NPM installation**, **SETUP script** (NODE), **locally** and through **CDN**.
+### (1) NPM Installation
+To install Turbo-Web framework, run in your terminal ```npm install turbo-web```
+
+### (2) NODE initialization script
+To install the framework with pre-configured templates using CLI, run in your terminal ```npx turbo-web PROJECT_NAME```
+This will create a starting kit: project directory, package.json, index.html + src/ with router.js, main.js and store.js
+
+// script exists under bin/turbo-charge.js
+
+### (3) Locally
+To import the framework locally - you must include the bundled file located in ```./framework/runtime/dist/turbo.js``` as imports
+
+// This file can be generated using script ```npm run build```
+
+Example:
+
+```'import {createApp, defineComponent, h, hFragment,} from '../../../framework/runtime/dist/turbo.js'```
+
+### (4) Using CDN (Content Delivery Network)
+You can import any version of the framework directly into your JS file:
+
+```import {createApp, defineComponent, h, hFragment,} from 'https://unpkg.com/turbo-web'```
+
+CDN Version control ( version 1x.2x.3x):
+1. x MAJOR: @1 or @^1.0.0 - fetches latest compatible minor and path release
+2. x MINOR: @1.2 or @~1.2.0 - fetches latest compatible patch release of a certain MINOR version 0.X.0
+3. x PATCH: @1.2.3 - fetches a specific build with full version control
+
+``````import ... from 'https://unpkg.com/turbo-web@2'`````` - will import latest minor + patch version of 2.X.X.
+
+[//]: # (A "Getting Started" guide.)
+## III. GETTING STARTED
+
+---
+
+### [1] IMPORT
+1. (2.) NPM installation & NODE script: Import from packages:
+> import { createApp, defineComponent, h, hFragment } from 'turbo-web'
+
+3. (4.) Locally & CDN: You must use relative paths (./ or ../):
+> import { createApp, defineComponent, h, hFragment } from './framework/runtime/index.js'
+
+### [2] LAUNCH
+
+You can run server using ```npm run serve:examples```.
+
+If you change code inside **examples/** make sure to do a hard reset for changes to apply:
+> F12 -> right-click on the REFRESH button -> Empty Cache & Hard Reload  OR ( Ctrl + Shift + R )
+
+
+[//]: # (A detailed explanation of each feature with code examples.)
+## IV. FEATURES
+
+---
+
+### [CORE] Feature 1: Declarative UI
+Using declarative methods to define final UI instead of manually handling DOM elements. "What the UI looks like vs step-by-step imperative programming"
+
+### [CORE] Feature 2: Virtual DOM
+Inversed Control principle - the user doesn't need to manipulate the DOM directly, the framework creates a lightweight
+JavaScript object tree that represents the UI.
+
+### [CORE] Feature 3: Reconciliation Algorithm
+Inversed Control principle - optimizing DOM manipulations by the process of diffing and patching only the required nodes (improves DOM re-rendering & re-painting).
+
+### [CORE] Feature 4: Components
+Encapsulation & Reusability principles: making UI building blocks with better combined hierarchical tree structure.
+
+### Feature 5: Client-Side Router (#hash-based)
+Allows for the **SPA design** (Single Page Application) with route guards (fn: checkNavigation) and a common "catch-all route" (cases: route not found). Based on a hash part of the URL, implemented with regex pattern matching by simulating URL path, parameters and query as part of the hash fragment itself.
+// router.js, route-matchers.js
+
+### Feature 6: Centralized Store
+Separation of Concerns & Single Source of Truth principles: Allows for a global state handling and eliminates the need for prop drilling.
+...
+
+### Feature 7: Persistent Storage
+Single Source of Truth principle: App's state is persistent between sessions.
+...
+
+...
+
+### Feature X: Node-based Initialization through CLI
+Scaffolding setup script that creates base structure with required templates for the App.
+
+Script: ```npx turbo-web ${PROJECT_NAME}``` creates "Project" & src directory + main.js, router.js, store.js + package.json
+
+[//]: # (Best practices and guidelines for building applications with the framework.)
+## V. BEST PRACTICES
+
+---
+
+### Routing
+
+
+```const routes = [{ path: '/', component: Home }, {}, {}]```
+```const router = new HashRouter(routes)```
+```await router.init()```
+```#isInitialized```
+
+### Components
+...
+
+### Centralized Store
+Must be initialized in a separate file (store.js).
+```
+export const store = new Store({
+    state: {
+        count: 0,
+        user: null
+    },
+    mutations: {
+        increment(state, payload = 1) {
+            state.count += payload
+        },
+        setUser(state, user) {
+            state.user = user
+        }
+    }
+```

package/dist/turbo.js

@@ -1050,6 +1050,9 @@ function defineComponent({ render, state, ...methods }) {
         get appContext() {
             return this.#appContext
         }
+        get $http() {
+            return this.appContext?.http;
+        }
         get elements() {
             if (this.#vdom == null) {
                 return []
@@ -1172,10 +1175,11 @@ const RouterLink = defineComponent({
 const RouterOutlet = defineComponent({
     state() {
         return {
-            matchedRoute: this.appContext.router.matchedRoute,
+            matchedRoute: null,
         }
     },
     onMounted() {
+        this.updateState({ matchedRoute: this.appContext.router.matchedRoute });
         this.boundHandler = this.handleRouteChange.bind(this);
         this.appContext.router.subscribe(this.boundHandler);
     },
@@ -1193,4 +1197,59 @@ const RouterOutlet = defineComponent({
     },
 });
 
-export { DOM_TYPES, HashRouter, RouterLink, RouterOutlet, createApp, defineComponent, h, hFragment, hSlot, hString, nextTick };
+class Store {
+    #state = {}
+    #initialState = {}
+    #mutations = {}
+    #actions = {}
+    #dispatcher = new Dispatcher()
+    #storageKey = 'turbo_state'
+    constructor({ state = {}, mutations = {}, actions = {} }) {
+        this.#initialState = structuredClone(state);
+        const saved = localStorage.getItem(this.#storageKey);
+        this.#state = saved ? JSON.parse(saved) : state;
+        this.#mutations = mutations;
+        this.#actions = actions;
+        window.addEventListener('storage', (event) => {
+            if (event.key === this.#storageKey && event.newValue) {
+                this.#state = JSON.parse(event.newValue);
+                this.#dispatcher.dispatch('state-change', this.state);
+            }
+        });
+    }
+    get state() {
+        return structuredClone(this.#state)
+    }
+    commit(mutationName, payload) {
+        const mutation = this.#mutations[mutationName];
+        if (typeof mutation !== 'function') {
+            console.warn(`[Store] Mutation "${mutationName}" does not exist.`);
+            return
+        }
+        mutation(this.#state, payload);
+        localStorage.setItem(this.#storageKey, JSON.stringify(this.#state));
+        this.#dispatcher.dispatch('state-change', this.state);
+    }
+    async dispatch(actionName, payload) {
+        const action = this.#actions[actionName];
+        if (typeof action !== 'function') {
+            console.warn(`[Store] Action "${actionName}" does not exist.`);
+            return
+        }
+        const context = {
+            commit: this.commit.bind(this),
+            state: this.state
+        };
+        return await action(context, payload)
+    }
+    subscribe(handler) {
+        return this.#dispatcher.subscribe('state-change', handler)
+    }
+    clear() {
+        localStorage.removeItem(this.#storageKey);
+        this.#state = structuredClone(this.#initialState);
+        this.#dispatcher.dispatch('state-change', this.state);
+    }
+}
+
+export { DOM_TYPES, HashRouter, RouterLink, RouterOutlet, Store, createApp, defineComponent, h, hFragment, hSlot, hString, nextTick };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "turbo-web",
-  "version": "4.2.6",
+  "version": "4.2.8",
   "main": "dist/turbo.js",
   "files": [
     "dist",