kiru 0.44.4

package/src/hooks/utils.ts

@@ -0,0 +1,259 @@
+import { KaiokenError } from "../error.js"
+import { __DEV__ } from "../env.js"
+import { ctx, hookIndex, node, nodeToCtxMap } from "../globals.js"
+import { getVNodeAppContext, noop } from "../utils.js"
+export { sideEffectsEnabled } from "../utils.js"
+export {
+  cleanupHook,
+  depsRequireChange,
+  useHook,
+  useVNode,
+  useAppContext,
+  useHookDebugGroup,
+  useRequestUpdate,
+  HookDebugGroupAction,
+  type HookState,
+  type HookCallback,
+  type HookCallbackContext as HookCallbackState,
+}
+
+type HookState<T> = Kaioken.Hook<T>
+
+enum HookDebugGroupAction {
+  Start = "start",
+  End = "end",
+}
+
+/**
+ * **dev only - this is a no-op in production.**
+ *
+ * Used to create 'groups' of hooks in the devtools.
+ * Useful for debugging and profiling.
+ */
+const useHookDebugGroup = (name: string, action: HookDebugGroupAction) => {
+  if (__DEV__) {
+    return useHook(
+      "devtools:useHookDebugGroup",
+      { displayName: name, action },
+      noop
+    )
+  }
+}
+
+/**
+ * Used obtain an 'requestUpdate' function for the current component.
+ */
+const useRequestUpdate = () => {
+  const n = node.current
+  if (!n) error_hookMustBeCalledTopLevel("useRequestUpdate")
+  const ctx = getVNodeAppContext(n)
+  return () => ctx.requestUpdate(n)
+}
+
+/**
+ * Used to obtain the 'AppContext' for the current component.
+ */
+const useAppContext = () => {
+  if (!node.current) error_hookMustBeCalledTopLevel("useAppContext")
+  const ctx = nodeToCtxMap.get(node.current)
+  if (!ctx)
+    error_hookMustBeCalledTopLevel(
+      "[kaioken]: unable to find node's AppContext"
+    )
+  return ctx
+}
+
+/**
+ * Used to obtain the 'VNode' for the current component.
+ */
+const useVNode = () => {
+  const n = node.current
+  if (!n) error_hookMustBeCalledTopLevel("useVNode")
+  return n
+}
+
+type HookCallbackContext<T> = {
+  /**
+   * The current state of the hook
+   */
+  hook: HookState<T>
+  /**
+   * Indicates if this is the first time the hook has been initialized
+   */
+  isInit: boolean
+  /**
+   * Dev mode only - indicates if the hook is being run as a result of a HMR update.
+   * This is the time to clean up the previous version of the hook if necessary, ie. initial arguments changed.
+   */
+  isHMR?: boolean
+  /**
+   * Queues the current component to be re-rendered
+   */
+  update: () => void
+  /**
+   * Queues an effect to be run, either immediately or on the next render
+   */
+  queueEffect: (callback: Function, opts?: { immediate?: boolean }) => void
+  /**
+   * The VNode associated with the current component
+   */
+  vNode: Kaioken.VNode
+  /**
+   * The index of the current hook.
+   * You can count on this being stable across renders,
+   * and unique across separate hooks in the same component.
+   */
+  index: number
+}
+type HookCallback<T> = (state: HookCallbackContext<T>) => any
+
+let currentHookName: string | null = null
+const nestedHookWarnings = new Set<string>()
+
+function useHook<
+  T extends () => Record<string, unknown>,
+  U extends HookCallback<ReturnType<T>>
+>(hookName: string, hookInitializer: T, callback: U): ReturnType<U>
+
+function useHook<T extends Record<string, unknown>, U extends HookCallback<T>>(
+  hookName: string,
+  hookData: T,
+  callback: U
+): ReturnType<U>
+
+function useHook<
+  T,
+  U extends T extends () => Record<string, unknown>
+    ? HookCallback<ReturnType<T>>
+    : HookCallback<T>
+>(
+  hookName: string,
+  hookDataOrInitializer: HookState<T> | (() => HookState<T>),
+  callback: U
+): ReturnType<U> {
+  const vNode = node.current
+  if (!vNode) error_hookMustBeCalledTopLevel(hookName)
+
+  if (__DEV__) {
+    if (
+      currentHookName !== null &&
+      !nestedHookWarnings.has(hookName + currentHookName)
+    ) {
+      nestedHookWarnings.add(hookName + currentHookName)
+      throw new KaiokenError({
+        message: `Nested primitive "useHook" calls are not supported. "${hookName}" was called inside "${currentHookName}". Strange will most certainly happen.`,
+        vNode,
+      })
+    }
+  }
+
+  const queueEffect = (callback: Function, opts?: { immediate?: boolean }) => {
+    if (opts?.immediate) {
+      ;(vNode.immediateEffects ??= []).push(callback)
+      return
+    }
+    ;(vNode.effects ??= []).push(callback)
+  }
+
+  const appCtx = ctx.current
+  const index = hookIndex.current++
+
+  let oldHook = (
+    vNode.prev ? vNode.prev.hooks?.at(index) : vNode.hooks?.at(index)
+  ) as HookState<T> | undefined
+
+  if (__DEV__) {
+    currentHookName = hookName
+
+    vNode.hooks ??= []
+    vNode.hookSig ??= []
+
+    if (!vNode.hookSig[index]) {
+      vNode.hookSig[index] = hookName
+    } else {
+      if (vNode.hookSig[index] !== hookName) {
+        console.warn(
+          `[kaioken]: hooks must be called in the same order. Hook "${hookName}" was called in place of "${vNode.hookSig[index]}". Strange things may happen.`
+        )
+        vNode.hooks.length = index
+        vNode.hookSig.length = index
+        oldHook = undefined
+      }
+    }
+
+    let hook: HookState<T>
+    if (!oldHook) {
+      hook =
+        typeof hookDataOrInitializer === "function"
+          ? hookDataOrInitializer()
+          : { ...hookDataOrInitializer }
+      hook.name = hookName
+    } else {
+      hook = oldHook
+    }
+
+    vNode.hooks[index] = hook
+
+    try {
+      const res = (callback as HookCallback<T>)({
+        hook,
+        isInit: !oldHook,
+        isHMR: vNode.hmrUpdated,
+        update: () => appCtx.requestUpdate(vNode),
+        queueEffect,
+        vNode,
+        index,
+      })
+      return res
+    } catch (error) {
+      throw error
+    } finally {
+      currentHookName = null
+    }
+  }
+
+  try {
+    const hook: HookState<T> =
+      oldHook ??
+      (typeof hookDataOrInitializer === "function"
+        ? hookDataOrInitializer()
+        : { ...hookDataOrInitializer })
+
+    vNode.hooks ??= []
+    vNode.hooks[index] = hook
+
+    const res = (callback as HookCallback<T>)({
+      hook,
+      isInit: !oldHook,
+      update: () => appCtx.requestUpdate(vNode),
+      queueEffect,
+      vNode,
+      index,
+    })
+    return res
+  } catch (error) {
+    throw error
+  }
+}
+
+function error_hookMustBeCalledTopLevel(hookName: string): never {
+  throw new KaiokenError(
+    `Hook "${hookName}" must be used at the top level of a component or inside another composite hook.`
+  )
+}
+
+function cleanupHook(hook: { cleanup?: () => void }) {
+  if (hook.cleanup) {
+    hook.cleanup()
+    hook.cleanup = undefined
+  }
+}
+
+function depsRequireChange(a?: unknown[], b?: unknown[]) {
+  return (
+    a === undefined ||
+    b === undefined ||
+    a.length !== b.length ||
+    (a.length > 0 && b.some((dep, i) => !Object.is(dep, a[i])))
+  )
+}

