@ipxjs/refract 0.3.1 → 0.4.0

package/src/refract/compat/sharedInternals.ts

@@ -0,0 +1,212 @@
+import {
+  useCallback as rawUseCallback,
+  useDebugValue as rawUseDebugValue,
+  useDeferredValue as rawUseDeferredValue,
+  useEffect as rawUseEffect,
+  useId as rawUseId,
+  useImperativeHandle as rawUseImperativeHandle,
+  useInsertionEffect as rawUseInsertionEffect,
+  useLayoutEffect as rawUseLayoutEffect,
+  useMemo as rawUseMemo,
+  useReducer as rawUseReducer,
+  useRef as rawUseRef,
+  useState as rawUseState,
+  useSyncExternalStore as rawUseSyncExternalStore,
+  useTransition as rawUseTransition,
+} from "../features/hooks.js";
+import { useContext as rawUseContext } from "../features/context.js";
+import {
+  registerAfterComponentRenderHandler,
+  registerBeforeComponentRenderHandler,
+} from "../runtimeExtensions.js";
+
+const INVALID_HOOK_CALL_MESSAGE = [
+  "Invalid hook call. Hooks can only be called inside of the body of a function component.",
+  "This could happen for one of the following reasons:",
+  "1. You might have mismatching versions of React and the renderer (such as React DOM)",
+  "2. You might be breaking the Rules of Hooks",
+  "3. You might have more than one copy of React in the same app",
+  "See https://react.dev/link/invalid-hook-call for tips about how to debug and fix this problem.",
+].join("\n");
+
+export interface ReactCurrentDispatcherCompat {
+  current: RefractHookDispatcher | null;
+}
+
+export interface ReactSecretInternalsCompat {
+  ReactCurrentDispatcher: ReactCurrentDispatcherCompat;
+}
+
+export interface ReactClientInternalsCompat {
+  H: RefractHookDispatcher | null;
+  [key: string]: unknown;
+}
+
+type ExternalReactLike = {
+  __CLIENT_INTERNALS_DO_NOT_USE_OR_WARN_USERS_THEY_CANNOT_UPGRADE?: unknown;
+  __SECRET_INTERNALS_DO_NOT_USE_OR_YOU_WILL_BE_FIRED?: unknown;
+};
+
+export interface RefractHookDispatcher {
+  useState: typeof rawUseState;
+  useReducer: typeof rawUseReducer;
+  useRef: typeof rawUseRef;
+  useEffect: typeof rawUseEffect;
+  useLayoutEffect: typeof rawUseLayoutEffect;
+  useInsertionEffect: typeof rawUseInsertionEffect;
+  useMemo: typeof rawUseMemo;
+  useCallback: typeof rawUseCallback;
+  useContext: typeof rawUseContext;
+  useId: typeof rawUseId;
+  useSyncExternalStore: typeof rawUseSyncExternalStore;
+  useTransition: typeof rawUseTransition;
+  useDeferredValue: typeof rawUseDeferredValue;
+  useImperativeHandle: typeof rawUseImperativeHandle;
+  useDebugValue: typeof rawUseDebugValue;
+}
+
+const dispatcher: RefractHookDispatcher = {
+  useState: rawUseState,
+  useReducer: rawUseReducer,
+  useRef: rawUseRef,
+  useEffect: rawUseEffect,
+  useLayoutEffect: rawUseLayoutEffect,
+  useInsertionEffect: rawUseInsertionEffect,
+  useMemo: rawUseMemo,
+  useCallback: rawUseCallback,
+  useContext: rawUseContext,
+  useId: rawUseId,
+  useSyncExternalStore: rawUseSyncExternalStore,
+  useTransition: rawUseTransition,
+  useDeferredValue: rawUseDeferredValue,
+  useImperativeHandle: rawUseImperativeHandle,
+  useDebugValue: rawUseDebugValue,
+};
+
+const clientInternals: ReactClientInternalsCompat = {
+  H: null,
+  A: null,
+  T: null,
+  S: null,
+  actQueue: null,
+  asyncTransitions: 0,
+  isBatchingLegacy: false,
+  didScheduleLegacyUpdate: false,
+  didUsePromise: false,
+  thrownErrors: [],
+  getCurrentStack: null,
+  recentlyCreatedOwnerStacks: 0,
+};
+
+const secretInternals: ReactSecretInternalsCompat = {
+  ReactCurrentDispatcher: {
+    current: null,
+  },
+};
+
+const externalClientInternals = new Set<ReactClientInternalsCompat>();
+const externalSecretInternals = new Set<ReactSecretInternalsCompat>();
+const dispatcherStack: (RefractHookDispatcher | null)[] = [];
+
+let runtimeInitialized = false;
+
+export const __CLIENT_INTERNALS_DO_NOT_USE_OR_WARN_USERS_THEY_CANNOT_UPGRADE = clientInternals;
+export const __SECRET_INTERNALS_DO_NOT_USE_OR_YOU_WILL_BE_FIRED = secretInternals;
+
+export function resolveDispatcher(): RefractHookDispatcher {
+  const active = clientInternals.H ?? secretInternals.ReactCurrentDispatcher.current;
+  if (active == null) {
+    throw new Error(INVALID_HOOK_CALL_MESSAGE);
+  }
+  return active;
+}
+
+export function ensureHookDispatcherRuntime(): void {
+  if (runtimeInitialized) return;
+  runtimeInitialized = true;
+  registerBeforeComponentRenderHandler(beforeComponentRender);
+  registerAfterComponentRenderHandler(afterComponentRender);
+  tryAutoRegisterExternalReact();
+}
+
+export function registerExternalReactModule(moduleValue: unknown): void {
+  if (!moduleValue || typeof moduleValue !== "object") return;
+  const moduleRecord = moduleValue as ExternalReactLike;
+
+  const candidateClient = moduleRecord.__CLIENT_INTERNALS_DO_NOT_USE_OR_WARN_USERS_THEY_CANNOT_UPGRADE;
+  if (candidateClient && typeof candidateClient === "object" && "H" in (candidateClient as Record<string, unknown>)) {
+    externalClientInternals.add(candidateClient as ReactClientInternalsCompat);
+  }
+
+  const candidateSecret = moduleRecord.__SECRET_INTERNALS_DO_NOT_USE_OR_YOU_WILL_BE_FIRED;
+  const dispatcherHolder = candidateSecret as { ReactCurrentDispatcher?: unknown } | undefined;
+  if (
+    dispatcherHolder
+    && typeof dispatcherHolder === "object"
+    && dispatcherHolder.ReactCurrentDispatcher
+    && typeof dispatcherHolder.ReactCurrentDispatcher === "object"
+    && "current" in (dispatcherHolder.ReactCurrentDispatcher as Record<string, unknown>)
+  ) {
+    externalSecretInternals.add(candidateSecret as ReactSecretInternalsCompat);
+  }
+
+  syncDispatcherToExternal();
+}
+
+function beforeComponentRender(): void {
+  dispatcherStack.push(clientInternals.H);
+  setDispatcher(dispatcher);
+}
+
+function afterComponentRender(): void {
+  const previous = dispatcherStack.pop() ?? null;
+  setDispatcher(previous);
+}
+
+function setDispatcher(value: RefractHookDispatcher | null): void {
+  clientInternals.H = value;
+  secretInternals.ReactCurrentDispatcher.current = value;
+  syncDispatcherToExternal();
+}
+
+function syncDispatcherToExternal(): void {
+  for (const ext of externalClientInternals) {
+    ext.H = clientInternals.H;
+  }
+  for (const ext of externalSecretInternals) {
+    ext.ReactCurrentDispatcher.current = clientInternals.H;
+  }
+}
+
+function tryAutoRegisterExternalReact(): void {
+  const maybeRequire = getNodeRequire();
+  if (!maybeRequire) return;
+  try {
+    registerExternalReactModule(maybeRequire("react"));
+  } catch {
+    // External React module is optional.
+  }
+}
+
+function getNodeRequire(): ((id: string) => unknown) | null {
+  const globalRecord = globalThis as Record<string, unknown>;
+  const candidateRequire = globalRecord.require;
+  if (typeof candidateRequire === "function") {
+    return candidateRequire as (id: string) => unknown;
+  }
+
+  const nodeProcess = globalRecord.process as { mainModule?: { require?: (id: string) => unknown } } | undefined;
+  const mainModuleRequire = nodeProcess?.mainModule?.require;
+  if (typeof mainModuleRequire === "function") {
+    return mainModuleRequire.bind(nodeProcess?.mainModule);
+  }
+
+  try {
+    const dynamicRequire = Function("return typeof require === 'function' ? require : null")() as
+      | ((id: string) => unknown)
+      | null;
+    return dynamicRequire;
+  } catch {
+    return null;
+  }
+}

