acrylblends 0.6.1 → 0.6.3

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.test.tsx

@@ -0,0 +1,128 @@
+/** @jsxImportSource ../ */
+import { JSDOM } from 'jsdom'
+import { useEffect } from './index.ts'
+import DefaultExport, { createRoot, hydrateRoot } from './client.ts'
+
+describe('createRoot', () => {
+  beforeAll(() => {
+    global.requestAnimationFrame = (cb) => setTimeout(cb)
+  })
+
+  let dom: JSDOM
+  let rootElement: HTMLElement
+  beforeEach(() => {
+    dom = new JSDOM('<html><body><div id="root"></div></body></html>', {
+      runScripts: 'dangerously',
+    })
+    global.document = dom.window.document
+    global.HTMLElement = dom.window.HTMLElement
+    global.SVGElement = dom.window.SVGElement
+    global.Text = dom.window.Text
+    rootElement = document.getElementById('root') as HTMLElement
+  })
+
+  it('render / unmount', async () => {
+    const cleanup = vi.fn()
+    const App = () => {
+      useEffect(() => cleanup, [])
+      return <h1>Hello</h1>
+    }
+    const root = createRoot(rootElement)
+    root.render(<App />)
+    expect(rootElement.innerHTML).toBe('<h1>Hello</h1>')
+    await new Promise((resolve) => setTimeout(resolve))
+    root.unmount()
+    await Promise.resolve()
+    expect(rootElement.innerHTML).toBe('')
+    expect(cleanup).toHaveBeenCalled()
+  })
+
+  it('call render twice', async () => {
+    const App = <h1>Hello</h1>
+    const App2 = <h1>World</h1>
+    const root = createRoot(rootElement)
+    root.render(App)
+    expect(rootElement.innerHTML).toBe('<h1>Hello</h1>')
+
+    const createElementSpy = vi.spyOn(dom.window.document, 'createElement')
+
+    root.render(App2)
+    await Promise.resolve()
+    expect(rootElement.innerHTML).toBe('<h1>World</h1>')
+
+    expect(createElementSpy).not.toHaveBeenCalled()
+  })
+
+  it('call render after unmount', async () => {
+    const App = <h1>Hello</h1>
+    const App2 = <h1>World</h1>
+    const root = createRoot(rootElement)
+    root.render(App)
+    expect(rootElement.innerHTML).toBe('<h1>Hello</h1>')
+    root.unmount()
+    expect(() => root.render(App2)).toThrow('Cannot update an unmounted root')
+  })
+})
+
+describe('hydrateRoot', () => {
+  let dom: JSDOM
+  let rootElement: HTMLElement
+  beforeEach(() => {
+    dom = new JSDOM('<html><body><div id="root"></div></body></html>', {
+      runScripts: 'dangerously',
+    })
+    global.document = dom.window.document
+    global.HTMLElement = dom.window.HTMLElement
+    global.SVGElement = dom.window.SVGElement
+    global.Text = dom.window.Text
+    rootElement = document.getElementById('root') as HTMLElement
+  })
+
+  it('should return root object', async () => {
+    const cleanup = vi.fn()
+    const App = () => {
+      useEffect(() => cleanup, [])
+      return <h1>Hello</h1>
+    }
+    const root = hydrateRoot(rootElement, <App />)
+    expect(rootElement.innerHTML).toBe('<h1>Hello</h1>')
+    await new Promise((resolve) => setTimeout(resolve))
+    root.unmount()
+    await Promise.resolve()
+    expect(rootElement.innerHTML).toBe('')
+    expect(cleanup).toHaveBeenCalled()
+  })
+
+  it('call render', async () => {
+    const App = <h1>Hello</h1>
+    const App2 = <h1>World</h1>
+    const root = hydrateRoot(rootElement, App)
+    expect(rootElement.innerHTML).toBe('<h1>Hello</h1>')
+
+    const createElementSpy = vi.spyOn(dom.window.document, 'createElement')
+
+    root.render(App2)
+    await Promise.resolve()
+    expect(rootElement.innerHTML).toBe('<h1>World</h1>')
+
+    expect(createElementSpy).not.toHaveBeenCalled()
+  })
+
+  it('call render after unmount', async () => {
+    const App = <h1>Hello</h1>
+    const App2 = <h1>World</h1>
+    const root = hydrateRoot(rootElement, App)
+    expect(rootElement.innerHTML).toBe('<h1>Hello</h1>')
+    root.unmount()
+    expect(() => root.render(App2)).toThrow('Cannot update an unmounted root')
+  })
+})
+
+describe('default export', () => {
+  ;['createRoot', 'hydrateRoot'].forEach((key) => {
+    it(key, () => {
+      // eslint-disable-next-line @typescript-eslint/no-explicit-any
+      expect((DefaultExport as any)[key]).toBeDefined()
+    })
+  })
+})

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,
+}