baremetal.js 1.0.0

package/docs/api.md

@@ -0,0 +1,109 @@
+# BareMetal.js - Exposed Methods
+
+BareMetal exports its core engine as a global configuration object. Here are the documented methods available for developers.
+
+## 1. Core Engine Initialization
+
+### `BareMetal.init(config)`
+Initializes the engine, sets up the Router, and binds global configurations.
+
+**Parameters:**
+- `config.debug` *(boolean)*: Enable verbose console logs (default: `false`).
+- `config.keepAliveSameModules` *(boolean)*: If true, modules shared between routes are not destroyed during navigation (default: `true`).
+- `config.autoWrap` *(boolean)*: If true, modules that do not export a `mount` function are automatically wrapped in a dynamic Blob URL to prevent syntax errors (default: `true`).
+- `config.transition` *(object)*: Configuration for the native page transition API.
+  - `config.transition.enabled` *(boolean)*: Enables the protected transition module.
+  - `config.transition.module` *(string)*: Optional path to a custom transition module (defaults to `/src/transition.js`).
+  - `config.transition.simulatedDelay` *(number)*: Optional artificial delay in milliseconds (useful for testing animations locally).
+
+---
+
+## 2. Router Navigation
+
+### `BareMetal.router.reload()`
+Executes a hard reload of the current SPA page by calling `window.location.reload()`. This is useful when you want to force the browser to wipe the entire SPA state and fetch fresh assets.
+
+### `BareMetal.router.handleRoute()`
+Forces the router to evaluate the current `window.location.pathname`, fetch the corresponding HTML, and swap the DOM. Usually called automatically via `popstate` or link clicks.
+
+---
+
+## 3. Reactive State & Event Bus
+
+The state manager is accessible via `BareMetal.state` (or its alias `BareMetal.events`).
+
+### `state.init(key, defaultValue)`
+Initializes a piece of state. If the key already exists, it is ignored.
+
+### `state.update(key, value)`
+Updates a state variable and synchronously triggers all callbacks subscribed to this specific key.
+
+### `state.get(key)`
+Returns the current synchronous value of the state key.
+
+### `state.subscribe(key, callback)`
+Subscribes a function to changes on a specific state key.
+- **Returns:** A function that, when called, unsubscribes the callback.
+- *Note:* The callback is invoked immediately upon subscription with the current value.
+
+### `state.publish(event, payload)`
+Fires a standard, one-off Pub/Sub event across the application.
+
+### `state.on(event, callback)`
+Listens for a Pub/Sub event.
+- **Returns:** An unsubscribe function.
+
+---
+
+## 5. Writing Custom Page Transitions
+
+You can replace the default progress bar and fade overlay by pointing `config.transition.module` to your own JavaScript file. A custom transition is just a standard BareMetal module that listens to routing events.
+
+**Rules for Custom Transitions:**
+1. **The Protected Node:** You must inject your transition UI into an element with `id="baremetal-transition-root"`. The Router explicitly protects this specific ID from being destroyed when it swaps the `document.body.innerHTML`.
+2. **Listen to Events:** Use `state.on()` to listen to `ROUTE_START`, `ROUTE_PROGRESS`, `ROUTE_END`, and `ROUTE_ERROR`.
+
+**Example:**
+```javascript
+// custom_transition.js
+export function mount({ state }) {
+  // 1. Create or get the protected root node
+  let root = document.getElementById('baremetal-transition-root');
+  if (!root) {
+    root = document.createElement('div');
+    root.id = 'baremetal-transition-root';
+    document.body.appendChild(root);
+  }
+
+  // 2. Build your custom UI (e.g., a spinner)
+  const spinner = document.createElement('div');
+  spinner.innerText = "Loading...";
+  spinner.style.display = 'none';
+  root.appendChild(spinner);
+
+  const unsubs = [];
+
+  // 3. Listen to Router events
+  unsubs.push(state.on('ROUTE_START', () => {
+    spinner.style.display = 'block';
+  }));
+
+  unsubs.push(state.on('ROUTE_PROGRESS', (payload) => {
+    // payload.progress goes from 0 to 100
+    spinner.innerText = `Loading... ${Math.round(payload.progress)}%`;
+  }));
+
+  unsubs.push(state.on('ROUTE_END', () => {
+    spinner.style.display = 'none';
+  }));
+
+  return {
+    destroy: () => {
+      unsubs.forEach(u => u());
+      if (root.parentNode) root.parentNode.removeChild(root);
+    }
+  };
+}
+```
+
+

package/package.json

