what-core 0.3.0 → 0.4.1

package/dist/helpers.js

@@ -1,17 +1,27 @@
 // What Framework - Helpers & Utilities
 // Commonly needed patterns, zero overhead.
 
-import { signal, effect, computed, batch } from './reactive.js';
+import { signal, effect, computed, batch, __DEV__ } from './reactive.js';
 
-// --- show(condition, vnode) ---
+// --- show(condition, vnode) --- [DEPRECATED: use <Show> component instead]
 // Conditional rendering. More readable than ternary.
+let _showWarned = false;
 export function show(condition, vnode, fallback = null) {
+  if (!_showWarned) {
+    _showWarned = true;
+    console.warn('[what] show() is deprecated. Use the <Show> component or ternary expressions instead.');
+  }
   return condition ? vnode : fallback;
 }
 
-// --- each(list, fn) ---
+// --- each(list, fn) --- [DEPRECATED: use <For> component or .map() instead]
 // Keyed list rendering. Optimized for reconciliation.
+let _eachWarned = false;
 export function each(list, fn, keyFn) {
+  if (!_eachWarned) {
+    _eachWarned = true;
+    console.warn('[what] each() is deprecated. Use the <For> component or Array.map() instead.');
+  }
   if (!list || list.length === 0) return [];
   return list.map((item, index) => {
     const vnode = fn(item, index);
@@ -76,18 +86,31 @@ export function throttle(fn, ms) {
   };
 }
 
+// Component context ref — injected by dom.js to avoid circular imports
+let _getCurrentComponentRef = null;
+export function _setComponentRef(fn) { _getCurrentComponentRef = fn; }
+
 // --- useMediaQuery ---
-// Reactive media query. Returns a signal.
+// Reactive media query. Returns a signal. Cleans up listener on component unmount.
 export function useMediaQuery(query) {
   if (typeof window === 'undefined') return signal(false);
   const mq = window.matchMedia(query);
   const s = signal(mq.matches);
-  mq.addEventListener('change', (e) => s.set(e.matches));
+  const handler = (e) => s.set(e.matches);
+  mq.addEventListener('change', handler);
+
+  // Register cleanup if inside a component context
+  const ctx = _getCurrentComponentRef?.();
+  if (ctx) {
+    ctx._cleanupCallbacks = ctx._cleanupCallbacks || [];
+    ctx._cleanupCallbacks.push(() => mq.removeEventListener('change', handler));
+  }
+
   return s;
 }
 
 // --- useLocalStorage ---
-// Signal synced with localStorage.
+// Signal synced with localStorage. Cleans up listeners on component unmount.
 export function useLocalStorage(key, initial) {
   let stored;
   try {
@@ -100,18 +123,34 @@ export function useLocalStorage(key, initial) {
   const s = signal(stored);
 
   // Sync to localStorage on changes
-  effect(() => {
+  const dispose = effect(() => {
     try {
       localStorage.setItem(key, JSON.stringify(s()));
-    } catch { /* quota exceeded, etc */ }
+    } catch (e) {
+      if (__DEV__) console.warn('[what] localStorage write failed (quota exceeded?):', e);
+    }
   });
 
   // Listen for changes from other tabs
+  let storageHandler = null;
   if (typeof window !== 'undefined') {
-    window.addEventListener('storage', (e) => {
+    storageHandler = (e) => {
       if (e.key === key && e.newValue !== null) {
-        try { s.set(JSON.parse(e.newValue)); } catch {}
+        try { s.set(JSON.parse(e.newValue)); } catch (err) {
+          if (__DEV__) console.warn('[what] localStorage parse failed:', err);
+        }
       }
+    };
+    window.addEventListener('storage', storageHandler);
+  }
+
+  // Register cleanup if inside a component context
+  const ctx = _getCurrentComponentRef?.();
+  if (ctx) {
+    ctx._cleanupCallbacks = ctx._cleanupCallbacks || [];
+    ctx._cleanupCallbacks.push(() => {
+      dispose();
+      if (storageHandler) window.removeEventListener('storage', storageHandler);
     });
   }
 
@@ -131,6 +170,30 @@ export function Portal({ target, children }) {
   return { tag: '__portal', props: { container }, children: Array.isArray(children) ? children : [children], _vnode: true };
 }
 
+// --- useClickOutside ---
+// Detect clicks outside a ref'd element. Essential for dropdowns, modals, popovers.
+export function useClickOutside(ref, handler) {
+  if (typeof document === 'undefined') return;
+
+  const listener = (e) => {
+    const el = ref.current || ref;
+    if (!el || el.contains(e.target)) return;
+    handler(e);
+  };
+
+  document.addEventListener('mousedown', listener);
+  document.addEventListener('touchstart', listener);
+
+  const ctx = _getCurrentComponentRef?.();
+  if (ctx) {
+    ctx._cleanupCallbacks = ctx._cleanupCallbacks || [];
+    ctx._cleanupCallbacks.push(() => {
+      document.removeEventListener('mousedown', listener);
+      document.removeEventListener('touchstart', listener);
+    });
+  }
+}
+
 // --- Transition helper ---
 // Animate elements in/out. Returns props to spread on the element.
 export function transition(name, active) {

package/dist/hooks.js

@@ -1,12 +1,17 @@
 // What Framework - Hooks
 // React-familiar hooks backed by signals. Zero overhead when deps don't change.
 
-import { signal, computed, effect, batch, untrack } from './reactive.js';
-import { getCurrentComponent, getComponentStack as _getComponentStack } from './dom.js';
+import { signal, computed, effect, batch, untrack, __DEV__ } from './reactive.js';
+import { getCurrentComponent } from './dom.js';
 
 function getCtx() {
   const ctx = getCurrentComponent();
-  if (!ctx) throw new Error('Hooks must be called inside a component');
+  if (!ctx) {
+    throw new Error(
+      '[what] Hooks must be called inside a component function. ' +
+      'If you need reactive state outside a component, use signal() directly.'
+    );
+  }
   return ctx;
 }
 
@@ -129,15 +134,26 @@ export function useRef(initial) {
 
 // --- useContext ---
 // Read from the nearest Provider in the component tree, or the default value.
+// Uses _parentCtx chain (persistent tree) instead of componentStack (runtime stack)
+// so context works correctly in re-renders, effects, and event handlers.
 
 export function useContext(context) {
-  // Walk up the component stack to find the nearest provider for this context
-  const stack = _getComponentStack();
-  for (let i = stack.length - 1; i >= 0; i--) {
-    const ctx = stack[i];
+  // Walk up the _parentCtx chain to find the nearest provider
+  let ctx = getCurrentComponent();
+  if (__DEV__ && !ctx) {
+    console.warn(
+      `[what] useContext(${context?.displayName || 'Context'}) called outside of component render. ` +
+      'useContext must be called during component rendering, not inside effects or event handlers. ' +
+      'Store the context value in a variable during render and use that variable in your callback.'
+    );
+  }
+  while (ctx) {
     if (ctx._contextValues && ctx._contextValues.has(context)) {
-      return ctx._contextValues.get(context);
+      const val = ctx._contextValues.get(context);
+      // If the stored value is a signal, read it to subscribe
+      return (val && val._signal) ? val() : val;
     }
+    ctx = ctx._parentCtx;
   }
   return context._defaultValue;
 }
@@ -145,15 +161,24 @@ export function useContext(context) {
 // --- createContext ---
 // Tree-scoped context: Provider sets value for its subtree only.
 // Multiple providers can coexist — each subtree sees its own value.
+// Context values are wrapped in signals so consumers re-render when values change.
 
 export function createContext(defaultValue) {
   const context = {
     _defaultValue: defaultValue,
     Provider: ({ value, children }) => {
-      // Store context value on the current component's context
       const ctx = getCtx();
       if (!ctx._contextValues) ctx._contextValues = new Map();
-      ctx._contextValues.set(context, value);
+      if (!ctx._contextSignals) ctx._contextSignals = new Map();
+
+      // Create or update the context signal
+      if (!ctx._contextSignals.has(context)) {
+        const s = signal(value);
+        ctx._contextSignals.set(context, s);
+        ctx._contextValues.set(context, s);
+      } else {
+        ctx._contextSignals.get(context).set(value);
+      }
       return children;
     },
   };
@@ -209,26 +234,33 @@ export function createResource(fetcher, options = {}) {
   const loading = signal(!options.initialValue);
   const error = signal(null);
 
-  let currentFetch = null;
+  let controller = null;
 
   const refetch = async (source) => {
+    // Abort previous request
+    if (controller) controller.abort();
+    controller = new AbortController();
+    const { signal: abortSignal } = controller;
+
     loading.set(true);
     error.set(null);
 
     try {
-      const fetchPromise = fetcher(source);
-      currentFetch = fetchPromise;
-      const result = await fetchPromise;
-
-      // Only update if this is still the current fetch
-      if (currentFetch === fetchPromise) {
-        data.set(result);
-        loading.set(false);
+      const result = await fetcher(source, { signal: abortSignal });
+
+      // Only update if not aborted
+      if (!abortSignal.aborted) {
+        batch(() => {
+          data.set(result);
+          loading.set(false);
+        });
       }
     } catch (e) {
-      if (currentFetch === fetchPromise) {
-        error.set(e);
-        loading.set(false);
+      if (!abortSignal.aborted) {
+        batch(() => {
+          error.set(e);
+          loading.set(false);
+        });
       }
     }
   };
@@ -237,6 +269,15 @@ export function createResource(fetcher, options = {}) {
     data.set(typeof value === 'function' ? value(data()) : value);
   };
 
+  // Register cleanup with component lifecycle: abort on unmount
+  const ctx = getCurrentComponent?.();
+  if (ctx) {
+    ctx._cleanupCallbacks = ctx._cleanupCallbacks || [];
+    ctx._cleanupCallbacks.push(() => {
+      if (controller) controller.abort();
+    });
+  }
+
   // Initial fetch if no initial value
   if (!options.initialValue) {
     refetch(options.source);

package/dist/index.js

@@ -2,7 +2,10 @@
 // The closest framework to vanilla JS.
 
 // Reactive primitives
-export { signal, computed, effect, batch, untrack } from './reactive.js';
+export { signal, computed, effect, memo as signalMemo, batch, untrack, flushSync, createRoot } from './reactive.js';
+
+// Fine-grained rendering primitives
+export { template, insert, mapArray, spread, delegateEvents, on, classList } from './render.js';
 
 // Virtual DOM
 export { h, Fragment, html } from './h.js';
@@ -31,7 +34,7 @@ export {
 export { memo, lazy, Suspense, ErrorBoundary, Show, For, Switch, Match, Island } from './components.js';
 
 // Store
-export { createStore, storeComputed, atom } from './store.js';
+export { createStore, derived, storeComputed, atom } from './store.js';
 
 // Head management
 export { Head, clearHead } from './head.js';
@@ -46,6 +49,7 @@ export {
   throttle,
   useMediaQuery,
   useLocalStorage,
+  useClickOutside,
   Portal,
   transition,
 } from './helpers.js';

package/dist/reactive.js

@@ -1,9 +1,13 @@
 // What Framework - Reactive Primitives
 // Signals + Effects: fine-grained reactivity without virtual DOM overhead
 
+// Dev-mode flag — build tools can dead-code-eliminate when false
+export const __DEV__ = typeof process !== 'undefined' && process.env?.NODE_ENV !== 'production' || true;
+
 let currentEffect = null;
+let currentRoot = null;
 let batchDepth = 0;
-let pendingEffects = new Set();
+let pendingEffects = [];
 
 // --- Signal ---
 // A reactive value. Reading inside an effect auto-tracks the dependency.
@@ -16,7 +20,7 @@ export function signal(initial) {
   function read() {
     if (currentEffect) {
       subs.add(currentEffect);
-      currentEffect.deps.add(subs); // Track reverse dep for cleanup
+      currentEffect.deps.push(subs); // Track reverse dep for cleanup
     }
     return value;
   }
@@ -48,19 +52,24 @@ export function computed(fn) {
   const inner = _createEffect(() => {
     value = fn();
     dirty = false;
-    notify(subs);
-  }, { lazy: true });
+  }, true);
 
   function read() {
     if (currentEffect) {
       subs.add(currentEffect);
-      currentEffect.deps.add(subs);
+      currentEffect.deps.push(subs);
     }
     if (dirty) _runEffect(inner);
     return value;
   }
 
-  inner._onNotify = () => { dirty = true; };
+  // When a dependency changes, mark dirty AND propagate to our subscribers.
+  // This is how effects that read this computed know to re-run:
+  // signal changes → computed._onNotify → computed's subs get notified.
+  inner._onNotify = () => {
+    dirty = true;
+    notify(subs);
+  };
 
   read._signal = true;
   read.peek = () => {
@@ -75,10 +84,25 @@ export function computed(fn) {
 // Runs a function, auto-tracking signal reads. Re-runs when deps change.
 // Returns a dispose function.
 
-export function effect(fn) {
+export function effect(fn, opts) {
   const e = _createEffect(fn);
-  _runEffect(e);
-  return () => _disposeEffect(e);
+  // First run: skip cleanup (deps is empty), just run and track
+  const prev = currentEffect;
+  currentEffect = e;
+  try {
+    const result = e.fn();
+    if (typeof result === 'function') e._cleanup = result;
+  } finally {
+    currentEffect = prev;
+  }
+  // Mark as stable after first run — subsequent re-runs skip cleanup/re-subscribe
+  if (opts?.stable) e._stable = true;
+  const dispose = () => _disposeEffect(e);
+  // Register with current root for automatic cleanup
+  if (currentRoot) {
+    currentRoot.disposals.push(dispose);
+  }
+  return dispose;
 }
 
 // --- Batch ---
@@ -96,22 +120,47 @@ export function batch(fn) {
 
 // --- Internals ---
 
-function _createEffect(fn, opts = {}) {
+function _createEffect(fn, lazy) {
   return {
     fn,
-    deps: new Set(),     // subscriber sets this effect belongs to
-    lazy: opts.lazy || false,
+    deps: [],            // array of subscriber sets (cheaper than Set for typical 1-3 deps)
+    lazy: lazy || false,
     _onNotify: null,
     disposed: false,
+    _pending: false,
+    _stable: false,      // stable effects skip cleanup/re-subscribe on re-run
   };
 }
 
 function _runEffect(e) {
   if (e.disposed) return;
+
+  // Stable effect fast path: deps don't change, skip cleanup/re-subscribe.
+  // Effect stays subscribed to its signals from the first run.
+  if (e._stable) {
+    if (e._cleanup) {
+      try { e._cleanup(); } catch (err) {
+        if (__DEV__) console.warn('[what] Error in effect cleanup:', err);
+      }
+      e._cleanup = null;
+    }
+    const prev = currentEffect;
+    currentEffect = null; // Don't re-track deps (already subscribed)
+    try {
+      const result = e.fn();
+      if (typeof result === 'function') e._cleanup = result;
+    } finally {
+      currentEffect = prev;
+    }
+    return;
+  }
+
   cleanup(e);
   // Run effect cleanup from previous run
   if (e._cleanup) {
-    try { e._cleanup(); } catch (err) { /* cleanup error */ }
+    try { e._cleanup(); } catch (err) {
+      if (__DEV__) console.warn('[what] Error in effect cleanup:', err);
+    }
     e._cleanup = null;
   }
   const prev = currentEffect;
@@ -132,40 +181,131 @@ function _disposeEffect(e) {
   cleanup(e);
   // Run cleanup on dispose
   if (e._cleanup) {
-    try { e._cleanup(); } catch (err) { /* cleanup error */ }
+    try { e._cleanup(); } catch (err) {
+      if (__DEV__) console.warn('[what] Error in effect cleanup on dispose:', err);
+    }
     e._cleanup = null;
   }
 }
 
 function cleanup(e) {
-  for (const dep of e.deps) dep.delete(e);
-  e.deps.clear();
+  const deps = e.deps;
+  for (let i = 0; i < deps.length; i++) deps[i].delete(e);
+  deps.length = 0;
 }
 
 function notify(subs) {
-  // Snapshot to avoid infinite loop when effects re-subscribe during run
-  const snapshot = [...subs];
-  for (const e of snapshot) {
+  for (const e of subs) {
     if (e.disposed) continue;
     if (e._onNotify) {
       e._onNotify();
-      if (batchDepth > 0) pendingEffects.add(e);
-      continue;
+    } else if (batchDepth === 0 && e._stable) {
+      // Inline execution for stable effects: skip queue + flush + _runEffect overhead.
+      // Safe because stable effects have fixed deps (no re-subscribe needed).
+      const prev = currentEffect;
+      currentEffect = null;
+      try {
+        const result = e.fn();
+        if (typeof result === 'function') {
+          if (e._cleanup) try { e._cleanup(); } catch (err) {}
+          e._cleanup = result;
+        }
+      } catch (err) {
+        if (__DEV__) console.warn('[what] Error in stable effect:', err);
+      } finally {
+        currentEffect = prev;
+      }
+    } else if (!e._pending) {
+      e._pending = true;
+      pendingEffects.push(e);
+    }
+  }
+  if (batchDepth === 0 && pendingEffects.length > 0) scheduleMicrotask();
+}
+
+let microtaskScheduled = false;
+function scheduleMicrotask() {
+  if (!microtaskScheduled) {
+    microtaskScheduled = true;
+    queueMicrotask(() => {
+      microtaskScheduled = false;
+      flush();
+    });
+  }
+}
+
+function flush() {
+  let iterations = 0;
+  while (pendingEffects.length > 0 && iterations < 100) {
+    const batch = pendingEffects;
+    pendingEffects = [];
+    for (let i = 0; i < batch.length; i++) {
+      const e = batch[i];
+      e._pending = false;
+      if (!e.disposed && !e._onNotify) _runEffect(e);
     }
-    if (batchDepth > 0) {
-      pendingEffects.add(e);
+    iterations++;
+  }
+  if (iterations >= 100) {
+    if (__DEV__) {
+      const remaining = pendingEffects.slice(0, 3);
+      const effectNames = remaining.map(e => e.fn?.name || e.fn?.toString().slice(0, 60) || '(anonymous)');
+      console.warn(
+        `[what] Possible infinite effect loop detected (100 iterations). ` +
+        `Likely cause: an effect writes to a signal it also reads, creating a cycle. ` +
+        `Use untrack() to read signals without subscribing. ` +
+        `Looping effects: ${effectNames.join(', ')}`
+      );
     } else {
-      _runEffect(e);
+      console.warn('[what] Possible infinite effect loop detected');
     }
+    for (let i = 0; i < pendingEffects.length; i++) pendingEffects[i]._pending = false;
+    pendingEffects.length = 0;
   }
 }
 
-function flush() {
-  const effects = [...pendingEffects];
-  pendingEffects.clear();
-  for (const e of effects) {
-    if (!e.disposed && !e._onNotify) _runEffect(e);
+// --- Memo ---
+// Eager computed that only propagates when the value actually changes.
+// Reads deps eagerly (unlike lazy computed), but skips notifying subscribers
+// when the recomputed value is the same. Critical for patterns like:
+//   memo(() => selected() === item().id)  — 1000 memos, only 2 change
+export function memo(fn) {
+  let value;
+  const subs = new Set();
+
+  const e = _createEffect(() => {
+    const next = fn();
+    if (!Object.is(value, next)) {
+      value = next;
+      notify(subs);
+    }
+  });
+
+  _runEffect(e);
+
+  // Register with current root
+  if (currentRoot) {
+    currentRoot.disposals.push(() => _disposeEffect(e));
   }
+
+  function read() {
+    if (currentEffect) {
+      subs.add(currentEffect);
+      currentEffect.deps.push(subs);
+    }
+    return value;
+  }
+
+  read._signal = true;
+  read.peek = () => value;
+  return read;
+}
+
+// --- flushSync ---
+// Force all pending effects to run synchronously. Use sparingly.
+export function flushSync() {
+  microtaskScheduled = false;
+  flush();
 }
 
 // --- Untrack ---
@@ -179,3 +319,23 @@ export function untrack(fn) {
     currentEffect = prev;
   }
 }
+
+// --- createRoot ---
+// Isolated reactive scope. All effects created inside are tracked and disposed together.
+// Essential for per-item cleanup in reactive lists.
+export function createRoot(fn) {
+  const prevRoot = currentRoot;
+  const root = { disposals: [], owner: currentRoot };
+  currentRoot = root;
+  try {
+    const dispose = () => {
+      for (let i = root.disposals.length - 1; i >= 0; i--) {
+        root.disposals[i]();
+      }
+      root.disposals.length = 0;
+    };
+    return fn(dispose);
+  } finally {
+    currentRoot = prevRoot;
+  }
+}