@remix-run/ui 0.0.0 → 0.1.0

package/src/runtime/render.ts

@@ -0,0 +1,101 @@
+import type { RemixNode } from './jsx.ts'
+import { createRoot, type VirtualRoot, type VirtualRootOptions } from './vdom.ts'
+
+/**
+ * Options for {@link render}.
+ */
+export interface RenderOptions extends VirtualRootOptions {
+  /**
+   * The element to mount the component into. Defaults to a fresh `div` appended to
+   * `document.body`.
+   */
+  container?: HTMLElement
+}
+
+/**
+ * Result returned by {@link render}.
+ */
+export interface RenderResult {
+  /**
+   * The element the component is mounted into.
+   */
+  container: HTMLElement
+
+  /**
+   * The {@link VirtualRoot} the component is rendered in. Use it to access the
+   * underlying scheduler or dispatch lifecycle events.
+   */
+  root: VirtualRoot
+
+  /**
+   * Shorthand for `container.querySelector<HTMLElement>(selector)`.
+   */
+  $: (selector: string) => HTMLElement | null
+
+  /**
+   * Shorthand for `container.querySelectorAll<HTMLElement>(selector)`.
+   */
+  $$: (selector: string) => NodeListOf<HTMLElement>
+
+  /**
+   * Runs `fn` and then flushes any pending component updates so the DOM reflects them
+   * before the next assertion.
+   */
+  act: (fn: () => unknown | Promise<unknown>) => Promise<void>
+
+  /**
+   * Disposes the root and removes the container from the DOM. Pass to `t.after()` for
+   * automatic cleanup at the end of a test.
+   */
+  cleanup: () => void
+}
+
+/**
+ * Mounts a {@link RemixNode} into a DOM container for testing.
+ *
+ * @param node - The node to render
+ * @param opts - {@link RenderOptions}; pass `opts.container` to render into a specific
+ *   element instead of a fresh `div` appended to `document.body`
+ * @returns A {@link RenderResult} with the container, root, and helpers for querying and
+ *   interacting with the rendered output.
+ */
+export function render(node: RemixNode, opts: RenderOptions = {}): RenderResult {
+  let { container: userContainer, ...virtualRootOpts } = opts
+
+  let container: HTMLElement | undefined
+  if (userContainer) {
+    container = userContainer
+  } else {
+    container = document.createElement('div')
+    document.body.appendChild(container)
+  }
+
+  let root: VirtualRoot | undefined = createRoot(container, virtualRootOpts)
+  root.render(node)
+  root.flush()
+
+  let ctx: RenderResult = {
+    get container() {
+      if (!container) throw new Error('Test container has already been cleaned up')
+      return container
+    },
+    get root() {
+      if (!root) throw new Error('Test root has already been cleaned up')
+      return root
+    },
+    $: (s: string) => ctx.container.querySelector<HTMLElement>(s),
+    $$: (s: string) => ctx.container.querySelectorAll<HTMLElement>(s),
+    async act(fn: () => unknown | Promise<unknown>) {
+      await fn()
+      ctx.root.flush()
+    },
+    cleanup() {
+      root?.dispose()
+      container?.remove()
+      container = undefined
+      root = undefined
+    },
+  }
+
+  return ctx
+}

package/src/runtime/run.ts

