pulse-js-framework 1.0.0 → 1.4.0

package/runtime/native.js

@@ -0,0 +1,368 @@
+/**
+ * Pulse Native Runtime Module
+ * Reactive wrappers for native mobile APIs
+ * Integrates with Pulse reactivity system
+ */
+
+import { pulse, effect, batch } from './pulse.js';
+
+/**
+ * Check if PulseMobile bridge is available
+ */
+export function isNativeAvailable() {
+  return typeof window !== 'undefined' && typeof window.PulseMobile !== 'undefined';
+}
+
+/**
+ * Get the PulseMobile instance
+ */
+export function getNative() {
+  if (!isNativeAvailable()) {
+    throw new Error('PulseMobile is not available. Include pulse-native.js in your app.');
+  }
+  return window.PulseMobile;
+}
+
+/**
+ * Get current platform
+ */
+export function getPlatform() {
+  if (!isNativeAvailable()) return 'web';
+  return getNative().platform;
+}
+
+/**
+ * Check if running in native environment
+ */
+export function isNative() {
+  return isNativeAvailable() && getNative().isNative;
+}
+
+/**
+ * Create reactive native storage
+ * Syncs between native storage and Pulse reactivity
+ */
+export function createNativeStorage(prefix = '') {
+  const cache = new Map();
+
+  return {
+    /**
+     * Get a reactive value from native storage
+     * Returns a Pulse signal that auto-persists
+     */
+    get(key, defaultValue = null) {
+      const fullKey = prefix + key;
+
+      if (cache.has(fullKey)) {
+        return cache.get(fullKey);
+      }
+
+      const p = pulse(defaultValue);
+      cache.set(fullKey, p);
+
+      // Load initial value from storage
+      if (isNativeAvailable()) {
+        getNative().Storage.getItem(fullKey).then(value => {
+          if (value !== null) {
+            try {
+              p.set(JSON.parse(value));
+            } catch {
+              p.set(value);
+            }
+          }
+        });
+      } else if (typeof localStorage !== 'undefined') {
+        const value = localStorage.getItem(fullKey);
+        if (value !== null) {
+          try {
+            p.set(JSON.parse(value));
+          } catch {
+            p.set(value);
+          }
+        }
+      }
+
+      // Auto-persist on changes
+      let initialized = false;
+      effect(() => {
+        const value = p.get();
+        // Skip first effect run (initial load)
+        if (!initialized) {
+          initialized = true;
+          return;
+        }
+        const serialized = JSON.stringify(value);
+        if (isNativeAvailable()) {
+          getNative().Storage.setItem(fullKey, serialized);
+        } else if (typeof localStorage !== 'undefined') {
+          localStorage.setItem(fullKey, serialized);
+        }
+      });
+
+      return p;
+    },
+
+    /**
+     * Remove a value from storage
+     */
+    async remove(key) {
+      const fullKey = prefix + key;
+      cache.delete(fullKey);
+      if (isNativeAvailable()) {
+        await getNative().Storage.removeItem(fullKey);
+      } else if (typeof localStorage !== 'undefined') {
+        localStorage.removeItem(fullKey);
+      }
+    },
+
+    /**
+     * Clear all storage with prefix
+     */
+    async clear() {
+      cache.clear();
+      if (isNativeAvailable()) {
+        const keys = await getNative().Storage.keys();
+        for (const key of keys) {
+          if (key.startsWith(prefix)) {
+            await getNative().Storage.removeItem(key);
+          }
+        }
+      } else if (typeof localStorage !== 'undefined') {
+        const keysToRemove = [];
+        for (let i = 0; i < localStorage.length; i++) {
+          const key = localStorage.key(i);
+          if (key && key.startsWith(prefix)) {
+            keysToRemove.push(key);
+          }
+        }
+        for (const key of keysToRemove) {
+          localStorage.removeItem(key);
+        }
+      }
+    }
+  };
+}
+
+/**
+ * Create reactive device info
+ */
+export function createDeviceInfo() {
+  const info = pulse(null);
+  const network = pulse({ connected: true, type: 'unknown' });
+
+  // Load device info
+  if (isNativeAvailable()) {
+    getNative().Device.getInfo().then(data => {
+      info.set(data);
+    });
+
+    getNative().Device.getNetworkStatus().then(status => {
+      network.set(status);
+    });
+
+    // Listen for network changes
+    getNative().Device.onNetworkChange(status => {
+      network.set(status);
+    });
+  } else {
+    // Web fallback
+    info.set({
+      platform: 'web',
+      userAgent: typeof navigator !== 'undefined' ? navigator.userAgent : '',
+      language: typeof navigator !== 'undefined' ? navigator.language : 'en'
+    });
+
+    if (typeof navigator !== 'undefined') {
+      network.set({
+        connected: navigator.onLine,
+        type: 'unknown'
+      });
+
+      window.addEventListener('online', () => {
+        network.set({ connected: true, type: 'unknown' });
+      });
+
+      window.addEventListener('offline', () => {
+        network.set({ connected: false, type: 'none' });
+      });
+    }
+  }
+
+  return {
+    /** Device info as reactive Pulse */
+    info,
+
+    /** Network status as reactive Pulse */
+    network,
+
+    /** Current platform */
+    get platform() {
+      return getPlatform();
+    },
+
+    /** Is running in native app */
+    get isNative() {
+      return isNative();
+    },
+
+    /** Is currently online */
+    get isOnline() {
+      return network.get().connected;
+    }
+  };
+}
+
+/**
+ * Native UI helpers
+ */
+export const NativeUI = {
+  /**
+   * Show a toast message
+   */
+  toast(message, isLong = false) {
+    if (isNativeAvailable()) {
+      return getNative().UI.showToast(message, isLong);
+    }
+    // Fallback: simple console log
+    console.log('[Toast]', message);
+    return Promise.resolve();
+  },
+
+  /**
+   * Trigger haptic feedback / vibration
+   */
+  vibrate(duration = 100) {
+    if (isNativeAvailable()) {
+      return getNative().UI.vibrate(duration);
+    }
+    // Web fallback
+    if (typeof navigator !== 'undefined' && navigator.vibrate) {
+      navigator.vibrate(duration);
+    }
+    return Promise.resolve();
+  }
+};
+
+/**
+ * Native clipboard helpers
+ */
+export const NativeClipboard = {
+  /**
+   * Copy text to clipboard
+   */
+  async copy(text) {
+    if (isNativeAvailable()) {
+      return getNative().Clipboard.copy(text);
+    }
+    if (typeof navigator !== 'undefined' && navigator.clipboard) {
+      return navigator.clipboard.writeText(text);
+    }
+    return Promise.reject(new Error('Clipboard not available'));
+  },
+
+  /**
+   * Read text from clipboard
+   */
+  async read() {
+    if (isNativeAvailable()) {
+      return getNative().Clipboard.read();
+    }
+    if (typeof navigator !== 'undefined' && navigator.clipboard) {
+      return navigator.clipboard.readText();
+    }
+    return '';
+  }
+};
+
+/**
+ * App lifecycle - pause handler
+ */
+export function onAppPause(callback) {
+  if (typeof document !== 'undefined') {
+    document.addEventListener('visibilitychange', () => {
+      if (document.hidden) callback();
+    });
+  }
+  if (isNativeAvailable()) {
+    getNative().App.onPause(callback);
+  }
+}
+
+/**
+ * App lifecycle - resume handler
+ */
+export function onAppResume(callback) {
+  if (typeof document !== 'undefined') {
+    document.addEventListener('visibilitychange', () => {
+      if (!document.hidden) callback();
+    });
+  }
+  if (isNativeAvailable()) {
+    getNative().App.onResume(callback);
+  }
+}
+
+/**
+ * Handle Android back button
+ */
+export function onBackButton(callback) {
+  if (isNativeAvailable()) {
+    getNative().App.onBackButton(callback);
+  }
+}
+
+/**
+ * Wait for native bridge to be ready
+ */
+export function onNativeReady(callback) {
+  if (typeof window === 'undefined') return;
+
+  window.addEventListener('pulse:ready', (e) => {
+    callback(e.detail);
+  });
+
+  // If already ready (web or native initialized)
+  if (typeof window.PulseMobile !== 'undefined') {
+    const platform = window.PulseMobile.platform;
+    setTimeout(() => callback({ platform }), 0);
+  }
+}
+
+/**
+ * Exit the app (Android only)
+ */
+export function exitApp() {
+  if (isNativeAvailable() && getNative().isAndroid) {
+    return getNative().App.exit();
+  }
+  console.warn('exitApp is only available on Android');
+  return Promise.resolve();
+}
+
+/**
+ * Minimize the app
+ */
+export function minimizeApp() {
+  if (isNativeAvailable()) {
+    return getNative().App.minimize();
+  }
+  console.warn('minimizeApp is only available in native apps');
+  return Promise.resolve();
+}
+
+export default {
+  isNativeAvailable,
+  getNative,
+  getPlatform,
+  isNative,
+  createNativeStorage,
+  createDeviceInfo,
+  NativeUI,
+  NativeClipboard,
+  onAppPause,
+  onAppResume,
+  onBackButton,
+  onNativeReady,
+  exitApp,
+  minimizeApp
+};

