turbo-web 4.2.10 → 4.4.0

package/README.md

@@ -67,34 +67,48 @@ If you change code inside **examples/** make sure to do a hard reset for changes
 ---
 
 ### [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"
+**Abstraction** principle: Using declarative methods to define final UI instead of manually handling DOM elements. "What the UI looks like vs step-by-step imperative programming"
+
+```component.js```
 
 ### [CORE] Feature 2: Virtual DOM
-Inversed Control principle - the user doesn't need to manipulate the DOM directly, the framework creates a lightweight
+**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.
 
+```patch-dom.js```
+
 ### [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).
+**Inversed Control** principle - optimizing DOM manipulations by the process of diffing and patching only the required nodes (improves DOM re-rendering & re-painting).
 
+```patch-dom.js```
 ### [CORE] Feature 4: Components
-Encapsulation & Reusability principles: making UI building blocks with better combined hierarchical tree structure.
+**Encapsulation & Reusability** principles: making UI building blocks with better combined hierarchical tree structure.
+
+// Events accept additional modificator ```.stop .prevent``` to stop event bubbling and prevent default browser behaviour.
+
+```component.js // building scheme: h(tagOrComponent, { attributes, class, style, on: events }, [children])```
 
 ### 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
+
+```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.
-...
+**Separation of Concerns** & **Single Source of Truth** principles: Allows for a global state handling and eliminates the need for prop drilling.
+```store.js```
 
 ### Feature 7: Persistent Storage
-Single Source of Truth principle: App's state is persistent between sessions.
-...
+**Single Source of Truth** principle: App's state is persistent between sessions.
+
+```store.js```
 
-...
+### Feature 8: built-in HTTP module.
+**Abstraction** principle: simplifies development by abstracting imperative logic in HTTP request handling.
+
+```http.js```
 
 ### Feature X: Node-based Initialization through CLI
-Scaffolding setup script that creates base structure with required templates for the App.
+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
 
@@ -103,31 +117,86 @@ Script: ```npx turbo-web ${PROJECT_NAME}``` creates "Project" & src directory +
 
 ---
 
-### Routing
+### [1] Router
+Define Routes with Guards - Use the beforeEnter guard to protect routes (e.g., authentication).
+>The router supports asynchronous guards that can either return a boolean or redirect to a different path string
 
+```
+beforeEnter: async (from, to, params, query) => {
+    const isAuthenticated = localStorage.getItem('auth_token');
+    if (!isAuthenticated) return '/login'; // Redirects to login
+    return true; // allows navigation
+}
+```
 
-```const routes = [{ path: '/', component: Home }, {}, {}]```
-```const router = new HashRouter(routes)```
-```await router.init()```
-```#isInitialized```
+### [2] RouterLink
+Always use the built-in RouterLink component instead of standard anchor tags ```(<a href="...">)``` for internal navigation.
 
-### Components
-...
+```
+export const Navbar = defineComponent({
+    render() {
+        return h('nav', {}, [
+            h(RouterLink, { to: '/' }, ['Home']),
+            h(RouterLink, { to: '/dashboard' }, ['Dashboard'])
+        ]);
+    }
+});
+```
 
-### Centralized Store
-Must be initialized in a separate file (store.js).
+### [3] Components
+Never mutate this.state directly. Always use this.updateState() to trigger the virtual DOM patching process.
+> State initialization should be done via the state() function
 ```
-export const store = new Store({
-    state: {
-        count: 0,
-        user: null
+increment() {
+    // Correct: Triggers VDOM diffing and patching
+    this.updateState({ count: this.state.count + 1 });
+        
+    // Incorrect: Will not update the UI
+    // this.state.count++; 
+}
+```
+
+### [4] Centralized Store
+Mutations must be strictly synchronous as they immediately write to localStorage and trigger state-change events. Use actions for asynchronous operations like HTTP requests, and have the action commit the mutation.
+
+```
+mutations: {
+    setLoading(state, status) {
+        state.isLoading = status; // Synchronous
     },
-    mutations: {
-        increment(state, payload = 1) {
-            state.count += payload
-        },
-        setUser(state, user) {
-            state.user = user
-        }
+    setUsers(state, users) {
+        state.users = users; // Synchronous
+    }
+},
+actions: {
+    async fetchUsers({ commit, state }) {
+        commit('setLoading', true);
+        // Async operation
+        const response = await fetch('https://api.example.com/users');
+        const data = await response.json();
+        commit('setUsers', data);
+        commit('setLoading', false);
     }
+```
+
+### [5] Subscribe to Store Changes in Components
+To make a component react to global state changes, subscribe to the store in onMounted and trigger a local re-render.
+> You must unsubscribe in ```onUnmounted```!!!.
+
+```
+onMounted() {
+    this.unsubscribe = this.appContext.store.subscribe(() => {
+        this.updateState({}); // Force re-render
+    });
+    this.appContext.store.dispatch('fetchUsers');
+},
+onUnmounted() {
+    if (this.unsubscribe) this.unsubscribe();
+},
+```
+### [6] Event bubbling & default browser behaviour override
+It is possible to prevent both by passing additional modificators with functions.
+```
+on: { 'click.stop': () => this.addLog('Button with .stop Clicked') }
+on: { 'click.prevent': () => this.addLog('Link with .prevent Clicked') }
 ```

package/bin/turbo-charge.js

@@ -41,17 +41,47 @@ fs.writeFileSync(
 
 // defines the boilerplate file contents
 const storeContent = `import { Store } from 'turbo-web';
-export const appStore = new Store({ state: { count: 0 } });`;
 
-const routerContent = `import { HashRouter } from 'turbo-web';
-export const router = new HashRouter([{ path: '/', component: null }]);`;
+export const appStore = new Store({ 
+    state: { 
+        count: 0 
+    },
+    mutations: {
+        increment(state) {
+            state.count++;
+        }
+    }
+});`;
+
+const routerContent = `import { HashRouter, defineComponent, h } from 'turbo-web';
+
+const Home = defineComponent({
+    render() {
+        return h('h2', {}, ['Welcome to Home Page']);
+    }
+});
+
+export const router = new HashRouter([
+    { path: '/', component: Home }
+]);`;
 
-const mainContent = `import { createApp, h } from 'turbo-web';
+const mainContent = `import { createApp, defineComponent, h, RouterOutlet } from 'turbo-web';
 import { router } from './router.js';
 import { appStore } from './store.js';
 
-const App = { render: () => h('div', {}, ['Turbo Power!']) };
-createApp(App, {}, { router, store: appStore }).mount(document.body);`;
+const App = defineComponent({
+    render() {
+        return h('div', { style: { padding: '20px', fontFamily: 'sans-serif' } }, [
+            h('h1', {}, ['Turbo Power! 🚀']),
+            h('hr'),
+            // RouterOutlet renders the components defined in router.js
+            h(RouterOutlet) 
+        ]);
+    }
+});
+
+const app = createApp(App, {}, { router, store: appStore });
+app.mount(document.body);`;
 
 // write the files to the user's new project directory
 fs.writeFileSync(path.join(srcPath, 'store.js'), storeContent);

package/dist/turbo.js

@@ -194,8 +194,15 @@ function hSlot(name = 'default', children = []) {
     return { type: DOM_TYPES.SLOT, name: name, children: children }
 }
 
-function addEventListener(eventName, handler, el, hostComponent = null) {
-    function boundHandler() {
+function addEventListener(eventNameWithModifiers, handler, el, hostComponent = null) {
+    const [eventName, ...modifiers] = eventNameWithModifiers.split('.');
+    function boundHandler(event) {
+        if (modifiers.includes('stop')) {
+            event.stopPropagation();
+        }
+        if (modifiers.includes('prevent')) {
+            event.preventDefault();
+        }
         hostComponent
             ? handler.apply(hostComponent, arguments)
             : handler(...arguments);
@@ -212,7 +219,8 @@ function addEventListeners(listeners = {}, el, hostComponent = null ) {
     return addedListeners
 }
 function removeEventListeners(listeners = {}, el) {
-    Object.entries(listeners).forEach(([eventName, handler]) => {
+    Object.entries(listeners).forEach(([eventNameWithModifiers, handler]) => {
+        const eventName = eventNameWithModifiers.split('.')[0];
         el.removeEventListener(eventName, handler);
     });
 }
@@ -893,14 +901,14 @@ function patchStyles(el, oldStyle = {}, newStyle = {}) {
 }
 function patchEvents(el, oldListeners = {}, oldEvents = {}, newEvents = {}, hostComponent) {
     const { removed, added, updated } = objectsDiff(oldEvents, newEvents);
-    for (const eventName of removed.concat(updated)) {
-        el.removeEventListener(eventName, oldListeners[eventName]);
+    for (const eventNameWithModifiers of removed.concat(updated)) {
+        const eventName = eventNameWithModifiers.split('.')[0];
+        el.removeEventListener(eventName, oldListeners[eventNameWithModifiers]);
     }
     const addedListeners = {};
-    for (const eventName of added.concat(updated)) {
-        const listener =
-            addEventListener(eventName, newEvents[eventName], el, hostComponent);
-        addedListeners[eventName] = listener;
+    for (const eventNameWithModifiers of added.concat(updated)) {
+        const listener = addEventListener(eventNameWithModifiers, newEvents[eventNameWithModifiers], el, hostComponent);
+        addedListeners[eventNameWithModifiers] = listener;
     }
     return addedListeners
 }

package/package.json

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