@@ -0,0 +1,100 @@
+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 { createComponentErrorEvent } from './error-event.ts'
+import type { ComponentErrorEvent } from './error-event.ts'
+import type { LoadModule, ResolveFrame } from './frame.ts'
+import { startNavigationListener } from './navigation.ts'
+import { TypedEventTarget } from './typed-event-target.ts'
+
+/**
+ * Options for starting the client runtime with {@link run}.
+ */
+export type RunInit = {
+  loadModule: LoadModule
+  resolveFrame?: ResolveFrame
+}
+
+/**
+ * Events emitted by the application runtime.
+ */
+export type AppRuntimeEventMap = {
+  error: ComponentErrorEvent
+}
+
+/**
+ * Client runtime returned by {@link run}.
+ */
+export type AppRuntime = TypedEventTarget<AppRuntimeEventMap> & {
+  ready(): Promise<void>
+  flush(): void
+  dispose(): void
+}
+
+let topFrame: Frame
+/**
+ * Returns the top-level frame handle for the running application.
+ *
+ * @returns The top-level frame handle.
+ */
+export function getTopFrame(): FrameHandle {
+  if (!topFrame) throw new Error('app runtime not initialized')
+  return topFrame.handle
+}
+
+const namedFrames = new Map<string, FrameHandle>()
+/**
+ * Returns a named frame handle, falling back to the top frame when not found.
+ *
+ * @param name Name of the frame to look up.
+ * @returns The matching frame handle or the top frame.
+ */
+export function getNamedFrame(name: string): FrameHandle {
+  return namedFrames.get(name) ?? getTopFrame()
+}
+
+/**
+ * Starts the client-side Remix component runtime for the current document.
+ *
+ * @param init Runtime hooks for loading modules and resolving frames.
+ * @returns The running application runtime.
+ */
+export function run(init: RunInit): AppRuntime {
+  let styleManager = createStyleManager()
+  let errorTarget = new TypedEventTarget<AppRuntimeEventMap>()
+  let scheduler = createScheduler(document, errorTarget, styleManager)
+
+  let resolveFrame: ResolveFrame = init.resolveFrame ?? (() => '<p>resolve frame unimplemented</p>')
+
+  topFrame = createFrame(document, {
+    src: document.location.href,
+    errorTarget,
+    loadModule: init.loadModule,
+    resolveFrame,
+    pendingClientEntries: new Map(),
+    scheduler,
+    styleManager,
+    data: {},
+    moduleCache: new Map(),
+    moduleLoads: new Map(),
+    frameInstances: new WeakMap(),
+    namedFrames,
+  })
+
+  let appController = new AbortController()
+  startNavigationListener(appController.signal)
+  let readyPromise = topFrame.ready().catch((error) => {
+    errorTarget.dispatchEvent(createComponentErrorEvent(error))
+    throw error
+  })
+
+  return Object.assign(errorTarget, {
+    ready: () => readyPromise,
+    flush: () => topFrame.flush(),
+    dispose: () => {
+      appController.abort()
+      topFrame.dispose()
+    },
+  })
+}

package/src/runtime/scheduler.ts

