Upload docs

sigpro/sigpro.js

@@ -1,5 +1,5 @@
 /**
- * SigPro 2.0 - Atomic Unified Reactive Engine
+ * SigPro - Atomic Unified Reactive Engine
  * A lightweight, fine-grained reactivity system with built-in routing and plugin support.
  * @author Gemini & User
  */
@@ -8,32 +8,31 @@
   let activeEffect = null;
 
   /**
-   * @typedef {Object} SigPro
-   * @property {function(string, Object=, any=): HTMLElement} html - Creates a reactive HTML element.
-   * @property {function((HTMLElement|function), (HTMLElement|string)=): void} mount - Mounts a component to the DOM.
-   * @property {function(Array<Object>): HTMLElement} router - Initializes a hash-based router.
-   * @property {function(string): void} router.go - Programmatic navigation to a hash path.
-   * @property {function((function|string|Array<string>)): (Promise<SigPro>|SigPro)} plugin - Extends SigPro or loads external scripts.
-   */
+     * @typedef {Object} SigPro
+     * @property {function(any|function, string=): Function} $ - Creates a Signal or Computed. Optional key for localStorage.
+     * @property {function(string, Object=, any=): HTMLElement} html - Creates a reactive HTML element.
+     * @property {function((HTMLElement|function), (HTMLElement|string)=): void} mount - Mounts a component to the DOM.
+     * @property {function(Array<Object>): HTMLElement} router - Initializes a hash-based router.
+     * @property {function(string): void} router.go - Programmatic navigation to a hash path.
+     * @property {function((function|string|Array<string>)): (Promise<SigPro>|SigPro)} plugin - Extends SigPro or loads external scripts.
+     */
 
   /**
-   * Creates a Signal (state) or a Computed/Effect (reaction).
-   * @param {any|function} initial - Initial value for a signal, or a function for computed logic.
-   * @returns {Function} A reactive accessor/mutator function.
-   * @example
-   * const $count = $(0); // Signal: $count(5) to update, $count() to read.
-   * const $double = $(() => $count() * 2); // Computed: Auto-updates when $count changes.
-   */
-  const $ = (initial) => {
+     * Creates a Signal (state) or a Computed/Effect (reaction).
+     * Supports optional persistence in localStorage.
+     * * @param {any|function} initial - Initial value or a function for computed logic.
+     * @param {string} [key] - Optional localStorage key for automatic state persistence.
+     * @returns {Function} A reactive accessor/mutator function.
+     */
+  const $ = (initial, key) => {
     const subs = new Set();
-    
-    // Logic for Computed Signals (Functions)
+
     if (typeof initial === 'function') {
       let cached;
       const runner = () => {
         const prev = activeEffect;
         activeEffect = runner;
-        try { 
+        try {
           const next = initial();
           if (!Object.is(cached, next)) {
             cached = next;
@@ -48,12 +47,19 @@
       };
     }
 
-    // Logic for Standard Signals (State)
+    if (key) {
+      const saved = localStorage.getItem(key);
+      if (saved !== null) {
+        try { initial = JSON.parse(saved); } catch (e) { }
+      }
+    }
+
     return (...args) => {
       if (args.length) {
         const next = typeof args[0] === 'function' ? args[0](initial) : args[0];
         if (!Object.is(initial, next)) {
           initial = next;
+          if (key) localStorage.setItem(key, JSON.stringify(initial));
           subs.forEach(s => s());
         }
       }
@@ -116,6 +122,9 @@
     return el;
   };
 
+  const tags = ['div', 'span', 'p', 'button', 'h1', 'h2', 'h3', 'ul', 'ol', 'li', 'a', 'label', 'section', 'nav', 'main', 'header', 'footer', 'input', 'form', 'img', 'select', 'option', 'table', 'thead', 'tbody', 'tr', 'th', 'td', 'canvas', 'video', 'audio'];
+  tags.forEach(t => window[t] = (p, c) => $.html(t, p, c));
+
   /**
    * Application mounter.
    * @param {HTMLElement|function} node - Root component or element to mount.
@@ -129,6 +138,62 @@
     }
   };
 
+  /**
+ * Initializes a reactive hash-based router.
+ * Maps URL hash changes to component rendering and supports Vite's dynamic imports.
+ * * @param {Array<{path: string, component: Function|Promise|HTMLElement}>} routes - Array of route objects.
+ * @returns {HTMLElement} A reactive div container that swaps content based on the current hash.
+ */
+  $.router = (routes) => {
+    const sPath = $(window.location.hash.replace(/^#/, "") || "/");
+    window.addEventListener("hashchange", () => sPath(window.location.hash.replace(/^#/, "") || "/"));
+
+    return $.html('div', [
+      () => {
+        const current = sPath();
+        const cP = current.split('/').filter(Boolean);
+
+        const route = routes.find(r => {
+          const rP = r.path.split('/').filter(Boolean);
+          if (rP.length !== cP.length) return false;
+          return rP.every((part, i) => part.startsWith(':') || part === cP[i]);
+        }) || routes.find(r => r.path === "*");
+
+        if (!route) return $.html('h1', "404 - Not Found");
+
+        const rP = route.path.split('/').filter(Boolean);
+        const params = {};
+        rP.forEach((part, i) => {
+          if (part.startsWith(':')) params[part.slice(1)] = cP[i];
+        });
+
+        const result = typeof route.component === 'function' ? route.component(params) : route.component;
+
+        if (result instanceof Promise) {
+          const $lazyNode = $($.html('span', "Loading..."));
+          result.then(m => {
+            const content = m.default || m;
+            const finalView = typeof content === 'function' ? content(params) : content;
+            $lazyNode(finalView);
+          });
+          return () => $lazyNode();
+        }
+
+        return result instanceof Node ? result : $.html('span', String(result));
+      }
+    ]);
+  };
+
+  /**
+   * Programmatically navigates to a specific path using the hash.
+   * * @param {string} path - The destination path (e.g., '/home' or 'settings').
+   * @example
+   * $.router.go('/profile/42');
+   */
+  $.router.go = (path) => {
+    window.location.hash = path.startsWith('/') ? path : `/${path}`;
+  };
+
   /**
    * Polymorphic Plugin System.
    * Registers internal functions or loads external .js files as plugins.
@@ -154,9 +219,5 @@
     }))).then(() => $);
   };
 
-  // Global HTML Tag Proxy Helpers
-  const tags = ['div', 'span', 'p', 'button', 'h1', 'h2', 'h3', 'ul', 'ol', 'li', 'a', 'label', 'section', 'nav', 'main', 'header', 'footer', 'input', 'form', 'img', 'select', 'option', 'table', 'thead', 'tbody', 'tr', 'th', 'td', 'canvas', 'video', 'audio'];
-  tags.forEach(t => window[t] = (p, c) => $.html(t, p, c));
-
   window.$ = $;
 })();