package/src/hydration.ts

@@ -0,0 +1,67 @@
+import type { MaybeDom, SomeDom } from "./types.utils"
+
+export const hydrationStack = {
+  parentStack: [] as Array<SomeDom>,
+  childIdxStack: [] as Array<number>,
+  eventDeferrals: new Map<Element, Array<() => void>>(),
+  parent: function () {
+    return this.parentStack[this.parentStack.length - 1]
+  },
+  clear: function () {
+    this.parentStack.length = 0
+    this.childIdxStack.length = 0
+  },
+  pop: function () {
+    this.parentStack.pop()
+    this.childIdxStack.pop()
+  },
+  push: function (el: SomeDom) {
+    this.parentStack.push(el)
+    this.childIdxStack.push(0)
+  },
+  currentChild: function () {
+    return this.parentStack[this.parentStack.length - 1].childNodes[
+      this.childIdxStack[this.childIdxStack.length - 1]
+    ]
+  },
+  nextChild: function () {
+    return this.parentStack[this.parentStack.length - 1].childNodes[
+      this.childIdxStack[this.childIdxStack.length - 1]++
+    ] as MaybeDom
+  },
+  bumpChildIndex: function () {
+    this.childIdxStack[this.childIdxStack.length - 1]++
+  },
+  captureEvents: function (element: Element) {
+    toggleEvtListeners(element, true)
+    this.eventDeferrals.set(element, [])
+  },
+  resetEvents: function (element: Element) {
+    this.eventDeferrals.delete(element)
+  },
+  releaseEvents: function (element: Element) {
+    toggleEvtListeners(element, false)
+    const events = this.eventDeferrals.get(element)
+    while (events?.length) events.shift()!()
+  },
+}
+
+const captureEvent = (e: Event) => {
+  const t = e.target
+  if (!e.isTrusted || !t) return
+  hydrationStack.eventDeferrals
+    .get(t as Element)
+    ?.push(() => t.dispatchEvent(e))
+}
+const toggleEvtListeners = (element: Element, value: boolean) => {
+  for (const key in element) {
+    if (key.startsWith("on")) {
+      const eventType = key.substring(2)
+      element[value ? "addEventListener" : "removeEventListener"](
+        eventType,
+        captureEvent,
+        { passive: true }
+      )
+    }
+  }
+}

