#tiye/react

React bindings for MoonBit

#Project Status

#API Stability and JavaScript Boundary

#Bound APIs and Types

#Core Rendering API

• render(vdom: VirtualNode, parent: @dom.Element) -> Unit - Render virtual DOM to specified parent element
• render_with_options(vdom: VirtualNode, parent: @dom.Element, options: RootOptions) -> Unit - Create and render through a configured React root
• hydrate_root(vdom: VirtualNode, parent: @dom.Element, options?: RootOptions) -> Unit - Attach React to matching server-rendered HTML
• unmount(parent: @dom.Element) -> Unit - Unmount the React root for an element
• create_portal(child: VirtualNode, parent: @dom.Element, key?: String) -> VirtualNode - Place DOM in another container while retaining React-tree context and event propagation
• render_to_string(vdom: VirtualNode, identifier_prefix?: String) -> String - Basic synchronous SSR/SSG renderer
• render_to_readable_stream(vdom: VirtualNode, options?: StreamRenderOptions) -> ReactReadableStream - Start React 19.2 progressive SSR on runtimes with Web Streams
• StreamRenderOptions::new(...) -> StreamRenderOptions - Configure identifier prefixes, bootstrap scripts/modules, CSP nonce, and server error reporting
• ReactReadableStream::{wait_all_ready, read_text, abort, to_js_readable_stream} - Wait for suspended content, consume HTML, cancel work, or integrate the one-shot Web Stream directly
• RootOptions::new(...) -> RootOptions - Configure identifierPrefix and caught, uncaught, and recoverable error callbacks
• ReactError::message() -> String, ReactErrorInfo::component_stack() -> String - Inspect root callback values
• component[T](f: (T) -> VirtualNode, props: T, children: Array[VirtualNode]) -> VirtualNode - Create a leaf component
• component_with_children[T](f: (T, Array[VirtualNode]) -> VirtualNode, props: T, children: Array[VirtualNode]) -> VirtualNode - Create a component that places its children
• define_component[T](render: (T) -> VirtualNode) -> ReactComponent[T] - Define a stable reusable component type with typed MoonBit props
• ReactComponent::render(props: T) -> VirtualNode - Render a reusable typed component
• ReactComponent::memo(are_props_equal?: (T, T) -> Bool) -> ReactComponent[T] - Memoize a typed component with default identity or a typed comparator
• lazy_component[T](loader: async () -> ReactComponent[T]) -> ReactComponent[T] - Lazily load and cache a typed component through Suspense
• suspense(fallback: VirtualNode, children: Array[VirtualNode]) -> VirtualNode - Display fallback UI until suspended children are ready
• activity(mode: ActivityMode, children: Array[VirtualNode]) -> VirtualNode - React 19.2 boundary that hides and restores UI while retaining child state
• resource_from_promise[T](promise: Promise[T]) -> ReactResource[T] - Preserve one cached JavaScript Promise as a typed React resource
• resource_from_async[T](loader: async () -> T) -> ReactResource[T] - Start one MoonBit async operation outside render and preserve its Promise identity
• use_resource[T](resource: ReactResource[T]) -> T - Read a cached resource with React 19 use, suspending or throwing to the nearest boundary
• error_boundary(fallback, children, reset_key?, on_error?) -> VirtualNode - Render a local fallback for render/resource errors and retry when its reset key changes
• component_from_js[T](component: JsObscure) -> ReactComponent[T] - Declare the typed MoonBit props contract for a trusted JavaScript component
• VirtualNode::with_key(key: String) -> VirtualNode - Assign a stable React reconciliation key without adding a DOM wrapper
• create_context[T](default_value: T) -> ReactContext[T] - Create a typed React Context
• ReactContext::provider(value: T, children: Array[VirtualNode]) -> VirtualNode - Provide a value without adding a DOM wrapper
• flush_sync(callback: () -> Unit) -> Unit - Force callback updates into the DOM before returning for rare third-party integrations
• prefetch_dns, preconnect, preload, preload_module, preinit, preinit_module - Emit React-managed browser resource hints
• PreloadOptions, ModuleHintOptions, PreinitOptions - Configure typed destination, CORS, priority, integrity, CSP, image, module, and stylesheet-precedence metadata

