kiru 0.54.4 → 1.0.1

package/src/signals/tracking.ts

@@ -0,0 +1,69 @@
+import { node } from "../globals.js"
+import { sideEffectsEnabled } from "../utils/index.js"
+import { effectQueue } from "./globals.js"
+import { tick } from "./utils.js"
+import type { Signal } from "./base.js"
+import type { SignalValues } from "./types.js"
+
+export const tracking = {
+  enabled: true,
+  stack: new Array<Map<string, Signal<unknown>>>(),
+  current: function (): Map<string, Signal<unknown>> | undefined {
+    return this.stack[this.stack.length - 1]
+  },
+}
+
+type TrackedExecutionContext<T, Deps extends readonly Signal<unknown>[]> = {
+  id: string
+  subs: Map<string, Function>
+  fn: (...values: SignalValues<Deps>) => T
+  deps?: Deps
+  onDepChanged: () => void
+}
+
+/**
+ * Executes an effect function with dependency tracking enabled, and manages
+ * the effect's subscriptions.
+ * @param ctx - The execution context
+ * @returns The result of the effect function
+ */
+export function executeWithTracking<T, Deps extends readonly Signal<unknown>[]>(
+  ctx: TrackedExecutionContext<T, Deps>
+): T {
+  const { id, subs, fn, deps = [], onDepChanged } = ctx
+  let observations: Map<string, Signal<unknown>> | undefined
+
+  effectQueue.delete(id)
+  const isServer = !!node.current && !sideEffectsEnabled()
+
+  if (!isServer) {
+    observations = new Map<string, Signal<unknown>>()
+    tracking.stack.push(observations)
+  }
+
+  const result = fn(...(deps.map((s) => s.value) as SignalValues<Deps>))
+
+  if (!isServer) {
+    for (const [id, unsub] of subs) {
+      if (observations!.has(id)) continue
+      unsub()
+      subs.delete(id)
+    }
+
+    const effect = () => {
+      if (!effectQueue.size) {
+        queueMicrotask(tick)
+      }
+      effectQueue.set(id, onDepChanged)
+    }
+
+    for (const [id, sig] of observations!) {
+      if (subs.has(id)) continue
+      const unsub = sig.subscribe(effect)
+      subs.set(id, unsub)
+    }
+    tracking.stack.pop()
+  }
+
+  return result
+}

package/src/signals/types.ts