@@ -0,0 +1,262 @@
+import { createDocumentState } from './document-state.ts'
+import { createComponentErrorEvent } from './error-event.ts'
+import type { CommittedComponentNode, VNode } from './vnode.ts'
+import { isCommittedComponentNode } from './vnode.ts'
+import {
+  findNextSiblingDomAnchor,
+  renderComponent,
+  setActiveSchedulerUpdateParents,
+} from './reconcile.ts'
+import { defaultStyleManager } from './diff-props.ts'
+import type { StyleManager } from '../style/index.ts'
+
+type EmptyFn = () => void
+type SchedulerPhaseType = 'beforeUpdate' | 'commit'
+type SchedulerPhaseListener = EventListenerOrEventListenerObject | null
+
+/**
+ * Scheduler API used by the reconciler and frame runtime.
+ */
+export type Scheduler = ReturnType<typeof createScheduler>
+
+// Protect against infinite cascading updates (e.g. handle.update() during render)
+const MAX_CASCADING_UPDATES = 50
+
+export type SchedulerPhaseEvent = Event & {
+  parents: ParentNode[]
+}
+
+/**
+ * Creates the DOM update scheduler used by the component runtime.
+ *
+ * @param doc Document associated with the rendered tree.
+ * @param rootTarget Event target that receives runtime errors.
+ * @param styles Style manager used during reconciliation.
+ * @returns A scheduler instance.
+ */
+export function createScheduler(
+  doc: Document,
+  rootTarget: EventTarget,
+  styles: StyleManager = defaultStyleManager,
+) {
+  let documentState = createDocumentState(doc)
+  let scheduled = new Map<CommittedComponentNode, ParentNode>()
+  let workTasks: EmptyFn[] = []
+  let commitPhaseTasks: EmptyFn[] = []
+  let postCommitTasks: EmptyFn[] = []
+  let flushScheduled = false
+  let flushing = false
+  let cascadingUpdateCount = 0
+  let resetScheduled = false
+  let phaseEvents = new EventTarget()
+  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
+  }
+
+  function dispatchError(error: unknown) {
+    console.error(error)
+    rootTarget.dispatchEvent(createComponentErrorEvent(error))
+  }
+
+  function scheduleCounterReset() {
+    if (resetScheduled) return
+    resetScheduled = true
+    // Reset when control returns to the event loop while still allowing
+    // microtask-driven flushes in the same turn to count as cascading.
+    setTimeout(() => {
+      cascadingUpdateCount = 0
+      resetScheduled = false
+    }, 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
+    try {
+      while (true) {
+        flushScheduled = false
+
+        let batch = new Map(scheduled)
+        scheduled.clear()
+
+        let hasWork =
+          batch.size > 0 ||
+          workTasks.length > 0 ||
+          commitPhaseTasks.length > 0 ||
+          postCommitTasks.length > 0
+        if (!hasWork) return
+
+        cascadingUpdateCount++
+        scheduleCounterReset()
+
+        if (cascadingUpdateCount > MAX_CASCADING_UPDATES) {
+          let error = new Error('handle.update() infinite loop detected')
+          dispatchError(error)
+          return
+        }
+
+        documentState.capture()
+
+        let updateParents = batch.size > 0 ? Array.from(new Set(batch.values())) : []
+        setActiveSchedulerUpdateParents(updateParents)
+        dispatchPhaseEvent('beforeUpdate', updateParents)
+
+        if (batch.size > 0) {
+          let vnodes = Array.from(batch)
+          let noScheduledAncestor = new Set<VNode>()
+
+          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, vParent) || undefined
+            try {
+              let updateStyles = getFrameStyleManager(vnode)
+              renderComponent(
+                handle,
+                curr,
+                vnode,
+                domParent,
+                handle.frame,
+                scheduler,
+                updateStyles,
+                rootTarget,
+                vParent,
+                anchor,
+              )
+            } catch (error) {
+              dispatchError(error)
+            }
+          }
+        }
+
+        flushTaskQueue(workTasks)
+        setActiveSchedulerUpdateParents(undefined)
+
+        // Restore selection before commit-phase lifecycle work so mixins see
+        // the final DOM state but still run before commit listeners and user tasks.
+        documentState.restore()
+
+        flushTaskQueue(commitPhaseTasks)
+        dispatchPhaseEvent('commit', updateParents)
+        flushTaskQueue(postCommitTasks)
+      }
+    } finally {
+      setActiveSchedulerUpdateParents(undefined)
+      flushing = false
+    }
+  }
+
+  function dispatchPhaseEvent(type: SchedulerPhaseType, parents: ParentNode[]) {
+    let event = new Event(type) as SchedulerPhaseEvent
+    event.parents = parents
+    phaseEvents.dispatchEvent(event)
+  }
+
+  function flushTaskQueue(queue: EmptyFn[]) {
+    while (queue.length > 0) {
+      let task = queue.shift()
+      if (!task) continue
+      try {
+        task()
+      } catch (error) {
+        dispatchError(error)
+      }
+    }
+  }
+
+  function scheduleFlush() {
+    if (flushScheduled || flushing) return
+    flushScheduled = true
+    queueMicrotask(flush)
+  }
+
+  function ancestorIsScheduled(
+    vnode: VNode,
+    batch: Map<CommittedComponentNode, ParentNode>,
+    safe: Set<VNode>,
+  ): boolean {
+    let path: VNode[] = []
+    let current = vnode._parent
+
+    while (current) {
+      // Already verified this node has no scheduled ancestor above it
+      if (safe.has(current)) {
+        for (let node of path) safe.add(node)
+        return false
+      }
+
+      path.push(current)
+
+      if (isCommittedComponentNode(current) && batch.has(current)) {
+        return true
+      }
+
+      current = current._parent
+    }
+
+    // Reached root - mark entire path as safe for future lookups
+    for (let node of path) safe.add(node)
+    return false
+  }
+
+  scheduler = {
+    enqueue(vnode: CommittedComponentNode, domParent: ParentNode): void {
+      scheduled.set(vnode, domParent)
+      scheduleFlush()
+    },
+
+    enqueueWork(newTasks: EmptyFn[]): void {
+      workTasks.push(...newTasks)
+      scheduleFlush()
+    },
+
+    enqueueCommitPhase(newTasks: EmptyFn[]): void {
+      commitPhaseTasks.push(...newTasks)
+      scheduleFlush()
+    },
+
+    enqueueTasks(newTasks: EmptyFn[]): void {
+      postCommitTasks.push(...newTasks)
+      scheduleFlush()
+    },
+
+    addEventListener(type, listener, options) {
+      phaseEvents.addEventListener(type, listener, options)
+    },
+
+    removeEventListener(type, listener, options) {
+      phaseEvents.removeEventListener(type, listener, options)
+    },
+
+    dequeue() {
+      flush()
+    },
+  }
+
+  return scheduler
+}