package/src/refract/coreRenderer.ts

@@ -2,9 +2,12 @@ import type { VNode, Fiber, Props } from "./types.js";
 import { PLACEMENT, UPDATE } from "./types.js";
 import { reconcileChildren } from "./reconcile.js";
 import { Fragment } from "./createElement.js";
+import { Portal } from "./portal.js";
 import { createDom, applyProps } from "./dom.js";
 import {
+  runAfterComponentRenderHandlers,
   runAfterCommitHandlers,
+  runBeforeComponentRenderHandlers,
   runCommitHandlers,
   runFiberCleanupHandlers,
   shouldBailoutComponent,
@@ -52,6 +55,7 @@ export function renderFiber(vnode: VNode, container: Node): void {
 function performWork(fiber: Fiber): void {
   const isComponent = typeof fiber.type === "function";
   const isFragment = fiber.type === Fragment;
+  const isPortal = fiber.type === Portal;
 
   if (isComponent) {
     if (fiber.alternate && fiber.flags === UPDATE && shouldBailoutComponent(fiber)) {
@@ -62,22 +66,32 @@ function performWork(fiber: Fiber): void {
     fiber._hookIndex = 0;
     if (!fiber.hooks) fiber.hooks = [];
 
-    const comp = fiber.type as (props: Props) => VNode;
+    const comp = fiber.type as (props: Props) => unknown;
+    runBeforeComponentRenderHandlers(fiber);
     try {
-      const children = [comp(fiber.props)];
+      const children = normalizeRenderedChildren(comp(fiber.props));
       reconcileChildren(fiber, children);
     } catch (error) {
       if (!tryHandleRenderError(fiber, error)) throw error;
+    } finally {
+      runAfterComponentRenderHandlers(fiber);
     }
   } else if (isFragment) {
-    reconcileChildren(fiber, fiber.props.children ?? []);
+    reconcileChildren(fiber, normalizeChildrenProp(fiber.props.children));
+  } else if (isPortal) {
+    const container = fiber.props.container;
+    if (!(container instanceof Node)) {
+      throw new TypeError("createPortal expects a valid DOM Node container");
+    }
+    fiber.dom = container;
+    reconcileChildren(fiber, normalizeChildrenProp(fiber.props.children));
   } else {
     if (!fiber.dom) {
       fiber.dom = createDom(fiber);
     }
     // Skip children when dangerouslySetInnerHTML is used
     if (!fiber.props.dangerouslySetInnerHTML) {
-      reconcileChildren(fiber, fiber.props.children ?? []);
+      reconcileChildren(fiber, normalizeChildrenProp(fiber.props.children));
     }
   }
 
@@ -90,6 +104,41 @@ function performWork(fiber: Fiber): void {
   advanceWork(fiber);
 }
 
+type RenderedChild = VNode | string | number | boolean | null | undefined | RenderedChild[];
+
+function normalizeRenderedChildren(rendered: unknown): VNode[] {
+  return flattenRenderedChildren([rendered as RenderedChild]);
+}
+
+function normalizeChildrenProp(children: unknown): VNode[] {
+  if (children === undefined) return [];
+  if (Array.isArray(children)) {
+    return flattenRenderedChildren(children as RenderedChild[]);
+  }
+  return flattenRenderedChildren([children as RenderedChild]);
+}
+
+function flattenRenderedChildren(raw: RenderedChild[]): VNode[] {
+  const result: VNode[] = [];
+  for (const child of raw) {
+    if (child == null || typeof child === "boolean") continue;
+    if (Array.isArray(child)) {
+      result.push(...flattenRenderedChildren(child));
+      continue;
+    }
+    if (typeof child === "string" || typeof child === "number") {
+      result.push({ type: "TEXT", props: { nodeValue: String(child) }, key: null });
+      continue;
+    }
+    result.push(child);
+  }
+  return result;
+}
+
+function isPortalFiber(fiber: Fiber): boolean {
+  return fiber.type === Portal;
+}
+
 function advanceWork(fiber: Fiber): void {
   let next: Fiber | null = fiber;
   while (next) {
@@ -105,6 +154,10 @@ function advanceWork(fiber: Fiber): void {
 function getNextDomSibling(fiber: Fiber): Node | null {
   let sib: Fiber | null = fiber.sibling;
   while (sib) {
+    if (isPortalFiber(sib)) {
+      sib = sib.sibling;
+      continue;
+    }
     // Skip any sibling that is itself being placed/moved
     if (sib.flags & PLACEMENT) {
       sib = sib.sibling;
@@ -125,6 +178,10 @@ function collectChildDomNodes(fiber: Fiber): Node[] {
   const nodes: Node[] = [];
   function walk(f: Fiber | null): void {
     while (f) {
+      if (isPortalFiber(f)) {
+        f = f.sibling;
+        continue;
+      }
       if (f.dom) {
         nodes.push(f.dom);
       } else {
@@ -139,6 +196,7 @@ function collectChildDomNodes(fiber: Fiber): Node[] {
 
 /** Get the first committed DOM node in a fiber subtree */
 function getFirstCommittedDom(fiber: Fiber): Node | null {
+  if (isPortalFiber(fiber)) return null;
   if (fiber.dom && !(fiber.flags & PLACEMENT)) return fiber.dom;
   let child = fiber.child;
   while (child) {
@@ -160,6 +218,13 @@ function commitRoot(rootFiber: Fiber): void {
 }
 
 function commitWork(fiber: Fiber): void {
+  if (isPortalFiber(fiber)) {
+    fiber.flags = 0;
+    if (fiber.child) commitWork(fiber.child);
+    if (fiber.sibling) commitWork(fiber.sibling);
+    return;
+  }
+
   let parentFiber = fiber.parent;
   while (parentFiber && !parentFiber.dom) {
     parentFiber = parentFiber.parent;
@@ -226,7 +291,13 @@ function commitDeletion(fiber: Fiber): void {
   if (fiber.dom && fiber.props.ref) {
     setRef(fiber.props.ref, null);
   }
-  if (fiber.dom) {
+  if (isPortalFiber(fiber)) {
+    let child: Fiber | null = fiber.child;
+    while (child) {
+      commitDeletion(child);
+      child = child.sibling;
+    }
+  } else if (fiber.dom) {
     fiber.dom.parentNode?.removeChild(fiber.dom);
   } else if (fiber.child) {
     // Fragment/component — delete children
@@ -289,3 +360,8 @@ function flushRenders(): void {
   }
   pendingContainers.clear();
 }
+
+export function flushPendingRenders(): void {
+  if (!flushScheduled) return;
+  flushRenders();
+}

package/src/refract/dom.ts

@@ -13,6 +13,8 @@ export type UnsafeUrlPropChecker = (key: string, value: unknown) => boolean;
 
 let htmlSanitizer: HtmlSanitizer = identitySanitizer;
 let unsafeUrlPropChecker: UnsafeUrlPropChecker = () => false;
+let reactCompatEventMode = false;
+const reactCompatWrappers = new WeakMap<EventListener, EventListener>();
 
 export function setHtmlSanitizer(sanitizer: HtmlSanitizer | null): void {
   htmlSanitizer = sanitizer ?? identitySanitizer;
@@ -22,10 +24,46 @@ export function setUnsafeUrlPropChecker(checker: UnsafeUrlPropChecker | null): v
   unsafeUrlPropChecker = checker ?? (() => false);
 }
 
+export function setReactCompatEventMode(enabled: boolean): void {
+  reactCompatEventMode = enabled;
+}
+
 function identitySanitizer(html: string): string {
   return html;
 }
 
+function getEventListener(handler: unknown): EventListener {
+  if (typeof handler !== "function") {
+    return handler as EventListener;
+  }
+  if (!reactCompatEventMode) {
+    return handler as EventListener;
+  }
+
+  const typedHandler = handler as EventListener;
+  const existing = reactCompatWrappers.get(typedHandler);
+  if (existing) return existing;
+
+  const wrapped: EventListener = (event: Event) => {
+    const eventRecord = event as unknown as Record<string, unknown>;
+    if (!("nativeEvent" in eventRecord)) {
+      try {
+        Object.defineProperty(event, "nativeEvent", {
+          configurable: true,
+          enumerable: false,
+          value: event,
+          writable: false,
+        });
+      } catch {
+        // ignore if event object is non-extensible
+      }
+    }
+    typedHandler(event);
+  };
+  reactCompatWrappers.set(typedHandler, wrapped);
+  return wrapped;
+}
+
 /** Create a real DOM node from a fiber */
 export function createDom(fiber: Fiber): Node {
   if (fiber.type === "TEXT") {
@@ -61,7 +99,7 @@ export function applyProps(
     if (key === "children" || key === "key" || key === "ref") continue;
     if (!(key in newProps)) {
       if (key.startsWith("on")) {
-        el.removeEventListener(key.slice(2).toLowerCase(), oldProps[key] as EventListener);
+        el.removeEventListener(key.slice(2).toLowerCase(), getEventListener(oldProps[key]));
       } else {
         el.removeAttribute(key);
       }
@@ -106,9 +144,9 @@ export function applyProps(
         if (key.startsWith("on")) {
           const event = key.slice(2).toLowerCase();
           if (oldProps[key]) {
-            el.removeEventListener(event, oldProps[key] as EventListener);
+            el.removeEventListener(event, getEventListener(oldProps[key]));
           }
-          el.addEventListener(event, newProps[key] as EventListener);
+          el.addEventListener(event, getEventListener(newProps[key]));
         } else {
           if (unsafeUrlPropChecker(key, newProps[key])) {
             el.removeAttribute(key);

package/src/refract/features/hooks.ts

@@ -1,6 +1,6 @@
 import type { Hook } from "../types.js";
 import { currentFiber, scheduleRender } from "../coreRenderer.js";
-import { markPendingEffects } from "../hooksRuntime.js";
+import { markPendingEffects, markPendingInsertionEffects, markPendingLayoutEffects } from "../hooksRuntime.js";
 
 function getHook(): Hook {
   const fiber = currentFiber!;
@@ -15,13 +15,15 @@ function getHook(): Hook {
   return hook;
 }
 
-export function useState<T>(initial: T): [T, (value: T | ((prev: T) => T)) => void] {
+export function useState<T>(initial: T | (() => T)): [T, (value: T | ((prev: T) => T)) => void] {
   const hook = getHook();
   const fiber = currentFiber!;
 
   // Initialize on first render
   if (hook.queue === undefined) {
-    hook.state = initial;
+    hook.state = typeof initial === "function"
+      ? (initial as () => T)()
+      : initial;
     hook.queue = [];
   }
 
@@ -72,6 +74,44 @@ export function useEffect(effect: () => EffectCleanup, deps?: unknown[]): void {
   }
 }
 
+export function useLayoutEffect(effect: () => EffectCleanup, deps?: unknown[]): void {
+  const hook = getHook() as EffectHook;
+  const fiber = currentFiber!;
+
+  if (hook.state === undefined) {
+    hook.state = { effect, deps, cleanup: undefined, pending: true };
+    markPendingLayoutEffects(fiber);
+  } else {
+    if (depsChanged(hook.state.deps, deps)) {
+      hook.state.effect = effect;
+      hook.state.deps = deps;
+      hook.state.pending = true;
+      markPendingLayoutEffects(fiber);
+    } else {
+      hook.state.pending = false;
+    }
+  }
+}
+
+export function useInsertionEffect(effect: () => EffectCleanup, deps?: unknown[]): void {
+  const hook = getHook() as EffectHook;
+  const fiber = currentFiber!;
+
+  if (hook.state === undefined) {
+    hook.state = { effect, deps, cleanup: undefined, pending: true };
+    markPendingInsertionEffects(fiber);
+  } else {
+    if (depsChanged(hook.state.deps, deps)) {
+      hook.state.effect = effect;
+      hook.state.deps = deps;
+      hook.state.pending = true;
+      markPendingInsertionEffects(fiber);
+    } else {
+      hook.state.pending = false;
+    }
+  }
+}
+
 interface RefHook extends Hook {
   state: { current: unknown };
 }
@@ -108,9 +148,25 @@ export function useCallback<T extends Function>(cb: T, deps: unknown[]): T {
 
 export function useReducer<S, A>(
   reducer: (state: S, action: A) => S,
-  initialState: S,
+  initialArg: S,
+): [S, (action: A) => void];
+
+export function useReducer<S, A, I>(
+  reducer: (state: S, action: A) => S,
+  initialArg: I,
+  init: (arg: I) => S,
+): [S, (action: A) => void];
+
+export function useReducer<S, A, I>(
+  reducer: (state: S, action: A) => S,
+  initialArg: S | I,
+  init?: (arg: I) => S,
 ): [S, (action: A) => void] {
-  const [state, setState] = useState(initialState);
+  const [state, setState] = useState<S>(() => (
+    init
+      ? init(initialArg as I)
+      : initialArg as S
+  ));
   const dispatch = (action: A) => {
     setState((prev) => reducer(prev, action));
   };
@@ -121,6 +177,74 @@ export function createRef<T = unknown>(): { current: T | null } {
   return { current: null };
 }
 
+let idCounter = 0;
+
+export function useId(): string {
+  const hook = getHook();
+  if (hook.state === undefined) {
+    hook.state = `:r${idCounter++}:`;
+  }
+  return hook.state as string;
+}
+
+export function useImperativeHandle<T>(
+  ref: { current: T | null } | ((value: T | null) => void) | null | undefined,
+  create: () => T,
+  deps?: unknown[],
+): void {
+  useLayoutEffect(() => {
+    const value = create();
+    if (typeof ref === "function") {
+      ref(value);
+      return () => ref(null);
+    }
+    if (ref && typeof ref === "object" && "current" in ref) {
+      ref.current = value;
+      return () => {
+        ref.current = null;
+      };
+    }
+    return;
+  }, deps);
+}
+
+export function useDebugValue(_value: unknown): void {
+  // no-op compatibility hook
+}
+
+export function startTransition(callback: () => void): void {
+  callback();
+}
+
+export function useTransition(): [boolean, (callback: () => void) => void] {
+  return [false, startTransition];
+}
+
+export function useDeferredValue<T>(value: T, _initialValue?: T): T {
+  return value;
+}
+
+export function useSyncExternalStore<T>(
+  subscribe: (onStoreChange: () => void) => () => void,
+  getSnapshot: () => T,
+  _getServerSnapshot?: () => T,
+): T {
+  const [snapshot, setSnapshot] = useState<T>(getSnapshot());
+
+  useEffect(() => {
+    const handleStoreChange = () => {
+      setSnapshot(getSnapshot());
+    };
+    const unsubscribe = subscribe(handleStoreChange);
+    handleStoreChange();
+    return () => {
+      unsubscribe();
+    };
+  }, [subscribe, getSnapshot]);
+
+  return snapshot;
+}
+
 export function useErrorBoundary(): [
   unknown,
   () => void,

package/src/refract/full.ts

@@ -3,8 +3,27 @@ export { render } from "./render.js";
 export { memo } from "./memo.js";
 export { setHtmlSanitizer } from "./features/security.js";
 export { setDevtoolsHook, DEVTOOLS_GLOBAL_HOOK } from "./devtools.js";
-export { useState, useEffect, useRef, useMemo, useCallback, useReducer, createRef, useErrorBoundary } from "./features/hooks.js";
+export {
+  useState,
+  useEffect,
+  useLayoutEffect,
+  useInsertionEffect,
+  useRef,
+  useMemo,
+  useCallback,
+  useReducer,
+  useSyncExternalStore,
+  useImperativeHandle,
+  useDebugValue,
+  useId,
+  useTransition,
+  startTransition,
+  useDeferredValue,
+  createRef,
+  useErrorBoundary,
+} from "./features/hooks.js";
 export { createContext, useContext } from "./features/context.js";
+export { createPortal } from "./portal.js";
 export type { VNode, Props, Component } from "./types.js";
 export type {
   RefractDevtoolsHook,

package/src/refract/hooks.ts

@@ -1,10 +1,19 @@
 export {
   useState,
   useEffect,
+  useLayoutEffect,
+  useInsertionEffect,
   useRef,
   useMemo,
   useCallback,
   useReducer,
+  useSyncExternalStore,
+  useImperativeHandle,
+  useDebugValue,
+  useId,
+  useTransition,
+  startTransition,
+  useDeferredValue,
   createRef,
   useErrorBoundary,
   depsChanged,