@remix-run/ui 0.3.0 → 0.5.0

package/src/runtime/jsx.ts

@@ -97,8 +97,8 @@ export type Props<T extends keyof JSX.IntrinsicElements> = NormalizeMixProp<
  * @param key Optional reconciliation key.
  * @returns A Remix virtual element.
  */
-export function jsx(type: ElementType, props: ElementProps, key?: string): RemixElement
-export function jsx(type: ElementType, props: ElementProps, key?: string): RemixElement {
+export function jsx(type: ElementType, props: ElementProps, key?: any): RemixElement
+export function jsx(type: ElementType, props: ElementProps, key?: any): RemixElement {
   return createRemixElement(type, props, key)
 }
 
@@ -359,8 +359,6 @@ declare global {
     }
 
     export interface IntrinsicElements
-      extends IntrinsicSVGElements,
-        IntrinsicMathMLElements,
-        IntrinsicHTMLElements {}
+      extends IntrinsicSVGElements, IntrinsicMathMLElements, IntrinsicHTMLElements {}
   }
 }

package/src/runtime/key.ts

@@ -0,0 +1 @@
+export type Key = string | number | bigint

package/src/runtime/mixins/link-mixin.ts

@@ -36,6 +36,7 @@ export const link: MixinFactory<
           href,
           ...(options?.target == null ? {} : { 'rmx-target': options.target }),
           ...(options?.src == null ? {} : { 'rmx-src': options.src }),
+          ...(options?.history == null ? {} : { 'rmx-history': options.history }),
           ...(options?.resetScroll === false ? { 'rmx-reset-scroll': 'false' } : {}),
         })
       }

package/src/runtime/mixins/mixin.ts

@@ -1,5 +1,6 @@
 import type { Context, FrameHandle } from '../component.ts'
 import type { ElementProps, RemixElement } from '../jsx.ts'
+import type { Key } from '../key.ts'
 import type { Scheduler } from '../scheduler.ts'
 import type { SchedulerPhaseEvent } from '../scheduler.ts'
 import { jsx } from '../jsx.ts'