#Hooks API

• use_state[T](initial: T) -> (T, (T) -> Unit) - State management hook
• use_context[T](context: ReactContext[T]) -> T - Read and subscribe to the nearest typed Context provider
• use_state_with_updater[T](initial: T) -> (T, (StateUpdate[T]) -> Unit) - State hook with direct and functional updates
• use_reducer_with_initial[S, A](initial: S, reducer: (S, A) -> S) -> (S, (A) -> Unit) - Reducer hook for any explicit state type
• use_reducer[S: Default, A](initial?: S, reducer: (S, A) -> S) -> (S, (A) -> Unit) - Reducer hook
• use_effect_once(effect: () -> Unit) -> Unit - Effect hook that runs only once
• use_effect_cleanup_deps(effect: () -> () -> Unit, deps: Array[JsObscure]) -> Unit - Effect hook with a cleanup function
• use_effect_once_with_cleanup(effect: () -> () -> Unit) -> Unit - One-time effect with a cleanup function
• use_effect_deps(effect: () -> Unit, deps: Array[JsObscure]) -> Unit - Effect hook with dependencies
• use_layout_effect_deps(effect: () -> Unit, deps: Array[JsObscure]) -> Unit - Layout effect hook
• use_memo_deps[A](factory: () -> A, deps: Array[JsObscure]) -> A - Memoization hook
• use_callback_deps[F](callback: F, deps: Array[JsObscure]) -> F - Callback memoization hook
• use_effect_event[F](callback: F) -> F - React 19.2 effect-only callback that reads latest state without re-subscribing an effect
• use_action_state[S, A](initial: S, action: (S, A) -> S) -> (S, (A) -> Unit, Bool) - React 19 action state, dispatch, and pending flag
• use_async_action_state[S, A](initial: S, action: async (S, A) -> S) -> (S, (A) -> Unit, Bool) - Export a MoonBit async reducer as a Promise-returning React Action
• use_optimistic[S, A](value: S, reducer: (S, A) -> S) -> (S, (A) -> Unit) - Temporary optimistic state scoped to a React Action
• use_form_status() -> FormStatus - Read pending data, method, and action from the nearest parent form
• use_callback0_deps(f: () -> Unit, deps: Array[JsObscure]) -> () -> Unit - Zero-argument callback hook
• use_ref[T](initial: T) -> ReactRef[T] - Reference hook
• use_dom_ref() -> ReactDomRef - Nullable DOM-element ref hook whose current() value is None before mount and after unmount
• use_id() -> String - Stable component-local identifier hook
• use_deferred_value[T](value: T) -> T - Deferred-value hook for non-urgent rendering
• use_transition() -> (Bool, (() -> Unit) -> Unit) - Transition state and starter hook
• start_transition(action: () -> Unit) -> Unit - Start a transition when pending state is not needed
• use_sync_external_store[T](subscribe, get_snapshot, get_server_snapshot?) -> T - Read and subscribe to a typed immutable external-store snapshot
• use_imperative_ref[T]() -> ImperativeRef[T] - Create a nullable typed ref for a custom component handle
• use_imperative_handle_deps[T](ref: ImperativeRef[T], create_handle: () -> T, deps: Array[JsObscure]) -> Unit - Expose a typed React 19 imperative handle
• obscure[T](v: T) -> JsObscure - Dependency conversion helper function

#HTML Element Bindings

• div, span, p, h1, h2, h3 - Basic text elements
• form, button, input, textarea, select, option - Form elements
• a, img, video, audio - Media and link elements
• ul, ol, li - List elements
• section, article, header, footer, nav, aside - Semantic elements
• label - Label element
• Generated table helpers: table, caption, colgroup, col, thead, tbody, tfoot, tr, th, and td
• Generated form and interactive helpers: fieldset, legend, datalist, optgroup, output, progress, meter, dialog, details, and summary
• Generated React 19 metadata helpers: title, meta, link, style_tag, and script_tag
• Generated core SVG helpers include svg, g, defs, symbol, path, circle, ellipse, rect, line, gradients, clipping/masking, text, and use_

