what-core 0.5.1 → 0.5.4

package/README.md

@@ -0,0 +1,119 @@
+# what-core
+
+The reactive engine behind [What Framework](https://whatfw.com). Provides signals, fine-grained reactivity, components, hooks, and DOM rendering -- all without a virtual DOM diffing step.
+
+Most users should install [`what-framework`](https://www.npmjs.com/package/what-framework) instead. `what-core` is the internal engine consumed by other What packages.
+
+## Install
+
+```bash
+npm install what-core
+```
+
+## Reactive Primitives
+
+```js
+import { signal, computed, effect, batch, untrack } from 'what-core';
+
+const count = signal(0);
+
+// Read
+count();          // 0
+
+// Write
+count.set(5);
+count.set(c => c + 1);
+
+// Derived value
+const doubled = computed(() => count() * 2);
+
+// Side effects
+effect(() => {
+  console.log('Count:', count());
+});
+
+// Batch updates (effects run once at the end)
+batch(() => {
+  a.set(1);
+  b.set(2);
+});
+
+// Read without subscribing
+untrack(() => someSignal());
+count.peek();
+```
+
+## Hooks
+
+React-compatible hooks backed by signals internally.
+
+```js
+import {
+  useState, useEffect, useMemo, useCallback,
+  useRef, useReducer, useContext, createContext,
+  onMount, onCleanup,
+} from 'what-core';
+
+const [count, setCount] = useState(0);
+
+useEffect(() => {
+  const id = setInterval(tick, 1000);
+  return () => clearInterval(id);
+}, []);
+```
+
+## Components
+
+```js
+import { h, mount, Fragment, memo, lazy, Suspense, ErrorBoundary, Show, For } from 'what-core';
+
+function Counter() {
+  const count = signal(0);
+  return h('button', { onclick: () => count.set(c => c + 1) }, () => count());
+}
+
+mount(h(Counter), '#app');
+```
+
+## Additional Modules
+
+| Export path | Contents |
+|---|---|
+| `what-core` | Signals, hooks, components, store, forms, data fetching, animation, a11y, skeleton loaders |
+| `what-core/render` | Fine-grained rendering primitives (`template`, `insert`, `spread`, `delegateEvents`) |
+| `what-core/jsx-runtime` | JSX automatic runtime |
+| `what-core/testing` | Test utilities |
+
+## API Overview
+
+**Reactivity** -- `signal`, `computed`, `effect`, `batch`, `untrack`, `flushSync`, `createRoot`
+
+**Rendering** -- `h`, `Fragment`, `html`, `mount`, `template`, `insert`, `spread`, `delegateEvents`
+
+**Hooks** -- `useState`, `useSignal`, `useComputed`, `useEffect`, `useMemo`, `useCallback`, `useRef`, `useContext`, `useReducer`, `createContext`, `onMount`, `onCleanup`, `createResource`
+
+**Components** -- `memo`, `lazy`, `Suspense`, `ErrorBoundary`, `Show`, `For`, `Switch`, `Match`, `Island`, `Portal`
+
+**Store** -- `createStore`, `derived`, `atom`
+
+**Data Fetching** -- `useSWR`, `useQuery`, `useInfiniteQuery`, `invalidateQueries`, `prefetchQuery`
+
+**Forms** -- `useForm`, `useField`, `rules`, `zodResolver`, `Input`, `Select`, `Checkbox`, `ErrorMessage`
+
+**Animation** -- `spring`, `tween`, `easings`, `useGesture`, `useTransition`
+
+**Accessibility** -- `useFocusTrap`, `FocusTrap`, `announce`, `SkipLink`, `useRovingTabIndex`, `VisuallyHidden`, `useId`
+
+**Scheduler** -- `scheduleRead`, `scheduleWrite`, `measure`, `mutate`, `onResize`, `onIntersect`
+
+**Head** -- `Head`, `clearHead`
+
+## Links
+
+- [Documentation](https://whatfw.com)
+- [GitHub](https://github.com/zvndev/what-fw)
+- [Benchmarks](https://benchmarks.whatfw.com)
+
+## License
+
+MIT

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "what-core",
-  "version": "0.5.1",
+  "version": "0.5.4",
   "description": "What Framework - The closest framework to vanilla JS",
   "type": "module",
   "main": "dist/what.js",
@@ -48,10 +48,10 @@
   "license": "MIT",
   "repository": {
     "type": "git",
-    "url": "https://github.com/aspect/what-fw"
+    "url": "https://github.com/zvndev/what-fw"
   },
   "bugs": {
-    "url": "https://github.com/aspect/what-fw/issues"
+    "url": "https://github.com/zvndev/what-fw/issues"
   },
-  "homepage": "https://github.com/aspect/what-fw#readme"
+  "homepage": "https://whatfw.com"
 }

package/src/components.js

@@ -50,7 +50,7 @@ export function memo(Component, areEqual) {
 let _getCurrentComponent = null;
 export function _injectGetCurrentComponent(fn) { _getCurrentComponent = fn; }
 
-function shallowEqual(a, b) {
+export function shallowEqual(a, b) {
   if (a === b) return true;
   const keysA = Object.keys(a);
   const keysB = Object.keys(b);

package/src/data.js

@@ -636,3 +636,20 @@ export function clearCache() {
   lastFetchTimestamps.clear();
   inFlightRequests.clear();
 }
+
+/**
+ * Get a snapshot of all cache entries for devtools.
+ * @internal
+ */
+export function __getCacheSnapshot() {
+  const entries = [];
+  for (const [key, sig] of cacheSignals) {
+    entries.push({
+      key,
+      data: sig.peek(),
+      error: errorSignals.has(key) ? errorSignals.get(key).peek() : null,
+      isValidating: validatingSignals.has(key) ? validatingSignals.get(key).peek() : false,
+    });
+  }
+  return entries;
+}

package/src/dom.js

@@ -3,8 +3,8 @@
 // Components use <what-c> wrapper elements (display:contents) for clean reconciliation.
 // No virtual DOM tree kept in memory — we diff against the live DOM.
 
-import { effect, batch, untrack, signal } from './reactive.js';
-import { reportError, _injectGetCurrentComponent } from './components.js';
+import { effect, batch, untrack, signal, __DEV__, __devtools } from './reactive.js';
+import { reportError, _injectGetCurrentComponent, shallowEqual } from './components.js';
 import { _setComponentRef } from './helpers.js';
 
 // Register <what-c> custom element to prevent flash of unstyled content
@@ -14,6 +14,36 @@ if (typeof customElements !== 'undefined' && !customElements.get('what-c')) {
     connectedCallback() {
       this.style.display = 'contents';
     }
+    // display:contents elements don't generate a layout box — getBoundingClientRect()
+    // returns zeros, offsetWidth/Height return 0. React libraries (react-draggable,
+    // react-colorful, etc.) traverse parentNode and call getBoundingClientRect() on
+    // what they expect to be a layout container. Since <what-c> is layout-invisible,
+    // delegate to the nearest ancestor that has a real box.
+    _layoutParent() {
+      let el = this.parentElement;
+      while (el && el.tagName === 'WHAT-C') el = el.parentElement;
+      return el;
+    }
+    getBoundingClientRect() {
+      const p = this._layoutParent();
+      return p ? p.getBoundingClientRect() : super.getBoundingClientRect();
+    }
+    get offsetWidth() {
+      const p = this._layoutParent();
+      return p ? p.offsetWidth : 0;
+    }
+    get offsetHeight() {
+      const p = this._layoutParent();
+      return p ? p.offsetHeight : 0;
+    }
+    get clientWidth() {
+      const p = this._layoutParent();
+      return p ? p.clientWidth : 0;
+    }
+    get clientHeight() {
+      const p = this._layoutParent();
+      return p ? p.clientHeight : 0;
+    }
   });
 }
 
@@ -67,6 +97,7 @@ function disposeComponent(ctx) {
     try { dispose(); } catch (e) { /* effect already disposed */ }
   }
 
+  if (__DEV__ && __devtools?.onComponentUnmount) __devtools.onComponentUnmount(ctx);
   mountedComponents.delete(ctx);
 }
 
@@ -160,6 +191,11 @@ export function createDOM(vnode, parent, isSvg) {
     return document.createTextNode(String(vnode));
   }
 
+  // Portal (string-tagged vnodes from helpers.js Portal or react-compat createPortal)
+  if (vnode.tag === '__portal') {
+    return createPortalDOM(vnode, parent);
+  }
+
   // Component
   if (typeof vnode.tag === 'function') {
     return createComponent(vnode, parent, isSvg);
@@ -208,7 +244,20 @@ export function getComponentStack() {
 }
 
 function createComponent(vnode, parent, isSvg) {
-  const { tag: Component, props, children } = vnode;
+  let { tag: Component, props, children } = vnode;
+
+  // Class component detection — ES6 classes can't be called without `new`.
+  // React compat layer wraps class components in createElement, but some
+  // library-internal components may bypass that path. Detect and wrap here.
+  if (typeof Component === 'function' &&
+      (Component.prototype?.isReactComponent || Component.prototype?.render)) {
+    const ClassComp = Component;
+    Component = function ClassComponentBridge(props) {
+      const instance = new ClassComp(props);
+      return instance.render();
+    };
+    Component.displayName = ClassComp.displayName || ClassComp.name || 'ClassComponent';
+  }
 
   // Handle special boundary components
   if (Component === '__errorBoundary' || vnode.tag === '__errorBoundary') {
@@ -217,8 +266,8 @@ function createComponent(vnode, parent, isSvg) {
   if (Component === '__suspense' || vnode.tag === '__suspense') {
     return createSuspenseBoundary(vnode, parent);
   }
-  if (Component === '__portal' || vnode.tag === '__portal') {
-    return createPortal(vnode, parent);
+  if (Component === '__portal' || vnode.tag === '__portal') { // Now also handled in createDOM directly
+    return createPortalDOM(vnode, parent);
   }
 
   // Component context for hooks
@@ -256,9 +305,12 @@ function createComponent(vnode, parent, isSvg) {
 
   // Track for disposal
   mountedComponents.add(ctx);
+  if (__DEV__ && __devtools?.onComponentMount) __devtools.onComponentMount(ctx);
 
   // Props signal for reactive updates from parent
-  const propsSignal = signal({ ...props, children });
+  // Match React's children semantics: 0→undefined, 1→single child, N→array
+  const propsChildren = children.length === 0 ? undefined : children.length === 1 ? children[0] : children;
+  const propsSignal = signal({ ...props, children: propsChildren });
   ctx._propsSignal = propsSignal;
 
   // Reactive render: re-renders when signals used inside change
@@ -280,7 +332,9 @@ function createComponent(vnode, parent, isSvg) {
       return;
     }
 
-    componentStack.pop();
+    // Keep ctx on componentStack while creating/reconciling children
+    // so child components' _parentCtx correctly points to this component.
+    // This is essential for context propagation (useContext walks _parentCtx).
 
     const vnodes = Array.isArray(result) ? result : [result];
 
@@ -306,6 +360,8 @@ function createComponent(vnode, parent, isSvg) {
       // Update: reconcile children inside wrapper
       reconcileChildren(wrapper, vnodes);
     }
+
+    componentStack.pop();
   });
 
   ctx.effects.push(dispose);
@@ -343,7 +399,6 @@ function createErrorBoundary(vnode, parent) {
       vnodes = children;
     }
 
-    componentStack.pop();
     vnodes = Array.isArray(vnodes) ? vnodes : [vnodes];
 
     if (wrapper.childNodes.length === 0) {
@@ -354,6 +409,8 @@ function createErrorBoundary(vnode, parent) {
     } else {
       reconcileChildren(wrapper, vnodes);
     }
+
+    componentStack.pop();
   });
 
   boundaryCtx.effects.push(dispose);
@@ -381,6 +438,8 @@ function createSuspenseBoundary(vnode, parent) {
     const vnodes = isLoading ? [fallback] : children;
     const normalized = Array.isArray(vnodes) ? vnodes : [vnodes];
 
+    componentStack.push(boundaryCtx);
+
     if (wrapper.childNodes.length === 0) {
       for (const v of normalized) {
         const node = createDOM(v, wrapper);
@@ -389,6 +448,8 @@ function createSuspenseBoundary(vnode, parent) {
     } else {
       reconcileChildren(wrapper, normalized);
     }
+
+    componentStack.pop();
   });
 
   boundaryCtx.effects.push(dispose);
@@ -396,7 +457,7 @@ function createSuspenseBoundary(vnode, parent) {
 }
 
 // Portal component handler — renders children into a different DOM container
-function createPortal(vnode, parent) {
+function createPortalDOM(vnode, parent) {
   const { container } = vnode.props;
   const children = vnode.children;
 
@@ -494,9 +555,33 @@ function reconcileUnkeyed(parent, oldNodes, newVNodes, beforeMarker) {
 
 // Keyed reconciliation with LIS algorithm for O(n log n) minimal moves
 function reconcileKeyed(parent, oldNodes, newVNodes, beforeMarker) {
+  const newLen = newVNodes.length;
+  const oldLen = oldNodes.length;
+
+  // --- Fast path: same-position keys (covers "update N items in-place") ---
+  // If same length and all keys match at the same index, skip LIS entirely.
+  // Just patch each node in-place — O(n) with zero DOM moves.
+  if (newLen === oldLen && newLen > 0) {
+    let allMatch = true;
+    for (let i = 0; i < newLen; i++) {
+      const newKey = newVNodes[i]?.key;
+      const oldKey = oldNodes[i]?._vnode?.key;
+      if (newKey == null || newKey !== oldKey) {
+        allMatch = false;
+        break;
+      }
+    }
+    if (allMatch) {
+      for (let i = 0; i < newLen; i++) {
+        patchNode(parent, oldNodes[i], newVNodes[i]);
+      }
+      return;
+    }
+  }
+
   // Build old key -> { node, index } map
   const oldKeyMap = new Map();
-  for (let i = 0; i < oldNodes.length; i++) {
+  for (let i = 0; i < oldLen; i++) {
     const node = oldNodes[i];
     const key = node._vnode?.key;
     if (key != null) {
@@ -505,7 +590,6 @@ function reconcileKeyed(parent, oldNodes, newVNodes, beforeMarker) {
   }
 
   const newNodes = [];
-  const newLen = newVNodes.length;
 
   // First pass: match keys and find reusable nodes
   const sources = new Array(newLen).fill(-1); // Maps new index to old index
@@ -522,7 +606,7 @@ function reconcileKeyed(parent, oldNodes, newVNodes, beforeMarker) {
   }
 
   // Remove nodes that aren't reused
-  for (let i = 0; i < oldNodes.length; i++) {
+  for (let i = 0; i < oldLen; i++) {
     if (!reused.has(i) && oldNodes[i]?.parentNode) {
       disposeTree(oldNodes[i]);
       oldNodes[i].parentNode.removeChild(oldNodes[i]);
@@ -794,7 +878,14 @@ function patchNode(parent, domNode, vnode) {
     if (domNode._componentCtx && !domNode._componentCtx.disposed
         && domNode._componentCtx.Component === vnode.tag) {
       // Same component — update props reactively, let its effect re-render
-      domNode._componentCtx._propsSignal.set({ ...vnode.props, children: vnode.children });
+      const ch = vnode.children;
+      const patchChildren = ch.length === 0 ? undefined : ch.length === 1 ? ch[0] : ch;
+      const nextProps = { ...vnode.props, children: patchChildren };
+      // Skip signal update if props haven't changed (shallow compare)
+      const prevProps = domNode._componentCtx._propsSignal.peek();
+      if (!shallowEqual(prevProps, nextProps)) {
+        domNode._componentCtx._propsSignal.set(nextProps);
+      }
       domNode._vnode = vnode; // Keep vnode current for keyed reconciliation
       return domNode;
     }
@@ -905,23 +996,40 @@ function applyProps(el, newProps, oldProps, isSvg) {
 }
 
 function setProp(el, key, value, isSvg) {
-  // Event handlers: onClick -> click
+  // Event handlers: onClick -> click, onFocusCapture -> focus (capture phase)
   // Wrap in untrack so signal reads in handlers don't create subscriptions
   if (key.startsWith('on') && key.length > 2) {
-    const event = key.slice(2).toLowerCase();
+    let eventName = key.slice(2);
+    // React-style capture phase: onClickCapture → click in capture phase
+    let useCapture = false;
+    if (eventName.endsWith('Capture')) {
+      eventName = eventName.slice(0, -7);
+      useCapture = true;
+    }
+    const event = eventName.toLowerCase();
+    // Use a combined key for storage so capture/bubble don't conflict
+    const storageKey = useCapture ? event + '_capture' : event;
     // Store handler for removal
-    const old = el._events?.[event];
+    const old = el._events?.[storageKey];
     // Skip re-wrapping if same handler function
     if (old && old._original === value) return;
-    if (old) el.removeEventListener(event, old);
+    if (old) el.removeEventListener(event, old, useCapture);
+    // If handler is null/undefined, just remove the old one and bail
+    if (value == null) return;
     if (!el._events) el._events = {};
-    // Wrap handler to untrack signal reads
-    const wrappedHandler = (e) => untrack(() => value(e));
+    // Wrap handler to untrack signal reads.
+    // Add nativeEvent for React compat — React synthetic events have
+    // e.nativeEvent pointing to the actual DOM event. Libraries like
+    // react-colorful, cmdk, and @floating-ui/react check this property.
+    const wrappedHandler = (e) => {
+      if (!e.nativeEvent) e.nativeEvent = e;
+      return untrack(() => value(e));
+    };
     wrappedHandler._original = value;
-    el._events[event] = wrappedHandler;
+    el._events[storageKey] = wrappedHandler;
     // Check for _eventOpts (once/capture/passive from compiler)
     const eventOpts = value._eventOpts;
-    el.addEventListener(event, wrappedHandler, eventOpts || undefined);
+    el.addEventListener(event, wrappedHandler, eventOpts || useCapture || undefined);
     return;
   }
 
@@ -1003,10 +1111,17 @@ function setProp(el, key, value, isSvg) {
 
 function removeProp(el, key, oldValue) {
   if (key.startsWith('on') && key.length > 2) {
-    const event = key.slice(2).toLowerCase();
-    if (el._events?.[event]) {
-      el.removeEventListener(event, el._events[event]);
-      delete el._events[event];
+    let eventName = key.slice(2);
+    let useCapture = false;
+    if (eventName.endsWith('Capture')) {
+      eventName = eventName.slice(0, -7);
+      useCapture = true;
+    }
+    const event = eventName.toLowerCase();
+    const storageKey = useCapture ? event + '_capture' : event;
+    if (el._events?.[storageKey]) {
+      el.removeEventListener(event, el._events[storageKey], useCapture);
+      delete el._events[storageKey];
     }
     return;
   }

package/src/hooks.js

@@ -192,6 +192,11 @@ export function createContext(defaultValue) {
       }
       return children;
     },
+    // React-compatible Consumer: <Context.Consumer>{value => ...}</Context.Consumer>
+    Consumer: ({ children }) => {
+      const value = useContext(context);
+      return typeof children === 'function' ? children(value) : children;
+    },
   };
   return context;
 }

package/src/index.js

@@ -2,7 +2,7 @@
 // The closest framework to vanilla JS.
 
 // Reactive primitives
-export { signal, computed, effect, memo as signalMemo, batch, untrack, flushSync, createRoot } from './reactive.js';
+export { signal, computed, effect, memo as signalMemo, batch, untrack, flushSync, createRoot, __setDevToolsHooks } from './reactive.js';
 
 // Fine-grained rendering primitives
 export { template, insert, mapArray, spread, setProp, delegateEvents, on, classList } from './render.js';
@@ -132,6 +132,7 @@ export {
   setQueryData,
   getQueryData,
   clearCache,
+  __getCacheSnapshot,
 } from './data.js';
 
 // Form utilities

package/src/reactive.js

@@ -2,7 +2,18 @@
 // 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;
+export const __DEV__ = typeof process !== 'undefined'
+  ? process.env?.NODE_ENV !== 'production'
+  : true;
+
+// DevTools hooks — set by what-devtools when installed.
+// These are no-ops in production (dead-code eliminated with __DEV__).
+export let __devtools = null;
+
+/** @internal Install devtools hooks. Called by what-devtools. */
+export function __setDevToolsHooks(hooks) {
+  if (__DEV__) __devtools = hooks;
+}
 
 let currentEffect = null;
 let currentRoot = null;
@@ -13,7 +24,7 @@ let pendingEffects = [];
 // A reactive value. Reading inside an effect auto-tracks the dependency.
 // Writing triggers only the effects that depend on this signal.
 
-export function signal(initial) {
+export function signal(initial, debugName) {
   let value = initial;
   const subs = new Set();
 
@@ -31,6 +42,7 @@ export function signal(initial) {
     const nextVal = typeof args[0] === 'function' ? args[0](value) : args[0];
     if (Object.is(value, nextVal)) return;
     value = nextVal;
+    if (__DEV__ && __devtools) __devtools.onSignalUpdate(sig);
     notify(subs);
   }
 
@@ -38,6 +50,7 @@ export function signal(initial) {
     const nextVal = typeof next === 'function' ? next(value) : next;
     if (Object.is(value, nextVal)) return;
     value = nextVal;
+    if (__DEV__ && __devtools) __devtools.onSignalUpdate(sig);
     notify(subs);
   };
 
@@ -48,6 +61,14 @@ export function signal(initial) {
   };
 
   sig._signal = true;
+  if (__DEV__) {
+    sig._subs = subs;
+    if (debugName) sig._debugName = debugName;
+  }
+
+  // Notify devtools of signal creation
+  if (__DEV__ && __devtools) __devtools.onSignalCreate(sig);
+
   return sig;
 }
 
@@ -130,7 +151,7 @@ export function batch(fn) {
 // --- Internals ---
 
 function _createEffect(fn, lazy) {
-  return {
+  const e = {
     fn,
     deps: [],            // array of subscriber sets (cheaper than Set for typical 1-3 deps)
     lazy: lazy || false,
@@ -139,6 +160,8 @@ function _createEffect(fn, lazy) {
     _pending: false,
     _stable: false,      // stable effects skip cleanup/re-subscribe on re-run
   };
+  if (__DEV__ && __devtools) __devtools.onEffectCreate(e);
+  return e;
 }
 
 function _runEffect(e) {
@@ -158,9 +181,13 @@ function _runEffect(e) {
     try {
       const result = e.fn();
       if (typeof result === 'function') e._cleanup = result;
+    } catch (err) {
+      if (__devtools?.onError) __devtools.onError(err, { type: 'effect', effect: e });
+      if (__DEV__) console.warn('[what] Error in stable effect:', err);
     } finally {
       currentEffect = prev;
     }
+    if (__DEV__ && __devtools?.onEffectRun) __devtools.onEffectRun(e);
     return;
   }
 
@@ -168,6 +195,7 @@ function _runEffect(e) {
   // Run effect cleanup from previous run
   if (e._cleanup) {
     try { e._cleanup(); } catch (err) {
+      if (__devtools?.onError) __devtools.onError(err, { type: 'effect-cleanup', effect: e });
       if (__DEV__) console.warn('[what] Error in effect cleanup:', err);
     }
     e._cleanup = null;
@@ -180,13 +208,18 @@ function _runEffect(e) {
     if (typeof result === 'function') {
       e._cleanup = result;
     }
+  } catch (err) {
+    if (__devtools?.onError) __devtools.onError(err, { type: 'effect', effect: e });
+    throw err;
   } finally {
     currentEffect = prev;
   }
+  if (__DEV__ && __devtools?.onEffectRun) __devtools.onEffectRun(e);
 }
 
 function _disposeEffect(e) {
   e.disposed = true;
+  if (__DEV__ && __devtools) __devtools.onEffectDispose(e);
   cleanup(e);
   // Run cleanup on dispose
   if (e._cleanup) {
@@ -220,6 +253,7 @@ function notify(subs) {
           e._cleanup = result;
         }
       } catch (err) {
+        if (__devtools?.onError) __devtools.onError(err, { type: 'effect', effect: e });
         if (__DEV__) console.warn('[what] Error in stable effect:', err);
       } finally {
         currentEffect = prev;