package/runtime/pulse.js

@@ -10,6 +10,17 @@ let currentEffect = null;
 let batchDepth = 0;
 let pendingEffects = new Set();
 let isRunningEffects = false;
+let cleanupQueue = [];
+
+/**
+ * Register a cleanup function for the current effect
+ * Called when the effect re-runs or is disposed
+ */
+export function onCleanup(fn) {
+  if (currentEffect) {
+    currentEffect.cleanups.push(fn);
+  }
+}
 
 /**
  * Pulse - A reactive value container
@@ -104,6 +115,29 @@ export class Pulse {
   _init(value) {
     this.#value = value;
   }
+
+  /**
+   * Set from computed - propagates to subscribers (internal use)
+   */
+  _setFromComputed(newValue) {
+    if (this.#equals(this.#value, newValue)) return;
+    this.#value = newValue;
+    this.#notify();
+  }
+
+  /**
+   * Add a subscriber directly (internal use)
+   */
+  _addSubscriber(subscriber) {
+    this.#subscribers.add(subscriber);
+  }
+
+  /**
+   * Trigger notification to all subscribers (internal use)
+   */
+  _triggerNotify() {
+    this.#notify();
+  }
 }
 
 /**
@@ -160,25 +194,95 @@ export function pulse(value, options) {
  * Create a computed pulse that automatically updates
  * when its dependencies change
  */