#Event Handling

• DOMEvent type and its methods:
  • target_value() -> String - Get form element value
  • target_checked() -> Bool - Get checkbox or radio checked state
  • key() -> String, key_code() -> Int - Keyboard events
  • client_x() -> Int, client_y() -> Int - Mouse coordinates
  • prevent_default(), stop_propagation() - Event control
  • ctrl_key(), shift_key(), alt_key(), meta_key() -> Bool - Modifier key detection

#Styles and Attributes

• ElementAttrs - HTML attribute management, including typed string, boolean, integer, floating-point, and JavaScript-value setters
• ElementEvents - Event handler management
• RespoStyle - CSS styles (from @css module)
• InputType enum - Support for all HTML input types
• StateUpdate[T] - Set(value) or Update(fn(previous) { ... }) for safely deriving state from the latest React value

#React DOM Operational APIs

• prefetch_dns resolves a host speculatively; preconnect additionally asks the browser to open an early connection.
• preload and preload_module download a classic resource or ESM module without applying/evaluating it.
• preinit and preinit_module download and immediately apply a stylesheet or evaluate a classic/ESM script when ready.

#Portals, Roots, and SSR Scope

• render_to_string is a synchronous react-dom/server binding.
• render_to_readable_stream resolves when the shell is ready and supports progressive Suspense output on runtimes that implement Web Streams and AbortController.
• wait_all_ready delays static generation until all suspended content is ready; read_text and to_js_readable_stream expose the same one-shot body, so choose one consumption path.
• abort cancels pending server work and leaves unresolved boundaries for client recovery. Use StreamRenderOptions::new(on_error=...) to observe server failures.
• hydrate_root requires markup identical to the initial client tree.
• identifier_prefix must be identical between either server renderer and RootOptions::new when the tree uses use_id.
• React Server Components and framework routing/data protocols are not provided.

import * as React from "react";
import * as ReactDOMServer from "react-dom/server";

globalThis.React = React;
globalThis.ReactDOMServer = ReactDOMServer;

#External Stores and Component Integration

#Resources and local errors / 资源与局部错误

#Activity / 活动边界

#Virtual DOM Types

• VirtualNode - Base virtual node type
• VirtualElement - Virtual element type
• Text(String) - Text node

#Quick Start

import * as React from "react";
import * as ReactDOM from "react-dom";
import * as ReactDOMClient from "react-dom/client";

globalThis.React = React;
globalThis.ReactDOM = ReactDOM;
globalThis.ReactDOMClient = ReactDOMClient;

// Define your component props
struct ContainerProps {} derive(Default)

// Create a functional component
fn comp_container(_v : ContainerProps) -> @react.VirtualNode {
  let (counter, set_counter) = @react.use_state(Float::from_double(0.0))

  @react.div(
    id="container",
    style=@css.respo_style(
      color=@css.CssColor::Blue,
      font_family="Arial",
      padding=@css.CssSize::Px(10.0),
    ),
    on_click=fn(_) {
      println("clicked \{counter}")
      set_counter(counter + 1.0)
    },
    [
      @react.Fragment([@react.Text("Demo: ")]),
      @react.Text("Counter \{counter}")
    ],
  )
}

// Render to DOM
fn main {
  let window = @dom.window()
  let doc = window.document()
  let body = doc.body()
  let props : ContainerProps = Default::default()

  @react.render(
    @react.component(comp_container, props, []),
    body,
  )
  println("loaded")
}

#Features

• Type-safe virtual DOM construction
• React-style hooks (useState)
• CSS-in-JS styling support
• Event handling
• Component composition

#Development

moon check
moon test
moon info
corepack yarn install --frozen-lockfile
corepack yarn generate:dom
corepack yarn check:generated
corepack yarn check:docs
corepack yarn test:server
corepack yarn build
corepack yarn test:browser

#Release

#License