acrylblends 0.6.2 → 0.6.4

package/plugins/acryl-router/src/core/jsx/components.ts

@@ -0,0 +1,257 @@
+import { raw } from '../helper/html/index.ts'
+import type { HtmlEscapedCallback, HtmlEscapedString } from '../utils/html.ts'
+import { HtmlEscapedCallbackPhase, resolveCallback } from '../utils/html.ts'
+import type { Child, FC, PropsWithChildren } from './index.ts'
+import { jsx, Fragment, isUntrustedObject, renderChildren, renderUntrustedObject } from './base.ts'
+import { DOM_RENDERER } from './constants.ts'
+import { captureRenderContext, useContext } from './context.ts'
+import { ErrorBoundary as ErrorBoundaryDomRenderer } from './dom/components.ts'
+import type { HasRenderToDom } from './dom/render.ts'
+import { StreamingContext } from './streaming.ts'
+
+let errorBoundaryCounter = 0
+
+export const childrenToString = async (children: Child[]): Promise<HtmlEscapedString[]> => {
+  try {
+    return children.flat().map(resolveChildEarly) as HtmlEscapedString[]
+  } catch (e) {
+    if (e instanceof Promise) {
+      // Capture before `await`: on the fallback path the render context is
+      // only observable during this synchronous window.
+      const resume = captureRenderContext()
+      await e
+      return resume(() => childrenToString(children))
+    } else {
+      throw e
+    }
+  }
+}
+
+const resolveChildEarly = (child: Child): HtmlEscapedString | Promise<HtmlEscapedString> => {
+  if (child == null || typeof child === 'boolean') {
+    return '' as HtmlEscapedString
+  } else if (typeof child === 'string' || Array.isArray(child)) {
+    return renderChildren([child])
+  } else if (isUntrustedObject(child)) {
+    return renderUntrustedObject(child)
+  } else {
+    const str = child.toString()
+    return str instanceof Promise ? (str as Promise<HtmlEscapedString>) : raw(str)
+  }
+}
+
+export type ErrorHandler = (error: Error) => void
+export type FallbackRender = (error: Error) => Child
+
+/**
+ * @experimental
+ * `ErrorBoundary` is an experimental feature.
+ * The API might be changed.
+ */
+export const ErrorBoundary: FC<
+  PropsWithChildren<{
+    fallback?: Child
+    fallbackRender?: FallbackRender
+    onError?: ErrorHandler
+  }>
+> = async ({ children, fallback, fallbackRender, onError }) => {
+  if (!children) {
+    return raw('')
+  }
+
+  if (!Array.isArray(children)) {
+    children = [children]
+  }
+
+  const nonce = useContext(StreamingContext)?.scriptNonce
+
+  let resume: ReturnType<typeof captureRenderContext> | undefined
+  const getResume = () => (resume ||= captureRenderContext())
+
+  let fallbackStrPromise: Promise<HtmlEscapedString | string | undefined> | undefined
+  const resolveFallbackStr = (): Promise<HtmlEscapedString | string | undefined> =>
+    (fallbackStrPromise ||= (async () => {
+      const awaitedFallback = await fallback
+      if (awaitedFallback === null || awaitedFallback === undefined) {
+        return
+      }
+      if (typeof awaitedFallback === 'string' || Array.isArray(awaitedFallback)) {
+        return getResume()(() => renderChildren([awaitedFallback]))
+      }
+      if (isUntrustedObject(awaitedFallback)) {
+        return getResume()(() => renderUntrustedObject(awaitedFallback))
+      }
+      const fallbackResult = await getResume()(() => awaitedFallback.toString())
+      return raw(
+        fallbackResult,
+        (fallbackResult as HtmlEscapedString).callbacks ||
+          (awaitedFallback as unknown as HtmlEscapedString).callbacks
+      )
+    })())
+  const renderFallback = async (error: Error): Promise<HtmlEscapedString> => {
+    const fallbackStr = await resolveFallbackStr()
+    return getResume()(async () => {
+      onError?.(error)
+      const fallbackRes = (
+        fallbackStr !== undefined
+          ? fallbackStr
+          : (fallbackRender && jsx(Fragment, {}, fallbackRender(error) as HtmlEscapedString)) || ''
+      ) as HtmlEscapedString
+      const fallbackResString = await Fragment({ children: fallbackRes }).toString()
+      return raw(
+        fallbackResString,
+        (fallbackResString as HtmlEscapedString).callbacks || fallbackRes.callbacks
+      )
+    })
+  }
+  let resArray: HtmlEscapedString[] | Promise<HtmlEscapedString[]>[] = []
+  try {
+    resArray = children.map(resolveChildEarly) as unknown as HtmlEscapedString[]
+  } catch (e) {
+    const resume = getResume()
+    if (e instanceof Promise) {
+      resArray = [
+        e
+          .then(() => resume(() => childrenToString(children as Child[])))
+          .catch((e) => renderFallback(e)),
+      ] as Promise<HtmlEscapedString[]>[]
+    } else {
+      resArray = [await renderFallback(e as Error)]
+    }
+  }
+
+  if (resArray.some((res) => (res as {}) instanceof Promise)) {
+    // Prime the context capture while still synchronous: a child that returned
+    // a Promise from `resolveChildEarly` skipped the `catch`, so the deferred
+    // `catchCallback` would otherwise capture too late.
+    getResume()
+    const index = errorBoundaryCounter++
+    const replaceRe = RegExp(`(<template id="E:${index}"></template>)(.*?)(<!--E:${index}-->)`, 's')
+    let caught = false
+    const catchCallback = async ({ error, buffer }: { error: Error; buffer?: [string] }) => {
+      if (caught) {
+        return ''
+      }
+      caught = true
+
+      const fallbackResString = await renderFallback(error)
+      const fallbackCallbacks = fallbackResString.callbacks
+      if (buffer) {
+        buffer[0] = buffer[0].replace(replaceRe, () => fallbackResString)
+        return fallbackCallbacks?.length ? raw('', fallbackCallbacks) : ''
+      }
+      return raw(
+        `<template data-acryl-target="E:${index}">${fallbackResString}</template><script>
+((d,c,n) => {
+c=d.currentScript.previousSibling
+d=d.getElementById('E:${index}')
+if(!d)return
+do{n=d.nextSibling;n.remove()}while(n.nodeType!=8||n.nodeValue!='E:${index}')
+d.replaceWith(c.content)
+})(document)
+</script>`,
+        fallbackCallbacks
+      )
+    }
+
+    let error: unknown
+    const promiseAll = Promise.all(resArray).catch((e) => (error = e))
+    return raw(`<template id="E:${index}"></template><!--E:${index}-->`, [
+      ({ phase, buffer, context }) => {
+        if (phase === HtmlEscapedCallbackPhase.BeforeStream) {
+          return
+        }
+        return promiseAll
+          .then(async (htmlArray: HtmlEscapedString[]) => {
+            if (error) {
+              throw error
+            }
+            htmlArray = htmlArray.flat()
+            const content = htmlArray.join('')
+            let html = buffer
+              ? ''
+              : `<template data-acryl-target="E:${index}">${content}</template><script${
+                  nonce ? ` nonce="${nonce}"` : ''
+                }>
+((d,c) => {
+c=d.currentScript.previousSibling
+d=d.getElementById('E:${index}')
+if(!d)return
+d.parentElement.insertBefore(c.content,d.nextSibling)
+})(document)
+</script>`
+
+            if (htmlArray.every((html) => !(html as HtmlEscapedString).callbacks?.length)) {
+              if (buffer) {
+                buffer[0] = buffer[0].replace(replaceRe, () => content)
+              }
+              return html
+            }
+
+            if (buffer) {
+              buffer[0] = buffer[0].replace(
+                replaceRe,
+                (_all, pre, _, post) => `${pre}${content}${post}`
+              )
+            }
+
+            const callbacks = htmlArray
+              .map((html) => (html as HtmlEscapedString).callbacks || [])
+              .flat()
+
+            if (phase === HtmlEscapedCallbackPhase.Stream) {
+              html = await resolveCallback(
+                html,
+                HtmlEscapedCallbackPhase.BeforeStream,
+                true,
+                context
+              )
+            }
+
+            let resolvedCount = 0
+            const promises = callbacks.map<HtmlEscapedCallback>(
+              (c) =>
+                (...args) =>
+                  c(...args)
+                    ?.then((content) => {
+                      resolvedCount++
+
+                      if (buffer) {
+                        if (resolvedCount === callbacks.length) {
+                          buffer[0] = buffer[0].replace(replaceRe, (_all, _pre, content) => content)
+                        }
+                        buffer[0] += content
+                        return raw('', (content as HtmlEscapedString).callbacks)
+                      }
+
+                      return raw(
+                        content +
+                          (resolvedCount !== callbacks.length
+                            ? ''
+                            : `<script>
+((d,c,n) => {
+d=d.getElementById('E:${index}')
+if(!d)return
+n=d.nextSibling
+while(n.nodeType!=8||n.nodeValue!='E:${index}'){n=n.nextSibling}
+n.remove()
+d.remove()
+})(document)
+</script>`),
+                        (content as HtmlEscapedString).callbacks
+                      )
+                    })
+                    .catch((error) => catchCallback({ error, buffer }))
+            )
+
+            // eslint-disable-next-line @typescript-eslint/no-explicit-any
+            return raw(html, promises as any)
+          })
+          .catch((error) => catchCallback({ error, buffer }))
+      },
+    ])
+  } else {
+    return Fragment({ children: resArray as Child[] })
+  }
+}
+;(ErrorBoundary as HasRenderToDom)[DOM_RENDERER] = ErrorBoundaryDomRenderer

