@remix-run/ui 0.3.0 → 0.5.0

package/src/runtime/refresh.ts

@@ -0,0 +1,46 @@
+import type { VirtualRoot } from './vdom.ts'
+
+/**
+ * Reports whether an existing component instance must remount instead of reconciling during a
+ * development refresh.
+ *
+ * @param type Component function being considered for reuse.
+ * @returns `true` when existing instances must be remounted.
+ */
+export type ComponentStalenessCheck = (type: Function) => boolean
+
+export let componentStalenessCheck: ComponentStalenessCheck | null = null
+
+const roots = new Set<VirtualRoot>()
+
+/**
+ * Installs the process-wide component compatibility check used during development refreshes.
+ *
+ * When the check returns `true`, reconciliation replaces existing instances of that component
+ * instead of preserving their state. This is a low-level integration point for HMR runtimes.
+ *
+ * @param check Callback that returns `true` when instances of a component must be remounted.
+ */
+export function setComponentStalenessCheck(check: ComponentStalenessCheck): void {
+  componentStalenessCheck = check
+}
+
+export function registerRoot(root: VirtualRoot): void {
+  roots.add(root)
+}
+
+export function unregisterRoot(root: VirtualRoot): void {
+  roots.delete(root)
+}
+
+/**
+ * Immediately schedules reconciliation for every active Remix UI root using its current element.
+ *
+ * HMR runtimes call this after installing updated component implementations so mounted trees render
+ * the new code while preserving compatible component state.
+ */
+export function reconcileRoots(): void {
+  for (let root of roots) {
+    root.reconcile()
+  }
+}

package/src/runtime/run.ts

@@ -1,7 +1,7 @@
 import { createFrame, type Frame } from './frame.ts'
 import { createScheduler } from './vdom.ts'
 import { createStyleManager } from '../style/index.ts'
-import type { FrameHandle } from './component.ts'
+import type { FrameHandle, Handle } from './component.ts'
 import { createComponentErrorEvent } from './error-event.ts'
 import type { ComponentErrorEvent } from './error-event.ts'
 import type { LoadModule, ResolveFrame } from './frame.ts'
@@ -40,6 +40,8 @@ export type AppRuntimeEventMap = {
  * Client runtime returned by {@link run}.
  */
 export type AppRuntime = TypedEventTarget<AppRuntimeEventMap> & {
+  /** Access top-level and named frames in the application runtime. */
+  frames: Handle['frames']
   /** Resolves after the current document finishes hydrating. */
   ready(): Promise<void>
   /** Flushes any queued component updates synchronously. */
@@ -99,18 +101,26 @@ export function run(init: RunInit): AppRuntime {
   })
 
   let appController = new AbortController()
-  startNavigationListener(appController.signal)
+  let frames: Handle['frames'] = {
+    top: topFrame.handle,
+    get(name) {
+      return namedFrames.get(name)
+    },
+  }
+  startNavigationListener(appController.signal, init.resolveFrame !== undefined)
   let readyPromise = topFrame.ready().catch((error) => {
     errorTarget.dispatchEvent(createComponentErrorEvent(error))
     throw error
   })
 
   return Object.assign(errorTarget, {
+    frames,
     ready: () => readyPromise,
     flush: () => topFrame.flush(),
     dispose: () => {
       appController.abort()
       topFrame.dispose()
+      styleManager.dispose()
     },
   })
 }

package/src/runtime/scheduler.ts

@@ -1,6 +1,6 @@
 import { createDocumentState } from './document-state.ts'
 import { createComponentErrorEvent } from './error-event.ts'
-import type { CommittedComponentNode, VNode } from './vnode.ts'
+import type { CommittedComponentNode, VNodeParent } from './vnode.ts'
 import { isCommittedComponentNode } from './vnode.ts'
 import {
   findNextSiblingDomAnchor,
@@ -87,11 +87,6 @@ export function createScheduler(
     }, 0)
   }
 
