turbo-web 4.2.5 → 4.2.7

package/README.md

@@ -0,0 +1,132 @@
+# 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/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.
+...
+
+[//]: # (Best practices and guidelines for building applications with the framework.)
+## V. BEST PRACTICES
+
+---
+
+### Routing
+Make sure to ...
+
+```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/bin/turbo-charge.js

@@ -5,7 +5,6 @@ import '../dist/turbo.js';
 import fs from 'fs';
 import path from 'path';
 
-// 1. gets the project name from the terminal command
 const projectName = process.argv[2];
 
 if (!projectName) {
@@ -14,41 +13,67 @@ if (!projectName) {
     process.exit(1);
 }
 
-// 2. defines the target directory path
+// defines the target directory path
 const projectPath = path.join(process.cwd(), projectName);
+const srcPath = path.join(projectPath, 'src');
 
-// 3. creates the directories
+// creates the directories
 fs.mkdirSync(projectPath, { recursive: true });
 fs.mkdirSync(path.join(projectPath, 'src'), { recursive: true });
 
-// 4. defines the boilerplate file contents
-const storeContent = `import { Store } from 'your-framework';
-
-export const appStore = new Store({
-    state: {},
-    mutations: {},
-    actions: {}
-});
-`;
-
-const routerContent = `export function initRouter() {
-    window.addEventListener('hashchange', () => {
-        const path = window.location.hash.slice(1).toLowerCase() || '/';
-        console.log('Navigated to:', path);
-        // Add route matching and component mounting logic here
-    });
-}
-`;
+// auto initiating package.json
+const packageJsonContent = {
+    name: projectName,
+    version: "1.0.0",
+    type: "module",
+    dependencies: {
+        "turbo-web": "latest"
+    },
+    scripts: {
+        "start": "npx serve ."
+    }
+};
+
+fs.writeFileSync(
+    path.join(projectPath, 'package.json'),
+    JSON.stringify(packageJsonContent, null, 2)
+);
+
+// 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 }]);`;
+
+const mainContent = `import { createApp, h } 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);`;
+
+// write the files to the user's new project directory
+fs.writeFileSync(path.join(srcPath, 'store.js'), storeContent);
+fs.writeFileSync(path.join(srcPath, 'router.js'), routerContent);
+fs.writeFileSync(path.join(srcPath, 'main.js'), mainContent);
 
-const mainContent = `import { appStore } from './store.js';
-import { initRouter } from './router.js';
+// defining HTML
+const htmlContent = `<!DOCTYPE html>
+<html>
+<head><title>${projectName}</title></head>
+<body>
+    <script type="module" src="./src/main.js"></script>
+</body>
+</html>`;
 
-initRouter();
-`;
+fs.writeFileSync(path.join(projectPath, 'index.html'), htmlContent);
 
-// 5. Write the files to the user's new project directory
-fs.writeFileSync(path.join(projectPath, 'src', 'store.js'), storeContent);
-fs.writeFileSync(path.join(projectPath, 'src', 'router.js'), routerContent);
-fs.writeFileSync(path.join(projectPath, 'src', 'main.js'), mainContent);
+console.log(`
+BUENO! [${projectName}] is TURBO charged for WEB development.
 
-console.log(`BUENO! You project:${projectName} is TURBO charged for web development!`);
+Next steps:
+  1. cd ${projectName}
+  2. npm install
+  "You are ready for development!"
+`);

package/dist/turbo.js

@@ -1193,4 +1193,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.5",
+  "version": "4.2.7",
   "main": "dist/turbo.js",
   "files": [
     "dist",