what-react 0.10.0 → 0.11.0

package/README.md

@@ -1,8 +1,8 @@
 # what-react
 
-React compatibility layer for [What Framework](https://whatfw.com). Use React ecosystem libraries with What's signal-based engine under the hood -- zero code changes required.
+React compatibility layer for [What Framework](https://whatfw.com). Run React ecosystem libraries on What — `what-react` ships a dedicated React-semantics runtime (value-returning hooks, re-renders with keyed reconciliation, working context) that coexists with What's run-once signal engine.
 
-**90+ React libraries confirmed working**, including zustand, @tanstack/react-query, react-hook-form, framer-motion, @radix-ui, react-select, react-router, and many more.
+**Verified end-to-end (2026-06-09, real browser + jsdom CI):** zustand, @tanstack/react-query, react-hook-form, react-hot-toast, @headlessui/react, framer-motion. Other libraries are untested on the current runtime — see [REACT-COMPAT.md](https://github.com/CelsianJs/what-framework/blob/main/REACT-COMPAT.md) for the full verified matrix, method, and known limitations.
 
 ## Install
 
@@ -75,22 +75,23 @@ function Todos() {
 
 ## How It Works
 
-`what-react` implements React's public API using What's signals and reconciler:
+`what-react` ships its own React-semantics runtime (`src/runtime.js`) — what-core is not modified:
 
-- `useState`, `useEffect`, `useMemo`, etc. map to What's hook system
-- `createElement` maps to What's `h()` hyperscript
-- Class components (`Component`, `PureComponent`) are wrapped as function components
-- `createRoot` / `render` map to What's `mount()`
-- `createPortal` creates portal vnodes handled by What's reconciler
-- `forwardRef`, `cloneElement`, `Children`, `createContext` all implemented
+- Hooks return **values** (`useState` → `[value, setState]`, `useMemo` → the value) with React's deps/cleanup semantics
+- Components **re-render** on state change; output is reconciled with a keyed, type-matched diff, so DOM elements and child component state are preserved
+- `createContext` / `useContext` propagate real values through the component tree (nested providers, memo-bailout propagation)
+- Element refs attach after DOM insertion; `useLayoutEffect` is synchronous at commit; `useEffect` is async; children's effects run before the parent's
+- Class components (`Component`, `PureComponent`) are wrapped as function components (state, lifecycle, error boundaries, `contextType`)
+- `createPortal`, `lazy` + minimal `Suspense`, `React.memo` with real skip semantics
+- Compat semantics apply ONLY to elements created via what-react's `createElement`/JSX runtime — native What components keep their run-once signal semantics, in both directions (What-inside-React and React-inside-What)
 
-The key insight: React libraries import `react` and call its hooks. By aliasing `react` to `what-react`, those hooks execute on What's signal engine instead. The library never knows the difference.
+React libraries import `react` and call its hooks. By aliasing `react` to `what-react`, those hooks execute on this runtime. SSR of compat components is not supported (browser/jsdom only) — see REACT-COMPAT.md for the full limitations list.
 
 ## What's Implemented
 
 ### React (index.js)
 
-`useState`, `useEffect`, `useLayoutEffect`, `useInsertionEffect`, `useMemo`, `useCallback`, `useRef`, `useContext`, `useReducer`, `useImperativeHandle`, `useId`, `useDebugValue`, `useSyncExternalStore`, `useTransition`, `useDeferredValue`, `createElement`, `createContext`, `createRef`, `createFactory`, `forwardRef`, `cloneElement`, `isValidElement`, `Component`, `PureComponent`, `Fragment`, `Suspense`, `StrictMode`, `memo`, `lazy`, `Children`, `startTransition`
+`useState`, `useEffect`, `useLayoutEffect`, `useInsertionEffect`, `useMemo`, `useCallback`, `useRef`, `useContext`, `useReducer`, `useImperativeHandle`, `useId`, `useDebugValue`, `useSyncExternalStore`, `useTransition`, `useDeferredValue`, `use`, `createElement`, `createContext`, `createRef`, `createFactory`, `forwardRef`, `cloneElement`, `isValidElement`, `Component`, `PureComponent`, `Fragment`, `Suspense`, `StrictMode`, `memo`, `lazy`, `act`, `Children`, `startTransition`
 
 ### ReactDOM (dom.js)
 

package/package.json

@@ -1,9 +1,13 @@
 {
   "name": "what-react",
-  "version": "0.10.0",
-  "description": "React compatibility layer for What Framework — use React packages with signals under the hood",
+  "version": "0.11.0",
+  "description": "React compatibility layer for What Framework — real React semantics (value hooks, re-renders, context) on a dedicated compat runtime",
   "type": "module",
+  "sideEffects": false,
   "main": "src/index.js",
+  "scripts": {
+    "test": "node --test 'test/*.test.js'"
+  },
   "exports": {
     ".": "./src/index.js",
     "./dom": "./src/dom.js",
@@ -23,7 +27,7 @@
     "compatibility"
   ],
   "peerDependencies": {
-    "what-core": "^0.10.0"
+    "what-core": "^0.11.0"
   },
   "author": "ZVN DEV (https://zvndev.com)",
   "license": "MIT",

package/src/dom.js

@@ -1,34 +1,45 @@
 /**
  * what-react/dom — ReactDOM compatibility layer
  *
- * Implements ReactDOM's public API using What's mount() and rendering.
+ * Renders through what-react's compat runtime (React semantics: re-renders,
+ * keyed reconciliation, value hooks). Native What vnodes inside the tree are
+ * delegated to what-core automatically by the runtime.
  */
 
-import { mount as whatMount, h, Fragment } from 'what-core';
-import { flushSync as whatFlushSync } from 'what-core';
+import {
+  mountRoot,
+  patchRoot,
+  unmountRoot,
+  flushUpdates,
+  _flushPassive,
+} from './runtime.js';
 
 // ---- createRoot (React 18) ----
 
 export function createRoot(container) {
-  let unmount = null;
+  let root = null;
 
   return {
     render(element) {
-      if (unmount) unmount();
-      unmount = whatMount(element, container);
+      if (root) {
+        patchRoot(root, element);
+      } else {
+        container.textContent = '';
+        root = mountRoot(element, container);
+      }
     },
     unmount() {
-      if (unmount) {
-        unmount();
-        unmount = null;
+      if (root) {
+        unmountRoot(root);
+        root = null;
       }
-      container.innerHTML = '';
+      container.textContent = '';
     },
   };
 }
 
 // ---- hydrateRoot ----
-// Basic implementation — mounts fresh (true hydration would reuse existing DOM)
+// No true hydration — replaces server-rendered content with a fresh mount.
 
 export function hydrateRoot(container, initialChildren) {
   const root = createRoot(container);
@@ -38,8 +49,14 @@ export function hydrateRoot(container, initialChildren) {
 
 // ---- render (React 17 legacy) ----
 
+const legacyRoots = new WeakMap();
+
 export function render(element, container, callback) {
-  const root = createRoot(container);
+  let root = legacyRoots.get(container);
+  if (!root) {
+    root = createRoot(container);
+    legacyRoots.set(container, root);
+  }
   root.render(element);
   if (callback) queueMicrotask(callback);
   return root;
@@ -48,53 +65,59 @@ export function render(element, container, callback) {
 // ---- unmountComponentAtNode (React 17 legacy) ----
 
 export function unmountComponentAtNode(container) {
+  const root = legacyRoots.get(container);
+  if (root) {
+    root.unmount();
+    legacyRoots.delete(container);
+    return true;
+  }
   container.innerHTML = '';
   return true;
 }
 
 // ---- createPortal ----
+// The compat runtime recognizes '__portal' vnodes and renders children into
+// the target container while keeping context/ownership from the React tree.
 
 export function createPortal(children, container, key) {
-  // Create a vnode that the core reconciler recognizes as a portal.
-  // Core's createDOM routes '__portal' tagged vnodes to the internal portal handler,
-  // which renders children into the target container and returns a placeholder comment.
-  const portal = {
+  return {
     tag: '__portal',
+    type: '__portal',
     props: { container, key },
     children: Array.isArray(children) ? children : [children],
-    key: key || null,
+    key: key ?? null,
     _vnode: true,
+    _compat: true,
   };
-
-  return portal;
 }
 
 // ---- flushSync ----
 
 export function flushSync(fn) {
-  if (fn) fn();
-  whatFlushSync();
+  let result;
+  if (fn) result = fn();
+  flushUpdates();
+  _flushPassive();
+  flushUpdates();
+  return result;
 }
 
 // ---- findDOMNode (deprecated but needed for legacy packages) ----
 
 export function findDOMNode(component) {
   if (component == null) return null;
-  // If it's already a DOM node, return it
-  if (component instanceof HTMLElement) return component;
-  // Class component instance — look for _domNode or _container
+  if (typeof Element !== 'undefined' && component instanceof Element) return component;
   if (component._domNode) return component._domNode;
-  // If the component has a ref attached, try that
-  if (component._ref?.current instanceof HTMLElement) return component._ref.current;
-  // what-c wrapper element — return the first child
-  if (component instanceof Element) return component;
+  if (component._ref && component._ref.current instanceof Element) return component._ref.current;
   return null;
 }
 
 // ---- batching ----
 
 export function unstable_batchedUpdates(fn) {
-  fn();
+  const result = fn();
+  flushUpdates();
+  return result;
 }
 
 // ---- Version ----

package/src/hooks.js

@@ -0,0 +1,351 @@
+/**
+ * what-react/hooks — React hooks with REAL React semantics (value-returning).
+ *
+ * Unlike what-core's hooks (which return signal accessors for the run-once
+ * model), these hooks return plain VALUES and trigger re-renders through the
+ * compat runtime's scheduler:
+ *
+ *   const [count, setCount] = useState(0);   // count is a NUMBER
+ *   const doubled = useMemo(() => count * 2, [count]); // doubled is a NUMBER
+ *
+ * They are only valid inside components rendered by the compat runtime
+ * (anything created via what-react's createElement / jsx-runtime).
+ */
+
+import {
+  _requireInstance,
+  _getCurrentInstance,
+  _getHookSlot,
+  scheduleUpdate,
+  _pushLayout,
+  _pushPassive,
+  flushUpdates,
+} from './runtime.js';
+
+function depsChanged(oldDeps, newDeps) {
+  if (oldDeps === undefined || newDeps === undefined) return true;
+  if (oldDeps === null || newDeps === null) return true;
+  if (oldDeps.length !== newDeps.length) return true;
+  for (let i = 0; i < oldDeps.length; i++) {
+    if (!Object.is(oldDeps[i], newDeps[i])) return true;
+  }
+  return false;
+}
+
+// ---- useState ----
+
+export function useState(initial) {
+  const inst = _requireInstance('useState');
+  const slot = _getHookSlot(inst);
+  if (!slot.init) {
+    slot.init = true;
+    slot.value = typeof initial === 'function' ? initial() : initial;
+    slot.set = (next) => {
+      const resolved = typeof next === 'function' ? next(slot.value) : next;
+      if (Object.is(resolved, slot.value)) return;
+      slot.value = resolved;
+      scheduleUpdate(inst);
+    };
+  }
+  return [slot.value, slot.set];
+}
+
+// ---- useReducer ----
+
+export function useReducer(reducer, initialArg, init) {
+  const inst = _requireInstance('useReducer');
+  const slot = _getHookSlot(inst);
+  if (!slot.init) {
+    slot.init = true;
+    slot.value = init ? init(initialArg) : initialArg;
+    slot.reducer = reducer;
+    slot.dispatch = (action) => {
+      const next = slot.reducer(slot.value, action);
+      if (Object.is(next, slot.value)) return;
+      slot.value = next;
+      scheduleUpdate(inst);
+    };
+  }
+  slot.reducer = reducer; // always use the latest reducer closure
+  return [slot.value, slot.dispatch];
+}
+
+// ---- useMemo / useCallback ----
+
+export function useMemo(factory, deps) {
+  const inst = _requireInstance('useMemo');
+  const slot = _getHookSlot(inst);
+  if (!slot.init || depsChanged(slot.deps, deps)) {
+    slot.init = true;
+    slot.deps = deps;
+    slot.value = factory();
+  }
+  return slot.value;
+}
+
+export function useCallback(callback, deps) {
+  const inst = _requireInstance('useCallback');
+  const slot = _getHookSlot(inst);
+  if (!slot.init || depsChanged(slot.deps, deps)) {
+    slot.init = true;
+    slot.deps = deps;
+    slot.value = callback;
+  }
+  return slot.value;
+}
+
+// ---- useRef ----
+
+export function useRef(initial) {
+  const inst = _requireInstance('useRef');
+  const slot = _getHookSlot(inst);
+  if (!slot.init) {
+    slot.init = true;
+    slot.value = { current: initial };
+  }
+  return slot.value;
+}
+
+// ---- useEffect / useLayoutEffect / useInsertionEffect ----
+
+function useEffectImpl(hookName, push, fn, deps) {
+  const inst = _requireInstance(hookName);
+  const slot = _getHookSlot(inst);
+  if (!slot.init) {
+    slot.init = true;
+    slot._isEffect = true;
+    slot.cleanup = null;
+    slot.deps = undefined;
+    slot._pending = null;
+  }
+  if (depsChanged(slot.deps, deps)) {
+    slot.deps = deps;
+    push(inst, slot, fn);
+  }
+}
+
+export function useEffect(fn, deps) {
+  useEffectImpl('useEffect', _pushPassive, fn, deps);
+}
+
+export function useLayoutEffect(fn, deps) {
+  useEffectImpl('useLayoutEffect', _pushLayout, fn, deps);
+}
+
+// Runs synchronously during render (before this component's DOM mutations) —
+// the closest approximation of React's insertion phase for CSS-in-JS libs.
+export function useInsertionEffect(fn, deps) {
+  const inst = _requireInstance('useInsertionEffect');
+  const slot = _getHookSlot(inst);
+  if (!slot.init) {
+    slot.init = true;
+    slot._isEffect = true;
+    slot.cleanup = null;
+    slot.deps = undefined;
+  }
+  if (depsChanged(slot.deps, deps)) {
+    slot.deps = deps;
+    if (slot.cleanup) {
+      try { slot.cleanup(); } catch (e) { console.error('[what-react] insertion effect cleanup error:', e); }
+      slot.cleanup = null;
+    }
+    try {
+      const result = fn();
+      if (typeof result === 'function') slot.cleanup = result;
+    } catch (e) {
+      console.error('[what-react] insertion effect error:', e);
+    }
+  }
+}
+
+// ---- useImperativeHandle ----
+
+export function useImperativeHandle(ref, createHandle, deps) {
+  useLayoutEffect(() => {
+    if (typeof ref === 'function') {
+      const handle = createHandle();
+      ref(handle);
+      return () => ref(null);
+    } else if (ref && typeof ref === 'object') {
+      ref.current = createHandle();
+      return () => { ref.current = null; };
+    }
+  }, deps == null ? deps : [...deps, ref]);
+}
+
+// ---- useContext / createContext ----
+
+export function createContext(defaultValue) {
+  const context = {
+    $$typeof: Symbol.for('react.context'),
+    _defaultValue: defaultValue,
+    displayName: 'Context',
+  };
+
+  function Provider(props) {
+    const inst = _requireInstance('Context.Provider');
+    if (!inst._ctxProvided) inst._ctxProvided = new Map();
+    const had = inst._ctxProvided.has(context);
+    const prev = inst._ctxProvided.get(context);
+    inst._ctxProvided.set(context, props.value);
+    if (had && !Object.is(prev, props.value) && inst._ctxSubs) {
+      // Context propagation: consumers re-render even if intermediate
+      // components bailed out (identical-element / memo skip).
+      const subs = inst._ctxSubs.get(context);
+      if (subs) {
+        for (const sub of subs) scheduleUpdate(sub);
+      }
+    }
+    return props.children;
+  }
+  Provider.displayName = 'Context.Provider';
+  Provider._context = context;
+
+  function Consumer(props) {
+    const value = useContext(context);
+    const children = props.children;
+    return typeof children === 'function' ? children(value) : children;
+  }
+  Consumer.displayName = 'Context.Consumer';
+  Consumer._context = context;
+
+  context.Provider = Provider;
+  context.Consumer = Consumer;
+  return context;
+}
+
+export function useContext(context) {
+  const inst = _requireInstance('useContext');
+  let p = inst.parent;
+  while (p) {
+    if (p._ctxProvided && p._ctxProvided.has(context)) {
+      // Subscribe for direct propagation (needed when ancestors bail out).
+      if (!p._ctxSubs) p._ctxSubs = new Map();
+      let subs = p._ctxSubs.get(context);
+      if (!subs) {
+        subs = new Set();
+        p._ctxSubs.set(context, subs);
+      }
+      if (!subs.has(inst)) {
+        subs.add(inst);
+        (inst._ctxDeps || (inst._ctxDeps = [])).push([p, context]);
+      }
+      return p._ctxProvided.get(context);
+    }
+    p = p.parent;
+  }
+  return context._defaultValue;
+}
+
+// ---- useSyncExternalStore ----
+// Spec-compliant: returns the snapshot VALUE and re-renders on store change.
+
+export function useSyncExternalStore(subscribe, getSnapshot, getServerSnapshot) {
+  const inst = _requireInstance('useSyncExternalStore');
+  const slot = _getHookSlot(inst);
+  if (!slot.init) {
+    slot.init = true;
+    slot._isEffect = true; // unmount runs slot.cleanup (the unsubscribe)
+    slot.cleanup = null;
+    slot.subscribe = undefined;
+    slot._pending = null;
+  }
+  const value = getSnapshot();
+  slot.value = value;
+  slot.getSnapshot = getSnapshot;
+
+  if (slot.subscribe !== subscribe) {
+    slot.subscribe = subscribe;
+    _pushLayout(inst, slot, () => {
+      const handleChange = () => {
+        const next = slot.getSnapshot();
+        if (!Object.is(slot.value, next)) {
+          slot.value = next;
+          scheduleUpdate(inst);
+        }
+      };
+      const unsubscribe = subscribe(handleChange);
+      handleChange(); // catch changes between render and subscription
+      return unsubscribe;
+    });
+  }
+
+  return value;
+}
+
+// ---- useTransition / useDeferredValue / startTransition ----
+// Rendering here is synchronous — transitions degrade to immediate updates.
+
+export function useTransition() {
+  _requireInstance('useTransition');
+  return [false, startTransition];
+}
+
+export function startTransition(fn) {
+  fn();
+  flushUpdates();
+}
+
+export function useDeferredValue(value) {
+  return value;
+}
+
+// ---- useId ----
+
+let idCounter = 0;
+
+export function useId() {
+  const inst = _requireInstance('useId');
+  const slot = _getHookSlot(inst);
+  if (!slot.init) {
+    slot.init = true;
+    slot.value = ':w' + (++idCounter).toString(36) + ':';
+  }
+  return slot.value;
+}
+
+// ---- useDebugValue ----
+
+export function useDebugValue() {}
+
+// ---- use (React 19-style, minimal) ----
+// Context → useContext. Thenable → resolved value or throw for Suspense.
+
+export function use(usable) {
+  if (usable !== null && typeof usable === 'object') {
+    if (typeof usable.then === 'function') {
+      const thenable = usable;
+      if (thenable._whatStatus === 'fulfilled') return thenable._whatValue;
+      if (thenable._whatStatus === 'rejected') throw thenable._whatReason;
+      if (thenable._whatStatus === undefined) {
+        thenable._whatStatus = 'pending';
+        thenable.then(
+          (v) => { thenable._whatStatus = 'fulfilled'; thenable._whatValue = v; },
+          (e) => { thenable._whatStatus = 'rejected'; thenable._whatReason = e; },
+        );
+      }
+      throw thenable; // caught by the nearest Suspense boundary
+    }
+    if (usable.$$typeof === Symbol.for('react.context')) {
+      return useContext(usable);
+    }
+  }
+  throw new Error('[what-react] use() expects a promise or a context.');
+}
+
+// ---- useSignal (escape hatch) ----
+// Bridge helper for mixed codebases: subscribe a compat component to a
+// what-core signal. Re-renders this component when the signal changes.
+
+export function useWhatSignal(sig) {
+  return useSyncExternalStore(
+    (notify) => {
+      // what-core signals don't expose subscribe directly; poll via effect-free
+      // microtask comparison is wasteful — use sig.subscribe if present.
+      if (typeof sig.subscribe === 'function') return sig.subscribe(notify);
+      // Fallback: no subscription available; value still read each render.
+      return () => {};
+    },
+    () => sig(),
+  );
+}