package/src/runtime/svg-attributes.ts

@@ -0,0 +1,133 @@
+const XLINK_NS = 'http://www.w3.org/1999/xlink'
+const XML_NS = 'http://www.w3.org/XML/1998/namespace'
+
+const CANONICAL_CAMEL_SVG_ATTRS = new Set([
+  'accentHeight',
+  'attributeName',
+  'attributeType',
+  'baseFrequency',
+  'baseProfile',
+  'calcMode',
+  'viewBox',
+  'preserveAspectRatio',
+  'externalResourcesRequired',
+  'filterRes',
+  'gradientUnits',
+  'gradientTransform',
+  'glyphRef',
+  'kernelMatrix',
+  'kernelUnitLength',
+  'keyPoints',
+  'keySplines',
+  'keyTimes',
+  'lengthAdjust',
+  'limitingConeAngle',
+  'markerHeight',
+  'patternUnits',
+  'patternContentUnits',
+  'patternTransform',
+  'markerWidth',
+  'numOctaves',
+  'pathLength',
+  'pointsAtX',
+  'pointsAtY',
+  'pointsAtZ',
+  'preserveAlpha',
+  'clipPathUnits',
+  'maskUnits',
+  'maskContentUnits',
+  'filterUnits',
+  'primitiveUnits',
+  'refX',
+  'refY',
+  'requiredExtensions',
+  'requiredFeatures',
+  'specularConstant',
+  'specularExponent',
+  'spreadMethod',
+  'startOffset',
+  'stdDeviation',
+  'stitchTiles',
+  'surfaceScale',
+  'systemLanguage',
+  'tableValues',
+  'targetX',
+  'targetY',
+  'textLength',
+  'viewTarget',
+  'xChannelSelector',
+  'yChannelSelector',
+  'zoomAndPan',
+  'edgeMode',
+  'diffuseConstant',
+  'markerUnits',
+])
+
+const SVG_ATTR_ALIASES = new Map<string, string>()
+for (let attr of CANONICAL_CAMEL_SVG_ATTRS) {
+  SVG_ATTR_ALIASES.set(camelToKebab(attr), attr)
+}
+
+const NAMESPACED_SVG_ALIASES = new Map([
+  ['xlinkHref', { ns: XLINK_NS, attr: 'xlink:href' }],
+  ['xlink:href', { ns: XLINK_NS, attr: 'xlink:href' }],
+  ['xlink-href', { ns: XLINK_NS, attr: 'xlink:href' }],
+  ['xlinkActuate', { ns: XLINK_NS, attr: 'xlink:actuate' }],
+  ['xlink:actuate', { ns: XLINK_NS, attr: 'xlink:actuate' }],
+  ['xlink-actuate', { ns: XLINK_NS, attr: 'xlink:actuate' }],
+  ['xlinkArcrole', { ns: XLINK_NS, attr: 'xlink:arcrole' }],
+  ['xlink:arcrole', { ns: XLINK_NS, attr: 'xlink:arcrole' }],
+  ['xlink-arcrole', { ns: XLINK_NS, attr: 'xlink:arcrole' }],
+  ['xlinkRole', { ns: XLINK_NS, attr: 'xlink:role' }],
+  ['xlink:role', { ns: XLINK_NS, attr: 'xlink:role' }],
+  ['xlink-role', { ns: XLINK_NS, attr: 'xlink:role' }],
+  ['xlinkShow', { ns: XLINK_NS, attr: 'xlink:show' }],
+  ['xlink:show', { ns: XLINK_NS, attr: 'xlink:show' }],
+  ['xlink-show', { ns: XLINK_NS, attr: 'xlink:show' }],
+  ['xlinkTitle', { ns: XLINK_NS, attr: 'xlink:title' }],
+  ['xlink:title', { ns: XLINK_NS, attr: 'xlink:title' }],
+  ['xlink-title', { ns: XLINK_NS, attr: 'xlink:title' }],
+  ['xlinkType', { ns: XLINK_NS, attr: 'xlink:type' }],
+  ['xlink:type', { ns: XLINK_NS, attr: 'xlink:type' }],
+  ['xlink-type', { ns: XLINK_NS, attr: 'xlink:type' }],
+  ['xmlBase', { ns: XML_NS, attr: 'xml:base' }],
+  ['xml:base', { ns: XML_NS, attr: 'xml:base' }],
+  ['xml-base', { ns: XML_NS, attr: 'xml:base' }],
+  ['xmlLang', { ns: XML_NS, attr: 'xml:lang' }],
+  ['xml:lang', { ns: XML_NS, attr: 'xml:lang' }],
+  ['xml-lang', { ns: XML_NS, attr: 'xml:lang' }],
+  ['xmlSpace', { ns: XML_NS, attr: 'xml:space' }],
+  ['xml:space', { ns: XML_NS, attr: 'xml:space' }],
+  ['xml-space', { ns: XML_NS, attr: 'xml:space' }],
+  ['xmlnsXlink', { attr: 'xmlns:xlink' }],
+  ['xmlns:xlink', { attr: 'xmlns:xlink' }],
+  ['xmlns-xlink', { attr: 'xmlns:xlink' }],
+])
+
+export function normalizeSvgAttributeName(name: string): string {
+  let alias = SVG_ATTR_ALIASES.get(name)
+  if (alias) return alias
+
+  if (CANONICAL_CAMEL_SVG_ATTRS.has(name)) return name
+
+  return camelToKebab(name)
+}
+
+export function normalizeSvgAttribute(name: string): {
+  ns?: string
+  attr: string
+} {
+  let namespaced = NAMESPACED_SVG_ALIASES.get(name)
+  if (namespaced) {
+    return namespaced
+  }
+
+  return { attr: normalizeSvgAttributeName(name) }
+}
+
+function camelToKebab(input: string): string {
+  return input
+    .replace(/([a-z0-9])([A-Z])/g, '$1-$2')
+    .replace(/_/g, '-')
+    .toLowerCase()
+}