@@ -0,0 +1,29 @@
+{
+  "name": "baremetal.js",
+  "version": "1.0.0",
+  "description": "A lightweight, dependency-free Vanilla JavaScript SPA engine prioritizing extreme performance, native browser features, and explicit lifecycle management.",
+  "main": "src/index.js",
+  "type": "module",
+  "scripts": {
+    "test": "echo \"No tests written yet.\" && exit 0"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/dkydivyansh/BareMetal.js.git"
+  },
+  "keywords": [
+    "spa",
+    "vanilla",
+    "framework",
+    "router",
+    "state-management",
+    "baremetal",
+    "performance"
+  ],
+  "author": "Divyansh",
+  "license": "GPL-3.0",
+  "bugs": {
+    "url": "https://github.com/dkydivyansh/BareMetal.js/issues"
+  },
+  "homepage": "https://BareMetal.dkydivyansh.com"
+}

package/src/index.js

@@ -0,0 +1,25 @@
+import { stateManager } from './state.js';
+import { Loader, loader } from './loader.js';
+import { Router } from './router.js';
+
+const BareMetal = {
+  state: stateManager,
+  events: stateManager, // Aliased for backward compatibility with Pub/Sub mental model
+  loader: loader,
+  router: Router,
+
+  init(config = {}) {
+    if (config.debug !== undefined) Loader.setConfig({ debug: config.debug });
+    if (config.keepAliveSameModules !== undefined) Loader.setConfig({ keepAliveSameModules: config.keepAliveSameModules });
+    if (config.transition !== undefined) Loader.setConfig({ transition: config.transition });
+    if (config.autoWrap !== undefined) Loader.setConfig({ autoWrap: config.autoWrap });
+    if (config.hoverPrefetch !== undefined) Loader.setConfig({ hoverPrefetch: config.hoverPrefetch });
+    if (config.showErrorNotification !== undefined) Loader.setConfig({ showErrorNotification: config.showErrorNotification });
+
+    // Initialize Router
+    Router.init();
+    Loader.log("Initialized BareMetal Engine with config:", config);
+  }
+};
+
+export { BareMetal, loader };

package/src/loader.js