package/src/index.ts

@@ -0,0 +1,61 @@
+import {
+  createAppContext,
+  type AppContext,
+  type AppContextOptions,
+} from "./appContext.js"
+import { ctx } from "./globals.js"
+import { createKaiokenGlobalContext } from "./globalContext.js"
+import { __DEV__ } from "./env.js"
+import { KaiokenError } from "./error.js"
+
+export type * from "./types"
+export * from "./appContext.js"
+export * from "./context.js"
+export * from "./cloneVNode.js"
+export * from "./element.js"
+export * from "./hooks/index.js"
+export * from "./lazy.js"
+export { memo } from "./memo.js"
+export * from "./portal.js"
+export * from "./renderToString.js"
+export * from "./signals/index.js"
+export * from "./store.js"
+export * from "./transition.js"
+
+if ("window" in globalThis) {
+  globalThis.window.__kaioken ??= createKaiokenGlobalContext()
+}
+
+export function mount<T extends Record<string, unknown>>(
+  appFunc: (props: T) => JSX.Element,
+  options: AppContextOptions,
+  appProps?: T
+): Promise<AppContext<T>>
+
+export function mount<T extends Record<string, unknown>>(
+  appFunc: (props: T) => JSX.Element,
+  root: HTMLElement,
+  appProps?: T
+): Promise<AppContext<T>>
+
+export function mount<T extends Record<string, unknown>>(
+  appFunc: (props: T) => JSX.Element,
+  optionsOrRoot: HTMLElement | AppContextOptions,
+  appProps = {} as T
+): Promise<AppContext<T>> {
+  let root: HTMLElement, opts: AppContextOptions | undefined
+  if (optionsOrRoot instanceof HTMLElement) {
+    root = optionsOrRoot
+    opts = { root }
+  } else {
+    opts = optionsOrRoot
+    root = optionsOrRoot.root!
+    if (__DEV__) {
+      if (!(root instanceof HTMLElement)) {
+        throw new KaiokenError("Root node must be an HTMLElement")
+      }
+    }
+  }
+  ctx.current = createAppContext<T>(appFunc, appProps, opts)
+  return ctx.current.mount()
+}

package/src/jsx.ts

@@ -0,0 +1,11 @@
+import { createElement, Fragment } from "./element.js"
+
+export { jsx, jsx as jsxs, jsx as jsxDEV, Fragment }
+
+function jsx(
+  type: Kaioken.VNode["type"],
+  { children, ...props } = {} as { children?: Kaioken.VNode[] }
+) {
+  if (!children) return createElement(type, props)
+  return createElement(type, props, children)
+}

package/src/lazy.ts