-export function computed(fn) {
+export function computed(fn, options = {}) {
+  const { lazy = false } = options;
   const p = new Pulse(undefined);
   let initialized = false;
+  let dirty = true;
+  let cachedValue;
+  let cleanup = null;
+
+  if (lazy) {
+    // Lazy computed - only evaluates when read
+    const originalGet = p.get.bind(p);
+
+    // Track which pulses this depends on
+    let trackedDeps = new Set();
+
+    p.get = function() {
+      if (dirty) {
+        // Run computation
+        const prevEffect = currentEffect;
+        const tempEffect = {
+          run: () => {},
+          dependencies: new Set(),
+          cleanups: []
+        };
+        currentEffect = tempEffect;
+
+        try {
+          cachedValue = fn();
+          dirty = false;
+
+          // Cleanup old subscriptions
+          for (const dep of trackedDeps) {
+            dep._unsubscribe(markDirty);
+          }
+
+          // Set up new subscriptions
+          trackedDeps = tempEffect.dependencies;
+          for (const dep of trackedDeps) {
+            dep.subscribe(() => {
+              dirty = true;
+              // Notify our own subscribers
+              p._triggerNotify();
+            });
+          }
+
+          p._init(cachedValue);
+        } finally {
+          currentEffect = prevEffect;
+        }
+      }
 
-  effect(() => {
-    const newValue = fn();
-    if (initialized) {
-      p._init(newValue); // Use _init to avoid triggering notifications during compute
-    } else {
-      p._init(newValue);
-      initialized = true;
-    }
-  });
+      // Track dependency on this computed
+      if (currentEffect) {
+        p._addSubscriber(currentEffect);
+        currentEffect.dependencies.add(p);
+      }
+
+      return cachedValue;
+    };
+
+    const markDirty = { run: () => { dirty = true; }, dependencies: new Set(), cleanups: [] };
+  } else {
+    // Eager computed - updates immediately when dependencies change
+    cleanup = effect(() => {
+      const newValue = fn();
+      if (!initialized) {
+        p._init(newValue);
+        initialized = true;
+      } else {
+        // Use set() to properly propagate to downstream subscribers
+        p._setFromComputed(newValue);
+      }
+    });
+  }
 
   // Override set to make it read-only
   p.set = () => {
     throw new Error('Cannot set a computed pulse directly');
   };
 
+  p.update = () => {
+    throw new Error('Cannot update a computed pulse directly');
+  };
+
+  // Add dispose method
+  p.dispose = () => {
+    if (cleanup) cleanup();
+  };
+
   return p;
 }
 
@@ -188,6 +292,16 @@ export function computed(fn) {
 export function effect(fn) {
   const effectFn = {
     run: () => {
+      // Run cleanup functions from previous run
+      for (const cleanup of effectFn.cleanups) {
+        try {
+          cleanup();
+        } catch (e) {
+          console.error('Cleanup error:', e);
+        }
+      }
+      effectFn.cleanups = [];
+
       // Clean up old dependencies
       for (const dep of effectFn.dependencies) {
         dep._unsubscribe(effectFn);
@@ -206,7 +320,8 @@ export function effect(fn) {
         currentEffect = prevEffect;
       }
     },
-    dependencies: new Set()
+    dependencies: new Set(),
+    cleanups: []
   };
 
   // Run immediately to collect dependencies
@@ -214,6 +329,16 @@ export function effect(fn) {
 
   // Return cleanup function
   return () => {
+    // Run any pending cleanups
+    for (const cleanup of effectFn.cleanups) {
+      try {
+        cleanup();
+      } catch (e) {
+        console.error('Cleanup error:', e);
+      }
+    }
+    effectFn.cleanups = [];
+
     for (const dep of effectFn.dependencies) {
       dep._unsubscribe(effectFn);
     }
@@ -246,7 +371,62 @@ export function createState(obj) {
   const pulses = {};
 
   for (const [key, value] of Object.entries(obj)) {
-    if (typeof value === 'object' && value !== null && !Array.isArray(value)) {
+    if (Array.isArray(value)) {
+      // Arrays get special handling with reactive methods
+      pulses[key] = new Pulse(value);
+
+      Object.defineProperty(state, key, {
+        get() {
+          return pulses[key].get();
+        },
+        set(newValue) {
+          pulses[key].set(newValue);
+        },
+        enumerable: true
+      });
+
+      // Add array helper methods
+      state[`${key}$push`] = (...items) => {
+        pulses[key].update(arr => [...arr, ...items]);
+      };
+      state[`${key}$pop`] = () => {
+        let popped;
+        pulses[key].update(arr => {
+          popped = arr[arr.length - 1];
+          return arr.slice(0, -1);
+        });
+        return popped;
+      };
+      state[`${key}$shift`] = () => {
+        let shifted;
+        pulses[key].update(arr => {
+          shifted = arr[0];
+          return arr.slice(1);
+        });
+        return shifted;
+      };
+      state[`${key}$unshift`] = (...items) => {
+        pulses[key].update(arr => [...items, ...arr]);
+      };
+      state[`${key}$splice`] = (start, deleteCount, ...items) => {
+        let removed;
+        pulses[key].update(arr => {
+          const copy = [...arr];
+          removed = copy.splice(start, deleteCount, ...items);
+          return copy;
+        });
+        return removed;
+      };
+      state[`${key}$filter`] = (fn) => {
+        pulses[key].update(arr => arr.filter(fn));
+      };
+      state[`${key}$map`] = (fn) => {
+        pulses[key].update(arr => arr.map(fn));
+      };
+      state[`${key}$sort`] = (fn) => {
+        pulses[key].update(arr => [...arr].sort(fn));
+      };
+    } else if (typeof value === 'object' && value !== null) {
       // Recursively create state for nested objects
       state[key] = createState(value);
     } else {
@@ -273,6 +453,57 @@ export function createState(obj) {
   return state;
 }
 
+/**
+ * Memoize a function based on reactive dependencies
+ * Only recomputes when dependencies change
+ */
+export function memo(fn, options = {}) {
+  const { equals = Object.is } = options;
+  let cachedResult;
+  let cachedDeps = null;
+  let initialized = false;
+
+  return (...args) => {
+    // Check if args have changed
+    const depsChanged = !cachedDeps ||
+      args.length !== cachedDeps.length ||
+      args.some((arg, i) => !equals(arg, cachedDeps[i]));
+
+    if (!initialized || depsChanged) {
+      cachedResult = fn(...args);
+      cachedDeps = args;
+      initialized = true;
+    }
+
+    return cachedResult;
+  };
+}
+
+/**
+ * Create a memoized computed value
+ * Combines memo with computed for expensive derivations
+ */
+export function memoComputed(fn, options = {}) {
+  const { deps = [], equals = Object.is } = options;
+  let lastDeps = null;
+  let lastResult;
+
+  return computed(() => {
+    const currentDeps = deps.map(d => typeof d === 'function' ? d() : d.get());
+
+    const depsChanged = !lastDeps ||
+      currentDeps.length !== lastDeps.length ||
+      currentDeps.some((d, i) => !equals(d, lastDeps[i]));
+
+    if (depsChanged) {
+      lastResult = fn();
+      lastDeps = currentDeps;
+    }
+
+    return lastResult;
+  });
+}
+
 /**
  * Watch specific pulses and run a callback when they change
  */
@@ -335,5 +566,8 @@ export default {
   createState,
   watch,
   fromPromise,
-  untrack
+  untrack,
+  onCleanup,
+  memo,
+  memoComputed
 };