package/plugins/acryl-router/src/core/jsx/constants.ts

@@ -0,0 +1,6 @@
+export const DOM_RENDERER = Symbol('RENDERER')
+export const DOM_ERROR_HANDLER = Symbol('ERROR_HANDLER')
+export const DOM_STASH = Symbol('STASH')
+export const DOM_INTERNAL_TAG = Symbol('INTERNAL')
+export const DOM_MEMO = Symbol('MEMO')
+export const PERMALINK = Symbol('PERMALINK')

package/plugins/acryl-router/src/core/jsx/context.ts

@@ -0,0 +1,266 @@
+import { raw } from '../helper/html/index.ts'
+import type { HtmlEscapedString } from '../utils/html.ts'
+import type { FC, PropsWithChildren } from './index.ts'
+import { isUntrustedObject, JSXFragmentNode, renderChildren, renderUntrustedObject } from './base.ts'
+import { DOM_RENDERER } from './constants.ts'
+import { createContextProviderFunction } from './dom/context.ts'
+
+export interface Context<T> extends FC<PropsWithChildren<{ value: T }>> {
+  values: T[]
+  Provider: FC<PropsWithChildren<{ value: T }>>
+}
+
+export const globalContexts: Context<unknown>[] = []
+
+/** Per-render context store, isolated per request so values never leak across renders. */
+type RenderStore = WeakMap<Context<unknown>, unknown[]>
+
+type AsyncLocalStorageLike<T> = {
+  getStore(): T | undefined
+  run<R>(store: T, callback: () => R): R
+}
+type AsyncLocalStorageClass = new <T>() => AsyncLocalStorageLike<T>
+type AsyncHooksModule = { AsyncLocalStorage?: AsyncLocalStorageClass }
+
+let alsProbed = false
+let asyncLocalStorage: AsyncLocalStorageLike<RenderStore> | undefined
+let fallbackStore: RenderStore | undefined
+// Unsettled async renders on the fallback path. While > 0, a store-less
+// context access is a post-`await` read that degraded to the default value
+// — worth a one-time warning. Stays 0 in the browser DOM renderer.
+let fallbackRendersInFlight = 0
+let warnedFallbackDefault = false
+
+const loadAsyncLocalStorage = (): AsyncLocalStorageLike<RenderStore> | undefined => {
+  if (alsProbed) {
+    return asyncLocalStorage
+  }
+  alsProbed = true
+
+  const global = globalThis as unknown as {
+    process?: {
+      getBuiltinModule?: (specifier: string) => AsyncHooksModule
+      mainModule?: { require?: (specifier: string) => AsyncHooksModule }
+    }
+  }
+  let AsyncLocalStorage: AsyncLocalStorageClass | undefined
+  for (const probe of [
+    // Node.js >= 20.16, Deno, Bun, Cloudflare Workers (nodejs_compat). Property
+    // access only, so bundlers don't statically resolve `node:async_hooks`.
+    () => global.process?.getBuiltinModule?.('node:async_hooks')?.AsyncLocalStorage,
+    // Node.js < 20.16 has no `process.getBuiltinModule`, but a CJS entrypoint
+    // exposes the main module's `require` here.
+    () => global.process?.mainModule?.require?.('node:async_hooks')?.AsyncLocalStorage,
+  ]) {
+    try {
+      AsyncLocalStorage = probe()
+    } catch {}
+    if (AsyncLocalStorage) {
+      break
+    }
+  }
+
+  if (AsyncLocalStorage) {
+    asyncLocalStorage = new AsyncLocalStorage<RenderStore>()
+  }
+  return asyncLocalStorage
+}
+
+const getCurrentStore = (): RenderStore | undefined => {
+  return loadAsyncLocalStorage()?.getStore() || fallbackStore
+}
+
+const warnIfStorelessAccess = (): void => {
+  if (fallbackRendersInFlight > 0 && !warnedFallbackDefault) {
+    warnedFallbackDefault = true
+    console.warn(
+      'acryl-router/jsx: AsyncLocalStorage is unavailable in this runtime, so useContext() after an await in an async component falls back to the context default value during server-side rendering. To get provided values across await boundaries, use a runtime with AsyncLocalStorage (Node.js >= 20.16, Deno, Bun, or Cloudflare Workers with the nodejs_compat flag).'
+    )
+  }
+}
+
+// Write path: materializes the store entry so a Provider's push/pop pair
+// operates on a per-render array.
+const getContextValuesIn = <T>(store: RenderStore | undefined, context: Context<T>): T[] => {
+  if (!store) {
+    warnIfStorelessAccess()
+    return context.values
+  }
+
+  let values = store.get(context as Context<unknown>) as T[] | undefined
+  if (!values) {
+    values = [context.values[0]]
+    store.set(context as Context<unknown>, values)
+  }
+  return values
+}
+
+// Read path: never materializes a store entry — a missing entry always
+// resolves to the default value, so reads stay allocation-free.
+const readContextValueIn = <T>(store: RenderStore | undefined, context: Context<T>): T => {
+  if (!store) {
+    warnIfStorelessAccess()
+    return context.values.at(-1) as T
+  }
+  const values = store.get(context as Context<unknown>) as T[] | undefined
+  return values?.length ? (values.at(-1) as T) : context.values[0]
+}
+
+type LocalContexts = [Context<unknown>, unknown][]
+
+const captureContextValues = (store: RenderStore | undefined): LocalContexts =>
+  (store ? globalContexts.filter((c) => store.has(c)) : globalContexts).map((c) => [
+    c,
+    readContextValueIn(store, c),
+  ])
+
+const resumeWithContextValues = <T>(
+  callback: () => T,
+  store: RenderStore | undefined,
+  contexts: LocalContexts
+): T =>
+  runWithRenderContext(() => {
+    // Resolve each target array once so every pop operates on the same array
+    // as its push, as the Provider in `createContext` does.
+    const currentStore = getCurrentStore()
+    const valuesPerContext = contexts.map(([context, value]) => {
+      const values = getContextValuesIn(currentStore, context)
+      values.push(value)
+      return values
+    })
+    const popContextValues = () => {
+      valuesPerContext.forEach((values) => {
+        values.pop()
+      })
+    }
+    try {
+      const result = callback()
+      if (result instanceof Promise) {
+        return result.finally(popContextValues) as T
+      }
+      popContextValues()
+      return result
+    } catch (e) {
+      popContextValues()
+      throw e
+    }
+  }, store)
+
+/**
+ * Establish the request-scoped context store for a render.
+ *
+ * `resumeStore` continues a suspended subtree in the same store on the fallback
+ * path (ignored when `AsyncLocalStorage` is available, where isolation is
+ * automatic).
+ *
+ * Without `AsyncLocalStorage` a render can't be followed across `await`, so the
+ * store lives in `fallbackStore` only during synchronous work (mirroring
+ * React's request storage). Reading context after `await` then finds no store
+ * and falls back to the default value — never another request's value.
+ */
+export const runWithRenderContext = <T>(callback: () => T, resumeStore?: RenderStore): T => {
+  if (getCurrentStore()) {
+    // Already inside a render (synchronously nested or resumed subtree).
+    return callback()
+  }
+
+  const store = resumeStore ?? new WeakMap()
+  const storage = loadAsyncLocalStorage()
+  if (storage) {
+    // AsyncLocalStorage path: request isolation propagates across `await`.
+    return storage.run(store, callback)
+  }
+
+  // Fallback path (no AsyncLocalStorage).
+  fallbackStore = store
+  let result: T
+  try {
+    result = callback()
+  } finally {
+    fallbackStore = undefined
+  }
+  if (!warnedFallbackDefault && result instanceof Promise) {
+    fallbackRendersInFlight++
+    result = result.finally(() => {
+      fallbackRendersInFlight--
+    }) as T
+  }
+  return result
+}
+
+/**
+ * Capture the current render store and return a resumer that re-establishes it
+ * around a deferred continuation (e.g. a re-render after a suspended promise
+ * settles). Shared by every suspension point so none reimplements it.
+ */
+export const captureRenderContext = (): (<T>(callback: () => T) => T) => {
+  const store = getCurrentStore()
+  const contexts = captureContextValues(store)
+  return (callback) => resumeWithContextValues(callback, store, contexts)
+}
+
+/**
+ * Create a context whose value can be provided with `<Context.Provider>` and
+ * read with {@link useContext}.
+ *
+ * Server-side renders are isolated per request, so a provided value never leaks
+ * into a concurrent request — even across `await` in an async component, when
+ * `AsyncLocalStorage` is available (Node.js >= 20.16, Deno, Bun, Cloudflare
+ * Workers with `nodejs_compat`). Without it, reading context after `await`
+ * returns the default value; synchronous components and `use()`-based
+ * suspension are unaffected.
+ */
+export const createContext = <T>(defaultValue: T): Context<T> => {
+  const values = [defaultValue]
+  const context: Context<T> = ((props): HtmlEscapedString | Promise<HtmlEscapedString> => {
+    // Resolve the target array once, synchronously: the pop in `.finally()`
+    // below may run later and must operate on the same array as the push.
+    const contextValues = getContextValuesIn(getCurrentStore(), context)
+    contextValues.push(props.value)
+    let rendered
+    try {
+      rendered =
+        typeof props.children === 'string'
+          ? renderChildren([props.children])
+          : isUntrustedObject(props.children)
+            ? renderUntrustedObject(props.children)
+            : props.children
+              ? (Array.isArray(props.children)
+                  ? new JSXFragmentNode('', {}, props.children)
+                  : props.children
+                ).toString()
+              : raw('')
+    } catch (e) {
+      contextValues.pop()
+      throw e
+    }
+
+    if (rendered instanceof Promise) {
+      return rendered
+        .finally(() => contextValues.pop())
+        .then((resString) => raw(resString, (resString as HtmlEscapedString).callbacks))
+    } else {
+      contextValues.pop()
+      return raw(rendered)
+    }
+  }) as Context<T>
+  context.values = values
+  context.Provider = context
+
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  ;(context as any)[DOM_RENDERER] = createContextProviderFunction(values)
+
+  globalContexts.push(context as Context<unknown>)
+
+  return context
+}
+
+/**
+ * Read the current value of a context created with {@link createContext}.
+ *
+ * Safe to call from async components after `await`. See {@link createContext}
+ * for the per-runtime isolation guarantees.
+ */
+export const useContext = <T>(context: Context<T>): T => {
+  return readContextValueIn(getCurrentStore(), context)
+}

