@remix-run/ui 0.1.0 → 0.1.2

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

@@ -49,6 +49,10 @@ export function createScheduler(
   let cascadingUpdateCount = 0
   let resetScheduled = false
   let phaseEvents = new EventTarget()
+  let phaseListenerCounts: Record<SchedulerPhaseType, number> = {
+    beforeUpdate: 0,
+    commit: 0,
+  }
   let scheduler: {
     enqueue(vnode: CommittedComponentNode, domParent: ParentNode): void
     enqueueWork(newTasks: EmptyFn[]): void
@@ -172,6 +176,7 @@ export function createScheduler(
   }
 
   function dispatchPhaseEvent(type: SchedulerPhaseType, parents: ParentNode[]) {
+    if (phaseListenerCounts[type] === 0) return
     let event = new Event(type) as SchedulerPhaseEvent
     event.parents = parents
     phaseEvents.dispatchEvent(event)
@@ -246,10 +251,12 @@ export function createScheduler(
     },
 
     addEventListener(type, listener, options) {
+      if (listener) phaseListenerCounts[type]++
       phaseEvents.addEventListener(type, listener, options)
     },
 
     removeEventListener(type, listener, options) {
+      if (listener) phaseListenerCounts[type] = Math.max(0, phaseListenerCounts[type] - 1)
       phaseEvents.removeEventListener(type, listener, options)
     },
 

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/to-vnode.ts

@@ -1,39 +1,37 @@
 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'
 
 function flatMapChildrenToVNodes(node: RemixElement): VNode[] {
-  return 'children' in node.props
-    ? Array.isArray(node.props.children)
-      ? node.props.children.flat(Infinity).map(toVNode)
-      : [toVNode(node.props.children)]
-    : []
+  if (!('children' in node.props)) return []
+  let children = node.props.children
+  if (!Array.isArray(children)) return [toVNode(children)]
+  let vnodes: VNode[] = []
+  flattenChildrenToVNodes(children, vnodes)
+  return vnodes
 }
 
-function flattenRemixNodeArray(nodes: RemixNode[], out: RemixNode[] = []): RemixNode[] {
-  for (let child of nodes) {
-    if (Array.isArray(child)) {
-      flattenRemixNodeArray(child, out)
-    } else {
-      out.push(child)
-    }
+function flattenChildrenToVNodes(nodes: RemixNode[], out: VNode[]): void {
+  for (let child of normalizeChildren(nodes)) {
+    out.push(toVNode(child))
   }
-  return out
 }
 
 export function toVNode(node: RemixNode): VNode {
-  if (node === null || node === undefined || typeof node === 'boolean') {
+  if (isEmptyChild(node)) {
     return { type: TEXT_NODE, _text: '' }
   }
 
-  if (typeof node === 'string' || typeof node === 'number' || typeof node === 'bigint') {
+  if (isPrimitiveChild(node)) {
     return { type: TEXT_NODE, _text: String(node) }
   }
 
   if (Array.isArray(node)) {
-    let flatChildren = flattenRemixNodeArray(node)
-    return { type: Fragment, _children: flatChildren.map(toVNode) }
+    let children: VNode[] = []
+    flattenChildrenToVNodes(node, children)
+    return { type: Fragment, _children: children }
   }
 
   if (node.type === Fragment) {

package/src/runtime/vnode.ts

@@ -1,6 +1,9 @@
 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 ROOT_VNODE = Symbol('ROOT_VNODE')
@@ -25,6 +28,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 +42,6 @@ export type VNode<T extends VNodeType = VNodeType> = {
   _frameResolveController?: AbortController
   _frameResolved?: boolean
 
-  // Internal diffing fields
-  _index?: number
-  _flags?: number
-
   // TEXT_NODE
   _text?: string
 
@@ -121,10 +122,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,88 @@
+# Server
+
+Remix Component 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,
+  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.
+- **`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` prop 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>`

package/src/server/stream.ts

@@ -2,7 +2,14 @@ import type { ComponentHandle, FrameHandle, Key, RemixNode } from '../runtime/co
 import type { ElementType, ElementProps, RemixElement } from '../runtime/jsx.ts'
 import { Fragment, createComponent, createFrameHandle, Frame } from '../runtime/component.ts'
 import { isEntry, type EntryComponent } from '../runtime/client-entries.ts'
-import { normalizeSvgAttribute } from '../runtime/svg-attributes.ts'
+import {
+  FRAMEWORK_PROPS as RUNTIME_FRAMEWORK_PROPS,
+  SELF_CLOSING_TAGS,
+  normalizeAttributeName,
+  serializeStyleObject,
+} from '../runtime/core/attributes.ts'
+import { appendFlushMarker, type FlushKind, stripFlushMarkers } from '../runtime/stream-protocol.ts'
+import { REMIX_UI_STYLE_LAYER } from '../style/layers.ts'
 
 interface VNode {
   type: ElementType
@@ -90,6 +97,7 @@ interface RenderContext {
   unresolvedHydrationData: Map<string, UnresolvedHydrationData>
   frameData: Map<string, FrameData>
   blockingFrameTails: ReadableStream<Uint8Array>[]
+  flushKind: FlushKind
   serverIdScope: string
   serverIdCounter: number
 }
@@ -114,49 +122,32 @@ type Segment =
       pending?: Promise<void>
     }
 
-const SELF_CLOSING_TAGS = new Set([
-  'area',
-  'base',
-  'br',
-  'col',
-  'embed',
-  'hr',
-  'img',
-  'input',
-  'link',
-  'meta',
-  'param',
-  'source',
-  'track',
-  'wbr',
-])
-
-const DEFAULT_STYLE_LAYER = 'rmx'
-
-function getStyleLayerName(selector: string, layer: string = DEFAULT_STYLE_LAYER): string {
+const TEXTAREA_VALUE_PROPS = new Set(['value', 'defaultValue'])
+const INPUT_DEFAULT_PROPS = new Set(['defaultValue', 'defaultChecked'])
+
+const DOCTYPE_PATTERN = /<!doctype(?:\s[^>]*)?>/gi
+
+function stripDoctypeMarkup(html: string): string {
+  return html.replace(DOCTYPE_PATTERN, '')
+}
+
+function hasRenderableHtml(html: string): boolean {
+  return stripDoctypeMarkup(html).trim() !== ''
+}
+
+function emptyReadableStream(): ReadableStream<Uint8Array> {
+  return new ReadableStream({
+    start(controller) {
+      controller.close()
+    },
+  })
+}
+
+function getStyleLayerName(selector: string, layer: string = REMIX_UI_STYLE_LAYER): string {
   return `${layer}.${selector}`
 }
 
-const NUMERIC_CSS_PROPS = new Set([
-  'z-index',
-  'opacity',
-  'flex-grow',
-  'flex-shrink',
-  'flex-order',
-  'grid-area',
-  'grid-row',
-  'grid-column',
-  'font-weight',
-  'line-height',
-  'order',
-  'orphans',
-  'widows',
-  'zoom',
-  'columns',
-  'column-count',
-])
-
-const FRAMEWORK_PROPS = new Set(['children', 'innerHTML', 'on', 'key', 'mix'])
+const SSR_OMITTED_PROPS = RUNTIME_FRAMEWORK_PROPS
 
 const ssrSignal = Object.freeze({
   get aborted() {
@@ -213,6 +204,7 @@ export function renderToStream(
     unresolvedHydrationData: new Map(),
     frameData: new Map(),
     blockingFrameTails: [],
+    flushKind: 'fragment',
     serverIdScope: crypto.randomUUID().slice(0, 8),
     serverIdCounter: 0,
   }
@@ -226,7 +218,7 @@ export function renderToStream(
         validateClientEntriesForHydration(context)
         let html = serializeSegment(root)
         let finalHtml = finalizeHtml(html, context)
-        let bytes = encoder.encode(finalHtml)
+        let bytes = encoder.encode(appendFlushMarker(finalHtml, context.flushKind))
         controller.enqueue(bytes)
 
         // If we have any tails from blocking frame streams, stream them now.
@@ -284,24 +276,28 @@ function createServerComponentId(context: RenderContext): string {
   return `s${context.serverIdScope}-${context.serverIdCounter}`
 }
 
-async function splitFirstChunk(
-  stream: ReadableStream<Uint8Array>,
-): Promise<{ first: Uint8Array; tail: ReadableStream<Uint8Array> }> {
+async function splitFirstChunk(stream: ReadableStream<Uint8Array>): Promise<ResolvedFrameHtml> {
   let reader = stream.getReader()
+  let decoder = new TextDecoder()
 
-  let { value, done } = await reader.read()
-  if (done || !value) {
-    reader.releaseLock()
-    return {
-      first: new Uint8Array(),
-      tail: new ReadableStream({
-        start(controller) {
-          controller.close()
-        },
-      }),
+  let first: Uint8Array | undefined
+  while (true) {
+    let { value, done } = await reader.read()
+    if (done || !value) break
+
+    let text = decoder.decode(value, { stream: true })
+    if (hasRenderableHtml(text)) {
+      first = value
+      break
     }
   }
 
+  if (!first) {
+    decoder.decode()
+    reader.releaseLock()
+    return { html: '', tail: emptyReadableStream() }
+  }
+
   let released = false
   function release() {
     if (released) return
@@ -329,17 +325,15 @@ async function splitFirstChunk(
     },
   })
 
-  return { first: value, tail }
+  return { html: stripFlushMarkers(stripDoctypeMarkup(decoder.decode(first))), tail }
 }
 
 async function resolveFrameHtml(
   input: string | ReadableStream<Uint8Array>,
 ): Promise<ResolvedFrameHtml> {
-  if (typeof input === 'string') return { html: input }
+  if (typeof input === 'string') return { html: stripFlushMarkers(stripDoctypeMarkup(input)) }
 
-  let decoder = new TextDecoder()
-  let { first, tail } = await splitFirstChunk(input)
-  return { html: decoder.decode(first), tail }
+  return await splitFirstChunk(input)
 }
 
 function isRemixElement(node: unknown): node is RemixElement {
@@ -380,6 +374,7 @@ function buildSegment(node: RemixNode, context: RenderContext, frameState: SsrFr
       let tag = type
 
       if (tag === 'html') {
+        context.flushKind = 'document'
         return buildElementSegment(tag, props, context, frameState)
       }
 
@@ -459,7 +454,15 @@ function buildElementSegment(
   let processedProps = processStyleProps(mixedProps)
   // Determine namespace context for the current element and its children
   let currentIsSvg = context.insideSvg || tag === 'svg'
-  let attrs = renderAttributes(processedProps, currentIsSvg)
+
+  if (!currentIsSvg && tag === 'textarea') {
+    return buildTextareaElementSegment(tag, processedProps)
+  }
+
+  let attrs =
+    !currentIsSvg && tag === 'input'
+      ? renderInputAttributes(processedProps)
+      : renderAttributes(processedProps, currentIsSvg)
 
   if (SELF_CLOSING_TAGS.has(tag)) {
     return staticSeg(`<${tag}${attrs} />`)
@@ -480,6 +483,27 @@ function buildElementSegment(
   return compositeSeg([open, children, close])
 }
 
+function buildTextareaElementSegment(tag: string, props: any): Segment {
+  let attrs = renderAttributes(props, false, TEXTAREA_VALUE_PROPS)
+  let value = props.value ?? props.defaultValue ?? ''
+  return staticSeg(`<${tag}${attrs}>${escapeTextContent(String(value))}</${tag}>`)
+}
+
+function renderInputAttributes(props: any): string {
+  let value =
+    props.value === undefined && props.defaultValue !== undefined ? props.defaultValue : props.value
+  let checked =
+    props.checked === undefined && props.defaultChecked !== undefined
+      ? props.defaultChecked
+      : props.checked
+  let inputProps = {
+    ...props,
+    ...(value === undefined ? {} : { value }),
+    ...(checked === undefined ? {} : { checked }),
+  }
+  return renderAttributes(inputProps, false, INPUT_DEFAULT_PROPS)
+}
+
 function buildHeadElementSegment(
   tag: string,
   props: any,
@@ -497,11 +521,12 @@ function buildHeadElementSegment(
   return compositeSeg([open, children, close])
 }
 
-function renderAttributes(props: any, isSvg: boolean): string {
+function renderAttributes(props: any, isSvg: boolean, excludedProps?: Set<string>): string {
   let attrs = ''
 
   for (let key in props) {
-    if (FRAMEWORK_PROPS.has(key)) continue
+    if (SSR_OMITTED_PROPS.has(key)) continue
+    if (excludedProps?.has(key)) continue
 
     let value = props[key]
     if (value === undefined || value === null || value === false) continue
@@ -793,7 +818,11 @@ function buildComponentSegment(
   let [renderedNode] = handle.render(props)
   let childContext = { ...context, parentVNode: vnode }
 
-  return buildSegment(renderedNode, childContext, frameState)
+  let rendered = buildSegment(renderedNode, childContext, frameState)
+  if (childContext.flushKind === 'document') {
+    context.flushKind = 'document'
+  }
+  return rendered
 }
 
 function createHydrationPropsReplacer(context: RenderContext, frameState: SsrFrameState) {
@@ -1058,24 +1087,11 @@ function escapeTemplateContent(html: string): string {
 }
 
 function transformAttributeName(name: string, isSvg: boolean): string {
-  // aria-/data- pass through
-  if (name.startsWith('aria-') || name.startsWith('data-')) return name
-
-  // HTML mappings
-  if (name === 'className') return 'class'
-  if (!isSvg) {
-    if (name === 'htmlFor') return 'for'
-    if (name === 'tabIndex') return 'tabindex'
-    if (name === 'acceptCharset') return 'accept-charset'
-    if (name === 'httpEquiv') return 'http-equiv'
-    return name.toLowerCase()
-  }
-
-  return normalizeSvgAttribute(name).attr
+  return normalizeAttributeName(name, isSvg).attr
 }
 
 function finalizeHtml(html: string, context: RenderContext): string {
-  let hasHtmlRoot = html.trimStart().toLowerCase().startsWith('<html')
+  let hasHtmlRoot = context.flushKind === 'document'
 
   let styles = collectStyleTags(context)
   if (styles) {
@@ -1159,7 +1175,7 @@ function collectStyleTags(context: RenderContext): string {
 function wrapStyleForLayer(
   selector: string,
   css: string,
-  layer: string = DEFAULT_STYLE_LAYER,
+  layer: string = REMIX_UI_STYLE_LAYER,
 ): string {
   let trimmed = css.trim()
   if (!trimmed) return ''
@@ -1169,7 +1185,7 @@ function wrapStyleForLayer(
 function renderStyleTag(
   selector: string,
   css: string,
-  layer: string = DEFAULT_STYLE_LAYER,
+  layer: string = REMIX_UI_STYLE_LAYER,
 ): string {
   let wrappedCss = wrapStyleForLayer(selector, css, layer)
   if (!wrappedCss) return ''
@@ -1220,36 +1236,6 @@ function escapeScriptJson(json: string): string {
   return json.replace(/</g, '\\u003c')
 }
 
-function serializeStyleObject(style: Record<string, any>): string {
-  let parts: string[] = []
-
-  for (let [key, value] of Object.entries(style)) {
-    if (value == null) continue
-    if (typeof value === 'boolean') continue
-    if (typeof value === 'number' && !Number.isFinite(value)) continue
-
-    // Convert camelCase to kebab-case
-    let cssKey = key.replace(/[A-Z]/g, (m) => `-${m.toLowerCase()}`)
-
-    // Add px to numeric values where appropriate
-    let shouldAppendPx =
-      typeof value === 'number' &&
-      value !== 0 &&
-      !NUMERIC_CSS_PROPS.has(cssKey) &&
-      !cssKey.startsWith('--')
-
-    let cssValue = shouldAppendPx
-      ? `${value}px`
-      : Array.isArray(value)
-        ? value.join(', ')
-        : String(value)
-
-    parts.push(`${cssKey}: ${cssValue};`)
-  }
-
-  return parts.join(' ')
-}
-
 // Frame styles work end-to-end when frame handlers use their own `renderToStream`:
 // the handler's `finalizeHtml` emits selector-addressed `<style>` tags in its HTML, and on the client,
 // the `adoptServerStyleTag` MutationObserver (stylesheet.ts) picks it up anywhere in the
@@ -1332,11 +1318,13 @@ async function drain(stream: ReadableStream<Uint8Array>): Promise<string> {
  * @returns Rendered HTML.
  */
 export async function renderToString(node: RemixNode): Promise<string> {
-  return drain(
-    renderToStream(node, {
-      onError(error) {
-        throw error
-      },
-    }),
+  return stripFlushMarkers(
+    await drain(
+      renderToStream(node, {
+        onError(error) {
+          throw error
+        },
+      }),
+    ),
   )
 }

package/src/style/layers.ts

@@ -0,0 +1,2 @@
+export const REMIX_UI_STYLE_LAYER = 'rmx'
+export const REMIX_UI_RESET_LAYER = 'rmx-reset'