@@ -7,7 +7,7 @@ export type SignalSubscriber<T = unknown> = (value: T, prevValue?: T) => void
 
 export type SignalValues<T extends readonly Signal<unknown>[]> = {
   [I in keyof T]: T[I] extends Signal<infer V>
-    ? V extends Kiru.StatefulPromise<infer P>
+    ? V extends Kiru.StatefulPromiseBase<infer P>
       ? P
       : V
     : never

package/src/signals/utils.ts

@@ -1,13 +1,21 @@
 import { call } from "../utils/index.js"
 import { Signal } from "./base.js"
 import { effectQueue } from "./globals.js"
+import { tracking } from "./tracking.js"
 
 export function unwrap<T>(value: T | Signal<T>, reactive = false): T {
   if (!Signal.isSignal(value)) return value
   return reactive ? value.value : value.peek()
 }
 
-export const tick = () => {
+export function tick() {
   effectQueue.forEach(call)
   effectQueue.clear()
 }
+
+export function untrack<T>(fn: () => T) {
+  tracking.enabled = false
+  const result = fn()
+  tracking.enabled = true
+  return result
+}

package/src/ssr/client.ts

@@ -1,9 +1,9 @@
-import type { AppContext, AppContextOptions } from "../appContext"
+import type { AppHandle, AppHandleOptions } from "../appHandle"
 import { hydrationStack } from "../hydration.js"
 import { hydrationMode, renderMode } from "../globals.js"
 import { mount } from "../index.js"
 
-interface HydrationAppContextOptions extends AppContextOptions {
+interface AppHandleHydrationOptions extends AppHandleOptions {
   /**
    * Configures the hydration mode
    * - "static": SSG
@@ -16,8 +16,8 @@ interface HydrationAppContextOptions extends AppContextOptions {
 export function hydrate(
   children: JSX.Element,
   container: HTMLElement,
-  options?: HydrationAppContextOptions
-): AppContext {
+  options?: AppHandleHydrationOptions
+): AppHandle {
   hydrationStack.clear()
 
   const prevRenderMode = renderMode.current

package/src/ssr/server.ts

@@ -2,7 +2,7 @@ import { Readable } from "node:stream"
 import { Fragment } from "../element.js"
 import { renderMode } from "../globals.js"
 import { STREAMED_DATA_EVENT } from "../constants.js"
-import { headlessRender, HeadlessRenderContext } from "../recursiveRender.js"
+import { headlessRender, HeadlessRenderContext } from "../headlessRender.js"
 
 const STREAMED_DATA_SETUP = `
 <script type="text/javascript">
@@ -26,7 +26,7 @@ export function renderToReadableStream(element: JSX.Element): {
 } {
   const stream = new Readable({ read() {} })
   const rootNode = Fragment({ children: element })
-  const streamPromises = new Set<Kiru.StatefulPromise<unknown>>()
+  const streamPromises = new Set<Kiru.StatefulPromiseBase<unknown>>()
   const pendingWritePromises: Promise<void>[] = []
 
   let immediate = ""

package/src/statefulPromise.ts

@@ -0,0 +1,136 @@
+import { $STREAM_DATA, STREAMED_DATA_EVENT } from "./constants.js"
+import { hydrationMode, node, renderMode } from "./globals.js"
+import { Signal, signal } from "./signals/base.js"
+import { getVNodeId } from "./utils/vdom.js"
+import { onCleanup } from "./hooks/onCleanup.js"
+
+export interface StreamDataThrowValue {
+  [$STREAM_DATA]: {
+    fallback?: JSX.Element
+    data: Kiru.StatefulPromiseBase<unknown>[]
+  }
+}
+
+/**
+ * Returns true if the value is a {@link StreamDataThrowValue}
+ */
+export function isStreamDataThrowValue(
+  value: unknown
+): value is StreamDataThrowValue {
+  return typeof value === "object" && !!value && $STREAM_DATA in value
+}
+
+/**
+ * Returns true if the value is a {@link Kiru.StatefulPromiseBase}
+ */
+export function isStatefulPromise(
+  thing: unknown
+): thing is Kiru.StatefulPromiseBase<unknown> {
+  return thing instanceof Promise && "id" in thing && "state" in thing
+}
+
+const nodeToPromiseIndex = new WeakMap<Kiru.VNode, number>()
+
+type StatefulPromise<T> = Kiru.StatefulPromiseBase<T> & {
+  isPending: Signal<boolean>
+}
+
+export function statefulPromise<T>(
+  callback: (signal: AbortSignal) => Promise<T>
+): StatefulPromise<T> {
+  const vNode = node.current!
+  if (!vNode) {
+    throw new Error("statefulPromise must be called inside a Kiru component")
+  }
+  const id = getVNodeId(vNode)
+  const isPending = signal(true)
+
+  isPending.value = true
+
+  const controller = new AbortController()
+  onCleanup(() => controller.abort())
+
+  const index = nodeToPromiseIndex.get(vNode) ?? 0
+  nodeToPromiseIndex.set(vNode, index + 1)
+
+  const promiseId = `${id}:data:${index}`
+
+  let promise: Promise<T>
+  if (renderMode.current === "string") {
+    // if we're rendering to a string, there's no need to fire the callback
+    promise = Promise.resolve() as Promise<T>
+  } else if (
+    renderMode.current === "hydrate" &&
+    hydrationMode.current === "dynamic"
+  ) {
+    // if we're hydrating and the hydration mode is not static,
+    // we need to resolve the promise from cache/event
+    promise = resolveDeferredPromise<T>(promiseId, controller.signal)
+  } else {
+    // dom / stream / (hydrate + static)
+    promise = callback(controller.signal)
+  }
+
+  const state: Kiru.PromiseState<T> = {
+    id: promiseId,
+    state: "pending",
+  }
+  const statefulPromise: Kiru.StatefulPromiseBase<T> = Object.assign(
+    promise,
+    state
+  )
+
+  statefulPromise
+    .then((value) => {
+      statefulPromise.state = "fulfilled"
+      statefulPromise.value = value
+      isPending.value = false
+    })
+    .catch((error) => {
+      statefulPromise.state = "rejected"
+      statefulPromise.error = error instanceof Error ? error : new Error(error)
+    })
+
+  return Object.assign(statefulPromise, { isPending })
+}
+
+interface DeferredPromiseEventDetail<T> {
+  id: string
+  data?: T
+  error?: string
+}
+
+function resolveDeferredPromise<T>(
+  id: string,
+  signal: AbortSignal
+): Promise<T> {
+  return new Promise<T>((resolve, reject) => {
+    const deferralCache: Map<string, { data?: T; error?: string }> = // @ts-ignore
+      (window[STREAMED_DATA_EVENT] ??= new Map())
+
+    const existing = deferralCache.get(id)
+    if (existing) {
+      const { data, error } = existing
+      deferralCache.delete(id)
+      if (error) return reject(error)
+      return resolve(data!)
+    }
+
+    const onDataEvent = (event: Event) => {
+      const { detail } = event as CustomEvent<DeferredPromiseEventDetail<T>>
+      if (detail.id === id) {
+        deferralCache.delete(id)
+        window.removeEventListener(STREAMED_DATA_EVENT, onDataEvent)
+        const { data, error } = detail
+        if (error) return reject(error)
+        resolve(data!)
+      }
+    }
+
+    window.addEventListener(STREAMED_DATA_EVENT, onDataEvent)
+    signal.addEventListener("abort", () => {
+      window.removeEventListener(STREAMED_DATA_EVENT, onDataEvent)
+      reject()
+    })
+  })
+}

package/src/types.dom.ts

@@ -598,17 +598,13 @@ interface PopoverControlAttributes {
   popoverTargetAction?: "show" | "hide" | "toggle"
 }
 
-declare class DoNotUseBindWithPlainError extends Error {
-  $brand: "DoNotUseBindWithPlainError"
-}
-
 type BindableProp<K extends string, V> =
   | ({
-      [k in K]?: Signalable<V>
-    } & { [k in `bind:${K}`]?: DoNotUseBindWithPlainError })
+      [k in K]?: Signalable<V | undefined>
+    } & { [k in `bind:${K}`]?: never })
   | ({
-      [k in `bind:${K}`]?: Signal<V>
-    } & { [k in K]?: DoNotUseBindWithPlainError })
+      [k in `bind:${K}`]?: Signal<V | undefined>
+    } & { [k in K]?: never })
 
 type MediaElementBindableProps = BindableProp<"volume", number> &
   BindableProp<"playbackRate", number> &