package/plugins/acryl-router/src/core/jsx/dom/client.ts

@@ -0,0 +1,89 @@
+/**
+ * @module
+ * This module provides APIs for `acryl-router/jsx/dom/client`, which is compatible with `react-dom/client`.
+ */
+
+import type { Child } from '../base.ts'
+import { useState } from '../hooks/index.ts'
+import { buildNode, renderNode } from './render.ts'
+import type { NodeObject } from './render.ts'
+
+export interface Root {
+  render(children: Child): void
+  unmount(): void
+}
+export type RootOptions = Record<string, unknown>
+
+/**
+ * Create a root object for rendering
+ * @param element Render target
+ * @param options Options for createRoot (not supported yet)
+ * @returns Root object has `render` and `unmount` methods
+ */
+export const createRoot = (
+  element: HTMLElement | DocumentFragment,
+  options: RootOptions = {}
+): Root => {
+  let setJsxNode:
+    | undefined // initial state
+    | ((jsxNode: unknown) => void) // rendered
+    | null = // unmounted
+    undefined
+
+  if (Object.keys(options).length > 0) {
+    console.warn('createRoot options are not supported yet')
+  }
+
+  return {
+    render(jsxNode: unknown) {
+      if (setJsxNode === null) {
+        // unmounted
+        throw new Error('Cannot update an unmounted root')
+      }
+      if (setJsxNode) {
+        // rendered
+        setJsxNode(jsxNode)
+      } else {
+        renderNode(
+          buildNode({
+            tag: () => {
+              const [_jsxNode, _setJsxNode] = useState(jsxNode)
+              setJsxNode = _setJsxNode
+              return _jsxNode
+            },
+            props: {},
+            // eslint-disable-next-line @typescript-eslint/no-explicit-any
+          } as any) as NodeObject,
+          element
+        )
+      }
+    },
+    unmount() {
+      setJsxNode?.(null)
+      setJsxNode = null
+    },
+  }
+}
+
+/**
+ * Create a root object and hydrate app to the target element.
+ * In acryl-router/jsx/dom, hydrate is equivalent to render.
+ * @param element Render target
+ * @param reactNode A JSXNode to render
+ * @param options Options for createRoot (not supported yet)
+ * @returns Root object has `render` and `unmount` methods
+ */
+export const hydrateRoot = (
+  element: HTMLElement | DocumentFragment,
+  reactNode: Child,
+  options: RootOptions = {}
+): Root => {
+  const root = createRoot(element, options)
+  root.render(reactNode)
+  return root
+}
+
+export default {
+  createRoot,
+  hydrateRoot,
+}

