kiru 0.54.3 → 1.0.1

package/src/hooks/onBeforeMount.ts

@@ -0,0 +1,12 @@
+import { queueSetupEffect } from "./utils.js"
+
+/**
+ * Registers a callback that runs after the component is first mounted to the DOM, but before the DOM is painted.
+ * Optionally returns a cleanup function that will run when the component unmounts.
+ * Intended for use during component setup when the component returns a render function.
+ *
+ * @see https://kirujs.dev/docs/hooks/onBeforeMount
+ */
+export function onBeforeMount(fn: () => (() => void) | void): void {
+  queueSetupEffect(fn, { immediate: true })
+}

package/src/hooks/onCleanup.ts

@@ -0,0 +1,15 @@
+import { node } from "../globals.js"
+import { generateRandomID, registerVNodeCleanup } from "../utils/index.js"
+
+/**
+ * Registers a cleanup function that runs when the component unmounts.
+ * Intended for use during component setup when the component returns a render function.
+ *
+ * @see https://kirujs.dev/docs/hooks/onCleanup
+ */
+export function onCleanup(fn: () => void): void {
+  const vNode = node.current!
+  if (!vNode)
+    throw new Error("Cannot queue cleanup effect outside of a component")
+  registerVNodeCleanup(vNode, generateRandomID(10), fn)
+}

package/src/hooks/onMount.ts

@@ -0,0 +1,12 @@
+import { queueSetupEffect } from "./utils.js"
+
+/**
+ * Registers a callback that runs after the component is first mounted to the DOM.
+ * Optionally returns a cleanup function that will run when the component unmounts.
+ * Intended for use during component setup when the component returns a render function.
+ *
+ * @see https://kirujs.dev/docs/hooks/onMount
+ */
+export function onMount(fn: () => (() => void) | void): void {
+  queueSetupEffect(fn)
+}

package/src/hooks/utils.ts

@@ -1,242 +1,32 @@
-import { KiruError } from "../error.js"
-import { __DEV__ } from "../env.js"
-import { hookIndex, node } from "../globals.js"
-import { noop } from "../utils/index.js"
-import { requestUpdate } from "../scheduler.js"
-import { isHmrUpdate } from "../hmr.js"
-export {
-  cleanupHook,
-  depsRequireChange,
-  useHook,
-  useVNode,
-  useHookDebugGroup,
-  useRequestUpdate,
-  HookDebugGroupAction,
-  type HookState,
-  type HookCallback,
-  type HookCallbackContext as HookCallbackState,
-}
-
-type HookState<T> = Kiru.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 vNode = getVNodeOrError("useRequestUpdate")
-  return () => requestUpdate(vNode)
-}
-
-/**
- * Used to obtain the 'VNode' for the current component.
- */
-const useVNode = () => {
-  return getVNodeOrError("useVNode")
-}
-
-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: Kiru.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 = getVNodeOrError(hookName)
-
-  if (
-    __DEV__ &&
-    currentHookName !== null &&
-    !nestedHookWarnings.has(hookName + currentHookName)
-  ) {
-    nestedHookWarnings.add(hookName + currentHookName)
-    throw new KiruError({
-      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
+import { node } from "../globals.js"
+import { sideEffectsEnabled } from "../utils/index.js"
+
+export function queueSetupEffect(
+  effect: Kiru.LifecycleHookCallback,
+  opts?: { immediate?: boolean }
+): void {
+  if (!sideEffectsEnabled()) return
+  const vNode = node.current!
+  if (!vNode)
+    throw new Error("Cannot queue setup effect outside of a component")
+
+  const hooks = (vNode.hooks ??= {
+    pre: [],
+    preCleanups: [],
+    post: [],
+    postCleanups: [],
+  })
+
+  const [bag, cleanups] = opts?.immediate
+    ? [hooks.pre, hooks.preCleanups]
+    : [hooks.post, hooks.postCleanups]
+
+  const wrapped = () => {
+    const ret = effect()
+    if (typeof ret === "function") {
+      cleanups.push(ret)
     }
-    ;(vNode.effects ??= []).push(callback)
   }
 
-  const index = hookIndex.current++
-
-  let oldHook = 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(
-          `[kiru]: hooks must be called in the same order. Hook "${hookName}" was called in place of "${vNode.hookSig[index]}". Strange things may happen.`
-        )
-        oldHook?.cleanup?.()
-        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: isHmrUpdate(),
-        update: () => 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: () => requestUpdate(vNode),
-      queueEffect,
-      vNode,
-      index,
-    })
-    return res
-  } catch (error) {
-    throw error
-  }
-}
-
-function getVNodeOrError(hookName: string) {
-  const vNode = node.current
-  if (!vNode) {
-    throw new KiruError(
-      `Hook "${hookName}" must be used at the top level of a component or inside another composite hook.`
-    )
-  }
-  return vNode
-}
-
-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])))
-  )
+  bag.push(wrapped)
 }