package/src/types.ts

@@ -1,10 +1,5 @@
 import type { ReadonlySignal, Signal as SignalClass } from "./signals"
-import type {
-  $CONTEXT,
-  $CONTEXT_PROVIDER,
-  $ERROR_BOUNDARY,
-  $FRAGMENT,
-} from "./constants"
+import type { $CONTEXT, $ERROR_BOUNDARY, $FRAGMENT } from "./constants"
 import type { KiruGlobalContext } from "./globalContext"
 import type {
   GlobalAttributes,
@@ -22,7 +17,7 @@ import type {
   Signalable,
   SomeDom,
 } from "./types.utils"
-import type { AppContext } from "./appContext"
+import type { AppHandle } from "./appHandle"
 
 export type { AsyncTaskState, ElementProps, Prettify, Signalable, StyleObject }
 
@@ -32,24 +27,26 @@ type ElementProps<T extends keyof JSX.IntrinsicElements> =
 type SignalableHtmlElementAttributes<Tag extends keyof HtmlElementAttributes> =
   {
     [K in keyof HtmlElementAttributes[Tag]]: Signalable<
-      HtmlElementAttributes[Tag][K]
+      HtmlElementAttributes[Tag][K] | undefined
     >
   } & (Tag extends keyof HtmlElementBindableProps
     ? HtmlElementBindableProps[Tag]
     : {})
 type SignalableSvgElementAttributes<Tag extends keyof SvgElementAttributes> = {
   [K in keyof SvgElementAttributes[Tag]]: Signalable<
-    SvgElementAttributes[Tag][K]
+    SvgElementAttributes[Tag][K] | undefined
   >
 }
 type SignalableAriaProps = {
-  [K in keyof ARIAMixin]?: Signalable<ARIAMixin[K]>
+  [K in keyof ARIAMixin]?: Signalable<ARIAMixin[K] | undefined>
 }
 type SignalableGlobalAttributes = {
-  [K in keyof GlobalAttributes]: Signalable<GlobalAttributes[K]>
+  [K in keyof GlobalAttributes]: Signalable<GlobalAttributes[K] | undefined>
 }
 type SignalableSvgGlobalAttributes = {
-  [K in keyof SvgGlobalAttributes]: Signalable<SvgGlobalAttributes[K]>
+  [K in keyof SvgGlobalAttributes]: Signalable<
+    SvgGlobalAttributes[K] | undefined
+  >
 }
 
 type ElementMap = {
@@ -58,10 +55,7 @@ type ElementMap = {
     SignalableAriaProps &
     Kiru.EventAttributes<HTMLTagToElement<Tag>> &
     JSX.ElementAttributes & {
-      ref?:
-        | Kiru.Ref<HTMLTagToElement<Tag> | null>
-        | SignalClass<HTMLTagToElement<Tag> | null>
-        | null
+      ref?: Kiru.Ref<Element | null> | SignalClass<Element | null> | null
     }
 } & {
   [Tag in keyof SvgElementAttributes]: SignalableSvgElementAttributes<Tag> &
@@ -70,10 +64,7 @@ type ElementMap = {
     SignalableAriaProps &
     Kiru.EventAttributes<SVGTagToElement<Tag>> &
     JSX.ElementAttributes & {
-      ref?:
-        | Kiru.Ref<SVGTagToElement<Tag> | null>
-        | SignalClass<SVGTagToElement<Tag> | null>
-        | null
+      ref?: Kiru.Ref<Element | null> | SignalClass<Element | null> | null
     }
 } & {
   [Tag in `${string}-${string}`]: Record<string, any>
@@ -108,6 +99,7 @@ declare global {
       | Kiru.Element
       | PrimitiveChild
       | Kiru.Signal<PrimitiveChild>
+      | Kiru.FC<any>
 
     interface ElementAttributes {
       key?: JSX.ElementKey
@@ -121,42 +113,25 @@ declare global {
   namespace Kiru {
     interface CustomEvents {}
 
-    interface ProviderProps<T> {
+    interface ContextProps<T> {
       value: T
-      children?: JSX.Children | ((value: T) => JSX.Element)
+      children?: JSX.Children
     }
-    interface Context<T> {
-      [$CONTEXT]: true
-      Provider: (({ value, children }: ProviderProps<T>) => JSX.Element) & {
-        displayName?: string
-      }
-      default: () => T
-      /** Used to display the name of the context in devtools  */
-      displayName?: string
+
+    interface Context<T> extends Kiru.FC<ContextProps<T>> {
+      [$CONTEXT]: () => T
     }
 
-    interface FC<T = {}> {
-      (props: FCProps<T>): JSX.Element
+    export interface FC<T = {}> {
+      (props: T):
+        | Exclude<JSX.Element, Kiru.FC<any>>
+        | ((props: T) => JSX.Element)
       /** Used to display the name of the component in devtools  */
       displayName?: string
     }
 
-    type FCProps<T = {}> = T & { children?: JSX.Children }
     type InferProps<T> = T extends Kiru.FC<infer P> ? P : never
 
-    interface HookDevtoolsProvisions<T extends Record<string, any>> {
-      get: () => T
-      set?: (value: T) => void
-    }
-    type Hook<T> = T & {
-      cleanup?: () => void
-      name?: string
-      dev?: {
-        /** Used to perform invalidation during HMR when the hook's arguments have changed */
-        initialArgs?: any
-        devtools?: HookDevtoolsProvisions<any>
-      }
-    }
     interface RefObject<T> {
       current: T
     }
@@ -173,7 +148,7 @@ declare global {
       error?: Error
     }
 
-    interface StatefulPromise<T> extends Promise<T>, PromiseState<T> {}
+    interface StatefulPromiseBase<T> extends Promise<T>, PromiseState<T> {}
 
     type RenderMode = "dom" | "hydrate" | "string" | "stream"
 
@@ -183,7 +158,7 @@ declare global {
 
     type ExoticSymbol =
       | typeof $FRAGMENT
-      | typeof $CONTEXT_PROVIDER
+      | typeof $CONTEXT
       | typeof $ERROR_BOUNDARY
 
     interface Element {
@@ -196,8 +171,10 @@ declare global {
       }
     }
 
+    type LifecycleHookCallback = () => (() => void) | void
+
     interface VNode extends Element {
-      app?: AppContext
+      app?: AppHandle
       dom?: SomeDom
       index: number
       depth: number
@@ -207,22 +184,30 @@ declare global {
       sibling: VNode | null
       prev: VNodeSnapshot | null
       deletions: VNode[] | null
-      hooks?: Hook<unknown>[]
       subs?: Set<Function>
       cleanups?: Record<string, Function>
-      effects?: Array<Function>
-      immediateEffects?: Array<Function>
-      // dev-mode only
-      hookSig?: string[]
+
+      hooks?: {
+        pre: LifecycleHookCallback[]
+        preCleanups: (() => void)[]
+        post: LifecycleHookCallback[]
+        postCleanups: (() => void)[]
+      }
+      render?: (props: VNode["props"]) => unknown
     }
-  }
-  interface VNodeSnapshot {
-    props: Kiru.VNode["props"]
-    key: Kiru.VNode["key"]
-    index: number
+    interface VNodeSnapshot {
+      props: Kiru.VNode["props"]
+      key: Kiru.VNode["key"]
+      index: number
+    }
+
+    type ContainerElement = HTMLElement | ShadowRoot
   }
 
   interface Element {
     __kiruNode?: Kiru.VNode
   }
+  interface ShadowRoot {
+    __kiruNode?: Kiru.VNode
+  }
 }

package/src/types.utils.ts

@@ -1,4 +1,4 @@
-import type { $CONTEXT_PROVIDER, $ERROR_BOUNDARY, $FRAGMENT } from "./constants"
+import type { $CONTEXT, $ERROR_BOUNDARY, $FRAGMENT } from "./constants"
 import type { Signal } from "./signals"
 import type { ErrorBoundaryProps } from "./components/errorBoundary"
 
@@ -20,12 +20,11 @@ export interface DomVNode extends Kiru.VNode {
   type: "#text" | (string & {})
 }
 
-export interface ContextProviderNode<T> extends Kiru.VNode {
-  type: typeof $CONTEXT_PROVIDER
+export interface ContextNode<T> extends Kiru.VNode {
+  type: typeof $CONTEXT
   props: Kiru.VNode["props"] & {
     value: T
     ctx: Kiru.Context<T>
-    dependents: Set<Kiru.VNode>
   }
 }
 

package/src/utils/vdom.ts

@@ -1,17 +1,16 @@
 import {
   FLAG_DELETION,
   $FRAGMENT,
-  $CONTEXT_PROVIDER,
   FLAG_PLACEMENT,
   FLAG_UPDATE,
   $ERROR_BOUNDARY,
+  $CONTEXT,
 } from "../constants.js"
 import { createElement } from "../index.js"
 import { KiruError } from "../error.js"
 import { node } from "../globals.js"
-import type { AppContext } from "../appContext.js"
+import type { AppHandle } from "../appHandle.js"
 import type { ErrorBoundaryNode } from "../types.utils.js"
-import { isMemoFn } from "../components/memo.js"
 
 export {
   cloneElement,
@@ -22,17 +21,19 @@ export {
   isExoticType,
   isFragment,
   isLazy,
-  isMemo,
   isContextProvider,
   vNodeContains,
   getCurrentVNode,
-  getVNodeAppContext,
+  getVNodeApp,
   commitSnapshot,
   traverseApply,
   findParent,
   findParentErrorBoundary,
   assertValidElementProps,
   normalizeElementKey,
+  getVNodeId,
+  registerVNodeCleanup,
+  propsChanged,
 }
 
 function cloneElement(vNode: Kiru.VNode): Kiru.Element {
@@ -68,9 +69,7 @@ function isValidTextChild(thing: unknown): thing is string | number | bigint {
 }
 
 function isExoticType(type: Kiru.VNode["type"]): type is Kiru.ExoticSymbol {
-  return (
-    type === $FRAGMENT || type === $CONTEXT_PROVIDER || type === $ERROR_BOUNDARY
-  )
+  return type === $FRAGMENT || type === $CONTEXT || type === $ERROR_BOUNDARY
 }
 
 function isFragment(
@@ -87,21 +86,17 @@ function isLazy(vNode: Kiru.VNode): boolean {
   )
 }
 
-function isMemo(vNode: Kiru.VNode): boolean {
-  return typeof vNode.type === "function" && isMemoFn(vNode.type)
-}
-
 function isContextProvider(
   thing: unknown
-): thing is Kiru.VNode & { type: typeof $CONTEXT_PROVIDER } {
-  return isVNode(thing) && thing.type === $CONTEXT_PROVIDER
+): thing is Kiru.VNode & { type: typeof $CONTEXT } {
+  return isVNode(thing) && thing.type === $CONTEXT
 }
 
 function getCurrentVNode(): Kiru.VNode | null {
   return node.current
 }
 
-function getVNodeAppContext(vNode: Kiru.VNode): AppContext | null {
+function getVNodeApp(vNode: Kiru.VNode): AppHandle | null {
   let n: Kiru.VNode | null = vNode
   while (n) {
     if (n.app) {
@@ -190,3 +185,37 @@ function normalizeElementKey(thing: unknown): JSX.ElementKey | null {
   }
   return null
 }
+
+function getVNodeId(vNode: Kiru.VNode): string {
+  const accumulator: number[] = []
+  let n: Kiru.VNode | null = vNode
+  while (n) {
+    accumulator.push(n.index)
+    accumulator.push(n.depth)
+    n = n.parent
+  }
+  return `k:${BigInt(accumulator.join("")).toString(36)}`
+}
+
+function registerVNodeCleanup(
+  vNode: Kiru.VNode,
+  id: string,
+  callback: () => void
+) {
+  ;(vNode.cleanups ??= {})[id] = callback
+}
+
+function propsChanged(
+  oldProps: Kiru.VNode["props"],
+  newProps: Kiru.VNode["props"],
+  keysToSkip?: string[]
+) {
+  const aKeys = Object.keys(oldProps)
+  const bKeys = Object.keys(newProps)
+  if (aKeys.length !== bKeys.length) return true
+  for (let key of aKeys) {
+    if (keysToSkip?.includes(key)) continue
+    if (oldProps[key] !== newProps[key]) return true
+  }
+  return false
+}