package/plugins/acryl-router/src/core/jsx/dom/components.ts

@@ -0,0 +1,39 @@
+import type { Child, FC, PropsWithChildren } from '../index.ts'
+import type { ErrorHandler, FallbackRender } from '../components.ts'
+import { DOM_ERROR_HANDLER } from '../constants.ts'
+import { Fragment } from './jsx-runtime.ts'
+
+/* eslint-disable @typescript-eslint/no-explicit-any */
+export const ErrorBoundary: FC<
+  PropsWithChildren<{
+    fallback?: Child
+    fallbackRender?: FallbackRender
+    onError?: ErrorHandler
+  }>
+> = (({ children, fallback, fallbackRender, onError }: any) => {
+  const res = Fragment({ children })
+  ;(res as any)[DOM_ERROR_HANDLER] = (err: any) => {
+    if (err instanceof Promise) {
+      throw err
+    }
+    onError?.(err)
+    return fallbackRender?.(err) || fallback
+  }
+  return res
+}) as any
+
+export const Suspense: FC<PropsWithChildren<{ fallback: any }>> = (({
+  children,
+  fallback,
+}: any) => {
+  const res = Fragment({ children })
+  ;(res as any)[DOM_ERROR_HANDLER] = (err: any, retry: () => void) => {
+    if (!(err instanceof Promise)) {
+      throw err
+    }
+    err.finally(retry)
+    return fallback
+  }
+  return res
+}) as any
+/* eslint-enable @typescript-eslint/no-explicit-any */