@@ -0,0 +1,238 @@
+import { createElement } from "./element.js"
+import { __DEV__ } from "./env.js"
+import { KaiokenError } from "./error.js"
+import { node, renderMode } from "./globals.js"
+import { useContext } from "./hooks/useContext.js"
+import { useRef } from "./hooks/useRef.js"
+import { useAppContext, useRequestUpdate } from "./hooks/utils.js"
+import { hydrationStack } from "./hydration.js"
+import {
+  HYDRATION_BOUNDARY_MARKER,
+  HydrationBoundaryContext,
+} from "./ssr/hydrationBoundary.js"
+import type { SomeDom } from "./types.utils"
+import { noop } from "./utils.js"
+
+type FCModule = { default: Kaioken.FC<any> }
+type LazyImportValue = Kaioken.FC<any> | FCModule
+type InferLazyImportProps<T extends LazyImportValue> = T extends FCModule
+  ? Kaioken.InferProps<T["default"]>
+  : Kaioken.InferProps<T>
+
+type LazyState = {
+  fn: string
+  promise: Promise<LazyImportValue>
+  result: Kaioken.FC | null
+}
+
+type LazyComponentProps<T extends LazyImportValue> = InferLazyImportProps<T> & {
+  fallback?: JSX.Element
+}
+
+const lazyCache: Map<string, LazyState> =
+  "window" in globalThis
+    ? // @ts-ignore - we're shamefully polluting the global scope here and hiding it 🥲
+      (window.__KAIOKEN_LAZY_CACHE ??= new Map<string, LazyState>())
+    : new Map<string, LazyState>()
+
+function consumeHydrationBoundaryChildren(parentNode: Kaioken.VNode): {
+  parent: HTMLElement
+  childNodes: Node[]
+  startIndex: number
+} {
+  const boundaryStart = hydrationStack.currentChild()
+  if (
+    boundaryStart?.nodeType !== Node.COMMENT_NODE ||
+    boundaryStart.nodeValue !== HYDRATION_BOUNDARY_MARKER
+  ) {
+    throw new KaiokenError({
+      message:
+        "Invalid HydrationBoundary node. This is likely a bug in Kaioken.",
+      fatal: true,
+      vNode: parentNode,
+    })
+  }
+  const parent = boundaryStart.parentElement!
+  const childNodes: Node[] = []
+  const isBoundaryEnd = (n: Node) => {
+    return (
+      n.nodeType === Node.COMMENT_NODE &&
+      n.nodeValue === "/" + HYDRATION_BOUNDARY_MARKER
+    )
+  }
+  let n = boundaryStart.nextSibling
+  boundaryStart.remove()
+  const startIndex =
+    hydrationStack.childIdxStack[hydrationStack.childIdxStack.length - 1]
+  while (n && !isBoundaryEnd(n)) {
+    childNodes.push(n)
+    hydrationStack.bumpChildIndex()
+    n = n.nextSibling
+  }
+  const boundaryEnd = hydrationStack.currentChild()
+  if (!isBoundaryEnd(boundaryEnd)) {
+    throw new KaiokenError({
+      message:
+        "Invalid HydrationBoundary node. This is likely a bug in Kaioken.",
+      fatal: true,
+      vNode: parentNode,
+    })
+  }
+  boundaryEnd.remove()
+  return { parent, childNodes, startIndex }
+}
+
+export function lazy<T extends LazyImportValue>(
+  componentPromiseFn: () => Promise<T>
+): Kaioken.FC<LazyComponentProps<T>> {
+  function LazyComponent(props: LazyComponentProps<T>) {
+    const { fallback = null, ...rest } = props
+    const appCtx = useAppContext()
+    const hydrationCtx = useContext(HydrationBoundaryContext, false)
+    const needsHydration = useRef(
+      hydrationCtx && renderMode.current === "hydrate"
+    )
+    const abortHydration = useRef(noop)
+    const requestUpdate = useRequestUpdate()
+    if (renderMode.current === "string" || renderMode.current === "stream") {
+      return fallback
+    }
+
+    const fn = componentPromiseFn.toString()
+    const withoutQuery = removeQueryString(fn)
+    const cachedState = lazyCache.get(withoutQuery)
+    if (!cachedState || cachedState.fn !== fn) {
+      const promise = componentPromiseFn()
+      const state: LazyState = {
+        fn,
+        promise,
+        result: null,
+      }
+      lazyCache.set(withoutQuery, state)
+
+      const ready = promise.then((componentOrModule) => {
+        state.result =
+          typeof componentOrModule === "function"
+            ? componentOrModule
+            : componentOrModule.default
+      })
+
+      if (!needsHydration.current) {
+        ready.then(() => requestUpdate())
+        return fallback
+      }
+
+      const thisNode = node.current!
+
+      abortHydration.current = () => {
+        for (const child of childNodes) {
+          if (child instanceof Element) {
+            hydrationStack.resetEvents(child)
+          }
+          child.parentNode?.removeChild(child)
+        }
+        needsHydration.current = false
+        delete thisNode.lastChildDom
+      }
+
+      if (__DEV__) {
+        window.__kaioken?.HMRContext?.onHmr(() => {
+          if (needsHydration.current) {
+            abortHydration.current()
+          }
+        })
+      }
+
+      const { parent, childNodes, startIndex } =
+        consumeHydrationBoundaryChildren(thisNode)
+
+      thisNode.lastChildDom = childNodes[childNodes.length - 1] as SomeDom
+
+      for (const child of childNodes) {
+        if (child instanceof Element) {
+          hydrationStack.captureEvents(child)
+        }
+      }
+      const hydrate = () => {
+        if (needsHydration.current === false) return
+
+        appCtx.scheduler?.nextIdle(() => {
+          delete thisNode.lastChildDom
+          needsHydration.current = false
+          hydrationStack.push(parent)
+          hydrationStack.childIdxStack[
+            hydrationStack.childIdxStack.length - 1
+          ] = startIndex
+          const prev = renderMode.current
+          /**
+           * must call requestUpdate before setting renderMode
+           * to hydrate, otherwise the update will be postponed
+           * and flushSync will have no effect
+           */
+          requestUpdate()
+          renderMode.current = "hydrate"
+          appCtx.flushSync()
+          renderMode.current = prev
+          for (const child of childNodes) {
+            if (child instanceof Element) {
+              hydrationStack.releaseEvents(child)
+            }
+          }
+        })
+      }
+
+      /**
+       * once the promise resolves, we need to act according
+       * to the HydrationBoundaryContext 'mode'.
+       *
+       * - with 'eager', we just hydrate the children immediately
+       * - with 'lazy', we'll wait for user interaction before hydrating
+       */
+
+      if (hydrationCtx.mode === "eager") {
+        ready.then(hydrate)
+        return null
+      }
+      const interactionEvents = hydrationCtx.events
+      const onInteraction = (e: Event) => {
+        const tgt = e.target
+        if (
+          tgt instanceof Element &&
+          childNodes.some((child) => child.contains(tgt))
+        ) {
+          interactionEvents.forEach((evtName) => {
+            window.removeEventListener(evtName, onInteraction)
+          })
+          ready.then(hydrate)
+        }
+      }
+      interactionEvents.forEach((evtName) => {
+        window.addEventListener(evtName, onInteraction)
+      })
+
+      return null
+    }
+
+    if (cachedState.result === null) {
+      cachedState.promise.then(requestUpdate)
+      return fallback
+    }
+    if (needsHydration.current) {
+      abortHydration.current()
+    }
+    return createElement(cachedState.result, rest)
+  }
+  LazyComponent.displayName = "Kaioken.lazy"
+  return LazyComponent
+}
+
+/**
+ * removes the query string from a function - prevents
+ * vite-modified imports (eg. () => import("./Counter.tsx?t=123456"))
+ * from causing issues
+ */
+const removeQueryString = (fnStr: string): string =>
+  fnStr.replace(
+    /import\((["'])([^?"']+)\?[^)"']*\1\)/g,
+    (_, quote, path) => `import(${quote}${path}${quote})`
+  )

package/src/memo.ts

@@ -0,0 +1,48 @@
+import { $MEMO } from "./constants.js"
+import { createElement } from "./element.js"
+import { __DEV__ } from "./env.js"
+
+function _arePropsEqual<T extends Record<string, unknown>>(
+  prevProps: T,
+  nextProps: T
+) {
+  const keys = new Set([...Object.keys(prevProps), ...Object.keys(nextProps)])
+  for (const key of keys) {
+    if (prevProps[key] !== nextProps[key]) {
+      return false
+    }
+  }
+  return true
+}
+
+export type MemoFn = Function & {
+  [$MEMO]: {
+    arePropsEqual: (
+      prevProps: Record<string, unknown>,
+      nextProps: Record<string, unknown>
+    ) => boolean
+  }
+}
+
+export function memo<T extends Record<string, unknown> = {}>(
+  fn: Kaioken.FC<T>,
+  arePropsEqual: (prevProps: T, nextProps: T) => boolean = _arePropsEqual
+): (props: T) => JSX.Element {
+  return Object.assign(
+    function Memo(props: T) {
+      return createElement(fn, props)
+    },
+    {
+      [$MEMO]: { arePropsEqual },
+      displayName: "Kaioken.memo",
+    }
+  )
+}
+
+export function isMemoFn(fn: any): fn is MemoFn {
+  return (
+    typeof fn === "function" &&
+    fn[$MEMO] &&
+    typeof fn[$MEMO].arePropsEqual === "function"
+  )
+}