@@ -0,0 +1,149 @@
+import { stateManager } from './state.js';
+
+export const Loader = {
+  activeModules: {}, // { key: { path: "./dash.js", module: exportedModule } }
+  config: { keepAliveSameModules: true, debug: false, autoWrap: true, hoverPrefetch: false, showErrorNotification: false, transition: { enabled: false, simulatedDelay: 0, module: null } },
+  
+  setConfig(globalConfig) {
+    this.config = { ...this.config, ...globalConfig };
+  },
+
+  log(...args) {
+    if (this.config.debug) console.log('[BareMetal Loader]', ...args);
+  },
+
+  /**
+   * Prepares the transition by destroying obsolete modules and identifying new ones.
+   */
+  async prepare(newConfig) {
+    // Auto-inject transition module if enabled
+    if (this.config.transition && this.config.transition.enabled) {
+      const transitionPath = this.config.transition.module || '/src/transition.js';
+      newConfig['__baremetal_transition'] = transitionPath;
+    }
+
+    const modulesToKeep = {};
+    const modulesToDestroy = [];
+    const modulesToLoad = {};
+
+    for (const [key, mod] of Object.entries(this.activeModules)) {
+      const isImmortal = key === '__baremetal_transition';
+      if ((this.config.keepAliveSameModules || isImmortal) && newConfig[key] === mod.path) {
+        // Keep alive
+        modulesToKeep[key] = mod;
+        this.log(`Keep-Alive: ${key} (${mod.path})`);
+      } else {
+        // Mark for destruction
+        modulesToDestroy.push(mod);
+      }
+    }
+
+    // Destroy obsolete modules
+    for (const mod of modulesToDestroy) {
+      this.log(`Destroying module: ${mod.path}`);
+      if (mod.module && typeof mod.module.destroy === 'function') {
+        try {
+          mod.module.destroy();
+        } catch (e) {
+          console.error(`Error destroying module ${mod.path}`, e);
+        }
+      }
+    }
+
+    // Determine what's new
+    for (const [key, path] of Object.entries(newConfig)) {
+      if (!modulesToKeep[key]) {
+        modulesToLoad[key] = path;
+      }
+    }
+
+    // Temporarily update active modules to only the kept ones
+    this.activeModules = modulesToKeep;
+
+    return modulesToLoad;
+  },
+
+  /**
+   * Loads the prepared modules. Called by Router after DOM swap.
+   */
+  async loadPrepared(modulesToLoad) {
+    const total = Object.keys(modulesToLoad).length;
+    let loaded = 0;
+
+    const loadPromises = Object.entries(modulesToLoad).map(async ([key, path]) => {
+      this.log(`Importing module: ${path}`);
+      try {
+        const resolvedPath = new URL(path, document.baseURI).href;
+        const noCachePath = `${resolvedPath}?t=${Date.now()}`;
+        
+        let module;
+
+        if (this.config.autoWrap) {
+          // Fetch source to check if it needs auto-wrapping
+          const response = await fetch(noCachePath);
+          if (!response.ok) throw new Error(`Failed to fetch ${noCachePath}`);
+          const sourceText = await response.text();
+
+          const hasMount = /export\s+(function|const|let|var)\s+mount\b/.test(sourceText) || /export\s+\{.*?\bmount\b.*?\}/.test(sourceText);
+
+          if (!hasMount) {
+            console.warn(`[BareMetal] WARNING: Module ${path} does not explicitly export a mount() function. Auto-wrapping it...`);
+            
+            const wrappedSource = `
+              export async function mount(context) {
+                const { state } = context;
+                ${sourceText}
+              }
+            `;
+            
+            const blob = new Blob([wrappedSource], { type: 'application/javascript' });
+            const blobUrl = URL.createObjectURL(blob);
+            module = await import(blobUrl);
+            URL.revokeObjectURL(blobUrl);
+          } else {
+            module = await import(noCachePath);
+          }
+        } else {
+          // Auto-wrapping disabled, load natively
+          module = await import(noCachePath);
+        }
+        
+        if (typeof module.mount === 'function') {
+          this.log(`Mounting module: ${path}`);
+          const instance = await module.mount({ state: stateManager });
+          
+          this.activeModules[key] = {
+            path: path,
+            module: instance ? { destroy: instance.destroy } : module
+          };
+        } else {
+          console.error(`[BareMetal] Module ${path} failed to provide a mount function even after wrapping.`);
+        }
+      } catch (err) {
+        console.error(`Failed to load module: ${path}`, err);
+      } finally {
+        loaded++;
+        if (total > 0) {
+          const progress = 50 + (loaded / total) * 50;
+          stateManager.publish('ROUTE_PROGRESS', { url: window.location.pathname, progress });
+        }
+      }
+    });
+
+    await Promise.all(loadPromises);
+    stateManager.publish('ROUTE_END', { url: window.location.pathname });
+  },
+
+  /**
+   * Legacy standalone load (used on first page load directly)
+   */
+  async load(config) {
+    const modulesToLoad = await this.prepare(config);
+    await this.loadPrepared(modulesToLoad);
+  }
+};
+
+// The user-facing API
+export function loader(config) {
+  return Loader.load(config);
+}

package/src/router.js