@@ -40,13 +41,13 @@ export type MixinElement<
 export type MixinInsertEvent<node extends EventTarget = Element> = Event & {
   node: node
   parent: ParentNode
-  key?: string
+  key?: Key
 }
 
 export type MixinReclaimedEvent<node extends EventTarget = Element> = Event & {
   node: node
   parent: ParentNode
-  key?: string
+  key?: Key
 }
 
 export type MixinUpdateEvent<node extends EventTarget = Element> = Event & {
@@ -71,14 +72,15 @@ type MixinHandleEventMap<node extends EventTarget = Element> = {
 /**
  * Runtime handle passed to mixin setup functions.
  *
- * Mixin render callbacks receive host props with `children` and `innerHTML` removed.
+ * The node type is covariant so a handle for a subtype host can be used by a mixin authored for
+ * its base type. Mixin render callbacks receive host props with `children` and `innerHTML` removed.
  * Returned mixin elements may patch host attributes and nested `mix`, but cannot replace
  * the host subtree.
  */
-export type MixinHandle<
-  node extends EventTarget = Element,
+export interface MixinHandle<
+  out node extends EventTarget = Element,
   props extends ElementProps = ElementProps,
-> = TypedEventTarget<MixinHandleEventMap<node>> & {
+> extends TypedEventTarget<MixinHandleEventMap<node>> {
   id: string
   context: MixinContext
   frame: FrameHandle
@@ -92,7 +94,7 @@ export function renderMixinElement<
   node extends EventTarget = Element,
   props extends ElementProps = ElementProps,
 >(element: MixinElement<node, props>, props?: MixinProps<node, props>): RemixElement {
-  let { key, ...rest } = (props ?? {}) as MixinProps<node, props> & { key?: any }
+  let { key, ...rest } = (props ?? {}) as MixinProps<node, props> & { key?: Key }
   return jsx(element, rest, key)
 }
 
@@ -121,7 +123,7 @@ export type MixinType<
  * Serializable descriptor stored in the `mix` prop.
  */
 export type MixinDescriptor<
-  node extends EventTarget = Element,
+  in node extends EventTarget = Element,
   args extends unknown[] = [],
   props extends ElementProps = ElementProps,
 > = {
@@ -172,6 +174,7 @@ type MixinReturn<node extends EventTarget = Element, props extends ElementProps
 
 type AnyMixinType = MixinRuntimeType<unknown[], Element, ElementProps>
 type AnyMixinDescriptor = MixinDescriptor<Element, unknown[], ElementProps>
+export type MixinRuntimeValue = AnyMixinDescriptor | ReadonlyArray<AnyMixinDescriptor>
 type AnyMixinRunner = (
   ...args: [...unknown[], currentProps: ElementProps]
 ) => MixinReturn<Element, ElementProps>
@@ -201,11 +204,11 @@ type MixinHandleFactoryOptions = {
   getBinding: () => MixinRuntimeBinding | undefined
 }
 
-export type MixinRuntimeBinding = {
+export type MixinRuntimeBinding<target = unknown> = {
   node: Element
   parent: ParentNode
-  key?: string
-  target: unknown
+  key?: Key
+  target: target
   frame: FrameHandle
   scheduler: Scheduler
   enqueueUpdate(done: (signal: AbortSignal) => void): void
@@ -381,9 +384,9 @@ export function teardownMixins(state?: MixinRuntimeState) {
   finalizeMixinTeardown(state)
 }
 
-export function bindMixinRuntime(
+export function bindMixinRuntime<target>(
   state: MixinRuntimeState | undefined,
-  binding?: MixinRuntimeBinding,
+  binding?: MixinRuntimeBinding<target>,
   options?: { dispatchReclaimed?: boolean },
 ) {
   if (!state) return
@@ -700,7 +703,7 @@ function dispatchMixinInsert(
   scope: symbol,
   node: Element,
   parent: ParentNode,
-  key?: string,
+  key?: Key,
 ) {
   let event = new Event('insert') as MixinInsertEvent<Element>
   event.node = node
@@ -714,7 +717,7 @@ function dispatchMixinReclaimed(
   scope: symbol,
   node: Element,
   parent: ParentNode,
-  key?: string,
+  key?: Key,
 ) {
   let event = new Event('reclaimed') as MixinReclaimedEvent<Element>
   event.node = node
@@ -738,7 +741,7 @@ function queueMixinInsert(
   scope: symbol,
   node: Element,
   parent: ParentNode,
-  key?: string,
+  key?: Key,
 ) {
   handle.queueCommitTask(() => {
     dispatchMixinInsert(handle, scope, node, parent, key)
@@ -750,7 +753,7 @@ function queueMixinReclaimed(
   scope: symbol,
   node: Element,
   parent: ParentNode,
-  key?: string,
+  key?: Key,
 ) {
   handle.queueCommitTask(() => {
     dispatchMixinReclaimed(handle, scope, node, parent, key)
@@ -896,7 +899,7 @@ function isRemixElement(value: unknown): value is RemixElement {
   return (value as { $rmx?: unknown }).$rmx === true
 }
 
-function isMixinDescriptor(value: unknown): value is AnyMixinDescriptor {
+export function isMixinDescriptor(value: unknown): value is AnyMixinDescriptor {
   if (!value || typeof value !== 'object' || isRemixElement(value)) {
     return false
   }

package/src/runtime/navigation.ts

@@ -1,4 +1,15 @@
 import { getTopFrame, getNamedFrame } from './run.ts'
+import { reloadFrameForNavigation } from './frame.ts'
+import { createFormNavigationResolver, type FormSubmission } from './form-navigation.ts'
+
+interface NavigationPrecommitControllerLike {
+  redirect(url: string, options: { history: 'replace' }): void
+}
+
+interface NavigationInterceptOptionsWithPrecommit extends NavigationInterceptOptions {
+  handler(): Promise<void>
+  precommitHandler(controller: NavigationPrecommitControllerLike): void
+}
 
 type NavigationState = {
   target: string | undefined
@@ -11,6 +22,25 @@ type SourceElementNavigateEvent = NavigateEvent & {
   sourceElement?: Element | null
 }
 
+type RuntimeNavigation = {
+  state: NavigationState
+  getSubmission?: () => Promise<FormSubmission>
+  replaceHistory?: boolean
+}
+
+interface FormSubmissionNavigationInfo {
+  type: typeof formSubmissionNavigationInfoType
+  state: NavigationState
+  getSubmission(): Promise<FormSubmission>
+}
+
+interface FrameRedirectNavigationInfo {
+  type: typeof frameRedirectNavigationInfoType
+}
+
+const formSubmissionNavigationInfoType = 'frame-form-submission'
+const frameRedirectNavigationInfoType = 'frame-redirect'
+
 /**
  * Options for client-side frame-aware navigation.
  */
@@ -42,10 +72,16 @@ export async function navigate(href: string, options?: NavigationOptions) {
  * Starts listening for Navigation API transitions and routes them through frame reloads.
  *
  * @param signal Abort signal used to remove the listener.
+ * @param canResolveFrames Whether the runtime has a resolver that can handle intercepted navigations.
  * @returns void
  */
-export function startNavigationListener(signal: AbortSignal) {
-  return startNavigationListenerImpl(signal, { getTopFrame, getNamedFrame })
+export function startNavigationListener(signal: AbortSignal, canResolveFrames = true) {
+  if (!canResolveFrames) return
+  return startNavigationListenerImpl(signal, {
+    getTopFrame,
+    getNamedFrame,
+    reloadFrame: reloadFrameForNavigation,
+  })
 }
 
 // Internal version used by unit tests so we can inject stub frames
@@ -54,9 +90,11 @@ export function startNavigationListenerImpl(
   options: {
     getTopFrame: typeof getTopFrame
     getNamedFrame: typeof getNamedFrame
+    reloadFrame: typeof reloadFrameForNavigation
   },
 ) {
   let navigation = window.navigation
+  let resolveFormNavigation = createFormNavigationResolver(signal)
 
   navigation.updateCurrentEntry({
     state: { target: undefined, src: window.location.href, resetScroll: true, $rmx: true },
@@ -71,28 +109,103 @@ export function startNavigationListenerImpl(
       // https://html.spec.whatwg.org/multipage/nav-history-apis.html#can-have-its-url-rewritten
       if (!event.canIntercept || isCrossOriginDestination(event)) return
 
-      let state = getRuntimeNavigationState(event)
-      if (!state) return
+      if (isFrameRedirectNavigationInfo(event.info)) {
+        event.intercept({ async handler() {} })
+        return
+      }
+
+      let replayedSubmission = isFormSubmissionNavigationInfo(event.info) ? event.info : undefined
+      let runtimeNavigation = replayedSubmission
+        ? {
+            state: replayedSubmission.state,
+            getSubmission: replayedSubmission.getSubmission,
+          }
+        : getRuntimeNavigation(event, resolveFormNavigation)
+      if (!runtimeNavigation) return
+      let { state } = runtimeNavigation
 
       let topFrame = options.getTopFrame()
       let namedFrame = state.target ? options.getNamedFrame(state.target) : undefined
       let frame = namedFrame ?? topFrame
 
-      event.intercept({
-        async handler() {
-          if (event.navigationType !== 'traverse') {
-            navigation.updateCurrentEntry({ state })
-          }
+      let handler = async () => {
+        let submission = await runtimeNavigation.getSubmission?.()
+        if (event.signal.aborted) return
+
+        if (event.navigationType !== 'traverse') {
+          navigation.updateCurrentEntry({ state })
+        }
+
+        topFrame.src = event.destination.url
+        if (frame !== topFrame) frame.src = state.src
+        let { redirectedTo } = await options.reloadFrame(frame, {
+          ...submission,
+          signal: event.signal,
+        })
+
+        if (redirectedTo && frame === topFrame) {
+          frame.src = redirectedTo
+          // Start the successor navigation without awaiting it: this handler must settle before
+          // the replacement navigation can finish.
+          navigation.navigate(redirectedTo, {
+            history: 'replace',
+            state: { ...state, src: redirectedTo },
+            info: {
+              type: frameRedirectNavigationInfoType,
+            } satisfies FrameRedirectNavigationInfo,
+          })
+        }
+
+        let isNewEntry = event.navigationType === 'push' || event.navigationType === 'replace'
+        if (state.resetScroll && isNewEntry) {
+          window.scrollTo(0, 0)
+        }
+      }
+
+      if (runtimeNavigation.getSubmission) {
+        // <form method="post"> navigations
+        if (runtimeNavigation.replaceHistory && replayedSubmission == null) {
+          let supportsPrecommit =
+            typeof Reflect.get(window, 'NavigationPrecommitController') === 'function'
 
-          frame.src = frame === topFrame ? event.destination.url : state.src
-          await frame.reload()
+          // Modern browsers allow you to update the in-flight navigation entry before it's committed
+          if (supportsPrecommit) {
+            let interceptOptions: NavigationInterceptOptionsWithPrecommit = {
+              handler,
+              precommitHandler(controller) {
+                controller.redirect(event.destination.url, { history: 'replace' })
+              },
+            }
+            event.intercept(interceptOptions)
+            return
+          }
 
-          let isNewEntry = event.navigationType === 'push' || event.navigationType === 'replace'
-          if (state.resetScroll && isNewEntry) {
-            window.scrollTo(0, 0)
+          // Safari doesn't support precommit as of Aug 2026, so we do a full replacement navigation
+          if (event.cancelable) {
+            event.preventDefault()
+            window.navigation.navigate(event.destination.url, {
+              history: 'replace',
+              state,
+              info: {
+                type: formSubmissionNavigationInfoType,
+                state,
+                getSubmission: runtimeNavigation.getSubmission,
+              } satisfies FormSubmissionNavigationInfo,
+            })
+            return
           }
-        },
-      })
+        }
+
+        event.intercept({ handler })
+      } else {
+        // <a>/<form method="get"> navigations
+        if (runtimeNavigation.replaceHistory && event.cancelable) {
+          event.preventDefault()
+          navigation.navigate(event.destination.url, { history: 'replace', state })
+        } else {
+          event.intercept({ handler })
+        }
+      }
     },
     { signal },
   )
@@ -102,21 +215,47 @@ function isRuntimeNavigation(info: unknown): info is NavigationState {
   return typeof info === 'object' && info != null && '$rmx' in info
 }
 
+function isFormSubmissionNavigationInfo(value: unknown): value is FormSubmissionNavigationInfo {
+  return (
+    typeof value === 'object' &&
+    value != null &&
+    'type' in value &&
+    value.type === formSubmissionNavigationInfoType &&
+    'state' in value &&
+    isRuntimeNavigation(value.state) &&
+    'getSubmission' in value &&
+    typeof value.getSubmission === 'function'
+  )
+}
+
+function isFrameRedirectNavigationInfo(value: unknown): value is FrameRedirectNavigationInfo {
+  return (
+    typeof value === 'object' &&
+    value != null &&
+    'type' in value &&
+    value.type === frameRedirectNavigationInfoType
+  )
+}
+
 function isCrossOriginDestination(event: NavigateEvent): boolean {
   let destination = new URL(event.destination.url)
   return destination.origin !== window.location.origin
 }
 
-function getRuntimeNavigationState(event: NavigateEvent): NavigationState | undefined {
+function getRuntimeNavigation(
+  event: NavigateEvent,
+  resolveFormNavigation: ReturnType<typeof createFormNavigationResolver>,
+): RuntimeNavigation | undefined {
   if (event.navigationType === 'traverse') {
-    return getTraverseNavigationState(event)
+    let state = getTraverseNavigationState(event)
+    return state ? { state } : undefined
   }
 
-  let sourceState = getSourceElementNavigationState(event)
-  if (sourceState) return sourceState
+  let sourceNavigation = getSourceElementNavigation(event, resolveFormNavigation)
+  if (sourceNavigation) return sourceNavigation
 
   let destinationState = event.destination.getState()
-  if (isRuntimeNavigation(destinationState)) return destinationState
+  if (isRuntimeNavigation(destinationState)) return { state: destinationState }
 }
 
 function getTraverseNavigationState(event: NavigateEvent): NavigationState | undefined {
@@ -139,19 +278,54 @@ function getTraverseNavigationState(event: NavigateEvent): NavigationState | und
   return undefined
 }
 
-function getSourceElementNavigationState(event: NavigateEvent): NavigationState | undefined {
+function getSourceElementNavigation(
+  event: NavigateEvent,
+  resolveFormNavigation: ReturnType<typeof createFormNavigationResolver>,
+): RuntimeNavigation | undefined {
   let sourceEvent = event as SourceElementNavigateEvent
   let sourceElement = sourceEvent.sourceElement
   if (!(sourceElement instanceof Element)) return
+
   let linkElement = sourceElement.closest('a, area')
-  if (!(linkElement instanceof Element)) return
-  if (linkElement.hasAttribute('rmx-document')) return
-  if (linkElement.hasAttribute('download')) return
+  if (linkElement instanceof Element) {
+    if (linkElement.hasAttribute('rmx-document')) return
+    if (linkElement.hasAttribute('download')) return
+
+    return {
+      state: {
+        target: linkElement.getAttribute('rmx-target') ?? undefined,
+        src: linkElement.getAttribute('rmx-src') ?? event.destination.url,
+        resetScroll: linkElement.getAttribute('rmx-reset-scroll') !== 'false',
+        $rmx: true,
+      },
+      replaceHistory: getReplaceHistory(linkElement.getAttribute('rmx-history'), false),
+    }
+  }
+
+  let formNavigation = resolveFormNavigation(event)
+  if (!formNavigation || formNavigation.hasAttribute('rmx-document')) return
+
+  let replaceHistoryByDefault =
+    formNavigation.getSubmission !== undefined &&
+    event.destination.url === window.navigation.currentEntry?.url
 
   return {
-    target: linkElement.getAttribute('rmx-target') ?? undefined,
-    src: linkElement.getAttribute('rmx-src') ?? event.destination.url,
-    resetScroll: linkElement.getAttribute('rmx-reset-scroll') !== 'false',
-    $rmx: true,
-  } satisfies NavigationState
+    state: {
+      target: formNavigation.getAttribute('rmx-target') ?? undefined,
+      src: formNavigation.getAttribute('rmx-src') ?? event.destination.url,
+      resetScroll: formNavigation.getAttribute('rmx-reset-scroll') !== 'false',
+      $rmx: true,
+    },
+    replaceHistory: getReplaceHistory(
+      formNavigation.getAttribute('rmx-history'),
+      replaceHistoryByDefault,
+    ),
+    getSubmission: formNavigation.getSubmission,
+  }
+}
+
+function getReplaceHistory(value: string | null, defaultValue: boolean): boolean {
+  if (value === 'replace') return true
+  if (value === 'push') return false
+  return defaultValue
 }