-  function getFrameStyleManager(vnode: CommittedComponentNode): StyleManager {
-    let runtime = vnode._handle?.frame.$runtime as { styleManager?: StyleManager } | undefined
-    return runtime?.styleManager ?? styles
-  }
-
   function flush() {
     if (flushing) return
     flushing = true
@@ -126,32 +121,18 @@ export function createScheduler(
 
         if (batch.size > 0) {
           let vnodes = Array.from(batch)
-          let noScheduledAncestor = new Set<VNode>()
+          let noScheduledAncestor = new Set<VNodeParent>()
 
           for (let [vnode, domParent] of vnodes) {
             if (ancestorIsScheduled(vnode, batch, noScheduledAncestor)) continue
-            let handle = vnode._handle
             let curr = vnode._content
-            let vParent = vnode._parent!
             // Calculate anchor at render time from current vdom position (never stale).
             // 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) || undefined
             try {
-              let updateStyles = getFrameStyleManager(vnode)
-              renderComponent(
-                handle,
-                curr,
-                vnode,
-                domParent,
-                handle.frame,
-                scheduler,
-                updateStyles,
-                rootTarget,
-                vParent,
-                anchor,
-              )
+              renderComponent(curr, vnode, domParent, vnode._context, anchor)
             } catch (error) {
               dispatchError(error)
             }
@@ -177,8 +158,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
+    let event: SchedulerPhaseEvent = Object.assign(new Event(type), { parents })
     phaseEvents.dispatchEvent(event)
   }
 
@@ -201,12 +181,12 @@ export function createScheduler(
   }
 
   function ancestorIsScheduled(
-    vnode: VNode,
+    vnode: CommittedComponentNode,
     batch: Map<CommittedComponentNode, ParentNode>,
-    safe: Set<VNode>,
+    safe: Set<VNodeParent>,
   ): boolean {
-    let path: VNode[] = []
-    let current = vnode._parent
+    let path: VNodeParent[] = []
+    let current: VNodeParent | undefined = vnode._parent
 
     while (current) {
       // Already verified this node has no scheduled ancestor above it
@@ -221,7 +201,7 @@ export function createScheduler(
         return true
       }
 
-      current = current._parent
+      current = current.kind === 'root' ? undefined : current._parent
     }
 
     // Reached root - mark entire path as safe for future lookups

package/src/runtime/to-vnode.ts

@@ -1,48 +1,110 @@
 import { Fragment } from './component.ts'
+import { Frame } 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, NON_RENDER_NODE, TEXT_NODE, type VNode } from './vnode.ts'
+import { isEmptyChild, isPrimitiveChild, isRemixNode, normalizeChildren } from './core/children.ts'
+import type { RemixNode } from './jsx.ts'
+import type { ElementFunction } from './element-function.ts'
+import type { FrameProps } from './component.ts'
+import { isMixinDescriptor } from './mixins/mixin.ts'
+import {
+  isRemixElement,
+  NON_RENDER_NODE,
+  TEXT_NODE,
+  type RuntimeElementProps,
+  type RuntimeHostProps,
+  type VNodeInput,
+} from './vnode.ts'
 
-function flatMapChildrenToVNodes(node: RemixElement): VNode[] {
-  if (!('children' in node.props)) return []
-  let children = node.props.children
+function flatMapChildrenToVNodes(props: RuntimeHostProps): VNodeInput[] {
+  let children = props.children
+  if (children === undefined) return []
   if (!Array.isArray(children)) return [toVNode(children)]
-  let vnodes: VNode[] = []
+  let vnodes: VNodeInput[] = []
   flattenChildrenToVNodes(children, vnodes)
   return vnodes
 }
 
-function flattenChildrenToVNodes(nodes: RemixNode[], out: VNode[]): void {
-  for (let child of normalizeChildren(nodes)) {
-    out.push(toVNode(child))
+function flattenChildrenToVNodes(nodes: RemixNode[], out: VNodeInput[]): void {
+  let children = normalizeChildren(nodes)
+  for (let i = 0; i < children.length; i++) {
+    out.push(toVNode(children[i]))
   }
 }
 
-export function toVNode(node: RemixNode): VNode {
+export function toVNode(node: RemixNode): VNodeInput {
   if (isEmptyChild(node)) {
-    return { type: NON_RENDER_NODE }
+    return { kind: 'empty', type: NON_RENDER_NODE }
   }
 
   if (isPrimitiveChild(node)) {
-    return { type: TEXT_NODE, _text: String(node) }
+    return { kind: 'text', type: TEXT_NODE, _text: String(node) }
+  }
+
+  if (isRemixElement(node)) {
+    if (node.type === Fragment) {
+      let props = parseHostProps(node.props)
+      return {
+        kind: 'fragment',
+        type: Fragment,
+        key: node.key,
+        _children: flatMapChildrenToVNodes(props),
+      }
+    }
+
+    if (node.type === Frame) {
+      invariant(isFrameProps(node.props), '<Frame /> requires a src prop')
+      return { kind: 'frame', type: Frame, key: node.key, props: node.props }
+    }
+
+    if (typeof node.type === 'string') {
+      let props = parseHostProps(node.props)
+      // When innerHTML is set, ignore children
+      let children = props.innerHTML != null ? [] : flatMapChildrenToVNodes(props)
+      return {
+        kind: 'host',
+        type: node.type,
+        key: node.key,
+        props,
+        _children: children,
+      }
+    }
+    invariant(isElementFunction(node.type), 'Expected component element type')
+    return { kind: 'component', type: node.type, key: node.key, props: node.props }
   }
 
   if (Array.isArray(node)) {
-    let children: VNode[] = []
+    let children: VNodeInput[] = []
     flattenChildrenToVNodes(node, children)
-    return { type: Fragment, _children: children }
+    return { kind: 'fragment', type: Fragment, _children: children }
   }
 
-  if (node.type === Fragment) {
-    return { type: Fragment, key: node.key, _children: flatMapChildrenToVNodes(node) }
-  }
+  invariant(false, 'Unexpected RemixNode')
+}
 
-  if (isRemixElement(node)) {
-    // When innerHTML is set, ignore children
-    let children = node.props.innerHTML != null ? [] : flatMapChildrenToVNodes(node)
-    return { type: node.type, key: node.key, props: node.props, _children: children }
+function isFrameProps(props: RuntimeElementProps): props is RuntimeElementProps & FrameProps {
+  return typeof props.src === 'string' && props.src.length > 0
+}
+
+function parseHostProps(props: RuntimeElementProps): RuntimeHostProps {
+  let children = props.children
+  invariant(children === undefined || isRemixNode(children), 'Invalid host children')
+
+  let innerHTML = props.innerHTML
+  invariant(innerHTML === undefined || typeof innerHTML === 'string', 'Invalid innerHTML prop')
+
+  let mix = props.mix
+  invariant(mix === undefined || isRuntimeMixValue(mix), 'Invalid mix prop')
+  return props
+}
+
+function isRuntimeMixValue(value: unknown): value is RuntimeHostProps['mix'] {
+  if (!Array.isArray(value)) return isMixinDescriptor(value)
+  for (let descriptor of value) {
+    if (!isMixinDescriptor(descriptor)) return false
   }
+  return true
+}
 
-  invariant(false, 'Unexpected RemixNode')
+function isElementFunction(value: unknown): value is ElementFunction {
+  return typeof value === 'function'
 }

package/src/runtime/vdom.ts

@@ -1,7 +1,8 @@
-import type { FrameContent, FrameHandle } from './component.ts'
+import type { FrameHandle } from './component.ts'
 import { createFrameHandle } from './component.ts'
 import { invariant } from './invariant.ts'
 import type { RemixNode } from './jsx.ts'
+import { createFrameRuntime, type ResolveFrame } from './frame.ts'
 import {
   createComponentErrorEvent,
   getComponentError,
@@ -11,8 +12,9 @@ import { createScheduler, type Scheduler } from './scheduler.ts'
 import { diffVNodes, remove as removeVNode } from './reconcile.ts'
 import { toVNode } from './to-vnode.ts'
 import { TypedEventTarget } from './typed-event-target.ts'
-import { ROOT_VNODE, type VNode } from './vnode.ts'
+import { ROOT_VNODE, type CommittedVNode, type ReconcileContext, type RootVNode } from './vnode.ts'
 import { resetStyleState, defaultStyleManager } from './diff-props.ts'
+import { registerRoot, unregisterRoot } from './refresh.ts'
 import type { StyleManager } from '../style/index.ts'
 
 /**
@@ -27,6 +29,7 @@ export type VirtualRootEventMap = {
  */
 export type VirtualRoot = TypedEventTarget<VirtualRootEventMap> & {
   render: (element: RemixNode) => void
+  reconcile: () => void
   dispose: () => void
   flush: () => void
 }
@@ -40,11 +43,7 @@ export type VirtualRootOptions = {
   styleManager?: StyleManager
   frameInit?: {
     src?: string
-    resolveFrame: (
-      src: string,
-      signal?: AbortSignal,
-      target?: string,
-    ) => Promise<FrameContent> | FrameContent
+    resolveFrame: ResolveFrame
     loadModule?: (moduleUrl: string, exportName: string) => Promise<Function> | Function
   }
 }
@@ -73,7 +72,8 @@ export function createRangeRoot(
   options: VirtualRootOptions = {},
 ): VirtualRoot {
   let [start, end] = boundaries
-  let vroot: VNode | null = null
+  let vroot: CommittedVNode | null = null
+  let currentElement: RemixNode | undefined
   let styles = options.styleManager ?? defaultStyleManager
 
   let container = end.parentNode
@@ -96,6 +96,12 @@ export function createRangeRoot(
       scheduler,
       styleManager: styles,
     })
+  let context: ReconcileContext = {
+    frame: frameStub,
+    scheduler,
+    styles,
+    rootTarget: eventTarget,
+  }
 
   let isErrorForwardingAttached = false
   function forwardDomError(event: Event) {
@@ -113,13 +119,16 @@ export function createRangeRoot(
   }
   attachDomErrorForwarding()
 
-  return Object.assign(eventTarget, {
+  let root = Object.assign(eventTarget, {
     render(element: RemixNode) {
       attachDomErrorForwarding()
+      currentElement = element
 
       let vnode = toVNode(element)
-      let vParent: VNode = {
+      let vParent: RootVNode = {
+        kind: 'root',
         type: ROOT_VNODE,
+        _children: [],
         _svg: false,
         _rangeStart: start,
         _rangeEnd: end,
@@ -127,32 +136,30 @@ export function createRangeRoot(
       }
       scheduler.enqueueWork([
         () => {
-          diffVNodes(
-            vroot,
-            vnode,
-            parent,
-            frameStub,
-            scheduler,
-            styles,
-            vParent,
-            eventTarget,
-            end,
-            hydrationCursor,
-          )
-          vroot = vnode
+          let cursor = hydrationCursor === null ? undefined : { current: hydrationCursor }
+          let committed = diffVNodes(vroot, vnode, parent, vParent, context, end, cursor)
+          vParent._children = [committed]
+          vroot = committed
           hydrationCursor = null
         },
       ])
       scheduler.dequeue()
     },
 
+    reconcile() {
+      if (currentElement === undefined) return
+      root.render(currentElement)
+    },
+
     dispose() {
       detachDomErrorForwarding()
+      unregisterRoot(root)
+      currentElement = undefined
 
       if (!vroot) return
       let current = vroot
       vroot = null
-      scheduler.enqueueWork([() => removeVNode(current, parent, scheduler, styles)])
+      scheduler.enqueueWork([() => removeVNode(current, parent, context)])
       scheduler.dequeue()
     },
 
@@ -160,6 +167,9 @@ export function createRangeRoot(
       scheduler.dequeue()
     },
   })
+
+  registerRoot(root)
+  return root
 }
 
 /**
@@ -170,8 +180,15 @@ export function createRangeRoot(
  * @returns A virtual root controller.
  */
 export function createRoot(container: HTMLElement, options: VirtualRootOptions = {}): VirtualRoot {
-  let vroot: VNode | null = null
+  let vroot: CommittedVNode | null = null
+  let currentElement: RemixNode | undefined
   let styles = options.styleManager ?? defaultStyleManager
+  if (container.innerHTML.trim() !== '') {
+    // Adopt additively: multiple roots hydrating separate islands may share
+    // the default style manager, and adopting a later island must not release
+    // the server styles an earlier island still depends on.
+    styles.adoptServerStyles(container)
+  }
   let hydrationCursor = container.innerHTML.trim() !== '' ? container.firstChild : undefined
 
   let eventTarget = new TypedEventTarget<VirtualRootEventMap>()
@@ -187,6 +204,12 @@ export function createRoot(container: HTMLElement, options: VirtualRootOptions =
       scheduler,
       styleManager: styles,
     })
+  let context: ReconcileContext = {
+    frame: frameStub,
+    scheduler,
+    styles,
+    rootTarget: eventTarget,
+  }
 
   let isErrorForwardingAttached = false
   function forwardDomError(event: Event) {
@@ -204,40 +227,44 @@ export function createRoot(container: HTMLElement, options: VirtualRootOptions =
   }
   attachDomErrorForwarding()
 
-  return Object.assign(eventTarget, {
+  let root = Object.assign(eventTarget, {
     render(element: RemixNode) {
       attachDomErrorForwarding()
+      currentElement = element
 
       let vnode = toVNode(element)
-      let vParent: VNode = { type: ROOT_VNODE, _svg: false }
+      let vParent: RootVNode = {
+        kind: 'root',
+        type: ROOT_VNODE,
+        _children: [],
+        _svg: false,
+      }
       scheduler.enqueueWork([
         () => {
-          diffVNodes(
-            vroot,
-            vnode,
-            container,
-            frameStub,
-            scheduler,
-            styles,
-            vParent,
-            eventTarget,
-            undefined,
-            hydrationCursor,
-          )
-          vroot = vnode
+          let cursor = hydrationCursor === undefined ? undefined : { current: hydrationCursor }
+          let committed = diffVNodes(vroot, vnode, container, vParent, context, undefined, cursor)
+          vParent._children = [committed]
+          vroot = committed
           hydrationCursor = undefined
         },
       ])
       scheduler.dequeue()
     },
 
+    reconcile() {
+      if (currentElement === undefined) return
+      root.render(currentElement)
+    },
+
     dispose() {
       detachDomErrorForwarding()
+      unregisterRoot(root)
+      currentElement = undefined
 
       if (!vroot) return
       let current = vroot
       vroot = null
-      scheduler.enqueueWork([() => removeVNode(current, container, scheduler, styles)])
+      scheduler.enqueueWork([() => removeVNode(current, container, context)])
       scheduler.dequeue()
     },
 
@@ -245,15 +272,14 @@ export function createRoot(container: HTMLElement, options: VirtualRootOptions =
       scheduler.dequeue()
     },
   })
+
+  registerRoot(root)
+  return root
 }
 
 function createRootFrameHandle(init: {
   src?: string
-  resolveFrame?: (
-    src: string,
-    signal?: AbortSignal,
-    target?: string,
-  ) => Promise<FrameContent> | FrameContent
+  resolveFrame?: ResolveFrame
   loadModule?: (moduleUrl: string, exportName: string) => Promise<Function> | Function
   errorTarget: EventTarget
   scheduler: Scheduler
@@ -267,29 +293,25 @@ function createRootFrameHandle(init: {
       )
     })
 
-  let frame = createFrameHandle({
-    src: init.src ?? '/',
-    $runtime: {
-      canResolveFrames: !!init.resolveFrame,
-      topFrame: undefined,
-      loadModule:
-        init.loadModule ??
-        (() => {
-          throw new Error('loadModule is required to hydrate client entries inside <Frame />')
-        }),
-      resolveFrame,
-      errorTarget: init.errorTarget,
-      pendingClientEntries: new Map(),
-      scheduler: init.scheduler,
-      styleManager: init.styleManager,
-      data: {},
-      moduleCache: new Map(),
-      moduleLoads: new Map(),
-      frameInstances: new WeakMap(),
-      namedFrames: new Map(),
-    },
+  let runtime = createFrameRuntime({
+    topFrame: undefined,
+    loadModule:
+      init.loadModule ??
+      (() => {
+        throw new Error('loadModule is required to hydrate client entries inside <Frame />')
+      }),
+    resolveFrame,
+    errorTarget: init.errorTarget,
+    pendingClientEntries: new Map(),
+    scheduler: init.scheduler,
+    styleManager: init.styleManager,
+    moduleCache: new Map(),
+    moduleLoads: new Map(),
+    frameInstances: new WeakMap(),
+    namedFrames: new Map(),
   })
-  let runtime = frame.$runtime as { topFrame?: FrameHandle } | undefined
-  if (runtime) runtime.topFrame = frame
+  runtime.canResolveFrames = !!init.resolveFrame
+  let frame = createFrameHandle({ src: init.src ?? '/', $runtime: runtime })
+  runtime.topFrame = frame
   return frame
 }