@@ -0,0 +1,240 @@
+import { Loader } from './loader.js';
+import { stateManager } from './state.js';
+
+export const Router = {
+  htmlCache: {},
+  scrollMemory: {},
+  historyStack: [],
+
+  init() {
+    if ('scrollRestoration' in history) {
+      history.scrollRestoration = 'manual';
+    }
+    window.addEventListener('popstate', this.handleRoute.bind(this));
+    
+    // Intercept all link clicks
+    document.body.addEventListener('click', e => {
+      // Find closest anchor tag
+      const anchor = e.target.closest('a');
+      if (!anchor) return;
+
+      // Ignore external domains, target="_blank", noreferrer, or downloads
+      if (
+        anchor.origin !== window.location.origin || 
+        anchor.target === '_blank' ||
+        (anchor.rel && anchor.rel.includes('noreferrer')) ||
+        anchor.hasAttribute('download')
+      ) {
+        return; // Let browser handle it naturally
+      }
+
+      // Intercept same-origin internal links
+      e.preventDefault();
+      
+      // Save current state before navigating away
+      this.historyStack.push(window.location.pathname);
+      this.scrollMemory[window.location.pathname] = window.scrollY;
+
+      history.pushState(null, '', anchor.href);
+      this.handleRoute();
+    });
+
+    // Hover Pre-fetching
+    document.body.addEventListener('mouseover', e => {
+      if (!Loader.config.hoverPrefetch) return;
+      const anchor = e.target.closest('a');
+      if (!anchor) return;
+      if (
+        anchor.origin === window.location.origin && 
+        anchor.target !== '_blank' && 
+        !anchor.hasAttribute('download') &&
+        !this.htmlCache[anchor.href]
+      ) {
+        this.htmlCache[anchor.href] = 'fetching'; // Prevent duplicate fetches
+        fetch(anchor.href)
+          .then(res => {
+             if (res.ok) return res.text();
+             throw new Error('Failed to prefetch');
+          })
+          .then(html => this.htmlCache[anchor.href] = html)
+          .catch(() => delete this.htmlCache[anchor.href]);
+      }
+    });
+  },
+
+  back() {
+    // Custom programmatic back button
+    if (this.historyStack.length > 0) {
+      const prevUrl = this.historyStack.pop();
+      history.pushState(null, '', prevUrl);
+      this.handleRoute();
+    } else {
+      history.back(); // Fallback to browser's native back
+    }
+  },
+
+  reload() {
+    window.location.reload();
+  },
+
+  async handleRoute() {
+    const url = window.location.pathname;
+    try {
+      Loader.log(`Navigating to ${url}`);
+      stateManager.publish('ROUTE_START', { url });
+
+      if (Loader.config.transition && Loader.config.transition.simulatedDelay) {
+        stateManager.publish('ROUTE_PROGRESS', { url, progress: 10 });
+        await new Promise(r => setTimeout(r, Loader.config.transition.simulatedDelay / 2));
+        stateManager.publish('ROUTE_PROGRESS', { url, progress: 30 });
+        await new Promise(r => setTimeout(r, Loader.config.transition.simulatedDelay / 2));
+      }
+
+      let htmlText;
+      const fullUrl = new URL(url, document.baseURI).href;
+      
+      if (Loader.config.hoverPrefetch && this.htmlCache[fullUrl] && this.htmlCache[fullUrl] !== 'fetching') {
+        htmlText = this.htmlCache[fullUrl];
+        Loader.log(`Used pre-fetched cache for ${url}`);
+      } else {
+        const response = await fetch(url);
+        if (!response.ok) throw new Error(`HTTP error! status: ${response.status}`);
+        htmlText = await response.text();
+      }
+      
+      stateManager.publish('ROUTE_PROGRESS', { url, progress: 50 });
+
+      const parser = new DOMParser();
+      const doc = parser.parseFromString(htmlText, 'text/html');
+      
+      // 1. Extract Config
+      let config = null;
+      const scriptTags = doc.querySelectorAll('script');
+      for (const script of scriptTags) {
+        if (script.textContent.includes('loader(')) {
+          // Extract the JSON-like object from loader({...})
+          const match = script.textContent.match(/loader\s*\(\s*(\{[\s\S]*?\})\s*\)/);
+          if (match && match[1]) {
+            try {
+              // Using Function to safely parse object string that might not be strict JSON
+              config = new Function('return ' + match[1])();
+            } catch (e) {
+              console.error("Failed to parse loader config in new page", e);
+            }
+          }
+        }
+      }
+
+      // If no BareMetal loader config is found, fallback to standard navigation
+      if (!config) {
+        Loader.log(`No BareMetal config found on ${url}. Falling back to native navigation.`);
+        window.location.assign(url);
+        return;
+      }
+
+      // 2. Prepare transition: identify kept vs destroyed modules
+      const modulesToLoad = await Loader.prepare(config);
+
+      // 3. Swap DOM and Head
+      document.title = doc.title;
+      
+      // Swap Head Styles (prevent CSS leak)
+      const oldStyles = document.head.querySelectorAll('link[data-baremetal="style"], style[data-baremetal="style"]');
+      oldStyles.forEach(s => s.remove());
+      const newStyles = doc.head.querySelectorAll('link[data-baremetal="style"], style[data-baremetal="style"]');
+      newStyles.forEach(s => document.head.appendChild(s.cloneNode(true)));
+
+      // User Protected Elements (data-baremetal-preserve)
+      const preservedNodes = [];
+      const persistentElements = document.querySelectorAll('[data-baremetal-preserve]');
+      
+      persistentElements.forEach(el => {
+        if (!el.id) return;
+        if (doc.getElementById(el.id)) {
+           // Synchronously detach the live node
+           const placeholder = document.createElement('div');
+           el.parentNode.replaceChild(placeholder, el);
+           preservedNodes.push(el);
+        }
+      });
+
+      // Engine Protected Elements (Immortal)
+      const transitionRoot = document.getElementById('baremetal-transition-root');
+      if (transitionRoot) {
+        transitionRoot.parentNode.removeChild(transitionRoot);
+      }
+
+      // The actual synchronous DOM swap and restoration
+      const executeDOMSwap = () => {
+        document.body.innerHTML = doc.body.innerHTML;
+
+        // Restore User Protected Elements into their exact new positions
+        preservedNodes.forEach(el => {
+          const newEl = document.getElementById(el.id);
+          if (newEl) {
+             // Sync attributes from the new HTML node so classes/styles update
+             Array.from(el.attributes).forEach(attr => {
+               if (attr.name !== 'id' && attr.name !== 'data-baremetal-preserve') el.removeAttribute(attr.name);
+             });
+             Array.from(newEl.attributes).forEach(attr => {
+               if (attr.name !== 'id') el.setAttribute(attr.name, attr.value);
+             });
+             
+             newEl.parentNode.replaceChild(el, newEl);
+          }
+        });
+
+        if (transitionRoot) {
+          document.body.appendChild(transitionRoot);
+        }
+
+        // Notify keep-alive modules that the DOM has been swapped so they can re-bind UI elements
+        stateManager.publish('DOM_SWAPPED', null);
+      };
+
+      // Execute DOM swap and restore scroll synchronously
+      executeDOMSwap();
+      window.scrollTo(0, this.scrollMemory[url] || 0);
+
+      // 4. Mount new modules (this emits ROUTE_END)
+      await Loader.loadPrepared(modulesToLoad);
+
+    } catch (err) {
+      console.error("Routing error:", err);
+      stateManager.publish('ROUTE_ERROR', { url, error: err.message });
+      
+      if (Loader.config.showErrorNotification) {
+        // Revert URL bar since we are aborting
+        if (this.historyStack.length > 0) {
+          const prev = this.historyStack.pop();
+          history.replaceState(null, '', prev);
+        }
+
+        // Show floating notification
+        const notif = document.createElement('div');
+        notif.style.position = 'fixed';
+        notif.style.bottom = '20px';
+        notif.style.left = '20px';
+        notif.style.background = '#e74c3c';
+        notif.style.color = 'white';
+        notif.style.padding = '15px 20px';
+        notif.style.borderRadius = '8px';
+        notif.style.boxShadow = '0 4px 12px rgba(0,0,0,0.15)';
+        notif.style.zIndex = '999999';
+        notif.style.fontFamily = 'sans-serif';
+        notif.style.transition = 'opacity 0.3s ease';
+        notif.innerHTML = `<strong>Navigation Failed:</strong> ${err.message}`;
+        
+        document.body.appendChild(notif);
+        
+        setTimeout(() => {
+          notif.style.opacity = '0';
+          setTimeout(() => notif.remove(), 300);
+        }, 4000);
+      } else {
+        // Formal redirect to let server handle the error
+        window.location.assign(url);
+      }
+    }
+  }
+};