package/src/runtime/to-vnode.ts

@@ -0,0 +1,50 @@
+import { Fragment } from './component.ts'
+import { invariant } from './invariant.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)]
+    : []
+}
+
+function flattenRemixNodeArray(nodes: RemixNode[], out: RemixNode[] = []): RemixNode[] {
+  for (let child of nodes) {
+    if (Array.isArray(child)) {
+      flattenRemixNodeArray(child, out)
+    } else {
+      out.push(child)
+    }
+  }
+  return out
+}
+
+export function toVNode(node: RemixNode): VNode {
+  if (node === null || node === undefined || typeof node === 'boolean') {
+    return { type: TEXT_NODE, _text: '' }
+  }
+
+  if (typeof node === 'string' || typeof node === 'number' || typeof node === 'bigint') {
+    return { type: TEXT_NODE, _text: String(node) }
+  }
+
+  if (Array.isArray(node)) {
+    let flatChildren = flattenRemixNodeArray(node)
+    return { type: Fragment, _children: flatChildren.map(toVNode) }
+  }
+
+  if (node.type === Fragment) {
+    return { type: Fragment, key: node.key, _children: flatMapChildrenToVNodes(node) }
+  }
+
+  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 }
+  }
+
+  invariant(false, 'Unexpected RemixNode')
+}