@nifrajs/web-react 4.0.2 → 5.1.0

package/src/server-components/outlet.ts

@@ -0,0 +1,109 @@
+import {
+  type ComponentClientAdapter,
+  ComponentController,
+  type ServerComponent as ComponentHandle,
+  type ComponentKey,
+  type ComponentState,
+  resolveComponentRecord,
+} from "@nifrajs/web/server-components/client"
+import { createElement, useLayoutEffect, useRef } from "react"
+
+declare const __NIFRA_COMPONENT_BROWSER__: boolean
+function lazyClient(): ComponentClientAdapter {
+  let pending: Promise<ComponentClientAdapter> | undefined
+  const client = () => {
+    if (typeof __NIFRA_COMPONENT_BROWSER__ === "boolean" && !__NIFRA_COMPONENT_BROWSER__)
+      throw new Error("component_contract")
+    pending ??= import("./client.ts").then((module) => module.reactComponentClient())
+    return pending
+  }
+  return {
+    name: "react",
+    prepare: async (...args) => (await client()).prepare(...args),
+    hydrate: async (...args) => (await client()).hydrate(...args),
+    create: async (...args) => {
+      const create = (await client()).create
+      if (create === undefined) throw new Error("component_contract")
+      return create(...args)
+    },
+    update: async (...args) => (await client()).update(...args),
+  }
+}
+export interface ServerComponentProps<Input, Props, View> {
+  readonly state: ComponentState
+  readonly component: ComponentHandle<Input, Props, View>
+  readonly instanceKey: ComponentKey
+  readonly input: NoInfer<Input>
+  readonly parent?: string
+  readonly controller?: ComponentController | undefined
+  readonly clientAdapter?: ComponentClientAdapter
+  readonly onError?: (code: string) => void
+}
+export function ServerComponent<Input, Props, View>(
+  props: ServerComponentProps<Input, Props, View>,
+) {
+  const record = resolveComponentRecord(
+    props.state,
+    props.component,
+    props.instanceKey,
+    props.input,
+    props.parent ?? null,
+  )
+  return createElement(ComponentRange, {
+    key: record.instance,
+    state: props.state,
+    record,
+    controller: props.controller,
+    clientAdapter: props.clientAdapter,
+    onError: props.onError,
+  })
+}
+function ComponentRange(props: {
+  readonly state: ComponentState
+  readonly record: import("@nifrajs/web/server-components/client").ComponentRecord
+  readonly controller?: ComponentController | undefined
+  readonly clientAdapter?: ComponentClientAdapter | undefined
+  readonly onError?: ((code: string) => void) | undefined
+}) {
+  const record = props.record
+  const host = useRef<HTMLElement>(null)
+  // React owns the shell; the independently hydrated native root is an unassociated child.
+  const initial = useRef({
+    __html: `<nifra-component data-nifra-component="${record.instance}">${record.html}</nifra-component>`,
+  })
+  const active = useRef<ComponentController | undefined>(undefined)
+  const lifecycle = useRef(props)
+  lifecycle.current = props
+  useLayoutEffect(() => {
+    const options = lifecycle.current
+    const element = host.current?.firstElementChild
+    if (!(element instanceof HTMLElement) || element.localName !== "nifra-component") return
+    const controller =
+      options.controller ??
+      new ComponentController({
+        state: options.state,
+        adapter: options.clientAdapter ?? lazyClient(),
+        onError: (code) => lifecycle.current.onError?.(code),
+      })
+    active.current = controller
+    void controller
+      .mount(element, record.instance)
+      .catch(() => lifecycle.current.onError?.("component_failed"))
+    return () => {
+      void (
+        options.controller === undefined
+          ? controller.dispose()
+          : controller.unmount(record.instance)
+      ).catch(() => lifecycle.current.onError?.("component_failed"))
+    }
+  }, [record.instance])
+  useLayoutEffect(() => {
+    if (active.current !== undefined)
+      void active.current.adopt(props.state).catch(() => props.onError?.("component_failed"))
+  }, [props.state, props.onError])
+  return createElement("nifra-component-outlet", {
+    ref: host,
+    // biome-ignore lint/security/noDangerouslySetInnerHtml: Record HTML passed the shared component policy before an outlet can resolve it.
+    dangerouslySetInnerHTML: initial.current,
+  })
+}