package/src/state.js

@@ -0,0 +1,83 @@
+class StateManager {
+  constructor() {
+    this.state = {};
+    this.listeners = {};
+    this.eventBus = {};
+  }
+
+  // --- Reactive State ---
+
+  /**
+   * Initialize a state property with a default value
+   */
+  init(key, defaultValue) {
+    if (this.state[key] === undefined) {
+      this.state[key] = defaultValue;
+    }
+  }
+
+  /**
+   * Subscribe to changes on a specific state key
+   */
+  subscribe(key, callback) {
+    if (!this.listeners[key]) {
+      this.listeners[key] = [];
+    }
+    this.listeners[key].push(callback);
+    
+    // Call immediately with current value if exists
+    if (this.state[key] !== undefined) {
+      callback(this.state[key]);
+    }
+
+    return () => this.unsubscribe(key, callback);
+  }
+
+  /**
+   * Unsubscribe from a state key
+   */
+  unsubscribe(key, callback) {
+    if (!this.listeners[key]) return;
+    this.listeners[key] = this.listeners[key].filter(cb => cb !== callback);
+  }
+
+  /**
+   * Update a state value and trigger listeners
+   */
+  update(key, value) {
+    this.state[key] = value;
+    if (this.listeners[key]) {
+      this.listeners[key].forEach(callback => callback(value));
+    }
+  }
+
+  /**
+   * Get current state value
+   */
+  get(key) {
+    return this.state[key];
+  }
+
+  // --- Event Bus (Pub/Sub) for one-off actions ---
+
+  on(event, callback) {
+    if (!this.eventBus[event]) {
+      this.eventBus[event] = [];
+    }
+    this.eventBus[event].push(callback);
+    return () => this.off(event, callback);
+  }
+
+  off(event, callback) {
+    if (!this.eventBus[event]) return;
+    this.eventBus[event] = this.eventBus[event].filter(cb => cb !== callback);
+  }
+
+  publish(event, data) {
+    if (this.eventBus[event]) {
+      this.eventBus[event].forEach(callback => callback(data));
+    }
+  }
+}
+
+export const stateManager = new StateManager();