package/src/index.ts

@@ -3,18 +3,26 @@ import { createKiruGlobalContext } from "./globalContext.js"
 export type * from "./types"
 export * from "./signals/index.js"
 export * from "./action.js"
-export * from "./appContext.js"
+export * from "./appHandle.js"
+export * from "./components/index.js"
 export * from "./context.js"
 export * from "./customEvents.js"
+export * from "./devtools.js"
 export * from "./element.js"
 export * from "./error.js"
 export * from "./hooks/index.js"
-export * from "./components/index.js"
+export type { ProfilingEvent, AppStats } from "./profiling.js"
 export * from "./renderToString.js"
-export { nextIdle, flushSync, requestUpdate } from "./scheduler.js"
-export * from "./store.js"
+export * from "./ref.js"
+export {
+  nextIdle,
+  flushSync,
+  requestUpdate,
+  useRequestUpdate,
+} from "./scheduler.js"
+export * from "./statefulPromise.js"
+export * from "./viewTransitions.js"
 
-// @ts-ignore
-if ("window" in globalThis && !globalThis.__KIRU_DEVTOOLS__) {
+if ("window" in globalThis) {
   globalThis.window.__kiru ??= createKiruGlobalContext()
 }

package/src/profiling.ts

@@ -1,4 +1,4 @@
-import type { AppContext } from "./appContext"
+import type { AppHandle } from "./appHandle"
 
 const MAX_TICKS = 100
 
@@ -13,27 +13,25 @@ const ProfilingEvents = [
 ] as const
 
 export type ProfilingEvent = (typeof ProfilingEvents)[number]
+export interface AppStats {
+  timestamps: TickTS[]
+  mountDuration: number
+  totalTicks: number
+}
 
 interface TickTS {
   start: number
   end: number
 }
 
-type ProfilingEventListener = (app: AppContext) => void
+type ProfilingEventListener = (app: AppHandle) => void
 
 export function createProfilingContext() {
   const eventListeners = new Map<ProfilingEvent, Set<ProfilingEventListener>>()
-  const appStats: Map<
-    AppContext,
-    {
-      timestamps: TickTS[]
-      mountDuration: number
-      totalTicks: number
-    }
-  > = new Map()
+  const appStats: Map<AppHandle, AppStats> = new Map()
   return {
     appStats,
-    emit: (event: ProfilingEvent, app: AppContext) => {
+    emit: (event: ProfilingEvent, app: AppHandle) => {
       eventListeners.get(event)?.forEach((listener) => listener(app))
     },
     addEventListener: (
@@ -52,23 +50,28 @@ export function createProfilingContext() {
       if (!eventListeners.has(event)) return
       eventListeners.get(event)!.delete(listener)
     },
-    mountDuration: (app: AppContext) => {
+    mountDuration: (app: AppHandle) => {
       const stats = appStats.get(app)
       if (!stats) return 0
       return stats.mountDuration
     },
-    totalTicks: (app: AppContext) => {
+    totalTicks: (app: AppHandle) => {
       const stats = appStats.get(app)
       if (!stats) return 0
       return stats.totalTicks
     },
-    lastTickDuration: (app: AppContext) => {
+    lastTickDuration: (app: AppHandle) => {
       const stats = appStats.get(app)
-      if (!stats) return 0
-      const last = stats.timestamps[stats.timestamps.length - 1]
+      if (!stats) return Infinity
+      let last = stats.timestamps[stats.timestamps.length - 1]
+      if (!last) return Infinity
+      if (last.end === Infinity) {
+        last = stats.timestamps[stats.timestamps.length - 2]
+      }
+      if (!last) return Infinity
       return last.end - last.start
     },
-    averageTickDuration: (app: AppContext) => {
+    averageTickDuration: (app: AppHandle) => {
       const stats = appStats.get(app)
       if (!stats) return 0
       const completeTicks = stats.timestamps.filter((ts) => ts.end !== Infinity)
@@ -77,7 +80,7 @@ export function createProfilingContext() {
         completeTicks.length
       )
     },
-    beginTick: (app: AppContext) => {
+    beginTick: (app: AppHandle) => {
       if (!appStats.has(app)) {
         appStats.set(app, {
           mountDuration: Infinity,
@@ -89,8 +92,7 @@ export function createProfilingContext() {
       stats.totalTicks++
       stats.timestamps.push({ start: performance.now(), end: Infinity })
     },
-    endTick: (app: AppContext) => {
-      if (!appStats.has(app)) return
+    endTick: (app: AppHandle) => {
       const stats = appStats.get(app)!
 
       const last = stats.timestamps[stats.timestamps.length - 1]

package/src/reconciler.ts

@@ -1,31 +1,26 @@
+import { $FRAGMENT, FLAG_PLACEMENT, FLAG_UPDATE } from "./constants.js"
 import {
-  $FRAGMENT,
-  FLAG_MEMO,
-  FLAG_PLACEMENT,
-  FLAG_UPDATE,
-} from "./constants.js"
-import {
-  getVNodeAppContext,
+  getVNodeApp,
   isElement,
   isValidTextChild,
   latest,
+  propsChanged,
 } from "./utils/index.js"
 import { Signal } from "./signals/base.js"
 import { __DEV__ } from "./env.js"
-import type { AppContext } from "./appContext.js"
-import { isMemoFn } from "./components/memo.js"
+import type { AppHandle } from "./appHandle.js"
 import { createVNode as createBaseVNode } from "./vNode.js"
 
 type VNode = Kiru.VNode
 type KElement = Kiru.Element
-let appCtx: AppContext
+let app: AppHandle
 
 export function reconcileChildren(
   parent: VNode,
   children: unknown
 ): VNode | null {
   if (__DEV__) {
-    appCtx = getVNodeAppContext(parent)!
+    app = getVNodeApp(parent)!
   }
   if (Array.isArray(children)) {
     if (__DEV__) {
@@ -238,7 +233,7 @@ function updateNode(parent: VNode, oldChild: VNode | null, newChild: KElement) {
     oldChild.index = 0
     oldChild.sibling = null
     if (typeof type === "string") {
-      if (propsChanged(oldChild.props, props)) {
+      if (domNodePropsChanged(oldChild.props, props)) {
         oldChild.flags |= FLAG_UPDATE
       }
     } else {
@@ -344,7 +339,7 @@ function updateFromMap(
         dev_emitUpdateNode()
       }
       if (typeof type === "string") {
-        if (propsChanged(oldChild.props, props)) {
+        if (domNodePropsChanged(oldChild.props, props)) {
           oldChild.flags |= FLAG_UPDATE
         }
       } else {
@@ -380,20 +375,9 @@ function updateFromMap(
   return null
 }
 
-function propsChanged(oldProps: VNode["props"], newProps: VNode["props"]) {
-  const aKeys = Object.keys(oldProps)
-  const bKeys = Object.keys(newProps)
-  if (aKeys.length !== bKeys.length) return true
-  for (let key of aKeys) {
-    if (key === "children" || key === "key") continue
-    if (oldProps[key] !== newProps[key]) return true
-  }
-  return false
-}
-
 function dev_emitUpdateNode() {
   if (!("window" in globalThis)) return
-  window.__kiru.profilingContext?.emit("updateNode", appCtx)
+  window.__kiru.profilingContext?.emit("updateNode", app)
 }
 
 const $LIST_CHILD = Symbol("kiru:marked-list-child")
@@ -495,12 +479,16 @@ function createVNode(
   const node = createBaseVNode(type, parent, props, key, index)
   node.flags |= FLAG_PLACEMENT
 
-  if (typeof type === "function" && isMemoFn(type)) {
-    node.flags |= FLAG_MEMO
-  }
-
   if (__DEV__ && "window" in globalThis) {
-    window.__kiru.profilingContext?.emit("createNode", appCtx)
+    window.__kiru.profilingContext?.emit("createNode", app)
   }
   return node
 }
+
+const IGNORED_DOM_NODE_PROPS = ["children", "key"]
+function domNodePropsChanged(
+  oldProps: Kiru.VNode["props"],
+  newProps: Kiru.VNode["props"]
+) {
+  return propsChanged(oldProps, newProps, IGNORED_DOM_NODE_PROPS)
+}

package/src/ref.ts

@@ -0,0 +1,6 @@
+export function ref<T>(initialValue: T): Kiru.RefObject<T>
+export function ref<T>(initialValue: T | null): Kiru.RefObject<T | null>
+export function ref<T = undefined>(): Kiru.RefObject<T | undefined>
+export function ref<T>(initialValue?: T | null) {
+  return { current: initialValue }
+}

package/src/renderToString.ts

@@ -1,6 +1,6 @@
 import { renderMode } from "./globals.js"
 import { Fragment } from "./element.js"
-import { headlessRender, HeadlessRenderContext } from "./recursiveRender.js"
+import { headlessRender, HeadlessRenderContext } from "./headlessRender.js"
 
 export function renderToString(element: JSX.Element) {
   const prev = renderMode.current

package/src/router/context.ts

@@ -1,6 +1,5 @@
-import { createContext } from "../context.js"
+import { createContext, useContext } from "../context.js"
 import { __DEV__ } from "../env.js"
-import { useContext } from "../hooks/index.js"
 import type { RouteQuery, RouterState } from "./types.js"
 
 export interface ReloadOptions {

package/src/router/fileRouter.ts

@@ -1,9 +1,9 @@
 import { createElement } from "../element.js"
-import { useState, useEffect } from "../hooks/index.js"
 import { RouterContext } from "./context.js"
 import { FileRouterController } from "./fileRouterController.js"
 import type { FileRouterConfig } from "./types.js"
 import { fileRouterInstance } from "./globals.js"
+import { onCleanup } from "../hooks/onCleanup.js"
 
 export interface FileRouterProps {
   /**
@@ -24,18 +24,28 @@ export interface FileRouterProps {
   config: FileRouterConfig
 }
 
-export function FileRouter({ config }: FileRouterProps): JSX.Element {
-  const [controller] = useState(() => {
-    fileRouterInstance.current?.dispose()
-    const router = (fileRouterInstance.current = new FileRouterController())
-    router.init(config)
-    return router
-  })
-  useEffect(() => () => controller.dispose(), [controller])
+export const FileRouter: Kiru.FC<FileRouterProps> = ({ config }) => {
+  fileRouterInstance.current?.dispose()
+  let router = (fileRouterInstance.current = new FileRouterController())
+  let configStr = ""
 
-  return createElement(
-    RouterContext.Provider,
-    { value: controller.contextValue },
-    controller.getChildren()
+  onCleanup(() => router.dispose())
+
+  const onUpdate = (props: FileRouterProps) => {
+    const newConfigStr = JSON.stringify(props.config)
+    if (newConfigStr !== configStr) {
+      config = props.config
+      configStr = newConfigStr
+      router.init(config)
+    }
+  }
+
+  return (nextProps) => (
+    onUpdate(nextProps),
+    createElement(
+      RouterContext,
+      { value: router.contextValue },
+      router.getChildren()
+    )
   )
 }