package/src/server-components/rsc.ts

@@ -0,0 +1,39 @@
+import type { ComponentRenderContext, ServerComponentHandle } from "@nifrajs/web/server-components"
+import { guardComponentProps } from "@nifrajs/web/server-components/props"
+import { renderToReadableStream } from "@vitejs/plugin-rsc/rsc/server"
+import { type ComponentType, createElement } from "react"
+import { publicFlightStream } from "./flight.ts"
+
+/** Export this renderer from the compiler's RSC entry, which owns React's server condition. */
+export function createReactComponentRenderer(components: readonly ServerComponentHandle[]) {
+  const references = new Map(components.map((component) => [component.reference, component]))
+  if (references.size !== components.length || references.has(undefined))
+    throw new Error("component_contract")
+  return async (
+    reference: string,
+    props: unknown,
+    context: ComponentRenderContext,
+  ): Promise<ReadableStream<Uint8Array>> => {
+    const component = references.get(reference)
+    if (component === undefined) throw new Error("component_unavailable")
+    const projected = await guardComponentProps(component.props, props)
+    const stream = renderToReadableStream(
+      // biome-ignore lint/plugin/requireSafetyCommentForTypeAssertion: The renderer resolves an allowlisted definition and guards its public props before invoking that definition.
+      createElement(component.view as ComponentType<{ props: unknown; children: unknown }>, {
+        props: projected,
+        // biome-ignore lint/correctness/noChildrenProp: Server views receive verified record metadata through their declared children prop.
+        children: context.children ?? [],
+      }),
+      {
+        signal: context.signal,
+        // React development debug metadata can contain server-only props; it has no public transport.
+        debugChannel: { writable: new WritableStream<Uint8Array>({ write() {} }) },
+        filterStackFrame: () => false,
+        onError() {
+          return "component_failed"
+        },
+      },
+    )
+    return publicFlightStream(stream, context.signal)
+  }
+}

package/src/server-components/server.ts

@@ -0,0 +1,52 @@
+import type {
+  ComponentRenderContext,
+  ServerComponentRenderAdapter,
+} from "@nifrajs/web/server-components"
+import {
+  bytesStream,
+  encodeComponentBytes,
+  readComponentBytes,
+} from "@nifrajs/web/server-components/stream"
+import { createFromReadableStream } from "@vitejs/plugin-rsc/ssr"
+import type { ReactNode } from "react"
+import { renderToReadableStream } from "react-dom/server.edge"
+
+export type ReactFlightRenderer = (
+  reference: string,
+  props: unknown,
+  context: ComponentRenderContext,
+) => Promise<ReadableStream<Uint8Array>>
+
+export function reactServerComponents(
+  renderFlight: ReactFlightRenderer,
+): ServerComponentRenderAdapter {
+  return {
+    name: "react",
+    version: 1,
+    async render(_view, props, context) {
+      const flight = await readComponentBytes(
+        await renderFlight(context.reference, props, context),
+        context.signal,
+      )
+      const tree = await createFromReadableStream<ReactNode>(bytesStream(flight))
+      let failed = false
+      const options: NonNullable<Parameters<typeof renderToReadableStream>[1]> = {
+        identifierPrefix: context.instance + "-",
+        signal: context.signal,
+        onError() {
+          failed = true
+          return "component_failed"
+        },
+      }
+      if (context.nonce !== undefined) options.nonce = context.nonce
+      const html = await renderToReadableStream(tree, options)
+      await html.allReady
+      const bytes = await readComponentBytes(html, context.signal)
+      if (failed) throw new Error("component_failed")
+      return {
+        html: new TextDecoder().decode(bytes),
+        payload: { flight: encodeComponentBytes(flight) },
+      }
+    },
+  }
+}