kiru 0.54.4 → 1.1.0

package/src/signals/globals.ts

@@ -1,11 +1,4 @@
-import type { Signal } from "./base.js"
 import type { SignalSubscriber } from "./types.js"
 
-export const tracking = {
-  stack: new Array<Map<string, Signal<unknown>>>(),
-  current: function (): Map<string, Signal<unknown>> | undefined {
-    return this.stack[this.stack.length - 1]
-  },
-}
 export const effectQueue = new Map<string, Function>()
 export const signalSubsMap: Map<string, Set<SignalSubscriber<any>>> = new Map()

package/src/signals/index.ts

@@ -4,9 +4,9 @@
  * 2. global computed will lose its vNode subscription on HMR
  * */
 
-export { Signal, signal, useSignal } from "./base.js"
-export { ComputedSignal, computed, useComputed } from "./computed.js"
-export { WatchEffect, watch, useWatch } from "./watch.js"
+export { Signal, signal } from "./base.js"
+export { ComputedSignal, computed } from "./computed.js"
+export { Effect, effect } from "./effect.js"
 export { unwrap, tick } from "./utils.js"
-export * from "./for.js"
+export * from "./jsx.js"
 export * from "./types.js"

package/src/signals/{for.ts → jsx.ts}

@@ -1,3 +1,4 @@
+import { Signalable } from "../types.js"
 import type { Signal } from "./base.js"
 import { unwrap } from "./utils.js"
 
@@ -28,3 +29,12 @@ export function For<T extends Signal<any[]> | unknown[]>({
   if (items.length === 0) return fallback
   return items.map(children)
 }
+
+export interface ShowProps {
+  children: JSX.Element
+  when: Signalable<unknown>
+  fallback?: JSX.Element
+}
+export function Show({ children, when, fallback }: ShowProps): JSX.Element {
+  return !!unwrap(when, true) ? children : fallback
+}

package/src/signals/tracking.ts

@@ -0,0 +1,70 @@
+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 type TrackingStackObservations = Map<string, Signal<unknown>>
+export const tracking = {
+  enabled: true,
+  stack: new Array<TrackingStackObservations>(),
+  current: function (): TrackingStackObservations | 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 { createVNodeId } 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 = createVNodeId(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

@@ -153,8 +153,8 @@ type AllStyleRules = Omit<
 type StyleObject = Prettify<
   Partial<{
     [Key in keyof AllStyleRules & string]: Key extends NumericStyleKeys
-      ? number | string
-      : AllStyleRules[Key]
+      ? Signalable<number | string | undefined>
+      : Signalable<AllStyleRules[Key] | undefined>
   }>
 >
 
@@ -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,11 +158,15 @@ declare global {
 
     type ExoticSymbol =
       | typeof $FRAGMENT
-      | typeof $CONTEXT_PROVIDER
+      | typeof $CONTEXT
       | typeof $ERROR_BOUNDARY
 
     interface Element {
-      type: Function | ExoticSymbol | "#text" | (string & {})
+      type:
+        | (Function & { displayName?: string })
+        | ExoticSymbol
+        | "#text"
+        | (string & {})
       key: JSX.ElementKey | null
       props: {
         [key: string]: any
@@ -196,8 +175,10 @@ declare global {
       }
     }
 
+    type LifecycleHookCallback = () => (() => void) | void
+
     interface VNode extends Element {
-      app?: AppContext
+      app?: AppHandle
       dom?: SomeDom
       index: number
       depth: number
@@ -207,22 +188,32 @@ 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)[]
+      }
+      /** Run before each render with current props to sync prop-derived signals */
+      propSyncs?: ((props: VNode["props"]) => 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/format.ts

@@ -84,8 +84,10 @@ function propToHtmlAttr(key: string): string {
 function styleObjectToString(obj: Partial<CSSStyleDeclaration>): string {
   let cssString = ""
   for (const key in obj) {
+    const val = unwrap((obj as Record<string, unknown>)[key])
+    if (val === null || val === undefined) continue
     const cssKey = key.replace(REGEX_ALPHA_UPPER, "-$&").toLowerCase()
-    cssString += `${cssKey}:${obj[key]};`
+    cssString += `${cssKey}:${val};`
   }
   return cssString
 }