@remix-run/ui 0.1.1 → 0.2.0

package/src/runtime/run.ts

@@ -11,8 +11,21 @@ import { TypedEventTarget } from './typed-event-target.ts'
 /**
  * Options for starting the client runtime with {@link run}.
  */
-export type RunInit = {
+export interface RunInit {
+  /**
+   * Loads the named browser module export for a hydrated `clientEntry()`.
+   *
+   * Implementations usually call dynamic `import(moduleUrl)` and return
+   * `mod[exportName]`.
+   */
   loadModule: LoadModule
+
+  /**
+   * Resolves browser-loaded `<Frame>` content.
+   *
+   * Omit this only when the runtime never needs to load or reload frames in the
+   * browser.
+   */
   resolveFrame?: ResolveFrame
 }
 
@@ -27,8 +40,11 @@ export type AppRuntimeEventMap = {
  * Client runtime returned by {@link run}.
  */
 export type AppRuntime = TypedEventTarget<AppRuntimeEventMap> & {
+  /** Resolves after the current document finishes hydrating. */
   ready(): Promise<void>
+  /** Flushes any queued component updates synchronously. */
   flush(): void
+  /** Stops runtime listeners and disposes the top-level frame. */
   dispose(): void
 }
 

package/src/runtime/scheduler.ts

@@ -17,7 +17,23 @@ type SchedulerPhaseListener = EventListenerOrEventListenerObject | null
 /**
  * Scheduler API used by the reconciler and frame runtime.
  */
-export type Scheduler = ReturnType<typeof createScheduler>
+export interface Scheduler {
+  enqueue(vnode: CommittedComponentNode, domParent: ParentNode): void
+  enqueueWork(newTasks: EmptyFn[]): void
+  enqueueCommitPhase(newTasks: EmptyFn[]): void
+  enqueueTasks(newTasks: EmptyFn[]): void
+  addEventListener(
+    type: SchedulerPhaseType,
+    listener: SchedulerPhaseListener,
+    options?: AddEventListenerOptions | boolean,
+  ): void
+  removeEventListener(
+    type: SchedulerPhaseType,
+    listener: SchedulerPhaseListener,
+    options?: EventListenerOptions | boolean,
+  ): void
+  dequeue(): void
+}
 
 // Protect against infinite cascading updates (e.g. handle.update() during render)
 const MAX_CASCADING_UPDATES = 50
@@ -38,7 +54,7 @@ export function createScheduler(
   doc: Document,
   rootTarget: EventTarget,
   styles: StyleManager = defaultStyleManager,
-) {
+): Scheduler {
   let documentState = createDocumentState(doc)
   let scheduled = new Map<CommittedComponentNode, ParentNode>()
   let workTasks: EmptyFn[] = []
@@ -53,23 +69,7 @@ export function createScheduler(
     beforeUpdate: 0,
     commit: 0,
   }
-  let scheduler: {
-    enqueue(vnode: CommittedComponentNode, domParent: ParentNode): void
-    enqueueWork(newTasks: EmptyFn[]): void
-    enqueueCommitPhase(newTasks: EmptyFn[]): void
-    enqueueTasks(newTasks: EmptyFn[]): void
-    addEventListener(
-      type: SchedulerPhaseType,
-      listener: SchedulerPhaseListener,
-      options?: AddEventListenerOptions | boolean,
-    ): void
-    removeEventListener(
-      type: SchedulerPhaseType,
-      listener: SchedulerPhaseListener,
-      options?: EventListenerOptions | boolean,
-    ): void
-    dequeue(): void
-  }
+  let scheduler: Scheduler
 
   function dispatchError(error: unknown) {
     console.error(error)
@@ -137,7 +137,7 @@ export function createScheduler(
             // Needed for fragment self-updates that add children - without this, new children
             // would be appended after siblings. The keyed diff has placement logic, but unkeyed
             // diff relies on anchor for correct positioning.
-            let anchor = findNextSiblingDomAnchor(vnode, vParent) || undefined
+            let anchor = findNextSiblingDomAnchor(vnode) || undefined
             try {
               let updateStyles = getFrameStyleManager(vnode)
               renderComponent(

package/src/runtime/stream-protocol.ts

@@ -0,0 +1,27 @@
+export type FlushKind = 'document' | 'fragment'
+
+const FLUSH_MARKER_PATTERN = /<!--\s*rmx:flush\s+(document|fragment)\s*-->/g
+
+export function appendFlushMarker(html: string, kind: FlushKind): string {
+  return `${html}<!-- rmx:flush ${kind} -->`
+}
+
+export function stripFlushMarkers(html: string): string {
+  FLUSH_MARKER_PATTERN.lastIndex = 0
+  return html.replace(FLUSH_MARKER_PATTERN, '')
+}
+
+export function findFlushMarker(
+  html: string,
+  startIndex: number,
+): { index: number; endIndex: number; kind: FlushKind } | undefined {
+  FLUSH_MARKER_PATTERN.lastIndex = startIndex
+  let match = FLUSH_MARKER_PATTERN.exec(html)
+  if (!match) return undefined
+
+  return {
+    index: match.index,
+    endIndex: FLUSH_MARKER_PATTERN.lastIndex,
+    kind: match[1] as FlushKind,
+  }
+}

package/src/runtime/svg-attributes.ts

@@ -5,6 +5,7 @@ const CANONICAL_CAMEL_SVG_ATTRS = new Set([
   'accentHeight',
   'attributeName',
   'attributeType',
+  'autoReverse',
   'baseFrequency',
   'baseProfile',
   'calcMode',

package/src/runtime/to-vnode.ts

@@ -1,7 +1,8 @@
 import { Fragment } from './component.ts'
 import { invariant } from './invariant.ts'
+import { isEmptyChild, isPrimitiveChild, normalizeChildren } from './core/children.ts'
 import type { RemixElement, RemixNode } from './jsx.ts'
-import { isRemixElement, TEXT_NODE, type VNode } from './vnode.ts'
+import { isRemixElement, NON_RENDER_NODE, TEXT_NODE, type VNode } from './vnode.ts'
 
 function flatMapChildrenToVNodes(node: RemixElement): VNode[] {
   if (!('children' in node.props)) return []
@@ -13,21 +14,17 @@ function flatMapChildrenToVNodes(node: RemixElement): VNode[] {
 }
 
 function flattenChildrenToVNodes(nodes: RemixNode[], out: VNode[]): void {
-  for (let child of nodes) {
-    if (Array.isArray(child)) {
-      flattenChildrenToVNodes(child, out)
-    } else {
-      out.push(toVNode(child))
-    }
+  for (let child of normalizeChildren(nodes)) {
+    out.push(toVNode(child))
   }
 }
 
 export function toVNode(node: RemixNode): VNode {
-  if (node === null || node === undefined || typeof node === 'boolean') {
-    return { type: TEXT_NODE, _text: '' }
+  if (isEmptyChild(node)) {
+    return { type: NON_RENDER_NODE }
   }
 
-  if (typeof node === 'string' || typeof node === 'number' || typeof node === 'bigint') {
+  if (isPrimitiveChild(node)) {
     return { type: TEXT_NODE, _text: String(node) }
   }
 

package/src/runtime/vnode.ts

@@ -1,8 +1,12 @@
 import type { ComponentHandle, Component } from './component.ts'
 import { Fragment, Frame } from './component.ts'
-import type { ElementProps, RemixElement, RemixNode } from './jsx.ts'
+import { isRemixElement } from './core/vnode.ts'
+import type { ElementProps, RemixNode } from './jsx.ts'
+
+export { isRemixElement }
 
 export const TEXT_NODE = Symbol('TEXT_NODE')
+export const NON_RENDER_NODE = Symbol('NON_RENDER_NODE')
 export const ROOT_VNODE = Symbol('ROOT_VNODE')
 
 export type VNodeType =
@@ -10,6 +14,7 @@ export type VNodeType =
   | string // host element
   | Function // component
   | typeof TEXT_NODE
+  | typeof NON_RENDER_NODE
   | typeof Fragment
   | typeof Frame
 
@@ -25,6 +30,8 @@ export type VNode<T extends VNodeType = VNodeType> = {
   _dom?: unknown
   _controller?: AbortController
   _mixState?: unknown
+  _directEventDescriptors?: unknown
+  _directEventState?: unknown
   _controlledState?: unknown
   _svg?: boolean
   // Range roots render between comment boundary markers
@@ -37,10 +44,6 @@ export type VNode<T extends VNodeType = VNodeType> = {
   _frameResolveController?: AbortController
   _frameResolved?: boolean
 
-  // Internal diffing fields
-  _index?: number
-  _flags?: number
-
   // TEXT_NODE
   _text?: string
 
@@ -65,6 +68,10 @@ export type TextNode = VNode & {
   _text: string
 }
 
+export type NonRenderNode = VNode & {
+  type: typeof NON_RENDER_NODE
+}
+
 export type CommittedTextNode = TextNode & {
   _dom: Text
 }
@@ -101,6 +108,10 @@ export function isTextNode(node: VNode): node is TextNode {
   return node.type === TEXT_NODE
 }
 
+export function isNonRenderNode(node: VNode): node is NonRenderNode {
+  return node.type === NON_RENDER_NODE
+}
+
 export function isCommittedTextNode(node: VNode): node is CommittedTextNode {
   return isTextNode(node) && node._dom instanceof Text
 }
@@ -121,10 +132,6 @@ export function isCommittedComponentNode(node: VNode): node is CommittedComponen
   return isComponentNode(node) && node._content !== undefined
 }
 
-export function isRemixElement(node: RemixNode): node is RemixElement {
-  return typeof node === 'object' && node !== null && '$rmx' in node
-}
-
 export function findContextFromAncestry(node: VNode, type: Component): unknown {
   let current: VNode | undefined = node
   while (current) {

package/src/server/README.md

@@ -0,0 +1,90 @@
+# Server
+
+Remix UI can render to HTML on the server using two APIs:
+
+- `renderToString` - Returns a complete HTML string. Simple, but buffers the entire response.
+- `renderToStream` - Returns a `ReadableStream<Uint8Array>`. Sends the initial HTML immediately and streams frame content as it resolves.
+
+Both are exported from `remix/ui/server`.
+
+## renderToString
+
+Renders a component tree to a complete HTML string. Use this when you need the full output before responding (e.g., generating static pages or embedding HTML in an email).
+
+```tsx
+import { renderToString } from 'remix/ui/server'
+
+let html = await renderToString(<App />)
+```
+
+## renderToStream
+
+Renders a component tree to a streaming response. The initial HTML is sent immediately. Any `<Frame>` components with a `fallback` prop will render the fallback first, then stream the resolved content as it becomes available.
+
+```tsx
+import { renderToStream } from 'remix/ui/server'
+
+let stream = renderToStream(<App />, {
+  frameSrc: request.url,
+  signal: request.signal,
+  resolveFrame(src, _target, context) {
+    let frameUrl = new URL(src, context?.currentFrameSrc ?? request.url)
+    return fetchHtml(frameUrl)
+  },
+  onError(error) {
+    console.error(error)
+  },
+})
+
+return new Response(stream, {
+  headers: { 'Content-Type': 'text/html; charset=utf-8' },
+})
+```
+
+### Options
+
+- **`frameSrc`** - Seeds SSR frame state for the current render. When provided, server-rendered components can read `handle.frame.src` and `handle.frames.top.src` during SSR.
+- **`topFrameSrc`** - Overrides the root frame URL used for `handle.frames.top.src`. This is mainly useful when calling `renderToStream()` from inside `resolveFrame()` for a nested frame render.
+- **`signal`** - Cancels pending server rendering work. Pass `request.signal` so client disconnects can stop unresolved frame work without invoking `onError` for the disconnect itself.
+- **`resolveFrame(src, target, context)`** - Called when a `<Frame>` needs its content. Return a string of HTML, a `ReadableStream<Uint8Array>`, or a promise of either. `context.currentFrameSrc` is the URL for the frame that contains the `<Frame>`, and `context.topFrameSrc` is the outer document URL. Required if your component tree contains `<Frame>` elements.
+- **`onError(error)`** - Called when a rendering error occurs. If not provided, the stream rejects with the error.
+
+When you render nested frame responses with `renderToStream()` inside `resolveFrame()`, pass `frameSrc` for the frame being rendered and carry `topFrameSrc` forward from the parent context. That preserves `handle.frames.top.src` across the whole SSR frame tree.
+
+### Streaming behavior
+
+When the stream encounters a `<Frame>` component:
+
+- **Without `fallback`** (blocking): The frame content is awaited before the initial HTML chunk is sent. The resolved content appears inline.
+- **With `fallback`** (non-blocking): The fallback is rendered inline in the initial chunk. Once the frame resolves, a `<template>` element containing the real content is streamed at the end of the response. The client swaps it in automatically.
+
+This means the first chunk always contains a complete, renderable page. Slow data sources don't block the initial paint.
+
+## Head content
+
+To render content into the document head during SSR, use an explicit `<head>` element:
+
+```tsx
+function ProductPage() {
+  return () => (
+    <html>
+      <head>
+        <title>Product Name</title>
+        <meta name="description" content="A great product" />
+      </head>
+      <body>
+        <h1>Product Name</h1>
+      </body>
+    </html>
+  )
+}
+```
+
+## CSS
+
+Components using the `css(...)` mixin through `mix` have their styles collected during rendering and emitted as a single `<style>` tag in the `<head>`. No client-side style injection is needed for server-rendered content.
+
+## See Also
+
+- [Hydration](https://github.com/remix-run/remix/blob/main/packages/ui/docs/hydration.md) - Making server-rendered components interactive on the client
+- [Frames](https://github.com/remix-run/remix/blob/main/packages/ui/docs/frames.md) - Streaming partial server UI with `<Frame>`